fix(dgj): 补齐 listOrders 的 scanHost 定义,并补快手 key / 菜鸟 templateURL 打印字段

1) 修正 F47D8CC 的漏提:那次只提交了「补查其它域名」的调用侧
   (`for (const host of hosts) await scanHost(host);`),把 `const scanHost = async host => {`
   的定义留在了工作区,HEAD 上 `listOrders` 会 ReferenceError。本次一并补齐,HEAD 与工作区一致。

2) 面单打印字段按平台口径区分(WMS 侧联调结论):
   - 快手(KS):printinfo = encryptedData,encryptprintinfo / key = 逐单密钥(原口径不变)
   - 菜鸟系(TB / TM / TGC / 1688):平台 printInfo 为空,菜鸟打印只认整包 JSON
     `{ encryptedData, signature, ver, templateURL }`,按该形态回拼 printinfo;
     templateURL 取 `contents[0].templateURL`
   - 其它平台:printinfo 原样用平台下发数据
   - `extractDocumentContents` 增加 template_url 字段(缺失时为空串)

3) 单测:printPlatformDgj.test.js 覆盖 template_url 解析与淘宝/快手/其它平台三种口径,
   test/app/lib 73 passing;eslint 干净

4) 文档:WMS-OMS-取号对接.md 追加 WMS 侧核实记录(快手 printinfo 未落库的报文缺字段结论、
   打印数据形态兼容、菜鸟 templateURL 模板要求与对账表)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-07 20:33:33 +08:00
parent f47d8ccdec
commit 511f7abf94
3 changed files with 118 additions and 23 deletions

View File

