cmroubao/docs/routes.md

# 路由与页面结构

T-202 的离线 P0 页面入口见[原型索引](design/index.html)。原型仅用于确认页面区块、
控件、文案和主要动作，不代表正式路由实现。

## 管理 Web

| 路由 | 页面 | 职责 | 用户故事 | 交互 |
| --- | --- | --- | --- | --- |
| `/login` | 管理登录 | 建立服务端管理会话 | US-007 | IX-001 |
| `/tasks` | 任务列表 | 查看状态、筛选并进入详情 | US-002 | IX-003 |
| `/tasks/new` | 新建任务 | 提交图片和采购约束 | US-001 | IX-002 |
| `/tasks/{id}` | 任务详情 | 查看输入/候选/证据、创建下单授权，并展示对账中/人工对账/待人工付款状态 | US-002、US-006、US-010 | IX-003、IX-008、IX-011 |
| `/freight` | ERP 货运列表 | 查看已导入货运单并进入全部商品明细 | US-011 | IX-012 |
| `/freight/import` | ERP 货运导入 | 创建精确单号、最多 7 天日期范围或“同步至现在”任务，并查看成功水位 | US-011 | IX-012 |
| `/freight/{id}` | ERP 货运详情 | 查看全部商品明细、来源变化、补图和采购任务生成状态 | US-011、US-012 | IX-012、IX-013 |

MVP 登录后默认进入 `/tasks`。未登录访问受保护页面时跳转 `/login` 并携带安全的
站内返回路径；只接受 `/tasks`、`/freight` 及其本站子路径，拒绝绝对 URL、`//`
和反斜杠。
不存在和无权限必须使用不同内部原因，但页面均不得泄露任务内容。

## Android 页面

Android 导航名称是逻辑目的地，具体 Compose/Fragment 形式待接入 Roubao 源码后确定。

| 目的地 | 页面 | 职责 | 用户故事 | 交互 |
| --- | --- | --- | --- | --- |
| `login` | 登录/设备绑定 | 建立人员与设备身份 | US-007 | IX-004 |
| `tasks` | 任务主页 | 就绪检查、获取或继续任务 | US-003 | IX-005 |
| `task/{id}/preview` | 任务预览 | 检查原始要求并开始 | US-003、US-004 | IX-005、IX-006 |
| `task/{id}/running` | 任务执行 | 显示步骤、返回拼多多、安全停止 | US-004、US-006 | IX-006、IX-008 |
| `task/{id}/confirm` | 候选确认 | 接受、拒绝、无匹配或转人工；T-208 增加逐候选结构化理由 | US-005、US-008 | IX-007、IX-009 |
| `task/{id}/result` | 任务结果 | 查看终态和同步状态 | US-002、US-006 | IX-007、IX-008 |
| `settings` | 设备设置 | 查看权限、后端、执行模式和本地 VLM 配置 | US-003、US-007、US-009 | IX-004、IX-005、IX-010 |

## App 后端路由

以下路由只接受有效 BUYER Bearer token，认证 principal 中的用户和设备是权威身份：

| 路由 | 职责 |
| --- | --- |
| `POST /api/v1/devices/heartbeat` | 上报版本、就绪位并核对服务端活跃任务 |
| `POST /api/v1/tasks/claim-next` | 用户点击后原子领取或重放领取结果 |
| `GET /api/v1/tasks/{id}/reference-image` | 用当前 claim 读取该任务匿名参考图 |
| `POST /api/v1/tasks/{id}/start` | `CLAIMED -> RUNNING` 并创建 execution |
| `POST /api/v1/tasks/{id}/heartbeat` | 更新 step、设备在线时间和运行租约 |
| `POST /api/v1/tasks/{id}/release` | 未开始时 `CLAIMED -> PENDING` |
| `POST /api/v1/tasks/{id}/cancel-ack` | 安全停止后确认 `CANCELED` 并结束 execution |
| `POST /api/v1/tasks/{id}/events` | 幂等补报本地执行事件 |
| `POST /api/v1/tasks/{id}/candidates` | 保存最多 5 个候选、模型判断和本地推荐 |
| `POST /api/v1/tasks/{id}/commands/next` | 拉取或重放 Admin 已创建的同一条下单命令 |
| `POST /api/v1/tasks/{id}/commands/{command_id}/ack` | App 加密落盘后幂等确认命令 |
| `POST /api/v1/tasks/{id}/order-dry-runs/start` | 加密保存执行意图后开始已授权商品重新定位 |
| `POST /api/v1/tasks/{id}/order-dry-runs/{command_id}/ready` | 回传确认订单页前的 SKU/数量/金额与证据 |
| `POST /api/v1/tasks/{id}/complete` | 提交人工结果，强制 `order_submitted=false` |
| `POST /api/v1/tasks/{id}/fail` | 提交结构化失败和受控证据 |

claim/start/release/cancel-ack 使用相应幂等规则；参考图、start、task heartbeat、
release 和 cancel-ack 都必须匹配当前 `X-Claim-Token` 与 `claim_generation`。
运行授权过期后只有 task heartbeat 状态同步和已请求取消的 cancel-ack 允许原设备
继续调用；它们不赋予 App 恢复外部动作的权限。
T-207 的 events/candidates/complete/fail 接受原设备对授权内已产生结果的离线补报，
并由服务端记录是否在执行授权过期后收到；后端不提供 VLM 代理路由。

## 导航规则

- App 有活跃任务时启动后优先恢复该任务，不允许直接领取下一条。
- `CLAIMED` 进入预览；`RUNNING` 进入执行；`WAITING_CONFIRMATION` 进入等待 Admin；
  终态进入结果。
- 从执行页切换拼多多后，使用前台服务通知返回执行页。
- 候选确认页返回不能恢复自动化。
- 登录过期时先保存非敏感本地状态，再跳转登录；重新登录后查询服务端状态。
- 设备设置不是首屏，任务主页是采购人员的工作入口。
- 后台任务不能携带或修改 provider、模型、Base URL 和 API Key；App 设置由设备
  操作者管理，Key 使用 Keystore-backed 加密存储。
- 管理后端离线时执行页显示授权截止时间和待同步数量；到期后只能安全停止和等待
  联网，不能领取或继续页面动作。

## 页面组件边界

| 组件 | 归属 | 说明 |
| --- | --- | --- |
| `TaskForm` | 管理 Web | 只管理表单状态和可访问反馈，创建逻辑在 usecase |
| `TaskStatusBadge` | 管理 Web | 统一状态中文和语义，不内置状态迁移 |
| `ExecutionTimeline` | 管理 Web/App | 展示只追加事件 |
| `ReadinessPanel` | Android | 汇总权限、安装、网络和活跃任务 |
| `TaskRequirementSummary` | Android/Web | 展示原始输入和 AI 派生信息，视觉上明确区分 |
| `CandidateReview` | Android/Web | 展示候选与硬约束校验，不执行自动化动作 |
| `ExecutionController` | Android | UI 命令入口，委托 workflow，不直接调用 Accessibility |
| `PendingPaymentSummary` | 管理 Web/App | 只读展示对账订单与人工付款提醒，不提供付款或重提动作 |
| `FreightSyncForm` | 管理 Web | 创建精确单号/日期同步记录、查看成功水位，不持有 ERP 凭证 |
| `FreightItemReview` | 管理 Web | 显示规范化来源字段、缺失项和采购任务生成操作 |

具体状态反馈以[交互清单](08-interaction-checklist.md)为准，组件命名可在接入真实框架后
调整并同步本文。