WMS_MAIN/app/service/openapi/callbackRegistry.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

197 lines
5.5 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';
/**
* OpenAPI 回调事件注册表。
* 每个事件包含 name(事件名)、label(展示名)、description(说明)、
* request(奇门同层级报文模板,即 request 节点的内容,不含外层 request 包装;
* 真实回调报文结构统一为 { request: {...} },字段名与嵌套层级和真实调用点完全一致)。
* 回调调试页 GET /docs/api/openapi/callback-test 直接消费本注册表。
*/
const CALLBACK_EVENTS = [
{
name: 'entryorder.confirm',
label: '入库单确认完成(直入)',
description: '直入入库(API 来源)完成后回传,对应奇门 taobao.qimen.entryorder.confirm',
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,
},
],
},
},
{
name: 'entryorder.match',
label: '入库单匹配收货完成',
description: '入库单匹配收货单完成后回传(API 来源),对应奇门 taobao.qimen.entryorder.confirm',
request: {
entryOrder: {
entryOrderCode: 'RK20260912002',
ownerCode: 'OWNER-001',
warehouseCode: 'WH-100',
entryOrderId: 543,
entryOrderType: 'SCRK',
outBizCode: 'RECEIVING_MATCH_1726131400000',
confirmType: 0,
status: 'FULFILLED',
freight: 0,
operateTime: '2026-09-12 10:30:00',
remark: '匹配收货单RCV20260912001自动回传',
},
orderLines: [
{
orderLineNo: 1,
ownerCode: 'OWNER-001',
itemCode: 'SKU-1',
itemId: '1001',
inventoryType: 'ZP',
planQty: 2,
actualQty: 2,
},
],
},
},
{
name: 'deliveryorder.confirm',
label: '订单发货完成',
description: '订单同步(出库)完成后触发,对应奇门 taobao.qimen.deliveryorder.confirm',
request: {
deliveryOrder: {
totalOrderLines: 1,
deliveryOrderCode: 'DO20260912001',
deliveryOrderId: 123,
warehouseCode: 'WH-100',
orderType: 'JYCK',
status: 'DELIVERED',
outBizCode: 'DO20260912001',
confirmType: 0,
orderConfirmTime: '2026-09-12 10:30:00',
operatorCode: '',
operatorName: '',
storageFee: '0',
operateTime: '2026-09-12 10:30:00',
},
packages: {
package: [
{
logisticsCode: 'YTO',
logisticsName: '圆通速递',
expressCode: 'YT1234567890',
packageCode: 'DO20260912001',
invoiceNo: 'INV20260912001',
items: [
{
itemCode: 'SKU-1',
itemId: 1001,
quantity: 2,
},
],
},
],
},
orderLines: [
{
orderLineNo: '1',
orderSourceCode: 'SO20260912001',
subSourceCode: '',
ownerCode: 'OWNER-001',
itemCode: 'SKU-1',
itemId: 1001,
itemName: '测试商品1',
extCode: '',
planQty: 2,
actualQty: 2,
retailPrice: 0,
actualPrice: 0,
discountAmount: '0',
inventoryType: 'ZP',
snList: [],
qrCode: '',
},
],
},
},
{
name: 'stockout.confirm',
label: '出库单确认完成',
description: '出库单确认回传(API 来源),对应奇门 taobao.qimen.stockout.confirm',
request: {
deliveryOrder: {
totalOrderLines: 1,
deliveryOrderCode: 'SO20260912001',
deliveryOrderId: 5001,
warehouseCode: 'WH-100',
orderType: 'PTCK',
status: 'DELIVERED',
outBizCode: 'SO20260912001',
confirmType: 0,
orderConfirmTime: '2026-09-12 10:30:00',
operatorCode: '',
operatorName: '',
},
packages: {
package: [
{
logisticsCode: 'YTO',
logisticsName: '圆通速递',
expressCode: 'YT1234567890',
packageCode: 'SO20260912001',
items: [
{
itemCode: 'SKU-1',
itemId: 1001,
quantity: 2,
},
],
},
],
},
orderLines: [
{
orderLineNo: '1',
ownerCode: 'OWNER-001',
itemCode: 'SKU-1',
itemId: 1001,
itemName: '测试商品1',
planQty: 2,
actualQty: 2,
inventoryType: 'ZP',
},
],
},
},
{
name: 'deliveryorder.cancel',
label: '订单已取消',
description: '订单取消成功后触发(出站回调事件名 deliveryorder.cancel,与入站方法 order.cancel 区分,避免回调误路由到取消单据接口;无奇门对应接口,按 deliveryOrder 节点约定自定义)',
request: {
deliveryOrder: {
deliveryOrderCode: 'TEST-ORDER-001',
orderType: 'JYCK',
status: 'CANCELED',
},
},
},
];
module.exports = { CALLBACK_EVENTS };