# 学员实操手册

## 实操目标

你要完成一份 JeecgBoot 工单模块设计与交付方案。课堂不要求你把完整代码写出来，但要求你能证明每个设计都有项目依据、业务边界和验收方式。

最终提交内容写入 [worksheets.md](./worksheets.md) 对应表格，并用 [acceptance-checklist.md](./acceptance-checklist.md) 自检。

## 第 1 步：建立项目地图

先阅读 [source-map.md](./source-map.md)，再让 TRAE 根据真实路径输出项目地图。

你需要找出：

- 后端启动入口。
- 后端业务模块组织方式。
- 前端启动入口。
- 前端 API 请求层。
- 动态路由和权限来源。
- 配置文件和运行模式。
- 数据库初始化和迁移位置。

交付物：`源码依据记录表`。

不要问：

```text
帮我看看 JeecgBoot 项目。
```

要问：

```text
请基于我给出的 JeecgBoot 路径，定位后端入口、前端入口、API 请求层、权限路由和配置文件。
输出时必须按“事实依据、推断、建议、不确定点、下一步验证”分组。
```

## 第 2 步：整理工单需求

把工单需求拆成可开发、可测试、可验收的条目。

最小需求范围：

- 工单列表：查询、筛选、分页、排序。
- 工单详情：基础字段、状态、优先级、指派人、评论记录。
- 工单创建和编辑：标题、描述、类型、优先级、负责人。
- 指派和状态流转：从新建到关闭的业务过程。
- 审计日志：记录关键操作。
- 看板：展示数量、周期、缺陷分布和趋势。

交付物：`需求拆解表`。

## 第 3 步：定位源码依据

你不能只写“JeecgBoot 支持权限”。你需要指出从哪里判断。

至少记录：

| 主题 | 最少依据数量 |
| --- | ---: |
| 后端模块结构 | 2 个路径 |
| 前端模块结构 | 2 个路径 |
| 权限和动态路由 | 2 个路径 |
| API 请求层 | 1 个路径 |
| 配置和运行 | 2 个路径 |
| 数据库或迁移 | 1 个路径 |

交付物：`源码依据记录表`。

## 第 4 步：设计接口契约

先设计接口契约，再讨论实现。

至少包含：

- 工单分页列表。
- 工单详情。
- 新增工单。
- 编辑工单。
- 指派负责人。
- 状态流转。
- 查询审计日志。
- 看板指标。

每个接口都要写：

- 请求方法和路径。
- 请求参数。
- 响应字段。
- 权限字符。
- 成功场景。
- 失败场景。
- 验收方式。

交付物：`接口契约表`。

## 第 5 步：设计权限和状态流转

先写角色，再写权限矩阵。

建议角色：

- 管理员。
- 工单负责人。
- 研发处理人。
- 测试验证人。
- 只读观察者。

权限设计要覆盖：

- 页面是否可见。
- 列表是否可查询。
- 按钮是否可操作。
- 后端接口是否允许。
- 数据范围是否受限。

状态设计要覆盖：

- 新建。
- 处理中。
- 待验证。
- 已关闭。
- 已驳回。

必须列出非法流转，例如：

- 已关闭工单不能直接回到处理中，除非有重新打开动作。
- 待验证工单不能由无测试权限的人关闭。
- 非负责人不能指派给他人，除非具备管理权限。

交付物：`RBAC 权限矩阵`、`状态流转表`。

## 第 6 步：补齐审计和异常态

审计日志至少考虑：

- 创建工单。
- 编辑关键字段。
- 指派负责人。
- 状态流转。
- 删除或关闭。
- 评论新增或删除。
- 权限拒绝的重要操作。

异常态至少考虑：

- 接口失败。
- 空数据。
- 权限不足。
- 重复提交。
- 非法状态流转。
- 工单不存在。
- 当前用户不是负责人。
- 并发修改导致数据过期。

交付物：`审计日志设计表`、`异常态清单`。

## 第 7 步：设计看板指标

看板不是画几个卡片，而是定义可计算指标。

至少包含：

- 工单总数。
- 未关闭工单数。
- 平均关闭周期。
- 按优先级分布。
- 按类型分布。
- 缺陷趋势。
- 逾期工单数。
- 人员处理负载。

每个指标都要写清：

- 指标口径。
- 过滤条件。
- 数据来源。
- 展示方式。
- 权限要求。
- 异常态。

交付物：`看板指标表`。

## 第 8 步：做 Review 和交付验收

最后不要只问 TRAE “看看有没有问题”。要提供你的上下文包、需求表、接口契约、权限矩阵、状态流转表和异常态清单，让 TRAE 按标准 Review。

Review 必须覆盖：

- 是否有源码依据。
- 是否有业务边界。
- 是否遗漏权限。
- 是否遗漏非法状态。
- 是否遗漏审计。
- 是否遗漏异常态。
- 是否有不可验证的指标。
- 是否有需要人工确认的业务决策。

交付物：`Review 记录表`、`最终交付记录`。

提交前用 [acceptance-checklist.md](./acceptance-checklist.md) 自检。若某项无法确认，写入“不确定点”，不要假装已经完成。