# 用户故事清单

> 本文记录“谁在什么场景下，为了获得什么价值，要完成什么目标”。它是产品需求的细化清单，不写接口、数据字段、组件实现或逐个按钮的行为。
> 页面如何响应操作见[交互清单](08-interaction-checklist.md)；页面入口和导航见[路由与页面结构](routes.md)；接口形状以[API 合约](api.md)为准。

## 一、何时使用

- 有用户角色、业务目标或交互式界面的项目，必须为每个 P0 闭环维护用户故事。
- 无图形界面的 CLI、批处理或纯基础设施项目，也可用本文描述操作者目标；没有界面交互时，不必建立交互清单。
- 一个用户故事描述一个可感知的业务结果，不按“一个页面”“一个按钮”机械拆分。

## 二、职责边界与关联

| 信息 | 权威文档 | 说明 |
| --- | --- | --- |
| MVP 范围、优先级、非目标 | [需求](02-requirements.md) | 先定做什么，再细化故事。 |
| 用户目标、场景与验收场景 | 本文 | 每个故事使用稳定的 US 编号。 |
| 页面操作、状态与反馈 | [交互清单](08-interaction-checklist.md) | 每项交互使用稳定的 IX 编号，并回链 US。 |
| 页面入口、导航与组件归属 | [路由与页面结构](routes.md) | 不在本文复制路由表。 |
| 接口、事件与错误格式 | [API 合约](api.md) | 不在本文虚构接口路径或字段。 |

- 用户故事 ID 使用 US-001、US-002 的形式；编号一经引用不要重用。
- 一条用户故事可以关联多条交互；每条面向用户的 P0 交互都应回链至少一个用户故事。
- 需求变化时，先更新[需求](02-requirements.md)，再同步本文和受影响的交互清单、任务验收。

## 三、用户故事总表

| ID | 标题 | 优先级 | 角色 | 要达成的目标 | 关联功能 | 关联交互 | 状态 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| US-001 | 【一句话故事名】 | P0 | 【角色】 | 【用户结果】 | 【功能名】 | IX-001、IX-002 | 【待确认 / 已定】 |
| US-002 | 【一句话故事名】 | P1 | 【角色】 | 【用户结果】 | 【功能名】 | 【IX 编号或不适用】 | 【待确认 / 已定】 |

## 四、故事详情模板

### US-001 【故事标题】

- 优先级：【P0 / P1 / P2】
- 关联功能：【02-requirements.md 中的功能名称】
- 关联页面 / 入口：【路由、命令或入口名称】
- 关联交互：【IX-001、IX-002；无 UI 时写不适用】
- 角色：【谁】
- 使用场景 / 前置条件：【何时、在什么限制下】

**用户故事**

作为【角色】，我想要【完成的目标】，从而【得到的价值】。

**范围**

- 包含：【本故事必须覆盖的结果】
- 不包含：【明确不做或由其他故事承担的内容】

**验收场景**

1. 假如【前置条件】，当【用户目标相关的动作发生】，那么【用户可观察到的结果】。
2. 假如【异常、权限或数据边界】，当【用户尝试目标】，那么【系统如何保护用户并给出下一步】。
3. 假如【需要保存、同步或恢复】，当【用户离开再返回】，那么【应保留或应丢弃的结果】。

**待确认**

- 【业务规则、角色权限、数据边界或文案决策】

## 五、编写规则

- 先写角色、目标和价值，再写验收场景；不要把“点击某按钮”当作故事本身。
- P0 故事必须可独立验收，并明确成功、失败或无权限时用户得到的结果。
- 同一故事的细粒度点击、输入、加载、校验、确认与撤销，写入[交互清单](08-interaction-checklist.md)。
- 未确认的规则写为【待确认】，不要让 agent 在代码中自行补全。
- 需求、优先级或范围改变后，检查关联 US、IX、任务文件和验收标准是否仍一致。

## 六、交付前检查

- [ ] 每个 P0 功能至少关联一个 US 编号。
- [ ] 每个故事都说明角色、目标、价值和可验证的验收场景。
- [ ] UI 故事已关联对应 IX 编号；无 UI 的故事明确标为不适用。
- [ ] 故事没有复制接口、字段或组件实现细节。
- [ ] 范围、优先级与[需求](02-requirements.md)一致。

## 七、填写示例

> 本节只演示如何填写字段，所有【占位符】必须替换为项目事实；不要把示例当作通用业务规则。

### 示例总表

| ID | 标题 | 优先级 | 角色 | 要达成的目标 | 关联功能 | 关联交互 | 状态 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| US-001 | 【完成核心操作】 | P0 | 【目标角色】 | 【完成后得到的价值】 | 【功能 1】 | IX-001 | 【待确认 / 已定】 |
| US-002 | 【确认执行影响数据的操作】 | P0 | 【目标角色】 | 【理解影响后完成操作】 | 【功能 2】 | IX-002 | 【待确认 / 已定】 |

### US-001 【完成核心操作】

- 关联页面 / 入口：【页面、命令或入口】
- 使用场景 / 前置条件：【用户已满足的条件】

作为【目标角色】，我想要【完成核心操作】，从而【获得明确价值】。

**验收场景**

1. 假如【前置条件】，当用户【执行目标相关的动作】，那么【可观察到成功结果】。
2. 假如【异常、权限或边界条件】，当用户尝试该目标，那么系统【解释原因并提供下一步】。

### US-002 【确认执行影响数据的操作】

- 关联页面 / 入口：【页面、命令或入口】
- 关联交互：IX-002

作为【目标角色】，我想要在了解【操作影响】后确认或取消【操作】，从而【避免意外结果】。

**验收场景**

1. 假如【操作会影响已有数据】，当用户发起【操作】，那么系统【明确说明影响并提供确认与取消】。
2. 假如用户取消或操作失败，那么系统【保留必要上下文并说明恢复路径】。