cmbuyer/docs/routes.md

路由与页面结构

采购服务使用服务端渲染；采购工具使用固定 tab 的 Windows 桌面外壳。交互细节以 08-interaction-checklist.md 为准。

一、采购服务页面路由

方法	路径	页面 / 动作	身份
GET	/login	登录页	匿名
POST	/login	建立会话	匿名 + CSRF
POST	/logout	退出	管理员 + CSRF
GET	/tasks	采购任务表格、筛选、批量选择和创建入口	管理员
GET	/tasks/new	无 JS 时的创建表单；有 JS 时装入对话框	管理员
POST	/tasks	创建 DRAFT	管理员 + CSRF
POST	/tasks/start-purchases	批量开始采购并签发一次性授权	管理员 + CSRF
GET	/tasks/{id}	完整任务详情；也作为列表抽屉的可复制 URL	管理员
POST	/tasks/{id}/reset-to-draft	围栏前人工处理后回待开始	管理员 + CSRF
POST	/tasks/{id}/cancel	围栏前取消	管理员 + CSRF
POST	/tasks/{id}/mark-paid	记录人工已付款并完成	管理员 + CSRF
POST	/order-submissions/{sid}/reconcile	围栏后调和同一提交	管理员 + CSRF
GET	/evidence/{asset_id}	受保护内部截图	管理员；不缓存

设备 JSON API 不属于页面路由，见 api.md。

二、采购任务工作台 /tasks

页面标题：采购服务。

表格上方两行：

1. 第一行：导入（disabled 占位）、创建按钮；存在选择时显示上下文批量操作条。
2. 第二行：标题关键词输入框（默认筛选）、其他可选筛选，右侧“筛选”“清除”。

表格字段：

字段	行为
checkbox	只允许选择 DRAFT；表头全选当前筛选结果中的可选行
标题	<a> 指向 canonical 拼多多商品页；点击链接不触发行详情
颜色	任务目标颜色
尺码	任务目标尺码
价格	任务最高总价；执行后详情另列实际闸门金额
数量	正整数
采购结果	用 `颜色
状态	中文状态徽标，不只靠颜色
创建时间	本地时区显示，数据按 UTC 保存

没有操作列。双击非控件区域或键盘 Enter 打开 /tasks/{id} 路由化详情抽屉；新 tab 直接访问同 URL 则显示完整详情页。标题下方同时提供可见“查看详情”按钮，双击不是唯一入口。商品外链、checkbox、 输入和按钮本身不触发行双击。抽屉成功加载后才把 URL 推进 /tasks/{id}；关闭、Esc 或浏览器返回 恢复筛选、滚动和触发行焦点，浏览器前进重新打开同一详情且不重复写 history。

批量开始采购

选择 DRAFT 后，表格前的上下文操作条显示：

• 已选条数；
• 所选最高总价合计；
• “将授权采购工具逐条创建待付款订单，系统不会付款”；
• 主按钮“开始采购（只创建待付款订单）”。

点击即为最终授权，不另弹“机器选对了吗”的同义确认框。整批全有或全无；成功更新 PENDING， 冲突时保持页面现场并要求刷新重选。

创建任务

字段：标题、拼多多商品链接、颜色分类、尺码、最高总价、数量。保存成功后关闭对话框，新任务插到 首行且状态为待开始；创建本身不授权、不领取、不执行。

三、任务详情 /tasks/{id}

详情按状态展示同一条单趟采购的事实，而不是审批流程：

1. 任务要求：商品链接 / goods_id、颜色、尺码、数量、最高总价、版本。
2. 开始采购授权：授权 id、授权人、锁定任务版本、创建/有效期、当前状态。
3. 设备执行：attempt、设备、App 版本、步骤时间线和失败 code。
4. 三道闸门：闸门一规格面板单价、规格/数量读回、闸门二顶部总额、闸门三最终控件金额同额校验。
5. 内部截图：三道闸门已批准的规格面板/合并式最终提交面板证据；只经受保护端点读取。MVP 不存在提交后结果 截图类型，不展示外部支付页，也不把 Gate3 图片冒充结果图。
6. 提交围栏：submission id、是否首次明确许可、唯一点击和调和记录。
7. 待付款收口：明确写系统尚未付款；人工核对后记录完成。

状态动作：

状态	页面动作
DRAFT	返回列表勾选并开始采购；可编辑/取消（按任务版本）
PENDING / CLAIMED / ORDERING	只读进度；围栏前异常由人工处理，不中途确认规格
NEEDS_MANUAL	查看原因；确认没有围栏后重置为 DRAFT 或取消
RECONCILIATION_REQUIRED	只调和同一 submission；无重试、释放或重新授权
WAITING_PAYMENT	查看证据、人工付款、标记完成或转人工
终态	只读审计

详情中不出现 WAITING_CONFIRMATION、“确认机器选对了吗”、“签发第二趟授权”或“重新试选”。

完整页与抽屉执行同一 task-detail-content 模板和只读查询。直接导航返回完整 SSR 文档；列表 JS 对 同一 URL 发出同源 X-CMBuyer-View: drawer 请求，只取得 HTML fragment。加载失败时抽屉提供重试和 “在完整页打开”，不会把失败请求伪装成已打开详情。

T-204 只显示数据库中当前实际存在的任务、授权、attempt、submission 和内部截图，缺少事实就显示 明确空态；它不创建 attempt/event，不计算闸门，也不提供重置、调和、标记付款或任何设备动作。 截图以服务端记录的宽高预留布局并延迟加载，alt 只描述证据种类和采集时间，不转录截图中的地址或手机号。

四、采购工具界面结构

应用名：采购工具。顶部固定 tab：

1. 采购执行（默认）
2. 配置

采购执行 tab

• 顶部第一行：采购服务、ADB、拼多多版本、会话状态；其右侧是“开始轮询 / 停止轮询”。
• 左上“当前任务”：左侧文字约 2/3，右侧商品图片约 1/3；空闲显示占位。
• 左下“滚动日志”：占满剩余高度，显示阶段、固定 reason 和安全下一步。
• 右侧“采购记录”：时间倒序表格，MVP 只显示标题和状态。
• 双击或 Enter 记录：左侧原位切换到记录详情，不弹窗；上方文字/图片，下方执行结果。
• Esc 或“返回当前任务”：恢复当前任务视图；不暂停执行、不释放围栏。

单趟状态：待领取、已领取、打开商品、选择规格、闸门一、数量复核、闸门二、最终提交面板/闸门三、 申请围栏、已发出唯一提交、待付款或待调和。桌面端没有让用户手工点击“提交订单”的按钮。

配置 tab

• 采购服务 URL、设备 token（密码框，不回显完整值；首次必填，已有凭据时留空表示保留，非空表示替换）；
• ADB 路径、设备 serial、USB/WiFi 通道选择；
• 轮询间隔与连续失败停止阈值；
• 只做本地字段与路径格式检查，并提示服务身份、设备连接、拼多多安装和已取证版本将在首次真实领取/ 后续已批准真机流程中验证。配置页不调用 claim-next、renew、evidence 等业务 API，也不运行 ADB/PDD 作为“连接检查”；MVP 不提供清除已保存设备凭据的命令。

配置凭据进入系统安全存储；日志和界面不显示完整 token。

五、导航和焦点规则

• Web 主导航 MVP 只有“采购任务”；logo 文案为“采购服务”。
• 商品标题链接是外部导航；行详情是内部导航，两者事件相互隔离。
• Web 路由抽屉与完整页共享数据和 URL；关闭恢复触发行焦点。
• Desk tab 使用标准键盘关系；历史详情 Esc 返回当前任务，不关闭应用。
• 真机执行、围栏和提交不受页面/视图切换影响；关闭窗口时若有活跃任务，提示只影响 UI/轮询， 不把它解释为撤销服务端授权。

六、组件归属

组件	归属
会话 / CSRF / SSR 模板	admin/internal/transport/webui
任务 / 授权 / attempt / submission 用例	admin/internal/usecase
SQLite / 证据存储	admin/internal/storage
设备 API	admin/internal/transport/httpapi
ADB / PDD 页面能力	client/src/cmbuyer_client/device、pdd
任务来源与结果 sink	client/src/cmbuyer_client/core、remote
PySide6 UI	client/src/cmbuyer_client/app

七、原型

• Web：docs/design/web-task-create.html、web-task-workbench.html、web-task-detail.html。
• Desk：docs/design/desk-execution.html；配置结构见 desk-device-settings.html。
• 原型只使用假数据、无网络和生产副作用；显著流程变更先更新原型再实现。