# 架构设计

> 本文定义系统结构、职责、单趟采购流程、安全边界和数据模型。框架与运行命令见
> [技术栈](03-tech-stack.md)，双端线协议以 [API 合约](api.md)为唯一权威。

## 一、系统结构

```text
人工填链接（MVP）                 Excel / ERP（V2）
         │                              │
         └──────────────┬───────────────┘
                        v
        ┌─────────────────────────────────────────┐
        │  采购服务（admin/，Go）                   │
        │  · 建单、查询、开始采购授权与任务状态        │
        │  · 提交围栏、结果调和、内部证据与审计         │
        │  · 服务端渲染管理页面                       │
        └───────────────────┬─────────────────────┘
                            │ 本机回环 HTTP / JSON（MVP）
                            │ Bearer + 设备绑定；非回环前必须先上 TLS
                            v
        ┌─────────────────────────────────────────┐
        │  采购工具（client/，Python + PySide6）    │
        │  · 轮询领取、单趟执行、回传状态与证据        │
        │  · 本地完整节点树与执行轨迹                  │
        └───────────────────┬─────────────────────┘
                            │ ADB（USB / WiFi）
                            v
                 Android 手机（拼多多 App）
```

- 采购服务：Go + gin，SQLite，goose migration，本地 SHA-256 证据存储。
- 采购工具：Python + uiautomator2 + PySide6；执行器只依赖 `TaskSource` / `ResultSink` 抽象。
- 页面判据与拼多多 App 版本绑定；版本不同即停止，不把前序项目页面结构当作事实。

## 二、职责划分

### 采购服务（`admin/`）

独占以下权威：

- 任务创建、批量开始采购、状态流转和终态判定；
- **一次性采购授权的签发**：管理员点击“开始采购”是唯一的人类授权动作；
- 任务不可变字段和最高总价校验；
- 提交订单前的原子围栏与点击后结果调和；
- 管理员会话、设备凭据、内部截图证据和审计记录。

采购服务不连接手机、不发 ADB 命令、不解析拼多多页面，也不持有支付或 AI provider 凭据。

### 采购工具（`client/`）

独占以下设备能力：

- ADB 连接、设备健康检查和已取证 App 版本校验；
- 打开商品、识别页面、精确选规格、设置数量、读取价格；
- 在满足全部门禁并取得服务端围栏后，精确点击一次“提交订单”；
- 截图、完整节点树和执行日志的本地采集，显式上传内部截图。

采购工具不自行修改任务约束、不扩大金额上限、不领取 `DRAFT`，也不能签发授权。没有服务端
明确返回 `click_permitted=true` 时，任何本地判断都不能创建订单。

### 权威冲突规则

服务端校验锁定的任务约束，客户端校验当前真机事实。任一端拒绝或两端摘要不一致，一律停止并
转人工；不能为了“继续跑”选择相信其中一端。

## 三、单趟采购执行

MVP 只做任务自带商品链接的 A 路径。创建任务与开始采购分离，但管理员开始后不再插入试选确认：

```text
管理员创建 DRAFT
      │
      ├─ 勾选 DRAFT，查看选中数与最高总额
      └─ 点击“开始采购（只创建待付款订单）”
             │  同一事务：校验版本 + 创建一次性授权 + PENDING
             v
采购工具领取授权任务
      │  1. 打开 canonical 商品链接
      │  2. 通过证据/版本绑定、精确唯一的受控入口打开规格面板
      │  3. 按维度精确选择并读回颜色、尺码
      │  4. 【闸门一】读 SKU 单价；单价×数量不得超过最高总价
      │  5. 设置数量并精确读回
      │  6. 【闸门二】重读规格、数量与面板总额；总额不超最高总价
      │  7. 保持在合并式最终提交面板，不执行页面导航
      │  8. 【闸门三】重核规格/数量；最终控件金额等于闸门二且不超最高总价
      │  9. 上传验证摘要并申请服务端提交围栏
      │ 10. 仅在 click_permitted=true 且提交控件唯一时点击一次
      │ 11. 回传观察结果；不确定时只调和，不重试
      v
WAITING_PAYMENT ──人核对与付款──> SUCCEEDED
      或
RECONCILIATION_REQUIRED ──人工核查同一提交──> WAITING_PAYMENT / FAILED
```

