From d11ed3b2a2ab0c8c3495ef895f788aca012388e1 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Mon, 27 Jul 2026 17:46:26 +0800 Subject: [PATCH] =?UTF-8?q?feat(order.pendingOrder):=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=20allocateSubOrderNumber=20=E5=AD=90=E5=8D=95=E5=8F=B7?= =?UTF-8?q?=E5=BC=82=E6=AD=A5=E5=88=86=E9=85=8D=E6=8E=A5=E5=8F=A3=E4=B8=8E?= =?UTF-8?q?=E8=BF=9B=E5=BA=A6=E6=9F=A5=E8=AF=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../systemMethods/order/pendingOrder.js | 417 +++++++++++++++++- methods/changes/system.json | 21 + methods/system.json | 168 +++++++ 3 files changed, 603 insertions(+), 3 deletions(-) diff --git a/app/service/systemMethods/order/pendingOrder.js b/app/service/systemMethods/order/pendingOrder.js index ebfa97a..a5dcaf2 100644 --- a/app/service/systemMethods/order/pendingOrder.js +++ b/app/service/systemMethods/order/pendingOrder.js @@ -53,6 +53,18 @@ const SYNC_ORDER_IDS_PROGRESS_MAP = Object.freeze({ unknown: 0, }); +const ALLOCATE_SUB_ORDER_TASK_CACHE_KEY_PREFIX = 'order:pending:allocate_sub_order:request:'; +const ALLOCATE_SUB_ORDER_TASK_CACHE_TTL_SECONDS = 60 * 60 * 2; +const ALLOCATE_SUB_ORDER_PROGRESS_MAP = Object.freeze({ + submitted: 5, + running: 50, + success: 100, + partial: 80, + failed: 100, + not_found: 0, + unknown: 0, +}); + /** * 中国行政区划反向查询表。 * @@ -528,9 +540,9 @@ class PendingOrderService extends OrderBaseService { constructor(ctx) { super(ctx); const _noNeedLogin = ''; - const _noNeedRight = 'list,pendingOrder,reverseReviewOrder,markPendingOutboundOrder,cancelOrder,allocateExpressCode,allocateExpressCodeTaskProgress,allocateStorage,allocateStorageProgress,cancelAllocateStorage,syncOrderIds,syncOrderIdsProgress,updateOrderPlatform,updateOrderExpress,updateRemark,updateAddress,cloneOrder,createOrder,downloadCreateTemplate,parseAddress,batchIntercept,batchInterceptTaskProgress,batchLock,batchLockTaskProgress,batchUnlock,batchUnlockTaskProgress,batchUnintercept,batchUninterceptTaskProgress,manualWaybill'; - const _noNeedLog = 'list,markPendingOutboundOrder,cancelOrder,allocateExpressCode,allocateExpressCodeTaskProgress,allocateStorage,allocateStorageProgress,cancelAllocateStorage,syncOrderIds,syncOrderIdsProgress,parseAddress,batchIntercept,batchInterceptTaskProgress,batchLock,batchLockTaskProgress,batchUnlock,batchUnlockTaskProgress,batchUnintercept,batchUninterceptTaskProgress,manualWaybill'; - const _noNeedAuth = 'list,pendingOrder,reverseReviewOrder,markPendingOutboundOrder,cancelOrder,allocateExpressCode,allocateExpressCodeTaskProgress,allocateStorage,allocateStorageProgress,cancelAllocateStorage,syncOrderIds,syncOrderIdsProgress,updateOrderPlatform,updateOrderExpress,updateRemark,updateAddress,cloneOrder,createOrder,downloadCreateTemplate,parseAddress,batchIntercept,batchInterceptTaskProgress,batchLock,batchLockTaskProgress,batchUnlock,batchUnlockTaskProgress,batchUnintercept,batchUninterceptTaskProgress,manualWaybill'; + const _noNeedRight = 'list,pendingOrder,reverseReviewOrder,markPendingOutboundOrder,cancelOrder,allocateExpressCode,allocateExpressCodeTaskProgress,allocateStorage,allocateStorageProgress,cancelAllocateStorage,syncOrderIds,syncOrderIdsProgress,updateOrderPlatform,updateOrderExpress,updateRemark,updateAddress,cloneOrder,createOrder,downloadCreateTemplate,parseAddress,batchIntercept,batchInterceptTaskProgress,batchLock,batchLockTaskProgress,batchUnlock,batchUnlockTaskProgress,batchUnintercept,batchUninterceptTaskProgress,manualWaybill,allocateSubOrderNumber,allocateSubOrderNumberProgress'; + const _noNeedLog = 'list,markPendingOutboundOrder,cancelOrder,allocateExpressCode,allocateExpressCodeTaskProgress,allocateStorage,allocateStorageProgress,cancelAllocateStorage,syncOrderIds,syncOrderIdsProgress,parseAddress,batchIntercept,batchInterceptTaskProgress,batchLock,batchLockTaskProgress,batchUnlock,batchUnlockTaskProgress,batchUnintercept,batchUninterceptTaskProgress,manualWaybill,allocateSubOrderNumber,allocateSubOrderNumberProgress'; + const _noNeedAuth = 'list,pendingOrder,reverseReviewOrder,markPendingOutboundOrder,cancelOrder,allocateExpressCode,allocateExpressCodeTaskProgress,allocateStorage,allocateStorageProgress,cancelAllocateStorage,syncOrderIds,syncOrderIdsProgress,updateOrderPlatform,updateOrderExpress,updateRemark,updateAddress,cloneOrder,createOrder,downloadCreateTemplate,parseAddress,batchIntercept,batchInterceptTaskProgress,batchLock,batchLockTaskProgress,batchUnlock,batchUnlockTaskProgress,batchUnintercept,batchUninterceptTaskProgress,manualWaybill,allocateSubOrderNumber,allocateSubOrderNumberProgress'; this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth); } @@ -5917,6 +5929,405 @@ class PendingOrderService extends OrderBaseService { } } + // ========== allocateSubOrderNumber 子单号分配 ========== + + /** + * 分配子单号(异步任务模式)。 + * + * 为指定订单按 business_key(从 2 开始)逐个子单号分配运单号。 + * 将所有 business_key 全量传入 createWaybillCodePipeline, + * 由 pipeline 内部事务 + UNIQUE(order_id,business_key,status,warehouse_id) 索引 + * 保证并发安全:已分配(status=1)自动跳过,未分配 INSERT status=0 占位后分配。 + * + * @param {Object} data 请求体。 + * @param {number|string} data.order_id 订单ID(必填)。 + * @param {number} data.sub_order_count 子单号数量(必填,>=1)。 + * @return {Promise} 统一 success 包装,立即返回 task_id。 + */ + async allocateSubOrderNumber(data = {}) { + const requestData = this.isPlainObject(data) ? data : {}; + const warehouseId = this.getWarehouseId(); + + // 1. 参数校验 + const orderId = Number(requestData.order_id); + if (!Number.isInteger(orderId) || orderId <= 0) { + throw new Error('order_id 必须为正整数'); + } + + const subOrderCount = Number(requestData.sub_order_count); + if (!Number.isInteger(subOrderCount) || subOrderCount < 1) { + throw new Error('sub_order_count 必须为正整数且 >= 1'); + } + + // 2. 查询订单并校验状态(待处理:step in [1,2,3] 且 outbound_status != 'padding') + const model = await this.getOrderModel('order', warehouseId); + const where = this.buildOrderWhere([ orderId ], warehouseId); + const order = await model.findOne({ + where, + attributes: [ 'id', 'step', 'outbound_status', 'warehouse_id', 'store_id', 'sys_platform_code', 'logistics_code', 'sys_platform_name', 'logistics_name' ], + raw: true, + }); + + if (!order) { + throw new Error(`订单 ${orderId} 不存在或不属于当前仓库`); + } + + const allowedSteps = new Set([ 1, 2, 3 ]); + if (!allowedSteps.has(order.step)) { + throw new Error(`订单 ${orderId} 当前步骤为 ${order.step},仅允许待处理状态(step 1/2/3)的订单分配子单号`); + } + + if (order.outbound_status === PENDING_OUTBOUND_STATUS) { + throw new Error(`订单 ${orderId} 已标记待出库,不允许分配子单号`); + } + + // 3. 计算 business_key 列表(从 2 开始) + const orderExpressModel = this.ctx.model && this.ctx.model.OrderExpress; + if (!orderExpressModel) { + throw new Error('OrderExpress 模型未加载'); + } + + const businessKeys = []; + for (let i = 0; i < subOrderCount; i++) { + businessKeys.push(2 + i); + } + + // 4. 预查已有的已分配运单号(status=1),仅用于初始 details 展示与全部跳过优化 + const { Op } = this.app.Sequelize; + const existingCompleted = await orderExpressModel.findAll({ + where: { + order_id: orderId, + warehouse_id: Number(order.warehouse_id) || warehouseId, + status: 1, + business_key: { [Op.in]: businessKeys }, + }, + attributes: [ 'business_key', 'waybill_code' ], + raw: true, + }); + + const completedBusinessKeyMap = new Map(); + if (Array.isArray(existingCompleted)) { + for (const row of existingCompleted) { + completedBusinessKeyMap.set(Number(row.business_key), String(row.waybill_code || '').trim()); + } + } + + // 5. 生成任务ID,立即返回 + const taskId = `sub_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`; + const taskPayload = { + task_id: taskId, + order_id: orderId, + status: 'submitted', + progress: ALLOCATE_SUB_ORDER_PROGRESS_MAP.submitted, + message: '子单号分配任务已提交', + result: { + total_count: businessKeys.length, + skip_count: completedBusinessKeyMap.size, + pending_count: businessKeys.length - completedBusinessKeyMap.size, + business_keys: businessKeys, + skipped_business_keys: businessKeys.filter(bk => completedBusinessKeyMap.has(bk)), + pending_business_keys: businessKeys.filter(bk => !completedBusinessKeyMap.has(bk)), + details: businessKeys.map(bk => ({ + business_key: bk, + status: completedBusinessKeyMap.has(bk) ? 'skipped' : 'pending', + waybill_code: completedBusinessKeyMap.get(bk) || null, + })), + }, + error: '', + }; + await this.setAllocateSubOrderTaskProgress(taskId, taskPayload); + + // 6. 如果全部已分配,跳过 pipeline 直接完成 + if (completedBusinessKeyMap.size === businessKeys.length) { + await this.setAllocateSubOrderTaskProgress(taskId, { + ...taskPayload, + status: 'success', + progress: ALLOCATE_SUB_ORDER_PROGRESS_MAP.success, + message: '子单号分配完成(全部已分配,无待处理项)', + }); + return this.success('ok', { + ...taskPayload, + status: 'success', + progress: ALLOCATE_SUB_ORDER_PROGRESS_MAP.success, + message: '子单号分配完成(全部已分配,无待处理项)', + update_time: Date.now(), + }); + } + + // 7. 后台异步执行分配(全量 business_key 传入 pipeline,由其内部事务保证去重与并发安全) + const orderWarehouseId = Number(order.warehouse_id) || warehouseId; + setImmediate(async () => { + try { + await this.setAllocateSubOrderTaskProgress(taskId, { + ...taskPayload, + status: 'running', + progress: ALLOCATE_SUB_ORDER_PROGRESS_MAP.running, + message: '子单号分配处理中', + }); + + // 全量传入(含已分配的),pipeline 内部 createWaybillCode 事务会跳过 status=1 的记录 + const ordersForPipeline = businessKeys.map(bk => ({ + order_id: orderId, + business_key: bk, + sys_platform_code: order.sys_platform_code, + logistics_code: order.logistics_code, + sys_platform_name: order.sys_platform_name, + logistics_name: order.logistics_name, + store_id: order.store_id, + })); + + const pipelineResult = await this.service.systems.express.createWaybillCodePipeline( + ordersForPipeline, + { awaitTasks: true } + ); + + // 回查最终分配结果 + const updatedDetails = await this.buildSubOrderDetails(orderId, orderWarehouseId, businessKeys); + + const successCount = updatedDetails.filter(d => d.status === 'allocated' || d.status === 'skipped').length; + const isPartial = successCount < businessKeys.length; + + await this.setAllocateSubOrderTaskProgress(taskId, { + ...taskPayload, + status: isPartial ? 'partial' : 'success', + progress: isPartial ? ALLOCATE_SUB_ORDER_PROGRESS_MAP.partial : ALLOCATE_SUB_ORDER_PROGRESS_MAP.success, + message: isPartial + ? `子单号分配部分完成(${successCount}/${businessKeys.length})` + : '子单号分配完成', + result: { + ...taskPayload.result, + pipeline_result: pipelineResult, + details: updatedDetails, + }, + }); + } catch (error) { + const errorMessage = error && error.message ? error.message : String(error); + + await this.setAllocateSubOrderTaskProgress(taskId, { + ...taskPayload, + status: 'failed', + progress: ALLOCATE_SUB_ORDER_PROGRESS_MAP.failed, + message: '子单号分配失败', + error: errorMessage, + }); + } + }); + + return this.success('ok', { + ...taskPayload, + update_time: Date.now(), + }); + } + + /** + * 查询子单号分配任务进度。 + * + * 可按 task_id 或 business_key 查询。 + * 若传入 business_key,返回该 business_key 对应的分配详情。 + * + * @param {Object} data 请求体。 + * @param {string} data.task_id 任务ID。 + * @param {string} data.taskId 任务ID(驼峰写法)。 + * @param {number} [data.business_key] 子单号业务ID(可选,按业务ID过滤)。 + * @param {number} [data.businessKey] 子单号业务ID(可选,驼峰写法)。 + * @return {Promise} 统一 success 包装。 + */ + async allocateSubOrderNumberProgress(data = {}) { + const requestData = this.isPlainObject(data) ? data : {}; + const taskId = String(requestData.task_id || requestData.taskId || '').trim(); + const businessKey = Number(requestData.business_key || requestData.businessKey); + + if (!taskId) { + return this.success('ok', { + task_id: '', + status: 'not_found', + progress: ALLOCATE_SUB_ORDER_PROGRESS_MAP.not_found, + message: '任务不存在', + result: null, + error: '', + update_time: Date.now(), + }); + } + + const cachedTask = await this.getAllocateSubOrderTaskProgress(taskId); + if (!cachedTask) { + return this.success('ok', { + task_id: taskId, + status: 'not_found', + progress: ALLOCATE_SUB_ORDER_PROGRESS_MAP.not_found, + message: '任务不存在', + result: null, + error: '', + update_time: Date.now(), + }); + } + + // 如果传入了 business_key,过滤出该业务ID对应的详情 + let filteredResult = cachedTask.result; + if (Number.isInteger(businessKey) && businessKey > 0 && cachedTask.result) { + const details = Array.isArray(cachedTask.result.details) ? cachedTask.result.details : []; + const matchedDetail = details.find(d => Number(d.business_key) === businessKey); + filteredResult = { + ...cachedTask.result, + filtered_business_key: businessKey, + matched_detail: matchedDetail || null, + }; + } + + return this.success('ok', { + ...cachedTask, + result: filteredResult, + update_time: cachedTask.update_time || Date.now(), + }); + } + + // ========== allocateSubOrderNumber 缓存工具方法 ========== + + /** + * 获取子单号分配任务缓存键。 + * + * @param {string} taskId 任务ID。 + * @return {string} 缓存键。 + */ + getAllocateSubOrderTaskCacheKey(taskId = '') { + const normalizedTaskId = String(taskId || '').trim(); + if (!normalizedTaskId) { + return ''; + } + return `${ALLOCATE_SUB_ORDER_TASK_CACHE_KEY_PREFIX}${normalizedTaskId}`; + } + + /** + * 写入子单号分配任务进度。 + * + * @param {string} taskId 任务ID。 + * @param {Object} payload 任务状态与结果。 + * @return {Promise} + */ + async setAllocateSubOrderTaskProgress(taskId = '', payload = {}) { + const cacheKey = this.getAllocateSubOrderTaskCacheKey(taskId); + if (!cacheKey || typeof this.app.setCacheAsync !== 'function') { + return; + } + + const safePayload = this.isPlainObject(payload) ? payload : {}; + const progressPayload = { + task_id: String(taskId || '').trim(), + order_id: safePayload.order_id || null, + status: String(safePayload.status || 'unknown').trim(), + progress: Number(safePayload.progress || 0), + message: String(safePayload.message || ''), + result: safePayload.result || null, + error: String(safePayload.error || ''), + update_time: Date.now(), + }; + + try { + await this.app.setCacheAsync(cacheKey, progressPayload, ALLOCATE_SUB_ORDER_TASK_CACHE_TTL_SECONDS); + } catch (error) { + this.ctx.logger.warn('[pendingOrder.allocateSubOrderNumber] 写入任务进度缓存失败: %s', error && error.message ? error.message : error); + } + } + + /** + * 读取子单号分配任务进度。 + * + * @param {string} taskId 任务ID。 + * @return {Promise} 任务缓存结果。 + */ + async getAllocateSubOrderTaskProgress(taskId = '') { + const cacheKey = this.getAllocateSubOrderTaskCacheKey(taskId); + if (!cacheKey || typeof this.app.getCacheAsync !== 'function') { + return null; + } + + try { + const cached = await this.app.getCacheAsync(cacheKey); + if (!this.isPlainObject(cached)) { + return null; + } + return cached; + } catch (error) { + this.ctx.logger.warn('[pendingOrder.allocateSubOrderNumber] 读取任务进度缓存失败: %s', error && error.message ? error.message : error); + return null; + } + } + + /** + * 回查子单号分配结果详情(pipeline 执行后调用)。 + * + * 根据 order_express 表最终状态判断每个 business_key 的结果: + * - status=1 且 waybill_code 非空 → allocated(本次分配成功或之前已分配) + * - status=0 → pipeline 占位但 API 未完成 → failed + * - 无记录 → failed(pipeline 未处理到) + * + * @param {number} orderId 订单ID。 + * @param {number} warehouseId 仓库ID。 + * @param {number[]} businessKeys 全部 business_key 列表。 + * @return {Promise>} 每个 business_key 的分配详情。 + */ + async buildSubOrderDetails(orderId, warehouseId, businessKeys) { + const orderExpressModel = this.ctx.model && this.ctx.model.OrderExpress; + if (!orderExpressModel) { + return businessKeys.map(bk => ({ + business_key: bk, + status: 'unknown', + waybill_code: null, + note: 'OrderExpress 模型未加载', + })); + } + + const { Op } = this.app.Sequelize; + const allRecords = await orderExpressModel.findAll({ + where: { + order_id: orderId, + warehouse_id: warehouseId, + business_key: { [Op.in]: businessKeys }, + }, + attributes: [ 'business_key', 'waybill_code', 'status' ], + raw: true, + }); + + const recordMap = new Map(); + if (Array.isArray(allRecords)) { + for (const row of allRecords) { + // 同一 business_key 可能有多条(status 不同),优先取 status=1 的 + const existing = recordMap.get(Number(row.business_key)); + if (!existing || Number(row.status) === 1) { + recordMap.set(Number(row.business_key), row); + } + } + } + + return businessKeys.map(bk => { + const record = recordMap.get(bk); + if (record && Number(record.status) === 1 && String(record.waybill_code || '').trim()) { + return { + business_key: bk, + status: 'allocated', + waybill_code: String(record.waybill_code || '').trim(), + note: '子单号分配成功', + }; + } + + if (record && Number(record.status) === 0) { + return { + business_key: bk, + status: 'failed', + waybill_code: null, + note: '运单占位已创建但 API 未返回运单号(status=0)', + }; + } + + return { + business_key: bk, + status: 'failed', + waybill_code: null, + note: '未找到分配的运单记录', + }; + }); + } + } module.exports = PendingOrderService; diff --git a/methods/changes/system.json b/methods/changes/system.json index b6c7084..6913765 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,25 @@ [ + { + "version": "2026.07.27-system-02", + "date": "2026-07-27", + "type": "added", + "summary": "新增 order.pendingOrder.allocateSubOrderNumber:待处理订单分配子单号(异步任务),business_key 从 2 开始递增,跳过已分配运单号;新增 allocateSubOrderNumberProgress 按 task_id/business_key 查询进度", + "methods": [ + "order.pendingOrder.allocateSubOrderNumber", + "order.pendingOrder.allocateSubOrderNumberProgress" + ], + "notes": [ + "新增 allocateSubOrderNumber:入参 order_id + sub_order_count,按 business_key 2..(2+count-1) 全量传入 createWaybillCodePipeline。", + "并发安全:全量传入 pipeline,由其内部事务 + UNIQUE(order_id,business_key,status,warehouse_id) 索引保证并发去重。", + "pipeline 内部 createWaybillCode 事务:status=1 已分配→跳过;status=0 占位中→复用;无记录→INSERT status=0 占位。", + "异步任务模式:请求立即返回 task_id(sub_ 前缀),后台 setImmediate 执行,进度通过 Redis 缓存追踪。", + "新增 allocateSubOrderNumberProgress:支持 task_id 查整体进度,business_key 可选参数过滤单个业务ID的详情。", + "进度状态 submitted→running→success/partial/failed,progress 对应 5/50/80/100。", + "result.details 数组记录每个 business_key 的 status(skipped/allocated/failed/pending)与 waybill_code。", + "buildSubOrderDetails 回查最终状态:status=1+waybill→allocated,status=0→failed,无记录→failed。" + ], + "module": "order.pendingOrder" + }, { "version": "2026.07.27-system-01", "date": "2026-07-27", diff --git a/methods/system.json b/methods/system.json index d660c3c..3476756 100644 --- a/methods/system.json +++ b/methods/system.json @@ -25847,6 +25847,174 @@ } ] }, + { + "method": "order.pendingOrder.allocateSubOrderNumber", + "description": "分配子单号(异步任务模式)。为指定订单按 business_key(从 2 开始)全量传入 createWaybillCodePipeline,由其内部事务 + UNIQUE(order_id,business_key,status,warehouse_id) 索引保证并发安全:已分配(status=1)自动跳过,未分配 INSERT status=0 占位后分配。请求立即返回 task_id(sub_ 前缀),后续通过 allocateSubOrderNumberProgress 按 task_id 或 business_key 查询进度与结果。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "order_id", + "type": "number", + "required": true, + "source": "body", + "description": "订单 ID,必须为正整数" + }, + { + "name": "sub_order_count", + "type": "number", + "required": true, + "source": "body", + "description": "子单号数量,>= 1。business_key 从 2 开始递增,如 count=1 则创建 business_key=2,count=3 则创建 2/3/4" + } + ], + "response": [ + { + "name": "task_id", + "type": "string", + "required": true, + "description": "任务 ID(sub_ 前缀),用于查询进度" + }, + { + "name": "order_id", + "type": "number", + "required": true, + "description": "订单 ID" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "任务状态:submitted/running/success/partial/failed" + }, + { + "name": "progress", + "type": "number", + "required": true, + "description": "进度百分比:5/50/80/100" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "任务状态说明" + }, + { + "name": "result", + "type": "object", + "required": true, + "description": "分配结果摘要,含 total_count/skip_count/pending_count/business_keys/skipped_business_keys/pending_business_keys/details 等字段" + } + ], + "errors": [ + { + "code": 400, + "message": "order_id 必须为正整数" + }, + { + "code": 400, + "message": "sub_order_count 必须为正整数且 >= 1" + }, + { + "code": 400, + "message": "订单不存在或不属于当前仓库" + }, + { + "code": 400, + "message": "订单当前步骤不在允许范围,仅允许待处理状态(step 1/2/3)的订单分配子单号" + }, + { + "code": 400, + "message": "订单已标记待出库,不允许分配子单号" + }, + { + "code": 500, + "message": "内部错误:OrderExpress 模型未加载或运单分配链路异常" + } + ] + }, + { + "method": "order.pendingOrder.allocateSubOrderNumberProgress", + "description": "查询子单号分配任务进度。可按 task_id 查询整体进度,也可传入 business_key 进一步过滤该业务ID对应的分配详情与最终结果。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "task_id", + "type": "string", + "required": true, + "source": "body", + "description": "任务 ID(返回的 task_id),支持 task_id 或 taskId 两种写法" + }, + { + "name": "business_key", + "type": "number", + "required": false, + "source": "body", + "description": "子单号业务ID(可选),传入后返回该 business_key 对应的分配详情。支持 business_key 或 businessKey 两种写法" + } + ], + "response": [ + { + "name": "task_id", + "type": "string", + "required": true, + "description": "任务 ID" + }, + { + "name": "order_id", + "type": "number", + "required": true, + "description": "订单 ID" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "任务状态:submitted/running/success/partial/failed/not_found" + }, + { + "name": "progress", + "type": "number", + "required": true, + "description": "进度百分比" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "任务状态说明" + }, + { + "name": "result", + "type": "object", + "required": true, + "description": "分配结果。若传了 business_key,额外返回 filtered_business_key 与 matched_detail" + } + ], + "errors": [ + { + "code": 500, + "message": "查询缓存异常" + } + ] + }, { "method": "order.bindExpressPackageMaterialByWaybill", "description": "按运单号绑定包材。仅需传入运单号与包材ID,系统自动根据运单号反查对应订单运单记录并绑定包材,无需传入订单ID。",