chengma/cmbuyer
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(project): align product names and source directories

Browse Source
This commit is contained in:
QiuSW
2026-08-03 16:27:05 +08:00
parent fe0c867948
commit b9e29ed970
16 changed files with 177 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/04-architecture.md
+33 -32
View File
@@ -11,7 +11,7 @@
└────────────┬───────────┴────────────────────┘
v
┌─────────────────────────────────────────┐
│ web 端（Go 单二进制） │
│ 采购服务（admin/，Go 单二进制） │
│ · 建单、批量开始试选与任务生命周期 │
│ · 候选确认与下单授权（唯一决策权威） │
│ · 证据存储与审计 │
@@ -21,7 +21,7 @@
│ Bearer Token + 设备绑定
v
┌─────────────────────────────────────────┐
│ desk 端（Python + PySide6） │
│ 采购工具（client/，Python + PySide6） │
│ · 领任务、跑流程、回传结果 │
│ · 本地执行轨迹与证据落盘 │
│ · AI 辅助调用（P1） │
@@ -35,15 +35,16 @@
组件落位：
- web 端：Go + gin，入口 `web/cmd/server/main.go`，模板 `web/internal/transport/webui/templates/`
- desk 端：Python，入口 `desk/src/main.py`，真机流程 `desk/src/android/pdd_flow.py`
- 采购服务：Go + gin，入口 `admin/cmd/server/main.go`，模板
`admin/internal/transport/webui/templates/`
- 采购工具：Python，入口 `client/src/main.py`，真机流程 `client/src/android/pdd_flow.py`
- 数据库：SQLite，迁移由 goose 管理
- 证据存储：web 端本地文件系统，SHA-256 寻址
- 外部服务：顺运宝 ERP（只读）、AI provider（P1，仅 desk 端调用）
- 证据存储：采购服务本地文件系统，SHA-256 寻址
- 外部服务：顺运宝 ERP（只读）、AI provider（P1，仅采购工具调用）
## 二、职责划分
### web 端
### 采购服务（网页端，`admin/`）
**独占**：
@@ -60,7 +61,7 @@
- 不保存、代理或下发任何 AI provider 凭据
- 不解析拼多多页面
### desk 端
### 采购工具（桌面端，`client/`）
**独占**：
@@ -72,7 +73,7 @@
**不做**：
- **不自行决定买哪个候选**——必须等 web 端的授权
- **不自行决定买哪个候选**——必须等采购服务的授权
- **不自行放宽金额上限**——本地校验只能更严，不能更松
- 不直接读 Excel 或访问 ERP
- 不在没有授权的情况下执行任何创建订单的动作
@@ -87,14 +88,14 @@
这是本项目最核心的结构决策。**MVP 只做 A 路径（任务自带商品链接），分两趟跑完。**
```text
┌──────────── web 端开始第一趟 ────────────┐
┌────────── 采购服务开始第一趟 ───────────┐
│ 新任务先保存为 DRAFT │
│ 管理员在任务表格勾选一条或多条 │
│ 原子转为 PENDING，只进入试选队列 │
└────────────────────┬─────────────────────┘
v
┌──────────────── 第一趟：试选 ────────────────┐
│ desk 端轮询领取 PENDING 任务 │
│ 采购工具轮询领取 PENDING 任务 │
│ 1. open_product(url) │
│ 2. 打开规格面板 │
│ 3. 按维度精确勾选颜色分类、尺码 │
@@ -107,14 +108,14 @@
任务转 WAITING_CONFIRMATION
│
┌────────────────────┴─────────────────────────┐
│ 人在 web 端确认：机器选对了吗 │
│ 人在采购服务确认：机器选对了吗 │
│ 看：需求 vs 选中规格、单价、合计、截图 │
│ 点「确认下单（不付款）」→ 签发授权，锁定授权价 │
│ 或「退回，不买」→ 任务终止 │
└────────────────────┬─────────────────────────┘
v
┌──────────────── 第二趟：下单 ────────────────┐
│ desk 端轮询拿到授权 │
│ 采购工具轮询拿到授权 │
│ 1. 重新 open_product(url) │
│ 2. 重新按维度精确勾选同一规格 │
│ 3. 【闸门二】重读单价，必须与授权价一致 │
@@ -179,15 +180,15 @@ V2 实现时仍遵守：**图搜的唯一产出是 goods_id**，不在搜索结
| 安全校验 | 检测到验证码、风控、人脸、短信校验立即停止，不尝试绕过 | 封号 / 违规 |
| 敏感信息 | 只读非敏感摘要，不提取收货地址原文、手机号、支付凭据 | 隐私泄露 |
| 授权一次性 | 一笔授权只能产生一笔订单，重复提交幂等 | 重复采购 |
| 服务端提交围栏 | 真机点击前必须由 web 端原子冻结授权并创建唯一提交记录；失败或响应不明不得点击 | 并发 / 断网导致重复下单 |
| 服务端提交围栏 | 真机点击前必须由采购服务原子冻结授权并创建唯一提交记录；失败或响应不明不得点击 | 并发 / 断网导致重复下单 |
| App 版本失配即停 | 运行版本与本项目已取证版本不一致时停止领取真机任务，先重新取证 | 旧判据误点新页面 |
### 提交订单的四个前置条件
这是本项目唯一会创建真实待付款订单的动作。**四者同时满足才允许点击，且只点一次：**
1. **授权存在且未消费，并已建立服务端提交围栏**——web 端已签发、desk 端已 ack；
真机点击前，web 端在一个原子事务中把授权从可执行态冻结为本次唯一
1. **授权存在且未消费，并已建立服务端提交围栏**——采购服务已签发、采购工具已 ack；
真机点击前，采购服务在一个原子事务中把授权从可执行态冻结为本次唯一
`order_submission`。围栏接口失败或响应不明时不得点击。
2. **闸门二通过**——第二趟重读的单价与授权时锁定的价格一致。
3. **闸门三通过**——订单确认页「实付款」不超过授权总额上限。
@@ -211,9 +212,9 @@ V2 实现时仍遵守：**图搜的唯一产出是 goods_id**，不在搜索结
1. **dry-run（只读演练）**：进入订单确认页，读取规格、数量和「实付款」，确认提交控件
唯一，上传证据后退出。该阶段绝不点击「提交订单」，也不消费授权。
2. **提交围栏**：真实第二趟再次读取并通过三道闸门后，desk 端向 web 端申请围栏。web 端
2. **提交围栏**：真实第二趟再次读取并通过三道闸门后，采购工具向采购服务申请围栏。采购服务
原子校验任务版本、命令、未消费授权和唯一性，创建 `order_submissions` 记录并冻结授权。
只有明确收到成功响应，desk 端才可点击一次。
只有明确收到成功响应，采购工具才可点击一次。
3. **结果调和**：点击后只上报观察结果。明确创建则转 `WAITING_PAYMENT`；超时、外部支付、
安全校验或断连均转 `RECONCILIATION_REQUIRED`，保留额度并由人核查。**不得释放围栏、
重新签发授权或自动重试点击。**
@@ -307,7 +308,7 @@ MVP 的授权没有「选择理由 / 拒绝理由」——那是从多个候选
### 5.2 状态机
任务状态（web 端权威）。创建与开始试选分离；两趟执行对应两次 `CLAIMED → RUNNING`：
任务状态（采购服务权威）。创建与开始试选分离；两趟执行对应两次 `CLAIMED → RUNNING`：
```text
DRAFT ─start trial→ PENDING ─┐
@@ -331,7 +332,7 @@ PENDING_RETRIAL ─────────────┴─claim→ CLAIMED
| `RUNNING(TRIAL)` | 第一趟试选中：正在勾选规格、读价、截图 |
| `WAITING_CONFIRMATION` | 试选已回传，**等人确认机器选对了没** |
| `PENDING_RETRIAL` | 旧授权已过期或在围栏前被放弃，必须重新跑第一趟取得新价格 |
| `AUTHORIZED` | 已签发授权，等 desk 端下一轮轮询领走 |
| `AUTHORIZED` | 已签发授权，等采购工具下一轮轮询领走 |
| `ORDERING` | 第二趟下单中：重新选规格、过闸门二三、提交订单 |
| `WAITING_PAYMENT` | 订单已创建，等人在拼多多付款。**这不是成功** |
| `RECONCILIATION_REQUIRED` | 已建立提交围栏，但点击结果不明确；可能已创建订单，只能核查，不能重试 |
@@ -355,7 +356,7 @@ PENDING_RETRIAL ─────────────┴─claim→ CLAIMED
- 每笔授权带 `expires_at`。**仅在尚未建立提交围栏时**，超时自动转 `EXPIRED`。
- 授权 `EXPIRED` 后任务转 `PENDING_RETRIAL`，先重新跑第一趟取得新价格，再回到人工确认；
不允许在旧 `spec_trials` 上直接重新确认。
- web 端在围栏建立前提供「放弃当前授权」入口；围栏建立后改为「进入人工核查」，不得
- 采购服务在围栏建立前提供「放弃当前授权」入口；围栏建立后改为「进入人工核查」，不得
作废或释放授权。
- **任何时候都不允许出现「任务停在某状态且界面上没有任何可用动作」的组合。**
这是验收项，不是实现细节。
@@ -367,12 +368,12 @@ PENDING_RETRIAL ─────────────┴─claim→ CLAIMED
| 数据 | 位置 | 理由 |
| --- | --- | --- |
| 候选商品页 / 规格页截图 | 上传 web 端 | 管理员做授权决策必须看 |
| 订单确认页截图 | 上传 web 端 | 授权后核对与审计必须留 |
| 订单核对截图 | 上传 web 端 | 资金核对证据 |
| 完整节点树 XML | **仅 desk 端本地** | 体积大、含页面全文、只用于排障 |
| AI 调用记录（P1） | **仅 desk 端本地** | 含 prompt / 响应全文，脱敏成本高 |
| 失败现场快照 | 仅 desk 端本地，可按需手工导出 | 同上 |
| 候选商品页 / 规格页截图 | 上传采购服务 | 管理员做授权决策必须看 |
| 订单确认页截图 | 上传采购服务 | 授权后核对与审计必须留 |
| 订单核对截图 | 上传采购服务 | 资金核对证据 |
| 完整节点树 XML | **仅采购工具本地** | 体积大、含页面全文、只用于排障 |
| AI 调用记录（P1） | **仅采购工具本地** | 含 prompt / 响应全文，脱敏成本高 |
| 失败现场快照 | 仅采购工具本地，可按需手工导出 | 同上 |
上传前必须脱敏：**不上传含收货地址、手机号、支付凭据的截图区域或文本。**
@@ -397,9 +398,9 @@ PENDING_RETRIAL ─────────────┴─claim→ CLAIMED
2. **Phase 1 真机取证**：WiFi ADB 连通；打开商品 → 打开规格面板 → 按维度精确勾选颜色
分类和尺码 → **读到该 SKU 单价** → 设数量 → 进订单确认页 → 读「实付款」。
**结论写入文档，判据带拼多多 App 版本。**
3. **Phase 2 web 端核心**：数据模型与状态机、手工建单、任务查询、试选结果接收、
3. **Phase 2 采购服务核心**：数据模型与状态机、手工建单、任务查询、试选结果接收、
确认页与授权签发、**授权超时与放弃**。
4. **Phase 3 双端打通**：设备侧 API、desk 端 `HttpTaskSource`/`HttpResultSink`、
4. **Phase 3 双端打通**：设备侧 API、采购工具 `HttpTaskSource`/`HttpResultSink`、
定时轮询、第一趟试选端到端。
5. **Phase 4 闭环收尾**：第二趟下单（含三道闸门与提交）、失败分类、完整验收、打包。
6. **V2 及以后**：图片搜索路径、候选对照台、Excel 导入、ERP 建单、订单自动核对、AI 辅助。
@@ -412,7 +413,7 @@ PENDING_RETRIAL ─────────────┴─claim→ CLAIMED
```text
cmbuyer/
├── docs/
├── web/ # Go
├── admin/ # 采购服务（Go）
│ ├── cmd/server/
│ ├── internal/
│ │ ├── domain/ # 实体与状态机，无外部依赖
@@ -422,7 +423,7 @@ cmbuyer/
│ │ │ └── webui/ # 管理页面 + 模板 + 静态资源
│ │ └── storage/ # SQLite 与证据资产
│ └── migrations/
├── desk/ # Python
├── client/ # 采购工具（Python）
│ ├── src/
│ │ ├── android/ # adb / device / pdd_flow
│ │ ├── core/ # models / task_runner / sources 抽象
@@ -432,7 +433,7 @@ cmbuyer/
└── scripts/
```
`desk/src/core/sources.py` 必须保留 `TaskSource` / `ResultSink` 抽象，执行器只依赖抽象。
`client/src/core/sources.py` 必须保留 `TaskSource` / `ResultSink` 抽象，执行器只依赖抽象。
这样离线 Excel 模式可作为降级路径存在，且执行器不因来源变化而改动。
## 九、架构纪律