# 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 失败必须及时修复 --- ## 逻辑集中化强制规则 > **详细规范**: 详见 [项目规则 - 第8章](../../.trae/rules/project-specific-rules.md#8-逻辑集中化原则硬性约束) ### 核心原则 - 所有业务逻辑必须集中在 Service 层 - 禁止分散在 Controller、前端或数据库操作中 ### AI开发强制规则（摘要） 1. **禁止在 Controller 中实现业务逻辑** - Controller 只负责请求/响应和权限校验 2. **禁止在前端实现业务规则** - 前端只负责展示、交互和调用接口 3. **禁止直接操作数据库** - 所有数据库操作必须通过 Repository 层 4. **所有业务逻辑必须封装在 Service 层** - 每个业务操作必须对应一个 Service 方法 5. **所有状态变更必须通过 Service 方法** - 禁止直接修改状态字段 ### 违反后果 - **代码审查不通过**：任何违反逻辑集中化原则的代码将被拒绝合并 - **AI 任务失败**：AI 无法维护分散的逻辑，导致任务执行失败 - **生产环境风险**：分散逻辑导致数据不一致，直接影响系统稳定性 --- ## Mock 数据规范 > **详细规范**: 详见 [项目规则 - 第11章](../../.trae/rules/project-specific-rules.md#11-mock数据规范ai上下文安全) ### 核心原则 - **禁止**: 在业务组件中硬编码 Mock 数据 - **必须**: 通过 DataSource 抽象层获取数据 - **必须**: 所有 Mock 文件放在 `/mock` 目录 --- ## TypeScript 编译错误修复 > **详细方案**: 详见 [TypeScript 错误修复方案](07_TypeScript_Error_Fix_Guide.md) 当前存在 613 个编译错误，必须按照分阶段策略修复： 1. **阶段 1**: 修复 tsconfig.json 配置 2. **阶段 2**: 消除所有 any 类型 3. **阶段 3**: 修复类型不匹配 4. **阶段 4**: 统一模块导入导出 5. **阶段 5**: 正确处理 undefined 和 null