2026-03-18 12:35:52 +08:00
|
|
|
|
# AI_RULES（AI开发规则）
|
|
|
|
|
|
|
|
|
|
|
|
## 核心原则
|
|
|
|
|
|
|
|
|
|
|
|
- 必须基于 SERVICE_MAP 开发
|
|
|
|
|
|
- 不允许绕过 Service 层
|
|
|
|
|
|
- 不允许直接操作数据库（除 repository）
|
|
|
|
|
|
- 必须遵守 STATE_MACHINE
|
|
|
|
|
|
- 必须接入 BILLING（如果涉及收费）
|
|
|
|
|
|
- 必须接入 PERMISSION
|
|
|
|
|
|
- 必须遵循 DOMAIN_MODEL 定义的实体关系
|
|
|
|
|
|
- 必须按照 TEST_SPEC 进行测试
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 开发顺序
|
|
|
|
|
|
|
|
|
|
|
|
1. Service（业务逻辑）
|
|
|
|
|
|
2. Repository（数据访问）
|
|
|
|
|
|
3. Controller（接口层）
|
|
|
|
|
|
4. Frontend（前端实现）
|
|
|
|
|
|
5. Test（测试用例）
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 禁止行为
|
|
|
|
|
|
|
|
|
|
|
|
- Controller 写业务逻辑
|
|
|
|
|
|
- 前端控制状态
|
|
|
|
|
|
- 跳过权限校验
|
|
|
|
|
|
- 硬编码业务规则
|
|
|
|
|
|
- 直接修改数据库表结构
|
|
|
|
|
|
- 忽略状态机流转
|
|
|
|
|
|
- 绕过服务层直接调用底层API
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 代码规范
|
|
|
|
|
|
|
|
|
|
|
|
- 服务类统一使用 `Service` 后缀
|
|
|
|
|
|
- 控制器类统一使用 `Controller` 后缀
|
|
|
|
|
|
- 仓库类统一使用 `Repository` 后缀
|
|
|
|
|
|
- 方法名使用驼峰命名法
|
|
|
|
|
|
- 变量名使用驼峰命名法
|
|
|
|
|
|
- 常量使用大写蛇形命名法
|
|
|
|
|
|
- 类名使用帕斯卡命名法
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 注释规范
|
|
|
|
|
|
|
|
|
|
|
|
- 每个服务类必须包含完整 JSDoc
|
|
|
|
|
|
- 每个方法必须包含参数和返回值说明
|
|
|
|
|
|
- 关键业务逻辑必须添加注释
|
|
|
|
|
|
- 状态变更必须添加注释说明
|
|
|
|
|
|
- 收费相关逻辑必须添加注释
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 错误处理
|
|
|
|
|
|
|
|
|
|
|
|
- 所有错误必须通过统一的错误处理机制
|
|
|
|
|
|
- 错误信息必须清晰明确
|
|
|
|
|
|
- 错误必须记录详细日志
|
|
|
|
|
|
- 敏感错误信息不得返回给前端
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 日志规范
|
|
|
|
|
|
|
|
|
|
|
|
- 所有服务调用必须记录日志
|
|
|
|
|
|
- 状态变更必须记录日志
|
|
|
|
|
|
- 收费行为必须记录日志
|
|
|
|
|
|
- 权限校验失败必须记录日志
|
|
|
|
|
|
- 异常情况必须记录日志
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 安全规范
|
|
|
|
|
|
|
|
|
|
|
|
- 密码必须加密存储
|
|
|
|
|
|
- 敏感数据必须加密传输
|
|
|
|
|
|
- API 调用必须使用 token 认证
|
|
|
|
|
|
- 防止 SQL 注入
|
|
|
|
|
|
- 防止 XSS 攻击
|
|
|
|
|
|
- 防止 CSRF 攻击
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 性能规范
|
|
|
|
|
|
|
|
|
|
|
|
- 避免不必要的数据库查询
|
|
|
|
|
|
- 合理使用缓存
|
|
|
|
|
|
- 批量操作优化
|
|
|
|
|
|
- 异步处理耗时操作
|
|
|
|
|
|
- 合理设置超时时间
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 测试规范
|
|
|
|
|
|
|
|
|
|
|
|
- 每个服务必须有对应的测试用例
|
|
|
|
|
|
- 测试用例必须覆盖正常流程和异常流程
|
|
|
|
|
|
- 测试用例必须基于 TEST_SPEC
|
|
|
|
|
|
- 测试结果必须记录详细日志
|
|
|
|
|
|
- 测试失败必须及时修复
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 代码审查
|
|
|
|
|
|
|
|
|
|
|
|
- 代码提交前必须进行自我审查
|
|
|
|
|
|
- 审查重点：
|
|
|
|
|
|
- 业务逻辑正确性
|
|
|
|
|
|
- 状态机遵循情况
|
|
|
|
|
|
- 权限校验完整性
|
|
|
|
|
|
- 收费逻辑正确性
|
|
|
|
|
|
- 错误处理完整性
|
|
|
|
|
|
- 性能优化
|
|
|
|
|
|
- 安全漏洞
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 版本控制
|
|
|
|
|
|
|
|
|
|
|
|
- 代码必须使用 Git 进行版本控制
|
|
|
|
|
|
- 提交信息必须清晰明确
|
|
|
|
|
|
- 分支管理必须规范
|
|
|
|
|
|
- 代码合并前必须进行代码审查
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 持续集成
|
|
|
|
|
|
|
|
|
|
|
|
- 代码提交后必须触发 CI 流程
|
|
|
|
|
|
- CI 流程必须包含：
|
|
|
|
|
|
- 代码质量检查
|
|
|
|
|
|
- 单元测试
|
|
|
|
|
|
- 集成测试
|
|
|
|
|
|
- 构建检查
|
2026-03-19 01:39:34 +08:00
|
|
|
|
- CI 失败必须及时修复
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 逻辑集中化强制规则
|
|
|
|
|
|
|
|
|
|
|
|
### 核心原则
|
|
|
|
|
|
> **所有业务逻辑必须集中在 Service 层，禁止分散在 Controller、前端或数据库操作中。**
|
|
|
|
|
|
|
|
|
|
|
|
### AI开发强制规则
|
|
|
|
|
|
|
|
|
|
|
|
1. **禁止在 Controller 中实现业务逻辑**
|
|
|
|
|
|
- Controller 只负责请求/响应和权限校验
|
|
|
|
|
|
- 业务决策、状态变化、数据校验必须在 Service 层
|
|
|
|
|
|
|
|
|
|
|
|
2. **禁止在前端实现业务规则**
|
|
|
|
|
|
- 前端只负责展示、交互和调用接口
|
|
|
|
|
|
- 禁止在前端进行业务计算、状态判断和权限判断
|
|
|
|
|
|
|
|
|
|
|
|
3. **禁止直接操作数据库**
|
|
|
|
|
|
- 所有数据库操作必须通过 Repository 层
|
|
|
|
|
|
- AI 不允许直接使用数据库连接或 ORM 操作数据库
|
|
|
|
|
|
|
|
|
|
|
|
4. **所有业务逻辑必须封装在 Service 层**
|
|
|
|
|
|
- 每个业务操作必须对应一个 Service 方法
|
|
|
|
|
|
- Service 方法必须体现业务闭环
|
|
|
|
|
|
|
|
|
|
|
|
5. **所有状态变更必须通过 Service 方法**
|
|
|
|
|
|
- 禁止直接修改状态字段
|
|
|
|
|
|
- 状态变更必须通过 Service 方法并遵循状态机
|
|
|
|
|
|
|
|
|
|
|
|
6. **所有跨模块操作必须在 Service 中完成**
|
|
|
|
|
|
- 跨模块协同必须在 Service 层实现
|
|
|
|
|
|
- 禁止在 Controller 或前端进行跨模块调用
|
|
|
|
|
|
|
|
|
|
|
|
7. **AI 修改代码时的优先顺序**
|
|
|
|
|
|
- 优先修改 Service 层代码
|
|
|
|
|
|
- 其次修改 Repository 层代码
|
|
|
|
|
|
- 最后修改 Controller 或前端代码
|
|
|
|
|
|
|
|
|
|
|
|
8. **Service 方法命名规范**
|
|
|
|
|
|
- 方法名必须体现业务闭环
|
|
|
|
|
|
- 例如：`createOrderWithInventoryLock()` 而不是 `createOrder()`
|
|
|
|
|
|
|
|
|
|
|
|
9. **状态机遵循**
|
|
|
|
|
|
- 所有状态变更必须遵循 STATE_MACHINE 定义
|
|
|
|
|
|
- 禁止非法状态流转
|
|
|
|
|
|
|
|
|
|
|
|
10. **服务层职责边界**
|
|
|
|
|
|
- Controller：请求/响应 + 权限校验
|
|
|
|
|
|
- Service：业务逻辑编排 + 状态流转 + 多模块协同
|
|
|
|
|
|
- Repository：数据库 CRUD 操作
|
|
|
|
|
|
|
|
|
|
|
|
### 违反后果
|
|
|
|
|
|
- **代码审查不通过**：任何违反逻辑集中化原则的代码将被拒绝合并
|
|
|
|
|
|
- **AI 任务失败**：AI 无法维护分散的逻辑，导致任务执行失败
|
|
|
|
|
|
- **生产环境风险**：分散逻辑导致数据不一致，直接影响系统稳定性
|