@ -169,11 +169,11 @@ OMS 侧实现:`D:\oms\backend\app\lib\wms\sign.js`。
"waybill_codes": ["78812345678901"],
"package_index": 0,
"cai_niao_auth_info_id": 364375,
"printinfo": "eyJQYXBlclNpemUiOi...",
"signature": "MEQCIB...",
"encryptprintinfo": "",
"printinfo": "{\"encryptedData\":\"AES:rU904…\",\"signature\":\"MD:xNFh…\",\"ver\":\"waybill_print_secret_version_1\",\"templateURL\":\"http://cloudprint.cainiao.com/template/standard/304351\"}",
"signature": "MD:xNFh…",
"encryptprintinfo": "AES:rU904…",
"key": "",
"ver": "",
"ver": "waybill_print_secret_version_1",
"print_history_ids": [
{ "id": "10000078656002", "pid": "3316997317085033076", "waybill_code": "78812345678901", "batch_index": 1 }
],
@ -204,7 +204,7 @@ OMS 侧实现:`D:\oms\backend\app\lib\wms\sign.js`。
| `waybill_codes` | 成功 | 全部运单号(当前每次取号只对应 1 个包裹,恒为单元素) |
| `package_index` | 成功 | 本次取号对应的包裹序号(0 基),回显便于核对「这个号是哪个包裹的」 |
| `cai_niao_auth_info_id` | 成功 | **菜鸟授权网点ID**(模板绑定的 `CaiNiaoAuthInfoId`,如视频号 `6890457`、淘宝 `364375/393235`);同平台不同授权网点取值不同,WMS 需要按网点归集/对账时用它,取不到为 `null` |
| `printinfo` | 成功 | **面单打印数据**,打单平台原样返回:店管家取 `Data.PrintDataList.task.documents[].printInfo`(base64 的 URL-encoded JSON);**快手取 `documents[].contents[0].encryptedData`**(快手该单据的 `printInfo` 为空)。WMS 落 `order_express.printinfo`,打印时**原样**塞进 `task.printInfo`,不要解码 |
| `printinfo` | 成功 | **面单打印数据**,打单平台原样返回:店管家取 `Data.PrintDataList.task.documents[].printInfo`(base64 的 URL-encoded JSON);**快手取 `documents[].contents[0].encryptedData`**(快手该单据的 `printInfo` 为空);**菜鸟系(TB/TM/TGC/1688)回拼整包 JSON** `{"encryptedData","signature","ver","templateURL"}`(模板地址取 `contents[0].templateURL`,菜鸟云打印必需)。WMS 落 `order_express.printinfo`,打印时**原样**塞进 `task.printInfo`,不要解码 |
| `signature` | 成功 | 面单签名,取 `documents[].contents[0].signature`;视频号自定义模板平台不返回 `contents`,此时为空串 |
| `encryptprintinfo` | 成功 | 加密打印数据:其它平台取 `contents[0].encryptedData`;**快手取 `contents[0].key`**(与菠萝派口径一致,WMS 快手打印的 `key` 参数) |
| `key` | 成功 | **快手逐单加密密钥**(base64,约 172 字符,逐单不同),取 `contents[0].key`;其余平台为空串 |
@ -1221,3 +1221,37 @@ WMS 现有快手分支(`encryptedData ← printinfo`、`key ← encryptprintin
- 新增 `test/verify_kuaishou_print_payload.js` 12 例;全部回归脚本合计 12+22+18+23+24+19+16 = 134 例通过。
wms/
---
## WMS 侧确认 OMS 快手修复(前置提交 e0c718a)(2026-11-07 19:10)
### 1. 已核对 OMS 提交
`e0c718a fix(waybill): 快手取号补齐 key 与加密面单字段` 的实现与 WMS 打印口径一致:
- `extractDocumentContents` 取 `contents[0].encryptedData` / `contents[0].key` / `signature` / `ver`;
- `buildWaybillPrintFields`:快手单 `printinfo = encryptedData(密文)`、`encryptprintinfo = key(密钥)`,并新增响应字段 `key`;其它平台保持原口径(`printinfo = documents[].printInfo`、`encryptprintinfo = encryptedData`)。
### 2. WMS 端到端仿真(按修复后口径)
| 环节 | 结果 |
|---|---|
| 落库字段 | `printinfo` 长 3648(密文)、`encryptprintinfo` 长 172(密钥)、`signature` 32、`ver=1` |
| 菜鸟回拼逻辑 | 快手单正确跳过(`buildOmsCainiaoPrintinfo` 返回空) |
| 快手打印 content | `keys = addData, encryptedData, signature, key, templateURL, ver`;`encryptedData` 3648、`key` 172、`signature`/`ver` 正确 |
| 快手告警 | 无(不再出现「key 疑似为密文」) |
结论:**WMS 无需为快手再改代码**,OMS 修复上线后即可打印。
### 3. WMS 侧新增兜底(本轮)
`express_platform.oms` 落库时,若 `encryptprintinfo` 为空而响应带 `key`(快手平台),用 `key` 兜底写入 `encryptprintinfo`,
防止 OMS 灰度期只上了 `key` 字段的情况。134 例回归全绿,eslint 通过。
### 4. 下一步
WMS 侧待发布(打印层兼容 + 菜鸟 printinfo 回拼 + 本次 key 兜底),发布后建议实测一单快手:
取号 → 查 `wms_order_express.printinfo/encryptprintinfo` 长度(约 3.4–3.8KB / 172)→ 打印验证。
wms/

View File

@ -795,13 +795,14 @@ function firstPrintInfo(items, printed, waybillCode) {
*
* 旧系统 `Dianguanjia.php` 取的是
* `PrintDataList.task.documents[0].contents[0]` 的 `signature` / `encryptedData` / `ver`;
* 快手还会下发逐单加密密钥 `key`(base64,约 172 字符,与密文不同),打印端必需。
* 快手还会下发逐单加密密钥 `key`(base64,约 172 字符,与密文不同),打印端必需;
* 菜鸟系(淘宝/天猫等)另外下发主面单模板地址 `templateURL`(菜鸟打印必需)。
* 视频号等自定义模板场景平台不返回 `contents`,此时各值都为空串。
* @param {Object} document 打印单据
* @return {{signature: string, encryptprintinfo: string, key: string, ver: string}} 签名、加密打印数据、快手密钥、版本
* @return {{signature: string, encryptprintinfo: string, key: string, template_url: string, ver: string}} 签名、加密打印数据、快手密钥、模板地址、版本
*/
function extractDocumentContents(document) {
const empty = { signature: '', encryptprintinfo: '', key: '', ver: '' };
const empty = { signature: '', encryptprintinfo: '', key: '', template_url: '', ver: '' };
const contents = document && document.contents;
const first = Array.isArray(contents) ? contents[0] : null;
if (!first || typeof first !== 'object') return empty;
@ -809,17 +810,22 @@ function extractDocumentContents(document) {
signature: typeof first.signature === 'string' ? first.signature : '',
encryptprintinfo: typeof first.encryptedData === 'string' ? first.encryptedData : '',
key: typeof first.key === 'string' ? first.key : '',
template_url: typeof first.templateURL === 'string' ? first.templateURL : '',
ver: first.ver == null ? '' : String(first.ver),
};
}
/** 菜鸟系平台(菜鸟打印只认 printinfo 整包 JSON,见 buildWaybillPrintFields) */
const CAINIAO_PLATFORM_CODES = new Set([ 'TB', 'TM', 'TGC', '1688' ]);
/**
* 组装回给 WMS 的面单打印字段
* 组装回给 WMS 的面单打印字段(各平台口径不同)
*
* 快手(KS)与其它平台口径不同:
* - 快手:平台把加密面单放在 `contents[0].encryptedData`、逐单密钥放在 `contents[0].key`,
* - 快手(KS):平台把加密面单放在 `contents[0].encryptedData`、逐单密钥放在 `contents[0].key`,
* 文档里的 `printInfo` 为空。菠萝派取号的做法是「密文 -> printinfo、密钥 -> encryptprintinfo」,
* WMS 快手打印按该口径取 encryptedData / key,这里对齐,并把 key 单独返回;
* - 菜鸟系(淘宝/天猫/淘工厂/1688):平台下发的 `printInfo` 为空,
* 菜鸟打印只认整包 JSON `{ encryptedData, signature, ver, templateURL }`,这里按该形态回拼;
* - 其它平台:`printinfo` 原样用平台下发的打印数据,`encryptprintinfo` 仍是 `contents[0].encryptedData`。
* @param {Object} options 参数
* @param {string} options.platformCode 系统预设平台编码(如 KS / TB)
@ -828,13 +834,37 @@ function extractDocumentContents(document) {
* @return {{printinfo: string, encryptprintinfo: string, key: string}} 打印字段
*/
function buildWaybillPrintFields({ platformCode, contents, documentPrintInfo = '' }) {
const isKuaishou = String(platformCode || '').trim().toUpperCase() === 'KS';
const code = String(platformCode || '').trim().toUpperCase();
const encryptedData = String((contents && contents.encryptprintinfo) || '');
const key = String((contents && contents.key) || '');
const printData = String(documentPrintInfo || '');
if (code === 'KS') {
return {
printinfo: encryptedData || printData,
encryptprintinfo: key,
key,
};
}
if (CAINIAO_PLATFORM_CODES.has(code) && !printData && encryptedData) {
const payload = { encryptedData };
const signature = String((contents && contents.signature) || '');
const version = String((contents && contents.ver) || '');
const templateUrl = String((contents && contents.template_url) || '');
if (signature) payload.signature = signature;
if (version) payload.ver = version;
if (templateUrl) payload.templateURL = templateUrl;
return {
printinfo: JSON.stringify(payload),
encryptprintinfo: encryptedData,
key,
};
}
return {
printinfo: isKuaishou ? (encryptedData || printData) : printData,
encryptprintinfo: isKuaishou ? key : encryptedData,
printinfo: printData,
encryptprintinfo: encryptedData,
key,
};
}
@ -1903,7 +1933,12 @@ class DgjService extends PrintPlatformService {
// 店铺没有声明该平台的老分区(只有新系统分区)时,该平台的老分区属于迁移前遗留数据,跳过不拉
const skippedLegacy = [];
const areaFlags = this.resolveAreaFlags(data);
for (const host of hosts) {
/**
* 扫一个域名下的全部分区
* @param {string} host 订单接口域名
* @return {Promise<void>} 无返回值
*/
const scanHost = async host => {
// 商家分区声明里没有该平台的记录时,按「新旧分区都要查」处理,宁可多查也不漏单
const flags = areaFlags[host] || { hasNew: true, hasLegacy: true };
const areas = await this.listProductAreas(host);

View File

@ -92,24 +92,26 @@ describe('printPlatform/dgj extractDocumentContents', () => {
assert.strictEqual(contents.key, 'MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQ==');
assert.strictEqual(contents.signature, 'MEQCIB');
assert.strictEqual(contents.ver, '1');
assert.strictEqual(contents.template_url, 'https://example.com/t.json');
});
it('没有 contents 时各字段为空串', () => {
assert.deepStrictEqual(DgjService.extractDocumentContents(null), {
signature: '', encryptprintinfo: '', key: '', ver: '',
signature: '', encryptprintinfo: '', key: '', template_url: '', ver: '',
});
assert.deepStrictEqual(DgjService.extractDocumentContents({ printInfo: 'x' }), {
signature: '', encryptprintinfo: '', key: '', ver: '',
signature: '', encryptprintinfo: '', key: '', template_url: '', ver: '',
});
});
});
describe('printPlatform/dgj buildWaybillPrintFields', () => {
const contents = {
signature: 'SIG',
encryptprintinfo: 'ENCRYPTED_DATA',
signature: 'MD:xNFhrlrQ7keXD+RciHKOWA==',
encryptprintinfo: 'AES:rU904rj6UH2oqfSUb43+Z199',
key: 'PER_ORDER_KEY',
ver: '1',
template_url: 'http://cloudprint.cainiao.com/template/standard/304351',
ver: 'waybill_print_secret_version_1',
};
it('快手:printinfo 用 encryptedData,encryptprintinfo/key 都用逐单密钥', () => {
@ -119,7 +121,7 @@ describe('printPlatform/dgj buildWaybillPrintFields', () => {
documentPrintInfo: '',
});
assert.deepStrictEqual(fields, {
printinfo: 'ENCRYPTED_DATA',
printinfo: 'AES:rU904rj6UH2oqfSUb43+Z199',
encryptprintinfo: 'PER_ORDER_KEY',
key: 'PER_ORDER_KEY',
});
@ -135,15 +137,39 @@ describe('printPlatform/dgj buildWaybillPrintFields', () => {
assert.strictEqual(fields.key, 'PER_ORDER_KEY');
});
it('其它平台:printinfo 原样,encryptprintinfo 仍是密文', () => {
it('淘宝:printinfo 回拼菜鸟整包 JSON(含模板地址),encryptprintinfo 仍是密文', () => {
const fields = DgjService.buildWaybillPrintFields({
platformCode: 'TB',
contents,
documentPrintInfo: '',
});
assert.deepStrictEqual(JSON.parse(fields.printinfo), {
encryptedData: 'AES:rU904rj6UH2oqfSUb43+Z199',
signature: 'MD:xNFhrlrQ7keXD+RciHKOWA==',
ver: 'waybill_print_secret_version_1',
templateURL: 'http://cloudprint.cainiao.com/template/standard/304351',
});
assert.strictEqual(fields.encryptprintinfo, 'AES:rU904rj6UH2oqfSUb43+Z199');
});
it('淘宝:平台已下发 printInfo 时保持原值,不覆盖', () => {
const fields = DgjService.buildWaybillPrintFields({
platformCode: 'TB',
contents,
documentPrintInfo: 'PLAIN_PRINT_DATA',
});
assert.strictEqual(fields.printinfo, 'PLAIN_PRINT_DATA');
});
it('其它平台:printinfo 原样,encryptprintinfo 仍是密文', () => {
const fields = DgjService.buildWaybillPrintFields({
platformCode: 'PDD',
contents,
documentPrintInfo: 'PLAIN_PRINT_DATA',
});
assert.deepStrictEqual(fields, {
printinfo: 'PLAIN_PRINT_DATA',
encryptprintinfo: 'ENCRYPTED_DATA',
encryptprintinfo: 'AES:rU904rj6UH2oqfSUb43+Z199',
key: 'PER_ORDER_KEY',
});
});