WMS_MAIN/test/app/service/systems/inbound_direct_log.callback.test.js
liufumingren d725e7e457 feat(openapi): 出站回调命名与报文改奇门同层级
- 回调 method 由 snake_case 事件名改为 模块.动作:entryorder.confirm / entryorder.match / deliveryorder.confirm / stockout.confirm / deliveryorder.cancel(原 order.cancel 与入站方法同名,改名避免 callback_url 误指向 /openapi 时被路由到取消单据接口)。

- 时间戳统一为秒级(String(Math.floor(Date.now()/1000))),与 /openapi 入站 ±600 秒时效校验及回调调试页一致。

- 报文体由 { event, data, metadata } 改为奇门同层级 { request: {...} }(移除 metadata,事件标识只靠 query 的 method);入库类回调与奇门侧共用同一份报文组装。

- deliveryorder.confirm 改为逐单发送(仅同步成功的订单);stockout.confirm 直接复用 buildStockoutConfirmDataInternal 结果。

- 修复 entryorder.match 死代码:绑定成功且本次新建绑定时回传,重复触发不重复通知,回传失败不影响绑定。

- 调试页 /docs/api/openapi/callback-test 按真实报文预填;新增出站回调文档页 /docs/api/openapi_callback 及入口链接。

- script/update-api-doc.cjs 支持 spec.newDoc 新建文档与 docMeta.description(附单测)。

- 文档:methods/openapi_callback.json、AI_METHOD_ROUTING.md 5.6 节、docs/openapi-callback-events.md、docs/api-doc-update-workflow.md 等。
2026-09-13 02:24:37 +08:00

413 lines
13 KiB
JavaScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

