oms/backend/app/lib/orderCallback.js
liufumingren 23a7715dc9 feat(shop): 数据库店铺新增回传单号设置,发货确认后把运单号写回客户库
- shop_database_configs 增加回传设置:方式(不回传/写回字段/写回行)、目标表、运单号字段、定位字段、间隔符、写回行字段映射
- 配置弹窗新增「回传单号」区块:写回字段选表+字段+定位字段+间隔符;写回行按回传值(订单号/运单号/快递公司编码/快递公司名称/回传时间)逐项选列
- 保存时校验回传表与列在客户库中存在,回传行必填项(订单号、运单号)
- 发货确认(WMS 回推运单号)后自动回传:写回字段按间隔符合并写单值,写回行按订单号先删后插保证幂等;失败只记日志不影响发货确认

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-05 16:33:15 +08:00

1218 lines
54 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 completeInbound = require('../utils/completeInbound');
const { applyStockChange } = require('../utils/stockRecord');
const { deductDeliveryStock } = require('../utils/deliveryStock');
const { ORDER_STATUS, orderModelName, orderStatusLabel } = require('./orderStatus');
/**
* 外部回调(对外通用回调接口 /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<String>} 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<Object>} 包裹数组(无则空数组)
*/
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<Object>} packages 包裹数组
* @param {Array<String>} 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<Object>} packages 包裹数组
* @return {Array<String>} 运单号数组(无则空数组)
*/
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<Object>} packages 包裹数组
* @return {Promise<{ok: Boolean, items: Array<Object>, 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<String>} 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') {
const body = Object.keys(value)
.sort()
.map(key => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
.join(',');
return `{${body}}`;
}
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<Number>} 实际更新的明细行数
*/
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, stock_locked: 0 }, { 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<Object>} packages 包裹数组
* @param {Object} [options] 可选参数
* @param {Object} [options.express] 解析后的快递({ raw, code, name, source }),优先于包裹里的原值
* @return {Promise<{changed: Array<String>, express_code: String, express_codes: Array<String>,
* 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<Object>} packages 包裹数组
* @param {Array<Object>} 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<Object>} packages 包裹数组
* @param {Array<Object>} 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<Object>} packages 包裹数组
* @param {Array<Object>} 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<String>}>} 摘要 + 是否写库 + 覆盖的快递列
*/
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 resolved = await resolveDeliveryBill(ctx, { code, principalId });
const order = resolved.order;
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,
resolved.isNewModel ? wrapNewOrderView(resolved) : order,
packages,
{ express: expressResult.first }
);
// 新表(order_index + 状态表):委外中 → 配送(扣减锁定库存),已配送幂等回执
if (resolved.isNewModel) {
const result = await confirmOrderStatusDelivery(ctx, { resolved, payload, packages, lines, pkgInfo });
if (result.ok) {
await writeBackShopWaybills(ctx, resolved.order, pkgInfo, {
orderNo: resolved.order.parent_order_no || resolved.index.order_no,
});
}
return result;
}
// 幂等:已完成(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);
await writeBackShopWaybills(ctx, order, pkgInfo);
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);
await writeBackShopWaybills(ctx, order, pkgInfo);
return { ok: true, message: 'ok', data: result };
}
/**
* 推导源订单号(数据库店铺回传单号时用于定位客户库中的订单行)
* 新表取 parent_order_no(拉单时写入的平台/源单号),老表取 source_order_codes 首个
* @param {Object} order 订单实例
* @return {String} 源订单号(取不到返回空串)
*/
function guessSourceOrderNo(order) {
if (!order) return '';
if (order.parent_order_no) return String(order.parent_order_no).trim();
const raw = order.source_order_codes;
if (Array.isArray(raw) && raw.length) return String(raw[0]).trim();
if (typeof raw === 'string' && raw) {
try {
const parsed = JSON.parse(raw);
if (Array.isArray(parsed) && parsed.length) return String(parsed[0]).trim();
} catch (err) {
// 非 JSON 时按单值处理
return raw.trim();
}
}
return '';
}
/**
* 数据库店铺(shops.type=3)回传单号:发货确认拿到运单号后写回客户自有库
* 只对数据库店铺生效;未开启回传/配置缺失/调用失败都只记日志,不影响发货确认本身
* @param {Object} ctx egg context
* @param {Object} order 订单实例(状态表行 / order_deliveries)
* @param {Object} pkgInfo 运单号与快递解析结果(express_code / express_codes / logistics_*)
* @param {Object} [options] 可选参数
* @param {String} [options.orderNo] 源订单号(缺省按实例字段推导)
* @return {Promise<Object|null>} 回传结果(无需回传时返回 null)
*/
async function writeBackShopWaybills(ctx, order, pkgInfo, { orderNo } = {}) {
const shopId = Number(order && order.shop_id);
if (!shopId) return null;
const codes = [];
if (pkgInfo && Array.isArray(pkgInfo.express_codes)) {
for (const code of pkgInfo.express_codes) {
const text = String(code == null ? '' : code).trim();
if (text && !codes.includes(text)) codes.push(text);
}
}
const single = String((pkgInfo && pkgInfo.express_code) || '').trim();
if (single && !codes.includes(single)) codes.push(single);
if (!codes.length) return null;
const shop = await ctx.model.Shop.findByPk(shopId, { attributes: [ 'id', 'principal_id', 'type' ] });
if (!shop || Number(shop.type) !== 3) return null;
const sourceOrderNo = String(orderNo || guessSourceOrderNo(order)).trim();
if (!sourceOrderNo) return null;
try {
const result = await ctx.service.shopDatabaseSync.writeBackWaybills(shop, {
orderNo: sourceOrderNo,
waybills: codes,
expressCode: (pkgInfo && pkgInfo.logistics_code) || single,
expressName: pkgInfo && pkgInfo.logistics_name,
});
if (result.written) {
ctx.logger.info(`[order-callback] 数据库店铺 ${shop.id} 回传单号(订单 ${sourceOrderNo}):${codes.join(',')}`);
} else {
ctx.logger.info(`[order-callback] 数据库店铺 ${shop.id} 跳过回传单号:${result.reason}`);
}
return result;
} catch (err) {
ctx.logger.warn(`[order-callback] 数据库店铺 ${shop.id} 回传单号失败:${err.message}`);
return null;
}
}
/**
* 定位发货单(订单):先查新表(order_index.order_no → 对应状态表),再回退老表(order_deliveries)
* @param {Object} ctx egg context
* @param {Object} options 参数
* @param {String} options.code 外部回传的单号(deliveryOrderCode / outBizCode)
* @param {Number} options.principalId 主体ID
* @return {Promise<{isNewModel: Boolean, order: Object|null, index: Object|null}>} 定位结果
*/
async function resolveDeliveryBill(ctx, { code, principalId }) {
const index = await ctx.model.OrderIndex.findOne({ where: { order_no: code, principal_id: principalId } });
if (index) {
const row = await ctx.model[orderModelName(index.current_status)].findByPk(index.id);
if (row) return { isNewModel: true, order: row, index };
}
const legacy = await ctx.model.OrderDelivery.findOne({
where: { delivery_order_code: code, principal_id: principalId },
});
return { isNewModel: false, order: legacy, index: null };
}
/**
* 新表(状态表行)的视图包装:补齐 delivery_order_code 别名,并把 update 落到状态表
* @param {Object} resolved resolveDeliveryBill 的返回
* @return {Object} 供 applyDeliveryPackageInfo 使用的视图对象
*/
function wrapNewOrderView(resolved) {
const order = resolved.order;
const view = {
...order.get({ plain: true }),
delivery_order_code: resolved.index.order_no,
update: async patch => {
await order.update(patch);
Object.assign(view, patch);
},
};
return view;
}
/**
* 新表发货确认:委外中 → 配送(扣减审核时锁定的库存),已配送幂等回执
* @param {Object} ctx egg context
* @param {Object} options 参数
* @param {Object} options.resolved resolveDeliveryBill 的返回
* @param {Object} options.payload 归一化报文
* @param {Array} options.packages 包裹数组
* @param {Array} options.lines 发货明细行
* @param {Object} options.pkgInfo 运单/物流回写结果
* @return {Promise<Object>} 处理结果
*/
async function confirmOrderStatusDelivery(ctx, { resolved, payload, packages, lines, pkgInfo }) {
const { order, index } = resolved;
const base = {
delivery_order_id: Number(order.id),
delivery_order_code: index.order_no,
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,
};
// 幂等:已配送(已完成)再次收到相同报文只补写缺失字段,不重复流转、不重复扣减库存
if (index.current_status === ORDER_STATUS.DELIVERY) {
const done = { ...base, status: ORDER_STATUS.DELIVERY, already_completed: true };
ctx.logger.info('[order-callback] 订单已配送,跳过(幂等回执)', done);
return { ok: true, message: 'ok', data: done };
}
if (index.current_status !== ORDER_STATUS.OUTSOURCING) {
return {
ok: false,
message: `单据 ${index.order_no} 当前状态(${orderStatusLabel(index.current_status)})不允许发货确认,需为「委外中」`,
};
}
const d = (payload && payload.deliveryOrder) || {};
const externalId = toNumberOrNull(d.deliveryOrderId);
const now = new Date();
const prev = order.wms_push_result && typeof order.wms_push_result === 'object' ? order.wms_push_result : {};
// 推送结果与确认报文摘要先回写,随状态流转一并搬到配送表
await order.update({
wms_status: 'delivered',
wms_order_no: externalId == null ? order.wms_order_no : String(externalId),
wms_synced_at: now,
wms_push_result: { ...prev, confirm: buildDeliveryConfirmSummary(payload, packages, lines) },
});
await ctx.service.orderStatus.confirmDelivery({
ids: [ Number(order.id) ],
principalId: Number(order.principal_id),
});
// 配送后需要把发货结果同步回外部打单平台(店管家发货接口),这里只标记待同步,
// 真正的调用交给定时任务 externalSendSyncWorker(失败重试 / 转异常都在那边收敛)
await ctx.service.externalSendSync.markPending([ Number(order.id) ], Number(order.principal_id));
const result = {
...base,
status: ORDER_STATUS.DELIVERY,
already_completed: false,
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)、或推送未成功但已锁定库存(stock_locked=1)且未扣减库存:取消时释放锁定库存
if (billType === 2 && (order.status === 3 || Number(order.stock_locked) === 1) && !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, stock_locked: 0 }, { 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,
resolveDeliveryBill,
cancelOrder,
};