TARE-Learn/第 4 天：JeecgBoot 工单复杂业务开发：权限、审计、异常态与看板.md

# 第 4 天：JeecgBoot 工单复杂业务开发：权限、审计、异常态与看板

# 第 0 部分：从基础功能到复杂业务

---

## Slide 0-1：第 3 天到第 4 天

### PPT 页面内容

```Plain Text
第 3 天：
JeecgBoot 工单基础功能闭环

完成：
需求拆解
接口契约
代码生成 Review
工单列表
工单详情
基础验证

第 4 天：
复杂业务开发与上线前审查
```

### 讲师逐字稿

昨天我们已经把 JeecgBoot 工单模块的基础功能跑通了。

第三天的重点是从需求到基础功能闭环：先把工单需求拆成用户故事和验收标准，再设计字段、接口契约、页面状态，然后借助 JeecgBoot 的代码生成能力得到基础 CRUD，最后对工单列表和工单详情做基础验证。

今天进入第四天，重点完全不同。

第四天不是继续生成 CRUD，也不是把页面字段再调整一遍。

今天要处理真实企业后台最容易出问题的部分：权限、状态流转、审计日志、异常态、防重复提交和看板指标。

也就是说，第三天解决“能跑通”，第四天解决“能不能安全、可控、可审计、可上线前审查”。

---

## Slide 0-2：第四天训练主线

### PPT 页面内容

```Plain Text
今天训练七个动作：

设计 RBAC 权限矩阵
生成权限控制方案
设计工单状态机
补齐审计日志
处理异常态和防御性逻辑
开发研发效能看板
阶段 Review 与修复
```

### 讲师逐字稿

今天的主线有七个动作。

第一，设计 RBAC 权限矩阵。工单模块不是所有人都能做所有操作。

第二，生成权限控制方案。权限不能只停留在按钮隐藏，必须覆盖菜单、按钮、接口和数据权限。

第三，设计工单状态机。工单从创建、处理中、待验证、关闭、驳回，不是随便跳转的。

第四，补齐审计日志。谁在什么时候改了什么字段，必须能追溯。

第五，处理异常态和防御性逻辑。空数据、接口失败、权限不足、重复提交、非法状态流转都要有明确处理。

第六，开发研发效能看板。看板不是炫技图表，而是对工单数据进行指标化管理。

第七，阶段 Review 与修复。今天最后要用 TRAE 对当天复杂业务代码做一次结构化 Review。

---

## Slide 0-3：第四天贯穿案例

### PPT 页面内容

```Plain Text
贯穿案例：
JeecgBoot 工单模块增强

从“能用”
升级到：

可控
可审计
可验证
可统计
可 Review
```

### 讲师逐字稿

第四天仍然使用 JeecgBoot 工单模块。

但今天的目标不是做一个新的模块，而是把第三天的基础工单模块增强到更接近企业真实系统的状态。

一个工单模块只是能查询、能打开详情，还不能算真正可用。

真实系统还要回答几个问题：

谁能新增工单？谁能指派工单？谁能删除工单？谁能关闭工单？

状态能不能乱跳？关闭后的工单能不能重新处理？

指派人变更有没有日志？状态变更有没有前后值？

接口失败时页面会不会崩？重复点击会不会提交两次？

看板指标怎么算？关闭周期的口径是什么？

今天就围绕这些问题展开。

---

## Slide 0-4：第四天不做什么

### PPT 页面内容

```Plain Text
今天不做：

不重新生成基础 CRUD
不大改 JeecgBoot 框架
不追求复杂页面效果
不让 AI 自行决定业务权限
不跳过人工 Review

今天只做：
围绕工单模块补复杂业务闭环
```

### 讲师逐字稿

在正式进入实操之前，先把边界说清楚。

第四天不是让大家重新生成一个工单 CRUD。

第三天已经完成基础功能闭环，今天是在这个基础上补复杂业务能力。

也不要让 AI 大改 JeecgBoot 框架。

JeecgBoot 本身已经提供菜单、权限、代码生成、日志、字典、前后端分层等能力，课堂里要做的是顺着它的体系增强工单模块，而不是绕开框架另起一套。

今天也不追求看板页面多炫。

看板的重点是指标口径和数据来源，不是图表数量。

最重要的是，不让 AI 自己决定业务权限。

AI 可以生成矩阵初稿、列出遗漏项、生成检查清单，但最终谁能删除工单、谁能关闭工单、谁能看审计日志，必须由人确认。

---

## Slide 0-5：课堂工作区与代码落点

### PPT 页面内容

```Plain Text
课堂实操围绕四类文件：

前端页面
前端 API
后端 Controller / Service
权限、日志、状态、看板相关模型

要求：
每个改动都能说清文件位置、业务规则和验收方式
```

### 讲师逐字稿

今天虽然是讲义课，但每个产物都要能落到代码现场。

JeecgBoot 不同版本、不同团队生成目录可能略有差异，所以讲义里不强行绑定唯一目录。

课堂上大家以自己沙箱项目实际生成路径为准。

通常会涉及四类文件。

第一类是前端页面，比如工单列表、详情、表单、看板页面。

第二类是前端 API，比如工单查询、指派、状态流转、审计日志、看板统计接口。

第三类是后端 Controller 和 Service，比如 `WorkOrderController`、`WorkOrderServiceImpl`。

第四类是权限、日志、状态、看板相关模型，比如状态枚举、流转请求 DTO、审计日志实体、看板指标 VO。

今天每个小组做完一个实操，都要回答三个问题：改了哪里、遵守了哪条业务规则、怎么验收。

### 课堂产出

```md
# 第四天课堂工作区记录

## 前端文件
- 工单列表页面：
- 工单详情页面：
- 工单 API：
- 工单看板页面：

## 后端文件
- Controller：
- Service：
- Mapper：
- Entity / DTO / VO：

## 配置与数据
- 菜单权限配置：
- 字典配置：
- 审计日志表：

## 说明
以上路径以课堂沙箱项目实际生成结果为准。
```

---

# 模块 1：RBAC 权限模型设计

---

## Slide 1-1：为什么工单模块必须先做权限矩阵？

### PPT 页面内容

```Plain Text
工单模块不是普通 CRUD

不同角色看到的内容不同
不同角色能做的动作不同
不同角色的数据范围不同

先设计权限矩阵
再生成权限控制方案
```

### 讲师逐字稿

工单模块看起来像一个普通 CRUD，但真实业务里它不是普通 CRUD。

管理员、负责人、研发、测试、只读用户，他们的权限边界完全不同。

研发可以处理自己被指派的工单，但不一定能删除工单。

测试可以创建缺陷工单，也可以验证或驳回，但不一定能指派所有人。

负责人可以查看团队工单、指派、跟踪进度。

只读用户只能查看，不能修改。

所以在写权限代码之前，必须先设计权限矩阵。

如果没有权限矩阵，AI 很容易直接按 CRUD 默认生成新增、编辑、删除按钮，最后变成所有人都能看到或调用敏感操作。

---

## Slide 1-2：工单角色定义

### PPT 页面内容

```Plain Text
建议角色：

管理员
负责人
研发
测试
只读用户
```

### 讲师逐字稿

今天我们先定义五类角色。

管理员拥有全部工单管理权限，可以做配置、删除、看板查看等操作。

负责人负责团队工单，可以查看团队范围内工单、指派工单、推动状态流转、查看看板。

研发负责处理被分配给自己的工单，可以更新处理进度、提交验证、评论。

测试可以创建缺陷工单，可以验证处理结果，可以驳回或建议关闭。

只读用户只查看，不修改。

注意，这里先不用纠结和企业真实组织是否完全一致。课堂上需要一个足够典型的 RBAC 模型，后面才能训练权限矩阵、状态流转和测试点。

---

## Slide 1-3：RBAC 权限矩阵示例

### PPT 页面内容

```Plain Text
权限矩阵必须回答：

谁能看？
谁能改？
谁能删？
谁能指派？
谁能流转状态？
谁能看统计？
```

### 讲师逐字稿

权限矩阵不是写几句“管理员权限最大”。

它必须落到具体功能点。

比如查看列表、查看详情、新增工单、编辑工单、删除工单、指派工单、更新状态、查看审计记录、查看看板。

每个功能点都要明确哪些角色允许，哪些角色不允许。

这张矩阵后面会直接影响前端按钮权限、后端接口权限和测试用例。

### 课堂产出

```md
# 工单模块 RBAC 权限矩阵

| 功能 | 管理员 | 负责人 | 研发 | 测试 | 只读 |
|---|---|---|---|---|---|
| 查看列表 | Y | Y | Y | Y | Y |
| 查看详情 | Y | Y | Y | Y | Y |
| 新增工单 | Y | Y | N | Y | N |
| 编辑工单 | Y | Y | 条件允许 | 条件允许 | N |
| 删除工单 | Y | N | N | N | N |
| 指派工单 | Y | Y | N | N | N |
| 提交验证 | Y | Y | Y | N | N |
| 关闭工单 | Y | Y | N | Y | N |
| 驳回工单 | Y | Y | N | Y | N |
| 查看审计记录 | Y | Y | 条件允许 | 条件允许 | N |
| 查看看板 | Y | Y | N | N | N |
```

---