'use strict';
const assert = require('node:assert/strict');
const InboundDirectLogService = require('../../../../app/service/systems/inbound_direct_log');
/**
* 构建入库单桩实例。
* @param {Object} [overrides] 覆盖字段。
* @param {Array<Object>} [updateLog] 收集 entryOrder.update 调用的数组。
* @return {Object} 入库单桩实例。
*/
function buildEntryOrder(overrides = {}, updateLog = []) {
return {
id: 1001,
entry_order_code: 'RK-1001',
source_type: 'API',
order_type: 'CGRK',
warehouse_id: 100000,
store_id: 1000000,
qimen_owner_code: 'OWNER-1',
qimen_warehouse_code: 'WH-1',
async update(values, options) {
updateLog.push({ values, options });
return [ 1 ];
},
...overrides,
};
}
/**
* 构建入库明细行(奇门 orderLines 结构)。
* @return {Array<Object>} 明细行数组。
*/
function buildOrderLines() {
return [
{ orderLineNo: 1, ownerCode: 'OWNER-1', itemCode: 'SKU-1', itemId: 'ITEM-1', inventoryType: 'ZP', planQty: 2, actualQty: 2 },
{ orderLineNo: 2, ownerCode: 'OWNER-1', itemCode: 'SKU-2', itemId: '', inventoryType: 'ZP', planQty: 1, actualQty: 0 },
];
}
/**
* 创建纯桩测试环境:不访问数据库、不依赖 Egg 上下文。
* @param {Object} [options] 可选配置。
* @param {Function} [options.onQimenSend] 奇门发送桩实现。
* @param {Function} [options.onSendWithRetry] OpenAPI 回调桩实现。
* @return {Object} 服务实例、上下文与各调用记录。
*/
function createHarness(options = {}) {
const logs = { info: [], warn: [], error: [] };
const sends = [];
const openApiSends = [];
const operationLogs = [];
const commits = [];
const rollbacks = [];
const ctx = {
app: {
Sequelize: {
Op: {
in: Symbol('in'),
ne: Symbol('ne'),
and: Symbol('and'),
},
},
formatDate() {
return '2026-09-12 10:00:00';
},
qimenClient: {
async send(method, ownerCode, queryData, sendOptions) {
sends.push({ method, ownerCode, queryData, options: sendOptions });
if (typeof options.onQimenSend === 'function') {
return await options.onQimenSend(method, ownerCode, queryData, sendOptions);
}
return { xmlArray: { response: { flag: 'success', message: 'ok' } } };
},
},
},
model: {
async transaction() {
return {
async commit() { commits.push(1); },
async rollback() { rollbacks.push(1); },
};
},
StoreWarehouse: {
async findOne() {
return { id: 1 };
},
},
ApiApp: {
async findOne() {
return {
self_app_key: 'APP-KEY',
self_app_secret: 'SECRET',
callback_url: 'https://cb.example.com/hook',
};
},
},
},
service: {
openapi: {
callback: {
async sendWithRetry(payload) {
openApiSends.push(payload);
if (typeof options.onSendWithRetry === 'function') {
return await options.onSendWithRetry(payload);
}
return { success: true, retryCount: 0 };
},
},
},
systems: {
operationLog: {
async createOperationLog(payload) {
operationLogs.push(payload);
},
},
},
},
logger: {
info(...args) {
logs.info.push(args.join(' '));
},
warn(...args) {
logs.warn.push(args.join(' '));
},
error(...args) {
logs.error.push(args.join(' '));
},
},
};
const service = new InboundDirectLogService(ctx);
return {
service,
ctx,
logs,
sends,
openApiSends,
operationLogs,
commits,
rollbacks,
};
}
/**
* 临时静默 console.log,避免被测代码调试输出刷屏。
* @param {Function} fn 执行体。
* @return {Promise<*>} fn 的返回值。
*/
async function withSilentConsole(fn) {
const original = console.log;
console.log = () => {};
try {
return await fn();
} finally {
console.log = original;
}
}
describe('test/app/service/systems/inbound_direct_log.callback.test.js', () => {
it('QM 分支奇门报文逐字段不变(entryOrder + orderLines 快照一致)', async () => {
await withSilentConsole(async () => {
const harness = createHarness();
const onSuccessCalls = [];
const entryOrder = buildEntryOrder({ source_type: 'QM' });
const orderLines = buildOrderLines();
const result = await harness.service.qimenEntrySync({
entryOrder,
orderLines,
outBizCode: 'DIRECT_INBOUND_12345',
remark: '导入/PDA直接入库提交',
isFin: true,
onSuccess: async eo => {
onSuccessCalls.push(eo);
},
operator: { id: 1, name: '张三' },
});
assert.equal(result.success, true);
assert.equal(result.message, '同步成功');
assert.equal(onSuccessCalls.length, 1);
assert.equal(onSuccessCalls[0], entryOrder);
assert.equal(harness.openApiSends.length, 0);
assert.equal(harness.sends.length, 1);
const sent = harness.sends[0];
assert.equal(sent.method, 'taobao.qimen.entryorder.confirm');
assert.equal(sent.ownerCode, 'OWNER-1');
assert.equal(sent.options.ctx, harness.ctx);
assert.deepEqual(sent.queryData, {
request: {
entryOrder: {
entryOrderCode: 'RK-1001',
ownerCode: 'OWNER-1',
warehouseCode: 'WH-1',
entryOrderId: 1001,
entryOrderType: 'CGRK',
outBizCode: 'DIRECT_INBOUND_12345',
confirmType: 0,
status: 'FULFILLED',
freight: 0,
operateTime: '2026-09-12 10:00:00',
remark: '导入/PDA直接入库提交',
},
orderLines,
},
});
});
});
it('QM 部分确认 isFin=false 时 confirmType=1 且 status=PARTFULFILLED', async () => {
await withSilentConsole(async () => {
const harness = createHarness();
const onSuccessCalls = [];
const result = await harness.service.qimenEntrySync({
entryOrder: buildEntryOrder({ source_type: 'QM' }),
orderLines: buildOrderLines(),
outBizCode: 'DIRECT_INBOUND_12345',
remark: '导入/PDA直接入库提交',
isFin: false,
onSuccess: async () => {
onSuccessCalls.push(1);
},
operator: { id: 1, name: '张三' },
});
assert.equal(result.success, true);
assert.equal(onSuccessCalls.length, 1);
assert.equal(harness.sends.length, 1);
assert.equal(harness.sends[0].queryData.request.entryOrder.confirmType, 1);
assert.equal(harness.sends[0].queryData.request.entryOrder.status, 'PARTFULFILLED');
});
});
it('QM 缺省 ownerCode/warehouseCode/outBizCode/remark 时按兜底写法组装,不查库', async () => {
await withSilentConsole(async () => {
const harness = createHarness();
await harness.service.qimenEntrySync({
entryOrder: buildEntryOrder({
source_type: 'QM',
qimen_owner_code: null,
qimen_warehouse_code: null,
}),
orderLines: buildOrderLines(),
onSuccess: async () => {},
});
assert.equal(harness.sends.length, 1);
const entryOrder = harness.sends[0].queryData.request.entryOrder;
assert.equal(entryOrder.ownerCode, '');
assert.equal(entryOrder.warehouseCode, '');
assert.match(entryOrder.outBizCode, /^DIRECT_INBOUND_\d+$/);
assert.equal(entryOrder.remark, '');
});
});
it('API 分支回传 event=entryorder.confirm,request 结构与奇门同层级且无 data/metadata 顶层键', async () => {
await withSilentConsole(async () => {
const harness = createHarness();
const onSuccessCalls = [];
const orderLines = buildOrderLines();
const result = await harness.service.qimenEntrySync({
entryOrder: buildEntryOrder({ source_type: 'API' }),
orderLines,
outBizCode: 'DIRECT_INBOUND_12345',
remark: '导入/PDA直接入库提交',
isFin: true,
onSuccess: async () => {
onSuccessCalls.push(1);
},
operator: { id: 1, name: '张三' },
});
assert.equal(result.success, true);
assert.equal(onSuccessCalls.length, 1);
assert.equal(harness.sends.length, 0);
assert.equal(harness.openApiSends.length, 1);
const sent = harness.openApiSends[0];
assert.equal(sent.event, 'entryorder.confirm');
assert.equal(sent.callbackUrl, 'https://cb.example.com/hook');
assert.equal(sent.appKey, 'APP-KEY');
assert.equal(sent.selfAppSecret, 'SECRET');
assert.equal(sent.data, undefined);
assert.equal(sent.metadata, undefined);
assert.deepEqual(Object.keys(sent.request).sort(), [ 'entryOrder', 'orderLines' ]);
assert.deepEqual(sent.request.entryOrder, {
entryOrderCode: 'RK-1001',
ownerCode: 'OWNER-1',
warehouseCode: 'WH-1',
entryOrderId: 1001,
entryOrderType: 'CGRK',
outBizCode: 'DIRECT_INBOUND_12345',
confirmType: 0,
status: 'FULFILLED',
freight: 0,
operateTime: '2026-09-12 10:00:00',
remark: '导入/PDA直接入库提交',
});
assert.deepEqual(sent.request.orderLines, orderLines);
});
});
it('同一入参下 API 与 QM 的报文逐字段一致', async () => {
await withSilentConsole(async () => {
const harness = createHarness();
const paramsBase = {
orderLines: buildOrderLines(),
outBizCode: 'DIRECT_INBOUND_12345',
remark: '导入/PDA直接入库提交',
isFin: true,
onSuccess: async () => {},
};
await harness.service.qimenEntrySync({
entryOrder: buildEntryOrder({ source_type: 'QM' }),
...paramsBase,
});
await harness.service.qimenEntrySync({
entryOrder: buildEntryOrder({ source_type: 'API' }),
...paramsBase,
});
assert.equal(harness.sends.length, 1);
assert.equal(harness.openApiSends.length, 1);
assert.deepEqual(
harness.openApiSends[0].request,
harness.sends[0].queryData.request
);
});
});
it('API 回传失败时返回失败并写 FAILED 状态与操作日志,不执行 onSuccess', async () => {
await withSilentConsole(async () => {
const harness = createHarness({
onSendWithRetry: async () => ({ success: false, error: '回调被拒' }),
});
const updateLog = [];
const onSuccessCalls = [];
const result = await harness.service.qimenEntrySync({
entryOrder: buildEntryOrder({ source_type: 'API' }, updateLog),
orderLines: buildOrderLines(),
outBizCode: 'DIRECT_INBOUND_12345',
remark: '导入/PDA直接入库提交',
isFin: true,
onSuccess: async () => {
onSuccessCalls.push(1);
},
operator: { id: 1, name: '张三' },
});
assert.equal(result.success, false);
assert.equal(result.message.includes('回调被拒'), true);
assert.equal(onSuccessCalls.length, 0);
assert.equal(updateLog.length, 1);
assert.equal(updateLog[0].values.sync_status, 'FAILED');
assert.equal(JSON.parse(updateLog[0].values.sync_message).errorCode, 'API_FAILED');
assert.equal(harness.operationLogs.length, 1);
assert.equal(harness.operationLogs[0].operationCode, 'QUICK_INBOUND_FAILED');
assert.equal(harness.commits.length, 1);
assert.equal(harness.rollbacks.length, 0);
});
});
it('行不能为空时直接返回失败,不发任何回传', async () => {
await withSilentConsole(async () => {
const harness = createHarness();
const onSuccessCalls = [];
const result = await harness.service.qimenEntrySync({
entryOrder: buildEntryOrder({ source_type: 'QM' }),
orderLines: [],
onSuccess: async () => {
onSuccessCalls.push(1);
},
});
assert.equal(result.success, false);
assert.equal(result.message, '行不能为空');
assert.equal(onSuccessCalls.length, 0);
assert.equal(harness.sends.length, 0);
assert.equal(harness.openApiSends.length, 0);
});
});
it('非 QM/API 来源跳过回传并直接执行回调', async () => {
await withSilentConsole(async () => {
const harness = createHarness();
const onSuccessCalls = [];
const result = await harness.service.qimenEntrySync({
entryOrder: buildEntryOrder({ source_type: 'WMS' }),
orderLines: buildOrderLines(),
onSuccess: async () => {
onSuccessCalls.push(1);
},
});
assert.equal(result.success, true);
assert.equal(onSuccessCalls.length, 1);
assert.equal(harness.sends.length, 0);
assert.equal(harness.openApiSends.length, 0);
});
});
});