/product-feature-tech-design

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` — 测试矩阵子模板,深化"验收标准"章节时使用。