技术方案设计

基于需求文档产出完整技术方案。核心原则：文档先行；前后端并行；测试聚焦单元与必要集成。

版本号约定

1.X 为占位符，详见 requirements-workshop/SKILL.md。真实路径必须替换为具体数字（如 workplace/1/references/）。

前后端联合设计原则

技术方案必须同时覆盖：

• 后端：架构、数据模型、API、服务、权限
• 前端：页面结构、路由、组件、状态管理、API 接入、关键交互
• 测试：后端单元/集成测试、前端单元/组件测试

需求文档"页面/界面清单"必须在技术方案中逐项有对应前端设计。遗漏前端是审核必拒项。

工作流程（9 步）

1. 读取需求文档 → 需求理解确认
2. 现状分析与变更识别：分析当前代码状态 → 产出变更清单（Delta）→ 用户确认变更范围
3. 区分新/旧功能 → 准备技术文档（新功能：参考文档；旧功能：技术栈说明）→ 存入 workplace/1.X/references/
4. 设计架构 → 架构确认
5. 设计数据模型 → 数据模型确认
6. 设计 API → API确认
7. 设计前端（路由/页面/组件/状态/API 接入，逐页确认）→ 前端逐页确认
8. 制定测试策略（单元为主，必要集成）
9. 产出技术方案 → 自检 → 用户确认 → 产出交接清单 → 进入 implementation-planning

---

第一步：读取需求文档 + 需求理解确认

从 workplace/1.X/requirements/ 读取最近的需求文档。

• 若不存在：提示用户先做 requirements-workshop 或提供文档路径
• 若有多个：列出最近 3 个让用户选择

提取功能清单与页面清单后，向用户确认理解：

我已读取需求文档，理解如下：

核心目标：[一句话概括]

功能清单摘要（共N个功能）：

• 功能1：[名称] - [用户入口] → [闭环终点]
• 功能2：...

页面清单摘要（共N个页面）：

• 页面1：[名称] ([路由]) - 对应功能X
• 页面2：...

关键验收标准：

• [主要验收点]

请确认我的理解是否准确？是否有遗漏或需要补充的重点？

等待用户确认后才进入下一步。若用户指出理解偏差，调整理解后重新确认。

---

第二步：现状分析与变更识别（Delta 分析）

这一步是技术方案质量的关键。没有 Delta 分析，方案就会退化为对已有功能的复述。

2.1 分析当前代码状态

针对需求文档中的每个功能点，探索现有代码：

• 相关模块/文件在哪里？核心函数/组件是什么？
• 当前的数据模型、API 接口、前端页面是怎样的？
• 哪些部分可以直接复用，哪些需要修改，哪些是全新的？

方法：用 Glob/Grep/Read 探索项目结构 → 用 Explore agent 深入复杂模块 → 与用户确认关键发现。

2.2 产出变更清单（Delta 清单）

变更清单是后续所有设计工作的唯一输入。它回答一个核心问题：从当前状态到目标状态，具体要改什么？

## 变更清单

### 后端变更
| 编号 | 变更类型 | 目标模块/文件 | 当前状态 | 目标状态 | 具体修改 |
| B-1 | 修改 | src/api/user.ts:getUser() | 返回字段不含 avatar | 返回字段含 avatar | 在 SELECT 中添加 avatar 字段；更新响应 DTO |
| B-2 | 新增 | src/api/user.ts | 无此接口 | 新增上传头像接口 | 新增 POST /user/avatar，处理 multipart 上传 |
| B-3 | 修改 | src/models/user.sql | 无 avatar 列 | 新增 avatar VARCHAR(255) | ALTER TABLE 添加列；编写迁移脚本 |

### 前端变更
| 编号 | 变更类型 | 目标模块/文件 | 当前状态 | 目标状态 | 具体修改 |
| F-1 | 修改 | src/pages/profile.vue | 无头像展示区域 | 顶部展示圆形头像 | 添加 avatar 展示组件；绑定 store 中的 avatar 数据 |
| F-2 | 新增 | src/components/AvatarUpload.vue | 无此组件 | 头像裁剪+上传组件 | 新建组件，集成 cropper.js + 上传 API |

### 数据模型变更
| 编号 | 变更类型 | 实体 | 变更内容 |
| D-1 | 修改 | User | 新增 avatar 字段 (VARCHAR(255), 可空) |

