# 需求：REQ-{id}

> Dispatch policy: waves-v1

> 名称：{需求名称}
> 状态：draft / locked / changed / archived
> （draft→locked 的翻转由 agent 依据人类在对话中的明确"锁定"拍板执行，见 skills: requirement-funnel）
> Owner：{产品/用户}
> PM / Architect：{姓名}
> 版本：v0.1.0
> 创建日期：YYYY-MM-DD
> UI impact：none / changed / unknown

> `UI impact` 是 `状态：locked` 的强制顶部字段，`req bind` 只解析这一处（§C 的回显必须与之一致，不一致会被拒绝）。值必须三选一：`none` / `changed` / `unknown`。`unknown` 会触发规划暂停门禁，需在 §D 澄清后才能推进 S2。

<!-- 给 agent（固定阅读，2 行）：
若预期效果可能改界面：先按 design-foundation 判定 local/core/extended；local 使用模块推导，core/extended 缺覆盖才走 F0–F6；再按 §A→§B→§C 推进。
提案纪律与自审见 requirement-funnel skill——上交唯一合格形态是完整方案，开放问题禁止上交。 -->

## §A 理念（Why）

> A1 不是人的原话：你接收并理解人的表述后，过滤口语歧义、补全隐含前提，整理成结构化复述，交人确认"这就是我想说的"。原话会歧义；对话不入册，整理稿才是权威。

| 字段 | 内容 |
|:--|:--|
| A1 预期效果（agent 整理稿，人确认） | {做什么、为什么值得做——两三句} |
| A2 背景与痛点 | {问题和上下文}{现在没有它时用户怎么凑合} |
| A3 成功长什么样 | {完成后用户可感知的变化——验收的精神锚} |
| A4 明确不做（负空间/negative space） | {范围外事项——与 A1 同等重要，每条一句不做的原因；编号供 AC 指向列做 N/A 背书（`§A4-2` 即本表第 2 条）} |

用户和利益相关者（决策权"高"的诉求冲突 = 拍板点候选）：

| 角色 | 诉求 | 决策权 |
|:--|:--|:--|
| {角色} | {诉求} | 高 / 中 / 低 |

术语（分歧当场定名；统一叫法供全部下游文档使用）：

| 术语 | 含义 | 禁止叫法 |
|:--|:--|:--|
| {术语} | {含义} | {容易混淆的叫法} |

## §B 方向与约束（How 的边界——需求级选型，架构归 S2）

方向取舍（每个被否方向必须有一句否决理由——ADR 雏形，S2 承接）：

| 方向 | 一句话方案 | 采纳/否决 | 理由 |
|:--|:--|:--|:--|
| {方向 1（推荐标 ★）} | | 采纳 | {为什么} |
| {方向 2} | | 否决 | {一句否决理由} |

硬约束（agent 对人给的每条"必须"追问打破的代价；答不出代价的不是必须，降级为偏好并入下方假设与风险表）：

| 硬约束 | 为什么是必须 |
|:--|:--|
| {约束} | {代价/理由} |

关键假设与风险：

| 假设 / 风险 | 影响 | 缓解措施 / 验证方式 |
|:--|:--|:--|
| {假设或风险} | 高 / 中 / 低 | {缓解或验证} |

## §C 具体需求（What——逐条可追溯）

> 正向范围 = 本节需求点全集（FR + NFR）；§A4 只登记负向。

需求点（"服务于"指不回任何 §A 条目 = 范围蔓延，当场质疑）：

| 编号 | 模块 / 流程 | 需求 | 服务于 §A_ | 优先级 |
|:--|:--|:--|:--|:--|
| FR-001 | {模块} | {需求} | {A1/A2/…} | Must / Should / Could / Won't |

流程和异常：

| 流程 | 输入 | 输出 | 状态 | 异常 | 权限 | 验收标准 |
|:--|:--|:--|:--|:--|:--|:--|
| {流程} | {输入} | {输出} | {状态} | {异常} | {谁能做/谁被拒} | {证据} |

验收标准（换个人来判，结果一样；**指向列填写规则**——S0 阶段只需保证 `FR-{id}` 指向 §C 真实存在的 FR 行；其余两种合法值是"经背书的 N/A"：`NFR-{id}`（须在下方非功能需求表声明）或 `§A4-{条目}`（指向"明确不做"表的某一行）。自由文本（如"人工检查"）会在 S2 收口时被机器拒绝。示例：`FR-003` ✅ / `NFR-002` ✅ / `§A4-2` ✅ / `上线后观察` ❌）：

