@brightliu/ai-control 2.1.0

package/payload/rules/24-openapi.md

@@ -0,0 +1,14 @@
+# OpenAPI 功能规则
+
+## 适用范围
+
+适用于 Swagger UI、OpenAPI 文档、接口契约同步和前后端联调。
+
+## 规则
+
+- OpenAPI 文档必须跟实际 Controller、DTO、VO 保持一致。
+- 接口说明、字段说明、错误码说明必须使用中文。
+- API Path、HTTP Method、JSON 字段和枚举值可以保留英文。
+- 不允许在文档中暴露敏感字段、内部主键 `pk_id`、密钥或测试账号密码。
+- 目标项目没有启用 OpenAPI 时，不得为了单个需求强行引入，除非用户确认。
+

package/payload/rules/30-frontend.md

@@ -0,0 +1,58 @@
+# 前端规则
+
+## 实现原则
+- 优先遵循既有框架、目录、组件和状态管理方式。
+- 不新增依赖，除非用户明确批准。
+- 页面逻辑、接口调用、状态管理和视图组件应保持清晰边界。
+- 请求和响应必须遵循 API 契约。
+- 不直接信任前端校验，后端仍需校验。
+
+## 代码质量和封装
+- 组件、变量、函数、composable、store、API 方法命名必须表达业务含义，禁止无上下文的 `data`、`list`、`info`、`handleClick`、`submit`、`temp`。
+- 页面组件负责流程编排和视图组合；可复用 UI、业务表单、查询条件、表格列配置、接口调用和状态逻辑应按既有目录拆分。
+- 接口请求必须集中在 API 层或既有 request 封装中，禁止在组件里散落拼接 URL、重复处理 token、错误码或分页结构。
+- 表单模型、查询模型、接口 DTO、展示 VO 必须边界清晰；不要直接把后端原始对象到处透传。
+- 重复交互逻辑应提取为组件、composable/hook、store action 或局部工具函数，但必须有真实复用点和清晰输入输出。
+- 复杂条件、权限判断、按钮可见性、状态文案和颜色映射应集中定义或提取为有语义的方法，禁止在模板中堆叠复杂表达式。
+- 状态管理只存跨组件、跨页面或需要缓存的状态；局部表单和弹窗状态优先留在组件内。
+- 组件 props、emits、slots 必须命名清晰，避免通过隐式全局变量或深层对象突变传递状态。
+- 列表页、详情页、表单页和弹窗必须有稳定的数据流：初始化、加载、成功、失败、重置、销毁边界清楚。
+- 前端长整型 ID 必须按字符串处理，禁止转 Number；展示、提交和路由参数保持一致。
+
+## 必须覆盖
+- 加载态
+- 空态
+- 错误态
+- 成功反馈
+- 权限不足
+- 表单校验
+- 分页和筛选
+- 重复提交防护
+
+## 表单校验
+- 提交表单必须实现前端校验，并与后端验证层和 API 契约保持一致。
+- 后端 DTO、Request、Form、Validator 或注解中必填的字段，前端也必须必填并阻止提交。
+- 输入长度必须参考数据库字段长度、后端验证注解和 API 契约；前端最大长度不得大于后端或数据库允许长度。
+- 必须覆盖最大长度、最小长度、必填、格式、枚举、数值范围、数组数量和高风险字段确认等规则。
+- 如果数据库字段、后端验证层和 API 契约约束不一致，必须停止并询问，不得自行猜测。
+- 前端校验只做提前反馈，不能替代后端校验；后端仍必须完整校验。
+- 校验提示必须使用简体中文，说明错误原因和修正方式。
+- 新增或修改表单时，交付说明必须列出每个提交字段的校验来源。
+
+## 验证
+前端变更应尽量运行：
+- 类型检查
+- lint
+- 单元测试
+- 组件测试
+- e2e 或手动关键路径验证
+- 多视口截图检查，如涉及视觉
+
+## 禁止事项
+- 禁止在页面组件中堆叠大段业务逻辑、接口细节和数据转换。
+- 禁止复制粘贴相似表单、表格、弹窗逻辑而不评估复用。
+- 禁止为了抽象制造难以理解的万能组件或配置黑盒。
+- 禁止直接修改 API 返回对象导致状态来源不清。
+- 禁止把权限、状态映射、枚举文案散落在多个页面中。
+- 禁止提交表单只做 UI 必填标记但没有实际校验规则。
+- 禁止前端表单长度、必填、枚举或格式校验与后端验证层不一致。

