diff --git a/app/service/systemMethods/stock/check.js b/app/service/systemMethods/stock/check.js index 18aa7d0..82131f3 100644 --- a/app/service/systemMethods/stock/check.js +++ b/app/service/systemMethods/stock/check.js @@ -59,9 +59,9 @@ class StockCheckMethodService extends MainService { * * @param {Object} data 请求体。 * @param {string} [data.title] 盘点名称/主题。 - * @param {string} [data.type] 盘点范围类型:all/store/goods/location。 + * @param {string} [data.type] 盘点范围类型:location/store/goods,缺省 location。 * @param {string} [data.mode] 盘点方式:open=明盘/blind=盲盘; - * 按库位盘点(all/location)一律盲盘,忽略前端传入;按商品盘点(store/goods)按传入值(默认明盘)。 + * 按库位盘点(location)一律盲盘,忽略前端传入;按商品盘点(store/goods)按传入值(默认明盘)。 * @param {number} [data.store_id] 货主ID(按货主盘点时必填)。 * @param {string} [data.remark] 备注。 * 盘点日期固定为今天,前端不传。 @@ -151,7 +151,7 @@ class StockCheckMethodService extends MainService { * @param {Object} [data.pagination] 分页参数。 * @param {Object} [data.where] 查询条件。 * @param {string|Array} [data.where.status] 状态筛选(单值或数组)。 - * @param {string|Array} [data.where.type] 范围类型筛选(all/store/goods/location)。 + * @param {string|Array} [data.where.type] 范围类型筛选(location/store/goods)。 * @param {string|Array} [data.where.mode] 盘点方式筛选(open/blind)。 * @param {number} [data.where.store_id] 货主筛选。 * @param {string} [data.where.keyword] 关键字(单号/标题模糊)。 @@ -334,7 +334,7 @@ class StockCheckMethodService extends MainService { /** * 拉取盘点作业数据(视图由任务类型与 is_goods 驱动)。 * warehouse_id 由服务端从当前上下文自动注入,前端无需传递。 - * 视图规则:任务范围为库位(type=location/all)时一律按库位视图返回(无视 view/is_goods); + * 视图规则:任务范围为库位(type=location)时一律按库位视图返回(无视 view/is_goods); * 任务范围为商品(type=goods/store)时默认聚合库位视图(space), * 仅传入 is_goods=true 时按商品视图(goods)返回。 * 分页:data.pagination.{page,pageSize}(与 stock.check.list 口径一致, @@ -386,7 +386,7 @@ class StockCheckMethodService extends MainService { /** * 拉取盘点作业数据(space 视图分页版)。 * warehouse_id 由服务端从当前上下文自动注入,前端无需传递。 - * 行结构与 workData space 视图行一致(id=库位ID/space_code/custom_barcode/custom_name/goods, + * 行结构与 workData space 视图行一致(id=库位ID/location_id 同义库位ID/space_code/custom_barcode/custom_name/goods, * goods 行含 detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images/ * record_ids,明盘另含 system_quantity/checked_quantity,status=checked/unchecked); * 传入 location_id 时只返回该库位行(total=1),不传时按分页返回全部库位行。 @@ -450,8 +450,10 @@ class StockCheckMethodService extends MainService { * @param {Object} data 请求体。 * @param {number} data.id 盘点任务ID。 * @param {number} data.detail_id 明细ID。 - * @param {string} [data.location] 库位编码(可空;库位明细行以明细库位为准)。 - * @param {number} data.quantity 实盘数量(>=0)。 + * @param {number} data.space_id 库位ID(wms_location_space.id,**必传**;兼容 spaceId / location_id / locationId 写法)。 + * 必须属于本仓库且所属分区有效;服务端以该 ID 为准落库,不再按库位编码猜库位。 + * @param {string} [data.location] 库位编码(可选,仅做一致性校验:与 space_id 对应库位编码不一致报 400)。 + * @param {number} data.quantity 实盘数量(>=0 且 <= 2147483647)。 * @param {number} [data.stock_id] 商品库存ID(wms_stock_warehouse.id;库位明细行必填,或改传 barcode)。 * @param {string} [data.barcode] 扫描到的条码/编码(未传 stock_id 时按条码匹配系统商品,未命中记为未知商品)。 * @param {string} [data.item_name] 未知商品名称(缺省为 barcode;已知商品忽略)。 @@ -472,7 +474,13 @@ class StockCheckMethodService extends MainService { barcode, item_name: itemName, is_empty: isEmpty, + space_id: spaceIdSnake, + spaceId: spaceIdCamel, + location_id: locationIdSnake, + locationId: locationIdCamel, } = data || {}; + const spaceId = [ spaceIdSnake, spaceIdCamel, locationIdSnake, locationIdCamel ] + .find(value => value !== undefined && value !== null && value !== ''); return this._call( () => this.service.systems.stockCheck.report({ @@ -480,6 +488,7 @@ class StockCheckMethodService extends MainService { id, detailId, location, + spaceId, quantity, stockId, barcode, @@ -494,7 +503,7 @@ class StockCheckMethodService extends MainService { /** * 标记库位为空(库位盘点模式专属)。 - * warehouse_id 由服务端从当前上下文自动注入;仅任务范围为库位(type=location/all)时允许, + * warehouse_id 由服务端从当前上下文自动注入;仅任务范围为库位(type=location)时允许, * 非库位任务报 400;状态仅 approved/checking;明细必须属于本任务且为库位范围行。 * 行为与 report(is_empty=true) 一致:写/更新空标记记录、清除该明细商品记录、重算汇总。 * @@ -594,7 +603,7 @@ class StockCheckMethodService extends MainService { /** * 重盘清除库位(按库位清除盘点信息,库位盘点模式专属)。 * 传入任务ID与库位ID,清除该库位范围内明细的全部作业记录(含空库位标记),该库位回到未盘; - * 仅任务范围为库位(type=location/all)且状态 approved/checking 时允许,非库位任务报 400。 + * 仅任务范围为库位(type=location)且状态 approved/checking 时允许,非库位任务报 400。 * * @param {Object} data 请求体。 * @param {number} data.id 盘点任务ID。 diff --git a/app/service/systems/location_zone.js b/app/service/systems/location_zone.js index 4e04ff8..3951f58 100644 --- a/app/service/systems/location_zone.js +++ b/app/service/systems/location_zone.js @@ -376,9 +376,44 @@ class LocationZoneService extends Service { return count === 0; } + /** + * 校验分区编码在同仓库未占用(已归档分区不占用编码:paranoid 查询自动带 deleted_at IS NULL)。 + * 同仓库同 zone_code 并存会生成同 space_code 的库位行,导致盘点/库存按编码定位到多条库位。 + * + * @param {number} warehouseId 仓库ID。 + * @param {string} zoneCode 分区编码。 + * @param {number} [excludeZoneId] 排除的分区ID(更新场景排除自身)。 + * @return {Promise} 校验不通过时抛出错误。 + */ + async assertZoneCodeAvailable(warehouseId, zoneCode, excludeZoneId = 0) { + const { ctx } = this; + const code = String(zoneCode || '').trim(); + if (!code) { + return; + } + if (!/^[A-Z0-9]{1,5}$/.test(code)) { + throw new Error('编码必须是1-5位大写字母或数字'); + } + const where = { + warehouse_id: Number(warehouseId), + zone_code: code, + }; + if (Number(excludeZoneId) > 0) { + where.id = { [ctx.app.Sequelize.Op.ne]: Number(excludeZoneId) }; + } + const exists = await ctx.model.LocationZone.findOne({ + where, + attributes: [ 'id' ], + raw: true, + }); + if (exists) { + throw new Error(`分区编码已存在:${code}(同仓库编码需唯一,归档分区不占用编码)`); + } + } + /** * 创建元素 - * @param {Object} data 元素数据 + * @param {Object} data 元素数据 * @return {Promise} 创建的元素 */ async createZone(data) { @@ -398,6 +433,9 @@ class LocationZoneService extends Service { // 5. 处理编码(根据类型) const zoneCode = this.generateZoneCodeByType(data); + // 5.1 编码唯一性:同仓库未归档分区不得重复(否则会生成同编码库位,盘点按编码定位错乱) + await this.assertZoneCodeAvailable(warehouse_id, zoneCode); + // 6. 创建分区 const zone = await ctx.model.LocationZone.create({ warehouse_id, @@ -737,6 +775,17 @@ class LocationZoneService extends Service { const updateData = { ...data }; + // 编码变更需保证同仓库未归档分区内唯一(未变更则跳过) + if (updateData.zone_code !== undefined && updateData.zone_code !== null) { + const nextCode = String(updateData.zone_code).trim(); + if (nextCode && nextCode !== String(zone.zone_code || '').trim()) { + await this.assertZoneCodeAvailable(zone.warehouse_id, nextCode, id); + updateData.zone_code = nextCode; + } else if (!nextCode) { + delete updateData.zone_code; + } + } + if (data.is_active !== undefined) { const isActive = [ true, 1, '1', 'true' ].includes(data.is_active); const isInactive = [ false, 0, '0', 'false' ].includes(data.is_active); diff --git a/app/service/systems/stock_check.js b/app/service/systems/stock_check.js index 2e6c8a1..4a4e485 100644 --- a/app/service/systems/stock_check.js +++ b/app/service/systems/stock_check.js @@ -9,7 +9,7 @@ const ExcelJS = require('exceljs'); const Service = require('egg').Service; /** 盘点范围类型枚举(wms_stock_check.type) */ -const STOCK_CHECK_TYPES = Object.freeze([ 'all', 'store', 'goods', 'location' ]); +const STOCK_CHECK_TYPES = Object.freeze([ 'store', 'goods', 'location' ]); /** 盘点方式枚举(wms_stock_check.mode) */ const STOCK_CHECK_MODES = Object.freeze([ 'open', 'blind' ]); /** 允许添加明细的主表状态 */ @@ -18,6 +18,11 @@ const ADD_DETAIL_ALLOWED_STATUSES = Object.freeze([ 'created', 'rejected' ]); const STOCK_CHECK_ADD_LOCATION_DETAIL_MAX_IDS = 200; /** 允许盘点作业上报/完成的主表状态 */ const REPORT_ALLOWED_STATUSES = Object.freeze([ 'approved', 'checking' ]); +/** + * 单次上报实盘数量上限(wms_stock_check_record.quantity 为 int(12) 有符号列, + * 实际可存上限 2147483647;超限直接落库会抛 Out of range 变成 500)。 + */ +const REPORT_MAX_QUANTITY = 2147483647; /** 允许提交审核的主表状态 */ const SUBMIT_ALLOWED_STATUSES = Object.freeze([ 'created', 'rejected' ]); /** 允许取消的主表状态 */ @@ -33,7 +38,6 @@ const VALID_SPACE_SQL = '(SELECT ls.id FROM wms_location_space ls ' /** 盘点范围类型中文标签 */ const STOCK_CHECK_TYPE_LABELS = Object.freeze({ - all: '全盘', store: '按货主', goods: '按商品', location: '按库位', @@ -158,7 +162,7 @@ class StockCheckService extends Service { id: row.id, check_no: row.check_no, title: row.title || '', - type: row.type || 'all', + type: row.type || 'location', mode: row.mode || 'open', store_id: row.store_id || null, status: row.status || 'created', @@ -546,9 +550,9 @@ class StockCheckService extends Service { * @param {Object} params 创建参数。 * @param {number} params.warehouseId 仓库ID(由方法层从上下文注入)。 * @param {string} [params.title] 盘点名称/主题。 - * @param {string} [params.type='all'] 盘点范围类型:all/store/goods/location。 + * @param {string} [params.type='location'] 盘点范围类型:location/store/goods。 * @param {string} [params.mode='open'] 盘点方式:open=明盘/blind=盲盘; - * 按库位盘点(all/location)一律盲盘,忽略前端传入;按商品盘点(store/goods)按传入值(默认明盘)。 + * 按库位盘点(location)一律盲盘,忽略前端传入;按商品盘点(store/goods)按传入值(默认明盘)。 * @param {number} [params.storeId] 货主ID(按货主盘点时必填)。 * @param {string} [params.remark] 备注。 * 盘点日期固定为今天,前端不传。 @@ -575,7 +579,7 @@ class StockCheckService extends Service { throw this.createBusinessError('无法获取当前仓库上下文'); } - const normalizedType = type ? String(type).trim() : 'all'; + const normalizedType = type ? String(type).trim() : 'location'; if (!STOCK_CHECK_TYPES.includes(normalizedType)) { throw this.createBusinessError(`盘点范围类型不合法,仅支持 ${STOCK_CHECK_TYPES.join('/')}`); } @@ -584,9 +588,9 @@ class StockCheckService extends Service { if (!STOCK_CHECK_MODES.includes(normalizedMode)) { throw this.createBusinessError(`盘点方式不合法,仅支持 ${STOCK_CHECK_MODES.join('/')}`); } - // 按库位盘点(all/location)一律盲盘,不管前端传入什么; + // 按库位盘点一律盲盘,不管前端传入什么; // 按商品盘点(store/goods)按传入值(默认明盘) - if (normalizedType === 'all' || normalizedType === 'location') { + if (normalizedType === 'location') { normalizedMode = 'blind'; } @@ -1046,10 +1050,9 @@ class StockCheckService extends Service { /** * 添加盘点明细(商品或库位,按任务盘点类型决定)。 * 仅 created/rejected 状态允许;store/goods 类型按 stock_ids 添加商品行(商品必须属于 - * 任务货主);all/location 类型按 locations(库位编码,兼容旧调用)或 location_ids + * 任务货主);location 类型按 locations(库位编码,兼容旧调用)或 location_ids * (库位ID,直接查库校验,不再解析编码)添加库位行,两者都传时 location_ids 优先、 - * locations 忽略;all 未传库位且未传库位ID时自动拉取全仓库启用库位; - * 兼容历史任务:type=all 且已存在商品明细行(改造前创建)时继续按商品模式接受 stock_ids; + * locations 忽略;location 未传库位且未传库位ID时自动拉取全仓库启用库位(原全盘语义); * 已存在的同盘点项跳过(幂等),重算主表 total_items。 * * @param {Object} params 添加明细参数。 @@ -1080,26 +1083,16 @@ class StockCheckService extends Service { throw this.createBusinessError(`当前状态(${check.status})不允许添加明细`); } - const checkType = String(check.type || 'all').trim(); - let isGoodsScope = checkType === 'store' || checkType === 'goods'; - let isLocationScope = checkType === 'all' || checkType === 'location'; + const checkType = String(check.type || 'location').trim(); + const isGoodsScope = checkType === 'store' || checkType === 'goods'; + const isLocationScope = checkType === 'location'; + if (!isGoodsScope && !isLocationScope) { + throw this.createBusinessError(`盘点范围类型不合法(${checkType})`); + } const numericStockIds = this._normalizeIdList(stockIds); const locationCodes = this._normalizeCodeList(locations); const numericLocationIds = this._normalizeIdList(locationIds); - // 兼容历史任务:改造前 type=all 的任务按商品添加明细(明细行 scope_type='goods')。 - // 这类任务已存在商品明细行时,继续按商品模式接受 stock_ids,避免旧调用被 400 拒绝; - // 全新 type=all 任务(无任何商品明细行)维持新语义:按库位盘点,只能传 locations。 - if (checkType === 'all' && isLocationScope) { - const goodsScopeCount = await ctx.model.StockCheckDetail.count({ - where: { check_id: checkId, scope_type: 'goods' }, - }); - if (goodsScopeCount > 0) { - isGoodsScope = true; - isLocationScope = false; - } - } - // 按盘点类型校验入参维度(商品与库位互斥) if (isGoodsScope && locationCodes.length > 0) { throw this.createBusinessError('当前盘点类型按商品盘点,请传 stock_ids'); @@ -1143,8 +1136,9 @@ class StockCheckService extends Service { }); } else { let codes = locationCodes; - // 全盘:未显式传库位时自动拉取全仓库启用库位(排除无头库位:zone 必须存在且未删除) - if (checkType === 'all' && codes.length === 0) { + // 未显式传库位时自动拉取全仓库启用库位(原全盘语义); + // 排除无头库位:zone 必须存在且未删除 + if (codes.length === 0) { const enabledSpaces = await ctx.model.LocationSpace.findAll({ where: { warehouse_id: Number(warehouseId), is_enabled: true }, attributes: [ 'space_code' ], @@ -1164,9 +1158,6 @@ class StockCheckService extends Service { throw this.createBusinessError('当前仓库没有启用库位,无法按全盘自动生成盘点范围'); } } - if (codes.length === 0) { - throw this.createBusinessError('请至少选择一个库位'); - } await this._addLocationDetailRows({ checkId, warehouseId, @@ -1408,7 +1399,7 @@ class StockCheckService extends Service { } /** - * 生成按库位盘点明细的待创建行(all/location 类型)。 + * 生成按库位盘点明细的待创建行(location 类型)。 * 按 space_code 匹配 wms_location_space(warehouse_id + space_code), * 不存在的编码记入 invalidLocations;已存在同 check_id+location_code 的明细跳过(幂等)。 * @@ -1483,7 +1474,7 @@ class StockCheckService extends Service { } /** - * 生成按库位盘点明细的待创建行(库位ID直查路径,all/location 类型)。 + * 生成按库位盘点明细的待创建行(库位ID直查路径,location 类型)。 * 直接按 wms_location_space.id 查库校验(warehouse_id 仓库隔离),不经过 space_code 二次解析; * 查不到的 ID 记入 invalidLocationIds(不报错);库位编码为空(脏数据)或已存在 * 同 check_id+location_code 的明细跳过(uk_check_location 唯一索引口径,幂等), @@ -2354,14 +2345,72 @@ class StockCheckService extends Service { return stockRow ? matchedStockId : 0; } + /** + * 按库位编码解析库位ID(仅命中分区存在且未删除的有效库位行)。 + * 同仓库同编码可能同时存在多条库位(历史重复库位、分区已删除的无头库位, + * 唯一索引含 deleted_at 且 NULL 不去重),此处取稳定口径: + * 优先该商品有启用库存的库位行,其次 ID 最小的有效行。 + * + * @param {number} warehouseId 仓库ID。 + * @param {string} locationCode 库位编码。 + * @param {number} [stockId] 商品库存ID(wms_stock_warehouse.id,用于优先命中库存所在库位)。 + * @return {Promise} 库位ID,未命中返回 0。 + */ + async _resolveLocationIdByCode(warehouseId, locationCode, stockId) { + const { ctx } = this; + const { Op } = ctx.app.Sequelize; + const normalizedCode = String(locationCode || '').trim(); + if (!normalizedCode) { + return 0; + } + const spaceRows = await ctx.model.LocationSpace.findAll({ + where: { + warehouse_id: Number(warehouseId), + space_code: normalizedCode, + }, + attributes: [ 'id' ], + // 库位有效性:zone 必须存在且未删除(无头库位不参与匹配) + include: [{ + model: ctx.model.LocationZone, + as: 'zone', + attributes: [], + required: true, + }], + order: [[ 'id', 'ASC' ]], + raw: true, + }); + const candidateIds = (Array.isArray(spaceRows) ? spaceRows : []) + .map(row => Number(row && row.id)) + .filter(id => Number.isInteger(id) && id > 0); + if (candidateIds.length === 0) { + return 0; + } + if (candidateIds.length === 1 || !(Number(stockId) > 0)) { + return candidateIds[0]; + } + const storageRow = await ctx.model.Storage.findOne({ + where: { + warehouse_id: Number(warehouseId), + stock_id: Number(stockId), + space_id: { [Op.in]: candidateIds }, + is_enabled: 1, + }, + attributes: [ 'space_id' ], + raw: true, + }); + const storageSpaceId = storageRow ? Number(storageRow.space_id) : 0; + return storageSpaceId > 0 ? storageSpaceId : candidateIds[0]; + } + /** * 盘点作业上报(覆盖式)。 * 仅 approved/checking 状态允许;商品明细行固定上报明细商品(入参商品不一致报错), * 库位明细行必须指定商品且商品必须属于本仓库,库位以明细库位为准(入参库位不一致报错); * 同明细 + 同商品 + 同库位编码重复上报时更新已有记录的 * quantity/checker_id/checker_name/checked_at(保留原 location_id,若本次新匹配到 location_id 则回填), - * 不再新增;未传库位归入"无库位"分组(location_code 存空串); - * 库位编码匹配 wms_location_space.space_code 时回填 location_id; + * 不再新增;未传库位编码时以 space_id 对应库位的编码落库; + * **space_id 必传**(wms_location_space.id,须属于本仓库且分区有效),库位以该 ID 为准, + * location 编码入参仅做一致性校验(不一致报 400),服务端不再按编码猜库位; * 主表 approved 自动转 checking;重算 checked_items / diff_items / detail_status。 * 数据库层由唯一索引 uk_detail_stock_location(detail_id, stock_id, location_code) 保证并发安全。 * @@ -2379,8 +2428,10 @@ class StockCheckService extends Service { * @param {number} params.warehouseId 仓库ID(由方法层从上下文注入)。 * @param {number} params.id 盘点任务ID。 * @param {number} params.detailId 明细ID。 - * @param {string} [params.location] 库位编码(可空;库位明细行以明细库位为准)。 - * @param {number} params.quantity 实盘数量(>=0)。 + * @param {string} [params.location] 库位编码(可选,仅做一致性校验;库位以 spaceId 为准)。 + * @param {number} params.spaceId 库位ID(wms_location_space.id,必传):必须属于本仓库且分区有效, + * 缺失报 400「缺少库位ID(space_id)」;与 location 编码不一致或(库位明细行)与明细库位不一致同样 400。 + * @param {number} params.quantity 实盘数量(>=0 且 <= 2147483647)。 * @param {number} [params.stockId] 商品库存ID(wms_stock_warehouse.id;库位明细行必填,或改传 barcode)。 * @param {string} [params.barcode] 扫描到的条码/编码(未传 stock_id 时按条码匹配系统商品, * 未命中记为未知商品)。 @@ -2395,7 +2446,7 @@ class StockCheckService extends Service { /** * 标记库位为空(库位盘点模式专属,转调 report 的空库位标记口径)。 - * 仅任务范围为库位(type=location/all)时允许:非库位任务报 400; + * 仅任务范围为库位(type=location)时允许:非库位任务报 400; * 状态仅 approved/checking;明细必须属于本任务且为库位范围行(scope_type=location)。 * 行为与 report(is_empty=true) 完全一致:写/更新空标记记录(stock_id/barcode/item_name 为空、 * quantity=0、is_empty=1)、清除该明细商品记录、主表 approved→checking、 @@ -2430,7 +2481,7 @@ class StockCheckService extends Service { throw this.createBusinessError(`当前状态(${check.status})不允许盘点作业`); } const normalizedType = String(check.type || '').trim(); - if (normalizedType !== 'location' && normalizedType !== 'all') { + if (normalizedType !== 'location') { throw this.createBusinessError('仅库位盘点任务支持空库位标记'); } @@ -2445,11 +2496,20 @@ class StockCheckService extends Service { throw this.createBusinessError('仅库位盘点明细支持空库位标记'); } - // 转调 report 空库位标记口径(查重/互斥/汇总/日志统一) + // 转调 report 空库位标记口径(查重/互斥/汇总/日志统一); + // report 要求必传 space_id,这里按明细库位编码解析有效库位(明细库位可能指向无头库位) + const resolvedSpaceId = await this._resolveLocationIdByCode( + Number(warehouseId), + String(detail.location_code || '').trim() + ); + if (resolvedSpaceId <= 0) { + throw this.createBusinessError('盘点明细库位无效(库位不存在或所属分区已删除)'); + } return this.report({ warehouseId, id: checkId, detailId: detailRowId, + spaceId: resolvedSpaceId, is_empty: true, checkerId, checkerName, @@ -2462,6 +2522,7 @@ class StockCheckService extends Service { id, detailId, location, + spaceId: spaceIdInput, quantity, stockId, barcode, @@ -2496,6 +2557,9 @@ class StockCheckService extends Service { if (!normalizedIsEmpty && (!Number.isInteger(quantityValue) || quantityValue < 0)) { throw this.createBusinessError('实盘数量必须为不小于0的整数'); } + if (!normalizedIsEmpty && quantityValue > REPORT_MAX_QUANTITY) { + throw this.createBusinessError(`实盘数量不能超过 ${REPORT_MAX_QUANTITY}`); + } const detail = await ctx.model.StockCheckDetail.findOne({ where: { id: detailRowId, check_id: checkId, warehouse_id: Number(warehouseId) }, @@ -2518,6 +2582,36 @@ class StockCheckService extends Service { const inputItemName = itemName !== undefined && itemName !== null && String(itemName).trim() !== '' ? String(itemName).trim() : ''; + // 必填库位ID(wms_location_space.id):必须属于本仓库且所属分区有效。 + // 不允许按编码猜库位(同仓库同编码可能有多条历史重复/无头库位),缺失即 400 由调用方补传 + const inputSpaceId = spaceIdInput !== undefined && spaceIdInput !== null && spaceIdInput !== '' + ? Number(spaceIdInput) + : 0; + if (!Number.isInteger(inputSpaceId) || inputSpaceId <= 0) { + throw this.createBusinessError('缺少库位ID(space_id),请传取回数据中的 space_id'); + } + const inputLocationRow = await ctx.model.LocationSpace.findOne({ + where: { id: inputSpaceId, warehouse_id: Number(warehouseId) }, + attributes: [ 'id', 'space_code' ], + include: [{ + model: ctx.model.LocationZone, + as: 'zone', + attributes: [], + required: true, + }], + raw: true, + }); + if (!inputLocationRow) { + throw this.createBusinessError('上报库位不存在、不属于当前仓库或所属分区已删除'); + } + const inputLocationCode = String(inputLocationRow.space_code || '').trim(); + if (!inputLocationCode) { + throw this.createBusinessError('上报库位的库位编码为空,无法上报'); + } + // 入参库位编码(可选):仅做一致性校验,库位以 space_id 对应的库位行为准 + const inputLocationCodeParam = location !== undefined && location !== null && String(location).trim() !== '' + ? String(location).trim() + : ''; let normalizedStockId = 0; let normalizedBarcode = null; @@ -2552,39 +2646,25 @@ class StockCheckService extends Service { } else if (inputBarcode) { normalizedBarcode = inputBarcode; } - // 库位编码匹配 wms_location_space.space_code 时回填 location_id; - // 未传库位归一为空串("无库位"分组,配合 uk_detail_stock_location 唯一索引) - locationCode = location !== undefined && location !== null && String(location).trim() !== '' - ? String(location).trim() - : ''; - if (locationCode) { - const space = await ctx.model.LocationSpace.findOne({ - where: { - warehouse_id: Number(warehouseId), - space_code: locationCode, - }, - attributes: [ 'id' ], - raw: true, - }); - if (space) { - locationId = space.id; - } + // 库位以 space_id 对应的库位行为准(必填);location 编码仅做一致性校验 + if (inputLocationCodeParam && inputLocationCodeParam !== inputLocationCode) { + throw this.createBusinessError('上报库位编码与库位ID不一致'); } + locationCode = inputLocationCode; + locationId = Number(inputLocationRow.id); } else { // 库位行:以明细库位为准 locationCode = String(detail.location_code || '').trim(); if (!locationCode) { throw this.createBusinessError('盘点明细缺少库位信息'); } - const inputLocation = location !== undefined && location !== null && String(location).trim() !== '' - ? String(location).trim() - : ''; - if (inputLocation && inputLocation !== locationCode) { + if (inputLocationCodeParam && inputLocationCodeParam !== locationCode) { throw this.createBusinessError('上报库位与盘点明细库位不一致'); } - locationId = detail.location_id !== null && detail.location_id !== undefined - ? Number(detail.location_id) - : null; + if (inputLocationCode !== locationCode) { + throw this.createBusinessError('上报库位与盘点明细库位不一致'); + } + locationId = Number(inputLocationRow.id); if (normalizedIsEmpty) { // 空库位标记:不要求商品,stock_id/barcode/item_name 均为空、quantity=0 @@ -2628,7 +2708,7 @@ class StockCheckService extends Service { const now = new Date(); - // 覆盖式上报:已知商品按同明细 + 同商品 + 同库位编码(未传库位为空串"无库位"分组)更新已有记录, + // 覆盖式上报:已知商品按同明细 + 同商品 + 同库位编码(库位编码来自 space_id 对应库位)更新已有记录, // 依赖唯一索引 uk_detail_stock_location(detail_id, stock_id, location_code) 保证并发安全; // 未知商品唯一索引不约束 NULL 行,按同明细 + 同条码 + 同库位编码在应用层查重; // 空库位标记按(detail_id + is_empty=1 + location_code)应用层查重覆盖更新 @@ -2761,6 +2841,8 @@ class StockCheckService extends Service { const summary = await this._recalcCheckSummary(checkId); // 写入操作日志(失败不影响主流程) + // message 补充库位编码/库位ID(原 message 只有明细与数量,事后无法定位是哪个库位被上报), + // before_changes 落明细快照与本次上报字段,供追溯 await ctx.service.systems.operationLog.createOperationLog({ businessType: 'stock_check', businessId: checkId, @@ -2769,6 +2851,24 @@ class StockCheckService extends Service { changeSummary: normalizedIsEmpty ? `盘点作业上报:明细 ${detailRowId} 确认库位 ${locationCode || '未指定'} 为空` : `盘点作业上报:明细 ${detailRowId},库位 ${locationCode || '未指定'},实盘 ${quantityValue}${normalizedBarcode ? `,条码 ${normalizedBarcode}` : ''}(${mode === 'created' ? '新增' : '更新'})`, + beforeChanges: { + check_no: check.check_no, + detail_id: detailRowId, + scope_type: scopeType, + stock_id: normalizedStockId > 0 ? normalizedStockId : null, + location_code: locationCode || '', + location_id: locationId !== null && locationId !== undefined ? Number(locationId) : null, + detail_location_code: String(detail.location_code || '').trim() || null, + detail_location_id: detail.location_id !== null && detail.location_id !== undefined + ? Number(detail.location_id) + : null, + quantity: quantityValue, + barcode: normalizedBarcode, + is_unknown_goods: isUnknownGoods, + is_empty: normalizedIsEmpty, + mode, + record_id: Number(record && record.id) || null, + }, operator: { id: ctx.user?.employees_id || ctx.user?.id || '', name: ctx.user?.employees_name || '', @@ -2778,14 +2878,15 @@ class StockCheckService extends Service { checkNo: check.check_no, detailId: detailRowId, locationCode, + locationId: locationId !== null && locationId !== undefined ? Number(locationId) : null, quantity: quantityValue, barcode: normalizedBarcode, isUnknownGoods, is_empty: normalizedIsEmpty, mode, message: normalizedIsEmpty - ? `盘点作业上报:明细 ${detailRowId} 确认库位为空` - : `盘点作业上报:明细 ${detailRowId} 实盘 ${quantityValue}`, + ? `盘点作业上报:明细 ${detailRowId} 确认库位 ${locationCode || '未指定'}${locationId ? `(#${locationId})` : ''} 为空` + : `盘点作业上报:明细 ${detailRowId},库位 ${locationCode || '未指定'}${locationId ? `(#${locationId})` : ''},实盘 ${quantityValue}`, }, }); @@ -2914,7 +3015,7 @@ class StockCheckService extends Service { /** * 拉取盘点作业数据(视图由任务类型与 is_goods 驱动,view 入参已废弃忽略)。 * 视图解析规则: - * - 任务范围为库位(type=location/all):一律按库位视图(location)返回,无视 view/is_goods 入参; + * - 任务范围为库位(type=location):一律按库位视图(location)返回,无视 view/is_goods 入参; * - 任务范围为商品(type=goods/store):默认聚合库位视图(space);仅 is_goods=true 时按商品视图(goods)返回。 * 三视图行结构: * location=库位结构,以任务库位范围行(scope_type=location)为列表, @@ -2974,7 +3075,7 @@ class StockCheckService extends Service { // 商品范围任务默认 space(聚合库位),仅 is_goods=true 时 goods 视图 const normalizedType = String(check.type || '').trim(); const goodsViewRequested = isGoods === true || isGoods === 'true' || isGoods === 1; - const resolvedView = normalizedType === 'location' || normalizedType === 'all' + const resolvedView = normalizedType === 'location' ? 'location' : (goodsViewRequested ? 'goods' : 'space'); @@ -3064,7 +3165,7 @@ class StockCheckService extends Service { /** * 拉取盘点作业数据(space 视图分页版)。 - * 行结构与 workData space 视图行一致(id=库位ID/space_code/custom_barcode/custom_name/goods), + * 行结构与 workData space 视图行一致(id=库位ID/location_id 同义库位ID/space_code/custom_barcode/custom_name/goods), * 商品任务(scope_type=goods)按库位聚合;传入 location_id 时只返回该库位行(total=1), * 不传时按分页返回全部库位行。 * @@ -3315,11 +3416,14 @@ class StockCheckService extends Service { } } + const rowLocationId = detailRow.location_id !== null && detailRow.location_id !== undefined + ? Number(detailRow.location_id) + : null; return { detail_id: detailId, - location_id: detailRow.location_id !== null && detailRow.location_id !== undefined - ? detailRow.location_id - : null, + location_id: rowLocationId, + // space_id 为 location_id 的同义字段,供调用方直接回传 stock.check.report + space_id: rowLocationId, location_code: locationCode, location_name: locationName, status: detailRecords.length > 0 ? 'checked' : 'unchecked', @@ -3449,6 +3553,42 @@ class StockCheckService extends Service { } const spaceCodeByStockMap = new Map(); const spaceQuantityByStockMap = new Map(); + // 库位编码 → 有效库位ID(同编码多条时取拣货顺序第一条):供 goods 视图 locations[] 回传 location_id, + // 让调用方能直接把库位ID回传 stock.check.report(否则只有编码,服务端只能按编码猜库位) + const spaceIdByCodeMap = new Map(); + for (const row of sortedSpaceRows) { + const spaceCode = String(row.space_code || '').trim(); + if (spaceCode && !spaceIdByCodeMap.has(spaceCode)) { + spaceIdByCodeMap.set(spaceCode, Number(row.id)); + } + } + // 已盘库位(当前库存已无该商品)补查有效库位ID,口径与 workData space 视图一致(zone 存在未删除) + const uncoveredRecordCodes = [ ...new Set(records + .map(record => String(record.location_code || '').trim()) + .filter(code => code && !spaceIdByCodeMap.has(code))) ]; + if (uncoveredRecordCodes.length > 0) { + const uncoveredRows = await ctx.model.LocationSpace.findAll({ + where: { + warehouse_id: Number(warehouseId), + space_code: { [Op.in]: uncoveredRecordCodes }, + }, + attributes: [ 'id', 'space_code' ], + include: [{ + model: ctx.model.LocationZone, + as: 'zone', + attributes: [], + required: true, + }], + order: [[ 'id', 'ASC' ]], + raw: true, + }); + for (const row of uncoveredRows) { + const spaceCode = String(row.space_code || '').trim(); + if (spaceCode && !spaceIdByCodeMap.has(spaceCode)) { + spaceIdByCodeMap.set(spaceCode, Number(row.id)); + } + } + } for (const [ stockId, spaceIds ] of stockSpaceIdsMap.entries()) { const spaceRowMap = new Map(sortedSpaceRows.map(row => [ Number(row.id), row ])); const orderedRows = spaceIds @@ -3551,7 +3691,12 @@ class StockCheckService extends Service { } const buildLocationItem = (code, group) => { + const locationIdValue = (code && spaceIdByCodeMap.get(code)) || (group && group.location_id) || null; const locationItem = { + // 库位ID(wms_location_space.id):优先有效库位行,其次作业记录回填值; + // space_id 供调用方直接回传 stock.check.report(location_id 为兼容别名) + location_id: locationIdValue, + space_id: locationIdValue, location_code: code || null, checked_at: group ? group.checked_at : null, checker_name: group ? group.checker_name : null, @@ -3596,13 +3741,15 @@ class StockCheckService extends Service { /** * 构建 space 视图行:以任务商品(scope_type=goods 的 stock_id 集合)所在的库位为列表。 - * 库位集合取 wms_storage(warehouse_id + stock_id 在集合内 + is_enabled=1 且未删除,DISTINCT space_id), + * 库位集合取 wms_storage(warehouse_id + stock_id 在集合内 + is_enabled=1 且未删除,DISTINCT space_id) + * ∪ 作业记录库位(上报库位与明细库位编码一致时归并到明细固化 location_id, + * 无头库位归并到同编码有效库位,避免同编码出现重复行), * 库位仅按拣货顺序排序:pick_sequence 升序(pick_priority/库位 id 不参与排序, * 同值保持库位查询顺序); * 行内 goods 为该库位下的任务商品:明盘含 system_quantity(wms_storage space+stock * SUM(available_quantity+locked_quantity))、locked_quantity(wms_storage space+stock SUM(locked_quantity)) * 与 checked_quantity(该商品在该库位的实盘合计),盲盘不返回任何数量字段; - * status 已盘口径:该 (detail_id, location_code) 存在作业记录; + * status 已盘口径:该 (库位, 商品) 存在作业记录(兼容按明细 + 库位编码命中); * 未在 wms_storage 有库位的商品不入列表(无库位可聚)。 * * @param {number} warehouseId 仓库ID。 @@ -3647,6 +3794,11 @@ class StockCheckService extends Service { .filter(storeId => Number.isInteger(storeId) && storeId > 0); const storeNameMap = await this._resolveStoreNameMap(storeIds, warehouseId); const detailByStockId = new Map(detailRows.map(row => [ Number(row.stock_id), row ])); + const detailById = new Map(detailRows.map(row => [ Number(row.id), row ])); + // 明细按「库位 + 商品」索引:同一商品分布在多个库位时,库位行应取本库位对应的明细 + const detailByStockSpace = new Map( + detailRows.map(row => [ `${Number(row.location_id)}_${Number(row.stock_id)}`, row ]) + ); // 任务商品所在库位:wms_storage(warehouse + stock_id 在集合 + 启用未删除)DISTINCT space_id, // 同时按 (space_id, stock_id) 汇总账面数量(口径=可用+锁定)与锁定数量 @@ -3667,12 +3819,101 @@ class StockCheckService extends Service { group: [ 'space_id', 'stock_id' ], raw: true, }); + // 记录库位归一:上报库位与明细库位编码一致时以明细固化库位为准, + // 避免同仓库同编码存在多条库位(历史重复库位/无头库位)时同一编码在视图里出现两行 + const recordSpaceIdMap = new Map(); + for (const record of records) { + const recordCode = String(record.location_code || '').trim(); + const recordDetail = detailById.get(Number(record.detail_id)); + const detailLocationCode = recordDetail ? String(recordDetail.location_code || '').trim() : ''; + const detailLocationId = recordDetail ? Number(recordDetail.location_id) || 0 : 0; + const recordSpaceId = recordCode && detailLocationCode === recordCode && detailLocationId > 0 + ? detailLocationId + : Number(record.location_id) || 0; + recordSpaceIdMap.set(Number(record.id), recordSpaceId); + } + + // 无头库位(分区不存在/已删除)不直接入视图:同仓库同编码多条库位时会出现自定义字段为空的幽灵行, + // 统一归并到同编码的有效库位(优先该商品有启用库存的库位,其次 ID 最小) + const recordSpaceIdList = [ ...new Set([ ...recordSpaceIdMap.values() ].filter(spaceId => spaceId > 0)) ]; + if (recordSpaceIdList.length > 0) { + const validRecordSpaceRows = await ctx.model.LocationSpace.findAll({ + where: { id: { [Op.in]: recordSpaceIdList } }, + attributes: [ 'id' ], + include: [{ + model: ctx.model.LocationZone, + as: 'zone', + attributes: [], + required: true, + }], + raw: true, + }); + const validRecordSpaceIdSet = new Set(validRecordSpaceRows.map(row => Number(row.id))); + const invalidRecordSpaceIds = recordSpaceIdList.filter(spaceId => !validRecordSpaceIdSet.has(spaceId)); + if (invalidRecordSpaceIds.length > 0) { + const invalidRows = await ctx.model.LocationSpace.findAll({ + where: { id: { [Op.in]: invalidRecordSpaceIds } }, + attributes: [ 'id', 'space_code' ], + raw: true, + }); + const invalidSpaceCodeMap = new Map( + invalidRows.map(row => [ Number(row.id), String(row.space_code || '').trim() ]) + ); + const fallbackCodes = [ ...new Set([ ...invalidSpaceCodeMap.values() ].filter(Boolean)) ]; + const fallbackRows = fallbackCodes.length === 0 ? [] : await ctx.model.LocationSpace.findAll({ + where: { + warehouse_id: Number(warehouseId), + space_code: { [Op.in]: fallbackCodes }, + }, + attributes: [ 'id', 'space_code' ], + include: [{ + model: ctx.model.LocationZone, + as: 'zone', + attributes: [], + required: true, + }], + order: [[ 'id', 'ASC' ]], + raw: true, + }); + const fallbackIdsByCode = new Map(); + for (const row of fallbackRows) { + const code = String(row.space_code || '').trim(); + if (!fallbackIdsByCode.has(code)) { + fallbackIdsByCode.set(code, []); + } + fallbackIdsByCode.get(code).push(Number(row.id)); + } + const storageKeySet = new Set( + storageRows.map(row => `${Number(row.space_id)}_${Number(row.stock_id)}`) + ); + for (const record of records) { + const recordId = Number(record.id); + const currentSpaceId = recordSpaceIdMap.get(recordId) || 0; + if (!invalidRecordSpaceIds.includes(currentSpaceId)) { + continue; + } + const code = invalidSpaceCodeMap.get(currentSpaceId) + || String(record.location_code || '').trim(); + const candidates = fallbackIdsByCode.get(code) || []; + if (candidates.length === 0) { + continue; + } + const recordStockId = Number(record.stock_id) || 0; + const stockHit = recordStockId > 0 + ? candidates.find(spaceId => storageKeySet.has(`${spaceId}_${recordStockId}`)) + : 0; + recordSpaceIdMap.set(recordId, stockHit || candidates[0]); + } + } + } + // 作业记录库位:优先已回填 location_id;未回填的按库位编码匹配 wms_location_space 补查, - // 保证商品库存已无记录时(如盘点前库存已出空)space 视图仍能展示已盘库位行。 + // 保证商品库存已无记录时(如盘点前库存已出空)space 视图仍能展示已盘库位行 + // (编码一致时已在上面归并到明细固化库位)。 const recordSpaceIds = []; const recordLocationCodes = []; for (const record of records) { - const recordSpaceId = Number(record.location_id) || 0; + const recordSpaceId = recordSpaceIdMap.get(Number(record.id)) || 0; if (recordSpaceId > 0) { if (!recordSpaceIds.includes(recordSpaceId)) { recordSpaceIds.push(recordSpaceId); @@ -3759,10 +4000,12 @@ class StockCheckService extends Service { codeMatchedLocationRows.map(row => [ String(row.space_code || '').trim(), Number(row.id) ]) ); const recordsByDetailSpace = new Map(); + // 记录按「库位 + 商品」归集:跨明细上报(记录明细与库位不一致)时仍能命中对应库位行 + const recordsBySpaceStock = new Map(); // 仅记录库位(当前库存无该商品)按库位归集记录,供 space 视图补行 const recordsBySpace = new Map(); for (const record of records) { - let spaceId = Number(record.location_id) || 0; + let spaceId = recordSpaceIdMap.get(Number(record.id)) || 0; if (!spaceId) { spaceId = codeToSpaceIdMap.get(String(record.location_code || '').trim()) || 0; } @@ -3776,6 +4019,15 @@ class StockCheckService extends Service { } recordsByDetailSpace.get(detailSpaceKey).push(record); + const recordStockId = Number(record.stock_id) || 0; + if (recordStockId > 0) { + const spaceStockKey = `${spaceId}_${recordStockId}`; + if (!recordsBySpaceStock.has(spaceStockKey)) { + recordsBySpaceStock.set(spaceStockKey, []); + } + recordsBySpaceStock.get(spaceStockKey).push(record); + } + if (!recordsBySpace.has(spaceId)) { recordsBySpace.set(spaceId, []); } @@ -3800,7 +4052,7 @@ class StockCheckService extends Service { .sort((left, right) => Number(left.stock_id) - Number(right.stock_id)) .map(storageRow => { const stockId = Number(storageRow.stock_id); - const detailRow = detailByStockId.get(stockId); + const detailRow = detailByStockSpace.get(`${spaceId}_${stockId}`) || detailByStockId.get(stockId); if (!detailRow) { return null; } @@ -3808,7 +4060,8 @@ class StockCheckService extends Service { const barcodes = Array.isArray(stockDetail.barcodes) ? stockDetail.barcodes : []; const storeId = stockDetail.store_id != null ? Number(stockDetail.store_id) : null; const detailId = Number(detailRow.id); - const locationRecords = recordsByDetailSpace.get(`${detailId}_${spaceId}`) + const locationRecords = recordsBySpaceStock.get(`${spaceId}_${stockId}`) + || recordsByDetailSpace.get(`${detailId}_${spaceId}`) || recordsByDetailLocation.get(`${detailId}_${spaceCode}`) || []; // 作业照片与记录ID(供前端展示与编辑/移除记录) @@ -3849,8 +4102,11 @@ class StockCheckService extends Service { .filter(item => item !== null); return { - // 库位字段对齐库位查询惯例(index.searchSpace:id/space_code/custom_barcode/custom_name) + // 库位字段对齐库位查询惯例(index.searchSpace:id/space_code/custom_barcode/custom_name); + // location_id / space_id 均为 id 的同义字段,上报 stock.check.report 时以 space_id 必传 id: spaceId, + location_id: spaceId, + space_id: spaceId, space_code: spaceCode || null, custom_barcode: locationRow.custom_barcode != null && String(locationRow.custom_barcode).trim() !== '' ? String(locationRow.custom_barcode).trim() @@ -3982,7 +4238,7 @@ class StockCheckService extends Service { /** * 重盘清除库位(按库位清除盘点信息,库位盘点模式专属)。 * 传入任务ID与库位ID,清除该库位范围内明细的全部作业记录(含空库位标记), - * 该库位回到未盘状态;仅任务范围为库位(type=location/all)且状态 approved/checking 时允许; + * 该库位回到未盘状态;仅任务范围为库位(type=location)且状态 approved/checking 时允许; * 删除后重算 checked_items/diff_items/detail_status,主表状态不回退; * 同时清理被删记录的图片引用(失败仅告警不影响主流程)。 * @@ -4015,7 +4271,7 @@ class StockCheckService extends Service { throw this.createBusinessError(`当前状态(${check.status})不允许清除库位盘点信息`); } const normalizedType = String(check.type || '').trim(); - if (normalizedType !== 'location' && normalizedType !== 'all') { + if (normalizedType !== 'location') { throw this.createBusinessError('仅库位盘点任务支持重盘清除库位'); } @@ -5091,10 +5347,23 @@ class StockCheckService extends Service { raw: true, }); for (const spaceRow of spaceRows) { - locationDisplayMap.set(String(spaceRow.space_code || '').trim(), { + const code = String(spaceRow.space_code || '').trim(); + if (!code) { + continue; + } + const candidate = { custom_name: String(spaceRow.custom_name || '').trim(), custom_barcode: String(spaceRow.custom_barcode || '').trim(), - }); + }; + // 同仓库同编码可能有多条库位(历史重复/无头库位):优先保留有自定义名称的行, + // 避免空值行后写覆盖,导致导出回退成库位编码 + const existing = locationDisplayMap.get(code); + const shouldReplace = !existing + || (!existing.custom_name && candidate.custom_name) + || (!existing.custom_name && !candidate.custom_name && candidate.custom_barcode); + if (shouldReplace) { + locationDisplayMap.set(code, candidate); + } } } diff --git a/methods/changes/system.json b/methods/changes/system.json index d626f7d..73a3634 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,73 @@ [ + { + "version": "0.3.308", + "date": "2026-10-27", + "type": "updated", + "summary": "库存盘点移除范围类型 all(与 location 语义重复):全盘能力(未传库位时自动拉取全仓库启用库位)并入 location,type 缺省值改为 location,create 传 all 返回 400;存量 type=all 任务由迁移收敛(商品行任务改 goods、库位行/空任务改 location 并归一盲盘)。", + "methods": [ + "stock.check.create", + "stock.check.list", + "stock.check.addDetail", + "stock.check.workData", + "stock.check.markEmpty", + "stock.check.recheckClearLocation" + ], + "notes": [ + "动机:type=all 与 type=location 语义完全重复——两者都按库位盘点、明细都是 scope_type=location、mode 都被强制 blind;all 唯一的额外能力「添加明细时未传库位自动拉取全仓库启用库位」已合并进 location,all 因此下线。", + "create:type 仅允许 store/goods/location,缺省由 all 改为 location;传 all 返回 400「盘点范围类型不合法,仅支持 store/goods/location」。mode 规则不变——location 一律盲盘(忽略传入),store/goods 按传入值(缺省明盘)。", + "addDetail:type=location 未传 locations 且未传 location_ids 时自动拉取当前仓库全部启用且有效库位(排除无头库位)生成库位行(原 all 全盘语义);type=all 的历史任务不再走「已有商品明细行则按商品模式」兼容分支,直接返回 400「盘点范围类型不合法(all)」。", + "存量数据:database/migrations/20261027010000-merge-stock-check-type-all-into-location.js 将明细含商品行(scope_type=goods,2026-09-30 改造前的全仓按商品口径)的 type=all 任务改为 type=goods(mode 保持原值),其余(明细为库位行或无明细的空任务)改为 type=location 并归一 mode=blind;wms_stock_check.type 列默认值改为 location、注释去掉 all。", + "影响面:前端传 type=all 的创建调用将收到 400,需改为 location(需要全盘时创建 location 任务后调用 addDetail 不传库位即可)。workData/markEmpty/recheckClearLocation 等按库位判定的接口仍只认 type=location(历史 all 任务经迁移后即为 location)。", + "测试:test/app/service/systems/stock_check.test.js 改为 location 口径——新增「type=all 创建报 400」「历史 type=all 任务添加明细报 400」用例;原「type=all 缺省库位自动全仓」用例改由 type=location 承接;移除 type=all 历史商品明细兼容用例。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.create/list/addDetail/workData/markEmpty/recheckClearLocation(type 语义、mode 规则、全盘自动范围、错误文案);根版本 0.3.307 → 0.3.308、updatedAt 2026-10-27;methods/changes/system.json 新增本条(插入数组首位);未改动其它分组。", + "破坏性提示:type=all 不再是合法入参(400);依赖「all 缺省自动全仓」的调用改为 location 即可,行为一致。", + "代码依据:app/service/systems/stock_check.js#create/#addDetail/#workData/#markEmpty/#recheckClearLocation、app/service/systemMethods/stock/check.js、app/model/stock_check.js、database/migrations/20261027010000-merge-stock-check-type-all-into-location.js。" + ] + }, + { + "version": "0.3.307", + "date": "2026-10-25", + "type": "updated", + "summary": "库存盘点上报(stock.check.report)改为 space_id 必传:库位一律按库位ID落库、不再按编码猜库位(修复同仓库同编码重复库位导致作业记录挂到无头脏库位);实盘数量上限 2147483647 返回 400;取回接口补充 space_id/location_id 字段供回传;操作日志 message/before_changes 补充库位编码与库位ID。", + "methods": [ + "stock.check.report", + "stock.check.workData" + ], + "notes": [ + "问题现象:生产盘点单 PD20261025000001 的 stock.check.workData space 视图出现 custom_name/custom_barcode 为 null 的库位行(如 E02-06-01-01)。根因:wms_location_space 存在大量同仓库同编码重复库位(uk_warehouse_space_code 含 deleted_at,NULL 不去重导致重复插入不受约束),其中大量库位所属 zone 已删除(无头库位);report 旧逻辑只按 warehouse_id + space_code 做 findOne,命中最小的历史行,导致作业记录挂到脏库位,space 视图再按记录库位补行时又未做分区有效性过滤。", + "取回侧字段(本次补齐):workData/workDataSpaceDetails 的 space 视图行新增 space_id 与 location_id(与既有 id 同值);goods 视图 locations[] 新增 space_id 与 location_id(取分区有效库位行,同编码多条取拣货顺序第一条,已盘但无库存的库位按编码补查有效库位)。location 视图/recordList/result 的 location_id 保持不变。", + "report 写库(本次修正为强制):space_id 必传(兼容 spaceId/location_id/locationId 写法,取回接口 rows[].space_id、rows[].id、locations[].space_id 可直接回传);服务端校验属于本仓库且 zone 存在未删除,缺失/非法返回 400「缺少库位ID(space_id)」,不存在/跨仓库/分区已删除返回 400;库位编码以 space_id 对应库位行为准,location 入参降级为可选一致性校验(不一致 400),服务端不再按编码匹配/猜库位;库位明细行还要求 space_id 对应编码等于明细库位编码。", + "report 校验:实盘数量新增上限 2147483647(wms_stock_check_record.quantity 为 int(12)),超限返回 400「实盘数量不能超过 2147483647」;此前超限直接落库抛 Out of range 变 500(生产今日 10 次)。", + "workData space 视图:记录库位归一(上报编码与明细编码一致归并到明细固化 location_id;记录指向无头库位时归并到同编码有效库位),库位商品明细改按「库位+商品」索引、作业记录改按「库位+商品」聚合,避免跨库位上报时同一编码出现两行或实盘数落到别的行。", + "操作日志:STOCK_CHECK_REPORT 的 message 追加库位编码与库位ID;before_changes 落 check_no/detail_id/scope_type/stock_id/location_code/location_id/detail_location_code/detail_location_id/quantity/barcode/is_unknown_goods/is_empty/mode/record_id 快照(原 changeSummary 参数在 operationLog.buildOperationLogData 中未落库,日志里查不到库位信息)。", + "问题定位依据(只读核查):生产 wms-api.log 中 244 条 stock.check.report 请求 body 键仅 id/detail_id/quantity/location/stock_id,无 space_id;detail 6151 于 2026-10-25 22:55:36 上报 location=E02-06-01-01(明细库位为 E02-06-02-01),落库 location_id=13768(zone 59 已删除);有效行为 22093(E1区02-06-01/00224214)。", + "测试:test/app/service/systems/stock_check.test.js 升级为 space_id 必传口径——新增/改写用例覆盖「同编码重复库位不产生幽灵行」「space_id 必传与缺失/非法/跨仓库/无头/编码不一致 400」「数量超限 400 且不落库」「操作日志含库位信息」「space 视图行 space_id=id」「goods 视图 locations[] 含 space_id」,全量 244 通过。", + "文档变更范围:methods/system.json 的 stock.check.report(space_id 必填参数、location 降级为一致性校验、quantity 上限)、stock.check.workData / stock.check.workDataSpaceDetails(space 视图行含 id/space_id/location_id、goods locations[] 含 space_id)+根版本 0.3.306 → 0.3.307、updatedAt 2026-10-25;methods/changes/system.json 新增本条(插入数组首位)。", + "破坏性提示:旧调用方(未传 space_id)将收到 400「缺少库位ID(space_id)」,前端需改为回传取回接口返回的 space_id;「无库位上报」通道随之取消(历史 location_code='' 记录仍按既有口径展示/导出为空)。", + "代码依据:app/service/systems/stock_check.js#_resolveLocationIdByCode/#report/#_buildSpaceWorkRows、app/service/systemMethods/stock/check.js#report。" + ] + }, + { + "version": "0.3.306", + "date": "2026-10-25", + "type": "added", + "summary": "用户账号能力增强:user.getAccountInfo 返回新增 is_custom_password;新增 user.updateUsername(服务端重名校验并排除自己)与 user.changePassword(首次自定义密码可免旧密码,修改后置 is_custom_password=1,再次修改必须校验旧密码)。", + "methods": [ + "user.getAccountInfo", + "user.updateUsername", + "user.changePassword" + ], + "notes": [ + "user.getAccountInfo:返回字段白名单新增 is_custom_password(是否自定义密码:0-否,1-是),仍不返回 password_hash、salt、last_login_ip。", + "user.updateUsername:新增方法,仅修改当前登录账号;username 必填,长度3-50且仅允许字母/数字/下划线;服务端查询 username 重名时排除自己(id != 当前账号),重名返回 409;用户名未变化直接返回成功;更新后清理用户缓存,并同步当前请求上下文 username。", + "user.changePassword:新增方法,入参 new_password 必填(兼容 newPassword),old_password 兼容 oldPassword;is_custom_password=0 时旧密码可不传,is_custom_password=1 时必须传且校验通过;修改时重新生成 salt 与 password_hash,并将 is_custom_password 置为1;方法已加入 _noNeedLog,避免请求体中的明文密码写入操作日志。", + "错误码:updateUsername 400(参数/格式)/401(未登录)/404(账号不存在)/409(用户名已存在);changePassword 400(新密码为空、请输入旧密码、旧密码错误)/401/404;数据库异常返回 code=0。", + "数据库:依赖迁移 20261025135000-add-is-custom-password-to-wms-account.js(wms_account.is_custom_password TINYINT(1) NOT NULL DEFAULT 0),开发库与生产库均已执行。", + "测试:test/app/service/systemMethods/user.getAccountInfo.test.js(5)、user.updateUsername.test.js(7)、user.changePassword.test.js(8),合计 20 通过。", + "文档变更范围:methods/system.json 的 user.getAccountInfo(response 新增 is_custom_password)、user.updateUsername(新增)、user.changePassword(新增)+根版本 0.3.305 → 0.3.306、updatedAt 2026-10-25;方法文档已写入开发库 wms_api_method_doc 并重新导出;methods/changes/system.json 新增本条(插入数组首位)。", + "代码依据:app/service/systemMethods/user.js#updateUsername/#changePassword、app/service/systems/auth/user.js#updateUsername/#changePassword、app/service/systems/auth/user.js#getAccountInfo。" + ] + }, { "version": "0.3.305", "date": "2026-10-25", @@ -12486,5 +12555,23 @@ "测试:test/app/service/systemMethods/order/wave.wavePickTaskList.test.js 补充 cart_code 操作符/默认模糊/顶层优先/keyword 覆盖用例,并修复原 mock 缺失 QueryTypes.SELECT 导致的既有用例失败。" ], "module": "order" + }, + { + "version": "2026.10.26-index.getShopExpressList-productTypes", + "date": "2026-10-26", + "type": "updated", + "summary": "index.getShopExpressList 返回的 list 每项新增 product_types 字段:[{ name, code }],按 sys_express_code 匹配 wms_express_product_type 得到,未匹配时为空数组;PDD 平台不补充该字段。", + "methods": [ + "index.getShopExpressList" + ], + "notes": [ + "适用范围:仅 PDD 以外的平台(CAINIAO/DY/KS/SPH/XHS/JD 等)补充 product_types,PDD 平台保持原有返回结构不变。", + "匹配规则:list 项 sys_express_code 与 wms_express_product_type.express_code 比较(trim + 大写,不区分大小写),同一 express_code 下按 code 去重;name 为空时回退为 code。", + "数据来源与缓存:复用系统快递服务 getExpressProductTypeList 的全量缓存(缓存键 express:product-type:list,TTL 1 小时),缓存失效由 upsertExpressProductTypeList 在新增/更新产品类型后清理,接口不再额外直连数据库。", + "容错:产品类型读取异常时仅记录 warn 日志,list 各项目 product_types 返回空数组,不影响电子面单签约列表主流程。", + "JD 平台在 sys_express_code 补偿映射完成后再补充 product_types,与最终返回的 sys_express_code 一致。", + "代码变更:app/service/systemMethods/index.js 新增 buildExpressProductTypeMap 与 attachExpressProductTypes,getShopExpressList 在返回前按平台补充字段(PDD 跳过、不读取产品类型缓存);methods/system.json 同步 data.list 说明与 product_types 子字段文档。" + ], + "module": "index" } ] diff --git a/methods/system.json b/methods/system.json index 17d10da..90742ff 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.305", - "updatedAt": "2026-10-25", + "version": "0.3.308", + "updatedAt": "2026-10-27", "headers": [ { "name": "platform", @@ -1804,7 +1804,7 @@ "name": "data.list", "type": "array", "required": true, - "description": "服务端按店铺所属平台拉取并统一收敛后的快递签约/电子面单可用列表;未接入的平台返回空数组。", + "description": "服务端按店铺所属平台拉取并统一收敛后的快递签约/电子面单可用列表;未接入的平台返回空数组。非 PDD 平台的每条记录会按 sys_express_code 匹配 wms_express_product_type 补充 product_types 字段,PDD 平台不返回该字段。", "children": [ { "name": "wp_code", @@ -1824,6 +1824,26 @@ "required": true, "description": "系统快递编码;由平台快递编码 wp_code 映射得到,未匹配到时返回空字符串。" }, + { + "name": "product_types", + "type": "array", + "required": true, + "description": "系统快递对应的产品类型列表(仅非 PDD 平台返回);按 sys_express_code 与 wms_express_product_type.express_code 匹配(不区分大小写),数据经系统快递服务缓存读取,未匹配到时返回空数组;PDD 平台不返回该字段。", + "children": [ + { + "name": "name", + "type": "string", + "required": true, + "description": "产品类型名称;为空时回退为 code。" + }, + { + "name": "code", + "type": "string", + "required": true, + "description": "产品类型编码。" + } + ] + }, { "name": "wp_type", "type": "string", @@ -31306,6 +31326,12 @@ "required": true, "description": "状态:0-禁用,1-启用,2-离职" }, + { + "name": "is_custom_password", + "type": "number", + "required": true, + "description": "是否自定义密码:0-否,1-是" + }, { "name": "last_login_at", "type": "string", @@ -31362,6 +31388,113 @@ "params": [], "response": [], "errors": [] + }, + { + "method": "user.updateUsername", + "description": "修改当前登录账号的用户名;服务端做重名校验(排除自己),重名返回 409;用户名只允许字母、数字、下划线,长度3-50", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "******" + } + ], + "params": [ + { + "name": "username", + "type": "string", + "required": true, + "source": "body", + "description": "新用户名(3-50位,仅字母、数字、下划线)" + } + ], + "response": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "账号ID" + }, + { + "name": "username", + "type": "string", + "required": true, + "description": "修改后的用户名" + } + ], + "errors": [ + { + "code": 400, + "message": "username 不能为空或格式不正确(3-50位,仅字母、数字、下划线)" + }, + { + "code": 401, + "message": "未登录或登录已过期" + }, + { + "code": 404, + "message": "账号不存在" + }, + { + "code": 409, + "message": "用户名已存在" + } + ] + }, + { + "method": "user.changePassword", + "description": "修改当前登录账号密码;is_custom_password=0(未自定义过密码)时旧密码可不传,修改成功后将 is_custom_password 置为1;已自定义过密码后再次修改必须传旧密码校验", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "******" + } + ], + "params": [ + { + "name": "old_password", + "type": "string", + "required": false, + "source": "body", + "description": "旧密码;is_custom_password=1 时必填(兼容 oldPassword)" + }, + { + "name": "new_password", + "type": "string", + "required": true, + "source": "body", + "description": "新密码(去除首尾空格,最长64位;兼容 newPassword)" + } + ], + "response": [ + { + "name": "is_custom_password", + "type": "number", + "required": true, + "description": "是否自定义密码,修改成功后恒为1" + } + ], + "errors": [ + { + "code": 400, + "message": "新密码不能为空 / 请输入旧密码 / 旧密码错误" + }, + { + "code": 401, + "message": "未登录或登录已过期" + }, + { + "code": 404, + "message": "账号不存在" + } + ] } ] }, @@ -38167,7 +38300,7 @@ "list": [ { "method": "stock.check.create", - "description": "创建盘点任务(空任务):生成盘点单号(PD+YYYYMMDD+6位序号,序号全局递增(不按仓库隔离),并发下撞 uk_check_no 唯一键自动重取重试(最多 5 次),口径与收货单 receiving_number 一致),初始状态 created、明细进度 none_checked;warehouse_id 由服务端从当前登录上下文(ctx.user.store_id)自动注入,前端无需传递。盘点范围类型语义:all=按库位盘点(添加明细时未传库位自动拉取全仓库启用库位生成范围)/ location=按库位盘点 / store=按货主按商品盘点(必须指定货主)/ goods=按商品盘点;type=all/location 时明细为库位行(scope_type=location),type=store/goods 时明细为商品行(scope_type=goods)。盘点时间不传(主表已无 check_date):start_time=盘点开始时间(第一个盘点明细写入的时间,report 首次写入明细时补写)、end_time=盘点结束时间(完成盘点的时间,finish 时写入),与 patternCreate 口径一致。", + "description": "创建盘点任务(空任务):生成盘点单号(PD+YYYYMMDD+6位序号,序号全局递增(不按仓库隔离),并发下撞 uk_check_no 唯一键自动重取重试(最多 5 次),口径与收货单 receiving_number 一致),初始状态 created、明细进度 none_checked;warehouse_id 由服务端从当前登录上下文(ctx.user.store_id)自动注入,前端无需传递。盘点范围类型语义:location=按库位盘点(添加明细时未传库位自动拉取全仓库启用库位生成范围,原 all 全盘语义已并入)/ store=按货主按商品盘点(必须指定货主)/ goods=按商品盘点,缺省 location;type=location 时明细为库位行(scope_type=location),type=store/goods 时明细为商品行(scope_type=goods);type=all 已下线(与 location 语义重复),传入返回 400。盘点时间不传(主表已无 check_date):start_time=盘点开始时间(第一个盘点明细写入的时间,report 首次写入明细时补写)、end_time=盘点结束时间(完成盘点的时间,finish 时写入),与 patternCreate 口径一致。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -38191,14 +38324,14 @@ "type": "string", "required": false, "source": "body", - "description": "盘点范围类型,缺省 all:all=按库位盘点(未传库位时自动全仓库启用库位生成盘点范围)/ location=按库位盘点 / store=按货主按商品盘点 / goods=按商品盘点;all/location 走库位明细行(scope_type=location),store/goods 走商品明细行(scope_type=goods)" + "description": "盘点范围类型,缺省 location:location=按库位盘点(未传库位时自动全仓库启用库位生成盘点范围)/ store=按货主按商品盘点 / goods=按商品盘点;location 走库位明细行(scope_type=location),store/goods 走商品明细行(scope_type=goods);all 已下线(与 location 语义重复),传入返回 400" }, { "name": "mode", "type": "string", "required": false, "source": "body", - "description": "盘点方式,缺省 open:open=明盘(可见账面数量)/ blind=盲盘(不可见账面数量);按库位盘点(all/location)一律盲盘,忽略前端传入;按商品盘点(store/goods)按传入值(默认明盘)" + "description": "盘点方式,缺省 open:open=明盘(可见账面数量)/ blind=盲盘(不可见账面数量);按库位盘点(location)一律盲盘,忽略前端传入;按商品盘点(store/goods)按传入值(默认明盘)" }, { "name": "store_id", @@ -38262,7 +38395,7 @@ "name": "type", "type": "string", "required": true, - "description": "盘点范围类型:all/store/goods/location" + "description": "盘点范围类型:location/store/goods" }, { "name": "mode", @@ -38360,7 +38493,7 @@ "errors": [ { "code": 400, - "message": "无法获取当前仓库上下文 / 盘点范围类型不合法(仅支持 all/store/goods/location)/ 盘点方式不合法(仅支持 open/blind)/ 按货主盘点时必须指定货主" + "message": "无法获取当前仓库上下文 / 盘点范围类型不合法(仅支持 store/goods/location)/ 盘点方式不合法(仅支持 open/blind)/ 按货主盘点时必须指定货主" }, { "code": 500, @@ -38372,10 +38505,10 @@ "原因说明:uk_check_no 为全局唯一索引(不区分仓库),原按仓库隔离序号各自从 1 起会跨仓撞号;改为全局递增后并发创建仍有极小概率撞号,由唯一键重试兜底。", "收货单参照口径:与收货单 receiving_number 一致——按全局最大序号 +1 生成 + 撞唯一键自动重取重试。", "并发重试说明:每次重试都重新调用 generateCheckNo() 取最新全局最大序号;仅 ER_DUP_ENTRY 且命中 uk_check_no 的错误才重试,其它错误不重试直接抛出。", - "范围类型语义:type=all/location 为按库位盘点(明细为库位行 scope_type=location,all 未传库位时自动全仓库启用库位生成范围);type=store/goods 为按商品盘点(明细为商品行 scope_type=goods,store 必须指定货主)。", + "范围类型语义:type=location 为按库位盘点(明细为库位行 scope_type=location,未传库位时自动全仓库启用库位生成范围,原 all 全盘语义已并入);type=all 已下线(与 location 语义重复),create 传入返回 400;type=store/goods 为按商品盘点(明细为商品行 scope_type=goods,store 必须指定货主)。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.create/addDetail/report/detail/finish/export 六条(范围类型语义与库位行支持);根版本 0.3.205 → 0.3.206、updatedAt 保持 2026-09-30;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库与生产库(import 当前 system.json → export 回写往返校验),保持库与文件一致。", - "盘点方式规则:按库位盘点(type=all/location,明细为库位行)一律盲盘(blind),忽略前端传入的 mode;按商品盘点(type=store/goods,明细为商品行)按传入值,默认明盘(open)。代码依据:app/service/systems/stock_check.js#create 在 mode 合法性校验(仅支持 open/blind)通过后、写库前,normalizedType 为 all/location 时强制 normalizedMode='blind'。", + "盘点方式规则:按库位盘点(type=location,明细为库位行)一律盲盘(blind),忽略前端传入的 mode;按商品盘点(type=store/goods,明细为商品行)按传入值,默认明盘(open)。代码依据:app/service/systems/stock_check.js#create 在 mode 合法性校验(仅支持 open/blind)通过后、写库前,normalizedType 为 location 时强制 normalizedMode='blind'。", "盘点时间口径(主表无 check_date):create 不写盘点时间(入参与主表均无 check_date,迁移 20260930150000-remove-check-date-from-wms-stock-check.js 已移除字段与索引);start_time=盘点开始时间(第一个盘点明细写入的时间,report 首次写入明细时补写)、end_time=盘点结束时间(完成盘点的时间,finish 时写入);_formatCheckRow 不再返回 check_date(仅返回 start_time/end_time);代码依据:app/service/systems/stock_check.js#create(不再写 check_date)、#report(start_time 为空补写)、#finish(写 end_time)、#_formatCheckRow(仅返回 start_time/end_time)。", "响应统一 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)。" ] @@ -38413,7 +38546,7 @@ "type": "string", "required": false, "source": "body", - "description": "盘点范围类型筛选(单值或数组,自动去重):all=按库位盘点 / location=按库位盘点 / store=按货主按商品盘点 / goods=按商品盘点" + "description": "盘点范围类型筛选(单值或数组,自动去重):location=按库位盘点 / store=按货主按商品盘点 / goods=按商品盘点" }, { "name": "where.mode", @@ -38535,7 +38668,7 @@ }, { "method": "stock.check.addDetail", - "description": "添加盘点明细(商品或库位,按任务盘点类型决定):type=store/goods 按 stock_ids 添加商品行(scope_type=goods,商品任务必须按库位盘点:按商品在仓库的启用库存库位(wms_storage is_enabled=1 且库位有效——库位未删除且所属 zone 存在未删除,排除无头库位,按 space_id 分组 SUM)拆行——每个「商品+库位」生成一条明细行,location_id/location_code 快照绑定库存库位、system_quantity=该库位库存 SUM,一个商品多个库位对应多行;无启用库存库位的商品计入 invalid_stock_ids 不入明细),商品必须属于本仓库,且任务 store_id 非空时商品货主必须与任务货主一致(不一致的商品记入 invalid_stock_ids);type=all/location 按 locations(库位编码)或 location_ids(库位ID)添加库位行(scope_type=location),location_ids 优先(两者都传时 locations 忽略)——库位ID路径直接按 wms_location_space.id+warehouse_id 查库校验(不再按编码二次解析),查不到的 ID 记入 invalid_location_ids,编码路径按 warehouse_id+space_code 匹配 wms_location_space,不存在的编码记入 invalid_locations;库位必须有效(未删除且所属 zone 存在未删除):无头库位(zone 不存在/已删除)分别记入 invalid_location_ids / invalid_locations;type=all 未传库位且未传库位ID时自动拉取全仓库启用且有效库位(排除无头库位)生成盘点范围;兼容历史任务:type=all 且已存在商品明细行(scope_type=goods,改造前创建)时继续按商品模式接受 stock_ids,避免旧调用报 400;stock_ids 与 locations/location_ids 按任务类型二选一(传错维度报 400:按库位盘点传 stock_ids 报『当前盘点类型按库位盘点,请传 locations 或 location_ids(如需按商品盘点请创建 type=goods 任务)』,按商品盘点传 locations 报『当前盘点类型按商品盘点,请传 stock_ids』、传 location_ids 报『当前盘点类型按商品盘点,不能添加库位明细』),locations 兼容 location_codes 写法(locations 优先)、location_ids 兼容 locationIds 驼峰写法(location_ids 优先);仅 created/rejected 状态允许;已存在同盘点项(商品行 stock_id / 库位行 location_code)自动跳过(幂等);完成后重算主表 total_items。", + "description": "添加盘点明细(商品或库位,按任务盘点类型决定):type=store/goods 按 stock_ids 添加商品行(scope_type=goods,商品任务必须按库位盘点:按商品在仓库的启用库存库位(wms_storage is_enabled=1 且库位有效——库位未删除且所属 zone 存在未删除,排除无头库位,按 space_id 分组 SUM)拆行——每个「商品+库位」生成一条明细行,location_id/location_code 快照绑定库存库位、system_quantity=该库位库存 SUM,一个商品多个库位对应多行;无启用库存库位的商品计入 invalid_stock_ids 不入明细),商品必须属于本仓库,且任务 store_id 非空时商品货主必须与任务货主一致(不一致的商品记入 invalid_stock_ids);type=location 按 locations(库位编码)或 location_ids(库位ID)添加库位行(scope_type=location),location_ids 优先(两者都传时 locations 忽略)——库位ID路径直接按 wms_location_space.id+warehouse_id 查库校验(不再按编码二次解析),查不到的 ID 记入 invalid_location_ids,编码路径按 warehouse_id+space_code 匹配 wms_location_space,不存在的编码记入 invalid_locations;库位必须有效(未删除且所属 zone 存在未删除):无头库位(zone 不存在/已删除)分别记入 invalid_location_ids / invalid_locations;type=location 未传库位且未传库位ID时自动拉取全仓库启用且有效库位(排除无头库位)生成盘点范围(原 all 全盘语义);type=all 已下线(与 location 语义重复),传 all 的历史任务添加明细返回 400;stock_ids 与 locations/location_ids 按任务类型二选一(传错维度报 400:按库位盘点传 stock_ids 报『当前盘点类型按库位盘点,请传 locations 或 location_ids(如需按商品盘点请创建 type=goods 任务)』,按商品盘点传 locations 报『当前盘点类型按商品盘点,请传 stock_ids』、传 location_ids 报『当前盘点类型按商品盘点,不能添加库位明细』),locations 兼容 location_codes 写法(locations 优先)、location_ids 兼容 locationIds 驼峰写法(location_ids 优先);仅 created/rejected 状态允许;已存在同盘点项(商品行 stock_id / 库位行 location_code)自动跳过(幂等);完成后重算主表 total_items。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -38566,7 +38699,7 @@ "type": "array", "required": false, "source": "body", - "description": "库位编码列表(wms_location_space.space_code);type=all/location 按库位盘点时使用,与 stock_ids 按任务类型二选一;与 location_ids 同时传入时被忽略(location_ids 优先);type=all 未传库位且未传 location_ids 时自动拉取全仓库启用库位生成盘点范围" + "description": "库位编码列表(wms_location_space.space_code);type=location 按库位盘点时使用,与 stock_ids 按任务类型二选一;与 location_ids 同时传入时被忽略(location_ids 优先);type=location 未传库位且未传 location_ids 时自动拉取全仓库启用库位生成盘点范围" }, { "name": "location_codes", @@ -38580,7 +38713,7 @@ "type": "array", "required": false, "source": "body", - "description": "库位ID列表(wms_location_space.id);type=all/location 按库位盘点时使用,直接按 id+warehouse_id 查库校验(不再按编码二次解析),查不到的 ID 记入 invalid_location_ids(不报错);与 locations 同时传入时 location_ids 优先、locations 忽略;兼容 locationIds 驼峰写法(location_ids 优先)" + "description": "库位ID列表(wms_location_space.id);type=location 按库位盘点时使用,直接按 id+warehouse_id 查库校验(不再按编码二次解析),查不到的 ID 记入 invalid_location_ids(不报错);与 locations 同时传入时 location_ids 优先、locations 忽略;兼容 locationIds 驼峰写法(location_ids 优先)" } ], "response": [ @@ -38665,11 +38798,11 @@ ], "notes": [ "无头库位排除(本次变更):库位所属 zone 不存在或已删除即视为无头库位,一律不纳入盘点——商品路径仅按有效库位拆行(启用库存全部在无头库位的商品计入 invalid_stock_ids)、库位编码/ID 路径计入 invalid_locations/invalid_location_ids(不报错)、全盘自动范围直接排除;workData goods/space 视图库位枚举与明细生成同口径过滤。代码依据:app/service/systems/stock_check.js#VALID_SPACE_SQL(模块常量:wms_location_space JOIN wms_location_zone deleted_at IS NULL)。", - "按类型二选一:type=store/goods 传 stock_ids(传 locations 报『当前盘点类型按商品盘点,请传 stock_ids』、传 location_ids 报『当前盘点类型按商品盘点,不能添加库位明细』);type=all/location 传 locations 或 location_ids(传 stock_ids 报『当前盘点类型按库位盘点,请传 locations 或 location_ids(如需按商品盘点请创建 type=goods 任务)』)。", + "按类型二选一:type=store/goods 传 stock_ids(传 locations 报『当前盘点类型按商品盘点,请传 stock_ids』、传 location_ids 报『当前盘点类型按商品盘点,不能添加库位明细』);type=location 传 locations 或 location_ids(传 stock_ids 报『当前盘点类型按库位盘点,请传 locations 或 location_ids(如需按商品盘点请创建 type=goods 任务)』)。", "location_ids 优先:两者都传时忽略 locations,直接按 wms_location_space.id+warehouse_id 查库校验(不再按 space_code 二次解析),查不到的 ID 记入 invalid_location_ids(不报错)。", - "历史任务兼容:改造前创建的 type=all 任务按商品添加明细(明细行 scope_type='goods');判定口径为该任务在 wms_stock_check_detail 中 scope_type='goods' 行存在(count>0)即继续按商品模式接受 stock_ids(此时传 locations/location_ids 分别报『当前盘点类型按商品盘点,请传 stock_ids』/『当前盘点类型按商品盘点,不能添加库位明细』);全新 type=all 任务(无任何商品明细行)维持按库位语义,只能传 locations/location_ids。仅 type=all 走兼容判定,store/goods/location 类型判定不变。", + "下线说明:type=all 已移除(与 location 语义重复:同样按库位盘点、同样强制盲盘、明细同为库位行),全盘能力并入 location;create 传 all 返回 400「盘点范围类型不合法,仅支持 store/goods/location」,历史 type=all 任务(如迁移未覆盖)添加明细返回 400「盘点范围类型不合法(all)」。存量数据口径见 database/migrations/20261027010000-merge-stock-check-type-all-into-location.js:明细含商品行(scope_type=goods,改造前全仓按商品口径)的历史任务改 type=goods(mode 保持原值),其余(库位行/无明细空任务)改 type=location 并归一 mode=blind。", "商品货主限制:任务 store_id 非空时商品 store_id 必须与之一致,不一致计入 invalid_stock_ids(限制非本货主商品加入盘点)。", - "全盘自动范围:type=all 且未传库位且未传 location_ids 时,自动拉取当前仓库全部启用且有效库位(is_enabled=true 且所属 zone 存在未删除,排除无头库位)的 space_code 生成库位行;无启用库位时报 400。", + "全盘自动范围(原 all 语义):type=location 且未传库位且未传 location_ids 时,自动拉取当前仓库全部启用且有效库位(is_enabled=true 且所属 zone 存在未删除,排除无头库位)的 space_code 生成库位行;无启用库位时报 400。", "幂等:商品行按 check_id+stock_id 整体跳过(同商品重复添加整体跳过,不重复拆行)、库位行按 check_id+location_code 跳过(商品行唯一索引 uk_check_stock_location(check_id, stock_id, location_id),库位行原唯一约束 uk_check_location 已放宽为普通索引 idx_check_location、幂等由应用层查重保证);location_ids 路径跳过项按库位ID记入 skipped。", "商品拆行口径(本次改造,商品任务必须按库位盘点):type=store/goods 传 stock_ids 后按商品在仓库的启用库存库位(wms_storage is_enabled=1 且库位有效(未删除且所属 zone 存在未删除,排除无头库位),按 space_id 分组 SUM(available_quantity+locked_quantity)(=可用+锁定))拆行——每个「商品+库位」生成一条 scope_type=goods 明细行(location_id/location_code 快照绑定库存库位、system_quantity=该库位库存 SUM(可用+锁定));一个商品多个库位对应多行;无启用库存库位的商品计入 invalid_stock_ids 不入明细;added/total_items 均为拆分明细行数。代码依据:app/service/systems/stock_check.js#_addGoodsDetailRows(Storage.findAll warehouse_id+stock_id in+is_enabled=1、attributes SUM(quantity)、group=[stock_id, space_id];LocationSpace 按 id 取 space_code 快照)。", "响应统一 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)。" @@ -38973,7 +39106,7 @@ }, { "method": "stock.check.workData", - "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)的任务可拉取」。", + "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)一律按 location 视图;任务范围为商品(type=goods/store)默认 space 视图、仅 is_goods=true 时 goods 视图。location(库位结构):以任务库位范围行(scope_type=location)为列表(按明细 id 升序;行含 detail_id/location_id 与同义字段 space_id/location_code/location_name/status/has_unknown/is_empty/checked_at/checkers/goods,space_id 可直接回传 stock.check.report),行内挂该库位的盘点作业记录 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 按拣货路径排序,无库存但已有作业记录的库位追加在末尾;每项含 location_id(库位ID wms_location_space.id,取分区有效的库位行,供调用方直接回传 stock.check.report 的 location_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_id;指向无头库位(分区不存在/已删除)时归并到同编码有效库位并优先该商品有库存的库位,保证同编码只出一行、自定义名称/编码取有效库位行)、未回填的按 location_code 匹配 wms_location_space.space_code 补查,与库存库位去重后取并集),仅按库位拣货顺序排序(pick_sequence 升序,pick_priority 与库位 id 不参与,同值保持库位查询顺序),行含 id/space_code/custom_barcode/custom_name/goods(id 为库位ID wms_location_space.id,并额外输出同义字段 location_id,便于与 location/goods 视图、recordList、result 统一命名并直接回传 stock.check.report),行内 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": [ @@ -39004,7 +39137,7 @@ "type": "string", "required": false, "source": "body", - "description": "关键字(可选,向后兼容新增):仅库位任务(服务端解析视图为 location,即任务类型 location/all)生效——按行 location_code(优先明细快照,缺失回退库位表 space_code)与 location_name(custom_name 兜底 space_code)做模糊匹配(contains、不区分大小写)过滤任务明细后再分页返回;非库位任务(goods/store,space/goods 视图)忽略该参数;keyword 为空/纯空白视为未传不过滤" + "description": "关键字(可选,向后兼容新增):仅库位任务(服务端解析视图为 location,即任务类型 location)生效——按行 location_code(优先明细快照,缺失回退库位表 space_code)与 location_name(custom_name 兜底 space_code)做模糊匹配(contains、不区分大小写)过滤任务明细后再分页返回;非库位任务(goods/store,space/goods 视图)忽略该参数;keyword 为空/纯空白视为未传不过滤" }, { "name": "only_abnormal", @@ -39050,7 +39183,7 @@ "name": "view", "type": "string", "required": true, - "description": "服务端实际解析出的视图类型(location=库位结构 / goods=商品结构 / space=聚合库位结构),由任务范围(type=location/all 一律 location)与 is_goods 入参共同决定,供调用方判断 rows 行结构" + "description": "服务端实际解析出的视图类型(location=库位结构 / goods=商品结构 / space=聚合库位结构),由任务范围(type=location 一律 location)与 is_goods 入参共同决定,供调用方判断 rows 行结构" }, { "name": "rows", @@ -39104,7 +39237,7 @@ } ], "notes": [ - "代码依据:app/service/systemMethods/stock/check.js#workData(warehouse_id 由服务端从 ctx.user.store_id 自动注入,前端无需传递;const { id, is_goods: isGoodsSnake, isGoods: isGoodsCamel, pagination } = data || {},isGoods=is_goods 未定义时回退 isGoods(兼容 isGoods 驼峰写法);不再读取、不再校验 view,透传 { warehouseId, id, isGoods, pagination })+ app/service/systems/stock_check.js#workData(id 非正整数抛 400『盘点任务ID不能为空』;任务不存在(按 id+warehouse_id 查 wms_stock_check)抛 400『盘点任务不存在』;状态守卫:任务状态非 REPORT_ALLOWED_STATUSES(approved/checking)时抛 400『当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取』;视图解析:normalizedType=String(check.type||'').trim(),type=location/all 一律 location 视图(无视 view/is_goods),否则 goodsViewRequested=isGoods===true||'true'||1 时 goods 视图、其余默认 space 视图;按解析视图分派 _buildLocationWorkRows/_buildGoodsWorkRows/_buildSpaceWorkRows,统一返回 { check: _formatCheckRow 口径, rows, total: rows.length, page, pageSize })。本次代码已改(view 入参废弃、is_goods 驱动视图)并测试通过 197/197、ESLint 0 错误。", + "代码依据:app/service/systemMethods/stock/check.js#workData(warehouse_id 由服务端从 ctx.user.store_id 自动注入,前端无需传递;const { id, is_goods: isGoodsSnake, isGoods: isGoodsCamel, pagination } = data || {},isGoods=is_goods 未定义时回退 isGoods(兼容 isGoods 驼峰写法);不再读取、不再校验 view,透传 { warehouseId, id, isGoods, pagination })+ app/service/systems/stock_check.js#workData(id 非正整数抛 400『盘点任务ID不能为空』;任务不存在(按 id+warehouse_id 查 wms_stock_check)抛 400『盘点任务不存在』;状态守卫:任务状态非 REPORT_ALLOWED_STATUSES(approved/checking)时抛 400『当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取』;视图解析:normalizedType=String(check.type||'').trim(),type=location 一律 location 视图(无视 view/is_goods),否则 goodsViewRequested=isGoods===true||'true'||1 时 goods 视图、其余默认 space 视图;按解析视图分派 _buildLocationWorkRows/_buildGoodsWorkRows/_buildSpaceWorkRows,统一返回 { check: _formatCheckRow 口径, rows, total: rows.length, page, pageSize })。本次代码已改(view 入参废弃、is_goods 驱动视图)并测试通过 197/197、ESLint 0 错误。", "三视图口径(由任务范围 + is_goods 解析后分派):location=库位结构(库位范围任务一律该视图),以任务库位范围行(scope_type=location)为列表(按明细 id 升序),行内挂该库位盘点作业记录 goods 子列表(已知商品与未知商品记录均入内:已知商品 stock_id 有值,商品信息批量取自 stockWarehouse.getStockDetails 带缓存、货主名 _resolveStoreNameMap 解析;未知商品 stock_id=null,item_code 用条码兜底、item_name 用名称快照兜底条码、store_id/store_name 为 null;已知/未知商品的 images 均为作业记录照片(经 _attachRecordImages 挂载 FileReference business_type=stock_check_record,已知商品不再输出商品主图 image_url)),has_unknown 标记该库位是否含未知商品记录;goods=商品结构(商品范围任务且 is_goods=true 时该视图),以任务商品范围行(scope_type=goods)为列表(按明细 id 升序),行内 locations 为商品所在全部库位列表(商品库存库位取自 wms_storage 启用未删除存储且库位有效(未删除且所属 zone 存在未删除,排除无头库位)DISTINCT space_id 按拣货路径排序,无库存但已有作业记录的库位按首条记录 id 升序追加在末尾,空库位归 location_code=null 组排在最后;明盘每库位含 system_quantity 该库位账面数量与 quantity 该库位盘点数量(未盘库位 0),盲盘仅 location_code/checked_at/checker_name/record_ids/images);space=聚合库位列表(商品范围任务默认该视图),库位集合=当前库存库位 ∪ 作业记录库位——当前库存库位:wms_storage(warehouse_id + stock_id 在集合 + is_enabled=1 未删除且库位有效(排除无头库位))DISTINCT space_id;作业记录库位:wms_stock_check_record 的 location_id 已回填直接用、未回填的按 location_code 匹配 wms_location_space.space_code 补查,与库存库位去重后并集;行内 goods 为该库位下的任务商品;盘点前库存已出空但已有盘点作业记录的库位也能展示(该库位商品行账面 system_quantity 按 0、checked_quantity 按该库位实盘合计)。", "明盘/盲盘数量控制:明盘(mode=open)goods 视图行返回 system_quantity(明细账面快照)/checked_quantity(已盘合计=locations.quantity 合计)/diff_quantity(已盘-账面,仅存在作业记录的行计算)/is_diff(差异非 0 为 1),locations 各项含 system_quantity(该库位账面数量=可用+锁定,wms_storage 该库位 SUM(available_quantity+locked_quantity),无库存记录库位为 0)、locked_quantity(该库位锁定数量,wms_storage 该库位 SUM(locked_quantity))与 quantity(该库位盘点数量=实盘合计,未盘库位为 0);space 视图 goods 各项含 system_quantity(wms_storage space+stock SUM(available_quantity+locked_quantity) 账面,该库位无库存记录时按 0)/locked_quantity(wms_storage space+stock SUM(locked_quantity))/checked_quantity(该商品在该库位的实盘合计);盲盘(mode=blind)不返回任何数量字段(goods 视图 locations 仅 location_code/checked_at/checker_name/record_ids/images,space 视图 goods 仅商品信息+images/record_ids/status);goods 视图 locations 为商品所在全部库位列表(含未盘库位,无作业记录时各项为空信息),无作业记录的行明盘已盘合计恒 0、差异/is_diff 恒 0(避免未盘行误显盘亏差异)。", "排序口径:space 视图库位仅按库位拣货顺序排序——pick_sequence 升序(pick_priority 与库位 id 均不参与,同值保持库位查询顺序);space 行内 goods 按 stock_id 升序;location/goods 视图行按明细 id 升序;goods 视图 locations 按首条记录 id 升序。", @@ -39124,7 +39257,7 @@ "分页口径修正(本次):上一轮文档曾描述「支持顶层 data.page / data.pageSize / data.page_size(顶层优先)并兼容 page_size 蛇形写法」,实际代码已按用户要求改为与同模块 stock.check.list 完全一致的常规口径——仅 pagination.{page,pageSize};本次同步文档删除上述兼容描述,params.pagination/description/response.page/pageSize/notes 统一为常规口径。代码依据:app/service/systemMethods/stock/check.js#workData(const { id, is_goods: isGoodsSnake, isGoods: isGoodsCamel, pagination } = data || {},直接透传)+ app/service/systems/stock_check.js#workData(pagination 默认 {},page/pageSize 归一化后对全量行 slice)。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params.pagination 描述、description、response.page/pageSize 描述、notes 同步常规分页口径,删除顶层参数兼容与 page_size 兼容表述;response.rows/total、headers/errors/isNeedAuth/isNeedLogin 不变);根版本 0.3.229 → 0.3.230、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 19 条 method 未改动(stock.check 分组仍为 20 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库(显式 WMS_DB_TARGET=local)与生产库(显式 WMS_DB_TARGET=production)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。", - "视图驱动规则(本次改造):view 入参废弃——方法层不再读取、不再校验 view,传任何值都被忽略、不报错;视图改由任务范围 + is_goods 驱动——任务范围为库位(type=location/all)一律按库位视图(location)返回,无视 view/is_goods;任务范围为商品(type=goods/store)默认聚合库位视图(space),仅 is_goods=true 时按商品视图(goods)返回;is_goods 其他值(false/0/缺省等)一律按默认 space。is_goods 兼容 isGoods 驼峰写法(is_goods 未定义时回退 isGoods)。分页能力不变(pagination.{page,pageSize},与 stock.check.list 口径一致,默认 20 上限 200)。影响面:前端如需商品视图须改传 is_goods=true;view 传值不再生效。", + "视图驱动规则(本次改造):view 入参废弃——方法层不再读取、不再校验 view,传任何值都被忽略、不报错;视图改由任务范围 + is_goods 驱动——任务范围为库位(type=location)一律按库位视图(location)返回,无视 view/is_goods;任务范围为商品(type=goods/store)默认聚合库位视图(space),仅 is_goods=true 时按商品视图(goods)返回;is_goods 其他值(false/0/缺省等)一律按默认 space。is_goods 兼容 isGoods 驼峰写法(is_goods 未定义时回退 isGoods)。分页能力不变(pagination.{page,pageSize},与 stock.check.list 口径一致,默认 20 上限 200)。影响面:前端如需商品视图须改传 is_goods=true;view 传值不再生效。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params 删除 view、新增 is_goods(boolean,body,可选,兼容 isGoods 驼峰写法);description 同步「库位任务一律 location、商品任务默认 space、is_goods=true 才 goods;view 入参已废弃忽略」;errors 删除「视图类型非法(仅支持 location/goods/space)」条目;response 结构不变(check/rows/total/page/pageSize);notes 同步代码依据与视图驱动规则);根版本 0.3.230 → 0.3.231、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 19 条 method 未改动(stock.check 分组仍为 20 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。", "响应统一 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)。", @@ -39139,11 +39272,11 @@ "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(description/response.rows/notes 同步三视图作业照片挂载与 record_ids 输出口径);headers/params/errors/isNeedAuth/isNeedLogin 与分页/状态限制描述不变;根版本 0.3.238 → 0.3.239、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 21 条 method 未改动(stock.check 分组仍为 22 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 与变更记录后,同步回填开发库(显式 WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(显式 WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 22 条 method 无损。", "不返回 check、改返回 view 口径(本次改造):workData 响应由 { check, rows, total, page, pageSize } 调整为 { view, rows, total, page, pageSize }——移除任务主表信息 check(任务信息请调用 stock.check.detail),新增 view(服务端实际解析出的视图类型 location/goods/space,供调用方判断 rows 行结构)。check 仍由服务端内部查询(视图解析 normalizedType=check.type、盲盘/明盘 check.mode、状态守卫),仅不再对外返回。代码依据:app/service/systems/stock_check.js#workData(resolvedView 取自 normalizedType/is_goods 解析结果)。", - "view 取值口径:任务范围为库位(type=location/all)一律 location(无视 is_goods/view 入参);任务范围为商品(type=goods/store)默认 space,仅 is_goods=true(含 true/\"true\"/1)时为 goods。与视图解析规则一一对应。", + "view 取值口径:任务范围为库位(type=location)一律 location(无视 is_goods/view 入参);任务范围为商品(type=goods/store)默认 space,仅 is_goods=true(含 true/\"true\"/1)时为 goods。与视图解析规则一一对应。", "兼容性影响(破坏性变更):响应 data 移除 check 字段;新增 view 字段;rows/total/page/pageSize 与三视图行结构、明盘盲盘数量控制、状态限制均不变;前端如需任务主表信息改调 stock.check.detail。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(description 同步 view/移除 check、response 的 data.children 以 view 替换 check、notes 补充 view 口径与兼容性说明;headers/params/errors/isNeedAuth/isNeedLogin 与 rows 三视图结构不变);根版本 0.3.241 → 0.3.242、updatedAt 保持 2026-10-03;methods/changes/system.json 新增本条(插入数组首位);其余 21 条 method 未改动(stock.check 分组仍为 22 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,需另行同步回填开发库与生产库(import 当前 system.json → export 往返校验),保持库与文件一致。", - "keyword 过滤口径(本次新增):keyword(string,可选,向后兼容)仅库位任务(服务端解析视图为 location,即任务类型 location/all)生效——resolvedView===\"location\" 且 normalizedKeyword=String(keyword||\"\").trim().toLowerCase() 非空时,先按行 location_code/location_name 模糊匹配(contains、不区分大小写)过滤全量任务明细行,再按 pagination 切片;非库位任务(goods/store,space/goods 视图)忽略该参数;keyword 为空/纯空白视为未传不过滤;total=filteredRows.length(过滤后行数),rows 为过滤后当前页行。代码依据:app/service/systemMethods/stock/check.js#workData(透传 keyword)+ app/service/systems/stock_check.js#workData(filteredRows)。本次代码已改并测试通过 214/214、ESLint 0 错误。", + "keyword 过滤口径(本次新增):keyword(string,可选,向后兼容)仅库位任务(服务端解析视图为 location,即任务类型 location)生效——resolvedView===\"location\" 且 normalizedKeyword=String(keyword||\"\").trim().toLowerCase() 非空时,先按行 location_code/location_name 模糊匹配(contains、不区分大小写)过滤全量任务明细行,再按 pagination 切片;非库位任务(goods/store,space/goods 视图)忽略该参数;keyword 为空/纯空白视为未传不过滤;total=filteredRows.length(过滤后行数),rows 为过滤后当前页行。代码依据:app/service/systemMethods/stock/check.js#workData(透传 keyword)+ app/service/systems/stock_check.js#workData(filteredRows)。本次代码已改并测试通过 214/214、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params 新增 keyword(string,可选);description 与 response.rows/total 描述同步 keyword 过滤口径(location 视图 + keyword 时 rows 为过滤后的库位行、total 同步过滤口径;非库位任务忽略);headers/errors/isNeedAuth/isNeedLogin 与响应结构不变);根版本 0.3.243 → 0.3.244、updatedAt 保持 2026-10-04;methods/changes/system.json 新增本条(插入数组首位);其余 21 条 method 未改动(stock.check 分组仍为 22 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 与变更记录后,同步回填开发库(WMS_DB_TARGET=local)与生产库(WMS_DB_TARGET=production)(import 当前 system.json → export 往返校验),保持库与文件一致。", "goods 视图 locations 商品库位列表口径(本次改造):_buildGoodsWorkRows 的 locations 由「仅已盘库位(按首条记录 id 升序)」改为「商品所在全部库位列表」——基础库位取自 wms_storage(任务 stock_id 集合 + is_enabled=1 未删除,DISTINCT space_id)经库位表取 space_code 并按拣货路径排序(pick_sequence 升序、pick_priority 降序、库位 id 升序兜底);无库存但已有作业记录的库位按首条记录 id 升序追加在末尾;空库位(location_code 空)组仍排在最后。未盘库位输出空信息(checked_at/checker_name=null、record_ids/images 空数组、明盘 quantity=0);明盘 checked_quantity=locations 各库位 quantity 合计(未盘行恒 0);diff_quantity/is_diff 仅对存在作业记录(detailRecords.length>0)的行计算,未盘行恒 0(避免未盘行误显盘亏差异)。盲盘仍不返回任何数量字段。代码依据:app/service/systems/stock_check.js#_buildGoodsWorkRows;回归测试 222/222 通过、ESLint 0 错误。", @@ -39159,7 +39292,7 @@ }, { "method": "stock.check.workDataSpaceDetails", - "description": "拉取盘点作业数据(space 视图分页版):入参 id(盘点任务ID)+ location_id(库位ID,可选,兼容 locationId 驼峰写法)+ pagination({page,pageSize},缺省 page=1/pageSize=20,上限 200);warehouse_id 由服务端从当前上下文自动注入,前端无需传递。行结构与 workData space 视图行一致:id=库位ID(wms_location_space.id)/ space_code 库位编码 / custom_barcode 自定义条码 / custom_name 库位名称 / goods 该库位下的任务商品子列表(detail_id 明细ID / stock_id 商品库存ID / item_code 商品编码 / item_name 商品名称 / spec 规格 / store_id 货主ID / store_name 货主名 / barcode 条码 / images 作业照片 / record_ids 作业记录ID列表;明盘 mode=open 另含 system_quantity 账面数量(wms_storage 该库位该商品 SUM(available_quantity+locked_quantity))、locked_quantity 锁定数量(wms_storage 该库位该商品 SUM(locked_quantity))与 checked_quantity 已盘合计;盲盘 mode=blind 不返回任何数量字段;status=checked 该 (detail_id, location_code) 存在作业记录 / unchecked 未盘)。库位仅按库位拣货顺序排序(pick_sequence 升序,pick_priority 与库位 id 不参与,同值保持库位查询顺序);传入 location_id 时只返回该库位行(total=1),不传时按分页返回全部库位行;返回 { view:'space', rows, total, page, pageSize }(不返回任务主表信息,任务信息请调用 stock.check.detail)。仅任务状态 approved(审核完成)或 checking(盘点作业中)可拉取(与 workData 同口径)。权限口径:免 API 权限校验,仅需登录(与 stock.check 分组其他方法一致)。", + "description": "拉取盘点作业数据(space 视图分页版):入参 id(盘点任务ID)+ location_id(库位ID,可选,兼容 locationId 驼峰写法)+ pagination({page,pageSize},缺省 page=1/pageSize=20,上限 200);warehouse_id 由服务端从当前上下文自动注入,前端无需传递。行结构与 workData space 视图行一致:id=库位ID(wms_location_space.id,另有同义字段 location_id)/ space_code 库位编码 / custom_barcode 自定义条码 / custom_name 库位名称 / goods 该库位下的任务商品子列表(detail_id 明细ID / stock_id 商品库存ID / item_code 商品编码 / item_name 商品名称 / spec 规格 / store_id 货主ID / store_name 货主名 / barcode 条码 / images 作业照片 / record_ids 作业记录ID列表;明盘 mode=open 另含 system_quantity 账面数量(wms_storage 该库位该商品 SUM(available_quantity+locked_quantity))、locked_quantity 锁定数量(wms_storage 该库位该商品 SUM(locked_quantity))与 checked_quantity 已盘合计;盲盘 mode=blind 不返回任何数量字段;status=checked 该 (detail_id, location_code) 存在作业记录 / unchecked 未盘)。库位仅按库位拣货顺序排序(pick_sequence 升序,pick_priority 与库位 id 不参与,同值保持库位查询顺序);传入 location_id 时只返回该库位行(total=1),不传时按分页返回全部库位行;返回 { view:'space', rows, total, page, pageSize }(不返回任务主表信息,任务信息请调用 stock.check.detail)。仅任务状态 approved(审核完成)或 checking(盘点作业中)可拉取(与 workData 同口径)。权限口径:免 API 权限校验,仅需登录(与 stock.check 分组其他方法一致)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -39238,7 +39371,7 @@ }, { "method": "stock.check.workDataDetail", - "description": "拉取单条盘点明细的作业数据(workData 单行版,按明细范围类型分流,均返回单行对象):入参 detail_id(盘点明细ID,兼容 detailId 驼峰写法);warehouse_id 由服务端从当前上下文自动注入,前端无需传递;返回统一 success 包装,data 为单行作业数据。① 库位明细(scope_type=location):行结构与 workData location 视图单行一致——detail_id 明细ID / location_id 库位ID(明细未绑定库位时为 null)/ location_code 库位编码(优先明细快照,缺失回退库位表 space_code)/ location_name 库位名称(custom_name 兜底 space_code,无库位编码时为 null)/ status 盘点状态(checked=存在作业记录(含空库位标记记录),unchecked=无作业记录)/ has_unknown 是否含未知商品记录 / is_empty 是否空库位标记(空标记记录不计入 goods 子列表)/ checked_at 该库位最近上报时间(无记录为 null)/ checkers 盘点人去重数组 + goods 作业记录子列表(已知商品与未知商品记录均入内,字段与 workData location 视图一致:record_id 作业记录ID(可调 stock.check.recordDelete / stock.check.recheckClearLocation 移除)/ stock_id 商品库存ID(未知商品为 null)/ item_code 商品编码(未知商品用条码兜底)/ item_name 商品名称(未知商品用名称快照兜底条码)/ barcode 条码 / images 作业记录照片(FileReference business_type=stock_check_record 经 _attachRecordImages 挂载,与 workData/result/recordList 口径一致,无照片为空数组)/ store_id 货主ID(未知商品为 null)/ store_name 货主名(未知商品为 null)/ quantity 实盘数量 / checked_at 上报时间 / checker_name 盘点人;空库位标记记录不计入 goods)。② 商品明细(scope_type=goods):行结构与 workData goods 视图行一致——detail_id 明细ID / stock_id 商品库存ID / item_code 商品编码 / item_name 商品名称 / spec 规格 / store_id 货主ID / store_name 货主名 / barcode 条码 / images 商品图片(URL 数组,与 workData goods 视图一致)/ locations 商品所在全部库位列表(商品库存库位按拣货路径排序在前,无库存但已有作业记录的库位按首条记录 id 升序追加在末尾,空库位归 location_code=null 组排在最后;每项 { location_code, checked_at, checker_name, record_ids, images },未盘库位 checked_at/checker_name 为 null、record_ids/images 为空数组;明盘另含 system_quantity 该库位账面数量(=可用+锁定)、locked_quantity 该库位锁定数量与 quantity 该库位盘点数量(未盘库位 0),盲盘只返回库位信息);明盘(mode=open)另含 system_quantity 账面快照 / checked_quantity 已盘合计 / diff_quantity 差异(仅存在作业记录时计算,未盘恒 0) / is_diff,盲盘(mode=blind)不返回任何数量字段。仅任务状态 approved(审核完成)或 checking(盘点作业中)可拉取(与 workData 同口径)。", + "description": "拉取单条盘点明细的作业数据(workData 单行版,按明细范围类型分流,均返回单行对象):入参 detail_id(盘点明细ID,兼容 detailId 驼峰写法);warehouse_id 由服务端从当前上下文自动注入,前端无需传递;返回统一 success 包装,data 为单行作业数据。① 库位明细(scope_type=location):行结构与 workData location 视图单行一致——detail_id 明细ID / location_id 库位ID(明细未绑定库位时为 null)与同义字段 space_id(可直接回传 stock.check.report)/ location_code 库位编码(优先明细快照,缺失回退库位表 space_code)/ location_name 库位名称(custom_name 兜底 space_code,无库位编码时为 null)/ status 盘点状态(checked=存在作业记录(含空库位标记记录),unchecked=无作业记录)/ has_unknown 是否含未知商品记录 / is_empty 是否空库位标记(空标记记录不计入 goods 子列表)/ checked_at 该库位最近上报时间(无记录为 null)/ checkers 盘点人去重数组 + goods 作业记录子列表(已知商品与未知商品记录均入内,字段与 workData location 视图一致:record_id 作业记录ID(可调 stock.check.recordDelete / stock.check.recheckClearLocation 移除)/ stock_id 商品库存ID(未知商品为 null)/ item_code 商品编码(未知商品用条码兜底)/ item_name 商品名称(未知商品用名称快照兜底条码)/ barcode 条码 / images 作业记录照片(FileReference business_type=stock_check_record 经 _attachRecordImages 挂载,与 workData/result/recordList 口径一致,无照片为空数组)/ store_id 货主ID(未知商品为 null)/ store_name 货主名(未知商品为 null)/ quantity 实盘数量 / checked_at 上报时间 / checker_name 盘点人;空库位标记记录不计入 goods)。② 商品明细(scope_type=goods):行结构与 workData goods 视图行一致——detail_id 明细ID / stock_id 商品库存ID / item_code 商品编码 / item_name 商品名称 / spec 规格 / store_id 货主ID / store_name 货主名 / barcode 条码 / images 商品图片(URL 数组,与 workData goods 视图一致)/ locations 商品所在全部库位列表(商品库存库位按拣货路径排序在前,无库存但已有作业记录的库位按首条记录 id 升序追加在末尾,空库位归 location_code=null 组排在最后;每项 { location_code, location_id, space_id, checked_at, checker_name, record_ids, images },未盘库位 checked_at/checker_name 为 null、record_ids/images 为空数组(location_id/space_id 同值,取分区有效库位行,可直接回传 stock.check.report);明盘另含 system_quantity 该库位账面数量(=可用+锁定)、locked_quantity 该库位锁定数量与 quantity 该库位盘点数量(未盘库位 0),盲盘只返回库位信息);明盘(mode=open)另含 system_quantity 账面快照 / checked_quantity 已盘合计 / diff_quantity 差异(仅存在作业记录时计算,未盘恒 0) / is_diff,盲盘(mode=blind)不返回任何数量字段。仅任务状态 approved(审核完成)或 checking(盘点作业中)可拉取(与 workData 同口径)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -39391,7 +39524,7 @@ }, { "method": "stock.check.report", - "description": "盘点作业上报(覆盖式):商品明细行(scope_type=goods)固定上报明细商品(入参 stock_id 与明细商品不一致报错),库位可选(未传归入\"无库位\"分组,location_code 存空串 '');库位明细行(scope_type=location)必须指定商品(stock_id 或 barcode 至少一项),库位以明细库位为准(入参库位与明细库位不一致报错,不传时默认明细库位);空库位标记(is_empty=true,仅库位明细行支持):确认该库位为空——不要求商品/条码,quantity 恒为 0,写一条特殊作业记录(stock_id=null、barcode=null、item_name=null、quantity=0、is_empty=1);与商品记录互斥:标记空时删除该明细下所有商品记录(含未知商品),上报商品时删除该明细下空标记记录;商品明细行传 is_empty 报 400「仅库位盘点明细支持空库位标记」。覆盖式查重:已知商品维度 detail_id+stock_id+location_code、未知商品维度 detail_id+stock_id IS NULL+barcode+location_code,同明细+同商品+同库位重复上报时更新已有记录(quantity/checker_id/checker_name/checked_at,保留原 location_id,本次新匹配到 location_id 则回填),不再新增;仅 approved/checking 状态允许;库位编码匹配 wms_location_space.space_code 时回填 location_id;主表 approved 首次上报自动转 checking;完成后重算 checked_items/diff_items/detail_status(已盘口径=存在记录的明细数,差异=记录数量合计-账面:商品行 vs system_quantity 快照、库位行按商品 vs wms_storage 账面;未知商品无账面,实盘>0 即盘盈、必然计入差异;空标记记录同样计入已盘明细(checked_items/detail_status),空标记明细的库位账面有库存即计盘亏差异(diff_items));数据库层由唯一索引 uk_detail_stock_location(detail_id, stock_id, location_code) 保证已知商品覆盖式上报并发安全(并发下不产生重复记录),未知商品(stock_id=NULL)唯一索引不约束 NULL 行、应用层查重兜底。主表 start_time 为空时以本次明细写入时间补写(首个盘点明细写入时间记录为 start_time,即盘点开始时间)。未知商品上报(stock_id 与 barcode 至少传一项):仅传 barcode → 先按条码匹配系统商品(wms_stock_barcodes 按 barcode+本仓库,关联 StockWarehouse 校验商品属于本仓库),命中回填 stock_id 走已知商品逻辑;未命中记录未知商品(stock_id=NULL+barcode+item_name,item_name 缺省为 barcode);都未传沿用原报错口径。", + "description": "盘点作业上报(覆盖式):商品明细行(scope_type=goods)固定上报明细商品(入参 stock_id 与明细商品不一致报错),库位可选(未传归入\"无库位\"分组,location_code 存空串 '');库位明细行(scope_type=location)必须指定商品(stock_id 或 barcode 至少一项),库位以明细库位为准(入参库位与明细库位不一致报错,不传时默认明细库位);空库位标记(is_empty=true,仅库位明细行支持):确认该库位为空——不要求商品/条码,quantity 恒为 0,写一条特殊作业记录(stock_id=null、barcode=null、item_name=null、quantity=0、is_empty=1);与商品记录互斥:标记空时删除该明细下所有商品记录(含未知商品),上报商品时删除该明细下空标记记录;商品明细行传 is_empty 报 400「仅库位盘点明细支持空库位标记」。覆盖式查重:已知商品维度 detail_id+stock_id+location_code、未知商品维度 detail_id+stock_id IS NULL+barcode+location_code,同明细+同商品+同库位重复上报时更新已有记录(quantity/checker_id/checker_name/checked_at,保留原 location_id,本次新匹配到 location_id 则回填),不再新增;仅 approved/checking 状态允许;**space_id 必传**(库位以该 ID 为准,传了 location 编码则仅做一致性校验,服务端不再按编码猜库位,缺失报 400「缺少库位ID(space_id)」);实盘数量上限 2147483647(超出报 400「实盘数量不能超过 2147483647」,避免落库列 int(12) 越界变成 500);主表 approved 首次上报自动转 checking;完成后重算 checked_items/diff_items/detail_status(已盘口径=存在记录的明细数,差异=记录数量合计-账面:商品行 vs system_quantity 快照、库位行按商品 vs wms_storage 账面;未知商品无账面,实盘>0 即盘盈、必然计入差异;空标记记录同样计入已盘明细(checked_items/detail_status),空标记明细的库位账面有库存即计盘亏差异(diff_items));数据库层由唯一索引 uk_detail_stock_location(detail_id, stock_id, location_code) 保证已知商品覆盖式上报并发安全(并发下不产生重复记录),未知商品(stock_id=NULL)唯一索引不约束 NULL 行、应用层查重兜底。主表 start_time 为空时以本次明细写入时间补写(首个盘点明细写入时间记录为 start_time,即盘点开始时间)。未知商品上报(stock_id 与 barcode 至少传一项):仅传 barcode → 先按条码匹配系统商品(wms_stock_barcodes 按 barcode+本仓库,关联 StockWarehouse 校验商品属于本仓库),命中回填 stock_id 走已知商品逻辑;未命中记录未知商品(stock_id=NULL+barcode+item_name,item_name 缺省为 barcode);都未传沿用原报错口径。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -39422,14 +39555,21 @@ "type": "string", "required": false, "source": "body", - "description": "库位编码(可空;商品明细行:未传归入无库位分组(存空串 '');库位明细行:以明细库位为准,传入时必须与明细库位一致)" + "description": "库位编码(可选,仅做一致性校验;库位一律以 space_id 为准):商品明细行传入时必须与 space_id 对应库位编码一致(否则 400「上报库位编码与库位ID不一致」);库位明细行传入时必须与明细库位一致(否则 400「上报库位与盘点明细库位不一致」);不传时按 space_id 对应库位编码落库" + }, + { + "name": "space_id", + "type": "number", + "required": true, + "source": "body", + "description": "库位ID(wms_location_space.id,**必填**;兼容 spaceId / location_id / locationId 写法,取回接口 rows[].space_id / rows[].id / locations[].space_id 可直接回传):必须属于当前仓库且所属分区(zone)存在未删除,缺失或非法返回 400「缺少库位ID(space_id)」、不存在/跨仓库/分区已删除返回 400「上报库位不存在、不属于当前仓库或所属分区已删除」;服务端以该 ID 为准落库,不再按库位编码猜库位" }, { "name": "quantity", "type": "number", "required": true, "source": "body", - "description": "实盘数量(不小于 0 的整数)" + "description": "实盘数量(不小于 0 的整数,且不大于 2147483647——超出落库列 int(12) 范围会报 400「实盘数量不能超过 2147483647」)" }, { "name": "stock_id", @@ -39564,7 +39704,7 @@ }, { "method": "stock.check.markEmpty", - "description": "标记库位为空(库位盘点模式专属,转调 report 的空库位标记口径):仅库位范围任务(type=location/all)支持——非库位任务报 400「仅库位盘点任务支持空库位标记」;仅 approved/checking 状态允许;明细必须属于本任务且为库位范围行(scope_type=location),非库位行报 400「仅库位盘点明细支持空库位标记」;行为与 report(is_empty=true) 完全一致——写/更新空标记记录(stock_id/barcode/item_name 均为 null、quantity=0、is_empty=1)、清除该明细商品记录、主表 approved 首次标记自动转 checking、重算 checked_items/diff_items/detail_status(空标记计入已盘;库位账面有库存计盘亏差异);warehouse_id 由服务端从当前登录上下文(ctx.user.store_id)自动注入,前端无需传递。", + "description": "标记库位为空(库位盘点模式专属,转调 report 的空库位标记口径):仅库位范围任务(type=location)支持——非库位任务报 400「仅库位盘点任务支持空库位标记」;仅 approved/checking 状态允许;明细必须属于本任务且为库位范围行(scope_type=location),非库位行报 400「仅库位盘点明细支持空库位标记」;行为与 report(is_empty=true) 完全一致——写/更新空标记记录(stock_id/barcode/item_name 均为 null、quantity=0、is_empty=1)、清除该明细商品记录、主表 approved 首次标记自动转 checking、重算 checked_items/diff_items/detail_status(空标记计入已盘;库位账面有库存计盘亏差异);warehouse_id 由服务端从当前登录上下文(ctx.user.store_id)自动注入,前端无需传递。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -39703,7 +39843,7 @@ ], "notes": [ "库位盘点专属便捷方法:内部转调 report(is_empty=true) 口径(查重/互斥/汇总/日志统一),行为与 report 空库位标记完全一致——写/更新空标记记录(stock_id=null、barcode=null、item_name=null、quantity=0、is_empty=1)、清除该明细商品记录、主表 approved 首次标记自动转 checking、完成后重算 checked_items/diff_items/detail_status。代码依据:app/service/systemMethods/stock/check.js#markEmpty(warehouse_id 由服务端从 ctx.user.store_id 自动注入,checkerId/checkerName 同口径注入)+ app/service/systems/stock_check.js#markEmpty(校验后转调 this.report({ is_empty: true }))。", - "校验顺序口径:任务ID/明细ID 非正整数 → 400「盘点任务ID不能为空」/「盘点明细ID不能为空」;任务不存在(按 id+warehouse_id 查 wms_stock_check)→ 400「盘点任务不存在」;状态非 REPORT_ALLOWED_STATUSES(approved/checking)→ 400「当前状态(xx)不允许盘点作业」;任务范围非库位(type≠location/all)→ 400「仅库位盘点任务支持空库位标记」;明细不存在(id+check_id+warehouse_id 查 wms_stock_check_detail)→ 400「盘点明细不存在」;明细非库位行(scope_type≠location)→ 400「仅库位盘点明细支持空库位标记」。", + "校验顺序口径:任务ID/明细ID 非正整数 → 400「盘点任务ID不能为空」/「盘点明细ID不能为空」;任务不存在(按 id+warehouse_id 查 wms_stock_check)→ 400「盘点任务不存在」;状态非 REPORT_ALLOWED_STATUSES(approved/checking)→ 400「当前状态(xx)不允许盘点作业」;任务范围非库位(type≠location)→ 400「仅库位盘点任务支持空库位标记」;明细不存在(id+check_id+warehouse_id 查 wms_stock_check_detail)→ 400「盘点明细不存在」;明细非库位行(scope_type≠location)→ 400「仅库位盘点明细支持空库位标记」。", "权限口径:随 ALL_METHOD_NAMES(22 个,已由 20 增至 21(markEmpty),本次再增 recheckClearLocation)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(_noNeedAuth)、必须登录(isNeedLogin=true,免登录清单为空);为写操作,不在免日志清单(_noNeedLog)中,记录操作日志(内部转调 report,走 STOCK_CHECK_REPORT 操作日志口径)。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内({ record, detail_id, mode, total_items, checked_items, diff_items, detail_status },与 report 完全一致)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.markEmpty 一条(位于 stock.check.report 之后);分组内各 method notes 的「统一包装」描述与 workData「权限口径」note 中 ALL_METHOD_NAMES 方法清单由 20 增至 21 个(markEmpty 插在 report 之后);根版本 0.3.234 → 0.3.235、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);stock.check 分组由 20 条增至 21 条。", @@ -39991,7 +40131,7 @@ }, { "method": "stock.check.recheckClearLocation", - "description": "重盘清除库位(按库位清除盘点信息,库位盘点模式专属):传盘点任务ID与库位ID,清除该库位范围内明细(scope_type=location)的全部作业记录(含空库位标记),该库位回到未盘;仅任务范围为库位(type=location/all)且状态 approved/checking 允许;删除后清理被删记录图片引用(失败仅告警不影响主流程)、重算 checked_items/diff_items/detail_status(主表状态不回退)、写 STOCK_CHECK_CLEAR_LOCATION 操作日志。", + "description": "重盘清除库位(按库位清除盘点信息,库位盘点模式专属):传盘点任务ID与库位ID,清除该库位范围内明细(scope_type=location)的全部作业记录(含空库位标记),该库位回到未盘;仅任务范围为库位(type=location)且状态 approved/checking 允许;删除后清理被删记录图片引用(失败仅告警不影响主流程)、重算 checked_items/diff_items/detail_status(主表状态不回退)、写 STOCK_CHECK_CLEAR_LOCATION 操作日志。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -40132,7 +40272,7 @@ } ], "notes": [ - "校验顺序口径(按代码实现顺序):任务ID 非正整数 → 400「盘点任务ID不能为空」;库位ID 非正整数 → 400「库位ID不能为空」;任务不存在(按 id+warehouse_id 查 wms_stock_check)→ 400「盘点任务不存在」;状态非 REPORT_ALLOWED_STATUSES(approved/checking)→ 400「当前状态(xx)不允许清除库位盘点信息」;任务范围非库位(type≠location/all)→ 400「仅库位盘点任务支持重盘清除库位」;库位不在任务范围(按 check_id+warehouse_id+location_id+scope_type=location 查 wms_stock_check_detail)→ 400「该库位不在盘点任务范围内」。代码依据:app/service/systems/stock_check.js#recheckClearLocation。", + "校验顺序口径(按代码实现顺序):任务ID 非正整数 → 400「盘点任务ID不能为空」;库位ID 非正整数 → 400「库位ID不能为空」;任务不存在(按 id+warehouse_id 查 wms_stock_check)→ 400「盘点任务不存在」;状态非 REPORT_ALLOWED_STATUSES(approved/checking)→ 400「当前状态(xx)不允许清除库位盘点信息」;任务范围非库位(type≠location)→ 400「仅库位盘点任务支持重盘清除库位」;库位不在任务范围(按 check_id+warehouse_id+location_id+scope_type=location 查 wms_stock_check_detail)→ 400「该库位不在盘点任务范围内」。代码依据:app/service/systems/stock_check.js#recheckClearLocation。", "行为口径:清除该库位范围内明细(scope_type=location)的全部作业记录(wms_stock_check_record,含空库位标记记录 is_empty=1),该库位回到未盘(明细无作业记录);删除后清理被删记录图片引用(FileReference business_type=stock_check_record,失败仅告警不影响主流程)、重算 checked_items/diff_items/detail_status(_recalcCheckSummary),主表状态不回退;写操作日志 operationCode=STOCK_CHECK_CLEAR_LOCATION(文案「重盘清除库位:删除作业记录 N 条」)。warehouse_id 由服务端从 ctx.user.store_id 自动注入,前端无需传递。", "权限口径:随 ALL_METHOD_NAMES(22 个,已由 21 增至 22、本次加入 recheckClearLocation,位于 recordDelete 之后)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(_noNeedAuth)、必须登录(isNeedLogin=true,免登录清单为空);为写操作,不在免日志清单(_noNeedLog)中,记录操作日志(STOCK_CHECK_CLEAR_LOCATION)。", "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内({ detail_id, location_id, deleted_count, total_items, checked_items, diff_items, detail_status })。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", diff --git a/script/stock-check-location-consistency.cjs b/script/stock-check-location-consistency.cjs new file mode 100644 index 0000000..e54b095 --- /dev/null +++ b/script/stock-check-location-consistency.cjs @@ -0,0 +1,329 @@ +'use strict'; + +/** + * 盘点库位一致性体检 / 订正脚本(wms_location_space 同编码重复 + 作业记录库位错挂)。 + * + * 背景:uk_warehouse_space_code 为 (warehouse_id, space_code, deleted_at),MySQL 唯一索引不对 + * NULL 去重,同编码可重复插入;分区删除后库位行未被软删 → 出现「无头库位」(zone 不存在/已删除) + * 与同编码多条并存。历史 stock.check.report 只按编码 findOne 猜库位,作业记录会挂到这些旧行上, + * 导致 stock.check.workData space 视图出现 custom_name 为 null 的幽灵行。 + * + * 用法: + * node script/stock-check-location-consistency.cjs # 开发库体检(只读) + * node script/stock-check-location-consistency.cjs --prod # 生产库体检(只读) + * node script/stock-check-location-consistency.cjs --prod --apply-record # 订正作业记录 location_id + * node script/stock-check-location-consistency.cjs --prod --sql-out=temp/fix-location.sql # 输出清理 SQL(不执行) + * + * 说明: + * 1. 默认只读;只有显式 --apply-record 才写库,且仅处理「记录库位编码 == 明细库位编码」且 + * 明细库位分区有效的安全场景(跨库位上报需人工确认,只统计不修改)。 + * 2. 无头库位清理不直接执行:--sql-out 生成 SQL 文件(含引用计数过滤),人工审核后再跑。 + */ + +const path = require('path'); +const fs = require('fs'); + +const PROJECT_ROOT = path.resolve(__dirname, '..'); + +/** + * 解析命令行参数。 + * @return {Object} 选项。 + */ +function parseArgs() { + const args = process.argv.slice(2); + const options = { + prod: false, + applyRecord: false, + sqlOut: '', + config: '', + }; + for (const arg of args) { + if (arg === '--prod') { + options.prod = true; + } else if (arg === '--apply-record') { + options.applyRecord = true; + } else if (arg.startsWith('--sql-out=')) { + options.sqlOut = arg.slice('--sql-out='.length); + } else if (arg.startsWith('--config=')) { + options.config = arg.slice('--config='.length); + } + } + return options; +} + +/** + * 读取数据库连接配置。 + * @param {Object} options 命令行选项。 + * @return {Object} mysql2 连接参数。 + */ +function resolveClient(options) { + const configPath = options.config + ? path.resolve(PROJECT_ROOT, options.config) + : path.resolve(PROJECT_ROOT, options.prod ? 'script/db-query-prod-config.js' : 'config/config.local.js'); + // eslint-disable-next-line global-require + const configFactory = require(configPath); + const config = typeof configFactory === 'function' ? configFactory({ name: 'wms-script' }) : configFactory; + const client = config && config.mysql && config.mysql.clients && config.mysql.clients.wms; + if (!client) { + throw new Error(`未在 ${configPath} 找到 mysql.clients.wms 配置`); + } + return { + host: client.host, + port: Number(client.port), + user: client.user, + password: client.password, + database: client.database, + charset: client.charset || 'utf8mb4', + connectTimeout: 20000, + enableKeepAlive: true, + }; +} + +/** 引用库位ID的业务表(列名 → 表名),用于判断无头库位是否仍被引用 */ +const SPACE_REFERENCE_COLUMNS = [ + [ 'wms_storage', 'space_id' ], + [ 'wms_picking', 'space_id' ], + [ 'wms_receiving_detail', 'space_id' ], + [ 'wms_storage_transaction', 'space_id' ], + [ 'wms_inbound_direct_log', 'space_id' ], + [ 'wms_stock_check_detail', 'location_id' ], + [ 'wms_stock_check_record', 'location_id' ], +]; + +/** 分批查询的批大小(避免 IN 列表过长 / 单条大查询超时) */ +const IN_CHUNK_SIZE = 500; + +/** + * 数组分块。 + * @param {Array} list 源数组。 + * @param {number} size 每块大小。 + * @return {Array} 分块结果。 + */ +function chunk(list, size) { + const result = []; + for (let i = 0; i < list.length; i += size) { + result.push(list.slice(i, i + size)); + } + return result; +} + +/** 有效库位判定 SQL(分区存在且未删除) */ +const VALID_SPACE_SQL = '(SELECT ls.id FROM wms_location_space ls ' + + 'JOIN wms_location_zone z ON z.id = ls.zone_id AND z.deleted_at IS NULL ' + + 'WHERE ls.deleted_at IS NULL)'; + +/** + * 记录当前库位不可用判定(为空 / 行不存在 / 已归档 / 所属分区不存在或已删除)。 + * 订正只允许改动这类「坏记录」,已经是有效库位的记录一律不动。 + */ +const BROKEN_RECORD_LOCATION_SQL = '(r.location_id IS NULL OR NOT EXISTS (' + + 'SELECT 1 FROM wms_location_space cur ' + + 'JOIN wms_location_zone cz ON cz.id = cur.zone_id AND cz.deleted_at IS NULL ' + + 'WHERE cur.id = r.location_id AND cur.deleted_at IS NULL))'; + +/** 同编码订正目标表达式(明细固化库位,且分区有效) */ +const SAME_CODE_TARGET_JOIN = 'JOIN wms_stock_check_detail d ON d.id = r.detail_id AND d.check_id = r.check_id ' + + 'JOIN wms_location_space good ON good.id = d.location_id AND good.deleted_at IS NULL ' + + 'JOIN wms_location_zone gz ON gz.id = good.zone_id AND gz.deleted_at IS NULL'; + +/** 跨编码订正目标(同仓库同编码、分区有效,取 id 最小);同时 JOIN 明细用于排除「编码本就等于明细编码」的记录 */ +const CROSS_CODE_TARGET_JOIN = 'JOIN wms_stock_check_detail d ON d.id = r.detail_id AND d.check_id = r.check_id ' + + 'JOIN (' + + 'SELECT ls.warehouse_id, ls.space_code, MIN(ls.id) target_id FROM wms_location_space ls ' + + 'JOIN wms_location_zone z ON z.id = ls.zone_id AND z.deleted_at IS NULL ' + + 'WHERE ls.deleted_at IS NULL GROUP BY ls.warehouse_id, ls.space_code' + + ') t ON t.warehouse_id = r.warehouse_id AND t.space_code = r.location_code'; + +/** + * 主流程。 + * @return {Promise} 无返回值。 + */ +async function main() { + const options = parseArgs(); + // eslint-disable-next-line global-require + const mysql = require(path.join(PROJECT_ROOT, 'node_modules/mysql2/promise')); + const client = resolveClient(options); + const connection = await mysql.createConnection(client); + const summary = { target: `${client.host}:${client.port}/${client.database}`, applyRecord: options.applyRecord }; + + try { + const [ warehouses ] = await connection.query( + 'SELECT warehouse_id, COUNT(*) space_cnt FROM wms_location_space WHERE deleted_at IS NULL GROUP BY warehouse_id' + ); + summary.warehouseCount = warehouses.length; + + // 1) 无头库位(分区不存在/已删除)ID 列表与总数 + const [ headlessIdRows ] = await connection.query( + `SELECT ls.id FROM wms_location_space ls + WHERE ls.deleted_at IS NULL AND ls.id NOT IN ${VALID_SPACE_SQL}` + ); + const headlessIds = headlessIdRows.map(row => Number(row.id)).filter(id => id > 0); + const headlessIdSet = new Set(headlessIds); + summary.headlessSpaceCount = headlessIds.length; + + // 2) 同编码重复分组 + const [ dupRows ] = await connection.query( + `SELECT COUNT(*) group_cnt, COALESCE(SUM(c), 0) rows_in_dup FROM ( + SELECT warehouse_id, space_code, COUNT(*) c FROM wms_location_space + WHERE deleted_at IS NULL GROUP BY warehouse_id, space_code HAVING COUNT(*) > 1 + ) t` + ); + summary.duplicateCodeGroups = Number(dupRows[0].group_cnt) || 0; + summary.rowsInDuplicateGroups = Number(dupRows[0].rows_in_dup) || 0; + + // 3) 作业记录库位错挂统计(记录库位编码 == 明细库位编码,但 location_id 不同) + const [ sameCodeRows ] = await connection.query( + `SELECT COUNT(*) cnt, + SUM(CASE WHEN good.id IS NOT NULL THEN 1 ELSE 0 END) fixable + FROM wms_stock_check_record r + JOIN wms_stock_check_detail d ON d.id = r.detail_id AND d.check_id = r.check_id + LEFT JOIN wms_location_space good ON good.id = d.location_id AND good.deleted_at IS NULL + WHERE r.location_code = d.location_code + AND (r.location_id IS NULL OR r.location_id <> d.location_id)` + ); + summary.sameCodeMismatchRecords = Number(sameCodeRows[0].cnt) || 0; + summary.sameCodeFixable = Number(sameCodeRows[0].fixable) || 0; + + // 4) 跨库位上报(记录编码 != 明细编码)——需人工确认,不自动改 + const [ crossCodeRows ] = await connection.query( + `SELECT COUNT(*) cnt FROM wms_stock_check_record r + JOIN wms_stock_check_detail d ON d.id = r.detail_id AND d.check_id = r.check_id + WHERE r.location_code <> d.location_code` + ); + summary.crossCodeRecords = Number(crossCodeRows[0].cnt) || 0; + + // 5) 无头库位中「无任何引用」的候选清理数:先取无头库位 id(小集合),再按表分批 IN 查引用, + // 避免在 wms_storage_transaction / wms_inbound_direct_log 等大表上做相关 NOT EXISTS 导致超时 + const referencedHeadlessIds = new Set(); + for (const [ table, column ] of SPACE_REFERENCE_COLUMNS) { + for (const ids of chunk(headlessIds, IN_CHUNK_SIZE)) { + const [ refRows ] = await connection.query( + `SELECT DISTINCT ${column} AS id FROM ${table} WHERE ${column} IN (?)`, + [ ids ] + ); + for (const refRow of refRows) { + const refId = Number(refRow.id); + if (headlessIdSet.has(refId)) { + referencedHeadlessIds.add(refId); + } + } + } + } + summary.headlessReferencedCount = referencedHeadlessIds.size; + summary.headlessOrphanCount = headlessIds.length - referencedHeadlessIds.size; + + // 6) 需人工处理的重复编码 Top 10(按行数) + const [ topDup ] = await connection.query( + `SELECT warehouse_id, space_code, COUNT(*) c FROM wms_location_space + WHERE deleted_at IS NULL GROUP BY warehouse_id, space_code HAVING COUNT(*) > 1 + ORDER BY c DESC, space_code ASC LIMIT 10` + ); + summary.topDuplicates = topDup.map(row => ({ + warehouse_id: Number(row.warehouse_id), + space_code: row.space_code, + rows: Number(row.c), + })); + + // 7) 订正作业记录 location_id(仅安全场景,默认只读): + // a. 记录编码 == 明细编码 → 改挂明细固化库位(分区有效) + // b. 记录编码 != 明细编码(跨库位上报)→ 改挂「同仓库同编码、分区有效」的库位行(取 id 最小) + // 两条都只处理当前 location_id 不可用的坏记录(为空/不存在/已归档/分区已删),已经有效的记录不动 + const [ drySameCode ] = await connection.query( + `SELECT COUNT(*) cnt FROM wms_stock_check_record r ${SAME_CODE_TARGET_JOIN} + WHERE r.location_code = d.location_code AND r.location_id <> d.location_id + AND ${BROKEN_RECORD_LOCATION_SQL}` + ); + const [ dryCrossCode ] = await connection.query( + `SELECT COUNT(*) cnt FROM wms_stock_check_record r ${CROSS_CODE_TARGET_JOIN} + WHERE r.location_code <> d.location_code + AND r.location_id <> t.target_id AND ${BROKEN_RECORD_LOCATION_SQL}` + ); + summary.wouldUpdateSameCode = Number(drySameCode[0].cnt) || 0; + summary.wouldUpdateCrossCode = Number(dryCrossCode[0].cnt) || 0; + + if (options.applyRecord) { + const [ sameCodeResult ] = await connection.query( + `UPDATE wms_stock_check_record r ${SAME_CODE_TARGET_JOIN} + SET r.location_id = d.location_id + WHERE r.location_code = d.location_code + AND r.location_id <> d.location_id + AND ${BROKEN_RECORD_LOCATION_SQL}` + ); + const [ crossCodeResult ] = await connection.query( + `UPDATE wms_stock_check_record r ${CROSS_CODE_TARGET_JOIN} + SET r.location_id = t.target_id + WHERE r.location_code <> d.location_code + AND r.location_id <> t.target_id + AND ${BROKEN_RECORD_LOCATION_SQL}` + ); + summary.updatedRecords = (Number(sameCodeResult.affectedRows) || 0) + + (Number(crossCodeResult.affectedRows) || 0); + summary.updatedRecordsSameCode = Number(sameCodeResult.affectedRows) || 0; + summary.updatedRecordsCrossCode = Number(crossCodeResult.affectedRows) || 0; + } + + // 8) 生成无头库位清理 SQL(不执行) + if (options.sqlOut) { + const outPath = path.resolve(PROJECT_ROOT, options.sqlOut); + const sql = [ + '-- 由 script/stock-check-location-consistency.cjs 生成,请人工审核后执行', + `-- target: ${summary.target}`, + '-- 1) 盘点作业记录 location_id 订正(只改当前库位不可用的坏记录:为空/不存在/已归档/分区已删)', + '-- 1.1 记录编码 == 明细编码 → 改挂明细固化库位(要求明细库位分区有效)', + 'UPDATE wms_stock_check_record r', + ' JOIN wms_stock_check_detail d ON d.id = r.detail_id AND d.check_id = r.check_id', + ' JOIN wms_location_space good ON good.id = d.location_id AND good.deleted_at IS NULL', + ' JOIN wms_location_zone gz ON gz.id = good.zone_id AND gz.deleted_at IS NULL', + ' SET r.location_id = d.location_id', + ' WHERE r.location_code = d.location_code', + ' AND r.location_id <> d.location_id', + ` AND ${BROKEN_RECORD_LOCATION_SQL.replace(/\n/g, ' ')};`, + '', + '-- 1.2 跨库位上报(记录编码 != 明细编码)→ 改挂同仓库同编码、分区有效的库位行(取 id 最小)', + 'UPDATE wms_stock_check_record r', + ' JOIN wms_stock_check_detail d ON d.id = r.detail_id AND d.check_id = r.check_id', + ' JOIN (', + ' SELECT ls.warehouse_id, ls.space_code, MIN(ls.id) target_id', + ' FROM wms_location_space ls', + ' JOIN wms_location_zone z ON z.id = ls.zone_id AND z.deleted_at IS NULL', + ' WHERE ls.deleted_at IS NULL', + ' GROUP BY ls.warehouse_id, ls.space_code', + ' ) t ON t.warehouse_id = r.warehouse_id AND t.space_code = r.location_code', + ' SET r.location_id = t.target_id', + ' WHERE r.location_code <> d.location_code', + ' AND r.location_id <> t.target_id', + ` AND ${BROKEN_RECORD_LOCATION_SQL.replace(/\n/g, ' ')};`, + '', + '-- 2) 无头库位软删除(仅无任何业务引用的孤行;有引用的需人工合并到有效库位)', + 'UPDATE wms_location_space ls', + ' SET ls.deleted_at = NOW()', + ' WHERE ls.deleted_at IS NULL', + ` AND ls.id NOT IN ${VALID_SPACE_SQL}`, + ' AND NOT EXISTS (SELECT 1 FROM wms_storage s WHERE s.space_id = ls.id)', + ' AND NOT EXISTS (SELECT 1 FROM wms_picking p WHERE p.space_id = ls.id)', + ' AND NOT EXISTS (SELECT 1 FROM wms_receiving_detail rd WHERE rd.space_id = ls.id)', + ' AND NOT EXISTS (SELECT 1 FROM wms_storage_transaction st WHERE st.space_id = ls.id)', + ' AND NOT EXISTS (SELECT 1 FROM wms_inbound_direct_log il WHERE il.space_id = ls.id)', + ' AND NOT EXISTS (SELECT 1 FROM wms_stock_check_detail d WHERE d.location_id = ls.id)', + ' AND NOT EXISTS (SELECT 1 FROM wms_stock_check_record r WHERE r.location_id = ls.id);', + '', + '-- 3) 清理后复查:仍重复的编码(需人工决定保留哪一行)', + 'SELECT warehouse_id, space_code, COUNT(*) c FROM wms_location_space', + ' WHERE deleted_at IS NULL GROUP BY warehouse_id, space_code HAVING COUNT(*) > 1;', + '', + ].join('\n'); + fs.mkdirSync(path.dirname(outPath), { recursive: true }); + fs.writeFileSync(outPath, sql, 'utf8'); + summary.sqlOut = outPath; + } + + console.log(JSON.stringify(summary, null, 2)); + } finally { + await connection.end(); + } +} + +main().catch(error => { + console.error('[stock-check-location-consistency] 执行失败:', error.message); + process.exit(1); +}); diff --git a/script/stock-check-record-deleted-location.cjs b/script/stock-check-record-deleted-location.cjs new file mode 100644 index 0000000..4d1df7b --- /dev/null +++ b/script/stock-check-record-deleted-location.cjs @@ -0,0 +1,223 @@ +'use strict'; + +/** + * 盘点作业记录「库位指向异常」体检(只读)。 + * + * 输出三类异常,均以 wms_stock_check_record.location_id 为准: + * A 已归档库位:location_id 命中 wms_location_space 且 deleted_at IS NOT NULL(软删除/归档行) + * B 无头库位:库位未归档,但所属 zone 不存在或已删除(分区被删后库位行漏归档) + * C 悬空库位:location_id 在 wms_location_space 中查不到(行已被物理删除) + * + * 用法: + * node script/stock-check-record-deleted-location.cjs # 开发库(只读) + * node script/stock-check-record-deleted-location.cjs --prod # 生产库(只读) + * node script/stock-check-record-deleted-location.cjs --prod --limit=30 --top=30 + * node script/stock-check-record-deleted-location.cjs --prod --csv-out=temp/records.csv + */ + +const path = require('path'); +const fs = require('fs'); + +const PROJECT_ROOT = path.resolve(__dirname, '..'); + +/** + * 解析命令行参数。 + * @return {Object} 选项。 + */ +function parseArgs() { + const args = process.argv.slice(2); + const options = { prod: false, limit: 20, top: 20, csvOut: '', config: '' }; + for (const arg of args) { + if (arg === '--prod') { + options.prod = true; + } else if (arg.startsWith('--limit=')) { + options.limit = Math.max(1, Number(arg.slice('--limit='.length)) || 20); + } else if (arg.startsWith('--top=')) { + options.top = Math.max(1, Number(arg.slice('--top='.length)) || 20); + } else if (arg.startsWith('--csv-out=')) { + options.csvOut = arg.slice('--csv-out='.length); + } else if (arg.startsWith('--config=')) { + options.config = arg.slice('--config='.length); + } + } + return options; +} + +/** + * 读取数据库连接配置。 + * @param {Object} options 命令行选项。 + * @return {Object} mysql2 连接参数。 + */ +function resolveClient(options) { + const configPath = options.config + ? path.resolve(PROJECT_ROOT, options.config) + : path.resolve(PROJECT_ROOT, options.prod ? 'script/db-query-prod-config.js' : 'config/config.local.js'); + // eslint-disable-next-line global-require + const configFactory = require(configPath); + const config = typeof configFactory === 'function' ? configFactory({ name: 'wms-script' }) : configFactory; + const client = config && config.mysql && config.mysql.clients && config.mysql.clients.wms; + if (!client) { + throw new Error(`未在 ${configPath} 找到 mysql.clients.wms 配置`); + } + return { + host: client.host, + port: Number(client.port), + user: client.user, + password: client.password, + database: client.database, + charset: client.charset || 'utf8mb4', + }; +} + +/** 分类条件(A 已归档 / B 无头 / C 悬空 / D 无库位ID),均以记录 location_id 为基准 */ +const CATEGORY_SQL = { + A: 'ls.id IS NOT NULL AND ls.deleted_at IS NOT NULL', + B: 'ls.id IS NOT NULL AND ls.deleted_at IS NULL AND (z.id IS NULL OR z.deleted_at IS NOT NULL)', + C: 'r.location_id IS NOT NULL AND ls.id IS NULL', + D: 'r.location_id IS NULL', +}; + +const BASE_FROM = `FROM wms_stock_check_record r + LEFT JOIN wms_stock_check c ON c.id = r.check_id + LEFT JOIN wms_location_space ls ON ls.id = r.location_id + LEFT JOIN wms_location_zone z ON z.id = ls.zone_id`; + +/** + * 主流程。 + * @return {Promise} 无返回值。 + */ +async function main() { + const options = parseArgs(); + // eslint-disable-next-line global-require + const mysql = require(path.join(PROJECT_ROOT, 'node_modules/mysql2/promise')); + const client = resolveClient(options); + const connection = await mysql.createConnection(client); + + try { + const summary = { target: `${client.host}:${client.port}/${client.database}`, categories: {} }; + const [ totalRows ] = await connection.query('SELECT COUNT(*) cnt FROM wms_stock_check_record'); + summary.totalRecords = Number(totalRows[0].cnt) || 0; + + for (const [ key, condition ] of Object.entries(CATEGORY_SQL)) { + const [ rows ] = await connection.query( + `SELECT COUNT(*) cnt, COUNT(DISTINCT r.check_id) checks FROM wms_stock_check_record r + LEFT JOIN wms_location_space ls ON ls.id = r.location_id + LEFT JOIN wms_location_zone z ON z.id = ls.zone_id + WHERE ${condition}` + ); + summary.categories[key] = { + records: Number(rows[0].cnt) || 0, + checks: Number(rows[0].checks) || 0, + }; + } + + // 明细明细:A(已归档库位)与 B(无头库位)分别出「按盘点单 / 按库位 / 样本」三段 + summary.details = {}; + for (const key of [ 'A', 'B' ]) { + const condition = CATEGORY_SQL[key]; + const [ topChecks ] = await connection.query( + `SELECT r.check_id, MAX(c.check_no) check_no, MAX(r.warehouse_id) warehouse_id, + COUNT(*) records, COUNT(DISTINCT r.detail_id) details + ${BASE_FROM} + WHERE ${condition} + GROUP BY r.check_id + ORDER BY records DESC + LIMIT ${options.top}` + ); + const [ topLocations ] = await connection.query( + `SELECT r.location_id, MAX(ls.space_code) space_code, MAX(ls.zone_id) zone_id, + COUNT(*) records, COUNT(DISTINCT r.check_id) checks + ${BASE_FROM} + WHERE ${condition} + GROUP BY r.location_id + ORDER BY records DESC + LIMIT ${options.top}` + ); + const [ samples ] = await connection.query( + `SELECT r.id record_id, r.check_id, c.check_no, r.detail_id, r.stock_id, + r.location_id, r.location_code, ls.space_code space_code, ls.zone_id zone_id, + z.id zone_exists, z.deleted_at zone_deleted_at, + r.quantity, r.checker_name, r.checked_at + ${BASE_FROM} + WHERE ${condition} + ORDER BY r.id DESC + LIMIT ${options.limit}` + ); + summary.details[key] = { + topChecks: topChecks.map(row => ({ + check_id: Number(row.check_id), + check_no: row.check_no, + warehouse_id: Number(row.warehouse_id), + records: Number(row.records), + details: Number(row.details), + })), + topLocations: topLocations.map(row => ({ + location_id: Number(row.location_id), + space_code: row.space_code, + zone_id: row.zone_id === null ? null : Number(row.zone_id), + records: Number(row.records), + checks: Number(row.checks), + })), + samples: samples.map(row => ({ + record_id: Number(row.record_id), + check_id: Number(row.check_id), + check_no: row.check_no, + detail_id: Number(row.detail_id), + stock_id: row.stock_id === null ? null : Number(row.stock_id), + location_id: Number(row.location_id), + record_location_code: row.location_code, + space_code: row.space_code, + zone_id: row.zone_id === null ? null : Number(row.zone_id), + zone_exists: row.zone_exists !== null && row.zone_exists !== undefined, + zone_deleted_at: row.zone_deleted_at, + quantity: Number(row.quantity), + checker_name: row.checker_name, + checked_at: row.checked_at, + })), + }; + } + + if (options.csvOut) { + const header = 'category,record_id,check_id,check_no,detail_id,stock_id,location_id,record_location_code,detail_location_code,detail_location_id,space_code,zone_id,zone_exists,zone_deleted_at,quantity,checker_name,checked_at'; + const lines = []; + for (const key of [ 'A', 'B' ]) { + if ((summary.categories[key].records || 0) === 0) { + continue; + } + const [ rows ] = await connection.query( + `SELECT r.id record_id, r.check_id, c.check_no, r.detail_id, r.stock_id, + r.location_id, r.location_code, d.location_code detail_location_code, + d.location_id detail_location_id, ls.space_code space_code, ls.zone_id zone_id, + z.id zone_exists, z.deleted_at zone_deleted_at, + r.quantity, r.checker_name, r.checked_at + ${BASE_FROM} + LEFT JOIN wms_stock_check_detail d ON d.id = r.detail_id AND d.check_id = r.check_id + WHERE ${CATEGORY_SQL[key]} + ORDER BY r.check_id ASC, r.id ASC` + ); + for (const item of rows) { + lines.push([ + key, item.record_id, item.check_id, item.check_no, item.detail_id, item.stock_id, + item.location_id, item.location_code, item.detail_location_code, item.detail_location_id, + item.space_code, item.zone_id, item.zone_exists ? 1 : 0, item.zone_deleted_at, + item.quantity, item.checker_name, + item.checked_at instanceof Date ? item.checked_at.toISOString() : item.checked_at, + ].map(value => (value === null || value === undefined ? '' : String(value).replace(/,/g, ' '))).join(',')); + } + } + const outPath = path.resolve(PROJECT_ROOT, options.csvOut); + fs.mkdirSync(path.dirname(outPath), { recursive: true }); + fs.writeFileSync(outPath, [ header, ...lines ].join('\n'), 'utf8'); + summary.csvOut = outPath; + } + + console.log(JSON.stringify(summary, null, 2)); + } finally { + await connection.end(); + } +} + +main().catch(error => { + console.error('[stock-check-record-deleted-location] 执行失败:', error.message); + process.exit(1); +});