wurenzhi/makemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2748456d8acc9d1e29febf79312421879025b9ad
makemd/docs/ARCHIVE/05_AI/02_Rules.md
wurenzhi 2b86715c09 refactor: 优化代码结构并修复类型问题 
- 移除未使用的TabPane组件
- 修复类型定义和导入方式
- 优化mock数据源的环境变量判断逻辑
- 更新文档结构并归档旧文件
- 添加新的UI组件和Memo组件
- 调整API路径和响应处理
2026-03-23 12:41:35 +08:00

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

逻辑集中化强制规则

详细规范: 详见 项目规则 - 第8章

核心原则

  • 所有业务逻辑必须集中在 Service 层
  • 禁止分散在 Controller、前端或数据库操作中

AI开发强制规则（摘要）

  1. 禁止在 Controller 中实现业务逻辑 - Controller 只负责请求/响应和权限校验
  2. 禁止在前端实现业务规则 - 前端只负责展示、交互和调用接口
  3. 禁止直接操作数据库 - 所有数据库操作必须通过 Repository 层
  4. 所有业务逻辑必须封装在 Service 层 - 每个业务操作必须对应一个 Service 方法
  5. 所有状态变更必须通过 Service 方法 - 禁止直接修改状态字段

违反后果

  • 代码审查不通过：任何违反逻辑集中化原则的代码将被拒绝合并
  • AI 任务失败：AI 无法维护分散的逻辑，导致任务执行失败
  • 生产环境风险：分散逻辑导致数据不一致，直接影响系统稳定性

Mock 数据规范

详细规范: 详见 项目规则 - 第11章

核心原则

  • 禁止: 在业务组件中硬编码 Mock 数据
  • 必须: 通过 DataSource 抽象层获取数据
  • 必须: 所有 Mock 文件放在 /mock 目录

TypeScript 编译错误修复

详细方案: 详见 TypeScript 错误修复方案

当前存在 613 个编译错误，必须按照分阶段策略修复：

  1. 阶段 1: 修复 tsconfig.json 配置
  2. 阶段 2: 消除所有 any 类型
  3. 阶段 3: 修复类型不匹配
  4. 阶段 4: 统一模块导入导出
  5. 阶段 5: 正确处理 undefined 和 null
Reference in New Issue View Git Blame Copy Permalink