cmbuyer/docs/00-ai-start-here.md

AI 开发入口

给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见 05-coding-rules.md。

一句话定位

cmbuyer 是一个自动化采购系统：采购服务（网页端，admin/）负责建单与人工决策， 采购工具（桌面端，client/）驱动 Android 手机在拼多多完成找货和下单， 付款始终由人完成。

第一版 MVP 只做任务自带商品链接的情形，分两趟跑：

1. 第一趟试选：桌面端定时领取 → 开商品 → 精确勾选颜色分类和尺码 → 读单价 → 截图 → 退出释放手机 → 回传。
2. 人工确认：管理员在网页端看「机器选对了吗」，确认后签发授权并锁定单价。
3. 第二趟下单：重新开商品 → 重新选同一规格 → 三道价格闸门 → 提交订单一次 → 任务转「待付款」，人在拼多多核对后付款。

上下文读取

首次接入、agent-context.json 缺失或校验失败时，按顺序建立上下文：

1. 01-vision.md：为什么做、为谁做、什么不做。
2. 02-requirements.md：MVP 要什么、怎么算达成。
3. 03-tech-stack.md：两端各自的技术选型与验证矩阵。
4. 04-architecture.md：双端职责、两趟执行、三道价格闸门、安全边界、数据模型。
5. 05-coding-rules.md：写代码前必须遵守的规则。
6. 06-tasks.md：阶段路线图与建议拆分。
7. tasks/README.md：任务文件约定。
8. current-state.md：当前代码现实、可运行命令、下一步任务。

涉及页面或桌面界面时，还必须读 07-user-stories.md、 08-interaction-checklist.md 和 routes.md。

日常会话按 agent-context.json 的最小路径读取，不机械重读全部文档。

固定开工流程

1. pwd：确认在 cmbuyer 仓库根目录。
2. 读 current-state.md 和 docs/tasks/ 中的活跃任务，恢复已验证状态、 下一步和当前 blocker。
3. git log --oneline -5：看清最近发生了什么。
4. 运行 ./init.ps1（或 ./init.sh）：安装、验证、打印启动命令。
5. 跑一条基础 smoke，确认基线没坏。
6. 基线已坏就先修基线，不要在坏的起点上叠新功能。
7. 基线绿了，再从 docs/tasks/ 领取唯一任务。

本项目的四条特有纪律

这四条比通用流程更重要，违反会直接造成资金损失或重蹈前序项目覆辙。

1. 涉及真机页面判据的任务，先取证再写代码

拼多多 App 会随版本改变页面结构。前序项目已观察到详情页没有独立规格入口、价格文本被 拆成多个节点等变化。

不得从前序项目的结论、旧文档或推理直接写判据。 必须先在真机上 dump 页面取证， 把证据（截图路径、XML 路径、拼多多 App 版本）写进任务文件，再写代码。

2. 安全边界只能收紧，不能放宽

04-architecture.md 第四节的硬约束（不付款、提交订单四条件与服务端围栏、 规格精确匹配、提交控件唯一、数量必须复核、三道价格闸门、第一趟不下单、外部支付停止、 安全校验停止、敏感信息不提取、授权一次性）不得在任务中顺手放宽。

确需变更时先改架构文档并说明理由，再动代码。任何「为了让流程跑通先放宽一下」的改动 一律拒绝。

3. 价格只在两个地方读

规格面板（闸门一 / 二）和订单确认页（闸门三）。

不从商品详情页正文、搜索结果卡片或任何其他位置读价格。 那些位置的价格文本被拆成 多个节点、带「券后」前缀、实付价与原价混在一起，前序项目在这里耗掉大量时间且无可靠 结论。读不到就转人工，不用别处的数字凑合。

理由与三道闸门的定义见 04-architecture.md 第三节。

4. 第一趟绝不下单

试选阶段只勾选规格和读价，绝不点击「现在买」或任何进入下单流程的入口。 第一趟的代码路径不得引用 go_to_order_confirm() 与 submit_order()，必须有测试 证明它们不可达。

当前阶段

Phase 0 · 地基。 采购服务骨架已初始化，采购工具骨架仍在进行；尚无采购业务代码。

执行按任务依赖驱动，不按 Phase 整段串行等待。当前优先路径：

