# 交互清单

> 本文把用户故事落成可实现、可测试的界面行为：用户如何触发、系统处于什么状态、如何反馈，以及失败时怎样恢复。
> 本文适用于 Web、移动端、桌面端、插件和其他面向用户的交互界面；纯 CLI 或无界面项目可标记为不适用。

## 一、职责边界

| 信息 | 写在哪里 | 说明 |
| --- | --- | --- |
| 用户目标、价值与业务验收 | [用户故事清单](07-user-stories.md) | 本文中的每项 UI 交互回链一个或多个 US 编号。 |
| MVP 范围与优先级 | [需求](02-requirements.md) | 交互清单不能扩大需求范围。 |
| 页面入口、路由和组件归属 | [路由与页面结构](routes.md) | 不重复维护页面导航事实。 |
| API、事件和错误格式 | [API 合约](api.md) | 这里只引用合约，不自行定义接口路径、字段或状态码。 |

- 交互 ID 使用 IX-001、IX-002 的形式；编号一经引用不要重用。
- 一项交互可以服务多个用户故事；一个故事通常包含多项交互。
- 有用户可见动作、自动状态变化或关键系统反馈的 P0 页面，都应列入本文。

## 二、交互总表

> **先总表，后详情（默认只展开 P0）**
>
> 1. 先在总表列出每个页面或组件的完整交互集合，确保没有遗漏用户可见动作和关键自动状态。
> 2. 详情模板默认只填写 P0 交互；P1 / P2 仅在高风险、不可逆、权限敏感或容易产生歧义时补充详情。
> 3. 简单、低风险且规则清楚的交互只保留总表条目，不为逐个按钮重复填写完整状态表。

| ID | 关联用户故事 | 页面 / 组件 | 触发 | 用户目标 | 预期结果 | 优先级 | 状态 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| IX-001 | US-001 | 【页面 / 组件】 | 【点击 / 输入 / 键盘 / 自动】 | 【用户要完成什么】 | 【可观察到的结果】 | P0 | 【待确认 / 已定】 |
| IX-002 | US-001、US-002 | 【页面 / 组件】 | 【触发方式】 | 【用户要完成什么】 | 【可观察到的结果】 | P1 | 【待确认 / 已定】 |

## 三、交互详情模板（默认仅 P0）

P0 交互必须使用本模板；非 P0 交互只有在高风险、不可逆、权限敏感或容易产生歧义时才补充。

### IX-001 【交互标题】

- 关联用户故事：【US-001】
- 关联需求 / 验收：【功能名或验收条目】
- 页面 / 组件：【路由、界面名称或组件名称】
- 目标角色：【角色】
- 前置条件：【登录态、权限、数据存在性、网络或其他条件】
- 触发方式：【点击 / 键盘 / 输入 / 手势 / 自动触发】
- 用户操作：【用户具体做什么】
- 服务 / 数据依赖：【引用 API、事件或本地模块合约；无则写不适用】
- 关联原型（可选）：【`docs/design/` 下的原型文件，约定见[设计原型输入约定](design/README.md)；无原型时写不适用】

**正常路径**

1. 用户【操作】。
2. 系统【立即可见的响应，例如聚焦、展开、禁用重复提交或显示进度】。
3. 系统【完成后的状态变化、页面变化或数据刷新】。
4. 用户看到【成功反馈、下一步入口或返回位置】。

**状态与异常清单**

| 场景 | 必须说明的行为 | 本交互约定 |
| --- | --- | --- |
| 默认 / 可操作 | 控件是否可见、可用，用户如何发现其用途 | 【填写】 |
| 加载 / 提交中 | 是否禁用重复操作、进度如何表达、是否保留上下文 | 【填写】 |
| 成功 | 数据、页面或焦点如何更新，用户如何确认完成 | 【填写】 |
| 空状态 | 无数据时解释原因并给出可执行的下一步 | 【填写 / 不适用】 |
| 输入校验 | 何时校验、错误显示位置、如何修复 | 【填写 / 不适用】 |
| 服务或网络错误 | 可理解的错误、保留的数据、重试或恢复路径 | 【填写 / 不适用】 |
| 权限不足 | 不静默失败，说明限制和可执行的下一步 | 【填写 / 不适用】 |
| 冲突 / 重复提交 | 幂等、刷新或冲突解决方式 | 【填写 / 不适用】 |
| 破坏性操作 | 是否确认、影响范围、取消、撤销或恢复方式 | 【填写 / 不适用】 |
| 中断 / 离线 | 草稿、返回、关闭或网络恢复后的处理 | 【填写 / 不适用】 |

**可访问性与多端要求**

- 键盘与焦点：【Tab 顺序、Enter / Escape、路由变化后的焦点位置】
- 语义与读屏：【控件名称、状态、错误和动态反馈如何被感知】
- 触控与手势：【不依赖悬停或单一手势；最小可点击区域遵循项目平台规范】
- 响应式 / 小屏：【窄屏、横屏、缩放或动态文字下的布局和操作】
- 动效：【是否需要动效、动效表达什么，以及减少动态效果时的降级】

**验收证据**

- 手工验证：【角色、环境、操作和可观察结果】
- 自动化验证：【测试层级、场景或命令】
- 关联任务：【T-编号；尚未拆任务时写待创建】

## 四、页面级检查清单

每个有交互的页面或组件在交付前至少确认：

