From 1402aa38418b3281058270a83f7f947645615395 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Sat, 10 Oct 2026 03:22:40 +0800 Subject: [PATCH] =?UTF-8?q?refactor(stock.check):=20submit=20=E4=BB=85?= =?UTF-8?q?=E5=88=B7=E6=96=B0=E6=98=8E=E7=BB=86=E8=A1=8C=E8=B4=A6=E9=9D=A2?= =?UTF-8?q?=E5=BF=AB=E7=85=A7=EF=BC=8C=E4=B8=8D=E5=86=99=E4=B8=BB=E8=A1=A8?= =?UTF-8?q?=20scope=5Fsnapshot=EF=BC=88=E6=98=8E=E7=BB=86=E8=A1=A8?= =?UTF-8?q?=E5=B7=B2=E5=AE=8C=E6=95=B4=E8=AE=B0=E5=BD=95=EF=BC=8C0.3.260?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- app/service/systems/stock_check.js | 62 +++++++----------------------- methods/changes/system.json | 10 ++--- methods/system.json | 4 +- 3 files changed, 21 insertions(+), 55 deletions(-) diff --git a/app/service/systems/stock_check.js b/app/service/systems/stock_check.js index 3ceeafc..53603e8 100644 --- a/app/service/systems/stock_check.js +++ b/app/service/systems/stock_check.js @@ -4235,21 +4235,19 @@ 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,不写快照。 + * 提交审核时刷新商品范围明细行的账面快照(盘点基准)。 + * 商品范围(scope_type=goods)任务在提交审核时把各明细行 system_quantity 刷新为 + * 该库位当时的账面 SUM(available_quantity+locked_quantity)(库存记录不存在时按 0), + * 保证 result/差异对比使用提交时点的账面;明细表本身已按「商品 + 库位」完整记录快照, + * 不额外写主表快照。库位范围(scope_type=location)账面实时查 wms_storage,不处理。 * * @param {number} checkId 盘点任务ID。 * @param {number} warehouseId 仓库ID。 * @return {Promise} 无返回值。 */ - async _snapshotGoodsBookOnSubmit(checkId, warehouseId) { + async _refreshGoodsBookSnapshotOnSubmit(checkId, warehouseId) { const { ctx } = this; - const { Op, fn, col, literal } = ctx.app.Sequelize; + const { Op, literal } = ctx.app.Sequelize; const checkIdNumber = Number(checkId); const detailRows = await ctx.model.StockCheckDetail.findAll({ @@ -4264,7 +4262,7 @@ class StockCheckService extends Service { .map(row => Number(row.stock_id)) .filter(stockId => Number.isInteger(stockId) && stockId > 0)) ]; - // 按 (stock_id, space_id) 聚合当前账面:SUM(可用+锁定) 与 SUM(锁定) + // 按 (stock_id, space_id) 聚合当前账面:SUM(可用+锁定) const storageQuantityMap = new Map(); if (stockIds.length > 0) { const storageRows = await ctx.model.Storage.findAll({ @@ -4277,7 +4275,6 @@ class StockCheckService extends Service { 'stock_id', 'space_id', [ literal('SUM(available_quantity + locked_quantity)'), 'totalQuantity' ], - [ fn('SUM', col('locked_quantity')), 'lockedQuantity' ], ], group: [ 'stock_id', 'space_id' ], raw: true, @@ -4285,52 +4282,21 @@ class StockCheckService extends Service { 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, - } + Number(storageRow.totalQuantity) || 0 ); } } // 逐明细行刷新库位级账面快照(提交时账面,库存记录不存在时按 0) for (const detailRow of detailRows) { - const current = storageQuantityMap.get( + const systemQuantity = storageQuantityMap.get( `${Number(detailRow.stock_id)}_${Number(detailRow.location_id)}` - ) || { total: 0, locked: 0 }; + ) || 0; await ctx.model.StockCheckDetail.update( - { system_quantity: current.total }, + { system_quantity: systemQuantity }, { 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 } } - ); } /** @@ -4381,9 +4347,9 @@ class StockCheckService extends Service { throw this.createBusinessError('存在缺少库位的盘点明细,无法提交审核'); } - // 提交审核时固化商品范围账面快照(盘点基准:明细行库位级快照 + 主表商品级总数/锁定快照, + // 提交审核时刷新商品范围明细行账面快照(提交时点账面=盘点基准, // 快照失败则提交失败,保证「提交即快照」) - await this._snapshotGoodsBookOnSubmit(checkId, Number(warehouseId)); + await this._refreshGoodsBookSnapshotOnSubmit(checkId, Number(warehouseId)); await check.update({ status: 'submitted' }); diff --git a/methods/changes/system.json b/methods/changes/system.json index b9c7aab..37ef7ea 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -3,15 +3,15 @@ "version": "0.3.260", "date": "2026-10-10", "type": "updated", - "summary": "stock.check.submit 商品范围任务提交审核时固化账面快照(提交即快照):明细行库位级快照刷新 + 主表 scope_snapshot 记录商品总数/锁定总数(0.3.259 → 0.3.260)", + "summary": "stock.check.submit 商品范围任务提交审核时刷新明细行账面快照(提交即快照,提交时点账面;不新增表、主表不额外写快照)(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 条)。" + "变更内容:商品范围任务(scope_type=goods)提交审核时把各明细行 system_quantity 刷新为该库位当时账面 SUM(available_quantity+locked_quantity)(库存记录不存在按 0),保证 result/差异对比使用提交时点的账面(添加明细到提交之间库存变动以提交时点为准,与 result 商品范围聚合的库位账面快照同源);明细表本身已按「商品+库位」完整记录快照,主表不额外写快照(scope_snapshot 保持 null);快照失败则提交失败(提交即快照);驳回(rejected)后重新提交会重新刷新;库位范围任务(scope_type=location)账面实时查 wms_storage,不处理。", + "存储方案:无需新表、无迁移——明细表已有 system_quantity 快照列(按「商品+库位」拆行),提交时直接刷新即可。", + "代码依据:app/service/systems/stock_check.js#submit(缺库位校验后、置 submitted 前调用)/#_refreshGoodsBookSnapshotOnSubmit(新增);回归测试两用例(商品任务提交后明细行快照刷新为提交时账面、主表 scope_snapshot 保持 null,库存临时 +100 后 finally 恢复;库位范围任务提交明细行 system_quantity 保持 0),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 条)。" ] }, { diff --git a/methods/system.json b/methods/system.json index 9821a5b..e9e50c1 100644 --- a/methods/system.json +++ b/methods/system.json @@ -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 不会产生此类明细)。商品范围任务(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,不写快照。", + "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,不处理。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -40019,7 +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。", + "提交时账面快照口径(本次新增):商品范围任务(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。", "响应统一 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→无明细行→缺库位明细)。",