变更类型的含义：

• 新增：当前代码中不存在，需要从零创建
• 修改：当前代码存在但需要改动，必须说清"改哪里、改成什么"
• 删除：当前代码存在但需要移除
• 重构：功能不变但结构调整（如拆分函数、迁移模块）

2.3 用户确认变更范围

变更清单已完成。请确认：

• 变更范围是否完整？有没有遗漏的功能点？
• 每个变更的"当前状态"描述是否准确？
• 每个变更的"具体修改"是否是你想要的？

确认后才进入下一步。 变更清单是后续设计的约束——架构、数据模型、API、前端设计都必须围绕变更清单展开，不得脱离变更清单描述无关内容。

---

第三步：准备参考文档

3.1 区分功能类型

分类	定义	文档要求
新功能	项目无类似实现，引入新技术/模块	必须有参考文档
旧功能扩展	基于现有代码扩展	必须有技术栈说明
旧功能复用	直接调用现有功能	无需额外文档

判断方法：搜索现有代码 → 检查技术栈 → 与用户确认。

3.2 输出技术文档需求清单（用户确认后再继续）

## 技术文档需求清单

### 新功能（需要参考文档）
| 功能 | 文档类型 | 来源建议 | 状态 |

### 旧功能扩展（需要技术栈说明）
| 功能 | 涉及模块 | 文档要求 | 状态 |

### 文档存放位置：workplace/1.X/references/
- 参考文档：`{技术名}-reference.md`
- 技术栈说明：`{模块名}-techstack.md`
- 前端 UI 库参考：`{库名}-frontend-reference.md`

3.3 收集 / 整理文档

新功能参考文档模板（核心字段）：基本信息（链接/版本/引入方式）、核心概念、API 参考（用途/参数/返回/示例）、最佳实践、注意事项、与本项目关联。 收集方式：Context7 MCP / WebFetch/WebSearch / 用户提供 / 现有代码探索。

旧功能技术栈说明模板：模块定位、代码结构、数据模型、API 接口、依赖关系、扩展点、注意事项。

3.4 验证清单

检查项	要求
目录存在	workplace/1.X/references/ 已创建
新功能文档	每个新功能都有参考文档
旧功能文档	每个旧功能扩展都有技术栈说明

通过后宣布：> 技术文档准备完成，开始技术方案设计。

---

第四步：架构设计 + 架构确认

核心原则：以变更清单为输入，每个设计项必须对应变更清单中的编号。设计的是"改什么"而非"是什么"。

4.1 架构设计

章节	内容
系统架构图	模块划分、层次、依赖（Mermaid graph）
技术选型	各模块技术栈与理由
部署架构	部署方式、网络拓扑（如适用）
数据流向	数据在模块间流转

4.2 架构确认

产出架构设计后，向用户确认：

架构设计已完成：

系统架构图：[简述分层结构]

技术选型：

• 后端：[技术栈]
• 前端：[技术栈]

数据流向：[关键数据流]

这个架构是否符合你的预期？技术选型是否可接受？

等待用户确认后才进入下一步。若用户提出调整，修改架构设计后重新确认。

---

第五步：数据模型设计 + 数据模型确认

每个实体描述字段（名/类型/必填/默认/说明）、约束、索引、迁移计划（若有）。

### {实体名}
| 字段 | 类型 | 必填 | 默认 | 说明 |
| id | UUID | 是 | 自动 | 主键 |

5.1 数据模型确认

产出数据模型后，向用户确认：

数据模型设计如下：

新增/修改实体（共N个）：

| 实体 | 变更类型 | 关键字段 | 说明 |

请确认：

• 实体划分是否合理？
• 关键字段是否完整？
• 是否有遗漏的业务属性？

等待用户确认后才进入下一步。若用户提出调整，修改数据模型后重新确认。

---

第六步：API 设计 + API确认

接口清单 + 每个接口的：路径与方法、描述、认证、请求参数表、请求示例、响应字段表、响应示例、错误码。

6.1 API确认

产出API设计后，向用户确认：

API接口清单（共N个新增/修改）：

| 接口 | 方法 | 路径 | 对应功能 | 说明 |

请确认：

• 接口覆盖是否完整？
• 接口设计是否符合前端调用需求？
• 是否有遗漏的业务场景？

等待用户确认后才进入下一步。若用户提出调整，修改API设计后重新确认。

