# JeecgBoot 工单案例包

这是一个独立培训案例包，用于在 TRAE 课程中训练学员把 AI 编程工具用于真实 JeecgBoot 类后台项目。案例围绕“企业工单与研发效能看板”展开，但不假设当前源码中已经存在完整工单模块。

## 适用场景

| 场景 | 用法 |
| --- | --- |
| 第 3 天功能开发闭环 | 用于需求拆解、接口契约、页面状态、测试点前置设计 |
| 第 4 天复杂业务开发 | 用于权限、状态流转、审计、异常态、看板和 Review |
| 企业内部二开培训 | 作为 JeecgBoot 项目入门和 TRAE 协作标准样例 |
| 课后资产沉淀 | 拆分为 rules、Prompt、Command、Skill、SOP 和案例库 |

## 学习目标

完成本案例后，学员应该能做到：

1. 使用 TRAE 从真实项目中定位前端入口、后端入口、权限、路由、API、配置和数据库依据。
2. 把“工单管理”需求拆成用户故事、字段、接口契约、页面状态和验收标准。
3. 先生成权限矩阵和状态流转表，再设计代码修改计划。
4. 对审计日志、异常态、看板指标和 Review 输出提出可验证要求。
5. 识别 TRAE 输出中的事实、推断、建议和不确定点。

## 建议使用顺序

1. 先读 [source-map.md](./source-map.md)，建立 JeecgBoot 项目地图。
2. 讲师按 [instructor-guide.md](./instructor-guide.md) 选择 2 小时、半天或 1 天节奏。
3. 学员按 [learner-guide.md](./learner-guide.md) 完成实操。
4. 每一步复制 [prompts.md](./prompts.md) 中的模板，但必须填入本组上下文。
5. 课堂产出写入 [worksheets.md](./worksheets.md)。
6. 交付前用 [acceptance-checklist.md](./acceptance-checklist.md) 验收。
7. 课后按 [assets-index.md](./assets-index.md) 沉淀团队资产。
8. 需要直接复用资产时，复制 [ai-dev-assets/README.md](./ai-dev-assets/README.md) 下列出的规则、Prompt、模板、检查清单、Skill 和反例。

## 课前准备

| 事项 | 要求 |
| --- | --- |
| 项目目录 | `../../../JeecgBoot` 存在，并包含 `jeecg-boot`、`jeecgboot-vue3` 和 `docs/project-knowledge` |
| 工具 | TRAE、Git、Node 20.19+ 或 22.12+、pnpm、JDK 17、Maven |
| 账号 | JeecgBoot 默认演示账号可用于讲解：`admin/123456`，真实环境不得复用 |
| 数据 | 课堂可使用虚拟工单数据，不要求真实连接数据库 |
| 协作约束 | 后端遵守 `../../../JeecgBoot/jeecg-boot/CLAUDE.md`，前端遵守 `../../../JeecgBoot/jeecgboot-vue3/CLAUDE.md` |

## 案例任务主线

工单模块用于管理研发团队内的任务、缺陷和支持请求。课堂不要求完整编码实现，而是训练“先理解、再设计、再计划、最后验收”的 AI 协作方式。

| 阶段 | 任务 | 产出 |
| --- | --- | --- |
| 项目理解 | 定位前后端入口、权限、API、配置和数据库 | 项目地图、源码依据表 |
| 需求拆解 | 设计工单列表、详情、状态、指派、评论、看板需求 | 用户故事、字段清单、非目标范围 |
| 接口契约 | 设计列表、详情、创建、编辑、指派、状态流转、审计查询接口 | 接口契约表 |
| 权限设计 | 定义管理员、负责人、研发、测试、只读角色权限边界 | RBAC 权限矩阵 |
| 状态流转 | 定义新建、处理中、待验证、已关闭、已驳回流转规则 | 状态流转表、非法流转清单 |
| 审计与异常态 | 设计操作日志、重复提交、权限不足、非法状态等处理 | 审计字段表、异常态清单 |
| 看板与 Review | 设计数量、周期、缺陷分布、趋势指标并审查方案 | 看板指标表、AI Review 报告 |

## 最终交付物

每个小组至少提交：

- 一份源码依据记录表。
- 一份工单需求拆解表。
- 一份接口契约表。
- 一份 RBAC 权限矩阵。
- 一份状态流转表和非法流转清单。
- 一份审计日志设计表。
- 一份异常态清单。
- 一份看板指标表。
- 一份 Review 记录和最终验收记录。

## 关键约束

- 不要直接让 TRAE “帮我做一个工单模块”。
- 每次让 TRAE 输出结论前，先要求它列出依据文件、函数、接口或配置。
- 所有输出必须区分事实、推断、建议和不确定点。
- 涉及权限、状态流转、删除、审计和看板的任务必须先出方案，再讨论代码修改。
- 后端实际改代码时必须遵守 `update-begin` / `update-end` 修改痕迹规则。
- 前端实际改代码时必须复用 `/@/` alias、Pinia、动态路由和 `defHttp` 请求层。

## 文件索引

| 文件 | 用途 |
| --- | --- |
| [instructor-guide.md](./instructor-guide.md) | 讲师授课节奏和讲法 |
| [learner-guide.md](./learner-guide.md) | 学员实操路径 |
| [source-map.md](./source-map.md) | JeecgBoot 源码定位图 |
| [prompts.md](./prompts.md) | 可复制的 TRAE Prompt 模板 |
| [worksheets.md](./worksheets.md) | 课堂填写表 |
| [acceptance-checklist.md](./acceptance-checklist.md) | 交付验收清单 |
| [assets-index.md](./assets-index.md) | 课后资产沉淀建议 |
| [ai-dev-assets/](./ai-dev-assets/README.md) | 可直接复制到团队资产库的具体产物 |

其中 [generate-project-constraints](./ai-dev-assets/skills/generate-project-constraints/SKILL.md) 是跨项目复用 Skill，用于在没有 `CLAUDE.md`、`AGENTS.md` 或 `README.md` 的项目中，也能从配置、源码模式、测试和 CI 中提取项目约束。

另外还提供 3 个可复用 Skill：

- [design-complex-business-module](./ai-dev-assets/skills/design-complex-business-module/SKILL.md)：生成权限、状态、审计、异常态和看板设计资产。
- [review-business-delivery](./ai-dev-assets/skills/review-business-delivery/SKILL.md)：审查复杂业务交付中的权限、状态、审计、异常态、看板和验收风险。
- [track-review-fix-loop](./ai-dev-assets/skills/track-review-fix-loop/SKILL.md)：把 Review 问题转成修复记录、验证证据和资产沉淀建议。