# 第 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 和修复闭环跑起来。 这就是第四天要带走的能力。