技术方案设计
基于需求文档产出完整技术方案。核心原则：文档先行；前后端并行；测试聚焦单元与必要集成。
版本号约定
1.X 为占位符，详见 requirements-workshop/SKILL.md。真实路径必须替换为具体数字（如 workplace/1/references/）。
前后端联合设计原则
技术方案必须同时覆盖：
- 后端：架构、数据模型、API、服务、权限
- 前端：页面结构、路由、组件、状态管理、API 接入、关键交互
- 测试：后端单元/集成测试、前端单元/组件测试
需求文档"页面/界面清单"必须在技术方案中逐项有对应前端设计。遗漏前端是审核必拒项。
工作流程（精简为 6 步）
- 读取需求文档（含功能清单 + 页面清单）
- 区分新/旧功能 → 准备技术文档（新功能：参考文档；旧功能：技术栈说明）→ 存入
workplace/1.X/references/ - 设计架构 + 数据模型 + API
- 设计前端（路由/页面/组件/状态/API 接入）
- 制定测试策略（单元为主，必要集成）
- 产出技术方案 → 自检 → 用户确认 → 进入
implementation-planning
第一步：读取需求文档
从 workplace/1.X/requirements/ 读取最近的需求文档。
- 若不存在：提示用户先做 requirements-workshop 或提供文档路径
- 若有多个：列出最近 3 个让用户选择
提取功能清单与页面清单。
第二步：准备参考文档
2.1 区分功能类型
| 分类 | 定义 | 文档要求 |
|---|---|---|
| 新功能 | 项目无类似实现，引入新技术/模块 | 必须有参考文档 |
| 旧功能扩展 | 基于现有代码扩展 | 必须有技术栈说明 |
| 旧功能复用 | 直接调用现有功能 | 无需额外文档 |
判断方法：搜索现有代码 → 检查技术栈 → 与用户确认。
2.2 输出技术文档需求清单（用户确认后再继续）
## 技术文档需求清单
### 新功能（需要参考文档）
| 功能 | 文档类型 | 来源建议 | 状态 |
### 旧功能扩展（需要技术栈说明）
| 功能 | 涉及模块 | 文档要求 | 状态 |
### 文档存放位置：workplace/1.X/references/
- 参考文档：`{技术名}-reference.md`
- 技术栈说明：`{模块名}-techstack.md`
- 前端 UI 库参考：`{库名}-frontend-reference.md`2.3 收集 / 整理文档
新功能参考文档模板（核心字段）：基本信息（链接/版本/引入方式）、核心概念、API 参考（用途/参数/返回/示例）、最佳实践、注意事项、与本项目关联。 收集方式：Context7 MCP / WebFetch/WebSearch / 用户提供 / 现有代码探索。
旧功能技术栈说明模板：模块定位、代码结构、数据模型、API 接口、依赖关系、扩展点、注意事项。
2.4 验证清单
| 检查项 | 要求 |
|---|---|
| 目录存在 | workplace/1.X/references/ 已创建 |
| 新功能文档 | 每个新功能都有参考文档 |
| 旧功能文档 | 每个旧功能扩展都有技术栈说明 |
通过后宣布：> 技术文档准备完成，开始技术方案设计。
第三步：架构 + 数据模型 + API
3.1 架构设计
| 章节 | 内容 |
|---|---|
| 系统架构图 | 模块划分、层次、依赖（Mermaid graph） |
| 技术选型 | 各模块技术栈与理由 |
| 部署架构 | 部署方式、网络拓扑（如适用） |
| 数据流向 | 数据在模块间流转 |
3.2 数据模型
每个实体描述字段（名/类型/必填/默认/说明）、约束、索引、迁移计划（若有）。
### {实体名}
| 字段 | 类型 | 必填 | 默认 | 说明 |
| id | UUID | 是 | 自动 | 主键 |3.3 API 设计
接口清单 + 每个接口的：路径与方法、描述、认证、请求参数表、请求示例、响应字段表、响应示例、错误码。
第四步：前端设计（强制）
针对需求文档"页面/界面清单"，逐项给出前端实现设计。任何遗漏都会让需求功能在实施阶段消失。
4.1 设计内容
| 章节 | 内容 |
|---|---|
| 路由结构 | 所有路由及层级（含权限/守卫） |
| 页面设计 | 每页布局、组件、数据来源、状态机 |
| 组件清单 | 复用组件、第三方组件库选型 |
| 状态管理 | 方案选型（Pinia/Redux/Zustand）+ store 划分 |
| API 接入 | 调用哪些后端接口、错误处理、loading/重试 |
| 关键交互 | 表单校验、上传下载、分页等 |
4.2 页面设计模板
### 页面：{页面名}（路由：{path}）
- **对应需求功能**：[功能编号/名称]
- **布局**：[结构示意]
- **关键组件**：[列表]
- **数据来源**：[API/本地状态]
- **状态机**：初始 / 加载中 / 空 / 错误 / 成功
- **交互细节**：[校验、跳转、二次确认]
- **权限**：[未登录/无权限处理]4.3 覆盖核查表（必做）
列一张表：左列=需求文档"页面清单"每一行，右列=本方案"页面设计"对应章节锚点。任意缺失即返工。
第五步：测试策略（聚焦单元，必要集成）
5.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列出运行命令：单测、集成、覆盖率
5.2 测试策略内容
| 章节 | 内容 |
|---|---|
| 测试范围 | 哪些功能需要测试（前后端均需列出） |
| 测试类型 | 单元测试（主）+ 关键集成测试 |
| 测试数据 | fixtures 准备方式 |
| 覆盖率目标 | 后端/前端分别的目标 |
| 运行命令 | 各类测试命令（写入 test/README.md） |
5.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 不做端到端测试。如确有强需求，由用户单独提出后另行规划，不在本方案默认范围内。
第六步：产出技术方案文档
6.1 命名与存储
命名：YYYY-MM-DD-{需求名称}-技术方案.md 存储：workplace/1.X/tech-design/
6.2 模板
# {需求名称} 技术方案
> 需求文档：[路径]
> 技术参考：workplace/1.X/references/
## 一、架构设计
### 1.1 系统架构图（含前后端分层）
### 1.2 技术选型
### 1.3 部署架构（如适用）
## 二、数据模型
### 2.1 实体定义
### 2.2 关系图
### 2.3 索引设计
## 三、API 设计
### 3.1 接口清单
### 3.2 接口详情
## 四、前端设计
### 4.1 路由结构
### 4.2 页面设计
### 4.3 组件清单
### 4.4 状态管理
### 4.5 API 接入与错误处理
### 4.6 覆盖核查表（需求页面清单 → 本章节锚点）
| 需求页面 | 路由 | 对应章节 |
## 五、测试策略
### 5.1 测试目录（workplace/1.X/test/，单元为主+必要集成，不做 E2E）
### 5.2 测试范围（前后端分别列出）
### 5.3 测试类型与工具
### 5.4 覆盖率目标
### 5.5 运行命令
## 六、风险评估
### 6.1 技术风险
### 6.2 兼容风险
### 6.3 资源风险
## 七、附录
### 7.1 参考文档清单
### 7.2 术语表6.3 自检（一次 subagent 审查）
读取 references/tech-design-reviewer-prompt.md，传入文档路径派发 subagent。
| 状态 | 处理 |
|---|---|
| 通过 | 进入用户确认 |
| 发现问题 | 修复后无需重审 |
6.4 用户确认
技术方案已完成。请确认： - 架构与数据模型是否合理？ - API 是否满足需求？ - 前端设计是否覆盖需求页面清单的每一项？ - 测试策略是否可行（单元+必要集成，不含 E2E）？
确认后：> 下一步使用 implementation-planning 拆分可执行模块清单。
工作原则
- 文档先行：参考文档准备完成前不得开始设计
- 基于需求：方案必须完全覆盖需求功能清单
- 测试聚焦：以单元测试为主，仅在关键路径补充集成测试，不做 E2E
- 前后端均覆盖：前端设计章节缺失或漏页 = 审核必拒
- 风险意识：每个设计决策都考虑潜在风险
特殊情况
- 需求过大：建议拆分子方案，先做哪个？
- 技术选型分歧：列对比表给出 2-3 方案，让用户选
- 文档无法获取：用户提供 / 探索现有代码 / 推迟该功能
- 现有代码复杂：聚焦核心接口与数据模型，忽略实现细节；分层探索（接口 → 数据 → 业务）