diff --git a/CI失败日志-真实Maven环境错误.md b/CI失败日志-真实Maven环境错误.md new file mode 100644 index 0000000..a4aff9f --- /dev/null +++ b/CI失败日志-真实Maven环境错误.md @@ -0,0 +1,29 @@ +# CI 失败日志： Maven 环境错误 + +## 使用边界 + +这是一段实际保留的 Maven 构建失败记录，用于第六天的 CI 日志分析演练。 + +- 直接错误是本地 Maven 仓库文件无法写入。 +- 它是环境/文件权限问题，不是公务用车模块的业务代码或编译错误。 +- 不将它写入 `training/require-cancel-reason` 训练分支，因此该分支仍保持两处业务改动的真实 diff。 + +## 原始记录 + +```text +[WARNING] Failed to write tracking file '/Users/smart/.m2/repository/org/bouncycastle/bcpkix-jdk18on/resolver-status.properties' +java.io.FileNotFoundException: /Users/smart/.m2/repository/org/bouncycastle/bcpkix-jdk18on/resolver-status.properties (Operation not permitted) + at java.io.RandomAccessFile.open0 (Native Method) + at java.io.RandomAccessFile.open (RandomAccessFile.java:344) + at java.io.RandomAccessFile.(RandomAccessFile.java:259) + at org.eclipse.aether.internal.impl.DefaultTrackingFileManager.update(DefaultTrackingFileManager.java:84) + at org.eclipse.aether.internal.impl.DefaultUpdateCheckManager.write(DefaultUpdateCheckManager.java:529) + at org.eclipse.aether.internal.impl.DefaultMetadataResolver.resolveMetadata(DefaultMetadataResolver.java:180) + +[ERROR] java.io.FileNotFoundException: /Users/smart/.m2/repository/org/bouncycastle/bcpkix-jdk18on/resolver-status.properties (Operation not permitted) +[ERROR] BUILD FAILURE +``` + +## 来源说明 + +记录来源：`JeecgBoot-training` 仓库历史训练分支 `training/no-cross-order-ticket-reassignment` 中的 `training/ci-build-failure.log`。该历史分支仅作为环境错误材料来源，不作为第五、六天的业务案例。 diff --git a/TRAE 培训大纲V1.0.md b/TRAE 培训大纲V1.0.md index df1f010..53262ee 100644 --- a/TRAE 培训大纲V1.0.md +++ b/TRAE 培训大纲V1.0.md @@ -145,61 +145,62 @@ -### 第 5 天：历史代码重构、测试覆盖与团队资产库建设 +### 第 5 天：可沉淀的 AI 工程资产：Rule、任务上下文契约、Skill、Agent 与 MCP **目标：** -掌握用 TRAE 安全治理技术债、补齐测试覆盖，并将课程中的规则、Prompt、模板、案例和流程沉淀为可维护的企业资产库。 +以当前 JeecgBoot 的公务用车模块为真实素材，识别一次状态变更中的项目事实、反例与重复判断；重点拆解如何将这些信息分别沉淀为 Rule、任务上下文契约、检查单、示例和 Skill。案例只提供证据来源，不作为可复制的通用答案。 |内容|实操|产出| |---|---|---| -|历史代码问题识别|分析长函数、重复判断、隐式规则、类型缺失、分支过深|代码坏味道清单| -|重构方案生成|生成策略模式、composable 拆分、类型抽取方案|重构方案| -|重构风险审查|检查行为一致性、影响范围、回滚方案、测试缺口|重构风险清单| -|重构实操|对预置历史模块进行分层拆分和类型治理|重构 Diff| -|TypeScript 类型治理|从接口响应、状态枚举、表单模型中抽取类型|TypeScript Interface| -|测试用例生成|覆盖权限、状态流转、异常输入、边界值|单测用例清单| -|Vitest 单测补齐|修正无效断言和脆弱测试|单测脚本与覆盖率报告| -|团队资产库分层设计|将课程产物分为规则、Prompt、模板、案例、SOP、指标|资产库目录结构| -|`.trae/rules.md` 生命周期|设计规则新增、评审、废弃、版本管理机制|规则维护机制| -|Prompt 模板库建设|标准化读代码、拆需求、写代码、重构、测试、Review、CI 修复 Prompt|Prompt 模板库| -|案例库沉淀|提取优秀案例、问题案例、幻觉案例、CI 失败案例|案例库| -|资产评审机制|明确谁维护、多久评审、如何合入、如何淘汰|资产治理 SOP| -|新人和项目推广机制|设计新人学习路径、项目接入流程、检查机制|TRAE 推广流程| +|案例引子：识别资产原料|阅读取消派车的状态、入口、权限和写入顺序，区分项目事实与可迁移判断|事实与反例清单| +|资产边界与选型|根据变化频率、误用风险、决策复杂度和证据来源，区分稳定约束、运行时事实与可沉淀资产|资产选型表| +|Rule 设计契约|编写证据等级、适用场景、必须项、禁止项、来源与验收方式完整的 Rule|可执行 Rule 草案| +|任务上下文契约|拆分固定约束与运行时事实，定义结构化输出、证据缺口与停止边界，并用代表性输入验证|影响分析任务契约与测试样例| +|Skill 包拆解|理解 SKILL.md、发现配置、Prompt、检查单、模板、参考资料和脚本各自职责|Skill 包结构图| +|Skill 组合与停止条件|用 Rule、Prompt、检查单和模板编排事实提取、方案比较、验证设计与结论输出|Skill 工作流与输出契约| +|资产验证与演进|用完整输入、缺失证据、范围冲突和跨项目输入测试资产边界，明确可复用与必须重查的内容|资产测试矩阵与演进记录| +|自定义 Agent 角色契约|拆解角色名称、用途说明、参数提示、模型、工具和默认指令，区分稳定配置与运行时事实|自定义 Agent 设计卡| +|Agent 权限与停止边界|按职责配置最小工具集，明确证据不足、范围越界和验证缺失时的停止条件|Agent 权限矩阵与停止条件| +|Agent 与 Skill 组合|明确 Agent、Skill、Rule、Prompt、检查单和运行时事实的权威位置，设计结构化交接结果|Agent-Skill 组合图与交接契约| +|历史模块职责识别与方案比选|基于公务用车派车 Service 的现有校验、写入与事务边界，识别重构候选并比较最小方案|重构候选与方案比选表| +|重构风险审查|围绕取消派车的输入保护、状态保护、双对象写入、权限与审计入口识别不可改变行为|重构风险清单| +|跨端类型契约治理|核验审批结果与申请状态在 Java 常量、TypeScript 模型和表单配置中的表示差异|类型契约与核验项| +|测试基线与定向补齐|区分当前 JUnit/Mockito 与 Jest 已证明的范围，补齐派车状态、副作用、请求载荷和类型契约测试|测试缺口矩阵与定向用例清单| +|真实 Skill 包与资产库|拆解现有 Skill 包的目录、Prompt、模板、检查单与反例，用测试夹具验证资产边界|资产索引与验收夹具| +|MCP 能力资产|围绕外部工具的能力说明、输入输出、权限、审计、故障降级与验证夹具编写 MCP 契约|MCP 能力契约与权限验收清单| +|派车重构目标结构|在不改变事务边界、拒绝顺序、接口字段和状态写入语义的前提下，设计派车入口的候选职责拆分|候选职责结构图| +|无损重构行为基线|将申请、车辆、司机的拒绝路径与派车成功后的车辆预占整理为可回归的行为基线|无损重构验收表| +|命令与展示模型分离|基于派车 VO、实体和前端模型区分用户可提交字段与系统生成字段|命令与展示类型表| +|类型契约核验用例|将审批结果大小写与申请状态表示差异转化为可执行的接受、拒绝和载荷检查|类型契约用例集| +|取消派车测试矩阵|覆盖空白原因、任务不存在、非法状态、正常取消与车辆缺失等真实分支|取消派车测试矩阵| +|测试层级与断言边界|区分 Controller 委派、Service 状态副作用与 API 契约各自应验证的内容|测试分层检查表| - - -### 第 6 天：企业研发效能、PR 闭环、CI 门禁与落地计划 +### 第 6 天：工程协作与质量闭环：PR、Git、CI、证据链与资产验证 **目标：** -建立 AI 辅助研发效能管理方法，能够基于 PR、CI、缺陷、需求流转数据分析团队产出率、质量和吞吐，并跑通开发、Review、CI、验收、资产沉淀、管理复盘的完整闭环。 +将 AI 参与的分析、实现和资产使用放入可审查、可验证、可追溯的工程交付链路，掌握 PR 说明、Git 合并控制、CI 失败分析、变更证据链、资产版本兼容性和可演进性审查的方法。AI Code Review 方法沿用第 4 天的既有流程，不再重复讲解。 |内容|实操|产出| |---|---|---| -|研发效能指标体系|定义产出、质量、吞吐、周期、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 改动的工程闭环|建立从影响分析、变更实现到 PR、CI 和技术结论的交付链路|工程质量检查视图| +|标准 PR 说明与 AI 使用记录|基于 diff、需求、测试结果和风险点生成可审查的 PR 描述|PR 模板与样例| +|AI 变更 Git 协作|明确分支范围、提交粒度、冲突处理、合并前置条件和回退方式|Git 协作检查单| +|CI 失败日志分析|结合日志、构建配置、相关 diff 和项目规则，区分源码、依赖与环境问题|CI 失败分析记录| +|CI 质量门禁|理解 lint、typecheck、unit test、coverage 与人工检查各自覆盖的风险|CI 质量门禁清单| +|共享资产的版本与兼容性|识别会改变 Agent 行为的资产 diff，说明版本边界、不兼容点、迁移与回退条件|资产兼容性说明| +|变更证据链与可追溯说明|将需求、diff、测试、CI、日志和人工观察连接到可复核的技术结论|技术说明与证据地图| +|AI 改动的可演进性审查|审查修改入口、规则权威位置、依赖隔离和回归定位能力，降低后续变化成本|可演进性审查清单| +|资产变更的工程验证|审查 Rule、任务上下文契约、Skill、Agent 与 MCP 契约的行为变化、引用完整性、兼容性和测试夹具|资产变更审查清单| ### AI Native 技能清单 @@ -223,8 +224,8 @@ |重构阶段|无损重构|重构 Diff、风险清单| |Review 阶段|AI Code Review|Review 问题清单| |CI 阶段|CI 失败分析|CI 失败原因与修复方案| -|管理阶段|研发效能分析|效能分析报告| -|管理阶段|ROI 测算|ROI 测算报告| +|工程协作阶段|PR 与变更说明|可审查的变更记录| +|工程协作阶段|CI 失败分析|失败原因与验证方案| @@ -272,19 +273,25 @@ - \[ \] 可运行的工单/效能看板业务代码 -- \[ \] 核心历史模块的重构 Diff 记录 +- \[ \] 项目知识库 README 与新人上手导览 -- \[ \] 高质量 TypeScript 接口定义文件 +- \[ \] AI 任务委派模板 -- \[ \] 达到标准覆盖率的单元测试脚本与报告 +- \[ \] 核心历史模块的坏味道清单、重构风险清单与最小重构方案 -- \[ \] 跑通的 CI/CD 质量门禁 YAML 配置 +- \[ \] 测试安全网清单、单元测试脚本与覆盖率记录 -- \[ \] 团队级 AI Code Review 标准清单 +- \[ \] Rule / Prompt / Command / Skill 设计卡与候选资产清单 -- \[ \] 精选沉淀的 Prompt 模板资产库 +- \[ \] 标准 PR 模板与 AI 使用记录表 -- \[ \] ROI 效能提升测算报告及落地计划 +- \[ \] 团队级 AI Code Review 标准清单与 Review 修复闭环记录 + +- \[ \] CI 失败分析记录与 CI/CD 质量门禁方案 + +- \[ \] 团队资产库目录、入库标准、版本维护与淘汰机制 + +- \[ \] 交付证据包与复用边界说明 --- @@ -306,13 +313,10 @@ 8. **工程闭环力：** 能够将 AI Review 融入个人提交习惯，并掌握借助 CI 日志让 AI 自动修复代码的流水线能力。 -9. **管理量化力：** 技术负责人能建立明确的 TRAE 落地方案，掌握代码产出比、交付周期等 ROI 测算方式。 +9. **工程协作力：** 学员能够把 AI 参与的变更说明、验证证据和可复用资产纳入可审查、可追溯的研发交付链路。 ## 咨询费用 6 \* 12000 = 720000 元 付款方式：合同签订后付款50%，培训过半后付款30%，培训结束付款20%。 - - - diff --git a/deliverables/ai-engineering-skills-delivery-utf8.zip b/deliverables/ai-engineering-skills-delivery-utf8.zip deleted file mode 100644 index 648057c..0000000 Binary files a/deliverables/ai-engineering-skills-delivery-utf8.zip and /dev/null differ diff --git a/deliverables/ai-engineering-skills-delivery.zip b/deliverables/ai-engineering-skills-delivery.zip deleted file mode 100644 index da38126..0000000 Binary files a/deliverables/ai-engineering-skills-delivery.zip and /dev/null differ diff --git a/deliverables/ai-engineering-skills-delivery/INSTALL.md b/deliverables/ai-engineering-skills-delivery/INSTALL.md deleted file mode 100644 index 8afc3d5..0000000 --- a/deliverables/ai-engineering-skills-delivery/INSTALL.md +++ /dev/null @@ -1,67 +0,0 @@ -# 安装说明 - -## 方式一：安装到 TRAE Skills 目录 - -把 `skills/` 下的 5 个 Skill 文件夹复制到本机 Skills 目录： - -```text -~/.trae/skills/ -``` - -安装后目录应类似： - -```text -~/.trae/skills/ -├── project-knowledge-builder/ -├── 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 $project-knowledge-builder 为当前项目生成 docs/project-knowledge 项目知识库。 -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、检查清单和反例库。 - -`examples/` 目录只用于学习参考，不要复制到通用 Skills 安装目录。换项目复用时，应先用 `project-knowledge-builder` 建立项目知识库，再用 `generate-project-constraints` 重新扫描目标项目，最后使用其他 Skill 生成该项目自己的权限、状态、审计、Review 和修复闭环资产。 - -## 维护建议 - -- 每次项目规则变化后，重新运行 `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 deleted file mode 100644 index 3cae1b7..0000000 --- a/deliverables/ai-engineering-skills-delivery/README.md +++ /dev/null @@ -1,51 +0,0 @@ -# AI Engineering Skills Delivery - -本交付包提供 5 个可复用 AI 工程 Skill，覆盖真实项目中从项目知识库、项目约束生成、复杂业务设计、交付 Review 到修复闭环的完整流程。 - -这些 Skill 不是单次 Prompt，而是可安装、可复制、可随项目持续维护的团队资产。 - -`skills/` 目录中的内容是通用资产，不能绑定某个训练项目或客户项目；具体案例只放在 `examples/` 目录，作为参考材料，不作为通用 Skill 安装项。 - -## 交付内容 - -```text -客户AI工程Skill交付包/ -├── README.md -├── INSTALL.md -├── skills/ -│ ├── project-knowledge-builder/ -│ ├── generate-project-constraints/ -│ ├── design-complex-business-module/ -│ ├── review-business-delivery/ -│ └── track-review-fix-loop/ -└── examples/ - └── jeecgboot-work-order/ -``` - -## Skill 列表 - -| Skill | 用途 | 典型产物 | -| --- | --- | --- | -| `project-knowledge-builder` | 深度整理代码仓库，生成给人和 AI 复用的项目知识库 | 项目知识库 README、上下文图、架构/运行/前后端/数据/权限文档、RAG 索引建议、生成索引 | -| `generate-project-constraints` | 从项目源码、配置、CI、文档中提取项目约束 | rules、约束提取表、验收清单 | -| `design-complex-business-module` | 设计复杂业务模块的权限、状态、审计、异常态和看板 | RBAC 矩阵、权限控制方案、状态流转表、审计 SOP、异常态清单、看板指标字典、看板接口验收记录 | -| `review-business-delivery` | 审查复杂业务交付物或 PR 的业务风险 | AI Review 报告、阶段 Review 报告、权限/状态/审计/异常态/看板检查清单、业务交付验收清单 | -| `track-review-fix-loop` | 跟踪 Review 问题修复、验证和资产沉淀 | 修复记录、未闭环清单、资产更新建议、权限/状态/审计/指标反例库 | - -## 推荐使用顺序 - -1. 使用 `project-knowledge-builder` 生成项目知识库，让团队和 AI 先理解项目。 -2. 使用 `generate-project-constraints` 为客户项目生成项目规则。 -3. 使用 `design-complex-business-module` 生成复杂业务设计资产。 -4. 使用 `review-business-delivery` 审查设计、代码或阶段交付物。 -5. 使用 `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 deleted file mode 100644 index 4bc5f74..0000000 --- a/deliverables/ai-engineering-skills-delivery/examples/jeecgboot-work-order/JeecgBoot工单模块开发审查.skill.md +++ /dev/null @@ -1,44 +0,0 @@ -# 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 deleted file mode 100644 index 36337fa..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/SKILL.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -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 deleted file mode 100644 index 1d0695e..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -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 deleted file mode 100644 index 438030f..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/RBAC权限矩阵.template.md +++ /dev/null @@ -1,19 +0,0 @@ -# <模块名称> RBAC 权限矩阵 - -## 使用说明 - -将列名中的 `<角色A>`、`<角色B>`、`<角色C>` 替换为目标项目真实角色。权限字符只能写成建议，除非源码、菜单配置或后端注解已经证明。 - -| 功能点 | <管理员角色> | <业务负责人角色> | <处理人角色> | <审核人角色> | <只读角色> | 权限字符建议 | 数据范围 | 来源证据 | 备注 | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| 查看列表 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | `::list` | 按授权范围 | | | -| 查看详情 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | `::query` | 仅可见数据 | | | -| 新建记录 | 允许 | 允许 | 条件允许 | 条件允许 | 拒绝 | `::add` | 通常无数据范围 | | | -| 编辑记录 | 允许 | 条件允许 | 条件允许 | 拒绝 | 拒绝 | `::edit` | 创建人/负责人/授权范围 | | 需结合状态 | -| 分配/转交 | 允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | `::assign` | 管理范围 | | 高风险操作 | -| 状态流转 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | `::transition` | 当前数据范围 | | 需结合状态表 | -| 关闭/归档 | 允许 | 条件允许 | 拒绝 | 条件允许 | 拒绝 | `::close` | 当前数据范围 | | 终态动作 | -| 删除记录 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | 拒绝 | `::delete` | 管理范围 | | 高危操作 | -| 查看审计日志 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | `::audit` | 当前数据范围 | | | -| 查看统计看板 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | `::dashboard` | 按角色过滤 | | | -| 导出数据 | 条件允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | `::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 deleted file mode 100644 index 0ff18f8..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/RBAC权限矩阵生成.prompt.md +++ /dev/null @@ -1,27 +0,0 @@ -# RBAC 权限矩阵生成 Prompt - -```text -请基于目标业务模块设计 RBAC 权限矩阵。 - -输入材料： -- 模块名称：<填写> -- 业务对象：<填写，例如订单、客户、申请、任务> -- 需求说明或用户故事：<粘贴> -- 角色列表：<粘贴目标项目真实角色> -- 功能点：<粘贴页面、按钮、接口、数据动作> -- 项目依据：<粘贴权限、路由、菜单、接口、后端校验相关路径> - -输出要求： -1. 先列事实依据：权限、菜单、动态路由、接口、后端校验相关路径。 -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 deleted file mode 100644 index bb815dc..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/审计日志SOP.template.md +++ /dev/null @@ -1,41 +0,0 @@ -# <模块名称> 审计日志 SOP - -## 记录原则 - -所有会改变目标业务对象关键状态、负责人/处理人、可见性、金额、结论或对外结果的动作都必须记录审计日志。 - -## 审计字段 - -| 字段 | 含义 | 示例 | -| --- | --- | --- | -| target_type | 业务对象类型 | order / customer / request | -| target_id | 业务对象 ID | 100001 | -| actor_id | 操作人 ID | 1001 | -| actor_name | 操作人名称 | zhangsan | -| action | 操作类型 | ASSIGN / APPROVE / CLOSE | -| field_name | 变更字段 | status / owner_id / amount | -| 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 deleted file mode 100644 index 1eebc8f..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/审计日志检查清单.md +++ /dev/null @@ -1,12 +0,0 @@ -# 审计日志检查清单 - -| 检查项 | 通过标准 | 结果 | -| --- | --- | --- | -| 创建记录 | 创建业务记录后能查询审计记录 | | -| 字段变更 | 编辑关键字段记录 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 deleted file mode 100644 index d53299c..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/异常态检查清单.md +++ /dev/null @@ -1,12 +0,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 deleted file mode 100644 index f591b2e..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/异常态清单.template.md +++ /dev/null @@ -1,13 +0,0 @@ -# <模块名称> 异常态清单 - -| 场景 | 触发条件 | 前端表现 | 后端响应 | 验收 | 来源证据 | -| --- | --- | --- | --- | --- | --- | -| 权限不足 | 无权限操作敏感功能 | 按钮不可见或提示无权限 | 403 或业务拒绝 | 不完成操作 | | -| 记录不存在 | 传入错误 ID | 显示不存在 | 404 或业务错误 | 页面不崩溃 | | -| 非法状态流转 | `<状态A> -> <状态C>` 不在状态表 | 提示非法流转 | 状态不变 | 数据状态不变 | | -| 重复提交 | 连续点击提交或重复请求 | 按钮 loading/禁用 | 只处理一次 | 只生成一条有效审计 | | -| 参数缺失 | 必填原因、金额、范围或结论缺失 | 表单校验提示 | 参数错误 | 不改变业务数据 | | -| 并发修改 | 数据版本过期 | 提示刷新 | 拒绝覆盖或合并冲突 | 旧数据不覆盖新数据 | | -| 统计无数据 | 无匹配记录 | 空状态 | 返回 0 或空集合 | 页面不显示假数据 | | -| 审计日志为空 | 无审计记录 | 空状态 | 返回空集合 | 页面不报错 | | -| 下游服务失败 | 外部接口超时或失败 | 错误提示且可重试 | 失败响应可追踪 | 不写成功审计 | | 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 deleted file mode 100644 index 3dca924..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/异常态补齐.prompt.md +++ /dev/null @@ -1,31 +0,0 @@ -# 异常态补齐 Prompt - -```text -请基于目标业务模块，列出状态流转、分配/转交、删除/作废、查询详情、审计日志、统计看板相关的异常态和防御性逻辑。 - -输入材料： -- 模块名称：<填写> -- 业务对象：<填写> -- 角色与权限：<粘贴> -- 状态流转表：<粘贴> -- 接口契约或页面说明：<粘贴> - -输出表格： -场景 | 触发条件 | 前端表现 | 后端响应 | 用户提示 | 测试点 | 验收 - -必须覆盖： -- 权限不足 -- 记录不存在 -- 非法状态流转 -- 重复提交 -- 参数缺失 -- 并发修改 -- 统计无数据 -- 审计日志为空 -- 下游服务失败 - -约束： -- 先列异常态，不要直接改代码。 -- 给出每个异常态的验收步骤。 -- 标注事实、推断、建议和不确定点。 -``` 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 deleted file mode 100644 index e7bf421..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/权限上线前检查清单.md +++ /dev/null @@ -1,11 +0,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 deleted file mode 100644 index adbf43f..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/权限控制方案.template.md +++ /dev/null @@ -1,11 +0,0 @@ -# <模块名称> 权限控制方案 - -| 操作 | 前端入口 | 权限字符 | 后端接口 | 后端校验 | 数据权限 | 验收 | -| --- | --- | --- | --- | --- | --- | --- | -| 新增记录 | 新增按钮 | `::add` | `` | 权限注解或统一鉴权 | 通常无数据范围 | 无权限账号看不到按钮且直接请求失败 | -| 编辑记录 | 编辑按钮 | `::edit` | `` | 权限校验 + 状态校验 | 创建人/负责人/授权范围 | 越权账号返回 403 或业务拒绝 | -| 分配/转交 | 分配按钮 | `::assign` | `` | 权限校验 | 管理范围或当前授权范围 | 未授权角色无法分配给他人 | -| 状态流转 | 状态按钮 | `::transition` | `` | 权限校验 + 状态机校验 | 当前授权范围 | 非法流转失败且状态不变 | -| 删除/作废 | 删除或作废按钮 | `::delete` | `` | 权限校验 + 风险校验 | 管理范围 | 非授权角色返回 403 或业务拒绝 | -| 查看审计 | 审计页签 | `::audit` | `` | 权限校验 | 当前授权范围 | 无权限不可见且接口拒绝 | -| 统计看板 | 看板菜单 | `::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 deleted file mode 100644 index d568350..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/权限控制方案生成.prompt.md +++ /dev/null @@ -1,26 +0,0 @@ -# 权限控制方案生成 Prompt - -```text -请基于目标业务模块 RBAC 权限矩阵，生成权限控制方案。 - -输入材料： -- 模块名称：<填写> -- 业务对象：<填写> -- 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 deleted file mode 100644 index 759c879..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/状态流转检查清单.md +++ /dev/null @@ -1,11 +0,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 deleted file mode 100644 index 8a737e6..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/状态流转表.template.md +++ /dev/null @@ -1,21 +0,0 @@ -# <模块名称> 状态流转表 - -| 当前状态 | 动作 | 目标状态 | 允许角色 | 前置条件 | 后置动作 | 验收 | 来源证据 | -| --- | --- | --- | --- | --- | --- | --- | --- | -| 草稿/新建 | 提交 | 待处理/待审核 | 创建人/提交人 | 必填字段完整 | 写审计日志 | 状态变为目标状态 | | -| 待处理/待审核 | 分配/领取 | 处理中 | 管理员/负责人/处理人 | 处理人存在且有权限 | 写审计日志 | 处理人变化且状态正确 | | -| 处理中 | 提交结果 | 待确认/待复核 | 处理人/负责人 | 处理说明或结果不为空 | 写审计日志 | 状态变为待确认 | | -| 待确认/待复核 | 通过 | 已完成/已关闭 | 审核人/负责人 | 审核结论通过 | 写审计日志和完成时间 | 状态进入终态 | | -| 待确认/待复核 | 驳回 | 已驳回/待修改 | 审核人/负责人 | 驳回原因不为空 | 写审计日志 | 状态变为驳回态 | | -| 已驳回/待修改 | 重新提交 | 待处理/待审核 | 创建人/处理人 | 修改说明不为空 | 写审计日志 | 回到处理链路 | | -| 已完成/已关闭 | 重新打开 | 草稿/新建/处理中 | 管理员/负责人 | 重开原因不为空 | 写审计日志 | 状态按规则回退 | | - -## 非法流转清单 - -| 当前状态 | 尝试动作 | 问题 | 系统响应 | 验收 | -| --- | --- | --- | --- | --- | -| 已完成/已关闭 | 直接处理 | 终态不能直接进入处理中 | 返回非法流转 | 状态不变 | -| 草稿/新建 | 直接通过 | 未提交或未处理不能通过 | 返回非法流转 | 状态不变 | -| 待确认/待复核 | 重复提交结果 | 重复动作不应再次生效 | 返回非法流转或幂等结果 | 只保留原状态 | -| 处理中 | 直接通过 | 未进入确认/复核节点 | 返回非法流转 | 状态不变 | -| 已驳回/待修改 | 直接关闭 | 驳回后不能绕过修改或确认 | 返回非法流转 | 状态不变 | 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 deleted file mode 100644 index 683b298..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/状态流转设计.prompt.md +++ /dev/null @@ -1,33 +0,0 @@ -# 状态流转设计 Prompt - -```text -请为目标业务模块设计状态流转规则。 - -输入材料： -- 模块名称：<填写> -- 业务对象：<填写> -- 角色列表：<粘贴> -- 当前需求或已有状态枚举：<粘贴> -- 关键动作：<粘贴> - -可参考但必须按项目替换的状态类型： -- 草稿/新建 -- 待处理/待审核 -- 处理中 -- 待确认/待复核 -- 已完成/已关闭 -- 已驳回/待修改 - -输出要求： -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 deleted file mode 100644 index b732c20..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板指标口径检查清单.md +++ /dev/null @@ -1,13 +0,0 @@ -# 看板指标口径检查清单 - -| 检查项 | 通过标准 | 结果 | -| --- | --- | --- | -| 指标含义 | 每个指标有业务解释 | | -| 计算口径 | 每个指标有公式或筛选条件 | | -| 时间范围 | 明确按创建时间、关闭时间还是更新时间统计 | | -| 数据范围 | 不同角色的数据范围清楚 | | -| 空数据 | 空数据展示为 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 deleted file mode 100644 index 980755b..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板指标字典.template.md +++ /dev/null @@ -1,12 +0,0 @@ -# <模块名称> 看板指标字典 - -| 指标 | 含义 | 口径 | 数据来源 | 展示方式 | 权限 | 验收 | -| --- | --- | --- | --- | --- | --- | --- | -| 记录总数 | 当前筛选范围内业务记录数量 | count(target_id) | 主业务表 | 指标卡 | 看板权限 | 与列表同条件数量一致 | -| 未完成数量 | 状态不在终态集合内的数量 | status not in `` | 主业务表 | 指标卡 | 看板权限 | 过滤状态验证 | -| 平均完成周期 | 从开始时间到完成时间的平均耗时 | avg(completed_at - started_at) | 主业务表 | 指标卡/趋势 | 看板权限 | 抽样计算一致 | -| 按状态分布 | 各状态记录数量 | group by status | 主业务表/状态字典 | 饼图/柱状图 | 看板权限 | 分组总和等于总数 | -| 按类型分布 | 各业务类型数量 | group by type | 主业务表/字典 | 柱状图 | 看板权限 | 分组总和等于总数 | -| 趋势指标 | 按日期统计新增、完成或失败数量 | group by date_field | 主业务表 | 折线图 | 看板权限 | 日期范围正确 | -| 逾期数量 | 超过 SLA 且未完成的数量 | due_at < now and status not in `` | 主业务表 | 指标卡 | 看板权限 | SLA 口径明确 | -| 人员处理负载 | 按负责人/处理人统计未完成数量 | group by owner_id / assignee_id | 主业务表 | 排行榜 | 管理员/负责人 | 数据范围正确 | 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 deleted file mode 100644 index 80815d9..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板指标设计.prompt.md +++ /dev/null @@ -1,35 +0,0 @@ -# 看板指标设计 Prompt - -```text -请为目标业务模块设计业务看板指标。 - -输入材料： -- 模块名称：<填写> -- 业务对象：<填写> -- 角色与数据范围：<粘贴> -- 状态枚举与时间字段：<粘贴> -- 列表筛选条件：<粘贴> - -指标方向可参考： -- 记录总数 -- 未完成数量 -- 平均完成周期 -- 按状态分布 -- 按类型分布 -- 趋势指标 -- 逾期数量 -- 人员处理负载 - -输出要求： -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 deleted file mode 100644 index 4ba40fc..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板接口验收.prompt.md +++ /dev/null @@ -1,29 +0,0 @@ -# 看板接口验收 Prompt - -```text -请为目标业务模块看板统计接口生成验收记录。 - -输入材料： -- 模块名称：<填写> -- 业务对象：<填写> -- 看板指标字典：<粘贴> -- 看板接口契约：<粘贴> -- 权限矩阵：<粘贴> - -输出表格： -验收项 | 账号/条件 | 请求参数 | 预期 | 实际 | 证据 | 结论 - -必须覆盖： -- 有数据 -- 空数据 -- 无权限 -- 过滤条件 -- 指标口径 -- 时间范围 -- 数据范围 - -约束： -- 不要只说“接口正常”。 -- 每个指标至少有一个验收动作。 -- 每个验收动作都要说明账号/角色、请求参数、预期、实际和证据。 -``` 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 deleted file mode 100644 index d1f43b4..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板接口验收清单.md +++ /dev/null @@ -1,11 +0,0 @@ -# 看板接口验收清单 - -| 验收项 | 请求条件 | 通过标准 | 结果 | -| --- | --- | --- | --- | -| 默认查询 | 管理员或授权角色默认条件 | 返回完整指标 | | -| 时间过滤 | 指定 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 deleted file mode 100644 index 91cb3e0..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/design-complex-business-module/assets/看板接口验收记录.template.md +++ /dev/null @@ -1,10 +0,0 @@ -# <模块名称> 看板接口验收记录 - -| 验收项 | 账号/条件 | 请求参数 | 预期 | 实际 | 证据 | 结论 | -| --- | --- | --- | --- | --- | --- | --- | -| 记录总数 | 管理员或授权角色 | 默认筛选 | 返回总数 | | | | -| 空数据 | 授权角色 + 无匹配条件 | 不存在的日期范围或筛选条件 | 返回空集合或 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 deleted file mode 100644 index 27f43b1..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/SKILL.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -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 协作规则。以下约束来自配置文件和源码模式；未能由仓库证明的内容已标记为待确认。 -``` - -## 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 one project's 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 deleted file mode 100644 index 43f4885..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -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 deleted file mode 100644 index 2fc3a9f..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/assets/项目约束提取表.template.md +++ /dev/null @@ -1,43 +0,0 @@ -# 项目约束提取表 - -## 项目信息 - -| 字段 | 内容 | -| --- | --- | -| 项目名称 | | -| 项目路径 | | -| 提取日期 | | -| 提取人 | | -| 目标输出 | 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 deleted file mode 100644 index 7c25980..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/assets/项目约束生成.prompt.md +++ /dev/null @@ -1,61 +0,0 @@ -# 项目约束生成 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 deleted file mode 100644 index 78e13c6..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/generate-project-constraints/assets/项目约束验收清单.md +++ /dev/null @@ -1,44 +0,0 @@ -# 项目约束验收清单 - -## 基础完整性 - -- [ ] 已列出目标项目路径和输出路径。 -- [ ] 已说明是否发现显式规则文件。 -- [ ] 已记录缺失证据，没有因为缺失 README / CLAUDE.md / AGENTS.md 而停止。 -- [ ] 已区分 `硬约束`、`观察性约束`、`待确认约束`。 -- [ ] 每条硬约束都有明确来源路径。 -- [ ] 每条观察性约束至少有一个代表性源码样例。 -- [ ] 每条待确认约束都写明需要谁确认。 - -## 规则质量 - -- [ ] 规则包含适用场景。 -- [ ] 规则包含必须做什么。 -- [ ] 规则包含禁止做什么，或说明没有禁止项。 -- [ ] 规则包含验收方式。 -- [ ] 规则包含迁移说明，说明换项目时能否复用。 -- [ ] 规则没有把通用最佳实践冒充为项目事实。 -- [ ] 规则没有把某个单一代码样例冒充为全项目硬约束。 - -## 覆盖范围 - -- [ ] global 约束覆盖项目理解、证据引用、事实/推断区分。 -- [ ] frontend 约束覆盖包管理器、框架、路径别名、API 层、路由和状态管理。 -- [ ] backend 约束覆盖语言版本、框架、分层、响应结构、异常和数据访问。 -- [ ] security 约束覆盖认证、权限、敏感信息、数据范围和接口防护。 -- [ ] testing 约束覆盖已有测试工具、运行命令和缺失测试时的处理。 -- [ ] delivery 约束覆盖计划、Review、验收记录、发布或交付要求。 - -## 可复用性 - -- [ ] 某个项目特有规则没有写进通用规则。 -- [ ] 每条规则都标注了“可直接复用 / 需重新扫描 / 不可迁移”。 -- [ ] 换项目时必须重新扫描的内容已经列出。 -- [ ] 可以从本清单反推出生成步骤。 - -## 交付检查 - -- [ ] 生成文件中没有未完成占位符、示例假名或空标题。 -- [ ] 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 deleted file mode 100644 index 916473a..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/SKILL.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -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 deleted file mode 100644 index f2dc7c9..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -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 deleted file mode 100644 index 0fe0982..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/AIReview报告模板.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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 deleted file mode 100644 index cea4742..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/业务交付验收清单.md +++ /dev/null @@ -1,59 +0,0 @@ -# 业务交付验收清单 - -本清单用于判断复杂业务模块是否达到可验收状态，适用于后台管理、审批流、运营系统、CRM、低代码二开和数据看板等项目。 - -## 项目理解 - -| 检查项 | 通过标准 | 结果 | -| --- | --- | --- | -| 能说明模块边界 | 说明模块负责什么、不负责什么 | | -| 能定位关键目录 | 能指出前端页面、API 层、后端入口、服务层和数据层位置 | | -| 能区分事实和推断 | 对没有源码依据的业务规则标注为推断或待确认 | | -| 能记录不确定点 | 不确定内容没有被包装成确定事实 | | - -## 需求与接口 - -| 检查项 | 通过标准 | 结果 | -| --- | --- | --- | -| 用户故事完整 | 覆盖主要角色、关键动作和限制条件 | | -| 非目标范围明确 | 明确本次不做的能力、数据迁移、生产部署或外部集成 | | -| 接口契约完整 | 覆盖列表、详情、新增、编辑、分配、状态、审计和看板 | | -| 失败场景明确 | 每个关键接口至少有权限、参数、状态或数据不存在失败场景 | | -| 验收方式明确 | 每个关键需求都有可执行检查方法 | | - -## 权限与状态 - -| 检查项 | 通过标准 | 结果 | -| --- | --- | --- | -| 权限矩阵完整 | 覆盖页面级、按钮级、接口级和数据范围 | | -| 权限字符合理 | 命名统一，并标注为建议或源码事实 | | -| 后端权限未缺失 | 没有用前端按钮隐藏替代后端接口控制 | | -| 状态流转表完整 | 覆盖初始态、处理中、确认/审核态、终态和驳回态 | | -| 非法流转明确 | 列出关键非法流转、拒绝原因和验收方式 | | - -## 审计、异常态与看板 - -| 检查项 | 通过标准 | 结果 | -| --- | --- | --- | -| 审计操作覆盖关键动作 | 创建、编辑、分配、状态流转、关闭/归档等关键动作被覆盖 | | -| 审计字段可追溯 | 包含 actor、action、targetId、oldValue、newValue、source | | -| 敏感信息处理 | oldValue/newValue 有脱敏说明 | | -| 异常态可测试 | 权限不足、重复提交、非法状态、数据不存在、并发修改均覆盖 | | -| 看板指标可计算 | 每个指标有口径、维度、过滤条件和数据来源建议 | | - -## Review 与交付 - -| 检查项 | 通过标准 | 结果 | -| --- | --- | --- | -| Review 有证据 | 问题能回到路径、表格、接口、角色或业务规则 | | -| 风险按严重程度排序 | 高风险问题优先展示 | | -| 建议可行动 | 每条建议有修复方向和验收方式 | | -| 交付物齐全 | 设计表、Review 报告、验证记录和未闭环事项完整 | | -| 能沉淀资产 | 高频问题能转成规则、检查清单、Prompt、反例或 Skill | | - -## 判定原则 - -- 优先看证据，不优先看文字是否漂亮。 -- 优先看权限、状态、审计、异常态，不只看 CRUD。 -- 优先看不确定点是否被诚实标出。 -- 优先看结论能否被角色账号、接口请求、样例数据或浏览器操作验证。 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 deleted file mode 100644 index 1eebc8f..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/审计日志检查清单.md +++ /dev/null @@ -1,12 +0,0 @@ -# 审计日志检查清单 - -| 检查项 | 通过标准 | 结果 | -| --- | --- | --- | -| 创建记录 | 创建业务记录后能查询审计记录 | | -| 字段变更 | 编辑关键字段记录 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 deleted file mode 100644 index d53299c..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/异常态检查清单.md +++ /dev/null @@ -1,12 +0,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 deleted file mode 100644 index e7bf421..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/权限上线前检查清单.md +++ /dev/null @@ -1,11 +0,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 deleted file mode 100644 index 759c879..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/状态流转检查清单.md +++ /dev/null @@ -1,11 +0,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 deleted file mode 100644 index b732c20..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/看板指标口径检查清单.md +++ /dev/null @@ -1,13 +0,0 @@ -# 看板指标口径检查清单 - -| 检查项 | 通过标准 | 结果 | -| --- | --- | --- | -| 指标含义 | 每个指标有业务解释 | | -| 计算口径 | 每个指标有公式或筛选条件 | | -| 时间范围 | 明确按创建时间、关闭时间还是更新时间统计 | | -| 数据范围 | 不同角色的数据范围清楚 | | -| 空数据 | 空数据展示为 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 deleted file mode 100644 index d1f43b4..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/看板接口验收清单.md +++ /dev/null @@ -1,11 +0,0 @@ -# 看板接口验收清单 - -| 验收项 | 请求条件 | 通过标准 | 结果 | -| --- | --- | --- | --- | -| 默认查询 | 管理员或授权角色默认条件 | 返回完整指标 | | -| 时间过滤 | 指定 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 deleted file mode 100644 index 57a6da6..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/阶段Review.prompt.md +++ /dev/null @@ -1,32 +0,0 @@ -# 阶段 Review Prompt - -```text -请对目标业务模块阶段交付物做 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 deleted file mode 100644 index 5a56f75..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/review-business-delivery/assets/阶段Review报告.template.md +++ /dev/null @@ -1,27 +0,0 @@ -# 阶段 Review 报告 - -## Review 输入 - -- RBAC 权限矩阵： -- 权限控制方案： -- 状态流转表： -- 非法流转清单： -- 审计日志 SOP： -- 异常态清单： -- 看板指标字典： -- 看板接口验收记录： - -## 问题清单 - -| 等级 | 模块 | 问题 | 触发规则 | 风险 | 修复建议 | 验收 | -| --- | --- | --- | --- | --- | --- | --- | -| P1 | 权限 | 敏感操作只做前端按钮隐藏，后端缺少权限校验 | 前端按钮不是安全边界 | 可绕过前端直接调用接口完成高风险操作 | 后端补权限校验和数据范围校验 | 无权限账号直接请求返回 403 或业务拒绝 | - -## 不确定点 - -| 不确定点 | 影响 | 需要谁确认 | -| --- | --- | --- | - -## 结论 - -通过 / 有条件通过 / 不通过 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 deleted file mode 100644 index 67b0c6c..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/SKILL.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -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 deleted file mode 100644 index 500b19a..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -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 deleted file mode 100644 index 39df455..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/Review修复闭环检查清单.md +++ /dev/null @@ -1,12 +0,0 @@ -# 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 deleted file mode 100644 index b98ac20..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/修复记录.template.md +++ /dev/null @@ -1,7 +0,0 @@ -# Review 修复记录 - -| Review 编号 | 问题 | 是否成立 | 修改文件 | 修改说明 | 验证结果 | 资产沉淀 | -| --- | --- | --- | --- | --- | --- | --- | -| R01 | 敏感操作接口缺少后端权限校验 | 是 | `` | 增加权限校验和数据范围校验 | 无权限请求被拒绝 | 权限检查清单 | -| R02 | 终态记录可被直接改回处理中 | 是 | `` | 补非法流转校验 | terminal -> 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 deleted file mode 100644 index 24fcfe7..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/修复记录生成.prompt.md +++ /dev/null @@ -1,24 +0,0 @@ -# 修复记录生成 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 deleted file mode 100644 index f3982b1..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/审计日志缺失反例.md +++ /dev/null @@ -1,31 +0,0 @@ -# 审计日志缺失反例 - -## 场景 - -业务记录分配处理人成功，但没有记录审计日志。 - -## 问题表现 - -| 操作 | 结果 | -| --- | --- | -| 张三将记录分配给李四 | 处理人变更成功 | -| 查询审计日志 | 没有处理人变更记录 | - -## 风险 - -无法追溯处理人变化，出现延误或争议时无法定位责任。 - -## 修复要求 - -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 deleted file mode 100644 index d1406a1..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/权限遗漏反例.md +++ /dev/null @@ -1,32 +0,0 @@ -# 权限遗漏反例 - -## 场景 - -敏感删除或作废按钮在前端按权限隐藏，但后端接口没有权限校验。 - -## 问题代码表现 - -| 层级 | 表现 | -| --- | --- | -| 前端 | 普通业务账号看不到删除按钮 | -| 后端 | 直接请求删除或作废接口仍可成功 | -| 审计 | 删除记录可能缺失 | - -## 风险 - -攻击者或误操作用户可以绕过前端直接调用接口删除或作废业务数据。 - -## 修复要求 - -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 deleted file mode 100644 index d636fcc..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/看板指标口径不清反例.md +++ /dev/null @@ -1,30 +0,0 @@ -# 看板指标口径不清反例 - -## 场景 - -看板展示“平均完成周期”，但没有说明从哪个时间到哪个时间。 - -## 问题表现 - -| 指标 | 当前说明 | -| --- | --- | -| 平均完成周期 | 最近记录平均处理时间 | - -## 风险 - -不同人理解不同：可能是创建到完成，也可能是开始处理到完成，导致管理判断失真。 - -## 修复要求 - -1. 明确定义为 `completed_at - created_at`、`closed_at - created_at` 或其他确定口径。 -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 deleted file mode 100644 index 0606610..0000000 --- a/deliverables/ai-engineering-skills-delivery/skills/track-review-fix-loop/assets/非法状态流转反例.md +++ /dev/null @@ -1,30 +0,0 @@ -# 非法状态流转反例 - -## 场景 - -已完成或已关闭的业务记录可以直接被改回处理中。 - -## 问题表现 - -| 当前状态 | 动作 | 结果 | -| --- | --- | --- | -| 已关闭 | 开始处理 | 状态变成处理中 | - -## 风险 - -终态记录被重新打开但没有重开原因、没有审计、没有负责人确认，导致统计和责任链失真。 - -## 修复要求 - -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 index 541ff94..53e9812 100644 Binary files a/deliverables/客户AI工程Skill交付包.zip and b/deliverables/客户AI工程Skill交付包.zip differ diff --git a/deliverables/客户AI工程Skill交付包/README.md b/deliverables/客户AI工程Skill交付包/README.md index b5ff6e0..925175c 100644 --- a/deliverables/客户AI工程Skill交付包/README.md +++ b/deliverables/客户AI工程Skill交付包/README.md @@ -1,8 +1,8 @@ -# 客户 AI 工程 Skill 交付包 +# 客户 AI 工程资产交付包 -本交付包提供 4 个可复用 AI 工程 Skill，覆盖真实项目中从项目约束生成、复杂业务设计、交付 Review 到修复闭环的完整流程。 +本包是第五、六天课程配套的正式资产交付物，用于把 AI 编程中的项目理解、约束提取、复杂业务设计、交付 Review 和修复闭环沉淀为可维护的团队资产。 -这些 Skill 不是单次 Prompt，而是可安装、可复制、可随项目持续维护的团队资产。 +它不包含客户代码、服务地址、账号、令牌、真实业务数据或未经验证的项目结论。所有业务字段、权限码、接口和状态均以占位符表达，使用时必须从目标项目重新取证。 ## 交付内容 @@ -10,37 +10,46 @@ 客户AI工程Skill交付包/ ├── README.md ├── 安装说明.md +├── 交付清单.md ├── skills/ -│ ├── generate-project-constraints/ -│ ├── design-complex-business-module/ -│ ├── review-business-delivery/ -│ └── track-review-fix-loop/ +│ ├── generate-project-constraints/ # 提取项目规则与约束 +│ ├── project-knowledge-builder/ # 建立源码依据的项目知识库 +│ ├── design-complex-business-module/ # 设计权限、状态、审计、异常态和指标 +│ ├── review-business-delivery/ # 审查业务交付与变更风险 +│ └── track-review-fix-loop/ # 跟踪 Review 修复与验证闭环 +├── mcp-assets/ +│ ├── MCP能力契约.template.md +│ └── MCP工具权限与验收清单.md └── examples/ - └── jeecgboot-work-order/ + └── jeecgboot-official-vehicle/ + └── 公务用车取消派车案例.md ``` ## Skill 列表 -| Skill | 用途 | 典型产物 | -| -------------------------------- | ------------------------------------------------ | --------------------------------------------- | -| `generate-project-constraints` | 从项目源码、配置、CI、文档中提取项目约束 | rules、约束提取表、验收清单 | -| `design-complex-business-module` | 设计复杂业务模块的权限、状态、审计、异常态和看板 | RBAC 矩阵、状态流转表、审计 SOP、看板指标字典 | -| `review-business-delivery` | 审查复杂业务交付物或 PR 的业务风险 | 阶段 Review 报告、风险清单、验收建议 | -| `track-review-fix-loop` | 跟踪 Review 问题修复、验证和资产沉淀 | 修复记录、未闭环清单、资产更新建议 | +| Skill | 解决的问题 | 典型产物 | +|---|---|---| +| `generate-project-constraints` | 从源码、配置、测试和 CI 中提取项目约束 | Rule、约束提取表、验收清单 | +| `project-knowledge-builder` | 建立可追溯、可持续更新的项目知识库 | 项目地图、接口与权限索引、维护指南 | +| `design-complex-business-module` | 设计高风险业务模块的工程边界 | 权限矩阵、状态流转表、审计 SOP、指标字典 | +| `review-business-delivery` | 审查设计、代码或 PR 的业务风险 | Review 报告、风险清单、验收建议 | +| `track-review-fix-loop` | 跟踪问题修复、验证和资产更新 | 修复记录、未闭环清单、资产更新建议 | -## 推荐使用顺序 +## MCP 资产 -1. 使用 `generate-project-constraints` 为项目生成项目规则。 -2. 使用 `design-complex-business-module` 生成复杂业务设计资产。 -3. 使用 `review-business-delivery` 审查设计、代码或阶段交付物。 -4. 使用 `track-review-fix-loop` 跟踪修复、验证结果和资产沉淀。 +`mcp-assets/` 只提供能力契约和验收清单，不预置任何 MCP 服务地址、工具配置或凭据。接入外部能力前，必须明确输入输出、数据范围、权限、副作用、失败降级和验证夹具；写入、删除、发布和外发能力不应作为通用 Agent 的默认权限。 -## 适用项目 +## 公务用车案例 -适用于后台管理系统、低代码平台二开、CRM、工单、审批、运营系统、数据看板等企业业务项目。 +`examples/jeecgboot-official-vehicle/` 是基于现有 JeecgBoot 公务用车模块的单人训练案例。它展示如何把“取消派车时取消原因不能为空”的训练改造，转成源码依据、最小改动边界、验证证据和待确认项。 -这些 Skill 不要求项目必须有 `CLAUDE.md`、`AGENTS.md` 或 `README.md`。如果项目没有显式说明文档，Skill 会从配置、源码模式、测试和 CI 中提取约束，并把无法证明的内容标记为待确认。 +该案例只说明已读取到的项目事实与已执行验证，不代表客户已提出相同业务需求，也不能直接替代目标项目的重新取证。 -## 示例说明 +## 使用边界 -`examples/jeecgboot-work-order/` 提供 JeecgBoot 工单案例参考，帮助理解这些 Skill 在真实后台项目中的使用方式。该示例不是通用 Skill 安装项。 +- Skill 保存可复用的判断流程，不保存某个项目的路径、字段、接口或权限码。 +- Rule、任务上下文契约、检查单、模板、Skill、Agent 和 MCP 职责不同，应保持单一权威位置。 +- 任何没有源码、日志、测试或明确规范支持的结论，都要标记为待确认。 +- 资产变更应检查行为变化、引用完整性、兼容性、迁移与回退，并使用完整、缺失、冲突和越界输入夹具复核。 + +安装与团队使用方式见 [安装说明.md](./安装说明.md)，本次正式交付范围见 [交付清单.md](./交付清单.md)。 diff --git a/deliverables/客户AI工程Skill交付包/examples/jeecgboot-official-vehicle/公务用车取消派车案例.md b/deliverables/客户AI工程Skill交付包/examples/jeecgboot-official-vehicle/公务用车取消派车案例.md new file mode 100644 index 0000000..30404a0 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/examples/jeecgboot-official-vehicle/公务用车取消派车案例.md @@ -0,0 +1,48 @@ +# 公务用车取消派车：影响分析与验证案例 + +## 案例边界 + +本案例来自当前 JeecgBoot 已接入的公务用车模块，用于单人练习“先取证、再限制改动范围、最后如实记录验证”的工作方式。 + +训练改造目标：取消已派车任务时，后端必须拒绝空值和全空白的取消原因。前端表单必填只用于减少误操作，不能替代 Service 入口的业务保护。 + +本案例不代表客户已提出相同需求；其他项目必须重新读取自身源码、配置和测试材料。 + +## 已确认的项目事实 + +| 维度 | 已读取依据 | 结论 | +|---|---|---| +| 前端入口 | `jeecgboot-vue3/src/views/official/vehicle/dispatch/DispatchList.vue`、`DispatchModal.vue`、`dispatch.data.ts` | 仅在有取消权限且派车状态为 `DISPATCHED` 时显示取消操作；弹窗已配置取消原因必填。 | +| 前端 API | `jeecgboot-vue3/src/api/official/vehicle/dispatch.ts` | 页面外仍可直接调用取消接口，因此前端必填不是最终保护。 | +| 后端入口 | `OfficialVehicleDispatchController.java`、`OfficialVehicleDispatchServiceImpl.java` | Controller 负责权限与请求转交；Service 负责状态写入和车辆状态释放。 | +| 取消参数 | `OfficialVehicleCancelDispatchVo.java` | 请求体包含派车 ID 与取消原因，原有参数对象未限制空白文本。 | +| 测试基座 | `OfficialVehicleDispatchControllerTest.java`、模块 `pom.xml` | 模块具备 JUnit 测试基础，原用例未覆盖空白取消原因。 | + +## 可直接复用的任务上下文契约 + +```text +请基于当前打开的项目，且只基于实际读取到的源码，完成一次变更影响分析；不要修改代码，不要猜测项目外逻辑。 + +训练目标：取消已派车任务时，取消原因必须为非空文本；前端必填不能替代后端业务保护。 + +请读取前端页面、前端 API、后端 Controller、Service、参数对象、实体、现有测试、模块构建配置和必要数据库脚本。 + +请输出：已读取源码；已确认事实及文件依据；必须检查的模块；接口、数据、权限、状态、配置和测试影响；明确不改动项；不超过四步的最小改动计划；人工待确认项。 + +要求：事实与推测分开；没有源码或验证证据时标记待确认；不编造测试结果；不直接实施修改。 +``` + +## 实际改动与证据 + +| 项目 | 记录 | +|---|---| +| 最小改动 | 在 `OfficialVehicleDispatchServiceImpl.cancel` 的状态写入前加入取消原因非空校验。 | +| 对应测试 | 新增 Service 定向测试，传入全空白取消原因并断言请求被拒绝。 | +| 已执行验证 | Maven 定向测试已执行成功，定向 Service 测试通过。 | +| 保持不变 | 前端必填、既有取消权限、审计注解、车辆状态释放逻辑和数据库表结构未修改。 | + +## 结论边界 + +下列事项没有被本案例写成“已通过”：实际数据库中非空取消原因的正常取消回归、HTTP 响应映射、浏览器提示、审计记录和车辆状态的集成环境验证。 + +这正是本案例的核心要求：已有证据支持多大的结论，就只形成多大的结论。 diff --git a/deliverables/客户AI工程Skill交付包/examples/jeecgboot-work-order/JeecgBoot工单模块开发审查.skill.md b/deliverables/客户AI工程Skill交付包/examples/jeecgboot-work-order/JeecgBoot工单模块开发审查.skill.md deleted file mode 100644 index 4bc5f74..0000000 --- a/deliverables/客户AI工程Skill交付包/examples/jeecgboot-work-order/JeecgBoot工单模块开发审查.skill.md +++ /dev/null @@ -1,44 +0,0 @@ -# JeecgBoot 工单模块开发审查 Skill - -## 触发场景 - -涉及工单列表、详情、评论、状态、指派、看板、权限字符、数据权限、操作日志的需求拆解、代码生成或代码修改。 - -## 输入材料 - -- PR diff 或相关文件。 -- 工单需求说明。 -- 数据模型与接口契约。 -- 当前 rules。 -- 前端页面文件。 -- API 模块文件。 -- 后端 Controller / Service。 -- 权限矩阵。 -- 状态流转表。 -- 审计日志 SOP。 - -## 执行步骤 - -1. 识别需求范围和非目标范围。 -2. 检查字段、接口契约和页面状态是否完整。 -3. 审查 JeecgBoot 生成代码的字段、查询、分页、字典和异常态。 -4. 检查新增、编辑、删除、指派、状态变更的前端按钮与后端权限。 -5. 检查操作日志、数据权限和测试缺口。 -6. 检查看板指标口径和接口验收记录。 -7. 输出风险、不确定点和验收建议。 - -## 输出格式 - -- 需求范围确认。 -- 接口契约问题表。 -- 代码生成 Review 清单。 -- 权限风险表。 -- 状态流转风险表。 -- 审计日志风险表。 -- 测试缺口清单。 -- 不确定点清单。 - -## 验收标准 - -每个关键结论必须标注文件、函数、注解、配置或调用链依据。每条建议必须有验收方式。 - diff --git a/deliverables/客户AI工程Skill交付包/mcp-assets/MCP工具权限与验收清单.md b/deliverables/客户AI工程Skill交付包/mcp-assets/MCP工具权限与验收清单.md new file mode 100644 index 0000000..45cc916 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/mcp-assets/MCP工具权限与验收清单.md @@ -0,0 +1,33 @@ +# MCP 工具权限与验收清单 + +## 接入前 + +- [ ] 已确认该能力确实需要 MCP，而非 CLI、Rule、任务上下文契约 或 Skill。 +- [ ] 每个工具都有用途、输入、输出、副作用和错误语义说明。 +- [ ] 已确认数据范围、鉴权、审计和脱敏要求。 +- [ ] 未将密钥、Token、账号、完整个人信息或内部地址写入配置、示例或日志。 +- [ ] 已明确只读、可逆写入和不可逆操作，未根据工具名称猜测性质。 + +## Agent 授权 + +- [ ] 每个自定义 Agent 只绑定完成职责所需的 MCP 工具。 +- [ ] 读取受限信息时，调用身份和数据范围可被 MCP 服务校验。 +- [ ] 写入、删除、发布和外发操作不属于通用 Agent 默认权限。 +- [ ] 有副作用操作具备二次确认、幂等或明确的重复调用处理。 +- [ ] Agent 在 MCP 失败时输出“外部事实未取得”，不编造结果。 + +## 验收夹具 + +- [ ] 合法完整请求：返回结构、来源时间和范围符合契约。 +- [ ] 缺少必填参数：拒绝并指出缺口。 +- [ ] 越权请求：拒绝或触发确认，不泄露超范围数据。 +- [ ] 鉴权失败、限流、超时和服务错误：错误类型可区分。 +- [ ] 返回空结果：与工具故障明确区分。 +- [ ] 敏感字段：按契约脱敏，审计日志不暴露秘密信息。 +- [ ] 重复调用：符合幂等设计或被安全阻止。 + +## 结论 + +- [ ] 可接入：契约、权限、审计、失败处理和验收夹具完整。 +- [ ] 待确认：记录缺失的外部规范或验证材料。 +- [ ] 不接入：说明改用 CLI、Skill 或人工流程的原因。 diff --git a/deliverables/客户AI工程Skill交付包/mcp-assets/MCP能力契约.template.md b/deliverables/客户AI工程Skill交付包/mcp-assets/MCP能力契约.template.md new file mode 100644 index 0000000..71336cb --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/mcp-assets/MCP能力契约.template.md @@ -0,0 +1,34 @@ +# MCP 能力契约 + +## 基本信息 + +| 字段 | 内容 | +|---|---| +| 服务名称 | `<名称>` | +| 接入目的 | `<要解决的外部事实或操作>` | +| 适用场景 | `<何时允许使用>` | +| 不适用场景 | `<何时不得使用>` | +| 来源依据 | `<接口文档、系统规范或已验证记录>` | + +## 工具清单 + +| 工具 | 用途 | 输入契约 | 输出契约 | 副作用 | 权限与确认 | 错误语义 | 审计与脱敏 | +|---|---|---|---|---|---|---|---| +| `` | `<用途>` | `<必填、格式、范围>` | `<字段、时效、空值>` | `只读 / 可逆写入 / 不可逆` | `<调用资格与确认>` | `<鉴权、限流、超时等>` | `<留痕字段与脱敏规则>` | + +## Agent 绑定边界 + +- 允许调用的自定义 Agent：`<名称或角色>`。 +- 不允许调用的 Agent：`<名称或角色>`。 +- Agent 调用前必须具备的运行时事实：`<数据范围、目标对象、确认信息>`。 +- Agent 调用后必须输出：`<来源、时间、结果、失败或待确认>`。 + +## 停止与降级 + +| 情况 | MCP 或 Agent 的行为 | +|---|---| +| 缺少关键输入 | 拒绝调用并列出字段缺口 | +| 鉴权或数据范围不满足 | 拒绝调用，不尝试扩大权限 | +| 限流、超时或服务不可用 | 区分故障类型，标记外部事实未取得 | +| 有副作用但未确认 | 停止并请求确认 | +| 返回敏感信息 | 按规则脱敏，避免写入任务记录或日志 | diff --git a/deliverables/客户AI工程Skill交付包/mcp-assets/README.md b/deliverables/客户AI工程Skill交付包/mcp-assets/README.md new file mode 100644 index 0000000..bc7c86c --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/mcp-assets/README.md @@ -0,0 +1,29 @@ +# MCP 能力资产包 + +本目录用于沉淀可被 Agent 调用的外部能力边界，不保存任何服务地址、访问令牌、账号、内部域名或业务数据。 + +## 何时使用 + +- 需要跨系统读取经授权的事实、日志或文档。 +- 需要调用具有结构化输入输出的外部工具。 +- 需要将浏览器、数据库、内部平台或其他服务能力提供给 Agent。 + +## 不适用场景 + +- 已有稳定命令且不需要交互式工具调用的任务，优先使用 CLI。 +- 只有知识、流程、模板或检查清单的任务，优先沉淀为 Rule、任务上下文契约或 Skill。 +- 未确认数据范围、鉴权方式、审计要求或副作用的外部服务。 + +## 使用顺序 + +1. 使用 `MCP能力契约.template.md` 描述每个拟接入的服务与工具。 +2. 使用 `MCP工具权限与验收清单.md` 审查权限、敏感数据、错误和副作用。 +3. 为完整请求、缺参、越权、故障和脱敏结果准备验证夹具。 +4. 只有契约与验收都满足时，才将对应工具分配给自定义 Agent 或 Skill。 + +## 基本原则 + +- 不根据工具名称推断只读或安全性。 +- 外部工具失败时，结论必须标记为“外部事实未取得”。 +- 写入、删除、发布和外发能力不应作为通用 Agent 的默认权限。 +- 日志、示例和夹具不得包含密钥、Token、账号、完整个人信息或内部地址。 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 index 1885beb..b7bfb1b 100644 --- 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 @@ -1,16 +1,16 @@ -# 工单 RBAC 权限矩阵 +# 业务对象 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 | | +| 查看列表 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | :list | 按数据范围 | +| 查看详情 | 允许 | 条件允许 | 条件允许 | 条件允许 | 条件允许 | :query | 仅可见范围 | +| 新建业务对象 | 允许 | 允许 | 允许 | 允许 | 拒绝 | :add | | +| 编辑业务对象 | 允许 | 条件允许 | 条件允许 | 拒绝 | 拒绝 | :edit | 状态限制 | +| 指派负责人 | 允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | :assign | | +| 状态流转 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | :transition | 按状态 | +| 关闭业务对象 | 允许 | 条件允许 | 拒绝 | 条件允许 | 拒绝 | :close | 测试验证后 | +| 删除业务对象 | 允许 | 拒绝 | 拒绝 | 拒绝 | 拒绝 | :delete | 高危操作 | +| 查看审计日志 | 允许 | 条件允许 | 条件允许 | 条件允许 | 拒绝 | :audit | | +| 查看看板 | 允许 | 允许 | 条件允许 | 条件允许 | 条件允许 | :dashboard | 按数据范围 | +| 导出数据 | 允许 | 条件允许 | 拒绝 | 拒绝 | 拒绝 | :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 index 84a9100..4856c49 100644 --- 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 @@ -1,11 +1,11 @@ -# RBAC 权限矩阵生成 Prompt +# RBAC 权限矩阵生成 任务上下文契约 ```text -请基于 JeecgBoot 工单模块设计 RBAC 权限矩阵。 +请基于 目标业务模块设计 RBAC 权限矩阵。 输入材料： -- 工单模块需求：<粘贴需求> -- 角色列表：管理员、工单负责人、研发处理人、测试验证人、只读观察者 +- 业务模块需求：<粘贴需求> +- 角色列表：管理员、业务对象负责人、研发处理人、测试验证人、只读观察者 - 功能点：查看列表、查看详情、新建、编辑、指派、状态流转、关闭、删除、查看审计、查看看板、导出 - 项目依据：<粘贴权限、路由、菜单相关路径> 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 index 876d692..6f27039 100644 --- 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 @@ -1,14 +1,14 @@ -# 工单审计日志 SOP +# 业务对象审计日志 SOP ## 记录原则 -所有会改变工单关键业务状态、负责人、可见性或结论的动作都必须记录审计日志。 +所有会改变业务对象关键业务状态、负责人、可见性或结论的动作都必须记录审计日志。 ## 审计字段 | 字段 | 含义 | 示例 | | --- | --- | --- | -| ticket_id | 工单 ID | WO-001 | +| | 业务对象 ID | <业务编号> | | actor_id | 操作人 ID | 1001 | | actor_name | 操作人名称 | zhangsan | | action | 操作类型 | ASSIGN | @@ -23,12 +23,12 @@ | 动作 | 写入时机 | oldValue | newValue | 验收 | | --- | --- | --- | --- | --- | -| 创建工单 | 创建成功后 | 空 | 工单摘要 | 审计列表可见 | +| 创建业务对象 | 创建成功后 | 空 | 业务对象摘要 | 审计列表可见 | | 编辑字段 | 保存成功后 | 修改前字段 | 修改后字段 | 字段前后值正确 | | 指派负责人 | 指派成功后 | 原负责人 | 新负责人 | 审计记录负责人变化 | | 状态流转 | 状态变更成功后 | 原状态 | 新状态 | 审计记录状态变化 | | 评论新增 | 评论保存后 | 空 | 评论摘要 | 审计记录评论动作 | -| 关闭工单 | 关闭成功后 | 原状态 | 已关闭 | 审计记录关闭时间 | +| 关闭业务对象 | 关闭成功后 | 原状态 | 已关闭 | 审计记录关闭时间 | ## 验收方式 diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/审计日志检查清单.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/审计日志检查清单.md index 0e271a4..093e3bd 100644 --- a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/审计日志检查清单.md +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/审计日志检查清单.md @@ -2,7 +2,7 @@ | 检查项 | 通过标准 | 结果 | | --- | --- | --- | -| 创建记录 | 创建工单后能查询审计记录 | | +| 创建记录 | 创建业务对象后能查询审计记录 | | | 字段变更 | 编辑关键字段记录 oldValue/newValue | | | 指派记录 | 指派负责人记录原负责人和新负责人 | | | 状态记录 | 状态流转记录原状态和新状态 | | diff --git a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态检查清单.md b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态检查清单.md index e1b6496..74442ae 100644 --- a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态检查清单.md +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态检查清单.md @@ -3,7 +3,7 @@ | 异常态 | 必须验证 | 结果 | | --- | --- | --- | | 空列表 | 页面显示空状态，不报错 | | -| 详情不存在 | 提示工单不存在，页面不崩溃 | | +| 详情不存在 | 提示业务对象不存在，页面不崩溃 | | | 权限不足 | 前端提示或隐藏，后端拒绝 | | | 非法状态 | 返回非法流转，状态不变 | | | 重复提交 | 只成功一次，只写一条有效审计 | | 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 index 286eaff..9e4d2fd 100644 --- a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态清单.template.md +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态清单.template.md @@ -1,9 +1,9 @@ -# 工单异常态清单 +# 业务对象异常态清单 | 场景 | 触发条件 | 前端表现 | 后端响应 | 验收 | | --- | --- | --- | --- | --- | | 权限不足 | 无权限操作 | 按钮不可见或提示无权限 | 403 或业务拒绝 | 不完成操作 | -| 工单不存在 | 传入错误 ID | 显示不存在 | 404 或业务错误 | 页面不崩溃 | +| 业务对象不存在 | 传入错误 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 index 17bd793..cd63f5b 100644 --- a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态补齐.prompt.md +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/异常态补齐.prompt.md @@ -1,14 +1,14 @@ -# 异常态补齐 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 index cacf893..c99b571 100644 --- a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/权限上线前检查清单.md +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/权限上线前检查清单.md @@ -2,10 +2,10 @@ | 检查项 | 通过标准 | 结果 | | --- | --- | --- | -| 菜单权限 | 工单菜单只对授权角色可见 | | +| 菜单权限 | 业务对象菜单只对授权角色可见 | | | 按钮权限 | 新增、编辑、删除、指派、状态按钮按权限显示 | | | 接口权限 | 无权限账号直接请求敏感接口失败 | | -| 数据权限 | 普通用户只能看到授权范围内工单 | | +| 数据权限 | 普通用户只能看到授权范围内业务对象 | | | 权限字符 | 前端按钮、菜单配置、后端接口命名一致 | | | 审计 | 权限敏感操作成功后有审计记录 | | | 反例验证 | 无权限账号不能绕过前端执行删除/指派 | | 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 index d7d0910..158b452 100644 --- a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/权限控制方案.template.md +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/权限控制方案.template.md @@ -1,12 +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 | 权限注解 | 数据范围过滤 | 不同角色数据范围不同 | +| 新增业务对象 | 新增按钮 | :add | //add | 权限注解 | 无 | 无权限账号看不到按钮且直接请求失败 | +| 编辑业务对象 | 编辑按钮 | :edit | //edit | 权限注解 + 状态校验 | 负责人/创建人范围 | 越权账号返回 403 或业务拒绝 | +| 指派负责人 | 指派按钮 | :assign | //assign | 权限注解 | 管理员/负责人范围 | 普通研发无法指派他人 | +| 状态流转 | 状态按钮 | :transition | //transition | 权限注解 + 状态机校验 | 相关业务对象范围 | 非法流转失败 | +| 删除业务对象 | 删除按钮 | :delete | //delete | 权限注解 | 管理员范围 | 非管理员返回 403 | +| 查看审计 | 审计页签 | :audit | //audit/list | 权限注解 | 相关业务对象范围 | 无权限不可见且接口拒绝 | +| 看板 | 看板菜单 | :dashboard | //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 index 7dcf834..23dc4f7 100644 --- a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/权限控制方案生成.prompt.md +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/权限控制方案生成.prompt.md @@ -1,7 +1,7 @@ -# 权限控制方案生成 Prompt +# 权限控制方案生成 任务上下文契约 ```text -请基于工单模块 RBAC 权限矩阵，生成 JeecgBoot 权限控制方案。 +请基于业务模块 RBAC 权限矩阵，生成 JeecgBoot 权限控制方案。 输入材料： - RBAC 权限矩阵：<粘贴> 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 index 29456b8..1f5b02b 100644 --- a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/状态流转表.template.md +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/状态流转表.template.md @@ -1,8 +1,8 @@ -# 工单状态流转表 +# 业务对象状态流转表 | 当前状态 | 动作 | 目标状态 | 允许角色 | 前置条件 | 后置动作 | 验收 | | --- | --- | --- | --- | --- | --- | --- | -| 新建 | 指派 | 新建 | 管理员/负责人 | 工单未关闭 | 写审计日志 | 指派人变化且状态不变 | +| 新建 | 指派 | 新建 | 管理员/负责人 | 业务对象未关闭 | 写审计日志 | 指派人变化且状态不变 | | 新建 | 开始处理 | 处理中 | 研发处理人/负责人 | 已指派处理人 | 写审计日志 | 状态变为处理中 | | 处理中 | 提交验证 | 待验证 | 研发处理人/负责人 | 处理说明不为空 | 写审计日志 | 状态变为待验证 | | 待验证 | 验证通过 | 已关闭 | 测试验证人/负责人 | 验证结果通过 | 写审计日志和关闭时间 | 状态变为已关闭 | 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 index 58b609b..b73a840 100644 --- a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/状态流转设计.prompt.md +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/状态流转设计.prompt.md @@ -1,7 +1,7 @@ -# 状态流转设计 Prompt +# 状态流转设计 任务上下文契约 ```text -请为 JeecgBoot 工单模块设计状态流转规则。 +请为 目标业务模块设计状态流转规则。 状态候选： - 新建 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 index 32da66b..16cf9d3 100644 --- a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板指标字典.template.md +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板指标字典.template.md @@ -1,13 +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 | 工单表 | 排行榜 | 管理员/负责人 | 数据范围正确 | +| 业务对象总数 | 当前筛选范围内业务对象数量 | count() | 业务对象表 | 指标卡 | 看板权限 | 与列表同条件数量一致 | +| 未关闭业务对象数 | 状态不是已关闭的数量 | 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 index 9851ec7..c513237 100644 --- a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板指标设计.prompt.md +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板指标设计.prompt.md @@ -1,16 +1,16 @@ -# 看板指标设计 Prompt +# 看板指标设计 任务上下文契约 ```text -请为 JeecgBoot 工单模块设计研发效能看板指标。 +请为 目标业务模块设计研发效能看板指标。 指标方向： -- 工单总数 -- 未关闭工单数 +- 业务对象总数 +- 未关闭业务对象数 - 平均关闭周期 - 按优先级分布 - 按类型分布 - 缺陷趋势 -- 逾期工单数 +- 逾期业务对象数 - 人员处理负载 输出要求： 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 index b3f2e75..3abc4f4 100644 --- a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板接口验收.prompt.md +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板接口验收.prompt.md @@ -1,7 +1,7 @@ -# 看板接口验收 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 index 95e740a..b21d2d7 100644 --- a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板接口验收清单.md +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板接口验收清单.md @@ -4,7 +4,7 @@ | --- | --- | --- | --- | | 默认查询 | 管理员默认条件 | 返回完整指标 | | | 时间过滤 | 指定 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 index 6ddf072..7becf5e 100644 --- a/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板接口验收记录.template.md +++ b/deliverables/客户AI工程Skill交付包/skills/design-complex-business-module/assets/看板接口验收记录.template.md @@ -1,8 +1,8 @@ -# 工单看板接口验收记录 +# 业务对象看板接口验收记录 | 验收项 | 账号/条件 | 请求参数 | 预期 | 实际 | 证据 | 结论 | | --- | --- | --- | --- | --- | --- | --- | -| 工单总数 | 管理员 | 默认筛选 | 返回总数 | | | | +| 业务对象总数 | 管理员 | 默认筛选 | 返回总数 | | | | | 空数据 | 管理员 + 无匹配条件 | 不存在的日期范围 | 返回空集合或 0 | | | | | 无权限 | 只读外角色 | 默认筛选 | 返回 403 或业务拒绝 | | | | | 时间过滤 | 管理员 | start/end | 只统计范围内数据 | | | | diff --git a/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/assets/项目约束生成.prompt.md b/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/assets/项目约束生成.prompt.md index 7c25980..0e4001b 100644 --- a/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/assets/项目约束生成.prompt.md +++ b/deliverables/客户AI工程Skill交付包/skills/generate-project-constraints/assets/项目约束生成.prompt.md @@ -1,4 +1,4 @@ -# 项目约束生成 Prompt +# 项目约束生成 任务上下文契约 请为下面项目生成可复用的 AI 开发约束资产。 diff --git a/deliverables/ai-engineering-skills-delivery/skills/project-knowledge-builder/SKILL.md b/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/SKILL.md similarity index 100% rename from deliverables/ai-engineering-skills-delivery/skills/project-knowledge-builder/SKILL.md rename to deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/SKILL.md diff --git a/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/SKILL_zh.md b/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/SKILL_zh.md new file mode 100644 index 0000000..d4662c8 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/SKILL_zh.md @@ -0,0 +1,133 @@ +--- +name: project-knowledge-builder +description: 当用户要求“项目知识库”“看项目”“整理项目”，或需要深度检查软件项目、构建/刷新项目知识库、创建入门文档、架构图、领域词汇表、ADR、API/配置/数据库生成索引或 RAG 友好仓库文档时使用。 +--- + +# 项目知识库构建 + +## 概览 + +构建一个有源码依据的项目知识库，帮助人和 AI 理解、扩展、排障和索引代码库。把知识库视为持续维护的系统资产，而不是 README 改写。 + +## 快速使用 + +用户不需要记住命令、脚本路径或 `$project-knowledge-builder`。 + +最短触发语即可： + +- `项目知识库` + +除非用户另有说明，将当前仓库作为目标，输出到 `docs/project-knowledge/`。由你运行 bundled inventory 脚本并写文档。只有用户明确要求命令行用法时，才展示手工命令。 + +## 语言和受众默认值 + +如果用户使用中文或要求中文，人类阅读的叙述文档默认使用中文：README、上下文、架构、运行、后端、前端、数据、认证/权限、扩展、排障、RAG 指南和 ADR。源码路径、类名、命令、API 路径、配置键、表名、权限码、元数据枚举值保持原样。 + +把新维护者作为主要受众。一个有用的知识库应该让新人无需额外辅导就能回答四个问题： + +1. 这个项目是什么，主要模块在哪里？ +2. 如何本地运行，或如何识别当前运行模式？ +3. 如何找到某个功能对应的后端接口、前端页面、数据库表和权限码？ +4. 新增普通功能时通常需要修改什么，尤其是菜单/按钮权限？ + +生成索引不要为了友好而牺牲精确性。生成文件要便于机器刷新；叙述文档要便于人阅读。 + +## 核心规则 + +每个结论都必须能追溯到仓库，或明确标记为推断。优先使用源码路径、命令、生成索引和未解决问题清单，而不是自信散文。 + +## 工作流 + +1. **设定范围。** 确认或默认输出位置为 `docs/project-knowledge/`。如果用户提到 RAG、飞书/Lark、Dify、Notion、入门、架构 Review 或 API 文档，调整输出契约。 +2. **优先读取本地说明。** 检查根文档，以及 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`.codex/`、`.agents/`、包管理文件、构建文件、env 示例、Docker 文件和模块 README。 +3. **生成 inventory。** 对目标仓库运行本 Skill 的 `scripts/project_inventory.py`。用输出作为事实基础，再人工检查关键文件。 +4. **映射上下文。** 识别限界上下文、运行模式、主要模块、路径暗示的 owner、外部系统和数据存储。使用 `CONTEXT.md` 和 `CONTEXT-MAP.md` 风格文档。 +5. **提取生成索引。** 尽可能产出可机器刷新的文档：接口、前端路由/视图、配置键、环境变量、数据库表、权限码、定时任务、队列、扩展点。 +6. **编写人类指南。** 产出入门、架构、本地运行/部署、数据模型、认证/权限、扩展、排障和术语表文档。按用户语言书写；中文用户使用 `已观察来源`、`核心事实`、`操作影响`、`未知与风险` 等标题。 +7. **为真实决策创建 ADR。** 记录当前代码已经体现的重要架构决策。不要发明未来决策，除非标为 proposed。 +8. **添加 RAG 元数据指南。** 包括切块、source-path metadata、过期策略和排除规则。 +9. **验证。** 重新运行 inventory，扫描占位符、坏链接、过期路径和无依据结论。报告已验证内容和仍不确定内容。 + +## 输出契约 + +创建或升级完整知识库时读取 `references/output-contract_zh.md`。 + +最小有用集合： + +```text +docs/project-knowledge/ +├── README.md +├── CONTEXT.md +├── CONTEXT-MAP.md +├── 01-architecture.md +├── 02-runtime.md +├── 03-backend.md +├── 04-frontend.md +├── 05-data-and-migrations.md +├── 06-auth-permissions.md +├── 07-extension-guide.md +├── 08-troubleshooting.md +├── 09-rag-indexing.md +├── adr/ +│ └── 0001-current-runtime-architecture.md +└── generated/ + ├── project-inventory.md + ├── backend-endpoints.md + ├── frontend-routes.md + ├── config-reference.md + ├── database-dictionary.md + └── permission-codes.md +``` + +只有仓库较小或用户要求轻量产物时，才缩小范围。 + +## 来源依据标准 + +- 非显然结论必须内联引用来源路径。 +- 区分 **已观察**、**推断** 和 **未知**。 +- 不要凭记忆总结生成代码、依赖或配置，必须读取。 +- 如果不稳定事实需要外部文档，浏览一手来源并附链接。 +- 保留项目专用约定。如果仓库要求追踪注释、ADR 格式或 issue ID，记录并遵守。 + +## 跨平台兼容 + +当用户询问 macOS、Windows、Linux、CI、可移植性或跨机器安装/运行时，读取 `references/compatibility_zh.md`。bundled inventory 脚本面向 Python 3.9+，只使用标准库。 + +## Inventory 脚本 + +仅在手工刷新或用户询问命令时展示。请在目标仓库运行： + +macOS/Linux： + +```sh +python3 /path/to/skill/scripts/project_inventory.py --root . --out docs/project-knowledge/generated +``` + +Windows PowerShell： + +```powershell +py -3 C:\path\to\skill\scripts\project_inventory.py --root . --out docs\project-knowledge\generated +``` + +常用选项： + +```sh +python3 /path/to/skill/scripts/project_inventory.py --root . --out ./kb-inventory --json +python3 /path/to/skill/scripts/project_inventory.py --root . --out docs/project-knowledge/generated --max-files 20000 +``` + +脚本只是起点，不能替代阅读核心文件。编写叙述文档前，必须检查代表性文件。 + +## 质量门禁 + +最终回复前： + +- 用适合平台的命令列出生成文档，例如 macOS/Linux 使用 `find docs/project-knowledge -type f | sort`，PowerShell 使用 `Get-ChildItem docs/project-knowledge -Recurse -File`。 +- 执行 `rg -n "TODO|TBD|待补|unknown|your/path|foo|bar" docs/project-knowledge`。 +- 编辑后重新运行 inventory 脚本。 +- 检查顶层 README 链接是否可解析。 +- 如果用户是中文用户，扫描叙述文档中是否仍有英文结构标题，例如 `Observed Sources`、`Core Facts`、`Operational Implications`、`Unknowns/Risks`、`Architecture`、`Runtime`、`Backend`、`Frontend`、`Troubleshooting`，除代码、元数据或生成输出外应翻译。 +- 检查新人可用性：README 给出阅读顺序；运行文档说明本地/Docker/云端模式；权限文档说明菜单/按钮权限流；扩展文档说明后端 CRUD、前端页面和权限变更。 +- 使用 `git status --short` 报告变更文件。 + +如果用户要求“深度”或“落地”，不要停在单页概览。必须交付生成索引和人类指南。 diff --git a/deliverables/ai-engineering-skills-delivery/skills/project-knowledge-builder/agents/openai.yaml b/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/agents/openai.yaml similarity index 100% rename from deliverables/ai-engineering-skills-delivery/skills/project-knowledge-builder/agents/openai.yaml rename to deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/agents/openai.yaml diff --git a/deliverables/ai-engineering-skills-delivery/skills/project-knowledge-builder/references/compatibility.md b/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/references/compatibility.md similarity index 100% rename from deliverables/ai-engineering-skills-delivery/skills/project-knowledge-builder/references/compatibility.md rename to deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/references/compatibility.md diff --git a/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/references/compatibility_zh.md b/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/references/compatibility_zh.md new file mode 100644 index 0000000..16e7fc6 --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/references/compatibility_zh.md @@ -0,0 +1,64 @@ +# 跨平台兼容 + +在 macOS、Windows、Linux 或 CI 上运行或安装本 Skill 时使用本参考。 + +## 兼容性摘要 + +| 项目 | macOS | Linux | Windows | +| --- | --- | --- | --- | +| `SKILL.md` 工作流 | 支持 | 支持 | 支持 | +| `project_inventory.py` | Python 3.9+ 支持 | Python 3.9+ 支持 | Python 3.9+ 支持 | +| Python 依赖 | 仅标准库 | 仅标准库 | 仅标准库 | +| 路径处理 | `pathlib` | `pathlib` | `pathlib` | +| shell 依赖 | 脚本无依赖 | 脚本无依赖 | 脚本无依赖 | +| 生成 Markdown 路径 | POSIX 风格相对路径 | POSIX 风格相对路径 | POSIX 风格相对路径 | + +脚本故意使用带 `/` 分隔符的仓库相对路径，使生成 Markdown 在跨平台、GitHub URL 和 RAG metadata 中更稳定。 + +## Python 调用 + +macOS 和 Linux 通常使用： + +```sh +python3 skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated +python skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated +``` + +Windows PowerShell 通常使用： + +```powershell +py -3 skills\project-knowledge-builder\scripts\project_inventory.py --root . --out docs\project-knowledge\generated +python skills\project-knowledge-builder\scripts\project_inventory.py --root . --out docs\project-knowledge\generated +``` + +CI 应优先使用明确的 Python： + +```sh +python -m py_compile skills/project-knowledge-builder/scripts/project_inventory.py +python skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated --json +``` + +## 命令替换 + +| 任务 | macOS/Linux | Windows PowerShell | +| --- | --- | --- | +| 列出文档 | `find docs/project-knowledge -type f \| sort` | `Get-ChildItem docs/project-knowledge -Recurse -File \| Sort-Object FullName` | +| 搜索占位符 | `rg -n "TODO|TBD" docs/project-knowledge` | `rg -n "TODO|TBD" docs/project-knowledge` | +| 查看 git 状态 | `git status --short` | `git status --short` | +| 删除临时输出 | `rm -rf ./kb-inventory` | `Remove-Item .\kb-inventory -Recurse -Force` | + +优先使用 `rg`。如果环境中没有 `rg`，使用该平台可用的搜索工具。 + +## Skill 示例中应避免 + +- 在应支持 Windows 的命令中写死 `/tmp` 路径。 +- 在面向用户的说明中只给 POSIX 命令链，例如 `cmd1 && cmd2`，而不给 PowerShell 等价方式。 +- 假设 shell glob 在 zsh、bash、PowerShell、cmd 中行为一致。 +- 依赖 shebang 可执行行为的 Python 用法；Windows 用户应调用 `py -3 script.py`。 + +## 已知限制 + +- Java endpoint 提取基于正则，故意保持保守。它不会完整解析常量、组合注解或继承的 controller mapping。 +- SQL 表提取查找 `CREATE TABLE`；动态创建的表或其他迁移 DSL 需要人工文档化。 +- 前端路由提取会扫描 route-like 字面量和 view 文件；运行时由 API 生成的路由仍需要后端菜单/权限数据或数据库导出。 +- 超大仓库可能需要调整 `--max-files`，或增加忽略目录。 diff --git a/deliverables/ai-engineering-skills-delivery/skills/project-knowledge-builder/references/output-contract.md b/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/references/output-contract.md similarity index 100% rename from deliverables/ai-engineering-skills-delivery/skills/project-knowledge-builder/references/output-contract.md rename to deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/references/output-contract.md diff --git a/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/references/output-contract_zh.md b/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/references/output-contract_zh.md new file mode 100644 index 0000000..8bb5cee --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/references/output-contract_zh.md @@ -0,0 +1,135 @@ +# 项目知识库输出契约 + +生成完整代码库知识库时使用本参考。 + +## 语言策略 + +人类阅读的叙述文档应匹配用户语言。如果用户使用中文或要求中文，README、上下文、架构、运行、后端、前端、数据、认证/权限、扩展、排障、RAG 指南和 ADR 都应使用中文。 + +技术锚点保持原样：源码路径、命令、类名、方法名、API 路径、配置键、表名、权限码、JSON key 和元数据枚举值。 + +生成索引可以保持技术化和接近源码。不要为了翻译而破坏可刷新性。 + +## 文档职责 + +| 文件 | 用途 | +| --- | --- | +| `README.md` | 入口、阅读顺序、高价值链接、新鲜度说明。中文输出时标题和使用说明应为中文。 | +| `CONTEXT.md` | 领域语言、业务能力、用户角色、核心名词、不变量。 | +| `CONTEXT-MAP.md` | 限界上下文、模块归属、上下游依赖、运行边界。 | +| `01-architecture.md` | 系统形态、模块图、请求/数据/控制流、扩展点。 | +| `02-runtime.md` | 本地运行、构建、环境变量、Docker、部署模式、进程拓扑。存在时必须识别本地、Docker standalone 和云端模式。 | +| `03-backend.md` | 后端模块、入口点、API 约定、service/mapper/entity 模式。 | +| `04-frontend.md` | 前端启动、路由、状态、API client、组件/页面约定。 | +| `05-data-and-migrations.md` | 数据库、迁移、schema 来源、种子数据、表族。 | +| `06-auth-permissions.md` | 认证、授权、token/session 流、权限码生命周期。仓库存在后端驱动菜单时，必须解释菜单/按钮权限流。 | +| `07-extension-guide.md` | 如何端到端新增功能，并给出有来源依据的示例。适用时必须覆盖后端 CRUD、前端页面和权限/菜单数据变更。 | +| `08-troubleshooting.md` | 面向症状的排障手册，包含命令、文件和可能原因。 | +| `09-rag-indexing.md` | 切块、元数据、排除规则、刷新频率、过期数据策略。 | +| `adr/*.md` | 当前代码已经体现的架构决策。 | +| `generated/*.md` | 可重新生成的数据索引。 | + +## 必要章节 + +每份叙述文档应包含： + +- **已观察来源**：使用过的具体文件或命令。 +- **核心事实**：简洁、有来源依据的陈述。 +- **操作影响**：开发者因这些事实需要采取的不同做法。 +- **未知与风险**：需要运行权限、数据库导出、产品负责人输入或外部文档才能确认的缺口。 + +## 新人可用性门禁 + +认为知识库可交接前，确认新维护者能回答： + +1. 这个产品/项目是什么，哪些目录最重要？ +2. 如何启动，或如何识别当前运行模式？ +3. 后端接口、前端路由/页面、配置、数据表、权限码在哪里索引？ +4. 菜单、按钮和后端权限校验如何连接？ +5. 新增普通功能时，通常会改哪些后端、前端、数据库和权限产物？ + +如果 README 加叙述文档无法明显回答这些问题，先补充或修改人类阅读指南。不要通过加长生成索引来解决。 + +## 生成索引 + +### `project-inventory.md` + +包含： + +- 仓库根路径 +- 构建/包管理清单 +- 主要语言 +- 主要目录 +- scripts +- Docker/compose 文件 +- env 文件 +- 测试文件 + +### `backend-endpoints.md` + +包含路由方法、路径、类/文件、近似行号、认证注解和备注。不要在 class-level 与 method-level mapping 需要 Java 表达式解析时编造完整路径；展示已观察片段，并标记组合限制。 + +### `frontend-routes.md` + +包含静态路由文件、动态路由加载器、`src/views` 索引、路由守卫文件和外部路由包加载器。 + +### `config-reference.md` + +包含 env 文件、YAML/properties 文件、相关 key、默认值和风险说明。敏感信息必须脱敏。 + +### `database-dictionary.md` + +包含 SQL 文件、迁移文件、表名、表族，以及表是初始化、迁移还是推断得出。不要把巨大 SQL 写进正文；摘要并链接来源。 + +### `permission-codes.md` + +包含后端注解、前端权限 helper/usage、菜单/权限 SQL 命中和认证生命周期说明。 + +## ADR 模板 + +```markdown +# ADR NNNN: 标题 + +Date: YYYY-MM-DD +Status: Observed + +## Context + +说明该决策已经存在的来源事实。 + +## Decision + +当前代码体现的架构决策。 + +## Consequences + +收益、取舍、操作约束和迁移风险。 + +## Sources + +- `path/to/file` +``` + +## RAG 元数据 + +推荐每个 chunk 使用： + +```json +{ + "project": "name", + "snapshot_date": "YYYY-MM-DD", + "source_path": "path", + "doc_type": "architecture|runtime|generated|adr|runbook", + "domain": "backend|frontend|data|auth|deploy", + "freshness": "manual|generated", + "confidence": "observed|inferred|unknown" +} +``` + +## 反模式 + +- 只有长篇说明，没有生成索引。 +- 写与仓库无关的“最佳实践”建议。 +- 把 README 营销文案复制成架构文档。 +- 没有来源路径就声称某接口、表、权限或运行模式存在。 +- 隐藏未知问题，而不是列出来。 diff --git a/deliverables/ai-engineering-skills-delivery/skills/project-knowledge-builder/scripts/project_inventory.py b/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/scripts/project_inventory.py similarity index 100% rename from deliverables/ai-engineering-skills-delivery/skills/project-knowledge-builder/scripts/project_inventory.py rename to deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/scripts/project_inventory.py diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/审计日志检查清单.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/审计日志检查清单.md index 0e271a4..093e3bd 100644 --- a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/审计日志检查清单.md +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/审计日志检查清单.md @@ -2,7 +2,7 @@ | 检查项 | 通过标准 | 结果 | | --- | --- | --- | -| 创建记录 | 创建工单后能查询审计记录 | | +| 创建记录 | 创建业务对象后能查询审计记录 | | | 字段变更 | 编辑关键字段记录 oldValue/newValue | | | 指派记录 | 指派负责人记录原负责人和新负责人 | | | 状态记录 | 状态流转记录原状态和新状态 | | diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/异常态检查清单.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/异常态检查清单.md index e1b6496..74442ae 100644 --- a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/异常态检查清单.md +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/异常态检查清单.md @@ -3,7 +3,7 @@ | 异常态 | 必须验证 | 结果 | | --- | --- | --- | | 空列表 | 页面显示空状态，不报错 | | -| 详情不存在 | 提示工单不存在，页面不崩溃 | | +| 详情不存在 | 提示业务对象不存在，页面不崩溃 | | | 权限不足 | 前端提示或隐藏，后端拒绝 | | | 非法状态 | 返回非法流转，状态不变 | | | 重复提交 | 只成功一次，只写一条有效审计 | | diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/权限上线前检查清单.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/权限上线前检查清单.md index cacf893..c99b571 100644 --- a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/权限上线前检查清单.md +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/权限上线前检查清单.md @@ -2,10 +2,10 @@ | 检查项 | 通过标准 | 结果 | | --- | --- | --- | -| 菜单权限 | 工单菜单只对授权角色可见 | | +| 菜单权限 | 业务对象菜单只对授权角色可见 | | | 按钮权限 | 新增、编辑、删除、指派、状态按钮按权限显示 | | | 接口权限 | 无权限账号直接请求敏感接口失败 | | -| 数据权限 | 普通用户只能看到授权范围内工单 | | +| 数据权限 | 普通用户只能看到授权范围内业务对象 | | | 权限字符 | 前端按钮、菜单配置、后端接口命名一致 | | | 审计 | 权限敏感操作成功后有审计记录 | | | 反例验证 | 无权限账号不能绕过前端执行删除/指派 | | diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/看板接口验收清单.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/看板接口验收清单.md index 95e740a..b21d2d7 100644 --- a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/看板接口验收清单.md +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/看板接口验收清单.md @@ -4,7 +4,7 @@ | --- | --- | --- | --- | | 默认查询 | 管理员默认条件 | 返回完整指标 | | | 时间过滤 | 指定 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 index 99c3843..db1c747 100644 --- a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/阶段Review.prompt.md +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/阶段Review.prompt.md @@ -1,7 +1,7 @@ -# 阶段 Review Prompt +# 阶段 Review 任务上下文契约 ```text -请对 JeecgBoot 工单模块阶段交付物做 Review。 +请对 目标业务模块阶段交付物做 Review。 输入材料： - RBAC 权限矩阵 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 index eba0738..b2f6c12 100644 --- a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/阶段Review报告.template.md +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/阶段Review报告.template.md @@ -15,7 +15,7 @@ | 等级 | 模块 | 问题 | 触发规则 | 风险 | 修复建议 | 验收 | | --- | --- | --- | --- | --- | --- | --- | -| P1 | 权限 | 删除接口只隐藏按钮，后端缺少权限校验 | 前端按钮不是安全边界 | 可绕过前端删除工单 | 后端补权限校验 | 无权限账号请求返回 403 | +| P1 | 权限 | 删除接口只隐藏按钮，后端缺少权限校验 | 前端按钮不是安全边界 | 可绕过前端删除业务对象 | 后端补权限校验 | 无权限账号请求返回 403 | ## 不确定点 diff --git a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/验收清单.md b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/验收清单.md index 230cd33..384e658 100644 --- a/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/验收清单.md +++ b/deliverables/客户AI工程Skill交付包/skills/review-business-delivery/assets/验收清单.md @@ -1,71 +1,35 @@ -# 验收清单 +# 业务交付验收清单 -本清单用于判断学员是否真正掌握 JeecgBoot 工单案例，而不是只复制了 TRAE 输出。建议讲师在小组展示时逐项打分。 +本清单用于审查一个业务模块的设计、代码或 PR 是否具备可交付证据。它不替代目标项目的实际规则、接口规范或测试要求。 ## 项目理解 | 检查项 | 通过标准 | 结果 | -| --- | --- | --- | -| 能说明 JeecgBoot 前后端目录 | 至少指出 `jeecg-boot`、`jeecgboot-vue3`、`docs/project-knowledge` 的用途 | | -| 能定位后端入口 | 能指出 `JeecgSystemApplication.java` 和后端启动模块 | | -| 能定位前端入口 | 能指出 `src/main.ts`、路由、Pinia 和 API 请求层 | | -| 能区分事实和推断 | 对没有源码依据的业务规则标注为推断或待确认 | | -| 能记录不确定点 | 不确定内容没有被包装成确定事实 | | +|---|---|---| +| 模块边界明确 | 已定位前后端入口、接口、数据模型和必要配置 | | +| 事实与推断分开 | 每个非显然结论能够回到源码、日志、配置或规范 | | +| 待确认项明确 | 无证据内容没有被包装成确定事实 | | -## 需求与接口 +## 改动边界 | 检查项 | 通过标准 | 结果 | -| --- | --- | --- | -| 用户故事完整 | 覆盖管理员、负责人、研发、测试、只读用户 | | -| 非目标范围明确 | 明确课堂不做完整编码、生产部署、真实数据迁移 | | -| 接口契约完整 | 覆盖列表、详情、新增、编辑、指派、状态、审计、看板 | | -| 失败场景明确 | 每个关键接口至少有权限、参数、状态或数据不存在失败场景 | | -| 验收方式明确 | 每个关键需求都有可执行检查方法 | | +|---|---|---| +| 目标与非目标明确 | 说明本次解决的问题及明确不修改的相邻范围 | | +| 关键风险已识别 | 权限、状态、审计、异常、数据范围和兼容性按需核对 | | +| 最小改动可解释 | 关键规则有权威入口，未引入无关重构 | | -## 权限与状态 +## 验证与交付 | 检查项 | 通过标准 | 结果 | -| --- | --- | --- | -| 权限矩阵完整 | 覆盖页面级、按钮级、接口级和数据范围 | | -| 权限字符合理 | 命名统一，并标注为建议而非源码事实 | | -| 后端权限未缺失 | 没有用前端按钮隐藏替代后端接口控制 | | -| 状态流转表完整 | 覆盖新建、处理中、待验证、已关闭、已驳回 | | -| 非法流转明确 | 至少列出 5 条非法流转和拒绝原因 | | +|---|---|---| +| 验证覆盖匹配风险 | 正常、异常、权限、状态与边界场景按实际风险设计 | | +| 执行结果如实记录 | 已执行命令、CI、日志或人工观察可复核；未执行项明确列出 | | +| PR 或变更说明完整 | 包含目标、实现范围、验证证据和已知边界 | | +| 资产沉淀有依据 | 仅将可复用且已验证的判断沉淀为 Rule、任务上下文契约、检查单、Skill 或 MCP 契约 | | -## 审计、异常态与看板 - -| 检查项 | 通过标准 | 结果 | -| --- | --- | --- | -| 审计操作覆盖关键动作 | 创建、编辑、指派、状态流转、关闭、评论至少覆盖 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。 -- 优先看不确定点是否被诚实标出。 -- 优先看能否复用到团队资产库。 -- 对没有依据的自信结论扣分。 +## 判定原则 +- 优先审查证据与边界，不以篇幅或术语数量判断质量。 +- 前端隐藏或必填不能替代后端权限和业务状态保护。 +- 局部测试、CI 通过和源码阅读分别只支撑相应范围的结论。 +- 发生资产变更时，补充行为、引用、兼容性和夹具验证证据。 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 index 24fcfe7..01d6ad3 100644 --- a/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/修复记录生成.prompt.md +++ b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/修复记录生成.prompt.md @@ -1,4 +1,4 @@ -# 修复记录生成 Prompt +# 修复记录生成 任务上下文契约 ```text 请根据阶段 Review 报告生成修复记录。 diff --git a/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/审计日志缺失反例.md b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/审计日志缺失反例.md index 8dba8d6..e0f7166 100644 --- a/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/审计日志缺失反例.md +++ b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/审计日志缺失反例.md @@ -2,13 +2,13 @@ ## 场景 -工单指派负责人成功，但没有记录审计日志。 +业务对象指派负责人成功，但没有记录审计日志。 ## 问题表现 | 操作 | 结果 | | --- | --- | -| 张三将工单指派给李四 | 工单负责人变更成功 | +| 张三将业务对象指派给李四 | 业务对象负责人变更成功 | | 查询审计日志 | 没有负责人变更记录 | ## 风险 @@ -28,5 +28,5 @@ | --- | --- | | 指派成功 | 审计列表出现 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 index 0e3cfb7..60b9887 100644 --- a/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/权限遗漏反例.md +++ b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/权限遗漏反例.md @@ -2,19 +2,19 @@ ## 场景 -工单删除按钮在前端按权限隐藏，但后端删除接口没有权限校验。 +业务对象删除按钮在前端按权限隐藏，但后端删除接口没有权限校验。 ## 问题代码表现 | 层级 | 表现 | | --- | --- | | 前端 | 普通研发账号看不到删除按钮 | -| 后端 | 直接请求 `/workOrder/delete` 仍可删除 | +| 后端 | 直接请求 `//delete` 仍可删除 | | 审计 | 删除记录可能缺失 | ## 风险 -攻击者或误操作用户可以绕过前端直接调用接口删除工单。 +攻击者或误操作用户可以绕过前端直接调用接口删除业务对象。 ## 修复要求 @@ -27,7 +27,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 index be5ee62..885263a 100644 --- a/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/看板指标口径不清反例.md +++ b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/看板指标口径不清反例.md @@ -8,7 +8,7 @@ | 指标 | 当前说明 | | --- | --- | -| 平均关闭周期 | 最近工单平均处理时间 | +| 平均关闭周期 | 最近业务对象平均处理时间 | ## 风险 @@ -17,7 +17,7 @@ ## 修复要求 1. 明确定义为 `close_time - create_time` 或其他确定口径。 -2. 明确是否排除未关闭工单。 +2. 明确是否排除未关闭业务对象。 3. 明确时间范围过滤字段。 4. 用样例数据手工校验。 @@ -25,7 +25,7 @@ | 样例 | 预期 | | --- | --- | -| 工单 A 创建 1 日、关闭 3 日 | 周期 2 天 | -| 未关闭工单 | 不计入平均关闭周期 | +| 业务对象 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 index e675156..6830a33 100644 --- a/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/非法状态流转反例.md +++ b/deliverables/客户AI工程Skill交付包/skills/track-review-fix-loop/assets/非法状态流转反例.md @@ -2,7 +2,7 @@ ## 场景 -已关闭工单可以直接被改回处理中。 +已关闭业务对象可以直接被改回处理中。 ## 问题表现 @@ -12,12 +12,12 @@ ## 风险 -已关闭工单被重新打开但没有重开原因、没有审计、没有负责人确认，导致统计和责任链失真。 +已关闭业务对象被重新打开但没有重开原因、没有审计、没有负责人确认，导致统计和责任链失真。 ## 修复要求 1. Service 层集中校验状态流转。 -2. 已关闭工单只能通过“重新打开”动作变为新建。 +2. 已关闭业务对象只能通过“重新打开”动作变为新建。 3. 重新打开必须填写原因。 4. 所有成功流转写审计日志。 diff --git a/deliverables/客户AI工程Skill交付包/交付清单.md b/deliverables/客户AI工程Skill交付包/交付清单.md new file mode 100644 index 0000000..82f46ca --- /dev/null +++ b/deliverables/客户AI工程Skill交付包/交付清单.md @@ -0,0 +1,42 @@ +# 正式交付清单 + +## 版本信息 + +- 交付名称：客户 AI 工程资产交付包 +- 版本：V1.0 +- 整理日期：2026-08-06 +- 正式载体：本目录与同级 `客户AI工程Skill交付包.zip` + +目录与 ZIP 内容一致；对外发送时任选一种载体即可，不应混用历史压缩包或旧目录。 + +## 正式交付范围 + +| 类别 | 内容 | 用途 | +|---|---|---| +| 项目约束 | `generate-project-constraints` | 从目标项目提取可验证的开发约束 | +| 项目知识 | `project-knowledge-builder` | 建立源码依据的项目知识库与索引 | +| 复杂业务设计 | `design-complex-business-module` | 设计权限、状态、审计、异常态和指标 | +| 交付审查 | `review-business-delivery` | 审查设计、代码或 PR 的风险与验证缺口 | +| 修复闭环 | `track-review-fix-loop` | 跟踪 Review 问题、修复、验证与资产更新 | +| MCP 资产 | `mcp-assets/` | 描述外部能力、权限、副作用、失败降级和验收夹具 | +| 实战案例 | `examples/jeecgboot-official-vehicle/` | 基于现有公务用车模块的单人影响分析与验证案例 | + +## 使用边界 + +- 五个 Skill 与 MCP 资产均为通用工程资产；业务对象、路径、接口、权限码、状态和测试命令必须从目标项目重新取得。 +- 公务用车案例只保留已经读取和验证的事实，用于说明方法，不构成任何客户业务要求。 +- MCP 目录不包含服务地址、凭据、内部域名或真实数据。接入时必须先完成能力契约、权限审查和验证夹具。 +- 本包不包含客户源码、训练分支、构建产物、在线考试题或讲师逐字稿；这些材料按其使用场景独立管理。 + +## 交付前核验项 + +- [x] 五个 Skill 目录均包含 `SKILL.md`，并保留各自的 assets、references、scripts 或 agents 文件。 +- [x] `mcp-assets/` 包含能力契约模板、权限与验收清单及使用说明。 +- [x] 扫描确认未携带历史案例、多人协作要求、默认账号或系统元数据文件。 +- [x] 压缩包可完整解压，且内容与本目录一致。 + +## 交付后的首次动作 + +1. 阅读 `README.md` 与 `安装说明.md`，确认目标 AI 编程工具的 Skill 加载方式。 +2. 在目标项目先运行项目约束提取与项目知识构建，再选择复杂业务设计或 Review 类 Skill。 +3. MCP 接入前填写能力契约，未完成权限和夹具验证时不得给 Agent 授权高风险工具。 diff --git a/deliverables/客户AI工程Skill交付包/安装说明.md b/deliverables/客户AI工程Skill交付包/安装说明.md index e931a84..3c0974e 100644 --- a/deliverables/客户AI工程Skill交付包/安装说明.md +++ b/deliverables/客户AI工程Skill交付包/安装说明.md @@ -1,63 +1,56 @@ # 安装说明 -## 方式一：安装到 TRAE Skills 目录 +## 使用前确认 -把 `skills/` 下的 4 个 Skill 文件夹复制到本机 Skills 目录： +本包不携带外部系统地址、账号、令牌或客户数据。请先在目标项目中确认 AI 工具的 Skill 加载方式、项目规则位置和访问权限，再决定安装范围。 -```text -~/.trae/skills/ -``` +## 方式一：作为本地 Skill 目录使用 -安装后目录应类似： +将 `skills/` 下需要启用的完整文件夹复制到当前 AI 编程工具配置的本地 Skill 目录。不同版本和不同工具的目录规则可能不同，应以当前客户端实际配置为准。 -```text -~/.trae/skills/ -├── generate-project-constraints/ -├── design-complex-business-module/ -├── review-business-delivery/ -└── track-review-fix-loop/ -``` - -每个 Skill 文件夹必须保留完整结构： +每个 Skill 必须保留原始目录结构： ```text skill-name/ ├── SKILL.md ├── agents/ │ └── openai.yaml -└── assets/ +├── assets/ # 部分 Skill 提供 +├── references/ # 部分 Skill 提供 +└── scripts/ # 部分 Skill 提供 ``` -## 调用方式 +推荐启用顺序： -在支持 Skill 的 AI 编程工具中，可以这样调用： - -```text -Use $generate-project-constraints 为当前项目生成 AI 开发约束。 -Use $design-complex-business-module 设计这个业务模块的权限、状态、审计、异常态和看板。 -Use $review-business-delivery Review 这批阶段交付物。 -Use $track-review-fix-loop 根据 Review 报告生成修复闭环记录。 -``` +1. `generate-project-constraints`：先获取项目约束。 +2. `project-knowledge-builder`：建立项目地图和可检索知识。 +3. `design-complex-business-module`：设计权限、状态、审计等高风险边界。 +4. `review-business-delivery`：审查设计、代码或 PR。 +5. `track-review-fix-loop`：跟踪修复、验证与资产更新。 ## 方式二：作为团队资产库使用 -如果当前 AI 工具暂不支持原生 Skill 机制，可以把本包作为团队资产库使用： +如果当前工具不支持原生 Skill 发现，可将本包纳入团队资产库。保留目录结构，并让任务上下文契约或 Agent 明确引用对应文件。 ```text ai-engineering-assets/ ├── skills/ -├── rules/ -├── prompts/ -├── templates/ -├── checklists/ +├── mcp-assets/ └── examples/ ``` -此时 `SKILL.md` 作为标准工作流说明，`assets/` 作为可复制模板、Prompt、检查清单和反例库。 +其中 `SKILL.md` 负责输入、工作流、输出契约和停止条件；`assets/` 存放模板、任务上下文契约、检查单和反例；`mcp-assets/` 负责外部能力的契约、权限与验收边界。 -## 维护建议 +## MCP 资产的使用 -- 每次项目规则变化后，重新运行 `generate-project-constraints`。 -- 每次复杂业务模块交付后，把高频问题沉淀到 `review-business-delivery` 或 `track-review-fix-loop` 的 assets。 -- 不要把某个项目的专用规则直接复制成通用规则。 -- 对无法从源码或配置证明的内容，统一标记为待确认。 +1. 使用 `mcp-assets/MCP能力契约.template.md` 描述每项待接入能力。 +2. 使用 `mcp-assets/MCP工具权限与验收清单.md` 审查数据范围、权限、副作用和故障降级。 +3. 为完整请求、缺参、越权、超时和敏感字段准备验证夹具。 +4. 只有契约与验证完整后，才把工具授权给对应 Agent。 + +## 维护要求 + +- 项目规则、框架、接口、权限或测试基座变化后，重新取证并更新相关资产。 +- 不要将示例中的业务对象、路径、字段、接口、状态或验证结论复制到其他项目。 +- 资产变更需要说明行为变化、兼容边界、迁移方式、回退条件和验证证据。 +- 对无法证明的内容保留为待确认，不以经验或模型建议替代事实。 diff --git a/exams/TRAE编程培训考试评估卷-实操与项目实战.docx b/exams/TRAE编程培训考试评估卷-实操与项目实战.docx new file mode 100644 index 0000000..c9947df Binary files /dev/null and b/exams/TRAE编程培训考试评估卷-实操与项目实战.docx differ diff --git a/exams/TRAE编程培训考试评估卷-实操与项目实战（修订版）.docx b/exams/TRAE编程培训考试评估卷-实操与项目实战（修订版）.docx new file mode 100644 index 0000000..e027adf Binary files /dev/null and b/exams/TRAE编程培训考试评估卷-实操与项目实战（修订版）.docx differ diff --git a/exams/TRAE编程培训考试评估卷-实操与项目实战（阅卷参考答案）.docx b/exams/TRAE编程培训考试评估卷-实操与项目实战（阅卷参考答案）.docx new file mode 100644 index 0000000..a3f70cb Binary files /dev/null and b/exams/TRAE编程培训考试评估卷-实操与项目实战（阅卷参考答案）.docx differ diff --git a/exams/TRAE编程培训考试题-30分钟线上版-客观题版.docx b/exams/TRAE编程培训考试题-30分钟线上版-客观题版.docx new file mode 100644 index 0000000..ba1ec17 Binary files /dev/null and b/exams/TRAE编程培训考试题-30分钟线上版-客观题版.docx differ diff --git a/exams/exam-kit/README.md b/exams/exam-kit/README.md new file mode 100644 index 0000000..599d43b --- /dev/null +++ b/exams/exam-kit/README.md @@ -0,0 +1,34 @@ +# TRAE 编程培训考试包 + +本目录是 B 卷的唯一考试输入。评分以本目录给出的 GitHub 仓库、固定提交、指定 diff 和提交模板为准。 + +## 阅卷参考答案 + +`reference-answer.md` 仅供讲师和阅卷人员使用，不能与学生版 `exam-output/` 一同发放。它给出每题的关键证据、可接受结论、测试口径和 Review 要点；学员不必逐字复述，但结论必须能由固定版本源码或指定 diff 支撑。 + +## 公开源码与 diff + +- GitHub 仓库：`https://github.com/jeecgboot/JeecgBoot.git` +- 固定版本：标签 `v3.9.2`，提交 `7df07a823fd558be857d0208ccae96342539fbc1` +- 指定变更：`review-diff.patch`，仅包含两处文件变更。 + +考试开始前完成源码下载；下载时间不计入作答时间。建议命令： + +```bash +git clone --depth 1 --branch v3.9.2 https://github.com/jeecgboot/JeecgBoot.git +cd JeecgBoot +git rev-parse HEAD +``` + +输出必须为 `7df07a823fd558be857d0208ccae96342539fbc1`。版本不一致时，立即记录为环境问题并联系监考人员，不得基于其他版本作答。 + +## 允许与禁止 + +- 允许使用 TRAE、上述 GitHub 固定版本和本考试包中的材料。 +- 不要求修改业务代码；不得将本次作答建立在未指定版本、历史成品或他人交付物上。 +- 所有项目结论必须能回溯到固定工作区中的文件、符号或指定 diff。 +- 测试只能如实标记为“已执行”或“未执行”；未执行时必须说明原因和计划验证方式。 + +## 提交方式 + +将 `exam-output/` 中的四个模板另存为个人提交目录并补全内容。不要改动文件名。 diff --git a/exams/exam-kit/exam-output/01-project-understanding.md b/exams/exam-kit/exam-output/01-project-understanding.md new file mode 100644 index 0000000..15188c0 --- /dev/null +++ b/exams/exam-kit/exam-output/01-project-understanding.md @@ -0,0 +1,21 @@ +# 项目理解与影响分析 + +## 结论摘要 + + + +## 证据表 + +| 结论 | 文件路径与符号 | 证据说明 | 判断类型 | +|---|---|---|---| +| | | | 事实 / 推断 / 待确认 | + +## 影响与保护边界 + + + +## 待确认项 + +| 待确认问题 | 原因 | 需要的证据或验证方式 | +|---|---|---| +| | | | diff --git a/exams/exam-kit/exam-output/02-change-and-test.md b/exams/exam-kit/exam-output/02-change-and-test.md new file mode 100644 index 0000000..d889677 --- /dev/null +++ b/exams/exam-kit/exam-output/02-change-and-test.md @@ -0,0 +1,23 @@ +# 最小改造与测试安全网 + +## 改造目标与验收标准 + +## 校验位置与顺序 + + + +## 不改动项 + +| 不改动项 | 保持原因 | 代码依据 | +|---|---|---| +| | | | + +## 测试矩阵 + +| 场景 | 预期结果 | 验证入口 | 执行状态 | 命令或未执行原因 | +|---|---|---|---|---| +| 空白或非法状态值 | | | 已执行 / 未执行 | | +| 正常冻结 | | | 已执行 / 未执行 | | +| 正常解冻 | | | 已执行 / 未执行 | | +| 无权限调用 | | | 已执行 / 未执行 | | +| 管理员保护与缓存/用户状态回归 | | | 已执行 / 未执行 | | diff --git a/exams/exam-kit/exam-output/03-pr-and-assets.md b/exams/exam-kit/exam-output/03-pr-and-assets.md new file mode 100644 index 0000000..4188f62 --- /dev/null +++ b/exams/exam-kit/exam-output/03-pr-and-assets.md @@ -0,0 +1,31 @@ +# Review、PR 与资产沉淀 + +## Review 结论 + + + +| 等级或结论 | 证据 | 风险 | 建议的验收方式 | +|---|---|---|---| +| | | | | + +## PR 说明 + +### 背景 + +### 实现 + +### 测试 + +### 风险与回退 + +## 可复用 Prompt + +### 输入 + +### 约束与输出 + +### 验收方式 + +## Rule、Checklist 或 Skill 设计卡 + + diff --git a/exams/exam-kit/exam-output/trae-usage-record.md b/exams/exam-kit/exam-output/trae-usage-record.md new file mode 100644 index 0000000..ac9dd37 --- /dev/null +++ b/exams/exam-kit/exam-output/trae-usage-record.md @@ -0,0 +1,5 @@ +# TRAE 使用记录 + +| Prompt 或操作 | TRAE 建议摘要 | 采纳或否决 | 人工判断点 | 证据或验证状态 | +|---|---|---|---|---| +| | | | | 已执行 / 未执行 | diff --git a/exams/exam-kit/reference-answer.md b/exams/exam-kit/reference-answer.md new file mode 100644 index 0000000..a2f1b71 --- /dev/null +++ b/exams/exam-kit/reference-answer.md @@ -0,0 +1,168 @@ +# TRAE 编程培训考试评估卷 - 阅卷参考答案 + +> 阅卷专用。对应 `jeecgboot/JeecgBoot` 标签 `v3.9.2`、提交 `7df07a823fd558be857d0208ccae96342539fbc1` 及 `review-diff.patch`。学生不需要逐字复述本答案，但所有核心结论都必须有等价的源码依据。 + +## A 卷 + +### 任务 1：Prompt 改写（15 分） + +下列内容是一份达到满分要求的参考 Prompt。允许更换表述，但不能省略范围、约束、交付格式和验收条件。 + +```text +你是负责 JeecgBoot 系统用户模块的后端工程师。请基于 GitHub 仓库 +jeecgboot/JeecgBoot 的 v3.9.2（提交 7df07a823fd558be857d0208ccae96342539fbc1）， +审查“批量冻结/解冻用户”的后端链路是否允许非法状态值进入数据层。 + +范围：只分析 +1. SysUserController.frozenBatch； +2. ISysUserService.updateStatus 和 SysUserServiceImpl.updateStatus； +3. CommonConstant 中的用户状态常量； +4. 与本接口直接相关的权限、管理员保护、缓存和测试入口。 + +目标：给出最小改造建议，使 status 只允许 1（解冻）或 2（冻结），并在数据库写入前拒绝 +空白或其他值。不要修改接口路径、权限 system:user:frozenBatch、管理员保护或缓存失效策略。 + +请按以下格式输出： +- 调用链和每个结论的“文件路径 + 方法/符号”； +- 变更位置、伪代码和不改动项； +- 空白/非法状态、冻结、解冻、无权限、管理员保护和缓存回归的测试矩阵； +- 仍需人工确认的问题。事实、推断和待确认项必须分别标识。 + +验收：每个结论均可回溯到上述固定提交；不编造测试结果；信息不足时先提出待确认项。 +``` + +判分关键：背景与目标（3 分）、范围（2 分）、约束（4 分）、输出格式（3 分）、验收和证据要求（3 分）。只写“帮我检查有没有问题”不能得高分。 + +### 任务 2：AI 输出辨析（15 分） + +题干中的 AI 结论“页面已限制状态值，因此 Service 不需要校验；直接调用接口也不会有问题”应判为错误，理由如下： + +1. 前端限制不是服务端的可信边界。调用者可以绕过页面直接发送 `PUT /sys/user/frozenBatch` 请求。 +2. `SysUserController.frozenBatch` 从 JSON 读取 `status` 后逐个调用 `sysUserService.updateStatus(id, status)`；原版 `updateStatus` 会直接执行 `Integer.parseInt(status)` 并更新数据库。 +3. Service 入口是数据写入前的最后业务保护点。正确做法是在 `updateStatus` 内、`Integer.parseInt` 和 `userMapper.update` 之前，仅允许 `CommonConstant.USER_UNFREEZE`（1）和 `CommonConstant.USER_FREEZE`（2）。`null`、空串、空白串、`3` 及其他值均应抛出业务异常。 +4. 不能因此删除接口权限、管理员保护或缓存注解；这些分别处理调用授权、关键账号保护和用户缓存一致性。 + +## B 卷任务 1：项目理解与影响分析（25 分） + +### 满分结论摘要 + +1. 批量冻结/解冻的 HTTP 入口是 `PUT /sys/user/frozenBatch`，由 `SysUserController.frozenBatch` 处理，受 `system:user:frozenBatch` 权限保护。 +2. Controller 从请求体读取 `ids`、先调用 `checkUserAdminRejectDel(ids)`，再读取 `status`，对每个非空 ID 调用 `updateStatus(id, status)`。 +3. `updateStatus` 是最终写入入口：它将状态转换为整数，通过 `userMapper.update` 更新 `SysUser.status`，并用 `@CacheEvict(CacheConstant.SYS_USERS_CACHE, allEntries = true)` 失效用户缓存。 +4. 用户状态常量中，`1` 表示解冻，`2` 表示冻结，`3` 表示注销；本题只允许前两种状态。 +5. 冻结状态会影响登录有效性判断：服务在读取到 `USER_FREEZE` 时返回“该用户已冻结”。 + +### 至少应出现的证据 + +| 结论 | 文件路径与符号 | 证明内容 | 判断类型 | +|---|---|---|---| +| 接口、HTTP 方法和权限 | `.../controller/SysUserController.java`，`frozenBatch` | `@RequiresPermissions("system:user:frozenBatch")` 与 `@RequestMapping(... "/frozenBatch", PUT)` | 事实 | +| Controller 到 Service 调用链 | 同文件 `frozenBatch` | 读取 `ids`、管理员保护、读取 `status`，循环调用 `updateStatus` | 事实 | +| 服务契约 | `.../service/ISysUserService.java`，`updateStatus(String id, String status)` | 状态更新是服务接口的一部分 | 事实 | +| 数据库与缓存副作用 | `.../service/impl/SysUserServiceImpl.java`，`updateStatus` | `@CacheEvict`、`Integer.parseInt(status)`、`userMapper.update` | 事实 | +| 合法状态枚举 | `.../common/constant/CommonConstant.java`，`USER_UNFREEZE`、`USER_FREEZE`、`USER_QUIT` | 取值分别为 1、2、3 | 事实 | +| 管理员保护 | `.../service/impl/SysUserServiceImpl.java`，`checkUserAdminRejectDel` | 目标 ID 中含用户名 `admin` 时抛出业务异常；`frozenBatch` 会调用它 | 事实 | +| 登录影响 | `.../service/impl/SysUserServiceImpl.java`，登录有效性检查中对 `USER_FREEZE` 的分支 | 冻结用户不能正常登录 | 事实 | + +### 影响和保护边界 + +- 非法状态若进入原版 Service，会在 `Integer.parseInt` 处异常，或在可解析但不受业务允许的值（如 `3`）场景写入不符合本题要求的状态；因此应在 Service 入口先拒绝。 +- 校验位于 `userMapper.update` 前；抛出异常时不会完成本次用户状态写入。`@CacheEvict` 默认在方法成功返回后生效，因此异常路径不应把一次失败校验伪装为成功变更。 +- 必须保持：接口路径和 PUT 方法、`system:user:frozenBatch` 权限、`checkUserAdminRejectDel(ids)` 调用、逐个用户更新的方式、缓存失效注解。 +- 可接受的待确认项：批量操作是否要求原子性、前端是否会发送 `null` 或空白状态、缓存是否有跨节点配置。不得把这些未查证项写成事实。 + +## B 卷任务 2：最小改造与测试安全网（25 分） + +### 改造位置和参考实现 + +文件：`jeecg-boot/jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/system/service/impl/SysUserServiceImpl.java`。 + +方法：`updateStatus(String id, String status)`。 + +位置：保留已有 `@Override` 和 `@CacheEvict`，在 `Integer.parseInt(status)`、`userMapper.update(...)` 之前加入校验： + +```java +if (!String.valueOf(CommonConstant.USER_UNFREEZE).equals(status) + && !String.valueOf(CommonConstant.USER_FREEZE).equals(status)) { + throw new JeecgBootException("账号状态仅支持冻结或解冻"); +} +``` + +该写法同时拒绝 `null`、空串、空白串、`3` 和其他非 `1`/`2` 的值；允许 `"1"` 与 `"2"`。它没有改变原有数据更新、缓存失效、权限或管理员保护路径。 + +### 必须明确的不改动项 + +| 不改动项 | 原因和代码依据 | +|---|---| +| 权限 | `SysUserController.frozenBatch` 的 `@RequiresPermissions("system:user:frozenBatch")` 仍是接口授权边界。 | +| 管理员保护 | Controller 继续先调用 `sysUserService.checkUserAdminRejectDel(ids)`；状态校验不能替代该保护。 | +| 缓存失效 | `SysUserServiceImpl.updateStatus` 的 `@CacheEvict(value = {CacheConstant.SYS_USERS_CACHE}, allEntries = true)` 保留，以保证成功修改后的用户缓存刷新。 | +| 数据写入方式 | 合法状态仍走原有 `userMapper.update(new SysUser().setStatus(...), ...)`。 | + +### 参考测试矩阵 + +| 场景 | 预期结果 | 验证入口 | 执行状态的正确写法 | +|---|---|---|---| +| `null`、空串、空白串、`3` | 抛出 `JeecgBootException`；不调用 mapper，不成功失效缓存 | `SysUserServiceImpl.updateStatus` 单元测试 | 未实际运行时必须写“未执行”和原因；不能凭空写通过 | +| `"1"` 解冻 | 调用 mapper，写入状态 1；成功返回后缓存失效 | Service 单元测试或集成测试 | 记录实际命令和结果 | +| `"2"` 冻结 | 调用 mapper，写入状态 2；成功返回后缓存失效 | Service 单元测试或集成测试 | 记录实际命令和结果 | +| 无权限请求 | 被权限框架拒绝，不能执行状态写入 | `PUT /sys/user/frozenBatch` 的接口/集成测试 | 记录测试账号、HTTP 结果或未执行原因 | +| 目标包含 `admin` | `checkUserAdminRejectDel` 拒绝，不能更新管理员 | 接口或 Controller 集成测试 | 记录结果或未执行原因 | +| 冻结后登录 | 读取冻结用户时走“该用户已冻结”分支 | 登录集成测试 | 可标为待环境验证，不得臆造 | + +`review-diff.patch` 已提供一个针对 `"3"` 的最小单元测试。它覆盖非法数值在访问 mapper 前被拒绝；高质量答案还应补充空白值和两个合法值的测试。项目父 POM 默认配置 `maven-surefire-plugin` 跳过测试，因此学员若未调整本地测试配置，应如实标记“未执行”，并给出启用测试后的计划命令，而不是伪造成功结果。 + +## B 卷任务 3：Review、PR 与资产沉淀（20 分） + +### 参考 Review 结论 + +**结论：可以合入，但建议在合入前补充测试用例。** + +检查范围是 `review-diff.patch` 的两处改动：`SysUserServiceImpl.updateStatus` 和新增的 `SysUserServiceImplTest`。 + +| 级别 | 结论 | 证据 | 建议 | +|---|---|---|---| +| 通过 | 校验位于 `Integer.parseInt` 和 `userMapper.update` 前，阻止非法状态写入 | 服务实现新增条件与业务异常 | 保持 | +| 通过 | 仅允许常量 1/2，`null` 和空白均不匹配，状态 3 也被拒绝 | 两个常量比较均通过 `String.valueOf` | 保持 | +| 通过 | 没有删除缓存失效注解、接口权限或管理员保护 | diff 只改 Service 校验和新增测试 | 保持 | +| 建议 | 新测试仅覆盖 `"3"`，未直接覆盖 `null`、空白、`"1"`、`"2"` 和 mapper 未调用 | 新增测试类只有一个 `assertThrows` | 加参数化负例和合法值的 mapper 交互断言 | +| 残余风险 | Controller 对异常统一返回的语义、批量更新原子性和集群缓存行为不属于本 diff 的直接变更 | 原始 Controller 和框架配置 | 作为后续集成测试范围，不阻断本次最小修复 | + +不能仅写“代码没问题”。若给出“未发现阻断问题”，仍须写清检查范围、证据和残余风险。 + +### 参考 PR 说明 + +**背景**：系统用户批量冻结/解冻接口会将请求中的 `status` 传入 Service。前端选项限制不能替代服务端边界，非法值应在数据写入前被拒绝。 + +**实现**：在 `SysUserServiceImpl.updateStatus` 增加状态白名单，仅允许解冻（1）和冻结（2）；非法值抛出 `JeecgBootException`。保留原缓存失效、Controller 权限和管理员保护。 + +**测试**：新增非法状态 `"3"` 的单元测试。合入前建议补充 `null`、空白、`"1"`、`"2"` 及接口权限/管理员保护的测试；每项测试状态必须按实际执行情况填写。 + +**风险与回退**：该变更会拒绝过去可能被错误接受的状态值，属于预期的业务收紧。出现兼容性问题时可回退本次 Service 白名单提交；不能通过放宽为任意整数解决。 + +### 参考可复用 Prompt + +```text +基于指定 Git 提交审查一个状态更新 diff。先输出 Controller -> Service -> Mapper/缓存的调用链， +再判断校验是否发生在所有数据写入和可见副作用之前。只接受代码中已定义的状态常量；列出保留的 +权限、关键账号保护、缓存和审计逻辑。最后按“阻断问题 / 建议 / 残余风险 / 测试矩阵”输出， +每项都给出文件路径和符号。没有执行的测试必须标为未执行，不能推断为通过。 +``` + +验收方式：输出必须能标出校验位置、常量来源、未改动保护和至少一项负例及正例测试；不能凭空声称测试成功。 + +### 参考 Checklist 设计卡 + +| 项目 | 内容 | +|---|---| +| 名称 | 状态变更服务端边界 Checklist | +| 适用场景 | 新增或修改“启用/停用/冻结/解冻/审批状态”等服务端状态写入逻辑时 | +| 输入 | 固定提交、变更 diff、状态常量定义、调用入口 | +| 检查项 | 1. 合法状态是否白名单化；2. 校验是否早于解析、写库和副作用；3. 权限和关键账号保护是否保留；4. 缓存/审计/事件是否明确；5. 正负例和接口授权测试是否如实记录 | +| 输出 | Review 结论、证据表、测试矩阵、残余风险 | +| 边界 | 只辅助检查，不能替代实际权限配置、集成测试和人工业务审批 | +| 验收 | 每项结论都有文件路径和符号；未执行测试有原因与后续验证计划 | + +## AI 使用记录的判分口径 + +不提供统一的“标准 Prompt 列表”。满分记录应至少能够说明：使用 AI 或 TRAE 做了什么、建议是什么、哪些被采纳或否决、人工为什么这样判断、相应证据或测试是否真的执行。工具名称可以不同；缺少 `trae-usage-record.md` 时，本题“AI 使用记录”2 分为 0 分。 diff --git a/exams/exam-kit/review-diff.patch b/exams/exam-kit/review-diff.patch new file mode 100644 index 0000000..ce92a3c --- /dev/null +++ b/exams/exam-kit/review-diff.patch @@ -0,0 +1,37 @@ +diff --git a/jeecg-boot/jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/system/service/impl/SysUserServiceImpl.java b/jeecg-boot/jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/system/service/impl/SysUserServiceImpl.java +index c2fe868..236b4f2 100644 +--- a/jeecg-boot/jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/system/service/impl/SysUserServiceImpl.java ++++ b/jeecg-boot/jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/system/service/impl/SysUserServiceImpl.java +@@ -1464,6 +1464,10 @@ public class SysUserServiceImpl extends ServiceImpl impl + @Override + @CacheEvict(value={CacheConstant.SYS_USERS_CACHE}, allEntries=true) + public void updateStatus(String id, String status) { ++ if (!String.valueOf(CommonConstant.USER_UNFREEZE).equals(status) ++ && !String.valueOf(CommonConstant.USER_FREEZE).equals(status)) { ++ throw new JeecgBootException("账号状态仅支持冻结或解冻"); ++ } + userMapper.update(new SysUser().setStatus(Integer.parseInt(status)), + new UpdateWrapper().lambda().eq(SysUser::getId,id)); + } +diff --git a/jeecg-boot/jeecg-module-system/jeecg-system-biz/src/test/java/org/jeecg/modules/system/service/impl/SysUserServiceImplTest.java b/jeecg-boot/jeecg-module-system/jeecg-system-biz/src/test/java/org/jeecg/modules/system/service/impl/SysUserServiceImplTest.java +new file mode 100644 +index 0000000..082f21a +--- /dev/null ++++ b/jeecg-boot/jeecg-module-system/jeecg-system-biz/src/test/java/org/jeecg/modules/system/service/impl/SysUserServiceImplTest.java +@@ -0,0 +1,16 @@ ++package org.jeecg.modules.system.service.impl; ++ ++import org.jeecg.common.exception.JeecgBootException; ++import org.junit.jupiter.api.Test; ++ ++import static org.junit.jupiter.api.Assertions.assertThrows; ++ ++class SysUserServiceImplTest { ++ ++ @Test ++ void rejectsAStatusOutsideFreezeAndUnfreezeBeforeUpdatingUser() { ++ SysUserServiceImpl service = new SysUserServiceImpl(); ++ ++ assertThrows(JeecgBootException.class, () -> service.updateStatus("user-1", "3")); ++ } ++} diff --git a/exams/exam-kit/source-version.txt b/exams/exam-kit/source-version.txt new file mode 100644 index 0000000..154d244 --- /dev/null +++ b/exams/exam-kit/source-version.txt @@ -0,0 +1,9 @@ +repository=jeecgboot/JeecgBoot +repository_url=https://github.com/jeecgboot/JeecgBoot.git +base_ref=v3.9.2 +base_commit=7df07a823fd558be857d0208ccae96342539fbc1 +controller_path=jeecg-boot/jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/system/controller/SysUserController.java +service_path=jeecg-boot/jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/system/service/impl/SysUserServiceImpl.java +test_path=jeecg-boot/jeecg-module-system/jeecg-system-biz/src/test/java/org/jeecg/modules/system/service/impl/SysUserServiceImplTest.java +diff_file=review-diff.patch +diff_command=git apply --check review-diff.patch diff --git a/exams/scripts/build_reference_answer_docx.py b/exams/scripts/build_reference_answer_docx.py new file mode 100644 index 0000000..92fb3eb --- /dev/null +++ b/exams/scripts/build_reference_answer_docx.py @@ -0,0 +1,264 @@ +from pathlib import Path + +from docx import Document +from docx.enum.section import WD_SECTION +from docx.enum.table import WD_CELL_VERTICAL_ALIGNMENT +from docx.enum.text import WD_ALIGN_PARAGRAPH +from docx.oxml import OxmlElement +from docx.oxml.ns import qn +from docx.shared import Inches, Pt, RGBColor + + +ROOT = Path('/Users/smart/Documents/TRAE培训/TRAE课件/exams') +TARGET = ROOT / 'TRAE编程培训考试评估卷-实操与项目实战（阅卷参考答案）.docx' + +FONT = 'Microsoft YaHei' +BODY = 11 +BLUE = '2E74B5' +DARK_BLUE = '1F4D78' +HEADER_FILL = 'E8EEF5' +LIGHT_FILL = 'F4F6F9' +TABLE_WIDTH = 9360 + + +def set_font(run, size=BODY, bold=False, color=None, italic=False): + run.font.name = FONT + run._element.rPr.rFonts.set(qn('w:ascii'), 'Calibri') + run._element.rPr.rFonts.set(qn('w:hAnsi'), 'Calibri') + run._element.rPr.rFonts.set(qn('w:eastAsia'), FONT) + run.font.size = Pt(size) + run.bold = bold + run.italic = italic + if color: + run.font.color.rgb = RGBColor.from_string(color) + + +def shade(cell, color): + tc_pr = cell._tc.get_or_add_tcPr() + shd = OxmlElement('w:shd') + shd.set(qn('w:fill'), color) + tc_pr.append(shd) + + +def set_cell_margins(cell, top=80, start=120, bottom=80, end=120): + tc_pr = cell._tc.get_or_add_tcPr() + tc_mar = tc_pr.first_child_found_in('w:tcMar') + if tc_mar is None: + tc_mar = OxmlElement('w:tcMar') + tc_pr.append(tc_mar) + for side, value in [('top', top), ('start', start), ('bottom', bottom), ('end', end)]: + element = tc_mar.find(qn(f'w:{side}')) + if element is None: + element = OxmlElement(f'w:{side}') + tc_mar.append(element) + element.set(qn('w:w'), str(value)) + element.set(qn('w:type'), 'dxa') + + +def set_table_geometry(table, widths): + table.autofit = False + tbl_pr = table._tbl.tblPr + tbl_w = tbl_pr.first_child_found_in('w:tblW') + tbl_w.set(qn('w:w'), str(sum(widths))) + tbl_w.set(qn('w:type'), 'dxa') + tbl_ind = tbl_pr.first_child_found_in('w:tblInd') + if tbl_ind is None: + tbl_ind = OxmlElement('w:tblInd') + tbl_pr.append(tbl_ind) + tbl_ind.set(qn('w:w'), '120') + tbl_ind.set(qn('w:type'), 'dxa') + grid_cols = table._tbl.tblGrid.gridCol_lst + for grid_col, width in zip(grid_cols, widths): + grid_col.set(qn('w:w'), str(width)) + for row in table.rows: + for cell, width in zip(row.cells, widths): + tc_w = cell._tc.tcPr.tcW + tc_w.set(qn('w:w'), str(width)) + tc_w.set(qn('w:type'), 'dxa') + cell.vertical_alignment = WD_CELL_VERTICAL_ALIGNMENT.CENTER + set_cell_margins(cell) + + +def add_paragraph(doc, text='', style=None, before=0, after=6, line=1.1, color=None, bold=False, size=BODY): + paragraph = doc.add_paragraph(style=style) + paragraph.paragraph_format.space_before = Pt(before) + paragraph.paragraph_format.space_after = Pt(after) + paragraph.paragraph_format.line_spacing = line + run = paragraph.add_run(text) + set_font(run, size=size, bold=bold, color=color) + return paragraph + + +def add_heading(doc, text, level): + sizes = {1: 16, 2: 13, 3: 12} + colors = {1: BLUE, 2: BLUE, 3: DARK_BLUE} + before = {1: 16, 2: 12, 3: 8} + after = {1: 8, 2: 6, 3: 4} + paragraph = doc.add_paragraph() + paragraph.paragraph_format.space_before = Pt(before[level]) + paragraph.paragraph_format.space_after = Pt(after[level]) + paragraph.paragraph_format.keep_with_next = True + run = paragraph.add_run(text) + set_font(run, size=sizes[level], bold=True, color=colors[level]) + return paragraph + + +def add_table(doc, headers, rows, widths): + table = doc.add_table(rows=1, cols=len(headers)) + table.style = 'Table Grid' + table.rows[0]._tr.get_or_add_trPr().append(OxmlElement('w:tblHeader')) + for cell, text in zip(table.rows[0].cells, headers): + shade(cell, HEADER_FILL) + paragraph = cell.paragraphs[0] + paragraph.paragraph_format.space_after = Pt(0) + run = paragraph.add_run(text) + set_font(run, size=10, bold=True) + for values in rows: + cells = table.add_row().cells + for cell, text in zip(cells, values): + paragraph = cell.paragraphs[0] + paragraph.paragraph_format.space_after = Pt(0) + paragraph.paragraph_format.line_spacing = 1.08 + run = paragraph.add_run(text) + set_font(run, size=9.5) + set_table_geometry(table, widths) + doc.add_paragraph().paragraph_format.space_after = Pt(2) + return table + + +def add_callout(doc, label, text): + table = doc.add_table(rows=1, cols=1) + table.style = 'Table Grid' + shade(table.cell(0, 0), LIGHT_FILL) + paragraph = table.cell(0, 0).paragraphs[0] + paragraph.paragraph_format.space_after = Pt(0) + label_run = paragraph.add_run(f'{label}：') + set_font(label_run, bold=True, color=DARK_BLUE) + text_run = paragraph.add_run(text) + set_font(text_run) + set_table_geometry(table, [TABLE_WIDTH]) + doc.add_paragraph().paragraph_format.space_after = Pt(2) + + +def build_document(): + doc = Document() + section = doc.sections[0] + section.top_margin = Inches(1) + section.bottom_margin = Inches(1) + section.left_margin = Inches(1) + section.right_margin = Inches(1) + section.header_distance = Inches(0.492) + section.footer_distance = Inches(0.492) + + styles = doc.styles + normal = styles['Normal'] + normal.font.name = 'Calibri' + normal._element.rPr.rFonts.set(qn('w:eastAsia'), FONT) + normal.font.size = Pt(BODY) + normal.paragraph_format.space_after = Pt(6) + normal.paragraph_format.line_spacing = 1.1 + + header = section.header.paragraphs[0] + header.alignment = WD_ALIGN_PARAGRAPH.RIGHT + header.paragraph_format.space_after = Pt(0) + set_font(header.add_run('TRAE 编程培训 | 阅卷参考答案'), size=9, color='6B7280') + footer = section.footer.paragraphs[0] + footer.alignment = WD_ALIGN_PARAGRAPH.CENTER + footer.paragraph_format.space_after = Pt(0) + set_font(footer.add_run('阅卷专用 - 不随学生试卷发放'), size=9, color='6B7280') + + title = doc.add_paragraph() + title.paragraph_format.space_before = Pt(16) + title.paragraph_format.space_after = Pt(4) + set_font(title.add_run('TRAE 编程培训考试评估卷'), size=23, bold=True, color='0B2545') + subtitle = doc.add_paragraph() + subtitle.paragraph_format.space_after = Pt(16) + set_font(subtitle.add_run('实操与项目实战 - 阅卷参考答案'), size=14, color='475569') + for label, value in [ + ('适用试卷', '系统用户状态管理综合卷（修订版）'), + ('固定源码', 'GitHub jeecgboot/JeecgBoot，v3.9.2'), + ('固定提交', '7df07a823fd558be857d0208ccae96342539fbc1'), + ('阅卷原则', '考查证据与判断，不要求逐字复述；禁止把未执行测试写成已通过。'), + ]: + paragraph = doc.add_paragraph() + paragraph.paragraph_format.space_after = Pt(2) + set_font(paragraph.add_run(f'{label}：'), bold=True, color='1F4D78') + set_font(paragraph.add_run(value)) + + add_callout(doc, '使用说明', '本答案与 exam-kit/reference-answer.md 内容对应。学生提交可以有不同表述，但必须给出等价的源码证据、边界判断和如实的测试状态。') + + add_heading(doc, 'A 卷参考答案', 1) + add_heading(doc, '任务 1：Prompt 改写', 2) + add_paragraph(doc, '合格 Prompt 必须明确固定提交、分析范围、状态白名单目标、不可改动的保护项、输出结构和验收证据。可按以下六项核查：', after=4) + add_table(doc, ['项目', '参考要求'], [ + ('背景与目标', '在固定版本中审查批量冻结/解冻，保证 status 仅允许 1/2 且在写库前校验。'), + ('范围', 'SysUserController.frozenBatch、ISysUserService.updateStatus、SysUserServiceImpl.updateStatus、状态常量及直接关联的保护。'), + ('约束', '不得改接口路径、system:user:frozenBatch 权限、管理员保护和缓存失效；事实、推断、待确认分开。'), + ('输出', '调用链与证据、最小改造、测试矩阵、待确认项。'), + ('验收', '每项结论写文件路径和符号；未执行测试必须如实标注。'), + ], [1800, 7560]) + + add_heading(doc, '任务 2：AI 输出辨析', 2) + add_callout(doc, '正确结论', '“页面已限制状态值，因此 Service 不需要校验”是错误结论。页面不是可信边界，调用者可直接请求接口；Service.updateStatus 在原版中直接解析 status 并更新数据库。') + add_table(doc, ['应说明的点', '参考答案'], [ + ('正确校验位置', 'SysUserServiceImpl.updateStatus 内，在 Integer.parseInt(status) 与 userMapper.update 之前。'), + ('允许值', 'CommonConstant.USER_UNFREEZE（1）和 USER_FREEZE（2）。'), + ('拒绝值', 'null、空串、空白串、3 及其他非 1/2 值，抛 JeecgBootException。'), + ('保留项', 'Controller 权限、管理员保护、@CacheEvict 和原有数据更新路径。'), + ], [1800, 7560]) + + add_heading(doc, 'B 卷参考答案', 1) + add_heading(doc, '任务 1：项目理解与影响分析', 2) + add_table(doc, ['结论', '文件路径与符号', '证明内容', '类型'], [ + ('接口与权限', 'SysUserController.java / frozenBatch', '@RequiresPermissions("system:user:frozenBatch")；PUT /sys/user/frozenBatch。', '事实'), + ('调用链', 'SysUserController.java / frozenBatch', '读取 ids，先做 checkUserAdminRejectDel，再读取 status，逐个调用 updateStatus。', '事实'), + ('服务契约', 'ISysUserService.java / updateStatus', '状态更新是 Service 接口。', '事实'), + ('写库与缓存', 'SysUserServiceImpl.java / updateStatus', '@CacheEvict；Integer.parseInt(status) 后调用 userMapper.update。', '事实'), + ('状态枚举', 'CommonConstant.java / USER_UNFREEZE、USER_FREEZE、USER_QUIT', '取值为 1、2、3；本题只允许 1、2。', '事实'), + ('管理员保护', 'SysUserServiceImpl.java / checkUserAdminRejectDel', '检测目标 ID 中的 admin 用户并抛业务异常。', '事实'), + ('登录影响', 'SysUserServiceImpl.java / 用户登录有效性检查', '状态为 USER_FREEZE 时返回“该用户已冻结”。', '事实'), + ], [1500, 3000, 3600, 1260]) + add_callout(doc, '边界判断', 'Service 白名单必须早于解析和 mapper 写入。异常返回时不完成该次状态更新；缓存失效注解、接口权限和管理员保护都不是此变更的替代项。批量原子性与跨节点缓存可列为待确认，不能直接写成事实。') + + add_heading(doc, '任务 2：最小改造与测试安全网', 2) + add_paragraph(doc, '参考改造：在 SysUserServiceImpl.updateStatus 方法开头增加状态白名单，保持已有 @CacheEvict 和 mapper 写入。', after=3) + code_table = doc.add_table(rows=1, cols=1) + code_table.style = 'Table Grid' + shade(code_table.cell(0, 0), 'F8FAFC') + code = 'if (!String.valueOf(CommonConstant.USER_UNFREEZE).equals(status)\n && !String.valueOf(CommonConstant.USER_FREEZE).equals(status)) {\n throw new JeecgBootException("账号状态仅支持冻结或解冻");\n}' + paragraph = code_table.cell(0, 0).paragraphs[0] + paragraph.paragraph_format.space_after = Pt(0) + set_font(paragraph.add_run(code), size=9.5) + set_table_geometry(code_table, [TABLE_WIDTH]) + doc.add_paragraph().paragraph_format.space_after = Pt(2) + add_table(doc, ['场景', '预期', '验证口径'], [ + ('null、空串、空白串、3', '抛 JeecgBootException；不写库。', '负例单元测试；未跑则写明原因和计划。'), + ('"1" 解冻', '更新状态 1，成功后缓存失效。', 'Service 单元测试或集成测试。'), + ('"2" 冻结', '更新状态 2，成功后缓存失效。', 'Service 单元测试或集成测试。'), + ('无权限调用', '被权限框架拒绝。', '接口/集成测试，记录账号与结果。'), + ('目标含 admin', '管理员保护拒绝更新。', 'Controller/接口测试。'), + ('冻结后登录', '登录有效性检查返回冻结错误。', '可列待环境验证，不得虚报通过。'), + ], [1950, 3660, 3750]) + add_callout(doc, '测试状态', 'review-diff.patch 中的最小测试只覆盖 status 为 "3"。父 POM 默认跳过 surefire 测试；未修改本地测试配置的学员应标注未执行，而不是将测试状态写为已通过。') + + add_heading(doc, '任务 3：Review、PR 与资产沉淀', 2) + add_table(doc, ['结论', '证据', '阅卷判断'], [ + ('可合入，建议补测', '白名单校验位于 parse 和 mapper 写入前；保护项未被删除。', '认可“无阻断问题”，但必须列检查范围和残余风险。'), + ('测试覆盖不足', '新增测试只断言 "3" 抛异常。', '建议补 null、空白、"1"、"2" 与 mapper 交互断言。'), + ('残余风险', '异常返回语义、批量原子性、跨节点缓存并非此 diff 的直接变更。', '可列后续集成验证；不能凭空断言已验证。'), + ], [1950, 4200, 3210]) + add_paragraph(doc, '参考 PR 要点：背景是前端限制不能替代服务端边界；实现是在 Service 白名单化 status；测试写明实际已跑或未跑状态；风险是业务收紧会拒绝此前错误状态，必要时回退本次白名单提交。', after=4) + add_callout(doc, '资产答案', '可复用资产应围绕“状态变更服务端边界”设计：输入固定提交、diff 和状态常量；检查白名单、校验顺序、权限/关键账号保护、缓存/审计、副作用和正负例；输出 Review、证据表、测试矩阵和残余风险。') + + add_heading(doc, 'AI 使用记录的判分口径', 1) + add_paragraph(doc, '不提供统一的逐字 Prompt。可得满分的记录需要写清：使用 AI/TRAE 做了什么、建议摘要、采纳或否决、人工判断和证据/验证状态。工具名称可以不同；缺少 trae-usage-record.md 时，任务 3 的该项 2 分为 0 分。') + + doc.core_properties.title = 'TRAE 编程培训考试评估卷（阅卷参考答案）' + doc.core_properties.subject = '系统用户状态管理综合卷阅卷参考' + doc.core_properties.author = 'TRAE 培训' + doc.save(TARGET) + print(TARGET) + + +if __name__ == '__main__': + build_document() diff --git a/exams/scripts/revise_exam_docx.py b/exams/scripts/revise_exam_docx.py new file mode 100644 index 0000000..5e159be --- /dev/null +++ b/exams/scripts/revise_exam_docx.py @@ -0,0 +1,197 @@ +from copy import deepcopy +from pathlib import Path +from docx import Document +from docx.enum.text import WD_BREAK + + +ROOT = Path('/Users/smart/Documents/TRAE培训/TRAE课件/exams') +SOURCE = ROOT / 'TRAE编程培训考试评估卷-实操与项目实战.docx' +TARGET = ROOT / 'TRAE编程培训考试评估卷-实操与项目实战（修订版）.docx' + + +def replace_paragraph(paragraph, text, bold=None, size=None): + first_run = paragraph.runs[0] if paragraph.runs else None + old_bold = first_run.bold if first_run else None + old_size = first_run.font.size if first_run else None + paragraph.clear() + run = paragraph.add_run(text) + run.bold = old_bold if bold is None else bold + if size is not None: + run.font.size = size + elif old_size is not None: + run.font.size = old_size + return paragraph + + +def replace_cell(cell, text, bold=None): + for paragraph in cell.paragraphs[1:]: + paragraph._element.getparent().remove(paragraph._element) + paragraph = cell.paragraphs[0] + first_run = paragraph.runs[0] if paragraph.runs else None + old_bold = first_run.bold if first_run else None + old_size = first_run.font.size if first_run else None + paragraph.clear() + run = paragraph.add_run(text) + run.bold = old_bold if bold is None else bold + if old_size is not None: + run.font.size = old_size + + +def find_paragraph(document, text): + for paragraph in document.paragraphs: + if text in paragraph.text: + return paragraph + raise ValueError(f'Paragraph not found: {text}') + + +def set_table_rows(table, rows): + while len(table.rows) < len(rows): + table.add_row() + if len(table.rows) != len(rows): + raise ValueError('Unexpected table row count') + for row, values in zip(table.rows, rows): + if len(row.cells) != len(values): + raise ValueError('Unexpected table column count') + for cell, value in zip(row.cells, values): + replace_cell(cell, value) + + +def clone_paragraph(document, source_paragraph, text): + paragraph = document.add_paragraph() + placeholder = paragraph._p + element = deepcopy(source_paragraph._element) + placeholder.getparent().replace(placeholder, element) + paragraph._p = paragraph._element = element + replace_paragraph(paragraph, text) + return paragraph + + +def clone_table(document, source_table): + table = document.add_table(rows=1, cols=1) + placeholder = table._tbl + element = deepcopy(source_table._element) + placeholder.getparent().replace(placeholder, element) + table._tbl = table._element = element + return table + + +def insert_after(anchor, element): + anchor._element.addnext(element._element) + + +doc = Document(SOURCE) + +replace_paragraph(find_paragraph(doc, '实操 + 公务用车项目实战综合卷'), '实操 + 系统用户状态管理综合卷') + +# 1. Fixed time: 20 minutes for A, 60 for B, 10 for submission check. +set_table_rows(doc.tables[0], [ + ['项目', '说明'], + ['适用对象', '参加 TRAE 编程培训并完成 JeecgBoot 实战的技术学员。'], + ['考试形式', '允许使用 TRAE，上机完成；提交 Markdown 产物包与 AI 使用记录。'], + ['建议时长', '90 分钟：A 卷 20 分钟，B 卷 60 分钟，提交检查 10 分钟。'], + ['总分', '100 分：小实操 30 分，项目实战 70 分。'], + ['评估目标', '考察学员能否把真实研发问题拆成 TRAE 可执行、团队可验收、后续可复用的工程任务。'], +]) +set_table_rows(doc.tables[2], [ + ['部分', '时间', '分值', '形式', '核心能力'], + ['A. 小实操', '20 分钟', '30 分', '个人完成', 'Prompt 改写、证据判断'], + ['B. 项目实战', '60 分钟', '70 分', '个人完成', '项目理解、变更边界、测试安全网、Review 与交付'], + ['提交检查', '10 分钟', '-', '个人完成', '核对目录、文件名与执行状态'], + ['合计', '90 分钟', '100 分', '上机 + 文档交付', '个人基本功 + 项目落地能力'], +]) + +# 2. Deliverable templates and missing-file treatment. +replace_paragraph(find_paragraph(doc, '建议要求学员提交一个 Markdown 目录包'), '使用 exam-kit/exam-output/ 中的模板提交，目录和文件名不得改动：') +set_table_rows(doc.tables[3], [ + ['文件', '主要内容'], + ['01-project-understanding.md', '结论摘要、证据表、影响与保护边界、待确认项'], + ['02-change-and-test.md', '验收标准、校验位置、不改动项、测试矩阵、执行状态'], + ['03-pr-and-assets.md', 'Review、PR 说明、可复用 Prompt、Rule/Checklist/Skill 设计卡'], + ['trae-usage-record.md', 'Prompt、采纳/否决、人工判断点、证据或验证状态；缺失则任务 3 的如实记录项计 0 分'], +]) + +# Insert the fixed source / tools contract after the deliverable table. +input_heading = clone_paragraph(doc, find_paragraph(doc, '二、最终提交物'), '考试输入与作答约束') +input_intro = clone_paragraph(doc, find_paragraph(doc, '使用 exam-kit/exam-output/'), 'B 卷仅以 exam-kit/ 中的固定版本、指定 diff 和模板为准。') +input_table = clone_table(doc, doc.tables[3]) +set_table_rows(input_table, [ + ['项目', '统一要求'], + ['固定源码', 'GitHub jeecgboot/JeecgBoot；标签 v3.9.2：7df07a823fd558be857d0208ccae96342539fbc1。'], + ['指定模块', 'jeecg-module-system；以 SysUserController.frozenBatch 和 SysUserServiceImpl.updateStatus 为事实入口。'], + ['指定 diff', 'exam-kit/review-diff.patch；仅以该两文件变更为 Review 输入。'], + ['允许材料', 'TRAE、GitHub 固定版本与 exam-kit；版本不一致时记录环境问题并联系监考人员。'], +]) +anchor = doc.tables[3] +insert_after(anchor, input_heading) +insert_after(input_heading, input_intro) +insert_after(input_intro, input_table) + +replace_paragraph(find_paragraph(doc, '本部分由学员个人完成，重点考察 TRAE 基础使用'), '本部分由学员个人完成，重点考察 TRAE 基础使用与 AI 协作基本功。限时 20 分钟。') +replace_cell(doc.tables[5].cell(0, 0), '原始 Prompt\n帮我看一下系统用户批量冻结/解冻功能有没有问题。') +replace_cell(doc.tables[7].cell(0, 0), 'AI 输出片段\n页面已限制状态值，因此 Service 不需要校验；直接调用接口也不会有问题。') +replace_paragraph(find_paragraph(doc, 'B 卷：公务用车项目实战'), 'B 卷：系统用户状态管理项目实战（70 分）') +replace_paragraph(find_paragraph(doc, '本部分使用 JeecgBoot 现有公务用车模块'), '本部分使用 exam-kit 指定版本的 JeecgBoot 系统用户模块，由学员个人完成。限时 60 分钟。') +replace_cell(doc.tables[9].cell(0, 0), '实战任务背景\n案例使用 GitHub 公开的 JeecgBoot v3.9.2 中系统用户模块。训练改造要求：批量冻结/解冻用户时，后端必须拒绝空白或 1、2 之外的状态值；页面限制不能替代 Service 入口的业务保护。本次考试不要求完整开发所有代码，重点考察如何使用 TRAE 完成项目理解、变更边界分析、测试设计、Review 和资产沉淀。') + +# 3. Observable requirements for B tasks. +replace_paragraph(find_paragraph(doc, '使用 TRAE 输出公务用车模块结构说明'), '使用 TRAE 完成 01-project-understanding.md：说明系统用户模块结构、批量冻结/解冻接口、Service 入口、权限、管理员保护、缓存和测试入口。证据表至少含 5 条有效依据，每条必须写文件路径、符号或方法，以及它证明的结论；另说明非法状态值与接口、用户状态写入、缓存失效的影响关系，并区分事实、推断和待确认项。') +replace_paragraph(find_paragraph(doc, '输出最小改造方案和测试安全网'), '完成 02-change-and-test.md：说明应在哪个方法、哪次用户状态写入之前校验非法状态值；列出不改动的接口权限、管理员保护和缓存失效逻辑及依据；为空白或非法状态、正常冻结、正常解冻、无权限调用、管理员保护与缓存/用户状态回归逐项写明预期结果、验证入口、执行状态。已执行项必须给出命令和结果，未执行项必须说明原因和计划验证方式。') +replace_paragraph(find_paragraph(doc, '基于 `main...training/require-cancel-reason`'), '基于 exam-kit/review-diff.patch 的实际两文件 diff，完成 03-pr-and-assets.md：生成 Review 和 PR 说明，再输出一条可复用 Prompt 及一条 Rule、Checklist 或 Skill 设计卡。Review 可以得出“未发现阻断问题”的结论，但必须说明检查范围、证据和残余风险；所有已执行与未执行的验证必须如实标注。') + +# 4. Replace vague scoring with observable, non-overlapping criteria. +set_table_rows(doc.tables[6], [ + ['评分项', '分值'], + ['背景与目标清楚', '3'], + ['范围可控，限定目录、文件、接口或页面', '2'], + ['约束清楚，含项目规则、安全、权限、测试要求及信息不足时先提问', '4'], + ['输出格式明确，如表格、清单、报告或 PR 说明', '3'], + ['验收标准和证据要求明确', '3'], +]) +set_table_rows(doc.tables[10], [ + ['评分项', '分值'], + ['系统用户模块与批量冻结/解冻入口明确', '4'], + ['frozenBatch 接口、Controller 与 Service 调用链明确', '5'], + ['权限、管理员保护、缓存和测试入口明确', '4'], + ['至少 5 条有效证据，每条含路径、符号和证明内容', '7'], + ['影响与保护边界完整，并区分事实、推断和待确认项', '5'], +]) +set_table_rows(doc.tables[11], [ + ['评分项', '分值'], + ['状态校验改造目标和验收标准清楚', '4'], + ['校验方法、位置和副作用前后顺序正确', '5'], + ['不改动项及其依据清楚', '4'], + ['非法状态、冻结、解冻、权限、管理员保护/缓存五类场景完整', '8'], + ['验证命令、执行结果或未执行原因明确', '4'], +]) +set_table_rows(doc.tables[12], [ + ['评分项', '分值'], + ['Review 结论、证据、风险和验收方式完整', '5'], + ['PR 说明包含背景、实现、测试和风险', '5'], + ['可复用 Prompt 的输入、约束、输出和验收清楚', '5'], + ['Rule、Checklist 或 Skill 设计卡的边界和验收清楚', '3'], + ['AI 使用记录完整；不编造测试结果，能说明人工取舍', '2'], +]) +replace_paragraph(find_paragraph(doc, '三、综合评分维度'), '三、阅卷通用原则（不重复计分）') +set_table_rows(doc.tables[13], [ + ['阅卷原则', '优秀表现', '使用方式'], + ['证据意识', '结论能引用文件、函数、接口、日志或数据来源', '仅用于判断对应任务中的证据项，不单独追加扣分'], + ['上下文选择', '知道先全局找路，再文件聚焦，再代码细查', '仅用于判断对应任务中的任务表达与证据项'], + ['任务表达', '背景、目标、范围、约束、输出、验收完整', '仅用于判断 A 卷 Prompt 改写项'], + ['风险意识', '能识别权限、状态、审计、异常态、测试缺口', '仅用于判断 B 卷影响、测试和 Review 项'], + ['人机协作', '知道哪些让 AI 做，哪些必须人工确认', '仅用于判断 AI 使用记录与待确认项'], + ['资产意识', '能沉淀可复用 Prompt、Rule、Checklist、Skill', '仅用于判断任务 3 的资产项'], +]) + +set_table_rows(doc.tables[15], [ + ['环节', '要求'], + ['发卷前检查', '发放 exam-kit；核对 GitHub 仓库、v3.9.2 完整提交和 review-diff.patch 均可读取。'], + ['考试输入', '考试前完成 GitHub 固定版本下载；版本不一致时由监考人员处理，不得由学员自行替换版本。'], + ['过程记录', '必须提交 trae-usage-record.md；缺失时任务 3 的 AI 使用记录项计 0 分。'], + ['阅卷方式', '先核对四个交付文件，再按对应评分表打分；通用原则不重复扣分。'], + ['独立作答', '抽查关键路径、证据来源和人工取舍，确认交付物与作答者理解一致。'], +]) + +doc.core_properties.title = 'TRAE 编程培训考试评估卷（修订版）' +doc.core_properties.subject = '实操与系统用户状态管理综合卷' +doc.save(TARGET) +print(TARGET) diff --git a/exams/~$AE编程培训考试评估卷-实操与项目实战（修订版）.docx b/exams/~$AE编程培训考试评估卷-实操与项目实战（修订版）.docx new file mode 100644 index 0000000..1215360 Binary files /dev/null and b/exams/~$AE编程培训考试评估卷-实操与项目实战（修订版）.docx differ diff --git a/slidev/pages/day1.md b/slidev/pages/day1.md deleted file mode 100644 index 182ad58..0000000 --- a/slidev/pages/day1.md +++ /dev/null @@ -1,517 +0,0 @@ ---- -layout: cover -background: https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=1920&q=80 ---- - -# 第 1 天：TRAE 基础工作流与陌生代码库理解 - -
-真实项目案例：若依 RuoYi-Vue / RuoYi-Vue3 -
- -
-主线任务：理解「登录 → 用户信息 → 菜单路由 → 按钮权限」调用链路 -
- ---- - -# 为什么选若依作为案例？ - -
- -
-
-
若依的特点
-
- -- 🏢 足够**真实** — 不是 demo，是完整后台管理系统 -- 📋 足够**典型** — 用户、角色、菜单、权限、日志、字典 -- 🔗 足够**复杂** — 前后端分离、多模块、多层级 - -
-
-
- -
-
-
适合训练的维度
-
- -- 陌生代码库理解 -- 前后端分离结构分析 -- 登录认证链路 -- 动态菜单与路由 -- 角色与权限体系 -- 按钮权限控制 -- 操作日志审计 - -
-
-
- -
- ---- - -# 今天训练四个动作 - -
- -
-
- 🏗️ -
-
看结构
-
目录、模块
分层、技术栈
-
- -
-
- 🔍 -
-
找入口
-
登录、用户信息
菜单、权限入口
-
- -
-
- 🔗 -
-
追链路
-
从登录到路由
到按钮权限
-
- -
-
- ✅ -
-
查依据
-
每个结论
验证文件来源
-
- -
- -
-最终产出：若依权限与菜单模块代码理解报告 -
- ---- - -# 模块 1：TRAE 在真实研发中的定位 - -
- -
-
TRAE 适合辅助
-
- -- 检索代码 -- 解释函数 -- 梳理结构 -- 生成链路初稿 -- 生成文档初稿 - -
-
- -
-
不能直接替代
-
- -- 业务判断 -- 权限决策 -- 安全判断 -- 上线决策 - -
-
- -
- -
-核心区分： -代码事实（代码现在怎么写） vs -业务事实（业务应该怎么规定）
-TRAE 擅长发现代码事实，人工必须判断业务事实 -
- ---- - -# 模块 2：若依核心业务对象 - -
- -```mermaid {scale: 0.85} -graph LR - U[User 用户] -->|绑定| R[Role 角色] - R -->|授权| M[Menu 菜单] - M -->|包含| P[Permission 权限字符] - P -->|控制| A[页面/按钮/接口] - U -->|属于| D[Dept 部门] - R -->|数据权限| D -``` - -
- -
- -
-
页面权限
-能不能看到某个菜单页面 -
- -
-
按钮权限
-能不能操作新增/修改/删除 -
- -
-
数据权限
-能看到哪些部门范围的数据 -
- -
- ---- - -# 模块 3：@workspace 理解全局结构 - -
- -
- -**标准 Prompt：** - -``` -@workspace 请分析若依项目全局结构。 - -维度： -1. 前端目录 2. 后端目录 -3. 登录认证 4. 动态路由 -5. API 封装 6. 权限控制 -7. 操作日志 8. 代码生成 -9. 测试与构建 10. 不确定点 - -每个结论标注依据文件。 -``` - -
-
- -
-⚠️ 不要问：「@workspace 帮我看看若依项目」— 太泛泛，会得到空洞总结 -
- ---- -layout: two-cols -layoutClass: gap-6 ---- - -# 若依前后端结构重点 - -
- -### 前端重点目录 - -| 目录 | 职责 | -|------|------| -| `src/api` | 接口封装 | -| `src/router` | 路由配置 | -| `src/store` | 状态管理 | -| `src/views` | 页面组件 | -| `src/directive` | 权限指令 | -| `src/permission` | 路由守卫 | -| `src/utils/request` | 请求拦截 | - -
- -::right:: - -
- -### 后端重点模块 - -| 模块 | 职责 | -|------|------| -| `ruoyi-admin` | 启动+接口 | -| `ruoyi-framework` | 框架配置 | -| `ruoyi-system` | 业务逻辑 | -| `ruoyi-common` | 公共工具 | - -
- -**分层结构：** Controller → Service → Mapper - -
-
- ---- - -# 模块 4：核心调用链路 - -
- -```mermaid {scale: 0.8} -graph TD - A[用户登录] --> B[获取 Token] - B --> C[获取用户信息 getInfo] - C --> D[获取菜单路由 getRouters] - D --> E[生成动态路由] - E --> F[进入系统页面] - F --> G[权限字符控制按钮] -``` - -
- -
-
登录页面
-
API 调用
-
后端 Controller
-
状态更新
-
- ---- - -# 登录认证链路 - -
- -
- -
1. 用户输入账号密码
-
↓
-
2. Login 页面提交
-
↓
-
3. 调用 login API
-
↓
-
4. 后端认证用户
-
↓
-
5. 返回 Token
-
↓
-
6. 前端保存 Token
-
↓
-
7. Request 拦截器携带 Token
- -
- -
-
-
重点确认
-
- -- Token 存储在哪里？ -- Request 拦截器在哪里带 Token？ -- Token 失效后如何处理？ -- 是否有刷新 Token 机制？ - -
-
-
- -
- ---- - -# 动态路由加载链路 - -
- -
-
1. 调用 getRouters
-
↓
-
2. 后端返回菜单树
-
↓
-
3. 前端转换为路由对象
-
↓
-
4. 动态挂载路由 (addRoute)
-
↓
-
5. 渲染侧边栏菜单
-
↓
-
6. 用户进入页面
-
- -
-
-
菜单类型
-
- -| 类型 | 说明 | -|------|------| -| 目录 | M - 包含子菜单 | -| 菜单 | C - 对应页面组件 | -| 按钮 | F - 权限字符 | - -
-
-
- -
- ---- - -# 按钮权限链路 - -
- -```mermaid {scale: 0.85} -graph LR - A[菜单配置权限字符] --> B[角色授权该字符] - B --> C[getInfo 返回 permissions] - C --> D[前端权限指令判断] - D --> E[按钮显示/隐藏] -``` - -
- -
- -
-
⚠️ 关键警告
-
- -前端按钮权限 **只能控制 UI 展示** - -如果用户绕过前端直接请求后端接口，安全由后端接口权限决定 - -
-
- -
-
必须确认
-
- -- Controller 是否有权限注解？ -- Service 是否校验数据权限？ -- 不能只看前端就下结论 - -
-
- -
- ---- - -# 模块 5：AI 输出可信度判断 - -
- -
-
❌ 不可信回答
-
-「若依已经实现了完整权限控制，用户登录后会自动加载菜单和按钮权限，后端接口也都有权限校验，整体风险较低。」 -
-
-无文件路径 · 无函数名 · 无依据 · 无不确定点 -
-
- -
-
✅ 可信回答
-
-「前端登录成功后调用 getInfo 获取用户信息和权限字符。随后调用 getRouters 获取动态路由菜单。可确认前端存在菜单和按钮权限控制。但仍需检查后端 Controller 权限注解。」 -
-
-有依据 · 有调用关系 · 区分前后端 · 标注不确定点 -
-
- -
- ---- - -# 可信结论四件套 - -
- -
-
📁
-
文件路径
-
前端 api 文件
后端 Controller
-
- -
-
⚙️
-
函数/类/注解
-
getInfo · getRouters
权限注解
-
- -
-
🔗
-
调用关系
-
登录→token→info
→routes→权限
-
- -
-
❓
-
不确定点
-
无法确认的内容
必须标注
-
- -
- -
-没有这四项内容的 AI 输出，不能轻易采纳进入报告 -
- ---- - -# 模块 6：代码理解报告结构 - -
- -| 章节 | 内容要求 | -|------|---------| -| 模块职责 | 具体说明，不能写空话 | -| 核心对象 | User / Role / Menu / Permission / Dept | -| 目录与文件 | 标注和权限主线的关系 | -| 核心调用链路 | 拆分子链路，标注依据 | -| 权限风险 | 风险描述 + 触发条件 + 影响 + 验证 | -| 操作日志风险 | 哪些操作缺失日志 | -| 改造建议 | 文件 + 方法 + 验收标准 | -| 不确定结论 | 必须单独列出 | - -
- -
-风险写法要求：不能写「权限有风险」，必须具体到触发条件 + 影响范围 + 验证方式 -
- ---- -layout: center ---- - -# 第 1 天交付物 - -
- -
-
01
-TRAE 使用边界清单 -
- -
-
02
-若依模块认知图 -
- -
-
03
-若依项目结构图 -
- -
-
04
-权限调用链路图 -
- -
-
05
-TRAE 输出校验清单 -
- -
-
06
-代码理解报告 -
- -
diff --git a/slidev/pages/day1/m1-trae-positioning.md b/slidev/pages/day1/m1-trae-positioning.md index 66000f0..400a754 100644 --- a/slidev/pages/day1/m1-trae-positioning.md +++ b/slidev/pages/day1/m1-trae-positioning.md @@ -91,7 +91,7 @@ AI 会替代一部分重复性、低上下文、低判断含量的工作方式 --- -# 第一天真正要学什么？ +# 陌生项目分析的四个动作
diff --git a/slidev/pages/day1/m3-workspace-structure.md b/slidev/pages/day1/m3-workspace-structure.md index ea1b9c8..65bf9ac 100644 --- a/slidev/pages/day1/m3-workspace-structure.md +++ b/slidev/pages/day1/m3-workspace-structure.md @@ -1,4 +1,4 @@ -# 模块 3：不要让 AI 泛泛总结项目 +# 模块 3：项目理解的证据化提问
diff --git a/slidev/pages/day1/m4-call-chain.md b/slidev/pages/day1/m4-call-chain.md index f184689..3acad8a 100644 --- a/slidev/pages/day1/m4-call-chain.md +++ b/slidev/pages/day1/m4-call-chain.md @@ -1,8 +1,8 @@ -# 模块 4：第一天核心链路 +# 模块 4：权限与认证核心链路
-```mermaid {scale: 0.75} +```mermaid {scale: 0.6} graph TD A[用户登录] --> B[获取 token] B --> C[获取用户信息] diff --git a/slidev/pages/day1/m6-code-report.md b/slidev/pages/day1/m6-code-report.md index 700265f..bc8fae4 100644 --- a/slidev/pages/day1/m6-code-report.md +++ b/slidev/pages/day1/m6-code-report.md @@ -122,7 +122,7 @@ User 用户 · Role 角色 · Menu 菜单 · Permission 权限字符 · Dept 部 --- -# 第 1 天最终交付物 +# 项目认知的可审查产物
01 TRAE 使用边界清单
diff --git a/slidev/pages/day2.md b/slidev/pages/day2.md deleted file mode 100644 index 20db772..0000000 --- a/slidev/pages/day2.md +++ /dev/null @@ -1,553 +0,0 @@ ---- -layout: cover -background: https://images.unsplash.com/photo-1558494949-ef010cbdcc31?w=1920&q=80 ---- - -# 第 2 天：TRAE 上下文工程与规则体系 - -
-让 TRAE 按团队规则改代码 — 从代码理解到研发治理 -
- -
-上下文决定 AI 看什么 · 规则决定 AI 怎么做 · 资产化决定团队怎么复用 -
- ---- - -# 第 1 天到第 2 天的跨越 - -
- -
-
第 1 天
-
让 TRAE 看懂若依代码
-
-看结构 · 找入口 · 追链路 · 查依据 -
-
- -
-
第 2 天
-
让 TRAE 按团队规则改代码
-
-组织上下文 · 控制幻觉 · 编写 rules · 沉淀资产 -
-
- -
- -
-核心变化：当团队多人都使用 AI 时，必须有统一上下文、统一 rules、统一验收标准，否则 AI 会带来不一致甚至风险。 -
- ---- - -# 若依场景下的团队规则问题 - -
-
-
若依类后台项目常见风险
-
- -
- -- 🚨 绕过权限，页面直接调接口 -- 🚨 按钮权限当安全边界 -- 🚨 接口缺少权限注解 -- 🚨 操作日志缺失 - -
- -
- -- 🚨 代码生成后直接上线 -- 🚨 敏感信息进入日志 -- 🚨 数据权限范围不清 -- 🚨 AI 修改未经复核 - -
- -
-
-
- -
-今天要把这些隐性开发要求写成规则，让 TRAE 长期遵守 -
- ---- - -# 今天三个关键词 - -
- -
-
- 🎯 -
-
上下文
-
决定 AI 看什么
-
整个项目 vs 单模块 vs 单文件
-
- -
-
- 📏 -
-
规则
-
决定 AI 怎么做
-
不能绕过权限 · 不能遗漏日志
-
- -
-
- 📦 -
-
资产化
-
决定团队怎么复用
-
Prompt · Rules · 模板
-
- -
- ---- - -# 模块 1：上下文工程 — 好任务五要素 - -
- -
-好任务 = 目标 + 范围 + 约束 + 输出格式 + 验收标准 -
- -
- -
- -
-
❌ 坏 Prompt
- -``` -@workspace 帮我检查若依权限有没有问题。 -``` - -
目标不清 · 范围不清 · 约束不清 · 输出不清
-
- -
-
✅ 好 Prompt
- -``` -@workspace 分析若依用户管理页面按钮权限调用链路 - -范围：只分析新增/修改/删除按钮 -约束：不修改代码；标注文件和函数 -输出：表格 -验收：覆盖按钮/权限字符/前端判断/后端接口 -``` - -
- -
- ---- - -# 模块 2：四类上下文工具 - -
- -
-
-@workspace -找路 -
-
全局搜索入口、文件、模块
-
如：找 getInfo、getRouters、权限指令
-
- -
-
-#File -看文件 -
-
分析指定文件间的调用关系
-
如：分析用户 Controller 和 Service
-
- -
-
-#Code -抠细节 -
-
分析单个方法的参数、调用、异常
-
如：分析 handleLogin 函数
-
- -
-
-#Web -查外部 -
-
查询框架文档或最佳实践
-
但若依当前实现必须回到代码验证
-
- -
- ---- - -# 模块 3：幻觉死循环切断 - -
- -
-
常见幻觉表现
-
-
AI 说所有接口都有权限校验
但不给 Controller 依据
-
AI 说操作日志完整
但不给注解或 AOP 依据
-
AI 说按钮权限安全
但只看到前端代码
-
-
- -
- -
-
1️⃣
-
先找证据
-
文件 · 类 · 方法 · 注解
-
- -
-
2️⃣
-
再判断原因
-
区分事实和推测
-
- -
-
3️⃣
-
最后给方案
-
修改 · 影响 · 验证
-
- -
- -
- ---- - -# 证据收集标准 Prompt - -
- -``` -请先不要修改代码。 - -请围绕"用户管理删除按钮权限"收集证据： - -1. 前端按钮在哪个页面 -2. 使用了哪个权限字符 -3. 前端如何判断按钮显示 -4. 后端删除接口在哪里 -5. Controller 是否有权限注解 -6. 是否记录操作日志 -7. 无法确认的内容 -``` - -
- -
-先收集证据，再判断风险，最后才给方案。
不要让 AI 跳过证据直接给结论。 -
- ---- - -# 模块 4：.gitignore 与敏感配置 - -
- -
-
不应提交的文件
-
- -- `.env` 环境变量 -- `application-dev.yml` 真实密码 -- 数据库账号 / Redis 密码 -- `target/` 编译产物 -- `node_modules/` / `dist/` -- 日志文件 -- IDE 本地配置 - -
-
- -
-
敏感配置规则
-
- -- 禁止硬编码数据库密码 -- 禁止硬编码 Redis 密码 -- 禁止硬编码 JWT 密钥 -- 禁止硬编码第三方密钥 -- 不得提交真实配置文件 -- 示例配置必须使用占位符 - -
-
- -
- ---- - -# 模块 5：.trae/rules.md 安全规则 - -
- -
-规则 1：前端按钮权限只能作为交互控制，不能作为安全边界。 -
- -
-规则 2：涉及用户、角色、菜单、部门、岗位等敏感接口时，必须检查后端 Controller 是否存在权限控制。 -
- -
-规则 3：涉及新增、修改、删除、导出等操作时，必须检查是否记录操作日志。 -
- -
-规则 4：禁止在源码中硬编码数据库密码、Redis 密码、JWT 密钥。 -
- -
-规则 5：列表查询必须确认是否需要数据权限过滤。 -
- -
- ---- - -# 模块 6：编码与测试规则 - -
- -
-
编码规则重点
-
- -- 前端接口放 `api` 目录，不在页面写请求 -- 后端遵守 Controller → Service → Mapper 分层 -- 敏感接口关注权限注解 -- 敏感操作关注日志注解 -- 列表查询关注数据权限 -- 固定枚举值使用字典 -- 代码生成结果必须人工检查 - -
-
- -
-
测试规则重点
-
- -- ✅ 登录成功 / 失败 -- ✅ 无权限访问接口返回拒绝 -- ✅ 按钮权限和权限字符匹配 -- ✅ 角色授权变化后权限更新 -- ✅ 数据权限范围正确 -- ✅ 敏感操作有日志记录 -- ✅ 代码生成 CRUD 完整性 - -
-
- -
- ---- - -# 模块 7：前端专项规则 - -
- -
-
用户管理页面规则示例
- -| 规则项 | 要求 | -|--------|------| -| 按钮权限 | 新增/修改/删除/导出必须使用权限控制 | -| 删除操作 | 必须二次确认 | -| 提交失败 | loading 必须恢复 | -| 数据刷新 | 修改后必须刷新列表 | -| 敏感字段 | 不得明文展示或输出日志 | -| 接口调用 | 统一放 api 目录 | -| 动态路由 | 不能随意绕过 | -| 字典字段 | 使用统一字典显示 | - -
-
- ---- - -# 模块 8：规则可执行性检查 - -
- -
-
❌ 坏规则
-
- -- 「注意权限安全」 -- 「代码要规范」 -- 「日志要完整」 -- 「数据权限要合理」 -- 「生成代码要检查」 - -
-
方向没错，但不可执行
-
- -
-
✅ 好规则
-
- -- 涉及用户/角色/菜单/部门/岗位的新增/修改/删除/导出接口 → **必须检查后端权限和操作日志** -- 涉及列表查询 → **必须确认数据权限过滤** -- 代码生成结果上线前 → **必须检查权限、日志、校验、异常和测试** - -
-
有触发场景 · 有必须动作 · 可被检查
-
- -
- ---- - -# 模块 9：技能与规则资产化 - -
- -``` -ai-dev-assets/ -├── prompts/若依/ # 若依相关 Prompt 模板 -│ ├── 结构分析.md -│ ├── 登录权限链路.md -│ ├── 按钮权限检查.md -│ └── 操作日志检查.md -├── rules/若依/ # 若依 rules.md -├── templates/若依/ # 报告模板 -├── checklists/若依/ # 检查清单 -│ ├── 权限检查.md -│ ├── 日志检查.md -│ └── 代码生成Review.md -└── examples/若依/ # 优秀案例 & 反面案例 -``` - -
- -
-这些资产以后可以直接用于公司内部类似后台管理系统 -
- ---- - -# 若依版 rules.md 核心条款 - -
- -
-
1
-
前端按钮权限不是安全边界
-
- -
-
2
-
敏感接口必须检查后端权限
-
- -
-
3
-
敏感操作必须检查操作日志
-
- -
-
4
-
列表查询必须考虑数据权限
-
- -
-
5
-
代码生成结果不得直接上线
-
- -
-
6
-
不确定内容必须标注
-
- -
- ---- -layout: center ---- - -# 第 2 天交付物 - -
- -
01 上下文组织清单
-
02 上下文引用模板
-
03 幻觉控制 Prompt
-
04 .gitignore 配置样例
-
05 若依安全规则
-
06 若依编码测试规则
-
07 若依前端规则
-
08 若依 AI 资产库目录
-
09 规则验收清单
-
10 若依版 rules.md v0.1
- -
- ---- - -# 两天课程总结 - -
- -
-
第 1 天：读懂若依
-
- -- 看结构 — 全局目录与模块职责 -- 找入口 — 登录、权限、菜单入口 -- 追链路 — 完整调用链路分析 -- 查依据 — 验证 AI 输出可信度 - -
-
- -
-
第 2 天：按规则参与若依
-
- -- 组织上下文 — 精准任务五要素 -- 控制幻觉 — 证据→原因→方案 -- 编写 rules — 可执行规则 -- 沉淀资产 — 团队长期复用 - -
-
- -
- -
-
-
最终能力
-
-
读得懂
-
问得准
-
查得实
-
改得稳
-
可复用
-
-
-
diff --git a/slidev/pages/day2/m1-context-engineering.md b/slidev/pages/day2/m1-context-engineering.md index 0fe5c45..f1ba112 100644 --- a/slidev/pages/day2/m1-context-engineering.md +++ b/slidev/pages/day2/m1-context-engineering.md @@ -1,15 +1,15 @@ -# 第 1 天到第 2 天 +# 从项目理解到研发治理
-**第 1 天：** 让 TRAE 看懂若依代码 +**项目理解：** 让 TRAE 看懂若依代码
-**第 2 天：** 让 TRAE 按团队规则改若依代码 +**研发治理：** 让 TRAE 按团队规则改若依代码 -核心变化：从代码理解到研发治理 +从项目事实到可执行规则
@@ -43,7 +43,7 @@ AI 可能在页面里直接新增接口调用；只做前端按钮隐藏；没 --- -# 今天三个关键词 +# 上下文、规则与资产
@@ -72,7 +72,7 @@ AI 可能在页面里直接新增接口调用；只做前端按钮隐藏；没 --- -# 第 2 天训练主线 +# 上下文工程流程
@@ -94,7 +94,7 @@ AI 可能在页面里直接新增接口调用；只做前端按钮隐藏；没
-课堂总产出：围绕若依“用户管理删除权限”完成一次证据审查，并产出一版可落地的 .trae/rules.md v0.1。 +任务产物：围绕若依“用户管理删除权限”完成证据审查，并形成可落地的 .trae/rules.md v0.1。
--- -# 第 2 天交付物 +# 上下文与规则资产
01 上下文组织清单
@@ -91,17 +90,17 @@ layout: center class: text-center --- -# 两天课程总结 +# 从项目事实到规则资产
-**第 1 天：用 TRAE 看懂若依** +**项目理解：用 TRAE 看懂若依** - 看结构 · 找入口 · 追链路 · 查依据
-**第 2 天：让 TRAE 按规则参与若依研发** +**规则资产：让 TRAE 按规则参与若依研发** - 组织上下文 · 控制幻觉 · 编写 rules · 沉淀资产
diff --git a/slidev/pages/day2/m2-four-references.md b/slidev/pages/day2/m2-four-references.md index 1fa0906..0deb94c 100644 --- a/slidev/pages/day2/m2-four-references.md +++ b/slidev/pages/day2/m2-four-references.md @@ -88,7 +88,7 @@
-课堂要求：每组至少让 TRAE 找出 3 个前端文件、2 个后端文件、1 个权限或日志相关依据。 +最低证据：至少定位 3 个前端文件、2 个后端文件，以及 1 条权限或日志相关依据。
diff --git a/slidev/pages/day2/m8-asset-library.md b/slidev/pages/day2/m8-asset-library.md index 4a35d09..c9b8a72 100644 --- a/slidev/pages/day2/m8-asset-library.md +++ b/slidev/pages/day2/m8-asset-library.md @@ -82,7 +82,7 @@ examples 存优秀案例和反面案例。 diff --git a/slidev/pages/day2/m9-rules-check.md b/slidev/pages/day2/m9-rules-check.md index 6ed7540..b48026c 100644 --- a/slidev/pages/day2/m9-rules-check.md +++ b/slidev/pages/day2/m9-rules-check.md @@ -129,7 +129,7 @@ --- diff --git a/slidev/pages/day3/m1-rules-evolution.md b/slidev/pages/day3/m1-rules-evolution.md index e5a413f..bc4b6e3 100644 --- a/slidev/pages/day3/m1-rules-evolution.md +++ b/slidev/pages/day3/m1-rules-evolution.md @@ -115,7 +115,7 @@ AGENTS.md 的价值在于跨工具复用，同一个仓库可以被多个 Agent --- -# 课堂产出：规则迁移清单 +# 规则迁移清单
diff --git a/slidev/pages/day3/m2-token-cue-agent.md b/slidev/pages/day3/m2-token-cue-agent.md index 45ad979..397ee94 100644 --- a/slidev/pages/day3/m2-token-cue-agent.md +++ b/slidev/pages/day3/m2-token-cue-agent.md @@ -137,7 +137,7 @@ Cue 的能力并没有消失，它进入了更大的 Agent 工作流。 --- -# 课堂产出：成本与任务匹配表 +# 成本与任务匹配表
diff --git a/slidev/pages/day3/m3-commands-skills-mcp.md b/slidev/pages/day3/m3-commands-skills-mcp.md index d7f54c5..f72e83c 100644 --- a/slidev/pages/day3/m3-commands-skills-mcp.md +++ b/slidev/pages/day3/m3-commands-skills-mcp.md @@ -206,7 +206,7 @@ assets 里放模板、检查清单、Prompt、反例和案例。
-| 接入方式 | 适合场景 | 课堂判断 | +| 接入方式 | 适合场景 | 选择依据 | |---|---|---| | Command | 固定话术、固定格式 | 降低重复输入 | | CLI | 命令稳定、脚本成熟 | 优先轻量封装 | @@ -223,7 +223,7 @@ MCP 是一种协议形态，CLI 是一种执行方式，Command 是轻量入口 --- -# 课堂产出：能力封装决策表 +# 能力封装决策表
diff --git a/slidev/pages/day3/m4-agent-teams-product-shape.md b/slidev/pages/day3/m4-agent-teams-product-shape.md index 80c1043..dcdac45 100644 --- a/slidev/pages/day3/m4-agent-teams-product-shape.md +++ b/slidev/pages/day3/m4-agent-teams-product-shape.md @@ -58,7 +58,7 @@ Agent Teams 适合有角色分工的复杂交付，比如设计、开发、测 @@ -172,7 +172,7 @@ AI 产品的每次调用都有真实计算成本，企业落地需要分层计 --- -# 课堂产出：Agent 分工表 +# Agent 分工表
diff --git a/slidev/pages/day3/m5-browser-docs-index.md b/slidev/pages/day3/m5-browser-docs-index.md index 578b058..e39dd17 100644 --- a/slidev/pages/day3/m5-browser-docs-index.md +++ b/slidev/pages/day3/m5-browser-docs-index.md @@ -203,7 +203,7 @@ Markdown 很适合 AI 读写。 --- -# 课堂产出：前端验证清单 +# 前端验证清单
diff --git a/slidev/pages/day3/m6-plan-review-summary.md b/slidev/pages/day3/m6-plan-review-summary.md index 9b38e34..a58a37d 100644 --- a/slidev/pages/day3/m6-plan-review-summary.md +++ b/slidev/pages/day3/m6-plan-review-summary.md @@ -127,7 +127,7 @@ Trae CLI 企业版也可以嵌入流水线，形成类似能力。
-| 第 4 天任务 | 为什么不能直接改 | Plan 里必须写清 | +| 复杂业务任务 | 为什么不能直接改 | Plan 里必须写清 | |---|---|---| | RBAC 权限矩阵 | 影响菜单、按钮、接口和数据范围 | 角色、权限字符、接口、验收账号 | | 状态流转 | 容易出现越权流转和脏状态 | 状态枚举、合法路径、非法路径 | @@ -145,7 +145,7 @@ Trae CLI 企业版也可以嵌入流水线，形成类似能力。 --- -# 第 3 天交付物 +# 任务编排资产
01 规则迁移清单
@@ -155,7 +155,7 @@ Trae CLI 企业版也可以嵌入流水线，形成类似能力。
05 前端浏览器验证清单
06 Plan 与 Review 验收清单
07 JeecgBoot 工单链路索引
-
08 第 4 天任务 Plan 草案
+
08 复杂业务任务 Plan 草案
+ +--- + +# 可直接复制到 rules：权限安全 + +
+ +```md +## 敏感操作必须四层校验 +- 级别：硬约束 +- 适用场景：新增、编辑、删除、指派、状态流转、查看审计、查看看板。 +- 必须：同时覆盖页面/菜单权限、按钮权限、后端接口权限、数据范围权限。 +- 禁止：只做页面或按钮控制。 +- 验收方式：授权角色能完成；未授权角色前端不可见且直接请求接口失败；越权数据访问失败。 + +## 权限字符必须有来源或标记为建议 +- 必须：来自现有菜单、权限配置、前端权限指令、后端鉴权注解或团队规范。 +- 禁止：凭空编造权限字符并当成事实。 +- 验收方式：权限字符在前端、菜单配置、后端接口之间一致。 + +## 数据权限不得被查询条件替代 +- 必须：后端统一校验当前用户可访问的数据范围。 +- 禁止：只依赖前端传入 userId、deptId、tenantId 或筛选条件。 +``` + +
+ + diff --git a/slidev/pages/day4/m2-permission-control.md b/slidev/pages/day4/m2-permission-control.md index 2c7b45e..9f74c41 100644 --- a/slidev/pages/day4/m2-permission-control.md +++ b/slidev/pages/day4/m2-permission-control.md @@ -102,3 +102,28 @@ work:order:dashboard 课堂实操时，不要求只看代码。 要用不同账号或模拟请求验证：前端不可见只是第一步，后端拒绝才是强制边界。 --> + +--- + +# rules 要落到这些位置 + +
+ +| rule 条款 | 代码落点 | 验证项 | +|---|---|---| +| 四层校验 | 菜单配置、按钮权限、Controller、Service 查询 | 无权限账号不可见且接口失败 | +| 权限字符有来源 | 菜单表、路由、按钮指令、后端注解 | 同一字符贯穿前后端 | +| 数据权限后端校验 | 列表、详情、导出、看板查询 | 改请求参数不能越权 | +| 敏感字段最小返回 | 列表接口、详情接口、审计展示 | 不暴露不必要 old/new value | + +
+ +
+让 TRAE 改权限前，先把相关 rule 和权限控制方案一起给它。 +
+ + diff --git a/slidev/pages/day4/m3-status-transition.md b/slidev/pages/day4/m3-status-transition.md index b8c7e99..5c8666c 100644 --- a/slidev/pages/day4/m3-status-transition.md +++ b/slidev/pages/day4/m3-status-transition.md @@ -89,3 +89,31 @@ POST /workOrder/transition 指派和状态流转建议有明确接口。 Service 层负责读取工单、校验权限、校验状态、更新状态、记录日志。 --> + +--- + +# 可直接复制到 rules：状态流转 + +
+ +```md +## 复杂业务状态必须先建模 +- 级别：硬约束 +- 适用场景：工单指派、处理、验证、驳回、关闭、重开。 +- 必须：先产出状态流转表，列出当前状态、动作、目标状态、允许角色、前置条件、后置动作和验收方式。 +- 禁止：直接在代码中堆状态判断而没有状态表。 +- 验收方式：每个状态动作都有合法路径和非法路径验证。 + +## 非法状态流转必须拒绝且状态不变 +- 必须：集中校验非法流转；失败时返回明确错误，业务状态不变，不写成功审计。 +- 禁止：仅靠前端禁用按钮防止非法流转。 +- 验收方式：构造非法状态动作，接口失败且数据库状态不变。 +``` + +
+ + diff --git a/slidev/pages/day4/m4-audit-log.md b/slidev/pages/day4/m4-audit-log.md index ad0ef58..69f689d 100644 --- a/slidev/pages/day4/m4-audit-log.md +++ b/slidev/pages/day4/m4-audit-log.md @@ -93,3 +93,31 @@ 状态更新成功但日志失败，或者日志成功但状态失败，都会造成追溯问题。 所以 Service 层要明确事务边界。 --> + +--- + +# 可直接复制到 rules：审计日志 + +
+ +```md +## 关键业务操作必须写审计 +- 级别：硬约束 +- 适用场景：创建、编辑关键字段、指派、状态流转、驳回、关闭、删除、导出、权限变更。 +- 必须：记录 actor、action、target_id、old_value、new_value、source、request_id、created_at 或项目等价字段。 +- 禁止：只记录普通日志而没有业务审计；操作失败后写成功审计。 +- 验收方式：执行关键操作后可查询审计记录，字段与实际变更一致。 + +## 审计和业务写入必须一致 +- 必须：明确审计写入时机、事务关系、失败处理和重试策略。 +- 禁止：业务成功审计丢失，或审计成功但业务失败。 +- 验收方式：模拟业务失败和审计失败，结果符合一致性策略。 +``` + +
+ + diff --git a/slidev/pages/day4/m5-exception-defensive.md b/slidev/pages/day4/m5-exception-defensive.md index 802d5a1..48969b2 100644 --- a/slidev/pages/day4/m5-exception-defensive.md +++ b/slidev/pages/day4/m5-exception-defensive.md @@ -88,3 +88,33 @@ 异常态修复很容易扩散。 课堂里要控制边界：只补工单模块相关前端状态、后端校验、Service 状态保护和审计日志。 --> + +--- + +# 可直接复制到 rules：异常态测试 + +
+ +```md +## 核心逻辑必须有测试或豁免说明 +- 级别：待确认约束 +- 适用场景：权限校验、状态流转、审计、看板指标、异常态修复。 +- 必须：优先补自动化测试；无法测试时说明原因、风险和手工验收方式。 +- 禁止：只说“已验证”但没有命令、样例、截图、接口响应或手工步骤。 + +## 权限必须做正反角色验证 +- 必须：至少验证一个授权角色和一个未授权角色；涉及数据范围时验证越权数据。 +- 禁止：只用管理员账号验证。 + +## 状态流转必须覆盖合法和非法路径 +- 必须：每个关键动作至少覆盖一条合法路径和一条非法路径。 +- 禁止：只测试从初始状态到成功终态的主链路。 +``` + +
+ + diff --git a/slidev/pages/day4/m6-dashboard-metrics.md b/slidev/pages/day4/m6-dashboard-metrics.md index 1903f55..5ba55d8 100644 --- a/slidev/pages/day4/m6-dashboard-metrics.md +++ b/slidev/pages/day4/m6-dashboard-metrics.md @@ -93,3 +93,31 @@ GET /workOrder/dashboard/trend 看板页面不是能打开就算完成。 验收要看权限、口径、空态和数字是否能解释。 --> + +--- + +# 可直接复制到 rules：看板指标 + +
+ +```md +## 看板指标必须手工抽样校验 +- 级别：硬约束 +- 适用场景：统计卡片、趋势图、分布图、排行、效能指标。 +- 必须：每个关键指标有含义、公式、过滤条件、时间字段、数据范围，并用样例数据手工校验。 +- 禁止：只验证接口返回 200 或页面有图表。 +- 来源证据：指标字典、接口契约、样例数据、数据库查询或列表数据。 +- 验收方式：至少一组样例数据的手工计算结果与接口返回一致。 +``` + +
+ +
+看板交付时要同时交付指标字典、接口契约和一组手工核对样例。 +
+ + diff --git a/slidev/pages/day4/m7-review-delivery.md b/slidev/pages/day4/m7-review-delivery.md index 3a09de5..ed8d8c9 100644 --- a/slidev/pages/day4/m7-review-delivery.md +++ b/slidev/pages/day4/m7-review-delivery.md @@ -2,7 +2,7 @@
-第四天改动涉及权限、状态、审计、异常和看板，必须做阶段 Review。 +工单模块改动涉及权限、状态、审计、异常和看板，必须做阶段 Review。
@@ -45,6 +45,61 @@ AI Review 不能只给 diff。 --- +# 复杂业务控制面的三个 Skill + +
+ +| Skill | 什么时候用 | 输入材料 | 输出产物 | +|---|---|---|---| +| design-complex-business-module | 开始写代码前 | 需求、项目规则、现有角色/API/表结构 | RBAC、权限方案、状态表、审计 SOP、异常清单、指标字典 | +| review-business-delivery | 阶段 Review 时 | diff、业务产物、测试结果、验收记录 | 问题清单、证据缺口、待确认项 | +| track-review-fix-loop | 修 Review 后 | Review 报告、修改文件、验证证据 | 修复记录、未闭环事项、资产更新建议 | + +
+ +
+Skill 负责流程和质量门禁；rule 负责长期约束；template/checklist 负责稳定输出。 +
+ + + +--- + +# design-complex-business-module 怎么用 + +
+ +```md +请使用 design-complex-business-module，基于 JeecgBoot 工单模块设计复杂业务控制面。 + +输入材料： +1. 需求范围：工单权限、状态流转、审计、异常态、看板。 +2. 项目规则：security-permission、state-audit、testing、delivery。 +3. 现有证据：角色、菜单权限、接口、数据表、相似模块。 + +输出必须包含： +RBAC 权限矩阵、权限控制方案、状态流转表、非法流转清单、 +审计日志 SOP、异常态清单、看板指标字典、看板接口验收记录。 + +要求： +没有源码或配置证据的内容标记为“建议”或“待确认”。 +``` + +
+ + + +--- + # 阶段 Review 报告
@@ -65,6 +120,36 @@ Review 输出必须结构化。 --- +# review-business-delivery 怎么用 + +
+ +```md +请使用 review-business-delivery 对本次工单模块改动做阶段 Review。 + +输入材料： +- 当天 diff 或修改文件清单 +- RBAC 权限矩阵和权限控制方案 +- 状态流转表和非法流转清单 +- 审计日志 SOP 和异常态清单 +- 看板指标字典和接口验收记录 +- 测试命令、接口响应、浏览器验证或手工验收记录 + +输出格式： +先列问题清单，按 P0/P1/P2/P3 排序； +每个问题必须有证据、风险、修复建议和验收方式； +缺少证据时单独列“证据缺口”，不要猜测。 +``` + +
+ + + +--- + # 修复记录
@@ -84,7 +169,38 @@ Review 不是结束。 --- -# 第 4 天交付物 +# track-review-fix-loop 怎么用 + +
+ +```md +请使用 track-review-fix-loop，把阶段 Review 问题转成修复闭环记录。 + +输入材料： +- 带编号的 Review 报告 +- 修改文件或产物 +- 测试输出、接口响应、浏览器截图或手工验收步骤 +- 现有 rules、checklists、prompts、examples、skills 目录 + +每个问题状态只能是： +成立-已修复 / 成立-暂不修复 / 不成立 / 需确认 / 未闭环 + +输出必须包含： +修复记录、未闭环事项、资产更新建议。 +资产类型从 rule、checklist、prompt、command、skill、example 中选择。 +``` + +
+ + + +--- + +# 复杂业务模块资产
01 工单 RBAC 权限矩阵
@@ -104,12 +220,47 @@ Review 不是结束。 这些产物共同说明：工单模块不只是能运行，还具备权限、状态、审计、异常和指标的工程闭环。 --> +--- + +# 复杂业务资产包目录 + +
+ +```text +ai-dev-assets/ +├── rules/ +│ ├── security-permission.md +│ ├── state-audit.md +│ ├── testing.md +│ └── delivery.md +├── skills/ +│ ├── design-complex-business-module/ +│ ├── review-business-delivery/ +│ └── track-review-fix-loop/ +├── templates/jeecgboot/ +├── checklists/jeecgboot/ +├── prompts/jeecgboot/ +└── examples/jeecgboot/ +``` + +
+ +
+交付给团队的不是聊天记录，而是可安装、可复用、可审查的工程资产包。 +
+ + + --- layout: center class: text-center --- -# 第 4 天总结 +# 复杂业务模块的控制面
让工单模块从“能跑通”升级到“可控制、可审计、可验证、可 Review”。 diff --git a/slidev/pages/day5/m1-project-workshop.md b/slidev/pages/day5/m1-project-workshop.md new file mode 100644 index 0000000..7b1ce12 --- /dev/null +++ b/slidev/pages/day5/m1-project-workshop.md @@ -0,0 +1,132 @@ +# 模块 1：案例引子：从状态变更提取资产原料 + +
+ +“取消原因不能为空”看起来只是一个字段校验，实际却处在派车、车辆、司机和行程状态交汇的位置。 + +这里不讨论如何完成这一项改动，而是用它识别后续可沉淀的约束、提问框架与验证方法。 + +
+ +
+
申请
+
派车
+
车辆 / 司机
+
行程
+
+ + + +--- + +# 公务用车模块中的三条状态线 + +
+ +| 对象 | 正常演进 | 取消或完成后的变化 | +|---|---|---| +| 申请 | `DRAFT -> PROCESSING -> COMPLETED` | 取消回到 `CANCELLED` | +| 派车 | `DISPATCHED -> COMPLETED` | 取消变为 `CANCELLED` | +| 车辆 | `AVAILABLE -> RESERVED -> IN_USE` | 取消或行程完成后回到 `AVAILABLE` | +| 司机 | `AVAILABLE -> ON_TASK` | 行程完成后回到 `AVAILABLE` | + +
+ +
+一个派车动作会改变多个对象；校验位置错了，错误状态就会扩散。 +
+ + + +--- + +# 取消派车的真实调用链 + +
+ +```text +取消按钮（仅 DISPATCHED 状态可见） + -> 取消弹窗（cancelReason 必填） + -> POST /official/vehicle/dispatch/cancel + -> Controller（权限 + 审计） + -> DispatchService.cancel + -> 派车状态 CANCELLED + 车辆状态 AVAILABLE +``` + +
+ +
+
前端：减少误操作
+
权限：限制谁能调用
+
Service：保护业务状态
+
+ + + +--- + +# 把业务语言变成可验证的目标 + +
+ +| 业务表达 | 可验证的技术表达 | +|---|---| +| 取消必须写原因 | `cancelReason` 不能是 `null`、空串或全空白 | +| 不允许无效取消 | 在读取派车记录、更新派车和释放车辆之前拒绝请求 | +| 不能影响正常取消 | 非空原因仍沿用原有状态更新与资源释放逻辑 | +| 不扩大改动 | 不改变权限、审计、页面交互、数据库字段或行程协议 | + +
+ +
+目标越可验证，TRAE 越不容易把一个小需求扩写成跨层重构。 +
+ + + +--- + +# 从案例中提取资产原料 + +
+
+
项目事实
+
状态、入口、权限、写入顺序和测试结构。
+
+
+
重复判断
+
哪些结论下次同类任务仍然需要重新做。
+
+
+
可沉淀资产
+
Rule、Prompt、Skill、检查单和反例各自承接什么。
+
+
+ + diff --git a/slidev/pages/day5/m10-agent-skill-composition.md b/slidev/pages/day5/m10-agent-skill-composition.md new file mode 100644 index 0000000..eb806dc --- /dev/null +++ b/slidev/pages/day5/m10-agent-skill-composition.md @@ -0,0 +1,163 @@ +# 模块 10：自定义 Agent 如何调用 Skill + +
+ +一个成熟的 Agent 不把所有知识写进自己身上。 + +它负责选择合适的工作流、加载必要资产，并将结果交给下一步；Skill 继续负责具体任务的判断顺序和交付格式。 + +
+ +
+ +```text +自定义 Agent（角色 + 工具边界） + -> 选择 Skill（任务工作流） + -> 加载 Rule / 任务上下文契约 / Checklist / Example + -> 输出结构化结论 + -> 交给 Review、PR 或下一项任务 +``` + +
+ + + +--- + +# Agent、Skill 与 MCP 的本质区别 + +
+ +| 对象 | 本质 | 负责什么 | 不负责什么 | +|---|---|---|---| +| Agent | 执行角色与权限边界 | 选择任务、调用 Skill 和工具、控制停止与交接 | 承载全部业务流程与项目事实 | +| Skill | 可复用的任务工作流 | 规定输入、判断步骤、输出与验收 | 决定谁可调用、拥有什么工具权限 | +| MCP | 外部能力接口 | 提供查询、读取、写入等工具能力 | 判断业务规则、决定任务流程 | + +
+ +
+
谁来做：Agent
+
如何做：Skill
+
能调用什么：MCP
+
+ + + +--- + +# 不同信息应该放在哪里？ + +
+ +| 信息类型 | 最合适的位置 | 原因 | +|---|---|---| +| “先取证，缺口必须暴露” | Rule / Agent 默认指令 | 多个任务都必须遵守 | +| “状态变更如何审查” | Skill | 需要多步判断与停止条件 | +| “影响分析报告长什么样” | 任务上下文契约 / Template | 下游需要固定结构 | +| “五项不可遗漏检查” | Checklist | 适合逐项核对 | +| “数据库 NOT NULL 不适用的条件” | Example / 反例 | 防止机械套用 | +| 某项目的路径、字段和日志 | 运行时输入 | 换任务或换项目会变化 | + +
+ +
+一份内容只应有一个权威位置；重复复制到 Agent、Skill 和任务上下文契约中，更新时一定会漂移。 +
+ + + +--- + +# 上下文分层：稳定、任务与事实 + +
+ +| 层级 | 内容 | 更新频率 | 典型落点 | +|---|---|---|---| +| 稳定层 | 角色职责、最小授权、通用安全规则 | 低 | 自定义 Agent、Rule | +| 任务层 | 事实提取、方案比较、验证设计流程 | 中 | Skill、任务上下文契约、Checklist | +| 事实层 | 当前需求、源码、diff、日志和测试结果 | 高 | 本次对话或任务输入 | + +
+ +
+
稳定层错了
所有任务都会偏
+
任务层错了
同类任务反复偏
+
事实层缺失
当前结论必须停止
+
+ + + +--- + +# Agent 之间只交接结构化结果 + +
+ +```md +## 已确认事实 +- <证据路径或记录> + +## 交接去向 +- <应调用的 Skill 或应执行的验证> + +## 输入缺口 +- <缺少什么，为什么不能继续> + +## 不可覆盖的边界 +- <权限、范围、状态或发布限制> +``` + +
+ +
+交接的是可复核结论，不是把完整对话、推理过程和未经验证的猜测交给下一个 Agent。 +
+ + + +--- + +# Agent 与 Skill 组合的三种失效方式 + +
+ +| 失效方式 | 表现 | 修正方向 | +|---|---|---| +| Agent 变成万能角色 | 读、改、测、发、审全都默认允许 | 按职责拆分，降低工具权限 | +| Skill 被复制进 Agent | 多份流程说明彼此不一致 | Skill 保持唯一工作流来源 | +| 交接只有自然语言总结 | 下游重新猜事实、范围和验证状态 | 使用固定输出契约 | +| 运行时事实混入资产 | 换项目仍引用旧路径、字段和权限 | 把事实移回每次任务输入 | + +
+ +
+组合的目的不是增加层数，而是让角色、工作流和事实各自保持可维护。 +
+ + diff --git a/slidev/pages/day5/m11-asset-library-delivery.md b/slidev/pages/day5/m11-asset-library-delivery.md new file mode 100644 index 0000000..d1a4412 --- /dev/null +++ b/slidev/pages/day5/m11-asset-library-delivery.md @@ -0,0 +1,285 @@ +# 模块 11：历史代码治理与可交付资产库 + +
+ +资产库不是提示词文件夹。 + +一份可交付资产要让使用者看得出：解决什么重复问题、需要什么输入、如何运行、输出什么、什么情况下不能继续，以及如何验证它仍然有效。 + +
+ +
+
项目约束生成
+
项目知识构建
+
复杂业务设计
+
业务交付 Review
+
Review 修复闭环
+
+ + + +--- + +# 历史代码识别：先定位职责交界 + +
+ +`OfficialVehicleDispatchServiceImpl.assign` 不是已被判定的缺陷；源码能确认的是，它是一个同时协调多个业务对象的入口。 + +| 源码事实 | 涉及对象 | 重构时必须保留的含义 | +|---|---|---| +| 申请已完成、且不能重复派车 | 申请 / 派车 | 拒绝条件仍在任何写入之前 | +| 车辆可用且时间不冲突 | 车辆 / 派车 | 车辆选择不是只看当前状态 | +| 需要司机时司机必填、且时间不冲突 | 司机 / 派车 | `needDriver` 决定额外前置条件 | +| 创建派车任务后预占车辆 | 派车 / 车辆 | 两次写入处于同一个事务中 | + +
+ +
+“职责交界较多”是重构候选，不等同于“现有实现有错误”。 +
+ + + +--- + +# 重构方案先比选，再决定是否拆分 + +
+ +| 方案 | 对当前 `assign` 的处理 | 依据与判断 | +|---|---|---| +| 保留编排入口，提取校验段 | 分出申请、车辆、司机校验与派车创建的内部方法 | 保持事务、写入顺序和接口不变，便于定向测试 | +| 合并车辆与司机冲突校验 | 抽成通用“资源冲突”组件 | 当前只有查询形状相似，数据模型和错误语义是否统一尚无证据 | +| 将业务校验移动到前端 | 依赖页面下拉选项和表单必填 | 前端可被绕过，不能代替 Service 的业务保护 | + +
+ +
+当前源码支持“先做内部拆分的可行性评估”，不支持直接引入跨领域的通用抽象。 +
+ + + +--- + +# 重构风险审查要逐项回到现有行为 + +
+ +以 `cancel` 为例，以下行为来自当前 Service、Controller 和事务注解： + +| 风险点 | 当前行为 | 重构后的验证点 | +|---|---|---| +| 输入保护 | 空白取消原因在查询与写入之前被拒绝 | 无效输入不能读取或修改业务状态 | +| 状态保护 | 只有 `DISPATCHED` 的派车任务可取消 | 非法状态被拒绝，不能释放车辆 | +| 写入耦合 | 派车变为 `CANCELLED` 并记录原因；车辆恢复 `AVAILABLE` | 两类状态同时成功，异常时整体回滚 | +| 接口边界 | Controller 保留取消权限、审计记录与成功语义 | 不因内部拆分丢失权限或审计入口 | + +
+ +
+风险清单不是重构方案的附录，而是判断“能否改”的前提。 +
+ + + +--- + +# TypeScript 类型治理：类型不能遮住契约冲突 + +
+ +当前公务用车模块已经提供了一个需要核验的跨端契约案例： + +| 位置 | 现有定义或行为 | 需要确认的事实 | +|---|---|---| +| 后端常量 | 审批结果仅定义 `pass` / `reject` | Service 只接受这两个小写值 | +| 前端类型 | `ApproveResult` 同时允许大小写字符串和 `boolean` | 放宽联合类型掩盖了实际允许范围 | +| 前端表单 | 审批选项提交 `PASS` / `REJECT` | 请求载荷与后端接收值是否一致 | +| 申请状态模型 | 后端为字符串，前端同时接受字符串与 `number` | 需要明确接口中的唯一表示方式 | + +
+ +
+源码已证明存在定义差异；是否发生运行时错误，仍需以实际请求和接口验证为准。 +
+ + + +--- + +# 现有测试证明了什么，也暴露了什么 + +
+ +| 已有测试证据 | 能支持的结论 | 仍不能支持的结论 | +|---|---|---| +| `OfficialVehicleDispatchServiceImplTest` | 空白取消原因会在依赖访问前被拒绝 | 正常取消是否更新派车和车辆状态 | +| `OfficialVehicleDispatchControllerTest` | 接口委派、成功提示和 Service 异常透传 | Service 内的状态校验、事务与持久化结果 | +| 官方车辆模块的 Maven 测试配置 | 该后端模块可以执行 Surefire 测试 | 所有状态分支均已覆盖 | +| 前端 `jest.config.mjs` | 当前前端已有 Jest 测试基座 | 派车页面或模型已经具备测试 | + +
+ +
+“已有单测通过”只能说明已运行的场景通过，不能替代对未覆盖状态和副作用的判断。 +
+ + + +--- + +# 单测补齐必须服从当前项目的测试基座 + +
+ +远程大纲中的“Vitest 单测补齐”，在当前项目应转换为“按既有测试框架补齐行为证据”。 + +| 测试目标 | 当前适用基座 | 应补的行为证据 | +|---|---|---| +| Service 规则 | JUnit 5 / Mockito | 非 `DISPATCHED` 取消被拒绝且不写入；正常取消同步更新派车与车辆 | +| 派车前置条件 | JUnit 5 / Mockito | 未审批、重复派车、车辆不可用、需司机但缺司机等分支 | +| 前端请求与模型 | Jest / Vue Test Utils | 审批值的真实载荷、派车表单的必填与可见条件 | +| 跨端类型契约 | API 验证或集成测试 | 大小写审批值、状态值表示与服务端拒绝语义 | + +
+ +
+不为引入新工具而另起 Vitest；先让现有 JUnit 和 Jest 覆盖真实业务行为。 +
+ + + +--- + +# 拆开一个真实 Skill 包 + +
+ +```text +track-review-fix-loop/ +├── SKILL.md # 输入、状态模型、流程、输出与质量门禁 +├── agents/openai.yaml # 展示名、简介和默认触发语 +└── assets/ + ├── 修复记录生成.prompt.md # 将原始材料整理为固定结构 + ├── 修复记录.template.md # 下游可消费的结果格式 + ├── Review修复闭环检查清单.md # 固定遗漏点 + └── 多份反例.md # 权限、审计、状态等典型误用 +``` + +
+ +
+核心文档不求长，而是把“输入、判断、输出、停止、验证”写成能被人和 Agent 同时执行的契约。 +
+ + + +--- + +# 资产库需要一个可检索的索引 + +
+ +| 索引字段 | 要回答的问题 | 示例 | +|---|---|---| +| 资产名称与类型 | 这是 Rule、Prompt、Skill 还是 Agent？ | 状态变更审查 Agent | +| 适用信号 | 什么任务应该选择它？ | 涉及状态写入或资源释放 | +| 必要输入 | 缺少什么就不能运行？ | 目标、源码、状态规则、验证记录 | +| 输出契约 | 结果能交给谁使用？ | 事实表、方案比较、验证清单 | +| 权威位置 | 应到哪个文件更新？ | Skill 的 SKILL.md 或 assets/ | +| 复核触发 | 什么变化会使它失效？ | 框架、流程、接口或真实误用变化 | + +
+ +
+索引不记录“有哪些好提示词”，而是帮助使用者快速判断“此刻该用哪一份资产”。 +
+ + + +--- + +# 用测试夹具验证资产，而不是验证文案 + +
+ +| 夹具类型 | 提供的材料 | 应观察的行为 | +|---|---|---| +| 完整事实 | 入口、状态、diff 与测试记录齐全 | 结论可追溯，输出结构完整 | +| 证据缺失 | 缺少关键 Service 或验证记录 | 明确列出缺口并停止结论 | +| 范围冲突 | 同时要求改数据库、权限和页面 | 指出越界，不默认扩大改动 | +| 反例输入 | 已知的权限、审计或状态误用 | 能识别风险并引用检查项 | +| 跨项目输入 | 不同目录、字段、框架和测试基座 | 重新取证，不复制旧项目结论 | + +
+ +
+资产测试关心的是边界是否正确，不要求模型每次生成完全相同的句子。 +
+ + + +--- + +# 资产库还应包含 MCP 能力契约 + +
+案例提供事实；资产保存判断；自定义 Agent 在受控权限下调用这些资产。连接外部系统的 MCP 还需要独立的能力与权限契约。 +
+ +
+
选型
+
Rule
+
Prompt
+
Skill
+
Agent
+
验证
+
+ + diff --git a/slidev/pages/day5/m12-mcp-asset-governance.md b/slidev/pages/day5/m12-mcp-asset-governance.md new file mode 100644 index 0000000..d20d099 --- /dev/null +++ b/slidev/pages/day5/m12-mcp-asset-governance.md @@ -0,0 +1,152 @@ +# 模块 12：MCP 也必须沉淀为能力资产 + +
+ +MCP 不是一条连接地址，也不是把所有外部系统工具都暴露给 Agent。 + +它是“可被 Agent 调用的外部能力”，因此同样需要清楚的输入输出、权限、审计、失败处理和验证边界。 + +
+ +
+
能力说明
+
工具契约
+
权限范围
+
失败降级
+
验收夹具
+
+ + + +--- + +# MCP 资产包应包含什么？ + +
+ +```text +mcp-assets/ +├── README.md # 接入边界、适用场景与不适用场景 +├── MCP能力契约.template.md # 服务、工具、输入、输出、错误与审计 +├── MCP工具权限与验收清单.md # 最小授权、敏感数据与副作用验证 +├── MCP故障降级清单.md # 超时、鉴权、限流、不可用时的处理 +└── fixtures/ # 完整、拒绝、失败与脱敏结果样例 +``` + +
+ +
+连接配置只说明“连得上”；资产包还要说明“什么时候可以调用、调用后能相信到什么程度”。 +
+ + + +--- + +# 每个 MCP 工具都需要输入输出契约 + +
+ +| 契约字段 | 必须说明的问题 | +|---|---| +| 工具名称与用途 | 它解决哪一类外部事实或操作？ | +| 输入 | 必填字段、格式、数据范围和敏感参数处理方式是什么？ | +| 输出 | 返回哪些已确认字段，哪些字段可能为空或过期？ | +| 副作用 | 只读、可逆写入，还是不可逆操作？ | +| 错误 | 鉴权、限流、超时、无结果和服务错误如何区分？ | +| 审计 | 调用主体、目标对象、时间和结果如何留痕并脱敏？ | + +
+ +
+工具名叫“查询”不代表一定只读；是否有副作用必须由契约明确，而不是让 Agent 猜测。 +
+ + + +--- + +# Agent 调用 MCP 时，权限要再收一层 + +
+ +| 外部能力类型 | Agent 默认策略 | 必须补充的保护 | +|---|---|---| +| 读取公开或脱敏信息 | 可按职责开放 | 结果范围、来源时间与引用记录 | +| 读取受限业务信息 | 仅在明确授权后调用 | 数据范围、脱敏与审计 | +| 创建草稿或临时资源 | 需要用户确认 | 幂等键、撤销方式和可见结果 | +| 修改业务状态或数据 | 不作为默认工具权限 | 二次确认、最小范围和回滚路径 | +| 删除、发布、外发 | 不交给通用 Agent | 专用流程与人工最终确认 | + +
+ +
+自定义 Agent 的工具选择只是第一层；MCP 工具自身仍要定义调用级的权限与确认边界。 +
+ + + +--- + +# MCP 的验收不只检查“调用成功” + +
+ +| 验收夹具 | 预期行为 | +|---|---| +| 合法完整请求 | 返回结构符合契约，来源和时间可追溯 | +| 缺少必填参数 | 拒绝并说明字段缺口，不自动补造参数 | +| 越权请求 | 拒绝或要求确认，不泄露超范围数据 | +| 限流、超时或服务不可用 | 区分故障类型，输出降级结论，不伪装成无结果 | +| 敏感字段返回 | 按契约脱敏，日志不写入密钥、Token 或完整隐私数据 | +| 有副作用的重复调用 | 符合幂等或明确阻止重复执行 | + +
+ +
+MCP 失败时，Agent 应该报告“外部事实未取得”，而不是用已有代码或常识补出一个答案。 +
+ + + +--- + +# MCP 能力资产的交付标准 + +
+一份 MCP 资产的完成标准，不是 Agent 调用成功，而是能力、契约、权限、故障处置和验证边界均可被复核。 +
+ +
+
适用边界
+
工具契约
+
调用权限
+
故障降级
+
验收夹具
+
+ + diff --git a/slidev/pages/day5/m13-historical-code-governance.md b/slidev/pages/day5/m13-historical-code-governance.md new file mode 100644 index 0000000..44bdbf7 --- /dev/null +++ b/slidev/pages/day5/m13-historical-code-governance.md @@ -0,0 +1,210 @@ +# 模块 13：历史代码治理、类型契约与测试补齐 + +
+ +Rule、Skill、Agent 和 MCP 解决的是“如何沉淀判断”。 + +回到真实项目，历史代码治理还需要回答：哪些结构可以调整、哪些行为必须保持、类型是否真的表达了接口契约，以及测试到底覆盖到哪里。 + +
+ +
+
职责结构
+
行为基线
+
命令模型
+
类型契约
+
测试矩阵
+
断言边界
+
+ + + +--- + +# 派车重构的候选职责结构 + +
+ +当前 `assign` 保持事务编排入口，候选拆分只调整内部职责，不改变 Controller、接口或写入顺序： + +```text +assign(vo) @Transactional + |- 校验申请：存在、已审批、未重复派车 + |- 校验车辆：存在、可用、时间不冲突 + |- 校验司机：按 needDriver 决定必填、可用、时间不冲突 + |- 创建派车任务：写入申请、车辆、司机、计划时间与状态 + `- 预占车辆：AVAILABLE -> RESERVED +``` + +| 可调整的内部边界 | 不能借拆分改变的行为 | +|---|---| +| 私有校验方法、局部命名、组装对象的位置 | 事务边界、拒绝顺序、接口字段、派车与车辆的写入语义 | + +
+ + + +--- + +# 用行为基线验收无损重构 + +
+ +`assign` 的当前源码可先整理为行为基线；重构后的代码和测试都应逐项回到这张表。 + +| 输入条件 | 预期结果 | 允许的写入 | +|---|---|---| +| 申请不存在、未完成或已派车 | 拒绝派车 | 无派车任务、无车辆状态变更 | +| 车辆不存在、不可用或时间冲突 | 拒绝派车 | 无派车任务、无车辆状态变更 | +| 需要司机但未提供，或司机不可用/冲突 | 拒绝派车 | 无派车任务、无车辆状态变更 | +| 所有前置条件满足 | 创建 `DISPATCHED` 派车任务 | 车辆由 `AVAILABLE` 变为 `RESERVED` | + +
+ +
+“无损”不是代码未报错，而是每个拒绝路径和成功副作用仍与基线一致。 +
+ + + +--- + +# 类型治理要分开命令、实体与展示模型 + +
+ +派车模块已有一组可对照的模型边界： + +| 模型 | 当前字段范围 | 应承担的职责 | +|---|---|---| +| `OfficialVehicleDispatchVo` | `applyId`、`carId`、可选 `driverId`、`remark` | 派车命令的唯一输入 | +| `OfficialVehicleDispatch` | ID、调度人、时间、状态、取消原因等 | 服务端持久化与列表展示结果 | +| 前端 `OfficialVehicleDispatchVo` | 与派车命令相同的四类字段 | 提交时只发送用户可提供的内容 | +| 前端 `OfficialVehicleDispatch` | 读取列表中的状态、时间和调度人等 | 展示与操作条件判断 | + +
+ +
+命令类型不是实体类型的 `Partial`：状态、时间和操作人不应由派车表单决定。 +
+ + + +--- + +# 类型差异必须形成可执行的核验用例 + +
+ +审批结果和申请状态的定义差异，不能只记录在问题单中，应转换为可验证的契约。 + +| 核验对象 | 输入或观察值 | 需要确认的结论 | +|---|---|---| +| 审批命令 | `pass`、`reject`、`PASS`、`REJECT` | 哪些值能被接口接受；拒绝时返回什么语义 | +| 审批表单 | 单选组件实际提交的 `result` | 页面提交值是否与接口契约一致 | +| 申请状态 | `1`、`"1"` 及接口返回值 | 前端渲染和状态判断使用的唯一表示 | +| 类型定义 | 联合类型、表单选项、后端常量 | 三处是否指向同一组允许值 | + +
+ +
+类型契约完成的标准是“能执行的接受与拒绝用例”，不是文档里多了一行枚举。 +
+ + + +--- + +# 取消派车的测试用例应覆盖状态与副作用 + +
+ +| 场景 | 期望行为 | 当前证据状态 | +|---|---|---| +| `cancelReason` 全空白 | 立即拒绝，不访问后续依赖 | 已有 Service 单测 | +| 派车任务不存在 | 拒绝，不更新派车或车辆 | 待补 | +| 派车状态不是 `DISPATCHED` | 拒绝，不释放车辆 | 待补 | +| 任务可取消且车辆存在 | 记录取消原因，派车变 `CANCELLED`，车辆变 `AVAILABLE` | 待补 | +| 任务可取消但车辆记录缺失 | 派车仍完成取消，避免空指针 | 待补，当前源码有空值保护 | + +
+ +
+测试用例的粒度应跟随状态与副作用，不以“覆盖了 cancel 方法”作为完成标准。 +
+ + + +--- + +# 断言要与被测层级匹配 + +
+ +| 被测层级 | 当前可见证据 | 应断言什么 | 不能替代什么 | +|---|---|---|---| +| Controller | Mockito 验证 `cancel` 的委派与结果消息 | 接口是否交给正确的 Service 参数 | Service 内部状态和持久化行为 | +| Service 拒绝路径 | 空白原因抛出异常 | 不满足条件时无后续写入或资源释放 | 正常取消的双对象更新 | +| Service 成功路径 | 当前尚无定向单测 | 派车状态、取消原因、车辆状态及更新次数 | 前端实际请求载荷 | +| API / 集成层 | 当前尚无契约验证记录 | 前后端值、权限、序列化与错误响应 | 未执行环境的全链路结论 | + +
+ +
+Controller Mock 测试通过，不等于业务状态机已经被测试。 +
+ + + +--- + +# 从案例到可执行资产 + +
+案例提供事实；资产保存判断；重构守住行为；类型表达契约；测试证明副作用；MCP 将外部能力纳入同一套边界。 +
+ +
+
事实
+
Rule
+
任务契约
+
Skill
+
Agent
+
MCP
+
类型
+
测试
+
+ + diff --git a/slidev/pages/day5/m2-project-knowledge.md b/slidev/pages/day5/m2-project-knowledge.md new file mode 100644 index 0000000..b626637 --- /dev/null +++ b/slidev/pages/day5/m2-project-knowledge.md @@ -0,0 +1,125 @@ +# 模块 2：从案例判断资产边界 + +
+ +资产化最难的不是给文件命名，而是把可长期复用的判断，与一次任务中的项目事实分开。 + +稳定约束可以沉淀；字段名、路径、权限码和未验证结论必须留在运行时输入中。 + +
+ +
+
稳定约束
+
运行时事实
+
已知反例
+
证据缺口
+
+ + + +--- + +# 资产选型先看变化与风险 + +
+ +| 判断维度 | 信号 | 更合适的承载方式 | +|---|---|---| +| 约束变化频率 | 长期稳定，违反代价高 | Rule：明确必须项、禁止项与验收 | +| 任务输入变化 | 问法稳定，但每次事实材料不同 | 任务上下文契约：固定约束，替换运行时输入 | +| 漏检风险 | 风险项有限且常被忽略 | Checklist：让关键检查可以逐项确认 | +| 决策复杂度 | 需要多步读取、判断、交接和验证 | Skill：编排资产与停止条件 | +| 误解成本 | 正确做法容易被错误套用 | Example：保留正例、反例和适用边界 | + +
+ +
+同一条经验不一定只对应一种资产；选择依据是变化速度、误用风险和决策复杂度。 +
+ + + +--- + +# 公务用车案例能沉淀什么？ + +
+ +| 案例中的发现 | 不应直接沉淀为 | 更合适的资产 | +|---|---|---| +| 前端必填不能代替后端业务保护 | “取消原因不能为空”的全局 Rule | 状态变更必要信息后端保护 Rule | +| 分析时要同时看页面、API、权限和 Service | 一段固定答案 | 影响分析任务上下文的输入清单 | +| 状态写入前要检查必需字段 | 一次性代码片段 | 状态变更检查单与反例 | +| 需要读源码、判断边界、列验证项 | 超长 Prompt | 多步状态变更审查 Skill | +| 数据库 NOT NULL 在此场景不合适 | “永远不要改数据库” | 条件化反例与取舍说明 | + +
+ + + +--- + +# 资产候选必须有证据来源 + +
+ +| 证据来源 | 可以升级的资产 | 还需要补什么 | +|---|---|---| +| 明确的项目规范、配置或接口契约 | Rule | 适用范围和验收方式 | +| 多次出现的同类提问与交付结构 | Prompt / Template | 必填输入与输出 Schema | +| 已发生的漏检、误用或缺陷 | Checklist / Example | 反例、触发条件和修复依据 | +| 可重复的多步分析与验证路径 | Skill | 各步骤输入、交接和停止条件 | +| 未经核对的模型建议或单次对话 | 暂不沉淀 | 先补项目事实或验证记录 | + +
+ +
+资产不是知识收藏；没有来源证据的内容只能是候选建议。 +
+ + + +--- + +# 不值得沉淀的内容 + +
+
+
单次对话结论
+
没有输入、证据和适用范围，下一次无法复核。
+
+
+
项目特有字段或权限码
+
换项目后很可能失效，必须留在运行时输入中。
+
+
+
没有验证过的模型建议
+
只能作为候选方案，不能升级为规则。
+
+
+
一次性检查列表
+
重复价值不足时，保留在任务记录即可。
+
+
+ + diff --git a/slidev/pages/day5/m3-task-delegation.md b/slidev/pages/day5/m3-task-delegation.md new file mode 100644 index 0000000..047e480 --- /dev/null +++ b/slidev/pages/day5/m3-task-delegation.md @@ -0,0 +1,112 @@ +# 模块 3：Rule 的设计契约 + +
+ +Rule 不是“代码要规范”这类口号。 + +一条可执行 Rule 必须说明：它基于什么证据、在哪些场景生效、必须做什么、不能做什么，以及如何验收。 + +
+ +
+
来源可信
+
边界明确
+
结果可验
+
+ + + +--- + +# 先给 Rule 标注证据等级 + +
+ +| 等级 | 什么时候使用 | 典型写法 | +|---|---|---| +| 硬约束 | 配置、构建、CI 或显式规范直接证明 | 必须 / 禁止 | +| 观察性约束 | 多处源码反复出现，但没有书面规范 | 默认采用 / 优先复用 | +| 待确认约束 | 对交付很重要，但当前项目无法证明 | 需确认 / 不下结论 | + +
+ +
+不要把“一个代码样例”或“通用最佳实践”直接升级成项目硬规则。 +
+ + + +--- + +# 一条 Rule 的六个字段 + +
+ +```md +## 状态变更必要信息保护 + +- 级别：观察性约束 +- 适用场景：Service 方法会写入业务状态或释放、占用资源。 +- 必须：在任何写入前校验本次状态变更必需的信息。 +- 禁止：仅依赖前端必填；将条件必填扩大为全表非空。 +- 来源证据：状态更新、资源更新与现有调用链。 +- 验收方式：无效输入被拒绝；正常路径及副作用单独验证。 +``` + +
+ + + +--- + +# 常见的 Rule 失效方式 + +
+ +| 写法 | 为什么失效 | 改写方向 | +|---|---|---| +| “后端要做好校验” | 没有触发点、位置和验收 | 指出状态写入前的必要信息保护 | +| “所有字段都不能空” | 把条件规则扩大为数据模型规则 | 写清具体状态与字段条件 | +| “统一使用 Service” | 把架构偏好误当业务约束 | 说明为什么该规则需要覆盖复用入口 | +| “严格测试” | 无法判断是否满足 | 写出无效输入、正常路径和副作用验证 | + +
+ +
+好的 Rule 约束行为，不替人猜业务，也不替项目做架构重写。 +
+ + + +--- + +# Rule 的验收不是“读起来像规范” + +
+
能触发
知道什么时候应用
+
能约束
必须与禁止清楚
+
能取证
来源不是主观偏好
+
能验证
可用代码、测试或检查确认
+
+ + diff --git a/slidev/pages/day5/m4-refactor-safety.md b/slidev/pages/day5/m4-refactor-safety.md new file mode 100644 index 0000000..24592f5 --- /dev/null +++ b/slidev/pages/day5/m4-refactor-safety.md @@ -0,0 +1,126 @@ +# 模块 4：任务上下文契约 + +
+ +任务上下文契约不是一句“帮我分析”。它规定任务需要哪些事实、遵守哪些约束、缺少什么时停止，以及结果如何交给下一步使用。 + +Prompt 只是这份契约的常见承载形式之一。 + +
+ +
+
固定约束
+
运行时事实
+
输出结构
+
停止边界
+
+ + + +--- + +# 固定约束与运行时事实要分开 + +
+ +| 固定上下文 | 每次任务重新提供的事实 | +|---|---| +| 先取证、再判断、最后给方案的要求 | 本次变更目标 | +| 证据不足时标记待确认 | 已读文件、diff、日志和测试结果 | +| 输出必须区分事实、建议和未知项 | 当前接口、字段、状态和权限信息 | +| 不得编造运行结果或业务结论 | 本次允许与禁止修改的范围 | + +
+ +
+可复用的是判断框架；项目事实必须作为运行时上下文重新提供。 +
+ + + +--- + +# 影响分析的输出契约 + +
+ +```md +任务：基于提供的源码与记录分析本次变更，不要修改代码。 + +必备上下文：变更目标、已读源码、状态或权限规则、diff 或测试记录。 + +输出必须包含： +1. 已确认事实：每项关联来源路径或输入证据。 +2. 影响链路：入口、业务边界、状态/数据副作用。 +3. 候选方案：范围、优缺点、验证方式。 +4. 最小改动建议：允许修改与明确不改内容。 +5. 待确认项：证据缺口以及不能推出的结论。 + +约束：没有证据时写“待确认”；不得补充测试、接口或业务结果。 +``` + +
+ + + +--- + +# 任务上下文契约也需要测试用例 + +
+ +| 输入情况 | 期望行为 | 不能接受的行为 | +|---|---|---| +| 入口、Service 与测试齐全 | 输出可追溯的影响分析 | 只给泛化最佳实践 | +| 只有页面截图或单个文件 | 明确缺少 API、状态或验证证据 | 自行补全调用链 | +| 要求跨层重构但无依据 | 标记范围风险并给出最小方案 | 默认修改数据库、权限和页面 | +| 测试结果缺失 | 输出待执行验证项 | 写成“测试已通过” | + +
+ +
+一份任务上下文契约在不同事实输入下都能保持边界，才具备复用价值。 +
+ + + +--- + +# 上下文契约失控的三个信号 + +
+
+
输入缺失仍结论完整
+
说明模型在补猜，缺少待确认出口。
+
+
+
输出无法进入下一步
+
说明没有固定输出结构或验收字段。
+
+
+
每次都要重写长背景
+
说明固定约束和变量输入没有拆开。
+
+
+ + diff --git a/slidev/pages/day5/m5-testing-safety-net.md b/slidev/pages/day5/m5-testing-safety-net.md new file mode 100644 index 0000000..f9230a0 --- /dev/null +++ b/slidev/pages/day5/m5-testing-safety-net.md @@ -0,0 +1,137 @@ +# 模块 5：Skill 的难点是决策边界 + +
+ +Skill 的价值不在于堆叠说明，而在于把任务拆成可核对的输入条件、决策顺序、交接结果和停止边界。 + +只有这些边界被显式定义，复杂任务才能在不同项目事实下保持可控。 + +
+ +
+
输入条件
+
决策顺序
+
交接结果
+
停止边界
+
+ + + +--- + +# 一个真实 Skill 包如何按职责拆开 + +
+ +```text +skill-name/ +├── SKILL.md # 触发条件、输入、工作流、输出与门禁 +├── agents/ +│ └── openai.yaml # 展示名、简介与默认触发提示 +├── assets/ +│ ├── 生成.prompt.md # 可复用任务 Prompt +│ ├── 检查清单.md # 固定遗漏点 +│ └── 报告.template.md # 结构化输出模板 +├── references/ # 稳定背景知识与兼容性说明 +└── scripts/ # 可重复执行的机械检查 +``` + +
+ +
+`SKILL.md` 负责决策和编排；模板、检查单、参考资料和脚本各自承担单一职责，避免同一约束出现多个版本。 +
+ + + +--- + +# SKILL.md 的核心结构 + +
+ +```md +--- +name: state-change-safety +description: 当任务涉及业务状态写入、资源占用或释放时使用。 +--- + +## Inputs +变更目标、相关源码、状态规则、测试或 diff、项目约束。 + +## Workflow +提取事实 -> 判断状态与副作用 -> 比较候选方案 -> 生成验证清单。 + +## Output Contract +事实表、影响链路、最小改动建议、验证项、待确认事项。 + +## Stop Conditions +证据不足、规则冲突、范围越界或关键验证失败时停止并说明原因。 +``` + +
+ + + +--- + +# agent 配置只解决“如何被发现” + +
+ +```yaml +interface: + display_name: "状态变更安全审查" + short_description: "分析状态写入、资源副作用与验证边界" + default_prompt: "Use $state-change-safety to review this change." + +policy: + allow_implicit_invocation: true +``` + +
+ +
+
配置文件：让 Agent 找得到
+
SKILL.md：让 Agent 做得对
+
+ + + +--- + +# 什么不该做成 Skill？ + +
+ +| 情况 | 更合适的资产 | 原因 | +|---|---|---| +| 只有一条永远成立的约束 | Rule | 没有多步决策必要 | +| 只需固定格式生成一段内容 | Prompt 或 Command | 不需要上下文编排 | +| 只检查五个固定项目 | Checklist | 不需要 Agent 主动分析 | +| 只有一个项目的临时异常 | 任务记录或 Example | 复用价值不足 | +| 需要读取、判断、生成、验证并输出结构化结果 | Skill | 需要多个资产协同 | + +
+ + diff --git a/slidev/pages/day5/m6-asset-skill-writing.md b/slidev/pages/day5/m6-asset-skill-writing.md new file mode 100644 index 0000000..123d1dc --- /dev/null +++ b/slidev/pages/day5/m6-asset-skill-writing.md @@ -0,0 +1,131 @@ +# 模块 6：Skill 如何组合 Rule、Prompt 与检查单 + +
+ +Skill 的难点不是写步骤，而是把每一步需要的判断、材料和停止条件拆开。 + +一次状态变更审查，至少要完成“事实、方案、验证、边界”四类判断。 + +
+ +
+
事实
+
方案
+
验证
+
边界
+
+ + + +--- + +# 状态变更 Skill 的四个决策阶段 + +
+ +```text +1. 事实提取 + 读取入口、状态、写入顺序、权限、审计和已有验证。 + +2. 方案比较 + 用 Rule 判断最终保护边界；排除范围越界方案。 + +3. 验证设计 + 用检查单覆盖无效输入、正常路径和关键副作用。 + +4. 结论输出 + 区分已确认、待执行和待确认；证据不足时停止。 +``` + +
+ + + +--- + +# 每一步应加载什么资产？ + +
+ +| 阶段 | 使用的资产 | 作用 | +|---|---|---| +| 事实提取 | 影响分析 Prompt、项目约束 | 防止遗漏入口和把猜测写成事实 | +| 方案比较 | 状态变更 Rule、反例 | 判断保护位置与禁止范围 | +| 验证设计 | 状态流转检查单、测试模板 | 覆盖正常、异常与副作用 | +| 结论输出 | 报告模板、输出契约 | 使后续 Review 或 PR 能继续使用 | + +
+ +
+Skill 的每一步都应能指出“为什么读这个资产、产出交给谁”。 +
+ + + +--- + +# Output Contract 决定 Skill 是否可用 + +
+ +```md +## 已确认事实 +<来源路径 / 记录 / 证据> + +## 方案比较 +<候选方案、覆盖范围、取舍理由> + +## 验证清单 +<已覆盖、待执行、阻断条件> + +## 待确认事项 +<证据缺口与不能下结论的原因> + +## 资产建议 + +``` + +
+ + + +--- + +# Stop Conditions 比步骤更重要 + +
+ +| 停止信号 | Skill 应做什么 | 不应做什么 | +|---|---|---| +| 缺少入口或状态源码 | 列出缺失材料并停止结论 | 自行补全调用链 | +| 业务规则互相矛盾 | 标记待确认并列出冲突来源 | 擅自选一个规则执行 | +| 方案超出允许范围 | 明确指出越界位置 | 顺手改数据库、权限或页面 | +| 关键验证没有证据 | 输出待执行项 | 写成“已验证” | + +
+ +
+能在证据不足时停下来的 Skill，比能不断生成内容的 Skill 更可靠。 +
+ + diff --git a/slidev/pages/day5/m7-delivery-review.md b/slidev/pages/day5/m7-delivery-review.md new file mode 100644 index 0000000..b002e9d --- /dev/null +++ b/slidev/pages/day5/m7-delivery-review.md @@ -0,0 +1,115 @@ +# 模块 7：资产也要验证与演进 + +
+ +代码需要测试，Rule、Prompt 和 Skill 同样需要验证。 + +一份资产能否长期使用，不取决于措辞是否漂亮，而取决于面对完整信息、缺失信息和越界请求时能否保持正确边界。 + +
+ +
+
完整输入
+
缺失证据
+
范围冲突
+
跨项目复用
+
+ + + +--- + +# 用四类输入测试资产边界 + +
+ +| 测试输入 | 期望结果 | 失败信号 | +|---|---|---| +| 入口、状态与测试材料齐全 | 输出事实、方案和验证项都可追溯 | 只给泛化建议，无法指向输入 | +| 缺少 Controller 或状态规则 | 明确列出缺失证据 | 擅自补全权限或调用链 | +| 请求修改数据库、权限和页面 | 标出范围冲突与风险 | 把扩展改动当作默认方案 | +| 换到另一个项目 | 重新扫描项目事实和约束 | 直接复制字段名、路径和异常文案 | + +
+ + + +--- + +# 资产更新只接受两类证据 + +
+ +| 更新依据 | 应如何处理 | +|---|---| +| 项目规则、框架、接口或测试基座发生变化 | 更新适用范围、来源路径和验证方式 | +| 资产在真实任务中造成误用、遗漏或无效输出 | 补充反例、停止条件或拆分更小资产 | +| 只是觉得“提示词不够顺” | 保留意见，不能直接升级为规则 | +| 想把另一个项目的细节抄进来 | 先标记为待确认，并重新获取证据 | + +
+ +
+资产演进依赖新证据，不依赖个人偏好或模型建议本身。 +
+ + + +--- + +# 可复用与必须重查的内容 + +
+ +| 可以跨项目复用 | 换项目必须重新获取 | +|---|---| +| 事实、方案、验证、边界的输出结构 | 路径、模块名、字段、接口与权限码 | +| 证据不足时停止的规则 | 状态枚举、异常映射和事务边界 | +| Prompt 的输入输出契约 | 构建命令、测试基座和目录结构 | +| Skill 的质量门禁与测试矩阵 | 业务必填条件与发布前置条件 | + +
+ +
+资产复用的是判断方法，不是上一次项目的结论。 +
+ + + +--- + +# 资产验证后，进入 Agent 封装 + +
+案例提供事实和反例；资产把事实背后的判断方法保存下来。 +
+ +
+
资产选型
+
Rule 契约
+
Prompt 契约
+
Skill 组合
+
资产验证
+
+ + diff --git a/slidev/pages/day5/m8-custom-agent-asset.md b/slidev/pages/day5/m8-custom-agent-asset.md new file mode 100644 index 0000000..bf8492c --- /dev/null +++ b/slidev/pages/day5/m8-custom-agent-asset.md @@ -0,0 +1,138 @@ +# 模块 8：自定义 Agent：把稳定角色做成资产 + +
+ +自定义 Agent 不是另起一套 Prompt。 + +它把一个稳定的职责、可用工具、默认指令和交付边界封装为可选择的角色，让每次任务不必从“你是谁、能做什么”重新说明。 + +
+ +
+
职责固定
+
工具受控
+
指令稳定
+
结果可验
+
+ + + +--- + +# 它和其他资产分别解决什么？ + +
+ +| 资产 | 固化的内容 | 不承担的内容 | +|---|---|---| +| Rule | 必须遵守的长期约束 | 多步任务编排 | +| Prompt | 一类提问的输入输出结构 | 角色权限与默认工具 | +| Checklist | 固定遗漏点 | 源码分析与方案判断 | +| Skill | 多步工作流、资源与停止条件 | 对话入口的默认身份 | +| 自定义 Agent | 角色、指令、模型和工具边界 | 某个任务的项目事实 | + +
+ +
+自定义 Agent 负责“谁来做、能做什么”；Skill 负责“这类任务按什么流程完成”。 +
+ + + +--- + +# 一个自定义 Agent 的配置契约 + +
+ +```md +--- +name: 状态变更审查 +description: 分析状态写入、资源副作用与验证边界。 +argument-hint: "变更目标、相关源码、测试或 diff" +model: <当前环境允许的模型> +tools: <仅选择完成该职责所需的工具> +--- + +先提取事实；证据不足时列出缺口； +不修改代码；输出影响链路、方案比较、验证项和待确认事项。 +``` + +
+ +
+
标头：让 Trae 识别角色、入口与能力边界
+
正文：让 Agent 在任务中保持判断与交付边界
+
+ + + +--- + +# 固定配置与运行时输入必须分开 + +
+ +| 固定在自定义 Agent 中 | 每次任务重新提供 | +|---|---| +| 角色名称与职责范围 | 本次变更目标 | +| 先取证、后判断的工作原则 | 相关目录、文件、diff、日志 | +| 可用工具与停止条件 | 当前状态、字段、接口与权限事实 | +| 结构化输出要求 | 实际执行过的测试或验证结果 | +| 引用哪些 Rule / Skill | 本次允许与禁止的改动范围 | + +
+ +
+把项目路径、字段名和历史结论写死在 Agent 中，会让它离开原项目后继续错误复用。 +
+ + + +--- + +# 什么时候不该创建自定义 Agent？ + +
+ +| 需求 | 更合适的做法 | 原因 | +|---|---|---| +| 只要一句固定约束 | Rule | 不需要独立角色 | +| 只生成一段固定格式文本 | Prompt / Command | 无需工具与长期指令 | +| 只核对少数固定项 | Checklist | 无需自主检索判断 | +| 只有一次临时排查 | 普通对话与任务记录 | 长期复用价值不足 | +| 需要稳定职责、工具边界和结构化交付 | 自定义 Agent | 角色本身有重复价值 | + +
+ +
+“每个任务一个 Agent”会造成角色泛滥、说明重复和难以维护。 +
+ + diff --git a/slidev/pages/day5/m9-agent-boundaries.md b/slidev/pages/day5/m9-agent-boundaries.md new file mode 100644 index 0000000..bb49b86 --- /dev/null +++ b/slidev/pages/day5/m9-agent-boundaries.md @@ -0,0 +1,121 @@ +# 模块 9：Agent 的权限与停止边界 + +
+ +给 Agent 更多工具，不会让结论更可靠，只会扩大它可能造成的影响。 + +角色、上下文和工具权限必须同时收敛，才能让一份 Agent 资产在不同任务中保持可控。 + +
+ +
+
角色
允许承担什么判断
+
上下文
允许读取什么材料
+
工具
允许产生什么副作用
+
+ + + +--- + +# 按风险选择最小工具集 + +
+ +| Agent 类型 | 典型职责 | 最小能力方向 | 不应默认拥有 | +|---|---|---|---| +| 代码理解 Agent | 定位入口、调用链与事实 | 代码搜索、文件读取 | 写文件、执行发布 | +| 方案审查 Agent | 比较方案与范围风险 | 读取源码、diff、规则 | 直接修改业务代码 | +| 测试设计 Agent | 生成测试点与验证方案 | 读取需求、代码、测试 | 宣称测试已经通过 | +| CI 分析 Agent | 分层解释失败日志 | 读取日志、配置、diff | 修改环境或密钥 | +| 实施 Agent | 在确认范围内生成变更 | 受控编辑与验证 | 自行扩大任务范围 | + +
+ +
+先定义角色，再分配最少工具；不要先打开全部权限，再期待提示词自己约束行为。 +
+ + + +--- + +# 用真实案例设计一个只读审查 Agent + +
+ +```text +角色：状态变更审查 Agent +输入：变更目标、入口与 Service 源码、状态定义、相关测试或 diff +可读材料：页面/API、权限与审计入口、状态写入代码、测试结构 +输出：事实表、影响链路、最小改动建议、验证清单、待确认项 +禁止：修改代码、执行发布、把前端必填当作最终业务保护 +停止：缺少状态写入点、关键规则冲突、验证证据缺失 +``` + +
+ +
+公务用车案例在这里只贡献“状态变更要先取证”的素材，不把任何字段名或接口路径固化为通用规则。 +
+ + + +--- + +# Stop Conditions 是 Agent 的安全阀 + +
+ +| 停止信号 | Agent 应输出 | Agent 不应做 | +|---|---|---| +| 缺少入口或关键 Service | 缺失材料清单 | 补猜调用链 | +| 状态规则与需求冲突 | 冲突来源与待确认问题 | 自行选择业务规则 | +| 请求超出角色权限 | 范围风险与转交建议 | 临时取得写入或发布权限 | +| 验证记录不完整 | 待执行验证项 | 写成“已通过” | +| 需要外部系统事实 | 所需日志、接口或外部确认项 | 将源码推断包装成运行结论 | + +
+ +
+可靠 Agent 的表现不是总能继续，而是知道何时不能再继续。 +
+ + + +--- + +# 自定义 Agent 的验收标准 + +
+
职责清楚
知道何时选择它
+
权限收敛
只拥有必要工具
+
输出稳定
可被后续 Skill 或 Review 使用
+
会正确停止
证据不足不虚构
+
+ +
+不能说明“为什么需要这个角色、为什么给这些工具”的 Agent，不应进入共享资产库。 +
+ + diff --git a/slidev/pages/day6/m1-team-flow.md b/slidev/pages/day6/m1-team-flow.md new file mode 100644 index 0000000..6138bc0 --- /dev/null +++ b/slidev/pages/day6/m1-team-flow.md @@ -0,0 +1,124 @@ +# 模块 1：AI 改动的工程闭环 + +
+ +AI 辅助完成的代码，仍然要经过研发协作中的基本检验：范围清晰、变更可审查、结果可验证、结论可追溯。 + +这些工程要素共同约束 AI 改动的速度、质量与责任边界。 + +
+ +
+ +```text +影响分析 + -> 变更实现 + -> PR 说明 + -> Git 审查与合并 + -> CI 构建与测试 + -> 发布或回退判断 + -> 可追溯技术结论 +``` + +
+ + + +--- + +# CI/CD 在交付链路中的位置 + +
+
+
CI：持续集成
+
代码提交后自动编译、检查和测试，尽早发现无法合入的问题。
+
+
+
持续交付
+
CI 通过后形成可部署版本，进入测试或预生产环境；生产发布仍需人工确认。
+
+
+
持续部署
+
CI 通过后自动发布生产环境，需要成熟的监控、自动化门禁和回退能力。
+
+
+ +
+提交 PR -> CI 构建与测试 -> 可部署版本 -> 测试环境验证 -> 人工确认 -> 生产发布或回退 +
+ +
+CI 负责尽早暴露问题；是否发布仍需要结合业务风险和验证证据作出判断。 +
+ + + +--- + +# AI 改动进入协作后的四类信息 + +
+
+改动目标 +
解决什么问题，明确不解决什么问题
+
+
+影响范围 +
涉及哪些入口、数据、状态、权限或外部依赖
+
+
+验证证据 +
哪些行为已经由测试、日志或人工检查证实
+
+
+已知边界 +
哪些场景尚未覆盖，哪些结论仍需要确认
+
+
+ + + +--- + +# 工程质量的最终责任仍在人 + +
+ +| AI 可以加速 | 人必须确认 | +|---|---| +| 搜索代码、归纳调用链、生成候选实现 | 业务规则是否正确 | +| 生成测试草稿、解释日志、提出修复假设 | 权限、数据和状态边界是否完整 | +| 补充 PR 说明和变更摘要 | 变更范围是否可接受，验证结论是否准确 | +| 提供多种实现方案 | 采用哪一种方案及其长期维护成本 | + +
+ +
+把 AI 当作加速器，而不是把工程判断外包给 AI。 +
+ + diff --git a/slidev/pages/day6/m10-ai-trends.md b/slidev/pages/day6/m10-ai-trends.md new file mode 100644 index 0000000..b1ca2f7 --- /dev/null +++ b/slidev/pages/day6/m10-ai-trends.md @@ -0,0 +1,236 @@ +# 模块 10：AI Agent 新趋势 + +
+ +AI Agent 已能读取外部资料、触发真实动作、组合工具能力并委托其他 Agent。输入边界、执行门禁、工具服务、能力分发、IDE 接入与跨 Agent 协作，开始形成不同层次的开放协议。 + +
+ +
+
输入权威
外部内容不能下指令
+
运行时策略
动作发生时再判断
+
MCP 新扩展
工具调用走向任务与交互
+
Agent Plugins
能力以统一插件包交付
+
ACP
IDE 与 Agent 解耦
+
A2A
跨 Agent 应用协作
+
+ +--- + +# Agent 工程的边界正在外延 + +
+
输入边界
上下文不再只有仓库与任务描述，还包含网页、Issue、检索结果和外部系统返回的数据。
+
执行边界
Agent 不只输出文本，也会调用工具、运行命令、更新外部系统，甚至交给后台长任务处理。
+
协作边界
协作不再局限于同一 IDE 内的角色分工，开始需要跨 Agent 应用的发现、委托和结果交接。
+
+ +
每一次外部读取、工具调用和任务交接，都需要明确的信息权威、执行权限和责任归属。
+ +--- + +# 外部内容不拥有指令权 + +
+
+
它是什么
+网页、Issue、RAG 文档和 MCP 工具描述都是输入材料。它们可以提供事实、线索和建议，但不能自行改变任务目标、权限或停止条件。 +
+
+
它解决什么
+间接提示注入往往把正当问题和越权动作混在一起。分离“可核实的问题”和“无权执行的指令”，才能安全接入真实世界资料。 +
+
+ +
“导出报错”可以成为排查线索；“关闭测试并上传配置”不能因为写在同一条 Issue 里就获得执行权。
+ + + +--- + +# 运行时策略与 Hook + +
+
+
它是什么
+策略在会话开始、工具调用前后和任务出错时运行，根据工具、参数、环境和角色决定允许、拒绝、确认或记录。 +
+
+
它解决什么
+把“不要做错”从一段静态说明，变成动作发生时的实际判断：拦截危险命令、扫描敏感信息、记录审计并限制失败重试。 +
+
+ +
GitHub Copilot Hooks 是这一方向的代表：策略可以在事件点执行，而不只依赖模型记住一段 Prompt。
+ + + +--- + +# MCP 的三项扩展 + +
+
Tasks
将耗时工作变成有任务号、进度、取消、补充输入和最终产物的异步任务。
+
Skills over MCP
让 Server 发布可发现的结构化工作方法，不只暴露一组工具名称和参数。
+
MCP Apps
在对话内展示表单、参数预览、图表和任务进度，把人带回关键判断点。
+
+ +
它们让 MCP 从“同步调用一个工具”扩展为“观察长任务、发现工作方法、完成可见的人机确认”。
+ + + +--- + +# MCP 正在摆脱会话绑定 + +
+
请求自带上下文
协议版本、客户端能力与调用信息跟随每次请求，不再依赖先建立一条长期会话。
+
服务可水平扩展
任意请求可以路由到任意实例，网关可按方法与工具名进行路由、限流和授权。
+
状态必须显式交接
业务仍可有状态，但状态要以任务号或句柄传递，不能隐含在一条连接里。
+
+ +
连接可以断开和重连；任务与业务状态必须可见、可恢复、可审计。
+ + + +--- + +# Agent Plugins：把一组能力装进同一个包 + +
+
+
它是什么
+
+reports-plugin/
+├─ plugin.json
+├─ skills/     工作方法与参考资料
+├─ mcp.json    工具与服务连接声明
+└─ com.vendor.client/   客户端扩展 +
+
+
+
它解决什么
+将相互配合的 Skill 与 MCP Server 按固定目录和清单一起交付。不同客户端不必各自发明目录、清单和连接配置，能力包也不必维护多份分叉版本。 +
+
+ +
Plugin 只规定“怎么打包”；安装、权限、信任校验、沙箱和界面仍由每个客户端负责。
+ + + +--- + +# IDE 与 Coding Agent 正在解耦 + +
+
IDE / 编辑器
负责工作区、文件编辑、Diff 展示、终端入口和人工确认。
+
ACP
统一会话、消息与编码任务交互，让编辑器和 Agent 不必逐对定制集成。
+
Coding Agent
负责理解任务、制定计划、修改代码、调用工具并返回可审查的变更。
+
+ +
选择 Agent 不必同时接受唯一界面；选择 IDE 也不必被单一 Agent 绑定。
+ + + +--- + +# Agent 的输出开始变成交互界面 + +
+
Agent
输出当前任务需要展示的字段、选项、进度与下一步，而不是直接执行一段界面代码。
+
A2UI
用声明式组件蓝图描述界面，可随 Agent 的流式输出逐步更新。
+
宿主应用
按自身设计系统渲染原生组件，并决定哪些控件、数据和交互可以出现。
+
+ +
Agent 决定“现在需要什么交互”；宿主应用决定“允许如何呈现和执行”。
+ + + +--- + +# A2A：多 Agent 协作的协议层 + +
+
+
它是什么
+多 Agent 协作是多个角色分工和交接任务的广义工作方式。A2A 是其中的协议层，让独立 Agent 应用按标准方式发现彼此、委托工作和返回结果。 +
+
+
它解决什么
+跨产品、跨框架协作不再依赖共享所有 Prompt、记忆和工具实现，而是交接身份、能力、任务状态、结果和失败原因。 +
+
+ +
A2A 管 Agent 到 Agent 的任务协作；MCP 管 Agent 到工具、数据和资源。一个 A2A Agent 可以在内部使用 MCP。
+ + + +--- + +# 工程落地的三项前提 + +
+
来源有边界
外部内容只能补充事实与线索，不能自行改变任务、权限或停止条件。
+
执行有门禁
每次写入、发布或高风险工具调用，都要有最小权限、确认与可回退条件。
+
协作可交接
跨角色或跨系统协作必须明确任务状态、验证结果、失败原因与责任归属。
+
+ +
外部内容不能授予权限；工具动作必须有执行门禁；跨 Agent 协作必须交接任务、状态、结果与责任。
+ + diff --git a/slidev/pages/day6/m11-six-day-retrospective.md b/slidev/pages/day6/m11-six-day-retrospective.md new file mode 100644 index 0000000..e313ff4 --- /dev/null +++ b/slidev/pages/day6/m11-six-day-retrospective.md @@ -0,0 +1,221 @@ +# 复盘：六天能力图谱 + +
+ +六天内容只有一条主线：让 AI 参与研发时，团队如何持续获得事实、控制范围、验证行为，并把可靠经验沉淀下来。 + +
+ +
+
看懂项目
+-> +
组织上下文
+-> +
处理复杂业务
+-> +
沉淀团队资产
+-> +
进入工程闭环
+
+ + + +--- + +# 第 1 天：先把陌生项目变成可追溯的事实 + +
+ +| 学到的动作 | 不能跳过的原因 | 交付物 | +|---|---|---| +| 找模块、入口与关键对象 | 不知道系统在哪里，就无法讨论改动影响 | 模块认知图、项目结构图 | +| 追认证、路由、权限和日志链路 | 后台系统的风险常在跨层调用关系中 | 调用链路图 | +| 区分代码事实、业务事实与推断 | AI 的流畅表达不等于项目真实行为 | 输出校验清单 | +| 写代码理解报告 | 让团队的理解可被交接和审查 | 代码理解报告 | + +
+ +
+项目理解必须回到文件、函数、调用关系和不确定点，不能停在泛泛总结。 +
+ + + +--- + +# 第 2 天：把一次会话变成可复用的上下文与规则 + +
+ +| 学到的动作 | 解决的问题 | 交付物 | +|---|---|---| +| 用目标、范围、约束、输出、验收组织任务 | 避免 AI 泛泛回答和无边界修改 | 上下文组织清单 | +| 组合 @workspace、#File、#Code、#Web | 让检索从宽到窄、从事实到细节 | 上下文引用模板 | +| 先收集证据，再判断和给方案 | 切断幻觉和错误归因 | 证据收集 Prompt | +| 编写安全、编码、测试与前端 Rule | 让团队隐性习惯变成可执行约束 | rules.md v0.1 与检查单 | + +
+ +
+好规则不是“写得严格”，而是能说明何时触发、必须检查什么、不能做什么、如何验收。 +
+ + + +--- + +# 第 3 天：从工具功能转向任务编排能力 + +
+ +| 学到的动作 | 关键判断 | 交付物 | +|---|---|---| +| 理解 Rule、Cue、模型和 Token 的位置 | 资源要匹配任务风险与信息复杂度 | 成本与任务匹配表 | +| 区分 Command、Skill、MCP 与 CLI | 高频输入、多步决策和外部工具不是同一问题 | 能力封装决策表 | +| 设计 Agent 分工 | 输入、输出、验收和停止条件都要明确 | Agent 分工表 | +| 使用 Browser、文档与 Plan | 先计划、再执行、再记录验证 | 前端验证清单与 Plan 检查项 | + +
+ +
+任务越复杂，越需要先把边界显式化，不能因为有 Agent 就跳过计划。 +
+ + + +--- + +# 第 4 天：复杂业务先建立控制面，再讨论实现 + +
+ +| 业务难点 | 先产出的控制面 | 为什么不能直接生成代码 | +|---|---|---| +| 权限 | RBAC 矩阵、页面/按钮/接口/数据范围方案 | 角色与数据范围是业务事实 | +| 状态 | 状态流转表、非法流转清单 | 允许和拒绝路径都必须明确 | +| 审计 | 字段表、前后值、SOP | “记录日志”不足以保证可追溯 | +| 异常态 | 前后端行为与最小测试集 | 正常流程跑通不代表业务安全 | +| 看板 | 指标字典、接口契约和验收 | 数字必须有口径、来源和权限范围 | + +
+ +
+复杂业务最危险的顺序是“先让 AI 写代码，再回头补权限、状态和审计”。 +
+ + + +--- + +# 第 5 天：把可靠判断沉淀为可维护资产 + +
+ +| 资产 | 适合保存什么 | 不应保存什么 | +|---|---|---| +| Rule | 长期稳定、违反代价高的约束 | 一次任务的临时路径和猜测 | +| 任务上下文契约 | 输入、输出、证据缺口和停止条件 | 没有来源的项目事实 | +| Checklist / Template | 固定遗漏点和稳定输出结构 | 所有判断逻辑的重复副本 | +| Skill | 多步骤、需要证据和验收的工作流 | 只有一句指令的简单需求 | +| Agent / MCP | 稳定角色、权限边界和外部能力 | 未声明读写性质的工具连接 | + +
+ +
+资产化不是把聊天记录保存下来，而是把可复用的判断、边界和验证方式保存下来。 +
+ + + +--- + +# 第 6 天：让 AI 改动进入真实工程闭环 + +
+ +| 工程环节 | AI 可以辅助的工作 | 人必须负责的判断 | +|---|---|---| +| PR 与 Git | 归纳 Diff、生成说明、检查范围 | 改动是否该合入、如何回退 | +| Review | 发现风险、汇总证据缺口、生成问题草稿 | 问题是否成立、优先级与修复决策 | +| CI | 分类日志、关联配置与 Diff、建议验证命令 | 区分代码缺陷与环境处置 | +| 证据链 | 整理需求、实现、测试和边界 | 结论能否被当前证据支持 | +| 资产变更 | 检查引用、夹具和行为变化 | 权限和兼容性是否可接受 | + +
+ +
+AI 产出必须进入已有的工程审查、验证和责任体系。 +
+ + + +--- + +# 六项能力必须形成闭环 + +
+
事实
代码、配置、日志和业务确认。
+
上下文
目标、范围、约束、输出和验收。
+
计划
影响范围、最小方案、风险和验证。
+
控制面
权限、状态、审计、异常和指标。
+
验证
测试、CI、浏览器和人工观察。
+
沉淀
PR、证据链、Rule、Skill 和资产库。
+
+ + + +--- + +# 六天里最应该避免的六种误用 + +
+ +| 误用 | 正确替代动作 | +|---|---| +| 让 AI 泛泛总结整个项目 | 指定入口、问题、范围和证据格式 | +| 把模型回答当作业务规则 | 区分代码事实、业务确认、推断与待确认 | +| 直接接受大范围代码生成 | 先审阅 Plan，选择最小可验证 Diff | +| 只隐藏前端按钮就认为有权限控制 | 验证页面、按钮、接口和数据范围四层边界 | +| CI 变红就修改业务代码 | 先定位最早错误，区分代码、依赖、配置和环境 | +| 把一次有效 Prompt 直接升级为团队标准 | 先验证适用范围、停止条件和代表性夹具 | + +
+ + + +--- + +# 最终交付不应只有代码 + +
+
项目结构、调用链与事实记录
+
上下文包、Rule、Prompt 和检查单
+
权限、状态、审计、异常与指标控制面
+
Plan、Diff、测试、浏览器与 CI 证据
+
PR 说明、Review、修复记录和未覆盖边界
+
可验证、可维护、可演进的工程资产
+
+ +
代码是结果之一；可复用、可验证、可维护的工程资产，才能支撑长期协作。
+ + diff --git a/slidev/pages/day6/m2-pr-template-ai-record.md b/slidev/pages/day6/m2-pr-template-ai-record.md new file mode 100644 index 0000000..164128d --- /dev/null +++ b/slidev/pages/day6/m2-pr-template-ai-record.md @@ -0,0 +1,162 @@ +# 模块 2：标准 PR 说明与 AI 使用记录 + +
+ +PR 是团队协作里最稳定的交付节点。 + +如果 TRAE 参与了需求拆解、代码修改、测试和 Review，PR 说明里就要能看见这些证据。 + +
+ +
+
需求背景
+
实现说明
+
测试结果
+
风险与 AI 记录
+
+ + + +--- + +# PR 模板 + +
+ +```md +## 需求背景 +<为什么做，本次解决什么> + +## 实现说明 +<改了哪些模块、接口、页面、规则> + +## 测试结果 +- [ ] 单元测试： +- [ ] 接口验证： +- [ ] 浏览器验证： +- [ ] 手工验收： + +## 风险点 +<权限、状态、审计、异常、兼容性、数据范围> + +## AI 使用记录 + + +## 关联资产 +<使用了哪些 rules、任务上下文契约、skills、checklists> +``` + +
+ + + +--- + +# PR 说明示例 + +
+ +```md +## 需求背景 +取消已派车任务时，后端必须拒绝空白取消原因。 + +## 实现说明 +- `OfficialVehicleDispatchServiceImpl.cancel` 在状态写入前加入 `Assert.hasText`。 +- 新增全空白取消原因的 Service 单元测试。 +- 未改前端必填、权限、审计、SQL、派车和行程逻辑。 + +## 测试结果 +- [x] 单元测试：覆盖空白取消原因的拒绝行为。 +- [ ] 接口、数据库、浏览器和审计验证：按实际执行情况记录。 + +## 风险点 +统一异常映射、非空正常取消路径和外部调用方需要单独确认。 +``` + +
+ + + +--- + +# TRAE 生成 PR 说明的任务上下文契约 + +
+ +```md +请基于以下材料生成标准 PR 说明：任务背景、 +main 与当前分支的 git diff、实际测试结果、Review 结论、 +使用过的 rules、任务上下文契约、skills。 + +输出必须包含：需求背景、实现说明、测试结果、风险点、 +AI 使用记录、关联资产。 + +要求：不要编造测试结果；没有证据的测试项标记“未执行”； +风险必须具体到模块或文件；不要将训练约束写成客户既有需求。 +``` + +
+ + + +--- + +# AI 使用记录表 + +
+ +| 环节 | TRAE 做了什么 | 人工判断 | 沉淀内容 | +|---|---|---|---| +| 代码理解 | 定位前端必填、取消 API、权限、审计和 Service | 用源码逐条核对 | 影响分析任务上下文契约 | +| 方案选择 | 建议 Service 作为最终保护边界 | 因状态变更和车辆释放都在此处而采纳 | 状态变更 Rule | +| 测试设计 | 提出空白输入与正常取消回归点 | 仅将实际执行的空白单测标为通过 | 测试安全网 | +| 交付说明 | 整理最小 diff、风险和待确认项 | 删除任何无证据的“已验证”表述 | PR 模板 | + +
+ + + +--- + +# AI 使用记录不是聊天记录 + +
+ +| 应保留 | 不必保留 | +|---|---| +| 影响实现或验证结论的 AI 建议 | 完整对话逐字稿 | +| 人工采纳或否决建议的理由 | 与本次改动无关的探索 | +| 关联的 Rule、任务上下文契约、Skill 或检查单 | 无法复查的笼统评价 | +| 未解决风险和待确认边界 | 把推断包装成已验证结论 | + +
+ +
+好的 PR 说明，让评审者看到工程结论，而不是看到一段 AI 对话。 +
+ + diff --git a/slidev/pages/day6/m3-ai-code-review.md b/slidev/pages/day6/m3-ai-code-review.md new file mode 100644 index 0000000..53123d4 --- /dev/null +++ b/slidev/pages/day6/m3-ai-code-review.md @@ -0,0 +1,111 @@ +# 模块 3：AI 变更的 Git 协作与合并控制 + +
+ +TRAE 可以加快修改，但不能绕开 Git 的可追溯、可审查和可回退要求。 + +AI 参与的改动越多，越要让分支、提交和合并边界保持清楚。 + +
+ +
+
分支范围
+
提交粒度
+
冲突处理
+
合并控制
+
+ + + +--- + +# 分支和提交要服务于审查 + +
+ +| 做法 | 为什么重要 | 公务用车案例 | +|---|---|---| +| 一个分支只解决一个问题 | diff 容易审查和回退 | 取消原因保护不混入无关重构 | +| 一个提交对应一个可验证动作 | 可定位问题和选择性回退 | 参数保护与对应测试保持一致 | +| 提交前排除无关文件 | 噪声不会掩盖业务风险 | 构建生成物不应混入业务变更 | +| 描述真实变更与验证情况 | 后续定位有证据 | 提交信息和 PR 只写有依据的验证 | + +
+ + + +--- + +# 合并前的四道检查 + +
+ +| 检查点 | 要确认什么 | 当前案例的检查问题 | +|---|---|---| +| 范围 | diff 是否只包含已说明的改动 | 是否只有 Service 校验和相应测试？ | +| 证据 | PR 是否如实标记测试、风险和未确认项 | 是否把 API 或浏览器验证误写为已通过？ | +| 冲突 | 是否理解双方业务意图 | 是否保留“写入前校验”的顺序？ | +| 回退 | 是否知道回退哪个提交、是否涉及数据补偿 | 代码改动可以选择性回退；集成数据仍需另行核对 | + +
+ + + +--- + +# 用 TRAE 审查变更范围 + +
+ +```md +请检查以下 git diff 是否符合本次变更范围。 + +目标：取消派车必须由后端拒绝空白取消原因。 +允许修改：Dispatch Service 的参数保护和对应的聚焦测试。 +禁止修改：SQL、权限、菜单、前端页面、派车/行程状态协议、无关格式。 +证据：实际 Maven 定向测试结果；API 和浏览器验证尚未执行。 + +请输出：直接相关改动、可能无关或风险较高改动、 +合并前必须补充的验证、回退点。 +``` + +
+ + + +--- + +# Git 历史也是工程接口 + +
+
看得懂
目标与范围一致
+
审得动
每次改动足够聚焦
+
退得回
影响与恢复路径清楚
+
查得到
结论能对应 diff 与证据
+
+ +
+AI 可以生成改动，Git 负责把改动保留为可理解、可审查的工程历史。 +
+ + diff --git a/slidev/pages/day6/m4-ci-failure-loop.md b/slidev/pages/day6/m4-ci-failure-loop.md new file mode 100644 index 0000000..828e887 --- /dev/null +++ b/slidev/pages/day6/m4-ci-failure-loop.md @@ -0,0 +1,284 @@ +# 模块 4：CI 失败日志分析 + +
+ +CI 失败时，首先要判断失败来自代码、配置、依赖还是运行环境。 + +TRAE 可提取日志中的直接错误、关联改动和缺失证据；修复前仍要先确认失败来源。 + +
+ +
+
代码
+
测试
+
配置
+
依赖
+
环境
+
+ + + +--- + +# 先按失败来源分类 + +
+ +| 失败来源 | 常见信号 | 首先核对的材料 | 处理边界 | +|---|---|---|---| +| 代码与类型 | 编译、lint、类型报错指向具体文件 | diff、调用方、类型定义 | 只修改能解释错误的实现 | +| 测试断言 | 预期与实际结果不同 | 测试用例、业务规则、测试数据 | 不能只为通过而改断言 | +| 构建配置 | 脚本、工作流、环境变量缺失 | package/pom、workflow、项目规则 | 先确认配置是否属于本次改动 | +| 依赖解析 | 版本冲突、锁文件不一致、制品缺失 | lockfile、依赖树、仓库配置 | 区分项目依赖与制品服务异常 | +| Runner 与环境 | 权限、磁盘、网络、系统工具失败 | Runner 日志、环境配置、重试结果 | 不把环境故障归因到源码 | + +
+ +
+分类不是为了快速贴标签，而是为了确定下一份该看的证据。 +
+ + + +--- + +# 日志必须和 diff 一起读 + +
+ +| 日志现象 | 与 diff 的关系 | 正确结论 | +|---|---|---| +| 新增类型错误指向本次修改文件 | 直接命中新增或改动行 | 优先检查该改动与接口契约 | +| 测试失败在相邻模块，diff 未触及该模块 | 关联尚未建立 | 标记待确认，不把失败直接归因于本次改动 | +| 依赖下载失败，代码尚未进入编译 | 没有代码执行证据 | 按环境或依赖问题排查 | +| 同一失败在未改动分支也可复现 | 与本次 diff 无关 | 记录为基线问题或外部问题 | + +
+ +
+
日志给出直接错误
+
diff 说明影响范围
+
两者共同支持根因
+
+ + + +--- + +# 代码修复与环境处置要分开 + +
+ +| 场景 | 代码侧动作 | 环境侧动作 | 不应做的事 | +|---|---|---|---| +| 类型或编译失败 | 修正实现、类型或调用契约 | 保持环境不变 | 顺手升级无关依赖 | +| 测试预期冲突 | 复核业务规则和测试数据 | 保留失败记录 | 只改断言让流水线通过 | +| 依赖解析失败 | 核对锁文件与版本声明 | 核对制品源、缓存和网络 | 修改业务逻辑 | +| Runner 权限或资源不足 | 不改项目源码 | 调整 Runner 或重试并留存结果 | 误报为代码缺陷 | + +
+ +
+修复范围必须和失败来源一致；CI 通过也不应掩盖未验证的业务风险。 +
+ + + +--- + +# 公务用车模块：已执行的定向测试门禁 + +
+ +```bash +mvn -pl jeecg-boot-module/jeecg-module-officialvehicle -am \ + -DskipTests=false \ + -Dtest=OfficialVehicleDispatchServiceImplTest \ + -Dsurefire.failIfNoSpecifiedTests=false test +``` + +| 项目事实 | 该命令支持的结论 | 不能外推的结论 | +|---|---|---| +| 公务用车模块启用了 Maven Surefire 测试 | 模块依赖与指定 Service 用例能够被执行 | 接口、数据库、浏览器与审计链路已验证 | +| 用例传入全空白取消原因 | `cancel` 会在状态写入前拒绝空白原因 | 非空正常取消路径已经回归 | +| 2026-08-06 记录为 `BUILD SUCCESS`，1 项用例零失败 | 本次定向 Service 验证通过 | 全模块或生产可发布 | + +
+ +
+可执行命令、实际结果和结论边界一起保存，才构成一项可复核的质量门禁证据。 +
+ + + +--- + +# 真实失败案例：Maven 本地仓库无写入权限 + +
+ +
+ +```text +[WARNING] Failed to write tracking file +$HOME/.m2/repository/.../resolver-status.properties + +[ERROR] java.io.FileNotFoundException +(Operation not permitted) +[ERROR] BUILD FAILURE +``` + +
+ +
+ +| 判断项 | 本次结论 | +|---|---| +| 首个直接错误 | Maven 更新本地仓库跟踪文件时被系统拒绝 | +| 失败来源 | 本地环境 / 文件权限 | +| 与业务 diff 的关联 | 未建立源码关联证据 | +| 正确处置 | 恢复 Maven 仓库写入条件，保留日志后重跑 | +| 不应做的事 | 修改派车 Service、测试断言或业务状态逻辑 | + +
+ +
+ +
+构建失败发生在依赖元数据写入阶段时，不能据此推断公务用车业务代码存在缺陷。 +
+ + + +--- + +# CI 分析任务上下文契约 + +
+ +```md +请分析以下 CI 失败日志。 + +输入材料：CI 日志、相关 diff、package/pom/workflow 配置、锁文件、项目 rules。 + +请输出： +1. 首个失败阶段与原始错误；2. 失败来源分类； +3. 与 diff 的关联证据；4. 有依据的根因判断； +5. 需要查看的文件或环境信息；6. 候选处置方案；7. 验证命令； +8. 是否适合沉淀为规则或检查清单。 + +要求：先解释失败原因，再给方案；不能只根据最后一行日志下结论； +区分代码修复与环境处置；证据不足时标记待确认。 +``` + +
+ + + +--- + +# CI 修复记录 + +
+ +| 字段 | 内容 | +|---|---| +| 失败阶段 | lint / typecheck / test / build / dependency / environment | +| 原始错误 | 日志中的直接报错，不改写 | +| 失败来源 | 代码、测试、配置、依赖、Runner 或外部服务 | +| diff 关联 | 命中改动 / 无关联证据 / 待确认 | +| 根因 | 支持判断的日志、配置或代码证据 | +| 处置范围 | 代码修复或环境处置，涉及哪些位置 | +| 验证命令 | 本地或 CI 重新执行命令 | +| 结果 | 通过 / 未通过 / 待确认 | +| 资产沉淀 | rule / checklist / 任务上下文契约 / example / 不沉淀 | + +
+ + + +--- + +# CI 质量门禁分别覆盖什么？ + +
+ +| 门禁 | 作用 | 不能替代什么 | +|---|---|---| +| lint | 保证基础格式和规范 | 业务规则审查 | +| typecheck | 提前发现接口和类型不匹配 | 运行时行为验证 | +| unit test | 保护核心逻辑 | 完整集成链路 | +| coverage | 发现测试覆盖缺口 | 测试质量判断 | +| manual checklist | 覆盖权限、审计、状态和页面验收 | 可重复的自动化验证 | + +
+ +
+质量门禁不是越多越好，而是每道门禁都要清楚自己覆盖和不覆盖什么。 +
+ + + +--- + +# 一条 CI 结论应当写清什么？ + +
+ +| 信息 | 说明 | +|---|---| +| 失败阶段 | lint、类型检查、测试、构建、依赖或环境 | +| 原始错误 | 保留日志中的直接报错，不提前改写 | +| diff 关联 | 说明是否命中本次改动及依据 | +| 根因判断 | 说明对应的配置、代码或环境依据 | +| 处置范围 | 只指出确实需要调整的位置 | +| 验证方式 | 使用可重复的命令或 CI 结果确认 | +| 结论边界 | 证据不足时明确标记待确认 | + +
+ +
+先区分直接错误、失败来源和根因，再决定是否修改代码。 +
+ + diff --git a/slidev/pages/day6/m5-asset-governance.md b/slidev/pages/day6/m5-asset-governance.md new file mode 100644 index 0000000..c9acb8d --- /dev/null +++ b/slidev/pages/day6/m5-asset-governance.md @@ -0,0 +1,149 @@ +# 模块 5：共享资产的版本与兼容性 + +
+ +Rule、任务上下文契约、Skill、自定义 Agent 和 MCP 契约一旦被共享使用，就会影响后续任务的判断与行为。 + +共享资产治理要明确资产变更后的可用范围、引用迁移与旧版本退出方式。 + +
+ +
+
版本
+
兼容
+
迁移
+
回退
+
+ + + +--- + +# 哪些资产变更属于行为变更？ + +
+ +| 资产 | 变更示例 | 可能改变的行为 | +|---|---|---| +| Rule | 增加必须检查的前置条件 | Agent 的允许范围和停止条件 | +| 任务上下文契约 | 删除一个必填输入字段 | 输出是否仍有足够事实基础 | +| Skill | 调整步骤或输出 Schema | 下游任务能否继续消费结果 | +| 自定义 Agent | 增加工具或修改默认指令 | 可访问的能力和风险边界 | +| MCP 契约 | 更改读写标识或错误语义 | 调用权限与失败后的处置 | + +
+ +
+只要会改变 Agent 的输入、判断、输出或权限，就不应把它当成普通文案修改。 +
+ + + +--- + +# 版本号应表达使用边界 + +
+ +| 变更类型 | 使用建议 | 对既有调用方的要求 | +|---|---|---| +| 仅修正文案，不改变输入输出或约束 | 小版本 | 保持原有验证夹具通过 | +| 增加可选字段或补充反例 | 小版本，并说明新增行为 | 检查是否需要提供新材料 | +| 修改必填输入、输出结构、权限或停止条件 | 新版本边界 | 明确迁移方式和不兼容点 | +| 移除能力或结束支持 | 弃用版本 | 保留替代资产和退出期限 | + +
+ + + +--- + +# 兼容性说明的最小字段 + +
+ +| 字段 | 要回答的问题 | +|---|---| +| 资产与版本 | 当前使用的是哪一份可识别资产？ | +| 适用范围 | 面向哪些项目、任务或技术栈？ | +| 行为变化 | 输入、输出、约束、工具权限中变了什么？ | +| 不兼容点 | 哪些旧引用、模板或 Agent 不能直接继续使用？ | +| 迁移方式 | 使用者需要替换什么、补充什么或调整什么？ | +| 回退条件 | 遇到何种结果时应回到哪个稳定版本？ | +| 验证证据 | 哪些夹具、测试或实际记录支持本次变化？ | + +
+ +
+兼容性说明服务于正确替换，不是为了增加文档数量。 +
+ + + +--- + +# 弃用不是删除旧文件 + +
+ +| 需要保留的信息 | 目的 | +|---|---| +| 被替代的版本与适用范围 | 识别历史引用，不误用旧能力 | +| 替代资产及目标版本 | 提供明确迁移方向 | +| 不再适用的原因 | 防止未来又恢复同一错误做法 | +| 已知引用位置 | 便于逐项替换与复核 | +| 回退条件与稳定版本 | 变更异常时能够恢复已验证行为 | + +
+ +
+
直接删除：历史引用失去解释
+
明确弃用：新旧边界仍可追溯
+
+ + + +--- + +# 版本发布前需要确认什么？ + +
+ +| 确认项 | 要回答的问题 | 形成的版本结论 | +|---|---|---| +| 当前稳定版本 | 哪个版本仍可作为已知可用的回退点？ | 明确 source version | +| 目标版本边界 | 新版本改变了哪些使用前提与适用范围？ | 明确 target version | +| 使用者与引用 | 哪些 Rule、Skill、Agent、MCP 或模板仍依赖旧版本？ | 明确迁移清单 | +| 退出与回退 | 旧版本何时停止默认使用，异常时回到哪里？ | 明确弃用与恢复路径 | + +
+ +
+模块 5 解决“发布哪个版本、谁需要迁移、出现异常退回哪里”；单次资产 diff 的验证证据由模块 8 处理。 +
+ + diff --git a/slidev/pages/day6/m6-onboarding-rollout.md b/slidev/pages/day6/m6-onboarding-rollout.md new file mode 100644 index 0000000..8f6cce9 --- /dev/null +++ b/slidev/pages/day6/m6-onboarding-rollout.md @@ -0,0 +1,207 @@ +# 模块 6：变更证据链与可追溯说明 + +
+ +AI 可以帮助定位和实现，但不能替代研发交付中的说明责任。 + +一次改动是否值得合入，取决于阅读者能否快速判断：改了什么、为什么改、验证到哪里、还存在哪些边界。 + +
+ +
+
目标
+
范围
+
证据
+
边界
+
+ + + +--- + +# PR 模板不等于证据链 + +
+ +| PR 模板解决什么 | 证据链解决什么 | +|---|---| +| 让评审者快速阅读改动说明 | 让每条结论回到可核对的事实 | +| 组织目标、实现、测试和风险 | 关联需求、diff、测试、CI、日志与人工观察 | +| 呈现本次交付 | 支撑结论强度与后续排查 | +| 可以由 AI 协助起草 | 必须由真实记录持续校验 | + +
+ +
+PR 是阅读入口；证据链是结论能够被复核的依据。 +
+ + + +--- + +# 一条变更证据链包含什么？ + +
+ +| 证据节点 | 能支持的判断 | 不能替代的判断 | +|---|---|---| +| 需求与规则 | 改动目标、约束和非目标 | 实现已正确运行 | +| diff 与代码阅读 | 修改范围、调用关系与关键分支 | 线上或全链路行为 | +| 自动化测试 | 对应方法、接口或场景的行为 | 未覆盖路径的行为 | +| CI 结果与日志 | 构建、检查和已运行用例的结果 | 所有环境和业务风险 | +| API、浏览器或人工观察 | 特定环境下的真实交互结果 | 未观察到的条件组合 | +| 已知边界 | 仍需确认的依赖与缺口 | 已完成验证的替代结论 | + +
+ + + +--- + +# 用证据地图连接结论 + +
+ +
需求与规则
+-> +
diff 与关键代码
+-> +
测试与 CI
+-> +
技术结论
+ +
+ +
+
每个结论都能回指来源
+
每项证据都有适用边界
+
缺口不能被推断补全
+
+ + + +--- + +# 技术结论要和证据强度匹配 + +
+ +| 信息类别 | 可以形成的结论 | 常见误区 | +|---|---|---| +| 代码阅读 | 已定位到调用入口、状态写入点或权限判断 | 把源码推断当作线上运行结论 | +| 实际变更 | 本次修改了哪些文件、条件和分支 | 用“优化”“完善”等词掩盖改动范围 | +| 自动化验证 | 已覆盖某个方法、接口或用例 | 用局部测试替代全链路验证 | +| 待确认事项 | 业务规则、外部调用、环境差异仍需核对 | 用“应该没有影响”替代事实 | + +
+ +
+证据能支持多大的结论，就只写多大的结论。 +
+ + + +--- + +# 证据丢失时，结论也会失效 + +
+ +| 缺失的证据 | 常见后果 | 正确处理 | +|---|---|---| +| 原始 CI 日志 | 无法判断失败来自代码还是环境 | 保留失败阶段、原始错误与关联链接 | +| 已执行命令与结果 | “已测试”无法复核 | 记录命令、环境和结果摘要 | +| 需求或规则依据 | 不清楚为什么改、是否越界 | 关联明确的约束与非目标 | +| diff 与关键位置 | 无法核对实际影响范围 | 说明模块、入口和关键条件 | +| 未覆盖边界 | 被误解为全量验证 | 明确写出待确认项和原因 | + +
+ +
+没有证据的“已完成”，在工程上等同于不可审查的结论。 +
+ + + +--- + +# 一份可审查的改动说明 + +
+ +```md +## 改动目标 +解决什么业务问题或风险，并关联需求或规则依据。 + +## 实现范围 +涉及的模块、入口和关键判断；明确未修改的相邻范围。 + +## 验证证据 +已执行的测试、检查项、CI 或实际观察，以及对应结果。 + +## 已知边界 +尚未覆盖的场景、依赖的前提和需要业务确认的事项。 +``` + +
+ +
+
避免：功能已完成、已充分测试
+
写清：已覆盖范围与未覆盖范围
+
+ + + +--- + +# 让 AI 产出成为工程知识 + +
+ +| 只保留对话 | 留下可追溯说明 | +|---|---| +| 结论散落在窗口和临时文件里 | 关键结论随代码或 PR 一起保存 | +| 难以判断 AI 建议是否被采纳 | 清楚说明人工选择了什么、舍弃了什么 | +| 后续排查需要重新理解上下文 | 可直接定位目标、范围、证据和边界 | +| 相同问题容易重复分析 | 可复用判断方式，但重新核对项目事实 | + +
+ +
+AI 的价值不止是更快产出代码，也包括留下经得起复核的技术结论。 +
+ + diff --git a/slidev/pages/day6/m7-maintainability-review.md b/slidev/pages/day6/m7-maintainability-review.md new file mode 100644 index 0000000..8bf5c0a --- /dev/null +++ b/slidev/pages/day6/m7-maintainability-review.md @@ -0,0 +1,179 @@ +# 模块 7：AI 改动的可演进性审查 + +
+ +业务行为通过验证，只说明本次任务得到了正确结果。 + +可演进性关心的是下一次规则变化时，能否找到唯一入口、控制影响范围、替换依赖并准确定位回归。 + +
+ +
+
修改入口
+
单一权威
+
依赖隔离
+
回归定位
+
+ + + +--- + +# 四类会放大后续修改成本的风险 + +
+ +| 风险 | 典型表现 | 更好的处理 | +|---|---|---| +| 修改入口分散 | 一个业务变化要在多个页面、接口或服务中同步修改 | 明确唯一的规则入口和调用边界 | +| 平行规则 | 同一校验在多个位置各自维护一份 | 让关键规则只有一个权威实现 | +| 隐藏依赖 | 逻辑依赖环境、全局状态或外部服务却不可见 | 把依赖显式注入、记录或隔离 | +| 回归难定位 | 失败只能靠全项目搜索和猜测 | 保留可观察结果、场景夹具与最小影响范围 | + +
+ + + +--- + +# 从“本次通过”到“下次可改” + +
+ +| 本次交付已确认 | 可演进性还要确认 | +|---|---| +| 当前行为符合预期 | 下一次规则变化从哪里修改最清楚 | +| 本次 diff 已通过构建与测试 | 影响范围能否被调用关系和夹具限制 | +| 新逻辑放进了可运行的位置 | 关键规则是否有唯一权威位置 | +| 用例覆盖当前结果 | 失败时能否回到具体场景和依赖定位 | + +
+ +
+可演进的改动，不是为未来过度设计，而是不给下一次变化留下多份解释。 +
+ + + +--- + +# 可演进性审查的四个问题 + +
+
规则变化时，第一处应修改哪里？
+
关键约束是否只有一个权威实现？
+
外部依赖能否替换、观察或明确失败？
+
回归能否缩小到具体场景、diff 与依赖？
+
+ +
+审查的目标，是让 AI 生成的改动成为下一次可靠修改的起点。 +
+ + + +--- + +# 公务用车案例：规则入口与状态写入相邻 + +
+ +| 已读取的实现事实 | 对后续修改的意义 | +|---|---| +| `OfficialVehicleDispatchServiceImpl.cancel` 首行使用 `Assert.hasText` 校验取消原因 | 取消原因规则有明确的后端最终保护入口 | +| 同一方法随后读取派车单、校验 `DISPATCHED` 状态、写入取消状态与原因，并释放车辆 | 规则与其保护的状态写入相邻，影响范围容易阅读 | +| `OfficialVehicleDispatchServiceImplTest` 直接传入全空白原因并断言异常 | 规则变化可以从同一测试文件开始定位回归 | + +
+ +
+下一次调整“取消原因”规则时，应先从 Service 与这项聚焦测试开始；不应在页面、Controller 和 Service 中维护多份独立规则。 +
+ + + +--- + +# 案例结论：已获得的可维护性证据 + +
+ +
+ +
已经由源码与测试支持
+ +| 证据 | 可形成的结论 | +|---|---| +| 本次训练分支仅改动 Service 参数保护和对应测试 | 改动范围聚焦，未混入页面、SQL 或状态协议调整 | +| 空白原因在读取派车单与写状态前被拒绝 | 无效输入不会进入后续状态变更路径 | +| 定向 Maven 测试记录为成功 | 该 Service 场景具备可重复的回归起点 | + +
+ +
+ +
尚不能由现有材料证明
+ +| 缺少的证据 | 不能写成的结论 | +|---|---| +| 取消接口的 HTTP / 统一异常验证 | 前端会收到何种错误码和提示 | +| 非空正常取消的集成验证 | 派车、车辆状态与审计已完整回归 | +| 浏览器与数据库观察记录 | 页面交互和持久化链路已通过 | + +
+ +
+ +
+可维护性审查也要按证据说话：明确规则入口与回归起点，不把局部验证扩大成全链路结论。 +
+ + + +--- + +# 何时需要重构，何时保持聚焦？ + +
+ +| 观察到的证据 | 适合的处理 | 不应做的事 | +|---|---|---| +| 当前只新增一条取消原因非空规则，且规则入口就在状态变更方法中 | 保持 Service 中的最小改动，并维护同一聚焦测试 | 为单一校验新建没有复用对象的抽象层 | +| 后续出现多个取消入口且重复表达同一规则 | 先核对全部调用方、状态效果与测试，再评估抽取唯一规则入口 | 未确认重复语义就机械合并代码 | +| 发现外部调用方、异常协议或审计要求会影响规则 | 补齐接口与集成证据，再调整边界 | 用猜测替代兼容性和回归验证 | + +
+ +
+可演进性不是预先堆叠抽象，而是让每次重构都有明确的重复、耦合或回归证据。 +
+ + diff --git a/slidev/pages/day6/m8-asset-change-validation.md b/slidev/pages/day6/m8-asset-change-validation.md new file mode 100644 index 0000000..e85fe83 --- /dev/null +++ b/slidev/pages/day6/m8-asset-change-validation.md @@ -0,0 +1,195 @@ +# 模块 8：资产变更也要走工程验证 + +
+ +代码变更会进入 Review、测试和 CI；会影响 Agent 行为的资产变更也应接受同样严肃的验证。 + +Rule、任务上下文契约、Skill、自定义 Agent 和 MCP 契约不是静态文档，而是研发过程中的可执行配置。 + +
+ +
+
Rule
+
上下文契约
+
Skill
+
Agent
+
MCP
+
+ + + +--- + +# 为什么资产变更会改变行为？ + +
+ +| 改动位置 | 直接影响 | 需要防范的风险 | +|---|---|---| +| Rule 的必须与禁止项 | 任务允许做什么、何时停止 | 放宽关键约束或误伤正常任务 | +| 任务上下文契约的输入与输出 Schema | 模型可依据什么、结果如何被消费 | 事实缺失、下游解析失效 | +| Skill 的步骤与引用 | 判断顺序、加载的资产和交接结果 | 漏掉验证步骤或引用旧资产 | +| Agent 的指令与工具 | 角色职责、可调用能力和权限 | 越权、职责重叠或不可控输出 | +| MCP 的能力契约 | 外部读写范围与失败语义 | 把高风险调用当成只读查询 | + +
+ +
+审查资产 diff 的重点，是行为变化，而不是措辞是否顺畅。 +
+ + + +--- + +# 资产变更审查的四个问题 + +
+
输入、输出、停止条件或权限改变了吗？
+
名称、路径、引用和元数据仍能正确解析吗？
+
实际行为变化与本次变更目的一致吗？
+
完整、缺失、冲突和越界输入都重新验证了吗？
+
+ +
+四个问题覆盖语义、引用、变更意图与边界验证。 +
+ + + +--- + +# 用测试夹具做资产回归 + +
+ +| 夹具类型 | 输入特征 | 预期行为 | +|---|---|---| +| 完整输入 | 事实、规则和验证材料齐全 | 输出结构完整，结论能关联证据 | +| 缺失输入 | 缺少关键代码、日志或规则 | 明确列出缺口并停止结论 | +| 冲突输入 | 需求、规则和实现信息不一致 | 标识冲突，不擅自选择一方 | +| 越界输入 | 请求超出定义的项目或权限范围 | 拒绝越界操作，解释允许范围 | + +
+ +
+资产回归验证边界是否正确，不要求模型每次生成完全相同的文字。 +
+ + + +--- + +# 修改前后都要检查引用完整性 + +
+ +| 检查对象 | 典型问题 | 验证方式 | +|---|---|---| +| Skill 元数据 | 名称、触发描述、入口路径失效 | 读取目录与发现配置 | +| Rule 与任务上下文契约引用 | 指向旧路径、旧字段或旧版本 | 搜索引用并运行代表性任务 | +| Agent 调用 Skill | 角色名或交接 Schema 改变 | 检查调用参数与结构化输出 | +| MCP 工具契约 | 工具名、读写标记、错误语义不一致 | 契约校对与权限夹具 | +| 下游交付模板 | 新输出字段未被消费或旧字段仍被依赖 | 对照输入输出 Schema | + +
+ + + +--- + +# 三类不能直接合入的资产变更 + +
+ +| 信号 | 风险 | 需要补齐的内容 | +|---|---|---| +| 新增工具权限，却没有用途和停止边界 | Agent 可能越权调用外部能力 | 权限说明、允许场景和失败降级 | +| 修改必填输入或输出结构，却没有代表性夹具 | 行为变化无法被回归判断 | 覆盖正常、缺失与冲突材料的验证记录 | +| 更新规则或任务上下文契约，却没有代表性夹具 | 无法判断是修复还是引入新误用 | 完整、缺失、冲突和越界输入验证 | + +
+ +
+没有行为说明、引用检查和验证证据的资产 diff，不具备合入条件。 +
+ + + +--- + +# 资产变更的最小交付说明 + +
+ +```md +## 变更目的 +解决的重复问题、误用风险或项目事实变化。 + +## 行为变化 +输入、输出、约束、工具权限、停止条件中发生了什么变化。 + +## 变更范围与引用结果 +受影响的文件、调用方、模板或配置，以及名称、路径和 Schema 的检查结果。 + +## 验证证据 +已运行的夹具、引用检查和可复核结果；未覆盖项如实列出。 +``` + +
+ + + +--- + +# 资产也纳入工程质量闭环 + +
+ +
识别行为变化
+-> +
检查引用与解析结果
+-> +
验证夹具与权限边界
+-> +
留下可追溯结论
+ +
+ +
+代码和 AI 工程资产都需要以事实、边界和验证作为进入共享使用的依据。 +
+ + diff --git a/slidev/pages/day6/m8-final-demo.md b/slidev/pages/day6/m8-final-demo.md new file mode 100644 index 0000000..9661ab5 --- /dev/null +++ b/slidev/pages/day6/m8-final-demo.md @@ -0,0 +1,83 @@ +# 模块 9：AI 编程的工程底线 + +
+ +AI 让研发更快，但不改变软件工程的基本要求。 + +范围、规则、验证、协作和可维护性，决定一段 AI 生成代码能否真正进入项目。 + +
+ +
+
理解范围
+
保护规则
+
验证行为
+
说明结论
+
保持可维护
+
+ + + +--- + +# AI 参与研发时，什么没有改变？ + +
+ +| AI 可以改变 | 工程原则不变 | +|---|---| +| 更快搜索代码和生成候选方案 | 先理解现有系统，再决定改动范围 | +| 更快补齐实现和测试草稿 | 业务规则仍要在正确边界保护 | +| 更快解释日志和定位假设 | 验证证据必须与结论强度匹配 | +| 更快生成说明和文档初稿 | 人工仍对合入与发布结论负责 | + +
+ +
+工具能力会持续演进，工程判断的价值反而更高。 +
+ + + +--- + +# 高质量 AI 编程的共同语言 + +
+
+
事实优先
+
区分已读到、已验证和仍待确认的信息。
+
+
+
最小改动
+
以明确目标约束改动范围，避免无关重写。
+
+
+
验证闭环
+
让测试、日志和人工检查分别支持相应结论。
+
+
+
可追溯说明
+
让后续维护者理解目标、范围、证据和边界。
+
+
+ + diff --git a/slidev/slides.md b/slidev/slides.md index 554e5b7..d3e9dd7 100644 --- a/slidev/slides.md +++ b/slidev/slides.md @@ -162,3 +162,115 @@ src: ./pages/day4/m6-dashboard-metrics.md --- src: ./pages/day4/m7-review-delivery.md --- + +--- +layout: new-section +--- + +# 第 5 天：可沉淀的 AI 工程资产 + +真实案例 · 规则 · 任务上下文契约 · Skill / Agent / MCP + +--- +src: ./pages/day5/m1-project-workshop.md +--- + +--- +src: ./pages/day5/m2-project-knowledge.md +--- + +--- +src: ./pages/day5/m3-task-delegation.md +--- + +--- +src: ./pages/day5/m4-refactor-safety.md +--- + +--- +src: ./pages/day5/m5-testing-safety-net.md +--- + +--- +src: ./pages/day5/m6-asset-skill-writing.md +--- + +--- +src: ./pages/day5/m7-delivery-review.md +--- + +--- +src: ./pages/day5/m8-custom-agent-asset.md +--- + +--- +src: ./pages/day5/m9-agent-boundaries.md +--- + +--- +src: ./pages/day5/m10-agent-skill-composition.md +--- + +--- +src: ./pages/day5/m11-asset-library-delivery.md +--- + +--- +src: ./pages/day5/m12-mcp-asset-governance.md +--- + +--- +src: ./pages/day5/m13-historical-code-governance.md +--- + +--- +layout: new-section +--- + +# 第 6 天：工程协作与质量闭环 + +PR · Git 协作 · CI 诊断 · 证据链 · 资产变更验证 + +--- +src: ./pages/day6/m1-team-flow.md +--- + +--- +src: ./pages/day6/m2-pr-template-ai-record.md +--- + +--- +src: ./pages/day6/m3-ai-code-review.md +--- + +--- +src: ./pages/day6/m4-ci-failure-loop.md +--- + +--- +src: ./pages/day6/m5-asset-governance.md +--- + +--- +src: ./pages/day6/m6-onboarding-rollout.md +--- + +--- +src: ./pages/day6/m7-maintainability-review.md +--- + +--- +src: ./pages/day6/m8-asset-change-validation.md +--- + +--- +src: ./pages/day6/m8-final-demo.md +--- + +--- +src: ./pages/day6/m10-ai-trends.md +--- + +--- +src: ./pages/day6/m11-six-day-retrospective.md +--- diff --git a/第 4 天：JeecgBoot 工单复杂业务开发：权限、审计、异常态与看板.md b/第 4 天：JeecgBoot 工单复杂业务开发：权限、审计、异常态与看板.md index 195db96..d20f454 100644 --- a/第 4 天：JeecgBoot 工单复杂业务开发：权限、审计、异常态与看板.md +++ b/第 4 天：JeecgBoot 工单复杂业务开发：权限、审计、异常态与看板.md @@ -387,6 +387,59 @@ AI 可以帮助我们补漏，比如提醒我们“导出”“查看审计记 --- +## Slide 1-5：可直接复制到 rules：权限安全 + +### PPT 页面内容 + +```Plain Text +权限安全 rules： + +敏感操作必须四层校验 +权限字符必须有来源或标记为建议 +数据权限不得被查询条件替代 + +每条 rule 都要写清： +适用场景、必须、禁止、验收方式 +``` + +### 讲师逐字稿 + +这里把权限矩阵进一步沉淀成 rules。 + +rules 不是写给人看的口号，而是写给 AI 和团队共同执行的约束。 + +权限相关至少要有三条硬规则。 + +第一，敏感操作必须四层校验：菜单、按钮、接口、数据范围都要覆盖。 + +第二，权限字符必须有来源。如果是新建议，要明确标记为建议，不能让 AI 凭空编一个权限字符就当成事实。 + +第三，数据权限不能被前端查询条件替代。后端必须校验当前用户的数据范围。 + +后面权限方案、代码修改和 Review 都要回到这些 rules。 + +### 课堂产出 + +```md +## 敏感操作必须四层校验 +- 级别：硬约束 +- 适用场景：新增、编辑、删除、指派、状态流转、查看审计、查看看板。 +- 必须：同时覆盖页面/菜单权限、按钮权限、后端接口权限、数据范围权限。 +- 禁止：只做页面或按钮控制。 +- 验收方式：授权角色能完成；未授权角色前端不可见且直接请求接口失败；越权数据访问失败。 + +## 权限字符必须有来源或标记为建议 +- 必须：来自现有菜单、权限配置、前端权限指令、后端鉴权注解或团队规范。 +- 禁止：凭空编造权限字符并当成事实。 +- 验收方式：权限字符在前端、菜单配置、后端接口之间一致。 + +## 数据权限不得被查询条件替代 +- 必须：后端统一校验当前用户可访问的数据范围。 +- 禁止：只依赖前端传入 userId、deptId、tenantId 或筛选条件。 +``` + +--- + # 模块 2：权限控制方案生成 --- @@ -661,6 +714,49 @@ RBAC 权限矩阵 --- +## Slide 2-7：rules 要落到这些位置 + +### PPT 页面内容 + +```Plain Text +rule 不是单独文件 + +要落到： +菜单配置 +按钮权限 +Controller +Service 查询 +审计展示 +验收记录 +``` + +### 讲师逐字稿 + +很多团队写了 rules，但代码生成时没有真正用上。 + +第四天要强调：让 TRAE 改权限前，必须同时给它当前项目 rules、权限矩阵、权限控制方案和实际文件路径。 + +比如“四层校验”这条 rule，就要落到菜单配置、按钮权限、Controller、Service 查询和验收记录。 + +“权限字符有来源”这条 rule，要落到菜单表、路由、按钮指令和后端注解。 + +“数据权限不得被查询条件替代”这条 rule，要落到列表、详情、导出和看板查询。 + +这样 rule 才不是口号，而是代码修改和 Review 的检查依据。 + +### 课堂产出 + +```md +| rule 条款 | 代码落点 | 课堂验收 | +|---|---|---| +| 四层校验 | 菜单配置、按钮权限、Controller、Service 查询 | 无权限账号不可见且接口失败 | +| 权限字符有来源 | 菜单表、路由、按钮指令、后端注解 | 同一字符贯穿前后端 | +| 数据权限后端校验 | 列表、详情、导出、看板查询 | 改请求参数不能越权 | +| 敏感字段最小返回 | 列表接口、详情接口、审计展示 | 不暴露不必要 old/new value | +``` + +--- + # 模块 3：工单状态流转规则实现 --- @@ -995,6 +1091,57 @@ POST /workOrder/transition --- +## Slide 3-8：可直接复制到 rules：状态流转 + +### PPT 页面内容 + +```Plain Text +状态流转 rules： + +复杂业务状态必须先建模 +非法状态流转必须拒绝且状态不变 + +验证重点： +合法路径成功 +非法路径失败 +状态不被错误修改 +失败不写成功审计 +``` + +### 讲师逐字稿 + +状态流转表不是一次性课堂表格。 + +它应该沉淀成团队 rules，后续遇到审批、发布、上下架、支付、归档等状态型业务都可以复用。 + +第一条 rule 是复杂业务状态必须先建模。 + +也就是先产出状态流转表，再进入代码实现，不能直接在代码里堆 if else。 + +第二条 rule 是非法状态流转必须拒绝且状态不变。 + +这条非常关键。非法请求失败后，数据库状态不能被改坏，也不能写一条成功审计。 + +这类 rules 会直接进入后续 Review 和测试清单。 + +### 课堂产出 + +```md +## 复杂业务状态必须先建模 +- 级别：硬约束 +- 适用场景：工单指派、处理、验证、驳回、关闭、重开。 +- 必须：先产出状态流转表，列出当前状态、动作、目标状态、允许角色、前置条件、后置动作和验收方式。 +- 禁止：直接在代码中堆状态判断而没有状态表。 +- 验收方式：每个状态动作都有合法路径和非法路径验证。 + +## 非法状态流转必须拒绝且状态不变 +- 必须：集中校验非法流转；失败时返回明确错误，业务状态不变，不写成功审计。 +- 禁止：仅靠前端禁用按钮防止非法流转。 +- 验收方式：构造非法状态动作，接口失败且数据库状态不变。 +``` + +--- + # 模块 4：审计日志设计 --- @@ -1267,6 +1414,57 @@ SOP 要写清： --- +## Slide 4-7：可直接复制到 rules：审计日志 + +### PPT 页面内容 + +```Plain Text +审计日志 rules： + +关键业务操作必须写审计 +审计和业务写入必须一致 + +不能只写： +“记录日志” + +必须说明： +字段、时机、事务、失败行为、验收方式 +``` + +### 讲师逐字稿 + +审计 rules 要比“记录日志”具体得多。 + +关键业务操作必须写审计，适用于创建、编辑关键字段、指派、状态流转、驳回、关闭、删除、导出、权限变更。 + +审计字段要包含操作人、动作、目标对象、修改前、修改后、来源、请求 ID 或项目里的等价字段。 + +第二条 rule 是审计和业务写入必须一致。 + +如果状态更新成功但审计丢了，后续无法追溯。 + +如果审计写成功但业务失败，也会产生错误记录。 + +所以必须说明审计写入时机、事务关系、失败处理和验证方式。 + +### 课堂产出 + +```md +## 关键业务操作必须写审计 +- 级别：硬约束 +- 适用场景：创建、编辑关键字段、指派、状态流转、驳回、关闭、删除、导出、权限变更。 +- 必须：记录 actor、action、target_id、old_value、new_value、source、request_id、created_at 或项目等价字段。 +- 禁止：只记录普通日志而没有业务审计；操作失败后写成功审计。 +- 验收方式：执行关键操作后可查询审计记录，字段与实际变更一致。 + +## 审计和业务写入必须一致 +- 必须：明确审计写入时机、事务关系、失败处理和重试策略。 +- 禁止：业务成功审计丢失，或审计成功但业务失败。 +- 验收方式：模拟业务失败和审计失败，结果符合一致性策略。 +``` + +--- + # 模块 5：异常态与防御性逻辑 --- @@ -1535,6 +1733,59 @@ Service 要保证失败时状态不变。 --- +## Slide 5-7：可直接复制到 rules：异常态测试 + +### PPT 页面内容 + +```Plain Text +测试 rules： + +核心逻辑必须有测试或豁免说明 +权限必须做正反角色验证 +状态流转必须覆盖合法和非法路径 + +禁止： +只用管理员账号验证 +只说“已验证” +只跑正常主链路 +``` + +### 讲师逐字稿 + +异常态模块最后要沉淀成测试 rules。 + +第一，核心逻辑必须有测试或豁免说明。 + +如果没法写自动化测试，也要写清手工验收步骤、证据和剩余风险，不能只说“已验证”。 + +第二，权限必须做正反角色验证。 + +至少一个授权角色、一个未授权角色；如果涉及数据范围，还要验证越权数据。 + +第三，状态流转必须覆盖合法和非法路径。 + +不能只测从创建到关闭的成功链路，也要构造 closed 重新处理、pending_verify 驳回无原因这类失败路径。 + +### 课堂产出 + +```md +## 核心逻辑必须有测试或豁免说明 +- 级别：待确认约束 +- 适用场景：权限校验、状态流转、审计、看板指标、异常态修复。 +- 必须：优先补自动化测试；无法测试时说明原因、风险和手工验收方式。 +- 禁止：只说“已验证”但没有命令、样例、截图、接口响应或手工步骤。 + +## 权限必须做正反角色验证 +- 必须：至少验证一个授权角色和一个未授权角色；涉及数据范围时验证越权数据。 +- 禁止：只用管理员账号验证。 + +## 状态流转必须覆盖合法和非法路径 +- 必须：每个关键动作至少覆盖一条合法路径和一条非法路径。 +- 禁止：只测试从初始状态到成功终态的主链路。 +``` + +--- + # 模块 6：研发效能看板指标开发 --- @@ -1801,6 +2052,52 @@ trend 返回每日新增和每日关闭趋势。 --- +## Slide 6-7：可直接复制到 rules：看板指标 + +### PPT 页面内容 + +```Plain Text +看板指标 rule： + +看板指标必须手工抽样校验 + +必须有： +含义、公式、过滤条件 +时间字段、数据范围、样例数据 + +禁止： +只验证接口 200 +只验证页面有图表 +``` + +### 讲师逐字稿 + +看板最容易出现“页面很漂亮，但数字说不清”的问题。 + +所以看板指标也要写成 rules。 + +每个关键指标必须有含义、公式、过滤条件、时间字段、数据范围，并且用样例数据手工校验。 + +比如平均关闭周期，至少要拿三条样例工单，人工算一次，再和接口返回对上。 + +接口返回 200 不代表指标正确，页面有图表也不代表指标可信。 + +课堂交付时，看板必须同时交付指标字典、接口契约和至少一组手工核对样例。 + +### 课堂产出 + +```md +## 看板指标必须手工抽样校验 +- 级别：硬约束 +- 适用场景：统计卡片、趋势图、分布图、排行、效能指标。 +- 必须：每个关键指标有含义、公式、过滤条件、时间字段、数据范围，并用样例数据手工校验。 +- 禁止：只验证接口返回 200 或页面有图表。 +- 来源证据：指标字典、接口契约、样例数据、数据库查询或列表数据。 +- 验收方式：至少一组样例数据的手工计算结果与接口返回一致。 +``` + +--- + # 模块 7：阶段代码审查与修复 --- @@ -1874,6 +2171,94 @@ AI Review 不能只给 diff。 --- +## Slide 7-2A：第 4 天要用的三个 Skill + +### PPT 页面内容 + +```Plain Text +三个 Skill： + +design-complex-business-module +开工前设计控制面 + +review-business-delivery +阶段 Review 检查风险 + +track-review-fix-loop +修复后闭环并沉淀资产 +``` + +### 讲师逐字稿 + +前三天已经讲过 Skill 的概念。 + +第四天要让大家看到具体怎么用。 + +第一个 Skill 是 `design-complex-business-module`，用在开始写代码前，先设计权限、状态、审计、异常态和看板指标。 + +第二个 Skill 是 `review-business-delivery`，用在阶段 Review 时，检查权限缺口、非法状态流转、审计缺失、异常处理薄弱、看板口径不清和测试缺失。 + +第三个 Skill 是 `track-review-fix-loop`，用在修复 Review 问题后，把问题状态、修改文件、验证证据和资产沉淀记录下来。 + +Skill 负责流程和质量门禁；rule 负责长期约束；template 和 checklist 负责稳定输出。 + +### 课堂产出 + +```md +| Skill | 什么时候用 | 输入材料 | 输出产物 | +|---|---|---|---| +| design-complex-business-module | 开始写代码前 | 需求、项目规则、现有角色/API/表结构 | RBAC、权限方案、状态表、审计 SOP、异常清单、指标字典 | +| review-business-delivery | 阶段 Review 时 | diff、业务产物、测试结果、验收记录 | 问题清单、证据缺口、待确认项 | +| track-review-fix-loop | 修 Review 后 | Review 报告、修改文件、验证证据 | 修复记录、未闭环事项、资产更新建议 | +``` + +--- + +## Slide 7-2B：design-complex-business-module 怎么用 + +### PPT 页面内容 + +```Plain Text +用于开工前： + +先设计控制面 +再进入代码实现 + +输出： +RBAC、权限方案、状态表、非法流转、 +审计 SOP、异常清单、指标字典、接口验收记录 +``` + +### 讲师逐字稿 + +`design-complex-business-module` 的核心原则是：先设计控制面，再设计代码。 + +它不是让 AI 直接写实现，而是先把复杂业务应该有的控制资产产出。 + +课堂里可以把工单需求、项目规则、现有角色、菜单权限、接口、数据表和相似模块作为输入。 + +如果缺少源码或配置证据，输出必须标记为“建议”或“待确认”，不能让 AI 把推断当成事实。 + +### 推荐 Prompt + +```md +请使用 design-complex-business-module，基于 JeecgBoot 工单模块设计复杂业务控制面。 + +输入材料： +1. 需求范围：工单权限、状态流转、审计、异常态、看板。 +2. 项目规则：security-permission、state-audit、testing、delivery。 +3. 现有证据：角色、菜单权限、接口、数据表、相似模块。 + +输出必须包含： +RBAC 权限矩阵、权限控制方案、状态流转表、非法流转清单、 +审计日志 SOP、异常态清单、看板指标字典、看板接口验收记录。 + +要求： +没有源码或配置证据的内容标记为“建议”或“待确认”。 +``` + +--- + ## Slide 7-3：阶段 Review 报告模板 ### PPT 页面内容 @@ -1919,6 +2304,59 @@ Review 输出必须结构化。 --- +## Slide 7-3A：review-business-delivery 怎么用 + +### PPT 页面内容 + +```Plain Text +用于阶段 Review： + +输入不能只有 diff + +必须同时给： +业务产物 +测试结果 +验收记录 +项目 rules + +输出问题优先，按 P0/P1/P2/P3 排序 +``` + +### 讲师逐字稿 + +`review-business-delivery` 的作用是防止 AI Review 只做代码风格点评。 + +第四天 Review 的对象是业务交付，不只是代码 diff。 + +所以输入材料必须包括当天 diff、RBAC 矩阵、权限控制方案、状态流转表、非法流转清单、审计 SOP、异常态清单、看板指标字典和测试结果。 + +输出要问题优先，按 P0/P1/P2/P3 排序。 + +每个问题必须有证据、风险、修复建议和验收方式。 + +如果缺少证据，就列到“证据缺口”，不能让 AI 猜。 + +### 推荐 Prompt + +```md +请使用 review-business-delivery 对第四天工单模块交付做阶段 Review。 + +输入材料： +- 当天 diff 或修改文件清单 +- RBAC 权限矩阵和权限控制方案 +- 状态流转表和非法流转清单 +- 审计日志 SOP 和异常态清单 +- 看板指标字典和接口验收记录 +- 测试命令、接口响应、浏览器验证或手工验收记录 + +输出格式： +先列问题清单，按 P0/P1/P2/P3 排序； +每个问题必须有证据、风险、修复建议和验收方式； +缺少证据时单独列“证据缺口”，不要猜测。 +``` + +--- + ## Slide 7-4：修复闭环 ### PPT 页面内容 @@ -1994,6 +2432,58 @@ Review 问题 --- +## Slide 7-5A：track-review-fix-loop 怎么用 + +### PPT 页面内容 + +```Plain Text +用于 Review 修复后： + +每个问题只能标记为： +成立-已修复 +成立-暂不修复 +不成立 +需确认 +未闭环 + +没有验证证据不能关闭 +``` + +### 讲师逐字稿 + +`track-review-fix-loop` 负责把 Review 问题真正闭环。 + +它要求每个问题不能只写“已修复”。 + +必须判断问题是否成立，列出修改文件或产物，提供验证证据，说明剩余风险，并判断是否要沉淀成资产。 + +如果没有验证证据，就不能标记为完成，只能标记为未闭环。 + +如果问题依赖业务决策，就标记为需确认。 + +如果问题不成立，也要保留原因和证据，不要直接删除。 + +### 推荐 Prompt + +```md +请使用 track-review-fix-loop，把阶段 Review 问题转成修复闭环记录。 + +输入材料： +- 带编号的 Review 报告 +- 修改文件或产物 +- 测试输出、接口响应、浏览器截图或手工验收步骤 +- 现有 rules、checklists、prompts、examples、skills 目录 + +每个问题状态只能是： +成立-已修复 / 成立-暂不修复 / 不成立 / 需确认 / 未闭环 + +输出必须包含： +修复记录、未闭环事项、资产更新建议。 +资产类型从 rule、checklist、prompt、command、skill、example 中选择。 +``` + +--- + ## Slide 7-6：第四天完整实操链路 ### PPT 页面内容 @@ -2128,6 +2618,59 @@ Review 问题 --- +## Slide 8-2A：第 4 天资产包目录 + +### PPT 页面内容 + +```Plain Text +第 4 天资产包： + +rules +skills +templates +checklists +prompts +examples + +交付给团队的不是聊天记录 +而是可复用工程资产包 +``` + +### 讲师逐字稿 + +第四天最后要让学员看到：课堂产物不是聊天记录。 + +真正交付给团队的，是一套可安装、可复用、可审查的工程资产包。 + +rules 是长期约束，比如权限四层校验、状态先建模、审计一致性、看板手工抽样。 + +skills 是可触发流程，比如复杂业务设计、阶段 Review、修复闭环。 + +templates、checklists、prompts 和 examples 是 Skill 运行时会用到的材料。 + +这样团队下次做审批、报销、发布、合同、库存这些复杂业务模块时，就不需要重新从聊天记录里找经验。 + +### 课堂产出 + +```text +ai-dev-assets/ +├── rules/ +│ ├── security-permission.md +│ ├── state-audit.md +│ ├── testing.md +│ └── delivery.md +├── skills/ +│ ├── design-complex-business-module/ +│ ├── review-business-delivery/ +│ └── track-review-fix-loop/ +├── templates/jeecgboot/ +├── checklists/jeecgboot/ +├── prompts/jeecgboot/ +└── examples/jeecgboot/ +``` + +--- + ## Slide 8-3：交付物验收标准 ### PPT 页面内容 diff --git a/项目实操-影响分析提示词与TRAE返回结果.md b/项目实操-影响分析提示词与TRAE返回结果.md new file mode 100644 index 0000000..6758f28 --- /dev/null +++ b/项目实操-影响分析提示词与TRAE返回结果.md @@ -0,0 +1,133 @@ +# 项目实操：公务用车取消派车影响分析与实际验证记录 + +> 案例来自当前 JeecgBoot 项目已接入的“公务用车”模块，不代表客户提出过这一条具体业务需求。培训中设置的改造要求是：**取消已派车任务时，取消原因必须由后端校验为非空；前端必填不能替代后端业务保护。** + +## 可直接发送给 TRAE 的提示词 + +```text +请基于当前打开的 JeecgBoot 项目，且只基于你实际读取到的源码，完成一次变更影响分析；不要修改代码，不要猜测项目外逻辑。 + +训练改造目标：取消已派车任务时，取消原因必须为非空文本。前端表单已设为必填，但后端也必须拒绝空值和全空白值，避免直接调用接口绕过页面校验。 + +已知入口： +- 前端列表：jeecgboot-vue3/src/views/official/vehicle/dispatch/DispatchList.vue +- 前端弹窗与表单：jeecgboot-vue3/src/views/official/vehicle/dispatch/DispatchModal.vue、dispatch.data.ts +- 前端 API：jeecgboot-vue3/src/api/official/vehicle/dispatch.ts +- 后端接口：POST /official/vehicle/dispatch/cancel +- 后端 Controller：OfficialVehicleDispatchController.java +- 后端 Service：OfficialVehicleDispatchServiceImpl.java + +请再读取取消参数 VO、派车实体、现有测试、模块 pom 和必要的数据库初始化 SQL，并按以下结构输出： +1. 已读取的源码。 +2. 已确认事实，每条附文件和行号依据。 +3. 必须检查的文件或模块，以及为什么。 +4. 可能受影响的接口、数据、权限、状态、配置和测试。 +5. 本次明确不应修改的内容。 +6. 不超过 4 步的最小改动计划：修改目标、完成证据、验证方式、回退条件。 +7. 人工待确认事项。 + +要求： +- 事实与推测分开；无源码证据的内容标记为“待确认”。 +- 不要编造测试结果、全局异常语义、权限链路或项目外调用方。 +- 不要直接实施修改。 +``` + +## 本次实际核对记录 + +以下结论来自本地实际读取的源码、训练分支 diff 和实际 Maven 命令结果。没有执行过的数据库、接口和浏览器验证均明确标记为未执行。 + +### 已读取的源码 + +- `jeecgboot-vue3/src/views/official/vehicle/dispatch/DispatchList.vue` +- `jeecgboot-vue3/src/views/official/vehicle/dispatch/DispatchModal.vue` +- `jeecgboot-vue3/src/views/official/vehicle/dispatch/dispatch.data.ts` +- `jeecgboot-vue3/src/api/official/vehicle/dispatch.ts` +- `jeecg-boot/jeecg-boot-module/jeecg-module-officialvehicle/src/main/java/org/jeecg/modules/officialvehicle/controller/OfficialVehicleDispatchController.java` +- `jeecg-boot/jeecg-boot-module/jeecg-module-officialvehicle/src/main/java/org/jeecg/modules/officialvehicle/service/impl/OfficialVehicleDispatchServiceImpl.java` +- `jeecg-boot/jeecg-boot-module/jeecg-module-officialvehicle/src/main/java/org/jeecg/modules/officialvehicle/vo/OfficialVehicleCancelDispatchVo.java` +- `jeecg-boot/jeecg-boot-module/jeecg-module-officialvehicle/src/main/java/org/jeecg/modules/officialvehicle/entity/OfficialVehicleDispatch.java` +- `jeecg-boot/jeecg-boot-module/jeecg-module-officialvehicle/src/test/java/org/jeecg/modules/officialvehicle/controller/OfficialVehicleDispatchControllerTest.java` +- `jeecg-boot/jeecg-boot-module/jeecg-module-officialvehicle/pom.xml` +- `jeecg-boot/jeecg-boot-module/pom.xml` +- `jeecg-boot/db/officialvehicle/official_vehicle_mvp_mysql.sql` + +### 已确认事实 + +1. 公务用车为项目现有模块，而非 `demo` 示例：聚合模块 `jeecg-boot-module/pom.xml` 包含 `jeecg-module-officialvehicle`，数据库脚本同时提供菜单、权限和演示数据。 + - 依据：`jeecg-boot/jeecg-boot-module/pom.xml` 第 18 行；`db/officialvehicle/official_vehicle_mvp_mysql.sql` 第 134 至 218 行。 + +2. 前端仅当用户具有 `vehicle:dispatch:cancel` 权限、且派车状态为 `DISPATCHED` 时显示“取消派车”操作。 + - 依据：`DispatchList.vue` 第 26 至 30 行。 + +3. 取消弹窗的 `cancelReason` 已配置 `required: true`，提交时会调用前端 API 的 `cancelDispatch`。 + - 依据：`dispatch.data.ts` 第 72 至 75 行；`DispatchModal.vue` 第 28 至 36 行。 + +4. 前端 API 只是向 `POST /official/vehicle/dispatch/cancel` 提交 `dispatchId` 和 `cancelReason`，因此直接调用接口不经过页面必填校验。 + - 依据：`src/api/official/vehicle/dispatch.ts` 第 4 至 12 行。 + +5. 后端 Controller 有 `@AutoLog` 和 `@RequiresPermissions("vehicle:dispatch:cancel")`，但只将 VO 中两个字段转交给 Service，没有参数校验注解。 + - 依据：`OfficialVehicleDispatchController.java` 第 55 至 61 行；`OfficialVehicleCancelDispatchVo.java` 第 14 至 20 行。 + +6. 原有 Service 会校验派车任务存在且状态为 `DISPATCHED`，随后把状态改为 `CANCELLED`、写入 `cancelReason`，并把关联车辆状态改为 `AVAILABLE`；原实现没有非空或空白校验。 + - 依据：改造前 `OfficialVehicleDispatchServiceImpl.java` 第 84 至 96 行。 + +7. `cancel_reason` 在 `official_vehicle_dispatch` 表中允许为空，因此仅靠当前表结构不能保证取消原因留痕。 + - 依据：`official_vehicle_mvp_mysql.sql` 第 82 至 105 行。 + +8. 模块已有 JUnit 基座和 Controller 测试；原有取消测试只验证带“计划变更”原因时 Controller 转交 Service，未覆盖空白原因。 + - 依据：模块 `pom.xml` 的 Surefire 配置；`OfficialVehicleDispatchControllerTest.java` 第 48 至 59 行。 + +### 最小改动及实际完成证据 + +| 步骤 | 实际改动 | 完成证据 | 验证状态 | 回退条件 | +|---|---|---|---|---| +| 1 | 在 Service 的 `cancel` 首行加入 `Assert.hasText(cancelReason, "取消原因不能为空")` | 空值或全空白值在读取派车单、改变状态、释放车辆前被拒绝 | 已执行单元测试 | 若业务确认允许无原因取消，撤回该校验并重新定义留痕方式 | +| 2 | 新增 `OfficialVehicleDispatchServiceImplTest`，传入全空白原因并断言抛出 `IllegalArgumentException` | 测试直接调用 Service，不依赖前端表单 | 已执行 | 若异常约定需要调整，更新断言及统一异常验证 | +| 3 | 保持前端必填、Controller 权限/审计、派车状态流转和数据库表结构不变 | `main...training/require-cancel-reason` 仅含上述两个后端文件 | 已核对 diff | 若接口回归显示兼容问题，只回退提交 `d357de7` | + +### 本次明确不应修改 + +- `official_vehicle_dispatch` 的字段、索引和初始化 SQL。 +- 派车、取消派车后的车辆可用状态处理、申请状态流转和行程模块。 +- 已存在的 `vehicle:dispatch:cancel` 权限和 `@AutoLog` 审计注解。 +- 前端弹窗、路由、菜单和无关页面。前端已经有必填规则，本次不重复实现。 +- 未读取到源码依据的全局异常、数据权限、网关、审批或外部调用方逻辑。 + +### 可能受影响的内容 + +| 维度 | 结论 | 当前状态 | +|---|---|---| +| 接口 | 空值、`""` 或全空白 `cancelReason` 将不再被正常取消流程接受 | 已通过 Service 单测验证 | +| 数据 | 被拒绝的请求不会进入派车状态和车辆状态更新；表字段仍允许空值 | 代码顺序与单测已验证；数据库级验证未执行 | +| 权限与审计 | 原有权限和 `@AutoLog` 保持不变 | 已读取源码，未做运行环境验证 | +| 正常取消 | 非空原因仍应按原有流程取消并释放车辆 | 未做数据库/API 回归 | +| 统一响应 | `Assert` 的异常如何映射 HTTP/`Result` 取决于项目全局异常处理 | 待确认 | + +### 实际验证结果 + +训练分支：`training/require-cancel-reason` +提交：`d357de7 fix: require reason when cancelling dispatch` + +执行命令： + +```bash +mvn -pl jeecg-boot-module/jeecg-module-officialvehicle -am \ + -DskipTests=false \ + -Dtest=OfficialVehicleDispatchServiceImplTest \ + -Dsurefire.failIfNoSpecifiedTests=false test +``` + +实际结果：2026-08-06 再次执行完成，`BUILD SUCCESS`；`OfficialVehicleDispatchServiceImplTest` 共 1 项，`Failures: 0`、`Errors: 0`、`Skipped: 0`。 + +未执行且不能写成已通过： + +- 已派车数据提交非空取消原因后的数据库状态、车辆状态和审计记录。 +- 直接调用取消接口时空值/全空白值的 HTTP/`Result` 响应。 +- 浏览器中取消弹窗的必填提示和成功取消路径。 + +### 人工待确认事项 + +1. 取消原因是否仅要求非空，还是需要最小长度、枚举原因或特殊角色豁免。 +2. `Assert.hasText` 抛出的异常在当前服务中的错误码、HTTP 状态和前端提示是否符合统一约定。 +3. 正常取消后派车状态、车辆状态和审计记录的集成环境回归结果。 +4. 是否存在项目外系统直接调用取消接口，以及它们对空原因的历史依赖。