3

routes

ila edited this page 2026-08-07 16:47:49 +08:00

Table of Contents

• 路由与页面结构
• 管理 Web
• Android 页面
• App 后端路由
• 导航规则
• 页面组件边界

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

同步来源：docs/routes.md · commit afc651f75a3a

路由与页面结构

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
/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	显示规范化来源字段、缺失项和采购任务生成操作

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