makemd/docs/ARCHIVE/05_AI/05_Development_Checklist.md

AI 开发检查清单（AI Development Checklist）

模块: 05_AI - AI 开发检查清单
更新日期: 2026-03-20
用途: AI 开发各阶段的强制检查项

---

📋 使用说明

AI 在开发过程中必须在以下阶段执行检查清单：

1. 开发前 - 任务领取和规划阶段
2. 开发中 - 编码实现阶段
3. 提交前 - 代码提交前验证
4. 交付后 - 任务完成确认

---

🔵 开发前检查清单（Pre-Development Checklist）

1. 任务理解

• 已阅读任务文档

  • 任务 ID 和描述
  • 验收标准
  • 依赖关系

• 已理解业务逻辑

  • 业务闭环流程
  • 状态机流转
  • 权限要求

• 已确认技术方案

  • 技术栈选择
  • 架构设计
  • 接口定义

2. 文档查阅

• 已查阅相关文档

  • .trae/rules/project-specific-rules.md - 硬性约束
  • docs/05_AI/02_Rules.md - AI 开发规则
  • docs/05_AI/04_Quick_Reference_Card.md - 快速参考
  • docs/01_Architecture/13_TypeScript_Standards.md - TypeScript 规范
  • docs/01_Architecture/15_Schema_Driven_Development.md - Schema 驱动

• 已理解领域模型

  • 实体关系
  • 数据模型
  • 业务规则

3. 任务领取

• 已检查任务状态

  • 任务状态为 pending
  • 无其他 Agent 占用

• 已声明占用

  • 在 Task_Overview.md 声明占用
  • 声明涉及文件
  • 声明预计完成时间

• 已领取完整任务包

  • 领取同一闭环的完整任务链
  • 最小粒度不少于 2 个相关任务

---

🟢 开发中检查清单（During Development Checklist）

1. TypeScript 类型安全

• 类型定义

  • 所有函数已声明返回类型
  • 所有变量已声明类型
  • 所有参数已声明类型
  • 禁止使用 any 类型

• Schema 驱动

  • 类型从 Schema（zod）推导
  • 所有外部数据经过 Schema 验证
  • 类型守卫已实现

• 类型导入

  • 所有类型从 /types 目录导入
  • 禁止各模块重复定义类型

2. 逻辑集中化

• Service 层

  • 所有业务逻辑在 Service 层
  • 状态流转在 Service 层
  • 多模块协同在 Service 层

• Controller 层

  • 只负责请求/响应
  • 只负责权限校验
  • 无业务逻辑

• Repository 层

  • 只负责数据库 CRUD
  • 无业务逻辑

3. 数据安全

• 数据库

  • 表名以 cf_ 开头
  • 金额字段使用 decimal(10,2)
  • 复杂查询通过 EXPLAIN 校验

• 五元组

  • tenantId 已填写
  • shopId 已填写
  • taskId 已填写
  • traceId 已填写
  • businessType 已填写

4. 业务规则

• 状态机

  • 状态流转遵循 STATE_MACHINE
  • 非法状态流转已拦截

• 权限校验

  • 使用 authorize() 中间件
  • 数据隔离已实现

• 利润红线

  • B2B 利润率 ≥ 15%
  • B2C 利润率 ≥ 20%

5. 代码质量

• 命名规范

  • 服务类使用 Service 后缀
  • 控制器类使用 Controller 后缀
  • 仓库类使用 Repository 后缀

• 注释规范

  • 每个服务类包含完整 JSDoc
  • 每个方法包含参数和返回值说明
  • 关键业务逻辑已添加注释
  • 任务 ID 已标注

• 文件规模

  • 单文件 ≤ 1500 行
  • 单函数 ≤ 120 行
  • UI 组件 ≤ 300 行

---

🟡 提交前检查清单（Pre-Commit Checklist）

1. 编译检查

• TypeScript 编译

  npm run typecheck
  

  • 无类型错误
  • 无编译警告

• ESLint 检查

  npm run lint
  

  • 无 ESLint 错误
  • 已修复可自动修复的问题

