haoliang-net/docs/02-功能清单/03-界面变更执行规范.md

界面变更执行规范

本规范供AI助手执行界面变更时遵循，确保最小阅读量+最大覆盖度。

---

一、动手前必读（最小文件集）

AI助手执行任何界面变更前，只需读以下文件：

优先级	文件	读的目的
必须	docs/02-前端全局规范.md	全局规范+Layout+路由总表+CRUD必填项+模块进度+工程开发规范（确认当前状态）
必须	docs/02-功能清单/02-文件夹创建规范.md	文件命名规则+创建顺序
按需	目标模块的 00-{模块名}-索引.md	了解本模块页面清单+路由跳转
按需	目标模块的页面文件	了解要修改的页面的当前设计
按需	docs/00-文档进度总览.md	仅当涉及新增/删除/状态变更时

禁止：读 01-数据库设计.md、00-需求与设计文档.md 等大文件，除非变更确实涉及数据库或核心需求。

---

二、变更执行清单

A. 新增页面

1. 确认模块编号和页面编号（读索引文件）
2. 创建页面文件，命名：{模块号}-{页面号}-{页面名}.md
3. 按 02-前端全局规范.md 中对应页面类型的必填项填写
4. 界面布局使用 box-drawing 样式（┌───┐），首行放面包屑
5. 页面末尾增加「数据需求」章节
6. 更新模块索引文件（页面清单+功能详情+子目录表）
7. 更新 02-前端全局规范.md 模块进度表
8. 更新 00-文档进度总览.md

B. 修改页面

1. 读取目标页面文件 + 模块索引文件
2. 修改页面内容（保留已有结构，只改变更部分）
3. 如果修改涉及路由/跳转/状态机 → 同步更新模块索引文件
4. 如果修改涉及新增数据需求 → 同步更新「数据需求」章节
5. 不需要更新进度文件（修改不改状态）

C. 新增模块

1. 读 02-文件夹创建规范.md 确认命名规则
2. 创建模块目录：{编号}-{模块名}/
3. 创建3个文件：00-{模块名}-索引.md + 01-{模块名}-规范.md + {模块号}-01-{页面名}.md
4. 规范文件写"继承上级规范"
5. 索引文件按模板填写
6. 页面文件按必填项填写
7. 更新 管理后台/00-管理后台-索引.md（子目录表）
8. 更新 02-前端全局规范.md 模块进度表
9. 更新 00-文档进度总览.md

---

三、联动同步规则

规则1：改了页面文件的路由或跳转 → 必须同步该模块的索引文件；如果跳转跨模块，还要同步目标模块的索引文件

规则2：页面新增了数据字段或接口需求 → 必须同步该页面的「数据需求」章节

规则3：新增或删除了页面文件 → 必须同步：模块索引文件 + 02-前端全局规范.md的模块进度表 + 00-文档进度总览.md

规则4：新增了模块目录 → 必须同步：管理后台/00-管理后台-索引.md + 02-前端全局规范.md的模块进度表 + 00-文档进度总览.md

规则5：修改了02-前端全局规范.md中的全局规范 → 必须检查各模块规范文件是否冲突

规则6（接口变更同步）：新增或变更接口时，必须同步以下3处：

• 端点清单（03-API接口设计.md §3.x）：同时维护两列——正式API列（RESTful）+ Mock URL列（POST简化），禁止只新增一列
• 页面文件§9（接口引用与数据结构）：定义该接口的Request/Response数据结构（这是数据结构的唯一来源）
• Mock文件（frontend/mock/*.ts）：按页面文件§9的数据结构生成Mock数据

记忆口诀：改页面→查索引；改路由→查双向索引；增删页面/模块→三处同步（索引+进度表+总览）；增改接口→三处同步（端点清单两列URL + 页面§9数据结构 + Mock文件）

---

四、界面布局规范

• 样式：box-drawing（┌───┐├───┤└───┘│），不用 +---+
• 首行：面包屑，格式 [面包屑] 首页 / 模块名 / 子页名
• 分区标签：方括号标注，如 [查询条件区] [列表区] [操作栏]
• 字段对齐：用竖线 | 分隔，表头和数据行对齐

---

五、禁止事项

• 禁止读大文件获取上下文（除非变更确实涉及）
• 禁止跳过联动同步（改了页面不更新索引）
• 禁止修改全局规范而不检查模块兼容性
• 禁止在页面文件中重复全局规范已有内容
• 禁止使用旧样式 +---+ 画界面布局

---

六、逐字段验证测试规范（联调测试必读）

联调测试时，以下三种场景必须执行逐字段验证，不能只验证"操作成功"：

1. 编辑测试（逐字段验证）

对每个可编辑字段：

1. 记录原始值 → 修改为新值 → 保存
2. 列表页验证：该字段对应的列显示新值
3. 重新打开编辑弹窗：逐字段比对回填值是否为新值
4. （推荐）通过 API 直接查询数据库，确认数据库中存储的值正确

2. 分页测试（数据变化验证）

1. 记录当前页第一条数据的关键字段（如 device_code）
2. 切换到第2页
3. 确认第一条数据的关键字段确实变了（不是同一批数据）
4. 切换回第1页
5. 确认数据恢复为之前记录的值

3. 详情页测试（逐字段显示验证）

对详情页每个展示字段：

1. 打开已知数据的详情页
2. 逐字段检查：名称、编码、关联名称（车间名称、品牌名称、工人名称等）、IP、状态
3. 空白/异常值不能跳过——如果某个字段显示为空，必须记录为 Bug
4. 特别关注外键关联的名称字段（ID 存在但 Name 为空 = Bug）