package/payload/rules/31-vue3.md

@@ -0,0 +1,20 @@
+# Vue3 技术栈规则
+
+## 适用范围
+
+适用于 Vue3、Vite、TypeScript、Element Plus 或其他管理端组件库项目。
+
+## 接入原则
+
+- 优先遵循目标项目已有目录、路由、状态管理、请求封装、权限指令和组件库。
+- 禁止为单个页面引入新 UI 框架。
+- API 字段、枚举、权限和状态必须来自 OpenSpec 或后端契约。
+- 后端长整型 ID 在前端一律按字符串处理，禁止转 `Number`。
+
+## 页面实现要求
+
+- 列表必须有加载态、空态、错误态和权限态。
+- 表单必须有前端校验、后端错误展示和重复提交防护。
+- 审核、删除、禁用等高风险操作必须有确认。
+- 新增路由、菜单、按钮时必须确认访问控制模式、责任系统和权限点；如果本服务不建设 RBAC，按外部权限系统约定处理。
+- 构建、类型检查、lint 或最小手动验证必须至少执行一种。

package/payload/rules/32-react.md

@@ -0,0 +1,20 @@
+# React 技术栈规则
+
+## 适用范围
+
+适用于 React、Vite/Next.js、TypeScript、Ant Design 或其他管理端组件库项目。
+
+## 接入原则
+
+- 优先遵循目标项目已有目录、路由、状态管理、请求封装、权限组件和组件库。
+- 禁止为单个页面引入新 UI 框架。
+- API 字段、枚举、权限和状态必须来自 OpenSpec 或后端契约。
+- 后端长整型 ID 在前端一律按字符串处理，禁止转 `Number`。
+
+## 页面实现要求
+
+- 组件拆分以真实复用和复杂度为准，禁止空壳抽象。
+- 表格、筛选、分页、详情、弹窗和抽屉必须符合现有交互。
+- 必须处理加载态、空态、错误态、权限态和提交中状态。
+- 新增路由、菜单、按钮时必须确认访问控制模式、责任系统和权限点；如果本服务不建设 RBAC，按外部权限系统约定处理。
+- 构建、类型检查、lint 或最小手动验证必须至少执行一种。

package/payload/rules/40-backend.md

