---
id: <ID>                 # 例如 FEAT-001；全局唯一
title: <标题>
status: draft            # draft / frozen / red / implementing / uat / done / terminated
gate1: pending           # pending / approved / rejected
gate2: pending
gate4: pending
prdVersion: 1
---

# <ID> <标题>

## 当前状态一览

> 一屏内可读完，只写"现在是什么状态"，不留沿革；随每次交付就地更新。
> 与正文冲突时**以顶部为准**。

- 交付状态：<当前环节 + 下一步>
- 预期红绿：<N 绿 / M 红；红的分诊>
- 未决事项：<`Q-N` 列表 / 无>
- 最后更新轮次：<rN>

---

## 1. 来源与裁定追溯

> 本 PRD 的每条判据都必须能追溯回需求核对件的裁定；**不得在这里发明新业务口径** —— 需要新口径一律进 §7 待确认事项，由人裁定。

| 项 | 内容 |
| --- | --- |
| 来源 | `docs/process/input/<ID>-需求核对件.md`（Gate0 产物，**裁定 `R-NN` 是权威来源**） |
| 裁定追溯 | `R-01` ~ `R-NN` 逐条：本 PRD 由哪条 AC / 边界承接（见下表） |
| 契约 | `docs/process/contracts/<ID>.md` |
| 设计与说明 | `docs/process/prd/<ID>-design.md`（逐条对齐 `R-NN`） |

| `R-NN` | 裁定一句话 | 承接处（AC / E 编号） |
| --- | --- | --- |
| `R-01` | <一句话> | <AC-1 / E-1> |
| `R-02` | <一句话> | <AC-2> |

---

## 2. 范围与非目标

| 项 | 内容 |
| --- | --- |
| 输入定位 | <该需求在业务中的位置；属于平台能力层还是业务应用层> |
| 本次范围 | <做什么> |
| 非目标（明确不做） | <逐条列出不做什么，避免范围蔓延；与核对件 §6 保持一致> |

> 存量（已实现）行为**保留并按其口径写断言**，不因新需求而删减 —— 这些断言若变红，即「现状与新口径不符」的真缺口，是本包最有价值的产出。新增区只放未实现的新实体 / 新端点 / 新行为。

---

## 3. 端覆盖表

> 全栈需求必填，防后端之外的范围被静默切掉。涉及但不在本 PRD 的端，**必须在本节依赖栏登记**（谁做、哪个 PRD、是否阻塞本 PRD 的验收）。

| 端 | 是否涉及 | 归属 | 依赖 / 阻塞说明 |
| --- | --- | --- | --- |
| `<app-a>`（后端 API） | 是 / 否 | 本 PRD / 另立 PRD（注明 ID）/ 不适用 | <是否阻塞本 PRD 的验收> |
| `<app-b>` | 是 / 否 | 同上 | <…> |
| `<app-c>` | 是 / 否 | 同上 | <…> |
| 智能体卡片 / 工具 | 是 / 否 | 同上 | <…> |

---

## 4. 验收标准（`AC-N`，Given / When / Then）

> **标题格式（强制）**：`### AC-N <中文短名（6–12 字）>｜<一句话结论>`。短名取材于结论句主干、**一处定死**，下游（台账 / 契约 / uat 清单 / 测试 / 报告 / 证据文件名）一律照抄，禁止另起别名。
> 每条 AC 必须**可自动化断言**：给出**具体期望值**（状态码、`code` 字段值、字段名、类型、数量、顺序、文案关键字）。避免「正确」「正常」「合理」等不可断言措辞。
> UI / 移动端 / 卡片类 AC 的 **Then** 写**用户可观察行为**（元素出现 / 文案关键字 / 页面跳转 / 卡片弹出与字段）；可自动化的标注断言方式，不可自动化的归 §6 产品验收清单。
> 「对应测试用例」列由测试角色回填，命名形如 `TC-<ID>-01`。

### AC-1 <中文短名>｜<一句话结论>

- **Given** <前置状态，含具体数据>
- **When** <触发动作，含请求方法与入参>
- **Then** <可断言的期望结果>
- **可验证性要素** <见下方清单，逐项给值>
- **对应测试用例**：`TC-<ID>-01`

### AC-2 <中文短名>｜<一句话结论>

- **Given** <前置状态>
- **When** <触发动作>
- **Then** <可断言结果>
- **可验证性要素** <…>
- **对应测试用例**：`TC-<ID>-02`

### AC 可验证性要素（缺一即判 AC 不合格，测试有权拒收）

1. **边界四要素**（凡涉及阈值 / 时间窗 / 数量上限）：内一点（应通过）、外一点（应拒绝）、两端各一点（闭区间）、两端外各一秒 / 一单位（应拒绝）。
2. **判定粒度显式**：写清「分钟级 / 秒级 / 毫秒级」，禁止只写"含端点"。
3. **平台差异声明**：凡依赖运行时行为（JSON 库、文件系统、时区、编码、原生 API、内存模型）的 AC，必须写明「桌面 / 单测 与 真机 行为是否一致」；不一致的必须给出能在桌面环境抓住它的判据。
4. **数值口径**：涉及估算 / 换算的，写明是「实测值」还是「估算兜底值」。
5. **阈值类判据自带可分辨性**：凡**门限 + 统计量**（中位数 / 比例 / 分位）的 AC，必须至少写明其一 —— ① 最小样本量 / 最小重复次数；② 「测量步长 < 判定余量」的证明；③ 两者都给不出 ⇒ 不得作为停点判据，只能当观察项。

