cmroubao/docs/routes.md

路由与页面结构

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

管理 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

MVP 登录后默认进入 /tasks。未登录访问受保护页面时跳转 /login 并携带安全的 站内返回路径；只接受 /tasks 及其本站子路径，拒绝绝对 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	只读展示对账订单与人工付款提醒，不提供付款或重提动作

具体状态反馈以交互清单为准，组件命名可在接入真实框架后 调整并同步本文。