From 9edc0e3e471ccf051c4ca01f32f610545b33ea3e Mon Sep 17 00:00:00 2001 From: liufumingren Date: Wed, 28 Oct 2026 23:08:00 +0800 Subject: [PATCH] =?UTF-8?q?fix(stock.check):=20=E8=B4=A6=E9=9D=A2=E5=8F=A3?= =?UTF-8?q?=E5=BE=84=E6=94=B9=E5=8F=96=E5=8F=AF=E7=94=A8=E6=95=B0=E9=87=8F?= =?UTF-8?q?=E5=B9=B6=E6=96=B0=E5=A2=9E=E9=9D=99=E6=80=81=E7=9B=98=E7=82=B9?= =?UTF-8?q?=E6=8B=A3=E8=B4=A7=E5=AE=8C=E6=88=90=E6=A0=A1=E9=AA=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 账面口径统一为 wms_storage SUM(available_quantity)(不再加 locked_quantity),避免静态盘点在仍有在途拣货时开盘产生假盘亏(PD20261027000001 商品 160240 -115)。 静态盘点(is_static=1)新增拣货完成判定 _fetchStockLockedQuantityMap:workData/workDataDetail 输出 picking_completed 与明盘 locked_quantity,report 对仍有锁定量(未完成拣货)的商品返回 400 拒绝上报。 同步更新 methods/system.json(0.3.319~0.3.321)与 changes 变更记录。ESLint 0 错误。 --- app/service/systems/stock_check.js | 156 +++++++++++++--- methods/changes/system.json | 65 +++++++ methods/system.json | 71 +++---- script/stock-check-goods-summary-verify.cjs | 2 +- test/app/service/systems/stock_check.test.js | 184 +++++++++++++++++-- 5 files changed, 397 insertions(+), 81 deletions(-) diff --git a/app/service/systems/stock_check.js b/app/service/systems/stock_check.js index f3c7d01..b28d078 100644 --- a/app/service/systems/stock_check.js +++ b/app/service/systems/stock_check.js @@ -389,7 +389,7 @@ class StockCheckService extends Service { byStock.set(stockId, agg); } - // 库位行账面:wms_storage 按 (space_id, stock_id) SUM(可用+锁定),并附到按商品聚合 + // 库位行账面:wms_storage 按 (space_id, stock_id) SUM(可用数量),并附到按商品聚合 const storageQuantityMap = new Map(); const locationDetailRows = detailRows.filter(row => (row.scope_type || 'goods') === 'location'); const goodsDetailRows = detailRows.filter(row => (row.scope_type || 'goods') !== 'location'); @@ -416,7 +416,7 @@ class StockCheckService extends Service { attributes: [ 'space_id', 'stock_id', - [ literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ], + [ literal('SUM(available_quantity)'), 'totalQuantity' ], ], group: [ 'space_id', 'stock_id' ], raw: true, @@ -453,7 +453,7 @@ class StockCheckService extends Service { where: { space_id: { [Op.in]: emptyLocationIds } }, attributes: [ 'space_id', - [ literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ], + [ literal('SUM(available_quantity)'), 'totalQuantity' ], ], group: [ 'space_id' ], raw: true, @@ -1348,7 +1348,7 @@ class StockCheckService extends Service { const existingStockIds = new Set(existingRows.map(item => Number(item.stock_id))); // 商品在本仓库的启用库存库位(按库位拆分明细行:商品任务必须按库位盘点, - // 一个商品多个库位对应多行,各行账面 = 该库位库存 SUM(可用+锁定);无库存库位商品不可盘点; + // 一个商品多个库位对应多行,各行账面 = 该库位库存 SUM(可用数量);无库存库位商品不可盘点; // 库位有效性:仅统计有效库位(所属 zone 存在且未删除),无头库位(zone 不存在/已删除)不纳入盘点) const storageRows = await ctx.model.Storage.findAll({ where: { @@ -1362,7 +1362,7 @@ class StockCheckService extends Service { attributes: [ 'stock_id', 'space_id', - [ literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ], + [ literal('SUM(available_quantity)'), 'totalQuantity' ], ], group: [ 'stock_id', 'space_id' ], raw: true, @@ -2155,7 +2155,7 @@ class StockCheckService extends Service { * (未盘库位为 0),仅作业记录存在而快照不存在的库位追加在末尾(system_quantity=0)); * 库位范围行输出 { ...row, scope_type: 'location', stocks },stocks 按商品聚合该明细下记录 * [{ stock_id, item_code, item_name, system_quantity, checked_quantity, diff_quantity }], - * 账面数量查 wms_storage SUM(available_quantity+locked_quantity)(=可用+锁定),行级 checked_quantity 为行内合计、 + * 账面数量查 wms_storage SUM(available_quantity)(=可用数量,不含锁定待出库),行级 checked_quantity 为行内合计、 * diff_quantity 为行内各商品差异代数和; * 未知商品单独输出行级 unknown_items [{ barcode, item_name, checked_quantity }] * (无账面,差异 = 实盘 - 0 = 盘盈,已计入行级 checked_quantity/diff_quantity/is_diff)。 @@ -2310,7 +2310,7 @@ class StockCheckService extends Service { goodsGroups.get(stockId).push(detailRow); } - // 库位行需要:记录商品快照(wms_stock_warehouse)与库位账面(wms_storage 可用+锁定) + // 库位行需要:记录商品快照(wms_stock_warehouse)与库位账面(wms_storage 可用数量) const stockIds = new Set(); for (const detailRow of locationRows) { const detailRecords = recordsByDetail.get(Number(detailRow.id)) || []; @@ -2330,7 +2330,7 @@ class StockCheckService extends Service { stockMap = new Map(stockRows.map(item => [ Number(item.id), item ])); } - // 库位行账面:wms_storage 按 (space_id, stock_id) SUM(可用+锁定) + // 库位行账面:wms_storage 按 (space_id, stock_id) SUM(可用数量) const storageQuantityMap = new Map(); if (locationRows.length > 0 && stockIds.size > 0) { const locationIds = [ ...new Set(locationRows @@ -2345,7 +2345,7 @@ class StockCheckService extends Service { attributes: [ 'space_id', 'stock_id', - [ literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ], + [ literal('SUM(available_quantity)'), 'totalQuantity' ], ], group: [ 'space_id', 'stock_id' ], raw: true, @@ -2647,7 +2647,7 @@ class StockCheckService extends Service { if (isEmptyLocation && locationId > 0) { const emptyStorageRows = await ctx.model.Storage.findAll({ where: { space_id: locationId }, - attributes: [[ literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ]], + attributes: [[ literal('SUM(available_quantity)'), 'totalQuantity' ]], raw: true, }); locationSystemTotal = Number(emptyStorageRows[0] && emptyStorageRows[0].totalQuantity) || 0; @@ -2822,6 +2822,9 @@ class StockCheckService extends Service { * **space_id 必传**(wms_location_space.id,须属于本仓库且分区有效),库位以该 ID 为准, * location 编码入参仅做一致性校验(不一致报 400),服务端不再按编码猜库位; * 主表 approved 自动转 checking;重算 checked_items / diff_items / detail_status。 + * 静态盘点(is_static=1)商品范围任务额外要求「该商品已完全拣货」:仓库内该商品 + * wms_storage SUM(locked_quantity) > 0(存在已分配储位、尚未拣出的在途出库)时拒绝上报, + * 返回 400「商品尚未完成拣货,不满足静态盘点要求,请先等待该商品完全完成拣货」。 * 数据库层由唯一索引 uk_detail_stock_location(detail_id, stock_id, location_code) 保证并发安全。 * * 未知商品上报口径(stock_id 与 barcode 至少传一项): @@ -3148,6 +3151,15 @@ class StockCheckService extends Service { } } + // 静态盘点要求「该商品已完全拣货」:商品仍有锁定量说明存在已分配储位但尚未拣出的在途出库, + // 此时上报的实盘数与账面快照之间会夹着这批货,差异不可信,直接拒绝上报 + if (Number(check.is_static) === 1 && scopeType === 'goods' && normalizedStockId > 0) { + const stockLockedMap = await this._fetchStockLockedQuantityMap(warehouseId, [ normalizedStockId ]); + if ((stockLockedMap.get(normalizedStockId) || 0) > 0) { + throw this.createBusinessError('商品尚未完成拣货,不满足静态盘点要求,请先等待该商品完全完成拣货'); + } + } + const now = new Date(); // 覆盖式上报:已知商品按同明细 + 同商品 + 同库位编码(库位编码来自 space_id 对应库位)更新已有记录, @@ -3495,8 +3507,11 @@ class StockCheckService extends Service { * location 行含 detail_id/location_id/location_code/location_name/status/has_unknown/ * checked_at/checkers/goods(已知商品与未知商品记录均入 goods,未知商品 stock_id=null); * 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。 + * (明盘另含 system_quantity(账面快照合计)/checked_quantity/diff_quantity/is_diff; + * 静态盘点另含 picking_completed(1=该商品已完成拣货/0=未完成,判定口径=仓库内该商品锁定量为 0) + * 与明盘下的 locked_quantity(该商品仓库内锁定量合计)); + * space 行含 id/space_code/custom_barcode/custom_name/goods(goods 子项在静态盘点时 + * 另含 picking_completed,口径与 goods 视图行一致)。 * @throws {Error} 任务不存在或任务状态非 approved/checking 时抛出业务错误(错误码 400)。 */ async workData(params = {}) { @@ -3613,7 +3628,9 @@ class StockCheckService extends Service { * 拉取盘点作业数据(space 视图分页版)。 * 行结构与 workData space 视图行一致(id=库位ID/location_id 同义库位ID/space_code/custom_barcode/custom_name/goods), * 商品任务(scope_type=goods)按库位聚合;传入 location_id 时只返回该库位行(total=1), - * 不传时按分页返回全部库位行。 + * 不传时按分页返回全部库位行。静态盘点(is_static=1)时 goods 子项含 picking_completed + * (1=该商品已完成拣货/0=未完成,口径=仓库内该商品 wms_storage SUM(locked_quantity) 是否为 0, + * 按商品维度判定,明盘盲盘均返回)。 * * @param {Object} params 查询参数。 * @param {number} params.warehouseId 仓库ID(由方法层从上下文注入)。 @@ -3681,9 +3698,11 @@ class StockCheckService extends Service { * summary 为商品级汇总(明盘含 system_quantity 账面快照合计/checked_quantity 实盘合计/ * diff_quantity/is_diff;盲盘不含数量字段); * rows 为该商品每个库位一行(detail_id 该库位明细ID/location_id 与同义 space_id 库位ID/ - * location_code 库位编码,明盘另含 system_quantity 该库位当前账面(可用+锁定)/ + * location_code 库位编码,明盘另含 system_quantity 该库位当前账面(可用数量)/ * snapshot_quantity 该库位账面快照/locked_quantity 锁定数量/checked_quantity 该库位实盘/ - * diff_quantity 该库位差异(实盘-快照),另有 checked_at/checker_name/record_ids/images)。 + * diff_quantity 该库位差异(实盘-快照),另有 checked_at/checker_name/record_ids/images); + * 静态盘点另在顶层返回 picking_completed(1=该商品已完成拣货/0=未完成,判定口径=仓库内该商品 + * wms_storage SUM(locked_quantity) 是否为 0)与明盘下的 locked_quantity(仓库内锁定量合计)。 * * @param {Object} params 查询参数。 * @param {number} params.warehouseId 仓库ID(由方法层从上下文注入)。 @@ -3823,6 +3842,13 @@ class StockCheckService extends Service { book_source: goodsRow.book_source === 'snapshot' ? 'snapshot' : 'storage', rows, }; + // 静态盘点:该商品是否已完成拣货(1=已完成/0=未完成);盲盘不输出锁定量数值 + if (Number(goodsRow.is_static) === 1) { + detail.picking_completed = Number(goodsRow.picking_completed) === 1 ? 1 : 0; + if (isOpen) { + detail.locked_quantity = Number(goodsRow.locked_quantity) || 0; + } + } if (isOpen) { detail.summary = { system_quantity: Number(goodsRow.system_quantity) || 0, @@ -3997,13 +4023,16 @@ class StockCheckService extends Service { * stock_id 为空/异常的明细行无法按商品归并,各自成行。 * locations 为商品所在全部库位(wms_storage 中该商品的 space_id 集合,按拣货路径排序): * 明盘(mode=open)每库位含 system_quantity(该库位账面数量,wms_storage space+stock - * SUM(available_quantity+locked_quantity),无库存记录库位为 0)、locked_quantity(该库位锁定数量, + * SUM(available_quantity),无库存记录库位为 0)、locked_quantity(该库位锁定数量, * wms_storage space+stock SUM(locked_quantity))与 quantity(该库位盘点数量=实盘合计,未盘库位为 0),三者区分开; * 盲盘(mode=blind)只显示库位(location_code)不含任何数量字段;已盘库位额外含 * checked_at/checker_name/record_ids/images,未盘库位这些字段为 null/空数组; * 商品库存已无记录但已盘的库位(仅记录库位)追加在末尾。 * 明盘行级返回 system_quantity(账面快照合计=该商品各库位明细行快照之和)/ * checked_quantity(已盘合计)/diff_quantity/is_diff; + * 静态盘点(is_static=1)另返回 picking_completed(1=该商品已完成拣货/0=未完成, + * 口径=仓库内该商品 wms_storage SUM(locked_quantity) 是否为 0)与明盘下的 locked_quantity + * (该商品仓库内锁定量合计;盲盘不输出该数值); * 商品基础信息批量取自 stockWarehouse.getStockDetails(未命中回退明细商品快照), * 货主名经 _resolveStoreNameMap 解析。 * @@ -4011,7 +4040,7 @@ class StockCheckService extends Service { * @param {number} checkId 盘点任务ID。 * @param {string} mode 盘点方式:open=明盘/blind=盲盘。 * @param {boolean} [isStatic=false] 是否静态盘点(is_static=1):true=账面取明细快照, - * false=账面取当前 wms_storage(可用+锁定)。 + * false=账面取当前 wms_storage(可用数量)。 * @return {Promise>} 商品视图行列表(按商品首个明细 id 升序)。 */ async _buildGoodsWorkRows(warehouseId, checkId, mode, isStatic = false) { @@ -4039,6 +4068,13 @@ class StockCheckService extends Service { const stockIds = [ ...new Set(detailRows .map(row => Number(row.stock_id)) .filter(stockId => Number.isInteger(stockId) && stockId > 0)) ]; + + // 静态盘点:拣货完成判定——商品在仓库内仍存在锁定量(wms_storage SUM(locked_quantity) > 0) + // 即说明有已分配储位但未拣出的在途出库,拣货未完成(report 对未完成拣货的商品拒绝上报) + const stockLockedQuantityMap = isStatic + ? await this._fetchStockLockedQuantityMap(warehouseId, stockIds) + : new Map(); + let stockDetailMap = new Map(); if (stockIds.length > 0) { const stockDetails = await ctx.service.systems.stockWarehouse.getStockDetails(stockIds, { @@ -4052,7 +4088,7 @@ class StockCheckService extends Service { const storeNameMap = await this._resolveStoreNameMap(storeIds, warehouseId); // 商品所在库位:wms_storage(warehouse + stock_id 在集合 + 启用未删除)DISTINCT space_id - // 同时按 stock+space 汇总账面数量(该库位系统库存,口径=可用+锁定)与锁定数量, + // 同时按 stock+space 汇总账面数量(该库位系统库存,口径=可用数量)与锁定数量, // 供明盘 locations.system_quantity / locked_quantity 使用 const stockSpaceIdsMap = new Map(); const stockSpaceQuantityMap = new Map(); @@ -4069,7 +4105,7 @@ class StockCheckService extends Service { attributes: [ 'stock_id', 'space_id', - [ literal('SUM(available_quantity + locked_quantity)'), 'system_quantity' ], + [ literal('SUM(available_quantity)'), 'system_quantity' ], [ fn('SUM', col('locked_quantity')), 'locked_quantity' ], ], group: [ 'stock_id', 'space_id' ], @@ -4236,6 +4272,15 @@ class StockCheckService extends Service { book_source: isStatic ? 'snapshot' : 'storage', locations: [], }; + // 静态盘点:该商品是否已完成拣货(1=已完成/0=未完成,判定口径=仓库内该商品锁定量是否为 0); + // 盲盘不输出锁定量数值(与盲盘不含数量字段口径一致),仅输出完成标记 + if (isStatic) { + const lockedQuantity = stockLockedQuantityMap.get(stockId) || 0; + row.picking_completed = lockedQuantity > 0 ? 0 : 1; + if (isOpen) { + row.locked_quantity = lockedQuantity; + } + } if (isOpen) { row.system_quantity = 0; row.checked_quantity = 0; @@ -4303,7 +4348,7 @@ class StockCheckService extends Service { }; if (isOpen) { // 明盘:逐库位账面按任务是否静态取值——静态盘点取该库位明细快照(盘点基准冻结), - // 非静态取当前 wms_storage 账面(可用+锁定);两者同时输出便于对照, + // 非静态取当前 wms_storage 账面(可用数量);两者同时输出便于对照, // system_quantity 始终为「本次参与差异计算的账面」 const spaceQuantity = (spaceQuantityByStockMap.get(stockId) || new Map()).get(code || '') || {}; const storageQuantity = Number(spaceQuantity.system_quantity) || 0; @@ -4356,8 +4401,10 @@ class StockCheckService extends Service { * 库位仅按拣货顺序排序:pick_sequence 升序(pick_priority/库位 id 不参与排序, * 同值保持库位查询顺序); * 行内 goods 为该库位下的任务商品:明盘含 system_quantity(wms_storage space+stock - * SUM(available_quantity+locked_quantity))、locked_quantity(wms_storage space+stock SUM(locked_quantity)) + * SUM(available_quantity))、locked_quantity(wms_storage space+stock SUM(locked_quantity)) * 与 checked_quantity(该商品在该库位的实盘合计),盲盘不返回任何数量字段; + * 静态盘点(is_static=1)goods 子项另含 picking_completed(1=该商品已完成拣货/0=未完成, + * 口径=仓库内该商品 wms_storage SUM(locked_quantity) 是否为 0,按商品维度判定,明盘盲盘均返回); * status 已盘口径:该 (库位, 商品) 存在作业记录(兼容按明细 + 库位编码命中); * 未在 wms_storage 有库位的商品不入列表(无库位可聚)。 * @@ -4365,7 +4412,7 @@ class StockCheckService extends Service { * @param {number} checkId 盘点任务ID。 * @param {string} mode 盘点方式:open=明盘/blind=盲盘。 * @param {boolean} [isStatic=false] 是否静态盘点(is_static=1):true=账面取明细快照, - * false=账面取当前 wms_storage(可用+锁定)。 + * false=账面取当前 wms_storage(可用数量)。 * @return {Promise>} 聚合库位视图行列表(按拣货路径排序)。 */ async _buildSpaceWorkRows(warehouseId, checkId, mode, isStatic = false) { @@ -4386,6 +4433,13 @@ class StockCheckService extends Service { const isOpen = mode !== 'blind'; + // 静态盘点:拣货完成判定——商品在仓库内仍存在锁定量(wms_storage SUM(locked_quantity) > 0) + // 即说明有已分配储位但未拣出的在途出库,拣货未完成;判定按商品维度(非库位维度), + // 同一商品在各库位行上的 picking_completed 取值一致 + const stockLockedQuantityMap = isStatic + ? await this._fetchStockLockedQuantityMap(warehouseId, stockIds) + : new Map(); + const records = await ctx.model.StockCheckRecord.findAll({ where: { check_id: checkId, warehouse_id: Number(warehouseId) }, order: [[ 'id', 'ASC' ]], @@ -4412,7 +4466,7 @@ class StockCheckService extends Service { ); // 任务商品所在库位:wms_storage(warehouse + stock_id 在集合 + 启用未删除)DISTINCT space_id, - // 同时按 (space_id, stock_id) 汇总账面数量(口径=可用+锁定)与锁定数量 + // 同时按 (space_id, stock_id) 汇总账面数量(口径=可用数量)与锁定数量 const storageRows = await ctx.model.Storage.findAll({ where: { warehouse_id: Number(warehouseId), @@ -4424,7 +4478,7 @@ class StockCheckService extends Service { attributes: [ 'space_id', 'stock_id', - [ literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ], + [ literal('SUM(available_quantity)'), 'totalQuantity' ], [ fn('SUM', col('locked_quantity')), 'totalLockedQuantity' ], ], group: [ 'space_id', 'stock_id' ], @@ -4712,6 +4766,11 @@ class StockCheckService extends Service { 0 ); } + // 静态盘点:该商品是否已完成拣货(1=已完成/0=未完成,按商品维度判定—— + // 仓库内该商品锁定量为 0 才算完成;盲盘同样输出,便于上报前拦截提示) + if (isStatic) { + item.picking_completed = (stockLockedQuantityMap.get(stockId) || 0) > 0 ? 0 : 1; + } item.status = locationRecords.length > 0 ? 'checked' : 'unchecked'; return item; }) @@ -5166,10 +5225,51 @@ class StockCheckService extends Service { }; } + /** + * 查询商品在仓库内的锁定量合计(wms_storage SUM(locked_quantity)),用于判定是否已完成拣货。 + * 分配储位(拣货锁库)只把 available_quantity 搬成 locked_quantity;拣货完成时 + * quantity 与 locked_quantity 同时扣减、available_quantity 不变。因此 + * locked_quantity > 0 即表示该商品仍有「已分配储位、尚未拣出」的在途出库,拣货未完成; + * locked_quantity = 0 即该商品已完全拣货。 + * + * @param {number} warehouseId 仓库ID。 + * @param {Array|number} stockIds 商品库存ID(wms_stock_warehouse.id),单值自动转数组。 + * @return {Promise>} stock_id → 锁定量合计(无库存记录的商品不在 Map 中)。 + */ + async _fetchStockLockedQuantityMap(warehouseId, stockIds) { + const { ctx } = this; + const { Op, literal } = ctx.app.Sequelize; + + const numericStockIds = [ ...new Set((Array.isArray(stockIds) ? stockIds : [ stockIds ]) + .map(stockId => Number(stockId)) + .filter(stockId => Number.isInteger(stockId) && stockId > 0)) ]; + if (numericStockIds.length === 0) { + return new Map(); + } + + const rows = await ctx.model.Storage.findAll({ + where: { + warehouse_id: Number(warehouseId), + stock_id: { [Op.in]: numericStockIds }, + is_enabled: 1, + }, + attributes: [ + 'stock_id', + [ literal('SUM(locked_quantity)'), 'lockedQuantity' ], + ], + group: [ 'stock_id' ], + raw: true, + }); + return new Map(rows.map(row => [ Number(row.stock_id), Number(row.lockedQuantity) || 0 ])); + } + /** * 刷新商品范围明细行的账面快照(盘点基准)。 - * 商品范围(scope_type=goods)任务把各明细行 system_quantity 刷新为该库位当时的账面 - * SUM(available_quantity+locked_quantity)(库存记录不存在时按 0): + * 商品范围(scope_type=goods)任务把各明细行 system_quantity 刷新为该库位当时的可用数量 + * SUM(available_quantity)(= 库存总量 − 锁定数量 − 拦截锁定数量;库存记录不存在时按 0): + * 账面只统计可用数量,不把 locked_quantity(已分配储位、待拣出库)计入: + * 分配储位只搬 available→locked(账面不变),拣货完成同时扣 quantity 与 locked、 + * available 不变,因此「可用数量」口径在静态盘点窗口内对拣货动作不敏感。 * - 提交审核时调用(保证 result/差异对比使用提交时点的账面); * - 审核通过时再次调用(盘点基准以「审核完成=开始盘点」时刻为准,覆盖提交后到达的出入库); * 库位范围(scope_type=location)账面实时查 wms_storage,不处理。 @@ -5195,7 +5295,7 @@ class StockCheckService extends Service { .map(row => Number(row.stock_id)) .filter(stockId => Number.isInteger(stockId) && stockId > 0)) ]; - // 按 (stock_id, space_id) 聚合当前账面:SUM(可用+锁定) + // 按 (stock_id, space_id) 聚合当前账面:SUM(可用数量) const storageQuantityMap = new Map(); if (stockIds.length > 0) { const storageRows = await ctx.model.Storage.findAll({ @@ -5207,7 +5307,7 @@ class StockCheckService extends Service { attributes: [ 'stock_id', 'space_id', - [ literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ], + [ literal('SUM(available_quantity)'), 'totalQuantity' ], ], group: [ 'stock_id', 'space_id' ], raw: true, diff --git a/methods/changes/system.json b/methods/changes/system.json index eb637a2..b8f1363 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,69 @@ [ + { + "version": "0.3.321", + "date": "2026-10-28", + "type": "updated", + "summary": "space 视图补齐静态盘点拣货完成标记:stock.check.workData(space 视图)与 stock.check.workDataSpaceDetails 的 goods 子项在 is_static=1 时新增 picking_completed(是否已完成拣货),口径与 goods 视图一致", + "methods": [ + "stock.check.workData", + "stock.check.workDataSpaceDetails" + ], + "notes": [ + "背景:0.3.320 已在 goods 视图行与商品钻取输出 picking_completed,但盘点作业前端默认使用 space 视图(workData 不传 is_goods)与 workDataSpaceDetails(库位分页),这两条链路拿不到拣货完成状态,无法在上报前提示/置灰。", + "现口径:_buildSpaceWorkRows 在 is_static=1 时按商品维度查询仓库内 SUM(locked_quantity)(_fetchStockLockedQuantityMap),goods 子项输出 picking_completed(1=已完成拣货/0=未完成);同一商品在各库位行上的取值一致(商品维度,非库位维度)。盲盘(mode=blind)同样返回该标记,但仍不返回任何数量字段(locked_quantity 仍只在明盘输出)。", + "workDataSpaceDetails 复用同一 space 视图构建函数,因此自动获得该字段,无需额外参数;与 stock.check.report 的静态盘点上报拦截配套(商品未完成拣货返回 400「商品尚未完成拣货,不满足静态盘点要求,请先等待该商品完全完成拣货」)。", + "兼容性:非静态任务(is_static=0)不返回 picking_completed,行为与之前一致;未新增必填入参;原有 system_quantity/storage_quantity/locked_quantity/snapshot_quantity/checked_quantity 字段口径与取值均未变化。", + "测试:test/app/service/systems/stock_check.test.js 的「静态盘点拣货完成标记」用例补充 space 视图(workData 默认视图)与 workDataSpaceDetails(按 location_id 取库位行)的 picking_completed 断言,锁定量存在时为 0、清零后为 1。真实库全量 256 用例通过、ESLint 0 错误。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 2 条 method(stock.check.workData:description/response.rows 的 space 视图 goods 字段说明 + notes;stock.check.workDataSpaceDetails:description + 新增 notes);根版本 0.3.320 → 0.3.321、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位)。", + "代码依据:app/service/systems/stock_check.js#_buildSpaceWorkRows/#workDataSpaceDetails/#_fetchStockLockedQuantityMap。" + ] + }, + { + "version": "0.3.320", + "date": "2026-10-28", + "type": "updated", + "summary": "静态盘点拣货完成口径:stock.check.workData(goods 视图)与 stock.check.workDataDetail(商品钻取)新增 picking_completed(是否已完成拣货,判定=该商品在仓库内 wms_storage SUM(locked_quantity) 是否为 0)与明盘 locked_quantity;stock.check.report 对静态盘点且仍未完成拣货的商品拒绝上报", + "methods": [ + "stock.check.workData", + "stock.check.workDataDetail", + "stock.check.report" + ], + "notes": [ + "背景:静态盘点审核通过即冻结账面基准,但盘点期间仍允许把「已分配储位、尚未拣出」的存量锁定货拣走(静态锁定只拦截新的储位分配,不拦截已有锁定)。若实盘发生在该批货拣完之前,实盘数与其后扣减的库位库存会相互矛盾,差异不可信(生产 PD20261027000001 商品 160240:快照后仍有 129 件在拣,最终产生 -115 的假盘亏)。", + "现口径:静态盘点(is_static=1)要求「该商品已完成拣货」——判定依据为 wms_storage 中该商品在仓库内 SUM(locked_quantity) 是否为 0。分配储位只把 available_quantity 搬成 locked_quantity(quantity 不变),拣货完成时 quantity 与 locked_quantity 同时扣减、available_quantity 不变,因此 locked_quantity>0 即表示仍有在途待拣出库。", + "新增字段:stock.check.workData goods 视图行在 is_static=1 时返回 picking_completed(1=已完成/0=未完成)与明盘 locked_quantity(该商品仓库内锁定量合计,盲盘不输出数值只输出完成标记);stock.check.workDataDetail 商品钻取在 is_static=1 时顶层返回同名两字段,口径一致。", + "上报拦截:stock.check.report 在任务 is_static=1 且为商品范围明细(scope_type=goods)时,写记录前校验该商品锁定量,>0 直接 400「商品尚未完成拣货,不满足静态盘点要求,请先等待该商品完全完成拣货」。库位范围任务 is_static 恒为 0,不受影响;未知商品(stock_id 为空)无锁定量,不受影响。", + "兼容性:非静态任务(is_static=0)不返回 picking_completed,行为与之前一致;未新增必填入参,前端可忽略新字段。锁定量判定按仓库维度(不限任务库位范围),与静态锁定商品(stock 维度)口径一致。", + "测试:test/app/service/systems/stock_check.test.js 新增「静态盘点拣货完成标记」用例——人为把 available 搬成 locked 后断言 goods 视图/钻取 picking_completed=0 且 locked_quantity 正确、report 被拒;锁定量清零后 picking_completed=1 且上报成功。原「账面取值按任务静态标记」用例改为仅取无锁定量商品并在 finally 完成盘点释放静态锁定。真实库全量 256 用例通过、ESLint 0 错误。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 3 条 method(stock.check.workData:response.rows 商品视图字段补 picking_completed/locked_quantity + notes;stock.check.workDataDetail:description + notes;stock.check.report:description、errors 400 文案 + notes);根版本 0.3.319 → 0.3.320、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位)。", + "代码依据:app/service/systems/stock_check.js#_fetchStockLockedQuantityMap/#_buildGoodsWorkRows/#_formatGoodsWorkDetail/#report。" + ] + }, + { + "version": "0.3.319", + "date": "2026-10-28", + "type": "updated", + "summary": "盘点账面口径统一改为可用数量(wms_storage SUM(available_quantity)),不再把 locked_quantity(已分配储位、待拣出库的锁定量)计入账面;商品明细快照、动态实时账面、库位盘点、明盘工作台/钻取全部统一", + "methods": [ + "stock.check.addDetail", + "stock.check.result", + "stock.check.report", + "stock.check.finish", + "stock.check.submit", + "stock.check.audit", + "stock.check.workData", + "stock.check.workDataDetail" + ], + "notes": [ + "背景:原账面口径为 SUM(available_quantity + locked_quantity)(=可用+锁定),会把已分配储位但尚未拣出的锁定量算进账面。静态盘点若在仍有在途拣货时开盘,快照会包含这批货,拣货完成后即变成假盘亏(生产 PD20261027000001:商品 160240 账面 248 vs 实盘 133,差异 -115,其中 129 件是快照后 19:02-20:51 才从库位拣出的)。", + "现口径:全部盘点账面统一取 wms_storage SUM(available_quantity)(= quantity - locked_quantity - intercept_locked_quantity)。涉及:addDetail 拆行快照、submit/audit 刷新快照、result 库位行与空库位标记、_recalcCheckSummary/report/finish 差异汇总、workData/workDataDetail 明盘实时账面。", + "语义依据:分配储位只把 available 搬成 locked(quantity 不变、账面不变);拣货完成同时扣 quantity 与 locked、available 不变。因此可用数量口径在盘点窗口内对拣货动作不敏感,锁定货拣完前后都成立。", + "兼容性:locked_quantity 字段继续单独输出(明细 locations.locked_quantity / space 视图 goods.locked_quantity),仅不再计入 system_quantity;前端如需「含锁定总量」请用 system_quantity + locked_quantity 或直接查 storage.quantity。", + "历史任务:已完成任务 system_quantity 为旧口径快照,本次不回刷;如需对齐新口径需驳回重新提交或重新审核触发快照刷新。", + "测试:test/app/service/systems/stock_check.test.js 账面 helper/断言同步改为 SUM(available_quantity),真实库全量 255 用例通过,ESLint 0 错误。", + "代码依据:app/service/systems/stock_check.js#_addGoodsDetailRows/#_refreshGoodsBookSnapshot/#_recalcCheckSummary/#result/#_formatDetailAggregationRow/#_buildGoodsWorkRows/#_buildSpaceWorkRows。" + ] + }, { "version": "0.3.318", "date": "2026-10-28", diff --git a/methods/system.json b/methods/system.json index 906643b..03bc09b 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,7 +1,7 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.318", + "version": "0.3.321", "updatedAt": "2026-10-28", "headers": [ { @@ -38829,7 +38829,7 @@ "商品货主限制:任务 store_id 非空时商品 store_id 必须与之一致,不一致计入 invalid_stock_ids(限制非本货主商品加入盘点)。", "全盘自动范围(原 all 语义):type=location 且未传库位且未传 location_ids 时,自动拉取当前仓库全部启用且有效库位(is_enabled=true 且所属 zone 存在未删除,排除无头库位)的 space_code 生成库位行;无启用库位时报 400。", "幂等:商品行按 check_id+stock_id 整体跳过(同商品重复添加整体跳过,不重复拆行)、库位行按 check_id+location_code 跳过(商品行唯一索引 uk_check_stock_location(check_id, stock_id, location_id),库位行原唯一约束 uk_check_location 已放宽为普通索引 idx_check_location、幂等由应用层查重保证);location_ids 路径跳过项按库位ID记入 skipped。", - "商品拆行口径(本次改造,商品任务必须按库位盘点):type=store/goods 传 stock_ids 后按商品在仓库的启用库存库位(wms_storage is_enabled=1 且库位有效(未删除且所属 zone 存在未删除,排除无头库位),按 space_id 分组 SUM(available_quantity+locked_quantity)(=可用+锁定))拆行——每个「商品+库位」生成一条 scope_type=goods 明细行(location_id/location_code 快照绑定库存库位、system_quantity=该库位库存 SUM(可用+锁定));一个商品多个库位对应多行;无启用库存库位的商品计入 invalid_stock_ids 不入明细;added/total_items 均为拆分明细行数。代码依据:app/service/systems/stock_check.js#_addGoodsDetailRows(Storage.findAll warehouse_id+stock_id in+is_enabled=1、attributes SUM(quantity)、group=[stock_id, space_id];LocationSpace 按 id 取 space_code 快照)。", + "商品拆行口径(本次改造,商品任务必须按库位盘点):type=store/goods 传 stock_ids 后按商品在仓库的启用库存库位(wms_storage is_enabled=1 且库位有效(未删除且所属 zone 存在未删除,排除无头库位),按 space_id 分组 SUM(available_quantity)(=可用数量,不含锁定待出库))拆行——每个「商品+库位」生成一条 scope_type=goods 明细行(location_id/location_code 快照绑定库存库位、system_quantity=该库位库存 SUM(可用数量));一个商品多个库位对应多行;无启用库存库位的商品计入 invalid_stock_ids 不入明细;added/total_items 均为拆分明细行数。代码依据:app/service/systems/stock_check.js#_addGoodsDetailRows(Storage.findAll warehouse_id+stock_id in+is_enabled=1、attributes SUM(quantity)、group=[stock_id, space_id];LocationSpace 按 id 取 space_code 快照)。", "响应统一 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)。" ] }, @@ -38954,7 +38954,7 @@ }, { "method": "stock.check.detail", - "description": "拉取盘点任务详情(只返回任务本身信息):入参 id(盘点任务ID);返回 { check },check 为盘点主表信息(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;start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间))+ 数量差异汇总 profit_total(盘盈合计数量)/loss_total(盘亏合计数量,正数口径,与 finish 一致;商品范围按商品聚合 vs 账面快照合计(未盘商品按实盘 0 计盘亏)、库位行按商品聚合 vs wms_storage 账面(SUM(available_quantity+locked_quantity)=可用+锁定,未盘库位行不计差异)、未知商品按实盘计盘盈;无作业记录时均为 0);不再返回明细范围行(rows)与明细总条数(total)——盘点明细范围行/盘点结果聚合请调用 stock.check.result,作业记录请调用 stock.check.recordList,盘点作业数据请调用 stock.check.workData;400 边界(任务ID为空/任务不存在)。", + "description": "拉取盘点任务详情(只返回任务本身信息):入参 id(盘点任务ID);返回 { check },check 为盘点主表信息(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;start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间))+ 数量差异汇总 profit_total(盘盈合计数量)/loss_total(盘亏合计数量,正数口径,与 finish 一致;商品范围按商品聚合 vs 账面快照合计(未盘商品按实盘 0 计盘亏)、库位行按商品聚合 vs wms_storage 账面(SUM(available_quantity)=可用数量,未盘库位行不计差异)、未知商品按实盘计盘盈;无作业记录时均为 0);不再返回明细范围行(rows)与明细总条数(total)——盘点明细范围行/盘点结果聚合请调用 stock.check.result,作业记录请调用 stock.check.recordList,盘点作业数据请调用 stock.check.workData;400 边界(任务ID为空/任务不存在)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -39003,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/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=盘点结束时间(完成盘点的时间))" + "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)=可用数量,未盘库位行不计差异)、未知商品按实盘计盘盈);start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间))" } ] }, @@ -39036,7 +39036,7 @@ }, { "method": "stock.check.result", - "description": "拉取盘点明细结果(盘点前/盘点后后台查看明细专用,不再作为盘点作业数据提供):入参 id(盘点任务ID);返回 { check, rows, total };无作业记录(如待提交/盘点前)时 rows 直接返回 wms_stock_check_detail 明细范围行(原始行,不聚合);有作业记录时商品范围按商品聚合(一个商品一行,多个库位明细行合并):行含商品快照 + system_quantity(账面快照合计=各库位明细行 system_quantity 之和,创建明细时落库=盘点时做快照)+ 已盘聚合(checked_quantity=作业记录数量合计、diff_quantity=实盘-账面快照合计、is_diff、status=checked|unchecked、location_codes、checkers、last_checked_at)+ records(该商品在 wms_stock_check_record 的全部作业记录,每条含 barcode/item_name 与 images 图片列表)+ locations(商品所在库位列表 [{ location_id, location_code, system_quantity, quantity }],system_quantity 为该库位账面快照(盘点时做快照)、quantity 为该库位实盘合计(未盘库位为 0),按明细 id 升序;仅作业记录存在而快照不存在的库位追加在末尾且 system_quantity=0)+ unknown_items(未知商品按条码聚合 [{ barcode, item_name, checked_quantity }],无账面、差异=实盘-0=盘盈);库位行(scope_type=location)含 is_empty(是否空库位标记)+ checked_quantity(行级合计=行内商品实盘合计)、diff_quantity(行内各商品差异代数和)、is_diff、status + records/locations + stocks(按商品聚合 [{ stock_id, item_code, item_name, system_quantity, checked_quantity, diff_quantity }],按 stock_id 升序,账面 system_quantity 查 wms_storage(space_id+stock_id SUM(available_quantity+locked_quantity)=可用+锁定),location_id 为空时账面按 0)+ unknown_items(口径同商品范围);主表计数 check.total_items/checked_items/diff_items 按聚合行口径同步输出(商品范围按商品计数);每条作业记录挂载 images(FileReference business_type=stock_check_record,仿收货 receivingItem 口径);空库位标记(is_empty=true)时:stocks=[]、unknown_items=[]、checked_quantity=0、status=checked(视为已盘点),账面有库存时 diff_quantity 为负数(盘亏,差异=0-库位账面库存总量)、is_diff=1;无作业记录时 rows 直接返回明细范围行(原始行,见下)。", + "description": "拉取盘点明细结果(盘点前/盘点后后台查看明细专用,不再作为盘点作业数据提供):入参 id(盘点任务ID);返回 { check, rows, total };无作业记录(如待提交/盘点前)时 rows 直接返回 wms_stock_check_detail 明细范围行(原始行,不聚合);有作业记录时商品范围按商品聚合(一个商品一行,多个库位明细行合并):行含商品快照 + system_quantity(账面快照合计=各库位明细行 system_quantity 之和,创建明细时落库=盘点时做快照)+ 已盘聚合(checked_quantity=作业记录数量合计、diff_quantity=实盘-账面快照合计、is_diff、status=checked|unchecked、location_codes、checkers、last_checked_at)+ records(该商品在 wms_stock_check_record 的全部作业记录,每条含 barcode/item_name 与 images 图片列表)+ locations(商品所在库位列表 [{ location_id, location_code, system_quantity, quantity }],system_quantity 为该库位账面快照(盘点时做快照)、quantity 为该库位实盘合计(未盘库位为 0),按明细 id 升序;仅作业记录存在而快照不存在的库位追加在末尾且 system_quantity=0)+ unknown_items(未知商品按条码聚合 [{ barcode, item_name, checked_quantity }],无账面、差异=实盘-0=盘盈);库位行(scope_type=location)含 is_empty(是否空库位标记)+ checked_quantity(行级合计=行内商品实盘合计)、diff_quantity(行内各商品差异代数和)、is_diff、status + records/locations + stocks(按商品聚合 [{ stock_id, item_code, item_name, system_quantity, checked_quantity, diff_quantity }],按 stock_id 升序,账面 system_quantity 查 wms_storage(space_id+stock_id SUM(available_quantity)=可用数量),location_id 为空时账面按 0)+ unknown_items(口径同商品范围);主表计数 check.total_items/checked_items/diff_items 按聚合行口径同步输出(商品范围按商品计数);每条作业记录挂载 images(FileReference business_type=stock_check_record,仿收货 receivingItem 口径);空库位标记(is_empty=true)时:stocks=[]、unknown_items=[]、checked_quantity=0、status=checked(视为已盘点),账面有库存时 diff_quantity 为负数(盘亏,差异=0-库位账面库存总量)、is_diff=1;无作业记录时 rows 直接返回明细范围行(原始行,见下)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -39091,7 +39091,7 @@ "name": "rows", "type": "array", "required": true, - "description": "明细结果行列表:商品范围按商品聚合(一个商品一行,多个库位明细行合并)——行含范围行字段(合并后行级 location_id/location_code 为 null)+ system_quantity(账面快照合计=各库位明细行 system_quantity 之和,创建明细时落库=盘点时做快照)+ 已盘聚合字段(checked_quantity 已盘数量=作业记录 quantity 合计,无记录为 null;diff_quantity 差异数量=已盘-账面快照合计,无记录为 null;is_diff 是否有差异 0|1;status 盘点状态 checked|unchecked;location_codes 库位编码数组去重;checkers 盘点人数组去重;last_checked_at 最近上报时间,无记录为 null)+ records(该商品全部盘点作业记录,每条含 id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/barcode/item_name/created_at/updated_at + images 图片列表 [{ id: file_id, url }],FileReference business_type=stock_check_record)+ locations(商品所在库位列表 [{ location_id, location_code, system_quantity, quantity }],system_quantity 为该库位账面快照(创建明细时落库)、quantity 为该库位实盘合计(未盘库位为 0),按明细 id 升序;仅作业记录存在而快照不存在的库位追加在末尾且 system_quantity=0)+ unknown_items(未知商品聚合数组 [{ barcode, item_name, checked_quantity }],按条码升序;记录 stock_id 为空的未知商品按条码归组,无账面、差异=实盘-0=盘盈,已计入行级 checked_quantity/diff_quantity/is_diff;无未知商品为空数组);库位行(scope_type=location)含范围行字段 + is_empty(是否空库位标记:该明细存在空标记记录(is_empty=1)时为 true)+ stocks(按商品聚合数组 [{ stock_id, item_code, item_name, system_quantity, checked_quantity, diff_quantity }],按 stock_id 升序,仅含存在作业记录的已知商品;system_quantity 为 wms_storage 账面(space_id+stock_id SUM(available_quantity+locked_quantity)=可用+锁定),location_id 为空时按 0)+ checked_quantity(行级合计=行内商品实盘合计,无记录为 null)/ diff_quantity(行内各商品差异代数和,无记录为 null)/ is_diff / status + location_codes / checkers / last_checked_at + records / locations + unknown_items(口径同商品行);空库位标记(is_empty=true)时:stocks=[]、unknown_items=[]、checked_quantity=0、diff_quantity=0-库位账面库存总量(账面有库存时为负数=盘亏、账面为 0 时为 0)、is_diff=账面有库存时为 1、status=checked(视为已盘点);无作业记录(盘点前/待提交等)时 rows 直接返回 wms_stock_check_detail 明细范围行(原始行,含 scope_type/stock_id/location_id/location_code/system_quantity 账面快照等明细表字段,不聚合、无 checked/diff 字段)" + "description": "明细结果行列表:商品范围按商品聚合(一个商品一行,多个库位明细行合并)——行含范围行字段(合并后行级 location_id/location_code 为 null)+ system_quantity(账面快照合计=各库位明细行 system_quantity 之和,创建明细时落库=盘点时做快照)+ 已盘聚合字段(checked_quantity 已盘数量=作业记录 quantity 合计,无记录为 null;diff_quantity 差异数量=已盘-账面快照合计,无记录为 null;is_diff 是否有差异 0|1;status 盘点状态 checked|unchecked;location_codes 库位编码数组去重;checkers 盘点人数组去重;last_checked_at 最近上报时间,无记录为 null)+ records(该商品全部盘点作业记录,每条含 id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/barcode/item_name/created_at/updated_at + images 图片列表 [{ id: file_id, url }],FileReference business_type=stock_check_record)+ locations(商品所在库位列表 [{ location_id, location_code, system_quantity, quantity }],system_quantity 为该库位账面快照(创建明细时落库)、quantity 为该库位实盘合计(未盘库位为 0),按明细 id 升序;仅作业记录存在而快照不存在的库位追加在末尾且 system_quantity=0)+ unknown_items(未知商品聚合数组 [{ barcode, item_name, checked_quantity }],按条码升序;记录 stock_id 为空的未知商品按条码归组,无账面、差异=实盘-0=盘盈,已计入行级 checked_quantity/diff_quantity/is_diff;无未知商品为空数组);库位行(scope_type=location)含范围行字段 + is_empty(是否空库位标记:该明细存在空标记记录(is_empty=1)时为 true)+ stocks(按商品聚合数组 [{ stock_id, item_code, item_name, system_quantity, checked_quantity, diff_quantity }],按 stock_id 升序,仅含存在作业记录的已知商品;system_quantity 为 wms_storage 账面(space_id+stock_id SUM(available_quantity)=可用数量),location_id 为空时按 0)+ checked_quantity(行级合计=行内商品实盘合计,无记录为 null)/ diff_quantity(行内各商品差异代数和,无记录为 null)/ is_diff / status + location_codes / checkers / last_checked_at + records / locations + unknown_items(口径同商品行);空库位标记(is_empty=true)时:stocks=[]、unknown_items=[]、checked_quantity=0、diff_quantity=0-库位账面库存总量(账面有库存时为负数=盘亏、账面为 0 时为 0)、is_diff=账面有库存时为 1、status=checked(视为已盘点);无作业记录(盘点前/待提交等)时 rows 直接返回 wms_stock_check_detail 明细范围行(原始行,含 scope_type/stock_id/location_id/location_code/system_quantity 账面快照等明细表字段,不聚合、无 checked/diff 字段)" }, { "name": "total", @@ -39121,19 +39121,19 @@ "notes": [ "权限口径:随 ALL_METHOD_NAMES(16 个)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(免鉴权清单)、必须登录(isNeedLogin=true,免登录清单为空);为查询类方法,加入免日志清单 _noNeedLog(list/detail/result/recordList/export/exportTaskProgress)。", "商品范围聚合口径:按商品合并(一个商品一行,多个库位明细行合并)——checked_quantity=该商品全部作业记录 quantity 合计;diff_quantity=已盘-账面快照合计(各库位明细行 system_quantity 之和,创建明细时落库=盘点时做快照);locations 各库位同时输出 system_quantity(该库位账面快照)与 quantity(该库位实盘合计,未盘库位为 0);is_diff=存在记录且差异非 0 时为 1;status=存在记录 checked,否则 unchecked。主表计数 check.total_items/checked_items/diff_items 按聚合行口径同步输出(total_items=行数、checked_items=已盘行数、diff_items=差异行数),历史任务主表残留的按库位拆行计数在响应中以聚合行为准。", - "库位行账面口径:wms_storage 按 (space_id, stock_id) SUM(available_quantity+locked_quantity)(=可用+锁定)现算(与 finish/export 汇总口径一致),location_id 为空时账面按 0;库位行 stocks 仅含存在作业记录的已知商品(stock_id 有值,无记录时为空数组),商品快照 item_code/item_name 从 wms_stock_warehouse 补齐。", + "库位行账面口径:wms_storage 按 (space_id, stock_id) SUM(available_quantity)(=可用数量,不含锁定待出库)现算(与 finish/export 汇总口径一致),location_id 为空时账面按 0;库位行 stocks 仅含存在作业记录的已知商品(stock_id 有值,无记录时为空数组),商品快照 item_code/item_name 从 wms_stock_warehouse 补齐。", "无作业记录口径(本次变更):rows 直接返回 wms_stock_check_detail 明细范围行(原始行,不聚合),total=明细行数——盘点前/待提交等后台查看盘点范围明细用(本接口仅展示盘点前/盘点后明细,不再作为盘点作业数据提供;盘点作业数据见 stock.check.workData)。代码依据:app/service/systems/stock_check.js#result(records.length===0 分支直接返回明细行)。", "未知商品聚合口径:stock_id 为空的作业记录按 barcode 维度归组输出行级 unknown_items [{ barcode, item_name, checked_quantity }](按条码升序,item_name 为上报名称快照);未知商品无账面,差异=实盘-0=盘盈,已计入行级 checked_quantity/diff_quantity/is_diff;stocks 保持只输出已知商品(stock_id 有值)。代码依据:app/service/systems/stock_check.js#_formatMergedGoodsAggregationRow(商品范围合并行)/#_formatDetailAggregationRow(库位行)。", "图片挂载口径(图片独立维护,仿收货 receivingItem):_attachRecordImages 查询 wms_file_reference(business_type=stock_check_record,business_id in 记录ID)并关联 wms_file 取 file_url,每条作业记录挂载 images [{ id: file_id, url }],无图片返回空数组;上传走通用上传接口(uploadSuccessNotify 传 businessType=stock_check_record + businessId=作业记录ID,建 FileReference)。代码依据:app/service/systems/stock_check.js#result/#_attachRecordImages。", "响应统一 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)。", - "空库位标记口径(本次新增):库位行存在空标记记录(is_empty=1)时 is_empty=true——stocks 为空数组、unknown_items 为空数组、checked_quantity=0、status=checked(视为已盘点);账面口径:按 location_id 查 wms_storage SUM(available_quantity+locked_quantity)(该库位全部库存账面总量=可用+锁定,location_id 为空时按 0),账面>0 时 diff_quantity=-账面总量(盘亏)、is_diff=1,账面=0 时 diff_quantity=0、is_diff=0。代码依据:app/service/systems/stock_check.js#_formatDetailAggregationRow。", + "空库位标记口径(本次新增):库位行存在空标记记录(is_empty=1)时 is_empty=true——stocks 为空数组、unknown_items 为空数组、checked_quantity=0、status=checked(视为已盘点);账面口径:按 location_id 查 wms_storage SUM(available_quantity)(该库位全部库存账面总量=可用数量,location_id 为空时按 0),账面>0 时 diff_quantity=-账面总量(盘亏)、is_diff=1,账面=0 时 diff_quantity=0、is_diff=0。代码依据:app/service/systems/stock_check.js#_formatDetailAggregationRow。", "文档变更范围: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 无损。" ] }, { "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(商品结构):按商品(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)的任务可拉取」。", + "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),无库存记录库位为 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 该商品在该库位的作业照片聚合(扁平去重,不再输出商品主图),供前端编辑/移除记录),明盘含库位账面(可用数量)/锁定数量/已盘数量、盲盘不含数量;静态盘点(is_static=1)时 goods 子项另含 picking_completed(1=该商品已完成拣货/0=未完成,口径=仓库内该商品 wms_storage SUM(locked_quantity) 是否为 0,按商品维度判定,同一商品各库位行取值一致,明盘盲盘均返回);盘点前库存已出空但已有盘点作业记录的库位也能展示(该库位商品行账面 system_quantity 按 0、locked_quantity 按 0、checked_quantity 按该库位实盘合计)。状态限制:仅任务状态为 approved(审核完成)或 checking(盘点作业中)时可拉取盘点作业数据,其他状态(created 已创建/submitted 待审核/rejected 已驳回/completed 已完成/cancelled 已取消)返回 400「当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取」。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -39216,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.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(该商品在该库位的实盘合计),盲盘不含数量;库位集合=当前库存库位 ∪ 作业记录库位(盘点前库存已出空但已有盘点作业记录的库位也能展示)" + "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);两者都会额外输出 storage_quantity(当前 storage 账面)与 snapshot_quantity(明细快照)供对照,system_quantity 始终为参与差异计算的账面,行/商品额外输出 is_static 与 book_source(snapshot|storage),locations 各项与行级均按此口径),静态盘点(is_static=1)goods 视图行额外输出 picking_completed(1=该商品已完成拣货/0=未完成,判定口径=wms_storage 中该商品在仓库内 SUM(locked_quantity) 是否为 0:锁定量>0 表示仍有已分配储位、尚未拣出的在途出库)与明盘下的 locked_quantity(该商品仓库内锁定量合计;盲盘不输出该数值,仅输出 picking_completed):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),无库存记录库位 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) 账面=可用数量,该库位无库存记录时按 0)/locked_quantity(该库位锁定数量,SUM(locked_quantity))/checked_quantity(该商品在该库位的实盘合计),盲盘不含数量;静态盘点(is_static=1)时 goods 子项另含 picking_completed(1=该商品已完成拣货/0=未完成,口径=仓库内该商品 wms_storage SUM(locked_quantity) 是否为 0,按商品维度判定,同一商品各库位行取值一致,明盘盲盘均返回);库位集合=当前库存库位 ∪ 作业记录库位(盘点前库存已出空但已有盘点作业记录的库位也能展示)" }, { "name": "total", @@ -39266,7 +39266,7 @@ "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 时该视图),按商品(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(避免未盘行误显盘亏差异)。", + "明盘/盲盘数量控制:明盘(mode=open)goods 视图行返回 system_quantity(该商品各库位明细行账面快照合计)/checked_quantity(已盘合计=locations.quantity 合计)/diff_quantity(已盘-账面,仅存在作业记录的行计算)/is_diff(差异非 0 为 1),locations 各项含 system_quantity(该库位账面数量=可用数量,wms_storage 该库位 SUM(available_quantity),无库存记录库位为 0)、locked_quantity(该库位锁定数量,wms_storage 该库位 SUM(locked_quantity))与 quantity(该库位盘点数量=实盘合计,未盘库位为 0);space 视图 goods 各项含 system_quantity(wms_storage space+stock SUM(available_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 条)。", @@ -39310,18 +39310,20 @@ "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(description/response.rows/notes 同步 goods 视图 locations 商品所在全部库位列表口径:未盘库位空信息、明盘每库位 quantity(未盘 0)、diff/is_diff 仅已有记录行计算);根版本 0.3.245 → 0.3.246、updatedAt 2026-10-04 → 2026-10-05;methods/changes/system.json 新增本条(插入数组首位);其余 22 条 method 未改动(stock.check 分组仍为 23 条)。", "goods 视图 locations 明盘库位数量区分(本次改造):明盘每库位同时输出 system_quantity(该库位账面数量,wms_storage 该库位 SUM(quantity),无库存记录库位为 0)与 quantity(该库位盘点数量=实盘合计,未盘库位为 0)两字段区分开;盲盘仍不返回任何数量字段。Storage 查询改为 attributes 增加 fn('SUM', col('quantity')) 按 stock+space 分组汇总,构建 stockId→spaceCode→账面数量映射;行级 checked_quantity 仍为 locations.quantity 合计,diff/is_diff 计算条件不变。代码依据:app/service/systems/stock_check.js#_buildGoodsWorkRows;回归测试 222/222 通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 与 stock.check.workDataDetail 两条(description/response.rows/notes 同步 goods 视图明盘库位 system_quantity(账面)+quantity(盘点)双数量字段口径);根版本 0.3.246 → 0.3.247、updatedAt 保持 2026-10-05;methods/changes/system.json 新增本条(插入数组首位);其余 21 条 method 未改动(stock.check 分组仍为 23 条)。", - "库位账面口径改造(本次):盘点作业数据接口的库位账面 system_quantity 由 SUM(quantity) 改为 SUM(available_quantity+locked_quantity)(=可用+锁定),并新增 locked_quantity(该库位锁定数量,SUM(locked_quantity))——goods 视图 locations 各项与 space 视图 goods 子项(workData/workDataDetail/workDataSpaceDetails 共用构建器);盲盘仍不返回任何数量字段。代码依据:app/service/systems/stock_check.js#_buildGoodsWorkRows/#_buildSpaceWorkRows;回归测试 222/222 通过、ESLint 0 错误。(后续已按用户要求全部统一:result/report/finish/detail 差异汇总与 addDetail 拆行快照均改为可用+锁定口径,见 0.3.249 变更记录)", - "文档变更范围: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 错误。", + "库位账面口径改造(本次):盘点作业数据接口的库位账面 system_quantity 由 SUM(quantity) 改为 SUM(available_quantity)(=可用数量,不含锁定待出库),并新增 locked_quantity(该库位锁定数量,SUM(locked_quantity))——goods 视图 locations 各项与 space 视图 goods 子项(workData/workDataDetail/workDataSpaceDetails 共用构建器);盲盘仍不返回任何数量字段。代码依据:app/service/systems/stock_check.js#_buildGoodsWorkRows/#_buildSpaceWorkRows;回归测试 222/222 通过、ESLint 0 错误。(后续已按用户要求全部统一:result/report/finish/detail 差异汇总与 addDetail 拆行快照均改为可用数量口径,见 0.3.249 变更记录)", + "文档变更范围: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)(=可用数量,不含锁定待出库)——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 条)。", "商品视图按商品汇总(本次,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。" + "账面取值按静态标记区分(本次,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。", + "静态盘点拣货完成标记(本次,0.3.320):goods 视图行在 is_static=1 时新增 picking_completed(1=已完成拣货/0=未完成)与明盘 locked_quantity(该商品仓库内 wms_storage SUM(locked_quantity)),判定口径为商品在仓库内是否仍有锁定量——分配储位只把 available_quantity 搬成 locked_quantity(quantity 不变),拣货完成时 quantity 与 locked_quantity 同时扣减、available_quantity 不变,因此 locked_quantity>0 即说明仍有已分配储位但未拣出的在途出库。盲盘(mode=blind)不输出 locked_quantity 数值、仅输出完成标记。代码依据:app/service/systems/stock_check.js#_buildGoodsWorkRows/#_fetchStockLockedQuantityMap。", + "space 视图拣货完成标记(本次,0.3.321):goods 子项在 is_static=1 时新增 picking_completed(1=已完成拣货/0=未完成),与 goods 视图行口径一致(按商品维度统计仓库内 SUM(locked_quantity)),盲盘同样返回。代码依据:app/service/systems/stock_check.js#_buildSpaceWorkRows。" ] }, { "method": "stock.check.workDataSpaceDetails", - "description": "拉取盘点作业数据(space 视图分页版):入参 id(盘点任务ID)+ location_id(库位ID,可选,兼容 locationId 驼峰写法)+ pagination({page,pageSize},缺省 page=1/pageSize=20,上限 200);warehouse_id 由服务端从当前上下文自动注入,前端无需传递。行结构与 workData space 视图行一致:id=库位ID(wms_location_space.id,另有同义字段 location_id)/ space_code 库位编码 / custom_barcode 自定义条码 / custom_name 库位名称 / goods 该库位下的任务商品子列表(detail_id 明细ID / stock_id 商品库存ID / item_code 商品编码 / item_name 商品名称 / spec 规格 / store_id 货主ID / store_name 货主名 / barcode 条码 / images 作业照片 / record_ids 作业记录ID列表;明盘 mode=open 另含 system_quantity 账面数量(wms_storage 该库位该商品 SUM(available_quantity+locked_quantity))、locked_quantity 锁定数量(wms_storage 该库位该商品 SUM(locked_quantity))与 checked_quantity 已盘合计;盲盘 mode=blind 不返回任何数量字段;status=checked 该 (detail_id, location_code) 存在作业记录 / unchecked 未盘)。库位仅按库位拣货顺序排序(pick_sequence 升序,pick_priority 与库位 id 不参与,同值保持库位查询顺序);传入 location_id 时只返回该库位行(total=1),不传时按分页返回全部库位行;返回 { view:'space', rows, total, page, pageSize }(不返回任务主表信息,任务信息请调用 stock.check.detail)。仅任务状态 approved(审核完成)或 checking(盘点作业中)可拉取(与 workData 同口径)。权限口径:免 API 权限校验,仅需登录(与 stock.check 分组其他方法一致)。", + "description": "拉取盘点作业数据(space 视图分页版):入参 id(盘点任务ID)+ location_id(库位ID,可选,兼容 locationId 驼峰写法)+ pagination({page,pageSize},缺省 page=1/pageSize=20,上限 200);warehouse_id 由服务端从当前上下文自动注入,前端无需传递。行结构与 workData space 视图行一致:id=库位ID(wms_location_space.id,另有同义字段 location_id)/ space_code 库位编码 / custom_barcode 自定义条码 / custom_name 库位名称 / goods 该库位下的任务商品子列表(detail_id 明细ID / stock_id 商品库存ID / item_code 商品编码 / item_name 商品名称 / spec 规格 / store_id 货主ID / store_name 货主名 / barcode 条码 / images 作业照片 / record_ids 作业记录ID列表;明盘 mode=open 另含 system_quantity 账面数量(wms_storage 该库位该商品 SUM(available_quantity))、locked_quantity 锁定数量(wms_storage 该库位该商品 SUM(locked_quantity))与 checked_quantity 已盘合计;盲盘 mode=blind 不返回任何数量字段;静态盘点(is_static=1)时 goods 子项另含 picking_completed(1=该商品已完成拣货/0=未完成,口径=仓库内该商品 wms_storage SUM(locked_quantity) 是否为 0,按商品维度判定,明盘盲盘均返回);status=checked 该 (detail_id, location_code) 存在作业记录 / unchecked 未盘)。库位仅按库位拣货顺序排序(pick_sequence 升序,pick_priority 与库位 id 不参与,同值保持库位查询顺序);传入 location_id 时只返回该库位行(total=1),不传时按分页返回全部库位行;返回 { view:'space', rows, total, page, pageSize }(不返回任务主表信息,任务信息请调用 stock.check.detail)。仅任务状态 approved(审核完成)或 checking(盘点作业中)可拉取(与 workData 同口径)。权限口径:免 API 权限校验,仅需登录(与 stock.check 分组其他方法一致)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -39396,11 +39398,14 @@ "code": "500", "message": "拉取盘点作业数据失败" } + ], + "notes": [ + "静态盘点拣货完成标记(本次,0.3.321):goods 子项在 is_static=1 时新增 picking_completed(1=已完成拣货/0=未完成),口径与 stock.check.workData goods/space 视图一致——按商品维度统计仓库内 wms_storage SUM(locked_quantity),>0 即仍有已分配储位但未拣出的在途出库。盲盘(mode=blind)同样返回该标记(不含任何数量字段)。与 stock.check.report 的静态盘点上报拦截(商品未完成拣货返回 400)配套使用。代码依据:app/service/systems/stock_check.js#_buildSpaceWorkRows(workDataSpaceDetails 复用同一 space 视图构建)。" ] }, { "method": "stock.check.workDataDetail", - "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 同口径)。", + "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 同口径)。静态盘点(is_static=1)商品钻取另在顶层返回 picking_completed(1=该商品已完成拣货/0=未完成,口径=仓库内该商品 wms_storage SUM(locked_quantity) 是否为 0)与明盘 locked_quantity(该商品仓库内锁定量合计)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -39457,7 +39462,7 @@ "name": "data", "type": "object", "required": true, - "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=实盘-参与计算的账面。", + "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);两者都会额外输出 storage_quantity(当前 storage 账面)与 snapshot_quantity(明细快照)供对照,system_quantity 始终为参与差异计算的账面,行/商品额外输出 is_static 与 book_source(snapshot|storage);明细行另含 storage_quantity(该库位当前 storage 账面),差异 diff_quantity=实盘-参与计算的账面。", "children": [ { "name": "detail_id", @@ -39561,15 +39566,16 @@ "状态限制口径:仅任务状态 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 错误。", + "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 = 该库位 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。" + "账面取值按静态标记区分(本次,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。", + "静态盘点拣货完成标记(本次,0.3.320):商品钻取(scope_type=goods)在 is_static=1 时顶层新增 picking_completed(1=已完成拣货/0=未完成)与明盘 locked_quantity(该商品仓库内锁定量合计),口径与 stock.check.workData goods 视图行一致。代码依据:app/service/systems/stock_check.js#_formatGoodsWorkDetail。" ] }, { "method": "stock.check.report", - "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);都未传沿用原报错口径。", + "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);都未传沿用原报错口径。静态盘点拣货完成校验:任务 is_static=1 且为商品范围明细(scope_type=goods)时,上报前校验该商品在仓库内的锁定量(wms_storage SUM(locked_quantity),is_enabled=1),大于 0 说明仍有已分配储位但尚未拣出的在途出库,直接拒绝上报并返回 400「商品尚未完成拣货,不满足静态盘点要求,请先等待该商品完全完成拣货」。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -39724,7 +39730,7 @@ "errors": [ { "code": 400, - "message": "盘点任务ID不能为空 / 盘点明细ID不能为空 / 盘点任务不存在 / 当前状态(非 approved/checking)不允许盘点作业 / 实盘数量必须为不小于0的整数 / 盘点明细不存在 / 盘点明细缺少商品信息 / 上报商品与盘点明细商品不一致 / 按库位盘点时必须指定商品 / 上报商品不属于本仓库 / 盘点明细缺少库位信息 / 上报库位与盘点明细库位不一致 / 仅库位盘点明细支持空库位标记" + "message": "盘点任务ID不能为空 / 盘点明细ID不能为空 / 盘点任务不存在 / 当前状态(非 approved/checking)不允许盘点作业 / 实盘数量必须为不小于0的整数 / 盘点明细不存在 / 盘点明细缺少商品信息 / 上报商品与盘点明细商品不一致 / 按库位盘点时必须指定商品 / 上报商品不属于本仓库 / 盘点明细缺少库位信息 / 上报库位与盘点明细库位不一致 / 仅库位盘点明细支持空库位标记 / 商品尚未完成拣货,不满足静态盘点要求,请先等待该商品完全完成拣货(静态盘点商品范围任务仍有锁定量时)" }, { "code": 500, @@ -39741,11 +39747,12 @@ "迁移依据:database/migrations/20261001100000-support-unknown-goods-in-stock-check-record.js(wms_stock_check_record:stock_id 改可空(NULL=未知商品)+ 新增 barcode VARCHAR(100)/item_name VARCHAR(255),本地与生产均已执行)。", "响应统一 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)。", "空库位标记上报口径(本次新增):is_empty 仅库位明细行(scope_type=location)支持,商品明细行传 is_empty 报 400『仅库位盘点明细支持空库位标记』;标记空时不要求商品/条码,quantity 恒为 0(跳过『实盘数量必须为不小于0的整数』校验),写一条特殊作业记录(stock_id=null、barcode=null、item_name=null、quantity=0、is_empty=1);覆盖式查重按(detail_id + is_empty=1 + location_code)应用层查重覆盖更新。互斥口径:标记空时删除该明细下所有商品记录(is_empty=false,含未知商品),上报商品时删除该明细下空标记记录(is_empty=true),两者不会并存。代码依据:app/service/systems/stock_check.js#report。", - "汇总口径(本次同步 _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。", + "汇总口径(本次同步 _recalcCheckSummary):空库位标记记录计入已盘明细(checked_items 按 DISTINCT detail_id 自然计入、detail_status 按已盘占比正常推进);差异口径:空标记明细的库位账面(wms_storage 按 space_id SUM(available_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 无损。", - "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 解析)。" + "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 解析)。", + "静态盘点拣货完成校验(本次,0.3.320):任务 is_static=1 且为商品范围明细(scope_type=goods)时,上报前校验该商品在仓库内的锁定量(wms_storage SUM(locked_quantity),is_enabled=1):大于 0 说明该商品仍有已分配储位但未拣出的在途出库,直接拒绝上报并返回 400「商品尚未完成拣货,不满足静态盘点要求,请先等待该商品完全完成拣货」;锁定量为 0(拣货已完成)才写作业记录。库位范围任务 is_static 恒为 0 不受影响;未知商品(stock_id 为空)无锁定量不受影响。代码依据:app/service/systems/stock_check.js#report(_fetchStockLockedQuantityMap 前置校验)。" ] }, { @@ -40328,7 +40335,7 @@ }, { "method": "stock.check.finish", - "description": "完成盘点作业(允许部分未盘完成):仅 approved/checking 状态允许;未盘商品明细=无作业记录(wms_stock_check_record)的明细,按实盘 0 处理(差异=-账面快照,计入盘亏与差异行数);未盘库位明细行因无法枚举商品不计差异;已盘商品明细按作业记录数量合计与账面快照(system_quantity)对比聚合;已盘库位明细按商品聚合实盘 vs wms_storage 账面(space_id+stock_id SUM(available_quantity+locked_quantity)=可用+锁定,space_id 为空时账面按 0)对比聚合;盘盈=正差异合计、盘亏=负差异绝对值合计;完成后主表置 completed、回填 end_time(完成盘点的时间)、detail_status=all_checked,返回差异汇总(盘盈/盘亏合计)与未盘明细数(unchecked_items)。", + "description": "完成盘点作业(允许部分未盘完成):仅 approved/checking 状态允许;未盘商品明细=无作业记录(wms_stock_check_record)的明细,按实盘 0 处理(差异=-账面快照,计入盘亏与差异行数);未盘库位明细行因无法枚举商品不计差异;已盘商品明细按作业记录数量合计与账面快照(system_quantity)对比聚合;已盘库位明细按商品聚合实盘 vs wms_storage 账面(space_id+stock_id SUM(available_quantity)=可用数量,space_id 为空时账面按 0)对比聚合;盘盈=正差异合计、盘亏=负差异绝对值合计;完成后主表置 completed、回填 end_time(完成盘点的时间)、detail_status=all_checked,返回差异汇总(盘盈/盘亏合计)与未盘明细数(unchecked_items)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -40413,7 +40420,7 @@ "name": "profit_total", "type": "number", "required": true, - "description": "盘盈合计(商品行:作业记录数量合计大于账面快照的差异合计;库位行:按商品实盘大于 wms_storage 账面(SUM(available_quantity+locked_quantity)=可用+锁定)的差异合计)" + "description": "盘盈合计(商品行:作业记录数量合计大于账面快照的差异合计;库位行:按商品实盘大于 wms_storage 账面(SUM(available_quantity)=可用数量)的差异合计)" }, { "name": "loss_total", @@ -40447,7 +40454,7 @@ } ], "notes": [ - "库位行账面口径:wms_storage 按 (space_id, stock_id) SUM(available_quantity+locked_quantity)(=可用+锁定),与 detail 接口的 stocks 账面一致。", + "库位行账面口径:wms_storage 按 (space_id, stock_id) SUM(available_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)。", @@ -40457,7 +40464,7 @@ }, { "method": "stock.check.submit", - "description": "完成盘点任务(提交审核):仅 created/rejected 状态允许;校验 total_items>0(无明细行时拒绝)后主表置 submitted(待审核);所有明细行(库位型 scope_type=location 与商品型 scope_type=goods)缺少库位(location_id 为空或 location_code 为空/空串)时不可提交(脏数据防御;商品任务按「商品+库位」拆行后商品行同样必须带库位,正常流程 addDetail/addLocationDetail 不会产生此类明细)。商品范围任务(scope_type=goods)提交时刷新明细行账面快照(提交即快照,快照失败则提交失败):按「商品+库位」把各明细行 system_quantity 刷新为该库位当时账面 SUM(available_quantity+locked_quantity)(库存记录不存在时按 0);明细表本身已按「商品+库位」完整记录快照,主表不额外写快照;库位范围任务(scope_type=location)账面实时查 wms_storage,不处理。", + "description": "完成盘点任务(提交审核):仅 created/rejected 状态允许;校验 total_items>0(无明细行时拒绝)后主表置 submitted(待审核);所有明细行(库位型 scope_type=location 与商品型 scope_type=goods)缺少库位(location_id 为空或 location_code 为空/空串)时不可提交(脏数据防御;商品任务按「商品+库位」拆行后商品行同样必须带库位,正常流程 addDetail/addLocationDetail 不会产生此类明细)。商品范围任务(scope_type=goods)提交时刷新明细行账面快照(提交即快照,快照失败则提交失败):按「商品+库位」把各明细行 system_quantity 刷新为该库位当时账面 SUM(available_quantity)(库存记录不存在时按 0);明细表本身已按「商品+库位」完整记录快照,主表不额外写快照;库位范围任务(scope_type=location)账面实时查 wms_storage,不处理。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -40534,7 +40541,7 @@ } ], "notes": [ - "提交时账面快照口径(本次新增):商品范围任务(scope_type=goods)提交审核时把各明细行 system_quantity 刷新为该库位当时账面 SUM(available_quantity+locked_quantity)(库存记录不存在按 0),保证 result/差异对比使用提交时点的账面(添加明细到提交之间库存变动以提交时点为准);明细表本身已按「商品+库位」完整记录快照,主表不额外写快照(scope_snapshot 保持 null);驳回(rejected)后重新提交会重新刷新;库位范围任务(scope_type=location)不处理(账面实时查 wms_storage)。代码依据:app/service/systems/stock_check.js#submit/#_refreshGoodsBookSnapshotOnSubmit。", + "提交时账面快照口径(本次新增):商品范围任务(scope_type=goods)提交审核时把各明细行 system_quantity 刷新为该库位当时账面 SUM(available_quantity)(库存记录不存在按 0),保证 result/差异对比使用提交时点的账面(添加明细到提交之间库存变动以提交时点为准);明细表本身已按「商品+库位」完整记录快照,主表不额外写快照(scope_snapshot 保持 null);驳回(rejected)后重新提交会重新刷新;库位范围任务(scope_type=location)不处理(账面实时查 wms_storage)。代码依据:app/service/systems/stock_check.js#submit/#_refreshGoodsBookSnapshotOnSubmit。", "响应统一 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)。", "提交校验口径(本次扩展):全部明细行(库位型 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→无明细行→缺库位明细)。", @@ -40725,7 +40732,7 @@ ], "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)。", - "审核刷新快照 + 解锁缓存(本次,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.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}` 再重建锁定缓存,使并发中的旧回源自动失效,避免脏读。" ] }, diff --git a/script/stock-check-goods-summary-verify.cjs b/script/stock-check-goods-summary-verify.cjs index e0e7634..ea2e6bb 100644 --- a/script/stock-check-goods-summary-verify.cjs +++ b/script/stock-check-goods-summary-verify.cjs @@ -53,7 +53,7 @@ function log(title, payload) { is_enabled: 1, space_id: { [Op.in]: literal(validSpaceSql) }, }, - attributes: [ 'stock_id', 'space_id', [ literal('SUM(available_quantity + locked_quantity)'), 'qty' ]], + attributes: [ 'stock_id', 'space_id', [ literal('SUM(available_quantity)'), 'qty' ]], group: [ 'stock_id', 'space_id' ], raw: true, }); diff --git a/test/app/service/systems/stock_check.test.js b/test/app/service/systems/stock_check.test.js index 0513805..0a943c7 100644 --- a/test/app/service/systems/stock_check.test.js +++ b/test/app/service/systems/stock_check.test.js @@ -223,9 +223,12 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 * 拉取固定测试仓库下的真实库存行(用于生成盘点明细快照)。 * * @param {number} count 行数。 + * @param {Object} [options] 过滤选项。 + * @param {boolean} [options.requireUnlocked=false] 仅取无锁定量商品 + * (wms_storage SUM(locked_quantity)=0,静态盘点上报要求商品已完成拣货)。 * @return {Promise>} 库存行。 */ - async function fetchStockRows(count = 2) { + async function fetchStockRows(count = 2, options = {}) { // 取「仅在单个启用库位有库存」的商品:商品明细按「商品 + 库位」拆行后每商品 1 行, // 保证 total_items 与商品数一致(多库位商品拆多行、无库存库位商品不可加入盘点) const { Op, fn, col, literal } = ctx.app.Sequelize; @@ -235,12 +238,17 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 is_enabled: 1, space_id: { [Op.in]: literal(VALID_SPACE_SQL) }, }, - attributes: [ 'stock_id', [ fn('COUNT', fn('DISTINCT', col('space_id'))), 'spaceCount' ]], + attributes: [ + 'stock_id', + [ fn('COUNT', fn('DISTINCT', col('space_id'))), 'spaceCount' ], + [ literal('SUM(locked_quantity)'), 'lockedQuantity' ], + ], group: [ 'stock_id' ], raw: true, }); const singleSpaceStockIds = storageRows .filter(row => Number(row.spaceCount) === 1) + .filter(row => options.requireUnlocked !== true || (Number(row.lockedQuantity) || 0) === 0) .map(row => Number(row.stock_id)); return ctx.model.StockWarehouse.findAll({ @@ -287,7 +295,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 } /** - * 查询库位商品账面数量(wms_storage 按 stock_id SUM(可用+锁定),与实现口径一致)。 + * 查询库位商品账面数量(wms_storage 按 stock_id SUM(可用数量),与实现口径一致)。 * * @param {number} spaceId 库位ID。 * @param {Array} stockIds 商品库存ID列表。 @@ -300,7 +308,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 space_id: Number(spaceId), stock_id: { [Op.in]: stockIds.map(id => Number(id)) }, }, - attributes: [ 'stock_id', [ literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ]], + attributes: [ 'stock_id', [ literal('SUM(available_quantity)'), 'totalQuantity' ]], group: [ 'stock_id' ], raw: true, }); @@ -329,7 +337,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 /** * 取固定测试仓库下「只存放在单一库位」的有效商品与库位对(保证库位-商品一一对应, * 供 space 视图聚合/排序用例使用),并附库位编码/名称与账面数量(账面口径与实现一致: - * wms_storage 按 warehouse+space+stock+is_enabled=1 SUM(available_quantity+locked_quantity)) + * wms_storage 按 warehouse+space+stock+is_enabled=1 SUM(available_quantity)) * 及锁定数量(SUM(locked_quantity))。 * * @param {number} count 对数。 @@ -396,7 +404,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 is_enabled: 1, }, attributes: [ - [ ctx.app.Sequelize.literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ], + [ ctx.app.Sequelize.literal('SUM(available_quantity)'), 'totalQuantity' ], [ fn('SUM', col('locked_quantity')), 'totalLockedQuantity' ], ], raw: true, @@ -1310,7 +1318,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 assert.equal(row.item_code, stock.item_code, 'item_code 快照不一致'); assert.equal(row.item_name, stock.item_name, 'item_name 快照不一致'); assert.equal(row.spec, stock.sku_property, 'spec 应快照 sku_property'); - // 拆行口径:system_quantity = 该商品在其库存库位的账面(wms_storage SUM(可用+锁定)) + // 拆行口径:system_quantity = 该商品在其库存库位的账面(wms_storage SUM(可用数量)) const storageRows = await ctx.model.Storage.findAll({ where: { warehouse_id: TEST_WAREHOUSE_ID, @@ -1321,7 +1329,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 raw: true, }); const expectedSystemQuantity = storageRows.reduce( - (sum, item) => sum + (Number(item.available_quantity) || 0) + (Number(item.locked_quantity) || 0), + (sum, item) => sum + (Number(item.available_quantity) || 0), 0 ); assert.equal(Number(row.system_quantity), expectedSystemQuantity, 'system_quantity 应为该库位账面'); @@ -1380,7 +1388,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 is_enabled: 1, space_id: { [Op.in]: literal(VALID_SPACE_SQL) }, }, - attributes: [ 'stock_id', 'space_id', [ literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ]], + attributes: [ 'stock_id', 'space_id', [ literal('SUM(available_quantity)'), 'totalQuantity' ]], group: [ 'stock_id', 'space_id' ], raw: true, }); @@ -2356,7 +2364,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 const stockId = Number(detail.stock_id); const spaceId = Number(detail.location_id); - // 提交前账面(口径与实现一致:SUM 可用+锁定) + // 提交前账面(口径与实现一致:SUM 可用数量) const bookRows = await ctx.model.Storage.findAll({ where: { warehouse_id: TEST_WAREHOUSE_ID, @@ -2365,7 +2373,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 is_enabled: 1, }, attributes: [ - [ literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ], + [ literal('SUM(available_quantity)'), 'totalQuantity' ], ], raw: true, }); @@ -4109,7 +4117,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 is_enabled: 1, space_id: { [Op.in]: literal(VALID_SPACE_SQL) }, }, - attributes: [ 'stock_id', 'space_id', [ literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ]], + attributes: [ 'stock_id', 'space_id', [ literal('SUM(available_quantity)'), 'totalQuantity' ]], group: [ 'stock_id', 'space_id' ], raw: true, }); @@ -5340,7 +5348,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 is_enabled: 1, space_id: { [Op.in]: literal(VALID_SPACE_SQL) }, }, - attributes: [ 'stock_id', 'space_id', [ literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ]], + attributes: [ 'stock_id', 'space_id', [ literal('SUM(available_quantity)'), 'totalQuantity' ]], group: [ 'stock_id', 'space_id' ], raw: true, }); @@ -5479,7 +5487,8 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 }); it('账面取值按任务静态标记:静态任务取明细快照、非静态任务取当前 storage(goods/space/workDataDetail 一致)', async () => { - const stocks = await fetchStockRows(1); + // 静态任务上报要求商品已完成拣货(无锁定量),故只取无锁定商品 + const stocks = await fetchStockRows(1, { requireUnlocked: true }); const targetStock = stocks[0]; const DELTA = 7; @@ -5511,7 +5520,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 { 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 + `SELECT COALESCE(SUM(available_quantity), 0) AS total FROM wms_storage WHERE warehouse_id = :warehouseId AND stock_id = :stockId AND space_id = :spaceId`, { @@ -5538,10 +5547,12 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 } const spaceIdList = []; + const checkIdList = []; try { // ── 静态任务:账面=快照(冻结),当前 storage 仅作为参考字段输出 ── const staticPrepared = await prepareCheck(true); spaceIdList.push(staticPrepared.spaceId); + checkIdList.push(staticPrepared.check.id); assert.ok(staticPrepared.liveBook > staticPrepared.snapshot, '前置:人为变动后当前账面应大于快照'); const staticGoods = await workDataCheck(staticPrepared.check.id, { isGoods: true }); @@ -5589,6 +5600,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 // ── 非静态任务:账面=当前 storage,快照仅作参考字段 ── const normalPrepared = await prepareCheck(false); spaceIdList.push(normalPrepared.spaceId); + checkIdList.push(normalPrepared.check.id); const normalGoods = await workDataCheck(normalPrepared.check.id, { isGoods: true }); const normalRow = normalGoods.rows[0]; @@ -5621,6 +5633,139 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 for (const spaceId of spaceIdList) { await restoreBook(spaceId); } + // 收尾:完成盘点释放静态锁定,避免留存的 checking 静态任务影响后续锁定相关用例 + for (const checkId of checkIdList) { + const latestRow = await findCheckRow(checkId); + if (latestRow && [ 'approved', 'checking' ].includes(String(latestRow.status))) { + await ctx.service.systems.stockCheck.finish({ warehouseId: TEST_WAREHOUSE_ID, id: checkId }); + } + } + } + }); + + it('静态盘点拣货完成标记:商品仍有锁定量时 picking_completed=0 且 report 拒绝上报', async () => { + const stocks = await fetchStockRows(1, { requireUnlocked: true }); + const targetStock = stocks[0]; + const LOCK_DELTA = 2; + + // 前置:测试商品在测试仓库不应有锁定量(否则 picking_completed 初值即为 0,用例无法区分) + const lockedBefore = await ctx.model.query( + `SELECT COALESCE(SUM(locked_quantity), 0) AS total + FROM wms_storage + WHERE warehouse_id = :warehouseId AND stock_id = :stockId`, + { + replacements: { warehouseId: TEST_WAREHOUSE_ID, stockId: targetStock.id }, + type: ctx.model.QueryTypes.SELECT, + } + ); + assert.equal( + Number(lockedBefore[0] && lockedBefore[0].total) || 0, + 0, + '前置:测试商品在测试仓库不应有锁定量' + ); + + const check = await createCheck({ + title: uniqueTitle('静态拣货完成'), + type: 'goods', + isStatic: 1, + }); + 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); + + // 模拟分配储位:available → locked(quantity 不变),即该商品仍有在途待拣出库 + const shiftLock = async delta => { + await ctx.model.query( + `UPDATE wms_storage + SET available_quantity = available_quantity - :delta, + locked_quantity = locked_quantity + :delta + WHERE warehouse_id = :warehouseId AND stock_id = :stockId AND space_id = :spaceId`, + { replacements: { delta, warehouseId: TEST_WAREHOUSE_ID, stockId: targetStock.id, spaceId } } + ); + }; + + try { + await shiftLock(LOCK_DELTA); + + // goods 视图:picking_completed=0,并输出该商品仓库内锁定量合计 + const lockedGoods = await workDataCheck(check.id, { isGoods: true }); + const lockedRow = lockedGoods.rows[0]; + assert.equal(Number(lockedRow.is_static), 1); + assert.equal(Number(lockedRow.picking_completed), 0, '商品仍有锁定量时 picking_completed 应为 0'); + assert.equal(Number(lockedRow.locked_quantity), LOCK_DELTA, '行级应输出该商品锁定量合计'); + + // workDataDetail 同口径 + const lockedDrill = await workDataDetailCheck({ id: check.id, stockId: targetStock.id }); + assert.equal(Number(lockedDrill.picking_completed), 0, '钻取 picking_completed 应为 0'); + assert.equal(Number(lockedDrill.locked_quantity), LOCK_DELTA, '钻取应输出该商品锁定量合计'); + + // space 视图(workData 默认视图)goods 子项同口径 + const lockedSpace = await workDataCheck(check.id); + const lockedSpaceItem = lockedSpace.rows + .flatMap(row => row.goods || []) + .find(item => Number(item.stock_id) === Number(targetStock.id)); + assert.ok(lockedSpaceItem, 'space 视图应含该商品'); + assert.equal(Number(lockedSpaceItem.picking_completed), 0, 'space 视图 picking_completed 应为 0'); + + // workDataSpaceDetails(space 视图分页版)同口径 + const lockedSpaceDetails = await ctx.service.systems.stockCheck.workDataSpaceDetails({ + warehouseId: TEST_WAREHOUSE_ID, + id: check.id, + locationId: spaceId, + }); + const lockedSpaceDetailItem = (lockedSpaceDetails.rows[0] && lockedSpaceDetails.rows[0].goods || []) + .find(item => Number(item.stock_id) === Number(targetStock.id)); + assert.ok(lockedSpaceDetailItem, 'workDataSpaceDetails 库位行应含该商品'); + assert.equal( + Number(lockedSpaceDetailItem.picking_completed), + 0, + 'workDataSpaceDetails picking_completed 应为 0' + ); + + // 未完成拣货:report 拒绝上报 + await assert.rejects( + async () => reportCheck(check.id, detailRow.id, 1, detailRow.location_code), + /商品尚未完成拣货,不满足静态盘点要求,请先等待该商品完全完成拣货/ + ); + + // 拣货完成(锁定量清零)后 picking_completed=1,可正常上报 + await shiftLock(-LOCK_DELTA); + const doneGoods = await workDataCheck(check.id, { isGoods: true }); + assert.equal(Number(doneGoods.rows[0].picking_completed), 1, '无锁定量时 picking_completed 应为 1'); + assert.equal(Number(doneGoods.rows[0].locked_quantity), 0, '无锁定量时行级锁定量应为 0'); + const doneSpaceDetails = await ctx.service.systems.stockCheck.workDataSpaceDetails({ + warehouseId: TEST_WAREHOUSE_ID, + id: check.id, + locationId: spaceId, + }); + const doneSpaceDetailItem = (doneSpaceDetails.rows[0] && doneSpaceDetails.rows[0].goods || []) + .find(item => Number(item.stock_id) === Number(targetStock.id)); + assert.equal( + Number(doneSpaceDetailItem && doneSpaceDetailItem.picking_completed), + 1, + '拣货完成后 workDataSpaceDetails 的 picking_completed 应为 1' + ); + const reported = await reportCheck(check.id, detailRow.id, 1, detailRow.location_code); + assert.equal(Number(reported.record.quantity), 1, '拣货完成后应允许上报'); + } finally { + // 收尾:完成盘点释放静态锁定,避免留存的 checking 静态任务影响后续锁定相关用例 + const latestRow = await findCheckRow(check.id); + if (latestRow && [ 'approved', 'checking' ].includes(String(latestRow.status))) { + await ctx.service.systems.stockCheck.finish({ warehouseId: TEST_WAREHOUSE_ID, id: check.id }); + } + // 兜底回滚:无论用例是否中途失败,都把锁定量搬回可用数量 + await ctx.model.query( + `UPDATE wms_storage + SET available_quantity = available_quantity + locked_quantity, + locked_quantity = 0 + WHERE warehouse_id = :warehouseId AND stock_id = :stockId AND space_id = :spaceId + AND locked_quantity > 0`, + { replacements: { warehouseId: TEST_WAREHOUSE_ID, stockId: targetStock.id, spaceId } } + ); } }); @@ -5630,7 +5775,6 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 await addDetail(check.id, [ stocks[0].id ]); await submitCheck(check.id); await auditCheck(check.id, 'approve'); - const details = await detailCheck(check.id); await reportCheck(check.id, details.rows[0].id, 5, TEST_LOCATION_CODE); await reportCheck(check.id, details.rows[0].id, 3, TEST_LOCATION_CODE_2); @@ -5744,7 +5888,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 const reportedGoods = reportedRow.goods[0]; assert.equal(Number(reportedGoods.detail_id), Number(reportedDetail.id)); assert.equal(Number(reportedGoods.stock_id), reported.stockId); - assert.equal(Number(reportedGoods.system_quantity), reported.book, '库位账面应为 wms_storage SUM(可用+锁定)'); + assert.equal(Number(reportedGoods.system_quantity), reported.book, '库位账面应为 wms_storage SUM(可用数量)'); assert.equal(Number(reportedGoods.locked_quantity), reported.bookLocked, '库位锁定数量应为 wms_storage SUM(locked_quantity)'); assert.equal(Number(reportedGoods.checked_quantity), reportedQuantity, '已盘应为该库位实盘合计'); assert.equal(reportedGoods.status, 'checked'); @@ -6012,7 +6156,7 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 assert.equal(row.custom_name, target.customName || null); assert.equal(row.goods.length, 1, '该库位仅一个任务商品'); assert.equal(Number(row.goods[0].stock_id), target.stockId, 'goods 应挂载该库位的任务商品'); - assert.equal(Number(row.goods[0].system_quantity), target.book, '明盘库位账面应为 wms_storage SUM(可用+锁定)'); + assert.equal(Number(row.goods[0].system_quantity), target.book, '明盘库位账面应为 wms_storage SUM(可用数量)'); assert.equal(Number(row.goods[0].locked_quantity), target.bookLocked, '明盘库位锁定数量应为 wms_storage SUM(locked_quantity)'); assert.equal(Number(row.goods[0].checked_quantity), 0, '未盘库位已盘应为 0'); assert.equal(row.goods[0].status, 'unchecked'); @@ -8979,13 +9123,13 @@ runner('test/app/service/systems/stock_check.test.js(库存盘点真实库集 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 + `SELECT COALESCE(SUM(available_quantity), 0) AS total FROM wms_storage WHERE warehouse_id = :warehouseId AND stock_id = :stockId AND space_id = :spaceId`, {