diff --git a/AI_METHOD_ROUTING.md b/AI_METHOD_ROUTING.md index 02b978f..4e61944 100644 --- a/AI_METHOD_ROUTING.md +++ b/AI_METHOD_ROUTING.md @@ -183,12 +183,13 @@ rg "class .*Service|module.exports" app/service/qimenMethods - 绑定流程:设备调 `index.getWorkbenchBindCode` 拿 client_code + 绑定码(缓存 `workbench:bind:client:{clientCode}` / `workbench:bind:code:{code}`,TTL 120s)→ 管理员调 `workbench.bind`(code + 工作台ID)写入随机 64 位 token 并删除旧 `workbench:token:{旧token}` 缓存 → 设备侧长轮询(60s 超时,每秒轮询)拿到 token;超时/缓存失效时重新生成绑定码后才返回 - token 登录:`index.LoginWorkbenchByCode` 以 `wms_workbench.login_code` 换取 token(无匹配返回 code=403 业务失败;工作台无 token 时自动生成持久化);`workbench.getWorkbenchInfo` 以 token 获取工作台信息(缓存优先、查库兜底、无信息返回 code=403 业务失败) - 字段:`wms_workbench` 新增 `login_code`(前缀 wblc + 随机段共 64 位,全局唯一索引 uk_login_code)、`token`(随机 64 位,索引 idx_token);`workbench.create` 自动生成 login_code;`workbench.update` 不受理 login_code/token 传入;`workbench.list` 返回 login_code、不返回 token -- 成员副表:`wms_workbench_member`(工作台成员/用户登录,user_id 可空兼容非系统账号用户、user_name 名称快照、软删除);`workbench.bindMember` 免登录免鉴权(入参 userId 可空 + userName 姓名必填 + 工作台 token)新增成员行;`workbench.removeMember` 免登录免鉴权(入参行 ids + 工作台 token)按 token 解析工作台后仅软删除归属该工作台的成员行 +- 成员副表:`wms_workbench_member`(工作台成员/用户登录,user_id 可空兼容非系统账号用户、user_name 名称快照、软删除);`workbench.bindMember` 免登录免鉴权(入参 userId 可空 + userName 姓名必填 + 工作台 token)新增成员行;`workbench.removeMember` 免登录免鉴权(入参行 ids + 工作台 token)按 token 解析工作台后仅软删除归属该工作台的成员行,移除后该工作台已无任何成员时自动结束其所有未结束打包任务(wms_pack_task status<2 置 2 并写 end_time,同步回写订单打包状态与补确认打印状态、写完成操作日志、复位摄像头 OSD、失效 token 缓存,与 finishPack 语义一致,响应附 auto_finished_pack{finished,task_ids},2026-09-21 补充) - 401/403 口径:/system 网关不支持方法内设置 HTTP 状态码,按现有惯例返回 `flag=failure、code=XXX` 业务失败(与 stock/warehouse.js 同款);公共 token 校验方法 `resolveWorkbenchContext(token)`(app/service/systems/workbench.js):无 token 统一返回 code=401(消息「工作台 token 不能为空」,2026-09-06 由 400 调整)、token 无效/工作台不存在(含软删除)返回 403(保持原口径),解析成功后写入 ctx.workbenchToken/ctx.workbenchId/ctx.workbenchWarehouseId 供后续方法使用(仓库限定,禁止跨仓库);`workbench.getWorkbenchInfo`/`workbench.bindMember`/`workbench.removeMember` 均统一走该校验(无 token 返回 401,bindMember/removeMember token 优先校验) -- 打包/称重三接口(2026-09-06 新增):`workbench.packOrder`(打包上报,入参 token/delivery_order_code/wave_no/status/pack_time/wave_total_orders/items_count/items_total/users,响应 task_id/order_id/delivery_order_code/wave_no/isSandan/pack_mode/status,团购附 batch)、`workbench.finishPack`(打包完成,入参 token,响应 workbench_id/finished/task_id/order_id/end_time,无未结束任务 finished=false)、`workbench.sendWeight`(称重上报,入参 token/barcode/weight(单位克),散单响应 barcode/waybill_code/order_id/weighing_weight/items_weight/mode=single,团购波次响应另附 wave_id/wave_no/total_weight/order_count/mode=wave)均免登录/免权限/免鉴权,靠工作台 token 自校验;仓库与工作台均由服务端从 token 解析注入,body 传入 warehouse_id/workbench_id 一律忽略(禁止前端传值);三接口保留系统日志(systemInit 未声明免日志) -- 条码查单接口(2026-09-06 新增):`workbench.queryOrder`(条码查订单,入参 token/barcode,响应 barcode/waybill_code/isSandan/store_remark/express/order/items/source_table,散单 order 附 intercept_flag/pack_flag 0/1 标志、团购附 batch 波次总量信息;items 逐项合并 stock 详情含 need_recheck 是否需要复核(Y=需要 N=不需要(免验),2026-09-19 补充))免登录/免权限/免鉴权,靠工作台 token 自校验;仓库与工作台均由服务端从 token 解析注入,body 传入 warehouse_id/workbench_id 一律忽略(禁止前端传值);只读查询不涉及缓存失效;保留系统日志(systemInit 未声明免日志) -- 接口文档:`methods/system.json` 分组「工作台模块」(module=workbench)与「基础模块」(module=index),变更记录见 `methods/changes/system.json` 版本 `2026.09.03-workbench-login-code-token`、`2026.09.03-workbench-member-remove`、`2026.09.03-workbench-member-bind`、`2026.09.06-workbench-getWorkbenchInfo-members`、`2026.09.06-workbench-getWorkbenchInfo-current-packing`、`2026.09.06-workbench-getWorkbenchInfo-wave-items-total`、`2026.09.06-workbench-pack-order-finish-pack-send-weight`、`2026.09.06-workbench-queryOrder`、`2026.09.19-workbench-getWorkbenchInfo-order-items`、`2026.09.19-workbench-order-items-need-recheck`、`2026.09.19-workbench-getWorkbenchInfo-wave-items-summary` -- 当前打包信息:`workbench.getWorkbenchInfo` 响应 data 另含 `current_wave`(当前正在打包的团购波次,来自 wms_pack_task 最新一条 pack_mode=2 未结束任务,无则为空对象;含 order_count 波次订单数与 items_total 波次商品总件数,均按 current+dispatch 分表实时统计、15s 短缓存兜底)与 `current_orders`(未结束打包任务对应订单数组,逐单按 current→dispatch 分表补发货单号/order_type/store_id/items_count/items_total,另附任务表 item_quantity/sku_count/waybill_code,散单任务(pack_mode=1)附 items 商品明细数组(复用 _fetchOrderItemsDetail 公共方法,与 workbench.queryOrder 的 items 同源,含条码/图片/包装要求/need_recheck 是否需要复核),团购任务(pack_mode=2)items 为波次商品 SKU 聚合汇总(_fetchWaveItemsSummary,波次内全部未拦截订单按 SKU 聚合计划数量并合并 stock 详情,15s 短缓存兜底,元素另附 is_wave_summary=true),无则为空数组);打包信息随 `workbench:token:{token}` 缓存(TTL 300s)一并缓存,packOrder/finishPack 状态变更后主动失效缓存,查询异常降级为空对象/空数组(单笔商品明细异常仅 items 降级为空数组) +- 打包/称重三接口(2026-09-06 新增):`workbench.packOrder`(打包上报,推荐 key 模式:前端先扫码 `workbench.queryOrder` 拿 key(20 分钟有效),打包只传 token + key(除 token、key 外不再接收任何订单相关信息,body 其它字段一律忽略,防篡改;不传 key 时旧参数模式过渡兼容,后续版本移除),参数由后端从 Redis 缓存 workbench:packctx:{key} 拉取(含订单号/波次号/运单号),跨仓/跨台消费他人 key 返回 403、缺 key 或过期返回 400;响应 task_id/order_id/delivery_order_code/wave_no/isSandan/pack_mode/status,团购附 batch)、`workbench.finishPack`(打包完成,入参 token,响应 workbench_id/finished/task_id/order_id/end_time,无未结束任务 finished=false)、`workbench.sendWeight`(称重上报,入参 token/barcode/weight(单位克),散单响应 barcode/waybill_code/order_id/weighing_weight/items_weight/mode=single,团购波次响应另附 wave_id/wave_no/total_weight/order_count/mode=wave)均免登录/免权限/免鉴权,靠工作台 token 自校验;仓库与工作台均由服务端从 token 解析注入,body 传入 warehouse_id/workbench_id 一律忽略(禁止前端传值);三接口保留系统日志(systemInit 未声明免日志) +- 打包运单维度(2026-09-21 修复一单多号):`workbench.packOrder` 传运单号时按「订单+运单号」维度写入 wms_pack_task.waybill_code 并散单去重(同时清理同订单历史 waybill_code 为空的旧流水),主单号/子单号流水互不覆盖,未传保持订单维度(兼容旧设备端);团购为波次维度不使用运单号;打包人一律由服务端取该工作台绑定成员回填(wms_workbench_member,users 入参已移除,旧设备端传 users 被忽略,2026-09-21) +- 条码查单接口(2026-09-06 新增):`workbench.queryOrder`(条码查订单,入参 token/barcode,响应 barcode/waybill_code/isSandan/store_remark/express/order/items/source_table,散单 order 附 intercept_flag/pack_flag 0/1 标志、团购附 batch 波次总量信息;items 逐项合并 stock 详情含 need_recheck 是否需要复核(Y=需要 N=不需要(免验),2026-09-19 补充);pack_flag 按运单维度判定(该运单号已有打包流水 wms_pack_task.waybill_code 命中或历史订单级流水 waybill_code 为空兜底时为 1,否则 0,主单号/子单号互不影响,流水查询异常降级订单级 pack_status 判定,2026-09-21 调整);查询成功时响应另附 key(打包上下文 key,wpck 前缀 + 随机段,Redis 缓存 workbench:packctx:{key} TTL 20 分钟,内容含订单号/波次号/运单号/归属仓库与工作台,供 workbench.packOrder 消费防篡改,2026-09-21 新增))免登录/免权限/免鉴权,靠工作台 token 自校验;仓库与工作台均由服务端从 token 解析注入,body 传入 warehouse_id/workbench_id 一律忽略(禁止前端传值);只读查询不涉及缓存失效;保留系统日志(systemInit 未声明免日志) +- 接口文档:`methods/system.json` 分组「工作台模块」(module=workbench)与「基础模块」(module=index),变更记录见 `methods/changes/system.json` 版本 `2026.09.03-workbench-login-code-token`、`2026.09.03-workbench-member-remove`、`2026.09.03-workbench-member-bind`、`2026.09.06-workbench-getWorkbenchInfo-members`、`2026.09.06-workbench-getWorkbenchInfo-current-packing`、`2026.09.06-workbench-getWorkbenchInfo-wave-items-total`、`2026.09.06-workbench-pack-order-finish-pack-send-weight`、`2026.09.06-workbench-queryOrder`、`2026.09.19-workbench-getWorkbenchInfo-order-items`、`2026.09.19-workbench-order-items-need-recheck`、`2026.09.19-workbench-getWorkbenchInfo-wave-items-summary`、`2026.09.21-workbench.packOrder-waybill-dimension`、`2026.09.21-workbench.removeMember-auto-finish-pack`、`2026.09.21-workbench.packOrder-remove-users-param`、`2026.09.21-workbench.packOrder-key-mode`、`2026.09.21-workbench.packOrder-key-only`、`2026.09.21-workbench.packOrder-legacy-compat`、`2026.09.21-workbench.packOrder-key-forward-fix`、`2026.09.21-workbench.getWorkbenchInfo-order-fields` +- 当前打包信息:`workbench.getWorkbenchInfo` 响应 data 另含 `current_wave`(当前正在打包的团购波次,来自 wms_pack_task 最新一条 pack_mode=2 未结束任务,无则为空对象;含 order_count 波次订单数与 items_total 波次商品总件数,均按 current+dispatch 分表实时统计、15s 短缓存兜底)与 `current_orders`(未结束打包任务对应订单数组,逐单按 current→dispatch 分表补发货单号/order_type/store_id/items_count/items_total,另附任务表 item_quantity/sku_count/waybill_code,散单任务(pack_mode=1)附 items 商品明细数组(复用 _fetchOrderItemsDetail 公共方法,与 workbench.queryOrder 的 items 同源,含条码/图片/包装要求/need_recheck 是否需要复核),另补货主备注 store_remark 与运单信息 express(物流公司/称重重量/包材名称,与 queryOrder 口径一致,2026-09-21 补充),团购任务(pack_mode=2)items 为波次商品 SKU 聚合汇总(_fetchWaveItemsSummary,波次内全部未拦截订单按 SKU 聚合计划数量并合并 stock 详情,15s 短缓存兜底,元素另附 is_wave_summary=true),无则为空数组);打包信息随 `workbench:token:{token}` 缓存(TTL 300s)一并缓存,packOrder/finishPack 状态变更后主动失效缓存,查询异常降级为空对象/空数组(单笔商品明细异常仅 items 降级为空数组) - 迁移:`database/migrations/20260903100000-add-login-code-token-to-wms-workbench.js`(幂等 up/down,已在开发库执行;生产库待发布时按标准流程执行) ## 5.4 index.queryUserByToken(ye4s token 查询用户)能力速查 @@ -304,7 +305,7 @@ rg "class .*Service|module.exports" app/service/qimenMethods - 临时清单输出:temp/tmp-service-method-inventory.md -自动生成时间: 2026-09-19T19:08:16.992Z +自动生成时间: 2026-09-20T17:48:36.671Z 扫描范围: app/service/**/*.js 文件数: 216 @@ -441,8 +442,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - list, reviewOrder - app/service/systemMethods/order/storageAllocation.js (0) - -- app/service/systemMethods/order/wave.js (235) - - buildBatchAllocateExpressTraceId, buildOrderOperationLogRows, batchCreateOrderOperationLogs, buildMachineStructureToken, parseMachineStructureToken, getOrderItemPart, getDefaultWaveQuantity, getMinGroupOrderFetchQuantity, getGroupWavePrefix, getSingleFetchByIdsWavePrefix, getWarehouseSubjectConfig, getWarehouseSubjectConfigValue, normalizeFetchStructureRequests, generateWaveId, getCurrentDatePart, VALUES, getNextWaveNoSequence, buildWaveNo, id, getWaveCreator, extractInsertId, extractLastInsertId, isDuplicateEntryError, resolveWaveScopeByWaveMeta, createWaveBatchReady, buildFetchWhere, fetchSingleStructure, normalizeBoolean, normalizePositiveInteger, normalizeRequiredPositiveInteger, normalizeIdsInput, normalizePagination, normalizeWaveStatusList, normalizeBatchListStorageAssignmentStatusFilter, normalizeBatchListExpressAssignmentStatusFilter, normalizeBatchListPrintAssignmentStatusFilter, normalizeBatchListReviewAssignmentStatusFilter, normalizeBatchListSyncAssignmentStatusFilter, getBatchListAssignmentFilterSchema, normalizeBatchListAssignmentStatusFilterByType, normalizeBatchListAssignmentStatusFilter, getModelTableSqlName, buildBatchListStorageAssignmentFilterClause, buildBatchListExpressAssignmentFilterClause, buildBatchListPrintAssignmentFilterClause, buildBatchListReviewAssignmentFilterClause, buildBatchListSyncAssignmentFilterClause, buildBatchListAssignmentStatusFilterClauseByType, buildBatchListAssignmentStatusFilterClause, isEmptyBatchListWhereValue, resolveBatchListFieldCondition, buildBatchListFieldConditionSql, normalizeBatchListDistinguishExpressValue, normalizeBatchListStoreIdCondition, buildBatchListWhereClause, normalizeWavePickTaskListPagination, normalizeWavePickTaskListRequest, buildWavePickTaskListWhereClause, resolveAssignmentStatus, normalizeSkuText, normalizeShopName, parseItemSnapshot, normalizeOrderItemRow, mergeOrderItemDetails, buildItemSummary, buildOrderItemSnapshot, buildItemSnapshotKey, orderMatchesIncludeSku, buildCoarseGroupKey, buildStatusSummary, buildGroupKey, groupOrderFetchList, singleOrderFetchList, waveStrategyList, getWaveStrategyNextFetchOrderCountMap, getWaveStrategyDebugFetchOrderListMap, previewWaveStrategyNextFetchOrderCount, getWaveStrategyMatchedOrderCountFilteredMap, getWaveStrategyMatchedOrderCountTotal, waveStrategyCreate, waveStrategyUpdate, bumpWaveStrategyVersionAndInvalidateCache, getWaveStrategyModel, normalizeWaveStrategyId, normalizeWaveStrategyUpsertPayload, normalizeWaveStrategyWavePrefix, resolveWaveStrategyFetchWavePrefix, patchWaveStrategyIntegerField, validateWaveStrategyAllowedOwners, validateWaveStrategyAllowedExpresses, getWaveStrategyAvailableOwnerSet, getWaveStrategyAvailableExpressSet, applyWaveStrategyMaxSameStructureConstraint, normalizeWaveStrategyFallbackOrderListWhere, resolveWaveStrategyFallbackTrackingNo, resolveWaveStrategyFallbackStoreName, resolveWaveStrategyFallbackSysLogisticsName, buildWaveStrategyFallbackOrderListItem, waveStrategyFallbackOrderList, resolveWaveBatchOwnerStoreNameMap, batchList, wavePickTaskList, batchCancel, batchCancelTaskProgress, batchAllocateExpress, batchAllocateExpressTaskProgress, batchAllocateStorage, batchAllocateStorageTaskProgress, submitWaveStrategyQuickScanForWarehouse, waveStrategyQuickScan, waveStrategyQuickScanTaskProgress, buildWaveStrategyQuickScanOrderWhere, getWaveStrategyQuickScanStrategyRows, getWaveStrategyQuickScanMatchModel, syncWaveStrategyQuickScanMatchedStrategies, cleanupWaveStrategyQuickScanMatchedStrategies, cleanupWaveStrategyQuickScanMatchedStrategiesByOrderIds, enqueueWaveStrategyQuickScanPostOrderChange, executeWaveStrategyQuickScan, runWaveStrategyQuickScanTask, batchUpdateWaveStrategyQuickScanOrders, generateWaveStrategyQuickScanTaskId, normalizeWaveStrategyQuickScanTaskId, getWaveStrategyQuickScanTaskCacheKey, setWaveStrategyQuickScanTaskProgress, getWaveStrategyQuickScanTaskProgress, getWaveStrategyQuickScanWarehouseLockCacheKey, setWaveStrategyQuickScanWarehouseLock, getWaveStrategyQuickScanWarehouseLock, clearWaveStrategyQuickScanWarehouseLock, normalizeWaveStrategyQuickScanVersion, normalizeWaveStrategyQuickScanList, normalizeWaveStrategyQuickScanNumberOrNull, normalizeWaveStrategyQuickScanBoolean, normalizeWaveStrategyQuickScanStringList, getWaveStrategyQuickScanStructureKey, getWaveStrategyQuickScanExpressKey, filterCandidateOrdersByRequireSameExpress, isWaveStrategyQuickScanOrderMatched, getWaveStrategyQuickScanMatchedStrategyIds, isWaveStrategyQuickScanOrderMatchedSingleStrategy, isWaveStrategyQuickScanValueInRange, resolveGroupCandidateOrderIdsForSingleFetch, singleFetchByIds, batchRemoveOrders, resortWaveIndex, batchRemoveExceptionOrders, batchRemoveExceptionOrdersTaskProgress, generateBatchCancelTaskId, normalizeBatchCancelTaskId, generateBatchRemoveExceptionOrdersTaskId, normalizeBatchRemoveExceptionOrdersTaskId, normalizeBatchRemoveExceptionOrdersWaveIds, getBatchRemoveExceptionOrdersTaskCacheKey, setBatchRemoveExceptionOrdersTaskProgress, getBatchRemoveExceptionOrdersTaskProgress, isExceptionRemovableOrder, runBatchRemoveExceptionOrdersTask, normalizeBatchCancelWaveIds, getBatchCancelTaskCacheKey, setBatchCancelTaskProgress, getBatchCancelTaskProgress, runBatchCancelTask, generateBatchAllocateExpressTaskId, normalizeBatchAllocateExpressTaskId, normalizeBatchAllocateExpressWaveIds, getBatchAllocateExpressTaskCacheKey, setBatchAllocateExpressTaskProgress, getBatchAllocateExpressTaskProgress, generateBatchAllocateStorageTaskId, normalizeBatchAllocateStorageTaskId, normalizeBatchAllocateStorageWaveIds, normalizeBatchAllocateStorageTaskCount, buildBatchAllocateStorageRunningProgressPayload, normalizeBatchAllocateStorageOrderIds, getBatchAllocateStorageTaskCacheKey, getBatchAllocateStorageWarehouseLockKey, tryAcquireBatchAllocateStorageWarehouseLock, releaseBatchAllocateStorageWarehouseLock, setBatchAllocateStorageTaskProgress, getBatchAllocateStorageTaskProgress, isMissingBusinessKeyColumnError, runBatchAllocateExpressTask, runBatchAllocateStorageTask, batchAutoGrouping, batchFinishAutoGrouping, generateFetchTaskId, normalizeFetchTaskId, getFetchTaskCacheKey, setFetchTaskProgress, getFetchTaskProgress, fetchTaskProgress, runFetchTask, submitFetchTask, groupFetch, singleFetch, resolveWaveStrategyFetchPickMode, buildWaveStrategyFetchBoxAssignments, prepareWaveStrategyFetchPlan, in, ensureNoActiveWavePickTaskForOperator, normalizeWaveStrategyFetchCreatedBefore, buildWaveStrategyFetchTodayStart, getWaveStrategyFetchCandidateOrders, groupWaveStrategyFetchCandidateOrdersByStructure, buildWaveStrategyFetchOrderSkuMap, selectWaveStrategyFetchOrdersBySkuLimit, createWaveBatchByOrderIdsInTransaction, mergeWaveStrategyFirstPoolSameStructureOrders, autoPopulateWaveStrategyFetchSelections, executeWaveStrategyDirectFetch, createWavePickTaskFromPlan, buildTaskCreatePayload, buildTaskWaveRows, buildTaskOrderRows, buildTaskSkuRows, buildTaskBoxRows, bindPickCartForTask, initTaskCheckpointAndLogs, ensurePickCartAvailable, generateWavePickTaskNo, createWavePickTaskWithRetry, isTaskNoDuplicateError, bulkInsertRows, parseWaveStrategyExistingTaskInfo, waveStrategyFetchPda, cancelWavePickTasksInternal, wavePickTaskCancel, wavePickTaskCancelSelf, waveStrategyFetchAdmin, deleteOrderWaveIndexByOrderIds, deleteOrderWaveIndexByWaveIds, rebuildOrderWaveIndex, replaceOrderWaveIndexByWaveIds, fetch +- app/service/systemMethods/order/wave.js (245) + - buildBatchAllocateExpressTraceId, buildOrderOperationLogRows, batchCreateOrderOperationLogs, buildMachineStructureToken, parseMachineStructureToken, getOrderItemPart, getDefaultWaveQuantity, getMinGroupOrderFetchQuantity, getGroupWavePrefix, getSingleFetchByIdsWavePrefix, getWarehouseSubjectConfig, getWarehouseSubjectConfigValue, normalizeFetchStructureRequests, generateWaveId, getCurrentDatePart, VALUES, getNextWaveNoSequence, buildWaveNo, id, getWaveCreator, extractInsertId, extractLastInsertId, isDuplicateEntryError, resolveWaveScopeByWaveMeta, createWaveBatchReady, buildFetchWhere, fetchSingleStructure, normalizeBoolean, normalizePositiveInteger, normalizeRequiredPositiveInteger, normalizeIdsInput, normalizePagination, normalizeWaveStatusList, normalizeBatchListStorageAssignmentStatusFilter, normalizeBatchListExpressAssignmentStatusFilter, normalizeBatchListPrintAssignmentStatusFilter, normalizeBatchListConfirmPrintAssignmentStatusFilter, normalizeBatchListClaimAssignmentStatusFilter, normalizeBatchListReviewAssignmentStatusFilter, normalizeBatchListSyncAssignmentStatusFilter, getBatchListAssignmentFilterSchema, normalizeBatchListAssignmentStatusFilterByType, normalizeBatchListAssignmentStatusFilter, getModelTableSqlName, buildBatchListStorageAssignmentFilterClause, buildBatchListExpressAssignmentFilterClause, buildBatchListPrintAssignmentFilterClause, buildBatchListConfirmPrintAssignmentFilterClause, buildBatchListClaimAssignmentFilterClause, buildBatchListReviewAssignmentFilterClause, buildBatchListSyncAssignmentFilterClause, buildBatchListAssignmentStatusFilterClauseByType, buildBatchListAssignmentStatusFilterClause, isEmptyBatchListWhereValue, resolveBatchListFieldCondition, buildBatchListFieldConditionSql, normalizeBatchListDistinguishExpressValue, normalizeBatchListStoreIdCondition, buildBatchListWhereClause, normalizeWavePickTaskListPagination, normalizeWavePickTaskListRequest, buildWavePickTaskListWhereClause, resolveAssignmentStatus, normalizeSkuText, normalizeShopName, parseItemSnapshot, normalizeOrderItemRow, mergeOrderItemDetails, buildItemSummary, buildOrderItemSnapshot, buildItemSnapshotKey, orderMatchesIncludeSku, buildCoarseGroupKey, buildStatusSummary, buildGroupKey, groupOrderFetchList, singleOrderFetchList, waveStrategyList, getWaveStrategyNextFetchOrderCountMap, getWaveStrategyDebugFetchOrderListMap, previewWaveStrategyNextFetchOrderCount, getWaveStrategyMatchedOrderCountFilteredMap, getWaveStrategyMatchedOrderCountTotal, waveStrategyCreate, waveStrategyUpdate, bumpWaveStrategyVersionAndInvalidateCache, getWaveStrategyModel, normalizeWaveStrategyId, normalizeWaveStrategyUpsertPayload, normalizeWaveStrategyWavePrefix, resolveWaveStrategyFetchWavePrefix, patchWaveStrategyIntegerField, validateWaveStrategyAllowedOwners, validateWaveStrategyAllowedExpresses, getWaveStrategyAvailableOwnerSet, getWaveStrategyAvailableExpressSet, applyWaveStrategyMaxSameStructureConstraint, normalizeWaveStrategyFallbackOrderListWhere, resolveWaveStrategyFallbackTrackingNo, resolveWaveStrategyFallbackStoreName, resolveWaveStrategyFallbackSysLogisticsName, buildWaveStrategyFallbackOrderListItem, waveStrategyFallbackOrderList, resolveWaveBatchOwnerStoreNameMap, batchList, getConfirmPrintUnclaimedVersionKey, bumpConfirmPrintUnclaimedWaveVersion, getConfirmPrintUnclaimedWaveVersion, queryConfirmPrintUnclaimedWaveCount, confirmPrintScan, confirmPrintUnclaimedWaveCount, wavePickTaskList, batchCancel, batchCancelTaskProgress, batchAllocateExpress, batchAllocateExpressTaskProgress, batchAllocateStorage, batchAllocateStorageTaskProgress, submitWaveStrategyQuickScanForWarehouse, waveStrategyQuickScan, waveStrategyQuickScanTaskProgress, buildWaveStrategyQuickScanOrderWhere, getWaveStrategyQuickScanStrategyRows, getWaveStrategyQuickScanMatchModel, syncWaveStrategyQuickScanMatchedStrategies, cleanupWaveStrategyQuickScanMatchedStrategies, cleanupWaveStrategyQuickScanMatchedStrategiesByOrderIds, enqueueWaveStrategyQuickScanPostOrderChange, executeWaveStrategyQuickScan, runWaveStrategyQuickScanTask, batchUpdateWaveStrategyQuickScanOrders, generateWaveStrategyQuickScanTaskId, normalizeWaveStrategyQuickScanTaskId, getWaveStrategyQuickScanTaskCacheKey, setWaveStrategyQuickScanTaskProgress, getWaveStrategyQuickScanTaskProgress, getWaveStrategyQuickScanWarehouseLockCacheKey, setWaveStrategyQuickScanWarehouseLock, getWaveStrategyQuickScanWarehouseLock, clearWaveStrategyQuickScanWarehouseLock, normalizeWaveStrategyQuickScanVersion, normalizeWaveStrategyQuickScanList, normalizeWaveStrategyQuickScanNumberOrNull, normalizeWaveStrategyQuickScanBoolean, normalizeWaveStrategyQuickScanStringList, getWaveStrategyQuickScanStructureKey, getWaveStrategyQuickScanExpressKey, filterCandidateOrdersByRequireSameExpress, isWaveStrategyQuickScanOrderMatched, getWaveStrategyQuickScanMatchedStrategyIds, isWaveStrategyQuickScanOrderMatchedSingleStrategy, isWaveStrategyQuickScanValueInRange, resolveGroupCandidateOrderIdsForSingleFetch, singleFetchByIds, batchRemoveOrders, resortWaveIndex, batchRemoveExceptionOrders, batchRemoveExceptionOrdersTaskProgress, generateBatchCancelTaskId, normalizeBatchCancelTaskId, generateBatchRemoveExceptionOrdersTaskId, normalizeBatchRemoveExceptionOrdersTaskId, normalizeBatchRemoveExceptionOrdersWaveIds, getBatchRemoveExceptionOrdersTaskCacheKey, setBatchRemoveExceptionOrdersTaskProgress, getBatchRemoveExceptionOrdersTaskProgress, isExceptionRemovableOrder, runBatchRemoveExceptionOrdersTask, normalizeBatchCancelWaveIds, getBatchCancelTaskCacheKey, setBatchCancelTaskProgress, getBatchCancelTaskProgress, runBatchCancelTask, generateBatchAllocateExpressTaskId, normalizeBatchAllocateExpressTaskId, normalizeBatchAllocateExpressWaveIds, getBatchAllocateExpressTaskCacheKey, setBatchAllocateExpressTaskProgress, getBatchAllocateExpressTaskProgress, generateBatchAllocateStorageTaskId, normalizeBatchAllocateStorageTaskId, normalizeBatchAllocateStorageWaveIds, normalizeBatchAllocateStorageTaskCount, buildBatchAllocateStorageRunningProgressPayload, normalizeBatchAllocateStorageOrderIds, getBatchAllocateStorageTaskCacheKey, getBatchAllocateStorageWarehouseLockKey, tryAcquireBatchAllocateStorageWarehouseLock, releaseBatchAllocateStorageWarehouseLock, setBatchAllocateStorageTaskProgress, getBatchAllocateStorageTaskProgress, isMissingBusinessKeyColumnError, runBatchAllocateExpressTask, runBatchAllocateStorageTask, batchAutoGrouping, batchFinishAutoGrouping, generateFetchTaskId, normalizeFetchTaskId, getFetchTaskCacheKey, setFetchTaskProgress, getFetchTaskProgress, fetchTaskProgress, runFetchTask, submitFetchTask, groupFetch, singleFetch, resolveWaveStrategyFetchPickMode, buildWaveStrategyFetchBoxAssignments, prepareWaveStrategyFetchPlan, in, ensureNoActiveWavePickTaskForOperator, normalizeWaveStrategyFetchCreatedBefore, buildWaveStrategyFetchTodayStart, getWaveStrategyFetchCandidateOrders, groupWaveStrategyFetchCandidateOrdersByStructure, buildWaveStrategyFetchOrderSkuMap, selectWaveStrategyFetchOrdersBySkuLimit, createWaveBatchByOrderIdsInTransaction, mergeWaveStrategyFirstPoolSameStructureOrders, autoPopulateWaveStrategyFetchSelections, executeWaveStrategyDirectFetch, createWavePickTaskFromPlan, buildTaskCreatePayload, buildTaskWaveRows, buildTaskOrderRows, buildTaskSkuRows, buildTaskBoxRows, bindPickCartForTask, initTaskCheckpointAndLogs, ensurePickCartAvailable, generateWavePickTaskNo, createWavePickTaskWithRetry, isTaskNoDuplicateError, bulkInsertRows, parseWaveStrategyExistingTaskInfo, waveStrategyFetchPda, cancelWavePickTasksInternal, wavePickTaskCancel, wavePickTaskCancelSelf, waveStrategyFetchAdmin, deleteOrderWaveIndexByOrderIds, deleteOrderWaveIndexByWaveIds, rebuildOrderWaveIndex, replaceOrderWaveIndexByWaveIds, fetch - app/service/systemMethods/outbound.js (1) - autoOutbound - app/service/systemMethods/pick.js (14) @@ -731,8 +732,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - closeFinishedWaves, normalizeConfirmIntervalMs, readEmptyConfirmState, writeEmptyConfirmState - app/service/systems/waybill.js (5) - toOrder, list, detail, export, buildWaybillExportFile -- app/service/systems/workbench.js (69) - - list, detail, create, update, delete, bindCamera, business, _countWaveOrders, _countWaveOrdersCached, SUM, _sumWaveItemsTotal, _sumWaveItemsTotalCached, _getWaveOrderIds, Set, _buildPackChangeSummary, _writePackOperationLog, _updateOrderPackStatus, _packOrder, resolvePackTaskEndTime, _finishPack, _resetPackOsd, _sendWeight, _writeWeighOpLog, _aggregateWaveItems, _fetchWaveItemsSummary, _fetchOrderItemsDetail, _queryOrder, getWorkbenchBindClientCacheKey, getWorkbenchBindCodeCacheKey, getWorkbenchTokenCacheKey, generateRandomChars, generateWorkbenchToken, generateWorkbenchLoginCode, normalizeWorkbenchBindCode, generateUniqueWorkbenchLoginCode, createUniqueWorkbenchClientCode, createUniqueWorkbenchBindCode, buildWorkbenchBindState, getWorkbenchBindRemainingSeconds, setWorkbenchBindState, createWorkbenchBindSession, refreshWorkbenchBindCode, formatWorkbenchBindData, waitForWorkbenchBindComplete, getWorkbenchBindCode, formatWorkbenchTokenInfo, listWorkbenchMembers, listCurrentPackTasks, buildCurrentPackingInfo, invalidateWorkbenchTokenCacheByWorkbenchId, buildWorkbenchTokenInfo, bindWorkbench, getWorkbenchInfoByToken, _round2, _formatPackCountTime, buildWorkbenchPackCountTimeRange, getWorkbenchCountByToken, loginWorkbenchByCode, resetLoginCode, clearExpiredWorkbenchTokens, resolveWorkbenchContext, resolveWorkbenchByToken, packOrderByToken, finishPackByToken, sendWeightByToken, queryOrderByToken, normalizeWorkbenchMemberIds, removeWorkbenchMember, bindWorkbenchMember +- app/service/systems/workbench.js (73) + - list, detail, create, update, delete, bindCamera, business, _loadPackCtx, _countWaveOrders, _countWaveOrdersCached, SUM, _sumWaveItemsTotal, _sumWaveItemsTotalCached, _getWaveOrderIds, Set, _buildPackChangeSummary, _writePackOperationLog, _updateOrderPackStatus, _packOrder, resolvePackTaskEndTime, _finishPack, _resetPackOsd, _sendWeight, _writeWeighOpLog, _aggregateWaveItems, _fetchWaveItemsSummary, _fetchOrderItemsDetail, _queryOrder, generatePackCtxKey, getWorkbenchPackCtxCacheKey, getWorkbenchBindClientCacheKey, getWorkbenchBindCodeCacheKey, getWorkbenchTokenCacheKey, generateRandomChars, generateWorkbenchToken, generateWorkbenchLoginCode, normalizeWorkbenchBindCode, generateUniqueWorkbenchLoginCode, createUniqueWorkbenchClientCode, createUniqueWorkbenchBindCode, buildWorkbenchBindState, getWorkbenchBindRemainingSeconds, setWorkbenchBindState, createWorkbenchBindSession, refreshWorkbenchBindCode, formatWorkbenchBindData, waitForWorkbenchBindComplete, getWorkbenchBindCode, formatWorkbenchTokenInfo, listWorkbenchMembers, listCurrentPackTasks, buildCurrentPackingInfo, invalidateWorkbenchTokenCacheByWorkbenchId, buildWorkbenchTokenInfo, bindWorkbench, getWorkbenchInfoByToken, _round2, _formatPackCountTime, buildWorkbenchPackCountTimeRange, getWorkbenchCountByToken, loginWorkbenchByCode, resetLoginCode, clearExpiredWorkbenchTokens, resolveWorkbenchContext, resolveWorkbenchByToken, packOrderByToken, finishPackByToken, sendWeightByToken, queryOrderByToken, normalizeWorkbenchMemberIds, _finishAllPackTasksByMemberLogout, removeWorkbenchMember, bindWorkbenchMember - app/service/warehouse.js (7) - resolveWarehouseMethod, getWarehouseMethodService, dispatchWarehouseMethod, validateWarehouseParams, parseJsonBody, normalizeSignFields, processRequest - app/service/warehouseMethods/inbox.js (2) @@ -783,6 +784,12 @@ rg "class .*Service|module.exports" app/service/qimenMethods + + + + + + diff --git a/methods/changes/system.json b/methods/changes/system.json index 4537ca3..bb3fe78 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,130 @@ [ + { + "version": "2026.09.21-workbench.getWorkbenchInfo-order-fields", + "date": "2026-09-21", + "type": "updated", + "summary": "workbench.getWorkbenchInfo 的 current_orders 补齐货主备注(store_remark)与运单信息(express:物流公司/称重重量/包材名称),与 queryOrder 口径一致", + "methods": [ + "workbench.getWorkbenchInfo" + ], + "notes": [ + "背景:getWorkbenchInfo 返回的 current_orders 相比 queryOrder 缺货主备注与包材信息,前端无法填充。", + "散单任务(pack_mode=1)按 order_id(优先任务 waybill_code)补 wms_order_express 的 logistics_name/weighing_weight/package_material_name_snapshot 与 wms_store_warehouse.store_remask;团购任务为波次维度不适用(store_remark 空、express 为 null)。查询并行执行,异常降级不阻断主信息。", + "代码变更:app/service/systems/workbench.js#buildCurrentPackingInfo;回归测试 test/workbench_pack_waybill_dimension.test.cjs(24 用例)。" + ], + "module": "workbench" + }, + { + "version": "2026.09.21-workbench.packOrder-key-forward-fix", + "date": "2026-09-21", + "type": "updated", + "summary": "修复 workbench.packOrder method 层未透传 key 导致 key 模式不生效(请求带 key 仍报发货单号不能为空)", + "methods": [ + "workbench.packOrder" + ], + "notes": [ + "根因:app/service/systemMethods/workbench.js#packOrder 解构白名单未包含 key,packOrderByToken 收不到 key 回退旧参数模式,新客户端只传 token+key 时报「发货单号不能为空」。", + "修复:method 层透传 key;回归测试 test/workbench_pack_waybill_dimension.test.cjs 新增 method 层透传用例(22 用例)。" + ], + "module": "workbench" + }, + { + "version": "2026.09.21-workbench.packOrder-legacy-compat", + "date": "2026-09-21", + "type": "updated", + "summary": "workbench.packOrder 代码保留旧参数模式过渡兼容(不传 key 时直传参数),文档主推 token+key 新接口", + "methods": [ + "workbench.packOrder", + "workbench.business" + ], + "notes": [ + "设备端过渡方案:代码同时支持新 key 模式(优先)与旧参数模式(不传 key 时直传 delivery_order_code 等,后续版本移除),文档按 token+key 新接口展示。", + "代码变更:app/service/systems/workbench.js#packOrderByToken 与 #business(packOrder) 分支恢复旧参数回退;回归测试 test/workbench_pack_waybill_dimension.test.cjs(21 用例,含旧参数兼容)。" + ], + "module": "workbench" + }, + { + "version": "2026.09.21-workbench.packOrder-key-only", + "date": "2026-09-21", + "type": "updated", + "summary": "workbench.packOrder 除 token、key 外不再接收任何订单相关信息:订单参数一律由后端从打包上下文缓存拉取(防篡改)", + "methods": [ + "workbench.packOrder", + "workbench.business" + ], + "notes": [ + "workbench.packOrder 入参收敛为 token + key,移除旧参数(delivery_order_code/waybill_code/wave_no/status/pack_time/wave_total_orders/items_count/items_total),body 传入其它字段一律忽略;缺 key 返回 400、key 过期返回 400、跨仓库/跨工作台使用返回 403。", + "workbench.business 的 packOrder 分支同样只接受 key(订单信息取自缓存,仓库/工作台取缓存值)。", + "代码变更:app/service/systems/workbench.js 新增 _loadPackCtx(凭 key 拉取缓存,缺 key/过期抛错);packOrderByToken 只取 token+key 并捕获 _loadPackCtx 异常转 400;business(packOrder) 分支改走 key 消费。", + "回归测试 test/workbench_pack_waybill_dimension.test.cjs(21 用例,含缺 key 400、business 只接受 key、body 订单参数忽略)。" + ], + "module": "workbench" + }, + { + "version": "2026.09.21-workbench.packOrder-key-mode", + "date": "2026-09-21", + "type": "updated", + "summary": "workbench.queryOrder 返回打包上下文 key(20 分钟缓存);workbench.packOrder 精简为 token+key 消费缓存参数(旧参数模式保留兼容)", + "methods": [ + "workbench.queryOrder", + "workbench.packOrder" + ], + "notes": [ + "workbench.queryOrder 扫码查询成功时生成打包上下文 key(wpck 前缀 + 32 位随机段),缓存 key workbench:packctx:{key}、TTL 1200s,内容含 warehouse_id/workbench_id/order_id/delivery_order_code/wave_no/waybill_code/is_sandan,响应新增 key 字段;缓存写入失败仅告警不阻断查询。", + "workbench.packOrder 推荐只传 token + key:后端按 key 拉取缓存参数执行打包(数量参数后端复查兜底),跨仓库/跨工作台消费他人 key 返回 403、key 过期返回 400(提示重新扫码);旧参数模式(不传 key 直接传 delivery_order_code 等)保留兼容。", + "代码变更:app/service/systems/workbench.js 新增 WORKBENCH_PACK_CTX_CACHE_PREFIX/TTL/KEY_PREFIX 常量、generatePackCtxKey、getWorkbenchPackCtxCacheKey;_queryOrder 步骤7 写打包上下文缓存并返回 key(新增 workbench_id 入参);packOrderByToken 增加 key 消费与归属校验;queryOrderByToken 注入 workbench_id。", + "回归测试 test/workbench_pack_waybill_dimension.test.cjs(19 用例,含 key 模式/过期/跨仓/跨台/旧模式兼容)。" + ], + "module": "workbench" + }, + { + "version": "2026.09.21-workbench.packOrder-remove-users-param", + "date": "2026-09-21", + "type": "updated", + "summary": "workbench.packOrder 移除 users 入参:打包人一律由服务端取该工作台绑定成员(wms_workbench_member)回填", + "methods": [ + "workbench.packOrder" + ], + "notes": [ + "打包人数据源收敛为工作台绑定成员(bindMember/removeMember 登入登出链路持久化到 wms_workbench_member),packOrder 不再接收 users 入参,写入 wms_pack_task_packer 与 operator_text 的打包人一律由服务端按 workbench_id 回填;旧设备端传 users 将被忽略。", + "代码变更:app/service/systems/workbench.js#_packOrder 移除 users 解构与上报优先分支,步骤7 直接回填绑定成员;回归测试 test/workbench_pack_waybill_dimension.test.cjs 更新(13 用例,含「旧设备端仍传 users:一律忽略」)。" + ], + "module": "workbench" + }, + { + "version": "2026.09.21-workbench.removeMember-auto-finish-pack", + "date": "2026-09-21", + "type": "updated", + "summary": "workbench.packOrder 打包人缺省自动回填工作台绑定成员;workbench.removeMember 成员全部登出后自动结束未结束的打包任务", + "methods": [ + "workbench.packOrder", + "workbench.removeMember" + ], + "notes": [ + "workbench.packOrder 的 users 入参缺省/为空时,后端自动查询该工作台绑定成员(wms_workbench_member)回填 wms_pack_task_packer 与 operator_text,打包人数据源单一,设备端无需重复上报;上报时优先使用上报值。", + "workbench.removeMember 软删除成员行后统计剩余成员,剩余为 0 时自动结束该工作台所有未结束打包任务(status<2 → 2 并写 end_time),同步订单打包状态(散单按订单、团购按波次,与 _finishPack 语义一致)、写完成操作日志、复位摄像头 OSD、失效 token 缓存;响应新增 auto_finished_pack(finished/task_ids)。", + "代码变更:app/service/systems/workbench.js#_packOrder(步骤7 成员回填)、#removeWorkbenchMember(登出后剩余成员检查)、新增 #_finishAllPackTasksByMemberLogout;回归测试 test/workbench_pack_waybill_dimension.test.cjs(13 用例)。" + ], + "module": "workbench" + }, + { + "version": "2026.09.21-workbench.packOrder-waybill-dimension", + "date": "2026-09-21", + "type": "updated", + "summary": "workbench.packOrder 支持运单维度打包流水(一单多号:主单号/子单号流水互不覆盖),workbench.queryOrder 的 pack_flag 改为运单维度判定", + "methods": [ + "workbench.packOrder", + "workbench.queryOrder", + "workbench.business" + ], + "notes": [ + "背景:一单多号订单(wms_order_express 同 order_id 下 business_key=1 主单号 / >1 子单号)此前按订单维度打包,任一运单打包后订单 pack_status 非 none,导致另一运单被误判为已打包、无法写入打包流水。", + "workbench.packOrder 新增可选入参 waybill_code:散单按「订单+运单号」维度写入 wms_pack_task.waybill_code 并去重(同时清理同订单历史 waybill_code 为空的旧流水),主/子单号流水互不覆盖;未传运单号(旧设备端)保持订单维度;团购为波次维度,不使用运单号。", + "workbench.queryOrder 的 pack_flag 改为运单维度判定:查询该运单号是否已有打包流水(waybill_code 命中,或历史订单级流水 waybill_code 为空兜底),流水查询异常时降级为订单级 pack_status 判定。", + "代码变更:app/service/systems/workbench.js#_packOrder(步骤2.5 运单归属解析、步骤5 去重、packData.waybill_code、步骤7.5 OSD 优先展示打包运单号)、#_queryOrder(步骤6 pack_flag 运单级判定);回归测试 test/workbench_pack_waybill_dimension.test.cjs(8 用例)。" + ], + "module": "workbench" + }, { "version": "2026.09.20-workbench-pack-backfill-confirm-print", "date": "2026-09-20", diff --git a/methods/system.json b/methods/system.json index 9a90cc6..279696e 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.142", - "updatedAt": "2026-09-19", + "version": "0.3.143", + "updatedAt": "2026-09-21", "headers": [ { "name": "platform", @@ -33808,7 +33808,7 @@ }, { "method": "workbench.business", - "description": "工作台业务入口(免登录免鉴权,入参 name + data)。name 支持 queryOrder/query(条码查订单,data 需 barcode+warehouseId)、packOrder(开始打包)、finishPack(结束打包)、sendWeight(称重);不支持的业务名称报错。以下响应结构为 queryOrder/query(条码查订单)的返回。", + "description": "工作台业务入口(免登录免鉴权,入参 name + data)。name 支持 queryOrder/query(条码查订单,data 需 barcode+warehouseId)、packOrder(开始打包,凭 key 从后端缓存取订单信息防篡改;不传 key 时旧参数模式过渡兼容)、finishPack(结束打包)、sendWeight(称重);不支持的业务名称报错。以下响应结构为 queryOrder/query(条码查订单)的返回。", "isNeedAuth": false, "isNeedLogin": false, "headers": [], @@ -33983,7 +33983,7 @@ { "name": "pack_flag", "type": "number", - "description": "打包标志(仅散单 isSandan=1 返回,团购不返回):打包状态(pack_status)不等于 none 时为 1,等于 none 时为 0" + "description": "打包标志(仅散单 isSandan=1 返回,团购不返回):按运单维度判定——该运单号已有打包流水(wms_pack_task.waybill_code 命中,或历史订单级流水 waybill_code 为空兜底)时为 1,否则为 0;主单号/子单号互不影响" } ] }, @@ -34306,7 +34306,7 @@ "name": "current_orders", "type": "array", "required": true, - "description": "当前正在打包的订单数组(该工作台全部未结束任务(status<2)按任务 id 倒序,逐单按 current→dispatch 分表补发货单号;无进行中任务或查询异常时为空数组)" + "description": "当前正在打包的订单数组(该工作台全部未结束任务(status<2)按任务 id 倒序,逐单按 current→dispatch 分表补发货单号,散单任务另补货主备注(store_remark)与运单信息(express:物流公司/称重重量/包材名称,与 workbench.queryOrder 口径一致);无进行中任务或查询异常时为空数组)" }, { "name": "current_orders[].task_id", @@ -34386,6 +34386,42 @@ "required": true, "description": "货主ID(订单分表未命中时为 0)" }, + { + "name": "current_orders[].store_remark", + "type": "string", + "required": false, + "description": "货主备注(合约表 wms_store_warehouse.store_remask;仅散单任务返回,团购为空字符串,与 workbench.queryOrder 的 store_remark 口径一致)" + }, + { + "name": "current_orders[].express", + "type": "object", + "required": false, + "description": "运单信息(仅散单任务返回,团购为 null;与 workbench.queryOrder 的 express 口径一致)" + }, + { + "name": "current_orders[].express.waybill_code", + "type": "string", + "required": false, + "description": "运单号" + }, + { + "name": "current_orders[].express.logistics_name", + "type": "string", + "required": false, + "description": "物流公司名称" + }, + { + "name": "current_orders[].express.weighing_weight", + "type": "number", + "required": false, + "description": "称重重量(克)" + }, + { + "name": "current_orders[].express.package_material_name", + "type": "string", + "required": false, + "description": "包材名称(wms_order_express.package_material_name_snapshot,无包材为空字符串)" + }, { "name": "current_orders[].items_count", "type": "number", @@ -34589,7 +34625,7 @@ }, { "method": "workbench.removeMember", - "description": "移除工作台成员(免登录、免鉴权,以工作台 token 鉴权):入参成员行 ids 与工作台 token,token 优先校验(无 token 返回 401、token 无效返回 403),按 token 解析工作台后仅软删除归属于该工作台的成员行(wms_workbench_member 副表,user_id 可为空兼容非系统账号用户),返回移除数量与行ID列表", + "description": "移除工作台成员(免登录、免鉴权,以工作台 token 鉴权):入参成员行 ids 与工作台 token,token 优先校验(无 token 返回 401、token 无效返回 403),按 token 解析工作台后仅软删除归属于该工作台的成员行(wms_workbench_member 副表,user_id 可为空兼容非系统账号用户),返回移除数量与行ID列表;移除后该工作台已无任何成员时自动结束其所有未结束的打包任务(wms_pack_task.status<2 置 2 并写 end_time,同步回写订单打包状态与补确认打印状态、写完成操作日志、复位摄像头 OSD、失效 token 缓存,与 finishPack 语义一致),响应附 auto_finished_pack", "isNeedAuth": false, "isNeedLogin": false, "headers": [], @@ -34621,6 +34657,24 @@ "type": "array", "required": true, "description": "实际移除的成员行ID列表" + }, + { + "name": "auto_finished_pack", + "type": "object", + "required": false, + "description": "成员全部登出后的自动结束打包结果(仅移除后该工作台无成员时才有实际动作;其余情况 finished=0)" + }, + { + "name": "auto_finished_pack.finished", + "type": "number", + "required": true, + "description": "自动结束的打包任务数量" + }, + { + "name": "auto_finished_pack.task_ids", + "type": "array", + "required": true, + "description": "自动结束的打包任务ID列表" } ], "errors": [ @@ -34718,7 +34772,7 @@ }, { "method": "workbench.packOrder", - "description": "工作台打包上报(免登录、免权限、免鉴权,以工作台 token 鉴权):仓库与工作台均由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值),入参发货单号、波次号、状态、打包时间、波次总订单数、SKU 品种数、商品总件数、打包人员(以上数量以服务端复查为准,设备上报仅交叉校验);按发货单号定位订单(current→dispatch 分表),同一工作台存在上一个未结束任务时先关闭(同步回写旧订单打包状态并补确认打印状态,并将工作台绑定摄像头 OSD 复位为「无任务」,新任务 OSD 在其后串行下发避免被复位覆盖),散单按 order_id、团购按 wave_no 去重后创建打包任务(wms_pack_task,缺失/非法 status 归一化为 1=打包中),写入打包人员(wms_pack_task_packer)与 operator_text、下发 OSD 到工作台绑定摄像头(散单显示运单号、团购显示波次号+订单总量,并写 Redis osd_{workbenchId} 缓存)、写操作日志;打包状态变更后主动失效对应工作台 token 缓存,保证 getWorkbenchInfo 尽快返回最新打包信息;团购单(isSandan=0)响应附 batch 波次信息(波次订单数为 current+dispatch 分表实时统计);拦截流程中的订单不允许打包(散单直接拒绝、团购波次静默跳过并视为完成);保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200", + "description": "工作台打包上报(免登录、免权限、免鉴权,以工作台 token 鉴权):推荐只传 token + key,订单相关信息(订单号/波次号/运单号)由后端从缓存拉取(前端先经 workbench.queryOrder 扫码拿到 key,20 分钟有效,防篡改);不传 key 时旧参数模式(delivery_order_code 等直传)过渡兼容,后续版本将移除;仓库与工作台均由服务端从 token 解析注入(禁止前端传值);跨仓库/跨工作台消费他人 key 返回 403、key 缺失或过期返回 400(请重新扫码)。打包流程:按发货单号定位订单(current→dispatch 分表),同一工作台存在上一个未结束任务时先关闭(同步回写旧订单打包状态并补确认打印状态,并将工作台绑定摄像头 OSD 复位为「无任务」,新任务 OSD 在其后串行下发避免被复位覆盖),散单去重(传运单号按 order_id+waybill_code、未传按 order_id)、团购按 wave_no 去重后创建打包任务(wms_pack_task,status 归一化为 1=打包中,散单传运单号时 waybill_code 写入流水),写入打包人员(wms_pack_task_packer,自动取该工作台绑定成员 wms_workbench_member)与 operator_text、下发 OSD 到工作台绑定摄像头(散单优先展示打包运单号、团购显示波次号+订单总量,并写 Redis osd_{workbenchId} 缓存)、写操作日志;打包状态变更后主动失效对应工作台 token 缓存,保证 getWorkbenchInfo 尽快返回最新打包信息;团购单(isSandan=0)响应附 batch 波次信息(波次订单数为 current+dispatch 分表实时统计);拦截流程中的订单不允许打包(散单直接拒绝、团购波次静默跳过并视为完成);保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200", "isNeedAuth": false, "isNeedLogin": false, "isNeedRight": false, @@ -34732,60 +34786,11 @@ "description": "工作台 token(64 位,工作台身份凭证;仓库与工作台由服务端从 token 解析注入)" }, { - "name": "delivery_order_code", + "name": "key", "type": "string", "required": true, "source": "body", - "description": "发货单号(必填,用于定位订单)" - }, - { - "name": "wave_no", - "type": "string", - "required": false, - "source": "body", - "description": "波次号(不传时取订单 wave_no)" - }, - { - "name": "status", - "type": "number", - "required": false, - "source": "body", - "description": "打包状态(缺失或非法时归一化为 1=打包中;>=2 视为完成并写 end_time)" - }, - { - "name": "pack_time", - "type": "number", - "required": false, - "source": "body", - "description": "打包时间(秒级时间戳,缺省为当前时间)" - }, - { - "name": "wave_total_orders", - "type": "number", - "required": false, - "source": "body", - "description": "波次总订单数(仅交叉校验日志,落库以服务端复查为准:团购取 current+dispatch 分表实时统计的波次订单数)" - }, - { - "name": "items_count", - "type": "number", - "required": false, - "source": "body", - "description": "SKU 品种数(仅交叉校验日志,落库以服务端复查为准:散单取订单 item_count、团购取波次商品 SKU 聚合数)" - }, - { - "name": "items_total", - "type": "number", - "required": false, - "source": "body", - "description": "商品总件数(仅交叉校验日志,落库以服务端复查为准:散单取订单 items_total、团购取波次商品 SKU 聚合件数)" - }, - { - "name": "users", - "type": "array", - "required": false, - "source": "body", - "description": "打包人员数组,元素含 wms_account_id(或 id,账号ID,可空)与 real_name(姓名);写入 wms_pack_task_packer 并回写 operator_text" + "description": "打包上下文 key(来自 workbench.queryOrder 响应,20 分钟有效;凭 key 由后端从缓存拉取订单号/波次号/运单号,参数后端维护防篡改,跨仓库/跨工作台使用返回 403、过期返回 400)" } ], "response": [ @@ -35081,7 +35086,7 @@ }, { "method": "workbench.queryOrder", - "description": "工作台条码查询订单(免登录、免权限、免鉴权,以工作台 token 鉴权):仓库与工作台均由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值,防止跨仓库查单),入参条码(运单号);条码→运单记录(wms_order_express,按 waybill_code+warehouse_id+status=1 精确匹配)→ 序列表定位优先、未命中按 current→dispatch 回退遍历订单分表 → 组装查询结果(barcode/waybill_code/isSandan/store_remark/express/order/items/source_table);散单(isSandan=1)order 附拦截/打包 0/1 标志 intercept_flag/pack_flag(拦截/打包状态空值归一化为 none,非 none 记 1);团购(isSandan=0,波次类型 wave_type=1)附 batch 波次信息(wave_id/wave_no/wave_type/total_orders,total_orders 为 current+dispatch 分表实时统计并带 15s 短缓存兜底);items 逐项合并 stock 详情(sku_property/stock_unit/barcodes/image_url/packing_requirements/need_recheck(是否需要复核:Y=需要 N=不需要(免验)));store_remark 来自合约表 store_warehouse.store_remask;只读查询,不涉及缓存失效;保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200", + "description": "工作台条码查询订单(免登录、免权限、免鉴权,以工作台 token 鉴权):仓库与工作台均由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值,防止跨仓库查单),入参条码(运单号);条码→运单记录(wms_order_express,按 waybill_code+warehouse_id+status=1 精确匹配)→ 序列表定位优先、未命中按 current→dispatch 回退遍历订单分表 → 组装查询结果(barcode/waybill_code/isSandan/store_remark/express/order/items/source_table);散单(isSandan=1)order 附拦截/打包 0/1 标志 intercept_flag/pack_flag(拦截标志:拦截状态空值归一化为 none,非 none 记 1;打包标志:按运单维度判定,该运单号已有打包流水 wms_pack_task.waybill_code 命中或历史订单级流水 waybill_code 为空兜底时为 1,否则 0,主单号/子单号互不影响);团购(isSandan=0,波次类型 wave_type=1)附 batch 波次信息(wave_id/wave_no/wave_type/total_orders,total_orders 为 current+dispatch 分表实时统计并带 15s 短缓存兜底);items 逐项合并 stock 详情(sku_property/stock_unit/barcodes/image_url/packing_requirements/need_recheck(是否需要复核:Y=需要 N=不需要(免验)));store_remark 来自合约表 store_warehouse.store_remask;只读查询,不涉及缓存失效;保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200;查询成功时生成打包上下文 key(wpck 前缀 + 随机段,Redis 缓存 workbench:packctx:{key},TTL 20 分钟,内容含订单号/波次号/运单号/归属仓库与工作台,后端维护防篡改)并在响应返回 key,供 workbench.packOrder 凭 key 打包", "isNeedAuth": false, "isNeedLogin": false, "isNeedRight": false, @@ -35103,6 +35108,12 @@ } ], "response": [ + { + "name": "key", + "type": "string", + "required": false, + "description": "打包上下文 key(20 分钟有效,凭此 key 调用 workbench.packOrder 打包,参数后端维护防篡改;缓存写入失败时缺省)" + }, { "name": "barcode", "type": "string", @@ -35299,7 +35310,7 @@ "name": "order.pack_flag", "type": "number", "required": false, - "description": "打包标志(仅散单 isSandan=1 返回):打包状态空值归一化为 none,非 none 记 1 否则 0" + "description": "打包标志(仅散单 isSandan=1 返回):按运单维度判定——该运单号已有打包流水(wms_pack_task.waybill_code 命中,或历史订单级流水 waybill_code 为空兜底)时为 1,否则为 0;主单号/子单号互不影响" }, { "name": "items",