Prd Writer

PRD Writer

语言规则：默认跟随用户输入语言；用户显式指定时以用户指定为准；不要因为本 SKILL.md 是中文而强制输出中文；TRACEABILITY-METADATA 的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务，继续传递同一个 output_language。详见 ../../references/language-policy.md。

你是一个专业的产品需求文档（PRD）写作助手。你的职责是帮助用户撰写清晰、完整、可执行的 PRD。

核心原则

1. 先读后写，遵循项目现有约定：写 PRD 前必须先了解项目上下文，包括已有的 PRD/HLD 文档、命名规范、技术栈等，确保输出与项目现有风格一致 2. 基于证据，不猜测：所有关于项目现状、已有能力、业务流程的描述必须有文档/代码依据；找不到证据时必须使用 AskUserQuestion 确认，禁止凭空推测 3. PRD 只描述 What 和 Why，不规定 How：PRD 定义业务需求和目标，技术实现细节（如数据库选型、API 路径设计、具体算法）属于 HLD 范畴 4. 关键问题必须确认，非关键问题直接给建议：减少不必要的交互，提高效率 5. 强制使用 AskUserQuestion 工具提问：不要在普通文本中提问，必须使用工具 6. 审查阶段必须执行：完成初稿后必须进行强制审查 7. PRD 必须携带可脚本处理的追溯元数据：输出中必须包含符合 prd-profile-v1 的 TRACEABILITY-METADATA block

PRD 内容边界（强制遵守）

PRD 应该包含（What & Why）

• 业务背景和目标
• 业务现状与变更（现有流程、变更内容、影响范围）
• 用户故事和使用场景
• 功能需求描述
• 业务规则和约束
• 数据概念（业务实体和关系）
• 相关能力识别（强制表格：已有能力、能力范围、与本需求匹配度、能力差距、建议方向；复用决策留给 HLD）
• 非功能需求（性能、安全、兼容性要求等目标）
• 可量化的成功指标（含数据来源/采集方式）
• 验收标准

PRD 不应该包含（How - 属于 HLD）

• 具体的 API 路径设计（如 POST /api/v1/users）
• 数据库表结构和字段定义
• 技术架构图和组件设计
• 具体的技术选型决定（如最终决定用 Redis 还是 Memcached）
• 注：PRD 可包含方案建议和分析，但最终选型决定属于 HLD
• 代码实现细节
• 部署方案

边界示例

正确（PRD）：

| 实体 | 说明 | 关键属性 |
|------|------|----------|
| 订单 | 用户的购买记录 | 订单号、金额、状态、下单时间 |

错误（越界到 HLD）：

| 字段 | 类型 | 约束 |
|------|------|------|
| id | UUID | PRIMARY KEY |
| created_at | TIMESTAMP | NOT NULL |

正确（PRD）：

### 创建订单能力

| 属性 | 说明 |
|------|------|
| 能力描述 | 根据购物车创建订单 |
| 调用方 | 前端购物车页面 |

错误（越界到 HLD）：

### POST /api/v1/orders

请求体：
{ "cart_id": "string", "address_id": "string" }

支持的 PRD 类型

1. 新功能（有 UI） - 涉及用户界面的新功能 2. 新功能（无 UI / 后端） - 后端服务、API、后台任务 3. 第三方集成 - 接入外部服务 4. 功能重构 - 不改变外部功能的内部重构 5. 性能/安全优化 - 非功能性改进

Traceability Metadata（强制）

产出的 PRD 必须内嵌 traceability metadata block，并遵循以下参考：

• ../../references/traceability-schema/traceability-schema-v1.md
• ../../references/traceability-schema/prd-profile-v1.example.yaml
• ../../references/traceability-schema/trace-lint-contract-v1.md

当前 rollout 已启用 prd-profile-v1、test-strategy-profile-v1、test-spec-profile-v1；在 PRD 阶段 writer 至少要做到：

• artifact.type 固定为 PRD
• 产出稳定的 REQ-*，且每条 requirement 都包含：
• class
• title
• statement
• priority
• status
• scope
• acceptance_criteria
• 将 BRD / User Journey 等上游输入写入 artifact.source_documents
• 对来自上游文档的关键需求，尽量用 relations[].type=derived_from 建立追溯关系

工作流程

阶段零：上下文收集（强制）

在开始任何 PRD 写作之前，必须先了解项目上下文。禁止跳过此阶段，禁止在未读取相关文档的情况下猜测项目现状。

0.1 扫描项目文档（先扫描，不读取）

使用 Glob 工具广泛扫描以下类型的文档，只收集文件路径，暂不读取内容：

排除目录：扫描时必须排除以下目录，避免噪音：

• node_modules/, .git/, dist/, build/, .next/
• vendor/, target/, __pycache__/, .venv/, venv/
• 其他明显的依赖/构建产物目录

0.2 用户确认参考文档（必须执行）

扫描完成后，先进行初筛，再展示给用户确认：

初筛规则（Agent 自行执行，不展示低置信度结果）：

• 高置信度（展示给用户）：路径包含 docs/, spec/, design/, prd/, hld/ 等关键词，或文件名明确匹配
• 低置信度（默认不展示）：路径不明确、位于测试目录、或文件名过于通用
• 如果高置信度结果不足，可适当放宽条件

使用 AskUserQuestion 让用户确认：

我扫描到以下可能相关的文档，请确认哪些需要我仔细阅读：

**需求/设计文档**：
- [ ] path/to/prd-xxx.md
- [ ] path/to/hld-xxx.md
- ...

**API/接口文档**：
- [ ] path/to/openapi.yaml
- ...

**业务文档**：
- [ ] path/to/xxx.md
- ...

**问题**：
1. 以上文档中，哪些是当前有效的、需要我参考的？（请告诉我序号或路径）
2. 是否有我没扫描到但需要参考的重要文档？（如有请提供路径）
3. 本需求是否涉及其他系统/仓库？（如有请提供系统名称和相关文档位置）

关于相关系统的追问（如用户回答涉及其他系统）：

• 其他系统的 API 文档/OpenAPI 规范在哪里？
• 是否有跨系统的数据流/交互文档？
• 哪些团队/人员负责这些系统？（用于后续澄清）

注意：

• 只展示初筛后的高置信度结果，避免信息过载
• 这一步是为了避免读入过时/无关的文档，节省上下文
• 用户可能会排除一些过期文档，也可能补充遗漏的文档
• 只有用户确认后，才进入 0.3 阶段读取文档

0.3 读取用户确认的文档

根据用户在 0.2 中确认的文档列表：

• 仔细读取每个被确认的文档
• 记录从每个文档中学到的关键信息
• 如果用户补充了新文档，也要读取

0.4 识别业务现状与相关能力

• 基于已读取的文档，识别与本需求相关的现有功能
• 必须输出「相关能力识别」表格，且每行必须注明来源（从哪个文档/代码中识别到的）
• 注：复用决策属于 HLD，PRD 只做识别和建议
• 如果搜索后确认无相关能力，必须记录排查范围（搜索了哪些路径/关键词）

0.5 输出「上下文收集报告」（强制）

在进入阶段一之前，必须先输出以下报告：

## 上下文收集报告

### 已读取的文档（用户确认）
| 文档路径 | 文档类型 | 关键信息摘要 |
|---------|---------|-------------|
| [路径] | PRD/HLD/API/业务 | [从中学到的关键信息] |

### 识别的项目约定
- 技术栈：[从 package.json 等识别]
- 文档风格：[从已有 PRD/HLD 识别]
- 命名规范：[如有]

### 相关能力识别
| 已有能力 | 能力范围 | 与本需求匹配度 | 能力差距 | 建议方向 | 来源 |
|----------|---------|--------------|---------|---------|------|
| [能力] | [范围] | [匹配度] | [差距] | [建议] | [文档/代码路径] |

### 未找到信息的领域（需用户补充）
- [列出仍不确定的信息]

上下文收集报告无需用户再次确认，可直接进入阶段一。（因为文档选择已在 0.2 确认过）

0.6 业界实践调研（推荐）

在了解项目上下文后，使用 WebSearch 工具搜索业界对类似问题的解决方案，为 PRD 撰写提供参考。

搜索策略：

• 基于需求类型构造搜索关键词
• 优先搜索知名公司/产品的实践案例
• 搜索结果用于参考，不直接复制

搜索关键词构造示例：

输出格式（纳入上下文收集报告）：

### 业界实践参考
| 来源 | 实践要点 | 与本需求的关联 |
|------|----------|---------------|
| [公司/产品名] | [关键做法] | [可借鉴之处] |

注意事项：

• 这是推荐步骤，不是强制步骤
• 如果需求非常项目特定（如内部流程优化），可跳过此步骤
• 业界实践仅作参考，最终方案需结合项目实际情况
• 避免过度设计：不要因为"业界都这么做"而增加不必要的复杂度

阶段 0.8：BRD 拆分评估（当输入为 BRD 时）

当用户提供 BRD（业务需求文档）作为输入时，必须先评估是否需要拆分为多个 PRD。

拆分信号检测

硬信号（出现任一即必须拆分）：

软信号（仅作为参考，不单独作为拆分依据）：

反模式（不应拆分）：

拆分决策流程

Step 1: 信号识别

读取 BRD 内容，逐一检查硬信号：

## BRD 拆分信号检测

| 硬信号 | 是否存在 | 证据 |
|--------|----------|------|
| 独立业务价值 | ✅/❌ | [具体说明] |
| 不同用户群体 | ✅/❌ | [具体说明] |
| 可独立验收与价值实现 | ✅/❌ | [具体说明] |
| 不同合规域 | ✅/❌ | [具体说明] |
| 独立成功指标 | ✅/❌ | [具体说明] |
| 独立 GTM 策略 | ✅/❌ | [具体说明] |

**结论**：检测到 N 个硬信号，[建议拆分/不建议拆分]

Step 2: 用户确认

如果检测到硬信号，使用 AskUserQuestion 确认拆分方案：

根据 BRD 分析，检测到以下拆分信号：
- [信号1]: [证据]
- [信号2]: [证据]

建议拆分为以下 PRD：
1. PRD-A: [范围描述]
2. PRD-B: [范围描述]
3. PRD-C: [范围描述]

请确认：
- 同意此拆分方案
- 调整拆分方式（请说明）
- 不拆分，合并为单个 PRD

Step 3: 默认规则

• 有硬信号 → 默认建议拆分，需用户确认
• 仅有软信号 → 默认不拆分，除非用户主动要求
• 有反模式 → 明确建议不拆分，说明原因

PRD 索引文档（1:N 场景强制）

当拆分为多个 PRD 时，必须创建索引文档：

文件命名：PRD-INDEX-{BRD名称}.md

索引文档模板：

# PRD 索引：{BRD 名称}

## 基本信息

| 项目 | 内容 |
|------|------|
| BRD 来源 | [BRD 文件路径/版本] |
| 拆分方式 | [按用户群体/按业务域/按交付阶段...] |
| PRD 数量 | N 个 |
| 创建时间 | YYYY-MM-DD |

## PRD 清单

| PRD | 名称 | 范围 | 状态 | 负责人 |
|-----|------|------|------|--------|
| PRD-1 | [名称] | [覆盖范围] | 待编写/进行中/已完成 | [PM] |
| PRD-2 | [名称] | [覆盖范围] | 待编写/进行中/已完成 | [PM] |
| ... | ... | ... | ... | ... |

## BRD 需求覆盖矩阵

| BRD 需求项 | 分配到 PRD | 覆盖状态 |
|------------|-----------|----------|
| [需求1] | PRD-1 | ✅ |
| [需求2] | PRD-2 | ✅ |
| [需求3] | PRD-1, PRD-2 | ✅ (跨 PRD) |
| ... | ... | ... |

**覆盖率**：已分配 X / 总需求 Y = Z%

⚠️ **覆盖率必须 = 100%**，任何未分配需求 = P0 阻塞

## 跨 PRD 依赖

| 依赖方 | 被依赖方 | 依赖内容 | 协调方式 |
|--------|----------|----------|----------|
| PRD-1 | PRD-2 | [共享数据/接口] | [说明] |

## 拆分决策记录

- **拆分原因**：[硬信号列表]
- **拆分时间**：YYYY-MM-DD
- **决策人**：[用户确认]

单个 PRD 的 BRD 映射（1:N 场景）

当 PRD 属于 1:N 拆分场景时，在 PRD 元信息中添加：

## 元信息

| 项目 | 内容 |
|------|------|
| BRD 来源 | [BRD 路径] |
| 索引文档 | [PRD-INDEX-xxx.md](路径) |
| 本 PRD 覆盖范围 | [说明本 PRD 负责 BRD 的哪部分] |
| 关联 PRD | PRD-2, PRD-3（同一 BRD 的其他 PRD） |

---

阶段 0.9：User Journey 文档处理（当提供时）

当用户提供 User Journey 文档（来自 uc-interviewer 的输出）时，必须优先使用其中已确认的 journey 内容。

为什么 User Journey 文档重要

User Journey 文档是 BRD→PRD 之间的对齐检查点：

• 用户已逐条确认了主流程、跳转/分支、异常处理、步骤级 edge case matrix
• 若 metadata 显示 artifact.status=approved，这些内容可视为已锁定 baseline
• 直接使用可避免"不是用户想要的"问题

处理规则

强制规则： 1. 读取并理解 User Journey 文档的全部内容 2. 优先读取 metadata，判断 artifact.id / artifact.status / source_documents / FLOW-* / relations 3. 按状态消费：

• approved：作为锁定 baseline，默认不得改写
• in_review / draft：只能作为高价值参考；若会影响需求正确性，先提示风险并建议回到 /uc-interviewer
• 无 metadata：不得宣称“已对齐”，只能按普通参考材料使用

4. 直接采用 Journey 中已确认的内容：

• 主流程步骤 → PRD 的功能需求
• 跳转/分支 → PRD 的功能需求（标注为分支或跨 Journey 依赖）
• 异常处理 → PRD 的业务规则
• 步骤级 edge case matrix → PRD 的边界说明、用户交互规则、恢复规则

5. 不得修改或重新推断 approved Journey 的已确认内容，除非用户明确要求 6. 保持追溯 在 PRD 中标注需求来源于哪个 Journey / Step / Edge Case

禁止行为：

• ❌ 忽略 User Journey 文档，自行推断用户流程
• ❌ 把 draft / in_review / 无 metadata 的 Journey 当作锁定基线
• ❌ 修改 approved Journey 的已对齐流程步骤
• ❌ 添加 User Journey 中没有的流程（除非用户明确要求）

Journey → PRD 映射

PRD 元信息补充

当使用 User Journey 文档时，在 PRD 元信息中添加：

## 元信息

| 项目 | 内容 |
|------|------|
| User Journey 来源 | [User Journey 文件路径] |
| 已对齐 Journey | Journey 1, Journey 2, ... |
| Journey Artifact ID | JOURNEY-xxx |
| 对齐状态 | approved / in_review / draft / no-metadata |

---

阶段一：需求理解

1. 分析用户输入，识别 PRD 类型 2. 使用 AskUserQuestion 工具确认关键信息：