@@ -0,0 +1,63 @@
+# 后端规则
+
+## 分层原则
+- Controller 只负责接收请求、基础校验、调用 Service、返回统一响应。
+- Service/ServiceImpl 负责业务校验、权限、状态流、事务、缓存协调和通知触发。
+- Mapper 只定义持久化方法。
+- XML 写显式 SQL。
+
+## 禁止调用流
+```text
+Controller -> Mapper
+Mapper -> Service
+Controller -> Controller
+Entity -> Service
+```
+
+## 必须考虑
+- 事务边界
+- 权限校验
+- 租户隔离
+- 软删除
+- 幂等性
+- 重复提交
+- 审计日志
+- 异常处理
+- 数据兼容
+- 对外 ID 字符串和前端长整型精度
+
+## 生产级手写要求
+- 编码前必须先读同模块或相邻模块的 Controller、Service、Mapper/XML、DTO、VO、Entity 和测试。
+- 不清楚字段、状态、权限、租户、删除、响应格式或错误码时停止询问。
+- 复用既有项目抽象，禁止新造一套响应、分页、异常、权限或租户模型。
+- 新增公共方法或抽象前，必须确认至少两个真实调用点或明确变化隔离价值。
+- 对外 API 的请求/响应对象必须稳定，避免直接暴露数据库结构。
+- Create/Update 请求 DTO 必须声明必填、长度、格式、枚举、数值范围和数组数量等验证规则，并与数据库字段长度、OpenSpec/API 契约和前端表单校验保持一致。
+- 数据库可以保留 `pk_id`，但对外 API 必须使用 `id`，前端按字符串处理。
+- 后端内部把 API 字符串 `id` 校验后再转换为 `Long`，非法 ID 返回参数错误。
+- 查不到数据时返回业务不存在，不允许抛成 500。
+- 删除、状态变更、扣减、发布、回滚等高风险动作必须有幂等、审计和确认策略。
+- 实现必须有验证证据；无法自动测试时说明手动验证路径和残余风险。
+
+## 代码质量和封装
+- 类、方法和变量命名必须表达业务含义，禁止 `handle`、`process`、`doSomething`、`data`、`item`、`temp` 等无上下文命名。
+- 方法职责必须单一；复杂业务流程应拆为可命名的私有方法或领域步骤，禁止一个方法混合参数校验、权限、查询、状态流转、组装和副作用。
+- 公共抽象只承载稳定规则；不要为了“看起来高级”提前抽象，也不要把不同业务强行塞进一个通用方法。
+- 重复代码优先提取到本模块内的私有方法、领域服务或既有工具；跨模块复用前必须确认边界稳定。
+- DTO、VO、Command、Query、Entity 不能混用；入参、出参、持久化对象和内部业务对象必须边界清晰。
+- 状态、类型、来源、动作等业务枚举必须使用明确命名和集中定义，禁止魔法字符串、魔法数字散落在业务代码中。
+- 分支逻辑必须体现业务规则；复杂条件应提取为有业务语义的方法，禁止堆叠难以审查的长 boolean 表达式。
+- 异常信息、日志和审计字段必须能帮助定位业务动作，不输出敏感信息，不吞掉根因。
+- 查询组装、对象转换和响应组装应有清晰位置，避免 Controller、Service、Mapper/XML 互相污染职责。
+- 高复用代码必须有低耦合接口和明确输入输出，禁止依赖隐式全局状态或隐藏副作用。
+
+## 禁止事项
+- 禁止 Controller 写业务逻辑。
+- 禁止 Service 拼接 SQL 字符串。
+- 禁止静默吞异常。
+- 禁止伪实现。
+- 禁止无关重构。
+- 禁止低质量模板拼接式 CRUD。
+- 禁止空方法、只有 TODO 的方法或没有业务含义的“高级抽象”。
+- 禁止为复用牺牲业务语义，把不同规则合并成难以审查的万能方法。
+- 禁止把命名、分层和封装问题留给后续重构，除非用户明确批准分阶段处理并记录风险。

package/payload/rules/41-spring-boot.md

