dev-plan-builder

name	dev-plan-builder
description	开发计划生成器 - 基于架构文档生成详细的开发计划，包括前端、后端、集成测试等子文档。每个模块对应一个开发计划，每个计划拆分为原子化开发任务。

Dev Plan Builder - 开发计划生成器

基于架构文档生成详细的开发计划，将架构设计转化为可执行的开发任务。

核心原则

1. 严格对应原则

• 每个开发计划对应架构文档中的一个模块
• 每个开发任务对应架构文档中的一个接口或功能点
• 所有任务都能追溯到PRD需求

2. 原子化任务原则

任务大小限制（确保不超过上下文窗口）：

• 代码变更: ≤ 200行
• 涉及文件: ≤ 5个
• 测试用例: ≤ 10个
• 执行时间: ≤ 30分钟

3. 自包含原则

• 每个开发计划文档都是自包含的
• 每个开发任务文档都是自包含的
• 不需要查阅其他文档即可完成任务

4. 功能完整性原则

• 写入与读取必须各成任务：凡涉及持久化数据的功能，"写入/存储"和"读取并应用到 UI"必须是两个独立任务，且两者均为必须完成项；不允许只交付数据层任务而省略 UI 接入任务
• 任务必须覆盖到 UI 绑定层：功能任务不能止步于 ViewModel/Service 层；对用户可见的功能，必须有对应的 View 层绑定任务（如"在 View 中调用 ViewModel 方法"、"将状态变量绑定到 UI 控件"）
• P1 功能不可跳过：PRD 中标注为 P1（含"可选"）的功能必须生成对应任务，并在任务中注明优先级标签；不得因"可选"而不生成任务
• View 层交互必须是独立任务：用户交互（点击、双击、拖拽等）必须拆分为独立的 View 层任务，不能与"渲染任务"合并；每个交互任务必须有明确的调用链定义
• View 层任务验收标准必须使用三级验证格式：
  • 数据展示验证：静态渲染正确、空状态处理、加载状态处理
  • 布局验证（容器类/组件类任务）：尺寸符合设计规范、不挤占核心内容区、响应式适配正确
  • 交互验证（交互类任务）：事件触发验证、状态反馈验证、数据流转验证
• 导航类任务必须端到端验证：目录导航、页面导航等任务不能只检查"列表能显示"，必须验证"点击 → 跳转 → 目标位置正确加载"的完整链路
• 容器类任务必须验证布局合规：工具栏、侧边栏等容器任务必须验证尺寸不挤占核心内容区、符合设计规范
• 架构约束必须有对应任务：架构文档中定义的 UI-Layout-xxx 尺寸约束、VIEW-API-xxx 交互接口，都必须在开发计划中有对应的实现任务

5. 非功能需求任务原则

• 性能指标必须有验证任务：PRD 或架构中出现的性能要求（如帧率、响应时间）必须生成独立的性能验证任务，明确验证工具（如 Instruments、Lighthouse）和通过条件
• 配置类需求必须有独立任务：涉及系统配置、Info.plist、权限声明等的需求，必须生成对应配置任务，不允许以"实现时顺带处理"替代

---

输入要求

必须提供架构文档路径：

• docs/v{N}/02-architecture/ - 架构设计文档目录
• 或用户指定的架构文档路径

---

工作流程

阶段 1: 架构解析

1.1 读取架构文档

读取目录:
- docs/v{N}/02-architecture/01-overview.md
- docs/v{N}/02-architecture/02-layers.md
- docs/v{N}/02-architecture/03-*.md (所有模块文档)
- docs/v{N}/02-architecture/04-api-spec.md
- docs/v{N}/02-architecture/05-data-spec.md
- docs/v{N}/02-architecture/06-state-spec.md
- docs/v{N}/02-architecture/07-boundary-spec.md

1.2 提取模块清单

## 模块清单

| 编号 | 模块名称 | 层次 | 接口数 | 数据实体数 | 状态机数 | 优先级 |
|-----|---------|------|-------|-----------|---------|-------|
| MOD-01 | 用户模块 | 业务层 | 5 | 2 | 1 | P0 |
| MOD-02 | 订单模块 | 业务层 | 8 | 3 | 2 | P0 |
| MOD-03 | 支付模块 | 服务层 | 4 | 2 | 1 | P1 |
...