## Slide 1-4：用 TRAE 生成权限矩阵

### PPT 页面内容

```Plain Text
Prompt 要求：

基于角色
基于功能点
区分允许 / 禁止 / 条件允许
输出验收方式
```

### 讲师逐字稿

这里可以让 TRAE 辅助生成权限矩阵，但不能让它凭空决定业务权限。

更合理的做法是：我们给定角色和功能点，让 TRAE 生成一个初稿，然后人工确认。

AI 可以帮助我们补漏，比如提醒我们“导出”“查看审计记录”“状态流转”也是敏感操作。

但最终谁能做什么，必须由业务和团队确认。

### 推荐 Prompt

```md
请基于 JeecgBoot 工单模块设计 RBAC 权限矩阵。

角色：
管理员、负责人、研发、测试、只读用户。

功能点：
查看列表、查看详情、新增、编辑、删除、指派、提交验证、关闭、驳回、查看审计记录、查看看板。

要求：
1. 区分允许、禁止、条件允许。
2. 条件允许必须说明条件。
3. 每个敏感操作给出验收方式。
4. 不要直接生成代码。

输出：
权限矩阵表 + 不确定点。
```

---

## Slide 1-5：可直接复制到 rules：权限安全

### PPT 页面内容

```Plain Text
权限安全 rules：

敏感操作必须四层校验
权限字符必须有来源或标记为建议
数据权限不得被查询条件替代

每条 rule 都要写清：
适用场景、必须、禁止、验收方式
```

### 讲师逐字稿

这里把权限矩阵进一步沉淀成 rules。

rules 不是写给人看的口号，而是写给 AI 和团队共同执行的约束。

权限相关至少要有三条硬规则。

第一，敏感操作必须四层校验：菜单、按钮、接口、数据范围都要覆盖。

第二，权限字符必须有来源。如果是新建议，要明确标记为建议，不能让 AI 凭空编一个权限字符就当成事实。

第三，数据权限不能被前端查询条件替代。后端必须校验当前用户的数据范围。

后面权限方案、代码修改和 Review 都要回到这些 rules。

### 课堂产出

```md
## 敏感操作必须四层校验
- 级别：硬约束
- 适用场景：新增、编辑、删除、指派、状态流转、查看审计、查看看板。
- 必须：同时覆盖页面/菜单权限、按钮权限、后端接口权限、数据范围权限。
- 禁止：只做页面或按钮控制。
- 验收方式：授权角色能完成；未授权角色前端不可见且直接请求接口失败；越权数据访问失败。

## 权限字符必须有来源或标记为建议
- 必须：来自现有菜单、权限配置、前端权限指令、后端鉴权注解或团队规范。
- 禁止：凭空编造权限字符并当成事实。
- 验收方式：权限字符在前端、菜单配置、后端接口之间一致。

## 数据权限不得被查询条件替代
- 必须：后端统一校验当前用户可访问的数据范围。
- 禁止：只依赖前端传入 userId、deptId、tenantId 或筛选条件。
```

---

# 模块 2：权限控制方案生成

---

## Slide 2-1：权限不是按钮隐藏

### PPT 页面内容

```Plain Text
权限控制四层：

菜单权限
按钮权限
接口权限
数据权限

前端按钮不是安全边界
后端接口才是强制边界
```

### 讲师逐字稿

第二天我们已经讲过：前端按钮权限不是安全边界。

今天在 JeecgBoot 工单模块里要真正落地。

权限控制至少有四层。

菜单权限决定用户能不能进入工单管理页面。

按钮权限决定页面上是否显示新增、编辑、删除、指派、状态变更等按钮。

接口权限决定用户直接调用接口时是否会被后端拒绝。

数据权限决定用户能看到哪些工单数据，比如负责人看团队，研发看自己被指派的工单。

如果只隐藏按钮，但后端接口没有权限校验，那就是典型漏洞。

---

## Slide 2-2：权限字符设计

### PPT 页面内容

```Plain Text
权限字符建议：

work:order:list
work:order:query
work:order:add
work:order:edit
work:order:delete
work:order:assign
work:order:transition
work:order:audit
work:order:dashboard
```

### 讲师逐字稿

权限字符要命名清楚，不能随便写。

建议使用统一格式，比如 `work:order:add`、`work:order:delete`。

这样前端按钮、后端接口、菜单配置、Review 清单都能对齐。

如果权限字符命名混乱，后续排查问题会非常麻烦。

比如页面上叫 `work:order:remove`，后端叫 `work:order:delete`，菜单里又叫 `ticket:delete`，AI 和人都会判断困难。

所以第四天要把权限字符也当成设计产物。

---

## Slide 2-3：权限控制方案表

### PPT 页面内容

```Plain Text
每个敏感操作必须写清：

前端按钮
权限字符
后端接口
后端校验
数据范围
验收方式
```

### 讲师逐字稿

权限控制方案不能停留在“加权限”。

每个敏感操作都要写清楚：前端哪个按钮、使用哪个权限字符、对应哪个后端接口、后端如何校验、是否涉及数据权限、怎么验收。

比如删除工单：

前端有删除按钮，权限字符是 `work:order:delete`。

后端接口是 `/workOrder/delete`。

后端必须校验权限。

验收方式是非管理员账号直接请求接口时返回 403。

这样才是可执行的权限方案。

### 课堂产出

```md
# 工单模块权限控制方案

| 操作 | 前端入口 | 权限字符 | 后端接口 | 后端校验 | 数据权限 | 验收 |
|---|---|---|---|---|---|---|
| 查看列表 | 菜单/列表 | work:order:list | /workOrder/list | 登录校验 | 按角色过滤 | 不同角色数据范围不同 |
| 新增工单 | 新增按钮 | work:order:add | /workOrder/add | 权限注解 | 无 | 无权限账号返回 403 |
| 删除工单 | 删除按钮 | work:order:delete | /workOrder/delete | 权限注解 | 管理员范围 | 非管理员返回 403 |
| 指派工单 | 指派按钮 | work:order:assign | /workOrder/assign | 权限注解 | 团队范围 | 研发账号不可指派 |
| 状态流转 | 状态按钮 | work:order:transition | /workOrder/transition | 权限注解 | 工单可见范围 | 非法角色不能流转 |
```

---

## Slide 2-4：权限 Prompt 模板

### PPT 页面内容

```Plain Text
让 TRAE 输出方案
不要直接改代码

先要表格
再要影响范围
最后才进入代码修改
```

### 讲师逐字稿

权限相关修改一定不要直接让 TRAE 改代码。

先让它输出权限控制方案表。

然后让它说明影响范围，包括前端页面、api 文件、后端 Controller、Service、菜单配置、测试点。

人工确认后，再进入代码修改。

### 推荐 Prompt

```md
请基于工单模块 RBAC 权限矩阵，生成 JeecgBoot 权限控制方案。

要求：
1. 区分菜单权限、按钮权限、接口权限、数据权限。
2. 每个敏感操作都要列出权限字符。
3. 每个接口都要说明是否需要后端权限校验。
4. 不要直接修改代码。
5. 输出影响范围和验收方式。

输出：
权限控制方案表 + 影响范围 + 验收清单。
```

---

## Slide 2-5：JeecgBoot 权限落地检查

### PPT 页面内容

```Plain Text
权限落地检查：

菜单是否配置权限字符
按钮是否绑定权限字符
前端是否只负责显示控制
后端接口是否强制校验
查询是否按数据范围过滤
无权限请求是否返回拒绝
```

### 讲师逐字稿

有了权限控制方案之后，要回到 JeecgBoot 项目里检查落地。

第一，看菜单配置里是否有对应权限字符。

第二，看前端按钮是否绑定了权限字符。

第三，看前端是否只负责显示控制，而不是把按钮隐藏当成最终安全边界。

第四，看后端接口是否做了强制校验。

第五，看列表查询是否按角色做了数据范围过滤。

第六，用无权限账号或模拟请求验证接口是否真的拒绝。

这里要提醒大家，权限最常见的问题不是完全没做，而是只做了一半。

比如前端隐藏了删除按钮，但直接请求删除接口仍然成功。

这种问题必须在第四天被发现并修掉。

### 课堂产出

```md
# JeecgBoot 工单权限落地检查表

| 检查项 | 文件/配置位置 | 当前结果 | 问题 | 修复建议 | 验收 |
|---|---|---|---|---|---|
| 菜单权限字符 |  |  |  |  | 菜单权限与按钮权限一致 |
| 新增按钮权限 |  |  |  |  | 无权限用户不可见 |
| 删除接口权限 |  |  |  |  | 无权限请求返回 403 |
| 指派接口权限 |  |  |  |  | 研发账号不可指派 |
| 状态流转接口权限 |  |  |  |  | 非法角色不能流转 |
| 列表数据范围 |  |  |  |  | 不同角色只能看到授权数据 |
```

---

## Slide 2-6：权限代码修改 Prompt

### PPT 页面内容

```Plain Text
修改前必须给 TRAE：

RBAC 权限矩阵
权限控制方案表
实际文件路径
不做什么
验收命令或验收动作
```

### 讲师逐字稿

到这里才进入代码修改。

如果直接说“帮我补权限”，AI 容易把范围扩大，甚至改到无关模块。

