cmbuyer/docs/routes.md

路由与页面结构

本文约定 web 端页面路由、页面职责和组件归属，以及 desk 端的界面结构。 具体交互行为以交互清单为准，接口形状以 API 合约 为准。

一、web 端页面路由

路由	页面	职责	用户故事	交互
/login	登录	建立管理会话	US-007	IX-001
/tasks	采购任务	传统表格查询、创建弹窗、批量开始试选、进入详情抽屉	US-001、US-002、US-010	IX-002、IX-003、IX-004、IX-012
/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

采用采购人员熟悉的传统表格，默认按创建时间倒序。固定列为：选择、标题、颜色、尺码、 价格上限、数量、采购结果、状态、创建时间；不设置操作列。

• 标题链接在新标签打开拼多多商品页；标题下方任务编号链接打开内部任务详情。
• “采购结果”由结构化字段在展示层格式化为“阶段：颜色 | 尺码 | 单价 | 数量”；未产生 试选或下单结果时显示 —，不得把试选写成已下单。
• 双击行非控件区域，或聚焦行后按 Enter，打开 /tasks/{id} 的右侧详情抽屉。关闭抽屉、 按 Esc 或浏览器返回后，保留筛选、选择、滚动位置并把焦点还给原行。
• 直接访问 /tasks/{id} 或在抽屉中选择“在完整页面打开”时，使用完整详情页；关键路由可 深链接，不能只有无法复制地址的弹层状态。
• 第一工具行：导入（MVP 禁用占位并说明原因）、创建。创建打开模态表单；保存后任务以 DRAFT 状态出现在第一行。/tasks/new 保留为同表单的直达兜底。
• 第二工具行默认显示标题关键词、筛选、清除；状态和创建时间放在默认折叠的“更多条件”中， 保留 F-004 查询范围而不挤占常用操作。勾选 DRAFT 后切换成上下文批量栏，显示已选数量、 开始试选、清除选择；全选只覆盖当前筛选结果中的 DRAFT。
• “开始试选”把所选任务原子转为 PENDING，只进入第一趟试选队列；不签发授权、不创建 订单、不付款。其他状态复选框禁用并说明原因。
• 窄屏允许表格容器内部横向滚动，但页面本身不得横向溢出；选择列与标题列保持可见。

任务详情 /tasks/{id}

按任务当前状态呈现不同主区块，同一时刻只出现一个主动作：

状态	主区块
WAITING_CONFIRMATION	试选确认卡 + 确认 / 退回
AUTHORIZED / 未围栏的 ORDERING	授权摘要 + 放弃授权入口
已围栏的 ORDERING / RECONCILIATION_REQUIRED	提交围栏摘要 + 「订单可能已创建」提示 + 人工核查入口；无重试 / 放弃按钮
WAITING_PAYMENT	待付款核对卡（订单截图、商品、规格、数量、授权金额）+ 标记完成
NEEDS_MANUAL	原因说明 + 处理入口
终态	结果摘要 + 执行证据

试选确认卡是 MVP 的核心交互。人只回答一个问题：机器选对了吗。

你要的：   白色 · XL · 2 件 · 上限 ¥80
机器选到： 白色 · XL          ✓ 一致
          单价 ¥32.50 × 2 = ¥65.00   ✓ 没超
          [规格面板截图]
          商品标题：2026夏季新款纯棉圆领短袖T恤…

          [ 确认下单（不付款） ]   [ 退回，不买 ]

• 这是轻量确认，不是对照台——只有一个商品，不需要并排比较多个候选。 多候选对照台随 B 路径推迟到 V2。
• 不需要「选择理由 / 拒绝理由」下拉，保留一个可选备注即可。
• 机器选到的值与需求不一致时（✗），确认按钮默认禁用，需先退回或转人工。
• 不提供列表页一键确认。 确认前必须看过截图，这道闸不能省。

授权卡住时的出口

