209 lines
11 KiB
Markdown
209 lines
11 KiB
Markdown
# AI 开发入口
|
||
|
||
> 给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见
|
||
> [`05-coding-rules.md`](05-coding-rules.md)。
|
||
|
||
## 一句话定位
|
||
|
||
cmbuyer 是一个自动化采购系统：**采购服务**（网页端，`admin/`）负责建单与人工决策，
|
||
**采购工具**（桌面端，`client/`）驱动 Android 手机在拼多多完成找货和下单，
|
||
**付款始终由人完成**。
|
||
|
||
第一版 MVP 只做**任务自带商品链接**的情形，**分两趟跑**：
|
||
|
||
1. **第一趟试选**：桌面端定时领取 → 开商品 → 精确勾选颜色分类和尺码 → 读单价 →
|
||
截图 → **退出释放手机** → 回传。
|
||
2. **人工确认**：管理员在网页端看「机器选对了吗」，确认后签发授权并**锁定单价**。
|
||
3. **第二趟下单**：重新开商品 → 重新选同一规格 → **三道价格闸门** → 提交订单一次 →
|
||
任务转「待付款」，人在拼多多核对后付款。
|
||
|
||
## 上下文读取
|
||
|
||
首次接入、[`agent-context.json`](agent-context.json) 缺失或校验失败时，按顺序建立上下文：
|
||
|
||
1. [`01-vision.md`](01-vision.md)：为什么做、为谁做、什么不做。
|
||
2. [`02-requirements.md`](02-requirements.md)：MVP 要什么、怎么算达成。
|
||
3. [`03-tech-stack.md`](03-tech-stack.md)：两端各自的技术选型与验证矩阵。
|
||
4. [`04-architecture.md`](04-architecture.md)：双端职责、**两趟执行**、**三道价格闸门**、安全边界、数据模型。
|
||
5. [`05-coding-rules.md`](05-coding-rules.md)：写代码前必须遵守的规则。
|
||
6. [`06-tasks.md`](06-tasks.md)：阶段路线图与建议拆分。
|
||
7. [`tasks/README.md`](tasks/README.md)：任务文件约定。
|
||
8. [`current-state.md`](current-state.md)：当前代码现实、可运行命令、下一步任务。
|
||
|
||
涉及页面或桌面界面时，还必须读 [`07-user-stories.md`](07-user-stories.md)、
|
||
[`08-interaction-checklist.md`](08-interaction-checklist.md) 和 [`routes.md`](routes.md)。
|
||
|
||
日常会话按 [`agent-context.json`](agent-context.json) 的最小路径读取，不机械重读全部文档。
|
||
|
||
## 固定开工流程
|
||
|
||
1. `pwd`：确认在 `cmbuyer` 仓库根目录。
|
||
2. 读 [`current-state.md`](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`](04-architecture.md) 第四节的硬约束（不付款、提交订单四条件与服务端围栏、
|
||
规格精确匹配、提交控件唯一、数量必须复核、三道价格闸门、第一趟不下单、外部支付停止、
|
||
安全校验停止、敏感信息不提取、授权一次性）**不得在任务中顺手放宽**。
|
||
|
||
确需变更时先改架构文档并说明理由，再动代码。任何「为了让流程跑通先放宽一下」的改动
|
||
一律拒绝。
|
||
|
||
### 3. 价格只在两个地方读
|
||
|
||
**规格面板**（闸门一 / 二）和**订单确认页**（闸门三）。
|
||
|
||
**不从商品详情页正文、搜索结果卡片或任何其他位置读价格。** 那些位置的价格文本被拆成
|
||
多个节点、带「券后」前缀、实付价与原价混在一起，前序项目在这里耗掉大量时间且无可靠
|
||
结论。读不到就转人工，**不用别处的数字凑合**。
|
||
|
||
理由与三道闸门的定义见 [`04-architecture.md`](04-architecture.md) 第三节。
|
||
|
||
### 4. 第一趟绝不下单
|
||
|
||
试选阶段只勾选规格和读价，**绝不点击「现在买」或任何进入下单流程的入口**。
|
||
第一趟的代码路径不得引用 `go_to_order_confirm()` 与 `submit_order()`，必须有测试
|
||
证明它们不可达。
|
||
|
||
## 当前阶段
|
||
|
||
**Phase 1 · 真机可行性，并行启动采购服务基础能力。** 两端骨架与核心数据模型已完成，T-103
|
||
仍是当前真机关键路径；与真机可读字段无关的采购服务能力不再空等。
|
||
|
||
执行按任务依赖驱动，**不按 Phase 整段串行等待**。当前优先路径：
|
||
|
||
1. T-001～T-004 与 T-101～T-102 已完成，继续推进 **T-103 真机取证**。
|
||
2. T-103 进行时并行推进 T-201 管理会话 → T-202 `DRAFT` 建单与基础列表；两者不得启动试选，
|
||
也不得引入机器结果、规格面板单价或证据字段。
|
||
3. T-103 结论确认后，再推进 T-203 批量开始试选、T-204 试选证据详情、T-205～T-207，
|
||
并按依赖推进 T-104 → T-107 后续真机安全判据。
|
||
4. Phase 3：双端打通与**第一趟试选**端到端。
|
||
5. Phase 4：**第二趟下单**与收尾。
|
||
6. V2 及以后：图搜、Excel、ERP、订单自动核对、AI 辅助。
|
||
|
||
> **M2 是本项目的生死线**：真机能按链接打开商品、精确勾选颜色分类和尺码、
|
||
> **读到该 SKU 的单价**（T-103）。前序项目正是卡在选规格和读价。
|
||
> M2 不通过之前不要写**依赖真机可读字段或会启动试选**的 Phase 2 功能；T-201 与仅创建
|
||
> `DRAFT` 的 T-202 可以并行。原型只确认流程与信息架构，实际可读字段仍以真机证据为准。
|
||
|
||
## 领取任务规则
|
||
|
||
- 每个 agent 只领取一个 frontmatter `status: TODO` 且依赖均 `DONE` 的任务文件，取编号
|
||
最靠前的。
|
||
- `docs/tasks/` 暂无可领任务时，先按 [`06-tasks.md`](06-tasks.md) 把下一个建议任务落成
|
||
任务文件，再领取。
|
||
- 开始前在独立分支 / worktree 把 frontmatter `status` 改为 `DOING`。
|
||
- 本轮只完成这一个任务；验收通过后改为 `DONE`。
|
||
- **执行记录写进该任务文件的 `## 执行记录`**。
|
||
- 项目现实变化（启动 / 验证路径、目录结构、blocker）时覆盖更新
|
||
[`current-state.md`](current-state.md)。
|
||
- 结束前过一遍 [`clean-state-checklist.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` |
|
||
|
||
## 验证命令
|
||
|
||
> Windows 标准入口 `./init.ps1` 已由 T-003 实际验证。它优先使用合规的既有 venv（本机实际为
|
||
> Python 3.12），仅在 venv 缺失时才从 Python Launcher 自动选择最高的 Python 3.11+，避免回退到
|
||
> 默认 Python 3.10；通过后会输出两端真实启动命令。
|
||
|
||
```powershell
|
||
# Windows 统一安装、离线验证与启动命令提示
|
||
.\init.ps1
|
||
|
||
# 以下为诊断或单独验证时使用的等价命令
|
||
# 采购服务 admin/（改了 Go 代码后）
|
||
cd admin
|
||
go test ./...
|
||
go vet ./...
|
||
go build ./...
|
||
|
||
# 采购工具 client/（由 init.ps1 创建的 Python 3.11+ 虚拟环境）
|
||
cd client
|
||
.\.venv\Scripts\python.exe -m unittest discover -s tests -t .
|
||
.\.venv\Scripts\python.exe -m compileall -q src tests scripts
|
||
$wheelDir = Join-Path $env:TEMP ('cmbuyer-client-wheel-' + [guid]::NewGuid())
|
||
New-Item -ItemType Directory -Path $wheelDir | Out-Null
|
||
.\.venv\Scripts\python.exe -m pip wheel --no-deps . --wheel-dir $wheelDir
|
||
.\.venv\Scripts\python.exe scripts/verify_wheel_metadata.py (Get-ChildItem $wheelDir -Filter '*.whl').FullName
|
||
|
||
# 跨端契约改动：两端全跑
|
||
```
|
||
|
||
验证层级何时触发见 [`03-tech-stack.md`](03-tech-stack.md) 第六节验证矩阵。
|
||
`requirements.txt` 是采购工具唯一的运行时依赖来源，`pyproject.toml` 动态读取它写入 wheel
|
||
元数据。规范安装是 Python 3.11+ 虚拟环境中的 `python -m pip install -e .`，已由 Python 3.12
|
||
验证通过；桌面 GUI 和真机流程不属于本次验收。`init.ps1` 使用合规既有 venv，或在缺失时自动选择
|
||
Python 3.11+ 创建它；本机现有 venv 实际验证为 3.12。若命令当前不可运行，必须在回复里如实说明原因。
|