harness_coding_docs/docs/08-interaction-checklist.md

# 交互清单

> 本文把用户故事落成可实现、可测试的界面行为：用户如何触发、系统处于什么状态、如何反馈，以及失败时怎样恢复。
> 本文适用于 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、事件或本地模块合约；无则写不适用】

**正常路径**

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

**状态与异常清单**

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

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

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

**验收证据**

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

## 四、页面级检查清单

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

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

## 五、维护规则

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

## 六、填写示例

> 本节只演示如何填写字段，所有【占位符】必须替换为项目事实；示例不定义具体页面、接口或业务规则。

### 示例总表

| ID | 关联用户故事 | 页面 / 组件 | 触发 | 用户目标 | 预期结果 | 优先级 | 状态 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| IX-001 | US-001 | 【页面 / 组件】 | 【点击、键盘或自动触发】 | 【完成核心操作】 | 【看到明确结果和下一步】 | P0 | 【待确认 / 已定】 |
| IX-002 | US-002 | 【页面 / 组件】 | 【点击或键盘触发】 | 【确认或取消影响数据的操作】 | 【明确影响并安全完成或取消】 | P0 | 【待确认 / 已定】 |
| IX-003 | US-001 | 【页面 / 组件】 | 【提交编辑内容】 | 【保存修改】 | 【显示保存结果或可恢复错误】 | P1 | 【待确认 / 已定】 |
| IX-004 | 【US 编号】 | 【页面 / 组件】 | 【选择或拖入关联文件】 | 【关联所需文件】 | 【显示校验结果与下一步】 | P1 | 【待确认 / 已定】 |

### IX-001 【提交核心操作】

- 关联用户故事：US-001
- 前置条件：【用户具备权限且必填信息有效】
- 用户操作：【触发核心操作】
- 服务 / 数据依赖：【引用已定义的合约或写不适用】

**正常路径**

1. 用户触发【核心操作】。
2. 系统立即【给出进行中反馈并避免重复提交】。
3. 完成后系统【更新可见状态】，并向用户说明【下一步】。

**状态与异常（摘要）**

| 场景 | 必须说明的行为 | 本交互约定 |
| --- | --- | --- |
| 加载 / 提交中 | 保留上下文、避免重复操作、表达进度 | 【填写】 |
| 成功 | 更新结果并给出下一步 | 【填写】 |
| 输入校验 | 就近说明问题和修复方式 | 【填写 / 不适用】 |
| 服务或网络错误 | 保留可恢复数据并提供重试路径 | 【填写 / 不适用】 |