WMS_MAIN/test/app/service/systems/order_async.openapi.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

501 lines
16 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 OrderAsyncService = require('../../../../app/service/systems/order_async');
/**
* 轮询等待条件成立(fire-and-forget 回调为异步触发)。
*
* @param {Function} predicate 条件函数。
* @param {number} [timeoutMs] 超时时间(毫秒)。
* @return {Promise<void>} 条件成立或超时后返回。
*/
async function waitFor(predicate, timeoutMs = 500) {
const startAt = Date.now();
while (!predicate()) {
if (Date.now() - startAt > timeoutMs) {
return;
}
await new Promise(resolve => setTimeout(resolve, 5));
}
}
/**
* 创建订单异步服务测试桩(覆盖 OpenAPI 回调与 notice 通道断言)。
* @param {Object} [options] 可选配置。
* @param {Array} [options.orderRows] 订单主表记录(raw)。
* @param {Array} [options.orderItems] 订单明细记录(raw)。
* @param {Array} [options.orderExpressRows] 运单号记录(raw)。
* @param {Object} [options.stockoutOrder] 出库单主表记录(raw)。
* @param {Function} [options.onSendByAppKey] OpenAPI 回调桩实现。
* @param {Function} [options.onOutbound] 库存扣减桩实现(可模拟失败订单)。
* @param {boolean} [options.omitNoticeService] 是否省略 notice 服务。
* @return {Object} 服务实例与各调用记录。
*/
function createHarness(options = {}) {
const callbackCalls = [];
const noticeCalls = [];
const outboundCalls = [];
const transactionCalls = [];
const stockoutUpdates = [];
const orderUpdates = [];
const orderRows = Array.isArray(options.orderRows)
? options.orderRows.map(item => ({ ...item }))
: [
{
id: 1,
warehouse_id: 100000,
store_id: 1000000,
delivery_order_code: 'DO-1001',
warehouse_code: 'WH-100',
order_type: 'JYCK',
logistics_code: 'YTO',
logistics_name: '圆通速递',
express_code: '',
name: '测试客户',
mobile: '13800000000',
source_order_codes: 'SO-1001',
sync_status: 'pending',
},
];
const orderItems = Array.isArray(options.orderItems)
? options.orderItems.map(item => ({ ...item }))
: [
{
id: 101,
order_id: 1,
order_line_no: '1',
source_order_code: 'SRC-1',
owner_code: 'OWNER-001',
item_code: 'SKU-1',
item_id: '1001',
item_name: '测试商品1',
plan_qty: 2,
actual_qty: 2,
inventory_type: 'ZP',
},
];
const orderExpressRows = Array.isArray(options.orderExpressRows)
? options.orderExpressRows
: [
{
order_id: 1,
business_key: 9001,
waybill_code: 'WB-1001',
},
];
const ctx = {
app: {
Sequelize: {
Op: {
in: Symbol('in'),
ne: Symbol('ne'),
and: Symbol('and'),
},
},
formatDate() {
return '2026-09-12 10:00:00';
},
},
model: {
async transaction(callback) {
const transaction = {
id: `tx-${transactionCalls.length + 1}`,
LOCK: { UPDATE: Symbol('UPDATE') },
};
transactionCalls.push({ transaction });
return await callback(transaction);
},
OrderDeliveryFactory: {
async getCurrentModel() {
return {
async findAll(query = {}) {
const inIds = query.where && query.where.id && query.where.id[ctx.app.Sequelize.Op.in];
if (!Array.isArray(inIds)) {
return orderRows;
}
const normalizedIds = inIds.map(item => Number(item));
return orderRows.filter(row => normalizedIds.includes(Number(row.id)));
},
async findOne(query = {}) {
const where = query.where || {};
const targetId = Number(where.id);
const targetWarehouseId = Number(where.warehouse_id);
return orderRows.find(row => Number(row.id) === targetId && Number(row.warehouse_id) === targetWarehouseId) || null;
},
async update(values, updateOptions) {
orderUpdates.push({ values, options: updateOptions });
return [ 1 ];
},
};
},
},
OrderItemsFactory: {
async getCurrentModel() {
return {
async findAll(query = {}) {
const inIds = query.where && query.where.order_id && query.where.order_id[ctx.app.Sequelize.Op.in];
if (Array.isArray(inIds)) {
const normalizedIds = inIds.map(item => Number(item));
return orderItems.filter(item => normalizedIds.includes(Number(item.order_id)));
}
const singleOrderId = query.where && query.where.order_id;
if (singleOrderId !== undefined) {
return orderItems.filter(item => Number(item.order_id) === Number(singleOrderId));
}
return orderItems;
},
};
},
},
OrderExpress: {
async findAll(query = {}) {
const inIds = query.where && query.where.order_id && query.where.order_id[ctx.app.Sequelize.Op.in];
if (!Array.isArray(inIds)) {
return orderExpressRows;
}
const normalizedIds = inIds.map(item => Number(item));
return orderExpressRows.filter(item => normalizedIds.includes(Number(item.order_id)));
},
},
OrderStockout: {
async findOne() {
return options.stockoutOrder || {
id: 5001,
stockout_order_code: 'SO-1001',
warehouse_id: 100000,
store_id: 1000000,
source_type: 'API',
sync_status: 'PENDING',
express_code: '',
express_name: '',
total_order_lines: 1,
order_type: 'PTCK',
qimen_owner_code: 'OWNER-001',
qimen_warehouse_code: 'WH-100',
};
},
async update(values, updateOptions) {
stockoutUpdates.push({ values, options: updateOptions });
return [ 1 ];
},
},
OrderStockoutItems: {
async findAll() {
return [
{
id: 1,
order_id: 5001,
order_line_no: '1',
owner_code: 'OWNER-001',
item_code: 'SKU-1',
item_id: 1001,
item_name: '测试商品1',
plan_qty: 2,
actual_qty: 2,
inventory_type: 'ZP',
},
];
},
},
},
user: {
store_id: 1000000,
},
service: {
openapi: {
callback: {
async sendByAppKey(callOptions) {
callbackCalls.push(callOptions);
if (typeof options.onSendByAppKey === 'function') {
return await options.onSendByAppKey(callOptions);
}
return { success: true };
},
},
},
systems: {
stockStore: {
async outbound(itemId, quantity, transaction, meta) {
outboundCalls.push({ itemId, quantity, transaction, meta });
if (typeof options.onOutbound === 'function') {
return await options.onOutbound({ itemId, quantity, transaction, meta });
}
return { success: true };
},
},
...(options.omitNoticeService ? {} : {
notice: {
async send(payload) {
noticeCalls.push(payload);
return { success: true };
},
},
}),
storeWarehouse: {
async getContractConfig() {
return {
policy_config: {
notify_manual_sync: 1,
},
};
},
},
},
},
logger: {
info() {},
warn() {},
error() {},
},
};
const service = new OrderAsyncService(ctx);
return {
service,
ctx,
callbackCalls,
noticeCalls,
outboundCalls,
transactionCalls,
stockoutUpdates,
orderUpdates,
};
}
describe('test/app/service/systems/order_async.openapi.callback.test.js', () => {
it('API 订单同步完成应逐单发送 deliveryorder.confirm(request 对齐奇门报文,失败单不发送)', async () => {
const { service, callbackCalls } = createHarness({
orderRows: [
{
id: 1,
warehouse_id: 100000,
store_id: 1000000,
delivery_order_code: 'DO-1001',
warehouse_code: 'WH-100',
order_type: 'JYCK',
logistics_code: 'YTO',
logistics_name: '圆通速递',
express_code: '',
name: '测试客户',
mobile: '13800000000',
source_order_codes: 'SO-1001',
sync_status: 'pending',
},
{
id: 2,
warehouse_id: 100000,
store_id: 1000000,
delivery_order_code: 'DO-1002',
warehouse_code: 'WH-100',
order_type: 'JYCK',
logistics_code: 'YTO',
logistics_name: '圆通速递',
express_code: '',
name: '测试客户2',
mobile: '13800000001',
source_order_codes: 'SO-1002',
sync_status: 'pending',
},
{
id: 3,
warehouse_id: 100000,
store_id: 1000000,
delivery_order_code: 'DO-1003',
warehouse_code: 'WH-100',
order_type: 'JYCK',
logistics_code: 'YTO',
logistics_name: '圆通速递',
express_code: '',
name: '测试客户3',
mobile: '13800000002',
source_order_codes: 'SO-1003',
sync_status: 'pending',
},
],
orderItems: [
{
id: 101,
order_id: 1,
order_line_no: '1',
source_order_code: 'SRC-1',
owner_code: 'OWNER-001',
item_code: 'SKU-1',
item_id: '1001',
item_name: '测试商品1',
plan_qty: 2,
actual_qty: 2,
inventory_type: 'ZP',
},
{
id: 102,
order_id: 2,
order_line_no: '1',
source_order_code: 'SRC-2',
owner_code: 'OWNER-002',
item_code: 'SKU-2',
item_id: '1002',
item_name: '测试商品2',
plan_qty: 1,
actual_qty: 1,
inventory_type: 'ZP',
},
{
id: 103,
order_id: 3,
order_line_no: '1',
source_order_code: 'SRC-3',
owner_code: 'OWNER-003',
item_code: 'SKU-3',
item_id: '1003',
item_name: '测试商品3',
plan_qty: 3,
actual_qty: 3,
inventory_type: 'ZP',
},
],
orderExpressRows: [
{ order_id: 1, business_key: 9001, waybill_code: 'WB-1001' },
{ order_id: 2, business_key: 9002, waybill_code: 'WB-1002' },
{ order_id: 3, business_key: 9003, waybill_code: 'WB-1003' },
],
onOutbound({ meta }) {
if (Number(meta.orderId) === 3) {
return { success: false, error: '库存不足' };
}
return { success: true };
},
});
const result = await service.syncApiOrders({
create_channel: 'API',
order_ids: [ 1, 2, 3 ],
order_count: 3,
orders: [{ id: 1 }, { id: 2 }, { id: 3 }],
}, {
warehouseId: 100000,
appKey: 'APP-KEY-8',
});
assert.equal(result.success_count, 2);
assert.equal(result.failed_count, 1);
// fire-and-forget 逐单回调:成功 2 单各发送一次,失败单不发送
await waitFor(() => callbackCalls.length === 2);
assert.equal(callbackCalls.length, 2);
const sentCodes = callbackCalls.map(call => call.request.deliveryOrder.deliveryOrderCode).sort();
assert.deepEqual(sentCodes, [ 'DO-1001', 'DO-1002' ]);
for (const call of callbackCalls) {
assert.equal(call.event, 'deliveryorder.confirm');
assert.equal(call.appKey, 'APP-KEY-8');
assert.equal(call.data, undefined);
assert.equal(call.metadata, undefined);
assert.ok(call.request.deliveryOrder);
assert.ok(call.request.packages);
assert.ok(Array.isArray(call.request.orderLines));
assert.equal(call.request.deliveryOrder.status, 'DELIVERED');
assert.equal(call.request.deliveryOrder.orderType, 'JYCK');
// 请求报文不含 event / data / metadata 顶层键
assert.equal(call.request.event, undefined);
assert.equal(call.request.data, undefined);
assert.equal(call.request.metadata, undefined);
}
const firstCall = callbackCalls.find(call => call.request.deliveryOrder.deliveryOrderCode === 'DO-1001');
assert.equal(firstCall.request.orderLines[0].itemCode, 'SKU-1');
assert.equal(firstCall.request.packages.package[0].expressCode, 'WB-1001');
});
it('API 订单同步成功 1 单时仍逐单发送(event 与 appKey 正确)', async () => {
const { service, callbackCalls } = createHarness();
const result = await service.syncApiOrders({
create_channel: 'API',
order_ids: [ 1 ],
order_count: 1,
orders: [{ id: 1 }],
}, {
warehouseId: 100000,
appKey: 'APP-KEY-8',
});
assert.equal(result.status, 'success');
assert.equal(result.success_count, 1);
await waitFor(() => callbackCalls.length === 1);
assert.equal(callbackCalls.length, 1);
assert.equal(callbackCalls[0].event, 'deliveryorder.confirm');
assert.equal(callbackCalls[0].appKey, 'APP-KEY-8');
assert.equal(callbackCalls[0].data, undefined);
assert.equal(callbackCalls[0].metadata, undefined);
assert.equal(callbackCalls[0].request.deliveryOrder.deliveryOrderCode, 'DO-1001');
});
it('API 来源出库单回传 method 应为 stockout.confirm(request 为奇门同层级报文)', async () => {
const { service, callbackCalls } = createHarness();
const result = await service.syncStockoutOrders({
create_channel: 'STOCKOUT',
order_ids: [ 1 ],
order_count: 1,
orders: [{ id: 1 }],
}, {
warehouseId: 100000,
appKey: 'APP-KEY-9',
});
assert.equal(result.status, 'success');
assert.equal(result.success_count, 1);
assert.equal(callbackCalls.length, 1);
assert.equal(callbackCalls[0].event, 'stockout.confirm');
assert.equal(callbackCalls[0].appKey, 'APP-KEY-9');
assert.equal(callbackCalls[0].data, undefined);
assert.equal(callbackCalls[0].metadata, undefined);
const request = callbackCalls[0].request;
assert.ok(request.deliveryOrder);
assert.ok(request.packages);
assert.ok(Array.isArray(request.orderLines));
assert.equal(request.deliveryOrder.deliveryOrderCode, 'SO-1001');
assert.equal(request.orderLines.length, 1);
// 不再包含 stockoutOrderCode / status 外层薄包装,也不含 event / data / metadata 顶层键
assert.equal(request.stockoutOrderCode, undefined);
assert.equal(request.status, undefined);
assert.equal(request.event, undefined);
assert.equal(request.data, undefined);
assert.equal(request.metadata, undefined);
});
it('手工同步 notice 通道事件名 order_sync_completed 未被误改', async () => {
const { service, noticeCalls } = createHarness();
const result = await service.syncManualOrders({
create_channel: 'MANUAL',
order_ids: [ 1 ],
order_count: 1,
orders: [{ id: 1 }],
}, {
warehouseId: 100000,
});
assert.equal(result.status, 'success');
assert.equal(noticeCalls.length, 1);
assert.equal(noticeCalls[0].event, 'order_sync_completed');
assert.equal(noticeCalls[0].businessName, 'order');
});
});