feat(order): B2B 分箱快照商品明细补仓库商品属性,与拣货明细同口径

- order.getB2bPackingSnapshot 商品明细新增 sku_property / stock_unit / store_id / owner_code / store_remark / stock
- 商品属性走 stockWarehouse.getStockDetails(stockIds, { warehouseId }) 带缓存链路,未命中时按 item_snapshot → order_items 列逐级兜底
- item_code / item_name 取值优先 stock 属性,与 pick.wavePickTaskDetail 的 picking_details 保持一致
- loadB2bOrderItems 查询列补 owner_code
- 同步 methods/system.json 与 methods/changes/system.json(走 doc:api:update)
- 补充单测:stock 属性挂载、快照兜底,7 passing

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-22 18:44:03 +08:00
parent d86857d473
commit 22e95306b7
4 changed files with 303 additions and 7 deletions

View File

@ -997,7 +997,7 @@ class OrderB2bService extends Service {
: await factory.getCurrentModel(warehouseId);
const options = {
where: { order_id: orderId },
attributes: [ 'id', 'order_id', 'item_id', 'item_code', 'item_name', 'plan_qty', 'stock_id', 'item_snapshot' ],
attributes: [ 'id', 'order_id', 'item_id', 'item_code', 'item_name', 'plan_qty', 'stock_id', 'item_snapshot', 'owner_code' ],
order: [[ 'id', 'ASC' ]],
raw: true,
transaction,
@ -1071,6 +1071,125 @@ class OrderB2bService extends Service {
return result;
}
/**
* 批量查询订单商品对应的仓库商品属性(stock_warehouse),口径与拣货明细一致。
*
* 走 stockWarehouse.getStockDetails(带缓存),拿不到时按 item_snapshot → order_items 列
* 逐级兜底拼装,保证每个商品行都有 stock 属性可展示。
*
* @param {Object} params 参数。
* @param {number} params.warehouseId 仓库ID。
* @param {Array<Object>} params.orderItems 订单商品明细行。
* @return {Promise<Map<number, Object>>} stock_id → stock 属性对象。
*/
async loadB2bStockDetailMap({ warehouseId, orderItems }) {
const { ctx } = this;
const stockDetailMap = new Map();
const orderItemList = Array.isArray(orderItems) ? orderItems : [];
const stockIds = [ ...new Set(orderItemList
.map(item => Number(item && item.stock_id || 0))
.filter(stockId => Number.isInteger(stockId) && stockId > 0)) ];
if (stockIds.length > 0) {
try {
const stockWarehouseSvc = ctx.service && ctx.service.systems && ctx.service.systems.stockWarehouse;
if (stockWarehouseSvc && typeof stockWarehouseSvc.getStockDetails === 'function') {
const stockDetails = await stockWarehouseSvc.getStockDetails(stockIds, { warehouseId });
for (const detail of (Array.isArray(stockDetails) ? stockDetails : [])) {
stockDetailMap.set(Number(detail && detail.id || 0), detail);
}
}
} catch (error) {
ctx.logger?.warn?.(`[getB2bPackingSnapshot] 查询仓库商品属性失败,降级使用订单快照: ${error.message}`);
}
}
// 兜底:用 item_snapshot(下单时商品快照)→ order_items 列拼装
for (const item of orderItemList) {
const stockId = Number(item && item.stock_id || 0);
if (!Number.isInteger(stockId) || stockId <= 0 || stockDetailMap.has(stockId)) {
continue;
}
const itemSnapshot = this.parseItemSnapshot(item.item_snapshot);
stockDetailMap.set(stockId, {
id: stockId,
item_code: String(itemSnapshot.item_code || item.item_code || '').trim(),
item_name: String(itemSnapshot.item_name || item.item_name || '').trim(),
sku_property: String(itemSnapshot.sku_property || '').trim(),
stock_unit: String(itemSnapshot.stock_unit || '').trim(),
store_id: Number(itemSnapshot.store_id || 0),
image_url: [],
barcodes: [],
});
}
return stockDetailMap;
}
/**
* 查询货主备注名(wms_store_warehouse.store_remask),口径与拣货明细一致。
*
* @param {Object} params 参数。
* @param {number} params.warehouseId 仓库ID。
* @param {number[]} params.storeIds 货主ID数组。
* @return {Promise<Map<number, string>>} store_id → 货主备注。
*/
async loadB2bStoreRemarkMap({ warehouseId, storeIds }) {
const { ctx, app } = this;
const remarkMap = new Map();
const normalizedStoreIds = [ ...new Set((Array.isArray(storeIds) ? storeIds : [])
.map(storeId => Number(storeId || 0))
.filter(storeId => Number.isInteger(storeId) && storeId > 0)) ];
if (normalizedStoreIds.length === 0 || !ctx.model.StoreWarehouse) {
return remarkMap;
}
try {
const rows = await ctx.model.StoreWarehouse.findAll({
where: {
store_id: { [app.Sequelize.Op.in]: normalizedStoreIds },
warehouse_id: warehouseId,
},
attributes: [ 'store_id', 'store_remask' ],
raw: true,
});
for (const row of (Array.isArray(rows) ? rows : [])) {
const storeId = Number(row && row.store_id || 0);
if (storeId > 0 && !remarkMap.has(storeId)) {
remarkMap.set(storeId, String(row.store_remask || '').trim());
}
}
} catch (error) {
ctx.logger?.warn?.(`[getB2bPackingSnapshot] 查询货主备注失败: ${error.message}`);
}
return remarkMap;
}
/**
* 解析订单商品快照 JSON(item_snapshot 为下单时的 wms_stock_warehouse 快照)。
*
* @param {*} rawSnapshot 原始快照数据。
* @return {Object} 解析后的快照对象。
*/
parseItemSnapshot(rawSnapshot) {
if (!rawSnapshot) {
return {};
}
if (typeof rawSnapshot === 'string') {
try {
const parsed = JSON.parse(rawSnapshot);
return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
} catch (_) {
return {};
}
}
if (typeof rawSnapshot === 'object' && !Array.isArray(rawSnapshot)) {
return rawSnapshot;
}
return {};
}
/**
* 查询仓库是否开启 B2B 分箱齐套校验。
* @param {number} warehouseId 仓库ID。
@ -1378,6 +1497,11 @@ class OrderB2bService extends Service {
pickLocationSpaceKeys.add(location.space_id ? `id:${location.space_id}` : `name:${location.space_name}`);
}
}
const stockDetailMap = await this.loadB2bStockDetailMap({ warehouseId, orderItems });
const storeRemarkMap = await this.loadB2bStoreRemarkMap({
warehouseId,
storeIds: [ ...stockDetailMap.values() ].map(stock => Number(stock && stock.store_id || 0)),
});
const packedByItemId = new Map();
for (const packedItem of packedItems) {
const itemId = Number(packedItem.order_item_id);
@ -1389,17 +1513,36 @@ class OrderB2bService extends Service {
}
const items = orderItems.map(item => {
const boxes = packedByItemId.get(Number(item.id)) || [];
const stockId = Number(item.stock_id || 0);
// 商品属性与拣货明细同口径:stock 为 getStockDetails 完整对象(缺失时按快照兜底)
const stock = stockDetailMap.get(stockId) || {
id: stockId || null,
item_code: '',
item_name: '',
sku_property: '',
stock_unit: '',
store_id: 0,
image_url: [],
barcodes: [],
};
const storeId = Number(stock.store_id || 0);
return {
order_item_id: Number(item.id),
item_id: item.item_id,
stock_id: item.stock_id,
item_code: item.item_code,
item_name: item.item_name,
item_code: stock.item_code,
item_name: stock.item_name,
sku_property: stock.sku_property || '',
stock_unit: stock.stock_unit || '',
store_id: storeId,
owner_code: String(item.owner_code || '').trim(),
store_remark: storeRemarkMap.get(storeId) || '',
item_snapshot: item.item_snapshot,
plan_qty: item.plan_qty === null || item.plan_qty === undefined ? null : Number(item.plan_qty),
packed_quantity: boxes.reduce((sum, box) => sum + box.quantity, 0),
boxes,
pick_locations: pickLocationMap.get(Number(item.id)) || [],
stock,
};
});

View File

@ -1,4 +1,20 @@
[
{
"version": "2026.11.21-b2b-snapshot-stock-attrs",
"date": "2026-11-21",
"type": "updated",
"summary": "order.getB2bPackingSnapshot 商品明细补仓库商品属性(与拣货明细同口径):新增 sku_property / stock_unit / store_id / owner_code / store_remark / stock",
"methods": [
"order.getB2bPackingSnapshot"
],
"notes": [
"商品属性走 stockWarehouse.getStockDetails(stockIds, { warehouseId }) 带缓存链路,与 pick.wavePickTaskDetail 的 picking_details 完全一致;未命中时按 order_items.item_snapshot → order_items 列兜底,保证每行都有可展示的商品信息。",
"新增字段:sku_property(规格)、stock_unit(单位)、store_id(货主ID)、owner_code(货主编码,取 order_items.owner_code)、store_remark(货主备注名,按 store_id 关联 wms_store_warehouse.store_remask)、stock(完整仓库商品属性对象,键与拣货明细相同,含 barcodes / image_url / quantity / locked_quantity / pick_requirements / recheck_requirements 等)。",
"item_code / item_name 取值口径由 order_items 列改为优先 stock 属性(getStockDetails → item_snapshot → order_items 列),与拣货明细一致;字段名与结构不变,仅取值优先级变化。",
"实现:app/service/systems/order_b2b.js#loadB2bStockDetailMap / #loadB2bStoreRemarkMap(新增),由 getB2bPackingSnapshot 调用;loadB2bOrderItems 查询列补 owner_code。",
"库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 与变更记录后,再用 script/method-doc-import.cjs 回填开发库与生产库,import → export 往返校验与文件逐字节一致。"
]
},
{
"version": "2026.11.19-b2b-snapshot-pick-locations",
"date": "2026-11-19",

View File

@ -2,7 +2,7 @@
"module": "system",
"description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内",
"version": "0.3.375",
"updatedAt": "2026-11-19",
"updatedAt": "2026-11-21",
"headers": [
{
"name": "platform",
@ -4308,7 +4308,7 @@
},
{
"method": "order.getB2bPackingSnapshot",
"description": "查询单个 B2B 订单的商品明细与分箱快照。商品明细返回应拣数量、已分箱数量、对应箱号/箱内数量,以及该商品需要从哪些储位取货(取货储位来自订单储位分配表 wms_picking);同时返回订单号、订单状态、备货状态、总箱数、取货储位数量与当前仓库是否开启齐套校验。",
"description": "查询单个 B2B 订单的商品明细与分箱快照。商品明细返回应拣数量、已分箱数量、对应箱号/箱内数量、该商品需要从哪些储位取货(取货储位来自订单储位分配表 wms_picking),以及每个商品的仓库商品属性(stock,与拣货明细同口径);同时返回订单号、订单状态、备货状态、总箱数、取货储位数量与当前仓库是否开启齐套校验。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
@ -4375,7 +4375,7 @@
"name": "items",
"type": "array<object>",
"required": true,
"description": "订单商品明细数组;每项含 order_item_id、item_id、stock_id、item_code、item_name、item_snapshot、plan_qty、packed_quantity、boxes({box_no, quantity} 数组)、pick_locations(取货储位数组)"
"description": "订单商品明细数组;每项含 order_item_id、item_id、stock_id、item_code、item_name、sku_property(规格)、stock_unit(单位)、store_id(货主ID)、owner_code(货主编码)、store_remark(货主备注名)、item_snapshot、plan_qty、packed_quantity、boxes({box_no, quantity} 数组)、pick_locations(取货储位数组)、stock(完整仓库商品属性对象,含 sku_property/stock_unit/barcodes/image_url/quantity/locked_quantity 等,与拣货明细同口径)"
}
],
"errors": [
@ -4387,7 +4387,8 @@
"notes": [
"先查当前订单分表,未命中时查配送分表;商品明细从对应分表读取,分箱数据按 warehouse_id + order_id 读取。",
"该接口返回只读完整快照;提交变更请使用 order.updateB2bPackingItems。",
"取货储位口径:按 warehouse_id + order_id 查询 wms_picking(订单储位分配结果,排除 status=cancel),按 order_item_id 分到每个商品明细行,同一商品在同一储位(space_id,缺失时退回 space_name)的多条分配记录合并为一条并累加数量,按库位名称升序输出 pick_locations:[{ space_id, space_name, quantity }];pick_location_count 为本单涉及的不同储位个数,未分配储位时 items[].pick_locations 输出空数组、pick_location_count 为 0。"
"取货储位口径:按 warehouse_id + order_id 查询 wms_picking(订单储位分配结果,排除 status=cancel),按 order_item_id 分到每个商品明细行,同一商品在同一储位(space_id,缺失时退回 space_name)的多条分配记录合并为一条并累加数量,按库位名称升序输出 pick_locations:[{ space_id, space_name, quantity }];pick_location_count 为本单涉及的不同储位个数,未分配储位时 items[].pick_locations 输出空数组、pick_location_count 为 0。",
"商品属性口径(与 pick.wavePickTaskDetail 的 picking_details 一致):批量调用 stockWarehouse.getStockDetails(stockIds, { warehouseId }) 取仓库商品属性,item_code / item_name / sku_property / stock_unit / store_id 优先取该结果;未命中时按 order_items.item_snapshot(下单时快照)→ order_items 列逐级兜底。store_remark 按 store_id 关联 wms_store_warehouse.store_remask(同仓库)返回,owner_code 取 order_items.owner_code。每行同时输出 stock(完整属性对象,含 barcodes / image_url / quantity / locked_quantity / pick_requirements 等),供前端直接复用拣货的渲染逻辑。"
]
},
{

View File

@ -185,6 +185,142 @@ describe('OrderB2bService packing quantity validation', () => {
]);
});
it('attaches stock attributes like picking details do', async () => {
const transaction = { commit: async () => {}, rollback: async () => {} };
const getStockDetailsCalls = [];
const service = Object.create(OrderB2bService.prototype);
service.app = { Sequelize: { Op: { ne: Symbol('ne'), in: Symbol('in') } } };
service.ctx = {
logger: { warn: () => {} },
service: {
systems: {
stockWarehouse: {
getStockDetails: async (stockIds, options) => {
getStockDetailsCalls.push({ stockIds, options });
return [
{
id: 501,
item_code: 'SKU-A',
item_name: '商品A(仓库资料)',
sku_property: '红色/L',
stock_unit: '件',
store_id: 3,
quantity: 100,
image_url: [ 'http://img/a.png' ],
barcodes: [{ id: 1, barcode: '690000000001' }],
},
{
id: 502,
item_code: 'SKU-B',
item_name: '商品B(仓库资料)',
sku_property: '',
stock_unit: '箱',
store_id: 3,
quantity: 8,
image_url: [],
barcodes: [],
},
];
},
},
},
},
model: {
transaction: async () => transaction,
OrderDeliveryFactory: {
getCurrentModel: async () => ({
findOne: async () => ({ id: 99, is_b2b: 'Y', status: 'pending', delivery_order_code: 'DO-99' }),
}),
},
OrderItemsFactory: {
getCurrentModel: async () => ({
findAll: async () => [
{ id: 11, stock_id: 501, item_code: 'SKU-A', item_name: '商品A', plan_qty: 2, owner_code: 'OW-1' },
{ id: 12, stock_id: 502, item_code: 'SKU-B', item_name: '商品B', plan_qty: 1, owner_code: '' },
],
}),
},
OrderB2bItem: { findAll: async () => [] },
OrderB2b: { findOne: async () => null },
Picking: { findAll: async () => [] },
StoreWarehouse: {
findAll: async () => [{ store_id: 3, store_remask: '货主备注X' }],
},
},
};
service.isB2bPackingQuantityCheckEnabled = async () => false;
const result = await service.getB2bPackingSnapshot({ warehouseId: 7, orderIds: [ 99 ] });
assert.strictEqual(getStockDetailsCalls.length, 1);
assert.deepStrictEqual(getStockDetailsCalls[0].stockIds, [ 501, 502 ]);
assert.deepStrictEqual(getStockDetailsCalls[0].options, { warehouseId: 7 });
const [ first, second ] = result.items;
assert.strictEqual(first.item_code, 'SKU-A');
assert.strictEqual(first.item_name, '商品A(仓库资料)');
assert.strictEqual(first.sku_property, '红色/L');
assert.strictEqual(first.stock_unit, '件');
assert.strictEqual(first.store_id, 3);
assert.strictEqual(first.owner_code, 'OW-1');
assert.strictEqual(first.store_remark, '货主备注X');
assert.strictEqual(first.stock.id, 501);
assert.deepStrictEqual(first.stock.barcodes, [{ id: 1, barcode: '690000000001' }]);
assert.deepStrictEqual(first.stock.image_url, [ 'http://img/a.png' ]);
assert.strictEqual(second.stock_unit, '箱');
assert.strictEqual(second.owner_code, '');
assert.strictEqual(second.store_remark, '货主备注X');
});
it('falls back to item_snapshot for stock attributes when stock detail is missing', async () => {
const transaction = { commit: async () => {}, rollback: async () => {} };
const service = Object.create(OrderB2bService.prototype);
service.app = { Sequelize: { Op: { ne: Symbol('ne'), in: Symbol('in') } } };
service.ctx = {
logger: { warn: () => {} },
service: { systems: { stockWarehouse: { getStockDetails: async () => [] } } },
model: {
transaction: async () => transaction,
OrderDeliveryFactory: {
getCurrentModel: async () => ({
findOne: async () => ({ id: 99, is_b2b: 'Y', status: 'pending', delivery_order_code: 'DO-99' }),
}),
},
OrderItemsFactory: {
getCurrentModel: async () => ({
findAll: async () => [{
id: 11,
stock_id: 501,
item_code: 'SKU-A',
item_name: '商品A',
plan_qty: 1,
item_snapshot: JSON.stringify({
item_code: 'SKU-A',
item_name: '商品A(快照)',
sku_property: '蓝色/M',
stock_unit: '个',
store_id: 5,
}),
}],
}),
},
OrderB2bItem: { findAll: async () => [] },
OrderB2b: { findOne: async () => null },
Picking: { findAll: async () => [] },
StoreWarehouse: { findAll: async () => [] },
},
};
service.isB2bPackingQuantityCheckEnabled = async () => false;
const result = await service.getB2bPackingSnapshot({ warehouseId: 7, orderIds: [ 99 ] });
assert.strictEqual(result.items[0].item_name, '商品A(快照)');
assert.strictEqual(result.items[0].sku_property, '蓝色/M');
assert.strictEqual(result.items[0].stock_unit, '个');
assert.strictEqual(result.items[0].store_id, 5);
assert.deepStrictEqual(result.items[0].stock.barcodes, []);
});
it('outputs empty pick locations when the order has no allocation rows', async () => {
const transaction = { commit: async () => {}, rollback: async () => {} };
const service = Object.create(OrderB2bService.prototype);