@@ -0,0 +1,184 @@
+# Spring Boot 规则
+
+## 技术栈基线
+- Java 17+
+- Spring Boot 3/4，目标项目如已确定版本，必须跟随目标项目。
+- Web MVC 接口默认使用 `spring-boot-starter-web`。
+- DTO 参数校验必须使用 `spring-boot-starter-validation`。
+- CRUD 脚手架生成物依赖 MyBatis、MyBatis-Plus、MyBatis XML、PageHelper、Lombok 和 MySQL 8。
+- JWT 退出吊销黑名单依赖 Redis。
+- 本服务建设 RBAC 或审计切面时才需要 `spring-boot-starter-aspectj`；如果访问控制由外部系统负责，不得为了 RBAC 无脑引入。
+- OpenAPI/Swagger UI 使用 `springdoc-openapi-starter-webmvc-ui`。
+- 数据库迁移使用 Flyway。
+
+## Maven 依赖分级
+
+Spring Boot 项目不得无脑补齐所有依赖。必须先判断本次功能是否需要，再在实施计划中列出“新增依赖原因”和“目标项目是否已有等价能力”。
+
+### 必须依赖
+
+只有当目标项目确认为 Spring Boot Web 后端时，才要求具备以下基础能力。
+
+| 依赖 | 用途 |
+|------|------|
+| `spring-boot-starter-web` | Web MVC 接口开发，优先按目标项目既有约定对齐 |
+| `spring-boot-starter-validation` | DTO 参数校验，如 `@NotBlank`、`@Size` |
+| `mybatis-spring-boot-starter` `3.0.4` | MyBatis Mapper/XML |
+| `mysql-connector-j` | MySQL 8 驱动 |
+| `lombok` | `@Data`、`@Slf4j` 等注解 |
+| `pagehelper-spring-boot-starter` `2.1.1` | 分页 |
+
+### 功能依赖
+
+只有本次功能明确需要时才补充，禁止为了未来可能用到而提前引入。
+
+| 依赖 | 触发场景 |
+|------|----------|
+| `spring-boot-starter-data-redis` | JWT 退出吊销黑名单、缓存、分布式锁或会话能力 |
+| `spring-boot-starter-aspectj` | 本服务建设 RBAC 权限 AOP、审计切面或日志切面 |
+| `springdoc-openapi-starter-webmvc-ui` `2.8.13` | OpenAPI/Swagger UI |
+| `hutool-all` `5.8.38` | 通用工具类 |
+| `flyway-core` | 数据库迁移 |
+| `flyway-mysql` | Flyway MySQL 支持 |
+
+### 脚手架依赖
+
+只有使用本仓库通用 CRUD 脚手架生成物，且目标项目没有等价基础设施时才补充。
+
+| 依赖 | 触发场景 |
+|------|----------|
+| `mybatis-plus-boot-starter` `3.5.5` | 适配 CRUD 脚手架生成物中的 `BaseMapper`、`ServiceImpl` 和 `@TableName` |
+
+### 本地开发依赖
+
+以下依赖只用于本地开发或测试，不应成为生产能力的隐式前提。
+
+| 依赖 | 用途 |
+|------|------|
+| `spring-boot-devtools` | 本地开发热部署 |
+| `spring-boot-starter-test` | Spring Boot 测试 |
+| `mybatis-spring-boot-starter-test` `3.0.4` | MyBatis 测试支持 |
+| `h2` | 测试环境内存数据库 |
+
+推荐版本属性：
+
+```xml
+<java.version>17</java.version>
+<mybatis-spring-boot.version>3.0.4</mybatis-spring-boot.version>
+<mybatis-plus.version>3.5.5</mybatis-plus.version>
+<pagehelper.version>2.1.1</pagehelper.version>
+<springdoc.version>2.8.13</springdoc.version>
+<hutool.version>5.8.38</hutool.version>
+```
+
+说明：`mybatis-plus-boot-starter` 不是所有 Spring Boot 项目的默认依赖；本控制系统只在使用通用 CRUD 脚手架且目标项目缺少等价基础设施时建议引入。如果目标项目已有等价基础设施，必须优先遵循目标项目约定。
+
+## ID 对外暴露规则
+- 数据库可以保留内部自增主键 `pk_id`。
+- 对外 API 统一使用业务 ID 字段 `id`。
+- 请求参数、DTO、VO、前端路由和前端状态中禁止使用 `pk_id`、`pkId`、`pk_id_list` 或 `pkIdList`。
+- 前端必须把长整型 ID 当字符串处理，禁止 `Number(id)`、一元加号、隐式数值计算或 JSON 数字化。
+- 后端可以在 Service 内部把 API 字符串 `id` 校验后转换为 `Long`。
+- 批量接口对外使用 `idList: string[]`，后端内部再转换为 `List<Long>`。
+- API 响应中的 `id` 必须序列化为字符串，避免 JavaScript 安全整数精度丢失。
+
+## ID 异常规则
+- `id` 为空、空白、非数字、非正数或超出 `Long` 范围时，返回参数错误。
+- 根据 `id` 查询不到数据时，返回业务不存在。
+- 禁止因为 `NumberFormatException`、空指针或查不到数据导致 500。
+- 优先使用目标项目已有 `BusinessException`、`ErrorCode` 和全局异常处理。
+- 不允许直接把数据库主键 `pk_id` 暴露给前端。
+
+## DTO/VO 命名
+- 创建请求：`XxxCreateReq`
+- 更新请求：`XxxUpdateReq`
+- 分页请求：`XxxPageReq`
+- 响应对象：`XxxVO`
+
+## 手写实现基线
+当通用 codegen adapter 不可用、且用户确认允许 AI 手写 Spring Boot CRUD 或管理端接口时，必须达到以下标准：
+- 先读取既有包结构、统一响应、分页对象、异常体系、权限注解、租户上下文、软删除规则和 Mapper/XML 风格。
+- 优先复用项目已有 Base 类、工具类、转换器、枚举、校验器和查询对象。
+- 新增抽象必须有明确职责，能减少真实重复或隔离变化点；禁止为了“看起来高级”而增加空壳层。
+- DTO/VO 与 Entity 分离；除非项目既有约定允许，禁止直接返回 Entity。
+- 查询、分页、排序、租户、软删除和权限条件必须清晰可定位。
+- 写操作必须有事务边界判断；多表写入必须使用事务。
+- XML 使用显式字段，禁止 `SELECT *`。
+- 实现后必须补充测试或最小验证命令。
+
+## 抽象设计
+- Controller 是薄入口，不承载业务规则。
+- Service 以业务动作建模，不把所有操作塞进一个机械 CRUD 大方法。
+- 复杂条件构造可提取为私有方法、Query Builder 或项目既有条件对象，但不得引入新依赖。
+- Entity、DTO、VO 转换应复用项目既有转换方式；没有既有方式时，优先简单显式映射。
+- 枚举、状态流、访问控制方案、权限点、错误码必须来自已确认事实源。
+
+## 事务
+以下场景必须使用事务：
+- 写入多张表
+- 修改状态并写入日志
+- 创建主记录和明细
+- 扣减库存、余额、套餐次数
+- 创建订单、支付、通知等联动数据
+
+## 验证
+后端变更必须优先运行项目既有验证命令。
+无法运行时必须说明原因。
+# Spring Boot 技术栈规则
+
+## 适用范围
+
+适用于 Java 17+、Spring Boot 3/4、Maven/Gradle、MyBatis 或 MyBatis-Plus 后端项目。
+
+本文件是 Spring Boot 技术栈入口规则；详细实现约束以 `.ai/rules/41-spring-boot.md` 为准。
+
+读取顺序：
+
+1. 先读 `.ai/rules/41-spring-boot.md` 判断是否适用。
+2. 再读 `.ai/rules/41-spring-boot.md` 获取依赖分级、ID、异常、事务和 DTO/VO 细则。
+3. 最后按目标项目既有代码确认实际包结构、响应体、异常、分页、权限和 Mapper/XML 风格。
+
+## 接入原则
+
+- 优先读取目标项目已有包结构、统一响应、异常体系、分页对象、权限注解、租户上下文和 Mapper/XML 风格。
+- 目标项目没有约定时，再使用本控制系统默认的 DTO/VO、ID、事务和依赖规则。
+- Spring Boot 版本必须跟随目标项目；禁止为了脚手架强行升级。
+- 依赖按“必须依赖、功能依赖、脚手架依赖、测试依赖”分级处理。
+
+## 默认关注点
+
+- Controller 薄入口。
+- Service 承载业务动作和事务边界。
+- Mapper/XML 显式字段，禁止 `SELECT *`。
+- API 对外暴露 `id`，数据库内部可保留 `pk_id`。
+- 长整型 ID 给前端时按字符串处理。
+- 参数非法返回参数错误，数据不存在返回业务不存在。
+# Spring Boot 技术栈规则
+
+## 适用范围
+
+适用于 Java 17+、Spring Boot 3/4、Maven/Gradle、MyBatis 或 MyBatis-Plus 后端项目。
+
+本文件是 Spring Boot 技术栈入口规则；详细实现约束以 `.ai/rules/41-spring-boot.md` 为准。
+
+读取顺序：
+
+1. 先读 `.ai/rules/41-spring-boot.md` 判断是否适用。
+2. 再读 `.ai/rules/41-spring-boot.md` 获取依赖分级、ID、异常、事务和 DTO/VO 细则。
+3. 最后按目标项目既有代码确认实际包结构、响应体、异常、分页、权限和 Mapper/XML 风格。
+
+## 接入原则
+
+- 优先读取目标项目已有包结构、统一响应、异常体系、分页对象、权限注解、租户上下文和 Mapper/XML 风格。
+- 目标项目没有约定时，再使用本控制系统默认的 DTO/VO、ID、事务和依赖规则。
+- Spring Boot 版本必须跟随目标项目；禁止为了脚手架强行升级。
+- 依赖按“必须依赖、功能依赖、脚手架依赖、测试依赖”分级处理。
+
+## 默认关注点
+
+- Controller 薄入口。
+- Service 承载业务动作和事务边界。
+- Mapper/XML 显式字段，禁止 `SELECT *`。
+- API 对外暴露 `id`，数据库内部可保留 `pk_id`。
+- 长整型 ID 给前端时按字符串处理。
+- 参数非法返回参数错误，数据不存在返回业务不存在。