- [ ] 已关联用户故事、页面 / 组件和验收条目。
- [ ] 主操作与次要操作清晰，用户能预测操作后果。
- [ ] 加载、成功、空、错误、权限和必要的确认 / 撤销场景都有约定。
- [ ] 表单有可见标签、明确校验和可恢复的错误提示。
- [ ] 不把颜色、悬停或手势作为唯一信息和操作方式。
- [ ] 键盘、焦点、读屏、触控目标、缩放和小屏场景已说明或明确不适用。
- [ ] 页面跳转、返回、关闭和中断后，用户不会丢失未说明的数据或上下文。
- [ ] 交互没有引入[需求](02-requirements.md)之外的业务范围。

## 五、维护规则

- 先更新用户故事或需求，再更新受影响的 IX 条目。
- 交互涉及接口、字段或错误格式变化时，同步更新[API 合约](api.md)；不要只在本文写成事实。
- UI 任务的任务文件应列出相关 US / IX 编号，并把验证结果记录为完成证据。
- 不确定的交互规则写为【待确认】，不要以示例行为替代产品决策。

## 六、填写示例

> 本节演示"填好之后长什么样"，与[用户故事清单](07-user-stories.md)第七节的示例故事对应。示例采用通用的列表检索和删除场景，把【条目】替换为项目里的真实业务对象即可套用；接口一律引用【API 合约中的接口名】，不在本文虚构路径。示例同时演示两种粒度：低风险交互只留总表条目（IX-001、IX-003），破坏性 P0 交互按第三节完整模板展开（IX-002）。

### 示例总表

| ID | 关联用户故事 | 页面 / 组件 | 触发 | 用户目标 | 预期结果 | 优先级 | 状态 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| IX-001 | US-001 | 【条目】列表页 · 搜索框 | 输入关键词后点击搜索或按 Enter | 按关键词过滤列表 | 列表刷新为匹配结果并显示数量；空结果给出清除入口 | P0 | 已定 |
| IX-002 | US-002 | 【条目】列表页 · 行内删除 | 点击行内删除按钮 | 删除单条失效【条目】 | 确认影响后该行移除并提示成功 | P0 | 已定 |
| IX-003 | US-001 | 【条目】列表页 · 列表区域 | 自动（检索请求进行中） | 感知加载进度 | 显示骨架屏，完成后替换为数据或空状态 | P1 | 已定 |

IX-001 与 IX-003 规则清楚、风险低，只保留总表条目；IX-002 是破坏性 P0 操作，必须按完整模板展开：

### IX-002 删除单条【条目】（需确认）

- 关联用户故事：US-002
- 关联需求 / 验收：【条目】管理中"安全删除"的验收条目
- 页面 / 组件：【条目】列表页 · 行内删除按钮 + 确认对话框
- 目标角色：【管理员】
- 前置条件：已登录；对目标【条目】有删除权限；该行数据存在。
- 触发方式：点击行内删除按钮。
- 用户操作：点击删除 → 在确认对话框中确认或取消。
- 服务 / 数据依赖：【API 合约中的删除接口】；错误格式以合约为准。
- 关联原型（可选）：`docs/design/【条目列表页】.html`；无原型时写不适用。

**正常路径**

1. 用户点击行内删除按钮。
2. 系统弹出确认对话框，写明被删对象名称和影响（如"不可恢复"），默认焦点落在"取消"上。
3. 用户点击"确认删除"，按钮进入提交中状态并禁止重复提交。
4. 删除成功后对话框关闭，该行从列表移除，提示"已删除【条目名】"。

**状态与异常清单**

| 场景 | 必须说明的行为 | 本交互约定 |
| --- | --- | --- |
| 默认 / 可操作 | 控件是否可见、可用，用户如何发现其用途 | 有删除权限时按钮在行内可见，图标带可读名称 |
| 加载 / 提交中 | 是否禁用重复操作、进度如何表达、是否保留上下文 | 确认按钮显示进行中并禁用，对话框保持打开 |
| 成功 | 数据、页面或焦点如何更新，用户如何确认完成 | 对话框关闭、行移除、提示含【条目名】的成功信息 |
| 空状态 | 无数据时解释原因并给出可执行的下一步 | 删除最后一条后列表显示空状态和"新建"入口 |
| 输入校验 | 何时校验、错误显示位置、如何修复 | 不适用（本交互无输入） |
| 服务或网络错误 | 可理解的错误、保留的数据、重试或恢复路径 | 对话框保留并说明失败原因，可重试或取消 |
| 权限不足 | 不静默失败，说明限制和可执行的下一步 | 无权限时不渲染按钮；请求被拒时说明所需权限 |
| 冲突 / 重复提交 | 幂等、刷新或冲突解决方式 | 【条目】已被他人删除时提示"已不存在"并刷新列表 |
| 破坏性操作 | 是否确认、影响范围、取消、撤销或恢复方式 | 二次确认并写明不可恢复；默认焦点在"取消" |
| 中断 / 离线 | 草稿、返回、关闭或网络恢复后的处理 | 离线时提示不可用，不做本地假删除；恢复后可重试 |

**可访问性与多端要求**

- 键盘与焦点：对话框打开后焦点移入，Escape 等同取消；删除完成后焦点回到列表的合理位置。
- 语义与读屏：删除按钮名称含【条目名】；对话框标题、影响说明和结果提示可被读屏感知。
- 触控与手势：删除按钮满足项目平台的最小可点击区域，不依赖悬停才可见。
- 响应式 / 小屏：窄屏下确认对话框完整可见，确认与取消按钮不被遮挡。
- 动效：行移除可用淡出表达；用户开启"减少动态效果"时直接移除。

**验收证据**

- 手工验证：以【管理员】在【环境】删除一条测试【条目】，观察确认对话框、成功提示与列表刷新。
- 自动化验证：【测试层级、场景或命令】。
- 关联任务：【T-编号；尚未拆任务时写待创建】。