oms/backend/app/lib/openapiMethods.js
liufumingren 09587bc3e7 feat(waybill): 新增 deliveryorder.getprintdata,打印前按运单号换新 params
店管家面单打印数据(params)只有 10 分钟有效期,取号返回的 printinfo 存着不能用,
WMS 真正打印前必须换新的。新增对外方法:

  method = deliveryorder.getprintdata
  入参:{ caiNiaoAuthInfoIds: [6838859], waybillCodes: ["770357408441408"] }
       也支持直传 { printHistoryIds: ["10000078656212"] }(命中即跳过查库)
  出参:{ total, success, failed, expires_in: 600, results: [...] }
       每单含 print_data / printer_config / document(documentID = 运单号)

实现:
- app/lib/waybillPrintData.js:按「店铺标识 + 运单号」查 waybill_fetch_records 定位打印记录,
  同账号同分区合并成一次 PrintHistory/LoadPrintData(只读,不消耗面单)
- 取号记录补 platform_host(实际命中的订单域名):1688 分销单在 fxali、真实抖音单在 fxdd,
  用被换算过的 source_platform_code 推域名会打错
- waybillGet 落 platform_host;迁移 20261107050000 加列

实测(只读):运单号 770357408441408 → 新 params 7888 字符,documentID 770357408441408,
printer 默认打印机;不存在的运单号返回「未找到该运单号的取号记录」。

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-07 06:38:34 +08:00

234 lines
11 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');
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" ] }
* { "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 };