更稳的方式是把权限矩阵、权限控制方案、实际文件路径、禁止事项和验收动作一次性给清楚。

比如只允许它修改工单模块，不允许改全局登录逻辑，不允许改角色模型，不允许删除现有权限字符。

这样 AI 的修改就会收敛。

### 推荐 Prompt

```md
请基于以下材料补齐 JeecgBoot 工单模块权限控制。

输入材料：
1. 工单 RBAC 权限矩阵
2. 工单权限控制方案表
3. 当前工单前端页面、api 文件、后端 Controller、Service 文件路径
4. 当前项目 rules

修改范围：
- 只修改工单模块相关文件
- 不修改登录认证
- 不修改全局角色模型
- 不删除已有权限字符

要求：
1. 前端按钮只做显示控制。
2. 后端敏感接口必须有权限校验。
3. 列表查询要说明数据范围策略。
4. 输出修改文件清单。
5. 输出无权限访问验收步骤。

验收：
管理员可以删除；研发账号不能看到删除按钮；研发账号直接请求删除接口被拒绝。
```

---

## Slide 2-7：rules 要落到这些位置

### PPT 页面内容

```Plain Text
rule 不是单独文件

要落到：
菜单配置
按钮权限
Controller
Service 查询
审计展示
验收记录
```

### 讲师逐字稿

很多团队写了 rules，但代码生成时没有真正用上。

第四天要强调：让 TRAE 改权限前，必须同时给它当前项目 rules、权限矩阵、权限控制方案和实际文件路径。

比如“四层校验”这条 rule，就要落到菜单配置、按钮权限、Controller、Service 查询和验收记录。

“权限字符有来源”这条 rule，要落到菜单表、路由、按钮指令和后端注解。

“数据权限不得被查询条件替代”这条 rule，要落到列表、详情、导出和看板查询。

这样 rule 才不是口号，而是代码修改和 Review 的检查依据。

### 课堂产出

```md
| rule 条款 | 代码落点 | 课堂验收 |
|---|---|---|
| 四层校验 | 菜单配置、按钮权限、Controller、Service 查询 | 无权限账号不可见且接口失败 |
| 权限字符有来源 | 菜单表、路由、按钮指令、后端注解 | 同一字符贯穿前后端 |
| 数据权限后端校验 | 列表、详情、导出、看板查询 | 改请求参数不能越权 |
| 敏感字段最小返回 | 列表接口、详情接口、审计展示 | 不暴露不必要 old/new value |
```

---

# 模块 3：工单状态流转规则实现

---

## Slide 3-1：状态流转不能靠临时 if else

### PPT 页面内容

```Plain Text
工单状态：

已创建
处理中
待验证
已关闭
已驳回

状态流转必须先设计状态机
再实现代码
```

### 讲师逐字稿

工单状态流转是第四天的核心复杂业务。

很多系统一开始用几个 if else 写状态判断，后面状态越来越多，角色越来越多，异常越来越多，最后没人敢改。

所以今天不直接写状态流转代码。

先让 TRAE 帮我们生成状态机设计。

状态机要回答：当前状态是什么，允许什么动作，动作后进入什么状态，谁可以执行，前置条件是什么，非法流转怎么处理。

---

## Slide 3-2：状态枚举设计

### PPT 页面内容

```Plain Text
created：已创建
processing：处理中
pending_verify：待验证
closed：已关闭
rejected：已驳回
```

### 讲师逐字稿

课堂里我们先使用五个状态。

`created` 表示工单刚创建，还没有进入处理。

`processing` 表示已经被指派或开始处理。

`pending_verify` 表示研发处理完成，等待测试或负责人验证。

`closed` 表示已经关闭。

`rejected` 表示验证不通过，被驳回。

状态值要稳定，中文名可以展示，代码里要使用明确枚举或字典，不要到处写魔法字符串。

---

## Slide 3-3：状态流转表

### PPT 页面内容

```Plain Text
状态流转表包含：

当前状态
允许动作
目标状态
允许角色
前置条件
失败提示
```

### 讲师逐字稿

状态流转表是状态机的核心。

比如从 `created` 到 `processing`，动作是指派，允许角色是管理员或负责人，前置条件是必须有指派人。

从 `processing` 到 `pending_verify`，动作是提交验证，通常由研发执行，前置条件是必须填写处理说明。

从 `pending_verify` 到 `closed`，动作是关闭，由测试或负责人执行。

从 `pending_verify` 到 `rejected`，动作是驳回，必须填写驳回原因。

这些规则如果不先写清楚，代码很容易实现错。

### 课堂产出

```md
# 工单状态流转表

| 当前状态 | 允许动作 | 目标状态 | 允许角色 | 前置条件 | 失败提示 |
|---|---|---|---|---|---|
| created | 指派 | processing | 管理员/负责人 | 必须选择指派人 | 请选择指派人 |
| processing | 提交验证 | pending_verify | 研发/负责人 | 必须填写处理说明 | 请填写处理说明 |
| pending_verify | 关闭 | closed | 测试/负责人 | 验证通过 | 当前工单不可关闭 |
| pending_verify | 驳回 | rejected | 测试/负责人 | 必须填写驳回原因 | 请填写驳回原因 |
| rejected | 重新处理 | processing | 研发/负责人 | 必须填写处理说明 | 请填写重新处理说明 |
```

---

## Slide 3-4：非法流转清单

### PPT 页面内容

```Plain Text
非法流转也要设计：

closed -> processing
created -> closed
processing -> rejected
无权限状态变更
缺少必要说明
```

### 讲师逐字稿

很多团队只设计正常流，不设计非法流。

但真实系统里，非法流转更容易出事故。

比如已关闭工单不能随便重新处理。

刚创建的工单不能直接关闭。

处理中不能直接驳回，因为驳回应该发生在待验证阶段。

无权限用户不能改状态。

提交验证必须有处理说明，驳回必须有驳回原因。

这些都要写进非法流转清单。

### 课堂产出

```md
# 工单非法流转清单

| 当前状态 | 尝试动作 | 问题 | 系统响应 | 验收 |
|---|---|---|---|---|
| closed | 重新处理 | 已关闭工单不允许直接重开 | 返回非法状态流转 | 接口失败且状态不变 |
| created | 关闭 | 未处理工单不能关闭 | 返回非法状态流转 | 页面提示原因 |
| processing | 驳回 | 驳回应发生在待验证阶段 | 返回非法状态流转 | 状态不变 |
| pending_verify | 驳回但无原因 | 缺少必要说明 | 返回参数错误 | 提示填写驳回原因 |
```

---

## Slide 3-5：状态流转 Prompt 模板

### PPT 页面内容

```Plain Text
先生成状态机
再生成代码计划
最后再修改代码
```

### 讲师逐字稿

状态流转一定要分三步。

第一步，让 TRAE 生成状态机设计。

第二步，让 TRAE 基于状态机输出代码修改计划。

第三步，人工确认后再让 TRAE 修改代码。

不要一开始就说“帮我实现状态流转”。

### 推荐 Prompt

```md
请为 JeecgBoot 工单模块设计状态流转规则。

状态：
created、processing、pending_verify、closed、rejected。

要求：
1. 输出状态流转表。
2. 输出非法流转清单。
3. 区分允许角色和前置条件。
4. 给出接口设计建议。
5. 给出测试点。
6. 不要直接修改代码。

输出：
状态流转表 + 非法流转清单 + 接口建议 + 测试点。
```

---

## Slide 3-6：状态流转接口设计

### PPT 页面内容

```Plain Text
建议接口：

POST /workOrder/assign
POST /workOrder/transition

transition 入参：
工单 ID
动作
目标状态
说明
版本号或更新时间
```

### 讲师逐字稿

状态流转不要散落在多个编辑接口里。

建议课堂里把指派和状态流转单独设计成明确接口。

指派接口处理 assignee 变化。

状态流转接口处理提交验证、关闭、驳回、重新处理等动作。

入参至少要包含工单 ID、动作、目标状态、说明。

如果项目里已经有乐观锁、版本号或更新时间字段，也可以带上，避免并发修改覆盖。

这里的关键是：状态变化不是普通编辑，它必须经过状态机校验、角色校验、前置条件校验和审计日志记录。

### 课堂产出

```md
# 工单状态流转接口契约

## 指派接口
POST /workOrder/assign

请求：
| 字段 | 必填 | 含义 |
|---|---|---|
| id | Y | 工单 ID |
| assignee | Y | 新指派人 |
| remark | N | 指派说明 |

验收：
指派成功后状态进入 processing，并写入审计日志。

## 状态流转接口
POST /workOrder/transition

请求：
| 字段 | 必填 | 含义 |
|---|---|---|
| id | Y | 工单 ID |
| action | Y | submit_verify / close / reject / reopen |
| targetStatus | Y | 目标状态 |
| remark | 条件必填 | 处理说明、关闭说明或驳回原因 |
| version | N | 并发控制字段 |

验收：
合法流转成功；非法流转失败；状态不被错误修改；审计日志可查。
```

---

## Slide 3-7：状态流转最小实现计划

### PPT 页面内容

```Plain Text
实现顺序：

先定义枚举
再定义流转表
再写校验函数
再接 Service
最后补接口和测试点
```

### 讲师逐字稿

状态流转代码不要一上来就写很多 if else。

