feat(stock.check): submit 提交审核时固化商品范围账面快照(明细行库位级 + 主表 scope_snapshot 总数/锁定,0.3.260)
This commit is contained in:
parent
ae107e5cbe
commit
3401645419
@ -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<void>} 无返回值。
|
||||
*/
|
||||
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' });
|
||||
|
||||
// 写入操作日志(失败不影响主流程)
|
||||
|
||||
@ -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",
|
||||
|
||||
@ -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→无明细行→缺库位明细)。",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user