oms/backend/app/lib/openapiMethods.js
liufumingren e1e3bb638f feat(order): 拉单任务、外部发货同步与取号记录
- 拉单任务:新增 order_sync_tasks 异步任务池,按店铺逐店拉取外部打单平台订单,前端轮询进度
- 外部发货同步:配送后把发货结果同步回店管家,提供数量统计与批量重试(externalSendSync)
- 取号:新增 waybill_fetch_records 记录取号过程,外部快递接口补充菜鸟授权信息
- 补齐相关迁移、订单页同步入口/状态展示,并新增对接说明文档

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-04 20:53:35 +08:00

207 lines
10 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');
/**
* 对外通用回调接口的方法注册表。
*
* 命名与 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 = 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 };