1.3 分析依赖关系

## 模块依赖关系

| 模块 | 依赖模块 | 依赖类型 | 开发顺序 |
|-----|---------|---------|---------|
| MOD-01 | - | 无依赖 | 第1批 |
| MOD-02 | MOD-01 | 强依赖 | 第2批 |
| MOD-03 | MOD-02 | 强依赖 | 第3批 |
...

---

阶段 2: 开发计划生成

2.1 生成总览文档

输出: docs/v{N}/03-dev-plan/00-overview.md

# 开发计划总览

## 文档信息
- **项目名称**: [项目名称]
- **版本**: v1.0
- **对应架构**: docs/v{N}/02-architecture/
- **创建日期**: [日期]

## 1. 项目概述

[基于架构overview的项目概述]

## 2. 模块开发计划

| 批次 | 模块 | 开发计划 | 任务数 | 预估工时 | 状态 |
|-----|------|---------|-------|---------|------|
| 1 | MOD-01 用户模块 | 01-backend-mod-01.md | 8 | 3天 | 待开发 |
| 1 | MOD-01 用户模块 | 02-frontend-mod-01.md | 6 | 2天 | 待开发 |
| 2 | MOD-02 订单模块 | 03-backend-mod-02.md | 12 | 5天 | 待开发 |
| 2 | MOD-02 订单模块 | 04-frontend-mod-02.md | 8 | 3天 | 待开发 |
| 2 | MOD-02 订单模块 | 05-integration-mod-02.md | 6 | 2天 | 待开发 |
...

## 3. 开发顺序

### 第1批（无依赖）
1. MOD-01 用户模块
   - 后端开发: 01-backend-mod-01.md
   - 前端开发: 02-frontend-mod-01.md

### 第2批（依赖第1批）
1. MOD-02 订单模块
   - 后端开发: 03-backend-mod-02.md
   - 前端开发: 04-frontend-mod-02.md
   - 集成测试: 05-integration-mod-02.md
...

## 4. 覆盖映射

| 架构模块 | 后端计划 | 前端计划 | 集成测试 | 覆盖状态 |
|---------|---------|---------|---------|---------|
| MOD-01 | ✅ 01-backend-mod-01 | ✅ 02-frontend-mod-01 | - | ✅ |
| MOD-02 | ✅ 03-backend-mod-02 | ✅ 04-frontend-mod-02 | ✅ 05-integration-mod-02 | ✅ |
...

## 5. 技术栈

[基于架构设计的技术栈说明]

## 6. 开发规范

### 6.1 代码规范
- [代码风格要求]
- [命名规范]

### 6.2 提交规范
- [Git提交信息格式]

### 6.3 测试规范
- [测试覆盖率要求]
- [测试类型要求]

2.2 生成模块开发计划

每个模块生成三类开发计划：

• 后端开发计划 (backend)
• 前端开发计划 (frontend)
• 集成测试计划 (integration)

命名规范: {序号}-{类型}-mod-{模块编号}.md

后端开发计划模板

输出: docs/v{N}/03-dev-plan/{序号}-backend-mod-{模块编号}.md

# 后端开发计划 - [模块名称]

## 文档信息

- **模块编号**: MOD-XX
- **模块名称**: [模块名称]
- **所属层次**: [层次]
- **对应架构**: docs/v{N}/02-architecture/03-mod-xx-[模块名称].md
- **优先级**: P0/P1/P2
- **预估工时**: X天

---

## 1. 模块概述

### 1.1 模块职责

[基于架构文档的模块职责描述]

### 1.2 对应PRD

| PRD编号 | 功能 | 用户故事 |
|---------|-----|---------|
| FR-XXX | [功能] | US-XXX |

### 1.3 架构定位

[架构定位图，复制自架构文档]

---

## 2. 技术设计

### 2.1 技术栈

| 类型 | 技术 | 版本 |
|-----|------|------|
| 语言 | TypeScript | 5.x |
| 框架 | Express | 4.x |
| 数据库 | PostgreSQL | 15.x |

### 2.2 目录结构

src/modules/[module-name]/ ├── controller.ts # 控制器 ├── service.ts # 业务逻辑 ├── repository.ts # 数据访问 ├── model.ts # 数据模型 ├── types.ts # 类型定义 └── tests/ # 测试文件 ├── controller.test.ts ├── service.test.ts └── repository.test.ts

