# 任务路线图（Roadmap）

> 本文是**只读路线图**：维护阶段划分、里程碑、待办池和建议拆分清单。
> 真实任务以「一任务一文件」存放在 [`tasks/`](tasks/README.md)（`docs/tasks/T-<编号>.md`），
> 状态权威在任务文件 frontmatter。**本文不跟踪单任务状态。**

## 使用规则

1. **开工先落文件**：从下方清单把下一个任务落成 `docs/tasks/T-<编号>.md`（沿用建议编号），
   把验收要点展开成可执行、可观察的步骤，再开始实现。
2. **每个 agent 一次只做一个任务**：领取、状态流转、执行记录、完成定义遵循
   [`tasks/README.md`](tasks/README.md) 和[编码规则](05-coding-rules.md)。
3. **不跳步**：依赖未完成的任务不能开工。T-103 完成前可并行 T-201 管理会话与只创建 `DRAFT`
   的 T-202 基础建单 / 列表；**依赖真机可读字段或会启动试选的 Phase 2 功能仍不得抢跑**，
   T-103 若改变可读字段则先修订原型与 IX。
4. **本文只在规划变化时修改**：单个任务开工或完成**不**修改本文。
5. **动手前**先读 `00-ai-start-here.md`、`05-coding-rules.md` 和 `current-state.md`。

## 并行执行与关键路径

执行顺序以任务表中的 `依赖` 为准，Phase 是里程碑分组，**不是要求整段串行的栅栏**。
在 `write_paths` 不重叠且依赖已完成的前提下，按以下波次推进：

| 波次 | 采购服务方向 | 采购工具 / 真机方向 | 集成方向 |
| --- | --- | --- | --- |
| 1 | T-001 初始化 `admin/` | T-002 初始化 `client/` | - |
| 2 | T-001 后立即做 T-004 | T-002 后立即做 T-101 → T-102 → **T-103** | T-001、T-002 都完成后做 T-003 |
| 3 | 与 T-103 并行做 T-201 → T-202；T-103 后做 T-203 → T-207 | T-103 后推进 T-104 → T-107 | T-208 等待 T-207 与 T-107 均完成 |
| 4 | T-301 → T-302 | T-302 后交接 T-303 → T-304 → T-306 | T-306 与 T-104 完成后做 T-305 |
| 5 | - | T-305、T-208、T-306 后做 T-401 | T-401 后并行 T-402 / T-403，再做 T-404 → T-405 |

**T-103 是当前最高优先级和 MVP 生死线。** T-002 一完成就启动 T-101，不等待 T-003、
T-004 或整个 Phase 0 收尾。并行只优化等待关系，不改变下列门禁：

- T-103 的真机结论出来前，T-201 / T-202 只能落管理会话、`DRAFT` 建单与基础列表；不启动试选，
  不展示机器规格、规格面板单价或证据。T-203～T-207 继续等待 T-103。
- `needs_device: true` 的任务仍只能由人完成验收。
- 不复用前序项目页面判据，不放宽三道价格闸门，不让第一趟引用任何下单函数。
- 第三个 agent 优先做写路径独立的集成任务或只读复核，不与两端任务争写共享文档。

## 建议拆分清单

### Phase 0 · 地基

| ID | 任务 | 依赖 | 验收要点 |
| --- | --- | --- | --- |
| T-001 | 初始化采购服务 `admin/` Go 骨架 | - | 在 `admin/` 创建 Go 模块；`go test ./...`、`go vet ./...` 可运行；健康检查端点可访问；用真实命令替换 `03-tech-stack.md`、`00-ai-start-here.md`、`current-state.md` 中的占位命令 |
| T-002 | 初始化采购工具 `client/` Python 骨架 | - | 在 `client/` 创建虚拟环境、`requirements.txt` 与应用骨架；`unittest`、`python -m compileall` 可运行；日志与产物目录策略明确且不记录敏感信息 |
| T-003 | 建立 `init.ps1` 统一入口 | T-001, T-002 | 一条命令完成两端安装与基础验证并打印启动命令；未配置时主动失败而不是静默跳过 |
| T-004 | 建立核心数据模型与状态机 | T-001 | `tasks`、`order_authorizations`、`order_submissions` 表与 `04-architecture.md` 一致；状态流转有单元测试；金额用十进制字符串 |
| T-005 | 网页端 MVP 交互原型 | - | “采购服务”的 `docs/design/web-*.html` 单文件假数据原型覆盖登录、表格工作台、创建弹窗、批量开始试选、路由化详情抽屉与完整详情；键盘、窄屏、空态 / 错误 / 加载、围栏后调和状态可演示；经人工确认前保持 `DOING` |
| T-006 | 桌面端 MVP 交互原型 | - | `docs/design/desk-*.html` 单文件假数据原型覆盖“采购工具”的采购执行 / 配置固定页签、顶部轮询控制、当前任务图片、滚动日志、时间倒序执行记录，以及左侧当前任务 / 记录详情双视图；明确 dry-run / 真实下单、App 版本失配、围栏后不可重试；经人工确认前保持 `DOING` |
| T-007 | 统一产品名称与源码目录契约 | - | 项目名固定为 `cmbuyer`；采购服务使用 `admin/`，采购工具使用 `client/`；架构、任务和启动脚本不再把 `web/` / `desk/` 当生产源码目录 |