---

## 5. 边界与异常（`E-N`）

| # | 场景 | 期望行为 | 可断言点 | 对应测试用例 |
| --- | --- | --- | --- | --- |
| `E-1` <中文短名> | <空数据 / 超长 / 重复 / 越权 / 网络中断 / 并发> | <期望行为> | 状态码 / `code` / `data` | `TC-<ID>-E01` |
| `E-2` <中文短名> | <…> | <…> | <…> | `TC-<ID>-E02` |

> **每条边界同样要起 6–12 字中文短名**，供 uat 清单与证据文件名复用。
> 所有多语句写操作必须体现**原子性**（失败不产生部分写入的中间态）——这是可断言的业务约束。
> 错误码判别：`403` = 无权访问该资源；`409` = 有权但此操作对任何有权主体都不允许；`400` 只留入参非法。
> **编号命名空间**：`E-N` = 边界 / 异常（唯一允许被台账与用例名引用的命名空间）；勘误一律用 `ER-N`，不得与 `E-N` 混用。

---

## 6. 产品验收清单

> 业务语言，产品可照着逐步点击核对。每条与上方 AC 编号对应；「对应 AC」列写 `中文短名（AC-N）`。
> 本清单是 uat 验收的输入；uat 清单另由 pm 在验收开工前产出，并合并本表判据。

| # | 操作步骤（产品视角） | 预期观察到的结果 | 对应 AC |
| --- | --- | --- | --- |
| 1 | <步骤> | <可观察结果> | <中文短名>（AC-1） |
| 2 | <步骤> | <可观察结果> | <中文短名>（AC-2） |

---

## 7. 待确认事项（[待人类确认]）

> 只装核对件之后**新产生**的歧义（新裁定引发 / 新端引入），并逐条标注来源。核对件里人已裁定的 `R-NN` **不得**再以 Q 形式出现。
> **收敛要求**：`Q` 总数必须**递减或持平**。**禁止编造**：口径不明确一律在此列出等人裁定。
> 设计与说明中被判为「偏差 / 未落实」的 `R-NN` 若需改口径，其裁定也必须回流到本表，不得自行决定。

| # | 待确认问题 | 影响范围 | 建议选项 | 来源 | 状态 |
| --- | --- | --- | --- | --- | --- |
| `Q-1` | <问题> | <影响> | **A**… **B**… | <来源> | 待确认 |

> **未冻结判据不得进测试**：本 PRD 中「以 Q-x 裁定为准」「或 HTTP」这类未决措辞，在进测试前必须清零。

---

## 8. 契约指针

| 项 | 内容 |
| --- | --- |
| 契约文件 | `docs/process/contracts/<ID>.md` |
| 端点 / 实体清单 | <逐条列出；每个端点标 `alignment`：`keep`（沿用现状）/ `change`（现状→目标，必附差异）/ `new`（新增）> |
| 权限码 | <本 PRD 用到的**全部**权限码集中列出，供 Gate1 核对；格式 `{模块}:{资源}:{操作}`> |
| 数据契约 | <实体 / 字段 / 类型 / 约束 / 关系，只描述契约层，不写 SQL / DDL / 索引实现 / 迁移方案> |
| 可测性条款 | <凡写「必须导出可进程内调用的入口」这类条款，紧邻处必须给出测试侧可达的 import 路径> |

---

## 9. 设计与说明指针

| 项 | 内容 |
| --- | --- |
| 设计与说明文件 | `docs/process/prd/<ID>-design.md` |
| `R-NN` 对齐结论 | <已落实 N / 偏差 M / 未落实 K；逐条见该文件对齐表> |
| 偏差与未落实项 | <有则列出并注明原因与建议处置；无则写「无」> |

> Gate1 一次审三件：PRD + 契约 + 设计与说明。**设计与说明未能逐条对上 `R-NN` 的，不得放行。**

---

## 10. 依赖与风险

| # | 类型 | 内容 | 影响 |
| --- | --- | --- | --- |
| `D-1` | 依赖 | <依赖> | <影响> |
| `R-1` | 风险 | <风险> | <影响> |

---

## 11. 变更记录

> **闸门字段值一律不涂改**（它们记的是"当时确实通过了"这一历史事实）。
> 「单条 AC 作废」= 交付范围只减不增 ⇒ 不回退状态、走流程回溯（标注去除 / supersede + 同步台账 + 删改测试），**必须留痕**。
> 「AC 语义变更」（出现了没人审过的新要求）⇒ `status` 回落 `frozen`、重做判据、重判闸门，**现行未判对象写进注记、不写进值**。

| 版本 | 日期 | 修改人 | 修改内容 | 状态流转 |
| --- | --- | --- | --- | --- |
| 1 | <YYYY-MM-DD> | <角色> | 初稿 | — → draft |
