WMS_MAIN/test/app/service/openapi/callback.event.rename.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

620 lines
19 KiB
JavaScript
Raw 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 fs = require('node:fs');
const path = require('node:path');
const InboundDirectLogService = require('../../../../app/service/systems/inbound_direct_log');
const ReceivingEntryMatchService = require('../../../../app/service/systems/receiving_entry_match');
const OpenapiOrderService = require('../../../../app/service/openapiMethods/order');
const OpenapiCallbackMethodService = require('../../../../app/service/openapiMethods/callback');
const { CALLBACK_EVENTS } = require('../../../../app/service/openapi/callbackRegistry');
/** 项目根目录(test/app/service/openapi 上溯 4 级) */
const PROJECT_ROOT = path.join(__dirname, '..', '..', '..', '..');
/**
* 读取项目内源码文件全文。
* @param {string} relativePath 相对于项目根目录的文件路径。
* @return {string} 源码文本。
*/
function readSource(relativePath) {
return fs.readFileSync(path.join(PROJECT_ROOT, relativePath), 'utf8');
}
/**
* 递归收集对象/数组结构中的所有字段名(数组取其元素对象合并后的键集)。
* @param {*} value 任意结构值。
* @return {Set<string>} 字段名集合。
*/
function collectFieldNames(value) {
const names = new Set();
if (Array.isArray(value)) {
for (const item of value) {
for (const name of collectFieldNames(item)) {
names.add(name);
}
}
return names;
}
if (value && typeof value === 'object') {
for (const [ key, child ] of Object.entries(value)) {
names.add(key);
for (const name of collectFieldNames(child)) {
names.add(name);
}
}
}
return names;
}
/**
* 创建静默 logger 桩。
* @return {Object} logger 桩。
*/
function createLogger() {
return {
info() {},
warn() {},
error() {},
};
}
/**
* 临时静默 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;
}
}
/**
* 创建直入入库回传服务桩。
* @param {Object} [options] 可选配置。
* @return {{ service: Object, sendWithRetryCalls: Array, noticeCalls: Array }} 服务实例与调用记录。
*/
function createInboundDirectService(options = {}) {
const sendWithRetryCalls = [];
const noticeCalls = [];
const ctx = {
logger: createLogger(),
user: null,
model: {
StoreWarehouse: {
async findOne() {
return { id: 1 };
},
},
ApiApp: {
async findOne() {
return {
self_app_key: 'APP-KEY-1',
self_app_secret: 'SEC-1',
callback_url: 'http://cb.example.com/openapi',
};
},
},
},
service: {
openapi: {
callback: {
async sendWithRetry(callOptions) {
sendWithRetryCalls.push(callOptions);
if (typeof options.onSendWithRetry === 'function') {
return await options.onSendWithRetry(callOptions);
}
return { success: true };
},
},
},
systems: {
notice: {
async send(payload) {
noticeCalls.push(payload);
return { success: true };
},
},
},
},
};
const service = Object.create(InboundDirectLogService.prototype);
service.ctx = ctx;
service.app = {
Sequelize: { Op: { and: 'AND', ne: 'NE' } },
formatDate() {
return '2026-09-12 10:00:00';
},
};
// 通知文案明细查询降级为空,避免依赖模型层
service._queryCompletedEntryItems = async () => [];
return { service, sendWithRetryCalls, noticeCalls };
}
/**
* 创建入库单匹配收货回传服务桩。
* @return {{ service: Object, sendWithRetryCalls: Array }} 服务实例与调用记录。
*/
function createReceivingEntryMatchService() {
const sendWithRetryCalls = [];
const ctx = {
logger: createLogger(),
model: {
StoreWarehouse: {
async findOne() {
return { id: 9 };
},
},
ApiApp: {
async findOne() {
return {
self_app_key: 'APP-KEY-2',
self_app_secret: 'SEC-2',
callback_url: 'http://cb2.example.com/openapi',
};
},
},
EntryItems: {
async findAll() {
return [
{ item_code: 'SKU-1', item_id: '1001', count: 2, inventory_type: 'ZP', owner_code: 'OWNER-001', received_quantity: 2 },
];
},
},
},
service: {
openapi: {
callback: {
async sendWithRetry(callOptions) {
sendWithRetryCalls.push(callOptions);
return { success: true };
},
},
},
},
};
const service = Object.create(ReceivingEntryMatchService.prototype);
service.ctx = ctx;
service.app = {
Sequelize: { Op: { and: 'AND', ne: 'NE' } },
formatDate() {
return '2026-09-12 10:00:00';
},
};
return { service, sendWithRetryCalls };
}
/**
* 创建 openapi order.cancel 服务桩。
* @return {{ service: Object, callbackCalls: Array, orderUpdates: Array }} 服务实例与调用记录。
*/
function createOpenapiOrderService() {
const callbackCalls = [];
const orderUpdates = [];
const commitCalls = [];
const rollbackCalls = [];
const ctx = {
app: { config: {} },
logger: createLogger(),
user: null,
model: {
async transaction() {
return {
LOCK: { UPDATE: 'UPDATE' },
async commit() { commitCalls.push(1); },
async rollback() { rollbackCalls.push(1); },
};
},
OrderDeliveryFactory: {
async getCurrentModel() {
return {
async findOne() {
return {
id: 123,
delivery_order_code: 'TEST-ORDER-001',
wave_id: 0,
pick_status: 'none',
print_status: 'none',
async update(values, updateOptions) {
orderUpdates.push({ values, options: updateOptions });
},
};
},
};
},
},
},
service: {
openapi: {
callback: {
async sendByAppKey(callOptions) {
callbackCalls.push(callOptions);
return { success: true };
},
},
},
systemMethods: {
order: {
wave: {},
},
},
systems: {
stockoutOrder: {
async cancel() {
return { code: 200, message: '取消出库单成功' };
},
},
},
},
};
const service = new OpenapiOrderService(ctx);
service.setInfo(1000000, 100000, 'APP-KEY-1');
// 储位锁定释放走桩,隔离模型依赖
service.releaseStockLockForCancel = async () => {};
return { service, callbackCalls, orderUpdates, commitCalls };
}
/**
* 创建 openapi 回调测试方法服务桩。
* @return {{ service: Object, callbackCalls: Array }} 服务实例与调用记录。
*/
function createOpenapiCallbackMethodService() {
const callbackCalls = [];
const ctx = {
app: { config: {} },
logger: createLogger(),
model: {
ApiApp: {
async findOne() {
return { self_app_key: 'APP-KEY-3' };
},
},
},
service: {
openapi: {
callback: {
async sendByAppKey(callOptions) {
callbackCalls.push(callOptions);
return { success: true };
},
},
},
},
};
const service = new OpenapiCallbackMethodService(ctx);
return { service, callbackCalls };
}
describe('test/app/service/openapi/callback.event.rename.test.js', () => {
it('inbound_direct_log 回传 method 应为 entryorder.confirm(request 对齐奇门报文)', async () => {
await withSilentConsole(async () => {
const { service, sendWithRetryCalls } = createInboundDirectService();
const entryOrder = {
id: 543,
entry_order_code: 'RK-1',
store_id: 1000000,
warehouse_id: 100000,
};
// 与 buildEntryOrderConfirmRequest 组装结果同层级:{ entryOrder, orderLines }
const request = {
entryOrder: {
entryOrderCode: 'RK-1',
ownerCode: '',
warehouseCode: '',
entryOrderId: 543,
entryOrderType: undefined,
outBizCode: 'DIRECT_INBOUND_1726131400000',
confirmType: 0,
status: 'FULFILLED',
freight: 0,
operateTime: '2026-09-12 10:00:00',
remark: '导入/PDA直接入库提交',
},
orderLines: [
{
orderLineNo: 1,
ownerCode: '',
itemCode: 'SKU-1',
itemId: '1001',
inventoryType: 'ZP',
planQty: 2,
actualQty: 2,
},
],
};
const result = await service._sendOpenApiCallback(entryOrder, { request });
assert.equal(result.success, true);
assert.equal(sendWithRetryCalls.length, 1);
assert.equal(sendWithRetryCalls[0].event, 'entryorder.confirm');
assert.equal(sendWithRetryCalls[0].callbackUrl, 'http://cb.example.com/openapi');
// 报文对齐奇门 request 层级,由发送端包装为 { request },不再携带 data/metadata
assert.deepEqual(sendWithRetryCalls[0].request, request);
assert.equal(Object.prototype.hasOwnProperty.call(sendWithRetryCalls[0], 'data'), false);
assert.equal(Object.prototype.hasOwnProperty.call(sendWithRetryCalls[0], 'metadata'), false);
});
});
it('receiving_entry_match 回传 method 应为 entryorder.match(request 对齐奇门报文)', async () => {
const { service, sendWithRetryCalls } = createReceivingEntryMatchService();
// 明细行桩与 EntryItems 模型桩解耦,避免并行修改时相互影响
service._queryEntryOrderLines = async () => [
{
orderLineNo: 1,
ownerCode: 'OWNER-001',
itemCode: 'SKU-1',
itemId: '1001',
inventoryType: 'ZP',
planQty: 2,
actualQty: 2,
},
];
const entryOrder = {
id: 543,
entry_order_code: 'RK-2',
order_type: 'SCRK',
qimen_owner_code: 'OWNER-001',
qimen_warehouse_code: 'WH-100',
store_id: 1000000,
warehouse_id: 100000,
};
const receivingOrder = {
id: 88,
receiving_number: 'RCV-88',
};
const result = await service._sendOpenApiCallback(entryOrder, receivingOrder, 'auto_match');
assert.equal(result.success, true);
assert.equal(sendWithRetryCalls.length, 1);
assert.equal(sendWithRetryCalls[0].event, 'entryorder.match');
assert.equal(sendWithRetryCalls[0].callbackUrl, 'http://cb2.example.com/openapi');
// 报文对齐奇门 request 层级,由发送端包装为 { request },不再携带 data/metadata
assert.equal(Object.prototype.hasOwnProperty.call(sendWithRetryCalls[0], 'data'), false);
assert.equal(Object.prototype.hasOwnProperty.call(sendWithRetryCalls[0], 'metadata'), false);
assert.deepEqual(sendWithRetryCalls[0].request, {
entryOrder: {
entryOrderCode: 'RK-2',
ownerCode: 'OWNER-001',
warehouseCode: 'WH-100',
entryOrderId: 543,
entryOrderType: 'SCRK',
outBizCode: sendWithRetryCalls[0].request.entryOrder.outBizCode,
confirmType: 0,
status: 'FULFILLED',
freight: 0,
operateTime: '2026-09-12 10:00:00',
remark: '匹配收货单RCV-88自动回传',
},
orderLines: [
{
orderLineNo: 1,
ownerCode: 'OWNER-001',
itemCode: 'SKU-1',
itemId: '1001',
inventoryType: 'ZP',
planQty: 2,
actualQty: 2,
},
],
});
// outBizCode 动态生成,固定前缀 RECEIVING_MATCH_
assert.match(sendWithRetryCalls[0].request.entryOrder.outBizCode, /^RECEIVING_MATCH_\d+$/);
});
it('openapi order.cancel 回调 method 应为 deliveryorder.cancel(与入站 order.cancel 区分)', async () => {
const { service, callbackCalls, orderUpdates, commitCalls } = createOpenapiOrderService();
const result = await service.cancel({
body: {
orderCode: 'TEST-ORDER-001',
orderType: 'JYCK',
},
query: {
app_key: 'APP-KEY-1',
},
});
assert.equal(result.flag, 'success');
assert.equal(result.message, '取消订单成功');
assert.equal(callbackCalls.length, 1);
assert.equal(callbackCalls[0].event, 'deliveryorder.cancel');
assert.equal(callbackCalls[0].appKey, 'APP-KEY-1');
assert.deepEqual(callbackCalls[0].request, {
deliveryOrder: {
deliveryOrderCode: 'TEST-ORDER-001',
orderType: 'JYCK',
status: 'CANCELED',
},
});
// 报文对齐奇门 request 层级:不再携带 data/metadata
assert.equal(Object.prototype.hasOwnProperty.call(callbackCalls[0], 'data'), false);
assert.equal(Object.prototype.hasOwnProperty.call(callbackCalls[0], 'metadata'), false);
assert.equal(commitCalls.length, 1);
assert.equal(orderUpdates.length, 1);
assert.equal(orderUpdates[0].values.status, 'cancel');
});
it('openapiMethods/callback 测试方法默认 method 应为 deliveryorder.confirm', async () => {
const { service, callbackCalls } = createOpenapiCallbackMethodService();
const result = await service.test({
body: {
request: { orderIds: [ 1 ] },
},
query: {
app_key: 'APP-KEY-3',
},
});
assert.equal(result.flag, 'success');
assert.equal(callbackCalls.length, 1);
assert.equal(callbackCalls[0].event, 'deliveryorder.confirm');
assert.equal(callbackCalls[0].appKey, 'APP-KEY-3');
// 去掉 data/metadata:只透传 request,由发送端包装为 { request }
assert.deepEqual(callbackCalls[0].request, { orderIds: [ 1 ] });
assert.equal(Object.prototype.hasOwnProperty.call(callbackCalls[0], 'data'), false);
assert.equal(Object.prototype.hasOwnProperty.call(callbackCalls[0], 'metadata'), false);
});
it('notice 通道事件名 entry_order_completed 未被误改', async () => {
const { service, noticeCalls } = createInboundDirectService();
const result = await service.notifyEntryOrderCompleted({
id: 543,
entry_order_code: 'RK-1',
warehouse_id: 100000,
store_id: 1000000,
});
assert.equal(noticeCalls.length, 1);
assert.equal(noticeCalls[0].event, 'entry_order_completed');
assert.equal(noticeCalls[0].businessName, 'entry_order');
assert.equal(noticeCalls[0].channel, 'warehouse');
assert.equal(result.success, true);
});
it('CALLBACK_EVENTS 应包含 5 条且字段为 { name, label, description, request }', () => {
const names = CALLBACK_EVENTS.map(item => item.name);
assert.deepEqual(names, [
'entryorder.confirm',
'entryorder.match',
'deliveryorder.confirm',
'stockout.confirm',
'deliveryorder.cancel',
]);
for (const item of CALLBACK_EVENTS) {
assert.ok(item.name, '事件缺少 name');
assert.ok(item.label, `${item.name} 缺少 label`);
assert.ok(item.description, `${item.name} 缺少 description`);
assert.ok(item.request && typeof item.request === 'object', `${item.name} 缺少 request`);
assert.equal(
Object.prototype.hasOwnProperty.call(item, 'sampleData'),
false,
`${item.name} 不应再有 sampleData 字段`
);
assert.equal(
Object.prototype.hasOwnProperty.call(item, 'metadata'),
false,
`${item.name} 不应再有 metadata 字段`
);
}
const entryorderConfirm = CALLBACK_EVENTS.find(item => item.name === 'entryorder.confirm');
assert.deepEqual(entryorderConfirm.request, {
entryOrder: {
entryOrderCode: 'RK20260912001',
ownerCode: 'OWNER-001',
warehouseCode: 'WH-100',
entryOrderId: 543,
entryOrderType: 'SCRK',
outBizCode: 'DIRECT_INBOUND_1726131400000',
confirmType: 0,
status: 'FULFILLED',
freight: 0,
operateTime: '2026-09-12 10:30:00',
remark: '导入/PDA直接入库提交',
},
orderLines: [
{
orderLineNo: 1,
ownerCode: 'OWNER-001',
itemCode: 'SKU-1',
itemId: '1001',
inventoryType: 'ZP',
planQty: 2,
actualQty: 2,
},
],
});
});
it('各事件 request 顶层节点应与奇门报文同层级', () => {
const byName = Object.fromEntries(CALLBACK_EVENTS.map(item => [ item.name, item ]));
// 奇门 taobao.qimen.entryorder.confirm:request 节点为 { entryOrder, orderLines }
assert.deepEqual(Object.keys(byName['entryorder.confirm'].request).sort(), [ 'entryOrder', 'orderLines' ]);
assert.deepEqual(Object.keys(byName['entryorder.match'].request).sort(), [ 'entryOrder', 'orderLines' ]);
// 奇门 taobao.qimen.deliveryorder.confirm / stockout.confirm:request 节点为 { deliveryOrder, packages, orderLines }
assert.deepEqual(
Object.keys(byName['deliveryorder.confirm'].request).sort(),
[ 'deliveryOrder', 'orderLines', 'packages' ]
);
assert.deepEqual(
Object.keys(byName['stockout.confirm'].request).sort(),
[ 'deliveryOrder', 'orderLines', 'packages' ]
);
// 无奇门对应接口:按 deliveryOrder 节点约定自定义
assert.deepEqual(Object.keys(byName['deliveryorder.cancel'].request).sort(), [ 'deliveryOrder' ]);
assert.deepEqual(Object.keys(byName['deliveryorder.cancel'].request.deliveryOrder).sort(), [
'deliveryOrderCode',
'orderType',
'status',
]);
});
it('各事件 request 字段名应与真实调用点源码一致', () => {
const sourceExpectations = [
{
name: 'entryorder.confirm',
file: 'app/service/systems/inbound_direct_log.js',
},
{
name: 'entryorder.match',
file: 'app/service/systems/receiving_entry_match.js',
},
{
name: 'deliveryorder.confirm',
file: 'app/service/systems/order_async.js',
},
{
name: 'stockout.confirm',
file: 'app/service/systems/order_async.js',
},
{
// 无奇门对应接口:字段按 deliveryOrder 家族节点约定自定义,
// 已与真实调用点 app/service/openapiMethods/order.js 对齐
name: 'deliveryorder.cancel',
file: 'app/service/openapiMethods/order.js',
},
];
const byName = Object.fromEntries(CALLBACK_EVENTS.map(item => [ item.name, item ]));
for (const expectation of sourceExpectations) {
const event = byName[expectation.name];
assert.ok(event, `注册表应存在事件 ${expectation.name}`);
const source = readSource(expectation.file);
for (const fieldName of collectFieldNames(event.request)) {
assert.ok(
source.includes(fieldName),
`${expectation.name}.request 字段 ${fieldName} 未在 ${expectation.file} 源码中出现`
);
}
}
});
});