“开始采购”锁定的是管理员填写的 `goods_id`、颜色、尺码、数量和**最高总价**，不是一张旧页面
截图里观察到的价格。价格在执行时实时读取，因此取消试选确认不会取消价格保护。

### 受控规格面板入口

T-103 最新真机证据表明：拼多多 `8.17.0`、goods_id `937122477375`、1080×2376 的规格面板
入口是屏幕底部购买区第一行 `快要抢光 + 金额`，不是商品内容区的同名促销小字。T-110 已批准把
该**特定证据、版本和页面状态**绑定的点击定义为受控导航。

- 只能精确唯一匹配底部非点击文本叶节点、其直接可点击 PDD 父容器及证据绑定结构，并且只点击
  第一行文本叶节点中心；缺失、重复、版本失配、结构漂移或打开后面板不唯一时零后续点击。
- 商品内容区同名促销小字明确禁止作为入口。底部购买区入口金额只参与结构识别，不得解析、返回或
  充当价格来源；规格选择后的最终红色控件金额也不得用于 Gate1/Gate2，只在 T-106 已确认的合并式
  最终提交面板中作为 Gate3 独立金额角色。
- `免拼购买` 只允许作为已取证、不可点击的精确兄弟节点验证底部结构，不能作为选择器、目标或兜底；
  它变为可点击、位置漂移或出现在其他结构时必须拒绝。“单独购买 / 直接拼成”等其他文案同样不能
  用包含、前缀、同义或坐标兜底。
- 受控入口只负责进入已取证面板，不等于支付授权，也不能暴露通用任意点击能力。
- T-103 的隔离验证 capability 只包含开商品、开面板、选规格、读价和安全退出；数量、最终提交面板、
  提交和支付仍由后续真机任务分别取证后才能接入生产单趟执行器。

2026-08-05 的五组 8.17.0 真机证据进一步证明，面板刚打开时颜色与尺码均未选中，尺码选项尚未
进入视口；选择目标颜色后，摘要只剩“请选择：尺码”，但尺码仍不可见。实现必须把未选初态、
仅颜色已选态、非目标尺码态和目标尺码态作为各自完整的证据 profile 匹配，禁止把不同状态的价格、
摘要、容器或坐标拼成一个宽松判据。

- 显示尺码只允许命名的私有 `reveal_size_options()` 窄能力：仅从已证明的“目标颜色已选、尺码未选
  且隐藏”状态执行，绑定证据确认的嵌套滚动容器与列间安全通道，最多一次且不重试；不得公开通用
  `swipe`、`scroll`、任意坐标或把底部提交区纳入动作范围。
- 生产 reveal 落地前，必须补齐“动作前后目标尺码均未选、尺码由隐藏变为可见、提交区未触发”的
  同版本真机动作证据。现有“滚动后 M 已选中”快照不能证明滚动没有误点规格，不得据此猜测手势。
- 这组证据只能由独立 spike 在严格前置成立后执行一次固定、无参数手势采集；生产 Flow 不得调用该
  spike。RPC 超时或响应不明时只允许只读调和，不得重试；候选后置必须再由人核对后才能成为生产判据。
- 尺码 action 的真实节点类型、精确文案和 selected 读回必须随 profile 一起验证；当前证据中的 S/M
  是可点击 `TextView`。只有目标颜色与目标尺码双重读回一致后才能读取闸门一价格。
- 一次 Back 在调用前即封存且不得重试；仅“面板消失”不能作为生产安全退出的充分条件。同商品详情页
  的严格退出判据由 T-104 取得独立真机证据后开放。

### 三道价格闸门

| 闸门 | 当前页面 | 判据 | 拒绝条件 |
| --- | --- | --- | --- |
| 一 | 规格面板，选中目标规格后 | 单价唯一可读；`单价 × 授权数量 <= 最高总价` | 不可读、有歧义或超上限 |
| 二 | 规格面板，数量读回后 | 颜色、尺码仍正确；目标数量面板总额唯一可读且不超最高总价 | 规格/数量漂移、总额不可读/有歧义或超上限 |
| 三 | 同一合并式最终提交面板 | 规格、数量正确；最终红色控件结构化文本中的金额唯一可读、严格等于闸门二且不超最高总价 | 任一不一致、不可读、有歧义或超上限 |