---

第七步：前端设计 + 前端逐页确认（强制，基于变更清单）

针对需求文档"页面/界面清单"，逐项给出前端实现设计。任何遗漏都会让需求功能在实施阶段消失。

与变更清单的关系：前端变更清单（F-* 编号）是前端设计的输入。每个前端设计项必须标注对应的变更清单编号。

7.1 设计内容

章节	内容
路由结构	所有路由及层级（含权限/守卫）
页面设计	每页布局、组件、数据来源、状态机
组件清单	复用组件、第三方组件库选型
状态管理	方案选型（Pinia/Redux/Zustand）+ store 划分
API 接入	调用哪些后端接口、错误处理、loading/重试
关键交互	表单校验、上传下载、分页等

7.2 前端逐页确认

前端设计采用逐页确认方式：

现在进行前端设计，我将逐页与你确认。

---

页面1：[页面名]（路由：[path]）

• 对应需求功能：[功能编号/名称]
• 布局结构：[简述]
• 关键组件：[列表]
• 状态机：初始 → 加载中 → [结果态]

这个页面设计是否符合预期？

[用户确认后继续下一页]

---

页面2：[页面名]...

每页确认后才继续下一页。若用户提出调整，修改该页设计后重新确认。

7.3 页面设计模板

### 页面：{页面名}（路由：{path}）
- **对应需求功能**：[功能编号/名称]
- **布局**：[结构示意]
- **关键组件**：[列表]
- **数据来源**：[API/本地状态]
- **状态机**：初始 / 加载中 / 空 / 错误 / 成功
- **交互细节**：[校验、跳转、二次确认]
- **权限**：[未登录/无权限处理]

7.4 覆盖核查表（必做）

列一张表：左列=需求文档"页面清单"每一行，右列=本方案"页面设计"对应章节锚点。任意缺失即返工。

---

第八步：测试策略（聚焦单元，必要集成）

6.1 测试目录规范（强制）

workplace/1.X/test/
├── backend/
│   ├── unit/         # 后端单元测试（核心）
│   └── integration/  # 后端集成测试（仅关键 API/数据库交互）
├── frontend/
│   ├── unit/         # 前端单元测试（工具函数/composables/store）
│   └── component/    # 前端组件测试（关键组件）
├── fixtures/         # 共享测试数据
└── README.md         # 运行命令矩阵 + 覆盖率目标

约束：

• 业务源码内不得存放测试文件（不在 src 旁放 .test.ts/test_.py），测试与源码分离便于版本归档
• 跨模块复用的 mock/fixture 集中放在 test/fixtures/
• 以单元测试为主；集成测试仅覆盖关键路径（如核心 API + 数据库写入）；不做端到端测试
• test/README.md 列出运行命令：单测、集成、覆盖率

6.2 测试策略内容

章节	内容
测试范围	哪些功能需要测试（前后端均需列出）
测试类型	单元测试（主）+ 关键集成测试
测试数据	fixtures 准备方式
覆盖率目标	后端/前端分别的目标
运行命令	各类测试命令（写入 test/README.md）

6.3 测试分类

类型	覆盖	目录	工具建议
后端单元	业务逻辑、工具函数	test/backend/unit/	pytest / Jest / JUnit
后端集成	关键 API + 数据库	test/backend/integration/	pytest / Supertest
前端单元	工具函数、composables、store	test/frontend/unit/	Vitest / Jest
前端组件	关键 UI 组件渲染与交互	test/frontend/component/	Vitest + Vue Test Utils / RTL

本套 skill 不做端到端测试。如确有强需求，由用户单独提出后另行规划，不在本方案默认范围内。

---

第九步：产出技术方案文档 + 交接清单

9.1 命名与存储

命名：YYYY-MM-DD-{需求名称}-技术方案.md 存储：workplace/1.X/tech-design/

9.2 模板

# {需求名称} 技术方案

> 需求文档：[路径]
> 技术参考：workplace/1.X/references/

## 一、变更清单（Delta 清单）

> 这是本方案的核心。后续所有设计都必须围绕此清单展开。

### 1.1 后端变更
| 编号 | 变更类型 | 目标模块/文件 | 当前状态 | 目标状态 | 具体修改 |
| B-1 | ... | ... | ... | ... | ... |

