docs(architecture): adopt authorized single-pass purchase

docs/08-interaction-checklist.md

@@ -1,197 +1,147 @@
 # 交互清单
 
-> 本文把用户故事落成可实现、可测试的界面行为：用户如何触发、系统处于什么状态、如何
-> 反馈，以及失败时怎样恢复。覆盖 web 端页面与 desk 端桌面界面。
+> 本文是界面行为权威。需求范围见[需求](02-requirements.md)，页面位置见[routes](routes.md)。
 
 ## 一、职责边界
 
-| 信息 | 写在哪里 |
-| --- | --- |
-| 用户目标、价值与业务验收 | [用户故事清单](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 | 已定 |
+| ID | 故事 | 位置 | 触发 | 结果 | 优先级 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- |
+| IX-001 | US-007 | web `/login` | 登录 / 退出 | 建立或销毁管理员会话 | P0 | 已定 |
+| IX-002 | US-001 | web 任务表格创建弹窗 | 点击创建、保存 | 创建 `DRAFT` 并在首行反馈 | P0 | 已定 |
+| IX-003 | US-002 | web `/tasks` 筛选行 | 输入关键词、筛选、清除 | 更新表格并保留可理解的筛选状态 | P0 | 已定 |
+| IX-004 | US-002、US-004 | web 列表行 / `/tasks/{id}` | 双击行、浏览器前进后退 | 路由化详情抽屉或完整页，显示执行证据 | P0 | 已定 |
+| IX-005 | US-005 | web 批量操作条 | 点击开始采购 | 创建一次性授权并进入 `PENDING` | P0 | 已定 |
+| IX-006 | US-006 | web 待付款详情 | 查看后手工标记 | 只记录人工付款完成，不执行支付 | P0 | 已定 |
+| IX-007 | US-003 | desk 配置 tab | 保存并检查连接 | 服务、ADB、App 版本就绪 | P0 | 已定 |
+| IX-008 | US-003、US-008 | desk 采购执行 tab | 开始 / 停止轮询、选择记录、Esc | 单趟执行和安全人工接管 | P0 | 已定 |
+| IX-009 | US-008 | web / desk 通用错误反馈 | 请求或流程失败 | 显示阶段、原因和安全下一步 | P0 | 已定 |
+| IX-010 | US-005 | web 围栏前人工处理 | 重置 / 取消 | 关闭旧授权后回 `DRAFT` 或取消 | P0 | 已定 |
+| IX-011 | US-005、US-008 | desk 围栏 + web 调和 | 自动申请围栏 / 人工调和 | 点击一次或只处理同一提交 | P0 | 已定 |
+| IX-012 | US-010 | web 表格选择与操作条 | 勾选任务 | 明确批量范围、数量、最高总额 | P0 | 已定 |
 
-> IX-009（ERP 建单）随 F-003 移出 MVP，编号保留不重用。
+## 三、P0 高风险交互
 
-## 三、交互详情（P0 高风险）
+### IX-005 开始采购授权
 
-以下三项涉及资金、不可逆动作或权限，必须完整填写。其余交互保留总表条目。
+**目标**：让管理员用一个明确动作把选中任务授权给采购工具创建待付款订单，同时避免重复授权或
+让用户误以为系统会付款。
 
-### IX-005 试选确认与下单授权
+- 前置：已登录；至少一条 `DRAFT` 被选中；页面持有每条任务当前版本。
+- 触发：点击“开始采购（只创建待付款订单）”。
+- 点击本身即授权，不再弹出“机器选对了吗”或试选确认，也不需要第二个同义确认按钮。
 
-- 关联用户故事：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. “已选 N 条”；
+2. 所选任务最高总价之和；
+3. “采购工具会逐条创建待付款订单，系统不会付款”；
+4. 主按钮“开始采购（只创建待付款订单）”。
 
-**正常路径**
-
-1. 用户进入详情页，看到需求与机器所选的逐项对照、单价、合计和规格面板截图。
-2. 各项均为 ✓ 时，「确认下单（不付款）」可用。
-3. 用户点击确认，系统签发授权并**锁定本次试选的单价**，任务转 `AUTHORIZED`。
-4. 页面明确提示：只会创建待付款订单，付款需人在拼多多完成。
-
-**状态与异常清单**
-
-| 场景 | 本交互约定 |
+| 状态 | 行为 |
 | --- | --- |
-| 默认 / 可操作 | 各项 ✓ 时确认按钮可用；截图必须已加载出来才允许确认 |
-| 规格不一致（✗） | **确认按钮禁用**并说明哪一项不符；只能「退回，不买」或转人工 |
-| 金额超上限（✗） | **确认按钮禁用**并显示超出多少；不提供「仍然确认」入口 |
-| 加载 / 提交中 | 按钮禁用并显示进行中，防重复提交 |
-| 成功 | 关闭详情抽屉或返回工作台，该任务显示为已授权并等待桌面端领取第二趟 |
-| 退回 | 二次确认后任务终止为 `CANCELED`，说明不会再自动执行 |
-| 服务或网络错误 | 保留页面状态，说明原因并允许重试 |
-| 权限不足 | 设备凭据调用此接口一律 403 并记录；页面不暴露任务内容 |
-| 冲突 / 重复提交 | `expected_task_version` 不匹配返回 409，提示任务已变化并刷新；重复提交幂等，只产生一笔订单 |
-| 破坏性操作 | 确认会导致真实下单。提交前必须显示授权金额上限与「系统只下单不付款」 |
-| 试选已过期 | 授权过期后任务转待重新试选；完成新试选前不显示确认入口，页面明确说明旧价不再有效 |
-| 中断 / 离线 | 未提交的备注不保存；重进页面回到未确认状态 |
+| 未选择 | 按钮禁用，说明“请选择待开始任务” |
+| 选择中 | 只统计可选 `DRAFT`；非 DRAFT checkbox 禁用且有原因 |
+| 提交中 | 按钮禁用并显示“正在授权…”；避免双击，焦点不跳走 |
+| 成功 | 表格更新为 `PENDING`，清空已成功选择，toast/实时区提示授权数量和“不付款” |
+| 任一版本冲突 | 整批不变，保留筛选，清除失效选择并提示刷新后重选 |
+| 网络结果不明 | 使用同一 `start_key` 查询/重放，不生成新 key；不要直接再次授权 |
 
-**可访问性与多端**
-
-- 确认与退回按钮可键盘到达，焦点可见。
-- ✓ / ✗ 不能只靠颜色区分，必须带文字。
-- 窄屏下截图可放大查看，不被裁切到看不清规格。
+无障碍：操作条出现在表格前，状态变化用礼貌 `aria-live`；按钮具有可见焦点，文案不依赖颜色或图标。
 
 ### IX-006 待付款核对与标记完成
 
-- 关联用户故事：US-006 ｜ 关联需求：F-009 收口
-- 页面 / 组件：web `/tasks/{id}` 的 `PaymentCheckCard`
-- 目标角色：采购管理员（采购执行员在拼多多完成人工付款并反馈结果）
-- 前置条件：任务状态为 `WAITING_PAYMENT`，已收到订单截图
-- 服务依赖：`POST /tasks/{id}/mark-paid`
+- 页面显示商品、目标与实际规格、数量、授权上限、两次单价、确认页总额和订单截图。
+- 首屏警示：“订单已创建，系统尚未付款。请在拼多多人工核对并付款。”
+- “标记为已付款并完成”只写系统状态，不打开支付页面、不触发手机操作。
+- 提交前用简短确认对话框说明这是人工事实记录；成功转 `SUCCEEDED`，重复提交幂等。
+- 信息不一致时提供“转人工处理”，不提供“重新提交订单”。
 
-**MVP 简化版**：系统只展示，不自动回读。自动核对是 F-016（V2）。
+### IX-008 桌面端轮询与单趟执行
 
-**正常路径**
+采购工具固定两个 tab：“采购执行”（默认）和“配置”。采购执行顶部第一行依次显示采购服务、设备、
+拼多多版本、会话状态与“开始/停止轮询”；不另占一行。
 
-1. 用户看到订单截图、商品、规格、数量和授权金额。
-2. 用户在拼多多手工核对并付款。
-3. 用户回到页面点「已付款」，任务转 `SUCCEEDED`。
+主体保持左右结构：
 
-**状态与异常清单**
+- 左上：当前任务文字占约 2/3，商品图片占右侧约 1/3；无图显示稳定占位。
+- 左下：滚动日志，占用剩余高度；最新日志可自动跟随，用户上滚后不强制跳底。
+- 右侧：采购记录表格，按时间倒序，仅显示标题和状态。
+- 双击/Enter 记录后不弹窗，在左侧显示该记录：左侧原始文字、右侧图片、下方执行结果。
+- 按 Esc 或“返回当前任务”恢复当前任务视图；查看历史不暂停、不取消、不更改服务端状态。
 
-| 场景 | 本交互约定 |
+单趟可见阶段：
+
+```text
+待领取 → 已领取 → 打开商品 → 打开规格面板 → 选择规格
+→ 闸门一 → 数量复核 → 闸门二 → 确认页 / 闸门三
+→ 申请围栏 → 已发出唯一提交 → 待付款 / 待调和
+```
+
+| 情况 | 反馈和下一步 |
 | --- | --- |
-| 默认 | 显著提示「对不上就别付」，并说明不一致时回来标记异常而不是在拼多多改单 |
-| 成功 | 任务转已完成，记录标记人与时间 |
-| 金额或规格对不上 | 提供「标记异常」转 `NEEDS_MANUAL`，不允许直接标已付款 |
-| 截图缺失 | 说明证据缺失并转人工，**不允许在无证据情况下标记完成** |
-| 重复标记 | 幂等，不产生第二条完成记录 |
-| 破坏性操作 | 本交互不产生任何写平台动作，只改本地状态 |
+| 服务/设备/App 未就绪 | 开始轮询禁用；状态区给出具体修复入口 |
+| 正在领取或执行 | 显示阶段与任务；停止轮询只阻止下一次领取，不中断当前安全步骤 |
+| 规格、价格、数量或确认页失败 | 记录固定 reason code，停止点击并进入待人工 |
+| 正在申请围栏 | 禁用停止当前任务、退出和任何提交动作；界面只显示进度 |
+| 围栏响应不明 | 不点击，进入待调和 |
+| 已围栏 / 点击结果不明 | 红色安全横幅“可能已创建订单，禁止再次提交”；只能调和 |
+| 外部支付或安全校验 | 立即停止，不与页面继续交互；保存允许的证据并提示人工接管 |
+| 连续轮询失败 | 达阈值自动停止会话；当前已围栏提交不受影响 |
 
-### 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」并转人工，不自动下单也不自动放弃 |
-| 运行中变更 | 冻结设备切换和参数保存 |
-| 服务端不可达 | 保留本地结果与证据，提示待补传，不丢弃已完成工作 |
+键盘：Tab 顺序与视觉一致；表格上下箭头移动当前行，Enter 查看，Shift+F10 打开上下文菜单；Esc
+优先关闭菜单，其次返回当前任务视图。Esc、关闭窗口和停止轮询都不能释放围栏或触发重试。
 
 ### 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. 当前任务在同一趟内完成闸门二和闸门三，并确认提交控件精确唯一。
+2. 客户端显示“正在申请提交围栏”，提交当前验证摘要。
+3. 只有服务端首次明确返回 `click_permitted=true`，客户端才先持久化唯一点击意图，再精确点击一次。
+4. 明确创建转待付款；外部支付、安全校验、超时、断连或未知页面转待调和。
+5. 围栏后的 web 详情只显示同一 `submission_id` 的证据、调和记录与人工结论。
 
-1. dry-run 以醒目的「只读演练」标识运行，到确认页读取并验证后退出，不出现提交动作。
-2. 真实第二趟在三道闸门通过后显示「正在申请提交围栏」，此时不允许点击或取消。
-3. 只有服务端明确返回 `click_permitted` 后执行一次点击，界面立即进入「正在核对订单结果」。
-4. 明确创建后转待付款；结果不明确则两端都显示同一 `submission_id` 与「可能已创建」，
-   只提供人工核查，不提供重试或放弃。
+| 状态 | 允许动作 | 禁止动作 |
+| --- | --- | --- |
+| 围栏前 | 停止并转人工；管理员可安全重置为 DRAFT | 绕过闸门、客户端自签授权 |
+| 围栏申请结果不明 | 不点击，记录待调和 | 换 key 申请、点击猜测 |
+| 围栏已建立 | 上报一次观察结果、人工调和 | 释放授权、重新开始、再次点击 |
+| 明确待付款 | 人工核对/付款/标记完成 | 系统支付 |
 
-**状态与异常清单**
+围栏重放响应不授予点击许可。调和页面不得出现普通“重试”按钮。
 
-| 场景 | 本交互约定 |
-| --- | --- |
-| dry-run | 蓝色信息态并固定显示「不会提交订单」；完成后有证据摘要 |
-| 围栏申请中 | 主操作禁用、显示进度；关闭窗口受控，避免用户误以为可重来 |
-| 围栏申请失败 / 响应不明 | **不点击**；展示幂等键与核查入口 |
-| 围栏成功 | 显示唯一提交编号；只允许内部流程点击一次，不向用户暴露第二个提交按钮 |
-| 点击后明确创建 | 转待付款并显示订单证据 |
-| 点击后超时 / 外部支付 / 安全校验 | 转 `RECONCILIATION_REQUIRED`；显著提示可能已创建并预留额度 |
-| 重复打开或恢复 | 恢复同一提交编号和调和状态，不重新领取、不重新点击 |
-| 人工核查 | 可记录「已创建 / 未创建 / 仍不明确」及证据；系统本身不发起新的下单 |
+### IX-012 批量选择
+
+- 第一列为 checkbox；表头全选只覆盖当前筛选结果中可授权的 `DRAFT`。
+- 行单击只改变当前/焦点行，不等于勾选；双击行打开详情，不切换 checkbox。
+- 状态变化、翻页或筛选后失效的选择必须清除并告知，不能静默作用于不可见旧数据。
+- 不在每行增加“开始采购”操作列；批量操作统一位于表格上方上下文操作条。
+- 移动端表格允许水平滚动，不把关键金额和授权动作压成不可读卡片。
 
 ## 四、通用要求
 
-适用于所有 P0 交互：
-
-- **禁用按钮必须说明原因**，不留用户猜。
-- **失败必须给下一步**，不只报错。
-- **空状态是邀请，不是错误**。
-- 破坏性与不可逆动作必须二次确认，并说明影响范围。
-- 键盘可达、焦点可见、`prefers-reduced-motion` 生效。
-- 状态不能只靠颜色表达。
-- 金额一律显示两位小数并标注币种。
-- 双击只能作为效率快捷方式；任务编号链接和聚焦行后按 Enter 必须提供等价详情入口。
-- 表格行内的复选框、商品外链和任务编号链接不得误触发行双击；关闭详情抽屉后焦点回到原行。
-- 表格批量栏只在存在选择时出现；全选只覆盖当前筛选结果中允许当前动作的行。
+- 中文文案，状态名面向用户；技术 code 只出现在可复制详情中。
+- 所有输入有可见 label，错误与字段关联；必填不只靠星号。
+- 可交互元素有键盘可见焦点，目标尺寸至少 40–44 px；不依赖 hover 才能发现关键操作。
+- 加载、空态、失败、离线、禁用、成功、超时和结果不明均有明确表现。
+- 尊重 `prefers-reduced-motion`；状态变化不使用闪烁或大幅位移动画。
+- 高影响动作要说明范围与后果。开始采购已由持续可见的操作条和具体按钮文案完成确认，不再叠加
+  一个同义模态框；取消、人工付款事实等不同后果仍按各自流程确认。
+- 关闭抽屉、返回列表或查看历史记录必须恢复触发点焦点和筛选/滚动现场。
+- 内部截图有权限和不缓存标识；不把地址/手机号做成搜索字段，不展示完整 XML。
 
 ## 五、交付前检查
 
-- [ ] 每项 P0 交互回链至少一个 US 编号。
-- [ ] 涉及资金或不可逆动作的交互已填写完整状态表。
-- [ ] 所有禁用态都有说明文案。
-- [ ] 所有空状态都有可执行的下一步。
-- [ ] 未在本文自行定义接口路径、字段或状态码。
+- Web：375 / 768 / 1024 / 1440 px；键盘、焦点、表格横向滚动、抽屉返回均检查。
+- Desk：compact / medium / wide；浅色、深色、高对比近似；键盘和窗口关闭路径检查。
+- 单趟状态与 [architecture](04-architecture.md)、[api](api.md) 完全一致。
+- 页面没有 `WAITING_CONFIRMATION`、第二趟、锁定试选价或管理员中途确认。
+- “开始采购”处始终可见“只创建待付款订单 / 系统不付款”。
+- 围栏后没有重试、释放授权或重新开始入口。