feat(stock.check): workData 新增 only_abnormal 只看未盘与差异并同步接口文档(0.3.250)

This commit is contained in:
liufumingren 2026-10-07 23:26:05 +08:00
parent 49fb70fcbf
commit 0fa098c188
4 changed files with 99 additions and 8 deletions

View File

@ -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<Object>} 统一 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 }),
'拉取盘点作业数据失败'
);
}

View File

@ -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<Object>} { 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<Object>} rows 待过滤的作业数据行(keyword 过滤之后的全量行)。
* @param {boolean} isOpen 是否明盘(true=明盘含数量字段,false=盲盘无数量字段)。
* @return {Array<Object>} 过滤后的行列表。
*/
_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),

View File

@ -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",

File diff suppressed because one or more lines are too long