fix(stock.check): result 无作业记录时返回明细范围行(盘点前/待提交后台查看明细,0.3.262)

This commit is contained in:
liufumingren 2026-10-10 04:36:03 +08:00
parent d4daa6d671
commit 879bfaccbe
3 changed files with 36 additions and 7 deletions

View File

@ -1698,8 +1698,10 @@ class StockCheckService extends Service {
}
/**
* 拉取盘点明细结果(按范围聚合作业记录)。
* 商品范围(scope_type=goods)按商品合并输出(一个商品一行,多个库位明细行合并),
* 拉取盘点明细结果(后台查看明细口径,仅展示盘点前/盘点后明细使用)。
* 任务尚无作业记录(盘点前,如 created/rejected/submitted 待提交状态)时,rows 直接返回
* wms_stock_check_detail 明细范围行原始数据(商品/库位/商品快照/账面快照),供后台查看盘点范围;
* 存在作业记录后,商品范围(scope_type=goods)按商品合并输出(一个商品一行,多个库位明细行合并),
* 行内 locations 输出该商品所在库位与账面快照数量;库位范围(scope_type=location)
* 按明细行输出,行内按商品聚合作业记录并从 wms_storage 补齐账面数量。
* 未知商品(记录 stock_id 为空)按 barcode 维度归组,行级额外输出 unknown_items;
@ -1708,7 +1710,10 @@ class StockCheckService extends Service {
* @param {Object} params 查询参数。
* @param {number} params.warehouseId 仓库ID(由方法层从上下文注入)。
* @param {number} params.id 盘点任务ID。
* @return {Promise<Object>} { check, rows, total };商品范围按商品聚合(一个商品一行):
* @return {Promise<Object>} { check, rows, total };无作业记录时 rows=wms_stock_check_detail 明细范围行
* (id/check_id/warehouse_id/scope_type/stock_id/location_id/location_code/item_code/item_name/spec/
* batch_no/system_quantity/remark/created_at/updated_at,total=明细行数,check 为主表信息);
* 有作业记录时:商品范围按商品聚合(一个商品一行):
* 行含商品快照(item_code/item_name/spec/batch_no)+ system_quantity(账面快照合计)+ 已盘聚合
* (checked_quantity=记录数量合计、diff_quantity=实盘-账面快照合计、is_diff、status、location_codes、
* checkers、last_checked_at)、records(该商品全部作业记录,每条含 barcode/item_name/images)与
@ -1749,6 +1754,16 @@ class StockCheckService extends Service {
raw: true,
});
// 盘点前(尚无作业记录,如待提交状态):直接返回明细范围行(wms_stock_check_detail),
// 供后台查看盘点范围明细(本接口不再作为盘点作业数据提供)
if (records.length === 0) {
return {
check: this._formatCheckRow(check.get({ plain: true })),
rows: detailRows,
total: detailRows.length,
};
}
// 挂载作业记录图片(FileReference business_type=stock_check_record,与收货 receivingItem 口径一致)
await this._attachRecordImages(records);

View File

@ -1,4 +1,18 @@
[
{
"version": "0.3.262",
"date": "2026-10-10",
"type": "updated",
"summary": "stock.check.result 无作业记录时返回明细范围行(盘点前/待提交后台查看明细专用,不再作为盘点作业数据提供)(0.3.261 → 0.3.262)",
"methods": [
"stock.check.result"
],
"notes": [
"变更内容:result 在无作业记录(如待提交/盘点前)时 rows 直接返回 wms_stock_check_detail 明细范围行(原始行,不聚合),total=明细行数——本接口仅展示盘点前/盘点后后台查看明细使用,不再作为盘点作业数据提供(盘点作业数据见 stock.check.workData);有作业记录时保持原聚合口径不变(商品范围按商品合并、库位范围按库位行)。",
"代码依据:app/service/systems/stock_check.js#result(records.length===0 分支直接返回明细行);回归测试调整 3 用例(盘点前/待提交两用例新断言明细范围行口径;addDetail 与 recordDelete 用例同步改为断言明细范围行),stock_check 全量 235 用例通过、ESLint 0 错误。",
"文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.result 一条(description/response.rows/notes 补充无作业记录时返回明细范围行口径);根版本 0.3.261 → 0.3.262、updatedAt 保持 2026-10-10;methods/changes/system.json 新增本条(插入数组首位);其余 24 条 method 未改动(stock.check 分组仍为 25 条)。"
]
},
{
"version": "0.3.261",
"date": "2026-10-10",

View File

@ -1,7 +1,7 @@
{
"module": "system",
"description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内",
"version": "0.3.261",
"version": "0.3.262",
"updatedAt": "2026-10-10",
"headers": [
{
@ -38555,7 +38555,7 @@
},
{
"method": "stock.check.result",
"description": "拉取盘点明细结果(按范围聚合作业记录):入参 id(盘点任务ID);返回 { check, rows, total };商品范围按商品聚合(一个商品一行,多个库位明细行合并):行含商品快照 + 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;无作业记录时聚合字段为 null、records 为空数组。",
"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 直接返回明细范围行(原始行,见下)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
@ -38610,7 +38610,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(视为已盘点);无作业记录时 records/locations/stocks/unknown_items 为空数组、checked_quantity/diff_quantity/last_checked_at 为 null"
"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 字段)"
},
{
"name": "total",
@ -38641,7 +38641,7 @@
"权限口径:随 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 补齐。",
"无作业记录时:checked_quantity/diff_quantity/last_checked_at 为 null、records 为空数组、status=unchecked、is_diff=0(商品范围 locations 仍输出账面快照库位且 quantity 为 0;库位范围 locations/stocks 为空数组)。",
"无作业记录口径(本次变更):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)。",