课堂里建议采用最小实现计划。

第一，定义状态和动作枚举，避免魔法字符串。

第二，定义流转表，把 allowed from、action、target、roles、required fields 写清楚。

第三，写校验函数，只负责判断当前状态、动作、角色、前置条件是否合法。

第四，在 Service 里调用校验函数，真正更新状态。

第五，记录审计日志。

第六，补接口和测试点。

这种结构的好处是，后续新增状态或动作时，不需要到处找散落的判断。

### 课堂产出

```md
# 状态流转最小实现计划

## 新增或调整
- WorkOrderStatus：状态枚举或字典
- WorkOrderAction：动作枚举或字典
- WorkOrderTransitionRequest：流转请求
- WorkOrderTransitionRule：流转规则
- WorkOrderService.transition：状态流转入口
- WorkOrderAuditLogService.record：审计日志记录

## 修改原则
1. Controller 只接收请求和返回结果，不写复杂状态判断。
2. Service 负责读取工单、校验权限、校验状态、更新状态、记录日志。
3. 非法流转返回明确业务错误。
4. 状态修改和日志记录要在同一业务事务里完成。

## 验收
- created -> processing 成功
- processing -> pending_verify 成功
- pending_verify -> closed 成功
- closed -> processing 被拒绝
- pending_verify 驳回但无原因被拒绝
```

---

## Slide 3-8：可直接复制到 rules：状态流转

### PPT 页面内容

```Plain Text
状态流转 rules：

复杂业务状态必须先建模
非法状态流转必须拒绝且状态不变

验证重点：
合法路径成功
非法路径失败
状态不被错误修改
失败不写成功审计
```

### 讲师逐字稿

状态流转表不是一次性课堂表格。

它应该沉淀成团队 rules，后续遇到审批、发布、上下架、支付、归档等状态型业务都可以复用。

第一条 rule 是复杂业务状态必须先建模。

也就是先产出状态流转表，再进入代码实现，不能直接在代码里堆 if else。

第二条 rule 是非法状态流转必须拒绝且状态不变。

这条非常关键。非法请求失败后，数据库状态不能被改坏，也不能写一条成功审计。

这类 rules 会直接进入后续 Review 和测试清单。

### 课堂产出

```md
## 复杂业务状态必须先建模
- 级别：硬约束
- 适用场景：工单指派、处理、验证、驳回、关闭、重开。
- 必须：先产出状态流转表，列出当前状态、动作、目标状态、允许角色、前置条件、后置动作和验收方式。
- 禁止：直接在代码中堆状态判断而没有状态表。
- 验收方式：每个状态动作都有合法路径和非法路径验证。

## 非法状态流转必须拒绝且状态不变
- 必须：集中校验非法流转；失败时返回明确错误，业务状态不变，不写成功审计。
- 禁止：仅靠前端禁用按钮防止非法流转。
- 验收方式：构造非法状态动作，接口失败且数据库状态不变。
```

---

# 模块 4：审计日志设计

---

## Slide 4-1：为什么工单必须有审计日志？

### PPT 页面内容

```Plain Text
工单是协作过程

必须回答：
谁操作
什么时候操作
对哪个工单
做了什么动作
字段前后值是什么
操作是否成功
```

### 讲师逐字稿

工单模块不是单人填写表单，而是多人协作过程。

一个工单可能被创建、指派、修改优先级、提交验证、驳回、重新处理、关闭。

如果没有审计日志，出了问题很难追溯。

比如一个高优先级工单被改成低优先级，是谁改的？

指派人从张三变成李四，什么时候改的？

测试驳回时原因是什么？

关闭工单时是否有验证说明？

这些都应该进入审计日志。

---

## Slide 4-2：审计日志字段设计

### PPT 页面内容

```Plain Text
审计日志字段：

工单 ID
操作人
操作动作
字段名
修改前
修改后
操作结果
操作时间
```

### 讲师逐字稿

审计日志不是只记录一句“修改了工单”。

至少要记录工单 ID、操作人、操作动作、字段名、修改前、修改后、操作结果和操作时间。

如果是状态流转，还要记录从什么状态变到什么状态。

如果是指派，要记录原指派人和新指派人。

如果是驳回，要记录驳回原因。

审计日志越结构化，后续越容易查询、展示和分析。

### 课堂产出

```md
# 工单审计日志字段表

| 字段 | 含义 | 示例 |
|---|---|---|
| id | 主键 | 178xxx |
| ticket_id | 工单 ID | WO-001 |
| operator | 操作人 | zhangsan |
| action | 操作动作 | assign / transition / edit |
| field_name | 字段名 | status / assignee / priority |
| before_value | 修改前 | processing |
| after_value | 修改后 | pending_verify |
| result | 操作结果 | success / fail |
| operate_time | 操作时间 | 2026-06-29 10:00 |
| remark | 备注 | 提交验证说明 |
```

---

## Slide 4-3：必须记录的操作

### PPT 页面内容

```Plain Text
必须记录：

新增
编辑
删除
指派
状态变更
优先级变更
驳回
关闭
```

### 讲师逐字稿

不是所有字段都要写很复杂的日志，但敏感动作必须记录。

新增、编辑、删除是基础。

指派是协作关键动作，必须记录。

状态变更是工单生命周期核心，必须记录。

优先级变更会影响处理顺序，也应该记录。

驳回和关闭都影响交付结果，更要记录原因。

课堂上可以让 TRAE 帮我们补充哪些操作必须记录，但最终要由团队确认。

---

## Slide 4-4：审计日志 SOP

### PPT 页面内容

```Plain Text
SOP 要写清：

哪些动作记录
记录哪些字段
在哪里展示
如何查询
如何验收
```

### 讲师逐字稿

审计日志最终要形成 SOP。

不要只写“敏感操作要记录日志”。

要写清哪些动作记录，记录哪些字段，在哪里展示，如何查询，怎么验收。

比如工单详情页展示操作记录；状态变更后必须出现一条审计日志；删除失败也要记录失败结果或至少有系统日志可追踪。

### 课堂产出

```md
# 工单审计日志 SOP

## 必须记录的操作
新增、编辑、删除、指派、状态变更、优先级变更、驳回、关闭。

## 必须记录的字段
操作人、操作时间、工单 ID、动作、字段名、修改前、修改后、结果、备注。

## 展示位置
工单详情页操作记录区域。

## 查询方式
按工单 ID 查询审计日志，按时间倒序展示。

## 验收方式
执行状态变更、指派、驳回、关闭后，工单详情页能看到对应审计记录。
```

---

## Slide 4-5：审计日志表与展示

### PPT 页面内容

```Plain Text
审计日志至少要支持：

按工单 ID 查询
按时间倒序
显示动作和操作者
显示字段前后值
显示失败原因或备注
```

### 讲师逐字稿

审计日志不只是后端写一条记录，还要能被业务人员看见。

工单详情页应该有操作记录区域，按时间倒序展示。

每条记录至少显示操作人、操作时间、动作、字段前后值和备注。

如果是失败操作，可以根据团队要求决定是否进入业务审计日志；但至少要在系统日志里可追踪。

课堂上我们优先要求成功的关键业务动作进入审计日志：指派、状态流转、关闭、驳回、优先级变更。

### 课堂产出

```md
# 工单详情页审计记录展示要求

| 展示字段 | 示例 | 说明 |
|---|---|---|
| 操作时间 | 2026-06-29 10:00 | 按时间倒序 |
| 操作人 | zhangsan | 当前登录用户 |
| 动作 | 提交验证 | 从 action 转换成中文 |
| 变更内容 | status: processing -> pending_verify | 字段前后值 |
| 备注 | 已修复，请验证 | 来自 remark |
| 结果 | success | 成功或失败 |

## 验收
完成一次指派、一次提交验证、一次驳回后，详情页能看到三条不同审计记录。
```

---

## Slide 4-6：审计日志代码修改 Prompt

### PPT 页面内容

```Plain Text
要求 TRAE 同时考虑：

写入时机
字段前后值
事务一致性
详情页展示
查询接口
验收数据
```

### 讲师逐字稿

审计日志的 Prompt 要比普通新增功能更细。

如果只说“加操作日志”，AI 可能只加一个注解，或者只写一句字符串。

我们要明确写入时机、字段前后值、事务一致性、详情页展示、查询接口和验收数据。

尤其是状态流转，状态更新成功但审计日志失败，或者审计日志成功但状态更新失败，都会造成追溯问题。

所以 Service 层最好把状态更新和审计记录放在同一事务边界内。

### 推荐 Prompt

```md
请为 JeecgBoot 工单模块补齐审计日志能力。

输入：
- 工单审计日志 SOP
- 状态流转表
- 指派和状态流转接口契约
- 当前 Controller / Service / Entity / Mapper 文件路径

要求：
1. 新增或复用审计日志模型，记录工单 ID、操作人、动作、字段名、修改前、修改后、结果、时间、备注。
2. 指派、状态流转、驳回、关闭必须记录字段前后值。
3. 状态更新和日志写入要说明事务边界。
4. 工单详情页提供审计记录查询和展示。
5. 输出修改文件清单和验收步骤。

不做：
- 不修改全局登录逻辑。
- 不把敏感信息写入日志。
```

---

## Slide 4-7：可直接复制到 rules：审计日志

