'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} { 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} { 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} { 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} { 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} { 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} { 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} 方法名列表 */ function list() { return Object.keys(METHODS); } module.exports = { METHODS, resolve, list };