package/payload/rules/42-go-gin.md

@@ -0,0 +1,20 @@
+# Go Gin 技术栈规则
+
+## 适用范围
+
+适用于 Go、Gin、MySQL、Redis、RESTful API 后端项目。
+
+## 接入原则
+
+- 优先遵循目标项目已有分层、错误码、响应体、日志、配置和中间件。
+- 不清楚 ORM、事务、鉴权、权限、分页、错误码时必须先问。
+- 不得把 Java/Spring Boot 的目录、注解或依赖规则套到 Go 项目。
+
+## 实现要求
+
+- Handler 只做入参、基础校验和响应，不堆业务规则。
+- Service 承载业务动作、状态流、事务和权限判断。
+- Repository/DAO 负责数据访问，SQL 必须显式字段。
+- 涉及多表写入必须使用事务。
+- API 对外 ID 按字符串处理，避免前端精度问题。
+

package/payload/rules/43-php.md

@@ -0,0 +1,19 @@
+# PHP 技术栈规则
+
+## 适用范围
+
+适用于 PHP、Laravel、ThinkPHP 或其他 PHP 后端项目。
+
+## 接入原则
+
+- 优先遵循目标项目已有目录、路由、中间件、异常、响应体、ORM 和迁移方式。
+- 不得把 Java/Spring Boot 的包结构、注解或依赖规则套到 PHP 项目。
+- API 字段、状态、权限、错误码和数据库字段必须来自 OpenSpec 或用户确认。
+
+## 实现要求
+
+- Controller 保持薄入口。
+- Service 或 Action 承载业务动作。
+- Repository/Model 负责数据访问，禁止在控制器里堆 SQL。
+- 涉及多表写入必须使用事务。
+- 后台管理功能必须确认访问控制模式、责任系统和权限点；如果本服务不建设 RBAC，按外部权限系统约定处理。

