# 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 编译**
  ```bash
  npm run typecheck
  ```
  - [ ] 无类型错误
  - [ ] 无编译警告

- [ ] **ESLint 检查**
  ```bash
  npm run lint
  ```
  - [ ] 无 ESLint 错误
  - [ ] 已修复可自动修复的问题

### 2. 测试检查

- [ ] **单元测试**
  ```bash
  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 小时未释放

---

## 🟣 快速检查命令

```bash
# 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 在每个阶段完成后，应记录检查清单执行情况：

```markdown
## 检查清单执行记录

**任务 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 必须在每个阶段完成所有检查。*