cmroubao/docs/integrations/shunyunbao-contract.md

顺运宝 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。