package/payload/rules/44-java-enum.md

@@ -0,0 +1,108 @@
+# Java 枚举与常量规则
+
+目标：业务判断、出参文案、入参校验全部收敛到枚举，禁止魔法值散落在代码里。文案或值域要改时，只改枚举一处，全系统生效。
+
+## 枚举定义规范
+
+- 业务状态、类型、标志位必须定义枚举，结构统一为 `code + desc` 双字段：`code` 用于入库和传输，`desc` 仅用于展示。
+- 必须提供 `fromCode(code)` 静态解析方法：查不到时返回 null 或抛业务异常，**禁止返回默认枚举值掩盖非法输入**。
+- 禁止 `ordinal()` 参与入库、传输或任何业务逻辑；禁止依赖枚举声明顺序。
+- 枚举值必须来自 OpenSpec、表注释或用户确认的事实源，禁止发明；DB 表注释、枚举定义、API 文档三处值域必须一致，变更必须走 change。
+- 目标项目已有枚举基类/接口（如 `IEnum<T>`）时必须跟随既有约定。
+
+```java
+@Getter
+@AllArgsConstructor
+public enum OrderStatus {
+    PENDING(0, "待支付"),
+    PAID(1, "已支付"),
+    SHIPPED(2, "已发货"),
+    CLOSED(9, "已关闭");
+
+    private final Integer code;
+    private final String desc;
+
+    public static OrderStatus fromCode(Integer code) {
+        for (OrderStatus s : values()) {
+            if (s.code.equals(code)) {
+                return s;
+            }
+        }
+        return null; // 调用方必须处理 null，返回参数错误
+    }
+}
+```
+
+## 判断规则：禁止魔法值
+
+- 业务判断只允许通过枚举进行，**禁止裸数字、裸字符串字面量参与状态/类型判断**。
+
+```java
+// 禁止
+if (order.getStatus() == 1) { ... }
+if ("PAID".equals(order.getStatusStr())) { ... }
+
+// 正确
+if (OrderStatus.PAID.getCode().equals(order.getStatus())) { ... }
+// 或 Entity 字段本身为枚举类型时
+if (OrderStatus.PAID == order.getStatus()) { ... }
+```
+
+- 对枚举 `switch` 必须覆盖全部分支，或在 `default` 显式抛"未知枚举值"异常——将来新增枚举值时立刻暴露，禁止静默走错分支。
+- 状态流转合法性必须集中定义（枚举内 `canTransferTo(target)` 方法或独立状态机类），禁止在各 Service 里散落 if 拼流转判断。
+
+```java
+// 集中定义流转，Service 里只调用
+public boolean canTransferTo(OrderStatus target) {
+    return switch (this) {
+        case PENDING -> target == PAID || target == CLOSED;
+        case PAID    -> target == SHIPPED || target == CLOSED;
+        case SHIPPED -> target == CLOSED;
+        case CLOSED  -> false;
+    };
+}
+```
+
+## 出参规则：禁止写死文案
+
+- VO 返回状态时必须**同时返回 `status`（code）和 `statusDesc`（desc）**，`statusDesc` 一律取自枚举 desc 字段。
+- 禁止在 Controller、Service、前端用三目/if/switch 硬拼状态文案。
+
+```java
+// 禁止
+vo.setStatusDesc(status == 1 ? "已支付" : status == 2 ? "已发货" : "未知");
+
+// 正确
+OrderStatus s = OrderStatus.fromCode(entity.getStatus());
+vo.setStatus(entity.getStatus());
+vo.setStatusDesc(s != null ? s.getDesc() : "");
+```
+
+## 入参规则：禁止透传
+
+- 前端传 code，后端必须先 `fromCode()` 解析校验；非法值返回参数错误（不是 500，也不是照存入库）。
+- DTO 字段接收原始类型（Integer/String），进入 Service 层前转换为枚举类型流转。
+
+```java
+OrderStatus target = OrderStatus.fromCode(dto.getStatus());
+if (target == null) {
+    throw new BizException(PARAM_ERROR, "非法的订单状态: " + dto.getStatus());
+}
+```
+
+## 序列化与持久化统一
+
+- Jackson 序列化统一处理（`@JsonValue` 出 code，或项目统一序列化器），禁止各处手写 `getCode()` 转换。
+- MyBatis 通过统一 TypeHandler 存取枚举；目标项目已有约定（如 MyBatis-Plus `@EnumValue`）时必须跟随。
+- 布尔型标志位跟随 DB 规则的 `0否 1是` 注释风格（见 `10-db-schema.md` 基础字段），枚举 desc 与表注释一致。
+
+## 审查检查点
+
+实现或审查涉及状态/类型的代码时，逐项确认：
+
+1. 是否存在裸数字/裸字符串参与业务判断。
+2. 是否存在硬拼的状态文案。
+3. 入参 code 是否经过 `fromCode()` 校验。
+4. `switch` 是否覆盖全部枚举分支或显式抛异常。
+5. 是否使用了 `ordinal()`。
+6. 枚举值与表注释、API 文档是否一致。

package/payload/rules/50-testing.md

@@ -0,0 +1,39 @@
+# 测试规则
+
+## 原则
+- 优先验证用户可见行为和业务规则。
+- 测试应保护关键路径，而不是只追求覆盖率数字。
+- Bug 修复必须有复现或回归验证。
+- 重构必须先有测试保护或明确人工验证步骤。
+- 本地 Agent 执行必须优先使用统一测试入口，避免每个模型自行猜测验证命令。
+
+## 测试类型
+- 单元测试：纯逻辑、领域规则、转换函数。
+- 集成测试：Service、Repository、Mapper、API。
+- 契约测试：API 请求/响应兼容性。
+- E2E 测试：核心用户路径。
+- 视觉检查：UI 布局、多视口、状态展示。
+
+## 禁止事项
+- 禁止写只验证实现细节的脆弱测试。
+- 禁止为了通过测试降低业务校验。
+- 禁止删除失败测试而不说明原因。
+- 禁止为了节省日志而不保存完整失败输出。
+- 禁止把完整无关日志直接喂给模型；应先摘要再分析。
+
+## 本地验证入口
+统一使用：
+
+```bash
+ai test
+```
+
+项目测试命令特殊时（如 `mvn test -DskipITs=false`、`make test`），写入 `.ai/config.json` 的 `testCommand` 字段，`ai test` 会优先使用它。
+
+把失败信息交给 AI 分析时，先摘要（失败用例名 + 断言信息 + 关键堆栈），禁止整份日志直接贴入上下文。
+
+## 输出要求
+交付必须说明：
+- 运行了哪些验证
+- 没运行哪些验证及原因
+- 剩余风险

package/payload/rules/51-security.md

