@brightliu/ai-control 2.1.0

package/payload/rules/53-release.md

@@ -0,0 +1,141 @@
+# 发布规则
+
+## 发布前必须确认
+- 需求和规格已确认。
+- 数据库变更有 forward SQL 和必要 rollback SQL。
+- 高风险 SQL 已获确认。
+- 关键路径已验证。
+- API 和前端兼容性已审查。
+- 安全和权限风险已审查。
+- 监控、日志或审计要求已满足。
+- 回滚方案明确。
+
+## 发布报告
+必须包含：
+- 变更摘要
+- 影响范围
+- 数据库变更
+- API 变化
+- 前端变化
+- 验证结果
+- 回滚方案
+- 已知风险
+
+## 发布必查清单（只过与本次变更相关的项）
+
+- 是否猜测业务规则、字段、状态流、权限或响应格式。
+- 表结构变化是否有 migration SQL、rollback SQL 和历史数据兼容策略。
+- 高风险 SQL 是否已获得用户确认。
+- Entity/DTO/VO 与数据库表结构是否一致。
+- 多表写入、状态变更、扣减、日志记录是否有事务边界。
+- SQL 是否存在 `SELECT *`、租户隔离缺失、软删除缺失或危险 UPDATE/DELETE。
+- 是否存在魔法值判断（裸数字/裸字符串比较状态）、硬拼的状态文案、未经 `fromCode()` 校验的枚举入参或 `ordinal()` 入库（见 `.ai/rules/44-java-enum.md`）。
+- API 响应格式、路径、分页结构是否破坏兼容性。
+- 前端是否缺失加载态、空态、错误态、权限态或重复提交防护。
+- 是否暴露敏感字段、异常堆栈、token、密码或隐私数据。
+- 是否引入未经批准的依赖、架构变化或无关重构。
+- 每一行变更是否能追溯到用户需求、OpenSpec change、已确认规格或明确验证失败。
+- 自动化用例是否有 JUnit 报告证据（运行 `ai ship <change-id>` 验证：报告存在、无失败、TC-ID 覆盖）；手动用例的执行结果是否已逐条写入交付说明；失败是否已修复或明确记录残余风险。
+- 是否存在顺手优化、顺手改格式、顺手改注释、无关风格统一或无关历史代码清理。
+- 本次改动造成的 unused import、未使用变量、未使用组件引用、未使用私有方法、临时日志、调试代码和注释代码是否已清理。
+- 是否误删或计划删除改动前已存在的疑似 dead code；如有，是否完成静态引用、配置引用、框架引用、契约引用、测试引用和发布影响检查。
+- 是否存在过度封装：没有真实差异的接口、策略、模板方法、工厂类、空壳层、无调用方扩展点，或把简单流程拆成大量一行私有方法。
+- 删除 Controller、API 入口、路由页面、菜单入口、Entity、DTO、VO、Mapper、XML、枚举、状态类、权限码、错误码、序列化字段或动态组件时，是否有兼容性和运行时引用验证。
+
+## 安全检查（涉及权限/敏感数据时）
+
+### 工作流程
+
+1. 识别认证和权限边界。
+2. 新增或修改后台功能时，必须确认访问控制模式：本服务 RBAC、外部权限服务、网关/IAM/SSO 或明确不适用。
+3. 检查无权限、未登录、越权访问和数据范围隔离。
+4. 检查敏感字段、日志、异常和导出。
+5. 检查 SQL 注入、XSS、文件上传和密钥。
+6. 输出阻塞风险和修复建议。
+
+## 性能检查（涉及查询/列表/批量时）
+
+### 工作流程
+
+1. 明确数据规模和访问频率。
+2. 检查 SQL、索引、分页和 N+1。
+3. 检查缓存、批量操作和事务范围。
+4. 检查前端重复请求、大列表和渲染成本。
+5. 检查 API 响应体大小、分页策略、缓存头和重复请求。
+6. 输出优化建议和验证方式。
+
+## 代码审查要点
+
+## 审查优先级
+1. 业务正确性
+2. 数据安全
+3. 安全性
+4. 权限和租户
+5. 事务安全
+6. API 和前端兼容
+7. 测试和验证
+8. 性能
+9. 可维护性
+10. 代码风格
+
+### 严重级别
+
+### P0 阻塞
+必须阻止合入或发布的问题。包括数据破坏、越权、租户隔离缺失、未确认业务规则、编译失败、测试关键路径失败、破坏 API 兼容、危险 SQL、明文密钥泄露、未经确认的 DROP/TRUNCATE/全表 UPDATE/DELETE。
+
+### P1 重要
+应在本次合入前修复，除非有明确豁免和补救计划。包括事务边界缺失、错误态缺失、N+1 风险、索引缺失、分页不可控、重复提交风险、审计日志缺失、关键测试缺口、文档与实现不一致、职责边界混乱、核心命名不清、明显重复实现或错误抽象。
+
+### P2 次要
+不阻塞发布但应记录的问题。包括命名不清、重复代码、局部可读性问题、非关键文案不一致、低风险边界测试缺失、可维护性改进建议。
+
+### 审查方法
+- 先看 OpenSpec change/spec，再看 diff，最后看调用方和验证证据。
+- 问题必须可定位到文件和最小范围。
+- 每个问题说明影响、触发条件和修复方向。
+- 不把个人偏好写成阻塞问题。
+- 证据不足时列为待确认问题，不猜测。
+- 发现无关修改时要求拆分或说明原因。
+- 审查封装和复用时，必须判断是否服务真实业务边界，不能只按个人风格偏好要求重构。
+- 审查命名时，必须看调用上下文是否能表达业务含义；核心流程命名含糊应要求修复。
+
+### 工程质量审查
+- 职责边界：Controller、Service、Mapper/XML、DTO、VO、Entity、前端组件、API 层和状态管理是否各守边界。
+- 命名质量：类、方法、变量、组件、接口方法、枚举和状态名是否表达业务语义。
+- 封装质量：公共方法、组件、composable/hook、工具函数是否有清晰输入输出、真实复用点和低耦合边界。
+- 复用质量：是否存在明显复制粘贴；提取复用后是否仍保留业务语义。
+- 抽象风险：是否出现万能方法、万能组件、过度配置、隐藏副作用或为了高级而高级的抽象。
+- 可读性：复杂条件、状态流转、权限判断、对象转换和错误处理是否易于审查。
+- 一致性：是否复用既有响应、分页、异常、权限、租户、request、store、组件和设计系统约定。
+- 可测试性：核心业务逻辑是否能被单测、集成测试或清晰手动路径验证。
+
+### 阻塞问题
+出现以下情况必须拒绝变更：
+- 代码无法编译。
+- 业务规则是猜测出来的。
+- 状态流转错误。
+- 权限或租户隔离缺失。
+- 多表写入缺少事务。
+- SQL 可能破坏数据。
+- 表结构变化缺少 migration SQL。
+- API 响应结构破坏兼容性。
+- 前端缺失关键状态处理。
+- 暴露敏感数据。
+- 引入未经批准的依赖。
+- 修改无关文件。
+- 验证步骤缺失且变更影响生产行为。
+- OpenSpec 与实现冲突。
+- 核心流程职责严重混乱，导致权限、事务、状态流转或数据一致性难以审查。
+
+### 输出格式
+1. 阻塞问题
+2. 重要问题
+3. 次要建议
+4. 表结构/字段变化审查
+5. Entity/Mapper/XML/DTO/VO 与表结构一致性审查
+6. API/前端契约审查
+7. SQL 性能风险审查
+8. 安全和权限审查
+9. 封装、复用、命名和可维护性审查
+10. 验证步骤
+11. 风险总结