### 1.2 前端变更
| 编号 | 变更类型 | 目标模块/文件 | 当前状态 | 目标状态 | 具体修改 |
| F-1 | ... | ... | ... | ... | ... |

### 1.3 数据模型变更
| 编号 | 变更类型 | 实体 | 变更内容 |
| D-1 | ... | ... | ... |

### 1.4 变更汇总
- 新增：X 个（列出编号）
- 修改：Y 个（列出编号）
- 删除：Z 个（列出编号）

## 二、架构设计
### 2.1 系统架构图（含前后端分层）
### 2.2 技术选型
### 2.3 部署架构（如适用）

## 三、数据模型
### 3.1 实体定义（仅列出变更涉及的实体）
### 3.2 关系图
### 3.3 索引设计

## 四、API 设计
### 4.1 接口清单（仅列出变更涉及的接口）
### 4.2 接口详情

## 五、前端设计
### 5.1 路由结构
### 5.2 页面设计
### 5.3 组件清单
### 5.4 状态管理
### 5.5 API 接入与错误处理
### 5.6 覆盖核查表（需求页面清单 → 本章节锚点）
| 需求页面 | 路由 | 对应章节 |

## 六、测试策略
### 6.1 测试目录（workplace/1.X/test/，单元为主+必要集成，不做 E2E）
### 6.2 测试范围（前后端分别列出）
### 6.3 测试类型与工具
### 6.4 覆盖率目标
### 6.5 运行命令

## 七、需求-方案映射核查表

| 需求功能 | 变更清单编号 | API接口 | 前端页面 | 测试覆盖 |
|---------|-------------|---------|---------|---------|
| 功能1 | B-1, F-1 | GET /api/x | 页面A §5.2.1 | 后端单元 + 前端组件 |
| 功能2 | B-2, F-2 | POST /api/y | 页面B §5.2.2 | 后端集成 + 前端单元 |

## 八、风险评估
### 8.1 技术风险
### 8.2 兼容风险
### 8.3 资源风险

## 九、附录
### 9.1 参考文档清单
### 9.2 术语表

9.3 自检（一次 subagent 审查）

读取 references/tech-design-reviewer-prompt.md，传入文档路径派发 subagent。

状态	处理
通过	进入用户确认
发现问题	修复后无需重审

9.4 用户确认

技术方案已完成。请确认：

• 变更清单是否完整且具体？每个变更的"当前状态"和"具体修改"是否清晰？
• 架构与数据模型是否合理？
• API 是否满足需求？
• 前端设计是否覆盖需求页面清单的每一项？
• 测试策略是否可行（单元+必要集成，不含 E2E）？

9.5 产出交接清单

确认后，产出交接清单并宣布进入 implementation-planning：

技术方案已完成并确认。进入 implementation-planning 时请携带以下信息：

交接清单：

• 技术方案路径：workplace/1.X/tech-design/YYYY-MM-DD-xxx.md
• 变更数量：后端N项、前端M项、数据模型K项
• 前端页面数量：N个（列出编号）
• 测试策略摘要：[单元为主/关键路径集成]
• 特别关注点：[用户强调的内容]

implementation-planning 第一步应确认对这些内容的理解。

---

渐进式验证原则

本skill采用渐进式验证，核心原则：

• 分阶段确认：每个主要设计阶段结束后确认，而非最后统一确认
• 一次确认一个主题：避免同时确认多个复杂内容，降低认知负担
• 确认内容具体化：列出具体项让用户确认，而非抽象问"是否满意"
• 允许回溯调整：用户不满意时可返回该阶段调整，不影响后续阶段

---

工作原则

• 文档先行：参考文档准备完成前不得开始设计
• Delta 分析优先：变更清单是设计的唯一输入；没有 Delta 分析，方案就会退化为复述
• 基于需求：方案必须完全覆盖需求功能清单
• 测试聚焦：以单元测试为主，仅在关键路径补充集成测试，不做 E2E
• 前后端均覆盖：前端设计章节缺失或漏页 = 审核必拒
• 风险意识：每个设计决策都考虑潜在风险

特殊情况

• 需求过大：建议拆分子方案，先做哪个？
• 技术选型分歧：列对比表给出 2-3 方案，让用户选
• 文档无法获取：用户提供 / 探索现有代码 / 推迟该功能
• 现有代码复杂：聚焦核心接口与数据模型，忽略实现细节；分层探索（接口 → 数据 → 业务）