feat(returnUnpack): 原单 items 顶层透出与订单序列表车道定位

- create 新增顶层 order_items 字段(原订单商品明细,order.items 顶层透出),新建/幂等复用分支返回结构一致,非原单退回为 null
- 原订单详情解析优先按订单 id 序列表(wms_order_id_location_{warehouseId})定位车道(current/history/dispatch/outsourced)直接查分表,未命中再遍历四车道、最后回退基表;修复订单位于 history/dispatch 车道时 create/detail 返回 order=null、order_items=null
- _resolveReturnOrderInfo 原订单兜底查询同步改造(查退回交易单号/快递信息)
- 同步 methods/system.json 与 methods/changes/system.json 变更记录
This commit is contained in:
liufumingren 2026-08-21 23:03:04 +08:00
parent 9894e15ccd
commit f1a487bb06
4 changed files with 214 additions and 82 deletions

View File

@ -416,28 +416,65 @@ class AfterSaleService extends Service {
const { ctx, app } = this;
try {
// 1. 查询订单主记录(优先主表,再尝试工厂分表)
// 1. 查询订单主记录:优先按订单 id 序列表(wms_order_id_location_{warehouseId})
// 定位订单所在车道直接查对应分表,未命中再按 current → history → dispatch → outsourced
// 遍历回退,最后回退基表(存量订单)
let order = null;
try {
order = await ctx.model.OrderDelivery.findOne({
where: { id: orderDeliveryId },
raw: true,
});
} catch (err) {
ctx.logger.warn(`[_resolveOrderDetail] 主表查询失败: ${err.message}`);
}
let preferredLane = null;
const factory = ctx.model.OrderDeliveryFactory;
if (!order && ctx.model.OrderDeliveryFactory) {
if (factory && typeof factory.getCurrentModel === 'function') {
const laneLabels = [ 'current', 'history', 'dispatch', 'outsourced' ];
const laneGetters = {
current: () => factory.getCurrentModel(warehouseId),
history: () => factory.getHistoryModel(warehouseId),
dispatch: () => factory.getDispatchModel(warehouseId),
outsourced: () => factory.getOutsourcedModel(warehouseId),
};
// 序列表定位优先:命中车道先查对应分表
try {
const factoryModel = await ctx.model.OrderDeliveryFactory.getCurrentModel(warehouseId);
if (factoryModel) {
order = await factoryModel.findOne({
if (typeof factory.getOrderLocation === 'function') {
const location = await factory.getOrderLocation(orderDeliveryId, warehouseId);
if (location && laneGetters[location]) {
preferredLane = String(location);
}
}
} catch (err) {
ctx.logger.warn(`[_resolveOrderDetail] 序列表定位失败: ${err.message}`);
}
const orderedLanes = preferredLane
? [ preferredLane, ...laneLabels.filter(label => label !== preferredLane) ]
: laneLabels;
for (const lane of orderedLanes) {
try {
const model = await laneGetters[lane]();
if (!model || typeof model.findOne !== 'function') continue;
const row = await model.findOne({
where: { id: orderDeliveryId },
raw: true,
});
if (row) {
order = row;
break;
}
} catch (err) {
ctx.logger.warn(`[_resolveOrderDetail] 分表 ${lane} 查询失败: ${err.message}`);
}
}
}
// 分表均未命中:回退基表(存量订单)
if (!order) {
try {
order = await ctx.model.OrderDelivery.findOne({
where: { id: orderDeliveryId },
raw: true,
});
} catch (err) {
ctx.logger.warn(`[_resolveOrderDetail] 工厂模型查询失败: ${err.message}`);
ctx.logger.warn(`[_resolveOrderDetail] 主表查询失败: ${err.message}`);
}
}
@ -503,64 +540,86 @@ class AfterSaleService extends Service {
}
}
// 回退:若 items 为空且 OrderItemsFactory 可用,从分表查询
// 回退:若 items 为空且 OrderItemsFactory 可用,从分表查询(序列表定位车道优先)
if (orderItems.length === 0 && ctx.model.OrderItemsFactory) {
try {
const itemsModel = await ctx.model.OrderItemsFactory.getCurrentModel(warehouseId);
if (itemsModel) {
const dbItems = await itemsModel.findAll({
where: { order_id: orderDeliveryId },
raw: true,
});
if (dbItems && dbItems.length > 0) {
// 收集 stock_id 用于批量查库存详情
const stockIds = dbItems
.map(item => Number(item.stock_id))
.filter(id => Number.isInteger(id) && id > 0);
const itemsFactory = ctx.model.OrderItemsFactory;
const itemsLaneLabels = [ 'current', 'history', 'dispatch' ];
const itemsLaneGetters = {
current: () => itemsFactory.getCurrentModel(warehouseId),
history: () => itemsFactory.getHistoryModel(warehouseId),
dispatch: () => itemsFactory.getDispatchModel(warehouseId),
};
const orderedItemsLanes = preferredLane && itemsLaneGetters[preferredLane]
? [ preferredLane, ...itemsLaneLabels.filter(label => label !== preferredLane) ]
: itemsLaneLabels;
// 批量获取库存详情(带缓存的并行查询:条码 + 图片 + 库存属性)
const stockDetailsMap = new Map();
if (stockIds.length > 0) {
try {
const details = await ctx.service.systems.stockWarehouse.getStockDetails(stockIds, {
warehouseId,
cacheTTL: 300,
});
for (const detail of details) {
stockDetailsMap.set(detail.id, detail);
}
} catch (err) {
ctx.logger.warn(`[_resolveOrderDetail] 批量获取库存详情失败: ${err.message}`);
}
}
orderItems = dbItems.map(item => {
const stock = stockDetailsMap.get(Number(item.stock_id)) || {};
return {
id: item.id,
order_line_no: item.order_line_no || '',
item_code: item.item_code || stock.item_code || '',
item_name: item.item_name || stock.item_name || '',
sku_property: stock.sku_property || '',
quantity: stock.quantity || 0,
locked_quantity: stock.locked_quantity || 0,
is_batch_mgmt: stock.is_batch_mgmt || 'N',
is_shelf_life_mgmt: stock.is_shelf_life_mgmt || 'N',
is_images: stock.is_images || 'N',
store_id: stock.store_id || null,
packing_requirements: stock.packing_requirements || '',
stock_unit: stock.stock_unit || '',
image_url: stock.image_url || [],
barcodes: stock.barcodes || [],
plan_qty: item.plan_qty || 0,
stock_id: item.stock_id || null,
order_item_id: item.id,
order_id: orderDeliveryId,
};
let dbItems = [];
for (const lane of orderedItemsLanes) {
try {
const itemsModel = await itemsLaneGetters[lane]();
if (!itemsModel || typeof itemsModel.findAll !== 'function') continue;
const laneRows = await itemsModel.findAll({
where: { order_id: orderDeliveryId },
raw: true,
});
ctx.logger.info(`[_resolveOrderDetail] 从分表加载 ${orderItems.length} 条明细(含库存详情)`);
if (laneRows && laneRows.length > 0) {
dbItems = laneRows;
break;
}
} catch (err) {
ctx.logger.warn(`[_resolveOrderDetail] 商品明细分表 ${lane} 查询失败: ${err.message}`);
}
}
if (dbItems.length > 0) {
// 收集 stock_id 用于批量查库存详情
const stockIds = dbItems
.map(item => Number(item.stock_id))
.filter(id => Number.isInteger(id) && id > 0);
// 批量获取库存详情(带缓存的并行查询:条码 + 图片 + 库存属性)
const stockDetailsMap = new Map();
if (stockIds.length > 0) {
try {
const details = await ctx.service.systems.stockWarehouse.getStockDetails(stockIds, {
warehouseId,
cacheTTL: 300,
});
for (const detail of details) {
stockDetailsMap.set(detail.id, detail);
}
} catch (err) {
ctx.logger.warn(`[_resolveOrderDetail] 批量获取库存详情失败: ${err.message}`);
}
}
orderItems = dbItems.map(item => {
const stock = stockDetailsMap.get(Number(item.stock_id)) || {};
return {
id: item.id,
order_line_no: item.order_line_no || '',
item_code: item.item_code || stock.item_code || '',
item_name: item.item_name || stock.item_name || '',
sku_property: stock.sku_property || '',
quantity: stock.quantity || 0,
locked_quantity: stock.locked_quantity || 0,
is_batch_mgmt: stock.is_batch_mgmt || 'N',
is_shelf_life_mgmt: stock.is_shelf_life_mgmt || 'N',
is_images: stock.is_images || 'N',
store_id: stock.store_id || null,
packing_requirements: stock.packing_requirements || '',
stock_unit: stock.stock_unit || '',
image_url: stock.image_url || [],
barcodes: stock.barcodes || [],
plan_qty: item.plan_qty || 0,
stock_id: item.stock_id || null,
order_item_id: item.id,
order_id: orderDeliveryId,
};
});
ctx.logger.info(`[_resolveOrderDetail] 从分表加载 ${orderItems.length} 条明细(含库存详情)`);
}
} catch (err) {
ctx.logger.warn(`[_resolveOrderDetail] 分表查询商品明细失败: ${err.message}`);
}

View File

@ -31,7 +31,7 @@ class ReturnUnpackService extends Service {
* @param {Array<number>} [params.camera_ids] 摄像头ID列表。
* @param {number} [params.return_received_id] 关联退回收到单ID。
* @param {string} [params.remark] 备注。
* @return {Promise<Object>} 开单结果,含 id、record、is_original_return、store_remark、order。
* @return {Promise<Object>} 开单结果,含 id、record、is_original_return、store_remark、order、order_items。
*/
async create({ waybill_code, camera_ids, return_received_id, remark }) {
const { ctx, app } = this;
@ -106,6 +106,7 @@ class ReturnUnpackService extends Service {
if (existing) {
// 复用已有拆包单:返回主表 + 明细 + 视频 + 原订单详情(复用 detail 查询逻辑)
const existingDetail = await this.detail(existing.id);
const existingOrder = (existingDetail.related && existingDetail.related.order) || null;
ctx.logger.info(
`[returnUnpack.create] 运单号 ${waybillCode} 3 个月内已有拆包单 id=${existing.id},直接复用返回明细`
);
@ -114,7 +115,8 @@ class ReturnUnpackService extends Service {
record: existingDetail.record,
is_original_return: Boolean(existing.order_express_id),
store_remark: String(existingDetail.record && existingDetail.record.shop_name || ''),
order: (existingDetail.related && existingDetail.related.order) || null,
order: existingOrder,
order_items: existingOrder && Array.isArray(existingOrder.items) ? existingOrder.items : null,
reused: true,
};
}
@ -240,6 +242,7 @@ class ReturnUnpackService extends Service {
is_original_return: isOriginalReturn,
store_remark: storeRemark,
order,
order_items: order && Array.isArray(order.items) ? order.items : null,
};
}
@ -988,24 +991,55 @@ class ReturnUnpackService extends Service {
if (order_id && !info.trade_no) {
try {
let order = null;
try {
order = await ctx.model.OrderDelivery.findOne({
where: { id: order_id },
raw: true,
});
} catch (err) {
// 主表查询失败,继续走工厂分表兜底
}
if (!order && ctx.model.OrderDeliveryFactory) {
const factory = ctx.model.OrderDeliveryFactory;
if (factory && typeof factory.getCurrentModel === 'function') {
const laneLabels = [ 'current', 'history', 'dispatch', 'outsourced' ];
const laneGetters = {
current: () => factory.getCurrentModel(warehouse_id),
history: () => factory.getHistoryModel(warehouse_id),
dispatch: () => factory.getDispatchModel(warehouse_id),
outsourced: () => factory.getOutsourcedModel(warehouse_id),
};
// 序列表定位优先:命中车道先查对应分表,未命中按原顺序遍历回退
try {
const factoryModel = await ctx.model.OrderDeliveryFactory.getCurrentModel(warehouse_id);
if (factoryModel) {
order = await factoryModel.findOne({ where: { id: order_id }, raw: true });
if (typeof factory.getOrderLocation === 'function') {
const location = await factory.getOrderLocation(order_id, warehouse_id);
if (location && laneGetters[location]) {
laneLabels.sort((a, b) => (a === location ? -1 : b === location ? 1 : 0));
}
}
} catch (err) {
// 分表查询失败忽略
// 定位失败忽略,保持遍历顺序
}
for (const lane of laneLabels) {
try {
const model = await laneGetters[lane]();
if (!model || typeof model.findOne !== 'function') continue;
const row = await model.findOne({ where: { id: order_id }, raw: true });
if (row) {
order = row;
break;
}
} catch (err) {
// 该表可能不存在,继续下一张
}
}
}
// 分表均未命中:回退基表(存量订单)
if (!order) {
try {
order = await ctx.model.OrderDelivery.findOne({
where: { id: order_id },
raw: true,
});
} catch (err) {
// 主表查询失败忽略
}
}
if (order) {
info.trade_no = String(order.source_order_codes || order.source_platform_code || '');
if (!info.express && order.logistics_name) info.express = String(order.logistics_name);

View File

@ -1,4 +1,37 @@
[
{
"version": "2026.08.21-returnUnpack.orderLocationLane",
"date": "2026-08-21",
"type": "fixed",
"summary": "returnUnpack 原订单详情解析修复:优先按订单 id 序列表(wms_order_id_location_{warehouseId})定位订单所在车道(current/history/dispatch/outsourced)直接查对应分表,未命中再按 current→history→dispatch→outsourced 遍历、最后回退基表。修复订单位于 history/dispatch 车道时 create/detail 返回 order=null、order_items=null 的问题。",
"methods": [
"returnUnpack.create",
"returnUnpack.detail",
"returnUnpack.queryByWaybill"
],
"notes": [
"app/service/systems/afterSale.js _resolveOrderDetail:主记录查询由「基表优先→current 分表」改为「OrderDeliveryFactory.getOrderLocation 序列表定位车道优先→current/history/dispatch/outsourced 四车道遍历→基表回退(存量订单)」;商品明细回退查询同步按定位车道优先遍历 current/history/dispatch 三个 items 分表",
"app/service/systems/return_unpack.js _resolveReturnOrderInfo:原订单兜底查询同改(交易单号/快递信息),查退回场景同步受益",
"序列表未回填的存量订单(getOrderLocation 返回 null)自动落入遍历回退,行为不退化;定位/单表查询失败仅告警不阻断主流程",
"无 API 出参结构变化(仅修复 order/order_items 由 null 变正常返回),methods/system.json 无需更新"
],
"module": "returnUnpack"
},
{
"version": "2026.08.21-returnUnpack.create-orderItems",
"date": "2026-08-21",
"type": "enhanced",
"summary": "returnUnpack.create 返回新增顶层 order_items 字段:原订单商品明细数组(即 order.items 的顶层透出,含 item_code/item_name/sku_property/quantity/plan_qty/barcodes/image_url 等),仅原单退回且原订单详情解析成功时返回;非原单退回或原订单详情缺失时为 null。新建与幂等复用两个分支返回结构一致。",
"methods": [
"returnUnpack.create"
],
"notes": [
"app/service/systems/return_unpack.js create:新建分支返回 order_items(order.items 为数组时透出,否则 null);幂等复用分支从 detail().related.order 提取同名字段,与 order 字段同源",
"向后兼容:仅新增顶层字段,order/record 等既有字段不变",
"同步更新 methods/system.json 中 returnUnpack.create 的 response(新增 order_items 字段说明)"
],
"module": "returnUnpack"
},
{
"version": "2026.08.21-index.searchSpaces-batch-search",
"date": "2026-08-21",

View File

@ -36204,7 +36204,7 @@
"list": [
{
"method": "returnUnpack.create",
"description": "开拆包单(明细不在此提交,由 returnUnpack.addDetail 逐件录入)。用 waybill_code 反查 wms_order_express 判定是否原单退回,命中则回填 order_express_id/order_id/store_id 及订单信息快照(source_order_codes 平台交易单号 / shop_name 店铺名称=货主自定义店铺名称 store_remask)并返回原订单详情;未命中原单时按 warehouse_id+waybill_code 从 wms_return_query_log 反查货主(限最近 3 个月内登记)。幂等复用:同一仓库同一运单号 3 个月内已存在非 cancelled 拆包单时,不重复创建,直接返回已有拆包单的主表+明细(record.details)+视频(record.videos)+原订单详情(order),并携带 reused=true 标识;同运单号存在多张拆包单时优先复用已录明细的最新单(按明细表真实计数判定),超过 3 个月视为运单号已复用,按新单正常创建。拆包单号规则 RP+YYYYMMDD+6位序号。仓库隔离:warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入。",
"description": "开拆包单(明细不在此提交,由 returnUnpack.addDetail 逐件录入)。用 waybill_code 反查 wms_order_express 判定是否原单退回,命中则回填 order_express_id/order_id/store_id 及订单信息快照(source_order_codes 平台交易单号 / shop_name 店铺名称=货主自定义店铺名称 store_remask)并返回原订单详情(order)与顶层原单商品明细(order_items);未命中原单时按 warehouse_id+waybill_code 从 wms_return_query_log 反查货主(限最近 3 个月内登记)。幂等复用:同一仓库同一运单号 3 个月内已存在非 cancelled 拆包单时,不重复创建,直接返回已有拆包单的主表+明细(record.details)+视频(record.videos)+原订单详情(order),并携带 reused=true 标识;同运单号存在多张拆包单时优先复用已录明细的最新单(按明细表真实计数判定),超过 3 个月视为运单号已复用,按新单正常创建。拆包单号规则 RP+YYYYMMDD+6位序号。仓库隔离:warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [],
@ -36269,6 +36269,12 @@
"required": false,
"description": "原订单详情(含 items 明细,仅原单退回时返回,非原单为 null)"
},
{
"name": "order_items",
"type": "array",
"required": false,
"description": "原订单商品明细数组(即 order.items 的顶层透出,含 item_code/item_name/sku_property/quantity/plan_qty/barcodes/image_url 等,仅原单退回时返回;非原单退回或原订单详情缺失时为 null)"
},
{
"name": "reused",
"type": "boolean",