package/payload/rules/README.md

@@ -0,0 +1,12 @@
+# 规则库索引
+
+单层编号，AI 按需读取；开工提示会注入本次必读清单。
+
+- 00 角色骨架 / 01 代码变更（精准修改·精简·清理）/ 02 产品·业务·体验
+- 10 数据库（表结构/SQL/JOIN/两阶段确认）
+- 20 API / 21 JWT / 22 RBAC / 24 OpenAPI
+- 30 前端 / 31 Vue3 / 32 React
+- 40 后端 / 41 Spring Boot / 42 Go-Gin / 43 PHP / 44 Java 枚举
+- 50 测试 / 51 安全 / 52 性能 / 53 发布清单（含必查项/安全/性能/代码审查）
+
+约定：规则只在本目录维护；手册引用不复述正文。

package/payload/templates/design.md

@@ -0,0 +1,15 @@
+# 设计说明：{{CHANGE_ID}}
+
+> 仅在跨模块、数据库、接口兼容或状态流转变更时创建本文件。
+
+## 方案与取舍
+（补全：为什么这么设计、放弃了什么替代方案）
+
+## 数据库设计
+（涉及时补全；两阶段确认清单见 rules/10-db-schema.md）
+
+## 接口设计
+（涉及时补全；遵循 rules/20-api.md）
+
+## 待确认问题
+- （没有则写：无待确认）

