From e1f49451c04a0ffc9c5fa16fded6c701ac288a6f Mon Sep 17 00:00:00 2001 From: liufumingren Date: Sun, 8 Nov 2026 19:05:30 +0800 Subject: [PATCH] =?UTF-8?q?fix(dgj):=20=E5=8F=96=E5=8F=B7=E5=A4=B1?= =?UTF-8?q?=E8=B4=A5=E9=80=8F=E5=87=BA=E5=B9=B3=E5=8F=B0=20ErrCode/ErrMsg?= =?UTF-8?q?=EF=BC=8C=E5=8F=96=E5=8F=B7=E6=8A=A5=E6=96=87=E6=9E=84=E9=80=A0?= =?UTF-8?q?=E5=8F=AF=E5=AF=B9=E7=85=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 取号失败时用户只看到「店管家取号失败:平台返回取号失败」——平台把逐单错误放在 `Data.WaybillCode[n].ErrCode / ErrMsg`(实测 15002「非抖店订单,无法使用抖音电子面单 取号打印…」),我们只读了 `ErrorMsg` / `Message`,真实原因被吞掉。 - 新增 describeWaybillError:按 ErrMsg → ErrorMsg → Message → OrderInfo/Order 兜底, 并附上 ErrCode;「未返回运单号」分支也带上平台原因 - 把 ExpressPrint 的 Orders[i] 报文构造抽成纯函数 buildExpressPrintOrder / buildExpressPrintOrders(expressPrint 内部改为调用),并挂到 DgjService 静态方法上: 取号记录只有平台回显、没有请求体,出问题时要能把「我们实际发的报文」打出来对照 (对比过成功/失败两单:结构完全一致,只有业务值不同) - 单测:dgjWaybillError(4 例)+ dgjExpressPrintPayload(5 例:字段映射、明细口径、 收件人、多包裹 Index、当前运单号) - 文档补 §4.4.1:1688 分销单用抖音面单的前置条件(extField7 里要有 outPlatformOrderNo, 明文渠道单没有就报 15002,只能在店管家侧重新授权/建线下单) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- backend/app/lib/printPlatform/dgj.js | 223 ++++++++++++------ .../app/lib/dgjExpressPrintPayload.test.js | 89 +++++++ backend/test/app/lib/dgjWaybillError.test.js | 43 ++++ 店管家取号-旧系统提取.md | 27 ++- 4 files changed, 315 insertions(+), 67 deletions(-) create mode 100644 backend/test/app/lib/dgjExpressPrintPayload.test.js create mode 100644 backend/test/app/lib/dgjWaybillError.test.js diff --git a/backend/app/lib/printPlatform/dgj.js b/backend/app/lib/printPlatform/dgj.js index ac9cc77..334d54a 100644 --- a/backend/app/lib/printPlatform/dgj.js +++ b/backend/app/lib/printPlatform/dgj.js @@ -270,9 +270,129 @@ function buildSendOrder(row, index, expressCode = '') { return [ ...new Set(out) ].slice(0, 3); } +/** + * 当前运单号(平台订单行上已取的号):新单号打印时带给平台,平台据此分配下一个号 + * @param {Object} row 平台订单行 + * @return {string} 运单号,无则空串 + */ +function deriveCurrentWaybillCode(row) { + const data = row || {}; + const list = Array.isArray(data.WaybillCodes) ? data.WaybillCodes.filter(item => item && item.WaybillCode) : []; + return String(data.LastWaybillCode || (list[list.length - 1] || {}).WaybillCode || '').trim(); +} + +/** + * 构造取号(`ExpressPrint`)的 `Orders[i]` 报文 + * + * 单独抽出来是为了能把「我们实际发给平台的订单报文」打出来做对照(取号失败排查时, + * `waybill_fetch_records.raw_response` 只有平台回显,没有请求体)。 + * @param {Object} row 平台订单行(findPlatformOrderRow 的返回 / 拉单落库的 external_data) + * @param {Object} options 参数 + * @param {string} options.templateId 面单模板ID + * @param {string} [options.expressCode] 快递编码 + * @param {number} [options.index] 报文序号(0 基) + * @param {string} [options.currentWaybillCode] 当前运单号,缺省按订单行推导 + * @return {Object} Orders[i] 报文 + */ +function buildExpressPrintOrder(row, { templateId, expressCode = '', index = 0, currentWaybillCode } = {}) { + const waybillCode = currentWaybillCode === undefined ? deriveCurrentWaybillCode(row) : currentWaybillCode; + const items = []; + const orderItems = []; + for (const sub of Array.isArray(row.SubOrders) ? row.SubOrders : []) { + items.push({ + OrderItemId: sub.OrderItemId, + OrderItemCode: sub.OrderItemCode, + Quantity: '1', + ShortTitle: sub.ShortTitle, + SkuCode: sub.SkuCode, + ProductCode: sub.ProductCode, + }); + orderItems.push(sub.OrderItemId); + } + return { + WaybillCodeId: '', + Index: index + 1, + Id: row.Id, + IdStr: row.Id, + PlatformOrderId: row.LogicOrderId, + LogicOrderId: row.LogicOrderId, + PathFlowCode: row.PathFlowCode, + CustomerOrderId: row.PlatformOrderId, + ShopId: row.ShopId, + // 与平台前端一致:PrintInfo 传 `[1];\n`(第 1 份) + PrintInfo: '[1];\n', + OrderItems: orderItems, + Items: items, + OrderItemStrList: orderItems, + // 新单号打印:把当前号(含 Pid/WaybillCodeId)带给平台,平台据此分配下一个号 + WaybillCode: waybillCode, + WaybillCodes: buildWaybillCodesBlock(row, templateId, expressCode), + NewSellerRemark: '', + PrintRemark: '', + NewPrintRemark: '', + SellerRemark: row.SellerRemark, + BuyerRemark: row.BuyerRemark, + FxUserId: row.FxUserId, + IsSelectAllNotPrintedItem: '1', + SendType: '0', + DataFlag: row.IsCold, + Receiver: { + toFullName: row.ToName, + toMobile: row.ToPhone, + toArea: row.ToFullAddress, + toProvince: row.ToProvince, + toCity: row.ToCity, + toCounty: row.ToCounty, + toMaskAddress: `${row.ToTown || ''}${row.ToAddress || ''}`, + }, + Sender: { CompanyName: '' }, + Buyer: { BuyerWangWang: row.ToName }, + }; +} + +/** + * 构造取号报文的 `Orders` 数组(多包裹时同一订单行重复 N 份) + * @param {Array} rows 平台订单行 + * @param {Object} options 参数 + * @param {string} options.templateId 面单模板ID + * @param {string} [options.expressCode] 快递编码 + * @param {number} [options.repeat] 复制份数(包裹张数,默认 1) + * @return {Array} Orders 数组 + */ +function buildExpressPrintOrders(rows, { templateId, expressCode = '', repeat = 1 } = {}) { + const count = Number.isFinite(Number(repeat)) && Number(repeat) > 1 ? Math.floor(Number(repeat)) : 1; + const sourceRows = []; + for (let i = 0; i < count; i += 1) sourceRows.push(...(rows || [])); + const first = (rows || [])[0] || {}; + const currentWaybillCode = deriveCurrentWaybillCode(first); + return sourceRows.map((row, index) => buildExpressPrintOrder(row, { + templateId, expressCode, index, currentWaybillCode, + })); +} + +/** + * 取号失败的可读原因 + * + * 平台的逐单错误放在 `ErrMsg` / `ErrCode`(实测 `15002`「非抖店订单,无法使用抖音电子面单 + * 取号打印,请用抖店平台订单号重新创建线下单再重试」),早先只读 `ErrorMsg` / `Message`, + * 结果用户只看到「平台返回取号失败」,真实原因查不到。 + * @param {Object} item 平台返回的逐单结果(Data.WaybillCode[n]) + * @return {string} 可读原因,含 ErrCode + */ +function describeWaybillError(item) { + const data = item || {}; + const orderInfo = data.OrderInfo || {}; + const order = orderInfo.Order || {}; + const message = data.ErrorMsg || data.ErrMsg || data.Message + || orderInfo.ErrorMsg || orderInfo.ErrMsg + || order.ErrorMsg || order.ErrMsg || ''; + const code = data.ErrCode || data.ErrorCode || orderInfo.ErrCode || order.ErrCode || ''; + if (!message) return code ? `平台返回取号失败(ErrCode=${code})` : '平台返回取号失败'; + return code ? `${message}(ErrCode=${code})` : message; +} + /** 订单列表单页条数(平台允许 500) */ const ORDER_PAGE_SIZE = 500; - /** 订单查询的最大翻页数,防御平台分页异常 */ const ORDER_MAX_PAGES = 200; @@ -2811,13 +2931,16 @@ class DgjService extends PrintPlatformService { const errorItem = items.find(item => item && (item.IsError === true || Number(item.IsError) === 1)); if (errorItem) { - const reason = errorItem.ErrorMsg || errorItem.Message || (errorItem.OrderInfo && errorItem.OrderInfo.ErrorMsg) || '平台返回取号失败'; - throw buildPlatformError(`店管家取号失败:${reason}`, { status: 200, json: printed, text: '' }); + throw buildPlatformError(`店管家取号失败:${describeWaybillError(errorItem)}`, { status: 200, json: printed, text: '' }); } const waybillCodes = extractWaybillCodes(items); if (!waybillCodes.length) { - throw buildPlatformError('店管家未返回运单号:请检查模板与订单状态,或查看原始响应', { status: 200, json: printed, text: '' }); + const firstMessage = items.map(item => describeWaybillError(item)).find(text => text && text !== '平台返回取号失败'); + throw buildPlatformError( + `店管家未返回运单号${firstMessage ? `:${firstMessage}` : ':请检查模板与订单状态,或查看原始响应'}`, + { status: 200, json: printed, text: '' } + ); } const document = firstPrintDocument(printed, waybillCodes[0]); @@ -3039,11 +3162,6 @@ class DgjService extends PrintPlatformService { async expressPrint(host, { traceId, dbname, templateId, rows, checkData, packageCount = 1, expressCode = '', reuseWaybill = false }) { const data = checkData || {}; const repeat = Number.isFinite(Number(packageCount)) && Number(packageCount) > 1 ? Math.floor(Number(packageCount)) : 1; - const currentWaybillCode = (() => { - const row = (rows || [])[0] || {}; - const list = Array.isArray(row.WaybillCodes) ? row.WaybillCodes.filter(item => item && item.WaybillCode) : []; - return String(row.LastWaybillCode || (list[list.length - 1] || {}).WaybillCode || '').trim(); - })(); const branches = Array.isArray(data.Branches) ? data.Branches.map(branch => { const copy = { ...branch }; for (const key of Object.keys(copy)) { @@ -3055,63 +3173,7 @@ class DgjService extends PrintPlatformService { }) : ''; // 多包裹:同一订单行重复 N 份,Index 依次 1..N(平台按包裹各分配一个运单号) - const sourceRows = []; - for (let i = 0; i < repeat; i += 1) sourceRows.push(...(rows || [])); - - const orders = sourceRows.map((row, index) => { - const items = []; - const orderItems = []; - for (const sub of Array.isArray(row.SubOrders) ? row.SubOrders : []) { - items.push({ - OrderItemId: sub.OrderItemId, - OrderItemCode: sub.OrderItemCode, - Quantity: '1', - ShortTitle: sub.ShortTitle, - SkuCode: sub.SkuCode, - ProductCode: sub.ProductCode, - }); - orderItems.push(sub.OrderItemId); - } - return { - WaybillCodeId: '', - Index: index + 1, - Id: row.Id, - IdStr: row.Id, - PlatformOrderId: row.LogicOrderId, - LogicOrderId: row.LogicOrderId, - PathFlowCode: row.PathFlowCode, - CustomerOrderId: row.PlatformOrderId, - ShopId: row.ShopId, - // 与平台前端一致:PrintInfo 传 `[1];\n`(第 1 份) - PrintInfo: '[1];\n', - OrderItems: orderItems, - Items: items, - OrderItemStrList: orderItems, - // 新单号打印:把当前号(含 Pid/WaybillCodeId)带给平台,平台据此分配下一个号 - WaybillCode: currentWaybillCode, - WaybillCodes: buildWaybillCodesBlock(row, templateId, expressCode), - NewSellerRemark: '', - PrintRemark: '', - NewPrintRemark: '', - SellerRemark: row.SellerRemark, - BuyerRemark: row.BuyerRemark, - FxUserId: row.FxUserId, - IsSelectAllNotPrintedItem: '1', - SendType: '0', - DataFlag: row.IsCold, - Receiver: { - toFullName: row.ToName, - toMobile: row.ToPhone, - toArea: row.ToFullAddress, - toProvince: row.ToProvince, - toCity: row.ToCity, - toCounty: row.ToCounty, - toMaskAddress: `${row.ToTown || ''}${row.ToAddress || ''}`, - }, - Sender: { CompanyName: '' }, - Buyer: { BuyerWangWang: row.ToName }, - }; - }); + const orders = buildExpressPrintOrders(rows, { templateId, expressCode, repeat }); const form = buildPhpForm({ TemplateId: String(templateId), @@ -3580,6 +3642,35 @@ class DgjService extends PrintPlatformService { static buildForm(data) { return buildPhpForm(data); } + + /** + * 取号失败原因解析(逐单结果 → 可读文案) + * @param {Object} item 平台返回的逐单结果 + * @return {string} 可读原因 + */ + static describeWaybillError(item) { + return describeWaybillError(item); + } + + /** + * 打印「我们实际发给平台的取号订单报文」(排错用:取号记录里只有平台回显) + * @param {Object} row 平台订单行 + * @param {Object} options 参数(templateId / expressCode / index / currentWaybillCode) + * @return {Object} Orders[i] 报文 + */ + static buildExpressPrintOrder(row, options) { + return buildExpressPrintOrder(row, options); + } + + /** + * 构造取号报文的 Orders 数组(多包裹时同一订单行重复 N 份) + * @param {Array} rows 平台订单行 + * @param {Object} options 参数(templateId / expressCode / repeat) + * @return {Array} Orders 数组 + */ + static buildExpressPrintOrders(rows, options) { + return buildExpressPrintOrders(rows, options); + } } module.exports = DgjService; diff --git a/backend/test/app/lib/dgjExpressPrintPayload.test.js b/backend/test/app/lib/dgjExpressPrintPayload.test.js new file mode 100644 index 0000000..9badcf0 --- /dev/null +++ b/backend/test/app/lib/dgjExpressPrintPayload.test.js @@ -0,0 +1,89 @@ +'use strict'; + +const { assert } = require('egg-mock/bootstrap'); +const DgjService = require('../../../app/lib/printPlatform/dgj'); + +/** + * 取号请求报文(`ExpressPrint` 的 `Orders[i]`)构造。 + * + * 抽成纯函数是为了排错时能把「实际发给平台的报文」打出来 —— `waybill_fetch_records` + * 只存平台回显,没有请求体。这里锁住字段映射,避免以后调字段时又说不清「差异在哪」。 + */ +describe('dgj.buildExpressPrintOrder 取号请求报文', () => { + const row = { + Id: '10000289308857', + LogicOrderId: '10000289308857', + PlatformOrderId: '3316563626158027487', + PathFlowCode: '10000001412039', + ShopId: 7398588, + FxUserId: 1227061, + IsCold: 0, + ToName: '张*', + ToPhone: '157****6483-2116', + ToProvince: '河南省', + ToCity: '漯河市', + ToCounty: '舞阳县', + ToTown: '舞泉镇', + ToAddress: '北京路哆哆潮品服装店', + ToFullAddress: '河南省漯河市舞阳县舞泉镇 北京路哆哆潮品服装店', + SubOrders: [ + { OrderItemId: '10000314681299', OrderItemCode: '10000314681299', SkuCode: '006-1', ProductCode: '10000053027651' }, + ], + }; + + it('订单级字段按平台前端口径映射', () => { + const order = DgjService.buildExpressPrintOrder(row, { templateId: '12360764', expressCode: 'YUNDA' }); + assert.strictEqual(order.Index, 1); + assert.strictEqual(order.Id, '10000289308857'); + // 平台单号(抖店单号)放 CustomerOrderId,店管家系统编号放 LogicOrderId/PlatformOrderId + assert.strictEqual(order.CustomerOrderId, '3316563626158027487'); + assert.strictEqual(order.LogicOrderId, '10000289308857'); + assert.strictEqual(order.PlatformOrderId, '10000289308857'); + assert.strictEqual(order.ShopId, 7398588); + assert.strictEqual(order.FxUserId, 1227061); + assert.strictEqual(order.PrintInfo, '[1];\n'); + assert.strictEqual(order.IsSelectAllNotPrintedItem, '1'); + }); + + it('明细按 SubOrders 逐条下发,OrderItems 与 Items 同源', () => { + const order = DgjService.buildExpressPrintOrder(row, { templateId: '12360764' }); + assert.deepStrictEqual(order.OrderItems, [ '10000314681299' ]); + assert.deepStrictEqual(order.OrderItemStrList, [ '10000314681299' ]); + assert.deepStrictEqual(order.Items, [{ + OrderItemId: '10000314681299', + OrderItemCode: '10000314681299', + Quantity: '1', + ShortTitle: undefined, + SkuCode: '006-1', + ProductCode: '10000053027651', + }]); + }); + + it('收件人按平台字段映射,脱敏值原样透传', () => { + const order = DgjService.buildExpressPrintOrder(row, { templateId: '12360764' }); + assert.deepStrictEqual(order.Receiver, { + toFullName: '张*', + toMobile: '157****6483-2116', + toArea: '河南省漯河市舞阳县舞泉镇 北京路哆哆潮品服装店', + toProvince: '河南省', + toCity: '漯河市', + toCounty: '舞阳县', + toMaskAddress: '舞泉镇北京路哆哆潮品服装店', + }); + }); + + it('多包裹时同一订单行重复下发,Index 递增', () => { + const orders = DgjService.buildExpressPrintOrders([ row ], { templateId: '12360764', repeat: 2 }); + assert.strictEqual(orders.length, 2); + assert.deepStrictEqual(orders.map(item => item.Index), [ 1, 2 ]); + assert.deepStrictEqual(orders.map(item => item.LogicOrderId), [ '10000289308857', '10000289308857' ]); + }); + + it('平台已有运单号时作为当前号下发(新单号打印据此换号)', () => { + const order = DgjService.buildExpressPrintOrder( + { ...row, LastWaybillCode: '435434980095250', WaybillCodes: [{ WaybillCode: '435434980095251' }] }, + { templateId: '12360764' } + ); + assert.strictEqual(order.WaybillCode, '435434980095250'); + }); +}); diff --git a/backend/test/app/lib/dgjWaybillError.test.js b/backend/test/app/lib/dgjWaybillError.test.js new file mode 100644 index 0000000..7e13247 --- /dev/null +++ b/backend/test/app/lib/dgjWaybillError.test.js @@ -0,0 +1,43 @@ +'use strict'; + +const { assert } = require('egg-mock/bootstrap'); +const DgjService = require('../../../app/lib/printPlatform/dgj'); + +/** + * 取号失败的逐单错误解析。 + * + * 实测(生产 18:49):1688 抖音分销单用抖音模板取号,平台返回 + * `{"IsError":true,"ErrCode":"15002","ErrMsg":"非抖店订单,无法使用抖音电子面单取号打印…"}`, + * 旧代码只读 `ErrorMsg` / `Message`,用户侧只看到「平台返回取号失败」,查不到真实原因。 + */ +describe('dgj.describeWaybillError 取号失败原因', () => { + it('优先取 ErrMsg 并带上 ErrCode(真实响应结构)', () => { + const message = DgjService.describeWaybillError({ + IsError: true, + ErrCode: '15002', + ErrMsg: '非抖店订单,无法使用抖音电子面单取号打印,请用抖店平台订单号重新创建线下单再重试。', + }); + assert.strictEqual( + message, + '非抖店订单,无法使用抖音电子面单取号打印,请用抖店平台订单号重新创建线下单再重试。(ErrCode=15002)' + ); + }); + + it('兼容 ErrorMsg / Message 等历史字段', () => { + assert.strictEqual(DgjService.describeWaybillError({ ErrorMsg: '模板未配置' }), '模板未配置'); + assert.strictEqual(DgjService.describeWaybillError({ Message: '余额不足' }), '余额不足'); + assert.strictEqual( + DgjService.describeWaybillError({ ErrMsg: '地址超区', ErrorMsg: '' }), + '地址超区' + ); + }); + + it('只有 ErrCode 没有文案时也把它透出来', () => { + assert.strictEqual(DgjService.describeWaybillError({ ErrCode: '15002' }), '平台返回取号失败(ErrCode=15002)'); + }); + + it('什么都没有时回落到默认文案', () => { + assert.strictEqual(DgjService.describeWaybillError({}), '平台返回取号失败'); + assert.strictEqual(DgjService.describeWaybillError(null), '平台返回取号失败'); + }); +}); diff --git a/店管家取号-旧系统提取.md b/店管家取号-旧系统提取.md index b49a893..81e8661 100644 --- a/店管家取号-旧系统提取.md +++ b/店管家取号-旧系统提取.md @@ -632,8 +632,33 @@ WaybillCodeCreateDate='2026-11-04 08:20:37' } ``` -### 4.5 取号响应 +### 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` +在成功与失败响应里都一样,可以排除)。这类单只能在店管家侧解决: +重新授权「抖音分销」(`https://auth.dgjapp.com/auth/douyinfx`)后同步该单, +或按平台提示用抖店平台订单号在店管家建线下单再取号 —— OMS 侧重试即可。 + +取号失败原因的透出:平台的逐单错误在 `Data.WaybillCode[n].ErrCode / ErrMsg`, +`DgjService.describeWaybillError` 会拼成「ErrMsg(ErrCode=…)」写进 `waybill_fetch_records.error_message`, +不再只剩一句「平台返回取号失败」。 + +### 4.5 取号响应 旧系统只用到的两个字段: ```php