harness_coding_docs/docs/08-interaction-checklist.md

交互清单

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

一、职责边界

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

• 交互 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/ 下的原型文件，约定见设计原型输入约定；无原型时写不适用】

正常路径

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

状态与异常清单

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

可访问性与多端要求

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

验收证据

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

四、页面级检查清单

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

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

五、维护规则

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

六、填写示例

本节演示"填好之后长什么样"，与用户故事清单第七节的示例故事对应。示例采用通用的列表检索和删除场景，把【条目】替换为项目里的真实业务对象即可套用；接口一律引用【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-编号；尚未拆任务时写待创建】。