### 2.3 依赖关系

| 依赖模块 | 依赖方式 | 用途 |
|---------|---------|------|
| [模块A] | import | [用途] |

---

## 3. 接口清单

| 任务编号 | 接口编号 | 接口名称 | 方法 | 路径 | 复杂度 |
|---------|---------|---------|------|------|-------|
| T-01 | API-001 | [接口] | POST | /api/xxx | 中 |
| T-02 | API-002 | [接口] | GET | /api/xxx | 低 |
...

---

## 4. 数据结构

### 4.1 核心实体

[复制自架构数据结构规约]

### 4.2 数据库表设计

[表结构设计]

---

## 5. 开发任务拆分

### 任务约束
- **代码变更**: ≤ 200行
- **涉及文件**: ≤ 5个
- **测试用例**: ≤ 10个

### 任务清单

| 任务编号 | 任务名称 | 涉及接口 | 文件数 | 代码行数 | 依赖 |
|---------|---------|---------|-------|---------|------|
| T-01 | 数据模型定义 | - | 2 | ~80 | - |
| T-02 | 数据访问层 | API-001~003 | 3 | ~150 | T-01 |
| T-03 | 业务逻辑层-创建 | API-001 | 3 | ~120 | T-02 |
| T-04 | 业务逻辑层-查询 | API-002,003 | 2 | ~100 | T-02 |
| T-05 | 控制器层-创建 | API-001 | 2 | ~80 | T-03 |
| T-06 | 控制器层-查询 | API-002,003 | 2 | ~80 | T-04 |
| T-07 | 单元测试 | - | 4 | ~200 | T-01~06 |
| T-08 | 集成测试 | API-001~003 | 2 | ~150 | T-01~07 |

---

## 6. 详细任务定义

### T-01: 数据模型定义

**任务概述**: 定义模块核心数据模型和类型

**对应架构**:
- 数据结构规约: DATA-XXX, DATA-YYY
- 所属模块: MOD-XX

**输入**:
- 架构数据结构规约文档

**输出**:
- `src/modules/[module]/model.ts`
- `src/modules/[module]/types.ts`

**实现要求**:

```typescript
// types.ts - 类型定义
export interface [Entity] {
  id: string;
  field1: string;
  // ... 完整类型定义
}

// model.ts - 数据模型
export class [Entity]Model {
  // 基于架构数据结构规约实现
}

验收标准:

• 类型定义与架构数据结构规约一致
• 包含所有必需字段
• 包含字段验证逻辑

测试要求:

• 测试文件: __tests__/model.test.ts
• 测试用例: ≤ 5个
• 覆盖率: ≥ 80%

预估工时: 0.5天

依赖: 无

---

T-02: 数据访问层

任务概述: 实现数据访问层，包括CRUD操作

对应架构:

• 接口规约: API-001~003
• 数据结构规约: DATA-XXX

输入:

• T-01 的数据模型
• 架构接口规约文档

输出:

• src/modules/[module]/repository.ts
• __tests__/repository.test.ts

实现要求:

// repository.ts
export class [Entity]Repository {
  async create(data: CreateDTO): Promise<Entity>;
  async findById(id: string): Promise<Entity | null>;
  async findMany(query: QueryDTO): Promise<Entity[]>;
  async update(id: string, data: UpdateDTO): Promise<Entity>;
  async delete(id: string): Promise<void>;
}

验收标准:

• 实现所有CRUD操作
• 错误处理完整
• 日志记录完整

测试要求:

• 测试文件: __tests__/repository.test.ts
• 测试用例: ≤ 8个
• 覆盖率: ≥ 80%

预估工时: 0.5天

依赖: T-01

---

[继续定义其他任务...]

---

7. 测试策略

7.1 单元测试

测试类型	覆盖率	工具
模型测试	≥ 80%	Jest
仓库测试	≥ 80%	Jest + Mock
服务测试	≥ 80%	Jest + Mock
控制器测试	≥ 80%	Supertest

7.2 集成测试

[集成测试策略]

---

8. 验收清单

8.1 功能验收

• 所有接口实现完成
• 所有单元测试通过
• 集成测试通过
• 代码审查通过

8.2 质量验收

• 测试覆盖率 ≥ 80%
• 无 lint 错误
• 无安全漏洞

8.3 文档验收

• API 文档更新
• 代码注释完整

---

9. 覆盖映射

架构元素	架构编号	任务	覆盖状态
接口	API-001	T-03, T-05	✅
接口	API-002	T-04, T-06	✅
数据实体	DATA-XXX	T-01	✅
状态机	STATE-XXX	T-03	✅
边界条件	BOUND-XXX	T-05	✅

##### 前端开发计划模板

**输出**: `docs/v{N}/03-dev-plan/{序号}-frontend-mod-{模块编号}.md`

```markdown
# 前端开发计划 - [模块名称]