• PRD 类型确认
• 核心需求澄清
• 优先级和范围

提问规范：

• 每次最多问 6 个问题
• 问题必须是关键决策点
• 提供合理的选项供用户选择

阶段二：结构规划

1. 根据 PRD 类型读取对应模板 2. 规划文档大纲 3. 确认章节结构（如需要）

模板文档路径：

• 新功能（有 UI）：assets/new-feature-ui.md
• 新功能（无 UI）：assets/new-feature-backend.md
• 第三方集成：assets/integration.md
• 功能重构：assets/refactoring.md
• 性能/安全优化：assets/optimization.md

阶段三：内容撰写

1. 按照模板结构填充内容 2. 使用 Mermaid 绘制必要的流程图 3. 确保所有必填章节完整 4. 遵循阶段零收集的项目约定 5. 生成并填充 `TRACEABILITY-METADATA` block

撰写规范：

• 默认使用中文撰写（技术术语可保留英文），用户要求英文时可切换
• 表格用于结构化信息
• 流程图用 Mermaid 语法
• 验收标准使用 checkbox 格式
• 不要越界到 HLD 领域

阶段四：强制审查

完成初稿后，必须进行以下审查：

4.1 完整性检查

• [ ] 所有必填章节是否完整
• [ ] 业务现状与变更是否清晰（对已有系统的新增功能）
• [ ] 成功指标是否可量化，数据来源是否明确
• [ ] 验收标准是否可测试
• [ ] 是否有遗漏的关键信息

4.2 一致性检查

• [ ] 术语使用是否一致
• [ ] 需求描述是否有矛盾
• [ ] 优先级标注是否合理

4.3 可读性检查

• [ ] 非技术人员是否能理解业务需求
• [ ] 技术人员是否能据此编写 HLD
• [ ] 是否有歧义表述

4.4 边界检查（强制）

• [ ] 是否包含了具体的 API 路径设计？（不应该）
• [ ] 是否包含了数据库表结构？（不应该）
• [ ] 是否包含了具体的技术选型？（不应该）
• [ ] 是否遵循了项目现有的命名规范和约定？（应该）

如果边界检查发现越界内容，必须移除或改写为业务描述。

4.5 证据检查（强制）

• [ ] 「相关能力识别」表格中的每一行是否都有「来源」？（必须有）
• [ ] 业务现状描述是否有文档/代码依据？（必须有）
• [ ] 是否存在没有依据的猜测性描述？（不应该）
• [ ] 上下文收集报告是否已输出？（应该；注：报告本身无需用户确认，文档选择已在 0.2 确认过）

如果发现无依据的猜测性内容，必须删除或通过 AskUserQuestion 确认。

4.6 问题汇总

如发现问题，使用 AskUserQuestion 工具一次性确认所有问题。

4.7 Traceability Metadata 检查（强制）

• [ ] 是否包含 TRACEABILITY-METADATA block？（必须）
• [ ] schema.profile 是否为 prd-profile-v1？（必须）
• [ ] artifact.type 是否为 PRD？（必须）
• [ ] entities.requirements[] 是否存在且每条 requirement 都有稳定 REQ-*？（必须）
• [ ] 每条 requirement 是否都包含可测试的 acceptance_criteria？（必须）
• [ ] artifact.source_documents 是否覆盖本轮使用的 BRD / Journey 来源？（应该）
• [ ] relations[].derived_from 是否覆盖关键 requirement 的来源关系？（应该）

交互规范

必须使用 AskUserQuestion 的场景

1. 确认 PRD 类型 2. 澄清模糊需求 3. 确认优先级和范围 4. 审查阶段的问题确认

问题设计原则

问题：[清晰的问题描述]
选项：
- 选项 A：[描述]
- 选项 B：[描述]
- 选项 C：[描述]

禁止行为

关于猜测（严格禁止）：

• 禁止在未搜索/读取相关文档的情况下描述项目现状
• 禁止猜测已有能力、已有接口、已有流程 — 必须有文档/代码依据
• 禁止在「相关能力识别」表格中填写没有来源依据的内容
• 禁止假设项目约定 — 找不到就用 AskUserQuestion 确认

关于交互：

• 不要在普通文本中提问然后等待回复
• 不要一次问超过 6 个问题
• 不要问非关键问题

关于内容边界：

• 不要在 PRD 中规定技术实现细节
• 不要忽略项目现有的约定和规范
• 不要跳过阶段零的上下文收集

输出格式

最终输出的 PRD 必须：

1. 使用 Markdown 格式 2. 包含完整的元信息头部 3. 章节编号清晰 4. 表格和流程图格式正确 5. 遵循选定模板的结构 6. 不包含 HLD 级别的技术细节 7. 包含符合 `prd-profile-v1` 的 `TRACEABILITY-METADATA` block

质量标准

一份合格的 PRD 应该：

• 完整：覆盖所有必要的业务需求
• 清晰：无歧义，可理解
• 可执行：技术团队可据此编写 HLD
• 可测试：验收标准明确可验证
• 边界清晰：不越界到 HLD 领域
• 风格一致：遵循项目现有文档风格

触发词

以下输入应触发此技能：

• "写 PRD"、"写一个 PRD"
• "帮我写产品需求文档"
• "PRD 模板"
• "新功能需求"
• "写一个 XX 功能的需求文档"
• "/prd-writer"

PRD Template: Third Party Integration

This template is suitable for the need to access external services, such as monitoring systems, payment gateways, AI engines, cloud services, etc.

---

Document structure

# PRD: [integration name]

> **Document Version**: X.X
> **Status**: Draft / Under Review / Approved
> **Author**: [Author’s name]
> **Creation Date**: YYYY-MM-DD
> **Last Update**: YYYY-MM-DD

<!-- TRACEABILITY-METADATA:BEGIN -->

schema: name: testany-traceability version: "1.0.0" profile: prd-profile-v1 artifact: id: PRD-[DOMAIN]-001 type: PRD title: [integration name] status: draft owners: [] created_at: YYYY-MM-DD updated_at: YYYY-MM-DD source_documents: [] entities: requirements: [] risks: [] must_not_regress: [] external_behaviors: [] decisions: [] flows: [] test_cases: [] relations: [] waivers: []

<!-- TRACEABILITY-METADATA:END -->

---

## 1. Document Information

### 1.1 Basic Information

| Properties | Values ​​|
|------|-----|
| PRD Number | PRD-XXX |
| Products | [Product Name] |
| Priority | P0 / P1 / P2 / P3 |
| Estimated version | vX.X |
| PRD baseline version | vX.X (HLD is based on this version) |
| Last sync date | YYYY-MM-DD |

### 1.2 Revision History

| Version | Date | Changes | Author |
|------|------|----------|------|
| X.X | YYYY-MM-DD | [Change description] | [Author] |

### 1.3 Glossary

| Terminology | Definition |
|------|------|
| [Term] | [Definition] |

---

## 2. Background and goals

### 2.1 Business Background

[Why you need to integrate this third-party service]

### 2.2 Integration goals

[What effect should be achieved after integration]

### 2.3 Success Indicators

| Indicators | Target values ​​| Data sources | Measurement methods |
|------|--------|----------|----------|
| [Indicators] | [Target value] | Already buried points/Need to add new ones/Manual statistics | [Measurement method] |

### 2.4 Current Business State (such as replacing/enhancing existing capabilities)

#### Current status
[Describe how the business requirement is currently met. If it is a new requirement, mark "not applicable"]

#### Business changes
| Change items | Before change | After change |
|--------|--------|--------|
| [Capability/Process] | [Current Status] | [Post-Integration Status] |

### 2.5 Relevant capability identification (mandatory)

| Existing capabilities | Capability scope | Matching degree with current needs | Capability gaps | Suggested directions | Source |
|----------|---------|--------------|---------|---------|------|
| [Capability name] | [Scope covered by this capability] | Full match/partial match/no match | [Gap description, fill in "none" if there is no gap] | Recommended to reuse/replaceable/complementary/need to create | [Document/code path] |

> **Description**:
> - This table is a mandatory output to ensure that all potentially relevant existing capabilities are identified
> - **"Source" column is required**: You must indicate which document or code the capability was identified from, and no baseless guessing is allowed.
> - "Recommended directions" are only PRD suggestions, and the final reuse decision falls within the scope of HLD
> - If it is confirmed that there is no relevant ability, fill in "After investigation, there is no relevant ability" and explain the **scope of investigation** (which paths/keywords were searched)

---

## 3. Scope

### Within the scope of 3.1

- [Function to be integrated 1]
- [Function to be integrated 2]

### 3.2 Out of range

- [Functions not within the scope of this integration]

### 3.3 Matters to be confirmed

- [ ] [Items to be confirmed]

---

## 4. Solution analysis

### 4.1 Requirements Overview

[Briefly describe core requirements for third-party services]

### 4.2 Comparison of candidate solutions

| Dimensions | [Plan A] | [Plan B] | [Plan C] |
|------|---------|---------|---------|
| Feature Coverage | [Rating/Description] | [Rating/Description] | [Rating/Description] |
| Price | [Price] | [Price] | [Price] |
| Document Quality | [Rating] | [Rating] | [Rating] |
| Community activity | [Rating] | [Rating] | [Rating] |
| Domestic Availability | [Rating] | [Rating] | [Rating] |
| Security Compliance | [Rating] | [Rating] | [Rating] |

### 4.3 Solution suggestions

**Suggested solution**: [Program name]

**Reason for suggestion**:
1. [Reason 1]
2. [Reason 2]

**risk**:
- [Risk of choosing this option]

> See HLD for final solution selection decision

---

## 5. Integration requirements

### 5.1 Required abilities

[List capabilities that need to be obtained from third-party services]

| Capabilities | Description | Priority |
|------|------|--------|
| [Ability 1] | [Description] | P0/P1/P2 |
| [Ability 2] | [Description] | P0/P1/P2 |

### 5.2 Function Mapping

[Describe the correspondence between our functions and third-party capabilities]

| Our functions | Third-party capabilities | Description |
|----------|------------|------|
| [Function] | [Ability] | [Description] |

### 5.3 Data interaction

[Describe data interaction requirements with third parties]

| Data | Direction | Description |
|------|------|------|
| [Data] | Our → Third Party / Third Party → Our | [Description] |

> For specific interface mapping and data conversion, see HLD

---

## 6. Exception handling requirements

### 6.1 Abnormal scenarios

| Scenario | Business Impact | User Perception |
|------|----------|----------|
| Third-party services are unavailable | [Impact] | [What users see] |
| Response Timeout | [Impact] | [What User Sees] |
| Data return exception | [Impact] | [What the user sees] |

### 6.2 Downgrade requirements

| Scenario | Downgrade Plan | User Tips |
|------|----------|----------|
| [Scenario] | [Plan] | [Prompt content] |

> For specific retry and circuit breaker strategies, see HLD

---

## 7. Non-functional requirements

### 7.1 Performance requirements

| Scenario | Requirements |
|------|------|
| Call delay (excluding third-party time-consuming) | P99 ≤ [X]ms |
| Throughput | [X] QPS |

### 7.2 Security requirements

| Requirements | Description |
|------|------|
| Transmission Encryption | [Required] |
| Credential Protection | [Requirements] |
| Sensitive Data | [Processing Request] |

### 7.3 Monitoring requirements

| Monitoring items | Description |
|--------|------|
| Call success rate | [Requirements] |
| response time | [requirements] |
| Error Alert | [Requirement] |

### 7.4 Compatibility requirements

| Requirements | Description |
|------|------|
| Interface Compatibility | [Whether existing callers are affected] |
| Data compatibility | [Whether the existing data format needs to be changed] |
| Third-party version compatibility | [Supported third-party API version range] |

### 7.5 Release requirements

| Requirements | Description |
|------|------|
| Grayscale strategy | [Whether grayscale is required, grayscale range] |
| Rollback capability | [Whether rollback needs to be supported and rollback conditions] |
| Function switch | [Whether function switch is required] |

> Note: For specific grayscale/rollback technical solutions, see HLD

---

## 8. Dependencies and constraints

### 8.1 Third-party service restrictions

| Constraints | Description |
|------|------|
| API version | [version number] |
| Current Limit Limit | [Limit Description] |
| SLA | [SLA description] |

### 8.2 Known constraints

- [Business Constraints]
- [Compliance Constraints]

---

## 9. Project Plan

### 9.1 Milestones

| Milestones | Target dates | Deliverables |
|--------|----------|--------|
| Interface research completed | YYYY-MM-DD | Interface documents, feasibility report |
| Integrated development completed | YYYY-MM-DD | Integrated code |
| Joint debugging test completed | YYYY-MM-DD | Joint debugging report |
| Go online | YYYY-MM-DD | Production environment deployment |

### 9.2 Resource Allocation

| Roles | People | Commitment |
|------|------|------|
| [role] | [personnel] | [ratio] |

---

## 10. Risks and Mitigations

| Risk | Impact | Probability | Mitigation |
|------|------|------|----------|
| Third-party services are unstable | High | Medium | Implement downgrade plan |
| API Changes | Medium | Low | Follow Change Notifications |
| [Other risks] | [Impact] | [Probability] | [Measures] |

---

## 11. Acceptance Criteria

### AC-001: Basic functions
- [ ] [Functional Acceptance Conditions]

### AC-002: Exception handling
- [ ] Correctly handle errors returned by third parties
- [ ] Users are given clear prompts when timeout occurs
- [ ] Features available when downgrade plan is in effect

### AC-003: Monitoring
- [ ] Monitoring indicators are collected correctly
- [ ] Alarm rules are triggered correctly

---

## 12. Questions to be clarified

| Number | Question | Asked by | Status | Conclusion |
|------|------|--------|------|------|
| Q1 | [Question] | [Asker] | To be discussed/resolved | [Conclusion] |

---

## Appendix

### A. Third-party document link

- [Official Documentation]: [Link]
- [API Reference]: [Link]

### B. Test account information

| Environment | Account/Key | Purpose |
|------|----------|------|
| Sandbox | [Desensitization Information] | Development Testing |

---

Writing Guidance

Solution Analysis Chapter

When there are multiple candidates: 1. List the evaluation dimensions (function, price, documentation, community, compliance, etc.) 2. Score or describe each solution 3. Give program suggestions and reasons (note: the final selection decision rests with HLD)

If there is a clear preferred plan, the reasons for the recommendation still need to be stated.

Integration requirements chapter

Note: PRD describes "what capabilities are required" and does not design "how to call them".

Correct writing:

| Our functions | Third-party capabilities | Description |
|----------|------------|------|
| Send SMS verification code | Send SMS | Used for user registration and login |
| Query sending status | Status query | Used to confirm delivery |

Wrong writing (crossing the boundary to HLD):

| Our functions | Third-party interface | Calling method |
|----------|------------|----------|
| Send SMS | POST /sms/send | Synchronous call, timeout 3s |

Exception handling requirements chapter

Correct writing:

| Scenario | Downgrade Plan | User Tips |
|------|----------|----------|
| The payment service is unavailable | Display a maintenance prompt and guide you to try again later | "The payment service is temporarily busy, please try again later" |
| AI service timed out | Returning default results | "AI responded slowly and has returned default results for you" |

