---
id: T-220
title: 顺运宝 ERP 字段契约与凭证安全基线
phase: 2
deps:
  - T-219
status: DONE
created: 2026-07-28
context_ref: 78dc595
work_branch: null
write_paths:
  - .gitignore
  - shunyunbaoerp_single.py
  - docs/integrations/**
  - docs/tasks/T-220.md
  - docs/current-state.md
---

## 问题 / 背景

采购资料将以顺运宝 ERP 货运单为主要来源。现有单文件脚本证明了验证码登录、
Cookie 会话、按“全部单号”查询、按 stock id 批量读取详情的协议，但运行入口含
明文账号/密码/订单号，并会把完整结果写文件、打印到终端。货运响应包含收件人、
电话、地址、金额和商品信息，不能直接进入 Git、普通日志、VLM 或采购任务。

ERP 详情的 `details[]` 才是商品级来源；一个货运头可能有多个明细。必须先冻结
`stock.id -> detail.id -> details[].id` 的身份和字段映射，再开发导入链路。

## 关联需求与交互

- 功能：F-011、F-012
- 用户故事：US-011、US-012
- 交互：IX-012、IX-013
- 架构/API：ERP Connector、货运来源数据模型和内部安全边界

## 方案

1. 清除单文件脚本中的明文账号、密码和固定订单号，只允许环境变量或交互输入。
2. 查询结果默认只写被忽略的 `.local/`，控制台只输出数量和匿名结果文件位置。
3. 新增顺运宝集成字段契约，记录已由本地 HAR/脱敏结构确认的端点、查询关系和字段，
   不复制 HAR、Cookie、JWT、真实订单号或个人信息。
4. 定义最小规范化对象：
   - 货运单身份：`source_system + stock.id`
   - 商品明细身份：`source_system + stock.id + details[].id`
   - 待采购字段：标题、原始规格、`sku/variationSku`、正整数数量、`productThumb`
     引用、采购状态和来源内容 hash
5. `productThumb` 当前只确认是 ERP 引用值，不猜测为公开 URL；图片未解析时必须
   `NEEDS_IMAGE`，禁止生成采购任务。
6. 私有 HAR、验证码、查询结果、ERP session 和 connector 环境文件进入忽略规则。

## 验收要点

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

## 边界

- 不提交本地 HAR 和 `freight_detail.json`。
- 不在本任务启动 connector、写数据库或创建采购任务。
- 不解释未确认的 ERP 数字状态含义，不自动 OCR 绕过验证码。
- 不因字段缺失猜测标题、SKU、数量或图片。

## 执行记录

- 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。