151 lines
9.8 KiB
Markdown
151 lines
9.8 KiB
Markdown
# 交互清单
|
||
|
||
> 本文是界面行为权威。需求范围见[需求](02-requirements.md)，页面位置见[routes](routes.md)。
|
||
|
||
## 一、职责边界
|
||
|
||
- 采购服务负责建单、开始采购授权、任务详情、内部证据、调和和人工付款收口。
|
||
- 采购工具负责连接手机、轮询领取、单趟执行、日志和本地记录详情。
|
||
- “开始采购”是管理员对创建待付款订单的明确授权；不再有试选后的确认页面。
|
||
- 任一端都不自动付款；围栏后不提供重试或释放动作。
|
||
|
||
## 二、交互总表
|
||
|
||
| 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 | 保存并校验配置 | 本地字段/路径有效；服务身份与真机能力在真实流程中验证 | 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 | 已定 |
|
||
|
||
## 三、P0 高风险交互
|
||
|
||
### IX-005 开始采购授权
|
||
|
||
**目标**：让管理员用一个明确动作把选中任务授权给采购工具创建待付款订单，同时避免重复授权或
|
||
让用户误以为系统会付款。
|
||
|
||
- 前置：已登录；至少一条 `DRAFT` 被选中；页面持有每条任务当前版本。
|
||
- 触发：点击“开始采购（只创建待付款订单）”。
|
||
- 点击本身即授权，不再弹出“机器选对了吗”或试选确认，也不需要第二个同义确认按钮。
|
||
|
||
操作条必须持续展示：
|
||
|
||
1. “已选 N 条”；
|
||
2. 所选任务最高总价之和；
|
||
3. “采购工具会逐条创建待付款订单，系统不会付款”；
|
||
4. 主按钮“开始采购（只创建待付款订单）”。
|
||
|
||
| 状态 | 行为 |
|
||
| --- | --- |
|
||
| 未选择 | 按钮禁用，说明“请选择待开始任务” |
|
||
| 选择中 | 只统计可选 `DRAFT`；非 DRAFT checkbox 禁用且有原因 |
|
||
| 提交中 | 按钮禁用并显示“正在授权…”；避免双击，焦点不跳走 |
|
||
| 成功 | 表格更新为 `PENDING`，清空已成功选择，toast/实时区提示授权数量和“不付款” |
|
||
| 任一版本冲突 | 整批不变，保留筛选，清除失效选择并提示刷新后重选 |
|
||
| 网络结果不明 | 使用同一 `start_key` 查询/重放，不生成新 key；不要直接再次授权 |
|
||
|
||
无障碍：操作条出现在表格前，状态变化用礼貌 `aria-live`；按钮具有可见焦点，文案不依赖颜色或图标。
|
||
|
||
### IX-006 待付款核对与标记完成
|
||
|
||
- 页面显示商品、目标与实际规格、数量、授权上限、闸门一单价、闸门二顶部总额、闸门三最终控件同额校验和
|
||
三闸门内部证据；MVP
|
||
没有提交后结果截图类型，不把 Gate3 最终面板图片冒充订单结果图。
|
||
- 首屏警示：“订单已创建，系统尚未付款。请在拼多多人工核对并付款。”
|
||
- “标记为已付款并完成”只写系统状态，不打开支付页面、不触发手机操作。
|
||
- 提交前用简短确认对话框说明这是人工事实记录；成功转 `SUCCEEDED`，重复提交幂等。
|
||
- 信息不一致时提供“转人工处理”，不提供“重新提交订单”。
|
||
|
||
### IX-008 桌面端轮询与单趟执行
|
||
|
||
采购工具固定两个 tab：“采购执行”（默认）和“配置”。采购执行顶部第一行依次显示采购服务、设备、
|
||
拼多多版本、会话状态与“开始/停止轮询”；不另占一行。
|
||
|
||
主体保持左右结构：
|
||
|
||
- 左上：当前任务文字占约 2/3，商品图片占右侧约 1/3；无图显示稳定占位。
|
||
- 左下：滚动日志，占用剩余高度；最新日志可自动跟随，用户上滚后不强制跳底。
|
||
- 右侧：采购记录表格，按时间倒序，仅显示标题和状态。
|
||
- 双击/Enter 记录后不弹窗，在左侧显示该记录：左侧原始文字、右侧图片、下方执行结果。
|
||
- 按 Esc 或“返回当前任务”恢复当前任务视图；查看历史不暂停、不取消、不更改服务端状态。
|
||
|
||
单趟可见阶段：
|
||
|
||
```text
|
||
待领取 → 已领取 → 打开商品 → 打开规格面板 → 选择规格
|
||
→ 闸门一 → 数量复核 → 闸门二 → 同一最终面板 / 闸门三
|
||
→ 申请围栏 → 已发出唯一提交 → 待付款 / 待调和
|
||
```
|
||
|
||
| 情况 | 反馈和下一步 |
|
||
| --- | --- |
|
||
| 服务/设备/App 未就绪 | 开始轮询禁用；状态区给出具体修复入口 |
|
||
| 正在领取或执行 | 显示阶段与任务；停止轮询只阻止下一次领取，不中断当前安全步骤 |
|
||
| 规格、价格、数量或闸门三失败 | 记录固定 reason code，停止点击并进入待人工 |
|
||
| 正在申请围栏 | 禁用停止当前任务、退出和任何提交动作；界面只显示进度 |
|
||
| 围栏响应不明 | 不点击，进入待调和 |
|
||
| 已围栏 / 点击结果不明 | 红色安全横幅“可能已创建订单，禁止再次提交”；只能调和 |
|
||
| 外部支付或安全校验 | 立即停止，不与页面继续交互；保存允许的证据并提示人工接管 |
|
||
| 连续轮询失败 | 达阈值自动停止会话；当前已围栏提交不受影响 |
|
||
|
||
键盘：Tab 顺序与视觉一致；表格上下箭头移动当前行，Enter 查看，Shift+F10 打开上下文菜单；Esc
|
||
优先关闭菜单，其次返回当前任务视图。Esc、关闭窗口和停止轮询都不能释放围栏或触发重试。
|
||
|
||
### IX-011 提交围栏与结果调和
|
||
|
||
围栏由后台流程自动申请，不向执行员提供“提交订单”按钮。
|
||
|
||
1. 当前任务在同一合并式最终提交面板完成闸门二和闸门三，并确认结构化文本及最近可点击祖先唯一。
|
||
2. 客户端显示“正在申请提交围栏”，提交当前验证摘要。
|
||
3. 只有服务端首次明确返回 `click_permitted=true`，客户端才先持久化唯一点击意图，再精确点击一次。
|
||
4. MVP 首次真实点击后因没有已取证的提交后页面判据，无条件上报 `UNKNOWN` 并转待调和；只有管理员
|
||
对同一 submission 明确调和为已创建，才转待付款。
|
||
5. 围栏后的 web 详情只显示同一 `submission_id` 的证据、调和记录与人工结论。
|
||
|
||
| 状态 | 允许动作 | 禁止动作 |
|
||
| --- | --- | --- |
|
||
| 围栏前 | 停止并转人工；管理员可安全重置为 DRAFT | 绕过闸门、客户端自签授权 |
|
||
| 围栏申请结果不明 | 不点击，记录待调和 | 换 key 申请、点击猜测 |
|
||
| 围栏已建立 | 上报一次观察结果、人工调和 | 释放授权、重新开始、再次点击 |
|
||
| 明确待付款 | 人工核对/付款/标记完成 | 系统支付 |
|
||
|
||
围栏重放响应不授予点击许可。调和页面不得出现普通“重试”按钮。
|
||
|
||
### IX-012 批量选择
|
||
|
||
- 第一列为 checkbox；表头全选只覆盖当前筛选结果中可授权的 `DRAFT`。
|
||
- 行单击只改变当前/焦点行，不等于勾选；双击行打开详情，不切换 checkbox。
|
||
- 状态变化、翻页或筛选后失效的选择必须清除并告知，不能静默作用于不可见旧数据。
|
||
- 不在每行增加“开始采购”操作列；批量操作统一位于表格上方上下文操作条。
|
||
- 移动端表格允许水平滚动，不把关键金额和授权动作压成不可读卡片。
|
||
|
||
## 四、通用要求
|
||
|
||
- 中文文案，状态名面向用户；技术 code 只出现在可复制详情中。
|
||
- 所有输入有可见 label，错误与字段关联；必填不只靠星号。
|
||
- 可交互元素有键盘可见焦点，目标尺寸至少 40–44 px；不依赖 hover 才能发现关键操作。
|
||
- 加载、空态、失败、离线、禁用、成功、超时和结果不明均有明确表现。
|
||
- 尊重 `prefers-reduced-motion`；状态变化不使用闪烁或大幅位移动画。
|
||
- 高影响动作要说明范围与后果。开始采购已由持续可见的操作条和具体按钮文案完成确认，不再叠加
|
||
一个同义模态框；取消、人工付款事实等不同后果仍按各自流程确认。
|
||
- 关闭抽屉、返回列表或查看历史记录必须恢复触发点焦点和筛选/滚动现场。
|
||
- 内部截图有权限和不缓存标识；不把地址/手机号做成搜索字段，不展示完整 XML。
|
||
|
||
## 五、交付前检查
|
||
|
||
- Web：375 / 768 / 1024 / 1440 px；键盘、焦点、表格横向滚动、抽屉返回均检查。
|
||
- Desk：compact / medium / wide；浅色、深色、高对比近似；键盘和窗口关闭路径检查。
|
||
- 单趟状态与 [architecture](04-architecture.md)、[api](api.md) 完全一致。
|
||
- 页面没有 `WAITING_CONFIRMATION`、第二趟、锁定试选价或管理员中途确认。
|
||
- “开始采购”处始终可见“只创建待付款订单 / 系统不付款”。
|
||
- 围栏后没有重试、释放授权或重新开始入口。
|