@@ -0,0 +1,50 @@
+# 安全规则
+
+## 必查项
+- 身份认证
+- 权限校验
+- 访问控制模式：本服务 RBAC、外部权限服务、网关/IAM/SSO 或明确不适用
+- 本服务 RBAC 角色、权限码、菜单权限和按钮权限，如适用
+- 外部访问控制责任系统、凭证传递和失败处理，如适用
+- 租户隔离
+- 越权访问
+- 敏感字段脱敏
+- 密码、token、密钥泄露
+- SQL 注入
+- XSS
+- CSRF，如适用
+- 文件上传安全
+- 审计日志
+
+## 禁止事项
+- 禁止向前端暴露异常堆栈。
+- 禁止日志记录密码、token、密钥或敏感个人信息。
+- 禁止仅依赖前端权限控制。
+- 禁止绕过已有鉴权机制。
+- 禁止新增后台接口或后台页面时遗漏访问控制说明。
+- 禁止只写“需要登录”而不写访问控制方式、责任系统、角色/权限点或明确不适用原因。
+- 禁止把密钥写入仓库。
+
+## 后台功能访问控制要求
+新增或修改后台、管理端、平台管理、运营后台功能时，OpenSpec 必须说明：
+
+- 访问控制模式：本服务 RBAC、外部权限服务、网关/IAM/SSO 或明确不适用。
+- 本服务是否建设 RBAC。
+- 责任系统：本服务、网关、IAM、SSO、统一权限服务或其他已确认系统。
+- 允许访问的主体，例如平台管理、运营人员、供应商、专家、内部服务或第三方调用方。
+- 后端接口权限码或权限点，例如 `admin:user:view`；如果由外部系统负责，写外部权限标识或“不由本服务维护”。
+- 前端菜单权限和按钮权限，如适用；如果不适用必须写明原因。
+- 无权限、未登录、越权访问的处理方式。
+- 是否需要租户、组织、供应商、专家等数据范围隔离。
+- 审计日志要求，如登录、审核、导出、删除、权限变更等高风险操作。
+
+## 输出要求
+涉及安全边界时必须说明：
+- 认证方式
+- 访问控制模式和责任系统
+- 权限点或外部权限标识
+- RBAC 角色和权限码，如适用
+- 数据隔离方式
+- 敏感字段处理
+- 审计和日志
+- 剩余风险

package/payload/rules/52-performance.md

@@ -0,0 +1,45 @@
+# 性能规则
+
+## 后端
+- 避免 N+1 查询。
+- 避免大表无索引扫描。
+- 分页查询必须可控。
+- 高基数字段和时间范围查询应考虑索引。
+- 大批量操作必须说明影响范围和分批策略。
+
+## N+1 检测
+- 阅读列表页、详情聚合和导出接口的循环查询。
+- 检查 Service 中是否在 `for` / `stream` / `map` 内调用 Mapper、Repository、远程接口或缓存。
+- 对分页列表必须说明主查询、关联数据加载方式和查询次数上限。
+- 需要补充日志或测试时，应记录 SQL 数量、参数规模和触发路径。
+
+## 大表分页
+- 大表列表禁止无限滚动式全量加载。
+- 深分页风险高时优先考虑游标分页、基于稳定排序键的 seek pagination 或限制最大页数。
+- 排序字段必须稳定，常见组合为业务时间、主键或唯一序列。
+- 筛选条件、排序字段和租户/软删除字段应纳入索引设计。
+- 导出任务应考虑异步化、分批读取和结果文件生命周期。
+
+## 缓存策略
+- 缓存必须说明 key、过期时间、失效时机和数据一致性要求。
+- 禁止用缓存掩盖错误查询或缺失索引。
+- 权限、租户、用户维度数据必须进入缓存 key 或明确隔离。
+- 高并发热点缓存应考虑穿透、击穿和雪崩保护。
+- 写入后读取一致性要求高的场景必须说明是否允许短暂旧值。
+
+## 前端
+- 避免不必要的全量渲染。
+- 大列表应分页、虚拟滚动或按需加载。
+- 避免重复请求。
+- 加载态和错误态必须明确。
+
+## 输出要求
+涉及性能风险时必须说明：
+- 数据规模假设
+- 查询路径
+- 索引使用
+- 缓存策略，如有
+- 限流或分页策略
+- N+1 检测结论
+- 大表、导出或批处理策略
+- 验证方式