### PPT 页面内容

```Plain Text
审计日志 rules：

关键业务操作必须写审计
审计和业务写入必须一致

不能只写：
“记录日志”

必须说明：
字段、时机、事务、失败行为、验收方式
```

### 讲师逐字稿

审计 rules 要比“记录日志”具体得多。

关键业务操作必须写审计，适用于创建、编辑关键字段、指派、状态流转、驳回、关闭、删除、导出、权限变更。

审计字段要包含操作人、动作、目标对象、修改前、修改后、来源、请求 ID 或项目里的等价字段。

第二条 rule 是审计和业务写入必须一致。

如果状态更新成功但审计丢了，后续无法追溯。

如果审计写成功但业务失败，也会产生错误记录。

所以必须说明审计写入时机、事务关系、失败处理和验证方式。

### 课堂产出

```md
## 关键业务操作必须写审计
- 级别：硬约束
- 适用场景：创建、编辑关键字段、指派、状态流转、驳回、关闭、删除、导出、权限变更。
- 必须：记录 actor、action、target_id、old_value、new_value、source、request_id、created_at 或项目等价字段。
- 禁止：只记录普通日志而没有业务审计；操作失败后写成功审计。
- 验收方式：执行关键操作后可查询审计记录，字段与实际变更一致。

## 审计和业务写入必须一致
- 必须：明确审计写入时机、事务关系、失败处理和重试策略。
- 禁止：业务成功审计丢失，或审计成功但业务失败。
- 验收方式：模拟业务失败和审计失败，结果符合一致性策略。
```

---

# 模块 5：异常态与防御性逻辑

---

## Slide 5-1：复杂业务不能只测正常流

### PPT 页面内容

```Plain Text
必须覆盖：

空数据
接口失败
权限不足
重复提交
非法状态流转
不存在的工单 ID
并发修改
```

### 讲师逐字稿

第三天我们验证了基础页面能打开、列表能查询、详情能展示。

第四天要进一步补异常态和防御性逻辑。

真实系统里，问题往往不在正常流，而在异常流。

比如列表没有数据时页面是否友好？

接口失败时页面会不会崩？

无权限操作是否返回 403？

用户连续点击提交，会不会创建两条状态变更记录？

已关闭工单再次提交验证，会不会被拒绝？

传入不存在的工单 ID，接口如何响应？

这些都要设计。

---

## Slide 5-2：异常态清单

### PPT 页面内容

```Plain Text
异常态要写成表：

场景
触发条件
系统表现
后端响应
验收方式
```

### 讲师逐字稿

异常态不是一句“做好异常处理”。

要写成清单。

每个场景写清楚触发条件、系统表现、后端响应和验收方式。

前端和后端都要看。

比如权限不足，前端按钮应该不可见，但后端接口也必须返回 403。

比如重复提交，前端可以禁用按钮，后端也应该避免重复状态变更。

### 课堂产出

```md
# 工单异常态与防御性逻辑清单

| 场景 | 触发条件 | 前端表现 | 后端响应 | 验收 |
|---|---|---|---|---|
| 空列表 | 查询无结果 | 显示空状态 | 返回空数组 | 不显示报错 |
| 接口失败 | 服务异常 | 提示重试 | 5xx 或业务错误 | 页面不崩溃 |
| 权限不足 | 无权限操作 | 按钮不可见或提示无权限 | 403 | 不完成操作 |
| 重复提交 | 连续点击提交 | 按钮禁用或 loading | 拒绝重复请求 | 只生成一条记录 |
| 非法流转 | closed -> processing | 提示非法状态 | 业务错误码 | 状态不变 |
| 工单不存在 | 传入错误 ID | 显示不存在 | 404 或业务错误 | 页面不崩溃 |
```

---

## Slide 5-3：防重复提交

### PPT 页面内容

```Plain Text
防重复提交：

前端 loading / 禁用按钮
后端幂等或状态校验
审计日志不重复
用户可理解提示
```

### 讲师逐字稿

防重复提交是工单状态流转里很现实的问题。

比如用户点击“提交验证”，网络慢，又点了一次。

如果系统没有防护，可能产生两条操作记录，甚至触发两次状态变更。

前端可以通过 loading 和禁用按钮减少重复点击。

后端必须通过状态校验或幂等逻辑保证重复请求不会造成错误结果。

审计日志也要避免重复写入无意义记录。

---

## Slide 5-4：异常态 Prompt 模板

### PPT 页面内容

```Plain Text
让 TRAE 先列异常态
再给处理建议
最后给测试点
```

### 讲师逐字稿

异常态可以让 TRAE 辅助补齐。

但要注意顺序。

先让 TRAE 列异常态，不要直接改代码。

再让 TRAE 给处理建议。

最后让 TRAE 生成测试点。

### 推荐 Prompt

```md
请基于 JeecgBoot 工单模块，列出状态流转、指派、删除、查询详情相关的异常态和防御性逻辑。

要求：
1. 覆盖空数据、接口失败、权限不足、重复提交、非法状态流转、工单不存在。
2. 区分前端表现和后端响应。
3. 给出验收方式。
4. 给出测试点。
5. 不要直接修改代码。

输出：
异常态清单 + 防御性逻辑建议 + 测试点。
```

---

## Slide 5-5：异常态最小测试集

### PPT 页面内容

```Plain Text
最小测试集：

无权限删除
非法状态流转
重复提交验证
不存在的工单 ID
驳回缺少原因
看板无数据
```

### 讲师逐字稿

异常态很多，课堂时间有限，所以要有最小测试集。

第四天至少覆盖六类。

第一，无权限删除。前端不显示按钮，后端接口也拒绝。

第二，非法状态流转。比如 closed 工单不能直接重新处理。

第三，重复提交验证。连续点击或重复请求不能产生两次有效状态变更。

第四，不存在的工单 ID。接口要返回明确错误，页面不能崩。

第五，驳回缺少原因。系统应该拒绝，并提示必须填写驳回原因。

第六，看板无数据。页面应该显示空状态，而不是显示 NaN 或报错。

这六类测试能覆盖权限、状态、参数、并发、页面异常和统计口径。

### 课堂产出

```md
# 第四天异常态最小测试集

| 编号 | 场景 | 操作 | 预期结果 | 证据 |
|---|---|---|---|---|
| E01 | 无权限删除 | 研发账号请求删除接口 | 返回 403 或业务拒绝 | 接口响应截图/日志 |
| E02 | 非法状态流转 | closed -> processing | 返回非法流转，状态不变 | 数据库或详情页状态 |
| E03 | 重复提交验证 | 连续点击提交验证 | 只成功一次，只写一条有效审计 | 审计日志 |
| E04 | 工单不存在 | 查询错误 ID | 返回不存在，页面不崩 | 页面截图/响应 |
| E05 | 驳回缺少原因 | pending_verify 驳回但 remark 为空 | 返回参数错误 | 提示信息 |
| E06 | 看板无数据 | 清空筛选条件或无数据范围 | 显示空状态 | 页面截图 |
```

---

## Slide 5-6：防御性代码修改边界

### PPT 页面内容

```Plain Text
防御性修改边界：

前端补状态和提示
后端补校验和错误码
Service 保证状态不变
审计日志避免重复
不引入无关重构
```

### 讲师逐字稿

异常态修复很容易扩散。

比如处理重复提交，AI 可能想引入新的全局请求库、全局锁机制，甚至改很多无关页面。

课堂里要控制边界。

前端主要补 loading、禁用按钮、空状态、错误提示。

后端主要补参数校验、权限校验、状态校验和明确错误码。

Service 要保证失败时状态不变。

审计日志要避免重复写入无意义记录。

不要为了一个工单模块异常态，把整个项目请求封装重写一遍。

### 推荐 Prompt

```md
请基于第四天异常态最小测试集，补齐 JeecgBoot 工单模块防御性逻辑。

修改范围：
- 工单列表、详情、状态流转相关前端页面
- 工单 api
- 工单 Controller / Service
- 工单审计日志写入逻辑

要求：
1. 前端补 loading、禁用按钮、空状态、错误提示。
2. 后端补参数校验、权限校验、状态校验。
3. 非法操作失败后工单状态不能改变。
4. 重复提交不能产生重复有效审计记录。
5. 输出每个异常态的验收步骤。

不做：
- 不重写全局请求库。
- 不修改无关业务模块。
- 不改变既有角色模型。
```

---

## Slide 5-7：可直接复制到 rules：异常态测试

### PPT 页面内容

```Plain Text
测试 rules：

核心逻辑必须有测试或豁免说明
权限必须做正反角色验证
状态流转必须覆盖合法和非法路径

禁止：
只用管理员账号验证
只说“已验证”
只跑正常主链路
```

### 讲师逐字稿

异常态模块最后要沉淀成测试 rules。

第一，核心逻辑必须有测试或豁免说明。

如果没法写自动化测试，也要写清手工验收步骤、证据和剩余风险，不能只说“已验证”。

第二，权限必须做正反角色验证。

至少一个授权角色、一个未授权角色；如果涉及数据范围，还要验证越权数据。

第三，状态流转必须覆盖合法和非法路径。

不能只测从创建到关闭的成功链路，也要构造 closed 重新处理、pending_verify 驳回无原因这类失败路径。