金额一律使用十进制字符串和十进制定点运算，不用浮点数。Gate1/Gate2 只从规格面板顶部已批准角色
读取；Gate3 只从同一最终面板唯一结构化精确文本 `提交订单 ¥{规范十进制金额}` 读取。详情正文、
搜索卡片、底部购买入口和其他按钮数字都不是价格来源；Gate3 金额也不得回流充当 Gate1/Gate2。

2026-08-06 的拼多多 `8.17.0` 真机证据证明同一规格的多件优惠是非线性的：数量 1 时规格面板顶部
当前金额为 `12.88`，数量 2 时变为 `32.76`，而不是 `12.88 × 2`。因此闸门一仍是设置数量前的单价
预检，闸门二必须读取设置后的**面板总额** `gate2_panel_total_price` 并直接比较最高总价；不得把
Gate1 乘数量、不得要求 Gate2 等于 Gate1。2026-08-06 T-106 进一步证明当前版本没有独立确认页：
同一面板的红色 `提交订单 ¥32.76` 会直接创建待付款订单并进入付款界面。因此 Gate3 改为在不可逆
动作前只读该最终控件金额，并要求它与 Gate2 顶部总额严格相等；这是同一稳定页面两个独立 UI 位置的
交叉校验，不是把按钮金额当 Gate2 兜底。

闸门一与闸门二发生在同一设备会话中，不需要管理员在中间确认。旧截图、缓存值和发布前 dry-run
都不能替代这次实时读取。

### B 路径（V2）

没有商品链接时由图片搜索只产出 `goods_id`，再汇入上述流程。不在搜索结果页读取价格或规格。

## 四、安全边界（硬约束）

以下每条都必须有测试证明，不得在任务中顺手放宽：

| 边界 | 规则 | 防止什么 |
| --- | --- | --- |
| 不付款 | 不点击支付、免密支付、先用后付或任何扣款控件 | 真实资金损失 |
| 提交四条件 | 授权+围栏、闸门二、闸门三、控件唯一同时成立，只点一次 | 误下单 / 重复下单 |
| 最终面板零点击 | 除安全返回和满足四条件后的最终红色控件外不点击任何控件 | 未知副作用 |
| 规格精确匹配 | 维度内等值唯一匹配，防 `红/粉红`、`1/10` 前缀碰撞 | 买错规格 |
| 数量读回复核 | 设置后精确读回，不一致即停 | 买错数量 |
| 三道价格闸门 | 任一道不可读、有歧义或不通过都停，不用别处数字凑 | 超预算 |
| 受控页面能力 | 页面动作按任务与证据分层；不得把通用 `click` 传入业务流程 | 边界扩散 |
| 外部支付页 | 检测到外部支付交接立即停止，不读取、保存或输入凭据 | 凭据泄露 |
| 安全校验 | 验证码、风控、人脸、短信出现即停止，不绕过 | 封号 / 违规 |
| 内部截图 | 可上传页面已显示的地址/手机号；不解析成字段或日志，完整 XML 不上传 | 非必要扩散 |
| 身份隔离 | 管理 session+CSRF 与设备 Bearer 分属不同路由域，混合凭据不叠加权限 | 设备越权 / 会话冒充 |
| Bearer 传输 | MVP 仅绑定 IPv4 回环 `127.0.0.1:8080`；非回环访问先建立 HTTPS/TLS 终止 | 明文局域网泄露 token |
| 授权一次性 | 一条任务版本只有一份有效授权；幂等重放不生成第二份 | 重复采购 |
| 服务端提交围栏 | 点击前原子创建唯一提交记录；失败或响应不明不得点击 | 并发 / 断网重复下单 |
| App 版本绑定 | 运行版本不同于证据版本时停止并重新取证 | 旧判据误点 |

### 提交订单的四个前置条件

“提交订单”是系统唯一会创建真实待付款订单的动作。以下四项同时满足才允许点击一次：

1. **一次性授权有效且服务端提交围栏已建立**：围栏把授权、任务、领取和本次验证摘要原子绑定到
   唯一 `order_submission`；明确响应包含 `click_permitted=true`。
2. **闸门二通过**：目标规格和数量未漂移，目标数量面板总额唯一可读且不超过授权最高总价。
3. **闸门三通过**：同一最终面板的规格、数量正确；唯一结构化文本 `提交订单 ¥{金额}` 中金额严格
   等于闸门二顶部总额，且不超过授权最高总价。
4. **提交控件唯一**：完整结构化文本唯一、启用，且其最近可点击祖先唯一。不得使用包含、前缀、
   OCR、裸坐标或返回通用可点击对象。

围栏请求超时、断网、冲突或响应不明时不得点击。围栏建立后：

| 观察结果 | 处置 |
| --- | --- |
| 明确进入订单结果 / 待付款页 | 上报 `SUBMITTED`，任务转 `WAITING_PAYMENT` |
| 跳转外部支付 | 立即停止，上报结果不明确，不执行支付 |
| 出现验证码 / 风控 / 人脸 / 短信 | 立即停止，上报结果不明确，不绕过 |
| 超时、断连、页面无法判定 | 转 `RECONCILIATION_REQUIRED`，保留围栏和金额额度 |

后三种情况都禁止释放围栏、重新授权、重新领取或再次点击。只能调和同一提交记录。

### 发布前 dry-run 与生产围栏的区别

首次启用某一 App 版本的真实提交能力前，必须用独立真机任务完成只读 dry-run：在合并式最终提交
面板验证规格、数量、Gate2 顶部总额、Gate3 最终控件金额与最近可点击祖先唯一，然后退出且不点击。
它用于证明判据和不可达测试，不是每笔采购的
“第一趟”，也不产生可复用页面事实。生产任务仍在同一趟内重新通过三道闸门并申请服务端围栏。

## 五、数据模型

### 5.1 核心实体

```sql
CREATE TABLE tasks (
  id                 TEXT PRIMARY KEY,
  source             TEXT NOT NULL,              -- MANUAL | EXCEL | ERP
  source_ref         TEXT,
  title              TEXT NOT NULL,
  goods_id           TEXT NOT NULL,
  sku_color          TEXT NOT NULL,
  sku_size           TEXT NOT NULL,
  quantity           INTEGER NOT NULL CHECK (quantity > 0),
  max_total_price    TEXT NOT NULL,              -- 十进制字符串
  reference_asset_id TEXT,
  status             TEXT NOT NULL,
  version            INTEGER NOT NULL DEFAULT 1,
  created_at         TEXT NOT NULL,
  updated_at         TEXT NOT NULL
);

-- 管理员点击“开始采购”产生；锁定任务约束，不锁定旧观察价
CREATE TABLE order_authorizations (
  id                 TEXT PRIMARY KEY,
  task_id            TEXT NOT NULL REFERENCES tasks(id),
  task_version       INTEGER NOT NULL,
  start_key          TEXT NOT NULL,
  goods_id           TEXT NOT NULL,
  sku_color          TEXT NOT NULL,
  sku_size           TEXT NOT NULL,
  quantity           INTEGER NOT NULL,
  total_price_cap    TEXT NOT NULL,
  status             TEXT NOT NULL,              -- ACTIVE | CLAIMED | FENCED | CONSUMED | EXPIRED | ABANDONED
  created_by         TEXT NOT NULL,
  created_at         TEXT NOT NULL,
  expires_at         TEXT NOT NULL,
  UNIQUE (task_id, task_version),
  UNIQUE (start_key, task_id)
);

-- 一次领取产生一条可恢复执行；保存步骤摘要，不接收完整 XML
CREATE TABLE purchase_attempts (
  id                 TEXT PRIMARY KEY,
  task_id            TEXT NOT NULL REFERENCES tasks(id),
  authorization_id   TEXT NOT NULL REFERENCES order_authorizations(id),
  claim_generation   INTEGER NOT NULL,
  status             TEXT NOT NULL,
  gate1_unit_price   TEXT,
  gate2_panel_total_price TEXT,
  quantity_read      INTEGER,
  gate3_submit_amount TEXT,
  failure_code       TEXT,
  started_at         TEXT NOT NULL,
  finished_at        TEXT,
  UNIQUE (task_id, claim_generation),
  UNIQUE (task_id, authorization_id, id, claim_generation)
);

-- attempt 的设备/session 所有权与可恢复租约；token 明文永不入库
CREATE TABLE purchase_attempt_claims (
  attempt_id              TEXT PRIMARY KEY,
  task_id                 TEXT NOT NULL,
  authorization_id        TEXT NOT NULL UNIQUE,
  claimed_by_device_id    TEXT NOT NULL REFERENCES device_credentials(device_id),
  session_id              TEXT NOT NULL,
  claim_generation        INTEGER NOT NULL,
  task_version            INTEGER NOT NULL,
  task_title              TEXT NOT NULL,
  authorization_task_version INTEGER NOT NULL,
  goods_id                TEXT NOT NULL,
  sku_color               TEXT NOT NULL,
  sku_size                TEXT NOT NULL,
  quantity                INTEGER NOT NULL,
  total_price_cap         TEXT NOT NULL,
  authorization_expires_at TEXT NOT NULL,
  claim_nonce             BLOB NOT NULL,        -- 32 字节随机 nonce
  claim_token_sha256      BLOB NOT NULL,        -- 32 字节 hash，不是 token 明文
  lease_expires_at        TEXT NOT NULL,
  claimed_at              TEXT NOT NULL,
  closed_at               TEXT,
  FOREIGN KEY (task_id, authorization_id, attempt_id, claim_generation)
    REFERENCES purchase_attempts(task_id, authorization_id, id, claim_generation)
);

CREATE UNIQUE INDEX purchase_attempt_claims_one_open_per_device_idx
ON purchase_attempt_claims (claimed_by_device_id) WHERE closed_at IS NULL;

-- claim-next 的 CLAIMED / EMPTY / BLOCKED 与 renew CAS 都持久化，保证跨重启幂等。
-- 复合外键同时绑定 attempt、设备、session、generation 与 token hash，应用 bug 不能跨归属写事实。

-- 真机真实点击前建立；一份授权最多一条
CREATE TABLE order_submissions (
  id                 TEXT PRIMARY KEY,
  task_id            TEXT NOT NULL REFERENCES tasks(id),
  authorization_id   TEXT NOT NULL REFERENCES order_authorizations(id),
  attempt_id         TEXT NOT NULL REFERENCES purchase_attempts(id),
  status             TEXT NOT NULL,              -- FENCED | SUBMITTED | RECONCILIATION_REQUIRED | MANUAL_RESOLVED
  gate1_unit_price   TEXT NOT NULL,
  gate2_panel_total_price TEXT NOT NULL,
  quantity_read      INTEGER NOT NULL,
  gate3_submit_amount TEXT NOT NULL,
  created_at         TEXT NOT NULL,
  resolved_at        TEXT,
  UNIQUE (authorization_id),
  UNIQUE (attempt_id)
);

-- 设备 token 明文只在签发完成后显示一次；数据库仅保存原始 32 字节 token 的 SHA-256
CREATE TABLE device_credentials (
  device_id     TEXT PRIMARY KEY,              -- 规范小写 UUIDv4
  display_name  TEXT NOT NULL,                 -- 非秘密运维名称
  token_sha256  BLOB NOT NULL UNIQUE,           -- 恰好 32 字节
  status        TEXT NOT NULL,                  -- ACTIVE | REVOKED
  created_at    TEXT NOT NULL,
  revoked_at    TEXT,
  CHECK ((status = 'ACTIVE' AND revoked_at IS NULL)
      OR (status = 'REVOKED' AND revoked_at IS NOT NULL AND revoked_at >= created_at))
);

-- INTERNAL_RAW 原始截图；原文件名和客户端路径不进入数据库
CREATE TABLE evidence_assets (
  id                    TEXT PRIMARY KEY,
  upload_key            TEXT NOT NULL,
  task_id               TEXT NOT NULL,
  attempt_id            TEXT NOT NULL,
  kind                  TEXT NOT NULL,          -- T-204 仅 SKU_PANEL_GATE_1
  privacy_tier          TEXT NOT NULL,          -- 仅 INTERNAL_RAW
  sha256                TEXT NOT NULL,          -- 64 位小写十六进制
  byte_size             INTEGER NOT NULL,
  content_type          TEXT NOT NULL,          -- 仅 image/png
  width_px              INTEGER NOT NULL,
  height_px             INTEGER NOT NULL,
  storage_key           TEXT NOT NULL,          -- 由 SHA-256 唯一派生
  uploaded_by_device_id TEXT NOT NULL,
  captured_at           TEXT NOT NULL,
  created_at            TEXT NOT NULL,
  UNIQUE (uploaded_by_device_id, upload_key),
  FOREIGN KEY (task_id, attempt_id) REFERENCES purchase_attempts(task_id, id)
);
```

MVP 不再用 `spec_trials` 作为审批记录，也不存在 `authorized_unit_price`。实际读价属于
`purchase_attempts` / `order_submissions` 的执行与审计事实；管理员授权的资金边界始终是
`total_price_cap`。

上述 `gate3_submit_amount` 是 T-106 真机结论后的目标 schema。当前历史 migration 仍含
`confirm_amount` / `confirm_page_amount`；T-210 必须在 T-205/T-208 消费前用受保护 migration 完成
迁移，旧列存在期间不得开放 submission fence，不能把旧名字继续解释成新事实。

设备凭据由本机管理 CLI 签发、列出和撤销。token 是 32 字节加密随机值，以 64 位小写十六进制
只显示一次；服务端把 token 解码回原始字节后计算 SHA-256，并与按设备 id 查出的 32 字节 BLOB
恒定时间比较。未知 id 也执行固定宽度 dummy compare。认证逐请求查库，因此撤销事务提交后才开始的
请求全部拒绝；提交前已经完成认证的在途请求不追溯取消。格式/未知/错配/撤销统一空 401，存储故障
空 503，两类都在读取业务请求体前失败闭合。

### 5.2 状态机

```text
DRAFT
  └─开始采购（创建授权）→ PENDING
       └─claim→ CLAIMED ─start→ ORDERING
                    ├─围栏前验证失败→ NEEDS_MANUAL ─人工处理/重置→ DRAFT
                    ├─围栏前授权过期/安全释放→ DRAFT
                    └─submission FENCED
                           ├─明确创建→ WAITING_PAYMENT ─人工付款并标记→ SUCCEEDED
                           └─结果不明→ RECONCILIATION_REQUIRED
                                      └─人工调和同一提交→ WAITING_PAYMENT / FAILED

DRAFT / PENDING / NEEDS_MANUAL ─管理员取消（围栏前）→ CANCELED
```