| 编号 | 标准 | 指向 |
|:--|:--|:--|
| AC-001 | {可判定的验收表述，含衡量指标} | FR-{id} / NFR-{id} / §A4-{条目编号} |
| AC-002 | 示例：提交成功后 3 秒内可见回执 | FR-003 |
| AC-003 | 示例：不承诺移动端适配 | §A4-2 |

非功能需求：

| 编号 | 类型 | 要求 | 验收标准 |
|:--|:--|:--|:--|
| NFR-001 | 性能 | {要求} | {指标} |
| NFR-002 | 安全 | {要求} | {证据} |
| NFR-003 | 可靠性 | {要求} | {证据} |
| NFR-004 | 合规 | {要求} | {依据} |

数据迁移范围清单（轻量模式、迁移类、重构类需求即使跳过独立设计文档也必须填写本区；本区是 task 拆分边界依据）：

| 路径 / 文件 | 类型 | 处理动作 | 所属任务 | 引用 / 依赖 | 说明 |
|:--|:--|:--|:--|:--|:--|
| `{path}` | source / config / script / generated / test | migrate / keep / delete / review | TASK-{id} | `{import/script}` | {说明} |

填写纪律：删除项在"说明"列注引用清理标准；每个文件映射到唯一 task 或明确标注共享边界；任务拆分前检查重复 import、脚本引用、生成物入口和别名路径。

UI 影响（任何涉及前端页面、组件、交互、可见状态、错误展示、权限展示或响应式布局变化的需求必须填写本区；`UI impact = changed` 时必须先完成 UI Design Package Gate 才能锁定 FE/BE/SYNC 合同）：

| 字段 | 内容 |
|:--|:--|
| UI impact（引自顶部） | none / changed / unknown（顶部 blockquote 是唯一被 `parseUIImpact` 解析的位置，本节只回显，不独立声明） |
| 影响页面 / 模块 | {页面、路由、组件或 N/A} |
| Foundation reference | `docs/design/DESIGN.md@vX.Y.Z` / `local` / `pending-foundation` / `N/A`（`none` 可为 N/A；`local` 表示本 REQ 使用模块级推导，不发布项目级 Foundation；`changed` 的 Core/Extended 必须为版本化引用，不得用风格句替代。S1 parser 不读本字段，仍只解析顶部 `UI impact`） |
| Surface | `SUR-0X@vX.Y.Z` / `local` / `N/A`（Core/Extended 使用 `SUR-*@version`；`local` 仅用于模块级推导；旧值 `consumer/operations` 视为 `SUR-01` 别名） |
| Design posture | `local` / `inherit` / `extend` / `exception`（`local` 仅配合 `local` Foundation；`extend` 须在 Derivation Note 写清新增语法及是否候选晋升；`exception` 须同时有 `docs/design/decisions/EX-*.md` (legacy `docs/design/exceptions/EX-*.md` still recognized)） |
| Derivation note | `docs/design/derivation/REQ-{id}.md` / `N/A`（`changed` 时由 S2 填写且必须为可解析路径；`local` 亦需模块 Derivation；S0 可留 pending） |
| 模块当前真相包 | `docs/design/prototypes/<module>/`（index.html + stories.md + flows.md + scenario-model.json + cross-matrix.json + cases.json + scenario-coverage.json + fixture-contract.json + *.html）/ N/A |
| 原型门禁状态 | N/A / pending / ready |

> 真相包齐备性、S/F-NNN 完整性与 branch 覆盖率由 S2 的 `loop-harness scenario validate` 校验，不在本节自查。

## §D 待澄清问题

| 编号 | 问题 | 影响范围 | 阻塞范围? | 状态 | 结论 |
|:--|:--|:--|:--|:--|:--|
| Q-001 | {问题} | 范围 / 流程 / 状态 / API / 权限 / 验收 | 是 / 否 | open / closed | {结论} |

## §E 锁定记录与逐层拍板（locked 行的拍板权在人；拍板行与自审由 agent 依拍板凭证填写）