### 课堂产出

```md
## 核心逻辑必须有测试或豁免说明
- 级别：待确认约束
- 适用场景：权限校验、状态流转、审计、看板指标、异常态修复。
- 必须：优先补自动化测试；无法测试时说明原因、风险和手工验收方式。
- 禁止：只说“已验证”但没有命令、样例、截图、接口响应或手工步骤。

## 权限必须做正反角色验证
- 必须：至少验证一个授权角色和一个未授权角色；涉及数据范围时验证越权数据。
- 禁止：只用管理员账号验证。

## 状态流转必须覆盖合法和非法路径
- 必须：每个关键动作至少覆盖一条合法路径和一条非法路径。
- 禁止：只测试从初始状态到成功终态的主链路。
```

---

# 模块 6：研发效能看板指标开发

---

## Slide 6-1：看板不是图表堆叠

### PPT 页面内容

```Plain Text
研发效能看板关注：

工单数量
待处理数量
关闭周期
优先级分布
状态分布
趋势变化
```

### 讲师逐字稿

第四天最后一个业务模块是研发效能看板。

这里要强调：看板不是图表堆叠。

不要为了做图而做图。

看板的核心是指标口径。

工单总数怎么算？待处理数量包含哪些状态？关闭周期从哪个时间算到哪个时间？驳回后重新处理怎么算？优先级分布按当前优先级还是历史优先级？

这些问题不清楚，图表再漂亮也没有意义。

---

## Slide 6-2：指标字典

### PPT 页面内容

```Plain Text
每个指标必须定义：

指标名
含义
计算口径
数据来源
刷新频率
展示方式
```

### 讲师逐字稿

效能看板必须先做指标字典。

每个指标要写清指标名、含义、计算口径、数据来源、刷新频率和展示方式。

比如“平均关闭周期”，它到底是创建时间到关闭时间，还是处理中到关闭时间？

如果工单被驳回又重新处理，要不要扣除等待时间？

课堂里我们先用简化口径：创建时间到关闭时间。

但一定要写清楚，不能让 AI 自己猜。

### 课堂产出

```md
# 工单研发效能看板指标字典

| 指标 | 含义 | 计算口径 | 数据来源 | 展示 |
|---|---|---|---|---|
| 工单总数 | 当前工单总量 | count(*) | work_order | 数字卡片 |
| 待处理数量 | created + processing | 按状态统计 | work_order.status | 数字卡片 |
| 已关闭数量 | closed 数量 | 按状态统计 | work_order.status | 数字卡片 |
| 平均关闭周期 | 创建到关闭平均耗时 | avg(close_time - create_time) | work_order | 数字卡片 |
| 优先级分布 | 各优先级数量 | group by priority | work_order.priority | 饼图 |
| 状态趋势 | 每日新增/关闭 | 按日期聚合 | work_order | 折线图 |
```

---

## Slide 6-3：看板页面设计

### PPT 页面内容

```Plain Text
建议组成：

顶部指标卡
状态分布
优先级分布
趋势图
异常列表
```

### 讲师逐字稿

看板页面可以保持克制。

顶部是几个数字卡片，比如工单总数、待处理数量、已关闭数量、平均关闭周期。

中间可以放状态分布和优先级分布。

下面放趋势图，比如每日新增和每日关闭。

如果还有空间，可以放异常列表，比如超期未处理工单、高优先级未关闭工单。

注意，第四天不是专门做 BI 平台，不要把看板做得过大。

---

## Slide 6-4：看板 Prompt 模板

### PPT 页面内容

```Plain Text
先定义指标
再设计接口
再设计页面
最后验证口径
```

### 讲师逐字稿

让 TRAE 做看板时，顺序很重要。

不要直接说“帮我做个好看的看板”。

先定义指标，再设计接口，再设计页面，最后验证口径。

### 推荐 Prompt

```md
请基于 JeecgBoot 工单模块设计研发效能看板。

要求：
1. 先输出指标字典。
2. 再输出后端统计接口建议。
3. 再输出前端页面结构。
4. 每个指标必须说明计算口径和数据来源。
5. 不要直接生成代码。

输出：
指标字典 + 接口设计 + 页面结构 + 验收方式。
```

---

## Slide 6-5：看板统计接口契约

### PPT 页面内容

```Plain Text
建议接口：

GET /workOrder/dashboard/summary
GET /workOrder/dashboard/status
GET /workOrder/dashboard/priority
GET /workOrder/dashboard/trend

每个接口必须说明：
筛选条件、数据范围、统计口径
```

### 讲师逐字稿

看板不要只做前端假数据。

课堂里至少要设计后端统计接口契约。

可以把接口拆成 summary、status、priority、trend 四类。

summary 返回总量、待处理、已关闭、平均关闭周期。

status 返回状态分布。

priority 返回优先级分布。

trend 返回每日新增和每日关闭趋势。

每个接口都要说明筛选条件和数据范围。

比如负责人看到团队数据，管理员看到全量数据，研发普通账号如果没有看板权限就不能访问。

### 课堂产出

```md
# 工单看板统计接口契约

## GET /workOrder/dashboard/summary

查询参数：
| 字段 | 含义 |
|---|---|
| startDate | 开始日期 |
| endDate | 结束日期 |
| teamId | 团队 ID，可选 |

返回：
| 字段 | 含义 | 口径 |
|---|---|---|
| totalCount | 工单总数 | 时间范围内创建的工单 |
| pendingCount | 待处理数量 | created + processing |
| closedCount | 已关闭数量 | status = closed |
| avgCloseHours | 平均关闭周期 | close_time - create_time |

## GET /workOrder/dashboard/trend

返回：
| 字段 | 含义 |
|---|---|
| date | 日期 |
| createdCount | 当日新增 |
| closedCount | 当日关闭 |

验收：
同一时间范围下，summary 与 status/trend 聚合结果不互相矛盾。
```

---

## Slide 6-6：看板页面验收

### PPT 页面内容

```Plain Text
看板验收看四件事：

权限是否正确
口径是否清楚
空态是否可用
数字是否能解释
```

### 讲师逐字稿

看板页面不是能打开就算完成。

验收时看四件事。

第一，权限是否正确。没有 `work:order:dashboard` 权限的用户不能访问看板接口。

第二，口径是否清楚。每个数字都能回到指标字典。

第三，空态是否可用。没有数据时不能显示 NaN、undefined 或空白图。

第四，数字是否能解释。比如总数、状态分布、趋势数量之间不能明显矛盾。

如果一个看板数字说不清从哪里来，它就不能用于管理判断。

### 课堂产出

```md
# 工单看板验收记录

| 验收项 | 账号/条件 | 预期 | 实际 | 证据 |
|---|---|---|---|---|
| 看板权限 | 只读用户 | 不可访问或无菜单 |  |  |
| Summary 指标 | 管理员 + 本月 | 口径符合指标字典 |  |  |
| 状态分布 | 管理员 + 本月 | 与列表筛选统计一致 |  |  |
| 趋势图 | 管理员 + 本月 | 新增/关闭按日期展示 |  |  |
| 空数据 | 无数据筛选条件 | 显示空态，不报错 |  |  |
```

---

## Slide 6-7：可直接复制到 rules：看板指标

### PPT 页面内容

```Plain Text
看板指标 rule：

看板指标必须手工抽样校验

必须有：
含义、公式、过滤条件
时间字段、数据范围、样例数据

禁止：
只验证接口 200
只验证页面有图表
```

### 讲师逐字稿

看板最容易出现“页面很漂亮，但数字说不清”的问题。

所以看板指标也要写成 rules。

每个关键指标必须有含义、公式、过滤条件、时间字段、数据范围，并且用样例数据手工校验。

比如平均关闭周期，至少要拿三条样例工单，人工算一次，再和接口返回对上。

接口返回 200 不代表指标正确，页面有图表也不代表指标可信。

课堂交付时，看板必须同时交付指标字典、接口契约和至少一组手工核对样例。

### 课堂产出

```md
## 看板指标必须手工抽样校验
- 级别：硬约束
- 适用场景：统计卡片、趋势图、分布图、排行、效能指标。
- 必须：每个关键指标有含义、公式、过滤条件、时间字段、数据范围，并用样例数据手工校验。
- 禁止：只验证接口返回 200 或页面有图表。
- 来源证据：指标字典、接口契约、样例数据、数据库查询或列表数据。
- 验收方式：至少一组样例数据的手工计算结果与接口返回一致。
```

---

# 模块 7：阶段代码审查与修复

---

## Slide 7-1：第四天必须做阶段 Review

### PPT 页面内容

```Plain Text
Review 重点：

权限是否闭环
状态流转是否完整
审计日志是否可查
异常态是否覆盖
看板口径是否清楚
测试是否覆盖关键路径
```

### 讲师逐字稿

第四天最后必须做一次阶段 Review。

因为今天改动涉及权限、状态流转、审计日志和看板。

这些不是页面样式问题，而是业务风险问题。

Review 的重点不是格式，也不是变量名，而是业务闭环。

权限有没有前后端闭环？

状态流转有没有非法路径？

审计日志能不能查到字段前后值？

异常态有没有覆盖？

看板指标口径是否清楚？

测试是否覆盖关键路径？

---

## Slide 7-2：AI Review 输入

