644 lines
23 KiB
JSON
644 lines
23 KiB
JSON
{
|
||
"generatedAt": "2026-05-05 17:25:14",
|
||
"generatedAtLocal": "2026-05-05 17:25:14",
|
||
"source": "remote",
|
||
"filter": {
|
||
"platform": {
|
||
"value": "web",
|
||
"label": "网页端"
|
||
},
|
||
"project": {
|
||
"value": "all",
|
||
"label": "全部"
|
||
}
|
||
},
|
||
"module": {
|
||
"name": "订单波次模块",
|
||
"key": "order.wave",
|
||
"folder": "order.wave",
|
||
"interfaceCount": 9
|
||
},
|
||
"changes": {
|
||
"fromPreviousSnapshot": {
|
||
"moduleAdded": false,
|
||
"moduleRenamed": false,
|
||
"interfaceChanges": {
|
||
"addedMethods": [
|
||
"order.wave.singleOrderFetchList"
|
||
],
|
||
"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.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(范围)"
|
||
}
|
||
],
|
||
"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": "批量解除波次。传入 ids,清理订单波次ID,并将命中的波次状态置为 -1(已取消)。仅作用于当前登录仓库。",
|
||
"description": "批量解除波次。传入 ids,清理订单波次ID,并将命中的波次状态置为 -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": "affected_order_count",
|
||
"type": "number",
|
||
"required": false,
|
||
"description": "被清理 wave_id 的订单数量"
|
||
},
|
||
{
|
||
"name": "canceled_wave_count",
|
||
"type": "number",
|
||
"required": false,
|
||
"description": "实际置为 -1 的波次数量"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"method": "order.wave.fetch",
|
||
"title": "提交波次抓取任务:该接口为异步任务提交接口,立即返回任务已受理的信息,后端异步执行实际抓取,不在接口同步返回抓取结果。客户端可通过任务 ID 或调用 order.wave.fetchTaskProgress 查询任务状态与进度。",
|
||
"description": "提交波次抓取任务:该接口为异步任务提交接口,立即返回任务已受理的信息,后端异步执行实际抓取,不在接口同步返回抓取结果。客户端可通过任务 ID 或调用 order.wave.fetchTaskProgress 查询任务状态与进度。",
|
||
"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": "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": "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 列表"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|