diff --git a/TRAE AI编程实战培训意见反馈(1).docx b/TRAE AI编程实战培训意见反馈(1).docx new file mode 100644 index 0000000..e4e3aa5 Binary files /dev/null and b/TRAE AI编程实战培训意见反馈(1).docx differ diff --git a/TRAE 培训大纲V1.0.md b/TRAE 培训大纲V1.0.md new file mode 100644 index 0000000..df1f010 --- /dev/null +++ b/TRAE 培训大纲V1.0.md @@ -0,0 +1,318 @@ +# TRAE 培训大纲V1\.0 + +项目建议： + +> **企业级工单与研发效能看板系统** +> +> + +> 包含工单流转、角色权限、审计日志、数据看板、历史代码重构、测试与CI门禁。 +> +> + + + +--- + + + +## 课程基本设置 + + + +- 培训对象：研发、测试 + +- 培训规模：约70人 + +- 总时长：6天 + +- 课程目标：让学员掌握TRAE在真实研发流程中的标准用法 + + + +--- + + + +## 课前准备 + +|事项|内容| +|---|---| +|环境检查|Node、pnpm、Git、IDE、TRAE 安装与登录| +|项目准备|拉取沙箱项目，安装依赖，启动前后端| +|账号准备|Git 仓库权限、CI 权限、测试账号| +|数据准备|工单样例数据、权限角色数据、审计日志样例、CI 失败样例| +|管理数据准备|PR 样例、缺陷样例、需求流转样例、测试覆盖率样例| + + + +--- + + + +## 6 天课程大纲 + +### 第 1 天：TRAE 基础工作流与陌生代码库理解 + + + +**目标：** + +掌握用 TRAE 快速理解陌生项目结构、业务模块、调用链路的方法，并能识别 AI 输出中的不确定结论。 + + + +|内容|实操|产出| +|---|---|---| +|TRAE 在真实研发流程中的定位|判断哪些任务适合交给 TRAE，哪些必须人工判断|TRAE 使用边界清单| +|沙箱项目业务导览|浏览工单、权限、审计、看板模块|项目模块认知图| +|使用 @workspace 理解全局结构|梳理目录、路由、接口、状态管理、测试与 CI|项目结构图| +|调用链路分析|分析工单流转、权限判断、接口调用链路|模块调用链路图| +|AI 输出可信度判断|要求 TRAE 标注依据文件、函数、调用关系|TRAE 输出校验清单| +|统一实战：代码理解报告|针对指定模块生成架构理解、风险点和改造建议|代码理解报告| + + + + + +### 第 2 天：TRAE 上下文工程与规则体系 + + + +**目标：** + +掌握正确投喂上下文的方法，学会编写 `.trae/rules.md`，把团队隐性开发习惯变成可执行规则。 + + + +|内容|实操|产出| +|---|---|---| +|上下文工程原则|明确目标、范围、约束、输出格式和验收标准|上下文组织清单| +|@workspace、\#Code、\#File、\#Web 使用|对同一任务使用不同上下文组合并比较结果|上下文引用模板| +|幻觉死循环切断方法|要求 TRAE 先找证据、再判断、再给方案|幻觉控制 Prompt| +|`.gitignore` 与 IDE 忽略配置|配置忽略规则，避免提交缓存、密钥、本地配置|忽略配置样例| +|`.trae/rules.md` 安全规则|禁止泄露密钥、禁止硬编码账号、禁止提交敏感目录|安全规则段落| +|`.trae/rules.md` 编码与测试规则|写入 TypeScript、状态管理、接口分层、测试、Review 规则|团队通用规则草案| +|前端规则|写入页面状态、接口类型、权限按钮、异常态、防重复提交等规则|前端规则段落| +|技能与规则的资产化|将常用 Prompt、规则、模板、案例归档到企业资产库|资产库目录草案| +|规则可执行性检查|用 TRAE 检查规则是否含糊、冲突、不可执行|规则验收清单| + + + + + +### 第 3 天：需求拆解与功能开发基础闭环 + + + +**目标：** + +训练学员用 TRAE 把业务需求拆成可开发、可测试、可验收的任务，并完成基础功能开发闭环。 + + + +|内容|实操|产出| +|---|---|---| +|工单系统核心需求输入|输入工单列表、详情、状态、指派、评论需求|原始需求说明| +|用 TRAE 拆解用户故事|生成用户故事、功能边界、非目标范围、异常场景|需求拆解文档| +|接口契约与页面状态设计|生成字段、枚举、加载态、空态、失败态|接口契约表| +|测试点前置设计|生成正常流、异常流、权限流、边界值测试点|测试点清单| +|Builder / SOLO 模式使用|比较功能开发、局部修复、方案生成中的适用场景|功能开发 Prompt| +|工单列表基础开发|完成查询、筛选、分页、排序|工单列表代码| +|工单详情基础开发|展示状态、优先级、指派人、评论记录|基础功能 Diff| + + + +### 第 4 天：复杂业务开发：权限、审计、异常态与看板 + + + +**目标：** + +训练 TRAE 处理真实业务复杂度，掌握权限、审计、状态流转、异常态和数据看板的生成与调优方法。 + + + +|内容|实操|产出| +|---|---|---| +|RBAC 权限模型设计|定义管理员、研发、测试、负责人、只读用户权限边界|RBAC 权限矩阵| +|权限控制方案生成|生成按钮级、页面级、接口级权限控制方案|权限控制方案| +|工单状态流转规则实现|实现创建、处理中、待验证、关闭、驳回|状态流转代码| +|审计日志设计|记录操作人、时间、动作、字段前后值|审计日志 SOP| +|异常态与防御性逻辑|处理空数据、接口失败、权限不足、重复提交、非法流转|异常态代码| +|研发效能看板指标开发|实现工单数量、关闭周期、缺陷分布、趋势指标|效能看板代码| +|阶段代码审查与修复|使用 TRAE 对当天代码进行 Review 和修复|Review 记录| + + + +### 第 5 天：历史代码重构、测试覆盖与团队资产库建设 + + + +**目标：** + +掌握用 TRAE 安全治理技术债、补齐测试覆盖，并将课程中的规则、Prompt、模板、案例和流程沉淀为可维护的企业资产库。 + + + +|内容|实操|产出| +|---|---|---| +|历史代码问题识别|分析长函数、重复判断、隐式规则、类型缺失、分支过深|代码坏味道清单| +|重构方案生成|生成策略模式、composable 拆分、类型抽取方案|重构方案| +|重构风险审查|检查行为一致性、影响范围、回滚方案、测试缺口|重构风险清单| +|重构实操|对预置历史模块进行分层拆分和类型治理|重构 Diff| +|TypeScript 类型治理|从接口响应、状态枚举、表单模型中抽取类型|TypeScript Interface| +|测试用例生成|覆盖权限、状态流转、异常输入、边界值|单测用例清单| +|Vitest 单测补齐|修正无效断言和脆弱测试|单测脚本与覆盖率报告| +|团队资产库分层设计|将课程产物分为规则、Prompt、模板、案例、SOP、指标|资产库目录结构| +|`.trae/rules.md` 生命周期|设计规则新增、评审、废弃、版本管理机制|规则维护机制| +|Prompt 模板库建设|标准化读代码、拆需求、写代码、重构、测试、Review、CI 修复 Prompt|Prompt 模板库| +|案例库沉淀|提取优秀案例、问题案例、幻觉案例、CI 失败案例|案例库| +|资产评审机制|明确谁维护、多久评审、如何合入、如何淘汰|资产治理 SOP| +|新人和项目推广机制|设计新人学习路径、项目接入流程、检查机制|TRAE 推广流程| + + + +### 第 6 天：企业研发效能、PR 闭环、CI 门禁与落地计划 + + + +**目标：** + +建立 AI 辅助研发效能管理方法，能够基于 PR、CI、缺陷、需求流转数据分析团队产出率、质量和吞吐，并跑通开发、Review、CI、验收、资产沉淀、管理复盘的完整闭环。 + + + +|内容|实操|产出| +|---|---|---| +|研发效能指标体系|定义产出、质量、吞吐、周期、AI 使用、资产复用指标|指标字典| +|产出效率分析|分析 PR 数、有效提交、需求完成数、人均交付量|产出分析模板| +|需求吞吐分析|分析需求进入数、完成数、积压数、吞吐率|需求吞吐看板| +|交付周期分析|分析 Lead Time、Cycle Time、Review 等待时间、CI 修复时间|周期分析模板| +|质量指标分析|分析缺陷数、返工率、测试覆盖率、CI 失败率|质量分析模板| +|AI 使用指标|设计 AI 采纳率、AI 修改率、Prompt 复用率、AI Review 命中率|AI 使用指标表| +|团队资产指标|设计规则更新次数、模板复用次数、案例沉淀数、资产过期率|资产运营指标| +|TRAE 辅助效能分析|将 PR、CI、缺陷样例数据输入 TRAE，生成分析报告|效能分析报告| +|TRAE Code Review 方法|从安全、类型、性能、可维护性、测试缺口审查代码|AI Code Review 清单| +|PR 模板与审查标准|编写需求说明、实现说明、测试结果、风险点、AI 使用记录|PR 模板| +|CI 质量门禁设计|配置 lint、typecheck、unit test、coverage|CI/CD YAML| +|TRAE 分析 CI 失败日志|将失败日志输入 TRAE，定位原因并生成修复方案|CI 失败修复记录| +|标准 PR 闭环演练|完成代码整理、Review、测试、CI 修复和验收|可运行 PR| +|Prompt 模板资产库沉淀|汇总读代码、拆需求、写代码、重构、测试、Review Prompt|Prompt 模板资产库| +|ROI 测算方法|计算 AI 采纳率、PR 周期缩短、缺陷率变化、节省人日|ROI 测算报告| + +### AI Native 技能清单 + +|阶段|技能|典型产出| +|---|---|---| +|需求阶段|Brain 需求澄清|需求澄清问题清单| +|需求阶段|Md 文档生成|标准需求说明书| +|需求阶段|Grill 评审追问|需求评审问题清单| +|需求阶段|用户故事拆解|用户故事、验收标准、非目标范围| +|设计阶段|代码库理解|项目结构图、模块认知图| +|设计阶段|调用链分析|调用链路图| +|设计阶段|接口契约设计|接口契约表| +|设计阶段|状态机设计|状态流转图| +|设计阶段|RBAC 权限设计|权限矩阵| +|开发阶段|JeecgBoot 代码生成|Controller、Service、Mapper、DTO、VO| +|开发阶段|前端页面生成|列表、详情、表单、看板页面| +|开发阶段|异常态补齐|loading、empty、error、forbidden 状态| +|测试阶段|测试点生成|正常流、异常流、权限流、边界值| +|测试阶段|单测生成|Vitest / JUnit 单测| +|重构阶段|代码坏味道识别|坏味道清单| +|重构阶段|无损重构|重构 Diff、风险清单| +|Review 阶段|AI Code Review|Review 问题清单| +|CI 阶段|CI 失败分析|CI 失败原因与修复方案| +|管理阶段|研发效能分析|效能分析报告| +|管理阶段|ROI 测算|ROI 测算报告| + + + +--- + +## 企业通用规则 + + + +- AI 输出必须标注依据文件、函数、接口、日志或数据来源。 + +- 输出必须区分事实、推断和建议。 + +- 修改代码前必须说明影响范围。 + +- 复杂改动必须先给方案，再生成代码。 + +- 不允许盲目删除历史逻辑。 + +- 不允许泄露密钥、Token、账号、内网地址。 + +- 不允许硬编码账号、密码、租户 ID、环境地址。 + +- 不允许提交缓存、构建产物、本地配置和 IDE 私有配置。 + +- 测试必须覆盖正常流、异常流、权限流、边界值。 + +- Review 必须覆盖安全、类型、性能、可维护性、测试缺口。 + +- CI 修复必须先解释失败原因，再给修复方案。 + +## 最终交付物清单 + +- \[ \] 全局 `.gitignore` \+ IDE 忽略配置 + +- \[ \] 团队通用 `.trae/rules.md` + +- \[ \] TRAE 上下文引用避坑指南与模板 + +- \[ \] 读代码与架构分析 Prompt 模板 + +- \[ \] 标准化需求拆解文档与接口契约表 + +- \[ \] RBAC 权限矩阵与审计日志 SOP + +- \[ \] 可运行的工单/效能看板业务代码 + +- \[ \] 核心历史模块的重构 Diff 记录 + +- \[ \] 高质量 TypeScript 接口定义文件 + +- \[ \] 达到标准覆盖率的单元测试脚本与报告 + +- \[ \] 跑通的 CI/CD 质量门禁 YAML 配置 + +- \[ \] 团队级 AI Code Review 标准清单 + +- \[ \] 精选沉淀的 Prompt 模板资产库 + +- \[ \] ROI 效能提升测算报告及落地计划 + +--- + +## 课程验收标准 + +1. **架构认知力：** 学员能脱离业务宣讲，仅依靠 TRAE 快速梳理出陌生代码库的正确拓扑图。 + +2. **上下文管控力：** 学员能精准组合 `@workspace`、`#Code`、`#File`、`#Web`，不产生 token 浪费与无意义的全局检索。 + +3. **规则执行力：** 团队能成功编写并维护 `.trae/rules.md`，使 AI 生成的代码无需人工二次调整基础格式。 + +4. **架构设计力：** 学员不再直接让 AI 写代码，而是先用 TRAE 拆解需求、生成契约和防御性测试点。 + +5. **代码掌控力：** 学员具备对 TRAE 产出代码的局部重写和纠错能力，而不是盲目执行“Accept All”。 + +6. **技术债治理力：** 学员能在建立测试安全网的前提下，指挥 TRAE 进行复杂逻辑的无损重构。 + +7. **质量保障力：** 学员能用 TRAE 快速补齐核心流与边界条件的单测，消除无效的虚假断言。 + +8. **工程闭环力：** 能够将 AI Review 融入个人提交习惯，并掌握借助 CI 日志让 AI 自动修复代码的流水线能力。 + +9. **管理量化力：** 技术负责人能建立明确的 TRAE 落地方案，掌握代码产出比、交付周期等 ROI 测算方式。 + +## 咨询费用 + +6 \* 12000 = 720000 元 + +付款方式：合同签订后付款50%，培训过半后付款30%，培训结束付款20%。 + + + diff --git a/cases/jeecgboot-work-order/README.md b/cases/jeecgboot-work-order/README.md new file mode 100644 index 0000000..85bfb5c --- /dev/null +++ b/cases/jeecgboot-work-order/README.md @@ -0,0 +1,101 @@ +# 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 问题转成修复记录、验证证据和资产沉淀建议。 diff --git a/cases/jeecgboot-work-order/acceptance-checklist.md b/cases/jeecgboot-work-order/acceptance-checklist.md new file mode 100644 index 0000000..230cd33 --- /dev/null +++ b/cases/jeecgboot-work-order/acceptance-checklist.md @@ -0,0 +1,71 @@ +# 验收清单 + +本清单用于判断学员是否真正掌握 JeecgBoot 工单案例，而不是只复制了 TRAE 输出。建议讲师在小组展示时逐项打分。 + +## 项目理解 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 能说明 JeecgBoot 前后端目录 | 至少指出 `jeecg-boot`、`jeecgboot-vue3`、`docs/project-knowledge` 的用途 | | +| 能定位后端入口 | 能指出 `JeecgSystemApplication.java` 和后端启动模块 | | +| 能定位前端入口 | 能指出 `src/main.ts`、路由、Pinia 和 API 请求层 | | +| 能区分事实和推断 | 对没有源码依据的业务规则标注为推断或待确认 | | +| 能记录不确定点 | 不确定内容没有被包装成确定事实 | | + +## 需求与接口 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 用户故事完整 | 覆盖管理员、负责人、研发、测试、只读用户 | | +| 非目标范围明确 | 明确课堂不做完整编码、生产部署、真实数据迁移 | | +| 接口契约完整 | 覆盖列表、详情、新增、编辑、指派、状态、审计、看板 | | +| 失败场景明确 | 每个关键接口至少有权限、参数、状态或数据不存在失败场景 | | +| 验收方式明确 | 每个关键需求都有可执行检查方法 | | + +## 权限与状态 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 权限矩阵完整 | 覆盖页面级、按钮级、接口级和数据范围 | | +| 权限字符合理 | 命名统一，并标注为建议而非源码事实 | | +| 后端权限未缺失 | 没有用前端按钮隐藏替代后端接口控制 | | +| 状态流转表完整 | 覆盖新建、处理中、待验证、已关闭、已驳回 | | +| 非法流转明确 | 至少列出 5 条非法流转和拒绝原因 | | + +## 审计、异常态与看板 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 审计操作覆盖关键动作 | 创建、编辑、指派、状态流转、关闭、评论至少覆盖 5 类 | | +| 审计字段可追溯 | 包含 actor、action、targetId、oldValue、newValue、source | | +| 敏感信息处理 | oldValue/newValue 有脱敏说明 | | +| 异常态可测试 | 权限不足、重复提交、非法状态、数据不存在、并发修改均覆盖 | | +| 看板指标可计算 | 每个指标有口径、维度、过滤条件和数据来源建议 | | + +## Review 与交付 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| Review 有证据 | 问题能回到路径、表格或业务规则 | | +| 风险按严重程度排序 | 高风险问题优先展示 | | +| 建议可行动 | 每条建议有修复方向和验收方式 | | +| 交付物齐全 | [worksheets.md](./worksheets.md) 中最终交付记录完整 | | +| 能沉淀资产 | 能说明哪些内容进入 [assets-index.md](./assets-index.md) 的资产库 | | + +## 评分建议 + +| 等级 | 分数 | 描述 | +| --- | ---: | --- | +| A | 90-100 | 依据充分，设计完整，风险清楚，验收可执行 | +| B | 75-89 | 主链路完整，少量不确定点或验收细节不足 | +| C | 60-74 | 有基本产出，但权限、状态、审计或异常态明显薄弱 | +| D | 0-59 | 泛泛总结项目，缺少源码依据或无法验收 | + +## 讲师判定原则 + +- 优先看证据，不优先看文字是否漂亮。 +- 优先看权限、状态、审计、异常态，不只看 CRUD。 +- 优先看不确定点是否被诚实标出。 +- 优先看能否复用到团队资产库。 +- 对没有依据的自信结论扣分。 + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/README.md b/cases/jeecgboot-work-order/ai-dev-assets/README.md new file mode 100644 index 0000000..f58f756 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/README.md @@ -0,0 +1,76 @@ +# JeecgBoot 工单可复用资产包 + +这个目录里的文件不是大纲，而是课后可以直接复制到团队 `ai-dev-assets/` 的资产。 + +## 使用方式 + +1. 需要团队规则时，复制 `rules/`。 +2. 需要快捷提问时，复制 `commands/` 和 `prompts/jeecgboot/`。 +3. 需要把流程封装成团队能力时，复制 `skills/`。 +4. 需要课堂或项目交付表时，复制 `templates/` 和 `templates/jeecgboot/`。 +5. 需要验收和上线检查时，复制 `checklists/` 和 `checklists/jeecgboot/`。 +6. 需要反例教学时，复制 `examples/` 和 `examples/jeecgboot/`。 + +## 资产清单 + +### 第 3 天 Agent 工作流资产 + +- `rules/global.md` +- `rules/frontend.md` +- `rules/backend.md` +- `rules/security.md` +- `rules/testing.md` +- `rules/delivery.md` +- `commands/模块结构分析.command.md` +- `commands/工单需求拆解.command.md` +- `commands/接口契约生成.command.md` +- `commands/代码生成Review.command.md` +- `commands/PR说明生成.command.md` +- `skills/JeecgBoot工单模块开发审查.skill.md` +- `skills/generate-project-constraints/SKILL.md` +- `skills/generate-project-constraints/assets/项目约束提取表.template.md` +- `skills/generate-project-constraints/assets/项目约束验收清单.md` +- `skills/generate-project-constraints/assets/项目约束生成.prompt.md` +- `skills/design-complex-business-module/SKILL.md` +- `skills/review-business-delivery/SKILL.md` +- `skills/track-review-fix-loop/SKILL.md` +- `templates/Plan任务模板.md` +- `templates/AIReview报告模板.md` +- `templates/Browser验证报告模板.md` +- `checklists/任务成本与能力匹配表.md` +- `checklists/Agent分工表.md` +- `checklists/CLI-MCP-Skill封装决策表.md` +- `examples/好Command与坏Command对照.md` +- `examples/好Skill与坏Skill对照.md` +- `examples/好Plan与坏Plan对照.md` + +### 第 4 天 JeecgBoot 工单复杂业务资产 + +- `prompts/jeecgboot/RBAC权限矩阵生成.prompt.md` +- `prompts/jeecgboot/权限控制方案生成.prompt.md` +- `prompts/jeecgboot/状态流转设计.prompt.md` +- `prompts/jeecgboot/异常态补齐.prompt.md` +- `prompts/jeecgboot/看板指标设计.prompt.md` +- `prompts/jeecgboot/看板接口验收.prompt.md` +- `prompts/jeecgboot/阶段Review.prompt.md` +- `prompts/jeecgboot/修复记录生成.prompt.md` +- `templates/jeecgboot/RBAC权限矩阵.template.md` +- `templates/jeecgboot/权限控制方案.template.md` +- `templates/jeecgboot/状态流转表.template.md` +- `templates/jeecgboot/审计日志SOP.template.md` +- `templates/jeecgboot/异常态清单.template.md` +- `templates/jeecgboot/看板指标字典.template.md` +- `templates/jeecgboot/看板接口验收记录.template.md` +- `templates/jeecgboot/阶段Review报告.template.md` +- `templates/jeecgboot/修复记录.template.md` +- `checklists/jeecgboot/权限上线前检查清单.md` +- `checklists/jeecgboot/状态流转检查清单.md` +- `checklists/jeecgboot/审计日志检查清单.md` +- `checklists/jeecgboot/异常态检查清单.md` +- `checklists/jeecgboot/看板指标口径检查清单.md` +- `checklists/jeecgboot/看板接口验收清单.md` +- `checklists/jeecgboot/Review修复闭环检查清单.md` +- `examples/jeecgboot/权限遗漏反例.md` +- `examples/jeecgboot/非法状态流转反例.md` +- `examples/jeecgboot/审计日志缺失反例.md` +- `examples/jeecgboot/看板指标口径不清反例.md` diff --git a/cases/jeecgboot-work-order/ai-dev-assets/checklists/Agent分工表.md b/cases/jeecgboot-work-order/ai-dev-assets/checklists/Agent分工表.md new file mode 100644 index 0000000..71e0770 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/checklists/Agent分工表.md @@ -0,0 +1,12 @@ +# Agent 分工表 + +| Agent | 输入 | 动作 | 输出 | 验收 | 边界 | +| --- | --- | --- | --- | --- | --- | +| 需求拆解 Agent | 原始需求 | 拆用户故事、边界、异常 | 需求拆解文档 | 有验收标准 | 不直接写代码 | +| 代码理解 Agent | 项目路径 | 找入口、链路、依据 | 源码依据表 | 能指向文件 | 不做业务决策 | +| 规则审查 Agent | rules + 任务 | 判断规则命中 | 规则命中表 | 能解释触发原因 | 不改规则 | +| 代码生成审查 Agent | 生成代码、字段表、rules | 查字段、查询、字典、异常态 | 代码生成 Review 清单 | 能指向文件和问题 | 不直接合入 | +| 测试建议 Agent | 需求、diff | 生成测试点 | 测试点清单 | 覆盖正常/异常/权限/状态 | 不替代人工验收 | +| Review Agent | diff、rules、测试结果 | 输出问题等级和建议 | Review 报告 | 问题可定位 | 不替代负责人判断 | +| 文档整理 Agent | 课堂产出 | 归档资产 | 资产库条目 | 命名清楚 | 不编造产出 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/checklists/CLI-MCP-Skill封装决策表.md b/cases/jeecgboot-work-order/ai-dev-assets/checklists/CLI-MCP-Skill封装决策表.md new file mode 100644 index 0000000..802c323 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/checklists/CLI-MCP-Skill封装决策表.md @@ -0,0 +1,11 @@ +# CLI / MCP / Skill 封装决策表 + +| 需求 | 推荐封装 | 理由 | 验收 | +| --- | --- | --- | --- | +| 生成 PR 说明 | Command | 固定格式、低风险 | PR 模板字段完整 | +| 检查代码生成结果 | Command | 输入固定、输出固定 | Review 清单完整 | +| JeecgBoot 工单模块开发审查 | Skill | 多步骤、多文件、多规则 | 输出风险表和依据 | +| 调用浏览器检查页面 | MCP / Browser | 需要真实页面状态 | 有截图或操作证据 | +| 批量扫描源码指标 | CLI | 可脚本化、重复执行 | 命令输出稳定 | +| 跨系统取数据 | MCP | 需要外部工具或系统 | 有鉴权和审计 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/Review修复闭环检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/Review修复闭环检查清单.md new file mode 100644 index 0000000..39df455 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/Review修复闭环检查清单.md @@ -0,0 +1,12 @@ +# Review 修复闭环检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 问题编号 | 每个 Review 问题有编号 | | +| 成立判断 | 每个问题说明是否成立 | | +| 修改说明 | 成立问题说明修改文件和内容 | | +| 验证结果 | 每个修复有验证证据 | | +| 未修复说明 | 暂不修复的问题有原因和后续计划 | | +| 资产沉淀 | 有复用价值的问题已进入检查清单或反例库 | | +| 回归检查 | 修复后重新检查相关权限/状态/审计/看板 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/审计日志检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/审计日志检查清单.md new file mode 100644 index 0000000..0e271a4 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/审计日志检查清单.md @@ -0,0 +1,13 @@ +# 审计日志检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 创建记录 | 创建工单后能查询审计记录 | | +| 字段变更 | 编辑关键字段记录 oldValue/newValue | | +| 指派记录 | 指派负责人记录原负责人和新负责人 | | +| 状态记录 | 状态流转记录原状态和新状态 | | +| 操作人 | actor_id 和 actor_name 可追溯 | | +| 来源 | source 或 request_id 可追溯 | | +| 脱敏 | 敏感字段不明文进入审计 | | +| 失败处理 | 操作失败不写成功审计 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/异常态检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/异常态检查清单.md new file mode 100644 index 0000000..e1b6496 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/异常态检查清单.md @@ -0,0 +1,13 @@ +# 异常态检查清单 + +| 异常态 | 必须验证 | 结果 | +| --- | --- | --- | +| 空列表 | 页面显示空状态，不报错 | | +| 详情不存在 | 提示工单不存在，页面不崩溃 | | +| 权限不足 | 前端提示或隐藏，后端拒绝 | | +| 非法状态 | 返回非法流转，状态不变 | | +| 重复提交 | 只成功一次，只写一条有效审计 | | +| 参数缺失 | 返回参数错误，业务数据不变 | | +| 并发修改 | 拒绝覆盖或提示刷新 | | +| 看板无数据 | 图表显示空态，不显示假数据 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/权限上线前检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/权限上线前检查清单.md new file mode 100644 index 0000000..cacf893 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/权限上线前检查清单.md @@ -0,0 +1,12 @@ +# 权限上线前检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 菜单权限 | 工单菜单只对授权角色可见 | | +| 按钮权限 | 新增、编辑、删除、指派、状态按钮按权限显示 | | +| 接口权限 | 无权限账号直接请求敏感接口失败 | | +| 数据权限 | 普通用户只能看到授权范围内工单 | | +| 权限字符 | 前端按钮、菜单配置、后端接口命名一致 | | +| 审计 | 权限敏感操作成功后有审计记录 | | +| 反例验证 | 无权限账号不能绕过前端执行删除/指派 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/状态流转检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/状态流转检查清单.md new file mode 100644 index 0000000..2be5688 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/状态流转检查清单.md @@ -0,0 +1,12 @@ +# 状态流转检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 状态枚举 | 所有状态有统一枚举或字典 | | +| 合法流转 | 状态流转表中的合法路径可执行 | | +| 非法流转 | 非法路径被拒绝且状态不变 | | +| 角色限制 | 不同角色只能执行被授权动作 | | +| 前置条件 | 驳回原因、关闭条件、负责人等校验完整 | | +| 审计日志 | 每次成功流转写审计 | | +| 重复提交 | 重复点击不会产生重复有效流转 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/看板指标口径检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/看板指标口径检查清单.md new file mode 100644 index 0000000..b732c20 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/看板指标口径检查清单.md @@ -0,0 +1,13 @@ +# 看板指标口径检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 指标含义 | 每个指标有业务解释 | | +| 计算口径 | 每个指标有公式或筛选条件 | | +| 时间范围 | 明确按创建时间、关闭时间还是更新时间统计 | | +| 数据范围 | 不同角色的数据范围清楚 | | +| 空数据 | 空数据展示为 0 或空态，不误导 | | +| 分组一致性 | 分组总和能和总数对齐 | | +| 权限 | 无看板权限不能访问接口 | | +| 验收证据 | 至少有一组样例数据手工校验 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/看板接口验收清单.md b/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/看板接口验收清单.md new file mode 100644 index 0000000..95e740a --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/checklists/jeecgboot/看板接口验收清单.md @@ -0,0 +1,12 @@ +# 看板接口验收清单 + +| 验收项 | 请求条件 | 通过标准 | 结果 | +| --- | --- | --- | --- | +| 默认查询 | 管理员默认条件 | 返回完整指标 | | +| 时间过滤 | 指定 start/end | 只统计时间范围内数据 | | +| 类型过滤 | 指定工单类型 | 只统计对应类型 | | +| 空数据 | 无匹配条件 | 返回 0 或空集合 | | +| 无权限 | 未授权账号 | 返回 403 或业务拒绝 | | +| 数据范围 | 普通角色 | 只返回授权范围 | | +| 指标一致性 | 固定样例数据 | 与手工计算一致 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/checklists/任务成本与能力匹配表.md b/cases/jeecgboot-work-order/ai-dev-assets/checklists/任务成本与能力匹配表.md new file mode 100644 index 0000000..2be27f0 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/checklists/任务成本与能力匹配表.md @@ -0,0 +1,11 @@ +# 任务成本与能力匹配表 + +| 任务 | 风险 | 上下文需求 | 推荐能力 | 验收方式 | +| --- | --- | --- | --- | --- | +| 拆解工单需求 | 中 | 需求说明 + 项目规则 | Agent 分析 | 有用户故事和验收标准 | +| 生成接口契约 | 中 | 需求 + 字段 + 权限 | Command | 接口表完整 | +| 审查代码生成结果 | 中 | 生成代码 + rules | Command / Skill | 输出代码生成 Review 清单 | +| 修改工单状态流转 | 高 | 相关文件 + rules + 测试 | Plan 后执行 | 状态机验证 + Review | +| 生成 PR 说明 | 低 | diff + 测试结果 | Command | PR 模板字段完整 | +| 修复 CI 失败 | 中 | CI 日志 + diff + rules | Agent 分析 | 失败原因和修复方案清楚 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/commands/PR说明生成.command.md b/cases/jeecgboot-work-order/ai-dev-assets/commands/PR说明生成.command.md new file mode 100644 index 0000000..49cab29 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/commands/PR说明生成.command.md @@ -0,0 +1,38 @@ +# /PR说明生成 + +## 使用场景 + +工单模块阶段开发完成后，生成 PR 描述初稿。 + +## 输入 + +- diff 或变更文件清单。 +- 需求说明。 +- 测试结果。 +- Review 记录。 +- 风险和不确定点。 + +## 执行要求 + +1. 说明背景和目标。 +2. 列出变更范围。 +3. 标注不做什么。 +4. 写清测试和验收结果。 +5. 写清风险、回滚建议和 AI 使用记录。 + +## 输出格式 + +```md +## 背景 + +## 变更内容 + +## 不做什么 + +## 测试与验收 + +## 风险与回滚 + +## AI 辅助记录 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/commands/代码生成Review.command.md b/cases/jeecgboot-work-order/ai-dev-assets/commands/代码生成Review.command.md new file mode 100644 index 0000000..25592e7 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/commands/代码生成Review.command.md @@ -0,0 +1,30 @@ +# /代码生成 Review + +## 使用场景 + +JeecgBoot 基于工单表生成基础 CRUD 后，正式进入人工调整前使用。 + +## 输入 + +- 数据表字段说明。 +- 生成的前端页面。 +- API 模块文件。 +- 后端 Controller。 +- 后端 Service。 +- 当前 rules。 + +## 执行要求 + +1. 检查字段是否和数据模型一致。 +2. 检查查询条件、分页、排序是否完整。 +3. 检查状态、优先级、类型是否使用字典或枚举。 +4. 检查新增、编辑、删除、导出按钮是否需要权限控制。 +5. 检查后端接口是否有权限校验。 +6. 检查 loading、empty、error、forbidden 状态是否缺失。 +7. 标注不确定点。 + +## 输出格式 + +| 检查项 | 文件 | 现状 | 问题 | 建议 | 验收 | +| --- | --- | --- | --- | --- | --- | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/commands/工单需求拆解.command.md b/cases/jeecgboot-work-order/ai-dev-assets/commands/工单需求拆解.command.md new file mode 100644 index 0000000..7797983 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/commands/工单需求拆解.command.md @@ -0,0 +1,26 @@ +# /工单需求拆解 + +## 使用场景 + +把“工单管理”这类业务需求拆成用户故事、字段、接口、状态和验收标准。 + +## 输入 + +- 原始需求说明。 +- 角色列表。 +- 当前项目规则。 +- 已定位的源码依据。 + +## 执行要求 + +1. 先列业务目标和非目标范围。 +2. 按角色拆用户故事。 +3. 输出字段清单和字典需求。 +4. 输出接口候选清单。 +5. 标注需要业务确认的不确定点。 + +## 输出格式 + +| 用户故事 | 角色 | 目标 | 字段/接口 | 验收标准 | 不确定点 | +| --- | --- | --- | --- | --- | --- | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/commands/接口契约生成.command.md b/cases/jeecgboot-work-order/ai-dev-assets/commands/接口契约生成.command.md new file mode 100644 index 0000000..5581a1a --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/commands/接口契约生成.command.md @@ -0,0 +1,27 @@ +# /接口契约生成 + +## 使用场景 + +需求拆解后，用于生成工单模块接口契约初稿。 + +## 输入 + +- 需求拆解表。 +- 字段清单。 +- 权限矩阵。 +- 状态流转表。 +- JeecgBoot API 约定。 + +## 执行要求 + +1. 覆盖列表、详情、新增、编辑、指派、状态流转、审计、看板。 +2. 每个接口写方法、路径、参数、响应、权限字符。 +3. 每个接口写成功和失败场景。 +4. 每个接口写验收方式。 +5. 路径建议必须标注为建议，不伪装成已有事实。 + +## 输出格式 + +| 接口 | 方法 | 路径建议 | 参数 | 响应 | 权限 | 失败场景 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | --- | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/commands/模块结构分析.command.md b/cases/jeecgboot-work-order/ai-dev-assets/commands/模块结构分析.command.md new file mode 100644 index 0000000..a5cc128 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/commands/模块结构分析.command.md @@ -0,0 +1,25 @@ +# /模块结构分析 + +## 使用场景 + +接手 JeecgBoot 或类似前后端分离后台项目时，用于快速建立项目地图。 + +## 输入 + +- 项目根目录。 +- 后端入口文件或父 POM。 +- 前端入口文件或 package.json。 +- 项目知识库或 README。 + +## 执行要求 + +1. 按前端、后端、权限、配置、数据库分组。 +2. 每个结论必须引用路径。 +3. 区分事实、推断、建议、不确定点。 +4. 输出后续应该深入阅读的 5-8 个文件。 + +## 输出格式 + +| 模块 | 路径 | 事实依据 | 作用 | 下一步验证 | +| --- | --- | --- | --- | --- | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/examples/jeecgboot/审计日志缺失反例.md b/cases/jeecgboot-work-order/ai-dev-assets/examples/jeecgboot/审计日志缺失反例.md new file mode 100644 index 0000000..8dba8d6 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/examples/jeecgboot/审计日志缺失反例.md @@ -0,0 +1,32 @@ +# 审计日志缺失反例 + +## 场景 + +工单指派负责人成功，但没有记录审计日志。 + +## 问题表现 + +| 操作 | 结果 | +| --- | --- | +| 张三将工单指派给李四 | 工单负责人变更成功 | +| 查询审计日志 | 没有负责人变更记录 | + +## 风险 + +无法追溯负责人变化，出现延误或争议时无法定位责任。 + +## 修复要求 + +1. 指派成功后写审计日志。 +2. 记录原负责人、新负责人、操作人、时间、来源。 +3. 指派失败不写成功审计。 +4. 多步写入需要事务一致性。 + +## 验收 + +| 操作 | 预期 | +| --- | --- | +| 指派成功 | 审计列表出现 ASSIGN 记录 | +| 指派失败 | 不出现成功审计 | +| 查询详情 | 审计记录可在工单详情查看 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/examples/jeecgboot/权限遗漏反例.md b/cases/jeecgboot-work-order/ai-dev-assets/examples/jeecgboot/权限遗漏反例.md new file mode 100644 index 0000000..0e3cfb7 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/examples/jeecgboot/权限遗漏反例.md @@ -0,0 +1,33 @@ +# 权限遗漏反例 + +## 场景 + +工单删除按钮在前端按权限隐藏，但后端删除接口没有权限校验。 + +## 问题代码表现 + +| 层级 | 表现 | +| --- | --- | +| 前端 | 普通研发账号看不到删除按钮 | +| 后端 | 直接请求 `/workOrder/delete` 仍可删除 | +| 审计 | 删除记录可能缺失 | + +## 风险 + +攻击者或误操作用户可以绕过前端直接调用接口删除工单。 + +## 修复要求 + +1. 后端删除接口增加权限校验。 +2. 删除前校验数据范围。 +3. 删除成功写审计日志。 +4. 无权限账号直接请求接口返回 403 或业务拒绝。 + +## 验收 + +| 账号 | 操作 | 预期 | +| --- | --- | --- | +| 管理员 | 删除允许删除的工单 | 成功并写审计 | +| 普通研发 | 直接请求删除接口 | 失败 | +| 只读用户 | 前端访问删除按钮 | 不可见 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/examples/jeecgboot/看板指标口径不清反例.md b/cases/jeecgboot-work-order/ai-dev-assets/examples/jeecgboot/看板指标口径不清反例.md new file mode 100644 index 0000000..be5ee62 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/examples/jeecgboot/看板指标口径不清反例.md @@ -0,0 +1,31 @@ +# 看板指标口径不清反例 + +## 场景 + +看板展示“平均关闭周期”，但没有说明从哪个时间到哪个时间。 + +## 问题表现 + +| 指标 | 当前说明 | +| --- | --- | +| 平均关闭周期 | 最近工单平均处理时间 | + +## 风险 + +不同人理解不同：可能是创建到关闭，也可能是开始处理到关闭，导致管理判断失真。 + +## 修复要求 + +1. 明确定义为 `close_time - create_time` 或其他确定口径。 +2. 明确是否排除未关闭工单。 +3. 明确时间范围过滤字段。 +4. 用样例数据手工校验。 + +## 验收 + +| 样例 | 预期 | +| --- | --- | +| 工单 A 创建 1 日、关闭 3 日 | 周期 2 天 | +| 未关闭工单 | 不计入平均关闭周期 | +| 过滤 7 月 | 只统计 7 月范围内符合口径的数据 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/examples/jeecgboot/非法状态流转反例.md b/cases/jeecgboot-work-order/ai-dev-assets/examples/jeecgboot/非法状态流转反例.md new file mode 100644 index 0000000..e675156 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/examples/jeecgboot/非法状态流转反例.md @@ -0,0 +1,31 @@ +# 非法状态流转反例 + +## 场景 + +已关闭工单可以直接被改回处理中。 + +## 问题表现 + +| 当前状态 | 动作 | 结果 | +| --- | --- | --- | +| 已关闭 | 开始处理 | 状态变成处理中 | + +## 风险 + +已关闭工单被重新打开但没有重开原因、没有审计、没有负责人确认，导致统计和责任链失真。 + +## 修复要求 + +1. Service 层集中校验状态流转。 +2. 已关闭工单只能通过“重新打开”动作变为新建。 +3. 重新打开必须填写原因。 +4. 所有成功流转写审计日志。 + +## 验收 + +| 操作 | 预期 | +| --- | --- | +| closed -> processing | 失败，状态不变 | +| closed -> reopen -> new | 成功，必须有原因 | +| 重开成功 | 审计记录 oldValue=closed, newValue=new | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/examples/好Command与坏Command对照.md b/cases/jeecgboot-work-order/ai-dev-assets/examples/好Command与坏Command对照.md new file mode 100644 index 0000000..78c6672 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/examples/好Command与坏Command对照.md @@ -0,0 +1,47 @@ +# 好 Command 与坏 Command 对照 + +## 坏 Command + +```md +# /检查代码 + +帮我看看代码有没有问题。 +``` + +问题： + +- 没有使用场景。 +- 没有输入要求。 +- 没有执行步骤。 +- 没有输出格式。 +- 没有验收标准。 + +## 好 Command + +```md +# /代码生成 Review + +## 使用场景 +JeecgBoot 基于 work_order 表生成工单模块基础代码后使用。 + +## 输入 +- 数据表字段说明 +- 生成的前端页面 +- api 模块文件 +- 后端 Controller +- 后端 Service +- 当前 rules + +## 执行要求 +1. 检查字段是否和数据模型一致 +2. 检查查询条件、分页、排序是否完整 +3. 检查状态、优先级、类型是否使用字典或枚举 +4. 检查新增、编辑、删除、导出按钮是否需要权限控制 +5. 检查 loading、empty、error、forbidden 状态是否缺失 +6. 标注不确定点 + +## 输出格式 +| 检查项 | 文件 | 现状 | 问题 | 建议 | 验收 | +|---|---|---|---|---|---| +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/examples/好Plan与坏Plan对照.md b/cases/jeecgboot-work-order/ai-dev-assets/examples/好Plan与坏Plan对照.md new file mode 100644 index 0000000..0099788 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/examples/好Plan与坏Plan对照.md @@ -0,0 +1,55 @@ +# 好 Plan 与坏 Plan 对照 + +## 坏 Plan + +```md +1. 修改后端接口 +2. 修改前端页面 +3. 测试一下 +``` + +问题： + +- 没有目标。 +- 没有范围。 +- 没有不做什么。 +- 没有文件路径。 +- 没有风险和验收。 + +## 好 Plan + +```md +# 工单删除逻辑调整 Plan + +## 目标 +删除工单时补齐后端权限校验和审计日志。 + +## 范围 +- WorkOrderController 删除接口 +- WorkOrderService 删除逻辑 +- 工单审计日志写入 +- 前端删除按钮权限验证 + +## 不做什么 +- 不调整工单状态流转 +- 不重构列表页面 +- 不改动非工单模块 + +## 修改步骤 +| 步骤 | 文件/模块 | 动作 | 风险 | 验收 | +|---|---|---|---|---| +| 1 | Controller | 增加后端权限校验 | 权限字符不一致 | 无权限账号返回 403 | +| 2 | Service | 删除前写审计日志 | 事务不一致 | 删除后能查询审计 | +| 3 | 前端页面 | 检查删除按钮权限 | 只隐藏按钮不安全 | 仍需后端拒绝 | + +## 风险 +- 误删已关闭工单 +- 无权限绕过前端 +- 审计日志缺失 + +## 验收 +- 管理员可删除允许删除的工单 +- 普通研发账号请求删除接口失败 +- 删除操作产生审计记录 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/examples/好Skill与坏Skill对照.md b/cases/jeecgboot-work-order/ai-dev-assets/examples/好Skill与坏Skill对照.md new file mode 100644 index 0000000..0a79b02 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/examples/好Skill与坏Skill对照.md @@ -0,0 +1,50 @@ +# 好 Skill 与坏 Skill 对照 + +## 坏 Skill + +```md +# 工单开发 Skill + +帮我开发工单模块。 +``` + +问题： + +- 没有触发场景。 +- 没有输入材料。 +- 没有执行步骤。 +- 没有输出格式。 +- 没有边界和验收。 + +## 好 Skill + +```md +# JeecgBoot 工单模块开发审查 Skill + +## 触发场景 +涉及工单列表、详情、评论、状态、指派、看板、权限字符、数据权限、操作日志的需求拆解、代码生成或代码修改。 + +## 输入材料 +- PR diff 或相关文件 +- 工单需求说明 +- 数据模型与接口契约 +- 当前 rules +- 前端页面文件 +- api 模块文件 +- 后端 Controller / Service + +## 执行步骤 +1. 识别需求范围和非目标范围 +2. 检查字段、接口契约和页面状态是否完整 +3. 审查 JeecgBoot 生成代码的字段、查询、分页、字典和异常态 +4. 检查新增、编辑、删除、指派、状态变更的前端按钮与后端权限 +5. 检查操作日志、数据权限和测试缺口 +6. 输出风险、不确定点和验收建议 + +## 输出格式 +需求拆解表、接口契约表、代码生成 Review 清单、权限风险表、日志风险表、测试缺口清单、不确定点清单。 + +## 验收标准 +每个关键结论必须标注文件、函数、注解或调用链依据。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/RBAC权限矩阵生成.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/RBAC权限矩阵生成.prompt.md new file mode 100644 index 0000000..84a9100 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/RBAC权限矩阵生成.prompt.md @@ -0,0 +1,25 @@ +# RBAC 权限矩阵生成 Prompt + +```text +请基于 JeecgBoot 工单模块设计 RBAC 权限矩阵。 + +输入材料： +- 工单模块需求：<粘贴需求> +- 角色列表：管理员、工单负责人、研发处理人、测试验证人、只读观察者 +- 功能点：查看列表、查看详情、新建、编辑、指派、状态流转、关闭、删除、查看审计、查看看板、导出 +- 项目依据：<粘贴权限、路由、菜单相关路径> + +输出要求： +1. 先列事实依据：JeecgBoot 权限、菜单、动态路由相关路径。 +2. 输出 RBAC 权限矩阵：角色 x 功能点，允许、拒绝、条件允许。 +3. 输出权限字符建议，必须标注为建议。 +4. 输出页面级、按钮级、接口级、数据范围四层控制。 +5. 输出不确定点：哪些权限必须业务方确认。 +6. 输出验收方式：如何证明权限确实生效。 + +约束： +- 不要直接改代码。 +- 不要把前端按钮隐藏当作安全边界。 +- 所有结论必须区分事实、推断、建议。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/修复记录生成.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/修复记录生成.prompt.md new file mode 100644 index 0000000..24fcfe7 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/修复记录生成.prompt.md @@ -0,0 +1,24 @@ +# 修复记录生成 Prompt + +```text +请根据阶段 Review 报告生成修复记录。 + +输入材料： +- Review 报告：<粘贴> +- 已完成修改说明：<粘贴> +- 验证结果：<粘贴> + +输出表格： +Review 编号 | 问题 | 是否成立 | 修改文件 | 修改说明 | 验证结果 | 资产沉淀 + +要求： +1. 如果问题不成立，说明理由和依据。 +2. 如果问题成立，说明修改了哪些文件。 +3. 每条修复必须有验证结果。 +4. 判断是否需要沉淀为资产，例如权限检查清单、状态流转检查清单、审计日志检查清单。 + +约束： +- 不要模糊写“已修复”。 +- 没有验证结果的修复不能算完成。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/异常态补齐.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/异常态补齐.prompt.md new file mode 100644 index 0000000..17bd793 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/异常态补齐.prompt.md @@ -0,0 +1,24 @@ +# 异常态补齐 Prompt + +```text +请基于 JeecgBoot 工单模块，列出状态流转、指派、删除、查询详情、审计日志、看板相关的异常态和防御性逻辑。 + +输出表格： +场景 | 触发条件 | 前端表现 | 后端响应 | 用户提示 | 测试点 | 验收 + +必须覆盖： +- 权限不足 +- 工单不存在 +- 非法状态流转 +- 重复提交 +- 参数缺失 +- 并发修改 +- 看板无数据 +- 审计日志为空 + +约束： +- 先列异常态，不要直接改代码。 +- 给出每个异常态的验收步骤。 +- 标注事实、推断、建议和不确定点。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/权限控制方案生成.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/权限控制方案生成.prompt.md new file mode 100644 index 0000000..7dcf834 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/权限控制方案生成.prompt.md @@ -0,0 +1,24 @@ +# 权限控制方案生成 Prompt + +```text +请基于工单模块 RBAC 权限矩阵，生成 JeecgBoot 权限控制方案。 + +输入材料： +- RBAC 权限矩阵：<粘贴> +- 接口契约表：<粘贴> +- 当前项目权限相关路径：<粘贴> +- 当前 rules：<粘贴> + +输出要求： +1. 权限控制方案表，列为：操作、前端入口、权限字符、后端接口、后端校验、数据权限、验收。 +2. 影响范围：前端页面、API 文件、后端 Controller、Service、菜单配置、数据权限。 +3. 缺失风险：按钮隐藏、接口未校验、数据范围不清、权限字符不一致。 +4. 无权限访问验收步骤。 +5. 不确定点和需要人工确认的权限边界。 + +约束： +- 不要直接改代码。 +- 后端接口权限必须单独说明。 +- 每个敏感操作必须有验收方式。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/状态流转设计.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/状态流转设计.prompt.md new file mode 100644 index 0000000..58b609b --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/状态流转设计.prompt.md @@ -0,0 +1,34 @@ +# 状态流转设计 Prompt + +```text +请为 JeecgBoot 工单模块设计状态流转规则。 + +状态候选： +- 新建 +- 处理中 +- 待验证 +- 已关闭 +- 已驳回 + +动作候选： +- 指派 +- 开始处理 +- 提交验证 +- 验证通过 +- 验证驳回 +- 关闭 +- 重新打开 + +输出要求： +1. 状态流转表：当前状态、动作、目标状态、允许角色、前置条件、后置动作、验收。 +2. 非法流转清单：当前状态、尝试动作、问题、系统响应、验收。 +3. 接口设计建议。 +4. 测试点清单。 +5. 不确定点。 + +约束： +- 先出状态表，不要直接写 if else。 +- 已关闭、越权、缺少说明、重复提交必须覆盖。 +- 每条规则必须有验收方式。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/看板指标设计.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/看板指标设计.prompt.md new file mode 100644 index 0000000..9851ec7 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/看板指标设计.prompt.md @@ -0,0 +1,28 @@ +# 看板指标设计 Prompt + +```text +请为 JeecgBoot 工单模块设计研发效能看板指标。 + +指标方向： +- 工单总数 +- 未关闭工单数 +- 平均关闭周期 +- 按优先级分布 +- 按类型分布 +- 缺陷趋势 +- 逾期工单数 +- 人员处理负载 + +输出要求： +1. 指标字典：指标名、含义、口径、维度、过滤条件、数据来源、展示方式、权限。 +2. 看板统计接口契约建议。 +3. 空态、错误态、无权限态。 +4. 验收方式。 +5. 不确定点。 + +约束： +- 每个指标必须可计算。 +- 不要只写页面 UI。 +- 指标口径不清必须写入不确定点。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/看板接口验收.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/看板接口验收.prompt.md new file mode 100644 index 0000000..b3f2e75 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/看板接口验收.prompt.md @@ -0,0 +1,27 @@ +# 看板接口验收 Prompt + +```text +请为 JeecgBoot 工单看板统计接口生成验收记录。 + +输入材料： +- 看板指标字典：<粘贴> +- 看板接口契约：<粘贴> +- 权限矩阵：<粘贴> + +输出表格： +验收项 | 账号/条件 | 请求参数 | 预期 | 实际 | 证据 | 结论 + +必须覆盖： +- 有数据 +- 空数据 +- 无权限 +- 过滤条件 +- 指标口径 +- 时间范围 +- 数据范围 + +约束： +- 不要只说“接口正常”。 +- 每个指标至少有一个验收动作。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/阶段Review.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/阶段Review.prompt.md new file mode 100644 index 0000000..99c3843 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/prompts/jeecgboot/阶段Review.prompt.md @@ -0,0 +1,30 @@ +# 阶段 Review Prompt + +```text +请对 JeecgBoot 工单模块阶段交付物做 Review。 + +输入材料： +- RBAC 权限矩阵 +- 权限控制方案 +- 状态流转表 +- 非法流转清单 +- 审计日志 SOP +- 异常态清单 +- 看板指标字典 +- 看板接口验收记录 +- 测试结果或验证记录 + +输出表格： +等级 | 模块 | 问题 | 触发规则 | 风险 | 修复建议 | 验收 + +要求： +1. 问题按 P0/P1/P2/P3 分级。 +2. 每个问题必须说明触发了哪条规则。 +3. 每条建议必须有验收方式。 +4. 输出不确定点和需要人工确认的内容。 + +约束： +- 不要只说整体不错。 +- 不要直接改代码。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/rules/backend.md b/cases/jeecgboot-work-order/ai-dev-assets/rules/backend.md new file mode 100644 index 0000000..b2379e0 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/rules/backend.md @@ -0,0 +1,27 @@ +# 后端规则 + +## 适用范围 + +Spring Boot、Controller、Service、Mapper、权限注解、事务、审计、状态流转。 + +## JeecgBoot 后端约束 + +1. 后端二开必须遵守 `update-begin` / `update-end` 修改痕迹规则。 +2. Controller 返回统一使用项目已有 `Result` 风格。 +3. 查询优先复用项目已有 QueryWrapper/QueryGenerator 约定。 +4. 权限敏感接口必须有后端权限校验，不能只依赖前端按钮隐藏。 +5. 状态流转必须在 Service 层集中校验，不能只在前端限制。 +6. 删除、关闭、指派、状态变更必须考虑审计日志。 +7. 参数校验失败、数据不存在、非法状态、权限不足必须有明确响应。 +8. 涉及多步写入时必须说明事务边界。 + +## 输出验收 + +| 检查项 | 通过标准 | +| --- | --- | +| 修改痕迹 | 新增/修改代码块有 update 注释 | +| 权限 | 无权限账号请求接口被拒绝 | +| 状态 | 非法流转被 Service 拒绝 | +| 审计 | 关键操作有日志记录方案 | +| 事务 | 多表或多步骤写入说明事务 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/rules/delivery.md b/cases/jeecgboot-work-order/ai-dev-assets/rules/delivery.md new file mode 100644 index 0000000..277552b --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/rules/delivery.md @@ -0,0 +1,33 @@ +# 交付规则 + +## 交付前必须准备 + +1. 需求拆解表。 +2. 接口契约表。 +3. 权限矩阵。 +4. 状态流转表和非法流转清单。 +5. 审计日志 SOP。 +6. 异常态清单。 +7. 看板指标字典。 +8. Review 报告。 +9. 修复记录。 + +## PR 或阶段交付说明必须包含 + +- 背景和目标。 +- 修改范围。 +- 不做什么。 +- 关键设计。 +- 测试和验收结果。 +- 风险和回滚建议。 +- AI 辅助使用记录。 + +## 输出验收 + +| 检查项 | 通过标准 | +| --- | --- | +| 范围 | 修改范围和非目标范围明确 | +| 证据 | 关键结论有源码或表格依据 | +| 验收 | 每个风险点有验证动作 | +| 资产 | 可复用内容已归档到资产库 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/rules/frontend.md b/cases/jeecgboot-work-order/ai-dev-assets/rules/frontend.md new file mode 100644 index 0000000..76af7ed --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/rules/frontend.md @@ -0,0 +1,26 @@ +# 前端规则 + +## 适用范围 + +Vue3、Vite、Pinia、路由、API 请求、页面状态、按钮权限、看板和表单。 + +## JeecgBoot 前端约束 + +1. 路径别名优先使用 `/@/`，不要随意引入新的 alias。 +2. API 请求必须复用项目请求层 `defHttp`，不要在页面中直接创建独立 axios 实例。 +3. 用户、权限、动态路由相关状态优先查 Pinia store。 +4. 新增页面必须考虑 loading、empty、error、forbidden 状态。 +5. 按钮权限不能作为安全边界，必须同步检查后端接口权限。 +6. 字典字段优先复用项目已有字典组件或工具，不在页面硬编码中文枚举。 +7. 表单提交必须考虑防重复提交、接口失败和参数校验反馈。 + +## 输出验收 + +| 检查项 | 通过标准 | +| --- | --- | +| API 层 | 页面没有绕过 `defHttp` | +| 权限 | 页面按钮和后端接口都被检查 | +| 状态 | loading、empty、error、forbidden 齐全 | +| 字典 | 状态、优先级、类型不硬编码 | +| 验证 | 给出浏览器或接口验收动作 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/rules/global.md b/cases/jeecgboot-work-order/ai-dev-assets/rules/global.md new file mode 100644 index 0000000..b1e0393 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/rules/global.md @@ -0,0 +1,26 @@ +# 全局 AI 协作规则 + +## 适用范围 + +所有 TRAE 辅助分析、设计、编码、测试、Review 和文档任务。 + +## 必须遵守 + +1. 输出必须区分“事实依据、推断、建议、不确定点、下一步验证”。 +2. 项目事实必须标注文件、函数、接口、配置、日志或数据来源。 +3. 修改代码前必须先说明目标、范围、不做什么、影响文件、风险和验收方式。 +4. 复杂任务必须先生成 Plan，经人工确认后再进入修改。 +5. 不允许凭框架印象替代当前项目源码依据。 +6. 不允许删除历史逻辑，除非先说明影响范围和回滚方案。 +7. 不确定内容必须显式写入“不确定点”，不得包装成确定结论。 + +## 输出验收 + +| 检查项 | 通过标准 | +| --- | --- | +| 事实依据 | 每个关键结论能回到路径或代码 | +| 推断 | 标注为什么是推断 | +| 建议 | 有可执行下一步 | +| 不确定点 | 明确需要谁确认或怎么验证 | +| 验收方式 | 能由人或命令复核 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/rules/security.md b/cases/jeecgboot-work-order/ai-dev-assets/rules/security.md new file mode 100644 index 0000000..cc52561 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/rules/security.md @@ -0,0 +1,29 @@ +# 安全规则 + +## 必须禁止 + +1. 不允许提交密钥、Token、账号、密码、内网地址和真实租户 ID。 +2. 不允许在代码中硬编码生产环境地址。 +3. 不允许把前端按钮隐藏当作接口安全。 +4. 不允许在审计日志中明文记录敏感字段。 +5. 不允许让 AI 自行决定真实角色权限边界。 + +## 权限任务要求 + +权限相关输出必须覆盖： + +- 页面是否可见。 +- 按钮是否可操作。 +- 接口是否可访问。 +- 数据范围是否受限。 +- 无权限访问如何验收。 + +## 输出验收 + +| 检查项 | 通过标准 | +| --- | --- | +| 敏感信息 | 输出未包含真实密钥或账号 | +| 接口安全 | 后端权限校验被明确设计 | +| 审计脱敏 | oldValue/newValue 有脱敏规则 | +| 权限决策 | 标注待业务方确认 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/rules/testing.md b/cases/jeecgboot-work-order/ai-dev-assets/rules/testing.md new file mode 100644 index 0000000..13efed9 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/rules/testing.md @@ -0,0 +1,32 @@ +# 测试规则 + +## 测试覆盖要求 + +每个功能至少覆盖： + +1. 正常流。 +2. 异常流。 +3. 权限流。 +4. 状态流。 +5. 边界值。 + +## JeecgBoot 工单重点测试 + +| 类型 | 必测场景 | +| --- | --- | +| 权限 | 无权限账号直接请求删除/指派/关闭接口 | +| 状态 | closed -> processing 等非法流转 | +| 审计 | 编辑、指派、状态流转是否写审计 | +| 异常态 | 工单不存在、重复提交、参数缺失 | +| 看板 | 空数据、无权限、过滤条件、指标口径 | + +## 输出验收 + +测试建议必须包含： + +- 输入条件。 +- 操作步骤。 +- 预期结果。 +- 验证证据。 +- 不确定点。 + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/JeecgBoot工单模块开发审查.skill.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/JeecgBoot工单模块开发审查.skill.md new file mode 100644 index 0000000..4bc5f74 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/JeecgBoot工单模块开发审查.skill.md @@ -0,0 +1,44 @@ +# JeecgBoot 工单模块开发审查 Skill + +## 触发场景 + +涉及工单列表、详情、评论、状态、指派、看板、权限字符、数据权限、操作日志的需求拆解、代码生成或代码修改。 + +## 输入材料 + +- PR diff 或相关文件。 +- 工单需求说明。 +- 数据模型与接口契约。 +- 当前 rules。 +- 前端页面文件。 +- API 模块文件。 +- 后端 Controller / Service。 +- 权限矩阵。 +- 状态流转表。 +- 审计日志 SOP。 + +## 执行步骤 + +1. 识别需求范围和非目标范围。 +2. 检查字段、接口契约和页面状态是否完整。 +3. 审查 JeecgBoot 生成代码的字段、查询、分页、字典和异常态。 +4. 检查新增、编辑、删除、指派、状态变更的前端按钮与后端权限。 +5. 检查操作日志、数据权限和测试缺口。 +6. 检查看板指标口径和接口验收记录。 +7. 输出风险、不确定点和验收建议。 + +## 输出格式 + +- 需求范围确认。 +- 接口契约问题表。 +- 代码生成 Review 清单。 +- 权限风险表。 +- 状态流转风险表。 +- 审计日志风险表。 +- 测试缺口清单。 +- 不确定点清单。 + +## 验收标准 + +每个关键结论必须标注文件、函数、注解、配置或调用链依据。每条建议必须有验收方式。 + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/SKILL.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/SKILL.md new file mode 100644 index 0000000..36337fa --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/SKILL.md @@ -0,0 +1,73 @@ +--- +name: design-complex-business-module +description: Use when designing a complex enterprise business module that needs RBAC permissions, frontend/backend permission controls, state transitions, illegal transition handling, audit logging, exception states, dashboard metrics, interface contracts, or acceptance-ready design assets. +--- + +# Design Complex Business Module + +## Core Principle + +Design the control surfaces before designing code. For complex business modules, produce permission, state, audit, exception, dashboard, and acceptance assets before implementation planning. + +Do not jump from a requirement to CRUD code. Every business rule must have an owner, a source, and a verification method. + +## Inputs + +Collect what exists, then mark gaps explicitly: + +- Business requirement or user stories. +- Target project paths and project constraints. +- Existing roles, permissions, menus, routes, API layer, backend controllers/services, data model, and audit/logging patterns. +- Known non-goals and delivery deadline. +- Existing rules, checklists, or project knowledge docs. + +If project evidence is missing, label outputs as `建议` or `待确认`, not `事实`. + +## Workflow + +1. Define scope: module name, actors, key workflows, non-goals, and acceptance boundary. +2. Build the RBAC matrix: roles x features, with `允许`, `拒绝`, or `条件允许`. +3. Translate RBAC into a permission control plan: page/menu, button, backend API, and data scope. +4. Design the state machine: states, actions, allowed roles, preconditions, post-actions, and terminal states. +5. List illegal transitions and rejection behavior. +6. Design audit logging: actions, write timing, actor, target, old/new values, source/request id, masking, and failure behavior. +7. Complete exception states: permission denied, missing data, invalid state, duplicate submit, validation failure, concurrency, empty dashboard, empty audit log. +8. Define dashboard metrics: meaning, formula, dimensions, filters, data source, permission, empty state, and manual verification. +9. Produce interface and acceptance notes only after the above assets are consistent. + +## Output Contract + +Generate these assets unless the user narrows scope: + +```text +RBAC权限矩阵 +权限控制方案 +状态流转表 +非法流转清单 +审计日志SOP +异常态清单 +看板指标字典 +看板接口验收记录 +不确定点清单 +``` + +Use the templates in `assets/` when creating files. + +## Quality Gates + +- Every sensitive action has frontend visibility control and backend enforcement. +- Data permissions are not replaced by button hiding. +- Every state transition has a reverse or rejection story, or is explicitly terminal. +- Every illegal transition has expected system response and validation method. +- Every successful critical operation has an audit record; failed operations do not write success audit. +- Every dashboard metric has a formula or filter logic that can be manually checked. +- Every output distinguishes `事实`, `推断`, `建议`, and `待确认`. + +## Common Mistakes + +- Do not design UI first and add permissions later. +- Do not use "admin can do everything" as a complete RBAC design. +- Do not put all status rules into prose; use a state table. +- Do not write "record audit log" without naming fields and write timing. +- Do not define dashboard cards without metric formulas and data scope. +- Do not turn project-specific permission strings into facts without source evidence. diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/agents/openai.yaml b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/agents/openai.yaml new file mode 100644 index 0000000..1d0695e --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "复杂业务模块设计" + short_description: "生成权限状态审计异常态看板等复杂业务设计资产" + default_prompt: "Use $design-complex-business-module to design permissions, state transitions, audit logs, exception states, and dashboard metrics for this business module." + +policy: + allow_implicit_invocation: true diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/RBAC权限矩阵.template.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/RBAC权限矩阵.template.md new file mode 100644 index 0000000..1885beb --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/RBAC权限矩阵.template.md @@ -0,0 +1,16 @@ +# 工单 RBAC 权限矩阵 + +| 功能点 | 管理员 | 工单负责人 | 研发处理人 | 测试验证人 | 只读观察者 | 权限字符建议 | 备注 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 查看列表 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | work:order:list | 按数据范围 | +| 查看详情 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | work:order:query | 仅可见范围 | +| 新建工单 | 允许 | 允许 | 允许 | 允许 | 拒绝 | work:order:add | | +| 编辑工单 | 允许 | 条件允许 | 条件允许 | 拒绝 | 拒绝 | work:order:edit | 状态限制 | +| 指派负责人 | 允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | work:order:assign | | +| 状态流转 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | work:order:transition | 按状态 | +| 关闭工单 | 允许 | 条件允许 | 拒绝 | 条件允许 | 拒绝 | work:order:close | 测试验证后 | +| 删除工单 | 允许 | 拒绝 | 拒绝 | 拒绝 | 拒绝 | work:order:delete | 高危操作 | +| 查看审计日志 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | work:order:audit | | +| 查看看板 | 允许 | 允许 | 条件允许 | 条件允许 | 条件允许 | work:order:dashboard | 按数据范围 | +| 导出数据 | 允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | work:order:export | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/RBAC权限矩阵生成.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/RBAC权限矩阵生成.prompt.md new file mode 100644 index 0000000..84a9100 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/RBAC权限矩阵生成.prompt.md @@ -0,0 +1,25 @@ +# RBAC 权限矩阵生成 Prompt + +```text +请基于 JeecgBoot 工单模块设计 RBAC 权限矩阵。 + +输入材料： +- 工单模块需求：<粘贴需求> +- 角色列表：管理员、工单负责人、研发处理人、测试验证人、只读观察者 +- 功能点：查看列表、查看详情、新建、编辑、指派、状态流转、关闭、删除、查看审计、查看看板、导出 +- 项目依据：<粘贴权限、路由、菜单相关路径> + +输出要求： +1. 先列事实依据：JeecgBoot 权限、菜单、动态路由相关路径。 +2. 输出 RBAC 权限矩阵：角色 x 功能点，允许、拒绝、条件允许。 +3. 输出权限字符建议，必须标注为建议。 +4. 输出页面级、按钮级、接口级、数据范围四层控制。 +5. 输出不确定点：哪些权限必须业务方确认。 +6. 输出验收方式：如何证明权限确实生效。 + +约束： +- 不要直接改代码。 +- 不要把前端按钮隐藏当作安全边界。 +- 所有结论必须区分事实、推断、建议。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/审计日志SOP.template.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/审计日志SOP.template.md new file mode 100644 index 0000000..876d692 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/审计日志SOP.template.md @@ -0,0 +1,40 @@ +# 工单审计日志 SOP + +## 记录原则 + +所有会改变工单关键业务状态、负责人、可见性或结论的动作都必须记录审计日志。 + +## 审计字段 + +| 字段 | 含义 | 示例 | +| --- | --- | --- | +| ticket_id | 工单 ID | WO-001 | +| actor_id | 操作人 ID | 1001 | +| actor_name | 操作人名称 | zhangsan | +| action | 操作类型 | ASSIGN | +| field_name | 变更字段 | assignee | +| old_value | 旧值 | lisi | +| new_value | 新值 | wangwu | +| source | 来源 | web | +| request_id | 请求 ID | req-001 | +| created_at | 操作时间 | 2026-07-01 10:00:00 | + +## 必须记录的动作 + +| 动作 | 写入时机 | oldValue | newValue | 验收 | +| --- | --- | --- | --- | --- | +| 创建工单 | 创建成功后 | 空 | 工单摘要 | 审计列表可见 | +| 编辑字段 | 保存成功后 | 修改前字段 | 修改后字段 | 字段前后值正确 | +| 指派负责人 | 指派成功后 | 原负责人 | 新负责人 | 审计记录负责人变化 | +| 状态流转 | 状态变更成功后 | 原状态 | 新状态 | 审计记录状态变化 | +| 评论新增 | 评论保存后 | 空 | 评论摘要 | 审计记录评论动作 | +| 关闭工单 | 关闭成功后 | 原状态 | 已关闭 | 审计记录关闭时间 | + +## 验收方式 + +1. 执行关键操作后能在审计列表查询到记录。 +2. oldValue/newValue 和实际变更一致。 +3. 敏感字段已脱敏。 +4. 操作失败不写成功审计。 +5. 多步写入失败时审计和业务数据保持一致。 + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/审计日志检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/审计日志检查清单.md new file mode 100644 index 0000000..0e271a4 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/审计日志检查清单.md @@ -0,0 +1,13 @@ +# 审计日志检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 创建记录 | 创建工单后能查询审计记录 | | +| 字段变更 | 编辑关键字段记录 oldValue/newValue | | +| 指派记录 | 指派负责人记录原负责人和新负责人 | | +| 状态记录 | 状态流转记录原状态和新状态 | | +| 操作人 | actor_id 和 actor_name 可追溯 | | +| 来源 | source 或 request_id 可追溯 | | +| 脱敏 | 敏感字段不明文进入审计 | | +| 失败处理 | 操作失败不写成功审计 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/异常态检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/异常态检查清单.md new file mode 100644 index 0000000..e1b6496 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/异常态检查清单.md @@ -0,0 +1,13 @@ +# 异常态检查清单 + +| 异常态 | 必须验证 | 结果 | +| --- | --- | --- | +| 空列表 | 页面显示空状态，不报错 | | +| 详情不存在 | 提示工单不存在，页面不崩溃 | | +| 权限不足 | 前端提示或隐藏，后端拒绝 | | +| 非法状态 | 返回非法流转，状态不变 | | +| 重复提交 | 只成功一次，只写一条有效审计 | | +| 参数缺失 | 返回参数错误，业务数据不变 | | +| 并发修改 | 拒绝覆盖或提示刷新 | | +| 看板无数据 | 图表显示空态，不显示假数据 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/异常态清单.template.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/异常态清单.template.md new file mode 100644 index 0000000..286eaff --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/异常态清单.template.md @@ -0,0 +1,13 @@ +# 工单异常态清单 + +| 场景 | 触发条件 | 前端表现 | 后端响应 | 验收 | +| --- | --- | --- | --- | --- | +| 权限不足 | 无权限操作 | 按钮不可见或提示无权限 | 403 或业务拒绝 | 不完成操作 | +| 工单不存在 | 传入错误 ID | 显示不存在 | 404 或业务错误 | 页面不崩溃 | +| 非法状态流转 | closed -> processing | 提示非法流转 | 状态不变 | 数据状态不变 | +| 重复提交 | 连续点击提交 | 按钮 loading/禁用 | 只处理一次 | 只生成一条有效审计 | +| 参数缺失 | 驳回缺少原因 | 表单校验提示 | 参数错误 | 不改变状态 | +| 并发修改 | 数据版本过期 | 提示刷新 | 拒绝覆盖 | 旧数据不覆盖新数据 | +| 看板无数据 | 无匹配记录 | 空状态 | 返回空集合 | 页面不报错 | +| 审计日志为空 | 无审计记录 | 空状态 | 返回空集合 | 页面不报错 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/异常态补齐.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/异常态补齐.prompt.md new file mode 100644 index 0000000..17bd793 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/异常态补齐.prompt.md @@ -0,0 +1,24 @@ +# 异常态补齐 Prompt + +```text +请基于 JeecgBoot 工单模块，列出状态流转、指派、删除、查询详情、审计日志、看板相关的异常态和防御性逻辑。 + +输出表格： +场景 | 触发条件 | 前端表现 | 后端响应 | 用户提示 | 测试点 | 验收 + +必须覆盖： +- 权限不足 +- 工单不存在 +- 非法状态流转 +- 重复提交 +- 参数缺失 +- 并发修改 +- 看板无数据 +- 审计日志为空 + +约束： +- 先列异常态，不要直接改代码。 +- 给出每个异常态的验收步骤。 +- 标注事实、推断、建议和不确定点。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/权限上线前检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/权限上线前检查清单.md new file mode 100644 index 0000000..cacf893 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/权限上线前检查清单.md @@ -0,0 +1,12 @@ +# 权限上线前检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 菜单权限 | 工单菜单只对授权角色可见 | | +| 按钮权限 | 新增、编辑、删除、指派、状态按钮按权限显示 | | +| 接口权限 | 无权限账号直接请求敏感接口失败 | | +| 数据权限 | 普通用户只能看到授权范围内工单 | | +| 权限字符 | 前端按钮、菜单配置、后端接口命名一致 | | +| 审计 | 权限敏感操作成功后有审计记录 | | +| 反例验证 | 无权限账号不能绕过前端执行删除/指派 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/权限控制方案.template.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/权限控制方案.template.md new file mode 100644 index 0000000..d7d0910 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/权限控制方案.template.md @@ -0,0 +1,12 @@ +# 工单权限控制方案 + +| 操作 | 前端入口 | 权限字符 | 后端接口 | 后端校验 | 数据权限 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| 新增工单 | 新增按钮 | work:order:add | /workOrder/add | 权限注解 | 无 | 无权限账号看不到按钮且直接请求失败 | +| 编辑工单 | 编辑按钮 | work:order:edit | /workOrder/edit | 权限注解 + 状态校验 | 负责人/创建人范围 | 越权账号返回 403 或业务拒绝 | +| 指派负责人 | 指派按钮 | work:order:assign | /workOrder/assign | 权限注解 | 管理员/负责人范围 | 普通研发无法指派他人 | +| 状态流转 | 状态按钮 | work:order:transition | /workOrder/transition | 权限注解 + 状态机校验 | 相关工单范围 | 非法流转失败 | +| 删除工单 | 删除按钮 | work:order:delete | /workOrder/delete | 权限注解 | 管理员范围 | 非管理员返回 403 | +| 查看审计 | 审计页签 | work:order:audit | /workOrder/audit/list | 权限注解 | 相关工单范围 | 无权限不可见且接口拒绝 | +| 看板 | 看板菜单 | work:order:dashboard | /workOrder/dashboard | 权限注解 | 数据范围过滤 | 不同角色数据范围不同 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/权限控制方案生成.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/权限控制方案生成.prompt.md new file mode 100644 index 0000000..7dcf834 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/权限控制方案生成.prompt.md @@ -0,0 +1,24 @@ +# 权限控制方案生成 Prompt + +```text +请基于工单模块 RBAC 权限矩阵，生成 JeecgBoot 权限控制方案。 + +输入材料： +- RBAC 权限矩阵：<粘贴> +- 接口契约表：<粘贴> +- 当前项目权限相关路径：<粘贴> +- 当前 rules：<粘贴> + +输出要求： +1. 权限控制方案表，列为：操作、前端入口、权限字符、后端接口、后端校验、数据权限、验收。 +2. 影响范围：前端页面、API 文件、后端 Controller、Service、菜单配置、数据权限。 +3. 缺失风险：按钮隐藏、接口未校验、数据范围不清、权限字符不一致。 +4. 无权限访问验收步骤。 +5. 不确定点和需要人工确认的权限边界。 + +约束： +- 不要直接改代码。 +- 后端接口权限必须单独说明。 +- 每个敏感操作必须有验收方式。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/状态流转检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/状态流转检查清单.md new file mode 100644 index 0000000..2be5688 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/状态流转检查清单.md @@ -0,0 +1,12 @@ +# 状态流转检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 状态枚举 | 所有状态有统一枚举或字典 | | +| 合法流转 | 状态流转表中的合法路径可执行 | | +| 非法流转 | 非法路径被拒绝且状态不变 | | +| 角色限制 | 不同角色只能执行被授权动作 | | +| 前置条件 | 驳回原因、关闭条件、负责人等校验完整 | | +| 审计日志 | 每次成功流转写审计 | | +| 重复提交 | 重复点击不会产生重复有效流转 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/状态流转表.template.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/状态流转表.template.md new file mode 100644 index 0000000..29456b8 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/状态流转表.template.md @@ -0,0 +1,22 @@ +# 工单状态流转表 + +| 当前状态 | 动作 | 目标状态 | 允许角色 | 前置条件 | 后置动作 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| 新建 | 指派 | 新建 | 管理员/负责人 | 工单未关闭 | 写审计日志 | 指派人变化且状态不变 | +| 新建 | 开始处理 | 处理中 | 研发处理人/负责人 | 已指派处理人 | 写审计日志 | 状态变为处理中 | +| 处理中 | 提交验证 | 待验证 | 研发处理人/负责人 | 处理说明不为空 | 写审计日志 | 状态变为待验证 | +| 待验证 | 验证通过 | 已关闭 | 测试验证人/负责人 | 验证结果通过 | 写审计日志和关闭时间 | 状态变为已关闭 | +| 待验证 | 验证驳回 | 已驳回 | 测试验证人/负责人 | 驳回原因不为空 | 写审计日志 | 状态变为已驳回 | +| 已驳回 | 重新处理 | 处理中 | 研发处理人/负责人 | 驳回原因已读 | 写审计日志 | 状态变为处理中 | +| 已关闭 | 重新打开 | 新建 | 管理员 | 重开原因不为空 | 写审计日志 | 状态变为新建 | + +## 非法流转清单 + +| 当前状态 | 尝试动作 | 问题 | 系统响应 | 验收 | +| --- | --- | --- | --- | --- | +| 已关闭 | 开始处理 | 关闭后不能直接处理 | 返回非法流转 | 状态不变 | +| 新建 | 验证通过 | 未处理不能验证 | 返回非法流转 | 状态不变 | +| 待验证 | 提交验证 | 重复提交验证 | 返回非法流转 | 只保留原状态 | +| 处理中 | 验证通过 | 未进入待验证 | 返回非法流转 | 状态不变 | +| 已驳回 | 关闭 | 驳回后不能直接关闭 | 返回非法流转 | 状态不变 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/状态流转设计.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/状态流转设计.prompt.md new file mode 100644 index 0000000..58b609b --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/状态流转设计.prompt.md @@ -0,0 +1,34 @@ +# 状态流转设计 Prompt + +```text +请为 JeecgBoot 工单模块设计状态流转规则。 + +状态候选： +- 新建 +- 处理中 +- 待验证 +- 已关闭 +- 已驳回 + +动作候选： +- 指派 +- 开始处理 +- 提交验证 +- 验证通过 +- 验证驳回 +- 关闭 +- 重新打开 + +输出要求： +1. 状态流转表：当前状态、动作、目标状态、允许角色、前置条件、后置动作、验收。 +2. 非法流转清单：当前状态、尝试动作、问题、系统响应、验收。 +3. 接口设计建议。 +4. 测试点清单。 +5. 不确定点。 + +约束： +- 先出状态表，不要直接写 if else。 +- 已关闭、越权、缺少说明、重复提交必须覆盖。 +- 每条规则必须有验收方式。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板指标口径检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板指标口径检查清单.md new file mode 100644 index 0000000..b732c20 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板指标口径检查清单.md @@ -0,0 +1,13 @@ +# 看板指标口径检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 指标含义 | 每个指标有业务解释 | | +| 计算口径 | 每个指标有公式或筛选条件 | | +| 时间范围 | 明确按创建时间、关闭时间还是更新时间统计 | | +| 数据范围 | 不同角色的数据范围清楚 | | +| 空数据 | 空数据展示为 0 或空态，不误导 | | +| 分组一致性 | 分组总和能和总数对齐 | | +| 权限 | 无看板权限不能访问接口 | | +| 验收证据 | 至少有一组样例数据手工校验 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板指标字典.template.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板指标字典.template.md new file mode 100644 index 0000000..32da66b --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板指标字典.template.md @@ -0,0 +1,13 @@ +# 工单看板指标字典 + +| 指标 | 含义 | 口径 | 数据来源 | 展示方式 | 权限 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| 工单总数 | 当前筛选范围内工单数量 | count(ticket_id) | 工单表 | 指标卡 | 看板权限 | 与列表同条件数量一致 | +| 未关闭工单数 | 状态不是已关闭的数量 | status != closed | 工单表 | 指标卡 | 看板权限 | 过滤状态验证 | +| 平均关闭周期 | 从创建到关闭平均耗时 | avg(close_time - create_time) | 工单表 | 指标卡/趋势 | 看板权限 | 抽样计算一致 | +| 按优先级分布 | 高中低优先级数量 | group by priority | 工单表/字典 | 饼图/柱状图 | 看板权限 | 分组总和等于总数 | +| 按类型分布 | 缺陷/需求/支持数量 | group by type | 工单表/字典 | 柱状图 | 看板权限 | 分组总和等于总数 | +| 缺陷趋势 | 按日期统计缺陷工单 | type=bug group by date | 工单表 | 折线图 | 看板权限 | 日期范围正确 | +| 逾期工单数 | 超过 SLA 未关闭数量 | due_time < now and status != closed | 工单表 | 指标卡 | 看板权限 | SLA 口径明确 | +| 人员处理负载 | 按负责人统计未关闭数量 | group by assignee | 工单表 | 排行榜 | 管理员/负责人 | 数据范围正确 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板指标设计.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板指标设计.prompt.md new file mode 100644 index 0000000..9851ec7 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板指标设计.prompt.md @@ -0,0 +1,28 @@ +# 看板指标设计 Prompt + +```text +请为 JeecgBoot 工单模块设计研发效能看板指标。 + +指标方向： +- 工单总数 +- 未关闭工单数 +- 平均关闭周期 +- 按优先级分布 +- 按类型分布 +- 缺陷趋势 +- 逾期工单数 +- 人员处理负载 + +输出要求： +1. 指标字典：指标名、含义、口径、维度、过滤条件、数据来源、展示方式、权限。 +2. 看板统计接口契约建议。 +3. 空态、错误态、无权限态。 +4. 验收方式。 +5. 不确定点。 + +约束： +- 每个指标必须可计算。 +- 不要只写页面 UI。 +- 指标口径不清必须写入不确定点。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板接口验收.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板接口验收.prompt.md new file mode 100644 index 0000000..b3f2e75 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板接口验收.prompt.md @@ -0,0 +1,27 @@ +# 看板接口验收 Prompt + +```text +请为 JeecgBoot 工单看板统计接口生成验收记录。 + +输入材料： +- 看板指标字典：<粘贴> +- 看板接口契约：<粘贴> +- 权限矩阵：<粘贴> + +输出表格： +验收项 | 账号/条件 | 请求参数 | 预期 | 实际 | 证据 | 结论 + +必须覆盖： +- 有数据 +- 空数据 +- 无权限 +- 过滤条件 +- 指标口径 +- 时间范围 +- 数据范围 + +约束： +- 不要只说“接口正常”。 +- 每个指标至少有一个验收动作。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板接口验收清单.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板接口验收清单.md new file mode 100644 index 0000000..95e740a --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板接口验收清单.md @@ -0,0 +1,12 @@ +# 看板接口验收清单 + +| 验收项 | 请求条件 | 通过标准 | 结果 | +| --- | --- | --- | --- | +| 默认查询 | 管理员默认条件 | 返回完整指标 | | +| 时间过滤 | 指定 start/end | 只统计时间范围内数据 | | +| 类型过滤 | 指定工单类型 | 只统计对应类型 | | +| 空数据 | 无匹配条件 | 返回 0 或空集合 | | +| 无权限 | 未授权账号 | 返回 403 或业务拒绝 | | +| 数据范围 | 普通角色 | 只返回授权范围 | | +| 指标一致性 | 固定样例数据 | 与手工计算一致 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板接口验收记录.template.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板接口验收记录.template.md new file mode 100644 index 0000000..6ddf072 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/design-complex-business-module/assets/看板接口验收记录.template.md @@ -0,0 +1,11 @@ +# 工单看板接口验收记录 + +| 验收项 | 账号/条件 | 请求参数 | 预期 | 实际 | 证据 | 结论 | +| --- | --- | --- | --- | --- | --- | --- | +| 工单总数 | 管理员 | 默认筛选 | 返回总数 | | | | +| 空数据 | 管理员 + 无匹配条件 | 不存在的日期范围 | 返回空集合或 0 | | | | +| 无权限 | 只读外角色 | 默认筛选 | 返回 403 或业务拒绝 | | | | +| 时间过滤 | 管理员 | start/end | 只统计范围内数据 | | | | +| 数据范围 | 普通研发 | 默认筛选 | 只返回本人相关数据 | | | | +| 指标口径 | 管理员 | 固定样例数据 | 与手工计算一致 | | | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/generate-project-constraints/SKILL.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/generate-project-constraints/SKILL.md new file mode 100644 index 0000000..d5fb05b --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/generate-project-constraints/SKILL.md @@ -0,0 +1,125 @@ +--- +name: generate-project-constraints +description: Use when a user needs to extract project-specific AI coding constraints, team rules, repository rules, .trae rules, Cursor rules, CLAUDE.md/AGENTS.md content, or reusable rules/checklists from an existing software project, including projects without README or explicit instruction files. +--- + +# Generate Project Constraints + +## Core Principle + +Generate constraints from evidence, not preference. Treat instruction files as optional inputs: if they exist, read them first; if not, use code-only mode and infer cautiously from config, source patterns, tests, CI, and runtime behavior. + +Every output rule must be labeled as `硬约束`, `观察性约束`, or `待确认约束`, and every non-obvious rule must cite source paths. + +## Evidence Order + +Read available sources in this order: + +1. Explicit instructions: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.trae/rules`, `.cursor/rules`, `.cursorrules`, `README*`, `CONTRIBUTING*`, team docs. +2. Build/runtime manifests: `package.json`, lockfiles, `pom.xml`, `build.gradle`, `.env*`, `application*.yml`, Docker files, compose files. +3. Quality gates: ESLint, Prettier, Stylelint, Checkstyle, Spotless, PMD, Jest/Vitest/JUnit/Playwright configs, CI workflows. +4. Source patterns: API layer, response wrappers, auth/permission flow, routing, state management, controller/service/repository or mapper layers, error handling, audit/logging. +5. Existing examples: representative modules that already implement the pattern requested by the user. + +If a source category is absent, record it in `缺失证据`, then continue. Never block only because `README.md`, `CLAUDE.md`, or `AGENTS.md` is missing. + +## Constraint Levels + +| Level | Use When | Wording | +| --- | --- | --- | +| `硬约束` | Directly proven by config, build files, CI, runtime settings, or explicit team docs | `必须` / `禁止` | +| `观察性约束` | Repeated pattern appears in existing code but no written rule exists | `默认采用` / `优先复用` | +| `待确认约束` | Needed for delivery but not provable from the repo | `需团队确认` | + +Do not upgrade an observed pattern into a hard rule unless a source explicitly requires it. + +## Workflow + +1. Define scope: target repo path, output path, desired rule categories, and whether the user wants installable Skill assets or plain rules. +2. Inventory sources with fast shell commands such as `rg --files`, `find`, `sed`, and focused `rg` searches. +3. Extract facts into an evidence table: source path, observed fact, affected area, confidence, and candidate rule. +4. Normalize candidate rules into the output contract below. +5. Validate each rule against at least one source path or mark it `待确认约束`. +6. Write rules and checklists. Prefer small files such as `rules/backend.md`, `rules/frontend.md`, `rules/security.md`, `rules/testing.md`, `rules/delivery.md`. +7. Run verification: placeholder scan, broken-path spot checks, and a final pass that every hard/observed rule has evidence. + +## Output Contract + +When the user asks to generate constraints, produce these artifacts unless they request a lighter output: + +```text +ai-dev-assets/ +├── rules/ +│ ├── global.md +│ ├── frontend.md +│ ├── backend.md +│ ├── security.md +│ ├── testing.md +│ └── delivery.md +├── templates/ +│ └── 项目约束提取表.template.md +└── checklists/ + └── 项目约束验收清单.md +``` + +Each rule file should use this structure: + +```md +## 规则名称 + +- 级别：硬约束 | 观察性约束 | 待确认约束 +- 适用场景： +- 必须： +- 禁止： +- 来源证据： +- 验收方式： +- 迁移说明： +``` + +Use `assets/项目约束提取表.template.md` and `assets/项目约束验收清单.md` as copyable starting points when helpful. + +## Code-Only Mode + +Use this when no explicit instruction files exist. + +Required behavior: + +- State that explicit project docs were not found. +- Build constraints from manifests, configs, CI, tests, and repeated source patterns. +- Label all pattern-derived rules as `观察性约束`. +- Create a `待确认约束` section for business delivery rules that the repo cannot prove, such as review gates, branch policy, audit requirements, test minimums, and release process. + +Good wording: + +```md +本项目未发现 `AGENTS.md`、`CLAUDE.md`、`.trae/rules` 或 `README.md` 中的明确 AI 协作规则。以下约束来自配置文件和源码模式；未能由仓库证明的内容已标记为待确认。 +``` + +## JeecgBoot Example + +For the training case only, JeecgBoot evidence can generate rules such as: + +- `硬约束`: backend uses `Result` response wrapper, from backend `CLAUDE.md`. +- `硬约束`: frontend uses `defHttp` and backend menu permission mode, from frontend `CLAUDE.md`. +- `硬约束`: backend modification blocks require `update-begin` / `update-end`, from backend `CLAUDE.md`. +- `观察性约束`: business features should follow existing controller/service/mapper layering after verifying representative modules. + +Keep these examples out of generic outputs unless the target project is JeecgBoot or explicitly similar. + +## Quality Gates + +Before claiming completion: + +- List generated files. +- Scan generated files for unfinished placeholders, dummy names, and empty headings. +- Check hard and observed constraints cite source paths. +- Confirm missing evidence is not silently converted into rules. +- Report which sources were read and which rule categories remain `待确认`. + +## Common Mistakes + +- Do not require `CLAUDE.md`, `AGENTS.md`, or `README.md` to exist. +- Do not turn general best practices into project rules without evidence. +- Do not merge business constraints, technical constraints, and delivery constraints into one vague list. +- Do not omit verification steps; rules are useful only if a learner or team can check them. +- Do not copy JeecgBoot-specific constraints into unrelated projects. diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/generate-project-constraints/agents/openai.yaml b/cases/jeecgboot-work-order/ai-dev-assets/skills/generate-project-constraints/agents/openai.yaml new file mode 100644 index 0000000..43f4885 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/generate-project-constraints/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "项目约束生成" + short_description: "从项目证据提取可执行规则、模板和验收清单" + default_prompt: "Use $generate-project-constraints to extract project-specific AI coding constraints, rules, and checklists from this repository." + +policy: + allow_implicit_invocation: true diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/generate-project-constraints/assets/项目约束提取表.template.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/generate-project-constraints/assets/项目约束提取表.template.md new file mode 100644 index 0000000..2fc3a9f --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/generate-project-constraints/assets/项目约束提取表.template.md @@ -0,0 +1,43 @@ +# 项目约束提取表 + +## 项目信息 + +| 字段 | 内容 | +| --- | --- | +| 项目名称 | | +| 项目路径 | | +| 提取日期 | | +| 提取人 | | +| 目标输出 | rules / prompts / checklists / Skill | + +## 证据扫描记录 + +| 证据类型 | 文件或目录 | 是否存在 | 关键发现 | 备注 | +| --- | --- | --- | --- | --- | +| 显式规则 | AGENTS.md / CLAUDE.md / .trae/rules / .cursor/rules | | | | +| 项目说明 | README / CONTRIBUTING / docs | | | | +| 后端构建 | pom.xml / build.gradle / settings.gradle | | | | +| 前端构建 | package.json / lockfile / vite.config / tsconfig | | | | +| 运行配置 | .env / application.yml / Dockerfile / compose | | | | +| 质量工具 | ESLint / Prettier / Checkstyle / CI / test config | | | | +| 源码模式 | API / Controller / Service / Router / Store | | | | +| 权限与安全 | auth / permission / role / route guard / interceptor | | | | +| 数据与迁移 | schema / migration / mapper / repository | | | | + +## 候选约束 + +| 编号 | 分类 | 约束内容 | 级别 | 来源证据 | 影响范围 | 验收方式 | 迁移说明 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| C-001 | global / frontend / backend / security / testing / delivery | | 硬约束 / 观察性约束 / 待确认约束 | | | | | + +## 缺失证据 + +| 缺失项 | 影响 | 处理方式 | +| --- | --- | --- | +| | | 标记为待确认 / 询问团队 / 暂不生成规则 | + +## 待团队确认 + +| 问题 | 为什么需要确认 | 建议默认值 | 决策人 | +| --- | --- | --- | --- | +| 是否强制单测 | 仓库未发现 CI 或测试要求时无法证明 | 新增核心逻辑需补测试或说明豁免 | 技术负责人 | diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/generate-project-constraints/assets/项目约束生成.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/generate-project-constraints/assets/项目约束生成.prompt.md new file mode 100644 index 0000000..7c25980 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/generate-project-constraints/assets/项目约束生成.prompt.md @@ -0,0 +1,61 @@ +# 项目约束生成 Prompt + +请为下面项目生成可复用的 AI 开发约束资产。 + +## 项目输入 + +- 项目路径： +- 输出路径： +- 目标项目类型： +- 是否需要生成 rules： +- 是否需要生成 checklist： +- 是否需要生成 Skill： + +## 执行要求 + +1. 先扫描项目中是否存在显式规则文件，例如 `AGENTS.md`、`CLAUDE.md`、`.trae/rules`、`.cursor/rules`、`README.md`、`CONTRIBUTING.md`。 +2. 如果不存在显式规则文件，不要停止，进入 code-only 模式。 +3. 从构建配置、运行配置、源码模式、测试配置、CI 配置中提取约束。 +4. 每条约束必须标注为： + - `硬约束`：由配置、CI、构建或显式规则直接证明。 + - `观察性约束`：由多个源码样例归纳，但没有显式规则。 + - `待确认约束`：项目无法证明，但交付前必须团队确认。 +5. 每条硬约束和观察性约束必须标注来源路径。 +6. 不要把通用最佳实践当成项目事实。 +7. 不要把某个项目的专用规则复制到另一个项目。 + +## 输出格式 + +请生成： + +```text +rules/global.md +rules/frontend.md +rules/backend.md +rules/security.md +rules/testing.md +rules/delivery.md +templates/项目约束提取表.template.md +checklists/项目约束验收清单.md +``` + +每条规则使用： + +```md +## 规则名称 + +- 级别： +- 适用场景： +- 必须： +- 禁止： +- 来源证据： +- 验收方式： +- 迁移说明： +``` + +最后输出： + +- 已读来源。 +- 缺失证据。 +- 待确认问题。 +- 不能迁移到其他项目的项目特有约束。 diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/generate-project-constraints/assets/项目约束验收清单.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/generate-project-constraints/assets/项目约束验收清单.md new file mode 100644 index 0000000..7c8f339 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/generate-project-constraints/assets/项目约束验收清单.md @@ -0,0 +1,44 @@ +# 项目约束验收清单 + +## 基础完整性 + +- [ ] 已列出目标项目路径和输出路径。 +- [ ] 已说明是否发现显式规则文件。 +- [ ] 已记录缺失证据，没有因为缺失 README / CLAUDE.md / AGENTS.md 而停止。 +- [ ] 已区分 `硬约束`、`观察性约束`、`待确认约束`。 +- [ ] 每条硬约束都有明确来源路径。 +- [ ] 每条观察性约束至少有一个代表性源码样例。 +- [ ] 每条待确认约束都写明需要谁确认。 + +## 规则质量 + +- [ ] 规则包含适用场景。 +- [ ] 规则包含必须做什么。 +- [ ] 规则包含禁止做什么，或说明没有禁止项。 +- [ ] 规则包含验收方式。 +- [ ] 规则包含迁移说明，说明换项目时能否复用。 +- [ ] 规则没有把通用最佳实践冒充为项目事实。 +- [ ] 规则没有把某个单一代码样例冒充为全项目硬约束。 + +## 覆盖范围 + +- [ ] global 约束覆盖项目理解、证据引用、事实/推断区分。 +- [ ] frontend 约束覆盖包管理器、框架、路径别名、API 层、路由和状态管理。 +- [ ] backend 约束覆盖语言版本、框架、分层、响应结构、异常和数据访问。 +- [ ] security 约束覆盖认证、权限、敏感信息、数据范围和接口防护。 +- [ ] testing 约束覆盖已有测试工具、运行命令和缺失测试时的处理。 +- [ ] delivery 约束覆盖计划、Review、验收记录、发布或交付要求。 + +## 可复用性 + +- [ ] JeecgBoot 等项目特有规则没有写进通用规则。 +- [ ] 每条规则都标注了“可直接复用 / 需重新扫描 / 不可迁移”。 +- [ ] 换项目时必须重新扫描的内容已经列出。 +- [ ] 可以从本清单反推出生成步骤。 + +## 交付检查 + +- [ ] 生成文件中没有未完成占位符、示例假名或空标题。 +- [ ] Markdown 链接或路径经过抽样检查。 +- [ ] 规则文件标题不为空。 +- [ ] 交付说明列出已读来源、未读来源和仍需确认的问题。 diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/SKILL.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/SKILL.md new file mode 100644 index 0000000..916473a --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/SKILL.md @@ -0,0 +1,89 @@ +--- +name: review-business-delivery +description: Use when reviewing complex business delivery artifacts, AI-generated plans, PR diffs, or module designs for permission gaps, illegal state transitions, missing audit logs, weak exception handling, unclear dashboard metrics, missing tests, or incomplete acceptance evidence. +--- + +# Review Business Delivery + +## Core Principle + +Review behavior and risk before wording. Findings must be evidence-based, severity-ranked, and tied to a verification action. + +The review output should help the team decide whether to accept, conditionally accept, or reject the delivery. + +## Inputs + +Use any available inputs: + +- Requirement scope and non-goals. +- RBAC matrix and permission control plan. +- State transition table and illegal transition list. +- Audit SOP and exception-state list. +- Dashboard metric dictionary and API acceptance record. +- Code diff, API contract, test result, Browser verification record, or PR description. +- Project rules and constraints. + +If source evidence is missing, create an `证据缺口` section instead of guessing. + +## Review Flow + +1. Confirm delivery scope: what is being reviewed and what is outside scope. +2. Check source evidence: paths, rules, design tables, test results, and verification records. +3. Review permission risk: page/menu, button, backend API, and data scope. +4. Review state risk: legal transitions, illegal transitions, terminal states, duplicate submits, and role restrictions. +5. Review audit risk: action coverage, field completeness, masking, failure behavior, and consistency with business writes. +6. Review exception risk: empty, missing, invalid, forbidden, duplicate, concurrent, and downstream failure states. +7. Review dashboard risk: formula, filter, dimension, data source, permission, empty state, and manual calculation. +8. Review tests and acceptance: commands, roles, sample data, browser evidence, and unresolved risks. +9. Output findings sorted by severity. + +## Severity + +| Level | Meaning | +| --- | --- | +| P0 | Data loss, privilege bypass, irreversible wrong state, or release-blocking failure | +| P1 | Security, permission, audit, or state-machine defect with realistic business impact | +| P2 | Missing acceptance evidence, unclear metric, weak exception handling, or test gap | +| P3 | Maintainability, naming, documentation, or minor consistency issue | + +## Output Contract + +```md +## Review 结论 + +通过 / 有条件通过 / 不通过 + +## 问题清单 + +| 等级 | 模块 | 问题 | 证据 | 风险 | 修复建议 | 验收方式 | +| --- | --- | --- | --- | --- | --- | --- | + +## 证据缺口 + +| 缺口 | 影响 | 需要谁补充 | +| --- | --- | --- | + +## 待确认 + +| 问题 | 决策人 | 建议默认值 | +| --- | --- | --- | +``` + +Use the templates and checklists in `assets/` when writing files. + +## Quality Gates + +- Findings lead the response; summaries are secondary. +- Every P0/P1 finding cites a source path, table row, endpoint, role, state, metric, or verification record. +- Every finding has a concrete fix direction and acceptance method. +- Review does not accept frontend-only security controls. +- Missing tests or missing evidence are called out explicitly. +- Unclear business rules are marked `待确认`, not invented. + +## Common Mistakes + +- Do not write "整体不错" before listing risks. +- Do not merge all issues into one generic recommendation. +- Do not downgrade permission bypass, illegal state transitions, or missing audit for critical actions. +- Do not claim an issue is fixed without verification evidence. +- Do not review only code style when the requested delivery is business behavior. diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/agents/openai.yaml b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/agents/openai.yaml new file mode 100644 index 0000000..f2dc7c9 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "业务交付 Review" + short_description: "审查权限状态审计异常态看板测试与验收风险" + default_prompt: "Use $review-business-delivery to review complex business delivery artifacts for permission, state, audit, exception, and dashboard risks." + +policy: + allow_implicit_invocation: true diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/AIReview报告模板.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/AIReview报告模板.md new file mode 100644 index 0000000..0fe0982 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/AIReview报告模板.md @@ -0,0 +1,28 @@ +# AI Review 报告模板 + +## Review 输入 + +- PR diff： +- 需求说明： +- rules： +- 测试结果： +- 历史问题： + +## 结论 + +通过 / 有条件通过 / 不通过 + +## 问题清单 + +| 等级 | 文件/模块 | 问题 | 触发规则 | 风险 | 建议 | 测试/验收 | +| --- | --- | --- | --- | --- | --- | --- | + +## 不确定点 + +| 不确定点 | 需要谁确认 | 验证方式 | +| --- | --- | --- | + +## 是否建议合入 + +说明理由。 + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/审计日志检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/审计日志检查清单.md new file mode 100644 index 0000000..0e271a4 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/审计日志检查清单.md @@ -0,0 +1,13 @@ +# 审计日志检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 创建记录 | 创建工单后能查询审计记录 | | +| 字段变更 | 编辑关键字段记录 oldValue/newValue | | +| 指派记录 | 指派负责人记录原负责人和新负责人 | | +| 状态记录 | 状态流转记录原状态和新状态 | | +| 操作人 | actor_id 和 actor_name 可追溯 | | +| 来源 | source 或 request_id 可追溯 | | +| 脱敏 | 敏感字段不明文进入审计 | | +| 失败处理 | 操作失败不写成功审计 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/异常态检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/异常态检查清单.md new file mode 100644 index 0000000..e1b6496 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/异常态检查清单.md @@ -0,0 +1,13 @@ +# 异常态检查清单 + +| 异常态 | 必须验证 | 结果 | +| --- | --- | --- | +| 空列表 | 页面显示空状态，不报错 | | +| 详情不存在 | 提示工单不存在，页面不崩溃 | | +| 权限不足 | 前端提示或隐藏，后端拒绝 | | +| 非法状态 | 返回非法流转，状态不变 | | +| 重复提交 | 只成功一次，只写一条有效审计 | | +| 参数缺失 | 返回参数错误，业务数据不变 | | +| 并发修改 | 拒绝覆盖或提示刷新 | | +| 看板无数据 | 图表显示空态，不显示假数据 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/权限上线前检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/权限上线前检查清单.md new file mode 100644 index 0000000..cacf893 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/权限上线前检查清单.md @@ -0,0 +1,12 @@ +# 权限上线前检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 菜单权限 | 工单菜单只对授权角色可见 | | +| 按钮权限 | 新增、编辑、删除、指派、状态按钮按权限显示 | | +| 接口权限 | 无权限账号直接请求敏感接口失败 | | +| 数据权限 | 普通用户只能看到授权范围内工单 | | +| 权限字符 | 前端按钮、菜单配置、后端接口命名一致 | | +| 审计 | 权限敏感操作成功后有审计记录 | | +| 反例验证 | 无权限账号不能绕过前端执行删除/指派 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/状态流转检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/状态流转检查清单.md new file mode 100644 index 0000000..2be5688 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/状态流转检查清单.md @@ -0,0 +1,12 @@ +# 状态流转检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 状态枚举 | 所有状态有统一枚举或字典 | | +| 合法流转 | 状态流转表中的合法路径可执行 | | +| 非法流转 | 非法路径被拒绝且状态不变 | | +| 角色限制 | 不同角色只能执行被授权动作 | | +| 前置条件 | 驳回原因、关闭条件、负责人等校验完整 | | +| 审计日志 | 每次成功流转写审计 | | +| 重复提交 | 重复点击不会产生重复有效流转 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/看板指标口径检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/看板指标口径检查清单.md new file mode 100644 index 0000000..b732c20 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/看板指标口径检查清单.md @@ -0,0 +1,13 @@ +# 看板指标口径检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 指标含义 | 每个指标有业务解释 | | +| 计算口径 | 每个指标有公式或筛选条件 | | +| 时间范围 | 明确按创建时间、关闭时间还是更新时间统计 | | +| 数据范围 | 不同角色的数据范围清楚 | | +| 空数据 | 空数据展示为 0 或空态，不误导 | | +| 分组一致性 | 分组总和能和总数对齐 | | +| 权限 | 无看板权限不能访问接口 | | +| 验收证据 | 至少有一组样例数据手工校验 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/看板接口验收清单.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/看板接口验收清单.md new file mode 100644 index 0000000..95e740a --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/看板接口验收清单.md @@ -0,0 +1,12 @@ +# 看板接口验收清单 + +| 验收项 | 请求条件 | 通过标准 | 结果 | +| --- | --- | --- | --- | +| 默认查询 | 管理员默认条件 | 返回完整指标 | | +| 时间过滤 | 指定 start/end | 只统计时间范围内数据 | | +| 类型过滤 | 指定工单类型 | 只统计对应类型 | | +| 空数据 | 无匹配条件 | 返回 0 或空集合 | | +| 无权限 | 未授权账号 | 返回 403 或业务拒绝 | | +| 数据范围 | 普通角色 | 只返回授权范围 | | +| 指标一致性 | 固定样例数据 | 与手工计算一致 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/阶段Review.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/阶段Review.prompt.md new file mode 100644 index 0000000..99c3843 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/阶段Review.prompt.md @@ -0,0 +1,30 @@ +# 阶段 Review Prompt + +```text +请对 JeecgBoot 工单模块阶段交付物做 Review。 + +输入材料： +- RBAC 权限矩阵 +- 权限控制方案 +- 状态流转表 +- 非法流转清单 +- 审计日志 SOP +- 异常态清单 +- 看板指标字典 +- 看板接口验收记录 +- 测试结果或验证记录 + +输出表格： +等级 | 模块 | 问题 | 触发规则 | 风险 | 修复建议 | 验收 + +要求： +1. 问题按 P0/P1/P2/P3 分级。 +2. 每个问题必须说明触发了哪条规则。 +3. 每条建议必须有验收方式。 +4. 输出不确定点和需要人工确认的内容。 + +约束： +- 不要只说整体不错。 +- 不要直接改代码。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/阶段Review报告.template.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/阶段Review报告.template.md new file mode 100644 index 0000000..eba0738 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/阶段Review报告.template.md @@ -0,0 +1,28 @@ +# 阶段 Review 报告 + +## Review 输入 + +- RBAC 权限矩阵： +- 权限控制方案： +- 状态流转表： +- 非法流转清单： +- 审计日志 SOP： +- 异常态清单： +- 看板指标字典： +- 看板接口验收记录： + +## 问题清单 + +| 等级 | 模块 | 问题 | 触发规则 | 风险 | 修复建议 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| P1 | 权限 | 删除接口只隐藏按钮，后端缺少权限校验 | 前端按钮不是安全边界 | 可绕过前端删除工单 | 后端补权限校验 | 无权限账号请求返回 403 | + +## 不确定点 + +| 不确定点 | 影响 | 需要谁确认 | +| --- | --- | --- | + +## 结论 + +通过 / 有条件通过 / 不通过 + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/验收清单.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/验收清单.md new file mode 100644 index 0000000..230cd33 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/review-business-delivery/assets/验收清单.md @@ -0,0 +1,71 @@ +# 验收清单 + +本清单用于判断学员是否真正掌握 JeecgBoot 工单案例，而不是只复制了 TRAE 输出。建议讲师在小组展示时逐项打分。 + +## 项目理解 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 能说明 JeecgBoot 前后端目录 | 至少指出 `jeecg-boot`、`jeecgboot-vue3`、`docs/project-knowledge` 的用途 | | +| 能定位后端入口 | 能指出 `JeecgSystemApplication.java` 和后端启动模块 | | +| 能定位前端入口 | 能指出 `src/main.ts`、路由、Pinia 和 API 请求层 | | +| 能区分事实和推断 | 对没有源码依据的业务规则标注为推断或待确认 | | +| 能记录不确定点 | 不确定内容没有被包装成确定事实 | | + +## 需求与接口 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 用户故事完整 | 覆盖管理员、负责人、研发、测试、只读用户 | | +| 非目标范围明确 | 明确课堂不做完整编码、生产部署、真实数据迁移 | | +| 接口契约完整 | 覆盖列表、详情、新增、编辑、指派、状态、审计、看板 | | +| 失败场景明确 | 每个关键接口至少有权限、参数、状态或数据不存在失败场景 | | +| 验收方式明确 | 每个关键需求都有可执行检查方法 | | + +## 权限与状态 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 权限矩阵完整 | 覆盖页面级、按钮级、接口级和数据范围 | | +| 权限字符合理 | 命名统一，并标注为建议而非源码事实 | | +| 后端权限未缺失 | 没有用前端按钮隐藏替代后端接口控制 | | +| 状态流转表完整 | 覆盖新建、处理中、待验证、已关闭、已驳回 | | +| 非法流转明确 | 至少列出 5 条非法流转和拒绝原因 | | + +## 审计、异常态与看板 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 审计操作覆盖关键动作 | 创建、编辑、指派、状态流转、关闭、评论至少覆盖 5 类 | | +| 审计字段可追溯 | 包含 actor、action、targetId、oldValue、newValue、source | | +| 敏感信息处理 | oldValue/newValue 有脱敏说明 | | +| 异常态可测试 | 权限不足、重复提交、非法状态、数据不存在、并发修改均覆盖 | | +| 看板指标可计算 | 每个指标有口径、维度、过滤条件和数据来源建议 | | + +## Review 与交付 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| Review 有证据 | 问题能回到路径、表格或业务规则 | | +| 风险按严重程度排序 | 高风险问题优先展示 | | +| 建议可行动 | 每条建议有修复方向和验收方式 | | +| 交付物齐全 | [worksheets.md](./worksheets.md) 中最终交付记录完整 | | +| 能沉淀资产 | 能说明哪些内容进入 [assets-index.md](./assets-index.md) 的资产库 | | + +## 评分建议 + +| 等级 | 分数 | 描述 | +| --- | ---: | --- | +| A | 90-100 | 依据充分，设计完整，风险清楚，验收可执行 | +| B | 75-89 | 主链路完整，少量不确定点或验收细节不足 | +| C | 60-74 | 有基本产出，但权限、状态、审计或异常态明显薄弱 | +| D | 0-59 | 泛泛总结项目，缺少源码依据或无法验收 | + +## 讲师判定原则 + +- 优先看证据，不优先看文字是否漂亮。 +- 优先看权限、状态、审计、异常态，不只看 CRUD。 +- 优先看不确定点是否被诚实标出。 +- 优先看能否复用到团队资产库。 +- 对没有依据的自信结论扣分。 + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/SKILL.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/SKILL.md new file mode 100644 index 0000000..67b0c6c --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/SKILL.md @@ -0,0 +1,94 @@ +--- +name: track-review-fix-loop +description: Use when turning review findings into a fix-tracking record, deciding whether findings are valid, mapping fixes to files, verifying results, documenting unresolved items, or deciding which issues should become reusable rules, checklists, prompts, examples, or team assets. +--- + +# Track Review Fix Loop + +## Core Principle + +A review issue is not closed by saying "fixed". It closes only when the team records validity, changed artifacts, verification evidence, unresolved risk, and whether the lesson should become a reusable asset. + +## Inputs + +- Review report with numbered findings. +- Requirement or acceptance criteria. +- Code diff, design document, generated tables, or changed files. +- Test results, Browser verification evidence, API response samples, or manual validation notes. +- Existing team rules, checklists, examples, and asset index. + +If validation evidence is missing, mark the item as `未闭环`. + +## Status Model + +Use one of these statuses for each review item: + +| Status | Meaning | +| --- | --- | +| `成立-已修复` | Finding is valid, changed artifacts are listed, and verification evidence exists | +| `成立-暂不修复` | Finding is valid but deferred with reason, owner, and follow-up date | +| `不成立` | Finding is invalid with evidence | +| `需确认` | Finding depends on business or technical decision not available in current evidence | +| `未闭环` | Fix is claimed but evidence is missing | + +## Workflow + +1. Normalize review findings: ensure each issue has an ID, severity, module, risk, and suggested verification. +2. Decide validity: `成立`, `不成立`, or `需确认`; cite evidence. +3. Map valid fixes to changed files, tables, prompts, rules, or templates. +4. Verify each fix using commands, API checks, browser steps, role-based tests, or manual calculation. +5. Identify regressions: related permissions, states, audit actions, dashboard metrics, and exception states to re-check. +6. Decide asset sedimentation: rule, checklist, prompt, Command, Skill, example, or no asset. +7. Output unresolved items with owner and next step. + +## Output Contract + +```md +## 修复闭环结论 + +完成 / 部分完成 / 未完成 + +## 修复记录 + +| Review 编号 | 等级 | 问题 | 状态 | 修改文件/产物 | 验证证据 | 剩余风险 | 资产沉淀 | +| --- | --- | --- | --- | --- | --- | --- | --- | + +## 未闭环事项 + +| 编号 | 原因 | 负责人 | 下一步 | 截止时间 | +| --- | --- | --- | --- | --- | + +## 资产更新建议 + +| 来源问题 | 资产类型 | 建议文件 | 更新内容 | +| --- | --- | --- | --- | +``` + +Use `assets/修复记录.template.md` and `assets/Review修复闭环检查清单.md` when creating files. + +## Asset Decision Guide + +| If the issue is... | Asset | +| --- | --- | +| Repeated project convention violation | rule | +| Repeated review checklist miss | checklist | +| Reusable question or generation pattern | prompt | +| One-step repeatable agent action | command | +| Multi-step judgment workflow | skill | +| Good or bad teaching sample | example | + +## Quality Gates + +- Every fixed issue has verification evidence. +- Every deferred issue has owner and next step. +- Every invalid issue has source evidence, not opinion. +- P0/P1 issues cannot be marked complete without direct verification. +- Asset updates are specific file suggestions, not vague "沉淀经验". + +## Common Mistakes + +- Do not close issues with "已修复" without evidence. +- Do not erase invalid findings; keep why they are invalid. +- Do not mark business decisions as technical fixes. +- Do not create a Skill for a one-off checklist item. +- Do not ignore regressions around permissions, state transitions, audit logs, and dashboard metrics. diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/agents/openai.yaml b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/agents/openai.yaml new file mode 100644 index 0000000..500b19a --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Review 修复闭环" + short_description: "跟踪Review问题成立判断修复验证未闭环与资产沉淀" + default_prompt: "Use $track-review-fix-loop to turn review findings into verified fixes, unresolved decisions, and reusable team assets." + +policy: + allow_implicit_invocation: true diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/Review修复闭环检查清单.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/Review修复闭环检查清单.md new file mode 100644 index 0000000..39df455 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/Review修复闭环检查清单.md @@ -0,0 +1,12 @@ +# Review 修复闭环检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 问题编号 | 每个 Review 问题有编号 | | +| 成立判断 | 每个问题说明是否成立 | | +| 修改说明 | 成立问题说明修改文件和内容 | | +| 验证结果 | 每个修复有验证证据 | | +| 未修复说明 | 暂不修复的问题有原因和后续计划 | | +| 资产沉淀 | 有复用价值的问题已进入检查清单或反例库 | | +| 回归检查 | 修复后重新检查相关权限/状态/审计/看板 | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/修复记录.template.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/修复记录.template.md new file mode 100644 index 0000000..37732cc --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/修复记录.template.md @@ -0,0 +1,8 @@ +# Review 修复记录 + +| Review 编号 | 问题 | 是否成立 | 修改文件 | 修改说明 | 验证结果 | 资产沉淀 | +| --- | --- | --- | --- | --- | --- | --- | +| R01 | 删除接口缺少后端权限校验 | 是 | WorkOrderController | 增加权限校验 | 无权限请求被拒绝 | 权限检查清单 | +| R02 | closed 可重新处理 | 是 | WorkOrderService | 补非法流转校验 | closed -> processing 失败 | 状态流转检查清单 | +| R03 | 看板关闭周期口径不清 | 是 | 指标字典/看板接口 | 明确 create_time 到 close_time | 指标说明已更新 | 看板指标口径清单 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/修复记录生成.prompt.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/修复记录生成.prompt.md new file mode 100644 index 0000000..24fcfe7 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/修复记录生成.prompt.md @@ -0,0 +1,24 @@ +# 修复记录生成 Prompt + +```text +请根据阶段 Review 报告生成修复记录。 + +输入材料： +- Review 报告：<粘贴> +- 已完成修改说明：<粘贴> +- 验证结果：<粘贴> + +输出表格： +Review 编号 | 问题 | 是否成立 | 修改文件 | 修改说明 | 验证结果 | 资产沉淀 + +要求： +1. 如果问题不成立，说明理由和依据。 +2. 如果问题成立，说明修改了哪些文件。 +3. 每条修复必须有验证结果。 +4. 判断是否需要沉淀为资产，例如权限检查清单、状态流转检查清单、审计日志检查清单。 + +约束： +- 不要模糊写“已修复”。 +- 没有验证结果的修复不能算完成。 +``` + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/审计日志缺失反例.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/审计日志缺失反例.md new file mode 100644 index 0000000..8dba8d6 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/审计日志缺失反例.md @@ -0,0 +1,32 @@ +# 审计日志缺失反例 + +## 场景 + +工单指派负责人成功，但没有记录审计日志。 + +## 问题表现 + +| 操作 | 结果 | +| --- | --- | +| 张三将工单指派给李四 | 工单负责人变更成功 | +| 查询审计日志 | 没有负责人变更记录 | + +## 风险 + +无法追溯负责人变化，出现延误或争议时无法定位责任。 + +## 修复要求 + +1. 指派成功后写审计日志。 +2. 记录原负责人、新负责人、操作人、时间、来源。 +3. 指派失败不写成功审计。 +4. 多步写入需要事务一致性。 + +## 验收 + +| 操作 | 预期 | +| --- | --- | +| 指派成功 | 审计列表出现 ASSIGN 记录 | +| 指派失败 | 不出现成功审计 | +| 查询详情 | 审计记录可在工单详情查看 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/权限遗漏反例.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/权限遗漏反例.md new file mode 100644 index 0000000..0e3cfb7 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/权限遗漏反例.md @@ -0,0 +1,33 @@ +# 权限遗漏反例 + +## 场景 + +工单删除按钮在前端按权限隐藏，但后端删除接口没有权限校验。 + +## 问题代码表现 + +| 层级 | 表现 | +| --- | --- | +| 前端 | 普通研发账号看不到删除按钮 | +| 后端 | 直接请求 `/workOrder/delete` 仍可删除 | +| 审计 | 删除记录可能缺失 | + +## 风险 + +攻击者或误操作用户可以绕过前端直接调用接口删除工单。 + +## 修复要求 + +1. 后端删除接口增加权限校验。 +2. 删除前校验数据范围。 +3. 删除成功写审计日志。 +4. 无权限账号直接请求接口返回 403 或业务拒绝。 + +## 验收 + +| 账号 | 操作 | 预期 | +| --- | --- | --- | +| 管理员 | 删除允许删除的工单 | 成功并写审计 | +| 普通研发 | 直接请求删除接口 | 失败 | +| 只读用户 | 前端访问删除按钮 | 不可见 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/看板指标口径不清反例.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/看板指标口径不清反例.md new file mode 100644 index 0000000..be5ee62 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/看板指标口径不清反例.md @@ -0,0 +1,31 @@ +# 看板指标口径不清反例 + +## 场景 + +看板展示“平均关闭周期”，但没有说明从哪个时间到哪个时间。 + +## 问题表现 + +| 指标 | 当前说明 | +| --- | --- | +| 平均关闭周期 | 最近工单平均处理时间 | + +## 风险 + +不同人理解不同：可能是创建到关闭，也可能是开始处理到关闭，导致管理判断失真。 + +## 修复要求 + +1. 明确定义为 `close_time - create_time` 或其他确定口径。 +2. 明确是否排除未关闭工单。 +3. 明确时间范围过滤字段。 +4. 用样例数据手工校验。 + +## 验收 + +| 样例 | 预期 | +| --- | --- | +| 工单 A 创建 1 日、关闭 3 日 | 周期 2 天 | +| 未关闭工单 | 不计入平均关闭周期 | +| 过滤 7 月 | 只统计 7 月范围内符合口径的数据 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/非法状态流转反例.md b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/非法状态流转反例.md new file mode 100644 index 0000000..e675156 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/skills/track-review-fix-loop/assets/非法状态流转反例.md @@ -0,0 +1,31 @@ +# 非法状态流转反例 + +## 场景 + +已关闭工单可以直接被改回处理中。 + +## 问题表现 + +| 当前状态 | 动作 | 结果 | +| --- | --- | --- | +| 已关闭 | 开始处理 | 状态变成处理中 | + +## 风险 + +已关闭工单被重新打开但没有重开原因、没有审计、没有负责人确认，导致统计和责任链失真。 + +## 修复要求 + +1. Service 层集中校验状态流转。 +2. 已关闭工单只能通过“重新打开”动作变为新建。 +3. 重新打开必须填写原因。 +4. 所有成功流转写审计日志。 + +## 验收 + +| 操作 | 预期 | +| --- | --- | +| closed -> processing | 失败，状态不变 | +| closed -> reopen -> new | 成功，必须有原因 | +| 重开成功 | 审计记录 oldValue=closed, newValue=new | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/templates/AIReview报告模板.md b/cases/jeecgboot-work-order/ai-dev-assets/templates/AIReview报告模板.md new file mode 100644 index 0000000..0fe0982 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/templates/AIReview报告模板.md @@ -0,0 +1,28 @@ +# AI Review 报告模板 + +## Review 输入 + +- PR diff： +- 需求说明： +- rules： +- 测试结果： +- 历史问题： + +## 结论 + +通过 / 有条件通过 / 不通过 + +## 问题清单 + +| 等级 | 文件/模块 | 问题 | 触发规则 | 风险 | 建议 | 测试/验收 | +| --- | --- | --- | --- | --- | --- | --- | + +## 不确定点 + +| 不确定点 | 需要谁确认 | 验证方式 | +| --- | --- | --- | + +## 是否建议合入 + +说明理由。 + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/templates/Browser验证报告模板.md b/cases/jeecgboot-work-order/ai-dev-assets/templates/Browser验证报告模板.md new file mode 100644 index 0000000..21f73c8 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/templates/Browser验证报告模板.md @@ -0,0 +1,23 @@ +# Browser 验证报告模板 + +## 验证对象 + +- 页面： +- 分支/版本： +- 账号/角色： +- 浏览器： + +## 验证项 + +| 验收项 | 账号/条件 | 操作步骤 | 预期 | 实际 | 证据 | +| --- | --- | --- | --- | --- | --- | +| 页面打开 | | | | | | +| 主流程 | | | | | | +| 权限态 | | | | | | +| 空态 | | | | | | +| 错误态 | | | | | | + +## 结论 + +通过 / 有条件通过 / 不通过 + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/templates/Plan任务模板.md b/cases/jeecgboot-work-order/ai-dev-assets/templates/Plan任务模板.md new file mode 100644 index 0000000..0f0431d --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/templates/Plan任务模板.md @@ -0,0 +1,36 @@ +# Plan 任务模板 + +## 目标 + +说明本次任务要解决什么问题。 + +## 范围 + +列出会涉及的模块、页面、接口、数据和配置。 + +## 不做什么 + +明确排除项，避免 AI 扩大范围。 + +## 输入材料 + +- 需求说明： +- 源码依据： +- 规则文件： +- 验收标准： + +## 修改步骤 + +| 步骤 | 文件/模块 | 动作 | 风险 | 验收 | +| --- | --- | --- | --- | --- | +| 1 | | | | | + +## 风险点 + +| 风险 | 影响 | 应对 | 验收 | +| --- | --- | --- | --- | + +## 验证方式 + +列出命令、页面操作、账号、数据和预期结果。 + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/RBAC权限矩阵.template.md b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/RBAC权限矩阵.template.md new file mode 100644 index 0000000..1885beb --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/RBAC权限矩阵.template.md @@ -0,0 +1,16 @@ +# 工单 RBAC 权限矩阵 + +| 功能点 | 管理员 | 工单负责人 | 研发处理人 | 测试验证人 | 只读观察者 | 权限字符建议 | 备注 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 查看列表 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | work:order:list | 按数据范围 | +| 查看详情 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | work:order:query | 仅可见范围 | +| 新建工单 | 允许 | 允许 | 允许 | 允许 | 拒绝 | work:order:add | | +| 编辑工单 | 允许 | 条件允许 | 条件允许 | 拒绝 | 拒绝 | work:order:edit | 状态限制 | +| 指派负责人 | 允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | work:order:assign | | +| 状态流转 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | work:order:transition | 按状态 | +| 关闭工单 | 允许 | 条件允许 | 拒绝 | 条件允许 | 拒绝 | work:order:close | 测试验证后 | +| 删除工单 | 允许 | 拒绝 | 拒绝 | 拒绝 | 拒绝 | work:order:delete | 高危操作 | +| 查看审计日志 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | work:order:audit | | +| 查看看板 | 允许 | 允许 | 条件允许 | 条件允许 | 条件允许 | work:order:dashboard | 按数据范围 | +| 导出数据 | 允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | work:order:export | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/修复记录.template.md b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/修复记录.template.md new file mode 100644 index 0000000..37732cc --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/修复记录.template.md @@ -0,0 +1,8 @@ +# Review 修复记录 + +| Review 编号 | 问题 | 是否成立 | 修改文件 | 修改说明 | 验证结果 | 资产沉淀 | +| --- | --- | --- | --- | --- | --- | --- | +| R01 | 删除接口缺少后端权限校验 | 是 | WorkOrderController | 增加权限校验 | 无权限请求被拒绝 | 权限检查清单 | +| R02 | closed 可重新处理 | 是 | WorkOrderService | 补非法流转校验 | closed -> processing 失败 | 状态流转检查清单 | +| R03 | 看板关闭周期口径不清 | 是 | 指标字典/看板接口 | 明确 create_time 到 close_time | 指标说明已更新 | 看板指标口径清单 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/审计日志SOP.template.md b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/审计日志SOP.template.md new file mode 100644 index 0000000..876d692 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/审计日志SOP.template.md @@ -0,0 +1,40 @@ +# 工单审计日志 SOP + +## 记录原则 + +所有会改变工单关键业务状态、负责人、可见性或结论的动作都必须记录审计日志。 + +## 审计字段 + +| 字段 | 含义 | 示例 | +| --- | --- | --- | +| ticket_id | 工单 ID | WO-001 | +| actor_id | 操作人 ID | 1001 | +| actor_name | 操作人名称 | zhangsan | +| action | 操作类型 | ASSIGN | +| field_name | 变更字段 | assignee | +| old_value | 旧值 | lisi | +| new_value | 新值 | wangwu | +| source | 来源 | web | +| request_id | 请求 ID | req-001 | +| created_at | 操作时间 | 2026-07-01 10:00:00 | + +## 必须记录的动作 + +| 动作 | 写入时机 | oldValue | newValue | 验收 | +| --- | --- | --- | --- | --- | +| 创建工单 | 创建成功后 | 空 | 工单摘要 | 审计列表可见 | +| 编辑字段 | 保存成功后 | 修改前字段 | 修改后字段 | 字段前后值正确 | +| 指派负责人 | 指派成功后 | 原负责人 | 新负责人 | 审计记录负责人变化 | +| 状态流转 | 状态变更成功后 | 原状态 | 新状态 | 审计记录状态变化 | +| 评论新增 | 评论保存后 | 空 | 评论摘要 | 审计记录评论动作 | +| 关闭工单 | 关闭成功后 | 原状态 | 已关闭 | 审计记录关闭时间 | + +## 验收方式 + +1. 执行关键操作后能在审计列表查询到记录。 +2. oldValue/newValue 和实际变更一致。 +3. 敏感字段已脱敏。 +4. 操作失败不写成功审计。 +5. 多步写入失败时审计和业务数据保持一致。 + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/异常态清单.template.md b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/异常态清单.template.md new file mode 100644 index 0000000..286eaff --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/异常态清单.template.md @@ -0,0 +1,13 @@ +# 工单异常态清单 + +| 场景 | 触发条件 | 前端表现 | 后端响应 | 验收 | +| --- | --- | --- | --- | --- | +| 权限不足 | 无权限操作 | 按钮不可见或提示无权限 | 403 或业务拒绝 | 不完成操作 | +| 工单不存在 | 传入错误 ID | 显示不存在 | 404 或业务错误 | 页面不崩溃 | +| 非法状态流转 | closed -> processing | 提示非法流转 | 状态不变 | 数据状态不变 | +| 重复提交 | 连续点击提交 | 按钮 loading/禁用 | 只处理一次 | 只生成一条有效审计 | +| 参数缺失 | 驳回缺少原因 | 表单校验提示 | 参数错误 | 不改变状态 | +| 并发修改 | 数据版本过期 | 提示刷新 | 拒绝覆盖 | 旧数据不覆盖新数据 | +| 看板无数据 | 无匹配记录 | 空状态 | 返回空集合 | 页面不报错 | +| 审计日志为空 | 无审计记录 | 空状态 | 返回空集合 | 页面不报错 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/权限控制方案.template.md b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/权限控制方案.template.md new file mode 100644 index 0000000..d7d0910 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/权限控制方案.template.md @@ -0,0 +1,12 @@ +# 工单权限控制方案 + +| 操作 | 前端入口 | 权限字符 | 后端接口 | 后端校验 | 数据权限 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| 新增工单 | 新增按钮 | work:order:add | /workOrder/add | 权限注解 | 无 | 无权限账号看不到按钮且直接请求失败 | +| 编辑工单 | 编辑按钮 | work:order:edit | /workOrder/edit | 权限注解 + 状态校验 | 负责人/创建人范围 | 越权账号返回 403 或业务拒绝 | +| 指派负责人 | 指派按钮 | work:order:assign | /workOrder/assign | 权限注解 | 管理员/负责人范围 | 普通研发无法指派他人 | +| 状态流转 | 状态按钮 | work:order:transition | /workOrder/transition | 权限注解 + 状态机校验 | 相关工单范围 | 非法流转失败 | +| 删除工单 | 删除按钮 | work:order:delete | /workOrder/delete | 权限注解 | 管理员范围 | 非管理员返回 403 | +| 查看审计 | 审计页签 | work:order:audit | /workOrder/audit/list | 权限注解 | 相关工单范围 | 无权限不可见且接口拒绝 | +| 看板 | 看板菜单 | work:order:dashboard | /workOrder/dashboard | 权限注解 | 数据范围过滤 | 不同角色数据范围不同 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/状态流转表.template.md b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/状态流转表.template.md new file mode 100644 index 0000000..29456b8 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/状态流转表.template.md @@ -0,0 +1,22 @@ +# 工单状态流转表 + +| 当前状态 | 动作 | 目标状态 | 允许角色 | 前置条件 | 后置动作 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| 新建 | 指派 | 新建 | 管理员/负责人 | 工单未关闭 | 写审计日志 | 指派人变化且状态不变 | +| 新建 | 开始处理 | 处理中 | 研发处理人/负责人 | 已指派处理人 | 写审计日志 | 状态变为处理中 | +| 处理中 | 提交验证 | 待验证 | 研发处理人/负责人 | 处理说明不为空 | 写审计日志 | 状态变为待验证 | +| 待验证 | 验证通过 | 已关闭 | 测试验证人/负责人 | 验证结果通过 | 写审计日志和关闭时间 | 状态变为已关闭 | +| 待验证 | 验证驳回 | 已驳回 | 测试验证人/负责人 | 驳回原因不为空 | 写审计日志 | 状态变为已驳回 | +| 已驳回 | 重新处理 | 处理中 | 研发处理人/负责人 | 驳回原因已读 | 写审计日志 | 状态变为处理中 | +| 已关闭 | 重新打开 | 新建 | 管理员 | 重开原因不为空 | 写审计日志 | 状态变为新建 | + +## 非法流转清单 + +| 当前状态 | 尝试动作 | 问题 | 系统响应 | 验收 | +| --- | --- | --- | --- | --- | +| 已关闭 | 开始处理 | 关闭后不能直接处理 | 返回非法流转 | 状态不变 | +| 新建 | 验证通过 | 未处理不能验证 | 返回非法流转 | 状态不变 | +| 待验证 | 提交验证 | 重复提交验证 | 返回非法流转 | 只保留原状态 | +| 处理中 | 验证通过 | 未进入待验证 | 返回非法流转 | 状态不变 | +| 已驳回 | 关闭 | 驳回后不能直接关闭 | 返回非法流转 | 状态不变 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/看板指标字典.template.md b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/看板指标字典.template.md new file mode 100644 index 0000000..32da66b --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/看板指标字典.template.md @@ -0,0 +1,13 @@ +# 工单看板指标字典 + +| 指标 | 含义 | 口径 | 数据来源 | 展示方式 | 权限 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| 工单总数 | 当前筛选范围内工单数量 | count(ticket_id) | 工单表 | 指标卡 | 看板权限 | 与列表同条件数量一致 | +| 未关闭工单数 | 状态不是已关闭的数量 | status != closed | 工单表 | 指标卡 | 看板权限 | 过滤状态验证 | +| 平均关闭周期 | 从创建到关闭平均耗时 | avg(close_time - create_time) | 工单表 | 指标卡/趋势 | 看板权限 | 抽样计算一致 | +| 按优先级分布 | 高中低优先级数量 | group by priority | 工单表/字典 | 饼图/柱状图 | 看板权限 | 分组总和等于总数 | +| 按类型分布 | 缺陷/需求/支持数量 | group by type | 工单表/字典 | 柱状图 | 看板权限 | 分组总和等于总数 | +| 缺陷趋势 | 按日期统计缺陷工单 | type=bug group by date | 工单表 | 折线图 | 看板权限 | 日期范围正确 | +| 逾期工单数 | 超过 SLA 未关闭数量 | due_time < now and status != closed | 工单表 | 指标卡 | 看板权限 | SLA 口径明确 | +| 人员处理负载 | 按负责人统计未关闭数量 | group by assignee | 工单表 | 排行榜 | 管理员/负责人 | 数据范围正确 | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/看板接口验收记录.template.md b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/看板接口验收记录.template.md new file mode 100644 index 0000000..6ddf072 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/看板接口验收记录.template.md @@ -0,0 +1,11 @@ +# 工单看板接口验收记录 + +| 验收项 | 账号/条件 | 请求参数 | 预期 | 实际 | 证据 | 结论 | +| --- | --- | --- | --- | --- | --- | --- | +| 工单总数 | 管理员 | 默认筛选 | 返回总数 | | | | +| 空数据 | 管理员 + 无匹配条件 | 不存在的日期范围 | 返回空集合或 0 | | | | +| 无权限 | 只读外角色 | 默认筛选 | 返回 403 或业务拒绝 | | | | +| 时间过滤 | 管理员 | start/end | 只统计范围内数据 | | | | +| 数据范围 | 普通研发 | 默认筛选 | 只返回本人相关数据 | | | | +| 指标口径 | 管理员 | 固定样例数据 | 与手工计算一致 | | | | + diff --git a/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/阶段Review报告.template.md b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/阶段Review报告.template.md new file mode 100644 index 0000000..eba0738 --- /dev/null +++ b/cases/jeecgboot-work-order/ai-dev-assets/templates/jeecgboot/阶段Review报告.template.md @@ -0,0 +1,28 @@ +# 阶段 Review 报告 + +## Review 输入 + +- RBAC 权限矩阵： +- 权限控制方案： +- 状态流转表： +- 非法流转清单： +- 审计日志 SOP： +- 异常态清单： +- 看板指标字典： +- 看板接口验收记录： + +## 问题清单 + +| 等级 | 模块 | 问题 | 触发规则 | 风险 | 修复建议 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| P1 | 权限 | 删除接口只隐藏按钮，后端缺少权限校验 | 前端按钮不是安全边界 | 可绕过前端删除工单 | 后端补权限校验 | 无权限账号请求返回 403 | + +## 不确定点 + +| 不确定点 | 影响 | 需要谁确认 | +| --- | --- | --- | + +## 结论 + +通过 / 有条件通过 / 不通过 + diff --git a/cases/jeecgboot-work-order/assets-index.md b/cases/jeecgboot-work-order/assets-index.md new file mode 100644 index 0000000..47bb66d --- /dev/null +++ b/cases/jeecgboot-work-order/assets-index.md @@ -0,0 +1,232 @@ +# 资产归档索引 + +本文件用于说明 JeecgBoot 工单案例如何沉淀为团队可复用资产。具体可直接复制使用的资产已经生成在 [ai-dev-assets/](./ai-dev-assets/README.md)。 + +如果要发给学员或项目团队，优先发： + +```text +cases/jeecgboot-work-order/ai-dev-assets/ +``` + +## 可沉淀资产 + +| 资产类型 | 来源 | 归档价值 | +| --- | --- | --- | +| 项目源码定位图 | [source-map.md](./source-map.md) | 新人快速理解 JeecgBoot 类项目 | +| Prompt 模板 | [prompts.md](./prompts.md)、[ai-dev-assets/prompts/jeecgboot](./ai-dev-assets/prompts/jeecgboot) | 复用读项目、拆需求、Review 的提问方式 | +| 课堂工作表 | [worksheets.md](./worksheets.md)、[ai-dev-assets/templates/jeecgboot](./ai-dev-assets/templates/jeecgboot) | 标准化小组交付物 | +| 验收清单 | [acceptance-checklist.md](./acceptance-checklist.md)、[ai-dev-assets/checklists/jeecgboot](./ai-dev-assets/checklists/jeecgboot) | 建立统一验收标准 | +| 优秀小组案例 | 学员提交结果 | 建立正向样例 | +| 问题案例 | [ai-dev-assets/examples/jeecgboot](./ai-dev-assets/examples/jeecgboot) | 建立反例和风险库 | +| 讲师经验 | [instructor-guide.md](./instructor-guide.md) | 沉淀授课节奏和常见问题 | + +## 已生成的具体资产 + +### 规则文件 + +- [global.md](./ai-dev-assets/rules/global.md) +- [frontend.md](./ai-dev-assets/rules/frontend.md) +- [backend.md](./ai-dev-assets/rules/backend.md) +- [security.md](./ai-dev-assets/rules/security.md) +- [testing.md](./ai-dev-assets/rules/testing.md) +- [delivery.md](./ai-dev-assets/rules/delivery.md) + +### Command 模板 + +- [模块结构分析.command.md](./ai-dev-assets/commands/模块结构分析.command.md) +- [工单需求拆解.command.md](./ai-dev-assets/commands/工单需求拆解.command.md) +- [接口契约生成.command.md](./ai-dev-assets/commands/接口契约生成.command.md) +- [代码生成Review.command.md](./ai-dev-assets/commands/代码生成Review.command.md) +- [PR说明生成.command.md](./ai-dev-assets/commands/PR说明生成.command.md) + +### Skill 设计卡 + +- [JeecgBoot工单模块开发审查.skill.md](./ai-dev-assets/skills/JeecgBoot工单模块开发审查.skill.md) +- [generate-project-constraints/SKILL.md](./ai-dev-assets/skills/generate-project-constraints/SKILL.md) +- [项目约束提取表.template.md](./ai-dev-assets/skills/generate-project-constraints/assets/项目约束提取表.template.md) +- [项目约束验收清单.md](./ai-dev-assets/skills/generate-project-constraints/assets/项目约束验收清单.md) +- [项目约束生成.prompt.md](./ai-dev-assets/skills/generate-project-constraints/assets/项目约束生成.prompt.md) +- [design-complex-business-module/SKILL.md](./ai-dev-assets/skills/design-complex-business-module/SKILL.md) +- [review-business-delivery/SKILL.md](./ai-dev-assets/skills/review-business-delivery/SKILL.md) +- [track-review-fix-loop/SKILL.md](./ai-dev-assets/skills/track-review-fix-loop/SKILL.md) + +### 通用模板与检查表 + +- [Plan任务模板.md](./ai-dev-assets/templates/Plan任务模板.md) +- [AIReview报告模板.md](./ai-dev-assets/templates/AIReview报告模板.md) +- [Browser验证报告模板.md](./ai-dev-assets/templates/Browser验证报告模板.md) +- [任务成本与能力匹配表.md](./ai-dev-assets/checklists/任务成本与能力匹配表.md) +- [Agent分工表.md](./ai-dev-assets/checklists/Agent分工表.md) +- [CLI-MCP-Skill封装决策表.md](./ai-dev-assets/checklists/CLI-MCP-Skill封装决策表.md) + +### JeecgBoot 专用 Prompt + +- [RBAC权限矩阵生成.prompt.md](./ai-dev-assets/prompts/jeecgboot/RBAC权限矩阵生成.prompt.md) +- [权限控制方案生成.prompt.md](./ai-dev-assets/prompts/jeecgboot/权限控制方案生成.prompt.md) +- [状态流转设计.prompt.md](./ai-dev-assets/prompts/jeecgboot/状态流转设计.prompt.md) +- [异常态补齐.prompt.md](./ai-dev-assets/prompts/jeecgboot/异常态补齐.prompt.md) +- [看板指标设计.prompt.md](./ai-dev-assets/prompts/jeecgboot/看板指标设计.prompt.md) +- [看板接口验收.prompt.md](./ai-dev-assets/prompts/jeecgboot/看板接口验收.prompt.md) +- [阶段Review.prompt.md](./ai-dev-assets/prompts/jeecgboot/阶段Review.prompt.md) +- [修复记录生成.prompt.md](./ai-dev-assets/prompts/jeecgboot/修复记录生成.prompt.md) + +### JeecgBoot 专用模板 + +- [RBAC权限矩阵.template.md](./ai-dev-assets/templates/jeecgboot/RBAC权限矩阵.template.md) +- [权限控制方案.template.md](./ai-dev-assets/templates/jeecgboot/权限控制方案.template.md) +- [状态流转表.template.md](./ai-dev-assets/templates/jeecgboot/状态流转表.template.md) +- [审计日志SOP.template.md](./ai-dev-assets/templates/jeecgboot/审计日志SOP.template.md) +- [异常态清单.template.md](./ai-dev-assets/templates/jeecgboot/异常态清单.template.md) +- [看板指标字典.template.md](./ai-dev-assets/templates/jeecgboot/看板指标字典.template.md) +- [看板接口验收记录.template.md](./ai-dev-assets/templates/jeecgboot/看板接口验收记录.template.md) +- [阶段Review报告.template.md](./ai-dev-assets/templates/jeecgboot/阶段Review报告.template.md) +- [修复记录.template.md](./ai-dev-assets/templates/jeecgboot/修复记录.template.md) + +### JeecgBoot 专用检查清单 + +- [权限上线前检查清单.md](./ai-dev-assets/checklists/jeecgboot/权限上线前检查清单.md) +- [状态流转检查清单.md](./ai-dev-assets/checklists/jeecgboot/状态流转检查清单.md) +- [审计日志检查清单.md](./ai-dev-assets/checklists/jeecgboot/审计日志检查清单.md) +- [异常态检查清单.md](./ai-dev-assets/checklists/jeecgboot/异常态检查清单.md) +- [看板指标口径检查清单.md](./ai-dev-assets/checklists/jeecgboot/看板指标口径检查清单.md) +- [看板接口验收清单.md](./ai-dev-assets/checklists/jeecgboot/看板接口验收清单.md) +- [Review修复闭环检查清单.md](./ai-dev-assets/checklists/jeecgboot/Review修复闭环检查清单.md) + +### 可教学反例 + +- [好Command与坏Command对照.md](./ai-dev-assets/examples/好Command与坏Command对照.md) +- [好Skill与坏Skill对照.md](./ai-dev-assets/examples/好Skill与坏Skill对照.md) +- [好Plan与坏Plan对照.md](./ai-dev-assets/examples/好Plan与坏Plan对照.md) +- [权限遗漏反例.md](./ai-dev-assets/examples/jeecgboot/权限遗漏反例.md) +- [非法状态流转反例.md](./ai-dev-assets/examples/jeecgboot/非法状态流转反例.md) +- [审计日志缺失反例.md](./ai-dev-assets/examples/jeecgboot/审计日志缺失反例.md) +- [看板指标口径不清反例.md](./ai-dev-assets/examples/jeecgboot/看板指标口径不清反例.md) + +## 目录建议 + +团队资产库可以按以下结构归档： + +```text +ai-engineering-assets/ +├── rules/ +│ └── jeecgboot/ +├── prompts/ +│ └── jeecgboot-work-order/ +├── commands/ +│ └── jeecgboot/ +├── skills/ +│ └── jeecgboot-work-order-review/ +├── cases/ +│ └── jeecgboot-work-order/ +├── sop/ +│ └── ai-assisted-development/ +└── reviews/ + └── examples/ +``` + +## 规则资产 + +适合沉淀为 rules 的内容： + +- 修改代码前必须先输出影响范围和验收方式。 +- JeecgBoot 后端修改必须遵守 `update-begin` / `update-end` 注释规则。 +- JeecgBoot 前端修改必须复用 `/@/` alias、`defHttp`、Pinia 和已有组件。 +- 权限相关任务必须覆盖页面级、按钮级、接口级和数据范围。 +- 状态流转任务必须先提供状态表和非法流转清单。 +- 审计任务必须记录 actor、action、targetId、oldValue、newValue、source。 +- 看板任务必须定义指标口径、维度、过滤条件和数据来源。 + +## Prompt 资产 + +适合归档的 Prompt： + +- 项目理解 Prompt。 +- 源码定位 Prompt。 +- 需求拆解 Prompt。 +- 接口契约 Prompt。 +- RBAC 权限矩阵 Prompt。 +- 权限落地检查 Prompt。 +- 状态机设计 Prompt。 +- 审计日志 Prompt。 +- 异常态 Prompt。 +- 看板指标 Prompt。 +- 修改计划 Prompt。 +- Review Prompt。 + +归档时建议增加元数据： + +| 字段 | 示例 | +| --- | --- | +| 名称 | JeecgBoot 工单状态机设计 Prompt | +| 适用项目 | JeecgBoot 3.9.x 类后台项目 | +| 适用阶段 | 设计阶段 | +| 输入材料 | 需求表、权限矩阵、源码依据 | +| 输出格式 | 状态流转表、非法流转清单、测试点 | +| 维护人 | 课程讲师或项目负责人 | +| 更新时间 | 2026-07-01 | + +## Command 与 Skill 资产 + +适合沉淀为 Command 的内容： + +- `/jeecgboot-source-map`：根据项目路径输出源码依据表。 +- `/work-order-rbac-review`：检查权限矩阵是否覆盖页面、按钮、接口和数据范围。 +- `/work-order-state-review`：检查状态流转表和非法流转清单。 +- `/work-order-delivery-review`：按验收清单审查小组交付物。 + +适合沉淀为 Skill 的内容： + +- 跨项目约束生成 Skill。 +- 复杂业务模块设计 Skill。 +- 业务交付 Review Skill。 +- Review 修复闭环 Skill。 +- JeecgBoot 工单模块开发审查 Skill。 +- JeecgBoot 类后台权限落地检查 Skill。 +- JeecgBoot 代码生成后 Review Skill。 + +Skill 应包含： + +- 触发场景。 +- 必需输入。 +- 执行步骤。 +- 输出格式。 +- 验收标准。 +- 禁止事项。 + +## 案例库资产 + +建议沉淀三类案例： + +| 案例类型 | 内容 | 用途 | +| --- | --- | --- | +| 优秀案例 | 证据充分、设计完整、验收清楚的小组成果 | 作为新人参考 | +| 问题案例 | TRAE 幻觉、权限遗漏、状态遗漏、指标不可算 | 作为反例训练 | +| 修复案例 | 从问题交付物到合格交付物的修改过程 | 训练 Review 和迭代 | + +每个案例至少保存： + +- 原始任务。 +- 输入上下文。 +- TRAE 输出。 +- 人工修订。 +- Review 记录。 +- 最终验收结论。 + +## 维护机制 + +| 机制 | 建议 | +| --- | --- | +| 资产负责人 | 每类资产指定一个维护人 | +| 更新频率 | 每次培训后更新一次，项目大版本升级后复核一次 | +| 废弃规则 | 与当前项目不再匹配的 Prompt 和规则必须标记废弃 | +| 评审方式 | 由讲师、项目负责人和一名实际开发者共同评审 | +| 版本记录 | 每次更新记录日期、原因和影响范围 | + +## 课后行动清单 + +1. 从每组交付物中选 1-2 份优秀样例。 +2. 从 Review 中提取 3-5 个问题案例。 +3. 把高频 Prompt 收敛到团队 Prompt 库。 +4. 把稳定检查动作沉淀为 Command 或 Skill。 +5. 把项目约束沉淀到团队 rules。 +6. 约定下一次复核时间和维护人。 diff --git a/cases/jeecgboot-work-order/instructor-guide.md b/cases/jeecgboot-work-order/instructor-guide.md new file mode 100644 index 0000000..0fb00f2 --- /dev/null +++ b/cases/jeecgboot-work-order/instructor-guide.md @@ -0,0 +1,86 @@ +# 讲师手册 + +## 授课定位 + +本案例不是 JeecgBoot 功能讲解课，也不是代码生成演示。它训练的是学员如何用 TRAE 在真实后台项目中建立可靠上下文，控制 AI 输出质量，并把复杂业务拆成可验证的工程产出。 + +讲师要反复强调三点： + +- 先让 TRAE 找依据，再让它下结论。 +- 工单模块是教学案例，不代表当前 JeecgBoot 源码已经实现了完整工单。 +- 复杂业务不能从“写代码”开始，要从权限、状态、审计、异常态和验收开始。 + +## 2 小时版本 + +适合放在第 3 天或第 4 天中间，作为一个集中演练。 + +| 时间 | 内容 | 讲师动作 | 学员产出 | +| --- | --- | --- | --- | +| 10 分钟 | 案例介绍 | 打开 [README.md](./README.md)，说明任务边界 | 明确非目标 | +| 20 分钟 | 项目地图 | 带读 [source-map.md](./source-map.md)，演示如何问 TRAE 找依据 | 源码依据记录表 | +| 25 分钟 | 需求拆解 | 使用 [prompts.md](./prompts.md) 的需求拆解 Prompt | 需求拆解表 | +| 25 分钟 | 权限与状态 | 分组生成 RBAC 权限矩阵和状态流转表 | 权限矩阵、状态流转表 | +| 20 分钟 | 审计与异常态 | 让学员列出必须记录和必须防御的场景 | 审计表、异常态清单 | +| 15 分钟 | Review | 用 [acceptance-checklist.md](./acceptance-checklist.md) 做小组互评 | Review 记录 | +| 5 分钟 | 收束 | 指向 [assets-index.md](./assets-index.md) | 课后资产列表 | + +## 半天版本 + +适合完整覆盖第 3 天后半段或第 4 天前半段。 + +| 模块 | 时长 | 重点 | +| --- | ---: | --- | +| 项目地图和上下文包 | 40 分钟 | 学员必须从 JeecgBoot 实际路径中提取依据 | +| 工单需求和接口契约 | 50 分钟 | 输出字段、接口、页面状态、异常状态 | +| RBAC 权限和状态机 | 60 分钟 | 先做矩阵和流转表，再谈实现计划 | +| 审计、异常态、看板 | 50 分钟 | 把复杂业务补齐，而不是停在 CRUD | +| Review 和交付验收 | 30 分钟 | 要求每组展示“依据、设计、风险、验收” | + +## 1 天版本 + +适合企业内部二开训练。上午做理解和设计，下午做修改计划和 Review。 + +| 阶段 | 时间 | 任务 | +| --- | ---: | --- | +| 上午 1 | 60 分钟 | 读 JeecgBoot 项目知识库和源码定位图 | +| 上午 2 | 90 分钟 | 工单需求拆解、接口契约、页面状态 | +| 上午 3 | 60 分钟 | 权限矩阵、状态流转、非法流转 | +| 下午 1 | 60 分钟 | 审计日志、异常态、防重复提交 | +| 下午 2 | 60 分钟 | 研发效能看板指标设计 | +| 下午 3 | 60 分钟 | 修改计划、测试点、Review 报告 | +| 下午 4 | 30 分钟 | 小组展示和资产沉淀 | + +## 演示路径 + +1. 打开 `../../../JeecgBoot/docs/project-knowledge/README.md`，说明项目知识库的阅读顺序。 +2. 打开 `../../../JeecgBoot/jeecg-boot/CLAUDE.md`，强调后端二开约束和修改痕迹规则。 +3. 打开 `../../../JeecgBoot/jeecgboot-vue3/CLAUDE.md`，强调前端路由、Pinia、API 层和 alias 约定。 +4. 打开 [source-map.md](./source-map.md)，说明课堂只使用已定位路径，不接受泛泛总结。 +5. 打开 [prompts.md](./prompts.md)，现场复制一个“项目理解 Prompt”，要求 TRAE 输出依据、推断、建议和不确定点。 +6. 打开 [worksheets.md](./worksheets.md)，示范如何把 TRAE 输出转成课堂交付物。 + +## 讲师提醒 + +- 当学员直接问“帮我写工单模块”时，要让他们退回 [worksheets.md](./worksheets.md) 的上下文包。 +- 当 TRAE 输出没有文件路径时，要要求补充“依据文件、函数、接口、配置”。 +- 当学员只做列表 CRUD 时，要追问权限、状态流转、审计、异常态和验收。 +- 当学员想让 TRAE 决定角色权限时，要提醒：角色权限是业务事实，TRAE 只能生成初稿。 +- 当学员要改后端代码时，要提醒 `update-begin` / `update-end` 注释规则。 +- 当学员要改前端代码时，要提醒复用项目已有组件、请求层、路由和权限方法。 + +## 常见翻车点 + +| 问题 | 表现 | 讲师处理 | +| --- | --- | --- | +| 上下文过泛 | TRAE 输出 JeecgBoot 通用介绍 | 要求先填源码依据记录表 | +| 直接写代码 | 没有权限矩阵和状态表 | 打回到需求和设计阶段 | +| 权限只隐藏按钮 | 后端接口没有权限边界 | 要求列页面级、按钮级、接口级控制 | +| 状态靠口头约定 | 没有非法流转清单 | 要求列出允许流转和拒绝流转 | +| 审计字段太少 | 只记录操作人和时间 | 补字段前后值、动作、来源、请求 ID | +| 看板指标不可算 | 没有口径、维度和过滤条件 | 要求补指标口径和数据来源 | +| Review 只说“没问题” | 没有证据和风险 | 用 [acceptance-checklist.md](./acceptance-checklist.md) 逐项检查 | + +## 收束话术 + +今天这个案例的重点不是让大家记住 JeecgBoot 某个目录，而是掌握一套可迁移的方法：拿到真实项目后，先建立项目地图，再组织上下文，再让 TRAE 基于证据输出设计和计划。只要任务涉及权限、状态、审计、异常态和看板，就不能从“写代码”开始。真正可交付的 AI 协作，是每一步都有依据、每个设计都有验收、每个不确定点都被标出来。 + diff --git a/cases/jeecgboot-work-order/learner-guide.md b/cases/jeecgboot-work-order/learner-guide.md new file mode 100644 index 0000000..5a8f42b --- /dev/null +++ b/cases/jeecgboot-work-order/learner-guide.md @@ -0,0 +1,202 @@ +# 学员实操手册 + +## 实操目标 + +你要完成一份 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) 自检。若某项无法确认，写入“不确定点”，不要假装已经完成。 + diff --git a/cases/jeecgboot-work-order/prompts.md b/cases/jeecgboot-work-order/prompts.md new file mode 100644 index 0000000..8594795 --- /dev/null +++ b/cases/jeecgboot-work-order/prompts.md @@ -0,0 +1,371 @@ +# Prompt 模板库 + +## 使用规则 + +复制模板前，先把本组实际上下文填入尖括号占位说明处。不要把模板原样丢给 TRAE。 + +每个 Prompt 都必须要求 TRAE 输出： + +```text +事实依据 +推断 +建议 +不确定点 +下一步验证 +``` + +通用约束： + +- 先找依据，再给结论。 +- 不要直接改代码，除非我明确要求进入修改阶段。 +- 项目事实必须标注文件路径、函数、接口、配置或文档来源。 +- 业务规则必须标注为“待人工确认”，不能伪装成源码事实。 +- 涉及权限、状态、审计、删除、看板的内容必须给出验收方式。 + +## 项目理解 Prompt + +```text +请基于以下 JeecgBoot 项目路径，帮我建立工单案例的项目地图。 + +上下文路径： +- ../../../JeecgBoot/docs/project-knowledge/README.md +- ../../../JeecgBoot/jeecg-boot/CLAUDE.md +- ../../../JeecgBoot/jeecgboot-vue3/CLAUDE.md +- ../../../JeecgBoot/jeecg-boot/pom.xml +- ../../../JeecgBoot/jeecgboot-vue3/package.json + +请输出： +1. 事实依据：按后端、前端、权限、配置、数据库分组列路径和作用。 +2. 推断：根据这些路径推断工单模块如果二开，可能落在哪些层。 +3. 建议：课堂应该优先阅读哪些文件。 +4. 不确定点：哪些信息仅靠当前路径无法确认。 +5. 下一步验证：还需要继续查哪些文件或接口。 + +约束： +- 先找依据，再给结论。 +- 不要直接改代码。 +- 不要泛泛介绍 JeecgBoot。 +``` + +## 源码定位 Prompt + +```text +我正在做 JeecgBoot 工单案例，请帮我定位以下主题的源码依据： + +主题： +- 前端页面如何组织 +- 前端 API 请求如何封装 +- 动态路由和权限码如何进入前端 +- 后端 Controller/Service/Mapper 常见结构 +- 后端配置和数据库迁移在哪里 + +已知路径： +- ../../../JeecgBoot/jeecgboot-vue3/src/main.ts +- ../../../JeecgBoot/jeecgboot-vue3/src/router +- ../../../JeecgBoot/jeecgboot-vue3/src/store/modules/permission.ts +- ../../../JeecgBoot/jeecgboot-vue3/src/utils/http/axios +- ../../../JeecgBoot/jeecg-boot/jeecg-module-system +- ../../../JeecgBoot/docs/project-knowledge/generated/backend-endpoints.md +- ../../../JeecgBoot/docs/project-knowledge/generated/frontend-routes.md + +请输出一个源码依据表，列为： +主题 | 路径 | 证据内容 | 对工单案例的意义 | 不确定点 + +约束： +- 事实必须来自路径。 +- 不要直接改代码。 +- 对不能确认的内容写“不确定点”。 +``` + +## 需求拆解 Prompt + +```text +请把“企业工单管理与研发效能看板”拆成适合 JeecgBoot 二开的需求说明。 + +业务目标： +- 管理研发工单、缺陷和支持请求。 +- 支持列表、详情、创建、编辑、指派、状态流转、评论、审计和看板。 + +角色： +- 管理员 +- 工单负责人 +- 研发处理人 +- 测试验证人 +- 只读观察者 + +请输出： +1. 事实依据：当前 JeecgBoot 项目能支撑这类功能的源码或文档路径。 +2. 用户故事：按角色拆分。 +3. 字段清单：字段名、含义、类型、是否必填、字典需求。 +4. 非目标范围：课堂不做哪些功能。 +5. 验收标准：每个用户故事如何验收。 +6. 不确定点：需要业务方确认的规则。 + +约束： +- 先找依据，再给结论。 +- 不要直接改代码。 +- 权限和状态规则必须标注为待人工确认。 +``` + +## 接口契约 Prompt + +```text +请为 JeecgBoot 工单案例设计接口契约，不要写实现代码。 + +必须包含： +- 工单分页列表 +- 工单详情 +- 新增工单 +- 编辑工单 +- 指派负责人 +- 状态流转 +- 查询审计日志 +- 看板指标 + +请输出 Markdown 表格，列为： +接口名称 | 方法 | 路径建议 | 请求参数 | 响应字段 | 权限字符建议 | 成功场景 | 失败场景 | 验收方式 | 事实依据/推断 + +约束： +- 路径建议可以是推断，但必须标注为推断。 +- 事实依据必须引用 JeecgBoot 当前源码或 docs/project-knowledge。 +- 不要直接改代码。 +- 输出不确定点和下一步验证。 +``` + +## RBAC 权限矩阵 Prompt + +```text +请基于 JeecgBoot 工单案例设计 RBAC 权限矩阵。 + +角色： +- 管理员 +- 工单负责人 +- 研发处理人 +- 测试验证人 +- 只读观察者 + +功能点： +- 查看列表 +- 查看详情 +- 新建工单 +- 编辑工单 +- 指派负责人 +- 状态流转 +- 关闭工单 +- 删除工单 +- 查看审计日志 +- 查看看板 +- 导出数据 + +请输出： +1. 事实依据：JeecgBoot 权限、菜单、动态路由相关路径。 +2. 权限矩阵：角色 x 功能点，允许、拒绝、条件允许。 +3. 权限字符建议：例如 work:ticket:add，必须说明只是建议。 +4. 页面级、按钮级、接口级控制方式。 +5. 不确定点：必须人工确认的业务权限。 +6. 验收方式：如何验证权限确实生效。 + +约束： +- 先找依据，再给结论。 +- 不要直接改代码。 +- 不要让前端按钮隐藏替代后端接口权限。 +``` + +## 权限落地检查 Prompt + +```text +请检查以下工单权限设计是否适合 JeecgBoot 项目落地。 + +输入材料： +- RBAC 权限矩阵：<粘贴矩阵> +- 接口契约：<粘贴接口契约> +- 源码依据：<粘贴 source-map 中相关路径> + +请按以下维度 Review： +1. 事实依据：哪些结论能被 JeecgBoot 路径支撑。 +2. 页面级权限是否明确。 +3. 按钮级权限是否明确。 +4. 接口级权限是否明确。 +5. 数据范围是否明确。 +6. 权限字符是否有命名规则。 +7. 缺失项和风险。 +8. 下一步验证。 + +约束： +- 不要直接改代码。 +- 所有建议必须配验收方式。 +``` + +## 状态机设计 Prompt + +```text +请为 JeecgBoot 工单案例设计状态流转规则。 + +候选状态： +- 新建 +- 处理中 +- 待验证 +- 已关闭 +- 已驳回 + +候选动作： +- 指派 +- 开始处理 +- 提交验证 +- 验证通过 +- 验证驳回 +- 关闭 +- 重新打开 + +请输出： +1. 事实依据：当前项目中可参考的状态、字典、业务模块路径。 +2. 状态流转表：当前状态 | 动作 | 目标状态 | 允许角色 | 前置条件 | 后置动作。 +3. 非法流转清单。 +4. 接口设计建议。 +5. 测试点。 +6. 不确定点和下一步验证。 + +约束： +- 先出状态表，不要直接写 if else。 +- 不要直接改代码。 +- 每条流转都要有验收方式。 +``` + +## 审计日志 Prompt + +```text +请为 JeecgBoot 工单案例设计审计日志方案。 + +关键操作： +- 创建工单 +- 编辑标题、描述、优先级、类型 +- 指派负责人 +- 状态流转 +- 新增评论 +- 删除或关闭 +- 权限拒绝的重要操作 + +请输出： +1. 事实依据：JeecgBoot 当前日志、系统模块或项目知识库中可参考的路径。 +2. 审计字段表：字段名 | 含义 | 类型 | 示例 | 是否必填。 +3. 操作记录清单：操作 | 记录时机 | oldValue | newValue | actor | source。 +4. 查询接口建议。 +5. 展示方式建议。 +6. 异常态和验收方式。 +7. 不确定点。 + +约束： +- 不要直接改代码。 +- 字段前后值必须考虑敏感信息脱敏。 +``` + +## 异常态 Prompt + +```text +请基于 JeecgBoot 工单案例，列出必须处理的异常态和防御性逻辑。 + +范围： +- 列表查询 +- 详情查询 +- 新增和编辑 +- 指派 +- 状态流转 +- 删除或关闭 +- 审计日志查询 +- 看板查询 + +请输出表格： +场景 | 异常态 | 触发条件 | 前端表现 | 后端处理 | 用户提示 | 测试点 | 验收方式 + +约束： +- 先列异常态，不要直接改代码。 +- 权限不足、重复提交、非法状态、数据不存在、并发修改必须覆盖。 +- 输出事实、推断、建议、不确定点、下一步验证。 +``` + +## 看板指标 Prompt + +```text +请为 JeecgBoot 工单案例设计研发效能看板指标。 + +指标方向： +- 工单总数 +- 未关闭工单数 +- 平均关闭周期 +- 按优先级分布 +- 按类型分布 +- 缺陷趋势 +- 逾期工单数 +- 人员处理负载 + +请输出： +1. 指标表：指标名 | 口径 | 维度 | 过滤条件 | 数据来源建议 | 图表形式 | 权限要求 | 异常态。 +2. 接口契约建议。 +3. 前端页面状态。 +4. 验收方式。 +5. 不确定点。 + +约束： +- 不要只写页面样式。 +- 每个指标必须可计算。 +- 不要直接改代码。 +``` + +## 修改计划 Prompt + +```text +请基于以下材料，为 JeecgBoot 工单案例生成代码修改计划，但不要直接改代码。 + +输入材料： +- 源码依据表：<粘贴> +- 需求拆解表：<粘贴> +- 接口契约表：<粘贴> +- RBAC 权限矩阵：<粘贴> +- 状态流转表：<粘贴> +- 审计日志设计：<粘贴> +- 异常态清单：<粘贴> + +请输出： +1. 事实依据：涉及哪些已有路径。 +2. 修改范围：后端、前端、配置、数据库、测试。 +3. 分步计划：每一步改什么、为什么、怎么验收。 +4. 风险点：权限、状态、审计、兼容性、数据迁移。 +5. 测试计划：正常流、异常流、权限流、边界值。 +6. 不确定点：必须人工确认后才能实施的内容。 + +约束： +- 不要直接改代码。 +- 后端计划必须提醒遵守 update-begin/update-end 修改痕迹规则。 +- 前端计划必须提醒复用 defHttp、Pinia、动态路由和项目组件。 +``` + +## Review Prompt + +```text +请对以下 JeecgBoot 工单案例交付物做 Review。 + +输入材料： +- 源码依据记录表：<粘贴> +- 需求拆解表：<粘贴> +- 接口契约表：<粘贴> +- RBAC 权限矩阵：<粘贴> +- 状态流转表：<粘贴> +- 审计日志设计表：<粘贴> +- 异常态清单：<粘贴> +- 看板指标表：<粘贴> + +请输出： +1. Review 结论：通过 / 有条件通过 / 不通过。 +2. 事实依据是否充分。 +3. 高风险问题：按严重程度排序。 +4. 遗漏项：权限、状态、审计、异常态、看板、测试。 +5. 不确定点：必须人工确认的业务规则。 +6. 修复建议：每条建议都要有验收方式。 +7. 下一步验证。 + +约束： +- 不要只说“整体不错”。 +- 不要直接改代码。 +- 问题必须可定位、可验证、可行动。 +``` + diff --git a/cases/jeecgboot-work-order/source-map.md b/cases/jeecgboot-work-order/source-map.md new file mode 100644 index 0000000..6415657 --- /dev/null +++ b/cases/jeecgboot-work-order/source-map.md @@ -0,0 +1,97 @@ +# 源码定位图 + +本文件只记录当前本地 JeecgBoot 快照中已经观察到的路径。课堂中可以让 TRAE 基于这些路径继续追踪调用链，但不能把没有路径依据的内容当作事实。 + +## 项目知识库入口 + +| 主题 | 路径 | 用途 | +| --- | --- | --- | +| 项目知识库入口 | `../../../JeecgBoot/docs/project-knowledge/README.md` | 阅读顺序、架构文档和生成索引入口 | +| 项目语境 | `../../../JeecgBoot/docs/project-knowledge/CONTEXT.md` | 产品语境、核心名词、角色和不变量 | +| 上下文地图 | `../../../JeecgBoot/docs/project-knowledge/CONTEXT-MAP.md` | 限界上下文和运行边界 | +| 架构说明 | `../../../JeecgBoot/docs/project-knowledge/01-architecture.md` | 系统形态、请求流和数据流 | +| 运行说明 | `../../../JeecgBoot/docs/project-knowledge/02-runtime.md` | 本地、Docker、微服务运行模式 | +| 后端说明 | `../../../JeecgBoot/docs/project-knowledge/03-backend.md` | 后端模块、API 和 CRUD 约定 | +| 前端说明 | `../../../JeecgBoot/docs/project-knowledge/04-frontend.md` | 前端启动链路、路由、状态和 API 客户端 | +| 权限说明 | `../../../JeecgBoot/docs/project-knowledge/06-auth-permissions.md` | Token、Shiro、菜单和按钮权限生命周期 | +| 扩展指南 | `../../../JeecgBoot/docs/project-knowledge/07-extension-guide.md` | 基于源码的功能扩展路径 | + +## 后端入口与模块 + +| 主题 | 路径 | 课堂用途 | +| --- | --- | --- | +| 后端父 POM | `../../../JeecgBoot/jeecg-boot/pom.xml` | 判断 Maven 多模块、Spring Boot 版本、Java 版本 | +| 后端协作约束 | `../../../JeecgBoot/jeecg-boot/CLAUDE.md` | 查看模块结构、运行命令、修改痕迹规则 | +| 单体启动类 | `../../../JeecgBoot/jeecg-boot/jeecg-module-system/jeecg-system-start/src/main/java/org/jeecg/JeecgSystemApplication.java` | 后端启动入口 | +| 系统启动模块 | `../../../JeecgBoot/jeecg-boot/jeecg-module-system/jeecg-system-start` | 单体应用配置、启动和资源 | +| 系统业务模块 | `../../../JeecgBoot/jeecg-boot/jeecg-module-system/jeecg-system-biz` | 用户、角色、权限、菜单等系统业务 | +| 系统 API 模块 | `../../../JeecgBoot/jeecg-boot/jeecg-module-system/jeecg-system-api` | 单体和微服务 API 切换 | +| 基础核心模块 | `../../../JeecgBoot/jeecg-boot/jeecg-boot-base-core` | Shiro/JWT、MyBatis-Plus、通用工具 | +| 示例模块 | `../../../JeecgBoot/jeecg-boot/jeecg-boot-module/jeecg-module-demo` | 课堂可参考 CRUD 示例结构 | +| AI/RAG 模块 | `../../../JeecgBoot/jeecg-boot/jeecg-boot-module/jeecg-boot-module-airag` | AI 应用相关后端能力 | + +## 前端入口与模块 + +| 主题 | 路径 | 课堂用途 | +| --- | --- | --- | +| 前端 package | `../../../JeecgBoot/jeecgboot-vue3/package.json` | 查看脚本、依赖、Node engines | +| 前端协作约束 | `../../../JeecgBoot/jeecgboot-vue3/CLAUDE.md` | 查看启动链路、路由、Pinia、API 层约定 | +| 前端入口 | `../../../JeecgBoot/jeecgboot-vue3/src/main.ts` | Vue app 初始化顺序 | +| Vite 配置 | `../../../JeecgBoot/jeecgboot-vue3/vite.config.ts` | alias、插件、构建配置 | +| 系统页面 | `../../../JeecgBoot/jeecgboot-vue3/src/views/system` | 用户、角色、菜单、字典等系统管理页面 | +| 扩展模块 | `../../../JeecgBoot/jeecgboot-vue3/src/views/super` | 动态发现扩展模块 | +| 组件库 | `../../../JeecgBoot/jeecgboot-vue3/src/components/jeecg` | Jeecg 封装组件 | +| 布局 | `../../../JeecgBoot/jeecgboot-vue3/src/layouts/default` | 后台布局、菜单、页签 | + +## 权限与路由 + +| 主题 | 路径 | 课堂用途 | +| --- | --- | --- | +| 前端路由目录 | `../../../JeecgBoot/jeecgboot-vue3/src/router` | 静态路由、路由守卫、动态路由挂载 | +| 权限 Store | `../../../JeecgBoot/jeecgboot-vue3/src/store/modules/permission.ts` | 后端菜单、权限码、动态路由 | +| 用户 Store | `../../../JeecgBoot/jeecgboot-vue3/src/store/modules/user.ts` | Token、用户信息、角色、租户 | +| 认证工具 | `../../../JeecgBoot/jeecgboot-vue3/src/utils/auth/index.ts` | Token 本地存储和读取 | +| 后端系统业务 | `../../../JeecgBoot/jeecg-boot/jeecg-module-system/jeecg-system-biz` | 用户、角色、菜单权限相关后端逻辑 | +| 权限知识库 | `../../../JeecgBoot/docs/project-knowledge/06-auth-permissions.md` | 课堂优先阅读的权限链路说明 | + +## API 与请求层 + +| 主题 | 路径 | 课堂用途 | +| --- | --- | --- | +| 前端 API 目录 | `../../../JeecgBoot/jeecgboot-vue3/src/api` | API 定义分组 | +| Axios 封装 | `../../../JeecgBoot/jeecgboot-vue3/src/utils/http/axios` | `defHttp` 请求层 | +| 系统 API | `../../../JeecgBoot/jeecgboot-vue3/src/api/sys` | 登录、用户、权限等系统接口 | +| 通用 API | `../../../JeecgBoot/jeecgboot-vue3/src/api/common` | 通用上传、字典等能力 | +| 后端 Controller 索引 | `../../../JeecgBoot/docs/project-knowledge/generated/backend-endpoints.md` | 快速查后端接口候选位置 | +| 前端视图索引 | `../../../JeecgBoot/docs/project-knowledge/generated/frontend-routes.md` | 快速查前端页面候选位置 | + +## 配置与运行 + +| 主题 | 路径 | 课堂用途 | +| --- | --- | --- | +| 根 README | `../../../JeecgBoot/README.md` | 项目介绍、版本、启动入口 | +| 单体 Docker Compose | `../../../JeecgBoot/docker-compose.yml` | MySQL、Redis、后端、前端容器 | +| 微服务 Docker Compose | `../../../JeecgBoot/docker-compose-cloud.yml` | 微服务模式容器 | +| 后端主配置 | `../../../JeecgBoot/jeecg-boot/jeecg-module-system/jeecg-system-start/src/main/resources/application.yml` | profile 入口 | +| 后端开发配置 | `../../../JeecgBoot/jeecg-boot/jeecg-module-system/jeecg-system-start/src/main/resources/application-dev.yml` | 端口、context path、MySQL、Redis、AI 配置 | +| 前端开发环境 | `../../../JeecgBoot/jeecgboot-vue3/.env.development` | mock、代理、后端地址 | +| 前端基础环境 | `../../../JeecgBoot/jeecgboot-vue3/.env` | 端口、标题、运行平台等基础变量 | + +## 数据库与迁移 + +| 主题 | 路径 | 课堂用途 | +| --- | --- | --- | +| MySQL 初始化 | `../../../JeecgBoot/jeecg-boot/db/jeecgboot-mysql-5.7.sql` | 基础表结构和初始化数据 | +| Flyway 迁移 | `../../../JeecgBoot/jeecg-boot/jeecg-module-system/jeecg-system-start/src/main/resources/flyway/sql/mysql` | 增量迁移脚本 | +| 数据文档 | `../../../JeecgBoot/docs/project-knowledge/05-data-and-migrations.md` | 数据库来源和迁移策略 | +| 数据字典索引 | `../../../JeecgBoot/docs/project-knowledge/generated/database-dictionary.md` | 表结构快速索引 | +| 权限码索引 | `../../../JeecgBoot/docs/project-knowledge/generated/permission-codes.md` | 权限码候选索引 | + +## 课堂使用方式 + +1. 学员先复制本文件的路径表，形成自己的上下文包。 +2. 每次向 TRAE 提问前，至少提供 3 个相关路径。 +3. TRAE 输出后，必须把“事实依据”填入 [worksheets.md](./worksheets.md) 的源码依据记录表。 +4. 对没有路径支撑的内容，统一写入“不确定点”。 +5. 讲师只验收能回到路径的结论，不验收泛泛总结。 + diff --git a/cases/jeecgboot-work-order/worksheets.md b/cases/jeecgboot-work-order/worksheets.md new file mode 100644 index 0000000..81b3754 --- /dev/null +++ b/cases/jeecgboot-work-order/worksheets.md @@ -0,0 +1,139 @@ +# 课堂工作表 + +使用方式：每个小组复制本文件，填写后作为课堂交付物。不能确认的内容写“不确定点”，不要留空。 + +## 上下文包 + +| 项目 | 内容 | +| --- | --- | +| 小组名称 | | +| 任务范围 | JeecgBoot 工单案例 | +| 使用的项目路径 | | +| 已阅读文档 | | +| 本轮要解决的问题 | | +| 明确不做的内容 | | +| 验收方式 | | + +## 源码依据记录表 + +| 主题 | 路径 | 证据内容 | 对工单案例的意义 | 不确定点 | +| --- | --- | --- | --- | --- | +| 后端入口 | | | | | +| 后端模块结构 | | | | | +| 前端入口 | | | | | +| 前端 API 请求层 | | | | | +| 动态路由和权限 | | | | | +| 配置与运行 | | | | | +| 数据库与迁移 | | | | | + +## 需求拆解表 + +| 用户故事 | 角色 | 目标 | 业务价值 | 非目标范围 | 验收标准 | 不确定点 | +| --- | --- | --- | --- | --- | --- | --- | +| | | | | | | | +| | | | | | | | +| | | | | | | | + +## 接口契约表 + +| 接口名称 | 方法 | 路径建议 | 请求参数 | 响应字段 | 权限字符建议 | 成功场景 | 失败场景 | 验收方式 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 工单分页列表 | | | | | | | | | +| 工单详情 | | | | | | | | | +| 新增工单 | | | | | | | | | +| 编辑工单 | | | | | | | | | +| 指派负责人 | | | | | | | | | +| 状态流转 | | | | | | | | | +| 查询审计日志 | | | | | | | | | +| 看板指标 | | | | | | | | | + +## RBAC 权限矩阵 + +| 功能点 | 管理员 | 工单负责人 | 研发处理人 | 测试验证人 | 只读观察者 | 权限字符建议 | 验收方式 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 查看列表 | | | | | | | | +| 查看详情 | | | | | | | | +| 新建工单 | | | | | | | | +| 编辑工单 | | | | | | | | +| 指派负责人 | | | | | | | | +| 状态流转 | | | | | | | | +| 关闭工单 | | | | | | | | +| 删除工单 | | | | | | | | +| 查看审计日志 | | | | | | | | +| 查看看板 | | | | | | | | +| 导出数据 | | | | | | | | + +## 状态流转表 + +| 当前状态 | 动作 | 目标状态 | 允许角色 | 前置条件 | 后置动作 | 非法场景 | 验收方式 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 新建 | | | | | | | | +| 处理中 | | | | | | | | +| 待验证 | | | | | | | | +| 已关闭 | | | | | | | | +| 已驳回 | | | | | | | | + +## 审计日志设计表 + +| 操作 | 记录时机 | actor | action | targetId | oldValue | newValue | source | 是否脱敏 | 验收方式 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 创建工单 | | | | | | | | | | +| 编辑字段 | | | | | | | | | | +| 指派负责人 | | | | | | | | | | +| 状态流转 | | | | | | | | | | +| 新增评论 | | | | | | | | | | +| 关闭工单 | | | | | | | | | | + +## 异常态清单 + +| 场景 | 异常态 | 触发条件 | 前端表现 | 后端处理 | 用户提示 | 测试点 | 验收方式 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 列表查询 | | | | | | | | +| 详情查询 | | | | | | | | +| 新增工单 | | | | | | | | +| 编辑工单 | | | | | | | | +| 指派负责人 | | | | | | | | +| 状态流转 | | | | | | | | +| 审计查询 | | | | | | | | +| 看板查询 | | | | | | | | + +## 看板指标表 + +| 指标名 | 口径 | 维度 | 过滤条件 | 数据来源建议 | 图表形式 | 权限要求 | 异常态 | 验收方式 | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 工单总数 | | | | | | | | | +| 未关闭工单数 | | | | | | | | | +| 平均关闭周期 | | | | | | | | | +| 按优先级分布 | | | | | | | | | +| 按类型分布 | | | | | | | | | +| 缺陷趋势 | | | | | | | | | +| 逾期工单数 | | | | | | | | | +| 人员处理负载 | | | | | | | | | + +## Review 记录表 + +| 检查项 | 结论 | 依据 | 风险 | 修复建议 | 验收方式 | +| --- | --- | --- | --- | --- | --- | +| 源码依据是否充分 | | | | | | +| 需求边界是否清楚 | | | | | | +| 接口契约是否完整 | | | | | | +| 权限是否覆盖页面、按钮、接口 | | | | | | +| 状态流转是否覆盖非法场景 | | | | | | +| 审计是否覆盖关键操作 | | | | | | +| 异常态是否可测试 | | | | | | +| 看板指标是否可计算 | | | | | | + +## 最终交付记录 + +| 交付物 | 是否完成 | 文件或链接 | 负责人 | 备注 | +| --- | --- | --- | --- | --- | +| 源码依据记录表 | | | | | +| 需求拆解表 | | | | | +| 接口契约表 | | | | | +| RBAC 权限矩阵 | | | | | +| 状态流转表 | | | | | +| 审计日志设计表 | | | | | +| 异常态清单 | | | | | +| 看板指标表 | | | | | +| Review 记录 | | | | | + diff --git a/deliverables/ai-engineering-skills-delivery-utf8.zip b/deliverables/ai-engineering-skills-delivery-utf8.zip new file mode 100644 index 0000000..aa02287 Binary files /dev/null and b/deliverables/ai-engineering-skills-delivery-utf8.zip differ diff --git a/deliverables/ai-engineering-skills-delivery.zip b/deliverables/ai-engineering-skills-delivery.zip new file mode 100644 index 0000000..da38126 Binary files /dev/null and b/deliverables/ai-engineering-skills-delivery.zip differ diff --git a/deliverables/ai-engineering-skills-delivery/INSTALL.md b/deliverables/ai-engineering-skills-delivery/INSTALL.md new file mode 100644 index 0000000..5a50df8 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/INSTALL.md @@ -0,0 +1,63 @@ +# 安装说明 + +## 方式一：安装到 Codex Skills 目录 + +把 `skills/` 下的 4 个 Skill 文件夹复制到本机 Skills 目录： + +```text +~/.codex/skills/ +``` + +安装后目录应类似： + +```text +~/.codex/skills/ +├── generate-project-constraints/ +├── design-complex-business-module/ +├── review-business-delivery/ +└── track-review-fix-loop/ +``` + +每个 Skill 文件夹必须保留完整结构： + +```text +skill-name/ +├── SKILL.md +├── agents/ +│ └── openai.yaml +└── assets/ +``` + +## 调用方式 + +在支持 Skill 的 AI 编程工具中，可以这样调用： + +```text +Use $generate-project-constraints 为当前项目生成 AI 开发约束。 +Use $design-complex-business-module 设计这个业务模块的权限、状态、审计、异常态和看板。 +Use $review-business-delivery Review 这批阶段交付物。 +Use $track-review-fix-loop 根据 Review 报告生成修复闭环记录。 +``` + +## 方式二：作为团队资产库使用 + +如果当前 AI 工具暂不支持原生 Skill 机制，可以把本包作为团队资产库使用： + +```text +ai-engineering-assets/ +├── skills/ +├── rules/ +├── prompts/ +├── templates/ +├── checklists/ +└── examples/ +``` + +此时 `SKILL.md` 作为标准工作流说明，`assets/` 作为可复制模板、Prompt、检查清单和反例库。 + +## 维护建议 + +- 每次项目规则变化后，重新运行 `generate-project-constraints`。 +- 每次复杂业务模块交付后，把高频问题沉淀到 `review-business-delivery` 或 `track-review-fix-loop` 的 assets。 +- 不要把某个项目的专用规则直接复制成通用规则。 +- 对无法从源码或配置证明的内容，统一标记为待确认。 diff --git a/deliverables/ai-engineering-skills-delivery/README.md b/deliverables/ai-engineering-skills-delivery/README.md new file mode 100644 index 0000000..8c90be7 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/README.md @@ -0,0 +1,46 @@ +# AI Engineering Skills Delivery + +本交付包提供 4 个可复用 AI 工程 Skill，覆盖真实项目中从项目约束生成、复杂业务设计、交付 Review 到修复闭环的完整流程。 + +这些 Skill 不是单次 Prompt，而是可安装、可复制、可随项目持续维护的团队资产。 + +## 交付内容 + +```text +客户AI工程Skill交付包/ +├── README.md +├── INSTALL.md +├── skills/ +│ ├── generate-project-constraints/ +│ ├── design-complex-business-module/ +│ ├── review-business-delivery/ +│ └── track-review-fix-loop/ +└── examples/ + └── jeecgboot-work-order/ +``` + +## Skill 列表 + +| Skill | 用途 | 典型产物 | +| --- | --- | --- | +| `generate-project-constraints` | 从项目源码、配置、CI、文档中提取项目约束 | rules、约束提取表、验收清单 | +| `design-complex-business-module` | 设计复杂业务模块的权限、状态、审计、异常态和看板 | RBAC 矩阵、状态流转表、审计 SOP、看板指标字典 | +| `review-business-delivery` | 审查复杂业务交付物或 PR 的业务风险 | 阶段 Review 报告、风险清单、验收建议 | +| `track-review-fix-loop` | 跟踪 Review 问题修复、验证和资产沉淀 | 修复记录、未闭环清单、资产更新建议 | + +## 推荐使用顺序 + +1. 使用 `generate-project-constraints` 为客户项目生成项目规则。 +2. 使用 `design-complex-business-module` 生成复杂业务设计资产。 +3. 使用 `review-business-delivery` 审查设计、代码或阶段交付物。 +4. 使用 `track-review-fix-loop` 跟踪修复、验证结果和资产沉淀。 + +## 适用项目 + +适用于后台管理系统、低代码平台二开、CRM、工单、审批、运营系统、数据看板等企业业务项目。 + +这些 Skill 不要求项目必须有 `CLAUDE.md`、`AGENTS.md` 或 `README.md`。如果项目没有显式说明文档，Skill 会从配置、源码模式、测试和 CI 中提取约束，并把无法证明的内容标记为待确认。 + +## 示例说明 + +`examples/jeecgboot-work-order/` 提供 JeecgBoot 工单案例参考，帮助理解这些 Skill 在真实后台项目中的使用方式。该示例不是通用 Skill 安装项。 diff --git a/deliverables/ai-engineering-skills-delivery/examples/jeecgboot-work-order/JeecgBoot工单模块开发审查.skill.md b/deliverables/ai-engineering-skills-delivery/examples/jeecgboot-work-order/JeecgBoot工单模块开发审查.skill.md new file mode 100644 index 0000000..4bc5f74 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/examples/jeecgboot-work-order/JeecgBoot工单模块开发审查.skill.md @@ -0,0 +1,44 @@ +# JeecgBoot 工单模块开发审查 Skill + +## 触发场景 + +涉及工单列表、详情、评论、状态、指派、看板、权限字符、数据权限、操作日志的需求拆解、代码生成或代码修改。 + +## 输入材料 + +- PR diff 或相关文件。 +- 工单需求说明。 +- 数据模型与接口契约。 +- 当前 rules。 +- 前端页面文件。 +- API 模块文件。 +- 后端 Controller / Service。 +- 权限矩阵。 +- 状态流转表。 +- 审计日志 SOP。 + +## 执行步骤 + +1. 识别需求范围和非目标范围。 +2. 检查字段、接口契约和页面状态是否完整。 +3. 审查 JeecgBoot 生成代码的字段、查询、分页、字典和异常态。 +4. 检查新增、编辑、删除、指派、状态变更的前端按钮与后端权限。 +5. 检查操作日志、数据权限和测试缺口。 +6. 检查看板指标口径和接口验收记录。 +7. 输出风险、不确定点和验收建议。 + +## 输出格式 + +- 需求范围确认。 +- 接口契约问题表。 +- 代码生成 Review 清单。 +- 权限风险表。 +- 状态流转风险表。 +- 审计日志风险表。 +- 测试缺口清单。 +- 不确定点清单。 + +## 验收标准 + +每个关键结论必须标注文件、函数、注解、配置或调用链依据。每条建议必须有验收方式。 + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/SKILL.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/SKILL.md new file mode 100644 index 0000000..36337fa --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/SKILL.md @@ -0,0 +1,73 @@ +--- +name: design-complex-business-module +description: Use when designing a complex enterprise business module that needs RBAC permissions, frontend/backend permission controls, state transitions, illegal transition handling, audit logging, exception states, dashboard metrics, interface contracts, or acceptance-ready design assets. +--- + +# Design Complex Business Module + +## Core Principle + +Design the control surfaces before designing code. For complex business modules, produce permission, state, audit, exception, dashboard, and acceptance assets before implementation planning. + +Do not jump from a requirement to CRUD code. Every business rule must have an owner, a source, and a verification method. + +## Inputs + +Collect what exists, then mark gaps explicitly: + +- Business requirement or user stories. +- Target project paths and project constraints. +- Existing roles, permissions, menus, routes, API layer, backend controllers/services, data model, and audit/logging patterns. +- Known non-goals and delivery deadline. +- Existing rules, checklists, or project knowledge docs. + +If project evidence is missing, label outputs as `建议` or `待确认`, not `事实`. + +## Workflow + +1. Define scope: module name, actors, key workflows, non-goals, and acceptance boundary. +2. Build the RBAC matrix: roles x features, with `允许`, `拒绝`, or `条件允许`. +3. Translate RBAC into a permission control plan: page/menu, button, backend API, and data scope. +4. Design the state machine: states, actions, allowed roles, preconditions, post-actions, and terminal states. +5. List illegal transitions and rejection behavior. +6. Design audit logging: actions, write timing, actor, target, old/new values, source/request id, masking, and failure behavior. +7. Complete exception states: permission denied, missing data, invalid state, duplicate submit, validation failure, concurrency, empty dashboard, empty audit log. +8. Define dashboard metrics: meaning, formula, dimensions, filters, data source, permission, empty state, and manual verification. +9. Produce interface and acceptance notes only after the above assets are consistent. + +## Output Contract + +Generate these assets unless the user narrows scope: + +```text +RBAC权限矩阵 +权限控制方案 +状态流转表 +非法流转清单 +审计日志SOP +异常态清单 +看板指标字典 +看板接口验收记录 +不确定点清单 +``` + +Use the templates in `assets/` when creating files. + +## Quality Gates + +- Every sensitive action has frontend visibility control and backend enforcement. +- Data permissions are not replaced by button hiding. +- Every state transition has a reverse or rejection story, or is explicitly terminal. +- Every illegal transition has expected system response and validation method. +- Every successful critical operation has an audit record; failed operations do not write success audit. +- Every dashboard metric has a formula or filter logic that can be manually checked. +- Every output distinguishes `事实`, `推断`, `建议`, and `待确认`. + +## Common Mistakes + +- Do not design UI first and add permissions later. +- Do not use "admin can do everything" as a complete RBAC design. +- Do not put all status rules into prose; use a state table. +- Do not write "record audit log" without naming fields and write timing. +- Do not define dashboard cards without metric formulas and data scope. +- Do not turn project-specific permission strings into facts without source evidence. diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/agents/openai.yaml b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/agents/openai.yaml new file mode 100644 index 0000000..1d0695e --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "复杂业务模块设计" + short_description: "生成权限状态审计异常态看板等复杂业务设计资产" + default_prompt: "Use $design-complex-business-module to design permissions, state transitions, audit logs, exception states, and dashboard metrics for this business module." + +policy: + allow_implicit_invocation: true diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/RBAC权限矩阵.template.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/RBAC权限矩阵.template.md new file mode 100644 index 0000000..1885beb --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/RBAC权限矩阵.template.md @@ -0,0 +1,16 @@ +# 工单 RBAC 权限矩阵 + +| 功能点 | 管理员 | 工单负责人 | 研发处理人 | 测试验证人 | 只读观察者 | 权限字符建议 | 备注 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 查看列表 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | work:order:list | 按数据范围 | +| 查看详情 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | work:order:query | 仅可见范围 | +| 新建工单 | 允许 | 允许 | 允许 | 允许 | 拒绝 | work:order:add | | +| 编辑工单 | 允许 | 条件允许 | 条件允许 | 拒绝 | 拒绝 | work:order:edit | 状态限制 | +| 指派负责人 | 允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | work:order:assign | | +| 状态流转 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | work:order:transition | 按状态 | +| 关闭工单 | 允许 | 条件允许 | 拒绝 | 条件允许 | 拒绝 | work:order:close | 测试验证后 | +| 删除工单 | 允许 | 拒绝 | 拒绝 | 拒绝 | 拒绝 | work:order:delete | 高危操作 | +| 查看审计日志 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | work:order:audit | | +| 查看看板 | 允许 | 允许 | 条件允许 | 条件允许 | 条件允许 | work:order:dashboard | 按数据范围 | +| 导出数据 | 允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | work:order:export | | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/RBAC权限矩阵生成.prompt.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/RBAC权限矩阵生成.prompt.md new file mode 100644 index 0000000..84a9100 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/RBAC权限矩阵生成.prompt.md @@ -0,0 +1,25 @@ +# RBAC 权限矩阵生成 Prompt + +```text +请基于 JeecgBoot 工单模块设计 RBAC 权限矩阵。 + +输入材料： +- 工单模块需求：<粘贴需求> +- 角色列表：管理员、工单负责人、研发处理人、测试验证人、只读观察者 +- 功能点：查看列表、查看详情、新建、编辑、指派、状态流转、关闭、删除、查看审计、查看看板、导出 +- 项目依据：<粘贴权限、路由、菜单相关路径> + +输出要求： +1. 先列事实依据：JeecgBoot 权限、菜单、动态路由相关路径。 +2. 输出 RBAC 权限矩阵：角色 x 功能点，允许、拒绝、条件允许。 +3. 输出权限字符建议，必须标注为建议。 +4. 输出页面级、按钮级、接口级、数据范围四层控制。 +5. 输出不确定点：哪些权限必须业务方确认。 +6. 输出验收方式：如何证明权限确实生效。 + +约束： +- 不要直接改代码。 +- 不要把前端按钮隐藏当作安全边界。 +- 所有结论必须区分事实、推断、建议。 +``` + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/审计日志SOP.template.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/审计日志SOP.template.md new file mode 100644 index 0000000..876d692 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/审计日志SOP.template.md @@ -0,0 +1,40 @@ +# 工单审计日志 SOP + +## 记录原则 + +所有会改变工单关键业务状态、负责人、可见性或结论的动作都必须记录审计日志。 + +## 审计字段 + +| 字段 | 含义 | 示例 | +| --- | --- | --- | +| ticket_id | 工单 ID | WO-001 | +| actor_id | 操作人 ID | 1001 | +| actor_name | 操作人名称 | zhangsan | +| action | 操作类型 | ASSIGN | +| field_name | 变更字段 | assignee | +| old_value | 旧值 | lisi | +| new_value | 新值 | wangwu | +| source | 来源 | web | +| request_id | 请求 ID | req-001 | +| created_at | 操作时间 | 2026-07-01 10:00:00 | + +## 必须记录的动作 + +| 动作 | 写入时机 | oldValue | newValue | 验收 | +| --- | --- | --- | --- | --- | +| 创建工单 | 创建成功后 | 空 | 工单摘要 | 审计列表可见 | +| 编辑字段 | 保存成功后 | 修改前字段 | 修改后字段 | 字段前后值正确 | +| 指派负责人 | 指派成功后 | 原负责人 | 新负责人 | 审计记录负责人变化 | +| 状态流转 | 状态变更成功后 | 原状态 | 新状态 | 审计记录状态变化 | +| 评论新增 | 评论保存后 | 空 | 评论摘要 | 审计记录评论动作 | +| 关闭工单 | 关闭成功后 | 原状态 | 已关闭 | 审计记录关闭时间 | + +## 验收方式 + +1. 执行关键操作后能在审计列表查询到记录。 +2. oldValue/newValue 和实际变更一致。 +3. 敏感字段已脱敏。 +4. 操作失败不写成功审计。 +5. 多步写入失败时审计和业务数据保持一致。 + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/审计日志检查清单.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/审计日志检查清单.md new file mode 100644 index 0000000..0e271a4 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/审计日志检查清单.md @@ -0,0 +1,13 @@ +# 审计日志检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 创建记录 | 创建工单后能查询审计记录 | | +| 字段变更 | 编辑关键字段记录 oldValue/newValue | | +| 指派记录 | 指派负责人记录原负责人和新负责人 | | +| 状态记录 | 状态流转记录原状态和新状态 | | +| 操作人 | actor_id 和 actor_name 可追溯 | | +| 来源 | source 或 request_id 可追溯 | | +| 脱敏 | 敏感字段不明文进入审计 | | +| 失败处理 | 操作失败不写成功审计 | | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/异常态检查清单.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/异常态检查清单.md new file mode 100644 index 0000000..e1b6496 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/异常态检查清单.md @@ -0,0 +1,13 @@ +# 异常态检查清单 + +| 异常态 | 必须验证 | 结果 | +| --- | --- | --- | +| 空列表 | 页面显示空状态，不报错 | | +| 详情不存在 | 提示工单不存在，页面不崩溃 | | +| 权限不足 | 前端提示或隐藏，后端拒绝 | | +| 非法状态 | 返回非法流转，状态不变 | | +| 重复提交 | 只成功一次，只写一条有效审计 | | +| 参数缺失 | 返回参数错误，业务数据不变 | | +| 并发修改 | 拒绝覆盖或提示刷新 | | +| 看板无数据 | 图表显示空态，不显示假数据 | | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/异常态清单.template.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/异常态清单.template.md new file mode 100644 index 0000000..286eaff --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/异常态清单.template.md @@ -0,0 +1,13 @@ +# 工单异常态清单 + +| 场景 | 触发条件 | 前端表现 | 后端响应 | 验收 | +| --- | --- | --- | --- | --- | +| 权限不足 | 无权限操作 | 按钮不可见或提示无权限 | 403 或业务拒绝 | 不完成操作 | +| 工单不存在 | 传入错误 ID | 显示不存在 | 404 或业务错误 | 页面不崩溃 | +| 非法状态流转 | closed -> processing | 提示非法流转 | 状态不变 | 数据状态不变 | +| 重复提交 | 连续点击提交 | 按钮 loading/禁用 | 只处理一次 | 只生成一条有效审计 | +| 参数缺失 | 驳回缺少原因 | 表单校验提示 | 参数错误 | 不改变状态 | +| 并发修改 | 数据版本过期 | 提示刷新 | 拒绝覆盖 | 旧数据不覆盖新数据 | +| 看板无数据 | 无匹配记录 | 空状态 | 返回空集合 | 页面不报错 | +| 审计日志为空 | 无审计记录 | 空状态 | 返回空集合 | 页面不报错 | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/异常态补齐.prompt.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/异常态补齐.prompt.md new file mode 100644 index 0000000..17bd793 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/异常态补齐.prompt.md @@ -0,0 +1,24 @@ +# 异常态补齐 Prompt + +```text +请基于 JeecgBoot 工单模块，列出状态流转、指派、删除、查询详情、审计日志、看板相关的异常态和防御性逻辑。 + +输出表格： +场景 | 触发条件 | 前端表现 | 后端响应 | 用户提示 | 测试点 | 验收 + +必须覆盖： +- 权限不足 +- 工单不存在 +- 非法状态流转 +- 重复提交 +- 参数缺失 +- 并发修改 +- 看板无数据 +- 审计日志为空 + +约束： +- 先列异常态，不要直接改代码。 +- 给出每个异常态的验收步骤。 +- 标注事实、推断、建议和不确定点。 +``` + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/权限上线前检查清单.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/权限上线前检查清单.md new file mode 100644 index 0000000..cacf893 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/权限上线前检查清单.md @@ -0,0 +1,12 @@ +# 权限上线前检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 菜单权限 | 工单菜单只对授权角色可见 | | +| 按钮权限 | 新增、编辑、删除、指派、状态按钮按权限显示 | | +| 接口权限 | 无权限账号直接请求敏感接口失败 | | +| 数据权限 | 普通用户只能看到授权范围内工单 | | +| 权限字符 | 前端按钮、菜单配置、后端接口命名一致 | | +| 审计 | 权限敏感操作成功后有审计记录 | | +| 反例验证 | 无权限账号不能绕过前端执行删除/指派 | | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/权限控制方案.template.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/权限控制方案.template.md new file mode 100644 index 0000000..d7d0910 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/权限控制方案.template.md @@ -0,0 +1,12 @@ +# 工单权限控制方案 + +| 操作 | 前端入口 | 权限字符 | 后端接口 | 后端校验 | 数据权限 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| 新增工单 | 新增按钮 | work:order:add | /workOrder/add | 权限注解 | 无 | 无权限账号看不到按钮且直接请求失败 | +| 编辑工单 | 编辑按钮 | work:order:edit | /workOrder/edit | 权限注解 + 状态校验 | 负责人/创建人范围 | 越权账号返回 403 或业务拒绝 | +| 指派负责人 | 指派按钮 | work:order:assign | /workOrder/assign | 权限注解 | 管理员/负责人范围 | 普通研发无法指派他人 | +| 状态流转 | 状态按钮 | work:order:transition | /workOrder/transition | 权限注解 + 状态机校验 | 相关工单范围 | 非法流转失败 | +| 删除工单 | 删除按钮 | work:order:delete | /workOrder/delete | 权限注解 | 管理员范围 | 非管理员返回 403 | +| 查看审计 | 审计页签 | work:order:audit | /workOrder/audit/list | 权限注解 | 相关工单范围 | 无权限不可见且接口拒绝 | +| 看板 | 看板菜单 | work:order:dashboard | /workOrder/dashboard | 权限注解 | 数据范围过滤 | 不同角色数据范围不同 | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/权限控制方案生成.prompt.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/权限控制方案生成.prompt.md new file mode 100644 index 0000000..7dcf834 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/权限控制方案生成.prompt.md @@ -0,0 +1,24 @@ +# 权限控制方案生成 Prompt + +```text +请基于工单模块 RBAC 权限矩阵，生成 JeecgBoot 权限控制方案。 + +输入材料： +- RBAC 权限矩阵：<粘贴> +- 接口契约表：<粘贴> +- 当前项目权限相关路径：<粘贴> +- 当前 rules：<粘贴> + +输出要求： +1. 权限控制方案表，列为：操作、前端入口、权限字符、后端接口、后端校验、数据权限、验收。 +2. 影响范围：前端页面、API 文件、后端 Controller、Service、菜单配置、数据权限。 +3. 缺失风险：按钮隐藏、接口未校验、数据范围不清、权限字符不一致。 +4. 无权限访问验收步骤。 +5. 不确定点和需要人工确认的权限边界。 + +约束： +- 不要直接改代码。 +- 后端接口权限必须单独说明。 +- 每个敏感操作必须有验收方式。 +``` + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/状态流转检查清单.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/状态流转检查清单.md new file mode 100644 index 0000000..2be5688 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/状态流转检查清单.md @@ -0,0 +1,12 @@ +# 状态流转检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 状态枚举 | 所有状态有统一枚举或字典 | | +| 合法流转 | 状态流转表中的合法路径可执行 | | +| 非法流转 | 非法路径被拒绝且状态不变 | | +| 角色限制 | 不同角色只能执行被授权动作 | | +| 前置条件 | 驳回原因、关闭条件、负责人等校验完整 | | +| 审计日志 | 每次成功流转写审计 | | +| 重复提交 | 重复点击不会产生重复有效流转 | | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/状态流转表.template.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/状态流转表.template.md new file mode 100644 index 0000000..29456b8 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/状态流转表.template.md @@ -0,0 +1,22 @@ +# 工单状态流转表 + +| 当前状态 | 动作 | 目标状态 | 允许角色 | 前置条件 | 后置动作 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| 新建 | 指派 | 新建 | 管理员/负责人 | 工单未关闭 | 写审计日志 | 指派人变化且状态不变 | +| 新建 | 开始处理 | 处理中 | 研发处理人/负责人 | 已指派处理人 | 写审计日志 | 状态变为处理中 | +| 处理中 | 提交验证 | 待验证 | 研发处理人/负责人 | 处理说明不为空 | 写审计日志 | 状态变为待验证 | +| 待验证 | 验证通过 | 已关闭 | 测试验证人/负责人 | 验证结果通过 | 写审计日志和关闭时间 | 状态变为已关闭 | +| 待验证 | 验证驳回 | 已驳回 | 测试验证人/负责人 | 驳回原因不为空 | 写审计日志 | 状态变为已驳回 | +| 已驳回 | 重新处理 | 处理中 | 研发处理人/负责人 | 驳回原因已读 | 写审计日志 | 状态变为处理中 | +| 已关闭 | 重新打开 | 新建 | 管理员 | 重开原因不为空 | 写审计日志 | 状态变为新建 | + +## 非法流转清单 + +| 当前状态 | 尝试动作 | 问题 | 系统响应 | 验收 | +| --- | --- | --- | --- | --- | +| 已关闭 | 开始处理 | 关闭后不能直接处理 | 返回非法流转 | 状态不变 | +| 新建 | 验证通过 | 未处理不能验证 | 返回非法流转 | 状态不变 | +| 待验证 | 提交验证 | 重复提交验证 | 返回非法流转 | 只保留原状态 | +| 处理中 | 验证通过 | 未进入待验证 | 返回非法流转 | 状态不变 | +| 已驳回 | 关闭 | 驳回后不能直接关闭 | 返回非法流转 | 状态不变 | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/状态流转设计.prompt.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/状态流转设计.prompt.md new file mode 100644 index 0000000..58b609b --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/状态流转设计.prompt.md @@ -0,0 +1,34 @@ +# 状态流转设计 Prompt + +```text +请为 JeecgBoot 工单模块设计状态流转规则。 + +状态候选： +- 新建 +- 处理中 +- 待验证 +- 已关闭 +- 已驳回 + +动作候选： +- 指派 +- 开始处理 +- 提交验证 +- 验证通过 +- 验证驳回 +- 关闭 +- 重新打开 + +输出要求： +1. 状态流转表：当前状态、动作、目标状态、允许角色、前置条件、后置动作、验收。 +2. 非法流转清单：当前状态、尝试动作、问题、系统响应、验收。 +3. 接口设计建议。 +4. 测试点清单。 +5. 不确定点。 + +约束： +- 先出状态表，不要直接写 if else。 +- 已关闭、越权、缺少说明、重复提交必须覆盖。 +- 每条规则必须有验收方式。 +``` + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板指标口径检查清单.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板指标口径检查清单.md new file mode 100644 index 0000000..b732c20 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板指标口径检查清单.md @@ -0,0 +1,13 @@ +# 看板指标口径检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 指标含义 | 每个指标有业务解释 | | +| 计算口径 | 每个指标有公式或筛选条件 | | +| 时间范围 | 明确按创建时间、关闭时间还是更新时间统计 | | +| 数据范围 | 不同角色的数据范围清楚 | | +| 空数据 | 空数据展示为 0 或空态，不误导 | | +| 分组一致性 | 分组总和能和总数对齐 | | +| 权限 | 无看板权限不能访问接口 | | +| 验收证据 | 至少有一组样例数据手工校验 | | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板指标字典.template.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板指标字典.template.md new file mode 100644 index 0000000..32da66b --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板指标字典.template.md @@ -0,0 +1,13 @@ +# 工单看板指标字典 + +| 指标 | 含义 | 口径 | 数据来源 | 展示方式 | 权限 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| 工单总数 | 当前筛选范围内工单数量 | count(ticket_id) | 工单表 | 指标卡 | 看板权限 | 与列表同条件数量一致 | +| 未关闭工单数 | 状态不是已关闭的数量 | status != closed | 工单表 | 指标卡 | 看板权限 | 过滤状态验证 | +| 平均关闭周期 | 从创建到关闭平均耗时 | avg(close_time - create_time) | 工单表 | 指标卡/趋势 | 看板权限 | 抽样计算一致 | +| 按优先级分布 | 高中低优先级数量 | group by priority | 工单表/字典 | 饼图/柱状图 | 看板权限 | 分组总和等于总数 | +| 按类型分布 | 缺陷/需求/支持数量 | group by type | 工单表/字典 | 柱状图 | 看板权限 | 分组总和等于总数 | +| 缺陷趋势 | 按日期统计缺陷工单 | type=bug group by date | 工单表 | 折线图 | 看板权限 | 日期范围正确 | +| 逾期工单数 | 超过 SLA 未关闭数量 | due_time < now and status != closed | 工单表 | 指标卡 | 看板权限 | SLA 口径明确 | +| 人员处理负载 | 按负责人统计未关闭数量 | group by assignee | 工单表 | 排行榜 | 管理员/负责人 | 数据范围正确 | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板指标设计.prompt.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板指标设计.prompt.md new file mode 100644 index 0000000..9851ec7 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板指标设计.prompt.md @@ -0,0 +1,28 @@ +# 看板指标设计 Prompt + +```text +请为 JeecgBoot 工单模块设计研发效能看板指标。 + +指标方向： +- 工单总数 +- 未关闭工单数 +- 平均关闭周期 +- 按优先级分布 +- 按类型分布 +- 缺陷趋势 +- 逾期工单数 +- 人员处理负载 + +输出要求： +1. 指标字典：指标名、含义、口径、维度、过滤条件、数据来源、展示方式、权限。 +2. 看板统计接口契约建议。 +3. 空态、错误态、无权限态。 +4. 验收方式。 +5. 不确定点。 + +约束： +- 每个指标必须可计算。 +- 不要只写页面 UI。 +- 指标口径不清必须写入不确定点。 +``` + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板接口验收.prompt.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板接口验收.prompt.md new file mode 100644 index 0000000..b3f2e75 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板接口验收.prompt.md @@ -0,0 +1,27 @@ +# 看板接口验收 Prompt + +```text +请为 JeecgBoot 工单看板统计接口生成验收记录。 + +输入材料： +- 看板指标字典：<粘贴> +- 看板接口契约：<粘贴> +- 权限矩阵：<粘贴> + +输出表格： +验收项 | 账号/条件 | 请求参数 | 预期 | 实际 | 证据 | 结论 + +必须覆盖： +- 有数据 +- 空数据 +- 无权限 +- 过滤条件 +- 指标口径 +- 时间范围 +- 数据范围 + +约束： +- 不要只说“接口正常”。 +- 每个指标至少有一个验收动作。 +``` + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板接口验收清单.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板接口验收清单.md new file mode 100644 index 0000000..95e740a --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板接口验收清单.md @@ -0,0 +1,12 @@ +# 看板接口验收清单 + +| 验收项 | 请求条件 | 通过标准 | 结果 | +| --- | --- | --- | --- | +| 默认查询 | 管理员默认条件 | 返回完整指标 | | +| 时间过滤 | 指定 start/end | 只统计时间范围内数据 | | +| 类型过滤 | 指定工单类型 | 只统计对应类型 | | +| 空数据 | 无匹配条件 | 返回 0 或空集合 | | +| 无权限 | 未授权账号 | 返回 403 或业务拒绝 | | +| 数据范围 | 普通角色 | 只返回授权范围 | | +| 指标一致性 | 固定样例数据 | 与手工计算一致 | | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板接口验收记录.template.md b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板接口验收记录.template.md new file mode 100644 index 0000000..6ddf072 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板接口验收记录.template.md @@ -0,0 +1,11 @@ +# 工单看板接口验收记录 + +| 验收项 | 账号/条件 | 请求参数 | 预期 | 实际 | 证据 | 结论 | +| --- | --- | --- | --- | --- | --- | --- | +| 工单总数 | 管理员 | 默认筛选 | 返回总数 | | | | +| 空数据 | 管理员 + 无匹配条件 | 不存在的日期范围 | 返回空集合或 0 | | | | +| 无权限 | 只读外角色 | 默认筛选 | 返回 403 或业务拒绝 | | | | +| 时间过滤 | 管理员 | start/end | 只统计范围内数据 | | | | +| 数据范围 | 普通研发 | 默认筛选 | 只返回本人相关数据 | | | | +| 指标口径 | 管理员 | 固定样例数据 | 与手工计算一致 | | | | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/SKILL.md b/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/SKILL.md new file mode 100644 index 0000000..d5fb05b --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/SKILL.md @@ -0,0 +1,125 @@ +--- +name: generate-project-constraints +description: Use when a user needs to extract project-specific AI coding constraints, team rules, repository rules, .trae rules, Cursor rules, CLAUDE.md/AGENTS.md content, or reusable rules/checklists from an existing software project, including projects without README or explicit instruction files. +--- + +# Generate Project Constraints + +## Core Principle + +Generate constraints from evidence, not preference. Treat instruction files as optional inputs: if they exist, read them first; if not, use code-only mode and infer cautiously from config, source patterns, tests, CI, and runtime behavior. + +Every output rule must be labeled as `硬约束`, `观察性约束`, or `待确认约束`, and every non-obvious rule must cite source paths. + +## Evidence Order + +Read available sources in this order: + +1. Explicit instructions: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.trae/rules`, `.cursor/rules`, `.cursorrules`, `README*`, `CONTRIBUTING*`, team docs. +2. Build/runtime manifests: `package.json`, lockfiles, `pom.xml`, `build.gradle`, `.env*`, `application*.yml`, Docker files, compose files. +3. Quality gates: ESLint, Prettier, Stylelint, Checkstyle, Spotless, PMD, Jest/Vitest/JUnit/Playwright configs, CI workflows. +4. Source patterns: API layer, response wrappers, auth/permission flow, routing, state management, controller/service/repository or mapper layers, error handling, audit/logging. +5. Existing examples: representative modules that already implement the pattern requested by the user. + +If a source category is absent, record it in `缺失证据`, then continue. Never block only because `README.md`, `CLAUDE.md`, or `AGENTS.md` is missing. + +## Constraint Levels + +| Level | Use When | Wording | +| --- | --- | --- | +| `硬约束` | Directly proven by config, build files, CI, runtime settings, or explicit team docs | `必须` / `禁止` | +| `观察性约束` | Repeated pattern appears in existing code but no written rule exists | `默认采用` / `优先复用` | +| `待确认约束` | Needed for delivery but not provable from the repo | `需团队确认` | + +Do not upgrade an observed pattern into a hard rule unless a source explicitly requires it. + +## Workflow + +1. Define scope: target repo path, output path, desired rule categories, and whether the user wants installable Skill assets or plain rules. +2. Inventory sources with fast shell commands such as `rg --files`, `find`, `sed`, and focused `rg` searches. +3. Extract facts into an evidence table: source path, observed fact, affected area, confidence, and candidate rule. +4. Normalize candidate rules into the output contract below. +5. Validate each rule against at least one source path or mark it `待确认约束`. +6. Write rules and checklists. Prefer small files such as `rules/backend.md`, `rules/frontend.md`, `rules/security.md`, `rules/testing.md`, `rules/delivery.md`. +7. Run verification: placeholder scan, broken-path spot checks, and a final pass that every hard/observed rule has evidence. + +## Output Contract + +When the user asks to generate constraints, produce these artifacts unless they request a lighter output: + +```text +ai-dev-assets/ +├── rules/ +│ ├── global.md +│ ├── frontend.md +│ ├── backend.md +│ ├── security.md +│ ├── testing.md +│ └── delivery.md +├── templates/ +│ └── 项目约束提取表.template.md +└── checklists/ + └── 项目约束验收清单.md +``` + +Each rule file should use this structure: + +```md +## 规则名称 + +- 级别：硬约束 | 观察性约束 | 待确认约束 +- 适用场景： +- 必须： +- 禁止： +- 来源证据： +- 验收方式： +- 迁移说明： +``` + +Use `assets/项目约束提取表.template.md` and `assets/项目约束验收清单.md` as copyable starting points when helpful. + +## Code-Only Mode + +Use this when no explicit instruction files exist. + +Required behavior: + +- State that explicit project docs were not found. +- Build constraints from manifests, configs, CI, tests, and repeated source patterns. +- Label all pattern-derived rules as `观察性约束`. +- Create a `待确认约束` section for business delivery rules that the repo cannot prove, such as review gates, branch policy, audit requirements, test minimums, and release process. + +Good wording: + +```md +本项目未发现 `AGENTS.md`、`CLAUDE.md`、`.trae/rules` 或 `README.md` 中的明确 AI 协作规则。以下约束来自配置文件和源码模式；未能由仓库证明的内容已标记为待确认。 +``` + +## JeecgBoot Example + +For the training case only, JeecgBoot evidence can generate rules such as: + +- `硬约束`: backend uses `Result` response wrapper, from backend `CLAUDE.md`. +- `硬约束`: frontend uses `defHttp` and backend menu permission mode, from frontend `CLAUDE.md`. +- `硬约束`: backend modification blocks require `update-begin` / `update-end`, from backend `CLAUDE.md`. +- `观察性约束`: business features should follow existing controller/service/mapper layering after verifying representative modules. + +Keep these examples out of generic outputs unless the target project is JeecgBoot or explicitly similar. + +## Quality Gates + +Before claiming completion: + +- List generated files. +- Scan generated files for unfinished placeholders, dummy names, and empty headings. +- Check hard and observed constraints cite source paths. +- Confirm missing evidence is not silently converted into rules. +- Report which sources were read and which rule categories remain `待确认`. + +## Common Mistakes + +- Do not require `CLAUDE.md`, `AGENTS.md`, or `README.md` to exist. +- Do not turn general best practices into project rules without evidence. +- Do not merge business constraints, technical constraints, and delivery constraints into one vague list. +- Do not omit verification steps; rules are useful only if a learner or team can check them. +- Do not copy JeecgBoot-specific constraints into unrelated projects. diff --git a/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/agents/openai.yaml b/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/agents/openai.yaml new file mode 100644 index 0000000..43f4885 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "项目约束生成" + short_description: "从项目证据提取可执行规则、模板和验收清单" + default_prompt: "Use $generate-project-constraints to extract project-specific AI coding constraints, rules, and checklists from this repository." + +policy: + allow_implicit_invocation: true diff --git a/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/assets/项目约束提取表.template.md b/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/assets/项目约束提取表.template.md new file mode 100644 index 0000000..2fc3a9f --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/assets/项目约束提取表.template.md @@ -0,0 +1,43 @@ +# 项目约束提取表 + +## 项目信息 + +| 字段 | 内容 | +| --- | --- | +| 项目名称 | | +| 项目路径 | | +| 提取日期 | | +| 提取人 | | +| 目标输出 | rules / prompts / checklists / Skill | + +## 证据扫描记录 + +| 证据类型 | 文件或目录 | 是否存在 | 关键发现 | 备注 | +| --- | --- | --- | --- | --- | +| 显式规则 | AGENTS.md / CLAUDE.md / .trae/rules / .cursor/rules | | | | +| 项目说明 | README / CONTRIBUTING / docs | | | | +| 后端构建 | pom.xml / build.gradle / settings.gradle | | | | +| 前端构建 | package.json / lockfile / vite.config / tsconfig | | | | +| 运行配置 | .env / application.yml / Dockerfile / compose | | | | +| 质量工具 | ESLint / Prettier / Checkstyle / CI / test config | | | | +| 源码模式 | API / Controller / Service / Router / Store | | | | +| 权限与安全 | auth / permission / role / route guard / interceptor | | | | +| 数据与迁移 | schema / migration / mapper / repository | | | | + +## 候选约束 + +| 编号 | 分类 | 约束内容 | 级别 | 来源证据 | 影响范围 | 验收方式 | 迁移说明 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| C-001 | global / frontend / backend / security / testing / delivery | | 硬约束 / 观察性约束 / 待确认约束 | | | | | + +## 缺失证据 + +| 缺失项 | 影响 | 处理方式 | +| --- | --- | --- | +| | | 标记为待确认 / 询问团队 / 暂不生成规则 | + +## 待团队确认 + +| 问题 | 为什么需要确认 | 建议默认值 | 决策人 | +| --- | --- | --- | --- | +| 是否强制单测 | 仓库未发现 CI 或测试要求时无法证明 | 新增核心逻辑需补测试或说明豁免 | 技术负责人 | diff --git a/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/assets/项目约束生成.prompt.md b/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/assets/项目约束生成.prompt.md new file mode 100644 index 0000000..7c25980 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/assets/项目约束生成.prompt.md @@ -0,0 +1,61 @@ +# 项目约束生成 Prompt + +请为下面项目生成可复用的 AI 开发约束资产。 + +## 项目输入 + +- 项目路径： +- 输出路径： +- 目标项目类型： +- 是否需要生成 rules： +- 是否需要生成 checklist： +- 是否需要生成 Skill： + +## 执行要求 + +1. 先扫描项目中是否存在显式规则文件，例如 `AGENTS.md`、`CLAUDE.md`、`.trae/rules`、`.cursor/rules`、`README.md`、`CONTRIBUTING.md`。 +2. 如果不存在显式规则文件，不要停止，进入 code-only 模式。 +3. 从构建配置、运行配置、源码模式、测试配置、CI 配置中提取约束。 +4. 每条约束必须标注为： + - `硬约束`：由配置、CI、构建或显式规则直接证明。 + - `观察性约束`：由多个源码样例归纳，但没有显式规则。 + - `待确认约束`：项目无法证明，但交付前必须团队确认。 +5. 每条硬约束和观察性约束必须标注来源路径。 +6. 不要把通用最佳实践当成项目事实。 +7. 不要把某个项目的专用规则复制到另一个项目。 + +## 输出格式 + +请生成： + +```text +rules/global.md +rules/frontend.md +rules/backend.md +rules/security.md +rules/testing.md +rules/delivery.md +templates/项目约束提取表.template.md +checklists/项目约束验收清单.md +``` + +每条规则使用： + +```md +## 规则名称 + +- 级别： +- 适用场景： +- 必须： +- 禁止： +- 来源证据： +- 验收方式： +- 迁移说明： +``` + +最后输出： + +- 已读来源。 +- 缺失证据。 +- 待确认问题。 +- 不能迁移到其他项目的项目特有约束。 diff --git a/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/assets/项目约束验收清单.md b/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/assets/项目约束验收清单.md new file mode 100644 index 0000000..7c8f339 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/assets/项目约束验收清单.md @@ -0,0 +1,44 @@ +# 项目约束验收清单 + +## 基础完整性 + +- [ ] 已列出目标项目路径和输出路径。 +- [ ] 已说明是否发现显式规则文件。 +- [ ] 已记录缺失证据，没有因为缺失 README / CLAUDE.md / AGENTS.md 而停止。 +- [ ] 已区分 `硬约束`、`观察性约束`、`待确认约束`。 +- [ ] 每条硬约束都有明确来源路径。 +- [ ] 每条观察性约束至少有一个代表性源码样例。 +- [ ] 每条待确认约束都写明需要谁确认。 + +## 规则质量 + +- [ ] 规则包含适用场景。 +- [ ] 规则包含必须做什么。 +- [ ] 规则包含禁止做什么，或说明没有禁止项。 +- [ ] 规则包含验收方式。 +- [ ] 规则包含迁移说明，说明换项目时能否复用。 +- [ ] 规则没有把通用最佳实践冒充为项目事实。 +- [ ] 规则没有把某个单一代码样例冒充为全项目硬约束。 + +## 覆盖范围 + +- [ ] global 约束覆盖项目理解、证据引用、事实/推断区分。 +- [ ] frontend 约束覆盖包管理器、框架、路径别名、API 层、路由和状态管理。 +- [ ] backend 约束覆盖语言版本、框架、分层、响应结构、异常和数据访问。 +- [ ] security 约束覆盖认证、权限、敏感信息、数据范围和接口防护。 +- [ ] testing 约束覆盖已有测试工具、运行命令和缺失测试时的处理。 +- [ ] delivery 约束覆盖计划、Review、验收记录、发布或交付要求。 + +## 可复用性 + +- [ ] JeecgBoot 等项目特有规则没有写进通用规则。 +- [ ] 每条规则都标注了“可直接复用 / 需重新扫描 / 不可迁移”。 +- [ ] 换项目时必须重新扫描的内容已经列出。 +- [ ] 可以从本清单反推出生成步骤。 + +## 交付检查 + +- [ ] 生成文件中没有未完成占位符、示例假名或空标题。 +- [ ] Markdown 链接或路径经过抽样检查。 +- [ ] 规则文件标题不为空。 +- [ ] 交付说明列出已读来源、未读来源和仍需确认的问题。 diff --git a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/SKILL.md b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/SKILL.md new file mode 100644 index 0000000..916473a --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/SKILL.md @@ -0,0 +1,89 @@ +--- +name: review-business-delivery +description: Use when reviewing complex business delivery artifacts, AI-generated plans, PR diffs, or module designs for permission gaps, illegal state transitions, missing audit logs, weak exception handling, unclear dashboard metrics, missing tests, or incomplete acceptance evidence. +--- + +# Review Business Delivery + +## Core Principle + +Review behavior and risk before wording. Findings must be evidence-based, severity-ranked, and tied to a verification action. + +The review output should help the team decide whether to accept, conditionally accept, or reject the delivery. + +## Inputs + +Use any available inputs: + +- Requirement scope and non-goals. +- RBAC matrix and permission control plan. +- State transition table and illegal transition list. +- Audit SOP and exception-state list. +- Dashboard metric dictionary and API acceptance record. +- Code diff, API contract, test result, Browser verification record, or PR description. +- Project rules and constraints. + +If source evidence is missing, create an `证据缺口` section instead of guessing. + +## Review Flow + +1. Confirm delivery scope: what is being reviewed and what is outside scope. +2. Check source evidence: paths, rules, design tables, test results, and verification records. +3. Review permission risk: page/menu, button, backend API, and data scope. +4. Review state risk: legal transitions, illegal transitions, terminal states, duplicate submits, and role restrictions. +5. Review audit risk: action coverage, field completeness, masking, failure behavior, and consistency with business writes. +6. Review exception risk: empty, missing, invalid, forbidden, duplicate, concurrent, and downstream failure states. +7. Review dashboard risk: formula, filter, dimension, data source, permission, empty state, and manual calculation. +8. Review tests and acceptance: commands, roles, sample data, browser evidence, and unresolved risks. +9. Output findings sorted by severity. + +## Severity + +| Level | Meaning | +| --- | --- | +| P0 | Data loss, privilege bypass, irreversible wrong state, or release-blocking failure | +| P1 | Security, permission, audit, or state-machine defect with realistic business impact | +| P2 | Missing acceptance evidence, unclear metric, weak exception handling, or test gap | +| P3 | Maintainability, naming, documentation, or minor consistency issue | + +## Output Contract + +```md +## Review 结论 + +通过 / 有条件通过 / 不通过 + +## 问题清单 + +| 等级 | 模块 | 问题 | 证据 | 风险 | 修复建议 | 验收方式 | +| --- | --- | --- | --- | --- | --- | --- | + +## 证据缺口 + +| 缺口 | 影响 | 需要谁补充 | +| --- | --- | --- | + +## 待确认 + +| 问题 | 决策人 | 建议默认值 | +| --- | --- | --- | +``` + +Use the templates and checklists in `assets/` when writing files. + +## Quality Gates + +- Findings lead the response; summaries are secondary. +- Every P0/P1 finding cites a source path, table row, endpoint, role, state, metric, or verification record. +- Every finding has a concrete fix direction and acceptance method. +- Review does not accept frontend-only security controls. +- Missing tests or missing evidence are called out explicitly. +- Unclear business rules are marked `待确认`, not invented. + +## Common Mistakes + +- Do not write "整体不错" before listing risks. +- Do not merge all issues into one generic recommendation. +- Do not downgrade permission bypass, illegal state transitions, or missing audit for critical actions. +- Do not claim an issue is fixed without verification evidence. +- Do not review only code style when the requested delivery is business behavior. diff --git a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/agents/openai.yaml b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/agents/openai.yaml new file mode 100644 index 0000000..f2dc7c9 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "业务交付 Review" + short_description: "审查权限状态审计异常态看板测试与验收风险" + default_prompt: "Use $review-business-delivery to review complex business delivery artifacts for permission, state, audit, exception, and dashboard risks." + +policy: + allow_implicit_invocation: true diff --git a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/AIReview报告模板.md b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/AIReview报告模板.md new file mode 100644 index 0000000..0fe0982 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/AIReview报告模板.md @@ -0,0 +1,28 @@ +# AI Review 报告模板 + +## Review 输入 + +- PR diff： +- 需求说明： +- rules： +- 测试结果： +- 历史问题： + +## 结论 + +通过 / 有条件通过 / 不通过 + +## 问题清单 + +| 等级 | 文件/模块 | 问题 | 触发规则 | 风险 | 建议 | 测试/验收 | +| --- | --- | --- | --- | --- | --- | --- | + +## 不确定点 + +| 不确定点 | 需要谁确认 | 验证方式 | +| --- | --- | --- | + +## 是否建议合入 + +说明理由。 + diff --git a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/审计日志检查清单.md b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/审计日志检查清单.md new file mode 100644 index 0000000..0e271a4 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/审计日志检查清单.md @@ -0,0 +1,13 @@ +# 审计日志检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 创建记录 | 创建工单后能查询审计记录 | | +| 字段变更 | 编辑关键字段记录 oldValue/newValue | | +| 指派记录 | 指派负责人记录原负责人和新负责人 | | +| 状态记录 | 状态流转记录原状态和新状态 | | +| 操作人 | actor_id 和 actor_name 可追溯 | | +| 来源 | source 或 request_id 可追溯 | | +| 脱敏 | 敏感字段不明文进入审计 | | +| 失败处理 | 操作失败不写成功审计 | | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/异常态检查清单.md b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/异常态检查清单.md new file mode 100644 index 0000000..e1b6496 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/异常态检查清单.md @@ -0,0 +1,13 @@ +# 异常态检查清单 + +| 异常态 | 必须验证 | 结果 | +| --- | --- | --- | +| 空列表 | 页面显示空状态，不报错 | | +| 详情不存在 | 提示工单不存在，页面不崩溃 | | +| 权限不足 | 前端提示或隐藏，后端拒绝 | | +| 非法状态 | 返回非法流转，状态不变 | | +| 重复提交 | 只成功一次，只写一条有效审计 | | +| 参数缺失 | 返回参数错误，业务数据不变 | | +| 并发修改 | 拒绝覆盖或提示刷新 | | +| 看板无数据 | 图表显示空态，不显示假数据 | | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/权限上线前检查清单.md b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/权限上线前检查清单.md new file mode 100644 index 0000000..cacf893 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/权限上线前检查清单.md @@ -0,0 +1,12 @@ +# 权限上线前检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 菜单权限 | 工单菜单只对授权角色可见 | | +| 按钮权限 | 新增、编辑、删除、指派、状态按钮按权限显示 | | +| 接口权限 | 无权限账号直接请求敏感接口失败 | | +| 数据权限 | 普通用户只能看到授权范围内工单 | | +| 权限字符 | 前端按钮、菜单配置、后端接口命名一致 | | +| 审计 | 权限敏感操作成功后有审计记录 | | +| 反例验证 | 无权限账号不能绕过前端执行删除/指派 | | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/状态流转检查清单.md b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/状态流转检查清单.md new file mode 100644 index 0000000..2be5688 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/状态流转检查清单.md @@ -0,0 +1,12 @@ +# 状态流转检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 状态枚举 | 所有状态有统一枚举或字典 | | +| 合法流转 | 状态流转表中的合法路径可执行 | | +| 非法流转 | 非法路径被拒绝且状态不变 | | +| 角色限制 | 不同角色只能执行被授权动作 | | +| 前置条件 | 驳回原因、关闭条件、负责人等校验完整 | | +| 审计日志 | 每次成功流转写审计 | | +| 重复提交 | 重复点击不会产生重复有效流转 | | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/看板指标口径检查清单.md b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/看板指标口径检查清单.md new file mode 100644 index 0000000..b732c20 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/看板指标口径检查清单.md @@ -0,0 +1,13 @@ +# 看板指标口径检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 指标含义 | 每个指标有业务解释 | | +| 计算口径 | 每个指标有公式或筛选条件 | | +| 时间范围 | 明确按创建时间、关闭时间还是更新时间统计 | | +| 数据范围 | 不同角色的数据范围清楚 | | +| 空数据 | 空数据展示为 0 或空态，不误导 | | +| 分组一致性 | 分组总和能和总数对齐 | | +| 权限 | 无看板权限不能访问接口 | | +| 验收证据 | 至少有一组样例数据手工校验 | | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/看板接口验收清单.md b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/看板接口验收清单.md new file mode 100644 index 0000000..95e740a --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/看板接口验收清单.md @@ -0,0 +1,12 @@ +# 看板接口验收清单 + +| 验收项 | 请求条件 | 通过标准 | 结果 | +| --- | --- | --- | --- | +| 默认查询 | 管理员默认条件 | 返回完整指标 | | +| 时间过滤 | 指定 start/end | 只统计时间范围内数据 | | +| 类型过滤 | 指定工单类型 | 只统计对应类型 | | +| 空数据 | 无匹配条件 | 返回 0 或空集合 | | +| 无权限 | 未授权账号 | 返回 403 或业务拒绝 | | +| 数据范围 | 普通角色 | 只返回授权范围 | | +| 指标一致性 | 固定样例数据 | 与手工计算一致 | | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/阶段Review.prompt.md b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/阶段Review.prompt.md new file mode 100644 index 0000000..99c3843 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/阶段Review.prompt.md @@ -0,0 +1,30 @@ +# 阶段 Review Prompt + +```text +请对 JeecgBoot 工单模块阶段交付物做 Review。 + +输入材料： +- RBAC 权限矩阵 +- 权限控制方案 +- 状态流转表 +- 非法流转清单 +- 审计日志 SOP +- 异常态清单 +- 看板指标字典 +- 看板接口验收记录 +- 测试结果或验证记录 + +输出表格： +等级 | 模块 | 问题 | 触发规则 | 风险 | 修复建议 | 验收 + +要求： +1. 问题按 P0/P1/P2/P3 分级。 +2. 每个问题必须说明触发了哪条规则。 +3. 每条建议必须有验收方式。 +4. 输出不确定点和需要人工确认的内容。 + +约束： +- 不要只说整体不错。 +- 不要直接改代码。 +``` + diff --git a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/阶段Review报告.template.md b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/阶段Review报告.template.md new file mode 100644 index 0000000..eba0738 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/阶段Review报告.template.md @@ -0,0 +1,28 @@ +# 阶段 Review 报告 + +## Review 输入 + +- RBAC 权限矩阵： +- 权限控制方案： +- 状态流转表： +- 非法流转清单： +- 审计日志 SOP： +- 异常态清单： +- 看板指标字典： +- 看板接口验收记录： + +## 问题清单 + +| 等级 | 模块 | 问题 | 触发规则 | 风险 | 修复建议 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| P1 | 权限 | 删除接口只隐藏按钮，后端缺少权限校验 | 前端按钮不是安全边界 | 可绕过前端删除工单 | 后端补权限校验 | 无权限账号请求返回 403 | + +## 不确定点 + +| 不确定点 | 影响 | 需要谁确认 | +| --- | --- | --- | + +## 结论 + +通过 / 有条件通过 / 不通过 + diff --git a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/验收清单.md b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/验收清单.md new file mode 100644 index 0000000..230cd33 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/验收清单.md @@ -0,0 +1,71 @@ +# 验收清单 + +本清单用于判断学员是否真正掌握 JeecgBoot 工单案例，而不是只复制了 TRAE 输出。建议讲师在小组展示时逐项打分。 + +## 项目理解 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 能说明 JeecgBoot 前后端目录 | 至少指出 `jeecg-boot`、`jeecgboot-vue3`、`docs/project-knowledge` 的用途 | | +| 能定位后端入口 | 能指出 `JeecgSystemApplication.java` 和后端启动模块 | | +| 能定位前端入口 | 能指出 `src/main.ts`、路由、Pinia 和 API 请求层 | | +| 能区分事实和推断 | 对没有源码依据的业务规则标注为推断或待确认 | | +| 能记录不确定点 | 不确定内容没有被包装成确定事实 | | + +## 需求与接口 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 用户故事完整 | 覆盖管理员、负责人、研发、测试、只读用户 | | +| 非目标范围明确 | 明确课堂不做完整编码、生产部署、真实数据迁移 | | +| 接口契约完整 | 覆盖列表、详情、新增、编辑、指派、状态、审计、看板 | | +| 失败场景明确 | 每个关键接口至少有权限、参数、状态或数据不存在失败场景 | | +| 验收方式明确 | 每个关键需求都有可执行检查方法 | | + +## 权限与状态 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 权限矩阵完整 | 覆盖页面级、按钮级、接口级和数据范围 | | +| 权限字符合理 | 命名统一，并标注为建议而非源码事实 | | +| 后端权限未缺失 | 没有用前端按钮隐藏替代后端接口控制 | | +| 状态流转表完整 | 覆盖新建、处理中、待验证、已关闭、已驳回 | | +| 非法流转明确 | 至少列出 5 条非法流转和拒绝原因 | | + +## 审计、异常态与看板 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 审计操作覆盖关键动作 | 创建、编辑、指派、状态流转、关闭、评论至少覆盖 5 类 | | +| 审计字段可追溯 | 包含 actor、action、targetId、oldValue、newValue、source | | +| 敏感信息处理 | oldValue/newValue 有脱敏说明 | | +| 异常态可测试 | 权限不足、重复提交、非法状态、数据不存在、并发修改均覆盖 | | +| 看板指标可计算 | 每个指标有口径、维度、过滤条件和数据来源建议 | | + +## Review 与交付 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| Review 有证据 | 问题能回到路径、表格或业务规则 | | +| 风险按严重程度排序 | 高风险问题优先展示 | | +| 建议可行动 | 每条建议有修复方向和验收方式 | | +| 交付物齐全 | [worksheets.md](./worksheets.md) 中最终交付记录完整 | | +| 能沉淀资产 | 能说明哪些内容进入 [assets-index.md](./assets-index.md) 的资产库 | | + +## 评分建议 + +| 等级 | 分数 | 描述 | +| --- | ---: | --- | +| A | 90-100 | 依据充分，设计完整，风险清楚，验收可执行 | +| B | 75-89 | 主链路完整，少量不确定点或验收细节不足 | +| C | 60-74 | 有基本产出，但权限、状态、审计或异常态明显薄弱 | +| D | 0-59 | 泛泛总结项目，缺少源码依据或无法验收 | + +## 讲师判定原则 + +- 优先看证据，不优先看文字是否漂亮。 +- 优先看权限、状态、审计、异常态，不只看 CRUD。 +- 优先看不确定点是否被诚实标出。 +- 优先看能否复用到团队资产库。 +- 对没有依据的自信结论扣分。 + diff --git a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/SKILL.md b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/SKILL.md new file mode 100644 index 0000000..67b0c6c --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/SKILL.md @@ -0,0 +1,94 @@ +--- +name: track-review-fix-loop +description: Use when turning review findings into a fix-tracking record, deciding whether findings are valid, mapping fixes to files, verifying results, documenting unresolved items, or deciding which issues should become reusable rules, checklists, prompts, examples, or team assets. +--- + +# Track Review Fix Loop + +## Core Principle + +A review issue is not closed by saying "fixed". It closes only when the team records validity, changed artifacts, verification evidence, unresolved risk, and whether the lesson should become a reusable asset. + +## Inputs + +- Review report with numbered findings. +- Requirement or acceptance criteria. +- Code diff, design document, generated tables, or changed files. +- Test results, Browser verification evidence, API response samples, or manual validation notes. +- Existing team rules, checklists, examples, and asset index. + +If validation evidence is missing, mark the item as `未闭环`. + +## Status Model + +Use one of these statuses for each review item: + +| Status | Meaning | +| --- | --- | +| `成立-已修复` | Finding is valid, changed artifacts are listed, and verification evidence exists | +| `成立-暂不修复` | Finding is valid but deferred with reason, owner, and follow-up date | +| `不成立` | Finding is invalid with evidence | +| `需确认` | Finding depends on business or technical decision not available in current evidence | +| `未闭环` | Fix is claimed but evidence is missing | + +## Workflow + +1. Normalize review findings: ensure each issue has an ID, severity, module, risk, and suggested verification. +2. Decide validity: `成立`, `不成立`, or `需确认`; cite evidence. +3. Map valid fixes to changed files, tables, prompts, rules, or templates. +4. Verify each fix using commands, API checks, browser steps, role-based tests, or manual calculation. +5. Identify regressions: related permissions, states, audit actions, dashboard metrics, and exception states to re-check. +6. Decide asset sedimentation: rule, checklist, prompt, Command, Skill, example, or no asset. +7. Output unresolved items with owner and next step. + +## Output Contract + +```md +## 修复闭环结论 + +完成 / 部分完成 / 未完成 + +## 修复记录 + +| Review 编号 | 等级 | 问题 | 状态 | 修改文件/产物 | 验证证据 | 剩余风险 | 资产沉淀 | +| --- | --- | --- | --- | --- | --- | --- | --- | + +## 未闭环事项 + +| 编号 | 原因 | 负责人 | 下一步 | 截止时间 | +| --- | --- | --- | --- | --- | + +## 资产更新建议 + +| 来源问题 | 资产类型 | 建议文件 | 更新内容 | +| --- | --- | --- | --- | +``` + +Use `assets/修复记录.template.md` and `assets/Review修复闭环检查清单.md` when creating files. + +## Asset Decision Guide + +| If the issue is... | Asset | +| --- | --- | +| Repeated project convention violation | rule | +| Repeated review checklist miss | checklist | +| Reusable question or generation pattern | prompt | +| One-step repeatable agent action | command | +| Multi-step judgment workflow | skill | +| Good or bad teaching sample | example | + +## Quality Gates + +- Every fixed issue has verification evidence. +- Every deferred issue has owner and next step. +- Every invalid issue has source evidence, not opinion. +- P0/P1 issues cannot be marked complete without direct verification. +- Asset updates are specific file suggestions, not vague "沉淀经验". + +## Common Mistakes + +- Do not close issues with "已修复" without evidence. +- Do not erase invalid findings; keep why they are invalid. +- Do not mark business decisions as technical fixes. +- Do not create a Skill for a one-off checklist item. +- Do not ignore regressions around permissions, state transitions, audit logs, and dashboard metrics. diff --git a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/agents/openai.yaml b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/agents/openai.yaml new file mode 100644 index 0000000..500b19a --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Review 修复闭环" + short_description: "跟踪Review问题成立判断修复验证未闭环与资产沉淀" + default_prompt: "Use $track-review-fix-loop to turn review findings into verified fixes, unresolved decisions, and reusable team assets." + +policy: + allow_implicit_invocation: true diff --git a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/Review修复闭环检查清单.md b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/Review修复闭环检查清单.md new file mode 100644 index 0000000..39df455 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/Review修复闭环检查清单.md @@ -0,0 +1,12 @@ +# Review 修复闭环检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 问题编号 | 每个 Review 问题有编号 | | +| 成立判断 | 每个问题说明是否成立 | | +| 修改说明 | 成立问题说明修改文件和内容 | | +| 验证结果 | 每个修复有验证证据 | | +| 未修复说明 | 暂不修复的问题有原因和后续计划 | | +| 资产沉淀 | 有复用价值的问题已进入检查清单或反例库 | | +| 回归检查 | 修复后重新检查相关权限/状态/审计/看板 | | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/修复记录.template.md b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/修复记录.template.md new file mode 100644 index 0000000..37732cc --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/修复记录.template.md @@ -0,0 +1,8 @@ +# Review 修复记录 + +| Review 编号 | 问题 | 是否成立 | 修改文件 | 修改说明 | 验证结果 | 资产沉淀 | +| --- | --- | --- | --- | --- | --- | --- | +| R01 | 删除接口缺少后端权限校验 | 是 | WorkOrderController | 增加权限校验 | 无权限请求被拒绝 | 权限检查清单 | +| R02 | closed 可重新处理 | 是 | WorkOrderService | 补非法流转校验 | closed -> processing 失败 | 状态流转检查清单 | +| R03 | 看板关闭周期口径不清 | 是 | 指标字典/看板接口 | 明确 create_time 到 close_time | 指标说明已更新 | 看板指标口径清单 | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/修复记录生成.prompt.md b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/修复记录生成.prompt.md new file mode 100644 index 0000000..24fcfe7 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/修复记录生成.prompt.md @@ -0,0 +1,24 @@ +# 修复记录生成 Prompt + +```text +请根据阶段 Review 报告生成修复记录。 + +输入材料： +- Review 报告：<粘贴> +- 已完成修改说明：<粘贴> +- 验证结果：<粘贴> + +输出表格： +Review 编号 | 问题 | 是否成立 | 修改文件 | 修改说明 | 验证结果 | 资产沉淀 + +要求： +1. 如果问题不成立，说明理由和依据。 +2. 如果问题成立，说明修改了哪些文件。 +3. 每条修复必须有验证结果。 +4. 判断是否需要沉淀为资产，例如权限检查清单、状态流转检查清单、审计日志检查清单。 + +约束： +- 不要模糊写“已修复”。 +- 没有验证结果的修复不能算完成。 +``` + diff --git a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/审计日志缺失反例.md b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/审计日志缺失反例.md new file mode 100644 index 0000000..8dba8d6 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/审计日志缺失反例.md @@ -0,0 +1,32 @@ +# 审计日志缺失反例 + +## 场景 + +工单指派负责人成功，但没有记录审计日志。 + +## 问题表现 + +| 操作 | 结果 | +| --- | --- | +| 张三将工单指派给李四 | 工单负责人变更成功 | +| 查询审计日志 | 没有负责人变更记录 | + +## 风险 + +无法追溯负责人变化，出现延误或争议时无法定位责任。 + +## 修复要求 + +1. 指派成功后写审计日志。 +2. 记录原负责人、新负责人、操作人、时间、来源。 +3. 指派失败不写成功审计。 +4. 多步写入需要事务一致性。 + +## 验收 + +| 操作 | 预期 | +| --- | --- | +| 指派成功 | 审计列表出现 ASSIGN 记录 | +| 指派失败 | 不出现成功审计 | +| 查询详情 | 审计记录可在工单详情查看 | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/权限遗漏反例.md b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/权限遗漏反例.md new file mode 100644 index 0000000..0e3cfb7 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/权限遗漏反例.md @@ -0,0 +1,33 @@ +# 权限遗漏反例 + +## 场景 + +工单删除按钮在前端按权限隐藏，但后端删除接口没有权限校验。 + +## 问题代码表现 + +| 层级 | 表现 | +| --- | --- | +| 前端 | 普通研发账号看不到删除按钮 | +| 后端 | 直接请求 `/workOrder/delete` 仍可删除 | +| 审计 | 删除记录可能缺失 | + +## 风险 + +攻击者或误操作用户可以绕过前端直接调用接口删除工单。 + +## 修复要求 + +1. 后端删除接口增加权限校验。 +2. 删除前校验数据范围。 +3. 删除成功写审计日志。 +4. 无权限账号直接请求接口返回 403 或业务拒绝。 + +## 验收 + +| 账号 | 操作 | 预期 | +| --- | --- | --- | +| 管理员 | 删除允许删除的工单 | 成功并写审计 | +| 普通研发 | 直接请求删除接口 | 失败 | +| 只读用户 | 前端访问删除按钮 | 不可见 | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/看板指标口径不清反例.md b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/看板指标口径不清反例.md new file mode 100644 index 0000000..be5ee62 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/看板指标口径不清反例.md @@ -0,0 +1,31 @@ +# 看板指标口径不清反例 + +## 场景 + +看板展示“平均关闭周期”，但没有说明从哪个时间到哪个时间。 + +## 问题表现 + +| 指标 | 当前说明 | +| --- | --- | +| 平均关闭周期 | 最近工单平均处理时间 | + +## 风险 + +不同人理解不同：可能是创建到关闭，也可能是开始处理到关闭，导致管理判断失真。 + +## 修复要求 + +1. 明确定义为 `close_time - create_time` 或其他确定口径。 +2. 明确是否排除未关闭工单。 +3. 明确时间范围过滤字段。 +4. 用样例数据手工校验。 + +## 验收 + +| 样例 | 预期 | +| --- | --- | +| 工单 A 创建 1 日、关闭 3 日 | 周期 2 天 | +| 未关闭工单 | 不计入平均关闭周期 | +| 过滤 7 月 | 只统计 7 月范围内符合口径的数据 | + diff --git a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/非法状态流转反例.md b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/非法状态流转反例.md new file mode 100644 index 0000000..e675156 --- /dev/null +++ b/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/非法状态流转反例.md @@ -0,0 +1,31 @@ +# 非法状态流转反例 + +## 场景 + +已关闭工单可以直接被改回处理中。 + +## 问题表现 + +| 当前状态 | 动作 | 结果 | +| --- | --- | --- | +| 已关闭 | 开始处理 | 状态变成处理中 | + +## 风险 + +已关闭工单被重新打开但没有重开原因、没有审计、没有负责人确认，导致统计和责任链失真。 + +## 修复要求 + +1. Service 层集中校验状态流转。 +2. 已关闭工单只能通过“重新打开”动作变为新建。 +3. 重新打开必须填写原因。 +4. 所有成功流转写审计日志。 + +## 验收 + +| 操作 | 预期 | +| --- | --- | +| closed -> processing | 失败，状态不变 | +| closed -> reopen -> new | 成功，必须有原因 | +| 重开成功 | 审计记录 oldValue=closed, newValue=new | + diff --git a/deliverables/客户AI工程Skill交付包.zip b/deliverables/客户AI工程Skill交付包.zip new file mode 100644 index 0000000..541ff94 Binary files /dev/null and b/deliverables/客户AI工程Skill交付包.zip differ diff --git a/deliverables/客户AI工程Skill交付包/README.md b/deliverables/客户AI工程Skill交付包/README.md new file mode 100644 index 0000000..e7f7c62 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/README.md @@ -0,0 +1,46 @@ +# 客户 AI 工程 Skill 交付包 + +本交付包提供 4 个可复用 AI 工程 Skill，覆盖真实项目中从项目约束生成、复杂业务设计、交付 Review 到修复闭环的完整流程。 + +这些 Skill 不是单次 Prompt，而是可安装、可复制、可随项目持续维护的团队资产。 + +## 交付内容 + +```text +客户AI工程Skill交付包/ +├── README.md +├── 安装说明.md +├── skills/ +│ ├── generate-project-constraints/ +│ ├── design-complex-business-module/ +│ ├── review-business-delivery/ +│ └── track-review-fix-loop/ +└── examples/ + └── jeecgboot-work-order/ +``` + +## Skill 列表 + +| Skill | 用途 | 典型产物 | +| --- | --- | --- | +| `generate-project-constraints` | 从项目源码、配置、CI、文档中提取项目约束 | rules、约束提取表、验收清单 | +| `design-complex-business-module` | 设计复杂业务模块的权限、状态、审计、异常态和看板 | RBAC 矩阵、状态流转表、审计 SOP、看板指标字典 | +| `review-business-delivery` | 审查复杂业务交付物或 PR 的业务风险 | 阶段 Review 报告、风险清单、验收建议 | +| `track-review-fix-loop` | 跟踪 Review 问题修复、验证和资产沉淀 | 修复记录、未闭环清单、资产更新建议 | + +## 推荐使用顺序 + +1. 使用 `generate-project-constraints` 为客户项目生成项目规则。 +2. 使用 `design-complex-business-module` 生成复杂业务设计资产。 +3. 使用 `review-business-delivery` 审查设计、代码或阶段交付物。 +4. 使用 `track-review-fix-loop` 跟踪修复、验证结果和资产沉淀。 + +## 适用项目 + +适用于后台管理系统、低代码平台二开、CRM、工单、审批、运营系统、数据看板等企业业务项目。 + +这些 Skill 不要求项目必须有 `CLAUDE.md`、`AGENTS.md` 或 `README.md`。如果项目没有显式说明文档，Skill 会从配置、源码模式、测试和 CI 中提取约束，并把无法证明的内容标记为待确认。 + +## 示例说明 + +`examples/jeecgboot-work-order/` 提供 JeecgBoot 工单案例参考，帮助理解这些 Skill 在真实后台项目中的使用方式。该示例不是通用 Skill 安装项。 diff --git a/deliverables/客户AI工程Skill交付包/examples/jeecgboot-work-order/JeecgBoot工单模块开发审查.skill.md b/deliverables/客户AI工程Skill交付包/examples/jeecgboot-work-order/JeecgBoot工单模块开发审查.skill.md new file mode 100644 index 0000000..4bc5f74 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/examples/jeecgboot-work-order/JeecgBoot工单模块开发审查.skill.md @@ -0,0 +1,44 @@ +# JeecgBoot 工单模块开发审查 Skill + +## 触发场景 + +涉及工单列表、详情、评论、状态、指派、看板、权限字符、数据权限、操作日志的需求拆解、代码生成或代码修改。 + +## 输入材料 + +- PR diff 或相关文件。 +- 工单需求说明。 +- 数据模型与接口契约。 +- 当前 rules。 +- 前端页面文件。 +- API 模块文件。 +- 后端 Controller / Service。 +- 权限矩阵。 +- 状态流转表。 +- 审计日志 SOP。 + +## 执行步骤 + +1. 识别需求范围和非目标范围。 +2. 检查字段、接口契约和页面状态是否完整。 +3. 审查 JeecgBoot 生成代码的字段、查询、分页、字典和异常态。 +4. 检查新增、编辑、删除、指派、状态变更的前端按钮与后端权限。 +5. 检查操作日志、数据权限和测试缺口。 +6. 检查看板指标口径和接口验收记录。 +7. 输出风险、不确定点和验收建议。 + +## 输出格式 + +- 需求范围确认。 +- 接口契约问题表。 +- 代码生成 Review 清单。 +- 权限风险表。 +- 状态流转风险表。 +- 审计日志风险表。 +- 测试缺口清单。 +- 不确定点清单。 + +## 验收标准 + +每个关键结论必须标注文件、函数、注解、配置或调用链依据。每条建议必须有验收方式。 + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/SKILL.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/SKILL.md new file mode 100644 index 0000000..36337fa --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/SKILL.md @@ -0,0 +1,73 @@ +--- +name: design-complex-business-module +description: Use when designing a complex enterprise business module that needs RBAC permissions, frontend/backend permission controls, state transitions, illegal transition handling, audit logging, exception states, dashboard metrics, interface contracts, or acceptance-ready design assets. +--- + +# Design Complex Business Module + +## Core Principle + +Design the control surfaces before designing code. For complex business modules, produce permission, state, audit, exception, dashboard, and acceptance assets before implementation planning. + +Do not jump from a requirement to CRUD code. Every business rule must have an owner, a source, and a verification method. + +## Inputs + +Collect what exists, then mark gaps explicitly: + +- Business requirement or user stories. +- Target project paths and project constraints. +- Existing roles, permissions, menus, routes, API layer, backend controllers/services, data model, and audit/logging patterns. +- Known non-goals and delivery deadline. +- Existing rules, checklists, or project knowledge docs. + +If project evidence is missing, label outputs as `建议` or `待确认`, not `事实`. + +## Workflow + +1. Define scope: module name, actors, key workflows, non-goals, and acceptance boundary. +2. Build the RBAC matrix: roles x features, with `允许`, `拒绝`, or `条件允许`. +3. Translate RBAC into a permission control plan: page/menu, button, backend API, and data scope. +4. Design the state machine: states, actions, allowed roles, preconditions, post-actions, and terminal states. +5. List illegal transitions and rejection behavior. +6. Design audit logging: actions, write timing, actor, target, old/new values, source/request id, masking, and failure behavior. +7. Complete exception states: permission denied, missing data, invalid state, duplicate submit, validation failure, concurrency, empty dashboard, empty audit log. +8. Define dashboard metrics: meaning, formula, dimensions, filters, data source, permission, empty state, and manual verification. +9. Produce interface and acceptance notes only after the above assets are consistent. + +## Output Contract + +Generate these assets unless the user narrows scope: + +```text +RBAC权限矩阵 +权限控制方案 +状态流转表 +非法流转清单 +审计日志SOP +异常态清单 +看板指标字典 +看板接口验收记录 +不确定点清单 +``` + +Use the templates in `assets/` when creating files. + +## Quality Gates + +- Every sensitive action has frontend visibility control and backend enforcement. +- Data permissions are not replaced by button hiding. +- Every state transition has a reverse or rejection story, or is explicitly terminal. +- Every illegal transition has expected system response and validation method. +- Every successful critical operation has an audit record; failed operations do not write success audit. +- Every dashboard metric has a formula or filter logic that can be manually checked. +- Every output distinguishes `事实`, `推断`, `建议`, and `待确认`. + +## Common Mistakes + +- Do not design UI first and add permissions later. +- Do not use "admin can do everything" as a complete RBAC design. +- Do not put all status rules into prose; use a state table. +- Do not write "record audit log" without naming fields and write timing. +- Do not define dashboard cards without metric formulas and data scope. +- Do not turn project-specific permission strings into facts without source evidence. diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/agents/openai.yaml b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/agents/openai.yaml new file mode 100644 index 0000000..1d0695e --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "复杂业务模块设计" + short_description: "生成权限状态审计异常态看板等复杂业务设计资产" + default_prompt: "Use $design-complex-business-module to design permissions, state transitions, audit logs, exception states, and dashboard metrics for this business module." + +policy: + allow_implicit_invocation: true diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/RBAC权限矩阵.template.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/RBAC权限矩阵.template.md new file mode 100644 index 0000000..1885beb --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/RBAC权限矩阵.template.md @@ -0,0 +1,16 @@ +# 工单 RBAC 权限矩阵 + +| 功能点 | 管理员 | 工单负责人 | 研发处理人 | 测试验证人 | 只读观察者 | 权限字符建议 | 备注 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 查看列表 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | work:order:list | 按数据范围 | +| 查看详情 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | work:order:query | 仅可见范围 | +| 新建工单 | 允许 | 允许 | 允许 | 允许 | 拒绝 | work:order:add | | +| 编辑工单 | 允许 | 条件允许 | 条件允许 | 拒绝 | 拒绝 | work:order:edit | 状态限制 | +| 指派负责人 | 允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | work:order:assign | | +| 状态流转 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | work:order:transition | 按状态 | +| 关闭工单 | 允许 | 条件允许 | 拒绝 | 条件允许 | 拒绝 | work:order:close | 测试验证后 | +| 删除工单 | 允许 | 拒绝 | 拒绝 | 拒绝 | 拒绝 | work:order:delete | 高危操作 | +| 查看审计日志 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | work:order:audit | | +| 查看看板 | 允许 | 允许 | 条件允许 | 条件允许 | 条件允许 | work:order:dashboard | 按数据范围 | +| 导出数据 | 允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | work:order:export | | + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/RBAC权限矩阵生成.prompt.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/RBAC权限矩阵生成.prompt.md new file mode 100644 index 0000000..84a9100 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/RBAC权限矩阵生成.prompt.md @@ -0,0 +1,25 @@ +# RBAC 权限矩阵生成 Prompt + +```text +请基于 JeecgBoot 工单模块设计 RBAC 权限矩阵。 + +输入材料： +- 工单模块需求：<粘贴需求> +- 角色列表：管理员、工单负责人、研发处理人、测试验证人、只读观察者 +- 功能点：查看列表、查看详情、新建、编辑、指派、状态流转、关闭、删除、查看审计、查看看板、导出 +- 项目依据：<粘贴权限、路由、菜单相关路径> + +输出要求： +1. 先列事实依据：JeecgBoot 权限、菜单、动态路由相关路径。 +2. 输出 RBAC 权限矩阵：角色 x 功能点，允许、拒绝、条件允许。 +3. 输出权限字符建议，必须标注为建议。 +4. 输出页面级、按钮级、接口级、数据范围四层控制。 +5. 输出不确定点：哪些权限必须业务方确认。 +6. 输出验收方式：如何证明权限确实生效。 + +约束： +- 不要直接改代码。 +- 不要把前端按钮隐藏当作安全边界。 +- 所有结论必须区分事实、推断、建议。 +``` + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/审计日志SOP.template.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/审计日志SOP.template.md new file mode 100644 index 0000000..876d692 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/审计日志SOP.template.md @@ -0,0 +1,40 @@ +# 工单审计日志 SOP + +## 记录原则 + +所有会改变工单关键业务状态、负责人、可见性或结论的动作都必须记录审计日志。 + +## 审计字段 + +| 字段 | 含义 | 示例 | +| --- | --- | --- | +| ticket_id | 工单 ID | WO-001 | +| actor_id | 操作人 ID | 1001 | +| actor_name | 操作人名称 | zhangsan | +| action | 操作类型 | ASSIGN | +| field_name | 变更字段 | assignee | +| old_value | 旧值 | lisi | +| new_value | 新值 | wangwu | +| source | 来源 | web | +| request_id | 请求 ID | req-001 | +| created_at | 操作时间 | 2026-07-01 10:00:00 | + +## 必须记录的动作 + +| 动作 | 写入时机 | oldValue | newValue | 验收 | +| --- | --- | --- | --- | --- | +| 创建工单 | 创建成功后 | 空 | 工单摘要 | 审计列表可见 | +| 编辑字段 | 保存成功后 | 修改前字段 | 修改后字段 | 字段前后值正确 | +| 指派负责人 | 指派成功后 | 原负责人 | 新负责人 | 审计记录负责人变化 | +| 状态流转 | 状态变更成功后 | 原状态 | 新状态 | 审计记录状态变化 | +| 评论新增 | 评论保存后 | 空 | 评论摘要 | 审计记录评论动作 | +| 关闭工单 | 关闭成功后 | 原状态 | 已关闭 | 审计记录关闭时间 | + +## 验收方式 + +1. 执行关键操作后能在审计列表查询到记录。 +2. oldValue/newValue 和实际变更一致。 +3. 敏感字段已脱敏。 +4. 操作失败不写成功审计。 +5. 多步写入失败时审计和业务数据保持一致。 + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/审计日志检查清单.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/审计日志检查清单.md new file mode 100644 index 0000000..0e271a4 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/审计日志检查清单.md @@ -0,0 +1,13 @@ +# 审计日志检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 创建记录 | 创建工单后能查询审计记录 | | +| 字段变更 | 编辑关键字段记录 oldValue/newValue | | +| 指派记录 | 指派负责人记录原负责人和新负责人 | | +| 状态记录 | 状态流转记录原状态和新状态 | | +| 操作人 | actor_id 和 actor_name 可追溯 | | +| 来源 | source 或 request_id 可追溯 | | +| 脱敏 | 敏感字段不明文进入审计 | | +| 失败处理 | 操作失败不写成功审计 | | + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态检查清单.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态检查清单.md new file mode 100644 index 0000000..e1b6496 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态检查清单.md @@ -0,0 +1,13 @@ +# 异常态检查清单 + +| 异常态 | 必须验证 | 结果 | +| --- | --- | --- | +| 空列表 | 页面显示空状态，不报错 | | +| 详情不存在 | 提示工单不存在，页面不崩溃 | | +| 权限不足 | 前端提示或隐藏，后端拒绝 | | +| 非法状态 | 返回非法流转，状态不变 | | +| 重复提交 | 只成功一次，只写一条有效审计 | | +| 参数缺失 | 返回参数错误，业务数据不变 | | +| 并发修改 | 拒绝覆盖或提示刷新 | | +| 看板无数据 | 图表显示空态，不显示假数据 | | + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态清单.template.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态清单.template.md new file mode 100644 index 0000000..286eaff --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态清单.template.md @@ -0,0 +1,13 @@ +# 工单异常态清单 + +| 场景 | 触发条件 | 前端表现 | 后端响应 | 验收 | +| --- | --- | --- | --- | --- | +| 权限不足 | 无权限操作 | 按钮不可见或提示无权限 | 403 或业务拒绝 | 不完成操作 | +| 工单不存在 | 传入错误 ID | 显示不存在 | 404 或业务错误 | 页面不崩溃 | +| 非法状态流转 | closed -> processing | 提示非法流转 | 状态不变 | 数据状态不变 | +| 重复提交 | 连续点击提交 | 按钮 loading/禁用 | 只处理一次 | 只生成一条有效审计 | +| 参数缺失 | 驳回缺少原因 | 表单校验提示 | 参数错误 | 不改变状态 | +| 并发修改 | 数据版本过期 | 提示刷新 | 拒绝覆盖 | 旧数据不覆盖新数据 | +| 看板无数据 | 无匹配记录 | 空状态 | 返回空集合 | 页面不报错 | +| 审计日志为空 | 无审计记录 | 空状态 | 返回空集合 | 页面不报错 | + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态补齐.prompt.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态补齐.prompt.md new file mode 100644 index 0000000..17bd793 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态补齐.prompt.md @@ -0,0 +1,24 @@ +# 异常态补齐 Prompt + +```text +请基于 JeecgBoot 工单模块，列出状态流转、指派、删除、查询详情、审计日志、看板相关的异常态和防御性逻辑。 + +输出表格： +场景 | 触发条件 | 前端表现 | 后端响应 | 用户提示 | 测试点 | 验收 + +必须覆盖： +- 权限不足 +- 工单不存在 +- 非法状态流转 +- 重复提交 +- 参数缺失 +- 并发修改 +- 看板无数据 +- 审计日志为空 + +约束： +- 先列异常态，不要直接改代码。 +- 给出每个异常态的验收步骤。 +- 标注事实、推断、建议和不确定点。 +``` + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/权限上线前检查清单.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/权限上线前检查清单.md new file mode 100644 index 0000000..cacf893 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/权限上线前检查清单.md @@ -0,0 +1,12 @@ +# 权限上线前检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 菜单权限 | 工单菜单只对授权角色可见 | | +| 按钮权限 | 新增、编辑、删除、指派、状态按钮按权限显示 | | +| 接口权限 | 无权限账号直接请求敏感接口失败 | | +| 数据权限 | 普通用户只能看到授权范围内工单 | | +| 权限字符 | 前端按钮、菜单配置、后端接口命名一致 | | +| 审计 | 权限敏感操作成功后有审计记录 | | +| 反例验证 | 无权限账号不能绕过前端执行删除/指派 | | + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/权限控制方案.template.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/权限控制方案.template.md new file mode 100644 index 0000000..d7d0910 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/权限控制方案.template.md @@ -0,0 +1,12 @@ +# 工单权限控制方案 + +| 操作 | 前端入口 | 权限字符 | 后端接口 | 后端校验 | 数据权限 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| 新增工单 | 新增按钮 | work:order:add | /workOrder/add | 权限注解 | 无 | 无权限账号看不到按钮且直接请求失败 | +| 编辑工单 | 编辑按钮 | work:order:edit | /workOrder/edit | 权限注解 + 状态校验 | 负责人/创建人范围 | 越权账号返回 403 或业务拒绝 | +| 指派负责人 | 指派按钮 | work:order:assign | /workOrder/assign | 权限注解 | 管理员/负责人范围 | 普通研发无法指派他人 | +| 状态流转 | 状态按钮 | work:order:transition | /workOrder/transition | 权限注解 + 状态机校验 | 相关工单范围 | 非法流转失败 | +| 删除工单 | 删除按钮 | work:order:delete | /workOrder/delete | 权限注解 | 管理员范围 | 非管理员返回 403 | +| 查看审计 | 审计页签 | work:order:audit | /workOrder/audit/list | 权限注解 | 相关工单范围 | 无权限不可见且接口拒绝 | +| 看板 | 看板菜单 | work:order:dashboard | /workOrder/dashboard | 权限注解 | 数据范围过滤 | 不同角色数据范围不同 | + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/权限控制方案生成.prompt.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/权限控制方案生成.prompt.md new file mode 100644 index 0000000..7dcf834 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/权限控制方案生成.prompt.md @@ -0,0 +1,24 @@ +# 权限控制方案生成 Prompt + +```text +请基于工单模块 RBAC 权限矩阵，生成 JeecgBoot 权限控制方案。 + +输入材料： +- RBAC 权限矩阵：<粘贴> +- 接口契约表：<粘贴> +- 当前项目权限相关路径：<粘贴> +- 当前 rules：<粘贴> + +输出要求： +1. 权限控制方案表，列为：操作、前端入口、权限字符、后端接口、后端校验、数据权限、验收。 +2. 影响范围：前端页面、API 文件、后端 Controller、Service、菜单配置、数据权限。 +3. 缺失风险：按钮隐藏、接口未校验、数据范围不清、权限字符不一致。 +4. 无权限访问验收步骤。 +5. 不确定点和需要人工确认的权限边界。 + +约束： +- 不要直接改代码。 +- 后端接口权限必须单独说明。 +- 每个敏感操作必须有验收方式。 +``` + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/状态流转检查清单.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/状态流转检查清单.md new file mode 100644 index 0000000..2be5688 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/状态流转检查清单.md @@ -0,0 +1,12 @@ +# 状态流转检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 状态枚举 | 所有状态有统一枚举或字典 | | +| 合法流转 | 状态流转表中的合法路径可执行 | | +| 非法流转 | 非法路径被拒绝且状态不变 | | +| 角色限制 | 不同角色只能执行被授权动作 | | +| 前置条件 | 驳回原因、关闭条件、负责人等校验完整 | | +| 审计日志 | 每次成功流转写审计 | | +| 重复提交 | 重复点击不会产生重复有效流转 | | + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/状态流转表.template.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/状态流转表.template.md new file mode 100644 index 0000000..29456b8 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/状态流转表.template.md @@ -0,0 +1,22 @@ +# 工单状态流转表 + +| 当前状态 | 动作 | 目标状态 | 允许角色 | 前置条件 | 后置动作 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| 新建 | 指派 | 新建 | 管理员/负责人 | 工单未关闭 | 写审计日志 | 指派人变化且状态不变 | +| 新建 | 开始处理 | 处理中 | 研发处理人/负责人 | 已指派处理人 | 写审计日志 | 状态变为处理中 | +| 处理中 | 提交验证 | 待验证 | 研发处理人/负责人 | 处理说明不为空 | 写审计日志 | 状态变为待验证 | +| 待验证 | 验证通过 | 已关闭 | 测试验证人/负责人 | 验证结果通过 | 写审计日志和关闭时间 | 状态变为已关闭 | +| 待验证 | 验证驳回 | 已驳回 | 测试验证人/负责人 | 驳回原因不为空 | 写审计日志 | 状态变为已驳回 | +| 已驳回 | 重新处理 | 处理中 | 研发处理人/负责人 | 驳回原因已读 | 写审计日志 | 状态变为处理中 | +| 已关闭 | 重新打开 | 新建 | 管理员 | 重开原因不为空 | 写审计日志 | 状态变为新建 | + +## 非法流转清单 + +| 当前状态 | 尝试动作 | 问题 | 系统响应 | 验收 | +| --- | --- | --- | --- | --- | +| 已关闭 | 开始处理 | 关闭后不能直接处理 | 返回非法流转 | 状态不变 | +| 新建 | 验证通过 | 未处理不能验证 | 返回非法流转 | 状态不变 | +| 待验证 | 提交验证 | 重复提交验证 | 返回非法流转 | 只保留原状态 | +| 处理中 | 验证通过 | 未进入待验证 | 返回非法流转 | 状态不变 | +| 已驳回 | 关闭 | 驳回后不能直接关闭 | 返回非法流转 | 状态不变 | + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/状态流转设计.prompt.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/状态流转设计.prompt.md new file mode 100644 index 0000000..58b609b --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/状态流转设计.prompt.md @@ -0,0 +1,34 @@ +# 状态流转设计 Prompt + +```text +请为 JeecgBoot 工单模块设计状态流转规则。 + +状态候选： +- 新建 +- 处理中 +- 待验证 +- 已关闭 +- 已驳回 + +动作候选： +- 指派 +- 开始处理 +- 提交验证 +- 验证通过 +- 验证驳回 +- 关闭 +- 重新打开 + +输出要求： +1. 状态流转表：当前状态、动作、目标状态、允许角色、前置条件、后置动作、验收。 +2. 非法流转清单：当前状态、尝试动作、问题、系统响应、验收。 +3. 接口设计建议。 +4. 测试点清单。 +5. 不确定点。 + +约束： +- 先出状态表，不要直接写 if else。 +- 已关闭、越权、缺少说明、重复提交必须覆盖。 +- 每条规则必须有验收方式。 +``` + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板指标口径检查清单.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板指标口径检查清单.md new file mode 100644 index 0000000..b732c20 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板指标口径检查清单.md @@ -0,0 +1,13 @@ +# 看板指标口径检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 指标含义 | 每个指标有业务解释 | | +| 计算口径 | 每个指标有公式或筛选条件 | | +| 时间范围 | 明确按创建时间、关闭时间还是更新时间统计 | | +| 数据范围 | 不同角色的数据范围清楚 | | +| 空数据 | 空数据展示为 0 或空态，不误导 | | +| 分组一致性 | 分组总和能和总数对齐 | | +| 权限 | 无看板权限不能访问接口 | | +| 验收证据 | 至少有一组样例数据手工校验 | | + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板指标字典.template.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板指标字典.template.md new file mode 100644 index 0000000..32da66b --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板指标字典.template.md @@ -0,0 +1,13 @@ +# 工单看板指标字典 + +| 指标 | 含义 | 口径 | 数据来源 | 展示方式 | 权限 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| 工单总数 | 当前筛选范围内工单数量 | count(ticket_id) | 工单表 | 指标卡 | 看板权限 | 与列表同条件数量一致 | +| 未关闭工单数 | 状态不是已关闭的数量 | status != closed | 工单表 | 指标卡 | 看板权限 | 过滤状态验证 | +| 平均关闭周期 | 从创建到关闭平均耗时 | avg(close_time - create_time) | 工单表 | 指标卡/趋势 | 看板权限 | 抽样计算一致 | +| 按优先级分布 | 高中低优先级数量 | group by priority | 工单表/字典 | 饼图/柱状图 | 看板权限 | 分组总和等于总数 | +| 按类型分布 | 缺陷/需求/支持数量 | group by type | 工单表/字典 | 柱状图 | 看板权限 | 分组总和等于总数 | +| 缺陷趋势 | 按日期统计缺陷工单 | type=bug group by date | 工单表 | 折线图 | 看板权限 | 日期范围正确 | +| 逾期工单数 | 超过 SLA 未关闭数量 | due_time < now and status != closed | 工单表 | 指标卡 | 看板权限 | SLA 口径明确 | +| 人员处理负载 | 按负责人统计未关闭数量 | group by assignee | 工单表 | 排行榜 | 管理员/负责人 | 数据范围正确 | + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板指标设计.prompt.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板指标设计.prompt.md new file mode 100644 index 0000000..9851ec7 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板指标设计.prompt.md @@ -0,0 +1,28 @@ +# 看板指标设计 Prompt + +```text +请为 JeecgBoot 工单模块设计研发效能看板指标。 + +指标方向： +- 工单总数 +- 未关闭工单数 +- 平均关闭周期 +- 按优先级分布 +- 按类型分布 +- 缺陷趋势 +- 逾期工单数 +- 人员处理负载 + +输出要求： +1. 指标字典：指标名、含义、口径、维度、过滤条件、数据来源、展示方式、权限。 +2. 看板统计接口契约建议。 +3. 空态、错误态、无权限态。 +4. 验收方式。 +5. 不确定点。 + +约束： +- 每个指标必须可计算。 +- 不要只写页面 UI。 +- 指标口径不清必须写入不确定点。 +``` + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板接口验收.prompt.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板接口验收.prompt.md new file mode 100644 index 0000000..b3f2e75 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板接口验收.prompt.md @@ -0,0 +1,27 @@ +# 看板接口验收 Prompt + +```text +请为 JeecgBoot 工单看板统计接口生成验收记录。 + +输入材料： +- 看板指标字典：<粘贴> +- 看板接口契约：<粘贴> +- 权限矩阵：<粘贴> + +输出表格： +验收项 | 账号/条件 | 请求参数 | 预期 | 实际 | 证据 | 结论 + +必须覆盖： +- 有数据 +- 空数据 +- 无权限 +- 过滤条件 +- 指标口径 +- 时间范围 +- 数据范围 + +约束： +- 不要只说“接口正常”。 +- 每个指标至少有一个验收动作。 +``` + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板接口验收清单.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板接口验收清单.md new file mode 100644 index 0000000..95e740a --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板接口验收清单.md @@ -0,0 +1,12 @@ +# 看板接口验收清单 + +| 验收项 | 请求条件 | 通过标准 | 结果 | +| --- | --- | --- | --- | +| 默认查询 | 管理员默认条件 | 返回完整指标 | | +| 时间过滤 | 指定 start/end | 只统计时间范围内数据 | | +| 类型过滤 | 指定工单类型 | 只统计对应类型 | | +| 空数据 | 无匹配条件 | 返回 0 或空集合 | | +| 无权限 | 未授权账号 | 返回 403 或业务拒绝 | | +| 数据范围 | 普通角色 | 只返回授权范围 | | +| 指标一致性 | 固定样例数据 | 与手工计算一致 | | + diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板接口验收记录.template.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板接口验收记录.template.md new file mode 100644 index 0000000..6ddf072 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板接口验收记录.template.md @@ -0,0 +1,11 @@ +# 工单看板接口验收记录 + +| 验收项 | 账号/条件 | 请求参数 | 预期 | 实际 | 证据 | 结论 | +| --- | --- | --- | --- | --- | --- | --- | +| 工单总数 | 管理员 | 默认筛选 | 返回总数 | | | | +| 空数据 | 管理员 + 无匹配条件 | 不存在的日期范围 | 返回空集合或 0 | | | | +| 无权限 | 只读外角色 | 默认筛选 | 返回 403 或业务拒绝 | | | | +| 时间过滤 | 管理员 | start/end | 只统计范围内数据 | | | | +| 数据范围 | 普通研发 | 默认筛选 | 只返回本人相关数据 | | | | +| 指标口径 | 管理员 | 固定样例数据 | 与手工计算一致 | | | | + diff --git a/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/SKILL.md b/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/SKILL.md new file mode 100644 index 0000000..d5fb05b --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/SKILL.md @@ -0,0 +1,125 @@ +--- +name: generate-project-constraints +description: Use when a user needs to extract project-specific AI coding constraints, team rules, repository rules, .trae rules, Cursor rules, CLAUDE.md/AGENTS.md content, or reusable rules/checklists from an existing software project, including projects without README or explicit instruction files. +--- + +# Generate Project Constraints + +## Core Principle + +Generate constraints from evidence, not preference. Treat instruction files as optional inputs: if they exist, read them first; if not, use code-only mode and infer cautiously from config, source patterns, tests, CI, and runtime behavior. + +Every output rule must be labeled as `硬约束`, `观察性约束`, or `待确认约束`, and every non-obvious rule must cite source paths. + +## Evidence Order + +Read available sources in this order: + +1. Explicit instructions: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.trae/rules`, `.cursor/rules`, `.cursorrules`, `README*`, `CONTRIBUTING*`, team docs. +2. Build/runtime manifests: `package.json`, lockfiles, `pom.xml`, `build.gradle`, `.env*`, `application*.yml`, Docker files, compose files. +3. Quality gates: ESLint, Prettier, Stylelint, Checkstyle, Spotless, PMD, Jest/Vitest/JUnit/Playwright configs, CI workflows. +4. Source patterns: API layer, response wrappers, auth/permission flow, routing, state management, controller/service/repository or mapper layers, error handling, audit/logging. +5. Existing examples: representative modules that already implement the pattern requested by the user. + +If a source category is absent, record it in `缺失证据`, then continue. Never block only because `README.md`, `CLAUDE.md`, or `AGENTS.md` is missing. + +## Constraint Levels + +| Level | Use When | Wording | +| --- | --- | --- | +| `硬约束` | Directly proven by config, build files, CI, runtime settings, or explicit team docs | `必须` / `禁止` | +| `观察性约束` | Repeated pattern appears in existing code but no written rule exists | `默认采用` / `优先复用` | +| `待确认约束` | Needed for delivery but not provable from the repo | `需团队确认` | + +Do not upgrade an observed pattern into a hard rule unless a source explicitly requires it. + +## Workflow + +1. Define scope: target repo path, output path, desired rule categories, and whether the user wants installable Skill assets or plain rules. +2. Inventory sources with fast shell commands such as `rg --files`, `find`, `sed`, and focused `rg` searches. +3. Extract facts into an evidence table: source path, observed fact, affected area, confidence, and candidate rule. +4. Normalize candidate rules into the output contract below. +5. Validate each rule against at least one source path or mark it `待确认约束`. +6. Write rules and checklists. Prefer small files such as `rules/backend.md`, `rules/frontend.md`, `rules/security.md`, `rules/testing.md`, `rules/delivery.md`. +7. Run verification: placeholder scan, broken-path spot checks, and a final pass that every hard/observed rule has evidence. + +## Output Contract + +When the user asks to generate constraints, produce these artifacts unless they request a lighter output: + +```text +ai-dev-assets/ +├── rules/ +│ ├── global.md +│ ├── frontend.md +│ ├── backend.md +│ ├── security.md +│ ├── testing.md +│ └── delivery.md +├── templates/ +│ └── 项目约束提取表.template.md +└── checklists/ + └── 项目约束验收清单.md +``` + +Each rule file should use this structure: + +```md +## 规则名称 + +- 级别：硬约束 | 观察性约束 | 待确认约束 +- 适用场景： +- 必须： +- 禁止： +- 来源证据： +- 验收方式： +- 迁移说明： +``` + +Use `assets/项目约束提取表.template.md` and `assets/项目约束验收清单.md` as copyable starting points when helpful. + +## Code-Only Mode + +Use this when no explicit instruction files exist. + +Required behavior: + +- State that explicit project docs were not found. +- Build constraints from manifests, configs, CI, tests, and repeated source patterns. +- Label all pattern-derived rules as `观察性约束`. +- Create a `待确认约束` section for business delivery rules that the repo cannot prove, such as review gates, branch policy, audit requirements, test minimums, and release process. + +Good wording: + +```md +本项目未发现 `AGENTS.md`、`CLAUDE.md`、`.trae/rules` 或 `README.md` 中的明确 AI 协作规则。以下约束来自配置文件和源码模式；未能由仓库证明的内容已标记为待确认。 +``` + +## JeecgBoot Example + +For the training case only, JeecgBoot evidence can generate rules such as: + +- `硬约束`: backend uses `Result` response wrapper, from backend `CLAUDE.md`. +- `硬约束`: frontend uses `defHttp` and backend menu permission mode, from frontend `CLAUDE.md`. +- `硬约束`: backend modification blocks require `update-begin` / `update-end`, from backend `CLAUDE.md`. +- `观察性约束`: business features should follow existing controller/service/mapper layering after verifying representative modules. + +Keep these examples out of generic outputs unless the target project is JeecgBoot or explicitly similar. + +## Quality Gates + +Before claiming completion: + +- List generated files. +- Scan generated files for unfinished placeholders, dummy names, and empty headings. +- Check hard and observed constraints cite source paths. +- Confirm missing evidence is not silently converted into rules. +- Report which sources were read and which rule categories remain `待确认`. + +## Common Mistakes + +- Do not require `CLAUDE.md`, `AGENTS.md`, or `README.md` to exist. +- Do not turn general best practices into project rules without evidence. +- Do not merge business constraints, technical constraints, and delivery constraints into one vague list. +- Do not omit verification steps; rules are useful only if a learner or team can check them. +- Do not copy JeecgBoot-specific constraints into unrelated projects. diff --git a/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/agents/openai.yaml b/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/agents/openai.yaml new file mode 100644 index 0000000..43f4885 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "项目约束生成" + short_description: "从项目证据提取可执行规则、模板和验收清单" + default_prompt: "Use $generate-project-constraints to extract project-specific AI coding constraints, rules, and checklists from this repository." + +policy: + allow_implicit_invocation: true diff --git a/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/assets/项目约束提取表.template.md b/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/assets/项目约束提取表.template.md new file mode 100644 index 0000000..2fc3a9f --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/assets/项目约束提取表.template.md @@ -0,0 +1,43 @@ +# 项目约束提取表 + +## 项目信息 + +| 字段 | 内容 | +| --- | --- | +| 项目名称 | | +| 项目路径 | | +| 提取日期 | | +| 提取人 | | +| 目标输出 | rules / prompts / checklists / Skill | + +## 证据扫描记录 + +| 证据类型 | 文件或目录 | 是否存在 | 关键发现 | 备注 | +| --- | --- | --- | --- | --- | +| 显式规则 | AGENTS.md / CLAUDE.md / .trae/rules / .cursor/rules | | | | +| 项目说明 | README / CONTRIBUTING / docs | | | | +| 后端构建 | pom.xml / build.gradle / settings.gradle | | | | +| 前端构建 | package.json / lockfile / vite.config / tsconfig | | | | +| 运行配置 | .env / application.yml / Dockerfile / compose | | | | +| 质量工具 | ESLint / Prettier / Checkstyle / CI / test config | | | | +| 源码模式 | API / Controller / Service / Router / Store | | | | +| 权限与安全 | auth / permission / role / route guard / interceptor | | | | +| 数据与迁移 | schema / migration / mapper / repository | | | | + +## 候选约束 + +| 编号 | 分类 | 约束内容 | 级别 | 来源证据 | 影响范围 | 验收方式 | 迁移说明 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| C-001 | global / frontend / backend / security / testing / delivery | | 硬约束 / 观察性约束 / 待确认约束 | | | | | + +## 缺失证据 + +| 缺失项 | 影响 | 处理方式 | +| --- | --- | --- | +| | | 标记为待确认 / 询问团队 / 暂不生成规则 | + +## 待团队确认 + +| 问题 | 为什么需要确认 | 建议默认值 | 决策人 | +| --- | --- | --- | --- | +| 是否强制单测 | 仓库未发现 CI 或测试要求时无法证明 | 新增核心逻辑需补测试或说明豁免 | 技术负责人 | diff --git a/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/assets/项目约束生成.prompt.md b/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/assets/项目约束生成.prompt.md new file mode 100644 index 0000000..7c25980 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/assets/项目约束生成.prompt.md @@ -0,0 +1,61 @@ +# 项目约束生成 Prompt + +请为下面项目生成可复用的 AI 开发约束资产。 + +## 项目输入 + +- 项目路径： +- 输出路径： +- 目标项目类型： +- 是否需要生成 rules： +- 是否需要生成 checklist： +- 是否需要生成 Skill： + +## 执行要求 + +1. 先扫描项目中是否存在显式规则文件，例如 `AGENTS.md`、`CLAUDE.md`、`.trae/rules`、`.cursor/rules`、`README.md`、`CONTRIBUTING.md`。 +2. 如果不存在显式规则文件，不要停止，进入 code-only 模式。 +3. 从构建配置、运行配置、源码模式、测试配置、CI 配置中提取约束。 +4. 每条约束必须标注为： + - `硬约束`：由配置、CI、构建或显式规则直接证明。 + - `观察性约束`：由多个源码样例归纳，但没有显式规则。 + - `待确认约束`：项目无法证明，但交付前必须团队确认。 +5. 每条硬约束和观察性约束必须标注来源路径。 +6. 不要把通用最佳实践当成项目事实。 +7. 不要把某个项目的专用规则复制到另一个项目。 + +## 输出格式 + +请生成： + +```text +rules/global.md +rules/frontend.md +rules/backend.md +rules/security.md +rules/testing.md +rules/delivery.md +templates/项目约束提取表.template.md +checklists/项目约束验收清单.md +``` + +每条规则使用： + +```md +## 规则名称 + +- 级别： +- 适用场景： +- 必须： +- 禁止： +- 来源证据： +- 验收方式： +- 迁移说明： +``` + +最后输出： + +- 已读来源。 +- 缺失证据。 +- 待确认问题。 +- 不能迁移到其他项目的项目特有约束。 diff --git a/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/assets/项目约束验收清单.md b/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/assets/项目约束验收清单.md new file mode 100644 index 0000000..7c8f339 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/assets/项目约束验收清单.md @@ -0,0 +1,44 @@ +# 项目约束验收清单 + +## 基础完整性 + +- [ ] 已列出目标项目路径和输出路径。 +- [ ] 已说明是否发现显式规则文件。 +- [ ] 已记录缺失证据，没有因为缺失 README / CLAUDE.md / AGENTS.md 而停止。 +- [ ] 已区分 `硬约束`、`观察性约束`、`待确认约束`。 +- [ ] 每条硬约束都有明确来源路径。 +- [ ] 每条观察性约束至少有一个代表性源码样例。 +- [ ] 每条待确认约束都写明需要谁确认。 + +## 规则质量 + +- [ ] 规则包含适用场景。 +- [ ] 规则包含必须做什么。 +- [ ] 规则包含禁止做什么，或说明没有禁止项。 +- [ ] 规则包含验收方式。 +- [ ] 规则包含迁移说明，说明换项目时能否复用。 +- [ ] 规则没有把通用最佳实践冒充为项目事实。 +- [ ] 规则没有把某个单一代码样例冒充为全项目硬约束。 + +## 覆盖范围 + +- [ ] global 约束覆盖项目理解、证据引用、事实/推断区分。 +- [ ] frontend 约束覆盖包管理器、框架、路径别名、API 层、路由和状态管理。 +- [ ] backend 约束覆盖语言版本、框架、分层、响应结构、异常和数据访问。 +- [ ] security 约束覆盖认证、权限、敏感信息、数据范围和接口防护。 +- [ ] testing 约束覆盖已有测试工具、运行命令和缺失测试时的处理。 +- [ ] delivery 约束覆盖计划、Review、验收记录、发布或交付要求。 + +## 可复用性 + +- [ ] JeecgBoot 等项目特有规则没有写进通用规则。 +- [ ] 每条规则都标注了“可直接复用 / 需重新扫描 / 不可迁移”。 +- [ ] 换项目时必须重新扫描的内容已经列出。 +- [ ] 可以从本清单反推出生成步骤。 + +## 交付检查 + +- [ ] 生成文件中没有未完成占位符、示例假名或空标题。 +- [ ] Markdown 链接或路径经过抽样检查。 +- [ ] 规则文件标题不为空。 +- [ ] 交付说明列出已读来源、未读来源和仍需确认的问题。 diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/SKILL.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/SKILL.md new file mode 100644 index 0000000..916473a --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/SKILL.md @@ -0,0 +1,89 @@ +--- +name: review-business-delivery +description: Use when reviewing complex business delivery artifacts, AI-generated plans, PR diffs, or module designs for permission gaps, illegal state transitions, missing audit logs, weak exception handling, unclear dashboard metrics, missing tests, or incomplete acceptance evidence. +--- + +# Review Business Delivery + +## Core Principle + +Review behavior and risk before wording. Findings must be evidence-based, severity-ranked, and tied to a verification action. + +The review output should help the team decide whether to accept, conditionally accept, or reject the delivery. + +## Inputs + +Use any available inputs: + +- Requirement scope and non-goals. +- RBAC matrix and permission control plan. +- State transition table and illegal transition list. +- Audit SOP and exception-state list. +- Dashboard metric dictionary and API acceptance record. +- Code diff, API contract, test result, Browser verification record, or PR description. +- Project rules and constraints. + +If source evidence is missing, create an `证据缺口` section instead of guessing. + +## Review Flow + +1. Confirm delivery scope: what is being reviewed and what is outside scope. +2. Check source evidence: paths, rules, design tables, test results, and verification records. +3. Review permission risk: page/menu, button, backend API, and data scope. +4. Review state risk: legal transitions, illegal transitions, terminal states, duplicate submits, and role restrictions. +5. Review audit risk: action coverage, field completeness, masking, failure behavior, and consistency with business writes. +6. Review exception risk: empty, missing, invalid, forbidden, duplicate, concurrent, and downstream failure states. +7. Review dashboard risk: formula, filter, dimension, data source, permission, empty state, and manual calculation. +8. Review tests and acceptance: commands, roles, sample data, browser evidence, and unresolved risks. +9. Output findings sorted by severity. + +## Severity + +| Level | Meaning | +| --- | --- | +| P0 | Data loss, privilege bypass, irreversible wrong state, or release-blocking failure | +| P1 | Security, permission, audit, or state-machine defect with realistic business impact | +| P2 | Missing acceptance evidence, unclear metric, weak exception handling, or test gap | +| P3 | Maintainability, naming, documentation, or minor consistency issue | + +## Output Contract + +```md +## Review 结论 + +通过 / 有条件通过 / 不通过 + +## 问题清单 + +| 等级 | 模块 | 问题 | 证据 | 风险 | 修复建议 | 验收方式 | +| --- | --- | --- | --- | --- | --- | --- | + +## 证据缺口 + +| 缺口 | 影响 | 需要谁补充 | +| --- | --- | --- | + +## 待确认 + +| 问题 | 决策人 | 建议默认值 | +| --- | --- | --- | +``` + +Use the templates and checklists in `assets/` when writing files. + +## Quality Gates + +- Findings lead the response; summaries are secondary. +- Every P0/P1 finding cites a source path, table row, endpoint, role, state, metric, or verification record. +- Every finding has a concrete fix direction and acceptance method. +- Review does not accept frontend-only security controls. +- Missing tests or missing evidence are called out explicitly. +- Unclear business rules are marked `待确认`, not invented. + +## Common Mistakes + +- Do not write "整体不错" before listing risks. +- Do not merge all issues into one generic recommendation. +- Do not downgrade permission bypass, illegal state transitions, or missing audit for critical actions. +- Do not claim an issue is fixed without verification evidence. +- Do not review only code style when the requested delivery is business behavior. diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/agents/openai.yaml b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/agents/openai.yaml new file mode 100644 index 0000000..f2dc7c9 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "业务交付 Review" + short_description: "审查权限状态审计异常态看板测试与验收风险" + default_prompt: "Use $review-business-delivery to review complex business delivery artifacts for permission, state, audit, exception, and dashboard risks." + +policy: + allow_implicit_invocation: true diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/AIReview报告模板.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/AIReview报告模板.md new file mode 100644 index 0000000..0fe0982 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/AIReview报告模板.md @@ -0,0 +1,28 @@ +# AI Review 报告模板 + +## Review 输入 + +- PR diff： +- 需求说明： +- rules： +- 测试结果： +- 历史问题： + +## 结论 + +通过 / 有条件通过 / 不通过 + +## 问题清单 + +| 等级 | 文件/模块 | 问题 | 触发规则 | 风险 | 建议 | 测试/验收 | +| --- | --- | --- | --- | --- | --- | --- | + +## 不确定点 + +| 不确定点 | 需要谁确认 | 验证方式 | +| --- | --- | --- | + +## 是否建议合入 + +说明理由。 + diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/审计日志检查清单.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/审计日志检查清单.md new file mode 100644 index 0000000..0e271a4 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/审计日志检查清单.md @@ -0,0 +1,13 @@ +# 审计日志检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 创建记录 | 创建工单后能查询审计记录 | | +| 字段变更 | 编辑关键字段记录 oldValue/newValue | | +| 指派记录 | 指派负责人记录原负责人和新负责人 | | +| 状态记录 | 状态流转记录原状态和新状态 | | +| 操作人 | actor_id 和 actor_name 可追溯 | | +| 来源 | source 或 request_id 可追溯 | | +| 脱敏 | 敏感字段不明文进入审计 | | +| 失败处理 | 操作失败不写成功审计 | | + diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/异常态检查清单.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/异常态检查清单.md new file mode 100644 index 0000000..e1b6496 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/异常态检查清单.md @@ -0,0 +1,13 @@ +# 异常态检查清单 + +| 异常态 | 必须验证 | 结果 | +| --- | --- | --- | +| 空列表 | 页面显示空状态，不报错 | | +| 详情不存在 | 提示工单不存在，页面不崩溃 | | +| 权限不足 | 前端提示或隐藏，后端拒绝 | | +| 非法状态 | 返回非法流转，状态不变 | | +| 重复提交 | 只成功一次，只写一条有效审计 | | +| 参数缺失 | 返回参数错误，业务数据不变 | | +| 并发修改 | 拒绝覆盖或提示刷新 | | +| 看板无数据 | 图表显示空态，不显示假数据 | | + diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/权限上线前检查清单.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/权限上线前检查清单.md new file mode 100644 index 0000000..cacf893 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/权限上线前检查清单.md @@ -0,0 +1,12 @@ +# 权限上线前检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 菜单权限 | 工单菜单只对授权角色可见 | | +| 按钮权限 | 新增、编辑、删除、指派、状态按钮按权限显示 | | +| 接口权限 | 无权限账号直接请求敏感接口失败 | | +| 数据权限 | 普通用户只能看到授权范围内工单 | | +| 权限字符 | 前端按钮、菜单配置、后端接口命名一致 | | +| 审计 | 权限敏感操作成功后有审计记录 | | +| 反例验证 | 无权限账号不能绕过前端执行删除/指派 | | + diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/状态流转检查清单.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/状态流转检查清单.md new file mode 100644 index 0000000..2be5688 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/状态流转检查清单.md @@ -0,0 +1,12 @@ +# 状态流转检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 状态枚举 | 所有状态有统一枚举或字典 | | +| 合法流转 | 状态流转表中的合法路径可执行 | | +| 非法流转 | 非法路径被拒绝且状态不变 | | +| 角色限制 | 不同角色只能执行被授权动作 | | +| 前置条件 | 驳回原因、关闭条件、负责人等校验完整 | | +| 审计日志 | 每次成功流转写审计 | | +| 重复提交 | 重复点击不会产生重复有效流转 | | + diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/看板指标口径检查清单.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/看板指标口径检查清单.md new file mode 100644 index 0000000..b732c20 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/看板指标口径检查清单.md @@ -0,0 +1,13 @@ +# 看板指标口径检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 指标含义 | 每个指标有业务解释 | | +| 计算口径 | 每个指标有公式或筛选条件 | | +| 时间范围 | 明确按创建时间、关闭时间还是更新时间统计 | | +| 数据范围 | 不同角色的数据范围清楚 | | +| 空数据 | 空数据展示为 0 或空态，不误导 | | +| 分组一致性 | 分组总和能和总数对齐 | | +| 权限 | 无看板权限不能访问接口 | | +| 验收证据 | 至少有一组样例数据手工校验 | | + diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/看板接口验收清单.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/看板接口验收清单.md new file mode 100644 index 0000000..95e740a --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/看板接口验收清单.md @@ -0,0 +1,12 @@ +# 看板接口验收清单 + +| 验收项 | 请求条件 | 通过标准 | 结果 | +| --- | --- | --- | --- | +| 默认查询 | 管理员默认条件 | 返回完整指标 | | +| 时间过滤 | 指定 start/end | 只统计时间范围内数据 | | +| 类型过滤 | 指定工单类型 | 只统计对应类型 | | +| 空数据 | 无匹配条件 | 返回 0 或空集合 | | +| 无权限 | 未授权账号 | 返回 403 或业务拒绝 | | +| 数据范围 | 普通角色 | 只返回授权范围 | | +| 指标一致性 | 固定样例数据 | 与手工计算一致 | | + diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/阶段Review.prompt.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/阶段Review.prompt.md new file mode 100644 index 0000000..99c3843 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/阶段Review.prompt.md @@ -0,0 +1,30 @@ +# 阶段 Review Prompt + +```text +请对 JeecgBoot 工单模块阶段交付物做 Review。 + +输入材料： +- RBAC 权限矩阵 +- 权限控制方案 +- 状态流转表 +- 非法流转清单 +- 审计日志 SOP +- 异常态清单 +- 看板指标字典 +- 看板接口验收记录 +- 测试结果或验证记录 + +输出表格： +等级 | 模块 | 问题 | 触发规则 | 风险 | 修复建议 | 验收 + +要求： +1. 问题按 P0/P1/P2/P3 分级。 +2. 每个问题必须说明触发了哪条规则。 +3. 每条建议必须有验收方式。 +4. 输出不确定点和需要人工确认的内容。 + +约束： +- 不要只说整体不错。 +- 不要直接改代码。 +``` + diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/阶段Review报告.template.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/阶段Review报告.template.md new file mode 100644 index 0000000..eba0738 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/阶段Review报告.template.md @@ -0,0 +1,28 @@ +# 阶段 Review 报告 + +## Review 输入 + +- RBAC 权限矩阵： +- 权限控制方案： +- 状态流转表： +- 非法流转清单： +- 审计日志 SOP： +- 异常态清单： +- 看板指标字典： +- 看板接口验收记录： + +## 问题清单 + +| 等级 | 模块 | 问题 | 触发规则 | 风险 | 修复建议 | 验收 | +| --- | --- | --- | --- | --- | --- | --- | +| P1 | 权限 | 删除接口只隐藏按钮，后端缺少权限校验 | 前端按钮不是安全边界 | 可绕过前端删除工单 | 后端补权限校验 | 无权限账号请求返回 403 | + +## 不确定点 + +| 不确定点 | 影响 | 需要谁确认 | +| --- | --- | --- | + +## 结论 + +通过 / 有条件通过 / 不通过 + diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/验收清单.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/验收清单.md new file mode 100644 index 0000000..230cd33 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/验收清单.md @@ -0,0 +1,71 @@ +# 验收清单 + +本清单用于判断学员是否真正掌握 JeecgBoot 工单案例，而不是只复制了 TRAE 输出。建议讲师在小组展示时逐项打分。 + +## 项目理解 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 能说明 JeecgBoot 前后端目录 | 至少指出 `jeecg-boot`、`jeecgboot-vue3`、`docs/project-knowledge` 的用途 | | +| 能定位后端入口 | 能指出 `JeecgSystemApplication.java` 和后端启动模块 | | +| 能定位前端入口 | 能指出 `src/main.ts`、路由、Pinia 和 API 请求层 | | +| 能区分事实和推断 | 对没有源码依据的业务规则标注为推断或待确认 | | +| 能记录不确定点 | 不确定内容没有被包装成确定事实 | | + +## 需求与接口 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 用户故事完整 | 覆盖管理员、负责人、研发、测试、只读用户 | | +| 非目标范围明确 | 明确课堂不做完整编码、生产部署、真实数据迁移 | | +| 接口契约完整 | 覆盖列表、详情、新增、编辑、指派、状态、审计、看板 | | +| 失败场景明确 | 每个关键接口至少有权限、参数、状态或数据不存在失败场景 | | +| 验收方式明确 | 每个关键需求都有可执行检查方法 | | + +## 权限与状态 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 权限矩阵完整 | 覆盖页面级、按钮级、接口级和数据范围 | | +| 权限字符合理 | 命名统一，并标注为建议而非源码事实 | | +| 后端权限未缺失 | 没有用前端按钮隐藏替代后端接口控制 | | +| 状态流转表完整 | 覆盖新建、处理中、待验证、已关闭、已驳回 | | +| 非法流转明确 | 至少列出 5 条非法流转和拒绝原因 | | + +## 审计、异常态与看板 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 审计操作覆盖关键动作 | 创建、编辑、指派、状态流转、关闭、评论至少覆盖 5 类 | | +| 审计字段可追溯 | 包含 actor、action、targetId、oldValue、newValue、source | | +| 敏感信息处理 | oldValue/newValue 有脱敏说明 | | +| 异常态可测试 | 权限不足、重复提交、非法状态、数据不存在、并发修改均覆盖 | | +| 看板指标可计算 | 每个指标有口径、维度、过滤条件和数据来源建议 | | + +## Review 与交付 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| Review 有证据 | 问题能回到路径、表格或业务规则 | | +| 风险按严重程度排序 | 高风险问题优先展示 | | +| 建议可行动 | 每条建议有修复方向和验收方式 | | +| 交付物齐全 | [worksheets.md](./worksheets.md) 中最终交付记录完整 | | +| 能沉淀资产 | 能说明哪些内容进入 [assets-index.md](./assets-index.md) 的资产库 | | + +## 评分建议 + +| 等级 | 分数 | 描述 | +| --- | ---: | --- | +| A | 90-100 | 依据充分，设计完整，风险清楚，验收可执行 | +| B | 75-89 | 主链路完整，少量不确定点或验收细节不足 | +| C | 60-74 | 有基本产出，但权限、状态、审计或异常态明显薄弱 | +| D | 0-59 | 泛泛总结项目，缺少源码依据或无法验收 | + +## 讲师判定原则 + +- 优先看证据，不优先看文字是否漂亮。 +- 优先看权限、状态、审计、异常态，不只看 CRUD。 +- 优先看不确定点是否被诚实标出。 +- 优先看能否复用到团队资产库。 +- 对没有依据的自信结论扣分。 + diff --git a/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/SKILL.md b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/SKILL.md new file mode 100644 index 0000000..67b0c6c --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/SKILL.md @@ -0,0 +1,94 @@ +--- +name: track-review-fix-loop +description: Use when turning review findings into a fix-tracking record, deciding whether findings are valid, mapping fixes to files, verifying results, documenting unresolved items, or deciding which issues should become reusable rules, checklists, prompts, examples, or team assets. +--- + +# Track Review Fix Loop + +## Core Principle + +A review issue is not closed by saying "fixed". It closes only when the team records validity, changed artifacts, verification evidence, unresolved risk, and whether the lesson should become a reusable asset. + +## Inputs + +- Review report with numbered findings. +- Requirement or acceptance criteria. +- Code diff, design document, generated tables, or changed files. +- Test results, Browser verification evidence, API response samples, or manual validation notes. +- Existing team rules, checklists, examples, and asset index. + +If validation evidence is missing, mark the item as `未闭环`. + +## Status Model + +Use one of these statuses for each review item: + +| Status | Meaning | +| --- | --- | +| `成立-已修复` | Finding is valid, changed artifacts are listed, and verification evidence exists | +| `成立-暂不修复` | Finding is valid but deferred with reason, owner, and follow-up date | +| `不成立` | Finding is invalid with evidence | +| `需确认` | Finding depends on business or technical decision not available in current evidence | +| `未闭环` | Fix is claimed but evidence is missing | + +## Workflow + +1. Normalize review findings: ensure each issue has an ID, severity, module, risk, and suggested verification. +2. Decide validity: `成立`, `不成立`, or `需确认`; cite evidence. +3. Map valid fixes to changed files, tables, prompts, rules, or templates. +4. Verify each fix using commands, API checks, browser steps, role-based tests, or manual calculation. +5. Identify regressions: related permissions, states, audit actions, dashboard metrics, and exception states to re-check. +6. Decide asset sedimentation: rule, checklist, prompt, Command, Skill, example, or no asset. +7. Output unresolved items with owner and next step. + +## Output Contract + +```md +## 修复闭环结论 + +完成 / 部分完成 / 未完成 + +## 修复记录 + +| Review 编号 | 等级 | 问题 | 状态 | 修改文件/产物 | 验证证据 | 剩余风险 | 资产沉淀 | +| --- | --- | --- | --- | --- | --- | --- | --- | + +## 未闭环事项 + +| 编号 | 原因 | 负责人 | 下一步 | 截止时间 | +| --- | --- | --- | --- | --- | + +## 资产更新建议 + +| 来源问题 | 资产类型 | 建议文件 | 更新内容 | +| --- | --- | --- | --- | +``` + +Use `assets/修复记录.template.md` and `assets/Review修复闭环检查清单.md` when creating files. + +## Asset Decision Guide + +| If the issue is... | Asset | +| --- | --- | +| Repeated project convention violation | rule | +| Repeated review checklist miss | checklist | +| Reusable question or generation pattern | prompt | +| One-step repeatable agent action | command | +| Multi-step judgment workflow | skill | +| Good or bad teaching sample | example | + +## Quality Gates + +- Every fixed issue has verification evidence. +- Every deferred issue has owner and next step. +- Every invalid issue has source evidence, not opinion. +- P0/P1 issues cannot be marked complete without direct verification. +- Asset updates are specific file suggestions, not vague "沉淀经验". + +## Common Mistakes + +- Do not close issues with "已修复" without evidence. +- Do not erase invalid findings; keep why they are invalid. +- Do not mark business decisions as technical fixes. +- Do not create a Skill for a one-off checklist item. +- Do not ignore regressions around permissions, state transitions, audit logs, and dashboard metrics. diff --git a/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/agents/openai.yaml b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/agents/openai.yaml new file mode 100644 index 0000000..500b19a --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Review 修复闭环" + short_description: "跟踪Review问题成立判断修复验证未闭环与资产沉淀" + default_prompt: "Use $track-review-fix-loop to turn review findings into verified fixes, unresolved decisions, and reusable team assets." + +policy: + allow_implicit_invocation: true diff --git a/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/Review修复闭环检查清单.md b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/Review修复闭环检查清单.md new file mode 100644 index 0000000..39df455 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/Review修复闭环检查清单.md @@ -0,0 +1,12 @@ +# Review 修复闭环检查清单 + +| 检查项 | 通过标准 | 结果 | +| --- | --- | --- | +| 问题编号 | 每个 Review 问题有编号 | | +| 成立判断 | 每个问题说明是否成立 | | +| 修改说明 | 成立问题说明修改文件和内容 | | +| 验证结果 | 每个修复有验证证据 | | +| 未修复说明 | 暂不修复的问题有原因和后续计划 | | +| 资产沉淀 | 有复用价值的问题已进入检查清单或反例库 | | +| 回归检查 | 修复后重新检查相关权限/状态/审计/看板 | | + diff --git a/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/修复记录.template.md b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/修复记录.template.md new file mode 100644 index 0000000..37732cc --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/修复记录.template.md @@ -0,0 +1,8 @@ +# Review 修复记录 + +| Review 编号 | 问题 | 是否成立 | 修改文件 | 修改说明 | 验证结果 | 资产沉淀 | +| --- | --- | --- | --- | --- | --- | --- | +| R01 | 删除接口缺少后端权限校验 | 是 | WorkOrderController | 增加权限校验 | 无权限请求被拒绝 | 权限检查清单 | +| R02 | closed 可重新处理 | 是 | WorkOrderService | 补非法流转校验 | closed -> processing 失败 | 状态流转检查清单 | +| R03 | 看板关闭周期口径不清 | 是 | 指标字典/看板接口 | 明确 create_time 到 close_time | 指标说明已更新 | 看板指标口径清单 | + diff --git a/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/修复记录生成.prompt.md b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/修复记录生成.prompt.md new file mode 100644 index 0000000..24fcfe7 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/修复记录生成.prompt.md @@ -0,0 +1,24 @@ +# 修复记录生成 Prompt + +```text +请根据阶段 Review 报告生成修复记录。 + +输入材料： +- Review 报告：<粘贴> +- 已完成修改说明：<粘贴> +- 验证结果：<粘贴> + +输出表格： +Review 编号 | 问题 | 是否成立 | 修改文件 | 修改说明 | 验证结果 | 资产沉淀 + +要求： +1. 如果问题不成立，说明理由和依据。 +2. 如果问题成立，说明修改了哪些文件。 +3. 每条修复必须有验证结果。 +4. 判断是否需要沉淀为资产，例如权限检查清单、状态流转检查清单、审计日志检查清单。 + +约束： +- 不要模糊写“已修复”。 +- 没有验证结果的修复不能算完成。 +``` + diff --git a/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/审计日志缺失反例.md b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/审计日志缺失反例.md new file mode 100644 index 0000000..8dba8d6 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/审计日志缺失反例.md @@ -0,0 +1,32 @@ +# 审计日志缺失反例 + +## 场景 + +工单指派负责人成功，但没有记录审计日志。 + +## 问题表现 + +| 操作 | 结果 | +| --- | --- | +| 张三将工单指派给李四 | 工单负责人变更成功 | +| 查询审计日志 | 没有负责人变更记录 | + +## 风险 + +无法追溯负责人变化，出现延误或争议时无法定位责任。 + +## 修复要求 + +1. 指派成功后写审计日志。 +2. 记录原负责人、新负责人、操作人、时间、来源。 +3. 指派失败不写成功审计。 +4. 多步写入需要事务一致性。 + +## 验收 + +| 操作 | 预期 | +| --- | --- | +| 指派成功 | 审计列表出现 ASSIGN 记录 | +| 指派失败 | 不出现成功审计 | +| 查询详情 | 审计记录可在工单详情查看 | + diff --git a/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/权限遗漏反例.md b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/权限遗漏反例.md new file mode 100644 index 0000000..0e3cfb7 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/权限遗漏反例.md @@ -0,0 +1,33 @@ +# 权限遗漏反例 + +## 场景 + +工单删除按钮在前端按权限隐藏，但后端删除接口没有权限校验。 + +## 问题代码表现 + +| 层级 | 表现 | +| --- | --- | +| 前端 | 普通研发账号看不到删除按钮 | +| 后端 | 直接请求 `/workOrder/delete` 仍可删除 | +| 审计 | 删除记录可能缺失 | + +## 风险 + +攻击者或误操作用户可以绕过前端直接调用接口删除工单。 + +## 修复要求 + +1. 后端删除接口增加权限校验。 +2. 删除前校验数据范围。 +3. 删除成功写审计日志。 +4. 无权限账号直接请求接口返回 403 或业务拒绝。 + +## 验收 + +| 账号 | 操作 | 预期 | +| --- | --- | --- | +| 管理员 | 删除允许删除的工单 | 成功并写审计 | +| 普通研发 | 直接请求删除接口 | 失败 | +| 只读用户 | 前端访问删除按钮 | 不可见 | + diff --git a/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/看板指标口径不清反例.md b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/看板指标口径不清反例.md new file mode 100644 index 0000000..be5ee62 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/看板指标口径不清反例.md @@ -0,0 +1,31 @@ +# 看板指标口径不清反例 + +## 场景 + +看板展示“平均关闭周期”，但没有说明从哪个时间到哪个时间。 + +## 问题表现 + +| 指标 | 当前说明 | +| --- | --- | +| 平均关闭周期 | 最近工单平均处理时间 | + +## 风险 + +不同人理解不同：可能是创建到关闭，也可能是开始处理到关闭，导致管理判断失真。 + +## 修复要求 + +1. 明确定义为 `close_time - create_time` 或其他确定口径。 +2. 明确是否排除未关闭工单。 +3. 明确时间范围过滤字段。 +4. 用样例数据手工校验。 + +## 验收 + +| 样例 | 预期 | +| --- | --- | +| 工单 A 创建 1 日、关闭 3 日 | 周期 2 天 | +| 未关闭工单 | 不计入平均关闭周期 | +| 过滤 7 月 | 只统计 7 月范围内符合口径的数据 | + diff --git a/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/非法状态流转反例.md b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/非法状态流转反例.md new file mode 100644 index 0000000..e675156 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/非法状态流转反例.md @@ -0,0 +1,31 @@ +# 非法状态流转反例 + +## 场景 + +已关闭工单可以直接被改回处理中。 + +## 问题表现 + +| 当前状态 | 动作 | 结果 | +| --- | --- | --- | +| 已关闭 | 开始处理 | 状态变成处理中 | + +## 风险 + +已关闭工单被重新打开但没有重开原因、没有审计、没有负责人确认，导致统计和责任链失真。 + +## 修复要求 + +1. Service 层集中校验状态流转。 +2. 已关闭工单只能通过“重新打开”动作变为新建。 +3. 重新打开必须填写原因。 +4. 所有成功流转写审计日志。 + +## 验收 + +| 操作 | 预期 | +| --- | --- | +| closed -> processing | 失败，状态不变 | +| closed -> reopen -> new | 成功，必须有原因 | +| 重开成功 | 审计记录 oldValue=closed, newValue=new | + diff --git a/deliverables/客户AI工程Skill交付包/安装说明.md b/deliverables/客户AI工程Skill交付包/安装说明.md new file mode 100644 index 0000000..5a50df8 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/安装说明.md @@ -0,0 +1,63 @@ +# 安装说明 + +## 方式一：安装到 Codex Skills 目录 + +把 `skills/` 下的 4 个 Skill 文件夹复制到本机 Skills 目录： + +```text +~/.codex/skills/ +``` + +安装后目录应类似： + +```text +~/.codex/skills/ +├── generate-project-constraints/ +├── design-complex-business-module/ +├── review-business-delivery/ +└── track-review-fix-loop/ +``` + +每个 Skill 文件夹必须保留完整结构： + +```text +skill-name/ +├── SKILL.md +├── agents/ +│ └── openai.yaml +└── assets/ +``` + +## 调用方式 + +在支持 Skill 的 AI 编程工具中，可以这样调用： + +```text +Use $generate-project-constraints 为当前项目生成 AI 开发约束。 +Use $design-complex-business-module 设计这个业务模块的权限、状态、审计、异常态和看板。 +Use $review-business-delivery Review 这批阶段交付物。 +Use $track-review-fix-loop 根据 Review 报告生成修复闭环记录。 +``` + +## 方式二：作为团队资产库使用 + +如果当前 AI 工具暂不支持原生 Skill 机制，可以把本包作为团队资产库使用： + +```text +ai-engineering-assets/ +├── skills/ +├── rules/ +├── prompts/ +├── templates/ +├── checklists/ +└── examples/ +``` + +此时 `SKILL.md` 作为标准工作流说明，`assets/` 作为可复制模板、Prompt、检查清单和反例库。 + +## 维护建议 + +- 每次项目规则变化后，重新运行 `generate-project-constraints`。 +- 每次复杂业务模块交付后，把高频问题沉淀到 `review-business-delivery` 或 `track-review-fix-loop` 的 assets。 +- 不要把某个项目的专用规则直接复制成通用规则。 +- 对无法从源码或配置证明的内容，统一标记为待确认。 diff --git a/docs/superpowers/plans/2026-07-01-jeecgboot-work-order-case-pack.md b/docs/superpowers/plans/2026-07-01-jeecgboot-work-order-case-pack.md new file mode 100644 index 0000000..dff13f7 --- /dev/null +++ b/docs/superpowers/plans/2026-07-01-jeecgboot-work-order-case-pack.md @@ -0,0 +1,423 @@ +# JeecgBoot Work Order Case Pack Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Create an independent JeecgBoot work-order training case pack under `cases/jeecgboot-work-order/`. + +**Architecture:** This is a documentation-only training asset. The case pack is split into an entry README, role-specific guides, a source map, prompt templates, worksheets, an acceptance checklist, and an asset index. It references the local JeecgBoot project and existing TRAE course materials without changing either. + +**Tech Stack:** Markdown, local JeecgBoot source paths, existing TRAE course docs. + +--- + +## File Structure + +- Create: `cases/jeecgboot-work-order/README.md` + - Case pack entry, learning goals, audience, timing, usage order, required project context, final deliverables. +- Create: `cases/jeecgboot-work-order/instructor-guide.md` + - Teaching agenda for 2-hour, half-day, and full-day variants, with facilitation notes and common failure modes. +- Create: `cases/jeecgboot-work-order/learner-guide.md` + - Student-facing lab path from project reading to final review. +- Create: `cases/jeecgboot-work-order/source-map.md` + - Source-grounded JeecgBoot path map for backend, frontend, permissions, routes, config, database, and project knowledge docs. +- Create: `cases/jeecgboot-work-order/prompts.md` + - Copy-ready TRAE prompts with inputs, constraints, and output formats. +- Create: `cases/jeecgboot-work-order/worksheets.md` + - Fillable classroom templates for requirements, source evidence, APIs, RBAC, state transitions, audit, dashboard, and review. +- Create: `cases/jeecgboot-work-order/acceptance-checklist.md` + - Checklist for evaluating learner output. +- Create: `cases/jeecgboot-work-order/assets-index.md` + - Post-class asset library mapping for rules, prompts, commands, skills, SOPs, and cases. + +## Task 1: Create Case Pack Directory + +**Files:** +- Create: `cases/jeecgboot-work-order/` + +- [ ] **Step 1: Create the directory** + +Run: + +```bash +mkdir -p cases/jeecgboot-work-order +``` + +Expected: directory exists. + +- [ ] **Step 2: Verify the directory** + +Run: + +```bash +find cases -maxdepth 2 -type d | sort +``` + +Expected includes: + +```text +cases +cases/jeecgboot-work-order +``` + +## Task 2: Write Entry README + +**Files:** +- Create: `cases/jeecgboot-work-order/README.md` + +- [ ] **Step 1: Write README** + +Include these sections: + +```markdown +# JeecgBoot 工单案例包 + +## 适用场景 + +## 学习目标 + +## 建议使用顺序 + +## 课前准备 + +## 案例任务主线 + +## 最终交付物 + +## 关键约束 + +## 文件索引 +``` + +- [ ] **Step 2: Check README links** + +Run: + +```bash +rg -n "\\[[^\\]]+\\]\\(([^)]+)\\)" cases/jeecgboot-work-order/README.md +``` + +Expected: all relative links point to files created in this plan. + +## Task 3: Write Instructor And Learner Guides + +**Files:** +- Create: `cases/jeecgboot-work-order/instructor-guide.md` +- Create: `cases/jeecgboot-work-order/learner-guide.md` + +- [ ] **Step 1: Write instructor guide** + +Include: + +```markdown +# 讲师手册 + +## 授课定位 + +## 2 小时版本 + +## 半天版本 + +## 1 天版本 + +## 演示路径 + +## 讲师提醒 + +## 常见翻车点 + +## 收束话术 +``` + +- [ ] **Step 2: Write learner guide** + +Include: + +```markdown +# 学员实操手册 + +## 实操目标 + +## 第 1 步：建立项目地图 + +## 第 2 步：整理工单需求 + +## 第 3 步：定位源码依据 + +## 第 4 步：设计接口契约 + +## 第 5 步：设计权限和状态流转 + +## 第 6 步：补齐审计和异常态 + +## 第 7 步：设计看板指标 + +## 第 8 步：做 Review 和交付验收 +``` + +- [ ] **Step 3: Verify guides reference worksheets and prompts** + +Run: + +```bash +rg -n "prompts.md|worksheets.md|source-map.md|acceptance-checklist.md" cases/jeecgboot-work-order/instructor-guide.md cases/jeecgboot-work-order/learner-guide.md +``` + +Expected: both guides reference supporting files. + +## Task 4: Write Source Map + +**Files:** +- Create: `cases/jeecgboot-work-order/source-map.md` + +- [ ] **Step 1: Write source map** + +Include source-grounded tables for: + +```markdown +# 源码定位图 + +## 项目知识库入口 + +## 后端入口与模块 + +## 前端入口与模块 + +## 权限与路由 + +## API 与请求层 + +## 配置与运行 + +## 数据库与迁移 + +## 课堂使用方式 +``` + +- [ ] **Step 2: Verify referenced local paths exist** + +Run: + +```bash +rg -o "`\\.\\./JeecgBoot/[^`]+`" cases/jeecgboot-work-order/source-map.md +``` + +Then manually confirm representative paths exist with `test -e` or `ls`. + +## Task 5: Write Prompt Library + +**Files:** +- Create: `cases/jeecgboot-work-order/prompts.md` + +- [ ] **Step 1: Write prompt templates** + +Include prompts for: + +```markdown +# Prompt 模板库 + +## 使用规则 + +## 项目理解 Prompt + +## 源码定位 Prompt + +## 需求拆解 Prompt + +## 接口契约 Prompt + +## RBAC 权限矩阵 Prompt + +## 权限落地检查 Prompt + +## 状态机设计 Prompt + +## 审计日志 Prompt + +## 异常态 Prompt + +## 看板指标 Prompt + +## 修改计划 Prompt + +## Review Prompt +``` + +Each prompt must require TRAE to output: + +```text +事实依据 +推断 +建议 +不确定点 +下一步验证 +``` + +- [ ] **Step 2: Verify prompt safety wording** + +Run: + +```bash +rg -n "先找依据|事实|推断|建议|不确定点|不要直接改代码|验收" cases/jeecgboot-work-order/prompts.md +``` + +Expected: all key safety constraints are present. + +## Task 6: Write Worksheets + +**Files:** +- Create: `cases/jeecgboot-work-order/worksheets.md` + +- [ ] **Step 1: Write worksheets** + +Include fillable tables: + +```markdown +# 课堂工作表 + +## 上下文包 + +## 源码依据记录表 + +## 需求拆解表 + +## 接口契约表 + +## RBAC 权限矩阵 + +## 状态流转表 + +## 审计日志设计表 + +## 异常态清单 + +## 看板指标表 + +## Review 记录表 + +## 最终交付记录 +``` + +- [ ] **Step 2: Verify tables are fillable** + +Run: + +```bash +rg -n "\\|.*\\|.*\\|" cases/jeecgboot-work-order/worksheets.md +``` + +Expected: each worksheet section contains a Markdown table. + +## Task 7: Write Acceptance Checklist And Asset Index + +**Files:** +- Create: `cases/jeecgboot-work-order/acceptance-checklist.md` +- Create: `cases/jeecgboot-work-order/assets-index.md` + +- [ ] **Step 1: Write acceptance checklist** + +Include: + +```markdown +# 验收清单 + +## 项目理解 + +## 需求与接口 + +## 权限与状态 + +## 审计、异常态与看板 + +## Review 与交付 + +## 评分建议 +``` + +- [ ] **Step 2: Write asset index** + +Include: + +```markdown +# 资产归档索引 + +## 可沉淀资产 + +## 目录建议 + +## 规则资产 + +## Prompt 资产 + +## Command 与 Skill 资产 + +## 案例库资产 + +## 维护机制 +``` + +- [ ] **Step 3: Verify checklist and assets are cross-linked** + +Run: + +```bash +rg -n "README.md|prompts.md|worksheets.md|acceptance-checklist.md|assets-index.md" cases/jeecgboot-work-order/acceptance-checklist.md cases/jeecgboot-work-order/assets-index.md +``` + +Expected: files reference related materials. + +## Task 8: Final Verification + +**Files:** +- Inspect all files under `cases/jeecgboot-work-order/` + +- [ ] **Step 1: List generated files** + +Run: + +```bash +find cases/jeecgboot-work-order -type f | sort +``` + +Expected exactly: + +```text +cases/jeecgboot-work-order/README.md +cases/jeecgboot-work-order/acceptance-checklist.md +cases/jeecgboot-work-order/assets-index.md +cases/jeecgboot-work-order/instructor-guide.md +cases/jeecgboot-work-order/learner-guide.md +cases/jeecgboot-work-order/prompts.md +cases/jeecgboot-work-order/source-map.md +cases/jeecgboot-work-order/worksheets.md +``` + +- [ ] **Step 2: Scan for placeholders** + +Run: + +```bash +rg -n "TODO|TBD|待补|your/path|foo|bar|unknown" cases/jeecgboot-work-order +``` + +Expected: no output. + +- [ ] **Step 3: Check source path references** + +Run: + +```bash +rg -n "../../../JeecgBoot|jeecg-boot|jeecgboot-vue3|docs/project-knowledge" cases/jeecgboot-work-order +``` + +Expected: source references exist in `source-map.md`, `prompts.md`, and guides. + +- [ ] **Step 4: Check Git status** + +Run: + +```bash +git status --short +``` + +Expected: only new `docs/` and `cases/` from this work plus pre-existing unrelated changes. + diff --git a/docs/superpowers/specs/2026-07-01-jeecgboot-work-order-case-pack-design.md b/docs/superpowers/specs/2026-07-01-jeecgboot-work-order-case-pack-design.md new file mode 100644 index 0000000..9416157 --- /dev/null +++ b/docs/superpowers/specs/2026-07-01-jeecgboot-work-order-case-pack-design.md @@ -0,0 +1,142 @@ +# JeecgBoot 工单案例包设计 + +日期：2026-07-01 + +## 目标 + +在现有 TRAE 培训课件之外，新增一个可独立分发、可插入第 3/4 天课程的 `JeecgBoot 工单案例包`。案例包用于训练学员把 TRAE 用在真实 JeecgBoot 类后台项目中，完成从项目理解、需求拆解、权限设计、状态流转、审计、异常态、看板到 Review 的完整工程链路。 + +## 范围 + +案例包存放在： + +```text +cases/jeecgboot-work-order/ +``` + +新增文件： + +```text +cases/jeecgboot-work-order/ +├── README.md +├── instructor-guide.md +├── learner-guide.md +├── source-map.md +├── prompts.md +├── worksheets.md +├── acceptance-checklist.md +└── assets-index.md +``` + +不修改现有 Slidev 主课件，不修改 `JeecgBoot` 项目源码，不生成工单模块代码。案例包是培训资料资产，不是代码实现任务。 + +## 已观察来源 + +- `TRAE 培训大纲V1.0.md`：定义 6 天课程主线和 JeecgBoot 工单训练主题。 +- `第 3 天：TRAE 能力体系与 Agent 工作方式.md`：后半段已承接 JeecgBoot 工单、Plan、Review、Browser 验证。 +- `第 4 天：JeecgBoot 工单复杂业务开发：权限、审计、异常态与看板.md`：已有完整复杂业务讲法和交付物。 +- `slidev/slides.md`：当前 Slidev 主线已包含第 1-4 天，不纳入本次修改范围。 +- `../../../JeecgBoot/docs/project-knowledge/README.md`：JeecgBoot 项目知识库入口。 +- `../../../JeecgBoot/jeecg-boot/CLAUDE.md`：后端项目约束、模块结构、修改痕迹规则。 +- `../../../JeecgBoot/jeecgboot-vue3/CLAUDE.md`：前端项目约束、路由、Pinia、API 层、构建命令。 + +## 内容设计 + +### README.md + +案例包入口。说明适用对象、建议课时、学习目标、使用顺序、项目准备、交付物清单。 + +核心作用：让讲师和学员知道这个包怎么用。 + +### instructor-guide.md + +讲师手册。包含 2 小时、半天、1 天三种授课节奏，讲解重点、提问方式、演示路径、常见翻车点和收束话术。 + +核心作用：让讲师不用重新组织课堂流程。 + +### learner-guide.md + +学员手册。按步骤指导学员使用 TRAE 完成案例任务：读项目、定位源码、拆需求、设计权限、设计状态流转、补审计、列异常态、做看板、做 Review。 + +核心作用：让学员可以独立完成实操。 + +### source-map.md + +源码定位图。按主题列出 JeecgBoot 前端、后端、权限、路由、配置、数据库和知识库入口路径。 + +核心作用：避免学员和 TRAE 泛泛总结项目，强制回到实际路径。 + +### prompts.md + +Prompt 模板库。覆盖： + +- 项目理解 +- 源码定位 +- 需求拆解 +- 接口契约 +- RBAC 权限矩阵 +- 权限落地检查 +- 状态机设计 +- 审计日志设计 +- 异常态清单 +- 看板指标 +- 代码修改计划 +- Review 与验收 + +核心作用：提供课堂可直接复制的 TRAE 提问模板。 + +### worksheets.md + +课堂填写表。包含需求拆解表、上下文包、源码依据记录表、接口契约表、权限矩阵、状态流转表、异常态清单、看板指标表、Review 记录表。 + +核心作用：让课堂产出标准化。 + +### acceptance-checklist.md + +验收清单。按理解、设计、实现计划、验证、资产沉淀五类检查学员产出。 + +核心作用：判断学员是否真的掌握，而不是只让 AI 生成了一段内容。 + +### assets-index.md + +资产归档建议。说明哪些内容适合沉淀为团队规则、Prompt、Command、Skill、案例库、SOP。 + +核心作用：把一次课堂实操转成可复用企业资产。 + +## 关键约束 + +1. 所有非显而易见的项目事实必须引用实际路径。 +2. 工单模块是教学案例，不假设当前 JeecgBoot 源码中已经存在完整工单模块。 +3. Prompt 必须要求 TRAE 区分事实、推断和建议。 +4. Prompt 必须要求 TRAE 先找依据，再给结论，不允许直接改代码。 +5. 涉及权限、状态流转、审计、删除、数据看板的任务必须先产出计划和验收点。 +6. 后端二开说明必须提醒遵守 `jeecg-boot/CLAUDE.md` 中的 `update-begin` / `update-end` 修改痕迹规则。 +7. 前端说明必须提醒遵守 `jeecgboot-vue3/CLAUDE.md` 中的 `/@/` alias、Pinia、动态路由和 `defHttp` API 层约定。 +8. 不新增第 5/6 天课件，不改 `slidev/slides.md`。 + +## 产出质量标准 + +- 新人能根据 `README.md` 判断使用顺序。 +- 讲师能根据 `instructor-guide.md` 开始授课。 +- 学员能根据 `learner-guide.md` 完成一轮工单案例设计。 +- `source-map.md` 能把学员从“泛泛问项目”引导到具体源码路径。 +- `prompts.md` 的模板能直接复制使用，并包含输入、约束、输出格式和验收要求。 +- `worksheets.md` 的表格能承接课堂产出。 +- `acceptance-checklist.md` 能用于小组展示验收。 +- `assets-index.md` 能指导课后资产沉淀。 + +## 非目标 + +- 不实现真实工单模块。 +- 不安装依赖、不启动 JeecgBoot。 +- 不生成数据库迁移 SQL。 +- 不改现有课件结构。 +- 不替换第 4 天逐字稿。 +- 不把案例包写入 `JeecgBoot/docs/project-knowledge/`，避免培训资料和项目知识库混合。 + +## 未知与风险 + +- 当前 `TRAE课件` 工作区已有未提交改动，本次只新增案例包和设计说明，不处理既有改动。 +- JeecgBoot 目录不是 Git 仓库，案例包中的源码路径按当前本地目录快照编写。 +- 若后续要让学员真正生成并运行工单模块，还需要另行准备数据库、账号、菜单权限和初始数据脚本。 + diff --git a/slidev/pages/day3/m5-browser-docs-index.md b/slidev/pages/day3/m5-browser-docs-index.md index 57616c8..578b058 100644 --- a/slidev/pages/day3/m5-browser-docs-index.md +++ b/slidev/pages/day3/m5-browser-docs-index.md @@ -180,6 +180,29 @@ Markdown 很适合 AI 读写。 --- +# 落到 JeecgBoot 工单：链路与记录 + +
+ +| 工单功能 | 需要让 AI 找到的链路 | 需要沉淀的记录 | +|---|---|---| +| 工单列表 | 菜单、路由、页面、查询 API、分页参数 | 查询与分页截图 | +| 工单详情 | 详情页面、详情接口、字段来源、附件/评论区域 | 字段核对记录 | +| 指派负责人 | 前端按钮、后端接口、Service 校验、审计记录 | 指派结果与日志 | +| 状态流转 | 状态字典、按钮显隐、流转接口、非法状态处理 | 合法/非法流转记录 | +| 权限态 | 菜单按钮权限、接口权限、角色差异 | 无权限账号验证 | +| 看板指标 | 统计接口、查询口径、权限过滤、空态展示 | 指标口径与响应 | + +
+ + + +--- + # 课堂产出：前端验证清单
@@ -190,10 +213,12 @@ Markdown 很适合 AI 读写。 | 主流程可操作 | Browser Use 点击、输入、提交 | | 视觉无明显错位 | 截图检查关键视口 | | 代码结论可追溯 | 标注文件、函数、选择器、接口 | +| 工单流程可验收 | 列表、详情、指派、状态流转、权限态截图 |
diff --git a/slidev/pages/day3/m6-plan-review-summary.md b/slidev/pages/day3/m6-plan-review-summary.md index 08dd8f6..9b38e34 100644 --- a/slidev/pages/day3/m6-plan-review-summary.md +++ b/slidev/pages/day3/m6-plan-review-summary.md @@ -108,6 +108,8 @@ Trae CLI 企业版也可以嵌入流水线，形成类似能力。 | 项目 rules | 规则命中 | 能解释触发原因 | | 测试结果 | 缺口建议 | 能对应关键路径 | | 历史问题 | 回归提醒 | 能指向相似案例 | +| 工单权限矩阵 | 权限缺口 | 能对应角色和接口 | +| 工单状态流转表 | 非法路径 | 能指出拦截位置 | @@ -116,6 +118,29 @@ Trae CLI 企业版也可以嵌入流水线，形成类似能力。 输入包括 diff、rules、测试结果和历史问题。 输出要能落到文件、行号、规则和验证建议。 这样审查 Agent 才能进入团队流程。 +第四天处理工单复杂业务时，要把权限矩阵和状态流转表也放进 Review 输入。 +--> + +--- + +# JeecgBoot 工单承接：哪些任务必须先 Plan + +
+ +| 第 4 天任务 | 为什么不能直接改 | Plan 里必须写清 | +|---|---|---| +| RBAC 权限矩阵 | 影响菜单、按钮、接口和数据范围 | 角色、权限字符、接口、验收账号 | +| 状态流转 | 容易出现越权流转和脏状态 | 状态枚举、合法路径、非法路径 | +| 审计日志 | 事后追责依赖日志完整性 | 记录时机、字段、查询方式 | +| 异常态 | 代码成功但页面不可用 | 空态、失败态、无权限态、非法状态 | +| 看板指标 | 数字错误会误导管理判断 | 指标口径、权限过滤、数据来源 | + +
+ + --- @@ -129,11 +154,14 @@ Trae CLI 企业版也可以嵌入流水线，形成类似能力。
04 Agent 分工表
05 前端浏览器验证清单
06 Plan 与 Review 验收清单
+
07 JeecgBoot 工单链路索引
+
08 第 4 天任务 Plan 草案
--- @@ -141,29 +169,33 @@ layout: center class: text-center --- -# 三天课程闭环 +# 前三天到第四天 -
+
第 1 天
-用 TRAE 看懂真实代码库 +用 TRAE 看懂若依权限链路
第 2 天
-让 TRAE 按团队规则参与研发 +把若依经验沉淀成 rules
第 3 天
-把 TRAE 能力接入 Agent 工作方式 +能力体系 + JeecgBoot 工单承接 +
+
+
第 4 天
+进入权限、审计、异常态与看板开发

-> **最终能力：读得懂 · 问得准 · 查得实 · 改得稳 · 接得上流程** +> **第 4 天目标：让工单模块从“能跑通”升级到“可控制、可审计、可验证”。** diff --git a/slidev/pages/day4/m1-rbac-permission-model.md b/slidev/pages/day4/m1-rbac-permission-model.md new file mode 100644 index 0000000..4bcb3d3 --- /dev/null +++ b/slidev/pages/day4/m1-rbac-permission-model.md @@ -0,0 +1,77 @@ +# 模块 1：RBAC 权限模型设计 + +
+ +工单模块不是普通 CRUD。不同角色看到的数据不同、能做的动作不同、承担的责任也不同。 + +
+ +
+
管理员
+
负责人
+
研发
+
测试
+
只读用户
+
+ + + +--- + +# RBAC 权限矩阵 + +
+ +| 功能 | 管理员 | 负责人 | 研发 | 测试 | 只读 | +|---|---|---|---|---|---| +| 查看列表 | 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 | + +
+ + + +--- + +# 权限矩阵 Prompt + +
+ +```md +请基于 JeecgBoot 工单模块设计 RBAC 权限矩阵。 + +角色： +管理员、负责人、研发、测试、只读用户。 + +功能点： +查看列表、查看详情、新增、编辑、删除、指派、提交验证、关闭、驳回、查看审计记录、查看看板。 + +要求： +1. 区分允许、禁止、条件允许。 +2. 条件允许必须说明条件。 +3. 每个敏感操作给出验收方式。 +4. 不要直接生成代码。 +``` + +
+ + diff --git a/slidev/pages/day4/m2-permission-control.md b/slidev/pages/day4/m2-permission-control.md new file mode 100644 index 0000000..2c7b45e --- /dev/null +++ b/slidev/pages/day4/m2-permission-control.md @@ -0,0 +1,104 @@ +# 模块 2：权限控制方案生成 + +
+ +权限不是按钮隐藏。工单模块必须同时覆盖菜单权限、按钮权限、接口权限和数据权限。 + +
+ +
+
+
菜单
+能否进入页面 +
+
+
按钮
+能否看到操作 +
+
+
接口
+能否直接调用 +
+
+
数据
+能看到哪些工单 +
+
+ + + +--- + +# 工单权限字符建议 + +
+ +```md +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 +``` + +
+ +
+权限字符必须统一命名，否则前端、后端、菜单配置和 Review 清单会对不上。 +
+ + + +--- + +# 权限控制方案表 + +
+ +| 操作 | 前端入口 | 权限字符 | 后端接口 | 数据权限 | 验收 | +|---|---|---|---|---|---| +| 新增工单 | 新增按钮 | work:order:add | /workOrder/add | 无 | 无权限账号返回 403 | +| 删除工单 | 删除按钮 | work:order:delete | /workOrder/delete | 管理员范围 | 非管理员返回 403 | +| 指派工单 | 指派按钮 | work:order:assign | /workOrder/assign | 团队范围 | 研发账号不可指派 | +| 状态流转 | 状态按钮 | work:order:transition | /workOrder/transition | 工单可见范围 | 非法角色不能流转 | +| 查看看板 | 看板菜单 | work:order:dashboard | /workOrder/dashboard/* | 管理范围 | 只读用户不可访问 | + +
+ + + +--- + +# 权限落地检查 + +
+ +| 检查项 | 通过标准 | +|---|---| +| 菜单权限 | 菜单配置有对应权限字符 | +| 按钮权限 | 无权限用户看不到敏感按钮 | +| 接口权限 | 直接请求敏感接口被拒绝 | +| 数据权限 | 不同角色只看到授权范围 | +| 验收记录 | 有账号、操作、结果和证据 | + +
+ + diff --git a/slidev/pages/day4/m3-status-transition.md b/slidev/pages/day4/m3-status-transition.md new file mode 100644 index 0000000..b8c7e99 --- /dev/null +++ b/slidev/pages/day4/m3-status-transition.md @@ -0,0 +1,91 @@ +# 模块 3：工单状态流转规则实现 + +
+ +工单状态不能靠临时 if else。必须先设计状态机，再实现接口和校验。 + +
+ +
+
created
已创建
+
→
+
processing
处理中
+
→
+
pending_verify
待验证
+
→
+
closed
已关闭
+
+ +
pending_verify → rejected → processing
+ + + +--- + +# 状态流转表 + +
+ +| 当前状态 | 动作 | 目标状态 | 允许角色 | 前置条件 | 失败提示 | +|---|---|---|---|---|---| +| created | 指派 | processing | 管理员/负责人 | 必须选择指派人 | 请选择指派人 | +| processing | 提交验证 | pending_verify | 研发/负责人 | 必须填写处理说明 | 请填写处理说明 | +| pending_verify | 关闭 | closed | 测试/负责人 | 验证通过 | 当前工单不可关闭 | +| pending_verify | 驳回 | rejected | 测试/负责人 | 必须填写驳回原因 | 请填写驳回原因 | +| rejected | 重新处理 | processing | 研发/负责人 | 必须填写处理说明 | 请填写重新处理说明 | + +
+ + + +--- + +# 非法流转清单 + +
+ +| 当前状态 | 尝试动作 | 系统响应 | 验收 | +|---|---|---|---| +| closed | 重新处理 | 返回非法状态流转 | 状态不变 | +| created | 关闭 | 返回非法状态流转 | 页面提示原因 | +| processing | 驳回 | 返回非法状态流转 | 状态不变 | +| pending_verify | 驳回但无原因 | 返回参数错误 | 提示填写原因 | +| 任意状态 | 无权限流转 | 返回权限拒绝 | 不完成操作 | + +
+ + + +--- + +# 状态流转接口契约 + +
+ +```md +POST /workOrder/assign +字段：id、assignee、remark + +POST /workOrder/transition +字段：id、action、targetStatus、remark、version + +验收： +合法流转成功；非法流转失败；状态不被错误修改；审计日志可查。 +``` + +
+ + diff --git a/slidev/pages/day4/m4-audit-log.md b/slidev/pages/day4/m4-audit-log.md new file mode 100644 index 0000000..ad0ef58 --- /dev/null +++ b/slidev/pages/day4/m4-audit-log.md @@ -0,0 +1,95 @@ +# 模块 4：审计日志设计 + +
+ +工单是多人协作过程。关键动作必须能回答：谁、什么时候、对哪个工单、改了什么、结果如何。 + +
+ +
+
指派
+
状态变更
+
优先级变更
+
驳回
+
关闭
+
删除
+
+ + + +--- + +# 审计日志字段表 + +
+ +| 字段 | 含义 | 示例 | +|---|---|---| +| ticket_id | 工单 ID | WO-001 | +| operator | 操作人 | zhangsan | +| action | 操作动作 | assign / transition / edit | +| field_name | 字段名 | status / assignee | +| before_value | 修改前 | processing | +| after_value | 修改后 | pending_verify | +| result | 操作结果 | success / fail | +| operate_time | 操作时间 | 2026-06-29 10:00 | +| remark | 备注 | 提交验证说明 | + +
+ + + +--- + +# 详情页操作记录 + +
+ +| 展示字段 | 说明 | +|---|---| +| 操作时间 | 按时间倒序 | +| 操作人 | 当前登录用户 | +| 动作 | 指派、提交验证、驳回、关闭 | +| 变更内容 | status: processing -> pending_verify | +| 备注 | 处理说明、驳回原因 | +| 结果 | success / fail | + +
+ + + +--- + +# 审计日志 SOP + +
+ +```md +必须记录： +新增、编辑、删除、指派、状态变更、优先级变更、驳回、关闭。 + +展示位置： +工单详情页操作记录区域。 + +事务要求： +状态更新和日志写入在同一业务事务内完成。 + +验收： +执行状态变更、指派、驳回、关闭后，详情页能看到对应审计记录。 +``` + +
+ + diff --git a/slidev/pages/day4/m5-exception-defensive.md b/slidev/pages/day4/m5-exception-defensive.md new file mode 100644 index 0000000..802d5a1 --- /dev/null +++ b/slidev/pages/day4/m5-exception-defensive.md @@ -0,0 +1,90 @@ +# 模块 5：异常态与防御性逻辑 + +
+ +复杂业务不能只测正常流。权限不足、接口失败、重复提交、非法状态流转都必须有明确处理。 + +
+ +
+
空数据
+
接口失败
+
权限不足
+
重复提交
+
非法流转
+
工单不存在
+
+ + + +--- + +# 异常态清单 + +
+ +| 场景 | 触发条件 | 前端表现 | 后端响应 | 验收 | +|---|---|---|---|---| +| 空列表 | 查询无结果 | 显示空状态 | 返回空数组 | 不显示报错 | +| 接口失败 | 服务异常 | 提示重试 | 5xx 或业务错误 | 页面不崩溃 | +| 权限不足 | 无权限操作 | 按钮不可见或提示无权限 | 403 | 不完成操作 | +| 重复提交 | 连续点击提交 | 按钮禁用或 loading | 拒绝重复请求 | 只生成一条记录 | +| 非法流转 | closed -> processing | 提示非法状态 | 业务错误码 | 状态不变 | +| 工单不存在 | 错误 ID | 显示不存在 | 404 或业务错误 | 页面不崩溃 | + +
+ + + +--- + +# 最小测试集 + +
+ +| 编号 | 场景 | 操作 | 预期 | +|---|---|---|---| +| E01 | 无权限删除 | 研发账号请求删除接口 | 返回拒绝 | +| E02 | 非法状态流转 | closed -> processing | 状态不变 | +| E03 | 重复提交验证 | 连续点击提交验证 | 只成功一次 | +| E04 | 工单不存在 | 查询错误 ID | 页面不崩 | +| E05 | 驳回缺少原因 | remark 为空 | 返回参数错误 | +| E06 | 看板无数据 | 无数据范围 | 显示空态 | + +
+ + + +--- + +# 防御性修改边界 + +
+ +| 层级 | 修改重点 | +|---|---| +| 前端 | loading、禁用按钮、空态、错误提示 | +| 后端 Controller | 参数校验、权限校验 | +| Service | 状态校验、幂等、防重复、事务 | +| 审计日志 | 避免重复有效记录 | + +
+ +
+不要为了一个工单异常态，重写全局请求库或无关业务模块。 +
+ + diff --git a/slidev/pages/day4/m6-dashboard-metrics.md b/slidev/pages/day4/m6-dashboard-metrics.md new file mode 100644 index 0000000..1903f55 --- /dev/null +++ b/slidev/pages/day4/m6-dashboard-metrics.md @@ -0,0 +1,95 @@ +# 模块 6：研发效能看板指标开发 + +
+ +看板不是图表堆叠。核心是指标口径、数据来源和权限范围。 + +
+ +
+
工单总数
+
待处理数量
+
已关闭数量
+
平均关闭周期
+
优先级分布
+
状态趋势
+
+ + + +--- + +# 看板指标字典 + +
+ +| 指标 | 含义 | 计算口径 | 数据来源 | 展示 | +|---|---|---|---|---| +| 工单总数 | 当前工单总量 | 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 | 折线图 | + +
+ + + +--- + +# 看板统计接口契约 + +
+ +```md +GET /workOrder/dashboard/summary +返回：totalCount、pendingCount、closedCount、avgCloseHours + +GET /workOrder/dashboard/status +返回：状态分布 + +GET /workOrder/dashboard/priority +返回：优先级分布 + +GET /workOrder/dashboard/trend +返回：每日新增、每日关闭 +``` + +
+ +
+每个接口必须说明筛选条件、数据范围、统计口径和看板权限。 +
+ + + +--- + +# 看板页面验收 + +
+ +| 验收项 | 预期 | +|---|---| +| 看板权限 | 无 `work:order:dashboard` 权限不可访问 | +| Summary 指标 | 口径符合指标字典 | +| 状态分布 | 与列表筛选统计一致 | +| 趋势图 | 新增/关闭按日期展示 | +| 空数据 | 显示空态，不报 NaN 或 undefined | + +
+ + diff --git a/slidev/pages/day4/m7-review-delivery.md b/slidev/pages/day4/m7-review-delivery.md new file mode 100644 index 0000000..3a09de5 --- /dev/null +++ b/slidev/pages/day4/m7-review-delivery.md @@ -0,0 +1,129 @@ +# 模块 7：阶段代码审查与修复 + +
+ +第四天改动涉及权限、状态、审计、异常和看板，必须做阶段 Review。 + +
+ +
+
权限是否闭环
+
状态流转是否完整
+
审计日志是否可查
+
异常态是否覆盖
+
看板口径是否清楚
+
测试是否覆盖关键路径
+
+ + + +--- + +# AI Review 输入 + +
+ +| 输入材料 | 用途 | +|---|---| +| 当天 diff | 看实际修改 | +| RBAC 权限矩阵 | 判断权限是否正确 | +| 状态流转表 | 判断合法和非法路径 | +| 审计日志 SOP | 判断是否可追溯 | +| 异常态清单 | 判断防御性逻辑 | +| 看板指标字典 | 判断统计口径 | +| 测试结果 | 判断是否可验收 | + +
+ + + +--- + +# 阶段 Review 报告 + +
+ +| 等级 | 模块 | 问题 | 风险 | 修复建议 | 验收 | +|---|---|---|---|---|---| +| P1 | 权限 | 删除接口只隐藏按钮，后端缺少校验 | 可绕过前端删除工单 | 补后端权限校验 | 无权限请求返回 403 | +| P1 | 状态 | closed 工单仍可重新处理 | 关闭状态失效 | 禁止 closed -> processing | 接口返回非法状态 | +| P2 | 审计 | 指派未记录前后值 | 难以追踪责任 | 记录 old/new assignee | 详情页日志可查 | +| P2 | 看板 | 平均关闭周期口径不清 | 管理判断失真 | 明确 create_time 到 close_time | 指标字典更新 | + +
+ + + +--- + +# 修复记录 + +
+ +| Review 编号 | 问题 | 是否成立 | 修改说明 | 验证结果 | 资产沉淀 | +|---|---|---|---|---|---| +| R01 | 删除接口缺少权限校验 | 是 | 增加后端权限校验 | 无权限请求被拒绝 | 权限检查清单 | +| R02 | closed 可重新处理 | 是 | 补非法流转校验 | 状态不变 | 状态流转检查清单 | +| R03 | 看板关闭周期口径不清 | 是 | 明确指标口径 | 指标说明已更新 | 看板口径清单 | + +
+ + + +--- + +# 第 4 天交付物 + +
+
01 工单 RBAC 权限矩阵
+
02 工单权限控制方案
+
03 工单状态流转表
+
04 非法流转清单
+
05 工单审计日志 SOP
+
06 异常态与防御性逻辑清单
+
07 研发效能看板指标字典
+
08 看板接口验收记录
+
09 阶段 Review 报告
+
10 修复记录
+
+ + + +--- +layout: center +class: text-center +--- + +# 第 4 天总结 + +
+让工单模块从“能跑通”升级到“可控制、可审计、可验证、可 Review”。 +
+ +
+
权限矩阵
+
状态机
+
审计 SOP
+
异常清单
+
Review 闭环
+
+ + diff --git a/slidev/slides.md b/slidev/slides.md index 073ce01..554e5b7 100644 --- a/slidev/slides.md +++ b/slidev/slides.md @@ -126,3 +126,39 @@ src: ./pages/day3/m5-browser-docs-index.md --- src: ./pages/day3/m6-plan-review-summary.md --- + +--- +layout: new-section +--- + +# 第 4 天：JeecgBoot 工单复杂业务开发 + +权限 · 审计 · 异常态 · 看板 + +--- +src: ./pages/day4/m1-rbac-permission-model.md +--- + +--- +src: ./pages/day4/m2-permission-control.md +--- + +--- +src: ./pages/day4/m3-status-transition.md +--- + +--- +src: ./pages/day4/m4-audit-log.md +--- + +--- +src: ./pages/day4/m5-exception-defensive.md +--- + +--- +src: ./pages/day4/m6-dashboard-metrics.md +--- + +--- +src: ./pages/day4/m7-review-delivery.md +--- diff --git a/第 3 天：TRAE 能力体系与 Agent 工作方式.md b/第 3 天：TRAE 能力体系与 Agent 工作方式.md new file mode 100644 index 0000000..7484a41 --- /dev/null +++ b/第 3 天：TRAE 能力体系与 Agent 工作方式.md @@ -0,0 +1,1547 @@ +# 第 3 天：TRAE 能力体系与 Agent 工作方式 + +# 第 0 部分：从规则治理到 Agent 工作流 + +--- + +## Slide 0-1：第 1 天到第 3 天 + +### PPT 页面内容 + +```Plain Text +第 1 天： +让 TRAE 看懂若依代码 + +第 2 天： +让 TRAE 按团队规则参与若依研发 + +第 3 天： +切换到 JeecgBoot 工单案例 +把 TRAE 能力接入 Agent 工作方式 + +核心变化： +从单次对话 +到可复用、可验收、可协作的 Agent 工作流 +``` + +### 讲师逐字稿 + +前两天我们一直围绕若依项目来训练。 + +第一天，大家学习的是如何让 TRAE 看懂陌生代码库。我们不是泛泛问“这个项目是什么”，而是沿着登录、用户信息、菜单路由、按钮权限这条链路，找入口、追文件、查函数、标注依据。 + +第二天，我们进一步学习上下文工程和 rules。也就是说，不只是让 AI 看懂代码，还要让 AI 按团队规则做事。比如不能把前端按钮权限当安全边界，涉及敏感接口必须检查后端权限，敏感操作必须检查操作日志。 + +第三天我们切换到 JeecgBoot 工单管理模块。原因很简单：若依更适合训练读代码和规则治理，JeecgBoot 更适合训练企业应用开发、代码生成、页面配置、权限接入和功能验收。 + +今天不是单纯介绍产品功能。今天要回答的是：在 JeecgBoot 工单模块开发中，团队如何把常用 Prompt、规则、检查清单、浏览器验证、Plan 和 Review 组织成一套可以反复使用的 Agent 工作流。 + +--- + +## Slide 0-2：第三天训练主线 + +### PPT 页面内容 + +```Plain Text +今天训练六个动作： + +规则分层 +任务分级 +能力封装 +工具接入 +浏览器验证 +Plan / Review 闭环 + +最终产出： +JeecgBoot 工单 Agent 工作流资产草案 v0.1 +``` + +### 讲师逐字稿 + +今天的主线有六个动作。 + +第一，规则分层。第二天我们写了 rules.md，今天要把这些规则迁移到 JeecgBoot 工单模块里，形成前端、后端、权限、审计、测试和交付规则。 + +第二，任务分级。不是所有任务都适合让 Agent 全托管。拆工单需求、生成接口契约、审查代码生成结果、修改状态流转、修复 CI，它们的风险、上下文需求和验收方式都不同。 + +第三，能力封装。前两天大家写了很多好 Prompt，今天要把它们升级成 Commands 和 Skills。 + +第四，工具接入。Agent 不只看代码，还可能接 Git、CI、浏览器、文档库和内部平台。 + +第五，浏览器验证。尤其前端改动，不能停留在“代码看起来对”，必须能打开页面、操作流程、截图复核。 + +第六，Plan 和 Review 闭环。高风险任务必须先计划，再执行，再审查。 + +今天最终产出不只是代码，而是一套围绕 JeecgBoot 工单模块的 Agent 工作流资产草案 v0.1。 + +--- + +## Slide 0-3：贯穿案例 + +### PPT 页面内容 + +```Plain Text +贯穿案例： +JeecgBoot 工单管理模块开发与审查 + +从一次 Prompt +到一套 Agent 工作流： + +需求 -> 契约 -> 代码生成 -> Command -> Skill -> Browser 验证 -> Plan -> Review +``` + +### 讲师逐字稿 + +今天我们切换到新的贯穿案例：JeecgBoot 工单管理模块开发与审查。 + +这个案例包含工单列表、工单详情、状态、优先级、指派人、评论记录、按钮权限、接口权限和基础验收。它比前两天的“读代码和规则审查”更接近真实开发交付。 + +今天我们不再只问 TRAE：“帮我写一个工单模块。” + +今天我们要把这个任务拆成一套工作流： + +先把需求拆清楚，再设计字段、接口契约和页面状态；再判断哪些高频动作适合 Command，哪些复杂流程适合 Skill；如果涉及页面，就要设计 Browser 验证；如果涉及状态流转、删除、指派等高风险修改，就要进入 Plan 模式；最后再用 Review 模板检查风险。 + +这就是从单次对话升级到 Agent 工作流。 + +--- + +# 模块 1：规则体系的演进 + +--- + +## Slide 1-1：为什么第三天还要讲规则？ + +### PPT 页面内容 + +```Plain Text +第 2 天： +写出 rules.md v0.1 + +第 3 天： +让 rules 进入 Agent 工作流 + +规则不只是文档 +规则是 Agent 的执行边界 +``` + +### 讲师逐字稿 + +第二天我们已经写过若依 rules.md v0.1，为什么第三天还要继续讲规则？ + +因为规则写出来只是第一步。第三天要做的是把这些规则迁移到 JeecgBoot 工单模块开发中，让 Agent 在需求拆解、代码生成、权限接入、浏览器验证和 Review 中都能正确读取、触发和执行这些规则。 + +比如“前端按钮权限不是安全边界”这条规则，到了 JeecgBoot 工单模块里，就会影响新增、编辑、删除、指派、状态变更等按钮设计，也会影响后端接口权限注解和无权限访问验证。 + +所以第三天讲规则，不是重复第二天，而是把 rules 从静态文档推进到 Agent 工作流的执行边界。 + +--- + +## Slide 1-2：规则资产的演进路径 + +### PPT 页面内容 + +```Plain Text +规则资产演进： + +.vscode +统一编辑器和格式化 + +.cursorrules / .mdc +告诉 AI 项目偏好 + +.trae/rules/ +按场景拆分规则 + +AGENTS.md +跨工具共享协作约定 +``` + +### 讲师逐字稿 + +规则资产有一个演进路径。 + +最早我们用 `.vscode` 统一编辑器、插件、格式化和调试配置。这类配置主要服务人和 IDE。 + +后来出现 `.cursorrules`、`.mdc` 这类文件，开始把项目偏好告诉 AI。比如用什么框架、什么代码风格、什么测试方式。 + +再往后是 `.trae/rules/` 这类分层规则目录。它不只是一个大文件，而是可以按前端、后端、安全、测试、交付拆开。 + +最后是 `AGENTS.md` 这样的跨工具约定。同一个仓库可能被 TRAE、Cursor、Claude Code、Codex 等不同 Agent 读取，跨工具规则可以减少重复维护。 + +课堂里大家不用纠结哪个文件名更先进，关键是理解：团队规则正在从人读的文档，变成 Agent 能读取和执行的工程资产。 + +--- + +## Slide 1-3：从散装规则到分层规则 + +### PPT 页面内容 + +```Plain Text +.trae/ +└── rules/ + ├── global.md + ├── frontend.md + ├── backend.md + ├── security.md + ├── testing.md + └── delivery.md +``` + +### 讲师逐字稿 + +第二天我们写 rules.md v0.1 时，为了课堂统一，先写成一个文件。 + +真实团队里，如果规则越来越多，一个文件会很快变长，最后没人愿意维护，也很难判断规则什么时候触发。 + +所以更合理的做法是分层。 + +`global.md` 放所有任务都必须遵守的规则，比如输出要标注依据、不确定内容要说明、修改前要说明影响范围。 + +`frontend.md` 放前端页面、api 模块、权限按钮、异常态和防重复提交规则。 + +`backend.md` 放 Controller、Service、权限注解、事务、参数校验规则。 + +`security.md` 放密钥、账号、权限、敏感日志、越权风险。 + +`testing.md` 放测试覆盖要求。 + +`delivery.md` 放 PR、Review、CI、发布和回滚要求。 + +--- + +## Slide 1-4：规则迁移课堂练习 + +### PPT 页面内容 + +```Plain Text +练习： +把 Day 2 的 rules.md v0.1 迁移到 JeecgBoot 工单模块 + +要求： +每组至少迁移 5 条规则 +说明目标文件、触发场景、验收方式 +``` + +### 讲师逐字稿 + +这一页开始做第一个课堂练习。 + +请大家从第二天写的 rules.md v0.1 中挑出至少 5 条规则，把它们迁移到 JeecgBoot 工单模块的分层规则里。 + +不要只是说“这条放 security.md”。要说明为什么。 + +比如“前端按钮权限不是安全边界”，它可以放进 `security.md`，因为它本质是安全边界问题；同时也可以在 `frontend.md` 中引用，因为它会影响工单新增、编辑、删除、指派、状态变更等按钮实现方式。 + +再比如“新增接口调用必须放入 api 模块”，这明显属于 `frontend.md`。在 JeecgBoot 工单模块里，列表、详情、评论、状态变更都应该通过对应 api 文件调用。 + +每条规则都要写清楚三个信息：目标文件、触发场景、验收方式。 + +### 课堂产出 + +```md +| 原规则 | 目标文件 | 触发场景 | 必须动作 | 验收方式 | +|---|---|---|---|---| +| 前端按钮权限不是安全边界 | security.md / frontend.md | 工单新增、编辑、删除、指派、状态变更 | 检查后端权限注解 | 标注接口、权限字符和无权限验证 | +| 新增接口调用必须放入 api 模块 | frontend.md | 工单列表、详情、评论、状态变更接口 | 新建或复用工单 api 文件 | 页面不直接拼接 URL | +``` + +--- + +# 模块 2：Token、Cue 与任务成本 + +--- + +## Slide 2-1：Token 经济学不是省字数 + +### PPT 页面内容 + +```Plain Text +早期关注： +Prompt 越短越好 +Token 越省越好 + +现在关注： +任务边界是否清楚 +上下文是否有效 +输出是否可验收 +返工是否减少 +``` + +### 讲师逐字稿 + +很多人一听 Token 经济学，会以为是教大家怎么把 Prompt 写短。 + +这不是今天的重点。 + +企业真正要管的不是一两句话多花了多少 token，而是一次 AI 任务是否减少了返工。 + +如果任务边界不清楚，AI 反复猜、反复改、反复跑偏，看起来每次调用不贵，但整体成本很高。 + +如果上下文给得很准，输出格式清楚，验收标准明确，即使单次上下文更长，总体上也可能更省。 + +所以第三天讲 Token，不是讲个人省字数，而是讲团队如何设计稳定的上下文管道。 + +--- + +## Slide 2-2：JeecgBoot 工单任务的成本差异 + +### PPT 页面内容 + +```Plain Text +低成本任务： +解释生成代码、生成摘要、补充注释 + +中成本任务： +拆解需求、审查代码生成结果、生成测试点 + +高成本任务： +状态流转、权限逻辑修改、审计日志、CI 修复 +``` + +### 讲师逐字稿 + +在 JeecgBoot 项目里，不同任务的 AI 成本差异很大。 + +解释一段工单列表查询代码，通常只需要 `#Code`，成本低，风险也低。 + +分析工单列表到详情的完整链路，就需要 `@workspace` 找入口，再用 `#File` 聚焦前端页面、api 文件、Controller 和 Service，成本和复杂度都上升。 + +如果是修改工单删除、指派或状态流转逻辑，并补权限判断和审计日志，这就是高风险任务。它不仅需要上下文，还需要 Plan、测试和 Review。 + +所以不能一上来就说“交给 Agent”。要先判断任务类型。 + +--- + +## Slide 2-3：Tab、Cue 与 Agent + +### PPT 页面内容 + +```Plain Text +Tab： +补下一行 + +Cue： +理解上下文，做更智能的补全和编辑 + +Agent： +围绕目标执行多步任务 +计划、修改、验证、交付 +``` + +### 讲师逐字稿 + +大家可以把 AI 编程能力分成三个层次理解。 + +第一层是 Tab，也就是早期补全。你写到一半，它补下一行。 + +第二层是 Cue。Cue 强调上下文理解，不只是补一行，而是理解当前文件、周边代码和意图，给出更完整的建议。 + +第三层是 Agent。Agent 不只是补代码，而是围绕一个目标执行多步任务：理解需求、找文件、制定计划、修改代码、运行检查、解释结果。 + +企业培训里最重要的是：不要把这三层混在一起。 + +解释函数可以用局部能力。跨模块修改必须进入 Agent 工作流。 + +--- + +## Slide 2-4：课堂练习：任务成本与能力匹配 + +### PPT 页面内容 + +```Plain Text +练习： +判断以下JeecgBoot 工单任务适合哪种能力 + +解释生成代码 +拆解工单需求 +审查代码生成结果 +修改状态流转 +生成 PR 说明 +分析 CI 失败日志 +``` + +### 讲师逐字稿 + +现在做第二个课堂练习。 + +我给大家六个 JeecgBoot 工单任务，请每组判断：它的风险高不高，需要什么上下文，适合用对话、Cue、Command、Skill、Agent Plan 还是 Review。 + +注意，答案不是唯一的。 + +比如“审查代码生成结果”可以用 Command，也可以进入 Skill。区别在于：如果只是一次固定格式检查，用 Command 就够；如果要按步骤查字段、查询条件、字典、权限、审计、异常态和测试缺口，那就更像 Skill。 + +### 课堂产出 + +```md +| 任务 | 风险 | 上下文需求 | 推荐能力 | 验收方式 | +|---|---|---|---|---| +| 解释工单列表查询代码 | 低 | #Code | 对话 / Cue | 能说清输入、输出、异常 | +| 拆解工单需求 | 中 | 需求说明 + 项目规则 | Agent 分析 | 有用户故事和验收标准 | +| 审查代码生成结果 | 中 | 生成代码 + rules | Command / Skill | 输出代码生成 Review 清单 | +| 修改工单状态流转 | 高 | 相关文件 + rules + 测试 | Plan 后执行 | 状态机验证 + Review | +| 生成 PR 说明 | 低 | diff | Command | 说明变更、测试、风险 | +| 分析 CI 失败日志 | 中 | 日志 + diff | Agent / CLI | 定位原因和修复建议 | +``` + +--- + +# 模块 3：从 Commands 到 Skills + +--- + +## Slide 3-1：Commands 解决重复输入 + +### PPT 页面内容 + +```Plain Text +Commands： +把常用话术封装成快捷入口 + +适合： +固定问法 +固定格式 +固定检查 +固定输出 +``` + +### 讲师逐字稿 + +前两天大家已经写过很多 Prompt。 + +比如“请拆解 JeecgBoot 工单管理需求”，比如“请审查代码生成结果”，比如“请检查工单删除、指派、状态变更是否有后端权限和审计日志”。 + +如果这些 Prompt 每次都手打一遍，就会出现两个问题。 + +第一，容易漏条件。第二，每个人写法不一样，输出不稳定。 + +Commands 的价值，就是把这些高频、固定、可复用的 Prompt 变成快捷入口。 + +它适合固定问法、固定格式、固定检查和固定输出。 + +--- + +## Slide 3-2：JeecgBoot 工单适合沉淀哪些 Commands？ + +### PPT 页面内容 + +```Plain Text +建议沉淀： + +/模块结构分析 +/工单需求拆解 +/接口契约生成 +/代码生成 Review +/操作日志检查 +/生成测试点 +/生成 PR 说明 +``` + +### 讲师逐字稿 + +结合 JeecgBoot 工单案例，最适合先沉淀这些 Commands。 + +`/模块结构分析` 用来快速建立模块认知。 + +`/工单需求拆解` 用来把原始需求拆成用户故事、功能边界、非目标范围和异常场景。 + +`/接口契约生成` 用来生成工单列表、详情、评论、状态变更等接口契约。 + +`/代码生成 Review` 用来审查 JeecgBoot 生成的 CRUD 代码是否满足字段、查询、分页、字典、权限和异常态要求。 + +`/操作日志检查` 用来检查敏感操作是否记录日志。 + +`/生成测试点` 用来从正常流、异常流、权限流、边界值生成测试清单。 + +`/生成 PR 说明` 用来把 diff 转成标准 PR 描述。 + +这些都不是抽象能力，而是 JeecgBoot 工单开发当天会反复使用的任务。 + +--- + +## Slide 3-3：坏 Command 示例 + +### PPT 页面内容 + +```Plain Text +/检查代码 + +问题： +目标太泛 +范围不清 +没有输入要求 +没有输出格式 +没有验收标准 +``` + +### 讲师逐字稿 + +Command 不是随便起个名字就行。 + +比如 `/检查代码` 就是一个坏 Command。 + +它的问题和坏 Prompt 一样：目标太泛、范围不清、没有输入要求、没有输出格式、没有验收标准。 + +AI 看到这个命令，可能检查格式，可能检查 bug，可能检查权限，也可能泛泛说“代码结构清晰”。 + +这样的 Command 进入团队资产库，反而会制造噪声。 + +--- + +## Slide 3-4：好 Command 示例 + +### PPT 页面内容 + +```Plain Text +/代码生成 Review + +输入： +生成的前端页面、api 文件、后端 Controller、Service、rules + +输出： +字段一致性、查询条件、分页排序、字典使用、权限按钮、异常态、不确定点 +``` + +### 讲师逐字稿 + +更好的 Command 要明确场景。 + +比如 `/代码生成 Review`。 + +它的使用场景是：JeecgBoot 根据工单表生成基础 CRUD 之后，正式进入人工调整前使用。 + +它的输入包括生成的前端页面、api 文件、后端 Controller、Service、数据表字段和当前 rules。 + +它的输出必须覆盖字段一致性、查询条件、分页排序、字典枚举、权限按钮、异常态和不确定点。 + +这样它就不是一句口号，而是可以执行、可以验收的团队资产。 + +### 课堂产出 + +```md +# /代码生成 Review + +## 使用场景 +JeecgBoot 基于 work_order 表生成工单模块基础代码后使用。 + +## 输入 +- 数据表字段说明 +- 生成的前端页面 +- api 模块文件 +- 后端 Controller +- 后端 Service +- 当前 rules + +## 执行要求 +1. 检查字段是否和数据模型一致 +2. 检查查询条件、分页、排序是否完整 +3. 检查状态、优先级、类型是否使用字典或枚举 +4. 检查新增、编辑、删除、导出按钮是否需要权限控制 +5. 检查 loading、empty、error、forbidden 状态是否缺失 +6. 标注不确定点 + +## 输出格式 +| 检查项 | 文件 | 现状 | 问题 | 建议 | 验收 | +|---|---|---|---|---|---| +``` + +--- + +## Slide 3-5：Skills 解决完整流程 + +### PPT 页面内容 + +```Plain Text +Command： +封装一句标准化指令 + +Skill： +封装一套完整工作流 + +Skill 可以包含： +说明、步骤、模板、脚本、检查清单、示例 +``` + +### 讲师逐字稿 + +Command 解决的是重复输入。 + +Skill 解决的是完整流程。 + +比如“代码生成 Review”可以做成 Command，因为它主要是一套固定输出格式。 + +但“JeecgBoot 工单模块开发审查”更适合做成 Skill，因为它要分步骤执行：先拆需求和接口契约，再审查生成代码，再检查按钮权限、后端接口、操作日志、异常态和测试缺口，最后输出风险与验收建议。 + +Skill 还可以携带模板、脚本、检查清单和示例。 + +所以当一个任务需要多步判断、多个输入、多个输出，并且希望团队反复复用时，就应该考虑 Skill。 + +--- + +## Slide 3-6：JeecgBoot 工单模块开发审查 Skill 设计 + +### PPT 页面内容 + +```Plain Text +课堂任务： +设计一个“JeecgBoot 工单模块开发审查 Skill” + +必须包含： +触发场景 +输入材料 +执行步骤 +输出格式 +验收标准 +``` + +### 讲师逐字稿 + +现在每组设计一个“JeecgBoot 工单模块开发审查 Skill”。 + +注意，这里不是让大家写代码，也不是写一个很长的 Prompt。 + +我们要写的是一张 Skill 设计卡片，让团队知道这个 Skill 在什么情况下触发，需要什么输入，按什么步骤执行，输出什么结果，怎么判断合格。 + +### 课堂产出 + +```md +# JeecgBoot 工单模块开发审查 Skill + +## 触发场景 +涉及工单列表、详情、评论、状态、指派、看板、权限字符、数据权限、操作日志的需求拆解、代码生成或代码修改。 + +## 输入材料 +- PR diff 或相关文件 +- 工单需求说明 +- 数据模型与接口契约 +- `.trae/rules.md` +- 前端页面文件 +- api 模块文件 +- 后端 Controller / Service + +## 执行步骤 +1. 识别需求范围和非目标范围 +2. 检查字段、接口契约和页面状态是否完整 +3. 审查 JeecgBoot 生成代码的字段、查询、分页、字典和异常态 +4. 检查新增、编辑、删除、指派、状态变更的前端按钮与后端权限 +5. 检查操作日志、数据权限和测试缺口 +6. 输出风险、不确定点和验收建议 + +## 输出格式 +需求拆解表、接口契约表、代码生成 Review 清单、权限风险表、日志风险表、测试缺口清单、不确定点清单。 + +## 验收标准 +每个关键结论必须标注文件、函数、注解或调用链依据。 +``` + +--- + +## Slide 3-7：MCP 与 CLI 的位置 + +### PPT 页面内容 + +```Plain Text +CLI： +命令稳定、脚本成熟、轻量接入 + +MCP： +结构化能力描述、交互式工具、平台化接入 + +Skill： +把使用方法和流程一起交付 +``` + +### 讲师逐字稿 + +MCP 不要讲成抽象技术名词。 + +企业真正关心的是：Agent 怎么接入已有工具。 + +如果一个能力已经有稳定命令，比如跑测试、查日志、生成报告，优先用 CLI 封装，简单、直接、可维护。 + +如果一个能力需要长期连接、交互式操作、结构化描述，比如浏览器、数据库、设计工具、内部平台，那 MCP 更合适。 + +如果一个能力不只是工具调用，还需要说明、模板、步骤和示例，就适合放进 Skill。 + +所以 CLI、MCP、Skill 不是互相替代，而是不同层次的封装方式。 + +### 课堂产出 + +```md +| 需求 | 推荐封装 | 理由 | 验收 | +|---|---|---|---| +| 生成 PR 说明 | Command | 固定格式、低风险 | PR 模板字段完整 | +| JeecgBoot 工单模块开发审查 | Skill | 多步骤、多文件、多规则 | 输出风险表和依据 | +| 读取 CI 日志 | CLI | 已有命令或 API | 能定位失败阶段 | +| 操作浏览器验证页面 | Browser / MCP | 需要点击、输入、截图 | 有截图和步骤记录 | +``` + +--- + +# 模块 4：从单 Agent 到 Agent Teams + +--- + +## Slide 4-1：为什么需要多个 Agent？ + +### PPT 页面内容 + +```Plain Text +单 Agent： +一个助手处理全部任务 + +SubAgent： +主 Agent 拆出子任务 + +Agent Teams： +按角色分工协作交付 +``` + +### 讲师逐字稿 + +小任务用一个 Agent 就够了。 + +比如解释一个函数、生成一个 PR 说明、整理一段测试点，一个 Agent 可以完成。 + +但任务复杂之后，一个 Agent 很容易同时承担需求分析、代码修改、测试、Review、文档生成等职责，输出会混在一起。 + +多 Agent 的价值不是“看起来更智能”，而是分工。 + +就像真实研发团队里有开发、测试、Review、运维一样，Agent 也可以按角色承担不同职责。 + +--- + +## Slide 4-2：JeecgBoot 工单场景中的 Agent 分工 + +### PPT 页面内容 + +```Plain Text +JeecgBoot 工单模块开发审查可以拆成： + +代码理解 Agent +规则审查 Agent +测试建议 Agent +Review Agent +文档整理 Agent +``` + +### 讲师逐字稿 + +还是看 JeecgBoot 工单管理模块开发与审查。 + +需求拆解 Agent 负责把原始工单需求拆成用户故事、功能边界和验收标准。 + +代码生成审查 Agent 负责检查 JeecgBoot 生成的前后端代码是否符合字段、接口、字典和页面状态设计。 + +测试建议 Agent 负责输出正常流、无权限流、异常流、边界值和状态流转测试点。 + +Review Agent 负责基于 diff、rules 和测试结果输出问题等级、文件位置、风险解释和修复建议。 + +文档整理 Agent 负责把过程整理成报告或资产库条目。 + +这比让一个 Agent 直接“帮我检查一下”更稳定。 + +--- + +## Slide 4-3：Agent 分工表 + +### PPT 页面内容 + +```Plain Text +每个 Agent 都要定义： + +输入 +动作 +输出 +验收 +边界 +``` + +### 讲师逐字稿 + +Agent 分工不能只写名字。 + +比如“测试 Agent”这个名字没有意义。 + +必须说清楚它的输入是什么，是 diff、需求、接口契约，还是测试报告？ + +它的动作是什么，是生成测试点，还是补单测，还是分析失败日志？ + +它的输出是什么，是测试清单、测试代码，还是失败原因报告？ + +它的验收方式是什么？ + +它不能做什么？比如测试 Agent 不应该擅自改业务逻辑。 + +### 课堂产出 + +```md +| Agent | 输入 | 动作 | 输出 | 验收 | 边界 | +|---|---|---|---|---|---| +| 需求拆解 Agent | 原始需求 | 拆用户故事、边界、异常 | 需求拆解文档 | 有验收标准 | 不直接写代码 | +| 代码生成审查 Agent | 生成代码、字段表、rules | 查字段、查询、字典、异常态 | 代码生成 Review 清单 | 能指向文件和问题 | 不直接合入 | +| 测试建议 Agent | 需求、diff | 生成测试点 | 测试点清单 | 覆盖正常/异常/权限/状态 | 不替代人工验收 | +| Review Agent | PR diff、测试结果 | 审查风险 | Review 报告 | 有等级、位置、建议 | 不替代最终审批 | +``` + +--- + +## Slide 4-4：Trae Solo 的协作信号 + +### PPT 页面内容 + +```Plain Text +Trae Solo 体现的方向： + +设计能力 +开发能力 +部署能力 +验证能力 + +全托管不是无人负责 +而是更需要边界和验收 +``` + +### 讲师逐字稿 + +Trae Solo 这类模式，体现的是 Agent 能力从辅助走向全流程执行。 + +它可能帮助做设计、写代码、部署、验证。 + +但这里要提醒大家：全托管不是无人负责。 + +越是全托管，越需要明确边界和验收。 + +低风险任务可以让 Agent 多做一点，比如整理文档、生成摘要、补测试点。 + +高风险任务，比如权限、状态流转、工单删除、审计日志、生产缺陷修复，就必须有 Plan、Review 和人工确认。 + +--- + +## Slide 4-5：产品形态分化 + +### PPT 页面内容 + +```Plain Text +Trae IDE： +专业开发者主工作台 + +Trae Solo： +IDE 内全托管 Agent 模式 + +Trae Work： +面向任务结果 + +Trae CLI 企业版： +接入 Git、CI、协作平台和内部系统 +``` + +### 讲师逐字稿 + +AI 编程产品会出现不同形态。 + +IDE 面向专业开发者，适合在代码现场使用。 + +Solo 面向更完整的任务托管，在 IDE 内完成设计、开发、验证。 + +Work 更偏任务结果，可能让非专业开发者也能发起需求。 + +CLI 企业版适合接入 Git、CI、飞书、钉钉、GitLab、GitHub 和内部平台。 + +这里不是让大家记产品名，而是理解不同入口服务不同场景。 + +--- + +## Slide 4-6：AI 时代付费模式 + +### PPT 页面内容 + +```Plain Text +免费版： +体验与轻度使用 + +个人付费版： +高频开发者，更强模型与更多额度 + +企业版： +团队与组织，权限、合规、审计、私有化、集成 +``` + +### 讲师逐字稿 + +这一页是大家现场已经讲到的位置。 + +AI 产品和传统互联网产品不太一样，因为每次调用都有真实计算成本。 + +免费版更多是让用户建立习惯。 + +个人付费版解决高频开发者的额度和模型能力问题。 + +企业版真正解决的是团队治理问题：谁能用、怎么用、用什么模型、能不能审计、能不能接内部系统、能不能做权限和合规控制。 + +所以企业落地 AI 编程，不是简单买账号，而是要把 AI 放进研发流程里治理。 + +--- + +## Slide 4-7：从付费模式转回课堂实操 + +### PPT 页面内容 + +```Plain Text +讲到付费模式之后，要落回三个问题： + +什么任务值得交给 Agent？ +交给哪个 Agent？ +交付后怎么验收？ +``` + +### 讲师逐字稿 + +讲到付费模式之后，不要停留在商业模式。 + +要把它转回工程问题。 + +既然每次 AI 调用都有成本，企业版又强调权限、审计和集成，那么团队就必须回答三个问题。 + +第一，什么任务值得交给 Agent？ + +第二，交给哪个 Agent 或哪种能力？ + +第三，交付后怎么验收？ + +接下来我们就进入浏览器验证、Plan 和 Review，这些都是为了回答第三个问题：Agent 做完之后，怎么证明它做对了。 + +--- + +# 模块 5：Browser Preview 与 Browser Use + +--- + +## Slide 5-1：为什么前端任务必须浏览器验证？ + +### PPT 页面内容 + +```Plain Text +代码通过不等于页面可用 + +前端至少验证： +页面能打开 +主流程可操作 +异常态可见 +权限态正确 +截图可复核 +``` + +### 讲师逐字稿 + +前端任务有一个特点：代码看起来没问题，不代表页面真的可用。 + +JeecgBoot 工单管理页面也是这样。 + +列表能不能加载？标题、状态、优先级、指派人筛选有没有生效？重置按钮有没有清空？分页能不能切换？无权限用户是否看不到删除、指派、状态变更按钮？接口失败时页面有没有提示？ + +这些不能只靠读代码。 + +所以第三天要引入 Browser Preview 和 Browser Use。 + +--- + +## Slide 5-2：Browser Preview 与 Browser Use + +### PPT 页面内容 + +```Plain Text +Browser Preview： +人在 IDE 中看页面效果 + +Browser Use： +AI 操作浏览器完成验证 + +一个服务视觉反馈 +一个服务任务验收 +``` + +### 讲师逐字稿 + +Browser Preview 和 Browser Use 要分开。 + +Preview 是给人看的。它让开发者不用频繁切换窗口，可以在 IDE 里快速看页面。 + +Browser Use 是给 Agent 执行验证用的。它可以点击、输入、跳转、提交表单、截图，帮助完成流程验证。 + +一个服务视觉反馈，一个服务任务验收。 + +企业前端研发里，这两者都很有价值。 + +--- + +## Slide 5-3：JeecgBoot 工单管理页面验证项 + +### PPT 页面内容 + +```Plain Text +工单列表/详情页面验证： + +打开页面 +按标题查询 +按状态筛选 +重置条件 +分页切换 +新增/修改/删除/指派/状态变更按钮权限 +无权限访问 +接口失败提示 +``` + +### 讲师逐字稿 + +还是以 JeecgBoot 工单管理页面为例。 + +浏览器验证不要写成“页面正常”。 + +要拆成具体动作。 + +打开页面，页面是否加载成功。 + +输入工单标题查询，列表是否刷新。 + +选择状态或优先级筛选，结果是否符合条件。 + +点击重置，查询条件是否清空。 + +切换分页，列表是否变化。 + +不同角色账号访问时，新增、修改、删除、指派、状态变更、导出按钮是否按权限显示。 + +无权限用户直接请求接口，是否返回 403。 + +接口失败时，页面是否有错误提示。 + +这些才是可执行的 Browser 验证。 + +### 课堂产出 + +```md +| 步骤 | 操作 | 预期结果 | 证据 | 备注 | +|---|---|---|---|---| +| 1 | 打开工单列表/详情页面 | 页面正常加载 | 截图 | 记录 URL | +| 2 | 输入工单标题查询 | 列表按条件刷新 | 截图/接口 | 记录查询参数 | +| 3 | 按状态、优先级筛选 | 结果符合筛选条件 | 截图/接口 | 记录筛选参数 | +| 4 | 点击重置 | 查询条件清空 | 截图 | 检查默认值 | +| 5 | 无权限账号查看删除/指派按钮 | 按钮不可见或接口 403 | 截图/响应 | 不能只看前端 | +``` + +--- + +## Slide 5-4：浏览器驱动的三条路线 + +### PPT 页面内容 + +```Plain Text +Playwright： +稳定、可复现，适合自动测试 + +Agent Browser： +集成度高，适合复杂网页任务 + +指针模拟： +接近真人操作，适合临时验证 +``` + +### 讲师逐字稿 + +浏览器驱动有几条路线。 + +Playwright 适合工程化测试，稳定、可复现，适合进入 CI。 + +Agent Browser 更偏专用环境，集成度高，适合复杂网页任务。 + +指针模拟更接近真人操作，适合临时视觉验证。 + +课堂里不用深入实现细节，大家先理解能力边界。 + +真正落地时，稳定流程优先 Playwright，临时验证可以用 Browser Use。 + +--- + +## Slide 5-5：代码库索引的两种路线 + +### PPT 页面内容 + +```Plain Text +向量化索引： +语义搜索强，适合大仓库概念查找 + +关键词搜索： +实时、可解释，适合定位文件和函数 + +结论必须回到文件、函数、调用点 +``` + +### 讲师逐字稿 + +Agent 要理解代码，离不开代码库索引。 + +向量化索引适合语义搜索，比如“不知道权限在哪里，但想找权限相关逻辑”。 + +关键词搜索适合精确定位，比如搜 `queryById`、`工单按钮权限`、`@PreAuthorize`。 + +两种路线都有价值。 + +但无论用哪种，最终结论必须回到文件、函数和调用点。 + +这也是第一天反复强调的：AI 输出必须有依据。 + +--- + +## Slide 5-6：Markdown 是 AI 时代的一等文档格式 + +### PPT 页面内容 + +```Plain Text +Markdown 的价值： + +结构清楚 +易读写 +可 diff +可版本管理 +可转换 +``` + +### 讲师逐字稿 + +前两天的产物，包括代码理解报告、rules、检查清单、Prompt 模板，本质上都适合用 Markdown 保存。 + +原因很简单：结构清楚、容易读写、可以 diff、可以版本管理，也方便转换成 Word、PDF、网页或知识库。 + +AI 最擅长处理结构化文本。 + +所以企业资产库建议先用 Markdown 管核心内容，再按需要转换格式。 + +--- + +## Slide 5-7：水合与脱水 + +### PPT 页面内容 + +```Plain Text +脱水： +从 Word、PPT、PDF 抽出结构和模板 + +生成： +用 Markdown 生产正文 + +水合： +把 Markdown 注入目标格式 +``` + +### 讲师逐字稿 + +这里讲一个实用概念：水合与脱水。 + +复杂格式文档，比如 Word、PPT、PDF，不适合让 AI 直接自由编辑。 + +更稳定的流程是先脱水：从旧文档里抽出结构、模板、样式要求。 + +然后生成：让 AI 用 Markdown 写正文。 + +最后水合：把 Markdown 内容注入模板，输出 Word、PPT 或 PDF。 + +这套思路对后续课程资产库建设也很重要。 + +--- + +# 模块 6：Plan、Review 与第三天交付验收 + +--- + +## Slide 6-1：Agent 参与度光谱 + +### PPT 页面内容 + +```Plain Text +纯手工 +AI Copilot 辅助 +手动触发全托管 +Loops 全托管 + +参与度越高 +越需要清楚的边界和验收 +``` + +### 讲师逐字稿 + +Agent 参与研发有一个光谱。 + +最左边是纯手工，人自己写。 + +再往右是 Copilot 辅助，AI 补全、解释、给建议。 + +再往右是手动触发全托管，人给目标，AI 执行。 + +最右边是 Loops 全托管，AI 自主循环，人主要负责审阅。 + +越往右，AI 参与度越高，人越不能只靠感觉管理。 + +必须有边界、计划、验证和 Review。 + +--- + +## Slide 6-2：Plan 模式 + +### PPT 页面内容 + +```Plain Text +Plan 阶段： +理解目标 +划定范围 +列出步骤 +标注风险 + +执行阶段： +修改文件 +运行检查 +汇报 diff +给出验证结果 +``` + +### 讲师逐字稿 + +Plan 模式本质上是把“想清楚再动手”显性化。 + +高风险任务不要让 Agent 直接改代码。 + +比如修改工单删除逻辑、调整权限判断、修改数据权限过滤、修复生产缺陷，都应该先进入 Plan。 + +Plan 里要写清目标、范围、不做什么、涉及文件、步骤、风险、验证方式。 + +人审过 Plan，再让 Agent 执行。 + +这样可以减少误改和返工。 + +--- + +## Slide 6-3：JeecgBoot 高风险任务 Plan 模板 + +### PPT 页面内容 + +```Plain Text +示例任务： +调整工单管理删除逻辑 + +Plan 必须写清： +目标、范围、不做什么、步骤、风险、验证 +``` + +### 讲师逐字稿 + +我们用一个JeecgBoot 工单任务举例：调整工单管理删除逻辑。 + +这个任务看起来只是删除工单，但它实际涉及前端按钮、api 调用、后端接口、权限注解、操作日志、数据权限、异常处理和测试。 + +所以必须先写 Plan。 + +### 课堂产出 + +```md +# Plan：工单管理删除逻辑调整 + +## 目标 +检查并补齐工单删除逻辑中的权限校验、操作日志和异常处理。 + +## 范围 +- 工单列表/详情页面删除按钮 +- 工单 api 模块 +- 工单删除 Controller 接口 +- 工单 Service 删除逻辑 +- 权限注解和操作日志 + +## 不做什么 +- 不调整角色模型 +- 不修改数据库结构 +- 不修改无关页面 + +## 修改步骤 +1. 定位前端删除按钮和权限字符 +2. 定位删除 API 调用 +3. 定位后端删除接口 +4. 检查权限注解 +5. 检查操作日志 +6. 补充异常处理或测试建议 + +## 风险点 +权限绕过、误删、日志缺失、数据权限遗漏。 + +## 验收方式 +正常删除、无权限删除、非法参数、重复提交、日志记录。 +``` + +--- + +## Slide 6-4：自动 Review 的输入输出 + +### PPT 页面内容 + +```Plain Text +输入： +PR diff、项目 rules、测试结果、历史问题 + +输出： +风险点、规则命中、测试缺口、回归提醒 + +验收： +有文件、有行号、有原因、有建议 +``` + +### 讲师逐字稿 + +Review Agent 不能只说“代码不错”。 + +自动 Review 必须结构化。 + +输入包括 PR diff、项目 rules、测试结果和历史问题。 + +输出包括风险点、规则命中、测试缺口和回归提醒。 + +每个问题都要能落到文件、行号、规则、风险解释和修复建议。 + +如果证据不足，要写不确定点，而不是猜。 + +### 课堂产出 + +```md +# AI Review 报告 + +## Review 输入 +- PR diff： +- 相关 rules： +- 测试结果： +- 业务背景： + +## 问题清单 +| 等级 | 文件 | 问题 | 触发规则 | 风险 | 建议 | 测试 | +|---|---|---|---|---|---|---| +| P1 | WorkOrderController.java | 删除接口缺少权限校验 | 敏感接口必须检查后端权限 | 可能绕过前端删除工单 | 增加权限注解 | 无权限账号请求返回 403 | + +## 不确定点 +列出缺少代码、日志或业务依据的结论。 + +## 是否建议合入 +通过 / 暂缓 / 阻断，并说明原因。 +``` + +--- + +## Slide 6-5：最后 30 分钟交付验收会 + +### PPT 页面内容 + +```Plain Text +最后 30 分钟： + +整理第三天资产 +小组互评 +补验收标准 +选出可进入资产库的版本 +``` + +### 讲师逐字稿 + +第三天最后也要像第二天一样做交付验收会。 + +不要只停在概念总结。 + +每组至少拿出三类材料：一个 Command，一个 Skill 设计卡片，一个 Plan 或 Review 模板。 + +然后小组之间交叉 Review。 + +Review 的标准仍然是：是否有触发场景，是否有输入要求，是否有执行步骤，是否有输出格式，是否有验收方式。 + +最后选出可以进入团队资产库的版本。 + +### 课堂安排 + +```md +| 时间 | 动作 | 输出 | +|---|---|---| +| 8 分钟 | 整理一个 JeecgBoot 工单 Command | Command 模板 | +| 8 分钟 | 设计一个 JeecgBoot 工单 Skill | Skill 设计卡片 | +| 6 分钟 | 补一个 Plan 或 Review 模板 | Plan / Review 模板 | +| 5 分钟 | 小组互评 | 改写建议 | +| 3 分钟 | 选入资产库候选 | 候选资产 | +``` + +--- + +## Slide 6-6：第 3 天交付物 + +### PPT 页面内容 + +```Plain Text +第 3 天交付物： + +01 规则迁移清单 +02 任务成本与能力匹配表 +03 Command 模板 +04 Skill 设计卡片 +05 CLI / MCP / Skill 封装决策表 +06 Agent 分工表 +07 Browser 验证清单 +08 Plan 与 Review 模板 +``` + +### 讲师逐字稿 + +第三天最终交付八个产物。 + +第一，规则迁移清单。把第二天的 rules.md v0.1 拆成分层规则。 + +第二，任务成本与能力匹配表。判断不同任务适合哪种 AI 能力。 + +第三，Command 模板。把高频 Prompt 变成快捷入口。 + +第四，Skill 设计卡片。把完整流程封装成团队能力。 + +第五，CLI、MCP、Skill 封装决策表。判断不同工具和任务如何接入 Agent。 + +第六，Agent 分工表。明确代码理解、规则审查、测试建议、Review、文档整理等角色的输入输出。 + +第七，Browser 验证清单。让前端改动有可复核的验收记录。 + +第八，Plan 与 Review 模板。让高风险任务先计划、后执行、再审查。 + +这些材料共同构成第三天的 Agent 工作流资产草案 v0.1。 + +--- + +## Slide 6-7：交付物验收标准 + +### PPT 页面内容 + +```Plain Text +验收标准： + +能复用 +能触发 +能执行 +能验证 +能进入资产库 +``` + +### 讲师逐字稿 + +第三天的交付物，也要有验收标准。 + +能复用：不是一次性聊天记录，下个 JeecgBoot 类后台项目能改名继续用。 + +能触发：写清楚什么场景使用，不是泛泛的“检查一下”。 + +能执行：有输入、有步骤、有输出格式。 + +能验证：有验收标准、有证据要求、有不确定点处理。 + +能进入资产库：命名清楚，版本清楚，适合放进团队 `ai-dev-assets` 目录。 + +### 验收表 + +```md +| 交付物 | 通过标准 | +|---|---| +| 规则迁移清单 | 每条规则有目标文件、触发场景、验收方式 | +| Command 模板 | 有使用场景、输入、执行要求、输出格式 | +| Skill 设计卡片 | 有触发场景、输入材料、步骤、输出、验收 | +| Browser 验证清单 | 覆盖页面打开、主流程、权限态、异常态、证据 | +| Plan 模板 | 有目标、范围、不做什么、步骤、风险、验证 | +| Review 模板 | 有等级、文件、规则、风险、建议、测试 | +``` + +--- + +## Slide 6-8：三天课程闭环 + +### PPT 页面内容 + +```Plain Text +第 1 天： +读得懂 + +第 2 天： +问得准、查得实 + +第 3 天： +封装得住、验收得了、接得上流程 + +最终能力： +从单次使用 TRAE +到团队级 Agent 工作流 +``` + +### 讲师逐字稿 + +到第三天结束，前三天形成一个闭环。 + +第一天解决“读得懂”。拿到一个陌生代码库，能让 TRAE 帮我们看结构、找入口、追链路、查依据。 + +第二天解决“问得准、查得实”。通过上下文工程、幻觉控制、rules 和资产化，让 TRAE 输出更稳定、更可复核。 + +第三天解决“封装得住、验收得了、接得上流程”。把常用 Prompt 封装成 Command，把复杂流程封装成 Skill，把前端结果交给 Browser 验证，把高风险任务放进 Plan 和 Review。 + +这就是从个人使用 AI 工具，升级到团队级 Agent 工作流。 + +--- + +# 第 3 天最终资产目录建议 + +```Plain Text +ai-dev-assets/ +├── rules/ +│ ├── global.md +│ ├── frontend.md +│ ├── backend.md +│ ├── security.md +│ ├── testing.md +│ └── delivery.md +├── commands/ +│ ├── 模块结构分析.command.md +│ ├── 工单需求拆解.command.md +│ ├── 接口契约生成.command.md +│ ├── 代码生成Review.command.md +│ └── PR说明生成.command.md +├── skills/ +│ └── JeecgBoot 工单模块开发审查.skill.md +├── templates/ +│ ├── Plan任务模板.md +│ ├── AIReview报告模板.md +│ └── Browser验证报告模板.md +├── checklists/ +│ ├── 任务成本与能力匹配表.md +│ ├── Agent分工表.md +│ └── CLI-MCP-Skill封装决策表.md +└── examples/ + ├── 好Command与坏Command对照.md + ├── 好Skill与坏Skill对照.md + └── 好Plan与坏Plan对照.md +``` + +## 讲师收束话术 + +第三天的重点不是让大家记住更多名词。 + +Commands、Skills、MCP、Browser、Plan、Review，这些词如果孤立看，容易变成产品功能介绍。 + +但放回JeecgBoot 工单案例里，它们其实是一条很清楚的线： + +高频问法沉淀成 Command。 + +复杂流程沉淀成 Skill。 + +外部系统通过 CLI 或 MCP 接入。 + +前端结果通过 Browser 验证。 + +高风险任务先 Plan，再执行。 + +代码进入 PR 前后，用 Review 模板检查。 + +最终沉淀进团队资产库。 + +这就是第三天要带走的能力：不是会点更多按钮，而是能把 AI 编程能力组织成团队可复用的研发流程。 diff --git a/第 4 天：JeecgBoot 工单复杂业务开发：权限、审计、异常态与看板.md b/第 4 天：JeecgBoot 工单复杂业务开发：权限、审计、异常态与看板.md new file mode 100644 index 0000000..195db96 --- /dev/null +++ b/第 4 天：JeecgBoot 工单复杂业务开发：权限、审计、异常态与看板.md @@ -0,0 +1,2274 @@ +# 第 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. 不要直接生成代码。 + +输出： +权限矩阵表 + 不确定点。 +``` + +--- + +# 模块 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. 输出无权限访问验收步骤。 + +验收： +管理员可以删除；研发账号不能看到删除按钮；研发账号直接请求删除接口被拒绝。 +``` + +--- + +# 模块 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 驳回但无原因被拒绝 +``` + +--- + +# 模块 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. 输出修改文件清单和验收步骤。 + +不做： +- 不修改全局登录逻辑。 +- 不把敏感信息写入日志。 +``` + +--- + +# 模块 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. 输出每个异常态的验收步骤。 + +不做： +- 不重写全局请求库。 +- 不修改无关业务模块。 +- 不改变既有角色模型。 +``` + +--- + +# 模块 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 指标 | 管理员 + 本月 | 口径符合指标字典 | | | +| 状态分布 | 管理员 + 本月 | 与列表筛选统计一致 | | | +| 趋势图 | 管理员 + 本月 | 新增/关闭按日期展示 | | | +| 空数据 | 无数据筛选条件 | 显示空态，不报错 | | | +``` + +--- + +# 模块 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-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-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-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-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 和修复闭环跑起来。 + +这就是第四天要带走的能力。