### PPT 页面内容

```Plain Text
输入材料：

当天 diff
工单 RBAC 权限矩阵
状态流转表
审计日志 SOP
异常态清单
看板指标字典
测试结果
```

### 讲师逐字稿

AI Review 不能只给 diff。

如果只给 diff，AI 只能看代码变化，很难判断业务规则是否正确。

要把今天的关键产物都作为 Review 输入。

包括 RBAC 权限矩阵、状态流转表、审计日志 SOP、异常态清单、看板指标字典和测试结果。

这些材料就是 Review 的依据。

---

## Slide 7-2A：第 4 天要用的三个 Skill

### PPT 页面内容

```Plain Text
三个 Skill：

design-complex-business-module
开工前设计控制面

review-business-delivery
阶段 Review 检查风险

track-review-fix-loop
修复后闭环并沉淀资产
```

### 讲师逐字稿

前三天已经讲过 Skill 的概念。

第四天要让大家看到具体怎么用。

第一个 Skill 是 `design-complex-business-module`，用在开始写代码前，先设计权限、状态、审计、异常态和看板指标。

第二个 Skill 是 `review-business-delivery`，用在阶段 Review 时，检查权限缺口、非法状态流转、审计缺失、异常处理薄弱、看板口径不清和测试缺失。

第三个 Skill 是 `track-review-fix-loop`，用在修复 Review 问题后，把问题状态、修改文件、验证证据和资产沉淀记录下来。

Skill 负责流程和质量门禁；rule 负责长期约束；template 和 checklist 负责稳定输出。

### 课堂产出

```md
| Skill | 什么时候用 | 输入材料 | 输出产物 |
|---|---|---|---|
| design-complex-business-module | 开始写代码前 | 需求、项目规则、现有角色/API/表结构 | RBAC、权限方案、状态表、审计 SOP、异常清单、指标字典 |
| review-business-delivery | 阶段 Review 时 | diff、业务产物、测试结果、验收记录 | 问题清单、证据缺口、待确认项 |
| track-review-fix-loop | 修 Review 后 | Review 报告、修改文件、验证证据 | 修复记录、未闭环事项、资产更新建议 |
```

---

## Slide 7-2B：design-complex-business-module 怎么用

### PPT 页面内容

```Plain Text
用于开工前：

先设计控制面
再进入代码实现

输出：
RBAC、权限方案、状态表、非法流转、
审计 SOP、异常清单、指标字典、接口验收记录
```

### 讲师逐字稿

`design-complex-business-module` 的核心原则是：先设计控制面，再设计代码。

它不是让 AI 直接写实现，而是先把复杂业务应该有的控制资产产出。

课堂里可以把工单需求、项目规则、现有角色、菜单权限、接口、数据表和相似模块作为输入。

如果缺少源码或配置证据，输出必须标记为“建议”或“待确认”，不能让 AI 把推断当成事实。

### 推荐 Prompt

```md
请使用 design-complex-business-module，基于 JeecgBoot 工单模块设计复杂业务控制面。

输入材料：
1. 需求范围：工单权限、状态流转、审计、异常态、看板。
2. 项目规则：security-permission、state-audit、testing、delivery。
3. 现有证据：角色、菜单权限、接口、数据表、相似模块。

输出必须包含：
RBAC 权限矩阵、权限控制方案、状态流转表、非法流转清单、
审计日志 SOP、异常态清单、看板指标字典、看板接口验收记录。

要求：
没有源码或配置证据的内容标记为“建议”或“待确认”。
```

---

## Slide 7-3：阶段 Review 报告模板

### PPT 页面内容

```Plain Text
Review 输出必须包含：

问题等级
模块
问题
触发规则
风险
修复建议
验收方式
```

### 讲师逐字稿

Review 输出必须结构化。

不能只说“建议加强权限”。

要写清问题等级、模块、问题、触发规则、风险、修复建议和验收方式。

比如删除接口只隐藏前端按钮，后端没有权限校验，这就是 P1。

比如审计日志记录了状态变更，但没有记录前后值，这可能是 P2。

比如看板指标没有说明统计口径，这也是 Review 问题。

### 课堂产出

```md
# 第四天阶段 Review 报告

| 等级 | 模块 | 问题 | 触发规则 | 风险 | 修复建议 | 验收 |
|---|---|---|---|---|---|---|
| P1 | 权限 | 删除接口只隐藏按钮，后端缺少权限校验 | 前端按钮不是安全边界 | 可绕过前端删除工单 | 后端补权限注解 | 无权限账号请求返回 403 |
| P1 | 状态流转 | closed 工单仍可重新处理 | 非法流转必须拒绝 | 关闭状态失效 | 禁止 closed -> processing | 接口返回非法状态 |
| P2 | 审计 | 指派未记录前后值 | 敏感操作必须可追溯 | 难以追踪责任 | 记录 old/new assignee | 详情页日志可查 |
| P2 | 看板 | 平均关闭周期口径不清 | 指标必须有口径 | 管理判断失真 | 明确 create_time 到 close_time | 指标字典更新 |
```

---

## Slide 7-3A：review-business-delivery 怎么用

### PPT 页面内容

```Plain Text
用于阶段 Review：

输入不能只有 diff

必须同时给：
业务产物
测试结果
验收记录
项目 rules

输出问题优先，按 P0/P1/P2/P3 排序
```

### 讲师逐字稿

`review-business-delivery` 的作用是防止 AI Review 只做代码风格点评。

第四天 Review 的对象是业务交付，不只是代码 diff。

所以输入材料必须包括当天 diff、RBAC 矩阵、权限控制方案、状态流转表、非法流转清单、审计 SOP、异常态清单、看板指标字典和测试结果。

输出要问题优先，按 P0/P1/P2/P3 排序。

每个问题必须有证据、风险、修复建议和验收方式。

如果缺少证据，就列到“证据缺口”，不能让 AI 猜。

### 推荐 Prompt

```md
请使用 review-business-delivery 对第四天工单模块交付做阶段 Review。

输入材料：
- 当天 diff 或修改文件清单
- RBAC 权限矩阵和权限控制方案
- 状态流转表和非法流转清单
- 审计日志 SOP 和异常态清单
- 看板指标字典和接口验收记录
- 测试命令、接口响应、浏览器验证或手工验收记录

输出格式：
先列问题清单，按 P0/P1/P2/P3 排序；
每个问题必须有证据、风险、修复建议和验收方式；
缺少证据时单独列“证据缺口”，不要猜测。
```

---

## Slide 7-4：修复闭环

### PPT 页面内容

```Plain Text
Review 后必须闭环：

确认问题
生成修复计划
最小修改
运行验证
更新资产
```

### 讲师逐字稿

Review 不是结束，而是修复闭环的开始。

对于 AI Review 提出的每个问题，先确认它是否成立。

成立的问题，再让 TRAE 生成修复计划。

修复时要坚持最小修改，不要借机重构无关代码。

修复后运行验证。

如果这个问题有复用价值，比如“状态流转必须有非法路径测试”，就更新到团队资产库。

---

## Slide 7-5：修复记录模板

### PPT 页面内容

```Plain Text
修复记录必须包含：

Review 问题
是否成立
修改文件
修改说明
验证结果
是否沉淀资产
```

### 讲师逐字稿

第四天最后的产物里要有修复记录。

因为 Review 只发现问题还不够，必须看到问题是否闭环。

每条 Review 问题都要先判断是否成立。

成立的问题记录修改文件和修改说明。

不成立的问题也要说明原因，避免把 AI 的错误判断当成真实问题。

修复后记录验证结果。

如果这个问题有复用价值，就沉淀到资产库，比如权限上线前检查清单、状态流转检查清单、审计日志检查清单。

### 课堂产出

```md
# 第四天修复记录

| Review 编号 | 问题 | 是否成立 | 修改文件 | 修改说明 | 验证结果 | 资产沉淀 |
|---|---|---|---|---|---|---|
| R01 | 删除接口缺少后端权限校验 | 是 | WorkOrderController | 增加权限校验 | 无权限请求被拒绝 | 权限检查清单 |
| R02 | closed 可重新处理 | 是 | WorkOrderService | 补非法流转校验 | closed -> processing 失败 | 状态流转检查清单 |
| R03 | 看板关闭周期口径不清 | 是 | 指标字典/看板接口 | 明确 create_time 到 close_time | 指标说明已更新 | 看板指标口径清单 |
```

---

## Slide 7-5A：track-review-fix-loop 怎么用

### PPT 页面内容

```Plain Text
用于 Review 修复后：

每个问题只能标记为：
成立-已修复
成立-暂不修复
不成立
需确认
未闭环

没有验证证据不能关闭
```

### 讲师逐字稿

`track-review-fix-loop` 负责把 Review 问题真正闭环。

它要求每个问题不能只写“已修复”。

必须判断问题是否成立，列出修改文件或产物，提供验证证据，说明剩余风险，并判断是否要沉淀成资产。

如果没有验证证据，就不能标记为完成，只能标记为未闭环。

如果问题依赖业务决策，就标记为需确认。

如果问题不成立，也要保留原因和证据，不要直接删除。

### 推荐 Prompt

