- 只传 printHistoryId(单值/数组)时,用取号落库的 platform_host + dbname + account_id
直接回源 PrintHistory/LoadPrintData,WMS 不用知道域名与分区
- 记录定位改为 (waybill_code IN …) OR (print_history_ids LIKE '%"id":"…"%'),
避免直传 id 时按主体全表扫描
- 文档补最简用法
实测:{ printHistoryId: "10000078656212" } → 运单号 770357408441408、dbname y/2wUDWCZOk=、
print_data 7888 字符、documentID 770357408441408。
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
235 lines
12 KiB
JavaScript
235 lines
12 KiB
JavaScript
'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<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 已完成发货(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<Object>} { 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<Object>} { 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<Object>} { 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<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 };
|