fix(waybill): 快手取号补齐 key 与加密面单字段

- dgj: 抽取 contents[0].key;快手单 printinfo 取 encryptedData、encryptprintinfo 取逐单密钥(对齐菠萝派口径)
- waybillGet: deliveryorder.getwaybill 响应新增 key 字段并透传给 WMS
- 探测脚本输出 encryptprintinfo/key 长度;补充单测
- 更新 WMS-OMS 取号对接文档的快手字段说明

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-07 19:05:36 +08:00
parent b22730fdcb
commit e0c718af8e
5 changed files with 198 additions and 10 deletions

View File

@ -171,6 +171,9 @@ OMS 侧实现:`D:\oms\backend\app\lib\wms\sign.js`。
"cai_niao_auth_info_id": 364375,
"printinfo": "eyJQYXBlclNpemUiOi...",
"signature": "MEQCIB...",
"encryptprintinfo": "",
"key": "",
"ver": "",
"print_history_ids": [
{ "id": "10000078656002", "pid": "3316997317085033076", "waybill_code": "78812345678901", "batch_index": 1 }
],
@ -201,15 +204,16 @@ 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)。WMS 落 `order_express.printinfo`,打印时**原样**塞进 `task.printInfo`,不要解码 |
| `printinfo` | 成功 | **面单打印数据**,打单平台原样返回:店管家取 `Data.PrintDataList.task.documents[].printInfo`(base64 的 URL-encoded JSON);**快手取 `documents[].contents[0].encryptedData`**(快手该单据的 `printInfo` 为空)。WMS 落 `order_express.printinfo`,打印时**原样**塞进 `task.printInfo`,不要解码 |
| `signature` | 成功 | 面单签名,取 `documents[].contents[0].signature`;视频号自定义模板平台不返回 `contents`,此时为空串 |
| `encryptprintinfo` | 成功 | 加密打印数据,取 `contents[0].encryptedData`(需要加密打印的平台才有值,店管家当前为空串) |
| `encryptprintinfo` | 成功 | 加密打印数据:其它平台取 `contents[0].encryptedData`;**快手取 `contents[0].key`**(与菠萝派口径一致,WMS 快手打印的 `key` 参数) |
| `key` | 成功 | **快手逐单加密密钥**(base64,约 172 字符,逐单不同),取 `contents[0].key`;其余平台为空串 |
| `ver` | 成功 | 打印数据版本,取 `contents[0].ver`(无则为空串) |
| `print_history_ids` | 成功 | **打印记录ID**(店管家 `Data.PrintHistoryIds[]`):`[{ id, pid, waybill_code, batch_index }]`,每张面单一条,WMS 自行落库。`id` 即 printHistoryId,`WaybillCode` 与 `waybill_codes` 一一对应;平台**不会**把它放进面单数据(`printinfo` 里对应字段恒为 `null`) |
| `print_history_id` | 成功 | 第一张面单的打印记录ID(`print_history_ids[0].id` 的便捷值,多包裹时以数组为准) |
> **取号结果不回写 OMS 订单表**(现阶段取号与订单表不做关联),运单号与打印数据只在响应里返回,由 WMS 自行落单。
> **WMS 仍需落自己的 `order_express`**(`waybill_code` + `printinfo` + `signature` + `encryptprintinfo` + `ver` + `cai_niao_auth_info_id` + `print_history_ids`)**/ 队列状态**,不要依赖 OMS 的库。
> **WMS 仍需落自己的 `order_express`**(`waybill_code` + `printinfo` + `signature` + `encryptprintinfo` + `ver` + `cai_niao_auth_info_id` + `print_history_ids`,快手另有 `key`)**/ 队列状态**,不要依赖 OMS 的库。
> 每次取号的平台原始返回都会写进 OMS 的 `waybill_fetch_records`(见 §4.7),出问题可直接查表对账,不必再让 WMS 重放报文。
>
> **同一包裹重复取号会拿到新号**:店管家「新单号打印」口径是每次分配一个新号(`WaybillCodePid` 第二段自增),
@ -1171,3 +1175,49 @@ wms/
若要严格保证「模板与密文同源」,建议 OMS 在 `deliveryorder.getwaybill` 响应里补一个 `template_url`
(`deliveryorder.getprintdata` 已返回同名字段),WMS 回拼 printinfo 时写进 `templateURL` 即可,
无需新增数据库字段。当前不阻塞打印。
---
## WMS 侧核实快手(KS)printinfo 未落库 —— 结论:报文缺字段(2026-11-07 18:45)
### 1. 字段对照(生产实测 + 本次 OMS 报文)
| 字段 | 菠萝派快手单(正常,id=1775133 等) | OMS 快手单(本批 `dgj-10000280095565` / `319414677101981`) | 说明 |
|---|---|---|---|
| `printinfo` | 3456–3776 字符(大写 hex 密文) | **空串** | OMS 未返回 |
| `encryptprintinfo` | **172 字符**(base64,逐单密钥) | **3648 字符(hex 密文)** | 语义相反:OMS 把密文放进了「密钥」字段 |
| `key` | 无独立列,取 `encryptprintinfo` | **缺失** | 快手打印必需 |
| `signature` | 32 字符 hex | 32 字符 hex | ✅ |
| `ver` | `1` | `1` | ✅ |
生产正常快手单的 `encryptprintinfo` 逐单不同(逐单密钥,非店铺固定),无法从配置或其他字段推导。
### 2. 快手打印契约
`printer_data_builder` 快手分支需要四个字段:
`encryptedData ← printinfo`、`key ← encryptprintinfo`、`signature`、`ver`(模板 content keys:`addData, encryptedData, signature, key, templateURL, ver`)。
因此 OMS 快手单现状是 **`encryptedData` 缺失 + `key` 被密文占位**,即使把 `encryptprintinfo` 灌进 `printinfo` 也无法打印(缺真正的 key)。
### 3. 需要 OMS 侧补齐(阻塞项)—— ✅ 已补齐(2026-11-07)
快手单请在取号响应中返回:
- `printinfo`:快手 `encryptedData`(hex 密文,约 3.4–3.8KB)—— 已改:快手单取 `contents[0].encryptedData`(`printInfo` 为空时回退平台原值)
- `key`:快手加密密钥(base64,172 字符,**逐单生成**)——对应店管家 `contents[0].key` —— 已新增响应字段 `key`
- `signature`、`ver`:现有已正确,无需改动
同时把 `encryptprintinfo` 在快手口径下改为 `contents[0].key`(与菠萝派一致:密文进 `printinfo`、密钥进 `encryptprintinfo`),
WMS 现有快手分支(`encryptedData ← printinfo`、`key ← encryptprintinfo`)无需改代码即可打印;
新增的 `key` 字段供 WMS 后续直接落 `order_express` 使用。
其余平台不受影响:拼多多、抖音直接读 `encryptprintinfo`;菜鸟用 `printinfo` 整包 JSON(WMS 已按 `encryptprintinfo+signature+ver` 回拼)。
### 4. WMS 侧本轮改动
- 快手分支新增 key 合理性校验:`key` 长度 > 512 或与密文相同 → 告警
「快手模板字段 key 疑似为密文而非密钥(上游未返回 key),打印可能失败」,避免静默打出错误面单;
- 既有告警保留(encryptedData / signature / key 缺失映射源)。
- 新增 `test/verify_kuaishou_print_payload.js` 12 例;全部回归脚本合计 12+22+18+23+24+19+16 = 134 例通过。
wms/

