生产实测:1688 单的 `OutChannel=thyny`(密文淘宝分销单,订单号形如 5127404439433014429) 没有进渠道映射表,落库成了「其他(OTHER)」,取号时匹配不到菜鸟模板 (2 单:dgj-10000290937711 等)。业务确认 thyny 就是淘宝分销渠道。 - DISTRIBUTE_CHANNEL_PLATFORM 增加 thyny → TB - 单测:密文 thyny → TB / 淘宝;未识别渠道改用 chaoshibianli → OTHER(thyny 已有映射) - 文档 §4.2 换算表、§4.2.6「已确认的渠道映射」、.github/copilot-instructions.md 同步 存量:这 2 单重新拉单即从 OTHER 变成淘宝,可用 YUNDA(TB → 12362952 菜鸟韵达一联4)取号。 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
61 KiB
店管家取号:旧系统流程提取 & OMS 落地
来源:旧系统
D:\ye4s.wms.gztbyc.com\application\index\controller\wms\Dianguanjia.php(ThinkPHP,ExpressPrint()/CheckTemplateAvaliable()/Print()/sendProxyRequest()等) 目标:把「分配快递号(取号)」的完整流程提取出来,供 OMS 实现dgj.fetchWaybillNo()。 ⚠️ ExpressPrint 会真实消耗面单并产生费用,任何真实订单测试必须由业务手工触发。
1. 结论(TL;DR)
- 取号 =
POST /TemplateSet/CheckTemplateAvaliable(校验/余额,只读)+POST /NewOrder/ExpressPrint(取号 + 打印数据)。 - 前提是先从
POST /NewOrder/List拿到平台订单行(Id / LogicOrderId / ShopId / SubOrders…)。 - 订单接口与模板接口不在同一域名(踩坑点,见 §2)。
- 旧系统在平台已有运单号(
LastWaybillCode)时会直接复用;OMS 不采用该判断,每次都真实取号,去重只靠幂等表request_id。 - OMS 已实现(
backend/app/lib/printPlatform/dgj.js),默认开启真实取号(会调用 ExpressPrint 消耗面单);需要只读联调时用DGJ_WAYBILL_ENABLE=0关闭,并提供手工验证脚本。
2. 关键坑:订单域名 ≠ 模板域名
旧系统 $this->pingtais 把「平台 ID → 域名」映射为:
| 平台 | 旧系统域名 | 说明 |
|---|---|---|
| 淘宝 / 1688 / 视频号(WxVideo) / 小红书 / 快手 | fxali.dgjapp.com |
订单与取号都在这里 |
| 抖店(TouTiao) | fxdd.dgjapp.com |
|
| 拼多多 | fxpdd.dgjapp.com |
|
| 京东 | fxjd.dgjapp.com |
而面单模板接口走的是模板域名(OMS 现有 TEMPLATE_PLATFORMS:视频号模板在 fxdd)。
实测:订单 dgj-10000266092590(视频号)在 fxdd 查不到,在 fxali 一次命中 —— 取号必须用订单域名。
OMS 实现:resolveOrderHost(platformType)(dgj.js 顶部 ORDER_HOSTS,兜底 fxali),与 resolveTemplateHost 分开。
2.1 发货接口:POST /NewOrder/OnlineSend(同步发货)
OMS 的订单被 WMS 回传 deliveryorder.confirm 流转到「配送」后,需要把发货结果同步回店管家,平台才会把订单状态推进为「已发货」。
接口与取号同域(走订单域名,见上表),不消耗面单。
⚠️ 2026-11-07 抓包更正:真实接口是 /NewOrder/OnlineSend(不是 OnlineSendBatch),
且平台页面把整行订单模型都带上,顶层还必须带 TemplateId / ExpressCompanyId;
只发 Orders(旧实现)平台会回「请先勾选要发货的订单」。
实测请求(浏览器「待打订单 → 发货」):
TemplateId=10824270 ExpressCompanyId=8
ExcludeOrders[productItemCount]=1 ExcludeOrders[productCount]=1
NoLogisticsInfoModel= IsSendPreCheck=true IsContinueForStock=false
RequestBatchNumber=1/1/20261107080668392473417 IsCustomerOrder=false FxPageType=2
Orders[0][Id] / [Index] / [LogicOrderId] / [PlatformOrderId](= 系统编号)/ [PathFlowCode]
Orders[0][CustomerOrderId](= 平台单号)/ [PlatformType]=Alibaba / [PlatformTypeName]=1688
Orders[0][ShopId] / [ShopName] / [PlatformStatus]=waitsellersend / [RefunStatus]=
Orders[0][FxUserId] / [UpFxUserId](分销场景 ≠ FxUserId,必须透传平台值)
Orders[0][ExpressPrintTime] / [PayTime] / [MergeredType] / [LogisticStatus] / [DataFlag] / [PrintState]
Orders[0][ShippingType](平台给的加密串,原样带回)/ [ExtField1] / [ExtField2] / [SellerRemarkFlagTag]
Orders[0][OrderTags][n][...](分销渠道等标签,整块透传)
Orders[0][WaybillCode] / [ExpressCompanyCode] / [WaybillCodeUniqueKey] / [weight]=0
Orders[0][WaybillCodes][0][...](含 WaybillCodeId / Pid / ExpressCpCode / IsSended)
Orders[0][SubOrders][0][...](整块透传)
Orders[0][Items][n][OrderItemId/OrderItemCode/Quantity/SkuCode/ProductCode/OrderItemIdStr]
Orders[0][OrderItems][] / [OrderItemStrList][]
Orders[0][Receiver][ToProvince/ToCity/ToCounty/ToMaskAddress/ToName/ToMobile/ToAddress/toFullName/toArea]
Orders[0][Sender][SenderCompany/CompanyName] / [ReceiverIsEmpty]=0 / [PrintInfo]= / [NoPrintFlag]=false
响应是「整包 Success + Data.Orders[] 逐单结果」,必须看逐单 IsSuccess:
{"Success":true,"ErrorCode":"200","Data":{"Orders":[{"LogicOrderId":10000280844952,"IsSuccess":false,
"ErrorMessage":"订单不是待发货状态,请检查"}]}}
OMS 口径:逐单 IsSuccess=false 时,除「不是待发货 / 已发货 / 已取消 / 已关闭」(幂等,视为已同步)外都算失败。
整包层面也有一种幂等:单包裹发送时若平台整包回
{"Success":false,"Message":"存在不是待发货的商品,发货失败;"},说明这一单平台侧已不在待发货
(已发货/已取消),同样按已同步处理(dgj.sendOrders 直接返回,不发异常),否则会被重试 3 次打成「同步异常」。
⚠️ 这条提示两种形态都出现过(口径统一用 SEND_ALREADY_DONE_PATTERN 判):
| 形态 | 报文 |
|---|---|
| 整包失败 | {"Success":false,"Message":"存在不是待发货的商品,发货失败;"} |
| 逐单失败 | {"Success":true,"Data":{"Orders":[{"IsSuccess":false,"ErrorMessage":"存在不是待发货的商品,发货失败;"}]}} |
逐单形态平台常不回 LogicOrderId,旧实现会拼成 店管家发货同步失败:: 存在不是待发货的商品…(注意双冒号)——
看到这种双冒号就是走到了逐单分支。现在逐单失败且无单号时不再拼前缀。
OMS 实现:
| 位置 | 作用 |
|---|---|
lib/dgjSendRow.js#buildSendRow |
用本地快照拼订单行(不访问平台):快照 orders.external_data(PathFlowCode/ShippingType/OrderTags/SubOrders)+ 状态表(收件人/平台单号/运单号)+ 最近一次成功取号记录(WaybillCodeId/Pid/ExpressCpCode) |
dgj.sendOrders(host, { traceId, dbname, rows, templateId, expressCompanyId, expressCode }) |
按上面口径组装并提交;整包或逐单失败抛「店管家发货同步失败:…」 |
service/externalSendSync.js |
配送后同步的状态机(待同步 → 已同步 / 待重试 → 3 次转异常);快照缺失时才回读平台订单行兜底 |
发货模板必须按运单实际快递定位(2026-11-07 生产故障):
线上报过 店管家发货同步失败:10000280844951: 风控拦截#CONSIGN_RISK_CONTROL_BLOCK#风控拦截# NOT_MATCH_SEGMENT_CHANNEL#…此运单号非抖音的运单号…。
原因是发货模板取错:旧实现按「账号 + 平台」取第一条快递接口(order by id ASC),
抖音小店的第一条恰好是中通模板,而运单是申通(77035741…)。店管家把
TemplateId / ExpressCompanyId / ExpressCompanyCode 透传给平台,
抖音按模板的电子面单渠道去校验运单号 → 运单不在该渠道的号池里,直接风控拦截。
修正口径(与取号完全一致):
| 步骤 | 取值 |
|---|---|
| 本单运单号 | order_status_delivery.express_codes(JSON 数组,多包裹会有多个)+ express_code;注意这两列存的是运单号,快递编码在 logistics_code |
| 取号记录 | 必须和运单号对上:按 express_codes 里的号逐条匹配 waybill_fetch_records.waybill_code / waybill_codes,主运单优先;同一单取过多次号时只会命中真正要发出去的那张(对不上就返回 null,不拿别人的面单) |
| 运单快递 | 命中记录的 express_code → 兜底 logistics_code |
| 模板定位 | externalPrintExpressInterface.resolveByCode(账号, {平台编码, 快递编码})(显式绑定)→ 模板自带 express_company_code 匹配 → 该平台第一条(保留历史行为并 warn) |
| 面单快照 | WaybillCodes[].ExpressCpCode 优先用取号记录的快递编码,模板编码只做兜底 |
订单号前缀匹配也做了转义(LIKE '...\\_%'),避免 ..._1 误匹配到 ..._10 这类别的单。
验证(本地库真实数据):快手单 dgj-10000267890142_1 的运单 772085332374413 是申通,
旧逻辑命中模板 #17 / YUNDA(圆通),修正后命中 #29 / STO(申通),
拼出的报文 ExpressCompanyCode=STO、WaybillCodes[0].ExpressCpCode=STO;
抖音四张模板也能按快递分别命中(STO→10776786 / ZTO→13987231 / YUNDA→12360764 / POSTB→12712711)。
取号记录按运单号匹配的实测(同一单有 4 条不同运单号的取号记录 11~14):
| 配送单运单号 | 命中记录 | 说明 |
|---|---|---|
| 772085332374413 | #14(最新) |
正常命中 |
| 772085215446719 | #13(更早) |
不再无脑取最新那条 |
| 760000000000000(不存在) | 无 | 返回 null 并 warn,报文不带别人的面单标识 |
请求量控制(避免被平台判成刷单/攻击,以及服务商级 QPS 限流):
店管家对请求量有两道闸:风控/刷单判定(行为特征)和 服务商级 QPS 限流
(实测返回 isv.request-limited 请求太频繁…配置限流QPS:600, 当前访问QPS:687)。
后者是全 ISV 共享的额度,我们自己的突发只是其中一部分,所以既要把自己的峰值削平,
也要在被限流时退避重试而不是直接判失败。
| 手段 | 说明 |
|---|---|
| 拉单分页 500 | ORDER_PAGE_SIZE = 500(平台分页上限),/NewOrder/List 一页拿满,避免逐页请求把 QPS 打满;fetchOrdersByIds 的 PageSize 也封顶 500 |
| 商品分页 500 | PRODUCT_PAGE_SIZE = 500(原 200):/Product/LoadList 同样按上限拉;平台若自行封顶也不影响正确性——分页按 PageIndex 递增,fetchAreaSnapshot 用「去重商品数 = Total」校验完整性 |
| 全局请求间隔 | dgj.request() 是所有平台调用的唯一出口,统一排队:相邻两次请求至少间隔 DGJ_REQUEST_INTERVAL_MS(默认 100ms → 单进程约 10 请求/秒) |
| 限流自动退避 | postPlatformForm()(订单/模板校验/取号/发货/回读都走它)命中 isv.request-limited / 请求太频繁 / 访问QPS 时自动退避重试:DGJ_RATE_LIMIT_RETRY(默认 3 次)、DGJ_RATE_LIMIT_BACKOFF_MS(默认 1000ms,指数退避);仍限流则抛「店管家接口限流:…;已自动退避重试 N 次仍被限流,请稍后重试」 |
| 取号并发 | WAYBILL_CONCURRENCY(默认 2,原 4):批量取号每单要 3 次平台调用(回读订单 + 模板校验 + ExpressPrint),并发越低突发越平 |
| 发货不回读订单行 | 快照拼报文,每单只有 1 次 POST /NewOrder/OnlineSend;平台判报文无效时才回读平台实时订单行重发一次(见 §2.1.1) |
| 发货逐单间隔 | 同批相邻两单之间 EXTERNAL_SEND_INTERVAL_MS(默认 300ms) |
| 发货限流不计次 | 平台限流不是这单的问题:external_send_status 保持「待重试」,不累加 external_send_times,等下一轮调度(2 分钟)再试,避免一批单被打成「异常」 |
| traceId 缓存 | getUserInfo 按账号缓存(批量内只调 1 次);dgj.resolveTraceId() 实例级缓存 5 分钟 |
| 模板校验不缓存 | CheckTemplateAvaliable 返回的 DateNow / DayPrintBatchNumber 会拼进 RequestBatchNumber,属于单次打印批次标识,跨单复用有风险,因此不做缓存 |
2.1.1 发货 500(店管家发货同步失败:12;ErrorCode=500)的定位与兜底
2026-11-07 线上「意洁」全部订单发货回传失败,错误文案只有 12;ErrorCode=500(平台没给可读原因)。
用同一个账号直接对平台做对照实验(真实订单,2026-11-07):
| 报文来源 | 平台结果 |
|---|---|
平台实时订单行(/NewOrder/List 取回的原样行) |
Success:true + 逐单 IsSuccess:true,发货成功 |
本地快照行但把 SubOrders 清空 |
{"Success":false,"ErrorCode":"500","Message":"服务器繁忙,请稍会儿再试."} |
本地快照行但把 WaybillCodes 清空 |
{"Success":false,"Message":"当前选中的订单都没有打印,已取消发货"}(业务类,不是 500) |
结论:500 是"平台没能解析订单报文",不是订单状态问题。平台按 Orders[i][SubOrders]
校验收件人与商品明细,SubOrders 缺失/老化(拉单快照过期、只存了归一化数据)就会直接 500,
且文案可能是「服务器繁忙」也可能只回一串数字(如 12)。
兜底(service/externalSendSync):
resolveSendRow拼完本地行先做完整性校验:SubOrders为空就不用它,改回读平台实时订单行(warn留痕);syncOrder捕获到报文类失败(lib/platformError.isPayloadRejected:ErrorCode>=500/ 服务器繁忙 / 系统异常 /Message只有一串数字)时, 用forceRemote重新回读订单行并重发一次,成功即置「已同步」;- 仍失败时把平台原始返回写进日志(
平台原始返回:{…}),订单页只留可读文案。
判定口径刻意排除业务类失败:「不是待发货状态」「当前选中的订单都没有打印」「风控拦截」「请先勾选要发货的订单」 以及限流文案——这些重发也没用,按原逻辑计数/提示。
2.1.2 发货 500「Message=12」的真凶:用了模板记录的 dbname
2026-11-07 线上「意洁」整批回传失败,文案固定是 店管家发货同步失败:12;ErrorCode=500。
对同一单、同一域名 fxdd、同一模板 12360764 只改 dbname 做对照(该单平台侧已发货,正确报文只会回「不是待发货」):
请求带的 dbname |
平台响应 |
|---|---|
y/2wUDWCZOk=(模板记录 external_print_express_interfaces.dbname) |
{"Success":false,"ErrorCode":"500","Message":"12"} ← 线上同款 |
''(host 默认区) |
存在不是待发货的商品,发货失败(业务类,正常) |
dzh93a8yur84Y3Yln2ha9RbPovVMhBTc(取号记录 dbname) |
存在不是待发货的商品,发货失败(业务类,正常) |
根因:externalSendSync.resolveTarget 之前把模板记录的 dbname 当成订单分区回传发货。
模板的 dbname 是「模板接口」用的区(同一账号所有模板都是同一个值),拿它去发订单,
平台在错的区里解析 Orders[i] → 抛 500,只回一串数字,看起来像报文缺字段。
修正口径(resolveTarget):
| 用途 | 取值 |
|---|---|
| 回传发货 / 回读订单行 | 取号记录 waybill_fetch_records.dbname(取号就在那一区成功);没有取号记录时用 ''(host 默认区) |
| 模板同步 / 模板查询 | 仍用模板记录的 dbname(那是模板接口的区,两者不要混用) |
因此 §2.1.1 的「改用实时订单行重试」只有在 dbname 正确后才有意义——之前回读订单行也在错的区,拿不到行。
修正后同一批单的返回变成 存在不是待发货的商品,发货失败;(业务类),这类按幂等处理即「已同步」,
见 §2.1 的 OMS 口径。
失败单不转表:进了配送说明仓库已打包发货,是既成事实,必须留在配送表可见/可导出;
只在配送表标记 external_send_status(2 待重试 / 3 同步异常),由「配送异常」视图筛出来处理。
表变大靠索引和归档兜底:
| 措施 | 说明 |
|---|---|
| 索引 | idx_delivery_external_send_status (principal_id, external_send_status) 覆盖列表筛选;idx_delivery_send_scan (external_send_status, external_send_at) 覆盖定时任务扫描 |
| 归档 | 超期(默认 3 个月,ORDER_ARCHIVE_MONTHS)自动转「历史」表,仍可查可导 |
状态字段(配送表 order_status_delivery,所有状态表 + 历史表同构):
| 字段 | 说明 |
|---|---|
external_send_status |
0待同步 1已同步 2同步失败待重试 3异常(重试超限) |
external_send_times |
已尝试次数(≥3 转异常) |
external_send_error |
最近一次失败原因 |
external_send_at / external_sent_at |
最近尝试时间 / 同步成功时间 |
存量配送单在迁移
20261104050100里统一回填为「已同步」,避免上线后把历史订单重新通知平台发货。
3. 完整取号流程
① POST /NewOrder/List 回读平台订单行(只读)
└─ 命中后拿到 Id / LogicOrderId / ShopId / FxUserId / SubOrders / LastWaybillCode
② 已发货/已终结(isOrderFinished) → 直接失败:该单应作废/取消,不能再取号
└─ 旧系统会「平台已有运单号就直接复用」;**OMS 不采用**:
重复调用与否只由幂等表(request_id)决定,每次都真实取号,LastWaybillCode 仅用于事后对比是否换号
③ POST /TemplateSet/CheckTemplateAvaliable (只读)
└─ 返回 Data.Balance / PrintCount / DateNow / DayPrintBatchNumber / Branches
└─ Balance < PrintCount → 「余额不足」,旧系统发企业微信告警并中止
④ POST /NewOrder/ExpressPrint (!! 消耗面单)
└─ 返回 Data.WaybillCode[],逐单 IsError / PrintInfo(打印数据,内含 documentID = 运单号)
4. 各接口细节(照旧系统抄)
4.1 公共约定
- query:
token=<账号 token>&traceId=<登录上下文 traceId>&dbname=<分区库>&dataFlag= - body:
application/x-www-form-urlencoded,数组按Orders[0]=<JSON>形式(PHPhttp_build_query) - headers:
Cookie、X-Requested-With: XMLHttpRequest、Origin、Referer: https://<host>/NewOrder/WaitOrder、User-Agent - 旧系统 dbname 写死
wdJM8OZZiF4gKKxb82bFQlqydSPSQ9/W(那是老账号的分区); OMS 按店铺分区的dbname(实测y/2wUDWCZOk=可用),两者不可混用。
4.2 订单行:POST /NewOrder/List
- Filter(可精确命中,实测有效):
Filters[0][TableAlias]=o Filters[0][FieldType]=string Filters[0][TableName]=LogicOrder Filters[0][Name]=LogicOrderId Filters[0][Value]=10000266092590 Filters[0][Contract]=in PlatformOrderId过滤需要额外Filters[0][CustomQuery]=PlatformOrderIdSearch(旧系统写法)。- 其余字段:
PageSize=20、PageIndex=1、OrderByField=o.CreateTime、requestUrl=https://<host>/NewOrder/WaitOrder、FxPageType=2。 - 兜底:按
CreateTime时间窗(±2 天)翻页扫描后本地匹配LogicOrderId。
4.2.1 拉单用的过滤条件(对照平台「待发货订单」页抓包,实测)
平台订单页自己发出的请求是「时间窗 + 订单状态」两个 Filter:
Filters[0] TableAlias=o FieldType=DateTime TableName=LogicOrder Name=CreateTime Value=<起> ExtValue=<止> Contract=between
Filters[1] TableAlias=o FieldType=string TableName=LogicOrder Name=ErpState Value=waitsellersend Contract==
⚠️ 上一行的
Contract=只有一个等号,抓包里是Filters[1][Contract]=%3D(即=)。 2026-11-07 线上「抖音平台的订单拉取不到」就是这个符号写错导致的: OMS 早期按Contract: '=='发,抖店老分区直接回「服务器繁忙,请稍会儿再试」, 被误判成「该分区不支持过滤」→ 退化全量拉取 → 而平台全量列表里不含待发货单, 于是抖店 6 单待发货怎么都拉不到。改成=后同一分区立刻返回 6 单。 单测见test/app/lib/dgjOrderQuery.test.js(断言ErpState:=)。
按商家(店铺)过滤时平台再加一个 Filter(值就是商家的 FxUserId,与 shops.external_data.FxUserId 一致):
Filters[2] TableAlias=pfn FieldType=int TableName=PathFlowNode Name=UpFxUserId Value=1327427 Contract=in
实测(2026-11-07,账号 15197817068)三个分区都支持「待发货 + 商家」过滤:
| 分区 | 仅状态过滤 | 状态 + 商家 in | 状态 + 商家 = |
|---|---|---|---|
抖店-186 dzh93a8yur84Y3Yln2ha9RbPovVMhBTc |
6 单 | 6 单 | 6 单 |
新系统区 y/2wUDWCZOk= |
0 单 | 0 单 | 0 单 |
精选平台四区 wdJM8OZZiF4gKKxb82bFQlqydSPSQ9/W |
6 单 | 6 单 | 6 单 |
⚠️ 退化兜底的真实局限:一旦某个分区真的不支持过滤(或像上面那样写错操作符),
退化分支只按时间窗拉全量,而平台全量列表不返回待发货单,因此「0 单」并不代表没有待发货单。
DgjService.listOrders 仍然保留退化分支(防老分区彻底不可用),但会打 warn;
externalPrintOrder.buildZeroOrderHint 会在 0 单时把「平台实际出现的商家」写进提示,便于判断。
按商家分区声明决定要不要拉老分区:商家列表接口 POST /Partner/LoadMyAgentList 返回的
DbAreas[](已整体存在 shops.external_data)每一项带 IsNewSystem 标志,例如
{ DbName: 'toutiao', NickName: '抖店', IsNewSystem: false }
{ DbName: 'toutiao', NickName: '抖店-二区', IsNewSystem: true }
{ DbName: 'pinduoduo', NickName: '拼多多', IsNewSystem: false }
平台页面上的「所在区」列就是这里的 NickName。老分区只承载迁移前的历史单,
所以 resolveAreaFlags() 按域名归纳出 {hasNew, hasLegacy} 后:
hasLegacy=false的平台,直接跳过该平台的老分区(记入skippedLegacy,externalPrintOrder打 info 日志), 不再每次同步都白拉一遍历史数据;hasLegacy=true(或商家结构里查不到该平台的声明)时,老分区照常走全量兜底,避免漏掉仍留在老分区的待发货单;- 新系统区一律都查(过滤后单量极小),即使商家声明里没有该平台,也只多一次几乎空结果的请求,不会漏单。
时间窗默认值对齐平台页面:首次拉取回看 15 天(平台「待发货订单」页默认下单时间范围就是近 15 天)。
平台换算硬规则(分销代发口径):店管家 1688 单不按 1688 出号(平台侧没有 Alibaba 面单模板,
分销单必须用下游渠道的电子面单),拉单落库时 normalizeOrder 直接换算电商平台:
| 原始平台 | 判定(Tags / OrderTags 的 OutChannel) |
落库平台 |
|---|---|---|
1688(PlatformType=Alibaba) |
douyin(密文抖音分销单,订单带抖店原单号) |
抖音小店 DYXD |
| 1688 | kuaishou(密文快手分销单) |
快手 KS |
| 1688 | thyny(密文淘宝分销单,业务确认) |
淘宝 TB |
| 1688 | *_plaintext(明文分销单):douyin_plaintext、kuaishou_plaintext、thyny_plaintext… |
淘宝 TB |
| 1688 | 有 OutChannel 但渠道未映射且非明文(如 chaoshibianli) |
其他 OTHER(渠道留痕,等后续映射) |
| 1688 | 无 OutChannel(非分销单,ExtField1 也没有渠道名) |
淘宝 TB |
| 其它平台 | —— | 原平台不变 |
明文分销单为什么按淘宝出:店管家对同一渠道给成对标签值,明文单(*_plaintext)在平台侧
没有抖店/快手原单信息(取号响应里 Order.ExtraJson.extField7 为空,看不出 outPlatformOrderNo),
用抖店/快手电子面单取号会被平台直接拒绝:
"ErrCode":"15002","ErrMsg":"非抖店订单,无法使用抖音电子面单取号打印,请用抖店平台订单号重新创建线下单再重试。"
而 1688 单本身可以用淘宝(菜鸟)面单取号(生产实测 Alibaba→TB 成功多单),所以明文单一律换算成 TB。
渠道原值仍原样留在 extend_props.distribute_channel(如 douyin_plaintext),orders.external_data 保留完整报文。
留痕:状态表 extend_props.original_platform_code='1688'、extend_props.distribute_channel=<渠道>;
orders.external_data 保留店管家完整报文(含 Tags),后续做渠道映射时直接可用。
历史数据由迁移 20261107020000-convert-1688-orders-to-real-waybill-platform 按同一规则换算。
⚠️ 域名口径(换算后必须按原始平台算):订单行始终留在店管家原始平台的分区(1688 → Alibaba → fxali.dgjapp.com),
换算是为了「选对模板」,不能连带改域名。因此凡是「按订单读/写平台数据」的地方都用
extend_props.original_platform_code 推导 PlatformType 与域名:取号回读订单行(fetchWaybillNo 的 originalPlatformCode)、
拉单核对/作废(fetchRowsForVerify)、审核前已发货校验(checkPlatformFinished)、发货回传(externalSendSync.resolveTarget)。
实测同一条 1688 分销单:fxali 命中(ErpState=waitsellersend),fxdd 查不到——用错的域名会被判「平台已查不到」而误作废。
模板查找仍按换算后的平台编码(source_platform_code),因为模板必须与下游渠道一致。
4.2.1.1 第二来源:我的店铺(国内电商,自营店)
店管家账号下有两类店铺,接口与归属键都不同,由 PrintPlatformService.listShopSources() 统一声明:
来源 external_source |
接口 | 定位键 | 订单归属过滤 | 商品归属过滤 |
|---|---|---|---|---|
agent(默认,平台商家) |
GET /Partner/LoadMyAgentList |
商家 Id / FxUserId |
pfn.PathFlowNode.UpFxUserId in <FxUserId> |
SelectAgentId=<FxUserId> |
my_shop(我的店铺) |
POST /partner/LoadMyShopList |
店铺 ShopId |
o.LogicOrder.ShopId in <ShopId> |
SelectShopId=<ShopId> |
LoadMyShopList 请求(Content-Type: application/x-www-form-urlencoded,query 带 token/traceId/dbname/dataFlag):
_reqModel[ShopId]=0&_reqModel[ShopIds]=&_reqModel[Status]=0&_reqModel[PlatformTypes]=
&_reqModel[PageIndex]=1&_reqModel[PageSize]=50&_reqModel[AuthTimeOrderBy]=
&_reqModel[IsWherQuery]=true&IsCustomerOrder=false&FxPageType=1
Status:0 全部 / 1 授权成功 / 3 授权过期(页面「授权状态」下拉同口径)PlatformTypes:逗号分隔,如TouTiao,KuaiShou- 返回项关键字段:
Id(绑定记录)、ShopId(平台店铺ID)、ShopNameRemark/NickName、PlatformType/PlatformTypeName、Status、IsExpire、IsAuthExpired、AuthTime、AppKey - 没有
DbAreas:域名按PlatformType推导(TouTiao→fxdd、Pinduoduo→fxpdd、Jingdong→fxjd, 其余走 fxali),分区仍由各域名的/api/user/GetAreasInfo提供
已落地的部分(2026-11):店铺列表、导入到 OMS 并绑定货主、同步店铺商品、拉取订单。店铺编码
dgj-{账号ID}-{来源}-{ShopId}(默认来源 agent 省略来源段,历史编码不变),shops.external_data
原样存平台返回项。shopAreaSync 只刷新默认来源的店铺,「我的店铺」没有商家分区声明,不参与商家列表匹配,
不会被误禁用。
拉单/拉商品口径(自营店不能用商家的 FxUserId,那是账号自己):
| 场景 | 过滤条件 |
|---|---|
| 订单(我的店铺) | Filters[2] = { TableAlias:'o', TableName:'LogicOrder', Name:'ShopId', FieldType:'int', Contract:'in', Value:ShopId } |
| 商品(我的店铺) | 表单 SelectShopId=ShopId、SelectAgentId=''、SelectPlatformType=<PlatformType> |
| 域名 | PlatformType 推导(TouTiao→fxdd、Pinduoduo→fxpdd、Jingdong→fxjd,其余 fxali),分区仍逐 GetAreasInfo 查询 |
| 本地归属校验 | String(row.ShopId) === ShopId(不再比对 UpFxUserId) |
另外两处已对齐平台页面抓包:订单 CreateTime 上界补 .999(YYYY-MM-DD HH:mm:ss.999),
ShopId 过滤的 Contract 用 in(与平台「待打订单」页选择店铺一致)。
resolveTemplateTargets / listExpressTemplates 也按来源分支,自营店直接用
PlatformType 作为模板接口的 platformType。
4.2.2「所在区」的刷新(手动 + 定时)
DbAreas 会随平台迁移分区、商家解绑而变化,声明过期会让拉单查错分区或漏单,因此 shopAreaSync 负责刷新:
- 手动:店铺列表行内「刷新所在区」
POST /api/shops/{id}/refresh-area(货主权限即可)、 外部打单平台页面账号行「刷新所在区」POST /api/external-print-accounts/{id}/refresh-shops-area(集团权限); - 定时:
schedule/refreshExternalShopAreas.js每小时检查一次,按账号维度判断是否到期 (shops.extra.area_synced_at,默认 6 小时,可用DGJ_AREA_REFRESH_HOURS调整); - 同账号只拉一次:商家列表按账号拉全量(
PageSize=200翻页,实测 62 个商家一页), 账号下所有店铺共享同一份结果,按external_data.Id或店铺编码尾段匹配; - 已解绑自动禁用:商家已不在合作列表(解绑/停用)时把
shops.status置 0, 并在shops.extra.auto_disabled与last_order_sync_msg写明原因。自动拉单与一键拉单都只取status=1, 因此会自动跳过;只有人工把状态改回启用才会恢复(商家重新出现时只清理标记并提示,不会自动启用)。
4.2.3 店铺禁用 / 启用与待审核订单
店铺禁用后无法取号(账号或商家已不可用),留在「待审核」的单子一旦审核就会报错,所以状态切换会联动处理待审核订单
(service/shopOrderGuard,禁用与启用两条链路都覆盖:自动禁用走 shopAreaSync,人工改状态走 PUT /api/shops/{id}):
| 时机 | 处理 |
|---|---|
| 禁用(人工 / 商家解绑自动) | 该店铺全部待审核订单 pending → void,void_reason 写 店铺已禁用,暂停处理(…重新启用后自动恢复),并记一条系统操作日志 |
| 重新启用 | 只把 void_reason 以该前缀开头的订单 void → pending(恢复时清空作废痕迹;其它原因作废的单不受影响) |
- 只动「待审核」:待推送 / 异常 / 委外中 / 配送的订单不动(库存与仓库动作已发生,交人工处理);
- 禁用店铺再拉单会被拒绝(
syncOrders直接报「店铺已禁用,请先启用后再拉取订单」), 避免禁用后又拉回待审核订单; - 启停接口返回
pending_orders_voided/pending_orders_restored,前端提示作废/恢复了多少单。LogicOrderId的精确过滤(Contract=in,逗号分隔多值)在老分区与新系统区都可用, 用于核对「本地待审核但本次待发货结果里没有」的订单:回读到且已发货/已终结 → 作废;回读不到 → 按「查不到」作废。
订单行关键字段:
| 字段 | 用途 |
|---|---|
Id / LogicOrderId |
取号请求的订单主键(两者实测相同) |
PlatformOrderId |
平台单号(OMS extend_props.platform_order_no) |
ShopId / FxUserId / PathFlowCode |
取号报文必填 |
SubOrders[].OrderItemId / OrderItemCode |
取号明细(数量固定写 1) |
LastWaybillCode |
平台已有运单号(旧系统据此复用;OMS 只用于事后对比是否换号)。注意:它非空不代表已经出号给业务方,见 §4.2.4 |
PrintState / ExpressPrintTimes / ExpressPrintTime |
PrintState=1 已打印;ExpressPrintTimes 是该单被打印/取号的次数,ExpressPrintTime 是最近一次时间 |
WaybillCodes / IsMultiPack / SumPackageCount |
平台侧已出号列表 / 是否多包裹 / 包裹数;单包裹单号场景下 WaybillCodes 常为空数组 |
CaiNiaoAuthInfoId |
菜鸟授权网点ID(模板绑定的授权网点;同平台不同网点取值不同)。OMS 已独立成列 external_print_express_interfaces.cai_niao_auth_info_id,并在取号结果里回传给 WMS |
ErpState |
sended 表示平台侧已发货;waitsellersend 待发货 |
ToName / ToPhone / ToProvince / ToCity / ToCounty / ToTown / ToAddress / ToFullAddress |
收件人报文 |
4.2.4 LastWaybillCode ≠ 已出号(实测 2026-11-04)
同一行的两次观测:
08:20 前:PrintState=1 ExpressPrintTimes=1 LastWaybillCode='772085297346161' WaybillCodes=[]
08:48 (取号 2 次后):PrintState=1 ExpressPrintTimes=4 LastWaybillCode='772085297346161'
WaybillCodes=[
{ WaybillCode:'772085302413126', WaybillCodeId:10000273932918, TemplateId:'10824270' },
{ WaybillCode:'772085257627038', WaybillCodeId:10000273851363, TemplateId:'10824270' }
]
IsMultiPack=false SumPackageCount=1 SubOrders=1
ExpressPrint 的响应里,每个运单号对应一条 Data.WaybillCode[],关键字段:
WaybillCode='772085257627038' WaybillCodeId=10000273851363
WaybillCodePid='10000267890142_0' ← 平台幂等键:<LogicOrderId>_<包裹序号>
Index=0
WaybillCodeCreateDate='2026-11-04 08:20:37'
结论:
-
LastWaybillCode只是「最近一次打印用到的号」,WaybillCodes才是平台确认的出号列表,两者可能不一致。 -
平台自己的幂等键是
WaybillCodePid = <LogicOrderId>_<包裹序号>:同一序号重复调ExpressPrint会拿回同一个WaybillCodeId+ 同一个号(我们的 08:20 / 08:39 两次就是这种情况,每次只新增一条打印历史PrintHistoryIds), 换序号才会分配新号。 -
ExpressPrintTimes是打印次数,跟号码个数不是一回事(本单打印 4 次、只有 2 个号)。 -
打印记录(
Data.PrintHistoryIds):元素{ Id, Pid, WaybillCode, WaybillCodeChild, BatchIndex },Id即 printHistoryId,每打一张新增一条;Pid与WaybillCode[].WaybillCodePid、WaybillCodeId是不同概念,别混。 OMS 把解析结果(id/pid/waybill_code/batch_index数组)落到waybill_fetch_records.print_history_ids, 并在取号响应里回传print_history_ids/print_history_id(WMS 自行落库), 后续重打/作废(PrintHistory/LoadPrintData按它回捞)以 OMS 库里的记录为准。 -
printHistoryId 不在「面单数据」里(实测:
PrintDataJson.id = null、printDataJson.printHistoryIds = null,WaybillCode[]里也没有该字段),只在响应顶层:取号是Data.PrintHistoryIds[].Id, 回捞打印数据是Data[].ID(实测10000078656212,number)。要拿它只能从这两个顶层字段取。 -
打印数据(params)只有 10 分钟有效期:
contents[].params是平台在打印那一刻签发的 (access_token=…&method=logistics.getShopKey×tamp=…&sign=…,timestamp= 该打印记录的CreateDate)。 ⚠️ 实测确认:POST /PrintHistory/LoadPrintData只是回放那次打印的签名,不会重新签发 (换FxPageType=1/2、加IsRePrint/IsRefresh都返回同一个timestamp/sign)。 ✅ 要新签名只能让平台重新下发(不是重打,只是拿一份新的打印数据):ExpressPrint+PrintMethod=Normal+IsIgnoreWaybillRepeat=true→ 实测复用订单已有运单号(不消耗面单)、params.timestamp= 当前时间。 对照:PrintMethod=NewPrint(或IsIgnoreWaybillRepeat=false)会分配新号并消耗面单,拉取 params 绝不能用。 因此取号记录里同时落了dbname、platform_host(实际命中的域名)与cai_niao_auth_info_id(= 店铺唯一标识), 后续按「店铺标识 + 运单号」即可定位到该运单号对应的取号记录,再拉一份新的打印参数。 对外方法见deliveryorder.getprintdata(WMS-OMS-取号对接.md§4.7.1)。 -
deliveryorder.getprintdata的空引用(2026-11-07 线上故障,已修):WMS「韵达」面单 (template_id=12360764、CaiNiaoAuthInfoId=6838859、dbname=dzh93a8…)换打印数据时平台回拉取打印参数失败:未将对象引用设置到对象的实例。实测对照(同一账号、同一
fxdd域名、真实面单):报文 平台结果 ExpressPrint复用 +checkData={}(旧实现)空引用;偶尔「成功」但 documents为空、WaybillCode为 nullExpressPrint复用 +checkTemplateAvailable的Data(DateNow/DayPrintBatchNumber)成功,返回新鲜 params(timestamp= 当前时间)与templateURL根因:
RequestBatchNumber由DateNow + DayPrintBatchNumber拼成,取号流程(fetchWaybillNo) 会先调CheckTemplateAvaliable拿这两个值,而换打印参数时传了checkData: {},RequestBatchNumber退化成1/1/,平台解析批次号时抛空引用。结论:不是域名/分区问题(fxdd + 该 dbname 在补齐批次号后正常),也不是菜鸟授权网点字段问题 (
Orders[0][CaiNiaoAuthInfoId]加不加结果一样)。现在fetchPrintParams固定先做模板校验再提交。兜底(
waybillPrintData.fetchGroup):平台没给documents/params、或复用路径仍失败时, 回退POST /PrintHistory/LoadPrintData(按printHistoryId,只读、不消耗面单), 用Data[].PrintDataJson解出contents[].params+templateURL,返回标source: print_history。 这条路径在订单已离开「待发货」(ErpState=sended)时仍可用,但拿到的是当时打印的签名(可能已过期), 所以成功路径始终优先ExpressPrint重新签发。 -
params 是逐张面单的:
printDataJson.PrintDataList.task.documents[].documentID= 运单号,contents[].params是该张面单的内容;同店铺可共用的只有PrinterConfig与templateURL, 不能拿 A 单的 document 去打 B 单(会把收件人/面单号搞错)。 -
因此 OMS「按
LastWaybillCode复用」是错的判断;是否重复取号由 OMS 幂等表(request_id) 决定, 而同一个包裹重复取号拿回同号是平台行为,不是 bug。
多包裹 / 子单(已实测跑通,2026-11-04 09:28)
平台「新单号打印」的判定完全靠这三个字段,其余与我们原来一致:
字段 新单号打印(要新号) 原单号打印(复用旧号) PrintMethodNewPrintNormalIsIgnoreWaybillRepeatfalsetruePackageType1可不传 Orders[0][PrintInfo][1];\n空 Orders[0][WaybillCode]+Orders[0][WaybillCodes][]带上当前号(含 WaybillCodeId/Pid)可空 实测(同一订单
10000267890142,连续 3 次调用都拿到新号):09:22:14 → 772085315396234 WaybillCodeId=10000274161082 pid=63274907ebce8f6b_1_1 09:22:46 → 772085293866221 WaybillCodeId=10000274129933 pid=63274907ebce8f6b_2_1 09:28:xx → 772085311557965 WaybillCodeId=10000274191801 pid=63274907ebce8f6b_3_1所以:每次调用都分配新号,pid 第二段自增;OMS 现在统一走这套参数,WMS 按包裹各调一次即可拿到各自的号。 旧逻辑用的是
Normal+IsIgnoreWaybillRepeat=true→ 平台按已有号复用,才出现「取子单号拿回原单号」。⚠️ 代价:每次取号都真实消耗一张面单(
ExpressPrintTimes累加),重试务必复用同一个request_id。
4.2.5 订单明细 → 店铺商品 → 系统商品(匹配口径)
拉单时每条明细按「店铺 + 平台商品ID + 平台规格ID」命中店铺商品(service/externalPrintOrder.matchShopProduct):
| 明细字段 | 来源 | 店铺商品字段 |
|---|---|---|
outer_item_id |
明细 ProductId(商品级) |
shop_products.outer_item_id = 商品 PlatformId |
outer_sku_id |
明细 SkuId(无合法值退 SkuCode) |
shop_products.outer_sku_id = Skus[].SkuId(早期用过 SpecId,两者在部分平台不一致) |
outer_sku_code |
明细 PtProductInfo.SkuCode(退 SkuCode) |
shop_products.outer_sku_code = Skus[].SkuCode(店管家内部规格编码) |
1688(Alibaba)订单的 SkuId 是商品标题(实测:SubOrders[].SkuId = ProductSubject,
如「定型喷雾蓬松持久空气刘海同款…大小容量组合」),平台规格ID 这条路完全走不通。旧系统
(Dianguanjia.php 的 get_sku_bind)只按 SubOrders[].SkuId 与商品表 SkuId 严格等值匹配,
没有 SkuCode / CargoNumber / PtProductInfo 的兜底,所以 1688 分销单在旧系统里永远匹配不上
(hasnobind → 订单 ITEMS 置空,同时给商品打 hasOrder=1 触发按 SkuId 反查商品列表补采,
而用标题反查商品列表必然查不到)。
店管家对同一个规格给了两个键(同一份真实数据对照,商品 881526926136):
商品库 Skus[] (/Product/LoadList) |
1688 订单 SubOrders[] |
|---|---|
SkuId = 5937045124144 |
SkuId = 定型喷雾…大小容量组合(标题) |
SkuCode = 10000446302877 |
PtProductInfo.SkuCode = 10000446302877 ✔ |
CargoNumber = 007+111 |
SkuCode / CargoNumber = 007+111(商家编码,同商品内会重复,不能唯一定位规格) |
所以 OMS 的匹配改成两级(lib/shopProductMatch):
- 平台规格ID(
outer_sku_id)精确命中; - 命不中时按店管家规格编码(
outer_sku_code)命中; - 只有「明细根本没有规格ID/编码」才按商品ID取 id 最小的一条(兜底), 带了规格信息却都没命中时不退化,避免绑错规格。
- 明细带规格ID时必须精确命中同规格,不允许退化成「按商品ID随便取一条」(会绑错规格、发错货); 规格ID对不上 → 保持未采集,等商品补齐后重匹配;
- 命中店铺商品后才看绑定关系:
bind_type=1/2→ 已解析;bind_type=0→parse_status=2(parse_msg=店铺商品未绑定系统商品);没命中 →parse_status=2(parse_msg=未采集到该店铺商品); - 两种
parse_status=2都会被待审核列表的「仅已绑定」过滤掉,列表会给出「另有 N 单未显示」提示 (order_status.list的hidden_unbound)。
商品写入后自动重匹配(service/orderItemResolve.rematchUnboundItems):同步商品后,
在同一事务里把该店铺「shop_product_id 为空」的待审核 / 异常明细按上述口径再匹配一次并重建明细,
避免「先拉单、后同步商品」导致明细永远停在未采集(已审核之后的订单明细不参与,随审核锁定)。
同步商品接口返回 rematched(补上的明细行数)。
实测(店铺 19「意洁」同步 1438 行店铺商品后):原先 21 条 1688 明细全部指向正确的规格, 例如
PtProductInfo.SkuCode=10000446302877→outer_sku_code=10000446302877(420ml*1瓶+排骨梳)、10000446302878→ 99ML黑色、10000446302881→ 420ML;parse_msg也从 「未采集到该店铺商品」变成「店铺商品未绑定系统商品」(差的是绑定关系,不再是匹配)。 历史明细没有platform_snapshot.outer_sku_code时,resolveItemSkuCode会回落到 平台原始报文(raw.PtProductInfo.SkuCode),因此不用重拉订单也能修正。
早期还有一个「按平台商品ID单独补拉」的入口(
POST …/pull-products+listProductsByIds), 已移除:它绕开分区声明与SelectAgentId单查商品,容易把别的商家的同款商品写进本店铺, 现在统一走「同步商品(全量快照)+ 自动重匹配」。
沿用旧口径的坑:老数据里 shop_products.outer_sku_id 可能是 SpecId,与明细的 SkuId 对不上;
重新同步商品会按 SkuId 就地改键(同商品同规格名唯一命中),之后重匹配即可命中。
4.2.6 新增下游分销渠道怎么加(明文 / 密文)
分销渠道散落在 Tags / OrderTags 的 OutChannel.TagValue 里,同一渠道有成对写法:
密文(douyin、kuaishou)+ 明文(douyin_plaintext、kuaishou_plaintext、thyny_plaintext…)。
新增平台/渠道按下面这套走:
| 步骤 | 做什么 | 怎么判定 |
|---|---|---|
| 1 | 抓一单真实报文,确认 TagValue 形态 |
明文一定以 _plaintext 结尾;密文是纯渠道名 |
| 2 | 看取号响应里 Order.ExtraJson.extField7 是否带原单信息 |
有 outPlatformOrderNo / outShopId / encryptReceiver* → 密文单,可用下游电子面单;空串 → 明文单,只能用淘宝(菜鸟)面单 |
| 3 | 密文渠道:加进 DISTRIBUTE_CHANNEL_PLATFORM(lib/printPlatform/dgj.js);明文不用加 |
明文统一由 isPlaintextDistributeChannel 判到 TB |
| 4 | 确认「平台 + 快递编码」唯一命中模板 | external_print_express_interfaces 里 platform_code + custom_code 必须唯一(重复会让 resolveByCode 返回 null → 报「未绑定模板」) |
| 5 | 补单测 + 更新本文 §4.2 换算表 | test/app/lib/dgjOrderPlatformRule.test.js:密文 → 目标平台、明文 → TB |
已确认的渠道映射(生产实测 + 业务确认):
渠道 OutChannel |
下游平台 | 说明 |
|---|---|---|
douyin |
DYXD 抖音小店 |
密文,extField7 带抖店原单号 |
kuaishou |
KS 快手 |
密文 |
thyny |
TB 淘宝 |
密文,淘宝分销单(2026-11-09 业务确认,订单号形如 5127404439433014429) |
*_plaintext |
TB 淘宝 |
明文单,店管家没有原单信息,只能用菜鸟面单 |
其它(如 chaoshibianli) |
OTHER 其他 |
留痕待映射 |
判定依据(实测 2026-11-08):同一店铺(7398588)、同一模板(12360764 抖店韵达)、
同一收件人区域下,密文单 dgj-10000289308826 取号成功,明文单 dgj-10000289308857
被平台拒绝 ErrCode=15002 非抖店订单,无法使用抖音电子面单取号打印;两者差别只在
Order.ExtraJson.extField7(成功单有 outPlatformOrderNo,失败单是 "")。
另外店管家 UI 对明文单的打印弹窗默认模板是「【菜鸟】国内邮政小包一联3」(我们库里 TB 平台的 13873834),
LoadWaybillAccountDetailInfo 也用 expressCode=POSTB —— 说明平台自己就把明文单按淘宝/菜鸟处理。
4.3 模板校验:POST /TemplateSet/CheckTemplateAvaliable
{
"templateId": "10824270",
"printCount": "1",
"needCheck": "true",
"isResend": "",
"pirntMethod": "Normal", // 注意:平台字段名就是 pirntMethod(拼写错误)
"IsContinueForStock": "false",
"IsCustomerOrder": "false",
"FxPageType": "2",
"orders[0]": {
"SourceShopId": 7319156,
"UpFxUserId": 1227061,
"SourceFxUserId": 1227061,
"LogicOrderId": "10000266092590",
"PlatformOrderId": "10000266092590",
"IsAllowNegativeStock": "false",
"SendType": 1,
"DataFlag": 1,
"Items": [{ "OrderItemCode": "10000289254637", "LogicOrderItemId": "10000289254637", "Quantity": "1" }]
}
}
响应 Data:Balance(面单余额)、PrintCount(本次张数)、DateNow、DayPrintBatchNumber、Branches(网点信息,需 null→''、true/false→字符串)。
4.4 取号:POST /NewOrder/ExpressPrint
{
"TemplateId": "10824270",
"PackageCount": "1",
"PrintMethod": "Normal",
"IsIgnoreWaybillRepeat": "true", // 忽略重复校验,每次都取新号
"PrinterName": "默认打印机",
"IsPreview": "false",
"IsContinueForStock": "false",
"PackageDesc": "", "GoodsDesc": "", "PackageLength": "", "PackageWidth": "", "PackageHeight": "",
"ExpressSustenance[name]": "", "ExpressSustenance[desc]": "",
"Branches[0]": { "...": "来自 CheckTemplateAvaliable" },
"RequestBatchNumber": "1/1/202611045", // 1/1/<DataNow><DayPrintBatchNumber>
"IsCustomerOrder": "false",
"FxPageType": "2",
"Orders[0]": {
"WaybillCodeId": "",
"Index": 1,
"Id": "10000266092590",
"PlatformOrderId": "10000266092590", // 旧系统传的是 LogicOrderId
"LogicOrderId": "10000266092590",
"PathFlowCode": "1000001370772",
"CustomerOrderId": "3740288268498815232", // 真正的平台单号
"ShopId": 7319156,
"PrintInfo": "",
"OrderItems": ["10000289254637"],
"Items": [{ "OrderItemId": "...", "OrderItemCode": "...", "Quantity": "1", "ShortTitle": "...", "SkuCode": "...", "ProductCode": "..." }],
"WaybillCode": "", // 置空:号码复用/分配由平台按 <LogicOrderId>_<包裹序号> 决定
"ManyCodeSendIndex": "0", // 包裹序号(0 基),OMS 由发货单号尾部 _N 推导(N-1)
"IsManyCodeSend": "",
"SellerRemark": "", "BuyerRemark": "",
"FxUserId": 1227061,
"IsSelectAllNotPrintedItem": "1",
"SendType": "0",
"DataFlag": "...",
"Receiver": {
"toFullName": "...", "toMobile": "...", "toArea": "完整地址",
"toProvince": "...", "toCity": "...", "toCounty": "...", "toMaskAddress": "镇+详细地址"
},
"Sender": { "CompanyName": "" },
"Buyer": { "BuyerWangWang": "..." }
}
}
4.4.1 1688 分销单用抖音面单的前置条件(ErrCode=15002)
1688 分销单换算成抖音小店(DYXD)后,平台侧还要求订单在店管家带抖店原单信息,
否则 ExpressPrint 直接失败(实测 2026-11-08,订单 dgj-10000289308857):
"ErrCode":"15002",
"ErrMsg":"非抖店订单,无法使用抖音电子面单取号打印,请用抖店平台订单号重新创建线下单再重试。"
判据在订单报文的 Order.ExtraJson(店管家订单行 ExtField7)里:
| 场景 | ExtraJson.extField7 |
取号结果 |
|---|---|---|
下游渠道 OutChannel=douyin(API 授权过) |
{"outPlatformOrderNo":"6931267452381592757","outPlatformCode":"douyin","outPlatformAppkey":"…","outShopId":"152278571","encryptReceiver…":…} |
成功(生产 DYXD 成功 60+ 单,全部带 outPlatformOrderNo) |
下游渠道 OutChannel=douyin_plaintext(明文渠道) |
""(空串,没有抖店原单号/加密收件人) |
失败 15002 |
即:同一店铺、同一模板下,差别只在这个字段(RequestBatchNumber、AuthUrl、FxPathUserNodes
在成功与失败响应里都一样,可以排除)。
⚠️ 现在的处理口径:明文分销单(OutChannel=*_plaintext)在拉单时直接换算成淘宝(TB),
不再走抖店/快手模板(见 §4.2),所以不会再出现这条 15002;若某单仍报 15002,
说明它是密文渠道单(douyin)但店管家侧丢了抖店原单信息,只能在店管家侧解决:
重新授权「抖音分销」(https://auth.dgjapp.com/auth/douyinfx)后同步该单,
或按平台提示用抖店平台订单号在店管家建线下单再取号 —— OMS 侧重试即可。
取号失败原因的透出:平台的逐单错误在 Data.WaybillCode[n].ErrCode / ErrMsg,
DgjService.describeWaybillError 会拼成「ErrMsg(ErrCode=…)」写进 waybill_fetch_records.error_message,
不再只剩一句「平台返回取号失败」。
4.5 取号响应
旧系统只用到的两个字段:
foreach ($res["Data"]["WaybillCode"] as $WaybillCode) {
if ($WaybillCode["IsError"]) {
// 失败:$WaybillCode["OrderInfo"]["OrderInfo"]["OriginID"] 回查订单
}
}
运单号本身旧系统是从打印历史取的:
// PrintHistory/LoadPrintData → Data[0].PrintHistoryData.PrintDataJson
$documentID = $PrintDataList["task"]["documents"][0]["documentID"]; // = 运单号
因此 OMS 的解析顺序(防御式):
Data.WaybillCode[].WaybillCode / LogisticCode / MailNo / WaybillNoData.WaybillCode[].OrderInfo.OrderInfo.WaybillCode / LastWaybillCodeData.WaybillCode[].PrintInfo / PrintData / PrintDataJson(旧版返回)Data.PrintDataList.task.documents[](实际口径):documentID= 运单号printInfo= 面单打印数据(base64 编码的 URL-encoded JSON,WMS 打印端按原样塞进task.printInfo,不要再解码)contents[0].signature / encryptedData / ver→ OMS 的signature / encryptprintinfo / ver(视频号自定义模板不返回contents,这三项为空)
第 1、2、3 项是按常见字段名兜底;实测(2026-11-04)打印数据只在
documents[].printInfo, 之前只读WaybillCode[].PrintInfo导致回给 WMS 的printinfo是空串。打印数据必须留痕:
printinfo/signature会随逐单结果透传给 WMS(WMS 落order_express), 同时整条平台原始返回写入 OMS 的waybill_fetch_records(含raw_response、printinfo、waybill_source), 出问题查表即可,不需要让 WMS 重放报文。表结构见WMS-OMS-取号对接.md§4.7。
5. 旧系统的两个额外动作(OMS 暂不实现)
| 动作 | 接口 | 说明 |
|---|---|---|
| 发货 | POST /NewOrder/OnlineSend |
取号后通知平台发货;OMS 的发货由 WMS 回传 deliveryorder.confirm 处理,不在此调用 |
| 打印历史 | POST /PrintHistory/LoadList / LoadPrintData |
用于回捞运单号与打印数据;OMS 直接从 ExpressPrint 响应解析,打印记录ID(Data.PrintHistoryIds[].Id)已解析并落 waybill_fetch_records.print_history_ids(重打/作废要用),列表接口暂不接入 |
6. OMS 落地
6.1 代码位置
| 方法 | 作用 |
|---|---|
DgjService.fetchWaybillNo(order, { template }) |
取号主流程:回读订单行 → 已发货拦截 → 模板校验 → 取号 → 解析运单号/打印数据 |
DgjService.findPlatformOrderRow(host, {...}) |
按 LogicOrderId → PlatformOrderId → 时间窗兜底 找订单行 |
DgjService.fetchOrderRows(host, {...}) |
NewOrder/List 精确过滤查询 |
DgjService.checkTemplateAvailable(host, {...}) |
CheckTemplateAvaliable |
DgjService.expressPrint(host, {...}) |
ExpressPrint(会消耗面单) |
resolveOrderHost(platformType) |
订单域名(fxali / fxdd / fxpdd / fxjd) |
service/shopAreaSync.refreshAccount(account) |
拉一次账号商家列表,写回店铺 external_data(所在区),商家已解绑的店铺自动禁用 |
service/shopOrderGuard.voidPendingOrders/restorePendingOrders(shop) |
店铺禁用时作废待审核订单、启用时恢复(只处理因禁用被暂停的单) |
service/externalPrintOrder.syncOrders(shop, account, { startTime, endTime }) |
拉取并写入店铺订单(手动/定时共用) |
service/externalPrintOrder.matchShopProduct(shop, line) / service/orderItemParse.findShopProduct(item, principalId) |
明细 → 店铺商品:平台规格ID → 店管家规格编码(outer_sku_code)→ 商品ID 兜底(口径见 §4.2.5) |
lib/shopProductMatch.createShopProductMatcher/shopProductScopes |
同一口径的内存索引与查询条件(拉单逐条查库、商品同步后批量重匹配共用) |
6.1.1 订单明细解析:组合拆分与「订单唯一赠品」
订单明细按「店铺商品 → 系统商品 / 组合商品」展开成最小单位(lib/orderItemExpand + service/orderItemResolve):
| 绑定关系 | 明细行 |
|---|---|
| 系统商品 | 一行对一行,数量 = 平台数量 |
| 组合商品 | 拆成组合内每个子商品一行,数量 = 平台数量 × 组合内数量 |
| 未采集/未绑定 | 保留平台原样一行(parse_status=2) |
订单唯一赠品(products.is_order_unique_gift = 1,系统商品可配置、可筛选):
展开成最小单位后整单收敛——同一赠品商品只保留第一行、数量固定 1:
| 场景 | 结果 |
|---|---|
| 平台明细数量 3 | 1 行 × 1 |
| 买了 2 份同一个组合(组合里含该赠品) | 1 行 × 1 |
| 不同组合都含该赠品 | 1 行 × 1 |
| 多个不同赠品 | 各自 1 行 |
实现:orderItemResolve.collapseUniqueGifts(查 products.is_order_unique_gift)→
orderItemExpand.collapseUniqueGiftRows(纯函数收敛)。因为每次 rebuildOrderItems
都会在展开后收敛一次,重复重建不会把数量涨回去。注意:只影响 order_status_items
(订单页/推送仓库口径),老表 order_items 仍按平台明细逐行记录。
6.2 真实取号开关
# 默认开启:每次取号都会真实调用 ExpressPrint(消耗面单)
# 需要「只读联调、绝不下单」时关闭:
DGJ_WAYBILL_ENABLE=0 # 0/false/off/no 视为关闭;不设置或其他值均为开启
- 关闭后取号直接返回「店管家真实取号已关闭(DGJ_WAYBILL_ENABLE=0):…」(不再有「复用平台运单号」这种只读成功路径);
- 是否重复取号只看幂等表:同一
request_id的失败/部分失败可重试,成功则回放;清表或换request_id就会再取一次号。
6.3 自动作废的备注口径(区分「已发货」与「查不到」)
拉单时发现的「本地仍是待审核、但平台不应再处理」的订单会自动作废,作废备注按真实原因写入:
| 情形 | void_reason 示例 |
|---|---|
| 平台已发货/已终结 | 店管家侧已发货或已终结(平台订单状态 ErpState=sended、平台已有发货时间 2026-11-03 17:35:24、1 个面单包裹已发货、物流状态已推进(LogisticStatus=3)),系统自动作废 |
| 平台已查不到 | 店管家侧已查不到该订单(2026-11-01 07:00 至 2026-11-04 07:00 的拉取结果中没有该单,可能已删除、合并或转出本店铺),系统自动作废 |
- 「已发货」的判定依据(
describeFinishedOrder):ErpState属已发货/已终结、有OnlineSendTime、面单包裹IsSended、LogisticStatus>0,命中项全部写进备注。 - 「查不到」的判定:本地待审核单的下单时间落在本次实际查询窗口内,但平台返回的
list + finished里都没有它。 为避免误判,限制:窗口最长回看 45 天、本次必须成功命中至少一个分区、AUTO_VOID_MISSING_ORDER=0可整体关闭。 - 操作日志同步记录
reason与platform_status;店铺「最近同步结果」与拉单任务结果都会显示「其中平台已查不到 N 单」。
6.4 审核前平台状态守卫(防「平台已发货的单被审核推送」)
订单可能昨天已在店管家发货,OMS 今天才审核。orderStatus._auditOne 在审核前会:
- 判断是否「外部打单订单」(店铺
type=2+external_print_account_id); - 用已同步的快递接口记录拿
platform_type/dbname,实时回读店管家订单行(只读); isOrderFinished(row)为真(ErpState已发货/已终结、有OnlineSendTime、包裹IsSended、LogisticStatus>0)时:- 自动作废该订单,作废备注写明命中的具体依据(如「店管家侧已发货或已终结(平台订单状态 ErpState=sended、平台已有发货时间 2026-11-03 17:35:24),系统自动作废」);
- 抛 400:
订单 xxx 店管家侧已发货或已终结(…),不能审核(已自动作废)。
- 平台查询失败放行(只告警),避免平台抖动卡住审核。
关闭开关:DGJ_AUDIT_PLATFORM_CHECK=0(默认开启)。
审核现在会为外部打单订单增加 1 次只读的平台查询;批量审核按单串行执行。
6.5 取号时同样拦截
fetchWaybillNo 回读到平台订单行后:
isOrderFinished(row)为真 → 直接抛错「订单在店管家已发货或已终结(ErpState=sended,平台运单号 …),取号失败:请作废或取消该单」;- 否则继续调 ExpressPrint(不再判断
LastWaybillCode,也不复用)。若平台返回的号码与订单行原号码相同,响应message会注明「本次调用平台取号,但平台仍返回原运单号 X」。
6.6 手工验证脚本
cd backend
# 只读校验:查订单 → 查绑定 → 回读平台订单行 → 打印将发送的报文(不调用取号)
node scripts/dgj-waybill-probe.js --order dgj-10000266092590 --express STO
# 真实取号(会消耗面单;需显式加 --execute;原始响应落到 backend/tmp/*.json)
node scripts/dgj-waybill-probe.js --order dgj-10000266092590 --express STO --execute
实测输出(2026-11-04,只读):
Id: '10000266092590' LogicOrderId: '10000266092590' PlatformOrderId: '3740288268498815232'
ShopId: 7319156 FxUserId: 1227061 ErpState: 'sended' PrintState: 1
LastWaybillCode: '772085250163045' SubOrders: 1
平台订单行已有运单号 772085250163045(仅用于对比:OMS 不再复用,真实取号会调 ExpressPrint 换新号)
这张测试单在店管家已取号并已发货,
isOrderFinished会直接拦成「请作废或取消该单」,不会走到取号。
7. 尚未真实验证的点(首次取号时确认)
ExpressPrint响应里运单号的确切字段(是否就是WaybillCode,还是只在PrintInfo的documentID)。CheckTemplateAvaliable的Balance/PrintCount单位(张数)与「余额不足」实际返回码。PlatformOrderId过滤是否必须带CustomQuery=PlatformOrderIdSearch(LogicOrderId实测可用,已作为首选)。Branches结构(多网点时是否需要逐网点拆分取号)。- 快手/小红书等平台是否仍与淘宝同域(旧系统映射都指向
fxali)。 - 多包裹订单(
SubOrders>1/ 需要多张面单)时的取号数量策略。
8. 安全提示
ExpressPrint会真实消耗面单并可能产生费用;IsIgnoreWaybillRepeat=true表示每次都取新号,重复调用会重复取。- 因此:每次请求都会真实取号(不再复用平台已有运单号),去重只剩幂等表
request_id这一道; 联调/回归测试只用只读路径(订单行查询 + 报文字段核对),不要把真实订单反复取号。 - 生产环境如需启用,应由业务指定测试单、确认余额后再开开关。