105 lines
5.4 KiB
Markdown
105 lines
5.4 KiB
Markdown
---
|
||
id: T-206
|
||
title: App 接入手动领取和执行进度
|
||
phase: 2
|
||
deps:
|
||
- T-202
|
||
- T-205
|
||
status: TODO
|
||
created: 2026-07-27
|
||
context_ref: 45d4d11
|
||
work_branch: null
|
||
write_paths:
|
||
- README.md
|
||
- android-buyer/**
|
||
- backend-api/**
|
||
- docs/00-ai-start-here.md
|
||
- docs/02-requirements.md
|
||
- docs/04-architecture.md
|
||
- docs/05-coding-rules.md
|
||
- docs/07-user-stories.md
|
||
- docs/08-interaction-checklist.md
|
||
- docs/api.md
|
||
- docs/current-state.md
|
||
- docs/routes.md
|
||
- docs/tasks/T-206.md
|
||
- progress.md
|
||
---
|
||
|
||
## 问题 / 背景
|
||
|
||
T-205 已实现 BUYER + 设备联合鉴权、readiness heartbeat、原子 claim、任务参考图、
|
||
start、租约 heartbeat、release 和取消确认，但当前 Android 仍只消费本地 fixture。
|
||
管理员创建的 `PENDING` 任务无法在手机领取，真实端到端流程因此被阻塞。
|
||
|
||
现有 Roubao 基线包含端上模型服务商、Base URL 和 API Key 设置。正式采购工作流必须
|
||
把模型调用收口到肉包后端，避免采购手机持有供应商密钥或由执行员改变模型策略。
|
||
|
||
## 关联需求与交互
|
||
|
||
- 功能：F-003、F-007、F-009。
|
||
- 用户故事：US-003、US-006、US-007、US-009。
|
||
- 交互：IX-004、IX-005、IX-006、IX-008、IX-010。
|
||
- 架构/API：`HttpTaskSource`、设备联合身份、claim 租约状态机、前台服务和后端托管
|
||
VLM 边界。
|
||
|
||
## 已定合约
|
||
|
||
1. 采购 App 只配置肉包后端 HTTPS 地址，不直接配置或调用 VLM 服务商。模型名称、
|
||
Base URL 和 API Key 不进入生产采购页面、任务缓存、日志或网络响应。
|
||
2. Debug 技术探针可保留本机直连 OpenAI 兼容 mock，但必须位于 Debug source set，
|
||
不得进入 Release APK，也不得用于后端任务。
|
||
3. BUYER 登录必须同时提交预授权 device ID/secret；access token、device secret、
|
||
claim token 和幂等 key 使用 Android Keystore 支撑的安全存储。敏感值不进入
|
||
SavedState、普通 SharedPreferences、崩溃报告或日志。
|
||
4. App 每次领取前先发设备 heartbeat。无障碍未连接、拼多多未安装、网络不可用、
|
||
服务端认为设备不就绪或已有活跃任务时不生成新的 claim 请求。
|
||
5. claim token 和幂等 key 必须在请求前持久化；结果不确定时原样重放，不能生成新
|
||
token。领取成功后下载 task-scoped 参考图并校验媒体类型、大小和解码结果。
|
||
6. 用户在预览页确认后调用 start 并启动前台服务；运行中每 30 秒 heartbeat。服务端
|
||
version、generation、execution 和租约是权威状态。
|
||
7. T-206 先验证登录、领取、预览、start、前台步骤、续租、release、取消安全停止和
|
||
进程恢复。真实后端 VLM、候选/截图/事件/结果回传属于 T-207。
|
||
8. T-206 的执行进度使用 fake/受控步骤到达明确的“等待 T-207 AI 接入”结果，不把
|
||
未上传的本地结果伪装成服务端完成，也不触发拼多多不可逆操作。
|
||
|
||
## 方案
|
||
|
||
1. 在 Android 增加严格的后端配置、认证 client、token 安全存储和稳定错误映射；
|
||
Release 只接受 HTTPS，Debug 可显式信任开发证书或使用受控本机测试路径。
|
||
2. 实现 `HttpTaskSource`，把 claim 响应和参考图规范化为现有 `ProbeTask`/领域输入，
|
||
workflow 不判断任务来自 fixture 还是 HTTP。
|
||
3. 按已确认原型接入登录、任务主页、任务预览、运行和结果状态；重复点击、空队列、
|
||
登录过期、租约过期和服务端冲突都有稳定反馈。
|
||
4. 使用前台服务持有当前 execution、定时 heartbeat 并轮询取消标志；取消只在
|
||
workflow 安全检查点停止，再调用 `cancel-ack`。
|
||
5. App 重启后先用 heartbeat/任务详情核对服务端活跃任务；不能证明可恢复时停止
|
||
自动化并显示人工处理，不自行领取第二条任务。
|
||
6. 后端如缺少 App 当前任务查询所需字段，只做兼容性最小补充，不改变 T-205 的
|
||
token、幂等、租约和状态机语义。
|
||
|
||
## 验收要点
|
||
|
||
- [ ] 预授权 BUYER 在真机登录成功，错误账号、错误设备、禁用和过期状态均不能进入
|
||
任务页；敏感值不出现在日志和普通存储。
|
||
- [ ] 真机 heartbeat 后点击“获取任务”能领取管理 Web 创建的一条 `PENDING` 任务，
|
||
显示标题、SKU、数量、描述和参考图；无任务显示空状态。
|
||
- [ ] 重复点击和模拟响应丢失不会重复领取；App 重启后能继续同一 `CLAIMED` 任务。
|
||
- [ ] 预览可开始或释放；开始后前台服务显示步骤并按约 30 秒续租，不领取第二条任务。
|
||
- [ ] 管理 Web 请求安全停止后，App 在安全检查点停止并确认，服务端最终为
|
||
`CANCELED`；过期租约不会被 App 擅自续作。
|
||
- [ ] 生产采购页面没有 VLM 服务商、Base URL 或 API Key 输入；后端任务不会读取
|
||
Roubao 旧的端上 provider 配置；Release APK 不含 Debug mock 配置。
|
||
- [ ] Android 单元/集成测试、后端回归测试、根 `init.ps1` 和 OnePlus PKG110
|
||
Android 16 真机端到端 smoke 通过。
|
||
|
||
## 边界
|
||
|
||
- 不实现真实 VLM 代理、候选/截图/事件、complete/fail 和人工理由回传；属于 T-207。
|
||
- 不实现后台推送、自动领取、自动下单、支付、多任务并行或跨设备调度。
|
||
- 不允许生产 App 绕过后端直连任意模型地址，不提交真实账号、设备 secret 或订单。
|
||
|
||
## 执行记录
|
||
|
||
- 尚未开始。
|