| 状态 | 含义与安全下一步 |
| --- | --- |
| `DRAFT` | 已保存，未授权；管理员可编辑/取消或点击开始采购；设备不可领取 |
| `PENDING` | 已有有效一次性授权，等待采购工具领取 |
| `CLAIMED` | 已由一个设备实例持有租约，尚未开始页面操作 |
| `ORDERING` | 单趟执行中，正在选规格、过闸门或申请围栏 |
| `NEEDS_MANUAL` | 围栏前失败；显示原因，由人核查后重置为 DRAFT 或取消 |
| `WAITING_PAYMENT` | 订单已明确创建，等待人在拼多多付款；**不是成功** |
| `RECONCILIATION_REQUIRED` | 围栏后结果不明；只能核查同一提交，不能重试 |
| `SUCCEEDED` | 人已付款并完成核对 |
| `FAILED` | 人工调和确认订单未创建或任务无法完成 |
| `CANCELED` | 围栏前由管理员取消，不再执行 |

批量 `DRAFT → PENDING` 必须全有或全无。服务端同时创建授权；“先改状态、稍后补授权”无效。
`WAITING_CONFIRMATION`、`PENDING_RETRIAL`、`AUTHORIZED` 和 `RUNNING(TRIAL)` 不再属于 MVP 状态。

### 5.3 授权、租约与恢复

- claim/renew 使用独立 32 字节 HMAC secret；配置为 64 位小写十六进制，不得等于 session secret 或
  任一设备 token。每条 claim 以版本域分隔 HMAC 绑定 device/task/authorization/attempt/generation/
  32 字节随机 nonce，SQLite 只保存 nonce 和 token SHA-256。启动会重建并恒定时核对所有 open/closed
  claim；secret 错误时失败闭合，不轮换 token。
- claim 与 renew 的 SQLite 事务必须先通过条件 no-op UPDATE 取得写入线性化位置并复核设备 ACTIVE，
  才能读取或重放 request。撤销先提交则请求失败；claim/renew 先取得写位置则该事务可完成，随后撤销
  不会自动释放已建立的 claim。
- 同一授权最多一个 attempt，同一设备最多一个未关闭 claim。EMPTY、人工恢复冲突和续租响应都持久化；
  同幂等键只能重放原结果，不能因候选变化、续租或服务重启递增 generation、轮换 token 或延长第二次。
- claim 行同时冻结成功响应所需的 task 标题/版本以及 authorization 版本、规格、数量、总价上限和到期
  时间。旧 request 跨重启只从该快照重建；源 task/authorization 后续漂移不能改变历史响应，并会让新
  恢复或续租失败闭合。进入 `ORDERING` 的同 attempt 仅接受 task version 恰好比 claim 快照加一。
