'use strict'; const { nowTimestamp } = require('./apiResponse'); const orderCallback = require('./orderCallback'); const waybillGet = require('./waybillGet'); const waybillPrintData = require('./waybillPrintData'); /** * 对外通用回调接口的方法注册表。 * * 命名与 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 / order_deliveries.delivery_order_code) * 定位 OMS 单据;新增方法时在 METHODS 中按 `模块.动作` 注册即可。 * 取号(deliveryorder.getwaybill)走 app/lib/waybillGet.js:批量逐单返回结果,快递编码取 WMS 报文。 * * ⚠️ 单号表不可混用(以 D:/wms/methods/openapi_callback.json 为准): * entryorder.confirm → 入库单;stockout.confirm → 出库单(CK_ 组);deliveryorder.confirm → 发货单(FH_ 组) */ 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 已完成发货(ORDER 组 JYCK/HHCK/BFCK) * 报文:`{ request: { deliveryOrder: { deliveryOrderCode }, packages: { package: [...] }, orderLines: [...] } }` * (对齐 D:/wms/methods/openapi_callback.json#deliveryorder.confirm) * 处理:按 deliveryOrderCode / outBizCode 定位发货单(order_deliveries)→ 回写 * `packages.package[].expressCode` 运单号与物流公司 → 状态「已推送(3)」→「已完成(4)」;幂等 * @param {Object} ctx egg context * @param {Object} payload 调用上下文 * @param {Object} payload.api 按 app_key 定位到的接口配置 * @param {Object} payload.warehouse 接口配置关联的仓库 * @param {Object} payload.body 回调报文(含 deliveryOrder / packages / orderLines) * @return {Promise} { ok, message, data } */ 'deliveryorder.confirm': (ctx, { api, warehouse, body }) => orderCallback.confirmDelivery(ctx, { principalId: api.principal_id, warehouseId: warehouse.id, data: body, }), /** * 批量取号(method = deliveryorder.getwaybill) * * WMS 发起取号,报文携带快递编码(不读取订单上的 logistics_code),OMS 回读订单信息: * 订单平台(source_platform_code)→ 店铺 → 外部打单账号 → 按「账号 + 平台 + 编码」定位快递接口。 * 逐单返回成功/失败,互不影响;订单已取消 / 已作废 / 已归档时该单返回取号失败。 * * 报文示例: * { "orders": [ { "deliveryOrderCode": "FH_xxx", "expressCode": "ZTO" } ] } * 返回 data:{ total, success, failed, results: [ { delivery_order_code, success, message, waybill_code, ... } ] } * @param {Object} ctx egg context * @param {Object} payload 调用上下文 * @param {Object} payload.api 按 app_key 定位到的接口配置 * @param {Object} payload.warehouse 接口配置关联的仓库 * @param {Object} payload.body 批量取号报文 * @param {string} [payload.requestId] 调用方 request_id(写入取号记录) * @return {Promise} { ok, message, data } */ 'deliveryorder.getwaybill': (ctx, { api, warehouse, body, requestId }) => waybillGet.getWaybills(ctx, { principalId: api.principal_id, warehouseId: warehouse.id, data: body, requestId, }), /** * 重新获取面单打印数据(method = deliveryorder.getprintdata) * * 店管家面单打印数据(params)只有 10 分钟有效期,WMS 真正打印前必须换新的: * 报「店铺标识(CaiNiaoAuthInfoId)+ 运单号」,OMS 查取号记录得到该运单号的打印记录ID, * 再回平台 `PrintHistory/LoadPrintData` 取新数据(只读,不消耗面单)。 * * 报文示例: * { "caiNiaoAuthInfoIds": [ 6838859 ], "waybillCodes": [ "770357408441408" ] } * { "printHistoryId": "10000078656212" } // 最简:只给一个打印记录ID,域名/分区取自己落库的 * { "printHistoryIds": [ "10000078656212" ] } // 直传打印记录ID数组,命中即跳过按运单号查库 * 返回 data:{ total, success, failed, expires_in, results: [ { waybill_code, success, print_data, printer_config, document, ... } ] } * @param {Object} ctx egg context * @param {Object} payload 调用上下文 * @param {Object} payload.api 按 app_key 定位到的接口配置 * @param {Object} payload.warehouse 接口配置关联的仓库 * @param {Object} payload.body 报文 * @param {string} [payload.requestId] 调用方 request_id(日志用) * @return {Promise} { ok, message, data } */ 'deliveryorder.getprintdata': (ctx, { api, warehouse, body, requestId }) => waybillPrintData.getPrintData(ctx, { principalId: api.principal_id, warehouseId: warehouse.id, data: body, requestId, }), /** * 出库单确认(method = stockout.confirm):WMS 出库完成(非订单出库单,CK 组 / wms_order_stockout) * 写回明细「已出数量」,扣减系统库存并置「已完成(4)」(幂等,明细以仓库侧为准) * 报文:`{ request: { deliveryOrder: { deliveryOrderCode, outBizCode }, packages, orderLines } }` * (对齐 D:/wms/methods/openapi_callback.json#stockout.confirm,deliveryOrderCode = 出库单号 stockout_order_code) * 出库单无运单号/物流公司列 → 报文里的包裹/运单信息留存在 `outbound_orders.wms_push_result.confirm`(幂等) * 注:发货单(ORDER 组)的完成回调是 deliveryorder.confirm,走 confirmDelivery,不能用本方法 * @param {Object} ctx egg context * @param {Object} payload 调用上下文 * @param {Object} payload.api 按 app_key 定位到的接口配置 * @param {Object} payload.warehouse 接口配置关联的仓库 * @param {Object} payload.body 回调报文(含 deliveryOrder.deliveryOrderCode / outBizCode 与 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 };