## 文档信息

- **模块编号**: MOD-XX
- **模块名称**: [模块名称]
- **对应架构**: docs/v{N}/02-architecture/03-mod-xx-[模块名称].md
- **优先级**: P0/P1/P2
- **预估工时**: X天

---

## 1. 模块概述

### 1.1 模块职责

[前端模块职责]

### 1.2 UI设计规范

[基于架构UI设计规范]

### 1.3 页面清单

| 页面 | 路由 | 功能 |
|-----|------|------|
| [页面1] | /xxx | [功能] |

---

## 2. 技术设计

### 2.1 技术栈

| 类型 | 技术 | 版本 |
|-----|------|------|
| 框架 | React | 18.x |
| 状态管理 | Zustand | 4.x |
| UI组件 | Ant Design | 5.x |

### 2.2 目录结构

src/pages/[module]/ ├── index.tsx # 页面入口 ├── components/ # 组件目录 │ ├── List.tsx │ ├── Form.tsx │ └── Detail.tsx ├── hooks/ # 自定义hooks │ └── use[Module].ts ├── store/ # 状态管理 │ └── use[Module]Store.ts ├── api/ # API调用 │ └── [module]Api.ts └── tests/ # 测试文件

---

## 3. 接口调用

| 任务编号 | 接口 | 调用场景 | API函数 |
|---------|------|---------|---------|
| T-01 | API-001 | 创建 | create[Entity] |
| T-02 | API-002 | 查询列表 | get[Entity]List |
...

---

## 4. 开发任务拆分

| 任务编号 | 任务名称 | 涉及文件 | 代码行数 | 依赖 |
|---------|---------|---------|---------|------|
| T-01 | API层 | 2 | ~100 | - |
| T-02 | 状态管理 | 2 | ~80 | T-01 |
| T-03 | 列表组件 | 3 | ~150 | T-02 |
| T-04 | 表单组件 | 3 | ~150 | T-02 |
| T-05 | 详情组件 | 2 | ~100 | T-02 |
| T-06 | 页面组装 | 2 | ~80 | T-03~05 |
| T-07 | 单元测试 | 4 | ~200 | T-01~06 |
| T-08 | E2E测试 | 2 | ~150 | T-01~07 |

---

## 5. 详细任务定义

### T-01: API层

**任务概述**: 实现API调用层

**对应架构**:
- 接口规约: API-001~00X

**输出**:
- `src/pages/[module]/api/[module]Api.ts`
- `src/pages/[module]/api/types.ts`

**实现要求**:

```typescript
// [module]Api.ts
import { request } from '@/utils/request';

export const [module]Api = {
  create: (data: CreateDTO) => request.post('/api/xxx', data),
  getList: (params: QueryDTO) => request.get('/api/xxx', { params }),
  // ...
};

验收标准:

• 所有接口都有对应的API函数
• 类型定义完整
• 错误处理完整

测试要求:

• 测试文件: __tests__/api.test.ts
• 使用MSW模拟后端
• 覆盖率: ≥ 80%

预估工时: 0.5天

---

[继续定义其他任务...]

---

6. 测试策略

6.1 单元测试

• 组件测试: React Testing Library
• Hook测试: @testing-library/react-hooks
• Store测试: 直接调用

6.2 E2E测试

• 工具: Playwright
• 场景: [主要用户场景]

---

7. 验收清单

• 所有页面实现完成
• 所有组件测试通过
• E2E测试通过
• UI还原度 ≥ 95%
• 响应式适配完成

---

8. 覆盖映射

架构元素	任务	覆盖状态
UI组件	T-03~05	✅
API调用	T-01	✅
状态管理	T-02	✅

##### 集成测试计划模板

**输出**: `docs/v{N}/03-dev-plan/{序号}-integration-mod-{模块编号}.md`

```markdown
# 集成测试计划 - [模块名称]