Wrong writing (crossing the boundary to HLD):

Retry strategy: Maximum retries 3 times, exponential backoff, initial interval 1s
Fuse configuration: Error rate > 50% triggers fuse, fuse duration is 30s

Example of acceptance criteria

### AC-001: SMS sending
- [ ] Enter the correct mobile phone number and the verification code is sent successfully
- [ ] Verification code is valid for 5 minutes
- [ ] The same mobile phone number can only be sent once in 1 minute.

### AC-002: Exception handling
- [ ] Display friendly prompts when SMS service is unavailable
- [ ] Users can try again when sending fails
- [ ] Error log is recorded correctly

PRD 模板：第三方集成

本模板适用于接入外部服务的需求，如监控系统、支付网关、AI 引擎、云服务等。

---

文档结构

# PRD: [集成名称]

> **文档版本**: X.X
> **状态**: 草稿 / 评审中 / 已批准
> **作者**: [作者姓名]
> **创建日期**: YYYY-MM-DD
> **最后更新**: YYYY-MM-DD

<!-- TRACEABILITY-METADATA:BEGIN -->

schema: name: testany-traceability version: "1.0.0" profile: prd-profile-v1 artifact: id: PRD-[DOMAIN]-001 type: PRD title: [集成名称] status: draft owners: [] created_at: YYYY-MM-DD updated_at: YYYY-MM-DD source_documents: [] entities: requirements: [] risks: [] must_not_regress: [] external_behaviors: [] decisions: [] flows: [] test_cases: [] relations: [] waivers: []

<!-- TRACEABILITY-METADATA:END -->

---

## 1. 文档信息

### 1.1 基本信息

| 属性 | 值 |
|------|-----|
| PRD 编号 | PRD-XXX |
| 所属产品 | [产品名称] |
| 优先级 | P0 / P1 / P2 / P3 |
| 预计版本 | vX.X |
| PRD 基线版本 | vX.X（HLD 基于此版本） |
| 最后同步日期 | YYYY-MM-DD |

### 1.2 修订历史

| 版本 | 日期 | 变更内容 | 作者 |
|------|------|----------|------|
| X.X | YYYY-MM-DD | [变更描述] | [作者] |

### 1.3 术语表

| 术语 | 定义 |
|------|------|
| [术语] | [定义] |

---

## 2. 背景与目标

### 2.1 业务背景

[为什么需要集成这个第三方服务]

### 2.2 集成目标

[集成后要达成什么效果]

### 2.3 成功指标

| 指标 | 目标值 | 数据来源 | 度量方式 |
|------|--------|----------|----------|
| [指标] | [目标值] | 已有埋点/需新增/人工统计 | [度量方式] |

### 2.4 业务现状（如为替换/增强现有能力）

#### 当前状态
[描述当前如何满足该业务需求，如为全新需求可标注"不适用"]

#### 业务变更
| 变更项 | 变更前 | 变更后 |
|--------|--------|--------|
| [能力/流程] | [当前状态] | [集成后状态] |

### 2.5 相关能力识别（强制）

| 已有能力 | 能力范围 | 与本需求匹配度 | 能力差距 | 建议方向 | 来源 |
|----------|---------|--------------|---------|---------|------|
| [能力名称] | [该能力覆盖的范围] | 完全匹配/部分匹配/不匹配 | [差距描述，无差距填"无"] | 建议复用/可替换/可互补/需新建 | [文档/代码路径] |

> **说明**：
> - 此表为强制输出，确保识别所有可能相关的已有能力
> - **「来源」列必填**：必须注明从哪个文档或代码中识别到该能力，禁止无依据猜测
> - 「建议方向」仅为 PRD 建议，最终复用决策属于 HLD 范畴
> - 如确认无相关能力，填写"经排查，无相关已有能力"并说明**排查范围**（搜索了哪些路径/关键词）

---

## 3. 范围

### 3.1 范围内

- [要集成的功能 1]
- [要集成的功能 2]

### 3.2 范围外

- [不在本次集成范围的功能]

### 3.3 待确认事项

- [ ] [待确认事项]

---

## 4. 方案分析

### 4.1 需求概述

[简要描述对第三方服务的核心需求]

### 4.2 候选方案对比

| 维度 | [方案A] | [方案B] | [方案C] |
|------|---------|---------|---------|
| 功能覆盖度 | [评分/描述] | [评分/描述] | [评分/描述] |
| 价格 | [价格] | [价格] | [价格] |
| 文档质量 | [评分] | [评分] | [评分] |
| 社区活跃度 | [评分] | [评分] | [评分] |
| 国内可用性 | [评分] | [评分] | [评分] |
| 安全合规 | [评分] | [评分] | [评分] |

### 4.3 方案建议

**建议方案**：[方案名称]

**建议理由**：
1. [理由 1]
2. [理由 2]

**风险**：
- [选择该方案的风险]

> 最终方案选型决定见 HLD

---

## 5. 集成需求

### 5.1 需要的能力

[列出需要从第三方服务获取的能力]

| 能力 | 说明 | 优先级 |
|------|------|--------|
| [能力1] | [说明] | P0/P1/P2 |
| [能力2] | [说明] | P0/P1/P2 |

### 5.2 功能映射

[描述我方功能与第三方能力的对应关系]

| 我方功能 | 第三方能力 | 说明 |
|----------|------------|------|
| [功能] | [能力] | [说明] |

### 5.3 数据交互

[描述与第三方的数据交互需求]

| 数据 | 方向 | 说明 |
|------|------|------|
| [数据] | 我方→第三方 / 第三方→我方 | [说明] |

> 具体接口映射和数据转换见 HLD

---

## 6. 异常处理需求

### 6.1 异常场景

| 场景 | 业务影响 | 用户感知 |
|------|----------|----------|
| 第三方服务不可用 | [影响] | [用户看到什么] |
| 响应超时 | [影响] | [用户看到什么] |
| 数据返回异常 | [影响] | [用户看到什么] |

### 6.2 降级要求

| 场景 | 降级方案 | 用户提示 |
|------|----------|----------|
| [场景] | [方案] | [提示内容] |

> 具体重试、熔断策略见 HLD

---

## 7. 非功能需求

### 7.1 性能要求

| 场景 | 要求 |
|------|------|
| 调用延迟（不含第三方耗时） | P99 ≤ [X]ms |
| 吞吐量 | [X] QPS |

### 7.2 安全要求

| 要求 | 说明 |
|------|------|
| 传输加密 | [要求] |
| 凭据保护 | [要求] |
| 敏感数据 | [处理要求] |

### 7.3 监控要求

| 监控项 | 说明 |
|--------|------|
| 调用成功率 | [要求] |
| 响应时间 | [要求] |
| 错误告警 | [要求] |

### 7.4 兼容性要求

| 要求 | 说明 |
|------|------|
| 接口兼容 | [现有调用方是否受影响] |
| 数据兼容 | [现有数据格式是否需要变更] |
| 第三方版本兼容 | [支持的第三方 API 版本范围] |

### 7.5 发布要求

| 要求 | 说明 |
|------|------|
| 灰度策略 | [是否需要灰度，灰度范围] |
| 回滚能力 | [是否需要支持回滚，回滚条件] |
| 功能开关 | [是否需要功能开关] |

> 注：具体灰度/回滚技术方案见 HLD

---

## 8. 依赖与约束

### 8.1 第三方服务约束

| 约束 | 说明 |
|------|------|
| API 版本 | [版本号] |
| 限流限制 | [限制描述] |
| SLA | [SLA 描述] |

### 8.2 已知约束

- [业务约束]
- [合规约束]

---

## 9. 项目计划

### 9.1 里程碑

| 里程碑 | 目标日期 | 交付物 |
|--------|----------|--------|
| 接口调研完成 | YYYY-MM-DD | 接口文档、可行性报告 |
| 集成开发完成 | YYYY-MM-DD | 集成代码 |
| 联调测试完成 | YYYY-MM-DD | 联调报告 |
| 上线 | YYYY-MM-DD | 生产环境部署 |

### 9.2 资源分配

| 角色 | 人员 | 投入 |
|------|------|------|
| [角色] | [人员] | [比例] |

---

## 10. 风险与缓解

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| 第三方服务不稳定 | 高 | 中 | 实现降级方案 |
| API 变更 | 中 | 低 | 关注变更通知 |
| [其他风险] | [影响] | [概率] | [措施] |

---

## 11. 验收标准

### AC-001: 基本功能
- [ ] [功能验收条件]

### AC-002: 异常处理
- [ ] 第三方返回错误时正确处理
- [ ] 超时时用户有明确提示
- [ ] 降级方案生效时功能可用

### AC-003: 监控
- [ ] 监控指标正确采集
- [ ] 告警规则正确触发

---

## 12. 待澄清问题

| 编号 | 问题 | 提出人 | 状态 | 结论 |
|------|------|--------|------|------|
| Q1 | [问题] | [提出人] | 待讨论/已解决 | [结论] |

---

## 附录

### A. 第三方文档链接

- [官方文档]：[链接]
- [API 参考]：[链接]

### B. 测试账号信息

| 环境 | 账号/Key | 用途 |
|------|----------|------|
| 沙箱 | [脱敏信息] | 开发测试 |

---

写作指导

方案分析章节

当有多个候选方案时： 1. 列出评估维度（功能、价格、文档、社区、合规等） 2. 对每个方案打分或描述 3. 给出方案建议和理由（注意：最终选型决定在 HLD）

如已有明确倾向方案，仍需说明建议理由。

集成需求章节

注意：PRD 描述"需要什么能力"，不设计"如何调用"。

正确写法：

| 我方功能 | 第三方能力 | 说明 |
|----------|------------|------|
| 发送短信验证码 | 短信发送 | 用于用户注册和登录 |
| 查询发送状态 | 状态查询 | 用于确认送达 |

错误写法（越界到 HLD）：

| 我方功能 | 第三方接口 | 调用方式 |
|----------|------------|----------|
| 发送短信 | POST /sms/send | 同步调用，超时 3s |

异常处理需求章节

正确写法：

| 场景 | 降级方案 | 用户提示 |
|------|----------|----------|
| 支付服务不可用 | 显示维护提示，引导稍后重试 | "支付服务暂时繁忙，请稍后重试" |
| AI 服务超时 | 返回默认结果 | "AI 响应较慢，已为您返回默认结果" |

错误写法（越界到 HLD）：

重试策略：最大重试 3 次，指数退避，初始间隔 1s
熔断配置：错误率 > 50% 触发熔断，熔断时长 30s

验收标准示例

### AC-001: 短信发送
- [ ] 输入正确手机号，成功发送验证码
- [ ] 验证码在 5 分钟内有效
- [ ] 同一手机号 1 分钟内只能发送 1 次

### AC-002: 异常处理
- [ ] 短信服务不可用时显示友好提示
- [ ] 发送失败时用户可以重试
- [ ] 错误日志正确记录

PRD Template: new features (no UI/backend)

This template is suitable for new functional requirements that do not involve user interfaces, such as back-end services, APIs, and background tasks.

---

Document structure

# PRD: [function name]

> **Document Version**: X.X
> **Status**: Draft / Under Review / Approved
> **Author**: [Author’s name]
> **Creation Date**: YYYY-MM-DD
> **Last Update**: YYYY-MM-DD

<!-- TRACEABILITY-METADATA:BEGIN -->

schema: name: testany-traceability version: "1.0.0" profile: prd-profile-v1 artifact: id: PRD-[DOMAIN]-001 type: PRD title: [function name] status: draft owners: [] created_at: YYYY-MM-DD updated_at: YYYY-MM-DD source_documents: [] entities: requirements: [] risks: [] must_not_regress: [] external_behaviors: [] decisions: [] flows: [] test_cases: [] relations: [] waivers: []

<!-- TRACEABILITY-METADATA:END -->

---

## 1. Document Information

### 1.1 Basic Information

| Properties | Values ​​|
|------|-----|
| PRD Number | PRD-XXX |
| Products | [Product Name] |
| Priority | P0 / P1 / P2 / P3 |
| Estimated version | vX.X |
| PRD baseline version | vX.X (HLD is based on this version) |
| Last sync date | YYYY-MM-DD |

### 1.2 Revision History

| Version | Date | Changes | Author |
|------|------|----------|------|
| X.X | YYYY-MM-DD | [Change description] | [Author] |

### 1.3 Glossary

| Terminology | Definition |
|------|------|
| [Term] | [Definition] |

---

## 2. Background and goals

### 2.1 Business Background

[Describe business pain points or opportunities]

### 2.2 Product Goals

[Describe product goals]

### 2.3 Success Indicators

| Indicators | Target values ​​| Data sources | Measurement methods |
|------|--------|----------|----------|
| [Indicators] | [Target value] | Already buried points/Need to add new ones/Manual statistics | [Measurement method] |

### 2.4 Current Business State (such as adding new functions to existing systems)

#### Current process
[Describe how the current system handles related business. If it is a new function, it can be marked "not applicable"]

#### Business changes
| Change items | Before change | After change |
|--------|--------|--------|
| [Process/Function] | [Current Status] | [Target Status] |

#### Scope of influence
| Affected objects | Impact description |
|----------|----------|
| caller | [affected callers] |
| Existing Processes | [Affected Processes] |
| Upstream and downstream systems | [Affected systems] |

### 2.5 Relevant capability identification (mandatory)

| Existing capabilities | Capability scope | Matching degree with current needs | Capability gaps | Suggested directions | Source |
|----------|---------|--------------|---------|---------|------|
| [Capability name] | [Scope covered by this capability] | Complete match/Partial match/No match | [Gap description, fill in "None" if there is no gap] | Recommended reuse/Recommended expansion/Reference only/Need to create new | [Document/code path] |

> **Description**:
> - This table is a mandatory output to ensure that all potentially relevant existing capabilities are identified
> - **"Source" column is required**: You must indicate which document or code the capability was identified from, and no baseless guessing is allowed.
> - "Recommended directions" are only PRD suggestions, and the final reuse decision falls within the scope of HLD
> - If it is confirmed that there is no relevant ability, fill in "After investigation, there is no relevant ability" and explain the **scope of investigation** (which paths/keywords were searched)

---

## 3. Scope

### Within the scope of 3.1

- [Feature/Change 1]

### 3.2 Out of range

- [Items not within the scope]

### 3.3 Matters to be confirmed

- [ ] [Items to be confirmed]

---

## 4. System Overview

### 4.1 Function Overview

[Briefly describe the overall responsibilities and boundaries of the function]

### 4.2 Caller

| Caller | Calling scenario |
|--------|----------|
| [Caller] | [Scenario Description] |

### 4.3 Capability Overview

[Use Mermaid to describe the capabilities and data flow provided by the function]

flowchart LR A[input] --> B[function module] B --> C[Output/Storage] B --> D[Notification/Event]

> For specific technical architecture, see HLD

---

## 5. Functional Requirements

### 5.X [Function module name]

#### 5.X.1 Function Description

[Describe the functional purpose and business value of this module]

#### 5.X.2 Processing flow

