[ { "version": "0.3.325", "date": "2026-11-11", "type": "added", "summary": "新增运单物流轨迹批量更新:waybill.warehouse.updateTrace 与 waybill.warehouse.updateTraceTaskProgress,链路走 OpenAPI 出站回调 waybill.getTrace(入参同 waybill.getreceive,单批 10 单),结果按 (express_id, op_time, scan_type) 幂等落库 wms_order_express_trace", "methods": [ "waybill.warehouse.updateTrace", "waybill.warehouse.updateTraceTaskProgress" ], "notes": [ "回调方法注册:app/lib/callback_functions.js#CALLBACK_FUNCTIONS 新增 waybill.getTrace(名称「运单物流轨迹查询」),管理端 apiApp.listCallbackFunctions 可拉取并勾选。", "入参:与 waybill.warehouse.updateReceive 完全一致,支持 waybillCodes(优先)或 where(与 waybill.warehouse.list 同口径,不含分页/排序,上限 5000 条)。", "请求体:{ request: { waybill_codes: [...] } },单批最多 10 个运单号;签名口径与 waybill.getreceive 一致(MD5(appSecret + timestamp + bodyJson))。", "响应解析:[{ waybillNo, trace: {...} }],兼容 trace 为数组、traces 数组、traceList 与 { code, data: [...] } 包装。", "落库:wms_order_express_trace,字段映射 opTime→op_time、outBizCode→out_biz_code、memo→memo、opOrgCityName→op_org_city_name、weight→weight、scanType→scan_type,原始报文存 raw_data;唯一键 (express_id, op_time, scan_type) 保证重复回传不产生重复行,命中时更新轨迹文案等字段。", "任务:task_id 前缀 waybill_trace_,Redis 缓存键前缀 waybill_trace_task_;状态流转 submitted → running → success/failed,result 返回 { total, matched, inserted, updated, not_found, failed }。", "前置校验:仓库下无应用承接 waybill.getTrace 时直接失败并提示「如需更新运单物流轨迹信息,到【设置】->【基础设置】->【API开放接口】配置相应的外部访问接口」,不创建任务。", "代码依据:app/service/systemMethods/waybill/warehouse.js#updateTrace/#updateTraceTaskProgress,app/service/systems/waybill.js#queryTraces/#saveTraces。" ] }, { "version": "0.3.324", "date": "2026-11-11", "type": "added", "summary": "新增运单批量更新是否揽收:waybill.warehouse.updateReceive 与 waybill.warehouse.updateReceiveTaskProgress,链路走 OpenAPI 出站回调 waybill.getreceive(单批 10 单,按仓库通知协议签名),结果回写 wms_order_express.is_galaxy_receive(仓库隔离);支持 waybillCodes 或与 waybill.warehouse.list 一致的 where 条件圈选运单号。配套为 is_back / is_intercept / is_galaxy_receive 补默认值 N、回填存量 NULL 并建立单列索引", "methods": [ "waybill.warehouse.updateReceive", "waybill.warehouse.updateReceiveTaskProgress" ], "notes": [ "背景:wms_order_express.is_galaxy_receive 此前只有创建默认值且实际大量为 NULL,没有任何写入来源;列表按 isGalaxyReceive=N 筛选直接返回空。本批次补齐外部回传链路,并修复默认值与历史数据。", "where 入参(2026-11-11):复用 systems/waybill.js#buildListQueryWhere(由 list 抽取而来),条件口径与 waybill.warehouse.list 完全一致:支持 operator/value 格式、主单号展开(mainWaybillCode)、时间范围(createdAt 数组/区间/旧写法)、关键词模糊等;不含 pagination/sort。", "优先级与上限:waybillCodes 非空时直接使用并忽略 where;仅传 where 时先解析运单号再走同一任务链路;匹配数 > 5000 条直接失败(不截断),匹配 0 条失败,两者都不传失败。", "单批上限:waybill.getreceive 每次最多 10 个运单号,超出自动切批(25 单 → 10/10/5),每批完成后按已处理数更新任务进度。", "签名口径(2026-11-10 调整):外部接收端按 methods/warehouse_notify.json 协议验签,故 sign = MD5(appSecret + timestamp + bodyJson)(openapi/callback.js#signCallback 的 signMode=simple);沿用 /openapi 入站的 MD5(canonicalQuery + appSecret + MD5(body)) 会被对端判为验签失败(实测 code=401)。", "回写口径:按 waybill_code + warehouse_id 更新 wms_order_express.is_galaxy_receive(外部 1→Y、0→N),跨仓不串写;仅当状态变化时才发 UPDATE,未变化计入 unchanged。", "业务失败识别:HTTP 200 但响应体 code 非 0/1/200(如验签失败 code=401)时整批计入 result.failed,不再静默当作「无数据」。", "未配置外部接口:仓库下没有启用应用勾选 callback_functions=waybill.getreceive 时直接返回失败并提示「如需更新运单是否揽收信息,到【设置】->【基础设置】->【API开放接口】配置相应的外部访问接口」,不创建任务、不写进度缓存。", "任务进度:task_id 前缀 waybill_receive_,Redis 缓存键前缀 waybill_receive_task_;状态流转 submitted → running → success/failed,与运单导出(waybill_export_)同构但互相隔离。", "返回值兼容:外部响应支持裸数组 [{ waybill_code, is_galaxy_receive }]、{ code, data: [...] } 与 { data: { waybills: [...] } };is_galaxy_receive 支持 1/0、'Y'/'N'、布尔,非法取值计入 failed 不写库。", "配套数据库变更(已执行):迁移 20261111033000 为 is_back / is_intercept / is_galaxy_receive 补 DEFAULT 'N' 并把存量 NULL 回填为 'N'(Y 不动);迁移 20261111041500 为三列分别建立单列索引 idx_is_back / idx_is_intercept / idx_is_galaxy_receive(ALGORITHM=INPLACE, LOCK=NONE)。", "回调方法注册:app/lib/callback_functions.js#CALLBACK_FUNCTIONS 新增 waybill.getreceive,管理端 apiApp.listCallbackFunctions 可拉取并勾选。", "代码依据:app/service/systemMethods/waybill/warehouse.js#updateReceive/#updateReceiveTaskProgress,app/service/systems/waybill.js#buildListQueryWhere/#resolveWaybillCodesByWhere/#queryReceiveStatus。" ] }, { "version": "0.3.322", "date": "2026-11-02", "type": "updated", "summary": "订单批量锁定跳过已取消订单:order.pendingOrder.batchLock 后台任务不再锁定 status=cancel 的订单,避免取消订单被锁定后无法出库;新增 skipped_cancelled_order_count / skipped_cancelled_order_ids 透出跳过明细", "methods": [ "order.pendingOrder.batchLock", "order.pendingOrder.batchLockTaskProgress" ], "notes": [ "背景:奇门取消订单(ORDER_CANCEL,status=cancel)后,网页后台仍可对该订单执行订单锁定(ORDER_LOCK)。取消订单被锁定后会残留锁定标记,导致订单无法按取消逻辑正常出库。", "现口径:runBatchLockTask 查询订单时带出 status,status=cancel 的订单不进入锁定更新,也不写入 ORDER_LOCK 操作日志;混合批次只锁定未取消订单。", "并发保护:更新语句 where 增加 status != 'cancel';若更新影响行数少于目标行数,回查确认实际落库订单,只为确认锁定的订单写日志与计数。", "返回:batchLockTaskProgress 在 running/success/failed 返回 skipped_cancelled_order_count,running/success 返回 skipped_cancelled_order_ids;success.result.message 存在跳过项时提示「已跳过 N 条已取消订单」,全部为取消订单时提示「所选订单均已取消,已跳过 N 条,不能锁定」。", "兼容性:入参未变;解锁(order.pendingOrder.batchUnlock)仍可对已取消订单执行,便于清理历史锁定状态。", "测试:test/app/service/systemMethods/order/pendingOrder.batchLock.cancel.test.js 新增 4 条用例(混合批次跳过取消单、全部取消不更新、进度接口返回跳过明细、更新期间并发取消不写日志)。", "代码依据:app/service/systemMethods/order/pendingOrder.js#runBatchLockTask/#batchLockTaskProgress。" ] }, { "version": "0.3.321", "date": "2026-10-28", "type": "updated", "summary": "space 视图补齐静态盘点拣货完成标记:stock.check.workData(space 视图)与 stock.check.workDataSpaceDetails 的 goods 子项在 is_static=1 时新增 picking_completed(是否已完成拣货),口径与 goods 视图一致", "methods": [ "stock.check.workData", "stock.check.workDataSpaceDetails" ], "notes": [ "背景:0.3.320 已在 goods 视图行与商品钻取输出 picking_completed,但盘点作业前端默认使用 space 视图(workData 不传 is_goods)与 workDataSpaceDetails(库位分页),这两条链路拿不到拣货完成状态,无法在上报前提示/置灰。", "现口径:_buildSpaceWorkRows 在 is_static=1 时按商品维度查询仓库内 SUM(locked_quantity)(_fetchStockLockedQuantityMap),goods 子项输出 picking_completed(1=已完成拣货/0=未完成);同一商品在各库位行上的取值一致(商品维度,非库位维度)。盲盘(mode=blind)同样返回该标记,但仍不返回任何数量字段(locked_quantity 仍只在明盘输出)。", "workDataSpaceDetails 复用同一 space 视图构建函数,因此自动获得该字段,无需额外参数;与 stock.check.report 的静态盘点上报拦截配套(商品未完成拣货返回 400「商品尚未完成拣货,不满足静态盘点要求,请先等待该商品完全完成拣货」)。", "兼容性:非静态任务(is_static=0)不返回 picking_completed,行为与之前一致;未新增必填入参;原有 system_quantity/storage_quantity/locked_quantity/snapshot_quantity/checked_quantity 字段口径与取值均未变化。", "测试:test/app/service/systems/stock_check.test.js 的「静态盘点拣货完成标记」用例补充 space 视图(workData 默认视图)与 workDataSpaceDetails(按 location_id 取库位行)的 picking_completed 断言,锁定量存在时为 0、清零后为 1。真实库全量 256 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 2 条 method(stock.check.workData:description/response.rows 的 space 视图 goods 字段说明 + notes;stock.check.workDataSpaceDetails:description + 新增 notes);根版本 0.3.320 → 0.3.321、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位)。", "代码依据:app/service/systems/stock_check.js#_buildSpaceWorkRows/#workDataSpaceDetails/#_fetchStockLockedQuantityMap。" ] }, { "version": "0.3.320", "date": "2026-10-28", "type": "updated", "summary": "静态盘点拣货完成口径:stock.check.workData(goods 视图)与 stock.check.workDataDetail(商品钻取)新增 picking_completed(是否已完成拣货,判定=该商品在仓库内 wms_storage SUM(locked_quantity) 是否为 0)与明盘 locked_quantity;stock.check.report 对静态盘点且仍未完成拣货的商品拒绝上报", "methods": [ "stock.check.workData", "stock.check.workDataDetail", "stock.check.report" ], "notes": [ "背景:静态盘点审核通过即冻结账面基准,但盘点期间仍允许把「已分配储位、尚未拣出」的存量锁定货拣走(静态锁定只拦截新的储位分配,不拦截已有锁定)。若实盘发生在该批货拣完之前,实盘数与其后扣减的库位库存会相互矛盾,差异不可信(生产 PD20261027000001 商品 160240:快照后仍有 129 件在拣,最终产生 -115 的假盘亏)。", "现口径:静态盘点(is_static=1)要求「该商品已完成拣货」——判定依据为 wms_storage 中该商品在仓库内 SUM(locked_quantity) 是否为 0。分配储位只把 available_quantity 搬成 locked_quantity(quantity 不变),拣货完成时 quantity 与 locked_quantity 同时扣减、available_quantity 不变,因此 locked_quantity>0 即表示仍有在途待拣出库。", "新增字段:stock.check.workData goods 视图行在 is_static=1 时返回 picking_completed(1=已完成/0=未完成)与明盘 locked_quantity(该商品仓库内锁定量合计,盲盘不输出数值只输出完成标记);stock.check.workDataDetail 商品钻取在 is_static=1 时顶层返回同名两字段,口径一致。", "上报拦截:stock.check.report 在任务 is_static=1 且为商品范围明细(scope_type=goods)时,写记录前校验该商品锁定量,>0 直接 400「商品尚未完成拣货,不满足静态盘点要求,请先等待该商品完全完成拣货」。库位范围任务 is_static 恒为 0,不受影响;未知商品(stock_id 为空)无锁定量,不受影响。", "兼容性:非静态任务(is_static=0)不返回 picking_completed,行为与之前一致;未新增必填入参,前端可忽略新字段。锁定量判定按仓库维度(不限任务库位范围),与静态锁定商品(stock 维度)口径一致。", "测试:test/app/service/systems/stock_check.test.js 新增「静态盘点拣货完成标记」用例——人为把 available 搬成 locked 后断言 goods 视图/钻取 picking_completed=0 且 locked_quantity 正确、report 被拒;锁定量清零后 picking_completed=1 且上报成功。原「账面取值按任务静态标记」用例改为仅取无锁定量商品并在 finally 完成盘点释放静态锁定。真实库全量 256 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 3 条 method(stock.check.workData:response.rows 商品视图字段补 picking_completed/locked_quantity + notes;stock.check.workDataDetail:description + notes;stock.check.report:description、errors 400 文案 + notes);根版本 0.3.319 → 0.3.320、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位)。", "代码依据:app/service/systems/stock_check.js#_fetchStockLockedQuantityMap/#_buildGoodsWorkRows/#_formatGoodsWorkDetail/#report。" ] }, { "version": "0.3.319", "date": "2026-10-28", "type": "updated", "summary": "盘点账面口径统一改为可用数量(wms_storage SUM(available_quantity)),不再把 locked_quantity(已分配储位、待拣出库的锁定量)计入账面;商品明细快照、动态实时账面、库位盘点、明盘工作台/钻取全部统一", "methods": [ "stock.check.addDetail", "stock.check.result", "stock.check.report", "stock.check.finish", "stock.check.submit", "stock.check.audit", "stock.check.workData", "stock.check.workDataDetail" ], "notes": [ "背景:原账面口径为 SUM(available_quantity + locked_quantity)(=可用+锁定),会把已分配储位但尚未拣出的锁定量算进账面。静态盘点若在仍有在途拣货时开盘,快照会包含这批货,拣货完成后即变成假盘亏(生产 PD20261027000001:商品 160240 账面 248 vs 实盘 133,差异 -115,其中 129 件是快照后 19:02-20:51 才从库位拣出的)。", "现口径:全部盘点账面统一取 wms_storage SUM(available_quantity)(= quantity - locked_quantity - intercept_locked_quantity)。涉及:addDetail 拆行快照、submit/audit 刷新快照、result 库位行与空库位标记、_recalcCheckSummary/report/finish 差异汇总、workData/workDataDetail 明盘实时账面。", "语义依据:分配储位只把 available 搬成 locked(quantity 不变、账面不变);拣货完成同时扣 quantity 与 locked、available 不变。因此可用数量口径在盘点窗口内对拣货动作不敏感,锁定货拣完前后都成立。", "兼容性:locked_quantity 字段继续单独输出(明细 locations.locked_quantity / space 视图 goods.locked_quantity),仅不再计入 system_quantity;前端如需「含锁定总量」请用 system_quantity + locked_quantity 或直接查 storage.quantity。", "历史任务:已完成任务 system_quantity 为旧口径快照,本次不回刷;如需对齐新口径需驳回重新提交或重新审核触发快照刷新。", "测试:test/app/service/systems/stock_check.test.js 账面 helper/断言同步改为 SUM(available_quantity),真实库全量 255 用例通过,ESLint 0 错误。", "代码依据:app/service/systems/stock_check.js#_addGoodsDetailRows/#_refreshGoodsBookSnapshot/#_recalcCheckSummary/#result/#_formatDetailAggregationRow/#_buildGoodsWorkRows/#_buildSpaceWorkRows。" ] }, { "version": "0.3.318", "date": "2026-10-28", "type": "updated", "summary": "盘点作业数据账面取值按任务 is_static 区分:stock.check.workData(goods/space 视图)与 stock.check.workDataDetail(商品钻取)对静态盘点取明细快照、对普通盘点取当前 wms_storage 账面;新增 storage_quantity / is_static / book_source 字段。", "methods": [ "stock.check.workData", "stock.check.workDataDetail" ], "notes": [ "背景:静态盘点(is_static=1)在审核完成时会冻结账面基准(刷新明细 system_quantity 快照),盘点期间不允许出入库/移库;普通盘点则希望看到「当前账面」用于实时对比。原实现两种任务都混用了快照与 storage(goods 视图行级取快照、locations 取 storage),口径不一致。", "现口径:system_quantity = 本次参与差异计算的账面——is_static=1 → 该库位明细 system_quantity(快照);is_static=0 → wms_storage 该库位 SUM(available_quantity+locked_quantity)。行级(goods 视图行 / workDataDetail summary)为各库位账面之和;diff_quantity 一律 = 实盘 - system_quantity。", "新增字段:goods 视图行与 location item 增加 is_static / book_source(snapshot|storage)/ storage_quantity(当前 storage 账面),snapshot_quantity 继续输出明细快照;space 视图行内 goods 增加 storage_quantity / snapshot_quantity;workDataDetail 顶层增加 is_static / book_source,rows[] 增加 storage_quantity。", "兼容性:system_quantity 语义由「快照或 storage(视视图而定)」收紧为「按 is_static 取值」;普通盘点任务的 goods 视图行级账面可能从快照变为当前 storage(有出入库时数值不同),前端如需要基准值请改读 snapshot_quantity。", "未涉及:stock.check.result / finish / export 的差异汇总仍按「商品行快照、库位行 storage」的既有口径,本次未改;如需与两个作业数据接口完全对齐可另行确认。", "测试:test/app/service/systems/stock_check.test.js 新增「账面取值按任务静态标记」用例——审核后人为给该库位 +7,静态任务断言 row/locations/summary system_quantity == 快照且 storage_quantity == 快照+7、差异按快照算;非静态任务断言 system_quantity == 快照+7 且差异按当前账面算;goods 视图、space 视图、workDataDetail 三处交叉验证;全量 255 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.workData(rows.description 商品/space 视图账面口径 + notes)、stock.check.workDataDetail(data.description + notes);根版本 0.3.317 → 0.3.318、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位)。", "代码依据:app/service/systems/stock_check.js#workData/#workDataDetail/#_buildGoodsWorkRows/#_buildSpaceWorkRows/#_formatGoodsWorkDetail。" ] }, { "version": "0.3.317", "date": "2026-10-28", "type": "updated", "summary": "分配储位命中静态盘点锁定改为「订单级失败」:与库存不足同流程(该订单 storage_status=error + order_flag 静态盘点锁定原因),同批次其它订单继续分配,接口返回 200 并通过 shortage_order_ids/shortage_messages 体现。", "methods": [ "order.pendingOrder.allocateStorage", "order.wave.batchAllocateStorage" ], "notes": [ "修正原因:储位分配支持批量订单(order_ids 数组,波次/待处理订单均走同一入口),0.3.316 的「整单 400」会把同批次未锁定订单一并打断,与既有「库存不足」的静默跳过口径不一致,前端也无法区分哪些订单失败。", "现行为:命中静态盘点锁定的商品行在明细循环中直接跳过(不查可用储位、不加锁、不写 picking 行);订单级 finalShortageMessage 追加「静态盘点锁定:sku(x) 盘点单 PDxxx」,走与缺货完全相同的收尾——回滚该订单已锁定库存、置 storage_status=error、step=异常、order_flag=原因,并进入 orderResults(status=error)。", "响应:接口整体 200(除非仓库上下文/订单为空等参数错误);shortage_order_ids 含命中锁定的订单,shortage_messages 含静态盘点锁定文案与盘点单号;orders 中该订单 status=error;allocated_order_ids 仅含成功订单。", "与移库的区别:移库(storage.inventory.transferLocation/transferByProduct)是单条/单商品同步操作,仍保持 400 直接失败。", "测试:test/app/service/systems/static_lock_guard.test.js 改为批量口径——两个订单(1 命中锁定、2 正常)断言 code=200、shortage_order_ids=[1]、allocated_order_ids=[2]、锁定订单 order_flag 含静态盘点锁定、仅未锁定商品被加锁(lockCalls 仅 501/3)、picking 仅 1 行;另加「全部订单命中锁定仍返回 200、无加锁、事务正常提交」;5 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 order.pendingOrder 分组更新 order.pendingOrder.allocateStorage(description 改为订单级失败、移除静态盘点 400 错误项、notes 补充)、order.wave 分组更新 order.wave.batchAllocateStorage(notes);根版本 0.3.316 → 0.3.317、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位)。", "代码依据:app/service/systems/order_storage_allocation.js#allocatePicking、app/service/systems/stock_check.js#getStaticLockConflict。" ] }, { "version": "0.3.316", "date": "2026-10-28", "type": "updated", "summary": "静态盘点锁定拦截库存操作:分配储位(order.pendingOrder.allocateStorage / order.wave.batchAllocateStorage)与移库(storage.inventory.transferLocation / transferByProduct)在商品处于静态盘点锁定中时直接失败(400),返回冲突商品与来源盘点单号。", "methods": [ "order.pendingOrder.allocateStorage", "order.wave.batchAllocateStorage", "storage.inventory.transferLocation", "storage.inventory.transferByProduct" ], "notes": [ "需求:静态盘点(is_static=1,审核完成后锁定)期间,商品库存不允许被分配储位/移库,否则盘点实盘与账面基准错位;要求相关操作直接失败并给出明确原因。", "判定口径:复用 stock_check.staticLockList(按仓库缓存,TTL 300 秒 + 状态流转立即重建 + 代次防脏读)——is_static=1 且任务状态 approved/checking 的商品为锁定;审核完成即锁、完成/取消即释放。", "新增业务方法 stock_check.getStaticLockConflict({ warehouseId, stockIds, actionLabel }):返回 { locked, rows, message },message 形如「商品正在静态盘点中,禁止移库:编码(库存ID) 盘点单 PDxxxx」,供库存操作直接返回/抛出(systemMethods 未暴露,内部调用)。", "分配储位:orderStorageAllocation.allocatePicking 在归集订单明细 stock_id 后、查询可用储位库存之前校验,命中即回滚事务并返回 400 + data.locked_stock_ids/locked_items;allocateStorage 为其兼容入口,待处理订单分配、波次分配等内部调用全部生效。", "移库:storage.inventory.transferLocation(按库存记录)与 transferByProduct(按库位+商品)在锁定/读取原库存记录后校验 stock_id,命中即回滚并返回 400;未命中时行为与之前完全一致。", "降级策略:锁定查询异常(缓存/数据库故障)时按「未锁定」放行并写 warn 日志,避免因盘点缓存故障阻断出入库主流程;如需强一致可改为失败即拒绝。", "测试:新增 test/app/service/systems/static_lock_guard.test.js(4 个用例:transferLocation/transferByProduct 命中锁定 400+回滚+不写库存、未锁定时走原有可用量校验、allocatePicking 命中锁定 400+回滚+未查询储位库存);stock_check.test.js 新增 getStaticLockConflict 文案与空入参用例;相关套件 258 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 更新 storage.inventory.transferLocation、storage.inventory.transferByProduct、order.pendingOrder.allocateStorage(description/errors/notes)与 order.wave.batchAllocateStorage(notes);根版本 0.3.315 → 0.3.316、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位)。", "代码依据:app/service/systems/stock_check.js#getStaticLockConflict/#isStockStaticLocked、app/service/systems/storage/inventory.js#transferLocation/#transferByProduct/#_getStaticLockConflict、app/service/systems/order_storage_allocation.js#allocatePicking。" ] }, { "version": "0.3.315", "date": "2026-10-28", "type": "updated", "summary": "静态盘点锁定缓存增加防脏读机制:状态流转(审核/完成/取消/批量删除)先递增锁定代次再重建缓存,回源前后代次不一致则放弃写缓存(响应 cache_skipped=true),杜绝旧快照覆盖新缓存的脏读。", "methods": [ "stock.check.staticLockList", "stock.check.audit", "stock.check.finish" ], "notes": [ "问题:原实现为「状态更新 → 重建缓存(查询后写回)」,若两个流转并发(如审核 A 与完成 B),B 的重建可能先写入新快照,A 的旧快照随后覆盖 → 最长 300 秒脏读(锁定集合与库内状态不符)。", "方案(乐观锁/代次):新增代次键 `stock_check:static_lock_gen:{warehouseId}`,Redis 用 INCR 原子递增,Redis 不可用时退化为进程内计数;所有状态流转统一走 refreshStaticLockCache:递增代次 → 回源查询 → 写缓存;_loadStaticLockCache 在查询前后各读一次代次,不一致则判定为并发流转,跳过写缓存并清除缓存(返回 cache_skipped=true)。", "正确性:① 流转先提交数据库、再递增代次,故代次变化一定意味数据库已变;② 查询前读到的代次若在查询后被改,旧快照不会落盘;③ 未发生流转时的回源之间结果等价,覆盖无影响;④ 读取侧(staticLockList 缓存命中的分支)不受影响,缓存为空时回源保证最终一致。", "审核路径:audit(approve) → 刷新明细快照 → 更新状态 → refreshStaticLockCache(递增代次 + 重建),接口返回时缓存已包含新任务且无脏读窗口;reject 同理(重建后移除该任务)。", "性能:每次流转多 2 次 Redis 读 + 1 次 INCR(本地降级为内存操作),回源仍是 2 条 SQL;不影响常规查询(命中缓存时无额外开销)。", "测试:test/app/service/systems/stock_check.test.js 新增「防脏读:回源期间发生状态流转时不写入旧快照」用例——在 _queryStaticLockRows 内递增代次模拟并发流转,断言 cache_skipped=true 且缓存未被写入,并校验 refreshStaticLockCache 会递增代次;全量 253 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.staticLockList(新增 cache_skipped 响应字段 + 缓存设计/防脏读 notes)、stock.check.audit 与 stock.check.finish(notes 各追加代次说明);根版本 0.3.314 → 0.3.315、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位)。", "代码依据:app/service/systems/stock_check.js#refreshStaticLockCache/#_loadStaticLockCache/#_readStaticLockGeneration/#_bumpStaticLockGeneration/#staticLockList。" ] }, { "version": "0.3.314", "date": "2026-10-28", "type": "updated", "summary": "静态盘点锁定缓存策略加固:状态流转(审核/完成/取消/批量删除)由「删除缓存」改为「立即重建缓存」,消除审核后仍读到旧缓存的空窗;空集合也缓存(不穿透)、并发未命中用进程内 singleflight 去重(不击穿);TTL 仍为 300 秒兜底。", "methods": [ "stock.check.staticLockList" ], "notes": [ "缓存时长:TTL 300 秒(STATIC_LOCK_CACHE_TTL_SECONDS),仅作兜底;正常路径由状态流转触发重建,不依赖 TTL 到期。", "是否穿透:不会。回源结果(包括 rows 为空、stock_ids=[] 的空集合)都会写入缓存,因此「当前没有锁定商品」的仓库也不会每次查库;命中空缓存时返回 cached=true、total=0。", "是否击穿:同一进程内对同一仓库的并发未命中通过 STATIC_LOCK_INFLIGHT(Map)合并为一次回源,其余请求复用同一结果;跨实例的极短并发仍可能各自回源一次(2 条 SQL,成本低),数据结果一致。", "新审核是否清缓存:audit(approve) 在状态更新后调用 refreshStaticLockCache,回源并写回缓存(不是只删除),因此审核接口返回时缓存已包含新任务;reject 同样重建(移除该任务)。finish/cancel/batchDelete 亦为重建(移除对应任务,其它任务仍保留)。", "窗口评估:① 审核前查询到「未锁定」属于正确语义(审核未生效);② 审核接口返回后不存在旧缓存窗口;③ 若重建失败(Redis 异常等)会降级删除缓存并在日志留 warn,下一次查询回源,最坏 300 秒自愈;④ 仅 Redis 整体不可用时多实例的进程内缓存可能短暂不一致(各自最长 300 秒),该场景建议库存操作按 fail-safe(保守判定为锁定)处理。", "测试:test/app/service/systems/stock_check.test.js 调整/新增——审核后缓存已重建且查询命中(cached=true)、完成后重建缓存不包含该任务、取消后重建不包含该任务、空仓库集合缓存(首查回源/二次命中)、5 个并发未命中结果一致且均 cached=false、forceRefresh 强制回源;全量 252 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.staticLockList(cached 字段说明 + 缓存设计 notes + 本次策略答疑);根版本 0.3.313 → 0.3.314、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "代码依据:app/service/systems/stock_check.js#staticLockList/#_readStaticLockCache/#_loadStaticLockCache/#_queryStaticLockRows/#refreshStaticLockCache/#clearStaticLockCache。" ] }, { "version": "0.3.313", "date": "2026-10-28", "type": "updated", "summary": "库存盘点完成(stock.check.finish)立即释放静态盘点锁定:清除仓库级锁定缓存并返回 released_stock_ids(本任务覆盖的商品ID),同一商品若仍被其它静态任务覆盖则继续锁定。", "methods": [ "stock.check.finish" ], "notes": [ "需求:盘点完成时商品必须立刻解除锁定,不能等到缓存 TTL(300 秒)自然过期,否则完成后的出入库仍会被 staticLockList / isStockStaticLocked 判为锁定中。", "实现:finish 在状态置 completed 后调用 clearStaticLockCache(warehouseId) 删除 `stock_check:static_lock:{warehouseId}`(Redis 与进程内缓存同时清理,失败仅 warn 日志,靠 TTL 兜底);并在状态更新前用 _collectGoodsStockIds 记录本任务商品明细覆盖的 stock_id,随响应 released_stock_ids 返回、随操作日志 extras.releasedStockIds 落库,便于追溯「哪张单释放了哪些商品」。", "多任务叠加:锁定集合是「全部 approved/checking 静态任务的并集」,完成其中一张单只会移除该单贡献的商品;若商品仍被其它静态任务覆盖,缓存回源后依旧锁定(正确行为)。", "其它释放路径:cancel(取消)与 batchDelete(作废删除)同样会清除缓存;audit(approve/reject)清除缓存使锁定集合及时更新;report 仅 approved→checking 流转,不改变锁定集合、不失效。", "测试:test/app/service/systems/stock_check.test.js 新增「完成盘点立即释放锁定」用例——构造独有商品 → 审核通过后 isStockStaticLocked=true → finish 返回 released_stock_ids=[该商品] 且缓存已清 → isStockStaticLocked=false(回源);全量 251 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.finish(响应新增 released_stock_ids、notes 补充释放口径);根版本 0.3.312 → 0.3.313、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "代码依据:app/service/systems/stock_check.js#finish/#_collectGoodsStockIds/#clearStaticLockCache、app/service/systemMethods/stock/check.js#finish、app/extend/application.js#delCacheAsync。" ] }, { "version": "0.3.312", "date": "2026-10-28", "type": "updated", "summary": "库存盘点新增公共查询 stock.check.staticLockList(静态盘点锁定中的商品清单,按仓库缓存,供库存操作前置判断);stock.check.audit 审核通过时刷新商品明细账面快照(快照基准以「审核完成=开始盘点」时点为准)并返回 snapshot_refreshed,同时失效/进入静态锁定缓存。", "methods": [ "stock.check.staticLockList", "stock.check.audit", "stock.check.submit" ], "notes": [ "新增方法 stock.check.staticLockList:返回 is_static=1 且状态为 approved/checking 的任务所覆盖的商品 stock_id 集合(rows 附带来源任务ID/单号/库位编码),供出入库、移库、拣货等库存操作判断商品是否被静态盘点锁定;库位盘点任务 is_static 恒为 0,不参与锁定。", "锁定时机:审核完成(approved)即开始锁定、盘点作业中(checking)持续锁定;提交审核前不锁定;completed/cancelled/rejected 解锁。", "缓存:键 `stock_check:static_lock:{warehouseId}`,TTL 300 秒,走 app.setCacheAsync/getCacheAsync(Redis 优先、异常降级进程内缓存);audit/finish/cancel/batchDelete 主动失效;响应含 cached(是否命中)与 updated_at(缓存生成时间)。", "内部接口 isStockStaticLocked({ warehouseId, stockId }):读同一份缓存做单/多商品命中判断,返回 { locked, locked_stock_ids, rows, cached },供库存模块直接调用(systemMethods 层未暴露)。", "audit 刷新快照:approve 时把 scope_type=goods 明细行 system_quantity 刷新为该库位当前账面 SUM(available_quantity+locked_quantity)(仅统计启用存储,无记录按 0),覆盖「提交审核 → 审核完成」之间发生的出入库,保证账面基准=开始盘点时点;返回 snapshot_refreshed=本次刷新的明细行数(值无变化不计)。submit 的提交时刷新逻辑不变,两者叠加后以审核时点为准。", "测试:test/app/service/systems/stock_check.test.js 新增「staticLockList 静态盘点锁定商品(公共查询 + 缓存 + 审核刷新快照)」5 个用例——锁定口径(仅 approved/checking、submitted 与非静态任务不计入)、缓存命中与 audit/finish/cancel 主动失效、isStockStaticLocked 单商品判断与参数校验、审核刷新快照(提交后库存 +5,审核后快照等于审核时点账面,并回滚人为变更)、方法层仓库注入与 cached 透出;全量 250 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.staticLockList 一条(共 26 条),并更新 stock.check.audit(响应新增 snapshot_refreshed、notes 补充刷新口径与缓存失效)与 stock.check.submit(notes 补充审核再刷新说明);根版本 0.3.311 → 0.3.312、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位)。", "代码依据:app/service/systems/stock_check.js#staticLockList/#isStockStaticLocked/#clearStaticLockCache/#_refreshGoodsBookSnapshot/#audit、app/service/systemMethods/stock/check.js#staticLockList、app/extend/application.js#setCacheAsync/#getCacheAsync/#delCacheAsync。" ] }, { "version": "0.3.311", "date": "2026-10-28", "type": "updated", "summary": "库存盘点 is_static(是否静态盘点)口径收窄:仅商品盘点(type=store/goods)有效,按库位盘点(type=location)一律为 0(create 传入 1/true 也忽略),静态定式(pattern=static)仅商品类任务自动置 1。", "methods": [ "stock.check.create", "stock.check.patternCreate", "stock.check.list", "stock.check.detail" ], "notes": [ "口径说明:静态盘点针对「长期停收停发商品」,只对商品盘点(type=store/goods)有意义;库位盘点是按库位清点全部商品,不存在静态商品概念,因此 is_static 恒为 0,避免前端误把全仓库位盘点标成静态。", "create(本次修正):normalizedIsStatic = (type === 'location') ? 0 : (requested ? 1 : 0)——库位盘点即使传 is_static=1/true 也落库 0 且不报错(保持向后兼容、不新增 400);商品盘点沿用原归一化规则(true/'true'/1/'1' 记为 1,其余 0)。", "patternCreate(本次修正):is_static = (pattern.id === 'static' && pattern.type !== 'location') ? 1 : 0——静态定式为商品类(type=goods)恒为 1;库位类定式(empty_location)与其它商品定式(mis_shipment/expiring/warning)均为 0。", "响应口径:create/patternCreate 返回的 check、detail 的 check、list 的行对象均为 is_static(number,0|1);库位盘点任务读取时恒为 0。", "测试:test/app/service/systems/stock_check.test.js 的「is_static 静态标记」用例扩展——新增 type=location 传 is_static=1/true/'true' 均返回并落库 0 的断言;全量 245 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.create(is_static 参数说明补充「仅商品盘点有效」+响应字段文案+notes)、stock.check.patternCreate(静态定式口径+notes)、stock.check.list / stock.check.detail(返回口径 notes);根版本 0.3.310 → 0.3.311、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "代码依据:app/service/systems/stock_check.js#create/#patternCreate、app/service/systemMethods/stock/check.js#create、app/model/stock_check.js(is_static)。" ] }, { "version": "0.3.310", "date": "2026-10-28", "type": "updated", "summary": "库存盘点主表新增 is_static(是否静态盘点)标记:stock.check.create 支持入参 is_static(兼容 isStatic 驼峰与布尔/字符串写法),静态盘点定式(pattern=static)创建的任务自动置 1;stock.check.list / stock.check.detail / stock.check.patternCreate 返回该字段(0=普通盘点、1=静态盘点)。", "methods": [ "stock.check.create", "stock.check.list", "stock.check.detail", "stock.check.patternCreate" ], "notes": [ "需求背景:盘点任务需要区分「静态盘点」(针对长期停收停发商品的盘点)与普通盘点,原主表只有 type/mode/status,无法在列表/详情上识别任务来源与性质,静态定式创建的任务与手工任务混在一起。", "库表变更:database/migrations/20261028010000-add-is-static-to-stock-check.js 给 wms_stock_check 新增 is_static(TINYINT(1) NOT NULL DEFAULT 0,注释「是否静态盘点(1=静态盘点(静态定式创建或创建时开启),0=普通盘点)」,位于 store_id 之后);存量数据默认 0,无需回填;down 迁移删除该列。", "create 入参(新增):is_static 可选,纯标记——true / 'true' / 1 / '1' 记为 1,其余(含缺省、0、'false'、空串)记为 0;兼容 isStatic 驼峰写法;不参与模式强制(type=location 仍强制 blind)、状态机与差异计算;操作日志 STOCK_CHECK_CREATE 的 changeSummary/extras 追加静态标记。", "patternCreate(自动判定):pattern_id=static 的任务 is_static=1,其余定式(empty_location/mis_shipment/expiring/warning)为 0;日志同样带「静态盘点」字样。", "响应字段:create/detail/patternCreate 的 check(_formatCheckRow 口径)与 list 的行对象均返回 is_static(number,0|1);list 未新增 is_static 筛选条件。", "测试:test/app/service/systems/stock_check.test.js 新增「is_static 静态标记」用例(缺省 0、isStatic=1 落库 1、detail/list 返回、方法层 is_static/isStatic 透传、0/'false'/空串/false 记 0),并在 static/warning 定式用例中断言 1/0;全量 245 用例通过、ESLint 0 错误;迁移已在本地开发库执行(information_schema 校验列存在)。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.create(新增 is_static 参数 + 响应字段说明 + notes)、stock.check.list(rows 返回字段 + notes)、stock.check.detail(check 返回字段 + notes)、stock.check.patternCreate(静态定式自动置 1 + notes);根版本 0.3.309 → 0.3.310、updatedAt 2026-10-28;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "代码依据:app/model/stock_check.js(is_static 字段)、app/service/systems/stock_check.js#create/#patternCreate/#_formatCheckRow、app/service/systemMethods/stock/check.js#create、database/migrations/20261028010000-add-is-static-to-stock-check.js。" ] }, { "version": "0.3.309", "date": "2026-10-28", "type": "updated", "summary": "库存盘点作业数据商品视图改为按商品汇总:stock.check.workData(goods 视图)同商品多库位明细合并为一行且行级不再返回 detail_id;stock.check.workDataDetail 改为传 id + stock_id 返回 summary 汇总 + rows 按库位分行(明细ID/库位ID/账面快照/实盘/差异);stock.check.report 的 detail_id 改为可选,缺失时按 id + stock_id + space_id 反查明细。", "methods": [ "stock.check.workData", "stock.check.workDataDetail", "stock.check.report" ], "notes": [ "问题现象:goods 视图同一 stock_id 出现多条 detail_id(如盘点单里 stock_id=143270 出现 5 行、160240 出现 2 行),各行商品信息与 locations 库位列表完全相同,但行级 system_quantity/checked_quantity 只反映其中一条库位明细(该明细下作业记录),前端无法区分行间差异,跨行求和还会重复计数。", "根因:商品盘点明细按「商品+库位」拆行落库(wms_stock_check_detail 唯一键 uk_check_stock_location = check_id+stock_id+location_id,addDetail 为该商品每个启用库存库位生成一行,system_quantity 为对应库位账面快照),而 _buildGoodsWorkRows 原以明细行为列表输出;locations 却按 stock_id 整商品计算,导致同商品多行内容高度重复而数量各管一个库位。", "workData(goods 视图)改造:app/service/systems/stock_check.js#_buildGoodsWorkRows 先按 stock_id 分组(分组顺序沿用明细 id 升序,stock_id 为空/异常的明细行各自成行),再按组合并输出——行级 system_quantity=各库位明细行 system_quantity 之和、作业记录跨该商品全部明细合并后按库位编码聚合、checked_quantity/diff_quantity/is_diff 按合并后合计计算(无作业记录时差异仍恒 0);行级不再返回 detail_id/detail_ids(汇总行无单一明细语义),改为 locations 每项返回 detail_id(该库位盘点明细ID,供逐库位上报/删除)与 snapshot_quantity(该库位账面快照,明盘)。", "workDataDetail 改造:商品分支入参改为 id(盘点任务ID)+ stock_id(商品库存ID,兼容 stockId),返回 { check_id, stock_id, 商品信息, summary, rows }——summary 为商品级 system_quantity(账面快照合计)/checked_quantity(实盘合计)/diff_quantity/is_diff;rows 每个库位一行,含 detail_id、location_id 与同义 space_id(可直接回传 report)、location_code、system_quantity(该库位当前账面=可用+锁定)、locked_quantity、snapshot_quantity(该库位账面快照)、checked_quantity(该库位实盘)、diff_quantity(实盘-快照)与 checked_at/checker_name/record_ids/images;盲盘不返回 summary 与任何数量字段;库位明细(detail_id 指向 scope_type=location 行)分支与原返回结构不变;传商品范围 detail_id 仍可用(服务端按明细商品解析 id + stock_id)。", "report 兼容改造:detail_id 改为可选——未传时按 id + stock_id + space_id 反查明细(先命中 location_id=space_id 的该商品明细,未命中取该商品任一明细),反查不到报 400「盘点明细不存在(该商品不在本任务盘点范围内,或库位盘点任务需传 detail_id)」;既无 detail_id 也无 stock_id 仍报 400「盘点明细ID不能为空」;落库与覆盖式查重口径不变(作业记录仍挂 detail_id)。", "响应兼容性(破坏性提示):① workData goods 视图行不再返回 detail_id/detail_ids,按明细操作(detailDelete 等)需改用 locations[].detail_id 或 workDataDetail rows[].detail_id;② workDataDetail 商品分支返回结构由「goods 视图单行」变为「summary + rows」钻取结构,旧前端读取 locations/checked_quantity 的代码需改读 summary/rows;③ 商品任务 workData goods 视图 total/rows 由「库位明细行数」变为「商品行数」(与主表 total_items 按商品计数一致)。", "测试:test/app/service/systems/stock_check.test.js 新增/改写——「goods 视图多库位商品按商品汇总为一行」(两库位分别上报后断言 total=1、行级快照合计、跨明细合并实盘与 record_ids、locations 带 detail_id/snapshot_quantity)、「workDataDetail 商品钻取(summary + rows,含库位ID/明细ID/账面快照/实盘/差异)」「商品钻取盲盘不返回数量字段」「report 不传 detail_id 按 id + stock_id + space_id 反查上报」「方法层 stock_id/stockId/detail_id 兼容」;全量 244 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.workData(description/response.rows/notes 的商品视图口径与 locations 新字段)、stock.check.workDataDetail(params 改为 id/stock_id/detail_id 三选、description/response.data/notes 改为 summary+rows 钻取结构)、stock.check.report(detail_id 必填改可选 + stock_id 反查说明);根版本 0.3.308 → 0.3.309、updatedAt 2026-10-27 → 2026-10-28;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "代码依据:app/service/systems/stock_check.js#_buildGoodsWorkRows/#workData/#workDataDetail/#_formatGoodsWorkDetail/#report、app/service/systemMethods/stock/check.js#workData/#workDataDetail/#report、app/model/stock_check_detail.js(uk_check_stock_location)。" ] }, { "version": "0.3.308", "date": "2026-10-27", "type": "updated", "summary": "库存盘点移除范围类型 all(与 location 语义重复):全盘能力(未传库位时自动拉取全仓库启用库位)并入 location,type 缺省值改为 location,create 传 all 返回 400;存量 type=all 任务由迁移收敛(商品行任务改 goods、库位行/空任务改 location 并归一盲盘)。", "methods": [ "stock.check.create", "stock.check.list", "stock.check.addDetail", "stock.check.workData", "stock.check.markEmpty", "stock.check.recheckClearLocation" ], "notes": [ "动机:type=all 与 type=location 语义完全重复——两者都按库位盘点、明细都是 scope_type=location、mode 都被强制 blind;all 唯一的额外能力「添加明细时未传库位自动拉取全仓库启用库位」已合并进 location,all 因此下线。", "create:type 仅允许 store/goods/location,缺省由 all 改为 location;传 all 返回 400「盘点范围类型不合法,仅支持 store/goods/location」。mode 规则不变——location 一律盲盘(忽略传入),store/goods 按传入值(缺省明盘)。", "addDetail:type=location 未传 locations 且未传 location_ids 时自动拉取当前仓库全部启用且有效库位(排除无头库位)生成库位行(原 all 全盘语义);type=all 的历史任务不再走「已有商品明细行则按商品模式」兼容分支,直接返回 400「盘点范围类型不合法(all)」。", "存量数据:database/migrations/20261027010000-merge-stock-check-type-all-into-location.js 将明细含商品行(scope_type=goods,2026-09-30 改造前的全仓按商品口径)的 type=all 任务改为 type=goods(mode 保持原值),其余(明细为库位行或无明细的空任务)改为 type=location 并归一 mode=blind;wms_stock_check.type 列默认值改为 location、注释去掉 all。", "影响面:前端传 type=all 的创建调用将收到 400,需改为 location(需要全盘时创建 location 任务后调用 addDetail 不传库位即可)。workData/markEmpty/recheckClearLocation 等按库位判定的接口仍只认 type=location(历史 all 任务经迁移后即为 location)。", "测试:test/app/service/systems/stock_check.test.js 改为 location 口径——新增「type=all 创建报 400」「历史 type=all 任务添加明细报 400」用例;原「type=all 缺省库位自动全仓」用例改由 type=location 承接;移除 type=all 历史商品明细兼容用例。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.create/list/addDetail/workData/markEmpty/recheckClearLocation(type 语义、mode 规则、全盘自动范围、错误文案);根版本 0.3.307 → 0.3.308、updatedAt 2026-10-27;methods/changes/system.json 新增本条(插入数组首位);未改动其它分组。", "破坏性提示:type=all 不再是合法入参(400);依赖「all 缺省自动全仓」的调用改为 location 即可,行为一致。", "代码依据:app/service/systems/stock_check.js#create/#addDetail/#workData/#markEmpty/#recheckClearLocation、app/service/systemMethods/stock/check.js、app/model/stock_check.js、database/migrations/20261027010000-merge-stock-check-type-all-into-location.js。" ] }, { "version": "0.3.307", "date": "2026-10-25", "type": "updated", "summary": "库存盘点上报(stock.check.report)改为 space_id 必传:库位一律按库位ID落库、不再按编码猜库位(修复同仓库同编码重复库位导致作业记录挂到无头脏库位);实盘数量上限 2147483647 返回 400;取回接口补充 space_id/location_id 字段供回传;操作日志 message/before_changes 补充库位编码与库位ID。", "methods": [ "stock.check.report", "stock.check.workData" ], "notes": [ "问题现象:生产盘点单 PD20261025000001 的 stock.check.workData space 视图出现 custom_name/custom_barcode 为 null 的库位行(如 E02-06-01-01)。根因:wms_location_space 存在大量同仓库同编码重复库位(uk_warehouse_space_code 含 deleted_at,NULL 不去重导致重复插入不受约束),其中大量库位所属 zone 已删除(无头库位);report 旧逻辑只按 warehouse_id + space_code 做 findOne,命中最小的历史行,导致作业记录挂到脏库位,space 视图再按记录库位补行时又未做分区有效性过滤。", "取回侧字段(本次补齐):workData/workDataSpaceDetails 的 space 视图行新增 space_id 与 location_id(与既有 id 同值);goods 视图 locations[] 新增 space_id 与 location_id(取分区有效库位行,同编码多条取拣货顺序第一条,已盘但无库存的库位按编码补查有效库位)。location 视图/recordList/result 的 location_id 保持不变。", "report 写库(本次修正为强制):space_id 必传(兼容 spaceId/location_id/locationId 写法,取回接口 rows[].space_id、rows[].id、locations[].space_id 可直接回传);服务端校验属于本仓库且 zone 存在未删除,缺失/非法返回 400「缺少库位ID(space_id)」,不存在/跨仓库/分区已删除返回 400;库位编码以 space_id 对应库位行为准,location 入参降级为可选一致性校验(不一致 400),服务端不再按编码匹配/猜库位;库位明细行还要求 space_id 对应编码等于明细库位编码。", "report 校验:实盘数量新增上限 2147483647(wms_stock_check_record.quantity 为 int(12)),超限返回 400「实盘数量不能超过 2147483647」;此前超限直接落库抛 Out of range 变 500(生产今日 10 次)。", "workData space 视图:记录库位归一(上报编码与明细编码一致归并到明细固化 location_id;记录指向无头库位时归并到同编码有效库位),库位商品明细改按「库位+商品」索引、作业记录改按「库位+商品」聚合,避免跨库位上报时同一编码出现两行或实盘数落到别的行。", "操作日志:STOCK_CHECK_REPORT 的 message 追加库位编码与库位ID;before_changes 落 check_no/detail_id/scope_type/stock_id/location_code/location_id/detail_location_code/detail_location_id/quantity/barcode/is_unknown_goods/is_empty/mode/record_id 快照(原 changeSummary 参数在 operationLog.buildOperationLogData 中未落库,日志里查不到库位信息)。", "问题定位依据(只读核查):生产 wms-api.log 中 244 条 stock.check.report 请求 body 键仅 id/detail_id/quantity/location/stock_id,无 space_id;detail 6151 于 2026-10-25 22:55:36 上报 location=E02-06-01-01(明细库位为 E02-06-02-01),落库 location_id=13768(zone 59 已删除);有效行为 22093(E1区02-06-01/00224214)。", "测试:test/app/service/systems/stock_check.test.js 升级为 space_id 必传口径——新增/改写用例覆盖「同编码重复库位不产生幽灵行」「space_id 必传与缺失/非法/跨仓库/无头/编码不一致 400」「数量超限 400 且不落库」「操作日志含库位信息」「space 视图行 space_id=id」「goods 视图 locations[] 含 space_id」,全量 244 通过。", "文档变更范围:methods/system.json 的 stock.check.report(space_id 必填参数、location 降级为一致性校验、quantity 上限)、stock.check.workData / stock.check.workDataSpaceDetails(space 视图行含 id/space_id/location_id、goods locations[] 含 space_id)+根版本 0.3.306 → 0.3.307、updatedAt 2026-10-25;methods/changes/system.json 新增本条(插入数组首位)。", "破坏性提示:旧调用方(未传 space_id)将收到 400「缺少库位ID(space_id)」,前端需改为回传取回接口返回的 space_id;「无库位上报」通道随之取消(历史 location_code='' 记录仍按既有口径展示/导出为空)。", "代码依据:app/service/systems/stock_check.js#_resolveLocationIdByCode/#report/#_buildSpaceWorkRows、app/service/systemMethods/stock/check.js#report。" ] }, { "version": "0.3.306", "date": "2026-10-25", "type": "added", "summary": "用户账号能力增强:user.getAccountInfo 返回新增 is_custom_password;新增 user.updateUsername(服务端重名校验并排除自己)与 user.changePassword(首次自定义密码可免旧密码,修改后置 is_custom_password=1,再次修改必须校验旧密码)。", "methods": [ "user.getAccountInfo", "user.updateUsername", "user.changePassword" ], "notes": [ "user.getAccountInfo:返回字段白名单新增 is_custom_password(是否自定义密码:0-否,1-是),仍不返回 password_hash、salt、last_login_ip。", "user.updateUsername:新增方法,仅修改当前登录账号;username 必填,长度3-50且仅允许字母/数字/下划线;服务端查询 username 重名时排除自己(id != 当前账号),重名返回 409;用户名未变化直接返回成功;更新后清理用户缓存,并同步当前请求上下文 username。", "user.changePassword:新增方法,入参 new_password 必填(兼容 newPassword),old_password 兼容 oldPassword;is_custom_password=0 时旧密码可不传,is_custom_password=1 时必须传且校验通过;修改时重新生成 salt 与 password_hash,并将 is_custom_password 置为1;方法已加入 _noNeedLog,避免请求体中的明文密码写入操作日志。", "错误码:updateUsername 400(参数/格式)/401(未登录)/404(账号不存在)/409(用户名已存在);changePassword 400(新密码为空、请输入旧密码、旧密码错误)/401/404;数据库异常返回 code=0。", "数据库:依赖迁移 20261025135000-add-is-custom-password-to-wms-account.js(wms_account.is_custom_password TINYINT(1) NOT NULL DEFAULT 0),开发库与生产库均已执行。", "测试:test/app/service/systemMethods/user.getAccountInfo.test.js(5)、user.updateUsername.test.js(7)、user.changePassword.test.js(8),合计 20 通过。", "文档变更范围:methods/system.json 的 user.getAccountInfo(response 新增 is_custom_password)、user.updateUsername(新增)、user.changePassword(新增)+根版本 0.3.305 → 0.3.306、updatedAt 2026-10-25;方法文档已写入开发库 wms_api_method_doc 并重新导出;methods/changes/system.json 新增本条(插入数组首位)。", "代码依据:app/service/systemMethods/user.js#updateUsername/#changePassword、app/service/systems/auth/user.js#updateUsername/#changePassword、app/service/systems/auth/user.js#getAccountInfo。" ] }, { "version": "0.3.305", "date": "2026-10-25", "type": "added", "summary": "新增 user.getAccountInfo:仅返回当前登录账号在 wms_account 的账号级信息,不返回 password_hash、salt、last_login_ip 等敏感字段。", "methods": [ "user.getAccountInfo" ], "notes": [ "方法层:app/service/systemMethods/user.js 新增 getAccountInfo(data),未加入 _noNeedLogin(需登录),加入 _noNeedLog(只读接口不写操作日志),统一 this.success('获取账号信息成功', result) 包装;不接收账号ID,避免越权查询。", "系统层:app/service/systems/auth/user.js 新增 getAccountInfo(),账号ID取自 ctx.userId / ctx.user.id;使用 attributes 白名单(id/username/real_name/phone/email/status/last_login_at/created_at/updated_at)查询 wms_account,raw=true,显式排除 password_hash、salt、last_login_ip。", "错误码:未登录或登录已过期返回 401;账号不存在返回 404;查询异常返回 code=0。", "测试:test/app/service/systemMethods/user.getAccountInfo.test.js(5 通过,覆盖方法层透传/失败码、登录账号过滤与敏感字段白名单、未登录 401、账号不存在 404)。", "文档变更范围:methods/system.json 的 user.getAccountInfo 一条(新增)+根版本 0.3.304 → 0.3.305、updatedAt 2026-10-25;methods/changes/system.json 新增本条(插入数组首位)。", "代码依据:app/service/systemMethods/user.js#getAccountInfo、app/service/systems/auth/user.js#getAccountInfo。" ] }, { "version": "0.3.304", "date": "2026-10-23", "type": "updated", "summary": "pick.waveClaimScan 领料跳过拦截单改为按打印状态区分:已打印(print_status=fin)的拦截订单面单实物已流出,不再受拦截影响、照常置为已领料;仅未打印的拦截订单跳过领料(0.3.303 → 0.3.304)", "methods": [ "pick.waveClaimScan", "pick.query", "order.wave.confirmPrintUnclaimedWaveCount" ], "notes": [ "变更内容一(领料口径):waveClaimScan 计算待领料订单时,拦截订单由「整体跳过」改为「仅未打印(print_status != fin)的拦截订单跳过」;已打印(print_status=fin)的拦截订单纳入领料范围并写 ORDER_WAVE_CLAIM 日志,响应新增 intercept_skipped_order_count(因拦截且未打印跳过领料的订单数)与 claimed_intercepted_order_count(本次/本人已领的已打印拦截订单数);getWaveClaimGateStats(pick.query 领料门禁)同步按该口径统计,已打印的拦截订单未领料时阻隔建拣货任务。", "变更内容二(领料时间补写):waveClaimScan 命中 already_claimed 幂等分支时,若波次表 claim_time 为空则补写 claim_time + claim_operator 并递增统计版本号;旧逻辑下「整波订单均被拦截跳过」或历史领单发生在 claim_time 字段之前时,波次表永远没有领料时间,order.wave.confirmPrintUnclaimedWaveCount(以 wb.claim_time IS NULL 判定未领单)会长期显示该波次「已打印未领单」,且重复扫描领料只返回 already_claimed 无法自愈。", "背景:生产订单 1314391 所在波次已确认打印后被写入拦截,操作员扫描面单领料时该订单被拦截逻辑跳过、未置为已领料,但面单实物已打印并被领走;打印与领料之间不存在拦截出库流程,已打印订单不应再受拦截影响。同一波次在「确认打印未领单」统计中一直显示为 1,需重新扫描后自愈。", "代码依据:app/service/systemMethods/pick.js#waveClaimScan(新增 interceptClaimSkippedOrderIds,unclaimed/ownClaimed 与响应统计按新口径;already_claimed 分支调用 backfillWaveClaimTime 并复用 bumpConfirmPrintUnclaimedWaveVersionSafe)、#backfillWaveClaimTime、#bumpConfirmPrintUnclaimedWaveVersionSafe、#getWaveClaimGateStats(查询补 print_status,仅未打印拦截订单免领料);新增单测 test/app/service/systemMethods/pick.waveClaimScan.test.js(WC1~WC5,5 通过)。", "验证:npx egg-bin test test/app/service/systemMethods/pick.waveClaimScan.test.js 5 通过;ESLint 0 错误;pick.query.test.js / pick.createWavePickTask.test.js 的失败为改动前既有失败(stash 基线同样失败)。", "存量处理:受影响波次重新扫一次波次内已打印面单号即可自动补领料与 claim_time;若订单已迁出待处理订单表,需按仓库分表人工订正 claim_status/claim_time。", "文档变更范围:methods/system.json 的 pick.waveClaimScan(description、intercepted_order_count、新增 intercept_skipped_order_count / claimed_intercepted_order_count)、pick.query(description、400 错误说明)与 order.wave.confirmPrintUnclaimedWaveCount(description 补补写说明);根版本 0.3.303 → 0.3.304、updatedAt 2026-10-23;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "2026.10.21-order-delivery-summary", "date": "2026-10-21", "type": "added", "summary": "新增 order.deliveryOrder.summary(配送订单每日汇总):以自然日为维度统计每日订单量、迁入配送表订单量、发货量(订单数/商品件数/金额)、拦截数量、库内确定拦截数量与取消数量,默认最近 7 天、最多 90 天,缺失日期补 0;仓库取自登录上下文,可选 store_id 过滤。", "methods": [ "order.deliveryOrder.summary" ], "notes": [ "方法层:app/service/systemMethods/order/deliveryOrder.js 新增 summary(data),加入 _noNeedRight/_noNeedLog/_noNeedAuth(只读接口,与 list/quickSearch 同口径),统一 this.success('ok', result) 包装;参数兼容 start_date/startDate/start_time、end_date/endDate/end_time、store_id/storeId", "系统层:新增 app/service/systems/deliveryOrderSummary.js(queryDailySummary/queryDailyCount/queryDailyShipped),同时查订单常用表与配送表分表(getCurrentModel + getDispatchModel),归档 history 与委托外仓 outsourced 不参与;日期分组用 CONVERT_TZ(字段, Sequelize 时区, 服务器本地时区) 后取 DATE,保证自然日与本地时区一致", "纯函数:新增 app/lib/delivery_order_summary.js(区间解析/日期展开/聚合合并,无 egg 依赖),单次区间上限 90 天,缺省 7 天", "指标口径:order_count=create_at(排除 cancel);dispatch_count=配送表 dispath_time;shipped_count/shipped_items_total/shipped_amount=delivery_time(排除 cancel);intercepted_count=intercept_time 且 intercept_status != none;intercepted_at_warehouse_count=配送表 dispath_time 且 intercept_status=intercepted_at_warehouse(与 report interceptOrder 口径一致);cancelled_count=updated_at 且 status=cancel(取消操作会刷新 updated_at)", "测试:test/app/service/systemMethods/order/deliveryOrder.summary.test.js(聚合与参数映射 6 例)、test/delivery_order_summary.cjs(区间与合并纯函数 10 例)", "文档变更范围:methods/system.json 的 order.deliveryOrder.summary 一条(新增)+根版本 0.3.302 → 0.3.303、updatedAt 2026-10-21;methods/changes/system.json 新增本条(插入数组首位)" ] }, { "version": "2026.10.17-returnUnpack.transferByOrders", "date": "2026-10-17", "type": "added", "summary": "新增退回拆包接口 returnUnpack.transferByOrders(配送订单批量转退回拆包单):入参 ids 为订单表主键数组(去重后上限 200),仅允许库内拦截订单转换;已有拆包单/非库内拦截/无运单号/无明细的订单静默跳过;每单新建拆包单并 1:1 复制订单明细(product_status=normal),返回成功/跳过/失败明细。新增权限 643(API:配送订单批量转退回拆包单,授权角色 27/26)。", "methods": [ "returnUnpack.transferByOrders" ], "notes": [ "方法层:app/service/systemMethods/returnUnpack.js 新增 transferByOrders(data)(位于 transferByWaybills 之后),统一 this.success('ok', data) 包装,未加入 _noNeedRight/_noNeedLogin/_noNeedLog/_noNeedAuth 免检清单(isNeedAuth=true、isNeedLogin=true)", "系统层:app/service/systems/return_unpack.js 新增 transferByOrders / _isWarehouseInterceptedOrderStatus / _loadOrdersForTransferByOrders / _loadOrderItemsForTransferByOrders / _parseOrderItemsJson / _resolveOrderExpressForTransferByOrders;复用 _insertMainWithRetry / _buildTransferDetailRows / _recalcMain / _resolveStoreRemark / _resolveReturnReceivedId", "转换限制(用户确认):仅允许库内拦截(intercept_status=intercepted_at_warehouse,兼容 intercepted)的订单;非库内拦截订单跳过;已有拆包单(同订单或同运单号 status != 'cancelled')跳过;静默跳过,完成几个算几个", "拆包单:status=unpacking、detail_status 按明细识别率回填;明细 product_status 固定 normal;waybill_code 取订单主运单号,无运单回退 delivery_order_code", "权限:迁移 20261017100000-add-return-unpack-transfer-orders-permission.js,固定 ID 643(角色 27/26),开发库已执行(641/642 已被外部仓库小程序页面占用)", "文档变更范围:methods/system.json 的 returnUnpack.transferByOrders 一条(新增)+根版本 0.3.301 → 0.3.302、updatedAt 2026-10-17;methods/changes/system.json 新增本条(插入数组首位)" ] }, { "version": "0.3.301", "date": "2026-10-16", "type": "updated", "summary": "自动出库「不出库当天订单」支持跨天放行:放行时间放开到 00:00~47:59(27:00 = 次日 03:00),限制窗口改为按订单复核时间所在日计算", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "语义变更(原实现按「当前日」计算窗口,跨天时会提前放行,且放行时间只支持 00:00~23:59):新口径按**订单复核时间所在北京日 D**计算 —— recheck_time < D + 允许当天出库最后时间 的订单不受影响;recheck_time ≥ D + 最后时间 的订单在 now < D + 放行时间 前不出库,到达后放行。", "字段范围:same_day_outbound_release_time 放开到 00:00~47:59(24:00 之后的数字表示次日,例如 27:00 = 次日 03:00;48:00 等超限值回退默认 22:00);same_day_outbound_deadline_time 仍限当天内 00:00~23:59。", "典型配置:① 当天复核的订单当天不出、过零点出库 → deadline=00:00 + release=23:59;② 到次日 03:00 才出库 → deadline=00:00 + release=27:00;③ 当天 20:00 后复核的次日 05:00 放行 → deadline=20:00 + release=29:00。", "recheck_time 为 NULL 的订单仍不受该限制(既有口径);字段名 same_day_outbound_release_time 未变,仅中文名与语义说明调整(getFieldMeta 中显示名改为「放行时间」)。", "验证:本地隔离测试仓真实库走查 12 个场景全通过(含 S6a 当天/ S6b 次日 02:00 未放行 / S6c 次日 04:00 放行 / S6d 次日复核仍受限),脚本 test/auto_outbound_local_test_warehouse.cjs;单测 30 例通过(含跨天窗口补集断言)。", "文档变更范围:methods/system.json 的 setting.warehouse.getSettings 响应、setting.warehouse.saveSettings 入参中 exclude_same_day_outbound / same_day_outbound_deadline_time / same_day_outbound_release_time 三条描述 + method 描述;根版本 0.3.300 → 0.3.301、updatedAt 2026-10-16;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.300", "date": "2026-10-16", "type": "updated", "summary": "自动出库当天限制的时间口径补充:时间字段仅支持 00:00~23:59(不支持 24:00),「当天不出库、过零点全部出库」用 deadline=00:00 + release=23:59", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "背景:业务希望「未打包订单当天不出库,过了零点(24:00)后全部出库」。现有 same_day_outbound_deadline_time / same_day_outbound_release_time 只支持 HH:mm 且范围 00:00~23:59,写 24:00 会被回退成默认值。", "推荐配置:exclude_same_day_outbound=true + same_day_outbound_deadline_time=00:00 + same_day_outbound_release_time=23:59 —— 当天 00:00 之后复核的订单全天不出库,到达 23:59 后(含次日凌晨,cutoff 前移到次日 00:00 使前一日复核订单自动放行)全部出库。", "附带说明:recheck_time 为 NULL 的订单不受该限制(既有口径);已打包等其它规则若关闭 exclude_same_day_outbound 则不受影响。", "本地真实库走查(隔离临时仓 990001,8 个场景全通过):S1/S2 当天限制与放开时刻、S3 deadline 06:00→03:00 边界、S4a/S4b release 06:00 前后、S5a/S5b/S5c deadline=00:00+release=23:59 的当天/23:59/次日三个时点。测试脚本 test/auto_outbound_local_test_warehouse.cjs(不入库)。", "文档变更范围:methods/system.json 的 setting.warehouse.getSettings 响应、setting.warehouse.saveSettings 入参两条字段描述 + method 描述;根版本 0.3.299 → 0.3.300、updatedAt 2026-10-16;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.299", "date": "2026-10-16", "type": "updated", "summary": "仓库设置自动出库配置重构:开关拆分为 auto_outbound_enabled,auto_outbound_rules 改为规则数组(仅校验打包/称重/同步,任一命中即出库,固定要求已复核),移除复核/打印/拣货校验", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.getFieldMeta", "setting.warehouse.saveSettings" ], "notes": [ "变更内容:subject_config 新增 auto_outbound_enabled(flag,默认 false);auto_outbound_rules 由对象改为数组,每项字段为 require_pack/require_weigh/require_sync/exclude_same_day_outbound/same_day_outbound_deadline_time/same_day_outbound_release_time,规则内条件 AND、规则间 OR(任一命中即出库),空数组表示不出库任何订单。", "固定前置条件:所有规则均要求已复核(recheck_status=fin)与已分配储位(storage_status=fin),未复核订单一律不自动出库;不再校验已打印(print_status)与已拣货(pick_status)。", "不兼容变更:旧对象结构(含 enabled/require_recheck/require_print/require_pick)一律按默认(关闭 + 空规则)处理,需重新配置;saveSettings 保存非数组时返回 400(不静默重置)。", "处理范围:自动出库配置以仓库为单位生效(wms_store.id 即 warehouse_id),仅扫描该仓库自身订单,不再扩展到货主签约的外部合同仓。", "出库操作日志:自动出库成功更新后按订单写入 wms_operation_log(business_type=order,operation_code=ORDER_AUTO_OUTBOUND,operator=系统,message 形如「自动出库(命中规则1:需已打包、需已称重)」);写日志失败仅告警不影响出库。", "代码依据:app/model/store.js(默认值与 normalizeAutoOutboundRules)、app/service/systems/order_auto_outbound.js(getEnabledAutoOutboundWarehouses/isAutoOutboundEnabled/resolveAutoOutboundRules/buildAutoOutboundWhere/findAutoOutboundOrderIds/processWarehouseAutoOutbound/writeAutoOutboundOperationLogs)、app/service/systemMethods/outbound.js、app/service/systems/setting/warehouse.js(WAREHOUSE_SETTING_FIELDS + saveSettings 数组校验)、app/dict/businessDict.js(ORDER_AUTO_OUTBOUND)。", "验证:单测 test/auto_outbound_rules_v2.test.cjs(23 用例通过,含配置归一化/条件拼装/多规则命中去重/操作日志/字段元信息/保存校验);ESLint 0 错误。", "文档变更范围:methods/system.json 的 setting.warehouse.getSettings 响应、setting.warehouse.getFieldMeta、setting.warehouse.saveSettings 入参三处;根版本 0.3.298 → 0.3.299、updatedAt 2026-10-16;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.298", "date": "2026-10-14", "type": "added", "summary": "小程序用户须知增加系统默认版本:首次授权时自动写入作为第一版(0.3.297 → 0.3.298)", "methods": [ "wechat.getUserAgreementText" ], "notes": [ "变更内容:wms_wechat_agreement_version 新增系统级种子行 appid='system'(系统默认须知模板,迁移 20261014100000 开发+生产执行);首次授权的小程序(handleAuthCallback 与 authorized/updateauthorized 事件的 create 分支)自动复制该内容为第一版(systems/wechat.js#ensureDefaultAgreementVersion,幂等:已有任意版本则跳过)。", "系统默认内容可在 wms_wechat_agreement_version 中 appid='system' 的行直接修改(后续授权的小程序复制新内容);已授权但无版本的小程序不会自动回填(如需回填另行处理)。", "代码依据:app/service/systems/wechat.js 新增 SYSTEM_AGREEMENT_APPID 常量与 ensureDefaultAgreementVersion;app/controller/wechatOpen.js 两处 create 分支调用。", "文档变更范围:methods/system.json 的 wechat.getUserAgreementText 一条(description 补系统默认版本说明);根版本 0.3.297 → 0.3.298、updatedAt 2026-10-14;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.297", "date": "2026-10-14", "type": "updated", "summary": "wechat.getTemplateList 移除 Redis 缓存,改为每次实时拉取微信(0.3.296 → 0.3.297)", "methods": [ "wechat.getTemplateList" ], "notes": [ "变更内容:移除 wechat:template:list:normal 的 Redis 缓存读写(cacheGet/cacheSet),每次调用直接 GET wxa/gettemplatelist 实时拉取;响应移除 from_cache 字段。", "背景:模板缓存 24h → 5 分钟仍反复遇到旧列表问题,用户要求彻底移除缓存。", "代码依据:app/service/systems/wechat.js#getTemplateList 移除 CACHE_KEY/CACHE_TTL_SECONDS 与缓存分支;systemMethods/wechat.js JSDoc 同步。", "文档变更范围:methods/system.json 的 wechat.getTemplateList 一条(description 改实时拉取、response 移除 from_cache);根版本 0.3.296 → 0.3.297、updatedAt 2026-10-14;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.296", "date": "2026-10-13", "type": "updated", "summary": "wechat.getTemplateList 模板缓存 TTL 24h → 5 分钟(0.3.295 → 0.3.296)", "methods": [ "wechat.getTemplateList" ], "notes": [ "变更内容:模板列表 Redis 缓存 TTL 由 24 小时(24*3600)改为 5 分钟(5*60),模板更新后最多 5 分钟即可在列表接口看到最新模板。", "背景:2026-10-13 生产模板库变更后列表仍命中旧缓存,用户要求缩短缓存时间。", "代码依据:app/service/systems/wechat.js#getTemplateList CACHE_TTL_SECONDS 24*3600 → 5*60;JSDoc 同步;systemMethods/wechat.js JSDoc 同步。", "文档变更范围:methods/system.json 的 wechat.getTemplateList 一条(description 缓存 24h → 5 分钟);根版本 0.3.295 → 0.3.296、updatedAt 2026-10-13;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.295", "date": "2026-10-13", "type": "fixed", "summary": "wechat.commit 模板 ID 校验放开 0:普通模板库模板 ID 从 0 开始(0.3.294 → 0.3.295)", "methods": [ "wechat.commit" ], "notes": [ "变更内容:template_id 校验由「正整数(>0)」改为「非负整数(≥0)」,错误提示同步改为「template_id 必须为非负整数」;普通模板库第一个模板的 template_id 为 0(微信官方 wxa/commit 请求示例即 \"template_id\": \"0\"),此前模板库唯一模板 template_id=0 无法提交。", "背景:2026-10-13 生产模板库仅一个模板(template_id=0),调用 wechat.commit 被本服务校验拦截。", "代码依据:app/service/systems/wechat.js#commit 校验条件 <=0 → <0;本地未新增测试(0 的边界由现有 list.find 匹配覆盖),ESLint 0 错误。", "文档变更范围:methods/system.json 的 wechat.commit 一条(params.template_id.description 补 0 合法说明、errors 补非负整数校验提示);根版本 0.3.294 → 0.3.295、updatedAt 2026-10-13;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.294", "date": "2026-10-13", "type": "updated", "summary": "pick.wavePickTaskComplete 跳过拦截单时区分打印状态:已打印面单的拦截订单不再自动移出波次(0.3.293 → 0.3.294)", "methods": [ "pick.wavePickTaskComplete" ], "notes": [ "变更内容:拣货提交时被跳过的拦截订单中,仅未打印(print_status=none/空)的自动移出波次(原逻辑不区分打印状态,已打印面单的拦截订单也被移出,导致面单实物与波次记录分离);已打印(print_status!=none)的拦截订单保持不动(保留波次与任务订单关联,写 warn 日志提示,需人工 wave.batchRemoveOrders 处理),与复核链路 removeUnprintedInterceptedOrdersFromWave 的原则对齐。响应新增 kept_intercepted_order_ids(保持不动的拦截订单ID列表),skipped_intercepted_orders 明细新增 print_status 字段。", "背景:生产日志 2026-09-29 11:24:22 订单 839153 面单已打印、拣货员拿面单拣货时货主发起拦截,提交拣货后被自动移出波次 B2026092900050,面单与波次记录分离。", "代码依据:app/service/systems/pick.js#wavePickTaskComplete(拦截检查查询补 print_status、移出波次分支过滤已打印、新增 kept_intercepted_order_ids);本地单测新增 IC1/IC2/IC3 用例验证(test/ 目录不入库),31 通过 0 失败;ESLint 0 错误。", "文档变更范围:methods/system.json 的 pick.wavePickTaskComplete 一条(description 补打印状态区分说明、response 补 4 个字段);根版本 0.3.293 → 0.3.294、updatedAt 2026-10-13;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.293", "date": "2026-10-12", "type": "updated", "summary": "index.getWarehousePanelData scatterPacking 移除 wave 波次数(散单无波次语义)(0.3.292 → 0.3.293)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:scatterPacking(散单打包块)的 summary 与 top 各项移除 wave 字段(散单无波次语义),仅团购块 groupPacking 保留 wave(波次数);orders/goods/sku/top 结构不变。", "代码依据:app/service/systems/warehouse_panel.js#queryPackingBlock(isGroup 时才输出 wave);ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData 一条(response.data.description 补散单块无 wave);根版本 0.3.292 → 0.3.293、updatedAt 保持 2026-10-12;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.292", "date": "2026-10-12", "type": "updated", "summary": "index.getWarehousePanelData 新增面板刷新公共方法 touchLastChangeAt(warehouseId),并接入拣货完成/复核完成/打包完成路径(0.3.291 → 0.3.292)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:WarehousePanelService 新增公共方法 touchLastChangeAt(warehouseId)——更新对应仓库面板缓存键的最后更新时间戳(只写时间戳整值替换、TTL 300 秒、失败仅告警返回 0),供各业务写路径通知大屏刷新;已接入:拣货完成 systems/pick.js#wavePickTaskComplete、复核完成 systemMethods/order/recheckOrder.js#confirmRecheck / confirmRecheckByWaveId / batchQuickRecheck / batchQuickRecheckByWave、打包完成 systems/workbench.js#_updateOrderPackStatus(覆盖所有打包结束路径)。", "代码依据:app/service/systems/warehouse_panel.js#touchLastChangeAt(新增)+ 3 个文件 6 处调用点;ESLint 0 错误(workbench.js 存在预先存在的 class-field 解析告警与本次无关)。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData 一条(notes 新增外部驱动公共方法说明);根版本 0.3.291 → 0.3.292、updatedAt 保持 2026-10-12;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.291", "date": "2026-10-12", "type": "updated", "summary": "index.getWarehousePanelData stageOverview 环节卡 doing/abnormal 统一订单表状态口径(拣货中/打包中/各环节异常)(0.3.290 → 0.3.291)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:stageOverview 环节卡 doing/abnormal 统一订单表状态口径——拣货 doing 由拣货任务数(wms_wave_pick_task status=1)改为订单表 pick_status=padding(池内 + 配送表今日出库双表);拣货 abnormal=pick_status=error、复核 abnormal=recheck_status=error、打包 abnormal=pack_status=error 均补配送表今日出库双表;打包 abnormal 由任务数(wms_pack_task status=3)改为订单表 pack_status=error;复核 doing 保持波次口径(wms_wave_batch,订单表 recheck_status 仅有 none/fin/error 无复核中状态)。", "代码依据:app/service/systems/warehouse_panel.js#queryStageOverview(pickDoing/pickAbnormal/recheckAbnormal/packAbnormal 改 Promise.all 双表订单状态 count);ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData 一条(response.data.description 与 notes 补环节卡口径);根版本 0.3.290 → 0.3.291、updatedAt 保持 2026-10-12;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.290", "date": "2026-10-12", "type": "updated", "summary": "index.getWarehousePanelData 打包卡 doing 改订单表 pack_status=padding 订单数口径(0.3.289 → 0.3.290)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:stageOverview 打包卡 doing 由「打包中任务数(wms_pack_task status=1 count)」改为「打包中订单数」——订单表 pack_status=padding(池内 pendingBase + 配送表今日出库 dispatchTodayBase 双表计数),与 fulfillment 未打包/已打包同源订单表口径。", "数据说明:生产实测池内 padding=0;配送表今日出库存在 96 条 pack_status=padding 残留(订单已 outbound_status=fin 但出库未回填 pack_status,另有 8 条打包任务 status=1 挂起且关联订单均已出库),属历史数据问题,待出库回填逻辑修复。", "代码依据:app/service/systems/warehouse_panel.js#queryStageOverview(packDoing 改 Promise.all 双表 count pack_status=padding);ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData 一条(response.data.description 与 notes 补 doing 口径);根版本 0.3.289 → 0.3.290、updatedAt 保持 2026-10-12;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.289", "date": "2026-10-12", "type": "updated", "summary": "index.getWarehousePanelData 打包汇总(pack 卡 today / groupPacking / scatterPacking)排除打包中任务,仅统计已完成 status=2(0.3.288 → 0.3.289)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:pack 卡 today 与 groupPacking/scatterPacking 的任务条件由 status != 3(含打包中)改为 status = 2(仅已完成),打包中任务不再计入打包订单数;打包中仍体现为:fulfillment 未打包数(pack_status != fin 含 padding)+ stageOverview 打包卡 doing(打包中任务数)。", "代码依据:app/service/systems/warehouse_panel.js#queryStageOverview(packToday 两个子查询 status != 3 → status = 2)/#queryPackingBlock(taskWindowWhere status != 3 → status = 2);ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData 一条(response.data.description 与 notes 补排除打包中口径);根版本 0.3.288 → 0.3.289、updatedAt 保持 2026-10-12;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.288", "date": "2026-10-12", "type": "updated", "summary": "index.getWarehousePanelData stageOverview 打包卡 today 改真实打包订单数(团购按 wave_index 真实订单数替代 pack_quantity 快照)(0.3.287 → 0.3.288)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:打包卡 today 的团购部分由 pack_quantity 快照求和改为团购任务 wave_id 关联 wms_order_wave_index 的真实订单数(DISTINCT wave_id 去重)+ 散单任务数,修复快照虚高导致打包卡(16013)大于已复核(15385)的问题;新口径今日真实打包订单数=15408(与已复核差 23=免复核商品订单,属正常)。", "代码依据:app/service/systems/warehouse_panel.js#queryStageOverview(packToday countSql 改为散单任务计数 + 团购 wave_index 真实订单数子查询);ESLint 0 错误;生产 SQL 实测 15408。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData 一条(response.data.description 与 notes 补打包卡 today 口径);根版本 0.3.287 → 0.3.288、updatedAt 保持 2026-10-12;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.287", "date": "2026-10-12", "type": "updated", "summary": "index.getWarehousePanelData fulfillment 已打包改订单状态存量口径(pack_status=fin 池内+配送今日出库),修复已打包大于已复核(0.3.286 → 0.3.287)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:fulfillment 打包环节已* 由「今日打包任务订单数」(wms_pack_task 窗口内 pack_mode=2 按 pack_quantity 求和 + 散单每任务 1 单)改回订单状态存量口径(池内 pack_status=fin + 配送表今日出库 pack_status=fin),与分配/打印/拣货口径一致;修复打包任务快照含未复核/重复计入导致已打包(16013)大于已复核(15385)的问题,改后已打包=14739 ≤ 已复核。stageOverview 打包卡 today 仍为今日打包任务订单数口径(与打包卡语义一致)。", "代码依据:app/service/systems/warehouse_panel.js#queryFulfillment(新增 todayPackOrdersPromise 池内+配送双表 pack_status=fin,doneTodayMap.pack_status 改取该值,删除 packTaskOrdersToday 查询);ESLint 0 错误;egg 直调验证环节约束通过。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData 一条(response.data.description 与 notes 补打包环节已* 口径);根版本 0.3.286 → 0.3.287、updatedAt 保持 2026-10-12;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.286", "date": "2026-10-12", "type": "updated", "summary": "index.getWarehousePanelData trend 下单量窗口修正为业务日窗口(未过零点=今日自然日开始时间起,凌晨=昨日自然日开始时间起)(0.3.285 → 0.3.286)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:trend created_count 统计窗口由 [自然日零点, 业务日结束)(凌晨订单并入首点)修正为业务日窗口 [自然日开始时间, 次日自然日开始时间)——未到次日自然日开始时间时为 [今日自然日开始时间, 次日自然日开始时间),凌晨(已过零点)时为 [昨日自然日开始时间, 今日自然日开始时间);早于窗口起点的订单不再并入首点。", "代码依据:app/service/systems/warehouse_panel.js#queryTrend(删除 midnight/early 计数查询,窗口直接使用 todayStart/tomorrowStart);ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData 一条(response.data.description 与 notes 补窗口口径);根版本 0.3.285 → 0.3.286、updatedAt 2026-10-11 → 2026-10-12;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.285", "date": "2026-10-11", "type": "updated", "summary": "index.getWarehousePanelData trend 移除 pack_count 打包数(仅保留总单量累计)(0.3.284 → 0.3.285)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:trend points 每项由 { label, created_count, pack_count } 改为 { label, created_count },移除打包数(打包数口径与总单量不同源、易引起误解);created_count 保持总单量按订单创建时间落桶后按小时累计(与 fulfillment.total 同口径),max 仅按 created_count 峰值。", "代码依据:app/service/systems/warehouse_panel.js#queryTrend(删除 pack 查询与 pack_count 落桶/累计;签名移除 warehouseId);ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData 一条(response.data.description 与 notes 移除 pack_count 描述);根版本 0.3.284 → 0.3.285、updatedAt 保持 2026-10-11;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.284", "date": "2026-10-11", "type": "updated", "summary": "index.getWarehousePanelData trend 补充 total 总单量字段(与 fulfillment.total 同口径)(0.3.283 → 0.3.284)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:trend 响应由 { max, points } 补充为 { max, total, points },total=今日总单量(与 fulfillment.total 同口径:待处理订单池 + 配送表今日出库;fulfillment 块失败时兜底 0)。", "代码依据:app/service/systems/warehouse_panel.js#buildPanelData(组装数据时把 fulfillment.total 挂到 trend.total);ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData 一条(response.data.description 与 notes 补 total 字段);根版本 0.3.283 → 0.3.284、updatedAt 保持 2026-10-11;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.283", "date": "2026-10-11", "type": "updated", "summary": "index.getWarehousePanelData trend 双值改按小时累计(订单数/打包数累加,最后一点=全天总数)(0.3.282 → 0.3.283)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:trend 的 created_count/pack_count 由每小时独立计数改为按小时累计(前缀和,每点为截至该小时结束的累计总数,最后一点=全天总数);max 取累计峰值上取整。", "代码依据:app/service/systems/warehouse_panel.js#queryTrend(落桶后前缀和累计);ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData 一条(response.data.description 与 notes 补累计口径);根版本 0.3.282 → 0.3.283、updatedAt 保持 2026-10-11;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.282", "date": "2026-10-11", "type": "updated", "summary": "index.getWarehousePanelData trend 改业务日 24 点双值(created_count/pack_count),label 从仓库自然日开始时间起(0.3.281 → 0.3.282)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:trend 由固定 08:00-18:00 共 11 点单值(value)改为业务日 24 点双值——points 每项 { label, created_count, pack_count },label 从仓库自然日开始时间(day_start_time,默认 06:00)起每小时一点到次日自然日开始时间(共 24 点);created_count=订单创建时间落桶(自然日零点起统计、全部订单仅排除已取消,早于自然日开始时间的并入第一点);pack_count=打包订单数按打包任务创建时间落桶(pack_mode=2 按 pack_quantity 求和 + 散单每任务 1 单,非异常未删除,与打包卡 today 同口径);max 取双值峰值上取整。", "代码依据:app/service/systems/warehouse_panel.js#queryTrend(重写,签名改 (currentModel, warehouseId, todayStart, tomorrowStart),移除 TREND_HOURS 常量;buildPanelData 传 businessStart/businessEnd);ESLint 0 错误;egg 直调验证 24 点 label 从 06:00 到次日 05:00、每点双值结构正确。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData 一条(response.data.description 与 notes 补 trend 双值口径);根版本 0.3.281 → 0.3.282、updatedAt 保持 2026-10-11;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.281", "date": "2026-10-11", "type": "updated", "summary": "index.getWarehousePanelData stageOverview 打包卡 today 改今日打包订单数(与 fulfillment 已打包同口径),替代今日任务数(0.3.280 → 0.3.281)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:stageOverview 打包卡 today 由今日创建打包任务数(PackTask create_time 窗口 count)改为今日打包任务订单数(SUM(CASE WHEN pack_mode=2 THEN pack_quantity ELSE 1 END),窗口内非异常未删除,与 fulfillment 已打包一致);doing(打包中任务数)/abnormal(异常任务数)保持任务维度。", "原因:用户反馈 pack 卡数据错误——today 显示任务数(1928)与已打包订单数(12718)不一致,且与拣货/复核卡 today(订单数口径)不统一。", "代码依据:app/service/systems/warehouse_panel.js#queryStageOverview(packToday 改 countSql 订单数统计);ESLint 0 错误;egg 直调 VERIFY_OK。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData 一条(notes 补 pack 卡 today 口径);根版本 0.3.280 → 0.3.281、updatedAt 保持 2026-10-11;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.280", "date": "2026-10-11", "type": "updated", "summary": "stock.check 盘点范围排除无头库位(所属 zone 不存在/已删除的库位不纳入盘点明细生成与作业视图库位枚举)(0.3.279 → 0.3.280)", "methods": [ "stock.check.addDetail", "stock.check.addLocationDetail", "stock.check.patternCreate", "stock.check.workData" ], "notes": [ "变更内容:无头库位(wms_location_space.zone_id 指向的 wms_location_zone 行不存在或已软删)一律不纳入盘点——①addDetail 商品路径仅按有效库位拆行(wms_storage 加 space_id IN 有效库位子查询,启用库存全部在无头库位的商品计入 invalid_stock_ids);②库位编码/ID 路径把无头库位分别计入 invalid_locations/invalid_location_ids(不报错,与不存在同口径);③type=all 全盘自动范围直接排除无头库位;④patternCreate 空库位定式收集 SQL 加 JOIN wms_location_zone 排除无头库位;⑤workData goods/space 视图库位枚举与明细生成同口径过滤。", "代码依据:app/service/systems/stock_check.js#VALID_SPACE_SQL(新增模块常量,wms_location_space JOIN wms_location_zone deleted_at IS NULL;应用于 _addGoodsDetailRows/_buildGoodsWorkRows/_buildSpaceWorkRows 的 storage 查询与 addDetail 全盘自动拉取;_addLocationDetailRows/_addLocationRowsByIds 的 LocationSpace 查询加 include zone required:true)+ app/service/systems/stock_check_patterns.js#collectEmptyLocation(SQL 加 JOIN zone)。", "回归测试:新增 2 用例(无头库位编码计入 invalid_locations 不入库、无头库位 ID 计入 invalid_location_ids 不入库,fixture 直接建 zone_id 不存在的库位并 force 清理);全盘自动范围/空间视图/多库位等既有用例的测试口径同步为有效库位过滤(fetchStockRows/fetchSpaceStockPairs/多库位用例/排序用例改 fetchSpaceStockPairs),stock_check 全量 237 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 4 条 method(stock.check.addDetail:description/response 无效列表/notes 补无头库位口径;stock.check.addLocationDetail:description 补无头库位记入 invalid_location_ids;stock.check.patternCreate:空库位定式口径与 goods 拆行口径补排除无头库位;stock.check.workData:三视图口径补库位枚举排除无头库位);根版本 0.3.279 → 0.3.280、updatedAt 保持 2026-10-11;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "0.3.279", "date": "2026-10-11", "type": "updated", "summary": "index.getWarehousePanelData 拣货块汇总改订单表状态口径:团购+散单拣货数=已拣货(池内 pick fin + 配送表今日出库 pick fin,按 wave_scope 1/3 分团购),替代今日任务快照(0.3.278 → 0.3.279)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:groupPicking/scatterPicking 的汇总 orders/goods/sku/wave 由今日创建任务快照(wave_pick_task order_count/wave_count + 任务订单关联表)改为订单表状态口径——池内 pick_status=fin + 配送表今日出库 pick fin,团购=wave_scope IN (1,3)、散单=NOT IN (1,3);团购+散单严格等于 fulfillment 已拣货;top 按人排行保持任务口径(订单表无拣货人)。", "原因:用户反馈团购拣货数+散单拣货数(7372)小于已拣货数(11809),任务快照(创建时抓单数)偏小且部分订单不建任务。生产核算:池内 pick fin 按 wave_scope 拆分 团购 10883 + 散单 926 = 11809 = 已拣货 ✓。", "代码依据:app/service/systems/warehouse_panel.js#queryPickingBlock(签名 pickModes→isGroup,summary 改双表订单状态 SQL:step/outbound/status/pick_status/wave_scope 条件,goods/sku=SUM(items_total/items_count)、wave=去重 wave_id;top 与 queryPickingGoodsSku 保持任务口径);ESLint 0 错误;egg 直调 VERIFY_OK(开发库 团购 13280 / 散单 146)。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData 一条(notes 口径);根版本 0.3.278 → 0.3.279、updatedAt 保持 2026-10-11;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.278", "date": "2026-10-11", "type": "updated", "summary": "index.getWarehousePanelData 已分配/已打印改订单表状态口径:池内 fin + 配送表今日出库 fin(与已拣货同口径,保证已分配≥已打印≥已拣货的流程约束),替代今日新建运单数/今日打印记录数(0.3.277 → 0.3.278)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:fulfillment 已分配由今日新建运单数(wms_order_express 按 order_id 去重)改为订单表状态口径(池内 post_status=fin + 配送表今日出库 post fin);已打印由今日打印记录订单数(wms_print_record order_ids)改为订单表状态口径(池内 print_status=fin + 配送表今日出库 print fin);与已拣货状态口径统一,保证已分配≥已打印≥已拣货。", "原因:今日作业口径下已打印(4003)< 已拣货(10947)、已分配(12621)与已打印大小关系亦不稳定,用户要求分配/打印/拣货都从订单表获取。生产核算(池内):post fin 14933 ≥ print fin 12816 ≥ pick fin 11597 ✓;配送窗口当前 0。", "代码依据:app/service/systems/warehouse_panel.js#queryFulfillment(todayAllocOrdersPromise/todayPrintOrdersPromise 改为双表状态 count,与 todayPickOrdersPromise 同构);ESLint 0 错误;egg 直调 VERIFY_OK。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData 一条(notes 口径);根版本 0.3.277 → 0.3.278、updatedAt 保持 2026-10-11;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.277", "date": "2026-10-11", "type": "updated", "summary": "index.getWarehousePanelData 已拣货改为状态口径:池内 pick_status=fin + 配送表今日出库 pick fin(状态无跨天错位,已拣 ≥ 已复核),替代今日拣货任务订单数快照(0.3.276 → 0.3.277)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:fulfillment 已拣货与 stageOverview 拣货卡 today 由今日拣货任务订单数(wave_pick_task order_count 快照,偏小)改为订单状态口径——池内 pick_status=fin + 配送表今日出库 pick fin;生产核实:状态口径已拣 10947 > 今日复核 9192(今日复核订单全部 pick_status=fin),而任务快照 6098 < 复核 9192 明显不合理(复核必先拣货)。其余环节保持 0.3.276 口径。", "代码依据:app/service/systems/warehouse_panel.js#queryFulfillment(todayPickOrdersPromise 双表 pick fin count)/#queryStageOverview(pickToday 同步);ESLint 0 错误;egg 直调两处 VERIFY_OK。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData(notes 口径);根版本 0.3.276 → 0.3.277、updatedAt 保持 2026-10-11;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.276", "date": "2026-10-11", "type": "updated", "summary": "index.getWarehousePanelData 履约链路各环节已* 统一改为今日作业口径:已分配=今日新建运单、已打印=今日打印记录、已拣货=今日拣货任务、已复核=今日复核、已打包=今日打包任务、已出库=今日出库(与打包块一致,消除状态口径跨天错位)(0.3.275 → 0.3.276)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:fulfillment 各环节已* 由「池内 fin + 配送表今日出库 fin」改为今日作业口径——已分配=wms_order_express 今日 create_at 未删除按 order_id 去重;已打印=wms_print_record 今日 type=express 的 data.order_ids 长度求和(面单打印记录无 order_id 列,data JSON 含 order_ids 数组);已拣货=wms_wave_pick_task 今日 order_count 合计(全部 pick_mode);已复核=订单分表 recheck_time 今日双表;已打包=今日打包任务订单数(保持);已出库=配送表今日出库(保持)。未* 保持真实状态口径(池内未完成+配送表未完成)。stageOverview 同步:拣货卡 today 改今日拣货任务订单数(与已拣货一致)、复核卡 today 改 recheck_time 今日双表(与已复核一致)。", "原因:用户反馈团购拣货+散单拣货(3869)比已拣货(8265)少 4396——已拣货状态口径含昨日拣完未出库的池内订单(8440),与今日作业口径天然错位;按打包一致处理并扩展到打印/分配/复核。", "生产核算(窗口 UTC 10-10 22:00 起):已分配 12621、已打印 4003(1073 记录 order_ids 合计)、已拣货 3869、已复核 6789、已打包 4397、已出库 0(当天尚未出库)。", "代码依据:app/service/systems/warehouse_panel.js#queryFulfillment(新增 todayAllocOrdersPromise/todayPrintOrdersPromise/todayPickOrdersPromise/todayRecheckOrdersPromise,stageCounts 内 doneTodayMap 按环节字段映射今日作业数);ESLint 0 错误;egg 直调 VERIFY_OK。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData(notes 口径);根版本 0.3.275 → 0.3.276、updatedAt 保持 2026-10-11;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.275", "date": "2026-10-11", "type": "updated", "summary": "index.getWarehousePanelData 拣货块 goods/sku 补无关联任务:pick_mode=1 团购任务无 wms_wave_pick_task_order 关联记录导致商品数漏算,改为无关联任务按 wave_id 从订单分表统计(0.3.274 → 0.3.275)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:queryPickingGoodsSku 的 goods/sku 统计改为 UNION 两段——有 wms_wave_pick_task_order 关联的任务走 pto 精确统计;无关联的任务(实测 pick_mode=1 共 60 任务 3862 单 963 波全部无 pto 记录,导致 top 如黎英俊 goods=0)按 wave_id 从订单分表(current/dispatch,status!=cancel)统计波次订单商品;总量与 top 同步。", "核实过程:生产只读窗口内任务 401 个,仅 341 个有 pto 关联;无关联任务全为 pick_mode=1(60 个、orders 快照 3862、waves 963),配送表按 wave join 补数 goods=473/sku=336(current 表另有未出库部分)。orders 快照口径不受影响(与 fulfillment 已拣货 19062 基本一致)。", "代码依据:app/service/systems/warehouse_panel.js#queryPickingGoodsSku(goodsSkuSelect/topGoodsSkuSelect 改为 UNION ALL 双段,taskWindowWhere2 别名替换);ESLint 0 错误;egg 直调拣货块 VERIFY_OK。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData(notes 口径);根版本 0.3.274 → 0.3.275、updatedAt 保持 2026-10-11;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.274", "date": "2026-10-11", "type": "updated", "summary": "index.getWarehousePanelData 小团购归回团购块:groupPacking 范围由 wave_scope=1 改为 IN (1,3)(大团购+小团购,top 按打包台),scatterPacking=NOT IN (1,3);orders 保持按 pack_mode 统计(0.3.273 → 0.3.274)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:groupPacking(团购块)波次范围由 wave_scope=1 改为 wave_scope IN (1,3),小团购(3)从散单块归回团购块(top 仍按打包台聚合);scatterPacking(散单块)= wave_scope NOT IN (1,3)(0 未分配/2 散单/4 单品单件,top 按打包员);orders 口径不变(pack_mode=2 按 pack_quantity 求和、pack_mode=1 每任务 1 单)。", "生产核算(窗口内):团购块=wave_scope 1+3 共 1161 任务/17387 单,散单块=2+4 共 1471 任务/1471 单,合计 18858,与今日出库已打包 18652 仅差约 200(今日打包未出库)✓。", "代码依据:app/service/systems/warehouse_panel.js#queryPackingBlock(scopeWhere 改为 IN (1,3) / NOT IN (1,3));ESLint 0 错误;egg 直调 VERIFY_OK。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData(notes 口径);根版本 0.3.273 → 0.3.274、updatedAt 保持 2026-10-11;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.273", "date": "2026-10-11", "type": "updated", "summary": "index.getWarehousePanelData 打包订单数修正 wave_scope=3 小团购:orders 改为按打包模式统计(pack_mode=2 按 pack_quantity 求和 + 散单每任务 1 单),小团购任务不再按 1 单漏算(修正前今日打包 15997,修正后 18847,缺口 2850)(0.3.272 → 0.3.273)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:groupPacking/scatterPacking 与 fulfillment 已打包的订单数口径由「wave_scope=1 SUM(pack_quantity) + 其余每任务 1 单」改为「pack_mode=2(团购模式)按 pack_quantity 求和 + pack_mode=1 散单每任务 1 单」——wave_scope=3(小团购)的打包任务是团购模式(pack_mode=2、pack_quantity=多单),此前按散单每任务 1 单漏算(订单 1032238 日志:小团购波次 B2026101000155 共 12 单按 1 单统计)。", "核实过程:生产只读 wave_scope 分布(窗口内)1=244/2=1173/3=917/4=298,修正前订单数 15997(13654+2343),修正后 18847(13654+1173+3715+298);今日出库已打包 18652,差距由 2655 收敛到约 195(今日打包未出库),三个口径基本自洽。", "代码依据:app/service/systems/warehouse_panel.js#queryPackingBlock(ordersExpr 统一 SUM(CASE WHEN pack_mode=2 THEN pack_quantity ELSE 1 END),summary 与两块 top 同步)/#queryFulfillment(packTaskOrdersTodayPromise SQL 同口径);ESLint 0 错误;egg 直调 VERIFY_OK。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData(notes 口径);根版本 0.3.272 → 0.3.273、updatedAt 保持 2026-10-11;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.272", "date": "2026-10-11", "type": "updated", "summary": "index.getWarehousePanelData 未打包恢复真实状态口径:未*=池内未打包 + 配送表今日出库未打包(替代 total-已*),与只读核实口径一致(169+458=627);已*仍为今日打包任务数(0.3.271 → 0.3.272)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:fulfillment 打包环节未* 由 total-已* 改回真实状态口径——常用表池内 pack 非 fin + 配送表今日出库 pack 非 fin(与只读核实一致:待处理表 169 + 配送表 458 = 627);已* 保持今日打包任务订单数;未+已 不再强制等于 total(差额为昨日打包今日出库的跨天订单)。", "代码依据:app/service/systems/warehouse_panel.js#queryFulfillment(items 组装移除打包环节 undone=finalTotal-done 特判,恢复 stageCounts 真实 undone=池内非fin+配送非fin);ESLint 0 错误;临时验证脚本(非 pack 环节 undone+done=total 断言)通过。", "文档变更范围:methods/system.json 的 module=index 分组仅更新 index.getWarehousePanelData(notes 口径);根版本 0.3.271 → 0.3.272、updatedAt 保持 2026-10-11;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.271", "date": "2026-10-11", "type": "updated", "summary": "index.getWarehousePanelData 修复 stageOverview 解构错位:0.3.269 拣货卡双表求和插入时残留旧任务数 countSql 导致数组多一个元素,后续字段全部错位(pick.doing 错显已拣货数、pick.abnormal 错显拣货中任务数、pack.today 错显复核异常数)(0.3.270 → 0.3.271)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:queryStageOverview 的 Promise.all 数组移除残留的旧拣货任务数 countSql(今日完成拣货任务数),仅保留双表 pick fin 求和作为 pick.today;数组恢复 15 元素与解构一一对应。修复后 pick.today=已拣货订单数(与 fulfillment 同口径)、pick.doing=拣货中任务数、pick.abnormal=池内拣货异常、pack.today=今日打包任务数。", "代码依据:app/service/systems/warehouse_panel.js#queryStageOverview(删除 pick 区域冗余 countSql);ESLint 0 错误;临时验证脚本(queryStageOverview 直调:pick.today=13414 订单数、doing/abnormal 任务数、与 queryFulfillment 已拣货相等断言)通过。", "文档变更范围:methods/system.json 根版本 0.3.270 → 0.3.271、updatedAt 保持 2026-10-11;methods/changes/system.json 新增本条(插入数组首位);接口描述与口径未变。" ] }, { "version": "0.3.270", "date": "2026-10-11", "type": "added", "summary": "新增仓库配置「自然日开始时间」day_start_time(subject_config,HH:mm,默认 06:00):面板全部今日统计窗口改为业务日(昨日 06:00 后的订单视为今日;当前时间早于当日配置点窗口为昨日配置点→当日配置点,否则为当日→次日)", "methods": [ "index.getWarehousePanelData", "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "变更内容:wms_store.subject_config 新增 day_start_time(HH:mm,默认 06:00,范围 00:00-23:59),normalizeSubjectConfig 同步校验(格式非法报错、范围外回退默认、旧数据补默认);WAREHOUSE_SETTING_FIELDS 新增对应字段元信息(getFieldMeta 返回);面板 getWarehousePanelData 的今日统计窗口(fulfillment 配送表今日出库/今日打包任务/退件拆包、stageOverview 各 today、b2b、groupPicking/scatterPicking、groupPacking/scatterPacking)统一改为业务日窗口 [配置点, 次日配置点),当前时间早于当日配置点时窗口从昨日配置点开始;trend(08:00-18:00 小时趋势)与 weeklyEfficiency(7 日)保持自然日。", "代码依据:app/model/store.js(DEFAULT_DAY_START_TIME/DAY_START_TIME_MIN/MAX + DEFAULT_SUBJECT_CONFIG.day_start_time + normalizeSubjectConfig 校验段);app/service/systems/setting/warehouse.js(WAREHOUSE_SETTING_FIELDS 新增 day_start_time);app/service/systems/warehouse_panel.js(新增 getWarehouseDayStartTime(读 subject_config,异常回退 06:00)与 resolveBusinessDayRange,buildPanelData 各块传 businessStart/businessEnd);ESLint 0 错误;临时验证:开发库仓库 100000 配置默认 06:00,当前 2026-10-11 00:19 窗口=[2026-10-10 06:00, 2026-10-11 06:00) 断言通过。", "文档变更范围:methods/system.json 的 module=index 分组更新 index.getWarehousePanelData(notes 补业务日窗口口径)、module=setting.warehouse 分组更新 saveSettings(params 新增 subject_config.day_start_time)与 getFieldMeta(response 新增 data[].day_start_time);根版本 0.3.269 → 0.3.270、updatedAt 2026-10-10 → 2026-10-11;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.269", "date": "2026-10-10", "type": "updated", "summary": "index.getWarehousePanelData 未打包合并配送数据 + 拣货卡对齐:打包环节未*=总数-已*(配送表今日出库未打包/跨天错位并入未*,恢复每环节未+已=total);stageOverview 拣货卡 today 与 fulfillment 已拣货同口径(订单数)(0.3.268 → 0.3.269)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容一:fulfillment 打包环节未* 改为 total - 已*(已*=今日打包任务订单数),配送表今日出库中未打包单与跨天打包出库错位部分全部并入未打包,恢复每环节未+已=total;此前未*=池内未打包+配送表非 fin,未包含跨天错位部分,用户反馈未打包没有合并统计配送数据。", "变更内容二:stageOverview 拣货卡 today 由今日完成拣货任务数(任务维度,团购一任务几十单导致 401 与已拣货 19068 严重不一致)改为与 fulfillment 已拣货同口径:常用表池内 pick_status=fin + 配送表今日出库 pick fin(订单数)。", "代码依据:app/service/systems/warehouse_panel.js#queryFulfillment(items 组装时打包环节 undone=Math.max(finalTotal-done,0))/#queryStageOverview(pickToday 改为双表 pick fin Promise.all 求和,替换原 wave_pick_task 任务数 countSql);ESLint 0 错误;临时验证脚本 6 环节 undone+done=total 断言全部通过。", "文档变更范围:methods/system.json 的 module=index 基础模块分组仅更新 index.getWarehousePanelData 一条(notes 同步打包环节未* 与拣货卡口径);根版本 0.3.268 → 0.3.269、updatedAt 保持 2026-10-10;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.268", "date": "2026-10-10", "type": "updated", "summary": "index.getWarehousePanelData 已打包口径对齐打包任务:打包环节已* 由配送表今日出库 pack_status=fin 叠加改为今日打包任务订单数(团购 SUM(pack_quantity)+散单任务数,与 groupPacking/scatterPacking 严格一致,消除跨天打包出库窗口错位)(0.3.267 → 0.3.268)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:fulfillment 打包环节已* = 常用表池内 pack_status=fin + 今日打包任务订单数(wms_pack_task 今日创建、非异常、未删除:wave_scope=1 按 pack_quantity 求和 + 其余每任务 1 单,与 groupPacking/scatterPacking 同一口径);不再叠加配送表今日出库 pack_status=fin(昨日打包今日出库的订单不计入今日已打包)。未打包口径不变(池内 pack 非 fin + 配送表今日出库 pack 非 fin 的拦截等单)。其余五环节仍按配送表今日出库状态拆分叠加。", "核实过程:生产只读(1000028,UTC 今日)池内 pack fin=0、配送表今日出库 pack fin=17005、今日打包任务订单数=14827,差距 2178 为跨天打包出库窗口错位(昨日打包今日出库 − 今日打包未出库),因此已打包对齐打包任务口径后与 groupPacking+scatterPacking(12924+1885≈14827 北京窗口)一致。", "代码依据:app/service/systems/warehouse_panel.js#queryFulfillment(新增 packTaskOrdersTodayPromise 原生 SQL:SUM(CASE WHEN wave_scope=1 THEN pack_quantity ELSE 1 END) 今日窗口;stageCounts 内 pack_status 环节 done 叠加改用该值);ESLint 0 错误;临时验证脚本(非 pack 环节 undone+done=total 断言)通过。", "文档变更范围:methods/system.json 的 module=index 基础模块分组仅更新 index.getWarehousePanelData 一条(response.data/notes 同步打包环节口径);根版本 0.3.267 → 0.3.268、updatedAt 保持 2026-10-10;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.267", "date": "2026-10-10", "type": "updated", "summary": "index.getWarehousePanelData fulfillment 配送表补数按环节状态拆分:今日出库订单状态 fin 计入已*、非 fin 计入未*(未打包即出库的拦截单不再计入已打包,避免已打包虚高且大于团购+散单打包数)(0.3.266 → 0.3.267)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:fulfillment 各环节配送分表今日出库订单(status 非 cancel、outbound_status=fin、delivery_time 今日、dispatch_lane m4/m5)由无条件叠加已* 改为按环节状态字段拆分——状态 fin 计入已*,非 fin 计入未*(打包环节的拦截等未打包即出库单计入未打包);保证每环节未+已=total 且与真实状态一致,已打包不再虚高。", "根因:配送表今日出库中约 9%(1735/18593)pack_status 非 fin(拦截等特殊路径未打包即出库),无条件叠加导致已打包(18564)远大于团购打包数+散单打包数(14743);其余环节(post/print/pick/recheck)配送表今日出库订单状态均为 fin,拆分后与旧口径一致。", "代码依据:app/service/systems/warehouse_panel.js#queryFulfillment(stageCounts 每环节四元组:undoneCurrent/doneCurrent/dispatchFin/dispatchTodayOutbound,undone=池内非fin+配送表非fin、done=池内fin+配送表fin);ESLint 0 错误;临时验证脚本每环节 undone+done=total 断言通过;生产只读验证:配送表今日出库 18593,pack_fin=16858、pack_not_fin=1735,其余环节全 fin。", "文档变更范围:methods/system.json 的 module=index 基础模块分组仅更新 index.getWarehousePanelData 一条(response.data/notes 同步拆分口径);根版本 0.3.266 → 0.3.267、updatedAt 保持 2026-10-10;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.266", "date": "2026-10-10", "type": "updated", "summary": "index.getWarehousePanelData groupPacking 订单数修正:orders 由任务数(COUNT(*))改为打包数量快照求和 SUM(pack_quantity)(团购一任务一波次,任务数会严重低估订单数);scatterPacking 保持任务数(0.3.265 → 0.3.266)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:groupPacking 的 orders(summary 与 top 均)由 COUNT(*)(任务数)改为 COALESCE(SUM(pt.pack_quantity),0)——pack_quantity 是创建打包任务时服务端复查落库的波次订单数快照(workbench._packOrder:团购取波次实时订单数,散单默认 1),一任务一波次,任务数口径会把订单数低估为波次数(218 任务显示 218 单);scatterPacking 散单一单一任务,orders 保持 COUNT(*)。", "代码依据:app/service/systems/warehouse_panel.js#queryPackingBlock(ordersExpr 按 isGroup 分支:团购 SUM(pack_quantity)/散单 COUNT(*);summary 与团购 top 同步替换);ESLint 0 错误;生产只读验证:今日团购任务 220、orders=SUM(pack_quantity)=12743、wave=220。", "文档变更范围:methods/system.json 的 module=index 基础模块分组仅更新 index.getWarehousePanelData 一条(notes 补 groupPacking/scatterPacking orders 口径);根版本 0.3.265 → 0.3.266、updatedAt 保持 2026-10-10;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.265", "date": "2026-10-10", "type": "updated", "summary": "index.getWarehousePanelData fulfillment 全环节补配送表:已出库订单迁移到配送分表后,各环节 done 与 total 统一叠加配送表今日出库订单(出库即视为走完前序环节,每环节未+已=total);stageOverview.todayOutbound 同步双表(0.3.264 → 0.3.265)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:fulfillment 的各环节 done(已分配/已打印/已拣货/已复核/已打包/已出库)与 total 在常用分表作业池基础上统一叠加配送分表(wms_order_delivery_{仓库}_dispatch)今日出库订单(status 非 cancel、outbound_status=fin、delivery_time 今日、dispatch_lane m4/m5;已出库即视为走完前序环节),保证每环节未+已=total;stageOverview 的 todayOutbound 同步双表求和(常用表 step=4 今日出库 + 配送表今日出库),totalOrders=待处理+今日出库口径不再偏小。迭代记录:首版仅出库环节与 total 补数,用户反馈五环节已* 未核算已出库部分,改为全环节统一叠加。", "口径说明:配送表今日出库订单中有少量(约 17%)pack_status 非 fin(拦截等特殊路径未打包即出库),按看板口径仍计入各环节已*(出库即视为走完前序环节),以保持每环节未+已=total 一致。", "代码依据:app/service/systems/warehouse_panel.js#queryFulfillment(dispatchTodayBase 配送表今日出库过滤;stageCounts 每环节 done=常用表 fin + 配送表今日出库数,total=常用表待处理 + 配送表今日出库)/#queryStageOverview(todayOutbound 双表 Promise.all 求和);buildPanelData 调用处传入 dispatchModel;ESLint 0 错误;临时验证脚本断言每环节 undone+done=total 通过;生产只读验证:1000028 常用表 pending 3188 + 配送表今日出库 16000 = 19188。", "文档变更范围:methods/system.json 的 module=index 基础模块分组仅更新 index.getWarehousePanelData 一条(response.data/notes 同步配送表补数口径);根版本 0.3.264 → 0.3.265、updatedAt 保持 2026-10-10;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.264", "date": "2026-10-10", "type": "updated", "summary": "index.getWarehousePanelData 打包数据区分团购/散单:packingRank 拆分为 groupPacking(wave_scope=1,top 按打包台)与 scatterPacking(其余,top 按打包员)两块(0.3.263 → 0.3.264)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:原 packingRank(散单+团购合并)拆分为两个数据块——groupPacking(pack_task.wave_scope=1 大团购,top 按打包台 wms_workbench.name 聚合,workbench_id 为空归「未指定打包台」)与 scatterPacking(wave_scope 非 1:0 未分配波次/2 散单/3 小团购/4 单品单件,top 按打包员 pack_task_packer.account_name 聚合),每块含 orders/goods/sku/wave/top5(口径不变:今日创建、非异常、未删除);顶层 packingRank 字段移除。迭代记录:区分字段曾先按 pack_mode(废弃语义)实现,后改 wave_scope(先 IN(1,3),用户最终确认 3 归散单、仅 1 为团购);top 口径曾统一按打包员,用户要求团购按打包台、散单按个人。", "代码依据:app/service/systems/warehouse_panel.js#queryPackingPersonal 改为 queryPackingBlock(isGroup 布尔参数,SQL 拼 pt.wave_scope = 1 / != 1;top 查询按 isGroup 分支:团购 LEFT JOIN wms_workbench 按打包台聚合、散单 JOIN wms_pack_task_packer 按打包员聚合);buildPanelData 并行聚合两块(groupPacking/scatterPacking,各自单块容错),data 输出同步替换;ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=index 基础模块分组仅更新 index.getWarehousePanelData 一条(response.data/notes 同步打包两块口径);根版本 0.3.263 → 0.3.264、updatedAt 保持 2026-10-10;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.263", "date": "2026-10-10", "type": "updated", "summary": "index.getWarehousePanelData fulfillment 新增今日退回收件数与今日拆包件数(追加在 items 数组末尾两项,按 wms_return_received / wms_return_unpack 的 created_at 今日计数;wms_return_unpack 补 (warehouse_id, created_at) 索引)(0.3.262 → 0.3.263)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "变更内容:fulfillment 数据块的 items 数组在 6 环节未/已 12 项之后追加两项——label 今日退回收件 / 今日拆包(icon=returnReceived/returnUnpack,与环节项同构 label/icon/value),口径为按 warehouse_id 隔离 + created_at 落在今日 [00:00, 次日 00:00) 的计数(wms_return_received / wms_return_unpack);wms_return_received 已有 idx_warehouse_created_at,wms_return_unpack 无 created_at 索引,新增迁移 20261010100000-add-created-at-index-to-wms-return-unpack.js(addIndex (warehouse_id, created_at),模型 indexes 同步,开发库已执行核验,生产随发布执行)。", "代码依据:app/service/systems/warehouse_panel.js#queryFulfillment(新增 ReturnReceived/ReturnUnpack 两个 count,结果追加到 items 末尾,buildPanelData 调用处传入 warehouseId/todayStart/tomorrowStart);app/model/return_unpack.js(indexes 增加 idx_warehouse_created_at);ESLint 0 错误;临时验证脚本真实库直调 VERIFY_OK(items=14 项、末两项 label 正确、顶层无新增字段)。迭代记录:首版把两个计数放在 fulfillment 顶层字段(returnReceivedToday/returnUnpackToday),用户纠正为追加到 items 数组(与环节项同构)。", "文档变更范围:methods/system.json 的 module=index 基础模块分组仅更新 index.getWarehousePanelData 一条(response.data/notes 补充 fulfillment items 末尾两项口径);根版本 0.3.262 → 0.3.263、updatedAt 保持 2026-10-10;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.262", "date": "2026-10-10", "type": "updated", "summary": "stock.check.result 无作业记录时返回明细范围行(盘点前/待提交后台查看明细专用,不再作为盘点作业数据提供)(0.3.261 → 0.3.262)", "methods": [ "stock.check.result" ], "notes": [ "变更内容:result 在无作业记录(如待提交/盘点前)时 rows 直接返回 wms_stock_check_detail 明细范围行(原始行,不聚合),total=明细行数——本接口仅展示盘点前/盘点后后台查看明细使用,不再作为盘点作业数据提供(盘点作业数据见 stock.check.workData);有作业记录时保持原聚合口径不变(商品范围按商品合并、库位范围按库位行)。", "代码依据:app/service/systems/stock_check.js#result(records.length===0 分支直接返回明细行);回归测试调整 3 用例(盘点前/待提交两用例新断言明细范围行口径;addDetail 与 recordDelete 用例同步改为断言明细范围行),stock_check 全量 235 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.result 一条(description/response.rows/notes 补充无作业记录时返回明细范围行口径);根版本 0.3.261 → 0.3.262、updatedAt 保持 2026-10-10;methods/changes/system.json 新增本条(插入数组首位);其余 24 条 method 未改动(stock.check 分组仍为 25 条)。" ] }, { "version": "0.3.261", "date": "2026-10-10", "type": "added", "summary": "新增 stock.check.exportDetail 盘点明细导出接口(异步,按盘点范围分流:商品盘点固定两 sheet——汇总和差异 + 库位/数量/条码/商品名称;库位盘点简化)", "methods": [ "stock.check.exportDetail" ], "notes": [ "接口:stock.check.exportDetail,入参 id(盘点任务ID,必填);异步执行,立即返回 task_id,进度查询复用 stock.check.exportTaskProgress。", "商品盘点固定两个 Sheet:Sheet1「汇总和差异」每商品一行(盘点单号/商品编码/商品名称/规格/账面数量(明细行 system_quantity 快照合计,提交审核时刷新)/盘点数量/差异数量/差异类型(盘盈|盘亏,无差异或未盘留空);未知商品追加在末尾(无账面、差异=实盘=盘盈);Sheet2「库位明细」每商品每库位一行(库位编码/数量(实盘,未盘 0)/条码(wms_stock_barcodes 第一条)/商品名称)。", "库位盘点:Sheet「盘点明细」作业记录口径(库位编码/商品编码/商品名称/盘点数量),未知商品编码=扫描条码、空库位标记商品为空数量 0。", "迭代记录:首版按 mode 二选一(location 单 sheet / summary 两 sheet),用户纠正为商品盘点固定两 sheet(汇总和差异 + 库位明细精简列),mode 入参已移除;随后纠正「库位明细」按作业记录(wms_stock_check_record)一行一条实际盘点记录导出(不再按快照库位展开/合并无库位组);补充库位编码列显示覆盖(custom_name → custom_barcode → space_code);最后汇总和差异 sheet 增加「条码」列(wms_stock_barcodes 第一条,未知商品商品编码列即扫描条码、条码列留空)。", "代码依据:app/service/systems/stock_check.js#exportCheckDetail/#_generateAndUploadCheckDetailExcel(商品范围复用 result 的商品合并聚合;新增 StockBarcode 条码查询)/#_uploadExportExcelFile(原 _generateAndUploadStockCheckExcel 上传段抽为公共方法,两处导出一致复用)+ app/service/systemMethods/stock/check.js#exportDetail(ALL_METHOD_NAMES/_noNeedLog 已加入);回归测试 3 用例(商品两 sheet 回读断言/库位任务/方法层异步轮询至 success),stock_check 全量 235 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.exportDetail 一条(位于 stock.check.export 之后,分组由 24 条增至 25 条);根版本 0.3.260 → 0.3.261、updatedAt 保持 2026-10-10;methods/changes/system.json 新增本条(插入数组首位);其余 24 条 method 未改动。" ] }, { "version": "0.3.260", "date": "2026-10-10", "type": "updated", "summary": "stock.check.submit 商品范围任务提交审核时刷新明细行账面快照(提交即快照,提交时点账面;不新增表、主表不额外写快照)(0.3.259 → 0.3.260)", "methods": [ "stock.check.submit" ], "notes": [ "变更内容:商品范围任务(scope_type=goods)提交审核时把各明细行 system_quantity 刷新为该库位当时账面 SUM(available_quantity+locked_quantity)(库存记录不存在按 0),保证 result/差异对比使用提交时点的账面(添加明细到提交之间库存变动以提交时点为准,与 result 商品范围聚合的库位账面快照同源);明细表本身已按「商品+库位」完整记录快照,主表不额外写快照(scope_snapshot 保持 null);快照失败则提交失败(提交即快照);驳回(rejected)后重新提交会重新刷新;库位范围任务(scope_type=location)账面实时查 wms_storage,不处理。", "存储方案:无需新表、无迁移——明细表已有 system_quantity 快照列(按「商品+库位」拆行),提交时直接刷新即可。", "代码依据:app/service/systems/stock_check.js#submit(缺库位校验后、置 submitted 前调用)/#_refreshGoodsBookSnapshotOnSubmit(新增);回归测试两用例(商品任务提交后明细行快照刷新为提交时账面、主表 scope_snapshot 保持 null,库存临时 +100 后 finally 恢复;库位范围任务提交明细行 system_quantity 保持 0),stock_check 全量 231 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.submit 一条(description/notes 补提交时刷新明细行账面快照语义);根版本 0.3.259 → 0.3.260、updatedAt 保持 2026-10-10;methods/changes/system.json 新增本条(插入数组首位);其余 23 条 method 未改动(stock.check 分组仍为 24 条)。" ] }, { "version": "0.3.259", "date": "2026-10-10", "type": "updated", "summary": "stock.check.result 商品范围按商品聚合输出(一个商品一行,多个库位明细行合并),行内 locations 输出各库位账面快照与实盘;主表计数同步商品口径(0.3.258 → 0.3.259)", "methods": [ "stock.check.result", "stock.check.detail" ], "notes": [ "变更内容:按商品盘点(scope_type=goods)不再按库位拆行输出——result 商品范围按 stock_id 合并(一行一商品),行含 system_quantity(账面快照合计=各库位明细行 system_quantity 之和,创建明细时落库=盘点时做快照)与 locations(商品所在库位列表 [{ location_id, location_code, system_quantity, quantity }]:system_quantity 为该库位账面快照、quantity 为该库位实盘合计(未盘为 0),仅作业记录存在而快照不存在的库位追加在末尾且 system_quantity=0);行级 checked_quantity/diff_quantity/is_diff/status 按合并后的商品口径计算;主表计数 total_items/checked_items/diff_items 响应口径以聚合行为准(total_items=行数、checked_items=已盘行数、diff_items=差异行数)。", "同步改动:主表 total_items 商品范围改为按商品计数(addDetail/detailDelete/patternCreate/_countScopeSummary);_recalcCheckSummary 的 checked_items/diff_items 与 finish/_calcQuantityDiffSummary 的盘盈盘亏汇总(detail profit/loss 同口径)均改为商品范围按商品聚合;detail 描述同步。", "代码依据:app/service/systems/stock_check.js#result/#_buildDetailAggregations(新增 _formatMergedGoodsAggregationRow 商品合并格式化器,_formatDetailAggregationRow 仅保留库位行)、#_countScopeSummary(新增)、#_recalcCheckSummary、#finish、#_calcQuantityDiffSummary;回归测试新增「多库位商品合并为一行」用例(全部库位上报、差异=实盘合计-账面快照合计),stock_check 全量 229 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.result(description/response.rows/notes 同步商品范围合并口径)与 stock.check.detail(description 盘盈盘亏口径短语同步)两条;根版本 0.3.258 → 0.3.259、updatedAt 2026-10-09 → 2026-10-10;methods/changes/system.json 新增本条(插入数组首位);其余 22 条 method 未改动(stock.check 分组仍为 24 条)。" ] }, { "version": "0.3.258", "date": "2026-10-09", "type": "updated", "summary": "stock.check.workData / workDataSpaceDetails 空间视图库位排序修正:仅按库位拣货顺序 pick_sequence 升序排序,pick_priority 与库位 id 均不参与(同值保持库位查询顺序)(0.3.257 → 0.3.258)", "methods": [ "stock.check.workData", "stock.check.workDataSpaceDetails" ], "notes": [ "变更内容:space 视图库位排序在 0.3.257(对齐拣货模块 sort_by,pick_sequence 升序 + pick_priority 升序 + 库位 id 兜底)基础上修正为仅按库位拣货顺序排序——pick_sequence 升序,pick_priority 与库位 id 均不参与排序(同值保持库位查询顺序,依赖 Array.sort 稳定排序);行内 goods 排序与分页/过滤行为不变;goods 视图 locations 排序不受影响。", "代码依据:app/service/systems/stock_check.js#_buildSpaceWorkRows(sortedLocations 比较函数简化为仅 pick_sequence 差值;两处 LocationSpace 查询 attributes 移除 pick_priority;JSDoc 与 workData 方法注释同步);回归测试排序用例改造为两阶段(pick_sequence 升序 + pick_priority 双向设置均不影响顺序),stock_check 全量 228 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 与 stock.check.workDataSpaceDetails 两条(description/notes 同步排序口径);根版本 0.3.257 → 0.3.258、updatedAt 保持 2026-10-09;methods/changes/system.json 新增本条(插入数组首位);其余 22 条 method 未改动(stock.check 分组仍为 24 条)。" ] }, { "version": "0.3.257", "date": "2026-10-09", "type": "updated", "summary": "stock.check.workData / workDataSpaceDetails 空间视图库位排序对齐拣货模块:pick_priority 由降序改为升序(与拣货模块 sort_by [ pick_sequence, pick_priority, space_id, item_code ] 一致)(0.3.256 → 0.3.257)", "methods": [ "stock.check.workData", "stock.check.workDataSpaceDetails" ], "notes": [ "变更内容:space 视图库位排序规则由「pick_sequence 升序、pick_priority 降序、同值按库位 id 升序兜底」改为「pick_sequence 升序、pick_priority 升序、同值按库位 id 升序兜底」,与拣货模块(app/service/systems/pick.js sort_by 声明:[ pick_sequence, pick_priority, space_id, item_code ])排序规则一致,保证盘点作业顺序与拣货路径一致;goods 视图 locations 排序不受影响。", "代码依据:app/service/systems/stock_check.js#_buildSpaceWorkRows(sortedLocations 比较函数 priorityDiff 改为 left - right 升序;JSDoc 与 workData 方法注释同步);回归测试新增 space 视图排序用例(pick_sequence 升序 + pick_priority 升序两阶段断言,旧降序实现下第二阶段会失败),stock_check 全量 228 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 与 stock.check.workDataSpaceDetails 两条(description/notes 同步排序口径);根版本 0.3.256 → 0.3.257、updatedAt 保持 2026-10-09;methods/changes/system.json 新增本条(插入数组首位);其余 22 条 method 未改动(stock.check 分组仍为 24 条)。" ] }, { "version": "0.3.256", "date": "2026-10-09", "type": "updated", "summary": "index.getWarehousePanelData is_change=false 时返回空 data 节约流量(传入时间戳未过期时不查库不输出数据;is_change=true 时仍优先输出缓存数据)(0.3.255 → 0.3.256)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "代码依据:app/service/systems/warehouse_panel.js#getPanelData(缓存有最后更新时间时先算 isChange,false 直接返回 { is_change: false, last_change_at, data: {} } 不查库;true 时缓存有 data 直出、无 data 查库补数据保留外部时间戳;无最后更新时间仍查库+设置);app/service/systemMethods/index.js 注释同步;ESLint 0 错误;临时验证脚本 17 用例全 PASS(新增未变化空 data 不查库用例)。", "文档变更范围:methods/system.json 的 module=index 基础模块分组仅更新 index.getWarehousePanelData 一条(description/response.data/notes 同步空 data 语义);根版本 0.3.255 → 0.3.256、updatedAt 保持 2026-10-09;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.255", "date": "2026-10-09", "type": "updated", "summary": "index.getWarehousePanelData 拉取逻辑改为外部驱动:缓存有最后更新时间且有数据直接输出;有最后时间无数据(外部只驱动时间戳)查库补数据并保留外部时间戳;无最后时间才查库并设置最后更新时间;缓存 TTL 10 秒 → 300 秒(0.3.254 → 0.3.255)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "代码依据:app/service/systems/warehouse_panel.js#getPanelData(三段式拉取逻辑:命中直出 / 有外部时间戳无数据查库补 data 保留外部 ts / 无时间戳查库+设置 nowTs;PANEL_CACHE_TTL_SECONDS=300);app/service/systemMethods/index.js 注释同步(force 仅影响 last_change_at 是否可缺省);ESLint 0 错误;临时验证脚本 16 用例全 PASS(新增外部驱动时间戳查库补数据用例,断言保留外部时间戳 1800000000 且写缓存值一致)。", "文档变更范围:methods/system.json 的 module=index 基础模块分组仅更新 index.getWarehousePanelData 一条(response.is_change/last_change_at 描述与 notes 缓存语义同步外部驱动);根版本 0.3.254 → 0.3.255、updatedAt 保持 2026-10-09;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.254", "date": "2026-10-09", "type": "updated", "summary": "index.getWarehousePanelData data 填充有数据源的字段(title/fulfillment/stageOverview/b2b/groupPicking/scatterPicking/packingRank.personal/trend/weeklyEfficiency.intercept),无数据源的字段暂不输出;缓存值升级为 { last_change_at, data }(TTL 10 秒,过期重算)(0.3.253 → 0.3.254)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "代码依据:新增 app/service/systems/warehouse_panel.js(WarehousePanelService:getPanelData 增量判定与缓存、buildPanelData 8 个数据块并行聚合且单块容错、queryFulfillment/queryStageOverview/queryB2b/queryPickingBlock/queryPickingGoodsSku/queryPackingPersonal/queryTrend/queryWeeklyIntercept);app/service/systemMethods/index.js#getWarehousePanelData 改为参数校验后调用 systems 层(原 getWarehousePanelLastChangeCacheKey 移入 systems 层);ESLint 0 错误;临时逻辑脚本 15 用例全 PASS;真实库(127.0.0.1:3307)只读 SQL 验证仓库 100000/1000028 共 90 条查询全部可执行。", "文档变更范围:methods/system.json 的 module=index 基础模块分组仅更新 index.getWarehousePanelData 一条(response.data 描述补充已输出字段、notes 补充缓存语义/口径/未输出字段清单);根版本 0.3.253 → 0.3.254、updatedAt 保持 2026-10-09;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.253", "date": "2026-10-09", "type": "updated", "summary": "index.getWarehousePanelData 响应新增 last_change_at(服务端最后更改时间戳,缓存未命中时为 0),供前端保存并作为下次轮询入参回传(0.3.252 → 0.3.253)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "代码依据:app/service/systemMethods/index.js#getWarehousePanelData(读取缓存后 cachedAt 有效时返回其值,否则返回 0;is_change 判定逻辑不变);ESLint 0 错误,临时验证脚本 13 用例全 PASS(新增 last_change_at 断言:命中缓存返回缓存值、未命中返回 0)。", "文档变更范围:methods/system.json 的 module=index 基础模块分组仅更新 index.getWarehousePanelData 一条(response 新增 last_change_at;description/notes 同步);根版本 0.3.252 → 0.3.253、updatedAt 保持 2026-10-09;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.252", "date": "2026-10-09", "type": "updated", "summary": "index.getWarehousePanelData 新增 force 入参(可选):首次拉取传 true 时 is_change 强制为 true 且 last_change_at 可缺省(0.3.251 → 0.3.252)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "代码依据:app/service/systemMethods/index.js#getWarehousePanelData(force 解析兼容 true/'true'/1;force=true 时 last_change_at 缺省视为 0,传了仍做格式校验;is_change = force || (传入时间戳 < 缓存最后更改时间戳));ESLint 0 错误,临时验证脚本 13 用例全 PASS(含 force=true 缺省时间戳、force=1、force='true'、force=false 缺省时间戳仍报参数错误)。", "文档变更范围:methods/system.json 的 module=index 基础模块分组仅更新 index.getWarehousePanelData 一条(params 新增 force、last_change_at 的 required 由 true 改为 false 并同步说明;description/response/notes 同步);根版本 0.3.251 → 0.3.252、updatedAt 保持 2026-10-09;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.251", "date": "2026-10-09", "type": "added", "summary": "基础模块新增 index.getWarehousePanelData 仓库面板数据接口:按仓库增量变更检测,入参 last_change_at 小于缓存最后更改时间戳时返回 is_change=true,data 暂为空(0.3.250 → 0.3.251)", "methods": [ "index.getWarehousePanelData" ], "notes": [ "代码依据:app/service/systemMethods/index.js#getWarehousePanelData + #getWarehousePanelLastChangeCacheKey;缓存键 index:warehousePanel:lastChangeAt:{warehouseId}(按仓库存储,通过 getCacheAsync 读取);需要登录(isNeedLogin=true),免权限/免鉴权/免系统日志,ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=index 基础模块分组新增 1 条 method(插在 index.loadWarehouses 之后);根版本 0.3.250 → 0.3.251、updatedAt 2026-10-06 → 2026-10-09;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "0.3.250", "date": "2026-10-06", "type": "updated", "summary": "stock.check.workData 新增 only_abnormal 入参(可选,兼容 onlyAbnormal 驼峰写法):只看未盘和差异——过滤在 keyword 之后、分页切片之前完成,三视图均生效(location 视图按行 status=unchecked 或 has_unknown 保留;goods 视图按未盘行或明盘 is_diff=1 保留,盲盘仅按未盘;space 视图按行内 goods 子项过滤 status=unchecked 或明盘数量差异、空行整体移除;total 为过滤后行数)(0.3.249 → 0.3.250)", "methods": [ "stock.check.workData" ], "notes": [ "变更内容:stock.check.workData params 新增 only_abnormal(boolean,body,可选,向后兼容,兼容 onlyAbnormal 驼峰写法;未传或非 true(false/0/空串/缺省)不过滤)——过滤在 keyword 之后、分页切片之前完成(与 keyword 叠加,keyword 先过滤、only_abnormal 后过滤;total 为过滤后行数),三视图均生效:①location 视图仅保留 status=unchecked(未盘)或 has_unknown=true(含未知商品记录,未知商品无账面、差异=实盘-0=盘盈视为差异)的行,空库位标记(is_empty)后 status=checked 视为已盘点、不保留;②goods 视图仅保留未盘行(locations 均无 record_ids,即无任何作业记录)或明盘差异行(is_diff=1),盲盘(mode=blind)无数量字段仅按未盘过滤(已盘行全部移除);③space 视图按行内 goods 子项过滤(保留 status=unchecked 子项,明盘另保留 checked_quantity≠system_quantity 的数量差异子项,system_quantity 口径=可用+锁定),过滤后 goods 为空的行整体移除。", "代码依据:app/service/systemMethods/stock/check.js#workData(only_abnormal/onlyAbnormal 蛇形驼峰兼容与透传)+ app/service/systems/stock_check.js#workData(abnormalRequested=onlyAbnormal===true||'true'||1,keywordFilteredRows 后调用 _filterAbnormalWorkRows(resolvedView, rows, check.mode!=='blind'),再分页切片;新增 _filterAbnormalWorkRows 私有方法按视图过滤);回归测试新增 5 用例(location/goods 明盘/space 明盘/space 盲盘/keyword 叠加)全部通过、workData 相关 43 用例通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params 新增 only_abnormal、description/response.rows/response.total/notes 同步过滤口径;headers/errors/isNeedAuth/isNeedLogin 不变);根版本 0.3.249 → 0.3.250、updatedAt 保持 2026-10-06;methods/changes/system.json 新增本条(插入数组首位);其余 23 条 method 未改动(stock.check 分组仍为 24 条)。" ] }, { "version": "0.3.249", "date": "2026-10-06", "type": "updated", "summary": "盘点账面口径全量统一为可用+锁定(SUM(available_quantity+locked_quantity)):result 库位行/空标记盘亏、report 重算、finish 差异汇总、detail 盘盈盘亏汇总、addDetail 拆行快照(0.3.248 → 0.3.249)", "methods": [ "stock.check.workData", "stock.check.workDataDetail", "stock.check.workDataSpaceDetails", "stock.check.result", "stock.check.report", "stock.check.finish", "stock.check.detail", "stock.check.addDetail" ], "notes": [ "变更内容:全部盘点账面口径统一为 wms_storage SUM(available_quantity+locked_quantity)(=可用+锁定)——①result 库位行 stocks 账面与空库位标记盘亏(_buildDetailAggregations/_formatDetailAggregationRow);②report 重算 diff_items 的库位行按商品账面与空标记库位账面(_recalcCheckSummary);③finish 差异汇总复用 _recalcCheckSummary 口径;④detail profit_total/loss_total 汇总复用同口径;⑤addDetail 按库位拆行写入的明细快照 system_quantity=该库位库存 SUM(可用+锁定);与盘点作业视图(workData/workDataDetail/workDataSpaceDetails,0.3.248 已改)完全一致。商品行差异仍以明细账面快照(system_quantity 列)对比。", "代码依据:app/service/systems/stock_check.js#_recalcCheckSummary/#_buildDetailAggregations/#_formatDetailAggregationRow/#addDetail(attributes 全部改为 literal('SUM(available_quantity + locked_quantity)'));回归测试 222/222 通过、ESLint 0 错误(测试 helper fetchStorageQuantity/拆行断言/多库位拆行用例同步改口径)。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 8 条 method(workData/workDataDetail/workDataSpaceDetails/result/report/finish/detail/addDetail 的 description/notes 同步库位账面=可用+锁定口径);根版本 0.3.248 → 0.3.249、updatedAt 2026-10-05 → 2026-10-06;methods/changes/system.json 新增本条(插入数组首位);其余 15 条 method 未改动(stock.check 分组仍为 23 条)。", "库表维护源说明:维护源为库表(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 到临时文件往返校验,保持库与文件一致。" ] }, { "version": "0.3.248", "date": "2026-10-05", "type": "updated", "summary": "盘点作业数据接口(stock.check.workData/workDataDetail/workDataSpaceDetails)库位账面改为可用+锁定(SUM(available_quantity+locked_quantity))并新增 locked_quantity 锁定数量字段(0.3.247 → 0.3.248)", "methods": [ "stock.check.workData", "stock.check.workDataDetail", "stock.check.workDataSpaceDetails" ], "notes": [ "变更内容:goods 视图 locations 各项与 space 视图 goods 子项的库位账面 system_quantity 由 wms_storage SUM(quantity) 改为 SUM(available_quantity+locked_quantity)(=可用+锁定),并新增 locked_quantity(该库位锁定数量,SUM(locked_quantity));盘点数量 quantity/checked_quantity 口径不变;盲盘仍不返回任何数量字段。", "代码依据:app/service/systems/stock_check.js#_buildGoodsWorkRows/#_buildSpaceWorkRows(Storage 查询 attributes 增加 literal('SUM(available_quantity + locked_quantity)') 与 fn('SUM', col('locked_quantity')));result/report/finish 的差异汇总口径不变(仍按 quantity 与明细快照);回归测试 222/222 通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData、stock.check.workDataDetail 与 stock.check.workDataSpaceDetails 三条(description/response.rows/notes 同步库位账面=可用+锁定口径与 locked_quantity 字段);根版本 0.3.247 → 0.3.248、updatedAt 保持 2026-10-05;methods/changes/system.json 新增本条(插入数组首位);其余 20 条 method 未改动(stock.check 分组仍为 23 条)。", "库表维护源说明:维护源为库表(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 到临时文件往返校验,保持库与文件一致。" ] }, { "version": "0.3.247", "date": "2026-10-05", "type": "updated", "summary": "stock.check.workData / workDataDetail 的 goods 视图明盘库位同时输出账面数量(system_quantity)与盘点数量(quantity)两个字段(0.3.246 → 0.3.247)", "methods": [ "stock.check.workData", "stock.check.workDataDetail" ], "notes": [ "变更内容:goods 视图明盘(mode=open)每库位由单一 quantity(实盘合计)改为同时输出 system_quantity(该库位账面数量,wms_storage 该库位 SUM(quantity),无库存记录库位为 0)与 quantity(该库位盘点数量=实盘合计,未盘库位为 0)两字段区分开;盲盘仍不返回任何数量字段。", "代码依据:app/service/systems/stock_check.js#_buildGoodsWorkRows(Storage 查询 attributes 增加 fn('SUM', col('quantity')) 按 stock+space 分组汇总,构建 stockId→spaceCode→账面数量映射;buildLocationItem 明盘输出双数量字段);行级 checked_quantity 仍为 locations.quantity 合计、diff/is_diff 仅存在作业记录的行计算(口径不变);回归测试 222/222 通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 与 stock.check.workDataDetail 两条(description/response.rows/notes 同步明盘库位双数量字段口径);根版本 0.3.246 → 0.3.247、updatedAt 保持 2026-10-05;methods/changes/system.json 新增本条(插入数组首位);其余 21 条 method 未改动(stock.check 分组仍为 23 条)。", "库表维护源说明:维护源为库表(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 到临时文件往返校验,保持库与文件一致。" ] }, { "version": "0.3.246", "date": "2026-10-05", "type": "updated", "summary": "stock.check.workData / workDataDetail 的 goods 视图 locations 改为商品所在全部库位列表(明盘显示库位+数量、盲盘只显示库位;未盘行不误显盘亏差异)(0.3.245 → 0.3.246)", "methods": [ "stock.check.workData", "stock.check.workDataDetail" ], "notes": [ "变更内容:_buildGoodsWorkRows 的 locations 由「仅已盘库位(按首条记录 id 升序)」改为「商品所在全部库位列表」——基础库位取自 wms_storage(任务 stock_id 集合 + is_enabled=1 未删除,DISTINCT space_id)经库位表取 space_code 并按拣货路径排序(pick_sequence 升序、pick_priority 降序、库位 id 升序兜底);无库存但已有作业记录的库位按首条记录 id 升序追加在末尾;空库位(location_code 空)组仍排在最后;未盘库位输出空信息(checked_at/checker_name=null、record_ids/images 空数组、明盘 quantity=0)。", "差异口径:明盘 checked_quantity=locations 各库位 quantity 合计(未盘行恒 0);diff_quantity/is_diff 仅对存在作业记录(detailRecords.length>0)的行计算,未盘行恒 0(避免未盘行误显盘亏差异——此前 locations 非空导致未盘行 diff_quantity=0-账面为负);盲盘仍不返回任何数量字段。", "代码依据:app/service/systems/stock_check.js#_buildGoodsWorkRows(workData 与 workDataDetail goods 明细分支复用同一构建函数);回归测试 222/222 通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 与 stock.check.workDataDetail 两条(description/response.rows/notes 同步 goods 视图 locations 商品所在全部库位列表口径);根版本 0.3.245 → 0.3.246、updatedAt 2026-10-04 → 2026-10-05;methods/changes/system.json 新增本条(插入数组首位);其余 21 条 method 未改动(stock.check 分组仍为 23 条)。", "库表维护源说明:维护源为库表(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 到临时文件往返校验,保持库与文件一致。" ] }, { "version": "0.3.245", "date": "2026-10-04", "type": "added", "summary": "新增 stock.check.workDataDetail 盘点明细单行作业数据接口(workData 单行版,仅库位任务明细):入参 detail_id(库位范围行,兼容 detailId 驼峰),返回统一 success 包装、data 为单行作业数据(结构与 workData location 视图单行一致);仅任务状态 approved/checking 可拉取(0.3.244 → 0.3.245)", "methods": [ "stock.check.workDataDetail" ], "notes": [ "变更内容:ALL_METHOD_NAMES 新增 workDataDetail(22→23)、_noNeedLog 查询类清单新增 workDataDetail;方法层 stock.check.workDataDetail 兼容 detail_id/detailId 驼峰写法、warehouse_id 服务端自动注入;系统层仅库位任务明细(scope_type=location)支持,返回结构与 workData location 视图单行一致(detail_id/location_id/location_code/location_name/status/has_unknown/is_empty/checked_at/checkers/goods)。", "校验口径:detail_id 非正整数 400『盘点明细ID不能为空』;明细不存在 400『盘点明细不存在』;scope_type 非 location 400『仅库位任务明细支持拉取单行作业数据』;任务不存在 400『盘点任务不存在』;任务状态非 approved/checking 400 拒绝(与 stock.check.workData 同口径)。", "代码依据:app/service/systemMethods/stock/check.js#workDataDetail + app/service/systems/stock_check.js#workDataDetail(复用 _buildLocationWorkRows);回归测试 216/216 通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.workDataDetail 一条(位于 stock.check.workData 之后);根版本 0.3.244 → 0.3.245、updatedAt 保持 2026-10-04;methods/changes/system.json 新增本条(插入数组首位);其余 22 条 method 未改动(stock.check 分组由 22 条增至 23 条)。", "库表维护源说明:维护源为库表(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 到临时文件往返校验,保持库与文件一致。" ] }, { "version": "0.3.244", "date": "2026-10-04", "type": "updated", "summary": "stock.check.workData 新增 keyword 入参(可选,向后兼容):仅库位任务(location 视图)按行 location_code/location_name 模糊匹配(不区分大小写)过滤任务明细后再分页(0.3.243 → 0.3.244)", "methods": [ "stock.check.workData" ], "notes": [ "变更内容:params 新增 keyword(string,可选,向后兼容)——先分流:仅库位任务(type=location/all,即服务端解析视图为 location)生效;生效时按 location 视图行字段 location_code(优先明细快照,缺失回退库位表 space_code)与 location_name(custom_name 兜底 space_code)做模糊匹配(contains、不区分大小写)过滤任务明细后再分页返回;非库位任务(goods/store,space/goods 视图)忽略该参数;keyword 为空/纯空白视为未传不过滤。", "分页口径:过滤在分页切片之前完成,total 为过滤后的行数,rows 为过滤后的当前页行(分页仍按 pagination.{page,pageSize} 切片,与既有口径一致)。", "代码依据:app/service/systemMethods/stock/check.js#workData(包装层透传 keyword)+ app/service/systems/stock_check.js#workData(normalizedKeyword=String(keyword||\"\").trim().toLowerCase(),resolvedView===\"location\" 且非空时按 location_code/location_name includes 过滤);回归测试 214/214 通过、ESLint 0 错误。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(params 新增 keyword、description/response.rows/response.total 同步过滤口径;headers/errors/isNeedAuth/isNeedLogin 不变);根版本 0.3.243 → 0.3.244、updatedAt 保持 2026-10-04;methods/changes/system.json 新增本条(插入数组首位);其余 21 条 method 未改动(stock.check 分组仍为 22 条)。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 与变更记录后,同步回填开发库与生产库(import 当前 system.json → export 往返校验);生产库此前停留在 0.3.240,本次回填一并同步 0.3.241(detail 精简)、0.3.242(workData 返回 view)、0.3.243(waybill 主单号数组)三批累积差异。" ] }, { "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", "type": "updated", "summary": "docs 全局 Header 的 platform 下拉修正:「微信端」取值由 wx 改为 miniprogram,并移除重复的「小程序端」(miniProgram)选项", "methods": [ "/api/docs" ], "notes": [ "依据:app/service/system.js#ALLOWED_PLATFORMS 含小写 miniprogram(校验前 toLowerCase,实际建议使用规范值);app/service/systems/wechat.js 登录链路 platform_code 兜底为 'miniprogram';接口日志实测客户端 platform 取值只有 web/pda/miniprogram,从未出现 wx/miniProgram。", "文档变更范围:methods/system.json 根 headers 的 platform.list——「微信端」value 由 wx 改为 miniprogram,删除「小程序端」(value=miniProgram,与微信端同义且大小写与规范不一致);platform 描述示例补充 miniprogram;project 列表及其它 header 不变;根版本 0.3.226 → 0.3.227、updatedAt 保持 2026-10-02;methods/changes/system.json 新增本条(插入数组首位);所有 method 条目未改动。", "库表维护源说明:wms_method_doc_meta.headers 与 version 同步更新后按 import→export 往返校验,保持库与文件一致。" ] }, { "version": "2026.10.02-stock-check-work-data-status-guard", "date": "2026-10-02", "type": "updated", "summary": "workData 新增状态限制:仅 approved/checking 任务可拉取盘点作业数据,其他状态返回 400 并说明原因", "methods": [ "stock.check.workData" ], "notes": [ "代码依据:app/service/systems/stock_check.js#workData 在任务存在校验之后新增状态守卫——check.status 不在 REPORT_ALLOWED_STATUSES(approved/checking,与 report/finish 一致)内时抛 400(createBusinessError(message, 400)),文案『当前状态({STOCK_CHECK_STATUS_LABELS 中文标签,无标签回退状态值})不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取』;本次仅同步文档,未改动任何代码(代码变更已通过 ESLint 与 193 条集成测试)。", "状态限制口径:仅任务状态 approved(审核完成)或 checking(盘点作业中)可拉取盘点作业数据;created 已创建/submitted 待审核/rejected 已驳回/completed 已完成/cancelled 已取消 均返回 400;与 report(盘点作业上报,approved 首次上报自动转 checking)及 finish(完成盘点)使用同一 REPORT_ALLOWED_STATUSES 常量。", "400 文案:盘点任务ID不能为空 / 视图类型非法(仅支持 location/goods/space)→ 当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取 → 盘点任务不存在(校验顺序:id → view → 任务存在 → 状态守卫)。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.workData 一条(errors 的 400 拆分三条并新增状态限制文案、description/notes 补充状态限制口径);根版本 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 无损。" ] }, { "version": "2026.10.02-stock-check-work-data", "date": "2026-10-02", "type": "added", "summary": "新增 stock.check.workData 盘点作业数据接口:一个接口按 view 入参驱动三种视图(location 库位结构含未知商品子列表;goods 商品列表按库位子列表;space 聚合库位列表按拣货路径排序),明盘显示数量、盲盘隐藏数量", "methods": [ "stock.check.workData" ], "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『盘点任务不存在』;按 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(避免未盘行误显盘亏差异)。", "排序口径: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),不记录操作日志。", "文档变更范围: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 条)。", "库表维护源说明:维护源为库表(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 无损。" ] }, { "version": "2026.10.01-stock-check-detail-delete-batch", "date": "2026-10-01", "type": "updated", "summary": "detailDelete 支持批量删除:入参 detail_ids(兼容旧 detail_id 单值),返回改为 { deleted_count, deleted_ids, skipped_ids, total_items },未命中跳过不报错", "methods": [ "stock.check.detailDelete" ], "notes": [ "代码依据:app/service/systems/stock_check.js(detailDelete:id 非法抛 400『盘点任务ID不能为空』、任务不存在抛 400『盘点任务不存在』、状态非 created/rejected 抛 400『当前状态(xxx)不允许删除明细』、_normalizeIdList 归一化(单值自动转数组、去重、仅保留正整数)后为空抛 400『请至少选择一个明细』、超过 200 抛 400『单次最多删除 200 条明细』;按 id in ids + check_id + warehouse_id 仓库隔离查询,未命中 ID 计入 skipped_ids 不报错;命中明细批量 destroy 并防御性清理 wms_stock_check_record,重算主表 total_items;返回 { deleted_count, deleted_ids, skipped_ids, total_items },deleted_ids/skipped_ids 保持入参顺序)+ app/service/systemMethods/stock/check.js(detailDelete 入参改为 detail_ids 数组,兼容 detailIds 驼峰与旧 detail_id 单值,优先级 detail_ids > detailIds > detail_id,单值自动转数组);本次仅同步文档,未改动任何代码。", "批量口径:单次上限 200;单值自动转数组并去重;未命中的明细ID计入 skipped_ids 不报错;命中批量删除并防御清理作业记录(正常流程 created/rejected 不应有记录);删除后重算 total_items;deleted_ids/skipped_ids 保持入参顺序。", "响应结构变更(兼容性影响):由旧版 { detail_id, deleted, total_items } 变更为 { deleted_count, deleted_ids, skipped_ids, total_items },旧前端需按新结构适配。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.detailDelete(params 改为 detail_ids 数组+兼容字段 detailIds/detail_id、response 改为批量结构、errors 同步批量文案、description/notes 同步);根版本 0.3.223 → 0.3.224、updatedAt 保持 2026-10-01;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动(stock.check 分组仍为 19 条)。", "库表维护源说明:维护源为库表(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 分组共 19 条 method 无损。" ] }, { "version": "2026.10.01-stock-check-add-detail-location-ids", "date": "2026-10-01", "type": "updated", "summary": "addDetail 支持 location_ids 按库位ID直查添加(与 stock_ids 按任务类型区分维度),addLocationDetail 转调 addDetail 保留兼容", "methods": [ "stock.check.addDetail", "stock.check.addLocationDetail" ], "notes": [ "代码依据:app/service/systems/stock_check.js(addDetail 新增 locationIds 入参与 _addLocationRowsByIds 库位ID直查路径、addLocationDetail 薄封装转调 addDetail 并映射返回结构)+ app/service/systemMethods/stock/check.js(addDetail/addLocationDetail 新增 location_ids 入参并兼容 locationIds 驼峰,location_ids 优先);本次仅同步文档,未改动任何代码。", "分派口径:addDetail 按任务盘点类型区分维度——type=store/goods 接受 stock_ids(传 locations 报 400『当前盘点类型按商品盘点,请传 stock_ids』、传 location_ids 报 400『当前盘点类型按商品盘点,不能添加库位明细』);type=all/location 接受 locations 或 location_ids(传 stock_ids 报 400『当前盘点类型按库位盘点,请传 locations 或 location_ids(如需按商品盘点请创建 type=goods 任务)』)。", "ID 直查与幂等口径:location_ids 优先于 locations(两者都传时 locations 忽略),按 wms_location_space.id+warehouse_id 直查校验(不再按 space_code 二次解析),查不到的 ID 记入新增返回字段 invalid_location_ids(不报错);幂等按 check_id+location_code(uk_check_location 唯一索引),location_ids 路径跳过项按库位ID记入 skipped;商品行幂等仍按 uk_check_stock。", "兼容说明:addLocationDetail 保留旧接口名与返回结构 { added, skipped, invalid_location_ids, total_items },薄封装转调 addDetail 库位ID直查路径(stockIds/locations 置空、传 locationIds),返回结构过滤 invalid_locations/invalid_stock_ids;转发前保留旧口径参数校验(任务ID不能为空、库位ID不能为空、单次上限 200)。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.addDetail(params 新增 location_ids、response 新增 invalid_location_ids、description/errors/notes 同步新口径)并新增 stock.check.addLocationDetail 一条(此前未登记,分组由 18 条增至 19 条);根版本 0.3.222 → 0.3.223、updatedAt 保持 2026-10-01;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "库表维护源说明:维护源为库表(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 分组共 19 条 method 无损。" ] }, { "version": "2026.10.01-stock-check-unknown-goods", "date": "2026-10-01", "type": "updated", "summary": "盘点作业上报支持未知商品(stock_id 可空 + barcode/item_name,仿收货明细);图片独立维护(上传 businessType=stock_check_record,查询挂载 images,删除清理)", "methods": [ "stock.check.report", "stock.check.result", "stock.check.recordList", "stock.check.recordDelete", "stock.check.export" ], "notes": [ "代码依据:app/service/systems/stock_check.js(report/_resolveStockIdByBarcode/result/_buildDetailAggregations/_formatDetailAggregationRow/_attachRecordImages/recordList/recordDelete/exportStockChecks/_generateAndUploadStockCheckExcel)+ app/service/systemMethods/stock/check.js(report 新增入参 barcode/item_name 透传);未改动任何业务代码之外的逻辑。", "迁移依据:database/migrations/20261001100000-support-unknown-goods-in-stock-check-record.js(wms_stock_check_record:stock_id 改可空(NULL=未知商品,唯一索引 uk_detail_stock_location 中 NULL 不参与唯一约束)+ 新增 barcode VARCHAR(100) 可空/item_name VARCHAR(255) 可空),本地与生产均已执行。", "未知商品上报口径:report 新增入参 barcode/item_name;stock_id 与 barcode 至少传一项——仅传 barcode 先按条码匹配系统商品(wms_stock_barcodes 按 barcode+本仓库,关联 StockWarehouse 校验商品属于本仓库),命中回填 stock_id 走已知商品逻辑(商品明细行校验与明细商品一致),未命中记录未知商品(stock_id=NULL+barcode+item_name,item_name 缺省为 barcode);都未传沿用原报错口径;未知商品覆盖式查重 where { detail_id, stock_id:null, barcode, location_code }(应用层查重,唯一索引不约束 NULL 行,并发兜底逻辑对未知商品同样降级更新)。", "差异口径:未知商品账面 0,实盘=盘盈(差异=实盘-0),必然计入 diff_items;result 行级新增 unknown_items [{ barcode, item_name, checked_quantity }](stock_id 为空的记录按条码归组、条码升序,已计入行级 checked_quantity/diff_quantity/is_diff);finish 未知商品实盘>0 计入盘盈合计与差异行数。", "图片独立维护口径:上传走通用上传接口(businessType='stock_check_record' + businessId=作业记录ID,建 FileReference,仿收货 receivingItem);result 的 records 与 recordList 的 rows 每条挂载 images [{ id, url }](wms_file_reference 关联 wms_file.file_url,无图片返回空数组);recordDelete 删除记录后清理关联图片引用(失败仅告警不影响主流程);report 不接收图片。", "查询/导出显示口径:recordList 与 export Sheet2 未知商品(stock_id 为空)item_code 显示扫描条码(barcode)、item_name 显示上报名称快照(item_name 或 barcode 兜底);已知商品维持原口径(明细表/wms_stock_warehouse 商品快照)。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.report/result/recordList/recordDelete/export 五条(report 新增 params barcode/item_name、response record 补充 barcode/item_name/stock_id 可空;result 新增 response unknown_items 与 records.images;recordList 补充 rows barcode/item_name/images 口径;export 补充 Sheet2 未知商品列口径;recordDelete 补充图片清理说明);根版本 0.3.221 → 0.3.222、updatedAt 保持 2026-10-01;methods/changes/system.json 新增本条(插入数组首位);其余 13 条 method 未改动。", "库表维护源说明:维护源为库表(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 无损。" ] }, { "version": "2026.10.01-stock-check-detail-stock-mount", "date": "2026-10-01", "type": "updated", "summary": "stock.check.detail 商品行新增挂载 stock 对象(stockWarehouse.getStockDetails 全局商品信息:条码/图片/管理标识等,带缓存),库位行不挂载", "methods": [ "stock.check.detail" ], "notes": [ "代码依据:app/service/systems/stock_check.js#detail(对 scope_type=goods 行按 stock_id 去重后批量调用 ctx.service.systems.stockWarehouse.getStockDetails(goodsStockIds, { warehouseId }),结果按 stock_id 挂载到各行 stock 字段,未命中为 null;库位行不挂载)与 app/service/systems/storage/stock_warehouse.js#getStockDetails(带缓存批量取商品详情,key=cache:stock_detail:{warehouseId}:{stockId},默认 TTL 300 秒);未改动任何业务代码。", "挂载口径: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 货主ID/packing_requirements 打包要求/pick_requirements 拣货要求/recheck_requirements 复核要求/merge_requirements 要求合并开关/stock_unit 库存单位/barcodes 条码数组;仅 scope_type=goods 商品行挂载(未命中 stock=null),scope_type=location 库位行不挂载;范围行原有 15 字段与其余返回结构不变。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.detail 一条(description/response.rows/notes 补充商品行 stock 挂载口径);根版本 0.3.220 → 0.3.221、updatedAt 保持 2026-10-01;methods/changes/system.json 新增本条(插入数组首位);其余 17 条 method 未改动。", "库表维护源说明:维护源为库表(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 无损。" ] }, { "version": "2026.10.01-stock-check-list-store-name", "date": "2026-10-01", "type": "updated", "summary": "stock.check.list 返回行新增 store_name 货主名称(合约货主备注 store_remask 优先、公司全称 company_name 兜底)", "methods": [ "stock.check.list" ], "notes": [ "代码依据:app/service/systems/stock_check.js#list(返回前调用 _resolveStoreNameMap() 批量解析货主名称,每行新增 store_name 字段)与 #_resolveStoreNameMap(货主名称解析方法);未改动任何业务代码。", "解析口径:优先 wms_store_warehouse.store_remask(合约货主备注,按 store_id+warehouse_id 匹配);无合约或备注为空时回退 wms_store.company_name(公司全称);两者均查不到时返回空字符串 ''。", "文档变更范围: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 未改动。", "库表维护源说明:维护源为库表(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 无损。" ] }, { "version": "2026.10.01-stock-check-list-filters", "date": "2026-10-01", "type": "updated", "summary": "stock.check.list 查询条件扩展:修复 type 筛选不生效,新增 mode/货主 store_id/创建时间 created_at/盘点开始时间 start_time/盘点结束时间 end_time 筛选(时间支持单值 gte 与 [from,to] 区间)", "methods": [ "stock.check.list" ], "notes": [ "代码依据:app/service/systems/stock_check.js#list(新增 type/mode 枚举筛选与 created_at/start_time/end_time 时间筛选,status/store_id/keyword 已有不变)与 app/service/systemMethods/stock/check.js#list(prepareWhereContext 提取 where,支持 {operator,value} 标准结构);未改动任何业务代码。", "修复点:原方法层 list 未从 where 提取 type(where.type 传入不生效);本次方法层补齐 type/mode/created_at/start_time/end_time 提取(whereValue 优先、data 顶层字段兜底兼容),status/keyword 已有逻辑不变。", "筛选口径:status/type/mode 单值 eq、数组 in(归一化去重);store_id 数值 eq;keyword 对 check_no/title 模糊匹配;全部筛选叠加仓库隔离(ctx.user.store_id)。", "时间范围语义:created_at/start_time/end_time 口径一致——单值=gte 从该值起;[from,to] 两端合法=between 闭区间、仅 from=gte、仅 to=lte;非法时间值静默忽略。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.list 一条(params 新增 where.type/where.mode/where.created_at/where.start_time/where.end_time);根版本 0.3.218 → 0.3.219、updatedAt 更新为 2026-10-01;methods/changes/system.json 新增本条(插入数组首位);其余 17 条 method 未改动。", "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta),methods/system.json 是导出产物;写入 JSON 后同步回填开发库与生产库(import 当前 system.json → export 回写往返校验),stock.check 分组共 18 条 method 无损。" ] }, { "version": "2026.09.30-stock-check-time-fields", "date": "2026-09-30", "type": "updated", "summary": "盘点主表移除盘点日期 check_date,改用 start_time(第一个盘点明细写入时间)/end_time(完成盘点时间)表达盘点时间线;导出 Sheet1 移除盘点日期列", "methods": [ "stock.check.create", "stock.check.patternCreate", "stock.check.report", "stock.check.finish", "stock.check.detail", "stock.check.result", "stock.check.list", "stock.check.export" ], "notes": [ "代码依据:app/service/systems/stock_check.js——create/patternCreate 不再写 check_date;_formatCheckRow 不再返回 check_date(保留 start_time/end_time);report 首次写入明细时主表 start_time 为空则补写(盘点开始时间=第一个盘点明细写入的时间);finish 写 end_time(盘点结束时间=完成盘点的时间);_generateAndUploadStockCheckExcel 的 Sheet1 表头已移除「盘点日期」列(保留开始时间/结束时间列)。", "迁移文件:database/migrations/20260930150000-remove-check-date-from-wms-stock-check.js——移除 wms_stock_check 的 check_date 字段与 idx_warehouse_check_date 联合索引,start_time/end_time 注释对齐新语义(类型不变);本地与生产均已执行。", "语义口径:盘点时间线由 start_time/end_time 表达——start_time=盘点开始时间(第一个盘点明细写入的时间,report 首次写入明细时补写)、end_time=盘点结束时间(完成盘点的时间,finish 时写入);create/patternCreate 均不传盘点时间。", "接口兼容性影响:create/patternCreate 响应移除 check_date 字段(主表已无该字段);detail/result/list 返回主表行的字段清单移除 check_date;finish 响应结构不变(不返回 end_time,语义体现在主表回填与 description);export Sheet1 列移除「盘点日期」(保留开始/结束时间列);入参、errors、headers、鉴权(isNeedAuth=false、isNeedLogin=true)均不变;未改动任何业务代码。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 8 条(create/patternCreate/report/finish/detail/result/list/export);根版本 0.3.217 → 0.3.218、updatedAt 保持 2026-09-30;methods/changes/system.json 新增本条(插入数组首位);其余 10 条 method 未改动。", "库表维护源说明:维护源为库表(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 无损。" ] }, { "version": "2026.09.30-stock-check-create-no-date", "date": "2026-09-30", "type": "updated", "summary": "create 移除 check_date 入参,盘点日期固定为今天(与 patternCreate 口径一致)", "methods": [ "stock.check.create" ], "notes": [ "代码依据:app/service/systems/stock_check.js#create——入参解析已无 check_date(仅 warehouseId/title/type/mode/storeId/remark/creatorId/creatorName),checkDateValue = new Date() 后 setHours(0,0,0,0) 固定今天 00:00:00 写入主表 check_date;app/service/systemMethods/stock/check.js#create——data 解构已无 check_date,JSDoc 同步「盘点日期固定为今天,前端不传」;与 patternCreate 口径一致(systems 层 #patternCreate 同样 setHours(0,0,0,0) 固定今天)。", "规则口径:盘点日期固定为今天 00:00:00,前端不传 check_date(响应中仍返回 check_date 字段);创建后主表 status=created、detail_status=none_checked,其余创建口径(单号生成、范围类型语义、盘点方式规则)均不变。", "接口兼容性影响:params 移除 check_date(原为必填项,现前端不传;若前端仍传会被方法层忽略,不影响接口可用性与既有调用);errors 400 文案移除「盘点日期不能为空且格式必须合法」;headers/response 结构/鉴权(isNeedAuth=false、isNeedLogin=true)均不变;未改动任何业务代码。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.create 一条(params 移除 check_date、description/notes/errors 同步口径);根版本 0.3.216 → 0.3.217、updatedAt 保持 2026-09-30;methods/changes/system.json 新增本条(插入数组首位);其余 17 条 method 未改动。", "库表维护源说明:维护源为库表(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 无损。" ] }, { "version": "2026.09.30-stock-check-location-blind-only", "date": "2026-09-30", "type": "updated", "summary": "create 按库位盘点(all/location)一律盲盘,忽略前端传入的 mode;按商品盘点(store/goods)仍按传入值", "methods": [ "stock.check.create" ], "notes": [ "代码依据:app/service/systems/stock_check.js#create——normalizedType 校验通过后,type 为 all/location 时强制 normalizedMode='blind'(忽略前端传入的 mode);type 为 store/goods 时保持传入值(缺省 open);method 层 JSDoc 已同步该口径(按库位盘点一律盲盘)。", "规则口径:按库位盘点(type=all/location,明细为库位行 scope_type=location)一律盲盘(blind),前端传入的 mode 不生效;按商品盘点(type=store/goods,明细为商品行 scope_type=goods)按传入值,默认明盘(open)。", "接口兼容性影响:mode 仍为可选字符串参数(open/blind),入参结构、必填项、响应结构、errors、headers、鉴权(isNeedAuth=false、isNeedLogin=true)均不变;仅 all/location 场景服务端强制覆盖 mode 为 blind(前端传 blind 行为不变,传 open 落库值为 blind),对既有调用完全兼容。", "文档变更范围:methods/system.json 的 module=stock.check 分组仅更新 stock.check.create 一条(mode 参数描述补充规则、notes 补充规则说明);根版本 0.3.215 → 0.3.216、updatedAt 保持 2026-09-30;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 后,同步回填开发库与生产库(import 当前 system.json → export 回写往返校验),保持库与文件一致;stock.check 分组共 18 条 method 无损。" ] }, { "version": "2026.09.30-stock-check-pattern-fixed-mode", "date": "2026-09-30", "type": "updated", "summary": "patternCreate 移除 mode/check_date 入参:库位类定式一律盲盘、商品类定式一律明盘,盘点日期固定为今天", "methods": [ "stock.check.patternCreate" ], "notes": [ "代码依据:app/service/systemMethods/stock/check.js#patternCreate(入参仅 pattern_id/patternId 驼峰别名/title/remark,不再解析 mode/check_date)+ app/service/systems/stock_check.js#patternCreate(normalizedMode=pattern.type==='location'?'blind':'open';checkDateValue=new Date() 后 setHours(0,0,0,0) 固定今天;主表 mode/check_date 直接取服务端固定值)。", "固定规则:库位类定式(type=location,即 empty_location)一律盲盘(blind)、商品类定式(type=goods,其余 4 个定式)一律明盘(open);盘点日期固定为今天 00:00:00;前端不再传 mode/check_date。", "接口兼容性影响:params 移除 mode/check_date 两个可选参数(前端若仍传会被忽略,不影响接口可用性与既有调用);errors 400 文案移除「盘点方式不合法,仅支持 open/blind」与「盘点日期格式不合法」;headers/response 结构/鉴权(isNeedAuth=false、isNeedLogin=true)均不变。", "文档变更范围:methods/system.json 的 stock.check.patternCreate 条目更新(description/params/errors/notes);根版本 0.3.214 → 0.3.215、updatedAt 保持 2026-09-30;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 后,同步回填开发库与生产库(import 当前 system.json → export 回写往返校验),保持库与文件一致;stock.check 分组共 18 条 method 无损。" ] }, { "version": "2026.09.30-stock-check-patterns", "date": "2026-09-30", "type": "added", "summary": "新增定式快速创建盘点任务:patternList 拉取 5 个注册定式(空库位/错发/临期/静态/预警),patternCreate 按定式 id 收集对象创建盘点任务并直接进入待审核(submitted);静态盘点写入 wms_stock_static_check_task 并排除已盘商品", "methods": [ "stock.check.patternList", "stock.check.patternCreate" ], "notes": [ "代码依据:app/service/systems/stock_check_patterns.js(STOCK_CHECK_PATTERNS 注册 5 个定式 empty_location/mis_shipment/expiring/static/warning,collectEmptyLocation/collectMisShipment/collectExpiring/collectStatic/collectWarning 五个收集函数)+ app/service/systems/stock_check.js#patternList/#patternCreate(收集对象、创建主表 status=submitted、写明细、static 写 wms_stock_static_check_task)+ app/service/systemMethods/stock/check.js(ALL_METHOD_NAMES 扩为 18 个含 patternList/patternCreate;patternList 在免日志清单 _noNeedLog;warehouseId/创建人从登录上下文注入;统一 _call 捕获业务错误码)。", "5 个定式口径(与 stock_check_patterns.js 代码注释一致):空库位=启用且未删除、在 wms_storage 不存在 quantity>0 库存的账面空库位(type=location,其余为 goods);错发=登记过错发工单(wms_after_sale type=order+sub_type=mis_shipment,排除 closed/cancelled)关联订单商品按 stock_id 去重;临期=开启保质期管理且最早到期日 <= 当前时间+remaining_threshold_days 天(阈值 <=0 按已到期)的商品;静态=最后一次 INBOUND/OUTBOUND 流水距今超过 stock_static_hours 小时(默认 168,无流水按建档时间)且未进入 wms_stock_static_check_task 的商品;预警=quantity < stock_warning_quantity 的商品(需仓库配置 stock_warning_enabled=true,未开启报 400「未开启库存预警」)。", "状态口径:patternCreate 创建后主表 status 直接 submitted(进入待审核)、detail_status=none_checked、total_items 按明细重算,无需再调 stock.check.submit;无符合条件对象报 400(location 型报「当前仓库没有账面为空的库位」,goods 型报「没有符合条件的商品」)。", "静态记录表口径:收集阶段排除 wms_stock_static_check_task 已有记录(未删除)的 stock_id(已进入静态已盘点商品);任务创建成功后把命中 stock_id 批量写入该表(task_time=创建时间),写入失败仅告警不影响主流程。", "权限口径:两个新 method 均随 ALL_METHOD_NAMES(18 个)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权,必须登录(isNeedLogin=true);patternList 为查询类在免日志清单(_noNeedLog)不记操作日志,patternCreate 为写操作保留操作日志。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.patternList/patternCreate 两条(追加在 exportTaskProgress 之后,与代码 ALL_METHOD_NAMES 顺序一致);根版本 0.3.213 → 0.3.214、updatedAt 保持 2026-09-30;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 后,同步回填开发库与生产库(import 当前 system.json → export 回写往返校验),保持库与文件一致;stock.check 分组共 18 条 method 无损。" ] }, { "version": "2026.09.30-stock-check-operation-log", "date": "2026-09-30", "type": "updated", "summary": "库存盘点 10 个写操作补齐业务操作日志:成功路径写入 wms_operation_log(businessType=stock_check,operationCode STOCK_CHECK_*),失败不写、日志异常不影响主流程", "methods": [ "stock.check.create", "stock.check.addDetail", "stock.check.detailDelete", "stock.check.report", "stock.check.recordDelete", "stock.check.finish", "stock.check.submit", "stock.check.cancel", "stock.check.audit", "stock.check.batchDelete" ], "notes": [ "代码依据:app/service/systems/stock_check.js 的 10 个写操作(create/addDetail/detailDelete/report/recordDelete/finish/submit/cancel/audit/batchDelete)在主流程写入成功后调用 ctx.service.systems.operationLog.createOperationLog 写入 wms_operation_log(businessType=stock_check);operationCode 前缀 STOCK_CHECK_*,对应 CREATE/ADD_DETAIL/DELETE_DETAIL/REPORT/DELETE_RECORD/FINISH/SUBMIT/CANCEL/AUDIT/BATCH_DELETE;operationAction 对应 CREATE/UPDATE/UPDATE/UPDATE/UPDATE/UPDATE/UPDATE/UPDATE/UPDATE/DELETE。", "日志口径:businessId=盘点任务 id(create 取新建记录 plainRecord.id,其余取 checkId);operator 取登录上下文 ctx.user(id=employees_id 回退 user.id,name=employees_name);extras 统一携带 warehouseId、checkNo(create 用 plainRecord.check_no)与 message,report/finish/audit/batchDelete 等另带业务关键字段(明细/库位/实盘数量、差异/盘盈/盘亏、审核动作与原因、deletedIds/skippedIds 等);changeSummary 为中文变更描述。", "batchDelete 特殊口径:仅删除集非空(deletedIds.length>0)时写日志(全跳过不写);businessId 取首个删除 id(deletedIds[0]);extras 附 deletedIds/skippedIds/deletedCount/skippedCount;日志在事务提交后写入,不随事务回滚残留。", "失败不写与降级:10 个日志调用点全部位于主流程成功路径之后(各写操作失败时先抛业务错误码 400,不会执行到日志写入);createOperationLog 内部 try/catch,日志写入失败仅记录 error 日志并返回 null,不影响主流程(业务已提交的变更不受日志失败影响)。", "接口契约不变:本次仅服务层行为变更(补充业务操作日志),10 个 method 的入参/响应/错误码/鉴权均未变化,methods/system.json 接口条目与根版本号均不修改(不 bump);本条仅追加到 methods/changes/system.json 数组首位;changes 不入库表,无需回填 wms_api_method_doc。" ] }, { "version": "2026.09.30-stock-check-doc-polish", "date": "2026-09-30", "type": "updated", "summary": "盘点接口文档文案修正:detail 字段计数 14→15、result 权限注释方法数 15→16、recordList/detailDelete 免日志清单补 result、export errors 补「未找到可导出的盘点任务」400", "methods": [ "stock.check.detail", "stock.check.result", "stock.check.recordList", "stock.check.detailDelete", "stock.check.export" ], "notes": [ "修正点明细:① stock.check.detail 的 description/response/notes 中「纯范围行 14 字段」改为「15 字段」(_formatDetailScopeRow 实际枚举 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 共 15 个,枚举清单原本完整,仅计数文案错误);② stock.check.result notes 首条「随 ALL_METHOD_NAMES(15 个)免 API 权限」改为「16 个」;③ stock.check.recordList 与 stock.check.detailDelete 的免日志清单枚举补 result;④ stock.check.export errors 补 400「未找到可导出的盘点任务」。", "代码依据:app/service/systemMethods/stock/check.js(ALL_METHOD_NAMES 共 16 个:create/list/addDetail/detailDelete/detail/result/report/recordList/recordDelete/finish/submit/cancel/audit/batchDelete/export/exportTaskProgress;_noNeedLog='list,detail,result,recordList,export,exportTaskProgress';export 超 50 上限校验)+ app/service/systems/stock_check.js#_formatDetailScopeRow(15 字段返回对象)与 #exportStockChecks(checks.length===0 时抛「未找到可导出的盘点任务」400)。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.detail/result/recordList/detailDelete/export 五条;根版本 0.3.212 → 0.3.213、updatedAt 保持 2026-09-30;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 后,同步回填开发库与生产库(import 当前 system.json → export 回写往返校验),保持库与文件一致。" ] }, { "version": "2026.09.30-wavePickTaskDetail-pick-requirements", "date": "2026-09-30", "type": "updated", "summary": "pick.wavePickTaskDetail 的 picking_view.items 新增 pick_requirements(拣货要求),团购形态(pick_mode=1/5)不返回 picking_details,前端改由 items 展示拣货要求", "methods": [ "pick.wavePickTaskDetail" ], "notes": [ "代码依据:app/service/systems/pick.js#buildPickingView——items 聚合行新增 pick_requirements,取值自商品资料链路(getStockDetails)的 stock.pick_requirements(merge_requirements=Y 时已按打包要求回退),空值兜底为空字符串。", "背景:团购小波次/大波次(pick_mode=1/5)不返回 picking_details,此前 picking_view.items 缺拣货要求字段,前端无法展示拣货要求。", "picking_view.items 其余字段不变;picking_details 的 stock 对象本就含该字段,本次仅补齐 items 层。", "文档变更范围:methods/system.json 的 pick.wavePickTaskDetail 响应 picking_view.items 新增 pick_requirements 字段描述;根版本 0.3.211 → 0.3.212、updatedAt 保持 2026-09-30;methods/changes/system.json 新增本条(插入数组首位)。" ] }, { "version": "2026.09.30-stock-check-batch-delete", "date": "2026-09-30", "type": "added", "summary": "新增 stock.check.batchDelete:批量删除盘点任务(入参 ids,上限 200),仅作废(cancelled)任务删除,非作废任务跳过;级联删除作业记录与明细(事务)", "methods": [ "stock.check.batchDelete" ], "notes": [ "代码依据:app/service/systems/stock_check.js#batchDelete(入参归一化 _normalizeIdList:单值兼容、去重、正整数过滤、上限 200;仓库隔离查询主表 id in ids + warehouse_id;状态分流与级联删除事务)+ app/service/systemMethods/stock/check.js#batchDelete(ALL_METHOD_NAMES 扩为 16 个含 batchDelete;warehouseId 从登录上下文注入;走统一 _call 捕获业务错误码)。", "状态分流口径:仅 status=cancelled(作废)任务执行删除;其他状态及仓库内查不到的任务跳过(计入 skipped_ids,保持入参顺序),不报错。", "级联删除顺序(事务内):先删作业记录(wms_stock_check_record where check_id in 删除集),再删明细(wms_stock_check_detail where check_id in 删除集),最后删主表(wms_stock_check where id in 删除集)。", "权限口径:batchDelete 随 ALL_METHOD_NAMES(16 个)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(免鉴权清单)、必须登录(isNeedLogin=true);为写操作,不在免日志清单 _noNeedLog,保留操作日志。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.batchDelete(插入 audit 之后,与代码 ALL_METHOD_NAMES 顺序一致);根版本 0.3.210 → 0.3.211、updatedAt 保持 2026-09-30;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "库表维护源说明:维护源为库表(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.09.30-wavePickTaskDetail-pick-mode-enum", "date": "2026-09-30", "type": "updated", "summary": "pick.wavePickTaskDetail 响应 task.pick_mode 描述补全枚举:1-团购小波次 2-散单单品单件 3-散单先拣后分 4-边拣边分 5-团购大波次", "methods": [ "pick.wavePickTaskDetail" ], "notes": [ "原描述仅「拣货模式」,缺少 pick_mode=5 为大团购(团购大波次)的枚举说明;现与 pick.query、order.recheckOrder 等接口的 pick_mode 描述对齐。", "仅更新 methods/system.json 的 pick.wavePickTaskDetail 响应字段描述,不修改任何业务实现。" ] }, { "version": "2026.09.30-stock-check-export-records", "date": "2026-09-30", "type": "updated", "summary": "盘点导出口径调整:Sheet2 导出盘点明细(作业记录:一行一条实际盘点记录,含商品/库位/实盘数量/盘点人/时间),不再导出任务明细(未盘范围行)", "methods": [ "stock.check.export" ], "notes": [ "代码依据:app/service/systems/stock_check.js#exportStockChecks/_generateAndUploadStockCheckExcel——Sheet2 直接拉 wms_stock_check_record 作业记录(不按任务范围行展开,任务明细与未盘范围行不导出),商品快照(item_code/item_name)从 wms_stock_warehouse 补齐,totalCount=作业记录总数;app/service/systemMethods/stock/check.js#export 异步任务入口与 Redis 进度缓存机制不变。", "口径变化:Sheet2「盘点明细」由「按任务范围行展开(含未盘空行,账面按 wms_storage 现算)」改为「一行一条实际盘点记录(作业记录)」——列:盘点单号/商品编码/商品名称/库位编码(空库位输出为空)/实盘数量/盘点人/盘点时间;未盘的任务范围行不再导出;进度 totalCount=作业记录总数(导出前即确定),进度按已写明细行数/总数计算。", "Sheet1 不变说明:Sheet1「盘点单」保持一行一个盘点任务(盘点单号/盘点名称/盘点范围/盘点方式/盘点状态/盘点进度/盘点日期/货主ID/创建人/明细行数/已盘行数/差异行数/开始时间/结束时间/备注)。", "文档变更范围:methods/system.json 的 stock.check.export 更新 description/response(total_count/current_count 口径)/notes;根版本 0.3.208 → 0.3.209、updatedAt 保持 2026-09-30;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "库表维护源说明:维护源为库表(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.09.30-stock-check-detail-result-split", "date": "2026-09-30", "type": "updated", "summary": "任务明细与盘点结果接口拆分:detail 只返回任务范围行(商品/库位),新增 result 返回盘点结果聚合(商品行 checked/diff/records/locations,库位行 stocks 按商品聚合账面查 wms_storage)", "methods": [ "stock.check.detail", "stock.check.result" ], "notes": [ "代码依据:app/service/systemMethods/stock/check.js(ALL_METHOD_NAMES 扩为 15 个含 result;新增 result() 从登录上下文注入 warehouseId、入参 id、走统一 _call 捕获业务错误码;_noNeedLog 扩为 list/detail/result/recordList/export/exportTaskProgress)+ app/service/systems/stock_check.js(detail() 改为只返回纯范围行(_formatDetailScopeRow 14 字段,不再调 _buildDetailAggregations);新增 result() 查询全部明细与作业记录后调 _buildDetailAggregations/_formatDetailAggregationRow 聚合)。", "拆分口径:detail 只返回任务范围行(商品/库位原始字段 14 个,不含任何盘点作业聚合);新增 result 返回盘点结果聚合——商品行 checked_quantity/diff_quantity/is_diff/status/location_codes/checkers/last_checked_at + records + locations,库位行 checked_quantity(行级合计)/diff_quantity(差异代数和)+ records/locations + stocks(按商品聚合,账面查 wms_storage)。", "接口兼容性影响:旧 detail 的商品行聚合字段(checked_quantity/diff_quantity/is_diff/status/location_codes/checkers/last_checked_at)、records、locations 与库位行 stocks 全部迁移到新接口 result;detail 仅用于任务范围行展示,需要盘点结果的调用方改调 stock.check.result(入参同为 id,返回同为 { check, rows, total })。", "权限口径:result 随 ALL_METHOD_NAMES(15 个)免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(免鉴权清单)、必须登录(isNeedLogin=true);为查询类方法,加入免日志清单 _noNeedLog。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.result(放在 detail 之后,与代码 ALL_METHOD_NAMES 顺序一致)、更新 stock.check.detail 的 description/response/notes(纯范围行 14 字段,移除聚合字段描述);根版本 0.3.207 → 0.3.208、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 回写往返校验),保持库与文件一致。" ] }, { "version": "2026.09.30-stock-check-add-detail-compat", "date": "2026-09-30", "type": "updated", "summary": "addDetail 兼容历史任务:type=all 且已存在商品明细行(改造前创建)时继续按商品模式接受 stock_ids,避免旧调用 400;全新 type=all 任务维持按库位语义", "methods": [ "stock.check.addDetail" ], "notes": [ "代码依据:app/service/systems/stock_check.js#addDetail——type=all 且 wms_stock_check_detail 已存在 scope_type='goods' 明细行(count>0)时置 isGoodsScope=true/isLocationScope=false,继续按商品模式接受 stock_ids;全新 type=all 任务维持按库位语义;入参维度互斥校验的库位错误文案更新为『当前盘点类型按库位盘点,请传 locations(如需按商品盘点请创建 type=goods 任务)』。", "兼容判定口径:以 wms_stock_check_detail 中 check_id 对应 scope_type='goods' 行是否存在为准(改造前 type=all 任务按商品添加明细,明细行 scope_type='goods');仅 type=all 任务走兼容判定,store/goods/location 类型判定逻辑不变。", "新任务语义保持:全新 type=all 任务(无任何商品明细行)维持按库位盘点语义——传 stock_ids 报 400『当前盘点类型按库位盘点,请传 locations(如需按商品盘点请创建 type=goods 任务)』;历史任务(按商品模式)传 locations 报 400『当前盘点类型按商品盘点,请传 stock_ids』。", "文档变更范围:methods/system.json 的 stock.check.addDetail 更新 description/errors/notes(历史任务兼容口径 + 库位错误码文案);根版本 0.3.206 → 0.3.207、updatedAt 保持 2026-09-30;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "库表维护源说明:维护源为库表(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.09.30-stock-check-location-scope", "date": "2026-09-30", "type": "updated", "summary": "盘点明细支持商品/库位两种范围行:all/location 按库位盘点、store/goods 按商品盘点;添加商品限制非本货主商品;库位行作业上报指定商品,账面来源 wms_storage", "methods": [ "stock.check.create", "stock.check.addDetail", "stock.check.report", "stock.check.detail", "stock.check.finish", "stock.check.export" ], "notes": [ "代码依据:app/service/systems/stock_check.js(create/addDetail/_addGoodsDetailRows/_addLocationDetailRows/detail/_buildDetailAggregations/report/finish/exportStockChecks)+ app/service/systemMethods/stock/check.js(入参透传与 locations/location_codes、stock_id 兼容)+ app/model/stock_check_detail.js / app/model/stock_check_record.js(模型与索引定义)。", "迁移文件:database/migrations/20260930110000-support-location-scope-in-stock-check-detail.js(本地+生产已执行)——明细表新增 scope_type/location_id/location_code、stock_id/item_code 改可空、防御性合并重复明细并新增唯一索引 uk_check_stock(check_id, stock_id) 与 uk_check_location(check_id, location_code);记录表移除 uk_detail_location(detail_id, location_code)、防御性合并重复记录并新增 uk_detail_stock_location(detail_id, stock_id, location_code)(覆盖式语义升级为同明细+同商品+同库位)。", "语义变化明细:①create.type 语义明确——all=按库位盘点(未传库位自动全仓库启用库位生成范围)/ location=按库位盘点 / store=按货主按商品盘点 / goods=按商品盘点;②addDetail 新增 locations 入参(兼容 location_codes),按任务 type 与 stock_ids 二选一,响应新增 invalid_locations,商品货主必须与任务 store_id 一致否则计入 invalid_stock_ids;③report 新增可选 stock_id 入参(库位行必填且商品须本仓库),覆盖式查重升级为 detail_id+stock_id+location_code;④detail 库位行输出 scope_type='location' + stocks 数组(按商品聚合,账面查 wms_storage);⑤finish 库位行账面来源 wms_storage(space_id+stock_id SUM(quantity));⑥export Sheet2 按盘点项展开(goods 1 行、location 按商品 N 行)。", "接口兼容性影响:向后兼容——create.type 枚举不变(all/store/goods/location);addDetail 原 stock_ids 入参与响应字段保留(新增 invalid_locations,非法商品仍走 invalid_stock_ids);report 原入参不变(stock_id 为新增可选参数,商品行不传保持原行为);detail 商品行响应结构不变(库位行为新输出形态);finish/export 响应结构不变。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.create/addDetail/report/detail/finish/export 六条 description/params/response/errors;根版本 0.3.205 → 0.3.206、updatedAt 保持 2026-09-30;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "库表维护源说明:维护源为库表(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.09.30-manual-waybill-express-code", "date": "2026-09-30", "type": "updated", "summary": "order.pendingOrder.manualWaybill 新增可选参数 express_code:传入时同步修改订单的快递编码,行为参考 updateOrderExpress", "methods": [ "order.pendingOrder.manualWaybill" ], "notes": [ "代码依据:app/service/systemMethods/order/pendingOrder.js#manualWaybill 新增可选入参 express_code(string,选填,trim 后为空视为未传);传入时参考 updateOrderExpress 的解析口径——从当前仓库快递列表(带缓存 getExpressList)中查找对应项,不存在则抛『快递编码 不存在』;自定义映射(is_system_setting=true)时订单 sys_logistics_code/name 写系统快递编码和名称、logistics_code/name 写自定义编码和名称,系统快递(is_system_setting=false)时四个字段均写系统快递的 code/name;不传时保持原行为(运单记录沿用订单当前 sys_logistics_code/name)。", "写入范围:传入 express_code 时,订单表同步更新 sys_logistics_code/sys_logistics_name/logistics_code/logistics_name 四字段(与 print_status/post_status='fin' 同一次 update),运单记录(wms_order_express)的 logistics_code/logistics_name 写入解析后的新值;不传时运单记录沿用订单原系统快递字段。", "操作日志:extras 新增 expressCode/sysLogisticsCode/sysLogisticsName/logisticsCode/logisticsName 字段,message 在传入 express_code 时补充快递信息。", "响应:传入 express_code 时额外返回 express_code、sys_logistics_code、sys_logistics_name、logistics_code、logistics_name;不传时响应结构与原版本一致(向后兼容)。", "文档变更范围:methods/system.json 的 order.pendingOrder.manualWaybill 更新 description、params 新增 express_code、response 新增 5 个可选字段、errors 新增 404 快递编码不存在;根版本 0.3.204 → 0.3.205、updatedAt 更新为 2026-09-30;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" ] }, { "version": "2026.09.29-stock-check-no-global-sequence", "date": "2026-09-29", "type": "updated", "summary": "盘点单号改为全局递增:generateCheckNo 移除按仓库隔离(uk_check_no 全局唯一索引下按仓从 1 起会跨仓撞号),create 撞唯一键自动重取重试最多 5 次,口径与收货单 receiving_number 一致", "methods": [ "stock.check.create" ], "notes": [ "代码依据:app/service/systems/stock_check.js#generateCheckNo 移除 warehouse_id 隔离条件,改为查询全局最大 PD+YYYYMMDD 前缀单号取末尾 6 位序号 +1;新增 isCheckNoDuplicateError()(parent.code==='ER_DUP_ENTRY' 且 sqlMessage 命中 uk_check_no/check_no,参照收货单 isReceivingNumberDuplicateError 口径);create() 撞唯一键自动重取单号重试最多 5 次(与收货单 create 重试口径一致),超过重试次数或非单号冲突错误原样抛出。", "原因说明:uk_check_no 为全局唯一索引(不区分仓库),原按仓库隔离序号各自从 1 起会跨仓撞号;改为全局递增后并发创建仍有极小概率撞号,由唯一键重试兜底。", "收货单参照口径:与收货单 receiving_number 一致——按全局最大序号 +1 生成 + 撞唯一键自动重取重试。", "并发重试说明:每次重试都重新调用 generateCheckNo() 取最新全局最大序号;仅 ER_DUP_ENTRY 且命中 uk_check_no 才重试,其它错误直接抛出。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.create 的 description 与 notes;根版本 0.3.203 → 0.3.204、updatedAt 保持 2026-09-29;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 回写往返校验),保持库与文件一致。" ] }, { "version": "2026.09.29-stock-check-detail-delete", "date": "2026-09-29", "type": "added", "summary": "新增 stock.check.detailDelete:删除盘点明细(从任务移除商品),仅 created/rejected 状态允许,删除时防御性清理作业记录并重算 total_items", "methods": [ "stock.check.detailDelete" ], "notes": [ "代码依据:app/service/systemMethods/stock/check.js(ALL_METHOD_NAMES 扩为 14 个含 detailDelete;detailDelete 从登录上下文注入 warehouseId,入参 id + detail_id(兼容 detailId 驼峰,detail_id 优先),走统一 _call 捕获业务错误码;为写操作,不在免日志清单 list/detail/recordList/export/exportTaskProgress 中)、app/service/systems/stock_check.js(detailDelete:id/detail_id 非法抛 400『盘点任务ID不能为空/盘点明细ID不能为空』,任务不存在/明细不存在分别抛 400;仅 ADD_DETAIL_ALLOWED_STATUSES(created/rejected)允许删除,否则 400『当前状态(xxx)不允许删除明细』;删除明细后防御性清理 wms_stock_check_record 并重算主表 total_items;返回 { detail_id, deleted:true, total_items })。", "状态限制口径:仅主表 created/rejected 允许删除明细(与 addDetail 口径一致,共用 ADD_DETAIL_ALLOWED_STATUSES);其它状态返回 400。", "防御清理说明:正常流程 created/rejected 状态不应存在作业记录,但为兜底,删除明细时按 { detail_id, check_id, warehouse_id } 一并删除 wms_stock_check_record 中的关联记录,避免残留孤儿记录;删除后重算主表 total_items。", "权限口径:随 ALL_METHOD_NAMES 免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(免鉴权清单)、必须登录(isNeedLogin=true,免登录清单为空);detailDelete 为写操作,记录操作日志。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.detailDelete(放在 addDetail 之后,与代码 ALL_METHOD_NAMES 顺序一致);根版本 0.3.202 → 0.3.203、updatedAt 保持 2026-09-29;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 回写往返校验),保持库与文件一致。" ] }, { "version": "2026.09.29-stock-check-record-unique-index", "date": "2026-09-29", "type": "updated", "summary": "盘点作业记录表加固:location_code 空串归一 + 历史重复合并 + 唯一索引 uk_detail_location(detail_id, location_code),从数据库层保证 report 覆盖式上报并发安全;接口返回口径不变(空库位 location_code 仍为 null)", "methods": [ "stock.check.report", "stock.check.recordList" ], "notes": [ "代码依据:app/service/systems/stock_check.js(report 未传库位归一存空串 '';查重条件统一 { detail_id, location_code };依赖数据库层唯一索引 uk_detail_location 保证并发安全;recordList 返回 location_code 空串归一为 null;detail 的 locations/location_codes 输出口径不变,空库位组 location_code=null)、app/model/stock_check_record.js(location_code allowNull=false defaultValue='')。", "迁移:database/migrations/20260929130000-unique-stock-check-record-detail-location.js——location_code 归一 NULL→''、合并历史重复记录(同 detail_id+location_code 保留 id 最大一条)、列改 NOT NULL DEFAULT ''、新增唯一索引 uk_detail_location(detail_id, location_code);本地与生产均已执行。", "口径变化:report 未传库位不再存 NULL 而是存空串 ''(\"无库位\"分组),覆盖式查重条件不变({ detail_id, location_code },含空串分组),并发下由唯一索引兜底不产生重复记录。", "接口兼容性:对外返回口径不变——recordList 将空串归一为 null、detail 的 locations/location_codes 空库位组 location_code 仍为 null,客户端无需调整。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.report 的 description/notes 与 location 入参描述、stock.check.recordList 的 rows response 描述与 notes(空串归一 null 口径);根版本 0.3.201 → 0.3.202、updatedAt 保持 2026-09-29;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库,后续由维护者决定是否同步入库。" ] }, { "version": "2026.09.29-stock-check-work-adjust", "date": "2026-09-29", "type": "updated", "summary": "盘点作业接口 5 项调整:report 改为覆盖式(同明细+同库位重复上报更新已有记录)、新增 recordDelete(删作业记录重算汇总)与 recordList(分页查作业记录)、detail rows 增加按库位聚合 locations、finish 放宽未盘校验(未盘按实盘 0 计盘亏并返回 unchecked_items)", "methods": [ "stock.check.report", "stock.check.detail", "stock.check.finish", "stock.check.recordDelete", "stock.check.recordList" ], "notes": [ "代码依据:app/service/systemMethods/stock/check.js(ALL_METHOD_NAMES 扩为 13 个含 recordList/recordDelete;免权限/免鉴权清单共用全部方法,免日志清单为 list/detail/recordList/export/exportTaskProgress;recordDelete 入参兼容 record_id/recordId 写法)、app/service/systems/stock_check.js(report 覆盖式上报:同 detail_id + 同 location_code(含同为空库位 location_code 为 NULL)更新已有记录 quantity/checker_id/checker_name/checked_at 并保留/回填 location_id,否则新增,返回 mode=created|updated;recordList 按 id DESC 分页返回记录全字段 + item_code/item_name;recordDelete 仅 approved/checking 状态、删除后重算汇总且主表状态不回退;detail rows 增加 locations 按库位聚合;finish 未盘明细按实盘 0 计盘亏并返回 unchecked_items)。", "行为口径变化明细:①stock.check.report 从每次新增一条记录改为覆盖式——同 detail_id + 同 location_code(含同为空库位)重复上报更新已有记录(quantity/checker/checked_at),首次上报才新增,返回 mode=created|updated;②新增 stock.check.recordDelete:入参 id + record_id(兼容 recordId),仅 approved/checking 状态允许,删除后重算 total_items/checked_items/diff_items/detail_status(明细记录删光后回到未盘),主表状态不回退,返回 { record_id, deleted:true, ...summary };③新增 stock.check.recordList:入参 id(可选)+ detail_id(可选)+ pagination 至少传其一,返回 { rows, total, page, pageSize },rows=记录全字段 + item_code/item_name,按 id DESC;④stock.check.detail rows 每条新增 locations 数组(按库位聚合 [{ location_id, location_code, quantity }],空库位归 location_code=null 组),records 与既有聚合字段不变;⑤stock.check.finish 不再拦截未盘明细,未盘按实盘 0 处理(diff=-账面快照,计盘亏与 diff_items),返回新增 unchecked_items 字段。", "无 schema 变更:本次仅业务行为调整,wms_stock_check / wms_stock_check_detail / wms_stock_check_record 表结构未变,无需数据库迁移。", "权限口径:recordList/recordDelete 与同分组其它方法一致——免 API 权限(isNeedAuth=false)、免仓库有效期鉴权、必须登录(isNeedLogin=true);recordList 为查询类免操作日志,recordDelete 为写操作记录操作日志。", "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.recordList、stock.check.recordDelete 两条 method,更新 stock.check.report/detail/finish 三条 description 与 response(report 增加 mode 字段、detail rows 增加 locations 聚合、finish 增加 unchecked_items 并移除未盘拦截错误);根版本 0.3.200 → 0.3.201、updatedAt 保持 2026-09-29;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库,后续由维护者决定是否同步入库。" ] }, { "version": "2026.09.29-storage-entry-bindReceiving-soft-deleted-restore", "date": "2026-09-29", "type": "fixed", "summary": "storage.entry.bindReceiving 修复解绑后重新绑定失败:CREATED 分支改用三态幂等(已存在跳过/软删除恢复/新建),不再因软删除残留行撞唯一索引报 BINDING_WRITE_FAILED(Validation error)", "methods": [ "storage.entry.bindReceiving" ], "notes": [ "根因:findOrCreate 查询默认排除软删除行(paranoid),解绑(unbindReceiving 软删除主表绑定行)后再次绑定同一 (entry_order_id, receiving_id) 时,create 撞唯一索引 uk_entry_order_receiving 抛 SequelizeUniqueConstraintError(message 为 \"Validation error\"),被捕获计入 skipped 并返回 BINDING_WRITE_FAILED。生产现场:绑定行 id=793(入库单 1280 RK202609290005 ↔ 收货单 4686 R20725003)于 2026-09-28 19:02 解绑软删除,2026-09-29 重新绑定即失败。", "修复:app/service/systems/receiving_entry_match.js 的 bindEntryOrderReceiving CREATED 分支改为 paranoid:false 查询三态处理——未删除已存在跳过(created=false)、已软删除则 allocated_quantity 重置为 {} 并 restore(restored=true)、不存在新建(create 唯一索引冲突视为并发已建立,created=false);bound 项统一返回 created/restored 两字段。", "同类加固:_commitBinding(PDA 上架确保主表绑定)的 findOrCreate 同步改为三态;_bindEntryOrderReceiving(自动匹配)与 _bindOneReceivingAndSyncStorage(COMPLETED)恢复软删除行时显式 allocated_quantity={} 兜底、软删除判断兼容 deletedAt/deleted_at 两种属性名。", "文档变更范围:methods/system.json storage.entry.bindReceiving 的 bound.created/restored 描述更新、restored required 改为 true;根版本 0.3.199 → 0.3.200、updatedAt 保持 2026-09-29;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次直接写 JSON,未连接数据库、未写库,后续由维护者决定是否同步入库。" ] }, { "version": "2026.09.29-stock-check-detail-split", "date": "2026-09-29", "type": "updated", "summary": "盘点明细表拆分:wms_stock_check_detail 仅保留盘点商品(stock_id+快照),库位/数量信息下沉到新建 wms_stock_check_record(盘点作业记录表);report 改为写入记录(同明细可多库位多次上报),已盘口径=存在记录,差异=记录数量合计-账面快照;detail 返回 records 与聚合字段;导出明细行含库位合并/盘点人合并。", "methods": [ "stock.check.report", "stock.check.detail", "stock.check.finish", "stock.check.export", "stock.check.exportTaskProgress" ], "notes": [ "代码依据:app/model/stock_check_detail.js(明细表仅存盘点商品:stock_id+商品快照,移除 location_id/location_code/check_quantity/diff_quantity/is_diff/status/checker_id/checker_name/checked_at)、app/model/stock_check_record.js(新建盘点作业记录表:check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark,一个明细可在多库位多次上报)、app/service/systems/stock_check.js(report 写入记录不再更新明细;detail 返回 records 与聚合字段;finish 未盘=无记录明细、差异按记录聚合;export Sheet2 商品级聚合+库位/盘点人合并)、app/service/systemMethods/stock/check.js(report 从登录上下文注入 checkerId/checkerName)。", "迁移:database/migrations/20260929120000-split-stock-check-detail-create-record.js(明细表移除 9 个作业字段 + 新建 wms_stock_check_record 及 4 个索引 idx_check_id/idx_detail_id/idx_stock_id/idx_warehouse_location),本地与生产均已执行。", "口径变化明细:report 每次上报新增一条作业记录(同明细可在多库位多次上报),明细已盘数量=记录 quantity 合计;已盘口径=存在记录(DISTINCT detail_id);差异=记录数量合计-账面快照 system_quantity;detail.rows 返回 checked_quantity/diff_quantity/is_diff/status/location_codes[]/checkers[]/last_checked_at + records[];finish 未盘明细=无记录明细;export Sheet2 明细行(商品级聚合)列为 盘点单号/商品编码/商品名称/规格/账面数量/已盘数量/差异数量/是否有差异/库位编码(顿号合并)/盘点人(合并)/最近盘点时间。", "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.report/detail/finish/export 共 4 条 method 的 description 与 response;根版本 0.3.198 → 0.3.199、updatedAt 保持 2026-09-29;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库,后续由维护者决定是否同步入库。" ] }, { "version": "2026.09.29-stock-check-apis", "date": "2026-09-29", "type": "added", "summary": "新增库存盘点模块 11 个 method(创建空任务/列表/添加明细/拉取明细/盘点作业上报/完成盘点/提交审核/取消/审核/导出/导出进度),完整状态机 created→submitted→approved/rejected→checking→completed/cancelled", "methods": [ "stock.check.create", "stock.check.list", "stock.check.addDetail", "stock.check.detail", "stock.check.report", "stock.check.finish", "stock.check.submit", "stock.check.cancel", "stock.check.audit", "stock.check.export", "stock.check.exportTaskProgress" ], "notes": [ "代码依据:app/service/systemMethods/stock/check.js(11 个 method 包装层,统一 _call 包装 400/500)与 app/service/systems/stock_check.js(状态机、单号生成 PD+YYYYMMDD+6位序号、汇总重算、Excel 导出 + COS 上传)。", "表结构:wms_stock_check(盘点主表,仓库隔离 warehouse_id、盘点单号 check_no 唯一、状态 status、明细进度 detail_status、汇总 total_items/checked_items/diff_items)与 wms_stock_check_detail(盘点明细表,商品/库位快照、账面数量 system_quantity、实盘数量 check_quantity、差异数量 diff_quantity=实盘-账面)。", "迁移:database/migrations/20260929100000-create-wms-stock-check.js、20260929101000-create-wms-stock-check-detail.js、20260929110000-align-stock-check-status-machine.js(主表 status 默认值 pending → created、注释对齐新状态机),本地与生产均已执行。", "权限口径:11 个 method 全部免权限/免鉴权(仓库有效期检查)/需登录;list/detail/export/exportTaskProgress 免操作日志;不产生 wms_permission 权限记录,无需执行 permission:sync:system-api。", "导出任务口径:Redis 进度缓存 key stock_check_export_task_{taskId}、TTL 1800 秒;每任务一个 Sheet(Sheet 名=盘点单号 check_no);单次最多 50 个盘点任务。", "文档变更范围:methods/system.json 新增分组 module=stock.check(库存盘点模块)共 11 条 method;根版本 0.3.196 → 0.3.197、updatedAt 2026-09-28 → 2026-09-29;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库,后续由维护者决定是否同步入库。" ] }, { "version": "2026.09.28-weigh-pack-padding-message", "date": "2026-09-28", "type": "updated", "summary": "散单称重拦截提示区分打包中状态:pack_status=padding 返回「订单打包中」,其余未完成状态返回「订单未打包」", "methods": [ "order.updateExpressWeighingWeight", "workbench.sendWeight" ], "notes": [ "代码依据:app/service/systems/order_express.js 的 buildWeighPackBlockedMessage(packStatus) 恢复入参,padding 返回「订单打包中」、其余非 fin 状态返回「订单未打包」;assertSingleOrderPackedForWeigh 沿用该文案抛 400。", "代码依据:app/service/systems/workbench.js 的 _assertSingleWeighPackedForWeigh 复用同一文案,不再固定「订单未打包」。", "判定规则未变:开启仓库配置 single_weigh_require_pack 后,wave_scope 非 1 大团购/3 小团购的订单 pack_status 非 fin 时拒绝称重;团购波次批量称重不校验。", "测试:test/single_weigh_require_pack.test.cjs(27 用例,新增打包中文案断言,全部通过)。", "本次仅提示文案区分,无接口结构变化。" ] }, { "version": "2026.09.28-order-wave-fetchable-order-count", "date": "2026-09-28", "type": "added", "summary": "新增 order.wave.fetchableOrderCount:统计当前仓库团购可抓取订单数(与 order.wave.groupOrderFetchList 同口径:同一候选条件 + items_hash 粗分组 + 团购阈值过滤),但不分页、不查订单明细,仅返回命中分组数与组内订单数合计。", "methods": [ "order.wave.fetchableOrderCount" ], "notes": [ "代码依据:app/service/systemMethods/order/wave.js 新增 async fetchableOrderCount(data)。候选 where 与 groupOrderFetchList 完全一致(step in [1,2,3]、status != cancel、outbound_status != padding、intercept_status='none'、lock_status='none'、wave_id=0,叠加 store_id / shop_name / stock_query 过滤);分组键复用 buildCoarseGroupKey(items_hash 缺省回落 items,distinguish_express=true 时再叠加 sys_logistics_code);阈值同源 getMinGroupOrderFetchQuantity(仓库配置,默认 13);仅取 id/items_hash/items/sys_logistics_code 四列,纯内存计数,不查订单明细。", "口径差异(重要):groupOrderFetchList 的 pagination.total 是分组数(每组订单数在 item.group_count 内),本方法 order_count 是命中分组的订单数合计、group_count 是命中分组数;include_sku 为 groupOrderFetchList 的页内过滤参数,本方法不参与统计,因此带 include_sku 时两者不保证一致。", "权限与日志:方法已加入 wave.js systemInit 的 _noNeedRight / _noNeedLog / _noNeedAuth 名单(与 groupOrderFetchList 一致),仅需登录;isNeedAuth=false,不产生 wms_permission 权限记录,无需执行 permission:sync:system-api,也不需要新增迁移。", "返回结构:成功返回 flag=success/code=1,data 含 group_count / order_count / same_order_quantity / raw_order_count / warehouse_id / distinguish_express;仓库上下文缺失时返回 flag=failure/code=400「未识别到当前仓库上下文」。", "测试:test/app/service/systemMethods/order/wave.fetchableOrderCount.test.js(8 用例:阈值命中统计、阈值变化、区分快递粒度、store_id+shop_name 进入候选 where、stock_query 空命中短路、仓库上下文缺失 400、默认阈值回落、与 groupOrderFetchList 命中分组订单数合计一致性)。", "文档变更范围:methods/system.json 在 module=order.wave(订单波次模块)分组 list 末尾新增 1 条 method;根版本 0.3.194 → 0.3.195、updatedAt 2026-09-27 → 2026-09-28;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库,后续由维护者决定是否同步入库。" ] }, { "version": "2026.09.27-weigh-pack-message-simplify", "date": "2026-09-27", "type": "updated", "summary": "散单称重未打包拦截文案简化为固定「订单未打包」(移除打包状态明细与工作台条码后缀)", "methods": [ "order.updateExpressWeighingWeight", "workbench.sendWeight" ], "notes": [ "代码依据:app/service/systems/order_express.js 的 buildWeighPackBlockedMessage() 现返回固定文案「订单未打包」,assertSingleOrderPackedForWeigh 沿用该文案抛 400;原 formatPackStatusText 状态文案方法已移除。", "代码依据:app/service/systems/workbench.js 的 _assertSingleWeighPackedForWeigh(orderRow, warehouseId) 复用同一文案,不再追加 ` [条码]` 后缀。", "判定规则未变:开启仓库配置 single_weigh_require_pack 后,wave_scope 非 1 大团购/3 小团购的订单 pack_status 非 fin 时拒绝称重;团购波次批量称重不校验。", "测试:test/single_weigh_require_pack.test.cjs(26 用例,已按新文案断言)。", "本次仅文档文案对齐,无接口结构变化。" ] }, { "version": "2026.09.27-setting-save-big-group-coefficient-doc-fix", "date": "2026-09-27", "type": "updated", "summary": "补 setting.warehouse.saveSettings 入参遗漏的 subject_config.big_group_pack_coefficient(对齐 getSettings/getFieldMeta 与代码实现):大团购波次(wave_scope=1)打包中扫描其他波次订单至少需等待「当前波次打包数 × 系数」秒,默认 3,必须大于 0;非法值报 400。", "methods": [ "setting.warehouse.saveSettings" ], "notes": [ "代码依据:app/service/systems/setting/warehouse.js#WAREHOUSE_SETTING_FIELDS 已有 key=big_group_pack_coefficient(name=大团购打包系数,type=number,default=3,required=false,min=0.1,description=大团购波次(wave_scope=1)打包中,扫描其他波次订单至少需等待「当前波次打包数 × 系数」秒,单位:秒/单,默认 3,必须大于 0);app/model/store.js#DEFAULT_SUBJECT_CONFIG.big_group_pack_coefficient=3,normalizeSubjectConfig 对非空值 Number() 后校验有限且 >0,非法抛错 subject_config.big_group_pack_coefficient 必须是大于 0 的数字,空值/null/'' 回落默认 3。", "历史新增来源:该字段为上一期仓库配置新增(changes 已有记录「仓库设置新增大团购打包系数」,当时同步了 setting.warehouse.getSettings 响应与 getFieldMeta 字段元信息,但遗漏 saveSettings 入参文档);本次为文档补漏修正,仅补齐该遗漏,不涉及任何代码变更。", "文档变更范围:methods/system.json 仅 setting.warehouse.saveSettings 一条(params 在 subject_config.group_order_pack_max_minutes 之后、subject_config.single_weigh_require_pack 之前新增 subject_config.big_group_pack_coefficient;errors 新增对应 400;description 追加补漏说明);根版本 0.3.192 → 0.3.193、updatedAt 保持 2026-09-27;methods/changes/system.json 新增本条(插入数组首位);其余 method 逐字节未变。", "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库,后续由维护者决定是否同步入库。" ] }, { "version": "2026.09.27-single-weigh-require-pack", "date": "2026-09-27", "type": "updated", "summary": "新增仓库配置「散单称重是否需要打包」single_weigh_require_pack(默认关闭)+ 散单称重前置打包校验:开启后,订单波次范围 wave_scope 非 1(大团购)/3(小团购)且 pack_status 非 fin 的散单称重被拒绝(业务错误 code=400)。", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.getFieldMeta", "setting.warehouse.saveSettings", "order.updateExpressWeighingWeight", "workbench.sendWeight" ], "notes": [ "代码依据:app/service/systems/setting/warehouse.js#WAREHOUSE_SETTING_FIELDS 新增 key=single_weigh_require_pack(name=散单称重是否需要打包,type=flag,default=false,required=false,位于 big_group_pack_coefficient 与 return_unpack_max_record_minutes 之间);app/model/store.js#DEFAULT_SUBJECT_CONFIG 新增默认 false,normalizeSubjectConfig 仅布尔/like-flag(true/1/'1'/'true' → true;false/0/'0'/'false → false),非法值抛错 subject_config.single_weigh_require_pack 必须是布尔值,未配置时不写该键。", "校验逻辑(app/service/systems/order_express.js):新增 findOrderWaveAndPackStatus(current→history→dispatch 分表 + 序列表定位优先)/formatPackStatusText(none=未打包、padding=打包中、fin=已打包、error=打包异常,未知值按未打包)/isSingleWeighRequirePack(走 deliveryOrder.getStoreSubjectConfig 带缓存,缺失/读取异常按关闭)/assertSingleOrderPackedForWeigh/buildWeighPackBlockedMessage;_updateSingleOrderWeight 开头调用 assertSingleOrderPackedForWeigh,因此订单模式(order_id>0)与运单号模式(order_id=0)的散单/非团购波次路径均生效;规则:配置开启且 wave_scope ∉ {1,3} 且 pack_status != fin → 业务错误 code=400「散单称重需先完成打包:订单尚未打包(当前打包状态:未打包)」;warehouseId 缺失跳过校验;团购波次 _updateWaveOrderWeight/_updateWaveAllOrdersWeight 不校验。", "工作台路径(app/service/systems/workbench.js):_sendWeight 订单行查询补充 wave_scope/pack_status,拦截校验后调用 _assertSingleWeighPackedForWeigh,复用 order_express.buildWeighPackBlockedMessage 文案并在末尾追加「 [条码]」,经 workbench.sendWeight 出口以业务失败(code=400)返回。", "测试证据:test/single_weigh_require_pack.test.cjs(26 用例全部通过,覆盖配置规范化、wave_scope 1/3 跳过、未打包拦截且不落库、已打包放行、配置读取异常降级)。", "文档变更范围:methods/system.json 更新 5 条 method(setting.warehouse.getSettings 响应新增 subject_config.single_weigh_require_pack;getFieldMeta 描述补新字段元信息;saveSettings 入参补该字段与非法值 400;order.updateExpressWeighingWeight 与 workbench.sendWeight 的 errors 补未打包拦截 400 场景);根版本 0.3.191 → 0.3.192、updatedAt 2026-09-26 → 2026-09-27;methods/changes/system.json 新增本条(插入数组首位)。分组结构、其它 method、响应结构(除 getSettings 新增 1 字段)不变。", "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库,后续由维护者决定是否同步入库(method-doc-update 或全量 method-doc-import 后重新导出)。" ] }, { "version": "2026.09.26-order-packing-returnUnpack-where-person-filter", "date": "2026-09-26", "type": "updated", "summary": "接口入参新增:order.packing.list 新增 where.operator_text(打包员/作业人员筛选,wms_pack_task.operator_text 多人姓名逗号拼接快照,支持 {operator,value,type} 标准结构,value 支持字符串或数组多值取并集;contains/like 与缺省为 LIKE 模糊(通配符已转义)、eq/in 精确、ne 不等于、notlike 逐值排除、空值忽略);returnUnpack.list 新增 where.unpacker_name(拆包人筛选,wms_return_unpack.unpacker_name 工号名称快照,like 支持数组多值并集,兼支持 eq/ne/in/notin/between)。同一 _buildListWhere 被复用,order.packing.export 与 returnUnpack.export 的 where 同步获得同一筛选语义(其 where 字段清单已补 operator_text / unpacker_name)。", "methods": [ "order.packing.list", "order.packing.export", "returnUnpack.list", "returnUnpack.export" ], "notes": [ "变更类型:updated(接口入参新增 where 字段,不新增/删除 method、不改变响应结构与错误码)。", "代码依据:app/service/systems/order_packing.js#_buildListWhere(operator_text 分支,同时被 list 与 exportPackTask 复用,L525/L653);app/service/systems/return_unpack.js#_buildListWhere(textFields 新增 unpacker_name,同时被 list 与 exportUnpack 复用,L937/L1149)与 #_resolveConditionValue(like 支持数组多值并集)。目标列:wms_pack_task.operator_text(TEXT,多人姓名逗号拼接快照,如 小吴哥,阿猫;写入见 app/service/systems/workbench.js);wms_return_unpack.unpacker_name(STRING(50) NOT NULL,拆包人员工号名称快照 employees_name/real_name,app/model/return_unpack.js)。", "operator_text 取值口径(以代码为准):支持 {operator,value,type} 标准结构,value 支持字符串或字符串数组(多值取并集);operator=contains/like 与缺省(不传 operator)→ LIKE %值%(%/_ 通配符已转义);operator=eq/in → 精确匹配(单值等值、多值 IN);operator=ne → 不等于(多值取首值);operator=notlike → NOT LIKE %值%(多值逐个 AND 排除);值为 空串/null/空数组(trim/去空归一后为空)时忽略该条件(不过滤)。", "unpacker_name 取值口径(以代码为准):{operator:\"like\",value} 或直接值 → LIKE %值%;value 为数组时多值 LIKE 取并集(trim/去空归一后为空退化为 %% 全匹配、不过滤);同时兼容 _resolveConditionValue 既有操作符 eq/ne/in/notin/between/gt/gte/lt/lte。", "文档变更范围:methods/system.json 更新 order.packing.list(where.children 新增 operator_text)、order.packing.export(where description 字段清单补 operator_text)、returnUnpack.list(params 新增 where.unpacker_name)、returnUnpack.export(where description 字段清单补 unpacker_name)共 4 条;分组条数与响应结构不变;根版本 0.3.190 → 0.3.191、updatedAt 2026-09-25 → 2026-09-26;methods/changes/system.json 新增本条(插入数组首位)。", "前端传参示例:order.packing.list / export 传 {\"where\":{\"operator_text\":{\"value\":\"小吴哥\",\"operator\":\"like\",\"type\":\"text\"}}};returnUnpack.list / export 传 {\"where\":{\"unpacker_name\":{\"operator\":\"like\",\"value\":\"阿猫\"}}}。", "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta,导出脚本 script/method-doc-export.cjs)。本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(遵循「只修改文档」红线)。后续需由维护者决定是否同步入库(method-doc-update 或全量 method-doc-import 后重新导出),否则下次执行 method-doc-export.cjs 会用库表重建 system.json 而丢失本次文件改动。", "发布顺序:纯文档变更,无迁移、无代码改动(代码已实现并通过 ESLint),前端无需适配。" ] }, { "version": "2026.09.25-index-upload-client-error-log", "date": "2026-09-25", "type": "added", "summary": "新增客户端错误日志上报接口 index.uploadClientErrorLog(免登录、免权限、免鉴权,保留系统日志):设备端运行时错误批量上报暂存到新表 wms_client_error_log。入参支持单条对象/数组/{ logs: [...] } 三种形态、单次最多 50 条;snake_case 为主并兼容 camelCase 别名;error_message/error_stack 至少一项有值(超长截断 5000/65535),extra 截断 65535;report_uuid 唯一索引幂等去重(重复静默成功,duplicated +1),缺失时服务端生成 srv-{uuid};client_time 仅参考(非法存 null)。成功返回 code=200 + total/accepted/duplicated/rejected/rejected_reasons(≤10) 统计;方法级错误 HTTP 200 + flag=failure(code=400/500)。配套迁移 database/migrations/20260925100000-create-wms-client-error-log.js、模型 app/model/client_error_log.js、服务 app/service/systems/client_error_log.js。", "methods": [ "index.uploadClientErrorLog" ], "notes": [ "变更类型:added(新增 method + 新增表);影响范围:methods/system.json 的 index(基础模块)分组 28 → 29 条,根版本 0.3.189 → 0.3.190、updatedAt 2026-09-24 → 2026-09-25;methods/changes/system.json 新增本条(插入数组首位)。", "入口与鉴权:POST /system?method=index.uploadClientErrorLog&v=1×tamp=<数字时间戳>(controller.home.system 统一入口);请求头需 platform、project(根 headers 已声明枚举),无 Authorization/token;方法已登记 _noNeedLogin/_noNeedRight/_noNeedAuth,且不在 INDEX_NO_NEED_LOG_METHODS 清单 → 保留系统日志(index 模块日志口径已由通配改为显式清单)。", "入参归一化口径(代码为准):三种形态三选一(单条对象 / 数组 / { logs: [...] },单次最多 50 条,超限 code=400);字段按 snake_case 读取并兼容 camelCase 别名(clientType/appVersion/deviceId/osVersion/deviceModel/errorType/errorMessage/errorStack/reportUuid/clientTime);字符串字段超宽截断:client_type 32、app_version 64、device_id 128、os_version 64、device_model 128、error_type 64、report_uuid 64;error_message 截断 5000、error_stack 截断 65535(两者至少一项有值,否则该条 rejected);extra 支持对象(JSON.stringify 后截断 65535);client_time 支持毫秒/秒时间戳(≥1e12 视为毫秒)与日期字符串,非法解析存 null。", "幂等语义:report_uuid 唯一索引 uk_report_uuid —— 写入前先查已有 uuid,重复项 duplicated +1 且不再写入(静默成功);客户端未传 report_uuid 时服务端生成 srv-{uuid},此时不做幂等去重、不保证幂等;created_at/updated_at 由 Sequelize 统一取服务器时间,不采信 client_time。", "表结构:wms_client_error_log —— id BIGINT(20) UNSIGNED 自增主键;client_type/app_version/device_id/os_version/device_model/error_type/report_uuid 为 STRING(32/64/128/64/128/64/64,NOT NULL DEFAULT '');error_message TEXT、error_stack MEDIUMTEXT、extra TEXT 可空;client_time/created_at/updated_at DATE(created_at/updated_at NOT NULL);索引 uk_report_uuid(唯一)、idx_created_at、idx_client_type_app_version、idx_device_id。", "出参(成功):{ flag:'success', code:200, message:'上报成功', success:true, total, accepted, duplicated, rejected, rejected_reasons(≤10 条,每条 { index, reason }), timestamp };失败(400/500):HTTP 200 + { flag:'failure', code, message, timestamp }。", "客户端接入示例(无需 token,仅需公共头 platform/project 与 query method/v/timestamp):curl -X POST 'https:///system?method=index.uploadClientErrorLog&v=1×tamp=1764000000' -H 'platform: app' -H 'project: wms' -H 'Content-Type: application/json' -d '{\"client_type\":\"android\",\"app_version\":\"1.2.3\",\"device_id\":\"dev-001\",\"os_version\":\"Android 14\",\"device_model\":\"Pixel 8\",\"error_type\":\"crash\",\"error_message\":\"NullPointerException\",\"error_stack\":\"...\",\"report_uuid\":\"uuid-2026-001\",\"client_time\":1763999999000}';Kotlin(OkHttp) 伪代码:RequestBody.create(MediaType.parse(\"application/json\"), JSONObject().apply{put(\"client_type\",\"android\");put(\"error_message\",\"...\");put(\"report_uuid\", UUID.randomUUID().toString())}.toString()),Request.Builder().url(\"$base/system?method=index.uploadClientErrorLog&v=1×tamp=${System.currentTimeMillis()/1000}\").header(\"platform\",\"app\").header(\"project\",\"wms\").post(body).build() —— 客户端应在本地生成 report_uuid 以保证重试幂等。", "前端/客户端是否需适配:是(仅客户端接入层)。既有 /system 前端无改动;android/ios/web 端需按上述示例补齐 platform/project 头与 method/v/timestamp query,并自行生成并持久化 report_uuid 以利用幂等;无 token 校验,无需改造登录态链路。", "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta,导出脚本 script/method-doc-export.cjs)。本次仅按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(遵循「只修改文档」红线,与 2026-09-24 变更记录口径一致)。后续需由维护者决定是否以 method-doc-create 将该方法入库并重新导出,否则下次执行 method-doc-export.cjs 会用库表重建 system.json 而丢失本条。", "发布顺序:迁移(20260925100000-create-wms-client-error-log)先于代码发布;迁移为纯建表、无回填,先迁移无风险。" ] }, { "version": "2026.09.24-front-config-domain-two-phase-switch", "date": "2026-09-24", "type": "updated", "summary": "域名切换改为两阶段(待验证域名与生效域名分离)—— frontConfig.setDomain 只登记待验证域名 pending_domain 并下发 TXT 校验码,TXT 校验通过后才由提升逻辑切换为生效域名并清空证书;新增旧域名下线记录 retired_domain;解决「改域名瞬间旧域名公共接口 404」的中间态问题。", "methods": [ "frontConfig.setDomain", "frontConfig.getDomain", "frontConfig.checkDomain", "frontConfig.getByDomain", "frontConfig.saveCert", "frontConfig.getCert" ], "notes": [ "变更原因(旧口径问题,P0 中间态):旧 setDomain 是「设置即生效」—— 一次调用即改写生效域名 domain、domain_status 归零并清空证书,frontConfig.getByDomain 的放行闸门(domain + domain_status=1)对旧域名立即失效 → 旧域名公共接口立刻 404,而 nginx 侧旧域名 server 块仍在,出现「页面能打开但拉不到配置」的中间态;且用户改错域名无法回滚(只能再改一次并重新举证)。本轮以「待验证域名与生效域名分离」彻底消除该中间态。", "数据层:wms_warehouse_front_config 新增 8 列 —— pending_domain(STRING(100))、pending_verify_host(STRING(255))、pending_verify_token(STRING(64))、pending_verify_attempts(INTEGER NOT NULL 默认 0)、pending_last_error(STRING(500))、pending_created_at(DATE)、retired_domain(STRING(100),待下线旧域名)、retired_at(DATE);新增普通索引 idx_pending_domain(域名验证定时任务扫描待验证行)与 idx_retired_domain(外部脚本扫描待下线旧域名)。迁移文件 database/migrations/20260924180000-add-pending-domain-to-wms-warehouse-front-config.js(up/down 幂等)。纯追加且可空/带默认值,「无需任何数据回填」:存量行的 pending_* 为 NULL/0,语义即「没有待验证域名」,升级瞬间行为与升级前一致。", "四分支决策表(frontConfig.setDomain,域名比较忽略大小写):A 入参 == 生效域名且无 pending → 幂等短路(不写库;仅大小写不一致时改写 domain 字面值并清新旧两个字面值缓存);B 入参 == 生效域名且有 pending → 取消待切换(只清空 pending 6 列,生效域名/证书/同步状态一律不动);C 入参 == 现有 pending_domain → 校验码齐全则幂等短路,缺码(脏数据)则只补发 pending 校验码并清 pending_verify_attempts / pending_last_error;D 其它(含首次设置)→ 查重通过后只写 pending_domain + 新校验码,domain / domain_status / domain_verified_at / domain_verify_* / 证书 5 列 / 同步 4 列一律不动,也不清任何公共缓存。查重由「其他仓库 domain 命中」扩展为「其他仓库 domain 或 pending_domain 命中」→ 409「域名 X 已被其他仓库使用」。", "提升逻辑(frontConfig.promotePendingDomain,checkDomain 路径一与定时扫描共用):TXT 校验通过后一次 update 提交 —— domain = pending_domain、domain_status=1、domain_verified_at=now、domain_verify_host/token/attempts 由 pending_* 平移、domain_last_error=NULL;旧域名(生效域名非空且与待验证域名不同)写入 retired_domain + retired_at;清空 pending 6 列(pending_verify_attempts 归 0);清空证书 5 列(cert_pem / cert_key / cert_path / key_path / cert_expire_at);重置同步 4 列(sync_status=0、sync_attempts=0、last_sync_error=NULL、last_synced_at=NULL);由调用方清理旧域名与新域名两个公共拉取缓存(clearDomainCaches,先写库后清缓存,清失败仅记 WARN)。update 的 where 带 id + pending_domain 防并发重复提升。", "响应契约变化(纯追加、旧字段名与语义不变,前端可先发版兼容):frontConfig.getDomain 由 9 字段扩为 16 字段(追加 pending_domain / pending_verify_host / pending_verify_value / pending_attempts / pending_last_error / pending_created_at / pending_active);frontConfig.setDomain 响应同步由 9 字段扩为 16 字段;frontConfig.checkDomain 响应由 11 字段扩为 18 字段(getDomain 的 16 字段 + verified + resolved_values),并新增 409 错误码(提升时 domain 唯一索引冲突)。生效域名组字段名与语义一字未改:domain_status=1 时 verify_host/verify_value 仍返回空字符串;待验证域名在 pending_domain 非空时始终回显校验码(pending_verify_host / pending_verify_value)。", "旧域名下线由外部脚本执行(retired_domain 契约):script/warehouse-cert-sync.cjs 消费 retired_domain —— 删除该域名的 nginx server 块与证书文件后把 retired_domain 置 NULL,并有目录孤儿兜底清理;应用侧(service / schedule)不碰任何 nginx 文件。实测核对:当前工作区的 script/warehouse-cert-sync.cjs 尚未引用 retired_domain(全文检索 0 命中),该下线动作需脚本侧补齐后本闭环才完整;retired_domain 只保留最近一个旧域名,多次连续切换会丢中间域名(依赖脚本孤儿兜底清理)。", "发布顺序强约束(必须先迁移、再发代码):新代码的 SELECT 走 Sequelize 全字段,若生产库尚未执行迁移(pending_* / retired_* 共 8 列不存在),frontConfig.setDomain / getDomain / checkDomain 乃至 frontConfig.getByDomain 都会报 ER_BAD_FIELD_ERROR;定时扫描 verifyPendingDomains 会 fail-soft 返回零统计并记 WARN(含「迁移尚未执行」提示)。迁移为纯追加可空,先在生产执行迁移无风险。升级顺序:迁移 → 发布代码 → 前端发版。", "前端必须改造要点:①setDomain 提交成功后的 TXT 指引改读 pending_verify_host / pending_verify_value(不能再用 verify_host / verify_value);②首次设置时 domain 为空字符串是正常态(待验证域名在 pending_domain);③新增「取消待切换」交互 = 用当前生效域名再调一次 setDomain(走分支 B);④「切换中」状态用 pending_active / pending_attempts / pending_last_error / pending_created_at 展示;⑤提升完成后提示「切换完成,请重新上传证书」(提升会清空证书并重置同步状态);⑥明确「切换期间上传的证书属于旧域名」,提升后失效。", "文档变更范围与版本号:methods/system.json 更新 frontConfig.setDomain / frontConfig.getDomain / frontConfig.checkDomain / frontConfig.getByDomain / frontConfig.saveCert / frontConfig.getCert 共 6 条(description + notes;其中 setDomain / getDomain / checkDomain 的 response 同步追加待验证域名组 7 字段,checkDomain 另补 409);frontConfig 分组仍 8 条、其余方法未动;methods/changes/system.json 新增本条记录(插入数组首位);根版本 0.3.188 → 0.3.189(updatedAt 保持 2026-09-24)。", "历史记录说明(不回改):既有变更记录中关于「setDomain 未变化即幂等短路、缺码补发校验码」「domain_status=1 一律短路不降级」等描述属当时真实口径,作为历史事实不回改,由本条新记录承接并覆盖(现口径为四分支 A/B/C/D,原「缺码补发·已验证」分支已不存在)。", "维护源口径冲突(仅记录,未处理):methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(红线要求)。", "未处理遗留(建议单独修正):app/schedule/domain_verify_scan.js 头注释仍描述升级前口径(扫描 domain_verify_* 行并回写 domain_status / domain_verified_at / domain_verify_attempts / domain_last_error),与两阶段实现(只扫 pending 组、回写 pending_* 并在通过时提升)不符;app/service/systemMethods/frontConfig.js 的部分 JSDoc 仍写「生效域名组 9 字段」。两者均位于 app/**,本次为文档任务、不改代码,仅报告。" ], "module": "frontConfig" }, { "version": "2026.09.24-front-config-doh-multi-endpoint", "date": "2026-09-24", "type": "updated", "summary": "修复 DNS 解析误判 —— DoH 改为多端点顺序尝试(dohUrls),单端点「无记录」不再直接定论;仅在所有解析路径都失败时才判解析错误。", "methods": [ "frontConfig.checkDomain" ], "notes": [ "问题与实测案例:仓库 wmsv-aa4adaab13.wms.wms.gztbyc.com 的 TXT 记录真实存在(值 ddd9ae51cf95b488db544f23ccd01e7b,8.8.8.8 / 223.5.5.5 / AliDNS DoH / nslookup 四方一致),但默认 DoH 端点 doh.pub 返回 Status=0 且无 Answer(陈旧负缓存,其返回的 SOA 序列号偏旧);旧实现把单端点的 NODATA 直接定论为「未解析到 TXT 记录」→ domain_status=2 → 被 frontConfig.getByDomain 与 nginx 放行闸门断流(真实记录存在却被判为未解析到)。", "新口径:DoH 改为多端点顺序尝试(dohUrls,默认 alidns → 223.5.5.5 → doh.pub)+ 单端点结果三分类(values 立即返回 / empty 继续下一个端点 / error 继续下一个端点);empty(NODATA 或 NXDOMAIN)与 error 都不再直接定论,全部端点未取到值后降级系统 DNS;只要有一个端点或系统 DNS 明确答复「无该记录」就返回 [] (未解析到记录,不抛错),仅「所有 DoH 端点都是 error 且系统 DNS 也失败」才抛 500「DNS 解析失败:…」。", "配置兼容规则(dohUrl → dohUrls):config.frontConfig.domainVerify.dohUrls 为有效非空字符串数组时优先使用(顺序不变);否则回退历史单端点键 dohUrl(等价 [dohUrl]);两者均无效时回退内置默认数组 DEFAULT_DOH_URLS。旧键 dohUrl 保留读兼容,不作废。", "配置默认值变更:timeoutMs 5000 → 3000(单端点超时,系统 DNS 兜底同样显式限时 3s)、batchSize 50 → 20;配套核算 batchSize ≤ lockTtlSeconds×0.5 ÷ ((N+1)×timeoutMs/1000)(N 为端点数),3 端点场景单行最坏 12s、20 行 240s < lockTtlSeconds 600s。", "返回值契约:内部 resolveTxtValues 新增 endpoint 字段(追加不破坏,仍返回 { values, source, endpoint });verifyDomainRecord 契约不变({ verified, values, source, error },永不抛异常);新增内部 helper resolveDohUrls、queryDohEndpoint。", "可观测性:每个端点的 empty / error 均打日志(含 host + endpoint + 脱敏原因),可区分「记录不存在」与「链路不可用」。", "前端无感:不影响任何 method 的入参 / 响应结构,仅影响 frontConfig.checkDomain 与定时任务 domain_verify_scan 的判定正确性。", "文档变更范围:仅更新 frontConfig.checkDomain(description + notes),frontConfig 分组仍 8 条、各 response 计数不变;新增 1 条变更记录;根版本 0.3.187 → 0.3.188(updatedAt 保持 2026-09-24)。", "历史记录说明:既有变更记录中关于「Status=3 或无 Answer 视为未解析到记录、不重复走系统 DNS」的描述属于当时的真实口径,作为历史事实不回改,由本条新记录承接并覆盖。" ], "module": "frontConfig" }, { "version": "2026.09.24-front-config-domain-verified-shortcircuit", "date": "2026-09-24", "type": "updated", "summary": "修复「domain_status=1 的已验证域名可能被误降级」问题:frontConfig.setDomain 删除「已验证缺码补发」分支(已验证域名一律幂等短路、不补码、不写库);frontConfig.checkDomain 对 domain_status=1 一律短路返回 verified=true 且不写库、不改状态、不增加验证次数。", "methods": [ "frontConfig.setDomain", "frontConfig.checkDomain" ], "notes": [ "变更原因(P0 回归修复):上一轮把「domain_status=1 且缺校验码」的已验证域名也做成缺码补发,使 frontConfig.checkDomain 的「历史回填行短路」条件不再成立——用户手动点一次「校验」即走真实 DNS 解析,失败便把 domain_status 由 1 写成 2(domain_verify_attempts+1、domain_last_error 有值),随后被 frontConfig.getByDomain 与 nginx 放行闸门断流;且 status=1 时 getDomain 不回显校验码,用户无从发现补发的码。本轮改为「已验证域名一律不补码、一律短路」。", "问题现象与复现路径:库内 domain_status=1 且 domain_verify_host/domain_verify_token 为空(迁移回填常态)→ 前端再次提交同一域名触发 frontConfig.setDomain(旧口径走 C 分支补码入库)→ frontConfig.getDomain 因 domain_status=1 仍返回空 verify_host/verify_value(补发的码任何接口都读不到)→ 用户点「校验」触发 frontConfig.checkDomain,此时短路条件「无校验码」已不成立 → 走真实 DNS 解析 → 未配置对应 TXT 记录解析失败 → domain_status 由 1 写成 2、attempts+1、last_error 有值 → frontConfig.getByDomain 与 nginx 闸门断流(线上已生效域名被降级)。", "修复后口径(实现 app/service/systems/frontConfig.js):frontConfig.setDomain 删除原 C「缺码补发·已验证」分支,五分支收敛为 A/B/D/E/F(C 并入 A)——A 的判定为「域名忽略大小写相同 且(校验码齐全且字面值一致 或 domain_status=1)」,命中即幂等短路:不写库、不补码、不刷新校验码、不改验证状态与尝试次数、不清证书、不重置同步状态、不清缓存;B 大小写规范化仅改 domain 字面值(status=1 且缺码同样不补码);D 缺码补发仅限 domain_status∈{0,2};E 域名变更与 F 首次设置行为不变。三条「未变化」分支(A/B/D)均不写入 domain_verified_at。", "frontConfig.checkDomain 短路口径放宽:由「domain_status=1 且缺校验码」改为「domain_status=1」(不论库内有无校验码)一律短路,返回 verified=true、resolved_values=[],不写库、不改状态、不增加 attempts;已验证域名不再重复校验,误点「校验」不会把生效中的域名降级。", "行为影响(已知取舍):已验证(domain_status=1)域名自此无法通过 frontConfig.checkDomain 重新验证;如需该能力需另开接口(本次未做)。如需重新验证,应先通过 frontConfig.setDomain 变更域名(生成新校验码并回到「未验证」)后再校验。", "前端约束:不得依赖「重复调用 frontConfig.setDomain 换新校验码」——域名未变化时一律幂等短路,不会下发新码;当前也没有「更换校验码」的独立接口。", "文档变更范围:methods/system.json 更新 frontConfig.setDomain、frontConfig.checkDomain 的 description 与 notes,并顺带修正 frontConfig.getInfo(response.domain 描述)与 frontConfig.saveInfo(description)中「domain 只能通过 frontConfig.saveCert 变更」的陈旧表述(实际已收敛到 frontConfig.setDomain);4 条 method 的 params/response/errors/headers 均未变动,frontConfig 分组仍为 8 条;methods/changes/system.json 新增本条记录(插入数组首位);根版本 0.3.186 → 0.3.187,updatedAt 保持 2026-09-24。", "验证与实测:测试链路已确认「status=1 缺码 → setDomain 不再补码、不写库」「status=1 调 checkDomain 一律短路、不写库、不降状态、attempts 不变」「A/B/D/E/F 五分支行为与文档一致」;文档侧经 npm run doc:api:update --dry-run 预检,并以写入前备份做最小 diff 审计(除版本行、4 条 method、1 条 change 外无其它条目被动)。", "维护源口径冲突(仅记录,未处理):与前两轮一致,methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库。" ], "module": "frontConfig" }, { "version": "2026.09.24-front-config-setDomain-idempotent", "date": "2026-09-24", "type": "updated", "summary": "frontConfig.setDomain 语义收敛 —— 域名未变化时幂等短路,不再重新生成 DNS TXT 校验码、不再重置验证进度;仅「库内缺少校验码」时补发(已验证域名不降级),仅「库内域名大小写不同」时做小写规范化;域名变更与首次设置行为不变。", "methods": [ "frontConfig.setDomain" ], "notes": [ "变更原因:旧口径下「同一域名未验证/验证失败则重发新校验码并清零 attempts/last_error」,导致用户每次重复提交同一域名都会作废已配置好的 TXT 记录、并清空验证进度(attempts 归零、失败原因丢失),属无谓的进度回退;本轮以「域名是否变化」为第一决策点做幂等收敛", "五分支口径(实现 app/service/systems/frontConfig.js setDomain):A 完全未变化(忽略大小写相同 + 库内已有校验码 + 字面值一致)→ 幂等短路,不写库、不刷新校验码、不改验证状态与尝试次数、不清证书、不重置同步状态、不清缓存;B 大小写规范化(忽略大小写相同但库内字面值不同,如库内 Shop.com、入参 shop.com)→ 仅把 domain 规范化为小写并清理新旧两个字面值的公共缓存,校验码与验证状态不变;C 缺码补发·已验证(domain_status=1 但 host/token 为空)→ 仅补发校验码,domain_status/domain_verified_at/attempts 保持原值不降级;D 缺码补发·未验证或失败(domain_status∈{0,2} 且缺码)→ 补发校验码 + domain_status=0 + attempts=0 + 清 last_error;E 域名变更(忽略大小写后不同)→ 行为不变:查重 409、生成新校验码、domain_status=0、attempts=0、清空证书(cert_pem/cert_key/cert_path/key_path/cert_expire_at)+ 重置同步状态、清理新旧两个 domain 缓存;F 首次设置(无记录)→ 行为不变:先查重 409,其余同 E", "未变化短路(A/B/C/D)不再写入 domain_verified_at(该字段现在只在域名变更/首次设置分支被置 null),也不再调用 assertDomainUnique 查重;变更/首次设置(E/F)查重逻辑与 409 文案保持不变", "行为影响提示:domain_status=2(验证失败)的行若 domain_verify_attempts 已达 config.frontConfig.domainVerify.maxAttempts(默认 20),app/schedule/domain_verify_scan.js 不会再自动拾起(计入 skipped),恢复路径为手动调用 frontConfig.checkDomain(checkDomain 无 maxAttempts 门控);且当前没有「更换校验码」的接口,如需该能力需另开接口", "前端不得再依赖「重复调用 setDomain 换新校验码」这一行为;需要新校验码的场景只有库内缺码(C/D 自动补发),其余重复提交均按幂等短路处理", "文档变更范围:methods/system.json 仅更新 frontConfig.setDomain 一条(description 与 notes 重写,params/response/errors/headers 未变,frontConfig 分组仍 8 条),未使用 deleteMethods、未整条覆盖其它条目;methods/changes/system.json 新增本条记录(插入数组首位);根版本 0.3.185 → 0.3.186,updatedAt 保持 2026-09-24", "未处理遗留(仍建议下一批单独修正):frontConfig.getInfo 的 response.domain 描述与 frontConfig.saveInfo 的 description 仍写「domain 只能通过 frontConfig.saveCert 变更」,实际已收敛到 frontConfig.setDomain;本条 spec.methods 只放 setDomain,避免整条覆盖造成语义漂移", "维护源口径冲突(仅记录,未处理):与上一轮一致,methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库" ], "module": "frontConfig" }, { "version": "2026.09.24-return-unpack-notify-by-source", "date": "2026-09-24", "type": "updated", "summary": "拆包完成通知改为按原查询登记来源定向回信:_notifyUnpacked 不再按货主泛推售后群,改为按 wms_return_query_log 登记时记录的 group_id+user_id 聚合回信原查询群/用户(有用户信息时 writeOutboundReply 定向回原查询用户,否则退化为来源群系统通知);登记无来源群的记录不通知;仅推送成功的登记标记 is_notified=1。", "methods": [ "returnUnpack.submit" ], "notes": [ "代码位置:app/service/systems/return_unpack.js _notifyUnpacked(依赖此前新增的登记来源字段 group_id/group_name/user_id/user_name)", "回信链路与 video_record_request._replyResult 口径一致:批量反查 wms_inbox_group 补全 group_name/ext_data/store_id,缺失时用登记快照兜底;定向回信 source=ai_reply(wms_inbox_message 记录 user_id/user_name)" ] }, { "version": "2026.09.24-return-query-log-source-ids", "date": "2026-09-24", "type": "updated", "summary": "退回查询登记表 wms_return_query_log 新增登记来源字段 group_id/group_name/user_id/user_name(迁移 20260924160000-add-source-ids-to-wms-return-query-log):站内信「查退回」触发登记时写入查询来源群/用户信息,用于登记追溯与后续定向通知;returnWaybill.create/list/detail 响应记录同步包含新字段(后台登记路径为 null)。", "methods": [ "returnWaybill.create", "returnWaybill.list", "returnWaybill.detail" ], "notes": [ "代码位置:app/model/return_query_log.js 新增 4 字段;app/service/systems/return_unpack.js queryByWaybill 增加可选入参并在 received/not_returned 两处自动登记时写入来源;app/service/inbox/functions.js queryReturn 透传 ctx.inboxContext 的 group_id/group_name/user_id/user_name", "迁移执行:npx sequelize-cli db:migrate(生产:$env:NODE_ENV='production'; npx sequelize-cli db:migrate --migrations-path database/migrations --env production)", "库表化维护:method-doc-update.cjs 更新 3 个方法 response 说明并 --bump 至 0.3.184,method-doc-export.cjs 回写 methods/system.json" ] }, { "version": "2026.09.24-big-group-pack-coefficient-desc", "date": "2026-09-24", "type": "updated", "summary": "大团购打包系数字段描述统一:subject_config.big_group_pack_coefficient 描述更新为「大团购波次(wave_scope=1)打包中,扫描其他波次订单至少需等待「当前波次打包数 × 系数」秒,单位:秒/单,默认 3,必须大于 0」", "methods": [ "setting.warehouse.getSettings" ], "notes": [ "字段元信息 app/service/systems/setting/warehouse.js(WAREHOUSE_SETTING_FIELDS)中 big_group_pack_coefficient 的 description 已与该口径一致,无代码变更" ] }, { "version": "2026.09.24-workbench-big-group-pack-member-divide", "date": "2026-09-24", "type": "updated", "summary": "大团购打包时长按人数分摊:workbench.packOrder 倒计时字段 pack_wait_seconds 与 workbench.queryOrder 闸门等待秒数改为「大团购打包系数 × 当前波次打包数 ÷ 当前工作台打包人数」;拉取当前打包任务时仅统计进行中任务(status<2,任务已结束则不计);人数为 0 时任务已被成员全部登出流程自动结束,不会出现,仍按 1 兜底防除零", "methods": [ "workbench.packOrder", "workbench.queryOrder" ], "notes": [ "代码位置:app/service/systems/workbench.js(_packOrder 倒计时按 users 成员数分摊、_queryOrder 闸门按 _countCurrentPackMembers 统计 wms_workbench_member 人数分摊)", "回归测试:test/app/service/systems/workbench.bigGroupTimeGate.regression.test.js 新增人数分摊用例(打包 2 人 1×3/2=1.5 秒、闸门 3 人 10×3/3=10 秒),共 13 用例全绿" ] }, { "version": "2026.09.24-setting-big-group-pack-coefficient", "date": "2026-09-24", "type": "updated", "summary": "仓库设置新增大团购打包系数:subject_config 新增 big_group_pack_coefficient(数字,默认 3,单位秒/单,必须大于 0),用于 workbench 大团购波次打包时长闸门与倒计时;setting.warehouse.getSettings 响应新增该字段说明,getFieldMeta 字段元信息列表同步新增该项", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.getFieldMeta" ], "notes": [ "代码位置:app/service/systems/setting/warehouse.js(WAREHOUSE_SETTING_FIELDS 新增字段元信息:type=number、default=3、min=0.1);app/model/store.js(DEFAULT_SUBJECT_CONFIG 与 normalizeSubjectConfig 校验:空值回填 3,非法值抛错)", "读取链路:app/service/systems/delivery_order.js getStoreSubjectConfig(带缓存),workbench 侧经 _getBigGroupPackCoefficient 读取,异常/非法降级默认 3", "无需数据库迁移:配置存于 wms_store.subject_config(JSON 字段),仅需代码发布" ] }, { "version": "2026.09.24-workbench-big-group-pack-gate", "date": "2026-09-24", "type": "updated", "summary": "工作台大团购打包系数与打包时长闸门:workbench.packOrder 打包任务落库 wave_scope,大团购波次(wave_scope=1)响应新增倒计时字段 pack_wait_seconds(当前波次打包数 × 大团购打包系数,单位秒)与 pack_start_time(开始打包时间,毫秒时间戳),其他波次均为 0;workbench.queryOrder 响应 order 新增 wave_scope,并新增大团购打包时长闸门(当前工作台 wave_scope=1 任务未到时仅允许查询本波次订单,其他波次返回「打包时长不足」错误)", "methods": [ "workbench.packOrder", "workbench.queryOrder" ], "notes": [ "数据库迁移:wms_pack_task 新增 wave_scope 列(database/migrations/20260924150000-add-wave-scope-to-pack-task.js,幂等),开发库与生产库均已执行(生产库因存在更早 pending 迁移改为等价 DDL + SequelizeMeta 记录)", "代码位置:app/service/systems/workbench.js(_queryOrder 步骤3.5 闸门、_packOrder 落库与倒计时下发、_getBigGroupPackCoefficient 配置读取);app/model/pack_task.js 新增 wave_scope 字段定义", "回归测试:test/app/service/systems/workbench.bigGroupTimeGate.regression.test.js(11 用例全绿:响应 wave_scope / packOrder 落库与倒计时 / 闸门未到时同波次放行、不同波次拦截、已到时放行、其他 wave_scope 不限制)" ] }, { "version": "2026.09.24-front-config-domain-verify", "date": "2026-09-24", "type": "updated", "summary": "前端独立部署新增「域名归属验证」能力:新增设置/查询/校验域名的 3 个接口(frontConfig.setDomain/getDomain/checkDomain,均需登录、免权限、免鉴权、仅仓库主体可用);两个保存接口不再负责设置域名(saveCert 移除 domain 入参);新增域名验证闸门(getByDomain 仅放行 domain_status=1 的已验证域名、nginx 侧仅对已验证域名生成 server 块);getCert/saveCert 响应新增证书可设置性字段(10 → 13 字段:can_set_cert/can_set_cert_reason/domain_status)。", "methods": [ "frontConfig.setDomain", "frontConfig.getDomain", "frontConfig.checkDomain", "frontConfig.getByDomain", "frontConfig.getCert", "frontConfig.saveCert" ], "notes": [ "数据表与迁移:wms_warehouse_front_config 新增列 domain_status(tinyint 默认 0)/domain_verify_host/domain_verify_token/domain_verified_at/domain_verify_attempts/domain_last_error 与索引 idx_domain_status;迁移文件 database/migrations/20260924120000-add-domain-verify-to-wms-warehouse-front-config.js(幂等:列/索引已存在则跳过)。迁移会把历史非空 domain 的行回填 domain_status=1:存量域名在线上已生效(nginx 已在按域名提供服务),不回填会被新闸门在升级瞬间全部断流(证书上传被拒、公共拉取 404);回填只在真正新增该列的那一次执行,避免把升级后新设但未验证的域名误标为已验证;domain_verified_at 保持 NULL(历史生效时间不可考,不写虚假时间)", "定时任务:新增 app/schedule/domain_verify_scan.js,按 config.frontConfig.domainVerify.interval(默认 10m)扫描待验证行;配置项 enable(true)/interval(10m)/lockTtlSeconds(600)/batchSize(50)/dohUrl(https://doh.pub/dns-query)/timeoutMs(5000)/maxAttempts(20);并发控制为进程内重入标志(ctx.app._domainVerifyScanRunning)+ Redis SET NX EX 跨进程互斥锁(Redis 不可用/抛错时降级为仅进程内防重入并 WARN);业务逻辑全部委托 service.systems.frontConfig.verifyPendingDomains(schedule 内不写 SQL);单行解析/落库失败只计入 errors 不中断整轮;已达 maxAttempts 的行不再自动重试(计入 skipped,仍可由 checkDomain 手动触发)", "DNS 解析:DoH 为主(config.frontConfig.domainVerify.dohUrl,默认 https://doh.pub/dns-query;Status=3 或无 Answer 视为未解析到记录,不重复走系统 DNS),失败降级系统 DNS(node:dns,本仓首次引入,仅服务域名验证链路);校验目标一律为一次性子域 wmsv-<10 位 hex>.<域名>,避免与用户主域已有 TXT 记录(SPF/DKIM/站点校验等)冲突", "配置新增 config.frontConfig.cname(默认空字符串):域名未通过验证时随 getDomain/setDomain/checkDomain 响应返回给前端,提示用户把域名 CNAME 指向该目标", "nginx 侧联动(未改动本次文档范围,仅记录):script/warehouse-cert-sync.cjs 扫描待同步记录时新增 domain_status = 1 过滤(无该列时降级为不过滤并 WARN);script/deploy-cert-sync.cjs 探针新增 domain_status 列探测与取值分布/计数输出(0_unverified/1_verified/2_failed 与 gated-out 行数)", "前端必须改造(不兼容变更):域名设置从 saveCert 迁移到 setDomain —— saveCert 已删除 domain 入参,前端若继续传 domain 会被静默忽略且不再变更域名;正确顺序为 setDomain → 按 verify_host/verify_value 配置 TXT 记录(并按 cname 配置 CNAME)→ checkDomain 手动校验或等待定时任务 → domain_status=1 后才可 saveCert 上传证书;getCert/saveCert 响应新增 can_set_cert/can_set_cert_reason/domain_status,供上传入口置灰与提示文案", "风险提示:config.frontConfig.domainVerify.enable = false 时 app/schedule/domain_verify_scan.js 标记 disable、Egg 不注册该任务,新域名只能靠前端调用 checkDomain 手动触发才会放行;迁移尚未执行时 getByDomain 闸门降级为仅按 domain 查询(一次性 WARN),需迁移完成并重启实例后闸门才真正生效;getByDomain 命中配置缓存最长 600s 内仍可能放行刚被置为未验证的域名(setDomain/saveCert/校验成功均已主动清缓存,实际窗口极短,接受该取舍)", "文档变更:methods/system.json 的 frontConfig 分组新增 3 条(setDomain/getDomain/checkDomain,均 isNeedLogin=true、isNeedAuth=false、带 Authorization 头)+ 更新 3 条(getByDomain 描述补充闸门语义与迁移降级说明,params/response/errors 未变;getCert 响应 10 → 13 字段;saveCert 删除 domain 入参、新增前置闸门、response 10 → 13 字段、errors 同步收敛);spec.methods 只放上述 6 条,未放入 getInfo/saveInfo(避免整条覆盖造成语义漂移);未使用 deleteMethods;根版本 0.3.178 → 0.3.179,updatedAt 保持 2026-09-24", "已知遗留(本次未处理,建议下一批单独修正):frontConfig.getInfo 与 frontConfig.saveInfo 的描述仍写「domain 只能通过 frontConfig.saveCert 变更」,实际域名变更已收敛到 frontConfig.setDomain;这两条不在本批 spec.methods 内(避免整条覆盖),故未同步", "变更记录条目数 640 → 641(新记录插入数组首位,既有 640 条 version 未改动、未删除)", "维护源口径冲突(仅记录,未处理):与上一轮维持一致,methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库", "自动清单刷新:node temp/tmp-gen-service-method-inventory.cjs 与 node temp/tmp-update-ai-method-routing.cjs(AI_METHOD_ROUTING.md 第 6 节 SERVICE_METHOD_INVENTORY 标记区与 temp/tmp-service-method-inventory.md 同步刷新)", "docs/*.md 无需同步:检索 frontConfig/setDomain/checkDomain/域名验证 未命中解释性文档(仅 AI_METHOD_ROUTING.md 与 temp/tmp-service-method-inventory.md 含自动清单命中,已由刷新脚本处理)" ], "module": "frontConfig" }, { "version": "2026.09.24-front-config-saveCert-response-fix", "date": "2026-09-24", "type": "updated", "summary": "修正 frontConfig.saveCert 的响应契约:由错误的 8 字段品牌口径(buildInfoOutput:warehouse_id/domain/title/logo_url/favicon_url/login_bg_url/theme/updated_at)更正为 10 字段证书口径(buildCertOutput,与 frontConfig.getCert 一致:warehouse_id/domain/cert_pem/key_pem/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at);入参 domain/pem/key 与错误码 400/403/409/500 口径不变,其余 frontConfig 条目(getInfo/getCert/saveInfo/getByDomain)未改动。本记录闭环 2026.09.24-front-config-migrate-to-frontConfig 中标注的「saveCert 响应口径待确认」一项。", "methods": [ "frontConfig.saveCert" ], "notes": [ "闭环说明:本记录闭环 2026.09.24-front-config-migrate-to-frontConfig 中标注的「saveCert 响应口径待确认」一项(该记录 notes 第 6 条:JSDoc 声明返回 10 字段证书输出,但实现实际 return this.buildInfoOutput(...) 返回 8 字段品牌信息);按工作流「新记录插入数组头部、历史记录不回改」,原记录保持原样,修正以本记录承接", "代码证据:app/service/systems/frontConfig.js:782 saveCert 出口 return this.buildCertOutput(savedRecord, warehouseId);buildCertOutput 定义于同文件 :202,输出 10 字段 warehouse_id/domain/cert_pem/key_pem/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at(其中 key_pem 读 cert_key 列)", "由 wms-dev-agent 修正实现(saveCert 返回由 buildInfoOutput 改为 buildCertOutput),本次仅同步文档口径,未改动任何代码", "文档变更:methods/system.json 的 frontConfig 分组仅更新 saveCert 一条(spec.methods 只放这一条,未放入 getInfo/getCert/saveInfo/getByDomain,避免整条覆盖造成语义漂移;未使用 deleteMethods);响应字段 8 -> 10,method 级 notes 中「响应口径待确认」一条被替换为「响应契约修正」;headers/params/errors 沿用既有条目不变;根版本 0.3.177 -> 0.3.178,updatedAt 保持 2026-09-24", "通配语义同步写准:certCoversDomain 的 *.example.com 分支(app/service/systems/frontConfig.js:512)要求通配前缀非空且不含「.」,即仅覆盖恰好一级标签;*.a.com 覆盖 b.a.com,不覆盖 x.y.a.com(报 400「证书不合法」)", "变更记录条目数 639 -> 640(新记录插入数组首位,既有 639 条 version 未改动、未删除);script/update-api-doc.cjs 的 appendChange 仅支持 unshift + 重复 version 拦截,无整条替换既有 change 的能力,故未回改上一条记录的 note", "无代码结构变化,未重新生成 AI_METHOD_ROUTING.md 与 temp/tmp-service-method-inventory.md(上一轮已刷新,本次仅文档响应口径修正)", "维护源口径冲突(仅记录,未处理):与上一轮维持一致,methods/*.json 的维护源是否为数据库表 wms_method_doc_meta 仍待用户决策;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库" ], "module": "frontConfig" }, { "version": "2026.09.24-front-config-migrate-to-frontConfig", "date": "2026-09-24", "type": "updated", "summary": "前端独立部署接口从 setting.warehouse 迁移到 frontConfig 模块:删除 setting.warehouse.getFrontConfig / saveFrontConfig / saveFrontCert 三个旧方法(出口、服务实现与鉴权白名单同步移除,实测调用返回「方法 xxx 不存在」),新增 frontConfig.getInfo / getCert / saveInfo / saveCert 四个需登录、免权限、免鉴权的配置接口(权限由业务层 isWarehouse 判定,仅仓库主体可用);公共按域名拉取接口 frontConfig.getByDomain 保持不变(仍 6 字段公开白名单,免登录免权限免鉴权)。", "methods": [ "frontConfig.getInfo", "frontConfig.getCert", "frontConfig.saveInfo", "frontConfig.saveCert", "setting.warehouse.getFrontConfig", "setting.warehouse.saveFrontConfig", "setting.warehouse.saveFrontCert" ], "notes": [ "代码变更:新增出口 app/service/systemMethods/frontConfig.js 的 getInfo/getCert/saveInfo/saveCert(_noNeedRight/_noNeedAuth/_noNeedLog 均含这 4 个方法;_noNeedLogin 仍仅 getByDomain),实现见新增服务 app/service/systems/frontConfig.js(TEXT_FIELDS/PUBLIC_FIELDS 白名单、buildInfoOutput/buildCertOutput/buildPublicOutput)", "代码变更:app/service/systemMethods/setting/warehouse.js 与 app/service/systems/setting/warehouse.js 中 getFrontConfig/saveFrontConfig/saveFrontCert 的出口与实现已删除,_noNeedRight 收敛为 getSettings,getFieldMeta,saveSettings,getweChatApp;methods/system.json 中 setting.warehouse 分组仅删除这 3 条条目,分组与 getSettings/getFieldMeta/saveSettings 保留", "文档变更:methods/system.json 删除 setting.warehouse 分组下 3 条旧条目(原 L15632 saveFrontConfig / L15797 getFrontConfig / L15914 saveFrontCert),frontConfig 分组(groupName 前端独立部署模块)新增 4 条条目(isNeedLogin=true、isNeedAuth=false、Authorization 头);frontConfig.getByDomain 条目未改动(未放入本次 spec.methods,避免整条覆盖造成语义漂移);根版本 0.3.176 -> 0.3.177,updatedAt 2026-09-23 -> 2026-09-24", "saveInfo 口径:upsert 一仓一行;仅受理 title(≤100)/logo_url、favicon_url、login_bg_url(≤255)/theme(合法 JSON 对象或 JSON 字符串),domain 与证书字段由方法层白名单静默忽略;保存即重置同步状态(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at);写库成功后清当前 domain 公共拉取缓存(清缓存失败仅记日志)", "saveCert 口径:校验链 证书可解析 → 未生效拒绝 → 已过期拒绝 → 私钥与证书 SPKI 配对 → 证书 SAN/CN 覆盖 domain(支持 *.example.com 通配,仅匹配一级标签) → domain 全局唯一;校验链任一失败统一 400「证书不合法」不吐细节;cert_expire_at 以证书 validTo 权威写入;cert_pem/cert_key 直接入库、cert_path/key_path 置 null(等待 script/warehouse-cert-sync.cjs 部署后回填);写库后同时清旧 domain 与新 domain 两个公共缓存 key", "响应口径待确认:app/service/systems/frontConfig.js saveCert 的 JSDoc(及方法层注释)声明返回证书输出(10 字段含 cert_pem/key_pem),但实现实际 return this.buildInfoOutput(...) 返回 8 字段品牌信息、不含证书字段;本文档按当前实现(8 字段)编写,若确认应返回证书输出需先修正实现再同步文档", "维护源口径冲突(仅记录,未处理):methods/changes/system.json 既有记录备注「维护源是数据库表 wms_method_doc_meta,methods/*.json 只是导出产物」,仓库内已存在 script/method-doc-*.cjs 工具链与迁移 database/migrations/20260923150000-create-method-doc-tables.js;本次仍按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库,待用户决策是否需要回灌数据库维护源", "自动清单刷新:node temp/tmp-gen-service-method-inventory.cjs 与 node temp/tmp-update-ai-method-routing.cjs(AI_METHOD_ROUTING.md 第 6 节 SERVICE_METHOD_INVENTORY 标记区与 temp/tmp-service-method-inventory.md 同步刷新,会顺带更新扫描时间与文件/方法计数,属脚本预期行为)", "docs/*.md 与 README.md 无需同步:检索 getFrontConfig/saveFrontConfig/saveFrontCert/前端独立部署/frontConfig/getByDomain 未命中任何解释性文档(仅 AI_METHOD_ROUTING.md 与 temp/tmp-service-method-inventory.md 含自动清单命中,已由刷新脚本处理)" ], "module": "frontConfig" }, { "version": "2026.09.23-returnReceived-create-is-urgent", "date": "2026-09-23", "type": "updated", "summary": "returnReceived.create 响应新增 is_urgent 加急标记(boolean):wms_return_query_log(退回查询记录表)按 仓库+运单号 精确匹配,命中即 true,未命中或查询失败降级为 false;幂等命中(duplicated=true)与新创建(duplicated=false)两个分支均返回该字段", "methods": [ "returnReceived.create" ], "notes": [ "代码变更:app/service/systems/return_received.js 的 create 在幂等命中与新登记两个返回分支均新增顶层 is_urgent 字段,并新增私有辅助方法 _isUrgentReturnQuery(waybillCode, warehouseId)(含 JSDoc)", "判定口径:wms_return_query_log(退回查询记录表)中存在 warehouse_id=当前仓库且 waybill_code=登记运单号(精确匹配)的记录时为 true,否则 false;查询失败降级为 false,不影响登记主流程", "方法层 app/service/systemMethods/returnReceived.js 无需改动;文档变更:response 新增 is_urgent(boolean,required=true);维护源 wms_method_doc_meta 与导出产物 methods/system.json 版本同步至 0.3.176(dashboard.hot_order_rank mask 变更同步入库 0.3.175,本次变更升至 0.3.176)" ], "module": "returnReceived" }, { "version": "2026.09.23-dashboard.hot_order_rank.mask", "date": "2026-09-23", "type": "updated", "summary": "dashboard.hot_order_rank 响应口径调整:data[].sku 由商品编码改为库存商品ID(stock_warehouse.id);data[].name 做脱敏处理(前2字符+***+后2字符,长度不足 4 字符时返回 ***)", "methods": [ "dashboard.hot_order_rank" ], "notes": [ "代码变更:app/service/systemMethods/dashboard.js 中 buildHotOrderRankMap/mergeHotOrderRank 的聚合条目新增 stockId(订单明细 stock_id),并在货主端跨仓合并时保留首个非 0 值", "代码变更:resolveHotOrderRankProduct 的 sku 改为返回库存商品ID(number,stock_warehouse.id),仅当 stock_id 缺失时回退商品编码字符串;新增 maskHotOrderRankName 对最终展示名称统一脱敏(长度>=4 时前2字符+***+后2字符,否则返回 ***)", "文档变更:data[].sku 类型改为 number 并更新描述;data[].name 描述补充脱敏规则;根版本 0.3.174 -> 0.3.175" ], "module": "dashboard" }, { "version": "2026.09.23-returnReceived-list-created-at-filter", "date": "2026-09-23", "type": "updated", "summary": "修复 returnReceived.list 登记时间(created_at)筛选不生效问题:_buildListWhere 白名单补充 created_at/updated_at,并补齐文档此前缺失但代码已支持的 where 字段(scanner_name/order_express_id/order_id);returnReceived.export 的 where 语义描述同步更新(与 list 一致)。配套新增 wms_return_received 索引 idx_warehouse_created_at(warehouse_id, created_at)(迁移 20260923180000),优化登记时间范围过滤与默认 created_at desc 排序。", "methods": [ "returnReceived.list", "returnReceived.export" ], "notes": [ "代码变更:app/service/systems/return_received.js _buildListWhere 的 directFields 白名单补充 created_at、updated_at(list 与 exportList 同时生效)", "数据库变更:database/migrations/20260923180000-add-created-at-index-to-wms-return-received.js 新增 idx_warehouse_created_at(warehouse_id, created_at),已在开发库执行", "文档变更:returnReceived.list 新增 where.created_at / where.updated_at / where.scanner_name / where.order_express_id / where.order_id 参数说明,description 更新;returnReceived.export 的 where 参数描述补充 created_at/updated_at 范围", "文档库版本 0.3.173 -> 0.3.174(wms_method_doc_meta.version),methods/system.json 为导出产物" ] }, { "version": "2026.09.23-dashboard.hot_order_rank.realtime", "date": "2026-09-23", "type": "updated", "summary": "dashboard.hot_order_rank 由演示数据改为真实数据库查询:统计今日(00:00 至当前时刻)销量 Top10 商品及环比昨日趋势;仓库端单仓统计,货主端跨已签约仓库聚合", "methods": [ "dashboard.hot_order_rank" ], "notes": [ "核实 app/service/systemMethods/dashboard.js 实现后更新:废弃旧版 mock 数据,改为查询订单常用表/配送分表(OrderDeliveryFactory/OrderItemsFactory 的 current 与 dispatch)聚合", "口径:今日窗口 [今日 00:00, 当前时刻),昨日窗口 [昨日 00:00, 今日 00:00);value 为窗口内非取消、非异常、未删除订单的商品计划数量(plan_qty)合计;trend 为环比昨日百分比(保留 1 位小数,昨日为 0 且今日 >0 时按 100)", "仓库端使用 ctx.user.store_id 单仓统计;货主端(store_type=store)跨已签约仓库(auth_status=2)并行统计并按商品聚合;按今日销量降序取前 10 条,无数据时返回空数组", "响应更新:data[].name 无名称回退商品编码/商品+库存ID、data[].sku 无编码回退 SKU+库存ID;错误码补充 code=0(缺少仓库/货主上下文),500 改为订单数据查询失败", "文档库表同步:method-doc-update.cjs 更新 description/response/errors 并 --bump,method-doc-export.cjs 回写 methods/system.json" ], "module": "dashboard" }, { "version": "2026.09.23-dashboard.charts.doc", "date": "2026-09-23", "type": "updated", "summary": "补齐看板模块其余 5 个接口文档:express_ratio/platform_distribution/order_trend 为实时统计接口,warehouseStats/hot_order_rank 为演示数据接口(描述已标注);均无业务入参", "methods": [ "dashboard.express_ratio", "dashboard.platform_distribution", "dashboard.order_trend", "dashboard.warehouseStats", "dashboard.hot_order_rank" ], "notes": [ "核实 app/service/systemMethods/dashboard.js 实现后补齐", "express_ratio/platform_distribution 货主端跨已签约仓库(auth_status=2)汇总,返回 name/value/itemStyle.color 结构", "order_trend 按小时统计 08:00 至当前小时,返回 summary/categories/orders/shipments", "warehouseStats/hot_order_rank 当前为固定演示数据,待业务接入真实统计后需同步更新文档" ] }, { "version": "2026.09.23-dashboard.storeStats.doc", "date": "2026-09-23", "type": "updated", "summary": "补齐 dashboard.storeStats 接口文档:补充描述、13 个响应统计字段与错误码(无业务入参,依据登录用户上下文区分仓库端/货主端)", "methods": [ "dashboard.storeStats" ], "notes": [ "核实 app/service/systemMethods/dashboard.js 实现后补齐", "仓库端按当前用户 store_id 单仓统计;货主端跨已签约仓库(auth_status=2)汇总" ] }, { "version": "2026.09.23-index.tryAutoTranslateNewKeys.doc", "date": "2026-09-23", "type": "updated", "summary": "补全 index.tryAutoTranslateNewKeys 文档:明确其为 putI18nCollect 的内部辅助方法,补充 project/targetLanguage 参数说明,注明无对外返回值、异常仅记日志、不建议作为 HTTP API 直接调用", "methods": [ "index.tryAutoTranslateNewKeys" ], "notes": [ "代码事实:app/service/systemMethods/index.js:1512 async tryAutoTranslateNewKeys(project, targetLanguage),仅被 putI18nCollect(1451 行)内部调用;目标语言为 zh-CN 直接返回;为 zh-CN 已有翻译的键批量创建目标语言占位(translation=null、translation_status=0、auto_generated=1、translator=auto-translate);无返回值,异常被内部 try/catch 吞掉仅记日志。", "文档库表同步:method-doc-update.cjs 更新 description/params 并 --bump(版本 0.3.169 -> 0.3.170),method-doc-export.cjs 回写 methods/system.json(562 个方法)。", "说明:/system 通用分发不区分 public 与内部函数,该方法理论上可被直接调用,文档已注明不建议直接调用。" ], "module": "index" }, { "version": "2026.09.23-wechat.dropAgreementVersionNumber", "date": "2026-09-23", "type": "updated", "summary": "用户须知版本表去掉 version 数字版本号,直接使用 id 自增:最新版判定改 ORDER BY id DESC,提交即插入新行(去掉 max+1 与并发重试),接口响应只保留 version_id", "methods": [ "wechat.getUserAgreementText", "wechat.getUserAgreement", "wechat.setUserAgreement", "wechat.getAgreementVersion", "wechat.loginByCode" ], "notes": [ "迁移 20260923140000-drop-version-from-wechat-agreement-version(开发+生产均执行):removeIndex uk_appid_version + removeColumn version;down 为加回列与唯一索引。同步 app/model/wechat_agreement_version.js 删 version 字段与唯一索引(仅保留 idx_appid)。", "最新版判定统一为 ORDER BY id DESC(loginByCode/getUserAgreementText/getUserAgreement/findLatestAgreementVersion/cleanupUnusedAgreementVersions 的最终版=max(id));setUserAgreement 改为直接 create(appid+content),无并发重试;getUserAgreementText 缓存 JSON 仅 {version_id,text}。", "接口响应精简:getUserAgreementText/getUserAgreement/setUserAgreement 去掉 version 字段、getAgreementVersion 去掉 version 字段,均保留 version_id(=记录 id)。" ], "module": "wechat" }, { "version": "2026.09.23-wechat.getAgreementVersion", "date": "2026-09-23", "type": "added", "summary": "新增 wechat.getAgreementVersion(按协议版本 id 获取协议内容,需登录免权限+校验仓库);wechat.userList 响应新增 agreement_version_id(协议id)", "methods": [ "wechat.getAgreementVersion", "wechat.userList" ], "notes": [ "wechat.getAgreementVersion:入参 id(wms_wechat_agreement_version.id,来源 userList 的 agreement_version_id),按 id 查版本 → 校验该版本 appid 属于当前仓库启用小程序(warehouse_id=ctx.user.store_id, is_enabled=1),不属于则提示「该协议版本不属于当前仓库的小程序」;返回 id/appid/nickname/version/text/created_at。需登录免权限(systemInit 第2/4参)。", "wechat.userList:响应行新增 agreement_version_id(数值化,null 保持 null),sortField 白名单新增 agreement_version_id;该字段由 loginByCode 自动回写,供前端按版本 id 拉取协议内容。", "代码变更:app/service/systems/wechat.js 新增 getAgreementVersion + userList 响应数值化/排序白名单;app/service/systemMethods/wechat.js 白名单与出口同步。" ], "module": "wechat" }, { "version": "2026.09.23-wechat.agreementVersionCleanup", "date": "2026-09-23", "type": "updated", "summary": "新增定时任务:每 1 小时扫描 wms_wechat_agreement_version,真实删除未使用且非对应 appid 最终版的历史版本,释放 MySQL 磁盘", "methods": [], "notes": [ "保留规则:① 各 appid 的最终版(version 最大)永久保留;② 被 wms_user_oauth.agreement_version_id 引用的版本保留(老用户仍停留在旧协议);其余版本真实删除(模型 paranoid=false)。", "触发:app/schedule/wechat_agreement_cleanup.js,cron 从 config.wechatAgreementCleanup.cron 读取(默认 0 0 * * * * = 每 1 小时整点,type=worker 单 worker 防重入,enable=false 不注册);清理逻辑收敛在 service.systems.wechat.cleanupUnusedAgreementVersions(batchSize 默认 500,按 id 分批删走主键索引)。", "每次任务完成后输出日志:deleted/kept_latest/kept_in_use/total;失败仅记 error 日志不抛出。" ], "module": "wechat" }, { "version": "2026.09.23-wechat.userAgreement.versioning", "date": "2026-09-23", "type": "updated", "summary": "用户须知改为副表版本管理:移除 wms_wechat_app.user_agreement;新增 wms_wechat_agreement_version(appid+数字版本号+富文本,提交一次自动新增版本,拉取只取最新);wms_user_oauth 加 agreement_version_id,loginByCode 自动更新到最新协议版本", "methods": [ "wechat.getUserAgreementText", "wechat.getUserAgreement", "wechat.setUserAgreement", "wechat.loginByCode" ], "notes": [ "迁移 20260923130000-user-agreement-versioning(开发+生产均执行):① removeColumn wms_wechat_app.user_agreement;② createTable wms_wechat_agreement_version(id/appid/version INT/content LONGTEXT/时间戳,uk_appid_version(appid,version) 唯一 + idx_appid);③ addColumn wms_user_oauth.agreement_version_id(BIGINT UNSIGNED 可空,关联版本表 id)。同步 app/model/wechat_agreement_version.js 新增、wechat_app.js/user_oauth.js 字段同步。", "wechat.setUserAgreement:提交一次自动新增版本——查该 appid 最大 version 后 +1 插入(并发撞唯一键时重算重试最多 3 次),成功后 cacheDel 清 24h 缓存;返回 version_id/version/text。", "wechat.getUserAgreementText/getUserAgreement:拉取只拉最新版本(ORDER BY version DESC);getUserAgreementText 缓存 24h 存 JSON {version_id,version,text},命中 from_cache=true;无版本分别提示「未找到对应小程序或该小程序暂无用户须知」/「该小程序暂无用户须知」。", "wechat.loginByCode:查该小程序 appid 最新协议版本 id,oauth 新增/更新时自动写入 agreement_version_id(无需前端传入,为空版本表时为 null)。", "代码变更:app/service/systems/wechat.js loginByCode/getUserAgreementText/getUserAgreement/setUserAgreement 改版并新增 findLatestAgreementVersion;systemMethods 无签名变化。" ], "module": "wechat" }, { "version": "2026.09.23-wechat.userAgreement", "date": "2026-09-23", "type": "added", "summary": "新增用户须知三接口:wms_wechat_app 加 user_agreement(LONGTEXT)字段;wechat.getUserAgreementText(免登录,appId 查询 + 24h Redis 缓存)、wechat.getUserAgreement(需登录,当前仓库)、wechat.setUserAgreement(需登录,更新并清缓存)", "methods": [ "wechat.getUserAgreementText", "wechat.getUserAgreement", "wechat.setUserAgreement" ], "notes": [ "迁移 20260923120000-add-user-agreement-to-wms-wechat-app:wms_wechat_app 仅加 user_agreement 字段(Sequelize TEXT('long') = LONGTEXT,allowNull,comment 用户须知富文本),同步 app/model/wechat_app.js。开发+生产均需执行(生产:$env:NODE_ENV='production'; npx sequelize-cli db:migrate --migrations-path database/migrations --env production)。", "wechat.getUserAgreementText:免登录(systemInit 第1参),入参 appId;Redis key wechat:userAgreement:{appid},TTL 24h,命中直接返回 from_cache=true;未命中查 wms_wechat_app.user_agreement 并回写缓存;无该 appid 返回「未找到对应小程序」。", "wechat.getUserAgreement/setUserAgreement:需登录免权限(systemInit 第2/4参),按 ctx.user.store_id 取启用小程序(is_enabled=1),无则提示「无小程序,需要先绑定」;set 校验 text 为字符串(可空串清空)→ update 后 cacheDel 清除 24h 缓存。", "代码变更:app/service/systems/wechat.js 新增 getUserAgreementText/getUserAgreement/setUserAgreement/findWarehouseWechatApp;app/service/systemMethods/wechat.js 白名单与出口同步。" ], "module": "wechat" }, { "version": "2026.09.23-wechat.bindByEmployee", "date": "2026-09-23", "type": "added", "summary": "新增 wechat.bindByEmployee:管理员按工号绑定微信(需登录需权限),传工号 id + 微信绑定记录 id,查工号账号 id 写入 wms_user_oauth.user_id", "methods": [ "wechat.bindByEmployee" ], "notes": [ "新增接口 wechat.bindByEmployee(需登录需权限,区别于中间层 wechat.bindUser 的用户名密码自绑定):入参 id(工号 id=wms_account_store_employee.id,必填正整数)与 oauth_id(微信绑定记录 id=wms_user_oauth.id,必填正整数,来自 wechat.userList 结果)。", "业务:工号存在且 status=1 → account_id;工号须属于当前仓库(store_id=ctx.user.store_id);oauth 须存在、provider=wechat、未绑定或已绑定同一账号(已绑其他账号拒绝换绑);oauth.app_id 存在时校验对应 wms_wechat_app 属于当前仓库;账号存在且 status=1。校验通过后 wms_user_oauth.user_id=account_id,幂等返回 already_bound。不签发 token。", "鉴权:不加入 systemInit 任何白名单 → 需正常登录 token 且需 wms_permission 接口权限(path=wechat.bindByEmployee,type=api,需在开发库插入该权限记录并由管理员在角色中勾选后生效)。", "代码变更:app/service/systems/wechat.js 新增 bindByEmployee;app/service/systemMethods/wechat.js 新增 bindByEmployee 出口。" ], "module": "wechat" }, { "version": "2026.09.23-wechat.wxaauth-new-api", "date": "2026-09-23", "type": "updated", "summary": "wechat.wxaauth 迁移到微信新版认证接口:旧接口 /wxa/sec/wxaapi/wxaauth、/wxa/sec/wxaapi/uploadmedia 已下线(40066 invalid url),改为 POST /wxa/sec/wxaauth(auth_data 包裹)+ POST /wxa/sec/uploadauthmaterial(mediaid)", "methods": [ "wechat.wxaauth" ], "notes": [ "根因:微信下线旧版小程序认证接口,调用 /wxa/sec/wxaapi/wxaauth 与 /wxa/sec/wxaapi/uploadmedia 返回 40066 invalid url(与 queryauth 当年同因:路径不存在,详见 2026.09.22-wechat.queryauth-fix 记录)。", "发起认证改为 POST /wxa/sec/wxaauth,请求体 { auth_data }:customer_type(1 企业/12 个体户/15 个人)、account_name、account_name_type(1 自选词汇/2 商标)、pay_type(1 服务商预购包/2 自行支付)、third_party_phone、contact_info{name,email,mobile?} 必填;invoice_info/qualification/qualification_other(≤10)/account_supplemental/auth_identification/auth_ident_material/service_appid(代缴必填)/taskid 可选。", "上传材料改为 POST /wxa/sec/uploadauthmaterial(multipart media=文件,图片 ≤2M,PNG/JPEG/JPG/GIF),返回 mediaid(lib 层归一化为 media_id)。自动换 mediaid 的图片字段:qualification(单张)、qualification_other[]/account_supplemental[]/auth_ident_material[](数组),支持传 COS URL。", "破坏性变更:入参由旧扁平字段(contact_type/contact_name/contact_cert_photo/business_license_*/legal_persona_*/pic_list/qualification_list/statement_list 等 33 字段白名单)改为新版 auth_data 字段,前端需同步切换。打回重填走新接口 POST /wxa/sec/reauth(同 auth_data + taskid,暂未接入,可后续补 wechat.reauth)。", "代码变更:app/lib/wechat_open_client.js wxaauth/uploadAuthMedia 路径与 mediaid 归一化;app/service/systems/wechat.js wxaauth/resolveBodyMedia/resolveMediaValue 换新字段;app/service/systemMethods/wechat.js 注释同步。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.wxaauth-cos-url", "date": "2026-09-22", "type": "updated", "summary": "wechat.wxaauth 改为后端分步:图片字段传 COS 文件 URL,后端下载 → uploadmedia 换 media_id → wxaauth 提交", "methods": [ "wechat.wxaauth" ], "notes": [ "后端分步:① 图片字段值为 http/https(COS URL)时,后端 GET 下载 Buffer → POST /wxa/sec/wxaapi/uploadmedia(multipart/form-data,media_type=image,media=临时文件)换 media_id;② 替换请求体后调 /wxa/sec/wxaapi/wxaauth 提交。非 URL 值视为已传 media_id 原样透传。", "支持自动换 media_id 的图片字段:顶层 contact_cert_photo/business_license_copy/legal_persona_idcard_copy/legal_persona_media;pic_list 项的 pic_url;qualification_list 项 licence_list/certificate_list 的 value;statement_list 项的 value。", "uploadmedia 实现细节:Buffer 写临时文件(文件名带 jpg/jpeg/png 扩展名,从 URL path 提取,默认 image.jpg)后按路径传 files:{media}(urllib 2.44 files 支持 Buffer 但文件名固定 bufferfileN 无扩展名,故落临时文件保证扩展名),finally 删除临时文件;40001/40014 清 authorizer token 重试一次。media_id 3 天内有效。", "代码变更:app/lib/wechat_open_client.js 新增 uploadAuthMedia;app/service/systems/wechat.js 新增 resolveBodyMedia/resolveMediaValue/downloadFromUrl/resolveMediaFilename 并在 wxaauth 中调用。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.wxaauth", "date": "2026-09-22", "type": "added", "summary": "新增 wechat.wxaauth 发起小程序认证(一步提交):前端上传材料换 media_id 后传入,后端调 wxa/sec/wxaapi/wxaauth,成功回写 auth_task_id/auth_apply_status", "methods": [ "wechat.wxaauth" ], "notes": [ "新增接口 wechat.wxaauth(需登录免权限,权限集 18):前端负责上传材料换取 media_id 后一步提交;入参白名单透传(contact_type/contact_name 必填,其余 contact_*/business_license_*/legal_persona_*/pic_list 等 33 字段白名单)。", "成功回写 wms_wechat_app.auth_task_id=taskid、auth_apply_status(auth_task_status 置空),返回 taskid/auth_url/apply_status;taskid 供 wechat.queryauth 查询进度(taskid 可选,库中 auth_task_id 兜底)。", "已认证(verify_type_id>=0)拒绝重复发起;未授权权限集 18 拒绝。lib#wxaauth 40001/40014 清 authorizer token 重试一次。不拆表:认证状态继续复用 wms_wechat_app 现有字段,无迁移。", "代码变更:app/lib/wechat_open_client.js 新增 wxaauth;app/service/systems/wechat.js 新增 wxaauth;systemMethods/wechat.js 白名单与出口同步。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.queryauth-verified-first", "date": "2026-09-22", "type": "updated", "summary": "wechat.queryauth 改为先判已认证再查进度:已认证直接返回认证信息;未认证且有 taskid 才调微信查进度;taskid 可选(库中 auth_task_id 兜底);认证通过回写 verify_type_id=0", "methods": [ "wechat.queryauth" ], "notes": [ "判定顺序:① 本地 wms_wechat_app.verify_type_id>=0(已认证)→ 直接返回本地认证信息(is_verified=true/verify_type_id/principal_name/signature/service_type_id/account_status),不调微信;② 未认证(null/-1)→ taskid(入参优先,其次库中 auth_task_id)调 wxa/sec/queryauth 查进度;③ 未认证且无 taskid → 返回 code 200「尚未认证且无认证任务」(is_verified=false)。", "落库:查询成功回写 auth_task_id/auth_task_status/auth_apply_status;apply_status=4(认证通过)时同时回写 verify_type_id=0(微信认证),后续 queryauth 直接走已认证分支。", "文档:system.json wechat.queryauth 条目 params(taskid 改可选)/response(新增 is_verified/verify_type_id/principal_name 等)同步。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.getAuthorizerInfo-db-fields", "date": "2026-09-22", "type": "added", "summary": "新增 wechat.getAuthorizerInfo 基础信息接口;wms_wechat_app 补充授权账号基础信息与认证状态字段(13列);认证 taskid/状态随 queryauth 成功落库", "methods": [ "wechat.getAuthorizerInfo", "wechat.queryauth" ], "notes": [ "新增接口 wechat.getAuthorizerInfo(需登录免权限):调微信 POST /cgi-bin/component/api_get_authorizer_info(component_access_token)拉取 authorizer_info + authorization_info,将基础信息/认证类型/权限集落库 wms_wechat_app 后返回完整数据。", "迁移 20260922180000-add-authorizer-info-fields-to-wms-wechat-app:wms_wechat_app 新增 principal_name/signature/alias/qrcode_url/service_type_id/verify_type_id/account_status/register_type/business_info/mini_program_info/auth_task_id/auth_task_status/auth_apply_status,开发+生产均已执行。", "verify_type_info.id 语义:-1 未认证、0 微信认证、1 新浪微博认证、3 资质通过未名称认证、4 同3+微博;account_status:1 正常、14 已注销、16 已封禁、18 已告警、19 已冻结。", "认证任务落库口径:taskid 由发起认证接口(wxa/sec/wxaapi/wxaauth,暂未接入)返回,queryauth 查询成功后回写 auth_task_id/auth_task_status/auth_apply_status。", "代码变更:app/lib/wechat_open_client.js 新增 getAuthorizerDetail(完整返回);app/service/systems/wechat.js 新增 buildAuthorizerPatch/getAuthorizerInfo、queryauth 增加状态落库;app/controller/wechatOpen.js 授权回调/authorized/updateauthorized 事件改用 getAuthorizerDetail 全量字段落库;app/model/wechat_app.js、systemMethods/wechat.js 同步。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.getAuthUrl-scope", "date": "2026-09-22", "type": "updated", "summary": "wechat.getAuthUrl 授权链接限定授权范围:auth_type=2(仅小程序)+ category_id_list=18|86(代码管理、体验版二维码)", "methods": [ "wechat.getAuthUrl" ], "notes": [ "修正认知:auth_type 是授权账号类型(1公众号/2小程序/3公众号+小程序),不是权限范围;权限范围由 category_id_list(权限集 id 列表,竖线分隔)或商家在授权页自定义勾选控制。业务所需权限集:18=小程序代码管理(commit/submit_audit/queryauth/get_qrcode)、86=体验版二维码;getTemplateList/jscode2session/快速注册不需要商家权限集。", "代码变更:app/service/systems/wechat.js#getAuthUrl 授权链接增加 category_id_list=18|86、auth_type 改为 2。前提:18/86 需在微信开放平台后台「权限集」配置并全网发布,否则商家授权页看不到;已授权商家需重新扫码授权才能获得 18/86。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.commit-ext-json-default", "date": "2026-09-22", "type": "updated", "summary": "wechat.commit 的 ext_json 改为后端默认生成(仅 extEnable+extAppid),不再由前端传入", "methods": [ "wechat.commit" ], "notes": [ "入参仅剩 template_id;ext_json 由后端生成 JSON.stringify({extEnable:true, extAppid: 当前小程序appid}),前端传值被忽略;响应新增 ext_json 回显。", "代码变更:app/service/systems/wechat.js#commit;文档 system.json wechat.commit 条目 params/response 同步。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.commit-desc-from-template", "date": "2026-09-22", "type": "updated", "summary": "wechat.commit 代码描述也改为从模板取:user_version 与 user_desc 均不再由外部传入", "methods": [ "wechat.commit" ], "notes": [ "入参进一步瘦身:user_desc 也移除(外部传入被忽略);commit 流程:getTemplateList(0) → 按 template_id 找模板 → 取模板 user_version(≤64)与 user_desc 作为上传版本号/代码描述(缺失分别报「模板缺少合法版本号/缺少代码描述」)→ wxa/commit 成功后回写 wms_wechat_app.template_id/user_version;响应新增 user_desc。", "代码变更:app/service/systems/wechat.js#commit;文档 system.json wechat.commit 条目 params/response 同步。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.userList", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.userList(需登录):拉取当前仓库小程序的用户列表(wms_user_oauth),支持 where/pagination/sort", "methods": [ "wechat.userList" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.userList(isNeedLogin=true、isNeedAuth=false、Authorization 头):按 ctx.user.store_id 取仓库启用小程序(wms_wechat_app,is_enabled=1;可选 app_id 指定单个,须属于当前仓库),查询 wms_user_oauth(provider=wechat,app_id IN 命中应用);入参 where(字段白名单 id/user_id/app_id/openid/unionid/nickname/sex/login_time/login_count/created_at/updated_at,operator 结构,经 prepareWhereContext 解析)、pagination(page/pageSize)、sort(sortField 白名单同上,默认 updated_at DESC)。", "代码变更:app/service/systems/wechat.js#userList(findAndCountAll,attributes 排除 session_key/refresh_token/access_token/expire_in/expire_time/login_code 敏感字段,raw+is_bound);app/service/systemMethods/wechat.js 出口 + where 字段白名单过滤 + _noNeedRight/_noNeedLog/_noNeedAuth 白名单加入 userList。", "无数据库变更(纯只读查询)。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.queryauth-fix", "date": "2026-09-22", "type": "updated", "summary": "修复 wechat.queryauth:接口路径改为 wxa/sec/queryauth 并新增必填入参 taskid,响应改为 task_status/apply_status", "methods": [ "wechat.queryauth" ], "notes": [ "根因:此前实现误用 /wxa/sec/wxaapi/queryauth 且未传 taskid,微信返回 40066 invalid url;官方接口为 POST /wxa/sec/queryauth?access_token=authorizer_access_token,请求体必填 taskid(发起认证接口 wxa/sec/wxaapi/wxaauth 返回)。", "修复:lib#queryMiniProgramAuth 改路径并传 { taskid },40001/40014 清 authorizer token 重试;systems#queryauth 新增 taskid 必填校验,响应返回 task_status/apply_status/orderid/auth_url 等并附中文文案;文档 system.json queryauth 条目同步更新。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.submitAudit", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.submitAudit(需登录):提交代码审核,wms_wechat_app 新增审核状态字段(开发+生产已迁移)", "methods": [ "wechat.submitAudit" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.submitAudit(isNeedLogin=true、isNeedAuth=false、Authorization 头):入参白名单 item_list/feedback_info/feedback_stuff/preview_info/version_desc/privacy_api_not_use/order_info/ugc_declare;校验权限集 18;仅 audit_status!=1 时允许提交;POST wxa/submit_audit(authorizer_access_token,40001/40014 清缓存重试)成功后回写 audit_status=1、audit_id。", "数据库:迁移 20260922170000-add-audit-fields-to-wms-wechat-app.js(user_version/audit_status/audit_id/audit_reason),开发与生产均已执行;commit 同步回写 user_version;审核结果事件 weapp_audit_success→audit_status=2、weapp_audit_fail→audit_status=3+audit_reason(按 ToUserName=user_name 定位)。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.getTrialQRCode", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.getTrialQRCode(需登录):获取体验版二维码(转存 COS 返回 URL)", "methods": [ "wechat.getTrialQRCode" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.getTrialQRCode(isNeedLogin=true、isNeedAuth=false、Authorization 头):入参 path(可选);按 ctx.user.store_id 取仓库启用小程序,hasFuncScope 校验权限集 18 或 86;GET wxa/get_qrcode(authorizer_access_token,path 自动 urlencode,40001/40014 清 authorizer token 缓存重试)返回 jpeg 图片,经 upload.uploadBuffer 转存 COS(key=qrcode/wechat/{warehouseId}/{yyyymmdd}/{ts}{rand}.jpg)后返回 URL。", "代码变更:app/lib/wechat_open_client.js#getTrialQRCode;app/service/systems/wechat.js#getTrialQRCode/#buildTrialQrCodeKey;app/service/systemMethods/wechat.js 出口 + _noNeedRight/_noNeedAuth 白名单。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.commit", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.commit(需登录):上传代码并生成体验版,wms_wechat_app 新增 template_id 字段(开发+生产已迁移)", "methods": [ "wechat.commit" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.commit(isNeedLogin=true、isNeedAuth=false、Authorization 头):入参 template_id/ext_json/user_version(≤64)/user_desc;按 ctx.user.store_id 取仓库启用小程序,hasFuncScope(func_info, 18) 校验代码管理权限集,getTemplateList(0) 校验模板存在(微信 85014 兜底),POST wxa/commit(authorizer_access_token,40001/40014 清 authorizer token 缓存重试)成功后回写 wms_wechat_app.template_id。", "数据库:迁移 20260922160000-add-template-id-to-wms-wechat-app.js(wms_wechat_app.template_id bigint unsigned nullable),已在开发(127.0.0.1:3307)与生产(112.124.21.102)执行并验证;app/model/wechat_app.js 同步 template_id 字段。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.getTemplateList", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.getTemplateList(需登录):获取普通模板库列表,Redis 缓存 24h", "methods": [ "wechat.getTemplateList" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.getTemplateList(isNeedLogin=true、isNeedAuth=false、Authorization 头):只拉普通模板(template_type=0,GET wxa/gettemplatelist + component_access_token,40001 自愈);Redis key wechat:template:list:normal 缓存 24h,有缓存直接返回(from_cache=true),无缓存拉取后写缓存。", "代码变更:app/lib/wechat_open_client.js#getTemplateList(GET 请求封装);app/service/systems/wechat.js#getTemplateList;app/service/systemMethods/wechat.js 出口 + _noNeedRight/_noNeedAuth 白名单。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.getMyLoginCode", "date": "2026-09-22", "type": "added", "summary": "新增 wechat.getMyLoginCode:获取当前微信登录用户的登录码(至少微信登录),无则生成写入、有则直接返回", "methods": [ "wechat.getMyLoginCode" ], "notes": [ "systemMethods/wechat.js 白名单:_noNeedBind 新增 getMyLoginCode(微信登录态中间层,未绑定真实用户也可访问,业务层校验 ctx.oauth);systems/wechat.js 新增 getMyLoginCode:ctx.oauth 定位 wms_user_oauth,login_code 为空时 buildLoginCode(id) 生成(uuid={id}_{6位随机}、form=wechat 的 JSON base64)并回写,已有直接返回;system.json 微信模块新增该 method" ], "module": "wechat" }, { "version": "2026.09.22-wechat.uploadHeadimg", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.uploadHeadimg(微信登录态中间层):上传裁剪后的 PNG 头像(<500K)并回写 headimgurl", "methods": [ "wechat.uploadHeadimg" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.uploadHeadimg(中间层鉴权,至少微信登录即可,未绑定也可):入参 image(PNG base64,支持 data URL 前缀);校验大小 <500K 与 PNG 文件头魔数后经 upload.uploadBuffer 上传 COS(key=headimg/wechat/{yyyymmdd}/{timestamp}{random}.png,不依赖仓库上下文),回写 wms_user_oauth.headimgurl 并返回 URL。", "代码变更:app/service/systems/upload.js#uploadBuffer(Buffer 直传 COS);app/service/systems/wechat.js#uploadHeadimg/#buildHeadimgKey;app/service/systemMethods/wechat.js 出口 + _noNeedBind 白名单。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.updateInfo", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.updateInfo(微信登录态中间层):未绑定用户更新自己的昵称/头像", "methods": [ "wechat.updateInfo" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.updateInfo(中间层鉴权,需有效微信登录态 token):仅未绑定真实用户(wms_user_oauth.user_id=0)可更新 nickname(≤255)/headimgurl(≤500),可部分更新,至少一个字段;已绑定账号返回「账号已绑定,不支持修改微信资料」。", "代码变更:app/service/systems/wechat.js#updateInfo;app/service/systemMethods/wechat.js 出口 + _noNeedBind 白名单加入 updateInfo。" ], "module": "wechat" }, { "version": "2026.09.22-user.info-wechat-appId-filter", "date": "2026-09-22", "type": "updated", "summary": "user.info 新增可选入参 wechat_appId:传入时按小程序归属仓库过滤工号列表(仅保留非仓库工号(货主)+ 该仓库工号)", "methods": [ "user.info" ], "notes": [ "user.info 新增可选入参 wechat_appId:按 wms_wechat_app.appid(is_enabled=1)反查归属 warehouse_id,有仓库时过滤返回的 user.employees —— 保留 role_type!=warehouse(货主工号)或 store_id=该仓库 的工号;未传或查不到仓库保持原逻辑。", "代码变更:app/service/systems/auth/user.js#info 增加 data.wechat_appId 处理(method 层 user.info 已透传 data)。" ], "module": "user" }, { "version": "2026.09.22-wechat.registerMiniprogram", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.registerMiniprogram(需登录):快速注册企业小程序", "methods": [ "wechat.registerMiniprogram" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.registerMiniprogram(isNeedLogin=true、isNeedAuth=false、Authorization 头):入参 name/code/code_type/legal_persona_wechat/legal_persona_name(必填)+ component_phone(选填),校验后调微信 fastregisterweapp?action=create(component_access_token,40001 自愈重试);注册任务创建后法人微信收到模板消息做人脸核身,审核结果通过 notify_third_fasteregister 事件推送到授权事件接收 URL(后续需在 handleEvent 中处理该事件绑定仓库)。", "代码变更:app/lib/wechat_open_client.js#fastRegisterWeapp(create/search 通用封装 + 40001 自愈);app/service/systems/wechat.js#registerMiniprogram;app/service/systemMethods/wechat.js 出口 + _noNeedRight/_noNeedAuth 白名单。" ], "module": "wechat" }, { "version": "2026.09.22-wechat.queryauth", "date": "2026-09-22", "type": "added", "summary": "新增微信模块 wechat.queryauth(需登录):查询当前仓库小程序的认证状态", "methods": [ "wechat.queryauth" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.queryauth(isNeedLogin=true、isNeedAuth=false、Authorization 头):按 ctx.user.store_id 取仓库启用小程序(wms_wechat_app,is_enabled=1,id ASC 取第一条),用 authorizer_access_token 调微信 wxa/sec/wxaapi/queryauth 返回 auth_state(0 未认证/1 认证中/2 认证通过/3 认证失败)并附 auth_state_text 中文文案。", "代码变更:app/lib/wechat_open_client.js#queryMiniProgramAuth(authorizer_access_token 调 wxa/sec/wxaapi/queryauth,支持 DB 落库的 authorizer_refresh_token 兜底 Redis 丢失);app/service/systems/wechat.js#queryauth;app/service/systemMethods/wechat.js 出口 + _noNeedRight/_noNeedAuth 白名单加入 queryauth。" ], "module": "wechat" }, { "version": "2026.09.21-wechat.pushLoginCode-legacy-code", "date": "2026-09-21", "type": "updated", "summary": "弃用 wechat.getLoginWechatCode,wechat.pushLoginCode 改为复用旧 user.getLoginWechatCode 生成的登录码", "methods": [ "wechat.pushLoginCode" ], "notes": [ "弃用新增的 wechat.getLoginWechatCode(移除 systems/method 层与文档);小程序端继续使用旧 user.getLoginWechatCode 生成/轮询 6 位字母+数字登录码(user:wechat:login:code:* / client key,TTL 60s)。", "wechat.pushLoginCode(需登录免权限)改造:读旧码缓存(getWechatLoginCodeCacheKey)取 client_code,经 findYe4sBindingByAccountId 反查当前账号 ye4s_user,将 ye4s_user_id 双写旧登录码缓存(code key + client key,TTL 按剩余有效期),旧轮询方读到 ye4s_user_id 即走 loginByYe4sUserId 直登返回正常 WMS token。" ], "module": "wechat" }, { "version": "2026.09.21-wechat.loginCode-flow", "date": "2026-09-21", "type": "added", "summary": "新增微信模块 wechat.getLoginWechatCode / wechat.pushLoginCode:小程序端生成 6 位登录码轮询,PC 已登录用户确认后小程序端返回登录成功并绑定账号", "methods": [ "wechat.getLoginWechatCode", "wechat.pushLoginCode" ], "notes": [ "getLoginWechatCode(微信登录态中间层 _noNeedBind):不传 code 生成 6 位数字登录码写 Redis(key wechat:login:code:{code},TTL 300s,记录 oauth_id);传 code 轮询状态 pending/expired/success;success 时校验归属 oauth_id、一次性消费登录码、绑定 wms_user_oauth.user_id=确认账号(防换绑)并签发登录 token(id=账号ID、oauth_id 保留)。", "pushLoginCode(需登录、免权限):PC/Web 已登录用户传 code,将对应缓存态置 success 并写入 account_id(TTL 120s 等待小程序领取);登录码归属校验防止他人码窃取登录。", "代码变更:app/service/systems/wechat.js#getLoginWechatCode/#pushLoginCode/#createLoginCode/#getLoginCodeCacheKey、app/service/systemMethods/wechat.js(出口 + _noNeedBind 白名单 + _noNeedRight 加入 pushLoginCode)。" ], "module": "wechat" }, { "version": "2026.09.21-wechat.loginByCode-appid-string", "date": "2026-09-21", "type": "updated", "summary": "wechat.loginByCode 应用标识兼容字符串 appid:新增 appid(微信 AppID 字符串)入参按 uk_appid 反查,app_id(整数主键)保留向后兼容", "methods": [ "wechat.loginByCode" ], "notes": [ "微信 AppID 是字符串(如 wx6e91ec813bcb7eec),小程序端应传 appid 字符串(模板小程序运行时取 wx.getAccountInfoSync().miniProgram.appId)而非数据库主键。", "代码变更:app/service/systems/wechat.js 新增 resolveWechatApp(优先 app_id 主键,其次 appid 按 uk_appid 反查并过滤 is_enabled=1);loginByCode 经 resolveWechatApp 解析应用记录,wms_user_oauth.app_id 仍存 wms_wechat_app.id(整数外键)。文档 system.json loginByCode 入参补充 appid 字段说明。" ], "module": "wechat" }, { "version": "2026.09.21-user.info-oauth-middle", "date": "2026-09-21", "type": "updated", "summary": "user.info 支持微信登录态中间层:微信登录未绑定时返回微信层信息(is_bound=false),不 401", "methods": [ "user.info" ], "notes": [ "systemMethods/user.js 构造器新增 _noNeedBind='info'(systemInit 第 5 参),微信登录态 token 可调用 user.info;auth.user.info 增加分支:未绑定真实用户(ctx.oauth 存在且无 ctx.user)时返回微信层信息(id=0/is_bound=false/oauth_id/openid/unionid/nickname/headimgurl/login_time/login_count,code 200),不 401;绑定/正常登录仍返回 findById 完整信息。", "代码变更:app/service/systems/auth/user.js#info、app/service/systemMethods/user.js;撤销前版 wechat.getUserInfo(用户要求 getUserInfo 为公用接口,不收在 wechat 模块)。" ], "module": "user" }, { "version": "2026.09.21-wechat.bindUser", "date": "2026-09-21", "type": "added", "summary": "新增微信模块 wechat.bindUser(微信登录态中间层):用户名密码一致则绑定 wms_user_oauth.user_id 并签发绑定后的新 token", "methods": [ "wechat.bindUser" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.bindUser(中间层鉴权:需有效微信登录态 token,未绑定真实用户也可调用):入参 username(用户名/手机号/邮箱)+ password;复用 auth.user 的 findUserByIdentifier/checkUserStatus/verifyPassword 校验;一致则 wms_user_oauth.user_id 绑定账号并签发新 token(payload id=账号ID、oauth_id 保留);已绑定时仅允许本人凭据幂等调用,不允许换绑。", "鉴权机制:app/service/main.js checkAuth 新增中间层白名单 _noNeedBind(systemInit 第 5 参),oauth token 有效即通过(user_id=0 也可),ctx.oauth/ctx.oauthId 注入微信身份,不查 API 权限;代码变更:app/service/systemMethods/wechat.js(bindUser 出口 + _noNeedBind 白名单)、app/service/systems/wechat.js#bindUser/#buildBindResult。" ], "module": "wechat" }, { "version": "2026.09.21-wechat.loginByCode", "date": "2026-09-21", "type": "added", "summary": "新增微信模块 wechat.loginByCode(免登录):小程序 wx.login code 换 openid/session_key 并查/建 wms_user_oauth,返回 token+user", "methods": [ "wechat.loginByCode" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.loginByCode(免登录 isNeedLogin=false):入参 code(wx.login 获取)+ app_id(wms_wechat_app.id);jscode2session(GET /sns/component/jscode2session)换 openid/session_key/unionid;wms_user_oauth 有记录则刷新 login_time/login_count/session_key,无记录则创建且 user_id=0(未绑定);JWT payload 记录 oauth_id(wms_user_oauth.id),区别于正常登录的用户 id 字段。", "代码变更:app/lib/wechat_open_client.js#jscode2session(GET 请求封装);app/service/systems/wechat.js#loginByCode;app/service/systemMethods/wechat.js 免登录白名单加入 loginByCode。" ], "module": "wechat" }, { "version": "2026.09.21-workbench.packOrder-business-users-restore", "date": "2026-09-21", "type": "updated", "summary": "workbench.business 的 packOrder 分支恢复支持传入 users 上报打包人(未上报时回填工作台成员);token+key 新链路保持剥离 users", "methods": [ "workbench.business" ], "notes": [ "业务旧链路(workbench.business 的 packOrder 分支)恢复 users 上报生效:上报时以上报为准,未上报时自动回填该工作台绑定成员(wms_workbench_member);token+key 新链路(workbench.packOrder)保持剥离 users、一律取工作台绑定成员。", "代码变更:app/service/systems/workbench.js#_packOrder 恢复 users 入参(上报优先、未报回填)、#packOrderByToken 解构剥离 users;回归测试 test/workbench_pack_waybill_dimension.test.cjs(26 用例)。" ], "module": "workbench" }, { "version": "2026.09.21-wechat.getAuthUrl", "date": "2026-09-21", "type": "added", "summary": "新增微信模块 wechat.getAuthUrl:生成微信开放平台小程序授权链接(PC版),state 缓存仓库信息用于回跳绑定", "methods": [ "wechat.getAuthUrl" ], "notes": [ "system.json 新增 module=wechat 方法 wechat.getAuthUrl(需登录);app/service/systems/wechat.js + app/service/systemMethods/wechat.js 生成授权链接;state=随机串,缓存 key wechat_auth_state:{state}(TTL 600s)存仓库信息;GET /Authorization 回跳凭 state 绑定仓库并落库 wms_wechat_app;state 缺失/过期展示错误页 app/view/wechat_auth_callback.html;配置 wechatOpen.redirect_uri" ], "module": "wechat" }, { "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", "type": "updated", "summary": "打包链路(workbench.packOrder / workbench.finishPack)回写打包状态时同步补确认打印状态:扫描打包即视为面单已真实存在,confirm_print_status 未写入(none/null)时补 fin,团购按波次、散单按单,拦截订单跳过,并递增统计版本号驱动确认打印未领单长轮询。", "methods": [ "workbench.packOrder", "workbench.finishPack" ], "notes": [ "实现入口:systems/workbench.js _updateOrderPackStatus(覆盖开始打包/完成打包/关闭旧任务全部路径)", "幂等:仅 confirm_print_status 为 none/null 时补 fin" ] }, { "version": "2026.09.20-wave-confirmPrintScan-need-right", "date": "2026-09-20", "type": "updated", "summary": "order.wave.confirmPrintScan 改为需要接口权限(isNeedAuth=true),从免权限名单移除;confirmPrintUnclaimedWaveCount 保持免权限。", "methods": [ "order.wave.confirmPrintScan" ], "notes": [ "运行时:wave.js _noNeedRight/_noNeedAuth 已移除 confirmPrintScan,checkAuth 走 checkApiPermission", "权限记录由 permission:sync:system-api 从 system.json isNeedAuth=true 接口同步并授权角色 2" ] }, { "version": "2026.09.20-pendingOrder-list-confirm-print-claim-fields", "date": "2026-09-20", "type": "updated", "summary": "order.pendingOrder.list 文档补充 confirm_print_status(确认打印)与 claim_status(领料)的 where 筛选说明与响应字段说明(功能已支持,本次仅同步文档)。", "methods": [ "order.pendingOrder.list" ], "notes": [ "列表输出 ORDER_LIST_BASE_ATTRIBUTES 已包含 confirm_print_status/claim_status;where 无字段白名单,两列可直接透传筛选" ] }, { "version": "2026.09.20-wave-batchList-claim-status", "date": "2026-09-20", "type": "updated", "summary": "order.wave.batchList 波次列表新增 claim_assignment_status 领料状态显示(含 claim_time/claim_operator)与 where.claim_assignment_status 筛选(波次表 claim_time 口径)。", "methods": [ "order.wave.batchList" ], "notes": [ "领料状态以波次表 wms_wave_batch.claim_time 是否为空判定(二态:未领料/已领料),与 confirmPrintUnclaimedWaveCount 口径一致", "where 新增 claim_assignment_status 筛选字段(仅 eq,unclaimed/claimed,兼容中文)" ] }, { "version": "2026.09.20-wave-confirm-print-count-fix", "date": "2026-09-20", "type": "updated", "summary": "order.wave.confirmPrintUnclaimedWaveCount 统计口径修正:未领单由订单维度 claim_status 改为波次表维度 wms_wave_batch.claim_time IS NULL,避免历史领单(波次表加 claim_time 字段前)导致少算。", "methods": [ "order.wave.confirmPrintUnclaimedWaveCount" ], "notes": [ "根因:B2026081500088/89 等波次订单 claim_status='fin'(历史领单)但 wave_batch.claim_time=null,订单维度口径误判为已领单导致 count 少算", "新口径:wave_batch(wave_status 0/1、claim_time IS NULL)+ 波次下存在 confirm_print_status='fin' 的非取消订单" ] }, { "version": "2026.09.20-wave-confirm-print-scan-count", "date": "2026-09-20", "type": "added", "summary": "order.wave 新增两个接口:confirmPrintScan(扫面单批量确认打印并写日志,与领单操作一致)与 confirmPrintUnclaimedWaveCount(快速查询已确认打印但未领单波次数量,支持 60s 长轮询,由确认打印/领单版本号驱动)。", "methods": [ "order.wave.confirmPrintScan", "order.wave.confirmPrintUnclaimedWaveCount" ], "notes": [ "confirmPrintScan 复用 print.confirmWavePrint 实现(同入参同返回)", "confirmPrintUnclaimedWaveCount 长轮询:1s 间隔轮询 Redis 版本号(wave:confirm-print:unclaimed:version:{warehouseId}),60s 超时;Redis 不可用时降级为轮询 DB count", "确认打印(print.confirmWavePrint)与领单(pick.waveClaimScan)成功后均递增统计版本号" ] }, { "version": "2026.09.20-wave-batchList-confirm-print", "date": "2026-09-20", "type": "updated", "summary": "order.wave.batchList 波次列表新增 confirm_print_assignment_status 显示与筛选(确认打印状态:未确认打印/部分确认打印/已确认打印)。", "methods": [ "order.wave.batchList" ], "notes": [ "where 新增 confirm_print_assignment_status 筛选字段(仅 eq,英文枚举 unconfirmed/partially_confirmed/confirmed)", "list 每条新增 confirm_print_assignment_status 汇总状态字段" ] }, { "version": "2026.09.20-confirm-wave-print", "date": "2026-09-20", "type": "added", "summary": "订单表新增 confirm_print_status(确认打印状态)字段,并新增 print.confirmWavePrint 波次确认打印接口:打印完成后扫描波次内任一订单面单,批量确认波次下已打印订单。", "methods": [ "print.confirmWavePrint" ], "notes": [ "订单表 wms_order_delivery 及全部分表新增 confirm_print_status ENUM('none','fin'),默认 none;迁移 20260920100000-add-confirm-print-status-to-order-delivery", "波次下存在未打印订单(print_status != 'fin',拦截订单除外)时阻断确认", "拦截订单跳过(不确认、不阻断);全部已确认时重复扫描返回 already_confirmed" ] }, { "version": "2026.09.19-workbench-packOrder-server-side-verification", "date": "2026-09-19", "type": "enhance", "summary": "workbench.packOrder 落库数量改为服务端复查:打包数量/商品总件数/商品种类数不再取设备端上报值,散单取订单分表(orderRow),团购取波次实时统计(totalOrders + 波次商品 SKU 聚合 _fetchWaveItemsSummary),设备端 wave_total_orders/items_count/items_total 仅作交叉校验日志;修复团购波次打包数量落 0/1 的失真问题。", "methods": [ "workbench.packOrder" ], "notes": [ "代码:app/service/systems/workbench.js _packOrder 步骤6 改为服务端复查口径:packQuantity 散单固定 1、团购取 totalOrders(>0 否则 1);packItemQuantity/packSkuCount 散单取 orderRow.items_total/items_count(注:分表列名为 items_count 而非 item_count,此前兜底读 item_count 导致散单 sku_count 兜底落 0,已一并修正),团购取 _fetchWaveItemsSummary(15s 短缓存)聚合 rows.length 与 plan_qty 求和,聚合失败降级为扫描订单值", "交叉校验:设备端上报值与服务端不一致时仅 ctx.logger.info 告警(打包数量/商品总件数/商品种类数三组),落库始终以服务端为准", "开发库数据回填:temp/fix-dev-pack-task-quantities.cjs 已按新口径重算 wms_pack_task 存量 30 条并更新 19 条(保留 update_time、不删行;散单/团购各自取服务端口径,旧 6 月订单缺失的 6 条跳过)", "背景:原语义 pack_quantity=wave_total_orders(缺省 1、传 0 落 0),服务端实时波次订单数未回写,导致列表/统计口径失真", "methods/system.json:workbench.packOrder 参数 wave_total_orders/items_count/items_total 描述同步服务端复查口径;版本 0.3.140 -> 0.3.141(docMeta.version),updatedAt 保持 2026-09-19" ] }, { "version": "2026.09.19-workbench-getWorkbenchCount-avg-piece-count", "date": "2026-09-19", "type": "enhance", "summary": "workbench.getWorkbenchCount 个人工作台返回调整:新增 group_order_count(团购订单数量,团购任务 pack_quantity 求和,个人/团体工作台均返回);均件数 avg_piece_count 口径改为本人打包任务按 订单数量/人数 折算求和(本人作为打包人参与的任务按任务实际打包人数均分、缺省 1,本工作台单人任务整单计入),不再只统计打包人数≥2 的任务,单人打包 500 单波次可正确得到 500。", "methods": [ "workbench.getWorkbenchCount" ], "notes": [ "代码:app/service/systems/workbench.js getWorkbenchCountByToken 个人分支:新增 groupOrderCount(groupTasks 对 pack_quantity 求和);均件数循环改为 participatedTaskIds 按 packerCount(缺省 1)均分、workbenchTaskIds 未记本人时整单计入", "methods/system.json:getWorkbenchCount response 更新 avg_piece_count/group_order_count 描述;版本 0.3.141 -> 0.3.142(docMeta.version),updatedAt 保持 2026-09-19" ] }, { "version": "2026.09.19-workbench-getWorkbenchCount", "date": "2026-09-19", "type": "enhance", "summary": "新增 workbench.getWorkbenchCount 当前工作台班次打包统计(免登录/免权限/免鉴权,以工作台 token 鉴权):统计窗口为本地时间当日 08:00 至次日 08:00,早于 08:00 时为昨日 08:00 至今日 08:00;个人工作台(type=personal)统计涉及本人(工作台成员 user_id)的打包数据,返回团购波次数量/散单数量/团散(团购波次数/散单数 2 位小数)/均件数(多人打包任务按 订单数量/人数 折算求和 2 位小数);团体工作台(type=group)返回团购波次数量/团购订单数量(pack_quantity 快照求和)/散单数量。", "methods": [ "workbench.getWorkbenchCount" ], "notes": [ "代码:app/service/systems/workbench.js 新增 getWorkbenchCountByToken(resolveWorkbenchContext 统一 token 校验,无 token 401/无效 403)与辅助方法 buildWorkbenchPackCountTimeRange(8 点班次窗口)/ _round2 / _formatPackCountTime", "个人统计:窗口内本仓库任务走 idx_warehouse_create_time;本人参与任务通过 wms_pack_task_packer(account_id=成员 user_id,分批 IN 500)与 uix_pack_task_account 索引判定;统计范围 = 本工作台任务 ∪ 本人作为打包人参与的任务;均件数只折算本人参与的多人打包(打包人数≥2)任务", "团体统计:workbench_id+create_time 走新增 idx_workbench_create_time 索引", "索引:数据库迁移 20260919100000-add-workbench-create-time-index-to-wms-pack-task.js 为 wms_pack_task 新增 (workbench_id, create_time) 复合索引,避免窗口统计长跨度扫描导致慢 SQL;模型 app/model/pack_task.js indexes 同步补充", "methods/system.json:工作台模块新增 workbench.getWorkbenchCount 条目;版本 0.3.138 -> 0.3.139(docMeta.version),updatedAt 保持 2026-09-19" ] }, { "version": "2026.09.19-wave-batchList-sync-assignment-status", "date": "2026-09-19", "type": "enhance", "summary": "order.wave.batchList 响应新增 sync_assignment_status(同步状态,取值:未同步/部分同步/已同步/同步异常),并支持 where.sync_assignment_status 筛选(英文枚举 unsynced/partially_synced/synced,仅 eq,error 并入未同步集合)。", "methods": [ "order.wave.batchList" ], "notes": [ "代码:app/service/systemMethods/order/wave.js BATCH_LIST_ASSIGNMENT_FILTER_SCHEMAS 新增 sync 类型(fieldName=sync_assignment_status,enumMap unsynced/partially_synced/synced → none/partial/finished,caseInsensitive=true,statsColumnPrefix=sync,withErrorStatus=true)", "聚合:wave_order_stats 子查询新增 sync_none_count/sync_fin_count/sync_error_count,按订单 sync_status(padding/fin/error)聚合;none 口径为 sync_status IS NULL 或 NOT IN ('fin','error'),与 review 统计口径一致", "输出:list[].sync_assignment_status 复用 resolveAssignmentStatus,error 优先判定为同步异常,labels 为未同步/部分同步/已同步/同步异常", "筛选:buildBatchListWhereClause allowedFields 新增 sync_assignment_status,仅支持 eq;normalizeBatchListSyncAssignmentStatusFilter/buildBatchListSyncAssignmentFilterClause 复用通用 schema 链路", "methods/system.json:batchList description/where/response 同步 sync_assignment_status 说明;版本 0.3.137 -> 0.3.138(docMeta.version),updatedAt 保持 2026-09-19" ] }, { "version": "2026.09.19-workbench-getWorkbenchInfo-wave-items-summary", "date": "2026-09-19", "type": "enhance", "summary": "workbench.getWorkbenchInfo 团购任务(pack_mode=2)current_orders items 由空数组改为波次商品 SKU 聚合汇总,彻底解决工作台退出/刷新后团购打包任务无商品信息的问题:新增 _aggregateWaveItems(波次内全部未拦截订单(current+dispatch 分表)商品明细按 SKU 聚合计划数量并合并 stock 详情,聚合行另附 is_wave_summary=true)与 _fetchWaveItemsSummary(按 warehouseId+waveId 维度 15s 短缓存兜底,与 order_count/items_total 同款缓存模式),buildCurrentPackingInfo 团购任务分支调用;散单任务 items 口径不变。", "methods": [ "workbench.getWorkbenchInfo" ], "notes": [ "代码:app/service/systems/workbench.js 新增常量 WAVE_ITEMS_SUMMARY_CACHE_KEY_PREFIX/WAVE_ITEMS_SUMMARY_CACHE_TTL_SECONDS(15s);_aggregateWaveItems 聚合键 stock_id 优先、缺省按 item_code+item_name,stock 详情走 stockWarehouse.getStockDetails 通用缓存链路,异常降级空数组;buildCurrentPackingInfo 团购任务(wave_id>0)调用 _fetchWaveItemsSummary 填 items", "结构:聚合行与散单 items 结构同源(id/order_id 置 0、order_line_no 空串、actual_price null、plan_qty 为波次内该 SKU 合计),另附 is_wave_summary=true 供前端区分单笔明细与波次汇总", "性能:15s 短缓存保证 TTL 内重复查询零开销;缓存未命中时波次订单 ID 查询走 wave_id 索引、items 按 order_id IN 查询走索引,500 单规模波次一次聚合可接受;packOrder/finishPack 后 token 缓存失效,波次聚合缓存在 TTL 内可能与最新波次状态有最多 15s 滞后(与 order_count/items_total 同口径)", "methods/system.json:workbench.getWorkbenchInfo description 与 current_orders[].items/items[].id/items[].order_id/items[].plan_qty 描述更新为双口径,response 新增 current_orders[].items[].is_wave_summary 条目;版本 0.3.136 -> 0.3.137(docMeta.version),updatedAt 保持 2026-09-19" ] }, { "version": "2026.09.19-workbench-order-items-need-recheck", "date": "2026-09-19", "type": "updated", "summary": "workbench.queryOrder 与 workbench.getWorkbenchInfo 响应商品明细 items 新增 need_recheck 字段(Y=需要复核,N=不需要复核(免验),缺省 Y):组装链路 _fetchOrderItemsDetail 从 stock 详情(getStockDetails 通用缓存链路,其 attributes 已含 need_recheck)透出,补齐工作台打包端商品列表缺少免验标识的问题。", "methods": [ "workbench.queryOrder", "workbench.getWorkbenchInfo" ], "notes": [ "代码:app/service/systems/workbench.js _fetchOrderItemsDetail items 组装新增 need_recheck: String(stock.need_recheck || 'Y').trim()(与 order.recheckOrder.scanOrder/scanTask 同口径,getStockDetails 旧缓存无该字段时兜底 Y)", "workbench.queryOrder 与 workbench.getWorkbenchInfo(current_orders[].items)共用 _fetchOrderItemsDetail,两接口 items 同步生效", "methods/system.json:workbench.queryOrder description 补充 need_recheck 说明,response 新增 items[].need_recheck 条目;workbench.getWorkbenchInfo description 补充「是否需要复核 need_recheck」,response 新增 current_orders[].items[].need_recheck 条目,并将 current_orders[].items[].image_url 类型由 string 修正为 array(实际返回数组);版本 0.3.135 -> 0.3.136(docMeta.version),updatedAt 保持 2026-09-19" ] }, { "version": "2026.09.19-workbench-getWorkbenchInfo-order-items", "date": "2026-09-19", "type": "enhance", "summary": "enhance: workbench.getWorkbenchInfo 响应 data.current_orders 补全任务上下文字段,解决工作台退出/刷新后无法恢复任务信息的问题:散单任务(pack_mode=1)新增 items 商品明细数组(wms_order_items 分表按 order_id 查询并合并 stock 详情,含 item_code/item_name/plan_qty/barcodes/image_url/packing_requirements 等,与 workbench.queryOrder 返回结构同源),团购任务(pack_mode=2)波次商品明细量大,items 置空数组、以 current_wave 汇总展示;同时每项新增 wms_pack_task 已有字段 item_quantity/sku_count/waybill_code 与订单分表字段 order_type/store_id/items_count/items_total。", "methods": [ "workbench.getWorkbenchInfo" ], "notes": [ "实现:app/service/systems/workbench.js 从 _queryOrder 步骤4 抽取公共方法 _fetchOrderItemsDetail(orderId, warehouseId, sourceTable)(sourceTable=dispatch 查配送明细分表、其余查 current;stock 详情走 stockWarehouse.getStockDetails 自带缓存;异常降级空数组),_queryOrder 改为复用(响应结构不变);buildCurrentPackingInfo 任务遍历时记录订单所在分表 sourceTable 并多取 order_type/store_id/items_count/items_total 字段,散单任务调用 _fetchOrderItemsDetail 补 items,团购任务 items 置空数组", "口径:items 仅对 pack_mode=1 散单任务查询(团购波次逐单聚合开销大且前端以 current_wave 汇总展示);单笔商品明细查询异常仅该项 items 降级为空数组,不影响主信息与其余字段", "性能:buildCurrentPackingInfo 仅在 token 缓存(workbench:token:{token},TTL 300s)未命中或打包状态变更失效后执行,未结束任务通常单条,items 按 order_id 走索引查询,无新增高频开销", "methods/system.json:workbench.getWorkbenchInfo description 补充散单 items/团购空数组与新增字段说明,response 新增 current_orders[].item_quantity/sku_count/waybill_code/order_type/store_id/items_count/items_total 与 current_orders[].items 及 items[] 下 16 个子字段条目(沿用 current_orders[].xxx 嵌套命名惯例);版本 0.3.134 -> 0.3.135(docMeta.version),updatedAt 2026-09-17 -> 2026-09-19" ] }, { "version": "2026.09.17-inbox-group-template-reply-switch", "date": "2026-09-17", "type": "enhance", "summary": "enhance: inbox.group 系列接口接入模板消息回复开关 templateReplyEnabled/template_reply_enabled(0=关闭(普通文本回复) / 1=开启(模板消息回复)),默认 0,所有群类型均支持且独立于 aiEnabled。update 新增入参(未传不修改),reset 重置为关闭,list 返回字段与 where 筛选支持、quickList 返回字段同步补全。", "methods": [ "inbox.group.update", "inbox.group.reset", "inbox.group.list", "inbox.group.quickList" ], "notes": [ "字段落位:wms_inbox_group.template_reply_enabled(TINYINT(1) NOT NULL DEFAULT 0,迁移 database/migrations/20260917100000-add-template-reply-enabled-to-inbox-group.js,model app/model/inbox_group.js 已同步)", "语义:ai_enabled 控制是否 AI 处理;template_reply_enabled 控制命中处理后是否以模板消息形式回复(0=普通文本回复,1=模板消息回复),两开关相互独立", "update:data.templateReplyEnabled===1 时写 1,否则写 0,未传不修改;reset:清空配置时 template_reply_enabled 重置为 0;方法层 app/service/systemMethods/inbox.js#groupUpdate 透传", "list:attributes 与 where specialFieldMap 新增 template_reply_enabled(可筛选),返回行沿用 snake_case 风格(template_reply_enabled)与 ai_enabled 相邻", "quickList:轻量字段新增 template_reply_enabled,下拉选择可感知模板回信开关", "消费方:app/service/inbox/processor.js#loadGroupConfig 读取 template_reply_enabled,为 1 的群命中处理后走 inbox.v2.rules 可配置引擎(模板消息回复)", "文档版本 0.3.133 -> 0.3.134,updatedAt 2026-09-17" ] }, { "version": "2026.09.16-inbox-push-retry-warehouse-setting", "date": "2026-09-16", "type": "updated", "summary": "仓库设置新增「站内信推送失败自动重发」配置(嵌套结构 subject_config.inbox_push_retry,同「收货未入库提醒」):enabled(flag,默认 0=关闭,需显式开启)、window_minutes(重发时间范围,分钟,1-1440,默认 30)。开启后站内信回信/系统通知推送失败(如桥接离线返回 wx offline / qiwe offline 的 503)由定时任务每 3 分钟自动重发,仅重发失败时间在 window_minutes 内的消息,超出范围不再补发。", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "字段落位:wms_store.subject_config.inbox_push_retry(与 receiving_pending_inbound_notice 同表的嵌套 JSON 配置)", "默认值口径:未配置(或配置缺失/非法结构)时 enabled=false、window_minutes=30,即**默认关闭不重发**,需在仓库设置中显式开启", "代码依据:app/model/store.js#normalizeInboxPushRetry(enabled 走 normalizeBooleanFlag;window_minutes 限 1-1440 整数,越界抛「subject_config.inbox_push_retry.window_minutes 必须是 1-1440 的整数(分钟)」);app/service/systems/setting/warehouse.js#WAREHOUSE_SETTING_FIELDS(key=inbox_push_retry,type=object,item_keys 为 enabled/window_minutes)", "消费方:app/service/inbox/message.js#retryFailedByWarehouse(定时任务 app/schedule/retry_inbox_push.js,每 3 分钟;逐仓读设置 → 仅重发该仓窗口内 push_status=3 的出站消息,单仓单轮上限 config.inbox.pushRetryLimit,默认 20)", "全局应急开关:config.inbox.pushRetryEnabled(默认 true),置 false 后所有仓库都不再自动重发;config.inbox.pushRetryWindowMs 仅在仓库未配置/配置非法时兜底(默认 30 分钟)", "getFieldMeta 为通用结构(list + children,不逐字段枚举),本次未改动其文档", "文档版本 0.3.132 -> 0.3.133,updatedAt 2026-09-16" ] }, { "version": "2026.09.16-after-sale-type-subtype-crud", "date": "2026-09-16", "type": "added", "summary": "售后模块新增售后类型/子类型自定义配置 8 个接口:afterSale.typeList / typeCreate / typeUpdate / typeDelete / subTypeList / subTypeCreate / subTypeUpdate / subTypeDelete。列表返回系统级(warehouse_id=null、is_system=1)+ 当前仓库自定义(is_system=0)合并;创建仅允许仓库自定义;改/删仅命中 id + 当前仓库 + is_system=0;系统级不允许编辑/删除(未命中统一 404);编码仅允许小写字母/数字/下划线(type≤20、sub_type≤50、name≤50)且创建时校验不与系统级重复、同仓库内唯一(409);update 编码不可变;删除不做级联(类型下存在自定义子类型或子类型已被售后单引用时 409 拒绝)。", "methods": [ "afterSale.typeList", "afterSale.typeCreate", "afterSale.typeUpdate", "afterSale.typeDelete", "afterSale.subTypeList", "afterSale.subTypeCreate", "afterSale.subTypeUpdate", "afterSale.subTypeDelete" ], "notes": [ "接口口径:全部挂 afterSale 模块(POST /system?method=afterSale.xxx);方法层 app/service/systemMethods/afterSale.js(typeList/typeCreate/typeUpdate/typeDelete/subTypeList/subTypeCreate/subTypeUpdate/subTypeDelete)→ 业务层 app/service/systems/afterSale.js(getTypeList/createType/updateType/deleteType/getSubTypeList/createSubType/updateSubType/deleteSubType)", "权限口径(afterSale.js#systemInit):8 个方法全部免权限(_noNeedRight)、免仓库有效期校验(_noNeedAuth)、需登录(不在 _noNeedLogin);typeList/subTypeList 免日志(_noNeedLog),其余 6 个写系统日志", "仓库维度隔离:列表按 [warehouse_id IS NULL OR warehouse_id=当前仓库] 合并;创建/改/删均以 ctx.user.store_id 为 warehouseId(无仓库上下文报 400),改/删仅命中 id+warehouse_id+is_system=0", "系统级保护:is_system=1 记录不允许编辑/删除,未命中统一 404「不存在、无权操作或为系统预设类型」", "编码规则:type/sub_type 仅允许 /^[a-z0-9_]+$/(小写字母/数字/下划线);type≤20 字符、sub_type≤50、name≤50;创建时校验编码不与系统级重复、同仓库内唯一(409),MySQL 唯一索引 uk_type_warehouse / uk_type_subtype_warehouse 兜底", "编码不可变:typeUpdate 仅允许 name/is_enabled/sort_order,type 不可改;subTypeUpdate 仅允许 name/is_enabled/sort_order,type 与 sub_type 均不可改", "删除策略(拒绝,不做级联):typeDelete 在该类型下存在当前仓库自定义子类型时拒绝(409);subTypeDelete 在 wms_after_sale 存在该 type/sub_type 引用(deleted_at 为空)时拒绝(409「已被售后单使用」)", "错误码口径:400(参数/编码格式/无仓库上下文)、404(不存在/无权/系统预设)、409(编码重复/存在自定义子类型/已被售后单使用)", "数据模型:wms_after_sale_type / wms_after_sale_sub_type(app/model/after_sale_type.js、after_sale_sub_type.js;迁移 database/migrations/20260916100000-create-wms-after-sale-type-tables.js)", "AI_METHOD_ROUTING.md 新增 5.8 节(8 个方法的 method→文件→函数→登录→鉴权口径速查表)并刷新第 6 节自动清单(systemMethods/afterSale.js 22→30,systems/afterSale.js 29→46)", "文档版本 0.3.131 -> 0.3.132,updatedAt 2026-09-16;写入通过 script/update-api-doc.cjs(先 --dry-run)" ] }, { "version": "2026.09.15-warehouse-pending-receiving-notice-template", "date": "2026-09-15", "type": "updated", "summary": "收货未入库提醒支持自定义通知短语:subject_config.receiving_pending_inbound_notice 新增 notice_template(仓库/客服群短语)与 store_notice_template(货主群短语),支持变量替换({warehouse}/{warehouse_id}/{store}/{store_id}/{count}/{min_hours}/{max_hours}/{date}/{numbers}),消息结构固定为「短语 + 换行 + 明细(一行一条)+ 查看链接」,留空使用默认短语。", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "字段口径:wms_store.subject_config.receiving_pending_inbound_notice.notice_template / store_notice_template,均为 string、最长 500 字符、空值回退默认短语", "默认短语:仓库/客服群「【收货未入库提醒】以下 {count} 个收货单已超过 {min_hours} 小时且不足 {max_hours} 小时,仍未完成入库,请及时跟进:」;货主群「【收货未入库提醒】以下 {count} 个收货单已超过 {min_hours} 小时仍未完成入库,请尽快完成收货入库:」", "可用变量:{warehouse} 仓库名(缺名回退「仓库{id}」)/ {warehouse_id} / {store} 货主名(未绑定为「未绑定货主」)/ {store_id} / {count} 本批单数 / {min_hours} / {max_hours} / {date} 提醒日期 YYYY-MM-DD / {numbers} 本批收货单号(最多 20 个,超出以「等 N 单」结尾);未识别占位符原样保留", "校验:短语超 500 字符报 400「subject_config.receiving_pending_inbound_notice.notice_template 长度不能超过 500 字符」(store_notice_template 同);空串/null 回退默认短语(模型 app/model/store.js#normalizeReceivingPendingInboundNotice)", "消息结构:短语 + \\n + 明细行(一行一条,最多 20 行「序号.单号 货主 数量 创建时间 状态」)+ \\n + 快速查看/详情查看链接;不再在结尾追加句号", "单测:test/app/service/systems/receiving_pending_notice.test.js 新增「短语变量替换 + 明细逐行」「未识别占位符原样保留 + 货主短语缺省回退」两用例(共 11 用例)", "文档版本 0.3.130 -> 0.3.131,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run)" ] }, { "version": "2026.09.15-warehouse-pending-receiving-notice", "date": "2026-09-15", "type": "updated", "summary": "仓库设置(wms_store.subject_config)新增「收货未入库提醒」配置 receiving_pending_inbound_notice:enabled(是否通知收货未入库,flag,默认 0 关闭)/ notice_time(提醒时间 HH:mm,默认 08:30)/ min_hours(超时下限小时,默认 24)/ max_hours(超时上限小时,默认 48,须大于 min_hours)。开启后由定时任务(app/schedule/notice_receiving_pending_inbound.js,每 5 分钟检查、按仓库配置的提醒时间执行,每天一次)扫描超时未完成入库的收货单并通知:绑定货主的通知货主收货群(未配群回退仓库客服群),未绑定货主的通知仓库客服群。setting.warehouse.getSettings 响应与 setting.warehouse.saveSettings 入参补充该字段文档。", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "字段口径:wms_store.subject_config.receiving_pending_inbound_notice = { enabled, notice_time, min_hours, max_hours };默认 { enabled:false, notice_time:\"08:30\", min_hours:24, max_hours:48 }(默认不通知)", "模型默认值与校验:app/model/store.js(DEFAULT_SUBJECT_CONFIG + normalizeReceivingPendingInboundNotice);字段元信息:app/service/systems/setting/warehouse.js(WAREHOUSE_SETTING_FIELDS,type=object)", "校验口径:notice_time 必须为 HH:mm(如 08:30),否则 400「subject_config.receiving_pending_inbound_notice.notice_time 格式必须为 HH:mm(如 08:30)」;min_hours/max_hours 必须为大于 0 的整数,且 min_hours 必须小于 max_hours,否则 400", "定时任务:app/schedule/notice_receiving_pending_inbound.js(interval 5m、单 worker、进程内防重入)→ app/service/systems/receiving_pending_notice.js#execute;命中口径为「创建时间超过 min_hours 且不足 max_hours」且(status=receiving 或 storage_status<>all)、is_deleted=0、status<>cancelled;货主维度聚合成一条消息(每行一个收货单,最多 20 行)", "通知事件:新增事件码 receiving_pending_inbound(app/model/notification_webhook.js 注册),固定群订阅 app/service/systems/notice/index.js#FIXED_GROUP_SUBSCRIPTIONS:store:receiving + fallbackTargets warehouse:customer_service(无货主或货主未配收货群时通知仓库客服群)", "幂等:同一仓库+货主同一自然日只推送一次(Redis 当日锁 receiving_pending_notice:lock:{warehouseId}:{YYYYMMDD},TTL 24h;执行异常释放锁,宽限窗口内下一轮重试),消息 ext_id 含 receiving-pending:{warehouseId}:{storeId}:{YYYYMMDD}", "单测:test/app/service/systems/receiving_pending_notice.test.js(9 用例:开关关闭/未命中提醒时间不执行、超时窗口查询条件、货主群通知、无货主回退、当日只提醒一次、异常释放锁重试、行数截断、非法配置回退默认)", "文档版本 0.3.129 -> 0.3.130,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run)" ] }, { "version": "2026.09.15-camera-ptz-camera-id", "date": "2026-09-15", "type": "updated", "summary": "云台(PTZ)四个接口下发给打印服务时请求体统一携带摄像头ID:camera.ptzControl / camera.ptzStop / camera.ptzPresetGoto / camera.ptzPresetSet 的请求体由 { warehouse_id, rtspUrl, … } 改为 { warehouse_id, cameraId, rtspUrl, … }(cameraId 取 wms_camera.id,数值型;warehouse_id 仍为字符串)。接口入参与响应不变。", "methods": [ "camera.ptzControl", "camera.ptzStop", "camera.ptzPresetGoto", "camera.ptzPresetSet" ], "notes": [ "变更内容:4 个 PTZ 端点(/camera/ptzControl、/camera/ptzStop、/camera/ptzPresetGoto、/camera/ptzPresetSet)的请求体新增 cameraId 字段,值取摄像头记录主键 wms_camera.id(Number() 归一化后以数值下发),便于打印服务侧按摄像头ID定位/校验设备与日志排查", "前端入参不变:cameraId 由 WMS 服务端从查询到的摄像头记录自动带入(前端仍只传 id,无需重复传摄像头ID;也无需传 computerId)", "实现位置:app/lib/ptz_client.js#_send 统一拼接请求体 { warehouse_id: String(warehouseId), cameraId, ...业务字段 },四个入口方法无需各自处理;同时补 camera.id 合法性校验(非正整数报「摄像头ID不合法」)", "请求体口径(warehouse_id 为字符串、cameraId 为数值):ptzControl { warehouse_id, cameraId, rtspUrl, action, speed };ptzStop { warehouse_id, cameraId, rtspUrl, action };ptzPresetGoto { warehouse_id, cameraId, rtspUrl, presetId };ptzPresetSet { warehouse_id, cameraId, rtspUrl, presetId }", "响应不变:仍为 { camera_id, rtsp_url, action, speed | preset_id, print_service_response };错误码不变(400/404/500)", "回归:node run/check-camera-ptz.cjs(68 用例,四个方法的请求体断言均已含 cameraId)全部通过;npx eslint 无告警", "文档版本 0.3.128 -> 0.3.129,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run)", "AI_METHOD_ROUTING.md 5.7 段「下发通道」条目已同步补充 cameraId" ] }, { "version": "2026.09.15-camera-ptz-preset-set", "date": "2026-09-15", "type": "added", "summary": "摄像头模块新增 camera.ptzPresetSet(云台预置点设置):把摄像头当前机位保存为指定预置点,入参 id + presetId(1-256),一次调用即可、无需配对 stop。与既有的 camera.ptzPresetGoto(跳转到预置点)构成「存点 / 跳转」一对,写入载体为打印服务端点 POST {printService.url}/camera/ptzPresetSet,请求体 { warehouse_id, rtspUrl, presetId }。", "methods": [ "camera.ptzPresetSet" ], "notes": [ "接口口径:与 camera.ptzControl / camera.ptzStop / camera.ptzPresetGoto 完全一致 —— 独立端点(不带 computerId)、扁平请求体、warehouse_id 为字符串、rtspUrl 服务端按摄像头记录组装", "入参:id(摄像头ID,必填)、presetId(预置点编号,必填,1-256 整数,字符串数字会被归一化);无 speed / action 参数", "响应:data 为 { camera_id, rtsp_url, preset_id, print_service_response }", "错误码:400(摄像头ID不能为空 / 预置点编号不能为空或不是 1-256 的整数 / 摄像头未配置IP地址)、404(摄像头不存在或无权操作)、500(打印服务调用失败,含 HTTP 非 2xx 与回包 status=fail / success=false)", "权限口径:与 camera.setOsd 一致,camera.js#systemInit 已把 ptzPresetSet 加入 _noNeedRight/_noNeedAuth,_noNeedLog 为 *(不写系统日志)", "代码依据:app/lib/ptz_client.js#PTZ_PATH.PRESET_SET 与 #presetSet(复用 normalizePresetId/_send/buildRtspUrl)、app/service/systems/camera.js#ptzPresetSet(复用 _findCameraForControl/_assertPtzSuccess)、app/service/systemMethods/camera.js#ptzPresetSet", "回归:node run/check-camera-ptz.cjs(67 用例,新增 presetSet 的端点/请求体/归一化/边界/摄像头不存在 6 项断言)全部通过;npx eslint 无告警", "文档版本 0.3.127 -> 0.3.128,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run),新增 method 由脚本追加到「摄像头模块」分组尾部", "AI_METHOD_ROUTING.md 5.7 段表格已补 camera.ptzPresetSet 行,并刷新第 6 节自动清单(systemMethods/camera.js 与 systems/camera.js 方法数 +1)" ] }, { "version": "2026.09.15-camera-ptz-wms-endpoint", "date": "2026-09-15", "type": "updated", "summary": "云台(PTZ)三接口入参口径变更:camera.ptzControl / camera.ptzStop / camera.ptzPresetGoto 去除 computerId(打印电脑ID)参数,改为打印服务独立端点下发 —— POST {printService.url}/camera/ptzControl、/camera/ptzStop、/camera/ptzPresetGoto,请求体 { warehouse_id, rtspUrl, action, speed | presetId },与 camera.setOsd 同风格(独立端点、不带电脑ID、warehouse_id 为字符串)。响应同步去除 computer_id 字段。", "methods": [ "camera.ptzControl", "camera.ptzStop", "camera.ptzPresetGoto" ], "notes": [ "变更原因:与 camera.setOsd 对齐 —— 打印服务按 rtspUrl 定位摄像头,无需电脑房间路由;WMS 服务端也推导不出打印电脑ID(wms_print_computer.id 由打印端 /auth/bind 按「仓库+打印台名称」创建,Web 端登录用户仅有 store_id,wms_workbench 只有 device_ids)", "入参变化:三个接口均删除 computerId(必填);camera.ptzControl 保留 id/action/speed,camera.ptzStop 保留 id/action,camera.ptzPresetGoto 保留 id/presetId", "下发报文变化:由 POST {printService.url}/sendToRoom 信封 { warehouse, computerId, method: 'camera.ptz.control'|'camera.ptz.stop'|'camera.ptz.presetGoto', data } 改为三个独立端点 + 扁平请求体 { warehouse_id, rtspUrl, action, speed | presetId }", "响应变化:data 由 { camera_id, computer_id, rtsp_url, action, speed | preset_id, print_service_response } 改为 { camera_id, rtsp_url, action, speed | preset_id, print_service_response }(删除 computer_id)", "错误码变化:不再返回「打印电脑ID不能为空/不合法」;其余 400(摄像头ID为空、方向不合法、转速越界、预置点越界、摄像头未配置IP)/404/500 口径不变", "同一日已存在本接口首次登记的变更记录 2026.09.15-camera-ptz-control(type=added,尚未发布);script/update-api-doc.cjs 的变更记录仅支持头部插入新记录、不支持原位追加,故按兜底方案新增带 -wms-endpoint 后缀的独立记录", "代码依据:app/lib/ptz_client.js#PTZ_PATH(/camera/ptzControl、/camera/ptzStop、/camera/ptzPresetGoto)+ _send(请求体 warehouse_id 转字符串、字段与 setOSD 对齐)、app/service/systems/camera.js(删除 _normalizeComputerId;_findCameraForControl/_assertPtzSuccess 保留;三方法返回值去掉 computer_id)", "回归:node run/check-camera-ptz.cjs(60 用例,含「请求体不带 computerId」断言)全部通过;npx eslint 无告警", "文档版本 0.3.126 -> 0.3.127,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run)", "AI_METHOD_ROUTING.md 5.7 段已同步(删除 computerId 说明、改为独立端点),并刷新第 6 节自动清单" ] }, { "version": "2026.09.15-camera-ptz-control", "date": "2026-09-15", "type": "added", "summary": "摄像头模块新增云台控制(PTZ)三个接口:camera.ptzControl(按下,按方向持续转动,action 支持 8 个位置 up/down/left/right/upleft/upright/downleft/downright,speed 1-7 默认 4)、camera.ptzStop(松手,action 必须与按下时一致)、camera.ptzPresetGoto(预置点跳转,presetId 1-256,一次调用无需 stop)。服务端按摄像头记录组装 rtspUrl,通过打印服务统一指令信封 POST {printService.url}/sendToRoom 下发 { warehouse, computerId, method, data },computerId 由前端传入。", "methods": [ "camera.ptzControl", "camera.ptzStop", "camera.ptzPresetGoto" ], "notes": [ "接口口径:method 与打印服务一一对应 —— camera.ptzControl -> camera.ptz.control(data: { rtspUrl, action, speed })、camera.ptzStop -> camera.ptz.stop(data: { rtspUrl, action })、camera.ptzPresetGoto -> camera.ptz.presetGoto(data: { rtspUrl, presetId })", "action 枚举(8 个位置,与打印服务约定,写入 params[].action.list,顺序固定):up-上、down-下、left-左、right-右、upleft-左上、upright-右上、downleft-左下、downright-右下;大小写不敏感,服务端转小写后校验,非法值报 400", "参数校验:id 必填;computerId 必填且为正整数;action 必填且属于 8 个方向;speed 可选取 1-7 整数(默认 4);presetId 必填取 1-256 整数(转速/预置点仅约束下发的打印服务指令口径,摄像头端实际生效范围以设备为准)", "rtspUrl 由服务端组装(rtsp://{username}:{password}@{ip}:554/stream{channel_id}),与 camera.setOsd 同口径,前端无需传;摄像头无 ip 时报 400「摄像头未配置IP地址,无法组装RTSP地址」", "权限口径:与 camera.setOsd 一致,camera.js#systemInit 已把 ptzControl/ptzStop/ptzPresetGoto 加入 _noNeedRight/_noNeedAuth,且 _noNeedLog 为 *(PTZ 高频调用不写系统日志)", "响应口径:成功时 data 为 { camera_id, computer_id, rtsp_url, action, speed | preset_id, print_service_response }(print_service_response 为打印服务原始回信,便于前端/排查核对);打印服务 HTTP 非 2xx、或回包 status=fail / success=false 时按 500 抛出并带打印服务 message", "代码依据:app/lib/ptz_client.js(PTZ_METHOD/PTZ_ACTION_LIST/PTZ_ACTIONS + control/stop/presetGoto + buildRtspUrl 与 osd_client 同口径)、app/service/systems/camera.js(_findCameraForControl/_normalizeComputerId/_assertPtzSuccess + ptzControl/ptzStop/ptzPresetGoto)、app/service/systemMethods/camera.js(三个入口方法 + systemInit 免权限声明)", "文档版本 0.3.125 -> 0.3.126,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run),新增 method 由脚本追加到「摄像头模块」分组尾部", "AI_METHOD_ROUTING.md 已同步刷新第 6 节自动清单(app/service/systemMethods/camera.js 由 6 个方法变为 9 个)" ] }, { "version": "2026.09.15-returnUnpack.transferByWaybills-ids", "date": "2026-09-15", "type": "updated", "summary": "returnUnpack.transferByWaybills 入参口径变更:waybill_codes(运单号字符串/数组)改为 ids(运单表主键 wms_order_express.id,单个数值或数组,Number() 归一化 + 过滤非正整数 + 去重,单次上限 200)。系统层改为按 id IN (ids) + warehouse_id 一次批量反查运单,未命中即不存在或非本仓库,记失败「运单不存在」。失败项新增 waybill_id,waybill_code 仅运单命中时有值(否则为 null)。错误码新增 400「运单号为空,无法转入退件登记」与 500「反查运单失败,请稍后重试」。业务规则不变(统一置 is_back='Y'、子单跳过、明细按订单原本明细 1:1 复制、幂等复用非 cancelled 拆包单)。", "methods": [ "returnUnpack.transferByWaybills" ], "notes": [ "本次为入参变更;同日已存在 change 记录 2026.09.15-returnUnpack.transferByWaybills(type=added,接口首次登记,尚未发布/未提交)。script/update-api-doc.cjs 的变更记录结构仅支持新记录插入数组头部、不支持对既有记录原位追加,故本次按兜底方案新增 version 带 -ids 后缀的独立记录(summary 已说明是入参变更)", "代码依据:app/service/systems/return_unpack.js#transferByWaybills({ ids })(Number() 归一化 → 过滤非正整数 → 去重 → 上限 200 → id IN (ids)+warehouse_id 批量反查;failed[] 元素为 { waybill_id, waybill_code: 命中时有值否则 null, reason });app/service/systemMethods/returnUnpack.js#transferByWaybills(data) 取 data.ids 后透传,方法层包装不变", "错误码变化:新增 400「运单号为空,无法转入退件登记」、500「反查运单失败,请稍后重试」;400「waybill_codes 不能为空」改为「ids 不能为空」;其余 400/404/401/403/500 口径不变", "响应结构变化:failed[] 元素由 { waybill_code, reason } 调整为 { waybill_id, waybill_code, reason };success[] 元素由 { waybill_code, unpack_id, unpack_no, reused, detail_count, total_quantity } 调整为含 waybill_id 的 7 字段", "回归:代码已先行修改并跑通 76/76 回归,本次仅同步文档;AI_METHOD_ROUTING.md 方法名与数量不变,无需同步", "文档版本 0.3.124 -> 0.3.125,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" ] }, { "version": "2026.09.15-order-list-default-where-fix", "date": "2026-09-15", "type": "updated", "summary": "修正 order.pendingOrder.list / order.outboundOrder.list 的默认筛选说明,使其与 app/service/systemMethods/order/base.js#MODULE_CONFIGS 实现一致(前者 step in [1,2,3];后者 outbound_status in [fin,padding] 且 step in [4,9])。", "methods": [ "order.pendingOrder.list", "order.outboundOrder.list" ], "notes": [ "实现口径:base.js MODULE_CONFIGS.pendingOrder.defaultWhere = { outbound_status: { operator: \"ne\", value: \"padding\" }, step: { operator: \"in\", value: [1,2,3] } };outboundOrder.defaultWhere = { outbound_status: { operator: \"in\", value: [\"fin\",\"padding\"] }, step: { operator: \"in\", value: [4,9] } };两者 list 均直接 this.listByModule(module, data),无额外覆盖", "原描述偏差:pendingOrder 写 step in [1,2](漏 3);outboundOrder 写 outbound_status in [none,padding] 且 step in [1,2](正确为 outbound_status in [fin,padding] 且 step in [4,9])", "旁证:run/check-order-list-create-channel.cjs 的期望值按 MODULE_CONFIGS 语义独立构造(pendingOrder step in [1,2,3];outboundOrder outbound_status in [fin,padding] + step in [4,9]),45/45 通过", "文档版本 0.3.123 -> 0.3.124,updatedAt 2026-09-15;通过 script/update-api-doc.cjs 写入(先 --dry-run),按分组拆 spec(首个带 change,其余 --doc-only)" ] }, { "version": "2026.09.15-order-list-create-channel-filter", "date": "2026-09-15", "type": "updated", "summary": "订单工作台各订单列表接口(order.list、order.reviewOrder.list、order.pendingOrder.list、order.outboundOrder.list、order.expectionOrder.list、order.entrustOrder.list、order.deliveryOrder.list、order.deliveryExpectionOrder.list、order.archiveOrder.list)的 where 参数补充 create_channel 订单来源渠道查询条件说明与枚举(MANUAL=手工单、API=接口、QM=奇门、STOCKOUT=出库转单),并给出裸值/裸数组/标准 operator 结构写法。", "methods": [ "order.list", "order.reviewOrder.list", "order.pendingOrder.list", "order.outboundOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list", "order.archiveOrder.list" ], "notes": [ "口径来源:9 个列表均走 app/service/systemMethods/order/base.js#listByModule -> buildWhere -> lib/query_condition_parser.js(where 无字段白名单,字段直接透传为订单分表条件),故 create_channel 可作精确/多选/排除筛选", "枚举来源:app/service/systemMethods/order/base.js CREATE_CHANNEL_LABELS(MANUAL 手工单 / API 接口 / QM 奇门 / STOCKOUT 出库转单)、app/service/systems/order_async.js CREATE_CHANNEL_* 常量;列定义见 database/migrations/20260813140000-add-order-delivery-base-table-missing-columns.js(create_channel STRING(20),默认 MANUAL)", "响应口径:base.js#normalizeOrderListItem 会把 create_channel 通过 formatCreateChannelLabel 转成中文标签,故文档中明确「查询传英文枚举、响应回中文标签」", "已核实列存在性(本地库 information_schema):wms_order_delivery_{100000,1000028} 及 _dispatch/_history/_outsourced 分表均含 create_channel 列;本地数据取值分布仅 MANUAL(73715)/QM(1082)/API(18)/STOCKOUT(2)", "不支持的订单类列表(未纳入本次说明):order.recheckOrder.recheckOrderList / queryRecheckOrderSingleList(手写 SQL,仅 keyword/wave_no/recheck_status/pick_status/wave_index/stock_query)、order.packing.list(仅 status/pack_mode/waybill_code/wave_no 等)、order.wave.batchList(wave.js#buildBatchListWhereClause 字段白名单不含 create_channel)", "文档版本 0.3.122 -> 0.3.123,updatedAt 2026-09-15;写入走 script/update-api-doc.cjs(先 --dry-run),首个 spec 带 change,其余 --doc-only" ] }, { "version": "2026.09.15-returnUnpack.transferByWaybills", "date": "2026-09-15", "type": "added", "summary": "新增退回拆包接口 returnUnpack.transferByWaybills(运单批量转入退件登记):waybill_codes 单个字符串或数组批量转入(trim+去重+过滤空值,上限 200),逐单处理、单条失败不阻断;命中运单统一置 wms_order_express.is_back='Y';子单(business_key>1)跳过;幂等复用同仓库同运单号有效拆包单(reused=true,复用单明细为空按订单明细补写);明细按运单关联订单原明细 1:1 复制(items JSON 优先回退明细分表,复用 afterSale._resolveOrderDetail);命中退回收到登记回填 return_received_id;新增权限 568(API:运单批量转入退件登记,授权角色 27/26)。", "methods": [ "returnUnpack.transferByWaybills" ], "notes": [ "方法层:app/service/systemMethods/returnUnpack.js 新增 transferByWaybills(data)(位于 create 之后),统一 this.success('ok', data) 包装,未加入 _noNeedRight/_noNeedLogin/_noNeedLog/_noNeedAuth 免检清单(isNeedAuth=true、isNeedLogin=true)", "系统层:app/service/systems/return_unpack.js 新增 transferByWaybills / _insertMainWithRetry / _transferOneWaybill / _backfillDetailsFromOrder / _countDetails / _resolveReturnReceivedId / _buildTransferDetailRows(共 7 个方法)", "权限:database/migrations/20260915100000-add-return-unpack-transfer-waybills-permission.js 固定 ID 568 path=returnUnpack.transferByWaybills meta_title=API:运单批量转入退件登记,角色授权 27(仓库组-员工)→ 26(仓库组-主管),INSERT IGNORE + 权限数组追加去重排序幂等", "响应错误码:400 参数/上下文/子单跳过/无明细可复制、404 运单不存在、401/403 与其它接口一致、500 服务器内部错误;单运单失败进入 failed[] 不抛错", "AI_METHOD_ROUTING.md 同步:systemMethods/returnUnpack.js 20→21(新增 transferByWaybills)、systems/return_unpack.js 43→50(新增 7 个方法);docs/*.md 无退回拆包接口清单,无需同步", "文档版本 0.3.121 -> 0.3.122,updatedAt 2026-09-15;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" ], "module": "returnUnpack" }, { "version": "2026.09.15-storage-inventory-update-expiry", "date": "2026-09-15", "type": "added", "summary": "新增 storage.inventory.updateExpiry 接口:传入 storage_id 与 production_date / expiry_date,维护当前库存批次的生产日期与到期日期;两个日期至少传一个,未传字段保持原值,传 null/空串清空,合并后生产日期不得晚于到期日期。", "methods": [ "storage.inventory.updateExpiry" ], "notes": [ "app/service/systems/storage/inventory.js 新增 updateExpiry(data):校验 storage_id 为正整数、两个日期格式合法且至少传一个、当前仓库上下文(ctx.user.store_id);单事务 + 行锁(SELECT ... FOR UPDATE)按 id + warehouse_id + is_enabled=1 + delete_at IS NULL 定位库存记录,跨仓库按 404 处理", "app/service/systems/storage/inventory.js 新增模块级 helper parseStorageDateInput:undefined=未传(provided=false)、null/空串=清空、YYYY-MM-DD / YYYY/MM/DD / YYYY-MM-DD HH:mm:ss / ISO / Date 统一规范化为 YYYY-MM-DD(并校验真实存在日期,如 2026-02-30 判非法)、其它非法", "业务校验:合并后(未传字段取库内现值)生产日期不能晚于到期日期,违反返回 400「生产日期(x)不能晚于到期日期(y)」;两值均与库内一致时返回 changed=false,不写库、不记日志", "成功路径写业务操作日志(operationLog.createOperationLog,失败仅告警不影响主流程):business_type=storage、operation_code=STORAGE_UPDATE_EXPIRY、before_changes 含维护前两个日期与 storage/space/stock/batch 快照、message 为「生产日期 A → B;到期日期 C → D」摘要", "app/dict/businessDict.js OPERATION_CODE 新增 STORAGE_UPDATE_EXPIRY: '维护库存效期'", "app/service/systemMethods/storage/inventory.js 新增 updateExpiry 包装方法(this.success('ok', result) 透传 code/message/data),未加入 _noNeedRight/_noNeedAuth 豁免列表:该接口为写操作,需要 API 权限与仓库有效期校验", "权限联动:wms_permission 需新增 path=storage.inventory.updateExpiry 的接口权限并授予相关角色(校验逻辑 app/service/main.js checkApiPermission,路径比较不区分大小写);permissions='*' 的角色无需授权", "响应错误码:400 参数/业务校验失败、404 库存记录不存在或无权访问、409 库存记录被锁定请稍后重试(Lock wait timeout)", "验证:ESLint(npx eslint app/service/systems/storage/inventory.js app/service/systemMethods/storage/inventory.js app/dict/businessDict.js)0 error;parseStorageDateInput 通过临时脚本 temp/verify-update-expiry-date-parse.cjs 逐用例验证(未传/空/清空/多格式/非法日期/Date 对象);未执行任何部署/回退脚本,未改动数据库与 Redis 数据" ], "module": "storage.inventory" }, { "version": "2026.09.15-workbench-pack-osd-reset", "date": "2026-09-15", "type": "updated", "summary": "打包任务结束统一复位工作台摄像头 OSD 为「无任务」:覆盖三条结束路径 —— workbench.finishPack 手动结束、workbench.packOrder 关闭上一个未结束任务(先复位再串行下发新任务 OSD,避免复位覆盖新文字)、packTaskAutoFinish 定时任务自动结束;统一调用 workbench._resetPackOsd 回写 Redis osd_{workbenchId}=无任务 并逐台摄像头下发「无任务」,异常仅告警不阻塞打包主流程。", "methods": [ "workbench.packOrder", "workbench.finishPack" ], "notes": [ "代码:app/service/systems/workbench.js 新增 OSD_IDLE_TEXT/OSD_CACHE_KEY_PREFIX/OSD_CACHE_TTL_SECONDS 常量与 _resetPackOsd;_finishPack、_packOrder 步骤4/7.5 接入", "代码:app/service/systems/pack_task_auto_finish.js 扫描补 workbench_id,自动结束后调用 _resetPackOsd;app/schedule/auto_finish_pack_task.js 注释同步", "回归测试:test/workbench_reset_pack_osd.test.cjs(8 用例,mock ctx)全部通过" ] }, { "version": "2026.09.13-stockout-waybill-codes-single-deprecate", "date": "2026-09-13", "type": "updated", "module": "storage.stockout", "summary": "出库单运单号口径收敛为复数:storage.stockout.confirm 的确认校验与出站回传改为以 waybill_codes 为准(对齐奇门 packages.package[] 多运单模型,不使用 deliveryOrder.expressCode),错误文案由「未填写运单号(waybill_code)」改为 (waybill_codes);storage.stockout.updateExpress 以 waybill_codes 为主,单数 waybill_code 降级为镜像字段(传复数时自动镜像首个数,传空数组/null 时同步置 NULL),仅传单数的旧调用方行为不变。存量单在复数缺失时仍回退单数,避免卡单。", "methods": [ "storage.stockout.confirm", "storage.stockout.updateExpress" ], "notes": [ "代码依据:app/service/systemMethods/storage/stockout.js#confirm(校验改为 waybill_codes 优先、单数回退;报文运单号复用校验结果)、#updateExpress(waybill_codes 写入时镜像 waybill_code = 首个);app/service/systems/order_async.js#syncStockoutOrders 写回注释同步为「复数为准、单数为镜像」", "协议依据:taobao.qimen.stockout.confirm 中运单号在 packages.package[].expressCode(多包裹/多运单,每个包裹一个),deliveryOrder.expressCode 为单据级单运单号(多运单场景不使用)", "回归测试:stockout.confirm.outbound.test.js 扩到 8 条(新增「一单多运单只填复数即可确认且回传 packages.package[] 两个包裹」「存量单仅有单数仍可确认」);新增 stockout.updateExpress.test.js 7 条(复数镜像、空数组/null 清空、复数优先覆盖单数、仅单数行为不变、非数组 400、无字段 400)", "对外契约影响:确认失败文案变化(waybill_code → waybill_codes);updateExpress 响应仍同时返回两列(waybill_codes 为准,waybill_code 为镜像);仅传 waybill_codes 即可完成填写与确认,调用方可不再传单数", "存量兼容:复数缺失时 confirm 回退单数、updateExpress 仅传单数行为不变,因此旧调用方无需强制同步升级", "文档版本 0.3.118 -> 0.3.119,updatedAt 2026-09-13;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" ] }, { "version": "2026.09.13-storage-stockout-confirm-source-routing", "date": "2026-09-13", "type": "updated", "module": "storage.stockout", "summary": "修复 storage.stockout.confirm 出站回传未按出库单来源分流的问题:confirm 改为复用 systems/order_async.js#notifyStockoutExternalInternal(QM→奇门 taobao.qimen.stockout.confirm,API→OpenAPI 回调 method=stockout.confirm,WMS 等内部来源无需通知直接成功),与出库单转订单回传同一套分流口径;API 来源 appKey 按货主合约反查。修复后 API 来源出库单不再被错误发往奇门(此前被奇门以「-1 无法匹配货主」拒绝,且跳过出站同样走失败分支,导致该来源出库单无法确认);同时确认文档同步分流语义与新增失败文案。", "methods": [ "storage.stockout.confirm" ], "notes": [ "代码依据:app/service/systemMethods/storage/stockout.js#confirm(第二步由硬编码 qimenClient.send 改为调用 ctx.service.systems.orderAsync.buildStockoutConfirmRequest / resolveOpenApiAppByStore / notifyStockoutExternal);app/service/systems/order_async.js 新增 3 个实例方法(buildStockoutConfirmRequest / notifyStockoutExternal / resolveOpenApiAppByStore)复用既有模块级实现,未改动原函数与其既有调用方", "回归测试:test/app/service/systemMethods/storage/stockout.confirm.outbound.test.js 新增 6 条用例(API 走回调不发奇门、API 无可用 ApiApp 时不回落奇门、QM 仍走奇门且不发回调、WMS 内部来源直接完成、QM 奇门失败保持 CREATED、未填 waybill_code 前置拒绝)", "对照验证:order_async.openapi.callback.test.js(5 failing)与 order_async.syncOrderIds.test.js(13 failing)为改动前既有失败(测试未跟上 2026-09-13 API 回传「不再静默跳过」的口径变更),已用「新增方法临时抛错后失败数不变」判定与本次改动无路径交集", "对外契约影响:入参、成功响应结构不变;新增可能出现的失败文案「出库单回传服务不可用」与 API 来源的「缺少 appKey,无法回传出库单」;WMS 等内部来源出库单由「出站同步失败: 未发起出站通知」变为可正常确认完成", "文档版本 0.3.117 -> 0.3.118,updatedAt 2026-09-13;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" ] }, { "version": "2026.09.13-storage-stockout-waybill-field-align", "date": "2026-09-13", "type": "updated", "module": "storage.stockout", "summary": "修正 storage.stockout.updateExpress / storage.stockout.confirm 的运单号字段口径(仅文档,未改代码):updateExpress 的入参由「express_code=运单号、express_codes=运单号列表」纠正为真实实现口径——express_code=快递公司编码(自动解析 express_name)、waybill_code=运单号、waybill_codes=运单号列表,并补齐 express_name/waybill_code/waybill_codes 响应字段与「没有需要更新的字段」错误项;confirm 的运单号校验字段由 express_code 纠正为 waybill_code,并如实描述响应 expressCode/expressCodes 的来源与历史遗留命名。", "methods": [ "storage.stockout.confirm", "storage.stockout.updateExpress" ], "notes": [ "代码依据:app/service/systemMethods/storage/stockout.js#updateExpress(L826 起,仅识别 express_code/waybill_code/waybill_codes,无 express_codes 分支)、#confirm(L577 校验 order.waybill_code)、app/model/order_stockout.js(express_codes 标注 @deprecated)", "背景:2026-08-07 首次上线时 express_code/express_codes 即运单号口径;随后迁移 20260807140000 引入 waybill_code/waybill_codes 并改义 express_code 为快递公司编码,但 methods/system.json 与 confirm 错误文案未同步,导致调用方按旧文档传 express_codes 时静默失败。", "对外契约影响:仅描述与错误文案纠偏,接口行为、参数名、HTTP 状态码均未变更;调用方需把运单号列表参数由 express_codes 改为 waybill_codes(confirm 前还需填 waybill_code)。", "文档版本 0.3.116 -> 0.3.117,updatedAt 2026-09-13;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)", "后续代码侧待办(未在本次实施):updateExpress 增加 express_codes 兼容映射或对未识别参数报错、补 warehouse_id 归属校验;confirm 成功响应 expressCode/expressCodes 收敛为 waybill_code/waybill_codes。" ] }, { "version": "2026.09.13-pendingOrder-syncOrderIds-api-confirm-before-deduct", "date": "2026-09-13", "type": "updated", "summary": "order.pendingOrder.syncOrderIds 描述同步 API 渠道同步顺序变更(代码已先行落地):API 渠道订单改为逐单「先回传 deliveryorder.confirm、回调成功才扣减库存并置 sync_status='fin'」,回调失败/异常置 sync_status='error' + 待处理异常、不扣减库存、可重新派发;单订单失败统一「写入错误状态 + 标记待处理异常」。QM/MANUAL 口径不变。文档版本 0.3.115 → 0.3.116。", "methods": [ "order.pendingOrder.syncOrderIds" ], "notes": [ "代码依据:app/service/systems/order_async.js#finalizeLocalChannelOrdersInternal → processApiOrderInternal(回调成功才 processLocalChannelOrderInternal 扣减并置 fin)、markApiSyncFailedInternal(error + markPendingException)", "params / response / errors 未变,仅 description 同步语义", "本次仅同步文档,未修改任何业务代码;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" ] }, { "version": "2026.09.12-storage-entry-cancel-entryOrderCode-doc", "date": "2026-09-12", "type": "updated", "module": "storage.entry", "summary": "storage.entry.cancel 文档小幅补充(对外契约不变):description 末尾注明另支持按 entryOrderCode(兼容别名 entry_order_code)按单号定位、供奇门/openapi 外部渠道复用;params 新增可选 entryOrderCode(内部复用口径,优先于 id/ids)。id/ids 入参、响应结构 { code, message, data } 与全部失败文案(入库单不存在或无权访问 / 入库单已作废 / 已完成入库单不允许作废 / 入库单已完成回传,不可取消 / 作废成功)逐一不变。", "methods": [ "storage.entry.cancel" ], "notes": [ "app/service/systems/storage/entry.js cancel:新增 data.entryOrderCode(或 data.entry_order_code)按单号定位(定位条件带 is_enabled/deleted_at/warehouse_id,有 storeId 时追加货主条件),优先于 id/ids;options 为外部渠道扩展(warehouseId/storeId/operatorLabel/skipExternalSync/idempotent/notFoundMessage),系统方法入口不传时行为与文案与历史版本完全一致", "奇门 order.cancel 与 openapi order.cancel 的 RK 组经此共用作废流程(skipExternalSync=true、idempotent=true、notFoundMessage=未找到对应的入库单)", "methods/system.json:storage.entry.cancel 的 description 末尾补一句按 entryOrderCode 定位说明,params 新增可选 entryOrderCode;id/ids、response、errors 文案未动", "文档版本 0.3.114 -> 0.3.115(docMeta.version),updatedAt 保持 2026-09-12", "本次仅同步文档,未修改任何业务代码;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" ] }, { "version": "2026.09.12-storage-stockout-cancel-shared-impl", "date": "2026-09-12", "type": "updated", "module": "storage.stockout", "summary": "storage.stockout.cancel 内部实现改为委托共享 app/service/systems/stockout_order.js#cancel(奇门 / openapi 同口径:单事务 + 行锁);对外契约完全不变(缺少出库单ID / 缺少仓库上下文 / 出库单不存在 / 出库单当前状态(xxx)不允许取消 / 成功返回取消成功 + data 含 id、stockout_order_code、order_status);由「先查单再开事务」改为「单事务 + 行锁」,并发取消/确认/转单更安全。", "methods": [ "storage.stockout.cancel" ], "notes": [ "app/service/systemMethods/storage/stockout.js cancel 改为薄适配层:校验 id(缺少出库单ID)与仓库上下文(缺少仓库上下文),委托 systems.stockoutOrder.cancel({ id }, { storeId: null, warehouseId, operatorLabel }),将共享层「未找到对应的出库单」映射为「出库单不存在」,成功映射为「取消成功」并透传 id / stockout_order_code / order_status", "app/service/systems/stockout_order.js cancel:定位优先 stockoutOrderCode 其次 id;单事务 + 行锁(防止并发取消/确认/转单),仅 CREATED/PENDING 可取消(canCancel),已 CANCELLED 幂等返回成功,COMPLETED/TRANSFERRED 返回「出库单当前状态(xxx)不允许取消」", "对外契约与实现变更前一致,调用方无需改动", "methods/system.json:storage.stockout.cancel 的 description 补充共享实现说明;errors 由单条 description 文本改为逐条 code/message(与仓库统一格式),文案不变;docMeta.version 0.3.113 -> 0.3.114,updatedAt 保持 2026-09-12", "本次仅同步文档,未修改任何业务代码;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)" ] }, { "version": "2026.09.12-storage.inventory.listBySpaceId", "date": "2026-09-12", "type": "added", "summary": "新增 storage.inventory.listBySpaceId 接口:传入 space_id,先判断该库位是否为当前仓库的库位(不存在返回 404、存在但不属于当前仓库返回 400),是则返回该库位下有量库存(quantity > 0)的商品列表。列表按商品(stock_id)汇总为一条(汇总 quantity/locked_quantity/intercept_locked_quantity/available_quantity,含 batch_count 与最早/最晚入库时间);商品信息统一走 stock_warehouse 通用链路(getStockDetails)返回 stock_warehouse 通用属性。", "methods": [ "storage.inventory.listBySpaceId" ], "notes": [ "app/service/systemMethods/storage/inventory.js 新增 listBySpaceId 包装方法(透传 data.space_id,返回结构沿用 this.success('ok', result)),并加入 _noNeedRight/_noNeedLog/_noNeedAuth 豁免列表(与 listByStockId 一致)", "app/service/systems/storage/inventory.js 新增 getStorageListBySpaceId:校验 space_id 为正整数与当前仓库上下文(ctx.user.store_id);先查 wms_location_space(id + warehouse_id + deleted_at=null)判断库位归属,未命中再查全局记录以区分「库位不存在」(404)与「库位不属于当前仓库」(400)", "库存查询条件:wms_storage where warehouse_id + space_id + quantity > 0 + is_enabled=1 + delete_at=null,按 id 倒序取出库位明细行(仅取汇总所需列,不返回批次/效期明细)", "商品通用属性:收集明细行 stock_id 去重后调用 ctx.service.systems.stockWarehouse.getStockDetails(stockIds, { warehouseId })(带缓存通用链路),stock 对象即 stock_warehouse 通用属性(id/item_code/item_name/sku_property/quantity/locked_quantity/is_batch_mgmt/is_shelf_life_mgmt/is_images/need_recheck/store_id/packing_requirements/stock_unit/barcodes/image_url);该链路异常时降级为 stock=null 且不中断主流程", "app/service/systems/storage/inventory.js 新增 _aggregateStorageRowsByStock:按 stock_id 在内存汇总数量与批次数、取最早/最晚入库时间(app.formatDate 格式化),并平铺 space_code/space_name(custom_name 优先,否则 space_code)与 store_name(wms_store_warehouse.store_remask,按 warehouse_id + store_id 收敛,查询异常降级为 null)", "响应结构:data.space(id/warehouse_id/space_code/custom_name/space_status)+ data.list(按商品汇总行,无有量库存时为空数组)", "错误码:400「space_id 必填且必须为正整数」、400「无法获取当前仓库信息」、400「库位 {space_id} 不属于当前仓库」、404「库位不存在: space_id={space_id}」", "methods/system.json 新增 storage.inventory.listBySpaceId 条目(追加于 storage.inventory.listByStockId 之后;isNeedAuth=false、isNeedLogin=true、isNeedRight=false),version 0.3.112 -> 0.3.113,updatedAt 2026-09-12", "AI_METHOD_ROUTING.md 第 6 节按文件内维护说明刷新(node .\\script\\tmp-gen-service-method-inventory.cjs → node .\\script\\tmp-update-ai-method-routing.cjs):systemMethods/storage/inventory.js 14 -> 15、systems/storage/inventory.js 13 -> 15(新增 getStorageListBySpaceId、_aggregateStorageRowsByStock)", "验证:ESLint(npx eslint app/service/systems/storage/inventory.js app/service/systemMethods/storage/inventory.js)0 error;未执行任何部署/回退脚本,未改动数据库与 Redis 数据" ], "module": "storage.inventory" }, { "version": "2026.09.11-shops-edit-shop-name-doc-sync", "date": "2026-09-11", "type": "updated", "summary": "同步 shops.edit 文档:补入 shop_name 入参(修改店铺名称),修正「仅允许修改 platform_code 或 custom_name」的过时描述与错误文案。", "methods": [ "shops.edit" ], "notes": [ "实现依据:app/service/systemMethods/shops.js 的 edit 已透传 shop_name/shopName(与 custom_name/platform_code 同样兼容 camelCase),app/service/systems/shops.js 的 edit 已支持 updates.shop_name。", "字段语义区分:shop_name 为平台真实店铺名(shops.add 时写入 PENDING_* 占位名,授权回调后同步真实名称);custom_name 为自定义名称,仅作标签展示。", "校验行为:三者至少传一个,否则抛 400「仅允许修改 platform_code、custom_name 或 shop_name」;shop_name 走 normalizeText(required, maxLength=100),为空抛 400「shop_name 不能为空」、超长抛 400「shop_name 长度不能超过 100」。", "唯一性:改名与改平台合并后按「当前仓库 + next platform_code + next shop_name」调用 ensureShopNameUnique(排除自身,软删除店铺名以 DELETED_SHOP_NAME_PREFIX 前缀排除),冲突抛 409「同仓同平台下 shop_name 已存在」。", "文档更新:methods/system.json 的 shops.edit description 改为 platform_code/custom_name/shop_name 三选一,params 新增 shop_name(兼容 shopName),errors 补入 shop_name 相关 400 文案、id 与仓库校验 400、店铺不存在 404,并修正 400「仅允许修改 platform_code 或 custom_name」为「仅允许修改 platform_code、custom_name 或 shop_name」;version 0.3.111 -> 0.3.112,updatedAt 2026-09-11。", "仅文档同步,未修改任何业务代码;未执行部署/回退脚本,未改动生产数据。" ], "module": "shops" }, { "version": "2026.09.11-wave-batch-list-where-operator", "date": "2026-09-11", "type": "changed", "summary": "order.wave.batchList(波次管理列表)的 where 新增操作符传参支持:白名单字段统一支持裸值与 {operator,value,type} 标准结构(eq/ne/gt/lt/ge/le/in/notin/between/notbetween/like/contains/notlike/startswith/endswith/isnull/isnotnull,按字段分组限制),value 支持数组(like/contains 多值 OR、notlike 多值 AND、in/notin 要求非空数组、eq 传数组等价 in);未显式传 operator 时保持历史默认语义(wave_no/creator/logistics_name/item_part/item_snapshot_key/item_detail_machine 默认模糊,其余默认等值),裸数组按 in。新增 total_orders / processed_orders 两个数值字段,store_id 新增 ne/notin 排除语义。修复前端通用筛选器下发 {operator,value:[...]} 时 wave_id 等整数字段报「参数不合法」、wave_no 等文本字段被 String([...]) 拼成 'A,B' 导致恒空的问题。", "methods": [ "order.wave.batchList" ], "module": "order.wave", "notes": [ "app/service/systemMethods/order/wave.js:buildBatchListWhereClause 由「逐字段手写 if 取 .value」改为通用条件构建,新增 isEmptyBatchListWhereValue(空值跳过,isnull/isnotnull 例外)、resolveBatchListFieldCondition(区分标准结构与裸值,仅标准结构读取 operator,裸值回落字段默认操作符)、buildBatchListFieldConditionSql(操作符 → SQL 片段 + 命名占位符)、normalizeBatchListDistinguishExpressValue(布尔归一 0/1)、normalizeBatchListStoreIdCondition(货主条件归一 in/notin)。", "默认语义与历史完全对齐:wave_no/creator/logistics_name/item_part/item_snapshot_key/item_detail_machine 未传 operator 时 LIKE '%值%';wave_id/wave_type/wave_status/source/distinguish_express 默认等值;total_orders_min/max、processed_orders_min/max 默认 ge/le;裸数组按 in(此前会被 String(arr) 拼成 'A,B' 恒空)。", "新增数值字段 total_orders / processed_orders(默认 eq,支持 between 等数值操作符);原有 *_min/*_max 保留范围语义,也接受标准结构覆盖默认操作符(如 {operator:'between',value:[1,20]})。", "store_id:默认 eq/in(返回包含任一筛选货主订单的波次,含混合货主波次);新增 ne/notin 排除语义——外层 WHERE 追加 wb.wave_id NOT IN (SELECT DISTINCT od.wave_id FROM <订单分表> od WHERE od.wave_id IS NOT NULL AND od.store_id IN (:whereStoreIds)),子查询显式排除 NULL 波次号,避免 NOT IN 三值逻辑把整表过滤为空。", "分配/复核状态类(storage/express/print/review_assignment_status)仍只支持等值(内部按聚合统计判定):改为先解构 {operator,value} 再校验,显式传非 eq 操作符直接报错「仅支持: eq」,不再被 String({...}) 静默拼成非法枚举值。", "根因:batchList 走原生 SQL 拼条件(列表查询路线 B),只读 .value 不读 operator——整数字段 Number({operator,value}) → NaN → 抛「参数不合法」;文本字段 String([...]) → 'A,B' → LIKE '%A,B%' 恒空(无报错难以定位)。", "验证:run/check-wave-batch-where-operator.cjs(egg-mock 起真实 service,只读、不写库、不清理数据)33/33 通过——基线 274;wave_no eq/like/裸值/startswith/notlike/数组 contains/数组 eq;wave_id 裸值/in/裸数组/gt/between/notbetween;creator 裸值/eq/ne;wave_type in;source in;distinguish_express 裸 true/in;total_orders between、total_orders_min/max 历史回归;logistics_name isnotnull;storage_assignment_status {operator:eq} 与裸值结果一致;store_id 裸值/数组/notin(= baseline - positive)/不存在货主(notin 直通基线,验证 NULL 安全);5 个错误用例(不支持操作符、store_id 不支持操作符、分配状态仅 eq、where 禁止 warehouse_id、不支持的字段)。期望值均由本地开发库现算(含货主覆盖数),不依赖硬编码总量。", "methods/system.json:order.wave.batchList 方法描述与 where 参数说明同步操作符契约、字段分组允许集合、新增 total_orders/processed_orders 与 store_id ne/notin 语义;version 0.3.110 -> 0.3.111,updatedAt 2026-09-11。", "兼容性:未显式传 operator 的既有调用语义完全不变,包括 delivery_order.findAutoGroupingWaveId 传入的 wave_status/item_part_type/item_part/item_snapshot_key/distinguish_express/logistics_name 裸值,以及分页 page/pageSize 顶层写法。", "未执行任何部署/回退脚本,未改动生产数据;ESLint(npx eslint app/service/systemMethods/order/wave.js)0 error。" ] }, { "version": "2026.09.10-packing-where-waybill-wave-contains", "date": "2026-09-10", "type": "changed", "summary": "order.packing.list / order.packing.export 的 where.waybill_code 与 where.wave_no 新增 operator 支持:operator=contains(兼容 like)时按 LIKE '%值%' 模糊匹配;两字段 value 均支持字符串数组(多值取并集)。修复前端通用筛选器下发 {operator:'contains', value:[...]} 时因数组被整体字符串化(String(['A','B']) → 'A,B')导致恒返回空列表的问题。", "methods": [ "order.packing.list", "order.packing.export" ], "module": "order.packing", "notes": [ "app/service/systems/order_packing.js:_buildListWhere 的 waybill_code 分支改为逐单号展开条件——operator=contains/like 下发 { waybill_code: { [Op.like]: '%单号%' } }(escapeLikeWildcards 转义通配符);缺省/eq 保持原「完整单号等值 + 剥离 -1-1- 分段后缀主体等值 + 主体前缀 LIKE '主体-%'」三件套,仍不落入 %短串% 模糊分支。所有条件合并为一次 OrderExpress.findAll({ [Op.or]: ... }) 解析 order_id,无命中仍走 queryWhere.id = -1 强制空结果。", "app/service/systems/order_packing.js:wave_no 分支支持 operator——eq/in 精确(单值等值、多值 Op.in)、ne 不等、contains/like/缺省为模糊 LIKE '%值%'(缺省保持历史模糊语义),多值模糊通过 queryWhere[Op.and] 追加 { [Op.or]: [...] } 合并。", "list 与 export 复用同一 _buildListWhere,导出同步生效;未改任何 SQL 结构,仅条件组装方式变化。", "验证:run/check-packing-where-contains.cjs(egg-mock 启动真实 service,只读)10/10 通过——数组+contains 命中 2 条(原上报场景原为 0 条)、单值无 operator 回归 1 条、数组+eq 2 条、不存在单号+contains 0 条、空数组等同无筛选 13 条、wave_no contains 单值 3 条/数组 4 条、wave_no in 4 条、wave_no eq 精确不模糊 0 条。" ] }, { "version": "2026.09.10-report-filename-time-placeholder", "date": "2026-09-10", "type": "changed", "summary": "报表导出文件名模板新增占位符:{time}(生成时刻 HHmmss)、{datetime}(数据日期_生成时刻)、{timestamp}(生成时刻毫秒时间戳);{date} 语义保持不变(仍为数据日期 params.bizDate,缺省服务器当天)。用于同一天多次投递/手动导出同一报表时避免 COS 同名覆盖(同名文件被后一次写覆盖且 CDN 可能仍回源旧内容,表现为「下载到的还是旧版列」)。缺省文件名模板不变,存量定义不受影响(未改 file_name 者行为完全不变)。", "methods": [ "report.generate", "report.definition.save", "report.definition.list", "report.deliveryPlan.save" ], "module": "report", "notes": [ "app/service/systems/report.js:buildFilename(definition, bizDate, now) 新增第三参 now(生成时刻,缺省 new Date(),可注入供测试);替换顺序 {datetime} -> {date} -> {time} -> {timestamp};{date} 取值逻辑(params.bizDate || 服务器当天)与既有行为完全一致;缺省模板仍为 _.xlsx。", "根因与实测:2026-09-10 同一 (store 1000000, 定义 3, biz_date 2026-09-09) 在 19:40、19:58、20:07 三次投递使用同名 interceptOrder_2026-09-09.xlsx,COS 对象被覆盖且 CDN 仍回源旧版本,导致用户看到 10 列旧表(缺「仓库商品名称」)。定义改为 interceptOrder_{date}_{time} 后手动导出产出 interceptOrder_2026-09-09_201533.xlsx,文件 13 列(含仓库商品名称/平台交易单号/两列拦截时间)与定义勾选一致。", "app/model/report_definition.js 字段注释、app/service/systemMethods/report/definition.js JSDoc、methods/system.json(report.definition.save description 与 file_name 参数/响应/定义对象说明共 4 处)、docs/report-config-guide.md 第 1 节模型表与第 4 节文件名说明同步为四种占位符;docMeta.version 0.3.108 -> 0.3.109,updatedAt 保持 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位。", "测试:test/report_systems_engine.cjs 的 buildFilename 用例扩充({date}_{time}、{datetime}、{timestamp}、不同生成时刻文件名不同、未传 now 回落当前时刻、{date} 语义不变、缺省模板与自动补 .xlsx 保持);13 个 test/report_*.cjs 全部通过,ESLint 0 error。", "数据/配置变更(仅开发库,已披露):wms_report_definition id=3 的 file_name 由 interceptOrder_{date} 改为 interceptOrder_{date}_{time},使定义重新投递/手动导出时文件名唯一。", "兼容性:占位符为新增能力,未使用新占位符的既有定义(如 7日出入库数据 7daysStockFlow_{date})输出文件名与行为完全不变;未执行部署脚本,未改动生产数据。" ] }, { "version": "2026.09.10-intercept-order-source-order-codes", "date": "2026-09-10", "type": "added", "summary": "interceptOrder(库内确定拦截订单明细)报表新增导出列「平台交易单号」(字段 key source_order_codes,取配送表 wms_order_delivery_*.source_order_codes 原值,列位置紧跟「外部单号」)。注册字段数 48 -> 49(订单导出 item 模式去掉商品图片 46 列 + 附加 3 列:平台交易单号 + 通知拦截时间 + 库内确定拦截时间);接口入参/响应契约不变,stockFlow 与 order.export 均不受影响。", "methods": [ "report.definition.typeList", "report.generate", "report.definition.save" ], "module": "report", "notes": [ "app/service/systems/report/queries/interceptOrder.js:FIELDS 在 external_order_code(外部单号)之后插入 { key: 'source_order_codes', label: '平台交易单号', type: 'string' }。", "app/service/systems/report/queries/interceptOrder.js:enrichInterceptTimes 重命名为 enrichInterceptFields(已导出),回查 attributes 由 [id, intercept_time, dispath_time] 扩为 [id, source_order_codes, intercept_time, dispath_time],同一批查询同时回填平台交易单号(null/undefined 归一化为空字符串);仍按 500 订单分片、异常只 warn 不阻断报表。", "取数原因:明细行来自 orderExport.buildOrderExportPage(mode=item) → mapOrderExportRow(item),该映射不输出 source_order_codes,故由查询器回查补充。", "测试:test/report_intercept_order_fields.cjs 同步为 49 列断言(预期列序 = 订单导出 item 去掉商品图片,在 external_order_code 后插入平台交易单号、末尾 2 列拦截时间),并补充平台交易单号取值与回查 attributes 断言;test/report_systems_engine.cjs 注册字段数断言 48 -> 49;13 个 report_*.cjs + test/intercept_time_lifecycle.cjs 全部通过,ESLint 0 error。", "端到端:script/tmp-verify-intercept-order-dev.cjs D 段增加平台交易单号与配送表 source_order_codes 的逐单交叉核对(通过);同时修正该脚本 A 段旧断言(原先假设开发库昨日 0 行,现改为校验 meta.orderCount 与明细去重订单数一致)。", "生产/开发验证:投递计划 id=2(货主 1000000 → 仓 100000,时间点 19:40)于 2026-09-10 19:40:45 投递成功(wms_report_delivery_log id=16 status=delivered,文件 exports/report/3/store-1000000/20260910/interceptOrder_2026-09-09.xlsx),文件内容核对为 1 表头 + 4 行明细(对应补测的 3 单)。", "methods/system.json:report.definition.typeList description 与 fields 说明同步为 49 列(含平台交易单号);docMeta.version 0.3.107 -> 0.3.108,updatedAt 保持 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位。", "docs/report-config-guide.md 2.2 节:字段清单新增 source_order_codes 行(紧跟 external_order_code)、列数 48 -> 49、第 10 条口径改为「附加列(3 列)」并说明平台交易单号来源;AI_METHOD_ROUTING.md report 速查同步。", "注意:报表定义的 fields 需显式勾选 source_order_codes 才会出现在导出列中(已有定义不动则不输出该列);本次未修改任何已有 wms_report_definition 配置行,未执行部署脚本。" ] }, { "version": "2026.09.10-intercept-time-lifecycle", "date": "2026-09-10", "type": "changed", "summary": "拦截时间 intercept_time 口径调整(wms_order_delivery):统一为「最近一次发起拦截的通知时刻」——发起/通知拦截仅**首次写入**(重复发起不覆盖已有值),库内拦截确认(order.recheckOrder.confirmIntercept / order.recheckOrder.interceptScan / 定时自动确认)与退回入库(returned)**不再写该字段**,取消/解除拦截(order.pendingOrder.batchUnintercept)与订单克隆重置**置空 null**;「库内确定拦截时刻」改用配送表 dispath_time(订单迁移进配送表的时间)。同步调整 interceptOrder 报表两列:通知拦截时间 intercept_notice_time = 配送表 intercept_time(为空回落 ORDER_INTERCEPT_REQUEST 操作日志最早一条),库内确定拦截时间 intercept_confirm_time = 配送表 dispath_time(原 key intercept_time 更名;该报表类型尚未落库定义行,无兼容问题)。", "methods": [ "order.pendingOrder.batchIntercept", "order.pendingOrder.batchUnintercept", "order.pendingOrder.cloneOrder", "order.recheckOrder.confirmIntercept", "order.recheckOrder.interceptScan", "report.definition.typeList", "report.generate" ], "module": "order", "notes": [ "app/lib/intercept_time.js(新增):拦截时间字段口径工具(纯函数):isEmptyInterceptTime、buildNoticeTimePatch(currentValue, now)(空值才写入,已有值返回空对象=不覆盖)、pickNoticeTimeOrderIds(rows)(批量场景筛出尚未写入通知时刻的订单ID,去重保序);文件头注释固化生命周期口径(首次写入/不覆盖/取消置空/库内确定时刻改用 dispath_time)。", "发起/通知拦截(首次写入,不覆盖):app/service/qimenMethods/order.js(intercepting/requested 两处 existingOrder.update 改为 ...buildNoticeTimePatch(existingOrder.intercept_time, noticeNow))、app/service/openapiMethods/order.js(intercepting)、app/service/inbox/functions.js(两处波次感知拦截:订单查询 attributes 增补 intercept_time,主更新只写 intercept_status,随后仅对 pickNoticeTimeOrderIds 命中的订单补写 intercept_time)、app/service/systemMethods/order/pendingOrder.js(取消订单转拦截的 syncedOrders 批量更新、batchIntercept 分批更新:同样先取空值订单子集再补写)。", "库内拦截确认不再覆盖:app/service/systems/intercept_auto_confirm.js(confirmInterceptForOrderIds 的 updateValues 移除 intercept_time)、app/service/systemMethods/order/recheckOrder.js(interceptScan 的 orderModel.update 移除 intercept_time)。app/service/systems/return_received.js(退回入库 updateFields 移除 intercept_time)。", "取消/清空:app/service/systemMethods/order/pendingOrder.js batchUnintercept 保持 intercept_time=null(解除拦截置空);cloneOrder 的 RESET_FIELDS 新增 intercept_time=null(避免克隆重置新单继承原单发起拦截时刻)。", "interceptOrder 报表(app/service/systems/report/queries/interceptOrder.js):enrichInterceptTimes 改为 attributes=[id, intercept_time, dispath_time];intercept_notice_time ← intercept_time(为空时才回落 wms_operation_log 的 ORDER_INTERCEPT_REQUEST 最早记录,同仓隔离 business_type/business_id/warehouse_id 三重过滤,主取有值时不查日志);intercept_confirm_time ← dispath_time;meta 计数更名 confirmTimeFilledCount(原 interceptTimeFilledCount)。", "测试:新增 test/intercept_time_lifecycle.cjs(纯函数 3 例 + 写入点静态守卫 4 例:确认链路不得同写 intercepted_at_warehouse 与 intercept_time、发起链路使用首次写入工具、取消与克隆重置置空、退回入库不覆盖);test/report_intercept_order_fields.cjs 同步更新(末 2 列 key、dispath_time 作为库内确定拦截时间、日志兜底用例、缺失/模型不可用降级),共 18 例;test/report_*.cjs 13 个文件 + 新测试全部通过;ESLint 0 error。", "端到端校验(只读、无写操作):script/tmp-verify-intercept-order-dev.cjs D 段改为对开发库真实订单交叉核对「通知拦截时间=intercept_time(空时回落日志)」与「库内确定拦截时间=dispath_time」,与直连 SQL 一致。", "兼容性与风险:intercept_time 在本次上线前的历史数据可能仍是确认时刻(旧逻辑覆盖所致),这部分历史行的「通知拦截时间」不可靠;报表按「昨日」取数,上线次日起数据即为新口径。自动确认定时任务仍以 intercept_time 作为「发起后超时」判定依据,语义反而更准确(未被确认覆盖)。", "methods/system.json:order.pendingOrder.batchIntercept(首次写入不覆盖 + 取消清空说明)、order.pendingOrder.batchUnintercept(解除拦截清空 intercept_time)、order.recheckOrder.confirmIntercept 与 order.recheckOrder.interceptScan(确认不写 intercept_time、库内确定时刻以 dispath_time 为准)description 同步;report.definition.typeList 字段清单描述 key 更新为 intercept_confirm_time;docMeta.version 0.3.106 -> 0.3.107,updatedAt 保持 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位。", "docs/report-config-guide.md 2.2 节第 10 条与字段清单、AI_METHOD_ROUTING.md report 速查(新增拦截时间口径变更条目)同步;本次未执行任何数据库/Redis 写操作,未运行部署脚本。" ] }, { "version": "2026.09.10-intercept-order-time-columns", "date": "2026-09-10", "type": "added", "summary": "interceptOrder(库内确定拦截订单明细)报表新增导出列「通知拦截时间」与「库内确定拦截时间」:intercept_time(库内确定拦截时间)= 配送表 intercept_time(确认拦截时写入);intercept_notice_time(通知拦截时间)= wms_operation_log 中 operation_code='ORDER_INTERCEPT_REQUEST' 的最早记录时间(发起/通知拦截时刻,因为 intercept_time 在确认时会被覆盖,只能从操作日志反查,按订单ID+仓库ID同仓隔离;日志缺失时该列留空)。两列均格式化为 YYYY-MM-DD HH:mm:ss,列排在字段清单末尾,注册字段数 46 -> 48;接口入参/响应契约与 stockFlow 均不受影响。", "methods": [ "report.definition.typeList", "report.generate", "report.definition.save" ], "module": "report", "notes": [ "app/service/systems/report/queries/interceptOrder.js:FIELDS 末尾新增 intercept_notice_time(label 通知拦截时间)、intercept_time(label 库内确定拦截时间),type 均为 string(渲染层原样输出保留与订单导出 item 模式一致的零转换口径);列顺序 = 订单导出 item 模式 47 列去掉商品图片(46)+ 末 2 列拦截时间,共 48 列。", "app/service/systems/report/queries/interceptOrder.js:新增 enrichInterceptTimes(已导出供单测/脚本复核)——按订单ID分片(ENRICH_CHUNK_SIZE=500)回查:1)配送表模型 findAll(attributes: id/intercept_time) 取库内确定拦截时间;2)OperationLog.findAll(attributes: business_id + MIN(created_at) 别名 notice_time,group by business_id)取通知拦截时间,where 限定 business_type='order' + operation_code='ORDER_INTERCEPT_REQUEST' + warehouse_id=当前仓库 + business_id IN(订单ID字符串化)。两列分别格式化为 YYYY-MM-DD HH:mm:ss(空值/无效值空字符串,与订单导出 formatDateSafe 口径一致);任一回查异常只 warn 并留空,不影响报表主流程;OperationLog 模型缺失时跳过日志查询。", "同仓隔离:订单 ID 按仓库发号(wms_order_id_location_{wh}),日志查询必须带 warehouse_id,禁止仅凭订单ID跨仓串读(与 order_express 同仓隔离修复同口径)。", "app/service/systems/report/queries/interceptOrder.js:查询器返回 meta 新增 noticeTimeFilledCount / interceptTimeFilledCount(两列有值行数),便于核对日志覆盖率;rows 为同一行对象的拦截时间列赋值(同一订单的多条商品明细行同值)。", "测试:test/report_intercept_order_fields.cjs 新增 2 例(拦截时间两列取值/查询条件/分组断言;空值与 OperationLog 模型不可用降级),并同步列数断言 46 -> 48(前 46 列仍与订单导出 item 模式逐列对齐,末 2 列固定为拦截时间);test/report_systems_engine.cjs 注册表字段数断言同步为 48。test/report_*.cjs 13 个文件全部通过。", "真实数据校验(只读、无写操作):script/tmp-verify-intercept-order-dev.cjs 新增 D 段——以 egg 真实上下文调用 enrichInterceptTimes 对开发库 5 个库内确定拦截订单富化,并与直连 SQL(配送表 intercept_time、wms_operation_log 的 MIN(created_at))逐单交叉核对一致(开发库这 5 单均无 ORDER_INTERCEPT_REQUEST 日志,故通知拦截时间为空,符合预期);渲染表头列数校验同步为 48 且末两列表头为拦截时间列。", "methods/system.json:report.definition.typeList 的 description 与 fields 说明同步为 48 列(前 46 列对齐订单导出 item 模式去掉商品图片,末 2 列为拦截时间);docMeta.version 0.3.105 -> 0.3.106,updatedAt 保持 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位。", "docs/report-config-guide.md 2.2 节:字段清单补 2 行拦截时间列、新增第 10 条口径(两列来源/同仓隔离/空值语义/meta 计数),注册类型表与「与订单导出 item 模式差异」说明同步更新;AI_METHOD_ROUTING.md report 速查同步(48 列 + 两个时间列来源)。", "兼容性:仅为报表列扩展(新报表类型尚未在 wms_report_definition 落库定义行,无存量定义受影响);stockFlow 与 order.export 列口径、report.generate / report.deliveryPlan 链路均未改动。" ] }, { "version": "2026.09.10-report-intercept-order-type", "date": "2026-09-10", "type": "added", "summary": "通用报表新增注册类型 interceptOrder(库内确定拦截订单明细):以配送表 dispath_time(订单迁移进配送表的时间)为时间基准,统计昨日(自然日 [昨日 00:00:00, 今日 00:00:00) 本地时区半开区间)库内确定拦截订单(intercept_status=intercepted_at_warehouse),**统计日不得晚于昨天**(params.bizDate 传今天/未来一律回落昨日,今天发出去的报表不含今天数据;比昨天更早的显式日期仍被尊重以支持补数),按商品明细展开(一个商品一行),列与订单导出含明细模式(order.export export_mode=item)完全对齐、仅去掉「商品图片」列(共 46 列)。报表定义 type 填 interceptOrder 即可使用,report.generate / report.deliveryPlan / wms_report_definition 结构均无需变更。", "methods": [ "report.definition.typeList", "report.generate", "report.definition.save" ], "module": "report", "notes": [ "app/service/systems/report/queries/interceptOrder.js(新增):查询器签名与 stockFlow 一致 async ({ctx, storeId, warehouseId, params}) => ({windows: [], rows, meta})。数据源为配送表 wms_order_delivery_{warehouseId}_dispatch(经 orderExport.getOrderModelByTableType('dispatch', warehouseId) 取模型),过滤 intercept_status='intercepted_at_warehouse' 且 dispath_time ∈ [统计日 00:00:00, 次日 00:00:00);warehouseId 必填(<=0 抛「interceptOrder 查询器缺少仓库维度 warehouseId」),storeId>0 时追加 store_id 过滤(货主维度报表/投递),否则仓库维度全量。", "明细口径复用订单导出链路:按单页 1000 单分页循环(不足一页终止)调用 orderExport.buildOrderExportPage({ mode: 'item' }),即复用 mapOrderExportRow(item) 的状态中文翻译、货主备注、仓库商品名/条码回落、运单汇总、包材、收件人脱敏等取值,逐格与订单导出 item 模式一致;行再经 pickReportRow 按注册字段裁剪(丢弃 item_image 等多余键,缺失值回落空字符串)。", "统计日解析 resolveBizDayWindow:params.bizDate(兼容 biz_date)为真实存在的 YYYY-MM-DD 时按该自然日整天统计,缺省/非法一律回落昨日自然日;区间左闭右开,用 new Date(y, m, d) 构造规避夏令时步进偏差。Sequelize 未配置 timezone(默认 UTC)+ MySQL 时区 UTC,dispath_time 写入(orderDeliveryMigration.buildDispatchRow 写 new Date())与本查询的时间过滤经同一序列化路径,口径自洽。", "字段清单 FIELDS 共 46 列,与 order.export 的 ORDER_EXPORT_ITEM_COLUMNS(47 列)逐列对齐并去掉「商品图片」列,key/label/顺序一致;type 统一为 string(渲染层 renderCell 原样输出,不做 zeroToDash/yesNo 转换,且不声明 asText),以保证单元格取值与订单导出一致;无 array 展开列,windows 恒为空数组、单行表头、无表头合并。", "app/service/systems/report/queries/index.js:QUERIES 注册 interceptOrder,DESCRIPTIONS 新增条目(title「库内确定拦截订单明细」、window {dayCount: 1, cutoverHour: 0}),report.definition.typeList 自动带出 46 列字段元数据供报表定义勾选。", "行数保护与元信息:明细行数达 MAX_EXPORT_ROWS=200000 时截断并打 warn(meta.truncated=true);meta 返回 bizDate/startTime/endTime/warehouseId/storeId/interceptStatus/timeField/orderCount/rowCount/truncated 供复核。", "波次序号(wave_index)沿用订单导出同款 attachOrderWaveIndex(仓库ID取 ctx.user.store_id),定时投递(无 ctx.user)场景该列降级为 0,仓库主体手工导出为真实序号(与 order.export 行为一致)。", "统计日硬约束(同日补充):resolveBizDayWindow 解析出统计日后统一校验 baseDate >= 今日 00:00:00 时回落昨日——params.bizDate 传今天/未来(含手工导出误传当天)时查询区间仍为 [昨日 00:00:00, 今日 00:00:00),保证「今天发出去不含今天」;比昨天更早的显式日期仍被尊重(补数场景)。测试:test/report_intercept_order_fields.cjs 新增「硬约束:统计日不得晚于昨天」与「params.bizDate 传今天:查询区间仍为昨日」两例(共 16 例)。", "测试:新增 test/report_intercept_order_fields.cjs(14 例:字段与订单导出 item 逐列对齐、pickReportRow 裁剪、统计日区间解析、查询器 mock 链路含分页/where/meta/storeId 过滤与错误分支);同步修正 test/report_systems_engine.cjs 与 test/report_stockflow_fields.cjs 中「注册表仅 1 种类型」的旧断言(改为按 key 定位并断言注册顺序 stockFlow → interceptOrder)。test/report_*.cjs 共 13 个文件全部通过。", "端到端校验(只读、无写操作):script/tmp-verify-intercept-order-dev.cjs 以 egg 真实上下文在开发库跑通查询器(meta 正确、开发库历史拦截单 dispath_time 为 NULL 故昨日命中 0 行)、真实拦截订单 5 单 → 9 条商品明细行的取值映射,以及 renderSheetByType 渲染(表头 46 列、单行表头、无合并、无 textColumns)。", "methods/system.json:report.generate description 类型举例补 interceptOrder;params.bizDate 说明补充「同时是 interceptOrder 的统计日覆盖(缺省昨日自然日)」;params.dayCount/params.cutoverHour 标注仅 stockFlow 生效;report.definition.typeList 的 description、response.list、window.dayCount、window.cutoverHour、fields 说明同步为两种类型口径;docMeta.version 0.3.104 -> 0.3.105,updatedAt 保持 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位。", "docs/report-config-guide.md:新增注册类型行、46 列字段清单与 interceptOrder 口径章节;wms_report_definition 定义行由业务侧在后台配置(本次未插入定义行、未执行任何数据库写操作)。", "未修改任何既有接口入参/响应契约:新增类型为注册表扩展,stockFlow 行为不变,report.generate / report.deliveryPlan / report.exportTaskProgress 链路无需改动。", "README.md / AI_TOOLBOX.md 无需同步:检索确认无注册类型清单描述;AI_METHOD_ROUTING.md 第 6 节为函数清单,本次未新增/删除既有函数名(interceptOrder 为查询器注册 key),如需刷新可另行执行扫描脚本" ] }, { "version": "2026.09.10-cross-warehouse-order-express-warehouse-isolation", "date": "2026-09-10", "type": "fixed", "summary": "跨仓运单号串读缺陷修复文档同步:修复前所有按订单 ID 读取 wms_order_express 的查询缺少 warehouse_id 强制校验,存在跨仓串读运单号风险;修复后所有读取链路均强制校验订单所属仓库(查询条件同时限定订单ID与仓库ID),仓库归属无法确定时跳过读取或拒绝读取。order.detail 及各订单列表接口 description 补充「运单号按订单所属仓库隔离读取」说明,接口入参/出参契约不变。", "methods": [ "order.detail", "order.list", "order.reviewOrder.list", "order.pendingOrder.list", "order.pendingOrder.detail", "order.pendingOrder.reverseReviewOrder", "order.outboundOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list", "order.archiveOrder.list", "order.wave.waveStrategyFallbackOrderList", "order.recheckOrder.recheckOrderList", "order.recheckOrder.queryRecheckOrderSingleList" ], "module": "order", "notes": [ "app/service/systemMethods/order/base.js:getOrderExpressesByOrderId 强制同仓校验(仓库ID优先取订单行 order.warehouse_id,缺省回退当前上下文仓库,均缺失返回空数组);attachOrderExpressNumbers 批量回填改为按「订单ID+仓库ID」逐仓分组查询(行内 warehouse_id 优先,缺省回退上下文仓库,无法确定仓库归属的订单不参与运单查询)", "app/service/systemMethods/order/recheckOrder.js:confirmRecheck 调用 getOrderExpressesByOrderId 传入订单行;queryRecheckOrderSingleList 运单号关键词 EXISTS 搜索与 waybill_code 子查询均追加 oe.warehouse_id = o.warehouse_id 同仓条件", "app/service/systemMethods/order/pendingOrder.js:detail 传订单行给 getOrderExpressesByOrderId;assertOrdersWithoutWaybill 增加 warehouseId 入参强制同仓校验(reverseReviewOrder 反审前运单校验传入当前仓库ID,缺少仓库上下文时跳过校验读取,按无可读记录处理)", "app/service/systems/order_express.js:findValidOrderExpressRows 仓库ID缺失直接抛 400「缺少仓库上下文,禁止读取订单运单记录」;checkExpress 存在性校验、updateWeighingWeight、updateWeighingWeightByWaybill、按订单ID批量查询等读取链路全部追加 warehouse_id 条件", "app/service/systems/storage/report.js:loadReportReferenceMaps 运单查询强制 AND warehouse_id(仓库模式用当前仓库ID;货主模式按订单所属仓库 Map 分组查询);库存流水明细 SELECT 增加 t.warehouse_id 并构建订单ID→仓库ID映射传入", "app/service/systems/order_async.js:buildOrderWaybillCodeMapInternal 增加 warehouseId 入参并强制同仓校验(缺失返回空映射),syncManualOrders/syncStockoutOrders/syncQmOrders 三处调用均传入仓库ID", "app/service/systems/waybill.js:主单号 SELF JOIN 查询追加 warehouse_id 条件;app/service/systems/workbench.js:打包列表运单查询追加 warehouse_id 条件", "app/service/systems/express.js:运单状态 success 行查询追加 warehouse_id(取 options.warehouse_id 或当前仓库上下文);app/service/systems/express_platform.js:polyapi 已分配运单查询强制同仓校验,仓库ID缺失时不查询", "app/service/qimenMethods/order.js:getInterceptExpressInfo 增加 warehouseId 入参强制同仓校验(缺失返回空数组),sendCancelInterceptNotice 与取消拦截链路均传入 info.warehouseId;app/service/inbox/functions.js:已分配快递单号查询追加 warehouse_id;app/lib/intercept_guard.js:拦截守卫称重查询追加 warehouse_id", "methods/system.json:order.detail、order.pendingOrder.detail 与各订单列表接口(order.list、order.reviewOrder.list、order.pendingOrder.list、order.outboundOrder.list、order.expectionOrder.list、order.entrustOrder.list、order.deliveryOrder.list、order.deliveryExpectionOrder.list、order.archiveOrder.list、order.wave.waveStrategyFallbackOrderList、order.recheckOrder.recheckOrderList、order.recheckOrder.queryRecheckOrderSingleList)description 补充运单号按订单所属仓库隔离读取说明;params/response/errors/headers 契约均未变化;docMeta.version 0.3.103 -> 0.3.104,updatedAt 2026-09-08 -> 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位", "README.md / AI_TOOLBOX.md / AI_METHOD_ROUTING.md 无需同步:检索确认无 wms_order_express 读取口径描述;AI_METHOD_ROUTING.md 第 6 节为函数清单,本次未新增/删除函数名(仅实现与签名参数变化),无需刷新", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ] }, { "version": "2026.09.08-front-config-cert-pem-echo", "date": "2026-09-08", "type": "changed", "summary": "setting.warehouse.getFrontConfig 响应改为回显证书/私钥原文(cert_path/key_path 替换为 cert_pem/key_pem):cert_pem 读 cert_pem 列、key_pem 读 cert_key 列,未配置均为空字符串,响应仍 15 字段;saveFrontCert/saveFrontConfig 复用 buildFrontConfigOutput,响应口径同步返回 cert_pem/key_pem 原文;仅登录后的仓库主体(settings 页)接口回显,公共无鉴权接口 frontConfig.getByDomain 不受影响仍 6 字段白名单(domain/title/logo_url/login_bg_url/favicon_url/theme),严禁暴露证书内容。", "methods": [ "setting.warehouse.getFrontConfig", "setting.warehouse.saveFrontConfig", "setting.warehouse.saveFrontCert" ], "module": "setting.warehouse", "notes": [ "app/service/systems/setting/warehouse.js:buildFrontConfigOutput 输出字段 cert_path→cert_pem(证书 PEM 原文,读 cert_pem 列)、key_path→key_pem(私钥 PEM 原文,读 cert_key 列),未配置均为空字符串;响应仍 15 字段(warehouse_id/domain/title/logo_url/favicon_url/login_bg_url/theme/cert_pem/key_pem/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at);方法注释明确私钥原文回显仅限仓库主体登录后的 settings 页(getFrontConfig/saveFrontConfig/saveFrontCert 三个需登录接口复用本输出),公共无鉴权接口走 buildFrontConfigPublicOutput 白名单、不经过本方法", "app/service/systems/setting/warehouse.js:getFrontConfig 响应含证书原文(cert_pem)与私钥原文(key_pem)供仓库主体 settings 页回显;buildFrontConfigPublicOutput/getFrontConfigByDomain 不变(仍仅 FRONT_CONFIG_PUBLIC_FIELDS 6 字段,严禁输出 cert_pem/cert_key 证书与私钥内容及 cert_path/key_path/sync_status 等内部字段)", "app/service/systems/setting/warehouse.js:saveFrontConfig(约 L1260)与 saveFrontCert(约 L1380)响应均复用 buildFrontConfigOutput,响应口径与 getFrontConfig 一致返回 cert_pem/key_pem 原文;saveFrontCert 保存时证书/私钥 PEM 直接写 cert_pem/cert_key 列、cert_path/key_path 置空待定时任务回填真实路径的行为不变", "methods/system.json:setting.warehouse.getFrontConfig/saveFrontConfig/saveFrontCert 三个条目 response 中 cert_path/key_path 字段替换为 cert_pem/key_pem(原文回显语义、未配置为空字符串、注明仅登录仓库主体 settings 页回显的安全口径);getFrontConfig description 补充证书/私钥原文回显与公共接口 6 字段白名单口径;saveFrontCert description 由「响应 15 字段不含证书/私钥内容」修正为「响应 15 字段含 cert_pem/key_pem 原文回显」并同步「内容供定时任务读取、禁止写入日志」口径;saveFrontCert response updated_at 字段描述移除「响应不含 cert_pem/cert_key 证书与私钥内容」旧口径;getFrontConfig response cert_expire_at 描述删除已废弃的「纯路径模式」口径;frontConfig.getByDomain 条目未改动(仍 6 字段白名单、isNeedLogin=false、isNeedAuth=false);docMeta.version 0.3.102 -> 0.3.103,updatedAt 保持 2026-09-08;本变更记录写入 methods/changes/system.json 数组首位", "README.md / AI_TOOLBOX.md 无需同步:检索确认无 cert_path/key_path/getFrontConfig/saveFrontCert 字段描述引用;AI_METHOD_ROUTING.md 第 6 节仅方法名清单(getFrontConfig/saveFrontConfig/saveFrontCert 方法名未变、buildFrontConfigOutput 函数名未变)无需同步", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ] }, { "version": "2026.09.08-wave-strategy-group-buy-cross-pool-merge", "date": "2026-09-08", "type": "changed", "summary": "小团购 PDA 抓取跨池同结构合并文档同步(修复「1 单 1 波次」问题):order.wave.waveStrategyFetchPda 抓取主流程新增小团购跨池同结构合并工序(mergeWaveStrategyFirstPoolSameStructureOrders),自动分流执行结果 result 新增 merged_order_count 字段(合并进候选的跨池订单数量,无合并时为 0);触发条件为小团购 pickMode=1 + 第一池非空 + max_same_structure 为正整数且≠999,max_same_structure 为 null/999 的策略、大团购 pickMode=5 与后台抓取入口行为不变。", "methods": [ "order.wave.waveStrategyFetchPda" ], "module": "order.wave", "notes": [ "app/service/systemMethods/order/wave.js:新增私有方法 mergeWaveStrategyFirstPoolSameStructureOrders(约 L11339~L11495):按第一池候选分组出现过的 structure_key(require_same_express=1 时为「结构+快递」组合,快递口径复用候选 SQL expressExpr 的 COALESCE 优先级 sys_logistics_code > logistics_code > logistics_name)查询同结构全池过筛订单(wave_id=0、step!=0、post_status/storage_status=fin、print_status!=fin、status!=cancel、outbound_status!=padding、intercept_status=none、lock_status=none,不限策略匹配、不含池边界 create_at 条件),将两池同结构订单全部并入候选(按 id 去重)后复用既有分组建波流程;任一门控不满足返回 null 跳过合并", "app/service/systemMethods/order/wave.js:autoPopulateWaveStrategyFetchSelections 团购分支(strategy_type=2 且 pickMode=1)接入合并:仅 pickMode=1 且 candidate_pool_stage='first' 且 max_same_structure 为正整数且≠999 时执行合并,merged_order_count = 合并后候选数 - 原候选数;max_same_structure 为 null/999、pickMode=5(大团购)、第一池为空、全池查询无新增订单时 merged_order_count=0 维持现状;后台抓取入口(executeWaveStrategyDirectFetch / waveStrategyFetchAdmin)不经过本方法不受影响", "背景:订单池按今日前/今日分割 + min_same_structure 全池计数口径导致某结构第一池仅剩 1 条时仍通过门槛单独成波(生产订单 11103 案例「1 单 1 波次」)", "methods/system.json:order.wave.waveStrategyFetchPda 条目 response 数组末尾新增 merged_order_count 字段说明(合并进候选的跨池订单数量、无合并为 0、不含在原 candidate_count 内、合并后候选总量 = candidate_count + merged_order_count);description 补充小团购跨池同结构合并规则(触发条件与跳过条件);params/headers 不变;errors 条目键名由 description 规范化为 message(文案不变,满足更新脚本 schema,与 order.wave.waveStrategyList 等先例一致);docMeta.version 0.3.101 -> 0.3.102,updatedAt 保持 2026-09-08;本变更记录写入 methods/changes/system.json 数组首位", "兼容性:merged_order_count 为自动分流执行结果 result 新增可选字段,向后兼容;pickMode=5(大团购)、max_same_structure 为 null/999 的策略、后台抓取入口与第一池为空的场景行为与改动前一致,无接口破坏性变更", "回归验证:test/wave_first_pool_merge_regression_20260908.cjs 覆盖门控(pickMode/池阶段/max_same_structure)、快递组合口径、合并去重、merged_order_count 计数与建波结果(wms-test-agent 回归通过)", "README.md / AI_TOOLBOX.md 无需同步:检索确认无 waveStrategyFetchPda 抓取数量口径描述;AI_METHOD_ROUTING.md 第 6 节为自动扫描函数清单,如需刷新可另行执行扫描脚本", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ] }, { "version": "2026.09.08-wave-strategy-list-info-order-count", "date": "2026-09-08", "type": "changed", "summary": "order.wave.waveStrategyList 成功响应新增 info 子对象(info.order_count):返回当前查询条件下(当前仓库 + strategy_type 过滤)全部波次策略命中的订单总数,按订单去重、不受分页影响,统计失败时安全降级为 0;错误/失败路径响应结构不变,成功路径 info 恒存在。", "methods": [ "order.wave.waveStrategyList" ], "module": "order.wave", "notes": [ "app/service/systemMethods/order/wave.js:waveStrategyList 成功响应新增 info 对象;当 total>0(当前仓库存在波次策略)时调用 getWaveStrategyMatchedOrderCountTotal(contextWarehouseId,{strategyType}) 统计全部命中订单去重总数,异常时捕获并记录 warn 日志(含 warehouse_id/strategy_type/error)后降级为 0,不影响列表主流程", "app/service/systemMethods/order/wave.js:新增 getWaveStrategyMatchedOrderCountTotal(warehouseId,{strategyType}):基于 wms_order_wave_strategy_match 关联订单表与 wms_wave_strategy,require_same_express=1(结构+快递分组)与 =0(仅结构分组)两类候选口径 UNION ALL 后 COUNT(DISTINCT order_id);strategy_type 非法或未传时为 null(不过滤);仅统计未入波次且满足同结构 min/max 上下限的候选订单", "methods/system.json:order.wave 分组 order.wave.waveStrategyList 条目 response 数组末尾新增 info 子对象及 order_count 字段说明(全部命中订单去重总数、不受分页影响、异常降级为 0),params/headers/description 保持原样;errors 条目键名由 description 规范化为 message(文案不变,满足更新脚本 schema,与 order.manualOutboundOrder 等先例一致);docMeta.version 0.3.100 -> 0.3.101,updatedAt 保持 2026-09-08;本变更记录写入 methods/changes/system.json 数组首位", "README.md / AI_TOOLBOX.md 无需同步:检索确认无 waveStrategyList 响应结构描述;AI_METHOD_ROUTING.md 第 6 节为自动扫描函数清单(本次新增 getWaveStrategyMatchedOrderCountTotal 已纳入代码),如需刷新清单可另行执行扫描脚本", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ] }, { "version": "2026.09.08-front-cert-inline-content-save", "date": "2026-09-08", "type": "changed", "summary": "setting.warehouse.saveFrontCert 证书上传接口改版文档同步:入参 cert_pem/key_pem 重命名为 pem/key(必填,超长文案「pem|key 内容长度不能超过 65536 字符」);证书/私钥 PEM 内容直接写入 cert_pem/cert_key 列入库、保存时不再写暂存文件,cert_path/key_path 保存置空、等待未来定时任务部署后回填真实路径;cert_expire_at 仍由证书 validTo 权威写入,同步状态机重置(sync_status=0/sync_attempts=0/清空 last_sync_error/last_synced_at)与新旧 domain 公共拉取缓存清理保持不变;删除「证书暂存目录未配置/证书文件写入失败」500 错误分支;响应 15 字段不含证书内容(cert_pem/cert_key 仅定时任务读取)。", "methods": [ "setting.warehouse.saveFrontCert" ], "module": "setting.warehouse", "notes": [ "app/service/systems/setting/warehouse.js:saveFrontCert 入参改为 domain/pem/key(domain 经 normalizeFrontConfigText(data.domain,'domain',100) 校验非空 400「domain 不能为空」与超长 400「domain 长度不能超过 100 字符」;pem/key 经 normalizeFrontConfigPem 校验非空 400「pem 不能为空」「key 不能为空」、超长 400「pem|key 内容长度不能超过 65536 字符」);移除 writeFrontConfigCertFiles 落盘链路,证书内容直接入库 patch.cert_pem=certPem/cert_key=keyPem,patch.cert_path=null/key_path=null(等待未来定时任务从库内读取内容写 nginx 证书目录后回填真实路径);校验链 parseFrontConfigCertPem → assertFrontConfigCertValid → validateFrontConfigKeyPem → collectFrontConfigCertNames/frontConfigCertCoversDomain → assertFrontConfigDomainUnique 不变,任一失败统一「证书不合法」400;cert_expire_at=new Date(cert.validTo) 权威写入不变;sync_status=0/sync_attempts=0/清空 last_sync_error/last_synced_at 与新旧 domain front:config:domain:{*} 缓存清理逻辑不变;响应 buildFrontConfigOutput 15 字段不含 cert_pem/cert_key(内容仅定时任务读取)", "app/service/systemMethods/setting/warehouse.js:saveFrontCert 薄出口透传改为 domain/pem/key,_noNeedRight/_noNeedAuth 不变;错误 code 透传不变", "app/model/warehouse_front_config.js:cert_pem/cert_key TEXT 列承接证书内容(comment 注明仅定时任务读取、禁止写入日志/接口响应),cert_path/key_path 保存置空由未来定时任务回填;模型结构无变更", "config/config.default.js:frontConfig.certStagingDir 保留(注释已更新为「保存接口不再写暂存文件、证书内容直接入库,目录供未来定时任务部署使用」),无配置键变化", "methods/system.json:setting.warehouse.saveFrontCert 条目 params cert_pem→pem、key_pem→key(文案同步「pem/key 不能为空」与「pem|key 内容长度不能超过 65536 字符」);description 改为内容直接入库、cert_path/key_path 置空待定时任务回填、响应不含证书内容;errors 删除 500「证书暂存目录未配置(frontConfig.certStagingDir)或证书文件写入失败」分支,其余 400/403/409/500 文案按代码核实保留;response 15 字段结构不变;docMeta.version 0.3.99 -> 0.3.100,updatedAt 保持 2026-09-08;本变更记录写入 methods/changes/system.json 数组首位", "AI_METHOD_ROUTING.md:第 6 节自动扫描清单定向修正 systems/setting/warehouse.js 31→30(writeFrontConfigCertFiles 已从代码移除);systemMethods/setting/warehouse.js 6 个方法名不变,其余条目未动", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ] }, { "version": "2026.09.08-front-cert-config-split", "date": "2026-09-08", "type": "changed", "summary": "前端独立部署「证书上传」与「配置保存」拆分文档同步:新增 setting.warehouse.saveFrontCert 接口文档(证书上传:domain+cert_pem/key_pem 成对必填,校验链任一失败统一返回「证书不合法」400,通过后自动权威写入 cert_expire_at、证书内容落盘只存路径、清新旧 domain 公共拉取缓存);saveFrontConfig 入参瘦身为仅品牌字段 title/logo_url/favicon_url/login_bg_url/theme(domain/cert_pem/key_pem/cert_path/key_path/cert_expire_at 不再受理,前端传值被方法层白名单静默忽略,domain 变更必须走 saveFrontCert)。", "methods": [ "setting.warehouse.saveFrontCert", "setting.warehouse.saveFrontConfig" ], "module": "setting.warehouse", "notes": [ "app/service/systemMethods/setting/warehouse.js:新增 saveFrontCert 薄出口(透传 domain/cert_pem/key_pem,错误 code 透传);_noNeedRight/_noNeedAuth 增加 saveFrontCert(需登录、免权限、免鉴权,权限靠业务层 isWarehouse 判定);saveFrontConfig 方法层白名单收敛为 title/logo_url/favicon_url/login_bg_url/theme(domain/cert_path/key_path/cert_pem/key_pem/cert_expire_at 一律静默忽略)", "app/service/systems/setting/warehouse.js:saveFrontCert 校验链 parseFrontConfigCertPem(crypto.X509Certificate)→ assertFrontConfigCertValid(未生效/已过期 400)→ validateFrontConfigKeyPem(SPKI 公钥指纹比对,私钥无法解析/不匹配 400)→ collectFrontConfigCertNames/frontConfigCertCoversDomain(SAN DNS/CN 精确或 *.example.com 通配,不覆盖 400),所有证书校验失败统一文案「证书不合法」;domain 经 normalizeFrontConfigText(data.domain,'domain',100) 校验非空(400「domain 不能为空」)与超长(400「domain 长度不能超过 100 字符」);cert_pem/key_pem 必填(400「cert_pem 不能为空」「key_pem 不能为空」)且 ≤65536 字符(超长 400「{字段} 内容长度不能超过 65536 字符」);通过后 patch.domain/cert_path/key_path/cert_expire_at=new Date(cert.validTo)(权威值非入参)+ sync_status=0/sync_attempts=0/清空 last_sync_error/last_synced_at;writeFrontConfigCertFiles 落盘 frontConfig.certStagingDir({store_id}_{domain}.crt/.key,内容不入库只回传路径,暂存目录未配置或写入失败 500);assertFrontConfigDomainUnique 全局唯一(409「域名 {domain} 已被其他仓库使用」,并发唯一索引冲突兜底 409「仓库前端配置保存冲突,请稍后重试」);写库成功后清理旧 domain 与新 domain 的 front:config:domain:{*} 缓存(先写库后清缓存,清缓存失败仅日志)", "app/service/systems/setting/warehouse.js:saveFrontConfig 仅按 FRONT_CONFIG_TEXT_FIELDS(title/logo_url/favicon_url/login_bg_url)+ theme 组装 patch;不再受理 domain/cert_*;保存仍重置同步状态并清理当前 domain 公共拉取缓存;响应 buildFrontConfigOutput 15 字段(warehouse_id/domain/title/logo_url/favicon_url/login_bg_url/theme/cert_path/key_path/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at),getFrontConfig/frontConfig.getByDomain 无变化未改动", "methods/system.json:setting.warehouse 分组 list 末尾新增 saveFrontCert 条目(isNeedLogin=true、isNeedAuth=false、Authorization 头);saveFrontConfig 条目入参瘦身(移除 domain/cert_pem/key_pem/cert_path/key_path 入参说明,description 注明前端传值静默忽略)与 errors 修订(证书校验 400 统一文案「证书不合法」移至 saveFrontCert;保留 400/403/409 并发兜底/500);docMeta.version 0.3.98 -> 0.3.99,updatedAt 2026-09-07 -> 2026-09-08;本变更记录写入 methods/changes/system.json 数组首位", "AI_METHOD_ROUTING.md:按文件内维护说明执行第 6 节自动扫描清单刷新(node .\\script\\tmp-gen-service-method-inventory.cjs → node .\\script\\tmp-update-ai-method-routing.cjs),systemMethods/setting/warehouse.js 3→6、systems/setting/warehouse.js 12→31(以扫描结果为准)", "README.md / AI_TOOLBOX.md 无需同步:检索确认无 saveFrontConfig/saveFrontCert 相关描述", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ] }, { "version": "2026.09.07-front-config-independent-deploy", "date": "2026-09-07", "type": "changed", "summary": "仓库前端独立部署功能文档同步:新增 setting.warehouse.saveFrontConfig / setting.warehouse.getFrontConfig 与公共无鉴权接口 frontConfig.getByDomain 三个方法文档。保存配置支持上传 cert_pem/key_pem:后端解析证书并校验(无法解析/未生效/已过期/SAN-CN 不包含 domain/私钥不匹配报 400),自动权威写入 cert_expire_at(不再是入参,前端传值被忽略),证书内容落盘暂存目录、库内只存路径;纯路径模式(未提供 cert_pem)直接保存 cert_path/key_path 且不写有效期;保存即重置同步状态(sync_status=0、sync_attempts=0)。新增 favicon_url 字段(保存/查询/公共拉取均含)。公共拉取接口免登录、免鉴权、免权限(保留系统日志),响应仅 6 个公开字段(绝不返回证书路径/同步状态等内部字段),Redis 缓存 front:config:domain:{domain}(命中 TTL 600s、未登记域名空缓存 60s 防穿透、保存配置自动失效新旧域名缓存)。关联迁移 20260907150000(建表 wms_warehouse_front_config)与 20260907170000(favicon_url 列)。", "methods": [ "setting.warehouse.saveFrontConfig", "setting.warehouse.getFrontConfig", "frontConfig.getByDomain" ], "module": "setting.warehouse", "notes": [ "app/service/systemMethods/setting/warehouse.js:saveFrontConfig 方法层白名单仅透传 domain/title/logo_url/favicon_url/login_bg_url/theme/cert_path/key_path/cert_pem/key_pem(cert_expire_at 不入白名单,前端传值直接忽略);getFrontConfig 无入参;两方法均需登录、免权限(_noNeedRight 含 getFrontConfig,saveFrontConfig)、免鉴权(_noNeedAuth 含两方法),saveFrontConfig 权限由业务层 getCurrentSubject().isWarehouse 判定(非仓库主体 403「仅仓库主体可配置前端独立部署」)", "app/service/systemMethods/frontConfig.js:新模块 frontConfig(与 workbench/inbox 同级),getByDomain 配置 _noNeedLogin/_noNeedRight/_noNeedAuth='getByDomain'(免登录、免鉴权、免权限)、保留系统日志(_noNeedLog 为空);薄出口调用 systems.setting.warehouse.getFrontConfigByDomain,错误 code 透传(400/404/500)", "app/service/systems/setting/warehouse.js:saveFrontConfig upsert 一仓一行;domain 非空时 assertFrontConfigDomainUnique 全局唯一校验(409「域名 {domain} 已被其他仓库使用」,并发唯一索引冲突兜底转 409「仓库前端配置保存冲突,请稍后重试」);normalizeFrontConfigText 校验文本字段长度(domain/title≤100、logo_url/login_bg_url/favicon_url≤255、cert_path/key_path≤500);normalizeFrontConfigTheme 校验 theme 为合法 JSON 对象;normalizeFrontConfigPem 限制 PEM ≤65536 字符;提供 cert_pem 时 parseFrontConfigCertPem(crypto.X509Certificate)+ assertFrontConfigCertValid(未生效/已过期 400)+ collectFrontConfigCertNames/frontConfigCertCoversDomain(SAN DNS/CN 精确或 *.example.com 通配匹配,不含 domain 报 400)+ validateFrontConfigKeyPem(SPKI 公钥指纹比对),writeFrontConfigCertFiles 落盘暂存目录({store_id}_{domain}.crt/.key,只回传路径、内容不入库,旧暂存文件不主动删除);key_pem 单独提供报 400;未提供 cert_pem 时纯路径模式直接落库、cert_expire_at 允许为空;保存即 patch.sync_status=0/sync_attempts=0 并清空 last_sync_error/last_synced_at;写库成功后清理新旧 domain 公共拉取缓存(先写库后清缓存,清缓存失败仅日志不影响保存)", "app/service/systems/setting/warehouse.js:getFrontConfig 按 getCurrentWarehouseId()(ctx.user.store_id,未识别报 400「未识别到当前仓库,无法操作仓库设置」)查询 wms_warehouse_front_config,无记录返回 buildFrontConfigOutput 默认空配置(15 字段:warehouse_id/domain/title/logo_url/favicon_url/login_bg_url/theme/cert_path/key_path/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at)", "app/service/systems/setting/warehouse.js:getFrontConfigByDomain 校验 domain 必填非空(400「domain 不能为空」)且 ≤100 字符(400「domain 长度不能超过 100 字符」);Redis key front:config:domain:{domain},配置命中缓存 TTL 600s(FRONT_CONFIG_PUBLIC_CACHE_TTL_SECONDS),未登记域名写 {configured:false} 空缓存 TTL 60s(FRONT_CONFIG_PUBLIC_MISS_CACHE_TTL_SECONDS)防穿透并返回 404「域名未配置」;响应仅 FRONT_CONFIG_PUBLIC_FIELDS 白名单 6 字段(domain/title/logo_url/login_bg_url/favicon_url/theme),绝不返回 cert_path/key_path/sync_status/sync_attempts/last_sync_error 等内部字段;Redis 读异常降级查库、写异常仅日志", "app/model/warehouse_front_config.js:wms_warehouse_front_config 单表一仓一行(uk_store_id 唯一、uk_domain 可空列唯一索引允许多 NULL,非空唯一性靠应用层校验),字段含 domain/title/logo_url/favicon_url/login_bg_url/theme/cert_path/key_path/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at;不启用 paranoid,无 deleted_at", "数据库迁移:database/migrations/20260907150000-create-wms-warehouse-front-config.js(建表 wms_warehouse_front_config 及索引)、database/migrations/20260907170000-add-favicon-url-to-wms-warehouse-front-config.js(新增 favicon_url 列)", "methods/system.json:setting.warehouse 分组 list 末尾新增 saveFrontConfig/getFrontConfig 条目(isNeedLogin=true、isNeedAuth=false、Authorization 头);新增 frontConfig 分组(groupName 前端独立部署模块)与 frontConfig.getByDomain 条目(isNeedLogin=false、isNeedAuth=false、headers 为空,免登录免鉴权免权限);docMeta.version 0.3.97 -> 0.3.98,updatedAt 保持 2026-09-07;本变更记录写入 methods/changes/system.json 数组首位", "README.md / AI_TOOLBOX.md / AI_METHOD_ROUTING.md 无需同步:检索确认无前端独立部署配置相关行为描述(AI_METHOD_ROUTING.md 为函数清单由扫描脚本维护,本任务未执行扫描,如需刷新可另行执行)", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ] }, { "version": "2026.09.07-ai-method-routing-service-inventory-refresh", "date": "2026-09-07", "type": "changed", "summary": "AI_METHOD_ROUTING.md 第 6 节「全量 Service Method 能力清单」按项目维护脚本重新扫描刷新:receiving_entry_match.js 由 12 个函数更新为 27 个(补齐台账/防超扣链路的 _bindReceivingsWithStorageSync、_bindOneReceivingAndSyncStorage、_syncReceivingStorageByEntryItems、_parseLedgerMap、_serializeLedgerMap、_buildLegacyBaselineLedger、_bindingAllocationByStock、_recalcReceivingStorageStatus、_reconcileEntryReceivedQuantity、recordLedgerAllocation、setLedgerAllocation、rollbackEntryOrderBindings、_rollbackOneBindingStorage 等),并同步刷新 workbench.js(52→61)、express_platform.js(16→17)、intercept_auto_confirm.js(新增)等存量漂移条目;本节内容由自动扫描脚本生成,仅函数清单、无接口行为描述。", "methods": [ "storage.entry.bindReceiving", "storage.entry.unbindReceiving", "storage.entry.cancel", "storage.entry.commit", "storage.entry.quickInbound" ], "notes": [ "本记录是对 2026.09.07-entry-receiving-binding-allocated-quantity-ledger 同任务的补充记录:该记录撰写时判定 AI_METHOD_ROUTING.md 无需同步,随后按文件内维护说明执行刷新脚本同步了第 6 节自动扫描清单(本任务涉及 receiving_entry_match.js 新增 13 个台账/防超扣相关方法)", "刷新方式:node .\\script\\tmp-gen-service-method-inventory.cjs(扫描 app/service/**/*.js 输出 temp/tmp-service-method-inventory.md)→ node .\\script\\tmp-update-ai-method-routing.cjs(注入 AI_METHOD_ROUTING.md 第 6 节 BEGIN/END 标记内),自动生成时间 2026-09-06 → 2026-09-07、文件数 203 → 204", "生成器按类方法扫描,个别内置标识符(如 max、min、Set、Date、NOW)会被一并列出为方法名,属于既有生成器口径,非手工修改", "methods/system.json 无实质变化:本次 spec 复用 storage.entry.unbindReceiving 现有条目内容,upsert 为无差异重写;接口行为、参数、响应、错误码均不变", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ], "module": "storage.entry" }, { "version": "2026.09.07-entry-receiving-binding-allocated-quantity-ledger", "date": "2026-09-07", "type": "changed", "summary": "入库单绑定收货单链路防超扣修复文档同步:wms_entry_order_receiving 新增 allocated_quantity 数量台账列(JSON,收货明细ID→分配数量,迁移 20260907160000 仅基表);storage.entry.bindReceiving COMPLETED 绑定改为台账制归一化分配(每 SKU 分配目标 = min(入库单计划数 − 其他绑定已占用, 收货单剩余可入量),多退少补、旧超分数据回收、重复绑定幂等跳过、软删恢复仅分配剩余量),并同步 entry_items.received_quantity 口径;新增 storage.entry.unbindReceiving 接口文档(解绑按台账回滚 stored_quantity、重算 storage_status、清空台账,响应新增 rolled_back_quantity);storage.entry.cancel 作废回滚改台账制逐绑定回收(不再整体清零共享收货单);storage.entry.commit / storage.entry.quickInbound 分别按覆写/累计语义同步台账。", "methods": [ "storage.entry.bindReceiving", "storage.entry.unbindReceiving", "storage.entry.cancel", "storage.entry.commit", "storage.entry.quickInbound" ], "notes": [ "app/model/entry_order_receiving.js 新增 allocated_quantity 列(JSON 可空,comment 数量台账:收货明细ID→已分配数量(JSON对象,如 {\"123\":8});null 表示旧数据未初始化);数据库迁移 database/migrations/20260907160000-add-allocated-quantity-to-wms-entry-order-receiving.js 仅基表(describeTable 幂等检测)", "app/service/systems/receiving_entry_match.js _syncReceivingStorageByEntryItems(方案A台账版):FOR UPDATE 行锁入库单主行 + 该入库单全部未删除绑定行 + 绑定收货单明细行,串行化同一入库单的分配事务;每 SKU 分配目标 target = min(max(0, 入库单计划数 − 其他绑定已分配), 当前绑定已分配 + 收货单剩余可入量),多退少补(旧数据超分回收、亏分补分配);明细级结果回写绑定行台账 allocated_quantity,重算收货单主表 storage_status,并经 _reconcileEntryReceivedQuantity 同步 entry_items.received_quantity;返回的 storage_sync.stored_total 仅计补分配量(归一化回收不计入)", "幂等/恢复语义:绑定已存在且未删除 → skipped(error_code=ALREADY_BOUND,不重复分配);已软删除 → restore 后按归一化目标仅分配剩余量(restored=true);并发唯一索引冲突按已绑定跳过。旧绑定行(台账 null)由 _buildLegacyBaselineLedger 按收货侧累计量兜底重建明细级台账,新链路绑定行台账初始化为 {}(非 null)", "新增 unbindEntryOrderReceiving(对应 storage.entry.unbindReceiving):仅 CREATED / PENDING 可解绑(COMPLETED / CANCELLED 拒绝),解绑不回退入库单状态;事务内行锁后按台账逐明细回收该收货单 stored_quantity、重算明细与主表 storage_status、台账重置为 {},软删除主表绑定与关联明细绑定(InboundDirectLog status=committed 且 receiving_detail_id 非空的记录);返回 success/failed/success_count/failed_count,success 项含 released_detail_ids / released_detail_count / rolled_back_quantity(本次回滚的 stored_quantity 总量,无可回滚量为 0);不影响同一收货单上其他入库单的占用", "app/service/systems/storage/entry.js cancel → _rollbackReceivingStorageStatus → rollbackEntryOrderBindings(receivingId=null、softDeleteBinding=false):按台账逐绑定回收、清空台账(绑定行保留)、重算 received_quantity;回滚失败仅日志不阻塞作废主流程;QM 来源入库单作废前先发送奇门取消同步,sync_status=SUCCESS 不可取消", "app/service/systems/inbound_direct_log.js commit 绑定模式 _syncReceivingStorageStatus → receivingEntryMatch.setLedgerAllocation(按 committed 汇总量覆写台账条目);app/service/systems/storage/entry.js quickInbound _applyReceivingInboundUsage → receivingEntryMatch.recordLedgerAllocation(按本次落到收货明细的分配量累计台账)。说明:receiving_entry_match._commitBinding(PDA 明细绑定)内部调用 recordLedgerAllocation,但当前无调用方(实际 addItem 绑定走 inboundDirectLog._bindReceivingDetail),本次按实际生效链路记录,addItem 文档不改动", "methods/system.json:storage.entry.bindReceiving 条目 description/storage_sync.stored_total 说明按台账归一化语义更新;新增 storage.entry.unbindReceiving 条目(按脚本规则追加到 storage.entry 组列表末尾);storage.entry.cancel / commit / quickInbound 描述补充台账行为;cancel errors 补充「入库单已完成回传,不可取消」;版本 0.3.96 -> 0.3.97(docMeta.version),updatedAt 保持 2026-09-07", "README.md / AI_TOOLBOX.md / AI_METHOD_ROUTING.md 检索确认:无本链路行为描述(AI_METHOD_ROUTING.md 仅函数清单,无行为描述),无需同步", "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ], "module": "storage.entry" }, { "version": "2026.09.07-entry-bindReceiving-completed-storage-sync", "date": "2026-09-07", "type": "changed", "summary": "storage.entry.bindReceiving 契约变更:可绑定状态由 CREATED/PENDING 调整为 CREATED/COMPLETED;COMPLETED 绑定在事务内联动同步收货单入库进度(SKU 级累加 stored_quantity、重算明细与主表 storage_status);绑定已存在时幂等跳过不重复累加、软删除恢复后执行同步;返回结构由 success/failed/success_count/failed_count 修正为实际返回的 bound/skipped/summary,并在 COMPLETED 结果中新增 restored 与 storage_sync(含 unmatched_items)。", "methods": [ "storage.entry.bindReceiving" ], "notes": [ "app/service/systems/receiving_entry_match.js bindEntryOrderReceiving:ALLOWED_BIND_STATUSES = [CREATED, COMPLETED],其他状态抛错「入库单状态不允许绑定,当前状态: {status},仅 CREATED、COMPLETED 状态可操作」;收货单校验含 存在未删除、同仓库、同货主、未取消、已审核(is_review)", "COMPLETED 路径新增 _bindReceivingsWithStorageSync / _bindOneReceivingAndSyncStorage / _syncReceivingStorageByEntryItems:事务内逐收货单主表绑定 + 入库明细按 stock_id(≡ wms_receiving_detail.system_product_id)汇总,FOR UPDATE 行锁后逐明细累加 stored_quantity(上限 actual_quantity),按 stored vs actual 重算明细 storage_status(none/partial/all)并汇总更新收货单主表 storage_status;SKU 未匹配明细汇总进 unmatched_items;任一异常整体回滚", "幂等语义:绑定已存在且未删除 → skipped(error_code=ALREADY_BOUND,不重复累加);已软删除 → restore 并执行进度同步(restored=true);并发唯一索引冲突 → 按已绑定跳过", "methods/system.json:storage.entry.bindReceiving 条目 description/errors 按代码更新;response 由 success/failed/success_count/failed_count 修正为实际返回的 flag/code/message/bound/skipped/summary/timestamp(bound 项 CREATED 含 receiving_id/receiving_number/created,COMPLETED 新增 restored 与 storage_sync.stored_total/matched_item_count/unmatched_items;skipped 项 error_code 枚举 ALREADY_BOUND/BINDING_WRITE_FAILED;收货单校验失败不返回明细、仅 summary.skipped_count 计数);错误码同步为实际文案(抛错经 /system 全局异常处理返回 500「接口错误: ...」);版本 0.3.95 -> 0.3.96(docMeta.version),updatedAt 保持 2026-09-07", "README.md / AI_TOOLBOX.md / AI_METHOD_ROUTING.md 检索确认:无本接口状态规则描述(AI_METHOD_ROUTING.md 仅函数清单,无行为描述),无需同步", "本次仅同步文档,未修改任何业务代码" ], "module": "storage.entry" }, { "version": "2026.09.07-store-openAccount-remove-logo-url-domain", "date": "2026-09-07", "type": "changed", "summary": "storeWarehouse.store.openAccount 入参移除 logo_url、domain 两个可选参数:wms_store 表的 logo_url、domain 字段已废弃(代码写入链路已移除、数据库已执行删列迁移 20260907140000-drop-logo-url-and-domain-from-wms-store),文档同步删除这两个可选 body 入参对象;字段无业务承载,前端若仍传参会被忽略,不破坏响应结构。", "methods": [ "storeWarehouse.store.openAccount" ], "notes": [ "database/migrations/20260907140000-drop-logo-url-and-domain-from-wms-store.js:删除 wms_store 表的 logo_url、domain 两列(开发库已执行完成)", "代码写入链路(openAccount 创建货主)已由开发 agent 移除 logo_url、domain 写入,app/ 下无 logo_url 残留引用", "methods/system.json:storeWarehouse.store.openAccount 的 params 删除 logo_url(name logo_url、type string、required false、source body、description Logo 链接)与 domain(name domain、type string、required false、source body、description 绑定域名)两个可选 body 入参对象;其余 17 个入参、response(store_id/account_id/contract_id/company_name/username/role_id)与 errors 均不变;版本 0.3.94 -> 0.3.95(docMeta.version),updatedAt 保持 2026-09-07", "影响说明:字段已无业务承载,前端若仍传参会被忽略;响应结构不变,无错误码、鉴权方式、公共请求头变化", "methods/ 全目录检索确认:logo_url、Logo 链接、绑定域名 仅存在于 methods/system.json 本方法参数块,无其他文件或方法残留引用", "本次仅同步文档,未修改任何代码、迁移脚本或数据库" ], "module": "storeWarehouse.store" }, { "version": "2026.09.07-order-delivery-dispatch-dispath-time", "date": "2026-09-07", "type": "changed", "summary": "配送表 wms_order_delivery_{wh}_dispatch 新增 dispath_time 字段(DATETIME 可空无默认值,comment 订单迁移进配送表的时间),用于记录订单从待处理表迁移进配送表的时刻:模型 dispatch 分支新增字段定义,出库迁移 buildDispatchRow 写入 new Date(),迁移脚本覆盖全部配送分表;仅配送表独有(基表/current/history/outsourced 不涉及),无接口入参/响应结构变化。", "methods": [ "order.manualOutboundOrder" ], "notes": [ "database/migrations/20260907120000-add-dispath-time-to-order-delivery-dispatch.js:为库内全部配送分表 wms_order_delivery_{wh}_dispatch 增加 dispath_time 列(DATETIME 可空无默认值,comment 订单迁移进配送表的时间),仅配送表独有、不加基表/current/history/outsourced 分表;describeTable 幂等检测,列已存在则跳过;开发、生产均已执行。", "app/model/order_delivery_table_schema.js buildTableAttributes:dispatch 分支新增 dispath_time 字段定义(Sequelize DATE / allowNull=true / comment 订单迁移进配送表的时间),与既有 dispatch_lane 并列,仅 dispatch 分表生效。", "app/service/systems/order_delivery_migration.js buildDispatchRow:写入配送表行时追加 dispath_time = new Date()(订单迁移进配送表的时刻),源表数据不受影响;保留先删除源行 dispatch_lane、再统一写 DISPATCH_LANE 的既有逻辑。", "methods/system.json:order.manualOutboundOrder description 补充「迁移写入配送表的订单行记录 dispath_time(buildDispatchRow 写入 new Date(),仅配送表独有)」说明;errors 由 description 键规范化为 message 键(文案不变,满足更新脚本 schema);版本 0.3.93 -> 0.3.94(docMeta.version),updatedAt 更新为 2026-09-07。", "无接口入参/响应结构/错误码/鉴权变化;配送表整行 raw 响应(order.pendingOrder.detail 订单头、order.list 列表行等)文档均为 raw 行引用而非全量字段清单,按既有口径不硬加字段说明,仅在本变更记录体现。", "AI_METHOD_ROUTING.md(函数清单,无配送表字段清单章节)与 AI_TOOLBOX.md(无配送表字段相关内容)均无需同步;README.md 与 docs/*.md 亦无配送表字段清单章节。", "发布版本 v1.0.0-20260907164410-c5150bc(2026-09-07 发布);本次仅同步文档,未修改任何代码、迁移脚本或数据库。" ], "module": "order.index" }, { "version": "2026.09.06-workbench-resetLoginCode-reset-token", "date": "2026-09-06", "type": "changed", "summary": "workbench.resetLoginCode 行为变更:重置登录码时同步重置工作台 token。生成新 64 位 hex token 与 login_code 一并持久化到 wms_workbench(record.update({ login_code, token }));更新库前先删除旧 workbench:token:{旧token} 缓存,旧 token 随即失效;立即回填新 token 信息缓存(复用 buildWorkbenchTokenInfo,含 members/current_wave/current_orders,TTL 300s);返回值新增 token 字段 { id, login_code, token },出口层展开后响应顶层含 id、login_code、token;旧行为「token 不变」相关描述已更新。旧 token 失效后旧会话返回 403,设备端需用新 token 继续工作。", "methods": [ "workbench.resetLoginCode" ], "notes": [ "app/service/systems/workbench.js:resetLoginCode(id) 同步重置 token:generateUniqueWorkbenchLoginCode 生成新 login_code、generateWorkbenchToken 生成新 64 位 hex token,先 delCacheAsync 删除旧 workbench:token:{旧token} 缓存(旧 token 随即失效),再 record.update({ login_code, token }) 一并持久化,随后 setCacheAsync 立即回填新 token 信息缓存(buildWorkbenchTokenInfo,含 members/current_wave/current_orders,TTL 300s),返回 { id, login_code, token }", "app/service/systemMethods/workbench.js:resetLoginCode 薄出口 this.success('重置成功', result) 展开后响应顶层含 id、login_code、token(原仅 id/login_code,本次新增 token)", "methods/system.json:workbench.resetLoginCode 条目 description 更新(说明 login_code 与 token 同步重置、旧 token 缓存删除使旧 token 随即失效、立即回填新 token 缓存),response 新增 token 字段(string,64 位 hex,必返回),errors 补充 403 备注(旧 token 失效后旧会话返回 403,设备端需用新 token 继续工作);版本 0.3.92 -> 0.3.93(docMeta.version),updatedAt 保持 2026-09-06", "AI_METHOD_ROUTING.md:路由与方法清单无变化(5.3 节映射表与函数清单均未涉及行为描述),无需同步", "本次任务仅同步文档,未修改任何业务代码" ], "module": "workbench" }, { "version": "2026.09.06-workbench-queryOrder", "date": "2026-09-06", "type": "changed", "summary": "工作台模块新增免登录/免权限/免鉴权的 token 自校验只读接口 workbench.queryOrder(条码查询订单):入参 token(必填)+ barcode(必填),仓库与工作台均由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值,防止跨仓库查单);响应 data 与 business(queryOrder) 分支一致(barcode/waybill_code/isSandan/store_remark/express/order/items/source_table,散单 order 附 intercept_flag/pack_flag 0/1 标志、团购附 batch 波次总量信息);只读查询不涉及缓存失效;错误码沿用统一口径:无 token 401、token 无效 403、工作台未绑定有效仓库 403,条码为空/未找到运单/未找到订单为业务失败(flag=failure、code=0)。", "methods": [ "workbench.queryOrder" ], "notes": [ "app/service/systemMethods/workbench.js:新增 queryOrder 薄出口(调用业务层 queryOrderByToken),systemInit 免登录/免权限/免鉴权白名单均已包含 queryOrder(未声明免日志,保留系统日志)", "app/service/systems/workbench.js:新增 queryOrderByToken(data):走 resolveWorkbenchContext(token) 统一 token 校验(无 token 401、token 无效 403),解析成功后从 ctx.workbenchWarehouseId 注入仓库(工作台未绑定有效仓库返回 403),复用 _queryOrder 业务实现;只读查询,不涉及缓存失效", "methods/system.json:工作台模块新增 workbench.queryOrder 条目(isNeedAuth=false、isNeedLogin=false、isNeedRight=false,入参仅 token/barcode,description 说明 warehouse_id/workbench_id 由服务端注入);版本 0.3.91 -> 0.3.92(docMeta.version),updatedAt 保持 2026-09-06", "AI_METHOD_ROUTING.md 5.3 节新增 queryOrder 映射行与接口说明;本次任务仅同步文档,未修改任何业务代码" ], "module": "workbench" }, { "version": "2026.09.06-workbench-pack-order-finish-pack-send-weight", "date": "2026-09-06", "type": "changed", "summary": "工作台模块新增 3 个免登录/免权限/免鉴权的 token 自校验接口 workbench.packOrder(打包上报)、workbench.finishPack(打包完成)、workbench.sendWeight(称重上报,重量单位克),并统一公共 token 校验口径:新增 resolveWorkbenchContext(token) 公共校验方法(解析成功写入 ctx.workbenchToken/ctx.workbenchId/ctx.workbenchWarehouseId),无 token 统一返回 code=401(消息「工作台 token 不能为空」)、token 无效/工作台不存在保持 403;受影响的 workbench.getWorkbenchInfo/workbench.bindMember/workbench.removeMember 三个接口「无 token」错误码由 400 调整为 401,bindMember/removeMember 校验顺序变为 token 优先(token 无效且参数缺失的边界场景由 400 变 403)。", "methods": [ "workbench.packOrder", "workbench.finishPack", "workbench.sendWeight", "workbench.getWorkbenchInfo", "workbench.bindMember", "workbench.removeMember" ], "notes": [ "app/service/systemMethods/workbench.js:新增 packOrder/finishPack/sendWeight 三个薄出口(调用业务层 packOrderByToken/finishPackByToken/sendWeightByToken),systemInit 免登录/免权限/免鉴权白名单均已包含三个方法(未声明免日志,保留系统日志)", "app/service/systems/workbench.js:新增公共 token 校验方法 resolveWorkbenchContext(token):无 token 统一返回 401(消息「工作台 token 不能为空」),token 无效/工作台不存在(含软删除)返回 403(保持原口径);解析成功后写入 ctx.workbenchToken/ctx.workbenchId/ctx.workbenchWarehouseId 供后续方法使用(按仓库限定查询/写入,禁止跨仓库)", "新增 packOrderByToken/finishPackByToken/sendWeightByToken:仓库/工作台均由 token 解析上下文注入(body 传入 warehouse_id/workbench_id 被忽略),复用 _packOrder/_finishPack/_sendWeight 业务实现;打包/称重状态变更后失效对应工作台 token 缓存,保证 getWorkbenchInfo 及时返回最新信息", "行为变更:workbench.getWorkbenchInfo/workbench.bindMember/workbench.removeMember 无 token 时错误码由 400 调整为 401;bindMember/removeMember 校验顺序变为 token 优先(token 无效且参数缺失的边界场景由 400 变 403)", "methods/system.json:工作台模块新增 workbench.packOrder/workbench.finishPack/workbench.sendWeight 三条目(isNeedAuth=false、isNeedLogin=false、isNeedRight=false),并更新 workbench.getWorkbenchInfo/workbench.bindMember/workbench.removeMember 错误码(400→401);版本 0.3.90 -> 0.3.91(docMeta.version),updatedAt 保持 2026-09-06", "AI_METHOD_ROUTING.md 5.3 节新增三个接口映射行与 401 口径说明;本次任务仅同步文档,未修改任何业务代码" ], "module": "workbench" }, { "version": "2026.09.06-workbench-getWorkbenchInfo-wave-items-total", "date": "2026-09-06", "type": "changed", "summary": "workbench.getWorkbenchInfo 响应 data.current_wave 新增 items_total 字段(number):波次商品总件数,口径为商品总件数(非 SKU 品种数),来源为订单分表 wms_order_delivery_{仓库}_{current/dispatch} 的 items_total 列按 wave_id+warehouse_id 求和(与既有 order_count 同款分表口径),带 15s 短缓存兜底;current_wave 其余字段(task_id/wave_id/wave_no/status/order_count/operator_text/start_time)不变,无团购任务时 current_wave 仍为空对象;items_total 随 token 缓存 workbench:token:{token}(TTL 300s)一并缓存,packOrder/finishPack 打包状态变更后主动失效缓存,下一次调用即返回最新数据。", "methods": [ "workbench.getWorkbenchInfo" ], "notes": [ "app/service/systems/workbench.js:新增 _sumWaveItemsTotal(并发遍历 current+dispatch 分表 SUM(items_total),按 wave_id+warehouse_id 过滤,单表失败按 0 处理)与 _sumWaveItemsTotalCached(cache:workbench:wave_items_total:{warehouseId}:{waveId},TTL 15s,缓存不可用降级实时统计);buildCurrentPackingInfo 组装 current_wave 时通过 Promise.all 并行统计 order_count 与 items_total,current_wave 新增 items_total 字段", "getWorkbenchInfoByToken 缓存优先(workbench:token:{token},TTL 300s),缓存值已包含 items_total;_packOrder/_finishPack 打包状态变更后调用 invalidateWorkbenchTokenCacheByWorkbenchId 删除 token 缓存,保证下一次 getWorkbenchInfo 返回最新打包信息", "methods/system.json:workbench.getWorkbenchInfo description 与 current_wave 对象描述补充 items_total 说明,response 新增 current_wave.items_total 条目(沿用 current_wave.xxx 嵌套命名惯例);版本 0.3.89 -> 0.3.90(docMeta.version),updatedAt 保持 2026-09-06", "AI_METHOD_ROUTING.md 5.3 节接口文档行追加本变更记录版本号,当前打包信息行补充 items_total 口径;AI_TOOLBOX.md 无 workbench 相关内容,无需同步", "本次任务仅同步文档,未修改任何业务代码" ], "module": "workbench" }, { "version": "2026.09.06-workbench-getWorkbenchInfo-current-packing", "date": "2026-09-06", "type": "changed", "summary": "workbench.getWorkbenchInfo 响应 data 新增当前正在打包的波次与订单信息:current_wave(当前正在打包的团购波次:wms_pack_task 中 pack_mode=2 且 wave_id>0 的最新一条未结束任务(status<2)组装,无团购任务时为空对象,含 task_id/wave_id/wave_no/status/order_count/operator_text/start_time,order_count 为 15s 短缓存实时计数)与 current_orders(当前正在打包的订单数组:全部未结束任务按 id 倒序,逐单按 current→dispatch 分表补发货单号,无进行中任务时为空数组,每项含 task_id/order_id/delivery_order_code/wave_id/wave_no/pack_mode/status/pack_quantity/operator_text/start_time);打包信息随 token 缓存 workbench:token:{token}(TTL 300s)一并缓存,packOrder/finishPack 打包状态变更后主动失效缓存,下一次调用即返回最新数据;打包信息查询异常时降级(current_wave 空对象、current_orders 空数组),不影响主信息与 members。", "methods": [ "workbench.getWorkbenchInfo" ], "notes": [ "app/service/systems/workbench.js:新增 listCurrentPackTasks(wms_pack_task 按 workbench_id/warehouse_id 过滤 status<2(0=待处理/1=打包中),按 id 倒序)与 buildCurrentPackingInfo(组装 current_wave/current_orders:逐单按 current→dispatch 分表补 delivery_order_code;current_wave 取最新一条 pack_mode=2 且 wave_id>0 的未结束任务,order_count 走 _countWaveOrdersCached 实时计数 + 15s 短缓存;任一环节异常降级为空对象/空数组);buildWorkbenchTokenInfo 统一组装主表字段 + members + 打包信息", "getWorkbenchInfoByToken 缓存优先(workbench:token:{token},TTL 300s),缓存值同样含打包信息;_packOrder/_finishPack(workbench.business packOrder/finishPack 调度)打包状态变更后调用 invalidateWorkbenchTokenCacheByWorkbenchId 删除 token 缓存,保证下一次 getWorkbenchInfo 返回最新打包中信息", "methods/system.json:workbench.getWorkbenchInfo description 补充 current_wave/current_orders 与缓存失效行为说明,response 新增 current_wave/current_wave.* 与 current_orders/current_orders[].* 条目;版本 0.3.88 -> 0.3.89(docMeta.version),updatedAt 保持 2026-09-06", "AI_METHOD_ROUTING.md 5.3 节接口文档行追加本变更记录版本号;AI_TOOLBOX.md 无 workbench 相关内容,无需同步", "本次任务仅同步文档,未修改任何业务代码" ], "module": "workbench" }, { "version": "2026.09.06-workbench-getWorkbenchInfo-members", "date": "2026-09-06", "type": "changed", "summary": "workbench.getWorkbenchInfo 响应 data 新增 members 成员数组:成员来自副表 wms_workbench_member 未软删除记录(按 id ASC),元素含 id/user_id/user_name(轻量结构);接口 token 缓存 workbench:token:{token}(TTL 300s)缓存值已包含 members,绑定/移除成员后缓存立即失效,下一次调用即返回最新成员;主表字段与不含 token/login_code 口径不变。", "methods": [ "workbench.getWorkbenchInfo" ], "notes": [ "app/service/systems/workbench.js:buildWorkbenchTokenInfo 统一组装主表字段(formatWorkbenchTokenInfo:id/warehouse_id/name/status/type/remark/device_ids/created_at/updated_at,不含 token/login_code)+ members(listWorkbenchMembers 查 wms_workbench_member 未软删除记录,attributes id/user_id/user_name,按 id ASC;查询失败降级空数组)", "getWorkbenchInfoByToken 缓存优先(workbench:token:{token},TTL 300s)、查库兜底回填缓存;removeWorkbenchMember/bindWorkbenchMember 成功后 delCacheAsync 清除 token 信息缓存,保证下一次调用立即反映最新成员", "methods/system.json:workbench.getWorkbenchInfo description 补充 members 与缓存行为说明,response 新增 members/members[].id/members[].user_id/members[].user_name 条目;版本 0.3.87 -> 0.3.88(docMeta.version),updatedAt 保持 2026-09-06", "AI_METHOD_ROUTING.md 5.3 节接口文档行追加本变更记录版本号;AI_TOOLBOX.md 无 workbench 相关内容,无需同步", "本次任务仅同步文档,未修改任何业务代码" ], "module": "workbench" }, { "version": "2026.09.06-index.queryUserByToken", "date": "2026-09-06", "type": "added", "summary": "基础模块新增 index.queryUserByToken:按 ye4s 登录临时码 token 查询用户信息(免登录、免鉴权),命中返回 flag=success、code=200 与 real_name、wms_account_id,未命中返回 code=404 用户不存在,数据库异常返回 code=500。", "methods": [ "index.queryUserByToken" ], "notes": [ "app/service/systemMethods/index.js 新增 queryUserByToken:入参 token(ye4s 登录临时码,对应 ye4s 库 ye4s_user 表 tmp_code 字段),为空返回 code 400「token 不能为空」;命中返回 success + real_name(空串兜底)/wms_account_id(null 兜底),未命中返回 code 404「用户不存在」,异常返回 code 500", "免登录、免鉴权:queryUserByToken 已加入 _noNeedLogin / _noNeedAuth 白名单(systemInit 声明)", "methods/system.json:基础模块(module=index)新增 index.queryUserByToken 条目(isNeedAuth=false、isNeedLogin=false);版本 0.3.86 -> 0.3.87(docMeta.version),updatedAt 保持 2026-09-06", "本次任务仅同步文档,未修改任何业务代码" ], "module": "index" }, { "version": "2026.09.06-recheckOrder.remove-unprinted-intercepted", "date": "2026-09-06", "type": "enhanced", "summary": "复核链路新增自动清理:更新复核状态后,自动将波次内「已拦截且未打印」的订单移除出波次(回池),拦截解除后可重新抓取发货,避免拦截订单卡死波次完成判定。", "methods": [ "order.recheckOrder.confirmRecheck", "order.recheckOrder.batchQuickRecheck", "order.recheckOrder.batchQuickRecheckByWave" ], "notes": [ "app/service/systemMethods/order/recheckOrder.js 新增 removeUnprintedInterceptedOrdersFromWave:移除波次内 print_status='none' 且 intercept_status!='none'(空值按 none 处理)的订单(wave_id=0、wave_no/wave_strategy_version/wave_scan_result 清空),调用 wave.deleteOrderWaveIndexByOrderIds 删波次索引,删除 wms_wave_pick_task_order 任务订单关联,回写 wms_wave_batch total_orders/processed_orders 统计,写 ORDER_WAVE_REMOVE 操作日志,并触发 enqueueWaveStrategyQuickScanPostOrderChange 波次策略快扫(拦截未解除时策略仍排除,不会误抓)", "三个复核入口接入:updateTaskOrderReviewAndTryUnbindCart(confirmRecheck 单订单)、updateTaskOrdersReviewBatch(批量/团购)、_updateTaskOrderReviewInTransaction(batchQuickRecheck/batchQuickRecheckByWave 事务版,清理动作随事务执行并透传事务对象);清理失败仅记录 warn 日志,不影响复核主流程", "清理先于任务/波次完成判定执行,拦截订单移除后完成判定口径自然收敛,未改动既有完成判定 SQL;清理以 wave_id>0 为条件,幂等可重复触发", "已打印(print_status!='none')的拦截订单保持不动,避免已贴面单实物与波次记录分离;该类订单仍需人工 wave.batchRemoveOrders 处理", "单元测试:test/app/service/systemMethods/order/recheckOrder.removeUnprintedIntercepted.test.js(8 用例全通过,ESLint 0/0)" ], "module": "order.recheckOrder" }, { "version": "2026.09.06-stock.report.exportStore-lock-exclusion", "date": "2026-09-06", "type": "updated", "summary": "stock.report.exportStore(货主侧库存报表导出)变更记录口径收紧:变更记录 sheet 只导出出入库流水(INBOUND/OUTBOUND),锁定/解锁(LOCK/UNLOCK)记录一律不导出;export_mode/exportMode 参数对货主侧不再有任何效果(该参数仅仓库侧 stock.report.export 生效)。", "methods": [ "stock.report.exportStore", "stock.report.export" ], "notes": [ "app/service/systems/storage/report.js export():isStoreMode(货主侧)分支固定追加 t.transaction_type NOT IN ('LOCK','UNLOCK'),无视 exportMode;仓库侧维持 export_mode='item' 时含 LOCK、否则排除 LOCK 的既有行为", "methods/system.json:stock.report.exportStore 移除 export_mode/exportMode 参数条目,method description 补充“变更记录只含出入库流水(LOCK/UNLOCK 不导出)”与“export_mode/exportMode 不支持也不生效”;stock.report.export 的 export_mode 参数描述标注“仅仓库侧接口生效”,method description 补充“仓库侧”;版本 0.3.85 -> 0.3.86(docMeta.version),updatedAt 保持 2026-09-06", "本次任务仅同步文档,未修改任何业务代码" ], "module": "stock.report" }, { "version": "2026.09.06-order.list.waveScope", "date": "2026-09-06", "type": "updated", "summary": "order.list 订单列表 where 新增 wave_scope 波次范围虚拟筛选字段(订单表 wave_scope 字段直接过滤)", "methods": [ "order.list" ], "notes": [ "订单表(wms_order_delivery 与各仓库 current/history/dispatch/outsourced 分表)新增 wave_scope 字段:tinyint NOT NULL DEFAULT 0,取值 0=未分配波次 1=大团购 2=散单 3=小团购 4=单品单件。", "波次生成写入订单表时同步维护 wave_scope(app/service/systemMethods/order/wave.js resolveWaveScopeByWaveMeta):大团购=wave_type=1&source=0,小团购=wave_type=1&source=2,单品单件=wave_type=2&pickMode=2(策略 batch_mode=1),其余有波次为散单;移出波次重置为 0。", "order.list / 订单导出 where.wave_scope 直接按订单表 wave_scope 字段过滤(app/service/systemMethods/order/base.js buildWaveScopeFilterCondition),不再反查 wms_wave_batch 波次ID;支持单个值、数组多选与 { operator: in, value: [...] } 结构,非法值(非 0-4 整数)返回 400。", "数据库迁移:database/migrations/20260905100000-add-wave-scope-to-order-delivery.js(加列)、database/migrations/20260905130000-backfill-order-wave-scope.js(存量按口径回填,幂等)。", "列表响应 raw 行暂不输出 wave_scope 字段(ORDER_LIST_BASE_ATTRIBUTES 未包含),仅作为筛选条件使用。" ], "module": "order" }, { "version": "2026.09.05-storageTransaction-list-detail", "date": "2026-09-05", "summary": "storage.transaction.list 实现纠正:原实现错误查询 wms_stock_transaction 并按商品+单据类型聚合(合并模式),现改为查询 wms_storage_transaction 的逐条流水明细(与 stock.transaction.list 形态一致:裸 SQL 列白名单 + COUNT 分页 + 排序白名单)。聚合查询移除后,生产单仓库 160 万行聚合慢查询(约 9s)不复存在;明细查询实测 COUNT 约 0.2s。", "methods": [ "storage.transaction.list" ], "notes": [ "代码变更:systems/stock_transaction.js list() 由 ORM 聚合查询重写为 wms_storage_transaction 裸 SQL 逐条明细(列白名单含 storage_id/space_id/inventory_type/source_order_codes/before/after_intercept_locked_quantity,LEFT JOIN wms_stock_warehouse 返回 stockItem);systemMethods/storage/transaction.js 解构 whereValue 逐字段传参,warehouse_id 由服务端从 ctx.user.store_id 注入。", "行为变更:group_by_batch 参数废弃,恒返回逐条明细;原合并模式响应(quantity 合计/first_created_at/last_created_at/record_count)不再返回。", "where 支持字段:transaction_type、stock_id/stock_ids、space_id、store_id/store_ids、order_type、order_no(模糊)、batch_no、inventory_type、operator_name(模糊)、order_id、created_at(between)与 start_time/end_time;keyword 支持顶层或 where 内。", "排序白名单:created_at、quantity、stock_id、store_id、warehouse_id、space_id,非法回退 created_at DESC;pageSize 上限 200。", "前端调用方需按逐条明细结构适配(原合并模式渲染逻辑作废)。" ] }, { "version": "2026.09.04-storage.entry.quickInbound-noneed-notice", "date": "2026-09-04", "type": "enhanced", "summary": "storage.entry.quickInbound 新增参数 noNeedNotice(默认 0):0 时快捷直入完成后通知货主,1 时跳过通知,通知失败仍不影响入库主流程。", "methods": [ "storage.entry.quickInbound" ], "notes": [ "app/service/systemMethods/storage/entry.js:quickInbound 解析 data.noNeedNotice(默认 0)并透传底层 quickInbound({ id, noNeedNotice })", "app/service/systems/storage/entry.js:quickInbound(data) 解析 data.noNeedNotice(Number 归一化),事务提交后仅当 noNeedNotice !== 1 时调用 notifyEntryOrderCompleted", "methods/system.json:storage.entry.quickInbound 新增 noNeedNotice 参数说明与 description 补充;版本 0.3.83 -> 0.3.84(docMeta.version),updatedAt 保持 2026-09-04", "无数据库 schema 变更,未执行任何写库操作" ], "module": "storage.entry" }, { "version": "2026.09.04-storage.entry.commit-noneed-notice", "date": "2026-09-04", "type": "enhanced", "summary": "storage.entry.commit 新增参数 noNeedNotice(默认 0):0 时入库完成后通知货主,1 时跳过通知,通知失败仍不影响入库主流程。", "methods": [ "storage.entry.commit" ], "notes": [ "app/service/systemMethods/storage/entry.js:commit 解析 data.noNeedNotice(默认 0)并透传底层 inboundDirectLog.commit(entry_order_id, noNeedNotice)", "app/service/systems/inbound_direct_log.js:commit(entryOrderId, noNeedNotice = 0),事务提交后仅当 Number(noNeedNotice) !== 1 时调用 notifyEntryOrderCompleted(字符串 '1' 也兼容)", "methods/system.json:storage.entry.commit 新增 noNeedNotice 参数说明与 description 补充;版本 0.3.82 -> 0.3.83(docMeta.version),updatedAt 保持 2026-09-04", "无数据库 schema 变更,未执行任何写库操作" ], "module": "storage.entry" }, { "version": "2026.09.04-stock.report.export-stock-id-fix", "date": "2026-09-04", "type": "fixed", "summary": "修复 stock.report.export(含 search/searchStore/exportStore)where.stock_id 传数组时导出空白的问题:单数 stock_id 现兼容数组,避免被再包裹一层导致嵌套数组归一化为 NaN 全量过滤;同时修复默认分页上线后导出内部 search 被截断为第一页 20 条导致汇总/明细缺数据的回归。", "methods": [ "stock.report.search", "stock.report.searchStore", "stock.report.export", "stock.report.exportStore" ], "notes": [ "根因:where.stock_id 传数组时 systemMethods 层 [ stockIdRaw ] 再包一层形成嵌套数组,systems 层 Number(嵌套数组)=NaN 被全部过滤 → 汇总空 → 导出空白", "app/service/systemMethods/stock/report.js:search/searchStore/export/exportStore 四处 stock_id 解析兼容数组(Array.isArray ? 原样 : 包单元素)", "app/service/systems/storage/report.js:search 中 stockIds 归一化改用 flat() 防御嵌套;export 内部调用 search 显式传全量分页 { page: 1, pageSize: 1000000 }(新增常量 EXPORT_FULL_PAGE_SIZE),避免默认分页截断", "methods/system.json:search/searchStore 的 stock_id 描述补充“兼容数组”;export/exportStore 的 where 描述补充 stock_id/stock_ids/keyword,export 新增 export_mode 参数说明;版本 0.3.81 -> 0.3.82(docMeta.version),updatedAt 保持 2026-09-04", "验证:开发库 where.stock_id 传 20 个 ID 的 search 返回 20 行;export 同条件任务成功并产出 832KB Excel(非空白);无数据库 schema 变更,未执行任何写库操作" ], "module": "stock.report" }, { "version": "2026.09.04-stock.report.search-sort-fields", "date": "2026-09-04", "type": "enhanced", "summary": "stock.report.search 排序白名单扩充:新增 stock_id、item_code、item_name(与 begin_total、inbound_total、outbound_total、end_total 共 7 个字段),item_code/item_name 按字典序、其余按数值排序,与其他列表页面的 sort.sortField/sortOrder 用法保持一致。", "methods": [ "stock.report.search", "stock.report.searchStore", "stock.report.export", "stock.report.exportStore" ], "notes": [ "app/service/systems/storage/report.js:SORT_FIELD_WHITE_LIST 扩充为 7 字段;新增 STRING_SORT_FIELD_SET(item_code/item_name 字典序比较,localeCompare),其余字段数值比较;by_space=false 分支 baseStockRows 查询新增 sw.item_code/sw.item_name,groupedList 行携带(供排序与展示回退);by_space=true 分支 baseStorageRows LEFT JOIN wms_stock_warehouse sw ON sw.id=s.stock_id 取 MAX(sw.item_code)/MAX(sw.item_name);两分支最终 item_name/item_code 展示优先 getStockDetails,回退快照值", "app/service/systemMethods/stock/report.js:search JSDoc 同步白名单", "methods/system.json:search/searchStore/export/exportStore 的 sort 参数描述同步新白名单;版本 0.3.80 -> 0.3.81(docMeta.version),updatedAt 更新为 2026-09-04", "无数据库 schema 变更,未执行任何写库操作" ], "module": "stock.report" }, { "version": "2026.09.03-stock.report.search-default-pagination", "date": "2026-09-03", "type": "updated", "summary": "stock.report.search 分页改为默认生效:不传 data.pagination 或传非法分页时,默认按 page=1、pageSize=20 返回第一页,响应始终携带 data.pagination 分页信息(原为未传时全量返回)。分页参数同时支持顶层 page/pageSize/page_size(与其他 list 接口一致,顶层值优先)。", "methods": [ "stock.report.search" ], "notes": [ "app/service/systems/storage/report.js:paginateList 改为默认分页语义(未传/非法回退 page=1、pageSize=20,新增模块常量 DEFAULT_PAGE_SIZE=20);两个输出分支(by_space=false/true)响应 data.pagination 恒返回;200 空列表 early return 同步携带 pagination 元信息(total=0)", "app/service/systemMethods/stock/report.js:search 分页参数解析与其他 list 一致——data.pagination 优先,兼容顶层 data.page 与 data.pageSize / data.page_size(顶层值覆盖 pagination 对象);searchStore(货主侧)暂不支持分页,行为不变", "methods/system.json:pagination 参数与 data.list/data.pagination 响应描述更新为默认分页语义,data.pagination required 改为 true,新增 page/pageSize 顶层兼容参数条目;版本 0.3.78 -> 0.3.80(docMeta.version),updatedAt 保持 2026-09-03", "无数据库 schema 变更,未执行任何写库操作" ], "module": "stock.report" }, { "version": "2026.09.03-stock.report.search-pagination", "date": "2026-09-03", "type": "enhanced", "summary": "stock.report.search 新增分页支持:请求体 data.pagination = { page, pageSize } 时,先按现有排序规则排序再切片,仅对当前页行加载名称信息,响应 data.pagination 返回分页元信息;未传或非法分页保持全量返回(向后兼容)。", "methods": [ "stock.report.search" ], "notes": [ "app/service/systems/storage/report.js:新增模块函数 paginateList(归一化 page/pageSize,非法/未传返回 null 表示不分页);search 方法新增 pagination 入参,两个输出分支(by_space=false/true)均改为 sortReportList 先排序 → paginateList 切片 → 仅对 pageItems 加载名称信息(getStockDetails/Store/LocationSpace 只查当前页),分页时响应 data.pagination = { page, pageSize, total, totalPages, hasPrevious, hasNext }", "app/service/systemMethods/stock/report.js:search 透传 data.pagination(JSDoc 同步);searchStore(货主侧)暂不支持分页", "性能背景:生产实测全仓 33353 SKU 无分页约 4.6~8.8s,其中 getStockDetails 名称加载为耗时大头;分页后仅当前页触发缓存/DB 查询", "methods/system.json:stock.report.search 新增 pagination/pagination.page/pagination.pageSize 参数与 data.pagination 响应字段;版本 0.3.77 -> 0.3.78(docMeta.version),updatedAt 保持 2026-09-03", "无数据库 schema 变更,未执行任何写库操作" ], "module": "stock.report" }, { "version": "2026.09.03-workbench-barcode-removed", "date": "2026-09-03", "type": "removed", "summary": "下线工作台条码 barcode 相关字段(未使用):wms_workbench 删除 barcode 列及 idx_barcode、uk_warehouse_barcode 索引;workbench.list 移除 barcode 筛选与列表项、workbench.create/update 不再接收 barcode;workbench.checkBarcode 接口整体移除(方法、权限白名单、文档条目同步删除);order.packing.list / order.packing.detail 响应移除 workbench_barcode 字段(源列已删,恒为 null 无意义)。", "methods": [ "workbench.list", "workbench.create", "workbench.update", "workbench.getWorkbenchInfo", "workbench.checkBarcode", "order.packing.list", "order.packing.detail" ], "notes": [ "database/migrations/20260903180000-remove-barcode-from-wms-workbench.js:先删 uk_warehouse_barcode、idx_barcode 索引再删 barcode 列(幂等 describeTable/showIndex 判断),up/down 对称(down 恢复列与索引),已在开发库执行并验证(wms_workbench 现为 12 列)", "app/model/workbench.js:移除 barcode 字段定义与 idx_barcode、uk_warehouse_barcode 索引声明", "app/service/systems/workbench.js:list 移除 where.barcode 筛选;create/update 移除 barcode 处理;删除 checkBarcodeExists;formatWorkbenchTokenInfo 移除 barcode 输出", "app/service/systemMethods/workbench.js:删除 checkBarcode 方法,systemInit 免权限/免日志/免鉴权白名单移除 checkBarcode", "app/service/systems/order_packing.js:list/detail 扁平化输出移除 workbench_barcode 字段", "methods/system.json:工作台模块删除 workbench.checkBarcode 条目、list/create/update/getWorkbenchInfo 条目按无 barcode 形态重写;订单打包模块 order.packing.list / order.packing.detail description 移除 workbench_barcode 说明;版本 0.3.76 -> 0.3.77(docMeta.version),updatedAt 保持 2026-09-03", "本次未执行任何直接 DDL/写库操作;仅通过迁移文件在开发库(127.0.0.1:3307)执行 schema 变更并验证;生产库迁移需发布时按标准流程执行" ], "module": "workbench" }, { "version": "2026.09.03-workbench-member-bind", "date": "2026-09-03", "type": "enhanced", "summary": "新增接口 workbench.bindMember(免登录、免鉴权):入参用户ID(可为空,兼容非系统账号用户)+ 姓名(必填非空)+ 工作台 token,按 token 解析工作台后在 wms_workbench_member 副表新增成员行(user_id 空时仅存 user_name 姓名快照),返回新建成员行(id/workbench_id/user_id/user_name);token 无效返回失败 code=403。与已上线的 workbench.removeMember 构成成员增删闭环。", "methods": [ "workbench.bindMember" ], "notes": [ "app/service/systems/workbench.js:新增 bindWorkbenchMember(token 校验 → 姓名必填校验 → 用户ID归一化(空/非正整数处理)→ resolveWorkbenchByToken 解析工作台 → WorkbenchMember.create),复用既有 resolveWorkbenchByToken 缓存优先逻辑", "app/service/systemMethods/workbench.js:新增 bindMember 薄出口,systemInit 免登录/免权限/免日志/免鉴权声明补充 bindMember", "methods/system.json:工作台模块新增 workbench.bindMember 条目;版本 0.3.75 -> 0.3.76(docMeta.version),updatedAt 保持 2026-09-03", "无数据库 schema 变更(复用 wms_workbench_member 表),未执行任何写库操作" ], "module": "workbench" }, { "version": "2026.09.03-workbench-member-remove", "date": "2026-09-03", "type": "enhanced", "summary": "工作台新增成员/用户登录副表 wms_workbench_member(id/workbench_id/user_id/user_name/created_at/updated_at/deleted_at,user_id 允许为空以兼容非系统账号用户,user_name 存名称快照;索引 idx_workbench_id/idx_user_id)。新增接口 workbench.removeMember(免登录、免鉴权):入参成员行 ids 与工作台 token,按 token 解析工作台后仅软删除归属于该工作台的成员行,返回 removed 数量与 ids 列表;token 无效返回失败 code=403,无可移除成员返回 code=404。", "methods": [ "workbench.removeMember" ], "notes": [ "database/migrations/20260903150000-create-wms-workbench-member.js:创建 wms_workbench_member 表(幂等 showAllTables 判断)+ idx_workbench_id/idx_user_id 索引,up/down 对称,已在开发库执行并验证(user_id 列 IS_NULLABLE=YES)", "app/model/workbench_member.js:新增 WorkbenchMember 模型(paranoid 软删除),associate 声明 belongsTo Workbench(as workbench)与 belongsTo Account(as user)", "app/model/workbench.js:associate 新增 Workbench.hasMany(WorkbenchMember, as members)", "app/service/systems/workbench.js:新增 resolveWorkbenchByToken(缓存 workbench:token:{token} 优先、查库兜底并回填缓存)、normalizeWorkbenchMemberIds(数组/单值/逗号串,去重仅正整数)、removeWorkbenchMember(token 解析工作台后软删除归属成员行)", "app/service/systemMethods/workbench.js:新增 removeMember 薄出口,systemInit 免登录/免权限/免日志/免鉴权声明补充 removeMember", "methods/system.json:工作台模块新增 workbench.removeMember 条目;版本 0.3.74 -> 0.3.75(docMeta.version),updatedAt 保持 2026-09-03", "本次未执行任何直接 DDL/写库操作;仅通过迁移文件在开发库(127.0.0.1:3307)执行 schema 变更并验证表结构;生产库迁移需发布时按标准流程执行" ], "module": "workbench" }, { "version": "2026.09.03-workbench-login-code-token", "date": "2026-09-03", "type": "enhanced", "summary": "工作台登录码/令牌与绑定登录能力:wms_workbench 新增 token、login_code 两个字段(VARCHAR(64),login_code 前缀 wblc + 随机段共 64 位、全局唯一;token 随机 64 位)。新增 5 个接口:index.getWorkbenchBindCode(免登录免鉴权,参考 user.getLoginWechatCode:返回 client_code 并在缓存生成绑定码,传入 client_code 时长轮询等待绑定完成返回 token,超时/缓存失效重新生成绑定码后才返回数据)、workbench.bind(需登录需权限:校验缓存绑定码 + 工作台ID 关联绑定,成功后写入随机 token,旧 workbench:token:{token} 缓存删除)、workbench.getWorkbenchInfo(免登录免鉴权:token 查缓存 workbench:token:{token},未命中查库,无信息返回失败 code=403)、index.LoginWorkbenchByCode(免登录免鉴权:wms_workbench.login_code 入参换取 token,无匹配返回失败 code=403)、workbench.resetLoginCode(需登录需权限:随机重置 login_code)。workbench.list 返回 login_code(不返回 token),workbench.update 不受理 login_code 传入,workbench.create 自动创建 login_code。", "methods": [ "index.getWorkbenchBindCode", "index.LoginWorkbenchByCode", "workbench.bind", "workbench.getWorkbenchInfo", "workbench.resetLoginCode", "workbench.list", "workbench.create", "workbench.update" ], "notes": [ "database/migrations/20260903100000-add-login-code-token-to-wms-workbench.js:新增 login_code/token 两列(幂等 describeTable 判断)+ uk_login_code 唯一索引 + idx_token 索引,up/down 对称,已在开发库执行并验证", "app/model/workbench.js:新增 login_code/token 字段定义与 uk_login_code/idx_token 索引声明", "app/service/systems/workbench.js:新增绑定码/令牌能力(getWorkbenchBindCode/bindWorkbench/getWorkbenchInfoByToken/loginWorkbenchByCode/resetLoginCode 与配套缓存/生成/轮询辅助方法);list/detail 排除 token;create 自动生成唯一 login_code;update 白名单不含 login_code/token(传入不受理);缓存 key:workbench:bind:client:{clientCode}、workbench:bind:code:{code}(TTL 120s)、workbench:token:{token}(TTL 300s);长轮询 60s、每秒轮询缓存状态", "app/service/systemMethods/workbench.js:新增 bind/getWorkbenchInfo/resetLoginCode 薄出口,systemInit 免登录/免权限/免鉴权/免日志声明补充 getWorkbenchInfo(bind/resetLoginCode 走默认需登录需权限)", "app/service/systemMethods/index.js:新增 getWorkbenchBindCode/LoginWorkbenchByCode 薄出口,systemInit 免登录/免权限/免鉴权声明补充两方法(_noNeedLog 本就为 *)", "403 口径:/system 网关不支持方法内设置 HTTP 状态码,按现有惯例(stock/warehouse.js 同款)返回 flag=failure、code=403 业务失败", "methods/system.json:工作台模块新增 workbench.bind / workbench.getWorkbenchInfo / workbench.resetLoginCode 条目并更新 list/create/update 条目(list 响应补 login_code);基础模块新增 index.getWorkbenchBindCode / index.LoginWorkbenchByCode 条目;版本 0.3.73 -> 0.3.74(docMeta.version),updatedAt 保持 2026-09-03", "本次未执行任何直接 DDL/写库操作;仅通过迁移文件在开发库(127.0.0.1:3307)执行 schema 变更并验证列与索引;生产库迁移需发布时按标准流程执行" ], "module": "workbench" }, { "version": "2026.09.03-receiving-store-name-enrich", "date": "2026-09-03", "type": "changed", "summary": "storage.receiving.getReceivingList / getReceivingDetail 货主名称实时解析:列表每项与详情主单的 store_name 不再只依赖主表快照(约 26% 历史数据快照为空),改为优先取合约表 wms_store_warehouse.store_remask(货主备注名称,按 store_id + warehouse_id 维度),无合约或备注为空时回退 wms_store.company_name(公司全称),均无时保留主表快照(可能为空字符串)。", "methods": [ "storage.receiving.getReceivingList", "storage.receiving.getReceivingDetail" ], "notes": [ "app/service/systems/storage/receiving.js 新增 _resolveReceivingStoreNameMap(storeIds, warehouseId):批量解析货主名称映射——先查 wms_store_warehouse(store_id IN + warehouse_id)取 store_remask,再查 wms_store 取 company_name 兑底,返回 Map;口径与 afterSale._enrichListStoreNames / inventory.store_name 一致(store_remask 优先、company_name 兑底)", "app/service/systems/storage/receiving.js getReceivingList:拉取列表后批量调用 _resolveReceivingStoreNameMap,processedData 每项 store_name = 实时解析值 || 主表快照 || ''(实时值优先,兼容未绑定货主的存量数据)", "app/service/systems/storage/receiving.js getReceivingDetail:查到主单后按 receiving.store_id + receiving.warehouse_id 实时解析货主名称,解析有值时覆盖 receiving.store_name(否则保留快照)", "methods/system.json 收货单模块(module=storage_receiving):getReceivingList description 补充列表项 store_name 实时解析口径;getReceivingDetail 响应新增 receiving.store_name 字段描述;版本 0.3.72 -> 0.3.73(docMeta.version),updatedAt 保持 2026-09-03", "AI_METHOD_ROUTING.md / AI_TOOLBOX.md 本次未同步:两者仅登记服务方法名清单,不含字段级描述,无需改动", "本次仅查询验证(wms_receiving 共 1238 条、store_name 为空 319 条、store_id 为空 317 条;抽检 store_id=1000000 可经 store_remask='测试货主' 解析),未执行任何数据库写操作/DDL/Redis 操作;业务代码已通过 ESLint" ], "module": "storage.receiving" }, { "version": "2026.09.03-policy-allocate-start-time-cross-day", "date": "2026-09-03", "type": "enhanced", "summary": "货主策略与仓库级设置新增「开始自动分配时间」allocate_start_time(默认 08:00),支持跨天窗口:截单时间作为最后允许时间,开始时间晚于截单时间时截单时间视为次日;当前时间早于开始自动分配时间与超过截单时间行为一致(不自动分配快递/储位、不自动加团)。保存时开始时间等于截单时间(自动分配窗口为空)报 400。", "methods": [ "storeWarehouse.store.getPolicyConfigFields", "storeWarehouse.store.savePolicyConfig", "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "app/model/store_warehouse.js POLICY_CONFIG_FIELDS 新增 allocate_start_time(名称:开始自动分配时间,type string,default 08:00,min 00:00,max 23:59,maxLength 5);cutoff_order_time 的 min 从 12:00 放开为 00:00(支持凌晨截单/跨天窗口);cutoff_order_enabled/cutoff_order_time 描述补充跨天语义;normalizePolicyConfig 保存路径(sanitizeOnly=false)新增跨字段校验:allocate_start_time 与 cutoff_order_time 相同时抛错「policy_config.allocate_start_time 不能等于 policy_config.cutoff_order_time(自动分配窗口为空)」(400),读取路径(sanitizeOnly=true)不校验", "app/model/store.js DEFAULT_SUBJECT_CONFIG 新增 allocate_start_time: '08:00';CUTOFF_ORDER_TIME_MIN 放开为 00:00;normalizeSubjectConfig 新增 HH:mm 格式校验(非法抛「subject_config.allocate_start_time 格式必须为 HH:mm(如 08:00)」)与相等校验(显式同时提交两个时间字段且相等时抛错),旧数据读取自动补默认 08:00", "app/service/systems/setting/warehouse.js WAREHOUSE_SETTING_FIELDS 新增 allocate_start_time 字段元信息(default 08:00,min 00:00,max 23:59);cutoff_order_time 的 min 放开为 00:00;getFieldMeta 自动返回新字段元信息", "app/service/systems/delivery_order.js resolveCutoffOrderConfig 返回值新增 allocateStartTime(默认 08:00,货主-仓库级优先、仓库级兜底);新增 isAllocationWindowClosed(allocateStartTimeStr, cutoffTimeStr, nowDate):同天窗口(start=cutoff 禁止;跨天窗口(start>cutoff,截单视为次日)now in [cutoff,start) 禁止;start==cutoff 防御性全天禁止;asyncProcessOrderCreated 用 isAllocationBlocked 替换 isCutoffActive 控制自动分配快递/储位/自动加团,日志补充 allocateStartTime/cutoffTime", "methods/system.json:storeWarehouse.store.getPolicyConfigFields response 从空数组补充字段元信息说明(data[]、data[].allocate_start_time、data[].cutoff_order_time、data[].cutoff_order_enabled);storeWarehouse.store.savePolicyConfig params 补充 policy_config.cutoff_order_enabled/cutoff_order_time/allocate_start_time 字段文档与 400 错误说明,response 补充 data.policy_config.allocate_start_time;setting.warehouse.getSettings response 与 setting.warehouse.saveSettings params 补充 subject_config.allocate_start_time/subject_config.cutoff_order_time 字段文档(getFieldMeta 为通用字段元信息结构,无逐字段清单,无需改动);版本 0.3.71 -> 0.3.72(docMeta.version),updatedAt 更新为 2026-09-03", "本次仅文档同步(业务代码由 wms-dev-agent 完成:新增字段、跨天窗口判定、保存校验,并已通过 ESLint 与单元测试),未修改 app/ 下任何代码,未执行数据库/Redis 操作" ], "module": "storeWarehouse.store" }, { "version": "2026.09.02-order-packing-list-perf-export", "date": "2026-09-02", "type": "changed", "summary": "order.packing.list 慢查询优化 + 新增导出与进度查询接口:list 查询将 findAndCountAll 拆分为 count(不带 include)+ findAll(带 include),避免 count 生成 COUNT(DISTINCT)+双 LEFT JOIN(生产实测 520ms,拆分后 count 走单表索引约 44ms);筛选/排序逻辑提取为 _buildListWhere/_buildListOrder 供列表与导出复用。新增 order.packing.export(提交异步导出任务,入参 where/sort 语义与 list 一致,warehouse_id 由服务端注入;后台生成单 Sheet Excel「打包任务列表」并上传 COS)与 order.packing.exportTaskProgress(按 task_id 查询进度与下载链接)。两接口免权限免日志免鉴权(与 order.export 口径一致,无 wms_permission 记录),需登录。", "methods": [ "order.packing.list", "order.packing.export", "order.packing.exportTaskProgress" ], "notes": [ "app/service/systems/order_packing.js:list 查询拆分——findAndCountAll 改为 count({where})(不带 include)+ findAll({where, include, limit, offset}),修复 hasMany include(videos/expresses)导致 count 生成 COUNT(DISTINCT)+双 LEFT JOIN 的慢查询(生产实测 520ms → 44ms);where 构建逻辑(status/pack_mode/waybill_code/wave_no/order_id/workbench_id/quickWhere/has_video/video_enable/时间范围)原样提取为 _buildListWhere(list/export 共用),排序提取为 _buildListOrder(list/export 共用);新增 createBusinessError 与 exportPackTask", "app/service/systems/order_packing.js exportPackTask:复用 _buildListWhere/_buildListOrder 并强制 warehouse_id(缺失抛 400 缺少仓库上下文);主表全量分页拉取(每页 500,无行数上限);批量关联工作台(wms_workbench)、视频(wms_pack_task_video,含 camera 名称)、运单(wms_order_express,按 order_id 分批 100);ExcelJS 流式单 Sheet「打包任务列表」18 列(任务ID/订单ID/波次号/运单号/关联运单号/打包模式/任务状态/打包数量/商品总数量/商品种类数/工作台/作业人员/开始打包时间/结束打包时间/创建时间/视频状态/录像可用/备注),经 systems.upload.uploadFile 上传(key=exports/pack_task/{warehouseId}/{timestamp}_{token}.xlsx,mimetype xlsx,category=document),结果含 filename/fileKey/url/cdnUrl/cosUrl/current_count/total_count/sheet_count", "app/service/systemMethods/order/packing.js:新增 export/exportTaskProgress 与任务缓存辅助方法(generateExportTaskId/normalizeExportTaskId/getExportTaskCacheKey/setExportTaskProgress/getExportTaskProgress):缓存键前缀 packing_export_task_,Redis TTL 1800 秒;export 提交后 setImmediate 异步执行并逐阶段回写进度(submitted(0) → running(5) → 数据拉取 10~30(未命中数据时 85)→ 关联拉取 30~55 → Excel 55~90 → 上传 92 → success(100),失败 failed + error);exportTaskProgress 入参兼容 task_id/taskId,download_url 从 result.url/cdnUrl/cosUrl/fileKey 兜底取,未命中返回 status=not_found(正常响应非报错)", "systemInit 权限声明:_noNeedRight/_noNeedLog/_noNeedAuth 由 'list,get' 扩展为 'list,get,export,exportTaskProgress'(导出异步任务免权限免日志免鉴权,与 order.export 口径一致);_noNeedLogin 不变", "methods/system.json order.packing 模块:新增 order.packing.export 与 order.packing.exportTaskProgress 两个 method 条目(追加于 order.packing.list 之后),版本 0.3.70 -> 0.3.71(docMeta.version),updatedAt 更新为 2026-09-02", "本次未修改 wms_pack_task 表结构,未执行数据库写操作/Redis 操作;未运行测试" ], "module": "order.packing" }, { "version": "2026.09.01-report-delivery-notify-group-routing-fix", "date": "2026-09-01", "type": "changed", "summary": "修复「补货预警报表定时投递群路由」缺陷(G1):生产上 3 条投递计划发出 5 条消息——报表文件消息被投递到投递计划未配置的「货主默认站内信群」(如 store-1000156 的收货群、store-1000159 的对接群被误发)。根因:deliverByChannel 未按计划配置解析群目标,按 group_type='store' 取任意货主默认群(与 notify_group_ids 配置无关)。修复:新增 resolveNotifyGroups 统一解析(过滤 is_blocked=1、软删、仓库维度一致)供投递与通知两路共用;配置了 notify_group_ids 的计划文件消息仅逐群投递到配置群,全部不可达(不存在/已删除/被屏蔽/仓库不一致)时抛错进入 failed 退避重试、不再回退未配置群;未配置通知群的历史计划保持旧行为回退货主默认站内信群;sendNotifyIfConfigured 复用 resolveNotifyGroups 删除重复查询逻辑。响应结构不变,仅群路由语义变更。", "methods": [ "report.deliveryPlan.save", "report.deliveryPlan.list", "report.deliveryPlan.copy" ], "notes": [ "app/service/systems/reportDelivery.js 新增 resolveNotifyGroups({plan, warehouseId}):notify_group_ids → 有效群行统一解析(is_blocked=0、软删自动排除、warehouse_id 维度一致),投递(deliverByChannel)与文本通知(sendNotifyIfConfigured)两路共用,保证口径一致;未配置群或全部被过滤时返回空数组,InboxGroup 模型不可用时抛错", "app/service/systems/reportDelivery.js deliverByChannel 群路由改造:计划配置 notify_group_ids 时报表文件消息只逐群投递到配置群,不再投递任意「货主默认群」(旧逻辑为 group_type='store' 按 id ASC 取最早一条,与计划配置无关);配置了群但全部不可达(不存在/已删除/被屏蔽/仓库不一致)时抛「货主 配置的通知群不可达…无法投递」进入 failed 退避重试(MAX_RETRY=3,退避 retry_count × 60s),不再静默回退到未配置群;未配置通知群的历史计划保持旧行为回退到货主默认站内信群(group_type='store',取最早一条)兼容存量计划", "app/service/systems/reportDelivery.js sendNotifyIfConfigured 复用 resolveNotifyGroups 解析通知群,删除重复查询逻辑,投递与通知共用同一解析口径", "methods/system.json 通用报表模块(module=report):report.deliveryPlan.save description 与 params/response 的 notify_group_ids 描述补充群路由口径(文件消息仅投递计划配置群、未配置回退货主默认站内信群、配置群全部不可达失败退避);report.deliveryPlan.list description 与 response 的 notify_group_ids 描述同步;report.deliveryPlan.copy description 补充复制计划通知群置空后投递回退目标货主默认站内信群语义;请求/响应结构、headers、errors 均不变;版本 0.3.69 -> 0.3.70(docMeta.version),updatedAt 保持 2026-09-01", "docs/report-config-guide.md 第 5 节补充文件消息投递目标/群路由口径(配置群定向投递、未配置回退默认群、全部不可达失败退避),第 5.1.2 节 notify_group_ids 补充同时作为文件消息投递目标的说明", "测试回归:140 测试全过(业务代码由开发任务完成并测试通过);本次仅文档同步,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "report" }, { "version": "2026.09.01-returnReceived.export", "date": "2026-09-01", "type": "added", "summary": "退回收到模块新增导出与进度查询接口:returnReceived.export(提交异步导出任务,入参 where/sort 语义与 returnReceived.list 一致,warehouse_id 由服务端注入 ctx.user.store_id;后台生成单 Sheet Excel「退回收到登记列表」并上传 COS)与 returnReceived.exportTaskProgress(按 task_id 查询任务进度与下载链接,未命中返回 status=not_found)。任务缓存 Redis TTL 30 分钟,全量分页拉取 500/页;两接口默认走 API 权限校验(需 wms_permission 存在类型为 api 的记录),需登录。", "methods": [ "returnReceived.export", "returnReceived.exportTaskProgress" ], "notes": [ "app/service/systemMethods/returnReceived.js 新增 export/exportTaskProgress 与任务缓存辅助方法(generateExportTaskId/normalizeExportTaskId/getExportTaskCacheKey/setExportTaskProgress/getExportTaskProgress):缓存键前缀 return_received_export_task_,Redis TTL 1800 秒(30 分钟);export 提交后 setImmediate 异步执行并逐阶段回写进度(submitted(0) → running(5) → 数据拉取 10~55(未命中数据时 85)→ Excel 生成 60 → success(100),失败 failed + error);exportTaskProgress 入参兼容 task_id/taskId,download_url 从 result.url/cdnUrl/cosUrl/fileKey 兜底取;task_id 为空或缓存未命中返回 status=not_found(正常响应非报错)", "systemInit 权限声明:_noNeedRight 仅 detail(export/exportTaskProgress 未加入免权限列表,默认走 API 权限校验,需 wms_permission 存在 returnReceived.export / returnReceived.exportTaskProgress 类型为 api 的记录);_noNeedLogin 为空(两接口均需登录,isNeedAuth=true、isNeedLogin=true);_noNeedLog 为空(记录操作日志);_noNeedAuth 为空(走仓库有效期检查)", "app/service/systems/return_received.js 新增 exportList/_generateExportExcel/_resolveStoreRemarkMap:复用 _buildListWhere/_buildListOrder(与 list 语义一致)并强制 warehouse_id=注入值(缺失抛 400 缺少仓库上下文);主表全量分页拉取(每页 500,无行数上限);货主备注批量解析(wms_store_warehouse.store_remask,失败降级空字符串不阻断导出)", "导出 Excel:单 Sheet「退回收到登记列表」,列=运单号/扫描日期/扫描人员/是否原单退回(是/否)/订单ID/货主备注/备注/登记时间/更新时间;ExcelJS 流式写入临时文件后经 systems.upload.uploadFile 上传(key=exports/return_received/{warehouseId}/{timestamp}_{token}.xlsx,mimetype xlsx,category=document),结果含 filename/fileKey/url/cdnUrl/cosUrl/current_count/total_count", "methods/system.json 退回收到模块(module=returnReceived)新增 returnReceived.export 与 returnReceived.exportTaskProgress 两个 method 条目(追加于 returnReceived.delete 之后),版本 0.3.68 -> 0.3.69(docMeta.version),updatedAt 保持 2026-09-01", "AI_METHOD_ROUTING.md 同步:app/service/systemMethods/returnReceived.js 方法计数 (5) -> (7),方法清单补充 export/exportTaskProgress;AI_TOOLBOX.md 未涉及 returnReceived 清单,无需改动", "本次仅文档同步(业务代码由开发任务完成),未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "returnReceived" }, { "version": "2026.09.01-intercept-locked-quantity-rework", "date": "2026-09-01", "type": "changed", "summary": "库内拦截确认时库存不再归还可用、改移入拦截锁定字段的改造落地:wms_storage_transaction 新增 before_intercept_locked_quantity / after_intercept_locked_quantity 两个拦截锁定快照字段(migration 20260901000200,尚未上线);wms_storage 可用数量统一口径 available_quantity = quantity - locked_quantity - intercept_locked_quantity;拦截相关流水新增 order_type=INTERCEPT_LOCK(拦截锁迁移/实物返还并拦截锁定)与 INTERCEPT_UNLOCK(拦截锁释放回落可用);stock.warehouse.search(with_stock)与 stock.warehouse.getStockDetail 按库位合并明细响应新增 intercept_locked_quantity 字段(向后兼容);order.recheckOrder.confirmIntercept / interceptScan 确认拦截时以拦截模式释放储位分配(interceptMode=true,库存不归还可用、移入拦截锁定)。", "methods": [ "stock.warehouse.getStockDetail", "stock.warehouse.search", "order.recheckOrder.confirmIntercept", "order.recheckOrder.interceptScan" ], "notes": [ "database/migrations/20260901000200-add-intercept-locked-snapshots-to-wms-storage-transaction.js:describeTable 幂等检测,新增 before_intercept_locked_quantity / after_intercept_locked_quantity(INT NULL,comment 变更前/后拦截锁定数量,与既有 before/after_locked_quantity 风格一致、可空无默认值、由写入逻辑维护);该 migration 尚未上线", "app/model/storage_transaction.js:在 after_locked_quantity 之后新增 before_intercept_locked_quantity / after_intercept_locked_quantity 字段定义(INTEGER(12)/allowNull=true,comment 变更前/变更后拦截锁定数量)", "app/service/systems/storage/index.js updateQuantity:新增 options.interceptLockedChange 变化量参数,统一重算 available_quantity = quantity - locked_quantity - intercept_locked_quantity,并校验拦截锁定数量非负、不超过库存数量、与锁定数量之和不超过库存数量;新增 interceptLockQuantity(作业锁迁移为拦截锁:locked -q、intercept +q、available 不变)/ interceptReceiveQuantity(实物返还并拦截锁定:quantity +q、intercept +q、available 不变)/ interceptUnlockQuantity(拦截锁释放回落可用:intercept -q、available +q)三个专用方法", "app/service/systems/order_storage_allocation.js cancelAllocateStorage:新增 interceptMode 开关——拦截确认模式下 pending 行执行作业锁迁移(locked -q、intercept +q、available 不变)、fin 行实物返还并拦截锁定(quantity +q、intercept +q、available 不变),流水 order_type 记为 INTERCEPT_LOCK 并记录 order_id 与 before/after_intercept_locked_quantity 快照;普通取消模式行为不变;新增 releaseInterceptLocksByOrderIds:按 INTERCEPT_LOCK 与 INTERCEPT_UNLOCK 流水按 (storage_id, order_id) 汇总净拦截量,净量大于 0 时逐库存行调用 interceptUnlockQuantity 释放拦截锁(intercept -q、available +q),写入 order_type=INTERCEPT_UNLOCK 流水并记录快照,重复调用幂等(净量归零后不再释放)", "app/service/systemMethods/order/recheckOrder.js confirmIntercept/interceptScan:释放储位分配改走 cancelAllocateStorage({ order_ids, interceptMode: true }),确认拦截时库存不再归还可用而是移入拦截锁定字段 intercept_locked_quantity;运单标记、订单状态、订单锁、工单、日志等其余口径不变", "app/service/systemMethods/order/pendingOrder.js runBatchUninterceptTask:解除拦截不操作拦截锁定数量字段(业务上拦截→取消拦截均不动库存口径,拦截锁定数量仅在库内拦截确定时占用,回落由后续特定入库处理链路接管)", "app/service/systems/return_received.js create:退货登记不释放拦截锁定库存(拦截锁回落由退货货物后续入库处理接管)", "app/service/systems/stock_store.js search(with_stock)与 getStockDetail:storage 查询 attributes 显式加入 intercept_locked_quantity,按库位合并模式累加拦截锁定数量并按统一口径重算 available_quantity;合并明细响应新增 intercept_locked_quantity(向后兼容,默认 0)", "methods/system.json 同步:stock.warehouse.getStockDetail response storageList 描述补充 intercept_locked_quantity 与 available_quantity 统一口径;stock.warehouse.search response storage 字段的库位分组汇总(children_grouped)与批次明细(children_batch)字段清单均新增 intercept_locked_quantity、available_quantity 口径说明更新为 quantity - locked_quantity - intercept_locked_quantity;order.recheckOrder.confirmIntercept / interceptScan 描述更新为拦截模式释放储位分配(库存不归还可用、移入拦截锁定);版本 0.3.67 -> 0.3.68(docMeta.version),updatedAt 保持 2026-09-01", "核查结论:methods/qimen.json 与 methods/openapi.json 无涉及本改造的接口(openapi.json 仅 order.cancel 描述中出现 intercept_status 字面量,与本改造无关),未同步;stock.transaction.list / stock.transaction.storeList / stock.transaction.export 使用显式 SQL 列白名单(不含拦截锁定快照字段),响应不受影响,文档无需同步;storage.transaction.list(group_by_batch=true)明细模式因模型整行序列化隐含新增 before/after_intercept_locked_quantity,但其 response 文档为对象结构(更新脚本要求数组格式,与既有处理一致),本次未改写,其 list_detail 示例本非全量字段清单", "本次仅文档同步,未修改 app/ 与 database/ 下任何代码与 migration,未执行数据库/Redis 操作,未运行测试" ], "module": "storage" }, { "version": "2026.09.01-receiving-detail-stock-id", "date": "2026-09-01", "type": "changed", "summary": "storage.receiving.getReceivingDetail 与 deleteDetail 明细项新增 stock_id 字段(与 system_product_id 语义一致,向后兼容)", "methods": [ "storage.receiving.getReceivingDetail", "storage.receiving.deleteDetail" ], "notes": [ "app/service/systems/storage/receiving.js getReceivingDetail:明细组装时新增 stock_id: detailBase.system_product_id ?? null(商品/库存ID,语义与 system_product_id 一致,缺失时为 null),system_product_id 保留向后兼容", "app/service/systems/storage/receiving.js deleteDetail:删除后剩余明细 formattedDetails 每项同步新增 stock_id = detailData.system_product_id ?? null,与 getReceivingDetail 明细项字段保持一致", "methods/system.json 收货单模块(module=storage_receiving):getReceivingDetail 响应新增 receiving.details.*.stock_id(number|null,语义与 system_product_id 一致,取 system_product_id、缺失为 null,system_product_id 保留向后兼容);deleteDetail 响应 data.details 描述补充 stock_id 说明;deleteDetail 按更新脚本规范补齐 response 各字段 required、errors 的 description 归一化为 message(语义不变);版本 0.3.66 -> 0.3.67(docMeta.version),updatedAt 保持 2026-09-01", "AI_METHOD_ROUTING.md / AI_TOOLBOX.md 本次未同步:两者仅登记服务方法名清单,不含 getReceivingDetail/deleteDetail 的字段级描述,无需改动", "本次仅文档同步(业务代码由 wms-dev-agent 完成),未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "storage.receiving" }, { "version": "2026.09.01-wms-storage-intercept-locked-quantity", "date": "2026-09-01", "type": "changed", "summary": "wms_storage 库存表新增「拦截锁定数量」字段 intercept_locked_quantity(INTEGER(12) NOT NULL DEFAULT 0,comment 拦截锁定数量),用于拦截场景数量锁定、与 locked_quantity 区分;纯数据模型变更:无接口入参/错误码/鉴权变化,现有写入点由模型默认值 0 兜底;明细模式接口响应因模型整行序列化隐含新增该字段(当前恒为 0,暂无业务读写)。", "methods": [ "storage.inventory.listByStockId" ], "notes": [ "database/migrations/20260901000000-add-intercept-locked-quantity-to-wms-storage.js:describeTable 幂等检测,缺省时 ALTER TABLE wms_storage ADD COLUMN intercept_locked_quantity INT(12) NOT NULL DEFAULT 0 COMMENT '拦截锁定数量';down 删除该字段", "app/model/storage.js:在 locked_quantity 之后新增 intercept_locked_quantity 字段定义(INTEGER(12)/allowNull=false/defaultValue=0/comment 拦截锁定数量);现有写入点(quickPutaway/directPutaway/commit 等)不显式传该字段,依赖模型默认值 0 兜底", "methods/system.json storage.inventory.listByStockId:data.list 明细行字段清单补充 intercept_locked_quantity(拦截锁定数量,默认 0);group_by_space=true 汇总行与 params/errors/isNeedAuth/isNeedLogin 均不变;版本 0.3.65 -> 0.3.66(docMeta.version),updatedAt 更新为 2026-09-01", "storage.inventory.list(group_by_batch=true 明细模式)响应同样隐含新增该字段,但其 response 文档为对象结构(脚本校验要求数组格式),本次未改写;其 list_detail 示例本非全量字段清单(未列 is_enabled/delete_at/supplier_id 等),不构成文档缺口", "storage.inventory.export(明细/汇总导出)、stock.warehouse.getStockDetail、库存报表 stockFlow 等查询均使用显式 attributes 白名单,不受该字段影响,文档无需同步", "本次仅文档同步,未修改 app/ 与 database/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "storage" }, { "version": "2026.08.31-report-stockflow-export-columns-restructure", "date": "2026-08-31", "type": "changed", "summary": "stockFlow 报表(库存变化以及补货报表)导出列结构调整:静态字段清单由 16 个顶层字段收敛为 9 组列(顺序固定:item_name 产品名称 / barcode 条码 / item_code 外部编码 / daily 每日出入库(children ck/rk) / pending_occupy 待处理订单占用数 / available 可用库存 / ck_total 7日总出库数量 / suggest 推荐采购量 / warn 是否触发预警);item_code 复用为外部编码列(key 不变、label 由「商品编码」改为「外部编码」,取值优先 wms_stock_store.item_code 按 stock_id 关联、回落 wms_stock_warehouse.item_code);新增 pending_occupy(取 wms_stock_warehouse.locked_quantity,非 wms_storage 聚合口径);移除 stock_id/rk_total/total/pending/locked/ck_avg/rk_avg/stock_days 共 8 个旧列不再导出(rk_total/日均/预计可售天数等仍内部计算供 suggest/warn 判定与复核,不进入导出列)。", "methods": [ "report.definition.typeList" ], "notes": [ "app/service/systems/report/queries/sevenDayStockFlow.js:FIELDS 静态字段清单由 16 个顶层字段收敛为 9 组列(item_name/barcode/item_code(asText=true)/daily(children ck/rk)/pending_occupy/available/ck_total/suggest(computed=true)/warn(computed=true),顺序固定),item_code 复用旧「商品编码」key、label 改为「外部编码」;头部口径注释同步重写(外部编码优先 wms_stock_store.item_code 按 stock_id 关联 wms_stock_warehouse.id、同 stock_id 多条按 id 升序取第一条非空、stock_id 为空不参与匹配,未匹配回落 wms_stock_warehouse.item_code,再无留空;pending_occupy 取 wms_stock_warehouse.locked_quantity;出入库仍用 wms_stock_transaction 变更数量 quantity;内部仍计算 rk_total/ck_avg/rk_avg/stock_days 供 suggest/warn 判定与复核,不进入导出列)", "app/service/systems/report/queries/index.js:注册表 stockFlow 类型 description 已随查询器口径更新为「…每日出/入库、外部编码、待处理订单占用数、可用库存、7日总出库数量、推荐采购量与是否触发预警」;fields 动态取自查询器 fields 常量,无需单独维护", "methods/system.json 通用报表模块(module=report):report.definition.typeList response 的 fields 描述由「含 16 个字段」更新为「共 9 组列,顺序固定」,fields[].label 示例由「商品编码」更新为「外部编码」;description/params/headers/errors/isNeedAuth/isNeedLogin 不变;版本 0.3.64 -> 0.3.65(docMeta.version),updatedAt 保持 2026-08-31", "docs/report-config-guide.md:第 2 节 stockFlow 全量字段清单表由 16 个顶层字段改写为 9 组列(新顺序/新 label/新 key,附 pending_occupy 口径与外部编码 fallback 口径、8 个旧列移除说明);第 2.1 节口径与假设按查询器头部注释重写(外部编码口径、待处理订单占用数口径、内部计算字段不导出);第 3 节 asText 适用对象改为「条码、外部编码」;第 6 节保存示例 fields 更新为 9 组列、勾选说明由「16 个顶层字段」改为「9 组列」;第 7.3 节 typeList 响应示例字段顺序与 label 同步(外部编码/推荐采购量/是否触发预警)", "AI_METHOD_ROUTING.md 本次未同步(report 能力清单不含 stockFlow 字段列表,仅指向 docs/report-config-guide.md,无需改动)", "本次仅文档同步(业务代码由开发完成),未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试;测试数据保留不清理" ], "module": "report" }, { "version": "2026.08.31-report-generate-store-dimension-file-key", "date": "2026-08-31", "type": "changed", "summary": "修复「货主限制不符」缺陷(报表文件 key 与投递/通知幂等键补充货主维度隔离):systems/report.generate 上传目录由 exports/report/{report_id} 改为 exports/report/{report_id}/store-{store_id}(storeId 有效时)/ warehouse-{warehouse_id}(storeId 缺省且 warehouseId 有效时)/ common(两者均缺省,手动导出兼容兜底),避免不同货主的报表文件在 COS 上互相覆盖;reportDelivery 投递幂等键由 report:{report_definition_id}:{biz_date}:{time_point} 改为 report:{store_id}:{report_definition_id}:{biz_date}:{time_point}、文本通知幂等键 report:notify:... 同步加入 store_id 维度,并在 processOne 增加 store_id/report_definition_id 强校验(任一无效拒绝生成跨货主报表)。", "methods": [ "report.generate" ], "notes": [ "app/service/systems/report.js generate:新增 ownerSegment 计算——normalizedStoreId>0 时 store-{storeId},否则 normalizedWarehouseId>0 时 warehouse-{warehouseId},否则 common;dir 由 exports/report/{reportId} 改为 exports/report/{reportId}/{ownerSegment}(经 excel.generateAndUpload 追加 {YYYYMMDD} 日期目录与文件名),JSDoc 同步更新隔离语义", "app/service/systems/reportDelivery.js deliverByChannel:投递幂等键 idempotentKey 加入 store_id 维度(report:{store_id}:{report_definition_id}:{biz_date}:{time_point}),ext_id 幂等复用口径不变,不同货主的投递消息互不复用/串扰;sendNotifyIfConfigured:文本通知幂等键 report:notify:{store_id}:{report_definition_id}:{biz_date}:{time_point} 同步加入 store_id 维度;processOne:新增 store_id/report_definition_id 强校验(任一无效抛「投递计划维度非法(…),拒绝生成报表」),uniqueWhere 与 generate/投递调用统一使用归一化后的 normalizedStoreId/normalizedReportId", "methods/system.json 通用报表模块(module=report):report.generate description 补充上传目录按(报表定义 + 货主/仓库)隔离口径与 common 兜底、免权限说明移除已下线的 meta(仅 generate/generateTaskProgress 免权限);store_id/storeId 参数描述补货主维度隔离语义;response result 描述补 fileKey 含货主/仓库隔离目录说明;params/headers/errors/isNeedAuth/isNeedLogin 口径不变;版本 0.3.63 -> 0.3.64(docMeta.version),updatedAt 保持 2026-08-31", "docs/report-config-guide.md:第 4 节上传目录由 exports/report// 更新为按货主/仓库维度隔离的三级目录格式(store-{store_id} / warehouse-{warehouse_id} / common,含 excel.generateAndUpload 追加的 {YYYYMMDD} 日期目录);第 5 节补充投递/通知幂等键格式(含 store_id 维度)与 processOne 货主维度强校验说明", "本次仅文档同步(业务代码由开发完成),未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试;测试数据保留不清理" ], "module": "report" }, { "version": "2026.08.31-storeWarehouse.store.openAccount-remask", "date": "2026-08-31", "type": "updated", "summary": "优化 storeWarehouse.store.openAccount:未传 store_remask(或传空)时默认用公司全称填充 wms_store_warehouse.store_remask(截断 50 字符),保证货主名称在列表/导出中始终有值", "methods": [ "storeWarehouse.store.openAccount" ], "notes": [ "app/service/systems/store_warehouse.js openAccount:签约关系创建时 store_remask 兜底为 store.company_name 前 50 字符(仅当未传 store_remask 或传空时),与项目“货主名称 store_remask 优先、无备注回退 company_name”口径一致", "methods/system.json 货主-仓库签约模块(module=storeWarehouse.store):openAccount 的 store_remask 参数描述补充默认值说明,版本 0.3.62 -> 0.3.63(docMeta.version),updatedAt 保持 2026-08-31", "本次为行为变更:新开户且未传 store_remask 时签约表 store_remask 将写入公司全称;已存在的历史开户数据不受影响(如需回填需另行处理)", "未执行数据库/Redis 操作,未运行测试;测试数据保留不清理" ], "module": "storeWarehouse" }, { "version": "2026.08.31-report-meta-removed", "date": "2026-08-31", "type": "removed", "summary": "移除 report.meta(免权限只读列元数据接口):接口下线,前端获取注册字段/窗口参数改由 report.definition.typeList 提供、某报表定义勾选字段经 report.definition.list 的 fields 数组获取。", "methods": [ "report.meta" ], "notes": [ "app/service/systemMethods/report.js:删除 meta 方法(含 JSDoc);_noNeedRight/_noNeedAuth 清单移除 meta(保留 generate,generateTaskProgress),免权限口径收窄", "app/service/systems/report.js:删除 getMeta 方法(仅被 systemMethods report.meta 调用),getDefinition/resolveTypeEntry 仍被 generate/buildWorkbookSheets/定义管理复用不受影响", "app/service/systemMethods/report/definition.js、app/service/systems/report/queries/index.js、app/service/systems/report/queries/sevenDayStockFlow.js:注释中 report.meta 引用同步清理(改指 report.definition.typeList)", "methods/system.json 通用报表模块(module=report):删除 report.meta 条目,版本 0.3.61 -> 0.3.62(docMeta.version),updatedAt 保持 2026-08-31", "AI_METHOD_ROUTING.md:删除 report.meta 表格行,更新 report.generate 鉴权描述(不再提 meta),新增接口移除说明并登记变更版本", "docs/report-config-guide.md:第 7 节标题与 7.1-7.4 移除 report.meta 相关内容(响应示例/字段 selected 标记/调用步骤),保留 report.definition.typeList 并补充替代说明(窗口参数取 typeList、勾选字段取 definition.list 的 fields)", "test/report_method_layer.cjs:删除 systemMethods.report.meta 套件;test/report_systems_engine.cjs:删除 systems/report.getMeta 套件并更新文件头覆盖说明;test/scripts/verify_report_delivery_gateway.cjs:移除 report.meta 冒烟调用(generateTaskProgress 保留)", "权限说明:report.meta 原为免权限(isNeedAuth=false、无 wms_permission 记录),移除后无需任何权限回收操作", "本次为破坏性变更:前端若仍调用 report.meta 将得到 method 不存在错误,需同步改为 report.definition.typeList + report.definition.list;未执行数据库/Redis 操作,未运行测试,测试数据保留不清理" ], "module": "report" }, { "version": "2026.08.31-storeWarehouse.store.export", "date": "2026-08-31", "type": "added", "summary": "新增 storeWarehouse.store.export(提交货主签约列表异步导出任务)与 storeWarehouse.store.exportTaskProgress(按 task_id 查询导出进度与下载链接):筛选条件与 storeWarehouse.store.list 语义一致(keyword/counterparty_id/store_id/auth_status/use_status/warehouse_use_status/id),page/page_size 忽略全量导出;后台生成 26 列中文表头 Excel 并上传 COS。", "methods": [ "storeWarehouse.store.export", "storeWarehouse.store.exportTaskProgress" ], "notes": [ "app/service/systems/store_warehouse.js:抽取 buildListForStoreWhere(data, currentSubject)(仓库在 warehouse_id 方、对方货主在 store_id 方,支持 id/contract_id/relation_id、counterparty_id/store_id、auth_status、use_status/warehouse_use_status、keyword 筛选),listForStore 改用它(行为不变);新增 exportListForStore(data):复用 buildListForStoreWhere + getRelationIncludes 全量查询(updated_at/id 倒序,不翻页、无行数上限),奇门配置经 getQimenConfigMap 映射 has_qimen_config,每行经 serializeRelation 序列化并输出 needs_my_confirm;ExcelJS 流式写入 26 列中文表头(签约关系ID/货主ID/货主名称/仓库ID/仓库名称/对方主体ID/对方主体名称/对方主体角色/备注名/当前视角启用状态/货主侧启用状态/仓库侧启用状态/签约状态/签约是否有效/剩余有效天数/面单余额/锁定面单余额/授权开始时间/授权结束时间/实际结束时间/申请时间/审核时间/申请原因/审核评语/是否已配置奇门/是否需要我确认,角色/启用状态/有效性/奇门/需确认为中文展示),经 systems.upload.uploadFile 上传(key=export/store_relation/{storeId}/{timestamp}_{filename}.xlsx,mimetype xlsx,category=document)并 uploadSuccessNotify 通知,返回 filename/fileKey/url/cdnUrl/cosUrl/total_count", "app/service/systemMethods/storeWarehouse/store.js:新增 export(提交异步任务,task_id 前缀 store_relation_list_export_,setImmediate 异步执行并逐阶段回写进度:submitted→running(10)→success(100)/failed+error;失败 error 记录 message)与 exportTaskProgress(入参兼容 task_id/taskId,download_url 从 result.url/cdnUrl/cosUrl/fileKey 兜底取,task_id 缺失或缓存未命中返回 status=not_found 正常响应);generateExportTaskId 增加 options.base 自定义基础前缀(默认 print_qty_log 不变,现有 exportPrintQuantityLogs/exportStorePrintQuantityLogs 调用不受影响);systemInit 免权限声明:_noNeedRight/_noNeedAuth 加入 export,exportTaskProgress(异步任务模式,与 order.export 口径一致,无 wms_permission 记录),_noNeedLogin 不含(两接口均需登录,isNeedAuth=false、isNeedLogin=true)", "methods/system.json 货主-仓库签约模块(module=storeWarehouse.store):新增 storeWarehouse.store.export 与 storeWarehouse.store.exportTaskProgress 两个 method 条目(追加于 createUser 之后),版本 0.3.60 -> 0.3.61(docMeta.version),updatedAt 保持 2026-08-31", "AI_METHOD_ROUTING.md 本次未同步(storeWarehouse.store 相关行未覆盖导出能力,待后续补)", "权限说明:export/exportTaskProgress 免权限(无 wms_permission 记录),仅登录可用;本次未扩任何角色授权,不执行权限同步 apply", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未执行数据库/Redis 操作,未运行测试;测试数据保留不清理" ], "module": "storeWarehouse" }, { "version": "2026.08.31-workbench-queryOrder-item-packing-requirements", "date": "2026-08-31", "type": "enhanced", "summary": "workbench.business(queryOrder/query) 响应 items 每项新增 packing_requirements 字段(stock 打包要求,来自 wms_stock_warehouse.packing_requirements,经 getStockDetails 返回,未命中/异常时归一化为空字符串),纯增量字段,不破坏既有调用方。", "methods": [ "workbench.business" ], "notes": [ "app/service/systems/workbench.js _queryOrder 步骤4 items 组装:新增 1 行 packing_requirements: String(stock.packing_requirements || '').trim(),stock 未命中(stockMap 兜底 {})或 getStockDetails 异常时取值为空字符串、不抛错;与 items 既有 sku_property/stock_unit 取值风格一致", "methods/system.json workbench.business queryOrder/query 响应结构:items 字段 description 末尾追加 packing_requirements 字段说明(打包要求,来自 stock,未命中/异常时为空字符串)", "纯增量字段,params/headers/errors/权限口径(isNeedAuth=false、isNeedLogin=false)均不变,不破坏既有调用方", "methods/system.json 文档版本 0.3.59 -> 0.3.60(docMeta.version),updatedAt 更新为 2026-08-31", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "workbench" }, { "version": "2026.08.30-report-delivery-plan-copy-target-store-status", "date": "2026-08-30", "type": "changed", "summary": "report.deliveryPlan.copy 目标货主校验语义调整(放宽):目标货主有效性由仅 status=1(正常)放宽为 status 为 1 或 2(正常/审核中)均有效;其余状态(0/3 等)或已软删货主仍计入 skipped(reason「货主不存在或状态异常」文案不变);源计划校验、store_ids 校验、同源跳过、同报表定义计划跳过、通知配置不复制、enabled 原样复制等其余口径均不变。", "methods": [ "report.deliveryPlan.copy" ], "notes": [ "app/service/systems/reportDelivery.js copyPlan:目标货主存在性校验由 where: { id: { [Op.in]: candidates }, status: 1 } 调整为 status: { [Op.in]: [1, 2] }(1=正常、2=审核中均有效),软删自动排除不变;未命中者仍计入 skipped(reason「货主不存在或状态异常」文案不变);方法注释同步更新为 status 为 1 或 2(正常/审核中)均有效口径", "app/service/systemMethods/report/deliveryPlan.js copy:包装层无变化(解构 id/store_ids 透传 copyPlan),无需改动", "methods/system.json 通用报表模块(module=report):report.deliveryPlan.copy description 目标货主校验口径由「状态正常(status=1)」改为「status 为 1 或 2(正常/审核中)均有效,其余状态或已软删自动排除」;response skipped.reason 枚举「货主不存在或状态异常」name 同步更新为 status∈{1,2} 口径;params/headers/errors/权限口径不变;版本 0.3.58 -> 0.3.59(docMeta.version),updatedAt 保持 2026-08-30", "AI_METHOD_ROUTING.md:copy 相关行未提货主状态口径(仅概括「货主不存在或状态异常跳过」,与放宽后语义一致),无需改动", "权限口径不变:report.deliveryPlan.copy 与 save/list 相同(isNeedAuth=true、isNeedLogin=true),未执行权限变更、未扩大任何角色授权", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "report" }, { "version": "2026.08.30-report-delivery-plan-copy", "date": "2026-08-30", "type": "added", "summary": "新增 report.deliveryPlan.copy 批量复制接口:传入源计划ID id 与目标货主ID数组 store_ids(非空正整数数组,自动去重,兼容 storeIds 驼峰),快速复制源计划到其他货主;目标货主已存在同 report_definition_id 计划时跳过不覆盖;notify_group_ids/notify_member_ids 通知配置不复制(新计划置空);enabled 原样复制(保持复制语义),其余字段(report_definition_id/schedule_times/channel/late_grace_minutes/name/remark/notify_template)原样复制;事务批量创建,唯一键冲突单条降级 skipped。", "methods": [ "report.deliveryPlan.copy" ], "notes": [ "app/service/systemMethods/report/deliveryPlan.js copy:解构 id/store_ids(兼容 storeIds 驼峰,优先取驼峰形式,与 save 的 reportId 兼容口径一致),透传 systems.reportDelivery.copyPlan({ id, storeIds }),统一 success 包装 data={ created, skipped };systemInit 未声明免权限(_noNeedLogin/_noNeedRight/_noNeedAuth 均为空),与 save/list 同权限口径(需登录需鉴权,仅通配符角色或已授权角色可用)", "app/service/systems/reportDelivery.js copyPlan:id 必须为正整数(否则抛「计划ID无效」),findByPk 软删排除、不存在抛「计划不存在」;store_ids 经 parseJsonArray 解析为非空数组且元素为正整数并自动去重(空/非数组抛「目标货主 store_ids 必须为非空数组」,非法元素抛「目标货主 store_ids 含非法货主ID(需正整数): 」);与源计划 store_id 相同的目标计入 skipped(与源计划货主相同);wms_store 校验存在且 status=1(否则 skipped:货主不存在或状态异常);目标已存在同 report_definition_id 计划(软删排除)跳过(已存在同报表定义计划);新建 payload 中 notify_group_ids/notify_member_ids 置 null(通知配置不复制)、enabled 原样复制,其余字段原样复制;事务批量创建,并发撞 uk_store_report_definition 唯一索引时单条降级 skipped、不中断其余创建", "methods/system.json 通用报表模块(module=report):新增 report.deliveryPlan.copy 条目(description/headers/params id+store_ids+storeIds/response created+skipped(reason 枚举 与源计划货主相同/货主不存在或状态异常/已存在同报表定义计划)/errors);isNeedAuth=true、isNeedLogin=true;版本 0.3.57 -> 0.3.58(docMeta.version),updatedAt 保持 2026-08-30", "AI_METHOD_ROUTING.md 5.1 节路由表新增 report.deliveryPlan.copy 行(service 路径 app/service/systemMethods/report/deliveryPlan.js、函数 copy、需登录、需授权),并新增批量复制特性说明;变更记录列表顶部追加本版本", "权限口径不变:report.deliveryPlan.copy 与 save/list 相同(isNeedAuth=true、isNeedLogin=true),未执行权限变更、未扩大任何角色授权", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "report" }, { "version": "2026.08.30-inbox-group-members-groupids-array", "date": "2026-08-30", "type": "changed", "summary": "inbox.group.members 入参由单个 groupId 改为数组 groupIds(必填,非空且每个元素为正整数,对应 wms_inbox_group.id),一次查询多个群的成员并在消息层多群聚合去重(多群共享同一 500 条聚合池);破坏性入参变更(移除 groupId),调用方需同步升级。", "methods": [ "inbox.group.members" ], "notes": [ "app/service/systemMethods/inbox.js groupMembers:解构 groupIds 透传给 systems 层;warehouseId 仍从 ctx.user?.store_id 服务端注入(Number 化),不信任前端传值;keyword/limit 透传不变", "app/service/systems/inbox/group.js members:groupIds 校验为非空数组且每个元素为数字或可解析数字字符串的正整数(否则抛「groupIds 无效」);InboxGroup.findAll({ where: { id: { [Op.in]: groupIds }, warehouse_id } }) 批量校验群存在(软删自动排除),无匹配抛「群不存在或无权限操作」;聚合所有群外部 group_id(去重、剔空),全为空返回 { list: [] };消息按 group_id IN + warehouse_id 拉取(id 倒序、limit 500 共享聚合池、user_id 排除 NULL/空串、软删排除);按 user_id 去重取最新 user_name;keyword 对聚合结果做 user_name/user_id 小写包含过滤;截断到 limit(默认20上限100)", "methods/system.json 站内信分组(module=inbox):inbox.group.members 描述改为多群聚合语义;params 删除 groupId、新增 groupIds(array,必填,非空数组,元素为正整数,对应 wms_inbox_group.id);errors 400 由「群ID无效 / warehouseId 无效」改为「groupIds 无效 / warehouseId 无效」;headers/响应结构/权限口径不变(warehouseId 仍服务端注入、567 权限);版本 0.3.56 -> 0.3.57(docMeta.version),updatedAt 保持 2026-08-30", "AI_METHOD_ROUTING.md 5.2 节:members 底层实现描述由「groupId 必填」改为「groupIds 必填(数组,多群聚合)」;变更记录列表新增本版本", "权限不变:仍需 567(inbox.group.members,isNeedAuth=true、isNeedLogin=true),未执行权限变更", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "inbox" }, { "version": "2026.08.30-inbox-group-quicklist-dual-dim-filter", "date": "2026-08-30", "type": "changed", "summary": "inbox.group.quickList 改为双维度可选过滤:store_id(货主维度,对应 wms_inbox_group.store_id 列)与 warehouse_id(仓库维度,对应 wms_inbox_group.warehouse_id 列)均可选,可单独传、可同时传(AND),也可都不传(返回所有仓库/货主的群);本记录修正并取代 2026.08.30-inbox-group-quicklist-store-id(该版将 store_id 错误映射为 warehouse_id 列);新增 store_id 列索引迁移(待发布时执行)。", "methods": [ "inbox.group.quickList" ], "notes": [ "取代关系:本记录修正并取代 2026.08.30-inbox-group-quicklist-store-id 的口径——上一版将入参 store_id 错误映射为 wms_inbox_group.warehouse_id(仓库维度),本版明确 store_id=货主维度(对应 store_id 列)、warehouse_id=仓库维度(对应 warehouse_id 列),两维度均可选可组合,均不传时返回所有仓库/货主的群", "app/service/systemMethods/inbox.js groupQuickList:解构透传 data.store_id(storeId)与 data.warehouse_id(warehouseId)给 systems 层,不再从 ctx.user 注入任何仓库值;其余入参 keyword/groupType/limit 不变", "app/service/systems/inbox/group.js quickList:双列可选过滤——store_id(货主维度,String 化 trim 非空时 Number 化并校验 Number.isInteger 且 >0,否则抛「store_id 无效」)设置 where.store_id;warehouse_id(仓库维度,同样校验否则抛「warehouse_id 无效」)设置 where.warehouse_id;两者可同时传(AND)也可都不传(不加对应过滤条件);keyword 模糊匹配 group_name/group_id、groupType 筛选、limit 默认20上限100、created_at 倒序、软删自动排除均不变", "database/migrations/20260830150000-add-store-id-index-to-wms-inbox-group.js:为 wms_inbox_group.store_id 新增索引 idx_store_id(幂等 up/down,尚未执行,待发布时执行);warehouse_id 维度已由 uk_warehouse_group_id(warehouse_id, group_id) 前导列覆盖,双条件 AND 由两索引组合命中", "methods/system.json 站内信分组(module=inbox):inbox.group.quickList 描述改为双维度可选过滤口径;params 修正 store_id(货主维度,对应 store_id 列)并新增 warehouse_id(可选正整数,对应 warehouse_id 列);errors 400 由「store_id 无效」改为「store_id 无效 / warehouse_id 无效」;headers 保持登录凭证口径(不从中解析仓库上下文);版本 0.3.55 -> 0.3.56(docMeta.version),updatedAt 保持 2026-08-30", "AI_METHOD_ROUTING.md 5.2 节:quickList 底层实现与仓库口径改为双维度口径(store_id=货主维度 / warehouse_id=仓库维度,均可选可组合、不传返回全部、不再从登录上下文注入),变更记录列表新增本版本并标注修正/取代上一版", "权限不变:仍需 566(inbox.group.quickList,isNeedAuth=true、isNeedLogin=true),未执行权限变更", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "inbox" }, { "version": "2026.08.30-inbox-group-quicklist-store-id", "date": "2026-08-30", "type": "changed", "summary": "inbox.group.quickList 新增可选入参 store_id(对应 wms_inbox_group.warehouse_id):传入时仅返回该仓库的群,不传或为空时返回所有仓库的群;旧口径「warehouseId 由服务端从登录上下文自动注入、不信任前端传值」作废,改为透传前端入参 store_id。", "methods": [ "inbox.group.quickList" ], "notes": [ "app/service/systemMethods/inbox.js groupQuickList:不再从 ctx.user.store_id 自动注入 warehouseId,改为解构透传 data.store_id(storeId)给 systems 层;其余入参 keyword/groupType/limit 不变", "app/service/systems/inbox/group.js quickList:storeId 可选(String(data.storeId ?? '').trim() 非空时 Number 化并校验 Number.isInteger 且 >0,否则抛「store_id 无效」);传入时 where.warehouse_id = storeId 过滤,不传或为空时不加 warehouse_id 过滤、返回所有仓库的群;keyword 模糊匹配 group_name/group_id、groupType 筛选、limit 默认20上限100、created_at 倒序、软删自动排除均不变", "methods/system.json 站内信分组(module=inbox):inbox.group.quickList 描述删除「warehouseId 由服务端从登录上下文自动注入」,补 store_id 口径(可选正整数,对应 warehouse_id,不传返回全部);params 新增 store_id(number|string,可选);errors 400 由「warehouseId 无效」改为「store_id 无效」;headers 描述改为登录凭证口径(不再从中解析 warehouseId 仓库上下文);版本 0.3.54 -> 0.3.55(docMeta.version),updatedAt 保持 2026-08-30", "AI_METHOD_ROUTING.md 5.2 节:quickList 底层实现补 store_id 口径;仓库口径拆分为「quickList 透传前端 store_id(不再服务端注入)/ members 仍从 ctx.user.store_id 服务端注入」", "权限不变:仍需 566(inbox.group.quickList,isNeedAuth=true、isNeedLogin=true),未执行权限变更", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "inbox" }, { "version": "2026.08.30-report-delivery-plan-name-field", "date": "2026-08-30", "type": "enhanced", "summary": "投递计划新增计划名称 name 字段:report.deliveryPlan.save 新增可选入参 name(string|null;未传不覆盖,null/空串/全空白归一化为 null 显式清空,非空 trim 后 ≤100 超长报错),save 成功响应与 report.deliveryPlan.list 列表项新增 name 字段(缺省空串);name 仅展示字段,不参与幂等/关联逻辑。", "methods": [ "report.deliveryPlan.save", "report.deliveryPlan.list" ], "notes": [ "app/service/systems/reportDelivery.js:新增 normalizePlanName(value)(undefined=未传不覆盖返回 undefined;null/空串/全空白返回 null 显式清空;非空 trim 且 ≤PLAN_NAME_MAX_LENGTH(100),超长抛「计划名称 name 长度不能超过 100 字符」);savePlan 仅在 name !== undefined 时规范化并写入 payload.name,更新时不误清空", "app/service/systems/reportDelivery.js planToView:响应视图新增 name: String(plan.name || '')(缺省空串),save 成功响应与 list 列表项均带该字段", "app/service/systemMethods/report/deliveryPlan.js save:解构透传 name(仅入参存在时附加 saveArgs.name,保持旧调用形状与既有回归断言一致)", "wms_report_delivery_plan 新增 name 列(STRING(100) allowNull,comment「计划名称(前端展示用,缺省时可用报表名称兜底)」;迁移 20260830130000-add-name-to-wms-report-delivery-plan 已完成);name 仅展示字段,不参与 store_id+report_definition_id 幂等/关联逻辑", "methods/system.json 通用报表模块:report.deliveryPlan.save params 新增 name(string|null)、response 新增 name(缺省 '')、errors 新增「计划名称 name 长度不能超过 100 字符」;report.deliveryPlan.list response children 新增 name;版本 0.3.53 -> 0.3.54(docMeta.version),updatedAt 保持 2026-08-30", "docs/report-config-guide.md 第 5 节投递计划补 name 字段口径与保存示例;AI_METHOD_ROUTING.md 5.1 节补 name 变更条目与最新 changes 版本", "权限口径不变:report.deliveryPlan.save/list 仍 isNeedAuth=true(未声明免权限),仅执行 npm run permission:sync:system-api -- --dry-run 预演(不 apply、不扩任何角色授权)", "本次仅文档同步,未修改 app/ 下业务代码,未执行数据库/Redis 操作,未运行测试" ], "module": "report" }, { "version": "2026.08.30-report-type-list-merge-into-definition", "date": "2026-08-30", "type": "changed", "summary": "枚举接口并入 definition:report.type.list → report.definition.typeList。免权限只读的类型注册清单查询由独立模块 report/type.js 并入 report/definition.js(typeList 方法,systemInit 声明 _noNeedRight/_noNeedAuth/_noNeedLog='typeList',仅要求登录);同模块 save/list/delete 仍需授权。", "methods": [ "report.definition.typeList", "report.type.list" ], "notes": [ "app/service/systemMethods/report/type.js 已删除;app/service/systemMethods/report/definition.js 新增 typeList(data) 方法(无必填入参,忽略请求体),返回 success('ok', { list }),list 由 systems/report.js listRegisteredTypes() 提供(QUERIES.describe() 注册表全量描述,当前仅 stockFlow)", "权限口径:definition.js systemInit 声明 _noNeedRight/_noNeedAuth/_noNeedLog='typeList'(免权限/免鉴权/免审计日志,仅要求登录);同模块 save/list/delete 未声明免权限,仍需授权(isNeedAuth=true),同一模块内权限口径差异已在 method description 中注明", "methods/system.json 通用报表模块:删除 report.type.list,新增 report.definition.typeList(isNeedAuth=false、isNeedLogin=true、无入参;响应 { list: [{key,title,description,window:{dayCount,cutoverHour},fields:[{key,label,type,computed?,asText?,children?}]}] },字段口径与原 report.type.list 一致);版本 0.3.52 -> 0.3.53(docMeta.version),updatedAt 保持 2026-08-30", "docs/report-config-guide.md:report.type.list 全部替换为 report.definition.typeList(第 2/7 节标题、字段口径说明、请求/响应示例与设计器接口链),实现链由 report/type.js 改为 report/definition.js;AI_METHOD_ROUTING.md report 能力清单更新(report.definition.typeList → definition.js typeList)", "权限仅执行 npm run permission:sync:system-api -- --dry-run 预演(不 apply、不扩任何角色授权)", "本次仅文档同步(含文档脚本 update-api-doc.cjs 的 deleteMethods 能力扩展与缩进检测修正),未修改 app/ 下业务代码,未执行数据库/Redis 操作,未运行测试" ], "module": "report" }, { "version": "2026.08.30-report-definition-model-refactor", "date": "2026-08-30", "type": "changed", "summary": "报表定义模型重构:code→id 关联、type/fields 极简配置、注册表 stockFlow、新增 report.type.list。破坏性变更:report.generate/report.meta/report.deliveryPlan.* 的 report_code 入参全部替换为 report_id(=报表定义ID,兼容 reportId 驼峰),前端需同步改 report_id。", "methods": [ "report.generate", "report.meta", "report.type.list", "report.definition.save", "report.definition.list", "report.definition.delete", "report.deliveryPlan.save", "report.deliveryPlan.list", "report.deliveryLog.list" ], "notes": [ "模型重构(app/model/report_definition.js):移除 code/scope/description 与 output_config/source_config/sheet_config 三段 JSON 配置列,改为 name/type/file_name/fields/is_enabled/remark + 主键 id(唯一性由 id 承担,删除 uk_code);投递计划/记录表外键由 report_code 改为 report_definition_id,投递记录新增 report_name 名称快照", "app/service/systemMethods/report.js:generate/meta 入参 report_code 改为 report_id(reportId 驼峰优先);meta 响应由 report_code/name/scope/query/window/fields 改为 report_id/name/type/file_name/window/fields(fields 新增 selected 勾选标记与 asText 标记);generateTaskProgress 不变", "新增 app/service/systemMethods/report/type.js:report.type.list 免权限只读(systemInit 声明 _noNeedRight/_noNeedAuth/_noNeedLog 含 list,仅要求登录),返回注册类型清单 [{key,title,description,window:{dayCount,cutoverHour},fields:[{key,label,type,computed,asText,children}]}];当前仅注册 stockFlow(标题「库存变化以及补货报表」)", "app/service/systemMethods/report/definition.js:save 入参 {id?,name,type,file_name/fileName,fields,is_enabled,remark}(type 必须命中注册表、fields 必须为该类型注册字段子集,非法 key 报可读错误并列出可用字段;新增必填 type/file_name/fields);list where 改 name/type/is_enabled,sort 白名单 id/name/type/is_enabled/created_at/updated_at;delete 入参 id,引用拦截按 report_definition_id 统计启用中计划", "app/service/systems/report.js:新增 listRegisteredTypes/resolveTypeEntry/validateTypeFields,saveDefinition/listDefinitions/deleteDefinition 按 id 重写;渲染由 app/lib/report/render.js renderSheetByType 按类型硬编码字段规格完成(asText 由类型字段规格硬编码自动应用,string 字段 asText=true 时落地文本单元格),sheet_config 已删除", "app/service/systems/reportDelivery.js:savePlan/listPlans/listLogs 关联键由 report_code 改为 report_definition_id,listLogs 响应新增 report_name 快照;幂等键与唯一索引 uk_store_report_definition 同步改为 report_definition_id", "methods/system.json 通用报表模块:report.generate/report.meta/report.definition.save/report.definition.list/report.definition.delete/report.deliveryPlan.save/report.deliveryPlan.list/report.deliveryLog.list 8 个 method 按新形态重写,新增 report.type.list(report.generateTaskProgress 不受影响保持原样);版本 0.3.51 -> 0.3.52(docMeta.version),updatedAt 保持 2026-08-30", "docs/report-config-guide.md 整体改写(注册类型 stockFlow 标题/描述/16 字段表、report.type.list 用法、definition 保存示例 fileName+type+fields、plan 用 report_id、删除 sheet_config/asText 旧说明并按新渲染规则改写);AI_METHOD_ROUTING.md report 能力清单刷新", "权限口径:report.type.list 免权限(isNeedAuth=false);其余 report.* 沿用既有授权口径(管理类接口 isNeedAuth=true);仅执行 npm run permission:sync:system-api -- --dry-run 预演,未 apply、未扩任何角色授权", "本次仅文档同步,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "report" }, { "version": "2026.08.30-order-export-create-channel-column", "date": "2026-08-30", "type": "enhanced", "summary": "订单导出(order.export)waybill/item 两种导出模式在「平台」列之后新增导出列「来源」(字段 create_channel,中文取值:手工单/接口/奇门/出库转单);该列已自动纳入导出表头白名单 ORDER_EXPORT_ALL_COLUMN_HEADERS(waybill/item 两模式列头并集),export_columns/exportColumns 入参已支持传「来源」,不传或空数组时默认输出全部列。", "methods": [ "order.export" ], "notes": [ "app/service/systems/order_export.js:ORDER_EXPORT_COLUMNS(waybill 模式)与 ORDER_EXPORT_ITEM_COLUMNS(item 模式)均在「平台」(sys_platform_name)之后新增 { header: '来源', key: 'create_channel', width: 12 }", "ORDER_EXPORT_ALL_COLUMN_HEADERS 为 waybill/item 两模式列头并集(Object.freeze(new Set(...))),「来源」在列配置登记后自动可用:export_columns/exportColumns 传「来源」合法(校验不区分导出模式),不传或空数组时输出全部列(含来源)", "取值翻译:app/service/systemMethods/order/base.js CREATE_CHANNEL_LABELS = { MANUAL: '手工单', API: '接口', QM: '奇门', STOCKOUT: '出库转单' },formatCreateChannelLabel 未命中映射时原样返回 create_channel 原文", "methods/system.json:order.export 的 export_columns/exportColumns 参数描述中枚举由 51 个更新为 52 个(在「平台」之后插入「来源」),并补充来源列取值、位置(平台列之后)与两种模式均输出的说明;order.exportTaskProgress 无导出列枚举内容,无需改动", "methods/system.json 版本 0.3.50 -> 0.3.51(docMeta.version),updatedAt 2026-08-29 -> 2026-08-30", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作,未运行测试" ], "module": "order.index" }, { "version": "2026.08.29-waybill-warehouse-waybillCode-array-exact-match", "date": "2026-08-29", "type": "enhanced", "summary": "运单列表与导出接口的 where.waybillCode 支持字符串数组精确匹配:waybill.warehouse.list / waybill.warehouse.export 的 where.waybillCode 由「仅字符串模糊搜索」扩展为「字符串模糊搜索(LIKE '%值%',向后兼容)/ 字符串数组精确匹配(Op.in,元素自动 trim 并过滤空值,空数组或全空值不加该筛选条件)」,修复此前数组入参被逗号拼接后做 LIKE 导致搜索无结果的问题。", "methods": [ "waybill.warehouse.list", "waybill.warehouse.export" ], "notes": [ "app/service/systems/waybill.js list() 第 226-235 行:where.waybillCode 为数组时先逐元素 String 化并 trim、过滤空值,非空则 waybill_code = { [Op.in]: waybillCodeList } 精确匹配;字符串时保持 waybill_code = { [Op.like]: '%trim%', } 模糊匹配(向后兼容)", "export 的筛选条件构建(第 767-776 行)与 list 逻辑一致:数组 Op.in 精确匹配、字符串 Op.like 模糊匹配", "修复前行为:数组入参会被逗号拼接后进入 LIKE 分支,导致搜索无结果;修复后数组元素 trim 并过滤空值,空数组/全空值不加 waybill_code 筛选条件", "methods/system.json:waybill.warehouse.list 与 waybill.warehouse.export 的 where.waybillCode 参数 type 由 string 更新为 string|string[],description 补充字符串模糊搜索与字符串数组精确匹配(元素 trim、过滤空值)规则", "methods/system.json 版本 0.3.49 -> 0.3.50(docMeta.version),updatedAt 保持 2026-08-29", "本次仅文档同步,业务代码已由开发侧修复(app/service/systems/waybill.js),未修改 app/ 下任何代码,未执行数据库/Redis 操作" ], "module": "waybill.warehouse" }, { "version": "2026.08.29-order-packing-quickWhere-short-kw-guard", "date": "2026-08-29", "type": "enhanced", "summary": "order.packing.list 的 where.quickWhere 运单号降级模糊新增关键词长度校验:精确未命中后仅当 trim 后关键词长度 ≥ 4(QUICK_WHERE_WAYBILL_FUZZY_MIN_LENGTH)才降级 LIKE '%kw%' 模糊查询;长度 < 4 的短词(含单字符)禁止降级、运单号解析直接返回空结果(避免 %短词% 误命中海量历史单号);波次号模糊逻辑不变。", "methods": [ "order.packing.list" ], "notes": [ "app/service/systems/order_packing.js 第 12 行模块常量 QUICK_WHERE_WAYBILL_FUZZY_MIN_LENGTH = 4:注释说明短于该长度的输入(如单字符 \"7\")没有模糊搜索意义且 %短词% 极易误命中海量历史单号(实测 \"7\" 可命中 24149 行),因此禁止短词降级进入 %kw% 模糊分支", "list() 的 where.quickWhere 分支:波次号直接 LIKE '%kw%' 模糊不变;运单号先按「完整单号等值 + 剥离分段后缀主体等值 + 主体前缀 LIKE '主体-%'」精确集合查询 wms_order_express,第 206 行条件 expressRecords.length === 0 && kw.length >= QUICK_WHERE_WAYBILL_FUZZY_MIN_LENGTH 才降级 waybill_code LIKE '%kw%';短词(长度 < 4)不进入模糊分支,运单号解析保持空结果(仅保留波次号模糊条件)", "list() JSDoc 第 64 行 where.quickWhere 描述已同步:精确未命中且关键词长度≥4 时才降级模糊,短词禁止降级避免误命中", "methods/system.json:order.packing.list 的 where.quickWhere 参数描述补充「精确未命中且关键词长度 ≥ 4 才降级 %kw% 模糊;长度 < 4 短词不降级、直接返回空;波次号模糊不变」规则", "methods/system.json 版本 0.3.48 -> 0.3.49(docMeta.version),updatedAt 保持 2026-08-29", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作" ], "module": "order.packing" }, { "version": "2026.08.29-wave-batchCancel-pick-status-guard", "date": "2026-08-29", "type": "enhanced", "summary": "取消波次增加拣货状态校验:order.wave.batchCancel 提交前新增两道业务校验(code 400)——波次内存在拣货中或拣货完成(pick_status 为 padding/fin)的订单、或波次状态已进入拣货及后续环节(wms_wave_batch.wave_status >= 3)时禁止取消波次;runBatchCancelTask 异步兜底命中上述条件跳过该波次并继续处理其余波次;order.wave.batchCancelTaskProgress 任务结果新增 skipped_wave_ids / skipped_wave_count / skipped_waves 字段。", "methods": [ "order.wave.batchCancel", "order.wave.batchCancelTaskProgress" ], "notes": [ "app/service/systemMethods/order/wave.js batchCancel():活动拣货任务校验后新增两道 400 校验——① getOrderModel('pendingOrder', warehouseId) 查询波次内 pick_status IN ('padding','fin') 的订单,命中返回「波次内存在已拣货完成或拣货中的订单,禁止取消波次」(附 wave_ids 与最多前 20 个 order_ids);② 查询 wms_wave_batch 中 wave_status >= 3 的波次,命中返回「波次已进入拣货或后续环节,禁止取消波次」(附 wave_ids)", "runBatchCancelTask():目标波次查询新增 wave_status 列;逐波次处理时先校验 wave_status >= 3(跳过明细 reason=wave_status_blocked,附 wave_status),再在事务内校验波次内 pick_status IN ('padding','fin') 的订单(reason=picked_orders_exist,附 picked_order_count),命中则回滚事务、跳过该波次并继续处理其余波次;无目标波次时 result 返回空 skipped_wave_ids 数组与 skipped_wave_count=0", "任务结果:success 与 failed 终态的 result 均新增 skipped_wave_ids(被跳过波次 ID 列表)、skipped_wave_count(数量)、skipped_waves(明细数组,字段 wave_id/wave_no/reason/wave_status/picked_order_count,其中 wave_status 仅 reason=wave_status_blocked、picked_order_count 仅 reason=picked_orders_exist)", "methods/system.json:order.wave.batchCancel 的 description 补充校验规则说明、errors 新增两条 400 描述;order.wave.batchCancelTaskProgress 的 description 与 response 补充 skipped_wave_ids / skipped_wave_count / skipped_waves 字段说明(含 children 明细),并同步更新 result 字段描述(补充 ids/affected_wave_ids/affected_order_count/skipped_* 等字段枚举)", "methods/system.json 版本 0.3.47 -> 0.3.48(docMeta.version),updatedAt 保持 2026-08-29", "本次仅文档同步,业务代码改动已完成(git diff app/service/systemMethods/order/wave.js),未修改 app/ 下任何代码,未执行数据库/Redis 操作" ], "module": "order.wave" }, { "version": "2026.08.29-order-packing-waybill-code-match", "date": "2026-08-29", "type": "enhanced", "summary": "打包获取订单与订单快捷搜索的运单号匹配规则收敛:order.packing.list 的 where.waybill_code 由默认「%值%」模糊匹配改为「完整单号等值 + 剥离 -1-1- 分段后缀后主体单号等值 + 主体前缀 LIKE '主体-%'」精确匹配(不再支持部分单号模糊,无匹配返回空);quickWhere 运单号解析先按上述等值集合精确匹配、精确未命中才降级为 %kw% 模糊查询,波次号模糊逻辑不变;order.deliveryOrder.quickSearch 运单号条件同步扩展为「完整等值 + 主体等值 + 主体前缀 LIKE」,运单号不再落入模糊分支,发货单号/原始平台订单号模糊匹配不变(平台交易单号 pay_no 仅回显不参与匹配,修正文档过期描述)。", "methods": [ "order.packing.list", "order.deliveryOrder.quickSearch" ], "notes": [ "新增公共工具 app/lib/waybill_code.js:stripWaybillSegmentSuffix 剥离运单号尾部一单多件包裹序号分段(正则 /(?:-\\d+){2,}-?$/,如 JDX057941864338-1-1- → JDX057941864338,无分段原样返回);escapeLikeWildcards 转义 like 通配符 % _ \\,保证主体前缀匹配的主体部分被等值比较", "app/service/systems/order_packing.js list():where.waybill_code 通过 wms_order_express 解析 order_id(wms_pack_task.waybill_code 通常为空),条件集合为 [waybill_code=完整单号, waybill_code=剥离后缀后主体, waybill_code LIKE '转义主体-%'] 的 OR 组合,命中后按 order_id IN 过滤,无命中强制空结果(queryWhere.id=-1);不再使用 like '%值%' 模糊匹配", "order_packing.js list() 的 where.quickWhere:波次号直接 LIKE '%kw%' 模糊不变;运单号解析先按上述精确集合查询,expressRecords 为空才降级为 waybill_code LIKE '%kw%'(兼容输入部分单号场景);团购按 wave_no、散单按 order_id 查询链路不变", "app/service/systemMethods/order/deliveryOrder.js quickSearch():express 表 OR 条件中运单号扩展为 [完整等值, 主体等值, 主体前缀 LIKE '主体-%'],运单号不再落入 %kw% 模糊分支;delivery_order_code / source_order_codes 仍为 LIKE '%kw%' 模糊匹配;pay_no 不在搜索条件中(仅第三步订单详情输出回显),原文档「平台交易单号 pay_no(模糊)」为过期描述已按实现修正", "methods/system.json:order.packing.list 的 where.waybill_code 描述由「运单号(模糊匹配)」改为完整单号/剥离分段后缀主体/主体前缀三种匹配规则说明,quickWhere 描述补充「先精确后降级模糊」优先级;order.deliveryOrder.quickSearch 的 description 与 keyword 参数描述同步修正(express 表匹配口径、pay_no 仅回显);quickSearch 条目补充空 headers 数组以符合文档校验结构", "methods/system.json 版本 0.3.46 -> 0.3.47(docMeta.version),updatedAt 保持 2026-08-29", "本次仅文档同步,业务代码由 wms-dev-agent 完成,未修改 app/ 下任何代码,未执行数据库/Redis 操作" ], "module": "order.packing" }, { "version": "2026.08.29-return-unpack-max-record-minutes", "date": "2026-08-29", "type": "enhanced", "summary": "仓库设置新增「拆包最大录制时长」配置 return_unpack_max_record_minutes(分钟,默认 5,min 1):returnUnpack.submit 提交确认时,结束时间超过 开始时间+配置上限 时自动截断为上限时间点", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.getFieldMeta", "setting.warehouse.saveSettings", "returnUnpack.submit" ], "notes": [ "app/service/systems/setting/warehouse.js WAREHOUSE_SETTING_FIELDS 新增 return_unpack_max_record_minutes(名称:拆包最大录制时长(分钟),type integer,非必填,默认 5,min 1,描述:超过上限时提交的结束时间自动截断为开始时间+上限),与 single_order_pack_max_minutes(默认 3)/ group_order_pack_max_minutes(默认 40)并列;getFieldMeta 自动返回该字段元信息", "app/model/store.js DEFAULT_SUBJECT_CONFIG 增加 return_unpack_max_record_minutes: 5;normalizeSubjectConfig 非法值(非正整数)抛「subject_config.return_unpack_max_record_minutes 必须是大于 0 的整数」,空值回退默认 5", "app/service/systems/return_unpack.js submit() 新增私有方法 _resolveSubmitEndTime:候选 end_time 超过 start_time + 配置上限分钟时截断为上限时间点并记录 info 日志;配置读取 ctx.service.systems.deliveryOrder.getStoreSubjectConfig,配置非法/读取失败/start_time 缺失时不约束;其余行为不变(completed 终态、回写 is_back=1、货主群通知等均不变)", "methods/system.json:setting.warehouse.getSettings 响应与 setting.warehouse.saveSettings 入参新增 subject_config.return_unpack_max_record_minutes 字段文档;returnUnpack.submit description 与响应 record 补充「结束时间超过仓库配置的拆包最大录制时长上限时自动截断为开始时间+上限」语义;getFieldMeta 为通用字段元信息结构,无逐字段清单,无需改动", "向后兼容:新增字段可选,不影响既有仓库设置读写;本次仅文档同步,业务代码由 wms-dev-agent 完成", "methods/system.json 版本 0.3.45 -> 0.3.46(docMeta.version),updatedAt 保持 2026-08-29" ], "module": "returnUnpack" }, { "version": "2026.08.29-returnUnpack.export", "date": "2026-08-29", "type": "enhanced", "summary": "新增退回拆包导出与进度查询接口:returnUnpack.export(提交异步导出任务,入参 where/sort 语义与 returnUnpack.list 一致,warehouse_id 由服务端注入 ctx.user.store_id;后台生成双 Sheet Excel:Sheet1 正常退回运单号列表、Sheet2 明细表并上传)与 returnUnpack.exportTaskProgress(按 task_id 查询任务进度与下载链接,未命中返回 status=not_found)。任务缓存 Redis TTL 30 分钟,状态口径 submitted→running→数据拉取(10~30)→明细拉取(30~50)→Excel(55~90)→上传(92)→success(100),失败 failed+error。两接口免权限免日志口径与 order.export 一致(isNeedAuth=false、isNeedLogin=true)。", "methods": [ "returnUnpack.export", "returnUnpack.exportTaskProgress" ], "notes": [ "app/service/systemMethods/returnUnpack.js 新增 export/exportTaskProgress 与任务缓存辅助方法(generateExportTaskId/normalizeExportTaskId/setExportTaskProgress/getExportTaskProgress):缓存键前缀 return_unpack_export_task_,Redis TTL 1800 秒(30 分钟);export 提交后 setImmediate 异步执行并逐阶段回写进度;exportTaskProgress 入参兼容 task_id/taskId,download_url 从 result.url/cdnUrl/cosUrl/fileKey 兜底取(代码中同时兼容 cndUrl 拼写);task_id 为空或缓存未命中返回 status=not_found(正常响应非报错)", "systemInit 免权限声明:_noNeedRight/_noNeedAuth/_noNeedLog 均含 export,exportTaskProgress(异步任务模式,与 order.export 口径一致,无 wms_permission 记录);_noNeedLogin 不含(两接口均需登录,isNeedAuth=false、isNeedLogin=true)", "app/service/systems/return_unpack.js 新增 exportUnpack:复用 _buildListWhere/_buildListOrder(与 list 语义一致)并强制 warehouse_id=注入值;主表全量分页拉取(每页 500,无行数上限),明细按 unpack_id 分批(每批 100)拉取;货主名批量映射 wms_store.company_name、快递类型映射 wms_order_express.logistics_name(各自独立 try/catch,解析失败降级为空字符串不阻断导出)", "双 Sheet 结构:Sheet1「正常退回运单号列表」列=货主/快递号/商品类数/商品总数/记录人员/记录日期/开始时间/结束时间/是否原单(是/否)/快递类型/自定义店铺/平台单号;Sheet2「明细表」列=货主/快递号/商品名称/商品编码/条码/颜色/规格/数量/是否残次(是/否)/记录人员ID/记录日期/备注/是否原单(是/否)/快递类型/自定义店铺/平台单号;颜色取自明细 product_snapshot.sku_property 中「颜色:xxx」片段(兜底 spec 字段),无颜色信息为空;是否原单按 order_express_id 有值输出是/否;是否残次按 product_status=damaged 输出是/否", "导出上传:ExcelJS 流式写入临时文件后经 systems.upload.uploadFile 上传(key=exports/return_unpack/{warehouseId}/{timestamp}_{token}.xlsx,mimetype xlsx,category=document),结果含 filename/url/fileKey/cdnUrl/cosUrl/current_count/total_count/total_details/sheet_count=2;Sheet1 不加 status 过滤(如需只导特定状态由调用方传 where.status)", "methods/system.json 退回拆包模块(module=returnUnpack)新增 returnUnpack.export 与 returnUnpack.exportTaskProgress 两个 method 条目(追加于 returnUnpack.delete 之后),版本 0.3.44 -> 0.3.45(docMeta.version),updatedAt 保持 2026-08-29", "权限说明:export/exportTaskProgress 免权限(无 wms_permission 记录),仅登录可用;本次仅文档、未扩任何角色授权,不执行权限同步 apply", "仅文档变更,未改任何业务代码、表结构,未执行数据库/Redis 操作" ], "module": "returnUnpack" }, { "version": "2026.08.29-report-channel-normalize-doc-audit", "date": "2026-08-29", "type": "docs", "summary": "渠道默认值归一化 inbox + 文档一致性校对:全量核对「通用报表模块」全部 report.* method(generate/generateTaskProgress/meta/deliveryPlan.save/list/deliveryLog.list/definition.save/list/delete)与当前实现(app/service/systemMethods/report.js 及 report/ 子目录、app/service/systems/report.js、app/service/systems/reportDelivery.js、模型 report_definition/report_delivery_plan/report_delivery_log、迁移 20260829170000),仅发现 report.deliveryPlan.list / report.deliveryLog.list 响应 channel 字段存在过期描述(wecom/inbox/link),已修正为仅 inbox;其余 method 的 params/response/errors 均与实现一致,无接口行为变化。", "methods": [ "report.deliveryPlan.list", "report.deliveryLog.list" ], "notes": [ "迁移 database/migrations/20260829170000-normalize-report-channel-to-inbox.js:wms_report_delivery_plan / wms_report_delivery_log 的 channel 默认值 wecom → inbox、comment 收敛,存量 channel IN (wecom,link) 统一 UPDATE 为 inbox;模型同步(app/model/report_delivery_plan.js、app/model/report_delivery_log.js defaultValue: inbox)", "代码核对:app/service/systems/reportDelivery.js 的 DELIVERY_CHANNELS 收敛为 [inbox]、DEFAULT_CHANNEL=inbox;deliverByChannel 对非 inbox 渠道记录 warn 日志后按 inbox 兜底投递(不抛错);inbox 推送失败(success=false 或 push_status=3)立即经 ctx.service.inbox.message.retry 重推一次,重推失败进入 failed 退避重试(MAX_RETRY=3,退避 retry_count × 60s)", "修正点:report.deliveryPlan.list / report.deliveryLog.list 响应 channel 字段描述由「投递渠道:wecom/inbox/link」修正为「投递渠道:inbox(渠道已收敛,仅支持 inbox;历史数据已由迁移 20260829170000 归一化)」;仅文档描述修正,params/response 结构、错误码无任何变化", "report.definition.save 的 19 条错误、report.definition.list 排序白名单 id/code/name/scope/is_enabled/created_at/updated_at、notify_template(≤500,标签白名单 {time}/{url}/{report_name}/{biz_date})/notify_group_ids(正整数去重 ≤20,校验存在性排除软删)/notify_member_ids(非空字符串去重 ≤100)参数与校验规则均与代码一致,未改动", "report.generate/report.generateTaskProgress 免权限(_noNeedRight/_noNeedAuth 声明)、report.meta 免权限但保留审计日志(未列入 _noNeedLog)、report.deliveryPlan.*/report.deliveryLog.list/report.definition.* 需授权(isNeedAuth=true,未声明免权限)口径均与 systemInit 声明一致", "methods/system.json 版本 0.3.43 -> 0.3.44(docMeta.version),updatedAt 保持 2026-08-29", "配套文档核对:docs/report-config-guide.md 第 5 节渠道说明已与「仅 inbox + 兜底 + 重推」一致(补充迁移归一化说明);第 8 节 report.definition.save/list/delete 用法与实现一致;AI_METHOD_ROUTING.md 5.1 report 能力速查与路由说明已最新", "权限:仅执行 npm run permission:sync:system-api -- --dry-run 预演缺口,未执行 apply、未扩任何角色授权", "仅文档变更,未改任何业务代码、表结构,未执行数据库/Redis 操作" ], "module": "report" }, { "version": "2026.08.29-report-definition-management", "date": "2026-08-29", "type": "enhanced", "summary": "通用报表模块新增报表定义管理接口:report.definition.save/list/delete(wms_report_definition 管理侧 CRUD,均需登录且需鉴权 isNeedAuth=true,未扩任何角色授权)。save 按 code upsert(未传字段不覆盖),code 格式 ^[a-z][a-z0-9_]{1,63}$(长度 2-64)、name 必填 ≤100、scope 枚举 warehouse/store/open(默认 warehouse),output_config/source_config/sheet_config 三段 JSON 配置支持对象或 JSON 字符串,source_config.query 须为注册表已有查询器,sheet_config 列结构校验(static/expand/computed,expand pair 与查询器字段清单对齐),response 平铺 report_code;list 支持 where{code,name,scope,is_enabled}(code/name 模糊、scope/is_enabled 精确)/pagination/sort(白名单 id/code/name/scope/is_enabled/created_at/updated_at),response 全量字段含三段 JSON 配置;delete 按 code 软删(幂等),启用中的投递计划引用时拦截「存在 N 个启用的投递计划引用该报表,请先停用计划」。", "methods": [ "report.definition.save", "report.definition.list", "report.definition.delete" ], "notes": [ "app/service/systemMethods/report/definition.js 新增:save/list/delete 仅做出口包装与参数解构(save 仅附加入参中存在的字段,undefined 不进入参数对象,保持「未传不覆盖」语义;list 经 prepareWhereContext 解析 where 后取 code/name/scope/is_enabled),业务逻辑下沉 app/service/systems/report.js saveDefinition/listDefinitions/deleteDefinition", "saveDefinition:code 规范化 trim 后校验(空/格式非法分别报「报表编码 code 不能为空」「报表编码 code 格式非法:须以小写字母开头,仅含小写字母/数字/下划线,长度 2-64」,正则 ^[a-z][a-z0-9_]{1,63}$);name trim 必填 ≤100;scope 枚举校验;JSON 字段仅非 undefined 时经 parseRequiredJson 解析(对象原样返回/JSON 字符串解析/其余报「 解析失败:须为对象或合法 JSON 字符串」);source_config 的 query 必须为注册表已有查询器(resolveQueryKey 缺省 generic,未知报「未知的报表查询器: 」);sheet_config 经 validateDefinitionSheetConfig 校验列结构(columns 数组、列类型仅 static/expand/computed、static 列须有 field 或 value、computed 列须有 field 或 formatter、expand pair 须与查询器静态字段清单对齐否则报「sheet_config expand 列 pair 元素 '' 不在查询器 的字段清单中(可用: )」);is_enabled 仅 0/1;description/remark ≤500 截断", "upsert 细节:uk_code 唯一索引含 deleted_at,findOne 以 paranoid:false 完整查重;命中软删记录先 restore 再 update(restore 撞唯一索引报「存在多个同名已删除记录,无法自动恢复,请更换报表编码」);并发首次创建撞 SequelizeUniqueConstraintError 降级为重查并更新(查不到报「报表编码已存在,保存冲突,请重试」);保存成功返回 definitionToView 视图(JSON 字段解析为对象)", "listDefinitions:code/name LIKE 模糊(escapeLike 转义 \\%_)、scope 精确(非法报「scope 仅支持 warehouse/store/open,非法: 」)、is_enabled 空值不过滤(Number 化 0/1);pagination page≥1、pageSize 夹取 1-200;sort 白名单 id/code/name/scope/is_enabled/created_at/updated_at(sortField/sortOrder 兼容 sort_field/sort_order 别名,非法字段回退 id DESC);findAll+count 并行,raw 行映射 definitionToView", "deleteDefinition:先按 report_code+enabled=1 统计 wms_report_delivery_plan 启用中引用(>0 报「存在 个启用的投递计划引用该报表,请先停用计划」),停用计划不阻断;再按 code paranoid:false 查定义(不存在报「报表定义不存在: 」,已软删幂等返回 deleted=1),否则 destroy 软删", "method 层统一 catch 后 this.fail(error.message):错误响应 code=0、flag=failure(与 report.meta 惯例一致);save/delete 成功响应将定义 code 平铺为 report_code(避免覆盖统一响应 code=1)", "systemInit 未声明 _noNeedLogin/_noNeedRight/_noNeedAuth 免权限 → 3 个接口均 isNeedAuth=true、isNeedLogin=true,仅通配符角色(超级管理员/仓库管理员)或后续 wms_permission 同步授权角色可用;本次仅文档、未扩任何角色授权,不执行权限同步 apply", "methods/system.json 通用报表模块(module=report)新增 3 个 method 条目(追加于 report.meta 之后),版本 0.3.42 -> 0.3.43", "配套文档:docs/report-config-guide.md 新增第 8 节「报表模板管理接口」;AI_METHOD_ROUTING.md 5.1 report 能力速查表登记 3 个新 method", "仅文档变更,未改任何业务代码,未执行数据库/Redis 操作" ], "module": "report" }, { "version": "2026.08.29-inbox-group-quick-list-members", "date": "2026-08-29", "type": "enhanced", "summary": "新增站内信群选择下拉接口:inbox.group.quickList(群快速查询,keyword 模糊匹配群名称/外部群ID、groupType 筛选 store/warehouse/express、limit 默认20上限100,warehouseId 服务端注入,无分页,按创建时间倒序)与 inbox.group.members(群成员筛选,groupId 必填,按外部群ID在消息表聚合去重成员取每 user_id 最新 user_name,keyword 过滤后截断,外部群ID为空返回空列表);新增 API 权限 566(quickList)/567(members),授权角色 8/26/28/29,两接口均需登录且需鉴权。", "methods": [ "inbox.group.quickList", "inbox.group.members" ], "notes": [ "app/service/systems/inbox/group.js quickList:where 含 warehouse_id(服务端注入),keyword 对 group_name/group_id 双字段 LIKE 模糊匹配,limit 截断为 1-100(默认20),findAll 仅取 id/group_id/group_name/group_type/sub_type/is_blocked,按 created_at DESC,软删除由 paranoid 自动排除", "app/service/systems/inbox/group.js members:先按 id+warehouse_id 查 wms_inbox_group(不存在抛「群不存在或无权限操作」,id 无效抛「群ID无效」);externalGroupId 为空直接返回 {list:[]};再按外部群ID+仓库查 wms_inbox_message(最近 500 条按 id DESC,user_id 非空),Map 按 user_id 去重取首次(最新)user_name,keyword 在聚合结果上过滤 user_name/user_id,最后 slice(0, limit)", "app/service/systemMethods/inbox.js group.quickList/group.members 子入口:warehouseId 从 ctx.user.store_id 自动注入,不信任前端传值;inbox systemMethods 未声明 systemInit 免权限,两接口走标准 API 权限校验(isNeedAuth=true、isNeedLogin=true)", "权限迁移 database/migrations/20260829180000-add-inbox-group-select-permissions.js:固定权限 ID 566(inbox.group.quickList,API:群快速查询)/567(inbox.group.members,API:群成员列表),type=api,授权角色 26(仓库组-主管)/28(客服组-主管)/29(生产组-主管)/8(经理);超级管理员(7)/仓库管理员(2) 持 * 通配符自动拥有;INSERT IGNORE 幂等,角色权限数组追加后去重排序", "methods/system.json 站内信分组(module=inbox)新增 2 个 method 条目(追加于 inbox.group.messages 之后),版本 0.3.41 -> 0.3.42", "AI_METHOD_ROUTING.md 新增 5.2 inbox.group(站内信群管理)能力速查小节,登记两接口的实现文件/函数/登录/鉴权信息", "仅文档变更,未改任何代码,未执行数据库/Redis 操作" ], "module": "inbox" }, { "version": "2026.08.29-report-delivery-channel-converge", "date": "2026-08-29", "type": "changed", "summary": "报表投递渠道收敛:report.deliveryPlan.save 的 channel 收敛为仅支持 inbox(默认 inbox,移除 wecom/link,非法渠道报「投递渠道仅支持 inbox: 」);历史 wecom/link 计划投递时按 inbox 兜底执行(warn 日志不抛错);inbox 推送失败立即经 inbox.message.retry 重推一次(ext_id 幂等复用消息记录),重推仍失败进入 failed 退避重试(MAX_RETRY=3,退避 retry_count × 60s)。", "methods": [ "report.deliveryPlan.save" ], "notes": [ "app/service/systems/reportDelivery.js:DELIVERY_CHANNELS 收敛为 ['inbox'],DEFAULT_CHANNEL='inbox';savePlan 对 channel 规范化(trim+lowercase,缺省默认 inbox)后不在白名单则抛「投递渠道仅支持 inbox: 」(原「投递渠道不合法(wecom/inbox/link)」文案已移除)", "deliverByChannel:rawChannel !== 'inbox' 时记录 warn 日志「计划投递渠道 已弃用,按 inbox 兜底投递」后按 inbox 执行,不直接抛错(避免历史计划在 failed 退避循环中耗尽重试次数后永久卡死)", "inbox 推送失败判定双保险:pushResult.success=false 或消息记录回写 push_status=3;失败时复用 ctx.service.inbox.message.retry 重推一次(重置 push_status=0 异步重推,ext_id 幂等复用同一条消息记录不重复写);retry 自身抛错则抛「站内信推送失败且重推失败: <原因>」,交由上层 failed 退避循环(MAX_RETRY=3,退避 = retry_count × 60s)", "methods/system.json 通用报表模块:report.deliveryPlan.save 的 channel 参数枚举收敛为仅 inbox(默认 inbox)、响应 channel 字段说明同步收敛、errors 中渠道错误文案更新为「投递渠道仅支持 inbox: 」;版本 0.3.40 -> 0.3.41", "配套文档:docs/report-config-guide.md 投递章节更新渠道说明(移除 wecom/link、历史渠道按 inbox 兜底、inbox 推送失败自动重推);AI_METHOD_ROUTING.md 同步补充渠道收敛说明与变更版本号", "授权说明:本次仅文档、未扩任何角色授权。report.deliveryPlan.save/list、report.deliveryLog.list 仍为需授权接口(isNeedAuth=true),不涉及权限同步操作" ], "module": "report" }, { "version": "2026.08.29-report-delivery-notify-template-targets", "date": "2026-08-29", "type": "enhanced", "summary": "报表投递新增文本通知与定向群/成员:report.deliveryPlan.save 新增可选参数 notify_template(≤500 字符,标签白名单 {time}/{url}/{report_name}/{biz_date},未知标签报错列出非法标签)、notify_group_ids(wms_inbox_group.id 正整数去重 ≤20,保存时校验存在性且排除软删,缺失报错列出缺失 ID)、notify_member_ids(外部 IM 用户 ID 非空字符串去重 ≤100);report.deliveryPlan.list 响应带出上述 3 个配置字段;report.deliveryLog.list 响应新增 notify_targets 投递目标快照({group_ids, member_ids, notify_text})。", "methods": [ "report.deliveryPlan.save", "report.deliveryPlan.list", "report.deliveryLog.list" ], "notes": [ "app/service/systems/reportDelivery.js savePlan:notify_template/notify_group_ids/notify_member_ids 三个可选参数仅在入参存在(!== undefined)时生效,未传不进入 payload(更新时保持既有字段不动,不传参数行为与旧版完全一致)", "savePlan 校验:notify_template trim 后 ≤500 字符;notify_group_ids 正整数、去重升序、≤20,保存时 validateNotifyGroupExists 校验 wms_inbox_group 存在性(软删自动排除,不校验 is_blocked:被屏蔽群仍可选中,屏蔽属于发送时过滤维度);notify_member_ids 非空字符串、去重、≤100;两者支持数组或 JSON 字符串数组,非数组报「必须为数组」", "标签白名单渲染:app/lib/report/notifyTemplate.js ALLOWED_TAGS={time,url,report_name,biz_date},validateNotifyTemplate 提取 {xxx} 标签并列出非法标签,renderNotifyTemplate 仅替换白名单标签;{url} 为空时替换为兜底文案「文件生成中,稍后可在投递记录中查看」,不阻断投递", "发送链路:reportDelivery.deliverByChannel 投递完成后调用 sendNotifyIfConfigured(与渠道独立,link 渠道同样生效);未配置模板或未选任何群/成员返回 null(不发送);群多选按 wms_inbox_group 逐群推送(群维度协议字段单值),发送时过滤 is_blocked=1/软删/仓库维度不一致;成员 user_id 数组整体透传不循环拆发,选择群时随每个群推送携带,未选择群时单独一次仅成员推送;目标不可达或推送失败抛异常走失败退避重试", "快照:sendNotifyIfConfigured 返回 {group_ids(实际发送的内部群ID), member_ids, notify_text},markDelivered 随 delivered 写入 wms_report_delivery_log.notify_targets;listLogs 以 readJsonObject 读取并输出(未配置时为 null)", "app/service/systems/warehouseNotify.js pushSystemMessage 新增 userIds 参数(仅接受字符串数组,去重过滤空值),推送体 user_id 直接传数组(目标侧协议支持);向后兼容:不传 userIds 且传 group 时校验、幂等 ext_id、落库字段、推送体均与旧版一致;消息表 user_id 列不承载数组(避免超长截断),成员仅随推送体透传并记录在投递日志快照", "method 层 app/service/systemMethods/report/deliveryPlan.js save:仅当 notify_template/notify_group_ids/notify_member_ids 在入参存在时附加到 saveArgs(undefined 不进入参数对象),保持旧调用形状与既有回归断言一致", "授权说明:本次仅文档、未扩任何角色授权。report.deliveryPlan.save/list、report.deliveryLog.list 仍为需授权接口(isNeedAuth=true),不涉及权限同步操作", "methods/system.json 通用报表模块更新 3 个 method 的 params/response/errors(版本 0.3.39 -> 0.3.40);配套文档 docs/report-config-guide.md 投递章节新增「文本通知模板与定向群/成员」小节" ], "module": "report" }, { "version": "2026.08.29-report-meta", "date": "2026-08-29", "type": "enhanced", "summary": "新增 report.meta(免权限只读列元数据接口,供前端报表设计器拉取可用字段):按报表编码返回 wms_report_definition 的 report_code/name/scope/query 与窗口参数 window{dayCount,cutoverHour},以及查询器静态字段清单 fields(查询器模块挂载的 querier.fields,未挂载返回空数组),不执行真实数据查询。", "methods": [ "report.meta" ], "notes": [ "app/service/systemMethods/report.js meta:入参 report_code/reportCode 双写法(驼峰优先),为空返回 fail「报表编码 report_code 不能为空」(flag=failure、code=0、HTTP 200);调用 systems/report.getMeta 后组装 {report_code, name, scope, query, window, fields}(getMeta 的 code 字段回显为 report_code)", "systemInit 声明:_noNeedRight/_noNeedAuth 含 meta(免权限 + 免仓库有效期鉴权,仅登录),_noNeedLogin 不含 meta(必须登录);_noNeedLog 未含 meta → meta 保留审计日志(generate/generateTaskProgress 不写审计日志,两者行为不同,已在接口文档与配置指南中如实标注)", "app/service/systems/report.js getMeta:读 wms_report_definition(is_enabled=1,不存在/停用抛「报表定义不存在或已停用: 」,经 controller 兜底为 HTTP 500 接口错误);window 由 app/lib/report/day_window.resolveWindowConfig 解析(默认 dayCount=7、cutoverHour=7,[D 07:00, D+1 07:00) 半开区间,source_config 可覆盖);fields 由 resolveQuerierFields 读取查询器模块静态字段 querier.fields(未挂载返回空数组)", "静态字段清单挂载方式:查询器模块以 FIELDS 常量挂载到导出函数(queries/sevenDayStockFlow.js 挂载 12 个顶层字段 stock_id/item_code/item_name/barcode/daily/ck_total/rk_total/available/total/pending/suggest/warn;daily 为数组类型含 ck/rk 子字段,suggest/warn 为 computed=true 格式化器预计算字段;queries/generic.js 未挂载,fields 返回空数组)", "授权说明:本次仅文档、未扩任何角色授权。report.meta 免权限(isNeedAuth=false),不涉及权限同步操作", "methods/system.json 通用报表模块分组新增 report.meta 登记(版本 0.3.38 -> 0.3.39);配套文档 docs/report-config-guide.md 新增 report.meta 小节,AI_METHOD_ROUTING.md 刷新 report.meta 条目" ], "module": "report" }, { "version": "2026.08.29-report-config-driven-generate-delivery", "date": "2026-08-29", "type": "enhanced", "summary": "新增配置驱动通用报表与货主定时投递接口:report.generate(提交报表导出异步任务,仅登录免权限)、report.generateTaskProgress(查询导出任务进度,仅登录免权限)、report.deliveryPlan.save/list(货主报表投递计划新增/更新与分页查询,需授权)、report.deliveryLog.list(投递记录审计分页查询,需授权)。", "methods": [ "report.generate", "report.generateTaskProgress", "report.deliveryPlan.save", "report.deliveryPlan.list", "report.deliveryLog.list" ], "notes": [ "app/service/systemMethods/report.js:systemInit 声明 _noNeedRight/_noNeedAuth = generate,generateTaskProgress(免权限+免仓库有效期鉴权,仅登录);generate 的 warehouse_id 由服务端从登录上下文 ctx.user.store_id 自动注入,禁止前端传递;store_id 支持 store_id/storeId 双写法,<=0 视为不按货主过滤", "app/service/systemMethods/report/deliveryPlan.js 与 report/deliveryLog.js:systemInit 未声明免权限(_noNeedRight/_noNeedAuth 均为空),为需授权管理类接口;methods/system.json 中 isNeedAuth=true 已登记", "权限同步:本次仅写文档、未执行任何授权操作。report.deliveryPlan.save/list、report.deliveryLog.list 为需授权接口,后续请先执行 npm run permission:sync:system-api -- --dry-run 预演,再按标准流程授权;不扩大任何角色授权范围", "实现依赖:app/service/systems/report.js(getDefinition/resolveQuerier/buildWorkbookSheets/generate/generateBuffer)、app/service/systems/reportDelivery.js(savePlan/listPlans/listLogs/dispatch 投递编排)、app/lib/report/*(render/day_window/formatters 纯函数模块)、内置查询器注册表 app/service/systems/report/queries/index.js(sevenDayStockFlow/generic)", "报表配置驱动:wms_report_definition(app/model/report_definition.js)以 code/name/scope + output_config/source_config/sheet_config 三段 JSON 配置驱动,新报表优先加配置行、免发版;sheet_config 支持静态列/窗口展开列/计算列、headerRow1 的 {date} 模板、merges 绝对引用、style、rowFilter", "methods/system.json 新增「通用报表模块」分组(module=report,groupName=通用报表模块),登记 5 个 method 的参数(source=body)、响应与错误码;版本 0.3.37 -> 0.3.38", "配套文档:docs/report-config-guide.md 新增报表配置结构说明(三段 JSON 配置、列定义、{date} 模板、merges、style、rowFilter、查询器注册表与内置查询器口径假设);AI_METHOD_ROUTING.md 同步刷新 report 相关路由说明与服务清单" ], "module": "report" }, { "version": "2026.08.28-workbench-queryOrder-intercept-pack-flag", "date": "2026-08-28", "type": "enhanced", "summary": "workbench.business(queryOrder/query) 查询订单响应增强:order 对象新增 intercept_status 字段(拦截状态原始值,散单/团购均返回,与既有 pack_status 并列);散单(isSandan=1)时 order 额外返回 intercept_flag/pack_flag 两个 0/1 标志(拦截状态不等于 none 时 intercept_flag=1 否则 0,打包状态不等于 none 时 pack_flag=1 否则 0),团购不返回这两个标志;空值/null 统一归一化为 none。", "methods": [ "workbench.business" ], "notes": [ "app/service/systems/workbench.js _queryOrder 步骤6:intercept_status/pack_status 空值/null 归一化为 none(String(v||'').trim() || 'none'),interceptFlag = 状态 !== none ? 1 : 0,packFlag 同理", "_queryOrder 响应 order 对象新增 intercept_status(原始值,散单/团购均返回),与既有 pack_status 并列,原始状态字段原样保留、不破坏既有调用方", "仅散单(isSandan===1)向 result.order 追加 intercept_flag/pack_flag;团购(isSandan===0)不追加这两个标志字段,pack_status/intercept_status 原始值仍原样返回", "methods/system.json workbench.business 同步补充 queryOrder/query 响应结构:order.intercept_status 字段说明、散单场景 order.intercept_flag/order.pack_flag 字段说明与取值语义(状态不等于 none 返回 1,否则返回 0)" ], "module": "workbench" }, { "version": "2026.08.28-storage-entry-quickInbound-is-virtual-inbound", "date": "2026-08-28", "type": "enhanced", "summary": "storage.entry.quickInbound 事务内回写 is_virtual_inbound(是否虚拟入库):有绑定收货单 → 0(非虚拟入库),无绑定收货单 → 1(虚拟入库),与 order_status=COMPLETED 同一事务写入;wms_entry_order 新增 is_virtual_inbound 字段(TINYINT(1) NOT NULL DEFAULT 0)", "methods": [ "storage.entry.quickInbound" ], "notes": [ "app/service/systems/storage/entry.js quickInbound:eo.update 事务内新增 is_virtual_inbound 回写,值为 receivingIds.length > 0 ? 0 : 1(有绑定收货单 → 非虚拟入库,无绑定收货单 → 虚拟入库),与 order_status=COMPLETED、sync_status=SUCCESS 同一事务提交", "app/model/entry_order.js:wms_entry_order 新增 is_virtual_inbound 字段(TINYINT(1),allowNull:false,defaultValue:0,comment:是否虚拟入库:0=否 1=是)", "database/migrations/20260828100000-add-is-virtual-inbound-to-wms-entry-order.js:新增迁移(describeTable 已存在时跳过 addColumn),down 删除字段;迁移文件仅创建,本次文档任务未执行", "methods/system.json storage.entry.quickInbound 说明文字补充 is_virtual_inbound 判定规则;入参/出参不变(quickInbound 响应未返回该字段,list/get 查询白名单亦未包含该字段)" ], "module": "storage.entry" }, { "version": "2026.08.27-order-allocateStorage-allow-storage-location", "date": "2026-08-27", "type": "fixed", "summary": "order.pendingOrder.allocateStorage 修复 allow_storage_location=true 未生效:分配储位时仍强制校验库位类型 allow_allocation=1/is_active=1,存储储位被过滤。现在 allow_storage_location=true 时直接分配储位,无视库位类型的可分配/启用限制", "methods": [ "order.pendingOrder.allocateStorage" ], "notes": [ "app/service/systems/order_storage_allocation.js allocatePicking:storageRows 查询的 locationType include where(allow_allocation:1/is_active:1)改为仅当 allowStorageLocation=false 时生效;true 时不再过滤库位类型限制", "无候选库位时的缺货诊断 diagnoseStorageTypeRestriction 仅在 allowStorageLocation=false 时执行,避免「库位类型不可分配/未启用」被误报为缺货原因", "可分配库存查询完成日志补充 allowStorageLocation 字段", "同步更新 methods/system.json:order.pendingOrder.allocateStorage 描述与 allow_storage_location 参数说明" ], "module": "order" }, { "version": "2026.08.27-order-export-stock-query", "date": "2026-08-27", "type": "fixed", "summary": "order.export 修复携带产品查询(where.stock_query)时导出失败(Unknown column ... in where clause):导出链路补齐 stock_query 虚拟筛选提取,按商品编码/名称/ID/条码解析为订单ID集合后注入主查询,与 order.list 语义一致", "methods": [ "order.export" ], "notes": [ "app/service/systems/order_export.js exportOrders:在 extractBuyerMessageHasVirtualFilter 之后新增 extractStockQueryVirtualFilter,从 where 提取并移除 stock_query,避免其残留在 where 中经 buildWhere/parseWhereConditions 被当作数据库字段解析,导致 SQL Unknown column 报错", "stockQuery 非空时调用 findOrderIdsByStockQuery(商品编码/名称/ID/条码模糊匹配 → stock_id 集合 → order_items 关联订单ID),再经 appendOrderIdsFilterToWhere 注入主查询;无匹配商品时导出结果为空,与 order.list 行为一致", "stockQuery 模块名取 target.defaultWhereModuleName || target.sortModuleName || 'order',保证仅传 table_type 时按表类型推导对应模块(current/history 等)的 order_items 表类型" ], "module": "order" }, { "version": "2026.08.27-storage-entry-get-total-order-lines", "date": "2026-08-27", "type": "enhanced", "summary": "storage.entry.get 响应新增 total_order_lines(entryOrder 内)、total_quantity(应入库总数量)、received_quantity(已入库总数量)字段", "methods": [ "storage.entry.get", "storage.entry.getStore" ], "notes": [ "app/service/systems/storage/entry.js get:返回 data.entryOrder 新增 total_order_lines(直接取 wms_entry_order.total_order_lines)", "data 顶层新增 total_quantity = 明细 planned 之和(应入库总数量)、received_quantity = 明细 completed 之和(已入库总数量)", "getStore 共用同一底层实现,自动获得这些字段", "同步更新 get 方法 JSDoc 注释" ], "module": "storage.entry" }, { "version": "2026.08.27-directInbound-receiving-stock-occupancy", "date": "2026-08-27", "type": "enhanced", "summary": "storage.entry.commit 导入/PDA 入库支持绑定收货单占用:带 receiving_detail_id 的导入记录优先按明细扣减,未带 receiving_detail_id 的剩余导入量按 stock_id 匹配收货单明细占用并回写收货单入库状态", "methods": [ "storage.entry.commit", "storage.directInbound.commit" ], "notes": [ "app/service/systems/inbound_direct_log.js commit onSuccess 事务内新增 _applyReceivingStockOccupancy:绑定收货单(wms_entry_order_receiving)存在时,汇总未携带 receiving_detail_id 的导入记录数量,按 stock_id(=收货明细 system_product_id)匹配占用", "优先级:携带 receiving_detail_id 的记录先由 _syncReceivingStorageStatus 按明细扣减,随后剩余量复用 storage.entry._applyReceivingInboundUsage 按 stock_id 依次占用收货明细剩余可入数量(actual_quantity - stored_quantity),事务内行锁防并发超分", "占用后回写收货明细 stored_quantity/storage_status(all/partial),并汇总更新收货单主表 storage_status", "未绑定收货单或无剩余导入量时跳过,不影响原有非绑定模式入库行为", "storage.entry._applyReceivingInboundUsage 日志前缀由 [storage.entry.quickInbound] 改为 [storage.entry](方法现被 quickInbound 与 commit 两个流程复用)" ], "module": "storage.entry" }, { "version": "2026.08.27-storage-management-replenishmentDemand-owner-filter", "date": "2026-08-27", "type": "enhanced", "summary": "storage.management.replenishmentDemand 新增货主筛选:store_id(单值或数组)或 where.store_id 传入,仅返回指定货主的 SKU,summary 同步只统计筛选后数据", "methods": [ "storage.management.replenishmentDemand" ], "notes": [ "app/service/systemMethods/storage/management.js replenishmentDemand:解析 store_id / store_ids / where.store_id(单值/数组),归一化为正整数数组去重,非法值(非正整数)抛错;空值不筛选。", "app/service/systems/storage/management.js replenishmentDemand:options.storeIds 构建 Set,组装输出循环内非命中货主 SKU 直接跳过,list 与 summary 统计口径一致(仅含筛选货主)。", "同步更新 methods/system.json 参数文档(新增 store_id 参数说明)。" ], "module": "storage.management" }, { "version": "2026.08.27-quickInbound-receiving-intersection", "date": "2026-08-27", "type": "enhanced", "summary": "storage.entry.quickInbound 支持绑定收货单交集直入:有绑定时按 stock_id 只取收货单中剩余可入数量(actual_quantity - stored_quantity)与入库明细的较小值直入,并回写收货单明细已入库数量与收货单入库状态", "methods": [ "storage.entry.quickInbound" ], "notes": [ "app/service/systems/storage/entry.js quickInbound:新增绑定收货单查询(wms_entry_order_receiving),按 stock_id(=收货明细 system_product_id)聚合剩余可入数量 actual_quantity - stored_quantity", "入库明细实际直入量 = min(计划数量, 剩余可入数量);无交集商品跳过(明细 received_quantity 写 0),全部无交集或剩余为 0 时返回 400「收货单中无交集商品或剩余可入数量不足,无法快捷直入」", "未绑定收货单保持原行为:按明细计划数量全量直入", "存在截断/跳过明细时 isFin=false(confirmType=1, PARTFULFILLED)回传奇门/API", "新增 _applyReceivingInboundUsage 事务内回写:行锁重读收货明细,按明细 id 升序分配本次入库量(每个明细最多分配其剩余可入数量),更新 stored_quantity(使用了多少写多少)与 storage_status(all/partial),并汇总更新收货单主表 storage_status", "收货单主表 storage_status 按实际数量判定:全部明细 stored_quantity >= actual_quantity 才置 all;有部分入库置 partial;全部未入库置 none——收货单未全部使用所有商品时不会转为全部入库", "入库单明细 received_quantity 改为写实际入库量(原来写计划数量)", "响应新增 plan_quantity(计划入库总数量),total_quantity 语义改为实际入库总数量,items_count 语义改为实际入库明细条目数" ], "module": "storage.entry" }, { "version": "2026.08.27-storage-management-replenishmentDemand-owner-barcode", "date": "2026-08-27", "type": "enhanced", "summary": "storage.management.replenishmentDemand 响应 list 每项新增 store_id(货主ID)、store_name(货主名称)、barcodes(SKU 条码列表)字段", "methods": [ "storage.management.replenishmentDemand" ], "notes": [ "app/service/systems/storage/management.js replenishmentDemand:StockWarehouse 三处查询(严格/宽松/终极兜底)attributes 均新增 store_id,stockInfoMap 记录货主ID。", "新增货主名称查询:StoreWarehouse(store_remask 签约表备注名)优先、Store(company_name 商家公司名)兜底;新增 StockBarcode 按 stock_id 批量查询条码并分组为 barcodes: [{id, barcode}]。", "货主与条码查询与库存查询为顺序执行(货主/条码三表在 Promise.all 内并行)。", "响应字段:store_id (number) 货主ID;store_name (string) 货主名称;barcodes (array) 条码列表,children: id (number)/barcode (string)。", "同步更新 methods/system.json 响应文档。" ], "module": "storage.management" }, { "version": "2026.08.27-order-export-columns", "date": "2026-08-27", "type": "enhanced", "summary": "order.export 新增 export_columns/exportColumns 导出表头字段白名单参数(中文表头数组):不传或空数组输出全部列;传入时仅输出指定列;校验枚举覆盖 waybill/item 两种模式全部 51 个中文表头,非法表头抛错并列出非法值。", "methods": [ "order.export" ], "notes": [ "app/service/systems/order_export.js:新增 ORDER_EXPORT_ALL_COLUMN_HEADERS(waybill/item 两种模式表头并集,共 51 个);getOrderExportColumns(mode, selectedHeaders) 支持按中文表头过滤;新增 normalizeExportColumns(数组去重/trim/非法值抛错);exportOrders 读取 export_columns/exportColumns(下划线优先)并作用到初始 sheet 与自动续写的后续 sheet(resolvedColumns 复用)", "app/service/systemMethods/order/index.js export:解构 export_columns/exportColumns 并透传数组,未传时传空数组(输出全部列)", "methods/system.json order.export 新增 export_columns/exportColumns 参数文档:枚举全量 51 个中文表头,并标注仅 waybill 模式输出(系统订单号、外部订单号、平台单号、抓取波次号、商品明细)与仅 item 模式输出(订单ID、订单号、外部单号、波次号、仓库商品名称、商品条码、商品图片、数量)的字段" ], "module": "order" }, { "version": "2026.08.26-wave-batchList-store-id-filter", "date": "2026-08-26", "type": "enhanced", "summary": "order.wave.batchList 新增 where.store_id(货主ID)过滤:支持单值/数组/{operator,value} 结构(正整数),返回包含任一筛选货主订单的波次(含混合货主波次);未在 wms_wave_batch 加冗余 store_id 字段,通过订单分表 INNER JOIN 聚合匹配,零迁移零回填零口径漂移风险。", "methods": [ "order.wave.batchList" ], "notes": [ "app/service/systemMethods/order/wave.js buildBatchListWhereClause:allowedFields 新增 store_id,normalizeStoreIdList 归一化(单值/数组/{operator,value}→正整数数组去重,非法值抛错),返回值新增 storeIds", "batchList:storeIds 非空时在 wave_order_stats 之后追加 INNER JOIN wave_owner_filter(订单表 od.wave_id 匹配且 od.store_id IN (:whereStoreIds) 按 wave_id 分组),listSql/countSql replacements 新增 whereStoreIds", "设计决策:不在 wms_wave_batch 增加 store_id 冗余字段(混合填0),理由——batchList 原本就必须 LEFT JOIN 订单表做状态聚合,货主过滤挂同一次 JOIN 零额外成本;订单表已有 store_id 单列索引;冗余需覆盖抓取入波/策略任务建波/batchRemoveOrders/batchRemoveExceptionOrders 等 10+ 处写入点维护,遗漏即口径漂移;owner_name 展示已实时聚合订单 store_id,避免双口径", "实测:{operator:'',value:[1000281,1000000]} 过滤 wave_type=1&source=0 返回 196 条(库中该货主订单波次);单值/数组形式均返回 5 条;不存在货主 0 条;非法值报错;无过滤 baseline 278 条不受影响;原请求含 wave_status=0 返回 0 因库中活动波次均为 status=1", "同步更新 methods/system.json 的 batchList where 白名单说明" ], "module": "order.wave" }, { "version": "2026.08.26-wave-batchList-store-name", "date": "2026-08-26", "type": "enhanced", "summary": "order.wave.batchList 响应每条记录新增 store_name(货主信息):按波次内订单 store_id(货主ID)聚合,所有订单均为同一货主时返回货主名称,否则(多个货主、存在无货主订单或空波次)返回“混合”;货主名称优先取合约表 wms_store_warehouse.store_remask(货主备注名称),无合约或备注为空时回退 wms_store.company_name(公司全称)。", "methods": [ "order.wave.batchList" ], "notes": [ "app/service/systemMethods/order/wave.js batchList:wave_order_stats 子查询新增 owner_distinct_count(COUNT(DISTINCT NULLIF(store_id,0)))、owner_named_count(SUM 非空判定)、owner_store_id(MAX(NULLIF(store_id,0)))三个聚合字段,listSql SELECT 透出", "新增 resolveWaveBatchOwnerStoreNameMap:仅对满足单货主的波次批量查 StoreWarehouse(store_id+warehouse_id)取 store_remask,再查 wms_store.company_name 兑底,remask 覆盖 company_name;查询失败仅告警不影响列表", "判定口径:orderCount>0 且 ownerDistinctCount===1 且 ownerNamedCount===orderCount 且 ownerStoreId>0 才返回货主名称,否则返回“混合”(0 单波次同样返回“混合”)", "货主名称口径与 afterSale._enrichListStoreNames、inventory.store_name 一致(store_remask 优先、company_name 兑底);早期草稿曾按 shop_nick 店铺名称实现,已按项目货主口径修正", "同步更新 methods/system.json 的 batchList 描述与 response.list 字段说明" ], "module": "order.wave" }, { "version": "2026.08.26-workbench-queryOrder-pack-status", "date": "2026-08-26", "type": "enhanced", "summary": "工作台 workbench.business(queryOrder) 查询订单增强:接入订单序列表(wms_order_id_location_*)优先定位分表,未命中按 current→dispatch 回退遍历;响应 order 对象新增 pack_status 字段(散单/团购均返回)。", "methods": [ "workbench.business" ], "notes": [ "app/service/systems/workbench.js _queryOrder 步骤2:先经 orderDeliveryFactory.getOrderLocation(orderId, warehouseId) 获取序列表位置,命中则优先查对应分表,失败/未命中保持原 current→dispatch 遍历,与 _sendWeight/waybill/order_express 等模块的序列表优先定位语义一致", "_queryOrder 响应 order 对象新增 pack_status(none/padding/fin/error),与 pick_status/recheck_status 等状态机并列,工作台可根据打包状态判断该单是否已打包", "备注:_packOrder 订单查找仍按 delivery_order_code 双表遍历(序列表按 id 定位,发货单号场景暂不适用)" ], "module": "workbench" }, { "version": "2026.08.26-finishPack-sync-order-pack-status", "date": "2026-08-26", "type": "fixed", "summary": "修复打包任务结束事件不更新订单打包状态的问题:workbench.finishPack 结束任务后同步更新关联订单 pack_status 为 fin(散单按订单更新,团购按波次批量更新未拦截订单)并写完成操作日志;order.packing.setEndTime 手动结束同样同步订单;打包操作日志文案按任务状态区分(开始打包/打包完成),不再在开始打包时误写“打包完成”。", "methods": [], "notes": [ "问题定位:波次 B2026082503311(团购 7 单)开始打包时 packOrder(status=1) 写入的日志前缀硬编码为“团购打包完成”,实际尾部为“任务状态: 打包中”;设备结束事件走 finishPack 仅更新 wms_pack_task(end_time/status=2),未更新订单,导致订单 pack_status 停留在 padding", "app/service/systems/workbench.js 新增 _updateOrderPackStatus:遍历 current+dispatch 分表,散单按 order_id 更新单笔,团购按 wave_id 批量更新(intercept_status 空值按 none 处理,拦截订单跳过),异常仅记日志不影响主流程;_packOrder 步骤6.5 改为复用该方法", "app/service/systems/workbench.js _finishPack:任务结束后按 pack_mode 判定散单/团购,调用 _updateOrderPackStatus(packStatus=2) 同步订单,并按任务记录(含 operator_text 回填操作人)写入完成操作日志", "app/service/systems/order_packing.js setEndTime:任务由未完成转为已完成时同样调用 _updateOrderPackStatus 同步订单,与 finishPack 语义对齐", "app/service/systems/workbench.js _writePackOperationLog:日志前缀按 status 区分——status>=2 写“打包完成”,否则写“开始打包”,保留原有字段变更描述", "定时任务 auto_finish_pack_task 超时自动结束仅关闭任务记录、不更新订单(保持原语义,避免超时误标订单完成),如需要可在后续版本评估同步" ], "module": "workbench" }, { "version": "2026.08.26-stockout-listLogs", "date": "2026-08-26", "type": "added", "summary": "新增 storage.stockout.listLogs 出库单操作日志查询接口:按出库单ID或出库单号分页查询 wms_operation_log(business_type=stockout,business_id=出库单ID),覆盖转订单/确认/修改/取消等 STOCKOUT_* 操作,按创建时间倒序;配套 operationLog.queryStockoutLogs 服务方法与权限 565。", "methods": [ "storage.stockout.listLogs" ], "notes": [ "app/service/systemMethods/storage/stockout.js 新增 listLogs:支持 id 或 stockout_order_code 定位(出库单号先查表换ID),pagination.page/pageSize(兼容 page_size);出库单不存在返回空列表不报错;仓库上下文取 ctx.user.store_id", "app/service/systems/operation_log.js 新增 queryStockoutLogs:复用 queryLogsByBusinessType(query, 'stockout')", "database/migrations/20260826100000-add-stockout-listLogs-permission.js:权限 565,授权角色 8/26/28/29/30,开发库已执行", "storage.stockout.listItems 出库单明细接口此前已存在(按 stockout_order_code/id 查 wms_order_stockout_items),本次仅补 listLogs 文档", "实测:listLogs 按 stockout_order_code 与 id=22 均返回分页日志(STOCKOUT_TO_ORDER/STOCKOUT_UPDATE_INFO,含操作人/时间/消息/平台名),pagination.total=4 正确;注意权限迁移后短时间内用户权限上下文缓存可能未刷新导致 403,刷新后正常" ], "module": "storage.stockout" }, { "version": "2026.08.26-stockout-order-sync-channel", "date": "2026-08-26", "type": "added", "summary": "订单回传区分 STOCKOUT 创建渠道:待处理订单同步入口(syncOrderIds)按 create_channel 路由新增 syncStockoutOrders,回传时把订单实际快递编码/运单号写回出库单(express_code/express_name/waybill_code/waybill_codes),并按出库单来源通知外部(QM→奇门 taobao.qimen.stockout.confirm,API→OpenAPI 回调 event=stockout_completed,WMS 内部来源直接成功);通知成功后才扣减订单库存并完成同步(sync_status=fin、出库单 COMPLETED/SUCCESS),失败则订单 sync_status=error 标记待处理异常、出库单 sync_status=FAILED 记录失败原因。", "methods": [ "order.pendingOrder.syncOrderIds" ], "notes": [ "app/service/systems/order_async.js 新增 syncStockoutOrders/syncStockoutOrdersInternal/processStockoutOrderInternal/notifyStockoutExternalInternal/buildStockoutConfirmDataInternal/finalizeSuccessfulStockoutSyncInternal:反查出库单(订单 source_order_codes 首项或明细 source_order_code),运单号仅认 wms_order_express 表(不回退订单主表 express_code 面单前置);收尾事务内写回出库单 + 订单明细 outbound 扣库存 + sync_status=fin,SELECT FOR UPDATE 防重幂等", "app/service/systems/order_storage_allocation.js syncOrderIds 渠道路由新增 STOCKOUT 分支(原落入 MANUAL 兜底,不通知外部)", "出库单已 SUCCESS 的重试场景跳过重复通知,直接收尾;订单未分配运单号时回传失败并提示", "所有回传入口(pendingOrder.syncOrderIds 异步包装、express_platform 自动同步回传)均汇聚到同一路由,改动一处覆盖全部", "订单表无 sync_message 列:回传失败提示落在 order_flag 字段(markPendingExceptionInternal 同步置 inspection_status=error/step=3)", "实测失败路径:测试订单 122172(TEST-SO-20260826004828-003 转单)回传奇门 stockout.confirm 返回 JST_Error,订单 sync_status=error + order_flag 提示,出库单保持 TRANSFERRED + sync_status=FAILED + sync_message 记录原因", "实测成功路径:出库单 source_type 临时改 WMS(内部来源直接成功)触发回传,订单 sync_status=fin/order_flag 清空/step=2,出库单 COMPLETED/SUCCESS + 写回 express_code=SF/waybill_code/waybill_codes,库存 101389 quantity 100→95、locked 8→3,流水闭环 LOCK(QM_STOCKOUT)→UNLOCK(转单释放)→LOCK(DELIVERY_ORDER)→OUTBOUND(订单出库)" ], "module": "order.pendingOrder" }, { "version": "2026.08.26-stockout-cancel", "date": "2026-08-26", "type": "added", "summary": "新增 storage.stockout.cancel 出库单取消:仅 CREATED/PENDING 允许取消;事务内释放创建时占用的库存锁定(QM_STOCKOUT,写 UNLOCK 流水)并置 CANCELLED,写 wms_operation_log 操作日志(STOCKOUT_CANCEL);TRANSFERRED/COMPLETED 禁止取消。新增权限 564 并授权。", "methods": [ "storage.stockout.cancel" ], "notes": [ "app/service/systemMethods/storage/stockout.js 新增 cancel:复用 lockItemStorages 负数量释放(锁定不足幂等跳过),与状态更新、操作日志同事务;仓库隔离与 confirm/updateInfo 一致", "database/migrations/20260826093000-add-stockout-cancel-permission.js:权限 564,授权角色 8/26/28/29/30,开发库已执行", "实测:取消测试单后 locked_quantity 101379 3→2,UNLOCK 流水(出库单取消释放锁定)与 STOCKOUT_CANCEL 操作日志均落库", "同步更新 methods/system.json 新增 cancel 接口文档" ], "module": "storage.stockout" }, { "version": "2026.08.26-stockout-operation-log", "date": "2026-08-26", "type": "added", "summary": "storage.stockout 链路补写 wms_operation_log 操作日志(businessType=stockout):confirm 直出成功、toOrder 转单成功、updateInfo 修改均写操作记录;新增 updateInfo API 权限 563 并授权;修复 updateInfo 证件号参数名与出库单 ID 冲突。", "methods": [ "storage.stockout.confirm", "storage.stockout.toOrder", "storage.stockout.updateInfo" ], "notes": [ "app/service/systemMethods/storage/stockout.js 新增 _writeStockoutOperationLog(operationLog.createOperationLogs,失败仅告警不影响主流程):confirm 成功路径与状态更新同事务写 STOCKOUT_CONFIRM(含释放锁总量);toOrder 转单后写 STOCKOUT_TO_ORDER(含新订单号);updateInfo 写 STOCKOUT_UPDATE_INFO(含改动字段摘要)", "修复:updateInfo 收件人证件号参数由 id 改为 receiver_id(原与出库单ID参数冲突,会把 data.id 误写入 receiver_id 字段)", "database/migrations/20260826090000-add-stockout-updateInfo-permission.js:新增权限 563(storage.stockout.updateInfo),授权角色 8/26/28/29/30,开发库已执行", "实测:updateInfo 修改后 wms_operation_log 落库(business_type=stockout、operation_code=STOCKOUT_UPDATE_INFO、operator 阿猫、message 含改动摘要)" ], "module": "storage.stockout" }, { "version": "2026.08.26-stockout-confirm-release-lock", "date": "2026-08-26", "type": "fixed", "summary": "storage.stockout.confirm 直出确认后释放出库单创建时占用的库存锁定:出站通知成功后,事务内逐明细 lockItemStorages(-plan_qty, orderType=QM_STOCKOUT) 释放锁定并自动写 UNLOCK 流水,与状态推进到 COMPLETED 同事务提交,失败回滚可重试;释放遇\"锁定不足\"视为幂等成功跳过。", "methods": [ "storage.stockout.confirm" ], "notes": [ "修复前:confirm 直出成功后 locked_quantity 一直占用(出库单无取消入口,锁只能靠转订单释放)", "出站通知失败时锁保持、状态不变(sync_status=FAILED),重试 confirm 成功后才会释放;已释放场景(锁定不足)跳过不阻断", "实测:本地 confirm 真实出站淘宝奇门返回 JST_Error 单号转换失败,锁保持(101379.locked=3/101389.locked=8 不变),符合设计;释放+UNLOCK 流水由 lockItemStorages 负数量链路保证" ], "module": "storage.stockout" }, { "version": "2026.08.26-directPutaway-default-location", "date": "2026-08-26", "type": "updated", "summary": "storage.inventory.directPutaway 默认库位改为读取仓库设置:直入库存写 wms_storage 时,收货明细 space_id 无效则使用 wms_store.subject_config.default_location_id(经 deliveryOrder.getStoreSubjectConfig 缓存优先读取),未设置时兜底库位 1。", "methods": [ "storage.inventory.directPutaway" ], "notes": [ "app/service/systems/storage/inventory.js directPutaway:步骤 10 写 wms_storage 的 spaceId 由硬编码 1 改为 defaultSpaceId(收货明细有库位仍按其库位),defaultSpaceId 在方法前段读取仓库设置(正整数有效才采用,否则 1),读取失败仅告警不影响入库", "与 storage.receiving.addDetail 默认库位口径一致(仓库设置优先,兜底 1)", "同步更新 methods/system.json directPutaway 的库位规则说明" ], "module": "storage.inventory" }, { "version": "2026.08.26-receiving-addDetail-default-location", "date": "2026-08-26", "type": "updated", "summary": "storage.receiving.addDetail 默认库位改为读取仓库设置:新增明细时 space_id 默认取 wms_store.subject_config.default_location_id(经 deliveryOrder.getStoreSubjectConfig 缓存优先读取),未设置时兜底库位 1;前端传入 item.space_id 时仍按传入值。", "methods": [ "storage.receiving.addDetail" ], "notes": [ "app/service/systems/storage/receiving.js addDetail:默认明细 space_id 由硬编码 1 改为优先读仓库设置 default_location_id(正整数有效才采用),否则兜底 1;读取失败仅告警不影响创建", "依赖 deliveryOrder.getStoreSubjectConfig(缓存 10 分钟),saveSettings 保存仓库设置时会同步清理该缓存键", "同步更新 methods/system.json addDetail 的 item.space_id 描述" ], "module": "storage.receiving" }, { "version": "2026.08.26-warehouse-setting-default-location", "date": "2026-08-26", "type": "added", "summary": "仓库设置(wms_store.subject_config)新增\"默认库位\"字段 default_location_id(type location):setting.warehouse.getFieldMeta 字段元信息新增该字段(不返回库位选项列表,库位数量大,前端按仓库搜索选择),saveSettings 传入时校验库位属于当前仓库,否则报 400 拒绝写入。", "methods": [ "setting.warehouse.getFieldMeta", "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "app/service/systems/setting/warehouse.js WAREHOUSE_SETTING_FIELDS 新增 default_location_id(名称:默认库位,type location,default null,描述:仓库未指定库位入库/上架时使用的默认库位);getFieldMeta 不注入库位选项列表(库位数量大,前端按 type=location 自行按仓库搜索库位)", "saveSettings 新增 validateDefaultLocation:传入 default_location_id 时校验其属于当前仓库,否则 400 '默认库位 {id} 不属于当前仓库';传 null/空清空", "app/model/store.js DEFAULT_SUBJECT_CONFIG 新增 default_location_id: null;normalizeSubjectConfig 新增正整数校验分支(空值置 null)", "同步更新 methods/system.json:getSettings 响应、saveSettings 参数补充 default_location_id 说明" ], "module": "setting.warehouse" }, { "version": "2026.08.25-stockout-updateInfo-transferred", "date": "2026-08-25", "type": "added", "summary": "新增 storage.stockout.updateInfo 修改出库单信息接口,并引入 TRANSFERRED 状态:转订单成功后出库单置为 TRANSFERRED(已转订单),该状态下禁止一键出库。", "methods": [ "storage.stockout.updateInfo", "storage.stockout.toOrder" ], "notes": [ "storage.stockout.updateInfo:修改范围限收件人(name/tel/mobile/company/email)、地址(province/city/area/town/detailAddress/zipCode/countryCode)、快递编码(express_code,自动解析 express_name)、来源平台(source_platform_code/name),未传入不修改;仅 CREATED/PENDING 状态允许修改(400);修改后收货信息不完整(name、(tel/mobile) 其一、省市区镇详细地址)禁止提交并列出缺失字段", "数据库迁移 20260825180000-add-transferred-status-and-platform-to-wms-order-stockout.js:order_status ENUM 追加 TRANSFERRED + 新增 source_platform_code(50)/source_platform_name(200) 列,开发库已执行并核验", "app/model/order_stockout.js:ENUM 补 TRANSFERRED、新增两平台字段、新增 isTransferred() 辅助方法", "storage.stockout.toOrder:转单成功后 order_status 置 TRANSFERRED(原 CANCELLED);deliveryOrder.sourcePlatformCode 优先用出库单已存平台,为空走兜底平台;confirm(一键出库)经 canConfirm 拒绝 TRANSFERRED 状态", "同步更新 methods/system.json:新增 updateInfo 接口文档,更新 toOrder 描述与状态说明", "实测(2026-08-26,测试单 20):正常修改 name/mobile/detailAddress + express_code=SF(自动解析 express_name=顺丰速运)+ source_platform_code 均落库,未传字段不变;detailAddress 清空被拦截(收货信息缺失,禁止提交:缺少 detailAddress(详细地址));COMPLETED 单被拦截(不允许修改);操作日志 STOCKOUT_UPDATE_INFO 含改动字段摘要(收件人姓名、移动电话、详细地址、快递编码、来源平台);测试数据已恢复原貌、日志保留" ], "module": "storage.stockout" }, { "version": "2026.08.25-stockout-toOrder-receiver-validate", "date": "2026-08-25", "type": "fixed", "summary": "storage.stockout.toOrder 增加收货信息必填校验与同快递建单:name、(tel/mobile) 至少一项、省市区镇详细地址缺失时拒绝转单并提示缺失字段;收货信息优先接口传入,未传回填出库单已存的 receiver_* 字段;新订单快递编码沿用出库单 express_code(相同快递),平台不传 sourcePlatformCode 走兜底平台。", "methods": [ "storage.stockout.toOrder" ], "notes": [ "app/service/systemMethods/storage/stockout.js toOrder:释放锁前先合并收货信息(storedReceiverInfo 从出库单 receiver_company/name/zip_code/tel/mobile/email/country_code/province/city/area/town/detail_address 回填,接口 receiverInfo 非空字段覆盖)并逐项校验,缺项返回 fail 提示缺失字段列表", "建单参数:logisticsCode = 出库单 express_code(create 时已解析的系统快递编码),不传 sourcePlatformCode(resolvePlatformSnapshot 自动使用合约兜底平台)", "同步更新 methods/system.json 中 storage.stockout.toOrder 的 description 与 receiverInfo 参数说明" ], "module": "storage.stockout" }, { "version": "2026.08.25-stockout-receiver-info-db", "date": "2026-08-25", "type": "added", "summary": "wms_order_stockout 表新增 13 个收件人字段(receiver_* 前缀),对应奇门 stockout.create 报文 receiverInfo 节点(company/name/zipCode/tel/mobile/email/countryCode/province/city/area/town/detailAddress/id),为出库单解析收件人信息与转订单回填做准备。", "methods": [ "storage.stockout.toOrder", "stockout.create" ], "notes": [ "database/migrations/20260825170000-add-receiver-info-to-wms-order-stockout.js 新增 13 列:receiver_company(200)/receiver_name(50)/receiver_zip_code(50)/receiver_tel(50)/receiver_mobile(50)/receiver_email(50)/receiver_country_code(50)/receiver_province(50)/receiver_city(50)/receiver_area(50)/receiver_town(50)/receiver_detail_address(200)/receiver_id(50),均允许 NULL;up/down 均带 describeTable 幂等保护", "app/model/order_stockout.js 同步新增 13 个字段定义(remark 与 express_code 之间)", "开发库已执行迁移并核验 SHOW COLUMNS 全部落库;生产库需在发布时按 db-migration-envs 规范执行" ], "module": "storage.stockout" }, { "version": "2026.08.25-storage.stockout.toOrder", "date": "2026-08-25", "type": "added", "summary": "storage.stockout.toOrder 从占位接口落地为真实实现:将非订单出库单(wms_order_stockout)转为正式销售订单,新订单 create_channel 固定为 STOCKOUT;转单时释放出库单库存锁定(QM_STOCKOUT)并转由新订单重新锁定,成功后原出库单置为 CANCELLED 并写入 extend_props.transferred_order_id(幂等,重复调用直接返回已转订单信息)。", "methods": [ "storage.stockout.toOrder" ], "notes": [ "app/service/systemMethods/storage/stockout.js toOrder 实现:入参 id(出库单ID,必填)、delivery_order_code(可选,不传自动生成 SK 前缀单号)、receiverInfo(可选收件人信息);校验出库单存在且 order_status 为 CREATED/PENDING(否则 400),extend_props.transferred_order_id 存在时幂等返回已转订单", "锁转移:事务内逐明细 lockItemStorages(-plan_qty, orderType=QM_STOCKOUT) 释放出库单锁 → 调 deliveryOrder.addOrder(data, info, 'STOCKOUT') 建单并重新锁库存 → 建单失败/订单号重复时 _restoreStockoutLocks 补偿恢复锁定;建单成功后更新出库单 order_status=CANCELLED 并记录 transferred_order_id/transferred_order_code/transferred_at", "新订单明细手工单风格传 stockId(wms_stock_warehouse.id),sourceOrderCode 写入出库单号便于追溯;create_channel=STOCKOUT 不触发 addOrder 的 API/QM 异步流程,也不会被自动同步任务推送", "app/service/systemMethods/storage/delivery.js toOrder 兼容转发改为透传 data 参数", "app/service/systemMethods/order/base.js CREATE_CHANNEL_LABELS 新增 STOCKOUT: '出库转单',订单工作台渠道列正确显示中文标签", "同步更新 methods/system.json 中 storage.stockout.toOrder 接口文档" ], "module": "storage.stockout" }, { "version": "2026.08.25-storeWarehouse.store.createUser", "date": "2026-08-25", "type": "added", "summary": "新增 storeWarehouse.store.createUser:为货主创建用户。按用户名查询平台账号:账号不存在则自动注册并随机生成 12 位密码返回;两种情况统一完成货主工号绑定并授予货主管理员角色(wms_role.id=5)。幂等:重复调用不会重复创建账号或绑定。", "methods": [ "storeWarehouse.store.createUser" ], "notes": [ "app/service/systems/store_warehouse.js 新增 createUser:校验 username(必填 + 3-50 位字母数字下划线,400)与 store_id(必填正整数,400)→ 货主存在校验(404)→ 按用户名查询账号(不存在则复用 auth.user.register 注册并随机生成 12 位密码)→ 事务内 AccountStoreEmployee.findOrCreate 绑定货主工号(已存在且 status!=1 时恢复为 1)→ 校验货主管理员角色 wms_role.id=5 已初始化(缺失抛 500)→ EmployeeRole.findOrCreate 授予角色(幂等)", "app/service/systemMethods/storeWarehouse/store.js 新增 createUser 包装方法;构造器 _noNeedRight/_noNeedAuth 白名单加入 createUser(isNeedLogin=true 需登录、isNeedAuth=false)", "响应 data:account_id、username、store_id、created(是否本次新建账号;false 表示账号已存在仅完成授权)、password(仅 created=true 时返回 12 位随机明文密码)", "同步更新 methods/system.json 中 storeWarehouse.store.createUser 接口文档" ], "module": "storeWarehouse" }, { "version": "2026.08.25-returnUnpack.forceRecord", "date": "2026-08-25", "type": "added", "summary": "新增 returnUnpack.forceRecord:强制重新录制拆包视频。参考 order.packing.forceRecord,入参 id(拆包单ID);校验仓库录制电脑(wms_print_computer is_recording=true)在线后,将 wms_return_unpack_video 视频记录重置为 created 并清空 video_url,再向打印服务 /record/force 推送 { unpack_id } 触发重新录制。", "methods": [ "returnUnpack.forceRecord" ], "notes": [ "app/service/systems/return_unpack.js 新增 forceRecord:_findByIdChecked 仓库隔离校验(不存在 404 / 跨仓库 403)→ 查询录制电脑(无则 400)→ Redis 在线键 warehouse:{warehouseId}:printer:{computerId} 校验在线(不在线 400)→ 重置视频状态为 created 并清空 video_url → POST {printService.url}/record/force 推送 { unpack_id }(失败抛 500 业务错误)", "app/service/systemMethods/returnUnpack.js 新增 forceRecord 包装方法(与 submit 同层,走 _call 统一错误包装)", "database/migrations/20260825120000-add-return-unpack-force-record-permission.js 新增权限记录 562(returnUnpack.forceRecord,API:退回拆包强制录制),授权角色与作业类 540-545 一致:仓库组-员工(27)/仓库组-主管(26)", "同步更新 methods/system.json 中 returnUnpack.forceRecord 的接口文档" ], "module": "returnUnpack" }, { "version": "2026.08.24-storage.entry-receivingCompare-merge", "date": "2026-08-24", "type": "fixed", "summary": "storage.entry.receivingCompare 对比主体修正:多个收货单先合并明细,再与入库单做一次对照。原实现每个收货单各对照一遍,入库计划数量被重复展开多份,前端对比表格出现重复行。", "methods": [ "storage.entry.receivingCompare" ], "notes": [ "app/service/systems/storage/entry.js receivingCompare 重写:批量校验收货单后合并全部有效收货单明细,新增 _buildMergedComparison(替代 _compareSingleReceiving)输出单一对照视图", "出参结构调整:comparisons[](按收货单拆分)改为 comparison[](合并后逐行对照,每个入库明细仅一行)+ receiving_only[] + summary;matched 行新增 receiving_quantity/receiving_allocated/receiving_available(合并值)与 receiving_sources[](各收货单来源明细),entry_only 行对应数量为 0 且 receiving_sources 为空", "total_summary.matched_count 语义调整为有效参与对比的收货单数(原为处理成功的对照数);无效收货单仍进入 errors[]", "同步更新 methods/system.json 中 receivingCompare 的 response 结构说明" ], "module": "storage.entry" }, { "version": "2026.08.23-returnUnpack.video-url-cdn-domain", "date": "2026-08-23", "type": "fixed", "summary": "修复拆包视频地址未拼接 CDN 域名的问题:returnUnpack.list / returnUnpack.detail / returnUnpack.videoList / returnUnpack.queryByWaybill 输出的 videos[].video_url 此前直接返回相对路径(如 /recordings/...),与 order.packing 输出完整 URL 的口径不一致。现在按打包侧相同规则拼接 http://w{warehouseId}-c{recordingComputerId}.o.gztbyc.com{path}(录制电脑从 wms_print_computer 按 is_recording=true 获取,无录制电脑时保持原始路径)。", "methods": [ "returnUnpack.list", "returnUnpack.detail", "returnUnpack.videoList" ], "notes": [ "app/service/systems/return_unpack.js 新增 _getRecordingComputerId/_buildVideoUrl(与 order_packing.js 同口径,带实例级缓存)", "_enrichRow 视频派生块内对 videos[].video_url 拼接域名(覆盖 list/detail/submit 输出)", "videoList 按 unpack_id 反查 warehouse_id 后拼接;queryByWaybill(inbox 查退回)的 videos 同样拼接", "同步更新 methods/system.json 中 returnUnpack.list 与 returnUnpack.detail 的响应字段描述" ], "module": "returnUnpack" }, { "version": "2026.08.23-stock.warehouse-cache-invalidate-on-update", "date": "2026-08-23", "type": "fixed", "summary": "修复商品资料更新后 getStockDetails 详情缓存未清除的问题:saveWarehouseStock/handleBatchChange 使用 StockWarehouse.update 批量更新(不触发实例级 afterUpdate hook),导致 cache:stock_detail:{warehouseId}:{stockId} 旧数据在 TTL 内持续被读取(如 need_recheck 修改后复核扫描仍返回旧值)。现在两个编辑入口更新成功后显式调用 stockWarehouse.invalidateStockDetailCache 清除对应缓存。", "methods": [ "stock.warehouse.saveWarehouseStock", "stock.warehouse.handleBatchChange" ], "notes": [ "app/service/systems/stock_store.js saveWarehouseStock 提交事务后调用 service.systems.stockWarehouse.invalidateStockDetailCache(id, warehouseId)(失败仅告警不阻断主流程)", "同文件 handleBatchChange 批量更新后按 ids 批量清除详情缓存(Promise.allSettled,失败不阻断返回)", "实证验证:更新后 Redis 缓存 key 被删除,复核扫描/统一查询立即读取到新值" ], "module": "stock" }, { "version": "2026.08.23-recheckOrder.stock-need-recheck", "date": "2026-08-23", "type": "enhanced", "summary": "order.recheckOrder.scanOrder / scanTask 返回报文的 stock 明细新增 need_recheck 字段(Y=需要复核,N=不需要复核,缺省 Y):散单路径 enrichOrdersWithStock 组装与团购路径 buildGroupWaveList 的 stocks 映射均透出,供前端按商品判断是否免复核。", "methods": [ "order.recheckOrder.scanOrder", "order.recheckOrder.scanTask" ], "notes": [ "app/service/systemMethods/order/recheckOrder.js enrichOrdersWithStock stock 对象新增 need_recheck(取 getStockDetails 返回值,缺省 'Y')", "同文件 buildGroupWaveList 的 stocks 映射新增 need_recheck", "同步更新 methods/system.json 中 scanOrder 的 stock children 与 scanTask 的 stock 字段描述" ], "module": "order" }, { "version": "2026.08.23-stock.warehouse-need-recheck", "date": "2026-08-23", "type": "enhanced", "summary": "wms_stock_warehouse 新增 need_recheck(是否需要复核)字段:Y=需要复核(默认),N=不需要复核,非空。编辑(saveWarehouseStock/createWarehouseStock/getInfo/handleBatchChange)、导入(import 支持中文 需要/不需要 或 Y/N,缺省新建默认 Y、更新保留原值)、导出(仓库/外仓导出新增「是否需要复核」列,与导入列名对齐)全链路支持。", "methods": [ "stock.warehouse.getInfo", "stock.warehouse.saveWarehouseStock", "stock.warehouse.createWarehouseStock", "stock.warehouse.import", "stock.warehouse.handleBatchChange", "stock.warehouse.export", "stock.warehouse.externalExport" ], "notes": [ "database/migrations/20260823150000-add-need-recheck-to-wms-stock-warehouse.js 新增迁移(CHAR(1) NOT NULL DEFAULT 'Y',comment: 是否需要复核:Y=需要复核,N=不需要复核)", "app/model/stock_warehouse.js 新增 need_recheck 字段定义(默认 Y、非空)", "app/service/systems/stock_store.js getInfo attributes 增加 need_recheck;saveWarehouseStock 解构/更新数据增加 need_recheck;createWarehouseStock 解构并默认 'Y';validateSaveParams 校验非 Y/N 值报错;handleBatchChange 白名单增加 need_recheck 并校验 Y/N;exportWarehouseStock/exportExternalWarehouseStock 行数据输出中文 需要/不需要 并新增「是否需要复核」导出列", "app/service/systemMethods/stock/warehouse.js saveWarehouseStock 解构并透传 need_recheck;_normalizeWarehouseImportRow 解析「是否需要复核/need_recheck/needRecheck」列并新增 _normalizeNeedRecheckValue 归一化(需要→Y,不需要→N,非法值报错,缺省不覆盖)", "同步更新 methods/system.json 中 getInfo/saveWarehouseStock/createWarehouseStock/import/handleBatchChange 的字段说明" ], "module": "stock" }, { "version": "2026.08.23-pick.intercepted-skip-claim-pick", "date": "2026-08-23", "type": "fixed", "summary": "拦截订单不再阻隔领料/拣货且不参与作业数量:pick.waveClaimScan 打印校验与领料更新跳过拦截订单(拦截未打印不阻隔领料、拦截订单不置为 claim_status=fin,响应 data 新增 intercepted_order_count);pick.query 领料前置校验仅统计非拦截未领料订单(拦截未领料不阻隔拣货,fail data 新增 intercepted_order_count);pick.createWavePickTask 新增 excludeUnclaimed 选项,普通波次(source=0)创建拣货任务计算拣货数量(order_count/任务订单/筐)时剔除未领料订单。", "methods": [ "pick.waveClaimScan", "pick.query", "pick.wavePickComplete" ], "notes": [ "app/service/systemMethods/pick.js waveClaimScan 波次订单查询 attributes 增加 intercept_status,拦截订单集合不参与 unclaimed/unprinted 统计且不参与 claim_status=fin 更新", "app/service/systemMethods/pick.js 新增 getWaveClaimGateStats 辅助方法(统计 total/intercepted/unclaimed,unclaimed 仅计非拦截订单),query 领料门禁改用该统计", "app/service/systemMethods/pick.js createWavePickTask 新增 params.excludeUnclaimed(默认 false):为 true 时 attributes 增加 claim_status 并剔除 claim_status != fin 订单(未领料不参与 order_count/任务订单/筐数量);query 与 wavePickComplete 对普通波次(source=0)传 excludeUnclaimed=true(wavePickComplete 波次查询 SELECT 增加 source)", "同步更新 methods/system.json 中 pick.query 与 pick.waveClaimScan 的 description、400 错误说明与 response 字段" ], "module": "pick" }, { "version": "2026.08.23-returnUnpack.list-video-fields", "date": "2026-08-23", "type": "enhanced", "summary": "returnUnpack.list 对齐打包记录补齐视频字段:列表关联查询视频副表,每条记录新增 has_video(1=有视频记录/2=无)、video_enable(1=录像可用/2=不可用)派生字段与 videos 视频数组(id/video_url/status/camera_id/camera_name),并新增 has_video / video_enable 列表筛选(EXISTS 字面量,口径与 order.packing.list 一致)。", "methods": [ "returnUnpack.list" ], "notes": [ "app/service/systems/return_unpack.js list 改 raw:false 并 include ReturnUnpackVideo as videos(deleted_at IS NULL 过滤 + Camera 关联精简字段),行数据经 _flattenVideos 输出精简视频数组;_enrichRow 对含 videos 数组的记录派生 has_video/video_enable(create 幂等复用与 detail 返回同步受益,videos 结构不变);_buildListWhere 新增 has_video/video_enable 筛选(1/2,EXISTS/NOT EXISTS 字面量)", "同步更新 methods/system.json 中 returnUnpack.list 的 params(where.has_video / where.video_enable)与 response list 字段说明" ], "module": "returnUnpack" }, { "version": "2026.08.22-order.print-custom-area-wave-multiply-qty", "date": "2026-08-22", "type": "enhanced", "summary": "面单自定义区商品明细行尾新增「波次总单数×该行商品数量」:当波次 wms_wave_batch.source=0(普通波次)且 wave_type=1 时,每条商品明细行尾追加 波次总单数 × 该行商品数量(如 500 单 × 3 件 = 1500);策略抓取波次(source=1/2)与其他波次类型不追加。", "methods": [ "order.print.getOrderPrintData", "order.print.getWavePlatformPrintData", "order.print.getPrintDataByWaybillCodes" ], "notes": [ "app/service/systems/order_print.js queryWavesByIds 查询增加 source/wave_type 字段;getWavePlatformPrintData / getOrderPrintData / getPrintDataByWaybillCodes 三条路径构建 waveMetaMap 并在订单行附加 wave_source / wave_type", "app/lib/printer_data_builder.js buildWaybillCustomProductInfoLines 明细行构建时 waveSource=0 且 waveType=1 且 wave_total_orders>0 时行尾追加 波次总单数×qtyNumber(商品数量与乘数之间以两个空格分隔);7 个平台映射(快手/拼多多/抖音/菜鸟/小红书/视频号/京东)同步传入 waveSource/waveType", "更新 test/app/lib/printer_data_builder_package_material.test.js:新增 T15(source=0 且 wave_type=1 行尾乘数)与 T16(source=1 不追加乘数)", "同步更新 methods/system.json 中三个打印方法的 description" ], "module": "order" }, { "version": "2026.08.22-order.print-custom-area-total-qty", "date": "2026-08-22", "type": "enhanced", "summary": "面单打印自定义区首行在快递渠道名后新增「商品总数【n】」:n 优先取订单级商品总数(items_total,权威字段),其次商品明细数量累加,最后 items_count(商品种类数)兜底,避免订单 items 快照宽松文本(stock_id+数量)陈旧不完整导致数量偏差;覆盖菜鸟/京东/拼多多/抖音/快手/视频号/小红书全平台自定义区。", "methods": [ "order.print.getOrderPrintData", "order.print.getWavePlatformPrintData", "order.print.getPrintDataByWaybillCodes" ], "notes": [ "app/lib/printer_data_builder.js buildWaybillCustomProductInfoLines 头部行在快递渠道名后追加 商品总数【n】:fallbackTotalQty(items_total)>0 时优先,否则 safeItems 逐项 resolveItemQuantity 累加,再否则 fallbackItemsCount(items_count)兜底;7 个平台映射(快手/拼多多/抖音/菜鸟/小红书/视频号/京东)分别传入 fallbackTotalQty=items_total、fallbackItemsCount=items_count", "更新 test/app/lib/printer_data_builder_package_material.test.js(T10 包材前缀断言排除商品总数标签、新增 T11 商品总数累加、T12 items_total 兜底优先、T13 items 快照宽松文本不完整时取 items_total、T14 无 items_total 时回退明细累加)与 test/app/service/systems/order_print.getWavePlatformPrintData.test.js(W023 头部行断言追加 商品总数【2】)", "同步更新 methods/system.json 中三个打印方法的 description" ], "module": "order" }, { "version": "2026.08.22-pick.query-wave-claim-gate-source0", "date": "2026-08-22", "type": "enhanced", "summary": "pick.query 新增领料前置校验(仅普通波次 source=0):扫描命中普通波次时,若波次内存在未领料订单(claim_status != fin)则返回 400 并携带 action=wave_claim 提示「订单未领料,请先领料后再拣货」,阻隔开始拣货(中止拣货任务创建);已全部领料或策略抓取波次(source=1/2)不拦截。", "methods": [ "pick.query" ], "notes": [ "app/service/systemMethods/pick.js query 波次查询 SELECT 增加 source 字段并记录 targetWaveSource;目标波次信息校验后插入领料前置校验:source=0 时查询波次订单 claim_status,存在未领单订单 fail 400(data 含 action=wave_claim、wave_id、wave_no、wave_type、wave_source、pick_mode、unclaimed_order_count、total_order_count)", "同步更新 methods/system.json 中 pick.query 的 description 与 400 错误说明" ], "module": "pick" }, { "version": "2026.08.22-stock.warehouse.import-barcode-sync", "date": "2026-08-22", "type": "fixed", "summary": "修复 stock.warehouse.import 传入 barcode(条码)不生效的问题:归一化后条码未在新建/更新路径写入 wms_stock_barcodes 表。现在导入行携带非空 barcode 时,在商品创建/更新成功后调用 saveWarehouseStockBarcode 差异同步条码(未传条码则保留原有条码)。", "methods": [ "stock.warehouse.import" ], "notes": [ "app/service/systemMethods/stock/warehouse.js import():创建/更新成功后,若归一化 barcode 为非空数组,则按结果 id(缺省用行内 SKU)调用 systems.stockStore.saveWarehouseStockBarcode 同步到 wms_stock_barcodes 表", "条码同步失败计入该行 fail_items,且该行不再计入成功计数,便于定位", "未传 barcode(空数组)时不触发同步,避免误清空已有条码;barcode 格式与导出对齐(逗号分隔字符串)" ], "module": "stock.warehouse" }, { "version": "2026.08.22-storage.inventory.list-filter-zero-quantity", "date": "2026-08-22", "type": "enhanced", "summary": "storage.inventory.list 过滤总数量为 0 的商品或明细行:基础查询条件增加 quantity > 0,明细模式(group_by_batch=true)不再返回 quantity=0 的明细行,合并模式(group_by_batch=false)不再返回总数量为 0 的商品。storage.inventory.export 同步保持一致。", "methods": [ "storage.inventory.list", "storage.inventory.export" ], "notes": [ "app/service/systems/storage/inventory.js:getInventoryList 与 exportInventoryList 的 baseWhere 均增加 { quantity: { [Op.gt]: 0 } },动态 where/stock_query 条件不受影响", "明细模式:quantity=0 的 storage 行直接过滤;合并模式:某商品所有明细行均无正数量时分组自然消失,总量为 0 的商品不返回", "storage.inventory.export 入参与 list 语义保持一致(导出同样过滤零量行/零量商品)" ], "module": "storage.inventory" }, { "version": "2026.08.22-storage.inventory.listByStockId-group-by-space", "date": "2026-08-22", "type": "enhanced", "summary": "storage.inventory.listByStockId 新增 group_by_space 双模式:false(默认,不汇总)逐条返回 quantity > 1 明细行(含批次/效期/预警字段,行为不变);true(按库位汇总)先筛 quantity > 1 明细行,再按 space_id 汇总 quantity/locked_quantity/available_quantity,返回库位级汇总行(含 batch_count、first/last_inbound_time、stock/space/store_name),不含批次与效期/预警字段。", "methods": [ "storage.inventory.listByStockId" ], "notes": [ "app/service/systems/storage/inventory.js:getStorageListByStockId(stockId, groupBySpace=false) 两种模式共用同一查询(先筛 quantity > 1 明细行),group_by_space=true 时用新增 _aggregateStorageRowsBySpace 按 space_id 在内存汇总(求和、批次数、最早/最晚入库时间),并保留商品/库位关联与条码图片附属信息", "app/service/systemMethods/storage/inventory.js:listByStockId 透传 group_by_space(支持 true/'true' 布尔/字符串)", "汇总口径:先筛 quantity > 1 的明细行再按库位求和;汇总行不返回批次与效期/库存预警字段" ], "module": "storage.inventory" }, { "version": "2026.08.22-storage.inventory.store-stock-join-dedup", "date": "2026-08-22", "type": "fixed", "summary": "修复库存接口按 stock_id 查询返回重复 storage 行(同 id 多条)的问题:store_stock 关联(belongsTo StoreWarehouse,按 store_id 关联)未按仓库收敛,货主在多仓库存在签约行时 JOIN 多行匹配导致同一库存行重复且 store_name 不一致。改为统一使用 StoreWarehouse.buildStoreStockInclude(按 warehouse_id + warehouse_use_status=1 收敛,命中唯一签约行)。", "methods": [ "storage.inventory.listByStockId", "storage.inventory.list" ], "notes": [ "app/service/systems/storage/inventory.js:getStorageListByStockId、getInventoryList(明细模式与合并模式)三处 store_stock 嵌套 include 均改为 buildStoreStockInclude({ warehouseId, required: false, attributes: ['store_id','store_remask'] })", "wms_store_warehouse 存在 (store_id, warehouse_id) 唯一索引,按仓库收敛后每商品至多命中一行签约关系,不再产生重复明细;合并模式下 SUM(quantity) 也不会因 JOIN 多行而翻倍", "同时修正 storage.inventory.list 同源隐患(明细模式重复行、合并模式数量翻倍),返回结构不变" ], "module": "storage.inventory" }, { "version": "2026.08.22-storage.inventory.listByStockId", "date": "2026-08-22", "type": "added", "summary": "新增 storage.inventory.listByStockId 接口:传入 stock_id,返回该商品在当前仓库下所有 quantity > 1 的 wms_storage 明细行(按 id 倒序),返回结构与 storage.inventory.list 明细模式一致(含 stock 条码/图片、space 库位、货主名称及效期/库存预警字段)。", "methods": [ "storage.inventory.listByStockId" ], "notes": [ "app/service/systemMethods/storage/inventory.js 新增 listByStockId 包装方法,并加入 _noNeedRight/_noNeedLog/_noNeedAuth 豁免列表(与 list 一致)", "app/service/systems/storage/inventory.js 新增 getStorageListByStockId:校验 stock_id 正整数与当前仓库上下文,where 条件 warehouse_id+stock_id+quantity>1+is_enabled=1+delete_at=null,include stock/space 与明细模式一致", "重构 getInventoryList 明细分支:提取 _loadInventoryWarningRanges 与 _formatBatchStorageRows 复用,现有 storage.inventory.list 行为不变" ], "module": "storage.inventory" }, { "version": "2026.08.21-returnUnpack.create-orderItems", "date": "2026-08-21", "type": "enhanced", "summary": "returnUnpack.create 返回新增顶层 order_items 字段:原订单商品明细数组(即 order.items 的顶层透出,含 item_code/item_name/sku_property/quantity/plan_qty/barcodes/image_url 等),仅原单退回且原订单详情解析成功时返回;非原单退回或原订单详情缺失时为 null。新建与幂等复用两个分支返回结构一致。", "methods": [ "returnUnpack.create" ], "notes": [ "app/service/systems/return_unpack.js create:新建分支返回 order_items(order.items 为数组时透出,否则 null);幂等复用分支从 detail().related.order 提取同名字段,与 order 字段同源", "向后兼容:仅新增顶层字段,order/record 等既有字段不变", "同步更新 methods/system.json 中 returnUnpack.create 的 response(新增 order_items 字段说明)" ], "module": "returnUnpack" }, { "version": "2026.08.21-stock.warehouse.search-return-images", "date": "2026-08-21", "type": "enhanced", "summary": "stock.warehouse.search 默认模式返回数据新增 images 字段:批查 wms_file_reference(business_type=stock)+ wms_file 获取商品图片URL列表,按 display_order 升序;无图片时返回空数组。mode=\"combo\" 时不返回该字段。", "methods": [ "stock.warehouse.search" ], "notes": [ "app/service/systems/stock_store.js search:formattedResults 生成后批量查询 FileReference(include File.file_url,raw),按 business_id(商品ID)分组注入 item.images,与 stock.warehouse.list 图片口径一致", "同步更新 methods/system.json 中 stock.warehouse.search 的 response 字段" ], "module": "stock" }, { "version": "2026.08.21-order.pendingOrder.cloneOrder-sync-status-inherit", "date": "2026-08-21", "type": "enhanced", "summary": "order.pendingOrder.cloneOrder 同步状态继承原订单:原订单已同步(sync_status=fin)时新订单直接置 fin,避免克隆后重复回传平台;原订单未同步/同步失败(padding/error)则重置为 padding 重新走同步流程。", "methods": [ "order.pendingOrder.cloneOrder" ], "notes": [ "app/service/systemMethods/order/pendingOrder.js cloneOrder 第 4 步 newOrderData.sync_status 按 original.sync_status 判定:fin→fin,其余→padding(RESET_FIELDS 保留 padding 兜底)", "已同步新订单分配运单号不受 sync_status 限制(createWaybillCodePipeline 只校验 step 1/2/3/4、status、拦截、锁定、已分配运单号),但新订单 step=0 需先审核进入待处理才能分配;已同步订单分配新运单号后不会自动回传平台", "同步更新 methods/system.json 中 cloneOrder 的 description" ], "module": "order" }, { "version": "2026.08.21-order.pendingOrder.cloneOrder-storage-release-tolerant", "date": "2026-08-21", "type": "enhanced", "summary": "order.pendingOrder.cloneOrder 支持克隆已同步(sync_status=fin)订单且库存释放失败不阻断:原订单已分配储位时先清除已分配库存,cancelAllocateStorage 失败降级为告警(与 cancelOrder 策略一致),克隆继续执行;残留占用保留在原订单名下,克隆新订单不重新占用库存(storage_status=none,创建过程不触发储位分配与库存锁定)。", "methods": [ "order.pendingOrder.cloneOrder" ], "notes": [ "app/service/systemMethods/order/pendingOrder.js cloneOrder 第 2 步:清除已分配库存失败由抛错阻断改为 ctx.logger.warn 降级,不影响克隆主流程", "克隆新订单库存零占用(storage_status 重置 none、无自动储位分配),后续如需发货需在待处理工作台重新分配储位", "同步更新 methods/system.json 中 cloneOrder 的 description" ], "module": "order" }, { "version": "2026.08.21-order.pendingOrder.cloneOrder-unique-delivery-code", "date": "2026-08-21", "type": "fixed", "summary": "修复 order.pendingOrder.cloneOrder 复制原单号导致唯一键冲突:新订单 delivery_order_code 重新生成(SYS+时间戳+随机4位,与 createOrder 同规则),原单号写入 pre_delivery_order_code 保留克隆追溯链;此前复制原单号会命中 (delivery_order_code, store_id, warehouse_id) 唯一索引,克隆报「Validation error」且原订单已被取消、新订单未创建(原订单损坏)。", "methods": [ "order.pendingOrder.cloneOrder" ], "notes": [ "app/service/systemMethods/order/pendingOrder.js cloneOrder:COPY_FIELDS 移除 delivery_order_code,新订单单号改为 SYS${Date.now()}${1000~9999 随机} 生成;原订单无 pre_delivery_order_code 时写入原单号保留追溯链;注释说明唯一索引约束与 UniqueConstraintError 表现", "同步更新 methods/system.json 中 cloneOrder 的 description" ], "module": "order" }, { "version": "2026.08.21-index.searchSpaces-batch-search", "date": "2026-08-21", "type": "added", "summary": "新增 index.searchSpaces 批量库位查询接口:keywords 传入字符串数组,逐项按当前仓库上下文模糊查询(space_code/custom_barcode/custom_name,每项最多 50 条),结果按传入顺序以二维数组返回,无记录对应项返回空数组。", "methods": [ "index.searchSpaces" ], "notes": [ "app/service/systems/space.js 抽取 _searchByKeyword 私有查询方法(searchSpace 与 searchSpaces 共用同一查询口径),新增 searchSpaces 并行查询每个关键字并保持传入顺序输出,无记录项返回 []", "app/service/systemMethods/index.js 新增 searchSpaces 出口方法,并加入 _noNeedRight/_noNeedAuth 白名单(与 searchSpace 一致,免鉴权免权限、需登录)", "同步更新 methods/system.json 与 AI_METHOD_ROUTING.md" ], "module": "index" }, { "version": "2026.08.20-order.wave.matched-count-same-express-split", "date": "2026-08-20", "type": "fixed", "summary": "order.wave.waveStrategyList 的 matched_order_count_filtered 计数口径与按策略抓取保持一致:require_same_express=1 的策略按「结构(items_hash)+快递」分组计数并应用 min/max_same_structure,不再仅按结构分组统计,避免列表显示有命中订单但 waveStrategyFetchAdmin 实际抓取为 0 的口径不一致。", "methods": [ "order.wave.waveStrategyList" ], "notes": [ "app/service/systemMethods/order/wave.js getWaveStrategyMatchedOrderCountFilteredMap 改为接收策略行数组并按 require_same_express 拆分两类计数查询:同快递策略按 items_hash+快递(sys_logistics_code>logistics_code>logistics_name COALESCE 口径)分组,其余仅按 items_hash 分组;max_same_structure<=0 视为不设上限,与抓取候选 SQL 归一化一致;调用方 waveStrategyList 改传当前页策略行 list", "同步更新 methods/system.json 中 matched_order_count_filtered 字段描述" ], "module": "order" }, { "version": "2026.08.20-pick.waveClaimScan-print-gate", "date": "2026-08-20", "type": "enhanced", "summary": "pick.waveClaimScan 新增波次打印校验:整波领料前检查波次下全部订单 print_status,存在未打印订单(print_status != fin)时返回 400「波次未打印,禁止领料」(data 含 wave_id、wave_no、unprinted_order_count、total_order_count),波次全部打印后才允许将订单 claim_status 置为 fin;已全部领料幂等结果优先返回,不受打印校验拦截。", "methods": [ "pick.waveClaimScan" ], "notes": [ "app/service/systemMethods/pick.js waveClaimScan 波次订单查询 attributes 增加 print_status,already_claimed 幂等判断之后插入打印校验:unprinted_order_count > 0 时 fail 400「波次未打印,禁止领料」", "同步更新 methods/system.json 中 pick.waveClaimScan 的 description 与 400 错误说明" ], "module": "pick" }, { "version": "2026.08.20-pick.waveClaimScan-source-gate", "date": "2026-08-20", "type": "enhanced", "summary": "pick.waveClaimScan 整波领料资格判定收敛为仅普通波次(wms_wave_batch.source=0)生效:符合时将该波次下全部未领单订单 claim_status 置为 fin 并返回 wave_id/wave_no 与领单说明;策略抓取波次(source=1/2)返回「该波次为抓取波次,无需领料」(data 含 no_claim_needed=true、wave_id、wave_no);波次已全部领料返回 already_claimed 并提示「该波次已领料,无需重复领取」;面单号无记录/订单不在待处理订单表返回 404 无记录提示。", "methods": [ "pick.waveClaimScan" ], "notes": [ "app/service/systemMethods/pick.js waveClaimScan 资格判定由(大团购 wave_type=1 且 pick_mode=5 / 非抓取散单 wave_type=2 且 source=0)改为仅按 source 判定:source=0 全部支持整波领料,source∈{1,2} 返回抓取波次无需领料并携带 no_claim_needed=true、wave_id、wave_no,其余返回不支持提示;already_claimed tip 改为「该波次已领料,无需重复领取」", "app/dict/businessDict.js OPERATION_CODE 补记 ORDER_WAVE_CLAIM:'领取波次'", "同步更新 methods/system.json 中 pick.waveClaimScan 的 description/400/404 错误说明" ], "module": "pick" }, { "version": "2026.08.19-print-custom-area-stock-merge", "date": "2026-08-19", "type": "fixed", "summary": "修复打印自定义区同库位不同商品被合并为一行的问题:拣货明细聚合键由「库位」改为「库位+stock_id」复合键,仅同一库位同一商品才合并数量;stock_id 缺失时依次回退 order_item_id、商品名称+条码,无法识别商品身份时不再跨行合并。", "methods": [ "order.print.getOrderPrintData", "order.print.getWavePlatformPrintData", "order.print.getPrintDataByWaybillCodes" ], "notes": [ "app/service/systems/order_print.js buildPrintOrderRowMapWithPicking 阶段五聚合改为 buildPrintItemAggregationKey 复合键(pick_location::stock:stock_id),同库位不同商品保持独立行,数量/条码不再串;stock_id 字段延迟到聚合完成后才删除,避免污染 items JSON" ], "module": "order" }, { "version": "2026.08.19-pick.claim-prompt-refine", "date": "2026-08-19", "type": "enhanced", "summary": "领料提示文案细化:pick.query 领单前置校验拦截时直接提示「订单未领料,请先领料后再拣货」;pick.waveClaimScan 对抓取的波次(团购小波次 pick_mode=1、策略抓取散单波次 source=1/2)返回「该波次为抓取波次,无需领料」提示(失败 data 新增 no_claim_needed=true),其余未知类型保留通用不支持提示。", "methods": [ "pick.query", "pick.waveClaimScan" ], "notes": [ "app/service/systemMethods/pick.js query 领单前置校验拦截文案由「该波次尚未领单,请先整波领单后再拣货」改为「订单未领料,请先领料后再拣货」,action=wave_claim 等失败 data 字段不变", "app/service/systemMethods/pick.js waveClaimScan 资格判定失败时细分提示:抓取波次(wave_type=2 且 source∈{1,2},或 wave_type=1 且 pick_mode=1)返回「该波次为抓取波次,无需领料」并携带 no_claim_needed=true;其他未知类型保留「当前波次类型不支持整波领单」", "同步更新 methods/system.json 中 pick.query 与 pick.waveClaimScan 的 description/400 错误说明" ], "module": "pick" }, { "version": "2026.08.19-pick.query-wave-claim-gate", "date": "2026-08-19", "type": "enhanced", "summary": "pick.query 新增领单前置校验:扫描命中的波次属于大团购(pick_mode=5)或非抓取散单(wms_wave_batch.source=0 普通波次)时,若波次内存在未领单订单(claim_status != fin)则返回 400 并携带 action=wave_claim 提示先整波领单(pick.waveClaimScan),中止拣货任务创建;已全部领单则继续原流程。", "methods": [ "pick.query" ], "notes": [ "app/service/systemMethods/pick.js query 在解析目标波次后、活动任务去重前插入领单校验:复用 getWavePickModeByWaveId 与 wms_wave_batch.source 判定波次类型(大团购=wave_type 1 且 pick_mode 5;非抓取散单=wave_type 2 且 source 0),查询波次订单 claim_status,存在未领单订单时 fail 400(data 含 action=wave_claim、wave_id、wave_no、wave_type、wave_source、pick_mode、unclaimed_order_count、total_order_count)", "同步更新 methods/system.json 中 pick.query 的 description 与 400 错误说明" ], "module": "pick" }, { "version": "2026.08.19-pick.waveClaimScan", "date": "2026-08-19", "type": "enhanced", "summary": "新增 pick.waveClaimScan 整波领单接口:PDA 扫描波次内一个面单号后,针对大团购(pick_mode=5 团购大波次)与非抓取的散单(wms_wave_batch.source=0 普通波次)将该波次下全部订单 claim_status 置为 fin(领单完成),并写入 ORDER_WAVE_CLAIM 订单操作日志;团购小波次与策略抓取散单波次不支持整波领单,返回 400;波次已全部领单时返回 already_claimed 幂等结果。", "methods": [ "pick.waveClaimScan" ], "notes": [ "app/service/systemMethods/pick.js 新增 waveClaimScan:面单号定位订单(wms_order_express.waybill_code)→ 订单定位波次 → 读取 wms_wave_batch(wave_type/source)与拣货任务 pick_mode 判定资格(大团购=wave_type 1 且 pick_mode 5;非抓取散单=wave_type 2 且 source 0)→ 整波订单 claim_status='fin',并新增 getWavePickModeByWaveId 查询关联拣货模式", "app/service/systemMethods/pick.js 鉴权配置:waveClaimScan 加入 _noNeedRight/_noNeedAuth(免权限、免仓库有效期校验),保留登录校验与请求日志", "app/dict/businessDict.js OPERATION_CODE 新增 ORDER_WAVE_CLAIM:'领取波次'", "同步更新 methods/system.json 中 pick.waveClaimScan 接口文档" ], "module": "pick" }, { "version": "2026.08.19-manual-order-stock-store-guard", "date": "2026-08-19", "type": "fixed", "summary": "手工单(order.pendingOrder.createOrder)新增库存归属货主校验:item_id 直接传仓库 stock_id 时,校验 wms_stock_warehouse.store_id 与订单货主 store_id 一致,跨货主传库存将被拒绝,杜绝把其他货主库存挂在当前货主订单下。", "methods": [ "order.pendingOrder.createOrder" ], "notes": [ "app/service/systems/delivery_order.js addOrderLines 手工单分支(line.stockId)新增 StockWarehouse 归属校验,不一致时计入 errors 并跳过该行,错误文案:商品《xxx》编码《xxx》库存归属货主(store_id=…)与当前货主(store_id=…)不一致,无法创建订单", "同步更新 methods/system.json 中 order.pendingOrder.createOrder 的 notes 说明" ], "module": "order" }, { "version": "2026.08.19-wave-fallback-excluded-reason-cn-label", "date": "2026-08-19", "type": "enhanced", "summary": "order.wave.waveStrategyFallbackOrderList 响应 excluded_reason 由英文枚举值改为中文标签:locked→已锁定、intercepted→已拦截、printed→已打印、no_match→未匹配策略。", "methods": [ "order.wave.waveStrategyFallbackOrderList" ], "notes": [ "app/service/systemMethods/order/wave.js 新增 WAVE_STRATEGY_FALLBACK_EXCLUDED_REASON_LABELS 常量并用于 buildWaveStrategyFallbackOrderListItem,判定优先级不变", "同步更新 methods/system.json 中该接口 excluded_reason 字段与 list 说明" ], "module": "order" }, { "version": "2026.08.19-wave-fallback-excluded-reason-lock-fix", "date": "2026-08-19", "type": "fixed", "summary": "修复 order.wave.waveStrategyFallbackOrderList 所有行 excluded_reason 恒为 locked 的问题:列表行经 normalizeOrderListItem 后 lock_status 已归一化为 Y/N,原判断 lock_status !== 'none' 恒成立导致全部误标 locked;改为兼容归一化值(Y=锁定,N/none/空=未锁定)与原始值(warehouse/store 等),恢复 locked/intercepted/printed/no_match 的正确判定。", "methods": [ "order.wave.waveStrategyFallbackOrderList" ], "notes": [ "app/service/systemMethods/order/wave.js buildWaveStrategyFallbackOrderListItem 新增 lockStatus 归一化与 isLocked 判定(Y 或非 none/非 N 的原始值视为锁定),excluded_reason 优先级不变:locked > intercepted > printed > no_match" ], "module": "order" }, { "version": "2026.08.19-order-list-wave-index-range-filter", "date": "2026-08-19", "type": "enhanced", "summary": "订单列表 where 新增 wave_index 波次内序号范围查询入参:工作台订单列表(经 listByModule 的 9 个列表)与订单导出支持 wave_index 虚拟筛选(eq/in/gt/lt/ge/le/between/notbetween,between 要求 value 为长度 2 的数组);复核散单列表支持 wave_index between 与 wave_index_min/wave_index_max。", "methods": [ "order.list", "order.reviewOrder.list", "order.pendingOrder.list", "order.outboundOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list", "order.archiveOrder.list", "order.recheckOrder.recheckOrderList", "order.recheckOrder.queryRecheckOrderSingleList" ], "notes": [ "新增 app/model/order_wave_index.js 模型(wms_order_wave_index,timestamps=false),供副表条件查询", "app/service/systemMethods/order/base.js 新增 extractWaveIndexVirtualFilter(从 where 提取 wave_index/waveIndex,兼容数值简写按 eq 处理)与 findOrderIdsByWaveIndexCondition(用 parseWhereConditions 解析条件后查副表得 order_id 集合);listByModule 在 stock_query 之后接入,命中为空时主查询结果为空", "app/service/systems/order_export.js exportOrders 同样接入 wave_index 虚拟筛选,与列表 where 语义一致", "app/service/systemMethods/order/recheckOrder.js queryRecheckOrderSingleList 新增 wave_index 筛选(between/gte/lte/eq 或 wave_index_min/wave_index_max),countSql 同步 LEFT JOIN wms_order_wave_index 保持总数一致", "同步更新 methods/system.json 中 order.list 与复核列表 where 参数说明" ], "module": "order" }, { "version": "2026.08.19-order-list-wave-index-join", "date": "2026-08-19", "type": "enhanced", "summary": "所有订单列表统一联查 wms_order_wave_index 并输出 wave_index(波次内序号,无记录时降级为 0):覆盖 9 个工作台订单列表(order.list / reviewOrder.list / pendingOrder.list / outboundOrder.list / expectionOrder.list / entrustOrder.list / deliveryOrder.list / deliveryExpectionOrder.list / archiveOrder.list)、复核散单列表与波次策略兜底列表;订单导出(waybill/item 两种模式)新增「波次序号」列。", "methods": [ "order.list", "order.reviewOrder.list", "order.pendingOrder.list", "order.outboundOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list", "order.archiveOrder.list", "order.recheckOrder.recheckOrderList", "order.recheckOrder.queryRecheckOrderSingleList", "order.wave.waveStrategyFallbackOrderList" ], "notes": [ "app/service/systemMethods/order/base.js 新增 attachOrderWaveIndex:按列表行 id 批量查询 wms_order_wave_index(warehouse_id + order_id,命中唯一索引),无记录或查询异常时降级为 0 并告警;listByModule 在 attachOrderExpressNumbers 之后接入,统一覆盖全部工作台订单列表", "app/service/systemMethods/order/wave.js waveStrategyFallbackOrderList 接入 attachOrderWaveIndex,buildWaveStrategyFallbackOrderListItem 输出 wave_index(默认 0)", "app/service/systemMethods/order/recheckOrder.js queryRecheckOrderSingleList 列表 SQL 增加 LEFT JOIN wms_order_wave_index(warehouse_id + order_id),响应行新增 wave_index;recheckOrderList 散单分支同源生效", "app/service/systems/order_export.js exportOrders 接入 attachOrderWaveIndex,ORDER_EXPORT_COLUMNS / ORDER_EXPORT_ITEM_COLUMNS 在波次号后新增「波次序号」列,mapOrderExportRow commonFields 新增 wave_index", "同步更新 methods/system.json 中上述接口的 response 字段说明" ], "module": "order" }, { "version": "2026.08.19-recheckOrder.confirmIntercept-ids", "date": "2026-08-19", "type": "enhanced", "summary": "order.recheckOrder.confirmIntercept 入参由单值 order_id 改为批量 ids:支持数组或以逗号分隔的字符串(兼容 id/order_id/orderId 单值写法),批量确认拦截,返回 success/failed 列表与 success_count/failed_count 计数;单个订单失败不再阻断整体,未找到订单与更新失败订单记录在 failed 列表", "methods": [ "order.recheckOrder.confirmIntercept" ], "notes": [ "app/service/systemMethods/order/recheckOrder.js confirmIntercept:用 base.normalizeOrderIds 解析 ids(兼容 ids/id/order_id/orderId),findAll 批量查询后逐订单执行拦截主流程(intercept_status=intercepted_at_warehouse、step=4、outbound_status=fin,运单标记 is_back/is_intercept='Y',释放储位分配与订单锁,写入 ORDER_INTERCEPT_CONFIRM 操作日志),未找到订单与处理异常订单记录 failed 不抛错,仅 ids 全部无效时 400「订单ID列表不能为空」", "确认拦截前置校验:仅拦截发起中状态(requested/requesting/intercepting,历史值 intercepted 兼容)允许确认;未发起拦截(none/空)的订单直接静默跳过不参与处理,已确认拦截(intercepted_at_warehouse)订单跳过避免重复副作用并记录 failed「订单已确认拦截」,其余非可确认状态(intercepted_in_transit/returning/returned/delivered_by_mistake/timeout/cancelled/failed/exception)记录 failed「订单拦截状态不允许确认拦截: {状态}」;更新 SQL where 同时限定 intercept_status 白名单(CONFIRMABLE_INTERCEPT_STATUSES),防止查询后状态被并发修改导致误更新", "售后工单+快递群通知由原每订单调用改为按成功订单 ID 汇总后统一调用一次 afterSale.createInterceptWorkOrdersAndNotify,失败仅告警", "返回结构由单对象改为 { success, failed, success_count, failed_count },success 每项保持 order_id/order_no/intercept_status/updated_at,failed 每项含 order_id/delivery_order_code/reason", "同步更新 methods/system.json 中该接口 params(ids)、response 与 errors 文档" ], "module": "order.recheckOrder" }, { "version": "2026.08.18-order-list-lock-status-filter-doc", "date": "2026-08-18", "type": "enhanced", "summary": "订单列表 where 补充 lock_status 筛选说明:未锁定传 lock_status=none,已锁定(所有非 none)传 lock_status={operator:ne,value:none};筛选用数据库原始枚举 none/warehouse/store 而非响应 Y/N,条件值为空自动忽略。", "methods": [ "order.pendingOrder.list" ], "notes": [ "仅文档补充,无代码改动:methods/system.json 中 order.pendingOrder.list 的 where 参数 description 增加 lock_status 筛选说明", "行为依据:app/service/systemMethods/order/base.js listByModule/buildWhere 对 where 无字段白名单(仅禁止 warehouse_id/warehouseId),可直接传订单表列名;app/lib/query_condition_parser.js 支持 ne 操作符且条件值为空时自动忽略(isEmptyValue 跳过)", "lock_status 数据库原始枚举 none/warehouse/store(app/model/order_delivery.js LOCK_STATUS),列表响应仍统一输出 Y/N(normalizeLockStatusFlag:none→N,其余→Y),筛选入参必须用原始枚举而非响应 Y/N", "同样经 listByModule 的其它工作台订单列表(order.reviewOrder.list / order.outboundOrder.list / order.expectionOrder.list / order.entrustOrder.list / order.deliveryOrder.list / order.deliveryExpectionOrder.list / order.archiveOrder.list)where 语义一致,本次保持其文档不变,重点仅更新 order.pendingOrder.list" ], "module": "order" }, { "version": "2026.08.18-setting.expressInterface.update-doc-params", "date": "2026-08-18", "type": "enhanced", "summary": "补全 setting.expressInterface.update 接口文档:入参由 3 个字段扩展为全量可更新字段(含 town_name/townName、is_enabled/isEnabled、providertype 等),并补充全量响应字段与错误码说明。", "methods": [ "setting.expressInterface.update" ], "notes": [ "入参按 app/service/systems/setting/expressInterface.js update() 与包装层 app/service/systemMethods/setting/expressInterface.js update() 实际支持的字段补齐,含驼峰别名(shopId/townName/isEnabled 等),仅传入的字段被更新", "响应按 normalizeInterfaceRow 返回结构补齐全量字段", "仅文档变更,无代码改动" ], "module": "setting.expressInterface" }, { "version": "2026.08.18-order-lock-status-guard-and-list-yn", "date": "2026-08-18", "type": "enhanced", "summary": "新增锁定订单作业门禁与订单列表 lock_status 转 Y/N:lock_status 非 none(枚举 warehouse/store)的订单在分配储位、分配快递、抓取波次、自动加团等流程中被直接跳过,跳过明细通过 skipped_locked_order_ids / excluded_locked_order_ids / skipped_orders 等字段返回;订单列表 lock_status 统一输出 Y/N(none→N,其余→Y)。", "methods": [ "order.pendingOrder.list", "order.pendingOrder.allocateExpressCode", "order.pendingOrder.allocateStorage", "order.wave.singleFetchByIds", "order.wave.waveStrategyFallbackOrderList", "order.wave.batchAllocateExpress", "order.wave.batchAllocateExpressTaskProgress", "order.wave.batchAllocateStorage", "order.wave.batchAllocateStorageTaskProgress" ], "notes": [ "新增 app/lib/lock_guard.js isLockedOrderStatus:lock_status 非 'none' 即视为已锁定(枚举 none/warehouse/store)", "app/service/systems/order_storage_allocation.js allocatePicking:过滤循环新增锁定订单跳过,skipped 记录含 lock_status 与 skipped_reason='locked';order.storageAllocation.allocateStorage / order.pendingOrder.allocateStorage / order.wave.batchAllocateStorage 共用该底层入口", "app/service/systems/express.js createWaybillCodePipeline:查询新增 lock_status 字段,锁定订单与拦截订单同样剔除,返回结果新增 skipped_locked_order_ids", "app/service/systemMethods/order/wave.js runBatchAllocateExpressTask:查询新增 lock_status,任务进度与 result 新增 skipped_locked_order_ids;singleFetchByIds 查询属性新增 lock_status 并过滤锁定订单,响应新增 excluded_locked_order_ids(两个返回分支均返回);waveStrategyFallbackOrderList 查询追加 lock_status/intercept_status 非 none 条件,列表行新增 excluded_reason(locked/intercepted/printed/no_match)", "app/service/systems/delivery_order.js asyncProcessOrderCreated:订单已锁定时跳过自动分配快递/储位/自动加团三步;appendOrderToWave 增加锁定校验且更新波次时 where 追加 lock_status='none';countCandidateGroupOrders 过滤 lock_status='none'(内部流程,无公开接口)", "app/service/systemMethods/order/base.js 新增 normalizeLockStatusFlag:none(含空值)返回 'N',其余值一律返回 'Y';normalizeOrderListItem 统一覆盖 lock_status 输出为 Y/N,影响 order.pendingOrder.list、order.wave.waveStrategyFallbackOrderList 及经 listByModule 的各类工作台订单列表", "同步更新 methods/system.json 中上述 method 的 description 与 response 字段" ], "module": "order" }, { "version": "2026.08.18-storage.entry.addItem-non-binding", "date": "2026-08-18", "type": "fixed", "summary": "库存导入(storage.entry.addItem 导入/PDA 入库)不再强制绑定收货单:原 PENDING 状态下未绑定收货单拒绝上架、每项缺少 receiving_detail_id 拒绝,导致移除绑定收货单后仍限制必须传入收货单 ID。现 PENDING 状态允许不绑定收货单直接导入(非绑定模式,数量受计划数量限制),传 receiving_detail_id 时仍走绑定模式(预占收货明细)", "methods": [ "storage.entry.addItem" ], "notes": [ "app/service/systems/inbound_direct_log.js addItem:删除 PENDING 状态下 hasReceivingBindings 与 receiving_detail_id 的强制校验,绑定模式 space_id/可用数量校验仍由 _addSingleItem 统一处理;CREATED 已绑定收货单需先审核的限制保留", "PENDING 非绑定模式导入数量仍受计划数量限制(isManualImport 仅 CREATED 且非绑定可超计划),防止超计划入库", "同步更新 methods/system.json 中 storage.entry.addItem 的 description、receiving_detail_id 参数说明与错误码列表(移除两条 PENDING 绑定错误码)" ], "module": "storage.entry" }, { "version": "2026.08.18-recheckOrder.scanOrder.singleIntercept", "date": "2026-08-18", "type": "fixed", "summary": "修复 order.recheckOrder.scanOrder 散单模式拦截订单识别:原逻辑对波次内所有订单执行复核校验,只要波次内存在一单已进入拦截流程(requested/requesting/intercepting/intercepted_in_transit/intercepted_at_warehouse,历史值 intercepted 兼容),整个散单扫描视图即报错「订单已被拦截,无法提交复核」,导致波次内其他正常订单也无法复核。现拦截订单保留在 list 中按单提示(intercept_status),不再阻断整个扫描视图加载,且不计入复核/打印统计", "methods": [ "order.recheckOrder.scanOrder", "order.recheckOrder.scanTask" ], "notes": [ "buildSingleWaveScanView:用 isInterceptedOrderStatus 分离拦截订单,仅非拦截订单参与 assertOrderCanRecheck 校验与 reviewed/unreviewed/printed/unprinted 统计,拦截订单保留在 list 中按单提示", "车号/任务模式(cart/task)合并多个波次后,reviewed_count/unreviewed_count 仅统计非拦截订单,total_orders 仍为订单总数", "同步更新 methods/system.json 中 scanOrder 散单订单项 intercept_status 字段说明" ], "module": "order" }, { "version": "2026.08.17-inbox-group-reset", "date": "2026-08-17", "type": "enhanced", "summary": "新增 inbox.group.reset 群操作接口:入参群记录主键ID,清空群类型配置(group_type/sub_type/store_id/express_interfaces/system_express_code 置空、ai_enabled 重置为0),仅保留群创建时信息(群名称/群ID/仓库/来源/屏蔽状态/扩展数据)", "methods": [ "inbox.group.reset" ], "notes": [ "app/service/systems/inbox/group.js reset:仓库隔离按主键 id 定位群,清空类型相关字段并写操作日志,返回重置后群信息", "app/service/systemMethods/inbox.js 新增 groupReset,注册到 inbox.group 子入口", "数据库迁移 20260817120000-add-inbox-group-reset-permission.js:权限ID 556 授权角色 8/26/28/29", "同步更新 methods/system.json 中 inbox.group.reset 接口文档" ], "module": "inbox.group" }, { "version": "2026.08.17-afterSale-handleWorkOrder-remark-notify-group", "date": "2026-08-17", "type": "enhanced", "summary": "afterSale.handleWorkOrder 处理备注同步发送到对应货主售后群:填写 remark 时推送到货主售后群(工单 store_id 定位,缺失时从来源消息所在群反查货主,不转发快递群);消息内容格式为「【工单 售后单号】处理备注:备注内容」;响应新增 notified_groups 返回发送群数量", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "app/service/systems/afterSale.js handleWorkOrder:新增 notifyGroup 参数(方法层交互处理传 true,内部自动处理如库内拦截/退回已收到不传),事务提交后按 remark 非空发送:store_id 定位货主 → findStoreAfterSalesGroups 发货主售后群;无 store_id 时按 inbox_message_id 查来源消息 group_id → InboxGroup 反查 store_id 再发送;发送失败仅告警不影响处理结果", "app/service/systemMethods/afterSale.js handleWorkOrder:调用 systems 层时传 notifyGroup: true", "同步更新 methods/system.json 中 afterSale.handleWorkOrder 的 description、remark 参数说明与 notified_groups 响应说明" ], "module": "afterSale" }, { "version": "2026.08.16-waybill-createAt-between", "date": "2026-08-16", "type": "enhanced", "summary": "waybill.warehouse.list / export 创建时间筛选统一为 between 区间写法:where.createdAt 支持 {operator:\"between\", value:[起始,结束]},保留 createdAtStart/createdAtEnd 旧写法兼容", "methods": [ "waybill.warehouse.list", "waybill.warehouse.export" ], "notes": [ "app/service/systems/waybill.js list/export:createdAt 数组区间两端可单独为空,分别落 create_at gte/lte;同时兼容 createAt 别名与 createdAtStart/createdAtEnd 旧写法", "同步更新 methods/system.json 中 waybill.warehouse.list / export 的 where.createdAt 参数文档" ], "module": "waybill.warehouse" }, { "version": "2026.08.16-order-packing-list-time-filter", "date": "2026-08-16", "type": "enhanced", "summary": "order.packing.list 时间筛选统一为 between 区间写法:start_time / end_time / create_time 支持 {operator:\"between\", value:[起始,结束]},与已有 start_time_start/start_time_end 旧写法兼容", "methods": [ "order.packing.list" ], "notes": [ "app/service/systems/order_packing.js list:新增 applyTimeRangeFilter,统一处理 start_time/end_time/create_time 的 between 区间条件(数组两端可单独为空,按 gte/lte 拼接),与 warehouse_id 隔离及其他筛选叠加", "保留 start_time_start/start_time_end 旧拆分写法的兼容处理", "同步更新 methods/system.json 中 order.packing.list 的 where 参数文档" ], "module": "order.packing" }, { "version": "2026.08.16-waybill-export-ids", "date": "2026-08-16", "type": "enhanced", "summary": "waybill.warehouse.export 新增 where.ids 入参:支持按运单ID列表(勾选)导出快递号,与仓库隔离条件叠加过滤", "methods": [ "waybill.warehouse.export" ], "notes": [ "app/service/systems/waybill.js export:新增 where.ids 处理,数组值经 Number 转换并过滤非法值后生成 id IN (...) 条件,与 warehouse_id 隔离条件叠加,不影响其他筛选字段", "入口层 systemMethods/waybill/warehouse.js export 原样透传 where,无需改动", "同步更新 methods/system.json 中 waybill.warehouse.export 的 where.ids 参数文档" ], "module": "waybill.warehouse" }, { "version": "2026.08.15-packing-setEndTime-cap", "date": "2026-08-15", "type": "enhanced", "summary": "order.packing.setEndTime 增加结束时间上限约束:传入结束时间超过仓库配置的打包最大时长上限(散单 single_order_pack_max_minutes / 团购 group_order_pack_max_minutes)时,自动截断为 开始时间+上限时长 后落库", "methods": [ "order.packing.setEndTime" ], "notes": [ "app/service/systems/order_packing.js setEndTime:结束时间不能早于开始时间校验之后,复用 workbench.resolvePackTaskEndTime 做上限截断(按 pack_mode 区分散单/团购配置,未配置有效时长时不约束)", "截断使用最终值落库与响应(end_time/status 同步返回截断后的时间)", "与 workbench.finishPack / packOrder 关闭旧任务 / 定时任务自动结束 的 end_time 上限语义对齐", "同步更新 methods/system.json 中 order.packing.setEndTime 的 description、end_time 参数与响应说明" ], "module": "order.packing" }, { "version": "2026.08.15-pack-task-end-time-cap", "date": "2026-08-15", "type": "enhanced", "summary": "打包任务结束时间增加上限约束:工作台结束任务时(finishPack 手动结束、packOrder 关闭上一个未结束任务),若结束时间超过仓库配置的打包最大时长上限(散单 single_order_pack_max_minutes / 团购 group_order_pack_max_minutes),自动截断为 开始时间+上限时长", "methods": [], "notes": [ "app/service/systems/workbench.js 新增 resolvePackTaskEndTime:按 warehouse_id+pack_mode 读取配置上限分钟,候选结束时间超过 开始时间+上限 时返回上限时间点,未配置有效时长或 start_time 非法时不约束", "_packOrder 步骤4 关闭上一个未结束任务、_finishPack 手动结束 两处结束路径统一接入约束,_finishPack 响应 end_time 同步返回约束后的时间", "与定时任务 auto_finish_pack_task 语义一致:end_time 最多为 开始时间+上限时长,自动结束与手动结束行为对齐", "创建任务时即完成(packStatus>=2)的场景 end_time=start_time,不超上限,无需处理" ], "module": "setting.warehouse" }, { "version": "2026.08.15-pack-task-auto-finish", "date": "2026-08-15", "type": "added", "summary": "新增打包任务自动结束定时任务(每小时一次):扫描 wms_pack_task 未结束任务,按仓库配置 single_order_pack_max_minutes(散单,默认 3 分钟)/ group_order_pack_max_minutes(团购,默认 40 分钟)判断超时,当前时间-开始时间超过上限时将 end_time 置为开始时间+上限时长并标记已完成", "methods": [], "notes": [ "新增 app/schedule/auto_finish_pack_task.js:interval 1h、type worker、非 immediate,单 worker 防重入(ctx.app._autoFinishPackTaskRunning)", "新增 app/service/systems/pack_task_auto_finish.js:扫描 status < 2 且 start_time 非空的任务,按 warehouse_id 去重后经 deliveryOrder.getStoreSubjectConfig(缓存优先)拉取配置,pack_mode=2 按团购时长、其余按散单时长", "超时判定:当前时间 - 开始时间 > 配置分钟数;结束时间 = 开始时间 + 上限时长(而非当前时间),status 置为 2", "未配置有效时长(缺失或非正整数)的仓库跳过,不做自动结束;任务 start_time 非法时跳过", "配置字段与仓库设置联动:single_order_pack_max_minutes / group_order_pack_max_minutes 已在 WAREHOUSE_SETTING_FIELDS 与 Store.normalizeSubjectConfig 中注册,默认值 3 / 40 分钟" ], "module": "setting.warehouse" }, { "version": "2026.08.15-warehouse-pack-max-minutes", "date": "2026-08-15", "type": "added", "summary": "仓库设置 setting.warehouse 新增打包最大时长配置:single_order_pack_max_minutes 散单打包最大时长(分钟,默认 3)、group_order_pack_max_minutes 团购打包最大时长(分钟,默认 40)", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.getFieldMeta", "setting.warehouse.saveSettings" ], "notes": [ "在 WAREHOUSE_SETTING_FIELDS 中新增 single_order_pack_max_minutes(integer,非必填,默认 3,min 1)与 group_order_pack_max_minutes(integer,非必填,默认 40,min 1)", "wms_store.subject_config 默认值同步补齐(app/model/store.js DEFAULT_SUBJECT_CONFIG),normalizeSubjectConfig 增加大于 0 的整数校验,空值回退默认", "methods/system.json 中 getSettings 响应与 saveSettings 入参补充对应字段文档", "向后兼容:新增字段为可选,不影响既有仓库设置读写" ], "module": "setting.warehouse" }, { "version": "2026.08.15-recheckOrder.scanOrder.groupInterceptSeq", "date": "2026-08-15", "type": "fixed", "summary": "修复 order.recheckOrder.scanOrder 团购模式拦截订单识别:原逻辑仅匹配不存在的 'intercepted' 状态,导致已进入拦截流程的订单(requested/requesting/intercepting/intercepted_in_transit/intercepted_at_warehouse)被当作正常订单,团购复核数据不输出拦截订单及其序号。现统一按真实拦截状态枚举归类到波次项 intercepted 列表,并输出 wave_index 波次内序号", "methods": [ "order.recheckOrder.scanOrder", "order.recheckOrder.scanTask" ], "notes": [ "新增 isInterceptedOrderStatus 辅助方法:intercepted / requested / requesting / intercepting / intercepted_in_transit / intercepted_at_warehouse 均视为拦截流程状态", "buildGroupWaveList 拦截订单分离改用 isInterceptedOrderStatus,拦截订单不再进入正常订单校验与统计,仓库已拦截订单不再阻断整个团购扫描视图加载", "团购波次项 intercepted 列表每项新增 waybill_no 字段,wave_index 为波次内序号(优先读取 wms_order_wave_index 真实序号,无记录时降级数组临时序号)", "confirmRecheckByWaveId 团购波次批量复核同步修正拦截识别,拦截订单不再被批量标记复核", "同步更新 methods/system.json 中 scanOrder 团购波次项 intercepted 字段说明" ], "module": "order" }, { "version": "2026.08.15-parseAddress.batch", "date": "2026-08-15", "type": "enhanced", "summary": "parseAddress 支持数组批量入参:addresses(或 address)传字符串数组时批量解析,响应 data.list 按输入顺序返回每条地址的解析结果(含失败条目逐条错误信息)", "methods": [ "order.pendingOrder.parseAddress" ], "notes": [ "入参兼容三种形态:address 字符串(单条,原行为不变)、address 字符串数组、addresses 字符串数组(优先)", "批量解析:按每 10 条合并为一个 DeepSeek 请求并行发出(deepseek-v4-flash),全部返回后按输入顺序聚合,单次上限 50 条;失败/缺失条目逐条回退单条解析,不影响其他条目", "批量响应 data.list 每条元素包含 address/flag/message/province/city/area/town/detailAddress/name/mobile,失败条目 flag=failure、message 为具体错误原因、解析字段为空字符串,不影响其他条目", "抽取 _parseSingleAddress 私有方法复用单条解析逻辑,单条响应结构与之前完全一致", "同步更新 methods/system.json 中 parseAddress 的参数与响应字段说明" ], "module": "order" }, { "version": "2026.08.14-afterSale.detail-desc-first-step", "date": "2026-08-14", "type": "enhanced", "summary": "enhance: afterSale.detail 步骤列表默认将售后详细描述作为第一条 step 输出(虚拟步骤不落库),保证详情页首条即可看到售后问题描述。", "methods": [ "afterSale.detail" ], "notes": [ "售后主表 description 非空时,steps 列表头部前置一条虚拟步骤:action=售后描述、remark=description、step_status=pending、created_at=主表创建时间、attachments=[]、is_virtual=true、id=null", "虚拟步骤不写入 wms_after_sale_detail,仅在 detail 响应中动态拼接", "after_sale.started_at 仍取首条真实步骤记录的创建时间,不受虚拟步骤影响", "description 为空时不生成虚拟步骤,行为与之前一致", "同步更新 methods/system.json 中 afterSale.detail 的 steps 字段说明" ], "module": "afterSale" }, { "version": "2026.08.14-afterSale.workList-storeName", "date": "2026-08-14", "type": "changed", "summary": "afterSale.workList 返回列表行新增 store_name 货主名称字段:取合约表 wms_store_warehouse.store_remask 货主备注名称,无合约或备注为空时回退 wms_store.company_name 公司全称,无货主时为空字符串", "methods": [ "afterSale.workList" ], "notes": [ "systems/afterSale.js list() 新增 opts.enrichStoreName 开关,开启后调用新增私有方法 _enrichListStoreNames 批量补充:按行收集 store_id/warehouse_id,一次查询 StoreWarehouse(store_remask)与 Store(company_name),映射后写入每行 store_name", "systemMethods/afterSale.js workList 调用 list 时传 enrichStoreName: true;auditList 不受影响", "向后兼容:仅在列表行新增 store_name 字段,不影响既有字段", "同步更新 methods/system.json 中 afterSale.workList 的 response.list 字段说明" ], "module": "afterSale" }, { "version": "2026.08.14-returnUnpack.stockDetails", "date": "2026-08-14", "type": "changed", "summary": "returnUnpack 明细补充库存详情:detail/detailList/addDetail/updateDetail 返回的明细行统一走 stockWarehouse.getStockDetails 通用方法附加 stock 字段(item_code/item_name/sku_property/barcodes 条码数组/image_url 图片数组/packing_requirements/stock_unit/quantity/locked_quantity 等,带缓存),补齐条码与照片信息;create 幂等复用返回的 record.details 同步受益", "methods": [ "returnUnpack.detail", "returnUnpack.detailList", "returnUnpack.addDetail", "returnUnpack.updateDetail", "returnUnpack.create" ], "notes": [ "systems/return_unpack.js 新增私有方法 _enrichDetailsWithStock:收集明细 stock_id 批量调用 stockWarehouse.getStockDetails(缓存 key cache:stock_detail:{warehouseId}:{stockId}),按 stock_id 映射为明细行 stock 字段;未识别明细(stock_id 为空)/商品失效/拉取失败时 stock=null,不影响主流程", "detail:record.details 逐条附加 stock;detailList:list 逐条附加 stock(取首行 warehouse_id 作为查询仓库);addDetail/updateDetail:返回 detail 附加 stock(用主表 warehouse_id)", "向后兼容:明细行原有字段与 stockWarehouse 关联保持不变,仅新增 stock 字段", "同步更新 methods/system.json 中 create/detail/detailList/addDetail/updateDetail 的响应字段说明" ], "module": "returnUnpack" }, { "version": "2026.08.14-returnUnpack.createReuse", "date": "2026-08-14", "type": "changed", "summary": "returnUnpack.create 增加幂等复用:同一仓库同一运单号 3 个月内已存在非 cancelled 拆包单时不重复创建,直接返回已有拆包单的主表+明细(record.details)+视频+原订单详情,并携带 reused=true 标识;同运单号多张拆包单时优先复用已录明细的最新单;超过 3 个月视为运单号复用,按新单正常创建", "methods": [ "returnUnpack.create" ], "notes": [ "开单前先按 warehouse_id+waybill_code+created_at>=3个月前 查全部非 cancelled 拆包单(created_at DESC, id DESC)", "同运单号存在多张拆包单时优先复用已录明细的最新单(按 wms_return_unpack_detail 真实计数判定,不依赖主表冗余 total_items),避免命中并发/重复点击产生的空单导致返回明细为空;全部无明细时复用最新单", "命中时复用 detail 查询逻辑组装 record(含 details 明细+stockWarehouse 关联、videos、returnReceived)与 related.order,返回字段新增 reused=true", "查重失败仅记日志不阻断开单主流程;3 个月时间基准与退回查询记录反查货主窗口一致", "同步更新 methods/system.json 中 returnUnpack.create 的 description 与 response(record/reused 字段说明)" ], "module": "returnUnpack" }, { "version": "2026.08.14-warehouse-receive-address", "date": "2026-08-14", "type": "added", "summary": "仓库设置 setting.warehouse 新增仓库收货地址配置字段 receiver_address(一行文本,退货/退件收件地址)", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.getFieldMeta", "setting.warehouse.saveSettings" ], "notes": [ "在 WAREHOUSE_SETTING_FIELDS 中新增 receiver_address(string,非必填,默认空字符串,最大长度 500)", "wms_store.subject_config 默认值同步补齐(app/model/store.js DEFAULT_SUBJECT_CONFIG)", "methods/system.json 中 getSettings 响应与 saveSettings 入参补充对应字段文档", "向后兼容:新增字段为可选,不影响既有仓库设置读写" ], "module": "setting.warehouse" }, { "version": "2026.08.13-stockQueryWhere", "date": "2026-08-13", "type": "added", "summary": "storage.receiving.getReceivingList / getStoreReceivingList 新增 stock_query_where 参数:按商品条码/商品编码/商品ID 搜索,经收货明细关联过滤收货单列表(仓库侧与货主侧同步支持)", "methods": [ "storage.receiving.getReceivingList", "storage.receiving.getStoreReceivingList" ], "notes": [ "新增 stock_query_where 入参(string|string[], optional, body,前端通常传数组),搜索范围:wms_stock_barcodes.barcode + wms_stock_warehouse.item_code + wms_stock_warehouse.id(纯数字时精确匹配)", "解析链路:stock_query_where → wms_stock_warehouse.id 集合 → wms_receiving_detail.system_product_id IN 集合 → receiving_id 列表", "与 filterDepleted、entry_order_id 可组合使用(多组过滤取交集,仓库侧),无匹配结果时返回空列表", "代码变更:systems/storage/receiving.js 新增 _resolveStockQueryReceivingIds 并对两个列表方法注入过滤;systemMethods/storage/receiving.js 两个列表方法均透传 stock_query_where;methods/system.json 两个接口均新增参数文档" ], "module": "storage" }, { "version": "2026.08.12-confirmIntercept-doc", "date": "2026-08-12", "type": "updated", "summary": "order.recheckOrder.confirmIntercept 文档描述补全:补充释放储位分配、释放订单锁等副作用说明,明确各副作用失败不阻断主流程的容错语义", "methods": [ "order.recheckOrder.confirmIntercept" ], "notes": [ "description 补充:拦截成功后会释放储位分配(cancelAllocateStorage)与订单锁(lock_status=none)", "description 补充:储位释放、锁释放、日志写入失败均不影响主流程(try/catch 容错)", "仅文档变更,不修改业务代码" ], "module": "order" }, { "version": "2026.08.12-interceptScan", "date": "2026-08-12", "type": "added", "summary": "order.recheckOrder.interceptScan 新增拦截扫描接口:通过运单号查找运单,标记退回+拦截(is_back='Y', is_intercept='Y');运单记录不存在时自动创建补充;处理关联售后工单(写入「库内拦截成功」并完结);订单级拦截覆盖所有面单含子面单(与 confirmIntercept 一致)", "methods": [ "order.recheckOrder.interceptScan" ], "notes": [ "入参:waybill_code(string, required),运单号", "运单记录不存在时自动创建(INSERT wms_order_express),而非抛 404,确保缺失快递被补充", "同时设置 is_back='Y' 和 is_intercept='Y'", "查 wms_after_sale 表(未完结工单),命中则调用 handleWorkOrder 写入「库内拦截成功」步骤并置 status=completed;工单处理失败不阻断主流程", "订单拦截与 confirmIntercept 一致:只要有 order_id 即更新 wms_order_delivery.intercept_status = intercepted_at_warehouse,并释放储位分配与订单锁,写入 ORDER_INTERCEPT_CONFIRM 操作日志;不再区分 business_key,子面单同样会触发订单级拦截", "免权限/免日志/免鉴权(与 confirmIntercept 同级)", "代码变更:recheckOrder.js 构造函数 + interceptScan 方法(~180行);methods/system.json 新增 API 文档" ], "module": "order" }, { "version": "2026.08.10-storageTransaction-keyword", "date": "2026-08-10", "type": "updated", "summary": "storage.transaction.list 新增 keyword 快捷搜索参数,支持按 item_code(商品编码) 和 barcode(条码) 模糊匹配,内部解析为 stock_id 列表后以 IN 条件合并到查询中", "methods": [ "storage.transaction.list" ], "notes": [ "新增 keyword 参数(string, optional),搜索范围为 stock_warehouse.item_code + stock_barcodes.barcode", "keyword 解析复用已有 _resolveKeywordToStockIds 方法,与 stock.report.search 的 keyword 解析逻辑一致", "keyword 可与 where 条件叠加使用(交集),无匹配结果时直接返回空列表", "代码变更:stock_transaction.js list() 增加 keyword 参数并在 baseWhere 中注入 stock_id IN 条件;systemMethods/storage/transaction.js 透传 keyword" ], "module": "storage" }, { "version": "2026.08.10-stockTransaction-keyword-doc", "date": "2026-08-10", "type": "updated", "summary": "stock.transaction.list 补全 keyword 快捷搜索参数文档。代码层已支持 keyword(通过 queryList → _resolveKeywordToStockIds),本次仅补文档", "methods": [ "stock.transaction.list" ], "notes": [ "新增 where.keyword 参数文档(string, optional),搜索范围为 stock_warehouse.item_code/item_name/goods_code + stock_barcodes.barcode + SKU ID", "keyword 解析复用已有 _resolveKeywordToStockIds 方法,与 stock.report.search 逻辑一致", "keyword 与 stock_ids 互斥(keyword 优先),无匹配结果时返回空列表", "仅文档变更,不修改业务代码" ], "module": "stock" }, { "version": "2026.08.09-afterSale-doc", "date": "2026-08-09", "type": "updated", "summary": "补全 afterSale 组全部 11 个 method 的文档:workList/auditList/detail/create/transfer/handleWorkOrder/registerClaim/export/exportTaskProgress/workCount 的 params 与 response 补全 description,移除 create 中冗余 warehouse_id 参数(后端自动注入),明确各枚举值、关联表、业务语义。", "methods": [ "afterSale.workList", "afterSale.auditList", "afterSale.detail", "afterSale.create", "afterSale.transfer", "afterSale.handleWorkOrder", "afterSale.registerClaim", "afterSale.export", "afterSale.exportTaskProgress", "afterSale.workCount" ], "notes": [ "afterSale.create:移除 warehouse_id 参数(后端从 ctx.user.store_id 自动注入),补全所有 12 个参数的 description(含 type/sub_type 枚举值),response 新增 status 和 role_group 字段。", "afterSale.transfer:补全 id/role_group/remark 的 description,response 新增 role_group 字段。", "afterSale.handleWorkOrder:补全 action/status/attachment_ids 的 description,明确 action 示例和 status 枚举。", "afterSale.registerClaim:补全 10 个参数的 description,明确 claim_status/carrier_claim_status 枚举值(pending/reviewing/approved/paid/monthly/rejected)。", "afterSale.workList/auditList:补全 pagination/where/sort 与 response 的 description。", "afterSale.export/exportTaskProgress:补全参数和响应的 description,明确 task_id 用途。", "afterSale.workCount:已有完整 description,本次未修改。", "仅文档变更,不修改任何业务代码或接口语义。" ], "module": "afterSale" }, { "version": "2026.08.07-stockout-express", "date": "2026-08-07", "type": "changed", "summary": "wms_order_stockout 表新增 express_code / express_codes 字段;storage.stockout.confirm 改为读表字段回传,不再随机生成;新增 storage.stockout.updateExpress 接口。", "methods": [ "storage.stockout.confirm", "storage.stockout.updateExpress" ], "notes": [ "DB 迁移:20260807120000-add-express-code-to-wms-order-stockout.js 添加 express_code VARCHAR(50) 和 express_codes JSON 字段。", "Model:order_stockout.js 新增 express_code / express_codes 字段定义。", "storage.stockout.confirm:回传时不再随机生成 expressCode,改为读取表中 express_code / express_codes;express_code 为空则拒绝确认(400)。", "storage.stockout.updateExpress:新增接口,用于在确认前更新运单号,支持 express_code(单个)和 express_codes(列表)两个字段。", "qimenMethods/stockout.js confirm 同步调整,透传 expressCodes。" ], "module": "storage" }, { "version": "2026.08.07-stockout-confirm", "date": "2026-08-07", "type": "added", "summary": "新增 storage.stockout.confirm 直出确认接口:不改变内部库存,按出库单明细计划数量直接确认,状态推进到 COMPLETED。", "methods": [ "storage.stockout.confirm" ], "notes": [ "入参:id(出库单ID,必填)。", "逻辑:校验 canConfirm (CREATED/PENDING) → 事务内更新 order_status=COMPLETED、actual_qty=plan_qty。", "返回:id、stockout_order_code、order_status、logisticsName(固定OTHER)、expressCode(随机生成)。", "对应奇门 stockout.confirm 接口,由 qimenMethods/stockout.js confirm 方法调用。" ], "module": "storage" }, { "version": "2026.08.07-stockout-list-fix", "date": "2026-08-07", "type": "changed", "summary": "修复 storage.stockout.list / listItems 读错表:从 OrderDeliveryFactory/OrderItemsFactory 改为直接读取 OrderStockout/OrderStockoutItems 模型(wms_order_stockout 表)。", "methods": [ "storage.stockout.list", "storage.stockout.listItems" ], "notes": [ "list:数据源 OrderDeliveryFactory → OrderStockout;软删字段 delete_at → deleted_at;快速搜索字段适配 stockout_order_code/remark;排序字段适配 order_status/order_type/created_at/order_create_time。", "listItems:数据源 OrderDeliveryFactory+OrderItemsFactory → OrderStockout+OrderStockoutItems;参数 delivery_order_code → stockout_order_code(兼容旧参数名)。", "response 字段 items → list,与实际返回一致。" ], "module": "storage" }, { "version": "2026.08.06-inbox-bindCode", "date": "2026-08-06", "type": "added", "summary": "新增货主绑群码生成接口。校验 StoreWarehouse 合约有效性后生成12位随机码(大写字母+数字),缓存 key 为 chat:bind:{warehouseId}:{code},TTL 300秒。实现位于 systems/store.js → bindCode(),由 systemMethods/inbox.js → bindCode() 委托调用。", "methods": [ "inbox.bindCode" ], "notes": [ "调用链:/system → systemMethods/inbox.bindCode → systems/store.bindCode。", "前置校验:StoreWarehouse 合约 auth_status=2 AND warehouse_use_status=1,不满足则返回500。", "缓存策略:app.setCacheAsync('chat:bind:{warehouseId}:{code}', { store_id, initiator_subject_id, warehouse_id, group_type, sub_type }, 300)。", "绑定时消费:processor.tryBindGroup 匹配 '授权:CODE' 模式,读取缓存执行绑定,成功即清缓存。", "warehouseId:从 ctx.user.store_id 自动注入,前端无需传递。" ], "module": "inbox" }, { "version": "2026.08.05-inbox-group", "date": "2026-08-05", "type": "added", "summary": "站内信模块新增群管理接口:群列表拉取、群禁用/解禁、群信息修改(支持群类型/子类型/货主/快递接口/系统快递编码)、按群查询消息列表。仓库ID由服务端自动注入。express_interfaces输出为数组,systemExpressCode在express类型时必填校验。", "methods": [ "inbox.group.list", "inbox.group.disable", "inbox.group.update", "inbox.group.messages" ], "notes": [ "inbox.group.list:按群类型/关键词筛选,分页返回。express_interfaces 存储逗号分隔输出数组。", "inbox.group.disable:通过群主键ID禁用/解禁(isBlocked=1禁用/0启用)。", "inbox.group.update:支持修改groupType/subType/storeId/expressInterfaces/systemExpressCode。切换为express类型时systemExpressCode必填且需校验wms_express.code存在,expressInterfaces需校验wms_express_interface.id存在。非express类型忽略express相关字段。", "inbox.group.messages:按groupId拉取消息列表,支持direction/keyword筛选,仓库隔离,查询命中idx_warehouse_group_created索引。", "公共:所有方法warehouseId均从ctx.user.store_id自动注入,前端无需传递。" ], "module": "inbox" }, { "version": "2026.08.01-system-01", "date": "2026-08-01", "type": "added", "summary": "新增 apiApp 仓库 API 应用管理模块,支持当前仓库维度的 API 应用 CRUD、AppKey/Secret 自动生成与重新生成、IP 白名单、回调地址、限流等配置", "methods": [ "apiApp.list", "apiApp.detail", "apiApp.create", "apiApp.update", "apiApp.delete", "apiApp.regenerateSecret" ], "notes": [ "apiApp.list:分页查询当前仓库 API 应用列表,支持按 app_name(模糊)、is_enabled 筛选,Secret 自动脱敏(前8位+****)。", "apiApp.detail:按 ID 查询单个应用详情,需同时匹配 warehouse_id(自动注入 ctx.user.store_id),Secret 脱敏。", "apiApp.create:创建应用时自动生成 AppKey(AK{yyyyMMddHHmmss}{random8hex})和 AppSecret(64位hex)。默认 interface_type_id 取 WH_CHANNEL。仅创建时返回完整 Secret。", "apiApp.update:更新可编辑字段(app_name、self_ip_whitelist、callback_url、rate_limit、sign_method、is_enabled),不可变字段为 self_app_key 和 interface_type_id。", "apiApp.delete:软删除(is_enabled=0),不物理删除。", "apiApp.regenerateSecret:重新生成 64位hex AppSecret,旧 Secret 立即失效。仅此次返回完整 Secret。", "仓库隔离:所有操作按 ctx.user.store_id → warehouse_id 自动过滤。", "Secret 安全策略:list/detail/update 返回脱敏值,仅 create/regenerateSecret 返回完整 Secret。" ], "module": "apiApp" }, { "version": "2026.07.31-system-02", "date": "2026-07-31", "type": "added", "summary": "新增 storage.inventory.export 库存导出与 storage.inventory.exportTaskProgress 导出进度查询,入参复用 list 的 where/sort/group_by_batch 语义,支持两种导出模式(聚合汇总 / 逐条明细),库位信息一并导出", "methods": [ "storage.inventory.export", "storage.inventory.exportTaskProgress" ], "notes": [ "storage.inventory.export:异步提交导出任务,返回 task_id 与受理信息,后端异步生成 Excel 并上传。入参 where/sort/group_by_batch 与 storage.inventory.list 完全一致,无需额外学习成本。", "group_by_batch=false(默认):按 stock_id + space_id(库位)聚合导出库存汇总,含商品编码/名称/规格/单位/货主/库位编码/名称/总库存/锁定/可用/批次数/最近入库时间。", "group_by_batch=true:按 storage_id 逐条导出库存明细,含库存记录ID/商品信息/库位信息/批次号/库存类型/数量/生产日期/过期日期/入库时间/入库单号/供应商批次号。", "新增 storage.inventory.exportTaskProgress:按 task_id/taskId 查询导出任务进度与状态(submitted/running/success/failed/not_found),status=success 时返回 download_url 供客户端下载。", "导出文件目录:exports/storage/inventory/{warehouseId}/,缓存 TTL 1800 秒。" ], "module": "storage.inventory" }, { "version": "2026.07.31-system-01", "date": "2026-07-31", "type": "added", "summary": "新增按波次批量快捷复核接口 batchQuickRecheckByWave,支持批量波次 IDs 的前置条件检查(储位、快递、同步、拦截),自动完成拣货并标记复核,支持部分失败", "methods": [ "order.recheckOrder.batchQuickRecheckByWave" ], "notes": [ "新增 order.recheckOrder.batchQuickRecheckByWave 方法,复用 batchQuickRecheck 的 _completePickForOrder / _markRecheckForOrder / _tryCompleteWaveInTransaction 等内部事务方法", "入参 wave_ids 支持数组或逗号分隔字符串,兼容 waveIds(驼峰)、wave_id(单值)", "按波次维度批量查询订单后逐波次、逐订单执行前置校验与复核,每个订单独立事务,部分失败不影响其他订单", "响应包含 success/failed 列表及计数,failed 项含 order_id、wave_id、delivery_order_code、reason 说明;波次下无订单时仅返回 wave_id + reason" ], "module": "order.recheckOrder" }, { "version": "2026.07.29-system-01", "date": "2026-07-29", "type": "added", "summary": "补全 waybill.warehouse group API 文档参数定义:完善 list/detail/export 的 params 与 response,新增 exportTaskProgress 异步进度查询接口", "methods": [ "waybill.warehouse.list", "waybill.warehouse.detail", "waybill.warehouse.export", "waybill.warehouse.exportTaskProgress" ], "notes": [ "waybill.warehouse.list:params 含 pagination/where/sort 完整字段定义,where 支持 15 个筛选维度(运单号、主单号、订单ID、订单号、物流编码、物流接口ID、平台编码、状态、退回/拦截/星河签收、包材ID、已称重、关键词、创建时间范围),sort 白名单 create_at/weighing_weight/id。response 含 list(28 个字段)+ pagination。", "waybill.warehouse.detail:修正 id 参数为可选(required: false),与 waybillCode 二选一,waybillCode 优先。response 含 id/waybill_code/main_waybill_code/waybill_type/business_key/sibling_waybills/order/logistics/status_info/weight/package/print_records/print_count 等完整详情。", "waybill.warehouse.export:response 补充 progress/message/update_time 字段,完整覆盖异步任务返回信息。", "新增 waybill.warehouse.exportTaskProgress:按 task_id/taskId 查询导出进度,response 含 task_id/status/progress/current_count/total_count/message/result/error/download_url/update_time。", "所有接口 isNeedAuth: false, isNeedLogin: true,仓库隔离通过 ctx.user.store_id 自动注入。" ], "module": "waybill.warehouse" }, { "version": "2026.07.28-system-01", "date": "2026-07-28", "type": "added", "summary": "新增 order.pendingOrder.batchMarkPrinted:批量设置订单为已打印状态,将 print_status 更新为 'fin'", "methods": [ "order.pendingOrder.batchMarkPrinted" ], "notes": [ "同步批量更新接口,传入订单ID数组,直接将符合条件的订单 print_status 设为 'fin'。", "双表查询:先查 current 表(wms_order_delivery_{warehouseId}),未命中的 ID 再兜底查 dispatch 表(wms_order_delivery_{warehouseId}_dispatch)。", "dispatch 表查询失败仅记录 warn 日志,不影响 current 表已更新的结果。", "仅允许 step 在 [1,2,3] 且 status 不为 'cancel' 的订单操作,已打印(print_status='fin')的订单会被静默跳过。", "仓库上下文强制从 ctx.user.store_id 获取,禁止传入外部仓库ID。", "入参支持 order_ids / orderIds / ids 三种别名,优先级 order_ids > orderIds > ids。", "返回 updated_count 表示实际更新条数(current + dispatch 合计),ids 原样回传请求的订单ID列表。", "写入操作日志 operation_code: ORDER_BATCH_MARK_PRINTED。" ], "module": "order.pendingOrder" }, { "version": "2026.07.27-system-03", "date": "2026-07-27", "type": "changed", "summary": "storage.receiving 导出接口拆分:export 改为按仓库维度,新增 storeExport 按货主维度导出", "methods": [ "storage.receiving.export", "storage.receiving.exportTaskProgress", "storage.receiving.storeExport", "storage.receiving.storeExportTaskProgress" ], "notes": [ "export 改为仓库维度:过滤条件从 store_id(平台激活货主)改为 warehouse_id(ctx.user.store_id),与 getReceivingList 保持一致。", "exportTaskProgress 同步更新为仓库维度进度查询,任务 ID 前缀 receiving_export_。", "新增 storeExport:货主维度导出,通过平台激活上下文获取 store_id,过滤逻辑与 getStoreReceivingList 一致。", "新增 storeExportTaskProgress:货主维度进度查询,复用 exportTaskProgress 的缓存逻辑,任务 ID 前缀 receiving_store_export_。", "导出格式:双 Sheet Excel(Sheet1=收货单列表 21 列,Sheet2=收货单明细 17 列),通过 ExcelJS stream + uploadService 上传 COS。", "仓库导出上传路径 exports/receiving/{warehouseId}/,货主导出上传路径 exports/receiving/store/{storeId}/。", "修复 exportReceivingList 中 where 条件二次解析问题:增加 ctx.whereParsed 复用(与 getStoreReceivingList 一致),避免 prepareWhereContext 已解析后再重复 parseWhereConditions 导致边界条件丢失。", "命名对齐 entry 侧:storeExport / storeExportTaskProgress 方法名、任务 ID 前缀、上传路径均与 storage.entry.storeExport 模式一致。" ], "module": "storage.receiving" }, { "version": "2026.07.27-system-02", "date": "2026-07-27", "type": "added", "summary": "新增 order.pendingOrder.allocateSubOrderNumber:待处理订单分配子单号(异步任务),business_key 从 2 开始递增,跳过已分配运单号;新增 allocateSubOrderNumberProgress 按 task_id/business_key 查询进度", "methods": [ "order.pendingOrder.allocateSubOrderNumber", "order.pendingOrder.allocateSubOrderNumberProgress" ], "notes": [ "新增 allocateSubOrderNumber:入参 order_id + sub_order_count,按 business_key 2..(2+count-1) 全量传入 createWaybillCodePipeline。", "并发安全:全量传入 pipeline,由其内部事务 + UNIQUE(order_id,business_key,status,warehouse_id) 索引保证并发去重。", "pipeline 内部 createWaybillCode 事务:status=1 已分配→跳过;status=0 占位中→复用;无记录→INSERT status=0 占位。", "异步任务模式:请求立即返回 task_id(sub_ 前缀),后台 setImmediate 执行,进度通过 Redis 缓存追踪。", "新增 allocateSubOrderNumberProgress:支持 task_id 查整体进度,business_key 可选参数过滤单个业务ID的详情。", "进度状态 submitted→running→success/partial/failed,progress 对应 5/50/80/100。", "result.details 数组记录每个 business_key 的 status(skipped/allocated/failed/pending)与 waybill_code。", "buildSubOrderDetails 回查最终状态:status=1+waybill→allocated,status=0→failed,无记录→failed。" ], "module": "order.pendingOrder" }, { "version": "2026.07.27-system-01", "date": "2026-07-27", "type": "added", "summary": "新增 order.packing 打包任务模块:list/get 查询 + setEndTime 设置结束时间,含视频 CDN URL 拼接与状态回写", "methods": [ "order.packing.list", "order.packing.get", "order.packing.setEndTime", "order.packing.forceRecord" ], "notes": [ "新增 order.packing.list:按仓库维度查询打包任务列表,支持分页/筛选/排序,关联工作台、视频和运单信息。", "新增 order.packing.get:按 id + warehouse_id 查询单条打包任务详情。", "新增 order.packing.setEndTime:设置打包任务结束时间,入参 id + end_time;若任务状态不是已完成(2)则同步更新为已完成。", "新增 order.packing.forceRecord:强制重新录制打包任务视频,入参 id;校验录制电脑在线后重置视频状态并推送打印服务。", "前端默认值逻辑:若任务已有 end_time 则打开时默认为当前时间,否则默认为 start_time + 5分钟。", "视频 URL 自动拼接 CDN 域名前缀:http://w{warehouseId}-c{recordingComputerId}.o.gztbyc.com{videoPath};录制电脑从 wms_print_computer 按 is_recording=true 获取。", "视频响应新增 status 字段(created/recording/completed/failed),与数据库 ENUM 保持一致。", "pack_task_video Model 的 status 字段从 TINYINT 改为 STRING(20) 以匹配 DB ENUM 迁移。", "forceRecord 通过打印服务 /record/force 推送录制任务,传入 pack_task_id、warehouse_id、computer_id、camera_ids。" ], "module": "order.packing" }, { "version": "2026.07.10-system-01", "date": "2026-07-10", "type": "added", "summary": "新增 storage.report.searchStore 货主侧库存报表,以 store_id 为主维度查询库存流水", "methods": [ "storage.report.searchStore", "storage.report.exportStore" ], "notes": [ "新增 searchStore 方法:与 search 共享核心逻辑,通过 searchMode='store' 切换主维度从 warehouse_id → store_id。", "新增 exportStore 方法:与 export 共享核心逻辑,支持货主侧导出 Excel(含汇总 + 变更记录两个 sheet)。", "systems 层 search/export 方法新增 searchMode 参数(默认 'warehouse'),不影响现有 warehouse 侧行为。", "货主侧使用 ctx.user.store_id 作为主维度 store_id,辅助维度支持 warehouse_ids 过滤特定仓库。", "systemMethods 层 searchStore 从 where.warehouse_ids 取值传给 search 的 storeIds(承载 warehouse 过滤)。", "输出新增 warehouse_id / warehouse_name 字段,货主侧可区分不同仓库的库存。search 方法也同步输出这两个字段(向后兼容)。", "修复 getStockDetails 的 warehouseId 判断:从 != null 改为 !== undefined,使显式传 null 可跳过 warehouse 过滤。", "修复 loadReportReferenceMaps 未传递 warehouseId 给 getStockDetails 的问题。" ], "module": "storage.report" }, { "version": "2026.07.09-system-01", "date": "2026-07-09", "type": "updated", "summary": "签约 sign 方法改造:统一当前主体→store_id,解除角色校验,仓库可签仓库", "methods": [ "storeWarehouse.store.sign", "storeWarehouse.warehouse.sign" ], "notes": [ "resolvePairIds:统一当前主体始终在 store_id(货主方/消费方),对方在 warehouse_id(仓库方/提供方)。不再根据 isWarehouse 分支。", "getCounterparty:移除 expectedRole 角色校验(仓库不再只能签货主,可签仓库)。", "findScopedRelation:改为 OR 查询 store_id/warehouse_id 两边,兼容新旧签约数据。", "sign preview:counterparty.role 改为根据对方 project 真实返回(warehouse/store),不再硬编码反推。", "签仓库:仓库发起签约时对方 ID 传 counterparty_id,系统自动将当前仓库放 store_id。" ], "module": "storeWarehouse" }, { "version": "2026.07.08-system-01", "date": "2026-07-08", "type": "updated", "summary": "storeWarehouse.store.list 与 storeWarehouse.warehouse.list 拆分实现,不再共用;仓库侧支持查询外部合作仓库", "methods": [ "storeWarehouse.store.list", "storeWarehouse.warehouse.list" ], "notes": [ "拆分:store.list 调用 listForStore,warehouse.list 调用 listForWarehouse,不再共用同一个 list 方法。", "新规则:两个方法均按 store_id = 当前主体ID 过滤(主体在 store_id 为货主方/消费方,对方在 warehouse_id 为仓库方/提供方)。", "warehouse.list 新增支持查询外部合作仓库:当对方主体的 project='warehouse' 时为仓库-仓库合作,counterparty_role='warehouse'。", "响应新增 counterparty_role 字段(store/warehouse),标识对方主体的真实角色。", "warehouse.list 响应 use_status 改为 store_use_status(仓库在 store_id 方时,己方启用状态应为 store_use_status)。", "旧 list 方法保留标记为 @deprecated,保持向后兼容。", "新增 buildListWhereByStoreId 统一按 store_id 维度构建查询条件。" ], "module": "storeWarehouse" }, { "version": "2026.07.06-system-01", "date": "2026-07-06", "type": "updated", "summary": "order.wave.batchList:响应新增 pick_assignment_status(拣货分配状态),按订单 pick_status 聚合判定", "methods": [ "order.wave.batchList" ], "notes": [ "响应 list 每项新增字段 pick_assignment_status (string):拣货分配状态,按波次下订单的 pick_status 聚合判定。", "取值语义与 resolveAssignmentStatus 一致,自定义标签:未拣货(全 none)、部分拣货(混合且无 error)、已拣货(全 fin)、拣货异常(含 error)。", "SQL 子查询新增 pick_none_count / pick_fin_count / pick_error_count 聚合列。" ], "module": "order.wave" }, { "version": "2026.07.05-system-01", "date": "2026-07-05", "type": "added", "summary": "新增 pick.wavePickComplete:传入 wave_id 一键完成整个波次拣货,内部复用 query 去重与任务创建逻辑后自动调用 wavePickTaskComplete(mode=1)", "methods": [ "pick.wavePickComplete" ], "notes": [ "新增方法:pick.wavePickComplete,入参 wave_id(number,必填)。", "内部流程:按 wave_id 查波次 → 活动任务去重(同用户复用 / 他人409冲突)→ 完成任务去重 → 无任务则创建(source=2 后台抓取)→ 调用 pick.wavePickTaskComplete mode=1 全部确认。", "创建任务 remark 格式:pick.wavePickComplete wave_id={waveId},用于与 pick.query 区分。", "响应:task_id、status(completed / already_completed)、tip、confirmed_order_ids、is_completed、progress。", "错误码:400(参数/波次无订单)、401(缺少操作人)、404(波次不存在)、409(他人活动任务冲突)、500(创建/完成失败)。" ], "module": "pick" }, { "version": "2026.07.03-system-02", "date": "2026-07-03", "type": "added", "summary": "新增 order.pendingOrder.updateRemark:批量修改待处理订单备注(remark),不受 post_status 限制", "methods": [ "order.pendingOrder.updateRemark" ], "notes": [ "新增方法:order.pendingOrder.updateRemark,用于批量修改待处理订单的备注(remark)字段。", "入参:ids(number[],必填,正整数数组,不能为空)、remark(string,必填,最大500字符)。", "特性:不受 post_status 限制,可对所有状态的订单生效;纯批量不支持单ID。", "更新成功后写入操作日志。", "响应:updated_count(number,实际更新行数)、ids(number[],原样返回请求的ID数组)。", "错误码:400(ids 不能为空 / ids 仅支持正整数数组 / remark 不能为空)。" ], "module": "order.pendingOrder" }, { "version": "2026.07.03-system-01", "date": "2026-07-03", "type": "updated", "summary": "将 quick.waybill.toOrder 迁移为 index.toOrder 并移入基础模块,新增 waves 返回字段", "methods": [ "quick.waybill.toOrder", "index.toOrder" ], "notes": [ "移除快捷操作(quick)模块分组,原 quick.waybill.toOrder 方法从 methods/system.json 删除。", "在基础模块(index)新增 index.toOrder 方法:入参仍为 waybill_code,响应从单一 order_id 扩展为 order_id + waves 结构。", "waves 为数组,每项含 wave_id(波次ID)、wave_no(波次号)、order_ids(波次下所有订单ID列表),无波次时为空数组。", "查询路径:运单号 → wms_order_express(status=1)→ order_id + warehouse_id → 遍历 current/history/dispatch 表获取波次信息 → 再遍历多表获取同波次所有订单ID。" ] }, { "date": "2026-06-24", "type": "addition", "summary": "新增批量绑定入库单明细与收货单明细接口,支持明细级数量分配与部分成功", "version": "2026-06-24-add-bind-receiving-details", "methods": [ "storage.entry.bindReceivingDetails" ], "notes": [] }, { "date": "2026-06-24", "type": "deprecation", "summary": "废弃手动匹配入库单收货单接口,由 storage.entry.bindReceivingDetails 替代", "version": "2026-06-24-deprecate-manual-match-entry-order", "methods": [ "storage.receiving.manualMatchEntryOrder" ], "notes": [] }, { "version": "2026.06.16-system-03", "date": "2026-06-16", "summary": "order.wave.waveStrategyFallbackOrderList 响应新增 items_weight(总重量g)和 weight_type(重量类型)字段", "methods": [ "order.wave.waveStrategyFallbackOrderList" ], "notes": [ "响应 list 每项新增字段 items_weight (number|null):订单总重量(g),来自 wms_order.items_weight,为 null 时返回 null。", "响应 list 每项新增字段 weight_type (string):重量类型中文标签,来自 wms_order.weight_type 经 formatWeightTypeLabel 转换;取值:常规/轻货/重货/冷链(对应 DB 值 0/1/2/3)。" ], "type": "updated", "module": "order.wave" }, { "version": "2026.06.16-system-04", "date": "2026-06-16", "summary": "order.wave.singleOrderFetchList 响应新增 items_weight(总重量g)字段", "methods": [ "order.wave.singleOrderFetchList" ], "notes": [ "响应 list 每项新增字段 items_weight (number|null):订单总重量(g),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", "为 null 时返回 null。" ], "type": "updated", "module": "order.wave" }, { "version": "2026.05.20-system-03", "date": "2026-05-20", "summary": "新增 storeWarehouse.store.queryPrintQuantityLogs:按 store_id 分页查询面单余额变更日志", "methods": [ "storeWarehouse.store.queryPrintQuantityLogs" ], "notes": [ "新增方法:storeWarehouse.store.queryPrintQuantityLogs,用于按货主(store_id)分页查询面单余额变更日志。", "入参:store_id(必填)、page(可选)、page_size / pageSize(可选,兼容别名)。", "仅同步 methods/system.json 与本变更记录,不修改业务代码或测试。", "返回:使用默认分页格式,响应在 `data` 下包含 `list`(变更日志数组)和 `pagination` 对象,`pagination` 字段:`page`、`pageSize`、`total`、`totalPages`、`hasPrevious`、`hasNext`。" ], "type": "added", "module": "storeWarehouse" }, { "version": "2026.05.13-system-01", "date": "2026-05-13", "summary": "完善 print.send 的 API 文档与返回说明", "methods": [ "print.send" ], "notes": [ "补充请求参数说明:computerId、printer、template、data、type 标为必填,count、timestamp 保持可选。", "补充 template 的子字段说明:page_width、page_height、template_content。", "补充响应结构:flag、code、message、printId;其中成功时 code=200。", "补充错误码说明:1001 对应不支持的打印类型,504 对应打印任务发送失败(包含打印机不存在、脱机、通讯失败等场景)。" ], "type": "updated" }, { "version": "2026.05.08-system-06", "date": "2026-05-08", "summary": "新增取消拣货任务接口:order.wave.wavePickTaskCancel", "methods": [ "order.wave.wavePickTaskCancel" ], "notes": [ "接口功能:取消拣货任务,同时释放关联波次(物理删除波次记录,订单回池)、解绑拣货车、写操作日志。", "限制:仅允许在任务状态为 0(待开始)、1(拣货中)、2(待复核)时取消;状态为 3(已完成)或 9(已取消)时禁止取消,返回 400。", "事务内操作:将任务状态更新为 9(已取消)、删除关联波次、清空订单 wave_id(回池)、解绑拣货车、写入 action_log 与 order_pick_trace;若有任一步骤失败则回滚并返回 500。" ], "type": "added" }, { "version": "2026.07.01-system-01", "date": "2026-07-01", "summary": "storage.directInbound.addItem 参数名修正:entry_order_code → entry_order_id,类型 string → number", "methods": [ "storage.directInbound.addItem" ], "notes": [ "文档 params 中 entry_order_code(string)改为 entry_order_id(number),与代码 app/service/systems/inbound_direct_log.js 第 544 行实际校验保持一致", "同步修正 app/service/systemMethods/storage/direct_inbound.js JSDoc:@param {string} data.entry_order_code → @param {number} data.entry_order_id" ], "type": "fixed", "module": "storage.directInbound" }, { "version": "2026.07.01-system-02", "date": "2026-07-01", "summary": "新增 storage.entry.queryEntryLogs 接口文档定义", "methods": [ "storage.entry.queryEntryLogs" ], "notes": [ "代码 method 层(systemMethods/storage/entry.js L284)和 systems 层(systems/operation_log.js L318)均已实现,补充文档定义", "参数:id(number, required)、page(number, optional, 默认1)、pageSize(number, optional, 默认20)" ], "type": "added", "module": "storage.entry" }, { "version": "2026.06.18-system-01", "date": "2026-06-18", "summary": "order.pendingOrder.downloadCreateTemplate:模板列顺序调整,店铺名称(shop_nick)从末尾移至第2列B列,紧接*订单号之后", "methods": [ "order.pendingOrder.downloadCreateTemplate" ], "notes": [ "调整 Excel 导入模板列顺序:店铺名称(shop_nick)从原第25列(Y列/末尾)移动至第2列(B列),紧跟在*订单号(delivery_order_code)之后。", "同步更新 description 中的列顺序描述,明确 25 列(A-Y)的完整排列。", "响应结构中移除冗余的 shop_nick 字段(模板列不属于 API 响应字段)。" ], "type": "updated", "module": "order.pendingOrder" }, { "version": "2026.05.17-system-09", "date": "2026-05-17", "summary": "为 storage.receiving.deleteDetail 文档补充约束:收货单已完成/已取消时禁止删除明细", "methods": [ "storage.receiving.deleteDetail" ], "notes": [ "在 storage.receiving.deleteDetail 的 description 中补充:若关联收货单状态为 completed(已完成)或 cancelled(已取消),接口会返回删除失败(400),不允许删除明细。", "在 errors 中补充或合并 400 描述以明确禁止删除已完成/已取消的收货单明细。" ], "type": "updated", "module": "storage" }, { "version": "2026.05.17-system-08", "date": "2026-05-17", "summary": "完善 storage.receiving.deleteDetail 文档:补充入参/返回/错误说明,明确用户上下文来源及删除约束", "methods": [ "storage.receiving.deleteDetail" ], "notes": [ "补充 storage.receiving.deleteDetail 的参数说明:detail_id(来自请求体,必填);说明 creator_id 与 warehouse_id 来源于当前登录用户(ctx.user.employees_id / ctx.user.store_id)。", "补充返回结构:成功时返回 code/message/data,data 包含 details(删除后剩余明细)和 selectId(建议选中ID);product_snapshot 若存在将被解析为对象或 null。", "补充常见错误码:404(明细不存在或无权访问),400(收货单状态/已入库/删除失败),500(服务器异常)。", "仅文档更新,不修改任何业务实现。" ], "type": "updated", "module": "storage" }, { "version": "2026.05.17-system-05", "date": "2026-05-17", "summary": "移除 storage.receiving.addItem(方法已下线/实现不存在)", "methods": [ "storage.receiving.addItem" ], "notes": [ "仅同步文档:从 methods/system.json 中移除 storage.receiving.addItem,未修改任何业务代码或实现。", "该方法已下线或实现不存在;请以当前 methods/system.json 的 SSOT 为准。" ], "type": "removed" }, { "version": "2026.05.17-system-04", "date": "2026-05-17", "summary": "新增 stock.warehouse.import:仓库商品批量 JSON 导入(数组导入),SKU 为空创建/非空更新,支持 goods_code/货物编码 导入,更新写操作日志", "methods": [ "stock.warehouse.import" ], "notes": [ "支持直接传入商品数组 JSON(主方式为数组,兼容 rows/items/list/data 包装)。", "每项仅需传商品相关字段;SKU 为空时创建新商品,SKU 非空时为更新操作。", "更新操作会写入操作日志以便审计。", "支持导入 goods_code(货物编码)字段别名。", "仅同步文档,不修改业务代码或实现。" ], "type": "added" }, { "version": "2026.05.17-system-03", "date": "2026-05-17", "summary": "完善 stock.warehouse.handleBatchChange 文档:补充入参/出参/错误示例", "methods": [ "stock.warehouse.handleBatchChange" ], "notes": [ "补充方法入参说明:ids/method/value 的字段类型、是否必填、来源与示例;完善响应结构示例与常见错误码说明。", "仅文档更新,不改业务实现或语义。" ], "type": "updated" }, { "version": "2026.05.17-system-02", "date": "2026-05-17", "summary": "stock.warehouse.export 由同步改为异步任务并新增进度查询 exportTaskProgress", "methods": [ "stock.warehouse.export", "stock.warehouse.exportTaskProgress" ], "notes": [ "stock.warehouse.export 改为异步提交导出任务:接口返回 task_id 与受理信息,后端异步生成导出文件。", "新增 stock.warehouse.exportTaskProgress:按 task_id 查询任务状态与进度;当 status=success 时返回 download_url 供客户端下载;未找到时 status=not_found。", "调用方式:先调用 stock.warehouse.export 获取 task_id,然后轮询 stock.warehouse.exportTaskProgress 直到 status=success 并获取 download_url。" ], "type": "updated" }, { "version": "2026.05.17-system-01", "date": "2026-05-17", "summary": "新增 stock.warehouse.export:仓库商品导出(支持 where/sort),返回文件下载信息", "methods": [ "stock.warehouse.export" ], "notes": [ "新增方法:stock.warehouse.export。复用 stock.warehouse.list 的 where/sort 过滤语义(支持 operator/value/type 标准 where 结构与历史简写)。", "响应返回导出结果(示例字段:file_key、url),表示生成的 Excel 已上传并可下载/查询。" ], "type": "added" }, { "version": "2026.05.16-system-01", "date": "2026-05-16", "summary": "同步 setting.expressInterface.create 文档入参:移除未使用的 express_platform_id,标注必填字段", "methods": [ "setting.expressInterface.create" ], "notes": [ "移除文档中 express_platform_id(服务端实现未使用);确认必填字段 name/express_code/platform_code;仓库由系统自动填充,禁止传入 warehouse_id/warehouseId。" ], "type": "updated" }, { "version": "2026.05.12-system-01", "date": "2026-05-12", "summary": "调整订单打印中间态返回结构为 waveGroups(波次 -> 平台 -> 订单)", "methods": [ "order.print.getWavePlatformPrintData" ], "notes": [ "主要变更:将方法的主返回结构改为 waveGroups,按波次分组,波次内按平台分组,平台内为订单列表(波次 -> 平台 -> 订单)。", "兼容性:保留旧字段 platform_groups 与 order_list 作为向后兼容字段,但文档主结构与推荐使用为 waveGroups。", "返回结构说明:summary(total_waves/total_orders/total_platforms)、wave_ids(通过过滤的波次ID数组)、waveGroups(数组,项含 wave_id、wave_no、order_count、platforms[...],platforms项含 platform、platform_name、order_count、orders[...])、ext(missing_wave_ids、filtered_wave_ids)。", "errors:保留 400 / 500 不变。" ], "type": "modified" }, { "version": "2026.05.11-system-05", "date": "2026-05-11", "summary": "order.wave.batchList:支持 express/print 分配状态筛选,入参改为英文枚举(express/print)", "methods": [ "order.wave.batchList" ], "notes": [ "修复 where.express_assignment_status 可按快递分配状态筛选。", "新增 where.print_assignment_status 筛选(按打印分配聚合判断)。", "express_assignment_status / print_assignment_status 要求使用英文枚举值:express=unassigned/partially_assigned/assigned,print=unprinted/partially_printed/printed;storage_assignment_status 继续兼容中文枚举(未分配/部分分配/已分配)。", "若传入非法枚举值,接口返回 400(参数校验失败),message 中会说明允许取值。" ], "type": "updated" }, { "version": "2026.05.11-system-04", "date": "2026-05-11", "summary": "调整 order.wave.waveStrategyFetchAdmin:由创建任务改为直接创建波次(不创建拣货任务)", "methods": [ "order.wave.waveStrategyFetchAdmin" ], "notes": [ "接口行为变更:按策略直接抓取命中订单并创建波次,不再创建拣货任务(不返回 task_id/task_no 等任务字段)。", "响应调整为建波结果:fetch_state(1=成功/2=失败)、wave_ids、wave_nos、created_wave_count、created_order_count、order_ids、(可选)wave_prefix、wave_prefix_source、tip/message。", "错误调整:策略校验失败返回 400(并可能返回 validation_errors),缺少仓库上下文返回 400,建波失败返回 500 并在 message 中说明。" ], "type": "updated" }, { "version": "2026.05.11-system-03", "date": "2026-05-11", "summary": "更新 pick.query:由查询拣货明细调整为按 keyword 获取/创建拣货任务", "methods": [ "pick.query" ], "notes": [ "入参由 waybill_code/full_display 调整为 keyword(支持运单号或波次号)。", "接口语义调整为任务化返回:命中活动任务则返回 existing 任务ID;无活动任务则创建并返回 created 任务ID。", "新增任务归属冲突错误:当活动任务创建人非当前用户时返回冲突提示,并附带创建人及任务ID信息。" ], "type": "updated" }, { "version": "2026.05.11-system-02", "date": "2026-05-11", "summary": "新增 pick.wavePickTaskCurrent:PDA 无参查询当前进行中拣货任务", "methods": [ "pick.wavePickTaskCurrent" ], "notes": [ "新增 PDA 专用无参接口 pick.wavePickTaskCurrent。", "按当前登录用户上下文(pick_user_id + warehouse_id)查询状态在 0/1/2 的最新任务。", "命中返回 task_id,未命中返回 task_id=null。" ], "type": "added" }, { "version": "2026.05.10-system-04", "date": "2026-05-10", "summary": "pick.wavePickTaskDetail 新增按任务类型区分的 picking_view 形态输出", "methods": [ "pick.wavePickTaskDetail" ], "notes": [ "新增响应字段:picking_view(object),按 task.pick_mode 区分 5 种形态输出。", "picking_view 字段说明:mode_code, mode_name, require_box_allocations, group_by, sort_by, items[](每项含 space_id、space_name、location_space、item_code、item_name、stock_id、total_qty、box_allocations[])。", "当 pick_mode=1/3/4 时 require_box_allocations=true;当 pick_mode=2/5 时 require_box_allocations=false。" ], "type": "updated" }, { "version": "2026.05.10-system-02", "date": "2026-05-10", "summary": "order.wave.waveStrategyFetchPda/Admin 返回新增 fetch_state 三态与简短 tip", "methods": [ "order.wave.waveStrategyFetchPda", "order.wave.waveStrategyFetchAdmin" ], "notes": [ "新增返回字段:fetch_state(number)、tip(string)、can_enter_pick_flow(boolean)", "fetch_state 含义:1=创建成功(返回 task_id/task_no),2=普通失败(task_id=null),3=存在未完成任务(返回 existing task_id/task_no,前端可直接进入拣货流程)", "当 fetch_state=3 时,字段 can_enter_pick_flow=true,表示前端可直接进入拣货流程;tip 为简短提示文本" ], "type": "updated" }, { "version": "2026.05.10-system-03", "date": "2026-05-10", "summary": "裁剪 pick.wavePickTaskDetail 返回:移除 waves/orders,精简 task 并补充 boxes 拣货统计字段", "methods": [ "pick.wavePickTaskDetail" ], "notes": [ "移除响应中的 waves 与 orders 子表,接口仅返回精简的 task、boxes、picking_details 与 picking_summary。", "task 子字段裁剪为:task_id, task_no, status, pick_mode, start_at, finish_at, batch_no。", "boxes 补充并明确返回:ref_label(箱参考标签)、required_qty(箱内需拣总数)、picked_qty(已拣数量)。", "本次变更为文档层面的返回裁剪,前端应以新字段集合为准,旧字段可能不再返回。" ], "type": "updated" }, { "version": "2026.05.10-system-01", "date": "2026-05-10", "summary": "order.wave.waveStrategyList 新增 strategy_type 最小过滤(散单/团购)", "methods": [ "order.wave.waveStrategyList" ], "notes": [ "新增 strategy_type 过滤,仅 1/2", "支持顶层 strategy_type 和 where.strategy_type,顶层优先", "当前不引入其他 where 字段" ], "type": "updated" }, { "version": "2026.05.09-system-02", "date": "2026-05-09", "summary": "新增 pick.wavePickTaskDetail:按任务ID解析拣货任务详情", "methods": [ "pick.wavePickTaskDetail" ], "notes": [ "新增 pick.wavePickTaskDetail:传入 task_id 获取拣货任务完整信息,包含主表字段(task/pick_mode/status/wave_count/order_count/box_count 等)及三张子表数据(waves/orders/boxes)。", "安全限制:接口会校验当前登录用户(operator_id/employees_id)与任务的 pick_user_id 是否一致;不一致时直接返回 403,不返回任何拣货信息。", "鉴权配置:noNeedRight=true,noNeedAuth=true,isNeedLogin=true。" ], "type": "added" }, { "version": "2026.05.08-system-05", "date": "2026-05-08", "summary": "order.wave.batchList:新增 source 字段并支持 where.source 过滤,返回 list item 中新增 source 字段", "methods": [ "order.wave.batchList" ], "notes": [ "新增 where.source(可选,number)用于按来源过滤:0=普通波次(正常后台操作),1=管理后台策略任务,2=PDA策略任务;不传则不过滤。", "响应 list 每条记录新增字段 source(number),用于区分波次来源。", "仅更新文档,业务代码不在此变更范围。" ], "type": "updated" }, { "version": "2026.05.08-system-04", "date": "2026-05-08", "summary": "完善 order.wave.wavePickTaskList 文档:补充入参、分页与返回字段兼容说明", "methods": [ "order.wave.wavePickTaskList", "order.wave.wavePickTaskCancel" ], "notes": [ "入参补充:warehouse_id(必填)、status(支持单值或数组,建议传数组)、source、keyword、page_no、page_size;保留 pagination 对象以兼容旧客户端。", "兼容说明:接口同时支持历史 where 结构与顶层参数;当存在同名顶层参数时以顶层参数优先;pagination 支持 page/current 与 pageSize/size 别名。", "返回格式:响应包含 total 与 list;list 每项包含字段:task_id、task_no、status、source、pick_mode、wave_count、order_count、box_count、operator_id、operator_name、start_at、finish_at、created_at。为兼容旧客户端,响应同时保留旧字段:pick_user_id、pick_user_name、start_time、finish_time、create_time。", "入参 strategy_id 当前主表未存,接口会忽略该过滤,不建议使用。", "默认排序:create_time desc.", "文档变更:移除 order.wave.wavePickTaskCancel 的入参 operator_id 与 warehouse_id;入参改为仅支持 task_ids(数组,必填),不再兼容单个 task_id;操作人与仓库由请求上下文(例如当前登录用户上下文)自动获取;若上下文缺失接口将返回错误。响应补充批量结果字段:cancelled_count、task_ids、task_nos(若后端返回)。仅更新文档,未修改业务实现。" ], "type": "updated" }, { "version": "2026.05.08-system-03", "date": "2026-05-08", "summary": "升级按策略抓取接口为创建任务主流程:order.wave.waveStrategyFetchPda / order.wave.waveStrategyFetchAdmin", "methods": [ "order.wave.waveStrategyFetchPda", "order.wave.waveStrategyFetchAdmin" ], "notes": [ "将 PDA/Admin 场景的按策略抓取接口由受理壳方法升级为 '创建任务主流程':接口会执行参数校验并在同步响应中创建任务记录(state=created),返回 task_id、task_no、plan 与 plan_summary 供前端展示与后续查询。", "入参新增/扩展与创建流程相关字段:至少包含 cart_id(关联拣货车/作业车ID)、source(操作来源语义)并保留并透传 strategy_id 与 strategy_params(策略参数),以支持在创建阶段对策略进行局部覆盖或透传。", "成功返回示例字段:state=created、task_id、task_no、plan(对象)和 plan_summary(字符串);失败场景会返回 validation_errors(数组,每项含 field/message)或 message 描述创建失败原因。", "边界说明:当前为最小主流程(创建与计划预览),后续扫描/任务执行阶段(如实际抓取订单、写入 wave 等)将在后续版本中追加与完善。" ], "type": "updated" }, { "version": "2026.05.08-system-02", "date": "2026-05-08", "summary": "调整按策略抓取壳方法:order.wave.waveStrategyFetch 更名为 order.wave.waveStrategyFetchPda,并新增 order.wave.waveStrategyFetchAdmin", "methods": [ "order.wave.waveStrategyFetch", "order.wave.waveStrategyFetchPda", "order.wave.waveStrategyFetchAdmin" ], "notes": [ "waveStrategyFetchPda 仅用于 PDA 场景", "waveStrategyFetchAdmin 仅用于后台管理场景", "两者当前均为壳子受理方法,不执行真实抓取" ], "type": "updated" }, { "version": "2026.05.08-system-01", "date": "2026-05-08", "summary": "新增 order.wave.waveStrategyFetch:按策略提交抓取任务(壳子方法)", "methods": [ "order.wave.waveStrategyFetch" ], "notes": [ "当前方法为壳子方法:仅受理并返回任务受理信息,不执行真实抓取逻辑,后续补齐执行链路。" ], "type": "added" }, { "version": "2026.05.07-system-05", "date": "2026-05-07", "summary": "新增 order.wave.waveStrategyCreate 与 order.wave.waveStrategyUpdate:波次策略创建与更新接口(含参数校验与版本推进)", "methods": [ "order.wave.waveStrategyCreate", "order.wave.waveStrategyUpdate" ], "notes": [ "仓库 ID 与创建人(creator_name)由当前登录仓库/操作者上下文获取,接口不接受外部覆盖。", "入参 allowed_owners 与 allowed_expresses 会校验是否在系统可用范围内(基于仓库签约货主或系统快递列表),若存在非法值接口会直接报错(400)。", "max_same_structure 受仓库配置 min_group_order_fetch_quantity 限制:若传入值 >= min_group_order_fetch_quantity,则自动下调为 min_group_order_fetch_quantity - 1(最小值为 1)。", "新建/更新成功后会触发仓库的 wave_strategy_version 自增(+1)并失效相关仓库配置缓存,调用方可通过策略版本推进或缓存变化感知策略已生效。" ], "type": "added" }, { "version": "2026.05.07-system-06", "date": "2026-05-07", "summary": "收敛 order.wave.waveStrategyFallbackOrderList 返回字段,限定 where 白名单,补充 order.wave.singleFetchByIds 别名与返回语义", "methods": [ "order.wave.waveStrategyFallbackOrderList", "order.wave.singleFetchByIds" ], "notes": [ "收敛 order.wave.waveStrategyFallbackOrderList response.list 字段为 id, delivery_no, tracking_no, items_count, items_total, sys_logistics_name, store_name, province, sys_platform_name, item_snapshot;item_snapshot 格式示例:商品名称*数量|...。", "限制 order.wave.waveStrategyFallbackOrderList.where 白名单,禁止传入 warehouse_id / warehouseId;传入未列出字段或别名冲突将返回 400。", "补充 order.wave.singleFetchByIds:明确支持 ids / order_ids / orderIds 三个别名(优先顺序 ids -> order_ids -> orderIds)并说明返回字段 fetched_order_ids、excluded_existing_wave_order_ids、skipped_order_ids、not_found_order_ids 的语义与兼容性。" ], "type": "updated" }, { "version": "2026.05.07-system-04", "date": "2026-05-07", "summary": "更新 order.wave.waveStrategyFallbackOrderList,新增商品快照字段 item_snapshot", "methods": [ "order.wave.waveStrategyFallbackOrderList" ], "notes": [ "item_snapshot 返回格式为 商品名称1*数量|商品名称2*数量" ], "type": "updated" }, { "version": "2026.05.07-system-03", "date": "2026-05-07", "summary": "新增 order.wave.waveStrategyQuickScan 与进度查询接口", "methods": [ "order.wave.waveStrategyQuickScan", "order.wave.waveStrategyQuickScanTaskProgress" ], "notes": [ "同仓只允许一个扫描任务并使用缓存锁;扫描范围为当前表非待审核、未分配波次且订单策略版本与仓库当前版本不一致的订单;命中策略标记 wave_scan_result=1,否则=2" ], "type": "added" }, { "version": "2026.05.07-system-02", "date": "2026-05-07", "summary": "新增 order.wave.waveStrategyList:查询当前仓库波次策略列表", "methods": [ "order.wave.waveStrategyList" ], "notes": [ "从 wms_wave_strategy 拉取当前仓库的波次策略列表,分页返回" ], "type": "added" }, { "version": "2026.05.07-system-01", "date": "2026-05-07", "summary": "移除 order.wave.singleOrderFetchDetailList,新增 order.wave.waveStrategyFallbackOrderList(内置固定筛选条件)", "methods": [ "order.wave.singleOrderFetchDetailList", "order.wave.waveStrategyFallbackOrderList" ], "notes": [ "移除 order.wave.singleOrderFetchDetailList。", "新增 order.wave.waveStrategyFallbackOrderList。", "新接口基于订单通用查询口径,固定内置筛选条件:step != 0、wave_id = 0、wave_scan_result = 2。" ], "type": "updated" }, { "version": "2026.05.06-system-06", "date": "2026-05-06", "summary": "新增 order.wave.singleOrderFetchDetailList:订单级散单候选明细视图", "methods": [ "order.wave.singleOrderFetchDetailList" ], "notes": [ "新增 order.wave.singleOrderFetchDetailList:提供订单级的散单候选明细列表,返回按订单聚合的明细(非分组级)。", "返回订单级而非分组级;响应每项包含订单 id、group_count、item_detail_machine、item_detail_machine_snapshot、item_detail、item_snapshot、logistics_name、store_id、distinguish_express、create_at 与 status_summary 等关键字段。", "仍沿用 same_order_quantity 阈值来排除团购命中分组(仅保留 group_count < same_order_quantity 的候选项)。", "singleOrderFetchList 暂保留以兼容现有前端,前端可在切换到订单级视图后迁移到本接口。" ], "type": "added" }, { "version": "2026.05.06-system-05", "date": "2026-05-06", "summary": "storage.receiving.get 返回扩展:data.details[*] 新增 box_remainder、box_weight", "methods": [ "storage.receiving.get" ], "notes": [ "storage.receiving.get 的响应在 data.details[*] 中新增可选字段:box_remainder(箱内剩余数量/零散数量,number,默认 0)与 box_weight(实测箱重,number,默认 0)。", "兼容性:新增字段为可选,旧客户端无需修改;建议前端在需要展示箱内余量/箱重时使用这些字段。" ], "type": "updated" }, { "version": "2026.05.06-system-04", "date": "2026-05-06", "summary": "storage.receiving.getReceivingDetail 返回扩展:明细增加 box_remainder、box_weight;storage.receiving.completeReceiving 通知包含这两个字段", "methods": [ "storage.receiving.getReceivingDetail", "storage.receiving.completeReceiving" ], "notes": [ "为支持箱规统计与通知回传,getReceivingDetail 的明细项(receiving.details 或 data.details)在响应中新增可选字段:box_remainder(箱内剩余数量/零散数量,number)与 box_weight(实测箱重,number,单位同系统重量)。", "completeReceiving 在完成收货后会发送通知(或回调),通知 payload/metadata 中将包含每条明细的 box_remainder 与 box_weight 字段,供下游系统/前端展示或审计使用。", "兼容性:新增字段为可选,旧客户端在未使用这些字段时无需变更。" ], "type": "updated" }, { "version": "2026.05.06-system-03", "date": "2026-05-06", "summary": "storage.receiving.detailChange:新增入参/出参字段 box_remainder、box_weight", "methods": [ "storage.receiving.detailChange" ], "notes": [ "为支持箱规细化与回写,detailChange 新增可选入参 box_remainder(箱内余量/零散数量)和 box_weight(实测箱重,单位同系统重量),写入后会回写至明细并在响应 data 中返回对应字段。", "兼容性:新增字段为可选,不传入则不影响现有调用;建议前端在需要回写箱余与箱重时一并传入。" ], "type": "updated" }, { "version": "2026.05.06-system-02", "date": "2026-05-06", "summary": "新增 order.wave.singleFetchByIds:按订单ID抓取到一个散单波次", "methods": [ "order.wave.singleFetchByIds" ], "notes": [ "新增 order.wave.singleFetchByIds:按入参 ids(兼容 order_ids/orderIds)去重后筛选当前仓库内待处理且不在波次中的订单,若存在可抓取订单则创建单个散单波次并把这些订单写入该波次(不区分快递);成功后批量写入订单操作日志;若无可抓取订单返回 wave_id=0。", "接口行为严格对齐实现:过滤条件包含 step in [1,2,3]、status != 'cancel'、outbound_status != 'padding';已在波次的订单会被排除并返回 excluded_existing_wave_order_ids;响应包含 ids、wave_id、wave_no、fetched_order_ids、fetched_order_count、excluded_existing_wave_order_ids、skipped_order_ids、not_found_order_ids。" ], "type": "added" }, { "version": "2026.05.06-system-01", "date": "2026-05-06", "summary": "新增 order.wave.groupFetch 与 order.wave.singleFetch;order.wave.fetch 保留兼容别名;抓取进度补充上限字段", "methods": [ "order.wave.groupFetch", "order.wave.singleFetch", "order.wave.fetch", "order.wave.fetchTaskProgress" ], "notes": [ "新增 order.wave.groupFetch:抓取团购接口(异步任务提交),参数 structure_list 与原 fetch 一致。", "新增 order.wave.singleFetch:抓取散单接口(异步任务提交),在 structure_list 每项新增必填字段 max_fetch_quantity(最大抓取上限,订单数,正整数)。", "order.wave.fetch 保留为兼容别名(等同 groupFetch),避免误导客户端。", "groupFetch/singleFetch/fetch 的响应新增可选字段 fetch_mode;singleFetch 响应额外返回 max_fetch_quantity。", "order.wave.fetchTaskProgress 的响应增加单模式相关字段:fetch_mode、max_fetch_quantity、limit_reached、stop_reason,用于描述散单抓取的上限与停止原因。" ], "type": "updated" }, { "version": "2026.05.05-system-02", "date": "2026-05-05", "summary": "order.wave.batchList:新增 where.storage_assignment_status 的过滤语义说明", "methods": [ "order.wave.batchList" ], "notes": [ "新增 where 字段 `storage_assignment_status`:类型 string,可选值:`未分配`、`部分分配`、`已分配`;默认不传:不做分配状态限制。", "过滤语义:`已分配`:聚合后全部 fin;`部分分配`:不含 error,且既不是全 none,也不是全 fin;`未分配`:全 none 或包含 error(异常并入未分配筛选集合)。", "说明:返回字段 `storage_assignment_status` 的展示值保持不变;包含 error 时仍可能展示“分配异常”,但 where 的过滤语义把异常算到“未分配”集合,避免把过滤语义与展示值混淆。" ], "type": "updated" }, { "version": "2026.05.05-system-01", "date": "2026-05-05", "summary": "新增 order.wave.singleOrderFetchList:散单候选分组查询(排除团购命中分组)", "methods": [ "order.wave.singleOrderFetchList" ], "notes": [ "新增 order.wave.singleOrderFetchList:返回按机器结构分组的散单候选列表,接口会排除已达团购阈值(同组订单数量 >= same_order_quantity 或仓库配置 min_group_order_fetch_quantity)的分组,仅返回同组订单数量 < 阈值 的分组(散单候选)。", "与 order.wave.groupOrderFetchList 的关键差异:groupOrderFetchList 返回满足团购阈值(>=)的分组;singleOrderFetchList 返回未达阈值(<)的散单候选分组。", "影响范围:订单波次抓取相关前端/调度服务。兼容性:不影响或修改现有 order.wave.groupOrderFetchList,两个接口可并行使用。" ], "type": "added" }, { "version": "2026.05.04-system-04", "date": "2026-05-04", "summary": "完善商品编码唯一性校验接口文档,补充 item_id(排除自身)和 owner_id(货主ID)入参说明,新增 unique/isUnique 返回字段描述", "methods": [ "stock.warehouse.checkItemCodeUnique" ], "notes": [ "完善商品编码唯一性校验接口文档,补充 item_id(排除自身)和 owner_id(货主ID)入参说明,新增 unique/isUnique 返回字段描述" ], "type": "modified" }, { "version": "2026.05.04-system-02", "date": "2026-05-04", "summary": "修改 pick.query 入参:order_id -> waybill_code", "methods": [ "pick.query" ], "notes": [ "入参从 order_id 改为 waybill_code(快递号),通过快递号查找订单后再查波次拣货信息" ], "type": "breaking_change" }, { "version": "2026.05.04-system-01", "date": "2026-05-04", "summary": "新增 system method pick.query:按订单查询波次拣货信息", "methods": [ "pick.query" ], "notes": [ "按订单查询该订单所属波次的拣货信息,支持 full/full_display/is_full 控制是否完整显示;接口按当前登录用户仓库上下文过滤,防止跨仓越界。" ], "type": "added" }, { "version": "2026.05.03-system-09", "date": "2026-05-03", "summary": "新增按 request_id 查询分配状态/结果接口", "methods": [ "order.pendingOrder.allocateStorageProgress" ], "notes": [ "新增按 request_id 查询储位分配异步任务状态/结果接口,支持 status:submitted/running/success/failed/not_found;success 返回 result(底层分配结果),failed 返回 error(错误信息);兼容 requestId 参数名。" ], "type": "updated" }, { "version": "2026.05.03-system-07", "date": "2026-05-03", "summary": "新增抓取进度查询接口", "methods": [ "order.wave.fetch", "order.wave.fetchTaskProgress" ], "notes": [ "新增按 task_id 查询抓取任务进度的接口 order.wave.fetchTaskProgress,支持返回 status(submitted/running/success/failed/not_found)及进度相关字段:progress_percent、finished_structure_count、total_fetched_quantity、duration_ms、error、update_time 等;同时明确 order.wave.fetch 为异步任务提交接口,客户端可通过 task_id 调用 order.wave.fetchTaskProgress 查询进度和最终结果。" ], "type": "updated" }, { "version": "2026.05.03-system-05", "date": "2026-05-03", "summary": "补齐仓库设置模块 setting.warehouse 的 methods 文档", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.getFieldMeta", "setting.warehouse.saveSettings" ], "notes": [ "补齐仓库配置 methods API 文档" ], "type": "updated" }, { "version": "2026.05.03-system-04", "date": "2026-05-03", "summary": "order.wave:自动加团新增跳过规则并新增批量结束自动加团接口", "methods": [ "order.wave.batchAutoGrouping", "order.wave.batchFinishAutoGrouping" ], "notes": [ "开启自动加团新增“已打印/超最大波次容量”跳过规则并在响应中返回跳过明细;新增批量结束自动加团接口(将 wave_status=0 的波次批量置为 1)" ], "type": "updated" }, { "version": "2026.05.03-system-03", "date": "2026-05-03", "summary": "裁剪 order_list 以轻量化返回", "methods": [ "order.wave.batchList" ], "notes": [ "移除响应中的 order_list 字段,接口仅返回波次基础信息与状态汇总(order_count / storage_assignment_status / express_assignment_status / print_assignment_status)" ], "type": "updated" }, { "version": "2026.05.03-system-02", "date": "2026-05-03", "summary": "新增 order.wave.batchAutoGrouping:批量改为自动加团中", "methods": [ "order.wave.batchAutoGrouping" ], "notes": [ "新增批量改为自动加团中接口及返回字段" ], "type": "updated" }, { "version": "2026.04.22-system-02", "date": "2026-04-22", "summary": "新增 order.pendingOrder.syncOrderIds:待处理订单同步透传入口", "methods": [ "order.pendingOrder.syncOrderIds" ], "notes": [ "新增 order.pendingOrder.syncOrderIds:仅接收 order_ids 并转发到服务层,当前不做业务处理。", "接口保留登录态校验,入参仅接受订单 ID 相关字段,响应以服务层返回值为准。", "该方法用于预留同步链路,后续补齐业务逻辑时再扩展服务层实现。" ], "type": "updated" }, { "version": "2026.04.22-system-01", "date": "2026-04-22", "summary": "补全订单工作台各模块 detail 方法文档", "methods": [ "order.detail", "order.pendingOrder.detail", "order.reviewOrder.detail", "order.expectionOrder.detail", "order.outboundOrder.detail", "order.deliveryOrder.detail", "order.deliveryExpectionOrder.detail", "order.entrustOrder.detail", "order.archiveOrder.detail" ], "notes": [ "补全文档:detail 为订单工作台通用详情方法,入参支持 ids/id/order_id/orderId;可选 tableType/tablePosition/type/moduleName,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等。", "返回包含 order/detail(订单头)、orderItems/items(商品明细)、expresses(运单信息)、waybill_codes(去重运单号数组)。" ], "type": "updated" }, { "version": "2026.04.19-system-01", "date": "2026-04-19", "summary": "新增方法 setting.expressInterface.listByWarehousePlatformCode:按 warehouse_id + platform_code 查询全字段列表并支持缓存", "methods": [ "setting.expressInterface.listByWarehousePlatformCode" ], "notes": [ "新增 setting.expressInterface.listByWarehousePlatformCode:按 warehouse_id + platform_code 返回快递接口的全字段数组(不分页),每条记录包含 express 关联对象(id/code/name/platform 等)。", "支持缓存,缓存键由 warehouse_id + platform_code 组成;缓存命中将直接返回缓存结果以提升查询性能。", "在创建/更新/删除操作(setting.expressInterface.create/update/delete)后,会主动清理对应 warehouse_id + platform_code 的缓存以确保数据一致性。" ], "type": "added" }, { "version": "2026.04.17-system-08", "date": "2026-04-17", "summary": "新增快递编码管理模块批量软删除接口 setting.express.delete", "methods": [ "setting.express.delete" ], "notes": [ "新增批量软删除接口 setting.express.delete:接受 ids(数组、逗号字符串或单值),对属于当前仓库且未被删除的记录执行软删除(设置 deleted_at),并清理 express 列表缓存。", "当任一目标记录的 code 被 wms_express_interface.express_code 引用时,接口会拒绝删除并返回 409,错误信息中包含被引用的编码列表。", "响应包含 ids、deleted_ids、already_deleted_ids 与 status,已删除与未删除的 id 会明确分类。仅记录已实现行为。" ], "type": "added" }, { "version": "2026.04.17-system-05", "date": "2026-04-17", "summary": "新增文档分组:平台编码管理模块(收口 index.getPlatformList 与 setting.platform.*)", "methods": [ "index.getPlatformList", "setting.platform.list", "setting.platform.create", "setting.platform.update", "setting.platform.delete" ], "notes": [ "新增独立文档分组 '平台编码管理模块',将平台基础列表(index.getPlatformList)与平台设置管理接口(setting.platform.*)归并为单一分组以便维护;仅文档变更,不修改实现。", "文档中仅包含已实现的方法与字段,未新增或推断不存在的参数/返回字段。" ], "type": "added" }, { "version": "2026.04.17-system-04", "date": "2026-04-17", "summary": "新增独立平台设置模块 setting.platform(wms_platfrom_setting)及其 CRUD 接口:list/create/update/delete。", "methods": [ "setting.platform.list", "setting.platform.create", "setting.platform.update", "setting.platform.delete" ], "notes": [ "新增独立模块 setting.platform,映射数据表 wms_platfrom_setting;list 支持 where(id/code/name/platform_code/quickWhere)与 pagination(兼容 page/pageSize/page_size);create/update 要求 platform_code 必须存在于系统平台表(wms_platform),且禁止越权写入 warehouse_id;delete 需传入 id 并校验当前仓库范围。" ], "type": "added" }, { "version": "2026.04.15-system-07", "date": "2026-04-15", "summary": "将 docs/order-workbench-list-api.md 引用统一为 window 链接格式", "methods": [ "order.list", "order.reviewOrder.list", "order.pendingOrder.list", "order.outboundOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list" ], "notes": [ "将所有 methods/system.json 中指向 docs/order-workbench-list-api.md 的说明统一替换为 docs/order-workbench-list-api.md 格式,以便 HTML 渲染识别为 window 链接。", "仅修改 methods/system.json 的文档字段,不涉及任何业务代码或接口契约变化。" ], "type": "updated" }, { "version": "2026.04.15-system-06", "date": "2026-04-15", "summary": "订单工作台列表文档补全 raw 字段字典与中文语义说明", "methods": [ "order.list", "order.reviewOrder.list", "order.pendingOrder.list", "order.outboundOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list", "order.archiveOrder.list" ], "notes": [ "在 docs/order-workbench-list-api.md 中补充所有订单列表通用 raw 字段字典,明确每个字段的中文语义与 enum 取值。", "补充 express_numbers / waybill_codes 两个服务层派生字段说明,便于前端直接渲染多个快递号。", "methods/system.json 中所有订单 list 的 response.list 描述已指向该字段字典章节。" ], "type": "updated" }, { "version": "2026.04.15-system-05", "date": "2026-04-15", "summary": "基础模块新增快递/平台列表查询接口并设置为不鉴权,复用缓存 service", "methods": [ "index.getExpressList", "index.getPlatformList" ], "notes": [ "新增 index.getExpressList,归属基础模块(module=index),对应 app/service/systems/express.js 中的 getExpressList。", "index.getExpressList 设置为不鉴权,不需要 Authorization 头。", "新增 index.getPlatformList,归属基础模块(module=index),对应 app/service/systems/platform.js 中的 getPlatformList。", "index.getPlatformList 设置为不鉴权,不需要 Authorization 头。", "快递列表与平台列表都支持缓存优先,缓存未命中时回源数据库并写入缓存。", "平台列表支持缓存优先,缓存未命中时回源 wms_platform 并写入缓存。" ], "type": "added" }, { "version": "2026.04.15-system-02", "date": "2026-04-15", "summary": "签约策略字段元信息新增 default_express_code / default_platform_code list 选项", "methods": [ "storeWarehouse.store.getPolicyConfigFields" ], "notes": [ "getPolicyConfigFields 现在返回 default_express_code 与 default_platform_code 两个 list 字段,并从 wms_express / wms_platform 读取选项列表。", "默认值仍保留为 default_express_code=STO、default_platform_code=TB。" ], "type": "updated" }, { "version": "2026.04.15-system-03", "date": "2026-04-15", "summary": "签约策略字段移除 sku_visibility,receive_mode options 改为 value/label 结构", "methods": [ "storeWarehouse.store.savePolicyConfig", "storeWarehouse.store.getPolicyConfigFields" ], "notes": [ "策略字段定义不再包含 sku_visibility,历史值读取时仍会被归一化忽略。", "receive_mode 的 options 改为 [{ value, label }] 格式,便于前端直接渲染。" ], "type": "updated" }, { "version": "2026.04.15-system-04", "date": "2026-04-15", "summary": "按文件模块拆分 order 目录系统文档分组,覆盖订单工作台入口及各子模块方法", "methods": [ "order.list", "order.manualOutboundOrder", "order.badgeCount", "order.outboundOrder.manualOutboundOrder", "order.reviewOrder.list", "order.reviewOrder.reviewOrder", "order.pendingOrder.list", "order.pendingOrder.reverseReviewOrder", "order.pendingOrder.markPendingOutboundOrder", "order.pendingOrder.cancelOrder", "order.outboundOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list", "order.archiveOrder.list" ], "notes": [ "按 app/service/systemMethods/order 下的实际对外方法补全 methods/system.json 文档,只覆盖 system,不处理 qimen。", "order 文档已按 index / reviewOrder / pendingOrder / outboundOrder / expectionOrder / entrustOrder / deliveryOrder / deliveryExpectionOrder / archiveOrder 拆成多个模块分组。", "同步根据当前代码意图补充 params / response / errors,且不再把 index.js 已移除的兼容接口写回文档。" ], "type": "updated" }, { "version": "2026.04.15-system-01", "date": "2026-04-15", "summary": "货主主体配置默认补齐 default_express_code / default_platform_code", "methods": [ "store.createStore", "store.createWarehouse" ], "notes": [ "当 subject_config 未传或缺少字段时,自动补齐 default_express_code=STO、default_platform_code=TB,并保留现有的 max_notice_webhook_count 默认值。", "同步更新 methods/system.json 中 store.createStore 与 store.createWarehouse 的参数说明。" ], "type": "updated" }, { "version": "2026.04.14-system-01", "date": "2026-04-14", "summary": "库存列表新增货主名称字段 stock.store_name", "methods": [ "storage.inventory.list" ], "notes": [ "在 methods/system.json 的 storage.inventory.list response 中补充 stock.store_name:来源于签约表 store_remask,若无签约关系则为 null。", "只同步文档,不修改业务代码。" ], "type": "updated" }, { "version": "2026.04.13-system-01", "date": "2026-04-13", "summary": "补全 storage.receiving.detailChange 的入参/出参契约与错误码说明", "methods": [ "storage.receiving.detailChange" ], "notes": [ "在 methods/system.json 中补充 storage.receiving.detailChange 的 params/response/errors,明确 id 与 receiving_id 必填。", "说明 expiry_date 小于当前日期时返回 400 且 message 为 \"到期日期已过期,不能录入收货\"。", "说明当传入 system_product_id 时会回填条码、重量、箱规、商品名称与 product_snapshot;未传时 barcode/product_name 也可单独更新。", "同步补充文档:docs/storage-receiving-api.md 中新增 detailChange 段落。" ], "type": "updated" }, { "version": "2026.04.07-system-01", "date": "2026-04-07", "summary": "修正 warehouse.getAreaRacks 的鉴权/权限链路文档,明确该接口需要 登录并走权限校验。", "methods": [ "warehouse.getAreaRacks" ], "notes": [ "对齐当前 system 文档中的 isNeedAuth=true、isNeedLogin=true。", "用于补充该接口权限链路修正文档的历史上下文,不改变 methods/system.json 的 SSOT 角色。" ] }, { "version": "2026.04.07-system-02", "date": "2026-04-07", "summary": "补充签约配置相关接口文档,覆盖策略字段元信息查询与面单数量人工调整。", "methods": [ "storeWarehouse.store.getPolicyConfigFields", "storeWarehouse.store.adjustPrintQuantity" ], "notes": [ "getPolicyConfigFields 说明为获取签约策略可配置字段元信息列表。", "adjustPrintQuantity 说明为人工调整签约关系下的面单余额并记录变更日志,并 明确 id、change_quantity、reason 等关键入参。" ] }, { "version": "2026.04.07-system-03", "date": "2026-04-07", "summary": "对外命名从 qimenConfig 收口为 apiConfig,并在接口配置文档中强调 interface_type_id 校验。", "methods": [ "storeWarehouse.store.listApiConfig", "storeWarehouse.store.saveApiConfig", "storeWarehouse.store.deleteQimenConfig" ], "notes": [ "文档对外统一使用 apiConfig / api_config 命名,减少 qimenConfig 历史别名歧义。", "saveApiConfig 要求 interface_type_id 为必填且必须指向已存在的 wms_interface_type 记录。", "listApiConfig / deleteQimenConfig 同步补充 interface_type_id 字段说明。" ] }, { "version": "2026.04.07-system-04", "date": "2026-04-07", "summary": "补充 /api/docs 文档体验增强说明,新增查看变更记录与查看原文 JSON 的入口说明。", "methods": [ "/api/docs", "/api/docs/:docName", "/api/docs/:docName/raw", "/api/docs/:docName/changes" ], "notes": [ "sidecar 变更数组用于承载文档历史说明,不替代 methods/system.json 作为 SSOT。", "原文 JSON 入口继续用于直接查看当前生效文档。" ] }, { "version": "2026.04.07-system-05", "date": "2026-04-07", "summary": "修正 storeWarehouse.store.adjustPrintQuantity 的面单余额调整语义:由增减/累加改为覆盖设置目标余额。", "methods": [ "storeWarehouse.store.adjustPrintQuantity" ], "notes": [ "adjustPrintQuantity 当前兼容 print_quantity、target_quantity、change_quantity、adjust_quantity 作为目标面单余额输入,不再按增减量解释。", "变更日志中的 change_quantity 由 before/after 自动计算差值,以兼容历史审计与展示。" ] }, { "version": "2026.04.07-system-06", "date": "2026-04-07", "summary": "按接口类型分类限制必填字段,OPEN_API 创建时自动生成 self_app_key/self_app_secret", "methods": [ "storeWarehouse.store.saveApiConfig" ], "notes": [ "QM_WMS 类型须填写 qimen_app_key/qimen_customer_id/qimen_warehouse_code;OPEN_API 类型三个奇门字段非必填,创建时自动生成 self_app_key(WMS+32位HEX)和 self_app_secret(64位HEX),更新时保留已有密钥。" ], "type": "changed" }, { "version": "2026.04.07-system-07", "date": "2026-04-07", "summary": "新增接口类型列表查询接口,归属基础模块,无需权限", "methods": [ "index.listInterfaceTypes" ], "notes": [ "返回所有已启用的接口类型(wms_interface_type),包含 id、interface_code、interface_name、interface_category、description 字段。设置 isNeedAuth: false, isNeedLogin: true。" ], "type": "added" }, { "version": "2026.04.07-system-08", "date": "2026-04-07", "summary": "app_name 改为必传参数", "methods": [ "storeWarehouse.store.saveApiConfig" ], "notes": [ "app_name 不再有默认值自动生成逻辑,调用方必须传入非空的 app_name,否则返 回 400 错误。" ], "type": "changed" }, { "version": "2026.04.07-system-09", "date": "2026-04-07", "summary": "新增收货单快捷入库上架接口", "methods": [ "storage.inventory.quickPutaway" ], "notes": [ "新建 storage.inventory 库存操作模块。quickPutaway 从收货单直接生成入库单 (SCRK)并写入 wms_storage 库存表,同时更新 wms_stock_warehouse 库存数量(悲观行锁),回填收货明细入库状态。要求收货单已完成且所有明细已匹配系统商品。" ], "type": "added" }, { "version": "2026.04.08-system-01", "date": "2026-04-08", "summary": "新增收货单与入库单匹配入库接口", "methods": [ "storage.inventory.matchPutaway" ], "notes": [ "接收多个收货单和入库单,按商品(stock_warehouse_id)进行数量匹配入库,完 成后根据入库单来源(QM/API)自动触发回传。入参为 receiving_ids(数组)和 entry_order_ids(数组),返回匹配汇总、各收货单入库状态、各入库单状态及回传结果。isNeedAuth=true, isNeedLogin=true, isNeedRight=false。" ], "type": "added" }, { "version": "2026.04.08-system-02", "date": "2026-04-08", "summary": "saveApiConfig 新增 callback_url 可选参数", "methods": [ "storeWarehouse.store.saveApiConfig" ], "notes": [ "新增 callback_url 参数(VARCHAR(500),可选),用于 OPEN_API 类型入库单的 回调地址配置。" ], "type": "changed" }, { "version": "2026.04.08-system-03", "date": "2026-04-08", "summary": "serializeQimenConfig 新增返回 callback_url 字段,影响 list 和 listApiConfig 两个接口", "methods": [ "storeWarehouse.store.list", "storeWarehouse.store.listApiConfig" ], "notes": [ "serializeQimenConfig() 序列化方法新增 callback_url(string)字段。storeWarehouse.store.list 返回的每条记录 api_config 对象中包含 callback_url;storeWarehouse.store.listApiConfig 返回的 list 数组中每条配置包含 callback_url。" ], "type": "changed" }, { "version": "2026.04.08-system-04", "date": "2026-04-08", "summary": "新增库存移库(库位转移)接口", "methods": [ "storage.inventory.transferLocation" ], "notes": [ "新增 storage.inventory.transferLocation 接口,支持批量多商品多库位移库, 包含部分数量移库与全量移库。入参为 warehouse_id(仓库ID)和 transfers 数组(storage_id、target_space_id、quantity),触发 storage_transfer_completed 通知事件, 每条移库记录独立操作日志。isNeedAuth=true, isNeedLogin=true。" ], "type": "added" }, { "version": "2026.04.08-system-05", "date": "2026-04-08", "summary": "简化移库接口入参,从批量 transfers 数组改为单条移库", "methods": [ "storage.inventory.transferLocation" ], "notes": [ "移除 warehouse_id 和 transfers 数组入参,改为扁平的 storage_id + target_space_id + quantity 三个顶层参数。warehouse_id 从库存记录自动获取,接口从批量移库简化为单商品单库位移库。响应结构同步简化为单条结果对象。" ], "type": "modified" }, { "version": "2026.04.08-system-06", "date": "2026-04-08", "summary": "新增商品库存明细查询接口", "methods": [ "stock.warehouse.getStockDetail" ], "notes": [ "新增 stock.warehouse.getStockDetail 接口,按库位/批次维度查询商品库存分布。入参为 stock_id(必填,商品库存ID)和 pagination(可选,含 page/pageSize)。返回 stockItem(商品概要)、storageList(wms_storage 明细数组,含批次号、库位、数 量、锁定数量、生产日期、过期日期等,关联 location_space 库位信息)、pagination 分页信息。isNeedAuth=false, isNeedLogin=true。底层调用 stockStore.getStockDetail,自动校验商品归属当前仓库。" ], "type": "added" }, { "version": "2026.04.08-system-07", "date": "2026-04-08", "summary": "新增入参 group_by_batch,支持按批次维度切换库存明细聚合方式", "methods": [ "stock.warehouse.getStockDetail" ], "notes": [ "新增可选布尔参数 group_by_batch(默认 false)。false 时按库位合并数量,批次相关字段(batch_no, production_date, expiry_date, inbound_time, inbound_order_no, supplier_batch_no)置 null;true 时保持原逻辑返回每条明细。出参结构不变,但 storageList 中批次字段在合并模式下为 null。" ], "type": "modified" }, { "version": "2026.04.08-system-08", "date": "2026-04-08", "summary": "新增按商品维度移库接口", "methods": [ "storage.inventory.transferByProduct" ], "notes": [ "新增 storage.inventory.transferByProduct 接口,按库位+商品查找所有库存记 录合并移动。入参为 space_id(原库位ID)、stock_id(商品SKU ID,即 wms_stock_warehouse.id)、target_space_id(目标库位ID)、quantity(移库数量)。开启批次管理(is_batch_mgmt=Y)的商品会被拒绝,需使用 transferLocation 按库存记录精确移库。复用 storage_transfer_completed 通知事件,操作日志编码 STORAGE_TRANSFER_BY_PRODUCT。isNeedAuth=true, isNeedLogin=true。" ], "type": "added" }, { "version": "2026.04.08-system-09", "date": "2026-04-08", "summary": "补充 storeWarehouse.store.list 完整 response 输出字段说明,移除 api_config / apiConfig", "methods": [ "storeWarehouse.store.list" ], "notes": [ "从返回结果中移除 api_config 和 apiConfig 字段(代码中 delete serialized.api_config / delete serialized.apiConfig),文档 response 补充完整输出字段列表:id, store_id, store_name, warehouse_id, warehouse_name, counterparty_id, counterparty_name, current_subject_role, auth_status, auth_status_label, apply_reason, review_comment, apply_time, review_time, auth_start, auth_end, actual_end, print_quantity, applied_by, reviewed_by, ended_by, remask, use_status, policy_config, is_auth_valid, remaining_days 以及分页和 current_subject 信息。" ], "type": "updated" }, { "version": "2026.04.08-system-10", "date": "2026-04-08", "summary": "货主列表返回新增 has_qimen_config 布尔字段", "methods": [ "storeWarehouse.store.list" ], "notes": [ "storeWarehouse.store.list 返回的 data.list[] 中新增 has_qimen_config(boolean),表示该货主是否已配置奇门。" ], "type": "changed" }, { "version": "2026.04.08-system-11", "date": "2026-04-08", "summary": "补全 stock.warehouse.search 接口文档,新增 params / response / errors 完整说明", "methods": [ "stock.warehouse.search" ], "notes": [ "入参补充 keyword(string,模糊匹配 item_code / item_name / goods_code / barcode)和 store_id(number,按货主筛选)。响应补充 data 数组各字段(id, item_code, goods_code, item_name, sku_property, stock_unit, quantity, locked_quantity, brand_name, item_type, barcodes, store_stock)以及 total。errors 补充 code=0 搜 索失败场景。" ], "type": "updated" }, { "version": "2026.04.08-system-12", "date": "2026-04-08", "summary": "新增 with_stock / is_batch 参数,支持返回关联库存明细(按库位分 组或按批次逐条)", "methods": [ "stock.warehouse.search" ], "notes": [ "入参新增 with_stock(boolean,默认 false,是否返回关联库存数据)和 is_batch(boolean,默认 false,仅 with_stock=true 时生效,按批次明细返回)。响应 data[] 新增 storage[] 字段:is_batch=false 时按库位分组汇总(含 space_id、space、inventory_type、quantity、locked_quantity、available_quantity);is_batch=true 时逐 条返回批次明细(含 id、stock_id、space_id、batch_no、inventory_type、quantity、locked_quantity、available_quantity、production_date、expiry_date、inbound_time、inbound_order_no、supplier_batch_no、created_at、space)。" ], "type": "updated" }, { "version": "2026.04.08-system-13", "date": "2026-04-08", "summary": "新增 wms_stock_transaction 表和模型", "methods": [ "wms_stock_transaction" ], "notes": [ "新增出入库流水记录表 wms_stock_transaction,含 transaction_type(INBOUND/OUTBOUND)、warehouse_id、store_id、stock_id、storage_id、space_id、quantity、batch_no、inventory_type、order_type、order_no、order_id、receiving_id、entry_order_id、operator_id、operator_name、remark 等字段,关联 StockWarehouse 和 Storage 模型。" ], "type": "added" }, { "version": "2026.04.08-system-14", "date": "2026-04-08", "summary": "quickPutaway 和 matchPutaway 入库时自动写入出入库记录", "methods": [ "storage.inventory.quickPutaway", "storage.inventory.matchPutaway" ], "notes": [ "入库操作完成后自动写入 wms_stock_transaction 记录。quickPutaway 写入 order_type='SCRK'(收货入库),matchPutaway 写入 order_type='MATCH'(匹配入库),均 自动填充 warehouse_id、store_id、stock_id、storage_id、space_id、quantity、batch_no、inventory_type 等字段。" ], "type": "updated" }, { "version": "2026.04.08-system-15", "date": "2026-04-08", "summary": "新增 storage.inventory.list 出入库记录列表查询接口", "methods": [ "storage.inventory.list" ], "notes": [ "出入库记录列表查询,支持 where 条件(transaction_type、stock_id、space_id、store_id、order_type、order_no、inventory_type、operator_name、created_at)、 分页(pagination)、排序(sort)和 group_by_batch 参数。默认合并模式按库位+商品 聚合返回合计数量与记录条数,group_by_batch=true 时返回每条明细含 batch_no、order_no、operator_name 等完整信息。响应均关联 stockItem(item_code、item_name、sku_property、stock_unit)。" ], "type": "added" }, { "version": "2026.04.08-system-16", "date": "2026-04-08", "summary": "出入库流水记录查询接口从 storage.inventory.list 改名为 storage.transaction.list", "methods": [ "storage.transaction.list" ], "notes": [ "将出入库流水记录查询从 storage.inventory.list 迁移到 storage.transaction.list,避免与库存列表概念混淆。功能和参数不变。isNeedAuth=false, isNeedLogin=true, isNeedRight=false。" ], "type": "rename", "module": "storage" }, { "version": "2026.04.08-system-17", "date": "2026-04-08", "summary": "新增 storage.inventory.list 库存列表查询接口", "methods": [ "storage.inventory.list" ], "notes": [ "新增库存列表查询接口,查询 wms_storage 表。支持 where 条件(stock_id/space_id/store_id/inventory_type/batch_no/inbound_order_no/available_quantity/inbound_time/created_at)、分页、排序。支持 group_by_batch 参数:默认 false 按库位+商 品合并(SUM quantity/locked_quantity/available_quantity),true 返回每条明细含 batch_no/production_date/expiry_date 等。关联 stockItem(商品信息)和 space(库位信息)。isNeedAuth=false, isNeedLogin=true, isNeedRight=false。" ], "type": "add", "module": "storage" }, { "version": "2026.04.08-system-18", "date": "2026-04-08", "summary": "移除 storage.entry.create 创建入库单接口", "methods": [ "storage.entry.create" ], "notes": [ "不再允许通过 API 创建入库单。入库单仅由快捷入库(quickPutaway)和匹配入库(matchPutaway)等内部流程自动创建。底层 service 实现保留但不再通过 systemMethods 对外暴露。" ], "type": "remove", "module": "storage" }, { "version": "2026.04.08-system-19", "date": "2026-04-08", "summary": "移除 storage.entry.addDetail / deleteDetail / detailChange 对外 接口", "methods": [ "storage.entry.addDetail", "storage.entry.deleteDetail", "storage.entry.detailChange" ], "notes": [ "入库单明细编辑能力不再通过 systemMethods 对外暴露,入库单模块仅保留 list/get/cancel/completeEntry。" ], "type": "remove", "module": "storage" }, { "version": "2026.04.08-system-20", "date": "2026-04-08", "summary": "新增 storage.stockout 出库单模块(非订单出库单能力)", "methods": [ "storage.stockout.list", "storage.stockout.toOrder", "storage.stockout.listItems" ], "notes": [ "新增 storage.stockout.list / toOrder / listItems 接口,作为非订单出库单的主出口(对应奇门 stockout.create)。storage.delivery.* 仅作为兼容转发保留;底层 部分能力仍复用 order 模块。" ], "type": "add", "module": "storage" }, { "version": "2026.04.08-system-21", "date": "2026-04-08", "summary": "将 storage.stockout.toOrder 标记为占位接口", "methods": [ "storage.stockout.toOrder" ], "notes": [ "storage.stockout.toOrder 当前仅保留方法名用于后续扩展,暂不开放实际逻辑。调用时返回 code=405、message=占位接口,暂未开放。" ], "type": "change" }, { "version": "2026.04.09-system-01", "date": "2026-04-09", "summary": "storage.entry.cancel 支持批量作废,新增 ids 入参并兼容单条 id", "methods": [ "storage.entry.cancel" ], "notes": [ "新增入参 `ids`(number[])以支持批量作废,兼容旧入参 `id`;当同时传入 `ids` 与 `id` 时以 `ids` 为准。", "参数校验:`ids` 必须为非空数组;非法 ID 或空数组返回 400。", "业务约束:已完成/已作废/处于不可作废状态的单据不允许作废;批量场景下任一 单据不存在或状态不允许时整体返回 404/400,未执行部分更新。", "响应说明:单条作废返回字段 `id`(number);批量作废返回字段 `ids`(number[])。", "已同步更新 methods/system.json(storage.entry.cancel)为 SSOT。" ] }, { "version": "2026.04.09-system-02", "date": "2026-04-09", "summary": "新增基础模块车牌识别接口 index.recognizeLicensePlate", "methods": [ "index.recognizeLicensePlate" ], "notes": [ "入参:base64(string,必填)或 imageBase64/image_base64(兼容)", "响应:返回归一化后的识别对象,包含 licensePlate、plateNumber、color、confidence、requestId、imageSize、rawData", "错误:400(参数或图片格式/尺寸问题),500(第三方 OCR 调用失败或云密钥未 配置)", "文档中不包含任何敏感配置;实际腾讯云密钥保留在配置文件中,勿在文档中暴露 。" ], "type": "added" }, { "version": "2026.04.09-system-03", "date": "2026-04-09", "summary": "收紧基础模块车牌识别接口响应,仅返回 licensePlate 字段", "methods": [ "index.recognizeLicensePlate" ], "notes": [ "出参由 {licensePlate, plateNumber, color, confidence, requestId, imageSize, rawData} 调整为 {licensePlate}", "调用方请仅依赖 licensePlate 字段以适配新版本;历史字段已裁剪且不再保证存 在。", "文档中未包含任何云密钥或敏感配置信息。" ], "type": "changed" }, { "version": "2026.04.10-system-01", "date": "2026-04-10", "summary": "订单审核字段由 audit_status 替换为整数字段 step,并添加数据库迁移", "methods": [ "order.getreviewOrderlist", "order.reviewOrder.getreviewOrderlist", "order.reviewOrder.reviewOrder", "order.deliveryOrder.getdeliveryOrderlist", "order.list", "order.stats" ], "notes": [ "字段变更:order 相关审核字段从字符串/枚举 audit_status 替换为整数 step。", "step 映射:0=未审核,1=已审核,2=处理中,3=驳回/异常,4=配送中,5=已完成,9=已关闭。", "reviewOrder 接口在更新 inspection_status 的同时会写入 step 字段。", "必须执行迁移脚本:20260410150000-replace-audit-status-with-step-on-order-delivery-tables.js" ], "type": "changed" }, { "version": "2026.04.13-system-02", "date": "2026-04-13", "summary": "stock.warehouse.search 返回新增效期管理字段并保留 is_shelf_life_mgmt", "methods": [ "stock.warehouse.search" ], "notes": [ "响应 data[] 中新增字段:inbound_min_days、outbound_min_days、shelf_life_days、remaining_threshold_days(均为 number,单位:天)。", "保留并说明 is_shelf_life_mgmt 布尔字段(boolean),表示是否启用效期管理(true=启用)。", "仅更新文档(methods/system.json 与变更记录),代码行为不变。" ], "type": "updated" }, { "version": "2026.04.13-system-02", "date": "2026-04-13", "summary": "新增 storage.expiry.list 库存有效期列表查询接口", "methods": [ "storage.expiry.list" ], "notes": [ "该接口查询 wms_storage,关联 stockWarehouse 和 locationSpace,并按当前仓库与 remaining_threshold_days / expiry_date 过滤。" ], "type": "added" }, { "version": "2026.04.13-system-03", "date": "2026-04-13", "summary": "新增 storage.inventory.list 库存列表返回效期字段与预警标记", "methods": [ "storage.inventory.list" ], "notes": [ "库存列表响应增加生产日期、过期日期、效期预警是否触发字段", "预警标记仅在商品启用保质期管理且到期日满足阈值条件时为 true" ], "type": "updated" }, { "version": "2026.04.14-system-01", "date": "2026-04-14", "summary": "更新 index.searchSpace 文档", "methods": [ "index.searchSpace" ], "notes": [ "补充 index.searchSpace 的 params/response,按 ctx.user.store_id 作为仓库上下文;keyword 为可选字符串,对 space_code 与 custom_barcode 做 %keyword% 模糊匹配;返回字段 id、space_code、custom_barcode、custom_name,最多 50 条;仅文档同步,无代码变更。" ], "type": "updated" }, { "version": "2026.04.16-system-01", "date": "2026-04-16", "summary": "基础模块新增快递产品类型查询接口", "methods": [ "index.getExpressProductTypeList" ], "notes": [ "新增 index.getExpressProductTypeList,归属基础模块(module=index),用于查询指定快递公司的产品类型列表。", "对应服务实现:app/service/systems/express.js 中的 getExpressProductTypeList,支持传入 express_code 作为可选筛选参数(source=body)。", "接口设置为免鉴权(isNeedAuth=false)但需登录(isNeedLogin=true),与 index.getExpressList / index.getPlatformList 一致,优先从缓存读取。" ], "type": "added" }, { "version": "2026.04.17-system-01", "date": "2026-04-17", "summary": "新增快递管理模块(setting.express)及 5 个接口文档", "methods": [ "setting.express.list", "setting.express.listBase", "setting.express.create", "setting.express.checkCodeUnique", "setting.express.update" ], "notes": [ "新增独立模块组:快递管理模块(module=setting.express),将快递映射管理相关接口独立为一组以便维护。", "接口实现参考:app/service/systems/setting/express.js(返回结构)与 app/service/systemMethods/setting/express.js(对外方法包装)。", "接口鉴权与上下文:isNeedAuth=false, isNeedLogin=true;需在请求中传入 Authorization 以携带登录上下文(用于获取当前仓库/货主上下文)。", "已同步更新 methods/system.json,补充 params/response/errors,保持文档与实现一致。" ], "type": "added" }, { "version": "2026.04.17-system-02", "date": "2026-04-17", "summary": "setting.express.list 分页入参统一为 pagination", "methods": [ "setting.express.list" ], "notes": [ "将 setting.express.list 的分页入参文档从顶层 page/page_size/pageSize 迁移为 pagination 对象,主形态为 pagination;兼容 snake_case 的 page_size 与 camelCase 的 pageSize。", "文档与当前实现一致:顶层 page/page_size/pageSize 会被归一化到 data.pagination 并转发到系统服务。" ], "type": "updated" }, { "version": "2026.04.17-system-03", "date": "2026-04-17", "summary": "新增快递接口管理模块(setting.expressInterface)及 4 个接口文档", "methods": [ "setting.expressInterface.list", "setting.expressInterface.create", "setting.expressInterface.update", "setting.expressInterface.delete" ], "notes": [ "新增独立模块组:快递接口管理模块(module=setting.expressInterface),对应实现:app/service/systems/setting/expressInterface.js 与对外包装 app/service/systemMethods/setting/expressInterface.js。", "接口为当前仓库范围(基于 ctx.user.store_id),仓库边界由系统服务强制校验;禁止通过接口指定 warehouse_id/warehouseId。操作需登录(isNeedLogin=true),无需额外鉴权(isNeedAuth=false)。", "已在 methods/system.json 新增对应接口的 params/response/errors 文档,保持与实现一致。" ], "type": "added" }, { "version": "2026.04.18-system-01", "date": "2026-04-18", "summary": "补充订单储位分配接口文档:order.storageAllocation.allocateStorage", "methods": [ "order.storageAllocation.allocateStorage" ], "notes": [ "新增 order.storageAllocation.allocateStorage:按订单批量分配储位,支持多种入参别名(order_ids/ids/orderId 等)与仓库上下文优先级。", "响应包含 requested_order_ids, pending_order_ids, allocated_order_ids, shortage_order_ids, skipped_orders, picking_count, stock_lock_summary, storage_lock_summary 等字段,用于前端展示分配结果与不足提示。" ], "type": "added" }, { "version": "2026.04.18-system-02", "date": "2026-04-18", "summary": "新增 order.pendingOrder.allocateExpressCode:待处理订单模块的批量分配首单快递号(异步接口),复用 express.createWaybillCodePipeline。", "methods": [ "order.pendingOrder.allocateExpressCode" ], "notes": [ "异步接口:调用后立即返回 task_id,后台执行运单创建,通过 allocateExpressCodeTaskProgress 查询进度。", "入参为 ids(订单 ID 数组),sys_platform_code/logistics_code 等由后端从数据库读取。", "拆单场景请使用 order.pendingOrder.allocateSubOrderNumber。" ], "type": "added" }, { "version": "2026.04.18-system-03", "date": "2026-04-18", "summary": "将 order.storageAllocation.allocateStorage 迁移到 order.pendingOrder.allocateStorage,并移除原有公开分组。", "methods": [ "order.pendingOrder.allocateStorage" ], "notes": [ "将对外入口从 order.storageAllocation.allocateStorage 迁移到 order.pendingOrder.allocateStorage,旧的 order.storageAllocation 分组已从 methods/system.json 中移除。", "新的对外接口不接受 warehouse_id / warehouseId,仓库上下文由当前登录用户(ctx.user.store_id)提供。", "本次变更仅同步文档位置与对外方法名,底层实现保留且通过新的 system 方法暴露。" ], "type": "changed" }, { "version": "2026.04.19-system-02", "date": "2026-04-19", "summary": "新增待处理模块取消分配储位接口 order.pendingOrder.cancelAllocateStorage", "methods": [ "order.pendingOrder.cancelAllocateStorage" ], "notes": [ "新增待处理模块取消分配储位接口 `order.pendingOrder.cancelAllocateStorage`,直接对接 `service.systems.orderStorageAllocation.cancelAllocateStorage` 实现。", "接口现在仅接受订单ID(order_ids),不再接受 allow_storage_location;禁止传入 `warehouse_id/warehouseId`,仓库上下文由当前登录用户的 `store_id` 提供。", "响应返回标准 { flag, code, message, data } 结构,data 包含取消分配的汇总结果(warehouse_id, requested_order_ids, cancellable_order_ids, skipped_orders, orders, picking_count, storage_unlock_summary, stock_unlock_summary)。" ], "type": "added" }, { "version": "2026.04.21-system-01", "date": "2026-04-21", "summary": "新增 order.pendingOrder.updateOrderPlatform 方法:批量修改待处理订单平台信息", "methods": [ "order.pendingOrder.updateOrderPlatform" ], "notes": [ "通过 code 查找 wms_platform,平台不存在时返回 404 错误。", "仅操作当前仓库的当前订单表。", "noNeedRight=true,noNeedAuth=true(isNeedAuth: true 在 spec 中对应权限配置 noNeedAuth=true)。" ], "type": "added" }, { "version": "2026.04.21-system-02", "date": "2026-04-21", "summary": "新增方法 order.pendingOrder.updateOrderExpress:批量修改待处理订单的快递信息", "methods": [ "order.pendingOrder.updateOrderExpress" ], "notes": [ "新增 order.pendingOrder.updateOrderExpress:批量修改待处理订单的快递信息,按 express_code 从仓库快递列表(带缓存)匹配快递项。", "自定义映射(is_system_setting=true)时,sys_logistics_code/name 写入系统快递编码和名称,logistics_code/name 写入自定义编码和名称;系统快递(is_system_setting=false)时四个字段均写系统快递的 code/name。", "只操作当前仓库的当前订单表,不处理其他订单表;操作后写入操作日志(ORDER_UPDATE_EXPRESS)。" ], "type": "added" }, { "version": "2026.04.21-system-03", "date": "2026-04-21", "summary": "新增 order.expectionOrder.resolveException:将待处理异常订单转回正常待处理状态", "methods": [ "order.expectionOrder.resolveException" ], "notes": [ "新增 order.expectionOrder.resolveException:批量将 step=3 的异常订单恢复为 step=2 正常待处理状态。", "入参 ids 为订单ID 正整数数组,不能为空;仅操作当前仓库当前订单表。", "返回 updated_count(实际更新行数)与 ids(本次操作ID列表)。", "权限配置:noNeedLogin=false、noNeedRight=true、noNeedLog=false、noNeedAuth=true" ], "type": "added" }, { "version": "2026.04.21-system-04", "date": "2026-04-21", "summary": "新增 order.pendingOrder.cloneOrder 方法:克隆待处理订单", "methods": [ "order.pendingOrder.cloneOrder" ], "notes": [ "支持对 step 0/1/2/3 的待处理订单进行克隆操作。", "若原订单已分配储位(storage_status=fin),克隆前自动清除已分配库存。", "原订单取消后(step→9, status→cancel),以原订单业务数据创建新订单,流程状态字段全部重置为初始落库状态。", "克隆订单明细含 stock_id,新订单 ID 重新绑定。", "noNeedAuth=true,noNeedRight=true,noNeedLogin=false。" ], "type": "added" }, { "version": "2026.04.21-system-06", "date": "2026-04-21", "summary": "新增 order.pendingOrder.createOrder:手动创建待处理/待审核订单", "methods": [ "order.pendingOrder.createOrder" ], "notes": [ "新增 order.pendingOrder.createOrder:手动创建订单,step 由货主策略 need_order_approval 决定(1→待审核 step=0,0→待处理 step=1)。", "必填字段:store_id、name、mobile/tel 至少一项、detail_address、items[](含 item_code 和 plan_qty)。", "delivery_order_code 不传则自动生成(SYS+时间戳+随机4位);logistics_code/sys_platform_code 不传则读货主合约策略 default_express_code/default_platform_code。", "不做库存锁定,储位分配为独立步骤。操作日志写入 ORDER_CREATE。", "noNeedRight=true,noNeedAuth=true,noNeedLogin=false。" ], "type": "added" }, { "version": "2026.04.21-system-07", "date": "2026-04-21", "summary": "新增 Excel 模板下载与批量导入创建订单接口:order.pendingOrder.downloadCreateTemplate 和 order.pendingOrder.importOrdersFromExcel", "methods": [ "order.pendingOrder.downloadCreateTemplate", "order.pendingOrder.importOrdersFromExcel" ], "notes": [ "新增 order.pendingOrder.downloadCreateTemplate:生成 Excel 导入模板,返回 base64 编码的 xlsx 文件,表头中带 * 的列为必填项(橙色背景),可选列为灰色背景,含示例数据行和填写说明工作表。", "新增 order.pendingOrder.importOrdersFromExcel:接受 base64 编码的 xlsx 文件,按订单号分组,每组调用 createOrder 逻辑创建订单;不中断执行,逐条记录成功/失败结果返回。", "多行相同订单号的行组成一个完整订单,每行代表一条商品明细;订单头信息(收件人、地址等)取每组第一行。", "step 由货主策略 need_order_approval 决定(与 createOrder 一致);通过事务保证每个订单的主记录与明细原子写入。" ], "type": "added" }, { "version": "2026.05.01-system-01", "date": "2026-05-01", "summary": "新增基础模块 IM 登录码接口文档:index.loginToIm", "methods": [ "index.loginToIm" ], "notes": [ "新增 index.loginToIm 文档,入参为空对象({}),依赖当前登录用户上下文生成一次性 code。", "响应增加 data.code 字段,长度固定 64 位(hex),默认有效期 5 分钟。", "错误码补充:401(用户未登录)、400(用户信息不完整,缺 employees_id 或 employees_name)。", "该接口仅做登录码签发,实际换取员工信息由 IM 侧 ssoCodeToId 完成并在成功后使 code 失效。" ], "type": "added" }, { "version": "2026.05.01-system-03", "date": "2026-05-01", "summary": "扩展 index.loginToIm 返回字段:增加主体/主体类型/头像信息", "methods": [ "index.loginToIm" ], "notes": [ "登录码签发接口响应新增 employees_id、employees_name、subject、store_type、avatar 字段。", "subject 包含 id/name;store_type 严格取自 wms_store.project 字段,不再返回 subject_type 兼容字段。", "同一批字段会写入 code 缓存,供 IM 侧 ssoCodeToId 换取并在成功后失效。" ], "type": "updated" }, { "version": "2026.05.01-system-04", "date": "2026-05-01", "summary": "index.loginToIm 与 ssoCodeToId 改为严格字段模式,不再做兼容回退", "methods": [ "index.loginToIm" ], "notes": [ "loginToIm 仅读取 ctx.user 标准字段:employees_id、employees_name、store_id、store_name、store_type、avatar。", "不再兼容 id/real_name/username/company_name/avatar_url 等历史字段。", "ssoCodeToId 返回值不再使用默认兜底,缺少关键字段时按 code 无效处理。" ], "type": "updated" }, { "version": "2026.05.03-system-01", "date": "2026-05-03", "summary": "将 order.wave.fetch 调整为异步任务提交接口,删除同步返回抓取结果字段", "methods": [ "order.wave.fetch" ], "notes": [ "接口从同步返回抓取结果改为提交任务并异步处理。", "移除原方法中 result_list / total_request_quantity / total_fetched_quantity 等同步返回字段。" ], "type": "updated" }, { "version": "2026.05.03-system-06", "date": "2026-05-03", "summary": "order.wave.batchList:新增 where 支持并限制传入字段", "methods": [ "order.wave.batchList" ], "notes": [ "batchList 新增 where 支持及白名单过滤;禁止传入 warehouse_id/warehouseId。" ], "type": "updated" }, { "version": "2026.05.03-system-08", "date": "2026-05-03", "summary": "order.pendingOrder.allocateStorage 改为异步提交", "methods": [ "order.pendingOrder.allocateStorage" ], "notes": [ "接口变更为异步提交:调用后立即返回 request_id,后端异步执行储位分配;接口不再在响应中同步返回分配明细(如 requested_order_ids、allocated_order_ids 等)。客户端可后续通过任务 ID / 查询链路或事件获取最终分配结果。" ], "type": "updated" }, { "version": "2026.05.03-system-10", "date": "2026-05-03", "summary": "新增订单批量移出波次接口", "methods": [ "order.wave.batchRemoveOrders" ], "notes": [ "按订单ID批量移出波次;仅处理待处理订单表中非待审核订单(step in [1,2,3])。", "操作在单事务内完成:清空订单的 wave_id/wave_no,并回写 wms_wave_batch 统计(重算 total_orders;当波次被清空时将 wave_status 置为 -1)。", "仓库上下文来自当前登录用户(ctx.user.store_id)。" ], "type": "updated" }, { "version": "2026.05.08-system-05", "date": "2026-05-08", "summary": "order.wave.batchList:新增 source 字段并支持 where.source 过滤,返回 list item 中新增 source 字段", "methods": [ "order.wave.batchList" ], "notes": [ "新增 where.source(可选,number)用于按来源过滤:0=普通波次(正常后台操作),1=管理后台策略任务,2=PDA策略任务;不传则不过滤。", "响应 list 每条记录新增字段 source(number),用于区分波次来源。", "仅更新文档,业务代码不在此变更范围。" ], "type": "updated" }, { "version": "2026.05.09-system-01", "date": "2026-05-09", "summary": "新增 order.wave.wavePickTaskCancelSelf;order.wave.waveStrategyList 新增预演计数字段/参数", "methods": [ "order.wave.wavePickTaskCancelSelf", "order.wave.waveStrategyList" ], "notes": [ "新增接口 `order.wave.wavePickTaskCancelSelf`:仅支持单个 `task_id`(number,必填),明确不支持 `task_ids` 批量参数。", "业务约束:仅允许取消当前登录用户本人创建的拣货任务;若尝试取消非本人创建任务,接口应返回 400 错误(仅允许取消本人创建任务)。", "返回建议:与现有取消接口风格一致,包含 `cancelled_count`(0/1)、`task_id`、`task_no`(若后端返回)或相应的取消结果汇总。", "错误码建议:400 参数不合法(task_id 缺失或传了 task_ids);400 仅允许取消本人创建任务;500 取消失败。", "新增参数:calculate_next_fetch_order_count(number,可选),含别名 calculateNextFetchOrderCount;取值 0=不计算(默认),1=计算并返回每条策略的 next_fetch_order_count,用于前端在策略列表中预览抓取量。", "新增响应字段:list[*].next_fetch_order_count(number),含义:按当前策略口径预演一次自动抓取时,预计会选中的订单数量;当未开启计算时返回 0。" ], "type": "added" }, { "version": "2026.05.11-system-01", "date": "2026-05-11", "summary": "新增字段 wave_prefix(策略层波次前缀),并补充 PDA 抓取波次号生成行为说明", "methods": [ "order.wave.waveStrategyList", "order.wave.waveStrategyCreate", "order.wave.waveStrategyUpdate", "order.wave.waveStrategyFetchPda" ], "notes": [ "在 wave strategy 对象中新增可选字段 wave_prefix:策略波次前缀,优先于仓库前缀。", "校验规则:长度 1-5,仅允许 A-Z0-9;保存时会转为大写;为空时回退仓库前缀:团购使用 group_wave_prefix,散单使用 delete_order_wave_prefix。", "在 order.wave.waveStrategyList 的返回 list[*] 中新增字段 wave_prefix(string)。", "在 order.wave.waveStrategyCreate / waveStrategyUpdate 的入参中新增可选字段 wave_prefix(string),创建/更新成功后保存为大写且触发策略版本推进。", "在 order.wave.waveStrategyFetchPda 的行为说明中补充:生成波次号(wave_no)时优先使用策略层 wave_prefix,否则按策略类型回退到仓库前缀;前缀校验同上。" ], "type": "updated" }, { "version": "2026.05.15-system-01", "date": "2026-05-15", "summary": "仅更新文档:将 setting.express.create 入参与实现对齐(新增 express_code,移除 platform)", "methods": [ "setting.express.create" ], "notes": [ "仅同步文档,与实现对齐,未修改任何业务代码或行为" ], "type": "updated" }, { "version": "2026.05.15-system-02", "date": "2026-05-15", "summary": "新增 storage.report.search:库存流水统计报表,支持按时间闭区间过滤与按库位/按商品聚合", "methods": [ "storage.report.search" ], "notes": [ "方法新增:storage.report.search", "时间过滤为闭区间:created_at >= start_time 且 created_at <= end_time", "当 where.by_space 为 false(默认)时,按商品+货主聚合(多个库位汇总);当为 true 时按商品+库位返回", "不返回无流水的商品/键(仅返回在查询区间内出现过流水的数据)" ], "type": "added" }, { "version": "2026.05.15-system-03", "date": "2026-05-15", "summary": "库存报表模块主入口迁移到 stock.report.search,storage.report.search 保持兼容别名", "methods": [ "stock.report.search", "storage.report.search" ], "notes": [ "新增主入口方法 stock.report.search,沿用既有报表统计口径(时间闭区间、by_space/store_ids、返回字段保持一致)。", "保留 storage.report.search 作为兼容别名,并在描述中明确建议迁移到 stock.report.search。", "仅更新 methods 文档配置,不修改业务代码。" ], "type": "updated" }, { "version": "2026.05.15-system-04", "date": "2026-05-15", "summary": "文档主入口统一为 stock.report.search,storage.report.search 调整为兼容别名简述", "methods": [ "stock.report.search", "storage.report.search" ], "notes": [ "保留 stock.report.search 作为库存报表唯一完整文档入口。", "storage.report.search 不再维护完整重复字段,仅保留迁移与兼容说明。", "仅更新 methods 文档配置,不修改业务代码。" ], "type": "updated" }, { "version": "2026.05.15-system-05", "date": "2026-05-15", "summary": "拆分 storage.report 模块并移除错误 stock.report.search 文档入口", "methods": [ "storage.report.search", "stock.report.search" ], "notes": [ "将库存报表从 storage.inventory 中拆分为独立模块 storage.report,storage.report.search 文档改为主入口语义(不再作为兼容别名)。", "从 storage.inventory 分组中移除错误的 stock.report.search 文档入口以及兼容别名条目 storage.report.search。", "最终归属:storage.report.search 属于模块 storage.report;stock.report.search 的文档入口已移除以避免混淆(代码实现保留于 app/service/systemMethods/storage/report.js 的 storage.report.search)。", "仅修改文档,不修改应用代码实现。" ], "type": "updated" }, { "version": "2026.05.15-system-06", "date": "2026-05-15", "summary": "storage.report.search 新增排序能力文档说明", "methods": [ "storage.report.search" ], "notes": [ "补充 sort 参数:支持 sortField/sort_field、sortOrder/sort_order。", "补充排序白名单:begin_total、inbound_total、outbound_total、end_total。", "补充非法排序字段/顺序回退默认排序说明。", "响应说明补充:已按 sort 规则排序返回。" ], "type": "updated" }, { "version": "2026.05.16-system-01", "date": "2026-05-16", "summary": "新增 storage.report.export:按与 storage.report.search 相同条件导出库存报表 Excel", "methods": [ "storage.report.export" ], "notes": [ "新增方法:storage.report.export,复用 storage.report.search 的 where/sort 查询条件。", "导出文件包含两个 sheet:汇总、变更记录。", "用于在统计结果基础上回溯明细流水,提升库存变动追溯效率。" ], "type": "added" }, { "version": "2026.05.16-system-02", "date": "2026-05-16", "summary": "storage.report.export 改为异步任务 + 新增 exportTaskProgress", "methods": [ "storage.report.export", "storage.report.exportTaskProgress" ], "notes": [ "调用方式调整为两步:先调用 storage.report.export 提交任务并获取 task_id,再调用 storage.report.exportTaskProgress 轮询任务进度。", "下载链接获取方式:当 status=success 时,从 exportTaskProgress 响应的 download_url 字段获取导出文件地址。", "任务状态值补充:submitted/running/success/failed/not_found。" ], "type": "updated" }, { "version": "2026.05.16-system-03", "date": "2026.05.16", "summary": "同步 setting.expressInterface.create/update 入参与系统快递编码映射规则", "methods": [ "setting.expressInterface.create", "setting.expressInterface.update" ], "notes": [ "补充入参:sys_express_code、weight_type、address、town_name、ispickup、shipperno,并保留既有字段。", "在参数说明补充 camelCase 别名支持:sysExpressCode、weightType、townName、isPickup、shipperNo 等。", "同步约束变化:不再因同仓快递编码重复或平台重复直接返回 409;当 express_code 无法匹配系统快递编码时返回 400,文案为 express_code 未匹配到系统快递编码。" ], "type": "updated" }, { "version": "2026.05.17-system-05", "date": "2026-05-17", "summary": "同步 storage.receiving.addDetail 的参数与返回值(从实现提取)", "methods": [ "storage.receiving.addDetail" ], "notes": [ "补充 receiving_id 入参说明", "补充返回的 details 数组与 selectId 字段", "补充可能的错误码:404/400/500" ], "type": "updated" }, { "version": "2026.05.17-system-06", "date": "2026-05-17", "summary": "重新同步 addDetail 文档", "methods": [ "storage.receiving.addDetail" ], "notes": [ "再次从实现代码核对并补充参数/返回值/错误码,确保文档与实现一致", "仅同步文档,不修改业务代码" ], "type": "updated" }, { "version": "2026.05.17-system-07", "date": "2026-05-17", "summary": "addDetail 新增可选 item 入参并兼容空白创建链路", "methods": [ "storage.receiving.addDetail" ], "notes": [ "item 有值时按传入字段创建(服务端覆盖 receiving_id 与 creator_id)", "兼容不传 item 的空白创建链路;item.children 需覆盖关键字段(有则写、无则补齐)。" ], "type": "updated" }, { "version": "2026.05.17-system-10", "date": "2026-05-17", "summary": "调整 storage.receiving.getReceivingDetail 库位字段输出语义:space_id 改为展示名称并补充兼容字段", "methods": [ "storage.receiving.getReceivingDetail" ], "notes": [ "将 receiving.details.*.space_id 定义为展示名称(string|null),优先 custom_space_name,其次 space_name,不再作为原始数值ID文档语义。", "新增并明确 receiving.details.*.space_id_raw(number|null)用于保留原始库位ID,兼容旧调用方。", "补充 receiving.details.*.space_name(库位名称/编码)与 receiving.details.*.custom_space_name(自定义名称,可空)字段说明。" ], "type": "updated" }, { "version": "2026.05.17-system-11", "date": "2026-05-17", "summary": "补充 subject_config.enable_external_express_code 字段文档与默认值语义", "methods": [ "store.createStore", "store.createWarehouse", "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "在 store.createStore 与 store.createWarehouse 的 subject_config 入参中新增字段:enable_external_express_code(boolean),默认 false;开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)。", "此 change 同时用于说明将在 setting.warehouse.getSettings / saveSettings 中补充该字段的文档说明(后续 doc-only 写入)。" ], "type": "updated", "module": "store" }, { "version": "2026.05.17-system-12", "date": "2026-05-17", "summary": "storeWarehouse.store 策略配置文档新增 enable_external_express_code 字段说明(向后兼容)", "methods": [ "storeWarehouse.store.getPolicyConfig", "storeWarehouse.store.savePolicyConfig" ], "notes": [ "在 getPolicyConfig / savePolicyConfig 的出参说明中补充 data.policy_config.enable_external_express_code 字段,明确为 flag(0=关闭,1=开启),默认 0。", "在 savePolicyConfig 的入参说明中补充 policy_config.enable_external_express_code 字段定义。", "本次为向后兼容的文档增强:新增可选策略字段说明,不影响现有调用。" ], "type": "updated" }, { "version": "2026.05.19-system-01", "date": "2026-05-19", "summary": "补充 storage.entry.list 的 expense_record 筛选语义与未迁移环境错误提示", "methods": [ "storage.entry.list" ], "notes": [ "在 where 参数说明中补充 expense_record 字段语义(费用是否记录)及 eq/in 支持。", "明确 true/false、1/0、y/n、yes/no 的归一化规则与等价写法示例。", "补充未完成表结构迁移时可能返回 400 及错误提示文案。" ], "type": "updated" }, { "version": "2026.05.20-system-01", "date": "2026-05-20", "summary": "同步 order.recheckOrder.scanOrder 返回结构,补充 cart_match_view 语义化视图说明", "methods": [ "order.recheckOrder.scanOrder" ], "notes": [ "新增返回字段:match_type(waybill/cart)与 cart_match_view(仅 cart 命中返回)。", "cart_match_view 包含通用子字段:mode_code / mode_name / view_type / task;当车号命中时按 pick_mode 返回语义化结构:mode 1/5 返回 groups,mode 2 返回 orders,mode 3 返回 pick_groups,mode 4 返回 box_groups。" ], "type": "updated" }, { "version": "2026.05.22-system-01", "date": "2026-05-22", "summary": "新增 index.getPlatformOauthLink 文档,补充平台授权链接接口说明", "methods": [ "index.getPlatformOauthLink" ], "notes": [ "入参支持 code、platform_code、platformCode 三种平台编码字段别名。", "当前仅支持 PDD;成功返回 data.platform_code、data.oauth_link 和 code=200,其他平台返回 code=400。", "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改业务代码。" ], "type": "added", "module": "index" }, { "version": "2026.05.22-system-02", "date": "2026-05-22", "summary": "更新 index.getPlatformOauthLink 文档,补充仓库上下文、预占记录与错误说明", "methods": [ "index.getPlatformOauthLink" ], "notes": [ "补充真实行为:从 ctx.user.store_id 读取当前仓库 ID,从 wms_platform.auth_base_url 读取授权基础地址,并在 wms_shops 创建平台授权预占记录。", "补充 oauth_link 细节:追加 client_id、redirect_uri(配置非空时)以及长查询参数 wms_authorization_reservation_code,对应唯一 auth_random_code。", "补充常见错误:平台编码为空、仓库上下文缺失、平台不存在、授权基础地址缺失/格式错误、不支持的平台,以及预占记录创建失败。" ], "type": "updated", "module": "index" }, { "version": "2026.05.22-system-03", "date": "2026-05-22", "summary": "同步 index.getPlatformOauthLink 当前实现:裸码入库与 state 拼接规则", "methods": [ "index.getPlatformOauthLink" ], "notes": [ "补充真实行为:从 ctx.user.store_id 读取当前仓库,从 wms_platform.auth_base_url 读取基础授权链接,并优先复用 wms_shops 中 status=0 的未授权记录。", "明确 auth_random_code 当前以裸码保存;若复用到历史带前缀记录,会先去掉 platformOauthReservationCodePrefix 后再回写。", "更新 oauth_link 说明:state 由“前缀 + 平台编码 + '_' + 裸码”组成并整体 URL 编码后直接拼接到基础授权链接后,例如 xxxxx_PDD_;同时移除已不存在的基础地址格式错误/不支持平台错误描述。" ], "type": "updated", "module": "index" }, { "version": "2026.05.22-system-04", "date": "2026-05-22", "summary": "修正 index.getPlatformOauthLink 文档中的残留平台限制描述", "methods": [ "index.getPlatformOauthLink" ], "notes": [ "移除 index.getPlatformOauthLink 参数与返回字段中残留的“当前仅支持 PDD”描述,避免与当前实现不一致。", "保留授权链接仅依赖平台已配置基础授权链接模式的说明,不再把示例平台编码误写成实现限制。" ], "type": "updated", "module": "index" }, { "version": "2026.05.22-system-05", "date": "2026-05-22", "summary": "新增 index.getShopList 文档,并同步 custom_name 与店铺列表脱敏返回规则", "methods": [ "index.getShopList" ], "notes": [ "新增 index.getShopList:接口依赖当前登录仓库上下文 ctx.user.store_id,不接受额外业务入参,缺少仓库时返回 400:未识别到当前仓库。", "补充真实返回结构:data.list 为数组,包含 id、warehouse_id、platform_code、shop_name、custom_name、status、auth_expire_at、token_expires_at、refresh_token_expires_at、scope、created_at、updated_at 以及脱敏后的 owner_id、access_token、refresh_token、auth_random_code。", "同步脱敏规则:owner_id 非空且长度大于 5 时返回前 3 位 + *** + 后 2 位,长度小于等于 5 时返回 ***;access_token、refresh_token、auth_random_code 非空时固定返回 ***,空值返回 null。", "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改任何业务代码。" ], "type": "added", "module": "index" }, { "version": "2026.05.22-system-06", "date": "2026-05-22", "summary": "新增 index.getShopExpressList 文档,补充店铺快递列表统一返回结构", "methods": [ "index.getShopExpressList" ], "notes": [ "按 ctx.user.store_id 校验店铺归属,仅允许查询当前登录仓库下的店铺。", "服务端按店铺所属平台拉取并收敛快递签约/电子面单可用列表,统一返回前端消费结构。", "未接入平台当前返回空列表;若店铺缺少授权 access_token,则返回 400:店铺未授权。", "仅文档同步,不改业务代码。" ], "type": "added", "module": "index" }, { "version": "2026.05.22-system-07", "date": "2026-05-22", "summary": "同步快递接口文档:is_share 仅展示不可编辑", "methods": [ "setting.expressInterface.list", "setting.expressInterface.create", "setting.expressInterface.update" ], "notes": [ "create/update 不再接受 is_share", "list 仍可返回 is_share 作为展示信息", "仅文档同步,不改业务代码" ], "type": "updated", "module": "setting.expressInterface" }, { "version": "2026.05.22-system-08", "date": "2026-05-22", "summary": "同步快递接口列表文档,移除未返回字段说明", "methods": [ "setting.expressInterface.list" ], "notes": [ "根据 app/service/systems/setting/expressInterface.js 的 list() 查询字段与 normalizeInterfaceRow() 返回结构,同步 setting.expressInterface.list 不返回 token。", "按当前实现清理 response.children 中未返回的 share_id、can_use_count 字段说明。", "保留 is_share,并明确其仅用于展示,不作为编辑入参。" ], "type": "updated", "module": "setting.expressInterface" }, { "version": "2026.05.22-system-09", "date": "2026-05-22", "summary": "index.getShopList 支持按平台编码筛选店铺", "methods": [ "index.getShopList" ], "notes": [ "index.getShopList 兼容 platform_code 与 platformCode 两种传参方式,服务端按 platform_code、platformCode 顺序读取首个 trim 后非空值作为平台筛选条件。", "未传平台参数时返回当前登录仓库下全部已授权店铺;传入非空平台编码时仅返回该平台的已授权店铺。", "本次仅补充筛选条件文档,不影响返回结构、排序规则与 owner_id/access_token/refresh_token/auth_random_code 的脱敏规则。", "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改任何业务代码。" ], "type": "updated", "module": "index" }, { "version": "2026.05.22-system-10", "date": "2026-05-22", "summary": "快递接口配置新增 shop_id 字段", "methods": [ "setting.expressInterface.create", "setting.expressInterface.update", "setting.expressInterface.list" ], "notes": [ "create/update 支持 shop_id/shopId(兼容 snake_case 与 camelCase),为店铺 ID,未传或空值按 null 处理。", "list 返回 shop_id 字段,列表 where 支持按 shop_id 过滤。" ], "type": "updated" }, { "version": "2026.05.22-system-11", "date": "2026-05-22", "summary": "调整快递接口列表排序规则", "methods": [ "setting.expressInterface.list" ], "notes": [ "setting.expressInterface.list 改为按 weight ASC, id DESC 排序;优先按权重排序,权重相同再按 id 倒序。", "本次仅同步该接口排序说明,不影响返回结构。" ], "type": "updated", "module": "setting.expressInterface" }, { "version": "2026.05.22-system-12", "date": "2026-05-22", "summary": "index.getShopExpressList 返回新增系统快递编码", "methods": [ "index.getShopExpressList" ], "notes": [ "data.list[*] 新增 sys_express_code 字段,由平台快递编码 wp_code 映射系统快递编码,未匹配时返回空字符串。", "补充 data.list[*].wp_name 说明:由系统快递基础表根据平台快递编码映射得到名称,未匹配时返回空字符串。", "原有请求参数、鉴权方式与返回主结构保持不变。", "仅文档同步,不改业务代码。" ], "type": "updated", "module": "index" }, { "version": "2026.05.23-system-01", "date": "2026-05-23", "summary": "补充快递接口列表 is_system_express_code 返回字段说明", "methods": [ "setting.expressInterface.list" ], "notes": [ "在 setting.expressInterface.list 的 response.children 中补充 is_system_express_code 字段说明。", "该字段表示当前行 express_code 是否为系统快递编码;不是系统快递编码返回 0,否则返回 1。", "仅文档同步,不改业务代码。" ], "type": "updated", "module": "setting.expressInterface" }, { "version": "2026.05.23-system-02", "date": "2026-05-23", "summary": "完善 index.getExpressList 文档:补充过滤规则、返回字段与仓库维度行为", "methods": [ "index.getExpressList" ], "notes": [ "补充 `systemOnly`、`express_code`、`expressCode` 的真实入参语义,明确真值识别规则与字段优先级。", "补充默认模式、系统模式、按快递编码过滤模式下的返回差异,说明当前登录仓库维度来自 `ctx.user.store_id`。", "补充 `data[*]` 各字段含义,明确系统基础快递与仓库自定义快递编码的差异字段。", "仅文档同步,不修改业务代码。" ], "type": "updated", "module": "index" }, { "version": "2026.05.24-system-01", "date": "2026-05-24", "summary": "同步 index.getExpressList 文档:移除 expressCode 别名并明确 express_code 筛选语义", "methods": [ "index.getExpressList" ], "notes": [ "移除 index.getExpressList 文档中的 expressCode 驼峰别名参数,仅保留 express_code。", "明确当 systemOnly=false 且传入 express_code 时,接口按自定义映射记录中的系统快递编码字段 express_code 过滤,而不是按自定义 code 过滤。", "保留 systemOnly=true 按系统快递编码过滤系统基础快递列表,以及默认合并逻辑、缓存优先、仓库维度来源不变的说明。" ], "type": "updated" }, { "version": "2026.05.24-system-02", "date": "2026-05-24", "summary": "新增 index.getCainiaoStfTemplates 接口文档并明确模板返回语义", "methods": [ "index.getCainiaoStfTemplates" ], "notes": [ "新增无参接口 index.getCainiaoStfTemplates:从当前仓库首个已授权 TB 店铺发起 cainiao.waybill.ii.search 查询菜鸟 STF 模板。", "补充返回结构说明:data.platform_code 固定为 TB;data.list 返回模板数组并包含 template_id/template_name/template_url/cp_code/wp_code 字段。", "明确模板列表为宽松结构解析并按 template_id/template_name/template_url 核心语义去重。", "补充错误码说明:未识别仓库返回 400;当前仓库无已授权 TB 店铺返回 404。" ], "type": "added" }, { "version": "2026.05.24-system-03", "date": "2026-05-24", "summary": "调整 index.getCainiaoStfTemplates 为免登录/免鉴权接口", "methods": [ "index.getCainiaoStfTemplates" ], "notes": [ "将 index.getCainiaoStfTemplates 的 isNeedLogin 调整为 false,接口改为免登录访问。", "保持 isNeedAuth=false,并同步免权限拦截配置,避免登录态与鉴权拦截。", "该接口仍为无请求参数,headers 调整为空数组。" ], "type": "updated", "module": "index" }, { "version": "2026.05.24-system-04", "date": "2026-05-24", "summary": "调整 index.getCainiaoStfTemplates 为公共无参模板查询接口", "methods": [ "index.getCainiaoStfTemplates" ], "notes": [ "index.getCainiaoStfTemplates 改为公共无参查询,不再依赖当前仓库、登录态或店铺授权。", "接口直接调用 requestTbWaybillSearch({ cpCode: '' }) 查询公共模板,返回 data.platform_code='TB' 与模板数组。", "requestTbWaybillSearch 支持 accessToken 缺失时不下发 session,因此该接口不再依赖 session。" ], "type": "updated" }, { "version": "2026.05.24-system-05", "date": "2026-05-24", "summary": "同步 index.getCainiaoStfTemplates 改用淘宝标准模板公共接口", "methods": [ "index.getCainiaoStfTemplates" ], "notes": [ "index.getCainiaoStfTemplates 改为调用淘宝开放平台 cainiao.cloudprint.stdtemplates.get,不再复用 cainiao.waybill.ii.search。", "接口不需要用户授权,不下发 session,继续使用 https://eco.taobao.com/router/rest 与 TOP 公共签名参数。", "模板列表改为从 cainiao_cloudprint_stdtemplates_get_response.result.datas[*].standard_templates[*] 做宽松兼容解析,统一返回 template_id/template_name/template_url/cp_code/wp_code。" ], "type": "updated" }, { "version": "2026.05.24-system-06", "date": "2026-05-24", "summary": "新增 index.getPrintPlatformList 接口文档并明确打印平台下拉返回结构", "methods": [ "index.getPrintPlatformList" ], "notes": [ "新增 index.getPrintPlatformList 文档,说明该接口供快递接口新增/编辑页下拉选择使用。", "补充接口行为:仅返回未删除且状态为 ACTIVE 的打印平台,不分页,按 platform_name 与 id 升序返回。", "补充 data[*] 返回字段说明,明确 code/name/value/label/platform_code/platform_name/status/remark 的含义。", "仅文档同步,不修改业务代码。" ], "type": "added", "module": "index" }, { "version": "2026.05.24-system-07", "date": "2026-05-24", "summary": "新增 index.getPrintPlatformTemplateList 文档,明确 express_code 必填与模板过滤语义", "methods": [ "index.getPrintPlatformTemplateList" ], "notes": [ "新增 index.getPrintPlatformTemplateList 方法文档,补充 platform_code 与 express_code 入参,其中 express_code 标记为必填。", "明确业务语义:接口按 platform_code(默认 CAINIAO)定位 wms_express 中对应打印平台字段,并使用 express_code 过滤模板结果后返回。", "补充返回结构 data.platform_code / data.express_code / data.responseData,说明未实现平台返回空对象。", "仅文档同步,不修改业务代码。" ], "type": "added", "module": "index" }, { "version": "2026.05.25-system-01", "date": "2026-05-25", "summary": "新增 index.polyapiAuthorizeUrl 接口文档并标注免登录免鉴权特征", "methods": [ "index.polyapiAuthorizeUrl" ], "notes": [ "新增基础模块方法 index.polyapiAuthorizeUrl,说明其为公共无参接口。", "明确接口固定调用菠萝派 Differ.JH.BuildeAuthorizeUrl,返回体中以 data.respone 原样包裹上游响应。", "同步标注 isNeedLogin=false、isNeedAuth=false,headers 为空数组。" ], "type": "added" }, { "version": "2026.05.25-system-02", "date": "2026-05-25", "summary": "新增店铺模块相关接口文档(shops.list/add/del/edit)及授权会话接口 shops.GetAuthorizeSessionKey", "methods": [ "shops.list", "shops.add", "shops.del", "shops.edit", "shops.GetAuthorizeSessionKey" ], "notes": [ "同步实现:shops.list 支持 where 分页与 quickWhere 快速搜索;shops.add/edit 校验 platform_code 存在且为 ACTIVE,custom_name 必填且长度限制;shops.del 为软删除,会返回 deleted=true 并清空敏感字段,若存在快递接口引用返回 409;shops.GetAuthorizeSessionKey 对 PDD/CAINIAO 平台生成预占码并返回 authorize_url,其他平台返回 501。", "字段命名兼容说明:接口实现兼容 snake_case 与 camelCase 入参,文档以 snake_case 为主并注明兼容性。" ], "type": "added" }, { "version": "2026.05.25-system-03", "date": "2026-05-25", "summary": "同步 shops.add 去入参化:移除 shop_name 入参并明确由授权后获取店铺名称", "methods": [ "shops.add" ], "notes": [ "shops.add 入参移除 shop_name(及同义传参语义),仅保留 custom_name 与 platform_code 为关键请求字段。", "补充说明:新增时 shop_name 由服务端生成 PENDING_* 占位名,后续以授权回调同步真实店铺名称。", "仅文档同步,不修改任何业务代码。" ], "type": "updated", "module": "shops" }, { "version": "2026.05.28-system-02", "date": "2026-05-28", "summary": "新增 method: order.print.unlockWavePlatformPrintDataByGroup,按分组解锁波次平台打印锁", "methods": [ "order.print.unlockWavePlatformPrintDataByGroup" ], "notes": [ "新增方法:order.print.unlockWavePlatformPrintDataByGroup,用于按分组规则批量解锁波次内被锁定的订单(将 print_lock_status 设为 'none')。", "入参说明:group_type 默认为 platform_express(支持 platform、platform_express、order),unlock_scope 默认为 group(支持 group、wave);groups 为必须项,元素对象可包含 wave_id、platform、sys_logistics_code、order_ids 等字段。", "返回说明:返回 summary(解锁统计)、unlocked_order_ids、unlocked_orders、ext.missing_wave_ids、ext.filtered_wave_ids 等字段。", "实现参考:app/service/systemMethods/order/print.js 与 app/service/systems/order_print.js 的 unlockWavePlatformPrintDataByGroup 实现,相关单元测试位于 test/app/controller/system.order.print.unlockByGroup.test.js 与 test/app/service/systems/order_print.unlockWavePlatformPrintDataByGroup.test.js。" ], "type": "updated" }, { "version": "2026.05.28-system-03", "date": "2026-05-28", "summary": "新增 order.updateExpressWeighingWeight 方法文档并补充单/多运单称重写入规则", "methods": [ "order.updateExpressWeighingWeight" ], "notes": [ "新增 order.updateExpressWeighingWeight 入参说明:order_id、waybill_code、weighing_weight。", "明确规则:单运单订单忽略 waybill_code 并直接更新唯一运单;多运单订单必须传 waybill_code 且需匹配订单下运单。", "补充成功返回字段:order_id、waybill_code、weighing_weight。", "补充错误码:400(参数校验与多运单缺失运单号)、404(运单记录不存在或未匹配)、500(模型未初始化或更新失败)。", "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改业务代码。" ], "type": "added", "module": "order.index" }, { "version": "2026.05.28-system-01", "date": "2026-05-28", "summary": "新增包材相关 methods(create/update/delete/get),并提供 list 兼容说明", "methods": [ "setting.packageMaterial.create", "setting.packageMaterial.update", "setting.packageMaterial.delete", "setting.packageMaterial.get", "setting.packageMaterial.list" ], "notes": [ "实现参考:app/service/systems/setting/packageMaterial.js", "list 为兼容别名,内部转发至 get,建议新接入方改用 get" ], "type": "updated" }, { "version": "2026.05.28-system-04", "date": "2026-05-28", "summary": "Add packageSupplier methods (create/update/delete/get) with list alias note", "methods": [ "setting.packageSupplier.create", "setting.packageSupplier.update", "setting.packageSupplier.delete", "setting.packageSupplier.get", "setting.packageSupplier.list" ], "notes": [ "Reference implementation: app/service/systems/setting/packageSupplier.js", "list is a compatibility alias; prefer get" ], "type": "updated" }, { "version": "2026.05.28-system-05", "date": "2026-05-28", "summary": "新增 order.bindExpressPackageMaterial 方法文档,支持按订单运单绑定包材", "methods": [ "order.bindExpressPackageMaterial" ], "notes": [ "新增 order.bindExpressPackageMaterial 入参说明:order_id、waybill_code、package_material_code(均必填)。", "补充行为说明:按订单ID+运单号匹配 wms_order_express,按包材编码匹配包材并绑定 package_material_id 与 package_material_name_snapshot。", "补充成功返回字段:order_id、waybill_code、package_material_id、package_material_name_snapshot、package_material_code。", "补充错误码:400 参数错误、404 包材编码不存在、404 订单运单记录不存在、500 绑定包材失败。", "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改业务代码。" ], "type": "added", "module": "order.index" }, { "version": "2026.05.29-system-01", "date": "2026-05-29", "summary": "新增 order.export 与 order.exportTaskProgress:订单导出异步任务与进度查询", "methods": [ "order.export", "order.exportTaskProgress" ], "notes": [ "order.export:提交导出任务,入参支持 table_type/tableType(枚举 current/history/dispatch/outsourced,兼容订单模块别名)与 module/module_name,where/sort 语义与 order.list 一致。接口提交后立即返回 task_id,后台异步执行导出,导出进度与结果通过 order.exportTaskProgress 查询。", "order.exportTaskProgress:按 task_id 查询任务进度,返回 task_id、status、progress、current_count、total_count、message、error、download_url、update_time;任务上传完成后 download_url 返回可下载链接,未找到时 status=not_found。" ], "type": "added", "module": "order.index" }, { "version": "2026.05.30-system-01", "date": "2026-05-30", "summary": "新增 print.notifyLock(及 notify_lock 兼容别名),并补充 print.send 写入订单操作日志的行为说明", "methods": [ "print.notifyLock", "print.notify_lock", "print.send" ], "notes": [ "新增 print.notifyLock:入参支持 order_ids/orderIds、waveGroups、data.waveGroups(至少一类提供订单 ID);仅执行订单锁定流程,不发送打印任务;写打印任务日志 + 订单操作日志;返回 locked_count、order_ids_count、order_ids、source;错误:无有效订单ID(400)、锁定失败(500)。", "补充 print.send 文档:说明接口在执行打印任务记录的同时会写入订单操作日志(记录打印相关操作)。", "新增兼容别名 print.notify_lock:文档说明等价转调到 print.notifyLock。" ], "type": "updated", "module": "print" }, { "version": "2026.06.03-system-01", "date": "2026-06-03", "summary": "同步 pick.query 文档为 keyword 任务化语义并补充冲突错误码", "methods": [ "pick.query" ], "notes": [ "入参由 waybill_code/full_display 统一为 keyword(支持运单号或波次号)。", "成功返回调整为 task_id/status/tip,status 取值 existing 或 created。", "补充 409 冲突语义:波次已有他人活动任务时返回任务归属信息。" ], "type": "updated" }, { "version": "2026.06.03-system-02", "date": "2026-06-03", "summary": "更新 pick.wavePickTaskDetail:增加快递号/储位分配前置校验并返回 action+order_ids", "methods": [ "pick.wavePickTaskDetail" ], "notes": [ "新增前置校验:任务内若存在未分配快递号订单,返回 400,data.action=assign_express,data.order_ids 为未分配订单ID列表。", "新增前置校验:任务内若存在未分配储位订单,返回 400,data.action=assign_storage,data.order_ids 为未分配订单ID列表。", "保留原有权限校验与详情结构,仅补充分配校验失败分支的返回约定。" ], "type": "updated" }, { "version": "2026.06.03-system-03", "date": "2026-06-03", "summary": "更新 order.wave.batchList:新增同步状态输出与筛选 sync_assignment_status", "methods": [ "order.wave.batchList" ], "notes": [ "新增返回字段语义:list[].sync_assignment_status,取值为未同步/部分同步/已同步/同步异常。", "新增筛选入参 where.sync_assignment_status,支持 unsynced/partially_synced/synced 英文枚举。", "同步状态筛选规则与分配状态一致:error 并入 unsynced 过滤集合。" ], "type": "updated" }, { "version": "2026.06.03-system-04", "date": "2026-06-03", "summary": "更新拣货中间态流程文档:wavePickTaskDetail 增加完成标记,并新增中间态/完全提交接口", "methods": [ "pick.wavePickTaskDetail", "pick.wavePickTaskSubmit", "pick.wavePickTaskComplete" ], "notes": [ "更新 pick.wavePickTaskDetail 返回:新增 task.is_completed、task.progress(total_orders/picked_orders/pending_orders)以及顶层 is_completed。", "新增 pick.wavePickTaskSubmit:支持保存中间态 payload 到任务 ext_json.pick_intermediate,并返回当前完成状态与进度。", "新增 pick.wavePickTaskComplete:支持 mode=1 全部确认与 mode=2 部分确认(order_ids),返回 confirmed_order_ids 与最新进度。" ], "type": "updated" }, { "version": "2026.06.03-system-05", "date": "2026-06-03", "summary": "拣货车能力拆分为一级模块 pickCart:扫码查询、任务绑车、CRUD、编码查重", "methods": [ "pickCart.scan", "pickCart.bindTaskCart", "pickCart.create", "pickCart.update", "pickCart.delete", "pickCart.detail", "pickCart.list", "pickCart.codeDuplicateCheck" ], "notes": [ "拣货车能力独立为一级模块 pickCart,不再挂在 pick 模块下。", "新增 pickCart.scan:PDA 按 cart_code 扫码查询拣货车信息,用于进入任务绑定流程。", "新增 pickCart.bindTaskCart:支持按 cart_id/cart_code 将拣货车绑定到指定拣货任务,若车已绑定其他活动任务则返回冲突。", "新增 pickCart.create/pickCart.update/pickCart.delete/pickCart.detail/pickCart.list:补齐拣货车增删查改与分页查询能力。", "新增 pickCart.codeDuplicateCheck:支持 exclude_cart_id 排除自身,供编辑场景做非自身重复校验;拣货车编码在当前仓库内不可重复。" ], "type": "updated" }, { "version": "2026.06.03-system-06", "date": "2026-06-03", "summary": "更新 order.wave.batchList:新增 only_todo、复核状态聚合与复核筛选", "methods": [ "order.wave.batchList" ], "notes": [ "新增入参 only_todo(默认 0):传 1/true 时仅返回仍有未复核订单的波次(unreviewed_order_count > 0)。", "新增返回字段:list[].unreviewed_order_count(未复核订单数)与 list[].review_assignment_status(未复核/部分复核/已复核)。", "新增 where.review_assignment_status 筛选,支持 unreviewed/partially_reviewed/reviewed 英文枚举。" ], "type": "updated", "module": "order.wave" }, { "version": "2026.06.04-system-01", "date": "2026-06-04", "summary": "裁剪 pick.wavePickTaskDetail 返回:团购小波次(pick_mode=1)不返回 picking_details 字段以减少带宽", "methods": [ "pick.wavePickTaskDetail" ], "notes": [ "在 picking_details 字段 description 中补充:当 pick_mode=1(团购小波次)时该字段不返回,减少带宽浪费;其他 pick_mode(2/3/4/5)正常返回 picking_details。", "在接口 description 中补充该裁剪行为的说明。", "picking_summary、picking_view、boxes 等字段不受影响,pick_mode=1 时仍正常返回。" ], "type": "updated" }, { "version": "2026.06.04-system-02", "date": "2026-06-04", "summary": "完善 index.getPlatformList 文档:补充入参 systemOnly/full、响应字段及错误码 500", "methods": [ "index.getPlatformList" ], "notes": [ "补充入参说明:systemOnly(可选,支持 is_system 别名,真值识别 true/1/'1'/'true')、full(可选,真值识别同上,为 true 时返回全量表字段与 route_platform_code/platid 等扩展信息)", "补充响应 data 数组每项字段:code、name、value、label、platform_code、platform_name、default_express_interface、is_system_setting、id(仅仓库自定义项)、alias(仅仓库自定义项)、full 模式扩展字段说明", "说明合并逻辑:系统平台在前,仓库自定义在后,同 code 仅保留首条(系统优先);systemOnly=true 仅返回系统平台", "补充缓存策略:优先读缓存,key 格式为 platform:list:{warehouseId}[:full] 或 platform:list:system[:full]", "补充错误码 500:数据库或缓存访问异常", "仅文档更新,不修改任何业务实现" ], "type": "updated", "module": "index" }, { "version": "2026.06.04-system-03", "date": "2026-06-04", "summary": "作废 order.pendingOrder.downloadCreateTemplate 和 order.pendingOrder.importOrdersFromExcel", "methods": [ "order.pendingOrder.downloadCreateTemplate", "order.pendingOrder.importOrdersFromExcel" ], "notes": [ "order.pendingOrder.downloadCreateTemplate:下载订单导入模板方法已从代码中移除,标记为 deprecated。", "order.pendingOrder.importOrdersFromExcel:从 Excel 导入订单方法已从代码中移除,标记为 deprecated。", "两个方法的文档条目保留在 methods/system.json 中,仅追加 status: 'deprecated' 与 description 中的'(已作废)'标记,未删除。" ], "type": "deprecated" }, { "version": "2026.06.05-system-01", "date": "2026-06-05", "summary": "新增 storeWarehouse.store.openAccount 接口:仓库代货主一键开户(合并注册账号+创建货主+签约)", "methods": [ "storeWarehouse.store.openAccount" ], "notes": [ "新增 storeWarehouse.store.openAccount 方法,归属货主-仓库签约模块(storeWarehouse.store)。", "接口同时完成账号注册、货主创建和仓库-货主签约,一步完成开户全流程。", "当前主体必须为仓库角色(Authorization header 中携带的 token 对应仓库用户)。", "必填参数:username(登录账号)、password(初始密码)、company_name(公司全称)、business_license(营业执照号)、contact_person(联系人)、contact_phone(联系电话)。", "响应返回新创建的 store_id、account_id、contract_id、company_name、username、role_id。" ], "type": "added", "module": "storeWarehouse" }, { "version": "2026.06.05-system-02", "date": "2026-06-05", "summary": "优化 storeWarehouse.store.openAccount 必填参数:password 改为随机生成、business_license 和 contact_phone 改为可选,必填仅剩 username/company_name/contact_person 三个", "methods": [ "storeWarehouse.store.openAccount" ], "notes": [ "password:由必填改为可选,不传时自动随机生成 12 位密码", "business_license:由必填改为可选", "contact_phone:由必填改为可选" ], "type": "updated" }, { "version": "2026.06.05-system-03", "date": "2026-06-05", "summary": "saveApiConfig 增加 callback_url 参数,支持配置 API 回调通知地址", "methods": [ "storeWarehouse.store.saveApiConfig" ], "notes": [ "新增 callback_url 参数:OpenAPI 类型接口支持配置回调通知 URL", "兼容别名 callbackUrl,最大 500 字符", "存入 wms_api_app.callback_url 字段" ], "type": "modified" }, { "version": "2026.06.05-system-04", "date": "2026-06-05", "summary": "createOrder 入参 item_code 改为 item_id,province/city/area 改为必填", "methods": [ "order.pendingOrder.createOrder" ], "notes": [ "items[].item_code → items[].item_id:改用商品主键直接匹配,不依赖外部系统商品推送", "province/city/area 新增必填校验,空值返回 400", "item_name 优先外部传入,其次从 StockStore 缓存获取,最后兜底'商品'" ], "type": "modified" }, { "version": "2026.06.05-system-05", "date": "2026-06-05", "summary": "新增 order.pendingOrder.parseAddress 智能地址解析方法", "methods": [ "order.pendingOrder.parseAddress" ], "notes": [ "使用 DeepSeek AI 模型将非结构化地址字符串解析为省/市/区/详细地址/收件人/手机号", "解析结果可直接用于 createOrder 的 receiverInfo 字段", "DeepSeek API Key 通过 DEEPSEEK_API_KEY 环境变量配置" ], "type": "added" }, { "version": "2026.06.05-system-06", "date": "2026-06-05", "summary": "waveStrategyUpdate/waveStrategyCreate 新增 wave_prefix 参数", "methods": [ "order.wave.waveStrategyUpdate", "order.wave.waveStrategyCreate" ], "notes": [ "新增 wave_prefix 波次编号前缀字段,最多 5 个字符,为空存 null" ], "type": "modified" }, { "version": "2026.06.05-system-07", "date": "2026-06-05", "summary": "parseAddress 响应新增 town 字段(乡镇/街道)", "methods": [ "order.pendingOrder.parseAddress" ], "notes": [ "响应 data 中新增 town 字段,返回 AI 解析出的乡镇/街道名称" ], "type": "modified" }, { "version": "2026.06.05-system-08", "date": "2026-06-05", "summary": "为 order.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-09", "date": "2026-06-05", "summary": "为 order.reviewOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.reviewOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-10", "date": "2026-06-05", "summary": "为 order.pendingOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.pendingOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-11", "date": "2026-06-05", "summary": "为 order.outboundOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.outboundOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-12", "date": "2026-06-05", "summary": "为 order.expectionOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.expectionOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-13", "date": "2026-06-05", "summary": "为 order.entrustOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.entrustOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-14", "date": "2026-06-05", "summary": "为 order.deliveryOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.deliveryOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-15", "date": "2026-06-05", "summary": "为 order.deliveryExpectionOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.deliveryExpectionOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.05-system-16", "date": "2026-06-05", "summary": "为 order.archiveOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", "methods": [ "order.archiveOrder.list" ], "notes": [ "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" ], "type": "updated" }, { "version": "2026.06.06-system-01", "date": "2026-06-06", "summary": "恢复 order.pendingOrder.downloadCreateTemplate:方法仍存在于代码中,取消 deprecated 标记,完善文档描述", "methods": [ "order.pendingOrder.downloadCreateTemplate" ], "notes": [ "order.pendingOrder.downloadCreateTemplate 方法在 pendingOrder.js 中仍存在(line 2099),此前被误标记为 deprecated。", "取消 status: 'deprecated' 标记,恢复为 active 状态。", "移除 description 中的'(已作废)'后缀。", "完善 description:说明模板包含必填列(橙色背景)、可选列(灰色背景)、示例数据行和填写说明工作表。", "补充 response 字段说明:filename 和 mime 为固定值。" ], "type": "updated" }, { "version": "2026.06.07-system-01", "date": "2026-06-07", "summary": "order.pendingOrder.createOrder 文档新增 shop_nick 入参(店铺名称,可选,最大长度200)", "methods": [ "order.pendingOrder.createOrder" ], "notes": [ "在 order.pendingOrder.createOrder 的 request params 中新增 shop_nick 字段(string,非必填),对应代码实现中 shopNick: String(requestData.shop_nick || requestData.shopNick || '').trim()。", "shop_nick 已在 COPY_FIELDS 白名单中(pendingOrder.js L1738),仅文档缺失,本次为补齐。" ], "type": "updated" }, { "version": "2026.06.07-system-02", "date": "2026-06-07", "summary": "order.pendingOrder.downloadCreateTemplate:模板新增 shop_nick 列(店铺名称),store_id/province/city/area 标注为非必填", "methods": [ "order.pendingOrder.downloadCreateTemplate" ], "notes": [ "模板新增 shop_nick(店铺名称)列,非必填。", "明确标注 store_id(货主ID)、province(省份)、city(城市)、area(区/县)为非必填列。", "响应文档中新增 shop_nick 字段说明。" ], "type": "updated" }, { "version": "2026.06.07-system-03", "date": "2026-06-07", "summary": "新增 order.pendingOrder.updateAddress:批量修改待处理订单收件地址,限制未分配快递时可用", "methods": [ "order.pendingOrder.updateAddress" ], "notes": [ "新增 method:order.pendingOrder.updateAddress,免权限(isNeedAuth=false),需登录", "功能:批量修改待处理订单收件地址(name/mobile/tel/zip_code/province/city/area/town/detail_address)", "约束:仅 post_status='none'(未分配快递)的订单可修改;至少提供一个有效地址字段", "响应:返回 updated_count(实际更新行数)和 ids(请求订单ID数组)" ], "type": "added" }, { "version": "2026.06.07-system-04", "date": "2026-06-07", "summary": "order.wave.wavePickTaskCancel 扩展可取消状态至 status=3,并新增拣货状态回退", "methods": [ "order.wave.wavePickTaskCancel" ], "notes": [ "可取消状态从 [0,1,2] 扩展为 [0,1,2,3](status=3 已完成现在也可取消)", "取消 status=2(待复核)或 status=3(已完成)任务时,自动回退 wms_wave_pick_task_order.pick_status(1→0)和 order_delivery.pick_status(fin→padding)", "错误码 400 描述同步更新,补充 403 错误码说明" ], "type": "updated" }, { "version": "2026.06.07-system-05", "date": "2026-06-07", "summary": "order.wave.wavePickTaskList 响应新增 cart_name 字段(拣货车名称)", "methods": [ "order.wave.wavePickTaskList" ], "notes": [ "响应 list 子项新增 cart_name(string):通过 current_cart_id LEFT JOIN wms_pick_cart 表获取,未绑定拣货车时为空字符串。" ], "type": "updated" }, { "version": "2026.06.07-system-06", "date": "2026-06-07", "summary": "pick.wavePickTaskComplete 新增后台抓取任务(source=2)拣货车绑定校验,未绑定拣货车时拒绝提交", "methods": [ "pick.wavePickTaskComplete" ], "notes": [ "description 补充说明:后台抓取创建的任务(source=2)必须先绑定拣货车才能提交,否则返回 400。", "errors 中 400 错误补充:后台抓取任务(source=2)未绑定拣货车时拒绝提交,错误消息为\"后台抓取任务必须先绑定拣货车才能提交\"。" ], "type": "updated" }, { "version": "2026.06.07-system-07", "date": "2026-06-07", "summary": "order.wave.batchList 文档修正:移除代码中不存在的 sync_assignment_status 引用", "methods": [ "order.wave.batchList" ], "notes": [ "从 where 描述中移除 sync_assignment_status(代码 buildBatchListWhereClause allowedFields 中不存在该字段,BATCH_LIST_ASSIGNMENT_FILTER_SCHEMAS 中也无 review 之外的同步类型)。", "从 response list 描述中移除 sync_assignment_status(代码响应映射中仅返回 storage/express/print/review 四种 assignment_status,无 sync_assignment_status)。", "v2026.06.03-system-03 变更记录中声称新增的 sync_assignment_status 实际从未在代码中实现,本次仅为文档修正,不涉及代码变更。" ], "type": "updated", "module": "order.wave" }, { "version": "2026.06.07-system-08", "date": "2026-06-07", "summary": "order.recheckOrder.confirmRecheck 补充后置行为说明:波次任务全部复核完成后自动解绑车任务", "methods": [ "order.recheckOrder.confirmRecheck" ], "notes": [ "在 description 中补充:确认复核后,若该订单所属波次拣货任务下所有订单均已复核完成,则自动解绑车任务。解绑操作包括:清空 wms_wave_pick_task 的 current_cart_id/current_cart_code_snapshot、停用 wms_pick_task_cart_binding(is_active=0 并记录解绑人和时间)、释放 wms_pick_cart(清空 current_task_id/bind_user_id)。", "解绑失败仅记录 warn 日志,不影响复核主流程。", "入参和返回结构未变,仅补充行为说明。" ], "type": "updated" }, { "version": "2026.06.07-system-10", "date": "2026-06-07", "summary": "移除 order.wave.groupFetch / singleFetch / fetch 响应中已废弃的 auto_fetch_disabled_marker 字段", "methods": [ "order.wave.groupFetch", "order.wave.singleFetch", "order.wave.fetch" ], "notes": [ "auto_fetch_disabled_marker 字段已从代码 submitFetchTask 响应中移除,文档同步删除该字段的描述。", "auto_fetch_disabled 字段同样已从代码中移除,且原文档中不存在此字段(仅有 auto_fetch_disabled_marker),无需额外处理。", "涉及 method:order.wave.groupFetch、order.wave.singleFetch、order.wave.fetch,均移除 response 中的 auto_fetch_disabled_marker 字段。" ], "type": "updated", "module": "order.wave" }, { "version": "2026.06.08-system-01", "date": "2026-06-08", "summary": "order.recheckOrder 模块 scanOrder 返回值重构为统一 list 输出,新增 confirmIntercept 与 recheckOrderList 接口", "methods": [ "order.recheckOrder.scanOrder", "order.recheckOrder.confirmIntercept", "order.recheckOrder.recheckOrderList" ], "notes": [ "scanOrder 返回值重构:统一使用 list 字段输出,新增 list_type 字段区分散单/团购模式。散单模式顶层新增 picker_id、picker_name、wave_id、wave_no、wave_type、pick_mode、strategy_id、strategy_name、total_orders、reviewed_count、unreviewed_count 等汇总字段。list 中每项新增 waybill_no、is_printed、is_reviewed、wave_index、intercept_status、store_remark、stock[](含 stock_id、item_code、item_name、sku_property、packing_requirements、barcodes[]、images[]、plan_qty、has_shared_barcode)。移除旧字段 logs、order、order_id(顶层)、waybill_no(顶层旧位置)、wave_match_view、items、expresses、cart_match_view。", "scanOrder 入参新增 wave_no / waveNo 支持波次号直接扫描匹配。", "新增 order.recheckOrder.confirmIntercept:确认拦截接口,将订单 intercept_status 更新为 intercepted_at_warehouse,返回 order_id、order_no、intercept_status、updated_at。", "新增 order.recheckOrder.recheckOrderList:复核订单列表查询,支持 list_type=single(散单)与 list_type=group(团购),均返回统一 list + pagination 结构。" ], "type": "updated" }, { "version": "2026.06.08-system-02", "date": "2026-06-08", "summary": "order.recheckOrder 模块新增 batchIntercept/batchInterceptTaskProgress,更新 scanOrder 团购模式响应结构,完善 confirmIntercept/recheckOrderList 文档", "methods": [ "order.recheckOrder.batchIntercept", "order.recheckOrder.batchInterceptTaskProgress", "order.recheckOrder.scanOrder", "order.recheckOrder.confirmIntercept", "order.recheckOrder.recheckOrderList" ], "notes": [ "新增 order.recheckOrder.batchIntercept:批量提交订单拦截(异步任务模式),入参支持 order_ids/orderIds/ids(订单ID数组,不再使用 wave_ids),将 intercept_status 设为 'requested',返回 task_id/warehouse_id/message/accepted_at。支持幂等提交与 warehouse_id 校验。", "新增 order.recheckOrder.batchInterceptTaskProgress:按 task_id 查询批量拦截任务进度,返回 state(submitted/running/success/failed/not_found)及对应的进度/计数/结果/错误字段。", "更新 order.recheckOrder.scanOrder 响应文档:团购模式(cart 命中)list 项新增 wave_id/wave_no/wave_type/wave_status/total_orders/processed_orders/creator/create_time/update_time/order_count/pick_mode/box_no/orders[] 等波次级别字段;补充散单无波次信息时的回退详情模式说明(detail/items/expresses/logs)。", "完善 order.recheckOrder.confirmIntercept:补充操作日志写入说明(ORDER_INTERCEPT_CONFIRM)及失败不影响主流程的容错描述。", "完善 order.recheckOrder.recheckOrderList:补充散单模式默认排除 pick_status='none' 和 recheck_status='fin' 的说明;团购模式 where 支持 wave_no(模糊搜索)的说明。" ], "type": "updated" }, { "version": "2026.06.08-system-03", "date": "2026-06-08", "summary": "移除 order.recheckOrder.batchIntercept 的 warehouse_id/warehouseId 入参,仓库ID统一使用当前上下文", "methods": [ "order.recheckOrder.batchIntercept" ], "notes": [ "移除入参 warehouse_id / warehouseId:仓库ID统一从当前上下文(ctx.user.store_id)获取,不再由调用方传入。", "移除对应错误码:warehouse_id 参数不合法(400)、warehouse_id 与当前仓库上下文不一致(400)。", "description 中补充说明仓库ID来源为当前上下文。", "response 中 warehouse_id 字段描述改为「取自当前上下文」。" ], "type": "updated" }, { "version": "2026.06.08-system-10", "date": "2026-06-08", "summary": "batchIntercept / batchInterceptTaskProgress 从 order.recheckOrder 迁移至 order.pendingOrder", "methods": [ "order.pendingOrder.batchIntercept", "order.pendingOrder.batchInterceptTaskProgress" ], "notes": [ "method 从 order.recheckOrder.batchIntercept 重命名为 order.pendingOrder.batchIntercept,分组从订单复核模块迁移至订单待处理模块", "method 从 order.recheckOrder.batchInterceptTaskProgress 重命名为 order.pendingOrder.batchInterceptTaskProgress,分组从订单复核模块迁移至订单待处理模块", "接口入参、响应、错误码均保持不变,仅变更 method 名称与所属分组" ], "type": "updated" }, { "version": "2026.06.08-system-04", "date": "2026-06-08", "summary": "新增 order.print.getOrderPrintData:按订单ID拉取打印数据,返回结构与 getWavePlatformPrintData 一致,不限制锁定状态", "methods": [ "order.print.getOrderPrintData" ], "notes": [ "新增 order.print.getOrderPrintData 接口文档,入参为 warehouse_id + order_ids(非空数组),返回与 getWavePlatformPrintData 结构一致的 waveGroups / summary / wave_ids / ext", "与 getWavePlatformPrintData 的区别:入参为 order_ids(非 wave_ids),ext 中返回 missing_order_ids / filtered_order_ids(非 missing_wave_ids / filtered_wave_ids)", "不限制打印锁定状态,所有订单(无论是否被锁定)统一返回打印数据", "自动过滤 post_status !== 'fin' 的订单(快递未完全分配),被过滤订单出现在 ext.filtered_order_ids" ], "type": "added", "module": "order.print" }, { "version": "2026.06.08-system-11", "date": "2026-06-08", "summary": "新增 order.pendingOrder 批量锁定/解锁/解除拦截及对应进度查询共 6 个异步任务接口文档", "methods": [ "order.pendingOrder.batchLock", "order.pendingOrder.batchLockTaskProgress", "order.pendingOrder.batchUnlock", "order.pendingOrder.batchUnlockTaskProgress", "order.pendingOrder.batchUnintercept", "order.pendingOrder.batchUninterceptTaskProgress" ], "notes": [ "新增 batchLock:批量锁定订单,lock_status → 'warehouse',操作日志 ORDER_LOCK,task_id 格式 order_lock_{warehouseId}_{timestamp}_{rand}。", "新增 batchLockTaskProgress:查询批量锁定进度,返回 locked_order_count / locked_order_ids 等。", "新增 batchUnlock:批量解锁订单,lock_status → 'none',操作日志 ORDER_UNLOCK,task_id 格式 order_unlock_{warehouseId}_{timestamp}_{rand}。", "新增 batchUnlockTaskProgress:查询批量解锁进度,返回 unlocked_order_count / unlocked_order_ids 等。", "新增 batchUnintercept:批量解除拦截订单,intercept_status → 'none',操作日志 ORDER_INTERCEPT_CANCEL,task_id 格式 order_unintercept_{warehouseId}_{timestamp}_{rand}。", "新增 batchUninterceptTaskProgress:查询批量解除拦截进度,返回 unintercepted_order_count / unintercepted_order_ids 等。", "以上 6 个接口均采用与已有 batchIntercept/batchInterceptTaskProgress 一致的异步任务模式:提交返回 task_id,进度查询返回 state + 进度字段。", "仅同步文档,不修改业务代码或实现。" ], "type": "added", "module": "order" }, { "version": "2026.06.08-system-12", "date": "2026-06-08", "summary": "更新 order.print.getOrderPrintData:移除锁定限制,所有订单统一返回打印数据,不再区分锁定/未锁定", "methods": [ "order.print.getOrderPrintData" ], "notes": [ "移除打印锁定限制:所有订单(包括已锁定)统一返回打印数据,不再区分锁定/未锁定状态", "移除 locked_count、locked_orders、locked_wave_groups 等锁定相关字段", "返回结构与 getWavePlatformPrintData 完全一致:summary / waveGroups / wave_ids / ext", "ext 中使用 missing_order_ids / filtered_order_ids(替代锁定相关字段),与代码实现完全对齐" ], "type": "updated", "module": "order.print" }, { "version": "2026.06.08-system-13", "date": "2026-06-08", "summary": "更新 order.print.getOrderPrintData:移除 warehouse_id 入参,仓库ID统一从当前上下文获取", "methods": [ "order.print.getOrderPrintData" ], "notes": [ "移除 warehouse_id / warehouseId 入参,仓库ID统一从 this.getContextWarehouseId() 获取", "同步移除 errors 中 warehouse_id 必填 相关错误码", "description 补充说明仓库ID从上下文获取,无需调用方传入", "params 仅保留 order_ids(非空数组),与代码 method 层 getOrderPrintData(data) 解构一致" ], "type": "updated", "module": "order.print" }, { "version": "2026.06.08-system-14", "date": "2026-06-08", "summary": "新增 order.recheckOrder.scanTask 接口文档,并为 scanOrder 响应补充 task_id 字段", "methods": [ "order.recheckOrder.scanTask", "order.recheckOrder.scanOrder" ], "notes": [ "新增 order.recheckOrder.scanTask:按拣货任务 ID 拉取复核数据,数据结构与 scanOrder 完全一致,用于前端刷新。入参为 task_id(必填,number),返回 match_type='task',散单模式(pick_mode 2/3/4)返回扁平订单列表,团购模式(pick_mode 1/5)返回分组波次列表。", "更新 order.recheckOrder.scanOrder 响应定义:补充 task_id 字段说明(散单有波次时由 buildSingleWaveScanView 返回,团单车号命中时由 cartMatchContext 返回)。", "仅同步文档,不修改任何业务代码或实现。" ], "type": "updated" }, { "version": "2026.06.08-system-15", "date": "2026-06-08", "summary": "新增 order.pendingOrder.manualWaybill 接口(手工录入运单号)", "methods": [ "order.pendingOrder.manualWaybill" ], "notes": [ "为待处理订单手动录入运单号,写入 wms_order_express 表", "仅允许 step 在 [1,2,3] 且 outbound_status 不为 'padding' 的订单操作", "免权限(isNeedAuth: false),需登录", "成功返回运单记录的 id、order_id、waybill_code、create_at" ], "type": "added" }, { "version": "2026.06.09-system-01", "date": "2026-06-09", "summary": "order.pendingOrder.updateAddress 新增 remark 字段:订单留言/备注批量覆盖,不受 post_status 限制", "methods": [ "order.pendingOrder.updateAddress" ], "notes": [ "在 params 中新增 remark 字段(string,可选,最大500字符),支持批量覆盖所选订单的 remark", "remark 更新不受 post_status 限制,可对所有订单生效(地址字段仍仅允许 post_status='none')", "更新 description 明确 remark 与地址字段的独立性", "更新 response 中 updated_count 说明:取地址更新行数与备注更新行数的最大值", "更新 errors 中缺少字段的错误描述,改为「至少需要提供一个地址字段或备注进行修改」", "业务代码已同步实现,本次仅同步文档" ], "type": "updated" }, { "version": "2026.06.09-system-02", "date": "2026-06-09", "summary": "order.updateExpressWeighingWeight 新增运单号模式文档:order_id=0 时从运单号反查,支持散单与团购批量两种返回结构", "methods": [ "order.updateExpressWeighingWeight" ], "notes": [ "order_id 参数说明补充:设为0时切换为运单号模式,需配合 waybill_code 使用。", "waybill_code 参数说明补充:运单号模式(order_id=0)下必填。", "description 更新:明确订单模式与运单号模式两种路径及团购波次批量行为。", "response 新增运单号散单场景字段(order_id、waybill_code、weighing_weight)与运单号团购批量场景字段(wave_no、business_key、weighing_weight、success_count)。", "errors 新增运单号模式相关错误码:运单号不存在(404)、运单号对应的订单不存在(404)、波次下未找到订单(404)、批量更新失败(500)。", "仅文档同步,不修改业务代码。" ], "type": "updated" }, { "version": "2026.06.09-system-03", "date": "2026-06-09", "summary": "order.updateExpressWeighingWeight 团购返回新增拆单汇总字段,移除 success_count/total_count", "methods": [ "order.updateExpressWeighingWeight" ], "notes": [ "团购批量模式 response 新增 total_weight(所有拆单重量累加)、split_count(waybill_code 非空的 business_key 数量)、splits(按 business_key 分组的拆单明细数组,每项含 business_key/weighing_weight/waybill_code)、store_name(货主名称)和 sys_logistics_name(系统快递名称)。", "移除 response 中的 success_count 与 total_count 字段,改为由 total_weight 和 split_count 提供汇总信息。", "更新 description 以反映团购模式返回拆单汇总结构。" ], "type": "updated" }, { "version": "2026.06.10-system-01", "date": "2026-06-10", "summary": "order.detail 接口文档:expresses 数组新增字段 weighing_weight、sys_logistics_code、sys_logistics_name、business_key、created_at", "methods": [ "order.detail" ], "notes": [ "expresses 数组新增字段:weighing_weight(称重重量,number|null)、sys_logistics_code(系统物流公司编码,string)、sys_logistics_name(系统物流公司名称,string)、business_key(业务标识,string)、created_at(创建时间戳毫秒,number|null)", "字段来源:getOrderExpressesByOrderId 方法中 sys_logistics_code/sys_logistics_name 取自订单表 sys_logistics_code/sys_logistics_name,其余字段取自 OrderExpress 表" ], "type": "updated" }, { "version": "2026.06.10-system-02", "date": "2026-06-10", "summary": "dashboard.order_trend 从 mock 数据改为查询真实数据库,按小时统计当日订单数与发货数,补充完整返回结构与错误说明", "methods": [ "dashboard.order_trend" ], "notes": [ "接口实现从 mock 静态数据改为查询真实数据库(wms_order_delivery 与 dispatch 表),数据实时反映仓库当日运营情况。", "订单筛选条件:step in [1,2,3],排除 outbound_status='padding' 和 status='cancel',统计 create_at 在今日 00:00 到当前时刻的订单,按 HOUR(create_at) 分组。", "发货筛选条件:dispatch_lane='m4',统计 delivery_time 在今日 00:00 到当前时刻的发货记录,按 HOUR(delivery_time) 分组。", "时段范围:从 08:00 到当前小时(最晚 23:00),若当前时间早于 08:00 则从 08:00 开始。", "返回新增 summary 汇总对象:total_orders(订单总数)、total_shipments(发货总数)、shipment_rate(发货率百分比)、peak_hour(峰值时段)、peak_orders(峰值订单数)。", "categories/orders/shipments 三个数组一一对应,提供按时段的订单与发货趋势数据,可直接用于前端折线图/柱状图渲染。", "需要登录(Authorization header),从 token 中获取 warehouseId;若缺少仓库上下文则返回 flag='fail'。" ], "type": "updated", "module": "dashboard" }, { "version": "2026.06.10-system-03", "date": "2026-06-10", "summary": "order.pendingOrder.manualWaybill 新增可选参数 logistics_interface_name 与响应字段 business_key/logistics_interface_name,补充行为说明", "methods": [ "order.pendingOrder.manualWaybill" ], "notes": [ "新增可选参数 logistics_interface_name(string,选填,trim 后为空则传 null)", "响应新增字段 business_key(number):同一订单下从已有最大值 +1 递增,无记录时从 1 开始", "响应新增字段 logistics_interface_name(string/null):写入的物流接口名称", "补充 description 行为说明:完成后自动更新 wms_order_delivery_* 表的 print_status 和 post_status 为 'fin'", "wms_order_express 表写入时 status 固定为 1,warehouse_id 从订单记录取" ], "type": "updated" }, { "version": "2026.06.10-system-04", "date": "2026-06-10", "summary": "stock.warehouse.import 新增 barcode(条码)字段支持", "methods": [ "stock.warehouse.import" ], "notes": [ "新增 barcode(条码)字段支持,支持别名:条码、bar_code、barCode、barcodeList、barcode_list、barcode。", "条码字段支持数组格式(如 [\"6901234567890\"])和分号分隔字符串格式(如 \"6901234567890;6901234567891\")。", "新建和更新路径均已支持条码导入,条码写入 wms_stock_barcodes 表。", "仅同步文档,不修改业务代码或实现。" ], "type": "updated" }, { "version": "2026.06.10-system-05", "date": "2026-06-10", "summary": "stock.warehouse.import 的 barcode 字段分隔符改为逗号,对齐 stock.warehouse.export 导出格式;仅接收字符串格式,不再支持数组", "methods": [ "stock.warehouse.import" ], "notes": [ "barcode 字段分隔符从分号 ; 改为逗号 ,", "barcode 字段仅接收字符串格式,不再支持数组格式", "格式示例:\"6901234567890,6901234567891\",与 stock.warehouse.export 导出格式一致" ], "type": "modified" }, { "version": "2026.06.13-system-01", "date": "2026-06-13", "summary": "setting.warehouse 的 auto_outbound_rules 新增 require_print 和 require_pick 两个可选条件字段(同步代码实现)", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "在 getSettings 响应和 saveSettings 入参中补充 subject_config.auto_outbound_rules 对象的完整字段文档(enabled、require_recheck、require_pack、require_weigh、require_sync、require_print、require_pick)。", "require_print:是否要求已打印(print_status=fin),默认 true。", "require_pick:是否要求已拣货(pick_status=fin),默认 true。", "该规则由自动出库定时任务 order_auto_outbound 消费,全部开启的条件均满足时自动标记待出库。" ], "type": "updated" }, { "version": "2026.06.13-system-02", "date": "2026-06-13", "summary": "order.recheckOrder.scanOrder 团购模式响应新增 orders_detail 字段,暴露非拦截订单的详细列表(含 is_printed、is_reviewed 等状态字段)", "methods": [ "order.recheckOrder.scanOrder" ], "notes": [ "团购模式(list_type='group')波次视图项新增 orders_detail 字段:非拦截订单详细列表,每项含 order_id、delivery_order_code、waybill_no、pick_status、is_printed(print_status === 'fin')、is_reviewed(recheck_status === 'fin')、recheck_status、shop_nick、items_count、wave_index、intercept_status", "orders_detail 与现有 order_ids(纯数字 ID 数组)并存,均在团购模式的波次视图项中返回", "orders_detail 仅在 list_type='group' 时返回,散单模式不受影响", "同步更新 list 字段 description 以反映 group 模式新增的 order_ids、orders_detail、stocks 字段" ], "type": "updated" }, { "version": "2026.06.13-system-03", "date": "2026-06-13", "summary": "新增批量快捷复核接口 batchQuickRecheck,支持批量订单 IDs 的前置条件检查(储位、快递、同步、拦截),自动完成拣货并标记复核,支持部分失败。拣货完成后同步更新 wms_wave_pick_task 状态", "methods": [ "order.recheckOrder.batchQuickRecheck" ], "notes": [ "新增 order.recheckOrder.batchQuickRecheck 方法", "入参 ids 支持数组或逗号分隔字符串", "响应包含 success/failed 列表及计数,failed 项含 reason 说明" ], "details": { "description": "包含拣货任务状态同步:全部拣完→任务状态=2(已完成),未全拣完→任务状态推进为1(拣货中)" }, "type": "added" }, { "version": "2026.06.14-system-01", "date": "2026-06-14", "summary": "新增 order.bindExpressPackageMaterialByWaybill 方法:支持仅凭运单号绑定包材,无需传入订单ID", "methods": [ "order.bindExpressPackageMaterialByWaybill" ], "notes": [ "新增 order.bindExpressPackageMaterialByWaybill 入参说明:waybill_code(运单号,必填)、package_material_code(包材编码,必填)。无需传入 order_id。", "成功返回字段:order_id、waybill_code、package_material_id、package_material_name_snapshot、package_material_code。", "错误码定义:400(参数错误)、404(运单号不存在 / 包材编码不存在)、500(绑定包材失败)。" ], "type": "added" }, { "version": "2026.06.15-system-01", "date": "2026-06-15", "summary": "order.detail / order.deliveryOrder.detail 的 expresses 数组新增包材字段", "methods": [ "order.detail", "order.deliveryOrder.detail" ], "notes": [ "expresses 数组每个元素新增 package_material_id(包材ID,number|null)和 package_material_name_snapshot(包材名称快照,string|null)字段。" ], "type": "updated" }, { "version": "2026.06.15-system-02", "date": "2026-06-15", "summary": "order.deliveryOrder.detail 的 expresses 数组新增包材字段", "methods": [ "order.deliveryOrder.detail" ], "notes": [ "expresses 数组每个元素新增 package_material_id(包材ID,number|null)和 package_material_name_snapshot(包材名称快照,string|null)字段。" ], "type": "updated" }, { "version": "2026.06.15-system-03", "date": "2026-06-15", "summary": "新增 setting.packageMaterial.search 方法:支持按关键字模糊搜索包材编码和名称", "methods": [ "setting.packageMaterial.search" ], "notes": [ "新增 setting.packageMaterial.search 入参 keyword(可选),为空返回前 50 条启用中包材,有值时对 material_code 和 material_name 做模糊匹配。", "返回包材数组,字段:id、material_code、material_name、material_type、spec、status。" ], "type": "added" }, { "version": "2026.06.16-system-01", "date": "2026-06-16", "summary": "新增 order.recheckOrder.queryRecheckOrderSingleList:散单复核列表接口,响应新增 items_weight(总重量g)和 weight_type(重量类型)字段", "methods": [ "order.recheckOrder.queryRecheckOrderSingleList" ], "notes": [ "新增方法 order.recheckOrder.queryRecheckOrderSingleList,为 recheckOrderList 散单模式的独立入口。", "响应 list 每项新增字段 items_weight (DECIMAL(10,2)):订单总重量(g),来自 wms_order.items_weight,为 null 时返回 null。", "响应 list 每项新增字段 weight_type (string):重量类型中文标签,来自 wms_order.weight_type 经 formatWeightTypeLabel 转换;取值:常规/轻货/重货/冷链(对应 DB 值 0/1/2/3)。" ], "type": "added", "module": "order.recheckOrder" }, { "version": "2026.06.16-system-02", "date": "2026-06-16", "summary": "为 order.wave.groupOrderFetchList / waveStrategyFallbackOrderList / singleOrderFetchList 响应新增 items_weight(总重量g)和 weight_type(重量类型)字段", "methods": [ "order.wave.groupOrderFetchList", "order.wave.waveStrategyFallbackOrderList", "order.wave.singleOrderFetchList" ], "notes": [ "order.wave.groupOrderFetchList:响应 list 每项新增 items_weight (number|null):订单总重量(g),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", "order.wave.waveStrategyFallbackOrderList:响应 list 每项新增 items_weight (number|null):订单总重量(g),来自 wms_order.items_weight;新增 weight_type (string):重量类型中文标签,取值:常规/轻货/重货/冷链(对应 DB 值 0/1/2/3)。", "order.wave.singleOrderFetchList:响应 list 每项新增 items_weight (number|null):订单总重量(g),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", "所有新增字段均为可选(required=false),为 null 时返回 null。" ], "type": "updated", "module": "order.wave" }, { "version": "2026.06.17-system-01", "date": "2026-06-17", "summary": "新增 order.pendingOrder.replenishmentDemand 分拣缺货补货需求计算接口文档", "methods": [ "order.pendingOrder.replenishmentDemand" ], "notes": [ "新增分拣缺货补货需求计算方法,用于计算待处理订单的SKU在分拣区与存货区的库存分布及补货缺口", "入参 order_ids/warehouse_id 均为可选;不传 order_ids 时自动查询当前仓库所有未完成储位分配的订单", "纯只读查询接口,不修改任何数据", "响应包含 list(明细)与 summary(汇总),其中 shortage = max(0, total_demand - pick_zone_quantity),replenishment_needed = min(shortage, storage_zone_quantity)" ], "type": "add", "module": "order.pendingOrder" }, { "version": "2026.06.17-system-02", "date": "2026-06-17", "type": "update", "module": "order.pendingOrder", "method": "order.pendingOrder.replenishmentDemand", "description": "移除 order_ids 参数,改为纯仓库级别计算,自动查询当前仓库所有未完成储位分配的订单" }, { "version": "2026.06.17-system-03", "date": "2026-06-17", "type": "update", "module": "order.pendingOrder", "method": "order.pendingOrder.replenishmentDemand", "description": "新增 is_true_shortage 字段标识真正缺货(两区均无库存),summary 新增 total_true_shortage_skus 统计" }, { "version": "2026.06.17-system-04", "date": "2026-06-17", "type": "migrate", "module": "storage.management", "summary": "从 order.pendingOrder.replenishmentDemand 迁移至 storage.management.replenishmentDemand(库存管理模块),原路径已删除,开发阶段无需兼容", "methods": [ "storage.management.replenishmentDemand" ], "notes": [ "将 replenishmentDemand 接口从 order.pendingOrder 模块迁移到新建的 storage.management 库存管理模块。", "旧条目 order.pendingOrder.replenishmentDemand 已从 order.pendingOrder 组中移除。", "开发阶段无需兼容旧路径。" ] }, { "version": "2026.06.17-system-05", "date": "2026-06-17", "type": "update", "module": "storage.management", "summary": "storage.management.replenishmentDemand 移除 warehouse_id 入参,仓库ID改为纯从用户上下文(ctx.user)获取,接口无需入参", "methods": [ "storage.management.replenishmentDemand" ], "notes": [ "移除 warehouse_id 入参,仓库ID改为纯从用户上下文(ctx.user)获取,接口无需入参" ] }, { "version": "2026.06.17-system-06", "date": "2026-06-17", "type": "update", "module": "storage.management", "method": "storage.management.replenishmentDemand", "description": "新增分页入参(pagination)、排序入参(sort,默认按 shortage DESC)、响应新增 replenishment_locations(存货区可补货库位,最多5条)、响应新增 pagination 分页信息" }, { "version": "2026.06.17-system-07", "date": "2026-06-17", "type": "update", "module": "storage.management", "summary": "replenishment_locations 新增 space_name 字段,优先取自定义名称(custom_name),无则回退库位编码(space_code)", "methods": [ "storage.management.replenishmentDemand" ], "notes": [ "在 replenishment_locations.children 中新增 space_name 字段(string, required),放在 space_code 之后、available_quantity 之前。", "space_name 取值逻辑:优先使用库位自定义名称 custom_name,若无自定义名称则回退为库位编码 space_code。" ] }, { "version": "2026.06.17-system-08", "date": "2026-06-17", "type": "update", "module": "storage.management", "summary": "合并 is_sufficient 和 is_true_shortage 为 replenishment_status 枚举字段(replenishable/true_shortage)", "methods": [ "storage.management.replenishmentDemand" ], "notes": [ "删除 is_sufficient(boolean)和 is_true_shortage(boolean)两个字段。", "新增 replenishment_status(string)枚举字段:replenishable=存货区足够覆盖缺口,移库可解决;true_shortage=存货区不足以覆盖缺口或两区均无库存,需采购。" ] }, { "version": "2026.06.18-system-01", "date": "2026-06-18", "summary": "入库单完成后异步匹配收货单并回传:completeEntry / entryorderConfirm 入库完成时自动匹配收货单,明细一致则按来源回传(奇门/OpenAPI),覆盖场景标记收货单部分入库;completeReceiving 完成后清除收货单缓存", "methods": [ "storage.entry.completeEntry", "storage.receiving.completeReceiving" ], "notes": [ "新增 app/service/systems/receiving_entry_match.js:入库单完成后异步匹配收货单并回传的核心服务,含 Redis 缓存收货单列表(TTL 300s)、remark 匹配收货单号、明细对比、奇门回传、OpenAPI 回调、部分入库标记等能力。", "storage.entry.completeEntry 完成后通过 setImmediate 异步触发 matchAfterEntryCompleted,不阻塞主流程。", "entry_order.js entryorderConfirm() 事务提交后(isFin 最终完成)同样异步触发匹配。", "storage.receiving.completeReceiving 完成后清除收货单 Redis 缓存(cache:receiving_orders:warehouse:{warehouseId}),确保下次匹配获取最新收货单列表。", "匹配规则:入库单 remark 包含收货单号 → 对比 SKU+数量 → 完全一致回传 / 收货单覆盖标记部分入库 / 其他不处理。", "回传路径:source_type=QM → 奇门 taobao.qimen.entryorder.confirm;source_type=API → OpenAPI 回调(entry_order_receiving_matched 事件)。" ], "type": "updated" }, { "version": "2026.06.18-system-02", "date": "2026-06-18", "summary": "新增 storage.receiving.manualMatchEntryOrder 接口", "methods": [ "storage.receiving.manualMatchEntryOrder" ], "notes": [ "新增 storage.receiving.manualMatchEntryOrder:手动匹配入库单与收货单,传入 receivingId 和 entryOrderId,复用异步匹配服务的明细对比和回传逻辑,同步返回匹配结果", "参数:receivingId (number, 必填)、entryOrderId (number, 必填)", "校验:入库单存在性、收货单存在性、同仓库校验", "返回 matchType (full_match/receiving_covers_entry/entry_exceeds_receiving/no_match)、comparisonResult、callbackSent、callbackResult、partialStorageMarked、entryOrder、receivingOrder" ], "type": "added", "module": "storage" }, { "version": "2026.06.18-system-03", "date": "2026-06-18", "summary": "新增 storage.receiving.getAvailableInboundQuantity 接口:按 stock_id 查询已审核收货单的可入库数量(actual_quantity - stored_quantity),排除未审核和已取消的收货单", "methods": [ "storage.receiving.getAvailableInboundQuantity" ], "notes": [ "新增 system method:storage.receiving.getAvailableInboundQuantity,按 stock_id 查询已审核收货单中各明细的可入库数量(actual_quantity - stored_quantity),仅返回尚有可入库余量的明细。", "实现文件:app/service/systemMethods/storage/receiving.js(包装层)、app/service/systems/storage/receiving.js(业务层)。", "接口无需鉴权(isNeedAuth=false),但需要登录(isNeedLogin=true)。", "入参 stock_id 为必填,对应 stock_warehouse.id;服务端从 ctx.user.store_id 获取仓库上下文。" ], "type": "added", "module": "storage" }, { "version": "2026.06.18-system-04", "date": "2026-06-18", "summary": "新增 storage.entry.bindReceivingDetails 接口和 wms_entry_receiving_binding 中间表:入库单明细可显式绑定收货明细(pending状态),提交入库时事务内完成双向扣减(stored_quantity/received_quantity),通过唯一约束和行锁防止超分和重复绑定。同时重构 completeEntry 调用链为 commitEntryWithBindings,无绑定时向后兼容。", "methods": [ "storage.entry.bindReceivingDetails", "storage.entry.completeEntry" ], "notes": [ "新增 storage.entry.bindReceivingDetails 方法:入库单明细绑定收货明细,pending 状态软绑定,每次调用清除旧 pending 绑定后创建新绑定。", "新增 wms_entry_receiving_binding 中间表(migration: 20260618150000-create-wms-entry-receiving-binding.js),用于记录入库明细与收货明细的绑定关系。", "重构 completeEntry 调用链:systemMethods 层 completeEntry 改为调用 commitEntryWithBindings,有绑定则事务内完成双向扣减(stored_quantity/received_quantity),无绑定时向后兼容仅变更入库单状态。", "通过数据库唯一约束和行锁(SELECT ... FOR UPDATE)防止超分和重复绑定。", "涉及文件: app/model/entry_receiving_binding.js, app/service/systems/storage/entry.js, app/service/systemMethods/storage/entry.js, database/migrations/20260618150000-create-wms-entry-receiving-binding.js" ], "type": "added", "module": "storage.entry" }, { "version": "2026.06.18-system-05", "date": "2026-06-18", "summary": "storage.entry.get 响应追加 pending_total/total_planned/bindings 字段,storage.receiving.getAvailableInboundQuantity 响应追加 pending_allocated_quantity 字段:前端可通过 get 查看入库明细的绑定状态,getAvailableInboundQuantity 的可用量已扣除全局 pending 绑定总量", "methods": [ "storage.entry.get", "storage.receiving.getAvailableInboundQuantity" ], "notes": [ "storage.entry.get:items 数组每项新增 pending_total(该入库明细当前 pending 绑定的总预分配数量)、total_planned(计划入库数量=count)、bindings(pending 绑定列表,每项含 id/entry_item_id/receiving_detail_id/allocated_quantity/status/receivingDetail 子对象)", "storage.receiving.getAvailableInboundQuantity:list 每项新增 pending_allocated_quantity(该收货明细在当前 stock_id 所有入库单中的 pending 绑定总量),available_quantity 计算已扣除该值" ], "type": "updated" }, { "version": "2026.06.18-system-06", "date": "2026-06-18", "summary": "bindReceivingDetails 重构为\"绑定即实收\"(received_quantity 在绑定时更新,不再等到 completeEntry),新增 unbindReceivingDetails 解绑接口(删除 pending 绑定并回退 received_quantity),commitEntryWithBindings 移除 received_quantity 更新逻辑", "methods": [ "storage.entry.bindReceivingDetails", "storage.entry.unbindReceivingDetails", "storage.entry.completeEntry" ], "notes": [ "storage.entry.bindReceivingDetails:改为绑定即实收,绑定成功后立即更新入库明细 received_quantity;重复调用时先回退旧绑定量再创建新绑定,避免重复累加。", "storage.entry.unbindReceivingDetails:新增解绑接口,删除该入库明细的所有 pending 绑定记录,并将 received_quantity 回退到绑定前的值;收货明细可用数量随绑定记录删除自动恢复。", "storage.entry.completeEntry:commitEntryWithBindings 中移除 received_quantity 更新逻辑(received_quantity 已在绑定时更新,completeEntry 仅完成收货单侧入库数量扣减和库存上架)。" ], "type": "updated" }, { "version": "2026.06.19-system-01", "date": "2026-06-19", "summary": "order.recheckOrder.scanOrder 响应 list[] 新增 items_weight(订单商品总重量g)和 suggested_package_material(推荐包材)字段", "methods": [ "order.recheckOrder.scanOrder" ], "notes": [ "响应 list 每项新增 items_weight (number|null):订单商品总重量(g),来源于 wms_order_delivery.items_weight。散单模式每个订单对象包含,团购模式每个波次对象包含(取波次内首个正常订单的重量,为 null 时返回 0)。", "响应 list 每项新增 suggested_package_material (object|null):推荐包材信息,根据订单商品结构(items_hash + items_crc)匹配 wms_package_material_item_relation 历史绑定记录,按 bind_count 降序取最优匹配。若 items_hash 为空或无匹配记录则为 null。包含子字段:id、code、name、spec、type、weight、length、width、height、bind_count。", "同步更新 method description 和 list 字段 description,补充新增字段的说明。" ], "type": "updated", "module": "order.recheckOrder" }, { "version": "2026.06.21-system-01", "date": "2026-06-21", "summary": "order.bindExpressPackageMaterialByWaybill:入参 package_material_code 改为 package_material_id,类型由 string 改为 number|string", "methods": [ "order.bindExpressPackageMaterialByWaybill" ], "notes": [ "入参字段名从 package_material_code 改为 package_material_id。", "入参类型从 string 改为 number|string,与代码 normalizePackageMaterialId 的实现一致。", "同步更新该方法 description 中'包材编码'为'包材ID'。" ], "type": "updated", "module": "order" }, { "version": "2026.06.21-system-comboGoods-01", "date": "2026-06-21", "summary": "新增 comboGoods 组合商品模块 5 个接口文档:list/create/update/delete/search", "methods": [ "comboGoods.list", "comboGoods.create", "comboGoods.update", "comboGoods.delete", "comboGoods.search" ], "notes": [ "comboGoods.list:组合商品列表查询(分页),支持按 combo_code/combo_name/status/warehouse_id 筛选,返回含 simpleNotation 和 nameNotation 简记字段", "comboGoods.create:创建组合商品(含明细一次性提交),校验 combo_code 唯一性、子商品有效性和货主一致性,事务保证原子写入", "comboGoods.update:编辑组合商品(含明细替换),支持部分字段更新,传入 items 则先删旧明细再插入新明细", "comboGoods.delete:软删除组合商品(status 置为 0)", "comboGoods.search:关键字搜索组合商品,模糊匹配 combo_code 或 combo_name,仅返回启用状态记录,上限100条", "数据表:wms_combo_goods(主表)+ wms_combo_goods_item(明细表);子商品校验依赖 wms_stock_warehouse 表", "代码文件:app/service/systems/comboGoods.js(业务逻辑层)+ app/service/systemMethods/comboGoods.js(接口包装层)", "isNeedAuth:list/search 无需鉴权,create/update/delete 需要鉴权" ], "type": "added", "module": "comboGoods" }, { "version": "2026.06.21-system-comboGoods-02", "date": "2026-06-21", "summary": "comboGoods 模块新增 custom_code(自定义编码)功能:create/update 支持传入 custom_code 并校验按货主唯一,list/search 返回新增 custom_code 字段,search 搜索范围扩展至 custom_code 且优先排列匹配项", "methods": [ "comboGoods.list", "comboGoods.create", "comboGoods.update", "comboGoods.search" ], "notes": [ "新增字段 custom_code(VARCHAR(64) NULL),仅做按货主唯一性校验(排除已删除记录),非全局唯一。", "wms_combo_goods 表新增索引 uk_store_custom_code(warehouse_id, custom_code)。", "comboGoods.create:新增可选入参 custom_code,如果非空则校验同货主非删除记录中 unique;返回新增 custom_code 字段。", "comboGoods.update:新增可选入参 custom_code,如果非空则校验同货主非删除记录中 unique(排除自身 id)。", "comboGoods.list:返回每条记录新增 custom_code 字段。", "comboGoods.search:搜索条件扩大为 custom_code LIKE / combo_code LIKE / combo_name LIKE,custom_code 匹配项按 ORDER BY CASE 排在前面;返回新增 custom_code 字段。" ], "type": "updated" }, { "version": "2026.06.21-system-comboGoods-03", "date": "2026-06-21", "summary": "stock.warehouse.search 新增 mode=\"combo\" 组合商品查询模式,新增 id/custom_code 参数,补充组合商品响应结构", "methods": [ "stock.warehouse.search" ], "notes": [ "新增入参 mode(查询模式,传 \"combo\" 时搜索组合商品),id(mode=combo 时按组合商品ID精确查询),custom_code(mode=combo 时按自定义编码模糊查询)", "原有 keyword 参数在 mode=combo 时模糊匹配 combo_code / combo_name / custom_code", "mode=combo 响应结构新增 combo_code、combo_name、custom_code、items(子商品数组含 item_goods_sku_id/item_quantity)、simpleNotation(stock_id|数量格式)、nameNotation(【数量】商品名称格式)", "mode=combo 时不返回 stock 模式特有的字段(item_code/goods_code/item_name/sku_property/stock_unit/quantity/locked_quantity/brand_name/item_type/barcodes/store_stock/效期字段/storage)", "with_stock 和 is_batch 参数在 mode=combo 时不生效" ], "type": "updated" }, { "version": "2026.06.22-system-wavePickTaskList-01", "date": "2026-06-22", "summary": "order.wave.wavePickTaskList 响应新增 wave_list 数组:每个拣货任务返回关联波次列表", "methods": [ "order.wave.wavePickTaskList" ], "notes": [ "wavePickTaskList 响应 list 每项新增 wave_list 数组字段,通过批量查询 wms_wave_pick_task_wave 表获取关联波次详情。", "wave_list 每项包含:wave_id(波次ID)、wave_no(波次号)、box_no(框号)、status(波次关联状态)、bind_time(绑定时间)、pick_time(拣货完成时间)。", "无需额外入参,默认对所有拣货任务返回 wave_list;查询为空时返回空数组 []。", "同步更新 methods/system.json 响应文档。" ], "type": "updated", "module": "order.wave" }, { "version": "2026.06.22-system-order-export-mode-01", "date": "2026-06-22", "summary": "order.export 新增 export_mode 参数:支持 waybill(默认,按运单展开)与 item(按商品明细展开)两种导出模式", "methods": [ "order.export" ], "notes": [ "新增入参 export_mode/exportMode,枚举值:waybill(默认)— 按运单号展开,每运单一组,items_detail 列汇总商品;item — 按商品明细展开,每商品一行,运单信息汇总填充。", "方法层(OrderIndexService.export)新增 export_mode/exportMode 解构并透传到 systems.orderExport.exportOrders。", "同步更新 methods/system.json 文档:description 补充 export_mode 说明,params 新增 export_mode/exportMode 条目。", "order.export 导出的列新增:业务类型、运单接口、包材ID、包材编码、包材名称。" ], "type": "updated", "module": "order.index" }, { "version": "2026.06.22-system-directInbound-01", "date": "2026-06-22", "summary": "新增 storage.directInbound 导入/PDA直接入库模块:getItems(获取入库信息)、addItem(增量添加商品)、commit(提交完成入库并回传)", "methods": [ "storage.directInbound.getItems", "storage.directInbound.addItem", "storage.directInbound.commit" ], "notes": [ "新增 storage.directInbound 模块,用于非收货单途径的导入/PDA 直接入库场景。", "storage.directInbound.getItems:根据入库单号获取入库明细及已有的导入/PDA 入库记录,返回每项的可入库余量。", "storage.directInbound.addItem:按 stock_id 增量添加导入/PDA 入库记录,累加超过该 stock_id 在入库单中的计划总量时拒绝。支持 import(导入)和 pda(PDA)两种方式。", "storage.directInbound.commit:提交确认完成入库,按实收数量写入 wms_storage 库存和 wms_storage_transaction 流水,同 stock_id 多条明细只写一次库存,更新入库单状态为 COMPLETED 并同步 sync_status=SUCCESS,异步触发奇门/API 回传(按实收数量回传)。不足量提交时未入库商品跳过。", "新增数据表 wms_inbound_direct_log(migration: 20260622100000-create-wms-inbound-direct-log.js):记录非收货单途径入库操作,含 warehouse_id、stock_id、quantity、inbound_type(import/pda)、entry_order_id、operator 等字段。模型文件:app/model/inbound_direct_log.js。", "新增操作日志:addItem 记录 DIRECT_INBOUND_ADD(异步),commit 记录 DIRECT_INBOUND_COMMIT(事务内)。commit 响应返回 order_status=COMPLETED 和 sync_status=SUCCESS。", "涉及文件:app/service/systems/inbound_direct_log.js(业务层)、app/service/systemMethods/storage/direct_inbound.js(包装层)、app/model/inbound_direct_log.js、database/migrations/20260622100000-create-wms-inbound-direct-log.js、methods/system.json(新增导入/PDA入库模块)。", "E2E 测试:test/e2e_direct_inbound.test.js(53项断言全覆盖)。" ], "type": "added", "module": "storage.directInbound" }, { "version": "2026.06.22-system-directInbound-02", "date": "2026-06-22", "summary": "storage.directInbound.addItem 新增批量模式(items 数组),getItems 响应 summary 新增 total_import/total_pda 分类型汇总", "methods": [ "storage.directInbound.addItem", "storage.directInbound.getItems" ], "notes": [ "addItem 新增批量模式:支持传入 items 数组一次添加多条商品,每项含 stock_id/quantity/inbound_type/remark。单条模式(stock_id/quantity/inbound_type 顶层字段)保持向后兼容。批量模式下所有商品共享同一个入库单状态校验,任一商品校验失败整批拒绝。", "addItem 批量模式响应结构:{ count, total_quantity, items: [...] },items 每项含 id/stock_id/quantity/inbound_type/plan_quantity/existing_before/existing_after/remaining。", "getItems 响应 summary 新增 total_import(导入入库总数)和 total_pda(PDA入库总数)字段。", "同步更新 methods/system.json 文档。" ], "type": "updated", "module": "storage.directInbound" }, { "version": "2026.06.22-system-directInbound-03", "date": "2026-06-22", "summary": "storage.directInbound 新增 space_id 库位支持:addItem 支持传入 space_id(单条和批量),commit 从入库记录取 space_id 写入 wms_storage 替代硬编码 1", "methods": [ "storage.directInbound.addItem", "storage.directInbound.commit", "storage.directInbound.getItems" ], "notes": [ "addItem 新增可选入参 space_id(单条模式顶层字段 / 批量模式 items[].space_id),指定存放库位ID,关联 wms_location_space.id。", "wms_inbound_direct_log 表新增 space_id 字段(migration: 20260622110000-add-space-id-to-wms-inbound-direct-log.js)。", "commit 从入库记录中取第一个非空 space_id 写入 wms_storage,无记录时兜底使用库位 1。", "getItems 响应中 direct_logs 每条记录包含 space_id 字段。", "同步更新 methods/system.json 文档及模型文件。" ], "type": "updated", "module": "storage.directInbound" }, { "version": "2026.06.23-system-01", "date": "2026-06-23", "summary": "入库单(wms_entry_order)新增 CREATED 状态:order_status ENUM 从 CREATING/PENDING/CONFIRMED/PARTIAL_RECEIVED/COMPLETED/CANCELLED 扩展为 CREATING/CREATED/PENDING/CONFIRMED/PARTIAL_RECEIVED/COMPLETED/CANCELLED;默认值从 PENDING 变更为 CREATED;validTransitions 增加 CREATED 节点(CREATED→PENDING/CANCELLED,CREATING→CREATED/CANCELLED)", "methods": [ "storage.entry.list", "storage.entry.get", "storage.entry.cancel", "storage.entry.completeEntry", "storage.entry.bindReceivingDetails" ], "notes": [ "Model 层:app/model/entry_order.js order_status ENUM 新增 CREATED,默认值从 PENDING 变更为 CREATED", "Service 层:app/service/systems/entry_order.js addOrder 创建后状态从 CREATING→CREATED,validTransitions 增加 CREATED 节点", "Service 层:app/service/systems/storage/entry.js createEntry 默认状态 PENDING→CREATED", "Service 层:app/service/systems/storage/inventory.js 快捷入库默认 CREATED", "文档同步:storage.entry.list where.order_status 枚举补充 CREATED;storage.entry.get description 补充 order_status 枚举含 CREATED;storage.entry.cancel 补充 CREATED 可作废说明;storage.entry.completeEntry/bindReceivingDetails 补充可操作状态含 CREATED" ], "type": "updated", "module": "storage.entry" }, { "version": "2026.06.23-system-02", "date": "2026-06-23", "summary": "入库单 CREATED 状态限制:CREATED 状态不允许绑定货物和完成入库,仅 PENDING/CONFIRMED/PARTIAL_RECEIVED 状态可操作", "methods": [ "storage.entry.cancel", "storage.entry.completeEntry", "storage.entry.bindReceivingDetails", "storage.entry.unbindReceivingDetails" ], "notes": [ "completeEntry / bindReceivingDetails / unbindReceivingDetails / commitEntryWithBindings 的可操作状态从原来的白名单(包含 CREATED)改为 PENDING / CONFIRMED / PARTIAL_RECEIVED,排除 CREATED。", "CREATED 状态仅允许确认入库(→PENDING)或作废(→CANCELLED)。", "storage.entry.cancel 补充明确 COMPLETED 状态不可作废,CREATED 可作废。", "同步更新对应 method 的 description、errors 描述。" ], "type": "updated", "module": "storage.entry" }, { "version": "2026.06.23-system-03", "date": "2026-06-23", "summary": "storage.entry.cancel:CONFIRMED(已确认)状态不再允许作废,仅 CREATED 和 PENDING 可作废", "methods": [ "storage.entry.cancel" ], "notes": [ "canCancel() 白名单移除 CONFIRMED,仅保留 CREATED 和 PENDING", "validTransitions 中 CONFIRMED 不再可转为 CANCELLED", "cancel() 方法新增 CONFIRMED 状态拦截,返回 400:已确认入库单不允许作废,请先完成收货", "PARTIAL_RECEIVED 仍可作废,COMPLETED 不允许作废(行为不变)", "更新 description 明确各状态可作废规则,errors 中补充 CONFIRMED 不可作废的说明" ], "type": "updated", "module": "storage.entry" }, { "version": "2026.06.23-system-04", "date": "2026-06-23", "summary": "入库单状态从 7 个简化为 5 个:移除 CONFIRMED 和 PARTIAL_RECEIVED,最终状态为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED;同步更新 storage.entry 所有 method 的状态枚举和错误信息描述", "methods": [ "storage.entry.list", "storage.entry.get", "storage.entry.cancel", "storage.entry.completeEntry", "storage.entry.bindReceivingDetails", "storage.entry.unbindReceivingDetails" ], "notes": [ "wms_entry_order.order_status ENUM 从 CREATING/CREATED/PENDING/CONFIRMED/PARTIAL_RECEIVED/COMPLETED/CANCELLED 简化为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED", "storage.entry.list: where.order_status 描述和 where 参数描述中的状态枚举同步更新", "storage.entry.get: entryOrder.order_status 描述同步更新", "storage.entry.cancel: 移除 PARTIAL_RECEIVED 可作废和 CONFIRMED 不可作废的描述,仅保留 CREATED 和 PENDING 可作废,COMPLETED 不可作废", "storage.entry.completeEntry: 可完成状态从 PENDING/CONFIRMED/PARTIAL_RECEIVED 改为仅 PENDING", "storage.entry.bindReceivingDetails: 可操作状态从 PENDING/CONFIRMED/PARTIAL_RECEIVED 改为仅 PENDING", "storage.entry.unbindReceivingDetails: 可操作状态从 PENDING/CONFIRMED/PARTIAL_RECEIVED 改为仅 PENDING", "cancel() 取消 CONFIRMED 状态拦截(状态已不存在),COMPLETED 拦截保持不变" ], "type": "updated" }, { "version": "2026.06.23-system-05", "date": "2026-06-23", "summary": "入库单状态语义调整:CREATED=已创建待审核,PENDING=已审核;同步更新 storage.entry 所有 method 的 description 中状态说明", "methods": [ "storage.entry.list", "storage.entry.get", "storage.entry.cancel", "storage.entry.completeEntry", "storage.entry.bindReceivingDetails", "storage.entry.unbindReceivingDetails" ], "notes": [ "CREATED 含义从\"已创建\"改为\"已创建待审核\"(需审核后才能绑定和完成入库)", "PENDING 含义从\"待收货/收货中\"改为\"已审核\"(审核通过,可绑定和完成入库)", "CREATED→PENDING 步骤语义:绑定审核", "addOrder() 新增可选参数 autoReview(boolean,默认 false),false 创建后状态 CREATED(需审核),true 创建后状态 PENDING(自动审核通过)", "快捷入库 quickPutaway 内部流程改为调用 addOrder({autoReview:true}) → bindReceivingDetails → commitEntryWithBindings,不再直接写库存,对外返回格式不变", "storage.entry.list / storage.entry.get description 中补充 CREATED/PENDING 语义说明", "storage.entry.cancel description 中补充可作废状态说明", "storage.entry.completeEntry description 中补充可完成状态说明", "storage.entry.bindReceivingDetails / storage.entry.unbindReceivingDetails description 中补充可绑定/解绑状态说明" ], "type": "updated" }, { "version": "2026.06.23-system-06", "date": "2026-06-23", "summary": "storage.inventory.quickPutaway description 更新:补充内部已改为走 addOrder→bind→commit 链路,不再直接写库存", "methods": [ "storage.inventory.quickPutaway" ], "notes": [ "快捷入库 quickPutaway 内部流程改为调用 addOrder({autoReview:true}) → bindReceivingDetails → commitEntryWithBindings,不再直接写库存,外部返回格式不变", "description 中补充内部调用链路说明" ], "type": "updated" }, { "version": "2026.06.23-system-07", "date": "2026-06-23", "summary": "storage.entry 大范围清理:删除 bindReceivingDetails/unbindReceivingDetails(明细级绑定已弃用),更新 completeEntry 为纯状态变更(不再做库存写入/异步匹配)", "methods": [ "storage.entry.bindReceivingDetails", "storage.entry.unbindReceivingDetails", "storage.entry.completeEntry" ], "notes": [ "storage.entry.bindReceivingDetails:已从代码中删除,明细级绑定收货单功能下线。库存写入统一由 storage.inventory.matchPutaway 完成。", "storage.entry.unbindReceivingDetails:已从代码中删除,明细级解绑功能下线。", "storage.entry.completeEntry:改为纯状态变更(PENDING → COMPLETED),不再做库存写入和异步匹配回调。库存写入统一由 storage.inventory.matchPutaway 完成。" ], "type": "updated" }, { "version": "2026.06.23-system-08", "date": "2026-06-23", "summary": "storage.inventory 清理:删除 quickPutaway(快捷入库已下线,统一由 matchPutaway 完成匹配入库)", "methods": [ "storage.inventory.quickPutaway" ], "notes": [ "storage.inventory.quickPutaway:已从代码中删除,快捷入库功能下线。请使用 storage.inventory.matchPutaway 替代。" ], "type": "removed" }, { "version": "2026.06.23-system-09", "date": "2026-06-23", "summary": "入库流程弃用清理:bindReceivingDetails/unbindReceivingDetails 标记为已删除并补充弃用原因,completeEntry 明确不涉及库存写入", "methods": [ "storage.entry.bindReceivingDetails", "storage.entry.unbindReceivingDetails", "storage.entry.completeEntry" ], "notes": [ "storage.entry.bindReceivingDetails 与 storage.entry.unbindReceivingDetails 已从代码中移除,入库单与收货单关系改为 wms_entry_order_receiving 主表级关联,不再需要逐明细绑定/解绑。", "wms_entry_receiving_binding 表不再写入新数据。", "storage.entry.completeEntry 仅做状态变更(PENDING→COMPLETED),库存写入统一由 storage.inventory.matchPutaway 完成。", "commitEntryWithBindings(内部方法)不再使用,库存写入统一走 matchPutaway 链路。" ], "type": "updated" }, { "version": "2026.06.23-system-10", "date": "2026-06-23", "summary": "quickPutaway 弃用说明完善:明确替代方案为 matchPutaway;matchPutaway 标明为目前唯一库存写入入库链路", "methods": [ "storage.inventory.quickPutaway", "storage.inventory.matchPutaway" ], "notes": [ "storage.inventory.quickPutaway 已从代码中移除,替代方案为 storage.inventory.matchPutaway(支持多收货单+多入库单批量匹配入库)。", "storage.inventory.matchPutaway 是目前唯一的库存写入入库链路,入库单状态变更由 storage.entry.completeEntry 单独处理。", "本次为文档补充说明,不涉及代码变更。" ], "type": "updated" }, { "version": "2026.06.23-system-11", "date": "2026-06-23", "summary": "删除 storage.receiving.getAvailableInboundQuantity:该方法依赖已弃用的 wms_entry_receiving_binding 明细绑定表,已从代码中移除", "methods": [ "storage.receiving.getAvailableInboundQuantity" ], "notes": [ "该方法原用于按 stock_id 查询已审核收货单中各明细的可入库数量(actual_quantity - stored_quantity - pending_allocated_quantity)。", "由于 wms_entry_receiving_binding 明细绑定表已弃用,入库单与收货单的关联改为通过 wms_entry_order_receiving 主表级关联,该查询方法不再适用。", "替代方案:使用 storage.entry.get 查询入库单详情,通过顶层 receivingBindings 获取关联的收货单信息。" ], "type": "removed" }, { "version": "2026.06.23-system-12", "date": "2026-06-23", "summary": "storage.entry.get 响应结构变更:不再返回 items[].bindings(明细级绑定),改为返回顶层 receivingBindings(主表级关联收货单信息)", "methods": [ "storage.entry.get" ], "notes": [ "移除 items[].bindings(明细级绑定,原基于 wms_entry_receiving_binding 表),该绑定表已弃用。", "新增顶层 receivingBindings(wms_entry_order_receiving 主表级关联),每项含 id/receiving_id/receiving(含 id/receiving_number/status/storage_status/created_at)。", "items 中保留 external_item_code/external_item_id/warehouse_item_code/warehouse_item_name/warehouse_item_spec 等扁平化字段。", "响应结构变更与 storage.directInbound.getItems 的返回结构对齐,后者同样使用顶层 receivingBindings。" ], "type": "modified" }, { "version": "2026.06.23-system-13", "date": "2026-06-23", "summary": "新增 storage.entry.* 下 4 个 DirectInbound 方法:getDirectInboundItems、addItem、commit、removeItem,原 storage.directInbound.* 方法保留向后兼容并标记 deprecated", "methods": [ "storage.entry.getDirectInboundItems", "storage.entry.addItem", "storage.entry.commit", "storage.entry.removeItem" ], "notes": [ "storage.entry.getDirectInboundItems:获取入库单的导入/PDA 入库信息,参数与响应格式同原 storage.directInbound.getItems", "storage.entry.addItem:按商品增量添加导入/PDA 入库记录(支持单条和批量),参数与响应格式同原 storage.directInbound.addItem", "storage.entry.commit:提交确认完成导入/PDA 入库,按实收数量写入库存并异步回传奇门/API,参数与响应格式同原 storage.directInbound.commit", "storage.entry.removeItem:移除一条导入/PDA 入库记录,参数与响应格式同原 storage.directInbound.removeItem", "底层 inbound_direct_log.js 实现不变,仅入口从 storage.directInbound 模块迁入 storage.entry 模块" ], "type": "added" }, { "version": "2026.06.23-system-14", "date": "2026-06-23", "summary": "storage.directInbound.* 下 4 个方法标记 deprecated,指向 storage.entry.* 下对应新方法", "methods": [ "storage.directInbound.getItems", "storage.directInbound.addItem", "storage.directInbound.commit", "storage.directInbound.removeItem" ], "notes": [ "storage.directInbound.getItems → 替代方法 storage.entry.getDirectInboundItems", "storage.directInbound.addItem → 替代方法 storage.entry.addItem", "storage.directInbound.commit → 替代方法 storage.entry.commit", "storage.directInbound.removeItem → 替代方法 storage.entry.removeItem", "旧方法保留向后兼容,参数与响应格式不变,仅入口模块变更" ], "type": "deprecated" }, { "version": "2026.06.23-system-15", "date": "2026-06-23", "summary": "storage.inventory.matchPutaway 标记 deprecated,替代方案为 storage.entry.commit", "methods": [ "storage.inventory.matchPutaway" ], "notes": [ "storage.inventory.matchPutaway 已弃用,请迁移至 storage.entry.commit", "commit 提供导入/PDA 入库完成确认功能,按实收数量写入库存并异步回传" ], "type": "deprecated" }, { "version": "2026.06.23-system-16", "date": "2026-06-23", "summary": "清理已弃用 method 条目:从 system.json 删除 storage.entry.bindReceivingDetails、storage.entry.unbindReceivingDetails、storage.inventory.matchPutaway 三个已从代码中移除的 method 文档条目", "methods": [ "storage.entry.bindReceivingDetails", "storage.entry.unbindReceivingDetails", "storage.inventory.matchPutaway" ], "notes": [ "storage.entry.bindReceivingDetails:已从代码中删除,明细级绑定收货单功能下线。入库单与收货单关系改为 wms_entry_order_receiving 主表级关联。", "storage.entry.unbindReceivingDetails:已从代码中删除,明细级解绑功能下线。", "storage.inventory.matchPutaway:已从代码中删除,匹配入库功能下线。替代方案为 storage.entry.commit。", "storage.inventory.quickPutaway:之前已标记 [已删除],本次确认条目保留(与 matchPutaway 同一 group,保留作为历史参考)。", "storage.entry.create / addDetail / deleteDetail / detailChange:systems 层方法已删除,但从未在 system.json 中暴露为 API method,无需文档变更。" ], "type": "removed" }, { "version": "2026.06.23-system-17", "date": "2026-06-23", "summary": "storage.entry.get 响应新增仓库库存、条码、入库进度字段", "methods": [ "storage.entry.get" ], "notes": [ "items 每项新增 warehouse_quantity(仓库库存总量)、warehouse_locked_quantity(锁定数量)、warehouse_is_batch_mgmt(是否批次管理)、warehouse_is_shelf_life_mgmt(是否效期管理)、warehouse_image_url(商品图片URL)、warehouse_is_images(是否有图片)", "items 每项新增 barcodes(条码列表,每项含 id/barcode/sku_property)", "items 每项新增 direct_inbound_quantity(导入/PDA已入库数量)、remaining_quantity(剩余可入库数量)", "同步更新 response 字段定义,将原有概要描述展开为逐字段说明", "仅文档同步,不改业务代码" ], "type": "updated", "module": "storage.entry" }, { "version": "2026.06.24-system-01", "date": "2026-06-24", "summary": "新增批量绑定入库单明细与收货单明细接口 storage.entry.bindReceivingDetails,支持明细级数量分配与部分成功", "methods": [ "storage.entry.bindReceivingDetails" ], "notes": [ "新增 storage.entry.bindReceivingDetails:批量绑定入库单明细与收货单明细,支持明细级数量分配与部分成功", "storage.entry.get 追加 available_receiving_details 字段加载可匹配的收货单明细" ], "type": "addition" }, { "version": "2026.06.24-system-02", "date": "2026-06-24", "summary": "storage.entry.bindReceivingDetails:response.failed 字段从简单 reason 描述升级为结构化错误返回(含 error_code、message、detail);同步更新 400 错误说明", "methods": [ "storage.entry.bindReceivingDetails" ], "notes": [ "response.failed 新增 items 定义,每项含 entry_item_id、receiving_detail_id、allocated_quantity、error_code、message、detail", "error_code 枚举:ENTRY_ITEM_NOT_FOUND、STOCK_NOT_FOUND、RECEIVING_DETAIL_MISMATCH、RECEIVING_DETAIL_NOT_FOUND、INSUFFICIENT_AVAILABLE_QUANTITY、ENTRY_ORDER_STATUS_INVALID", "400 错误说明更新:入库单状态不允许绑定时,所有 bindings 均返回 failed 且 error_code 为 ENTRY_ORDER_STATUS_INVALID" ], "type": "updated" }, { "version": "2026.06.24-system-03", "date": "2026-06-24", "summary": "新增 storage.entry.quickInbound 快捷直入/虚拟入库接口", "methods": [ "storage.entry.quickInbound" ], "notes": [ "新增 quickInbound 方法:入库单所有商品按明细数量一键直入虚拟库位(space_id=2),跳过收货/质检流程", "支持状态:CREATED、PENDING 状态的入库单可执行", "拒绝状态:CANCELLED(已作废)、COMPLETED(已完成)", "事务内操作:更新入库明细收货量、累加库存总量、写入库存流水、写入虚拟库位库存、变更入库单状态为 COMPLETED", "事务外异步回传奇门/API" ], "type": "addition" }, { "version": "2026.06.24-system-04", "date": "2026-06-24", "summary": "收窄 storage.entry.quickInbound 状态约束:仅允许 CREATED 状态执行快捷直入", "methods": [ "storage.entry.quickInbound" ], "notes": [ "收窄状态约束:仅允许 CREATED 状态执行快捷直入,PENDING 状态不再允许" ], "type": "updated" }, { "version": "2026.06.24-system-05", "date": "2026-06-24", "summary": "修正 storage.entry.quickInbound errors[4] message 以匹配代码实现:改为动态状态描述", "methods": [ "storage.entry.quickInbound" ], "notes": [ "errors[4].message 从「入库单状态不允许快捷直入(仅支持CREATED状态)」改为「入库单状态不允许快捷直入,当前状态:非CREATED(如PENDING等)」,反映代码中 `${entryOrder.order_status}` 动态模板特性" ], "type": "updated" }, { "version": "2026.06.24-system-06", "date": "2026-06-24", "summary": "新增入库单与收货单商品对照预览接口", "methods": [ "storage.entry.receivingCompare" ], "notes": [ "新增 storage.entry.receivingCompare 方法:给定入库单ID和收货单ID,返回入库商品与收货商品的逐行对照视图。", "comparison 列表中每项含 match_status(matched/entry_only),以及入库侧和收货侧的商品与数量信息。", "receiving_only 列表包含仅存在于收货单中的商品明细。", "summary 提供 total_entry_items、matched_items、entry_only_items、receiving_only_items 汇总统计。", "纯只读接口,不产生任何数据写入或状态变更。" ], "type": "addition" }, { "version": "2026.06.24-system-07", "date": "2026-06-24", "summary": "setting.warehouse 模块新增 7 个发件人信息字段到 subject_config", "methods": [ "setting.warehouse.getSettings", "setting.warehouse.saveSettings" ], "notes": [ "在 getSettings 的 response 中新增 subject_config.sender_name(发件人姓名)、sender_tel(发件人电话)、province_name(省份)、city_name(城市)、district_name(区/县)、town_name(镇/街道)、address(详细地址)共 7 个字段,均为可选字符串,默认空。", "在 saveSettings 的 params 中新增对应的 7 个入参字段,source 为 body.subject_config,均为可选字符串,默认空,并标注 maxLength。", "字段 key 与 store_warehouse.policy_config 中发件人字段命名完全一致,统一仓库级发件人默认值配置。", "getFieldMeta 接口无需修改文档——其返回的字段元信息由 WAREHOUSE_SETTING_FIELDS 定义在运行时自动生成,新增字段会随代码自动纳入返回列表。" ], "type": "updated", "module": "setting.warehouse" }, { "version": "2026.06.25-system-01", "date": "2026-06-25", "summary": "新增 storage.entry.bindReceiving 接口:将收货单绑定到入库单(主表级关联,不做明细数量分配)", "methods": [ "storage.entry.bindReceiving" ], "notes": [ "新增入库单与收货单的主表绑定接口,与已有的 storage.entry.bindReceivingDetails(明细级绑定)区分:bindReceiving 仅建立 wms_entry_order_receiving 主表关联,不做明细数量分配。", "入库单需为 CREATED 或 PENDING 状态;收货单需存在、同仓库且未取消。", "支持部分成功模式:逐条校验收货单,校验通过的建立绑定,不通过的返回 error_code 和 message。", "响应包含 success(成功列表)、failed(失败列表)、success_count、failed_count。" ], "type": "addition" }, { "version": "2026.06.25-system-02", "date": "2026-06-25", "summary": "storage.entry.bindReceiving:新增 OWNER_MISMATCH 错误码,用于收货单与入库单货主不一致校验", "methods": [ "storage.entry.bindReceiving" ], "notes": [ "在 storage.entry.bindReceiving 的 errors 数组中新增 OWNER_MISMATCH(收货单与入库单货主不一致)错误码。", "同步更新 response.failed.error_code 的枚举描述,补充 OWNER_MISMATCH。" ], "type": "updated", "module": "storage.entry" }, { "version": "2026.06.25-system-03", "date": "2026-06-25", "summary": "storage.entry.bindReceiving:新增收货单未审核错误码 RECEIVING_NOT_REVIEWED", "methods": [ "storage.entry.bindReceiving" ], "notes": [ "在 errors 数组中新增错误码 RECEIVING_NOT_REVIEWED(收货单未审核),用于标识绑定前收货单尚未完成审核的场景。", "同步更新 response.failed.items.properties.error_code.description,在可能值列表中补充 RECEIVING_NOT_REVIEWED。" ], "type": "updated" }, { "version": "2026.06.25-system-04", "date": "2026-06-25", "summary": "storage.entry.list 响应新增 receivingBindings 和 hasReceiving 字段,where 新增 hasReceiving 虚拟筛选条件", "methods": [ "storage.entry.list" ], "notes": [ "响应 list 数组每项新增 receivingBindings(收货单绑定列表,主表级关联)和 hasReceiving(是否存在收货单绑定,boolean)字段。", "入参 where 新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单,内部通过 wms_entry_order_receiving 表查询实现。", "同步更新 description 以说明 hasReceiving 虚拟筛选的使用方式。" ], "type": "updated" }, { "version": "2026.06.26-system-01", "date": "2026-06-26", "summary": "storage.entry.receivingCompare 支持多收货单对照预览", "methods": [ "storage.entry.receivingCompare" ], "notes": [ "支持多个收货单ID对照预览(新增 receiving_ids 数组入参,优先于 receiving_id 使用)", "入参 receiving_id 从 required 改为 optional,与 receiving_ids 二选一", "出参结构调整为 comparisons[] 数组(多收货单),新增 errors[] 和 total_summary", "向后兼容原 receiving_id 单值传参(底层自动转为单元素数组)", "新增 400 错误码:receiving_ids 或 receiving_id 必填", "移除 404 错误码:收货单不存在(已改为在 comparisons[]/errors[] 中以 status=error 形式返回)" ], "type": "enhancement" }, { "version": "2026.06.26-system-02", "date": "2026-06-26", "summary": "storage.receiving.getReceivingList 新增 filterDepleted 可选参数;storage.entry.receivingCompare 返回值 receiving_only 字段新增 receiving_allocated 和 receiving_available 说明", "methods": [ "storage.receiving.getReceivingList", "storage.entry.receivingCompare" ], "notes": [ "storage.receiving.getReceivingList:params 新增 filterDepleted(boolean, 默认 false),用于过滤掉无可再用量的收货单(所有明细已被其他入库单 committed 绑定占满)。", "storage.entry.receivingCompare:response 中 receiving_only 字段的 description 补充 receiving_allocated(已分配数量)和 receiving_available(可再用量)两个子字段说明。" ], "type": "updated" }, { "version": "2026.06.26-system-03", "date": "2026-06-26", "summary": "storage.receiving.getReceivingList:新增可选参数 entry_order_id,按入库单商品交集过滤收货单列表", "methods": [ "storage.receiving.getReceivingList" ], "notes": [ "新增可选参数 entry_order_id(number),传入入库单 ID 后只返回至少有一条明细的 system_product_id 在入库单明细中存在的收货单。", "与现有 filterDepleted 参数可组合使用,二者取交集。", "不传则不过滤,保持原有行为不变。" ], "type": "updated" }, { "version": "2026.06.27-system-01", "date": "2026-06-27", "summary": "新增 storage.entry.reviewEntry 接口:审核入库单(CREATED→PENDING),需绑定收货单", "methods": [ "storage.entry.reviewEntry" ], "notes": [ "新增入库单审核接口,支持 CREATED→PENDING 状态流转。", "审核前置条件:入库单必须已绑定收货单(EntryOrderReceiving 存在关联记录)。", "审核通过后写入操作日志(ENTRY_ORDER_REVIEW)。" ], "type": "added" }, { "version": "2026.06.29-system-01", "date": "2026-06-29", "summary": "storage.inventory.quickPutaway 重新实现:收货单快捷转入库单", "methods": [ "storage.inventory.quickPutaway" ], "notes": [ "此前已从代码中删除(2026.06.23-system-08),现由 wms-dev-agent 重新实现。", "核心流程:参数校验 → 加载收货单及明细 → 检查货主配置 policy_config.allow_receiving_quick_putaway → 按 stock_id(system_product_id)分组合并数量 → 创建入库单 SCRK(自动审批到 PENDING)→ 写入 wms_entry_order_receiving 主表级绑定 → 更新收货单 storage_status 为 partial → 更新收货单明细 storage_status/stored_quantity → 提交事务。", "前置条件:收货单状态为 completed 且 is_review=true(已审核),货主仓库签约配置 allow_receiving_quick_putaway=1。", "与旧实现的区别:不涉及 wms_entry_receiving_binding 明细级绑定,使用 wms_entry_order_receiving 主表级关联;直接创建入库单并写入绑定,不再走 matchPutaway 匹配链路。", "返回:entry_order_id、entry_order_code(SCRK 格式)、order_status(PENDING)、receiving_id、total_lines、total_quantity。" ], "type": "addition" }, { "version": "2026.06.29-system-02", "date": "2026-06-29", "summary": "storage.entry.list:quickWhere 搜索范围扩展,新增收货单 ID(receiving_id)支持 PDA 扫描托盘唛头搜索绑定的入库单", "methods": [ "storage.entry.list" ], "notes": [ "quickWhere 搜索字段新增 receiving_id(收货单 ID / 托盘唛头),通过 wms_entry_order_receiving 绑定表关联搜索。", "同步更新 description 和 where 参数的 description,明确 quickWhere 完整搜索字段列表:entry_order_code、purchase_order_code、supplier_name、store_name、warehouse_name、receiving_id。" ], "type": "updated", "module": "storage" }, { "version": "2026.06.29-system-03", "date": "2026-06-29", "summary": "新增 storage.receiving.scanDetail 接口:PDA 上架扫码定位收货明细", "methods": [ "storage.receiving.scanDetail" ], "notes": [ "新增 storage.receiving.scanDetail(PDA专用):通过 entry_order_id + barcode 扫码快速定位收货明细。", "搜索逻辑:纯数字 barcode 优先按明细 ID 精确匹配(托盘唛头),未命中则模糊匹配商品条码;非纯数字仅模糊匹配商品条码。", "入参:entry_order_id(必填 number)、barcode(必填 string)。", "出参:detail_id、receiving_id、barcode、product_name、actual_quantity、receiving_status。", "错误码:入库单不存在或无权访问、该入库单尚未关联收货单、未找到匹配的收货明细。" ], "type": "added" }, { "version": "2026.06.29-system-04", "date": "2026-06-29", "summary": "storage.receiving.scanDetail 响应结构从单条改为列表:返回 { list, total } 支持同一条码匹配多条明细", "methods": [ "storage.receiving.scanDetail" ], "notes": [ "响应结构变更:原返回 data.detail_id/data.receiving_id 等单条字段,现改为顶层 list 数组 + total 计数。", "同一条码可能匹配到多条收货明细(不同收货单的同一商品),以列表形式返回所有匹配结果。", "list 中每条明细包含 detail_id/receiving_id/barcode/product_name/actual_quantity/receiving_status。", "补充错误码:用户未绑定仓库、入库单ID/条码为空、未找到可用的收货明细、500服务器错误。", "PDA专用接口,description 更新说明匹配逻辑。" ], "type": "updated", "module": "storage.receiving" }, { "version": "2026.06.30-system-01", "date": "2026-06-30", "summary": "新增 storage.entry.containerList:PDA 上架时拉取入库单绑定收货单中指定商品的可用容器列表", "methods": [ "storage.entry.containerList" ], "notes": [ "新增接口 storage.entry.containerList,用于 PDA 上架场景拉取入库单已绑定收货单中指定 stock_id 的可用收货明细(容器)列表。", "入参:entry_order_id(入库单ID,必填)、stock_id(商品 stock_id,必填)。", "出参:data.list 返回可用明细列表,每项含 detail_id、receiving_id、barcode、product_name、actual_quantity、receiving_status;data.total 为总数。", "已绑定占用的收货明细(wms_entry_receiving_binding 中已有记录且未软删除)会被排除。", "PDA 专用接口,无需额外鉴权(isNeedAuth=false)。" ], "type": "added" }, { "version": "2026.06.30-system-02", "date": "2026-06-30", "summary": "storage.entry.addItem 入参变更:entry_order_code → entry_order_id(number);quantity 改为可选(传入 receiving_detail_id 时自动计算);新增 receiving_detail_id/allocated_quantity 参数支持 PDA 上架收货明细绑定模式;space_id 绑定模式下必填", "methods": [ "storage.entry.addItem" ], "notes": [ "入参 entry_order_code(string) → entry_order_id(number),与底层 inboundDirectLog.addItem 实现对齐", "quantity 改为可选:传入 receiving_detail_id 时自动从收货明细计算可用数量(actual_quantity - 已绑定数量)", "新增 receiving_detail_id 参数:PDA 上架绑定收货明细时传入,触发预占绑定(wms_entry_receiving_binding status=pending)", "新增 allocated_quantity 参数:预分配数量,默认等于 quantity", "space_id 在绑定模式下必填;非绑定模式可选(commit 时兜底为 1)", "PENDING 状态入库单必须传 receiving_detail_id 且已绑定收货单方可操作", "CREATED + 已绑定收货单的入库单需先审核(reviewEntry)后才能上架", "批量模式 items 数组同步支持 receiving_detail_id/allocated_quantity 字段", "补充完整错误码列表:超量、可用数量不足、状态校验等" ], "type": "updated" }, { "version": "2026.06.30-system-03", "date": "2026-06-30", "summary": "storage.entry.commit 入参变更:entry_order_code → entry_order_id(number),与底层 inboundDirectLog.commit 实现对齐", "methods": [ "storage.entry.commit" ], "notes": [ "入参 entry_order_code(string) → entry_order_id(number),与底层 inboundDirectLog.commit(entryOrderId) 实现对齐", "补充 description 说明先同步后写库两段式流程:① 奇门/API 回传 → ② onSuccess 内事务写库存", "补充 commit 后 EntryReceivingBinding 状态从 pending 更新为 committed 的说明" ], "type": "updated" }, { "version": "2026.06.30-system-04", "date": "2026-06-30", "summary": "storage.directInbound.commit 入参变更:entry_order_code → entry_order_id(number),与底层 inboundDirectLog.commit 实现对齐", "methods": [ "storage.directInbound.commit" ], "notes": [ "入参 entry_order_code(string) → entry_order_id(number),与底层 inboundDirectLog.commit(entryOrderId) 实现对齐", "该方法已标记 deprecated,推荐使用 storage.entry.commit" ], "type": "updated" }, { "version": "2026.06.30-system-05", "date": "2026-06-30", "summary": "storage.entry.getDirectInboundItems 响应结构重构:entryOrder 精简字段,items[].count→planned、direct_inbound_quantity→completed,items[].bindings 新增,移除 direct_logs/summary 等冗余字段", "methods": [ "storage.entry.getDirectInboundItems" ], "notes": [ "entryOrder 精简为 id / entry_order_code / order_status / store_remask 四个字段", "items[].count → planned(计划数量),items[].direct_inbound_quantity → completed(已完成数量)", "items[].bindings 新增,结构为 { detail_id, binding_id, allocated_quantity, space_id, space_name }", "items[].stock 新增,返回 getStockDetails 缓存的商品详情(item_code、item_name、barcodes 等)", "移除 direct_logs(现有响应中已不存在该顶层字段)", "移除 summary(现有响应中已不存在该字段)", "移除 items[].received_quantity、items[].remaining_quantity、items[].pending_binding_total 等旧字段", "新增 receivingBindings 字段说明:入库单层级收货单绑定关系" ], "type": "updated" }, { "version": "2026.06.30-system-06", "date": "2026-06-30", "summary": "storage.directInbound.getItems 响应结构重构:entryOrder 精简字段,items[].count→planned、direct_inbound_quantity→completed,items[].bindings 新增,移除 direct_logs/summary 等冗余字段", "methods": [ "storage.directInbound.getItems" ], "notes": [ "响应结构与 storage.entry.getDirectInboundItems 对齐(两者共用同一个底层实现 inboundDirectLog.getItems)", "entryOrder 精简为 id / entry_order_code / order_status / store_remask", "items[].count → planned,items[].direct_inbound_quantity → completed", "items[].bindings 新增 { detail_id, binding_id, allocated_quantity, space_id, space_name }", "items[].stock 新增", "移除 direct_logs、summary、items[].received_quantity、items[].remaining_quantity 等旧字段", "新增 receivingBindings 字段" ], "type": "updated" }, { "version": "2026.06.30-system-07", "date": "2026-06-30", "summary": "storage.entry.containerList 响应结构补充 stock 字段:返回商品详情(item_code、item_name、barcodes 等)", "methods": [ "storage.entry.containerList" ], "notes": [ "响应 list[].stock 字段补充为必返回:通过 getStockDetails 批量获取商品详情缓存", "stock 对象包含 item_code、item_name、sku_property、barcodes 等字段" ], "type": "updated" }, { "version": "2026.06.30-system-08", "date": "2026-06-30", "summary": "storage.receiving.scanDetail 响应结构补充 stock 字段:返回商品详情(item_code、item_name、barcodes 等)", "methods": [ "storage.receiving.scanDetail" ], "notes": [ "响应 list[].stock 字段补充为必返回:通过 getStockDetails 批量获取商品详情缓存", "stock 对象包含 item_code、item_name、sku_property、barcodes 等字段", "完善 error 列表:补充 未找到可用的收货明细、未找到匹配的收货明细、入库单ID不能为空、扫描条码不能为空 等错误" ], "type": "updated" }, { "version": "2026.06.30-system-09", "date": "2026-06-30", "summary": "订单列表 list 响应新增 store_remark(货主备注)字段", "methods": [ "order.list", "order.reviewOrder.list", "order.pendingOrder.list", "order.expectionOrder.list", "order.entrustOrder.list", "order.deliveryOrder.list", "order.deliveryExpectionOrder.list", "order.archiveOrder.list" ], "notes": [ "数据库字段 store_remask,返回给前端的字段名为 store_remark。", "服务层从 wms_store_warehouse.store_remask 按 store_id+warehouse_id 聚合批量填充。", "货主备注值可能为空字符串(当货主未设置备注时)。", "该字段对订单列表的所有 method 均适用(current/dispatch/outsourced/history 模型均返回)。" ], "type": "updated" }, { "version": "2026.07.02-system-02", "date": "2026-07-02", "summary": "新增 quick.waybill.toOrder 接口:根据运单号快速查询订单ID", "methods": [ "quick.waybill.toOrder" ], "notes": [ "新增 quick 模块组(快捷查询)", "查询 wms_order_express 表中 status=1 的有效记录", "无需登录和鉴权(免登录/免鉴权)" ], "type": "added" }, { "version": "2026.07.02-system-01", "date": "2026-07-02", "summary": "修正 quick.waybill.toOrder 的 isNeedLogin 为 true,与代码实现保持一致", "methods": [ "quick.waybill.toOrder" ], "notes": [ "文档中 isNeedLogin 为 false,但代码 systemMethods/quick/waybill.js 中 _noNeedLogin 为空字符串,未将 toOrder 加入免登录列表,实际需要登录验证,修正文档以与代码一致。" ], "type": "fixed" }, { "version": "2026.07.03-system-01", "date": "2026-07-03", "summary": "binding 表弃用文档同步:wms_entry_receiving_binding 已弃用,功能迁移到 wms_inbound_direct_log 表;bindings 描述中表引用更新为 InboundDirectLog", "methods": [ "storage.entry.getDirectInboundItems" ], "notes": [ "bindings 数组 description 中 wms_entry_receiving_binding 引用更新为 InboundDirectLog,明确旧表已弃用", "binding_id description 中 wms_entry_receiving_binding.id 更新为 InboundDirectLog.id", "allocated_quantity description 中补充来源 InboundDirectLog.quantity", "wms_inbound_direct_log 表新增字段:entry_item_id、receiving_detail_id、status(ENUM: pending/committed/released)、updated_at、deleted_at" ], "type": "updated" }, { "version": "2026.07.03-system-02", "date": "2026-07-03", "summary": "binding 表弃用文档同步:wms_entry_receiving_binding 已弃用,功能迁移到 wms_inbound_direct_log 表;bindings 描述中表引用更新为 InboundDirectLog", "methods": [ "storage.directInbound.getItems" ], "notes": [ "bindings 数组 description 中更新为来自 InboundDirectLog,明确旧表已弃用", "binding_id description 更新为 InboundDirectLog.id", "allocated_quantity description 中补充来源 InboundDirectLog.quantity", "wms_inbound_direct_log 表新增字段:entry_item_id、receiving_detail_id、status(ENUM: pending/committed/released)、updated_at、deleted_at" ], "type": "updated" }, { "version": "2026.07.03-system-03", "date": "2026-07-03", "summary": "binding 表弃用文档同步:commit 描述中 EntryReceivingBinding 更新为 InboundDirectLog", "methods": [ "storage.entry.commit" ], "notes": [ "commit description 中将 pending 状态的 EntryReceivingBinding 更新为 pending 状态的 InboundDirectLog,与代码实现一致" ], "type": "updated" }, { "version": "2026-07-03-entry-get-params-fix", "date": "2026-07-03", "type": "updated", "summary": "修正 storage.entry.get 文档:id 改为必填;移除未实现的 entry_order_code 参数;修正错误码与实际返回一致;补充 available_receiving_details 响应字段;修正 remaining_quantity 计算公式及 warehouse_image_url 实际行为", "methods": [ "storage.entry.get" ], "notes": [ "params: 移除 entry_order_code(代码中从未使用该参数),id 从 required=false 改为 required=true", "params: id 描述从'二选一'改为'必填'", "errors: 400 的 message 从'参数错误:id 与 entry_order_code 至少提供一个'改为'id 参数不能为空'", "errors: 移除不存在的 404 error,入库单不存在时实际返回 code=0, message='入库单不存在或无权访问'", "errors: 删除不存在的 500 error", "response: 新增 entryOrder.items[].available_receiving_details 字段及其描述", "response: remaining_quantity 描述从 'count - received_quantity - direct_inbound_quantity' 修正为 'max(0, count - received_quantity)'", "response: warehouse_image_url 描述从 StockWarehouse.image_url 改为'当前固定返回空字符串'", "response: warehouse_is_images 类型从 number(0/1) 改为 string(Y/N),与 StockWarehouse.is_images 实际存储一致", "response: warehouse_quantity/warehouse_locked_quantity/warehouse_is_batch_mgmt/warehouse_is_shelf_life_mgmt 补充无匹配时为 null 的说明", "description: 更新描述以反映实际逻辑流程" ] }, { "version": "2026.07.03-system-04", "date": "2026-07-03", "type": "modified", "summary": "order.pendingOrder.updateAddress 移除 remark(备注)修改功能,现在仅支持地址字段批量修改;备注修改已独立为 order.pendingOrder.updateRemark", "methods": [ "order.pendingOrder.updateAddress" ], "notes": [ "移除入参 remark 参数定义项。", "移除 remark 更新逻辑及相关描述,updateAddress 现在仅处理地址字段(name/mobile/tel/zip_code/province/city/area/town/detail_address)。", "description 更新:去掉 remark 相关描述,仅描述地址字段修改规则。", "response updated_count 描述更新:从「取地址更新行数与备注更新行数的最大值」改为单纯描述地址更新行数。", "errors 更新:移除 remark 相关错误说明('remark 字段不受此限制' 等),修改 '至少需要提供一个地址字段或备注进行修改' 为 '至少需要提供一个地址字段进行修改'。", "备注修改功能已独立为 order.pendingOrder.updateRemark 方法。" ], "module": "order.pendingOrder" }, { "version": "2026-07-16", "date": "2026-07-16", "summary": "新增 workbench.bindCamera 接口,支持工作台绑定/解绑摄像头", "methods": [ "workbench.bindCamera" ], "notes": [ "通过 device_ids JSON 字段存储绑定关系", "传空数组可解绑" ] }, { "version": "2026.07.17-stock-report-migration-01", "date": "2026-07-17", "type": "updated", "summary": "storage.report 模块迁移至 stock.report:修正语义错误,库存报表属于 stock 域而非 storage 域", "methods": [ "stock.report.search", "stock.report.searchStore", "stock.report.export", "stock.report.exportStore", "stock.report.exportTaskProgress" ], "notes": [ "将 systemMethods/storage/report.js 移动到 systemMethods/stock/report.js", "内部引用同步更新:类名 StorageReportMethodService→StockReportMethodService,缓存键 storage_report→stock_report,日志前缀 [storage.report]→[stock.report]", "旧文件直接删除,不保留兼容(storage.report 为语义错误,调用方需同步更新 method 名)", "更新 systems/storage/entry.js L273 注释引用", "文档:methods/system.json module storage.report→stock.report,5个 method 名同步更新" ] }, { "version": "2026.07.17-stock-transaction-export-01", "date": "2026-07-17", "type": "added", "summary": "新增 stock.transaction 商品流水导出(仓库侧+货主侧),异步任务模式,支持与列表查询一致的条件筛选", "methods": [ "stock.transaction.export", "stock.transaction.exportStore", "stock.transaction.exportTaskProgress" ], "notes": [ "systems/stock_transaction.js 新增 exportList(),复用 queryList 的查询逻辑,不分页导出 Excel(上限 50000 条)", "systemMethods/stock/transaction.js 新增 export/exportStore/exportTaskProgress,采用异步任务模式(setImmediate + 缓存)", "仓库侧导出自动限定 warehouse_id=ctx.user.store_id,货主侧需传 store_id", "导出 Excel 列:序号/创建时间/流水类型/仓库ID/货主ID/商品ID/变动数量/变更前库存/变更后库存/变更前锁定/变更后锁定/批次号/单据类型/单据号/收货单ID/入库单ID/发货单ID/操作人/备注" ] }, { "version": "2026.07.29-system-01", "date": "2026-07-29", "type": "added", "summary": "新增 waybill.warehouse 运单模块(仓库侧):list(列表)、detail(详情)、export(导出)3 个接口,支持运单号独立查询与管理", "methods": [ "waybill.warehouse.list", "waybill.warehouse.detail", "waybill.warehouse.export" ], "notes": [ "新增 waybill.warehouse.list:仓库侧运单列表查询,支持分页与多条件筛选(运单号/主单号/订单ID/订单号/物流公司/物流接口/平台/状态/退回/拦截/星河签收/包材/称重/关键词/时间范围),默认按 create_at desc 排序。", "新增 waybill.warehouse.detail:仓库侧运单详情查询,含关联订单信息、兄弟运单(sibling_waybills)、物流信息、状态信息、称重信息、打包信息(打包状态/打包人/打包时间)、打印记录列表。", "新增 waybill.warehouse.export:仓库侧运单导出,复用 list 筛选逻辑,异步任务模式,支持自定义导出字段。", "仓库隔离策略:所有接口自动注入 warehouse_id = ctx.user.store_id(全系统统一约定),不可由前端入参覆盖。", "快照字段方案:wms_order_express 表新增 delivery_order_code、store_id_snapshot、store_name_snapshot、warehouse_name_snapshot 四个快照列,列表查询无需 JOIN 订单表或货主表,仅单表查询 + SELF JOIN(主单号)。", "主单号/子单号规则:同一 order_id 下 business_key=1 为主单号,business_key>1 为子单号,沿用系统已有约定。", "命名空间规划:waybill.warehouse.* 本期实现(仓库侧),后续预留 waybill.store.*(货主侧)。", "本模块一期仅提供只读查询,不涉及运单创建/修改/删除,不修改任何现有接口。" ], "module": "waybill.warehouse" }, { "version": "2026.07.30-system-01", "date": "2026-07-30", "type": "changed", "summary": "更新 waybill.warehouse group API 文档:list 新增 waybillType/storeId 筛选、移除 pack_status 响应字段;detail 精简 package 对象;export 响应改为纯异步任务模式(仅含 task_id/status/progress/message/update_time)", "methods": [ "waybill.warehouse.list", "waybill.warehouse.detail", "waybill.warehouse.export", "waybill.warehouse.exportTaskProgress" ], "notes": [ "waybill.warehouse.list:新增 where.waybillType 筛选(\"main\"/\"1\"=主单号,\"child\"/\"2\"=子单号),新增 where.storeId 货主ID等值筛选。where.orderNo 标注暂不可用(待快照字段就绪)。response 移除 pack_status 字段(两表无关联,不再返回),list 字段数从 28 减至 27。", "waybill.warehouse.detail:package 对象移除 pack_status/pack_quantity/pack_at/packer_name 四个字段,仅保留 package_material_id 和 package_material_name。description 同步去掉\"打包状态\"相关描述。", "waybill.warehouse.export:响应简化为纯异步任务模式,data 仅含 task_id/status/progress/message/update_time,不含 total_count/current_count/result/error/download_url 等执行期字段(这些信息由 exportTaskProgress 接口返回)。export 的 where 参数同步新增 waybillType 和 storeId。", "waybill.warehouse.exportTaskProgress:无变更,保持不变。" ], "module": "waybill.warehouse" }, { "version": "2026.08.03-system-01", "date": "2026-08-03", "type": "added", "summary": "新增站内信(Inbox)管理模块,支持消息列表、详情、对话链、回信、重推、统计等管理功能,仓库维度隔离,warehouseId 由服务端上下文注入", "methods": [ "inbox.list", "inbox.detail", "inbox.thread", "inbox.reply", "inbox.retry", "inbox.stats" ], "notes": [ "入口:POST /system,body.method=inbox.{action},路由到 app/controller/inbox.index", "inbox.list:分页查询消息列表,支持 direction/pushStatus/targetChannel/keyword 筛选,列表不含 ext_data 和 push_response 大字段", "inbox.detail:查单条消息详情,含完整 push_response 推送响应信息", "inbox.thread:对话链查询,从指定消息向上查找根消息,向下收集所有回信,按时间升序返回", "inbox.reply:系统回信,自动继承原消息 ext_data/ref_code,写入 direction=outbound + parent_id 形成对话链,异步推送到目标渠道", "inbox.retry:手动重推失败消息(仅 push_status=3 可重推),重置为 push_status=0 并触发 setImmediate 异步推送", "inbox.stats:按方向/推送状态汇总统计 + 最近24小时新增数量", "安全边界:warehouse_id 由 ctx.user.store_id 注入(内部管理端),外部不可传入,保证仓库隔离", "底层服务:app/service/inbox/index.js(查询管理)+ app/service/inbox/receiver.js(接收推送)" ], "module": "inbox" }, { "version": "2026.08.03-system-02", "date": "2026-08-03", "summary": "setting.expressInterface.list 返回新增 quantity/recycled_quantity/cancel_quantity/allocated_quantity 扁平字段,数据源为 index.getShopExpressList", "methods": [ "setting.expressInterface.list" ], "notes": [ "每条记录新增四个扁平字段:quantity(可用面单数)、recycled_quantity(已回收)、cancel_quantity(已取消)、allocated_quantity(已分配)", "数据通过 Promise.all 并行调用 index.getShopExpressList 获取各店铺快递签约数据", "匹配逻辑分三层:sys_express_code 匹配快递 → site_code/branch_code 匹配网点 → shipperno/customer_code_list 匹配账号", "无店铺或无数据时四个字段均为 0" ] }, { "version": "2026.08.03-system-03", "date": "2026-08-03", "summary": "补全 setting.expressInterface.list response 所有返回字段文档,包含 express 子对象、quantity 四字段等", "methods": [ "setting.expressInterface.list" ], "notes": [ "补全所有 response list children 字段:从原有的 4 个扩展为 42 个完整字段", "新增 express 子对象文档(code/name/polyapi_code/polyapi_extra_info/pdd_code/ks_code/dyxd_code)", "保留 quantity/recycled_quantity/cancel_quantity/allocated_quantity 四个扁平面单数量字段" ] }, { "version": "2026.08.03-system-04", "date": "2026-08-03", "type": "added", "summary": "新增店铺-快递绑定策略模块 storeExpressBindingPolicy,支持仓库维度的货主/店铺->快递绑定策略 CRUD,按优先级匹配,可附加商品/地区/重量/金额等条件", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "storeExpressBindingPolicy.list:分页查询策略列表,支持 where 条件筛选(id/custom_name/store_id/shop_id/express_code/priority/is_enabled/creator_id/quickWhere),按 priority DESC、updated_at DESC 排序。", "storeExpressBindingPolicy.add:新增策略,必填 custom_name 和 express_code。express_code 须存在于 wms_express。同仓库下 custom_name 唯一。可选 store_id/shop_id/priority/is_enabled/match_condition/remark/creator_id。", "storeExpressBindingPolicy.edit:编辑策略,必填 id。仅更新传入的非 undefined 字段。修改 custom_name 时校验同仓库唯一性。", "storeExpressBindingPolicy.del:软删除策略(deleted_at + is_enabled=0),不物理删除。", "仓库隔离:所有操作按 ctx.user.store_id → warehouse_id 自动过滤。", "匹配条件 match_condition(JSON):支持 platform_codes/provinces/cities/item_codes/min_weight_g/max_weight_g/min_amount/max_amount。" ], "module": "storeExpressBindingPolicy" }, { "version": "2026.08.03-system-05", "date": "2026-08-03", "type": "changed", "summary": "精简 storeExpressBindingPolicy:移除 store_id/shop_id 冗余字段,custom_name 明确为纯自由文本标签(与系统 shops 无关)", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "移除 add/edit 入参中的 store_id/shop_id(含 camelCase 兼容)", "list 响应不再返回 store_id/shop_id", "custom_name 为纯自由文本标签,与系统 shops 表无关" ], "module": "storeExpressBindingPolicy" }, { "version": "2026.08.04-system-01", "date": "2026-08-04", "type": "changed", "summary": "storeExpressBindingPolicy 字段重构: match_condition JSON 拆分为独立字段 provinces/cities/min_weight_g/max_weight_g/weight_type,新增 prohibited_type_id", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "移除 match_condition JSON,拆分 provinces TEXT逗号分隔 + cities TEXT逗号分隔 + min_weight_g INT + max_weight_g INT + weight_type TINYINT 默认0", "weight_type 枚举 0=常规 1=轻货 2=重货 3=冷链 必填默认0", "新增 prohibited_type_id 关联 wms_prohibited_type.id" ], "module": "storeExpressBindingPolicy" }, { "version": "2026.08.04-system-02", "date": "2026-08-04", "type": "changed", "summary": "合并 provinces/cities 为单一 regions 字段 TEXT逗号分隔", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "移除 provinces/cities 两个字段,合并为 regions TEXT 逗号分隔" ], "module": "storeExpressBindingPolicy" }, { "version": "2026.08.04-system-03", "date": "2026-08-04", "type": "added", "summary": "新增 exclude_regions 排除地区字段", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "新增 exclude_regions 排除地区字段 TEXT逗号分隔" ], "module": "storeExpressBindingPolicy" }, { "version": "2026.08.04-system-04", "date": "2026-08-04", "type": "changed", "summary": "修正 API 文档风格,对齐项目 shops.list 等模块规范", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "list page/pageSize 描述对齐 shops.list 风格", "add/edit 参数描述补充兼容性说明和详细格式" ], "module": "storeExpressBindingPolicy" }, { "version": "2026.08.04-system-05", "date": "2026-08-04", "type": "added", "summary": "新增 shop_name 字段,用于包含店铺名称匹配", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "新增 shop_name TEXT逗号分隔,与 custom_name区分:custom_name=策略名称,shop_name=包含店铺名称" ], "module": "storeExpressBindingPolicy" }, { "version": "2026.08.04-system-06", "date": "2026-08-04", "type": "added", "summary": "新增shop_name和store_ids字段", "methods": [ "storeExpressBindingPolicy.list", "storeExpressBindingPolicy.add", "storeExpressBindingPolicy.edit", "storeExpressBindingPolicy.del" ], "notes": [ "新增shop_name包含店铺名称", "新增store_ids限定货主ID" ], "module": "storeExpressBindingPolicy" }, { "version": "2026-08-05-wavePickTaskDetail-waveNo", "date": "2026-08-05", "summary": "pick.wavePickTaskDetail 响应 task 对象新增 wave_no 字段,从 wms_wave_pick_task_wave 关联 wms_wave_batch 获取波次号", "methods": [ "pick.wavePickTaskDetail" ], "notes": [ "task 对象新增 wave_no(string)字段,位于 task_no 之后;查询失败时降级为空字符串。", "数据来源:wms_wave_pick_task_wave INNER JOIN wms_wave_batch ON wave_id。" ] }, { "version": "2026-08-06", "date": "2026-08-06", "summary": "sign_method 收紧为仅支持 md5:create 固定为 md5 不可选,update 不允许修改 sign_method,list/detail 响应描述同步更新", "methods": [ "apiApp.list", "apiApp.detail", "apiApp.create", "apiApp.update" ], "notes": [ "验证确认 /openapi 和 /warehouse 实际只使用 MD5 签名算法", "apiApp.create: 删除 sign_method 入参,硬编码为 md5", "apiApp.update: sign_method 字段改为不可修改,传入即报错", "apiApp.list / apiApp.detail: sign_method 响应描述更新为「当前仅支持 md5」" ] }, { "version": "2026.08.10-afterSale-handleWorkOrder-remove-action", "date": "2026-08-10", "type": "changed", "summary": "afterSale.handleWorkOrder 移除 action 参数:action 不再由前端传入,改为服务端固定写入\"处理工单\";处理说明统一使用 remark 字段。", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "移除 action 参数(原为必填 string,前端传入操作动作描述),前端不再需要也不接受此参数。", "步骤记录的 action 字段由服务端在 systems/afterSale.js handleWorkOrder 中硬编码为\"处理工单\"。", "处理说明统一使用 remark 字段承载。", "代码变更:systemMethods/afterSale.js handleWorkOrder 移除 action 解构与必填校验;systems/afterSale.js handleWorkOrder 移除 message 参数,addStep action 固定为\"处理工单\"。" ], "module": "afterSale" }, { "version": "2026.08.10-afterSale-handleWorkOrder-status-whitelist", "date": "2026-08-10", "type": "changed", "summary": "afterSale.handleWorkOrder 新增 status 枚举白名单校验:status 必须与 wms_after_sale 主表 AFTER_SALE_STATUS 枚举一致(pending/processing/completed/closed/cancelled),补全 cancelled 枚举值文档。", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "status 参数新增枚举白名单校验:从 AfterSale.AFTER_SALE_STATUS 取 key 列表,不在白名单内返回 400。", "文档 status 枚举值补全 cancelled,与主表模型保持一致(pending | processing | completed | closed | cancelled)。", "校验同时在 systemMethods/afterSale.js(方法层)和 systems/afterSale.js(业务层)两层生效。", "仅代码校验增强 + 文档修正,不改变业务语义。" ], "module": "afterSale" }, { "version": "2026.08.10-afterSale-handleWorkOrder-status-default-processing", "date": "2026-08-10", "type": "changed", "summary": "afterSale.handleWorkOrder status 参数改为容错模式:不填或填错时默认 processing(处理中),不再返回 400 错误。status 始终写入主表。", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "status 参数行为变更:原来不传时保持当前状态(有 if 判断),现在不填或填错默认 processing,始终写入主表。", "校验方式从白名单拒绝改为容错兜底:safeStatus = (targetStatus 合法) ? targetStatus : 'processing'。", "updateFields.status 从条件写入改为始终写入 safeStatus。", "role_group 回退判断同步从 targetStatus 改为 safeStatus。", "代码变更:systemMethods/afterSale.js + systems/afterSale.js 两层均改为容错逻辑。" ], "module": "afterSale" }, { "version": "2026.08.10-afterSale-handleWorkOrder-exclude-pending", "date": "2026-08-10", "type": "changed", "summary": "afterSale.handleWorkOrder status 白名单排除 pending:pending 是创建默认值(表示尚未处理),处理工单时不允许回退到此状态。", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "handleWorkOrder 允许的 status 从全部 AFTER_SALE_STATUS 中排除 pending,剩余:processing | completed | closed | cancelled。", "若前端传 status=pending 视为填错,容错兜底为 processing。", "代码变更:两处 ALLOWED_STATUSES 增加 .filter(s => s !== 'pending')。" ], "module": "afterSale" }, { "version": "2026.08.10-afterSale-step-status-align-main-table", "date": "2026-08-10", "type": "changed", "summary": "wms_after_sale_detail.step_status 改为与 wms_after_sale.status 完全一致:字段类型从 TINYINT 改为 VARCHAR(20),每次写入步骤时记录主表当前 status 快照。", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "DB 迁移:20260810140000-alter-wms-after-sale-detail-step-status-to-varchar.js — step_status 从 TINYINT UNSIGNED 改为 STRING(20),已有数据回填 processing。", "Model:after_sale_detail.js 移除 TINYINT 引用,step_status 改为 STRING(20),STEP_STATUS 枚举对齐主表 AFTER_SALE_STATUS。", "addStep 默认值从 2 改为 'processing'。", "transfer:step_status 取 update() 返回的 updated.status。", "handleWorkOrder:step_status 取 safeStatus(与写入主表的 status 完全一致)。", "registerClaim:step_status 取 afterSale.status(主表当前状态)。" ], "module": "afterSale" }, { "version": "2026.08.11-afterSale-add-waiting-status", "date": "2026-08-11", "type": "added", "summary": "新增 waiting(等待外部处理)状态:用于内部处理完成后等待外部第三方(快递、客户、平台)响应的场景。", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "Model:after_sale.js AFTER_SALE_STATUS 新增 waiting: '等待外部处理'。", "Model:after_sale_detail.js STEP_STATUS 同步新增 waiting。", "handleWorkOrder 白名单自动包含 waiting(从 AFTER_SALE_STATUS 派生,仅排除 pending)。", "状态流转:processing → waiting → processing/completed。", "设计文档同步更新 ER 图、状态流转图、枚举表。" ], "module": "afterSale" }, { "version": "2026.08.11-afterSale-rename-pending-feedback", "date": "2026-08-11", "type": "changed", "summary": "waiting 重命名为 pending_feedback(等待外部反馈):语义更精确——内部已处理完并将信息发给外部,等待反馈后再决定是否继续处理,等待期间不需要内部介入。", "methods": [ "afterSale.handleWorkOrder" ], "notes": [ "Model/DB/文档中 waiting 全部替换为 pending_feedback", "workList/workCount 排除列表新增 pending_feedback(等待反馈期间不需要内部处理)", "典型场景:客服收到拦截工单 → 发信息给运方 → 设为 pending_feedback 等待运方反馈 → 收到反馈后回到 processing 通知客户" ], "module": "afterSale" }, { "version": "2026.08.11-afterSale-batchSetPendingFeedback", "date": "2026-08-11", "type": "added", "summary": "新增 afterSale.batchSetPendingFeedback 批量设为待反馈接口:传入 ids 列表,按仓库 policy_config.after_sale_followup_hours 配置自动计算 followup_at,事务内批量更新状态并写入步骤记录。", "methods": [ "afterSale.batchSetPendingFeedback" ], "notes": [ "新增 method:afterSale.batchSetPendingFeedback,入参 ids(number[])和 remark(string, optional)", "业务层 systems/afterSale.js 新增 batchSetPendingFeedback:预校验 ids 有效性/终态/跨仓库,事务内逐条更新 status=pending_feedback + followup_at=NOW()+INTERVAL hours HOUR + 步骤记录", "方法层 systemMethods/afterSale.js 新增 batchSetPendingFeedback:从 ctx.user 提取 operator 信息和 warehouseId,委托 systems 层执行", "followup_at 时长复用现有 _resolveFollowupHours 三级查找:仓库 policy_config → 内置 DEFAULTS 映射 → 兜底 24h", "终态工单(completed/closed/cancelled)不可设为待反馈,跨仓库工单被拒绝,均返回在 failed 列表中", "已在 _noNeedRight 和 _noNeedAuth 中注册,写入操作会记录日志" ], "module": "afterSale" }, { "version": "2026.08.11-afterSale-batchClose", "date": "2026-08-11", "type": "added", "summary": "新增 afterSale.batchClose 批量完结/关闭接口:传入 ids + status(completed|closed),事务内批量更新状态、写入步骤记录,completed 时自动写入 resolved_at 并清除 followup_at。", "methods": [ "afterSale.batchClose" ], "notes": [ "新增 method:afterSale.batchClose,入参 ids(number[])、status(completed|closed)、resolution(string, optional)、remark(string, optional)", "业务层 systems/afterSale.js 新增 batchClose:预校验 ids 有效性/终态/跨仓库,事务内逐条更新 status + resolved_at + followup_at 清除 + 步骤记录", "方法层 systemMethods/afterSale.js 新增 batchClose:从 ctx.user 提取 operator 信息和 warehouseId,委托 systems 层执行", "终态工单(completed/closed/cancelled)不可重复完结/关闭,跨仓库工单被拒绝,均返回在 failed 列表中", "已在 _noNeedRight 和 _noNeedAuth 中注册,写入操作会记录日志" ], "module": "afterSale" }, { "version": "2026.08.11-afterSale-detail-enrich", "date": "2026-08-11", "type": "enhanced", "summary": "enhance: afterSale.detail 响应新增 related 字段,自动补充关联订单详情(收件人/发件人/商品明细/打包视频)和货主合约备注(store_remask)。", "methods": [ "afterSale.detail" ], "notes": [ "响应新增 related 对象:含 related.order(订单详情)和 related.store_contract(货主合约备注),仅在售后单有关联单据时有值", "related.order.recipient:从 wms_order_delivery 提取收件人姓名/电话/手机/邮箱/省市区/详细地址", "related.order.sender:从货主 store.subject_config 提取发件人信息(sender_name/sender_tel/地址)", "related.order.current_table:根据 dispatch_status/outbound_status/status 判断订单当前所在表(main/dispatch/history)", "related.order.items:从 order_delivery.items JSON 字段解析商品明细数组", "related.order.pack_videos:通过 PackTask → PackTaskVideo 关联查询打包视频列表(含 video_url/camera_id)", "related.store_contract:从 wms_store_warehouse 查询 store_remask(商家备注)/warehouse_remask(仓库备注)/使用状态", "所有关联查询使用 try-catch 兜底,查询失败时仅打 warn 日志,不影响主流程", "systems/afterSale.js 新增 _enrichAfterSaleDetail / _resolveOrderDetail / _resolveStoreContractNote 三个私有方法" ], "module": "afterSale" }, { "version": "2026.08.11-afterSale-detail-waybill", "date": "2026-08-11", "type": "enhanced", "summary": "enhance: afterSale.detail 响应 related 新增 waybill 字段,自动补充运单详情(快递公司名称 + 使用的物流接口)。", "methods": [ "afterSale.detail" ], "notes": [ "响应 related 新增 related.waybill 字段(waybill_id 不为空时自动返回)", "related.waybill.logistics_name:快递公司名称(如 圆通/中通/顺丰),来源 wms_order_express.logistics_name", "related.waybill.logistics_interface_name:使用的物流接口名称,来源 wms_order_express.logistics_interface_name", "related.waybill.logistics_code:物流编码,来源 wms_order_express.logistics_code", "related.waybill 同时返回 waybill_code/status/is_back/is_intercept/create_at 等基础字段", "systems/afterSale.js 新增 _resolveWaybillDetail 私有方法,查询失败仅打 warn 日志不影响主流程", "仅文档 + 代码变更,不涉及数据库变更" ], "module": "afterSale" }, { "version": "2026.08.11-afterSale-create-order-id-alias", "date": "2026-08-11", "type": "enhanced", "summary": "enhance: afterSale.create 入参新增 order_id 别名,与 order_delivery_id 等效,优先取 order_delivery_id,为空时回退到 order_id。", "methods": [ "afterSale.create" ], "notes": [ "create 方法解构时新增 order_id 别名读取;优先使用 order_delivery_id,为空时取 order_id", "仅方法层变更(systemMethods/afterSale.js),业务层无改动", "同时更新 JSDoc 注释,标注 order_delivery_id 兼容别名 order_id" ], "module": "afterSale" }, { "version": "2026.08.11-inbox-group-update-subtype-enum", "date": "2026-08-11", "summary": "enhance: inbox.group.update 子类型枚举补全三层约束。groupType=store 可用 after_sales/finance/receiving,groupType=warehouse 新增 production/stockout/all/exception,groupType=express 补全 pickup/after_sales。同步更新 subType description 和 400 错误码描述", "type": "enhance", "methods": [ "inbox.group.update" ], "notes": [ "subType 枚举由 GROUP_TYPES 统一定义,与 AI 函数分组同源", "后端已新增两层类型校验:subType 必须在对应 groupType 的合法子类型列表中" ] }, { "version": "2026.08.11-inbox-group-update-subtype-enum-v2", "date": "2026-08-11", "summary": "enhance: inbox.group.update 子类型枚举补全三层约束。groupType=store 可用 after_sales/finance/receiving,groupType=warehouse 新增 production/stockout/all/exception,groupType=express 补全 pickup/after_sales。同步更新 subType description 和 400 错误码描述", "type": "enhance", "methods": [ "inbox.group.update" ], "notes": [ "subType 枚举由 GROUP_TYPES 统一定义,与 AI 函数分组同源", "后端已新增两层类型校验:subType 必须在对应 groupType 的合法子类型列表中" ] }, { "version": "2026.08.11-inbox-group-update-subtype-enum-v3", "date": "2026-08-11", "summary": "enhance: inbox.group.update 子类型枚举补全三层约束。groupType=store 可用 after_sales/finance/receiving,groupType=warehouse 新增 production/stockout/all/exception,groupType=express 补全 pickup/after_sales。同步更新 subType description 和 400 错误码描述", "type": "enhance", "methods": [ "inbox.group.update" ], "notes": [ "subType 枚举由 GROUP_TYPES 统一定义,与 AI 函数分组同源", "后端已新增两层类型校验:subType 必须在对应 groupType 的合法子类型列表中" ] }, { "version": "2026.08.13-returnReceived", "date": "2026-08-13", "type": "added", "summary": "新增退回收到模块(returnReceived):退回包裹扫码登记、分页列表、详情、删除四个接口。扫码登记30日内同仓库同单号幂等(以第一次为准),反查原运单判定是否原单退回并同步标记 is_back='Y';列表/详情/删除仓库隔离。配套权限 527/528/529(扫码登记→仓库员工及以上,列表/删除→客服员工及以上)", "methods": [ "returnReceived.create", "returnReceived.list", "returnReceived.detail", "returnReceived.delete" ], "notes": [ "新增表 wms_return_received(仓库隔离 warehouse_id、退回收件单号 waybill_code、扫描日期 scan_date、扫描人员 scanner_id/scanner_name、运单关联 order_express_id/order_id/store_id 非必填)", "returnReceived.create:30日幂等 + 反查 wms_order_express.waybill_code,命中回填关联字段并同步 is_back='Y',返回 is_original_return/store_remark/duplicated", "returnReceived.list:分页列表,仓库隔离由服务端注入 warehouse_id,支持运单号/日期/扫描人员/货主/是否原单退回筛选", "returnReceived.detail:详情含原运单与货主合约备注,免权限但需登录+仓库隔离", "returnReceived.delete:物理删除,需权限+仓库隔离", "权限:527 returnReceived.create(仓库员工及以上)、528 returnReceived.list、529 returnReceived.delete(客服员工及以上);detail 复用 list 权限", "代码变更:app/model/return_received.js、app/service/systems/return_received.js、app/service/systemMethods/returnReceived.js、database/migrations/20260812160000-create-wms-return-received.js、20260813100000-create-return-received-permissions.js" ], "module": "returnReceived" }, { "version": "2026.08.13-shops-GetAuthorizeSessionKey-doc-sync", "date": "2026-08-13", "type": "updated", "summary": "同步 shops.GetAuthorizeSessionKey 文档:实现已切换为调用授权服务 saveShop 换取授权会话,旧的 PDD/CAINIAO 预占码方案已下线。", "methods": [ "shops.GetAuthorizeSessionKey" ], "notes": [ "实现:按店铺 platform_code 取 wms_print_platform.get_auth_platform_name 作为 platName,POST 授权服务 saveShop,携带 RedirectCodeUrl/shopName;京东平台附 VenderID,视频号平台改传 appId/toUserName 且不带 RedirectCodeUrl", "成功后更新店铺 access_token=sessionKey、status=1,返回 data.message='获取授权成功';上游 code≠0 或未返回 sessionKey 时抛 500", "文档更新:移除旧 data.session_key/authorize_url/state 返回结构与 501 未实现错误,补充 appId/toUserName 入参及 shop_id/callbackurl/platform_code 校验错误码", "仅文档同步,不修改业务代码" ], "module": "shops" }, { "version": "2026.08.13-interceptScan-non-intercept-guard", "date": "2026-08-13", "type": "updated", "summary": "order.recheckOrder.interceptScan 增加非拦截订单前置校验:运单不存在或未发起系统拦截时直接拒绝并提示「非拦截订单」,移除原先自动创建运单补充记录的逻辑。", "methods": [ "order.recheckOrder.interceptScan" ], "notes": [ "校验规则:运单记录不存在即拒绝;运单 is_intercept≠'Y' 时回查关联订单,intercept_status 不在 requested/intercepting 也拒绝,提示「非拦截订单」", "校验通过后原逻辑不变:标记 is_back='Y'/is_intercept='Y'、处理未完结售后工单、订单级更新 intercepted_at_warehouse 并释放储位分配与订单锁", "移除运单不存在时自动创建补充记录的分支(未发起拦截的运单不再被静默置为拦截)", "同步更新 JSDoc 与 methods/system.json 文档,错误码新增 400 非拦截订单" ], "module": "order.recheckOrder" }, { "version": "2026.08.13-returnUnpack", "date": "2026-08-13", "type": "added", "summary": "新增退回拆包模块(returnUnpack):开拆包单、录明细、更新明细、移除明细、取消、提交确认、分页列表、明细列表、详情、删除十个接口。开单反查原运单判定原单退回并回填货主,未命中原单时按 warehouse_id+waybill_code 从退回查询记录反查货主;拆包单号 RP+YYYYMMDD+6位序号;状态机 unpacking/completed/cancelled;明细识别状态 none_recognized/partial_recognized/all_recognized;全接口仓库隔离(服务端注入 warehouse_id)。配套权限 540-549(作业类→仓库员工及以上,查询/删除类→客服员工及以上,detail 免权限复用列表权限)", "methods": [ "returnUnpack.create", "returnUnpack.addDetail", "returnUnpack.updateDetail", "returnUnpack.removeDetail", "returnUnpack.cancel", "returnUnpack.submit", "returnUnpack.list", "returnUnpack.detailList", "returnUnpack.detail", "returnUnpack.delete" ], "notes": [ "新增表 wms_return_unpack(主表)/ wms_return_unpack_detail(明细)/ wms_return_unpack_video(视频,paranoid 软删)/ wms_return_query_log(退回查询记录)", "returnUnpack.create:waybill_code 必填;反查 wms_order_express.waybill_code 命中则回填 order_express_id/order_id/store_id 并返回原订单详情(复用 afterSale._resolveOrderDetail);未命中再从 wms_return_query_log 按 warehouse_id+waybill_code 反查货主(限最近 3 个月内登记);返回 id/record/is_original_return/store_remark/order", "returnUnpack.addDetail:主单非终态校验;stock_id 有值 → 查 wms_stock_warehouse 校验货主归属(不一致 403)+ 回填 is_recognized=1 与快照;主表 store_id 为空时以首个识别商品回填货主;写明细后重算 total_items/total_quantity/detail_status", "returnUnpack.updateDetail:白名单仅 quantity/remark;仅 quantity 变更时重算主表汇总", "returnUnpack.removeDetail:明细表 paranoid:false 硬删除 + 重算主表汇总", "returnUnpack.cancel:仅 unpacking 状态;事务内硬删主表+明细,软删视频", "returnUnpack.submit:仅 unpacking;status=completed + 回写 end_time,并同步更新 wms_return_query_log.is_back=1(失败不阻断主流程)", "returnUnpack.list:主表分页,仓库隔离服务端注入 warehouse_id;where 支持 unpack_no/waybill_code 模糊、unpack_date/start_time/end_time 范围、status/detail_status/unpacker_id/return_received_id/store_id/order_express_id/order_id 等值", "returnUnpack.detailList:明细分页 + stockWarehouse 关联(命中时);where 支持 unpack_id/stock_id/barcode/is_recognized/product_status", "returnUnpack.detail:主表 + details(stockWarehouse) + videos(camera) + returnReceived;原单退回时返回 related.order;免权限仅登录 + 仓库隔离", "returnUnpack.delete:后台删除不限状态;事务物理删主表+明细,软删视频", "仓库隔离:全部接口禁止前端传入 warehouse_id,由服务端注入 ctx.user.store_id;拆包单号规则 RP+YYYYMMDD+6位序号(仓库维度序号)", "权限:540 returnUnpack.create、541 addDetail、542 updateDetail、543 removeDetail、544 cancel、545 submit(仓库员工及以上);546 list、547 detailList、548 detail、549 delete(客服员工及以上);detail 免权限(复用列表权限)", "代码变更:app/model/return_unpack.js、return_unpack_detail.js、return_unpack_video.js、return_query_log.js;app/service/systems/return_unpack.js;app/service/systemMethods/returnUnpack.js;database/migrations/20260813120000-20260813120300 建表、20260813130000 权限" ], "module": "returnUnpack" }, { "version": "2026.08.13-returnReceived.createResponse", "date": "2026-08-13", "type": "updated", "summary": "returnReceived.create 出参结构调整:由平铺返回登记字段改为包装结构 { record, is_original_return, store_remark, duplicated },record 含登记记录完整字段与派生字段 is_original_return/store_remark,与代码实现(app/service/systems/return_received.js)及设计文档对齐", "methods": [ "returnReceived.create" ], "notes": [ "原出参平铺 id/waybill_code/scan_date/scanner_id/scanner_name/order_express_id/order_id/store_id/remark/is_original_return/store_remark/duplicated,现改为四个顶层字段:record(object,必填)、is_original_return(boolean,必填)、store_remark(string,必填)、duplicated(boolean,必填)", "record 内字段:id、waybill_code、scan_date、scanner_id、scanner_name、order_express_id、order_id、store_id、remark、created_at、updated_at(时间为格式化字符串)+ 派生字段 is_original_return、store_remark", "顶层 is_original_return / store_remark / duplicated 为 record 之外独立返回字段,与 record 内同名字段取值一致", "仅文档变更,代码实现已对齐(create 返回 { record, is_original_return, store_remark, duplicated },30日幂等命中与新建分支结构一致)" ], "module": "returnReceived" }, { "version": "2026.08.13-returnWaybill", "date": "2026-08-13", "type": "added", "summary": "新增运单退回登记模块(returnWaybill):复用 wms_return_query_log 表实现「货主 + 运单号」退回关系的增删查改五个接口(create/update/list/detail/delete)。create 校验货主合约并幂等返回已有记录;update 支持改运单号/货主/备注,改后冲突 409 拒绝;list 分页筛选(运单号模糊/货主/是否已通知/是否退回/登记时间范围);detail 免权限仅登录+仓库隔离;delete 物理删除。全接口仓库隔离(warehouse_id 服务端注入)。配套权限 551-555(作业类 create/update→仓库员工及以上,查询/删除类 list/detail/delete→客服员工及以上,detail 免权限复用列表权限)", "methods": [ "returnWaybill.create", "returnWaybill.update", "returnWaybill.list", "returnWaybill.detail", "returnWaybill.delete" ], "notes": [ "复用表 wms_return_query_log(20260813120300 迁移已落地):warehouse_id/store_id/waybill_code/remark/is_notified/is_back/created_at/updated_at;登记接口不维护 is_notified/is_back(由定时任务与拆包联动维护)", "returnWaybill.create:waybill_code/store_id 必填;货主合约校验(wms_store_warehouse 存在 store_id+warehouse_id,无合约 400 拒绝);同仓库+货主+运单号已存在时幂等返回已有记录 duplicated=true;写入 is_notified=0/is_back=0", "returnWaybill.update:id 必填;仓库隔离校验;waybill_code/store_id/remark 可选更新;store_id 变更时校验新货主合约;改后与另一条同仓库+货主+运单号冲突则 409 拒绝", "returnWaybill.list:pagination(pageSize 上限 500 默认 20)+ where(waybill_code 模糊、store_id、is_notified、is_back、created_at 起止)+ sort(id/created_at/updated_at/waybill_code,默认 created_at desc)", "returnWaybill.detail:免权限(复用列表权限),仅登录 + 仓库隔离校验", "returnWaybill.delete:物理删除(表 paranoid:false),返回被删除记录 id", "仓库隔离:所有接口 warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入", "权限:551 create、552 update(仓库员工及以上);553 list、554 detail、555 delete(客服员工及以上);detail 免权限复用 list 权限", "代码变更:app/service/systems/return_waybill.js、app/service/systemMethods/returnWaybill.js、database/migrations/20260813160000-create-return-waybill-permissions.js" ], "module": "returnWaybill" }, { "version": "2026.08.13-returnUnpack.detailAuth", "date": "2026-08-13", "type": "updated", "summary": "returnUnpack.detail 鉴权配置变更:不再免权限(原 _noNeedRight='detail'),改为走 API 权限校验(固定权限 ID 548,客服员工及以上),与 app/service/systemMethods/returnUnpack.js 实现对齐。", "methods": [ "returnUnpack.detail" ], "notes": [ "isNeedAuth:false → true;description 同步说明「需 548 权限(客服员工及以上)」", "代码对齐:returnUnpack.js _noNeedRight 改为空字符串,detail 与其他接口一致走 API 权限校验", "权限 548 为客服员工及以上(与原「查询类→客服员工及以上」设计一致)", "仅文档同步,其余接口与模块不动" ], "module": "returnUnpack" }, { "version": "2026.08.13-returnUnpack.addDetailBarcode", "date": "2026-08-13", "type": "updated", "summary": "returnUnpack.addDetail 新增 barcode 入参(可选):stock_id 为空时按条码反查本仓库商品(wms_stock_barcodes)再走识别流程,反查不到按无关联货物处理;条码同步写入明细作记录(此前固定写 null)。复用基础模块条码索引,支持 PDA 扫描条码录明细。", "methods": [ "returnUnpack.addDetail" ], "notes": [ "params 新增 barcode(string,可选,最长100,body)", "识别优先级:stock_id > barcode 反查 > 无关联货物", "明细 barcode 字段由固定 null 改为记录扫描条码", "business 层按 warehouse_id+barcode 匹配 wms_stock_barcodes(uk_barcode 全局唯一,加仓库过滤防跨仓串货)" ], "module": "returnUnpack" }, { "version": "2026.08.13-returnUnpack.addDetailBarcodeV2", "date": "2026-08-13", "type": "updated", "summary": "returnUnpack.addDetail 识别策略调整:未指定 stock_id 时一律标注未知商品(item_name=未知商品),移除按条码自动反查 stock_id 的逻辑(同一条码可能对应多个 stock_id,自动匹配易误配);barcode 仍写入明细作记录。", "methods": [ "returnUnpack.addDetail" ], "notes": [ "移除 barcode 反查 wms_stock_barcodes 自动识别逻辑(v1 新增,本次回退)", "未指定 stock_id:is_recognized=0,item_name=未知商品(此前为 null)", "barcode 参数保留:仅作记录写入明细,不参与商品匹配", "docs 同步:addDetail description / stock_id / barcode 参数说明更新" ], "module": "returnUnpack" }, { "version": "2026.08.13-returnUnpack.orderInfoSnapshot", "date": "2026-08-13", "type": "updated", "summary": "wms_return_unpack 主表新增订单信息快照字段 source_order_codes(平台交易单号)/ shop_name(店铺名称=货主自定义店铺名称 store_remask),returnUnpack.create 原单退回时回填;退回查询(查退回)优先取主表快照返回交易单号与自定义店铺。", "methods": [ "returnUnpack.create" ], "notes": [ "迁移 20260813170000-add-return-unpack-order-info.js:addColumn source_order_codes VARCHAR(500) + shop_name VARCHAR(50)", "create 原单退回:source_order_codes 取 wms_order_express.source_order_codes,shop_name 取 store_remask", "addDetail 首个识别商品回填主表 store_id 时同步回填 shop_name", "退回查询 _resolveReturnOrderInfo 优先主表快照,空时实时兜底(交易单号→原运单/原订单,店铺→store_remask)" ], "module": "returnUnpack" }, { "version": "2026.08.18-storeWarehouse-sign-confirmSign-doc", "date": "2026-08-18", "type": "added", "summary": "补齐 storeWarehouse 签约接口文档(纯文档补全,无业务代码变更):新增 storeWarehouse.store.confirmSign(货主侧确认签约)、storeWarehouse.warehouse.sign(仓库侧发起签约)、storeWarehouse.warehouse.confirmSign(仓库侧确认签约)三个方法的入参/出参/错误码说明。", "methods": [ "storeWarehouse.store.confirmSign", "storeWarehouse.warehouse.sign", "storeWarehouse.warehouse.confirmSign" ], "notes": [ "storeWarehouse.store.confirmSign:当前主体作为对方主体确认待签约申请,auth_status 由 1(申请中)变更为 2(已通过);入参 id(兼容 contract_id);400=id 缺失或签约状态非待签约、403=当前主体不在签约关系中或发起方自确认、404=签约关系不存在;响应 data.mode=confirm 与 data.contract 精简对象(id/store_id/warehouse_id/counterparty_name/remask/use_status/auth_status/auth_status_label/auth_end/print_quantity/has_qimen_config)", "storeWarehouse.warehouse.sign:仓库侧发起签约,当前仓库在 store_id 方、对方在 warehouse_id 方,支持签约外部合作仓库;入参 counterparty_id(兼容 warehouse_id / store_id),当前主体自动识别;响应 data.mode=initiate/already_exists/already_confirmed 与 data.contract;400=对方主体缺失/日期非法,404=签约对象不存在", "storeWarehouse.warehouse.confirmSign:仓库侧确认签约,校验逻辑与货主侧确认一致(400/403/404 同 storeWarehouse.store.confirmSign)", "代码对齐:app/service/systemMethods/storeWarehouse/store.js#confirmSign、app/service/systemMethods/storeWarehouse/warehouse.js#sign/#confirmSign 均已注册(_noNeedAuth 含三个方法,isNeedAuth=false、isNeedLogin=true);实现位于 app/service/systems/store_warehouse.js#sign/#confirmSign;权限表 method id 397「签约确定」", "仅文档变更,无业务代码修改" ], "module": "storeWarehouse" }, { "version": "2026.08.21-storage.inventory.list-stock-query", "date": "2026-08-21", "type": "updated", "summary": "storage.inventory.list 新增 where.stock_query 虚拟筛选:按商品编码/名称/货物编码/条码/SKU ID 模糊匹配库存列表", "methods": [ "storage.inventory.list" ], "notes": [ "与订单查询一致的 stock_query 虚拟筛选字段,如 where.stock_query = { operator: 'like', value: '111' }。", "解析链路:stock_query → wms_stock_warehouse(item_code/item_name/goods_code/纯数字精确 id)+ wms_stock_barcodes(barcode)→ stock_id 集合 → wms_storage.stock_id IN 过滤;无匹配时返回空列表。", "代码变更:systemMethods/storage/inventory.js#list 新增 extractStockQueryVirtualFilter(从 where 提取并移除 stock_query);systems/storage/inventory.js#getInventoryList 新增 stockQuery 参数与 resolveStockQueryToStockIds;methods/system.json 同步 where 参数文档(export 注明暂不支持 stock_query)。" ], "module": "storage" }, { "version": "2026.08.24-storage.inventory.directPutaway", "date": "2026-08-24", "type": "added", "summary": "新增 storage.inventory.directPutaway 接口:收货单直入库存(一步完成),直接写 wms_storage 并生成入库单", "methods": [ "storage.inventory.directPutaway" ], "notes": [ "新增收货单直入库存接口,与 storage.inventory.quickPutaway(转入库单,不写库存)并存,名称不交换保持兼容。", "核心流程:校验收货单(completed + is_review=true,未作废)→ 检查货主配置 policy_config.allow_receiving_direct_putaway=1 → 过滤未入库明细(storage_status!=all)并校验全部已匹配系统商品 → 事务内锁定收货单行防并发 → 创建入库单 SCRK(order_status=COMPLETED、sync_status=SUCCESS,一步完成)→ 入库单明细与收货明细一一对应(不合并,每行 count/received_quantity=actual_quantity)→ 写入 wms_entry_order_receiving 主表级绑定 → 按 stock_id 聚合悲观行锁更新 wms_stock_warehouse 总库存并写 wms_stock_transaction(order_type=SCRK,与现有链路一致)→ 按收货明细库位 space_id 逐明细写入/累加 wms_storage 并写 wms_storage_transaction(order_type=entry_order,与现有 storage.entry.commit 链路一致)→ 逐明细写入 wms_inbound_direct_log(entry_item_id/receiving_detail_id/space_id 齐全,status=committed、inbound_type=import,与 storage.entry.commit 链路口径一致,保证 scanDetail/可用数量占用统计等读取链路数据一致)→ 回填收货明细 storage_status=all/stored_quantity 与主表 storage_status(all/partial)→ 操作日志。", "日志全量写入:storage 变更记录(wms_storage_transaction,逐明细含 before/after 数量与锁定量)、stock 变更记录(wms_stock_transaction,按 SKU 聚合含 before/after 数量与锁定量)、stock 变更(wms_stock_warehouse 悲观行锁 increment quantity);操作日志(wms_operation_log)同时写三条:businessType=entry_order(ENTRY_ORDER_DIRECT_PUTAWAY)、businessType=storage(STORAGE_DIRECT_PUTAWAY,记录库位库存写入笔数与数量)、businessType=stock(STOCK_DIRECT_PUTAWAY,记录各 SKU 总量变更前后值摘要)。", "库位规则:明细 space_id 有效则按其库位入库,否则回退默认库位 1;批次取收货明细 batch_number,无批次则以入库单号作为批次号;生产/效期日期取收货明细 production_date/expiry_date。", "与 quickPutaway 的区别:directPutaway 一步直接写库存(入库单 COMPLETED),quickPutaway 仅转入库单(PENDING)不写库存,需再走 storage.entry.commit 才写库存。", "货主开关:policy_config 新增 allow_receiving_direct_putaway(默认未开启时 400 拒绝),与 allow_receiving_quick_putaway 相互独立;app/model/store_warehouse.js 的 POLICY_CONFIG_FIELDS 白名单已补充该字段(否则模型 getter sanitizeOnly 会过滤掉该键导致开关无法读取)。", "代码变更:app/service/systems/storage/inventory.js#directPutaway、app/service/systemMethods/storage/inventory.js#directPutaway(_noNeedAuth 新增 directPutaway)、methods/system.json 新增 method 文档、database/migrations/20260824 新增权限记录(path=storage.inventory.directPutaway)。" ], "module": "storage" }, { "version": "2026.09.10-order.wave.wavePickTaskList-cart-code", "date": "2026-09-10", "type": "updated", "summary": "order.wave.wavePickTaskList 新增 cart_code 筛选:按拣货车编码查询拣货任务", "methods": [ "order.wave.wavePickTaskList" ], "notes": [ "新增 cart_code 过滤字段,匹配拣货任务主表快照字段 wms_wave_pick_task.current_cart_code_snapshot(与列表返回的 current_cart_code_snapshot 同源),支持操作符对象 { operator: 'like'|'notlike'|'eq', value },默认 like;顶层 cart_code 与 where.cart_code 均支持,顶层参数优先。", "keyword 关键字搜索同步覆盖 current_cart_code_snapshot 字段(此前文档已声明支持,本次代码补齐)。", "代码变更:app/service/systemMethods/order/wave.js#normalizeWavePickTaskListRequest 新增 cart_code 顶层合并、#buildWavePickTaskListWhereClause 新增 cart_code 白名单与条件拼接(复用 appendNameCondition)。", "顺带修正:该接口失败响应未透传业务码(this.fail(msg, 400) → this.fail(msg, {}, 400/500)),并将「不支持的 operator」类入参错误归为 400,与其它 systemMethods 约定及本文档错误码一致。", "测试:test/app/service/systemMethods/order/wave.wavePickTaskList.test.js 补充 cart_code 操作符/默认模糊/顶层优先/keyword 覆盖用例,并修复原 mock 缺失 QueryTypes.SELECT 导致的既有用例失败。" ], "module": "order" }, { "version": "2026.10.26-index.getShopExpressList-productTypes", "date": "2026-10-26", "type": "updated", "summary": "index.getShopExpressList 返回的 list 每项新增 product_types 字段:[{ name, code }],按 sys_express_code 匹配 wms_express_product_type 得到,未匹配时为空数组;PDD 平台不补充该字段。", "methods": [ "index.getShopExpressList" ], "notes": [ "适用范围:仅 PDD 以外的平台(CAINIAO/DY/KS/SPH/XHS/JD 等)补充 product_types,PDD 平台保持原有返回结构不变。", "匹配规则:list 项 sys_express_code 与 wms_express_product_type.express_code 比较(trim + 大写,不区分大小写),同一 express_code 下按 code 去重;name 为空时回退为 code。", "数据来源与缓存:复用系统快递服务 getExpressProductTypeList 的全量缓存(缓存键 express:product-type:list,TTL 1 小时),缓存失效由 upsertExpressProductTypeList 在新增/更新产品类型后清理,接口不再额外直连数据库。", "容错:产品类型读取异常时仅记录 warn 日志,list 各项目 product_types 返回空数组,不影响电子面单签约列表主流程。", "JD 平台在 sys_express_code 补偿映射完成后再补充 product_types,与最终返回的 sys_express_code 一致。", "代码变更:app/service/systemMethods/index.js 新增 buildExpressProductTypeMap 与 attachExpressProductTypes,getShopExpressList 在返回前按平台补充字段(PDD 跳过、不读取产品类型缓存);methods/system.json 同步 data.list 说明与 product_types 子字段文档。" ], "module": "index" } ]