fix(send): 发货回传遇平台 500 时改用实时订单行重发

线上「意洁」全部订单发货回传失败,文案只有 `店管家发货同步失败:12;ErrorCode=500`。
用同一账号对平台做对照实验(真实订单)确认:同一个单用**平台实时订单行**发送
`IsSuccess:true`;用本地快照行但清空 `SubOrders` 则回
`{"Success":false,"ErrorCode":"500","Message":"服务器繁忙,请稍会儿再试."}`。
即 500 是「平台没解析订单报文」,与订单业务状态无关。

- 新增 lib/platformError.isPayloadRejected:ErrorCode>=500 / 服务器繁忙 / 系统异常 /
  Message 只有一串数字 → 报文类失败;业务类(不是待发货、都没打印、风控拦截、请先勾选)与限流不算
- resolveSendRow:本地快照拼出的行若 SubOrders 为空则不使用,改回读平台实时订单行(warn 留痕)
- syncOrder:命中报文类失败时用 forceRemote 回读订单行重发一次,成功即置「已同步」
- recordFailure:把平台原始返回写进日志,便于下次直接定位缺了哪个字段
- 单测 platformError.test.js;文档补 §2.1.1(对照实验表 + 兜底三步)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-07 22:04:37 +08:00
parent b7da68a40c
commit 9f067c1b58
5 changed files with 186 additions and 17 deletions

View File

@ -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 };

View File

@ -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 店管家订单原始结构

View File

@ -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<Object|null>} 订单行
*/
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 };
}

View File

@ -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);
});
});

View File

@ -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 同步异常),由「配送异常」视图筛出来处理。
表变大靠索引和归档兜底: