diff --git a/app/service/systems/stock_check.js b/app/service/systems/stock_check.js index d81d70d..3ceeafc 100644 --- a/app/service/systems/stock_check.js +++ b/app/service/systems/stock_check.js @@ -4234,6 +4234,105 @@ class StockCheckService extends Service { }; } + /** + * 提交审核时固化商品范围账面快照(盘点基准)。 + * 商品范围(scope_type=goods)任务在提交审核时记录当时账面: + * 1) 按「商品 + 库位」刷新各明细行 system_quantity = 该库位当前账面 SUM(可用+锁定) + * (库存记录不存在时按 0),保证 result/差异对比使用提交时点的账面; + * 2) 主表 scope_snapshot 写入商品级汇总快照(总数=可用+锁定 与锁定总数),便于追溯: + * { snapshot_at, stocks: [{ stock_id, item_code, item_name, system_quantity, locked_quantity }] }。 + * 库位范围(scope_type=location)账面实时查 wms_storage,不写快照。 + * + * @param {number} checkId 盘点任务ID。 + * @param {number} warehouseId 仓库ID。 + * @return {Promise} 无返回值。 + */ + async _snapshotGoodsBookOnSubmit(checkId, warehouseId) { + const { ctx } = this; + const { Op, fn, col, literal } = ctx.app.Sequelize; + + const checkIdNumber = Number(checkId); + const detailRows = await ctx.model.StockCheckDetail.findAll({ + where: { check_id: checkIdNumber, scope_type: 'goods' }, + raw: true, + }); + if (detailRows.length === 0) { + return; + } + + const stockIds = [ ...new Set(detailRows + .map(row => Number(row.stock_id)) + .filter(stockId => Number.isInteger(stockId) && stockId > 0)) ]; + + // 按 (stock_id, space_id) 聚合当前账面:SUM(可用+锁定) 与 SUM(锁定) + const storageQuantityMap = new Map(); + if (stockIds.length > 0) { + const storageRows = await ctx.model.Storage.findAll({ + where: { + warehouse_id: Number(warehouseId), + stock_id: { [Op.in]: stockIds }, + is_enabled: 1, + }, + attributes: [ + 'stock_id', + 'space_id', + [ literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ], + [ fn('SUM', col('locked_quantity')), 'lockedQuantity' ], + ], + group: [ 'stock_id', 'space_id' ], + raw: true, + }); + for (const storageRow of storageRows) { + storageQuantityMap.set( + `${Number(storageRow.stock_id)}_${Number(storageRow.space_id)}`, + { + total: Number(storageRow.totalQuantity) || 0, + locked: Number(storageRow.lockedQuantity) || 0, + } + ); + } + } + + // 逐明细行刷新库位级账面快照(提交时账面,库存记录不存在时按 0) + for (const detailRow of detailRows) { + const current = storageQuantityMap.get( + `${Number(detailRow.stock_id)}_${Number(detailRow.location_id)}` + ) || { total: 0, locked: 0 }; + await ctx.model.StockCheckDetail.update( + { system_quantity: current.total }, + { where: { id: detailRow.id } } + ); + } + + // 商品级汇总快照(总数=可用+锁定、锁定总数) + const stocksAgg = new Map(); + for (const detailRow of detailRows) { + const stockId = Number(detailRow.stock_id); + const current = storageQuantityMap.get(`${stockId}_${Number(detailRow.location_id)}`) + || { total: 0, locked: 0 }; + const agg = stocksAgg.get(stockId) || { + stock_id: stockId, + item_code: detailRow.item_code || null, + item_name: detailRow.item_name || null, + system_quantity: 0, + locked_quantity: 0, + }; + agg.system_quantity += current.total; + agg.locked_quantity += current.locked; + stocksAgg.set(stockId, agg); + } + + await ctx.model.StockCheck.update( + { + scope_snapshot: { + snapshot_at: new Date(), + stocks: [ ...stocksAgg.values() ], + }, + }, + { where: { id: checkIdNumber } } + ); + } + /** * 完成盘点任务(提交审核)。 * 仅 created/rejected 状态允许;校验 total_items>0 后置为 submitted; @@ -4282,6 +4381,10 @@ class StockCheckService extends Service { throw this.createBusinessError('存在缺少库位的盘点明细,无法提交审核'); } + // 提交审核时固化商品范围账面快照(盘点基准:明细行库位级快照 + 主表商品级总数/锁定快照, + // 快照失败则提交失败,保证「提交即快照」) + await this._snapshotGoodsBookOnSubmit(checkId, Number(warehouseId)); + await check.update({ status: 'submitted' }); // 写入操作日志(失败不影响主流程) diff --git a/methods/changes/system.json b/methods/changes/system.json index 29ee22c..b9c7aab 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,19 @@ [ + { + "version": "0.3.260", + "date": "2026-10-10", + "type": "updated", + "summary": "stock.check.submit 商品范围任务提交审核时固化账面快照(提交即快照):明细行库位级快照刷新 + 主表 scope_snapshot 记录商品总数/锁定总数(0.3.259 → 0.3.260)", + "methods": [ + "stock.check.submit" + ], + "notes": [ + "变更内容:商品范围任务(scope_type=goods)提交审核时记录当时账面——①逐明细行刷新 system_quantity=该库位当时账面 SUM(available_quantity+locked_quantity)(库存记录不存在按 0),保证 result/差异对比使用提交时点的账面(添加明细到提交之间库存变动以提交时点为准,与 result 商品范围聚合的库位账面快照同源);②主表已有 scope_snapshot(JSON 列,此前闲置)写入商品级汇总快照 { snapshot_at, stocks: [{ stock_id, item_code, item_name, system_quantity, locked_quantity }] }(system_quantity=商品总数=可用+锁定合计、locked_quantity=锁定总数,口径与 workData goods 视图 locked_quantity 一致);快照失败则提交失败(提交即快照);驳回后重新提交会重新快照(覆盖);库位范围任务(scope_type=location)账面实时查 wms_storage,不写快照。", + "存储方案:无需新表——明细表已有 system_quantity 快照列(按「商品+库位」拆行),主表已有 scope_snapshot JSON 列,直接复用(无迁移)。", + "代码依据:app/service/systems/stock_check.js#submit(缺库位校验后、置 submitted 前调用)/#_snapshotGoodsBookOnSubmit(新增);回归测试新增两用例(商品任务提交后明细行快照刷新 + 主表 scope_snapshot 总数/锁定断言,库存临时 +100 后 finally 恢复;库位范围任务提交 scope_snapshot 保持 null),stock_check 全量 231 用例通过、ESLint 0 错误。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.submit 一条(description/notes 补提交时账面快照语义);根版本 0.3.259 → 0.3.260、updatedAt 保持 2026-10-10;methods/changes/system.json 新增本条(插入数组首位);其余 23 条 method 未改动(stock.check 分组仍为 24 条)。" + ] + }, { "version": "0.3.259", "date": "2026-10-10", diff --git a/methods/system.json b/methods/system.json index 20745ec..9821a5b 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,7 +1,7 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.259", + "version": "0.3.260", "updatedAt": "2026-10-10", "headers": [ { @@ -39942,7 +39942,7 @@ }, { "method": "stock.check.submit", - "description": "完成盘点任务(提交审核):仅 created/rejected 状态允许;校验 total_items>0(无明细行时拒绝)后主表置 submitted(待审核);所有明细行(库位型 scope_type=location 与商品型 scope_type=goods)缺少库位(location_id 为空或 location_code 为空/空串)时不可提交(脏数据防御;商品任务按「商品+库位」拆行后商品行同样必须带库位,正常流程 addDetail/addLocationDetail 不会产生此类明细)。", + "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_snapshot 写入商品级汇总快照 { snapshot_at, stocks: [{ stock_id, item_code, item_name, system_quantity, locked_quantity }] }(system_quantity=商品总数=可用+锁定合计、locked_quantity=锁定总数);库位范围任务(scope_type=location)账面实时查 wms_storage,不写快照。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -40019,6 +40019,7 @@ } ], "notes": [ + "提交时账面快照口径(本次新增):商品范围任务(scope_type=goods)提交审核时固化账面——①逐明细行刷新 system_quantity=该库位当时账面 SUM(available_quantity+locked_quantity)(库存记录不存在按 0),保证 result/差异对比使用提交时点的账面(添加明细到提交之间库存变动以提交时点为准);②主表 scope_snapshot 写入商品级汇总快照 { snapshot_at, stocks: [{ stock_id, item_code, item_name, system_quantity, locked_quantity }] }(system_quantity=商品总数=可用+锁定合计、locked_quantity=锁定总数,快照口径与 workData goods 视图 locked_quantity 一致);驳回(rejected)后重新提交会重新快照(覆盖);库位范围任务(scope_type=location)不写快照(账面实时查 wms_storage)。代码依据:app/service/systems/stock_check.js#submit/#_snapshotGoodsBookOnSubmit。", "响应统一 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→无明细行→缺库位明细)。",