harness_coding_docs/docs/07-user-stories.md

# 用户故事清单

> 本文记录“谁在什么场景下，为了获得什么价值，要完成什么目标”。它是产品需求的细化清单，不写接口、数据字段、组件实现或逐个按钮的行为。
> 页面如何响应操作见[交互清单](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 | 【管理员】 | 在大量【条目】中快速定位要处理的那一条 | 【条目】检索 | IX-001、IX-003 | 已定 |
| US-002 | 安全地删除不再需要的【条目】 | P0 | 【管理员】 | 移除失效【条目】，且不因误操作丢数据 | 【条目】管理 | IX-002 | 已定 |

### US-001 按关键词找到目标【条目】

- 优先级：P0
- 关联功能：【条目】检索
- 关联页面 / 入口：【条目】列表页
- 关联交互：IX-001、IX-003
- 角色：【管理员】
- 使用场景 / 前置条件：已登录且有查看权限；列表中【条目】数量多到无法逐条浏览。

**用户故事**

作为【管理员】，我想要按关键词检索【条目】列表，从而不必逐页翻找就能定位要处理的【条目】。

**范围**

- 包含：按关键词过滤列表、显示结果数量、空结果与失败时的反馈。
- 不包含：高级筛选、排序和保存搜索条件（另立故事）。

**验收场景**

1. 假如列表中存在匹配【条目】，当用户输入关键词并触发搜索，那么列表刷新为匹配结果，并显示结果数量。
2. 假如没有匹配结果，当用户搜索，那么显示空状态说明并提供"清除搜索"入口，不当作错误处理。
3. 假如搜索请求失败，当用户搜索，那么保留已输入的关键词，说明失败原因并允许重试。

**待确认**

- 【关键词匹配哪些字段、是否支持模糊匹配，由产品决策】

### US-002 安全地删除不再需要的【条目】

- 优先级：P0
- 关联功能：【条目】管理
- 关联页面 / 入口：【条目】列表页
- 关联交互：IX-002
- 角色：【管理员】
- 使用场景 / 前置条件：已登录且对目标【条目】有删除权限。

**用户故事**

作为【管理员】，我想要在确认影响后删除失效的【条目】，从而保持列表整洁且不担心误删。

**范围**

- 包含：单条删除、删除前确认、成功与失败反馈。
- 不包含：批量删除、回收站与恢复（另立故事）。

**验收场景**

1. 假如目标【条目】存在且用户有权限，当用户发起删除，那么系统先说明影响并要求确认，确认后该【条目】从列表消失并提示成功。
2. 假如用户在确认对话框中取消，那么不发生任何数据变化，用户回到原位置。
3. 假如删除请求失败或【条目】已被他人删除，那么系统说明原因、刷新列表，不出现"看起来删了但还在"的中间态。

**待确认**

- 【删除是硬删除还是软删除、是否需要审计留痕，由产品与合规决策】