wurenzhi/makemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
989c4b13a64c30633fd193c5ed4cdfbbf55db8b1
makemd/docs/05_AI/02_Rules.md
wurenzhi eafa1bbe94 feat: 添加货币和汇率管理功能 
refactor: 重构前端路由和登录逻辑

docs: 更新业务闭环、任务和架构文档

style: 调整代码格式和文件结构

chore: 更新依赖项和配置文件
2026-03-19 19:08:15 +08:00

4.8 KiB
Raw Blame History

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 失败必须及时修复

逻辑集中化强制规则

核心原则

所有业务逻辑必须集中在 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 无法维护分散的逻辑，导致任务执行失败
  • 生产环境风险：分散逻辑导致数据不一致，直接影响系统稳定性
Reference in New Issue View Git Blame Copy Permalink