```md
请使用 track-review-fix-loop，把阶段 Review 问题转成修复闭环记录。

输入材料：
- 带编号的 Review 报告
- 修改文件或产物
- 测试输出、接口响应、浏览器截图或手工验收步骤
- 现有 rules、checklists、prompts、examples、skills 目录

每个问题状态只能是：
成立-已修复 / 成立-暂不修复 / 不成立 / 需确认 / 未闭环

输出必须包含：
修复记录、未闭环事项、资产更新建议。
资产类型从 rule、checklist、prompt、command、skill、example 中选择。
```

---

## Slide 7-6：第四天完整实操链路

### PPT 页面内容

```Plain Text
完整链路：

权限矩阵
权限落地
状态机
状态接口
审计日志
异常测试
看板指标
阶段 Review
修复记录
```

### 讲师逐字稿

到这里，第四天形成一条完整链路。

先有权限矩阵，再有权限落地。

先有状态机，再有状态接口和状态校验。

关键动作必须写审计日志。

异常态必须用最小测试集验证。

看板必须先有指标字典，再有接口和页面。

最后通过阶段 Review 发现问题，再用修复记录闭环。

这条链路就是第四天真正要训练的能力。

不是简单地让 AI 写更多代码，而是让 AI 围绕业务规则、工程约束和验收证据工作。

---

# 第 4 天交付验收

---

## Slide 8-1：最后 30 分钟交付验收会

### PPT 页面内容

```Plain Text
最后 30 分钟：

整理权限矩阵
整理状态机
整理审计日志 SOP
整理异常态清单
整理看板指标与接口验收
完成阶段 Review
补齐修复记录
```

### 讲师逐字稿

第四天最后 30 分钟仍然要做交付验收会。

每组整理今天的关键产物。

重点不是谁做的页面更完整，而是谁的业务规则更清楚、验收方式更可执行。

课堂上可以让小组互评。

互评时不要泛泛说“不错”，要检查权限矩阵是否覆盖敏感操作，状态机是否有非法流转，审计日志是否有字段前后值，异常态是否覆盖关键风险，看板指标是否有口径。

### 课堂安排

```md
| 时间 | 动作 | 输出 |
|---|---|---|
| 6 分钟 | 整理 RBAC 与权限方案 | 权限矩阵 + 权限控制方案 |
| 6 分钟 | 整理状态流转 | 状态流转表 + 非法流转清单 |
| 5 分钟 | 整理审计日志 | 审计日志 SOP |
| 5 分钟 | 整理异常态与看板 | 异常态清单 + 指标字典 + 看板接口验收 |
| 5 分钟 | TRAE 阶段 Review | Review 报告 |
| 3 分钟 | 补齐修复记录与资产候选 | 修复记录 + 候选资产 |
```

---

## Slide 8-2：第 4 天交付物

### PPT 页面内容

```Plain Text
第 4 天交付物：

01 工单 RBAC 权限矩阵
02 工单权限控制方案
03 工单状态流转表
04 非法流转清单
05 工单审计日志 SOP
06 异常态与防御性逻辑清单
07 研发效能看板指标字典
08 看板统计接口契约与验收记录
09 阶段 Review 报告
10 修复记录
```

### 讲师逐字稿

第四天最终交付十个产物。

第一，工单 RBAC 权限矩阵。

第二，工单权限控制方案。

第三，工单状态流转表。

第四，非法流转清单。

第五，工单审计日志 SOP。

第六，异常态与防御性逻辑清单。

第七，研发效能看板指标字典。

第八，看板统计接口契约与验收记录。

第九，阶段 Review 报告。

第十，修复记录。

这些产物共同说明：工单模块不只是能运行，还具备权限、状态、审计、异常和指标的工程闭环。

---

## Slide 8-2A：第 4 天资产包目录

### PPT 页面内容

```Plain Text
第 4 天资产包：

rules
skills
templates
checklists
prompts
examples

交付给团队的不是聊天记录
而是可复用工程资产包
```

### 讲师逐字稿

第四天最后要让学员看到：课堂产物不是聊天记录。

真正交付给团队的，是一套可安装、可复用、可审查的工程资产包。

rules 是长期约束，比如权限四层校验、状态先建模、审计一致性、看板手工抽样。

skills 是可触发流程，比如复杂业务设计、阶段 Review、修复闭环。

templates、checklists、prompts 和 examples 是 Skill 运行时会用到的材料。

这样团队下次做审批、报销、发布、合同、库存这些复杂业务模块时，就不需要重新从聊天记录里找经验。

### 课堂产出

```text
ai-dev-assets/
├── rules/
│   ├── security-permission.md
│   ├── state-audit.md
│   ├── testing.md
│   └── delivery.md
├── skills/
│   ├── design-complex-business-module/
│   ├── review-business-delivery/
│   └── track-review-fix-loop/
├── templates/jeecgboot/
├── checklists/jeecgboot/
├── prompts/jeecgboot/
└── examples/jeecgboot/
```

---

## Slide 8-3：交付物验收标准

### PPT 页面内容

```Plain Text
验收标准：

权限可验证
状态可约束
日志可追溯
异常可处理
指标可解释
Review 可闭环
```

### 讲师逐字稿

第四天交付物要有明确验收标准。

权限可验证：无权限账号能被前端和后端同时拦住。

状态可约束：非法状态流转会被拒绝，并且状态不变。

日志可追溯：关键操作能看到操作人、时间、动作和字段前后值。

异常可处理：空数据、接口失败、权限不足、重复提交都有处理。

指标可解释：看板每个指标都有口径和数据来源。

Review 可闭环：Review 问题有等级、有建议、有验证结果。

### 验收表

```md
| 交付物 | 通过标准 |
|---|---|
| RBAC 权限矩阵 | 覆盖角色、功能点、允许/禁止/条件允许 |
| 权限控制方案 | 覆盖菜单、按钮、接口、数据权限和验收 |
| 状态流转表 | 有当前状态、动作、目标状态、角色、前置条件 |
| 非法流转清单 | 覆盖关闭后重开、越权流转、缺少说明等场景 |
| 审计日志 SOP | 明确动作、字段、展示位置、查询方式、验收 |
| 异常态清单 | 覆盖空、错、无权限、重复提交、非法状态 |
| 看板指标字典 | 每个指标有含义、口径、数据来源、展示方式 |
| 看板接口验收记录 | 接口契约、数据范围、空态和权限验证完整 |
| Review 报告 | 有等级、模块、问题、风险、建议、验收 |
| 修复记录 | 每个 Review 问题有成立判断、修改说明和验证结果 |
```

---

## Slide 8-4：第四天课程总结

### PPT 页面内容

```Plain Text
第 3 天：
让工单模块能跑通

第 4 天：
让工单模块能审查、能控制、能上线前验证

核心能力：
复杂业务不是让 AI 多写代码
而是让 AI 按规则、证据和验收标准协作
```

### 讲师逐字稿

第四天结束后，大家应该形成一个关键认识：

复杂业务不是让 AI 多写代码。

复杂业务的关键，是让 AI 按规则、证据和验收标准协作。

权限要有矩阵。

状态要有状态机。

审计要有 SOP。

异常要有清单。

看板要有指标字典。

Review 要有结构化报告和修复闭环。

这就是第四天和第三天的区别。

第三天让工单模块能跑通。

第四天让工单模块能审查、能控制、能上线前验证。

---

# 第 4 天最终资产目录建议

```Plain Text
ai-dev-assets/
├── prompts/jeecgboot/
│   ├── RBAC权限矩阵生成.prompt.md
│   ├── 权限控制方案生成.prompt.md
│   ├── 状态流转设计.prompt.md
│   ├── 异常态补齐.prompt.md
│   ├── 看板指标设计.prompt.md
│   ├── 看板接口验收.prompt.md
│   ├── 阶段Review.prompt.md
│   └── 修复记录生成.prompt.md
├── templates/jeecgboot/
│   ├── RBAC权限矩阵.template.md
│   ├── 权限控制方案.template.md
│   ├── 状态流转表.template.md
│   ├── 审计日志SOP.template.md
│   ├── 异常态清单.template.md
│   ├── 看板指标字典.template.md
│   ├── 看板接口验收记录.template.md
│   ├── 阶段Review报告.template.md
│   └── 修复记录.template.md
├── checklists/jeecgboot/
│   ├── 权限上线前检查清单.md
│   ├── 状态流转检查清单.md
│   ├── 审计日志检查清单.md
│   ├── 异常态检查清单.md
│   ├── 看板指标口径检查清单.md
│   ├── 看板接口验收清单.md
│   └── Review修复闭环检查清单.md
└── examples/jeecgboot/
    ├── 权限遗漏反例.md
    ├── 非法状态流转反例.md
    ├── 审计日志缺失反例.md
    ├── 看板指标口径不清反例.md
    └── Review未闭环反例.md
```

## 讲师收束话术

今天我们没有把 JeecgBoot 工单模块当成一个简单 CRUD 来讲。

我们把它当成一个真实企业后台功能来处理。

真实企业后台的复杂度，往往不在页面字段，而在权限边界、状态规则、审计追溯、异常防御和指标口径。

TRAE 在这里的价值，不是替我们拍脑袋决定业务规则，而是帮助我们把规则结构化，把风险列出来，把验收标准写清楚，把 Review 和修复闭环跑起来。

这就是第四天要带走的能力。