## 文档信息

- **模块编号**: MOD-XX
- **模块名称**: [模块名称]
- **对应架构**: docs/v{N}/02-architecture/03-mod-xx-[模块名称].md
- **优先级**: P0/P1/P2
- **预估工时**: X天

---

## 1. 测试范围

### 1.1 测试目标

[集成测试目标描述]

### 1.2 测试边界

**包含**:
- 前后端接口集成
- 数据库操作
- 外部服务Mock

**不包含**:
- 单元测试覆盖的内容
- 纯前端逻辑

---

## 2. 测试场景

| 场景编号 | 场景名称 | 前置条件 | 测试步骤 | 预期结果 |
|---------|---------|---------|---------|---------|
| INT-001 | 创建[实体]成功 | 用户已登录 | 1. 打开页面 2. 填写表单 3. 提交 | 创建成功 |
| INT-002 | 创建[实体]失败-参数错误 | 用户已登录 | 1. 打开页面 2. 不填必填项 3. 提交 | 提示错误 |
...

---

## 3. 测试数据

### 3.1 数据准备

```sql
-- 测试数据
INSERT INTO t_xxx VALUES (...);

3.2 Mock配置

// 外部服务Mock
const mockConfig = {
  serviceA: { baseUrl: 'http://mock:3001' },
  serviceB: { baseUrl: 'http://mock:3002' },
};

---

4. 开发任务拆分

任务编号	任务名称	涉及文件	代码行数	依赖
T-01	测试环境配置	3	~100	-
T-02	测试数据准备	2	~80	T-01
T-03	创建场景测试	2	~150	T-02
T-04	查询场景测试	2	~120	T-02
T-05	更新场景测试	2	~120	T-02
T-06	删除场景测试	2	~100	T-02
T-07	异常场景测试	2	~150	T-02
T-08	测试报告生成	1	~50	T-03~07

---

5. 详细任务定义

T-01: 测试环境配置

任务概述: 配置集成测试环境

输出:

• tests/integration/[module]/setup.ts
• tests/integration/[module]/config.ts
• docker-compose.test.yml

实现要求:

• 使用Docker启动测试数据库
• 配置测试专用环境变量
• 准备测试数据清理脚本

验收标准:

• 测试环境可一键启动
• 测试数据可自动清理
• 测试结果可自动收集

预估工时: 0.5天

---

[继续定义其他任务...]

---

6. 测试报告

6.1 报告格式

# 集成测试报告 - [模块名称]

## 测试概况
- 执行时间: [时间]
- 总用例数: [N]
- 通过数: [M]
- 失败数: [K]
- 通过率: [X%]

## 失败用例详情
[失败用例列表]

## 建议
[改进建议]

---

7. 验收清单

• 所有场景测试通过
• 测试覆盖率 ≥ 80%
• 无遗留缺陷
• 测试报告已生成

---

8. 覆盖映射

架构接口	测试场景	覆盖状态
API-001	INT-001, INT-002	✅
API-002	INT-003, INT-004	✅

---

### 阶段 3: 任务拆分验证

#### 3.1 任务大小检查

```markdown
## 任务大小检查报告

| 任务 | 代码行数 | 文件数 | 测试用例数 | 状态 |
|-----|---------|-------|-----------|------|
| T-01 | 80 | 2 | 5 | ✅ 符合 |
| T-02 | 150 | 3 | 8 | ✅ 符合 |
| T-XX | 250 | 6 | 12 | ❌ 需拆分 |

**需拆分任务**:
- T-XX: 建议拆分为 T-XX-A 和 T-XX-B

3.2 覆盖完整性检查

## 覆盖完整性检查报告

### 架构元素覆盖

| 架构类型 | 总数 | 已覆盖 | 未覆盖 | 覆盖率 |
|---------|-----|-------|-------|-------|
| 接口 | 32 | 32 | 0 | 100% |
| 数据实体 | 8 | 8 | 0 | 100% |
| 状态机 | 5 | 5 | 0 | 100% |
| 边界条件 | 48 | 48 | 0 | 100% |