View File

@ -795,22 +795,50 @@ function firstPrintInfo(items, printed, waybillCode) {
*
* 旧系统 `Dianguanjia.php` 取的是
* `PrintDataList.task.documents[0].contents[0]` 的 `signature` / `encryptedData` / `ver`;
* 视频号等自定义模板场景平台不返回 `contents`,此时三个值都为空串。
* 快手还会下发逐单加密密钥 `key`(base64,约 172 字符,与密文不同),打印端必需。
* 视频号等自定义模板场景平台不返回 `contents`,此时各值都为空串。
* @param {Object} document 打印单据
* @return {{signature: string, encryptprintinfo: string, ver: string}} 签名、加密打印数据、版本
* @return {{signature: string, encryptprintinfo: string, key: string, ver: string}} 签名、加密打印数据、快手密钥、版本
*/
function extractDocumentContents(document) {
const empty = { signature: '', encryptprintinfo: '', ver: '' };
const empty = { signature: '', encryptprintinfo: '', key: '', ver: '' };
const contents = document && document.contents;
const first = Array.isArray(contents) ? contents[0] : null;
if (!first || typeof first !== 'object') return empty;
return {
signature: typeof first.signature === 'string' ? first.signature : '',
encryptprintinfo: typeof first.encryptedData === 'string' ? first.encryptedData : '',
key: typeof first.key === 'string' ? first.key : '',
ver: first.ver == null ? '' : String(first.ver),
};
}
/**
* 组装回给 WMS 的面单打印字段
*
* 快手(KS)与其它平台口径不同:
* - 快手:平台把加密面单放在 `contents[0].encryptedData`、逐单密钥放在 `contents[0].key`,
* 文档里的 `printInfo` 为空。菠萝派取号的做法是「密文 -> printinfo、密钥 -> encryptprintinfo」,
* WMS 快手打印按该口径取 encryptedData / key,这里对齐,并把 key 单独返回;
* - 其它平台:`printinfo` 原样用平台下发的打印数据,`encryptprintinfo` 仍是 `contents[0].encryptedData`。
* @param {Object} options 参数
* @param {string} options.platformCode 系统预设平台编码(如 KS / TB)
* @param {Object} options.contents extractDocumentContents 的结果
* @param {string} [options.documentPrintInfo] 平台下发的打印数据(documents[].printInfo)
* @return {{printinfo: string, encryptprintinfo: string, key: string}} 打印字段
*/
function buildWaybillPrintFields({ platformCode, contents, documentPrintInfo = '' }) {
const isKuaishou = String(platformCode || '').trim().toUpperCase() === 'KS';
const encryptedData = String((contents && contents.encryptprintinfo) || '');
const key = String((contents && contents.key) || '');
const printData = String(documentPrintInfo || '');
return {
printinfo: isKuaishou ? (encryptedData || printData) : printData,
encryptprintinfo: isKuaishou ? key : encryptedData,
key,
};
}
/**
* 构造 `Orders[0][WaybillCodes][]`(平台「新单号打印」请求里带的当前号清单)
*
@ -2463,7 +2491,7 @@ class DgjService extends PrintPlatformService {
* @param {Object} options.template 已绑定的快递接口记录(template_id / platform_type / dbname / raw)
* @param {number} [options.packageIndex] 包裹序号(0 基):>0 目前不支持,会直接报错(见下)
* @param {number} [options.packageCount] 包裹张数(默认 1):>1 时同一次请求取多张面单
* @return {Promise<{waybill_code: string, waybill_codes: string[], printinfo: string, signature: string, previous_code: string, raw: Object}>} 取号结果
* @return {Promise<{waybill_code: string, waybill_codes: string[], printinfo: string, signature: string, encryptprintinfo: string, key: string, ver: string, previous_code: string, raw: Object}>} 取号结果
*/
async fetchWaybillNo(order, options = {}) {
if (!this.token || !this.cookie) throw new Error('店管家账号未登录:缺少 token 或 cookie,请先登录');
@ -2573,6 +2601,14 @@ class DgjService extends PrintPlatformService {
const document = firstPrintDocument(printed, waybillCodes[0]);
const contents = extractDocumentContents(document);
// 模板上落的是 OMS 预设编码,优先用它判断平台;缺失时再按打单平台原始类型/调用方编码换算
const platformCode = String((template && template.platform_code) || '').trim().toUpperCase()
|| resolveOrderPlatform((template && template.platform_type) || options.platformCode).code;
const printFields = buildWaybillPrintFields({
platformCode,
contents,
documentPrintInfo: firstPrintInfo(items, printed, waybillCodes[0]),
});
return {
waybill_code: waybillCodes[0],
waybill_codes: waybillCodes,
@ -2583,9 +2619,11 @@ class DgjService extends PrintPlatformService {
// 实际命中的订单域名:重取打印数据要发到同一个域名
host,
// 面单打印数据:原样透传(WMS 打印端直接塞进 task.printInfo)
printinfo: firstPrintInfo(items, printed, waybillCodes[0]),
printinfo: printFields.printinfo,
signature: contents.signature,
encryptprintinfo: contents.encryptprintinfo,
encryptprintinfo: printFields.encryptprintinfo,
// 快手逐单加密密钥(base64,约 172 字符),其余平台为空串
key: printFields.key,
ver: contents.ver,
// 取号前后对比用的旧号码(不参与判断,只用于提示「平台仍返回原运单号」)
previous_code: previousCode,
@ -3250,6 +3288,27 @@ class DgjService extends PrintPlatformService {
return extractPrintHistoryIds(printed);
}
/**
* 从打印单据里取 signature / encryptedData / key / ver(供脚本/单测复用同一口径)
* @param {Object} document 打印单据(`documents[]` 中的一项)
* @return {{signature: string, encryptprintinfo: string, key: string, ver: string}} 打印附加信息
*/
static extractDocumentContents(document) {
return extractDocumentContents(document);
}
/**
* 组装回给 WMS 的面单打印字段(快手口径与其它平台不同)
* @param {Object} options 参数
* @param {string} options.platformCode 系统预设平台编码(如 KS / TB)
* @param {Object} options.contents extractDocumentContents 的结果
* @param {string} [options.documentPrintInfo] 平台下发的打印数据
* @return {{printinfo: string, encryptprintinfo: string, key: string}} 打印字段
*/
static buildWaybillPrintFields(options) {
return buildWaybillPrintFields(options);
}
/**
* 组装发货回传单体报文(`Orders[i]`),供脚本/单测复用同一口径
* @param {Object} row 订单行(平台行或本地快照拼装结果)

View File

@ -481,7 +481,7 @@ async function processItem(ctx, { principalId, warehouseId, item, memo, requestI
// 留痕上下文:处理过程中逐步补齐(平台编码 / 打单账号 / 模板)
const meta = { principalId, warehouseId, requestId, code, expressCode, platformCode: '', accountId: null, templateId: null };
const detail = { raw: null, printinfo: '', signature: '', encryptprintinfo: '', ver: '', print_history_ids: [] };
const detail = { raw: null, printinfo: '', signature: '', encryptprintinfo: '', key: '', ver: '', print_history_ids: [] };
const result = await callPlatform(ctx, { principalId, warehouseId, code, expressCode, item, memo, meta, detail });
await saveRecord(ctx, meta, result, detail);
return result;
@ -593,6 +593,7 @@ async function callPlatform(ctx, { principalId, warehouseId, code, expressCode,
detail.printinfo = String((fetched && fetched.printinfo) || '');
detail.signature = String((fetched && fetched.signature) || '');
detail.encryptprintinfo = String((fetched && fetched.encryptprintinfo) || '');
detail.key = String((fetched && fetched.key) || '');
detail.ver = String((fetched && fetched.ver) || '');
// 取号结果只回给调用方(WMS 自行落单),不写回 OMS 订单表:
@ -607,6 +608,7 @@ async function callPlatform(ctx, { principalId, warehouseId, code, expressCode,
platformCode,
waybillCode: waybill.waybill_code,
printinfoLength: detail.printinfo.length,
keyLength: detail.key.length,
});
return {
delivery_order_code: code,
@ -632,6 +634,8 @@ async function callPlatform(ctx, { principalId, warehouseId, code, expressCode,
: ''),
// 需要加密打印的平台(如菜鸟系)才有值,店管家视频号自定义模板一般为空
encryptprintinfo: detail.encryptprintinfo,
// 快手逐单加密密钥(base64,约 172 字符):WMS 快手打印模板的 key 参数,其余平台为空串
key: detail.key,
ver: detail.ver,
};
} catch (err) {

View File

@ -207,6 +207,8 @@ function readArg(name) {
printinfo_len: (result.printinfo || '').length,
printinfo_head: (result.printinfo || '').slice(0, 120),
signature: result.signature ? '已返回' : '无',
encryptprintinfo_len: (result.encryptprintinfo || '').length,
key_len: (result.key || '').length,
raw: file,
});
if (result.previous_code && result.previous_code === result.waybill_code) {

View File

@ -75,3 +75,76 @@ describe('printPlatform/dgj extractPrintHistoryIds', () => {
assert.deepStrictEqual(DgjService.extractPrintHistoryIds(null), []);
});
});
describe('printPlatform/dgj extractDocumentContents', () => {
it('快手单据要取出逐单密钥 key 与密文 encryptedData', () => {
const document = {
contents: [{
encryptedData: 'A1B2C3D4'.repeat(400),
key: 'MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQ==',
signature: 'MEQCIB',
ver: '1',
templateURL: 'https://example.com/t.json',
}],
};
const contents = DgjService.extractDocumentContents(document);
assert.strictEqual(contents.encryptprintinfo, 'A1B2C3D4'.repeat(400));
assert.strictEqual(contents.key, 'MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQ==');
assert.strictEqual(contents.signature, 'MEQCIB');
assert.strictEqual(contents.ver, '1');
});
it('没有 contents 时各字段为空串', () => {
assert.deepStrictEqual(DgjService.extractDocumentContents(null), {
signature: '', encryptprintinfo: '', key: '', ver: '',
});
assert.deepStrictEqual(DgjService.extractDocumentContents({ printInfo: 'x' }), {
signature: '', encryptprintinfo: '', key: '', ver: '',
});
});
});
describe('printPlatform/dgj buildWaybillPrintFields', () => {
const contents = {
signature: 'SIG',
encryptprintinfo: 'ENCRYPTED_DATA',
key: 'PER_ORDER_KEY',
ver: '1',
};
it('快手:printinfo 用 encryptedData,encryptprintinfo/key 都用逐单密钥', () => {
const fields = DgjService.buildWaybillPrintFields({
platformCode: 'KS',
contents,
documentPrintInfo: '',
});
assert.deepStrictEqual(fields, {
printinfo: 'ENCRYPTED_DATA',
encryptprintinfo: 'PER_ORDER_KEY',
key: 'PER_ORDER_KEY',
});
});
it('快手:没有 encryptedData 时回退平台下发的 printInfo', () => {
const fields = DgjService.buildWaybillPrintFields({
platformCode: 'KS',
contents: { ...contents, encryptprintinfo: '' },
documentPrintInfo: 'PLAIN_PRINT_DATA',
});
assert.strictEqual(fields.printinfo, 'PLAIN_PRINT_DATA');
assert.strictEqual(fields.key, 'PER_ORDER_KEY');
});
it('其它平台:printinfo 原样,encryptprintinfo 仍是密文', () => {
const fields = DgjService.buildWaybillPrintFields({
platformCode: 'TB',
contents,
documentPrintInfo: 'PLAIN_PRINT_DATA',
});
assert.deepStrictEqual(fields, {
printinfo: 'PLAIN_PRINT_DATA',
encryptprintinfo: 'ENCRYPTED_DATA',
key: 'PER_ORDER_KEY',
});
});
});