From 562f63f18e917e2ebd8b9e5763a74eda935a5554 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Wed, 28 Oct 2026 07:22:44 +0800 Subject: [PATCH] =?UTF-8?q?feat(stock.check):=20=E5=95=86=E5=93=81?= =?UTF-8?q?=E8=A7=86=E5=9B=BE=E6=8C=89=E5=95=86=E5=93=81=E6=B1=87=E6=80=BB?= =?UTF-8?q?=E3=80=81=E8=B4=A6=E9=9D=A2=E6=8C=89=E9=9D=99=E6=80=81=E6=A0=87?= =?UTF-8?q?=E8=AE=B0=E5=8F=96=E5=80=BC=E3=80=81=E9=9D=99=E6=80=81=E7=9B=98?= =?UTF-8?q?=E7=82=B9=E9=94=81=E5=AE=9A=E7=BC=93=E5=AD=98=E4=B8=8E=E5=BA=93?= =?UTF-8?q?=E5=AD=98=E6=93=8D=E4=BD=9C=E6=8B=A6=E6=88=AA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 盘点作业数据(workData / workDataDetail) - workData goods 视图按 stock_id 汇总为一行(同商品多库位明细合并):行级账面=各库位之和, 作业记录跨明细按库位合并,locations 每项补 detail_id/snapshot_quantity,行级不再返回 detail_id。 - workDataDetail 商品分支改为 id + stock_id 钻取,返回 summary(汇总)+ rows(按库位分行: 明细ID/库位ID/账面快照/当前账面/实盘/差异);兼容传商品范围 detail_id。 - 账面取值按任务 is_static 区分:静态盘点取明细快照(冻结基准),普通盘点取当前 wms_storage; 新增 storage_quantity / is_static / book_source 字段,差异统一为「实盘 - system_quantity」。 - report 的 detail_id 改为可选:商品行可只传 id + stock_id + space_id,服务端按库位明细反查。 静态盘点(is_static) - wms_stock_check 新增 is_static(TINYINT(1) DEFAULT 0,迁移 20261028010000);create 支持 is_static (仅商品盘点有效,库位盘点恒 0);静态定式 pattern=static 创建的任务自动置 1。 - 新增公共查询 stock.check.staticLockList:返回 is_static=1 且 approved/checking 任务的商品集合, 按仓库缓存(TTL 300s、状态流转先递增代次再重建、回源前后代次校验防脏读、空集合也缓存、 进程内 singleflight 防击穿),并提供 isStockStaticLocked / getStaticLockConflict 供内部判断。 - 审核通过时刷新商品明细账面快照(快照基准=开始盘点时点),finish 立即释放锁定并返回 released_stock_ids。 - 库存操作拦截:分配储位命中锁定商品时按「库存不足」同流程将该订单标记失败(storage_status=error + order_flag),同批次其它订单继续;移库(transferLocation / transferByProduct)命中锁定直接 400。 其他 - 新增开发环境实测脚本 script/stock-check-goods-summary-verify.cjs。 - 测试:stock_check.test.js 覆盖汇总/钻取/静态标记/锁定缓存/账面口径;新增 static_lock_guard.test.js 覆盖分配与移库拦截;methods/system.json 与 changes 更新至 0.3.318。 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- app/model/stock_check.js | 8 +- app/service/systemMethods/stock/check.js | 86 +- .../systems/order_storage_allocation.js | 60 +- app/service/systems/stock_check.js | 858 +++++++++++-- app/service/systems/storage/inventory.js | 174 ++- ...1028010000-add-is-static-to-stock-check.js | 25 + methods/changes/system.json | 206 +++ methods/system.json | 242 +++- script/stock-check-goods-summary-verify.cjs | 182 +++ .../service/systems/static_lock_guard.test.js | 350 ++++++ test/app/service/systems/stock_check.test.js | 1117 +++++++++++++++-- 11 files changed, 3079 insertions(+), 229 deletions(-) create mode 100644 database/migrations/20261028010000-add-is-static-to-stock-check.js create mode 100644 script/stock-check-goods-summary-verify.cjs create mode 100644 test/app/service/systems/static_lock_guard.test.js diff --git a/app/model/stock_check.js b/app/model/stock_check.js index b4d8368..83afcb3 100644 --- a/app/model/stock_check.js +++ b/app/model/stock_check.js @@ -6,7 +6,7 @@ * @return {import('sequelize').ModelCtor} Sequelize 模型。 */ module.exports = app => { - const { BIGINT, STRING, INTEGER, DATE, JSON: JSON_TYPE } = app.Sequelize; + const { BIGINT, STRING, INTEGER, TINYINT, DATE, JSON: JSON_TYPE } = app.Sequelize; const StockCheck = app.model.define('wms_stock_check', { id: { @@ -47,6 +47,12 @@ module.exports = app => { allowNull: true, comment: '货主ID,按货主盘点时必填(type=store)', }, + is_static: { + type: TINYINT(1), + allowNull: false, + defaultValue: 0, + comment: '是否静态盘点(1=静态盘点(静态定式创建或创建时开启),0=普通盘点)', + }, scope_snapshot: { type: JSON_TYPE, allowNull: true, diff --git a/app/service/systemMethods/stock/check.js b/app/service/systemMethods/stock/check.js index 82131f3..529603b 100644 --- a/app/service/systemMethods/stock/check.js +++ b/app/service/systemMethods/stock/check.js @@ -8,8 +8,8 @@ const STOCK_CHECK_EXPORT_TASK_CACHE_TTL_SECONDS = 1800; /** 单次导出任务允许的最大盘点任务数量 */ const STOCK_CHECK_EXPORT_MAX_TASK_IDS = 50; -/** 全部 24 个 method 名(免权限/免鉴权清单共用) */ -const ALL_METHOD_NAMES = 'create,list,addDetail,addLocationDetail,detailDelete,detail,result,workData,workDataSpaceDetails,workDataDetail,report,markEmpty,recordList,recordDelete,recheckClearLocation,finish,submit,cancel,audit,batchDelete,export,exportDetail,exportTaskProgress,patternList,patternCreate'; +/** 全部 25 个 method 名(免权限/免鉴权清单共用) */ +const ALL_METHOD_NAMES = 'create,list,addDetail,addLocationDetail,detailDelete,detail,result,workData,workDataSpaceDetails,workDataDetail,report,markEmpty,recordList,recordDelete,recheckClearLocation,finish,submit,cancel,audit,batchDelete,export,exportDetail,exportTaskProgress,patternList,patternCreate,staticLockList'; /** * 系统方法层:stock.check(库存盘点模块接口包装层)。 @@ -24,7 +24,7 @@ class StockCheckMethodService extends MainService { // 免权限方法列表:全部 20 个方法免 API 权限校验(与 stock/transaction.js 口径一致) const _noNeedRight = ALL_METHOD_NAMES; // 免日志方法列表:查询类与导出类不记录操作日志(recordDelete/patternCreate 为写操作,保留操作日志) - const _noNeedLog = 'list,detail,result,workData,workDataSpaceDetails,workDataDetail,recordList,export,exportDetail,exportTaskProgress,patternList'; + const _noNeedLog = 'list,detail,result,workData,workDataSpaceDetails,workDataDetail,recordList,staticLockList,export,exportDetail,exportTaskProgress,patternList'; // 免鉴权(仓库有效期检查)方法列表:全部方法免鉴权(与 stock/transaction.js 口径一致) const _noNeedAuth = ALL_METHOD_NAMES; this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth); @@ -63,6 +63,8 @@ class StockCheckMethodService extends MainService { * @param {string} [data.mode] 盘点方式:open=明盘/blind=盲盘; * 按库位盘点(location)一律盲盘,忽略前端传入;按商品盘点(store/goods)按传入值(默认明盘)。 * @param {number} [data.store_id] 货主ID(按货主盘点时必填)。 + * @param {boolean|number} [data.is_static] 是否静态盘点(纯标记,0/1 或布尔;兼容 isStatic 驼峰写法; + * 缺省 0=普通盘点;仅对商品盘点有效,按库位盘点一律 0。静态盘点定式创建的任务由服务端自动置 1)。 * @param {string} [data.remark] 备注。 * 盘点日期固定为今天,前端不传。 * @return {Promise} 统一 success 包装,返回新建的盘点任务信息。 @@ -72,7 +74,18 @@ class StockCheckMethodService extends MainService { const warehouseId = Number(ctx.user && ctx.user.store_id) || 0; const creatorId = ctx.user ? (ctx.user.id || ctx.user.user_id || 0) : 0; const creatorName = ctx.user ? (ctx.user.employees_name || ctx.user.real_name || '') : ''; - const { title, type, mode, store_id: storeId, remark } = data || {}; + const { + title, + type, + mode, + store_id: storeIdSnake, + storeId: storeIdCamel, + is_static: isStaticSnake, + isStatic: isStaticCamel, + remark, + } = data || {}; + const storeId = storeIdSnake !== undefined ? storeIdSnake : storeIdCamel; + const isStatic = isStaticSnake !== undefined ? isStaticSnake : isStaticCamel; return this._call( () => this.service.systems.stockCheck.create({ @@ -81,6 +94,7 @@ class StockCheckMethodService extends MainService { type, mode, storeId, + isStatic, remark, creatorId, creatorName, @@ -102,6 +116,26 @@ class StockCheckMethodService extends MainService { ); } + /** + * 拉取「静态盘点锁定中」的库存商品列表(公共查询,供库存操作前置判断)。 + * warehouse_id 由服务端从当前上下文自动注入,前端无需传递。 + * 口径:is_static=1 且状态为 approved(审核完成)/checking(盘点作业中)任务的商品明细 stock_id 去重集合; + * 结果按仓库维度缓存(TTL 300 秒,状态流转时主动失效)。 + * + * @return {Promise} 统一 success 包装,返回 + * { warehouse_id, stock_ids, rows, total, cached, updated_at }; + * rows 每个 stock_id 一条:{ stock_id, item_code, item_name, check_ids, check_nos, location_codes }。 + */ + async staticLockList() { + const { ctx } = this; + const warehouseId = Number(ctx.user && ctx.user.store_id) || 0; + + return this._call( + () => this.service.systems.stockCheck.staticLockList({ warehouseId }), + '拉取静态盘点锁定商品列表失败' + ); + } + /** * 按定式快速创建盘点任务。 * warehouse_id 由服务端从当前上下文自动注入,前端无需传递。 @@ -357,8 +391,9 @@ class StockCheckMethodService extends MainService { * @param {Object} [data.pagination] 分页配置 { page, pageSize }。 * @return {Promise} 统一 success 包装,返回 { view, rows, total, page, pageSize };rows 结构按视图不同: * location=库位结构(任务库位范围行为列表,行内挂 goods/unknown 作业记录子列表); - * goods=商品结构(任务商品范围行为列表,行内挂按库位聚合的 locations 作业记录, - * 明盘返回数量与差异,盲盘不返回数量字段); + * goods=商品结构(按商品 stock_id 汇总,一个商品一行——同商品的库位明细行合并: + * 行内 locations 每项带该库位明细ID detail_id 与账面快照 snapshot_quantity(明盘), + * 明盘返回数量与差异,盲盘不返回数量字段;逐库位明细请调 workDataDetail(id + stock_id)); * space=聚合库位结构(任务商品所在库位为列表,按拣货路径排序,行内挂该库位的任务商品, * 明盘返回账面/实盘数量,盲盘不返回数量字段)。 */ @@ -415,27 +450,41 @@ class StockCheckMethodService extends MainService { } /** - * 拉取单条盘点明细的作业数据(workData 单行版)。 + * 拉取盘点作业数据明细(库位明细单行 / 商品钻取)。 * warehouse_id 由服务端从当前上下文自动注入,前端无需传递。 - * 按明细范围类型分流,均返回单行对象(与对应视图单行结构一致): - * 库位明细(scope_type=location)行结构同 workData location 视图单行 - * (detail_id/location_id/location_code/location_name/status/has_unknown/is_empty/ - * checked_at/checkers/goods);商品明细(scope_type=goods)行结构同 workData goods 视图行 - * (detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images/locations, - * 明盘含 system_quantity/checked_quantity/diff_quantity/is_diff,盲盘不含数量字段)。 + * ① 库位明细(detail_id 指向 scope_type=location 的行)返回单行, + * 结构与 workData location 视图单行一致(detail_id/location_id/location_code/location_name/ + * status/has_unknown/is_empty/checked_at/checkers/goods); + * ② 商品(id=盘点任务ID + stock_id,或 detail_id 指向商品范围行)返回该商品的库位分行数据 + 汇总: + * { check_id, stock_id, item_code/item_name/spec/store_id/store_name/barcode/images, + * summary 商品级汇总(明盘含 system_quantity 账面快照合计/checked_quantity 实盘合计/ + * diff_quantity/is_diff;盲盘不含数量字段), + * rows 按库位分行(detail_id 该库位明细ID/location_id 与同义 space_id/location_code, + * 明盘另含 system_quantity 该库位当前账面/snapshot_quantity 该库位账面快照/locked_quantity/ + * checked_quantity 该库位实盘/diff_quantity 该库位差异,另有 checked_at/checker_name/record_ids/images) }。 * * @param {Object} data 请求体。 - * @param {number} data.detail_id 盘点明细ID(库位范围行或商品范围行;兼容 detailId 驼峰写法)。 - * @return {Promise} 统一 success 包装,data 为单行作业数据(结构随明细范围类型)。 + * @param {number} [data.id] 盘点任务ID(商品钻取必传,与 stock_id 搭配)。 + * @param {number} [data.stock_id] 商品库存ID(商品钻取必传;兼容 stockId 驼峰写法)。 + * @param {number} [data.detail_id] 盘点明细ID(库位明细必传;商品可只传本参数按明细商品钻取; + * 兼容 detailId 驼峰写法)。 + * @return {Promise} 统一 success 包装,data 为库位单行或商品 { summary, rows } 结构。 */ async workDataDetail(data = {}) { const { ctx } = this; const warehouseId = Number(ctx.user && ctx.user.store_id) || 0; - const { detail_id: detailIdSnake, detailId: detailIdCamel } = data || {}; + const { + id, + detail_id: detailIdSnake, + detailId: detailIdCamel, + stock_id: stockIdSnake, + stockId: stockIdCamel, + } = data || {}; const detailId = detailIdSnake !== undefined ? detailIdSnake : detailIdCamel; + const stockId = stockIdSnake !== undefined ? stockIdSnake : stockIdCamel; return this._call( - () => this.service.systems.stockCheck.workDataDetail({ warehouseId, detailId }), + () => this.service.systems.stockCheck.workDataDetail({ warehouseId, id, stockId, detailId }), '拉取盘点明细作业数据失败' ); } @@ -449,7 +498,8 @@ class StockCheckMethodService extends MainService { * * @param {Object} data 请求体。 * @param {number} data.id 盘点任务ID。 - * @param {number} data.detail_id 明细ID。 + * @param {number} [data.detail_id] 明细ID(可选:商品行可不传,服务端按 id + stock_id + space_id + * 反查该商品的库位明细;库位盘点行仍必传)。 * @param {number} data.space_id 库位ID(wms_location_space.id,**必传**;兼容 spaceId / location_id / locationId 写法)。 * 必须属于本仓库且所属分区有效;服务端以该 ID 为准落库,不再按库位编码猜库位。 * @param {string} [data.location] 库位编码(可选,仅做一致性校验:与 space_id 对应库位编码不一致报 400)。 diff --git a/app/service/systems/order_storage_allocation.js b/app/service/systems/order_storage_allocation.js index 17ff28a..b40988f 100644 --- a/app/service/systems/order_storage_allocation.js +++ b/app/service/systems/order_storage_allocation.js @@ -799,6 +799,36 @@ class OrderStorageAllocationService extends MainService { const stockIds = Array.from(stockIdSet); + // 静态盘点锁定:与「库存不足」同流程——命中锁定的订单标记失败(storage_status=error/order_flag), + // 其余订单继续正常分配,不整单中断(最终由 shortage_order_ids / shortage_messages 返回) + const staticLockRowByStock = new Map(); + const stockCheckService = ctx.service && ctx.service.systems && ctx.service.systems.stockCheck; + if (stockIds.length > 0 && stockCheckService && typeof stockCheckService.getStaticLockConflict === 'function') { + try { + const lockConflict = await stockCheckService.getStaticLockConflict({ + warehouseId, + stockIds, + actionLabel: '分配储位', + }); + if (lockConflict.locked) { + for (const row of lockConflict.rows) { + staticLockRowByStock.set(Number(row.stock_id), row); + } + writeAllocationTextLog('[OrderStorageAllocationService.allocatePicking] 命中静态盘点锁定,相关订单将标记分配失败', { + warehouseId, + orderIds, + lockedStockIds: [ ...staticLockRowByStock.keys() ], + message: lockConflict.message, + }); + } + } catch (error) { + // 锁定查询异常不阻断分配主流程(按未锁定处理),仅记录日志 + if (ctx.logger && typeof ctx.logger.warn === 'function') { + ctx.logger.warn(`[OrderStorageAllocationService.allocatePicking] 静态盘点锁定查询失败: ${error && error.message}`); + } + } + } + writeAllocationTextLog('[OrderStorageAllocationService.allocatePicking] 订单明细归集完成', { warehouseId, pendingOrderCount: pendingOrderIds.length, @@ -1022,10 +1052,38 @@ class OrderStorageAllocationService extends MainService { const storageRowErrors = []; let allocatedQuantityForOrder = 0; + // 静态盘点锁定:本订单明细中含锁定商品时,整单标记失败(与库存不足同流程) + const lockedStockIdsInOrder = []; + for (const orderItem of orderItems) { + const lockedStockId = toNumber(orderItem.stock_id, 0); + if (lockedStockId > 0 && staticLockRowByStock.has(lockedStockId) && !lockedStockIdsInOrder.includes(lockedStockId)) { + lockedStockIdsInOrder.push(lockedStockId); + } + } + const staticLockMessage = lockedStockIdsInOrder.length > 0 + ? `静态盘点锁定:${lockedStockIdsInOrder.map(lockedStockId => { + const lockRow = staticLockRowByStock.get(lockedStockId) || {}; + const checkNos = (Array.isArray(lockRow.check_nos) ? lockRow.check_nos : []).filter(Boolean).join('/'); + return checkNos ? `sku(${lockedStockId}) 盘点单 ${checkNos}` : `sku(${lockedStockId})`; + }).join('|')}` + : ''; + if (staticLockMessage) { + writeAllocationTextLog('[OrderStorageAllocationService.allocatePicking] 订单命中静态盘点锁定,跳过分配', { + orderId, + lockedStockIds: lockedStockIdsInOrder, + staticLockMessage, + }); + } + for (const orderItem of orderItems) { const stockId = toNumber(orderItem.stock_id, 0); const requiredQuantity = toNumber(orderItem.plan_qty ?? orderItem.planQty ?? orderItem.count ?? 0, 0); + // 静态盘点锁定商品:不参与分配(不查储位、不加锁),整单由 staticLockMessage 标记失败 + if (stockId > 0 && staticLockRowByStock.has(stockId)) { + continue; + } + if (stockId <= 0 || requiredQuantity <= 0) { shortageItems.push({ stock_id: stockId, @@ -1324,7 +1382,7 @@ class OrderStorageAllocationService extends MainService { const spaceErrorMessage = storageRowErrors.length > 0 && shortageMessage ? `库位未设置(storage_id:${storageRowErrors.map(e => e.storage_id).join(',')})` : ''; - const finalShortageMessage = [ shortageMessage, spaceErrorMessage ].filter(Boolean).join('|'); + const finalShortageMessage = [ staticLockMessage, shortageMessage, spaceErrorMessage ].filter(Boolean).join('|'); writeAllocationTextLog('[OrderStorageAllocationService.allocatePicking] 订单缺货信息汇总', { orderId, diff --git a/app/service/systems/stock_check.js b/app/service/systems/stock_check.js index 4a4e485..f3c7d01 100644 --- a/app/service/systems/stock_check.js +++ b/app/service/systems/stock_check.js @@ -27,6 +27,24 @@ const REPORT_MAX_QUANTITY = 2147483647; const SUBMIT_ALLOWED_STATUSES = Object.freeze([ 'created', 'rejected' ]); /** 允许取消的主表状态 */ const CANCEL_ALLOWED_STATUSES = Object.freeze([ 'created', 'submitted', 'rejected' ]); +/** + * 静态盘点锁定中口径:is_static=1 且主表状态为「未结束」的任务(审核完成即开始锁定, + * 盘点作业中持续锁定;提交审核前、已完成/已取消/已驳回均不锁定)。 + */ +const STATIC_LOCK_ALLOWED_STATUSES = Object.freeze([ 'approved', 'checking' ]); +/** 静态盘点锁定缓存键前缀(按仓库维度缓存 stock_id 集合) */ +const STATIC_LOCK_CACHE_KEY_PREFIX = 'stock_check:static_lock:'; +/** 静态盘点锁定代次键前缀(状态流转时递增,供回源前后一致性校验防脏读) */ +const STATIC_LOCK_GENERATION_KEY_PREFIX = 'stock_check:static_lock_gen:'; +/** 锁定代次进程内回退计数(Redis 不可用时使用) */ +const STATIC_LOCK_GENERATION_LOCAL = new Map(); +/** 静态盘点锁定缓存 TTL(秒):状态流转时主动重建,此处仅作兜底过期 */ +const STATIC_LOCK_CACHE_TTL_SECONDS = 300; +/** + * 进程内 singleflight 表(键=缓存键,值=回源 Promise): + * 缓存未命中/失效瞬间的并发查询共用同一次数据库回源,避免瞬时击穿。 + */ +const STATIC_LOCK_INFLIGHT = new Map(); /** * 有效库位过滤 SQL(库位未删除且所属 zone 存在且未删除)。 @@ -165,6 +183,7 @@ class StockCheckService extends Service { type: row.type || 'location', mode: row.mode || 'open', store_id: row.store_id || null, + is_static: Number(row.is_static) === 1 ? 1 : 0, status: row.status || 'created', detail_status: row.detail_status || 'none_checked', start_time: row.start_time || null, @@ -554,6 +573,9 @@ class StockCheckService extends Service { * @param {string} [params.mode='open'] 盘点方式:open=明盘/blind=盲盘; * 按库位盘点(location)一律盲盘,忽略前端传入;按商品盘点(store/goods)按传入值(默认明盘)。 * @param {number} [params.storeId] 货主ID(按货主盘点时必填)。 + * @param {boolean|number} [params.isStatic] 是否静态盘点(纯标记):true/'true'/1/'1' 记为静态, + * 缺省与其他值为普通盘点;**仅对商品盘点(store/goods)有效**,按库位盘点(location)一律为 0 + * (忽略入参);静态盘点定式创建的任务自动置 1。 * @param {string} [params.remark] 备注。 * 盘点日期固定为今天,前端不传。 * @param {number} params.creatorId 创建人账户ID(由方法层从上下文注入)。 @@ -568,6 +590,7 @@ class StockCheckService extends Service { type, mode, storeId, + isStatic, remark, creatorId, creatorName, @@ -601,6 +624,11 @@ class StockCheckService extends Service { throw this.createBusinessError('按货主盘点时必须指定货主'); } + // 是否静态盘点:纯标记(true/'true'/1/'1' 视为开启,缺省/其他值为普通盘点); + // 仅对商品盘点有效——按库位盘点(type=location)一律为 0,忽略入参 + const isStaticRequested = isStatic === true || isStatic === 'true' || isStatic === 1 || isStatic === '1'; + const normalizedIsStatic = normalizedType === 'location' || !isStaticRequested ? 0 : 1; + // 创建盘点任务(并发下撞 uk_check_no 唯一键时自动重取单号,参照收货单口径,最多重试 5 次) const maxCreateRetries = 5; let record = null; @@ -614,6 +642,7 @@ class StockCheckService extends Service { type: normalizedType, mode: normalizedMode, store_id: normalizedStoreId, + is_static: normalizedIsStatic, scope_snapshot: null, status: 'created', detail_status: 'none_checked', @@ -641,7 +670,7 @@ class StockCheckService extends Service { businessId: plainRecord.id, operationCode: 'STOCK_CHECK_CREATE', operationAction: 'CREATE', - changeSummary: `创建盘点任务:单号 ${plainRecord.check_no},范围类型 ${STOCK_CHECK_TYPE_LABELS[normalizedType]},盘点方式 ${STOCK_CHECK_MODE_LABELS[normalizedMode]}`, + changeSummary: `创建盘点任务:单号 ${plainRecord.check_no},范围类型 ${STOCK_CHECK_TYPE_LABELS[normalizedType]},盘点方式 ${STOCK_CHECK_MODE_LABELS[normalizedMode]}${normalizedIsStatic ? ',静态盘点' : ''}`, operator: { id: ctx.user?.employees_id || ctx.user?.id || '', name: ctx.user?.employees_name || '', @@ -651,7 +680,8 @@ class StockCheckService extends Service { checkNo: plainRecord.check_no, type: normalizedType, mode: normalizedMode, - message: `创建盘点任务 ${plainRecord.check_no}(${STOCK_CHECK_TYPE_LABELS[normalizedType]}/${STOCK_CHECK_MODE_LABELS[normalizedMode]})`, + isStatic: normalizedIsStatic, + message: `创建盘点任务 ${plainRecord.check_no}(${STOCK_CHECK_TYPE_LABELS[normalizedType]}/${STOCK_CHECK_MODE_LABELS[normalizedMode]}${normalizedIsStatic ? '/静态' : ''})`, }, }); @@ -917,6 +947,9 @@ class StockCheckService extends Service { // 盘点方式由定式范围类型固定:库位类一律盲盘、商品类一律明盘(前端不传) const normalizedMode = pattern.type === 'location' ? 'blind' : 'open'; + // 静态定式创建的任务标记为静态盘点(纯标记,不改变流程与数量口径); + // 静态盘点仅对商品盘点有效,库位类定式一律 0 + const normalizedIsStatic = pattern.id === 'static' && pattern.type !== 'location' ? 1 : 0; const normalizedTitle = title ? String(title).trim() : pattern.name; @@ -946,6 +979,7 @@ class StockCheckService extends Service { type: pattern.type, mode: normalizedMode, store_id: null, + is_static: normalizedIsStatic, scope_snapshot: null, status: 'submitted', detail_status: 'none_checked', @@ -1026,7 +1060,7 @@ class StockCheckService extends Service { businessId: plainRecord.id, operationCode: 'STOCK_CHECK_CREATE', operationAction: 'CREATE', - changeSummary: `按定式创建盘点任务:单号 ${plainRecord.check_no},定式 ${pattern.name}(${pattern.id}),范围类型 ${STOCK_CHECK_TYPE_LABELS[pattern.type]},盘点方式 ${STOCK_CHECK_MODE_LABELS[normalizedMode]}`, + changeSummary: `按定式创建盘点任务:单号 ${plainRecord.check_no},定式 ${pattern.name}(${pattern.id}),范围类型 ${STOCK_CHECK_TYPE_LABELS[pattern.type]},盘点方式 ${STOCK_CHECK_MODE_LABELS[normalizedMode]}${normalizedIsStatic ? ',静态盘点' : ''}`, operator: { id: ctx.user?.employees_id || ctx.user?.id || '', name: ctx.user?.employees_name || '', @@ -1720,6 +1754,382 @@ class StockCheckService extends Service { }; } + /** + * 构建静态盘点锁定缓存键(按仓库维度)。 + * + * @param {number} warehouseId 仓库ID。 + * @return {string} 缓存键。 + */ + _staticLockCacheKey(warehouseId) { + return `${STATIC_LOCK_CACHE_KEY_PREFIX}${Number(warehouseId) || 0}`; + } + + /** + * 查询「静态盘点锁定中」的库存商品列表(公共查询,供库存操作前判断是否可动)。 + * + * 口径:主表 is_static=1 且状态为 approved(审核完成)/checking(盘点作业中)的任务, + * 取其商品范围明细(scope_type=goods)的 stock_id 去重集合——即这些商品的库位正在静态盘点, + * 出入库/移库等库存操作应被限制;任务提交审核前(created/submitted/rejected)与 + * 已完成(completed)/已取消(cancelled)不锁定。 + * + * 缓存:结果按仓库维度缓存在 `stock_check:static_lock:{warehouseId}`(TTL 300 秒兜底, + * Redis 优先、不可用时降级进程内缓存);审核/完成/取消/批量删除等状态流转时**立即重建缓存** + * (不是简单删除再等下次回源),空集合也会被缓存(不会因「当前没有锁定商品」反复回源)。 + * 同一进程内并发未命中用 singleflight 去重,只回源一次。返回 cached 标识本次是否命中缓存。 + * + * @param {Object} params 查询参数。 + * @param {number} params.warehouseId 仓库ID(由方法层从上下文注入)。 + * @param {boolean} [params.forceRefresh] 跳过缓存强制回源重建(内部/排障用)。 + * @return {Promise} { warehouse_id, stock_ids, rows, total, cached, updated_at }; + * rows 每个 stock_id 一条:{ stock_id, item_code, item_name, check_ids, check_nos, location_codes }。 + */ + async staticLockList(params = {}) { + const { warehouseId, forceRefresh } = params; + + const normalizedWarehouseId = Number(warehouseId); + if (!Number.isInteger(normalizedWarehouseId) || normalizedWarehouseId <= 0) { + throw this.createBusinessError('无法获取当前仓库上下文'); + } + + const cacheKey = this._staticLockCacheKey(normalizedWarehouseId); + if (forceRefresh !== true && forceRefresh !== 'true' && forceRefresh !== 1) { + const cachedPayload = await this._readStaticLockCache(cacheKey); + if (cachedPayload) { + return cachedPayload; + } + } + + const payload = await this._loadStaticLockCache(normalizedWarehouseId); + return payload; + } + + /** + * 读取锁定缓存(命中时补齐 cached=true)。 + * + * @param {string} cacheKey 缓存键。 + * @return {Promise} 缓存载荷(已格式化)或 null。 + */ + async _readStaticLockCache(cacheKey) { + const { ctx } = this; + const cachedPayload = await ctx.app.getCacheAsync(cacheKey); + if (!cachedPayload || !Array.isArray(cachedPayload.rows)) { + return null; + } + return { + warehouse_id: Number(cachedPayload.warehouse_id) || 0, + stock_ids: cachedPayload.stock_ids || [], + rows: cachedPayload.rows, + total: cachedPayload.rows.length, + cached: true, + updated_at: cachedPayload.updated_at || null, + }; + } + + /** + * 回源数据库并写入缓存(进程内 singleflight:同仓库并发未命中只回源一次)。 + * + * 防脏读(写缓存乐观锁):回源前后各读一次「锁定代次」(状态流转时由 + * refreshStaticLockCache 递增),两次不一致说明查询期间有并发状态流转, + * 本次结果可能是旧快照 → **放弃写入缓存**(删除缓存,交给下一次查询/该次流转的重建), + * 避免用旧快照覆盖新缓存。 + * + * @param {number} warehouseId 仓库ID。 + * @return {Promise} 格式化后的载荷(cached=false;未写缓存时同样带 skipped_write 标识)。 + */ + async _loadStaticLockCache(warehouseId) { + const { ctx } = this; + const cacheKey = this._staticLockCacheKey(warehouseId); + const inflight = STATIC_LOCK_INFLIGHT.get(cacheKey); + if (inflight) { + return inflight; + } + + const task = (async () => { + const generationBefore = await this._readStaticLockGeneration(warehouseId); + const rows = await this._queryStaticLockRows(warehouseId); + const generationAfter = await this._readStaticLockGeneration(warehouseId); + const payload = { + warehouse_id: Number(warehouseId), + stock_ids: rows.map(row => row.stock_id), + rows, + updated_at: new Date().toISOString(), + }; + + if (generationBefore !== generationAfter) { + // 查询期间有状态流转:不写入旧快照,删掉缓存让下一次读取回源 + ctx.logger.warn(`[StockCheckStaticLock] 回源期间发生状态流转,跳过写缓存 warehouse=${warehouseId}(gen ${generationBefore} → ${generationAfter})`); + await this.clearStaticLockCache(warehouseId); + return { + ...payload, + total: rows.length, + cached: false, + cache_skipped: true, + }; + } + + await ctx.app.setCacheAsync(cacheKey, payload, STATIC_LOCK_CACHE_TTL_SECONDS); + return { + ...payload, + total: rows.length, + cached: false, + }; + })(); + + STATIC_LOCK_INFLIGHT.set(cacheKey, task); + try { + return await task; + } finally { + STATIC_LOCK_INFLIGHT.delete(cacheKey); + } + } + + /** + * 查询静态锁定商品行(数据库口径,无缓存):is_static=1 且 approved/checking 任务的商品明细。 + * + * @param {number} warehouseId 仓库ID。 + * @return {Promise>} 按 stock_id 升序的聚合行。 + */ + async _queryStaticLockRows(warehouseId) { + const { ctx } = this; + const { Op } = ctx.app.Sequelize; + + const checkRows = await ctx.model.StockCheck.findAll({ + where: { + warehouse_id: Number(warehouseId), + is_static: 1, + status: { [Op.in]: STATIC_LOCK_ALLOWED_STATUSES }, + }, + attributes: [ 'id', 'check_no' ], + raw: true, + }); + if (checkRows.length === 0) { + return []; + } + + const checkNoById = new Map(checkRows.map(row => [ Number(row.id), String(row.check_no || '') ])); + const detailRows = await ctx.model.StockCheckDetail.findAll({ + where: { + check_id: { [Op.in]: [ ...checkNoById.keys() ] }, + scope_type: 'goods', + }, + attributes: [ 'check_id', 'stock_id', 'item_code', 'item_name', 'location_code' ], + raw: true, + }); + + const aggByStock = new Map(); + for (const detailRow of detailRows) { + const stockId = Number(detailRow.stock_id); + if (!Number.isInteger(stockId) || stockId <= 0) { + continue; + } + const agg = aggByStock.get(stockId) || { + stock_id: stockId, + item_code: detailRow.item_code || null, + item_name: detailRow.item_name || null, + check_ids: [], + check_nos: [], + location_codes: [], + }; + const detailCheckId = Number(detailRow.check_id); + if (!agg.check_ids.includes(detailCheckId)) { + agg.check_ids.push(detailCheckId); + agg.check_nos.push(checkNoById.get(detailCheckId) || ''); + } + const locationCode = String(detailRow.location_code || '').trim(); + if (locationCode && !agg.location_codes.includes(locationCode)) { + agg.location_codes.push(locationCode); + } + aggByStock.set(stockId, agg); + } + + return [ ...aggByStock.values() ].sort((left, right) => left.stock_id - right.stock_id); + } + + /** + * 重建静态盘点锁定缓存(状态流转后立即同步,避免「删除缓存 → 下次查询才回源」的空窗)。 + * 顺序:先递增锁定代次(使并发回源中的旧快照自动作废)→ 回源 → 写回缓存; + * 重建失败时降级为删除缓存(下次查询回源),并记录 warn 日志,不影响主流程。 + * + * @param {number} warehouseId 仓库ID。 + * @return {Promise} 无返回值。 + */ + async refreshStaticLockCache(warehouseId) { + const { ctx } = this; + const normalizedWarehouseId = Number(warehouseId); + if (!Number.isInteger(normalizedWarehouseId) || normalizedWarehouseId <= 0) { + return; + } + try { + // 代次必须在回源查询之前递增:并发中的旧回源读到代次变化会放弃写缓存 + await this._bumpStaticLockGeneration(normalizedWarehouseId); + await this._loadStaticLockCache(normalizedWarehouseId); + } catch (error) { + ctx.logger.warn(`[StockCheckStaticLock] 重建静态锁定缓存失败 warehouse=${normalizedWarehouseId}: ${error && error.message}`); + await this.clearStaticLockCache(normalizedWarehouseId); + } + } + + /** + * 构建锁定代次缓存键(状态流转时递增,用于回源前后一致性校验)。 + * + * @param {number} warehouseId 仓库ID。 + * @return {string} 代次键。 + */ + _staticLockGenerationKey(warehouseId) { + return `${STATIC_LOCK_GENERATION_KEY_PREFIX}${Number(warehouseId) || 0}`; + } + + /** + * 读取锁定代次(Redis 不可用时回退进程内计数)。 + * + * @param {number} warehouseId 仓库ID。 + * @return {Promise} 代次值(无记录为 0)。 + */ + async _readStaticLockGeneration(warehouseId) { + const { ctx } = this; + const normalizedWarehouseId = Number(warehouseId); + const redis = ctx.app.redis && typeof ctx.app.redis.get === 'function' ? ctx.app.redis.get('cache') : null; + if (redis && typeof redis.get === 'function') { + try { + const value = await redis.get(this._staticLockGenerationKey(normalizedWarehouseId)); + if (value !== null && value !== undefined) { + return Number(value) || 0; + } + } catch (error) { + ctx.logger.warn(`[StockCheckStaticLock] 读取锁定代次失败,回退进程内计数 warehouse=${normalizedWarehouseId}: ${error && error.message}`); + } + } + return STATIC_LOCK_GENERATION_LOCAL.get(normalizedWarehouseId) || 0; + } + + /** + * 递增锁定代次(Redis INCR 原子递增;不可用时退化为进程内计数)。 + * + * @param {number} warehouseId 仓库ID。 + * @return {Promise} 递增后的代次值。 + */ + async _bumpStaticLockGeneration(warehouseId) { + const { ctx } = this; + const normalizedWarehouseId = Number(warehouseId); + const redis = ctx.app.redis && typeof ctx.app.redis.get === 'function' ? ctx.app.redis.get('cache') : null; + if (redis && typeof redis.incr === 'function') { + try { + const value = await redis.incr(this._staticLockGenerationKey(normalizedWarehouseId)); + return Number(value) || 0; + } catch (error) { + ctx.logger.warn(`[StockCheckStaticLock] 递增锁定代次失败,回退进程内计数 warehouse=${normalizedWarehouseId}: ${error && error.message}`); + } + } + const nextValue = (STATIC_LOCK_GENERATION_LOCAL.get(normalizedWarehouseId) || 0) + 1; + STATIC_LOCK_GENERATION_LOCAL.set(normalizedWarehouseId, nextValue); + return nextValue; + } + + /** + * 删除静态盘点锁定缓存(Redis 与进程内缓存同时清理;下次查询回源重建)。 + * + * @param {number} warehouseId 仓库ID。 + * @return {Promise} 无返回值。 + */ + async clearStaticLockCache(warehouseId) { + const { ctx } = this; + const normalizedWarehouseId = Number(warehouseId); + if (!Number.isInteger(normalizedWarehouseId) || normalizedWarehouseId <= 0) { + return; + } + try { + await ctx.app.delCacheAsync(this._staticLockCacheKey(normalizedWarehouseId)); + } catch (error) { + ctx.logger.warn(`[StockCheckStaticLock] 清除静态锁定缓存失败 warehouse=${normalizedWarehouseId}: ${error && error.message}`); + } + } + + /** + * 判断指定商品当前是否处于静态盘点锁定中(供库存操作前置校验,读缓存)。 + * + * @param {Object} params 查询参数。 + * @param {number} params.warehouseId 仓库ID(由方法层从上下文注入)。 + * @param {number|Array} params.stockId 商品库存ID(单值或数组)。 + * @return {Promise} { locked, locked_stock_ids, rows, cached }; + * locked=true 表示至少有一个商品在锁定集合中;rows 仅返回命中的商品行。 + */ + async isStockStaticLocked(params = {}) { + const { warehouseId, stockId } = params; + + const stockIds = this._normalizeIdList(stockId); + if (stockIds.length === 0) { + throw this.createBusinessError('商品ID不能为空'); + } + + const lockList = await this.staticLockList({ warehouseId }); + const stockIdSet = new Set(stockIds.map(id => Number(id))); + const hitRows = lockList.rows.filter(row => stockIdSet.has(Number(row.stock_id))); + + return { + locked: hitRows.length > 0, + locked_stock_ids: hitRows.map(row => Number(row.stock_id)), + rows: hitRows, + cached: lockList.cached, + }; + } + + /** + * 查询商品是否被静态盘点锁定,并生成可直接返回/抛出的冲突文案(供库存操作前置拦截)。 + * + * @param {Object} params 查询参数。 + * @param {number} params.warehouseId 仓库ID。 + * @param {number|Array} params.stockIds 商品库存ID(单值或数组)。 + * @param {string} [params.actionLabel] 被禁止的操作名(用于文案,如「移库」「分配储位」)。 + * @return {Promise} { locked, rows, message };locked=false 时 rows 为空数组、message 为空串。 + */ + async getStaticLockConflict(params = {}) { + const { warehouseId, stockIds, actionLabel } = params; + + const normalizedStockIds = this._normalizeIdList(stockIds); + if (normalizedStockIds.length === 0) { + return { locked: false, rows: [], message: '' }; + } + + const result = await this.isStockStaticLocked({ warehouseId, stockId: normalizedStockIds }); + if (!result.locked) { + return { locked: false, rows: [], message: '' }; + } + + const actionText = String(actionLabel || '该操作').trim() || '该操作'; + const detailText = result.rows + .map(row => { + const stockText = row.item_code ? `${row.item_code}(${row.stock_id})` : String(row.stock_id); + const checkNos = (Array.isArray(row.check_nos) ? row.check_nos : []).filter(Boolean).join('/'); + return checkNos ? `${stockText} 盘点单 ${checkNos}` : stockText; + }) + .join(';'); + + return { + locked: true, + rows: result.rows, + message: `商品正在静态盘点中,禁止${actionText}:${detailText}`, + }; + } + + /** + * 收集任务商品范围明细覆盖的商品ID(去重升序),用于完成/释放锁定追溯。 + * + * @param {number} checkId 盘点任务ID。 + * @return {Promise>} 商品库存ID列表(升序;库位任务为空数组)。 + */ + async _collectGoodsStockIds(checkId) { + const { ctx } = this; + const detailRows = await ctx.model.StockCheckDetail.findAll({ + where: { check_id: Number(checkId), scope_type: 'goods' }, + attributes: [ 'stock_id' ], + raw: true, + }); + return [ ...new Set(detailRows + .map(row => Number(row.stock_id)) + .filter(stockId => Number.isInteger(stockId) && stockId > 0)) ] + .sort((left, right) => left - right); + } + /** * 拉取盘点明细结果(后台查看明细口径,仅展示盘点前/盘点后明细使用)。 * 任务尚无作业记录(盘点前,如 created/rejected/submitted 待提交状态)时,rows 直接返回 @@ -2541,7 +2951,12 @@ class StockCheckService extends Service { if (!Number.isInteger(checkId) || checkId <= 0) { throw this.createBusinessError('盘点任务ID不能为空'); } - if (!Number.isInteger(detailRowId) || detailRowId <= 0) { + // detail_id 可选:goods 汇总视图行不再带明细ID,允许按 id + stock_id + space_id 反查该商品明细 + let resolvedDetailRowId = Number.isInteger(detailRowId) && detailRowId > 0 ? detailRowId : 0; + const inputStockIdRaw = stockId !== undefined && stockId !== null && stockId !== '' + ? Number(stockId) + : 0; + if (resolvedDetailRowId === 0 && !(Number.isInteger(inputStockIdRaw) && inputStockIdRaw > 0)) { throw this.createBusinessError('盘点明细ID不能为空'); } @@ -2561,11 +2976,38 @@ class StockCheckService extends Service { throw this.createBusinessError(`实盘数量不能超过 ${REPORT_MAX_QUANTITY}`); } - const detail = await ctx.model.StockCheckDetail.findOne({ - where: { id: detailRowId, check_id: checkId, warehouse_id: Number(warehouseId) }, - }); - if (!detail) { - throw this.createBusinessError('盘点明细不存在'); + // 明细定位:传了 detail_id 直接用;未传时按 id + stock_id + space_id 反查该商品的库位明细 + // (goods 汇总视图行不再输出明细ID,前端可只回传商品与库位) + let detail = null; + if (resolvedDetailRowId > 0) { + detail = await ctx.model.StockCheckDetail.findOne({ + where: { id: resolvedDetailRowId, check_id: checkId, warehouse_id: Number(warehouseId) }, + }); + if (!detail) { + throw this.createBusinessError('盘点明细不存在'); + } + } else { + const candidateSpaceId = Number(spaceIdInput); + const detailScope = { + check_id: checkId, + warehouse_id: Number(warehouseId), + stock_id: inputStockIdRaw, + }; + if (Number.isInteger(candidateSpaceId) && candidateSpaceId > 0) { + detail = await ctx.model.StockCheckDetail.findOne({ + where: { ...detailScope, location_id: candidateSpaceId }, + }); + } + if (!detail) { + detail = await ctx.model.StockCheckDetail.findOne({ + where: detailScope, + order: [[ 'id', 'ASC' ]], + }); + } + if (!detail) { + throw this.createBusinessError('盘点明细不存在(该商品不在本任务盘点范围内,或库位盘点任务需传 detail_id)'); + } + resolvedDetailRowId = Number(detail.id); } const scopeType = (detail.scope_type || 'goods') === 'location' ? 'location' : 'goods'; @@ -2714,19 +3156,19 @@ class StockCheckService extends Service { // 空库位标记按(detail_id + is_empty=1 + location_code)应用层查重覆盖更新 const existingRecordWhere = normalizedIsEmpty ? { - detail_id: detailRowId, + detail_id: resolvedDetailRowId, is_empty: true, location_code: locationCode, } : (isUnknownGoods ? { - detail_id: detailRowId, + detail_id: resolvedDetailRowId, stock_id: null, barcode: normalizedBarcode, location_code: locationCode, } : { - detail_id: detailRowId, + detail_id: resolvedDetailRowId, stock_id: normalizedStockId, location_code: locationCode, }); @@ -2764,7 +3206,7 @@ class StockCheckService extends Service { const createdRecord = await ctx.model.StockCheckRecord.create({ check_id: checkId, warehouse_id: Number(warehouseId), - detail_id: detailRowId, + detail_id: resolvedDetailRowId, stock_id: (isUnknownGoods || normalizedIsEmpty) ? null : normalizedStockId, barcode: normalizedBarcode, item_name: normalizedItemName, @@ -2816,11 +3258,11 @@ class StockCheckService extends Service { // 空库位标记与商品记录互斥:确认库位为空后清除该明细下商品记录;上报商品后清除该明细下空标记 if (normalizedIsEmpty) { await ctx.model.StockCheckRecord.destroy({ - where: { detail_id: detailRowId, is_empty: false }, + where: { detail_id: resolvedDetailRowId, is_empty: false }, }); } else { await ctx.model.StockCheckRecord.destroy({ - where: { detail_id: detailRowId, is_empty: true }, + where: { detail_id: resolvedDetailRowId, is_empty: true }, }); } @@ -2849,11 +3291,11 @@ class StockCheckService extends Service { operationCode: 'STOCK_CHECK_REPORT', operationAction: 'UPDATE', changeSummary: normalizedIsEmpty - ? `盘点作业上报:明细 ${detailRowId} 确认库位 ${locationCode || '未指定'} 为空` - : `盘点作业上报:明细 ${detailRowId},库位 ${locationCode || '未指定'},实盘 ${quantityValue}${normalizedBarcode ? `,条码 ${normalizedBarcode}` : ''}(${mode === 'created' ? '新增' : '更新'})`, + ? `盘点作业上报:明细 ${resolvedDetailRowId} 确认库位 ${locationCode || '未指定'} 为空` + : `盘点作业上报:明细 ${resolvedDetailRowId},库位 ${locationCode || '未指定'},实盘 ${quantityValue}${normalizedBarcode ? `,条码 ${normalizedBarcode}` : ''}(${mode === 'created' ? '新增' : '更新'})`, beforeChanges: { check_no: check.check_no, - detail_id: detailRowId, + detail_id: resolvedDetailRowId, scope_type: scopeType, stock_id: normalizedStockId > 0 ? normalizedStockId : null, location_code: locationCode || '', @@ -2876,7 +3318,7 @@ class StockCheckService extends Service { extras: { warehouseId, checkNo: check.check_no, - detailId: detailRowId, + detailId: resolvedDetailRowId, locationCode, locationId: locationId !== null && locationId !== undefined ? Number(locationId) : null, quantity: quantityValue, @@ -2885,14 +3327,14 @@ class StockCheckService extends Service { is_empty: normalizedIsEmpty, mode, message: normalizedIsEmpty - ? `盘点作业上报:明细 ${detailRowId} 确认库位 ${locationCode || '未指定'}${locationId ? `(#${locationId})` : ''} 为空` - : `盘点作业上报:明细 ${detailRowId},库位 ${locationCode || '未指定'}${locationId ? `(#${locationId})` : ''},实盘 ${quantityValue}`, + ? `盘点作业上报:明细 ${resolvedDetailRowId} 确认库位 ${locationCode || '未指定'}${locationId ? `(#${locationId})` : ''} 为空` + : `盘点作业上报:明细 ${resolvedDetailRowId},库位 ${locationCode || '未指定'}${locationId ? `(#${locationId})` : ''},实盘 ${quantityValue}`, }, }); return { record, - detail_id: detailRowId, + detail_id: resolvedDetailRowId, mode, total_items: summary.total_items, checked_items: summary.checked_items, @@ -3021,8 +3463,10 @@ class StockCheckService extends Service { * location=库位结构,以任务库位范围行(scope_type=location)为列表, * 行内挂该库位的盘点作业记录 goods 子列表(已知商品与未知商品均入内, * has_unknown 标记是否含未知商品); - * goods=商品结构,以任务商品范围行(scope_type=goods)为列表,行内挂按库位聚合的作业记录, - * 明盘(mode=open)返回账面快照/已盘合计/差异,盲盘(mode=blind)不返回任何数量字段; + * goods=商品结构,按商品(stock_id)汇总,一个商品一行——同商品的多个库位明细行 + * (scope_type=goods,按「商品+库位」拆行)合并:行内挂跨明细按库位合并的作业记录 + * (locations 每项含该库位明细ID detail_id),明盘(mode=open)返回账面快照合计/已盘合计/差异, + * 盲盘(mode=blind)不返回任何数量字段;逐库位明细/汇总请调用 workDataDetail(id + stock_id); * space=聚合库位列表,以任务商品所在库位为列表(仅按库位拣货顺序 pick_sequence 升序 * 排序,pick_priority/库位 id 不参与,同值保持库位查询顺序),行内挂该库位的任务商品与账面/实盘数量,盲盘不返回数量字段; * 若任务无对应范围行(如 location 视图无库位范围行),rows 返回空数组。 @@ -3050,9 +3494,9 @@ class StockCheckService extends Service { * (location=库位结构/goods=商品结构/space=聚合库位结构);rows 结构按解析后的视图不同: * location 行含 detail_id/location_id/location_code/location_name/status/has_unknown/ * checked_at/checkers/goods(已知商品与未知商品记录均入 goods,未知商品 stock_id=null); - * goods 行含 detail_id/stock_id/item_code/item_name/spec/ - * store_id/store_name/barcode/images/locations(明盘另含 system_quantity/checked_quantity/ - * diff_quantity/is_diff);space 行含 id/space_code/custom_barcode/custom_name/goods。 + * goods 行含 stock_id/item_code/item_name/spec/store_id/store_name/barcode/images/locations + * (明盘另含 system_quantity(账面快照合计)/checked_quantity/diff_quantity/is_diff); + * space 行含 id/space_code/custom_barcode/custom_name/goods。 * @throws {Error} 任务不存在或任务状态非 approved/checking 时抛出业务错误(错误码 400)。 */ async workData(params = {}) { @@ -3079,11 +3523,13 @@ class StockCheckService extends Service { ? 'location' : (goodsViewRequested ? 'goods' : 'space'); + // 静态盘点(is_static=1)账面取明细快照,非静态取当前 wms_storage 账面 + const isStatic = Number(check.is_static) === 1; const allRows = resolvedView === 'location' ? await this._buildLocationWorkRows(warehouseId, checkId) : (resolvedView === 'goods' - ? await this._buildGoodsWorkRows(warehouseId, checkId, check.mode) - : await this._buildSpaceWorkRows(warehouseId, checkId, check.mode)); + ? await this._buildGoodsWorkRows(warehouseId, checkId, check.mode, isStatic) + : await this._buildSpaceWorkRows(warehouseId, checkId, check.mode, isStatic)); // keyword 过滤:仅库位任务(location 视图)启用,按行 location_code/location_name // 模糊匹配(不区分大小写)过滤任务明细后再分页;非库位任务忽略该参数 @@ -3197,7 +3643,12 @@ class StockCheckService extends Service { const normalizedLocationId = Number(locationId); const hasLocationFilter = Number.isInteger(normalizedLocationId) && normalizedLocationId > 0; - const allRows = await this._buildSpaceWorkRows(warehouseId, checkId, check.mode); + const allRows = await this._buildSpaceWorkRows( + warehouseId, + checkId, + check.mode, + Number(check.is_static) === 1 + ); // 库位过滤:传入 location_id 时只保留该库位行 const filteredRows = hasLocationFilter @@ -3219,37 +3670,66 @@ class StockCheckService extends Service { } /** - * 拉取单条盘点明细的作业数据(workData 单行版)。 + * 拉取盘点作业数据明细(单行/商品钻取版)。 * - * 按明细范围类型分流,均返回单行对象(与对应视图单行结构一致): - * - 库位明细(scope_type=location):行结构与 workData location 视图单行一致 + * 两种入参与返回: + * - 库位明细(detail_id,scope_type=location):返回单行,结构与 workData location 视图单行一致 * (detail_id/location_id/location_code/location_name/status/has_unknown/is_empty/ * checked_at/checkers/goods),便于作业端按明细ID刷新单行数据; - * - 商品明细(scope_type=goods):行结构与 workData goods 视图行一致(detail_id/stock_id/ - * item_code/item_name/spec/store_id/store_name/barcode/images/locations; - * 明盘另含 system_quantity/checked_quantity/diff_quantity/is_diff,盲盘不含数量字段)。 + * - 商品(id=盘点任务ID + stock_id,或 detail_id 指向商品范围行):返回该商品的库位分行数据 + + * 汇总数据 { check_id, stock_id, 商品信息, summary, rows }: + * summary 为商品级汇总(明盘含 system_quantity 账面快照合计/checked_quantity 实盘合计/ + * diff_quantity/is_diff;盲盘不含数量字段); + * rows 为该商品每个库位一行(detail_id 该库位明细ID/location_id 与同义 space_id 库位ID/ + * location_code 库位编码,明盘另含 system_quantity 该库位当前账面(可用+锁定)/ + * snapshot_quantity 该库位账面快照/locked_quantity 锁定数量/checked_quantity 该库位实盘/ + * diff_quantity 该库位差异(实盘-快照),另有 checked_at/checker_name/record_ids/images)。 * * @param {Object} params 查询参数。 * @param {number} params.warehouseId 仓库ID(由方法层从上下文注入)。 - * @param {number} params.detailId 盘点明细ID(库位范围行或商品范围行)。 - * @return {Promise} 单行作业数据(结构随明细范围类型与 workData 对应视图单行一致)。 - * @throws {Error} 明细不存在或任务状态非 approved/checking 时抛业务错误(错误码 400)。 + * @param {number} [params.id] 盘点任务ID(商品钻取必传,与 stockId 搭配)。 + * @param {number} [params.stockId] 商品库存ID(wms_stock_warehouse.id,商品钻取必传)。 + * @param {number} [params.detailId] 盘点明细ID(库位明细必传;商品明细可只传本参数,按明细商品钻取)。 + * @return {Promise} 库位明细返回 location 单行;商品返回 { check_id, stock_id, 商品信息, summary, rows }。 + * @throws {Error} 明细/商品不在任务范围内、任务状态非 approved/checking 时抛业务错误(错误码 400)。 */ async workDataDetail(params = {}) { const { ctx } = this; - const { warehouseId, detailId } = params; + const { warehouseId, detailId, id: checkIdInput, stockId } = params; const normalizedDetailId = Number(detailId); - if (!Number.isInteger(normalizedDetailId) || normalizedDetailId <= 0) { - throw this.createBusinessError('盘点明细ID不能为空'); + const normalizedCheckId = Number(checkIdInput); + const normalizedStockId = Number(stockId); + const hasDetailId = Number.isInteger(normalizedDetailId) && normalizedDetailId > 0; + const hasStockScope = Number.isInteger(normalizedCheckId) && normalizedCheckId > 0 + && Number.isInteger(normalizedStockId) && normalizedStockId > 0; + if (!hasDetailId && !hasStockScope) { + throw this.createBusinessError('请提供盘点明细ID(detail_id),或盘点任务ID(id)+商品ID(stock_id)'); } - const detailRow = await ctx.model.StockCheckDetail.findOne({ - where: { id: normalizedDetailId, warehouse_id: Number(warehouseId) }, - raw: true, - }); - if (!detailRow) { - throw this.createBusinessError('盘点明细不存在'); + let detailRow = null; + if (hasDetailId) { + detailRow = await ctx.model.StockCheckDetail.findOne({ + where: { id: normalizedDetailId, warehouse_id: Number(warehouseId) }, + raw: true, + }); + if (!detailRow) { + throw this.createBusinessError('盘点明细不存在'); + } + } else { + // 商品钻取:任务 + 商品 → 该商品的库位明细行(取明细 id 最小的一条定位商品与任务) + detailRow = await ctx.model.StockCheckDetail.findOne({ + where: { + check_id: normalizedCheckId, + warehouse_id: Number(warehouseId), + stock_id: normalizedStockId, + }, + order: [[ 'id', 'ASC' ]], + raw: true, + }); + if (!detailRow) { + throw this.createBusinessError('盘点明细不存在(该商品不在本任务盘点范围内)'); + } } const check = await this._findCheck(warehouseId, Number(detailRow.check_id)); @@ -3262,14 +3742,20 @@ class StockCheckService extends Service { const scopeType = (detailRow.scope_type || 'goods') === 'location' ? 'location' : 'goods'; - // 商品明细:返回 goods 视图单行(与 location 分支结构对称) + // 商品(scope_type=goods):返回该商品的库位分行数据 + 汇总数据 if (scopeType === 'goods') { - const goodsRows = await this._buildGoodsWorkRows(warehouseId, Number(detailRow.check_id), check.mode); - const goodsRow = goodsRows.find(item => Number(item.detail_id) === normalizedDetailId); + const isStatic = Number(check.is_static) === 1; + const goodsRows = await this._buildGoodsWorkRows( + warehouseId, + Number(detailRow.check_id), + check.mode, + isStatic + ); + const goodsRow = goodsRows.find(item => Number(item.stock_id) === Number(detailRow.stock_id)); if (!goodsRow) { throw this.createBusinessError('盘点明细不存在'); } - return goodsRow; + return this._formatGoodsWorkDetail(goodsRow, check.mode, Number(detailRow.check_id)); } // 库位明细:返回 location 视图单行 @@ -3281,6 +3767,73 @@ class StockCheckService extends Service { return row; } + /** + * 将 goods 视图聚合行格式化为商品钻取结果:汇总数据(summary)+ 按库位分行数据(rows)。 + * open(明盘)输出数量字段;blind(盲盘)不返回任何数量字段(仅库位与作业记录信息)。 + * + * @param {Object} goodsRow goods 视图单行(_buildGoodsWorkRows 输出)。 + * @param {string} mode 盘点方式:open=明盘/blind=盲盘。 + * @param {number} checkId 盘点任务ID。 + * @return {Object} { check_id, stock_id, 商品信息, summary, rows }。 + */ + _formatGoodsWorkDetail(goodsRow, mode, checkId) { + const isOpen = mode !== 'blind'; + const locations = Array.isArray(goodsRow.locations) ? goodsRow.locations : []; + const rows = locations.map(location => { + const detailRowId = location && location.detail_id !== undefined ? location.detail_id : null; + const row = { + // 该库位对应的盘点明细ID(商品按库位拆行,可为 null:库位已无明细但有作业记录) + detail_id: detailRowId, + // 库位ID(wms_location_space.id):location_id 与 space_id 同值,可直接回传 stock.check.report + location_id: location ? location.location_id : null, + space_id: location ? location.space_id : null, + location_code: location ? location.location_code : null, + checked_at: location ? location.checked_at : null, + checker_name: location ? location.checker_name : null, + record_ids: location && Array.isArray(location.record_ids) ? location.record_ids : [], + images: location && Array.isArray(location.images) ? location.images : [], + }; + if (isOpen) { + const checkedQuantity = Number(location && location.quantity) || 0; + const snapshotQuantity = Number(location && location.snapshot_quantity) || 0; + // system_quantity 为本次参与差异计算的账面(静态=快照,非静态=当前 storage) + const bookQuantity = Number(location && location.system_quantity) || 0; + row.system_quantity = bookQuantity; + row.storage_quantity = Number(location && location.storage_quantity) || 0; + row.locked_quantity = Number(location && location.locked_quantity) || 0; + row.snapshot_quantity = snapshotQuantity; + row.checked_quantity = checkedQuantity; + row.diff_quantity = checkedQuantity - bookQuantity; + } + return row; + }); + + const detail = { + check_id: Number(checkId) || null, + stock_id: Number(goodsRow.stock_id) || null, + item_code: goodsRow.item_code || null, + item_name: goodsRow.item_name || null, + spec: goodsRow.spec || null, + store_id: goodsRow.store_id !== undefined ? goodsRow.store_id : null, + store_name: goodsRow.store_name || null, + barcode: goodsRow.barcode || null, + images: Array.isArray(goodsRow.images) ? goodsRow.images : [], + // 账面取值来源:静态盘点=明细快照(盘点基准冻结),非静态=当前 wms_storage 账面 + is_static: Number(goodsRow.is_static) === 1 ? 1 : 0, + book_source: goodsRow.book_source === 'snapshot' ? 'snapshot' : 'storage', + rows, + }; + if (isOpen) { + detail.summary = { + system_quantity: Number(goodsRow.system_quantity) || 0, + checked_quantity: Number(goodsRow.checked_quantity) || 0, + diff_quantity: Number(goodsRow.diff_quantity) || 0, + is_diff: Number(goodsRow.is_diff) || 0, + }; + } + return detail; + } + /** * 构建 location 视图行:以任务库位范围行为列表,行内挂该库位的盘点作业记录。 * 已知商品子列表 goods 的商品基础信息(item_code/item_name/条码/图片/货主)批量取自 @@ -3437,7 +3990,11 @@ class StockCheckService extends Service { } /** - * 构建 goods 视图行:以任务商品范围行为列表,行内挂商品所在库位列表(locations)。 + * 构建 goods 视图行:按商品(stock_id)汇总输出,一个商品一行; + * 同商品的库位明细行(scope_type=goods,按「商品+库位」拆行、唯一键 check_id+stock_id+location_id) + * 合并为一行:行级数量跨明细合计(账面快照合计、作业记录按库位合并), + * locations 每项带该库位明细行ID(detail_id)与账面快照(snapshot_quantity,明盘)供逐库位上报/钻取; + * stock_id 为空/异常的明细行无法按商品归并,各自成行。 * locations 为商品所在全部库位(wms_storage 中该商品的 space_id 集合,按拣货路径排序): * 明盘(mode=open)每库位含 system_quantity(该库位账面数量,wms_storage space+stock * SUM(available_quantity+locked_quantity),无库存记录库位为 0)、locked_quantity(该库位锁定数量, @@ -3445,16 +4002,19 @@ class StockCheckService extends Service { * 盲盘(mode=blind)只显示库位(location_code)不含任何数量字段;已盘库位额外含 * checked_at/checker_name/record_ids/images,未盘库位这些字段为 null/空数组; * 商品库存已无记录但已盘的库位(仅记录库位)追加在末尾。 - * 明盘行级返回 system_quantity(账面快照)/checked_quantity(已盘合计)/diff_quantity/is_diff; + * 明盘行级返回 system_quantity(账面快照合计=该商品各库位明细行快照之和)/ + * checked_quantity(已盘合计)/diff_quantity/is_diff; * 商品基础信息批量取自 stockWarehouse.getStockDetails(未命中回退明细商品快照), * 货主名经 _resolveStoreNameMap 解析。 * * @param {number} warehouseId 仓库ID。 * @param {number} checkId 盘点任务ID。 * @param {string} mode 盘点方式:open=明盘/blind=盲盘。 - * @return {Promise>} 商品视图行列表(按明细 id 升序)。 + * @param {boolean} [isStatic=false] 是否静态盘点(is_static=1):true=账面取明细快照, + * false=账面取当前 wms_storage(可用+锁定)。 + * @return {Promise>} 商品视图行列表(按商品首个明细 id 升序)。 */ - async _buildGoodsWorkRows(warehouseId, checkId, mode) { + async _buildGoodsWorkRows(warehouseId, checkId, mode, isStatic = false) { const { ctx } = this; const { Op, fn, col, literal } = ctx.app.Sequelize; @@ -3621,28 +4181,63 @@ class StockCheckService extends Service { recordsByDetail.get(detailId).push(record); } - return detailRows.map(detailRow => { - const detailId = Number(detailRow.id); - const stockId = Number(detailRow.stock_id); - const detailRecords = recordsByDetail.get(detailId) || []; + // 按商品汇总:同商品的库位明细行合并为一组(分组顺序沿用明细 id 升序); + // stock_id 为空/异常的明细行无法按商品归并,各自成组(保持单行输出) + const detailGroups = []; + const groupIndexByStock = new Map(); + for (const detailRow of detailRows) { + const detailStockId = Number(detailRow.stock_id); + const groupKey = Number.isInteger(detailStockId) && detailStockId > 0 + ? `stock_${detailStockId}` + : `detail_${Number(detailRow.id)}`; + if (!groupIndexByStock.has(groupKey)) { + groupIndexByStock.set(groupKey, detailGroups.length); + detailGroups.push([]); + } + detailGroups[groupIndexByStock.get(groupKey)].push(detailRow); + } + + return detailGroups.map(groupRows => { + const firstDetailRow = groupRows[0]; + const stockId = Number(firstDetailRow.stock_id); + // 该商品全部明细的作业记录(明细 id 升序 → 记录 id 升序) + const detailRecords = []; + for (const groupRow of groupRows) { + detailRecords.push(...(recordsByDetail.get(Number(groupRow.id)) || [])); + } + // 库位编码 → 该库位明细行(明细ID + 账面快照):供逐库位钻取/上报回传, + // 同编码多条时取明细 id 最小的一行(正常数据唯一键已保证一个商品一个库位一行) + const detailByLocationCode = new Map(); + for (const groupRow of groupRows) { + const groupRowCode = String(groupRow.location_code || '').trim(); + if (!groupRowCode || detailByLocationCode.has(groupRowCode)) { + continue; + } + detailByLocationCode.set(groupRowCode, { + detail_id: Number(groupRow.id), + snapshot_quantity: Number(groupRow.system_quantity) || 0, + }); + } const stockDetail = stockDetailMap.get(stockId) || {}; const barcodes = Array.isArray(stockDetail.barcodes) ? stockDetail.barcodes : []; const storeId = stockDetail.store_id != null ? Number(stockDetail.store_id) : null; const row = { - detail_id: detailId, stock_id: stockId, - item_code: stockDetail.item_code || detailRow.item_code || null, - item_name: stockDetail.item_name || detailRow.item_name || null, - spec: stockDetail.sku_property || detailRow.spec || null, + item_code: stockDetail.item_code || firstDetailRow.item_code || null, + item_name: stockDetail.item_name || firstDetailRow.item_name || null, + spec: stockDetail.sku_property || firstDetailRow.spec || null, store_id: storeId, store_name: storeNameMap.get(storeId) || null, barcode: (barcodes[0] && barcodes[0].barcode) || null, images: stockDetail.image_url || [], + // 账面取值来源:静态盘点=明细快照(盘点基准冻结),非静态=当前 wms_storage 账面 + is_static: isStatic ? 1 : 0, + book_source: isStatic ? 'snapshot' : 'storage', locations: [], }; if (isOpen) { - row.system_quantity = Number(detailRow.system_quantity) || 0; + row.system_quantity = 0; row.checked_quantity = 0; row.diff_quantity = 0; row.is_diff = 0; @@ -3692,22 +4287,31 @@ class StockCheckService extends Service { const buildLocationItem = (code, group) => { const locationIdValue = (code && spaceIdByCodeMap.get(code)) || (group && group.location_id) || null; + const locationDetail = detailByLocationCode.get(code || '') || null; const locationItem = { // 库位ID(wms_location_space.id):优先有效库位行,其次作业记录回填值; // space_id 供调用方直接回传 stock.check.report(location_id 为兼容别名) location_id: locationIdValue, space_id: locationIdValue, location_code: code || null, + // 该库位对应的盘点明细ID(商品按库位拆行);无明细快照的库位为 null + detail_id: locationDetail ? locationDetail.detail_id : null, checked_at: group ? group.checked_at : null, checker_name: group ? group.checker_name : null, record_ids: group ? group.record_ids : [], images: group ? group.images : [], }; if (isOpen) { - // 明盘:库位账面数量(可用+锁定)、库位锁定数量与库位盘点数量(实盘合计)区分输出 + // 明盘:逐库位账面按任务是否静态取值——静态盘点取该库位明细快照(盘点基准冻结), + // 非静态取当前 wms_storage 账面(可用+锁定);两者同时输出便于对照, + // system_quantity 始终为「本次参与差异计算的账面」 const spaceQuantity = (spaceQuantityByStockMap.get(stockId) || new Map()).get(code || '') || {}; - locationItem.system_quantity = Number(spaceQuantity.system_quantity) || 0; + const storageQuantity = Number(spaceQuantity.system_quantity) || 0; + const snapshotQuantity = locationDetail ? locationDetail.snapshot_quantity : 0; + locationItem.system_quantity = isStatic ? snapshotQuantity : storageQuantity; + locationItem.storage_quantity = storageQuantity; locationItem.locked_quantity = Number(spaceQuantity.locked_quantity) || 0; + locationItem.snapshot_quantity = snapshotQuantity; locationItem.quantity = group ? group.quantity : 0; } return locationItem; @@ -3727,6 +4331,11 @@ class StockCheckService extends Service { } if (isOpen && row.locations.length > 0) { + // 行级账面 = 各库位账面(按静态/非静态口径取值)之和 + row.system_quantity = row.locations.reduce( + (sum, item) => sum + (Number(item.system_quantity) || 0), + 0 + ); row.checked_quantity = row.locations.reduce((sum, item) => sum + (Number(item.quantity) || 0), 0); // 差异仅对存在作业记录的行计算(未盘行差异保持 0,避免误显盘亏) if (detailRecords.length > 0) { @@ -3755,9 +4364,11 @@ class StockCheckService extends Service { * @param {number} warehouseId 仓库ID。 * @param {number} checkId 盘点任务ID。 * @param {string} mode 盘点方式:open=明盘/blind=盲盘。 + * @param {boolean} [isStatic=false] 是否静态盘点(is_static=1):true=账面取明细快照, + * false=账面取当前 wms_storage(可用+锁定)。 * @return {Promise>} 聚合库位视图行列表(按拣货路径排序)。 */ - async _buildSpaceWorkRows(warehouseId, checkId, mode) { + async _buildSpaceWorkRows(warehouseId, checkId, mode, isStatic = false) { const { ctx } = this; const { Op, fn, col, literal } = ctx.app.Sequelize; @@ -4089,8 +4700,13 @@ class StockCheckService extends Service { }; if (isOpen) { const storageQuantity = storageQuantityMap.get(`${spaceId}_${stockId}`) || {}; - item.system_quantity = Number(storageQuantity.system_quantity) || 0; + const liveQuantity = Number(storageQuantity.system_quantity) || 0; + const snapshotQuantity = Number(detailRow.system_quantity) || 0; + // 账面取值:静态盘点=明细快照(盘点基准冻结),非静态=当前 wms_storage 账面 + item.system_quantity = isStatic ? snapshotQuantity : liveQuantity; + item.storage_quantity = liveQuantity; item.locked_quantity = Number(storageQuantity.locked_quantity) || 0; + item.snapshot_quantity = snapshotQuantity; item.checked_quantity = locationRecords.reduce( (sum, record) => sum + (Number(record.quantity) || 0), 0 @@ -4466,7 +5082,9 @@ class StockCheckService extends Service { * @param {Object} params 完成参数。 * @param {number} params.warehouseId 仓库ID(由方法层从上下文注入)。 * @param {number} params.id 盘点任务ID。 - * @return {Promise} { id, status, total_items, checked_items, unchecked_items, diff_items, profit_total, loss_total }。 + * @return {Promise} { id, status, total_items, checked_items, unchecked_items, diff_items, + * profit_total, loss_total, released_stock_ids }(released_stock_ids=本任务覆盖的商品ID, + * 完成即释放静态锁定;库位任务为空数组)。 * @throws {Error} 状态不允许时抛出业务错误(错误码 400)。 */ async finish(params = {}) { @@ -4498,6 +5116,9 @@ class StockCheckService extends Service { const profitTotal = diffSummary.profit_total; const lossTotal = diffSummary.loss_total; + // 完成前先记录本任务覆盖的商品(完成=释放锁定,供响应与日志追溯) + const releasedStockIds = await this._collectGoodsStockIds(checkId); + await check.update({ status: 'completed', end_time: new Date(), @@ -4505,6 +5126,8 @@ class StockCheckService extends Service { checked_items: checkedItems, diff_items: diffItems, }); + // 任务结束:清除静态锁定缓存,释放本任务商品(is_static=1 时其余锁定任务仍保留) + await this.refreshStaticLockCache(warehouseId); // 写入操作日志(失败不影响主流程) await ctx.service.systems.operationLog.createOperationLog({ @@ -4525,7 +5148,8 @@ class StockCheckService extends Service { lossTotal, checkedItems, uncheckedItems, - message: `完成盘点:差异 ${diffItems} 项,盘盈 ${profitTotal},盘亏 ${lossTotal}`, + releasedStockIds, + message: `完成盘点:差异 ${diffItems} 项,盘盈 ${profitTotal},盘亏 ${lossTotal}${releasedStockIds.length > 0 ? `,释放静态锁定商品 ${releasedStockIds.length} 个` : ''}`, }, }); @@ -4538,21 +5162,23 @@ class StockCheckService extends Service { diff_items: diffItems, profit_total: profitTotal, loss_total: lossTotal, + released_stock_ids: releasedStockIds, }; } /** - * 提交审核时刷新商品范围明细行的账面快照(盘点基准)。 - * 商品范围(scope_type=goods)任务在提交审核时把各明细行 system_quantity 刷新为 - * 该库位当时的账面 SUM(available_quantity+locked_quantity)(库存记录不存在时按 0), - * 保证 result/差异对比使用提交时点的账面;明细表本身已按「商品 + 库位」完整记录快照, - * 不额外写主表快照。库位范围(scope_type=location)账面实时查 wms_storage,不处理。 + * 刷新商品范围明细行的账面快照(盘点基准)。 + * 商品范围(scope_type=goods)任务把各明细行 system_quantity 刷新为该库位当时的账面 + * SUM(available_quantity+locked_quantity)(库存记录不存在时按 0): + * - 提交审核时调用(保证 result/差异对比使用提交时点的账面); + * - 审核通过时再次调用(盘点基准以「审核完成=开始盘点」时刻为准,覆盖提交后到达的出入库); + * 库位范围(scope_type=location)账面实时查 wms_storage,不处理。 * * @param {number} checkId 盘点任务ID。 * @param {number} warehouseId 仓库ID。 - * @return {Promise} 无返回值。 + * @return {Promise} 刷新(含值变化)的明细行数。 */ - async _refreshGoodsBookSnapshotOnSubmit(checkId, warehouseId) { + async _refreshGoodsBookSnapshot(checkId, warehouseId) { const { ctx } = this; const { Op, literal } = ctx.app.Sequelize; @@ -4562,7 +5188,7 @@ class StockCheckService extends Service { raw: true, }); if (detailRows.length === 0) { - return; + return 0; } const stockIds = [ ...new Set(detailRows @@ -4594,16 +5220,22 @@ class StockCheckService extends Service { } } - // 逐明细行刷新库位级账面快照(提交时账面,库存记录不存在时按 0) + // 逐明细行刷新库位级账面快照(刷新时点账面,库存记录不存在时按 0) + let refreshedCount = 0; for (const detailRow of detailRows) { const systemQuantity = storageQuantityMap.get( `${Number(detailRow.stock_id)}_${Number(detailRow.location_id)}` ) || 0; + if (Number(detailRow.system_quantity || 0) === systemQuantity) { + continue; + } await ctx.model.StockCheckDetail.update( { system_quantity: systemQuantity }, { where: { id: detailRow.id } } ); + refreshedCount++; } + return refreshedCount; } /** @@ -4655,8 +5287,8 @@ class StockCheckService extends Service { } // 提交审核时刷新商品范围明细行账面快照(提交时点账面=盘点基准, - // 快照失败则提交失败,保证「提交即快照」) - await this._refreshGoodsBookSnapshotOnSubmit(checkId, Number(warehouseId)); + // 快照失败则提交失败,保证「提交即快照」);审核通过时会再次刷新到「开始盘点」时点 + await this._refreshGoodsBookSnapshot(checkId, Number(warehouseId)); await check.update({ status: 'submitted' }); @@ -4712,6 +5344,7 @@ class StockCheckService extends Service { } await check.update({ status: 'cancelled' }); + await this.refreshStaticLockCache(warehouseId); // 写入操作日志(失败不影响主流程) await ctx.service.systems.operationLog.createOperationLog({ @@ -4746,12 +5379,11 @@ class StockCheckService extends Service { * @param {number} params.id 盘点任务ID。 * @param {string} params.action 审核动作:approve=通过,reject=驳回。 * @param {string} [params.reason] 驳回原因(写入备注)。 - * @return {Promise} { id, status }。 + * @return {Promise} { id, status, snapshot_refreshed }(snapshot_refreshed=本次刷新的商品明细快照行数,驳回为 0)。 * @throws {Error} 状态不允许或动作非法时抛出业务错误(错误码 400)。 */ async audit(params = {}) { const { warehouseId, id, action, reason } = params; - const { ctx } = this; const checkId = Number(id); if (!Number.isInteger(checkId) || checkId <= 0) { @@ -4777,14 +5409,57 @@ class StockCheckService extends Service { : check.remark; if (actionValue === 'approve') { + // 审核完成即开始盘点基准:再次刷新商品范围明细快照(覆盖提交后到达的出入库), + // 并失效静态锁定缓存(is_static=1 的任务此刻起进入锁定集合) + const refreshedCount = await this._refreshGoodsBookSnapshot(checkId, Number(warehouseId)); await check.update({ status: 'approved' }); - } else { - await check.update({ - status: 'rejected', - remark: reasonValue, + await this.refreshStaticLockCache(warehouseId); + return await this._writeAuditLogAndResult({ + check, + checkId, + warehouseId, + actionValue, + reasonValue, + refreshedCount, }); } + await check.update({ + status: 'rejected', + remark: reasonValue, + }); + await this.refreshStaticLockCache(warehouseId); + + return await this._writeAuditLogAndResult({ + check, + checkId, + warehouseId, + actionValue, + reasonValue, + refreshedCount: 0, + }); + } + + /** + * 审核完成后写入操作日志并返回审核结果(审计分支共用)。 + * + * @param {Object} params 参数。 + * @param {Object} params.check 盘点主表模型实例。 + * @param {number} params.checkId 盘点任务ID。 + * @param {number} params.warehouseId 仓库ID。 + * @param {string} params.actionValue 审核动作:approve/reject。 + * @param {string} [params.reasonValue] 驳回原因。 + * @param {number} params.refreshedCount 刷新快照的明细行数(驳回为 0)。 + * @return {Promise} { id, status, snapshot_refreshed }。 + */ + async _writeAuditLogAndResult(params = {}) { + const { check, checkId, warehouseId, actionValue, reasonValue, refreshedCount } = params; + const { ctx } = this; + + const refreshedSuffix = actionValue === 'approve' && refreshedCount > 0 + ? `,刷新账面快照 ${refreshedCount} 行` + : ''; + // 写入操作日志(失败不影响主流程) await ctx.service.systems.operationLog.createOperationLog({ businessType: 'stock_check', @@ -4792,7 +5467,7 @@ class StockCheckService extends Service { operationCode: 'STOCK_CHECK_AUDIT', operationAction: 'UPDATE', changeSummary: actionValue === 'approve' - ? `审核通过盘点任务 ${check.check_no}` + ? `审核通过盘点任务 ${check.check_no}${refreshedSuffix}` : `审核驳回盘点任务 ${check.check_no}${reasonValue ? `,原因:${reasonValue}` : ''}`, operator: { id: ctx.user?.employees_id || ctx.user?.id || '', @@ -4803,8 +5478,9 @@ class StockCheckService extends Service { checkNo: check.check_no, action: actionValue, reason: actionValue === 'reject' ? reasonValue : '', + snapshotRefreshed: refreshedCount, message: actionValue === 'approve' - ? `审核通过盘点任务 ${check.check_no}` + ? `审核通过盘点任务 ${check.check_no}${refreshedSuffix}` : `审核驳回盘点任务 ${check.check_no}${reasonValue ? `,原因:${reasonValue}` : ''}`, }, }); @@ -4812,6 +5488,7 @@ class StockCheckService extends Service { return { id: checkId, status: actionValue === 'approve' ? 'approved' : 'rejected', + snapshot_refreshed: refreshedCount, }; } @@ -4887,6 +5564,7 @@ class StockCheckService extends Service { transaction, }); }); + await this.refreshStaticLockCache(normalizedWarehouseId); } // 事务提交后写入操作日志(不随事务回滚残留,失败不影响主流程) diff --git a/app/service/systems/storage/inventory.js b/app/service/systems/storage/inventory.js index c81b000..d16d8b9 100644 --- a/app/service/systems/storage/inventory.js +++ b/app/service/systems/storage/inventory.js @@ -305,6 +305,75 @@ function parseStorageDateInput(value) { class InventoryService extends Service { + /** + * 静态盘点锁定校验(移库等库存操作前置拦截)。 + * 商品若处于静态盘点锁定中(stock_check.is_static=1 且任务 approved/checking),返回冲突文案; + * 若 stockCheck 服务不可用(单测桩等)则视为未锁定,不阻断既有流程。 + * + * @param {number} warehouseId 仓库ID。 + * @param {Array|number} stockIds 商品库存ID(单值或数组)。 + * @param {string} actionLabel 被禁止的操作名(文案用)。 + * @return {Promise<{locked: boolean, message: string, rows: Array}>} 锁定冲突信息。 + */ + async _getStaticLockConflict(warehouseId, stockIds, actionLabel) { + const { ctx } = this; + const stockCheckService = ctx && ctx.service && ctx.service.systems && ctx.service.systems.stockCheck; + if (!stockCheckService || typeof stockCheckService.getStaticLockConflict !== 'function') { + return { locked: false, message: '', rows: [] }; + } + const normalizedWarehouseId = Number(warehouseId) || 0; + if (normalizedWarehouseId <= 0) { + return { locked: false, message: '', rows: [] }; + } + try { + return await stockCheckService.getStaticLockConflict({ + warehouseId: normalizedWarehouseId, + stockIds, + actionLabel, + }); + } catch (error) { + // 锁定查询失败不阻断库存主流程(缓存/DB 异常时按未锁定处理),仅记录告警 + if (ctx.logger && typeof ctx.logger.warn === 'function') { + ctx.logger.warn(`[InventoryStaticLock] 查询静态盘点锁定失败 action=${actionLabel}: ${error && error.message}`); + } + return { locked: false, message: '', rows: [] }; + } + } + + /** + * 计算单条库存记录的可用数量,口径与 `updateQuantity` 保持一致: + * `available = quantity - locked_quantity - intercept_locked_quantity`。 + * + * 同时与库内 `available_quantity` 字段取较小值:`available_quantity` 为页面展示口径, + * 任一字段显示为 0(例如被拦截锁定)时都不允许移库,避免把锁定/拦截锁定库存移走。 + * + * @param {Object} record wms_storage 记录 + * @return {number} 可用数量(不小于 0) + */ + _resolveAvailableQuantity(record) { + const quantity = Number(record?.quantity || 0); + const lockedQuantity = Number(record?.locked_quantity || 0); + const interceptLockedQuantity = Number(record?.intercept_locked_quantity || 0); + const physicalAvailable = quantity - lockedQuantity - interceptLockedQuantity; + const storedAvailable = Number(record?.available_quantity); + const available = Number.isFinite(storedAvailable) + ? Math.min(physicalAvailable, storedAvailable) + : physicalAvailable; + return Math.max(available, 0); + } + + /** + * 计算单条库存记录中不可移库的数量(锁定 + 拦截锁定)。 + * + * @param {Object} record wms_storage 记录 + * @return {number} 锁定与拦截锁定数量之和 + */ + _resolveLockedQuantity(record) { + const lockedQuantity = Number(record?.locked_quantity || 0); + const interceptLockedQuantity = Number(record?.intercept_locked_quantity || 0); + return lockedQuantity + interceptLockedQuantity; + } + /** * 写入移库双向库位流水(移库出/移库入)。 * @@ -445,6 +514,13 @@ class InventoryService extends Service { const warehouseId = srcRecord.warehouse_id; + // 静态盘点锁定校验:商品在静态盘点中禁止移库 + const lockConflict = await this._getStaticLockConflict(warehouseId, [ srcRecord.stock_id ], '移库'); + if (lockConflict.locked) { + await transaction.rollback(); + return { code: 400, message: lockConflict.message, data: null }; + } + const stockWarehouseSnapshot = await ctx.model.StockWarehouse.findOne({ where: { id: srcRecord.stock_id }, attributes: [ 'id', 'quantity', 'locked_quantity' ], @@ -484,12 +560,20 @@ class InventoryService extends Service { } // ────────── 5. 处理移库 ────────── - const availableQty = srcRecord.quantity - srcRecord.locked_quantity; + const availableQty = this._resolveAvailableQuantity(srcRecord); const transferQty = (data.quantity !== undefined && data.quantity !== null) ? Number(data.quantity) : availableQty; // 校验移库数量 + if (availableQty <= 0) { + await transaction.rollback(); + return { + code: 400, + message: `库存记录 ${storageId} 可用数量为 0(锁定 ${Number(srcRecord.locked_quantity) || 0}、拦截锁定 ${Number(srcRecord.intercept_locked_quantity) || 0}),不可移库`, + data: null, + }; + } if (transferQty > availableQty) { await transaction.rollback(); return { @@ -817,6 +901,15 @@ class InventoryService extends Service { * @param {number} data.target_space_id 目标库位ID(必填) * @param {number} data.quantity 移库数量(必填) * @return {Promise} code/data/message 结构 + * + * 说明: + * 1) 可用量口径与 `updateQuantity` 一致:`quantity - locked_quantity - intercept_locked_quantity`, + * 并与库内 `available_quantity` 取较小值;锁定/拦截锁定(`available_quantity=0`)的记录一律不参与移库; + * 2) 只按请求数量移库(不足整条时按数量拆分),不会清空库位;目标库位已有同批次同类型记录时合并; + * 3) 循环结束后复核实际移库量,未移满请求数量(并发改动、可用量不足等)时整单回滚并返回 409, + * 不会出现"提示成功但少移"的情况;成功时返回真实移库数量 `transfer_quantity` 与 + * 移库后原库位该商品剩余可用量 `remaining_quantity`、剩余锁定/拦截锁定数量 + * `remaining_locked_quantity`(并发写入原库位的新记录不会被本次移库带走)。 */ async transferByProduct(data = {}) { const { ctx, app } = this; @@ -895,7 +988,21 @@ class InventoryService extends Service { return { code: 404, message: `原库位 ${spaceId} 下未找到商品 ${stockId} 的库存记录`, data: null }; } - const totalAvailable = srcRecords.reduce((sum, r) => sum + (r.quantity - r.locked_quantity), 0); + // 静态盘点锁定校验:商品在静态盘点中禁止移库 + const lockConflict = await this._getStaticLockConflict( + Number(srcRecords[0].warehouse_id) || 0, + [ stockId ], + '移库' + ); + if (lockConflict.locked) { + await transaction.rollback(); + return { code: 400, message: lockConflict.message, data: null }; + } + + const totalAvailable = srcRecords.reduce( + (sum, r) => sum + this._resolveAvailableQuantity(r), + 0 + ); if (quantity > totalAvailable) { await transaction.rollback(); return { @@ -965,7 +1072,7 @@ class InventoryService extends Service { for (const srcRecord of srcRecords) { if (remainingQty <= 0) break; - const available = srcRecord.quantity - srcRecord.locked_quantity; + const available = this._resolveAvailableQuantity(srcRecord); const toTransfer = Math.min(available, remainingQty); if (toTransfer <= 0) continue; @@ -1083,6 +1190,53 @@ class InventoryService extends Service { remainingQty -= toTransfer; } + // ── 复核实际移库数量:若循环因记录被并发改动/可用量不足而提前结束,整单回滚,避免"提示成功但少移" ── + if (remainingQty > 0) { + await transaction.rollback(); + ctx.logger.warn('[inventory.transferByProduct] 实际移库数量不足,已回滚', { + space_id: spaceId, + stock_id: stockId, + target_space_id: targetSpaceId, + request_quantity: quantity, + transferred_quantity: quantity - remainingQty, + remaining_quantity: remainingQty, + available_snapshot: totalAvailable, + }); + return { + code: 409, + message: `可用库存不足:请求移库 ${quantity},实际只移了 ${quantity - remainingQty},剩余 ${remainingQty} 未移库,请刷新库存后重试`, + data: { + space_id: spaceId, + stock_id: stockId, + target_space_id: targetSpaceId, + transfer_quantity: 0, + remaining_quantity: remainingQty, + status: 'rolled_back', + }, + }; + } + + const transferredQuantity = quantity - remainingQty; + + // ── 复核原库位剩余可用量:并发写入的新记录不会被本次移库带走,需明确回给调用方 ── + const remainRows = await ctx.model.Storage.findAll({ + where: { + space_id: spaceId, + stock_id: stockId, + is_enabled: 1, + delete_at: null, + }, + transaction, + }); + const remainingQuantity = remainRows.reduce( + (sum, r) => sum + this._resolveAvailableQuantity(r), + 0 + ); + const remainingLockedQuantity = remainRows.reduce( + (sum, r) => sum + this._resolveLockedQuantity(r), + 0 + ); + // ── 计算 SKU 维度统计变化 ── const remainingSrcSku = await ctx.model.Storage.count({ where: { @@ -1117,7 +1271,9 @@ class InventoryService extends Service { space_id: spaceId, stock_id: stockId, target_space_id: targetSpaceId, - transfer_quantity: quantity, + transfer_quantity: transferredQuantity, + remaining_quantity: remainingQuantity, + remaining_locked_quantity: remainingLockedQuantity, affected_storage_count: affectedCount, }, beforeChanges: { @@ -1128,7 +1284,7 @@ class InventoryService extends Service { }, afterChanges: { target_space_id: targetSpaceId, - transfer_quantity: quantity, + transfer_quantity: transferredQuantity, affected_storage_count: affectedCount, }, }); @@ -1167,7 +1323,9 @@ class InventoryService extends Service { space_id: spaceId, stock_id: stockId, target_space_id: targetSpaceId, - transfer_quantity: quantity, + transfer_quantity: transferredQuantity, + remaining_quantity: remainingQuantity, + remaining_locked_quantity: remainingLockedQuantity, affected_storage_count: affectedCount, }); @@ -1178,7 +1336,9 @@ class InventoryService extends Service { space_id: spaceId, stock_id: stockId, target_space_id: targetSpaceId, - transfer_quantity: quantity, + transfer_quantity: transferredQuantity, + remaining_quantity: remainingQuantity, + remaining_locked_quantity: remainingLockedQuantity, affected_storage_count: affectedCount, warehouse_id: warehouseId, }, diff --git a/database/migrations/20261028010000-add-is-static-to-stock-check.js b/database/migrations/20261028010000-add-is-static-to-stock-check.js new file mode 100644 index 0000000..8869cd2 --- /dev/null +++ b/database/migrations/20261028010000-add-is-static-to-stock-check.js @@ -0,0 +1,25 @@ +'use strict'; + +/** + * 库存盘点主表新增「是否静态盘点」标记: + * + * wms_stock_check 新增 is_static(TINYINT(1) NOT NULL DEFAULT 0): + * - 1 = 静态盘点(由静态盘点定式 pattern=static 创建,或创建任务时显式开启); + * - 0 = 普通盘点(存量数据默认值即 0,无需回填); + * - 纯标记字段,不参与盘点流程判定(不改变模式/状态机/差异口径)。 + */ + +const TABLE_NAME = 'wms_stock_check'; + +module.exports = { + up: async queryInterface => { + await queryInterface.sequelize.query(` + ALTER TABLE \`${TABLE_NAME}\` + ADD COLUMN \`is_static\` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否静态盘点(1=静态盘点(静态定式创建或创建时开启),0=普通盘点)' AFTER \`store_id\` + `); + }, + + down: async queryInterface => { + await queryInterface.removeColumn(TABLE_NAME, 'is_static'); + }, +}; diff --git a/methods/changes/system.json b/methods/changes/system.json index 73a3634..eb637a2 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,210 @@ [ + { + "version": "0.3.318", + "date": "2026-10-28", + "type": "updated", + "summary": "盘点作业数据账面取值按任务 is_static 区分:stock.check.workData(goods/space 视图)与 stock.check.workDataDetail(商品钻取)对静态盘点取明细快照、对普通盘点取当前 wms_storage 账面;新增 storage_quantity / is_static / book_source 字段。", + "methods": [ + "stock.check.workData", + "stock.check.workDataDetail" + ], + "notes": [ + "背景:静态盘点(is_static=1)在审核完成时会冻结账面基准(刷新明细 system_quantity 快照),盘点期间不允许出入库/移库;普通盘点则希望看到「当前账面」用于实时对比。原实现两种任务都混用了快照与 storage(goods 视图行级取快照、locations 取 storage),口径不一致。", + "现口径:system_quantity = 本次参与差异计算的账面——is_static=1 → 该库位明细 system_quantity(快照);is_static=0 → wms_storage 该库位 SUM(available_quantity+locked_quantity)。行级(goods 视图行 / workDataDetail summary)为各库位账面之和;diff_quantity 一律 = 实盘 - system_quantity。", + "新增字段:goods 视图行与 location item 增加 is_static / book_source(snapshot|storage)/ storage_quantity(当前 storage 账面),snapshot_quantity 继续输出明细快照;space 视图行内 goods 增加 storage_quantity / snapshot_quantity;workDataDetail 顶层增加 is_static / book_source,rows[] 增加 storage_quantity。", + "兼容性:system_quantity 语义由「快照或 storage(视视图而定)」收紧为「按 is_static 取值」;普通盘点任务的 goods 视图行级账面可能从快照变为当前 storage(有出入库时数值不同),前端如需要基准值请改读 snapshot_quantity。", + "未涉及:stock.check.result / finish / export 的差异汇总仍按「商品行快照、库位行 storage」的既有口径,本次未改;如需与两个作业数据接口完全对齐可另行确认。", + "测试:test/app/service/systems/stock_check.test.js 新增「账面取值按任务静态标记」用例——审核后人为给该库位 +7,静态任务断言 row/locations/summary system_quantity == 快照且 storage_quantity == 快照+7、差异按快照算;非静态任务断言 system_quantity == 快照+7 且差异按当前账面算;goods 视图、space 视图、workDataDetail 三处交叉验证;全量 255 用例通过、ESLint 0 错误。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.workData(rows.description 商品/space 视图账面口径 + notes)、stock.check.workDataDetail(data.description + notes);根版本 0.3.317 → 0.3.318、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位)。", + "代码依据:app/service/systems/stock_check.js#workData/#workDataDetail/#_buildGoodsWorkRows/#_buildSpaceWorkRows/#_formatGoodsWorkDetail。" + ] + }, + { + "version": "0.3.317", + "date": "2026-10-28", + "type": "updated", + "summary": "分配储位命中静态盘点锁定改为「订单级失败」:与库存不足同流程(该订单 storage_status=error + order_flag 静态盘点锁定原因),同批次其它订单继续分配,接口返回 200 并通过 shortage_order_ids/shortage_messages 体现。", + "methods": [ + "order.pendingOrder.allocateStorage", + "order.wave.batchAllocateStorage" + ], + "notes": [ + "修正原因:储位分配支持批量订单(order_ids 数组,波次/待处理订单均走同一入口),0.3.316 的「整单 400」会把同批次未锁定订单一并打断,与既有「库存不足」的静默跳过口径不一致,前端也无法区分哪些订单失败。", + "现行为:命中静态盘点锁定的商品行在明细循环中直接跳过(不查可用储位、不加锁、不写 picking 行);订单级 finalShortageMessage 追加「静态盘点锁定:sku(x) 盘点单 PDxxx」,走与缺货完全相同的收尾——回滚该订单已锁定库存、置 storage_status=error、step=异常、order_flag=原因,并进入 orderResults(status=error)。", + "响应:接口整体 200(除非仓库上下文/订单为空等参数错误);shortage_order_ids 含命中锁定的订单,shortage_messages 含静态盘点锁定文案与盘点单号;orders 中该订单 status=error;allocated_order_ids 仅含成功订单。", + "与移库的区别:移库(storage.inventory.transferLocation/transferByProduct)是单条/单商品同步操作,仍保持 400 直接失败。", + "测试:test/app/service/systems/static_lock_guard.test.js 改为批量口径——两个订单(1 命中锁定、2 正常)断言 code=200、shortage_order_ids=[1]、allocated_order_ids=[2]、锁定订单 order_flag 含静态盘点锁定、仅未锁定商品被加锁(lockCalls 仅 501/3)、picking 仅 1 行;另加「全部订单命中锁定仍返回 200、无加锁、事务正常提交」;5 用例通过、ESLint 0 错误。", + "文档变更范围:methods/system.json 的 order.pendingOrder 分组更新 order.pendingOrder.allocateStorage(description 改为订单级失败、移除静态盘点 400 错误项、notes 补充)、order.wave 分组更新 order.wave.batchAllocateStorage(notes);根版本 0.3.316 → 0.3.317、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位)。", + "代码依据:app/service/systems/order_storage_allocation.js#allocatePicking、app/service/systems/stock_check.js#getStaticLockConflict。" + ] + }, + { + "version": "0.3.316", + "date": "2026-10-28", + "type": "updated", + "summary": "静态盘点锁定拦截库存操作:分配储位(order.pendingOrder.allocateStorage / order.wave.batchAllocateStorage)与移库(storage.inventory.transferLocation / transferByProduct)在商品处于静态盘点锁定中时直接失败(400),返回冲突商品与来源盘点单号。", + "methods": [ + "order.pendingOrder.allocateStorage", + "order.wave.batchAllocateStorage", + "storage.inventory.transferLocation", + "storage.inventory.transferByProduct" + ], + "notes": [ + "需求:静态盘点(is_static=1,审核完成后锁定)期间,商品库存不允许被分配储位/移库,否则盘点实盘与账面基准错位;要求相关操作直接失败并给出明确原因。", + "判定口径:复用 stock_check.staticLockList(按仓库缓存,TTL 300 秒 + 状态流转立即重建 + 代次防脏读)——is_static=1 且任务状态 approved/checking 的商品为锁定;审核完成即锁、完成/取消即释放。", + "新增业务方法 stock_check.getStaticLockConflict({ warehouseId, stockIds, actionLabel }):返回 { locked, rows, message },message 形如「商品正在静态盘点中,禁止移库:编码(库存ID) 盘点单 PDxxxx」,供库存操作直接返回/抛出(systemMethods 未暴露,内部调用)。", + "分配储位:orderStorageAllocation.allocatePicking 在归集订单明细 stock_id 后、查询可用储位库存之前校验,命中即回滚事务并返回 400 + data.locked_stock_ids/locked_items;allocateStorage 为其兼容入口,待处理订单分配、波次分配等内部调用全部生效。", + "移库:storage.inventory.transferLocation(按库存记录)与 transferByProduct(按库位+商品)在锁定/读取原库存记录后校验 stock_id,命中即回滚并返回 400;未命中时行为与之前完全一致。", + "降级策略:锁定查询异常(缓存/数据库故障)时按「未锁定」放行并写 warn 日志,避免因盘点缓存故障阻断出入库主流程;如需强一致可改为失败即拒绝。", + "测试:新增 test/app/service/systems/static_lock_guard.test.js(4 个用例:transferLocation/transferByProduct 命中锁定 400+回滚+不写库存、未锁定时走原有可用量校验、allocatePicking 命中锁定 400+回滚+未查询储位库存);stock_check.test.js 新增 getStaticLockConflict 文案与空入参用例;相关套件 258 用例通过、ESLint 0 错误。", + "文档变更范围:methods/system.json 更新 storage.inventory.transferLocation、storage.inventory.transferByProduct、order.pendingOrder.allocateStorage(description/errors/notes)与 order.wave.batchAllocateStorage(notes);根版本 0.3.315 → 0.3.316、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位)。", + "代码依据:app/service/systems/stock_check.js#getStaticLockConflict/#isStockStaticLocked、app/service/systems/storage/inventory.js#transferLocation/#transferByProduct/#_getStaticLockConflict、app/service/systems/order_storage_allocation.js#allocatePicking。" + ] + }, + { + "version": "0.3.315", + "date": "2026-10-28", + "type": "updated", + "summary": "静态盘点锁定缓存增加防脏读机制:状态流转(审核/完成/取消/批量删除)先递增锁定代次再重建缓存,回源前后代次不一致则放弃写缓存(响应 cache_skipped=true),杜绝旧快照覆盖新缓存的脏读。", + "methods": [ + "stock.check.staticLockList", + "stock.check.audit", + "stock.check.finish" + ], + "notes": [ + "问题:原实现为「状态更新 → 重建缓存(查询后写回)」,若两个流转并发(如审核 A 与完成 B),B 的重建可能先写入新快照,A 的旧快照随后覆盖 → 最长 300 秒脏读(锁定集合与库内状态不符)。", + "方案(乐观锁/代次):新增代次键 `stock_check:static_lock_gen:{warehouseId}`,Redis 用 INCR 原子递增,Redis 不可用时退化为进程内计数;所有状态流转统一走 refreshStaticLockCache:递增代次 → 回源查询 → 写缓存;_loadStaticLockCache 在查询前后各读一次代次,不一致则判定为并发流转,跳过写缓存并清除缓存(返回 cache_skipped=true)。", + "正确性:① 流转先提交数据库、再递增代次,故代次变化一定意味数据库已变;② 查询前读到的代次若在查询后被改,旧快照不会落盘;③ 未发生流转时的回源之间结果等价,覆盖无影响;④ 读取侧(staticLockList 缓存命中的分支)不受影响,缓存为空时回源保证最终一致。", + "审核路径:audit(approve) → 刷新明细快照 → 更新状态 → refreshStaticLockCache(递增代次 + 重建),接口返回时缓存已包含新任务且无脏读窗口;reject 同理(重建后移除该任务)。", + "性能:每次流转多 2 次 Redis 读 + 1 次 INCR(本地降级为内存操作),回源仍是 2 条 SQL;不影响常规查询(命中缓存时无额外开销)。", + "测试:test/app/service/systems/stock_check.test.js 新增「防脏读:回源期间发生状态流转时不写入旧快照」用例——在 _queryStaticLockRows 内递增代次模拟并发流转,断言 cache_skipped=true 且缓存未被写入,并校验 refreshStaticLockCache 会递增代次;全量 253 用例通过、ESLint 0 错误。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.staticLockList(新增 cache_skipped 响应字段 + 缓存设计/防脏读 notes)、stock.check.audit 与 stock.check.finish(notes 各追加代次说明);根版本 0.3.314 → 0.3.315、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位)。", + "代码依据:app/service/systems/stock_check.js#refreshStaticLockCache/#_loadStaticLockCache/#_readStaticLockGeneration/#_bumpStaticLockGeneration/#staticLockList。" + ] + }, + { + "version": "0.3.314", + "date": "2026-10-28", + "type": "updated", + "summary": "静态盘点锁定缓存策略加固:状态流转(审核/完成/取消/批量删除)由「删除缓存」改为「立即重建缓存」,消除审核后仍读到旧缓存的空窗;空集合也缓存(不穿透)、并发未命中用进程内 singleflight 去重(不击穿);TTL 仍为 300 秒兜底。", + "methods": [ + "stock.check.staticLockList" + ], + "notes": [ + "缓存时长:TTL 300 秒(STATIC_LOCK_CACHE_TTL_SECONDS),仅作兜底;正常路径由状态流转触发重建,不依赖 TTL 到期。", + "是否穿透:不会。回源结果(包括 rows 为空、stock_ids=[] 的空集合)都会写入缓存,因此「当前没有锁定商品」的仓库也不会每次查库;命中空缓存时返回 cached=true、total=0。", + "是否击穿:同一进程内对同一仓库的并发未命中通过 STATIC_LOCK_INFLIGHT(Map)合并为一次回源,其余请求复用同一结果;跨实例的极短并发仍可能各自回源一次(2 条 SQL,成本低),数据结果一致。", + "新审核是否清缓存:audit(approve) 在状态更新后调用 refreshStaticLockCache,回源并写回缓存(不是只删除),因此审核接口返回时缓存已包含新任务;reject 同样重建(移除该任务)。finish/cancel/batchDelete 亦为重建(移除对应任务,其它任务仍保留)。", + "窗口评估:① 审核前查询到「未锁定」属于正确语义(审核未生效);② 审核接口返回后不存在旧缓存窗口;③ 若重建失败(Redis 异常等)会降级删除缓存并在日志留 warn,下一次查询回源,最坏 300 秒自愈;④ 仅 Redis 整体不可用时多实例的进程内缓存可能短暂不一致(各自最长 300 秒),该场景建议库存操作按 fail-safe(保守判定为锁定)处理。", + "测试:test/app/service/systems/stock_check.test.js 调整/新增——审核后缓存已重建且查询命中(cached=true)、完成后重建缓存不包含该任务、取消后重建不包含该任务、空仓库集合缓存(首查回源/二次命中)、5 个并发未命中结果一致且均 cached=false、forceRefresh 强制回源;全量 252 用例通过、ESLint 0 错误。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.staticLockList(cached 字段说明 + 缓存设计 notes + 本次策略答疑);根版本 0.3.313 → 0.3.314、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", + "代码依据:app/service/systems/stock_check.js#staticLockList/#_readStaticLockCache/#_loadStaticLockCache/#_queryStaticLockRows/#refreshStaticLockCache/#clearStaticLockCache。" + ] + }, + { + "version": "0.3.313", + "date": "2026-10-28", + "type": "updated", + "summary": "库存盘点完成(stock.check.finish)立即释放静态盘点锁定:清除仓库级锁定缓存并返回 released_stock_ids(本任务覆盖的商品ID),同一商品若仍被其它静态任务覆盖则继续锁定。", + "methods": [ + "stock.check.finish" + ], + "notes": [ + "需求:盘点完成时商品必须立刻解除锁定,不能等到缓存 TTL(300 秒)自然过期,否则完成后的出入库仍会被 staticLockList / isStockStaticLocked 判为锁定中。", + "实现:finish 在状态置 completed 后调用 clearStaticLockCache(warehouseId) 删除 `stock_check:static_lock:{warehouseId}`(Redis 与进程内缓存同时清理,失败仅 warn 日志,靠 TTL 兜底);并在状态更新前用 _collectGoodsStockIds 记录本任务商品明细覆盖的 stock_id,随响应 released_stock_ids 返回、随操作日志 extras.releasedStockIds 落库,便于追溯「哪张单释放了哪些商品」。", + "多任务叠加:锁定集合是「全部 approved/checking 静态任务的并集」,完成其中一张单只会移除该单贡献的商品;若商品仍被其它静态任务覆盖,缓存回源后依旧锁定(正确行为)。", + "其它释放路径:cancel(取消)与 batchDelete(作废删除)同样会清除缓存;audit(approve/reject)清除缓存使锁定集合及时更新;report 仅 approved→checking 流转,不改变锁定集合、不失效。", + "测试:test/app/service/systems/stock_check.test.js 新增「完成盘点立即释放锁定」用例——构造独有商品 → 审核通过后 isStockStaticLocked=true → finish 返回 released_stock_ids=[该商品] 且缓存已清 → isStockStaticLocked=false(回源);全量 251 用例通过、ESLint 0 错误。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.finish(响应新增 released_stock_ids、notes 补充释放口径);根版本 0.3.312 → 0.3.313、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", + "代码依据:app/service/systems/stock_check.js#finish/#_collectGoodsStockIds/#clearStaticLockCache、app/service/systemMethods/stock/check.js#finish、app/extend/application.js#delCacheAsync。" + ] + }, + { + "version": "0.3.312", + "date": "2026-10-28", + "type": "updated", + "summary": "库存盘点新增公共查询 stock.check.staticLockList(静态盘点锁定中的商品清单,按仓库缓存,供库存操作前置判断);stock.check.audit 审核通过时刷新商品明细账面快照(快照基准以「审核完成=开始盘点」时点为准)并返回 snapshot_refreshed,同时失效/进入静态锁定缓存。", + "methods": [ + "stock.check.staticLockList", + "stock.check.audit", + "stock.check.submit" + ], + "notes": [ + "新增方法 stock.check.staticLockList:返回 is_static=1 且状态为 approved/checking 的任务所覆盖的商品 stock_id 集合(rows 附带来源任务ID/单号/库位编码),供出入库、移库、拣货等库存操作判断商品是否被静态盘点锁定;库位盘点任务 is_static 恒为 0,不参与锁定。", + "锁定时机:审核完成(approved)即开始锁定、盘点作业中(checking)持续锁定;提交审核前不锁定;completed/cancelled/rejected 解锁。", + "缓存:键 `stock_check:static_lock:{warehouseId}`,TTL 300 秒,走 app.setCacheAsync/getCacheAsync(Redis 优先、异常降级进程内缓存);audit/finish/cancel/batchDelete 主动失效;响应含 cached(是否命中)与 updated_at(缓存生成时间)。", + "内部接口 isStockStaticLocked({ warehouseId, stockId }):读同一份缓存做单/多商品命中判断,返回 { locked, locked_stock_ids, rows, cached },供库存模块直接调用(systemMethods 层未暴露)。", + "audit 刷新快照:approve 时把 scope_type=goods 明细行 system_quantity 刷新为该库位当前账面 SUM(available_quantity+locked_quantity)(仅统计启用存储,无记录按 0),覆盖「提交审核 → 审核完成」之间发生的出入库,保证账面基准=开始盘点时点;返回 snapshot_refreshed=本次刷新的明细行数(值无变化不计)。submit 的提交时刷新逻辑不变,两者叠加后以审核时点为准。", + "测试:test/app/service/systems/stock_check.test.js 新增「staticLockList 静态盘点锁定商品(公共查询 + 缓存 + 审核刷新快照)」5 个用例——锁定口径(仅 approved/checking、submitted 与非静态任务不计入)、缓存命中与 audit/finish/cancel 主动失效、isStockStaticLocked 单商品判断与参数校验、审核刷新快照(提交后库存 +5,审核后快照等于审核时点账面,并回滚人为变更)、方法层仓库注入与 cached 透出;全量 250 用例通过、ESLint 0 错误。", + "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.staticLockList 一条(共 26 条),并更新 stock.check.audit(响应新增 snapshot_refreshed、notes 补充刷新口径与缓存失效)与 stock.check.submit(notes 补充审核再刷新说明);根版本 0.3.311 → 0.3.312、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位)。", + "代码依据:app/service/systems/stock_check.js#staticLockList/#isStockStaticLocked/#clearStaticLockCache/#_refreshGoodsBookSnapshot/#audit、app/service/systemMethods/stock/check.js#staticLockList、app/extend/application.js#setCacheAsync/#getCacheAsync/#delCacheAsync。" + ] + }, + { + "version": "0.3.311", + "date": "2026-10-28", + "type": "updated", + "summary": "库存盘点 is_static(是否静态盘点)口径收窄:仅商品盘点(type=store/goods)有效,按库位盘点(type=location)一律为 0(create 传入 1/true 也忽略),静态定式(pattern=static)仅商品类任务自动置 1。", + "methods": [ + "stock.check.create", + "stock.check.patternCreate", + "stock.check.list", + "stock.check.detail" + ], + "notes": [ + "口径说明:静态盘点针对「长期停收停发商品」,只对商品盘点(type=store/goods)有意义;库位盘点是按库位清点全部商品,不存在静态商品概念,因此 is_static 恒为 0,避免前端误把全仓库位盘点标成静态。", + "create(本次修正):normalizedIsStatic = (type === 'location') ? 0 : (requested ? 1 : 0)——库位盘点即使传 is_static=1/true 也落库 0 且不报错(保持向后兼容、不新增 400);商品盘点沿用原归一化规则(true/'true'/1/'1' 记为 1,其余 0)。", + "patternCreate(本次修正):is_static = (pattern.id === 'static' && pattern.type !== 'location') ? 1 : 0——静态定式为商品类(type=goods)恒为 1;库位类定式(empty_location)与其它商品定式(mis_shipment/expiring/warning)均为 0。", + "响应口径:create/patternCreate 返回的 check、detail 的 check、list 的行对象均为 is_static(number,0|1);库位盘点任务读取时恒为 0。", + "测试:test/app/service/systems/stock_check.test.js 的「is_static 静态标记」用例扩展——新增 type=location 传 is_static=1/true/'true' 均返回并落库 0 的断言;全量 245 用例通过、ESLint 0 错误。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.create(is_static 参数说明补充「仅商品盘点有效」+响应字段文案+notes)、stock.check.patternCreate(静态定式口径+notes)、stock.check.list / stock.check.detail(返回口径 notes);根版本 0.3.310 → 0.3.311、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", + "代码依据:app/service/systems/stock_check.js#create/#patternCreate、app/service/systemMethods/stock/check.js#create、app/model/stock_check.js(is_static)。" + ] + }, + { + "version": "0.3.310", + "date": "2026-10-28", + "type": "updated", + "summary": "库存盘点主表新增 is_static(是否静态盘点)标记:stock.check.create 支持入参 is_static(兼容 isStatic 驼峰与布尔/字符串写法),静态盘点定式(pattern=static)创建的任务自动置 1;stock.check.list / stock.check.detail / stock.check.patternCreate 返回该字段(0=普通盘点、1=静态盘点)。", + "methods": [ + "stock.check.create", + "stock.check.list", + "stock.check.detail", + "stock.check.patternCreate" + ], + "notes": [ + "需求背景:盘点任务需要区分「静态盘点」(针对长期停收停发商品的盘点)与普通盘点,原主表只有 type/mode/status,无法在列表/详情上识别任务来源与性质,静态定式创建的任务与手工任务混在一起。", + "库表变更:database/migrations/20261028010000-add-is-static-to-stock-check.js 给 wms_stock_check 新增 is_static(TINYINT(1) NOT NULL DEFAULT 0,注释「是否静态盘点(1=静态盘点(静态定式创建或创建时开启),0=普通盘点)」,位于 store_id 之后);存量数据默认 0,无需回填;down 迁移删除该列。", + "create 入参(新增):is_static 可选,纯标记——true / 'true' / 1 / '1' 记为 1,其余(含缺省、0、'false'、空串)记为 0;兼容 isStatic 驼峰写法;不参与模式强制(type=location 仍强制 blind)、状态机与差异计算;操作日志 STOCK_CHECK_CREATE 的 changeSummary/extras 追加静态标记。", + "patternCreate(自动判定):pattern_id=static 的任务 is_static=1,其余定式(empty_location/mis_shipment/expiring/warning)为 0;日志同样带「静态盘点」字样。", + "响应字段:create/detail/patternCreate 的 check(_formatCheckRow 口径)与 list 的行对象均返回 is_static(number,0|1);list 未新增 is_static 筛选条件。", + "测试:test/app/service/systems/stock_check.test.js 新增「is_static 静态标记」用例(缺省 0、isStatic=1 落库 1、detail/list 返回、方法层 is_static/isStatic 透传、0/'false'/空串/false 记 0),并在 static/warning 定式用例中断言 1/0;全量 245 用例通过、ESLint 0 错误;迁移已在本地开发库执行(information_schema 校验列存在)。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.create(新增 is_static 参数 + 响应字段说明 + notes)、stock.check.list(rows 返回字段 + notes)、stock.check.detail(check 返回字段 + notes)、stock.check.patternCreate(静态定式自动置 1 + notes);根版本 0.3.309 → 0.3.310、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", + "代码依据:app/model/stock_check.js(is_static 字段)、app/service/systems/stock_check.js#create/#patternCreate/#_formatCheckRow、app/service/systemMethods/stock/check.js#create、database/migrations/20261028010000-add-is-static-to-stock-check.js。" + ] + }, + { + "version": "0.3.309", + "date": "2026-10-28", + "type": "updated", + "summary": "库存盘点作业数据商品视图改为按商品汇总:stock.check.workData(goods 视图)同商品多库位明细合并为一行且行级不再返回 detail_id;stock.check.workDataDetail 改为传 id + stock_id 返回 summary 汇总 + rows 按库位分行(明细ID/库位ID/账面快照/实盘/差异);stock.check.report 的 detail_id 改为可选,缺失时按 id + stock_id + space_id 反查明细。", + "methods": [ + "stock.check.workData", + "stock.check.workDataDetail", + "stock.check.report" + ], + "notes": [ + "问题现象:goods 视图同一 stock_id 出现多条 detail_id(如盘点单里 stock_id=143270 出现 5 行、160240 出现 2 行),各行商品信息与 locations 库位列表完全相同,但行级 system_quantity/checked_quantity 只反映其中一条库位明细(该明细下作业记录),前端无法区分行间差异,跨行求和还会重复计数。", + "根因:商品盘点明细按「商品+库位」拆行落库(wms_stock_check_detail 唯一键 uk_check_stock_location = check_id+stock_id+location_id,addDetail 为该商品每个启用库存库位生成一行,system_quantity 为对应库位账面快照),而 _buildGoodsWorkRows 原以明细行为列表输出;locations 却按 stock_id 整商品计算,导致同商品多行内容高度重复而数量各管一个库位。", + "workData(goods 视图)改造:app/service/systems/stock_check.js#_buildGoodsWorkRows 先按 stock_id 分组(分组顺序沿用明细 id 升序,stock_id 为空/异常的明细行各自成行),再按组合并输出——行级 system_quantity=各库位明细行 system_quantity 之和、作业记录跨该商品全部明细合并后按库位编码聚合、checked_quantity/diff_quantity/is_diff 按合并后合计计算(无作业记录时差异仍恒 0);行级不再返回 detail_id/detail_ids(汇总行无单一明细语义),改为 locations 每项返回 detail_id(该库位盘点明细ID,供逐库位上报/删除)与 snapshot_quantity(该库位账面快照,明盘)。", + "workDataDetail 改造:商品分支入参改为 id(盘点任务ID)+ stock_id(商品库存ID,兼容 stockId),返回 { check_id, stock_id, 商品信息, summary, rows }——summary 为商品级 system_quantity(账面快照合计)/checked_quantity(实盘合计)/diff_quantity/is_diff;rows 每个库位一行,含 detail_id、location_id 与同义 space_id(可直接回传 report)、location_code、system_quantity(该库位当前账面=可用+锁定)、locked_quantity、snapshot_quantity(该库位账面快照)、checked_quantity(该库位实盘)、diff_quantity(实盘-快照)与 checked_at/checker_name/record_ids/images;盲盘不返回 summary 与任何数量字段;库位明细(detail_id 指向 scope_type=location 行)分支与原返回结构不变;传商品范围 detail_id 仍可用(服务端按明细商品解析 id + stock_id)。", + "report 兼容改造:detail_id 改为可选——未传时按 id + stock_id + space_id 反查明细(先命中 location_id=space_id 的该商品明细,未命中取该商品任一明细),反查不到报 400「盘点明细不存在(该商品不在本任务盘点范围内,或库位盘点任务需传 detail_id)」;既无 detail_id 也无 stock_id 仍报 400「盘点明细ID不能为空」;落库与覆盖式查重口径不变(作业记录仍挂 detail_id)。", + "响应兼容性(破坏性提示):① workData goods 视图行不再返回 detail_id/detail_ids,按明细操作(detailDelete 等)需改用 locations[].detail_id 或 workDataDetail rows[].detail_id;② workDataDetail 商品分支返回结构由「goods 视图单行」变为「summary + rows」钻取结构,旧前端读取 locations/checked_quantity 的代码需改读 summary/rows;③ 商品任务 workData goods 视图 total/rows 由「库位明细行数」变为「商品行数」(与主表 total_items 按商品计数一致)。", + "测试:test/app/service/systems/stock_check.test.js 新增/改写——「goods 视图多库位商品按商品汇总为一行」(两库位分别上报后断言 total=1、行级快照合计、跨明细合并实盘与 record_ids、locations 带 detail_id/snapshot_quantity)、「workDataDetail 商品钻取(summary + rows,含库位ID/明细ID/账面快照/实盘/差异)」「商品钻取盲盘不返回数量字段」「report 不传 detail_id 按 id + stock_id + space_id 反查上报」「方法层 stock_id/stockId/detail_id 兼容」;全量 244 用例通过、ESLint 0 错误。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.workData(description/response.rows/notes 的商品视图口径与 locations 新字段)、stock.check.workDataDetail(params 改为 id/stock_id/detail_id 三选、description/response.data/notes 改为 summary+rows 钻取结构)、stock.check.report(detail_id 必填改可选 + stock_id 反查说明);根版本 0.3.308 → 0.3.309、updatedAt 2026-10-27 → 2026-10-28;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", + "代码依据:app/service/systems/stock_check.js#_buildGoodsWorkRows/#workData/#workDataDetail/#_formatGoodsWorkDetail/#report、app/service/systemMethods/stock/check.js#workData/#workDataDetail/#report、app/model/stock_check_detail.js(uk_check_stock_location)。" + ] + }, { "version": "0.3.308", "date": "2026-10-27", diff --git a/methods/system.json b/methods/system.json index 90742ff..906643b 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.308", - "updatedAt": "2026-10-27", + "version": "0.3.318", + "updatedAt": "2026-10-28", "headers": [ { "name": "platform", @@ -4268,7 +4268,7 @@ }, { "method": "order.pendingOrder.allocateStorage", - "description": "按订单批量分配储位(迁移自 order.storageAllocation.allocateStorage)。这是一个异步提交接口:调用后接口立即返回受理信息(包含 request_id),后端异步执行实际的储位分配与锁定操作;仓库上下文由当前登录用户提供(ctx.user.store_id)。接口不会在同步响应中返回分配明细(如 requested_order_ids、allocated_order_ids 等),客户端可通过请求 ID 或事件/查询链路获取最终结果。已锁定订单(lock_status 非 none)会在分配流水线中被跳过(底层分配结果 skipped_orders 中记录 skipped_reason='locked')。默认仅从库位类型允许分配且启用的储位中分配;传入 allow_storage_location=true 时直接分配储位,无视库位类型的 allow_allocation/is_active 限制。", + "description": "按订单批量分配储位(迁移自 order.storageAllocation.allocateStorage)。这是一个异步提交接口:调用后接口立即返回受理信息(包含 request_id),后端异步执行实际的储位分配与锁定操作;仓库上下文由当前登录用户提供(ctx.user.store_id)。接口不会在同步响应中返回分配明细(如 requested_order_ids、allocated_order_ids 等),客户端可通过请求 ID 或事件/查询链路获取最终结果。已锁定订单(lock_status 非 none)会在分配流水线中被跳过(底层分配结果 skipped_orders 中记录 skipped_reason='locked')。默认仅从库位类型允许分配且启用的储位中分配;传入 allow_storage_location=true 时直接分配储位,无视库位类型的 allow_allocation/is_active 限制。;静态盘点锁定(订单级失败,与库存不足同流程):订单明细中的商品若处于静态盘点锁定中(stock_check.is_static=1 且任务审核完成/盘点中),**该订单**标记分配失败(storage_status=error、order_flag=「静态盘点锁定:sku(x) 盘点单 PDxxx」),不产生拣货行与库存锁定;同批次其它订单继续正常分配,接口仍返回 200,失败订单体现在 shortage_order_ids/shortage_messages/orders", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -4332,6 +4332,10 @@ "code": 500, "message": "内部错误:模型不可用或数据库/锁定操作失败" } + ], + "notes": [ + "静态盘点锁定拦截(本次,0.3.316):储位分配在归集订单明细 stock_id 之后、查询可用储位库存之前调用 systems.stockCheck.getStaticLockConflict,命中即回滚事务并返回 { code: 400, message, data: { locked_stock_ids, locked_items } },避免出现「盘点中的商品被分配拣货并锁定库存」;该拦截位于 orderStorageAllocation.allocatePicking(allocateStorage 为其兼容入口),因此 order.pendingOrder.allocateStorage 与内部调用(拣货分配、波次等)均生效。代码依据:app/service/systems/order_storage_allocation.js#allocatePicking(stockIds 归集后静态锁定校验)、app/service/systems/stock_check.js#getStaticLockConflict。", + "静态盘点锁定改为订单级失败(本次,0.3.317):储位分配是批量的(一次可传多个订单),若因静态盘点锁定整单返回 400,会连带把同批次未锁定的订单一起打断,与「库存不足」的既有处理口径(单订单标记失败、其余继续)不一致。现改为:命中锁定的商品行直接跳过分配(不查储位、不加锁、不写拣货行),所在订单按缺货同款路径标记失败——order.storage_status=error、order.step=异常、order_flag=「静态盘点锁定:sku(x) 盘点单 PDxxx」,并在响应 orders/shortage_order_ids/shortage_messages 中体现;同批次其它订单照常分配,接口整体仍返回 200。代码依据:app/service/systems/order_storage_allocation.js#allocatePicking(staticLockRowByStock / staticLockMessage 并入 finalShortageMessage)。" ] }, { @@ -11089,6 +11093,10 @@ "code": "500", "message": "任务提交失败或内部错误" } + ], + "notes": [ + "静态盘点锁定拦截(本次,0.3.316):本接口内部调用 orderStorageAllocation.allocateStorage 完成分配,商品命中静态盘点锁定时同样整单失败(400),文案与 order.pendingOrder.allocateStorage 一致。", + "静态盘点锁定口径(本次,0.3.317):沿用 allocateStorage 的订单级失败处理——命中锁定的订单标记 storage_status=error/order_flag,其余订单继续分配;波次批量分配不会因个别订单命中锁定而整体失败。" ] }, { @@ -38340,6 +38348,13 @@ "source": "body", "description": "货主ID(type=store 按货主按商品盘点时必填;添加商品明细时商品货主必须与该货主一致)" }, + { + "name": "is_static", + "type": "number", + "required": false, + "source": "body", + "description": "是否静态盘点(可选,纯标记;0=普通盘点(缺省)/1=静态盘点;兼容布尔 true 与 isStatic 驼峰写法,'true'/'1' 亦视为开启,其他值视为普通盘点)。**仅对商品盘点(type=store/goods)有效**:按库位盘点(type=location)恒为 0,传入 1 也忽略;静态盘点定式创建的任务由服务端自动置 1" + }, { "name": "remark", "type": "string", @@ -38371,7 +38386,7 @@ "name": "data", "type": "object", "required": true, - "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)(含 is_static 静态盘点标记)", "children": [ { "name": "id", @@ -38409,6 +38424,12 @@ "required": false, "description": "货主ID(按货主盘点时有值)" }, + { + "name": "is_static", + "type": "number", + "required": true, + "description": "is_static 是否静态盘点(1=静态盘点,仅商品盘点 type=store/goods 可能为 1——由静态盘点定式 pattern=static 创建或创建时显式开启;按库位盘点 type=location 恒为 0;纯标记字段,不改变盘点方式/状态机/差异口径)" + }, { "name": "status", "type": "string", @@ -38510,7 +38531,9 @@ "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库与生产库(import 当前 system.json → export 回写往返校验),保持库与文件一致。", "盘点方式规则:按库位盘点(type=location,明细为库位行)一律盲盘(blind),忽略前端传入的 mode;按商品盘点(type=store/goods,明细为商品行)按传入值,默认明盘(open)。代码依据:app/service/systems/stock_check.js#create 在 mode 合法性校验(仅支持 open/blind)通过后、写库前,normalizedType 为 location 时强制 normalizedMode='blind'。", "盘点时间口径(主表无 check_date):create 不写盘点时间(入参与主表均无 check_date,迁移 20260930150000-remove-check-date-from-wms-stock-check.js 已移除字段与索引);start_time=盘点开始时间(第一个盘点明细写入的时间,report 首次写入明细时补写)、end_time=盘点结束时间(完成盘点的时间,finish 时写入);_formatCheckRow 不再返回 check_date(仅返回 start_time/end_time);代码依据:app/service/systems/stock_check.js#create(不再写 check_date)、#report(start_time 为空补写)、#finish(写 end_time)、#_formatCheckRow(仅返回 start_time/end_time)。", - "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" + "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", + "静态标记(本次,0.3.310):wms_stock_check 新增 is_static(TINYINT(1) NOT NULL DEFAULT 0),create 支持入参 is_static(兼容 isStatic/布尔/字符串写法:true、'true'、1、'1' 记为 1,其余值记为 0);纯标记字段,不参与模式强制(location 仍强制 blind)、状态机与差异计算;操作日志 STOCK_CHECK_CREATE 的 message/extras 追加静态标记。代码依据:app/service/systems/stock_check.js#create(normalizedIsStatic)、database/migrations/20261028010000-add-is-static-to-stock-check.js。", + "静态标记口径收窄(本次,0.3.311):静态盘点(长期停收停发商品的盘点)只对商品盘点有意义,库位盘点(type=location)不涉及静态商品概念,因此 create 时 type=location 一律把 is_static 置 0(传入 1/true 也忽略,不报错),仅 type=store/goods 才按入参取值;响应字段与 list/detail 返回口径不变(库位盘点行恒为 0)。代码依据:app/service/systems/stock_check.js#create(normalizedIsStatic = type === 'location' || !requested ? 0 : 1)。" ] }, { @@ -38620,7 +38643,7 @@ "name": "rows", "type": "array", "required": true, - "description": "盘点任务行列表(主表全字段,含 check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at,每行新增 store_name 货主名称;start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间));store_name=货主名称:优先 wms_store_warehouse.store_remask(合约货主备注,按 store_id+warehouse_id 匹配);无合约或备注为空时回退 wms_store.company_name(公司全称);两者均查不到返回空字符串" + "description": "盘点任务行列表(主表全字段,含 check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at,每行新增 store_name 货主名称;start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间));store_name=货主名称:优先 wms_store_warehouse.store_remask(合约货主备注,按 store_id+warehouse_id 匹配);无合约或备注为空时回退 wms_store.company_name(公司全称);两者均查不到返回空字符串;另含 is_static 是否静态盘点(1=静态盘点(由静态盘点定式 pattern=static 创建,或创建任务时显式开启),0=普通盘点;纯标记字段,不改变盘点方式/状态机/差异口径)" }, { "name": "total", @@ -38663,7 +38686,9 @@ "时间范围语义:created_at/start_time/end_time 三列口径一致——单值=该字段 >= 该值(从该值起);数组 [from,to] 两端都合法=between 闭区间,仅 from 合法=gte、仅 to 合法=lte;空值/无法解析的日期静默忽略(不加入 where 条件)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库与生产库(import 当前 system.json → export 回写往返校验),保持库与文件一致;stock.check 分组共 18 条 method 无损。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.list 一条(response.rows 描述新增 store_name 货主名称与解析口径,description/notes 同步;params/errors/headers/鉴权不变);根版本 0.3.219 → 0.3.220、updatedAt 保持 2026-10-01;methods/changes/system.json 新增本条(插入数组首位);其余 17 条 method 未改动。", - "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" + "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", + "静态标记返回(本次,0.3.310):wms_stock_check 新增 is_static 字段,list 的行对象直接透出该字段(沿用 raw 行全字段口径),取值 0=普通盘点 / 1=静态盘点;筛选仍只支持 status/type/mode/store_id/keyword/时间范围,未新增 is_static 筛选(如需按静态过滤请提需求)。", + "静态标记口径(本次,0.3.311):list 行对象 is_static 恒为 0(库位盘点)或按任务来源/入参取值(商品盘点),未新增筛选条件。" ] }, { @@ -38978,7 +39003,7 @@ "name": "check", "type": "object", "required": true, - "description": "盘点主表信息(id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at + profit_total 盘盈合计数量 / loss_total 盘亏合计数量(正数口径,与 finish 一致;商品行聚合 vs 账面快照(未盘商品行按实盘 0 计盘亏)、库位行按商品聚合 vs wms_storage 账面(SUM(available_quantity+locked_quantity)=可用+锁定,未盘库位行不计差异)、未知商品按实盘计盘盈);start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间))" + "description": "盘点主表信息(id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/is_static(1=静态盘点/0=普通盘点)/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at + profit_total 盘盈合计数量 / loss_total 盘亏合计数量(正数口径,与 finish 一致;商品行聚合 vs 账面快照(未盘商品行按实盘 0 计盘亏)、库位行按商品聚合 vs wms_storage 账面(SUM(available_quantity+locked_quantity)=可用+锁定,未盘库位行不计差异)、未知商品按实盘计盘盈);start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间))" } ] }, @@ -39004,7 +39029,9 @@ "调用方迁移:原依赖 detail.rows 的调用方需改调 stock.check.result(返回 { check, rows, total } 聚合行,含商品行已盘聚合、records、locations 与库位行 stocks)/ stock.check.recordList(作业记录)/ stock.check.workData(三视图作业数据)。", "查询类方法,不记录操作日志(免日志清单:list/detail/result/recordList/export/exportTaskProgress)。", "兼容性影响(破坏性变更):响应 data 由 { check, rows, total } 变更为 { check },rows/total 字段被移除,前端取值需同步调整。", - "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" + "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", + "静态标记返回(本次,0.3.310):wms_stock_check 新增 is_static 字段,detail 的 check 对象(_formatCheckRow 口径)返回该字段(0=普通盘点 / 1=静态盘点)。", + "静态标记口径(本次,0.3.311):detail 的 check.is_static 对库位盘点任务恒为 0,商品盘点任务按创建来源/入参取值。" ] }, { @@ -39106,7 +39133,7 @@ }, { "method": "stock.check.workData", - "description": "拉取盘点作业数据(视图由任务范围与 is_goods 入参驱动,view 入参已废弃忽略):入参 id(盘点任务ID)+ is_goods(可选,商品任务是否按商品视图返回——true=goods 视图;缺省 false=聚合库位 space 视图;兼容 isGoods 驼峰写法;库位任务无视该参数)+ keyword(可选,关键字:仅库位任务 location 视图生效——按行 location_code/location_name 模糊匹配(不区分大小写)过滤任务明细后再分页;非库位任务忽略;空/纯空白视为未传)+ only_abnormal(可选,只看未盘和差异:过滤在 keyword 之后、分页切片之前完成,三视图均生效——location 视图仅保留 status=unchecked 或含未知商品记录(has_unknown=true)的行;goods 视图仅保留未盘行(locations 均无 record_ids)或明盘差异行(is_diff=1,盲盘无数量字段仅按未盘过滤);space 视图按行内 goods 子项过滤(status=unchecked 或明盘 checked_quantity≠system_quantity),过滤后 goods 为空的行整体移除;兼容 onlyAbnormal 驼峰写法);返回 { view, rows, total, page, pageSize }(view=服务端实际解析出的视图类型 location/goods/space,供调用方判断 rows 行结构;不返回任务主表信息 check——任务信息请调用 stock.check.detail),rows 结构随解析视图不同(先构建全量行——location 视图且 keyword 非空时先按 location_code/location_name 过滤,only_abnormal=true 时再按未盘/差异过滤,最后按页切片,rows 为当前页行)、total=全部行数(未分页口径;keyword/only_abnormal 过滤后 total 为过滤后行数)、page=当前页码(默认 1)、pageSize=每页数量(默认 20,上限 200),任务无对应范围行时 rows 返回空数组。分页:入参 data.pagination({ page, pageSize }),未传或非法时默认 page=1、pageSize=20(上限 200),分页口径与 stock.check.list 一致。视图解析:任务范围为库位(type=location)一律按 location 视图;任务范围为商品(type=goods/store)默认 space 视图、仅 is_goods=true 时 goods 视图。location(库位结构):以任务库位范围行(scope_type=location)为列表(按明细 id 升序;行含 detail_id/location_id 与同义字段 space_id/location_code/location_name/status/has_unknown/is_empty/checked_at/checkers/goods,space_id 可直接回传 stock.check.report),行内挂该库位的盘点作业记录 goods 子列表(已知商品与未知商品记录均入内,未知商品 stock_id=null、item_code 用条码兜底;每项含 record_id 作业记录 ID(单条记录直接定位,可调 recordDelete/recheckClearLocation 移除)与 images 作业记录照片——FileReference business_type=stock_check_record 经 _attachRecordImages 挂载,与 result/recordList 口径一致,无照片为空数组)+ has_unknown 标记(该库位是否含未知商品记录)+ is_empty 标记(该库位是否存在空库位标记记录:空标记记录不计入 goods 子列表,存在空标记后该行 status=checked 视为已盘点);goods(商品结构):以任务商品范围行(scope_type=goods)为列表(按明细 id 升序),行内 locations 为商品所在全部库位列表(商品库存库位取自 wms_storage——启用未删除存储 DISTINCT space_id 按拣货路径排序,无库存但已有作业记录的库位追加在末尾;每项含 location_id(库位ID wms_location_space.id,取分区有效的库位行,供调用方直接回传 stock.check.report 的 location_id)、record_ids 该库位该商品全部作业记录 ID(按记录 id 升序)与 images 该库位该商品全部作业照片(扁平去重),供前端编辑/移除记录;未盘库位 checked_at=null、record_ids/images 为空数组),明盘(mode=open)返回账面快照/已盘合计/差异,每库位含 system_quantity(该库位账面数量=可用+锁定,wms_storage SUM(available_quantity+locked_quantity),无库存记录库位为 0)、locked_quantity(该库位锁定数量,wms_storage SUM(locked_quantity))与 quantity(该库位盘点数量,未盘库位为 0),盲盘(mode=blind)不返回任何数量字段(行级 images 仍为商品主图);space(聚合库位列表):库位集合=当前库存库位 ∪ 作业记录库位(当前库存库位:wms_storage 中任务 stock_id 集合的启用未删除存储 DISTINCT space_id;作业记录库位:wms_stock_check_record 的 location_id 已回填直接用(上报库位与明细库位编码一致时归并到明细固化 location_id;指向无头库位(分区不存在/已删除)时归并到同编码有效库位并优先该商品有库存的库位,保证同编码只出一行、自定义名称/编码取有效库位行)、未回填的按 location_code 匹配 wms_location_space.space_code 补查,与库存库位去重后取并集),仅按库位拣货顺序排序(pick_sequence 升序,pick_priority 与库位 id 不参与,同值保持库位查询顺序),行含 id/space_code/custom_barcode/custom_name/goods(id 为库位ID wms_location_space.id,并额外输出同义字段 location_id,便于与 location/goods 视图、recordList、result 统一命名并直接回传 stock.check.report),行内 goods 为该库位下的任务商品(每项含 record_ids 该商品在该库位全部作业记录 ID(按记录 id 升序)与 images 该商品在该库位的作业照片聚合(扁平去重,不再输出商品主图),供前端编辑/移除记录),明盘含库位账面(可用+锁定)/锁定数量/已盘数量、盲盘不含数量;盘点前库存已出空但已有盘点作业记录的库位也能展示(该库位商品行账面 system_quantity 按 0、locked_quantity 按 0、checked_quantity 按该库位实盘合计)。状态限制:仅任务状态为 approved(审核完成)或 checking(盘点作业中)时可拉取盘点作业数据,其他状态(created 已创建/submitted 待审核/rejected 已驳回/completed 已完成/cancelled 已取消)返回 400「当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取」。", + "description": "拉取盘点作业数据(视图由任务范围与 is_goods 入参驱动,view 入参已废弃忽略):入参 id(盘点任务ID)+ is_goods(可选,商品任务是否按商品视图返回——true=goods 视图;缺省 false=聚合库位 space 视图;兼容 isGoods 驼峰写法;库位任务无视该参数)+ keyword(可选,关键字:仅库位任务 location 视图生效——按行 location_code/location_name 模糊匹配(不区分大小写)过滤任务明细后再分页;非库位任务忽略;空/纯空白视为未传)+ only_abnormal(可选,只看未盘和差异:过滤在 keyword 之后、分页切片之前完成,三视图均生效——location 视图仅保留 status=unchecked 或含未知商品记录(has_unknown=true)的行;goods 视图仅保留未盘行(locations 均无 record_ids)或明盘差异行(is_diff=1,盲盘无数量字段仅按未盘过滤);space 视图按行内 goods 子项过滤(status=unchecked 或明盘 checked_quantity≠system_quantity),过滤后 goods 为空的行整体移除;兼容 onlyAbnormal 驼峰写法);返回 { view, rows, total, page, pageSize }(view=服务端实际解析出的视图类型 location/goods/space,供调用方判断 rows 行结构;不返回任务主表信息 check——任务信息请调用 stock.check.detail),rows 结构随解析视图不同(先构建全量行——location 视图且 keyword 非空时先按 location_code/location_name 过滤,only_abnormal=true 时再按未盘/差异过滤,最后按页切片,rows 为当前页行)、total=全部行数(未分页口径;keyword/only_abnormal 过滤后 total 为过滤后行数)、page=当前页码(默认 1)、pageSize=每页数量(默认 20,上限 200),任务无对应范围行时 rows 返回空数组。分页:入参 data.pagination({ page, pageSize }),未传或非法时默认 page=1、pageSize=20(上限 200),分页口径与 stock.check.list 一致。视图解析:任务范围为库位(type=location)一律按 location 视图;任务范围为商品(type=goods/store)默认 space 视图、仅 is_goods=true 时 goods 视图。location(库位结构):以任务库位范围行(scope_type=location)为列表(按明细 id 升序;行含 detail_id/location_id 与同义字段 space_id/location_code/location_name/status/has_unknown/is_empty/checked_at/checkers/goods,space_id 可直接回传 stock.check.report),行内挂该库位的盘点作业记录 goods 子列表(已知商品与未知商品记录均入内,未知商品 stock_id=null、item_code 用条码兜底;每项含 record_id 作业记录 ID(单条记录直接定位,可调 recordDelete/recheckClearLocation 移除)与 images 作业记录照片——FileReference business_type=stock_check_record 经 _attachRecordImages 挂载,与 result/recordList 口径一致,无照片为空数组)+ has_unknown 标记(该库位是否含未知商品记录)+ is_empty 标记(该库位是否存在空库位标记记录:空标记记录不计入 goods 子列表,存在空标记后该行 status=checked 视为已盘点);goods(商品结构):按商品(stock_id)汇总,一个商品一行——同商品的多个库位明细行(scope_type=goods,按「商品+库位」拆行,唯一键 check_id+stock_id+location_id)合并输出(按商品首个明细 id 升序,行级不返回 detail_id,逐库位明细/汇总请调用 stock.check.workDataDetail 传 id + stock_id),行内 locations 为商品所在全部库位列表(商品库存库位取自 wms_storage——启用未删除存储 DISTINCT space_id 按拣货路径排序,无库存但已有作业记录的库位追加在末尾;每项含 location_id(库位ID wms_location_space.id,取分区有效的库位行,供调用方直接回传 stock.check.report 的 location_id)、record_ids 该库位该商品全部作业记录 ID(按记录 id 升序)与 images 该库位该商品全部作业照片(扁平去重),供前端编辑/移除记录;未盘库位 checked_at=null、record_ids/images 为空数组;每项另含 detail_id 该库位盘点明细ID 与明盘 snapshot_quantity 该库位账面快照),明盘(mode=open)返回账面快照合计(该商品各库位明细行 system_quantity 之和)/已盘合计/差异(作业记录跨该商品全部明细按库位合并),每库位含 system_quantity(该库位账面数量=可用+锁定,wms_storage SUM(available_quantity+locked_quantity),无库存记录库位为 0)、locked_quantity(该库位锁定数量,wms_storage SUM(locked_quantity))与 quantity(该库位盘点数量,未盘库位为 0),盲盘(mode=blind)不返回任何数量字段(行级 images 仍为商品主图);space(聚合库位列表):库位集合=当前库存库位 ∪ 作业记录库位(当前库存库位:wms_storage 中任务 stock_id 集合的启用未删除存储 DISTINCT space_id;作业记录库位:wms_stock_check_record 的 location_id 已回填直接用(上报库位与明细库位编码一致时归并到明细固化 location_id;指向无头库位(分区不存在/已删除)时归并到同编码有效库位并优先该商品有库存的库位,保证同编码只出一行、自定义名称/编码取有效库位行)、未回填的按 location_code 匹配 wms_location_space.space_code 补查,与库存库位去重后取并集),仅按库位拣货顺序排序(pick_sequence 升序,pick_priority 与库位 id 不参与,同值保持库位查询顺序),行含 id/space_code/custom_barcode/custom_name/goods(id 为库位ID wms_location_space.id,并额外输出同义字段 location_id,便于与 location/goods 视图、recordList、result 统一命名并直接回传 stock.check.report),行内 goods 为该库位下的任务商品(每项含 record_ids 该商品在该库位全部作业记录 ID(按记录 id 升序)与 images 该商品在该库位的作业照片聚合(扁平去重,不再输出商品主图),供前端编辑/移除记录),明盘含库位账面(可用+锁定)/锁定数量/已盘数量、盲盘不含数量;盘点前库存已出空但已有盘点作业记录的库位也能展示(该库位商品行账面 system_quantity 按 0、locked_quantity 按 0、checked_quantity 按该库位实盘合计)。状态限制:仅任务状态为 approved(审核完成)或 checking(盘点作业中)时可拉取盘点作业数据,其他状态(created 已创建/submitted 待审核/rejected 已驳回/completed 已完成/cancelled 已取消)返回 400「当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取」。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -39189,7 +39216,7 @@ "name": "rows", "type": "array", "required": true, - "description": "盘点作业数据行列表(当前页行:先构建全量行——location 视图且 keyword 非空时先按行 location_code/location_name 模糊匹配(不区分大小写)过滤,only_abnormal=true 时再按未盘/差异过滤(location 按行 status=unchecked/has_unknown;goods 按行未盘或明盘 is_diff=1;space 按行内 goods 子项过滤后空行移除),最后按页切片;total 为全部行数——未分页口径;location 视图 + keyword 或 only_abnormal=true 时 rows 为过滤后的行、total 同步过滤口径;非库位任务(goods/store,space/goods 视图)忽略 keyword),结构随解析视图不同——location 视图行:detail_id 明细ID / location_id 库位ID / location_code 库位编码(优先明细快照,缺失回退库位表 space_code)/ location_name 库位名称(custom_name 兜底 space_code)/ status 盘点状态(checked=存在作业记录,unchecked=无)/ has_unknown 是否含未知商品记录(该库位存在 stock_id 为空的作业记录时为 true,未知商品同样计入 goods) / is_empty 是否空库位标记(该库位存在空库位标记记录(is_empty=1)时为 true;空标记记录不计入 goods 子列表;存在空标记后该行 status=checked 视为已盘点) / checked_at 该库位最近上报时间(无记录为 null)/ checkers 盘点人去重数组 + goods 作业记录子列表(已知商品与未知商品记录均入内,字段统一 record_id 作业记录ID(单条记录直接定位,可调 recordDelete/recheckClearLocation 移除)/stock_id/item_code/item_name/barcode/images 作业记录照片(已知商品与未知商品均经 _attachRecordImages 挂载 FileReference business_type=stock_check_record,与 result/recordList 口径一致,不再输出商品主图,无照片为空数组)/store_id/store_name/quantity 实盘数量/checked_at/checker_name——已知商品(stock_id 有值)商品信息批量取自 stockWarehouse.getStockDetails 带缓存、货主名经 _resolveStoreNameMap 解析;未知商品(stock_id=null)item_code 用条码兜底、item_name 用名称快照兜底条码、store_id/store_name 为 null);goods 视图行:detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images(行级 images 仍为商品主图 image_url)+ locations 商品所在全部库位列表(商品库存库位取自 wms_storage——启用未删除存储 DISTINCT space_id 按拣货路径排序;无库存但已有作业记录的库位按首条记录 id 升序追加在末尾;空库位归 location_code=null 组排在最后。每项 [{ location_code, checked_at, checker_name, record_ids 该库位该商品全部作业记录 ID(按记录 id 升序,供前端编辑/移除记录), images 该库位该商品全部记录的作业照片(扁平去重,无照片为空数组) }],未盘库位 checked_at/checker_name 为 null、record_ids/images 为空数组),明盘(mode=open)另含 system_quantity 账面快照/checked_quantity 已盘合计(locations 各库位 quantity 合计,未盘行恒 0)/diff_quantity 差异=已盘-账面(仅存在作业记录的行计算,未盘行恒 0)/is_diff 是否差异 0|1(未盘行恒 0),locations 各项另含 system_quantity 该库位账面数量(wms_storage 该库位 SUM(available_quantity+locked_quantity),无库存记录库位 0)、locked_quantity 该库位锁定数量(wms_storage 该库位 SUM(locked_quantity))与 quantity 该库位盘点数量(实盘合计,未盘库位 0),盲盘(mode=blind)不返回任何数量字段(locations 仅 location_code/checked_at/checker_name/record_ids/images);space 视图行:id(库位ID wms_location_space.id)/space_code(库位编码)/custom_barcode(库位自定义条码,空为 null)/custom_name(库位自定义名称,空为 null 不兜底 space_code;库位字段对齐库位查询惯例 index.searchSpace)+ goods 该库位下的任务商品子列表(detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images 该商品在该库位的作业照片聚合(扁平去重,不再输出商品主图,无照片为空数组)/record_ids 该商品在该库位的全部作业记录 ID(按记录 id 升序,供前端编辑/移除记录) + status 已盘状态(该 detail_id+location_code 存在作业记录即 checked,否则 unchecked)),明盘 goods 各项另含 system_quantity(wms_storage space+stock SUM(available_quantity+locked_quantity) 账面=可用+锁定,该库位无库存记录时按 0)/locked_quantity(该库位锁定数量,SUM(locked_quantity))/checked_quantity(该商品在该库位的实盘合计),盲盘不含数量;库位集合=当前库存库位 ∪ 作业记录库位(盘点前库存已出空但已有盘点作业记录的库位也能展示)" + "description": "盘点作业数据行列表(当前页行:先构建全量行——location 视图且 keyword 非空时先按行 location_code/location_name 模糊匹配(不区分大小写)过滤,only_abnormal=true 时再按未盘/差异过滤(location 按行 status=unchecked/has_unknown;goods 按行未盘或明盘 is_diff=1;space 按行内 goods 子项过滤后空行移除),最后按页切片;total 为全部行数——未分页口径;location 视图 + keyword 或 only_abnormal=true 时 rows 为过滤后的行、total 同步过滤口径;非库位任务(goods/store,space/goods 视图)忽略 keyword),结构随解析视图不同——location 视图行:detail_id 明细ID / location_id 库位ID / location_code 库位编码(优先明细快照,缺失回退库位表 space_code)/ location_name 库位名称(custom_name 兜底 space_code)/ status 盘点状态(checked=存在作业记录,unchecked=无)/ has_unknown 是否含未知商品记录(该库位存在 stock_id 为空的作业记录时为 true,未知商品同样计入 goods) / is_empty 是否空库位标记(该库位存在空库位标记记录(is_empty=1)时为 true;空标记记录不计入 goods 子列表;存在空标记后该行 status=checked 视为已盘点) / checked_at 该库位最近上报时间(无记录为 null)/ checkers 盘点人去重数组 + goods 作业记录子列表(已知商品与未知商品记录均入内,字段统一 record_id 作业记录ID(单条记录直接定位,可调 recordDelete/recheckClearLocation 移除)/stock_id/item_code/item_name/barcode/images 作业记录照片(已知商品与未知商品均经 _attachRecordImages 挂载 FileReference business_type=stock_check_record,与 result/recordList 口径一致,不再输出商品主图,无照片为空数组)/store_id/store_name/quantity 实盘数量/checked_at/checker_name——已知商品(stock_id 有值)商品信息批量取自 stockWarehouse.getStockDetails 带缓存、货主名经 _resolveStoreNameMap 解析;未知商品(stock_id=null)item_code 用条码兜底、item_name 用名称快照兜底条码、store_id/store_name 为 null);goods 视图行(按商品汇总,一个商品一行,行级不返回 detail_id——逐库位明细/汇总请调 stock.check.workDataDetail 传 id + stock_id;账面取值按任务静态标记(is_static)区分:is_static=1(静态盘点)取明细账面快照 system_quantity(盘点基准冻结,不受盘点期间出入库影响);is_static=0(普通盘点)取当前 wms_storage 账面 SUM(available_quantity+locked_quantity);两者都会额外输出 storage_quantity(当前 storage 账面)与 snapshot_quantity(明细快照)供对照,system_quantity 始终为参与差异计算的账面,行/商品额外输出 is_static 与 book_source(snapshot|storage),locations 各项与行级均按此口径):stock_id/item_code/item_name/spec/store_id/store_name/barcode/images(行级 images 仍为商品主图 image_url)+ locations 商品所在全部库位列表(商品库存库位取自 wms_storage——启用未删除存储 DISTINCT space_id 按拣货路径排序;无库存但已有作业记录的库位按首条记录 id 升序追加在末尾;空库位归 location_code=null 组排在最后。每项 [{ location_id 库位ID 与同义字段 space_id(wms_location_space.id,可直接回传 stock.check.report), location_code 库位编码, detail_id 该库位盘点明细ID(无明细快照的库位为 null), checked_at, checker_name, record_ids 该库位该商品全部作业记录 ID(按记录 id 升序,供前端编辑/移除记录), images 该库位该商品全部记录的作业照片(扁平去重,无照片为空数组) }],未盘库位 checked_at/checker_name 为 null、record_ids/images 为空数组),明盘(mode=open)另含 system_quantity 账面合计(按任务静态标记取快照合计或当前 storage 合计)/checked_quantity 已盘合计(locations 各库位 quantity 合计=该商品全部明细的作业记录合计,未盘行恒 0)/diff_quantity 差异=已盘-账面(仅存在作业记录的行计算,未盘行恒 0)/is_diff 是否差异 0|1(未盘行恒 0),locations 各项另含 system_quantity 该库位账面数量(wms_storage 该库位 SUM(available_quantity+locked_quantity),无库存记录库位 0)、locked_quantity 该库位锁定数量(wms_storage 该库位 SUM(locked_quantity))、snapshot_quantity 该库位账面快照、storage_quantity 该库位当前 storage 账面与 quantity 该库位盘点数量(实盘合计,未盘库位 0),其中 system_quantity 按任务静态标记取快照或 storage,盲盘(mode=blind)不返回任何数量字段(locations 仅 location_id/space_id/location_code/detail_id/checked_at/checker_name/record_ids/images);space 视图行:id(库位ID wms_location_space.id)/space_code(库位编码)/custom_barcode(库位自定义条码,空为 null)/custom_name(库位自定义名称,空为 null 不兜底 space_code;库位字段对齐库位查询惯例 index.searchSpace)+ goods 该库位下的任务商品子列表(detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images 该商品在该库位的作业照片聚合(扁平去重,不再输出商品主图,无照片为空数组)/record_ids 该商品在该库位的全部作业记录 ID(按记录 id 升序,供前端编辑/移除记录) + status 已盘状态(该 detail_id+location_code 存在作业记录即 checked,否则 unchecked)),明盘 goods 各项另含 system_quantity(wms_storage space+stock SUM(available_quantity+locked_quantity) 账面=可用+锁定,该库位无库存记录时按 0)/locked_quantity(该库位锁定数量,SUM(locked_quantity))/checked_quantity(该商品在该库位的实盘合计),盲盘不含数量;库位集合=当前库存库位 ∪ 作业记录库位(盘点前库存已出空但已有盘点作业记录的库位也能展示)" }, { "name": "total", @@ -39238,9 +39265,9 @@ ], "notes": [ "代码依据:app/service/systemMethods/stock/check.js#workData(warehouse_id 由服务端从 ctx.user.store_id 自动注入,前端无需传递;const { id, is_goods: isGoodsSnake, isGoods: isGoodsCamel, pagination } = data || {},isGoods=is_goods 未定义时回退 isGoods(兼容 isGoods 驼峰写法);不再读取、不再校验 view,透传 { warehouseId, id, isGoods, pagination })+ app/service/systems/stock_check.js#workData(id 非正整数抛 400『盘点任务ID不能为空』;任务不存在(按 id+warehouse_id 查 wms_stock_check)抛 400『盘点任务不存在』;状态守卫:任务状态非 REPORT_ALLOWED_STATUSES(approved/checking)时抛 400『当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取』;视图解析:normalizedType=String(check.type||'').trim(),type=location 一律 location 视图(无视 view/is_goods),否则 goodsViewRequested=isGoods===true||'true'||1 时 goods 视图、其余默认 space 视图;按解析视图分派 _buildLocationWorkRows/_buildGoodsWorkRows/_buildSpaceWorkRows,统一返回 { check: _formatCheckRow 口径, rows, total: rows.length, page, pageSize })。本次代码已改(view 入参废弃、is_goods 驱动视图)并测试通过 197/197、ESLint 0 错误。", - "三视图口径(由任务范围 + is_goods 解析后分派):location=库位结构(库位范围任务一律该视图),以任务库位范围行(scope_type=location)为列表(按明细 id 升序),行内挂该库位盘点作业记录 goods 子列表(已知商品与未知商品记录均入内:已知商品 stock_id 有值,商品信息批量取自 stockWarehouse.getStockDetails 带缓存、货主名 _resolveStoreNameMap 解析;未知商品 stock_id=null,item_code 用条码兜底、item_name 用名称快照兜底条码、store_id/store_name 为 null;已知/未知商品的 images 均为作业记录照片(经 _attachRecordImages 挂载 FileReference business_type=stock_check_record,已知商品不再输出商品主图 image_url)),has_unknown 标记该库位是否含未知商品记录;goods=商品结构(商品范围任务且 is_goods=true 时该视图),以任务商品范围行(scope_type=goods)为列表(按明细 id 升序),行内 locations 为商品所在全部库位列表(商品库存库位取自 wms_storage 启用未删除存储且库位有效(未删除且所属 zone 存在未删除,排除无头库位)DISTINCT space_id 按拣货路径排序,无库存但已有作业记录的库位按首条记录 id 升序追加在末尾,空库位归 location_code=null 组排在最后;明盘每库位含 system_quantity 该库位账面数量与 quantity 该库位盘点数量(未盘库位 0),盲盘仅 location_code/checked_at/checker_name/record_ids/images);space=聚合库位列表(商品范围任务默认该视图),库位集合=当前库存库位 ∪ 作业记录库位——当前库存库位:wms_storage(warehouse_id + stock_id 在集合 + is_enabled=1 未删除且库位有效(排除无头库位))DISTINCT space_id;作业记录库位:wms_stock_check_record 的 location_id 已回填直接用、未回填的按 location_code 匹配 wms_location_space.space_code 补查,与库存库位去重后并集;行内 goods 为该库位下的任务商品;盘点前库存已出空但已有盘点作业记录的库位也能展示(该库位商品行账面 system_quantity 按 0、checked_quantity 按该库位实盘合计)。", - "明盘/盲盘数量控制:明盘(mode=open)goods 视图行返回 system_quantity(明细账面快照)/checked_quantity(已盘合计=locations.quantity 合计)/diff_quantity(已盘-账面,仅存在作业记录的行计算)/is_diff(差异非 0 为 1),locations 各项含 system_quantity(该库位账面数量=可用+锁定,wms_storage 该库位 SUM(available_quantity+locked_quantity),无库存记录库位为 0)、locked_quantity(该库位锁定数量,wms_storage 该库位 SUM(locked_quantity))与 quantity(该库位盘点数量=实盘合计,未盘库位为 0);space 视图 goods 各项含 system_quantity(wms_storage space+stock SUM(available_quantity+locked_quantity) 账面,该库位无库存记录时按 0)/locked_quantity(wms_storage space+stock SUM(locked_quantity))/checked_quantity(该商品在该库位的实盘合计);盲盘(mode=blind)不返回任何数量字段(goods 视图 locations 仅 location_code/checked_at/checker_name/record_ids/images,space 视图 goods 仅商品信息+images/record_ids/status);goods 视图 locations 为商品所在全部库位列表(含未盘库位,无作业记录时各项为空信息),无作业记录的行明盘已盘合计恒 0、差异/is_diff 恒 0(避免未盘行误显盘亏差异)。", - "排序口径:space 视图库位仅按库位拣货顺序排序——pick_sequence 升序(pick_priority 与库位 id 均不参与,同值保持库位查询顺序);space 行内 goods 按 stock_id 升序;location/goods 视图行按明细 id 升序;goods 视图 locations 按首条记录 id 升序。", + "三视图口径(由任务范围 + is_goods 解析后分派):location=库位结构(库位范围任务一律该视图),以任务库位范围行(scope_type=location)为列表(按明细 id 升序),行内挂该库位盘点作业记录 goods 子列表(已知商品与未知商品记录均入内:已知商品 stock_id 有值,商品信息批量取自 stockWarehouse.getStockDetails 带缓存、货主名 _resolveStoreNameMap 解析;未知商品 stock_id=null,item_code 用条码兜底、item_name 用名称快照兜底条码、store_id/store_name 为 null;已知/未知商品的 images 均为作业记录照片(经 _attachRecordImages 挂载 FileReference business_type=stock_check_record,已知商品不再输出商品主图 image_url)),has_unknown 标记该库位是否含未知商品记录;goods=商品结构(商品范围任务且 is_goods=true 时该视图),按商品(stock_id)汇总,一个商品一行——同商品的多个库位明细行(scope_type=goods)合并输出(按商品首个明细 id 升序,行级不返回 detail_id),行内 locations 为商品所在全部库位列表(商品库存库位取自 wms_storage 启用未删除存储且库位有效(未删除且所属 zone 存在未删除,排除无头库位)DISTINCT space_id 按拣货路径排序,无库存但已有作业记录的库位按首条记录 id 升序追加在末尾,空库位归 location_code=null 组排在最后;明盘每库位含 system_quantity 该库位账面数量与 quantity 该库位盘点数量(未盘库位 0),盲盘仅 location_code/checked_at/checker_name/record_ids/images);space=聚合库位列表(商品范围任务默认该视图),库位集合=当前库存库位 ∪ 作业记录库位——当前库存库位:wms_storage(warehouse_id + stock_id 在集合 + is_enabled=1 未删除且库位有效(排除无头库位))DISTINCT space_id;作业记录库位:wms_stock_check_record 的 location_id 已回填直接用、未回填的按 location_code 匹配 wms_location_space.space_code 补查,与库存库位去重后并集;行内 goods 为该库位下的任务商品;盘点前库存已出空但已有盘点作业记录的库位也能展示(该库位商品行账面 system_quantity 按 0、checked_quantity 按该库位实盘合计)。", + "明盘/盲盘数量控制:明盘(mode=open)goods 视图行返回 system_quantity(该商品各库位明细行账面快照合计)/checked_quantity(已盘合计=locations.quantity 合计)/diff_quantity(已盘-账面,仅存在作业记录的行计算)/is_diff(差异非 0 为 1),locations 各项含 system_quantity(该库位账面数量=可用+锁定,wms_storage 该库位 SUM(available_quantity+locked_quantity),无库存记录库位为 0)、locked_quantity(该库位锁定数量,wms_storage 该库位 SUM(locked_quantity))与 quantity(该库位盘点数量=实盘合计,未盘库位为 0);space 视图 goods 各项含 system_quantity(wms_storage space+stock SUM(available_quantity+locked_quantity) 账面,该库位无库存记录时按 0)/locked_quantity(wms_storage space+stock SUM(locked_quantity))/checked_quantity(该商品在该库位的实盘合计);盲盘(mode=blind)不返回任何数量字段(goods 视图 locations 仅 location_code/checked_at/checker_name/record_ids/images,space 视图 goods 仅商品信息+images/record_ids/status);goods 视图 locations 为商品所在全部库位列表(含未盘库位,无作业记录时各项为空信息),无作业记录的行明盘已盘合计恒 0、差异/is_diff 恒 0(避免未盘行误显盘亏差异)。", + "排序口径:space 视图库位仅按库位拣货顺序排序——pick_sequence 升序(pick_priority 与库位 id 均不参与,同值保持库位查询顺序);space 行内 goods 按 stock_id 升序;location 视图行按明细 id 升序、goods 视图行按商品首个明细 id 升序;goods 视图 locations 按首条记录 id 升序。", "权限口径:随 ALL_METHOD_NAMES(22 个:create/list/addDetail/addLocationDetail/detailDelete/detail/result/workData/report/markEmpty/recordList/recordDelete/recheckClearLocation/finish/submit/cancel/audit/batchDelete/export/exportTaskProgress/patternList/patternCreate)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(_noNeedAuth)、必须登录(isNeedLogin=true,免登录清单为空);为查询类方法,加入免日志清单 _noNeedLog(list/detail/result/workData/recordList/export/exportTaskProgress/patternList),不记录操作日志。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.workData 一条(位于 stock.check.result 之后);根版本 0.3.224 → 0.3.225、updatedAt 2026-10-01 → 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 19 条 method 未改动(stock.check 分组由 19 条增至 20 条)。", "状态限制口径:仅任务状态为 approved(审核完成)或 checking(盘点作业中)可拉取盘点作业数据;其他状态(created 已创建/submitted 待审核/rejected 已驳回/completed 已完成/cancelled 已取消)返回 400,message 为『当前状态({状态中文标签,无标签时回退状态值})不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取』,状态标签取 STOCK_CHECK_STATUS_LABELS。状态守卫复用 REPORT_ALLOWED_STATUSES 常量,与 report(盘点作业上报)及 finish(完成盘点)一致。", @@ -39287,7 +39314,9 @@ "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData、stock.check.workDataDetail 与 stock.check.workDataSpaceDetails 三条(description/response.rows/notes 同步库位账面=可用+锁定口径与 locked_quantity 字段);根版本 0.3.247 → 0.3.248、updatedAt 保持 2026-10-05;methods/changes/system.json 新增本条(插入数组首位);其余 20 条 method 未改动(stock.check 分组仍为 23 条)。", "库位账面口径全量统一(本次,0.3.249 同步):全部盘点账面口径统一为 SUM(available_quantity+locked_quantity)(=可用+锁定)——result 库位行 stocks 账面与空库位标记盘亏、report 重算 diff_items 的库位行/空标记账面、finish 差异汇总、detail profit/loss 汇总、addDetail 按库位拆行的明细快照 system_quantity,与盘点作业视图(workData/workDataDetail/workDataSpaceDetails)一致;商品行仍以明细账面快照(system_quantity 列)对比。回归测试 222/222 通过、ESLint 0 错误。", "only_abnormal 过滤口径(本次新增):only_abnormal(boolean,可选,向后兼容,兼容 onlyAbnormal 驼峰写法;未传或非 true(false/0/空串/缺省)不过滤)——过滤在 keyword 之后、分页切片之前完成(total 为过滤后行数),三视图均生效:location 视图仅保留 status=unchecked 或 has_unknown=true 的行(未知商品无账面、差异=实盘-0=盘盈视为差异;空库位标记 is_empty 后 status=checked 视为已盘点、不保留);goods 视图仅保留未盘行(locations 均无 record_ids,即无任何作业记录)或明盘差异行(is_diff=1),盲盘无数量字段仅按未盘过滤(已盘行全部移除);space 视图按行内 goods 子项过滤(status=unchecked 或明盘 checked_quantity≠system_quantity,system_quantity 口径=可用+锁定),过滤后 goods 为空的行整体移除。与 keyword 过滤叠加(keyword 先过滤、only_abnormal 后过滤)。代码依据:app/service/systemMethods/stock/check.js#workData(only_abnormal/onlyAbnormal 蛇形驼峰兼容,透传 onlyAbnormal)+ app/service/systems/stock_check.js#workData/#_filterAbnormalWorkRows;回归测试新增 5 用例(location/goods 明盘/space 明盘/space 盲盘/keyword 叠加)全部通过、workData 相关 43 用例通过、ESLint 0 错误。", - "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params 新增 only_abnormal、description/response.rows/response.total/notes 同步过滤口径;headers/errors/isNeedAuth/isNeedLogin 不变);根版本 0.3.249 → 0.3.250、updatedAt 保持 2026-10-06;methods/changes/system.json 新增本条(插入数组首位);其余 23 条 method 未改动(stock.check 分组仍为 24 条)。" + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params 新增 only_abnormal、description/response.rows/response.total/notes 同步过滤口径;headers/errors/isNeedAuth/isNeedLogin 不变);根版本 0.3.249 → 0.3.250、updatedAt 保持 2026-10-06;methods/changes/system.json 新增本条(插入数组首位);其余 23 条 method 未改动(stock.check 分组仍为 24 条)。", + "商品视图按商品汇总(本次,0.3.309):goods 视图原以库位明细行为列表(同商品多库位输出多条 detail_id,商品信息与 locations 完全相同、行级数量各管一个库位),前端无法区分且跨行求和会重复计数;现按 stock_id 汇总一行——行级 system_quantity=各库位明细行快照合计、checked_quantity/diff_quantity=该商品全部明细的作业记录按库位合并后合计,locations 每项新增 detail_id(该库位盘点明细ID,供逐库位上报/删除)与 snapshot_quantity(该库位账面快照,明盘);行级不再返回 detail_id/detail_ids(汇总行无单一明细语义,逐库位明细与汇总改由 stock.check.workDataDetail 传 id + stock_id 获取);stock_id 为空/异常的明细行无法归并,仍各自成行;keyword(仅 location 视图生效)/only_abnormal/分页口径不变,商品任务 total 由「明细行数」变为「商品行数」(与主表 total_items 按商品计数一致)。代码依据:app/service/systems/stock_check.js#_buildGoodsWorkRows(按 stock_id 分组 detailGroups,locations 挂 detail_id/snapshot_quantity)。", + "账面取值按静态标记区分(本次,0.3.318):workData 的 goods / space 视图原先 goods 视图行级取快照、locations 取 storage,口径混用;现统一为「system_quantity = 本次参与差异计算的账面」——is_static=1 取明细快照(冻结基准),is_static=0 取当前 wms_storage(可用+锁定);同时新增 storage_quantity(当前 storage 账面)与 is_static/book_source 字段,快照仍以 snapshot_quantity 输出,调用方可按需对照。space 视图行内 goods 同样按此口径(并新增 storage_quantity/snapshot_quantity)。代码依据:app/service/systems/stock_check.js#workData(isStatic 透传)/#_buildGoodsWorkRows/#_buildSpaceWorkRows。" ] }, { @@ -39371,7 +39400,7 @@ }, { "method": "stock.check.workDataDetail", - "description": "拉取单条盘点明细的作业数据(workData 单行版,按明细范围类型分流,均返回单行对象):入参 detail_id(盘点明细ID,兼容 detailId 驼峰写法);warehouse_id 由服务端从当前上下文自动注入,前端无需传递;返回统一 success 包装,data 为单行作业数据。① 库位明细(scope_type=location):行结构与 workData location 视图单行一致——detail_id 明细ID / location_id 库位ID(明细未绑定库位时为 null)与同义字段 space_id(可直接回传 stock.check.report)/ location_code 库位编码(优先明细快照,缺失回退库位表 space_code)/ location_name 库位名称(custom_name 兜底 space_code,无库位编码时为 null)/ status 盘点状态(checked=存在作业记录(含空库位标记记录),unchecked=无作业记录)/ has_unknown 是否含未知商品记录 / is_empty 是否空库位标记(空标记记录不计入 goods 子列表)/ checked_at 该库位最近上报时间(无记录为 null)/ checkers 盘点人去重数组 + goods 作业记录子列表(已知商品与未知商品记录均入内,字段与 workData location 视图一致:record_id 作业记录ID(可调 stock.check.recordDelete / stock.check.recheckClearLocation 移除)/ stock_id 商品库存ID(未知商品为 null)/ item_code 商品编码(未知商品用条码兜底)/ item_name 商品名称(未知商品用名称快照兜底条码)/ barcode 条码 / images 作业记录照片(FileReference business_type=stock_check_record 经 _attachRecordImages 挂载,与 workData/result/recordList 口径一致,无照片为空数组)/ store_id 货主ID(未知商品为 null)/ store_name 货主名(未知商品为 null)/ quantity 实盘数量 / checked_at 上报时间 / checker_name 盘点人;空库位标记记录不计入 goods)。② 商品明细(scope_type=goods):行结构与 workData goods 视图行一致——detail_id 明细ID / stock_id 商品库存ID / item_code 商品编码 / item_name 商品名称 / spec 规格 / store_id 货主ID / store_name 货主名 / barcode 条码 / images 商品图片(URL 数组,与 workData goods 视图一致)/ locations 商品所在全部库位列表(商品库存库位按拣货路径排序在前,无库存但已有作业记录的库位按首条记录 id 升序追加在末尾,空库位归 location_code=null 组排在最后;每项 { location_code, location_id, space_id, checked_at, checker_name, record_ids, images },未盘库位 checked_at/checker_name 为 null、record_ids/images 为空数组(location_id/space_id 同值,取分区有效库位行,可直接回传 stock.check.report);明盘另含 system_quantity 该库位账面数量(=可用+锁定)、locked_quantity 该库位锁定数量与 quantity 该库位盘点数量(未盘库位 0),盲盘只返回库位信息);明盘(mode=open)另含 system_quantity 账面快照 / checked_quantity 已盘合计 / diff_quantity 差异(仅存在作业记录时计算,未盘恒 0) / is_diff,盲盘(mode=blind)不返回任何数量字段。仅任务状态 approved(审核完成)或 checking(盘点作业中)可拉取(与 workData 同口径)。", + "description": "拉取盘点作业数据明细(库位明细单行 / 商品钻取):入参二选一——① detail_id(盘点明细ID,兼容 detailId 驼峰写法,库位明细必传);② id(盘点任务ID)+ stock_id(商品库存ID,兼容 stockId 驼峰写法,商品钻取用,goods 汇总视图行不返回明细ID 时按此获取明细);warehouse_id 由服务端从当前上下文自动注入,前端无需传递;返回统一 success 包装,data 为单行作业数据。① 库位明细(scope_type=location):行结构与 workData location 视图单行一致——detail_id 明细ID / location_id 库位ID(明细未绑定库位时为 null)与同义字段 space_id(可直接回传 stock.check.report)/ location_code 库位编码(优先明细快照,缺失回退库位表 space_code)/ location_name 库位名称(custom_name 兜底 space_code,无库位编码时为 null)/ status 盘点状态(checked=存在作业记录(含空库位标记记录),unchecked=无作业记录)/ has_unknown 是否含未知商品记录 / is_empty 是否空库位标记(空标记记录不计入 goods 子列表)/ checked_at 该库位最近上报时间(无记录为 null)/ checkers 盘点人去重数组 + goods 作业记录子列表(已知商品与未知商品记录均入内,字段与 workData location 视图一致:record_id 作业记录ID(可调 stock.check.recordDelete / stock.check.recheckClearLocation 移除)/ stock_id 商品库存ID(未知商品为 null)/ item_code 商品编码(未知商品用条码兜底)/ item_name 商品名称(未知商品用名称快照兜底条码)/ barcode 条码 / images 作业记录照片(FileReference business_type=stock_check_record 经 _attachRecordImages 挂载,与 workData/result/recordList 口径一致,无照片为空数组)/ store_id 货主ID(未知商品为 null)/ store_name 货主名(未知商品为 null)/ quantity 实盘数量 / checked_at 上报时间 / checker_name 盘点人;空库位标记记录不计入 goods)。② 商品(id + stock_id,或 detail_id 指向商品范围行):返回该商品的库位分行数据 + 汇总数据 { check_id 盘点任务ID / stock_id 商品库存ID / item_code 商品编码 / item_name 商品名称 / spec 规格 / store_id 货主ID / store_name 货主名 / barcode 条码 / images 商品图片(URL 数组)/ summary 商品级汇总(仅明盘:system_quantity 账面快照合计=该商品各库位明细快照之和 / checked_quantity 实盘合计 / diff_quantity 差异=实盘-账面 / is_diff;盲盘不返回 summary 与任何数量字段)/ rows 按库位分行(每项 detail_id 该库位盘点明细ID(无明细快照的库位为 null)/ location_id 库位ID 与同义字段 space_id(wms_location_space.id,可直接回传 stock.check.report)/ location_code 库位编码 / checked_at 该库位最近上报时间 / checker_name 盘点人 / record_ids 该库位作业记录ID(按记录 id 升序)/ images 作业记录照片;明盘另含 system_quantity 该库位当前账面数量(wms_storage 可用+锁定)/ locked_quantity 该库位锁定数量 / snapshot_quantity 该库位账面快照(盘点开始时的账面)/ checked_quantity 该库位实盘合计 / diff_quantity 该库位差异=实盘-快照;盲盘不含任何数量字段))。分行库位顺序与 workData goods 视图 locations 一致(商品库存库位按拣货路径在前,已盘但当前无库存的库位按首条记录 id 升序追加在末尾,空库位归 location_code=null 组排最后)。仅任务状态 approved(审核完成)或 checking(盘点作业中)可拉取(与 workData 同口径)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -39383,12 +39412,26 @@ } ], "params": [ + { + "name": "id", + "type": "number", + "required": false, + "source": "body", + "description": "盘点任务ID(wms_stock_check.id):商品钻取(id + stock_id)必传" + }, + { + "name": "stock_id", + "type": "number", + "required": false, + "source": "body", + "description": "商品库存ID(wms_stock_warehouse.id):商品钻取必传,与 id 搭配返回该商品的库位分行数据 + 汇总数据(兼容 stockId 驼峰写法)" + }, { "name": "detail_id", "type": "number", - "required": true, + "required": false, "source": "body", - "description": "盘点明细ID(wms_stock_check_detail.id,scope_type=location 的库位范围行;兼容 detailId 驼峰写法)" + "description": "盘点明细ID(兼容 detailId 驼峰写法):库位明细(scope_type=location)必传,返回库位单行;商品范围明细可只传本参数,服务端按明细商品走商品钻取。与 id + stock_id 二选一" } ], "response": [ @@ -39414,7 +39457,7 @@ "name": "data", "type": "object", "required": true, - "description": "业务数据对象(统一 data 层封装:本方法业务数据整体位于 data 内;失败时 data=null),为单行作业数据,结构与 stock.check.workData location 视图单行一致", + "description": "业务数据对象(统一 data 层封装:本方法业务数据整体位于 data 内;失败时 data=null)。结构随入参分流:① 库位明细(detail_id 指向 scope_type=location 行)为单行作业数据,结构与 stock.check.workData location 视图单行一致(下方 children 即该结构);② 商品(id + stock_id)为商品钻取结构 { check_id, stock_id, item_code, item_name, spec, store_id, store_name, barcode, images, summary(仅明盘:system_quantity 账面快照合计/checked_quantity 实盘合计/diff_quantity/is_diff), rows(按库位分行:detail_id/location_id/space_id/location_code/checked_at/checker_name/record_ids/images,明盘另含 system_quantity 当前账面/locked_quantity/snapshot_quantity 账面快照/checked_quantity 实盘/diff_quantity 差异) }② 商品钻取结构补充:账面取值按任务静态标记(is_static)区分:is_static=1(静态盘点)取明细账面快照 system_quantity(盘点基准冻结,不受盘点期间出入库影响);is_static=0(普通盘点)取当前 wms_storage 账面 SUM(available_quantity+locked_quantity);两者都会额外输出 storage_quantity(当前 storage 账面)与 snapshot_quantity(明细快照)供对照,system_quantity 始终为参与差异计算的账面,行/商品额外输出 is_static 与 book_source(snapshot|storage);明细行另含 storage_quantity(该库位当前 storage 账面),差异 diff_quantity=实盘-参与计算的账面。", "children": [ { "name": "detail_id", @@ -39513,18 +39556,20 @@ ], "notes": [ "代码依据:app/service/systemMethods/stock/check.js#workDataDetail(ALL_METHOD_NAMES 由 22 增至 23 个(create,list,addDetail,addLocationDetail,detailDelete,detail,result,workData,workDataDetail,report,markEmpty,recordList,recordDelete,recheckClearLocation,finish,submit,cancel,audit,batchDelete,export,exportTaskProgress,patternList,patternCreate);_noNeedLog 查询类清单新增 workDataDetail(list,detail,result,workData,workDataDetail,recordList,export,exportTaskProgress,patternList);const { detail_id: detailIdSnake, detailId: detailIdCamel } = data || {},detailId=detail_id 未定义时回退 detailId(兼容 detailId 驼峰写法);warehouse_id 由服务端从 ctx.user.store_id 自动注入,前端无需传递,透传 { warehouseId, detailId })+ app/service/systems/stock_check.js#workDataDetail(detailId 非正整数抛 400『盘点明细ID不能为空』;按 id+warehouse_id 查 wms_stock_check_detail 不存在抛 400『盘点明细不存在』;_findCheck 查不到任务抛 400『盘点任务不存在』;任务状态非 REPORT_ALLOWED_STATUSES(approved/checking)抛 400『当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取』;按明细 scope_type 分流:location 走 _buildLocationWorkRows 构建全量库位行并 find 匹配该明细ID、goods 走 _buildGoodsWorkRows 构建全量商品行并 find 匹配该明细ID,未命中抛 400『盘点明细不存在』,命中返回该单行)。本次代码已改并测试通过 216/216、ESLint 0 错误;后续 goods 分支扩展与 locations 商品库位列表口径见下方变更说明。", - "单行口径:响应 data 为单行作业数据,与 stock.check.workData 对应视图单行完全一致(复用同一构建函数 _buildLocationWorkRows/_buildGoodsWorkRows),便于作业端按明细ID刷新单行数据;库位明细(scope_type=location)返回 location 视图单行(detail_id/location_id/location_code/location_name/status/has_unknown/is_empty/checked_at/checkers/goods),商品明细(scope_type=goods)返回 goods 视图单行(detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images/locations 商品所在全部库位列表,明盘另含数量字段)。", + "单行口径:响应 data 为单行作业数据,与 stock.check.workData 对应视图单行完全一致(复用同一构建函数 _buildLocationWorkRows/_buildGoodsWorkRows),便于作业端按明细ID刷新单行数据;库位明细(scope_type=location)返回 location 视图单行(detail_id/location_id/location_code/location_name/status/has_unknown/is_empty/checked_at/checkers/goods),商品明细(scope_type=goods)返回商品钻取结构(id + stock_id 或商品范围 detail_id):{ check_id, stock_id, 商品信息, summary 商品级汇总, rows 按库位分行(detail_id/location_id/space_id/location_code + 账面快照/实盘/差异) },明盘含数量字段、盲盘不含。", "权限口径:随 ALL_METHOD_NAMES(23 个)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(_noNeedAuth)、必须登录(isNeedLogin=true,免登录清单为空);为查询类方法,加入免日志清单 _noNeedLog,不记录操作日志。", "状态限制口径:仅任务状态 approved(审核完成)或 checking(盘点作业中)可拉取,与 stock.check.workData / report / finish 同口径(REPORT_ALLOWED_STATUSES)。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.workDataDetail 一条(位于 stock.check.workData 之后);根版本 0.3.244 → 0.3.245、updatedAt 保持 2026-10-04;methods/changes/system.json 新增本条(插入数组首位);其余 22 条 method 未改动(stock.check 分组由 22 条增至 23 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 与变更记录后,同步回填开发库(WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致。", "goods 明细单行 locations 商品库位列表口径(本次同步 workData 改造):workDataDetail 商品明细分支复用 _buildGoodsWorkRows,locations 为商品所在全部库位列表(库存库位按拣货路径排序在前、无库存但已有作业记录的库位按首条记录 id 升序追加、空库位归 null 组排在最后;明盘每库位含 system_quantity 该库位账面数量(=可用+锁定)、locked_quantity 该库位锁定数量与 quantity 该库位盘点数量(未盘 0),盲盘只返回库位信息);未盘明细 checked_quantity 恒 0、diff_quantity/is_diff 仅存在作业记录时计算(未盘恒 0)。回归测试 222/222 通过、ESLint 0 错误。", - "库位账面口径(本次同步 workData 改造):goods 明细单行 locations 各项库位账面 system_quantity = wms_storage 该库位 SUM(available_quantity+locked_quantity)(可用+锁定),locked_quantity = 该库位 SUM(locked_quantity);盲盘仍不返回任何数量字段。回归测试 222/222 通过、ESLint 0 错误。" + "库位账面口径(本次同步 workData 改造):goods 明细单行 locations 各项库位账面 system_quantity = wms_storage 该库位 SUM(available_quantity+locked_quantity)(可用+锁定),locked_quantity = 该库位 SUM(locked_quantity);盲盘仍不返回任何数量字段。回归测试 222/222 通过、ESLint 0 错误。", + "商品钻取改造(本次,0.3.309):goods 视图改为按商品汇总后行级不再返回明细ID,本方法商品分支新增入参 id(盘点任务ID)+ stock_id(商品库存ID),返回「汇总数据 summary + 按库位分行数据 rows」——summary 为该商品级账面快照合计/实盘合计/差异/is_diff,rows 每个库位一行并给出 detail_id(该库位盘点明细ID)、location_id/space_id(库位ID,可直接回传 stock.check.report)、location_code、system_quantity(该库位当前账面)、snapshot_quantity(该库位账面快照)、checked_quantity(该库位实盘)、diff_quantity(实盘-快照)及 checked_at/checker_name/record_ids/images;原「按明细ID 返回 goods 视图单行」的结构不再返回,兼容入口保留(传商品范围 detail_id 仍返回商品钻取结构,服务端按明细商品解析 id + stock_id);库位明细(scope_type=location)分支不变。代码依据:app/service/systems/stock_check.js#workDataDetail(id + stockId 解析,detail_id 兼容)/#_formatGoodsWorkDetail(summary + rows 组装)。", + "账面取值按静态标记区分(本次,0.3.318):workDataDetail 商品钻取的 summary.system_quantity 与 rows[].system_quantity 统一按任务 is_static 取值(1=明细快照,0=当前 wms_storage),rows[].diff_quantity=checked_quantity - system_quantity;另输出 storage_quantity(当前 storage 账面)、snapshot_quantity(明细快照)、is_static 与 book_source,便于前端展示「盘点基准 vs 当前账面」。代码依据:app/service/systems/stock_check.js#workDataDetail/#_formatGoodsWorkDetail。" ] }, { "method": "stock.check.report", - "description": "盘点作业上报(覆盖式):商品明细行(scope_type=goods)固定上报明细商品(入参 stock_id 与明细商品不一致报错),库位可选(未传归入\"无库位\"分组,location_code 存空串 '');库位明细行(scope_type=location)必须指定商品(stock_id 或 barcode 至少一项),库位以明细库位为准(入参库位与明细库位不一致报错,不传时默认明细库位);空库位标记(is_empty=true,仅库位明细行支持):确认该库位为空——不要求商品/条码,quantity 恒为 0,写一条特殊作业记录(stock_id=null、barcode=null、item_name=null、quantity=0、is_empty=1);与商品记录互斥:标记空时删除该明细下所有商品记录(含未知商品),上报商品时删除该明细下空标记记录;商品明细行传 is_empty 报 400「仅库位盘点明细支持空库位标记」。覆盖式查重:已知商品维度 detail_id+stock_id+location_code、未知商品维度 detail_id+stock_id IS NULL+barcode+location_code,同明细+同商品+同库位重复上报时更新已有记录(quantity/checker_id/checker_name/checked_at,保留原 location_id,本次新匹配到 location_id 则回填),不再新增;仅 approved/checking 状态允许;**space_id 必传**(库位以该 ID 为准,传了 location 编码则仅做一致性校验,服务端不再按编码猜库位,缺失报 400「缺少库位ID(space_id)」);实盘数量上限 2147483647(超出报 400「实盘数量不能超过 2147483647」,避免落库列 int(12) 越界变成 500);主表 approved 首次上报自动转 checking;完成后重算 checked_items/diff_items/detail_status(已盘口径=存在记录的明细数,差异=记录数量合计-账面:商品行 vs system_quantity 快照、库位行按商品 vs wms_storage 账面;未知商品无账面,实盘>0 即盘盈、必然计入差异;空标记记录同样计入已盘明细(checked_items/detail_status),空标记明细的库位账面有库存即计盘亏差异(diff_items));数据库层由唯一索引 uk_detail_stock_location(detail_id, stock_id, location_code) 保证已知商品覆盖式上报并发安全(并发下不产生重复记录),未知商品(stock_id=NULL)唯一索引不约束 NULL 行、应用层查重兜底。主表 start_time 为空时以本次明细写入时间补写(首个盘点明细写入时间记录为 start_time,即盘点开始时间)。未知商品上报(stock_id 与 barcode 至少传一项):仅传 barcode → 先按条码匹配系统商品(wms_stock_barcodes 按 barcode+本仓库,关联 StockWarehouse 校验商品属于本仓库),命中回填 stock_id 走已知商品逻辑;未命中记录未知商品(stock_id=NULL+barcode+item_name,item_name 缺省为 barcode);都未传沿用原报错口径。", + "description": "盘点作业上报(覆盖式):**detail_id 可选**——goods 汇总视图行(stock.check.workData)不再返回明细ID,商品行可只传 id + stock_id + space_id,服务端按「该商品在该库位(location_id=space_id)的明细 → 该商品任一明细」顺序反查明细后落库(反查不到报 400「盘点明细不存在(该商品不在本任务盘点范围内,或库位盘点任务需传 detail_id)」),库位盘点行仍必传 detail_id;商品明细行(scope_type=goods)固定上报明细商品(入参 stock_id 与明细商品不一致报错),库位可选(未传归入\"无库位\"分组,location_code 存空串 '');库位明细行(scope_type=location)必须指定商品(stock_id 或 barcode 至少一项),库位以明细库位为准(入参库位与明细库位不一致报错,不传时默认明细库位);空库位标记(is_empty=true,仅库位明细行支持):确认该库位为空——不要求商品/条码,quantity 恒为 0,写一条特殊作业记录(stock_id=null、barcode=null、item_name=null、quantity=0、is_empty=1);与商品记录互斥:标记空时删除该明细下所有商品记录(含未知商品),上报商品时删除该明细下空标记记录;商品明细行传 is_empty 报 400「仅库位盘点明细支持空库位标记」。覆盖式查重:已知商品维度 detail_id+stock_id+location_code、未知商品维度 detail_id+stock_id IS NULL+barcode+location_code,同明细+同商品+同库位重复上报时更新已有记录(quantity/checker_id/checker_name/checked_at,保留原 location_id,本次新匹配到 location_id 则回填),不再新增;仅 approved/checking 状态允许;**space_id 必传**(库位以该 ID 为准,传了 location 编码则仅做一致性校验,服务端不再按编码猜库位,缺失报 400「缺少库位ID(space_id)」);实盘数量上限 2147483647(超出报 400「实盘数量不能超过 2147483647」,避免落库列 int(12) 越界变成 500);主表 approved 首次上报自动转 checking;完成后重算 checked_items/diff_items/detail_status(已盘口径=存在记录的明细数,差异=记录数量合计-账面:商品行 vs system_quantity 快照、库位行按商品 vs wms_storage 账面;未知商品无账面,实盘>0 即盘盈、必然计入差异;空标记记录同样计入已盘明细(checked_items/detail_status),空标记明细的库位账面有库存即计盘亏差异(diff_items));数据库层由唯一索引 uk_detail_stock_location(detail_id, stock_id, location_code) 保证已知商品覆盖式上报并发安全(并发下不产生重复记录),未知商品(stock_id=NULL)唯一索引不约束 NULL 行、应用层查重兜底。主表 start_time 为空时以本次明细写入时间补写(首个盘点明细写入时间记录为 start_time,即盘点开始时间)。未知商品上报(stock_id 与 barcode 至少传一项):仅传 barcode → 先按条码匹配系统商品(wms_stock_barcodes 按 barcode+本仓库,关联 StockWarehouse 校验商品属于本仓库),命中回填 stock_id 走已知商品逻辑;未命中记录未知商品(stock_id=NULL+barcode+item_name,item_name 缺省为 barcode);都未传沿用原报错口径。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -39546,9 +39591,9 @@ { "name": "detail_id", "type": "number", - "required": true, + "required": false, "source": "body", - "description": "盘点明细ID" + "description": "盘点明细ID(wms_stock_check_detail.id):库位明细行必传;商品行可选——不传时按 id + stock_id + space_id 反查该商品的库位明细(先按 location_id=space_id 命中,未命中取该商品任一明细)" }, { "name": "location", @@ -39576,7 +39621,7 @@ "type": "number", "required": false, "source": "body", - "description": "商品库存ID(wms_stock_warehouse.id);商品明细行可选(传入必须与明细商品一致,否则报错);库位明细行必填(或改传 barcode 按条码匹配),商品必须属于本仓库" + "description": "商品库存ID(wms_stock_warehouse.id);商品明细行可选(传入必须与明细商品一致,否则报错);未传 detail_id 时必传,用于反查该商品的盘点明细;库位明细行必填(或改传 barcode 按条码匹配),商品必须属于本仓库" }, { "name": "barcode", @@ -39699,7 +39744,8 @@ "汇总口径(本次同步 _recalcCheckSummary):空库位标记记录计入已盘明细(checked_items 按 DISTINCT detail_id 自然计入、detail_status 按已盘占比正常推进);差异口径:空标记明细的库位账面(wms_storage 按 space_id SUM(available_quantity+locked_quantity)=可用+锁定)有库存即计盘亏差异(diff_items 加 1),账面无库存不计差异。代码依据:app/service/systems/stock_check.js#_recalcCheckSummary。", "迁移依据:database/migrations/20261002160000-add-is-empty-to-stock-check-record.js(wms_stock_check_record 新增 is_empty TINYINT(1) NOT NULL DEFAULT 0,COMMENT 是否空库位标记(1=确认为空),开发与生产库均已执行)。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.report:params 新增 is_empty 入参、errors 400 补「仅库位盘点明细支持空库位标记」、description/response/notes 补充空库位语义与互斥及汇总口径;stock.check.workData:description/response.rows 的 location 行新增 is_empty 字段说明;stock.check.result:description/response.rows 库位行新增 is_empty 与空标记盘亏口径;stock.check.recordList:response.rows 记录全字段说明新增 is_empty;stock.check.export:description/notes 补 Sheet2 空库位行输出口径);根版本 0.3.233 → 0.3.234、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 15 条 method 未改动(stock.check 分组仍为 20 条)。", - "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。" + "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。", + "detail_id 可选改造(本次,0.3.309):goods 视图按商品汇总后行级不再带明细ID,report 放宽 detail_id 为可选——未传时按 id + stock_id + space_id 反查明细(先查 check_id + warehouse_id + stock_id + location_id=space_id,未命中取该商品任一明细,货主/仓库隔离条件不变),反查不到返回 400「盘点明细不存在(该商品不在本任务盘点范围内,或库位盘点任务需传 detail_id)」;既未传 detail_id 也未传 stock_id 仍返回 400「盘点明细ID不能为空」;落库口径不变(作业记录仍挂 detail_id,覆盖式查重仍按 detail_id+stock_id+location_code)。代码依据:app/service/systems/stock_check.js#report(resolvedDetailRowId 解析)。" ] }, { @@ -40325,7 +40371,7 @@ "name": "data", "type": "object", "required": true, - "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)(另含 released_stock_ids:本次完成释放的静态锁定商品ID数组)", "children": [ { "name": "id", @@ -40374,6 +40420,12 @@ "type": "number", "required": true, "description": "盘亏合计(商品行:实盘小于账面快照的差异绝对值合计,含未盘明细的账面快照数;库位行:按商品实盘小于 wms_storage 账面的差异绝对值合计)" + }, + { + "name": "released_stock_ids", + "type": "array", + "required": true, + "description": "本次完成盘点释放的静态锁定商品ID数组(本任务商品明细覆盖的 stock_id,升序;库位盘点任务为空数组)" } ] }, @@ -40398,7 +40450,9 @@ "库位行账面口径:wms_storage 按 (space_id, stock_id) SUM(available_quantity+locked_quantity)(=可用+锁定),与 detail 接口的 stocks 账面一致。", "未盘库位明细行无法枚举商品(无作业记录即无商品维度),完成时不计差异、不计盘盈盘亏。", "end_time 语义:完成盘点时主表写入 end_time(完成盘点的时间);接口响应不返回 end_time(响应结构不变:id/status/total_items/checked_items/unchecked_items/diff_items/profit_total/loss_total),主表时间字段请通过 detail/result/list 查看。", - "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" + "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", + "完成即释放锁定(本次,0.3.313):finish 成功后清除本仓库静态锁定缓存(stock_check:static_lock:{warehouseId}),并返回 released_stock_ids(本任务商品明细覆盖的 stock_id,升序;库位任务为空数组),操作日志 STOCK_CHECK_FINISH 的 extras 同步落 releasedStockIds 与「释放静态锁定商品 N 个」文案;若同一商品仍被其它 approved/checking 的静态任务覆盖,则仍保持锁定(缓存回源后自动保留其它任务)。缓存清除失败只记 warn 日志不影响完成主流程,靠 300 秒 TTL 兜底。代码依据:app/service/systems/stock_check.js#finish/#_collectGoodsStockIds/#clearStaticLockCache。", + "缓存代次(本次,0.3.315):本方法成功后调用 refreshStaticLockCache——先递增 `stock_check:static_lock_gen:{warehouseId}` 再重建锁定缓存,使并发中的旧回源自动失效,避免脏读。" ] }, { @@ -40485,7 +40539,8 @@ "提交校验口径(本次扩展):全部明细行(库位型 scope_type=location 与商品型 scope_type=goods)缺少库位(location_id 为空或 location_code 为空/空串)时抛 400「存在缺少库位的盘点明细,无法提交审核」——校验不再限定 scope_type=location(商品任务按「商品+库位」拆行后商品行同样必须带库位),脏数据防御,正常流程 addDetail/addLocationDetail 写入的明细均带有效库位。代码依据:app/service/systems/stock_check.js#submit(StockCheckDetail.count where check_id+(location_id 为空或 location_code 为空/空串)>0 即拒绝,不再按 scope_type 过滤)。本次代码已改并测试通过 213/213、ESLint 0 错误。", "影响面:前端无需改动——该校验拦截缺库位明细(含商品拆行后缺库位的历史脏数据),正常盘点流程不受影响;原有校验顺序不变(任务ID 为空→任务不存在→状态非 created/rejected→无明细行→缺库位明细)。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.addDetail:description/params/response/notes 补商品拆行口径(拆多行、无库存库位 invalid、system_quantity=该库位账面、added=拆分行数);stock.check.detail:description/response.rows/notes 商品行 location_id/location_code 绑定库存库位;stock.check.submit:description/notes 缺库位校验改为覆盖全部明细行;stock.check.patternCreate:description/notes 补 goods 定式按库存库位拆行;stock.check.addLocationDetail:notes 幂等索引口径同步 uk_check_location 唯一约束放宽为普通索引 idx_check_location);根版本 0.3.237 → 0.3.238、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 17 条 method 未改动(stock.check 分组仍为 22 条)。", - "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 与变更记录后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 22 条 method 无损。" + "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 与变更记录后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 22 条 method 无损。", + "快照刷新口径补充(本次,0.3.312):submit 仍会在提交时刷新商品范围明细账面快照(提交时点账面);若任务随后审核通过,audit 会再次刷新为「审核完成=开始盘点」时点的账面,最终以审核时点为准。" ] }, { @@ -40572,7 +40627,7 @@ }, { "method": "stock.check.audit", - "description": "审核盘点任务:仅 submitted 状态允许;action=approve → 主表置 approved(审核完成,待盘点作业);action=reject → 主表置 rejected(驳回,可重新添加明细再提交),reason 可选(缺省保留原备注)。", + "description": "审核盘点任务(approve 通过时会把商品范围明细的账面快照刷新为审核时点账面,并解除/进入静态盘点锁定缓存):仅 submitted 状态允许;action=approve → 主表置 approved(审核完成,待盘点作业);action=reject → 主表置 rejected(驳回,可重新添加明细再提交),reason 可选(缺省保留原备注)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -40642,6 +40697,12 @@ "type": "string", "required": true, "description": "审核后的主表状态:approved(通过)/ rejected(驳回)" + }, + { + "name": "snapshot_refreshed", + "type": "number", + "required": true, + "description": "本次刷新账面快照的商品明细行数(仅 approve 且值发生变化时非 0;驳回或无需刷新为 0)" } ] }, @@ -40663,7 +40724,9 @@ } ], "notes": [ - "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" + "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", + "审核刷新快照 + 解锁缓存(本次,0.3.312):① approve 时调用 _refreshGoodsBookSnapshot 把 scope_type=goods 明细行的 system_quantity 刷新为该库位当前账面 SUM(可用+锁定)(提交审核后到审核前发生的出入库会被覆盖,保证「审核完成=开始盘点」即基准时点),返回新增 snapshot_refreshed 字段(本次刷新的明细行数,仅值有变化的行计数;驳回恒 0);② approve/reject 均清除静态盘点锁定缓存(approve 使 is_static 任务进入锁定集合):submit 时已刷新一次快照,audit approve 再刷新一次,两者共同保证快照口径。代码依据:app/service/systems/stock_check.js#audit/#_refreshGoodsBookSnapshot。", + "缓存代次(本次,0.3.315):本方法成功后调用 refreshStaticLockCache——先递增 `stock_check:static_lock_gen:{warehouseId}` 再重建锁定缓存,使并发中的旧回源自动失效,避免脏读。" ] }, { @@ -41349,7 +41412,7 @@ "name": "check", "type": "object", "required": true, - "description": "创建后的盘点任务信息(_formatCheckRow 口径:id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at,无 check_date);status 直接为 submitted(待审核),mode 由定式范围类型固定(location→blind、goods→open),start_time/end_time 创建时为空(分别由首个盘点明细写入与完成盘点回填)" + "description": "创建后的盘点任务信息(_formatCheckRow 口径:id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at,无 check_date);status 直接为 submitted(待审核),mode 由定式范围类型固定(location→blind、goods→open),start_time/end_time 创建时为空(分别由首个盘点明细写入与完成盘点回填)(另含 is_static:静态定式创建的任务为 1,其余为 0)" }, { "name": "total_items", @@ -41390,7 +41453,9 @@ "权限口径:免 API 权限(isNeedAuth=false)、免仓库有效期鉴权、必须登录(isNeedLogin=true);patternCreate 为写操作,不在免日志清单(_noNeedLog)中,记录操作日志(patternList 为查询类,免日志)。", "单号生成:check_no=PD+YYYYMMDD+6 位序号(全局递增不按仓库隔离),并发下撞 uk_check_no 唯一键自动重取重试(最多 5 次)。", "goods 定式拆行口径(本次改造):商品类定式(mis_shipment/expiring/static/warning,type=goods)收集到 stock_ids 后走 _addGoodsDetailRows 同款逻辑——按商品在仓库的启用库存库位(wms_storage is_enabled=1 且库位有效(未删除且所属 zone 存在未删除,排除无头库位),按 space_id 分组 SUM)拆行,每个「商品+库位」一条 scope_type=goods 明细行(location_id/location_code 绑定库存库位、system_quantity=该库位库存 SUM);无启用库存库位的商品不产生明细行,total_items 按拆分行重算。代码依据:app/service/systems/stock_check.js#patternCreate(pattern.type==='goods' 调 _addGoodsDetailRows)。", - "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" + "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", + "静态定式自动标记(本次,0.3.310):patternCreate 按定式创建任务时,pattern_id=static(静态盘点定式)的主表 is_static 自动写 1,其余定式(empty_location/mis_shipment/expiring/warning)写 0;返回的 check 与 GET 一样透出 is_static。代码依据:app/service/systems/stock_check.js#patternCreate(normalizedIsStatic = pattern.id === 'static' ? 1 : 0)。", + "静态定式口径收窄(本次,0.3.311):只有 pattern=static(商品类定式,type=goods)创建的任务 is_static=1;库位类定式(empty_location 等 type=location)与其它商品定式(mis_shipment/expiring/warning)均为 0,保证「库位盘点恒为普通盘点」。代码依据:app/service/systems/stock_check.js#patternCreate(pattern.id === 'static' && pattern.type !== 'location')。" ] }, { @@ -41496,6 +41561,117 @@ "ID 直查:按 wms_location_space.id+warehouse_id 直查校验(仓库隔离),查不到的 ID 记入 invalid_location_ids(不报错);幂等按 check_id+location_code(原 uk_check_location 唯一约束已放宽为普通索引 idx_check_location,幂等由应用层查重保证),已存在同库位明细跳过。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。" ] + }, + { + "method": "stock.check.staticLockList", + "description": "拉取「静态盘点锁定中」的库存商品列表(公共查询,供出入库/移库等库存操作前置判断是否可以动该商品):warehouse_id 由服务端从当前上下文自动注入,前端无需传参;口径为 wms_stock_check 中 is_static=1 且状态为 approved(审核完成)/checking(盘点作业中)的任务,取其商品范围明细(scope_type=goods)的 stock_id 去重集合——审核完成即开始锁定,任务完成/取消后解除;提交审核前(created/submitted/rejected)与已完成/已取消均不锁定;库位盘点任务 is_static 恒为 0,天然不参与。结果按仓库维度缓存在 `stock_check:static_lock:{warehouseId}`(默认 TTL 300 秒,Redis 优先、不可用时降级进程内缓存),审核/完成/取消/批量删除等状态流转时主动失效,返回 cached 标识本次是否命中缓存。返回 { warehouse_id, stock_ids, rows, total, cached, updated_at }:stock_ids 为锁定商品ID数组(升序);rows 每个 stock_id 一条 { stock_id, item_code, item_name, check_ids 来源盘点任务ID数组, check_nos 来源盘点单号数组, location_codes 该商品在盘子任务中的库位编码数组 };total=rows 行数;cached=true 表示命中缓存;updated_at=缓存生成时间(ISO 8601,命中缓存时为上次回源时间)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [], + "response": [ + { + "name": "flag", + "type": "string", + "required": true, + "description": "请求结果标记:success=成功 / failure=失败" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息:成功为 ok;失败为具体错误文案" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装;失败时 data=null)", + "children": [ + { + "name": "warehouse_id", + "type": "number", + "required": true, + "description": "仓库ID(由 ctx.user.store_id 注入)" + }, + { + "name": "stock_ids", + "type": "array", + "required": true, + "description": "静态盘点锁定中的库存商品ID数组(wms_stock_warehouse.id,按 stock_id 升序;无锁定时为空数组)" + }, + { + "name": "rows", + "type": "array", + "required": true, + "description": "锁定商品明细行(每个 stock_id 一条):stock_id 商品库存ID / item_code 商品编码(明细快照)/ item_name 商品名称(明细快照)/ check_ids 来源盘点任务ID数组 / check_nos 来源盘点单号数组 / location_codes 该商品在本任务中的库位编码数组" + }, + { + "name": "total", + "type": "number", + "required": true, + "description": "锁定商品数量(=rows.length)" + }, + { + "name": "cached", + "type": "boolean", + "required": true, + "description": "本次是否命中缓存:true=命中缓存(含审核/完成等状态流转后立即重建的缓存),false=回源数据库并已写入缓存;并发未命中时由 singleflight 共用同一次回源,各请求均返回 cached=false 且数据一致" + }, + { + "name": "cache_skipped", + "type": "boolean", + "required": false, + "description": "仅当本次回源期间检测到并发状态流转(锁定代次变化)时返回 true:表示本次结果未写入缓存(避免脏读),数据仍可正常使用" + }, + { + "name": "updated_at", + "type": "string", + "required": true, + "description": "缓存生成时间(ISO 8601;命中缓存时为上次回源生成时间)" + } + ] + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" + } + ], + "errors": [ + { + "code": 400, + "message": "无法获取当前仓库上下文(缺少 ctx.user.store_id / 未登录)" + }, + { + "code": 500, + "message": "服务器内部错误(缓存与数据库均不可用等未预期异常)" + } + ], + "notes": [ + "业务动机:静态盘点(is_static=1)期间商品库位正在清点,若同时发生出入库/移库会导致实盘数与账面基准错位;本方法对外暴露「锁定中的商品清单」并提供 isStockStaticLocked(warehouseId, stockId) 内部判断(读同一份缓存),供库存操作(出库分配、移库、拣货等)做前置拦截。", + "锁定口径:status ∈ {approved(审核完成), checking(盘点作业中)}——审核完成即开始锁定;提交审核前不锁(明细与快照仍可调整);completed/cancelled/rejected 解锁。库位盘点(type=location)的 is_static 恒为 0(见 0.3.311),因此只有商品盘点(store/goods)任务会进入锁定集合。", + "缓存设计:键 `stock_check:static_lock:{warehouseId}`,值 { warehouse_id, stock_ids, rows, updated_at },TTL 300 秒兜底;写入/读取走 app.setCacheAsync / getCacheAsync(Redis 优先,Redis 不可用或异常时降级进程内缓存)。状态流转(audit/finish/cancel/batchDelete)不是「删除缓存等下次回源」,而是**先递增锁定代次、再立即重建**:代次见 `stock_check:static_lock_gen:{warehouseId}`(Redis INCR,无 Redis 时进程内计数),回源查询前后各读一次,两次不一致说明查询期间发生过状态流转 → 本次结果可能是旧快照,**放弃写缓存并删除缓存**,交由下一次查询/该次流转的重建写入,避免脏读覆盖。", + "缓存失效时机(主动 delCacheAsync):audit(approve/reject)、finish、cancel、batchDelete;失效失败只记 warn 日志不影响主流程,靠 TTL 兜底。addDetail/detailDelete 仅在 created/rejected 状态可用(不在锁定集合内),因此不需要失效。", + "性能:回源仅 2 条查询(主表按 warehouse+is_static+status 取任务,明细按 check_id + scope_type=goods 取 stock_id),商品数量级很小;库存操作侧建议直接调 isStockStaticLocked 走缓存,避免每条单据回源。", + "代码依据:app/service/systems/stock_check.js#staticLockList/#isStockStaticLocked/#clearStaticLockCache、app/service/systemMethods/stock/check.js#staticLockList(ALL_METHOD_NAMES 25 个、免日志清单新增 staticLockList)。", + "缓存策略答疑(本次,0.3.314):① TTL=300 秒仅为兜底,正常情况每个状态流转都会立即重建缓存;② 缓存未命中会回源(2 条 SQL:主表 is_static+status,明细 scope_type=goods),但**空集合也会被缓存**,不存在「没有锁定商品 → 每次都查库」的缓存穿透;③ 失效瞬间的并发查询由进程内 singleflight(STATIC_LOCK_INFLIGHT)去重,同一仓库只回源一次,避免击穿;④ 新审核通过的任务在 audit(approve) 返回前就已完成缓存重建,之后的查询立即包含该任务,无「审核后仍读到旧缓存」的窗口(除非缓存重建失败,此时删除缓存 → 下次查询回源,仍能保证最多 300 秒内自愈);⑤ 多 worker/多实例:Redis 可用时所有实例共享同一份缓存,重建对全体生效;仅当 Redis 整体不可用时各实例退化为进程内缓存,重建只影响当前实例,其它实例最长 300 秒后(TTL)自愈——此降级场景下建议库存操作侧对「锁定判定失败/缓存不可用」采取保守策略(fail-safe,按锁定处理)。代码依据:app/service/systems/stock_check.js#staticLockList/#_loadStaticLockCache/#refreshStaticLockCache(STATIC_LOCK_INFLIGHT、STATIC_LOCK_CACHE_TTL_SECONDS)。", + "防脏读代次校验(本次,0.3.315):审核/完成/取消/批量删除统一走 refreshStaticLockCache = 递增代次 → 回源 → 写缓存;任何并发中的回源(含普通查询未命中回源)在拿到查询结果后会再读一次代次,若与查询前不一致就跳过写入(响应带 cache_skipped=true 且不落缓存),因此不会出现「旧快照后写覆盖新缓存」的脏读;读取侧仍按缓存优先,缓存为空时回源不影响正确性,最坏只多一次查询。代码依据:app/service/systems/stock_check.js#refreshStaticLockCache/#_loadStaticLockCache/#_readStaticLockGeneration/#_bumpStaticLockGeneration。" + ] } ] }, diff --git a/script/stock-check-goods-summary-verify.cjs b/script/stock-check-goods-summary-verify.cjs new file mode 100644 index 0000000..e0e7634 --- /dev/null +++ b/script/stock-check-goods-summary-verify.cjs @@ -0,0 +1,182 @@ +'use strict'; + +/** + * 开发环境实测脚本:盘点商品视图汇总 + workDataDetail 商品钻取 + report 免 detail_id。 + * + * 直连本地开发库(config.local.js,127.0.0.1:3307),全程走 systemMethods 方法层(含统一 success 包装), + * 完整复现一条盘点到上报链路: + * 1. 取一个多库位库存商品(模拟同 stock_id 多条库位明细); + * 2. create → addDetail → submit → audit(approve); + * 3. report 只传 id + stock_id + space_id(不传 detail_id),验证反查明细; + * 4. workData(is_goods=true) 校验商品视图汇总(行级无 detail_id、locations 带 detail_id/snapshot_quantity); + * 5. workDataDetail(id + stock_id) 校验 summary + 按库位分行(明细ID/库位ID/账面快照/实盘/差异); + * 6. 交叉校验明细快照合计 = goods 行级账面 = summary 账面,分行实盘合计 = 行级实盘 = summary 实盘。 + * + * 数据策略:脚本会在开发库新建一条盘点任务(单号 PD+日期+序号,标题以「实测_商品汇总_」开头) + * 作为核对样张保留,不做清理;不要在预发/生产库执行。 + * + * 用法:node script/stock-check-goods-summary-verify.cjs + */ + +const mm = require('egg-mock'); + +const WAREHOUSE_ID = 100000; +const CREATOR_ID = 4; +const CREATOR_NAME = '阿猫'; + +function log(title, payload) { + console.log(`\n===== ${title} =====`); + console.log(typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2)); +} + +(async () => { + const app = mm.app({ + baseDir: process.cwd(), + env: 'local', + clean: false, + cache: false, + }); + await app.ready(); + const ctx = app.createAnonymousContext(); + ctx.user = { id: CREATOR_ID, store_id: WAREHOUSE_ID, employees_name: CREATOR_NAME }; + const { Op, literal } = app.Sequelize; + + const validSpaceSql = '(SELECT ls.id FROM wms_location_space ls ' + + 'JOIN wms_location_zone z ON z.id = ls.zone_id AND z.deleted_at IS NULL ' + + 'WHERE ls.deleted_at IS NULL)'; + + try { + // 1. 找一个在两个及以上有效库位都有库存的商品(模拟生产里同 stock_id 多库位明细的场景) + const storageRows = await ctx.model.Storage.findAll({ + where: { + warehouse_id: WAREHOUSE_ID, + is_enabled: 1, + space_id: { [Op.in]: literal(validSpaceSql) }, + }, + attributes: [ 'stock_id', 'space_id', [ literal('SUM(available_quantity + locked_quantity)'), 'qty' ]], + group: [ 'stock_id', 'space_id' ], + raw: true, + }); + const spacesByStock = new Map(); + for (const row of storageRows) { + const stockId = Number(row.stock_id); + if (!spacesByStock.has(stockId)) { + spacesByStock.set(stockId, []); + } + spacesByStock.get(stockId).push(row); + } + const multiEntry = [ ...spacesByStock.entries() ] + .filter(([ , rows ]) => rows.length >= 2) + .sort((left, right) => left[0] - right[0])[0]; + if (!multiEntry) { + throw new Error('开发库中未找到多库位库存商品,无法实测汇总口径'); + } + const [ stockId, stockSpaces ] = multiEntry; + const stock = await ctx.model.StockWarehouse.findOne({ where: { id: stockId, warehouse_id: WAREHOUSE_ID }, raw: true }); + log('1. 选中的多库位商品', { + stock_id: stockId, + item_code: stock.item_code, + item_name: stock.item_name, + store_id: stock.store_id, + spaces: stockSpaces.map(row => ({ space_id: Number(row.space_id), qty: Number(row.qty) })), + }); + + // 2. 创建任务 → 添加明细 → 提交 → 审核(走方法层,含 success 包装) + const created = await ctx.service.systemMethods.stock.check.create({ + title: `实测_商品汇总_${Date.now()}`, + type: 'goods', + mode: 'open', + store_id: stock.store_id || undefined, + }); + if (created.flag !== 'success') { + throw new Error(`create 失败: ${created.message}`); + } + const checkId = Number(created.data.id); + + const added = await ctx.service.systemMethods.stock.check.addDetail({ id: checkId, stock_ids: [ stockId ] }); + console.log(`\n2. 任务创建 ${created.data.check_no}(id=${checkId}),添加明细:added=${added.data.added} skipped=${added.data.skipped}`); + + await ctx.service.systemMethods.stock.check.submit({ id: checkId }); + const audited = await ctx.service.systemMethods.stock.check.audit({ id: checkId, action: 'approve' }); + if (audited.flag !== 'success') { + throw new Error(`audit 失败: ${JSON.stringify(audited)}`); + } + + const detailRows = await ctx.model.StockCheckDetail.findAll({ + where: { check_id: checkId, scope_type: 'goods' }, + order: [[ 'id', 'ASC' ]], + raw: true, + }); + log('3. 明细行(商品按库位拆行,账面快照逐库位)', detailRows.map(row => ({ + detail_id: Number(row.id), + stock_id: Number(row.stock_id), + location_id: Number(row.location_id), + location_code: row.location_code, + system_quantity: Number(row.system_quantity), + }))); + + // 4. report 免 detail_id:只传 id + stock_id + space_id(goods 汇总视图行不再带明细ID) + const reportTargets = detailRows.slice(0, 2); + for (const [ index, detailRow ] of reportTargets.entries()) { + const reported = await ctx.service.systemMethods.stock.check.report({ + id: checkId, + stock_id: stockId, + space_id: Number(detailRow.location_id), + quantity: index === 0 ? 7 : 3, + }); + log(`4.${index + 1} report 免 detail_id(space_id=${detailRow.location_id})`, { + flag: reported.flag, + code: reported.code, + message: reported.message, + resolved_detail_id: reported.data && reported.data.detail_id, + record: reported.data && { + id: reported.data.record.id, + detail_id: reported.data.record.detail_id, + stock_id: reported.data.record.stock_id, + location_id: reported.data.record.location_id, + location_code: reported.data.record.location_code, + quantity: reported.data.record.quantity, + }, + }); + } + + // 5. workData goods 视图:一个商品一行,行级无 detail_id,locations 带 detail_id/snapshot_quantity + const workData = await ctx.service.systemMethods.stock.check.workData({ id: checkId, is_goods: true }); + const goodsRow = workData.data.rows[0]; + log('5. workData(is_goods=true) 商品视图行', { + view: workData.data.view, + total: workData.data.total, + row: goodsRow, + }); + console.log(' → 行级是否含 detail_id:', Object.prototype.hasOwnProperty.call(goodsRow, 'detail_id')); + + // 6. workDataDetail 商品钻取:id + stock_id → summary + rows + const drill = await ctx.service.systemMethods.stock.check.workDataDetail({ id: checkId, stock_id: stockId }); + log('6. workDataDetail(id + stock_id) 商品钻取', { + flag: drill.flag, + data: drill.data, + }); + + // 7. 口径交叉校验 + const snapshotTotal = detailRows.reduce((sum, row) => sum + Number(row.system_quantity), 0); + const rowsChecked = drill.data.rows.reduce((sum, row) => sum + Number(row.checked_quantity), 0); + log('7. 口径交叉校验', { + 明细快照合计: snapshotTotal, + 'goods 行级 system_quantity': goodsRow.system_quantity, + 'goods 行级 checked_quantity': goodsRow.checked_quantity, + 'drill.summary.system_quantity': drill.data.summary.system_quantity, + 'drill.summary.checked_quantity': drill.data.summary.checked_quantity, + 'drill.rows 实盘合计': rowsChecked, + 'locations[].detail_id': goodsRow.locations.map(item => ({ code: item.location_code, detail_id: item.detail_id, snapshot: item.snapshot_quantity })), + 一致: snapshotTotal === goodsRow.system_quantity + && goodsRow.system_quantity === drill.data.summary.system_quantity + && goodsRow.checked_quantity === drill.data.summary.checked_quantity + && rowsChecked === drill.data.summary.checked_quantity, + }); + } finally { + await app.close(); + } +})().catch(error => { + console.error('实测失败:', error && error.stack || error); + process.exit(1); +}); diff --git a/test/app/service/systems/static_lock_guard.test.js b/test/app/service/systems/static_lock_guard.test.js new file mode 100644 index 0000000..1e0c1ac --- /dev/null +++ b/test/app/service/systems/static_lock_guard.test.js @@ -0,0 +1,350 @@ +'use strict'; + +const assert = require('node:assert/strict'); +const Sequelize = require('sequelize'); +const InventoryService = require('../../../../app/service/systems/storage/inventory'); +const OrderStorageAllocationService = require('../../../../app/service/systems/order_storage_allocation'); + +/** + * 构造锁定冲突桩(模拟 stock_check.getStaticLockConflict)。 + * + * @param {boolean} locked 是否锁定。 + * @return {Object} 桩服务。 + */ +function createStockCheckStub(locked) { + const calls = []; + return { + calls, + async getStaticLockConflict(params = {}) { + calls.push(params); + if (!locked) { + return { locked: false, rows: [], message: '' }; + } + return { + locked: true, + rows: [{ stock_id: 301, item_code: 'LOCKED-ITEM', check_nos: [ 'PD20261028000001' ], check_ids: [ 1 ] }], + message: '商品正在静态盘点中,禁止移库:LOCKED-ITEM(301) 盘点单 PD20261028000001', + }; + }, + }; +} + +/** + * 创建移库(transferLocation)测试上下文。 + * + * @param {boolean} locked 静态盘点是否锁定。 + * @return {Object} { service, captures, stockCheck }。 + */ +function createTransferLocationHarness(locked) { + const captures = { rollbacks: 0, commits: 0, storageUpdates: 0, storageTransactions: 0 }; + const stockCheck = createStockCheckStub(locked); + const srcRecord = { + id: 11, + warehouse_id: 100000, + store_id: 100001, + space_id: 21, + stock_id: 301, + batch_no: 'B1', + inventory_type: 'ZP', + quantity: 10, + locked_quantity: 0, + intercept_locked_quantity: 0, + available_quantity: 10, + is_enabled: 1, + delete_at: null, + }; + + const ctx = { + app: { Sequelize }, + logger: { info() {}, warn() {}, error() {} }, + user: { employees_id: 'E1', employees_name: '测试员' }, + model: { + async transaction() { + return { + LOCK: { UPDATE: 'UPDATE' }, + async commit() { captures.commits += 1; }, + async rollback() { captures.rollbacks += 1; }, + }; + }, + Storage: { + async findOne() { + return srcRecord; + }, + async update() { + captures.storageUpdates += 1; + }, + async count() { + return 0; + }, + async findAll() { + return [ srcRecord ]; + }, + async create() { + return srcRecord; + }, + }, + StockWarehouse: { + async findOne() { + return { id: 301, quantity: 10, locked_quantity: 0, warehouse_id: 100000, is_batch_mgmt: 'N' }; + }, + }, + LocationSpace: { + async findOne() { + return { id: 22, warehouse_id: 100000, is_enabled: true, space_status: 'AVAILABLE', space_code: 'A-22' }; + }, + async update() { return null; }, + }, + StorageTransaction: { + async create() { + captures.storageTransactions += 1; + return { id: 1 }; + }, + }, + }, + service: { + systems: { + stockCheck, + operationLog: { async createOperationLog() { return null; } }, + notice: { async send() { return null; } }, + }, + }, + }; + + return { service: new InventoryService(ctx), captures, stockCheck }; +} + +describe('静态盘点锁定拦截:分配储位 / 移库', () => { + it('transferLocation:商品静态盘点中 → 400、事务回滚、不写库存', async () => { + const { service, captures, stockCheck } = createTransferLocationHarness(true); + const result = await service.transferLocation({ storage_id: 11, target_space_id: 22, quantity: 1 }); + + assert.equal(result.code, 400); + assert.match(result.message, /静态盘点/); + assert.match(result.message, /PD20261028000001/); + assert.equal(captures.rollbacks, 1, '命中锁定应回滚事务'); + assert.equal(captures.storageUpdates, 0, '不应更新库存'); + assert.equal(captures.storageTransactions, 0, '不应写库存流水'); + assert.equal(stockCheck.calls.length, 1, '应调用一次锁定校验'); + assert.deepEqual(stockCheck.calls[0].stockIds, [ 301 ]); + assert.equal(stockCheck.calls[0].actionLabel, '移库'); + }); + + it('transferByProduct:商品静态盘点中 → 400、事务回滚、不写库存', async () => { + const { service, captures } = createTransferLocationHarness(true); + const result = await service.transferByProduct({ space_id: 21, stock_id: 301, target_space_id: 22, quantity: 2 }); + + assert.equal(result.code, 400); + assert.match(result.message, /静态盘点/); + assert.equal(captures.rollbacks, 1); + assert.equal(captures.storageUpdates, 0); + assert.equal(captures.storageTransactions, 0); + }); + + it('未锁定时移库不拦截(保持原有可用量校验路径)', async () => { + const { service, stockCheck } = createTransferLocationHarness(false); + const result = await service.transferByProduct({ space_id: 21, stock_id: 301, target_space_id: 22, quantity: 99 }); + + assert.equal(result.code, 400); + assert.match(result.message, /可用数量不足/, '未锁定时进入原有校验分支'); + assert.equal(stockCheck.calls.length, 1); + }); + + /** + * 创建储位分配测试上下文(可含多个订单,模拟批量分配)。 + * + * @param {Object} options 配置。 + * @param {boolean} options.locked 静态盘点是否锁定。 + * @param {Array} options.orders 订单行。 + * @param {Array} options.orderItems 订单明细行。 + * @param {Array} options.storageRows 库存行(仅未锁定商品)。 + * @return {Object} { service, captures, stockCheck }。 + */ + function createAllocateHarness(options = {}) { + const captures = { + commits: 0, + rollbacks: 0, + orderUpdates: [], + lockCalls: [], + pickingRows: [], + storageQueries: 0, + }; + const stockCheck = createStockCheckStub(options.locked === true); + const storageRows = (options.storageRows || []).map(row => ({ ...row })); + + const ctx = { + user: { store_id: 100000, id: 1, employees_id: 'E1', employees_name: '测试员' }, + logger: { debug() {}, info() {}, warn() {}, error() {} }, + app: { Sequelize, config: {} }, + model: { + async transaction() { + return { + LOCK: { UPDATE: 'UPDATE' }, + async commit() { captures.commits += 1; }, + async rollback() { captures.rollbacks += 1; }, + }; + }, + OrderDeliveryFactory: { + async getCurrentModel() { + return { + async findAll() { + return (options.orders || []).map(row => ({ ...row })); + }, + async update(values, opts = {}) { + captures.orderUpdates.push({ values, where: opts.where }); + return [ 1 ]; + }, + }; + }, + }, + OrderItemsFactory: { + async getCurrentModel() { + return { + async findAll() { + return (options.orderItems || []).map(row => ({ ...row })); + }, + }; + }, + }, + Picking: { + async bulkCreate(rows) { + captures.pickingRows.push(...rows.map(row => ({ ...row }))); + return rows; + }, + async findAll() { + return []; + }, + }, + StockWarehouse: { + async findAll() { + return [ ...new Set((options.orderItems || []).map(row => Number(row.stock_id))) ].map(id => ({ id })); + }, + }, + Storage: { + async findAll() { + captures.storageQueries += 1; + return storageRows.map(row => ({ ...row })); + }, + async update() { + return [ 1 ]; + }, + }, + StorageTransaction: { + async create(payload) { + return { id: 1, ...payload }; + }, + }, + }, + service: { + systems: { + stockCheck, + storage: { + index: { + async lockQuantity(storageId, quantity) { + captures.lockCalls.push({ storageId, quantity }); + const row = storageRows.find(item => Number(item.id) === Number(storageId)); + if (row) { + row.available_quantity = Number(row.available_quantity) - quantity; + row.locked_quantity = Number(row.locked_quantity) + quantity; + } + return [ 1 ]; + }, + async unlockQuantity(storageId, quantity) { + const row = storageRows.find(item => Number(item.id) === Number(storageId)); + if (row) { + row.available_quantity = Number(row.available_quantity) + quantity; + row.locked_quantity = Number(row.locked_quantity) - quantity; + } + return [ 1 ]; + }, + }, + }, + stockStore: { + async getStoreWarehousePolicyConfigByStockId() { + return { policyConfig: { storage_separation: false, allow_storage_location: true } }; + }, + }, + orderPendingException: { + async reversePendingException() { + return null; + }, + }, + }, + }, + }; + + return { service: new OrderStorageAllocationService(ctx), captures, stockCheck }; + } + + it('allocatePicking 批量分配:锁定商品订单标记失败(同库存不足流程),其余订单照常分配', async () => { + const { service, captures, stockCheck } = createAllocateHarness({ + locked: true, + orders: [ + { id: 1, warehouse_id: 100000, status: 'padding', storage_status: 'none', intercept_status: null, lock_status: null }, + { id: 2, warehouse_id: 100000, status: 'padding', storage_status: 'none', intercept_status: null, lock_status: null }, + ], + orderItems: [ + { id: 11, order_id: 1, stock_id: 301, plan_qty: 2, order_line_no: 1 }, + { id: 12, order_id: 2, stock_id: 302, plan_qty: 3, order_line_no: 1 }, + ], + storageRows: [ + // 仅未锁定商品 302 有可用库存(锁定商品 301 即便有库存也不应被分配) + { + id: 501, stock_id: 302, space_id: 601, store_id: 100001, batch_no: 'B302', inventory_type: 'ZP', + quantity: 10, available_quantity: 10, locked_quantity: 0, intercept_locked_quantity: 0, + production_date: null, inbound_time: null, + }, + { + id: 502, stock_id: 301, space_id: 602, store_id: 100001, batch_no: 'B301', inventory_type: 'ZP', + quantity: 10, available_quantity: 10, locked_quantity: 0, intercept_locked_quantity: 0, + production_date: null, inbound_time: null, + }, + ], + }); + + const result = await service.allocatePicking({ order_ids: [ 1, 2 ], allow_storage_location: true }); + + assert.equal(result.code, 200, '批量分配不因单个订单命中锁定而整体失败'); + assert.deepEqual(result.data.shortage_order_ids, [ 1 ], '锁定商品所在订单计入失败列表'); + assert.deepEqual(result.data.allocated_order_ids, [ 2 ], '其余订单正常分配'); + assert.ok(result.data.shortage_messages.some(message => /静态盘点锁定/.test(message)), '失败原因应含静态盘点锁定'); + assert.ok(result.data.shortage_messages.some(message => /PD20261028000001/.test(message)), '失败原因应含来源盘点单号'); + + const lockedOrderResult = result.data.orders.find(item => Number(item.order_id) === 1); + assert.equal(lockedOrderResult.status, 'error', '锁定订单状态应为 error'); + assert.match(lockedOrderResult.shortage_message, /静态盘点锁定/); + + // 订单状态写库:锁定订单 storage_status=error 且 order_flag 带原因 + const lockedUpdate = captures.orderUpdates.find(item => Number(item.where.id) === 1); + assert.equal(lockedUpdate.values.storage_status, 'error'); + assert.match(String(lockedUpdate.values.order_flag), /静态盘点锁定/); + const normalUpdate = captures.orderUpdates.find(item => Number(item.where.id) === 2); + assert.equal(normalUpdate.values.storage_status, 'fin', '未锁定订单应正常完成分配'); + + // 库存锁定只发生在未锁定商品 302 上,锁定商品 301 一行都不加锁 + assert.deepEqual(captures.lockCalls, [{ storageId: 501, quantity: 3 }]); + assert.equal(captures.pickingRows.length, 1, '仅未锁定订单写拣货行'); + assert.equal(Number(captures.pickingRows[0].order_id), 2); + assert.deepEqual(stockCheck.calls[0].stockIds.slice().sort((left, right) => left - right), [ 301, 302 ]); + assert.equal(stockCheck.calls[0].actionLabel, '分配储位'); + }); + + it('allocatePicking 全部订单命中锁定:返回 200 且全部计入失败列表(不中断批量)', async () => { + const { service, captures } = createAllocateHarness({ + locked: true, + orders: [ + { id: 1, warehouse_id: 100000, status: 'padding', storage_status: 'none', intercept_status: null, lock_status: null }, + ], + orderItems: [{ id: 11, order_id: 1, stock_id: 301, plan_qty: 2, order_line_no: 1 }], + storageRows: [], + }); + + const result = await service.allocatePicking({ order_ids: [ 1 ], allow_storage_location: true }); + + assert.equal(result.code, 200, '全部命中锁定时仍按批量口径返回 200(与库存不足一致)'); + assert.deepEqual(result.data.shortage_order_ids, [ 1 ]); + assert.deepEqual(result.data.allocated_order_ids, []); + assert.equal(result.data.picking_count, 0); + assert.equal(captures.lockCalls.length, 0, '不应锁定任何库存'); + assert.equal(captures.commits, 1, '事务正常提交(订单标记失败但流程完成)'); + }); +}); diff --git a/test/app/service/systems/stock_check.test.js b/test/app/service/systems/stock_check.test.js index 42d85f3..0513805 100644 --- a/test/app/service/systems/stock_check.test.js +++ b/test/app/service/systems/stock_check.test.js @@ -53,8 +53,9 @@ * - 汇总差异口径:商品行用快照、库位行用 wms_storage 实时账面; * - workData 盘点作业数据(单接口三视图,is_goods 驱动;不返回 check,任务信息由 detail 返回): * location 视图库位结构(任务库位范围行为列表,行内挂 goods 子列表与 has_unknown/checkers/status)、 - * goods 视图商品结构(明盘返回 system_quantity/checked_quantity/diff_quantity/is_diff 与 - * locations.quantity,盲盘不含任何数量字段)、space 视图聚合库位结构(wms_storage 所在库位 + * goods 视图商品结构(按商品汇总,同商品多库位明细合并为一行:行级账面为快照合计、 + * 作业记录跨明细按库位合并、locations 带该库位明细ID 与账面快照;明盘返回 + * system_quantity/checked_quantity/diff_quantity/is_diff 与 locations.quantity,盲盘不含任何数量字段)、space 视图聚合库位结构(wms_storage 所在库位 * 按拣货路径排序,明盘含库位账面/已盘数量,盲盘不含数量);无记录任务子列表为空、 * 响应为 { view, rows, total, page, pageSize }(view=解析后的视图 location/goods/space;不返回 check,任务信息由 detail 返回)、400 边界(任务ID/任务不存在/跨仓库隔离) * 与状态限制(created/submitted/rejected/completed/cancelled 均 400,仅 approved/checking 可拉取) @@ -211,6 +212,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 type: options.type || 'goods', mode: options.mode || 'open', storeId: options.storeId !== undefined ? options.storeId : null, + isStatic: options.isStatic, remark: options.remark, creatorId: options.creatorId || TEST_CREATOR_ID, creatorName: options.creatorName || TEST_CREATOR_NAME, @@ -778,15 +780,16 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 } /** - * 业务层:拉取单条盘点明细的作业数据(workData 单行版)。 + * 业务层:拉取盘点作业数据明细(库位明细单行 / 商品钻取)。 * - * @param {number} detailId 盘点明细ID。 - * @return {Promise} 单行作业数据。 + * @param {number|Object} input 明细ID(数字)或 { id, stockId, detailId } 参数对象。 + * @return {Promise} 库位单行或商品 { check_id, stock_id, summary, rows }。 */ - async function workDataDetailCheck(detailId) { + async function workDataDetailCheck(input) { + const params = input !== null && typeof input === 'object' ? input : { detailId: input }; return ctx.service.systems.stockCheck.workDataDetail({ warehouseId: TEST_WAREHOUSE_ID, - detailId, + ...params, }); } @@ -1196,6 +1199,88 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 const row = await findCheckRow(result.id); assert.equal(row.mode, 'open', '主表应落库 open'); }); + + it('is_static 静态标记:缺省 0、传 1/true 落库 1、兼容 isStatic 驼峰与 list/detail 返回、库位盘点强制 0', async () => { + // 缺省不传 → 普通盘点 + const normal = await createCheck({ title: uniqueTitle('静态标记-缺省') }); + assert.equal(Number(normal.is_static), 0, '缺省应为普通盘点(0)'); + assert.equal(Number((await findCheckRow(normal.id)).is_static), 0, '主表应落库 0'); + + // 业务层传 isStatic=1 → 静态盘点 + const staticCheck = await ctx.service.systems.stockCheck.create({ + warehouseId: TEST_WAREHOUSE_ID, + title: uniqueTitle('静态标记-开启'), + type: 'goods', + isStatic: 1, + creatorId: TEST_CREATOR_ID, + creatorName: TEST_CREATOR_NAME, + }); + assert.equal(Number(staticCheck.is_static), 1, '传 isStatic=1 应返回 is_static=1'); + assert.equal(Number((await findCheckRow(staticCheck.id)).is_static), 1, '主表应落库 1'); + + // detail 返回该字段 + const detail = await ctx.service.systems.stockCheck.detail({ + warehouseId: TEST_WAREHOUSE_ID, + id: staticCheck.id, + }); + assert.equal(Number(detail.check.is_static), 1, 'detail 应返回 is_static'); + + // list 返回该字段 + const listResult = await listChecks({ pagination: { page: 1, pageSize: 200 } }); + const listed = listResult.rows.find(row => Number(row.id) === Number(staticCheck.id)); + assert.ok(listed, '前置:list 应能查到该任务'); + assert.equal(Number(listed.is_static), 1, 'list 行应返回 is_static'); + + // 方法层兼容 is_static 下划线与 isStatic 驼峰两种写法(需仓库上下文,临时设置 ctx.user) + const previousUser = ctx.user; + ctx.user = { id: TEST_CREATOR_ID, store_id: TEST_WAREHOUSE_ID, employees_name: TEST_CREATOR_NAME }; + try { + const viaMethodSnake = await ctx.service.systemMethods.stock.check.create({ + title: uniqueTitle('静态标记-方法层下划线'), + type: 'goods', + is_static: 1, + }); + assert.equal(viaMethodSnake.flag, 'success'); + assert.equal(Number(viaMethodSnake.data.is_static), 1, '方法层 is_static 应透传'); + + const viaMethodCamel = await ctx.service.systemMethods.stock.check.create({ + title: uniqueTitle('静态标记-方法层驼峰'), + type: 'goods', + isStatic: 'true', + }); + assert.equal(viaMethodCamel.flag, 'success'); + assert.equal(Number(viaMethodCamel.data.is_static), 1, "方法层 isStatic='true' 应透传"); + } finally { + ctx.user = previousUser; + } + + // 其他值(0/'false'/空串)视为普通盘点 + for (const value of [ 0, 'false', '', false ]) { + const created = await ctx.service.systems.stockCheck.create({ + warehouseId: TEST_WAREHOUSE_ID, + title: uniqueTitle(`静态标记-非开启-${String(value)}`), + type: 'goods', + isStatic: value, + creatorId: TEST_CREATOR_ID, + creatorName: TEST_CREATOR_NAME, + }); + assert.equal(Number(created.is_static), 0, `isStatic=${JSON.stringify(value)} 应为普通盘点`); + } + + // 仅对商品盘点有效:按库位盘点(location)即使传 isStatic=1 也一律 0 + for (const value of [ 1, true, 'true' ]) { + const locationCheck = await ctx.service.systems.stockCheck.create({ + warehouseId: TEST_WAREHOUSE_ID, + title: uniqueTitle(`静态标记-库位盘点-${String(value)}`), + type: 'location', + isStatic: value, + creatorId: TEST_CREATOR_ID, + creatorName: TEST_CREATOR_NAME, + }); + assert.equal(Number(locationCheck.is_static), 0, `按库位盘点传 isStatic=${JSON.stringify(value)} 应强制为 0`); + assert.equal(Number((await findCheckRow(locationCheck.id)).is_static), 0, '库位盘点主表应落库 0'); + } + }); }); // ------------------- addDetail:添加盘点明细 ------------------- @@ -4534,11 +4619,11 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 assert.equal(first.view, 'goods'); assert.equal(first.total, 2, '差异行 + 未盘行应均保留'); assert.deepEqual( - first.rows.map(row => Number(row.detail_id)).sort((left, right) => left - right), - [ Number(diffDetail.id), Number(flatDetail.id) ].sort((left, right) => left - right), - '保留行应为差异行与未盘行' + first.rows.map(row => Number(row.stock_id)).sort((left, right) => left - right), + [ Number(diffDetail.stock_id), Number(flatDetail.stock_id) ].sort((left, right) => left - right), + '保留行应为差异行与未盘行(goods 视图按商品汇总,行键为 stock_id)' ); - const flatRow = first.rows.find(row => Number(row.detail_id) === Number(flatDetail.id)); + const flatRow = first.rows.find(row => Number(row.stock_id) === Number(flatDetail.stock_id)); assert.ok( !flatRow.locations.some(location => Array.isArray(location.record_ids) && location.record_ids.length > 0), '未盘行应无任何作业记录' @@ -4548,7 +4633,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 await reportCheck(check.id, flatDetail.id, flatSnapshot, TEST_LOCATION_CODE); const second = await workDataCheck(check.id, { isGoods: true, onlyAbnormal: true }); assert.equal(second.total, 1, '已盘平账行应被过滤,仅剩差异行'); - assert.equal(Number(second.rows[0].detail_id), Number(diffDetail.id)); + assert.equal(Number(second.rows[0].stock_id), Number(diffDetail.stock_id)); assert.equal(second.rows[0].is_diff, 1); // 过滤在分页切片之前:pageSize=1 时 rows 为当前页、total 仍为过滤后行数 @@ -4684,7 +4769,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 }); it('workDataDetail 校验:明细ID非法/不存在/任务未审核均拒绝', async () => { - await assert.rejects(async () => workDataDetailCheck(null), /盘点明细ID不能为空/); + await assert.rejects(async () => workDataDetailCheck(null), /请提供盘点明细ID/); await assert.rejects(async () => workDataDetailCheck(999999999), /盘点明细不存在/); // 任务未审核 → 状态校验拒绝 @@ -4698,7 +4783,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 ); }); - it('workDataDetail goods 分支:商品明细返回单行(结构同 goods 视图行),与 location 分支结构对称', async () => { + it('workDataDetail 商品钻取:传 id + stock_id 返回 summary 汇总与按库位分行(账面快照/实盘/库位ID/明细ID)', async () => { const check = await createCheck({ type: 'goods' }); const stocks = await fetchStockRows(1); await addDetail(check.id, [ stocks[0].id ]); @@ -4709,42 +4794,71 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 const targetDetail = details.rows[0]; const snapshot = Number(targetDetail.system_quantity); - // 上报:盘盈 2 - await reportCheck(check.id, targetDetail.id, snapshot + 2, TEST_LOCATION_CODE); + // 上报库位取一个与该商品明细库位不同的测试库位(验证「已盘库位 vs 明细库位」两类分行) + const reportCode = [ TEST_LOCATION_CODE, TEST_LOCATION_CODE_2, TEST_EMPTY_LOCATION_CODE ] + .find(code => code && String(code) !== String(targetDetail.location_code)); + assert.ok(reportCode, '前置:应存在与商品明细库位不同的测试库位'); - const row = await workDataDetailCheck(targetDetail.id); - assert.equal(row.view, undefined, '应直接返回单行对象,不做 view/rows 包装'); - assert.equal(row.rows, undefined, '不应返回 rows 数组'); - assert.equal(Number(row.detail_id), Number(targetDetail.id)); - assert.equal(Number(row.stock_id), Number(targetDetail.stock_id)); - assert.ok(row.item_code !== undefined, '应含商品编码'); - assert.ok(row.item_name !== undefined, '应含商品名称'); - assert.equal(Number(row.system_quantity), snapshot, '账面应为明细快照'); - assert.equal(Number(row.checked_quantity), snapshot + 2, '已盘应为实盘合计'); - assert.equal(Number(row.diff_quantity), 2, '差异应为实盘-账面'); - assert.equal(Number(row.is_diff), 1); - assert.ok(Array.isArray(row.images), '应含商品图片数组'); - assert.ok(Array.isArray(row.locations), '应含商品所在库位列表'); - const checkedLocation = row.locations.find(loc => String(loc.location_code) === TEST_LOCATION_CODE); - assert.ok(checkedLocation, '已盘库位应出现在 locations'); - assert.equal(Number(checkedLocation.quantity), snapshot + 2, '已盘库位实盘应与上报一致'); - assert.equal(typeof checkedLocation.system_quantity, 'number', '明盘已盘库位应含账面数量'); - assert.equal(typeof checkedLocation.locked_quantity, 'number', '明盘已盘库位应含锁定数量'); - assert.ok(checkedLocation.checked_at, '已盘库位应有上报时间'); - assert.ok( - row.locations.some(loc => !loc.checked_at), - '未盘库位 checked_at 应为 null(商品所在库位列表包含未盘库位)' - ); + // 上报:盘盈 2 + await reportCheck(check.id, targetDetail.id, snapshot + 2, reportCode); + + const detail = await workDataDetailCheck({ id: check.id, stockId: targetDetail.stock_id }); + assert.equal(Number(detail.check_id), Number(check.id), '应返回任务ID'); + assert.equal(Number(detail.stock_id), Number(targetDetail.stock_id), '应返回商品ID'); + assert.equal(detail.view, undefined, '不做 view/rows 视图包装'); + assert.ok(detail.item_code !== undefined, '应含商品编码'); + assert.ok(detail.item_name !== undefined, '应含商品名称'); + assert.ok(Array.isArray(detail.images), '应含商品图片数组'); + assert.ok(detail.summary, '应返回汇总数据 summary'); + assert.equal(Number(detail.summary.system_quantity), snapshot, '汇总账面应为明细快照合计'); + assert.equal(Number(detail.summary.checked_quantity), snapshot + 2, '汇总实盘应为实盘合计'); + assert.equal(Number(detail.summary.diff_quantity), 2, '汇总差异应为实盘-账面'); + assert.equal(Number(detail.summary.is_diff), 1); + + assert.ok(Array.isArray(detail.rows) && detail.rows.length >= 1, '应返回按库位的分行数据 rows'); + const checkedRow = detail.rows.find(row => String(row.location_code) === String(reportCode)); + assert.ok(checkedRow, '已盘库位应出现在 rows'); + // 上报库位不是该商品的明细库位(商品实际库位在别处)→ 该分行无明细ID、快照为 0 + assert.equal(checkedRow.detail_id, null, '非明细库位分行不应带明细ID'); + assert.equal(Number(checkedRow.checked_quantity), snapshot + 2, '分行实盘应与上报一致'); + assert.equal(Number(checkedRow.snapshot_quantity), 0, '无明细快照的库位账面快照为 0'); + assert.equal(Number(checkedRow.diff_quantity), snapshot + 2, '分行差异=实盘-快照'); + assert.equal(typeof checkedRow.system_quantity, 'number', '明盘分行应含当前账面数量'); + assert.equal(typeof checkedRow.locked_quantity, 'number', '明盘分行应含锁定数量'); + assert.ok(checkedRow.checked_at, '已盘库位应有上报时间'); + // 库位ID:location_id 与同义 space_id 均为 wms_location_space.id,可直接回传 report + assert.equal(Number(checkedRow.location_id), Number(checkedRow.space_id)); + const spaceRow = await ctx.model.LocationSpace.findOne({ + where: { warehouse_id: TEST_WAREHOUSE_ID, space_code: reportCode }, + attributes: [ 'id' ], + order: [[ 'id', 'ASC' ]], + raw: true, + }); + assert.equal(Number(checkedRow.location_id), Number(spaceRow.id), '分行库位ID应与库位编码对应'); + + // 明细库位分行:带明细ID与账面快照,未盘(实盘 0,差异=-快照) + const ownRow = detail.rows.find(row => String(row.location_code) === String(targetDetail.location_code)); + assert.ok(ownRow, '商品明细库位应出现在 rows'); + assert.equal(Number(ownRow.detail_id), Number(targetDetail.id), '明细库位分行应带该库位明细ID'); + assert.equal(Number(ownRow.snapshot_quantity), snapshot, '明细库位分行应带该库位账面快照'); + assert.equal(Number(ownRow.checked_quantity), 0, '未盘库位实盘为 0'); + assert.equal(ownRow.checked_at, null, '未盘库位 checked_at 应为 null'); // 与 workData goods 视图行交叉验证 const goodsAll = await workDataCheck(check.id, { isGoods: true }); - const goodsRow = goodsAll.rows.find(item => Number(item.detail_id) === Number(targetDetail.id)); - assert.ok(goodsRow, 'goods 视图应含该明细行'); - assert.equal(Number(row.checked_quantity), Number(goodsRow.checked_quantity), '已盘合计应与 goods 视图一致'); - assert.equal(Number(row.diff_quantity), Number(goodsRow.diff_quantity), '差异应与 goods 视图一致'); + const goodsRow = goodsAll.rows.find(item => Number(item.stock_id) === Number(targetDetail.stock_id)); + assert.ok(goodsRow, 'goods 视图应含该商品行'); + assert.equal(Number(detail.summary.checked_quantity), Number(goodsRow.checked_quantity), '汇总实盘应与 goods 视图一致'); + assert.equal(Number(detail.summary.diff_quantity), Number(goodsRow.diff_quantity), '汇总差异应与 goods 视图一致'); + assert.equal(detail.rows.length, goodsRow.locations.length, '分行数应与 goods 视图 locations 一致'); + + // 兼容:传商品范围明细ID 也返回同一钻取结构 + const byDetailId = await workDataDetailCheck({ detailId: targetDetail.id }); + assert.equal(Number(byDetailId.stock_id), Number(targetDetail.stock_id)); + assert.equal(Number(byDetailId.summary.checked_quantity), snapshot + 2); }); - it('workDataDetail goods 分支盲盘:不返回数量字段,行信息仍输出', async () => { + it('workDataDetail 商品钻取盲盘:不返回数量字段,行信息仍输出', async () => { const check = await createCheck({ type: 'goods', mode: 'blind' }); const stocks = await fetchStockRows(1); await addDetail(check.id, [ stocks[0].id ]); @@ -4755,40 +4869,24 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 const targetDetail = details.rows[0]; await reportCheck(check.id, targetDetail.id, 6, TEST_LOCATION_CODE); - const row = await workDataDetailCheck(targetDetail.id); - assert.equal(row.view, undefined, '应直接返回单行对象'); + const detail = await workDataDetailCheck({ id: check.id, stockId: targetDetail.stock_id }); + assert.equal(Number(detail.stock_id), Number(targetDetail.stock_id)); assert.equal( - Object.prototype.hasOwnProperty.call(row, 'system_quantity'), + Object.prototype.hasOwnProperty.call(detail, 'summary'), false, - '盲盘不应含账面快照' + '盲盘不应返回汇总数量' ); - assert.equal( - Object.prototype.hasOwnProperty.call(row, 'checked_quantity'), - false, - '盲盘不应含已盘数量' - ); - assert.equal( - Object.prototype.hasOwnProperty.call(row, 'diff_quantity'), - false, - '盲盘不应含差异数量' - ); - assert.ok(row.locations.length >= 1, 'locations 应包含商品所在库位'); - for (const location of row.locations) { - assert.equal( - Object.prototype.hasOwnProperty.call(location, 'quantity'), - false, - '盲盘库位不应含数量' - ); - assert.equal( - Object.prototype.hasOwnProperty.call(location, 'system_quantity'), - false, - '盲盘库位不应含账面数量' - ); - assert.equal( - Object.prototype.hasOwnProperty.call(location, 'locked_quantity'), - false, - '盲盘库位不应含锁定数量' - ); + assert.ok(detail.rows.length >= 1, 'rows 应包含商品所在库位'); + for (const row of detail.rows) { + for (const key of [ 'system_quantity', 'locked_quantity', 'snapshot_quantity', 'checked_quantity', 'diff_quantity' ]) { + assert.equal( + Object.prototype.hasOwnProperty.call(row, key), + false, + `盲盘分行不应含数量字段 ${key}` + ); + } + assert.ok(row.location_code, '盲盘分行仍应输出库位编码'); + assert.ok(Array.isArray(row.record_ids), '盲盘分行仍应输出作业记录ID'); } }); @@ -5111,7 +5209,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 assert.equal(data.total, 2); - const firstRow = data.rows.find(row => Number(row.detail_id) === Number(firstDetail.id)); + const firstRow = data.rows.find(row => Number(row.stock_id) === Number(firstDetail.stock_id)); assert.equal(Number(firstRow.system_quantity), snapshot, '账面应来自明细快照'); assert.equal(firstRow.checked_quantity, snapshot + 6, '已盘合计应为多库位实盘之和'); assert.equal(firstRow.diff_quantity, 6, '差异=已盘合计-账面快照'); @@ -5137,7 +5235,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 assert.equal(firstRow.is_diff, resultFirst.is_diff); // 未盘行:明盘按 0 处理、locations 为商品所在库位列表(无作业信息) - const secondRow = data.rows.find(row => Number(row.detail_id) === Number(secondDetail.id)); + const secondRow = data.rows.find(row => Number(row.stock_id) === Number(secondDetail.stock_id)); assert.equal(Number(secondRow.system_quantity), Number(secondDetail.system_quantity)); assert.equal(secondRow.checked_quantity, 0); assert.equal(secondRow.diff_quantity, 0); @@ -5168,7 +5266,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 assert.equal(data.total, 2); for (const row of data.rows) { - const detail = details.rows.find(item => Number(item.id) === Number(row.detail_id)); + const detail = details.rows.find(item => Number(item.stock_id) === Number(row.stock_id)); const stockDetail = stockDetails.find(item => Number(item.id) === Number(row.stock_id)); assert.ok(stockDetail, '前置:商品详情应可查询'); assert.equal(row.item_code, stockDetail.item_code || detail.item_code || null); @@ -5233,6 +5331,299 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 } }); + it('goods 视图多库位商品按商品汇总为一行:账面快照合计、跨明细按库位合并、workDataDetail 返回汇总+分行', async () => { + const { Op, literal } = ctx.app.Sequelize; + // 前置:找一个在两个及以上启用库位都有库存的商品(addDetail 按「商品 + 库位」拆多行明细) + const storageRows = await ctx.model.Storage.findAll({ + where: { + warehouse_id: TEST_WAREHOUSE_ID, + is_enabled: 1, + space_id: { [Op.in]: literal(VALID_SPACE_SQL) }, + }, + attributes: [ 'stock_id', 'space_id', [ literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ]], + group: [ 'stock_id', 'space_id' ], + raw: true, + }); + const spacesByStock = new Map(); + for (const row of storageRows) { + const stockId = Number(row.stock_id); + if (!spacesByStock.has(stockId)) { + spacesByStock.set(stockId, []); + } + spacesByStock.get(stockId).push(row); + } + const multiStockEntry = [ ...spacesByStock.entries() ].find(([ , rows ]) => rows.length >= 2); + assert.ok(multiStockEntry, '前置:测试库应存在多库位库存商品'); + const multiStockId = Number(multiStockEntry[0]); + const multiStock = await ctx.model.StockWarehouse.findOne({ + where: { id: multiStockId, warehouse_id: TEST_WAREHOUSE_ID }, + raw: true, + }); + assert.ok(multiStock, '前置:多库位商品应存在于 wms_stock_warehouse'); + + const check = await createCheck({ type: 'goods', storeId: multiStock.store_id || null }); + await addDetail(check.id, [ multiStockId ]); + await submitCheck(check.id); + await auditCheck(check.id, 'approve'); + + const details = await detailCheck(check.id); + assert.equal(details.rows.length, multiStockEntry[1].length, '前置:多库位商品按库位拆多行明细'); + const detailIds = details.rows.map(row => Number(row.id)); + const snapshotTotal = details.rows.reduce((sum, row) => sum + (Number(row.system_quantity) || 0), 0); + + // 两个库位分别上报(记录落在各自明细行),汇总行应合并 + const firstDetail = details.rows[0]; + const secondDetail = details.rows[1]; + const firstCode = String(firstDetail.location_code || '').trim(); + const secondCode = String(secondDetail.location_code || '').trim(); + const firstReport = await reportCheck(check.id, firstDetail.id, 7, firstCode); + const secondReport = await reportCheck(check.id, secondDetail.id, 3, secondCode); + + const data = await workDataCheck(check.id, { isGoods: true }); + assert.equal(data.total, 1, '同商品多库位明细应汇总为一行'); + const row = data.rows[0]; + assert.equal(Number(row.stock_id), multiStockId); + assert.equal( + Object.prototype.hasOwnProperty.call(row, 'detail_id'), + false, + 'goods 汇总视图行不再输出明细ID(逐库位明细走 workDataDetail)' + ); + assert.equal(Number(row.system_quantity), snapshotTotal, '行级账面应为各库位明细快照之和'); + assert.equal(row.checked_quantity, 10, '行级已盘合计应跨明细合并'); + assert.equal(row.diff_quantity, 10 - snapshotTotal); + assert.equal(row.is_diff, row.diff_quantity !== 0 ? 1 : 0); + + const quantityByCode = new Map(row.locations.map(item => [ item.location_code, Number(item.quantity) ])); + assert.equal(quantityByCode.get(firstCode), 7, '首个库位实盘应来自其明细下记录'); + assert.equal(quantityByCode.get(secondCode), 3, '第二个库位实盘应来自另一条明细下记录'); + const firstLocation = row.locations.find(item => item.location_code === firstCode); + const secondLocation = row.locations.find(item => item.location_code === secondCode); + assert.deepEqual(firstLocation.record_ids, [ Number(firstReport.record.id) ]); + assert.deepEqual(secondLocation.record_ids, [ Number(secondReport.record.id) ]); + // locations 每项带该库位明细ID 与账面快照(供逐库位上报/钻取) + assert.equal(Number(firstLocation.detail_id), Number(firstDetail.id)); + assert.equal(Number(secondLocation.detail_id), Number(secondDetail.id)); + assert.equal(Number(firstLocation.snapshot_quantity), Number(firstDetail.system_quantity)); + assert.equal(Number(secondLocation.snapshot_quantity), Number(secondDetail.system_quantity)); + + // workDataDetail:id + stock_id 返回该商品的汇总 + 按库位分行 + const detail = await workDataDetailCheck({ id: check.id, stockId: multiStockId }); + assert.equal(detail.rows.length, detailIds.length, '分行数应等于该商品的库位明细行数'); + assert.equal(Number(detail.summary.system_quantity), snapshotTotal, '汇总账面=各行快照之和'); + assert.equal(Number(detail.summary.checked_quantity), 10, '汇总实盘=各行实盘之和'); + assert.equal(Number(detail.summary.diff_quantity), 10 - snapshotTotal); + const firstDetailRow = detail.rows.find(item => item.location_code === firstCode); + const secondDetailRow = detail.rows.find(item => item.location_code === secondCode); + assert.equal(Number(firstDetailRow.detail_id), Number(firstDetail.id), '分行应带该库位明细ID'); + assert.equal(Number(secondDetailRow.detail_id), Number(secondDetail.id)); + assert.equal(Number(firstDetailRow.checked_quantity), 7); + assert.equal(Number(secondDetailRow.checked_quantity), 3); + assert.equal(Number(firstDetailRow.diff_quantity), 7 - Number(firstDetail.system_quantity)); + assert.equal(Number(secondDetailRow.diff_quantity), 3 - Number(secondDetail.system_quantity)); + // 分行实盘之和 = 汇总实盘(与 goods 视图行级 checked_quantity 一致) + assert.equal( + detail.rows.reduce((sum, item) => sum + (Number(item.checked_quantity) || 0), 0), + Number(row.checked_quantity) + ); + }); + + it('report 兼容:不传 detail_id 时按 id + stock_id + space_id 反查该商品明细上报', async () => { + const check = await createCheck({ type: 'goods' }); + const stocks = await fetchStockRows(1); + await addDetail(check.id, [ stocks[0].id ]); + await submitCheck(check.id); + await auditCheck(check.id, 'approve'); + + const details = await detailCheck(check.id); + const targetDetail = details.rows[0]; + const spaceId = Number(targetDetail.location_id); + const reported = await ctx.service.systems.stockCheck.report({ + warehouseId: TEST_WAREHOUSE_ID, + id: check.id, + stockId: targetDetail.stock_id, + spaceId, + quantity: 12, + checkerId: TEST_CREATOR_ID, + checkerName: TEST_CREATOR_NAME, + }); + assert.equal(Number(reported.detail_id), Number(targetDetail.id), '应反查命中该商品的库位明细'); + assert.equal(Number(reported.record.stock_id), Number(targetDetail.stock_id)); + assert.equal(Number(reported.record.quantity), 12); + + // 既无 detail_id 也无 stock_id → 400 + await assert.rejects( + async () => ctx.service.systems.stockCheck.report({ + warehouseId: TEST_WAREHOUSE_ID, + id: check.id, + spaceId, + quantity: 1, + checkerId: TEST_CREATOR_ID, + checkerName: TEST_CREATOR_NAME, + }), + /盘点明细ID不能为空/ + ); + + // 商品不在本任务盘点范围 → 400 + await assert.rejects( + async () => ctx.service.systems.stockCheck.report({ + warehouseId: TEST_WAREHOUSE_ID, + id: check.id, + stockId: 999999999, + spaceId, + quantity: 1, + checkerId: TEST_CREATOR_ID, + checkerName: TEST_CREATOR_NAME, + }), + /盘点明细不存在/ + ); + }); + + it('账面取值按任务静态标记:静态任务取明细快照、非静态任务取当前 storage(goods/space/workDataDetail 一致)', async () => { + const stocks = await fetchStockRows(1); + const targetStock = stocks[0]; + const DELTA = 7; + + /** + * 构造一个已审核通过的商品任务,并在审核后人为改动该库位账面(模拟盘点期间库存变动)。 + * + * @param {boolean} isStatic 是否静态盘点。 + * @return {Promise} { check, detailRow, snapshot, liveBook, spaceId }。 + */ + async function prepareCheck(isStatic) { + const check = await createCheck({ + title: uniqueTitle(`账面口径-${isStatic ? '静态' : '非静态'}`), + type: 'goods', + isStatic, + }); + await addDetail(check.id, [ targetStock.id ]); + await submitCheck(check.id); + await auditCheck(check.id, 'approve'); + + const details = await detailCheck(check.id); + const detailRow = details.rows[0]; + const spaceId = Number(detailRow.location_id); + const snapshot = Number(detailRow.system_quantity); + + await ctx.model.query( + `UPDATE wms_storage + SET available_quantity = available_quantity + :delta + WHERE warehouse_id = :warehouseId AND stock_id = :stockId AND space_id = :spaceId`, + { replacements: { delta: DELTA, warehouseId: TEST_WAREHOUSE_ID, stockId: targetStock.id, spaceId } } + ); + const liveRows = await ctx.model.query( + `SELECT COALESCE(SUM(available_quantity + locked_quantity), 0) AS total + FROM wms_storage + WHERE warehouse_id = :warehouseId AND stock_id = :stockId AND space_id = :spaceId`, + { + replacements: { warehouseId: TEST_WAREHOUSE_ID, stockId: targetStock.id, spaceId }, + type: ctx.model.QueryTypes.SELECT, + } + ); + return { check, detailRow, spaceId, snapshot, liveBook: Number(liveRows[0] && liveRows[0].total) || 0 }; + } + + /** + * 回滚人为库存变动。 + * + * @param {number} spaceId 库位ID。 + * @return {Promise} 无返回值。 + */ + async function restoreBook(spaceId) { + await ctx.model.query( + `UPDATE wms_storage + SET available_quantity = available_quantity - :delta + WHERE warehouse_id = :warehouseId AND stock_id = :stockId AND space_id = :spaceId`, + { replacements: { delta: DELTA, warehouseId: TEST_WAREHOUSE_ID, stockId: targetStock.id, spaceId } } + ); + } + + const spaceIdList = []; + try { + // ── 静态任务:账面=快照(冻结),当前 storage 仅作为参考字段输出 ── + const staticPrepared = await prepareCheck(true); + spaceIdList.push(staticPrepared.spaceId); + assert.ok(staticPrepared.liveBook > staticPrepared.snapshot, '前置:人为变动后当前账面应大于快照'); + + const staticGoods = await workDataCheck(staticPrepared.check.id, { isGoods: true }); + const staticRow = staticGoods.rows[0]; + const staticLocation = staticRow.locations.find(item => item.detail_id !== null); + assert.equal(Number(staticRow.is_static), 1); + assert.equal(staticRow.book_source, 'snapshot', '静态任务账面来源应为快照'); + assert.equal( + Number(staticRow.system_quantity), + staticPrepared.snapshot, + '静态任务行级账面应取明细快照(不受盘点期间库存变动影响)' + ); + assert.equal(Number(staticLocation.system_quantity), staticPrepared.snapshot, '静态任务库位账面应取快照'); + assert.equal(Number(staticLocation.snapshot_quantity), staticPrepared.snapshot); + assert.equal(Number(staticLocation.storage_quantity), staticPrepared.liveBook, '当前 storage 账面作为参考字段输出'); + + // 上报后差异按快照计算 + await reportCheck(staticPrepared.check.id, staticPrepared.detailRow.id, staticPrepared.snapshot - 2, staticPrepared.detailRow.location_code); + const staticAfterReport = await workDataCheck(staticPrepared.check.id, { isGoods: true }); + assert.equal( + Number(staticAfterReport.rows[0].diff_quantity), + -2, + '静态任务差异=实盘-快照(而非实盘-当前账面)' + ); + + // space 视图同口径 + const staticSpace = await workDataCheck(staticPrepared.check.id); + const staticSpaceItem = staticSpace.rows + .flatMap(row => row.goods || []) + .find(item => Number(item.stock_id) === Number(targetStock.id)); + assert.ok(staticSpaceItem, 'space 视图应含该商品'); + assert.equal(Number(staticSpaceItem.system_quantity), staticPrepared.snapshot, 'space 视图静态任务账面应取快照'); + assert.equal(Number(staticSpaceItem.storage_quantity), staticPrepared.liveBook); + + // workDataDetail 同口径 + const staticDrill = await workDataDetailCheck({ id: staticPrepared.check.id, stockId: targetStock.id }); + assert.equal(Number(staticDrill.is_static), 1); + assert.equal(staticDrill.book_source, 'snapshot'); + assert.equal(Number(staticDrill.summary.system_quantity), staticPrepared.snapshot, '钻取汇总账面应取快照'); + const staticDrillRow = staticDrill.rows.find(item => item.detail_id !== null); + assert.equal(Number(staticDrillRow.system_quantity), staticPrepared.snapshot); + assert.equal(Number(staticDrillRow.snapshot_quantity), staticPrepared.snapshot); + assert.equal(Number(staticDrillRow.storage_quantity), staticPrepared.liveBook); + + // ── 非静态任务:账面=当前 storage,快照仅作参考字段 ── + const normalPrepared = await prepareCheck(false); + spaceIdList.push(normalPrepared.spaceId); + + const normalGoods = await workDataCheck(normalPrepared.check.id, { isGoods: true }); + const normalRow = normalGoods.rows[0]; + const normalLocation = normalRow.locations.find(item => item.detail_id !== null); + assert.equal(Number(normalRow.is_static), 0); + assert.equal(normalRow.book_source, 'storage', '非静态任务账面来源应为当前 storage'); + assert.equal(Number(normalRow.system_quantity), normalPrepared.liveBook, '非静态任务行级账面应取当前 storage'); + assert.equal(Number(normalLocation.system_quantity), normalPrepared.liveBook); + assert.equal(Number(normalLocation.snapshot_quantity), normalPrepared.snapshot, '快照仍作为参考字段输出'); + + await reportCheck(normalPrepared.check.id, normalPrepared.detailRow.id, normalPrepared.liveBook - 3, normalPrepared.detailRow.location_code); + const normalAfterReport = await workDataCheck(normalPrepared.check.id, { isGoods: true }); + assert.equal( + Number(normalAfterReport.rows[0].diff_quantity), + -3, + '非静态任务差异=实盘-当前账面' + ); + + const normalSpace = await workDataCheck(normalPrepared.check.id); + const normalSpaceItem = normalSpace.rows + .flatMap(row => row.goods || []) + .find(item => Number(item.stock_id) === Number(targetStock.id)); + assert.equal(Number(normalSpaceItem.system_quantity), normalPrepared.liveBook, 'space 视图非静态任务账面应取当前 storage'); + + const normalDrill = await workDataDetailCheck({ id: normalPrepared.check.id, stockId: targetStock.id }); + assert.equal(Number(normalDrill.is_static), 0); + assert.equal(normalDrill.book_source, 'storage'); + assert.equal(Number(normalDrill.summary.system_quantity), normalPrepared.liveBook); + } finally { + for (const spaceId of spaceIdList) { + await restoreBook(spaceId); + } + } + }); + it('goods 视图盲盘:不含任何数量字段(system_quantity/checked_quantity/diff_quantity/is_diff 与 locations.quantity)', async () => { const check = await createCheck({ mode: 'blind' }); const stocks = await fetchStockRows(1); @@ -5771,6 +6162,48 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 '明盘商品视图应含账面快照' ); }); + + it('workDataDetail 方法层:id + stock_id 返回 summary + rows,兼容 stockId 驼峰与 detail_id', async () => { + mockCurrentUser(); + + const check = await createCheck(); + const stocks = await fetchStockRows(1); + await addDetail(check.id, [ stocks[0].id ]); + await submitCheck(check.id); + await auditCheck(check.id, 'approve'); + + const details = await detailCheck(check.id); + const targetDetail = details.rows[0]; + const snapshot = Number(targetDetail.system_quantity); + await reportCheck(check.id, targetDetail.id, snapshot + 1, TEST_LOCATION_CODE); + + const bySnake = await ctx.service.systemMethods.stock.check.workDataDetail({ + id: check.id, + stock_id: stocks[0].id, + }); + assert.equal(bySnake.flag, 'success'); + assert.equal(bySnake.code, 1); + assert.equal(Number(bySnake.data.stock_id), Number(stocks[0].id)); + assert.equal(Number(bySnake.data.summary.checked_quantity), snapshot + 1, '方法层应返回汇总数据'); + assert.ok(Array.isArray(bySnake.data.rows) && bySnake.data.rows.length >= 1, '方法层应返回分行数据'); + + const byCamel = await ctx.service.systemMethods.stock.check.workDataDetail({ + id: check.id, + stockId: stocks[0].id, + }); + assert.equal(byCamel.flag, 'success'); + assert.equal(Number(byCamel.data.summary.checked_quantity), snapshot + 1); + + // 兼容旧写法:只传 detail_id(商品范围明细) + const byDetailId = await ctx.service.systemMethods.stock.check.workDataDetail({ detail_id: targetDetail.id }); + assert.equal(byDetailId.flag, 'success'); + assert.equal(Number(byDetailId.data.stock_id), Number(stocks[0].id)); + + // 缺少必要参数 → failure 400 包装 + const missing = await ctx.service.systemMethods.stock.check.workDataDetail({ id: check.id }); + assert.equal(missing.flag, 'failure'); + assert.equal(missing.code, 400); + }); }); // ------------------- exportStockChecks:盘点导出(盘点明细=作业记录口径) ------------------- @@ -7126,6 +7559,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 assert.equal(check.detail_status, 'none_checked'); assert.equal(check.type, 'goods', 'warning 定式应为按商品盘点'); assert.equal(check.mode, 'open', '商品类定式应固定明盘(open)'); + assert.equal(Number(check.is_static), 0, '非静态定式创建的任务应为普通盘点(is_static=0)'); assert.equal( Object.prototype.hasOwnProperty.call(check, 'check_date'), false, @@ -7318,6 +7752,9 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 assert.equal(result.pattern_id, 'static'); assert.equal(result.check.type, 'goods'); assert.equal(result.check.mode, 'open', '商品类定式应固定明盘(open)'); + assert.equal(Number(result.check.is_static), 1, '静态定式创建的任务应标记为静态盘点'); + const staticTaskRow = await findCheckRow(result.check.id); + assert.equal(Number(staticTaskRow.is_static), 1, '主表应落库 is_static=1'); const details = await queryCheckDetails(result.check.id); assert.ok(details.some(item => Number(item.stock_id) === stockA.id), '超时商品应写入明细'); @@ -8304,7 +8741,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 mockCurrentUser(); const { check } = await createCancelledCheck(); - const result = await ctx.service.systemMethods.stock.check.batchDelete({ ids: check.id }); + const result = await ctx.service.systemMethods.stock.check.batchDelete({ ids: [ check.id ] }); assert.equal(result.flag, 'success'); assert.equal(result.code, 1); @@ -8312,4 +8749,526 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 assert.deepEqual(result.data.deleted_ids, [ check.id ]); }); }); + + // ------------------- staticLockList:静态盘点锁定商品(公共查询 + 缓存) ------------------- + + describe('staticLockList 静态盘点锁定商品(公共查询 + 缓存 + 审核刷新快照)', () => { + /** 设置当前上下文用户(方法层需仓库上下文)。 */ + function mockCurrentUser() { + ctx.user = { + id: TEST_CREATOR_ID, + store_id: TEST_WAREHOUSE_ID, + employees_name: TEST_CREATOR_NAME, + }; + } + + /** + * 读取锁定缓存原始值(用于断言缓存命中/失效)。 + * + * @return {Promise} 缓存载荷。 + */ + async function readLockCache() { + return ctx.app.getCacheAsync(`stock_check:static_lock:${TEST_WAREHOUSE_ID}`); + } + + /** + * 清理锁定缓存,保证用例互不影响。 + * + * @return {Promise} 无返回值。 + */ + async function clearLockCache() { + await ctx.app.delCacheAsync(`stock_check:static_lock:${TEST_WAREHOUSE_ID}`); + } + + /** + * 业务层:查询静态锁定列表。 + * + * @return {Promise} { warehouse_id, stock_ids, rows, total, cached, updated_at }。 + */ + async function staticLockList() { + return ctx.service.systems.stockCheck.staticLockList({ warehouseId: TEST_WAREHOUSE_ID }); + } + + it('仅统计 is_static=1 且 approved/checking 任务的商品;submitted 与普通任务不计入', async () => { + await clearLockCache(); + const stocks = await fetchStockRows(2); + + // 静态任务 A:审核通过(锁定中) + const staticCheck = await ctx.service.systems.stockCheck.create({ + warehouseId: TEST_WAREHOUSE_ID, + title: uniqueTitle('静态锁定-审核通过'), + type: 'goods', + isStatic: 1, + creatorId: TEST_CREATOR_ID, + creatorName: TEST_CREATOR_NAME, + }); + await addDetail(staticCheck.id, [ stocks[0].id ]); + await submitCheck(staticCheck.id); + await auditCheck(staticCheck.id, 'approve'); + + // 静态任务 B:待审核(未锁定) + const pendingCheck = await ctx.service.systems.stockCheck.create({ + warehouseId: TEST_WAREHOUSE_ID, + title: uniqueTitle('静态锁定-待审核'), + type: 'goods', + isStatic: 1, + creatorId: TEST_CREATOR_ID, + creatorName: TEST_CREATOR_NAME, + }); + await addDetail(pendingCheck.id, [ stocks[1].id ]); + await submitCheck(pendingCheck.id); + + const lockList = await staticLockList(); + const lockedIds = lockList.stock_ids.map(Number); + assert.ok(lockedIds.includes(Number(stocks[0].id)), '审核通过的静态任务商品应锁定'); + assert.equal( + lockedIds.includes(Number(stocks[1].id)), + false, + '待审核的静态任务商品不应锁定' + ); + for (const stockId of lockedIds) { + assert.ok(Number.isInteger(stockId) && stockId > 0, '锁定集合应为正整数商品ID'); + } + const targetRow = lockList.rows.find(row => Number(row.stock_id) === Number(stocks[0].id)); + assert.ok(targetRow, 'rows 应含锁定商品'); + assert.ok(targetRow.check_ids.includes(Number(staticCheck.id)), 'rows 应含来源任务ID'); + assert.ok(targetRow.check_nos.length >= 1, 'rows 应含来源单号'); + assert.ok(Array.isArray(targetRow.location_codes) && targetRow.location_codes.length >= 1, 'rows 应含盘点库位编码'); + + // 普通(非静态)任务即使审核通过也不锁定 + const normalCheck = await createCheck({ title: uniqueTitle('静态锁定-普通任务') }); + const normalStock = (await fetchStockRows(3)).find(stock => Number(stock.id) !== Number(stocks[0].id) + && Number(stock.id) !== Number(stocks[1].id)); + if (normalStock) { + await addDetail(normalCheck.id, [ normalStock.id ]); + await submitCheck(normalCheck.id); + await auditCheck(normalCheck.id, 'approve'); + const afterNormal = await staticLockList(); + assert.equal( + afterNormal.stock_ids.map(Number).includes(Number(normalStock.id)), + false, + '非静态任务不应进入锁定集合' + ); + } + }); + + it('缓存命中与失效:二次查询命中缓存,审核/完成/取消后缓存清除', async () => { + await clearLockCache(); + const stocks = await fetchStockRows(1); + const check = await ctx.service.systems.stockCheck.create({ + warehouseId: TEST_WAREHOUSE_ID, + title: uniqueTitle('静态锁定-缓存'), + type: 'goods', + isStatic: 1, + creatorId: TEST_CREATOR_ID, + creatorName: TEST_CREATOR_NAME, + }); + await addDetail(check.id, [ stocks[0].id ]); + await submitCheck(check.id); + + // 提交审核不锁定:首次查询未命中缓存,且不包含本任务 + const beforeApprove = await staticLockList(); + assert.equal(beforeApprove.cached, false, '首次查询应回源'); + assert.equal( + beforeApprove.rows.some(row => row.check_ids.map(Number).includes(Number(check.id))), + false, + '待审核阶段不锁定(rows 不应含该任务)' + ); + + // 审核通过后缓存被立即重建(不是删除等下次回源)→ 含本任务;查询命中缓存 + await auditCheck(check.id, 'approve'); + const cacheAfterAudit = await readLockCache(); + assert.ok(cacheAfterAudit, '审核通过应重建锁定缓存(不留空窗)'); + assert.ok( + cacheAfterAudit.rows.some(row => row.check_ids.map(Number).includes(Number(check.id))), + '重建后的缓存应包含刚审核通过的任务' + ); + const afterApprove = await staticLockList(); + assert.equal(afterApprove.cached, true, '审核后查询应直接命中已重建的缓存'); + const lockedRow = afterApprove.rows.find(row => Number(row.stock_id) === Number(stocks[0].id)); + assert.ok(lockedRow, '审核通过后该商品应出现在锁定集合'); + assert.ok(lockedRow.check_ids.map(Number).includes(Number(check.id)), '锁定行应含该任务ID'); + assert.ok(afterApprove.updated_at, '缓存载荷应含 updated_at'); + + // 完成盘点 → 缓存重建且本任务已被移除 + await finishCheck(check.id); + const cacheAfterFinish = await readLockCache(); + assert.ok(cacheAfterFinish, '完成盘点应重建锁定缓存'); + assert.equal( + cacheAfterFinish.rows.some(row => row.check_ids.map(Number).includes(Number(check.id))), + false, + '重建后的缓存不应再包含已完成任务' + ); + const afterFinish = await staticLockList(); + assert.equal(afterFinish.cached, true, '完成后查询命中已重建的缓存'); + assert.equal( + afterFinish.rows.some(row => row.check_ids.map(Number).includes(Number(check.id))), + false, + '已完成任务不应出现在锁定集合' + ); + + // 取消任务 → 同样失效 + const cancelledCheck = await ctx.service.systems.stockCheck.create({ + warehouseId: TEST_WAREHOUSE_ID, + title: uniqueTitle('静态锁定-取消'), + type: 'goods', + isStatic: 1, + creatorId: TEST_CREATOR_ID, + creatorName: TEST_CREATOR_NAME, + }); + await staticLockList(); + await cancelCheck(cancelledCheck.id); + const cacheAfterCancel = await readLockCache(); + assert.ok(cacheAfterCancel, '取消任务应重建锁定缓存'); + assert.equal( + cacheAfterCancel.rows.some(row => row.check_ids.map(Number).includes(Number(cancelledCheck.id))), + false, + '重建后的缓存不应包含已取消任务' + ); + }); + + it('isStockStaticLocked:按商品判断是否锁定(读缓存),未锁定返回 false', async () => { + await clearLockCache(); + const stocks = await fetchStockRows(2); + const check = await ctx.service.systems.stockCheck.create({ + warehouseId: TEST_WAREHOUSE_ID, + title: uniqueTitle('静态锁定-单商品判断'), + type: 'goods', + isStatic: 1, + creatorId: TEST_CREATOR_ID, + creatorName: TEST_CREATOR_NAME, + }); + await addDetail(check.id, [ stocks[0].id ]); + await submitCheck(check.id); + await auditCheck(check.id, 'approve'); + + const lockedHit = await ctx.service.systems.stockCheck.isStockStaticLocked({ + warehouseId: TEST_WAREHOUSE_ID, + stockId: stocks[0].id, + }); + assert.equal(lockedHit.locked, true, '锁定中的商品应返回 locked=true'); + assert.deepEqual(lockedHit.locked_stock_ids, [ Number(stocks[0].id) ]); + assert.equal(Number(lockedHit.rows[0].stock_id), Number(stocks[0].id)); + + const lockedMiss = await ctx.service.systems.stockCheck.isStockStaticLocked({ + warehouseId: TEST_WAREHOUSE_ID, + stockId: [ stocks[1].id, 999999999 ], + }); + assert.equal(lockedMiss.locked, false, '未锁定商品应返回 locked=false'); + assert.deepEqual(lockedMiss.locked_stock_ids, []); + + await assert.rejects( + async () => ctx.service.systems.stockCheck.isStockStaticLocked({ warehouseId: TEST_WAREHOUSE_ID }), + /商品ID不能为空/ + ); + await assert.rejects( + async () => ctx.service.systems.stockCheck.staticLockList({ warehouseId: 0 }), + /无法获取当前仓库上下文/ + ); + }); + + it('审核通过刷新商品明细账面快照:提交后库存变化,审核时快照刷新为审核时点账面', async () => { + const stocks = await fetchStockRows(1); + const targetStock = stocks[0]; + const check = await createCheck({ title: uniqueTitle('审核刷新快照'), type: 'goods' }); + const added = await addDetail(check.id, [ targetStock.id ]); + assert.ok(added.added >= 1, '前置:应生成商品明细(按库位拆行)'); + + const detailsBefore = await detailCheck(check.id); + const targetDetail = detailsBefore.rows[0]; + const spaceId = Number(targetDetail.location_id); + + /** + * 读取指定商品在指定库位的当前账面(可用+锁定)。 + * + * @return {Promise} 账面数量。 + */ + async function readSpaceBook() { + const rows = await ctx.model.query( + `SELECT COALESCE(SUM(available_quantity + locked_quantity), 0) AS total + FROM wms_storage + WHERE warehouse_id = :warehouseId AND stock_id = :stockId AND space_id = :spaceId`, + { + replacements: { warehouseId: TEST_WAREHOUSE_ID, stockId: targetStock.id, spaceId }, + type: ctx.model.QueryTypes.SELECT, + } + ); + return Number(rows[0] && rows[0].total) || 0; + } + + const bookOnSubmit = await readSpaceBook(); + // 提交审核:快照=提交时点账面 + await submitCheck(check.id); + const afterSubmit = await ctx.model.StockCheckDetail.findByPk(targetDetail.id, { raw: true }); + assert.equal(Number(afterSubmit.system_quantity), bookOnSubmit, '提交时快照应等于提交时点账面'); + + // 模拟提交后、审核前的库存变动(该库位每行可用数量 +5) + await ctx.model.query( + `UPDATE wms_storage + SET available_quantity = available_quantity + 5 + WHERE warehouse_id = :warehouseId AND stock_id = :stockId AND space_id = :spaceId`, + { replacements: { warehouseId: TEST_WAREHOUSE_ID, stockId: targetStock.id, spaceId } } + ); + const bookAfterChange = await readSpaceBook(); + assert.ok(bookAfterChange > bookOnSubmit, '前置:库存变动后账面应增加'); + + try { + const auditResult = await auditCheck(check.id, 'approve'); + assert.equal( + Number(auditResult.snapshot_refreshed) >= 1, + true, + '审核通过应刷新快照并返回刷新行数' + ); + const afterAudit = await ctx.model.StockCheckDetail.findByPk(targetDetail.id, { raw: true }); + assert.equal( + Number(afterAudit.system_quantity), + bookAfterChange, + '审核通过后快照应刷新为审核时点账面(快照随库存变动更新为最新账面)' + ); + } finally { + // 回滚本次人为库存变更,避免污染开发库 + await ctx.model.query( + `UPDATE wms_storage + SET available_quantity = available_quantity - 5 + WHERE warehouse_id = :warehouseId AND stock_id = :stockId AND space_id = :spaceId`, + { replacements: { warehouseId: TEST_WAREHOUSE_ID, stockId: targetStock.id, spaceId } } + ); + } + }); + + it('完成盘点立即释放锁定:finish 清除缓存并返回 released_stock_ids,之后该商品不再锁定', async () => { + await clearLockCache(); + // 构造一个只属于本用例的商品(避免被历史静态任务同时锁定,便于验证释放) + const uniqueSuffix = `${Date.now()}-${Math.floor(Math.random() * 1000)}`; + const itemCode = `VERIFY-LOCK-${uniqueSuffix}`; + const [ fabricatedId ] = await ctx.model.query( + `INSERT INTO wms_stock_warehouse + (item_code, item_name, store_id, stock_unit, item_type, create_at, + warehouse_id, is_valid, quantity, is_shelf_life_mgmt, remaining_threshold_days) + VALUES (:itemCode, '静态锁定释放测试商品', :storeId, '个', 'normal', NOW(), + :warehouseId, 'Y', 3, 'N', 0)`, + { replacements: { itemCode, storeId: TEST_STORE_ID, warehouseId: TEST_WAREHOUSE_ID } } + ); + const stockId = Number(fabricatedId); + const [ validLocation ] = await fetchValidLocations(1); + assert.ok(validLocation, '前置:应存在有效库位'); + await ctx.model.query( + `INSERT INTO wms_storage + (warehouse_id, store_id, space_id, stock_id, batch_no, inventory_type, + quantity, expiry_date, inbound_time, inbound_order_no) + VALUES (:warehouseId, :storeId, :spaceId, :stockId, :batchNo, 'ZP', 3, NULL, NOW(), :orderNo)`, + { + replacements: { + warehouseId: TEST_WAREHOUSE_ID, + storeId: TEST_STORE_ID, + spaceId: validLocation.id, + stockId, + batchNo: `VERIFY-LOCK-BATCH-${uniqueSuffix}`, + orderNo: `VERIFY-LOCK-IN-${uniqueSuffix}`, + }, + type: ctx.model.QueryTypes.INSERT, + } + ); + + const check = await ctx.service.systems.stockCheck.create({ + warehouseId: TEST_WAREHOUSE_ID, + title: uniqueTitle('静态锁定-完成释放'), + type: 'goods', + isStatic: 1, + creatorId: TEST_CREATOR_ID, + creatorName: TEST_CREATOR_NAME, + }); + await addDetail(check.id, [ stockId ]); + await submitCheck(check.id); + await auditCheck(check.id, 'approve'); + + // 审核后锁定 + const lockedBefore = await ctx.service.systems.stockCheck.isStockStaticLocked({ + warehouseId: TEST_WAREHOUSE_ID, + stockId, + }); + assert.equal(lockedBefore.locked, true, '审核通过后该商品应在锁定集合中'); + + // 完成盘点 → 清缓存 + 返回释放商品 + 不再锁定 + const finishResult = await finishCheck(check.id); + assert.equal(finishResult.status, 'completed'); + assert.deepEqual(finishResult.released_stock_ids, [ stockId ], 'finish 应返回本任务覆盖的商品ID'); + const cacheAfterFinish = await readLockCache(); + assert.ok(cacheAfterFinish, '完成盘点应重建锁定缓存(不留空窗)'); + assert.equal( + cacheAfterFinish.stock_ids.includes(stockId), + false, + '重建后的缓存不应再包含该商品(已释放)' + ); + + // 完成盘点后该商品解除锁定,且缓存已重建(回源口径) + const lockedAfter = await ctx.service.systems.stockCheck.isStockStaticLocked({ + warehouseId: TEST_WAREHOUSE_ID, + stockId, + }); + assert.equal(lockedAfter.locked, false, '完成盘点后该商品应解除锁定'); + assert.deepEqual(lockedAfter.locked_stock_ids, []); + assert.equal(lockedAfter.cached, true, '完成时已重建缓存,判断应命中缓存'); + + // 清理本用例构造的商品数据 + await ctx.model.query('DELETE FROM wms_storage WHERE stock_id = :stockId', { replacements: { stockId } }); + await ctx.model.query('DELETE FROM wms_stock_warehouse WHERE id = :stockId', { replacements: { stockId } }); + }); + + it('空集合也缓存(不穿透):无锁定任务的仓库首次回源、二次命中;并发未命中只回源一次且结果一致', async () => { + // 用另一个测试仓库(无静态任务)验证「空结果缓存」与并发 singleflight + const emptyWarehouseId = OTHER_TEST_WAREHOUSE_ID; + const emptyKey = `stock_check:static_lock:${emptyWarehouseId}`; + await ctx.app.delCacheAsync(emptyKey); + + const firstEmpty = await ctx.service.systems.stockCheck.staticLockList({ warehouseId: emptyWarehouseId }); + assert.equal(firstEmpty.cached, false, '首次查询应回源'); + assert.deepEqual(firstEmpty.stock_ids, [], '无锁定任务时为空集合'); + assert.equal(firstEmpty.total, 0); + + const secondEmpty = await ctx.service.systems.stockCheck.staticLockList({ warehouseId: emptyWarehouseId }); + assert.equal(secondEmpty.cached, true, '空集合也会被缓存,二次查询命中(不穿透数据库)'); + assert.deepEqual(secondEmpty.stock_ids, []); + + // 并发未命中:singleflight 共用同一次回源,结果一致 + await ctx.app.delCacheAsync(emptyKey); + const concurrent = await Promise.all(Array.from({ length: 5 }, () => + ctx.service.systems.stockCheck.staticLockList({ warehouseId: emptyWarehouseId }))); + assert.equal(concurrent.length, 5); + for (const item of concurrent) { + assert.deepEqual(item.stock_ids, [], '并发查询结果应一致'); + } + assert.ok( + concurrent.every(item => item.cached === false), + '并发未命中时均由同一次回源答复(cached=false),不会各自打出多轮 SQL' + ); + + // forceRefresh 强制回源 + const forced = await ctx.service.systems.stockCheck.staticLockList({ + warehouseId: emptyWarehouseId, + forceRefresh: true, + }); + assert.equal(forced.cached, false, 'forceRefresh 应跳过缓存回源'); + + await ctx.app.delCacheAsync(emptyKey); + }); + + it('防脏读:回源期间发生状态流转(代次变化)时不写入旧快照,缓存保持为空由下次回源', async () => { + const guardWarehouseId = OTHER_TEST_WAREHOUSE_ID; + const guardKey = `stock_check:static_lock:${guardWarehouseId}`; + await ctx.app.delCacheAsync(guardKey); + + const service = ctx.service.systems.stockCheck; + const originalQuery = service._queryStaticLockRows; + try { + // 模拟「查询过程中另一个审核/完成流转正在重建缓存」:查询内部递增锁定代次 + service._queryStaticLockRows = async warehouseId => { + await service._bumpStaticLockGeneration(warehouseId); + return originalQuery.call(service, warehouseId); + }; + const guarded = await service.staticLockList({ warehouseId: guardWarehouseId, forceRefresh: true }); + assert.equal(guarded.cache_skipped, true, '代次变化时不写缓存'); + assert.equal(await ctx.app.getCacheAsync(guardKey), null, '旧快照不应写入缓存(避免脏读)'); + assert.deepEqual(guarded.stock_ids, [], '仍返回本次查询结果,供调用方使用'); + + // 恢复后正常写缓存 + service._queryStaticLockRows = originalQuery; + const normal = await service.staticLockList({ warehouseId: guardWarehouseId, forceRefresh: true }); + assert.equal(normal.cache_skipped, undefined, '无并发流转时正常写缓存'); + assert.ok(await ctx.app.getCacheAsync(guardKey), '缓存已写入'); + + // 状态流转会递增代次(审核通过时由 refreshStaticLockCache 递增) + const generationBefore = await service._readStaticLockGeneration(guardWarehouseId); + await service.refreshStaticLockCache(guardWarehouseId); + const generationAfter = await service._readStaticLockGeneration(guardWarehouseId); + assert.ok(generationAfter > generationBefore, 'refreshStaticLockCache 应递增锁定代次'); + } finally { + service._queryStaticLockRows = originalQuery; + await ctx.app.delCacheAsync(guardKey); + } + }); + + it('getStaticLockConflict:锁定商品返回可读冲突文案,未锁定返回空', async () => { + await clearLockCache(); + const stocks = await fetchStockRows(1); + const check = await ctx.service.systems.stockCheck.create({ + warehouseId: TEST_WAREHOUSE_ID, + title: uniqueTitle('静态锁定-冲突文案'), + type: 'goods', + isStatic: 1, + creatorId: TEST_CREATOR_ID, + creatorName: TEST_CREATOR_NAME, + }); + await addDetail(check.id, [ stocks[0].id ]); + await submitCheck(check.id); + await auditCheck(check.id, 'approve'); + + const conflict = await ctx.service.systems.stockCheck.getStaticLockConflict({ + warehouseId: TEST_WAREHOUSE_ID, + stockIds: [ stocks[0].id ], + actionLabel: '分配储位', + }); + assert.equal(conflict.locked, true); + assert.match(conflict.message, /禁止分配储位/); + assert.match(conflict.message, new RegExp(check.check_no), '冲突文案应含盘点单号'); + assert.equal(Number(conflict.rows[0].stock_id), Number(stocks[0].id)); + + const noConflict = await ctx.service.systems.stockCheck.getStaticLockConflict({ + warehouseId: TEST_WAREHOUSE_ID, + stockIds: [ 999999999 ], + actionLabel: '移库', + }); + assert.equal(noConflict.locked, false); + assert.equal(noConflict.message, ''); + assert.deepEqual(noConflict.rows, []); + + // 空入参不查库、不报错 + const emptyInput = await ctx.service.systems.stockCheck.getStaticLockConflict({ + warehouseId: TEST_WAREHOUSE_ID, + stockIds: [], + }); + assert.equal(emptyInput.locked, false); + }); + + it('方法层 staticLockList:仓库上下文注入、success 包装、缓存标识透出', async () => { + await clearLockCache(); + mockCurrentUser(); + const stocks = await fetchStockRows(1); + const check = await ctx.service.systems.stockCheck.create({ + warehouseId: TEST_WAREHOUSE_ID, + title: uniqueTitle('静态锁定-方法层'), + type: 'goods', + isStatic: 1, + creatorId: TEST_CREATOR_ID, + creatorName: TEST_CREATOR_NAME, + }); + await addDetail(check.id, [ stocks[0].id ]); + await submitCheck(check.id); + await auditCheck(check.id, 'approve'); + + // 审核通过时已重建缓存 → 首次调用即命中缓存 + const warmed = await ctx.service.systemMethods.stock.check.staticLockList(); + assert.equal(warmed.data.cached, true, '审核通过已重建缓存,首次调用应命中'); + + // 手动清除缓存后首次调用回源(cached=false),再次调用命中 + await clearLockCache(); + const first = await ctx.service.systemMethods.stock.check.staticLockList(); + assert.equal(first.flag, 'success'); + assert.equal(first.code, 1); + assert.equal(Number(first.data.warehouse_id), TEST_WAREHOUSE_ID, '仓库应由 ctx.user.store_id 注入'); + assert.ok(first.data.stock_ids.map(Number).includes(Number(stocks[0].id))); + assert.equal(first.data.cached, false); + assert.equal(first.data.total, first.data.rows.length); + + const second = await ctx.service.systemMethods.stock.check.staticLockList(); + assert.equal(second.flag, 'success'); + assert.equal(second.data.cached, true, '二次调用应命中缓存'); + + // 缺仓库上下文 → failure 400 + ctx.user = null; + const noWarehouse = await ctx.service.systemMethods.stock.check.staticLockList(); + assert.equal(noWarehouse.flag, 'failure'); + assert.equal(noWarehouse.code, 400); + }); + }); });