1. 继续完成 T-002 采购工具骨架；采购服务方向可并行推进 T-004 数据模型。
2. T-002 完成后立即推进 T-101 → T-102 → T-103 真机取证，并可并行补 T-003 统一入口。
3. T-103 结论确认后，才开始依赖真机可读字段的 Phase 2 生产页面；采购服务核心与 T-104 → T-107 后续真机安全判据按依赖并行推进。
4. Phase 3：双端打通与第一趟试选端到端。
5. Phase 4：第二趟下单与收尾。
6. V2 及以后：图搜、Excel、ERP、订单自动核对、AI 辅助。

M2 是本项目的生死线：真机能按链接打开商品、精确勾选颜色分类和尺码、 读到该 SKU 的单价（T-103）。前序项目正是卡在选规格和读价。 M2 不通过之前不要写 Phase 2 的生产页面；Phase 0 原型只确认流程与信息架构，实际可读 字段仍以真机证据为准。

领取任务规则

• 每个 agent 只领取一个 frontmatter status: TODO 且依赖均 DONE 的任务文件，取编号 最靠前的。
• docs/tasks/ 暂无可领任务时，先按 06-tasks.md 把下一个建议任务落成 任务文件，再领取。
• 开始前在独立分支 / worktree 把 frontmatter status 改为 DOING。
• 本轮只完成这一个任务；验收通过后改为 DONE。
• 执行记录写进该任务文件的 ## 执行记录。
• 项目现实变化（启动 / 验证路径、目录结构、blocker）时覆盖更新 current-state.md。
• 结束前过一遍 clean-state-checklist.md。
• 做完即停，汇报验证结果，等待下一步指令。

需要真机验收的任务，agent 不得自行标 DONE。 保持 DOING 并写明等待人工验收的 具体事项。

只做：

• 手工填链接建单、任务查询、勾选待开始任务后批量开始第一趟试选
• 桌面端定时轮询领取（试选与下单两类）
• 第一趟试选：精确勾选规格、读单价、截图、退出释放手机
• 人工确认「机器选对了吗」并签发授权（锁定单价）
• 授权超时与放弃，任务不会被永久锁死
• 第二趟下单：三道闸门全过后提交订单一次
• 真实点击前服务端原子建立提交围栏；围栏失败不点击，围栏后只调和同一提交记录
• 待付款展示订单截图，人核对付款后手工标记完成
• 失败分类与转人工

不做（推到 V2 或永不做）：

• 自动付款（任何版本都不做）
• 图片搜索（B 路径）与多候选对照台
• Excel 导入、ERP 建单（均被待确认字段契约阻塞）
• 订单自动回读核对
• 已开始任务的批量排序、暂停 / 继续和运行中人工接管
• 绕过验证码、风控、人脸、短信校验
• 拼多多以外的平台
• 多设备并行、审批链、退款、财务对账
• AI 辅助

事实来源

项目事实只信：

• 本目录下的文档（架构、API、需求、交互）
• 数据库迁移文件与 admin/internal/domain/ 中的实体定义
• 真机取证产物（截图、页面 XML）及其记录的 App 版本
• 当前仓库代码

不要当事实来源：

• 前序项目 cmroubao / cmpdd 的代码与文档——它们是设计依据，结论必须在本项目 重新验证。
• 历史备份、旧导出、临时实验目录。
• 未被任务或需求引用的草稿。

常见任务该看哪里

做什么	读什么
采购服务页面	02-requirements.md 验收 → 07-user-stories.md → 08-interaction-checklist.md → routes.md → 04-architecture.md
采购工具界面	同上，routes.md 看第三节桌面端结构
设备侧 API	api.md → 04-architecture.md 数据模型与鉴权边界
真机自动化	04-architecture.md 第三节两趟执行与三道闸门 → 第四节边界 → api.md 第三节模块合约 → 先真机取证
数据模型	04-architecture.md 第五节；schema 变化必须同步 api.md 和 current-state.md
部署 / 运行	03-tech-stack.md → current-state.md

验证命令

采购服务命令已由 T-001 实际验证；采购工具命令在 T-002 完成前仍是占位路径。

# 采购服务 admin/（改了 Go 代码后）
cd admin
go test ./...
go vet ./...
go build ./...

# 采购工具 client/（T-002 完成后启用）
cd client
python -m unittest discover -s tests -t .
python -m compileall -q src tests

# 跨端契约改动：两端全跑

验证层级何时触发见 03-tech-stack.md 第六节验证矩阵。 如果命令当前不可运行，必须在回复里如实说明原因。