oms/backend/app/lib/openapiMethods.js
liufumingren 0a9ee3c593 feat(backend): 对外通用回调接口 /openapi 与回调日志
- POST /openapi 入口(controller/openapi.js),协议与 WMS openapi 对齐(method/app_key/sign)
- 方法注册表 lib/openapiMethods.js:index.ping、entryorder.confirm/match、deliveryorder.confirm、stockout.confirm、order.cancel
- 单据处理公共逻辑 lib/orderCallback.js;请求/响应封装 lib/apiResponse.js、lib/openapiCallback.js
- WMS 回调入口 controller/wmsNotify.js 改为复用公共模块
- 回调日志:callback_logs 表 + lib/callbackLog.js(脱敏、fire-and-forget)
2026-09-13 02:23:49 +08:00

170 lines
7.4 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 { nowTimestamp } = require('./apiResponse');
const orderCallback = require('./orderCallback');
/**
* 对外通用回调接口的方法注册表。
*
* 命名与 WMS openapi 一致:`模块.动作`,如 index.ping。
* 方法签名:async (ctx, payload) => ({ ok, message, data })
* - payload.appKey 请求传入的应用Key
* - payload.api 按 app_key 定位到的接口配置(warehouse_apis 记录)
* - payload.warehouse 该接口配置关联的仓库(warehouse_apis.warehouse_id → warehouses)
* - payload.body 业务参数(请求体 JSON 解析结果)
* - payload.query 系统参数(method / app_key / v / timestamp 等)
* - payload.timestamp 归一化后的秒级时间戳
* ok=false 表示业务处理失败(控制器按 HTTP 400 + flag=failure 输出,便于调用方重试/告警);
* data 为成功时的业务数据,外层由控制器统一包装为 { flag, code, message, data, timestamp }。
*
* 单据处理统一走 app/lib/orderCallback.js:按 app_key 定位到的「主体 + 仓库」校验后
* 用单据号(inbound_orders.bill_no / outbound_orders.bill_no)定位 OMS 单据;
* 新增方法时在 METHODS 中按 `模块.动作` 注册即可。
*/
const METHODS = {
/**
* 连通性探测(method = index.ping)
* 外部系统配置好回调地址后先调用本方法,确认网络链路与 app_key/签名 是否可用;
* 同时回显按 app_key 定位到的仓库,便于确认凭据与仓库的对应关系是否正确。
* @param {Object} ctx egg context
* @param {Object} payload 调用上下文
* @param {Object} payload.api 按 app_key 定位到的接口配置(warehouse_apis 记录)
* @param {Object} payload.warehouse 接口配置关联的仓库
* @param {Object} payload.body 业务参数(请求体 JSON)
* @param {Object} payload.query 系统参数(method / app_key / v / timestamp 等)
* @return {Promise<Object>} { ok, message, data }
*/
'index.ping': async (ctx, { api, warehouse, body, query }) => {
ctx.logger.info('[openapi] index.ping', {
appKey: api.app_key,
warehouseId: warehouse.id,
principalId: api.principal_id,
});
return {
ok: true,
message: 'ok',
data: {
pong: true,
method: 'index.ping',
app_key: api.app_key,
warehouse: {
id: warehouse.id,
code: warehouse.code,
name: warehouse.name,
},
principal_id: api.principal_id,
api_version: query.v || '',
echo: body || {},
server_time: nowTimestamp(),
},
};
},
/**
* 入库单确认(method = entryorder.confirm):WMS 收货完成
* 写回明细「已入数量」,并把「已推送(3)」的单据完成入库(增加系统库存,幂等)
* 报文兼容两种结构:顶层字段 / entryOrder 一层嵌套,以及整体包一层 request
* (如 WMS 实际回推的 `{ request: { entryOrder: { entryOrderCode }, orderLines } }`,
* 由 app/lib/orderCallback.js#unwrapPayload 统一归一化)
* @param {Object} ctx egg context
* @param {Object} payload 调用上下文
* @param {Object} payload.api 按 app_key 定位到的接口配置
* @param {Object} payload.warehouse 接口配置关联的仓库
* @param {Object} payload.body 回调报文(含 entryOrderCode / orderCode 与 orderLines)
* @return {Promise<Object>} { ok, message, data }
*/
'entryorder.confirm': (ctx, { api, warehouse, body }) => orderCallback.confirmInbound(ctx, {
principalId: api.principal_id,
warehouseId: warehouse.id,
data: body,
}),
/**
* 入库单匹配(method = entryorder.match):WMS 反馈入库单与收货单的匹配结果
* 仅写回明细「已入数量」并登记匹配信息,不改单据状态、不加库存(等待 entryorder.confirm 确认收货)
* @param {Object} ctx egg context
* @param {Object} payload 调用上下文
* @param {Object} payload.api 按 app_key 定位到的接口配置
* @param {Object} payload.warehouse 接口配置关联的仓库
* @param {Object} payload.body 回调报文(含 entryOrderCode / receivingNumber / matchType)
* @return {Promise<Object>} { ok, message, data }
*/
'entryorder.match': (ctx, { api, warehouse, body }) => orderCallback.matchInbound(ctx, {
principalId: api.principal_id,
warehouseId: warehouse.id,
data: body,
}),
/**
* 发货单确认(method = deliveryorder.confirm):WMS 已发货出库
* 写回明细「已出数量」,扣减系统库存并置「已完成(4)」(幂等,明细以仓库侧为准)
* @param {Object} ctx egg context
* @param {Object} payload 调用上下文
* @param {Object} payload.api 按 app_key 定位到的接口配置
* @param {Object} payload.warehouse 接口配置关联的仓库
* @param {Object} payload.body 回调报文(含 deliveryOrderCode / orderCode 与 orderLines)
* @return {Promise<Object>} { ok, message, data }
*/
'deliveryorder.confirm': (ctx, { api, warehouse, body }) => orderCallback.confirmOutbound(ctx, {
principalId: api.principal_id,
warehouseId: warehouse.id,
data: body,
}),
/**
* 出库单确认(method = stockout.confirm):WMS 出库完成(非订单出库单)
* 处理同 deliveryorder.confirm,单号取 stockoutOrderCode / orderCode
* @param {Object} ctx egg context
* @param {Object} payload 调用上下文
* @param {Object} payload.api 按 app_key 定位到的接口配置
* @param {Object} payload.warehouse 接口配置关联的仓库
* @param {Object} payload.body 回调报文(含 stockoutOrderCode / orderCode 与 orderLines)
* @return {Promise<Object>} { ok, message, data }
*/
'stockout.confirm': (ctx, { api, warehouse, body }) => orderCallback.confirmOutbound(ctx, {
principalId: api.principal_id,
warehouseId: warehouse.id,
data: body,
}),
/**
* 订单取消通知(method = order.cancel):外部已取消该单据
* 未完成(≠4)的单据置为「已取消(9)」,出库单若已推送(3)则同时释放锁定库存
* @param {Object} ctx egg context
* @param {Object} payload 调用上下文
* @param {Object} payload.api 按 app_key 定位到的接口配置
* @param {Object} payload.warehouse 接口配置关联的仓库
* @param {Object} payload.body 回调报文(含 orderCode / deliveryOrderCode / entryOrderCode)
* @return {Promise<Object>} { ok, message, data }
*/
'order.cancel': (ctx, { api, warehouse, body }) => orderCallback.cancelOrder(ctx, {
principalId: api.principal_id,
warehouseId: warehouse.id,
data: body,
}),
};
/**
* 按方法名取处理器
* 未注册的方法一律视为不支持(调用方需据此报错,不做静默兜底),
* 用 hasOwnProperty 判断避免命中 Object 原型上的属性(如 constructor / toString)。
* @param {String} method 方法名,如 index.ping
* @return {Function|null} 处理器;未注册返回 null
*/
function resolve(method) {
const name = String(method || '').trim();
if (!name || !Object.prototype.hasOwnProperty.call(METHODS, name)) return null;
const handler = METHODS[name];
return typeof handler === 'function' ? handler : null;
}
/**
* 已注册的方法名列表(用于错误提示与联调)
* @return {Array<String>} 方法名列表
*/
function list() {
return Object.keys(METHODS);
}
module.exports = { METHODS, resolve, list };