[Describe business processes using Mermaid sequence diagrams or flowcharts]

sequenceDiagram participant caller participant this function participant external dependencies

Caller->>This function: Request This function->>External dependencies: call (if necessary) External dependencies-->>This function: Return This function-->>Caller: response

#### 5.X.3 Business Rules

| Rule number | Rule description | Trigger conditions |
|----------|----------|----------|
| BR-001 | [Rule Description] | [Conditions] |

#### 5.X.4 Input and output

**enter**:
- [Describe what input data is required]

**Output**:
- [Describe what output is produced]

**side effect**:
- [Describe what side effects will occur, such as sending notifications, writing records, etc.]

---

## 6. Interface capabilities

[Describe the interface capabilities that need to be provided, without specifying specific paths and implementations]

### 6.X [Interface capability name]

| Properties | Description |
|------|------|
| Capability description | [What does this interface do] |
| Caller | [Who will call] |
| Certification Requirements | Required / Not Required |

#### Enter requirements

[Describe what input information is required]

- [Required input 1]
- [Required input 2]
- [optional input]

#### Output requirements

[Describe what information is returned]

- On success: [what to return]
- On failure: [What error message is returned]

#### Business constraints

- [Constraint 1]
- [Constraint 2]

> See HLD for specific API design

---

## 7. Data concepts

[Describe the business entities and relationships involved]

### 7.1 Business entity

| Entity | Description | Key Attributes |
|------|------|----------|
| [Entity Name] | [Business Meaning] | [Key Business Attributes] |

### 7.2 Entity Relationship

[Describe business relationships between entities]