package/payload/templates/proposal-lite.md

@@ -0,0 +1,21 @@
+# 变更提案：{{CHANGE_ID}}
+
+变更级别: lite
+
+## 需求说明
+（补全：一两句话说清楚要改什么、为什么）
+
+## 影响范围
+```yaml
+affected_files:
+  - （补全：影响的文件）
+affected_tables:
+  - none
+affected_apis:
+  - none
+affected_pages:
+  - none
+```
+
+## 待确认问题
+- （没有则写：无待确认）

package/payload/templates/proposal.md

@@ -0,0 +1,28 @@
+# 变更提案：{{CHANGE_ID}}
+
+## 项目背景
+（补全：为什么要做这个功能）
+
+## 功能范围
+- （补全：本次要做什么）
+
+## 影响范围
+```yaml
+affected_files:
+  - none
+affected_tables:
+  - none
+affected_apis:
+  - none
+affected_pages:
+  - none
+```
+
+## 非目标
+- （补全：本次明确不做什么）
+
+## 待确认问题
+- 访问控制：本功能的权限要求是什么？
+- 数据表：涉及哪些表/字段/索引？（涉及则必须走数据库两阶段确认）
+- API 契约：路径、请求、响应、分页、错误码？（遵循 rules/20-api.md）
+- 验收标准：最小可验证路径、失败路径、越权场景分别是什么？

package/payload/templates/review-prompt.md

@@ -0,0 +1,20 @@
+# 独立审查提示词
+
+> 用法：对高风险变更想要第二意见时，在**新会话/新 subagent** 中带上本模板 + git diff，让 AI 做独立审查。
+> 独立性要点：审查者不能是写代码的那个会话。
+
+你是独立审查员。只基于给定材料输出审查发现，不要重写代码。
+
+审查目标：业务逻辑正确性、数据安全、SQL 风险、事务边界、API 兼容性、测试缺口。
+
+按影响范围定向检查：
+- 涉及数据库：migration/rollback 是否齐全？锁表与迁移窗口？无 WHERE 写操作？无 ON 条件 JOIN？租户/软删除条件缺失？多表写入事务边界？
+- 涉及接口：路径/请求/响应/分页/错误码是否破坏兼容？异常路径是否明确且不落 500？权限与数据可见性缺口？魔法值判断、硬拼状态文案、未校验的枚举 code 透传、ordinal() 入库？
+- 涉及页面：加载/空/错误/权限态与重复提交防护是否完整？字段映射与契约一致？长整型 ID 按字符串？
+
+输出格式：
+1. 阻塞问题
+2. 重要风险
+3. 需要用户确认的问题
+4. 建议补充的测试
+5. 最后单独一行机读结论：VERDICT: PASS | PASS_WITH_RISKS | BLOCK

package/payload/templates/spec.md

@@ -0,0 +1,13 @@
+# {{CHANGE_ID}} 规格
+
+## 场景
+（补全：用户在什么情况下做什么、系统给出什么可观察结果；每个场景一小节）
+
+#### 场景：（场景名）
+- （给定…时…则…）
+
+## 值域
+（补全：涉及的字段、枚举值、状态和约束；来源必须是已确认事实，禁止发明）
+
+## 待确认问题
+- （没有则写：无待确认）

package/payload/templates/test-cases.md

@@ -0,0 +1,18 @@
+# 测试用例
+
+> 设计期随 change 一起确认；验收以 JUnit 报告为证据（测试名含 TC-ID），手动用例结果写入交付说明。
+
+## 用例清单
+
+| 用例ID | 关联场景 | 类型 | 前置条件 | 步骤 | 预期结果 | 验证方式 |
+|--------|----------|------|----------|------|----------|----------|
+| TC-01 | （补全） | 正常流 | （补全） | （补全） | （补全） | 单测 |
+
+- 类型：正常流 / 异常流 / 权限 / 边界 / 兼容性 / 并发
+- 验证方式：单测 / 集成 / E2E / 手动
+
+## 覆盖要求
+
+- 涉及 API 必须有异常流用例（参数错误、数据不存在、状态不允许）。
+- 涉及页面必须有权限态与空态/错误态用例。
+- 涉及写操作必须有重复提交或并发用例。