diff --git a/backend/app/lib/platformError.js b/backend/app/lib/platformError.js new file mode 100644 index 0000000..334a51d --- /dev/null +++ b/backend/app/lib/platformError.js @@ -0,0 +1,29 @@ +'use strict'; + +/** + * 平台响应「报文不被接受」判定(外部打单平台通用) + * + * 实测店管家(2026-11-07):`Orders[i][SubOrders]` 为空时直接 + * `{"Success":false,"ErrorCode":"500","Message":"服务器繁忙,请稍会儿再试."}`; + * 线上还出现过 `Message` 只回一串数字的兜底文案(`店管家发货同步失败:12;ErrorCode=500`)。 + * 这类失败与订单业务状态无关,是平台没能解析我们提交的报文, + * 改用平台实时订单行重发通常即可成功(由调用方决定是否重试)。 + */ + +/** + * @param {Object|null} json 平台响应 + * @param {string} [message] 已拼好的错误文案 + * @return {boolean} 是否为报文类失败 + */ +function isPayloadRejected(json, message = '') { + if (!json || typeof json !== 'object') return false; + const message0 = json.Message == null ? '' : String(json.Message); + const text = `${message0} ${message || ''}`; + const code = Number(json.ErrorCode); + if (Number.isFinite(code) && code >= 500) return true; + if (/服务器繁忙|系统异常/.test(text)) return true; + // Message 只有一串数字:服务端异常兜底文案,不是业务原因 + return /^\s*[0-9]{1,6}\s*$/.test(message0); +} + +module.exports = { isPayloadRejected }; diff --git a/backend/app/lib/printPlatform/dgj.js b/backend/app/lib/printPlatform/dgj.js index 20bacc1..0c4bfe8 100644 --- a/backend/app/lib/printPlatform/dgj.js +++ b/backend/app/lib/printPlatform/dgj.js @@ -2,6 +2,7 @@ const PrintPlatformService = require('./base'); const { resolvePlatform } = require('../platformCode'); +const { isPayloadRejected } = require('../platformError'); /** 店管家商家门户站点 */ const PORTAL_ORIGIN = 'https://tfxportal.dgjapp.com'; @@ -243,8 +244,7 @@ function buildSendOrder(row, index, expressCode = '') { * 收集发货回传响应里的逐单错误(各平台结构不统一,这里按常见字段兜底) * @param {Object} json 平台响应 * @return {string[]} 可读错误文案 - */ -function describeSendErrors(json) { + */function describeSendErrors(json) { const out = []; const data = json && json.Data; const list = Array.isArray(data) ? data : (data && Array.isArray(data.List) ? data.List : []); @@ -3122,8 +3122,11 @@ class DgjService extends PrintPlatformService { // 「请先勾选要发货的订单」= 平台没把提交的 Orders 当成有效选中项, // 属于报文口径问题(不是业务状态问题),补一句指向文档的提示便于排查 const notSelected = /勾选/.test(String(json.Message || '')); + // 平台只回一串数字/服务器繁忙时不是业务原因,是它没能解析我们提交的订单行(多为 SubOrders 等字段缺失) + const payloadRejected = isPayloadRejected(json); throw buildPlatformError( - `店管家发货同步失败:${reason}${notSelected ? '(平台未识别提交的订单报文,需核对 OnlineSendBatch 报文口径)' : ''}`, + `店管家发货同步失败:${reason}${notSelected ? '(平台未识别提交的订单报文,需核对 OnlineSendBatch 报文口径)' : ''}` + + `${payloadRejected ? '(平台未成功解析订单报文,将改用平台实时订单行重试)' : ''}`, res ); } @@ -3214,6 +3217,16 @@ class DgjService extends PrintPlatformService { return isRateLimited(json); } + /** + * 平台返回是否为「报文不被接受」类失败(供上层决定是否用实时订单行重发) + * @param {Object|null} json 平台响应 + * @param {string} [message] 错误文案 + * @return {boolean} 是否为报文类失败 + */ + static isPayloadRejected(json, message = '') { + return isPayloadRejected(json, message); + } + /** * 订单是否已在平台侧发货或已终结(供脚本/上层按落库的平台原始结构复用同一口径) * @param {Object} row 店管家订单原始结构 diff --git a/backend/app/service/externalSendSync.js b/backend/app/service/externalSendSync.js index ae3fe69..523a903 100644 --- a/backend/app/service/externalSendSync.js +++ b/backend/app/service/externalSendSync.js @@ -2,6 +2,7 @@ const Service = require('egg').Service; const { buildSendRow, parseOrderWaybills, parseJson } = require('../lib/dgjSendRow'); +const { isPayloadRejected } = require('../lib/platformError'); /** 外部发货同步状态 */ const SEND_STATUS = { @@ -221,10 +222,61 @@ class ExternalSendSyncService extends Service { return await this.recordFailure(order, retryErr, now); } } + + // 平台判「报文不被接受」(5xx / 服务器繁忙 / 只回一串数字):本地快照拼的报文平台解析不了, + // 直接用平台实时订单行重发一次(实测同一单换成实时行后能正常发货) + const rejectedPayload = this.isPayloadRejectedError(err); + if (rejectedPayload) { + try { + const target = await this.resolveTarget(order); + if (target) { + const host = target.service.constructor.resolveOrderHost(target.platformType); + const liveRow = await this.resolveSendRow(order, { + service: target.service, + host, + dbname: target.dbname, + platformCode: target.platformCode, + template: target.template, + fetchRecord: target.fetchRecord, + forceRemote: true, + }); + if (liveRow) { + await target.service.sendOrders(host, { + traceId: await this.resolveTraceId(target.service), + dbname: target.dbname, + rows: [ liveRow ], + templateId: target.template ? target.template.template_id : '', + expressCompanyId: target.template ? target.template.express_company_id : '', + expressCode: target.template ? target.template.express_company_code : '', + }); + await order.update({ + external_send_status: SEND_STATUS.SYNCED, + external_send_error: '', + external_send_at: now, + external_sent_at: now, + }); + ctx.logger.info('[external-send] 改用平台实时订单行后同步成功 %s', order.order_no); + return { ok: true, message: 'ok' }; + } + } + } catch (retryErr) { + ctx.logger.warn('[external-send] %s 用平台实时订单行重试仍失败:%s', order.order_no, retryErr.message); + return await this.recordFailure(order, retryErr, now); + } + } return await this.recordFailure(order, err, now); } } + /** + * 平台返回是否为「报文不被接受」类失败(判定口径见 lib/platformError) + * @param {Error} err 平台异常(buildPlatformError 会带 rawResponse) + * @return {boolean} 是否需要改用实时订单行重发 + */ + isPayloadRejectedError(err) { + return isPayloadRejected(err && err.rawResponse, err && err.message); + } + /** * 组装发货回传用的订单行:优先用本地快照(不访问平台),快照缺失才回读平台 * @param {Object} order 配送状态行 @@ -234,29 +286,34 @@ class ExternalSendSyncService extends Service { * @param {string} ctxInfo.dbname 分区库名 * @param {Object} [ctxInfo.template] 快递接口记录 * @param {Object} [ctxInfo.fetchRecord] 最近一次成功取号记录(已在 resolveTarget 查过就不再查) + * @param {boolean} [ctxInfo.forceRemote] 强制回读平台订单行(平台判报文无效时重试用) * @return {Promise} 订单行 */ - async resolveSendRow(order, { service, host, dbname, template, fetchRecord }) { + async resolveSendRow(order, { service, host, dbname, template, fetchRecord, forceRemote = false }) { const { ctx } = this; const logicalOrderId = String(order.parent_order_no || order.order_no || ''); // 1) 拉单快照:老表 orders.external_data(平台整行,含 PathFlowCode / ShippingType / SubOrders) let snapshot = null; - try { - const legacy = await ctx.model.Order.findOne({ - where: { principal_id: order.principal_id, order_no: order.order_no }, - attributes: [ 'id', 'external_data' ], - }); - snapshot = legacy && legacy.external_data ? legacy.external_data : null; - } catch { - snapshot = null; + if (!forceRemote) { + try { + const legacy = await ctx.model.Order.findOne({ + where: { principal_id: order.principal_id, order_no: order.order_no }, + attributes: [ 'id', 'external_data' ], + }); + snapshot = legacy && legacy.external_data ? legacy.external_data : null; + } catch { + snapshot = null; + } } // 2) 最近一次成功取号记录:拿最新面单信息(WaybillCodeId / Pid / 快递编码) if (!fetchRecord) fetchRecord = await this.findLatestFetchRecord(order); const localRow = buildSendRow({ order, snapshot, fetchRecord, template }); - if (localRow) { + // 平台按 SubOrders 校验收件人与商品明细,缺了会直接回 500「服务器繁忙」; + // 这种快照(老化/只存了归一化数据)不能用,退回回读平台订单行 + if (localRow && Array.isArray(localRow.SubOrders) && localRow.SubOrders.length) { // 报文里 WaybillCodes 是平台校验运单渠道的依据(WaybillCodeId / Pid / 快递编码),缺失时要能查到 const waybills = Array.isArray(localRow.WaybillCodes) ? localRow.WaybillCodes : []; if (!waybills.length) { @@ -269,9 +326,13 @@ class ExternalSendSyncService extends Service { } return localRow; } + if (localRow) { + ctx.logger.warn('[external-send] %s 本地快照缺少 SubOrders,回读平台订单行拼报文', order.order_no); + } else { + ctx.logger.info('[external-send] %s 没有本地快照,回读平台订单行', order.order_no); + } - // 3) 没有快照(历史单/非平台单):退回回读平台订单行 - ctx.logger.info('[external-send] %s 没有本地快照,回读平台订单行', order.order_no); + // 3) 没有可用快照(历史单/非平台单/快照不完整):退回回读平台订单行 return await service.findPlatformOrderRow(host, { traceId: await this.resolveTraceId(service), dbname, @@ -313,6 +374,10 @@ class ExternalSendSyncService extends Service { }); ctx.logger.warn('[external-send] 同步外部发货失败 %s(第 %d 次%s):%s', order.order_no, times, exception ? ',转异常' : '', message); + // 平台原始返回只进日志(订单页只展示可读文案):报文类失败靠它定位缺了哪个字段 + if (err && err.rawResponse) { + ctx.logger.warn('[external-send] %s 平台原始返回:%s', order.order_no, truncateText(JSON.stringify(err.rawResponse), 2000)); + } return { ok: false, message }; } diff --git a/backend/test/app/lib/platformError.test.js b/backend/test/app/lib/platformError.test.js new file mode 100644 index 0000000..68ba341 --- /dev/null +++ b/backend/test/app/lib/platformError.test.js @@ -0,0 +1,37 @@ +'use strict'; + +const { app, assert } = require('egg-mock/bootstrap'); +const { isPayloadRejected } = require('../../../app/lib/platformError'); + +describe('app/lib/platformError 报文类失败判定', () => { + it('ErrorCode >= 500 视为平台没解析报文', () => { + assert.strictEqual(isPayloadRejected({ Success: false, ErrorCode: '500', Message: '服务器繁忙,请稍会儿再试.' }), true); + assert.strictEqual(isPayloadRejected({ Success: false, ErrorCode: 500, Message: '系统异常' }), true); + }); + + it('线上出现过的「Message 只回一串数字」也算报文类失败', () => { + // 店管家发货同步失败:12;ErrorCode=500 + assert.strictEqual(isPayloadRejected({ Success: false, ErrorCode: 500, Message: '12' }), true); + assert.strictEqual(isPayloadRejected({ Success: false, ErrorCode: '500', Message: 12 }), true); + }); + + it('业务类失败不重发(订单状态、运单未打印、风控拦截)', () => { + assert.strictEqual(isPayloadRejected({ Success: false, Message: '当前选中的订单都没有打印,已取消发货' }), false); + assert.strictEqual(isPayloadRejected({ Success: false, Message: '订单不是待发货状态,请检查' }), false); + assert.strictEqual(isPayloadRejected({ Success: false, Message: '风控拦截#NOT_MATCH_SEGMENT_CHANNEL#' }), false); + assert.strictEqual(isPayloadRejected({ Success: false, Message: '请先勾选要发货的订单' }), false); + }); + + it('限流与空响应不当成报文问题', () => { + assert.strictEqual(isPayloadRejected({ Success: false, Message: 'isv.request-limited 请求太频繁' }), false); + assert.strictEqual(isPayloadRejected(null), false); + assert.strictEqual(isPayloadRejected('text'), false); + }); + + it('平台服务实例复用同一口径', () => { + const DgjService = require('../../../app/lib/printPlatform/dgj'); + assert.strictEqual(DgjService.isPayloadRejected({ ErrorCode: 500, Message: '12' }), true); + assert.strictEqual(DgjService.isPayloadRejected({ Message: '订单不是待发货状态,请检查' }), false); + assert.ok(app); + }); +}); diff --git a/店管家取号-旧系统提取.md b/店管家取号-旧系统提取.md index d6da0ab..3585b25 100644 --- a/店管家取号-旧系统提取.md +++ b/店管家取号-旧系统提取.md @@ -121,7 +121,6 @@ NOT_MATCH_SEGMENT_CHANNEL#…此运单号非抖音的运单号…`。 | 760000000000000(不存在) | 无 | 返回 null 并 `warn`,报文不带别人的面单标识 | **请求量控制(避免被平台判成刷单/攻击,以及服务商级 QPS 限流)**: - 店管家对请求量有两道闸:**风控/刷单判定**(行为特征)和 **服务商级 QPS 限流** (实测返回 `isv.request-limited 请求太频繁…配置限流QPS:600, 当前访问QPS:687`)。 后者是全 ISV 共享的额度,我们自己的突发只是其中一部分,所以既要把自己的峰值削平, @@ -132,12 +131,38 @@ NOT_MATCH_SEGMENT_CHANNEL#…此运单号非抖音的运单号…`。 | 全局请求间隔 | `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` | +| 发货不回读订单行 | 快照拼报文,每单只有 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`): + +1. `resolveSendRow` 拼完本地行先做完整性校验:**`SubOrders` 为空就不用它**,改回读平台实时订单行(`warn` 留痕); +2. `syncOrder` 捕获到报文类失败(`lib/platformError.isPayloadRejected`:`ErrorCode>=500` / 服务器繁忙 / 系统异常 / `Message` 只有一串数字)时, + 用 `forceRemote` 重新回读订单行并**重发一次**,成功即置「已同步」; +3. 仍失败时把平台原始返回写进日志(`平台原始返回:{…}`),订单页只留可读文案。 + +判定口径刻意排除业务类失败:「不是待发货状态」「当前选中的订单都没有打印」「风控拦截」「请先勾选要发货的订单」 +以及限流文案——这些重发也没用,按原逻辑计数/提示。 + + **失败单不转表**:进了配送说明仓库已打包发货,是既成事实,必须留在配送表可见/可导出; 只在配送表标记 `external_send_status`(2 待重试 / 3 同步异常),由「配送异常」视图筛出来处理。 表变大靠索引和归档兜底: