diff --git a/app/service/systems/waybill.js b/app/service/systems/waybill.js index 46403d5..66f1452 100644 --- a/app/service/systems/waybill.js +++ b/app/service/systems/waybill.js @@ -147,6 +147,54 @@ class WaybillService extends MainService { }; } + /** + * 解析主单号筛选条件(单值 / 数组 / 标准 where 对象),返回对应订单ID列表。 + * 先按主单号(business_key=1)在 wms_order_express 中定位 order_id,调用方再据此查询订单下所有运单(主+子)。 + * + * @param {*} mainWaybillCode 主单号条件值(字符串 / 字符串数组 / {operator,value} 标准化对象)。 + * @param {number} warehouseId 仓库ID(仓库隔离)。 + * @return {Promise<{empty: boolean, orderIds: number[]}>} empty=true 表示所有主单号均不存在,调用方应直接返回空结果;orderIds 去重后的订单ID列表。 + */ + async resolveMainWaybillOrderIds(mainWaybillCode, warehouseId) { + const { ctx, app } = this; + const { Op } = app.Sequelize; + + const codes = (Array.isArray(mainWaybillCode) ? mainWaybillCode : [ mainWaybillCode ]) + .map(code => (code === undefined || code === null ? '' : String(code).trim())) + .filter(code => code !== ''); + + if (codes.length === 0) { + return { empty: false, orderIds: [] }; + } + + const mainRecords = await ctx.model.OrderExpress.findAll({ + where: { + waybill_code: { [Op.in]: codes }, + business_key: 1, + warehouse_id: warehouseId, + }, + attributes: [ 'order_id' ], + raw: true, + }); + + if (!mainRecords || mainRecords.length === 0) { + return { empty: true, orderIds: [] }; + } + + const orderIds = []; + for (const record of mainRecords) { + const orderId = Number(record.order_id); + if (Number.isFinite(orderId) && !orderIds.includes(orderId)) { + orderIds.push(orderId); + } + } + if (orderIds.length === 0) { + return { empty: true, orderIds: [] }; + } + + return { empty: false, orderIds }; + } + /** * 运单列表查询(仓库侧)。 * 按仓库维度查询运单号列表,支持分页、多条件筛选、排序。 @@ -154,7 +202,7 @@ class WaybillService extends MainService { * 主单号通过 SELF JOIN 同 order_id 下 business_key=1 的记录获取。 * * @param {Object} [options={}] 查询参数。 - * @param {Object} [options.where] 筛选条件,支持 waybillCode(字符串模糊匹配 / 字符串数组精确匹配)/ mainWaybillCode / orderId / orderNo / logisticsCode / logisticsInterfaceId / platformCode / status / isBack / isIntercept / isGalaxyReceive / packageMaterialId / hasWeighingWeight / keyword / createdAt({operator:'between', value:[start,end]},兼容 createAt 别名)/ createdAtStart / createdAtEnd(旧写法兼容)。 + * @param {Object} [options.where] 筛选条件,支持 waybillCode(字符串模糊匹配 / 字符串数组精确匹配)/ mainWaybillCode(字符串 / 字符串数组精确匹配,数组时返回多个主单对应订单下的运单)/ orderId / orderNo / logisticsCode / logisticsInterfaceId / platformCode / status / isBack / isIntercept / isGalaxyReceive / packageMaterialId / hasWeighingWeight / keyword / createdAt({operator:'between', value:[start,end]},兼容 createAt 别名)/ createdAtStart / createdAtEnd(旧写法兼容)。 * @param {Object} [options.pagination] 分页参数 { page, pageSize },默认 page=1, pageSize=20。 * @param {Object} [options.sort] 排序参数 { field, order },默认 create_at desc。 * @return {Promise} 运单列表与分页信息 { list, pagination }。 @@ -198,28 +246,20 @@ class WaybillService extends MainService { // 构建查询条件 const queryWhere = { warehouse_id: warehouseId }; - // 主单号查询:先通过主单号定位 order_id,再查该 order 下所有运单 - const mainWaybillCode = val(where.mainWaybillCode); - if (mainWaybillCode && String(mainWaybillCode).trim()) { - const mainCode = String(mainWaybillCode).trim(); - const mainRecord = await ctx.model.OrderExpress.findOne({ - where: { - waybill_code: mainCode, - business_key: 1, - warehouse_id: warehouseId, - }, - attributes: [ 'order_id' ], - raw: true, - }); - if (mainRecord) { - queryWhere.order_id = mainRecord.order_id; - } else { - // 主单号不存在,直接返回空结果 - return { - list: [], - pagination: { page, pageSize, total: 0, totalPages: 0 }, - }; - } + // 主单号查询:先通过主单号(支持单值/数组)定位 order_id,再查这些订单下所有运单(主+子) + const mainResolved = await this.resolveMainWaybillOrderIds(val(where.mainWaybillCode), warehouseId); + if (mainResolved.empty) { + // 主单号均不存在,直接返回空结果 + return { + list: [], + pagination: { page, pageSize, total: 0, totalPages: 0 }, + }; + } + if (mainResolved.orderIds.length > 0) { + // 单主单保持标量 order_id(向后兼容),多主单使用 Op.in + queryWhere.order_id = mainResolved.orderIds.length === 1 + ? mainResolved.orderIds[0] + : { [Op.in]: mainResolved.orderIds }; } // 运单号搜索:数组精确匹配(Op.in),字符串保持模糊匹配(Op.like) @@ -741,27 +781,19 @@ class WaybillService extends MainService { } } - // 主单号查询 - const mainWaybillCodeExport = val(where.mainWaybillCode); - if (mainWaybillCodeExport && String(mainWaybillCodeExport).trim()) { - const mainCode = String(mainWaybillCodeExport).trim(); - const mainRecord = await ctx.model.OrderExpress.findOne({ - where: { - waybill_code: mainCode, - business_key: 1, - warehouse_id: warehouseId, - }, - attributes: [ 'order_id' ], - raw: true, - }); - if (mainRecord) { - queryWhere.order_id = mainRecord.order_id; - } else { - if (typeof onProgress === 'function') { - await onProgress({ status: 'success', progress: 100, currentCount: 0, totalCount: 0, message: '导出完成', result: { list: [], url: '' } }); - } - return { list: [], current_count: 0, total_count: 0, url: '' }; + // 主单号查询(支持单值/数组,与 list 保持一致) + const mainResolvedExport = await this.resolveMainWaybillOrderIds(val(where.mainWaybillCode), warehouseId); + if (mainResolvedExport.empty) { + if (typeof onProgress === 'function') { + await onProgress({ status: 'success', progress: 100, currentCount: 0, totalCount: 0, message: '导出完成', result: { list: [], url: '' } }); } + return { list: [], current_count: 0, total_count: 0, url: '' }; + } + if (mainResolvedExport.orderIds.length > 0) { + // 单主单保持标量 order_id(向后兼容),多主单使用 Op.in + queryWhere.order_id = mainResolvedExport.orderIds.length === 1 + ? mainResolvedExport.orderIds[0] + : { [Op.in]: mainResolvedExport.orderIds }; } // 运单号搜索:数组精确匹配(Op.in),字符串保持模糊匹配(Op.like),与 list 保持一致 diff --git a/database/designs/waybill-module-design.md b/database/designs/waybill-module-design.md index af311a6..05f2d31 100644 --- a/database/designs/waybill-module-design.md +++ b/database/designs/waybill-module-design.md @@ -255,6 +255,8 @@ POST /system { method: "waybill.warehouse.list", ... } } ``` +> `where.mainWaybillCode` 支持字符串或字符串数组:`"SF1234567890"`(单主单)或 `["SF1234567890", "SF0987654321"]`(多主单,按 `IN` 精确匹配)。上例以单值展示。 + #### 参数说明 | 参数 | 类型 | 必填 | 说明 | @@ -262,7 +264,7 @@ POST /system { method: "waybill.warehouse.list", ... } | `pagination` | `object` | ✗ | 分页参数 `{ page, pageSize }`,默认 page=1, pageSize=20 | | `where` | `object` | ✗ | 筛选条件,所有字段均为可选 | | `where.waybillCode` | `string` | ✗ | 运单号(模糊搜索) | -| `where.mainWaybillCode` | `string` | ✗ | **主单号**(精确匹配)。先通过主单号定位 `order_id`,再返回该订单下所有运单(主+子)。与 `waybillCode` 互斥,同时传入时 `mainWaybillCode` 优先 | +| `where.mainWaybillCode` | `string \| string[]` | ✗ | **主单号**(精确匹配,2026-10-04 起支持数组)。单值:先通过主单号定位 `order_id`,再返回该订单下所有运单(主+子);数组:按 `Op.in` 匹配多个主单号,返回这些主单对应订单下的全部运单。与 `waybillCode` 同时传入时按 AND 叠加,不做互斥优先级处理。空数组/全空值不加该条件;主单号均不存在时直接返回空列表 | | `where.waybillType` | `string` | ✗ | 🆕 **运单类型**:`"main"`/`"1"`=主单号(`business_key=1`),`"child"`/`"2"`=子单号(`business_key>1`) | | `where.orderId` | `number` | ✗ | 订单ID(等值) | | `where.orderNo` | `string` | ✗ | ⛔ **暂不可用**:订单号(待快照字段 `delivery_order_code` 落库后启用 LIKE 模糊搜索) | @@ -367,7 +369,7 @@ POST /system { method: "waybill.warehouse.list", ... } 1. **仓库隔离**:自动注入 `warehouse_id = ctx.user.store_id`(系统统一约定,`ctx.user.store_id` 即为当前用户所属仓库ID)。所有查询 WHERE 条件自动追加 `warehouse_id`,不可由前端入参覆盖 2. **主单号关联查询**:每条运单记录通过 SELF JOIN(`t1.order_id = t2.order_id AND t2.business_key = 1`)获取主单号 `main_waybill_code`。当 `business_key = 1` 时,主单号就是自身 `waybill_code`;当 `business_key > 1` 时,需要 JOIN 获取主单号 -3. **按主单号入参查询**:当 `where.mainWaybillCode` 传入时,先通过主单号 `waybill_code` 定位 `order_id`(`WHERE waybill_code = ? AND business_key = 1`),再 `WHERE order_id = ?` 返回该订单下所有运单(主+子) +3. **按主单号入参查询**:当 `where.mainWaybillCode` 传入时,先通过主单号 `waybill_code` 定位 `order_id`,再返回该订单下所有运单(主+子)。**支持单值 / 数组**(2026-10-04):单值保持 `WHERE waybill_code = ? AND business_key = 1 AND warehouse_id = ?` → `WHERE order_id = ?`(标量,向后兼容);数组按 `WHERE waybill_code IN (?, ?) AND business_key = 1 AND warehouse_id = ?` → `WHERE order_id IN (?, ?)`(去重后 `Op.in`),返回多个主单对应订单下的全部运单;元素自动 trim 并过滤空值,全部主单号不存在时直接返回空列表,空数组/全空值数组不添加该条件 4. **按物流接口ID查询**:直接 `WHERE logistics_interface_id = ?`,等值匹配 5. **订单号模糊搜索**:当 `where.orderNo` 或 `where.keyword` 匹配到非纯数字运单号时,需要 JOIN 订单表(current/history/dispatch)进行 `delivery_order_code LIKE` 匹配 6. **打印次数**:通过子查询或 LEFT JOIN + GROUP BY `express_print_record.express_no = waybill_code` 聚合 @@ -609,7 +611,7 @@ POST /system { method: "waybill.warehouse.list", ... } |---|------|------|------|------| | — | `warehouse_id` | — | = | ✅ 自动注入 | | 1 | `waybillCode` | string | LIKE | ✅ | -| 2 | `mainWaybillCode` | string | 精确→order_id | ✅ | +| 2 | `mainWaybillCode` | string \| string[] | 精确→order_id(数组 Op.in) | ✅ 🆕 | | 3 | `waybillType` | string | `main/1`→bk=1, `child/2`→bk>1 | ✅ 🆕 | | 4 | `orderId` | number | = | ✅ | | 5 | `orderNo` | string | LIKE | ⛔ 待快照 | diff --git a/methods/changes/system.json b/methods/changes/system.json index 3106d98..edef7ba 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,282 @@ [ + { + "version": "0.3.243", + "date": "2026-10-04", + "type": "updated", + "summary": "waybill.warehouse.list/export 的 where.mainWaybillCode 支持字符串数组(多主单号精确匹配,Op.in 定位 order_id 集合,0.3.242 → 0.3.243)", + "methods": [ + "waybill.warehouse.list", + "waybill.warehouse.export" + ], + "notes": [ + "变更内容:where.mainWaybillCode 由「仅字符串单值」扩展为「字符串 | 字符串数组」;数组时按 Op.in 精确匹配多个主单号,先定位 order_id 集合,再返回/导出这些订单下的全部运单(主+子)。单值行为完全不变(order_id 条件仍为标量)。", + "边界:数组元素自动 trim 并过滤空值;全部不存在时直接返回空结果(list 空列表 / export total_count=0);空数组或全空值数组不添加该筛选条件;与 waybillCode 同时传入时按 AND 叠加。仓库隔离(warehouse_id = ctx.user.store_id)不受影响。", + "文档修正:原描述「与 waybillCode 互斥,同时传入时 mainWaybillCode 优先」与实际实现不符(实现为 AND 叠加),本次一并更正。", + "代码依据:app/service/systems/waybill.js#resolveMainWaybillOrderIds(list/export 共用);回归测试 test/app/service/systems/waybill.warehouse.mainWaybillCode.in.test.js。", + "库表维护源说明:维护源为库表(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 往返校验;生产库需另行同步。" + ] + }, + { + "version": "2026.10.03-stock-check-workdata-view-only", + "date": "2026-10-03", + "type": "updated", + "summary": "stock.check.workData 不返回任务主表信息 check,改为返回 view(解析后的视图类型 location/goods/space);任务信息统一由 stock.check.detail 返回", + "methods": [ + "stock.check.workData" + ], + "notes": [ + "代码依据:app/service/systems/stock_check.js#workData 返回体由 { check, rows, total, page, pageSize } 改为 { view, rows, total, page, pageSize }(check 仍内部查询用于视图解析/盲盘明盘/状态守卫;view=resolvedView);app/service/systemMethods/stock/check.js#workData 仅同步 JSDoc(行为不变,仍统一 success/failure 包装)。", + "测试同步:test/app/service/systems/stock_check.test.js(workData 用例移除 data.check.* 断言、新增「响应键集合为 page/pageSize/rows/total/view」「三视图 view 断言(location/goods/space、库位任务无视 is_goods、is_goods 非 true 走 space)」「方法层不返回 check 且 view=goods」;盲盘/明盘模式断言改由 findCheckRow 从库表核对);真实库集成测试 213/213 通过、ESLint 0 错误。", + "兼容性影响:响应 data 移除 check 字段(破坏性变更)、新增 view 字段;rows/total/page/pageSize 与 location/goods/space 三视图结构、明盘盲盘数量控制、状态限制均不变;前端如需任务主表信息改调 stock.check.detail,如需判断行结构可直接读取 view,无需再自行按任务类型/is_goods 推导。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(description/response(data.children 以 view 替换 check)/notes 同步;headers/params/errors/isNeedAuth/isNeedLogin 不变);根版本 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 往返校验),保持库与文件一致。" + ] + }, + { + "version": "2026.10.03-stock-check-detail-task-only", + "date": "2026-10-03", + "type": "updated", + "summary": "stock.check.detail 精简为只返回任务本身信息({ check }),不再返回明细范围行 rows 与 total(明细范围行/盘点结果改由 stock.check.result 返回)", + "methods": [ + "stock.check.detail" + ], + "notes": [ + "代码依据:app/service/systems/stock_check.js#detail 改为仅返回 { check: _formatCheckRow(check) }(删除明细表查询、rows/total 与商品行 stock 挂载);同步删除已无引用的 _formatDetailScopeRow;app/service/systemMethods/stock/check.js#detail 仅同步 JSDoc(行为不变,仍统一 success/failure 包装)。", + "测试同步:test/app/service/systems/stock_check.test.js(helper detailCheck 改为「detail 取 check + 直查明细表补 rows」,新增 detail 只返回 { check } 与 400 边界用例,方法层 detail 用例改写,删除原「detail 纯范围行」5 条用例与已无引用的字段常量);真实库集成测试 213/213 通过、ESLint 0 错误。", + "兼容性影响:响应 data 由 { check, rows, total } 变更为 { check },为破坏性变更;调用方如需明细范围行/盘点结果改调 stock.check.result(返回 { check, rows, total }),作业记录改调 stock.check.recordList,盘点作业数据改调 stock.check.workData。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.detail 一条(description/response(data.children 仅保留 check)/notes 同步;headers/params/errors/isNeedAuth/isNeedLogin 不变);根版本 0.3.240 → 0.3.241、updatedAt 2026-10-02 → 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 往返校验),保持库与文件一致。" + ] + }, + { + "version": "2026.10.02-stock-check-recordList-goods-mount-align-workData", + "date": "2026-10-02", + "type": "updated", + "summary": "stock.check.recordList 商品信息挂载对齐 workData:已知商品(stock_id 有值)item_code/item_name/spec 批量取自 stockWarehouse.getStockDetails(带缓存,未命中回退明细表商品快照),新增 store_id(商品货主ID)/store_name(货主名,经 _resolveStoreNameMap 解析)、barcode 兜底商品条码(getStockDetails.barcodes[0],无则保留记录原始条码);未知商品(stock_id 为空)item_code=扫描条码兜底、item_name=名称快照兜底条码、spec/store_id/store_name=null、barcode=扫描条码;保留记录表全字段不变、images 仍为作业记录照片(FileReference business_type=stock_check_record)、location_code 空串统一返回 null 不变——向后兼容,仅新增列。代码已改并测试通过 215/215、ESLint 0 错误。", + "methods": [ + "stock.check.recordList" + ], + "notes": [ + "代码依据:app/service/systems/stock_check.js#recordList(rows 记录表全字段不变 + 商品信息挂载:已知商品 stockDetailMap 由 ctx.service.systems.stockWarehouse.getStockDetails(stockIds, { warehouseId }) 带缓存批量取,item_code/item_name/spec 优先 getStockDetails、未命中回退明细表 wms_stock_check_detail 商品快照;store_id=Number(stockDetail.store_id)(无则 null)、store_name 经 _resolveStoreNameMap(storeIds, warehouseId) 解析;barcode=stockDetail.barcodes[0].barcode(无则保留记录原始条码);未知商品 isUnknownGoods=true:item_code=扫描条码(barcode 空则 null)、item_name=名称快照兜底条码、spec/store_id/store_name=null、barcode=扫描条码;location_code 空串归一 null 不变;images 经 _attachRecordImages 挂载 FileReference business_type=stock_check_record 不变)。本次代码已改并测试通过 215/215、ESLint 0 错误。", + "影响面:向后兼容(仅新增 spec/store_id/store_name 三列与 barcode 商品条码兜底),记录表全字段与 item_code/item_name 原有兜底口径保留;未知商品新增 spec/store_id/store_name 为 null;location_code 空串返回 null 不变;images 仍为作业记录照片。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.recordList 一条(description/response.rows 补新增字段 spec/store_id/store_name 与 barcode 兜底口径(对齐 workData)、说明保留记录全字段;notes 补「商品信息挂载对齐 workData」说明);headers/params/errors/isNeedAuth/isNeedLogin 不变;根版本 0.3.239 → 0.3.240、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 无损。" + ] + }, + { + "version": "2026.10.02-stock-check-work-data-record-photos", + "date": "2026-10-02", + "type": "updated", + "summary": "stock.check.workData 三视图作业照片挂载与 record_ids 输出:location 视图 goods 子项 images 由「商品主图 stockDetail.image_url」改为「作业记录照片 record.images」(_attachRecordImages 挂载 FileReference business_type=stock_check_record,与 result/recordList 口径一致;未知商品子项 images 维持记录照片不变);goods 视图(is_goods=true)locations 聚合项新增 images(该库位该商品全部记录的作业照片扁平去重)与 record_ids(该库位该商品全部作业记录 ID,按记录 id 升序);space 视图 goods 子项 images 由商品主图改为该商品在该库位的作业照片聚合(扁平去重)并新增 record_ids(该商品在该库位全部作业记录 ID);行级/未盘项无记录时 images/record_ids 为空数组。record_ids 供前端编辑/移除记录(recordDelete 批量删除、recheckClearLocation 重盘清除库位),location 视图单条 record_id 直接定位不变。代码已改并测试通过 214/214、ESLint 0 错误。", + "methods": [ + "stock.check.workData" + ], + "notes": [ + "代码依据:app/service/systems/stock_check.js#_buildLocationWorkRows(已知商品子项 images 由商品主图改为 record.images 作业记录照片,未知商品子项维持记录照片)+ #_buildGoodsWorkRows(locations 聚合项新增 record_ids(按记录 id 升序)与 images(该库位该商品全部记录照片扁平去重),行级 images 仍为 stockDetail.image_url)+ #_buildSpaceWorkRows(goods 子项 images 由商品主图改为该商品在该库位的作业照片聚合(扁平去重),新增 record_ids)+ #_attachRecordImages(FileReference business_type=stock_check_record,与 result/recordList 口径一致)。本次代码已改并测试通过 214/214、ESLint 0 错误。", + "影响面:images 由商品主图变为作业照片(location 视图已知商品子项、space 视图 goods 子项);goods 视图行级 images 仍为商品主图;goods locations 项与 space goods 项新增 record_ids(供前端编辑/移除记录:stock.check.recordDelete 批量删除、stock.check.recheckClearLocation 重盘清除库位);location 视图单条 record_id 直接定位不变;行级/未盘项无记录时 images/record_ids 为空数组;其余字段与分页/状态限制口径不变。", + "文档变更范围: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 无损。" + ] + }, + { + "version": "2026.10.02-stock-check-goods-detail-split-by-location", + "date": "2026-10-02", + "type": "updated", + "summary": "盘点模块「商品任务必须按库位盘点」改造:商品明细按「商品+库位」拆行——addDetail/patternCreate 商品路径(_addGoodsDetailRows)按商品在仓库的启用库存库位(wms_storage is_enabled=1,按 space_id 分组 SUM)拆行,每个「商品+库位」生成一条 scope_type=goods 明细行(location_id/location_code 绑定库存库位、system_quantity=该库位库存 SUM),一个商品多个库位多行;无启用库存库位的商品计入 invalid_stock_ids 不入明细(商品任务必须按库位盘点);同商品重复添加整体跳过(幂等口径不变);added/total_items 为拆分明细行数。detail 商品行 location_id/location_code 非空(15 字段结构不变)。submit「存在缺少库位的盘点明细,无法提交审核」校验不再限定 scope_type=location:全部明细行(库位型与商品型)location_id 为空或 location_code 为空/空串均拦截。配套数据库迁移 20261002170000(已在开发/生产执行):uk_check_stock(check_id,stock_id) → uk_check_stock_location(check_id,stock_id,location_id);uk_check_location 唯一约束放宽为普通索引 idx_check_location(库位行幂等由应用层查重保证)。代码已改并测试通过 213/213、ESLint 0 错误。", + "methods": [ + "stock.check.addDetail", + "stock.check.detail", + "stock.check.submit", + "stock.check.patternCreate", + "stock.check.addLocationDetail" + ], + "notes": [ + "代码依据:app/service/systems/stock_check.js#_addGoodsDetailRows(Storage.findAll where warehouse_id+stock_id in+is_enabled=1、attributes SUM(quantity)、group=[stock_id, space_id];LocationSpace 按 id 取 space_code 快照;货主校验与同商品整体跳过沿用;无启用库存库位商品 → invalidStockIds;每个「商品+库位」生成 scope_type=goods 行 location_id/location_code/system_quantity=该库位 SUM)+ #addDetail(added=toCreate.length、total_items 重算)+ #submit(count where check_id+(location_id 为空或 location_code 为空/空串),不再限定 scope_type=location)+ #detail/_formatDetailScopeRow(15 字段结构不变,商品行 location 有值)+ #patternCreate(pattern.type==='goods' 调 _addGoodsDetailRows)。本次代码已改并测试通过 213/213、ESLint 0 错误。", + "迁移说明:database/migrations/20261002170000-split-goods-detail-by-location.js(已在开发库与生产库执行)——wms_stock_check_detail 唯一索引 uk_check_stock(check_id, stock_id) 变更为 uk_check_stock_location(check_id, stock_id, location_id)(商品拆行后同任务同商品可多行);uk_check_location(check_id, location_code) 唯一约束放宽为普通索引 idx_check_location(商品拆行后同任务同库位可有多个商品行,库位行幂等由应用层查重保证)。", + "影响面:商品明细行数=商品×启用库存库位数(不再一商品一行);system_quantity 语义由商品全仓账面变为该「商品+库位」库存 SUM;无启用库存库位的商品无法加入盘点(addDetail 记入 invalid_stock_ids、patternCreate 不产生明细行);detail 商品行 location_id/location_code 由 null 变为绑定库存库位;submit 缺库位校验覆盖全部明细行(商品行与库位行)。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.addDetail:description/params/response/notes 补商品拆行口径(拆多行、无库存库位 invalid、system_quantity=该库位账面、added=拆分行数);stock.check.detail:description/response.rows/notes 商品行 location_id/location_code 绑定库存库位;stock.check.submit:description/notes 缺库位校验改为覆盖全部明细行;stock.check.patternCreate:description/notes 补 goods 定式按库存库位拆行;stock.check.addLocationDetail:notes 幂等索引口径同步 uk_check_location 唯一约束放宽为普通索引 idx_check_location);根版本 0.3.237 → 0.3.238、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 17 条 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 无损。" + ] + }, + { + "version": "2026.10.02-stock-check-submit-missing-location-guard", + "date": "2026-10-02", + "type": "updated", + "summary": "stock.check.submit 新增提交校验:库位范围明细(scope_type=location)缺少库位(location_id 为空或 location_code 为空/空串)的明细行存在时抛 400「存在缺少库位的盘点明细,无法提交审核」——脏数据防御,正常流程 addDetail/addLocationDetail 不会产生此类明细;原有校验(状态非 created/rejected 不允许提交审核、total_items<=0 无明细行拒绝)不变。代码已改并测试通过 211/211、ESLint 0 错误。", + "methods": [ + "stock.check.submit" + ], + "notes": [ + "代码依据:app/service/systems/stock_check.js#submit——校验顺序:任务ID 为空→400「盘点任务ID不能为空」;任务不存在→400「盘点任务不存在」;状态非 created/rejected→400「当前状态(xx)不允许提交审核」;total_items<=0→400「盘点任务还没有明细行,无法提交审核」;新增库位缺库位校验:StockCheckDetail.count where check_id+scope_type=location+(location_id 为空或 location_code 为空/空串)>0→400「存在缺少库位的盘点明细,无法提交审核」(脏数据防御,正常流程 addDetail/addLocationDetail 不会产生此类明细)。本次代码已改并测试通过 211/211、ESLint 0 错误。", + "影响面:前端无需改动——该校验仅拦截脏数据(手工/历史遗留缺库位明细),正常盘点流程不受影响;原有校验顺序不变。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.submit 一条(errors 400 补「存在缺少库位的盘点明细,无法提交审核」、description/notes 补该校验口径);根版本 0.3.236 → 0.3.237、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 无损。" + ] + }, + { + "version": "2026.10.02-stock-check-record-delete-batch-recheck-clear-location", + "date": "2026-10-02", + "type": "updated", + "summary": "盘点模块两项改动:① stock.check.recordDelete 由旧版单值删除升级为批量删除(与 detailDelete 批量口径一致)——入参 record_ids 数组(单次上限 200,兼容 recordIds 驼峰数组、recordId 单数驼峰、record_id 单值旧写法,单值自动转数组);响应由 { record_id, deleted, total_items, checked_items, diff_items, detail_status } 变更为 { deleted_count, deleted_ids, skipped_ids, total_items, checked_items, diff_items, detail_status }(deleted_ids/skipped_ids 保持入参顺序,查不到的记录计入 skipped_ids 不报错,旧版「作业记录不存在或不属于该盘点任务」400 不再返回);② 新增 stock.check.recheckClearLocation 重盘清除库位——传任务ID+库位ID,清除该库位范围内明细(scope_type=location)的全部作业记录(含空库位标记)、该库位回到未盘,仅库位范围任务(type=location/all)且状态 approved/checking 可用,删除后清理图片引用、重算汇总(主表状态不回退)、写 STOCK_CHECK_CLEAR_LOCATION 日志;ALL_METHOD_NAMES 由 21 个增至 22 个(加入 recheckClearLocation,位于 recordDelete 之后)。代码已改并测试通过 210/210、ESLint 0 错误。", + "methods": [ + "stock.check.recordDelete", + "stock.check.recheckClearLocation" + ], + "notes": [ + "代码依据:app/service/systemMethods/stock/check.js#recordDelete(record_ids 兼容 recordIds/recordId/record_id,单值自动转数组)+ app/service/systems/stock_check.js#recordDelete(校验顺序:任务ID 为空→400「盘点任务ID不能为空」;任务不存在→400「盘点任务不存在」;状态非 approved/checking→400「当前状态(xx)不允许删除作业记录」;ids 为空→400「请至少选择一条作业记录」;超 200→400「单次最多删除 200 条作业记录」;查不到计入 skipped_ids;清理 FileReference 图片引用、_recalcCheckSummary 重算、写 STOCK_CHECK_DELETE_RECORD 日志)。", + "代码依据:app/service/systemMethods/stock/check.js#recheckClearLocation(location_id 兼容 locationId 驼峰,warehouse_id 由 ctx.user.store_id 注入)+ app/service/systems/stock_check.js#recheckClearLocation(校验顺序:任务ID 为空/库位ID 为空/任务不存在/状态非 approved/checking→「当前状态(xx)不允许清除库位盘点信息」/任务范围非库位 type≠location/all→「仅库位盘点任务支持重盘清除库位」/库位不在任务范围→「该库位不在盘点任务范围内」;删除该库位范围明细全部作业记录含空库位标记、清理图片引用、重算汇总、主表状态不回退、写 STOCK_CHECK_CLEAR_LOCATION 日志)。", + "影响面:recordDelete 前端需改传 record_ids 数组并按新响应字段(deleted_count/deleted_ids/skipped_ids)解析;recheckClearLocation 为库位盘点重盘场景新接口,非库位任务调用报 400。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.recordDelete(params/response/errors/description/notes 按新批量口径重写,description 注明「由旧版单值删除升级为批量删除」)并新增 stock.check.recheckClearLocation(位于 recordDelete 之后);分组内「21 个 method」「21 个方法共用统一包装」等字样全部更新为 22 个(workData 权限口径 ALL_METHOD_NAMES 清单加入 recheckClearLocation);根版本 0.3.235 → 0.3.236、updatedAt 2026-10-02;methods/changes/system.json 插入本条(数组首位);stock.check 分组由 21 条增至 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 + --env production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,库与文件一致;stock.check 分组共 22 条 method 无损。" + ] + }, + { + "version": "2026.10.02-stock-check-markEmpty", + "date": "2026-10-02", + "type": "added", + "summary": "盘点模块新增 stock.check.markEmpty 方法(标记库位为空,库位盘点模式专属):仅库位范围任务(type=location/all)与库位明细行(scope_type=location)支持;内部转调 report(is_empty=true) 口径——写/更新空标记记录(stock_id/barcode/item_name=null、quantity=0、is_empty=1)、清除该明细商品记录、主表 approved→checking、重算 checked_items/diff_items/detail_status;按校验顺序返回 400(任务ID/明细ID 为空、任务不存在、状态不允许、非库位任务、明细不存在、明细非库位行);ALL_METHOD_NAMES 由 20 个增至 21 个(加入 markEmpty)——免 API 权限、免仓库有效期鉴权、必须登录,写操作记录操作日志(STOCK_CHECK_REPORT)。", + "methods": [ + "stock.check.markEmpty" + ], + "notes": [ + "代码依据:app/service/systemMethods/stock/check.js#markEmpty(warehouse_id 由服务端从 ctx.user.store_id 自动注入)+ app/service/systems/stock_check.js#markEmpty(校验后转调 this.report({ is_empty: true }));ALL_METHOD_NAMES 更新为 create,list,addDetail,addLocationDetail,detailDelete,detail,result,workData,report,markEmpty,recordList,recordDelete,finish,submit,cancel,audit,batchDelete,export,exportTaskProgress,patternList,patternCreate(21 个)。", + "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.markEmpty 一条(位于 stock.check.report 之后);分组内各 method notes 的「20 个方法共用统一包装」与 workData 权限口径 note 的 ALL_METHOD_NAMES 列表同步更新为 21 个;根版本 0.3.234 → 0.3.235、updatedAt 2026-10-02;methods/changes/system.json 插入本条(数组首位);stock.check 分组由 20 条增至 21 条。", + "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;先经 script/method-doc-create.cjs 在维护源新建(--bump 升版本),再按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入本变更记录;同步回填开发库(WMS_DB_TARGET=local,127.0.0.1:3307/wms)与生产库(WMS_DB_TARGET=production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,库与文件一致。" + ] + }, + { + "version": "2026.10.02-stock-check-empty-location-mark", + "date": "2026-10-02", + "type": "updated", + "summary": "盘点模块新增「空库位标记」能力:stock.check.report 新增 is_empty 入参(仅库位盘点明细支持,确认该库位为空——不要求商品/条码、quantity 恒 0,写特殊作业记录 stock_id/barcode/item_name=null、quantity=0、is_empty=1,与商品记录互斥:标记空删除该明细商品记录、上报商品删除空标记记录,商品明细行传 is_empty 报 400「仅库位盘点明细支持空库位标记」);stock.check.workData location 视图行新增 is_empty 字段(空标记记录不计入 goods 子列表,空标记后 status=checked 视为已盘点);stock.check.result 库位行新增 is_empty 字段(空标记时 stocks=[]、unknown_items=[]、checked_quantity=0、status=checked,账面有库存时 diff_quantity 为负数(盘亏)、is_diff=1);主表汇总(_recalcCheckSummary)空标记记录计入已盘明细、空标记明细库位账面有库存即计盘亏差异(diff_items);stock.check.recordList/export 记录行输出 is_empty(export Sheet2 空库位记录商品编码列输出「(空库位)」、数量 0);数据库 wms_stock_check_record 新增 is_empty 字段(TINYINT(1) NOT NULL DEFAULT 0,迁移 20261002160000 已在开发/生产执行)。代码已改并测试通过 201/201、ESLint 0 错误。", + "methods": [ + "stock.check.report", + "stock.check.workData", + "stock.check.result", + "stock.check.recordList", + "stock.check.export" + ], + "notes": [ + "代码依据:report 空库位标记(is_empty 归一化 true/'true'/1,仅 scope_type=location 支持、商品明细行报 400『仅库位盘点明细支持空库位标记』;标记空时 quantity 恒 0、写 stock_id/barcode/item_name=null、quantity=0、is_empty=1 的特殊作业记录;覆盖式查重按 detail_id+is_empty=1+location_code;互斥:标记空删除该明细 is_empty=false 记录、上报商品删除该明细 is_empty=true 记录)app/service/systems/stock_check.js#report;workData location 视图行 is_empty(空标记记录不进 goods 子列表、行 status=checked)app/service/systems/stock_check.js#_buildLocationWorkRows;result 库位行 is_empty 与盘亏口径(stocks=[]、unknown_items=[]、checked_quantity=0、status=checked;按 wms_storage SUM(quantity) 账面>0 时 diff_quantity=-账面总量、is_diff=1)app/service/systems/stock_check.js#_formatDetailAggregationRow;主表汇总(空标记计入已盘明细、账面有库存计盘亏差异)app/service/systems/stock_check.js#_recalcCheckSummary;recordList 记录全字段带 is_empty;export Sheet2 空库位行商品编码列输出『(空库位)』、数量 0 app/service/systems/stock_check.js#_generateAndUploadStockCheckExcel。本次代码已改并测试通过 201/201、ESLint 0 错误。", + "数据库变更:database/migrations/20261002160000-add-is-empty-to-stock-check-record.js(wms_stock_check_record 新增 is_empty TINYINT(1) NOT NULL DEFAULT 0 COMMENT 是否空库位标记,位于 item_name 之后),开发库(127.0.0.1:3307/wms)与生产库(112.124.21.102:3306/wms)均已执行。", + "影响面:前端库位盘点(明细 scope_type=location)可传 is_empty=true 快速确认空库位(无需扫描商品/条码);workData/result 库位行新增 is_empty 字段用于展示空标记状态(空标记行按已盘点处理、账面有库存显示盘亏差异);recordList/export 自动带出 is_empty(export 空库位行商品编码列显示「(空库位)」);商品明细行传 is_empty 会被 400 拒绝。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.report:params 新增 is_empty 入参、errors 400 补「仅库位盘点明细支持空库位标记」、description/response/notes 补充空库位语义与互斥及汇总口径;stock.check.workData:description/response.rows 的 location 行新增 is_empty 字段说明;stock.check.result:description/response.rows 库位行新增 is_empty 与空标记盘亏口径;stock.check.recordList:response.rows 记录全字段说明新增 is_empty;stock.check.export:description/notes 补 Sheet2 空库位行输出口径);根版本 0.3.233 → 0.3.234、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 15 条 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 无损。" + ] + }, + { + "version": "2026.10.02-stock-check-work-data-location-unknown-merge", + "date": "2026-10-02", + "type": "updated", + "summary": "stock.check.workData location 视图行结构调整:删除 unknown 未知商品子列表——未知商品记录(stock_id 为空)不再单独输出,与已知商品统一并入 goods 子列表、输出字段对齐已知商品(record_id/stock_id=null/item_code 用条码兜底/item_name 用名称快照兜底条码/barcode/images/store_id=null/store_name=null/quantity/checked_at/checker_name);行级 has_unknown 标记保留(该库位是否含未知商品记录)。代码已改并测试通过 197/197、ESLint 0 错误。", + "methods": [ + "stock.check.workData" + ], + "notes": [ + "代码依据:app/service/systems/stock_check.js#_buildLocationWorkRows——records 按 detail_id 聚合后,已知商品(stock_id 正整数)与未知商品(stock_id 为空/非正整数)均 push 进 goods:已知商品取 stockDetailMap(stockWarehouse.getStockDetails 带缓存)补 item_code/item_name/barcode(barcodes[0].barcode)/images(image_url)/store_id/store_name(_resolveStoreNameMap 解析);未知商品 stock_id=null、item_code=条码兜底、item_name=名称快照兜底条码、barcode=记录条码、images=_attachRecordImages 挂载(FileReference business_type=stock_check_record)、store_id/store_name=null;quantity/checked_at/checker_name 与已知商品一致;行级 has_unknown=true 标记保留。本次代码已改并测试通过 197/197、ESLint 0 错误。", + "影响面:前端无需再处理 unknown 数组——直接遍历 goods 子列表,按 stock_id 是否为 null 区分未知商品(未知商品 item_code 即扫描条码、item_name 即上报名称快照);has_unknown 仍可用于快速判断该库位是否含未知商品;其余视图(goods/space)与分页等结构不变。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(description/response.rows/notes 同步 location 视图行结构——删除 unknown 子列表字段说明、goods 改为「已知商品与未知商品记录均入内,未知商品 stock_id=null、item_code 用条码兜底、store_id/store_name 为 null」、has_unknown 保留说明;headers/params/errors/isNeedAuth/isNeedLogin 与 goods/space 视图及分页描述不变);根版本 0.3.232 → 0.3.233、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 无损。" + ] + }, + { + "version": "2026.10.02-stock-check-data-envelope", + "date": "2026-10-02", + "type": "updated", + "summary": "stock.check 分组全部 20 个方法响应统一增加 data 层封装:成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp };业务数据结构本身不变(如 create 返回盘点任务字段、list 返回 { rows,total,page,pageSize }、workData 返回 { check,rows,total,page,pageSize }),只是整体包进 data。代码已改并测试通过 197/197、ESLint 0 错误。", + "methods": [ + "stock.check.create", + "stock.check.list", + "stock.check.addDetail", + "stock.check.detailDelete", + "stock.check.detail", + "stock.check.result", + "stock.check.workData", + "stock.check.report", + "stock.check.recordList", + "stock.check.recordDelete", + "stock.check.finish", + "stock.check.submit", + "stock.check.cancel", + "stock.check.audit", + "stock.check.batchDelete", + "stock.check.export", + "stock.check.exportTaskProgress", + "stock.check.patternList", + "stock.check.patternCreate", + "stock.check.addLocationDetail" + ], + "notes": [ + "代码依据:app/service/systemMethods/stock/check.js#_call(20 个方法共用的统一调用包装)——成功返回 { flag:\"success\", code:1, message:\"ok\", data:result };业务错误(code 为 400-599 整数)返回 { flag:\"failure\", code, message, data:null };其余异常记录日志并返回 { flag:\"failure\", code:500, message:\"服务器内部错误\", data:null };app/lib/api_response.js#toSuccess 识别标准载荷后顶层补充 timestamp。", + "旧口径(改造前):成功 { flag:\"success\", code:1, message:\"ok\", ...业务字段平铺 }(MainService.success 展开 data 的平铺结构);失败响应 { flag:\"failure\", code, message }(无 data);本次统一为 data 层封装,与项目 toSuccess/toFailure 常规口径一致。", + "失败语义变化:业务错误(400/500 等)不再由控制器 catch 后转 HTTP 4xx/5xx + toFailure,而是由 _call 捕获后在 body 内以 flag=failure + data=null 返回(HTTP 200);未登录/鉴权失败(checkAuth 401)仍走控制器 toFailure(HTTP 401)。前端失败判定建议以 flag 为准。", + "影响面:前端解析响应需从 data 取业务数据(原顶层业务字段全部移入 data);业务数据结构本身不变。", + "文档变更范围:methods/system.json 的 module=stock.check 分组全部 20 条 method 的 response 统一调整——顶层固定为 flag/code/message/data/timestamp,原业务字段整体移入 data.children(字段与说明不变),每条 notes 追加统一 data 层封装口径;headers/params/errors/isNeedAuth/isNeedLogin/description 不变;根版本 0.3.231 → 0.3.232、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位)。", + "库表维护源说明:维护源为库表(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 + --env production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。" + ] + }, + { + "version": "2026.10.02-stock-check-work-data-view-driven", + "date": "2026-10-02", + "type": "updated", + "summary": "stock.check.workData 视图驱动规则改造:view 入参废弃(不再校验、不再使用,传任何值都被忽略、不报错);新增 is_goods 入参(boolean,body,可选,兼容 isGoods 驼峰写法)——任务范围为库位(type=location/all)一律按库位视图(location)返回、无视 view/is_goods;任务范围为商品(type=goods/store)默认聚合库位视图(space),仅 is_goods=true 时按商品视图(goods)返回,is_goods 其他值(false/0/缺省等)一律按默认 space;分页能力不变(pagination.{page,pageSize},与 stock.check.list 口径一致,默认 20 上限 200);errors 移除「视图类型非法(仅支持 location/goods/space)」条目,保留任务ID不能为空/状态限制/任务不存在/500。代码已改并测试通过 197/197、ESLint 0 错误。", + "methods": [ + "stock.check.workData" + ], + "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 兼容驼峰写法;不再读取/校验 view)+ app/service/systems/stock_check.js#workData(视图解析:normalizedType=String(check.type||'').trim(),type=location/all 一律 location 无视 view/is_goods;否则 isGoods===true||'true'||1 → goods、其余默认 space;错误口径不变:ID 不能为空/任务不存在/状态限制/500)。本次代码已改并测试通过 197/197、ESLint 0 错误。", + "影响面:前端如需商品视图须改传 is_goods=true(或 isGoods=true);view 传值不再生效、不会被校验;库位任务前端无需传 is_goods。响应结构 { check, rows, total, page, pageSize } 与分页口径不变。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params 删除 view、新增 is_goods;description 视图规则改为「库位任务一律 location、商品任务默认 space、is_goods=true 才 goods;view 入参已废弃忽略」;errors 删除视图非法条目;response 结构不变;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)与生产库(显式 WMS_DB_TARGET=production)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。" + ] + }, + { + "version": "2026.10.02-stock-check-work-data-pagination-conventional", + "date": "2026-10-02", + "type": "updated", + "summary": "stock.check.workData 分页口径修正:改为与 stock.check.list 一致的常规口径——仅入参 pagination.{page,pageSize}(不再兼容 page_size 蛇形写法、不再支持顶层 page/pageSize/page_size),默认 page=1、pageSize=20、上限 200,响应 page/pageSize 结构不变", + "methods": [ + "stock.check.workData" + ], + "notes": [ + "代码依据:app/service/systemMethods/stock/check.js#workData(const { id, view, pagination } = data || {},pagination 直接透传,不再解析顶层 page/pageSize/page_size、不做 page_size 兼容)+ app/service/systems/stock_check.js#workData(pagination 默认 {};page=Math.max(1, Number(pagination.page)||1) 默认 1、pageSize=Math.min(200, Math.max(1, Number(pagination.pageSize)||20)) 默认 20 上限 200、非法回退默认;先构建全量行再 slice(offset, offset+pageSize);返回 { check, rows, total, page, pageSize })。分页口径与 stock.check.list 完全一致。本次代码已改并测试通过 197/197、ESLint 0 错误。", + "口径修正说明:上一轮变更记录(2026.10.02-stock-check-work-data-pagination)曾描述「入参支持 pagination 对象与顶层 page/pageSize/page_size(顶层优先)、兼容 page_size 蛇形写法」,代码按用户要求改为常规分页方式后上述描述不再成立;本条为口径修正记录,替换上一轮记录中的入参兼容口径(历史记录保留不回改),以本条为准。", + "影响面:仅文档口径修正(methods/system.json 的 workData params.pagination 描述、description、response.page/pageSize 描述、notes),代码接口行为与响应结构(check/rows/total/page/pageSize)不变;涉及文件:methods/system.json、methods/changes/system.json、库表 wms_api_method_doc/wms_method_doc_meta。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params.pagination 描述、description、response.page/pageSize 描述、notes 同步常规分页口径并注明与 stock.check.list 一致;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 无损。" + ] + }, + { + "version": "2026.10.02-stock-check-work-data-pagination", + "date": "2026-10-02", + "type": "updated", + "summary": "stock.check.workData 新增分页能力:入参支持 pagination 对象与顶层 page/pageSize/page_size(顶层优先),响应新增 page/pageSize,rows 为当前页行、total 为全部行数(默认 page=1、pageSize=20 上限 200,向后兼容)", + "methods": [ + "stock.check.workData" + ], + "notes": [ + "代码依据:app/service/systemMethods/stock/check.js#workData(入参归一化:data.pagination.{page,pageSize} 兼容 page_size 蛇形写法;顶层 data.page / data.pageSize / data.page_size 顶层值优先,口径与 stock/report.js 一致)+ app/service/systems/stock_check.js#workData(三视图先构建全量行再按页切片 slice(offset, offset+pageSize);page=Math.max(1, Number(page)||1) 默认 1、pageSize=Math.min(200, Math.max(1, Number(pageSize)||20)) 默认 20 上限 200、非法回退默认;返回 { check, rows, total, page, pageSize },total=allRows.length 未分页口径)。本次代码已改并测试通过 197/197、ESLint 0 错误。", + "影响面:仅新增可选入参(pagination/page/pageSize/page_size)与两个响应字段(page/pageSize);旧调用方不传分页时 page=1、pageSize=20、rows 行为不变、total 不变,向后兼容;涉及文件:app/service/systemMethods/stock/check.js、app/service/systems/stock_check.js、methods/system.json、methods/changes/system.json、库表 wms_api_method_doc/wms_method_doc_meta。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params 新增 pagination、response 新增 page/pageSize 并同步 rows/total 口径、description/notes 补充分页口径;headers/errors/isNeedAuth/isNeedLogin 不变);根版本 0.3.228 → 0.3.229、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 + --env production)——import 当前 system.json → export 回写往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。" + ] + }, + { + "version": "2026.10.02-stock-check-work-data-space-fields", + "date": "2026-10-02", + "type": "updated", + "summary": "workData space 视图两处调整:库位聚合来源扩展为当前库存库位∪作业记录库位(盘点前库存已出空但已有作业记录的库位也能展示);行字段对齐库位查询惯例 index.searchSpace(id/space_code/custom_barcode/custom_name,custom_name 空输出 null 不兜底编码)", + "methods": [ + "stock.check.workData" + ], + "notes": [ + "代码依据:app/service/systems/stock_check.js#_buildSpaceWorkRows——库位集合由原「仅 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 补查(attributes 含 id/space_code/custom_barcode/custom_name/pick_sequence/pick_priority);仅记录库位(当前库存无该商品)按库位归集补行(totalQuantity 按 0),明盘该系统 quantity 按 0、checked_quantity 按该库位实盘合计;本次仅同步文档,未改动任何代码(代码已改并测试通过 196/196、ESLint 0 错误)。", + "行字段口径:space 视图行输出 id(wms_location_space.id)/space_code/custom_barcode(空为 null)/custom_name(空为 null,不再兜底 space_code),与库位查询惯例 index.searchSpace 一致;goods 子列表字段不变(detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images/status,明盘另含 system_quantity/checked_quantity);location/goods 视图行字段不变。", + "影响面:仅 space 视图行字段与库位集合口径变化(涉及文件:app/service/systems/stock_check.js、methods/system.json、methods/changes/system.json、库表 wms_api_method_doc/wms_method_doc_meta);check/total 结构、location/goods 视图行、明盘/盲盘数量控制、排序口径(pick_sequence 升序/pick_priority 降序/库位 id 升序兜底)、状态限制均不变。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(description/response.rows/notes 同步新口径);根版本 0.3.227 → 0.3.228、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 + --env production)——import 当前 system.json → export 回写往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。" + ] + }, { "version": "2026.10.02-system-platform-header-miniprogram", "date": "2026-10-02", diff --git a/methods/system.json b/methods/system.json index 101d98b..03800da 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.227", - "updatedAt": "2026-10-02", + "version": "0.3.243", + "updatedAt": "2026-10-04", "headers": [ { "name": "platform", @@ -37836,112 +37836,144 @@ ], "response": [ { - "name": "id", + "name": "flag", + "type": "string", + "required": true, + "description": "请求结果标记:success=成功 / failure=失败" + }, + { + "name": "code", "type": "number", "required": true, - "description": "盘点任务ID" + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { - "name": "check_no", + "name": "message", "type": "string", "required": true, - "description": "盘点单号(PD+YYYYMMDD+6位序号)" + "description": "提示信息:成功为 ok;失败为具体错误文案" }, { - "name": "title", - "type": "string", + "name": "data", + "type": "object", "required": true, - "description": "盘点名称/主题" + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "盘点任务ID" + }, + { + "name": "check_no", + "type": "string", + "required": true, + "description": "盘点单号(PD+YYYYMMDD+6位序号)" + }, + { + "name": "title", + "type": "string", + "required": true, + "description": "盘点名称/主题" + }, + { + "name": "type", + "type": "string", + "required": true, + "description": "盘点范围类型:all/store/goods/location" + }, + { + "name": "mode", + "type": "string", + "required": true, + "description": "盘点方式:open/blind" + }, + { + "name": "store_id", + "type": "number", + "required": false, + "description": "货主ID(按货主盘点时有值)" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "主表状态(新建为 created)" + }, + { + "name": "detail_status", + "type": "string", + "required": true, + "description": "明细盘点进度:none_checked/partial_checked/all_checked(新建为 none_checked)" + }, + { + "name": "start_time", + "type": "string", + "required": false, + "description": "盘点开始时间(第一个盘点明细写入的时间,创建时为空)" + }, + { + "name": "end_time", + "type": "string", + "required": false, + "description": "盘点结束时间(完成盘点的时间,创建时为空)" + }, + { + "name": "creator_id", + "type": "number", + "required": true, + "description": "创建人账户ID" + }, + { + "name": "creator_name", + "type": "string", + "required": true, + "description": "创建人名称快照" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "明细行数" + }, + { + "name": "checked_items", + "type": "number", + "required": true, + "description": "已盘行数" + }, + { + "name": "diff_items", + "type": "number", + "required": true, + "description": "差异行数" + }, + { + "name": "remark", + "type": "string", + "required": true, + "description": "备注" + }, + { + "name": "created_at", + "type": "string", + "required": false, + "description": "创建时间" + }, + { + "name": "updated_at", + "type": "string", + "required": false, + "description": "更新时间" + } + ] }, { - "name": "type", - "type": "string", - "required": true, - "description": "盘点范围类型:all/store/goods/location" - }, - { - "name": "mode", - "type": "string", - "required": true, - "description": "盘点方式:open/blind" - }, - { - "name": "store_id", - "type": "number", - "required": false, - "description": "货主ID(按货主盘点时有值)" - }, - { - "name": "status", - "type": "string", - "required": true, - "description": "主表状态(新建为 created)" - }, - { - "name": "detail_status", - "type": "string", - "required": true, - "description": "明细盘点进度:none_checked/partial_checked/all_checked(新建为 none_checked)" - }, - { - "name": "start_time", - "type": "string", - "required": false, - "description": "盘点开始时间(第一个盘点明细写入的时间,创建时为空)" - }, - { - "name": "end_time", - "type": "string", - "required": false, - "description": "盘点结束时间(完成盘点的时间,创建时为空)" - }, - { - "name": "creator_id", + "name": "timestamp", "type": "number", "required": true, - "description": "创建人账户ID" - }, - { - "name": "creator_name", - "type": "string", - "required": true, - "description": "创建人名称快照" - }, - { - "name": "total_items", - "type": "number", - "required": true, - "description": "明细行数" - }, - { - "name": "checked_items", - "type": "number", - "required": true, - "description": "已盘行数" - }, - { - "name": "diff_items", - "type": "number", - "required": true, - "description": "差异行数" - }, - { - "name": "remark", - "type": "string", - "required": true, - "description": "备注" - }, - { - "name": "created_at", - "type": "string", - "required": false, - "description": "创建时间" - }, - { - "name": "updated_at", - "type": "string", - "required": false, - "description": "更新时间" + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -37963,7 +37995,8 @@ "文档变更范围: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'。", - "盘点时间口径(主表无 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)。" + "盘点时间口径(主表无 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)。" ] }, { @@ -38046,28 +38079,60 @@ ], "response": [ { - "name": "rows", - "type": "array", + "name": "flag", + "type": "string", "required": true, - "description": "盘点任务行列表(主表全字段,含 check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at,每行新增 store_name 货主名称;start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间));store_name=货主名称:优先 wms_store_warehouse.store_remask(合约货主备注,按 store_id+warehouse_id 匹配);无合约或备注为空时回退 wms_store.company_name(公司全称);两者均查不到返回空字符串" + "description": "请求结果标记:success=成功 / failure=失败" }, { - "name": "total", + "name": "code", "type": "number", "required": true, - "description": "总条数" + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { - "name": "page", - "type": "number", + "name": "message", + "type": "string", "required": true, - "description": "当前页码" + "description": "提示信息:成功为 ok;失败为具体错误文案" }, { - "name": "pageSize", + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "rows", + "type": "array", + "required": true, + "description": "盘点任务行列表(主表全字段,含 check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at,每行新增 store_name 货主名称;start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间));store_name=货主名称:优先 wms_store_warehouse.store_remask(合约货主备注,按 store_id+warehouse_id 匹配);无合约或备注为空时回退 wms_store.company_name(公司全称);两者均查不到返回空字符串" + }, + { + "name": "total", + "type": "number", + "required": true, + "description": "总条数" + }, + { + "name": "page", + "type": "number", + "required": true, + "description": "当前页码" + }, + { + "name": "pageSize", + "type": "number", + "required": true, + "description": "每页条数" + } + ] + }, + { + "name": "timestamp", "type": "number", "required": true, - "description": "每页条数" + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -38083,12 +38148,13 @@ "筛选口径:status/type/mode 支持单值 eq 或数组 in(归一化 trim 后自动去重,空值忽略);store_id 经 Number 归一化后 eq;keyword 对盘点单号 check_no 与标题 title 做 OR 模糊匹配;所有筛选均叠加在 warehouse_id(ctx.user.store_id 仓库隔离)之上。", "时间范围语义:created_at/start_time/end_time 三列口径一致——单值=该字段 >= 该值(从该值起);数组 [from,to] 两端都合法=between 闭区间,仅 from 合法=gte、仅 to 合法=lte;空值/无法解析的日期静默忽略(不加入 where 条件)。", "库表维护源说明:维护源为库表(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 回写往返校验),保持库与文件一致;stock.check 分组共 18 条 method 无损。", - "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.list 一条(response.rows 描述新增 store_name 货主名称与解析口径,description/notes 同步;params/errors/headers/鉴权不变);根版本 0.3.219 → 0.3.220、updatedAt 保持 2026-10-01;methods/changes/system.json 新增本条(插入数组首位);其余 17 条 method 未改动。" + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.list 一条(response.rows 描述新增 store_name 货主名称与解析口径,description/notes 同步;params/errors/headers/鉴权不变);根版本 0.3.219 → 0.3.220、updatedAt 保持 2026-10-01;methods/changes/system.json 新增本条(插入数组首位);其余 17 条 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)。" ] }, { "method": "stock.check.addDetail", - "description": "添加盘点明细(商品或库位,按任务盘点类型决定):type=store/goods 按 stock_ids 添加商品行(scope_type=goods,从 wms_stock_warehouse 生成商品快照:编码/名称/规格/账面数量),商品必须属于本仓库,且任务 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;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,按 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;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。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -38112,7 +38178,7 @@ "type": "array", "required": false, "source": "body", - "description": "商品库存ID列表(wms_stock_warehouse.id);type=store/goods 按商品盘点时使用,与 locations/location_ids 按任务类型二选一" + "description": "商品库存ID列表(wms_stock_warehouse.id);type=store/goods 按商品盘点时使用,与 locations/location_ids 按任务类型二选一;每个商品按其启用库存库位(wms_storage is_enabled=1,按 space_id 分组)拆分为多行,无启用库存库位的商品记入 invalid_stock_ids" }, { "name": "locations", @@ -38138,40 +38204,72 @@ ], "response": [ { - "name": "added", + "name": "flag", + "type": "string", + "required": true, + "description": "请求结果标记:success=成功 / failure=失败" + }, + { + "name": "code", "type": "number", "required": true, - "description": "本次新增明细数" + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { - "name": "skipped", + "name": "message", + "type": "string", + "required": true, + "description": "提示信息:成功为 ok;失败为具体错误文案" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "added", + "type": "number", + "required": true, + "description": "本次新增明细数(商品路径为按「商品+库位」拆行后的明细行数)" + }, + { + "name": "skipped", + "type": "number", + "required": true, + "description": "已存在被跳过(幂等)的盘点项数" + }, + { + "name": "invalid_stock_ids", + "type": "array", + "required": true, + "description": "无效商品库存ID列表(不存在、不属于当前仓库、商品货主与任务货主不一致或在仓库无启用库存库位)" + }, + { + "name": "invalid_locations", + "type": "array", + "required": true, + "description": "无效库位编码列表(当前仓库不存在对应库位编码)" + }, + { + "name": "invalid_location_ids", + "type": "array", + "required": true, + "description": "无效库位ID列表(按 wms_location_space.id 直查当前仓库不存在)" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "重算后的明细总行数" + } + ] + }, + { + "name": "timestamp", "type": "number", "required": true, - "description": "已存在被跳过(幂等)的盘点项数" - }, - { - "name": "invalid_stock_ids", - "type": "array", - "required": true, - "description": "无效商品库存ID列表(不存在、不属于当前仓库或商品货主与任务货主不一致)" - }, - { - "name": "invalid_locations", - "type": "array", - "required": true, - "description": "无效库位编码列表(当前仓库不存在对应库位编码)" - }, - { - "name": "invalid_location_ids", - "type": "array", - "required": true, - "description": "无效库位ID列表(按 wms_location_space.id 直查当前仓库不存在)" - }, - { - "name": "total_items", - "type": "number", - "required": true, - "description": "重算后的明细总行数" + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -38190,7 +38288,9 @@ "历史任务兼容:改造前创建的 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 类型判定不变。", "商品货主限制:任务 store_id 非空时商品 store_id 必须与之一致,不一致计入 invalid_stock_ids(限制非本货主商品加入盘点)。", "全盘自动范围:type=all 且未传库位且未传 location_ids 时,自动拉取当前仓库全部启用库位(is_enabled=true)的 space_code 生成库位行;无启用库位时报 400。", - "幂等:商品行按 check_id+stock_id 跳过、库位行按 check_id+location_code 跳过(对应唯一索引 uk_check_stock / uk_check_location);location_ids 路径跳过项按库位ID记入 skipped。" + "幂等:商品行按 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,按 space_id 分组 SUM(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)。" ] }, { @@ -38238,28 +38338,60 @@ ], "response": [ { - "name": "deleted_count", + "name": "flag", + "type": "string", + "required": true, + "description": "请求结果标记:success=成功 / failure=失败" + }, + { + "name": "code", "type": "number", "required": true, - "description": "实际删除的明细数量" + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { - "name": "deleted_ids", - "type": "array", + "name": "message", + "type": "string", "required": true, - "description": "实际删除的明细ID列表(保持入参顺序)" + "description": "提示信息:成功为 ok;失败为具体错误文案" }, { - "name": "skipped_ids", - "type": "array", + "name": "data", + "type": "object", "required": true, - "description": "未命中被跳过的明细ID列表(明细不存在或不属于当前仓库,不报错;保持入参顺序)" + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "deleted_count", + "type": "number", + "required": true, + "description": "实际删除的明细数量" + }, + { + "name": "deleted_ids", + "type": "array", + "required": true, + "description": "实际删除的明细ID列表(保持入参顺序)" + }, + { + "name": "skipped_ids", + "type": "array", + "required": true, + "description": "未命中被跳过的明细ID列表(明细不存在或不属于当前仓库,不报错;保持入参顺序)" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "删除后重算的主表明细总行数" + } + ] }, { - "name": "total_items", + "name": "timestamp", "type": "number", "required": true, - "description": "删除后重算的主表明细总行数" + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -38276,12 +38408,13 @@ "写操作,记录操作日志(不在免日志清单 list/detail/result/recordList/export/exportTaskProgress/patternList 中)。", "入参兼容:detail_ids 优先于 detailIds、detail_id;detailIds/detail_id 为旧版兼容写法,单值自动转数组。", "批量口径:未命中(明细不存在或不属于当前仓库)的明细ID计入 skipped_ids 不报错;命中明细批量删除后对 wms_stock_check_record 按 { detail_id, check_id, warehouse_id } 防御性清理作业记录,并重算主表 total_items;deleted_ids/skipped_ids 均保持入参顺序。", - "响应结构变更(兼容性影响):由旧版 { detail_id, deleted, total_items } 变更为 { deleted_count, deleted_ids, skipped_ids, total_items },前端需按新结构取值。" + "响应结构变更(兼容性影响):由旧版 { detail_id, deleted, total_items } 变更为 { deleted_count, deleted_ids, skipped_ids, total_items },前端需按新结构取值。", + "响应统一 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)。" ] }, { "method": "stock.check.detail", - "description": "拉取盘点任务明细(任务范围行,不含盘点作业聚合):返回主表信息(check)与全部明细(rows);rows 每条为纯范围行 15 字段(id/check_id/warehouse_id/scope_type/stock_id/location_id/location_code/item_code/item_name/spec/batch_no/system_quantity/remark/created_at/updated_at),不返回任何盘点作业聚合字段(盘点结果聚合请调用 stock.check.result);scope_type=goods 为商品行(stock_id 有值、location 相关字段为 null,另挂载 stock 全局商品信息对象,见 response.rows),scope_type=location 为库位行(location_id/location_code 有值、stock_id 与商品快照字段为 null,不挂载 stock)。", + "description": "拉取盘点任务详情(只返回任务本身信息):入参 id(盘点任务ID);返回 { check },check 为盘点主表信息(id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at;start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间));不再返回明细范围行(rows)与明细总条数(total)——盘点明细范围行/盘点结果聚合请调用 stock.check.result,作业记录请调用 stock.check.recordList,盘点作业数据请调用 stock.check.workData;400 边界(任务ID为空/任务不存在)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -38303,22 +38436,42 @@ ], "response": [ { - "name": "check", - "type": "object", + "name": "flag", + "type": "string", "required": true, - "description": "盘点主表信息(id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at;start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间))" + "description": "请求结果标记:success=成功 / failure=失败" }, { - "name": "rows", - "type": "array", - "required": true, - "description": "明细行列表(纯范围行,不含盘点作业聚合):每条为 15 个范围行字段——id 明细ID / check_id 盘点任务ID / warehouse_id 仓库ID / scope_type 范围类型(goods=商品行 | location=库位行)/ stock_id 商品库存ID(wms_stock_warehouse.id,仅商品行有值,库位行为 null)/ location_id 库位ID(wms_location_space.id,仅库位行有值,商品行为 null)/ location_code 库位编码(仅库位行有值,商品行为 null)/ item_code 商品编码(商品快照,库位行为 null)/ item_name 商品名称(商品快照,库位行为 null)/ spec 规格(商品快照,库位行为 null)/ batch_no 批次号(商品快照,库位行为 null)/ system_quantity 账面数量快照(商品行为快照值,库位行为 0)/ remark 备注 / created_at 创建时间 / updated_at 更新时间;不返回 checked_quantity/diff_quantity/is_diff/status/location_codes/checkers/last_checked_at/records/locations/stocks 等作业聚合字段(见 stock.check.result);scope_type=goods 商品行另挂载 stock 对象(来源 stockWarehouse.getStockDetails,带缓存):完整全局商品信息——id 商品库存ID / item_code 商品编码 / item_name 商品名称 / sku_property SKU属性 / quantity 库存数量 / locked_quantity 锁定数量 / is_batch_mgmt 批次管理 Y|N / is_shelf_life_mgmt 效期管理 Y|N / image_url 商品图片 / is_images 是否有图 Y|N / need_recheck 是否需要复核 Y|N / store_id 货主ID / packing_requirements 打包要求 / pick_requirements 拣货要求 / recheck_requirements 复核要求 / merge_requirements 要求合并开关 Y|N / stock_unit 库存单位 / barcodes 条码数组([{ id, barcode, sku_property }]);未命中(库存不存在或不属于本仓库)stock=null;库位行(scope_type=location)不挂载 stock" - }, - { - "name": "total", + "name": "code", "type": "number", "required": true, - "description": "明细总条数" + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息:成功为 ok;失败为具体错误文案" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "check", + "type": "object", + "required": true, + "description": "盘点主表信息(id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at;start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间))" + } + ] + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -38332,14 +38485,16 @@ } ], "notes": [ - "商品行 stock 挂载口径:detail 返回时对 scope_type=goods 行按 stock_id 去重后批量调用 stockWarehouse.getStockDetails(stockIds, { warehouseId }),结果按 stock_id 挂载到各行 stock 字段;stock 为 wms_stock_warehouse 全局商品信息(id/item_code/item_name/sku_property/quantity/locked_quantity/is_batch_mgmt/is_shelf_life_mgmt/image_url/is_images/need_recheck/store_id/packing_requirements/pick_requirements/recheck_requirements/merge_requirements/stock_unit/barcodes),带 Redis 缓存(key=cache:stock_detail:{warehouseId}:{stockId},默认 TTL 300 秒);未命中(库存不存在或不属于本仓库)stock=null;库位行不挂载 stock;范围行原有 15 字段与其余返回结构不变。", - "拆分口径:detail 只返回任务范围行(纯 15 字段),原商品行已盘聚合(checked_quantity/diff_quantity/is_diff/status/location_codes/checkers/last_checked_at)、records(作业记录列表)、locations(按库位聚合)与库位行 stocks(按商品聚合)全部迁移到新接口 stock.check.result,调用方按需分别拉取。", - "查询类方法,不记录操作日志(免日志清单:list/detail/result/recordList/export/exportTaskProgress)。" + "只返回任务本身信息口径(本次改造):detail 不再查询/返回 wms_stock_check_detail 明细范围行与作业记录,响应仅含 { check }(不含 rows/total);同时移除商品行 stock 全局商品信息挂载(原 stockWarehouse.getStockDetails 挂载逻辑随 rows 一并移除)。明细范围行/盘点结果聚合见 stock.check.result,作业记录见 stock.check.recordList,盘点作业数据见 stock.check.workData。代码依据:app/service/systems/stock_check.js#detail(_formatDetailScopeRow 已删除)。", + "调用方迁移:原依赖 detail.rows 的调用方需改调 stock.check.result(返回 { check, rows, total } 聚合行,含商品行已盘聚合、records、locations 与库位行 stocks)/ stock.check.recordList(作业记录)/ stock.check.workData(三视图作业数据)。", + "查询类方法,不记录操作日志(免日志清单:list/detail/result/recordList/export/exportTaskProgress)。", + "兼容性影响(破坏性变更):响应 data 由 { check, rows, total } 变更为 { check },rows/total 字段被移除,前端取值需同步调整。", + "响应统一 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)。" ] }, { "method": "stock.check.result", - "description": "拉取盘点明细结果(按范围行聚合作业记录):入参 id(盘点任务ID);返回 { check, rows, total };商品行(scope_type=goods)含商品快照 + 已盘聚合(checked_quantity=作业记录数量合计、diff_quantity=实盘-账面、is_diff、status=checked|unchecked、location_codes、checkers、last_checked_at)+ records(该明细在 wms_stock_check_record 的全部作业记录,每条含 barcode/item_name 与 images 图片列表)+ locations(按库位聚合 [{ location_id, location_code, quantity }],空库位归 location_code=null 组,按首条记录 id 升序)+ unknown_items(未知商品按条码聚合 [{ barcode, item_name, checked_quantity }],无账面、差异=实盘-0=盘盈);库位行(scope_type=location)含 checked_quantity(行级合计=行内商品实盘合计)、diff_quantity(行内各商品差异代数和)、is_diff、status + records/locations + stocks(按商品聚合 [{ stock_id, item_code, item_name, system_quantity, checked_quantity, diff_quantity }],按 stock_id 升序,账面 system_quantity 查 wms_storage(space_id+stock_id SUM(quantity)),location_id 为空时账面按 0)+ unknown_items(口径同商品行);每条作业记录挂载 images(FileReference business_type=stock_check_record,仿收货 receivingItem 口径);无作业记录时聚合字段为 null、records/locations/stocks 为空数组。", + "description": "拉取盘点明细结果(按范围行聚合作业记录):入参 id(盘点任务ID);返回 { check, rows, total };商品行(scope_type=goods)含商品快照 + 已盘聚合(checked_quantity=作业记录数量合计、diff_quantity=实盘-账面、is_diff、status=checked|unchecked、location_codes、checkers、last_checked_at)+ records(该明细在 wms_stock_check_record 的全部作业记录,每条含 barcode/item_name 与 images 图片列表)+ locations(按库位聚合 [{ location_id, location_code, quantity }],空库位归 location_code=null 组,按首条记录 id 升序)+ unknown_items(未知商品按条码聚合 [{ barcode, item_name, checked_quantity }],无账面、差异=实盘-0=盘盈);库位行(scope_type=location)含 is_empty(是否空库位标记)+ checked_quantity(行级合计=行内商品实盘合计)、diff_quantity(行内各商品差异代数和)、is_diff、status + records/locations + stocks(按商品聚合 [{ stock_id, item_code, item_name, system_quantity, checked_quantity, diff_quantity }],按 stock_id 升序,账面 system_quantity 查 wms_storage(space_id+stock_id SUM(quantity)),location_id 为空时账面按 0)+ unknown_items(口径同商品行);每条作业记录挂载 images(FileReference business_type=stock_check_record,仿收货 receivingItem 口径);空库位标记(is_empty=true)时:stocks=[]、unknown_items=[]、checked_quantity=0、status=checked(视为已盘点),账面有库存时 diff_quantity 为负数(盘亏,差异=0-库位账面库存总量)、is_diff=1;无作业记录时聚合字段为 null、records/locations/stocks 为空数组。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -38361,22 +38516,54 @@ ], "response": [ { - "name": "check", - "type": "object", + "name": "flag", + "type": "string", "required": true, - "description": "盘点主表信息(id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at;start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间))" + "description": "请求结果标记:success=成功 / failure=失败" }, { - "name": "rows", - "type": "array", - "required": true, - "description": "明细结果行列表:商品行(scope_type=goods)含范围行字段 + 已盘聚合字段(checked_quantity 已盘数量=作业记录 quantity 合计,无记录为 null;diff_quantity 差异数量=已盘-账面快照,无记录为 null;is_diff 是否有差异 0|1;status 盘点状态 checked|unchecked;location_codes 库位编码数组去重;checkers 盘点人数组去重;last_checked_at 最近上报时间,无记录为 null)+ records(该明细全部盘点作业记录,每条含 id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/barcode/item_name/created_at/updated_at + images 图片列表 [{ id: file_id, url }],FileReference business_type=stock_check_record)+ locations(按库位聚合数组 [{ location_id, location_code, quantity }],quantity 为该库位下作业记录数量合计,空库位记录归 location_code=null 组,按首条记录 id 升序)+ unknown_items(未知商品聚合数组 [{ barcode, item_name, checked_quantity }],按条码升序;记录 stock_id 为空的未知商品按条码归组,无账面、差异=实盘-0=盘盈,已计入行级 checked_quantity/diff_quantity/is_diff;无未知商品为空数组);库位行(scope_type=location)含范围行字段 + stocks(按商品聚合数组 [{ stock_id, item_code, item_name, system_quantity, checked_quantity, diff_quantity }],按 stock_id 升序,仅含存在作业记录的已知商品;system_quantity 为 wms_storage 账面(space_id+stock_id SUM(quantity)),location_id 为空时按 0)+ checked_quantity(行级合计=行内商品实盘合计,无记录为 null)/ diff_quantity(行内各商品差异代数和,无记录为 null)/ is_diff / status + location_codes / checkers / last_checked_at + records / locations + unknown_items(口径同商品行);无作业记录时 records/locations/stocks/unknown_items 为空数组、checked_quantity/diff_quantity/last_checked_at 为 null" - }, - { - "name": "total", + "name": "code", "type": "number", "required": true, - "description": "明细总条数" + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息:成功为 ok;失败为具体错误文案" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "check", + "type": "object", + "required": true, + "description": "盘点主表信息(id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at;start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间))" + }, + { + "name": "rows", + "type": "array", + "required": true, + "description": "明细结果行列表:商品行(scope_type=goods)含范围行字段 + 已盘聚合字段(checked_quantity 已盘数量=作业记录 quantity 合计,无记录为 null;diff_quantity 差异数量=已盘-账面快照,无记录为 null;is_diff 是否有差异 0|1;status 盘点状态 checked|unchecked;location_codes 库位编码数组去重;checkers 盘点人数组去重;last_checked_at 最近上报时间,无记录为 null)+ records(该明细全部盘点作业记录,每条含 id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/barcode/item_name/created_at/updated_at + images 图片列表 [{ id: file_id, url }],FileReference business_type=stock_check_record)+ locations(按库位聚合数组 [{ location_id, location_code, quantity }],quantity 为该库位下作业记录数量合计,空库位记录归 location_code=null 组,按首条记录 id 升序)+ unknown_items(未知商品聚合数组 [{ barcode, item_name, checked_quantity }],按条码升序;记录 stock_id 为空的未知商品按条码归组,无账面、差异=实盘-0=盘盈,已计入行级 checked_quantity/diff_quantity/is_diff;无未知商品为空数组);库位行(scope_type=location)含范围行字段 + is_empty(是否空库位标记:该明细存在空标记记录(is_empty=1)时为 true)+ stocks(按商品聚合数组 [{ stock_id, item_code, item_name, system_quantity, checked_quantity, diff_quantity }],按 stock_id 升序,仅含存在作业记录的已知商品;system_quantity 为 wms_storage 账面(space_id+stock_id SUM(quantity)),location_id 为空时按 0)+ checked_quantity(行级合计=行内商品实盘合计,无记录为 null)/ diff_quantity(行内各商品差异代数和,无记录为 null)/ is_diff / status + location_codes / checkers / last_checked_at + records / locations + unknown_items(口径同商品行);空库位标记(is_empty=true)时:stocks=[]、unknown_items=[]、checked_quantity=0、diff_quantity=0-库位账面库存总量(账面有库存时为负数=盘亏、账面为 0 时为 0)、is_diff=账面有库存时为 1、status=checked(视为已盘点);无作业记录时 records/locations/stocks/unknown_items 为空数组、checked_quantity/diff_quantity/last_checked_at 为 null" + }, + { + "name": "total", + "type": "number", + "required": true, + "description": "明细总条数" + } + ] + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -38395,12 +38582,16 @@ "库位行账面口径:wms_storage 按 (space_id, stock_id) SUM(quantity) 现算(与 finish/export 汇总口径一致),location_id 为空时账面按 0;库位行 stocks 仅含存在作业记录的已知商品(stock_id 有值,无记录时为空数组),商品快照 item_code/item_name 从 wms_stock_warehouse 补齐。", "无作业记录时:checked_quantity/diff_quantity/last_checked_at 为 null、records/locations/stocks 为空数组、status=unchecked、is_diff=0。", "未知商品聚合口径:stock_id 为空的作业记录按 barcode 维度归组输出行级 unknown_items [{ barcode, item_name, checked_quantity }](按条码升序,item_name 为上报名称快照);未知商品无账面,差异=实盘-0=盘盈,已计入行级 checked_quantity/diff_quantity/is_diff;stocks 保持只输出已知商品(stock_id 有值)。代码依据:app/service/systems/stock_check.js#_formatDetailAggregationRow。", - "图片挂载口径(图片独立维护,仿收货 receivingItem):_attachRecordImages 查询 wms_file_reference(business_type=stock_check_record,business_id in 记录ID)并关联 wms_file 取 file_url,每条作业记录挂载 images [{ id: file_id, url }],无图片返回空数组;上传走通用上传接口(uploadSuccessNotify 传 businessType=stock_check_record + businessId=作业记录ID,建 FileReference)。代码依据:app/service/systems/stock_check.js#result/#_attachRecordImages。" + "图片挂载口径(图片独立维护,仿收货 receivingItem):_attachRecordImages 查询 wms_file_reference(business_type=stock_check_record,business_id in 记录ID)并关联 wms_file 取 file_url,每条作业记录挂载 images [{ id: file_id, url }],无图片返回空数组;上传走通用上传接口(uploadSuccessNotify 传 businessType=stock_check_record + businessId=作业记录ID,建 FileReference)。代码依据:app/service/systems/stock_check.js#result/#_attachRecordImages。", + "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", + "空库位标记口径(本次新增):库位行存在空标记记录(is_empty=1)时 is_empty=true——stocks 为空数组、unknown_items 为空数组、checked_quantity=0、status=checked(视为已盘点);账面口径:按 location_id 查 wms_storage SUM(quantity)(该库位全部库存账面总量,location_id 为空时按 0),账面>0 时 diff_quantity=-账面总量(盘亏)、is_diff=1,账面=0 时 diff_quantity=0、is_diff=0。代码依据:app/service/systems/stock_check.js#_formatDetailAggregationRow。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.report:params 新增 is_empty 入参、errors 400 补「仅库位盘点明细支持空库位标记」、description/response/notes 补充空库位语义与互斥及汇总口径;stock.check.workData:description/response.rows 的 location 行新增 is_empty 字段说明;stock.check.result:description/response.rows 库位行新增 is_empty 与空标记盘亏口径;stock.check.recordList:response.rows 记录全字段说明新增 is_empty;stock.check.export:description/notes 补 Sheet2 空库位行输出口径);根版本 0.3.233 → 0.3.234、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 15 条 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 无损。" ] }, { "method": "stock.check.workData", - "description": "拉取盘点作业数据(单接口三视图,view 入参驱动):入参 id(盘点任务ID)+ view(视图类型,仅支持 location/goods/space);返回 { check, rows, total },check 为盘点主表信息(_formatCheckRow 口径),rows 结构随 view 不同、total=rows.length,任务无对应范围行时 rows 返回空数组。view=location(库位结构):以任务库位范围行(scope_type=location)为列表(按明细 id 升序),行内挂该库位的盘点作业记录——goods(已知商品子列表,stock_id 有值)/unknown(未知商品子列表,stock_id 为空);view=goods(商品结构):以任务商品范围行(scope_type=goods)为列表(按明细 id 升序),行内挂按库位聚合的 locations 作业记录,明盘(mode=open)返回账面快照/已盘合计/差异,盲盘(mode=blind)不返回任何数量字段;view=space(聚合库位列表):以任务商品所在库位(wms_storage 中任务 stock_id 集合的启用未删除存储 DISTINCT space_id)为列表,按拣货路径排序(pick_sequence 升序、pick_priority 降序、库位 id 升序兜底),行内 goods 为该库位下的任务商品,明盘含库位账面与已盘数量、盲盘不含数量。状态限制:仅任务状态为 approved(审核完成)或 checking(盘点作业中)时可拉取盘点作业数据,其他状态(created 已创建/submitted 待审核/rejected 已驳回/completed 已完成/cancelled 已取消)返回 400「当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取」。", + "description": "拉取盘点作业数据(视图由任务范围与 is_goods 入参驱动,view 入参已废弃忽略):入参 id(盘点任务ID)+ is_goods(可选,商品任务是否按商品视图返回——true=goods 视图;缺省 false=聚合库位 space 视图;兼容 isGoods 驼峰写法;库位任务无视该参数);返回 { view, rows, total, page, pageSize }(view=服务端实际解析出的视图类型 location/goods/space,供调用方判断 rows 行结构;不返回任务主表信息 check——任务信息请调用 stock.check.detail),rows 结构随解析视图不同(先构建全量行再按页切片,rows 为当前页行)、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 作业记录(每项含 record_ids 该库位该商品全部作业记录 ID(按记录 id 升序)与 images 该库位该商品全部作业照片(扁平去重),供前端编辑/移除记录),明盘(mode=open)返回账面快照/已盘合计/差异,盲盘(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、checked_quantity 按该库位实盘合计)。状态限制:仅任务状态为 approved(审核完成)或 checking(盘点作业中)时可拉取盘点作业数据,其他状态(created 已创建/submitted 待审核/rejected 已驳回/completed 已完成/cancelled 已取消)返回 400「当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取」。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -38420,37 +38611,88 @@ "description": "盘点任务ID(wms_stock_check.id)" }, { - "name": "view", - "type": "string", - "required": true, + "name": "is_goods", + "type": "boolean", + "required": false, "source": "body", - "description": "视图类型,仅支持 location/goods/space:location=库位结构(任务库位范围行为列表,行内挂该库位 goods/unknown 作业记录子列表);goods=商品结构(任务商品范围行为列表,行内挂按库位聚合的 locations 作业记录);space=聚合库位列表(任务商品所在库位,按拣货路径排序,行内挂该库位的任务商品)" + "description": "商品任务是否按商品视图返回(true=goods);缺省 false=聚合库位视图 space;库位任务无视该参数(兼容 isGoods 驼峰写法)" + }, + { + "name": "pagination", + "type": "object", + "required": false, + "source": "body", + "description": "分页参数 { page, pageSize }(可选),默认 page=1、pageSize=20,pageSize 上限 200,分页口径与 stock.check.list 一致" } ], "response": [ { - "name": "check", - "type": "object", + "name": "flag", + "type": "string", "required": true, - "description": "盘点主表信息(id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at;start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间))" + "description": "请求结果标记:success=成功 / failure=失败" }, { - "name": "rows", - "type": "array", - "required": true, - "description": "盘点作业数据行列表,结构随 view 不同——location 视图行:detail_id 明细ID / location_id 库位ID / location_code 库位编码(优先明细快照,缺失回退库位表 space_code)/ location_name 库位名称(custom_name 兜底 space_code)/ status 盘点状态(checked=存在作业记录,unchecked=无)/ has_unknown 是否含未知商品记录 / checked_at 该库位最近上报时间(无记录为 null)/ checkers 盘点人去重数组 + goods 已知商品子列表(stock_id 有值:record_id/stock_id/item_code/item_name/barcode/images/store_id/store_name/quantity 实盘数量/checked_at/checker_name,商品信息批量取自 stockWarehouse.getStockDetails 带缓存、货主名经 _resolveStoreNameMap 解析)+ unknown 未知商品子列表(stock_id 为空:record_id/barcode/item_name/images/quantity/checked_at/checker_name,图片经 _attachRecordImages 挂载 FileReference business_type=stock_check_record);goods 视图行:detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images + locations 按库位聚合数组([{ location_code, checked_at, checker_name }],空库位归 location_code=null 组,按首条记录 id 升序),明盘(mode=open)另含 system_quantity 账面快照/checked_quantity 已盘合计/diff_quantity 差异=已盘-账面/is_diff 是否差异 0|1,locations 各项另含 quantity 该库位实盘合计,盲盘(mode=blind)不返回任何数量字段(locations 仅 location_code/checked_at/checker_name);space 视图行:location_id/location_code/location_name + goods 该库位下的任务商品子列表(detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images + status 已盘状态(该 detail_id+location_code 存在作业记录即 checked,否则 unchecked)),明盘 goods 各项另含 system_quantity(wms_storage space+stock SUM(quantity) 账面)/checked_quantity(该商品在该库位的实盘合计),盲盘不含数量" - }, - { - "name": "total", + "name": "code", "type": "number", "required": true, - "description": "行总数(=rows.length,任务无对应范围行时为 0)" + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息:成功为 ok;失败为具体错误文案" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "view", + "type": "string", + "required": true, + "description": "服务端实际解析出的视图类型(location=库位结构 / goods=商品结构 / space=聚合库位结构),由任务范围(type=location/all 一律 location)与 is_goods 入参共同决定,供调用方判断 rows 行结构" + }, + { + "name": "rows", + "type": "array", + "required": true, + "description": "盘点作业数据行列表(当前页行:先构建全量行再按页切片,total 为全部行数——未分页口径),结构随解析视图不同——location 视图行:detail_id 明细ID / location_id 库位ID / location_code 库位编码(优先明细快照,缺失回退库位表 space_code)/ location_name 库位名称(custom_name 兜底 space_code)/ status 盘点状态(checked=存在作业记录,unchecked=无)/ has_unknown 是否含未知商品记录(该库位存在 stock_id 为空的作业记录时为 true,未知商品同样计入 goods) / is_empty 是否空库位标记(该库位存在空库位标记记录(is_empty=1)时为 true;空标记记录不计入 goods 子列表;存在空标记后该行 status=checked 视为已盘点) / checked_at 该库位最近上报时间(无记录为 null)/ checkers 盘点人去重数组 + goods 作业记录子列表(已知商品与未知商品记录均入内,字段统一 record_id 作业记录ID(单条记录直接定位,可调 recordDelete/recheckClearLocation 移除)/stock_id/item_code/item_name/barcode/images 作业记录照片(已知商品与未知商品均经 _attachRecordImages 挂载 FileReference business_type=stock_check_record,与 result/recordList 口径一致,不再输出商品主图,无照片为空数组)/store_id/store_name/quantity 实盘数量/checked_at/checker_name——已知商品(stock_id 有值)商品信息批量取自 stockWarehouse.getStockDetails 带缓存、货主名经 _resolveStoreNameMap 解析;未知商品(stock_id=null)item_code 用条码兜底、item_name 用名称快照兜底条码、store_id/store_name 为 null);goods 视图行:detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images(行级 images 仍为商品主图 image_url)+ locations 按库位聚合数组([{ location_code, checked_at, checker_name, record_ids 该库位该商品全部作业记录 ID(按记录 id 升序,供前端编辑/移除记录), images 该库位该商品全部记录的作业照片(扁平去重,无照片为空数组) }],空库位归 location_code=null 组,按首条记录 id 升序),明盘(mode=open)另含 system_quantity 账面快照/checked_quantity 已盘合计/diff_quantity 差异=已盘-账面/is_diff 是否差异 0|1,locations 各项另含 quantity 该库位实盘合计,盲盘(mode=blind)不返回任何数量字段(locations 仅 location_code/checked_at/checker_name/record_ids/images);space 视图行:id(库位ID wms_location_space.id)/space_code(库位编码)/custom_barcode(库位自定义条码,空为 null)/custom_name(库位自定义名称,空为 null 不兜底 space_code;库位字段对齐库位查询惯例 index.searchSpace)+ goods 该库位下的任务商品子列表(detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images 该商品在该库位的作业照片聚合(扁平去重,不再输出商品主图,无照片为空数组)/record_ids 该商品在该库位的全部作业记录 ID(按记录 id 升序,供前端编辑/移除记录) + status 已盘状态(该 detail_id+location_code 存在作业记录即 checked,否则 unchecked)),明盘 goods 各项另含 system_quantity(wms_storage space+stock SUM(quantity) 账面,该库位无库存记录时按 0)/checked_quantity(该商品在该库位的实盘合计),盲盘不含数量;库位集合=当前库存库位 ∪ 作业记录库位(盘点前库存已出空但已有盘点作业记录的库位也能展示)" + }, + { + "name": "total", + "type": "number", + "required": true, + "description": "行总数(全部行数——未分页口径,任务无对应范围行时为 0;分页时 rows 为当前页行、total 保持全部行数不变)" + }, + { + "name": "page", + "type": "number", + "required": true, + "description": "当前页码(未传或非法时默认 1,分页口径与 stock.check.list 一致)" + }, + { + "name": "pageSize", + "type": "number", + "required": true, + "description": "每页数量(默认 20,上限 200,分页口径与 stock.check.list 一致)" + } + ] + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, - "message": "盘点任务ID不能为空 / 视图类型非法(仅支持 location/goods/space)" + "message": "盘点任务ID不能为空" }, { "code": 400, @@ -38466,20 +38708,50 @@ } ], "notes": [ - "代码依据:app/service/systems/stock_check.js#workData(id 非正整数抛 400『盘点任务ID不能为空』;view 非 location/goods/space 抛 400『视图类型非法(仅支持 location/goods/space)』;任务不存在(按 id+warehouse_id 查 wms_stock_check)抛 400『盘点任务不存在』;新增状态守卫:任务状态非 REPORT_ALLOWED_STATUSES(approved/checking)时抛 400『当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取』,即与 report/finish 一致的口径;按 view 分派 _buildLocationWorkRows/_buildGoodsWorkRows/_buildSpaceWorkRows,统一返回 { check: _formatCheckRow 口径, rows, total: rows.length })+ app/service/systemMethods/stock/check.js#workData(warehouse_id 由服务端从 ctx.user.store_id 自动注入,前端无需传递);本次仅同步文档,未改动任何代码。", - "三视图口径:location=库位结构,以任务库位范围行(scope_type=location)为列表(按明细 id 升序),行内挂该库位盘点作业记录——goods 已知商品子列表(stock_id 有值,商品信息批量取自 stockWarehouse.getStockDetails 带缓存、货主名 _resolveStoreNameMap 解析、图片 image_url)与 unknown 未知商品子列表(stock_id 为空,输出记录快照 barcode/item_name/images,图片经 _attachRecordImages 挂载 FileReference business_type=stock_check_record);goods=商品结构,以任务商品范围行(scope_type=goods)为列表(按明细 id 升序),行内挂按库位聚合的 locations(空库位归 location_code=null 组,按首条记录 id 升序);space=聚合库位列表,以任务商品(scope_type=goods 的 stock_id 集合)所在库位为列表——wms_storage(warehouse_id + stock_id 在集合 + is_enabled=1 未删除)DISTINCT space_id,行内 goods 为该库位下的任务商品,未在 wms_storage 有库位的商品不入列表。", - "明盘/盲盘数量控制:明盘(mode=open)goods 视图行返回 system_quantity(明细账面快照)/checked_quantity(已盘合计=locations.quantity 合计)/diff_quantity(已盘-账面)/is_diff(差异非 0 为 1),locations 各项含 quantity(该库位实盘合计);space 视图 goods 各项含 system_quantity(wms_storage space+stock SUM(quantity) 账面)/checked_quantity(该商品在该库位的实盘合计);盲盘(mode=blind)不返回任何数量字段(goods 视图 locations 仅 location_code/checked_at/checker_name,space 视图 goods 仅商品信息+status);无作业记录时 locations 为空数组、明盘已盘合计/差异按 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/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 错误。", + "三视图口径(由任务范围 + 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(空库位归 location_code=null 组,按首条记录 id 升序);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 各项含 quantity(该库位实盘合计);space 视图 goods 各项含 system_quantity(wms_storage space+stock SUM(quantity) 账面,该库位无库存记录时按 0)/checked_quantity(该商品在该库位的实盘合计);盲盘(mode=blind)不返回任何数量字段(goods 视图 locations 仅 location_code/checked_at/checker_name/record_ids/images,space 视图 goods 仅商品信息+images/record_ids/status);无作业记录时 locations 为空数组、明盘已盘合计/差异按 0(避免未盘行误显盘亏差异)。", "排序口径:space 视图库位按拣货路径排序——pick_sequence 升序、pick_priority 降序、同值按库位 id 升序兜底;space 行内 goods 按 stock_id 升序;location/goods 视图行按明细 id 升序;goods 视图 locations 按首条记录 id 升序。", - "权限口径:随 ALL_METHOD_NAMES(20 个:create/list/addDetail/addLocationDetail/detailDelete/detail/result/workData/report/recordList/recordDelete/finish/submit/cancel/audit/batchDelete/export/exportTaskProgress/patternList/patternCreate)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(_noNeedAuth)、必须登录(isNeedLogin=true,免登录清单为空);为查询类方法,加入免日志清单 _noNeedLog(list/detail/result/workData/recordList/export/exportTaskProgress/patternList),不记录操作日志。", + "权限口径:随 ALL_METHOD_NAMES(22 个:create/list/addDetail/addLocationDetail/detailDelete/detail/result/workData/report/markEmpty/recordList/recordDelete/recheckClearLocation/finish/submit/cancel/audit/batchDelete/export/exportTaskProgress/patternList/patternCreate)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(_noNeedAuth)、必须登录(isNeedLogin=true,免登录清单为空);为查询类方法,加入免日志清单 _noNeedLog(list/detail/result/workData/recordList/export/exportTaskProgress/patternList),不记录操作日志。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.workData 一条(位于 stock.check.result 之后);根版本 0.3.224 → 0.3.225、updatedAt 2026-10-01 → 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 19 条 method 未改动(stock.check 分组由 19 条增至 20 条)。", "状态限制口径:仅任务状态为 approved(审核完成)或 checking(盘点作业中)可拉取盘点作业数据;其他状态(created 已创建/submitted 待审核/rejected 已驳回/completed 已完成/cancelled 已取消)返回 400,message 为『当前状态({状态中文标签,无标签时回退状态值})不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取』,状态标签取 STOCK_CHECK_STATUS_LABELS。状态守卫复用 REPORT_ALLOWED_STATUSES 常量,与 report(盘点作业上报)及 finish(完成盘点)一致。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(errors 的 400 新增状态限制文案并拆分为独立条目、description/notes 补充状态限制口径;headers/params/response/isNeedAuth/isNeedLogin 不变);根版本 0.3.225 → 0.3.226、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)与生产库(NODE_ENV=production + --env production 双设置)——import 当前 system.json → export 回写往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。" + "库表维护源说明:维护源为库表(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)与生产库(NODE_ENV=production + --env production 双设置)——import 当前 system.json → export 回写往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。", + "库位字段口径(本次对齐):space 视图行字段对齐库位查询惯例(index.searchSpace,app/service/systems/space.js#_searchByKeyword attributes)——id=wms_location_space.id、space_code=库位编码、custom_barcode=库位自定义条码(空为 null)、custom_name=库位自定义名称(空为 null,不再兜底 space_code);goods 子列表字段不变(detail_id/stock_id/item_code/item_name/spec/store_id/store_name/barcode/images/status,明盘另含 system_quantity/checked_quantity);仅 space 视图行字段变化,location/goods 视图行字段不变。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(description/response.rows/notes 同步 space 视图库位聚合来源扩展与行字段规范对齐;headers/params/errors/isNeedAuth/isNeedLogin 不变);根版本 0.3.227 → 0.3.228、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 + --env production)——import 当前 system.json → export 回写往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。", + "分页口径(本次新增):三视图先构建全量行(_buildLocationWorkRows/_buildGoodsWorkRows/_buildSpaceWorkRows)再按页切片(slice(offset, offset+pageSize));rows 为当前页行、total 为全部行数(未分页口径)、响应新增 page(当前页码)与 pageSize(每页数量);page 默认 1、pageSize 默认 20、上限 200(非法值回退默认)。代码依据:app/service/systems/stock_check.js#workData。", + "分页入参口径(与 stock.check.list 一致):仅入参 data.pagination.{page,pageSize},不再兼容 page_size 蛇形写法、不再支持顶层 data.page / data.pageSize / data.page_size;方法层(app/service/systemMethods/stock/check.js#workData)直接透传 pagination 对象给系统层;系统层(app/service/systems/stock_check.js#workData)page=Math.max(1, Number(pagination.page)||1) 默认 1、pageSize=Math.min(200, Math.max(1, Number(pagination.pageSize)||20)) 默认 20 上限 200、非法回退默认;先构建全量行再按页切片,返回 { check, rows, total, page, pageSize }。本次代码已改并测试通过 197/197、ESLint 0 错误。", + "向后兼容:旧调用方不传分页参数时默认 page=1、pageSize=20,rows 行为与旧版一致(全量行数不超过 20 时)、total 不变;仅响应新增 page/pageSize 两个字段,其余字段口径不变。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params 新增 pagination、response 新增 page/pageSize 并同步 rows/total 口径、description/notes 补充分页口径;headers/errors/isNeedAuth/isNeedLogin 不变);根版本 0.3.228 → 0.3.229、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 + --env production)——import 当前 system.json → export 回写往返校验,保持库与文件一致;stock.check 分组共 20 条 method 无损。", + "分页口径修正(本次):上一轮文档曾描述「支持顶层 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 传值不再生效。", + "文档变更范围: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)。", + "location 视图行结构改造(本次):_buildLocationWorkRows 删除 unknown 未知商品子列表——未知商品记录(stock_id 为空)不再单独输出,与已知商品统一并入 goods 子列表、输出字段对齐已知商品(record_id/stock_id=null/item_code 用条码兜底/item_name 用名称快照兜底条码/barcode/images/store_id=null/store_name=null/quantity/checked_at/checker_name);行级 has_unknown 标记保留(该库位是否含未知商品记录)。代码依据:app/service/systems/stock_check.js#_buildLocationWorkRows。影响面:前端无需再处理 unknown 数组,直接遍历 goods、按 stock_id 是否为 null 区分未知商品。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(description/response.rows/notes 同步 location 视图行结构:删除 unknown 子列表字段说明、goods 改为「已知商品与未知商品记录均入内,未知商品 stock_id=null、item_code 用条码兜底、store_id/store_name 为 null」、has_unknown 保留说明;headers/params/errors/isNeedAuth/isNeedLogin 与 goods/space 视图及分页描述不变);根版本 0.3.232 → 0.3.233、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 无损。", + "空库位标记口径(本次新增):location 视图行新增 is_empty 字段——_buildLocationWorkRows 遍历该库位作业记录,存在空标记记录(is_empty=1)时 isEmptyLocation=true 且该记录不计入 goods 子列表(不输出为商品记录行);行级 status 仍按存在作业记录口径判断(空标记记录同样是记录),因此空标记后 status=checked 视为已盘点;checked_at/checkers 口径不变。代码依据:app/service/systems/stock_check.js#_buildLocationWorkRows。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.report:params 新增 is_empty 入参、errors 400 补「仅库位盘点明细支持空库位标记」、description/response/notes 补充空库位语义与互斥及汇总口径;stock.check.workData:description/response.rows 的 location 行新增 is_empty 字段说明;stock.check.result:description/response.rows 库位行新增 is_empty 与空标记盘亏口径;stock.check.recordList:response.rows 记录全字段说明新增 is_empty;stock.check.export:description/notes 补 Sheet2 空库位行输出口径);根版本 0.3.233 → 0.3.234、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 15 条 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 无损。", + "作业照片与 record_ids 口径(本次新增):三视图统一挂载作业记录照片(FileReference business_type=stock_check_record,_attachRecordImages 挂载,与 result/recordList 口径一致)——location 视图 goods 子项 images 为作业记录照片(已知商品由商品主图 stockDetail.image_url 改为作业记录照片,未知商品维持记录照片,无照片为空数组),record_id 为单条作业记录 ID(可直接定位,供 recordDelete/recheckClearLocation 移除);goods 视图行级 images 仍为商品主图,locations 聚合项新增 images(该库位该商品全部记录的作业照片扁平去重,无照片为空数组)与 record_ids(该库位该商品全部作业记录 ID,按记录 id 升序);space 视图 goods 子项 images 由商品主图改为该商品在该库位的作业照片聚合(扁平去重,无照片为空数组),并新增 record_ids(该商品在该库位全部作业记录 ID,按记录 id 升序)。record_ids 供前端编辑/移除记录(stock.check.recordDelete 批量删除 / stock.check.recheckClearLocation 重盘清除库位);行级/未盘项无记录时 images/record_ids 为空数组。代码依据:app/service/systems/stock_check.js#_buildLocationWorkRows/#_buildGoodsWorkRows/#_buildSpaceWorkRows。本次代码已改并测试通过 214/214、ESLint 0 错误。", + "影响面:location 视图已知商品子项 images 由商品主图变为作业记录照片;goods 视图 locations 项新增 record_ids/images;space 视图 goods 子项 images 由商品主图变为作业照片聚合并新增 record_ids;goods 视图行级 images(商品主图)不变;其余字段(check/rows/total/page/pageSize、明盘/盲盘数量控制、状态限制)不变。", + "文档变更范围: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。与视图解析规则一一对应。", + "兼容性影响(破坏性变更):响应 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 往返校验),保持库与文件一致。" ] }, { "method": "stock.check.report", - "description": "盘点作业上报(覆盖式):商品明细行(scope_type=goods)固定上报明细商品(入参 stock_id 与明细商品不一致报错),库位可选(未传归入\"无库位\"分组,location_code 存空串 '');库位明细行(scope_type=location)必须指定商品(stock_id 或 barcode 至少一项),库位以明细库位为准(入参库位与明细库位不一致报错,不传时默认明细库位);覆盖式查重:已知商品维度 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 即盘盈、必然计入差异);数据库层由唯一索引 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 状态允许;库位编码匹配 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);都未传沿用原报错口径。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -38539,56 +38811,95 @@ "required": false, "source": "body", "description": "未知商品名称快照(可选):仅未知商品记录落库,缺省为 barcode;已知商品忽略" + }, + { + "name": "is_empty", + "type": "boolean", + "required": false, + "source": "body", + "description": "空库位标记(可选,仅库位明细行 scope_type=location 支持):true 表示「确认该库位为空」——不要求商品/条码,quantity 恒为 0(不参与数量校验),写一条特殊作业记录(stock_id=null、barcode=null、item_name=null、quantity=0、is_empty=1);与商品记录互斥:标记空时删除该明细下所有商品记录(含未知商品),上报商品时删除该明细下空标记记录;商品明细行传 true 报 400「仅库位盘点明细支持空库位标记」" } ], "response": [ { - "name": "record", + "name": "flag", + "type": "string", + "required": true, + "description": "请求结果标记:success=成功 / failure=失败" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息:成功为 ok;失败为具体错误文案" + }, + { + "name": "data", "type": "object", "required": true, - "description": "新增或更新的盘点作业记录(wms_stock_check_record 行:id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/barcode/item_name/created_at/updated_at);stock_id 可空:NULL=未知商品(此时 barcode=扫描条码、item_name=未知商品名称快照(缺省为条码)),已知商品 barcode/item_name 可能为空" + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "record", + "type": "object", + "required": true, + "description": "新增或更新的盘点作业记录(wms_stock_check_record 行:id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/barcode/item_name/is_empty/created_at/updated_at);stock_id 可空:NULL=未知商品(此时 barcode=扫描条码、item_name=未知商品名称快照(缺省为条码)),已知商品 barcode/item_name 可能为空;is_empty=1 为空库位标记记录(stock_id/barcode/item_name 均为 null、quantity=0)" + }, + { + "name": "detail_id", + "type": "number", + "required": true, + "description": "盘点明细ID" + }, + { + "name": "mode", + "type": "string", + "required": true, + "description": "本次上报模式:created=首次上报新增记录 / updated=同明细+同商品+同库位重复上报更新已有记录(未知商品为同明细+同条码+同库位)" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "明细总行数" + }, + { + "name": "checked_items", + "type": "number", + "required": true, + "description": "已盘行数(存在作业记录的明细数;空库位标记记录同样计入已盘)" + }, + { + "name": "diff_items", + "type": "number", + "required": true, + "description": "差异行数(实盘合计与账面不一致的明细数;未知商品无账面,实盘>0 即盘盈、必然计入差异;空标记明细的库位账面有库存即计盘亏差异)" + }, + { + "name": "detail_status", + "type": "string", + "required": true, + "description": "明细盘点进度:none_checked/partial_checked/all_checked" + } + ] }, { - "name": "detail_id", + "name": "timestamp", "type": "number", "required": true, - "description": "盘点明细ID" - }, - { - "name": "mode", - "type": "string", - "required": true, - "description": "本次上报模式:created=首次上报新增记录 / updated=同明细+同商品+同库位重复上报更新已有记录(未知商品为同明细+同条码+同库位)" - }, - { - "name": "total_items", - "type": "number", - "required": true, - "description": "明细总行数" - }, - { - "name": "checked_items", - "type": "number", - "required": true, - "description": "已盘行数(存在作业记录的明细数)" - }, - { - "name": "diff_items", - "type": "number", - "required": true, - "description": "差异行数(实盘合计与账面不一致的明细数;未知商品无账面,实盘>0 即盘盈、必然计入差异)" - }, - { - "name": "detail_status", - "type": "string", - "required": true, - "description": "明细盘点进度:none_checked/partial_checked/all_checked" + "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, - "message": "盘点任务ID不能为空 / 盘点明细ID不能为空 / 盘点任务不存在 / 当前状态(非 approved/checking)不允许盘点作业 / 实盘数量必须为不小于0的整数 / 盘点明细不存在 / 盘点明细缺少商品信息 / 上报商品与盘点明细商品不一致 / 按库位盘点时必须指定商品 / 上报商品不属于本仓库 / 盘点明细缺少库位信息 / 上报库位与盘点明细库位不一致" + "message": "盘点任务ID不能为空 / 盘点明细ID不能为空 / 盘点任务不存在 / 当前状态(非 approved/checking)不允许盘点作业 / 实盘数量必须为不小于0的整数 / 盘点明细不存在 / 盘点明细缺少商品信息 / 上报商品与盘点明细商品不一致 / 按库位盘点时必须指定商品 / 上报商品不属于本仓库 / 盘点明细缺少库位信息 / 上报库位与盘点明细库位不一致 / 仅库位盘点明细支持空库位标记" }, { "code": 500, @@ -38602,12 +38913,166 @@ "start_time 口径:主表 start_time 为空时以本次明细写入时间补写(首个盘点明细写入时间记录为 start_time=盘点开始时间);代码依据 app/service/systems/stock_check.js#report(start_time 为空则补写,保证任何状态下首个明细落盘时间都被记录)。", "未知商品上报口径(stock_id 与 barcode 至少传一项):传了 stock_id 按已知商品走现有逻辑(本仓库校验等);未传 stock_id 但传了 barcode,先按条码匹配系统商品(_resolveStockIdByBarcode:wms_stock_barcodes 按 barcode+本仓库匹配,再校验 wms_stock_warehouse 中该商品属于本仓库),命中回填 stock_id 按已知商品处理(商品明细行还会校验与明细商品一致),未命中记录未知商品(stock_id=NULL + barcode + item_name,item_name 缺省为 barcode);都未传沿用现有报错口径(商品行缺商品信息报 400 / 库位行缺商品报 400)。", "未知商品覆盖式查重:已知商品 where { detail_id, stock_id, location_code } 不变;未知商品 where { detail_id, stock_id: null, barcode, location_code } 应用层查重(唯一索引 uk_detail_stock_location 不约束 NULL 行,并发下撞索引/冲突时同样按查重条件降级更新兜底)。", - "迁移依据:database/migrations/20261001100000-support-unknown-goods-in-stock-check-record.js(wms_stock_check_record:stock_id 改可空(NULL=未知商品)+ 新增 barcode VARCHAR(100)/item_name VARCHAR(255),本地与生产均已执行)。" + "迁移依据:database/migrations/20261001100000-support-unknown-goods-in-stock-check-record.js(wms_stock_check_record:stock_id 改可空(NULL=未知商品)+ 新增 barcode VARCHAR(100)/item_name VARCHAR(255),本地与生产均已执行)。", + "响应统一 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)。", + "空库位标记上报口径(本次新增):is_empty 仅库位明细行(scope_type=location)支持,商品明细行传 is_empty 报 400『仅库位盘点明细支持空库位标记』;标记空时不要求商品/条码,quantity 恒为 0(跳过『实盘数量必须为不小于0的整数』校验),写一条特殊作业记录(stock_id=null、barcode=null、item_name=null、quantity=0、is_empty=1);覆盖式查重按(detail_id + is_empty=1 + location_code)应用层查重覆盖更新。互斥口径:标记空时删除该明细下所有商品记录(is_empty=false,含未知商品),上报商品时删除该明细下空标记记录(is_empty=true),两者不会并存。代码依据:app/service/systems/stock_check.js#report。", + "汇总口径(本次同步 _recalcCheckSummary):空库位标记记录计入已盘明细(checked_items 按 DISTINCT detail_id 自然计入、detail_status 按已盘占比正常推进);差异口径:空标记明细的库位账面(wms_storage 按 space_id SUM(quantity))有库存即计盘亏差异(diff_items 加 1),账面无库存不计差异。代码依据:app/service/systems/stock_check.js#_recalcCheckSummary。", + "迁移依据:database/migrations/20261002160000-add-is-empty-to-stock-check-record.js(wms_stock_check_record 新增 is_empty TINYINT(1) NOT NULL DEFAULT 0,COMMENT 是否空库位标记(1=确认为空),开发与生产库均已执行)。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.report:params 新增 is_empty 入参、errors 400 补「仅库位盘点明细支持空库位标记」、description/response/notes 补充空库位语义与互斥及汇总口径;stock.check.workData:description/response.rows 的 location 行新增 is_empty 字段说明;stock.check.result:description/response.rows 库位行新增 is_empty 与空标记盘亏口径;stock.check.recordList:response.rows 记录全字段说明新增 is_empty;stock.check.export:description/notes 补 Sheet2 空库位行输出口径);根版本 0.3.233 → 0.3.234、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 15 条 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 无损。" + ] + }, + { + "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)自动注入,前端无需传递。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "盘点任务ID(正整数;非法抛 400「盘点任务ID不能为空」)" + }, + { + "name": "detail_id", + "type": "number", + "required": true, + "source": "body", + "description": "库位明细ID(正整数;非法抛 400「盘点明细ID不能为空」;明细必须属于本任务且为库位范围行 scope_type=location,非库位行报 400「仅库位盘点明细支持空库位标记」)" + } + ], + "response": [ + { + "name": "flag", + "type": "string", + "required": true, + "description": "请求结果标记:success=成功 / failure=失败" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息:成功为 ok;失败为具体错误文案" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,与 report 口径一致;失败时 data=null)", + "children": [ + { + "name": "record", + "type": "object", + "required": true, + "description": "新增或更新的空库位标记作业记录(wms_stock_check_record 行全字段:id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/barcode/item_name/is_empty/created_at/updated_at);is_empty=1 空库位标记记录:stock_id/barcode/item_name 均为 null、quantity=0" + }, + { + "name": "detail_id", + "type": "number", + "required": true, + "description": "盘点明细ID" + }, + { + "name": "mode", + "type": "string", + "required": true, + "description": "本次写入模式:created=首次写入空标记记录 / updated=重复标记更新已有空标记记录" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "明细总行数" + }, + { + "name": "checked_items", + "type": "number", + "required": true, + "description": "已盘行数(存在作业记录的明细数;空库位标记记录同样计入已盘)" + }, + { + "name": "diff_items", + "type": "number", + "required": true, + "description": "差异行数(实盘合计与账面不一致的明细数;空标记明细的库位账面有库存即计盘亏差异)" + }, + { + "name": "detail_status", + "type": "string", + "required": true, + "description": "明细盘点进度:none_checked/partial_checked/all_checked" + } + ] + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" + } + ], + "errors": [ + { + "code": 400, + "message": "盘点任务ID不能为空" + }, + { + "code": 400, + "message": "盘点明细ID不能为空" + }, + { + "code": 400, + "message": "盘点任务不存在" + }, + { + "code": 400, + "message": "当前状态(xx)不允许盘点作业" + }, + { + "code": 400, + "message": "仅库位盘点任务支持空库位标记" + }, + { + "code": 400, + "message": "盘点明细不存在" + }, + { + "code": 400, + "message": "仅库位盘点明细支持空库位标记" + }, + { + "code": 500, + "message": "服务器内部错误" + } + ], + "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「仅库位盘点明细支持空库位标记」。", + "权限口径:随 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 条。", + "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次先经 script/method-doc-create.cjs 在维护源新建本方法(--bump 版本 0.3.234→0.3.235),再按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入变更记录;随后同步回填开发库(显式 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 分组共 21 条 method 无损。" ] }, { "method": "stock.check.recordList", - "description": "拉取盘点作业记录列表:至少传 id(盘点任务ID)或 detail_id(明细ID)之一(可同时传,detail_id 生效时只查该明细的作业记录);按当前用户仓库(ctx.user.store_id)限定数据范围;rows 每条为作业记录(wms_stock_check_record)全字段 + 商品快照列(item_code/item_name);未知商品(stock_id 为空)商品编码列显示扫描条码(barcode)、名称列显示上报名称快照(item_name);每条记录挂载 images(FileReference business_type=stock_check_record,仿收货 receivingItem 口径);按记录 id 倒序,分页返回。", + "description": "拉取盘点作业记录列表:至少传 id(盘点任务ID)或 detail_id(明细ID)之一(可同时传,detail_id 生效时只查该明细的作业记录);按当前用户仓库(ctx.user.store_id)限定数据范围;rows 每条为作业记录(wms_stock_check_record)全字段(id/check_id/warehouse_id/detail_id/stock_id/barcode/item_name/location_id/location_code/quantity/checker_id/checker_name/checked_at/is_empty/remark/created_at/updated_at 等)+ 商品信息列(item_code/item_name/spec/store_id/store_name/barcode,挂载口径对齐 workData);未知商品(stock_id 为空)商品编码列显示扫描条码(barcode)、名称列显示上报名称快照(item_name),spec/store_id/store_name 为 null、barcode=扫描条码;每条记录挂载 images(FileReference business_type=stock_check_record,仿收货 receivingItem 口径);按记录 id 倒序,分页返回。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -38643,28 +39108,60 @@ ], "response": [ { - "name": "rows", - "type": "array", + "name": "flag", + "type": "string", "required": true, - "description": "作业记录行列表:每条为 wms_stock_check_record 全字段(id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/barcode/item_name/created_at/updated_at)+ 商品快照列 item_code/item_name + images 图片列表 [{ id: file_id, url }](FileReference business_type=stock_check_record);stock_id 可空(NULL=未知商品);item_code/item_name 口径:未知商品(stock_id 为空)item_code=扫描条码(barcode,空则 null)、item_name=上报名称快照(item_name 或 barcode 兜底),已知商品从明细表(wms_stock_check_detail)商品快照补齐;location_code 口径:库中空串(\"无库位\"分组)返回时归一为 null(接口返回口径不变)" + "description": "请求结果标记:success=成功 / failure=失败" }, { - "name": "total", + "name": "code", "type": "number", "required": true, - "description": "总条数" + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { - "name": "page", - "type": "number", + "name": "message", + "type": "string", "required": true, - "description": "当前页码" + "description": "提示信息:成功为 ok;失败为具体错误文案" }, { - "name": "pageSize", + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "rows", + "type": "array", + "required": true, + "description": "作业记录行列表:每条为 wms_stock_check_record 全字段(id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/barcode/item_name/is_empty/created_at/updated_at 等,保留记录全字段)+ 商品信息列 item_code/item_name/spec/store_id/store_name/barcode(挂载口径对齐 workData)+ images 图片列表 [{ id: file_id, url }](FileReference business_type=stock_check_record);stock_id 可空(NULL=未知商品);商品信息口径(对齐 workData):已知商品(stock_id 有值)item_code/item_name/spec 批量取自 stockWarehouse.getStockDetails(带缓存,未命中回退明细表 wms_stock_check_detail 商品快照)、store_id=商品货主ID、store_name=货主名(经 _resolveStoreNameMap 解析)、barcode=商品条码兜底(getStockDetails.barcodes[0],无则保留记录原始条码);未知商品(stock_id 为空)item_code=扫描条码(barcode,空则 null)、item_name=上报名称快照(item_name 或 barcode 兜底)、spec=null、store_id=null、store_name=null、barcode=扫描条码;location_code 口径:库中空串(\"无库位\"分组)返回时归一为 null(接口返回口径不变);is_empty 空库位标记:1=空库位标记记录(stock_id/barcode/item_name 均为 null、quantity=0)" + }, + { + "name": "total", + "type": "number", + "required": true, + "description": "总条数" + }, + { + "name": "page", + "type": "number", + "required": true, + "description": "当前页码" + }, + { + "name": "pageSize", + "type": "number", + "required": true, + "description": "每页条数" + } + ] + }, + { + "name": "timestamp", "type": "number", "required": true, - "description": "每页条数" + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -38681,13 +39178,19 @@ "查询类方法,不记录操作日志(免日志清单:list/detail/result/recordList/export/exportTaskProgress)。", "rows 按记录 id 倒序返回。", "location_code 返回口径:库中空串(无库位分组)归一为 null,接口返回口径不变(与 detail 的 locations/location_codes 空库位组 location_code=null 一致)。", - "未知商品显示口径:stock_id 为空的记录 item_code 显示扫描条码(barcode,空则 null)、item_name 显示上报名称快照(item_name 或 barcode 兜底);已知商品维持从明细表(wms_stock_check_detail)商品快照补齐。代码依据:app/service/systems/stock_check.js#recordList。", - "图片挂载口径(图片独立维护,仿收货 receivingItem):查询 wms_file_reference(business_type=stock_check_record)+ wms_file.file_url,每条记录挂载 images [{ id, url }],无图片返回空数组;上传走通用上传接口(businessType=stock_check_record + businessId=作业记录ID,建 FileReference)。" + "商品信息挂载对齐 workData(本次更新):已知商品(stock_id 有值)item_code/item_name/spec 批量取自 stockWarehouse.getStockDetails(带缓存,未命中回退明细表 wms_stock_check_detail 商品快照),新增 store_id(商品货主ID)/store_name(货主名,经 _resolveStoreNameMap 解析)、barcode 兜底商品条码(getStockDetails.barcodes[0],无则保留记录原始条码);未知商品(stock_id 为空)item_code=扫描条码(barcode,空则 null)、item_name=上报名称快照(item_name 或 barcode 兜底)、spec=null、store_id=null、store_name=null、barcode=扫描条码。保留记录全字段不变、向后兼容(仅新增列)。代码依据:app/service/systems/stock_check.js#recordList。本次代码已改并测试通过 215/215、ESLint 0 错误。", + "图片挂载口径(图片独立维护,仿收货 receivingItem):查询 wms_file_reference(business_type=stock_check_record)+ wms_file.file_url,每条记录挂载 images [{ id, url }],无图片返回空数组;上传走通用上传接口(businessType=stock_check_record + businessId=作业记录ID,建 FileReference)。", + "响应统一 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)。", + "空库位标记记录输出(本次新增):rows 每条为记录表全字段,is_empty 自动带出(1=空库位标记记录:stock_id/barcode/item_name 均为 null、quantity=0),未知商品显示口径不受影响。代码依据:app/service/systems/stock_check.js#recordList。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.report:params 新增 is_empty 入参、errors 400 补「仅库位盘点明细支持空库位标记」、description/response/notes 补充空库位语义与互斥及汇总口径;stock.check.workData:description/response.rows 的 location 行新增 is_empty 字段说明;stock.check.result:description/response.rows 库位行新增 is_empty 与空标记盘亏口径;stock.check.recordList:response.rows 记录全字段说明新增 is_empty;stock.check.export:description/notes 补 Sheet2 空库位行输出口径);根版本 0.3.233 → 0.3.234、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 15 条 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 无损。", + "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.recordList 一条(description/response.rows 补充新增字段 spec/store_id/store_name 与 barcode 兜底口径(对齐 workData)、说明保留记录全字段;notes 补充「商品信息挂载对齐 workData」说明;headers/params/errors/isNeedAuth/isNeedLogin 不变);根版本 0.3.239 → 0.3.240、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 无损。" ] }, { "method": "stock.check.recordDelete", - "description": "删除盘点作业记录:仅主表状态 approved/checking 允许删除;记录必须属于该盘点任务与当前仓库,删除后重算 checked_items/diff_items/detail_status(该明细作业记录删光后回到未盘口径),主表状态不回退;同时清理该记录的图片引用(FileReference business_type=stock_check_record,失败仅告警不影响主流程)。", + "description": "删除盘点作业记录(由旧版单值删除升级为批量删除,口径与 detailDelete 批量一致):入参 record_ids 数组(单次上限 200;兼容 recordIds 驼峰数组、recordId 单数驼峰、record_id 单值旧写法,单值自动转数组);仅主表状态 approved/checking 允许删除;记录必须属于该盘点任务与当前仓库,查不到的记录 ID 计入 skipped_ids 不报错(deleted_ids/skipped_ids 保持入参顺序);删除后清理该批记录的图片引用(FileReference business_type=stock_check_record,失败仅告警不影响主流程)、重算 checked_items/diff_items/detail_status(明细作业记录删光后回到未盘口径),主表状态不回退;写 STOCK_CHECK_DELETE_RECORD 操作日志(文案「批量删除盘点作业记录 N 条」)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -38707,62 +39210,130 @@ "description": "盘点任务ID" }, { - "name": "record_id", - "type": "number", + "name": "record_ids", + "type": "array", "required": true, "source": "body", - "description": "作业记录ID(wms_stock_check_record.id)" + "description": "作业记录ID数组(wms_stock_check_record.id;单次上限 200;兼容旧版单值写法——传单值自动转数组)" + }, + { + "name": "recordIds", + "type": "array", + "required": false, + "source": "body", + "description": "作业记录ID数组(驼峰别名,兼容写法;record_ids 优先)" }, { "name": "recordId", "type": "number", "required": false, "source": "body", - "description": "作业记录ID(驼峰别名,兼容写法;record_id 优先)" + "description": "作业记录ID(单数驼峰,兼容旧版单值写法;record_ids/recordIds 优先,单值自动转数组)" + }, + { + "name": "record_id", + "type": "number", + "required": false, + "source": "body", + "description": "作业记录ID(旧版单值写法,兼容;record_ids/recordIds/recordId 优先,单值自动转数组)" } ], "response": [ { - "name": "record_id", - "type": "number", - "required": true, - "description": "被删除的作业记录ID" - }, - { - "name": "deleted", - "type": "boolean", - "required": true, - "description": "是否删除成功(true)" - }, - { - "name": "total_items", - "type": "number", - "required": true, - "description": "明细总行数" - }, - { - "name": "checked_items", - "type": "number", - "required": true, - "description": "重算后的已盘行数(存在作业记录的明细数)" - }, - { - "name": "diff_items", - "type": "number", - "required": true, - "description": "重算后的差异行数(实盘合计与账面快照不一致的明细数;未知商品无账面,实盘>0 即盘盈、必然计入差异)" - }, - { - "name": "detail_status", + "name": "flag", "type": "string", "required": true, - "description": "重算后的明细盘点进度:none_checked/partial_checked/all_checked" + "description": "请求结果标记:success=成功 / failure=失败" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息:成功为 ok;失败为具体错误文案" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径见 data.children;失败时 data=null)", + "children": [ + { + "name": "deleted_count", + "type": "number", + "required": true, + "description": "实际删除的作业记录条数" + }, + { + "name": "deleted_ids", + "type": "array", + "required": true, + "description": "实际删除的作业记录ID列表(保持入参顺序)" + }, + { + "name": "skipped_ids", + "type": "array", + "required": true, + "description": "未删除(未命中:记录不存在或不属于该任务/仓库)的ID列表(保持入参顺序;查不到不报错)" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "明细总行数" + }, + { + "name": "checked_items", + "type": "number", + "required": true, + "description": "重算后的已盘行数(存在作业记录的明细数)" + }, + { + "name": "diff_items", + "type": "number", + "required": true, + "description": "重算后的差异行数(实盘合计与账面快照不一致的明细数;未知商品无账面,实盘>0 即盘盈、必然计入差异)" + }, + { + "name": "detail_status", + "type": "string", + "required": true, + "description": "重算后的明细盘点进度:none_checked/partial_checked/all_checked" + } + ] + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, - "message": "盘点任务ID不能为空 / 作业记录ID不能为空 / 盘点任务不存在 / 当前状态(非 approved/checking)不允许删除作业记录 / 作业记录不存在或不属于该盘点任务" + "message": "盘点任务ID不能为空" + }, + { + "code": 400, + "message": "盘点任务不存在" + }, + { + "code": 400, + "message": "当前状态(非 approved/checking)不允许删除作业记录" + }, + { + "code": 400, + "message": "请至少选择一条作业记录" + }, + { + "code": 400, + "message": "单次最多删除 200 条作业记录" }, { "code": 500, @@ -38770,9 +39341,163 @@ } ], "notes": [ - "删除为写操作,记录操作日志(不在免日志清单)。", + "删除为写操作,记录操作日志(不在免日志清单),operationCode=STOCK_CHECK_DELETE_RECORD、文案「批量删除盘点作业记录 N 条」(N=deleted_count,附跳过数量)。", + "批量口径(与 detailDelete 批量口径一致):查不到的记录 ID(记录不存在或不属于该任务/仓库)计入 skipped_ids 不报错;deleted_ids/skipped_ids 保持入参顺序;单值入参自动转数组。", "删除后仅重算盘点进度汇总(checked_items/diff_items/detail_status),主表状态不回退。", - "图片清理口径(图片独立维护,仿收货):删除作业记录后同步清理 wms_file_reference(business_type=stock_check_record + business_id=记录ID),失败仅告警(warn 日志)不影响主流程。代码依据:app/service/systems/stock_check.js#recordDelete。" + "图片清理口径(图片独立维护,仿收货):删除作业记录后同步清理 wms_file_reference(business_type=stock_check_record + business_id=记录ID),失败仅告警(warn 日志)不影响主流程。代码依据:app/service/systems/stock_check.js#recordDelete。", + "本接口由旧版单值删除升级为批量删除(2026-10-02):旧版入参 record_id(兼容 recordId)、响应 { record_id, deleted, total_items, checked_items, diff_items, detail_status }、记录不存在报 400「作业记录不存在或不属于该盘点任务」;新版入参 record_ids 数组(单次上限 200)、响应 { deleted_count, deleted_ids, skipped_ids, total_items, checked_items, diff_items, detail_status }、查不到计入 skipped_ids 不报错(旧版 record_id/deleted 响应字段与「作业记录不存在」错误文案不再返回)。", + "响应统一 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)。" + ] + }, + { + "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 操作日志。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "盘点任务ID" + }, + { + "name": "location_id", + "type": "number", + "required": true, + "source": "body", + "description": "库位ID(wms_location_space.id)" + }, + { + "name": "locationId", + "type": "number", + "required": false, + "source": "body", + "description": "库位ID(驼峰别名,兼容写法;location_id 优先)" + } + ], + "response": [ + { + "name": "flag", + "type": "string", + "required": true, + "description": "请求结果标记:success=成功 / failure=失败" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息:成功为 ok;失败为具体错误文案" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内;失败时 data=null)", + "children": [ + { + "name": "detail_id", + "type": "number", + "required": true, + "description": "该库位范围明细ID(wms_stock_check_detail.id)" + }, + { + "name": "location_id", + "type": "number", + "required": true, + "description": "库位ID(与入参一致,wms_location_space.id)" + }, + { + "name": "deleted_count", + "type": "number", + "required": true, + "description": "删除的作业记录条数(该库位范围明细下全部作业记录,含空库位标记)" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "明细总行数" + }, + { + "name": "checked_items", + "type": "number", + "required": true, + "description": "重算后的已盘行数(存在作业记录的明细数)" + }, + { + "name": "diff_items", + "type": "number", + "required": true, + "description": "重算后的差异行数(实盘合计与账面快照不一致的明细数;未知商品无账面,实盘>0 即盘盈、必然计入差异)" + }, + { + "name": "detail_status", + "type": "string", + "required": true, + "description": "重算后的明细盘点进度:none_checked/partial_checked/all_checked" + } + ] + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" + } + ], + "errors": [ + { + "code": 400, + "message": "盘点任务ID不能为空" + }, + { + "code": 400, + "message": "库位ID不能为空" + }, + { + "code": 400, + "message": "盘点任务不存在" + }, + { + "code": 400, + "message": "当前状态(非 approved/checking)不允许清除库位盘点信息" + }, + { + "code": 400, + "message": "仅库位盘点任务支持重盘清除库位" + }, + { + "code": 400, + "message": "该库位不在盘点任务范围内" + }, + { + "code": 500, + "message": "服务器内部错误" + } + ], + "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。", + "行为口径:清除该库位范围内明细(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)。", + "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.recheckClearLocation 一条(位于 stock.check.recordDelete 之后);分组内各 method notes 的「统一包装」描述由 21 个更新为 22 个、workData「权限口径」note 的 ALL_METHOD_NAMES 清单更新为 22 个(加入 recheckClearLocation);根版本 0.3.235 → 0.3.236、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);stock.check 分组由 21 条增至 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 + --env production,112.124.21.102:3306/wms)——import 当前 system.json → export 到临时文件往返校验,保持库与文件一致;stock.check 分组共 22 条 method 无损。" ] }, { @@ -38799,52 +39524,84 @@ ], "response": [ { - "name": "id", - "type": "number", - "required": true, - "description": "盘点任务ID" - }, - { - "name": "status", + "name": "flag", "type": "string", "required": true, - "description": "完成后的主表状态(completed)" + "description": "请求结果标记:success=成功 / failure=失败" }, { - "name": "total_items", + "name": "code", "type": "number", "required": true, - "description": "明细总行数" + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { - "name": "checked_items", - "type": "number", + "name": "message", + "type": "string", "required": true, - "description": "已盘行数(存在作业记录的明细数)" + "description": "提示信息:成功为 ok;失败为具体错误文案" }, { - "name": "unchecked_items", - "type": "number", + "name": "data", + "type": "object", "required": true, - "description": "未盘明细数(无作业记录的明细数;未盘商品明细按实盘 0 处理计为盘亏,未盘库位明细不计差异)" + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "盘点任务ID" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "完成后的主表状态(completed)" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "明细总行数" + }, + { + "name": "checked_items", + "type": "number", + "required": true, + "description": "已盘行数(存在作业记录的明细数)" + }, + { + "name": "unchecked_items", + "type": "number", + "required": true, + "description": "未盘明细数(无作业记录的明细数;未盘商品明细按实盘 0 处理计为盘亏,未盘库位明细不计差异)" + }, + { + "name": "diff_items", + "type": "number", + "required": true, + "description": "差异行数(商品行实盘合计与账面快照不一致、库位行任一商品实盘与账面不一致的明细数,未盘商品明细按实盘 0 计入)" + }, + { + "name": "profit_total", + "type": "number", + "required": true, + "description": "盘盈合计(商品行:作业记录数量合计大于账面快照的差异合计;库位行:按商品实盘大于 wms_storage 账面的差异合计)" + }, + { + "name": "loss_total", + "type": "number", + "required": true, + "description": "盘亏合计(商品行:实盘小于账面快照的差异绝对值合计,含未盘明细的账面快照数;库位行:按商品实盘小于 wms_storage 账面的差异绝对值合计)" + } + ] }, { - "name": "diff_items", + "name": "timestamp", "type": "number", "required": true, - "description": "差异行数(商品行实盘合计与账面快照不一致、库位行任一商品实盘与账面不一致的明细数,未盘商品明细按实盘 0 计入)" - }, - { - "name": "profit_total", - "type": "number", - "required": true, - "description": "盘盈合计(商品行:作业记录数量合计大于账面快照的差异合计;库位行:按商品实盘大于 wms_storage 账面的差异合计)" - }, - { - "name": "loss_total", - "type": "number", - "required": true, - "description": "盘亏合计(商品行:实盘小于账面快照的差异绝对值合计,含未盘明细的账面快照数;库位行:按商品实盘小于 wms_storage 账面的差异绝对值合计)" + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -38860,12 +39617,13 @@ "notes": [ "库位行账面口径:wms_storage 按 (space_id, stock_id) SUM(quantity),与 detail 接口的 stocks 账面一致。", "未盘库位明细行无法枚举商品(无作业记录即无商品维度),完成时不计差异、不计盘盈盘亏。", - "end_time 语义:完成盘点时主表写入 end_time(完成盘点的时间);接口响应不返回 end_time(响应结构不变:id/status/total_items/checked_items/unchecked_items/diff_items/profit_total/loss_total),主表时间字段请通过 detail/result/list 查看。" + "end_time 语义:完成盘点时主表写入 end_time(完成盘点的时间);接口响应不返回 end_time(响应结构不变:id/status/total_items/checked_items/unchecked_items/diff_items/profit_total/loss_total),主表时间字段请通过 detail/result/list 查看。", + "响应统一 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)。" ] }, { "method": "stock.check.submit", - "description": "完成盘点任务(提交审核):仅 created/rejected 状态允许;校验 total_items>0(无明细行时拒绝)后主表置 submitted(待审核)。", + "description": "完成盘点任务(提交审核):仅 created/rejected 状态允许;校验 total_items>0(无明细行时拒绝)后主表置 submitted(待审核);所有明细行(库位型 scope_type=location 与商品型 scope_type=goods)缺少库位(location_id 为空或 location_code 为空/空串)时不可提交(脏数据防御;商品任务按「商品+库位」拆行后商品行同样必须带库位,正常流程 addDetail/addLocationDetail 不会产生此类明细)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -38887,27 +39645,66 @@ ], "response": [ { - "name": "id", - "type": "number", - "required": true, - "description": "盘点任务ID" - }, - { - "name": "status", + "name": "flag", "type": "string", "required": true, - "description": "提交后的主表状态(submitted)" + "description": "请求结果标记:success=成功 / failure=失败" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息:成功为 ok;失败为具体错误文案" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "盘点任务ID" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "提交后的主表状态(submitted)" + } + ] + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" } ], "errors": [ { "code": 400, - "message": "盘点任务ID不能为空 / 盘点任务不存在 / 当前状态(非 created/rejected)不允许提交审核 / 盘点任务还没有明细行,无法提交审核" + "message": "盘点任务ID不能为空 / 盘点任务不存在 / 当前状态(非 created/rejected)不允许提交审核 / 盘点任务还没有明细行,无法提交审核 / 存在缺少库位的盘点明细,无法提交审核" }, { "code": 500, "message": "服务器内部错误" } + ], + "notes": [ + "响应统一 data 层封装(2026-10-02 起):成功 { flag:\"success\", code:1, message:\"ok\", data:<业务数据整体>, timestamp };失败 { flag:\"failure\", code:<业务错误码>, message:<错误文案>, data:null, timestamp }。本方法业务数据整体位于 data 内,data 内字段口径与改造前一致(原顶层业务字段全部移入 data.children)。代码依据:app/service/systemMethods/stock/check.js#_call(22 个方法共用统一包装)+ app/lib/api_response.js#toSuccess(识别标准载荷后顶层补充 timestamp)。", + "提交校验口径(本次扩展):全部明细行(库位型 scope_type=location 与商品型 scope_type=goods)缺少库位(location_id 为空或 location_code 为空/空串)时抛 400「存在缺少库位的盘点明细,无法提交审核」——校验不再限定 scope_type=location(商品任务按「商品+库位」拆行后商品行同样必须带库位),脏数据防御,正常流程 addDetail/addLocationDetail 写入的明细均带有效库位。代码依据:app/service/systems/stock_check.js#submit(StockCheckDetail.count where check_id+(location_id 为空或 location_code 为空/空串)>0 即拒绝,不再按 scope_type 过滤)。本次代码已改并测试通过 213/213、ESLint 0 错误。", + "影响面:前端无需改动——该校验拦截缺库位明细(含商品拆行后缺库位的历史脏数据),正常盘点流程不受影响;原有校验顺序不变(任务ID 为空→任务不存在→状态非 created/rejected→无明细行→缺库位明细)。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.addDetail:description/params/response/notes 补商品拆行口径(拆多行、无库存库位 invalid、system_quantity=该库位账面、added=拆分行数);stock.check.detail:description/response.rows/notes 商品行 location_id/location_code 绑定库存库位;stock.check.submit:description/notes 缺库位校验改为覆盖全部明细行;stock.check.patternCreate:description/notes 补 goods 定式按库存库位拆行;stock.check.addLocationDetail:notes 幂等索引口径同步 uk_check_location 唯一约束放宽为普通索引 idx_check_location);根版本 0.3.237 → 0.3.238、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 17 条 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 无损。" ] }, { @@ -38934,16 +39731,48 @@ ], "response": [ { - "name": "id", - "type": "number", - "required": true, - "description": "盘点任务ID" - }, - { - "name": "status", + "name": "flag", "type": "string", "required": true, - "description": "取消后的主表状态(cancelled)" + "description": "请求结果标记:success=成功 / failure=失败" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息:成功为 ok;失败为具体错误文案" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "盘点任务ID" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "取消后的主表状态(cancelled)" + } + ] + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -38955,6 +39784,9 @@ "code": 500, "message": "服务器内部错误" } + ], + "notes": [ + "响应统一 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)。" ] }, { @@ -38995,16 +39827,48 @@ ], "response": [ { - "name": "id", - "type": "number", - "required": true, - "description": "盘点任务ID" - }, - { - "name": "status", + "name": "flag", "type": "string", "required": true, - "description": "审核后的主表状态:approved(通过)/ rejected(驳回)" + "description": "请求结果标记:success=成功 / failure=失败" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息:成功为 ok;失败为具体错误文案" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "盘点任务ID" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "审核后的主表状态:approved(通过)/ rejected(驳回)" + } + ] + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -39016,6 +39880,9 @@ "code": 500, "message": "服务器内部错误" } + ], + "notes": [ + "响应统一 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)。" ] }, { @@ -39042,34 +39909,66 @@ ], "response": [ { - "name": "total", + "name": "flag", + "type": "string", + "required": true, + "description": "请求结果标记:success=成功 / failure=失败" + }, + { + "name": "code", "type": "number", "required": true, - "description": "入参去重后的任务ID数量" + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { - "name": "deleted_count", + "name": "message", + "type": "string", + "required": true, + "description": "提示信息:成功为 ok;失败为具体错误文案" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "total", + "type": "number", + "required": true, + "description": "入参去重后的任务ID数量" + }, + { + "name": "deleted_count", + "type": "number", + "required": true, + "description": "实际删除的任务数量(仅作废任务)" + }, + { + "name": "skipped_count", + "type": "number", + "required": true, + "description": "跳过的任务数量(非作废状态或查不到的任务)" + }, + { + "name": "deleted_ids", + "type": "array", + "required": true, + "description": "已删除的任务ID列表(保持入参顺序)" + }, + { + "name": "skipped_ids", + "type": "array", + "required": true, + "description": "跳过的任务ID列表(保持入参顺序)" + } + ] + }, + { + "name": "timestamp", "type": "number", "required": true, - "description": "实际删除的任务数量(仅作废任务)" - }, - { - "name": "skipped_count", - "type": "number", - "required": true, - "description": "跳过的任务数量(非作废状态或查不到的任务)" - }, - { - "name": "deleted_ids", - "type": "array", - "required": true, - "description": "已删除的任务ID列表(保持入参顺序)" - }, - { - "name": "skipped_ids", - "type": "array", - "required": true, - "description": "跳过的任务ID列表(保持入参顺序)" + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -39085,12 +39984,13 @@ "notes": [ "仅作废(status=cancelled)任务执行删除;其他状态及仓库内查不到的任务跳过(计入 skipped_ids,保持入参顺序),不视为业务错误。", "级联删除在事务内执行,顺序为:作业记录(StockCheckRecord)→ 明细(StockCheckDetail)→ 主表(StockCheck)。", - "写操作:随 ALL_METHOD_NAMES(16 个 method)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权,需登录(isNeedLogin=true);不在免日志清单(_noNeedLog),保留操作日志。" + "写操作:随 ALL_METHOD_NAMES(16 个 method)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权,需登录(isNeedLogin=true);不在免日志清单(_noNeedLog),保留操作日志。", + "响应统一 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)。" ] }, { "method": "stock.check.export", - "description": "提交盘点任务导出任务(异步):Excel 分两个 Sheet 生成——Sheet1「盘点单」一行一个盘点任务(盘点单号/盘点名称/盘点范围/盘点方式/盘点状态/盘点进度/货主ID/创建人/明细行数/已盘行数/差异行数/开始时间/结束时间/备注;主表移除 check_date 后已移除「盘点日期」列,保留开始/结束时间列);Sheet2「盘点明细」一行一条实际盘点记录(作业记录 wms_stock_check_record,列:盘点单号/商品编码/商品名称/库位编码(空库位输出为空)/实盘数量/盘点人/盘点时间;未知商品(stock_id 为空)商品编码列显示扫描条码(barcode)、商品名称列显示上报名称快照(item_name),已知商品快照从 wms_stock_warehouse 补齐),未盘的任务范围行不再导出;ExcelJS 流式生成后上传 COS;进度通过 Redis 缓存(key stock_check_export_task_*,TTL 1800 秒)追踪,立即返回任务ID;单次最多 50 个盘点任务。", + "description": "提交盘点任务导出任务(异步):Excel 分两个 Sheet 生成——Sheet1「盘点单」一行一个盘点任务(盘点单号/盘点名称/盘点范围/盘点方式/盘点状态/盘点进度/货主ID/创建人/明细行数/已盘行数/差异行数/开始时间/结束时间/备注;主表移除 check_date 后已移除「盘点日期」列,保留开始/结束时间列);Sheet2「盘点明细」一行一条实际盘点记录(作业记录 wms_stock_check_record,列:盘点单号/商品编码/商品名称/库位编码(空库位输出为空)/实盘数量/盘点人/盘点时间;未知商品(stock_id 为空)商品编码列显示扫描条码(barcode)、商品名称列显示上报名称快照(item_name),已知商品快照从 wms_stock_warehouse 补齐;空库位记录(is_empty=1)商品编码列输出「(空库位)」、商品名称为空、实盘数量输出 0),未盘的任务范围行不再导出;ExcelJS 流式生成后上传 COS;进度通过 Redis 缓存(key stock_check_export_task_*,TTL 1800 秒)追踪,立即返回任务ID;单次最多 50 个盘点任务。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -39119,58 +40019,90 @@ ], "response": [ { - "name": "task_id", + "name": "flag", "type": "string", "required": true, - "description": "导出任务ID(格式 stock_check_export_{warehouseId}_{时间戳}_{随机串})" + "description": "请求结果标记:success=成功 / failure=失败" }, { - "name": "status", - "type": "string", - "required": true, - "description": "任务状态:submitted/running/success/failed/not_found" - }, - { - "name": "progress", + "name": "code", "type": "number", "required": true, - "description": "进度百分比(0-100)" - }, - { - "name": "current_count", - "type": "number", - "required": true, - "description": "当前已处理明细行数(Sheet2 已写入的作业记录行数)" - }, - { - "name": "total_count", - "type": "number", - "required": true, - "description": "Sheet2 盘点明细总行数(作业记录总数,导出前即确定)" + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, - "description": "任务提示信息" + "description": "提示信息:成功为 ok;失败为具体错误文案" }, { - "name": "result", + "name": "data", "type": "object", - "required": false, - "description": "任务成功时的结果对象(含 filename/fileKey/url/cdnUrl/cosUrl)" - }, - { - "name": "error", - "type": "string", "required": true, - "description": "失败时的错误信息(可选)" + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "task_id", + "type": "string", + "required": true, + "description": "导出任务ID(格式 stock_check_export_{warehouseId}_{时间戳}_{随机串})" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "任务状态:submitted/running/success/failed/not_found" + }, + { + "name": "progress", + "type": "number", + "required": true, + "description": "进度百分比(0-100)" + }, + { + "name": "current_count", + "type": "number", + "required": true, + "description": "当前已处理明细行数(Sheet2 已写入的作业记录行数)" + }, + { + "name": "total_count", + "type": "number", + "required": true, + "description": "Sheet2 盘点明细总行数(作业记录总数,导出前即确定)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "任务提示信息" + }, + { + "name": "result", + "type": "object", + "required": false, + "description": "任务成功时的结果对象(含 filename/fileKey/url/cdnUrl/cosUrl)" + }, + { + "name": "error", + "type": "string", + "required": true, + "description": "失败时的错误信息(可选)" + }, + { + "name": "update_time", + "type": "number", + "required": true, + "description": "最近一次状态更新时间戳(毫秒)" + } + ] }, { - "name": "update_time", + "name": "timestamp", "type": "number", "required": true, - "description": "最近一次状态更新时间戳(毫秒)" + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -39192,7 +40124,11 @@ "异步执行:查询任务与作业记录(wms_stock_check_record,不按任务范围行展开)→ 商品快照从 wms_stock_warehouse 补齐(item_code/item_name)→ ExcelJS 流式写入(Sheet1「盘点单」一行一个盘点任务;Sheet2「盘点明细」一行一条实际盘点记录,列:盘点单号/商品编码/商品名称/库位编码(空库位输出为空)/实盘数量/盘点人/盘点时间,未盘的任务范围行不导出)→ COS 上传。", "进度缓存 Redis key stock_check_export_task_{taskId},TTL 1800 秒;totalCount=作业记录总数(导出前即确定),进度按已写入明细行数/总数计算(每 200 行汇报一次)。", "Sheet1「盘点单」一行一个盘点任务,列:盘点单号/盘点名称/盘点范围/盘点方式/盘点状态/盘点进度/货主ID/创建人/明细行数/已盘行数/差异行数/开始时间/结束时间/备注(主表移除 check_date 后不再导出「盘点日期」列,保留开始/结束时间列);Sheet2「盘点明细」由『按任务范围行展开(含未盘空行)』调整为『一行一条实际盘点记录(作业记录)』,未盘的任务范围行不再导出。", - "未知商品导出口径:stock_id 为空的记录商品编码列输出扫描条码(barcode,空则留空)、商品名称列输出上报名称快照(item_name 或 barcode 兜底);已知商品维持 wms_stock_warehouse 商品快照(item_code/item_name)。代码依据:app/service/systems/stock_check.js#exportStockChecks/#_generateAndUploadStockCheckExcel。" + "未知商品导出口径:stock_id 为空的记录商品编码列输出扫描条码(barcode,空则留空)、商品名称列输出上报名称快照(item_name 或 barcode 兜底);已知商品维持 wms_stock_warehouse 商品快照(item_code/item_name)。代码依据:app/service/systems/stock_check.js#exportStockChecks/#_generateAndUploadStockCheckExcel。", + "响应统一 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)。", + "空库位标记导出口径(本次新增):Sheet2「盘点明细」空库位记录(is_empty=1)商品编码列输出『(空库位)』、商品名称列为空、实盘数量输出 0(row.is_empty ? '(空库位)' : (row.item_code || '')、row.is_empty ? '' : (row.item_name || '')、row.is_empty ? 0 : (Number(row.quantity) || 0))。代码依据:app/service/systems/stock_check.js#_generateAndUploadStockCheckExcel。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 5 条 method(stock.check.report:params 新增 is_empty 入参、errors 400 补「仅库位盘点明细支持空库位标记」、description/response/notes 补充空库位语义与互斥及汇总口径;stock.check.workData:description/response.rows 的 location 行新增 is_empty 字段说明;stock.check.result:description/response.rows 库位行新增 is_empty 与空标记盘亏口径;stock.check.recordList:response.rows 记录全字段说明新增 is_empty;stock.check.export:description/notes 补 Sheet2 空库位行输出口径);根版本 0.3.233 → 0.3.234、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);其余 15 条 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 无损。" ] }, { @@ -39226,64 +40162,96 @@ ], "response": [ { - "name": "task_id", + "name": "flag", "type": "string", "required": true, - "description": "任务ID(未传任务ID时为空字符串)" + "description": "请求结果标记:success=成功 / failure=失败" }, { - "name": "status", - "type": "string", - "required": true, - "description": "任务状态:submitted/running/success/failed/not_found" - }, - { - "name": "progress", + "name": "code", "type": "number", "required": true, - "description": "进度百分比(0-100)" - }, - { - "name": "current_count", - "type": "number", - "required": true, - "description": "当前已处理明细数" - }, - { - "name": "total_count", - "type": "number", - "required": true, - "description": "明细总行数" + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { "name": "message", "type": "string", "required": true, - "description": "任务提示信息" + "description": "提示信息:成功为 ok;失败为具体错误文案" }, { - "name": "result", + "name": "data", "type": "object", - "required": false, - "description": "任务成功时的结果对象(含 filename/fileKey/url/cdnUrl/cosUrl)" - }, - { - "name": "error", - "type": "string", "required": true, - "description": "失败时的错误信息(可选)" + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "task_id", + "type": "string", + "required": true, + "description": "任务ID(未传任务ID时为空字符串)" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "任务状态:submitted/running/success/failed/not_found" + }, + { + "name": "progress", + "type": "number", + "required": true, + "description": "进度百分比(0-100)" + }, + { + "name": "current_count", + "type": "number", + "required": true, + "description": "当前已处理明细数" + }, + { + "name": "total_count", + "type": "number", + "required": true, + "description": "明细总行数" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "任务提示信息" + }, + { + "name": "result", + "type": "object", + "required": false, + "description": "任务成功时的结果对象(含 filename/fileKey/url/cdnUrl/cosUrl)" + }, + { + "name": "error", + "type": "string", + "required": true, + "description": "失败时的错误信息(可选)" + }, + { + "name": "download_url", + "type": "string", + "required": true, + "description": "任务完成后可直接下载的文件地址(从 result 兜底提取,未完成或未找到时为空字符串)" + }, + { + "name": "update_time", + "type": "number", + "required": true, + "description": "最近一次状态更新时间戳(毫秒)" + } + ] }, { - "name": "download_url", - "type": "string", - "required": true, - "description": "任务完成后可直接下载的文件地址(从 result 兜底提取,未完成或未找到时为空字符串)" - }, - { - "name": "update_time", + "name": "timestamp", "type": "number", "required": true, - "description": "最近一次状态更新时间戳(毫秒)" + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -39294,7 +40262,8 @@ ], "notes": [ "任务不存在为正常响应(status=not_found),非业务错误。", - "进度缓存 Redis key stock_check_export_task_{taskId},TTL 1800 秒。" + "进度缓存 Redis key stock_check_export_task_{taskId},TTL 1800 秒。", + "响应统一 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)。" ] }, { @@ -39313,42 +40282,74 @@ "params": [], "response": [ { - "name": "patterns", - "type": "array", + "name": "flag", + "type": "string", "required": true, - "description": "盘点定式列表(共 5 条:空库位/错发/临期/静态/预警),每条含 id/name/description/type", + "description": "请求结果标记:success=成功 / failure=失败" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息:成功为 ok;失败为具体错误文案" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", "children": [ { - "name": "id", - "type": "string", + "name": "patterns", + "type": "array", "required": true, - "description": "定式唯一标识(patternCreate 的 pattern_id 入参):empty_location=空库位盘点 / mis_shipment=错发盘点 / expiring=临期盘点 / static=静态盘点 / warning=预警盘点" + "description": "盘点定式列表(共 5 条:空库位/错发/临期/静态/预警),每条含 id/name/description/type", + "children": [ + { + "name": "id", + "type": "string", + "required": true, + "description": "定式唯一标识(patternCreate 的 pattern_id 入参):empty_location=空库位盘点 / mis_shipment=错发盘点 / expiring=临期盘点 / static=静态盘点 / warning=预警盘点" + }, + { + "name": "name", + "type": "string", + "required": true, + "description": "定式名称(创建任务时作为默认标题)" + }, + { + "name": "description", + "type": "string", + "required": true, + "description": "定式描述(含对象收集口径,详见 notes)" + }, + { + "name": "type", + "type": "string", + "required": true, + "description": "对应盘点任务 type:location=按库位(仅 empty_location)/ goods=按商品(其余 4 个)" + } + ] }, { - "name": "name", - "type": "string", + "name": "total", + "type": "number", "required": true, - "description": "定式名称(创建任务时作为默认标题)" - }, - { - "name": "description", - "type": "string", - "required": true, - "description": "定式描述(含对象收集口径,详见 notes)" - }, - { - "name": "type", - "type": "string", - "required": true, - "description": "对应盘点任务 type:location=按库位(仅 empty_location)/ goods=按商品(其余 4 个)" + "description": "定式总数(当前为 5)" } ] }, { - "name": "total", + "name": "timestamp", "type": "number", "required": true, - "description": "定式总数(当前为 5)" + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -39360,12 +40361,13 @@ "notes": [ "5 个定式口径(与代码注释一致):① empty_location 空库位盘点(type=location):wms_location_space 中启用且未删除、在 wms_storage 不存在任何 quantity>0 库存记录的账面空库位;② mis_shipment 错发盘点(type=goods):登记过错发工单(wms_after_sale type=order 且 sub_type=mis_shipment,凡登记过即纳入、排除 closed/cancelled 状态)关联订单的商品按 stock_id 去重;③ expiring 临期盘点(type=goods):开启保质期管理(wms_stock_warehouse.is_shelf_life_mgmt=Y)且存在临期库存(最早到期日 <= 当前时间+该商品 remaining_threshold_days 天,阈值 <=0 时按已到期)的商品维度去重;④ static 静态盘点(type=goods):最后一次 INBOUND/OUTBOUND 流水(wms_stock_transaction)距今超过仓库配置 stock_static_hours 小时(默认 168,无流水按 wms_stock_warehouse.create_at)且未进入 wms_stock_static_check_task 的商品;⑤ warning 预警盘点(type=goods):库存 quantity < 仓库配置 stock_warning_quantity 的商品(要求仓库配置 stock_warning_enabled=true 才可执行)。", "查询类接口:免 API 权限(isNeedAuth=false)、免仓库有效期鉴权、必须登录(isNeedLogin=true);在免日志清单(_noNeedLog)中,不记录操作日志。", - "返回字段仅对外 4 个(id/name/description/type),不含内部执行函数。" + "返回字段仅对外 4 个(id/name/description/type),不含内部执行函数。", + "响应统一 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)。" ] }, { "method": "stock.check.patternCreate", - "description": "按定式快速创建盘点任务:入参 pattern_id(兼容 patternId 驼峰写法,pattern_id 优先)+ 可选 title/remark;warehouse_id 与创建人由服务端从登录上下文(ctx.user.store_id / ctx.user.id / employees_name)自动注入,前端无需传递;盘点方式由定式范围类型固定:库位类定式(empty_location,type=location)一律盲盘 blind、商品类定式(type=goods,其余 4 个)一律明盘 open;盘点方式与盘点时间均无需前端传入(主表已无 check_date,start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间),由盘点作业流程自动回填);按定式收集盘点对象(goods 型得到 stock_ids、location 型得到库位列表),无符合条件对象报 400;创建后主表状态直接 submitted(进入待审核)、detail_status=none_checked、total_items 按明细重算;static 定式在任务创建成功后把命中的 stock_id 批量写入 wms_stock_static_check_task(失败不影响主流程);写操作,记录操作日志。", + "description": "按定式快速创建盘点任务:入参 pattern_id(兼容 patternId 驼峰写法,pattern_id 优先)+ 可选 title/remark;warehouse_id 与创建人由服务端从登录上下文(ctx.user.store_id / ctx.user.id / employees_name)自动注入,前端无需传递;盘点方式由定式范围类型固定:库位类定式(empty_location,type=location)一律盲盘 blind、商品类定式(type=goods,其余 4 个)一律明盘 open;盘点方式与盘点时间均无需前端传入(主表已无 check_date,start_time=盘点开始时间(第一个盘点明细写入的时间)、end_time=盘点结束时间(完成盘点的时间),由盘点作业流程自动回填);按定式收集盘点对象(goods 型得到 stock_ids、location 型得到库位列表),goods 型明细同样按「商品+库位」拆行(商品任务必须按库位盘点,同 addDetail 商品路径),无符合条件对象报 400;创建后主表状态直接 submitted(进入待审核)、detail_status=none_checked、total_items 按明细重算;static 定式在任务创建成功后把命中的 stock_id 批量写入 wms_stock_static_check_task(失败不影响主流程);写操作,记录操作日志。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -39408,22 +40410,54 @@ ], "response": [ { - "name": "check", - "type": "object", - "required": true, - "description": "创建后的盘点任务信息(_formatCheckRow 口径:id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at,无 check_date);status 直接为 submitted(待审核),mode 由定式范围类型固定(location→blind、goods→open),start_time/end_time 创建时为空(分别由首个盘点明细写入与完成盘点回填)" - }, - { - "name": "total_items", - "type": "number", - "required": true, - "description": "明细总行数(创建明细后按 wms_stock_check_detail 重算)" - }, - { - "name": "pattern_id", + "name": "flag", "type": "string", "required": true, - "description": "本次创建使用的定式ID" + "description": "请求结果标记:success=成功 / failure=失败" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示信息:成功为 ok;失败为具体错误文案" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "check", + "type": "object", + "required": true, + "description": "创建后的盘点任务信息(_formatCheckRow 口径:id/check_no/title/type/mode/store_id/status/detail_status/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at,无 check_date);status 直接为 submitted(待审核),mode 由定式范围类型固定(location→blind、goods→open),start_time/end_time 创建时为空(分别由首个盘点明细写入与完成盘点回填)" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "明细总行数(创建明细后按 wms_stock_check_detail 重算)" + }, + { + "name": "pattern_id", + "type": "string", + "required": true, + "description": "本次创建使用的定式ID" + } + ] + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -39442,7 +40476,9 @@ "状态口径:创建后主表 status 直接 submitted(进入待审核)、detail_status=none_checked,无需再调 stock.check.submit;store_id/scope_snapshot 为空,type 取定式类型(location/goods),mode 由定式范围类型固定(location→blind、goods→open),start_time/end_time 创建时为空。", "static 定式静态记录表口径:收集阶段排除 wms_stock_static_check_task 已有记录(未删除)的 stock_id(已进入静态已盘点商品);任务创建成功后把本次命中的 stock_id 批量写入该表(task_time=创建时间),写入失败仅记告警日志、不影响主流程。", "权限口径:免 API 权限(isNeedAuth=false)、免仓库有效期鉴权、必须登录(isNeedLogin=true);patternCreate 为写操作,不在免日志清单(_noNeedLog)中,记录操作日志(patternList 为查询类,免日志)。", - "单号生成:check_no=PD+YYYYMMDD+6 位序号(全局递增不按仓库隔离),并发下撞 uk_check_no 唯一键自动重取重试(最多 5 次)。" + "单号生成:check_no=PD+YYYYMMDD+6 位序号(全局递增不按仓库隔离),并发下撞 uk_check_no 唯一键自动重取重试(最多 5 次)。", + "goods 定式拆行口径(本次改造):商品类定式(mis_shipment/expiring/static/warning,type=goods)收集到 stock_ids 后走 _addGoodsDetailRows 同款逻辑——按商品在仓库的启用库存库位(wms_storage is_enabled=1,按 space_id 分组 SUM)拆行,每个「商品+库位」一条 scope_type=goods 明细行(location_id/location_code 绑定库存库位、system_quantity=该库位库存 SUM);无启用库存库位的商品不产生明细行,total_items 按拆分行重算。代码依据:app/service/systems/stock_check.js#patternCreate(pattern.type==='goods' 调 _addGoodsDetailRows)。", + "响应统一 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)。" ] }, { @@ -39476,28 +40512,60 @@ ], "response": [ { - "name": "added", - "type": "number", + "name": "flag", + "type": "string", "required": true, - "description": "本次新增明细数" + "description": "请求结果标记:success=成功 / failure=失败" }, { - "name": "skipped", + "name": "code", "type": "number", "required": true, - "description": "已存在被跳过(幂等)的盘点项数" + "description": "业务码:成功为 1;失败为具体业务错误码(如 400/500)" }, { - "name": "invalid_location_ids", - "type": "array", + "name": "message", + "type": "string", "required": true, - "description": "无效库位ID列表(按 wms_location_space.id 直查当前仓库不存在)" + "description": "提示信息:成功为 ok;失败为具体错误文案" }, { - "name": "total_items", + "name": "data", + "type": "object", + "required": true, + "description": "业务数据对象(统一 data 层封装:本方法全部业务数据整体位于 data 内,data 内字段口径与改造前完全一致;失败时 data=null)", + "children": [ + { + "name": "added", + "type": "number", + "required": true, + "description": "本次新增明细数" + }, + { + "name": "skipped", + "type": "number", + "required": true, + "description": "已存在被跳过(幂等)的盘点项数" + }, + { + "name": "invalid_location_ids", + "type": "array", + "required": true, + "description": "无效库位ID列表(按 wms_location_space.id 直查当前仓库不存在)" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "重算后的明细总行数" + } + ] + }, + { + "name": "timestamp", "type": "number", "required": true, - "description": "重算后的明细总行数" + "description": "服务器时间戳(秒)" } ], "errors": [ @@ -39513,7 +40581,8 @@ "notes": [ "兼容入口:保留旧接口名与返回结构({ added, skipped, invalid_location_ids, total_items }),内部转调 addDetail 库位ID直查路径(stockIds/locations 置空、传 locationIds),返回结构过滤 invalid_locations/invalid_stock_ids 保持原口径。", "转发前校验:任务ID不能为空、库位ID不能为空(请至少选择一个库位)、单次上限 200(超过报『单次最多添加 200 个库位』);任务不存在/状态不允许/商品任务不可添加库位明细由 addDetail 透传同款错误。", - "ID 直查:按 wms_location_space.id+warehouse_id 直查校验(仓库隔离),查不到的 ID 记入 invalid_location_ids(不报错);幂等按 check_id+location_code(uk_check_location 唯一索引),已存在同库位明细跳过。" + "ID 直查:按 wms_location_space.id+warehouse_id 直查校验(仓库隔离),查不到的 ID 记入 invalid_location_ids(不报错);幂等按 check_id+location_code(原 uk_check_location 唯一约束已放宽为普通索引 idx_check_location,幂等由应用层查重保证),已存在同库位明细跳过。", + "响应统一 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)。" ] } ] @@ -39573,10 +40642,10 @@ }, { "name": "where.mainWaybillCode", - "type": "string", + "type": "string|string[]", "required": false, "source": "body.where", - "description": "主单号(精确匹配)。先通过主单号定位 order_id,再返回该订单下所有运单(主+子)。与 waybillCode 互斥,同时传入时 mainWaybillCode 优先" + "description": "主单号筛选:字符串时为精确匹配(通过主单号定位 order_id,返回该订单下所有运单(主+子));字符串数组时按 Op.in 精确匹配多个主单号,返回这些主单对应订单下的全部运单(元素自动 trim 并过滤空值;全部不存在时返回空列表;空数组或全空值时不加该筛选条件)。与 waybillCode 同时传入时按 AND 叠加,不做互斥优先级处理" }, { "name": "where.orderId", @@ -39974,6 +41043,9 @@ "code": "500", "message": "服务器内部错误:运单列表查询失败" } + ], + "notes": [ + "mainWaybillCode 支持字符串数组(2026-10-04):数组按 Op.in 精确匹配多个主单号,返回这些主单对应订单下的全部运单(主+子);单值保持原「先定位 order_id 再查」行为不变,且 order_id 条件保持标量。" ] }, { @@ -40394,10 +41466,10 @@ }, { "name": "where.mainWaybillCode", - "type": "string", + "type": "string|string[]", "required": false, "source": "body.where", - "description": "主单号(精确匹配)" + "description": "主单号筛选:字符串/字符串数组均可(数组按 Op.in 精确匹配多个主单号),先定位 order_id 再导出对应订单下全部运单(元素自动 trim 并过滤空值,空数组或全空值时不加该筛选条件)" }, { "name": "where.ids", @@ -40619,6 +41691,9 @@ "code": "500", "message": "服务器内部错误:运单导出任务创建失败" } + ], + "notes": [ + "mainWaybillCode 支持字符串数组(2026-10-04):数组按 Op.in 精确匹配多个主单号,返回这些主单对应订单下的全部运单(主+子);单值保持原「先定位 order_id 再查」行为不变,且 order_id 条件保持标量。" ] }, { diff --git a/test/app/service/systems/waybill.warehouse.mainWaybillCode.in.test.js b/test/app/service/systems/waybill.warehouse.mainWaybillCode.in.test.js new file mode 100644 index 0000000..4b8a3d6 --- /dev/null +++ b/test/app/service/systems/waybill.warehouse.mainWaybillCode.in.test.js @@ -0,0 +1,341 @@ +'use strict'; + +const assert = require('node:assert/strict'); +const Sequelize = require('sequelize'); +const { Op } = Sequelize; +const WaybillService = require('../../../../app/service/systems/waybill'); +const { matchesWhere } = require('../../../support/where_matcher'); + +const TEST_WAREHOUSE_ID = 100000; +const TEST_STORE_ID = 1000000; + +/** + * 运单 fixture(主单号数组查询场景): + * - order 101:主单 SF9001-MAIN + 子单 SF9001-1 / SF9001-2 + * - order 102:主单 SF9002-MAIN + 子单 SF9002-1 + * - order 103:主单 SF9003-MAIN(无子单) + * - id 7 为其他仓库同主单号运单(验证仓库隔离) + * @return {Array} 运单行。 + */ +function buildExpressRows() { + const base = [ + { id: 1, order_id: 101, waybill_code: 'SF9001-MAIN', business_key: 1, warehouse_id: TEST_WAREHOUSE_ID }, + { id: 2, order_id: 101, waybill_code: 'SF9001-1', business_key: 2, warehouse_id: TEST_WAREHOUSE_ID }, + { id: 3, order_id: 101, waybill_code: 'SF9001-2', business_key: 3, warehouse_id: TEST_WAREHOUSE_ID }, + { id: 4, order_id: 102, waybill_code: 'SF9002-MAIN', business_key: 1, warehouse_id: TEST_WAREHOUSE_ID }, + { id: 5, order_id: 102, waybill_code: 'SF9002-1', business_key: 2, warehouse_id: TEST_WAREHOUSE_ID }, + { id: 6, order_id: 103, waybill_code: 'SF9003-MAIN', business_key: 1, warehouse_id: TEST_WAREHOUSE_ID }, + { id: 7, order_id: 104, waybill_code: 'SF9001-MAIN', business_key: 1, warehouse_id: 999999 }, + ]; + + return base.map((item, index) => ({ + ...item, + store_id: TEST_STORE_ID, + status: 1, + delivery_order_code: `DO-${item.order_id}`, + source_order_codes: `SO-${item.order_id}`, + logistics_code: 'SF', + logistics_name: '顺丰', + logistics_interface_id: 1, + logistics_interface_name: 'SF-IF', + platform_code: 'PDD', + is_back: 'N', + is_intercept: 'N', + is_galaxy_receive: 'N', + weighing_weight: 0, + package_material_id: 0, + package_material_name_snapshot: '', + create_at: `2026-08-0${(index % 9) + 1} 03:20:00`, + })); +} + +/** + * 创建 waybill list/export 服务测试环境(mock 模型按真实 where 语义过滤 fixture 行)。 + * @return {{service: WaybillService, calls: Object, captured: Object}} 测试上下文。 + */ +function createWaybillHarness() { + const expressRows = buildExpressRows(); + + const calls = { + listFindAndCountAllWhere: null, + listFindAllWheres: [], + exportCountWhere: null, + exportFindAllWheres: [], + }; + + const ctx = { + app: { + Sequelize, + config: {}, + formatDate(value) { + return value === null || value === undefined ? null : String(value); + }, + }, + user: { store_id: TEST_WAREHOUSE_ID }, + logger: { info() {}, warn() {}, error() {} }, + service: {}, + model: { + OrderExpress: { + async findAndCountAll(query = {}) { + calls.listFindAndCountAllWhere = query.where || null; + const filtered = expressRows.filter(item => matchesWhere(item, query.where || {})); + const offset = Number(query.offset) || 0; + const limit = Number(query.limit) || filtered.length; + return { count: filtered.length, rows: filtered.slice(offset, offset + limit) }; + }, + async findAll(query = {}) { + const where = query.where || {}; + if (where.waybill_code && where.waybill_code[Op.in]) { + calls.listFindAllWheres.push(where); + } else if (where.order_id && where.order_id[Op.in]) { + calls.exportFindAllWheres.push(where); + calls.listFindAllWheres.push(where); + } else { + calls.listFindAllWheres.push(where); + } + return expressRows.filter(item => matchesWhere(item, where)); + }, + async count(query = {}) { + calls.exportCountWhere = query.where || null; + return expressRows.filter(item => matchesWhere(item, query.where || {})).length; + }, + }, + ExpressPrintRecord: { + async findAll() { + return []; + }, + }, + StoreWarehouse: { + async findAll() { + return []; + }, + }, + }, + }; + + const service = new WaybillService(ctx); + + // export 的建表/上传副作用与筛选逻辑无关,打桩到文件生成边界, + // 通过 captured.filePayload 断言筛选后的行集,确保测的是真实 where 构建链路。 + const captured = { filePayload: null }; + service.buildWaybillExportFile = async payload => { + captured.filePayload = payload; + return { + current_count: payload.totalCount, + total_count: payload.totalCount, + url: 'mock-url', + }; + }; + + return { service, calls, captured }; +} + +/** + * 提取 list 结果中的运单号集合(排序后)。 + * @param {Object} result list 返回结果。 + * @return {Array} 排序后的运单号列表。 + */ +function resultWaybillCodes(result) { + return (result && result.list ? result.list : []).map(item => String(item.waybill_code)).sort(); +} + +/** + * 取主单号查询发出的 where(含 waybill_code Op.in 的那次)。 + * @param {Array} wheres 捕获的 where 列表。 + * @return {Object|null} 主单号查询 where。 + */ +function mainCodeLookupWhere(wheres) { + return wheres.find(where => where.waybill_code && where.waybill_code[Op.in]) || null; +} + +/** + * 从 where 中提取 order_id 条件(标量或 Op.in 数组)。 + * @param {Object|null} where Sequelize where 条件。 + * @return {number|Array|null} order_id 条件。 + */ +function orderIdCondition(where) { + if (!where) return null; + const value = where.order_id; + if (value === undefined || value === null) return null; + if (typeof value === 'object' && value[Op.in]) return value[Op.in]; + return value; +} + +describe('test/app/service/systems/waybill.warehouse.mainWaybillCode.in.test.js', () => { + describe('waybill.warehouse.list where.mainWaybillCode 数组支持', () => { + it('数组两个主单号:返回两个订单下全部运单(主+子),order_id 使用 Op.in', async () => { + const { service, calls } = createWaybillHarness(); + + const result = await service.list({ + where: { mainWaybillCode: [ 'SF9001-MAIN', 'SF9002-MAIN' ] }, + pagination: { page: 1, pageSize: 20 }, + }); + + assert.deepEqual(orderIdCondition(calls.listFindAndCountAllWhere), [ 101, 102 ]); + assert.equal(result.pagination.total, 5); + assert.deepEqual(resultWaybillCodes(result), [ 'SF9001-1', 'SF9001-2', 'SF9001-MAIN', 'SF9002-1', 'SF9002-MAIN' ]); + }); + + it('数组内元素自动 trim 并过滤空值', async () => { + const { service, calls } = createWaybillHarness(); + + const result = await service.list({ + where: { mainWaybillCode: [ ' SF9001-MAIN ', '', null, undefined ] }, + pagination: { page: 1, pageSize: 20 }, + }); + + assert.equal(orderIdCondition(calls.listFindAndCountAllWhere), 101); + assert.deepEqual(resultWaybillCodes(result), [ 'SF9001-1', 'SF9001-2', 'SF9001-MAIN' ]); + }); + + it('存在+不存在混合:仅返回存在主单号对应运单,不抛错', async () => { + const { service, calls } = createWaybillHarness(); + + const result = await service.list({ + where: { mainWaybillCode: [ 'SF9001-MAIN', 'SF-NOT-EXIST' ] }, + pagination: { page: 1, pageSize: 20 }, + }); + + assert.equal(orderIdCondition(calls.listFindAndCountAllWhere), 101); + assert.equal(result.pagination.total, 3); + assert.deepEqual(resultWaybillCodes(result), [ 'SF9001-1', 'SF9001-2', 'SF9001-MAIN' ]); + }); + + it('全部不存在:直接返回空结果,不发起主查询', async () => { + const { service, calls } = createWaybillHarness(); + + const result = await service.list({ + where: { mainWaybillCode: [ 'SF-NOT-EXIST-A', 'SF-NOT-EXIST-B' ] }, + pagination: { page: 1, pageSize: 20 }, + }); + + assert.equal(calls.listFindAndCountAllWhere, null, '主单号均不存在时不应发起主查询'); + assert.deepEqual(result.list, []); + assert.equal(result.pagination.total, 0); + }); + + it('重复主单号自动去重,不产生重复 order_id', async () => { + const { service, calls } = createWaybillHarness(); + + const result = await service.list({ + where: { mainWaybillCode: [ 'SF9001-MAIN', 'SF9001-MAIN', 'SF9002-MAIN' ] }, + pagination: { page: 1, pageSize: 20 }, + }); + + assert.deepEqual(orderIdCondition(calls.listFindAndCountAllWhere), [ 101, 102 ]); + assert.equal(result.pagination.total, 5); + }); + + it('单元素数组:与单值等价,order_id 保持标量(向后兼容)', async () => { + const { service, calls } = createWaybillHarness(); + + await service.list({ + where: { mainWaybillCode: [ 'SF9001-MAIN' ] }, + pagination: { page: 1, pageSize: 20 }, + }); + + assert.equal(orderIdCondition(calls.listFindAndCountAllWhere), 101); + }); + + it('字符串单值:行为不变(order_id 标量)', async () => { + const { service, calls } = createWaybillHarness(); + + const result = await service.list({ + where: { mainWaybillCode: 'SF9002-MAIN' }, + pagination: { page: 1, pageSize: 20 }, + }); + + assert.equal(orderIdCondition(calls.listFindAndCountAllWhere), 102); + assert.deepEqual(resultWaybillCodes(result), [ 'SF9002-1', 'SF9002-MAIN' ]); + }); + + it('标准 where 格式 {operator:"in", value:[...]}:经 normalizeWhereParams 后同样支持', async () => { + const { service, calls } = createWaybillHarness(); + + const result = await service.list({ + where: { mainWaybillCode: { operator: 'in', value: [ 'SF9001-MAIN', 'SF9003-MAIN' ] } }, + pagination: { page: 1, pageSize: 20 }, + }); + + assert.deepEqual(orderIdCondition(calls.listFindAndCountAllWhere), [ 101, 103 ]); + assert.equal(result.pagination.total, 4); + }); + + it('空数组 / 全空值数组:不加主单号筛选,返回本仓全部运单', async () => { + const { service, calls } = createWaybillHarness(); + + const emptyResult = await service.list({ + where: { mainWaybillCode: [] }, + pagination: { page: 1, pageSize: 20 }, + }); + assert.equal(orderIdCondition(calls.listFindAndCountAllWhere), null, '空数组不应添加 order_id 条件'); + assert.equal(emptyResult.pagination.total, 6, '仓库内全部 6 条'); + + const blankResult = await service.list({ + where: { mainWaybillCode: [ ' ', null ] }, + pagination: { page: 1, pageSize: 20 }, + }); + assert.equal(blankResult.pagination.total, 6); + }); + + it('仓库隔离:其他仓库同主单号运单不会被带出', async () => { + const { service, calls } = createWaybillHarness(); + + const result = await service.list({ + where: { mainWaybillCode: [ 'SF9001-MAIN' ] }, + pagination: { page: 1, pageSize: 20 }, + }); + + const lookup = mainCodeLookupWhere(calls.listFindAllWheres); + assert.equal(lookup.warehouse_id, TEST_WAREHOUSE_ID); + assert.equal(lookup.business_key, 1); + assert.equal(orderIdCondition(calls.listFindAndCountAllWhere), 101, '不含其他仓库 order 104'); + assert.equal(result.pagination.total, 3); + }); + + it('与 waybillCode 数组共存:AND 叠加', async () => { + const { service, calls } = createWaybillHarness(); + + const result = await service.list({ + where: { + mainWaybillCode: [ 'SF9001-MAIN', 'SF9002-MAIN' ], + waybillCode: [ 'SF9002-1' ], + }, + pagination: { page: 1, pageSize: 20 }, + }); + + assert.deepEqual(orderIdCondition(calls.listFindAndCountAllWhere), [ 101, 102 ]); + assert.deepEqual(calls.listFindAndCountAllWhere.waybill_code[Op.in], [ 'SF9002-1' ]); + assert.deepEqual(resultWaybillCodes(result), [ 'SF9002-1' ]); + }); + }); + + describe('waybill.warehouse.export where.mainWaybillCode 数组支持(与 list 保持一致)', () => { + it('数组两个主单号:导出两个订单下全部运单', async () => { + const { service, calls, captured } = createWaybillHarness(); + + await service.export({ + where: { mainWaybillCode: [ 'SF9001-MAIN', 'SF9002-MAIN' ] }, + }); + + assert.deepEqual(orderIdCondition(calls.exportCountWhere), [ 101, 102 ]); + assert.equal(captured.filePayload.totalCount, 5); + assert.deepEqual( + captured.filePayload.list.map(item => item.waybill_code).sort(), + [ 'SF9001-1', 'SF9001-2', 'SF9001-MAIN', 'SF9002-1', 'SF9002-MAIN' ] + ); + }); + + it('全部不存在:导出空结果,不发起统计查询', async () => { + const { service, calls, captured } = createWaybillHarness(); + + const result = await service.export({ + where: { mainWaybillCode: [ 'SF-NOT-EXIST' ] }, + }); + + assert.equal(calls.exportCountWhere, null, '主单号不存在时不应发起统计查询'); + assert.equal(result.total_count, 0); + assert.equal(captured.filePayload, null); + }); + }); +});