签入版本

EasyGoAdmin_GoFrame_NaiveVue/zh/api-spec/pagination.md

@@ -0,0 +1,90 @@
+# 8.3 分页查询规范
+
+:::tip 概述
+分页契约三件套：PageReq 入参（pageNo/pageSize）+ PageData 出参（records/total/size/current/pages）+ 筛选对齐三件套（querySchemas ↔ Req 字段 ↔ spec 声明）。导出与列表同套筛选。
+:::
+
+## 分页入参（common.PageReq）
+
+```text
+pageNo    页码，默认 1
+pageSize  每页条数，默认 10，上限 500（GetPageSize 截断——防恶意大 pageSize）
+
+请求示例：GET /api/user/page?pageNo=1&pageSize=10&keyword=张
+```
+
+## 分页出参（PageData[T]）
+
+```json
+{
+  "records": [], "total": 0, "size": 10, "current": 1, "pages": 0
+}
+```
+
+records 为空输出 `[]` 而非 null（前端无需判空兼容）。
+
+## 筛选对齐三件套（2026-10-14 定稿）
+
+```text
+前端 querySchemas.ts 每个筛选输入
+  ↔ XxxPageReq 同名驼峰字段
+    ↔ logic spec 声明
+
+字符串 Input        → LikeFields（逐列模糊，值取 req 同名字段，空跳过）
+Select/InputNumber  → EqFields（等值，零值跳过）
+关键词框（可选）     → KeywordFields（req.keyword 多列 OR）
+                      ——能力保留在基座，模块默认不声明，需要时再用
+```
+
+### 对齐示例（example 模块）
+
+| 前端 querySchemas | 后端 PageReq | spec 声明 |
+|-------------------|-------------|-----------|
+| `field: 'name'`（Input） | `Name string \`json:"name"\`` | LikeFields: []string{"name"} |
+| `field: 'type'`（Select） | `Type int \`json:"type"\`` | EqFields: []string{"type", "status"} |
+| `field: 'status'`（Select） | `Status int \`json:"status"\`` | 同上 |
+
+### 筛选链执行顺序（固定）
+
+```text
+applyFilters：LikeFields → EqFields → KeywordFields → Filter → DataScope
+前置：dao.Ctx 已注入 del_flag=0 + 租户 IN(0,自身)
+```
+
+复杂条件写 Filter 钩子，**不要重复 Like/Eq 已覆盖的条件**。
+
+## 导出=所见
+
+```text
+导出接口统一走 xxxSpec.applyFilters 与列表同套筛选：
+  Export 请求结构含与 PageReq 相同的筛选字段（不带 pageNo/pageSize）
+  → applyFilters 同链过滤 → 全量（ChunkQuery 分批）→ Excel
+保证：列表看到什么，导出就是什么（含数据权限过滤）
+```
+
+## 排序规范
+
+```text
+spec.OrderBy          默认排序（如 "id DESC"、"sort, id"）
+spec.ListOrderBy      列表专用排序
+spec.OrderableFields  前端排序白名单（orderField/orderType 仅白名单内生效）
+```
+
+前端排序参数不可直通 SQL——白名单外的排序字段忽略（防注入）。
+
+## 前端分页组件约定
+
+```text
+分页组件（components/pagination）：
+  change 事件携带 pageNo/pageSize → 重新请求 /page
+  pageSize 切换回到第 1 页
+  上限保护：≤500（与后端 GetPageSize 截断一致）
+```
+
+## 开发规约
+
++ 分页接口 PageReq 内嵌 common.PageReq（复用默认值与截断逻辑）
++ 筛选字段必须三件套对齐——querySchemas 加了输入，Req 与 spec 都要跟上
++ 字符串筛选走 LikeFields 声明（列名显式声明，值取 req 同名驼峰字段）
++ 零值跳过是 EqFields 语义（status=0 是有效筛选值时需在 Filter 处理或调整字段设计）
++ 大表分页深翻页注意：pageNo×pageSize 过大时的 offset 成本（管理后台低频场景可接受）