360 lines
7.4 KiB
Markdown
360 lines
7.4 KiB
Markdown
|
# 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 必须在每个阶段完成所有检查。*
|