131 lines
6.9 KiB
Markdown
131 lines
6.9 KiB
Markdown
# 路由与页面结构
|
||
|
||
> 本文约定 web 端页面路由、页面职责和组件归属，以及 desk 端的界面结构。
|
||
> 具体交互行为以[交互清单](08-interaction-checklist.md)为准，接口形状以 [API 合约](api.md) 为准。
|
||
|
||
## 一、web 端页面路由
|
||
|
||
| 路由 | 页面 | 职责 | 用户故事 | 交互 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `/login` | 登录 | 建立管理会话 | US-007 | IX-001 |
|
||
| `/tasks` | 工作台 | 按「谁持球」查看任务、查询筛选、进入详情 | US-002 | IX-003 |
|
||
| `/tasks/new` | 手工建单 | 填链接、颜色分类、尺码、数量、价格上限 | US-001 | IX-002 |
|
||
| `/tasks/{id}` | 任务详情 | 看要求与执行结果；**试选确认与授权**；待付款核对 | US-002、US-004、US-005 | IX-004、IX-005、IX-006 |
|
||
|
||
> `/tasks/import`（Excel）与 `/freight*`（ERP）随 F-002 / F-003 推迟到 V2。
|
||
|
||
登录后默认进入 `/tasks`。未登录访问受保护页面时跳转 `/login` 并携带站内返回路径；
|
||
**只接受 `/tasks` 及其子路径**，拒绝绝对 URL、`//` 和反斜杠。
|
||
|
||
## 二、web 端页面职责
|
||
|
||
### 工作台 `/tasks`
|
||
|
||
按**谁持球**分三条泳道，不按状态码平铺：
|
||
|
||
| 泳道 | 包含状态 | 含义 |
|
||
| --- | --- | --- |
|
||
| 等你决定 | `WAITING_CONFIRMATION`、`WAITING_PAYMENT`、`NEEDS_MANUAL`、`RECONCILIATION_REQUIRED` | 停在这里等人 |
|
||
| 机器在跑 | `PENDING`、`PENDING_RETRIAL`、`CLAIMED`、`RUNNING(TRIAL)`、`AUTHORIZED`、`ORDERING` | 不用操作 |
|
||
| 已结束 | `SUCCEEDED`、`FAILED`、`CANCELED` | 归档 |
|
||
|
||
- 落地时**第一条待决策任务直接展开**，不是先看一张表。
|
||
- 查询：关键词（标题 / 规格 / 任务编号）、泳道、时间范围。
|
||
- 计数只随关键词和时间范围变化，不随泳道选择变化。
|
||
|
||
### 任务详情 `/tasks/{id}`
|
||
|
||
按任务当前状态呈现不同主区块，同一时刻只出现一个主动作：
|
||
|
||
| 状态 | 主区块 |
|
||
| --- | --- |
|
||
| `WAITING_CONFIRMATION` | **试选确认卡** + 确认 / 退回 |
|
||
| `AUTHORIZED` / 未围栏的 `ORDERING` | 授权摘要 + **放弃授权**入口 |
|
||
| 已围栏的 `ORDERING` / `RECONCILIATION_REQUIRED` | 提交围栏摘要 + 「订单可能已创建」提示 + 人工核查入口；**无重试 / 放弃按钮** |
|
||
| `WAITING_PAYMENT` | 待付款核对卡（订单截图、商品、规格、数量、授权金额）+ 标记完成 |
|
||
| `NEEDS_MANUAL` | 原因说明 + 处理入口 |
|
||
| 终态 | 结果摘要 + 执行证据 |
|
||
|
||
**试选确认卡**是 MVP 的核心交互。人只回答一个问题：**机器选对了吗**。
|
||
|
||
```text
|
||
你要的： 白色 · XL · 2 件 · 上限 ¥80
|
||
机器选到： 白色 · XL ✓ 一致
|
||
单价 ¥32.50 × 2 = ¥65.00 ✓ 没超
|
||
[规格面板截图]
|
||
商品标题：2026夏季新款纯棉圆领短袖T恤…
|
||
|
||
[ 确认下单（不付款） ] [ 退回，不买 ]
|
||
```
|
||
|
||
- 这是**轻量确认，不是对照台**——只有一个商品，不需要并排比较多个候选。
|
||
多候选对照台随 B 路径推迟到 V2。
|
||
- 不需要「选择理由 / 拒绝理由」下拉，保留一个可选备注即可。
|
||
- 机器选到的值与需求不一致时（✗），确认按钮**默认禁用**，需先退回或转人工。
|
||
- **不提供列表页一键确认。** 确认前必须看过截图，这道闸不能省。
|
||
|
||
### 授权卡住时的出口
|
||
|
||
`AUTHORIZED` / 未建立提交围栏的 `ORDERING` 必须提供「放弃授权」入口；放弃后进入
|
||
`PENDING_RETRIAL`，重新跑第一趟。围栏建立后不得放弃，页面改为提供「进入人工核查」入口，
|
||
并明确禁止再次提交。**每个状态都必须给出安全且可执行的下一步**——这是验收项。
|
||
|
||
### 建单页
|
||
|
||
`/tasks/new` 填：任务名称、拼多多链接、颜色分类、尺码、数量、价格上限。
|
||
链接无法解析出 `goods_id` 时明确报错并保留已填内容。
|
||
|
||
## 三、desk 端界面结构
|
||
|
||
桌面端不是网页，用固定两页签，不做多级导航：
|
||
|
||
| 页签 | 职责 | 用户故事 | 交互 |
|
||
| --- | --- | --- | --- |
|
||
| 采购执行 | 连接状态、轮询开关、当前任务与步骤、待人工提示 | US-003、US-008 | IX-007、IX-008 |
|
||
| 设备与参数 | 设备档案、ADB 路径与 serial、超时参数、连接检查 | US-003 | IX-007 |
|
||
|
||
### 采购执行页
|
||
|
||
- 顶部：web 端连接状态 + 设备连接状态，两者都绿才能启动轮询。
|
||
- 顶部同时显示拼多多 App 实际版本与已取证版本；不一致时停止轮询并提示重新取证。
|
||
- 中部：当前任务卡（商品、规格、数量、**当前是第一趟还是第二趟**、当前步骤、剩余租约）。
|
||
- 底部：轮询控制条（开始轮询 / 停止轮询）+ 下次轮询倒计时 + 连续失败计数。
|
||
- **待人工时整页显著变色并说明缺什么**，不要让执行员盯着一个静止画面猜。
|
||
- 关闭窗口即停止轮询；连续失败达阈值自动停止并显示原因。
|
||
|
||
### 设备与参数页
|
||
|
||
- 设备档案必须**显式填写 serial**，不允许留空自动选——同一手机 USB + WiFi 同时在线时
|
||
自动选会失败（见[架构设计](04-architecture.md)第六节）。
|
||
- 连接检查只做连接和确认拼多多已安装，**不打开商品、不选规格、不创建订单**。
|
||
- 运行中冻结设备切换与参数保存。
|
||
|
||
## 四、导航规则
|
||
|
||
- web 端任务详情返回工作台时保留原筛选条件。
|
||
- desk 端启动时若服务端有本设备的活跃任务，优先恢复该任务，不允许直接领取下一条。
|
||
- 第一趟试选完成后**必须退出商品页**再进入下一轮轮询，不停在规格面板等人。
|
||
- desk 端在真机步骤执行期间禁用硬取消和关闭窗口，避免留下无法判定的中间态。
|
||
- 任何进入外部支付页的情形，desk 端立即停止并跳回待人工，**不提供「继续」按钮**。
|
||
- dry-run 与真实下单必须使用不同的醒目标识；dry-run 不得出现可触发真实提交的控件。
|
||
- 已建立提交围栏后，不提供重新领取、重新提交或放弃授权，只能恢复同一提交记录并调和。
|
||
|
||
## 五、组件归属
|
||
|
||
| 组件 | 归属 | 说明 |
|
||
| --- | --- | --- |
|
||
| `AppShell` | web 全局 | 导航、登录态、CSRF 注入 |
|
||
| `TaskLanes` | 工作台 | 三泳道渲染与折叠 |
|
||
| `QueryBar` | 工作台 | 关键词、泳道、时间范围 |
|
||
| `SpecTrialCard` | 任务详情 | 试选确认卡（MVP 签名组件） |
|
||
| `AuthorizePanel` | 任务详情 | 确认 / 退回 / 放弃授权 |
|
||
| `PaymentCheckCard` | 任务详情 | 待付款核对与标记完成 |
|
||
| `DeviceStatusBar` | desk 采购执行页 | 双连接状态 |
|
||
| `PollControls` | desk 采购执行页 | 轮询开关、倒计时、失败计数 |
|
||
|
||
## 六、原型
|
||
|
||
低保真原型放 `docs/design/`，约定见 [`design/README.md`](design/README.md)。
|
||
原型只回答「页面上有什么」，行为权威是[交互清单](08-interaction-checklist.md)；
|
||
实现时按真实框架重写，**不复制原型代码**。
|