[
{
"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-03",
"date": "2026-05-04",
"summary": "新增订单打印模块:按波次IDs获取打印数据并自动过滤未完全分配波次",
"methods": [
"order.print.getWavePrintData"
],
"notes": [
"按波次IDs获取订单打印数据,内部去重并规范化 wave_ids,自动过滤快递未完全分配的波次;返回通过过滤的波次订单明细,按 wave_no 排序分组,并在 ext 中返回 missing_wave_ids 与 filtered_wave_ids。"
],
"type": "added"
},
{
"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": [
"该接口直接接收订单对象数组入参;订单对象应为来自待处理订单列表或详情的原始订单对象。每个订单对象必须包含 order_id 与 business_key;sys_platform_code、logistics_code 为订单对象自带字段,前端无需额外拼装或单独构造,直接原样回传订单对象即可。",
"实际的运单创建、归一化与跳过逻辑由 express.createWaybillCodePipeline 处理。",
"接口返回值与现有分配链路一致,已用统一 success 包装返回。"
],
"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-02",
"date": "2026-05-20",
"summary": "新增打印失败自动补偿能力:定时扫描并触发 print.retryFailed 批量补打",
"methods": [
"print.retryFailed"
],
"notes": [
"新增定时任务:app/schedule/print_retry_compensation.js,按仓库分组调用 print.retryFailed 进行批量补打。",
"配置项位置:config/config.default.js 的 printRetryCompensation,包含:enable(boolean, 默认 false)、intervalMs(毫秒,默认 60000)、batchSize(批量大小,默认 50)、force(boolean,默认 false)、maxRetryCount(number,默认 5)。",
"行为摘要:任务按 printRetryCompensation.intervalMs 频率查询 send_status=send_failed 或 print_status IN (print_failed, timeout),且 next_retry_at <= now 且 retry_count < maxRetryCount 的记录,按仓库分组并调用 print.retryFailed({ print_ids, warehouse_id, force }) 进行补打。",
"兼容性:print.retryFailed 支持显式传入 warehouse_id(调度任务会传入),当未提供时回退到 ctx.user.store_id;若两者均无则接口返回 400。",
"注意:当前实现中传入的 force 参数不会放宽对状态的判定(代码注释说明为“最小实现”),如需放宽需修改 print.getRetryEligibility 的逻辑。",
"回滚说明:1) 将 printRetryCompensation.enable 设为 false 并重启服务以停止新任务;2) 从部署包中移除或注释 app/schedule/print_retry_compensation.js 并重启服务;3) 如需从 methods/changes/system.json 中移除此变更,请通过生成对应 spec(change.version 设置为本条版本并 type='removed')并运行 npm run doc:api:update -- --spec= 来更新变更记录;4) 若调度已触发的补打需中止,请在调度或队列系统中停止对应任务或通过运维回退正在执行的补打逻辑。"
],
"module": "print",
"type": "added"
},
{
"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"
}
]