@agile-team/wl-skills-kit 2.3.4 → 2.3.6

package/files/.github/skills/core/api-contract/SKILL.md

@@ -1,344 +1,344 @@
----
-name: api-contract
-description: "Use when: designing API contracts between frontend and backend based on prototype page inventory, defining request/response field structures, establishing naming conventions, and generating an api.md file per page for team alignment before coding. Triggers on: api contract, interface design, 接口约定, 前后端对齐, 字段定义, 接口设计, api.md."
----
-
-# Skill: 接口约定（api-contract）
-
-基于《页面清单》为每个页面生成 `api.md` 文件，放在**页面目录下**（和 index.vue 同级）。
-
-**双重作用：**
-
-1. **前端** — data.ts 中 `API_CONFIG` 的 URL 和字段名直接基于 api.md
-2. **后端** — 拿到 api.md 直接出接口（Controller + Service + Entity），字段名一致，联调零成本
-
----
-
-## 全局规范
-
-### URL 命名
-
-```
-/[服务缩写]/[资源名CamelCase]/[操作]
-```
-
-| 服务缩写 | 含义     | 示例                                 |
-| -------- | -------- | ------------------------------------ |
-| pm       | 生产管理 | `/pm/omptMillPlanOrder/list`         |
-| mmwr     | 精整作业 | `/mmwr/mmwrTechFinish/queryTechList` |
-| mmsm     | 炼钢管理 | `/mmsm/mmsmRsltLadleUse/list`        |
-| sale     | 销售管理 | `/sale/saleOrder/list`               |
-| hrms     | 人力资源 | `/hrms/hrmsEmployee/list`            |
-| base     | 基础数据 | `/base/cmUserGroup/list`             |
-
-### 标准操作集
-
-| 操作     | 方法 | URL 后缀          | 说明                                                  |
-| -------- | ---- | ----------------- | ----------------------------------------------------- |
-| 分页列表 | POST | `/list`           | 基类 `super({ url: { list } })` 自动调用              |
-| 单条查询 | GET  | `/getById?id=xxx` | `getAction(API_CONFIG.getById, { id })`               |
-| 新增     | POST | `/save`           | `postAction(API_CONFIG.save, formData)`               |
-| 编辑     | POST | `/update`         | `postAction(API_CONFIG.update, formData)`             |
-| 删除     | POST | `/remove`         | 基类 `super({ url: { remove } })` + `this.remove(id)` |
-| 导出     | GET  | `/export`         | `getAction(API_CONFIG.export, params)`                |
-
-### 业务操作命名规范
-
-非标准 CRUD 操作按以下约定命名，URL 后缀使用**动词原形**（camelCase）：
-
-| 操作      | 方法 | URL 后缀        | 请求说明                              |
-| --------- | ---- | --------------- | ------------------------------------- |
-| 提交审批  | POST | `/submit`       | `{ id }` 或 `{ ids: [] }`             |
-| 审批通过  | POST | `/approve`      | `{ id, opinion? }`                    |
-| 审批驳回  | POST | `/reject`       | `{ id, opinion }`                     |
-| 撤回      | POST | `/withdraw`     | `{ id }` 撤回已提交的单据             |
-| 启用/禁用 | POST | `/changeStatus` | `{ id, status }`                      |
-| 转化      | POST | `/convert`      | `{ id }` 临时→正式（如临时客户→正式） |
-| 下发      | POST | `/release`      | `{ id }` 计划/工单下发执行            |
-| 关闭      | POST | `/close`        | `{ id }` 关闭订单/计划                |
-| 作废      | POST | `/cancel`       | `{ id }` 作废单据                     |
-| 批量操作  | POST | `/batchXxx`     | 如 `/batchSubmit`、`/batchRemove`     |
-| 子表查询  | POST | `/queryXxxList` | 如 `/queryDetailList`，主从表场景     |
-
-> **命名原则**：`/[服务缩写]/[资源名]/[动作]`，动作用英文动词原形，不用中文拼音，不加 `do` / `handle` 前缀。
-
-### 统一响应结构（基于真实后端契约）
-
-> ⚠️ **重要**：本项目后端响应外壳为 `{ code, message, data }`（**非 `result`**），成功码为 **`2000`**（**非 200**）。
-
-#### 1. 分页查询响应
-
-```json
-{
-  "code": 2000,
-  "message": "操作成功",
-  "data": {
-    "records": [
-      {
-        /* Entity 字段 */
-      }
-    ],
-    "total": 100,
-    "current": 1,
-    "size": 20,
-    "pages": 5,
-    "countId": null,
-    "maxLimit": null,
-    "orders": [],
-    "searchCount": true
-  }
-}
-```
-
-| data 字段     | 类型    | 说明                                     |
-| ------------- | ------- | ---------------------------------------- |
-| `records`     | array   | 当前页数据列表                           |
-| `total`       | number  | 总记录数                                 |
-| `current`     | number  | 当前页码                                 |
-| `size`        | number  | 每页条数                                 |
-| `pages`       | number  | 总页数                                   |
-| `countId`     | any     | MyBatis-Plus 分页计数 ID（前端忽略）     |
-| `maxLimit`    | any     | 最大单页限制（前端忽略）                 |
-| `orders`      | array   | 排序条件回传（前端忽略，除非需回显排序） |
-| `searchCount` | boolean | 是否执行总数查询（前端忽略）             |
-
-> 前端 `BaseTable` / `AbstractPageQueryHook` 已自动适配：取 `data.records` 渲染、`data.total` 设分页、其他字段透传或忽略。无需在 data.ts 中处理。
-
-#### 2. 单条 / 非分页查询响应
-
-```json
-{
-  "code": 2000,
-  "message": "操作成功",
-  "data": {
-    /* Entity 单对象 */
-  }
-}
-```
-
-或返回数组（无需分页时）：
-
-```json
-{
-  "code": 2000,
-  "message": "操作成功",
-  "data": [
-    {
-      /* Entity */
-    }
-  ]
-}
-```
-
-#### 3. 字典查询响应
-
-```json
-{
-  "code": 2000,
-  "message": "操作成功",
-  "data": [
-    { "value": "01", "label": "已审批", "extra": null },
-    { "value": "02", "label": "驳回", "extra": null }
-  ]
-}
-```
-
-#### 4. 增删改响应
-
-```json
-{ "code": 2000, "message": "操作成功", "data": true }
-```
-
-或返回主键：
-
-```json
-{ "code": 2000, "message": "操作成功", "data": "1234567890123456789" }
-```
-
-#### 5. 失败响应
-
-```json
-{ "code": 4001, "message": "参数缺失：customerName 不能为空", "data": null }
-```
-
-| code 范围     | 含义                              |
-| ------------- | --------------------------------- |
-| `2000`        | 成功                              |
-| `4xxx`        | 客户端错误（参数/权限/校验）      |
-| `5xxx`        | 服务端错误                        |
-| `401` / `403` | 网关层未登录 / 无权限（统一拦截） |
-
-> 业务代码**不需要**关心 `code` 判断，`request.ts` 拦截器统一处理：非 2000 自动 `Promise.reject` + Toast 提示。业务代码 `.then()` 拿到的就是 `data` 字段内容。
-
-### 字段命名
-
-| 端   | 规范         | 说明                           |
-| ---- | ------------ | ------------------------------ |
-| 前端 | `camelCase`  | 所有请求/响应字段名            |
-| 后端 | `snake_case` | 数据库字段，Jackson 自动转驼峰 |
-
----
-
-## 执行步骤
-
-### Step 1：接收输入
-
-从 Phase 1 《页面清单》获取：
-
-- 业务服务缩写（如 `pm`）
-- 资源名（camelCase，如 `omptMillPlanOrder`）
-- 各页面的查询字段、表格列、表单字段
-
-### Step 2：为每个页面生成 api.md
-
-文件放在**页面目录下**（和 index.vue 同级），字段名与 data.ts 完全一致。
-
-### Step 3：同步生成 API_CONFIG
-
-api.md 中的接口 URL 直接对应 data.ts 中的 `API_CONFIG`：
-
-```typescript
-export const API_CONFIG = {
-  list: "/pm/omptMillPlanOrder/list",
-  remove: "/pm/omptMillPlanOrder/remove",
-  getById: "/pm/omptMillPlanOrder/getById",
-  save: "/pm/omptMillPlanOrder/save",
-  update: "/pm/omptMillPlanOrder/update",
-  export: "/pm/omptMillPlanOrder/export",
-  // 按需增加业务操作
-  release: "/pm/omptMillPlanOrder/release",
-} as const;
-```
-
----
-
-## api.md 模板
-
-每个页面目录下生成：
-
-````markdown
-# 接口约定 - [页面中文名]
-
-> 页面路径：`src/views/[域]/[模块]/[子模块]/[目录]/`
-> 服务缩写：[pm / mmwr / sale / ...]
-> 资源名：[camelCase 实体名]
-> 状态：🟡 待后端确认
-
----
-
-## API_CONFIG
-
-```typescript
-export const API_CONFIG = {
-  list: "/[服务缩写]/[资源名]/list",
-  remove: "/[服务缩写]/[资源名]/remove",
-  getById: "/[服务缩写]/[资源名]/getById",
-  save: "/[服务缩写]/[资源名]/save",
-  update: "/[服务缩写]/[资源名]/update",
-  export: "/[服务缩写]/[资源名]/export",
-} as const;
-```
-
----
-
-## 实体定义
-
-> 字段名与 data.ts 中 queryDef/columnsDef 使用的字段名**完全一致**
-
-| 字段名        | 类型   | 说明     | 必填 | 字典(logicValue) | 备注                 |
-| ------------- | ------ | -------- | ---- | ---------------- | -------------------- |
-| id            | string | 主键     | 自动 | -                | 后端生成             |
-| [field1]      | string | [说明]   | ✅   | -                |                      |
-| [statusField] | string | [状态]   | ✅   | [dictCode]       | 前端 logicValue 对应 |
-| [dateField]   | string | [日期]   | ❌   | -                | YYYY-MM-DD           |
-| createTime    | string | 创建时间 | 自动 | -                | YYYY-MM-DD HH:mm:ss  |
-| updateTime    | string | 更新时间 | 自动 | -                |                      |
-| createBy      | string | 创建人   | 自动 | -                |                      |
-
----
-
-## 接口清单
-
-### 1. 分页查询
-
-```
-POST /[服务缩写]/[资源名]/list
-```
-
-| 字段          | 类型   | 必填 | 说明                                |
-| ------------- | ------ | ---- | ----------------------------------- |
-| current       | number | ✅   | 页码（基类自动传）                  |
-| size          | number | ✅   | 每页条数（基类自动传）              |
-| [queryField1] | string | ❌   | [说明]                              |
-| [queryField2] | string | ❌   | [说明]，对应 logicValue: [dictCode] |
-| [startDate]   | string | ❌   | 开始日期 YYYY-MM-DD                 |
-| [endDate]     | string | ❌   | 结束日期 YYYY-MM-DD                 |
-
-**响应 data.records：** 同实体定义；外壳 `{ code: 2000, message, data: { records, total, current, size, pages, countId, maxLimit, orders, searchCount } }`
-
-### 2. 详情查询
-
-```
-GET /[服务缩写]/[资源名]/getById?id=xxx
-```
-
-**响应 data：** 单个 Entity；外壳 `{ code: 2000, message, data: {...} }`
-
-### 3. 新增
-
-```
-POST /[服务缩写]/[资源名]/save
-```
-
-**请求：** 实体定义中必填字段（不含 id、createTime 等自动字段）
-
-### 4. 编辑
-
-```
-POST /[服务缩写]/[资源名]/update
-```
-
-**请求：** 同新增 + `id`（必填）
-
-### 5. 删除
-
-```
-POST /[服务缩写]/[资源名]/remove
-```
-
-**请求：** `{ "ids": ["xxx"] }` 或 `{ "id": "xxx" }`
-
-### 6. 导出（如需要）
-
-```
-GET /[服务缩写]/[资源名]/export?[查询参数]
-```
-
----
-
-## 数据字典
-
-| dictCode(logicValue) | 用途   | 出现位置                     |
-| -------------------- | ------ | ---------------------------- |
-| [dictCode]           | [说明] | queryDef / columnsDef / form |
-
----
-
-## 联调注意
-
-1. **响应外壳**：`{ code, message, data }`，成功 `code: 2000`（非 200，非 result）
-2. 前端字段全部 camelCase，后端 JSON 序列化输出 camelCase
-3. 时间字段统一 `YYYY-MM-DD HH:mm:ss`
-4. 大数字 ID 后端转字符串（雪花 ID 超过 JS Number 精度）
-5. 分页参数前端传 `current` / `size`（基类自动处理），后端响应 `data.records` / `data.total`
-6. 枚举字段前端传 value，后端可返回 `[field]Label` 辅助展示，或前端自行通过 `logicValue` 字典翻译
-7. 业务代码 `.then(res => res)` 拿到的就是 `data` 字段（拦截器已剥外壳）
-````
-
----
-
-## 状态标记
-
-- 🟡 待后端确认 — 刚生成
-- 🟢 已确认 — 双方对齐，可编码
-- 🔴 有变更 — 需双方同步
+---
+name: api-contract
+description: "Use when: designing API contracts between frontend and backend based on prototype page inventory, defining request/response field structures, establishing naming conventions, and generating an api.md file per page for team alignment before coding. Triggers on: api contract, interface design, 接口约定, 前后端对齐, 字段定义, 接口设计, api.md."
+---
+
+# Skill: 接口约定（api-contract）
+
+基于《页面清单》为每个页面生成 `api.md` 文件，放在**页面目录下**（和 index.vue 同级）。
+
+**双重作用：**
+
+1. **前端** — data.ts 中 `API_CONFIG` 的 URL 和字段名直接基于 api.md
+2. **后端** — 拿到 api.md 直接出接口（Controller + Service + Entity），字段名一致，联调零成本
+
+---
+
+## 全局规范
+
+### URL 命名
+
+```
+/[服务缩写]/[资源名CamelCase]/[操作]
+```
+
+| 服务缩写 | 含义     | 示例                                 |
+| -------- | -------- | ------------------------------------ |
+| pm       | 生产管理 | `/pm/omptMillPlanOrder/list`         |
+| mmwr     | 精整作业 | `/mmwr/mmwrTechFinish/queryTechList` |
+| mmsm     | 炼钢管理 | `/mmsm/mmsmRsltLadleUse/list`        |
+| sale     | 销售管理 | `/sale/saleOrder/list`               |
+| hrms     | 人力资源 | `/hrms/hrmsEmployee/list`            |
+| base     | 基础数据 | `/base/cmUserGroup/list`             |
+
+### 标准操作集
+
+| 操作     | 方法 | URL 后缀          | 说明                                                  |
+| -------- | ---- | ----------------- | ----------------------------------------------------- |
+| 分页列表 | POST | `/list`           | 基类 `super({ url: { list } })` 自动调用              |
+| 单条查询 | GET  | `/getById?id=xxx` | `getAction(API_CONFIG.getById, { id })`               |
+| 新增     | POST | `/save`           | `postAction(API_CONFIG.save, formData)`               |
+| 编辑     | POST | `/update`         | `postAction(API_CONFIG.update, formData)`             |
+| 删除     | POST | `/remove`         | 基类 `super({ url: { remove } })` + `this.remove(id)` |
+| 导出     | GET  | `/export`         | `getAction(API_CONFIG.export, params)`                |
+
+### 业务操作命名规范
+
+非标准 CRUD 操作按以下约定命名，URL 后缀使用**动词原形**（camelCase）：
+
+| 操作      | 方法 | URL 后缀        | 请求说明                              |
+| --------- | ---- | --------------- | ------------------------------------- |
+| 提交审批  | POST | `/submit`       | `{ id }` 或 `{ ids: [] }`             |
+| 审批通过  | POST | `/approve`      | `{ id, opinion? }`                    |
+| 审批驳回  | POST | `/reject`       | `{ id, opinion }`                     |
+| 撤回      | POST | `/withdraw`     | `{ id }` 撤回已提交的单据             |
+| 启用/禁用 | POST | `/changeStatus` | `{ id, status }`                      |
+| 转化      | POST | `/convert`      | `{ id }` 临时→正式（如临时客户→正式） |
+| 下发      | POST | `/release`      | `{ id }` 计划/工单下发执行            |
+| 关闭      | POST | `/close`        | `{ id }` 关闭订单/计划                |
+| 作废      | POST | `/cancel`       | `{ id }` 作废单据                     |
+| 批量操作  | POST | `/batchXxx`     | 如 `/batchSubmit`、`/batchRemove`     |
+| 子表查询  | POST | `/queryXxxList` | 如 `/queryDetailList`，主从表场景     |
+
+> **命名原则**：`/[服务缩写]/[资源名]/[动作]`，动作用英文动词原形，不用中文拼音，不加 `do` / `handle` 前缀。
+
+### 统一响应结构（基于真实后端契约）
+
+> ⚠️ **重要**：本项目后端响应外壳为 `{ code, message, data }`（**非 `result`**），成功码为 **`2000`**（**非 200**）。
+
+#### 1. 分页查询响应
+
+```json
+{
+  "code": 2000,
+  "message": "操作成功",
+  "data": {
+    "records": [
+      {
+        /* Entity 字段 */
+      }
+    ],
+    "total": 100,
+    "current": 1,
+    "size": 20,
+    "pages": 5,
+    "countId": null,
+    "maxLimit": null,
+    "orders": [],
+    "searchCount": true
+  }
+}
+```
+
+| data 字段     | 类型    | 说明                                     |
+| ------------- | ------- | ---------------------------------------- |
+| `records`     | array   | 当前页数据列表                           |
+| `total`       | number  | 总记录数                                 |
+| `current`     | number  | 当前页码                                 |
+| `size`        | number  | 每页条数                                 |
+| `pages`       | number  | 总页数                                   |
+| `countId`     | any     | MyBatis-Plus 分页计数 ID（前端忽略）     |
+| `maxLimit`    | any     | 最大单页限制（前端忽略）                 |
+| `orders`      | array   | 排序条件回传（前端忽略，除非需回显排序） |
+| `searchCount` | boolean | 是否执行总数查询（前端忽略）             |
+
+> 前端 `BaseTable` / `AbstractPageQueryHook` 已自动适配：取 `data.records` 渲染、`data.total` 设分页、其他字段透传或忽略。无需在 data.ts 中处理。
+
+#### 2. 单条 / 非分页查询响应
+
+```json
+{
+  "code": 2000,
+  "message": "操作成功",
+  "data": {
+    /* Entity 单对象 */
+  }
+}
+```
+
+或返回数组（无需分页时）：
+
+```json
+{
+  "code": 2000,
+  "message": "操作成功",
+  "data": [
+    {
+      /* Entity */
+    }
+  ]
+}
+```
+
+#### 3. 字典查询响应
+
+```json
+{
+  "code": 2000,
+  "message": "操作成功",
+  "data": [
+    { "value": "01", "label": "已审批", "extra": null },
+    { "value": "02", "label": "驳回", "extra": null }
+  ]
+}
+```
+
+#### 4. 增删改响应
+
+```json
+{ "code": 2000, "message": "操作成功", "data": true }
+```
+
+或返回主键：
+
+```json
+{ "code": 2000, "message": "操作成功", "data": "1234567890123456789" }
+```
+
+#### 5. 失败响应
+
+```json
+{ "code": 4001, "message": "参数缺失：customerName 不能为空", "data": null }
+```
+
+| code 范围     | 含义                              |
+| ------------- | --------------------------------- |
+| `2000`        | 成功                              |
+| `4xxx`        | 客户端错误（参数/权限/校验）      |
+| `5xxx`        | 服务端错误                        |
+| `401` / `403` | 网关层未登录 / 无权限（统一拦截） |
+
+> 业务代码**不需要**关心 `code` 判断，`request.ts` 拦截器统一处理：非 2000 自动 `Promise.reject` + Toast 提示。业务代码 `.then()` 拿到的就是 `data` 字段内容。
+
+### 字段命名
+
+| 端   | 规范         | 说明                           |
+| ---- | ------------ | ------------------------------ |
+| 前端 | `camelCase`  | 所有请求/响应字段名            |
+| 后端 | `snake_case` | 数据库字段，Jackson 自动转驼峰 |
+
+---
+
+## 执行步骤
+
+### Step 1：接收输入
+
+从 Phase 1 《页面清单》获取：
+
+- 业务服务缩写（如 `pm`）
+- 资源名（camelCase，如 `omptMillPlanOrder`）
+- 各页面的查询字段、表格列、表单字段
+
+### Step 2：为每个页面生成 api.md
+
+文件放在**页面目录下**（和 index.vue 同级），字段名与 data.ts 完全一致。
+
+### Step 3：同步生成 API_CONFIG
+
+api.md 中的接口 URL 直接对应 data.ts 中的 `API_CONFIG`：
+
+```typescript
+export const API_CONFIG = {
+  list: "/pm/omptMillPlanOrder/list",
+  remove: "/pm/omptMillPlanOrder/remove",
+  getById: "/pm/omptMillPlanOrder/getById",
+  save: "/pm/omptMillPlanOrder/save",
+  update: "/pm/omptMillPlanOrder/update",
+  export: "/pm/omptMillPlanOrder/export",
+  // 按需增加业务操作
+  release: "/pm/omptMillPlanOrder/release",
+} as const;
+```
+
+---
+
+## api.md 模板
+
+每个页面目录下生成：
+
+````markdown
+# 接口约定 - [页面中文名]
+
+> 页面路径：`src/views/[域]/[模块]/[子模块]/[目录]/`
+> 服务缩写：[pm / mmwr / sale / ...]
+> 资源名：[camelCase 实体名]
+> 状态：🟡 待后端确认
+
+---
+
+## API_CONFIG
+
+```typescript
+export const API_CONFIG = {
+  list: "/[服务缩写]/[资源名]/list",
+  remove: "/[服务缩写]/[资源名]/remove",
+  getById: "/[服务缩写]/[资源名]/getById",
+  save: "/[服务缩写]/[资源名]/save",
+  update: "/[服务缩写]/[资源名]/update",
+  export: "/[服务缩写]/[资源名]/export",
+} as const;
+```
+
+---
+
+## 实体定义
+
+> 字段名与 data.ts 中 queryDef/columnsDef 使用的字段名**完全一致**
+
+| 字段名        | 类型   | 说明     | 必填 | 字典(logicValue) | 备注                 |
+| ------------- | ------ | -------- | ---- | ---------------- | -------------------- |
+| id            | string | 主键     | 自动 | -                | 后端生成             |
+| [field1]      | string | [说明]   | ✅   | -                |                      |
+| [statusField] | string | [状态]   | ✅   | [dictCode]       | 前端 logicValue 对应 |
+| [dateField]   | string | [日期]   | ❌   | -                | YYYY-MM-DD           |
+| createTime    | string | 创建时间 | 自动 | -                | YYYY-MM-DD HH:mm:ss  |
+| updateTime    | string | 更新时间 | 自动 | -                |                      |
+| createBy      | string | 创建人   | 自动 | -                |                      |
+
+---
+
+## 接口清单
+
+### 1. 分页查询
+
+```
+POST /[服务缩写]/[资源名]/list
+```
+
+| 字段          | 类型   | 必填 | 说明                                |
+| ------------- | ------ | ---- | ----------------------------------- |
+| current       | number | ✅   | 页码（基类自动传）                  |
+| size          | number | ✅   | 每页条数（基类自动传）              |
+| [queryField1] | string | ❌   | [说明]                              |
+| [queryField2] | string | ❌   | [说明]，对应 logicValue: [dictCode] |
+| [startDate]   | string | ❌   | 开始日期 YYYY-MM-DD                 |
+| [endDate]     | string | ❌   | 结束日期 YYYY-MM-DD                 |
+
+**响应 data.records：** 同实体定义；外壳 `{ code: 2000, message, data: { records, total, current, size, pages, countId, maxLimit, orders, searchCount } }`
+
+### 2. 详情查询
+
+```
+GET /[服务缩写]/[资源名]/getById?id=xxx
+```
+
+**响应 data：** 单个 Entity；外壳 `{ code: 2000, message, data: {...} }`
+
+### 3. 新增
+
+```
+POST /[服务缩写]/[资源名]/save
+```
+
+**请求：** 实体定义中必填字段（不含 id、createTime 等自动字段）
+
+### 4. 编辑
+
+```
+POST /[服务缩写]/[资源名]/update
+```
+
+**请求：** 同新增 + `id`（必填）
+
+### 5. 删除
+
+```
+POST /[服务缩写]/[资源名]/remove
+```
+
+**请求：** `{ "ids": ["xxx"] }` 或 `{ "id": "xxx" }`
+
+### 6. 导出（如需要）
+
+```
+GET /[服务缩写]/[资源名]/export?[查询参数]
+```
+
+---
+
+## 数据字典
+
+| dictCode(logicValue) | 用途   | 出现位置                     |
+| -------------------- | ------ | ---------------------------- |
+| [dictCode]           | [说明] | queryDef / columnsDef / form |
+
+---
+
+## 联调注意
+
+1. **响应外壳**：`{ code, message, data }`，成功 `code: 2000`（非 200，非 result）
+2. 前端字段全部 camelCase，后端 JSON 序列化输出 camelCase
+3. 时间字段统一 `YYYY-MM-DD HH:mm:ss`
+4. 大数字 ID 后端转字符串（雪花 ID 超过 JS Number 精度）
+5. 分页参数前端传 `current` / `size`（基类自动处理），后端响应 `data.records` / `data.total`
+6. 枚举字段前端传 value，后端可返回 `[field]Label` 辅助展示，或前端自行通过 `logicValue` 字典翻译
+7. 业务代码 `.then(res => res)` 拿到的就是 `data` 字段（拦截器已剥外壳）
+````
+
+---
+
+## 状态标记
+
+- 🟡 待后端确认 — 刚生成
+- 🟢 已确认 — 双方对齐，可编码
+- 🔴 有变更 — 需双方同步