- 出入库记录(库存流水):新增 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 为本地生成、不入库)
180 lines
8.6 KiB
JavaScript
180 lines
8.6 KiB
JavaScript
'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 };
|