| 日期 | 操作 | 操作人 | 说明 |
|:--|:--|:--|:--|
| YYYY-MM-DD | locked | {PM / Architect} | 用户确认范围；UI impact={none/changed/unknown} 已随顶部字段固化 |

逐层拍板记录（compaction 后的拍板凭证——对话不是权威，未落盘的拍板等于没发生）：

| 层 | 日期 | 拍板人 | 方式 |
|:--|:--|:--|:--|
| §A | YYYY-MM-DD | {人} | 对话确认 |
| §B | YYYY-MM-DD | {人} | 对话确认 |
| §C | YYYY-MM-DD | {人} | 对话确认 |

{agent 自审结论——提议锁定前全审的输出，一段话：审过什么、修了什么、留了什么旁注}

## §F 派生文档与覆盖矩阵（**S0 不读不填**——整个 §F 由 S3 起的 CONTRACTS-{id} 索引维护，本表仅锁定时快照；跳到 §G/文末即可）

<!-- 活矩阵唯一居所在 CONTRACTS-{id} 索引；REQ 是锁定基线，agent 不填写本表 -->

### 派生 UI 设计包

| 模块原型集 | 路径 | 状态 | 覆盖需求 |
|:--|:--|:--|:--|
| <module> | `docs/design/prototypes/<module>/` | N/A / pending / ready | FR-{id} |

### 派生合同

| 合同 | 路径 | 状态 | 覆盖需求 |
|:--|:--|:--|:--|
| CONTRACTS-{id} | `docs/dev/contracts/CONTRACTS-{id}.md` | draft / reviewed / locked | 当前 REQ 全量索引 |
| FE-{id} | `docs/dev/contracts/FE-{id}.md` | draft / reviewed / locked | FR-{id} |

### 条款覆盖

| REQ 条款 / source_ref | Rule → CASE → Story → PATH → Spec | 合同条款 | TASK | 验证证据 | 状态 |
|:--|:--|:--|:--|:--|:--|
| REQ-{id}/FR-{id} | BR-{id} → CASE-{id} → S-{id} → F-{id} → PATH-{id} → `web/e2e/{module}/*.spec.ts` | FE/BE/SYNC-{id} §{n} | TASK-{id} | REV/QA/E2E/BUG/ACC-{id} | planned / covered / verified |

### 模块当前真相映射

REQ 只能作为来源，不能创建需求私有设计或测试副本。任何触及模块的 REQ 都必须维护模块全集并触发 full-module regression。

| 模块 | Rule / CASE | Story | PATH | Spec | Round evidence |
|:--|:--|:--|:--|:--|:--|
| {module} | `scenario-model.json` / `cases.json` | `stories.md` / S-{id} | `flows.md` / F-{id} / PATH-{id} | `web/e2e/{module}/` | REV/QA/E2E round {n} |

### 批次下游索引

| 关系 | 文档 | 路径 | 状态 |
|:--|:--|:--|:--|
| downstream | 任务看板 | `docs/dev/tasks/index-REQ-{id}.md` | draft / executing / completed |
| evidence | Review round manifest | `{team-manifest-path}` | pending / complete |
| evidence | Delivery verification | `docs/reports/review/REV-{id}.md` | pending / PASS |
| evidence | QA evidence | `docs/reports/qa/QA-{id}.md` | pending / PASS |
| evidence | E2E Tester evidence | `docs/reports/e2e/E2E-{id}.md` | pending / PASS |
| evidence | Clean round | `{review-evidence-path}` | pending / valid |
| evidence | 验收 | `docs/reports/acceptance/ACC-{id}.md` | pending / passed |
| downstream | 发布审计 | `docs/reports/release-audits/{file}.md` | pending / approved |

## 变更记录

| 日期 | 版本 | 变更内容 | 申请人 | 审批人 |
|:--|:--|:--|:--|:--|
| 2026-08-15 | v2.0.0 | {示例行——首个真实变更从下一行开始} 重构为漏斗结构（§A 理念→§B 方向与约束→§C 具体需求→§D 澄清→§E 锁定→§F 覆盖矩阵）；删除 PM Todo、21 项自查 checklist 与设计公理五问（实质分别转入字段/S2 引擎）；状态枚举精简为 draft/locked/changed/archived；过程方法论由 requirement-funnel skill 承载；流程表补权限列、非功能表补 NFR 编号列 | owner | owner |