Table of Contents
同步来源：
docs/integrations/shunyunbao-contract.md· commitafc651f75a3a
顺运宝 ERP 字段契约
本文只记录协议结构和字段语义，不保存真实账号、Cookie、JWT、订单号、收件人、 电话、地址、商品内容或原始响应。私有 HAR/响应只允许位于被 Git 忽略的本地目录。
已确认请求链
- 同一 HTTP Session 获取
GET /api/p/code1验证码。 POST /am/auth/login提交环境变量提供的账号/密码和受控验证码。- 从登录
data.user读取正整数id和非空username，以同一 Cookie Session 调用GET /am/user/get?id=<user.id>；返回身份必须完全一致。 POST /am/stock/listTotal与/am/stock/list使用“全部单号”条件查询。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。生产使用前必须确认厂商授权、请求 频率、服务账号和个人信息处理规则。
Go 直连迁移契约（T-225）
T-225 至 T-227 在 backend-api/internal/platform/shunyunbao 用脱敏 fixture 固定以下
内容，并由 API 进程内的 Go source 直接执行：
- 基础请求 header 固定
Accept、Origin、Referer、User-Agent和X-Requested-With；base URL 必须是无 userinfo、query、fragment 或路径的 origin。 - 单号条件为
t_stock.allcode、op=6、type=0、optType=1；日期范围为t_stock.created、op=0、type=3、optType=0，单个 ERP 窗口最多 7 个自然日。 listTotal、list共享history=0、length、start、pageIndex、store=false、 已验证 columns 和单一queries；运行时每页固定 20 条、单次最多 100 条。listByStock?hist=0每批最多 100 个去重后的正整数 stock id，详情id必须与列表stock.id一致。- 所有结果必须经 Go allowlist 归一化；fixture 专门含收件信息、Cookie/JWT 标记值， 测试断言它们不会出现在输出或错误里。
Go 直连的验证码、登录、Cookie jar 和查询 source 都在 API 进程内。T-230 在未认证时只可将
验证码图片提交给受控本机/HTTPS OCR endpoint，结果只用于当前登录请求；不得写入 Redis、
SQLite、普通日志或浏览器。T-236 仅在 ERP 登录精确返回“图片验证码不正确”时，在首次失败后
额外重试最多 6 次；每次重新获取验证码和调用 OCR，最多 7 次登录且认证总预算为 20 秒。其他
登录拒绝、OCR、网络或协议错误不重试。T-234 仅允许显式 diagnostics 进程短时输出有效 OCR
文本和固定登录尝试分类；T-235 仅在受锁内存中保存已核验 user id/username，不保存登录 token。
HTTP 401/403 或 ERP code -2 才代表会话失效；其他非登录接口 status=false 是协议错误。
真实线上请求不属于自动化测试。
身份和规范字段
货运单
| 规范字段 | 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。