# 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 流程必须包含：
  - 代码质量检查
  - 单元测试
  - 集成测试
  - 构建检查
- CI 失败必须及时修复