@agile-team/wl-skills-kit 2.3.8 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,144 @@
1
+ # AI 辅助开发全景分析 & 架构演进蓝图
2
+
3
+ > **基于 wl-skills-kit v2.4.0 架构**
4
+ > **日期**:2026-05-02
5
+ > **目标**:企业级通用 · 质量精度高 · 速度快 · 节省 token · 还原度高 · 开箱即用 · 支持 Agent Pipeline
6
+
7
+ ---
8
+
9
+ ## 1. 能力层级
10
+
11
+ ```text
12
+ L1 提示词工程 ✅ copilot-instructions + 多编辑器适配 + standards 懒加载
13
+ L2 Skills ✅ 9 个启用 Skill + registry + pre-flight
14
+ L3 MCP ✅ 14 个 Tool(菜单/字典/权限/项目感知/通知)
15
+ L4 CLI ✅ init/update/clean/check/diff/validate/export
16
+ L5 Agent Pipeline 🟡 已落地协议,可进入试运行
17
+ L6 Multi-Agent 🔭 L5 稳定后再评估
18
+ L7 自演化体系 🔭 需要足够审计报告与模板样本后再规划
19
+ ```
20
+
21
+ ---
22
+
23
+ ## 2. 当前核心资产
24
+
25
+ | 资产 | 数量/状态 | 说明 |
26
+ |---|---:|---|
27
+ | Standards | 13 条 | 场景化 code-structure、Git 审计、AGGrid 判定均已纳入 |
28
+ | Skills | 9 个 | core/sync/ops 全部启用,domain 暂不扩展 |
29
+ | MCP Tools | 14 个 | 新增 code_scan / route_check / git_log_extract / audit_report_push |
30
+ | CLI 命令 | 7 个 | init / update / clean / check / diff / validate / export |
31
+ | Pipeline 协议 | 1 份 | `.github/skills/_pipeline.md` |
32
+ | 全盘分析文档 | 1 份 | `docs/全盘分析与智能体搭建指南.md` |
33
+
34
+ ---
35
+
36
+ ## 3. v2.4.0 关键新增
37
+
38
+ ### 3.1 Agent Pipeline
39
+
40
+ 已新增:
41
+
42
+ ```text
43
+ files/.github/skills/_pipeline.md
44
+ ```
45
+
46
+ 用于定义:
47
+
48
+ - Skill 输入来源
49
+ - Skill 产物路径
50
+ - 推荐后续动作
51
+ - Agent 完成摘要格式
52
+ - 人工确认边界
53
+
54
+ ### 3.2 MCP 项目感知工具
55
+
56
+ | Tool | 价值 |
57
+ |---|---|
58
+ | `wls_code_scan` | 扫描页面目录、文件完整性、API_CONFIG 分布 |
59
+ | `wls_route_check` | 检查页面是否可被路由发现 |
60
+ | `wls_git_log_extract` | 提取最近提交,支撑 Git 审计/变更日志 |
61
+ | `wls_audit_report_push` | 可选推送审计报告到飞书 webhook |
62
+
63
+ ### 3.3 CLI 质量工具
64
+
65
+ | 命令 | 价值 |
66
+ |---|---|
67
+ | `wl-skills check` | 新成员接入和环境排查 |
68
+ | `wl-skills diff` | update 前评估文件变化 |
69
+ | `wl-skills validate` | 无 AI 静态检查页面文件完整性 |
70
+ | `wl-skills export` | 导出菜单/字典/权限基线为 xlsx |
71
+
72
+ ---
73
+
74
+ ## 4. 智能体搭建建议
75
+
76
+ ### 4.1 最小可用 Agent
77
+
78
+ ```text
79
+ 用户目标
80
+ → 读取 _registry.md 匹配 Skill
81
+ → 读取 _pipeline.md 判断上下游
82
+ → wls_code_scan 感知项目结构
83
+ → 执行 Skill
84
+ → 输出完成摘要 + next_suggest
85
+ → 用户确认后继续下一步
86
+ ```
87
+
88
+ ### 4.2 推荐主链路
89
+
90
+ ```text
91
+ prototype-scan
92
+ → api-contract
93
+ → page-codegen
94
+ → convention-audit
95
+ → code-fix(可选)
96
+ → convention-audit 复扫
97
+ → menu-sync / dict-sync / permission-sync(按需)
98
+ ```
99
+
100
+ ### 4.3 存量项目治理链路
101
+
102
+ ```text
103
+ wls_code_scan
104
+ → convention-audit
105
+ → code-fix
106
+ → convention-audit 复扫
107
+ → wl-skills validate
108
+ ```
109
+
110
+ ---
111
+
112
+ ## 5. 后续路线
113
+
114
+ ### 短期
115
+
116
+ - 在真实项目中试跑 Agent Pipeline
117
+ - 将 `wl-skills validate` 接入 CI 非阻断阶段
118
+ - 持续收集 convention-audit 报告样本
119
+
120
+ ### 中期
121
+
122
+ - `prototype-diff`:新版原型 vs 已有代码
123
+ - `api-impact-scan`:api.md 变更影响面
124
+ - `changelog-gen`:基于 `wls_git_log_extract` 生成变更摘要
125
+ - `perf-audit`:AGGrid 性能反模式扫描
126
+
127
+ ### 暂不推进
128
+
129
+ - sale/produce 领域 Skill
130
+ - Multi-Agent 编排框架
131
+ - 自演化自动合并规范
132
+
133
+ ---
134
+
135
+ ## 6. 结论
136
+
137
+ v2.4.0 后,wl-skills-kit 已具备搭建通用智能体的基础条件:
138
+
139
+ - 有 Skills 作为结构化能力单元
140
+ - 有 MCP 作为实时项目感知与副作用执行工具
141
+ - 有 CLI 作为无 AI 的质量兜底
142
+ - 有 `_pipeline.md` 作为 Agent 串联协议
143
+
144
+ 下一步应先在真实业务项目中稳定跑通通用 Pipeline,再考虑领域 Skill 或 Multi-Agent。
@@ -0,0 +1,263 @@
1
+ # API 契约输入规范 — 后端如何配合前端 AI 代码生成
2
+
3
+ > **受众**:后端开发者
4
+ > **目的**:规范前后端接口约定流程,确保 AI 生成的 api.md 与后端实现完全一致,联调零返工
5
+
6
+ ---
7
+
8
+ ## 概述:AI 如何生成接口约定
9
+
10
+ 前端 AI(api-contract Skill)会基于页面清单自动生成 `api.md` 文件,放在每个页面目录下(与 `index.vue` 同级)。
11
+
12
+ **AI 能自动推断的部分**:
13
+ - 标准 CRUD 接口 URL(list / getById / save / update / remove / export)
14
+ - 响应结构(分页/单条/增删改/字典)
15
+ - 基本字段名(来自原型扫描结果)
16
+
17
+ **AI 无法推断、需后端提供的部分**:
18
+ - 真实的服务缩写(`pm` / `mmwr` / `sale` / ...)
19
+ - 实体名(`CamelCase` 资源名,如 `mmwrCustomerArchive`)
20
+ - 业务特殊操作(如 `submit` / `approve` / `release` / `convert`)
21
+ - 非标准字段名(后端有历史遗留命名时)
22
+
23
+ ---
24
+
25
+ ## 接口 URL 规范
26
+
27
+ 格式:`/[服务缩写]/[资源名CamelCase]/[操作]`
28
+
29
+ | 服务缩写 | 含义 | 示例 |
30
+ |---|---|---|
31
+ | `pm` | 生产管理 | `/pm/omptMillPlanOrder/list` |
32
+ | `mmwr` | 精整作业 | `/mmwr/mmwrCustomerArchive/list` |
33
+ | `sale` | 销售管理 | `/sale/saleOrder/list` |
34
+ | `hrms` | 人力资源 | `/hrms/hrmsEmployee/list` |
35
+ | `base` | 基础数据 | `/base/cmUserGroup/list` |
36
+ | `mmsm` | 炼钢管理 | `/mmsm/mmsmRsltLadleUse/list` |
37
+
38
+ **关于资源名**:
39
+ - 使用实体类名(去掉末尾的 `Entity` / `DO`,保留业务名)
40
+ - 通常带服务缩写前缀(如 `mmwrCustomerArchive`,不是 `customerArchive`)
41
+ - **请后端同学在开发前告知前端实体名**,避免 AI 自行推断
42
+
43
+ ---
44
+
45
+ ## 标准操作集
46
+
47
+ AI 会默认为每个页面生成以下标准接口,无需额外沟通:
48
+
49
+ | 操作 | 方法 | URL | 请求体 |
50
+ |------|------|-----|--------|
51
+ | 分页列表 | POST | `/list` | `{ current, size, ...查询条件 }` |
52
+ | 单条查询 | GET | `/getById` | `?id=xxx` |
53
+ | 新增 | POST | `/save` | 实体字段(不含 id) |
54
+ | 编辑 | POST | `/update` | 实体字段(含 id) |
55
+ | 删除 | POST | `/remove` | `{ id }` |
56
+ | 导出 | GET | `/export` | `?...查询条件` |
57
+
58
+ > 如后端实际 URL 与上述规范不同(历史项目),请在 `api.md` 确认时注明实际 URL。
59
+
60
+ ---
61
+
62
+ ## 统一响应结构(必须遵守)
63
+
64
+ > **所有接口响应外壳必须是这个格式,AI 和前端框架均依赖此契约**
65
+
66
+ ```json
67
+ {
68
+ "code": 2000,
69
+ "message": "操作成功",
70
+ "data": <实际数据>
71
+ }
72
+ ```
73
+
74
+ ### 分页列表响应(`/list` 接口)
75
+
76
+ ```json
77
+ {
78
+ "code": 2000,
79
+ "message": "操作成功",
80
+ "data": {
81
+ "records": [ { "字段名": "值" } ],
82
+ "total": 100,
83
+ "current": 1,
84
+ "size": 20,
85
+ "pages": 5
86
+ }
87
+ }
88
+ ```
89
+
90
+ > 前端 `AbstractPageQueryHook` 自动适配 MyBatis-Plus 分页格式(取 `records` 和 `total`),**不要改为 `list` 或 `rows`**。
91
+
92
+ ### 单条查询响应
93
+
94
+ ```json
95
+ { "code": 2000, "message": "操作成功", "data": { "id": "...", "字段名": "值" } }
96
+ ```
97
+
98
+ ### 增删改响应
99
+
100
+ ```json
101
+ { "code": 2000, "message": "操作成功", "data": true }
102
+ ```
103
+
104
+ 或返回新记录主键:
105
+
106
+ ```json
107
+ { "code": 2000, "message": "操作成功", "data": "1234567890123456789" }
108
+ ```
109
+
110
+ ### 字典查询响应
111
+
112
+ ```json
113
+ {
114
+ "code": 2000,
115
+ "message": "操作成功",
116
+ "data": [
117
+ { "value": "01", "label": "启用" },
118
+ { "value": "02", "label": "停用" }
119
+ ]
120
+ }
121
+ ```
122
+
123
+ ### 失败响应
124
+
125
+ ```json
126
+ { "code": 4001, "message": "参数缺失:customerName 不能为空", "data": null }
127
+ ```
128
+
129
+ > **成功码是 `2000`,不是 `200`**。`200` 是历史 mock 环境的遗留,真实后端必须用 `2000`。
130
+
131
+ ---
132
+
133
+ ## 字段命名约定
134
+
135
+ | 端 | 规范 | 说明 |
136
+ |---|---|---|
137
+ | **后端(数据库/Entity)** | `snake_case` | 如 `customer_name`, `enable_status` |
138
+ | **后端(JSON序列化)** | `camelCase` | Jackson 自动转换,前端收到的是驼峰 |
139
+ | **前端(请求/响应)** | `camelCase` | 与 Jackson 转换后的字段一致 |
140
+
141
+ **核心原则**:前端请求字段名 = 响应中的字段名 = `api.md` 中的字段名 = `data.ts` 中使用的字段名
142
+ **都是 camelCase**,不需要在前端做字段名转换。
143
+
144
+ ---
145
+
146
+ ## 业务特殊操作(最需要提前沟通)
147
+
148
+ 以下操作**AI 无法从原型直接推断**,需后端明确告知操作名和参数:
149
+
150
+ | 常见操作 | 默认 URL | 请求参数 | 备注 |
151
+ |---|---|---|---|
152
+ | 提交审批 | `/submit` | `{ id }` | |
153
+ | 审批通过 | `/approve` | `{ id, opinion? }` | |
154
+ | 审批驳回 | `/reject` | `{ id, opinion }` | opinion 必填 |
155
+ | 撤回 | `/withdraw` | `{ id }` | |
156
+ | 启用/停用 | `/changeStatus` | `{ id, status }` | |
157
+ | 转化 | `/convert` | `{ id }` | 如临时→正式客户 |
158
+ | 下发 | `/release` | `{ id }` | |
159
+ | 关闭 | `/close` | `{ id }` | |
160
+ | 作废 | `/cancel` | `{ id }` | |
161
+ | 批量操作 | `/batchXxx` | `{ ids: [] }` | |
162
+ | 子表查询 | `/queryXxxList` | `{ mainId }` | |
163
+
164
+ **请在收到 ai.md 后,确认或修正这些业务操作的实际 URL 和参数格式。**
165
+
166
+ ---
167
+
168
+ ## api.md 工作流
169
+
170
+ ### 第一步:AI 生成草稿
171
+
172
+ AI 基于原型/详设,自动生成 `api.md` 初稿,内容包括:
173
+ - `API_CONFIG`(URL 汇总)
174
+ - 实体字段表(字段名、类型、是否必填)
175
+ - 请求/响应示例
176
+
177
+ 初稿状态标记为 `🟡 待后端确认`。
178
+
179
+ ### 第二步:后端确认/修正
180
+
181
+ 后端同学拿到 `api.md` 后,需要确认/修正:
182
+
183
+ - [ ] 服务缩写正确(`pm` / `mmwr` / ...)
184
+ - [ ] 实体名正确(与 Controller 中路径一致)
185
+ - [ ] 字段名(camelCase)与实际 Entity 的 Jackson 序列化一致
186
+ - [ ] 分页参数名(`current` / `size` 还是其他)
187
+ - [ ] 特殊业务操作的 URL 和参数正确
188
+ - [ ] 必填字段标注正确
189
+ - [ ] 字典的 `value` 值(01/02/1/2 等)正确
190
+
191
+ 修正后将状态改为 `✅ 已确认` 或在注释中标注修改点。
192
+
193
+ ### 第三步:前端基于 api.md 编写 data.ts
194
+
195
+ `api.md` 确认后,`data.ts` 中的 `API_CONFIG` URL 和所有字段名与 `api.md` 完全一致,联调时两端字段自动对齐。
196
+
197
+ ---
198
+
199
+ ## 常见问题
200
+
201
+ ### Q:分页接口我们用的是 GET 还是 POST?
202
+
203
+ 统一用 **POST**,查询条件放在请求体(不是 query string)。这样支持复杂查询条件(数组、嵌套对象),且 URL 不会过长。
204
+
205
+ ### Q:主键我们用的是 int 还是 string 类型?
206
+
207
+ 前端统一按 **string** 处理主键(Java `Long` 在 JS 中超过安全整数范围,Jackson 加 `@JsonSerialize(using = ToStringSerializer.class)` 序列化为字符串)。api.md 中 `id` 字段类型写 `string`。
208
+
209
+ ### Q:软删除的字段前端需要过滤吗?
210
+
211
+ 不需要,后端 SQL 层过滤。前端不关心 `is_deleted` / `del_flag` 字段。
212
+
213
+ ### Q:`createTime` / `updateTime` / `createUser` / `updateUser` 要写在 api.md 里吗?
214
+
215
+ 只有在页面上**显示**这些字段时才需要写入 api.md 的实体字段表,否则不需要(前端不用知道这些内部字段)。
216
+
217
+ ### Q:返回的列表字段和表单字段不一样,需要两个接口吗?
218
+
219
+ 通常一个 `getById` 接口返回完整字段(包括列表不展示的字段)即可。前端 `data.ts` 对列表和表单分别映射不同字段,共用同一接口响应。
220
+
221
+ ---
222
+
223
+ ## api.md 模板(供参考)
224
+
225
+ ```markdown
226
+ # 接口约定 - [页面中文名]
227
+
228
+ > 服务缩写:[pm / mmwr / sale / ...]
229
+ > 资源名:[实体名CamelCase]
230
+ > 状态:🟡 待后端确认
231
+
232
+ ## API_CONFIG
233
+
234
+ \`\`\`typescript
235
+ export const API_CONFIG = {
236
+ list: "/[服务缩写]/[资源名]/list",
237
+ getById: "/[服务缩写]/[资源名]/getById",
238
+ save: "/[服务缩写]/[资源名]/save",
239
+ update: "/[服务缩写]/[资源名]/update",
240
+ remove: "/[服务缩写]/[资源名]/remove",
241
+ export: "/[服务缩写]/[资源名]/export",
242
+ } as const;
243
+ \`\`\`
244
+
245
+ ## 实体字段
246
+
247
+ | 字段名(camelCase) | 类型 | 说明 | 必填 | 字典code |
248
+ |---|---|---|---|---|
249
+ | id | string | 主键 | - | - |
250
+ | customerName | string | 客户名称 | 是 | - |
251
+ | customerType | string | 客户类型 | 是 | customer_type |
252
+ | enableStatus | string | 启用状态 | 是 | enable_status |
253
+
254
+ ## 分页查询(POST /list)
255
+
256
+ 请求参数:`{ current: 1, size: 20, customerName?: string, customerType?: string }`
257
+ 响应:标准分页格式,`records` 包含实体字段
258
+
259
+ ## 单条查询(GET /getById)
260
+
261
+ 请求:`?id=xxx`
262
+ 响应:实体完整字段(含表单字段)
263
+ ```
@@ -0,0 +1,238 @@
1
+ # 详设文档输入规范 — 如何编写让 AI 精确生成代码的需求文档
2
+
3
+ > **受众**:业务分析师 / 产品经理 / 项目经理
4
+ > **目的**:规范详细设计文档的编写格式,使 AI(prototype-scan Skill 模式 B)能 95-100% 准确提取页面结构,无需 AI 推断字段名和字典码
5
+
6
+ ---
7
+
8
+ ## 为什么详设比原型精度更高
9
+
10
+ **精度对比**:
11
+
12
+ | 输入方式 | 字段不遗漏 | 英文字段名 | 字典 code | 综合精度 |
13
+ |---|---|---|---|---|
14
+ | 详设文档(本文推荐格式) | ✅ | ✅ 直接读取 | ✅ 直接读取 | **95-100%** |
15
+ | Axure HTML 原型 | ✅ | ⚠️ AI 推断 | ⚠️ AI 推断 | 90-95% |
16
+ | 原型(无字段英文名标注) | ✅ | ⚠️ AI 推断 | ⚠️ AI 推断 | 85-90% |
17
+ | 自由格式需求文档 | ✅ | ⚠️ AI 推断 | ⚠️ AI 推断 | 80-90% |
18
+
19
+ **关键差距**:
20
+ - **字段英文名**:AI 从中文推断准确率约 85%,一个项目的 "客户编号" 可能是 `customerCode`、`custNo`、`clientId`……不确定
21
+ - **字典 code**:AI 完全无法推断,必须人工提供;推断值上线后 100% 需要联调确认
22
+
23
+ ---
24
+
25
+ ## 核心原则
26
+
27
+ 1. **字段英文名(camelCase)必须提供** — 这是最影响精度的单项因素
28
+ 2. **字典 code 必须提供** — 提供后 AI 可以直接硬编码,无需联调
29
+ 3. **字段顺序即最终顺序** — 表格列、查询字段的顺序 AI 会原样保留
30
+ 4. **格式不限,但越结构化越好** — Markdown 表格 > 普通列表 > 自由段落
31
+
32
+ ---
33
+
34
+ ## 推荐文档结构(标准模板)
35
+
36
+ > 直接复制此模板,按实际情况填写。不需要的章节可删除,但请保留标题层级。
37
+
38
+ ````markdown
39
+ ## [页面名称](如:客户档案)
40
+
41
+ **基本信息**
42
+ - 交互模式:LIST
43
+ (可选:LIST / MASTER_DETAIL / TREE_LIST / FORM_TAB)
44
+ - 目录名:customer-archive
45
+ (kebab-case,与路由路径一致)
46
+ - 服务缩写:mmwr
47
+ (如:pm / mmwr / sale / hrms / base)
48
+ - 是否隐藏菜单:否
49
+ (是 = 从列表跳转进入,不在菜单显示;否 = 常规菜单页)
50
+
51
+ ---
52
+
53
+ ### 查询条件
54
+
55
+ | 字段名(camelCase) | 中文名 | 类型 | 字典code | 备注 |
56
+ |------------------|--------|------|---------|------|
57
+ | customerName | 客户名称 | input | - | |
58
+ | customerType | 客户类型 | dict | customer_type | |
59
+ | enableStatus | 启用状态 | dict | enable_status | |
60
+ | createDate | 建立日期 | dateRange | - | 起:createDateStart 止:createDateEnd |
61
+
62
+ **字段类型参考**:
63
+ - `input` — 文本输入框
64
+ - `dict` — 字典下拉选择(需提供字典code)
65
+ - `date` — 单个日期选择
66
+ - `dateRange` — 日期范围(起止两个字段)
67
+ - `select` — 非字典的自定义下拉(需在备注里说明选项)
68
+ - `treeSelect` — 树形选择(部门/组织等)
69
+ - `number` — 数字输入
70
+
71
+ ---
72
+
73
+ ### 工具栏按钮
74
+
75
+ | 按钮文字 | 类型 | 行为 | 权限码 |
76
+ |----------|------|------|--------|
77
+ | 新增 | primary | openAddModal | - |
78
+ | 导出 | plain | export | - |
79
+
80
+ **行为说明**:
81
+ - `openAddModal` — 打开新增弹窗
82
+ - `export` — 导出当前查询结果
83
+ - `import` — 导入
84
+ - `batchDelete` — 批量删除(需勾选行)
85
+ - `customAction` — 自定义行为(在备注中描述)
86
+
87
+ ---
88
+
89
+ ### 表格列(按显示顺序)
90
+
91
+ | 字段名(camelCase) | 中文名 | 宽度px | 字典code | 备注 |
92
+ |------------------|--------|--------|---------|------|
93
+ | customerCode | 客户编码 | 120 | - | 可点击查看详情 |
94
+ | customerName | 客户名称 | 200 | - | |
95
+ | customerType | 客户类型 | 120 | customer_type | |
96
+ | enableStatus | 启用状态 | 100 | enable_status | |
97
+ | createDate | 建立日期 | 120 | - | 格式:YYYY-MM-DD |
98
+
99
+ > 宽度列不强制要求,填写参考值即可(AI 有默认规则)。
100
+
101
+ ---
102
+
103
+ ### 操作列
104
+
105
+ | 按钮文字 | 行为 | 条件显示 |
106
+ |----------|------|----------|
107
+ | 编辑 | openEditModal | - |
108
+ | 删除 | delete | - |
109
+ | 查看 | openDetailModal | - |
110
+
111
+ ---
112
+
113
+ ### 新增/编辑弹窗表单
114
+
115
+ (若新增和编辑共用同一弹窗,则只需写一次)
116
+
117
+ | 字段名(camelCase) | 中文名 | 类型 | 必填 | 字典code | 备注 |
118
+ |------------------|--------|------|------|---------|------|
119
+ | customerName | 客户名称 | input | 是 | - | |
120
+ | customerType | 客户类型 | dict | 是 | customer_type | |
121
+ | phone | 联系电话 | input | 否 | - | |
122
+ | enableStatus | 启用状态 | dict | 是 | enable_status | 新增时默认"启用" |
123
+
124
+ ---
125
+
126
+ ### 子表(如有)
127
+
128
+ **子表名称**: 业务信息(businessInfo)
129
+ - 是否可增删行:是
130
+ - 是否行内编辑:否
131
+
132
+ | 字段名 | 中文名 | 类型 | 必填 | 字典code |
133
+ |--------|--------|------|------|---------|
134
+ | salesType | 销售别 | dict | 是 | sales_type |
135
+ | remark | 备注 | textarea | 否 | - |
136
+
137
+ ---
138
+
139
+ ### 特殊说明(notes)
140
+
141
+ - 客户编码点击后跳转到"客户详情"页(隐藏菜单页)
142
+ - 客户类型改变后,客户分类下拉选项联动变化(根据客户类型过滤)
143
+ - 删除需二次确认,提示文字:"确认删除客户[客户名称]吗?"
144
+ ````
145
+
146
+ ---
147
+
148
+ ## 各字段详解
149
+
150
+ ### 交互模式(必填)
151
+
152
+ | 模式 | 说明 | 适用场景 |
153
+ |------|------|----------|
154
+ | `LIST` | 标准列表页 | 90% 的列表管理页面 |
155
+ | `MASTER_DETAIL` | 主从详情(点击列表行,右侧或下方展示详情) | 有主从关联的数据 |
156
+ | `TREE_LIST` | 左树右表(左侧树形导航,右侧表格) | 分类/层级数据管理 |
157
+ | `FORM_TAB` | Tab 表单页(多个 Tab 分区展示详情) | 数据详情展示/编辑 |
158
+
159
+ ---
160
+
161
+ ### 字段英文名规范
162
+
163
+ - 使用 **camelCase**(如 `customerName`,不是 `customer_name` 或 `CustomerName`)
164
+ - 与后端接口字段保持一致(Jackson 注解转换后的驼峰名)
165
+ - 日期范围字段格式:中文名带"日期",字段名带 `Start`/`End` 后缀(如 `createDateStart` / `createDateEnd`)
166
+
167
+ **命名参考**:
168
+
169
+ | 常见中文名 | 推荐英文名 |
170
+ |---|---|
171
+ | 编码 / 编号 | `xxxCode` / `xxxNo` |
172
+ | 名称 | `xxxName` |
173
+ | 状态 | `xxxStatus` |
174
+ | 类型 | `xxxType` |
175
+ | 启用状态 | `enableStatus` |
176
+ | 创建时间 | `createTime` |
177
+ | 建立日期 | `createDate` |
178
+ | 操作人 | `operateUser` |
179
+ | 备注 | `remark` |
180
+
181
+ ---
182
+
183
+ ### 字典 code 的重要性
184
+
185
+ 字典 code 决定下拉选项和状态展示的数据来源,**不提供则 AI 会猜一个,上线必然需要联调修正**。
186
+
187
+ 获取方式:
188
+ 1. 查询后端同学的字典表(通常在系统管理 → 字典管理)
189
+ 2. 查看已有类似页面的 data.ts 中使用的 code
190
+ 3. 直接问后端"这个字段用的哪个字典"
191
+
192
+ 字典 code **全部用下划线小写**(如 `order_status`,不是 `orderStatus` 或 `ORDER_STATUS`)。
193
+
194
+ ---
195
+
196
+ ### 关于"是否隐藏菜单"
197
+
198
+ - **否(菜单可见)**:页面在菜单栏直接显示,通过导航进入
199
+ - **是(隐藏菜单)**:页面通过其他页面的链接跳转进入(如点击列表的"客户编码"进入"客户详情"),不在菜单显示
200
+
201
+ 隐藏菜单页面在 `pages.ts` 注册时会带 `hideInMenu: true`。
202
+
203
+ ---
204
+
205
+ ## 常见遗漏清单
206
+
207
+ 提交文档前检查:
208
+
209
+ - [ ] 每个表格列都有 camelCase 字段名
210
+ - [ ] 所有下拉选择类字段都填了字典 code(`dict` 类型的字段)
211
+ - [ ] 日期范围字段写了起止字段名(`xxxStart` / `xxxEnd`)
212
+ - [ ] 弹窗表单的"必填"列填写完整
213
+ - [ ] 子表的"可增删行"和"行内编辑"两个属性都填了
214
+ - [ ] 特殊联动/特殊规则写在了"特殊说明"章节
215
+
216
+ ---
217
+
218
+ ## 不强制规定,但能提升精度
219
+
220
+ 以下内容可选,填写后 AI 精度会进一步提升:
221
+
222
+ | 可选信息 | 精度提升项 | 填写位置 |
223
+ |---|---|---|
224
+ | 接口 URL | 直接写入 api.md,无需推断 | 特殊说明 or 专门的接口章节 |
225
+ | 详情接口字段名 | 确保与查询字段名一致 | 子表/弹窗的字段表 |
226
+ | 表格每列的宽度 | 避免默认宽度不合适 | 表格列的"宽度px"列 |
227
+ | 操作列的权限码 | 直接生成权限控制代码 | 操作列的"权限码"列 |
228
+
229
+ ---
230
+
231
+ ## 与 Axure 原型的选择建议
232
+
233
+ | 项目阶段 | 推荐方式 |
234
+ |---|---|
235
+ | 需求阶段(只有交互稿)| 使用 Axure 原型(见 [input-spec-prototype.md](input-spec-prototype.md)) |
236
+ | 设计完成(有字段清单) | 使用详设文档(本文),精度更高 |
237
+ | 两者都有 | 先用详设文档,Axure 原型作为视觉参考 |
238
+ | 都没有,只有自然语言描述 | AI 会基于描述生成草稿,需人工逐一核对 |