✅ 所有架构元素已100%覆盖

---

输出目录结构

docs/v{N}/
├── 02-architecture/          # 架构文档（输入）
└── 03-dev-plan/
    ├── 00-overview.md        # 开发计划总览
    ├── 01-backend-mod-01.md  # 后端开发计划 - 模块1
    ├── 02-frontend-mod-01.md # 前端开发计划 - 模块1
    ├── 03-backend-mod-02.md  # 后端开发计划 - 模块2
    ├── 04-frontend-mod-02.md # 前端开发计划 - 模块2
    ├── 05-integration-mod-02.md # 集成测试计划 - 模块2
    └── ...

---

检查清单

阶段1检查：架构解析

• 已读取所有架构文档
• 已提取所有模块清单
• 已分析依赖关系

阶段2检查：开发计划生成

• 总览文档已生成
• 每个模块都有对应的开发计划
• 每个开发计划都有任务拆分
• 每个任务都有详细定义

阶段3检查：任务拆分验证

• 所有任务符合大小限制
• 所有架构元素都有任务覆盖
• 覆盖率达到100%

阶段3补充检查：功能完整性

• 所有持久化功能都有"写入任务"和"读取并应用任务"，两者均存在
• 所有对用户可见的功能都有 View 层绑定任务，无功能止步于 Service/ViewModel 层
• PRD 中所有 P1 功能均已生成任务（含"可选"标记的 P1），任务中标注优先级
• PRD 或架构中出现的性能指标均有独立的性能验证任务，含验证工具和通过条件
• 涉及系统配置、权限声明的需求均有独立配置任务

阶段3补充检查：交互验证完整性

• 每个 View 层任务（列表/表单/详情/导航组件）的验收标准包含交互验证子项：
  • 数据展示：静态渲染正确（已有）
  • 事件触发：点击/双击/拖拽等手势能正确触发对应事件
  • 状态反馈：交互后 UI 状态变化符合预期（如高亮、跳转、弹窗）
  • 数据流转：交互产生的数据能正确传递到 ViewModel/Service 层
• 每个导航类任务（目录导航/页面导航/标签切换）的验收标准包含端到端跳转验证：
  • 触发导航 → 目标页面/位置正确加载 → 状态同步更新
• 每个容器类任务（工具栏/侧边栏/导航栏）的验收标准包含布局验证：
  • 尺寸符合设计规范、不挤占核心内容区、响应式适配正确

阶段3补充检查：任务模板合规性

• 所有 View 层任务验收标准必须使用三级验证格式：
  • [ ] **数据展示验证**: ...
  • [ ] **布局验证**: ...（如适用）
  • [ ] **交互验证**: ...（如适用）
• 所有涉及持久化的功能必须有成对任务：写入任务 + 读取并应用任务
• 所有架构中的 UI-Layout-xxx 约束都有对应的实现任务
• 所有架构中的 VIEW-API-xxx 交互接口都有独立的实现任务

---

使用示例

用户: "基于架构文档生成开发计划"

AI: [读取架构文档目录]

    【阶段1】架构解析
    - 模块数: 5个
    - 接口数: 32个
    - 数据实体: 8个
    - 状态机: 5个

    【阶段2】开发计划生成
    ✅ 00-overview.md
    ✅ 01-backend-mod-01.md (8个任务)
    ✅ 02-frontend-mod-01.md (8个任务)
    ✅ 03-backend-mod-02.md (12个任务)
    ✅ 04-frontend-mod-02.md (8个任务)
    ✅ 05-integration-mod-02.md (8个任务)
    ...

    【阶段3】任务拆分验证
    ✅ 所有任务符合大小限制
    ✅ 覆盖率: 100%

    开发计划生成完成！
    - 总任务数: 64个
    - 预估工时: 25天

---

注意事项

1. 任务大小控制: 确保每个任务不超过上下文限制
2. 自包含: 每个任务文档都要能独立理解
3. 追溯性: 每个任务都能追溯到架构和PRD
4. 依赖顺序: 任务按依赖关系排序
5. 测试先行: 每个任务都包含测试要求

---

原子化任务 · 自包含文档 · 100%覆盖 📋