'use strict'; const completeInbound = require('../utils/completeInbound'); const { applyStockChange } = require('../utils/stockRecord'); const { deductDeliveryStock } = require('../utils/deliveryStock'); /** * 外部回调(对外通用回调接口 /openapi)驱动 OMS 单据的共用处理逻辑。 * * 调用方:① app/lib/openapiMethods.js 注册的 method 处理器(WMS/第三方 POST /openapi) * ② app/controller/wmsNotify.js(WMS 出站通知 /wms/notify) * 因此「写回实际数量」「按单号定位单据」只保留这一份实现。 * * 单据定位规则:app_key 已在控制器侧定位到「主体 + 仓库」,此处按 * 入库单 / 出库单:bill_no(WMS entryOrderCode / stockoutOrderCode)+ principal_id 查单; * 其中 stockout.confirm 的出库单号在 request.deliveryOrder.deliveryOrderCode(同 outBizCode), * 入库单号在 request.entryOrder.entryOrderCode; * 发货单:delivery_order_code(WMS deliveryOrderCode / outBizCode)+ principal_id 查单, * 并校验单据的 warehouse_id 与 app_key 定位到的仓库一致,避免跨仓库误处理。 * * 报文结构兼容(见 unwrapPayload):openapi 出站回调整体包一层 request(request.entryOrder.entryOrderCode), * 出站通知 /wms/notify 整体包一层 data,两种结构都会先归一化再按同一组路径取值。 */ /** 入库单单号候选字段(支持嵌套路径) */ const INBOUND_CODE_PATHS = [ 'entryOrderCode', 'entryOrder.entryOrderCode', 'orderCode', 'order.orderCode', ]; /** * 出库单单号候选字段(支持嵌套路径) * 对应 WMS 出站回调 `stockout.confirm`(见 D:/wms/methods/openapi_callback.json:报文体为 * `{ request: { deliveryOrder: { deliveryOrderCode, outBizCode }, packages, orderLines } }`, * 其中 deliveryOrder.deliveryOrderCode = wms_order_stockout.stockout_order_code,outBizCode 同值); * 部分外部系统会按奇门 flat 结构直接下发顶层 stockoutOrderCode / orderCode,故一并兼容。 * 注:候选路径允许与 deliveryorder.confirm 同名(deliveryOrder.deliveryOrderCode), * 两者不会混用 —— 方法名已决定查哪张单号表(stockout.confirm→outbound_orders, * deliveryorder.confirm→order_deliveries),本常量只被 confirmOutbound / cancelOrder 使用。 */ const OUTBOUND_CODE_PATHS = [ 'stockoutOrderCode', 'stockoutOrder.stockoutOrderCode', 'stockout.stockoutOrderCode', 'deliveryOrder.deliveryOrderCode', 'deliveryOrder.stockoutOrderCode', 'deliveryOrder.outBizCode', 'orderCode', 'order.orderCode', ]; /** * 发货单单号候选字段(支持嵌套路径) * 对应 WMS 出站回调 `deliveryorder.confirm`(见 D:/wms/methods/openapi_callback.json: * request.deliveryOrder.deliveryOrderCode = wms_order.delivery_order_code,outBizCode 同值) */ const DELIVERY_CODE_PATHS = [ 'deliveryOrderCode', 'deliveryOrder.deliveryOrderCode', 'outBizCode', 'deliveryOrder.outBizCode', 'orderCode', 'order.orderCode', ]; /** 发货单已完成状态(order_deliveries.status) */ const DELIVERY_STATUS_DONE = 4; /** 发货单已推送状态(可被发货确认推进为已完成) */ const DELIVERY_STATUS_PUSHED = 3; /** 入库单匹配信息候选字段 */ const MATCH_INFO_PATHS = { match_type: [ 'matchType', 'match_type' ], receiving_number: [ 'receivingNumber', 'receiving.receivingNumber' ], matched_at: [ 'completedAt', 'matchedAt', 'operateTime' ], }; /** * 归一化回调报文,兼容两种外层包裹: * - openapi 出站回调(WMS → OMS `POST /openapi?method=...`)整体包一层 request,如 * `{ request: { entryOrder: { entryOrderCode: 'RK_2_2' }, orderLines: [...] } }` * - 出站通知 `/wms/notify` 整体包一层 data,如 `{ code: 200, data: { entryOrderCode: 'RK_1' } }` * 内层字段优先(同名时覆盖顶层),归一化后调用方按同一组路径取值即可。 * @param {Object} data 原始回调报文 * @return {Object} 归一化后的报文 */ function unwrapPayload(data) { const source = data && typeof data === 'object' && !Array.isArray(data) ? data : {}; const inner = [ source.request, source.data ].find(v => v && typeof v === 'object' && !Array.isArray(v)); return inner ? { ...source, ...inner } : source; } /** * 按点号路径取值 * @param {Object} obj 源对象 * @param {String} path 形如 entryOrder.entryOrderCode * @return {*} 取到的值 */ function pickPath(obj, path) { return String(path).split('.').reduce((acc, key) => (acc === null || acc === undefined ? acc : acc[key]), obj); } /** * 按候选字段(支持嵌套路径)取第一个非空字符串 * @param {Object} data 回调报文 * @param {Array} paths 候选字段路径 * @return {String} 值(无则空串) */ function pickFirst(data, paths) { for (const path of paths) { const value = pickPath(data, path); if (value !== undefined && value !== null && String(value).trim() !== '') return String(value).trim(); } return ''; } /** * 从回调报文中提取明细行数组(兼容 orderLines.orderLine / orderLines / items 等结构) * @param {Object} data 回推报文 * @return {Array} 明细行数组 */ function extractLines(data) { const source = data || {}; const raw = source.orderLines || (source.entryOrder && source.entryOrder.orderLines) || (source.deliveryOrder && source.deliveryOrder.orderLines) || (source.stockoutOrder && source.stockoutOrder.orderLines) || source.items || []; if (Array.isArray(raw)) return raw; if (raw && Array.isArray(raw.orderLine)) return raw.orderLine; if (raw && Array.isArray(raw.orderLines)) return raw.orderLines; return []; } /** * 从回调报文中提取包裹数组(deliveryorder.confirm 的 packages.package) * 兼容 `{ packages: { package: [ ... ] } }`(WMS 实际结构)、`{ packages: [ ... ] }`、 * `{ packages: { package: { ... } } }`(单包裹对象)与顶层 `package`。 * @param {Object} data 回推报文(已归一化) * @return {Array} 包裹数组(无则空数组) */ function extractPackages(data) { const source = data || {}; const raw = source.packages || (source.deliveryOrder && source.deliveryOrder.packages) || source.package || []; const list = raw && !Array.isArray(raw) && raw.package !== undefined ? raw.package : raw; if (Array.isArray(list)) return list.filter(v => v && typeof v === 'object' && !Array.isArray(v)); return list && typeof list === 'object' && !Array.isArray(list) ? [ list ] : []; } /** * 在包裹数组中按候选字段取第一个非空字符串 * @param {Array} packages 包裹数组 * @param {Array} keys 候选字段名 * @return {String} 值(无则空串) */ function pickFromPackages(packages, keys) { for (const pkg of packages || []) { const value = pickFromObject(pkg, keys); if (value) return value; } return ''; } /** * 汇总包裹数组里的全部运单号(一单可拆多个包裹 → 多个运单号,去重去空) * 与 pickFromPackages(只取第一个)区分:本函数用于多值列(出库单 outbound_orders.waybill_codes / * 发货单 order_deliveries.express_codes)。 * @param {Array} packages 包裹数组 * @return {Array} 运单号数组(无则空数组) */ function collectExpressCodes(packages) { const codes = []; for (const pkg of packages || []) { const code = truncate(pickFromObject(pkg, [ 'expressCode', 'express_code' ]), 50); if (code && !codes.includes(code)) codes.push(code); } return codes; } /** * 解析回传包裹里的快递编码(**仓库映射优先 → 字典兜底 → 都没有报错**) * * 顺序(口径对齐 WMS `stockout_order.js#resolveStockoutExpress` 的「先 wms_express_setting 映射、 * 再系统快递列表匹配」): * ① 命中「仓库快递映射」(warehouse_express_mappings:warehouse_id + custom_code,status=1) * → 取映射到的**默认快递编码**(express_code)与其字典名称; * ② 未命中映射 → 外部编码本身若在快递公司字典(express_companies)里,直接**兜底**用原编码; * ③ 两者都没有 → 报错,提示去 OMS 外部仓库配置映射。 * * 口径:只解析**非空**编码(未传 packages / 编码为空时不拦截,该字段在 WMS 规范里选填); * 比对统一 trim + 大写。 * @param {Object} ctx egg context * @param {Number} warehouseId app_key 定位到的仓库ID(映射按仓库维度) * @param {Array} packages 包裹数组 * @return {Promise<{ok: Boolean, items: Array, first: Object|null, message?: String}>} * items: [{ raw, code, name, source }],source = mapping(映射命中)/ dictionary(字典兜底); * first: 第一个解析结果,供覆盖本地快递列(多包裹时取第一个非空) */ async function resolvePackageExpress(ctx, warehouseId, packages) { const raws = []; for (const pkg of packages || []) { const raw = truncate(pickFromObject(pkg, [ 'logisticsCode', 'logistics_code' ]), 50).toUpperCase(); if (raw && !raws.includes(raw)) raws.push(raw); } if (!raws.length) return { ok: true, items: [], first: null }; const Op = ctx.app.Sequelize.Op; // ① 仓库映射(一次查全部,避免逐包查询) const mappings = await ctx.model.WarehouseExpressMapping.findAll({ where: { warehouse_id: warehouseId, custom_code: { [Op.in]: raws }, status: 1 }, attributes: [ 'custom_code', 'express_code' ], }); const mappedByRaw = new Map( mappings.map(m => [ String(m.custom_code).trim().toUpperCase(), String(m.express_code).trim().toUpperCase() ]) ); // ② 快递公司字典:把「映射结果」与「未命中映射的原编码」一起查名称 const codes = [ ...new Set(raws.map(raw => mappedByRaw.get(raw) || raw)) ]; const companies = await ctx.model.ExpressCompany.findAll({ where: { code: { [Op.in]: codes } }, attributes: [ 'code', 'name' ], }); const nameByCode = new Map(companies.map(c => [ String(c.code).trim().toUpperCase(), c.name || '' ])); const items = []; const missing = []; for (const raw of raws) { const mapped = mappedByRaw.get(raw); if (mapped) { items.push({ raw, code: mapped, name: nameByCode.get(mapped) || '', source: 'mapping' }); } else if (nameByCode.has(raw)) { items.push({ raw, code: raw, name: nameByCode.get(raw) || '', source: 'dictionary' }); } else { missing.push(raw); } } if (missing.length) { return { ok: false, items, first: null, message: `外部传入的快递编码(${missing.join('、')})没有关联映射,请到 OMS 外部仓库完成映射配置`, }; } return { ok: true, items, first: items[0] || null }; } /** * 从对象中按候选字段取第一个非空字符串 * @param {Object} obj 源对象 * @param {Array} keys 候选字段名 * @return {String} 值(无则空串) */ function pickFromObject(obj, keys) { const source = obj || {}; for (const key of keys) { const value = source[key]; if (value !== undefined && value !== null && String(value).trim() !== '') return String(value).trim(); } return ''; } /** * 转数字,非法值返回 null * @param {*} value 原值 * @return {Number|null} 数字或 null */ function toNumberOrNull(value) { if (value === undefined || value === null || String(value).trim() === '') return null; const num = Number(value); return Number.isFinite(num) ? num : null; } /** * 按列长截断字符串(避免超长报错,如运单号列 50) * @param {String} value 原值 * @param {Number} max 最大长度 * @return {String} 截断后的值 */ function truncate(value, max) { const str = value == null ? '' : String(value).trim(); return str.length > max ? str.slice(0, max) : str; } /** * 把 JSON 列值归一化为数组(兼容驱动/历史数据返回字符串的情况) * @param {*} value JSON 列值 * @return {Array} 数组(非数组/解析失败返回空数组) */ function toJsonArray(value) { if (Array.isArray(value)) return value; if (typeof value === 'string' && value.trim()) { try { const parsed = JSON.parse(value); return Array.isArray(parsed) ? parsed : []; } catch (err) { return []; } } return []; } /** * 把 JSON 列值归一化为普通对象(兼容驱动/历史数据返回字符串的情况) * @param {*} value JSON 列值 * @return {Object} 普通对象(非对象/解析失败返回空对象) */ function toPlainObject(value) { if (value && typeof value === 'object' && !Array.isArray(value)) return value; if (typeof value === 'string' && value.trim()) { try { const parsed = JSON.parse(value); return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {}; } catch (err) { return {}; } } return {}; } /** * 稳定序列化(对象 key 递归升序),用于 JSON 结构比较。 * ⚠️ MySQL 的 JSON 列会重排对象 key(落库后读回的顺序与写入时的字面量顺序不同), * 因此直接 JSON.stringify 比较会误判为「有变化」,必须按 key 排序后再比。 * @param {*} value 任意 JSON 值 * @return {String} 稳定字符串 */ function stableStringify(value) { if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`; if (value && typeof value === 'object') { return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`; } return JSON.stringify(value === undefined ? null : value); } /** * 比较两份确认摘要是否一致(忽略 confirmed_at 时间戳),用于幂等判断: * WMS 重推同一报文时不反复刷新留存时间戳,也不产生无意义的写库。 * @param {Object} a 已留存的摘要 * @param {Object} b 本次组装出的摘要 * @return {Boolean} 除 confirmed_at 外内容一致返回 true */ function isSameConfirmSummary(a, b) { if (!a || !b) return false; const strip = summary => { const copy = { ...summary }; delete copy.confirmed_at; return stableStringify(copy); }; return strip(a) === strip(b); } /** * 把外部回推的实际数量写回单据明细的「已入/已出」数量(按 itemCode 匹配明细行) * @param {Object} ctx egg context * @param {Number} orderId 单据头ID * @param {Number} billType 1入库 2出库 * @param {String} field actual_in_qty / actual_out_qty * @param {Array} lines 回推明细行 * @return {Promise} 实际更新的明细行数 */ async function applyActualQty(ctx, orderId, billType, field, lines) { if (!Array.isArray(lines) || !lines.length) return 0; let updated = 0; for (const line of lines) { if (!line) continue; const itemCode = line.itemCode || line.item_code || (line.item && line.item.itemCode); if (!itemCode) continue; const raw = line.actualQty != null ? line.actualQty : (line.actual_qty != null ? line.actual_qty : (line.quantity != null ? line.quantity : line.planQty)); const qty = Number(raw); if (!Number.isFinite(qty)) continue; const [ affected ] = await ctx.model.StockItem.update( { [field]: qty }, { where: { bill_type: billType, bill_id: orderId, code: itemCode } } ); updated += affected; } return updated; } /** * 按单号 + 主体定位单据,并校验其归属仓库与 app_key 定位到的仓库一致 * @param {Object} ctx egg context * @param {Object} options 查询参数 * @param {String} options.model 模型名(InboundOrder / OutboundOrder) * @param {String} options.code 单据号(bill_no) * @param {Number} options.principalId 主体ID * @param {Number} options.warehouseId app_key 定位到的仓库ID * @return {Promise<{order?: Object, error?: String}>} 定位结果 */ async function findBill(ctx, { model, code, principalId, warehouseId }) { const order = await ctx.model[model].findOne({ where: { bill_no: code, principal_id: principalId } }); if (!order) return { error: `未找到${model === 'InboundOrder' ? '入库' : '出库'}单:${code}` }; // 历史单据可能没有 warehouse_id,仅在双方都有值时校验仓库归属 if (order.warehouse_id && warehouseId && Number(order.warehouse_id) !== Number(warehouseId)) { return { error: `单据 ${code} 不属于当前 app_key 对应的仓库` }; } return { order }; } /** * 入库单确认(entryorder.confirm):WMS 收货完成 * 写回明细「已入数量」,并把「已推送(3)」的单据完成入库(增加系统库存,幂等) * @param {Object} ctx egg context * @param {Object} options 处理参数 * @param {Number} options.principalId 主体ID * @param {Number} options.warehouseId app_key 定位到的仓库ID * @param {Object} options.data 回调报文 * @return {Promise<{ok: Boolean, message: String, data?: Object}>} 处理结果 */ async function confirmInbound(ctx, { principalId, warehouseId, data }) { const payload = unwrapPayload(data); const code = pickFirst(payload, INBOUND_CODE_PATHS); if (!code) return { ok: false, message: '缺少入库单号(entryOrderCode / orderCode)' }; const found = await findBill(ctx, { model: 'InboundOrder', code, principalId, warehouseId }); if (found.error) return { ok: false, message: found.error }; const order = found.order; const actualUpdated = await applyActualQty(ctx, order.id, 1, 'actual_in_qty', extractLines(payload)); const result = await completeInbound(ctx, order); if (!result.ok) return { ok: false, message: result.message }; const data_ = { bill_id: order.id, bill_no: order.bill_no, status: result.already ? order.status : 4, already_completed: !!result.already, actual_qty_updated: actualUpdated, }; ctx.logger.info('[order-callback] entryorder.confirm 完成', data_); return { ok: true, message: 'ok', data: data_ }; } /** * 入库单匹配(entryorder.match):WMS 反馈入库单与收货单匹配结果 * 仅写回明细「已入数量」并返回匹配信息,不改变单据状态、不增加库存(匹配 ≠ 收货完成) * @param {Object} ctx egg context * @param {Object} options 处理参数 * @param {Number} options.principalId 主体ID * @param {Number} options.warehouseId app_key 定位到的仓库ID * @param {Object} options.data 回调报文 * @return {Promise<{ok: Boolean, message: String, data?: Object}>} 处理结果 */ async function matchInbound(ctx, { principalId, warehouseId, data }) { const payload = unwrapPayload(data); const code = pickFirst(payload, INBOUND_CODE_PATHS); if (!code) return { ok: false, message: '缺少入库单号(entryOrderCode / orderCode)' }; const found = await findBill(ctx, { model: 'InboundOrder', code, principalId, warehouseId }); if (found.error) return { ok: false, message: found.error }; const order = found.order; const actualUpdated = await applyActualQty(ctx, order.id, 1, 'actual_in_qty', extractLines(payload)); const result = { bill_id: order.id, bill_no: order.bill_no, status: order.status, actual_qty_updated: actualUpdated, match_type: pickFirst(payload, MATCH_INFO_PATHS.match_type), receiving_number: pickFirst(payload, MATCH_INFO_PATHS.receiving_number), matched_at: pickFirst(payload, MATCH_INFO_PATHS.matched_at), }; ctx.logger.info('[order-callback] entryorder.match 匹配登记', result); return { ok: true, message: 'ok', data: result }; } /** * 出库单确认(stockout.confirm):WMS 出库完成(非订单出库单,CK 组 / wms_order_stockout) * 写回明细「已出数量」,扣减系统库存(总数量与锁定各减明细数量,幂等),并置「已完成(4)」 * 注:发货单(ORDER 组 JYCK/HHCK/BFCK,wms_order_delivery)的完成回调是 deliveryorder.confirm, * 由 confirmDelivery 处理,两者不能混用单号表。 * * 报文对齐 WMS 出站回调规范(D:/wms/methods/openapi_callback.json#stockout.confirm): * request.deliveryOrder.deliveryOrderCode / outBizCode → 定位 OMS 出库单 outbound_orders.bill_no * request.packages.package[].expressCode → 运单号(全部写入 outbound_orders.waybill_codes) * request.packages.package[].logisticsCode / logisticsName → **覆盖**出库单的 express_code / express_name * request.orderLines[].{planQty, actualQty} → 写回明细 actual_out_qty * request.deliveryOrder.status 固定 DELIVERED、confirmType 固定 0(最终确认) * 报文摘要(包裹/明细/时间)另存 `outbound_orders.wms_push_result.confirm` 供排查; * 幂等:除时间戳外摘要无变化、运单号与快递公司列均已同步时不重复写库。 * * ⚠️ **快递公司以回传为准(覆盖)**:WMS 可能「转快递」(推送 ZT 自提、实际发 YTO 圆通), * 回传的 `packages[].logisticsCode/logisticsName` 才是实际承运,故按回传值**覆盖** * `outbound_orders.express_code/express_name`(回传为空时不覆盖,避免清空已有值); * 因而不要求回传编码等于推送编码,也不做两边字典一致性约束。 * @param {Object} ctx egg context * @param {Object} options 处理参数 * @param {Number} options.principalId 主体ID * @param {Number} options.warehouseId app_key 定位到的仓库ID * @param {Object} options.data 回调报文 * @return {Promise<{ok: Boolean, message: String, data?: Object}>} 处理结果 */ async function confirmOutbound(ctx, { principalId, warehouseId, data }) { const payload = unwrapPayload(data); const code = pickFirst(payload, OUTBOUND_CODE_PATHS); if (!code) { return { ok: false, message: '缺少出库单号(deliveryOrder.deliveryOrderCode / stockoutOrderCode / orderCode)', }; } const found = await findBill(ctx, { model: 'OutboundOrder', code, principalId, warehouseId }); if (found.error) return { ok: false, message: found.error }; const order = found.order; const lines = extractLines(payload); const packages = extractPackages(payload); // 快递编码解析(仓库映射优先 → 字典兜底 → 都没有报错)——必须在任何写库动作之前完成 const expressResult = await resolvePackageExpress(ctx, warehouseId, packages); if (!expressResult.ok) return { ok: false, message: expressResult.message }; const actualUpdated = await applyActualQty(ctx, order.id, 2, 'actual_out_qty', lines); // 幂等:已完成且已扣减库存的单据不再重复处理(仅补写缺失的确认摘要,便于留存运单号) if (order.status === 4 && order.stock_deducted) { const summaryResult = await applyOutboundConfirmSummary(ctx, order, payload, packages, lines, { express: expressResult.first }); const done = { bill_id: order.id, bill_no: order.bill_no, status: order.status, already_completed: true, actual_qty_updated: actualUpdated, waybill_code: summaryResult.summary.waybill_code, waybill_codes: summaryResult.summary.waybill_codes, logistics_code: summaryResult.summary.logistics_code, logistics_name: summaryResult.summary.logistics_name, express_updated: summaryResult.expressUpdated, summary_updated: summaryResult.changed, }; ctx.logger.info('[order-callback] 出库单已完成,跳过', done); return { ok: true, message: 'ok', data: done }; } if (order.status !== 3 && order.status !== 4) { return { ok: false, message: `单据 ${order.bill_no} 当前状态(${order.status})不允许出库确认,需为「已推送(3)」` }; } const items = await ctx.model.StockItem.findAll({ where: { bill_type: 2, bill_id: order.id, product_id: { [ctx.app.Sequelize.Op.ne]: null } }, attributes: [ 'product_id', 'code', 'name', 'quantity', 'inventory_type' ], order: [[ 'product_id', 'ASC' ]], }); if (!items.length) return { ok: false, message: `单据 ${order.bill_no} 无明细,无法完成出库` }; const transaction = await ctx.model.transaction(); let summaryResult; try { if (!order.stock_deducted) { for (const it of items) { const p = it.get ? it.get({ plain: true }) : it; const itemType = p.inventory_type === 'CC' ? 'CC' : 'ZC'; // 扣减库存 + 写一条出库确认记录(含变动后锁定数量与可用数量) await applyStockChange(ctx, { bizType: 'outbound_deduct', principalId, warehouseId: order.warehouse_id, productId: Number(p.product_id), itemCode: p.code, itemName: p.name, itemType, quantity: Number(p.quantity) || 0, billId: order.id, billNo: order.bill_no, remark: '出库确认扣减库存(WMS 回推)', transaction, }); } } // 确认摘要(含运单号/物流公司)与状态、库存同事务写入 summaryResult = await applyOutboundConfirmSummary(ctx, order, payload, packages, lines, { transaction, express: expressResult.first }); await order.update({ status: 4, stock_deducted: 1 }, { transaction }); await transaction.commit(); } catch (err) { await transaction.rollback(); throw err; } const result = { bill_id: order.id, bill_no: order.bill_no, status: 4, stock_deducted: 1, already_completed: false, actual_qty_updated: actualUpdated, waybill_code: summaryResult.summary.waybill_code, waybill_codes: summaryResult.summary.waybill_codes, logistics_code: summaryResult.summary.logistics_code, logistics_name: summaryResult.summary.logistics_name, express_updated: summaryResult.expressUpdated, summary_updated: summaryResult.changed, }; ctx.logger.info('[order-callback] 出库确认完成', result); return { ok: true, message: 'ok', data: result }; } /** * 回写发货单的运单号与物流公司(幂等:值未变化时不写库) * 数据来源 request.packages.package[](每个运单号一条),取第一个非空的 expressCode / * logisticsCode / logisticsName;无包裹信息时不改动原值。 * 多包裹:全部运单号另存 express_codes(JSON 数组),express_code 仍是首个运单号(兼容既有口径)。 * * ⚠️ **物流公司以回传为准(覆盖)**:WMS 可能「转快递」,回传的 logisticsCode/logisticsName * 才是实际承运,故与本地值不同时直接覆盖(不回写推送值、不做两边字典一致性约束)。 * @param {Object} ctx egg context * @param {Object} order 发货单 model 实例(order_deliveries) * ⚠️ 物流公司以解析结果为准:先按仓库快递映射(warehouse_express_mappings)把外部自定义编码 * 解析成 OMS 默认快递编码,未命中映射则用字典兼容(extern 编码本身在 express_companies 里), * 两者都没有由调用方报错;因此物流公司列写的是**解析后**的编码/名称。 * @param {Array} packages 包裹数组 * @param {Object} [options] 可选参数 * @param {Object} [options.express] 解析后的快递({ raw, code, name, source }),优先于包裹里的原值 * @return {Promise<{changed: Array, express_code: String, express_codes: Array, * logistics_code: String, logistics_name: String}>} changed 为本次实际写入的列名 */ async function applyDeliveryPackageInfo(ctx, order, packages, { express } = {}) { const list = packages || []; const expressCode = truncate(pickFromPackages(list, [ 'expressCode', 'express_code' ]), 50); // 物流公司:优用解析结果(映射/字典),无解析结果时回退到包裹原值 const logisticsCode = truncate((express && express.code) || pickFromPackages(list, [ 'logisticsCode', 'logistics_code' ]), 50); const logisticsName = truncate((express && express.name) || pickFromPackages(list, [ 'logisticsName', 'logistics_name' ]), 200); // 多包裹:全部运单号留存到 express_codes(列 express_code 保留首个,兼容既有单值口径) const expressCodes = collectExpressCodes(list); const patch = {}; if (expressCode && String(order.express_code || '').trim() !== expressCode) patch.express_code = expressCode; if (logisticsCode && String(order.logistics_code || '').trim() !== logisticsCode) patch.logistics_code = logisticsCode; if (logisticsName && String(order.logistics_name || '').trim() !== logisticsName) patch.logistics_name = logisticsName; if (expressCodes.length && stableStringify(toJsonArray(order.express_codes)) !== stableStringify(expressCodes)) { patch.express_codes = expressCodes; } const changed = Object.keys(patch); if (changed.length) { await order.update(patch); ctx.logger.info(`[order-callback] 发货单 ${order.delivery_order_code} 回写运单/物流信息:${changed.join(', ')}`); } const storedCodes = toJsonArray(order.express_codes); return { changed, express_code: order.express_code || '', express_codes: storedCodes.length ? storedCodes : expressCodes, logistics_code: order.logistics_code || '', logistics_name: order.logistics_name || '', }; } /** * 组装发货确认报文摘要(写入 wms_push_result.confirm,便于排查运单号/确认时间/发货明细) * 字段口径对齐 D:/wms/methods/openapi_callback.json#deliveryorder.confirm * @param {Object} payload 归一化后的回调报文 * @param {Array} packages 包裹数组 * @param {Array} lines 发货明细行数组 * @return {Object} 摘要对象 */ function buildDeliveryConfirmSummary(payload, packages, lines) { const d = (payload && payload.deliveryOrder) || {}; const list = packages || []; const orderLines = lines || []; return { out_biz_code: pickFirst(payload, [ 'outBizCode', 'deliveryOrder.outBizCode' ]), wms_delivery_order_id: toNumberOrNull(d.deliveryOrderId), warehouse_code: pickFromObject(d, [ 'warehouseCode' ]), order_type: pickFromObject(d, [ 'orderType' ]), status: pickFromObject(d, [ 'status' ]), confirm_type: toNumberOrNull(d.confirmType), order_confirm_time: pickFromObject(d, [ 'orderConfirmTime' ]), operate_time: pickFromObject(d, [ 'operateTime' ]), storage_fee: pickFromObject(d, [ 'storageFee' ]), total_order_lines: toNumberOrNull(d.totalOrderLines) == null ? orderLines.length : toNumberOrNull(d.totalOrderLines), packages: list.map(pkg => ({ package_code: pickFromObject(pkg, [ 'packageCode', 'package_code' ]), express_code: pickFromObject(pkg, [ 'expressCode', 'express_code' ]), logistics_code: pickFromObject(pkg, [ 'logisticsCode', 'logistics_code' ]), logistics_name: pickFromObject(pkg, [ 'logisticsName', 'logistics_name' ]), invoice_no: pickFromObject(pkg, [ 'invoiceNo', 'invoice_no' ]), })), lines: orderLines.map(line => ({ order_line_no: pickFromObject(line, [ 'orderLineNo', 'order_line_no' ]), item_code: pickFromObject(line, [ 'itemCode', 'item_code' ]), plan_qty: toNumberOrNull(line.planQty), actual_qty: toNumberOrNull(line.actualQty), })), confirmed_at: new Date().toISOString(), }; } // -------- 出库确认报文摘要(stockout.confirm:包裹/运单信息留存) -------- /** * 组装出库确认报文摘要(写入 outbound_orders.wms_push_result.confirm,便于排查运单号/物流公司/出库明细) * 字段口径对齐 D:/wms/methods/openapi_callback.json#stockout.confirm(与发货单摘要同风格) * @param {Object} payload 归一化后的回调报文 * @param {Array} packages 包裹数组 * @param {Array} lines 出库明细行数组 * @return {Object} 摘要对象 */ function buildOutboundConfirmSummary(payload, packages, lines) { const d = (payload && payload.deliveryOrder) || {}; const list = packages || []; const orderLines = lines || []; const totalLines = toNumberOrNull(d.totalOrderLines); return { out_biz_code: pickFirst(payload, [ 'outBizCode', 'deliveryOrder.outBizCode' ]), wms_delivery_order_id: toNumberOrNull(d.deliveryOrderId), warehouse_code: pickFromObject(d, [ 'warehouseCode' ]), order_type: pickFromObject(d, [ 'orderType' ]), status: pickFromObject(d, [ 'status' ]), confirm_type: toNumberOrNull(d.confirmType), order_confirm_time: pickFromObject(d, [ 'orderConfirmTime' ]), operate_time: pickFromObject(d, [ 'operateTime' ]), total_order_lines: totalLines == null ? orderLines.length : totalLines, // 运单号/物流公司提到摘要根节点,便于直接读取(包内 express_code 依旧对应该单体 // package.expressCode;根节点用 waybill_* 区分「运单号」,与快递公司列 express_code 区分开) waybill_code: pickFromPackages(list, [ 'expressCode', 'express_code' ]), waybill_codes: collectExpressCodes(list), logistics_code: pickFromPackages(list, [ 'logisticsCode', 'logistics_code' ]), logistics_name: pickFromPackages(list, [ 'logisticsName', 'logistics_name' ]), packages: list.map(pkg => ({ package_code: pickFromObject(pkg, [ 'packageCode', 'package_code' ]), express_code: pickFromObject(pkg, [ 'expressCode', 'express_code' ]), logistics_code: pickFromObject(pkg, [ 'logisticsCode', 'logistics_code' ]), logistics_name: pickFromObject(pkg, [ 'logisticsName', 'logistics_name' ]), })), lines: orderLines.map(line => ({ order_line_no: pickFromObject(line, [ 'orderLineNo', 'order_line_no' ]), item_code: pickFromObject(line, [ 'itemCode', 'item_code' ]), item_name: pickFromObject(line, [ 'itemName', 'item_name' ]), inventory_type: pickFromObject(line, [ 'inventoryType', 'inventory_type' ]), plan_qty: toNumberOrNull(line.planQty), actual_qty: toNumberOrNull(line.actualQty), })), confirmed_at: new Date().toISOString(), }; } /** * 按需把出库确认摘要合并进 outbound_orders.wms_push_result.confirm(保留原有推送结果字段), * 并用回传的快递公司**覆盖**出库单的 express_code / express_name。 * * ⚠️ 覆盖口径:WMS 可能「转快递」(如推送 ZT 自提、实际发 YTO 圆通),回传的 * `packages.package[].logisticsCode/logisticsName` 才是**实际承运**,故本地快照以回传值覆盖, * 不再要求与推送值一致(推送值可在 api_outbound_logs 的请求报文里回溯)。 * 回传为空时不覆盖(避免把已有值清空)。 * * 出库单的运单号集合另存 outbound_orders.waybill_codes(JSON 数组,列名对齐 wms_order_stockout); * 幂等:除 confirmed_at 外与已留存摘要一致、且 waybill_codes / 快递公司列均已同步时跳过写库 * (WMS 重推不刷新时间戳)。 * @param {Object} ctx egg context * @param {Object} order 出库单 model 实例(outbound_orders) * @param {Object} payload 归一化后的回调报文 * @param {Array} packages 包裹数组 * @param {Array} lines 出库明细行数组 * @param {Object} [options] 可选参数 * @param {Object} [options.transaction] 事务;传入时摘要与状态/库存同事务写入 * @param {Object} [options.express] 解析后的快递({ raw, code, name, source }),用于覆盖 express_code/express_name * @return {Promise<{summary: Object, changed: Boolean, expressUpdated: Array}>} 摘要 + 是否写库 + 覆盖的快递列 */ async function applyOutboundConfirmSummary(ctx, order, payload, packages, lines, { transaction, express } = {}) { const summary = buildOutboundConfirmSummary(payload, packages, lines); const codes = collectExpressCodes(packages); const current = toPlainObject(order.wms_push_result); // 摘要变化 / 运单号集合列未同步(含历史单列还是 NULL)/ 快递公司需按回传覆盖,任一成立都要写库 const summaryChanged = !isSameConfirmSummary(current.confirm, summary); const codesChanged = codes.length > 0 && stableStringify(toJsonArray(order.waybill_codes)) !== stableStringify(codes); const expressPatch = buildExpressOverride(order, express); const expressUpdated = Object.keys(expressPatch); if (!summaryChanged && !codesChanged && !expressUpdated.length) { ctx.logger.info(`[order-callback] 出库单 ${order.bill_no} 确认摘要无变化,跳过写库`); return { summary, changed: false, expressUpdated }; } const patch = { wms_push_result: { ...current, confirm: summary }, ...expressPatch }; // 空包裹不改动原值(避免无包裹信息的重推把已有运单号清掉) if (codes.length) patch.waybill_codes = codes; await order.update(patch, { transaction }); ctx.logger.info( `[order-callback] 出库单 ${order.bill_no} 留存确认摘要(运单号 ${summary.waybill_codes.join('、') || '-'} / 物流 ${summary.logistics_name || '-'})` + (expressUpdated.length ? `;按回传覆盖 ${expressUpdated.join(', ')}` : '') ); return { summary, changed: true, expressUpdated }; } /** * 用**解析后**的快递(仓库映射优先 → 字典兜底)覆盖出库单的 express_code / express_name * (有值且与现值不同才写) * @param {Object} order 出库单 model 实例(outbound_orders) * @param {Object} express 解析结果({ raw, code, name, source }) * @return {Object} 需要写入的列(空对象表示无需覆盖) */ function buildExpressOverride(order, express) { const code = truncate((express && express.code) || '', 50); const name = truncate((express && express.name) || '', 200); const patch = {}; if (code && String(order.express_code || '').trim() !== code) patch.express_code = code; if (name && String(order.express_name || '').trim() !== name) patch.express_name = name; return patch; } /** * 发货单确认(deliveryorder.confirm):WMS 已完成发货(ORDER 组 JYCK/HHCK/BFCK → wms_order_delivery) * * 报文对齐 WMS 出站回调规范(D:/wms/methods/openapi_callback.json#deliveryorder.confirm): * request.deliveryOrder.deliveryOrderCode / outBizCode → 定位 OMS 发货单 order_deliveries.delivery_order_code * request.packages.package[].{expressCode, logisticsCode, logisticsName, packageCode, invoiceNo} → 运单号/物流公司回写 * request.orderLines[].{planQty, actualQty} → 报文摘要登记(发货单明细无「已发数量」列,故不落明细) * request.deliveryOrder.status 固定 DELIVERED、confirmType 固定 0(最终确认) * * 处理内容:① 回写运单号 express_code 与物流公司(缺失或变化时)② 状态「已推送(3)」→「已完成(4)」 * ③ 若审核时已锁定库存(order_deliveries.stock_locked=1)则扣减库存(总数量与锁定同减) * 并写 order_deduct 流水;历史单据(stock_locked=0)不扣减,避免凭空减少总数量 * 幂等:已完成(4) 的单据再次收到(可能多次)相同报文时只做缺失字段补写并直接回成功 * (不重复改状态、不重复扣减库存、不重复写推送结果);状态非 3/4 时返回失败,交由调用方告警/重试。 * @param {Object} ctx egg context * @param {Object} options 处理参数 * @param {Number} options.principalId 主体ID * @param {Number} options.warehouseId app_key 定位到的仓库ID * @param {Object} options.data 回调报文 * @return {Promise<{ok: Boolean, message: String, data?: Object}>} 处理结果 */ async function confirmDelivery(ctx, { principalId, warehouseId, data }) { const payload = unwrapPayload(data); const code = pickFirst(payload, DELIVERY_CODE_PATHS); if (!code) return { ok: false, message: '缺少发货单号(deliveryOrderCode / outBizCode)' }; const order = await ctx.model.OrderDelivery.findOne({ where: { delivery_order_code: code, principal_id: principalId }, }); if (!order) return { ok: false, message: `未找到发货单:${code}` }; // 历史单据可能没有 warehouse_id,仅在双方都有值时校验仓库归属 if (order.warehouse_id && warehouseId && Number(order.warehouse_id) !== Number(warehouseId)) { return { ok: false, message: `单据 ${code} 不属于当前 app_key 对应的仓库` }; } const packages = extractPackages(payload); const lines = extractLines(payload); // 快递编码解析(仓库映射优先 → 字典兜底 → 都没有报错)——必须在写回运单/物流信息之前完成 const expressResult = await resolvePackageExpress(ctx, warehouseId, packages); if (!expressResult.ok) return { ok: false, message: expressResult.message }; // 运单号/物流公司回写:幂等(值未变化则不写库),已完成单据也允许补写缺失值 const pkgInfo = await applyDeliveryPackageInfo(ctx, order, packages, { express: expressResult.first }); // 幂等:已完成(4) 直接回成功,不再流转状态、不重复扣减库存(外部重复推送同一报文时返回相同结果) if (Number(order.status) === DELIVERY_STATUS_DONE) { const done = { delivery_order_id: order.id, delivery_order_code: order.delivery_order_code, status: DELIVERY_STATUS_DONE, already_completed: true, express_code: pkgInfo.express_code, express_codes: pkgInfo.express_codes, logistics_code: pkgInfo.logistics_code, logistics_name: pkgInfo.logistics_name, package_updated: pkgInfo.changed, stock_locked: Number(order.stock_locked) === 1, }; ctx.logger.info('[order-callback] 发货单已完成,跳过(幂等回执)', done); return { ok: true, message: 'ok', data: done }; } if (Number(order.status) !== DELIVERY_STATUS_PUSHED) { return { ok: false, message: `单据 ${code} 当前状态(${order.status})不允许发货确认,需为「已推送(3)」`, }; } // 扣减库存(仅审核时锁定过的单据)+ 状态流转 + 推送结果,同事务写入 const transaction = await ctx.model.transaction(); let stockResult; try { stockResult = await deductDeliveryStock(ctx, order, { remark: '订单发货确认扣减库存(WMS 回推 deliveryorder.confirm)', transaction, }); await order.update({ status: DELIVERY_STATUS_DONE, // 保留原推送信息,追加本次发货确认报文摘要 wms_push_result: { ...(order.wms_push_result && typeof order.wms_push_result === 'object' ? order.wms_push_result : {}), confirm: buildDeliveryConfirmSummary(payload, packages, lines), }, }, { transaction }); await transaction.commit(); } catch (err) { await transaction.rollback(); throw err; } const result = { delivery_order_id: order.id, delivery_order_code: order.delivery_order_code, status: DELIVERY_STATUS_DONE, already_completed: false, express_code: pkgInfo.express_code, express_codes: pkgInfo.express_codes, logistics_code: pkgInfo.logistics_code, logistics_name: pkgInfo.logistics_name, package_updated: pkgInfo.changed, stock_deducted: stockResult.affected, stock_skipped: stockResult.skipped, stock_skipped_lines: stockResult.skippedLines, line_count: lines.length, }; ctx.logger.info('[order-callback] 发货确认完成', result); return { ok: true, message: 'ok', data: result }; } /** * 订单取消通知(order.cancel):外部已取消该单据 * 未完成(≠4)的单据置为「已取消(9)」;出库单若已推送(3)则同时释放锁定库存 * @param {Object} ctx egg context * @param {Object} options 处理参数 * @param {Number} options.principalId 主体ID * @param {Number} options.warehouseId app_key 定位到的仓库ID * @param {Object} options.data 回调报文 * @return {Promise<{ok: Boolean, message: String, data?: Object}>} 处理结果 */ async function cancelOrder(ctx, { principalId, warehouseId, data }) { const payload = unwrapPayload(data); const code = pickFirst(payload, [ ...OUTBOUND_CODE_PATHS, ...INBOUND_CODE_PATHS ]); if (!code) return { ok: false, message: '缺少单号(orderCode / deliveryOrderCode / entryOrderCode)' }; // 先按出库单定位,再按入库单定位 let billType = 2; let found = await findBill(ctx, { model: 'OutboundOrder', code, principalId, warehouseId }); if (found.error) { billType = 1; found = await findBill(ctx, { model: 'InboundOrder', code, principalId, warehouseId }); } if (found.error) { return { ok: false, message: `未找到可取消的单据:${code}(出入库单均无此单号或不属于当前仓库)` }; } const order = found.order; if (order.status === 4) return { ok: false, message: `单据 ${code} 已完成,不能取消` }; if (order.status === 9) { return { ok: true, message: 'ok', data: { bill_id: order.id, bill_no: order.bill_no, bill_type: billType, status: 9, already_cancelled: true } }; } // 出库单已推送(3)且未扣减库存:取消时释放锁定库存 if (billType === 2 && order.status === 3 && !order.stock_deducted) { const items = await ctx.model.StockItem.findAll({ where: { bill_type: 2, bill_id: order.id, product_id: { [ctx.app.Sequelize.Op.ne]: null } }, attributes: [ 'product_id', 'code', 'name', 'quantity', 'inventory_type' ], order: [[ 'product_id', 'ASC' ]], }); const transaction = await ctx.model.transaction(); try { for (const it of items) { const p = it.get ? it.get({ plain: true }) : it; const itemType = p.inventory_type === 'CC' ? 'CC' : 'ZC'; await applyStockChange(ctx, { bizType: 'outbound_unlock', principalId, warehouseId: order.warehouse_id, productId: Number(p.product_id), itemCode: p.code, itemName: p.name, itemType, quantity: Number(p.quantity) || 0, billId: order.id, billNo: order.bill_no, remark: '取消释放锁定库存(order.cancel)', transaction, }); } await order.update({ status: 9 }, { transaction }); await transaction.commit(); } catch (err) { await transaction.rollback(); throw err; } } else { await order.update({ status: 9 }); } const result = { bill_id: order.id, bill_no: order.bill_no, bill_type: billType, status: 9, already_cancelled: false, cancel_reason: pickFirst(data, [ 'cancelReason', 'reason', 'remark' ]), }; ctx.logger.info('[order-callback] order.cancel 已取消', result); return { ok: true, message: 'ok', data: result }; } module.exports = { pickFirst, extractLines, extractPackages, applyActualQty, resolvePackageExpress, confirmInbound, matchInbound, confirmOutbound, confirmDelivery, cancelOrder, };