{ "generatedAt": "2026-05-06 17:09:32", "generatedAtLocal": "2026-05-06 17:09:32", "source": "remote", "filter": { "platform": { "value": "web", "label": "网页端" }, "project": { "value": "all", "label": "全部" } }, "module": { "name": "订单波次模块", "key": "order.wave", "folder": "order.wave", "interfaceCount": 19 }, "changes": { "fromPreviousSnapshot": { "moduleAdded": false, "moduleRenamed": false, "interfaceChanges": { "addedMethods": [], "deletedMethods": [], "paramsUpdatedMethods": [], "responseUpdatedMethods": [] } } }, "interfaces": [ { "method": "order.wave.groupOrderFetchList", "title": "按机器结构分组的可抓取列表。仅处理待处理订单(排除待审核),且排除已在波次中的订单。", "description": "按机器结构分组的可抓取列表。仅处理待处理订单(排除待审核),且排除已在波次中的订单。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "description": "分页参数,支持 page / pageSize" }, { "name": "distinguish_express", "type": "boolean", "required": false, "description": "是否区分快递(影响分组粒度)" }, { "name": "store_id", "type": "number", "required": false, "description": "货主ID(仅作为筛选条件)" }, { "name": "same_order_quantity", "type": "number", "required": false, "description": "最小同组订单数量阈值(>=)。若显式传入有效数值则按传入值使用;未传入时使用仓库配置 min_group_order_fetch_quantity(默认 13)。" }, { "name": "shop_name", "type": "string", "required": false, "description": "店铺名称(模糊匹配)" }, { "name": "include_sku", "type": "string", "required": false, "description": "仅保留包含该 SKU 的分组(页内过滤)" }, { "name": "return_order_ids", "type": "boolean", "required": false, "description": "是否在结果中返回组内订单ID列表" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "分组列表,items 示例见实现:包含 item_detail_machine/item_snapshot/group_count 等字段" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" } ] }, { "method": "order.wave.singleFetchByIds", "title": "按订单 ID 列表抓取到一个散单波次。仅处理当前仓库的待处理订单(step in [1,2,3]),排除已在波次中的订单(wave_id>0),不区分快递;成功抓取后批量写入订单操作日志;当无可抓取订单时返回 wave_id=0。", "description": "按订单 ID 列表抓取到一个散单波次。仅处理当前仓库的待处理订单(step in [1,2,3]),排除已在波次中的订单(wave_id>0),不区分快递;成功抓取后批量写入订单操作日志;当无可抓取订单时返回 wave_id=0。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids / order_ids / orderIds", "type": "array|string|number", "required": true, "description": "订单ID列表,支持数组、逗号分隔字符串或单个ID;优先使用 ids 字段" } ], "response": [ { "name": "ids", "type": "array", "required": true, "description": "请求归一化后的 ids 列表(去重且为正整数)" }, { "name": "wave_id", "type": "number", "required": true, "description": "创建的波次 ID;若无可抓取订单返回 0" }, { "name": "wave_no", "type": "string", "required": true, "description": "创建的波次号;无可抓取时为空字符串" }, { "name": "fetched_order_ids", "type": "array", "required": true, "description": "实际被抓取并分配到波次的订单ID列表" }, { "name": "fetched_order_count", "type": "number", "required": true, "description": "实际被抓取的订单数量" }, { "name": "excluded_existing_wave_order_ids", "type": "array", "required": false, "description": "原始入参中已在其它波次中的订单ID(被排除)" }, { "name": "skipped_order_ids", "type": "array", "required": false, "description": "未被抓取的订单ID(包括已存在波次、状态不符或出库中等)" }, { "name": "not_found_order_ids", "type": "array", "required": false, "description": "入参中未在数据库中找到的订单ID" } ] }, { "method": "order.wave.singleOrderFetchList", "title": "按机器结构分组的散单候选列表。仅处理待处理订单(排除待审核),且排除已在波次中的订单。与 order.wave.groupOrderFetchList 不同:groupOrderFetchList 返回满足同组订单数量 >= same_order_quantity(或仓库配置 min_group_order_fetch_quantity)的团购命中分组;singleOrderFetchList 则排除这些团购命中分组,仅返回同组订单数量小于该阈值的散单候选分组(即 < same_order_quantity)。", "description": "按机器结构分组的散单候选列表。仅处理待处理订单(排除待审核),且排除已在波次中的订单。与 order.wave.groupOrderFetchList 不同:groupOrderFetchList 返回满足同组订单数量 >= same_order_quantity(或仓库配置 min_group_order_fetch_quantity)的团购命中分组;singleOrderFetchList 则排除这些团购命中分组,仅返回同组订单数量小于该阈值的散单候选分组(即 < same_order_quantity)。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "description": "分页参数,支持 page / pageSize" }, { "name": "distinguish_express", "type": "boolean", "required": false, "description": "是否区分快递(影响分组粒度)" }, { "name": "store_id", "type": "number", "required": false, "description": "货主ID(仅作为筛选条件)" }, { "name": "same_order_quantity", "type": "number", "required": false, "description": "最小同组订单数量阈值(用于判定团购命中);本接口返回同组订单数量小于该阈值的分组。若显式传入有效数值则按传入值使用;未传入时使用仓库配置 min_group_order_fetch_quantity(默认 13)。" }, { "name": "shop_name", "type": "string", "required": false, "description": "店铺名称(模糊匹配)" }, { "name": "include_sku", "type": "string", "required": false, "description": "仅保留包含该 SKU 的分组(页内过滤)" }, { "name": "return_order_ids", "type": "boolean", "required": false, "description": "是否在结果中返回组内订单ID列表" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "散单候选分组列表,items 示例见实现:包含 item_detail_machine/item_snapshot/group_count 等字段;返回的 group_count 均小于 same_order_quantity(或仓库配置的 min_group_order_fetch_quantity)。" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" } ] }, { "method": "order.wave.batchList", "title": "波次列表查询。仅使用当前登录操作者的仓库ID作为查询约束(禁止传入 warehouse_id / warehouseId)。支持通过白名单字段进行过滤(通过 where 对象传入),接口对 wave_status 固定叠加查询状态 0/1,无需客户端传入。列表按订单数量从大到小排序,并附带波次基础信息与分配状态汇总。", "description": "波次列表查询。仅使用当前登录操作者的仓库ID作为查询约束(禁止传入 warehouse_id / warehouseId)。支持通过白名单字段进行过滤(通过 where 对象传入),接口对 wave_status 固定叠加查询状态 0/1,无需客户端传入。列表按订单数量从大到小排序,并附带波次基础信息与分配状态汇总。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "pagination", "type": "object", "required": false, "description": "分页参数,支持 page / pageSize" }, { "name": "where", "type": "object", "required": false, "description": "筛选白名单字段(object,可选)。仅支持下列字段过滤,且禁止传入 warehouse_id / warehouseId: - wave_id(等值) - wave_no(模糊) - wave_type(等值) - wave_status(等值,接口固定叠加状态 0/1) - creator(模糊) - logistics_name(模糊) - item_part_type(等值) - item_part(模糊) - item_snapshot_key(模糊) - item_detail_machine(模糊) - distinguish_express(等值) - total_orders_min / total_orders_max(范围) - processed_orders_min / processed_orders_max(范围) - storage_assignment_status(等值,string,可选,取值:未分配、部分分配、已分配;默认不传不做限制)。过滤语义:已分配=聚合后全部 fin;部分分配=不含 error,且既不是全 none,也不是全 fin;未分配=全 none 或包含 error(异常并入未分配筛选集合)。说明:返回字段 storage_assignment_status 的展示值保持不变,包含 error 时仍可显示“分配异常”;此处 where 的过滤语义会把异常计入“未分配”,以避免把过滤语义与展示值混淆。" } ], "response": [ { "name": "list", "type": "array", "required": true, "description": "波次列表,包含波次基础信息与状态汇总(order_count / storage_assignment_status / express_assignment_status / print_assignment_status)" }, { "name": "pagination", "type": "object", "required": true, "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" } ] }, { "method": "order.wave.batchCancel", "title": "提交批量解除波次异步任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理波次并执行解除操作;可通过 order.wave.batchCancelTaskProgress 查询进度与结果。", "description": "提交批量解除波次异步任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理波次并执行解除操作;可通过 order.wave.batchCancelTaskProgress 查询进度与结果。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "wave_ids / waveIds / ids", "type": "array|string|number", "required": true, "description": "波次ID列表;支持数组、逗号分隔字符串或单个ID" }, { "name": "task_id / taskId", "type": "string", "required": false, "description": "可选外部任务ID,用于幂等提交" } ], "response": [ { "name": "status", "type": "string", "required": true, "description": "提交状态,固定 success" }, { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(用于查询任务进度)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "当前仓库ID" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO8601)" }, { "name": "message", "type": "string", "required": false, "description": "受理提示信息" } ] }, { "method": "order.wave.batchCancelTaskProgress", "title": "查询批量解除波次任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。响应包含 state、progress_percent、processed_wave_count、total_wave_count;当 state 为 success/failed 时返回额外字段说明。", "description": "查询批量解除波次任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。响应包含 state、progress_percent、processed_wave_count、total_wave_count;当 state 为 success/failed 时返回额外字段说明。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "description": "任务 ID(后端生成或提交时传入)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID" }, { "name": "state", "type": "string", "required": true, "description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比(0-100)" }, { "name": "processed_wave_count", "type": "number", "required": false, "description": "已处理的波次数量" }, { "name": "total_wave_count", "type": "number", "required": false, "description": "总波次数量" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒)" }, { "name": "error_message", "type": "string", "required": false, "description": "失败时的错误信息(仅在 state=failed 时返回)" }, { "name": "error_code", "type": "string", "required": false, "description": "失败时的错误码(仅在 state=failed 时返回)" }, { "name": "result", "type": "object", "required": false, "description": "成功时返回的汇总结果(仅在 state=success 时返回),例如 { \"processed_wave_count\": number, \"canceled_wave_count\": number }" } ] }, { "method": "order.wave.batchAllocateExpress", "title": "提交批次分配快递号任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理订单并提交到快递号分配流水线。", "description": "提交批次分配快递号任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理订单并提交到快递号分配流水线。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "wave_ids / waveIds / ids", "type": "array|string|number", "required": true, "description": "波次ID列表;支持数组、逗号分隔字符串或单个ID" }, { "name": "task_id / taskId", "type": "string", "required": false, "description": "可选外部任务ID,用于幂等提交" } ], "response": [ { "name": "status", "type": "string", "required": true, "description": "提交状态,固定 success" }, { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(用于查询任务进度)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "当前仓库ID" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO8601)" }, { "name": "message", "type": "string", "required": false, "description": "受理提示信息" } ] }, { "method": "order.wave.batchAllocateExpressTaskProgress", "title": "查询批次分配快递号任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。", "description": "查询批次分配快递号任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "description": "任务 ID(后端生成或提交时传入)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID" }, { "name": "state", "type": "string", "required": true, "description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "任务关联仓库ID" }, { "name": "total_wave_count", "type": "number", "required": false, "description": "波次数量" }, { "name": "total_order_count", "type": "number", "required": false, "description": "参与分配的订单数量" }, { "name": "processed_order_count", "type": "number", "required": false, "description": "已处理订单数量" }, { "name": "success_order_count", "type": "number", "required": false, "description": "成功提交分配的订单数量" }, { "name": "failed_order_count", "type": "number", "required": false, "description": "提交分配失败的订单数量" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比(0-100)" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒)" }, { "name": "error_message", "type": "string", "required": false, "description": "失败时的错误信息" }, { "name": "error_code", "type": "string", "required": false, "description": "失败时的错误码" } ] }, { "method": "order.wave.batchRemoveExceptionOrders", "title": "提交批次移除异常订单任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取异常订单并移出波次。", "description": "提交批次移除异常订单任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取异常订单并移出波次。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "wave_ids / waveIds / ids", "type": "array|string|number", "required": true, "description": "波次ID列表;支持数组、逗号分隔字符串或单个ID" }, { "name": "task_id / taskId", "type": "string", "required": false, "description": "可选外部任务ID,用于幂等提交" } ], "response": [ { "name": "status", "type": "string", "required": true, "description": "提交状态,固定 success" }, { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(用于查询任务进度)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "当前仓库ID" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO8601)" }, { "name": "message", "type": "string", "required": false, "description": "受理提示信息" } ] }, { "method": "order.wave.batchRemoveExceptionOrdersTaskProgress", "title": "查询批次移除异常订单任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。", "description": "查询批次移除异常订单任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "description": "任务 ID(后端生成或提交时传入)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID" }, { "name": "state", "type": "string", "required": true, "description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "任务关联仓库ID" }, { "name": "total_wave_count", "type": "number", "required": false, "description": "波次数量" }, { "name": "total_order_count", "type": "number", "required": false, "description": "参与处理的订单数量" }, { "name": "processed_order_count", "type": "number", "required": false, "description": "已处理订单数量" }, { "name": "removed_order_count", "type": "number", "required": false, "description": "已成功移出波次的订单数量" }, { "name": "failed_order_count", "type": "number", "required": false, "description": "处理失败的订单数量" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比(0-100)" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒)" }, { "name": "error_message", "type": "string", "required": false, "description": "失败时的错误信息" }, { "name": "error_code", "type": "string", "required": false, "description": "失败时的错误码" } ] }, { "method": "order.wave.batchAllocateStorage", "title": "提交批次分配储位任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理订单并提交到储位分配流水线。", "description": "提交批次分配储位任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理订单并提交到储位分配流水线。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "wave_ids / waveIds / ids", "type": "array|string|number", "required": true, "description": "波次ID列表;支持数组、逗号分隔字符串或单个ID" }, { "name": "task_id / taskId", "type": "string", "required": false, "description": "可选外部任务ID,用于幂等提交" } ], "response": [ { "name": "status", "type": "string", "required": true, "description": "提交状态,固定 success" }, { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(用于查询任务进度)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "当前仓库ID" }, { "name": "accepted_at", "type": "string", "required": true, "description": "任务受理时间(ISO8601)" }, { "name": "message", "type": "string", "required": false, "description": "受理提示信息" } ] }, { "method": "order.wave.batchAllocateStorageTaskProgress", "title": "查询批次分配储位任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。", "description": "查询批次分配储位任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "description": "任务 ID(后端生成或提交时传入)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID" }, { "name": "state", "type": "string", "required": true, "description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "任务关联仓库ID" }, { "name": "total_wave_count", "type": "number", "required": false, "description": "波次数量" }, { "name": "total_order_count", "type": "number", "required": false, "description": "参与分配的订单数量" }, { "name": "processed_order_count", "type": "number", "required": false, "description": "已处理订单数量" }, { "name": "success_order_count", "type": "number", "required": false, "description": "成功提交分配的订单数量" }, { "name": "failed_order_count", "type": "number", "required": false, "description": "提交分配失败的订单数量" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比(0-100)" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务耗时(毫秒)" }, { "name": "error_message", "type": "string", "required": false, "description": "失败时的错误信息" }, { "name": "error_code", "type": "string", "required": false, "description": "失败时的错误码" } ] }, { "method": "order.wave.groupFetch", "title": "抓取团购接口(异步任务提交)", "description": "抓取团购接口(异步任务提交)", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "structure_list", "type": "array", "required": true, "description": "结构请求数组;每项必须包含 item_detail_machine(由 buildMachineStructureToken 生成的结构标识),可选 quantity(未传入时使用仓库默认或全局默认)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(后端生成的唯一标识,用于查询任务状态或结果)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "生效的仓库 ID" }, { "name": "structure_count", "type": "number", "required": true, "description": "本次入参的结构数量(structure_list 长度)" }, { "name": "default_quantity", "type": "number", "required": true, "description": "仓库默认抓取数量或全局默认值" }, { "name": "auto_fetch_disabled_marker", "type": "string", "required": true, "description": "手动抓取标记;值为 'wave_manual_fetch' 表示手动抓取" }, { "name": "fetch_mode", "type": "string", "required": false, "description": "抓取模式,值为 'group'(团购)或 'single'(散单)" }, { "name": "message", "type": "string", "required": false, "description": "受理信息提示,通常为 '任务已提交,后端异步处理中' 或失败/错误说明" } ] }, { "method": "order.wave.singleFetch", "title": "抓取散单接口(异步任务提交)", "description": "抓取散单接口(异步任务提交)", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "structure_list", "type": "array", "required": true, "description": "结构请求数组;每项必须包含 item_detail_machine(由 buildMachineStructureToken 生成的结构标识)并包含必填字段 max_fetch_quantity(最大抓取上限,订单数,正整数);可选 quantity(未传入时使用仓库默认或全局默认)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(后端生成的唯一标识,用于查询任务状态或结果)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "生效的仓库 ID" }, { "name": "structure_count", "type": "number", "required": true, "description": "本次入参的结构数量(structure_list 长度)" }, { "name": "default_quantity", "type": "number", "required": true, "description": "仓库默认抓取数量或全局默认值" }, { "name": "auto_fetch_disabled_marker", "type": "string", "required": true, "description": "手动抓取标记;值为 'wave_manual_fetch' 表示手动抓取" }, { "name": "fetch_mode", "type": "string", "required": false, "description": "抓取模式,值为 'group'(团购)或 'single'(散单)" }, { "name": "max_fetch_quantity", "type": "number", "required": false, "description": "提交时生效的最大抓取上限(订单数,正整数)" }, { "name": "message", "type": "string", "required": false, "description": "受理信息提示,通常为 '任务已提交,后端异步处理中' 或失败/错误说明" } ] }, { "method": "order.wave.fetch", "title": "兼容别名(等同 groupFetch)", "description": "兼容别名(等同 groupFetch)", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "structure_list", "type": "array", "required": true, "description": "结构请求数组;每项必须包含 item_detail_machine(由 buildMachineStructureToken 生成的结构标识),可选 quantity(未传入时使用仓库默认或全局默认)" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID(后端生成的唯一标识,用于查询任务状态或结果)" }, { "name": "warehouse_id", "type": "number", "required": true, "description": "生效的仓库 ID" }, { "name": "structure_count", "type": "number", "required": true, "description": "本次入参的结构数量(structure_list 长度)" }, { "name": "default_quantity", "type": "number", "required": true, "description": "仓库默认抓取数量或全局默认值" }, { "name": "auto_fetch_disabled_marker", "type": "string", "required": true, "description": "手动抓取标记;值为 'wave_manual_fetch' 表示手动抓取" }, { "name": "fetch_mode", "type": "string", "required": false, "description": "抓取模式,值为 'group'(团购)或 'single'(散单)" }, { "name": "message", "type": "string", "required": false, "description": "受理信息提示,通常为 '任务已提交,后端异步处理中' 或失败/错误说明" } ] }, { "method": "order.wave.fetchTaskProgress", "title": "查询波次抓取任务进度:按 task_id 查询任务状态与进度;兼容 taskId 参数名。", "description": "查询波次抓取任务进度:按 task_id 查询任务状态与进度;兼容 taskId 参数名。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "task_id / taskId", "type": "string", "required": true, "description": "任务 ID(后端生成的唯一标识),兼容旧参数名 taskId,可从 order.wave.fetch 的返回值中获取" } ], "response": [ { "name": "task_id", "type": "string", "required": true, "description": "任务 ID" }, { "name": "status", "type": "string", "required": true, "description": "任务状态枚举:submitted(已受理)/ running(进行中)/ success(成功)/ failed(失败)/ not_found(未找到)" }, { "name": "warehouse_id", "type": "number", "required": false, "description": "生效的仓库 ID(若任务关联仓库时返回)" }, { "name": "structure_count", "type": "number", "required": false, "description": "本次任务的结构数量(structure_list 长度)" }, { "name": "finished_structure_count", "type": "number", "required": false, "description": "已完成抓取的结构数量" }, { "name": "progress_percent", "type": "number", "required": false, "description": "进度百分比(0-100,可能为小数)" }, { "name": "total_fetched_quantity", "type": "number", "required": false, "description": "已抓取的总件数" }, { "name": "duration_ms", "type": "number", "required": false, "description": "任务已运行时长,毫秒级" }, { "name": "error", "type": "string", "required": false, "description": "错误信息,仅当 status=failed 时返回" }, { "name": "fetch_mode", "type": "string", "required": false, "description": "抓取模式,值为 'group'(团购)或 'single'(散单);single 模式时可能返回下列额外字段" }, { "name": "max_fetch_quantity", "type": "number", "required": false, "description": "当 fetch_mode=single 时返回的最大抓取上限(订单数,正整数)" }, { "name": "limit_reached", "type": "boolean", "required": false, "description": "当 fetch_mode=single 时指示是否已达到 max_fetch_quantity 限制" }, { "name": "stop_reason", "type": "string", "required": false, "description": "任务停止原因(如达到上限、人工停止或其他失败原因)" }, { "name": "update_time", "type": "string", "required": false, "description": "最近一次状态更新时间,ISO8601 字符串" }, { "name": "message", "type": "string", "required": false, "description": "额外提示信息" } ] }, { "method": "order.wave.batchAutoGrouping", "title": "批量将波次状态修改为 0(自动加团中),仅作用当前登录仓库命中的波次。限制条件: - 跳过已打印及之后状态的波次(wave_status >= 2); - 跳过 total_orders >= 仓库配置 max_wave_quantity 的波次。被跳过的波次不会被修改为自动加团中。", "description": "批量将波次状态修改为 0(自动加团中),仅作用当前登录仓库命中的波次。限制条件: - 跳过已打印及之后状态的波次(wave_status >= 2); - 跳过 total_orders >= 仓库配置 max_wave_quantity 的波次。被跳过的波次不会被修改为自动加团中。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array|string|number", "required": true, "description": "波次ID 列表;支持数组、逗号分隔字符串或单个ID" } ], "response": [ { "name": "ids", "type": "array", "required": false, "description": "归一化后的请求ID" }, { "name": "affected_wave_ids", "type": "array", "required": false, "description": "实际命中的波次ID" }, { "name": "updated_wave_count", "type": "number", "required": false, "description": "实际更新数量" }, { "name": "skipped_wave_ids", "type": "array", "required": false, "description": "被跳过的波次ID数组(不修改状态)" }, { "name": "skipped_wave_count", "type": "number", "required": false, "description": "被跳过的波次数量" }, { "name": "skipped_details", "type": "array", "required": false, "description": "被跳过的波次明细數組,元素包含 wave_id 与 reason,reason 枚举 printed_or_after_printed / reach_max_wave_quantity" } ] }, { "method": "order.wave.batchFinishAutoGrouping", "title": "批量结束自动加团,将当前仓库命中且 wave_status=0 的波次改为 1(已就绪)。", "description": "批量结束自动加团,将当前仓库命中且 wave_status=0 的波次改为 1(已就绪)。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids", "type": "array|string|number", "required": true, "description": "波次ID 列表;支持数组、逗号分隔字符串或单个ID" } ], "response": [ { "name": "ids", "type": "array", "required": false, "description": "归一化后的请求ID" }, { "name": "affected_wave_ids", "type": "array", "required": false, "description": "实际命中的波次ID" }, { "name": "updated_wave_ids", "type": "array", "required": false, "description": "实际更新为已就绪的波次ID" }, { "name": "updated_wave_count", "type": "number", "required": false, "description": "实际更新数量" } ] }, { "method": "order.wave.batchRemoveOrders", "title": "按订单ID批量移出波次;仅处理当前仓库的待处理订单表中非待审核订单(step in [1,2,3])。操作会清空订单的 wave_id/wave_no,并在同一事务内回写 wms_wave_batch 表:重算 total_orders,若波次被清空则将 wave_status 置为 -1。仓库上下文来自当前登录用户(ctx.user.store_id)。", "description": "按订单ID批量移出波次;仅处理当前仓库的待处理订单表中非待审核订单(step in [1,2,3])。操作会清空订单的 wave_id/wave_no,并在同一事务内回写 wms_wave_batch 表:重算 total_orders,若波次被清空则将 wave_status 置为 -1。仓库上下文来自当前登录用户(ctx.user.store_id)。", "endpoint": "/system", "authRequired": false, "loginRequired": true, "status": { "isUsed": false, "isPlaceholder": false }, "headers": [ { "name": "Authorization", "type": "string", "required": true, "description": "Bearer token" } ], "params": [ { "name": "ids / order_ids / orderIds / order_id / orderId / id", "type": "array|string|number", "required": true, "description": "订单 ID 列表;支持数组、逗号分隔字符串或单个 ID,以上别名均可用(ids、order_ids、orderIds、order_id、orderId、id)" } ], "response": [ { "name": "ids", "type": "array", "required": true, "description": "归一化后的请求 ID 列表" }, { "name": "removed_order_ids", "type": "array", "required": true, "description": "实际被移出波次的订单 ID 列表" }, { "name": "removed_order_count", "type": "number", "required": true, "description": "被移出波次的订单数量" }, { "name": "affected_wave_ids", "type": "array", "required": true, "description": "本次操作涉及的波次 ID 列表" }, { "name": "updated_wave_ids", "type": "array", "required": true, "description": "实际更新了 total_orders 的波次 ID 列表" }, { "name": "emptied_wave_ids", "type": "array", "required": true, "description": "被清空且已置为 wave_status=-1 的波次 ID 列表" } ] } ] }