# 界面变更执行规范

> 本规范供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）