- 租约 TTL 显式配置为正且严格短于授权 TTL；新到期时间不得超过授权到期。租约与授权边界相等即过期，
  没有宽限；过期、撤销、停止轮询和进程退出均不关闭 claim、不释放授权、不允许另一设备接管。
- 授权带 `expires_at`，只有围栏前可转 `EXPIRED` / `ABANDONED`；任务回到 `DRAFT`，必须重新点击
  开始采购。旧授权永不复活。
- 设备租约丢失不等于授权可安全重用。只有服务端确认该 attempt 未建立围栏，才能关闭 attempt 并
  回到 `DRAFT` / `NEEDS_MANUAL`；不能自动重新领取并重复页面动作。
- 围栏建立后即使租约过期也只恢复同一 `order_submission` 的调和，不能回到可领取队列。
- 每种非终态都必须给出安全下一步，不能出现隐藏表单导致任务永久锁死。

#### 采购工具本地恢复状态

- 生产入口先取得基于规范数据库路径的 Windows `Global\` named mutex，再构造 DPAPI 和 SQLite；不能
  以服务端“单设备最多一个 claim”替代本机单实例。
- profile、polling session、claim/renew request、open/historical claim、evidence marker/slot 使用 WAL、
  `synchronous=FULL` 与 append-only/单调关闭约束。当前 session/claim 由 `closed_at IS NULL` partial
  unique 保证唯一，历史关闭后不阻塞下一条，但不得删除或复活。
- `DurableClientGateway` 是轮询和截图接入的唯一顺序入口：先 durable prepare，再一次 HTTP，最后原子
  commit。停止只把当前 session 的 `accept_new` 设为 false；飞行中响应仍提交，pending/open 不清除。
- 每次发送前校验 profile/session/request/active immutable business snapshot、renew history、evidence marker/slot/
  receipt 的完整状态图；snapshot、renew response 与 evidence receipt 还保存不可变摘要。任一冗余事实不一致、
  DPAPI context 不匹配、数据库缺行或文件 identity 变化时零 HTTP 停止，不能自行“修复”。
- 设备 Bearer 的 401 发生在服务端读取 body/写幂等事实前，因此槽保持 `PENDING`；只允许同 device id
  更新 Bearer，并在用户再次开始后用原 key/body/file 尝试。claim token 和其他 frozen 配置不变。
- 原始 token 以 DPAPI current-user context 密文保存：device token 绑定 profile+device，claim/renew token
  绑定 profile+attempt，密文不能跨行复用；日志 formatter 对 Bearer、裸 64 位 token 和
  traceback 做最终脱敏。异常对象也只保留固定 reason，不挂接含响应 body/partial/path 的异常上下文。

### 5.4 证据分层

| 数据 | 位置 | 边界 |
| --- | --- | --- |
| 商品 / 规格 / 最终提交面板原始 screenshot | 采购工具本机 + 采购服务内部证据存储 | 可含页面已显示地址/手机号；设备鉴权上传、管理员登录查看，不遮罩 |
| 完整 XML | 仅采购工具本机隔离目录 | 可在内存解析页面判据；不上传、不写日志、Git、Vikunja |
| 最小 XML fixture | 采购工具测试 / Git | 只保留判据所需结构，确认无地址、手机号、支付凭据 |
| 外部支付页或支付凭据 | 不保存、不上传 | 检测到交接立即停止 |
| AI 调用记录（V2） | 仅采购工具本地 | 不进入采购服务 |

截图上传器只能接收调用方显式指定的截图，不能枚举证据目录或顺带上传 XML/manifest。证据响应
使用 `Cache-Control: no-store`，不能暴露为免登录静态目录。

内部截图存储采用以下固定边界：

- 单个 PNG 最大 10 MiB、单边最大 8192 px、总像素最大 16,777,216；同时验证 multipart MIME、
  PNG 魔数、完整解码、字节数、尺寸和调用方声明的 SHA-256。
- 上传 handler 必须先通过逐请求 SQLite 设备认证并再次校验规范 principal，再解析 Content-Type 或
  读取 body。空库、无效或已撤销凭据拒绝，认证存储故障返回 503；不把管理员 session 当设备身份。
- 首次 evidence INSERT 必须由 store 校验和 SQLite trigger 双重证明 `(task, attempt, authenticated device)`
  对应未关闭 claim。历史同设备/upload key 重放先于该检查，因此人工关闭 claim 不会破坏已提交资产的
  幂等读取；关闭后禁止新 upload key，且不为此增加 token/session 字段或放宽截图 kind。
- 文件写入显式配置的私有证据根目录：同目录随机临时文件 → 流式 hash → 校验 → `fsync` → 原子
  rename 到 SHA-256 内容地址 → 最后事务写数据库。数据库永远不指向半文件或缺失文件。
- SQLite 与文件系统不能组成跨资源事务；极端故障最多留下不可达孤儿文件。不得为清理孤儿而删除
  可能被其他资产记录并发复用的内容文件，自动保留/删除策略留给部署任务。
- SHA-256 只用于物理内容寻址，不是业务资产唯一键；不同合法证据可以引用相同内容。同设备主体与
  `upload_key` 同载荷重放原资产，任一规范字段变化即冲突。

## 六、关键技术难点

| 难点 | 风险 | 应对 |
| --- | --- | --- |
| 页面结构随版本变化 | 旧选择器误点新页面 | 每条判据先真机取证，记录 App 版本、截图、XML、goods_id |
| 购买语义入口才打开面板 | 能力范围易扩散 | 只批准证据绑定的精确唯一入口；每种文案单独取证 |
| 当前价与原价/按钮价混杂 | 读错价格 | Gate1/Gate2 只读顶部角色；Gate3 只读最终控件结构化金额，角色不互相兜底 |
| 单趟页面状态变化 | 数量或促销导致金额非线性变化 | 同一趟读 Gate1 单价与 Gate2 顶部总额，再要求最终控件 Gate3 金额与 Gate2 严格相等 |
| WiFi ADB / 双通道 | 断连或操作错设备 | serial 必填；USB/WiFi 同设备或身份不明时 fail closed |
| 不可逆动作超时 | 可能已创建订单 | 服务端围栏 + 点击一次 + 只调和，不重试 |
| 双端契约漂移 | 静默不兼容 | [api.md](api.md) 唯一权威；契约改动跑完整双端门禁 |

## 七、推荐开发顺序

1. **Phase 0 地基**：双端骨架、测试命令、初始化脚本和原型。
2. **Phase 1 真机取证**：逐段验证商品打开、受控面板入口、精确规格与读价、数量、最终提交面板和提交
   控件；真实点击前先完成独立 dry-run。每个 spike 的 capability 只覆盖当期动作。
3. **Phase 2 采购服务核心**：DRAFT 建单/列表、批量开始采购与授权、状态/证据/围栏/调和接口。
4. **Phase 3 双端打通**：设备身份、原子领取、单趟执行到围栏前、事件与截图。
5. **Phase 4 闭环**：经明确真机授权验证一次提交、待付款收口、失败分类、打包。
6. **V2**：图搜、Excel、ERP、自动核对、AI、多设备。

T-103 继续作为“规格选择与读价”的隔离前置，不含数量、最终提交面板或提交。生产单趟并不意味着在一个
任务里跳过逐段取证；它只意味着这些已验证能力集成后，每笔业务任务不再等待中途人工确认。

## 八、项目结构

```text
cmbuyer/
├── docs/
├── admin/
│   ├── cmd/server/
│   ├── internal/domain/
│   ├── internal/usecase/
│   ├── internal/transport/httpapi/
│   ├── internal/transport/webui/
│   ├── internal/storage/
│   └── migrations/
├── client/
│   ├── src/cmbuyer_client/device/
│   ├── src/cmbuyer_client/pdd/
│   ├── src/cmbuyer_client/core/
│   ├── src/cmbuyer_client/remote/
│   ├── src/cmbuyer_client/app/
│   └── tests/
└── scripts/
```

执行器依赖核心端口，不直接读取 Excel 或拼接 HTTP。T-303 只提供 `TaskSource` / `EvidenceSink`；完整
`ResultSink` 在服务端 events/fail/fence/result 契约落地后分阶段组合，来源变化不得改变安全执行器。

## 九、架构纪律

- 业务事实和 schema 变化同步本文与 [api.md](api.md)，代码不得另起一套字段或状态。
- 第四节安全边界只能收紧。需要变更时先更新架构、任务边界和理由。
- 页面高风险能力先真机取证并隔离测试，再接入完整流程。
- 前序项目 `cmroubao` / `cmpdd` 只提供设计理由，不提供可直接复用的页面事实。