### Phase 1 · 真机取证（最高风险，必须先做）

> 本阶段每个任务都需要真机，**只能由人完成验收**。结论写入任务文件并同步
> `04-architecture.md`；**每条页面判据必须记录拼多多 App 版本**。

| ID | 任务 | 依赖 | 验收要点 |
| --- | --- | --- | --- |
| T-101 | 验证 ADB 与 uiautomator2 连接（USB + WiFi） | T-002 | 两种连接都能列设备、截图、`dump_hierarchy(compressed=False)`；同一手机双通道在线时报明确错误；超时参数可配置 |
| T-102 | 验证按链接打开商品详情页 | T-101 | 输入 `goods_id` 链接后真机进入对应详情页；打不开时有可区分的失败原因；保存截图与页面 XML |
| T-103 | 验证规格面板打开、按维度精确选择、**读取 SKU 单价** | T-102 | 能打开规格面板；按 `颜色分类=X`、`尺码=Y` 精确选中并读回确认；**防前缀碰撞**；找不到精确值时停止且不点相近项；**取证单价在哪个节点、是否带券后前缀**——闸门一依赖此结论 |
| T-104 | 验证试选后安全退出并释放手机 | T-103 | 读完价截完图后退出商品页；**全程不点击「现在买」或任何下单入口**，有测试证明；退出后可立即开始下一条任务 |
| T-105 | 验证数量设置与复核 | T-103 | 设置后读回精确等于要求值；不等时停止，不进入购买入口 |
| T-106 | dry-run：验证进入订单确认页并读「实付款」 | T-105 | 进入确认页读出规格、数量、实付金额；验证提交控件唯一但**绝不点击**；不提取地址原文与手机号；保存截图与 XML 证据到任务产物 |
| T-107 | 固化提交控件判据与 dry-run 安全边界 | T-106 | 只把本项目真机证据转成可测试判据；第一趟和 dry-run 路径不可达 `submit_order`；App 版本不匹配时 fail closed；**不创建真实订单** |

> **T-106 与 T-107 只做只读演练，不得点击提交订单。** 本路线图中首次允许创建真实订单
> 的任务是 T-401；执行前必须取得明确授权，并在任务文件记录订单是否产生、如何处置。

### Phase 2 · 采购服务核心

| ID | 任务 | 依赖 | 验收要点 |
| --- | --- | --- | --- |
| T-201 | 管理员登录与会话 | T-004, T-005 | 登录建立会话；CSRF 生效；未登录跳转并只接受站内返回路径 |
| T-202 | 手工建单（F-001） | T-201 | 列表内创建弹窗与 `/tasks/new` 复用表单；任务名称、链接、颜色分类、尺码、数量、价格上限校验；成功创建 `DRAFT` 并倒序显示第一行 |
| T-203 | 任务表格、查询与批量开始试选（F-004、F-018） | T-202 | 传统表格无操作列；标题关键词筛选；只选 `DRAFT`；批量 `DRAFT → PENDING` 全有或全无；空状态可清除筛选 |
| T-204 | 路由化任务详情（F-011） | T-203 | 从列表进入显示保留现场的右侧抽屉，直达显示完整页；按状态呈现唯一主区块与主动作；执行证据可查看 |
| T-205 | 试选结果接收与确认页（F-007） | T-204, T-103 | 接收 `spec_trials` 与规格面板截图；确认页展示需求 vs 所选、单价、合计、截图；**轻量版，非对照台** |
| T-206 | 人工确认与授权签发（F-008） | T-205 | 确认即签发一次性授权并**锁定试选单价**；`expected_task_version` 冲突返回 409；金额上限服务端校验；支持「退回，不买」 |
| T-207 | 授权超时与围栏前放弃（F-010） | T-206 | 围栏前超时 / 放弃后任务转 `PENDING_RETRIAL`，必须重新试选；围栏后禁止超时释放或放弃，改走人工核查；每个状态都有安全下一步 |
| T-208 | 提交围栏与结果调和 API（F-017） | T-207, T-107 | dry-run start / ready、submission start / reconcile / manual-review 幂等；围栏事务原子消费执行权；响应不明不允许点击；不确定结果保留额度且不可重试 |

### Phase 3 · 双端打通（第一趟）

