---
name: product-feature-tech-design
description: 将 PRD 翻译成「可独立测试」的功能设计文档。文档的下游使用者包括开发者、评审者、测试者,且三方互相隔离(测试者看不到开发者写的代码),所以必须把行为、状态、接口、数据、权限、异常、验收标准全部显式化,让测试者能独立从文档推导用例。输入是一份已写好的 PRD 文档,输出是一份完整的 Markdown 功能设计文档,保存到当前项目的 `markdown/` 目录。适用于:写功能设计文档、技术设计文档、Tech Design、详细设计说明书、FDD、Functional Design Doc、Detailed Design、模块设计文档、把 PRD 翻译成开发设计、把需求拆成可开发/可测试/可评审的规格。
---

# Product Feature Tech Design

## 核心约束(决定一切)

**测试者看不到开发者的代码**。功能设计文档是三方的唯一共同依据:

| 角色 | 从文档里读什么 | 看不到 |
|---|---|---|
| 开发者 | 接口契约、数据模型、行为规则、边界条件 | — (有文档) |
| 评审者 | 设计原则、权衡取舍、验收标准 | — (有文档) |
| 测试者 | 用例推导的完整基础 | 开发者的源代码 |

→ 文档必须**把行为写死**,不留给实现者自由发挥的空间;同时**不规定实现细节**(避免越界成架构图)。这条边界是这份文档的灵魂。

## 输入

- 一份 PRD 文档(本项目 `markdown/` 下,或用户提供的路径)。
- 用户的额外约束(若有):技术栈、性能指标、合规要求等。

如果输入没有 PRD,先停下来问用户要 PRD,不要凭空白生成功能设计文档。

## 工作流

1. **通读 PRD 并提取产物**
   - 目标用户、核心场景、成功指标、范围切片。
   - 所有功能模块、用户故事、边界条件、权限点。
   - 显式列出 PRD 中**没说清**的地方,作为"待确认项"记入文档,不擅自补全。

2. **按 `references/feature-design-template.md` 起骨架**
   - 不要跳过任何章节。允许"本章不适用"标注,但不能整章删除。
   - 每章用 PRD 中的事实填充,缺数据时标"待确认",不要瞎编。

3. **深化关键章节(优先级从高到低)**
   - **接口规格** → 读 `references/api-spec-template.md`,每个端点都给出:请求/响应字段表、错误码表、幂等性、限流、鉴权点。
   - **状态机** → 读 `references/state-machine-template.md`,每个实体都要画出状态转移图,包括非法转移。
   - **测试矩阵** → 读 `references/test-matrix-template.md`,用维度(角色 × 操作 × 数据状态 × 环境)穷举测试面,测试者直接按矩阵写用例。

4. **验收标准必须可执行**
   - 全部用 Given/When/Then 写,每条只测一个点。
   - 包含:正常路径、异常路径、权限路径、数据边界、并发/超时、跨模块交互。
   - 性能/可用性指标给出**具体数值**(p99 ≤ 200ms、错误率 < 0.1%),不给"较快"。

5. **自检**(见下方质检清单)
   - 如果任一项不过,补完后再交付。

6. **保存**
   - 路径:`markdown/<topic>-feature-design-<YYYYMMDD>.md`
   - 如果生成了 SVG 图,保存为 `markdown/<topic>-<diagram-name>-<YYYYMMDD>.svg`,在文档中用相对路径引用。

## 文档与下游的契约

### 给开发者(可实现)

- 完整的数据模型:实体、字段、类型、约束、生命周期、索引建议。
- 完整的接口契约:路径、方法、入参/出参/错误码、幂等、限流、鉴权。
- 业务规则用自然语言 + 决策表 / 伪代码,**不规定框架、不规定语言、不规定文件结构**。
- 状态机:所有合法/非法状态转移。
- 依赖关系:对外部模块/服务的契约要求。

### 给评审者(可检查)

- 设计决策与备选方案(为什么选 A 不选 B)。
- 非功能性指标(性能、可用性、安全、可观测性)的具体数值。
- 与 PRD 的对齐情况(每条 PRD 需求都有对应设计章节)。
- 风险点与缓解措施。

### 给测试者(可独立写用例,**最关键的读者**)

- 每个功能的**前置条件**、**操作步骤**、**期望结果**(逐字段,不要"返回成功"这种模糊描述)。
- **输入数据矩阵**:合法、非法、边界值(0、最大值、Unicode、SQL 注入字符、超长字符串等)。
- **状态前置**:基于哪一状态才能触发此操作。
- **并发与时序**:重入、双击、过期、跨时钟。
- **错误码表**:每种错误码对应的触发条件 + 用户可见提示。
- **不变量**:无论什么操作,系统都应保持的性质(如"用户余额永远 ≥ 0")。

## 质检清单(交付前自检)

- [ ] 每个 PRD 中的功能点都能在文档中找到对应章节。
- [ ] 每个对外接口都有完整的请求/响应/错误码表。
- [ ] 每个有状态的实体都有状态机图,且包含非法状态。
- [ ] 每条业务规则都用 Given/When/Then 或决策表表达,无歧义。
- [ ] 测试矩阵覆盖:角色 × 操作 × 数据状态 × 环境,且每个单元格都有预期结果。
- [ ] 性能/可用性指标都有具体数值,不是"较快/较稳定"。
- [ ] 权限矩阵明确:每个角色对每个资源的可见/可操作/不可操作。
- [ ] 至少 1 张图(系统上下文、流程、状态机、时序均可,优先 Mermaid)。
- [ ] "待确认项"清单存在,每项都标明对哪条设计有影响。
- [ ] 文档不规定具体语言/框架/库/目录结构(只规定行为和契约)。

## 输出

- 一份 Markdown 文件,保存到当前项目 `markdown/` 目录(不存在则创建)。
- 文件名:`<topic>-feature-design-<YYYYMMDD>.md`,其中 `<topic>` 用 PRD 的主题拼音/英文 slug。
- 文档用中文(除非用户要求其他语言)。
- 文档长度没有硬性上限,但应**详尽到让测试者能独立写用例**为准;不要为简洁而省略边界。

## 参考资料

- `references/feature-design-template.md` — 完整模板(16 章节),骨架必读。
- `references/api-spec-template.md` — 接口契约子模板,深化"对外接口"章节时使用。
- `references/state-machine-template.md` — 状态机子模板,深化"状态机"章节时使用。
- `references/test-matrix-template.md` — 测试矩阵子模板,深化"验收标准"章节时使用。