oms/backend/app/lib/openapiMethods.js
liufumingren 39c19a4de7 feat(backend): 出入库记录与库存锁定链路、出库单快递/收件人与推送队列
- 出入库记录(库存流水):新增 stock_records 表/模型/只读接口(列表 + 业务动作选项)与「出入库记录」菜单;
  库存变动统一收敛到 app/utils/stockRecord.js#applyStockChange,与流水写入同事务(含变动前后总/锁定/可用数量)
- 发货单:审核(1→2) 按明细锁定库存、发货确认(3→4) 扣减、推送失败退回/驳回/取消/作废释放(新增 stock_locked 列);
  恢复(9→1) 时曾推送过的单据换号(WMS 取消后原单号仍被占用,沿用旧号重推会被判「订单已存在」)
- 出库单:新增快递(express_code/express_name)、收件人(receiver_*) 与多运单号(express_codes) 字段;
  推送报文补齐 logisticsCode/receiverInfo;新增出库单推送服务与定时任务
- 快递:多运单号回填、仓库快递映射(warehouse_express_mappings) 与快递字典补录等迁移
- 契约:补充出入库记录、出库单快递/收件人等定义(swagger.json 为本地生成、不入库)
2026-09-14 00:59:23 +08:00

180 lines
8.6 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');
/**
* 对外通用回调接口的方法注册表。
*
* 命名与 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 中按 `模块.动作` 注册即可。
*
* ⚠️ 单号表不可混用(以 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 = 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 };