198 lines
13 KiB
Markdown
198 lines
13 KiB
Markdown
# 交互清单
|
||
|
||
> 本文把用户故事落成可实现、可测试的界面行为：用户如何触发、系统处于什么状态、如何
|
||
> 反馈，以及失败时怎样恢复。覆盖 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` 创建弹窗；`/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-012 | US-010 | web `/tasks` 表格选择与上下文批量栏 | 勾选后点「开始试选」 | 批量交给桌面端试选 | `DRAFT → PENDING` 原子提交；仅开始第一趟，不授权、不下单、不付款 | 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` + `CurrentTaskPanel` +
|
||
`ExecutionLog` + `ExecutionRecordTable` + `ExecutionRecordDetailPanel`
|
||
- 目标角色：采购执行员
|
||
- 前置条件：web 端连接正常；设备已通过连接检查
|
||
|
||
**正常路径**
|
||
|
||
1. 用户确认 web、设备和已取证 App 版本三项状态都就绪，在顶部状态区点击「开始轮询」。
|
||
2. 每到间隔时间领取一条任务，界面显示**这一趟是试选还是下单**、商品、规格、当前步骤。
|
||
3. 第一趟试选完成后**退出商品页释放手机**，继续下一轮轮询。
|
||
4. 执行结果按时间倒序进入右侧两列表格；单击只选中，双击、Enter 或可见查看命令在左侧打开
|
||
记录详情。宽屏可继续选择其他记录；可见返回按钮或 `Esc` 回到当前任务并恢复当前行焦点。
|
||
|
||
**状态与异常清单**
|
||
|
||
| 场景 | 本交互约定 |
|
||
| --- | --- |
|
||
| 默认 | 任一就绪条件不满足时「开始轮询」禁用，并说明是 web、设备还是 App 版本问题 |
|
||
| 轮询中 | 显示下次轮询倒计时与连续失败计数 |
|
||
| 执行中 | 显示当前趟次与步骤；**真机步骤期间禁用硬取消和关闭窗口** |
|
||
| 当前任务图片 | 无可信图片时显示空态；有图时标来源与采集时间，不用其他来源图片凑合 |
|
||
| 执行记录详情 | 左栏在当前任务 / 记录详情间切换，不打开模态框；详情内左侧原始文字、右侧图片证据、下方结构化采购结果；顶部实时状态不中断；不提供下单、重试提交或付款动作 |
|
||
| 详情读取异常 | 加载、失败、无图和记录不存在分别说明；仅可重试读取同一稳定记录 ID，过期异步结果不得覆盖当前视图 |
|
||
| 无可领任务 | 显示「暂无待领任务」并继续下一轮，**不当作错误、不计入失败计数** |
|
||
| 待人工 | 整页显著变色，说明缺什么、下一步做什么；该任务不再被本端领取 |
|
||
| 连续失败 | 达到阈值自动停止轮询并显示原因，**不无限重试** |
|
||
| 关闭窗口 | 立即停止轮询，不留后台进程 |
|
||
| 设备断连 | 当前任务标技术失败、保留现场；**不重试任何可能创建订单的点击** |
|
||
| 安全校验 | 立即停止轮询、截图、转人工，**不提供绕过入口** |
|
||
| 外部支付交接 | 立即停止并提示「订单可能已创建、支付未完成」；**不提供「继续」按钮** |
|
||
| 点击提交后超时 | 转 `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` 生效。
|
||
- 状态不能只靠颜色表达。
|
||
- 金额一律显示两位小数并标注币种。
|
||
- 双击只能作为效率快捷方式；任务编号链接和聚焦行后按 Enter 必须提供等价详情入口。
|
||
- 表格行内的复选框、商品外链和任务编号链接不得误触发行双击；关闭详情抽屉后焦点回到原行。
|
||
- 表格批量栏只在存在选择时出现；全选只覆盖当前筛选结果中允许当前动作的行。
|
||
|
||
## 五、交付前检查
|
||
|
||
- [ ] 每项 P0 交互回链至少一个 US 编号。
|
||
- [ ] 涉及资金或不可逆动作的交互已填写完整状态表。
|
||
- [ ] 所有禁用态都有说明文案。
|
||
- [ ] 所有空状态都有可执行的下一步。
|
||
- [ ] 未在本文自行定义接口路径、字段或状态码。
|