cmbuyer/docs/08-interaction-checklist.md

# 交互清单

> 本文把用户故事落成可实现、可测试的界面行为：用户如何触发、系统处于什么状态、如何
> 反馈，以及失败时怎样恢复。覆盖 web 端页面与 desk 端桌面界面。

## 一、职责边界

| 信息 | 写在哪里 |
| --- | --- |
| 用户目标、价值与业务验收 | [用户故事清单](07-user-stories.md) |
| MVP 范围与优先级 | [需求](02-requirements.md) |
| 页面入口、路由和组件归属 | [路由与页面结构](routes.md) |
| API、事件和错误格式 | [API 合约](api.md) |

IX 编号一经引用不再重用。交互清单不能扩大需求范围。

## 二、交互总表

| ID | 关联 US | 页面 / 组件 | 触发 | 用户目标 | 预期结果 | 优先级 | 状态 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| IX-001 | US-007 | web `/login` | 提交表单 | 进入管理后台 | 建立会话并进入原目标页或 `/tasks` | P0 | 已定 |
| IX-002 | US-001 | web `/tasks/new` | 提交表单 | 建单 | 解析出 `goods_id` 并返回任务编号 | P0 | 已定 |
| IX-003 | US-002 | web `/tasks` 查询条与泳道 | 输入 / 点选 | 找到要处理的任务 | 实时筛选、计数更新、空状态可清除 | P0 | 已定 |
| IX-004 | US-002 | web `/tasks/{id}` | 进入页面 | 了解任务当前处境 | 按状态呈现唯一主区块与主动作 | P0 | 已定 |
| IX-005 | US-004、US-005 | web 试选确认卡 | 查看后点确认 / 退回 | 确认机器选对了并授权 | 签发一次性授权并锁定单价，明确不付款 | P0 | 已定 |
| IX-006 | US-006 | web 待付款核对卡 | 查看后手工标记 | 核对后付款 | 展示订单截图与授权信息；人付款后标记完成 | P0 | 已定 |
| IX-007 | US-003 | desk 设备与参数页 | 填 serial → 连接检查 | 让设备就绪 | 连接成功并确认拼多多已安装 | P0 | 已定 |
| IX-008 | US-003、US-008 | desk 采购执行页 | 开始 / 停止轮询 | 让手机自动跑并处理异常 | 待人工时显著提示缺什么；连续失败自动停 | P0 | 已定 |
| IX-010 | US-005 | web 围栏前放弃授权入口 | 点击放弃 | 解开尚未提交的授权 | 授权作废，任务转待重新试选 | P0 | 已定 |
| IX-011 | US-005、US-008 | web / desk 提交围栏与调和状态 | 真实点击前申请围栏；点击后回报 | 防止断网或重复操作产生第二笔订单 | 围栏前失败不点击；围栏后不明确只核查、不重试 | P0 | 已定 |

> IX-009（ERP 建单）随 F-003 移出 MVP，编号保留不重用。

## 三、交互详情（P0 高风险）

以下三项涉及资金、不可逆动作或权限，必须完整填写。其余交互保留总表条目。

### IX-005 试选确认与下单授权

- 关联用户故事：US-004、US-005
- 关联需求 / 验收：F-007、F-008；[需求](02-requirements.md)第五节「决策与资金」
- 页面 / 组件：web `/tasks/{id}` 的 `SpecTrialCard` + `AuthorizePanel`
- 目标角色：采购管理员
- 前置条件：已登录；任务状态为 `WAITING_CONFIRMATION`；已收到试选结果与规格面板截图
- 触发方式：查看后点击「确认下单（不付款）」或「退回，不买」
- 服务依赖：`POST /tasks/{id}/order-authorizations`、`POST /tasks/{id}/reject`
- 关联原型：待补（`docs/design/`）

**这不是候选对照台。** 只有一个商品，人回答的是「机器选对了吗」，不是「哪个更好」。

**正常路径**

1. 用户进入详情页，看到需求与机器所选的逐项对照、单价、合计和规格面板截图。
2. 各项均为 ✓ 时，「确认下单（不付款）」可用。
3. 用户点击确认，系统签发授权并**锁定本次试选的单价**，任务转 `AUTHORIZED`。
4. 页面明确提示：只会创建待付款订单，付款需人在拼多多完成。

**状态与异常清单**

| 场景 | 本交互约定 |
| --- | --- |
| 默认 / 可操作 | 各项 ✓ 时确认按钮可用；截图必须已加载出来才允许确认 |
| 规格不一致（✗） | **确认按钮禁用**并说明哪一项不符；只能「退回，不买」或转人工 |
| 金额超上限（✗） | **确认按钮禁用**并显示超出多少；不提供「仍然确认」入口 |
| 加载 / 提交中 | 按钮禁用并显示进行中，防重复提交 |
| 成功 | 跳回工作台，该任务进入「机器在跑」等待第二趟 |
| 退回 | 二次确认后任务终止为 `CANCELED`，说明不会再自动执行 |
| 服务或网络错误 | 保留页面状态，说明原因并允许重试 |
| 权限不足 | 设备凭据调用此接口一律 403 并记录；页面不暴露任务内容 |
| 冲突 / 重复提交 | `expected_task_version` 不匹配返回 409，提示任务已变化并刷新；重复提交幂等，只产生一笔订单 |
| 破坏性操作 | 确认会导致真实下单。提交前必须显示授权金额上限与「系统只下单不付款」 |
| 试选已过期 | 授权过期后任务转待重新试选；完成新试选前不显示确认入口，页面明确说明旧价不再有效 |
| 中断 / 离线 | 未提交的备注不保存；重进页面回到未确认状态 |

**可访问性与多端**

- 确认与退回按钮可键盘到达，焦点可见。
- ✓ / ✗ 不能只靠颜色区分，必须带文字。
- 窄屏下截图可放大查看，不被裁切到看不清规格。

### IX-006 待付款核对与标记完成

- 关联用户故事：US-006 ｜ 关联需求：F-009 收口
- 页面 / 组件：web `/tasks/{id}` 的 `PaymentCheckCard`
- 目标角色：采购管理员（采购执行员在拼多多完成人工付款并反馈结果）
- 前置条件：任务状态为 `WAITING_PAYMENT`，已收到订单截图
- 服务依赖：`POST /tasks/{id}/mark-paid`

**MVP 简化版**：系统只展示，不自动回读。自动核对是 F-016（V2）。

**正常路径**

1. 用户看到订单截图、商品、规格、数量和授权金额。
2. 用户在拼多多手工核对并付款。
3. 用户回到页面点「已付款」，任务转 `SUCCEEDED`。

**状态与异常清单**

| 场景 | 本交互约定 |
| --- | --- |
| 默认 | 显著提示「对不上就别付」，并说明不一致时回来标记异常而不是在拼多多改单 |
| 成功 | 任务转已完成，记录标记人与时间 |
| 金额或规格对不上 | 提供「标记异常」转 `NEEDS_MANUAL`，不允许直接标已付款 |
| 截图缺失 | 说明证据缺失并转人工，**不允许在无证据情况下标记完成** |
| 重复标记 | 幂等，不产生第二条完成记录 |
| 破坏性操作 | 本交互不产生任何写平台动作，只改本地状态 |

### IX-008 桌面端定时轮询与人工接管

- 关联用户故事：US-003、US-008 ｜ 关联需求：F-005、F-011
- 页面 / 组件：desk 采购执行页 `PollControls` + `DeviceStatusBar`
- 目标角色：采购执行员
- 前置条件：web 端连接正常；设备已通过连接检查

**正常路径**

1. 用户确认两个连接状态都为绿，点击「开始轮询」。
2. 每到间隔时间领取一条任务，界面显示**这一趟是试选还是下单**、商品、规格、当前步骤。
3. 第一趟试选完成后**退出商品页释放手机**，继续下一轮轮询。

**状态与异常清单**

| 场景 | 本交互约定 |
| --- | --- |
| 默认 | 任一连接未就绪时「开始轮询」禁用并说明是哪一个 |
| 轮询中 | 显示下次轮询倒计时与连续失败计数 |
| 执行中 | 显示当前趟次与步骤；**真机步骤期间禁用硬取消和关闭窗口** |
| 无可领任务 | 显示「暂无待领任务」并继续下一轮，**不当作错误、不计入失败计数** |
| 待人工 | 整页显著变色，说明缺什么、下一步做什么；该任务不再被本端领取 |
| 连续失败 | 达到阈值自动停止轮询并显示原因，**不无限重试** |
| 关闭窗口 | 立即停止轮询，不留后台进程 |
| 设备断连 | 当前任务标技术失败、保留现场；**不重试任何可能创建订单的点击** |
| 安全校验 | 立即停止轮询、截图、转人工，**不提供绕过入口** |
| 外部支付交接 | 立即停止并提示「订单可能已创建、支付未完成」；**不提供「继续」按钮** |
| 点击提交后超时 | 转 `RECONCILIATION_REQUIRED` 并预留金额额度，**禁止自动重试**；授权保持永久围栏 |
| 闸门二不通过 | 说明「价格已变：授权 ¥X，现价 ¥Y」并转人工，不自动下单也不自动放弃 |
| 运行中变更 | 冻结设备切换和参数保存 |
| 服务端不可达 | 保留本地结果与证据，提示待补传，不丢弃已完成工作 |

### IX-011 提交围栏与结果调和

- 关联用户故事：US-005、US-008 ｜ 关联需求：F-017
- 页面 / 组件：desk 采购执行页；web 任务详情的提交围栏摘要
- 前置条件：已完成 dry-run；真实第二趟重新通过三道闸门；授权尚未消费且未建立围栏
- 服务依赖：`order-dry-runs/start`、`order-dry-runs/{rid}/ready`、
  `order-submissions/start`、`order-submissions/{sid}/reconcile`、`manual-review`

**正常路径**

1. dry-run 以醒目的「只读演练」标识运行，到确认页读取并验证后退出，不出现提交动作。
2. 真实第二趟在三道闸门通过后显示「正在申请提交围栏」，此时不允许点击或取消。
3. 只有服务端明确返回 `click_permitted` 后执行一次点击，界面立即进入「正在核对订单结果」。
4. 明确创建后转待付款；结果不明确则两端都显示同一 `submission_id` 与「可能已创建」，
   只提供人工核查，不提供重试或放弃。

**状态与异常清单**

| 场景 | 本交互约定 |
| --- | --- |
| dry-run | 蓝色信息态并固定显示「不会提交订单」；完成后有证据摘要 |
| 围栏申请中 | 主操作禁用、显示进度；关闭窗口受控，避免用户误以为可重来 |
| 围栏申请失败 / 响应不明 | **不点击**；展示幂等键与核查入口 |
| 围栏成功 | 显示唯一提交编号；只允许内部流程点击一次，不向用户暴露第二个提交按钮 |
| 点击后明确创建 | 转待付款并显示订单证据 |
| 点击后超时 / 外部支付 / 安全校验 | 转 `RECONCILIATION_REQUIRED`；显著提示可能已创建并预留额度 |
| 重复打开或恢复 | 恢复同一提交编号和调和状态，不重新领取、不重新点击 |
| 人工核查 | 可记录「已创建 / 未创建 / 仍不明确」及证据；系统本身不发起新的下单 |

## 四、通用要求

适用于所有 P0 交互：

- **禁用按钮必须说明原因**，不留用户猜。
- **失败必须给下一步**，不只报错。
- **空状态是邀请，不是错误**。
- 破坏性与不可逆动作必须二次确认，并说明影响范围。
- 键盘可达、焦点可见、`prefers-reduced-motion` 生效。
- 状态不能只靠颜色表达。
- 金额一律显示两位小数并标注币种。

## 五、交付前检查

- [ ] 每项 P0 交互回链至少一个 US 编号。
- [ ] 涉及资金或不可逆动作的交互已填写完整状态表。
- [ ] 所有禁用态都有说明文案。
- [ ] 所有空状态都有可执行的下一步。
- [ ] 未在本文自行定义接口路径、字段或状态码。