From 388809fc9fac3f894503ebf2fed246fbdaaf2acc Mon Sep 17 00:00:00 2001 From: liufumingren Date: Sat, 19 Sep 2026 15:09:31 +0800 Subject: [PATCH] =?UTF-8?q?feat(workbench):=20getWorkbenchInfo=20=E8=A1=A5?= =?UTF-8?q?=E5=85=A8=E5=BD=93=E5=89=8D=E6=89=93=E5=8C=85=E4=BB=BB=E5=8A=A1?= =?UTF-8?q?=E5=95=86=E5=93=81=E4=BF=A1=E6=81=AF=EF=BC=88=E6=95=A3=E5=8D=95?= =?UTF-8?q?=E6=98=8E=E7=BB=86/=E5=9B=A2=E8=B4=AD=E6=B3=A2=E6=AC=A1SKU?= =?UTF-8?q?=E8=81=9A=E5=90=88/=E5=85=8D=E9=AA=8C=E5=AD=97=E6=AE=B5?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 抽取 _fetchOrderItemsDetail 公共方法(queryOrder 复用),散单任务 items 返回单笔商品明细(含条码/图片/包装要求/need_recheck 免验字段) - 新增 _fetchWaveItemsSummary(15s 短缓存),团购任务 items 返回波次商品 SKU 聚合汇总(is_wave_summary=true),500 单波次本地实测聚合 1000 件与 items_total 一致 - current_orders 补 item_quantity/sku_count/waybill_code/order_type/store_id/items_count/items_total - 文档同步 system.json 0.3.137 与 changes 三条变更记录 --- AI_METHOD_ROUTING.md | 10 +- app/service/systems/workbench.js | 344 ++++++++++++++++++++++++------- methods/changes/system.json | 45 ++++ methods/system.json | 164 ++++++++++++++- 4 files changed, 481 insertions(+), 82 deletions(-) diff --git a/AI_METHOD_ROUTING.md b/AI_METHOD_ROUTING.md index ed9fbfb..21bfb0a 100644 --- a/AI_METHOD_ROUTING.md +++ b/AI_METHOD_ROUTING.md @@ -186,9 +186,9 @@ rg "class .*Service|module.exports" app/service/qimenMethods - 成员副表:`wms_workbench_member`(工作台成员/用户登录,user_id 可空兼容非系统账号用户、user_name 名称快照、软删除);`workbench.bindMember` 免登录免鉴权(入参 userId 可空 + userName 姓名必填 + 工作台 token)新增成员行;`workbench.removeMember` 免登录免鉴权(入参行 ids + 工作台 token)按 token 解析工作台后仅软删除归属该工作台的成员行 - 401/403 口径:/system 网关不支持方法内设置 HTTP 状态码,按现有惯例返回 `flag=failure、code=XXX` 业务失败(与 stock/warehouse.js 同款);公共 token 校验方法 `resolveWorkbenchContext(token)`(app/service/systems/workbench.js):无 token 统一返回 code=401(消息「工作台 token 不能为空」,2026-09-06 由 400 调整)、token 无效/工作台不存在(含软删除)返回 403(保持原口径),解析成功后写入 ctx.workbenchToken/ctx.workbenchId/ctx.workbenchWarehouseId 供后续方法使用(仓库限定,禁止跨仓库);`workbench.getWorkbenchInfo`/`workbench.bindMember`/`workbench.removeMember` 均统一走该校验(无 token 返回 401,bindMember/removeMember token 优先校验) - 打包/称重三接口(2026-09-06 新增):`workbench.packOrder`(打包上报,入参 token/delivery_order_code/wave_no/status/pack_time/wave_total_orders/items_count/items_total/users,响应 task_id/order_id/delivery_order_code/wave_no/isSandan/pack_mode/status,团购附 batch)、`workbench.finishPack`(打包完成,入参 token,响应 workbench_id/finished/task_id/order_id/end_time,无未结束任务 finished=false)、`workbench.sendWeight`(称重上报,入参 token/barcode/weight(单位克),散单响应 barcode/waybill_code/order_id/weighing_weight/items_weight/mode=single,团购波次响应另附 wave_id/wave_no/total_weight/order_count/mode=wave)均免登录/免权限/免鉴权,靠工作台 token 自校验;仓库与工作台均由服务端从 token 解析注入,body 传入 warehouse_id/workbench_id 一律忽略(禁止前端传值);三接口保留系统日志(systemInit 未声明免日志) -- 条码查单接口(2026-09-06 新增):`workbench.queryOrder`(条码查订单,入参 token/barcode,响应 barcode/waybill_code/isSandan/store_remark/express/order/items/source_table,散单 order 附 intercept_flag/pack_flag 0/1 标志、团购附 batch 波次总量信息)免登录/免权限/免鉴权,靠工作台 token 自校验;仓库与工作台均由服务端从 token 解析注入,body 传入 warehouse_id/workbench_id 一律忽略(禁止前端传值);只读查询不涉及缓存失效;保留系统日志(systemInit 未声明免日志) -- 接口文档:`methods/system.json` 分组「工作台模块」(module=workbench)与「基础模块」(module=index),变更记录见 `methods/changes/system.json` 版本 `2026.09.03-workbench-login-code-token`、`2026.09.03-workbench-member-remove`、`2026.09.03-workbench-member-bind`、`2026.09.06-workbench-getWorkbenchInfo-members`、`2026.09.06-workbench-getWorkbenchInfo-current-packing`、`2026.09.06-workbench-getWorkbenchInfo-wave-items-total`、`2026.09.06-workbench-pack-order-finish-pack-send-weight`、`2026.09.06-workbench-queryOrder` -- 当前打包信息:`workbench.getWorkbenchInfo` 响应 data 另含 `current_wave`(当前正在打包的团购波次,来自 wms_pack_task 最新一条 pack_mode=2 未结束任务,无则为空对象;含 order_count 波次订单数与 items_total 波次商品总件数,均按 current+dispatch 分表实时统计、15s 短缓存兜底)与 `current_orders`(未结束打包任务对应订单数组,逐单补发货单号,无则为空数组);打包信息随 `workbench:token:{token}` 缓存(TTL 300s)一并缓存,packOrder/finishPack 状态变更后主动失效缓存,查询异常降级为空对象/空数组 +- 条码查单接口(2026-09-06 新增):`workbench.queryOrder`(条码查订单,入参 token/barcode,响应 barcode/waybill_code/isSandan/store_remark/express/order/items/source_table,散单 order 附 intercept_flag/pack_flag 0/1 标志、团购附 batch 波次总量信息;items 逐项合并 stock 详情含 need_recheck 是否需要复核(Y=需要 N=不需要(免验),2026-09-19 补充))免登录/免权限/免鉴权,靠工作台 token 自校验;仓库与工作台均由服务端从 token 解析注入,body 传入 warehouse_id/workbench_id 一律忽略(禁止前端传值);只读查询不涉及缓存失效;保留系统日志(systemInit 未声明免日志) +- 接口文档:`methods/system.json` 分组「工作台模块」(module=workbench)与「基础模块」(module=index),变更记录见 `methods/changes/system.json` 版本 `2026.09.03-workbench-login-code-token`、`2026.09.03-workbench-member-remove`、`2026.09.03-workbench-member-bind`、`2026.09.06-workbench-getWorkbenchInfo-members`、`2026.09.06-workbench-getWorkbenchInfo-current-packing`、`2026.09.06-workbench-getWorkbenchInfo-wave-items-total`、`2026.09.06-workbench-pack-order-finish-pack-send-weight`、`2026.09.06-workbench-queryOrder`、`2026.09.19-workbench-getWorkbenchInfo-order-items`、`2026.09.19-workbench-order-items-need-recheck`、`2026.09.19-workbench-getWorkbenchInfo-wave-items-summary` +- 当前打包信息:`workbench.getWorkbenchInfo` 响应 data 另含 `current_wave`(当前正在打包的团购波次,来自 wms_pack_task 最新一条 pack_mode=2 未结束任务,无则为空对象;含 order_count 波次订单数与 items_total 波次商品总件数,均按 current+dispatch 分表实时统计、15s 短缓存兜底)与 `current_orders`(未结束打包任务对应订单数组,逐单按 current→dispatch 分表补发货单号/order_type/store_id/items_count/items_total,另附任务表 item_quantity/sku_count/waybill_code,散单任务(pack_mode=1)附 items 商品明细数组(复用 _fetchOrderItemsDetail 公共方法,与 workbench.queryOrder 的 items 同源,含条码/图片/包装要求/need_recheck 是否需要复核),团购任务(pack_mode=2)items 为波次商品 SKU 聚合汇总(_fetchWaveItemsSummary,波次内全部未拦截订单按 SKU 聚合计划数量并合并 stock 详情,15s 短缓存兜底,元素另附 is_wave_summary=true),无则为空数组);打包信息随 `workbench:token:{token}` 缓存(TTL 300s)一并缓存,packOrder/finishPack 状态变更后主动失效缓存,查询异常降级为空对象/空数组(单笔商品明细异常仅 items 降级为空数组) - 迁移:`database/migrations/20260903100000-add-login-code-token-to-wms-workbench.js`(幂等 up/down,已在开发库执行;生产库待发布时按标准流程执行) ## 5.4 index.queryUserByToken(ye4s token 查询用户)能力速查 @@ -723,8 +723,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - closeFinishedWaves, normalizeConfirmIntervalMs, readEmptyConfirmState, writeEmptyConfirmState - app/service/systems/waybill.js (5) - toOrder, list, detail, export, buildWaybillExportFile -- app/service/systems/workbench.js (62) - - list, detail, create, update, delete, bindCamera, business, _countWaveOrders, _countWaveOrdersCached, SUM, _sumWaveItemsTotal, _sumWaveItemsTotalCached, _getWaveOrderIds, Set, _buildPackChangeSummary, _writePackOperationLog, _updateOrderPackStatus, _packOrder, resolvePackTaskEndTime, _finishPack, _resetPackOsd, _sendWeight, _writeWeighOpLog, _queryOrder, getWorkbenchBindClientCacheKey, getWorkbenchBindCodeCacheKey, getWorkbenchTokenCacheKey, generateRandomChars, generateWorkbenchToken, generateWorkbenchLoginCode, normalizeWorkbenchBindCode, generateUniqueWorkbenchLoginCode, createUniqueWorkbenchClientCode, createUniqueWorkbenchBindCode, buildWorkbenchBindState, getWorkbenchBindRemainingSeconds, setWorkbenchBindState, createWorkbenchBindSession, refreshWorkbenchBindCode, formatWorkbenchBindData, waitForWorkbenchBindComplete, getWorkbenchBindCode, formatWorkbenchTokenInfo, listWorkbenchMembers, listCurrentPackTasks, buildCurrentPackingInfo, invalidateWorkbenchTokenCacheByWorkbenchId, buildWorkbenchTokenInfo, bindWorkbench, getWorkbenchInfoByToken, loginWorkbenchByCode, resetLoginCode, clearExpiredWorkbenchTokens, resolveWorkbenchContext, resolveWorkbenchByToken, packOrderByToken, finishPackByToken, sendWeightByToken, queryOrderByToken, normalizeWorkbenchMemberIds, removeWorkbenchMember, bindWorkbenchMember +- app/service/systems/workbench.js (65) + - list, detail, create, update, delete, bindCamera, business, _countWaveOrders, _countWaveOrdersCached, SUM, _sumWaveItemsTotal, _sumWaveItemsTotalCached, _getWaveOrderIds, Set, _buildPackChangeSummary, _writePackOperationLog, _updateOrderPackStatus, _packOrder, resolvePackTaskEndTime, _finishPack, _resetPackOsd, _sendWeight, _writeWeighOpLog, _aggregateWaveItems, _fetchWaveItemsSummary, _fetchOrderItemsDetail, _queryOrder, getWorkbenchBindClientCacheKey, getWorkbenchBindCodeCacheKey, getWorkbenchTokenCacheKey, generateRandomChars, generateWorkbenchToken, generateWorkbenchLoginCode, normalizeWorkbenchBindCode, generateUniqueWorkbenchLoginCode, createUniqueWorkbenchClientCode, createUniqueWorkbenchBindCode, buildWorkbenchBindState, getWorkbenchBindRemainingSeconds, setWorkbenchBindState, createWorkbenchBindSession, refreshWorkbenchBindCode, formatWorkbenchBindData, waitForWorkbenchBindComplete, getWorkbenchBindCode, formatWorkbenchTokenInfo, listWorkbenchMembers, listCurrentPackTasks, buildCurrentPackingInfo, invalidateWorkbenchTokenCacheByWorkbenchId, buildWorkbenchTokenInfo, bindWorkbench, getWorkbenchInfoByToken, loginWorkbenchByCode, resetLoginCode, clearExpiredWorkbenchTokens, resolveWorkbenchContext, resolveWorkbenchByToken, packOrderByToken, finishPackByToken, sendWeightByToken, queryOrderByToken, normalizeWorkbenchMemberIds, removeWorkbenchMember, bindWorkbenchMember - app/service/warehouse.js (7) - resolveWarehouseMethod, getWarehouseMethodService, dispatchWarehouseMethod, validateWarehouseParams, parseJsonBody, normalizeSignFields, processRequest - app/service/warehouseMethods/inbox.js (2) diff --git a/app/service/systems/workbench.js b/app/service/systems/workbench.js index 616f766..65415b5 100644 --- a/app/service/systems/workbench.js +++ b/app/service/systems/workbench.js @@ -13,6 +13,10 @@ const WAVE_ORDER_COUNT_CACHE_TTL_SECONDS = 15; const WAVE_ITEMS_TOTAL_CACHE_KEY_PREFIX = 'cache:workbench:wave_items_total'; /** @type {number} 工作台波次商品总件数缓存 TTL(秒),TTL 内分表 SUM 只执行一次 */ const WAVE_ITEMS_TOTAL_CACHE_TTL_SECONDS = 15; +/** @type {string} 工作台波次商品 SKU 聚合缓存 key 前缀(最终 key:{前缀}:{warehouseId}:{waveId}) */ +const WAVE_ITEMS_SUMMARY_CACHE_KEY_PREFIX = 'cache:workbench:wave_items_summary'; +/** @type {number} 工作台波次商品 SKU 聚合缓存 TTL(秒),TTL 内分表聚合只执行一次 */ +const WAVE_ITEMS_SUMMARY_CACHE_TTL_SECONDS = 15; /** @type {string} 工作台绑定会话缓存 key 前缀(client_code 维度,最终 key:{前缀}{clientCode}) */ const WORKBENCH_BIND_CLIENT_CACHE_PREFIX = 'workbench:bind:client:'; @@ -1581,6 +1585,231 @@ class WorkbenchService extends Service { } } + /** + * 实时聚合波次商品明细(无缓存,供 _fetchWaveItemsSummary 调用)。 + * 口径:波次下全部未拦截订单(current + dispatch 分表)的商品明细行按 SKU 聚合计划数量 + * (stock_id 优先作聚合键,缺省按 item_code+item_name),并合并 stock 详情(条码/图片/包装要求/是否需要复核); + * 任一环节异常均降级返回空数组,不抛错。 + * @param {number} warehouseId 仓库ID + * @param {number} waveId 波次ID + * @return {Promise>} 波次商品聚合数组(结构与散单 items 一致,另附 is_wave_summary=true) + */ + async _aggregateWaveItems(warehouseId, waveId) { + const { ctx } = this; + try { + const orderIds = await this._getWaveOrderIds(warehouseId, waveId, true); + if (!orderIds || orderIds.length === 0) return []; + + const orderItemsFactory = ctx.model.OrderItemsFactory; + const itemTables = [ + { getModel: () => orderItemsFactory.getCurrentModel(warehouseId) }, + { getModel: () => orderItemsFactory.getDispatchModel(warehouseId) }, + ]; + + const itemRows = []; + for (const entry of itemTables) { + try { + const model = await entry.getModel(); + if (!model) continue; + const rows = await model.findAll({ + where: { order_id: { [ctx.app.Sequelize.Op.in]: orderIds } }, + attributes: [ + 'id', 'order_id', 'item_id', 'item_code', 'item_name', + 'plan_qty', 'actual_price', 'stock_id', 'order_line_no', + 'inventory_type', + ], + raw: true, + }); + itemRows.push(...rows); + } catch (_err) { continue; } + } + + if (itemRows.length === 0) return []; + + // 按 SKU 聚合(stock_id 优先作聚合键,缺省按 item_code+item_name) + const aggregateMap = new Map(); + for (const row of itemRows) { + const stockId = Number(row.stock_id || 0); + const itemCode = String(row.item_code || '').trim(); + const itemName = String(row.item_name || '').trim(); + const key = stockId > 0 ? `stock:${stockId}` : `code:${itemCode}||${itemName}`; + if (!key) continue; + const planQty = Number(row.plan_qty || 0); + if (!aggregateMap.has(key)) { + aggregateMap.set(key, { + stock_id: stockId, + item_id: row.item_id, + item_code: itemCode, + item_name: itemName, + plan_qty: 0, + inventory_type: row.inventory_type || '', + }); + } + aggregateMap.get(key).plan_qty += planQty; + } + + const aggregates = Array.from(aggregateMap.values()); + const stockIds = [ ...new Set(aggregates.map(a => a.stock_id).filter(id => id > 0)) ]; + const stockMap = new Map(); + if (stockIds.length > 0) { + try { + const stockDetails = await ctx.service.systems.stockWarehouse.getStockDetails(stockIds, { warehouseId }); + for (const detail of stockDetails) { + stockMap.set(Number(detail.id), detail); + } + } catch (stockErr) { + ctx.logger.warn('[Workbench._aggregateWaveItems] 查询 stock 详情失败: %s', stockErr.message); + } + } + + return aggregates.map(agg => { + const stock = stockMap.get(agg.stock_id) || {}; + return { + id: 0, + order_id: 0, + item_id: agg.item_id, + item_code: agg.item_code || stock.item_code || '', + item_name: agg.item_name || stock.item_name || '', + plan_qty: agg.plan_qty, + actual_price: null, + stock_id: agg.stock_id, + order_line_no: '', + inventory_type: agg.inventory_type || '', + sku_property: stock.sku_property || '', + stock_unit: stock.stock_unit || '', + barcodes: stock.barcodes || [], + image_url: stock.image_url || [], + packing_requirements: String(stock.packing_requirements || '').trim(), + need_recheck: String(stock.need_recheck || 'Y').trim(), + is_wave_summary: true, + }; + }); + } catch (err) { + ctx.logger.warn('[Workbench._aggregateWaveItems] 聚合波次商品失败 waveId=%d: %s', waveId, err.message); + return []; + } + } + + /** + * 团购波次商品 SKU 聚合汇总(带 Redis 短 TTL 缓存兜底,供 getWorkbenchInfo 团购任务 items 返回)。 + * 波次商品明细量大(动辄数百单),逐单返回明细开销高且无必要, + * 因此按 (warehouseId, waveId) 维度做 15s 短缓存(与 _countWaveOrdersCached/_sumWaveItemsTotalCached 同款): + * TTL 内重复查询直接命中缓存,缓存不可用或读取失败时降级为实时聚合。 + * @param {number} warehouseId 仓库ID + * @param {number} waveId 波次ID + * @return {Promise>} 波次商品汇总数组(异常降级为空数组) + */ + async _fetchWaveItemsSummary(warehouseId, waveId) { + const { ctx, app } = this; + const cacheKey = `${WAVE_ITEMS_SUMMARY_CACHE_KEY_PREFIX}:${warehouseId}:${waveId}`; + + if (app && typeof app.getCacheAsync === 'function') { + try { + const cached = await app.getCacheAsync(cacheKey); + if (Array.isArray(cached)) { + return cached; + } + } catch (cacheReadErr) { + ctx.logger.warn('[Workbench._fetchWaveItemsSummary] 读取缓存失败,降级为实时聚合: %s', cacheReadErr.message); + } + } + + const items = await this._aggregateWaveItems(warehouseId, waveId); + + if (app && typeof app.setCacheAsync === 'function') { + try { + await app.setCacheAsync(cacheKey, items, WAVE_ITEMS_SUMMARY_CACHE_TTL_SECONDS); + } catch (cacheWriteErr) { + ctx.logger.warn('[Workbench._fetchWaveItemsSummary] 写入缓存失败,不影响本次返回: %s', cacheWriteErr.message); + } + } + + return items; + } + + /** + * 查询订单商品明细并合并 stock 详情(供 _queryOrder 与 buildCurrentPackingInfo 复用)。 + * - 商品明细来自 OrderItemsFactory 分表(sourceTable=dispatch 查配送明细表,其余查 current); + * - stock 详情(条码/图片/包装要求等)经 stockWarehouse.getStockDetails 批量查询(自带缓存); + * - 任一环节异常均降级返回空数组,不抛错。 + * @param {number} orderId 订单ID + * @param {number} warehouseId 仓库ID + * @param {string} [sourceTable] 订单所在分表(dispatch|current),决定明细分表选择 + * @return {Promise>} 商品明细数组(含 item_code/item_name/plan_qty/barcodes/image_url 等) + */ + async _fetchOrderItemsDetail(orderId, warehouseId, sourceTable) { + const { ctx } = this; + let items = []; + try { + const getItemsModel = sourceTable === 'dispatch' + ? () => ctx.model.OrderItemsFactory.getDispatchModel(warehouseId) + : () => ctx.model.OrderItemsFactory.getCurrentModel(warehouseId); + const itemsModel = await getItemsModel(); + if (itemsModel) { + const orderItems = await itemsModel.findAll({ + where: { order_id: orderId }, + attributes: [ + 'id', 'order_id', 'item_id', 'item_code', 'item_name', + 'plan_qty', 'actual_price', 'stock_id', 'order_line_no', + 'inventory_type', 'item_snapshot', + ], + order: [[ 'id', 'ASC' ]], + raw: true, + }); + + if (orderItems.length > 0) { + // 收集所有 stock_id,批量查询 stock 详情(带缓存) + const stockIds = [ ...new Set( + orderItems.map(item => Number(item.stock_id)).filter(id => id > 0) + ) ]; + + /** @type {Map} */ + const stockMap = new Map(); + if (stockIds.length > 0) { + try { + const stockDetails = await ctx.service.systems.stockWarehouse.getStockDetails( + stockIds, + { warehouseId } + ); + for (const detail of stockDetails) { + stockMap.set(Number(detail.id), detail); + } + } catch (stockErr) { + ctx.logger.warn('[Workbench._fetchOrderItemsDetail] 查询 stock 详情失败: %s', stockErr.message); + } + } + + // 组装 items,合并 stock 信息 + items = orderItems.map(item => { + const stockId = Number(item.stock_id); + const stock = stockMap.get(stockId) || {}; + return { + id: item.id, + order_id: item.order_id, + item_id: item.item_id, + item_code: item.item_code || stock.item_code || '', + item_name: item.item_name || stock.item_name || '', + plan_qty: item.plan_qty, + actual_price: item.actual_price, + stock_id: stockId, + order_line_no: item.order_line_no || '', + inventory_type: item.inventory_type || '', + sku_property: stock.sku_property || '', + stock_unit: stock.stock_unit || '', + barcodes: stock.barcodes || [], + image_url: stock.image_url || '', + packing_requirements: String(stock.packing_requirements || '').trim(), + need_recheck: String(stock.need_recheck || 'Y').trim(), + }; + }); + } + } + } catch (itemsErr) { + ctx.logger.warn('[Workbench._fetchOrderItemsDetail] 查询订单商品失败 orderId=%d: %s', orderId, itemsErr.message); + } + return items; + } + /** * 条码查订单:条码 → wms_order_express → 待处理/配送订单详情 * 散单(isSandan=1)时在响应 order 对象中额外返回 intercept_flag / pack_flag 两个 0/1 标志: @@ -1698,74 +1927,8 @@ class WorkbenchService extends Service { } } - // 步骤4:查询订单商品明细 + 关联 stock 详情(带缓存) - let items = []; - try { - const getItemsModel = sourceTable === 'dispatch' - ? () => ctx.model.OrderItemsFactory.getDispatchModel(warehouseId) - : () => ctx.model.OrderItemsFactory.getCurrentModel(warehouseId); - const itemsModel = await getItemsModel(); - if (itemsModel) { - const orderItems = await itemsModel.findAll({ - where: { order_id: orderId }, - attributes: [ - 'id', 'order_id', 'item_id', 'item_code', 'item_name', - 'plan_qty', 'actual_price', 'stock_id', 'order_line_no', - 'inventory_type', 'item_snapshot', - ], - order: [[ 'id', 'ASC' ]], - raw: true, - }); - - if (orderItems.length > 0) { - // 收集所有 stock_id,批量查询 stock 详情(带缓存) - const stockIds = [ ...new Set( - orderItems.map(item => Number(item.stock_id)).filter(id => id > 0) - ) ]; - - /** @type {Map} */ - const stockMap = new Map(); - if (stockIds.length > 0) { - try { - const stockDetails = await ctx.service.systems.stockWarehouse.getStockDetails( - stockIds, - { warehouseId } - ); - for (const detail of stockDetails) { - stockMap.set(Number(detail.id), detail); - } - } catch (stockErr) { - ctx.logger.warn('[Workbench._queryOrder] 查询 stock 详情失败: %s', stockErr.message); - } - } - - // 组装 items,合并 stock 信息 - items = orderItems.map(item => { - const stockId = Number(item.stock_id); - const stock = stockMap.get(stockId) || {}; - return { - id: item.id, - order_id: item.order_id, - item_id: item.item_id, - item_code: item.item_code || stock.item_code || '', - item_name: item.item_name || stock.item_name || '', - plan_qty: item.plan_qty, - actual_price: item.actual_price, - stock_id: stockId, - order_line_no: item.order_line_no || '', - inventory_type: item.inventory_type || '', - sku_property: stock.sku_property || '', - stock_unit: stock.stock_unit || '', - barcodes: stock.barcodes || [], - image_url: stock.image_url || '', - packing_requirements: String(stock.packing_requirements || '').trim(), - }; - }); - } - } - } catch (itemsErr) { - ctx.logger.warn('[Workbench._queryOrder] 查询订单商品失败: %s', itemsErr.message); - } + // 步骤4:查询订单商品明细 + 关联 stock 详情(带缓存,公共方法 _fetchOrderItemsDetail) + const items = await this._fetchOrderItemsDetail(orderId, warehouseId, sourceTable); // 步骤5:查询货主备注(从合约表 store_warehouse.store_remask) let storeRemark = ''; @@ -2276,8 +2439,11 @@ class WorkbenchService extends Service { /** * 组装工作台当前正在打包的波次与订单信息(供 workbench.getWorkbenchInfo 返回)。 * - current_wave:最新一条团购(pack_mode=2)未结束任务对应的波次信息,无则为空对象; - * - current_orders:全部未结束打包任务列表(含发货单号、波次号、任务状态等),无则为空数组。 - * 任一环节异常均降级为空对象/空数组,不影响主信息返回。 + * - current_orders:全部未结束打包任务列表(含发货单号、波次号、任务状态、商品件数/SKU 数等): + * 散单任务(pack_mode=1)items 为单笔订单商品明细(含条码/图片/包装要求/是否需要复核); + * 团购任务(pack_mode=2)items 为波次商品 SKU 聚合汇总(波次内全部未拦截订单按 SKU 聚合计划数量,15s 短缓存兜底, + * 元素另附 is_wave_summary=true),供工作台退出/刷新后恢复任务上下文。 + * 任一环节异常均降级为空对象/空数组/空明细,不影响主信息返回。 * @param {number} workbenchId 工作台 ID * @param {number} warehouseId 仓库 ID * @return {Promise<{current_wave: Object, current_orders: Array}>} 当前打包中波次与订单 @@ -2302,24 +2468,49 @@ class WorkbenchService extends Service { let currentWave = {}; const currentOrders = []; for (const task of tasks) { - // 按订单ID补齐发货单号(current → dispatch 分表遍历,与 _packOrder 口径一致) + // 按订单ID补齐发货单号与订单关键字段(current → dispatch 分表遍历,与 _packOrder 口径一致) let deliveryOrderCode = ''; + let orderRow = null; + let sourceTable = ''; for (const entry of tableOrders) { try { const model = await entry.getModel(); if (!model) continue; const row = await model.findOne({ where: { id: Number(task.order_id || 0), warehouse_id: warehouseId }, - attributes: [ 'delivery_order_code' ], + attributes: [ 'delivery_order_code', 'order_type', 'store_id', 'items_count', 'items_total' ], raw: true, }); if (row) { deliveryOrderCode = row.delivery_order_code || ''; + orderRow = row; + sourceTable = entry.label; break; } } catch (_err) { continue; } } + const isGroup = Number(task.pack_mode) === 2; + + // 散单任务补充单笔订单商品明细;团购任务补充波次商品 SKU 聚合汇总(15s 短缓存兜底), + // 均供工作台退出/刷新后恢复任务上下文(异常降级为空数组) + let items = []; + if (!isGroup && Number(task.order_id || 0) > 0 && sourceTable) { + try { + items = await this._fetchOrderItemsDetail(Number(task.order_id), warehouseId, sourceTable); + } catch (itemsErr) { + ctx.logger.warn('[Workbench.buildCurrentPackingInfo] 查询散单商品明细失败 orderId=%d: %s', + Number(task.order_id), itemsErr.message); + } + } else if (isGroup && Number(task.wave_id || 0) > 0) { + try { + items = await this._fetchWaveItemsSummary(warehouseId, Number(task.wave_id)); + } catch (itemsErr) { + ctx.logger.warn('[Workbench.buildCurrentPackingInfo] 查询团购波次商品汇总失败 waveId=%d: %s', + Number(task.wave_id), itemsErr.message); + } + } + currentOrders.push({ task_id: task.id, order_id: task.order_id, @@ -2329,12 +2520,19 @@ class WorkbenchService extends Service { pack_mode: Number(task.pack_mode || 1), status: Number(task.status || 0), pack_quantity: Number(task.pack_quantity || 0), + item_quantity: Number(task.item_quantity || 0), + sku_count: Number(task.sku_count || 0), + waybill_code: task.waybill_code || '', + order_type: (orderRow && orderRow.order_type) || '', + store_id: Number((orderRow && orderRow.store_id) || 0), + items_count: Number((orderRow && orderRow.items_count) || 0), + items_total: Number((orderRow && orderRow.items_total) || 0), + items, operator_text: task.operator_text || '', start_time: task.start_time, }); // 团购任务(pack_mode=2)作为当前波次,只取最新一条未结束任务 - const isGroup = Number(task.pack_mode) === 2; if (isGroup && !currentWave.task_id && Number(task.wave_id) > 0) { // 订单数与商品总件数并行统计(各自带 15s 短 TTL 缓存,缓存命中后几乎零开销) const [ orderCount, itemsTotal ] = await Promise.all([ diff --git a/methods/changes/system.json b/methods/changes/system.json index 31c48ab..07599f2 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,49 @@ [ + { + "version": "2026.09.19-workbench-getWorkbenchInfo-wave-items-summary", + "date": "2026-09-19", + "type": "enhance", + "summary": "workbench.getWorkbenchInfo 团购任务(pack_mode=2)current_orders items 由空数组改为波次商品 SKU 聚合汇总,彻底解决工作台退出/刷新后团购打包任务无商品信息的问题:新增 _aggregateWaveItems(波次内全部未拦截订单(current+dispatch 分表)商品明细按 SKU 聚合计划数量并合并 stock 详情,聚合行另附 is_wave_summary=true)与 _fetchWaveItemsSummary(按 warehouseId+waveId 维度 15s 短缓存兜底,与 order_count/items_total 同款缓存模式),buildCurrentPackingInfo 团购任务分支调用;散单任务 items 口径不变。", + "methods": [ + "workbench.getWorkbenchInfo" + ], + "notes": [ + "代码:app/service/systems/workbench.js 新增常量 WAVE_ITEMS_SUMMARY_CACHE_KEY_PREFIX/WAVE_ITEMS_SUMMARY_CACHE_TTL_SECONDS(15s);_aggregateWaveItems 聚合键 stock_id 优先、缺省按 item_code+item_name,stock 详情走 stockWarehouse.getStockDetails 通用缓存链路,异常降级空数组;buildCurrentPackingInfo 团购任务(wave_id>0)调用 _fetchWaveItemsSummary 填 items", + "结构:聚合行与散单 items 结构同源(id/order_id 置 0、order_line_no 空串、actual_price null、plan_qty 为波次内该 SKU 合计),另附 is_wave_summary=true 供前端区分单笔明细与波次汇总", + "性能:15s 短缓存保证 TTL 内重复查询零开销;缓存未命中时波次订单 ID 查询走 wave_id 索引、items 按 order_id IN 查询走索引,500 单规模波次一次聚合可接受;packOrder/finishPack 后 token 缓存失效,波次聚合缓存在 TTL 内可能与最新波次状态有最多 15s 滞后(与 order_count/items_total 同口径)", + "methods/system.json:workbench.getWorkbenchInfo description 与 current_orders[].items/items[].id/items[].order_id/items[].plan_qty 描述更新为双口径,response 新增 current_orders[].items[].is_wave_summary 条目;版本 0.3.136 -> 0.3.137(docMeta.version),updatedAt 保持 2026-09-19" + ] + }, + { + "version": "2026.09.19-workbench-order-items-need-recheck", + "date": "2026-09-19", + "type": "updated", + "summary": "workbench.queryOrder 与 workbench.getWorkbenchInfo 响应商品明细 items 新增 need_recheck 字段(Y=需要复核,N=不需要复核(免验),缺省 Y):组装链路 _fetchOrderItemsDetail 从 stock 详情(getStockDetails 通用缓存链路,其 attributes 已含 need_recheck)透出,补齐工作台打包端商品列表缺少免验标识的问题。", + "methods": [ + "workbench.queryOrder", + "workbench.getWorkbenchInfo" + ], + "notes": [ + "代码:app/service/systems/workbench.js _fetchOrderItemsDetail items 组装新增 need_recheck: String(stock.need_recheck || 'Y').trim()(与 order.recheckOrder.scanOrder/scanTask 同口径,getStockDetails 旧缓存无该字段时兜底 Y)", + "workbench.queryOrder 与 workbench.getWorkbenchInfo(current_orders[].items)共用 _fetchOrderItemsDetail,两接口 items 同步生效", + "methods/system.json:workbench.queryOrder description 补充 need_recheck 说明,response 新增 items[].need_recheck 条目;workbench.getWorkbenchInfo description 补充「是否需要复核 need_recheck」,response 新增 current_orders[].items[].need_recheck 条目,并将 current_orders[].items[].image_url 类型由 string 修正为 array(实际返回数组);版本 0.3.135 -> 0.3.136(docMeta.version),updatedAt 保持 2026-09-19" + ] + }, + { + "version": "2026.09.19-workbench-getWorkbenchInfo-order-items", + "date": "2026-09-19", + "type": "enhance", + "summary": "enhance: workbench.getWorkbenchInfo 响应 data.current_orders 补全任务上下文字段,解决工作台退出/刷新后无法恢复任务信息的问题:散单任务(pack_mode=1)新增 items 商品明细数组(wms_order_items 分表按 order_id 查询并合并 stock 详情,含 item_code/item_name/plan_qty/barcodes/image_url/packing_requirements 等,与 workbench.queryOrder 返回结构同源),团购任务(pack_mode=2)波次商品明细量大,items 置空数组、以 current_wave 汇总展示;同时每项新增 wms_pack_task 已有字段 item_quantity/sku_count/waybill_code 与订单分表字段 order_type/store_id/items_count/items_total。", + "methods": [ + "workbench.getWorkbenchInfo" + ], + "notes": [ + "实现:app/service/systems/workbench.js 从 _queryOrder 步骤4 抽取公共方法 _fetchOrderItemsDetail(orderId, warehouseId, sourceTable)(sourceTable=dispatch 查配送明细分表、其余查 current;stock 详情走 stockWarehouse.getStockDetails 自带缓存;异常降级空数组),_queryOrder 改为复用(响应结构不变);buildCurrentPackingInfo 任务遍历时记录订单所在分表 sourceTable 并多取 order_type/store_id/items_count/items_total 字段,散单任务调用 _fetchOrderItemsDetail 补 items,团购任务 items 置空数组", + "口径:items 仅对 pack_mode=1 散单任务查询(团购波次逐单聚合开销大且前端以 current_wave 汇总展示);单笔商品明细查询异常仅该项 items 降级为空数组,不影响主信息与其余字段", + "性能:buildCurrentPackingInfo 仅在 token 缓存(workbench:token:{token},TTL 300s)未命中或打包状态变更失效后执行,未结束任务通常单条,items 按 order_id 走索引查询,无新增高频开销", + "methods/system.json:workbench.getWorkbenchInfo description 补充散单 items/团购空数组与新增字段说明,response 新增 current_orders[].item_quantity/sku_count/waybill_code/order_type/store_id/items_count/items_total 与 current_orders[].items 及 items[] 下 16 个子字段条目(沿用 current_orders[].xxx 嵌套命名惯例);版本 0.3.134 -> 0.3.135(docMeta.version),updatedAt 2026-09-17 -> 2026-09-19" + ] + }, { "version": "2026.09.17-inbox-group-template-reply-switch", "date": "2026-09-17", diff --git a/methods/system.json b/methods/system.json index b0a4db3..bec64b5 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.134", - "updatedAt": "2026-09-17", + "version": "0.3.137", + "updatedAt": "2026-09-19", "headers": [ { "name": "platform", @@ -33893,7 +33893,7 @@ }, { "method": "workbench.getWorkbenchInfo", - "description": "使用 token 获取工作台信息(免登录、免鉴权):先查缓存 workbench:token:{token}(TTL 300s,缓存值已包含成员列表 members 与当前打包信息 current_wave/current_orders),未命中则按 token 查库并回填缓存后返回工作台信息(不含 token/login_code;工作台条码 barcode 字段已下线);响应 data 含 members 成员数组(wms_workbench_member 未软删除记录,按 id ASC 排序)、current_wave 当前正在打包的团购波次(wms_pack_task 中 pack_mode=2 且 wave_id>0 的最新一条未结束任务组装,含波次订单数 order_count 与商品总件数 items_total,无团购任务时为空对象)与 current_orders 当前正在打包的订单数组(未结束任务(status<2)对应订单,逐单补发货单号,无进行中任务时为空数组);绑定/移除成员、packOrder/finishPack 打包状态变更后 token 缓存立即失效,下一次调用即返回最新成员与打包信息;打包信息查询异常时降级(current_wave 空对象、current_orders 空数组),不影响主信息与 members;token 缺失返回失败(flag=failure、code=401,消息「工作台 token 不能为空」)、token 不存在或无对应工作台返回失败(flag=failure、code=403)", + "description": "使用 token 获取工作台信息(免登录、免鉴权):先查缓存 workbench:token:{token}(TTL 300s,缓存值已包含成员列表 members 与当前打包信息 current_wave/current_orders),未命中则按 token 查库并回填缓存后返回工作台信息(不含 token/login_code;工作台条码 barcode 字段已下线);响应 data 含 members 成员数组(wms_workbench_member 未软删除记录,按 id ASC 排序)、current_wave 当前正在打包的团购波次(wms_pack_task 中 pack_mode=2 且 wave_id>0 的最新一条未结束任务组装,含波次订单数 order_count 与商品总件数 items_total,无团购任务时为空对象)与 current_orders 当前正在打包的订单数组(未结束任务(status<2)对应订单,逐单按 current→dispatch 分表补发货单号/订单类型/货主/件数等字段,散单任务(pack_mode=1)另附 items 商品明细(含条码/图片/包装要求/是否需要复核 need_recheck 等,供工作台退出/刷新后恢复任务上下文),团购任务(pack_mode=2)items 为波次商品 SKU 聚合汇总(波次内全部未拦截订单按 SKU 聚合计划数量并合并 stock 详情,15s 短缓存兜底,元素另附 is_wave_summary=true;无进行中任务时为空数组);绑定/移除成员、packOrder/finishPack 打包状态变更后 token 缓存立即失效,下一次调用即返回最新成员与打包信息;打包信息查询异常时降级(current_wave 空对象、current_orders 空数组,单笔商品明细查询异常时 items 降级为空数组),不影响主信息与 members;token 缺失返回失败(flag=failure、code=401,消息「工作台 token 不能为空」)、token 不存在或无对应工作台返回失败(flag=failure、code=403)", "isNeedAuth": false, "isNeedLogin": false, "headers": [], @@ -34093,6 +34093,156 @@ "required": true, "description": "打包数量(件数)" }, + { + "name": "current_orders[].item_quantity", + "type": "number", + "required": true, + "description": "商品总数量(来自 wms_pack_task.item_quantity)" + }, + { + "name": "current_orders[].sku_count", + "type": "number", + "required": true, + "description": "商品种类数(SKU 数,来自 wms_pack_task.sku_count)" + }, + { + "name": "current_orders[].waybill_code", + "type": "string", + "required": false, + "description": "运单号(来自 wms_pack_task.waybill_code,散单任务创建时未回填则为空串)" + }, + { + "name": "current_orders[].order_type", + "type": "string", + "required": false, + "description": "订单类型(订单分表未命中时为空串)" + }, + { + "name": "current_orders[].store_id", + "type": "number", + "required": true, + "description": "货主ID(订单分表未命中时为 0)" + }, + { + "name": "current_orders[].items_count", + "type": "number", + "required": true, + "description": "订单商品品种数(订单分表 items_count,未命中时为 0)" + }, + { + "name": "current_orders[].items_total", + "type": "number", + "required": true, + "description": "订单商品总件数(订单分表 items_total,未命中时为 0)" + }, + { + "name": "current_orders[].items", + "type": "array", + "required": true, + "description": "商品数组:散单任务(pack_mode=1)为单笔订单商品明细(逐项合并 stock 详情(条码/图片/包装要求,走 getStockDetails 缓存));团购任务(pack_mode=2)为波次商品 SKU 聚合汇总(波次内全部未拦截订单按 SKU 聚合计划数量,15s 短缓存兜底,元素另附 is_wave_summary=true);查询异常降级为空数组" + }, + { + "name": "current_orders[].items[].id", + "type": "number", + "required": true, + "description": "订单商品明细ID(wms_order_items 分表 id;团购波次聚合行为 0)" + }, + { + "name": "current_orders[].items[].order_id", + "type": "number", + "required": false, + "description": "订单ID(团购波次聚合行为 0)" + }, + { + "name": "current_orders[].items[].item_id", + "type": "number", + "required": false, + "description": "商品ID" + }, + { + "name": "current_orders[].items[].item_code", + "type": "string", + "required": true, + "description": "商品编码(明细为空时回退 stock.item_code)" + }, + { + "name": "current_orders[].items[].item_name", + "type": "string", + "required": true, + "description": "商品名称(明细为空时回退 stock.item_name)" + }, + { + "name": "current_orders[].items[].plan_qty", + "type": "number", + "required": false, + "description": "计划数量(团购波次聚合行为波次内该 SKU 计划数量合计)" + }, + { + "name": "current_orders[].items[].actual_price", + "type": "number", + "required": false, + "description": "实际价格" + }, + { + "name": "current_orders[].items[].stock_id", + "type": "number", + "required": true, + "description": "库存ID(商品ID)" + }, + { + "name": "current_orders[].items[].order_line_no", + "type": "string", + "required": true, + "description": "订单行号" + }, + { + "name": "current_orders[].items[].inventory_type", + "type": "string", + "required": true, + "description": "库存类型" + }, + { + "name": "current_orders[].items[].sku_property", + "type": "string", + "required": false, + "description": "SKU 属性(来自 stock 详情,无则空串)" + }, + { + "name": "current_orders[].items[].stock_unit", + "type": "string", + "required": false, + "description": "库存单位(来自 stock 详情,无则空串)" + }, + { + "name": "current_orders[].items[].barcodes", + "type": "array", + "required": false, + "description": "条码列表(来自 stock 详情,无则空数组)" + }, + { + "name": "current_orders[].items[].image_url", + "type": "array", + "required": false, + "description": "商品图片地址数组(来自 stock 详情,无则空数组)" + }, + { + "name": "current_orders[].items[].packing_requirements", + "type": "string", + "required": false, + "description": "包装要求(来自 stock 详情,无则空串)" + }, + { + "name": "current_orders[].items[].need_recheck", + "type": "string", + "required": true, + "description": "是否需要复核:Y=需要复核,N=不需要复核(免验)(来自 stock 详情,缺省 Y)" + }, + { + "name": "current_orders[].items[].is_wave_summary", + "type": "boolean", + "required": false, + "description": "是否波次聚合行(仅团购任务 items 元素返回 true,用于区分单笔明细与波次 SKU 汇总)" + }, { "name": "current_orders[].operator_text", "type": "string", @@ -34668,7 +34818,7 @@ }, { "method": "workbench.queryOrder", - "description": "工作台条码查询订单(免登录、免权限、免鉴权,以工作台 token 鉴权):仓库与工作台均由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值,防止跨仓库查单),入参条码(运单号);条码→运单记录(wms_order_express,按 waybill_code+warehouse_id+status=1 精确匹配)→ 序列表定位优先、未命中按 current→dispatch 回退遍历订单分表 → 组装查询结果(barcode/waybill_code/isSandan/store_remark/express/order/items/source_table);散单(isSandan=1)order 附拦截/打包 0/1 标志 intercept_flag/pack_flag(拦截/打包状态空值归一化为 none,非 none 记 1);团购(isSandan=0,波次类型 wave_type=1)附 batch 波次信息(wave_id/wave_no/wave_type/total_orders,total_orders 为 current+dispatch 分表实时统计并带 15s 短缓存兜底);items 逐项合并 stock 详情(sku_property/stock_unit/barcodes/image_url/packing_requirements);store_remark 来自合约表 store_warehouse.store_remask;只读查询,不涉及缓存失效;保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200", + "description": "工作台条码查询订单(免登录、免权限、免鉴权,以工作台 token 鉴权):仓库与工作台均由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值,防止跨仓库查单),入参条码(运单号);条码→运单记录(wms_order_express,按 waybill_code+warehouse_id+status=1 精确匹配)→ 序列表定位优先、未命中按 current→dispatch 回退遍历订单分表 → 组装查询结果(barcode/waybill_code/isSandan/store_remark/express/order/items/source_table);散单(isSandan=1)order 附拦截/打包 0/1 标志 intercept_flag/pack_flag(拦截/打包状态空值归一化为 none,非 none 记 1);团购(isSandan=0,波次类型 wave_type=1)附 batch 波次信息(wave_id/wave_no/wave_type/total_orders,total_orders 为 current+dispatch 分表实时统计并带 15s 短缓存兜底);items 逐项合并 stock 详情(sku_property/stock_unit/barcodes/image_url/packing_requirements/need_recheck(是否需要复核:Y=需要 N=不需要(免验)));store_remark 来自合约表 store_warehouse.store_remask;只读查询,不涉及缓存失效;保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200", "isNeedAuth": false, "isNeedLogin": false, "isNeedRight": false, @@ -34984,6 +35134,12 @@ "required": false, "description": "打包要求(来自 stock 详情,trim 后返回)" }, + { + "name": "items[].need_recheck", + "type": "string", + "required": true, + "description": "是否需要复核:Y=需要复核,N=不需要复核(免验)(来自 stock 详情,缺省 Y)" + }, { "name": "source_table", "type": "string",