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:
parent
b7da68a40c
commit
9f067c1b58
29
backend/app/lib/platformError.js
Normal file
29
backend/app/lib/platformError.js
Normal 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 };
|
||||
@ -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 店管家订单原始结构
|
||||
|
||||
@ -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 };
|
||||
}
|
||||
|
||||
|
||||
37
backend/test/app/lib/platformError.test.js
Normal file
37
backend/test/app/lib/platformError.test.js
Normal 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);
|
||||
});
|
||||
});
|
||||
@ -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 同步异常),由「配送异常」视图筛出来处理。
|
||||
表变大靠索引和归档兜底:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user