2. 测试检查

• 单元测试

  npm run test
  

  • 所有测试通过
  • 测试覆盖率达标

• 集成测试

  • 核心流程测试通过
  • 异常流程测试通过

3. 代码审查

• 自我审查

  • 业务逻辑正确性
  • 状态机遵循情况
  • 权限校验完整性
  • 错误处理完整性
  • 性能优化
  • 安全漏洞

• 类型安全审查

  • 无 any 类型
  • 所有函数有返回类型
  • 所有 API 有类型定义
  • 类型从 Schema 推导

4. 文档同步

• 文档更新
  • API 文档已更新
  • 数据库文档已更新
  • 任务状态已更新

---

🟠 交付后检查清单（Post-Delivery Checklist）

1. 任务完成确认

• 功能验证

  • 功能测试通过
  • 符合验收标准
  • 无回归问题

• 文档同步

  • 任务状态更新为 completed
  • 相关文档已更新
  • 注释和 JSDoc 完整

2. 资源释放

• 占用释放

  • Task_Overview.md 占用声明已清除
  • 文件占用已释放

• 知识沉淀

  • 遇到的问题已记录
  • 解决方案已文档化

3. 质量确认

• 代码质量

  • GetDiagnostics 无错误
  • 代码审查通过
  • 测试覆盖率达标

• 部署标准

  • 数据库表已初始化
  • 核心逻辑已闭环
  • 最小冒烟测试已补充

---

🔴 禁止行为清单（Forbidden Actions）

TypeScript 相关

• ❌ 使用 any 类型
• ❌ 函数不声明返回类型
• ❌ API 调用不定义类型
• ❌ 手动定义类型（不从 Schema 推导）
• ❌ 各模块重复定义类型

架构相关

• ❌ Controller 中写业务逻辑
• ❌ 前端直接写业务规则
• ❌ 直接操作数据库（不通过 Repository）
• ❌ 跨 Domain 直接操作数据库模型
• ❌ 跳过权限校验

数据相关

• ❌ 表名不以 cf_ 开头
• ❌ 金额字段使用 float/double
• ❌ 代码中执行 DROP/TRUNCATE
• ❌ 五元组未填写

业务相关

• ❌ Agent 直接修改核心业务数据
• ❌ B2B 利润率 < 15% 报价
• ❌ B2C 利润率 < 20% 无预警
• ❌ 非法状态流转

协作相关

• ❌ 单独领取任务包内的部分任务
• ❌ 不声明占用直接开始开发
• ❌ 跨模块同时占用多个任务包
• ❌ 占用超过 24 小时未释放

---

🟣 快速检查命令

# TypeScript 类型检查
npm run typecheck

# ESLint 检查
npm run lint

# ESLint 自动修复
npm run lint:fix

# 单元测试
npm run test

# 测试覆盖率
npm run test:coverage

# 完整验证
npm run validate

# 构建
npm run build

---

📊 检查清单执行记录

AI 在每个阶段完成后，应记录检查清单执行情况：

## 检查清单执行记录

**任务 ID**: BE-U001
**Agent**: AI-Backend-1
**开始时间**: 2026-03-20 10:00

### 开发前检查
- [x] 已阅读任务文档
- [x] 已理解业务逻辑
- [x] 已声明占用
- 执行时间: 2026-03-20 10:05

### 开发中检查
- [x] TypeScript 类型安全
- [x] 逻辑集中化
- [x] 数据安全
- [x] 业务规则
- [x] 代码质量
- 执行时间: 2026-03-20 12:00

### 提交前检查
- [x] TypeScript 编译
- [x] ESLint 检查
- [x] 单元测试
- [x] 代码审查
- 执行时间: 2026-03-20 13:00

### 交付后检查
- [x] 功能验证
- [x] 文档同步
- [x] 资源释放
- 执行时间: 2026-03-20 14:00

**完成时间**: 2026-03-20 14:00
**状态**: ✅ 完成

---

本检查清单为强制执行项，AI 必须在每个阶段完成所有检查。