refactor：拆分 API 路由与请求校验，统一 final 类和代码风格

app/Support/PaginationTrait.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Support;
+
+use Illuminate\Http\Request;
+
+/**
+ * 分页请求参数解析 trait。
+ *
+ * 统一处理 `page`、`per_page`/`size` 参数的合法化。
+ */
+trait PaginationTrait
+{
+    /**
+     * 解析并限制每页条数。
+     *
+     * @param  Request  $request  请求对象
+     * @param  string  $key  参数名（默认 per_page）
+     * @param  int  $default  默认值
+     * @param  int  $max  最大值上限
+     */
+    protected function perPage(Request $request, string $key = 'per_page', int $default = 20, int $max = 50): int
+    {
+        $value = (int) $request->query($key, $request->query('size', $default));
+
+        return max(1, min($max, $value));
+    }
+
+    /**
+     * 解析当前页码（强制至少为 1）。
+     */
+    protected function page(Request $request, string $key = 'page', int $default = 1): int
+    {
+        return max(1, (int) $request->query($key, $default));
+    }
+
+    /**
+     * 解析分页元数据数组。
+     *
+     * @return array{page: int, per_page: int}
+     */
+    protected function paginationMeta(Request $request, int $defaultPerPage = 20, int $maxPerPage = 50): array
+    {
+        return [
+            'page' => $this->page($request),
+            'per_page' => $this->perPage($request, 'per_page', $defaultPerPage, $maxPerPage),
+        ];
+    }
+}