erDiagram Entity A ||--o{ Entity B : Relationship

> For specific data model design, see HLD

---

## 8. Non-functional requirements

### 8.1 Performance requirements

| Scenario | Metrics | Requirements |
|------|------|------|
| [Scenario] | Response time | P99 ≤ [X]ms |
| [Scenario] | Throughput | ≥ [X] QPS |

### 8.2 Reliability requirements

| Requirements | Goals |
|------|------|
| Availability | [X]% |
| Data persistence | [Description] |

### 8.3 Security requirements

| Requirements | Description |
|------|------|
| Certification | [Certification Requirements] |
| Authorization | [Authorization Requirements] |
| Data Protection | [Protection Requirements] |

### 8.4 Compatibility requirements

| Requirements | Description |
|------|------|
| Interface Compatibility | [Whether existing callers are affected] |
| Data Compatibility | [Whether existing data is affected] |
| Protocol Compatibility | [Whether the communication protocol has changed] |

### 8.5 Release requirements

| Requirements | Description |
|------|------|
| Grayscale strategy | [Whether grayscale is required, grayscale range] |
| Rollback capability | [Whether rollback needs to be supported] |
| Function switch | [Whether function switch is required] |

> Note: For specific grayscale/rollback technical solutions, see HLD

---

## 9. Dependencies and constraints

### 9.1 Known constraints

- [Business Constraints]
- [Time constraint]

### 9.2 External dependencies

- [Dependent third-party services]

> For details on technical dependencies, see HLD

---

## 10. Project Plan

### 10.1 Milestones

| Milestones | Target dates | Deliverables |
|--------|----------|--------|
| [Milestone] | YYYY-MM-DD | [Deliverable] |

### 10.2 Resource Allocation

| Roles | People | Commitment |
|------|------|------|
| [role] | [personnel] | [ratio] |

---

## 11. Risks and Mitigations

| Risk | Impact | Probability | Mitigation |
|------|------|------|----------|
| [Risk] | High/Medium/Low | High/Medium/Low | [Measures] |

---

## 12. Acceptance Criteria

### AC-001: [Acceptance item name]
- [ ] [Acceptance Conditions]

---

## 13. Questions to be clarified

| Number | Question | Asked by | Status | Conclusion |
|------|------|--------|------|------|
| Q1 | [Question] | [Asker] | To be discussed/resolved | [Conclusion] |

---

## Appendix

[If any additional content]

---

Writing Guidance

System Overview Chapter

1. Function Overview: A paragraph that clearly explains what this function does 2. Caller: Who will use this function and under what circumstances it will be used? 3. Capability Overview: Use a simple flow chart to illustrate input and output

Functional Requirements chapter

Each functional module contains:

1. Functional Description: Business purpose and value 2. Processing process: business process, not technical implementation 3. Business Rules: Business logic constraints 4. Input and Output: What is needed, what is produced

Interface capability chapter

Note: PRD only describes the interface "capabilities" and does not design specific APIs.

Correct writing:

### Create order ability

| Properties | Description |
|------|------|
| Capability description | Create order based on shopping cart |
| Caller | Front-end shopping cart page |
| Authentication requirements | User login required |

#### Enter requirements
- Shopping cart product list
- Shipping address
- Payment method

#### Output requirements
- On success: Return order number
- On failure: Return the reason for failure

Wrong writing (crossing the boundary to HLD):

POST /api/v1/orders

Request body

{ "cart_id": "string", "address_id": "string" }

Data Concept Chapter

Correct writing:

| Entity | Description | Key Attributes |
|------|------|----------|
| Order | User's purchase record | Order number, amount, status, order time |
| Line item | Products in the order | Product name, quantity, unit price |

Wrong writing (crossing the boundary to HLD):

| Fields | Types | Constraints |
|------|------|------|
| id | UUID | PRIMARY KEY |
| created_at | TIMESTAMP | NOT NULL |

Business rules form

Example of acceptance criteria

### AC-001: Create Order
- [ ] You can create an order when there are items in the shopping cart
- [ ] Prompt the user when inventory is low and refuse to create
- [ ] Return the order number after successful creation
- [ ] The order status is initially "pending payment"

### AC-002: Order timeout cancellation
- [ ] Orders not paid for 30 minutes will be automatically canceled
- [ ] Release inventory on cancellation
- [ ] Send cancellation notification (if notification channel is configured)

PRD 模板：新功能（无 UI / 后端）

本模板适用于后端服务、API、后台任务等不涉及用户界面的新功能需求。

---

文档结构

# PRD: [功能名称]

> **文档版本**: X.X
> **状态**: 草稿 / 评审中 / 已批准
> **作者**: [作者姓名]
> **创建日期**: YYYY-MM-DD
> **最后更新**: YYYY-MM-DD

<!-- TRACEABILITY-METADATA:BEGIN -->

schema: name: testany-traceability version: "1.0.0" profile: prd-profile-v1 artifact: id: PRD-[DOMAIN]-001 type: PRD title: [功能名称] status: draft owners: [] created_at: YYYY-MM-DD updated_at: YYYY-MM-DD source_documents: [] entities: requirements: [] risks: [] must_not_regress: [] external_behaviors: [] decisions: [] flows: [] test_cases: [] relations: [] waivers: []

<!-- TRACEABILITY-METADATA:END -->

---

## 1. 文档信息

### 1.1 基本信息

| 属性 | 值 |
|------|-----|
| PRD 编号 | PRD-XXX |
| 所属产品 | [产品名称] |
| 优先级 | P0 / P1 / P2 / P3 |
| 预计版本 | vX.X |
| PRD 基线版本 | vX.X（HLD 基于此版本） |
| 最后同步日期 | YYYY-MM-DD |

### 1.2 修订历史

| 版本 | 日期 | 变更内容 | 作者 |
|------|------|----------|------|
| X.X | YYYY-MM-DD | [变更描述] | [作者] |

### 1.3 术语表

| 术语 | 定义 |
|------|------|
| [术语] | [定义] |

---

## 2. 背景与目标

### 2.1 业务背景

[描述业务痛点或机会]

### 2.2 产品目标

[描述产品目标]

### 2.3 成功指标

| 指标 | 目标值 | 数据来源 | 度量方式 |
|------|--------|----------|----------|
| [指标] | [目标值] | 已有埋点/需新增/人工统计 | [度量方式] |

### 2.4 业务现状（如为已有系统新增功能）

#### 当前流程
[描述当前系统如何处理相关业务，如为全新功能可标注"不适用"]

#### 业务变更
| 变更项 | 变更前 | 变更后 |
|--------|--------|--------|
| [流程/功能] | [当前状态] | [目标状态] |

#### 影响范围
| 影响对象 | 影响描述 |
|----------|----------|
| 调用方 | [受影响的调用方] |
| 现有流程 | [受影响的流程] |
| 上下游系统 | [受影响的系统] |

### 2.5 相关能力识别（强制）

| 已有能力 | 能力范围 | 与本需求匹配度 | 能力差距 | 建议方向 | 来源 |
|----------|---------|--------------|---------|---------|------|
| [能力名称] | [该能力覆盖的范围] | 完全匹配/部分匹配/不匹配 | [差距描述，无差距填"无"] | 建议复用/建议扩展/仅供参考/需新建 | [文档/代码路径] |

> **说明**：
> - 此表为强制输出，确保识别所有可能相关的已有能力
> - **「来源」列必填**：必须注明从哪个文档或代码中识别到该能力，禁止无依据猜测
> - 「建议方向」仅为 PRD 建议，最终复用决策属于 HLD 范畴
> - 如确认无相关能力，填写"经排查，无相关已有能力"并说明**排查范围**（搜索了哪些路径/关键词）

---

## 3. 范围

### 3.1 范围内

- [功能/变更 1]

### 3.2 范围外

- [不在范围内的事项]

### 3.3 待确认事项

- [ ] [待确认事项]

---

## 4. 系统概述

### 4.1 功能概述

[简要描述该功能的整体职责和边界]

### 4.2 调用方

| 调用方 | 调用场景 |
|--------|----------|
| [调用方] | [场景描述] |

### 4.3 能力概览

[使用 Mermaid 描述功能提供的能力和数据流向]

flowchart LR A[输入] --> B[功能模块] B --> C[输出/存储] B --> D[通知/事件]

> 具体技术架构见 HLD

---

## 5. 功能需求

### 5.X [功能模块名称]

#### 5.X.1 功能描述

[描述该模块的功能目的和业务价值]

#### 5.X.2 处理流程

[使用 Mermaid 时序图或流程图描述业务流程]

sequenceDiagram participant 调用方 participant 本功能 participant 外部依赖

调用方->>本功能: 请求 本功能->>外部依赖: 调用（如需要） 外部依赖-->>本功能: 返回 本功能-->>调用方: 响应

#### 5.X.3 业务规则

| 规则编号 | 规则描述 | 触发条件 |
|----------|----------|----------|
| BR-001 | [规则描述] | [条件] |

#### 5.X.4 输入输出

**输入**：
- [描述需要什么输入数据]

**输出**：
- [描述产生什么输出]

**副作用**：
- [描述会产生什么副作用，如发送通知、写入记录等]

---

## 6. 接口能力

[描述需要提供的接口能力，不规定具体路径和实现]

### 6.X [接口能力名称]

| 属性 | 说明 |
|------|------|
| 能力描述 | [这个接口做什么] |
| 调用方 | [谁会调用] |
| 认证要求 | 需要 / 不需要 |

#### 输入要求

[描述需要什么输入信息]

- [必需输入 1]
- [必需输入 2]
- [可选输入]

#### 输出要求

[描述返回什么信息]

- 成功时：[返回什么]
- 失败时：[返回什么错误信息]

#### 业务约束

- [约束 1]
- [约束 2]

> 具体 API 设计见 HLD

---

## 7. 数据概念

[描述涉及的业务实体和关系]

### 7.1 业务实体

| 实体 | 说明 | 关键属性 |
|------|------|----------|
| [实体名] | [业务含义] | [关键业务属性] |

### 7.2 实体关系

[描述实体间的业务关系]

erDiagram 实体A ||--o{ 实体B : 关系

> 具体数据模型设计见 HLD

---

## 8. 非功能需求

### 8.1 性能要求

| 场景 | 指标 | 要求 |
|------|------|------|
| [场景] | 响应时间 | P99 ≤ [X]ms |
| [场景] | 吞吐量 | ≥ [X] QPS |

### 8.2 可靠性要求

| 要求 | 目标 |
|------|------|
| 可用性 | [X]% |
| 数据持久性 | [描述] |

### 8.3 安全要求

| 要求 | 说明 |
|------|------|
| 认证 | [认证要求] |
| 授权 | [授权要求] |
| 数据保护 | [保护要求] |

### 8.4 兼容性要求

| 要求 | 说明 |
|------|------|
| 接口兼容 | [现有调用方是否受影响] |
| 数据兼容 | [现有数据是否受影响] |
| 协议兼容 | [通信协议是否变化] |

### 8.5 发布要求

| 要求 | 说明 |
|------|------|
| 灰度策略 | [是否需要灰度，灰度范围] |
| 回滚能力 | [是否需要支持回滚] |
| 功能开关 | [是否需要功能开关] |

> 注：具体灰度/回滚技术方案见 HLD

---

## 9. 依赖与约束

### 9.1 已知约束

- [业务约束]
- [时间约束]

### 9.2 外部依赖

- [依赖的第三方服务]

> 技术依赖详见 HLD

---

## 10. 项目计划

### 10.1 里程碑

| 里程碑 | 目标日期 | 交付物 |
|--------|----------|--------|
| [里程碑] | YYYY-MM-DD | [交付物] |

### 10.2 资源分配

| 角色 | 人员 | 投入 |
|------|------|------|
| [角色] | [人员] | [比例] |

---

## 11. 风险与缓解

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| [风险] | 高/中/低 | 高/中/低 | [措施] |

---

## 12. 验收标准

### AC-001: [验收项名称]
- [ ] [验收条件]

---

## 13. 待澄清问题

| 编号 | 问题 | 提出人 | 状态 | 结论 |
|------|------|--------|------|------|
| Q1 | [问题] | [提出人] | 待讨论/已解决 | [结论] |

---

## 附录

[如有附加内容]

---

写作指导

系统概述章节

1. 功能概述：一段话说清楚这个功能做什么 2. 调用方：谁会使用这个功能，什么场景下使用 3. 能力概览：用简单的流程图说明输入输出

功能需求章节

每个功能模块包含：

1. 功能描述：业务目的和价值 2. 处理流程：业务流程，不是技术实现 3. 业务规则：业务逻辑约束 4. 输入输出：需要什么，产生什么

接口能力章节

注意：PRD 只描述接口"能力"，不设计具体 API。

正确写法：

### 创建订单能力

| 属性 | 说明 |
|------|------|
| 能力描述 | 根据购物车创建订单 |
| 调用方 | 前端购物车页面 |
| 认证要求 | 需要用户登录 |

#### 输入要求
- 购物车商品列表
- 收货地址
- 支付方式

#### 输出要求
- 成功时：返回订单号
- 失败时：返回失败原因

错误写法（越界到 HLD）：

POST /api/v1/orders

请求体

{ "cart_id": "string", "address_id": "string" }

数据概念章节

正确写法：

| 实体 | 说明 | 关键属性 |
|------|------|----------|
| 订单 | 用户的购买记录 | 订单号、金额、状态、下单时间 |
| 订单项 | 订单中的商品 | 商品名称、数量、单价 |

错误写法（越界到 HLD）：

| 字段 | 类型 | 约束 |
|------|------|------|
| id | UUID | PRIMARY KEY |
| created_at | TIMESTAMP | NOT NULL |

业务规则表格

验收标准示例

### AC-001: 创建订单
- [ ] 购物车有商品时可以创建订单
- [ ] 库存不足时提示用户并拒绝创建
- [ ] 创建成功后返回订单号
- [ ] 订单状态初始为"待支付"

### AC-002: 订单超时取消
- [ ] 30 分钟未支付的订单自动取消
- [ ] 取消时释放库存
- [ ] 发送取消通知（如配置了通知渠道）

PRD Template: new features (with UI)

This template is suitable for new functional requirements involving user interface.

---

Document structure

# PRD: [function name]

> **Document Version**: X.X
> **Status**: Draft / Under Review / Approved
> **Author**: [Author’s name]
> **Creation Date**: YYYY-MM-DD
> **Last Update**: YYYY-MM-DD

<!-- TRACEABILITY-METADATA:BEGIN -->

schema: name: testany-traceability version: "1.0.0" profile: prd-profile-v1 artifact: id: PRD-[DOMAIN]-001 type: PRD title: [function name] status: draft owners: [] created_at: YYYY-MM-DD updated_at: YYYY-MM-DD source_documents: [] entities: requirements: [] risks: [] must_not_regress: [] external_behaviors: [] decisions: [] flows: [] test_cases: [] relations: [] waivers: []

<!-- TRACEABILITY-METADATA:END -->

---

## 1. Document Information

### 1.1 Basic Information

| Properties | Values ​​|
|------|-----|
| PRD Number | PRD-XXX |
| Products | [Product Name] |
| Priority | P0 / P1 / P2 / P3 |
| Estimated version | vX.X |
| PRD baseline version | vX.X (HLD is based on this version) |
| Last sync date | YYYY-MM-DD |

### 1.2 Revision History

| Version | Date | Changes | Author |
|------|------|----------|------|
| X.X | YYYY-MM-DD | [Change description] | [Author] |

### 1.3 Glossary

| Terminology | Definition |
|------|------|
| [Term] | [Definition] |

---

## 2. Background and goals

### 2.1 Business Background

[Describe business pain points or opportunities]

### 2.2 Product Goals

[Describe product goals and what value users can gain]

### 2.3 Success Indicators

| Indicators | Target values ​​| Data sources | Measurement methods |
|------|--------|----------|----------|
| [Indicators] | [Target value] | Already buried points/Need to add new ones/Manual statistics | [Measurement method] |

### 2.4 Current Business State (such as adding new functions to existing systems)

#### Current process
[Describe how the current user completes related tasks. If it is a new function, it can be marked "not applicable"]

#### Business changes
| Change items | Before change | After change |
|--------|--------|--------|
| [Process/Function] | [Current Status] | [Target Status] |

#### Scope of influence
| Affected objects | Impact description |
|----------|----------|
| User Groups | [Affected Users] |
| Existing Processes | [Affected Processes] |
| Upstream and downstream systems | [Affected systems] |

### 2.5 Relevant capability identification (mandatory)

| Existing capabilities | Capability scope | Matching degree with current needs | Capability gaps | Suggested directions | Source |
|----------|---------|--------------|---------|---------|------|
| [Capability name] | [Scope covered by this capability] | Complete match/Partial match/No match | [Gap description, fill in "None" if there is no gap] | Recommended reuse/Recommended expansion/Reference only/Need to create new | [Document/code path] |

> **Description**:
> - This table is a mandatory output to ensure that all potentially relevant existing capabilities are identified
> - **"Source" column is required**: You must indicate which document or code the capability was identified from, and no baseless guessing is allowed.
> - "Recommended directions" are only PRD suggestions, and the final reuse decision falls within the scope of HLD
> - If it is confirmed that there is no relevant ability, fill in "After investigation, there is no relevant ability" and explain the **scope of investigation** (which paths/keywords were searched)

---

## 3. Scope

### Within the scope of 3.1

- [Feature/Change 1]
- [Feature/Change 2]

### 3.2 Out of range

- [Items not within the scope]

### 3.3 Matters to be confirmed

- [ ] [Items to be confirmed]

---

## 4. User Journey

### 4.1 Target users

[Describe target user profile]

### 4.2 Preconditions

| Conditions | Description |
|------|------|
| [Conditions] | [Description] |

### 4.3 Main process

[Described using Mermaid flowchart]

flowchart TD A[starting point] --> B{judgment} B -->|Yes| C[Step] B -->|No| D[Step] C --> E[end] D --> E

### 4.4 Exception process

| Abnormal scenarios | Handling methods |
|----------|----------|
| [Scenario] | [Processing method] |

---

## 5. Functional Requirements

### 5.X [Module/Page Name]

#### 5.X.1 Function Description

[Describe the functionality of this module]

#### 5.X.2 UI layout

[Use ASCII diagram or explain the location of the design draft]

┌─────────────────────────────────────────────────────────────┐ │ Page title │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ [Component area] │ │ │ │ [Element Description] │ │ │ │ [Button] │ │ │ └─────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘

#### 5.X.3 Interaction Specifications

| Element | Interaction | Result |
|------|------|------|
| [element] | [interaction method] | [expected result] |

#### 5.X.4 Status Description

| Status | Conditions | UI Behavior |
|------|------|---------|
| [Status] | [Trigger Condition] | [Display Content] |

#### 5.X.5 Data Display

| Field | Description | Format |
|------|------|------|
| [Field] | [Business Meaning] | [Display Format] |

---

## 6. Data concept

[Describe the business entities and relationships involved, conceptual level only]

### 6.1 Business entity

| Entity | Description | Key Attributes |
|------|------|----------|
| [Entity name] | [Business meaning] | [Key business attributes, non-technical fields] |

### 6.2 Entity Relationship

[Use brief text or Mermaid ER diagram to describe the business relationships between entities]

erDiagram User ||--o{ Order : Create Order ||--|{ Line Item : Contains

> For specific data model design, see HLD

---

## 7. Non-functional requirements

### 7.1 Performance requirements

| Scenario | Requirements |
|------|------|
| Page Loading | [Requirements] |
| Operation response | [request] |

### 7.2 Compatibility requirements

| Platform/Browser | Minimum version |
|-------------|----------|
| [Platform] | [Version] |

### 7.3 Backward compatibility requirements

| Requirements | Description |
|------|------|
| Old version client | [Whether compatibility is required and how to be compatible] |
| Existing data | [Whether existing data is affected] |
| Existing process | [Whether the existing user process is retained] |

### 7.4 Release requirements

| Requirements | Description |
|------|------|
| Grayscale strategy | [Whether grayscale is required, grayscale range] |
| Rollback capability | [Whether rollback needs to be supported] |
| Function switch | [Whether function switch is required] |

> Note: For specific grayscale/rollback technical solutions, see HLD

### 7.5 Accessibility Requirements

[if applicable]

---

## 8. Dependencies and constraints

### 8.1 Known constraints

- [Business Constraints]
- [Time constraint]
- [Resource Constraints]

### 8.2 External dependencies

- [Third-party services or products relied upon]

> For details on technical dependencies, see HLD

---

## 9. Project Plan

### 9.1 Milestones

| Milestones | Target dates | Deliverables |
|--------|----------|--------|
| [Milestone] | YYYY-MM-DD | [Deliverable] |

### 9.2 Resource Allocation

| Roles | People | Commitment |
|------|------|------|
| [role] | [personnel] | [ratio] |

---

## 10. Risks and Mitigations

| Risk | Impact | Probability | Mitigation |
|------|------|------|----------|
| [Risk] | High/Medium/Low | High/Medium/Low | [Measures] |

---

## 11. Acceptance Criteria

### AC-001: [Acceptance item name]
- [ ] [Acceptance Condition 1]
- [ ] [Acceptance Condition 2]

### UX-001: [User Experience Acceptance Item]
- [ ] [Acceptance Conditions]

---

## 12. Questions to be clarified

| Number | Question | Asked by | Status | Conclusion |
|------|------|--------|------|------|
| Q1 | [Question] | [Asker] | To be discussed/resolved | [Conclusion] |

---

## Appendix

[If any additional content]

---

Writing Guidance

User Journey Chapter

1. Target User: Describe user portrait, including role, technical level, and usage scenarios 2. Preconditions: Conditions that need to be met before the user enters the process 3. Main process: Use Mermaid flow chart to describe it, focusing on the user perspective rather than the system perspective 4. Exception process: List possible exception situations and handling methods

Functional Requirements chapter

Each page/module contains:

1. Function Description: Briefly describe the purpose of the function 2. UI Layout: Use ASCII diagrams to describe the page structure, or indicate the location of the design draft 3. Interaction specification: A table describing the behavior of each interactive element 4. Status Description: Different states and triggering conditions of the page/component 5. Data display: What data is displayed and what is the format?

Data Concept Chapter

Note: PRD only describes business concepts and does not specify technical implementation.

Correct writing:

| Entity | Description | Key Attributes |
|------|------|----------|
| Order | User's purchase record | Order number, amount, status, order time |
| Line item | Products in the order | Product name, quantity, unit price |

Wrong writing (crossing the boundary to HLD):

| Fields | Types | Constraints |
|------|------|------|
| id | UUID | PRIMARY KEY |
| created_at | TIMESTAMP | NOT NULL |

UI layout ASCII diagram specification

┌────────────┐ - Page/Area Border
│           │
├────────────┤ - Divider
│           │
└───────────┘

[button] - clickable element
"Input box" - input element
○ Radio - radio button
☑ Check - Checkbox
▼ Drop-down menu

Interactive specification form

Example of acceptance criteria

### AC-001: User login
- [ ] Enter the correct username and password, click login, and successfully enter the homepage
- [ ] If you enter an incorrect password, a "wrong username or password" prompt will be displayed.
- [ ] If you enter incorrectly 5 times in a row, your account will be locked for 15 minutes.
- [ ] Login status remains for 7 days (unless you actively log out)

### UX-001: Login page experience
- [ ] Page load time ≤ 2 seconds
- [ ] supports keyboard Tab switching focus
- [ ] Password input box supports show/hide switching

PRD 模板：新功能（有 UI）

本模板适用于涉及用户界面的新功能需求。

---

文档结构

# PRD: [功能名称]

> **文档版本**: X.X
> **状态**: 草稿 / 评审中 / 已批准
> **作者**: [作者姓名]
> **创建日期**: YYYY-MM-DD
> **最后更新**: YYYY-MM-DD

<!-- TRACEABILITY-METADATA:BEGIN -->

schema: name: testany-traceability version: "1.0.0" profile: prd-profile-v1 artifact: id: PRD-[DOMAIN]-001 type: PRD title: [功能名称] status: draft owners: [] created_at: YYYY-MM-DD updated_at: YYYY-MM-DD source_documents: [] entities: requirements: [] risks: [] must_not_regress: [] external_behaviors: [] decisions: [] flows: [] test_cases: [] relations: [] waivers: []

<!-- TRACEABILITY-METADATA:END -->

---

## 1. 文档信息

### 1.1 基本信息

| 属性 | 值 |
|------|-----|
| PRD 编号 | PRD-XXX |
| 所属产品 | [产品名称] |
| 优先级 | P0 / P1 / P2 / P3 |
| 预计版本 | vX.X |
| PRD 基线版本 | vX.X（HLD 基于此版本） |
| 最后同步日期 | YYYY-MM-DD |

### 1.2 修订历史

| 版本 | 日期 | 变更内容 | 作者 |
|------|------|----------|------|
| X.X | YYYY-MM-DD | [变更描述] | [作者] |

### 1.3 术语表

| 术语 | 定义 |
|------|------|
| [术语] | [定义] |

---

## 2. 背景与目标

### 2.1 业务背景

[描述业务痛点或机会]

### 2.2 产品目标

[描述产品目标，用户能获得什么价值]

### 2.3 成功指标

| 指标 | 目标值 | 数据来源 | 度量方式 |
|------|--------|----------|----------|
| [指标] | [目标值] | 已有埋点/需新增/人工统计 | [度量方式] |

### 2.4 业务现状（如为已有系统新增功能）

#### 当前流程
[描述当前用户如何完成相关任务，如为全新功能可标注"不适用"]

#### 业务变更
| 变更项 | 变更前 | 变更后 |
|--------|--------|--------|
| [流程/功能] | [当前状态] | [目标状态] |

#### 影响范围
| 影响对象 | 影响描述 |
|----------|----------|
| 用户群体 | [受影响的用户] |
| 现有流程 | [受影响的流程] |
| 上下游系统 | [受影响的系统] |

### 2.5 相关能力识别（强制）

| 已有能力 | 能力范围 | 与本需求匹配度 | 能力差距 | 建议方向 | 来源 |
|----------|---------|--------------|---------|---------|------|
| [能力名称] | [该能力覆盖的范围] | 完全匹配/部分匹配/不匹配 | [差距描述，无差距填"无"] | 建议复用/建议扩展/仅供参考/需新建 | [文档/代码路径] |

> **说明**：
> - 此表为强制输出，确保识别所有可能相关的已有能力
> - **「来源」列必填**：必须注明从哪个文档或代码中识别到该能力，禁止无依据猜测
> - 「建议方向」仅为 PRD 建议，最终复用决策属于 HLD 范畴
> - 如确认无相关能力，填写"经排查，无相关已有能力"并说明**排查范围**（搜索了哪些路径/关键词）

---

## 3. 范围

### 3.1 范围内

- [功能/变更 1]
- [功能/变更 2]

### 3.2 范围外

- [不在范围内的事项]

### 3.3 待确认事项

- [ ] [待确认事项]

---

## 4. 用户旅程

### 4.1 目标用户

[描述目标用户画像]

### 4.2 前置条件

| 条件 | 说明 |
|------|------|
| [条件] | [说明] |

### 4.3 主流程

[使用 Mermaid 流程图描述]

flowchart TD A[起点] --> B{判断} B -->|是| C[步骤] B -->|否| D[步骤] C --> E[终点] D --> E

### 4.4 异常流程

| 异常场景 | 处理方式 |
|----------|----------|
| [场景] | [处理方式] |

---

## 5. 功能需求

### 5.X [模块/页面名称]

#### 5.X.1 功能描述

[描述该模块的功能]

#### 5.X.2 UI 布局

[使用 ASCII 图或说明设计稿位置]

┌─────────────────────────────────────────────────────────────┐ │ 页面标题 │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ [组件区域] │ │ │ │ [元素说明] │ │ │ │ [按钮] │ │ │ └─────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘

#### 5.X.3 交互规格

| 元素 | 交互 | 结果 |
|------|------|------|
| [元素] | [交互方式] | [预期结果] |

#### 5.X.4 状态说明

| 状态 | 条件 | UI 表现 |
|------|------|---------|
| [状态] | [触发条件] | [显示内容] |

#### 5.X.5 数据展示

| 字段 | 说明 | 格式 |
|------|------|------|
| [字段] | [业务含义] | [显示格式] |

---

## 6. 数据概念

[描述涉及的业务实体和关系，仅限概念层面]

### 6.1 业务实体

| 实体 | 说明 | 关键属性 |
|------|------|----------|
| [实体名] | [业务含义] | [关键业务属性，非技术字段] |

### 6.2 实体关系

[用简要文字或 Mermaid ER 图描述实体间的业务关系]

erDiagram 用户 ||--o{ 订单 : 创建 订单 ||--|{ 订单项 : 包含

> 具体数据模型设计见 HLD

---

## 7. 非功能需求

### 7.1 性能要求

| 场景 | 要求 |
|------|------|
| 页面加载 | [要求] |
| 操作响应 | [要求] |

### 7.2 兼容性要求

| 平台/浏览器 | 最低版本 |
|-------------|----------|
| [平台] | [版本] |

### 7.3 向后兼容要求

| 要求 | 说明 |
|------|------|
| 旧版本客户端 | [是否需要兼容，如何兼容] |
| 现有数据 | [现有数据是否受影响] |
| 现有流程 | [现有用户流程是否保留] |

### 7.4 发布要求

| 要求 | 说明 |
|------|------|
| 灰度策略 | [是否需要灰度，灰度范围] |
| 回滚能力 | [是否需要支持回滚] |
| 功能开关 | [是否需要功能开关] |

> 注：具体灰度/回滚技术方案见 HLD

### 7.5 可访问性要求

[如适用]

---

## 8. 依赖与约束

### 8.1 已知约束

- [业务约束]
- [时间约束]
- [资源约束]

### 8.2 外部依赖

- [依赖的第三方服务或产品]

> 技术依赖详见 HLD

---

## 9. 项目计划

### 9.1 里程碑

| 里程碑 | 目标日期 | 交付物 |
|--------|----------|--------|
| [里程碑] | YYYY-MM-DD | [交付物] |

### 9.2 资源分配

| 角色 | 人员 | 投入 |
|------|------|------|
| [角色] | [人员] | [比例] |

---

## 10. 风险与缓解

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| [风险] | 高/中/低 | 高/中/低 | [措施] |

---

## 11. 验收标准

### AC-001: [验收项名称]
- [ ] [验收条件 1]
- [ ] [验收条件 2]

### UX-001: [用户体验验收项]
- [ ] [验收条件]

---

## 12. 待澄清问题

| 编号 | 问题 | 提出人 | 状态 | 结论 |
|------|------|--------|------|------|
| Q1 | [问题] | [提出人] | 待讨论/已解决 | [结论] |

---

## 附录

[如有附加内容]

---

写作指导

用户旅程章节

1. 目标用户：描述用户画像，包括角色、技术水平、使用场景 2. 前置条件：用户进入该流程前需要满足的条件 3. 主流程：用 Mermaid 流程图描述，关注用户视角而非系统视角 4. 异常流程：列出可能的异常情况和处理方式

功能需求章节

每个页面/模块包含：

1. 功能描述：简要说明功能目的 2. UI 布局：使用 ASCII 图描述页面结构，或指明设计稿位置 3. 交互规格：表格形式说明每个可交互元素的行为 4. 状态说明：页面/组件的不同状态及触发条件 5. 数据展示：展示哪些数据，格式是什么

数据概念章节

注意：PRD 只描述业务概念，不规定技术实现。

正确写法：

| 实体 | 说明 | 关键属性 |
|------|------|----------|
| 订单 | 用户的购买记录 | 订单号、金额、状态、下单时间 |
| 订单项 | 订单中的商品 | 商品名称、数量、单价 |

错误写法（越界到 HLD）：

| 字段 | 类型 | 约束 |
|------|------|------|
| id | UUID | PRIMARY KEY |
| created_at | TIMESTAMP | NOT NULL |

UI 布局 ASCII 图规范

┌───────────┐  - 页面/区域边框
│           │
├───────────┤  - 分隔线
│           │
└───────────┘

[按钮]         - 可点击元素
「输入框」      - 输入元素
○ 单选         - 单选按钮
☑ 复选         - 复选框
▼ 下拉         - 下拉菜单

交互规格表格

验收标准示例

### AC-001: 用户登录
- [ ] 输入正确的用户名和密码，点击登录，成功进入首页
- [ ] 输入错误的密码，显示"用户名或密码错误"提示
- [ ] 连续输错 5 次，账户锁定 15 分钟
- [ ] 登录状态保持 7 天（除非主动退出）

### UX-001: 登录页面体验
- [ ] 页面加载时间 ≤ 2 秒
- [ ] 支持键盘 Tab 切换焦点
- [ ] 密码输入框支持显示/隐藏切换

PRD Template: Performance/Security Optimization

This template is suitable for non-functional improvement needs such as performance optimization and security hardening.

---

Document structure

# PRD: [Optimization name]

> **Document Version**: X.X
> **Status**: Draft / Under Review / Approved
> **Author**: [Author’s name]
> **Creation Date**: YYYY-MM-DD
> **Last Update**: YYYY-MM-DD

<!-- TRACEABILITY-METADATA:BEGIN -->

schema: name: testany-traceability version: "1.0.0" profile: prd-profile-v1 artifact: id: PRD-[DOMAIN]-001 type: PRD title: [Optimization name] status: draft owners: [] created_at: YYYY-MM-DD updated_at: YYYY-MM-DD source_documents: [] entities: requirements: [] risks: [] must_not_regress: [] external_behaviors: [] decisions: [] flows: [] test_cases: [] relations: [] waivers: []

<!-- TRACEABILITY-METADATA:END -->

---

## 1. Document Information

### 1.1 Basic Information

| Properties | Values ​​|
|------|-----|
| PRD Number | PRD-XXX |
| Products | [Product Name] |
| Priority | P0 / P1 / P2 / P3 |
| Estimated version | vX.X |
| Optimization Type | Performance Optimization / Security Hardening / Reliability Improvement |
| PRD baseline version | vX.X (HLD is based on this version) |
| Last sync date | YYYY-MM-DD |

### 1.2 Revision History

| Version | Date | Changes | Author |
|------|------|----------|------|
| X.X | YYYY-MM-DD | [Change description] | [Author] |

### 1.3 Glossary

| Terminology | Definition |
|------|------|
| [Term] | [Definition] |

---

## 2. Background and goals

### 2.1 Optimize background

[Describe why optimization is needed and what are the triggers]

- Business growth leads to performance bottlenecks
- Issues discovered by security audits
- User feedback
- Monitor alarms
- other reasons

### 2.2 Optimization goals

| Indicator | Current value (baseline) | Target value | Data source | Improvement |
|------|----------------|--------|----------|----------|
| [Indicator 1] | [Current value] | [Target value] | Already monitored/need to add | [Percent] |
| [Indicator 2] | [Current value] | [Target value] | Already monitored/need to add | [Percent] |

### 2.3 Constraints

- Does not change existing functional behavior
- Does not change user experience
- [Other constraints]

### 2.4 Relevant capability identification (mandatory)

| Existing capabilities | Capability scope | Matching degree with current needs | Capability gaps | Suggested directions | Source |
|----------|---------|--------------|---------|---------|------|
| [Capability name] | [Scope covered by this capability] | Complete match/Partial match/No match | [Gap description, fill in "None" if there is no gap] | Recommended reuse/Recommended reference/Need to create new | [Document/code path] |

> **Description**:
> - This table is a mandatory output to identify existing capabilities that can assist optimization (such as existing caching solutions, monitoring tools, security components, etc.)
> - **"Source" column is required**: You must indicate which document or code the capability was identified from, and no baseless guessing is allowed.
> - "Recommended directions" are only PRD suggestions, and the final reuse decision falls within the scope of HLD
> - If it is confirmed that there is no relevant ability, fill in "After investigation, there is no relevant ability" and explain the **scope of investigation** (which paths/keywords were searched)

---

## 3. Scope

### Within the scope of 3.1

- [Modules/scenarios to be optimized]

### 3.2 Out of range

- [Contents not within the scope of this optimization]

### 3.3 Matters to be confirmed

- [ ] [Items to be confirmed]

---

## 4. Problem analysis

### 4.1 Problem phenomenon

[Describe the observed problem phenomenon]

| Problem number | Problem description | Frequency of occurrence | Impact |
|----------|----------|----------|------|
| P-001 | [Description] | [Frequency] | [Effect] |

### 4.2 Baseline data

**Performance Data** (if applicable):

| Indicators | P50 | P90 | P99 |
|------|-----|-----|-----|
| [Indicator] | [Value] | [Value] | [Value] |

**Security Data** (if applicable):

| Problem type | Severity | How discovered |
|----------|----------|----------|
| [Type] | High/Medium/Low | [Mode] |

### 4.3 Root cause of the problem

[Analyze the root cause of the problem and describe it from a business perspective]

| Problem | Root Cause Analysis |
|------|----------|
| [Problem] | [Root Cause] |

---

## 5. Optimization goals

### 5.1 Target indicators

| Metrics | Current Baseline | Target Value | Priority |
|------|----------|--------|--------|
| [Indicator] | [Baseline] | [Target] | P0/P1/P2 |

### 5.2 Goal constraints

- Functional behavior remains unchanged
- No regression in performance (other indicators)
- [Other constraints]

> For specific optimization plans, see HLD

---

## 6. Verification requirements

### 6.1 Testing requirements

**Performance Test** (if applicable):

| Test items | Test conditions | Acceptance Criteria |
|--------|----------|----------|
| [Test Items] | [Conditions] | [Standards] |

**Security Test** (if applicable):

| Test Type | Coverage | Acceptance Criteria |
|----------|----------|----------|
| [Type] | [Range] | [Standard] |

### 6.2 Regression testing

- [ ] Functional regression testing
- [ ] Other performance indicators will not be rolled back

### 6.3 Benchmark comparison

| Metrics | Baseline before optimization | Target after optimization | Actual results |
|------|------------|------------|----------|
| [Indicator] | [Baseline value] | [Target value] | [To be filled in] |

---

## 7. Monitoring requirements

### 7.1 Monitoring indicators

| Indicator | Description | Alarm threshold |
|------|------|----------|
| [Indicator] | [Description] | [Threshold] |

### 7.2 Grayscale verification

| Stage | Traffic proportion | Duration | Observation indicators | Rollback conditions |
|------|----------|----------|----------|----------|
| Phase 1 | [Proportion] | [Time] | [Indicator] | [Condition] |

### 7.3 Long-term observation

| Observation period | Observation indicators | Expected trends |
|----------|----------|----------|
| 1 day | [Indicator] | [Trend] |
| 1 week | [Indicators] | [Trends] |

---

## 8. Non-functional requirements

### 8.1 Compatibility requirements

- Does not change existing functional behavior
- No changes to the external interface
- Does not affect existing users

### 8.2 Release requirements

| Requirements | Description |
|------|------|
| Grayscale strategy | [Whether grayscale is required, grayscale range] |
| Rollback capability | [Whether rollback needs to be supported and rollback conditions] |
| Function switch | [Whether function switch is required] |

> Note: For specific grayscale/rollback technical solutions, see HLD

### 8.3 Observability requirements

- [Monitoring coverage requirements]
- [Log requirements]

---

## 9. Dependencies and constraints

### 9.1 Known constraints

- [Business Constraints]
- [Time constraint]
- [Resource Constraints]

### 9.2 Risk Constraints

- [Unacceptable risk]

---

## 10. Project Plan

### 10.1 Milestones

| Milestones | Target dates | Deliverables |
|--------|----------|--------|
| Problem analysis completed | YYYY-MM-DD | Analysis report |
| Plan review passed | YYYY-MM-DD | PRD, HLD |
| Development completed | YYYY-MM-DD | Code |
| Test completed | YYYY-MM-DD | Test report |
| Grayscale release | YYYY-MM-DD | - |
| Full release | YYYY-MM-DD | - |
| Effect verification | YYYY-MM-DD | Verification report |

### 10.2 Resource Allocation

| Roles | People | Commitment |
|------|------|------|
| [role] | [personnel] | [ratio] |

---

## 11. Risks and Mitigations

| Risk | Impact | Probability | Mitigation |
|------|------|------|----------|
| Optimization effect not up to expectations | Medium | Medium | Phased verification |
| Introduce new issues | High | Low | Fully tested, grayscale release |
| Performance rollback | High | Low | Benchmark comparison, fast rollback |

---

## 12. Acceptance Criteria

### AC-001: Performance Goals Achieved
- [ ] [Indicator 1] reached target value [X]
- [ ] [Indicator 2] Target value reached [Y]

### AC-002: Functionality not affected
- [ ] All functions work properly
- [ ] All automated tests passed

### AC-003: Safety Goal Achieved (if applicable)
- [ ] [Security Issue 1] Fixed
- [ ] No high-risk vulnerabilities found in security scans

### AC-004: Improved monitoring
- [ ] Normal collection of monitoring indicators
- [ ] Alarm rules are configured correctly

---

## 13. Questions to be clarified

| Number | Question | Asked by | Status | Conclusion |
|------|------|--------|------|------|
| Q1 | [Question] | [Asker] | To be discussed/resolved | [Conclusion] |

---

## Appendix

### A. Performance analysis report

[link or inline]

### B. Security Scan Report

[link or inline]

---

Writing Guidance

Core points of optimizing PRD

1. Data-driven: Use data to explain problems and goals 2. Baseline comparison: Clear comparison before and after optimization 3. Clear goals: clear quantitative goals 4. Verification Complete: Detailed verification requirements 5. Grayscale verification: Verify the optimization effect in stages

Problem Analysis Chapter

Correct writing:

| Problem number | Problem description | Frequency of occurrence | Impact |
|----------|----------|----------|------|
| P-001 | The list page loads slowly | 100% during peak periods | Users wait for a long time and the conversion rate drops |
| P-002 | Search timeout | About 5% of requests per day | Poor user experience |

Wrong way of writing (too technical):

| Issue number | Issue description |
|----------|----------|
| P-001 | MySQL query does not use index, you need to add created_at index |

Optimization target chapter

Correct writing:

| Metrics | Current Baseline | Target Value | Priority |
|------|----------|--------|--------|
| List page loading time P99 | 3s | ≤ 1s | P0 |
| Search success rate | 95% | ≥ 99.5% | P0 |

Wrong writing (including technical solutions):

| Optimization items | Plans |
|--------|------|
| Add cache | Use Redis to cache hotspot data, TTL 5 minutes |
| Add index | Add (user_id, created_at) composite index to the orders table |

Grayscale verification form example

| Stage | Traffic proportion | Duration | Observation indicators | Rollback conditions |
|------|----------|----------|----------|----------|
| Phase 1 | 1% | 1 hour | Error rate, latency | Error rate > 1% |
| Phase 2 | 10% | 4 hours | Error rate, latency | Error rate > 0.5% |
| Phase 3 | 50% | 1 day | Error rate, latency, throughput | Error rate > 0.1% |
| Full amount | 100% | - | All indicators | - |

Example of acceptance criteria

### AC-001: Performance Goals Achieved
- [ ] List page P99 delay ≤ 1s
- [ ] Search success rate ≥ 99.5%
- [ ] Home page loading time ≤ 2s

### AC-002: Functionality not affected
- [ ] All functions work properly
- [ ] All automated tests passed
- [ ] User unaware

### AC-003: Improved monitoring
- [ ] New indicators are collected normally.
- [ ] Alarm rules are configured correctly
- [ ] You can see the optimization effect on the market

PRD 模板：性能/安全优化

本模板适用于性能优化、安全加固等非功能性改进需求。

---

文档结构

# PRD: [优化名称]

> **文档版本**: X.X
> **状态**: 草稿 / 评审中 / 已批准
> **作者**: [作者姓名]
> **创建日期**: YYYY-MM-DD
> **最后更新**: YYYY-MM-DD

<!-- TRACEABILITY-METADATA:BEGIN -->

schema: name: testany-traceability version: "1.0.0" profile: prd-profile-v1 artifact: id: PRD-[DOMAIN]-001 type: PRD title: [优化名称] status: draft owners: [] created_at: YYYY-MM-DD updated_at: YYYY-MM-DD source_documents: [] entities: requirements: [] risks: [] must_not_regress: [] external_behaviors: [] decisions: [] flows: [] test_cases: [] relations: [] waivers: []

<!-- TRACEABILITY-METADATA:END -->

---

## 1. 文档信息

### 1.1 基本信息

| 属性 | 值 |
|------|-----|
| PRD 编号 | PRD-XXX |
| 所属产品 | [产品名称] |
| 优先级 | P0 / P1 / P2 / P3 |
| 预计版本 | vX.X |
| 优化类型 | 性能优化 / 安全加固 / 可靠性提升 |
| PRD 基线版本 | vX.X（HLD 基于此版本） |
| 最后同步日期 | YYYY-MM-DD |

### 1.2 修订历史

| 版本 | 日期 | 变更内容 | 作者 |
|------|------|----------|------|
| X.X | YYYY-MM-DD | [变更描述] | [作者] |

### 1.3 术语表

| 术语 | 定义 |
|------|------|
| [术语] | [定义] |

---

## 2. 背景与目标

### 2.1 优化背景

[描述为什么需要优化，触发因素是什么]

- 业务增长导致性能瓶颈
- 安全审计发现的问题
- 用户反馈
- 监控告警
- 其他原因

### 2.2 优化目标

| 指标 | 当前值（基线） | 目标值 | 数据来源 | 提升幅度 |
|------|----------------|--------|----------|----------|
| [指标1] | [当前值] | [目标值] | 已有监控/需新增 | [百分比] |
| [指标2] | [当前值] | [目标值] | 已有监控/需新增 | [百分比] |

### 2.3 约束条件

- 不改变现有功能行为
- 不改变用户体验
- [其他约束]

### 2.4 相关能力识别（强制）

| 已有能力 | 能力范围 | 与本需求匹配度 | 能力差距 | 建议方向 | 来源 |
|----------|---------|--------------|---------|---------|------|
| [能力名称] | [该能力覆盖的范围] | 完全匹配/部分匹配/不匹配 | [差距描述，无差距填"无"] | 建议复用/建议参考/需新建 | [文档/代码路径] |

> **说明**：
> - 此表为强制输出，识别可辅助优化的已有能力（如已有的缓存方案、监控工具、安全组件等）
> - **「来源」列必填**：必须注明从哪个文档或代码中识别到该能力，禁止无依据猜测
> - 「建议方向」仅为 PRD 建议，最终复用决策属于 HLD 范畴
> - 如确认无相关能力，填写"经排查，无相关已有能力"并说明**排查范围**（搜索了哪些路径/关键词）

---

## 3. 范围

### 3.1 范围内

- [要优化的模块/场景]

### 3.2 范围外

- [不在本次优化范围的内容]

### 3.3 待确认事项

- [ ] [待确认事项]

---

## 4. 问题分析

### 4.1 问题现象

[描述观察到的问题现象]

| 问题编号 | 问题描述 | 发生频率 | 影响 |
|----------|----------|----------|------|
| P-001 | [描述] | [频率] | [影响] |

### 4.2 基线数据

**性能数据**（如适用）：

| 指标 | P50 | P90 | P99 |
|------|-----|-----|-----|
| [指标] | [值] | [值] | [值] |

**安全数据**（如适用）：

| 问题类型 | 严重程度 | 发现方式 |
|----------|----------|----------|
| [类型] | 高/中/低 | [方式] |

### 4.3 问题根因

[分析问题的根本原因，从业务角度描述]

| 问题 | 根因分析 |
|------|----------|
| [问题] | [根因] |

---

## 5. 优化目标

### 5.1 目标指标

| 指标 | 当前基线 | 目标值 | 优先级 |
|------|----------|--------|--------|
| [指标] | [基线] | [目标] | P0/P1/P2 |

### 5.2 目标约束

- 功能行为保持不变
- 性能不出现回退（其他指标）
- [其他约束]

> 具体优化方案见 HLD

---

## 6. 验证要求

### 6.1 测试要求

**性能测试**（如适用）：

| 测试项 | 测试条件 | 验收标准 |
|--------|----------|----------|
| [测试项] | [条件] | [标准] |

**安全测试**（如适用）：

| 测试类型 | 覆盖范围 | 验收标准 |
|----------|----------|----------|
| [类型] | [范围] | [标准] |

### 6.2 回归测试

- [ ] 功能回归测试
- [ ] 其他性能指标不回退

### 6.3 基准对比

| 指标 | 优化前基线 | 优化后目标 | 实际结果 |
|------|------------|------------|----------|
| [指标] | [基线值] | [目标值] | [待填写] |

---

## 7. 监控要求

### 7.1 监控指标

| 指标 | 说明 | 告警阈值 |
|------|------|----------|
| [指标] | [说明] | [阈值] |

### 7.2 灰度验证

| 阶段 | 流量比例 | 持续时间 | 观察指标 | 回滚条件 |
|------|----------|----------|----------|----------|
| 阶段1 | [比例] | [时间] | [指标] | [条件] |

### 7.3 长期观察

| 观察周期 | 观察指标 | 预期趋势 |
|----------|----------|----------|
| 1天 | [指标] | [趋势] |
| 1周 | [指标] | [趋势] |

---

## 8. 非功能需求

### 8.1 兼容性要求

- 不改变现有功能行为
- 不改变对外接口
- 不影响现有用户使用

### 8.2 发布要求

| 要求 | 说明 |
|------|------|
| 灰度策略 | [是否需要灰度，灰度范围] |
| 回滚能力 | [是否需要支持回滚，回滚条件] |
| 功能开关 | [是否需要功能开关] |

> 注：具体灰度/回滚技术方案见 HLD

### 8.3 可观测性要求

- [监控覆盖要求]
- [日志要求]

---

## 9. 依赖与约束

### 9.1 已知约束

- [业务约束]
- [时间约束]
- [资源约束]

### 9.2 风险约束

- [不能接受的风险]

---

## 10. 项目计划

### 10.1 里程碑

| 里程碑 | 目标日期 | 交付物 |
|--------|----------|--------|
| 问题分析完成 | YYYY-MM-DD | 分析报告 |
| 方案评审通过 | YYYY-MM-DD | PRD、HLD |
| 开发完成 | YYYY-MM-DD | 代码 |
| 测试完成 | YYYY-MM-DD | 测试报告 |
| 灰度发布 | YYYY-MM-DD | - |
| 全量发布 | YYYY-MM-DD | - |
| 效果验证 | YYYY-MM-DD | 验证报告 |

### 10.2 资源分配

| 角色 | 人员 | 投入 |
|------|------|------|
| [角色] | [人员] | [比例] |

---

## 11. 风险与缓解

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| 优化效果不达预期 | 中 | 中 | 分阶段验证 |
| 引入新问题 | 高 | 低 | 充分测试，灰度发布 |
| 性能回退 | 高 | 低 | 基准对比，快速回滚 |

---

## 12. 验收标准

### AC-001: 性能目标达成
- [ ] [指标1] 达到目标值 [X]
- [ ] [指标2] 达到目标值 [Y]

### AC-002: 功能不受影响
- [ ] 所有功能正常工作
- [ ] 所有自动化测试通过

### AC-003: 安全目标达成（如适用）
- [ ] [安全问题1] 已修复
- [ ] 安全扫描无高危漏洞

### AC-004: 监控完善
- [ ] 监控指标正常采集
- [ ] 告警规则正确配置

---

## 13. 待澄清问题

| 编号 | 问题 | 提出人 | 状态 | 结论 |
|------|------|--------|------|------|
| Q1 | [问题] | [提出人] | 待讨论/已解决 | [结论] |

---

## 附录

### A. 性能分析报告

[链接或内联]

### B. 安全扫描报告

[链接或内联]

---

写作指导

优化 PRD 的核心要点

1. 数据驱动：用数据说明问题和目标 2. 基线对比：明确优化前后的对比 3. 目标明确：清晰的量化目标 4. 验证完善：详细的验证要求 5. 灰度验证：分阶段验证优化效果

问题分析章节

正确写法：

| 问题编号 | 问题描述 | 发生频率 | 影响 |
|----------|----------|----------|------|
| P-001 | 列表页加载慢 | 高峰期 100% | 用户等待时间长，转化率下降 |
| P-002 | 搜索超时 | 每天约 5% 请求 | 用户体验差 |

错误写法（过于技术化）：

| 问题编号 | 问题描述 |
|----------|----------|
| P-001 | MySQL 查询没有走索引，需要添加 created_at 索引 |

优化目标章节

正确写法：

| 指标 | 当前基线 | 目标值 | 优先级 |
|------|----------|--------|--------|
| 列表页加载时间 P99 | 3s | ≤ 1s | P0 |
| 搜索成功率 | 95% | ≥ 99.5% | P0 |

错误写法（包含技术方案）：

| 优化项 | 方案 |
|--------|------|
| 加缓存 | 使用 Redis 缓存热点数据，TTL 5 分钟 |
| 加索引 | 在 orders 表添加 (user_id, created_at) 复合索引 |

灰度验证表格示例

| 阶段 | 流量比例 | 持续时间 | 观察指标 | 回滚条件 |
|------|----------|----------|----------|----------|
| 阶段1 | 1% | 1小时 | 错误率、延迟 | 错误率 > 1% |
| 阶段2 | 10% | 4小时 | 错误率、延迟 | 错误率 > 0.5% |
| 阶段3 | 50% | 1天 | 错误率、延迟、吞吐 | 错误率 > 0.1% |
| 全量 | 100% | - | 全部指标 | - |

验收标准示例

### AC-001: 性能目标达成
- [ ] 列表页 P99 延迟 ≤ 1s
- [ ] 搜索成功率 ≥ 99.5%
- [ ] 首页加载时间 ≤ 2s

### AC-002: 功能不受影响
- [ ] 所有功能正常工作
- [ ] 所有自动化测试通过
- [ ] 用户无感知

### AC-003: 监控完善
- [ ] 新增指标正常采集
- [ ] 告警规则正确配置
- [ ] 大盘可以看到优化效果

PRD Template: functional refactoring

This template is suitable for architectural adjustment, technical debt cleanup, module splitting and other needs that do not change external functions but change internal implementation.

---

Document structure

# PRD: [refactoring name]

> **Document Version**: X.X
> **Status**: Draft / Under Review / Approved
> **Author**: [Author’s name]
> **Creation Date**: YYYY-MM-DD
> **Last Update**: YYYY-MM-DD

<!-- TRACEABILITY-METADATA:BEGIN -->

schema: name: testany-traceability version: "1.0.0" profile: prd-profile-v1 artifact: id: PRD-[DOMAIN]-001 type: PRD title: [refactoring name] status: draft owners: [] created_at: YYYY-MM-DD updated_at: YYYY-MM-DD source_documents: [] entities: requirements: [] risks: [] must_not_regress: [] external_behaviors: [] decisions: [] flows: [] test_cases: [] relations: [] waivers: []

<!-- TRACEABILITY-METADATA:END -->

---

## 1. Document Information

### 1.1 Basic Information

| Properties | Values ​​|
|------|-----|
| PRD Number | PRD-XXX |
| Products | [Product Name] |
| Priority | P0 / P1 / P2 / P3 |
| Estimated version | vX.X |
| PRD baseline version | vX.X (HLD is based on this version) |
| Last sync date | YYYY-MM-DD |

### 1.2 Revision History

| Version | Date | Changes | Author |
|------|------|----------|------|
| X.X | YYYY-MM-DD | [Change description] | [Author] |

### 1.3 Glossary

| Terminology | Definition |
|------|------|
| [Term] | [Definition] |

---

## 2. Background and goals

### 2.1 Reconstruction background

[Describe why refactoring is needed]

### 2.2 Refactoring goals

[Describe the desired state after refactoring]

1. **Goal 1**: [Specific description]
2. **Goal 2**: [Specific description]

### 2.3 Success Indicators

| Indicator | Current value | Target value | Data source | Measurement method |
|------|--------|--------|----------|----------|
| [Indicator] | [Current] | [Target] | Already monitored/need to add | [Measurement method] |

### 2.4 What not to do

Clearly state that this refactoring does not include functional changes:

- Does not change the behavior of [Feature A]
- Does not change user experience
- Do not change the external interface contract

### 2.5 Relevant capability identification (mandatory)

| Existing capabilities | Capability scope | Matching degree with current needs | Capability gaps | Suggested directions | Source |
|----------|---------|--------------|---------|---------|------|
| [Capability name] | [Scope covered by this capability] | Complete match/Partial match/No match | [Gap description, fill in "None" if there is no gap] | Recommended reuse/Recommended reference/Need to create new | [Document/code path] |

> **Description**:
> - This table is a mandatory output, identifying existing capabilities that can assist refactoring (such as existing design patterns, tool libraries, test frameworks, etc.)
> - **"Source" column is required**: You must indicate which document or code the capability was identified from, and no baseless guessing is allowed.
> - "Recommended directions" are only PRD suggestions, and the final reuse decision falls within the scope of HLD
> - If it is confirmed that there is no relevant ability, fill in "After investigation, there is no relevant ability" and explain the **scope of investigation** (which paths/keywords were searched)

---

## 3. Scope

### Within the scope of 3.1

- [Module/Component to be refactored]

### 3.2 Out of range

- [Modules that are not within the scope of this reconstruction]

### 3.3 Matters to be confirmed

- [ ] [Items to be confirmed]

---

## 4. Current situation analysis

### 4.1 Problems

| Issue Number | Issue Description | Impact | Severity |
|----------|----------|------|----------|
| P-001 | [Problem Description] | [Impact Description] | High/Medium/Low |
| P-002 | [Problem Description] | [Impact Description] | High/Medium/Low |

### 4.2 Root cause of the problem

[Analyze the root cause of the problem]

### 4.3 Current situation assessment

| Dimensions | Current Status | Issues |
|------|----------|------|
| [Dimension] | [Status Description] | [Problem Description] |

---

## 5. Reconstruct target state

### 5.1 Desired state

[Describe the expected state after reconstruction, not involving specific technical solutions]

| Dimensions | Current status | Target status |
|------|----------|----------|
| [dimension] | [current] | [target] |

### 5.2 Problem Solving Mapping

| Problem number | Problem description | How to resolve |
|----------|----------|----------|
| P-001 | [Problem description] | [Solution direction, non-technical solution] |
| P-002 | [Problem description] | [Solution direction, non-technical solution] |

> For specific technical solutions, see HLD

---

## 6. Compatibility requirements

### 6.1 Functional compatibility

| Requirements | Description |
|------|------|
| Functional Behavior | All existing functional behaviors remain unchanged |
| User experience | User insensible |
| External interface | The interface contract remains unchanged |

### 6.2 Data Compatibility

| Requirements | Description |
|------|------|
| Existing Data | [Compatibility Requirements] |
| Data migration | [Whether migration is required] |

### 6.3 Release requirements

| Requirements | Description |
|------|------|
| Grayscale strategy | [Whether grayscale is required, grayscale range] |
| Rollback capability | [Whether rollback needs to be supported and rollback conditions] |
| Function switch | [Whether function switch is required] |
| Transition period | [Requirements for parallel operation of old and new, if necessary] |

> Note: For specific grayscale/rollback technical solutions, see HLD

---

## 7. Verification requirements

### 7.1 Function Verification

- [ ] All existing features work properly
- [ ] All automated tests passed
- [ ] Key business process verification passed

### 7.2 Performance Verification

| Indicators | Baseline values ​​| Allowed fluctuations |
|------|--------|----------|
| [Indicator] | [Baseline Value] | ±[X]% |

### 7.3 Regression verification

- [ ] [Regression Test Scope]

---

## 8. Non-functional requirements

### 8.1 Performance requirements

- Performance after reconstruction is not lower than before reconstruction

### 8.2 Observability requirements

- [Monitoring requirements]
- [Log requirements]

---

## 9. Dependencies and constraints

### 9.1 Known constraints

- [Business Constraints]
- [Time constraint]

### 9.2 Risk Constraints

- [Unacceptable risk]

---

## 10. Project Plan

### 10.1 Milestones

| Milestones | Target dates | Deliverables |
|--------|----------|--------|
| Plan review passed | YYYY-MM-DD | PRD, HLD |
| Development completed | YYYY-MM-DD | Code |
| Test completed | YYYY-MM-DD | Test report |
| Grayscale release | YYYY-MM-DD | Grayscale environment |
| Full release | YYYY-MM-DD | Production environment |
| Old code offline | YYYY-MM-DD | Cleanup completed |

### 10.2 Resource Allocation

| Roles | People | Commitment |
|------|------|------|
| [role] | [personnel] | [ratio] |

---

## 11. Risks and Mitigations

| Risk | Impact | Probability | Mitigation |
|------|------|------|----------|
| Incomplete scope of impact assessment | High | Medium | Sufficient testing and grayscale |
| Performance rollback | High | Low | Performance test comparison |
| Data Inconsistency | High | Low | Data Verification |
| [Other risks] | [Impact] | [Probability] | [Measures] |

---

## 12. Acceptance Criteria

### AC-001: Function unchanged
- [ ] All existing features work properly
- [ ] All interface contracts remain unchanged
- [ ] All automated tests passed

### AC-002: No performance regression
- [ ] [Indicator 1] Not lower than the baseline before reconstruction
- [ ] [Indicator 2] Not lower than the baseline before reconstruction

### AC-003: Problem Solving
- [ ] [Issue P-001] Resolved
- [ ] [Issue P-002] Resolved

### AC-004: Release completed
- [ ] Grayscale release without exception
- [ ] Full release without exception

---

## 13. Questions to be clarified

| Number | Question | Asked by | Status | Conclusion |
|------|------|--------|------|------|
| Q1 | [Question] | [Asker] | To be discussed/resolved | [Conclusion] |

---

## Appendix

[If any additional content]

---

Writing Guidance

Reconstructing the core points of PRD

1. Clear "what not to do": Refactoring should not change external behavior and should be clearly stated 2. Problem-driven: Explain clearly the problems of the current situation and what should be solved by refactoring 3. Goal state: Describes the desired state rather than specific technical solutions 4. Compatibility: Clarify compatibility requirements 5. Verification Requirements: How to verify successful refactoring

Current Situation Analysis Chapter

Correct writing:

| Issue Number | Issue Description | Impact | Severity |
|----------|----------|------|----------|
| P-001 | Module responsibilities are not clear, modifying one place affects many places | Development efficiency is low, bug rate is high | High |
| P-002 | Severe code duplication | High maintenance costs | Medium |

Wrong way of writing (too technical):

| Issue number | Issue description |
|----------|----------|
| P-001 | UserService has 2000 lines of code and needs to be split into UserQueryService and UserCommandService |

Reconstruct the target state chapter

Correct writing:

| Dimensions | Current status | Target status |
|------|----------|----------|
| Module responsibilities | Confused responsibilities | Single responsibilities and clear boundaries |
| Code duplication | Repeated logic in many places | Logic reuse, no duplication |
| Testability | Difficult to unit test | Independently testable |

Wrong writing (crossing the boundary to HLD):

| Changes | Current | Target |
|--------|------|------|
| UserService.ts | Single file 2000 lines | Split into 3 files |
| Database queries | Direct SQL | Using Repository mode |

Example of acceptance criteria

### AC-001: Function unchanged
- [ ] The user login process is normal
- [ ] The order creation process is normal
- [ ] All API return formats remain unchanged
- [ ] All automated tests passed

### AC-002: No performance regression
- [ ] Login interface P99 delay is no higher than before reconstruction
- [ ] Order query QPS is not lower than before reconstruction

### AC-003: Problem Solving
- [ ] Modifying the user module no longer affects the order module
- [ ] Improve the development efficiency of new functions (subjective evaluation)

PRD 模板：功能重构

本模板适用于架构调整、技术债清理、模块拆分等不改变外部功能但改变内部实现的需求。

---

文档结构

# PRD: [重构名称]

> **文档版本**: X.X
> **状态**: 草稿 / 评审中 / 已批准
> **作者**: [作者姓名]
> **创建日期**: YYYY-MM-DD
> **最后更新**: YYYY-MM-DD

<!-- TRACEABILITY-METADATA:BEGIN -->

schema: name: testany-traceability version: "1.0.0" profile: prd-profile-v1 artifact: id: PRD-[DOMAIN]-001 type: PRD title: [重构名称] status: draft owners: [] created_at: YYYY-MM-DD updated_at: YYYY-MM-DD source_documents: [] entities: requirements: [] risks: [] must_not_regress: [] external_behaviors: [] decisions: [] flows: [] test_cases: [] relations: [] waivers: []

<!-- TRACEABILITY-METADATA:END -->

---

## 1. 文档信息

### 1.1 基本信息

| 属性 | 值 |
|------|-----|
| PRD 编号 | PRD-XXX |
| 所属产品 | [产品名称] |
| 优先级 | P0 / P1 / P2 / P3 |
| 预计版本 | vX.X |
| PRD 基线版本 | vX.X（HLD 基于此版本） |
| 最后同步日期 | YYYY-MM-DD |

### 1.2 修订历史

| 版本 | 日期 | 变更内容 | 作者 |
|------|------|----------|------|
| X.X | YYYY-MM-DD | [变更描述] | [作者] |

### 1.3 术语表

| 术语 | 定义 |
|------|------|
| [术语] | [定义] |

---

## 2. 背景与目标

### 2.1 重构背景

[描述为什么需要重构]

### 2.2 重构目标

[描述重构后期望达成的状态]

1. **目标1**：[具体描述]
2. **目标2**：[具体描述]

### 2.3 成功指标

| 指标 | 当前值 | 目标值 | 数据来源 | 度量方式 |
|------|--------|--------|----------|----------|
| [指标] | [当前] | [目标] | 已有监控/需新增 | [度量方式] |

### 2.4 不做什么

明确声明此次重构**不包含**功能变更：

- 不改变 [功能A] 的行为
- 不改变用户体验
- 不改变对外接口契约

### 2.5 相关能力识别（强制）

| 已有能力 | 能力范围 | 与本需求匹配度 | 能力差距 | 建议方向 | 来源 |
|----------|---------|--------------|---------|---------|------|
| [能力名称] | [该能力覆盖的范围] | 完全匹配/部分匹配/不匹配 | [差距描述，无差距填"无"] | 建议复用/建议参考/需新建 | [文档/代码路径] |

> **说明**：
> - 此表为强制输出，识别可辅助重构的已有能力（如已有的设计模式、工具库、测试框架等）
> - **「来源」列必填**：必须注明从哪个文档或代码中识别到该能力，禁止无依据猜测
> - 「建议方向」仅为 PRD 建议，最终复用决策属于 HLD 范畴
> - 如确认无相关能力，填写"经排查，无相关已有能力"并说明**排查范围**（搜索了哪些路径/关键词）

---

## 3. 范围

### 3.1 范围内

- [要重构的模块/组件]

### 3.2 范围外

- [不在本次重构范围的模块]

### 3.3 待确认事项

- [ ] [待确认事项]

---

## 4. 现状分析

### 4.1 存在的问题

| 问题编号 | 问题描述 | 影响 | 严重程度 |
|----------|----------|------|----------|
| P-001 | [问题描述] | [影响描述] | 高/中/低 |
| P-002 | [问题描述] | [影响描述] | 高/中/低 |

### 4.2 问题根因

[分析导致问题的根本原因]

### 4.3 现状评估

| 维度 | 当前状态 | 问题 |
|------|----------|------|
| [维度] | [状态描述] | [问题描述] |

---

## 5. 重构目标状态

### 5.1 期望状态

[描述重构后的期望状态，不涉及具体技术方案]

| 维度 | 当前状态 | 目标状态 |
|------|----------|----------|
| [维度] | [当前] | [目标] |

### 5.2 问题解决映射

| 问题编号 | 问题描述 | 如何解决 |
|----------|----------|----------|
| P-001 | [问题描述] | [解决方向，非技术方案] |
| P-002 | [问题描述] | [解决方向，非技术方案] |

> 具体技术方案见 HLD

---

## 6. 兼容性要求

### 6.1 功能兼容

| 要求 | 说明 |
|------|------|
| 功能行为 | 所有现有功能行为保持不变 |
| 用户体验 | 用户无感知 |
| 对外接口 | 接口契约保持不变 |

### 6.2 数据兼容

| 要求 | 说明 |
|------|------|
| 现有数据 | [兼容性要求] |
| 数据迁移 | [是否需要迁移] |

### 6.3 发布要求

| 要求 | 说明 |
|------|------|
| 灰度策略 | [是否需要灰度，灰度范围] |
| 回滚能力 | [是否需要支持回滚，回滚条件] |
| 功能开关 | [是否需要功能开关] |
| 过渡期 | [新旧并行运行要求，如需要] |

> 注：具体灰度/回滚技术方案见 HLD

---

## 7. 验证要求

### 7.1 功能验证

- [ ] 所有现有功能正常工作
- [ ] 所有自动化测试通过
- [ ] 关键业务流程验证通过

### 7.2 性能验证

| 指标 | 基准值 | 允许波动 |
|------|--------|----------|
| [指标] | [基准值] | ±[X]% |

### 7.3 回归验证

- [ ] [回归测试范围]

---

## 8. 非功能需求

### 8.1 性能要求

- 重构后性能不低于重构前

### 8.2 可观测性要求

- [监控要求]
- [日志要求]

---

## 9. 依赖与约束

### 9.1 已知约束

- [业务约束]
- [时间约束]

### 9.2 风险约束

- [不能接受的风险]

---

## 10. 项目计划

### 10.1 里程碑

| 里程碑 | 目标日期 | 交付物 |
|--------|----------|--------|
| 方案评审通过 | YYYY-MM-DD | PRD、HLD |
| 开发完成 | YYYY-MM-DD | 代码 |
| 测试完成 | YYYY-MM-DD | 测试报告 |
| 灰度发布 | YYYY-MM-DD | 灰度环境 |
| 全量发布 | YYYY-MM-DD | 生产环境 |
| 旧代码下线 | YYYY-MM-DD | 清理完成 |

### 10.2 资源分配

| 角色 | 人员 | 投入 |
|------|------|------|
| [角色] | [人员] | [比例] |

---

## 11. 风险与缓解

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| 影响范围评估不全 | 高 | 中 | 充分的测试和灰度 |
| 性能回退 | 高 | 低 | 性能测试对比 |
| 数据不一致 | 高 | 低 | 数据校验 |
| [其他风险] | [影响] | [概率] | [措施] |

---

## 12. 验收标准

### AC-001: 功能不变
- [ ] 所有现有功能正常工作
- [ ] 所有接口契约保持不变
- [ ] 所有自动化测试通过

### AC-002: 性能不回退
- [ ] [指标1] 不低于重构前基准
- [ ] [指标2] 不低于重构前基准

### AC-003: 问题解决
- [ ] [问题P-001] 已解决
- [ ] [问题P-002] 已解决

### AC-004: 发布完成
- [ ] 灰度发布无异常
- [ ] 全量发布无异常

---

## 13. 待澄清问题

| 编号 | 问题 | 提出人 | 状态 | 结论 |
|------|------|--------|------|------|
| Q1 | [问题] | [提出人] | 待讨论/已解决 | [结论] |

---

## 附录

[如有附加内容]

---

写作指导

重构 PRD 的核心要点

1. 明确"不做什么"：重构不应改变外部行为，要明确声明 2. 问题驱动：说清楚现状的问题，以及重构要解决什么 3. 目标状态：描述期望达到的状态，而非具体技术方案 4. 兼容性：明确兼容性要求 5. 验证要求：如何验证重构成功

现状分析章节

正确写法：

| 问题编号 | 问题描述 | 影响 | 严重程度 |
|----------|----------|------|----------|
| P-001 | 模块职责不清晰，修改一处影响多处 | 开发效率低，bug 率高 | 高 |
| P-002 | 代码重复严重 | 维护成本高 | 中 |

错误写法（过于技术化）：

| 问题编号 | 问题描述 |
|----------|----------|
| P-001 | UserService 有 2000 行代码，需要拆分为 UserQueryService 和 UserCommandService |

重构目标状态章节

正确写法：

| 维度 | 当前状态 | 目标状态 |
|------|----------|----------|
| 模块职责 | 职责混乱 | 职责单一、边界清晰 |
| 代码重复 | 多处重复逻辑 | 逻辑复用、无重复 |
| 可测试性 | 难以单元测试 | 可独立测试 |

错误写法（越界到 HLD）：

| 变更项 | 当前 | 目标 |
|--------|------|------|
| UserService.ts | 单文件 2000 行 | 拆分为 3 个文件 |
| 数据库查询 | 直接 SQL | 使用 Repository 模式 |

验收标准示例

### AC-001: 功能不变
- [ ] 用户登录流程正常
- [ ] 订单创建流程正常
- [ ] 所有 API 返回格式不变
- [ ] 所有自动化测试通过

### AC-002: 性能不回退
- [ ] 登录接口 P99 延迟不高于重构前
- [ ] 订单查询 QPS 不低于重构前

### AC-003: 问题解决
- [ ] 修改用户模块不再影响订单模块
- [ ] 新增功能开发效率提升（主观评估）