chore(t220): secure erp contract baseline

2026-07-28 22:43:47 +08:00
parent cc847c9aed
commit 305dd9f513
6 changed files with 1078 additions and 13 deletions
@@ -5,7 +5,7 @@
 ## 当前快照

 - 日期：2026-07-28
- 阶段：T-220 顺运宝 ERP 字段契约与凭证安全基线已领取
+- 阶段：T-220 已完成，T-221 顺运宝精确单号 Connector 已领取
 - Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 至 T-219
  均按文档提交、实现提交的顺序纳入历史
 - 生产代码：`android-buyer/` 已接入 Roubao Android 源码
@@ -151,8 +151,8 @@
 | `docs/tasks/T-217.md` | DONE | 重新核对已授权商品并选择 SKU/数量，停在最终提交前 |
 | `docs/tasks/T-218.md` | DONE | 单次提交围栏、最多一次提交动作和待付款订单唯一对账 |
 | `docs/tasks/T-219.md` | DONE | Admin 待付款提醒、Roubao 终态和跨端闭环验收 |
-| `docs/tasks/T-220.md` | DOING | 顺运宝 ERP 字段契约与凭证安全基线 |
-| `docs/tasks/T-221.md` | TODO | 顺运宝精确单号 Connector |
+| `docs/tasks/T-220.md` | DONE | 顺运宝 ERP 字段契约与凭证安全基线 |
+| `docs/tasks/T-221.md` | DOING | 顺运宝精确单号 Connector |
 | `docs/tasks/T-222.md` | TODO | 货运信息存储、API 与 Admin 页面 |
 | `docs/tasks/T-223.md` | TODO | 待采购需求提取与任务生成 |
 | `docs/tasks/T-224.md` | TODO | ERP 日期增量同步 |
@@ -167,9 +167,10 @@
 ## 任务摘要

 - 已完成：T-001 至 T-004、T-101 至 T-104、T-201 至 T-219。
- 进行中：T-220 顺运宝 ERP 字段契约与凭证安全基线。
- 下一步：依次完成 T-221 精确单号 Connector、T-222 货运模块、T-223 采购需求生成
-  和 T-224 日期增量同步，再进入 T-301 P0 UI 完整交互验收。
+- 已完成：另含 T-220 顺运宝 ERP 字段契约与凭证安全基线。
+- 进行中：T-221 顺运宝精确单号 Connector。
+- 下一步：完成 T-222 货运模块、T-223 采购需求生成和 T-224 日期增量同步，再进入
+  T-301 P0 UI 完整交互验收。

 ## 当前可运行内容

@@ -0,0 +1,72 @@
+# 顺运宝 ERP 字段契约
+
+> 本文只记录协议结构和字段语义，不保存真实账号、Cookie、JWT、订单号、收件人、
+> 电话、地址、商品内容或原始响应。私有 HAR/响应只允许位于被 Git 忽略的本地目录。
+
+## 已确认请求链
+
+1. 同一 HTTP Session 获取 `GET /api/p/code1` 验证码。
+2. `POST /am/auth/login` 提交环境变量提供的账号/密码和受控验证码。
+3. `POST /am/stock/listTotal` 与 `/am/stock/list` 使用“全部单号”条件查询。
+4. `POST /am/stock/detail/listByStock?hist=0` 使用列表 `stock.id` 批量读取详情。
+
+本地 HAR 结构确认：
+
+- “全部单号”查询输入匹配列表 `code`，不保证等于 `orderCode`。
+- 列表 `id` 等于详情请求 `ids[]` 使用的 stock id，也等于详情头 `id`。
+- 详情头 `details[]` 是商品级集合，一个货运单可以有多条商品。
+- 日期区间使用 `t_stock.created`、`op=0`、`type=3`、`optType=0`；具体增量规则属于
+  T-224。
+
+接口来自 ERP 页面协议，不是已确认的开放 API。生产使用前必须确认厂商授权、请求
+频率、服务账号和个人信息处理规则。
+
+## 身份和规范字段
+
+### 货运单
+
+| 规范字段 | ERP 来源 | 规则 |
+| --- | --- | --- |
+| `external_stock_id` | `stock.id` / `detail.id` | 必填正整数，字符串化保存；唯一外部身份 |
+| `source_code` | `stock.code` | 受控展示；查询输入不作为主键 |
+| `platform_order_no` | `stock.orderCode` | 可空，不进入 URL/普通日志 |
+| `shop_name` | `detail.shopName`，回退 `stock.shopName` | 可空，限制长度 |
+| `source_created_at` | `detail.created`，回退 `stock.created` | 必须可解析为 ERP 本地时间 |
+| `order_status` | `stock.orderStatus` / `detail.status` | 原值字符串化，不猜测数字语义 |
+| `purchase_status` | `stock.purchaseStatus` | 原值字符串化，不自动决定采购 |
+| `is_canceled` | `stock.isCancel` | 只接受明确布尔/已确认枚举 |
+
+### 商品明细
+
+| 规范字段 | ERP 来源 | 规则 |
+| --- | --- | --- |
+| `external_item_id` | `detail.details[].id` | 必填正整数；在货运单内唯一 |
+| `title` | `productTitle`，可核对回退 `detailProductName` | 去首尾空白；空值进入复核 |
+| `product_spec` | `productSpec` | 原样保留，不由 VLM 改写 |
+| `sku` | 非空 `sku`，否则 `variationSku` | 仍需 Admin 复核；两者都空时阻塞 |
+| `quantity` | `productQty` | 必须为正整数，不能使用货运头总数量代替 |
+| `product_thumb_ref` | `productThumb` | 当前确认可能为数字 ERP 引用，不是 URL |
+| `purchase_status` | `purchaseStatus` | 原值字符串化，允许值另行确认 |
+
+`productThumb` 未解析为可鉴权图片内容前，商品状态必须是 `NEEDS_IMAGE`。系统不得把
+数字引用拼接成 URL、抓取未知主机或用其他商品图片补位。
+
+## 规范化与版本
+
+- canonical JSON 固定 UTF-8、字段顺序和空值规则；对最小化对象计算 SHA-256。
+- `(creator, SHUNYUNBAO, external_stock_id)` 唯一确定货运单。
+- `(freight_order_id, external_item_id)` 唯一确定商品。
+- hash 不变是幂等重放；hash 变化递增 revision，不覆盖已生成采购任务。
+- 同一响应含重复 external item id 且内容不一致时整批失败，不选择其中一条。
+- 缺失详情头、`details` 不是数组或任一商品没有外部 ID时整批失败，不保存半批。
+
+## 数据最小化
+
+以下字段不得进入本项目数据库、业务响应、普通日志、任务、VLM 或 Git：
+
+- `receiver`、`receiverTel`、`receiverAddr` 和其他收件个人信息。
+- ERP username/password、验证码、Cookie、JWT、权限和完整用户资料。
+- 未裁剪的 `stock`、`detail`、HAR、HTTP body 和 Redis session JSON。
+
+允许保存的审计信息是：source system、外部 ID、规范字段 hash、同步状态、稳定错误码、
+数量和时间。错误信息不得拼接 ERP 原始 body。
@@ -4,7 +4,7 @@ title: 顺运宝 ERP 字段契约与凭证安全基线
 phase: 2
 deps:
  - T-219
