diff --git a/app/service/systemMethods/stock/check.js b/app/service/systemMethods/stock/check.js index 23bcc99..c4ee484 100644 --- a/app/service/systemMethods/stock/check.js +++ b/app/service/systemMethods/stock/check.js @@ -349,6 +349,11 @@ class StockCheckMethodService extends MainService { * 缺省 false=聚合库位视图(space);库位任务无视该参数(兼容 isGoods 驼峰写法)。 * @param {string} [data.keyword] 关键字(仅库位任务 location 视图生效):按行 * location_code/location_name 模糊匹配(不区分大小写)过滤任务明细后返回;非库位任务忽略。 + * @param {boolean} [data.only_abnormal] 只看未盘和差异(可选,向后兼容新增,兼容 onlyAbnormal 驼峰写法): + * 过滤在 keyword 之后、分页切片之前完成,三视图均生效——location 视图仅保留 status=unchecked + * 或含未知商品记录(has_unknown=true)的行;goods 视图仅保留未盘行(locations 均无 record_ids) + * 或明盘差异行(is_diff=1,盲盘无数量字段仅按未盘过滤);space 视图按行内 goods 子项过滤 + * (status=unchecked 或明盘 checked_quantity≠system_quantity),过滤后 goods 为空的行整体移除。 * @param {Object} [data.pagination] 分页配置 { page, pageSize }。 * @return {Promise} 统一 success 包装,返回 { view, rows, total, page, pageSize };rows 结构按视图不同: * location=库位结构(任务库位范围行为列表,行内挂 goods/unknown 作业记录子列表); @@ -366,11 +371,14 @@ class StockCheckMethodService extends MainService { isGoods: isGoodsCamel, keyword, pagination, + only_abnormal: onlyAbnormalSnake, + onlyAbnormal: onlyAbnormalCamel, } = data || {}; const isGoods = isGoodsSnake !== undefined ? isGoodsSnake : isGoodsCamel; + const onlyAbnormal = onlyAbnormalSnake !== undefined ? onlyAbnormalSnake : onlyAbnormalCamel; return this._call( - () => this.service.systems.stockCheck.workData({ warehouseId, id, isGoods, keyword, pagination }), + () => this.service.systems.stockCheck.workData({ warehouseId, id, isGoods, keyword, pagination, onlyAbnormal }), '拉取盘点作业数据失败' ); } diff --git a/app/service/systems/stock_check.js b/app/service/systems/stock_check.js index 2a76b77..ccaa2f6 100644 --- a/app/service/systems/stock_check.js +++ b/app/service/systems/stock_check.js @@ -2647,6 +2647,11 @@ class StockCheckService extends Service { * 缺省为 false(聚合库位 space 视图);库位任务无视该参数。 * @param {string} [params.keyword] 关键字(仅库位任务 location 视图生效):按行 * location_code/location_name 模糊匹配(不区分大小写)过滤后返回;非库位任务忽略。 + * @param {boolean} [params.onlyAbnormal] 只看未盘和差异(可选,向后兼容):过滤在 keyword 之后、 + * 分页切片之前完成,三视图均生效——location 视图仅保留 status=unchecked 或 has_unknown=true 的行; + * goods 视图仅保留未盘行(locations 均无 record_ids)或明盘差异行(is_diff=1); + * space 视图按行内 goods 子项过滤(status=unchecked 或明盘 checked_quantity≠system_quantity), + * 过滤后 goods 为空的行整体移除;盲盘无数量字段仅按未盘过滤;total 为过滤后行数。 * @param {Object} [params.pagination] 分页配置 { page, pageSize }。 * @return {Promise} { view, rows, total, page, pageSize };view 为解析后的视图类型 * (location=库位结构/goods=商品结构/space=聚合库位结构);rows 结构按解析后的视图不同: @@ -2658,7 +2663,7 @@ class StockCheckService extends Service { * @throws {Error} 任务不存在或任务状态非 approved/checking 时抛出业务错误(错误码 400)。 */ async workData(params = {}) { - const { warehouseId, id, isGoods, keyword, pagination = {} } = params; + const { warehouseId, id, isGoods, keyword, pagination = {}, onlyAbnormal } = params; const checkId = Number(id); if (!Number.isInteger(checkId) || checkId <= 0) { @@ -2690,12 +2695,19 @@ class StockCheckService extends Service { // keyword 过滤:仅库位任务(location 视图)启用,按行 location_code/location_name // 模糊匹配(不区分大小写)过滤任务明细后再分页;非库位任务忽略该参数 const normalizedKeyword = String(keyword || '').trim().toLowerCase(); - const filteredRows = resolvedView === 'location' && normalizedKeyword + const keywordFilteredRows = resolvedView === 'location' && normalizedKeyword ? allRows.filter(row => String(row.location_code || '').toLowerCase().includes(normalizedKeyword) || String(row.location_name || '').toLowerCase().includes(normalizedKeyword)) : allRows; + // only_abnormal 过滤:仅保留"未盘或有差异"的行(与 keyword 过滤叠加,三视图均生效); + // 未传/非 true(false/0/空串/缺省)不过滤 + const abnormalRequested = onlyAbnormal === true || onlyAbnormal === 'true' || onlyAbnormal === 1; + const filteredRows = abnormalRequested + ? this._filterAbnormalWorkRows(resolvedView, keywordFilteredRows, check.mode !== 'blind') + : keywordFilteredRows; + // 分页切片:page 默认 1、pageSize 默认 20(上限 200),非法值回退默认 const page = Math.max(1, Number(pagination.page) || 1); const pageSize = Math.min(200, Math.max(1, Number(pagination.pageSize) || 20)); @@ -2710,6 +2722,54 @@ class StockCheckService extends Service { }; } + /** + * only_abnormal 过滤:仅保留"未盘或有差异"的行(workData 专用,过滤在分页切片之前完成)。 + * 语义按视图区分: + * - location 视图:保留 status=unchecked(未盘)或 has_unknown=true(含未知商品记录,未知商品无账面、 + * 差异=实盘-0=盘盈,视为差异)的行;空库位标记(is_empty)后 status=checked 视为已盘点、不保留; + * - goods 视图:未盘口径为 locations 均无 record_ids(无任何作业记录);差异口径为明盘 is_diff=1; + * 盲盘(isOpen=false)无数量字段,仅按未盘过滤(已盘行全部移除); + * - space 视图:按行内 goods 子项过滤——保留 status=unchecked 的子项,明盘另保留 + * checked_quantity≠system_quantity(数量差异)的子项;过滤后 goods 为空的行整体移除。 + * + * @param {string} view 服务端解析出的视图类型(location/goods/space)。 + * @param {Array} rows 待过滤的作业数据行(keyword 过滤之后的全量行)。 + * @param {boolean} isOpen 是否明盘(true=明盘含数量字段,false=盲盘无数量字段)。 + * @return {Array} 过滤后的行列表。 + */ + _filterAbnormalWorkRows(view, rows, isOpen) { + if (view === 'location') { + return rows.filter(row => row.status === 'unchecked' || row.has_unknown === true); + } + if (view === 'goods') { + return rows.filter(row => { + const hasRecords = Array.isArray(row.locations) + && row.locations.some(location => location + && Array.isArray(location.record_ids) + && location.record_ids.length > 0); + if (!hasRecords) { + return true; + } + return isOpen && row.is_diff === 1; + }); + } + // space 视图:按行内 goods 子项过滤,过滤后 goods 为空的行整体移除 + return rows + .map(row => ({ + ...row, + goods: (Array.isArray(row.goods) ? row.goods : []).filter(item => { + if (!item) { + return false; + } + if (item.status === 'unchecked') { + return true; + } + return isOpen && Number(item.checked_quantity) !== Number(item.system_quantity); + }), + })) + .filter(row => Array.isArray(row.goods) && row.goods.length > 0); + } + /** * 拉取盘点作业数据(space 视图分页版)。 * 行结构与 workData space 视图行一致(id=库位ID/space_code/custom_barcode/custom_name/goods), diff --git a/methods/changes/system.json b/methods/changes/system.json index 140e64f..840100f 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,18 @@ [ + { + "version": "0.3.250", + "date": "2026-10-06", + "type": "updated", + "summary": "stock.check.workData 新增 only_abnormal 入参(可选,兼容 onlyAbnormal 驼峰写法):只看未盘和差异——过滤在 keyword 之后、分页切片之前完成,三视图均生效(location 视图按行 status=unchecked 或 has_unknown 保留;goods 视图按未盘行或明盘 is_diff=1 保留,盲盘仅按未盘;space 视图按行内 goods 子项过滤 status=unchecked 或明盘数量差异、空行整体移除;total 为过滤后行数)(0.3.249 → 0.3.250)", + "methods": [ + "stock.check.workData" + ], + "notes": [ + "变更内容:stock.check.workData params 新增 only_abnormal(boolean,body,可选,向后兼容,兼容 onlyAbnormal 驼峰写法;未传或非 true(false/0/空串/缺省)不过滤)——过滤在 keyword 之后、分页切片之前完成(与 keyword 叠加,keyword 先过滤、only_abnormal 后过滤;total 为过滤后行数),三视图均生效:①location 视图仅保留 status=unchecked(未盘)或 has_unknown=true(含未知商品记录,未知商品无账面、差异=实盘-0=盘盈视为差异)的行,空库位标记(is_empty)后 status=checked 视为已盘点、不保留;②goods 视图仅保留未盘行(locations 均无 record_ids,即无任何作业记录)或明盘差异行(is_diff=1),盲盘(mode=blind)无数量字段仅按未盘过滤(已盘行全部移除);③space 视图按行内 goods 子项过滤(保留 status=unchecked 子项,明盘另保留 checked_quantity≠system_quantity 的数量差异子项,system_quantity 口径=可用+锁定),过滤后 goods 为空的行整体移除。", + "代码依据:app/service/systemMethods/stock/check.js#workData(only_abnormal/onlyAbnormal 蛇形驼峰兼容与透传)+ app/service/systems/stock_check.js#workData(abnormalRequested=onlyAbnormal===true||'true'||1,keywordFilteredRows 后调用 _filterAbnormalWorkRows(resolvedView, rows, check.mode!=='blind'),再分页切片;新增 _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 条)。" + ] + }, { "version": "0.3.249", "date": "2026-10-06", diff --git a/methods/system.json b/methods/system.json index e0292d4..efb737c 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,7 +1,7 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.249", + "version": "0.3.250", "updatedAt": "2026-10-06", "headers": [ { @@ -38591,7 +38591,7 @@ }, { "method": "stock.check.workData", - "description": "拉取盘点作业数据(视图由任务范围与 is_goods 入参驱动,view 入参已废弃忽略):入参 id(盘点任务ID)+ is_goods(可选,商品任务是否按商品视图返回——true=goods 视图;缺省 false=聚合库位 space 视图;兼容 isGoods 驼峰写法;库位任务无视该参数)+ keyword(可选,关键字:仅库位任务 location 视图生效——按行 location_code/location_name 模糊匹配(不区分大小写)过滤任务明细后再分页;非库位任务忽略;空/纯空白视为未传);返回 { view, rows, total, page, pageSize }(view=服务端实际解析出的视图类型 location/goods/space,供调用方判断 rows 行结构;不返回任务主表信息 check——任务信息请调用 stock.check.detail),rows 结构随解析视图不同(先构建全量行——location 视图且 keyword 非空时先按 location_code/location_name 过滤,再按页切片,rows 为当前页行)、total=全部行数(未分页口径;location 视图 + keyword 时 total 为过滤后行数)、page=当前页码(默认 1)、pageSize=每页数量(默认 20,上限 200),任务无对应范围行时 rows 返回空数组。分页:入参 data.pagination({ page, pageSize }),未传或非法时默认 page=1、pageSize=20(上限 200),分页口径与 stock.check.list 一致。视图解析:任务范围为库位(type=location/all)一律按 location 视图;任务范围为商品(type=goods/store)默认 space 视图、仅 is_goods=true 时 goods 视图。location(库位结构):以任务库位范围行(scope_type=location)为列表(按明细 id 升序),行内挂该库位的盘点作业记录 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(商品结构):以任务商品范围行(scope_type=goods)为列表(按明细 id 升序),行内 locations 为商品所在全部库位列表(商品库存库位取自 wms_storage——启用未删除存储 DISTINCT space_id 按拣货路径排序,无库存但已有作业记录的库位追加在末尾;每项含 record_ids 该库位该商品全部作业记录 ID(按记录 id 升序)与 images 该库位该商品全部作业照片(扁平去重),供前端编辑/移除记录;未盘库位 checked_at=null、record_ids/images 为空数组),明盘(mode=open)返回账面快照/已盘合计/差异,每库位含 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_code 匹配 wms_location_space.space_code 补查,与库存库位去重后取并集),按拣货路径排序(pick_sequence 升序、pick_priority 降序、库位 id 升序兜底),行内 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/all)一律按 location 视图;任务范围为商品(type=goods/store)默认 space 视图、仅 is_goods=true 时 goods 视图。location(库位结构):以任务库位范围行(scope_type=location)为列表(按明细 id 升序),行内挂该库位的盘点作业记录 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(商品结构):以任务商品范围行(scope_type=goods)为列表(按明细 id 升序),行内 locations 为商品所在全部库位列表(商品库存库位取自 wms_storage——启用未删除存储 DISTINCT space_id 按拣货路径排序,无库存但已有作业记录的库位追加在末尾;每项含 record_ids 该库位该商品全部作业记录 ID(按记录 id 升序)与 images 该库位该商品全部作业照片(扁平去重),供前端编辑/移除记录;未盘库位 checked_at=null、record_ids/images 为空数组),明盘(mode=open)返回账面快照/已盘合计/差异,每库位含 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_code 匹配 wms_location_space.space_code 补查,与库存库位去重后取并集),按拣货路径排序(pick_sequence 升序、pick_priority 降序、库位 id 升序兜底),行内 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)的任务可拉取」。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -38624,6 +38624,13 @@ "source": "body", "description": "关键字(可选,向后兼容新增):仅库位任务(服务端解析视图为 location,即任务类型 location/all)生效——按行 location_code(优先明细快照,缺失回退库位表 space_code)与 location_name(custom_name 兜底 space_code)做模糊匹配(contains、不区分大小写)过滤任务明细后再分页返回;非库位任务(goods/store,space/goods 视图)忽略该参数;keyword 为空/纯空白视为未传不过滤" }, + { + "name": "only_abnormal", + "type": "boolean", + "required": false, + "source": "body", + "description": "只看未盘和差异(可选,向后兼容新增,兼容 onlyAbnormal 驼峰写法):过滤在 keyword 之后、分页切片之前完成,三视图均生效——location 视图仅保留 status=unchecked 或含未知商品记录(has_unknown=true)的行(空库位标记 is_empty 后 status=checked 视为已盘点、不保留);goods 视图仅保留未盘行(locations 均无 record_ids,即无任何作业记录)或明盘差异行(is_diff=1,盲盘无数量字段仅按未盘过滤);space 视图按行内 goods 子项过滤(status=unchecked 或明盘 checked_quantity≠system_quantity),过滤后 goods 为空的行整体移除;未传/非 true(false/0/空串/缺省)不过滤;total 为过滤后行数" + }, { "name": "pagination", "type": "object", @@ -38667,13 +38674,13 @@ "name": "rows", "type": "array", "required": true, - "description": "盘点作业数据行列表(当前页行:先构建全量行——location 视图且 keyword 非空时先按行 location_code/location_name 模糊匹配(不区分大小写)过滤,再按页切片;total 为全部行数——未分页口径;location 视图 + keyword 时 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_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_code, checked_at, checker_name, record_ids 该库位该商品全部作业记录 ID(按记录 id 升序,供前端编辑/移除记录), images 该库位该商品全部记录的作业照片(扁平去重,无照片为空数组) }],未盘库位 checked_at/checker_name 为 null、record_ids/images 为空数组),明盘(mode=open)另含 system_quantity 账面快照/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))与 quantity 该库位盘点数量(实盘合计,未盘库位 0),盲盘(mode=blind)不返回任何数量字段(locations 仅 location_code/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_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_code, checked_at, checker_name, record_ids 该库位该商品全部作业记录 ID(按记录 id 升序,供前端编辑/移除记录), images 该库位该商品全部记录的作业照片(扁平去重,无照片为空数组) }],未盘库位 checked_at/checker_name 为 null、record_ids/images 为空数组),明盘(mode=open)另含 system_quantity 账面快照/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))与 quantity 该库位盘点数量(实盘合计,未盘库位 0),盲盘(mode=blind)不返回任何数量字段(locations 仅 location_code/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(该商品在该库位的实盘合计),盲盘不含数量;库位集合=当前库存库位 ∪ 作业记录库位(盘点前库存已出空但已有盘点作业记录的库位也能展示)" }, { "name": "total", "type": "number", "required": true, - "description": "行总数(全部行数——未分页口径,任务无对应范围行时为 0;分页时 rows 为当前页行、total 保持全部行数不变;location 视图 + keyword 非空时 total 为过滤后的行数)" + "description": "行总数(全部行数——未分页口径,任务无对应范围行时为 0;分页时 rows 为当前页行、total 保持全部行数不变;location 视图 + keyword 非空或 only_abnormal=true 时 total 为过滤后的行数)" }, { "name": "page", @@ -38763,7 +38770,9 @@ "文档变更范围: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 错误。" + "库位账面口径全量统一(本次,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 错误。", + "文档变更范围: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 条)。" ] }, {