AUTHORIZED / 未建立提交围栏的 ORDERING 必须提供「放弃授权」入口；放弃后进入 PENDING_RETRIAL，重新跑第一趟。围栏建立后不得放弃，页面改为提供「进入人工核查」入口， 并明确禁止再次提交。每个状态都必须给出安全且可执行的下一步——这是验收项。

建单页

/tasks 的创建弹窗与 /tasks/new 直达页复用同一表单：任务名称、拼多多链接、颜色分类、 尺码、数量、价格上限。链接无法解析出 goods_id 时明确报错并保留已填内容；保存成功后 任务为 DRAFT，尚未进入设备领取队列。

三、desk 端界面结构

桌面端不是网页，用固定两页签，不做多级导航：

页签	职责	用户故事	交互
采购执行	连接状态、轮询开关、当前任务与步骤、待人工提示	US-003、US-008	IX-007、IX-008
设备与参数	设备档案、ADB 路径与 serial、超时参数、连接检查	US-003	IX-007

采购执行页

• 顶部：web 端连接状态 + 设备连接状态，两者都绿才能启动轮询。
• 顶部同时显示拼多多 App 实际版本与已取证版本；不一致时停止轮询并提示重新取证。
• 中部：当前任务卡（商品、规格、数量、当前是第一趟还是第二趟、当前步骤、剩余租约）。
• 底部：轮询控制条（开始轮询 / 停止轮询）+ 下次轮询倒计时 + 连续失败计数。
• 待人工时整页显著变色并说明缺什么，不要让执行员盯着一个静止画面猜。
• 关闭窗口即停止轮询；连续失败达阈值自动停止并显示原因。

设备与参数页

• 设备档案必须显式填写 serial，不允许留空自动选——同一手机 USB + WiFi 同时在线时 自动选会失败（见架构设计第六节）。
• 连接检查只做连接和确认拼多多已安装，不打开商品、不选规格、不创建订单。
• 运行中冻结设备切换与参数保存。

四、导航规则

• web 端从路由化详情抽屉返回工作台时不重新加载列表；完整详情页返回时保留原筛选条件。
• desk 端启动时若服务端有本设备的活跃任务，优先恢复该任务，不允许直接领取下一条。
• 第一趟试选完成后必须退出商品页再进入下一轮轮询，不停在规格面板等人。
• desk 端在真机步骤执行期间禁用硬取消和关闭窗口，避免留下无法判定的中间态。
• 任何进入外部支付页的情形，desk 端立即停止并跳回待人工，不提供「继续」按钮。
• dry-run 与真实下单必须使用不同的醒目标识；dry-run 不得出现可触发真实提交的控件。
• 已建立提交围栏后，不提供重新领取、重新提交或放弃授权，只能恢复同一提交记录并调和。

五、组件归属

组件	归属	说明
AppShell	web 全局	导航、登录态、CSRF 注入
TaskTable	采购任务	任务表格、创建时间倒序、选择状态与结构化采购结果格式化
QueryBar	采购任务	标题关键词、筛选与清除
BulkTrialBar	采购任务	DRAFT 批量选择与开始第一趟试选
CreateTaskDialog	采购任务 / 建单直达页	复用手工建单表单与字段错误
TaskDetailDrawer	采购任务	/tasks/{id} 路由驱动的右侧详情容器与焦点恢复
SpecTrialCard	任务详情	试选确认卡（MVP 签名组件）
AuthorizePanel	任务详情	确认 / 退回 / 放弃授权
PaymentCheckCard	任务详情	待付款核对与标记完成
DeviceStatusBar	desk 采购执行页	双连接状态
PollControls	desk 采购执行页	轮询开关、倒计时、失败计数

六、原型

低保真原型放 docs/design/，约定见 design/README.md。 原型只回答「页面上有什么」，行为权威是交互清单； 实现时按真实框架重写，不复制原型代码。