-status: DOING
+status: DONE
 created: 2026-07-28
 context_ref: 78dc595
 work_branch: null
@@ -50,10 +50,10 @@ ERP 详情的 `details[]` 才是商品级来源；一个货运头可能有多个

 ## 验收要点

- [ ] Git 跟踪内容不含 ERP 账号、密码、Cookie、JWT、真实单号和货运 PII。
- [ ] 单文件脚本无硬编码凭证/订单号，不再向 stdout 输出完整响应。
- [ ] 字段契约覆盖一货运头多商品、重复同步、缺详情、缺图片和来源更新。
- [ ] 可用静态命令证明脚本可编译，安全扫描和仓库根验证通过；不访问线上 ERP。
+- [x] Git 跟踪内容不含 ERP 账号、密码、Cookie、JWT、真实单号和货运 PII。
+- [x] 单文件脚本无硬编码凭证/订单号，不再向 stdout 输出完整响应。
+- [x] 字段契约覆盖一货运头多商品、重复同步、缺详情、缺图片和来源更新。
+- [x] 可用静态命令证明脚本可编译，安全扫描和仓库根验证通过；不访问线上 ERP。

 ## 边界

@@ -66,3 +66,11 @@ ERP 详情的 `details[]` 才是商品级来源；一个货运头可能有多个

 - 2026-07-28：在 T-219 `78dc595` 后领取。静态读取本机单文件和独立 ERP 参考工程；
  只提取协议结构和字段名，没有执行登录、线上查询或写操作。
+- 2026-07-28：任务合约提交 `cc847c9`。新增
+  `docs/integrations/shunyunbao-contract.md`，冻结 stock/detail/item 身份、最小字段、
+  canonical hash、PII 排除和缺图边界；私有 HAR/响应没有复制进仓库。
+- 2026-07-28：`shunyunbaoerp_single.py` 已移除硬编码账号、密码和订单号，改为环境
+  变量/交互输入；验证码与结果默认写 `.local/shunyunbao/`，stdout 不再输出 OCR
+  文本或完整货运响应。`.gitignore` 增加 HAR、验证码、查询结果和 Python 输出。
+- 2026-07-28：`python -m py_compile .\shunyunbaoerp_single.py`、离线 payload smoke、
+  Python AST 凭证/订单字面量扫描和根 `.\init.ps1` 通过。未访问线上 ERP。
@@ -4,7 +4,7 @@ title: 顺运宝精确单号 Connector
 phase: 2
 deps:
  - T-220
-status: TODO
+status: DOING
 created: 2026-07-28
 context_ref: 78dc595
 work_branch: null
@@ -57,4 +57,4 @@ Go 后端不应在 Gin 请求里启动 Python，也不应保存 ERP 密码、Coo

 ## 执行记录

- 2026-07-28：任务合约已冻结，等待 T-220。
+- 2026-07-28：任务合约已冻结；T-220 完成后领取。