| ID | 任务 | 依赖 | 验收要点 |
| --- | --- | --- | --- |
| T-301 | 设备凭据与身份隔离（F-013） | T-201 | 设备 Bearer 不能建单或授权；管理会话不能调设备接口；凭据可撤销 |
| T-302 | 原子领取与租约（F-005） | T-301, T-004 | 并发领取只有一个成功；重复领取重放同一结果；**同时支持领取待试选与已授权两类**；`claim_token` 与 `claim_generation` 校验生效 |
| T-303 | 采购工具 `HttpTaskSource` / `HttpResultSink` | T-302, T-002 | 执行器只依赖抽象；测试假数据与断连 JSONL 暂存不扩大 Excel MVP 范围；补传使用幂等键 |
| T-304 | 定时轮询与会话边界 | T-303, T-006 | 只在执行员启动的会话内轮询，关窗口即停；连续失败达阈值自动停止并提示原因；间隔可配置 |
| T-306 | 证据上传与分层 | T-304, T-103 | 规格面板截图与订单截图上传服务端并脱敏；节点树与失败现场留本地；上传前校验不含地址与手机号 |
| T-305 | **第一趟试选端到端** | T-306, T-104 | 从领取跑到试选回传：开商品、勾选规格、读单价、截图、退出释放手机；任务转「等你确认」；全程有事件与证据 |

### Phase 4 · 第二趟与收尾

| ID | 任务 | 依赖 | 验收要点 |
| --- | --- | --- | --- |
| T-401 | **第二趟下单端到端** | T-305, T-208, T-306 | 拿到授权后重新开商品、重新选同一规格、过三道闸门、原子建立提交围栏后提交一次；不确定结果进入调和且不可重试；明确创建才转「待付款」 |
| T-402 | 待付款收口与手工完成 | T-401 | 详情页展示订单截图与授权信息供核对；人付款后手工标记完成；**待付款不等于成功** |
| T-403 | 失败分类与证据归档（F-011） | T-401 | 覆盖需求列出的全部失败原因；终态一次原子回写，不落中间态 |
| T-404 | 完整验收 MVP | T-402, T-403 | `02-requirements.md` 的 P0 验收全部通过；真机记录写入任务文件与 `current-state.md` |
| T-405 | 采购工具打包与运行文档 | T-404 | 运营电脑可按文档运行；记录产物 SHA-256 |

### V2 及以后（不在 MVP，编号预留）

| ID | 任务 | 说明 |
| --- | --- | --- |
| T-501 | 图片搜索产出 goods_id（F-014） | 推图到相册、搜图、从结果页取 goods_id；**不读价格**；最多 5 个 |
| T-502 | 候选对照台（F-015） | 多候选并排对照，跨列逐行对齐，窄屏降级 |
| T-503 | Excel 批量建单（F-002） | 被表头契约待确认阻塞 |
| T-504 | ERP 货运同步与建单（F-003） | 被字段映射待确认阻塞 |
| T-505 | 批量顺序编排与人工接管（F-012） | 勾选多条、暂停继续、运行中冻结 |
| T-506 | 订单自动核对回读（F-016） | 五项唯一匹配才自动回写，否则待人工 |
| T-507 | 本地执行轨迹留档（F-103） | NDJSON，含规则与模型判断的分歧字段 |
| T-508 | AI 辅助（F-101、F-102） | 模型结论**不能放宽任何安全边界** |

## 里程碑

- **M0**：网页端与桌面端 P0 原型经人工确认，流程、状态与主动作可枚举。（T-005、T-006）
- **M1**：两端骨架可运行，数据模型与状态机落地。（Phase 0）
- **M2**：真机能按链接打开商品、精确勾选颜色分类和尺码、**读到该 SKU 单价**。（T-103）
- **M3**：真机能设对数量、以 dry-run 进入订单确认页读到「实付款」并验证唯一提交控件，
  但不点击。（T-107）
- **M4**：管理员能建单、看到试选结果、确认并签发授权。（Phase 2）
- **M5**：第一趟试选端到端跑通，任务能停在「等你确认」。（T-305）
- **M6**：MVP 闭环——第二趟下单成功，任务停在「待付款」。（T-401）

**M2 是本项目的生死线。** 前序项目正是卡在选规格和读价；M2 不通过之前只允许 T-201 与
不启动试选的 T-202，不写依赖真机字段或会推进任务执行的 Phase 2 功能。原型只用于确认信息架构，
T-103 若改变可读字段必须先回修原型与 IX。

## 待办池（Backlog）

- V2 全部条目见上方「V2 及以后」表（T-501 ~ T-508）
- 多设备并行（F-104）
- 完整 RBAC（F-105）
- 多平台比价（F-106）
- 证据保留期与自动清理策略
- 采购服务从 SQLite 迁移到 Postgres 的评估
- 设备凭据轮换机制
- 定时轮询间隔的风控友好节奏（需真机观察后确定）