From 635e86f984e74128cc18029e4024df3a2c529b5a Mon Sep 17 00:00:00 2001 From: liufumingren Date: Wed, 29 Jul 2026 13:57:04 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E6=8F=90=E4=BA=A4=E5=BD=93=E5=89=8D?= =?UTF-8?q?=E6=89=80=E6=9C=89=E5=8F=98=E6=9B=B4=EF=BC=8C=E5=87=86=E5=A4=87?= =?UTF-8?q?=E5=BC=80=E5=A7=8B=20allocateSubOrderNumber=20step=3D4=20?= =?UTF-8?q?=E6=94=B9=E9=80=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- app/model/after_sale_work_order.js | 267 ++++++++ app/model/after_sale_work_order_step.js | 99 +++ app/model/print_computer.js | 6 - app/service/qimenMethods/order.js | 73 +- .../systemMethods/order/pendingOrder.js | 121 +++- app/service/systemMethods/printComputer.js | 2 +- app/service/systems/express_platform.js | 28 +- app/service/systems/printComputer.js | 10 +- database/designs/after-sale-api-design.md | 644 ++++++++++++++++++ .../designs/after-sale-work-order-design.md | 440 ++++++++++++ database/designs/waybill-module-design.md | 579 ++++++++++++++++ ...remote-play-url-from-wms-print-computer.js | 28 + ...g-config-fields-from-wms-print-computer.js | 43 ++ ...cording-directory-to-wms-print-computer.js | 28 + ...120000-create-wms-after-sale-work-order.js | 215 ++++++ ...rding-size-fields-to-wms-print-computer.js | 35 + ...0-create-wms-after-sale-work-order-step.js | 115 ++++ methods/changes/system.json | 43 ++ methods/system.json | 47 ++ 19 files changed, 2792 insertions(+), 31 deletions(-) create mode 100644 app/model/after_sale_work_order.js create mode 100644 app/model/after_sale_work_order_step.js create mode 100644 database/designs/after-sale-api-design.md create mode 100644 database/designs/after-sale-work-order-design.md create mode 100644 database/designs/waybill-module-design.md create mode 100644 database/migrations/20260728000000-remove-remote-play-url-from-wms-print-computer.js create mode 100644 database/migrations/20260728100000-remove-recording-config-fields-from-wms-print-computer.js create mode 100644 database/migrations/20260728110000-restore-recording-directory-to-wms-print-computer.js create mode 100644 database/migrations/20260728120000-create-wms-after-sale-work-order.js create mode 100644 database/migrations/20260728120000-restore-recording-size-fields-to-wms-print-computer.js create mode 100644 database/migrations/20260728130000-create-wms-after-sale-work-order-step.js diff --git a/app/model/after_sale_work_order.js b/app/model/after_sale_work_order.js new file mode 100644 index 0000000..0d7e9dd --- /dev/null +++ b/app/model/after_sale_work_order.js @@ -0,0 +1,267 @@ +'use strict'; + +module.exports = app => { + const { STRING, BIGINT, INTEGER, TINYINT, TEXT, DATE, DECIMAL } = app.Sequelize; + + /** + * 售后工单业务类型定义 + * 外部可通过 require('./app/model/after_sale_work_order').BUSINESS_TYPES 访问 + * 增删业务类型或子类型只需修改此常量,无需 ALTER TABLE + */ + const BUSINESS_TYPES = { + waybill: { + label: '运单', + table: 'wms_order_express', + subtypes: { + intercept: '拦截', + urge: '催件', + damage: '破损', + lost: '丢件', + wrong_info: '信息错误', + }, + }, + order_delivery: { + label: '发货订单', + table: 'wms_order_delivery', + subtypes: { + mis_shipment: '错发', + missing_item: '少发', + wrong_sku: '错品', + quality_issue: '质量问题', + delivery_delay: '发货延迟', + }, + }, + entry_order: { + label: '入库单', + table: 'wms_entry_order', + subtypes: { + shortage: '少货', + damage: '破损', + wrong_sku: '错品', + quality_issue: '质量问题', + }, + }, + order_stockout: { + label: '出库单/退货出库单', + table: 'wms_order_stockout', + subtypes: { + return_issue: '退货异常', + wrong_outbound: '错发', + shortage: '少发', + }, + }, + receiving: { + label: '收货单', + table: 'wms_receiving', + subtypes: { + shortage: '少货', + damage: '破损', + quality_issue: '质量问题', + }, + }, + other: { + label: '其他', + table: null, + subtypes: { + general: '通用', + }, + }, + }; + + /** + * 根据 business_type 获取关联表名 + * @param {string} businessType 业务类型 + * @returns {string|null} 关联表名 + */ + function getBusinessTable(businessType) { + return BUSINESS_TYPES[businessType]?.table || null; + } + + /** + * 校验 business_type + business_sub_type 组合是否合法 + * @param {string} businessType 业务类型 + * @param {string} businessSubType 业务子类型 + * @returns {boolean} 是否合法 + */ + function isValidSubType(businessType, businessSubType) { + const def = BUSINESS_TYPES[businessType]; + return def && Object.prototype.hasOwnProperty.call(def.subtypes, businessSubType); + } + + const AfterSaleWorkOrder = app.model.define('after_sale_work_order', { + id: { + type: BIGINT(20).UNSIGNED, + primaryKey: true, + autoIncrement: true, + comment: '主键ID', + }, + warehouse_id: { + type: BIGINT(20).UNSIGNED, + allowNull: false, + comment: '仓库ID', + }, + store_id: { + type: BIGINT(20).UNSIGNED, + allowNull: false, + comment: '货主ID', + }, + work_order_no: { + type: STRING(50), + allowNull: false, + comment: '售后工单号,唯一', + }, + business_type: { + type: STRING(50), + allowNull: false, + comment: '关联业务类型', + }, + business_sub_type: { + type: STRING(50), + allowNull: false, + comment: '关联业务子类型', + }, + business_id: { + type: BIGINT(20).UNSIGNED, + allowNull: false, + comment: '关联业务单据主键ID(多态关联)', + }, + business_no: { + type: STRING(100), + allowNull: true, + comment: '关联业务单据号(冗余)', + }, + direction: { + type: TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 0, + comment: '记账方向:0=未确定 1=入库 2=出库', + }, + status: { + type: TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 0, + comment: '工单状态:0=待处理 1=处理中 2=已完成 3=已关闭 9=已取消', + }, + priority: { + type: TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 50, + comment: '优先级:1~100,数字越大优先级越高', + }, + title: { + type: STRING(200), + allowNull: false, + comment: '工单标题/摘要', + }, + description: { + type: TEXT, + allowNull: true, + comment: '问题描述', + }, + creator_id: { + type: BIGINT(20).UNSIGNED, + allowNull: false, + comment: '创建人ID,关联 account.id;0 表示 AI 自动接待', + }, + creator_snapshot: { + type: TEXT, + allowNull: true, + comment: '创建人信息快照(JSON格式);AI创建时记录模型/会话信息', + }, + assignee_id: { + type: BIGINT(20).UNSIGNED, + allowNull: true, + comment: '当前处理人ID,关联 account.id', + }, + parent_work_order_id: { + type: BIGINT(20).UNSIGNED, + allowNull: true, + comment: '父工单ID,自关联本表;非空时表示子工单', + }, + current_step: { + type: TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 1, + comment: '当前进度,值为当前正在处理的 step_order 序号', + }, + claim_needed: { + type: TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 0, + comment: '是否需要理赔:0=不需要 1=需要', + }, + claim_amount: { + type: DECIMAL(12, 2), + allowNull: true, + defaultValue: 0.00, + comment: '理赔金额(元)', + }, + claim_status: { + type: TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 0, + comment: '理赔状态:0=未理赔 1=已理赔(单笔结清) 2=月结', + }, + resolution: { + type: TEXT, + allowNull: true, + comment: '处理结果说明', + }, + resolved_at: { + type: DATE, + allowNull: true, + comment: '解决时间', + }, + created_at: { + type: DATE, + allowNull: false, + comment: '创建时间', + }, + updated_at: { + type: DATE, + allowNull: false, + comment: '更新时间', + }, + deleted_at: { + type: DATE, + allowNull: true, + comment: '软删除时间', + }, + }, { + tableName: 'wms_after_sale_work_order', + timestamps: true, + createdAt: 'created_at', + updatedAt: 'updated_at', + paranoid: true, + deletedAt: 'deleted_at', + comment: '售后工单主表', + }); + + AfterSaleWorkOrder.associate = () => { + // 自关联:父工单 → 子工单 + AfterSaleWorkOrder.hasMany(app.model.AfterSaleWorkOrder, { + foreignKey: 'parent_work_order_id', + sourceKey: 'id', + as: 'children', + }); + AfterSaleWorkOrder.belongsTo(app.model.AfterSaleWorkOrder, { + foreignKey: 'parent_work_order_id', + targetKey: 'id', + as: 'parent', + }); + + // 关联进度步骤表 + AfterSaleWorkOrder.hasMany(app.model.AfterSaleWorkOrderStep, { + foreignKey: 'work_order_id', + sourceKey: 'id', + as: 'steps', + }); + }; + + // 挂载业务类型常量及辅助函数到 Model + AfterSaleWorkOrder.BUSINESS_TYPES = BUSINESS_TYPES; + AfterSaleWorkOrder.getBusinessTable = getBusinessTable; + AfterSaleWorkOrder.isValidSubType = isValidSubType; + + return AfterSaleWorkOrder; +}; diff --git a/app/model/after_sale_work_order_step.js b/app/model/after_sale_work_order_step.js new file mode 100644 index 0000000..dc66ba4 --- /dev/null +++ b/app/model/after_sale_work_order_step.js @@ -0,0 +1,99 @@ +'use strict'; + +module.exports = app => { + const { STRING, BIGINT, TINYINT, TEXT, DATE } = app.Sequelize; + + const AfterSaleWorkOrderStep = app.model.define('after_sale_work_order_step', { + id: { + type: BIGINT(20).UNSIGNED, + primaryKey: true, + autoIncrement: true, + comment: '主键ID', + }, + work_order_id: { + type: BIGINT(20).UNSIGNED, + allowNull: false, + comment: '工单ID,关联 wms_after_sale_work_order.id', + }, + step_order: { + type: TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 1, + comment: '步骤序号(从1开始递增)', + }, + step_name: { + type: STRING(100), + allowNull: false, + comment: '步骤名称', + }, + step_status: { + type: TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 0, + comment: '步骤状态:0=待开始 1=进行中 2=已完成 3=已跳过', + }, + operator_id: { + type: BIGINT(20).UNSIGNED, + allowNull: true, + comment: '操作员工ID,关联 account.id', + }, + operator_snapshot: { + type: TEXT, + allowNull: true, + comment: '操作人信息快照(JSON格式)', + }, + action: { + type: STRING(100), + allowNull: true, + comment: '操作动作描述', + }, + remark: { + type: TEXT, + allowNull: true, + comment: '处理备注', + }, + started_at: { + type: DATE, + allowNull: true, + comment: '步骤开始时间', + }, + completed_at: { + type: DATE, + allowNull: true, + comment: '步骤完成时间', + }, + created_at: { + type: DATE, + allowNull: false, + comment: '创建时间', + }, + updated_at: { + type: DATE, + allowNull: false, + comment: '更新时间', + }, + deleted_at: { + type: DATE, + allowNull: true, + comment: '软删除时间', + }, + }, { + tableName: 'wms_after_sale_work_order_step', + timestamps: true, + createdAt: 'created_at', + updatedAt: 'updated_at', + paranoid: true, + deletedAt: 'deleted_at', + comment: '售后工单进度步骤表', + }); + + AfterSaleWorkOrderStep.associate = () => { + AfterSaleWorkOrderStep.belongsTo(app.model.AfterSaleWorkOrder, { + foreignKey: 'work_order_id', + targetKey: 'id', + as: 'workOrder', + }); + }; + + return AfterSaleWorkOrderStep; +}; diff --git a/app/model/print_computer.js b/app/model/print_computer.js index 4f60b0e..2d8c463 100644 --- a/app/model/print_computer.js +++ b/app/model/print_computer.js @@ -50,12 +50,6 @@ module.exports = app => { defaultValue: null, comment: '录制存储单位:KB/MB/GB/TB', }, - remote_play_url: { - type: STRING(500), - allowNull: true, - defaultValue: null, - comment: '远程播放地址', - }, recording_directory: { type: STRING(500), allowNull: true, diff --git a/app/service/qimenMethods/order.js b/app/service/qimenMethods/order.js index afe6bc1..400217b 100644 --- a/app/service/qimenMethods/order.js +++ b/app/service/qimenMethods/order.js @@ -222,14 +222,66 @@ class orderServer extends MainService { return this.fail('订单已同步,不可取消,已转为拦截处理'); } - await existingOrder.update({ + // 检查是否在波次中,若在波次中需清除波次关联 + const existingWaveId = Number(existingOrder.wave_id || 0); + + const updateValues = { status: 'cancel', outbound_status: 'fin', step: 4, updated_at: new Date(), - }, { - transaction, - }); + }; + if (existingWaveId > 0) { + updateValues.wave_id = 0; + updateValues.wave_no = ''; + } + + await existingOrder.update(updateValues, { transaction }); + + // 波次清理:删除波次索引、更新波次统计 + if (existingWaveId > 0) { + try { + await ctx.service.systemMethods.order.wave.deleteOrderWaveIndexByOrderIds({ + warehouseId: info.warehouseId, + orderIds: [existingOrder.id], + transaction, + }); + + const { Op } = this.app.Sequelize; + const WaveBatch = ctx.model.WaveBatch; + if (WaveBatch) { + await WaveBatch.decrement('total_orders', { + by: 1, + where: { + wave_id: existingWaveId, + warehouse_id: info.warehouseId, + total_orders: { [Op.gt]: 0 }, + }, + transaction, + }); + + const wave = await WaveBatch.findOne({ + where: { wave_id: existingWaveId, warehouse_id: info.warehouseId }, + attributes: ['wave_id', 'total_orders', 'wave_status'], + raw: true, + transaction, + }); + + if (wave) { + const totalOrders = Number(wave.total_orders); + const normalizedTotalOrders = Number.isFinite(totalOrders) ? totalOrders : 0; + if (normalizedTotalOrders <= 0) { + await WaveBatch.update( + { total_orders: 0, wave_status: -1, update_time: new Date() }, + { where: { wave_id: existingWaveId, warehouse_id: info.warehouseId }, transaction } + ); + } + } + } + } catch (waveErr) { + ctx.logger.warn('[QimenOrderCancel] 清理波次关联失败,不影响订单取消', waveErr); + } + } // 释放储位分配锁定库存(wms_storage / wms_stock_warehouse) await this.releaseStorageLockForCancel({ @@ -240,6 +292,19 @@ class orderServer extends MainService { await transaction.commit(); + // 波次策略扫描清理(不影响主流程) + if (existingWaveId > 0) { + try { + ctx.service.systemMethods.order.wave.enqueueWaveStrategyQuickScanPostOrderChange( + info.warehouseId, + [existingOrder.id], + { triggerScan: true, source: 'qimenCancel' } + ); + } catch (scanErr) { + ctx.logger.warn('[QimenOrderCancel] 波次策略扫描触发失败,不影响主流程', scanErr); + } + } + // 写入取消操作日志(不影响主流程) try { if (ctx.model && ctx.model.OperationLog) { diff --git a/app/service/systemMethods/order/pendingOrder.js b/app/service/systemMethods/order/pendingOrder.js index a5dcaf2..c8cb73a 100644 --- a/app/service/systemMethods/order/pendingOrder.js +++ b/app/service/systemMethods/order/pendingOrder.js @@ -540,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,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'; + 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,batchMarkPrinted'; + const _noNeedLog = 'list,markPendingOutboundOrder,cancelOrder,allocateExpressCode,allocateExpressCodeTaskProgress,allocateStorage,allocateStorageProgress,cancelAllocateStorage,syncOrderIds,syncOrderIdsProgress,parseAddress,batchIntercept,batchInterceptTaskProgress,batchLock,batchLockTaskProgress,batchUnlock,batchUnlockTaskProgress,batchUnintercept,batchUninterceptTaskProgress,manualWaybill,allocateSubOrderNumber,allocateSubOrderNumberProgress,batchMarkPrinted'; + 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,batchMarkPrinted'; this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth); } @@ -6328,6 +6328,121 @@ class PendingOrderService extends OrderBaseService { }); } + /** + * 批量设置订单为已打印状态。 + * + * 将给定订单 ID 列表中属于当前仓库的订单的 print_status 更新为 'fin'。 + * 先查 current 表(wms_order_delivery_{warehouseId}),再查 dispatch 表 + * (wms_order_delivery_{warehouseId}_dispatch)兜底。 + * 仅允许 step 在 [1,2,3] 且 status 不为 'cancel' 的订单操作,已打印(print_status='fin')的订单会被静默跳过。 + * + * @param {Object} data 请求体。 + * @param {Array|number|string} [data.order_ids] 订单ID集合(下划线写法)。 + * @param {Array|number|string} [data.orderIds] 订单ID集合(驼峰别名)。 + * @param {Array|number|string} [data.ids] 订单ID集合(简写别名)。 + * @return {Promise} 统一 success 包装的更新结果。 + */ + async batchMarkPrinted(data = {}) { + const requestData = this.isPlainObject(data) ? data : {}; + const warehouseId = this.getWarehouseId(); + const operator = this.getOrderLogOperator(); + const logWarehouseId = this.getOrderLogWarehouseId(warehouseId); + + if (!Number.isInteger(warehouseId) || warehouseId <= 0) { + throw new Error('未识别到当前仓库上下文'); + } + + const rawIds = requestData.order_ids !== undefined ? requestData.order_ids + : requestData.orderIds !== undefined ? requestData.orderIds + : requestData.ids; + const orderIds = this.normalizeIdsInput(rawIds); + if (orderIds.length === 0) { + throw new Error('order_ids 参数不能为空或格式错误'); + } + + const { Op } = this.app.Sequelize; + const now = new Date(); + + const buildWhere = () => ({ + step: { [Op.in]: [1, 2, 3] }, + status: { [Op.ne]: 'cancel' }, + print_status: { [Op.ne]: 'fin' }, + }); + + // 1. 先查 current 表 + const currentModel = await this.getOrderModel('order', warehouseId); + const currentWhere = { + ...this.buildOrderWhere(orderIds, warehouseId), + ...buildWhere(), + }; + + const [ currentAffected ] = await currentModel.update( + { print_status: 'fin', updated_at: now }, + { where: currentWhere } + ); + let updatedCount = Number(currentAffected || 0); + + // 2. 查询 current 表中已存在的订单 ID,计算出未命中的 ID + const currentFoundRows = await currentModel.findAll({ + attributes: ['id'], + where: this.buildOrderWhere(orderIds, warehouseId), + raw: true, + }); + const currentFoundIds = new Set( + (Array.isArray(currentFoundRows) ? currentFoundRows : []).map(row => Number(row.id)) + ); + const missingIds = orderIds.filter(id => !currentFoundIds.has(id)); + + // 3. dispatch 表兜底 + if (missingIds.length > 0) { + try { + const dispatchModel = await this.ctx.model.OrderDeliveryFactory.getDispatchModel(warehouseId); + if (dispatchModel && typeof dispatchModel.update === 'function') { + const dispatchWhere = { + id: { [Op.in]: missingIds }, + warehouse_id: warehouseId, + ...buildWhere(), + }; + + const [ dispatchAffected ] = await dispatchModel.update( + { print_status: 'fin', updated_at: now }, + { where: dispatchWhere } + ); + updatedCount += Number(dispatchAffected || 0); + } + } catch (dispatchErr) { + this.ctx.logger.warn('[PendingOrderService.batchMarkPrinted] dispatch 表更新失败,不影响 current 表结果', dispatchErr); + } + } + + // 写入操作日志(不影响主流程) + try { + const opLogService = this.ctx && this.ctx.service && this.ctx.service.systems && this.ctx.service.systems.operationLog; + if (opLogService && typeof opLogService.createOperationLogs === 'function') { + const logPayloads = orderIds.map(orderId => ({ + businessType: 'order', + businessId: String(orderId), + operationCode: 'ORDER_BATCH_MARK_PRINTED', + operator, + extras: { + warehouseId: logWarehouseId, + orderId, + message: `批量标记已打印:订单 ${orderId}`, + }, + beforeChanges: null, + })); + await opLogService.createOperationLogs(logPayloads); + } + } catch (logErr) { + this.ctx.logger.warn('[PendingOrderService.batchMarkPrinted] 写入操作日志失败,不影响业务', logErr); + } + + return this.success('ok', { + updated_count: updatedCount, + ids: orderIds, + }); + } + } module.exports = PendingOrderService; diff --git a/app/service/systemMethods/printComputer.js b/app/service/systemMethods/printComputer.js index d137003..7aeae5e 100644 --- a/app/service/systemMethods/printComputer.js +++ b/app/service/systemMethods/printComputer.js @@ -39,7 +39,7 @@ class PrintComputerService extends MainService { /** * 设置录制电脑(会先取消同仓库下其他录制电脑)。 - * @param {Object} data { id, recording_size_value, recording_size_unit, remote_play_url, recording_directory } + * @param {Object} data { id, recording_size_value, recording_size_unit, recording_directory } * @return {Promise} 设置结果 */ async setRecording(data) { diff --git a/app/service/systems/express_platform.js b/app/service/systems/express_platform.js index bd2ccc1..72c3eea 100644 --- a/app/service/systems/express_platform.js +++ b/app/service/systems/express_platform.js @@ -690,6 +690,7 @@ class ExpressPlatformService extends MainService { const order_bizcontent = { orders: orders.map(order_tmp => { const order = order_tmp.order_delivery; + console.log('order', order); const expressListItem = ExpressList.find(item => item.code === listByWarehousePlatformCode.sys_express_code) || {}; let playload = { object_Id: `${order.warehouse_id}_${order.id}_${order_tmp.business_key}`, // 菠萝派平台要求订单唯一标识必须为字符串 @@ -729,6 +730,7 @@ class ExpressPlatformService extends MainService { inputsite: listByWarehousePlatformCode.site_code || '', sitecode: listByWarehousePlatformCode.site_code || '', shipperno: listByWarehousePlatformCode.shipperno || '', + customercode: listByWarehousePlatformCode.shipperno || listByWarehousePlatformCode.client_id || '', sender: { company: listByWarehousePlatformCode.shop_name || '', name: listByWarehousePlatformCode.sender_name || '', @@ -743,7 +745,7 @@ class ExpressPlatformService extends MainService { receiver: { name: order.name || '', company: order.company || '', - phone: order.sys_platform_code === 'KS' ? undefined : (order.mobile || order.tel || ''), + phone: order.sys_platform_code === 'KS' || order.sys_platform_code === 'KS' ? undefined : (order.mobile || order.tel || ''), mobile: order.mobile || order.tel || '', country: order.country_code || 'CN', province: order.province || '', @@ -766,6 +768,9 @@ class ExpressPlatformService extends MainService { labelformat: listByWarehousePlatformCode.labelformat || '', extraInfo: ExpressList.find(item => item.code === listByWarehousePlatformCode.sys_express_code)?.polyapi_extra_info || '', }; + console.log("matchedPlatform.platid",matchedPlatform.platid); + console.log("startPlayload",playload); + if (Number(matchedPlatform.platid) === 673) { playload.BizVersion = '2'; playload.brandno = listByWarehousePlatformCode.brandno || ''; @@ -779,6 +784,7 @@ class ExpressPlatformService extends MainService { providercode, numpackage, businessplat, + oaid, ordertype, businessType, codpaymoney, @@ -789,6 +795,7 @@ class ExpressPlatformService extends MainService { ordersource, shipperno, sitecode, + customercode, goods, sender = {}, receiver = {}, @@ -836,6 +843,8 @@ class ExpressPlatformService extends MainService { sitecode, customername, goods, + oaid, + customercode: customercode || shipperno || listByWarehousePlatformCode.shipperno || listByWarehousePlatformCode.client_id || '', sender: { name: senderName, phone: senderPhoneRaw, @@ -870,7 +879,8 @@ class ExpressPlatformService extends MainService { if (!order.extend_props.ewaybill_order_code) { throw new Error('订单数据错误,参数不全缺失extend_props.ewaybill_order_code,请复制次信息给ERP方反馈'); } - playload.oaid = order.extend_props.ewaybill_order_code; + playload.oaid = order.extend_props.ewaybill_order_code||order.oaid||undefined; + playload.transtype = '0'; playload.Mallmaskid = order.buyer_nick; playload.mainsubpaymode = '1'; @@ -897,6 +907,8 @@ class ExpressPlatformService extends MainService { api: 'Differ.JH.Logistics.PostOrder', response: JSON.stringify(result), }); + console.log("分配运单号结果",result); + if (result && result.code !== '10000') { const postOrderErrorMessage = String( result.submessage || result.message || '菠萝派平台接口调用失败' @@ -981,8 +993,8 @@ class ExpressPlatformService extends MainService { case 'JD':{ const batchPrintSipshopid = String(listByWarehousePlatformCode.platform_shop_id || '0'); const batchPrintOrders = (result.results || []).map(item => ({ - orderno: String(item.orderno || ''), - logisticno: String(item.logisticno || item.waybill_code || ''), + orderno: String(item.orderno), + logisticno: String(item.logisticno), outputformat: 'JH_PDF', labelformat: 'JH_A4', printobjecttype: 'JH_Label', @@ -1007,18 +1019,18 @@ class ExpressPlatformService extends MainService { cargoname: '', senddata: '', weight: '', + eCustomerCode: '', remark: '', - carrier: batchPrintSipshopid, selleruserid: '', - printno: '', + printno: "", iscloudprint: 'false', needprintdetail: 'false', extenddata: '', providercode: String(item.procode || item.realcpcode || item.logisticcompanycode || ''), packageno: '', fontsize: '', - platorderno: String(item.plattradeno || item.platorderno || item.orderno || ''), - sipshopid: batchPrintSipshopid, + platorderno: "", + sipshopid: 0, })); console.log('京东批量打印请求参数', JSON.stringify({ api: 'Differ.JH.Logistics.BatchPrintOrder', diff --git a/app/service/systems/printComputer.js b/app/service/systems/printComputer.js index f973085..8ae474b 100644 --- a/app/service/systems/printComputer.js +++ b/app/service/systems/printComputer.js @@ -154,7 +154,7 @@ class PrintComputerService extends Service { * 设置录制电脑。 * 会将同仓库下其他已设为录制的电脑取消,再设置当前电脑为录制。 * @param {number} id 电脑ID - * @param {Object} data { recording_size_value, recording_size_unit, remote_play_url, recording_directory } + * @param {Object} data { recording_size_value, recording_size_unit, recording_directory } * @return {Promise} 更新后的记录 */ async setRecording(id, data) { @@ -176,11 +176,6 @@ class PrintComputerService extends Service { throw new Error(`存储单位不合法,支持:${VALID_UNITS.join('/')}`); } - const url = String(data.remote_play_url || '').trim(); - if (!/^https?:\/\/.+/.test(url)) { - throw new Error('远程播放地址必须以 http:// 或 https:// 开头'); - } - const directory = String(data.recording_directory || '').trim(); if (!directory) { throw new Error('录制目录不能为空'); @@ -198,7 +193,6 @@ class PrintComputerService extends Service { is_recording: false, recording_size_value: null, recording_size_unit: null, - remote_play_url: null, recording_directory: null, }, { @@ -215,7 +209,6 @@ class PrintComputerService extends Service { is_recording: true, recording_size_value: sizeValue, recording_size_unit: unit, - remote_play_url: url, recording_directory: directory, }); @@ -261,7 +254,6 @@ class PrintComputerService extends Service { is_recording: false, recording_size_value: null, recording_size_unit: null, - remote_play_url: null, recording_directory: null, }); diff --git a/database/designs/after-sale-api-design.md b/database/designs/after-sale-api-design.md new file mode 100644 index 0000000..b4a4bd3 --- /dev/null +++ b/database/designs/after-sale-api-design.md @@ -0,0 +1,644 @@ +# 售后工单 API 接口设计方案 + +> **状态**: ⏳ 等待人工审阅 +> **设计日期**: 2026-07-29 +> **设计人**: wms-db-agent +> **说明**: 本文档仅输出 API 接口设计方案,不直接修改程序代码。审阅通过后再执行实现。 + +--- + +## 一、模块概览 + +| 项目 | 说明 | +|------|------| +| 模块名 | `afterSale` | +| 接口路径 | `POST /system`,body 中 `method` 字段为 `afterSale.{方法名}` | +| 请求方式 | 全部 `POST`,参数放在 `body` 内 | +| 鉴权 | 除 `businessTypes` 外均需登录;写操作需鉴权 | + +### 文件规划 + +``` +app/service/systemMethods/afterSale.js ← 入口层(鉴权、参数校验、委托) +app/service/systems/afterSale.js ← 业务层(数据库操作、状态机) +methods/system.json ← API 文档(追加 afterSale group) +``` + +### 调用链路 + +``` +POST /system { method: "afterSale.list", ... } + → app/router.js + → app/service/system.js + → app/service/systemMethods/afterSale.js ← 鉴权 + 参数校验 + → app/service/systems/afterSale.js ← 业务逻辑 + DB操作 + → app/model/after_sale_work_order.js ← Sequelize Model + → app/model/after_sale_work_order_step.js +``` + +--- + +## 二、接口清单(共 13 个) + +| # | method | 描述 | 需登录 | 需鉴权 | +|---|--------|------|--------|--------| +| 1 | `afterSale.businessTypes` | 获取内置业务类型及子类型枚举 | ✗ | ✗ | +| 2 | `afterSale.list` | 工单列表(分页+筛选) | ✓ | ✗ | +| 3 | `afterSale.detail` | 工单详情(含步骤列表) | ✓ | ✗ | +| 4 | `afterSale.create` | 创建工单 | ✓ | ✓ | +| 5 | `afterSale.update` | 更新工单基本信息 | ✓ | ✓ | +| 6 | `afterSale.delete` | 删除工单(软删除) | ✓ | ✓ | +| 7 | `afterSale.assign` | 分配处理人 | ✓ | ✓ | +| 8 | `afterSale.complete` | 完成工单 | ✓ | ✓ | +| 9 | `afterSale.close` | 关闭工单 | ✓ | ✓ | +| 10 | `afterSale.cancel` | 取消工单 | ✓ | ✓ | +| 11 | `afterSale.stepStart` | 开始某个步骤 | ✓ | ✓ | +| 12 | `afterSale.stepComplete` | 完成某个步骤 | ✓ | ✓ | +| 13 | `afterSale.stepSkip` | 跳过某个步骤 | ✓ | ✓ | + +--- + +## 三、接口详细设计 + +### 3.1 `afterSale.businessTypes` — 获取业务类型枚举 + +```json +{ + "method": "afterSale.businessTypes", + "description": "获取售后工单内置业务类型及子类型枚举,供前端下拉选择使用。数据来源:app/model/after_sale_work_order.js 中的 BUSINESS_TYPES 常量。", + "isNeedAuth": false, + "isNeedLogin": false, + "params": [], + "response": [ + { + "name": "data", + "type": "object", + "description": "业务类型枚举,key 为 business_type,value 含 label、table、subtypes", + "example": { + "waybill": { + "label": "运单", + "table": "wms_order_express", + "subtypes": { + "intercept": "拦截", + "urge": "催件", + "damage": "破损", + "lost": "丢件", + "wrong_info": "信息错误" + } + }, + "order_delivery": { + "label": "发货订单", + "table": "wms_order_delivery", + "subtypes": { + "mis_shipment": "错发", + "missing_item": "少发", + "wrong_sku": "错品", + "quality_issue": "质量问题", + "delivery_delay": "发货延迟" + } + } + } + } + ] +} +``` + +--- + +### 3.2 `afterSale.list` — 工单列表 + +```json +{ + "method": "afterSale.list", + "description": "查询售后工单列表,支持分页与多条件筛选。仓库隔离(自动注入 warehouse_id)。", + "isNeedAuth": false, + "isNeedLogin": true, + "params": [ + { + "name": "pagination", + "type": "object", + "required": false, + "source": "body", + "description": "分页参数 { page, pageSize },默认 page=1 pageSize=20" + }, + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "筛选条件,所有字段均为可选", + "children": [ + { "name": "workOrderNo", "type": "string", "description": "工单号(模糊搜索)" }, + { "name": "businessType", "type": "string", "description": "业务类型(等值),如 waybill" }, + { "name": "businessSubType","type": "string", "description": "业务子类型(等值),如 intercept" }, + { "name": "businessNo", "type": "string", "description": "关联业务单据号(模糊)" }, + { "name": "status", "type": "number", "description": "工单状态(等值):0/1/2/3/9" }, + { "name": "priorityMin", "type": "number", "description": "优先级下限(>=)" }, + { "name": "priorityMax", "type": "number", "description": "优先级上限(<=)" }, + { "name": "claimStatus", "type": "number", "description": "理赔状态(等值):0/1/2" }, + { "name": "assigneeId", "type": "number", "description": "处理人ID(等值)" }, + { "name": "creatorId", "type": "number", "description": "创建人ID(等值)" }, + { "name": "keyword", "type": "string", "description": "关键词:匹配工单号/标题/业务单据号" }, + { "name": "createdAtStart", "type": "string", "description": "创建时间起始(YYYY-MM-DD)" }, + { "name": "createdAtEnd", "type": "string", "description": "创建时间截止(YYYY-MM-DD)" } + ] + }, + { + "name": "sort", + "type": "object", + "required": false, + "source": "body", + "description": "排序 { field: 'priority'|'created_at'|'status', order: 'asc'|'desc' },默认 priority desc" + } + ], + "response": [ + { + "name": "list", + "type": "array", + "description": "工单列表(不含 description/resolution 长文本,减少传输量)", + "children": [ + { "name": "id", "type": "number", "description": "工单ID" }, + { "name": "work_order_no", "type": "string", "description": "工单号" }, + { "name": "warehouse_id", "type": "number", "description": "仓库ID" }, + { "name": "store_id", "type": "number", "description": "货主ID" }, + { "name": "business_type", "type": "string", "description": "业务类型" }, + { "name": "business_sub_type","type": "string", "description": "业务子类型" }, + { "name": "business_id", "type": "number", "description": "关联单据ID" }, + { "name": "business_no", "type": "string", "description": "关联单据号" }, + { "name": "direction", "type": "number", "description": "记账方向:0/1/2" }, + { "name": "status", "type": "number", "description": "工单状态:0/1/2/3/9" }, + { "name": "priority", "type": "number", "description": "优先级:1-100" }, + { "name": "title", "type": "string", "description": "工单标题" }, + { "name": "creator_id", "type": "number", "description": "创建人ID" }, + { "name": "creator_name", "type": "string", "description": "创建人姓名(JOIN account)" }, + { "name": "assignee_id", "type": "number", "description": "当前处理人ID" }, + { "name": "assignee_name", "type": "string", "description": "当前处理人姓名(JOIN account)" }, + { "name": "parent_work_order_id","type":"number","description": "父工单ID" }, + { "name": "current_step", "type": "number", "description": "当前进度步骤序号" }, + { "name": "claim_needed", "type": "number", "description": "是否理赔" }, + { "name": "claim_amount", "type": "number", "description": "理赔金额" }, + { "name": "claim_status", "type": "number", "description": "理赔状态" }, + { "name": "resolved_at", "type": "string", "description": "解决时间" }, + { "name": "created_at", "type": "string", "description": "创建时间" }, + { "name": "updated_at", "type": "string", "description": "更新时间" } + ] + }, + { "name": "pagination", "type": "object", "description": "分页信息 { page, pageSize, total, totalPages }" } + ] +} +``` + +--- + +### 3.3 `afterSale.detail` — 工单详情 + +```json +{ + "method": "afterSale.detail", + "description": "查询单个工单详情,含完整字段 + 步骤列表。仓库隔离。", + "isNeedAuth": false, + "isNeedLogin": true, + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "工单ID(必填)" + } + ], + "response": [ + { + "name": "data", + "type": "object", + "description": "工单完整信息", + "children": [ + { "name": "id", "type": "number", "description": "工单ID" }, + { "name": "...", "type": "", "description": "同 list 接口所有字段" }, + { "name": "description", "type": "string", "description": "问题描述(详情接口返回)" }, + { "name": "resolution", "type": "string", "description": "处理结果说明(详情接口返回)" }, + { "name": "creator_snapshot", "type": "string", "description": "创建人信息快照" }, + { "name": "steps", "type": "array", "description": "步骤列表", + "children": [ + { "name": "id", "type": "number", "description": "步骤ID" }, + { "name": "step_order", "type": "number", "description": "步骤序号" }, + { "name": "step_name", "type": "string", "description": "步骤名称" }, + { "name": "step_status", "type": "number", "description": "步骤状态:0/1/2/3" }, + { "name": "operator_id", "type": "number", "description": "操作人ID" }, + { "name": "operator_name", "type": "string", "description": "操作人姓名" }, + { "name": "operator_snapshot","type": "string", "description": "操作人快照" }, + { "name": "action", "type": "string", "description": "操作动作" }, + { "name": "remark", "type": "string", "description": "处理备注" }, + { "name": "started_at", "type": "string", "description": "开始时间" }, + { "name": "completed_at", "type": "string", "description": "完成时间" }, + { "name": "created_at", "type": "string", "description": "创建时间" } + ] + }, + { "name": "children", "type": "array", "description": "子工单列表(如有)" }, + { "name": "parent", "type": "object", "description": "父工单简要信息(如有)" } + ] + } + ], + "errors": [ + { "code": "400", "description": "工单ID不能为空" }, + { "code": "404", "description": "工单不存在或无权访问" } + ] +} +``` + +--- + +### 3.4 `afterSale.create` — 创建工单 + +```json +{ + "method": "afterSale.create", + "description": "创建售后工单。自动生成工单号(AS+时间戳),自动设置 creator_id 和 warehouse_id。创建成功后返回工单详情。", + "isNeedAuth": true, + "isNeedLogin": true, + "params": [ + { + "name": "business_type", + "type": "string", + "required": true, + "source": "body", + "description": "业务类型(必填),如 waybill、order_delivery" + }, + { + "name": "business_sub_type", + "type": "string", + "required": true, + "source": "body", + "description": "业务子类型(必填),如 intercept、mis_shipment。需与 business_type 匹配(由 BUSINESS_TYPES 校验)" + }, + { + "name": "business_id", + "type": "number", + "required": true, + "source": "body", + "description": "关联业务单据主键ID(必填)" + }, + { + "name": "business_no", + "type": "string", + "required": false, + "source": "body", + "description": "关联业务单据号(可选,建议传入方便列表展示)" + }, + { + "name": "direction", + "type": "number", + "required": false, + "source": "body", + "description": "记账方向:1=入库 2=出库,默认 0(未确定)" + }, + { + "name": "priority", + "type": "number", + "required": false, + "source": "body", + "description": "优先级:1~100,默认 50。AI 创建时自动填入" + }, + { + "name": "title", + "type": "string", + "required": true, + "source": "body", + "description": "工单标题(必填)" + }, + { + "name": "description", + "type": "string", + "required": false, + "source": "body", + "description": "问题描述" + }, + { + "name": "claim_needed", + "type": "number", + "required": false, + "source": "body", + "description": "是否需要理赔:0=否 1=是,默认 0" + }, + { + "name": "claim_amount", + "type": "number", + "required": false, + "source": "body", + "description": "理赔金额,默认 0.00" + }, + { + "name": "parent_work_order_id", + "type": "number", + "required": false, + "source": "body", + "description": "父工单ID(子工单场景),不传则为根工单" + } + ], + "response": [ + { + "name": "data", + "type": "object", + "description": "创建成功的工单详情(同 detail 接口返回结构)" + } + ], + "errors": [ + { "code": "400", "description": "工单标题不能为空" }, + { "code": "400", "description": "业务类型或子类型不合法" }, + { "code": "400", "description": "父工单不存在" } + ] +} +``` + +--- + +### 3.5 `afterSale.update` — 更新工单基本信息 + +```json +{ + "method": "afterSale.update", + "description": "更新工单基本信息(标题、描述、优先级、记账方向、理赔信息)。不可修改 business_type/business_sub_type/business_id。仓库隔离。", + "isNeedAuth": true, + "isNeedLogin": true, + "params": [ + { "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" }, + { "name": "title", "type": "string", "required": false, "source": "body", "description": "工单标题" }, + { "name": "description", "type": "string", "required": false, "source": "body", "description": "问题描述" }, + { "name": "priority", "type": "number", "required": false, "source": "body", "description": "优先级" }, + { "name": "direction", "type": "number", "required": false, "source": "body", "description": "记账方向" }, + { "name": "claim_needed", "type": "number", "required": false, "source": "body", "description": "是否需要理赔" }, + { "name": "claim_amount", "type": "number", "required": false, "source": "body", "description": "理赔金额" }, + { "name": "claim_status", "type": "number", "required": false, "source": "body", "description": "理赔状态" } + ], + "response": [ + { "name": "data", "type": "object", "description": "更新后的工单详情" } + ], + "errors": [ + { "code": "400", "description": "工单ID不能为空" }, + { "code": "404", "description": "工单不存在或无权操作" } + ] +} +``` + +--- + +### 3.6 `afterSale.delete` — 删除工单 + +```json +{ + "method": "afterSale.delete", + "description": "软删除工单及其所有步骤。仅待处理(0)和已取消(9)状态的工单可删除。仓库隔离。", + "isNeedAuth": true, + "isNeedLogin": true, + "params": [ + { "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" } + ], + "response": [], + "errors": [ + { "code": "400", "description": "工单ID不能为空" }, + { "code": "400", "description": "处理中的工单不可删除" }, + { "code": "404", "description": "工单不存在或无权操作" } + ] +} +``` + +--- + +### 3.7 `afterSale.assign` — 分配处理人 + +```json +{ + "method": "afterSale.assign", + "description": "将工单分配给指定处理人。仅待处理(0)状态的工单可分配。分配后自动流转至处理中(1)。仓库隔离。", + "isNeedAuth": true, + "isNeedLogin": true, + "params": [ + { "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" }, + { "name": "assignee_id", "type": "number", "required": true, "source": "body", "description": "处理人ID(必填)" }, + { "name": "remark", "type": "string", "required": false, "source": "body", "description": "分配备注" } + ], + "response": [ + { "name": "data", "type": "object", "description": "更新后的工单详情" } + ], + "errors": [ + { "code": "400", "description": "工单ID不能为空" }, + { "code": "400", "description": "处理人ID不能为空" }, + { "code": "400", "description": "当前状态不可分配(非待处理状态)" } + ] +} +``` + +--- + +### 3.8 `afterSale.complete` — 完成工单 + +```json +{ + "method": "afterSale.complete", + "description": "完成工单。仅处理中(1)状态且所有步骤已完成/跳过的工单可完成。完成后自动设置 resolved_at。仓库隔离。", + "isNeedAuth": true, + "isNeedLogin": true, + "params": [ + { "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" }, + { "name": "resolution", "type": "string", "required": false, "source": "body", "description": "处理结果说明" } + ], + "response": [ + { "name": "data", "type": "object", "description": "更新后的工单详情" } + ], + "errors": [ + { "code": "400", "description": "工单ID不能为空" }, + { "code": "400", "description": "当前状态不可完成(非处理中状态)" }, + { "code": "400", "description": "仍有步骤未完成,请先完成所有步骤" } + ] +} +``` + +--- + +### 3.9 `afterSale.close` — 关闭工单 + +```json +{ + "method": "afterSale.close", + "description": "关闭工单。仅已完成(2)状态的工单可关闭。仓库隔离。", + "isNeedAuth": true, + "isNeedLogin": true, + "params": [ + { "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" }, + { "name": "remark", "type": "string", "required": false, "source": "body", "description": "关闭备注" } + ], + "response": [ + { "name": "data", "type": "object", "description": "更新后的工单详情" } + ], + "errors": [ + { "code": "400", "description": "工单ID不能为空" }, + { "code": "400", "description": "当前状态不可关闭(非已完成状态)" } + ] +} +``` + +--- + +### 3.10 `afterSale.cancel` — 取消工单 + +```json +{ + "method": "afterSale.cancel", + "description": "取消工单。仅待处理(0)和处理中(1)状态的工单可取消。仓库隔离。", + "isNeedAuth": true, + "isNeedLogin": true, + "params": [ + { "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" }, + { "name": "remark", "type": "string", "required": false, "source": "body", "description": "取消原因" } + ], + "response": [ + { "name": "data", "type": "object", "description": "更新后的工单详情" } + ], + "errors": [ + { "code": "400", "description": "工单ID不能为空" }, + { "code": "400", "description": "当前状态不可取消" } + ] +} +``` + +--- + +### 3.11 `afterSale.stepStart` — 开始步骤 + +```json +{ + "method": "afterSale.stepStart", + "description": "开始处理某个步骤。将步骤状态设为进行中(1),同时更新主表 current_step。同一时刻只允许一个步骤处于进行中。仓库隔离。", + "isNeedAuth": true, + "isNeedLogin": true, + "params": [ + { "name": "step_id", "type": "number", "required": true, "source": "body", "description": "步骤ID(必填,wms_after_sale_work_order_step.id)" }, + { "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" } + ], + "response": [ + { "name": "data", "type": "object", "description": "更新后的步骤信息" } + ], + "errors": [ + { "code": "400", "description": "步骤ID不能为空" }, + { "code": "400", "description": "已有其他步骤正在进行中" }, + { "code": "400", "description": "步骤当前状态不可开始" } + ] +} +``` + +--- + +### 3.12 `afterSale.stepComplete` — 完成步骤 + +```json +{ + "method": "afterSale.stepComplete", + "description": "完成某个步骤。将步骤状态设为已完成(2),记录操作人和完成时间。仓库隔离。", + "isNeedAuth": true, + "isNeedLogin": true, + "params": [ + { "name": "step_id", "type": "number", "required": true, "source": "body", "description": "步骤ID(必填)" }, + { "name": "action", "type": "string", "required": false, "source": "body", "description": "操作动作描述" }, + { "name": "remark", "type": "string", "required": false, "source": "body", "description": "处理备注" } + ], + "response": [ + { "name": "data", "type": "object", "description": "更新后的步骤信息" } + ], + "errors": [ + { "code": "400", "description": "步骤ID不能为空" }, + { "code": "400", "description": "步骤当前状态不可完成(非进行中状态)" } + ] +} +``` + +--- + +### 3.13 `afterSale.stepSkip` — 跳过步骤 + +```json +{ + "method": "afterSale.stepSkip", + "description": "跳过某个步骤。将步骤状态设为已跳过(3)。仓库隔离。", + "isNeedAuth": true, + "isNeedLogin": true, + "params": [ + { "name": "step_id", "type": "number", "required": true, "source": "body", "description": "步骤ID(必填)" }, + { "name": "remark", "type": "string", "required": false, "source": "body", "description": "跳过原因" } + ], + "response": [ + { "name": "data", "type": "object", "description": "更新后的步骤信息" } + ], + "errors": [ + { "code": "400", "description": "步骤ID不能为空" }, + { "code": "400", "description": "步骤当前状态不可跳过" } + ] +} +``` + +--- + +## 四、状态机约束(服务端校验规则) + +| 操作 | 允许的当前状态 | 目标状态 | +|------|-------------|---------| +| `create` | — | `status=0`, `current_step=1` | +| `assign` | `status=0` | `status=1` | +| `delete` | `status=0` 或 `status=9` | 软删除 | +| `complete` | `status=1` + 所有步骤已完成/跳过 | `status=2`, `resolved_at=NOW()` | +| `close` | `status=2` | `status=3` | +| `cancel` | `status=0` 或 `status=1` | `status=9` | +| `stepStart` | `step_status=0` + 无其他进行中步骤 | `step_status=1`, `current_step=该step_order` | +| `stepComplete` | `step_status=1` | `step_status=2` | +| `stepSkip` | `step_status=0` | `step_status=3` | + +--- + +## 五、methods/system.json 追加格式 + +在 `methods.system.json` 的 `methods.groups` 数组末尾追加: + +```json +{ + "groupName": "售后工单模块", + "module": "afterSale", + "list": [ + { "method": "afterSale.businessTypes", ... }, + { "method": "afterSale.list", ... }, + { "method": "afterSale.detail", ... }, + { "method": "afterSale.create", ... }, + { "method": "afterSale.update", ... }, + { "method": "afterSale.delete", ... }, + { "method": "afterSale.assign", ... }, + { "method": "afterSale.complete", ... }, + { "method": "afterSale.close", ... }, + { "method": "afterSale.cancel", ... }, + { "method": "afterSale.stepStart", ... }, + { "method": "afterSale.stepComplete", ... }, + { "method": "afterSale.stepSkip", ... } + ] +} +``` + +(完整 JSON 定义见第三节各接口) + +--- + +## 六、后续实现计划(审阅通过后执行) + +| 步骤 | 文件 | 说明 | +|------|------|------| +| 1 | `app/service/systems/afterSale.js` | 业务层:数据库操作、状态机、工单号生成 | +| 2 | `app/service/systemMethods/afterSale.js` | 入口层:鉴权配置、参数校验、委托调用 | +| 3 | `methods/system.json` | 追加 `afterSale` group 的 13 个 method 文档 | +| 4 | `methods/changes/afterSale-20260729.json` | 接口变更记录 | + +--- + +## 七、待确认事项 + +- [ ] **1. 模块名**:`afterSale` 是否合适?备选 `asWorkOrder`、`afterSaleWorkOrder` +- [ ] **2. 步骤操作是否需要独立接口**:`stepStart/stepComplete/stepSkip` 三个独立接口 vs 合并为一个 `stepUpdate`(传 status 参数) +- [ ] **3. `businessTypes` 接口免登录**:是否允许未登录用户获取业务类型枚举? +- [ ] **4. 步骤创建时机**:步骤是创建工单时自动初始化一组,还是由前端手动逐条添加? +- [ ] **5. 是否需要批量操作**:批量分配、批量关闭? +- [ ] **6. 是否需要操作日志**:是否复用 `operation_log` 记录关键状态变更? diff --git a/database/designs/after-sale-work-order-design.md b/database/designs/after-sale-work-order-design.md new file mode 100644 index 0000000..13d2914 --- /dev/null +++ b/database/designs/after-sale-work-order-design.md @@ -0,0 +1,440 @@ +# 售后工单表设计方案 + +> **状态**: ✅ 已落库(开发环境) +> **设计日期**: 2026-07-28(v4 定稿:新增 parent_work_order_id 支持主子工单) +> **设计人**: wms-db-agent +> **说明**: 本文档仅输出设计方案,不执行落库。审阅通过后再生成迁移文件。 + +--- + +## 一、需求概述 + +1. **主表**:售后工单单表,支持灵活绑定多种业务单据(运单、订单、入库单、退货单等),通过 `business_type` + `business_sub_type` + `business_id` 三级多态关联 +2. **副表**:进度步骤处理表,记录每一步的操作员工、动作、备注(步骤不预设模板,由业务逻辑动态创建) +3. **状态流转**:工单整体状态 + 主表 `current_step` 进度 + 步骤级状态三层次 +4. **简单记账**:记录是"进"还是"出" +5. **理赔追踪**:是否需要理赔、理赔金额、理赔结算状态 +6. **附件关联**:通过现有 `wms_file_reference` 表关联附件/图片 + +--- + +## 二、表结构设计 + +### 2.1 主表:`wms_after_sale_work_order`(售后工单主表) + +| # | 字段名 | 类型 | 必填 | 默认值 | 说明 | +|---|--------|------|------|--------|------| +| 1 | `id` | `BIGINT(20) UNSIGNED` | Y | AUTO | 主键ID | +| 2 | `warehouse_id` | `BIGINT(20) UNSIGNED` | Y | — | 仓库ID | +| 3 | `store_id` | `BIGINT(20) UNSIGNED` | Y | — | 货主ID | +| 4 | `work_order_no` | `VARCHAR(50)` | Y | — | 售后工单号,唯一,格式 `AS` + 时间戳(如 AS202607280001) | +| 5 | `business_type` | `VARCHAR(50)` | Y | — | 关联业务类型,见 §3.1 枚举及 §五 Model 内置定义 | +| 6 | `business_sub_type` | `VARCHAR(50)` | Y | — | 关联业务子类型,如运单下的 `intercept`(拦截)、订单下的 `mis_shipment`(错发),见 §五 | +| 7 | `business_id` | `BIGINT(20) UNSIGNED` | Y | — | 关联业务单据主键ID(多态关联) | +| 8 | `business_no` | `VARCHAR(100)` | N | — | 关联业务单据号(冗余,方便列表展示) | +| 9 | `direction` | `TINYINT UNSIGNED` | Y | 0 | 记账方向:`1`=入库(退货入库/换货入库),`2`=出库(补发/换货出库),`0`=未确定 | +| 10 | `status` | `TINYINT UNSIGNED` | Y | 0 | 工单状态,见 §3.4 状态机 | +| 11 | `priority` | `TINYINT UNSIGNED` | Y | 50 | 优先级:`1`~`100`,数字越大优先级越高,由客服接待或AI自动识别填入 | +| 12 | `title` | `VARCHAR(200)` | Y | — | 工单标题/摘要 | +| 13 | `description` | `TEXT` | N | — | 问题描述 | +| 14 | `creator_id` | `BIGINT(20) UNSIGNED` | Y | — | 创建人ID,关联 `account.id`;`0` 表示 AI 自动接待 | +| 15 | `creator_snapshot` | `TEXT` | N | — | 创建人信息快照(JSON格式);AI创建时记录模型/会话信息 | +| 16 | `assignee_id` | `BIGINT(20) UNSIGNED` | N | — | 当前处理人ID,关联 `account.id` | +| 17 | `parent_work_order_id` | `BIGINT(20) UNSIGNED` | N | — | 父工单ID,自关联 `wms_after_sale_work_order.id`;非空时表示当前工单为子工单 | +| 18 | `current_step` | `TINYINT UNSIGNED` | Y | 1 | **当前进度**(位于主表),值为当前正在处理的 `step_order` 序号 | +| 19 | `claim_needed` | `TINYINT UNSIGNED` | Y | 0 | 是否需要理赔:`0`=不需要,`1`=需要 | +| 20 | `claim_amount` | `DECIMAL(12,2)` | N | 0.00 | 理赔金额(元),精度2位小数 | +| 21 | `claim_status` | `TINYINT UNSIGNED` | Y | 0 | 理赔状态:`0`=未理赔,`1`=已理赔(单笔结清),`2`=月结 | +| 22 | `resolution` | `TEXT` | N | — | 处理结果说明 | +| 23 | `resolved_at` | `DATETIME` | N | — | 解决时间 | +| 24 | `created_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP` | 创建时间 | +| 25 | `updated_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP ON UPDATE` | 更新时间 | +| 26 | `deleted_at` | `DATETIME` | N | — | 软删除时间 | + +**索引设计**: + +| 索引名 | 字段 | 类型 | 说明 | +|--------|------|------|------| +| `PRIMARY` | `id` | 主键 | — | +| `uk_work_order_no` | `work_order_no` | 唯一 | 工单号唯一 | +| `idx_warehouse_id` | `warehouse_id` | 普通 | 按仓库查询 | +| `idx_store_id` | `store_id` | 普通 | 按货主查询 | +| `idx_business_type_subtype_id` | `business_type, business_sub_type, business_id` | 普通 | 按业务类型+子类型+单据ID反查工单 | +| `idx_status` | `status` | 普通 | 按状态筛选 | +| `idx_assignee_id` | `assignee_id` | 普通 | 按处理人查询 | +| `idx_parent_work_order_id` | `parent_work_order_id` | 普通 | 按父工单查所有子工单 | +| `idx_priority` | `priority` | 普通 | 按优先级排序 | +| `idx_claim_status` | `claim_status` | 普通 | 按理赔状态筛选 | +| `idx_created_at` | `created_at` | 普通 | 按时间排序 | +| `idx_deleted_at` | `deleted_at` | 普通 | 软删除查询 | + +--- + +### 2.2 副表:`wms_after_sale_work_order_step`(售后工单进度步骤表) + +| # | 字段名 | 类型 | 必填 | 默认值 | 说明 | +|---|--------|------|------|--------|------| +| 1 | `id` | `BIGINT(20) UNSIGNED` | Y | AUTO | 主键ID | +| 2 | `work_order_id` | `BIGINT(20) UNSIGNED` | Y | — | 工单ID,关联 `wms_after_sale_work_order.id` | +| 3 | `step_order` | `TINYINT UNSIGNED` | Y | 1 | 步骤序号(从1开始递增) | +| 4 | `step_name` | `VARCHAR(100)` | Y | — | 步骤名称 | +| 5 | `step_status` | `TINYINT UNSIGNED` | Y | 0 | 步骤状态:`0`=待开始,`1`=进行中,`2`=已完成,`3`=已跳过 | +| 6 | `operator_id` | `BIGINT(20) UNSIGNED` | N | — | 操作员工ID,关联 `account.id` | +| 7 | `operator_snapshot` | `TEXT` | N | — | 操作人信息快照(JSON格式) | +| 8 | `action` | `VARCHAR(100)` | N | — | 操作动作描述(如"核实问题属实,安排退货入库") | +| 9 | `remark` | `TEXT` | N | — | 处理备注 | +| 10 | `started_at` | `DATETIME` | N | — | 步骤开始时间 | +| 11 | `completed_at` | `DATETIME` | N | — | 步骤完成时间 | +| 12 | `created_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP` | 创建时间 | +| 13 | `updated_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP ON UPDATE` | 更新时间 | +| 14 | `deleted_at` | `DATETIME` | N | — | 软删除时间 | + +**索引设计**: + +| 索引名 | 字段 | 类型 | 说明 | +|--------|------|------|------| +| `PRIMARY` | `id` | 主键 | — | +| `idx_work_order_id` | `work_order_id` | 普通 | 按工单查所有步骤 | +| `idx_operator_id` | `operator_id` | 普通 | 按操作人反查 | +| `idx_deleted_at` | `deleted_at` | 普通 | 软删除查询 | +| `uk_work_order_step` | `work_order_id, step_order, deleted_at` | 唯一 | 同一工单下步骤序号唯一(含软删除) | + +--- + +## 三、枚举定义 + +### 3.1 `business_type` 与 `business_sub_type`(业务类型及子类型) + +业务类型和子类型由 Model 文件 `app/model/after_sale_work_order.js` 中的 `BUSINESS_TYPES` 常量统一定义。数据库层面使用 `VARCHAR(50)` 存储,方便扩展。 + +#### 内置业务类型总览 + +| business_type | 业务名称 | 关联表 | 子类型 (business_sub_type) | +|---------------|---------|--------|---------------------------| +| `waybill` | 运单 | `wms_order_express` | `intercept`(拦截)、`urge`(催件)、`damage`(破损)、`lost`(丢件)、`wrong_info`(信息错误) | +| `order_delivery` | 发货订单 | `wms_order_delivery` | `mis_shipment`(错发)、`missing_item`(少发)、`wrong_sku`(错品)、`quality_issue`(质量问题)、`delivery_delay`(发货延迟) | +| `entry_order` | 入库单 | `wms_entry_order` | `shortage`(少货)、`damage`(破损)、`wrong_sku`(错品)、`quality_issue`(质量问题) | +| `order_stockout` | 出库单/退货出库单 | `wms_order_stockout` | `return_issue`(退货异常)、`wrong_outbound`(错发)、`shortage`(少发) | +| `receiving` | 收货单 | `wms_receiving` | `shortage`(少货)、`damage`(破损)、`quality_issue`(质量问题) | +| `other` | 其他 | — | `general`(通用) | + +> **扩展方式**:在 Model 的 `BUSINESS_TYPES` 常量中增删条目即可,无需 ALTER TABLE。外部代码通过 `require` Model 文件读取。 + +### 3.2 `priority`(优先级) + +``` +1 ~ 100 的整数,数字越大优先级越高。 +由客服接待手动填入,或由 AI 根据问题描述自动识别并填入。 +默认值 50(中等优先级)。 +``` + +### 3.3 `direction`(记账方向) + +``` +0 — 未确定 +1 — 入库(IN):退货入库 / 换货入库 / 赔付补货入库 +2 — 出库(OUT):补发出库 / 换货出库 / 退款退货出库 +``` + +> 与 `stock_transaction.transaction_type`(`INBOUND`/`OUTBOUND`)语义对齐。 + +### 3.4 `status`(工单状态) + +``` +0 — 待处理 (工单刚创建,尚未分配) +1 — 处理中 (已分配处理人,正在推进) +2 — 已完成 (问题已解决,全部步骤完成) +3 — 已关闭 (问题关闭,不再跟进) +9 — 已取消 (工单作废) +``` + +### 3.5 `claim_status`(理赔状态) + +``` +0 — 未理赔 (不需要理赔,或尚未发起理赔) +1 — 已理赔 (单笔已结清,理赔款项已到账) +2 — 月结 (纳入月度结算,按月统一对账打款) +``` + +### 3.6 `step_status`(步骤状态) + +``` +0 — 待开始 (步骤尚未激活) +1 — 进行中 (当前正在处理的步骤) +2 — 已完成 (步骤已处理完毕) +3 — 已跳过 (该步骤被跳过,不适用) +``` + +### 3.7 `creator_id` 特殊值 + +``` +0 — AI 自动接待(非员工账号创建) +> 0 — 对应 account.id,人工客服/员工创建 +``` + +> 当 `creator_id = 0` 时,`creator_snapshot` 可记录 AI 模型标识及会话 ID 等元信息。 + +--- + +## 四、状态流转设计 + +### 4.1 工单级别状态机 + +``` + ┌──────────────────────────────────┐ + │ │ + ┌───┴──────┐ ┌───┴──────┐ + 创建工单 ───→ │ 待处理(0) │ ──── 分配处理人 ───→ │ 处理中(1) │ + └───┬──────┘ └───┬──────┘ + │ │ + │ 取消 │ 全部步骤完成 + ↓ ↓ + ┌───┴──────┐ ┌───┴──────┐ + │ 已取消(9) │ │ 已完成(2) │ + └──────────┘ └───┬──────┘ + │ + │ 关闭 + ↓ + ┌───┴──────┐ + │ 已关闭(3) │ + └──────────┘ +``` + +**流转规则**: + +| 当前状态 | 允许流转到 | 触发条件 | +|----------|-----------|----------| +| `0-待处理` | `1-处理中` | 分配处理人 | +| `0-待处理` | `9-已取消` | 主动取消 | +| `1-处理中` | `2-已完成` | 所有步骤均标记为已完成 | +| `1-处理中` | `9-已取消` | 主动取消 | +| `2-已完成` | `3-已关闭` | 确认关闭 | +| `3-已关闭` | — | 终态,不可流转 | + +### 4.2 步骤级别状态机 + +``` + ┌──────────────────────────────────┐ + │ │ + ┌───┴──────┐ ┌───┴──────┐ + 步骤创建 ───→ │ 待开始(0) │ ──── 开始处理 ───→ │ 进行中(1) │ + └───┬──────┘ └───┬──────┘ + │ │ + │ 跳过 │ 完成 + ↓ ↓ + ┌───┴──────┐ ┌───┴──────┐ + │ 已跳过(3) │ │ 已完成(2) │ + └──────────┘ └──────────┘ +``` + +**约束**: +- 同一工单下,同一时刻最多只有 1 个步骤处于 `进行中(1)` +- 步骤按 `step_order` 顺序流转,但允许跳过中间步骤 +- 工单进度由主表 `current_step` 字段追踪,指向当前正在处理的 `step_order` +- 所有步骤标记为 `已完成(2)` 或 `已跳过(3)` 后,`current_step` 置为最终步骤号,工单状态可流转至 `已完成(2)` + +--- + +## 五、Model 内置业务类型定义 + +> **步骤不预设模板**:`wms_after_sale_work_order_step` 表的步骤由业务逻辑在运行时动态创建,不在数据库或 Model 中硬编码步骤模板。 + +### 5.1 `BUSINESS_TYPES` 常量(定义在 `app/model/after_sale_work_order.js`) + +```javascript +/** + * 售后工单业务类型定义 + * 外部可通过 require('./app/model/after_sale_work_order').BUSINESS_TYPES 访问 + * 增删业务类型或子类型只需修改此常量,无需 ALTER TABLE + */ +const BUSINESS_TYPES = { + waybill: { + label: '运单', + table: 'wms_order_express', // 关联的数据库表名 + subtypes: { + intercept: '拦截', + urge: '催件', + damage: '破损', + lost: '丢件', + wrong_info: '信息错误', + }, + }, + order_delivery: { + label: '发货订单', + table: 'wms_order_delivery', + subtypes: { + mis_shipment: '错发', + missing_item: '少发', + wrong_sku: '错品', + quality_issue: '质量问题', + delivery_delay: '发货延迟', + }, + }, + entry_order: { + label: '入库单', + table: 'wms_entry_order', + subtypes: { + shortage: '少货', + damage: '破损', + wrong_sku: '错品', + quality_issue: '质量问题', + }, + }, + order_stockout: { + label: '出库单/退货出库单', + table: 'wms_order_stockout', + subtypes: { + return_issue: '退货异常', + wrong_outbound: '错发', + shortage: '少发', + }, + }, + receiving: { + label: '收货单', + table: 'wms_receiving', + subtypes: { + shortage: '少货', + damage: '破损', + quality_issue: '质量问题', + }, + }, + other: { + label: '其他', + table: null, + subtypes: { + general: '通用', + }, + }, +}; + +// 辅助函数:根据 business_type 获取关联表名 +function getBusinessTable(businessType) { + return BUSINESS_TYPES[businessType]?.table || null; +} + +// 辅助函数:校验 business_type + business_sub_type 组合是否合法 +function isValidSubType(businessType, businessSubType) { + const def = BUSINESS_TYPES[businessType]; + return def && Object.prototype.hasOwnProperty.call(def.subtypes, businessSubType); +} + +module.exports = { BUSINESS_TYPES, getBusinessTable, isValidSubType }; +``` + +### 5.2 使用示例 + +```javascript +// 外部读取 +const { BUSINESS_TYPES, getBusinessTable, isValidSubType } = require('./app/model/after_sale_work_order'); + +// 获取所有业务类型列表 +Object.keys(BUSINESS_TYPES); // ['waybill', 'order_delivery', 'entry_order', ...] + +// 获取运单下的子类型 +BUSINESS_TYPES.waybill.subtypes; // { intercept: '拦截', urge: '催件', ... } + +// 获取关联表 +const table = getBusinessTable('waybill'); // 'wms_order_express' + +// 校验合法性 +isValidSubType('waybill', 'intercept'); // true +isValidSubType('waybill', 'mis_shipment'); // false +``` + +--- + +## 六、与现有系统的关联 + +### 6.1 与业务单据的多态关联(三级定位) + +``` +wms_after_sale_work_order + .business_type = 'waybill' + .business_sub_type = 'intercept' ← 子类型(Model 常量定义) + .business_id = 12345 ← wms_order_express.id + .business_no = 'YD202607280001' ← 冗余单号 + +实际关联链路: + business_type → BUSINESS_TYPES[type].table → 确定关联表 + business_id → 关联表主键 + business_sub_type → 细分工单类别(如拦截/催件/破损) + +示例: + ├── 'waybill' / 'intercept' → wms_order_express.id + ├── 'waybill' / 'urge' → wms_order_express.id + ├── 'waybill' / 'damage' → wms_order_express.id + ├── 'order_delivery' / 'mis_shipment' → wms_order_delivery.id + ├── 'order_delivery' / 'missing_item' → wms_order_delivery.id + ├── 'entry_order' / 'shortage' → wms_entry_order.id + ├── 'order_stockout' / 'return_issue' → wms_order_stockout.id + ├── 'receiving' / 'damage' → wms_receiving.id + └── 'other' / 'general' → 自定义 +``` + +### 6.2 与库存交易的对账 + +``` +售后工单.direction = 1 (入库) + → stock_transaction.transaction_type = 'INBOUND' + → stock_transaction.order_type = 'AFTER_SALE' (需同步在 stock_transaction 中新增此类型) + +售后工单.direction = 2 (出库) + → stock_transaction.transaction_type = 'OUTBOUND' + → stock_transaction.order_type = 'AFTER_SALE' +``` + +### 6.4 与附件的关联 + +售后工单不新增附件字段,复用现有 `wms_file_reference` 表做多态附件关联: + +``` +wms_file_reference + .reference_type = 'after_sale_work_order' ← 固定标识 + .reference_id = 工单 id ← wms_after_sale_work_order.id + .file_id = 文件 id ← wms_file.id + +示例:一张工单可关联多张图片/多个附件(如破损照片、快递面单照片等)。 +``` + +> `file_reference` 表已支持多态关联(`reference_type` + `reference_id`),无需新建表或字段。 + +### 6.5 与员工的关联 + +``` +wms_after_sale_work_order.creator_id → account.id(创建人) +wms_after_sale_work_order.assignee_id → account.id(当前处理人) +wms_after_sale_work_order_step.operator_id → account.id(步骤操作人) +``` + +--- + +## 七、待确认事项(审阅清单) + +请审阅时重点关注以下设计决策: + +- [x] **1. `business_type` 枚举值**:`order_delivery` / `entry_order` / `order_stockout` / `waybill` / `receiving` / `other` — ✅ 已确认,暂不增加 `return_order` 独立类型(退货场景通过 `order_stockout` 覆盖) +- [x] **2. `direction` 记账方向**:`1`=入库 / `2`=出库 / `0`=未确定 — ✅ 已确认,细粒度区分由关联的实际出入库单承载 +- [x] **3. 工单状态值**:`0-待处理/1-处理中/2-已完成/3-已关闭/9-已取消` — ✅ 已确认,当前中间态足够,无需增加"驳回/退回" +- [x] **4. 预设步骤模板**:不再预设步骤模板,步骤由业务逻辑动态创建 ✅ +- [x] **5. `business_id` 多态关联**:采用 `business_type` + `business_sub_type` + `business_id` 三级多态关联,子类型由 Model 常量定义 ✅ +- [x] **6. 理赔信息**:已新增 `claim_needed` / `claim_amount` / `claim_status` 三个字段 ✅ +- [x] **7. 进度追踪**:进度由主表 `current_step` 字段承载(不再仅依赖副表步骤状态) ✅ +- [x] **8. 优先级**:改为 `TINYINT UNSIGNED` 取值范围 `1-100`,由客服或 AI 自动识别填入,默认值 `50` ✅ +- [x] **9. AI 创建支持**:`creator_id = 0` 表示 AI 自动接待,`creator_snapshot` 记录模型/会话信息 ✅ +- [x] **10. 附件/图片**:复用现有 `wms_file_reference` 表做多态关联,不新增字段 ✅ +- [x] **11. 预计完成时间**:暂不增加,后续通过 `created_at` + `priority` 做超时告警替代;SLA 配置表留待后续迭代 ✅ +- [x] **12. 关联工单**:已确认新增 `parent_work_order_id` 字段,支持主子工单拆分 ✅ +- [x] **13. 表名**:`wms_after_sale_work_order` 和 `wms_after_sale_work_order_step` — ✅ 已确认 +- [x] **14. 权限**:API 接口设计阶段再补录 `wms_permission` 记录,不阻塞表落库 ✅ + +--- + +## 八、后续落库计划(审阅通过后执行) + +1. 创建迁移文件 `database/migrations/20260728XXXXXX-create-wms-after-sale-work-order.js` +2. 创建迁移文件 `database/migrations/20260728XXXXXX-create-wms-after-sale-work-order-step.js` +3. 创建 Model 文件 `app/model/after_sale_work_order.js` +4. 创建 Model 文件 `app/model/after_sale_work_order_step.js` +5. 在 `methods/system.json` 中新增接口路由 +6. 如需,在 `stock_transaction.order_type` 中新增 `AFTER_SALE` 枚举值(独立迁移) +7. 如需,新增 `wms_permission` 权限记录 diff --git a/database/designs/waybill-module-design.md b/database/designs/waybill-module-design.md new file mode 100644 index 0000000..a963fe6 --- /dev/null +++ b/database/designs/waybill-module-design.md @@ -0,0 +1,579 @@ +# 运单号模块设计方案(仓库侧) + +> **状态**: ⏳ 等待审阅 +> **设计日期**: 2026-07-29 +> **设计人**: wms-db-agent +> **说明**: 本文档仅输出设计方案,不执行代码实现。审阅通过后再进入开发。 +> **命名空间**: `waybill.warehouse.*`(仓库侧操作);后续预留 `waybill.store.*`(货主侧操作),本期不实现。 + +--- + +## 一、需求概述 + +当前系统缺少独立的运单号查询与管理界面。运单数据(`wms_order_express`)始终依附于订单上下文——运单信息仅通过订单详情接口(`xxx.detail`)的 `expresses[]` 字段返回,或通过 `index.toOrder` 做运单号→订单反查。实际业务中需要: + +1. **运单号列表(仓库侧)**:按仓库维度,独立查询所有运单号,支持多条件筛选、分页,支持主单号/子单号关联展示与查询 +2. **运单详情(仓库侧)**:查看单个运单的完整信息,包含关联订单、打印记录、打包状态、称重信息 +3. **运单导出(仓库侧)**:支持按筛选条件导出运单列表 + +> **主单号/子单号规则**(沿用已有业务约定):同一 `order_id` 下,`business_key = 1` 的运单为**主单号**,`business_key > 1` 的运单为**子单号**(即拆单产生的子运单)。该规则已在 `order_export.js` 导出逻辑中使用。 +> +> **命名空间规划**:`waybill.warehouse.*` 本期实现(仓库侧操作);后续按需扩展 `waybill.store.*`(货主侧操作,按 `store_id` 维度查询)。两套接口共享底层 `systems/waybill.js` 业务逻辑,仅入口鉴权与数据隔离维度不同。 + +--- + +## 二、数据模型分析 + +### 2.1 核心表:`wms_order_express`(运单表,已有) + +当前表结构(关键字段): + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | `BIGINT(20) UNSIGNED` PK | 主键 | +| `waybill_code` | `VARCHAR(50)` | **运单号** | +| `order_id` | `BIGINT(20)` | 订单ID | +| `warehouse_id` | `BIGINT(20) UNSIGNED` | 仓库ID | +| `business_key` | `INTEGER(3)` | 拆单序号(1=主单号,>1=子单号) | +| `status` | `TINYINT(1)` DEFAULT 0 | 状态(1=已分配,0=未分配) | +| `logistics_interface_id` | `BIGINT(20) UNSIGNED` | 物流接口ID | +| `logistics_code` | `VARCHAR(50)` | 物流公司编码 | +| `logistics_name` | `VARCHAR(50)` | 物流公司名称 | +| `logistics_interface_id` | `BIGINT(20) UNSIGNED` | 物流接口ID | +| `logistics_interface_name` | `VARCHAR(50)` | 物流接口名称 | +| `platform_code` | `VARCHAR(50)` | 平台编码 | +| `is_galaxy_receive` | `ENUM('Y','N')` | 是否星河签收 | +| `is_back` | `ENUM('Y','N')` | 是否退回 | +| `is_intercept` | `ENUM('Y','N')` | 是否拦截 | +| `weighing_weight` | `INT(11)` DEFAULT 0 | 称重重量(g) | +| `package_material_id` | `BIGINT(20) UNSIGNED` | 包材ID | +| `package_material_name_snapshot` | `VARCHAR(128)` | 包材名称快照 | +| `printinfo` | `TEXT('long')` | 打印信息 | +| `ver` | `VARCHAR(50)` | 打印版本号 | +| `retry_count` | `TINYINT(3)` | 重试次数 | +| `create_at` | `DATE` | 创建时间 | +| `delete_at` | `DATE` | 删除时间 | + +**现有索引**: + +| 索引名 | 字段 | 类型 | +|--------|------|------| +| `PRIMARY` | `id` | 主键 | +| `uk_order_id_business_key` | `order_id, business_key` | 唯一 | +| `idx_waybill_code` | `waybill_code` | 普通 | +| `idx_create_at` | `create_at` | 普通 | +| `idx_wms_order_express_package_material_id` | `package_material_id` | 普通 | + +### 2.2 关联表 + +| 表名 | 关联字段 | 用途 | +|------|---------|------| +| `wms_order_delivery`(current/history/dispatch) | `order_id` | 订单信息(订单号、货主、波次等) | +| `wms_express` | `logistics_code` ↔ `code` | 物流公司名称(统一展示名) | +| `express_print_record` | `express_no` ↔ `waybill_code` | 打印记录(打印时间、打印机、模板) | +| `pack_task` | `waybill_code` | 打包任务(打包状态、打包人、打包时间) | +| `package_material` | `package_material_id` ↔ `id` | 包材详情 | + +### 2.3 索引评估 + +当前 `wms_order_express` 表的索引不足以支撑运单列表场景的高频查询: + +| 缺失索引 | 原因 | +|---------|------| +| `idx_warehouse_id_status` | 运单列表按仓库+状态是最常见查询 | +| `idx_logistics_code` | 按物流公司筛选运单 | +| `idx_logistics_interface_id` | 按快递接口ID筛选运单 | +| `idx_warehouse_id_create_at` | 仓库+时间范围排序分页 | +| `idx_order_id_business_key` | 已有 `uk_order_id_business_key` 唯一索引,可同时覆盖主单号 SELF JOIN 查询 | + +> **索引迁移**:以下索引将通过迁移文件 `YYYYMMDDHHmmss-add-waybill-list-indexes.js` 正式创建,见 §五 文件变更清单。 + +### 2.4 主单号/子单号关联关系 + +**规则**(沿用系统已有约定): + +- 同一 `order_id` 下,`business_key = 1` → **主单号**(main waybill) +- 同一 `order_id` 下,`business_key > 1` → **子单号**(child waybill) +- 该规则已在 `app/service/systems/order_export.js` 第 444 行使用:`business_key === 1 ? '主单号' : '子单号'` + +**查询方式**: + +- **正向查(子→主)**:在 `wms_order_express` 上做 SELF JOIN,`t1.order_id = t2.order_id AND t2.business_key = 1` 获取主单号 +- **反向查(主→子)**:通过 `order_id` + `business_key > 1` 查子单号;或通过主单号 `waybill_code` 先定位 `order_id`,再查该订单下所有运单 + +**注意**: +- 大部分运单 `business_key = 1`(未拆单),此时主单号 = 运单号本身 +- 仅拆单场景下存在 `business_key > 1` 的子单号 + +--- + +## 三、接口设计 + +### 3.1 模块概览 + +| 项目 | 说明 | +|------|------| +| 模块名 | `waybill.warehouse` | +| 接口路径 | `POST /system`,body 中 `method` 字段为 `waybill.warehouse.{方法名}` | +| 请求方式 | 全部 `POST`,参数放在 `body` 内 | +| 鉴权 | 查询类接口需登录但无需鉴权;导出需登录 | +| 数据隔离 | 按 `warehouse_id` 隔离(仓库侧视角,见 §3.1.1 仓库隔离策略) | +| 后续扩展 | 预留 `waybill.store.*`(货主侧,按 `store_id` 隔离),本期不实现 | + +### 3.1.1 仓库隔离策略(已核实) + +**核实结论**:仓库隔离策略与系统现有模式一致,无需调整。 + +**请求上下文来源**(系统统一约定): + +| 项目 | 值 | 说明 | +|------|-----|------| +| 仓库ID来源 | `ctx.user.store_id` | 全系统统一:`ctx.user.store_id` 即为当前操作用户所属仓库的 `warehouse_id` | +| 后备方案 | 无(必须登录) | 未登录用户无法访问,不存在 `store_id` 为空的情况 | +| 注入方式 | WHERE 条件自动追加 | 在 `systems/waybill.js` 中 `const warehouseId = Number(ctx.user.store_id)`,追加 `warehouse_id = warehouseId` 到所有查询的 WHERE 子句 | +| 注入时机 | 业务层(systems) | 不在入口层(systemMethods)注入,保持业务层职责单一 | + +**参考依据**(系统内一致使用 `ctx.user.store_id` 作为 warehouse_id): + +| 文件 | 行号/位置 | 用法 | +|------|----------|------| +| `systems/waybill.js`(现有 toOrder) | 第 29 行 | `ctx.user && ctx.user.store_id ? ctx.user.store_id : null` | +| `systemMethods/index.js` | 第 1593 行 | `ctx.user && ctx.user.store_id ? Number(ctx.user.store_id) : null` | +| `systemMethods/print.js` | 第 725 行 | `ctx.user.store_id` | +| `systemMethods/stock/transaction.js` | 第 32 行 | `Number(this.ctx.user && this.ctx.user.store_id)` | +| `systemMethods/storage/management.js` | JSDoc 注释 | "仓库 ID 从用户上下文(ctx.user.store_id / ctx.user.warehouse_id)自动获取" | + +> **注**:部分文件也支持 `ctx.user.warehouse_id` 作为备选来源(如 `storage/management.js`),但 `ctx.user.store_id` 是全系统主要来源,且 `wms_order_express` 表中的 `warehouse_id` 字段语义上对应 `store_id`。本期统一使用 `ctx.user.store_id`。 + +### 3.2 文件规划 + +``` +app/service/systemMethods/waybill/warehouse.js ← 入口层(鉴权、参数校验、委托) +app/service/systems/waybill.js ← 业务层(扩展:新增 list/detail/export 方法) +methods/system.json ← API 文档(新增 waybill.warehouse group) +``` + +> **注意**: +> - `app/service/systems/waybill.js` 已有 `toOrder()` 方法(运单反查),新方法将添加到同一文件中。 +> - 目录 `systemMethods/waybill/` 预留 `store.js`(货主侧入口),本期仅创建 `warehouse.js`。 + +### 3.3 调用链路 + +``` +POST /system { method: "waybill.warehouse.list", ... } + → app/router.js + → app/service/system.js + → app/service/systemMethods/waybill/warehouse.js ← 鉴权 + 参数校验 + → app/service/systems/waybill.js ← 业务逻辑 + DB操作 + → ctx.model.OrderExpress ← Sequelize Model + → ctx.model.OrderDeliveryFactory ← 订单信息补充 + → ctx.model.Express ← 物流公司名称 + → ctx.model.ExpressPrintRecord ← 打印记录 +``` + +--- + +### 3.4 接口清单 + +| # | method | 描述 | 需登录 | 需鉴权 | +|---|--------|------|--------|--------| +| 1 | `waybill.warehouse.list` | 运单列表-仓库侧(分页+筛选) | ✓ | ✗ | +| 2 | `waybill.warehouse.detail` | 运单详情-仓库侧(含订单/打印/打包/称重信息) | ✓ | ✗ | +| 3 | `waybill.warehouse.export` | 运单导出-仓库侧(按筛选条件) | ✓ | ✗ | + +> **预留接口(本期不实现)**: +> +> | # | method | 描述 | +> |---|--------|------| +> | 4 | `waybill.store.list` | 运单列表-货主侧(按 store_id 隔离) | +> | 5 | `waybill.store.detail` | 运单详情-货主侧 | +> | 6 | `waybill.store.export` | 运单导出-货主侧 | + +--- + +### 3.5 `waybill.warehouse.list` — 运单列表(仓库侧) + +**功能说明**:查询运单号列表,支持分页与多条件筛选。仓库隔离(自动注入 `warehouse_id`)。 + +#### 请求参数 + +```json +{ + "method": "waybill.warehouse.list", + "pagination": { + "page": 1, + "pageSize": 20 + }, + "where": { + "waybillCode": "", + "mainWaybillCode": "", + "orderId": null, + "logisticsCode": "", + "logisticsInterfaceId": null, + "platformCode": "", + "status": null, + "isBack": null, + "isIntercept": null, + "isGalaxyReceive": null, + "packageMaterialId": null, + "hasWeighingWeight": null, + "keyword": "", + "createdAtStart": "", + "createdAtEnd": "" + }, + "sort": { + "field": "create_at", + "order": "desc" + } +} +``` + +#### 参数说明 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `pagination` | `object` | ✗ | 分页参数 `{ page, pageSize }`,默认 page=1, pageSize=20 | +| `where` | `object` | ✗ | 筛选条件,所有字段均为可选 | +| `where.waybillCode` | `string` | ✗ | 运单号(模糊搜索) | +| `where.mainWaybillCode` | `string` | ✗ | **主单号**(精确匹配)。先通过主单号定位 `order_id`,再返回该订单下所有运单(主+子)。与 `waybillCode` 互斥,同时传入时 `mainWaybillCode` 优先 | +| `where.orderId` | `number` | ✗ | 订单ID(等值) | +| `where.orderNo` | `string` | ✗ | 订单号(需要 JOIN 订单表后模糊匹配) | +| `where.logisticsCode` | `string` | ✗ | 物流公司编码(等值) | +| `where.logisticsInterfaceId` | `number` | ✗ | **物流接口ID**(等值),对应 `wms_order_express.logistics_interface_id`,用于按快递接口筛选运单列表 | +| `where.platformCode` | `string` | ✗ | 平台编码(等值),如 PDD/DY/KS/JD/CAINIAO/SPH/XHS | +| `where.status` | `number` | ✗ | 运单状态:`0`=未分配,`1`=已分配 | +| `where.isBack` | `string` | ✗ | 是否退回:`Y`/`N` | +| `where.isIntercept` | `string` | ✗ | 是否拦截:`Y`/`N` | +| `where.isGalaxyReceive` | `string` | ✗ | 是否星河签收:`Y`/`N` | +| `where.packageMaterialId` | `number` | ✗ | 包材ID(等值) | +| `where.hasWeighingWeight` | `boolean` | ✗ | 是否已称重:`true`=weighing_weight>0,`false`=weighing_weight=0 | +| `where.keyword` | `string` | ✗ | 关键词:匹配运单号(`waybill_code`)、主单号(`main_waybill_code`)、订单号(需 JOIN) | +| `where.createdAtStart` | `string` | ✗ | 创建时间起始(YYYY-MM-DD) | +| `where.createdAtEnd` | `string` | ✗ | 创建时间截止(YYYY-MM-DD) | +| `sort` | `object` | ✗ | 排序 `{ field, order }`,默认 `create_at desc` | +| `sort.field` | `string` | ✗ | 排序字段:`create_at` / `weighing_weight` / `id` | +| `sort.order` | `string` | ✗ | 排序方向:`asc` / `desc`,默认 `desc` | + +#### 响应格式 + +```json +{ + "list": [ + { + "id": 123456, + "waybill_code": "SF1234567890", + "main_waybill_code": "SF1234567890", + "waybill_type": "主单号", + "order_id": 78901, + "order_no": "PO202607290001", + "warehouse_id": 1, + "warehouse_name": "默认仓库", + "store_id": 10, + "store_name": "测试货主", + "business_key": 1, + "status": 1, + "status_text": "已分配", + "logistics_interface_id": 3, + "logistics_code": "SF", + "logistics_name": "顺丰速运", + "logistics_interface_name": "顺丰标准", + "platform_code": "PDD", + "platform_name": "拼多多", + "is_back": "N", + "is_intercept": "N", + "is_galaxy_receive": "N", + "weighing_weight": 1250, + "weighing_weight_display": "1.25 kg", + "package_material_id": 5, + "package_material_name": "3号纸箱", + "pack_status": "已打包", + "print_count": 2, + "last_print_at": "2026-07-29 10:30:00", + "create_at": "2026-07-29 08:00:00" + } + ], + "pagination": { + "page": 1, + "pageSize": 20, + "total": 156, + "totalPages": 8 + } +} +``` + +#### 响应字段说明 + +| 字段 | 类型 | 来源 | 说明 | +|------|------|------|------| +| `id` | `number` | `wms_order_express.id` | 运单记录ID | +| `waybill_code` | `string` | `wms_order_express.waybill_code` | 运单号(当前运单的运单号) | +| `main_waybill_code` | `string` | SELF JOIN 同 order 下 `business_key=1` | **主单号**。当 `business_key=1` 时等于 `waybill_code` 本身;当 `business_key>1` 时通过 SELF JOIN 查找同 `order_id` 下 `business_key=1` 的运单号 | +| `waybill_type` | `string` | 计算字段 | 运单类型:`business_key=1` → `"主单号"`,`business_key>1` → `"子单号"` | +| `order_id` | `number` | `wms_order_express.order_id` | 订单ID | +| `order_no` | `string` | JOIN 订单表 | 订单号(`delivery_order_code`) | +| `warehouse_id` | `number` | `wms_order_express.warehouse_id` | 仓库ID | +| `warehouse_name` | `string` | JOIN `store` 表 | 仓库名称 | +| `store_id` | `number` | JOIN 订单表 | 货主ID | +| `store_name` | `string` | JOIN `store` 表 | 货主名称 | +| `business_key` | `number` | `wms_order_express.business_key` | 拆单序号 | +| `status` | `number` | `wms_order_express.status` | 状态:0/1 | +| `status_text` | `string` | 前端映射 | 状态文本 | +| `logistics_code` | `string` | `wms_order_express.logistics_code` | 物流公司编码 | +| `logistics_name` | `string` | `wms_order_express.logistics_name` | 物流公司名称 | +| `logistics_interface_id` | `number` | `wms_order_express.logistics_interface_id` | 物流接口ID | +| `logistics_interface_name` | `string` | `wms_order_express.logistics_interface_name` | 物流接口名称 | +| `platform_code` | `string` | `wms_order_express.platform_code` | 平台编码 | +| `platform_name` | `string` | 前端映射 | 平台名称 | +| `is_back` | `string` | `wms_order_express.is_back` | 是否退回 | +| `is_intercept` | `string` | `wms_order_express.is_intercept` | 是否拦截 | +| `is_galaxy_receive` | `string` | `wms_order_express.is_galaxy_receive` | 是否星河签收 | +| `weighing_weight` | `number` | `wms_order_express.weighing_weight` | 称重重量(g) | +| `weighing_weight_display` | `string` | 格式化 | 称重重量可读展示 | +| `package_material_id` | `number` | `wms_order_express.package_material_id` | 包材ID | +| `package_material_name` | `string` | `wms_order_express.package_material_name_snapshot` | 包材名称 | +| `pack_status` | `string` | LEFT JOIN `pack_task` | 打包状态("未打包"/"已打包") | +| `print_count` | `number` | COUNT `express_print_record` | 打印次数 | +| `last_print_at` | `string` | MAX `express_print_record.created_at` | 最近打印时间 | +| `create_at` | `string` | `wms_order_express.create_at` | 运单创建时间 | + +#### 查询逻辑要点 + +1. **仓库隔离**:自动注入 `warehouse_id = ctx.user.store_id`(系统统一约定,`ctx.user.store_id` 即为当前用户所属仓库ID)。所有查询 WHERE 条件自动追加 `warehouse_id`,不可由前端入参覆盖 +2. **主单号关联查询**:每条运单记录通过 SELF JOIN(`t1.order_id = t2.order_id AND t2.business_key = 1`)获取主单号 `main_waybill_code`。当 `business_key = 1` 时,主单号就是自身 `waybill_code`;当 `business_key > 1` 时,需要 JOIN 获取主单号 +3. **按主单号入参查询**:当 `where.mainWaybillCode` 传入时,先通过主单号 `waybill_code` 定位 `order_id`(`WHERE waybill_code = ? AND business_key = 1`),再 `WHERE order_id = ?` 返回该订单下所有运单(主+子) +4. **按物流接口ID查询**:直接 `WHERE logistics_interface_id = ?`,等值匹配 +5. **订单号模糊搜索**:当 `where.orderNo` 或 `where.keyword` 匹配到非纯数字运单号时,需要 JOIN 订单表(current/history/dispatch)进行 `delivery_order_code LIKE` 匹配 +6. **打印次数**:通过子查询或 LEFT JOIN + GROUP BY `express_print_record.express_no = waybill_code` 聚合 +7. **打包状态**:LEFT JOIN `pack_task` ON `waybill_code` +8. **性能注意**:打印次数和打包状态的聚合查询在数据量大时可能成为瓶颈,建议先不做 JOIN,改为按需异步加载(在 detail 接口中返回),list 只返回 `wms_order_express` 原生字段 + 主单号 SELF JOIN + +> **性能优化策略**(建议): +> - **方案 A(推荐)**:列表仅查 `wms_order_express` 原生字段,不 JOIN 订单/打印/打包表。`pack_status` 和 `print_count` 通过批量异步查询补充,或仅在 detail 接口返回。 +> - **方案 B**:列表即 JOIN,但需确保索引覆盖良好。 + +--- + +### 3.6 `waybill.warehouse.detail` — 运单详情(仓库侧) + +**功能说明**:查看单个运单的完整信息,包含关联订单、打印记录、打包信息。 + +#### 请求参数 + +```json +{ + "method": "waybill.warehouse.detail", + "id": 123456 +} +``` + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `id` | `number` | ✓ | 运单记录ID(`wms_order_express.id`) | +| `waybillCode` | `string` | ✗ | 运单号(与 id 二选一,waybillCode 优先) | + +#### 响应格式 + +```json +{ + "id": 123456, + "waybill_code": "SF1234567890", + "main_waybill_code": "SF1234567890", + "waybill_type": "主单号", + "business_key": 1, + "sibling_waybills": [ + { "waybill_code": "SF1234567890", "business_key": 1, "waybill_type": "主单号" }, + { "waybill_code": "SF1234567891", "business_key": 2, "waybill_type": "子单号" } + ], + "order": { + "order_id": 78901, + "order_no": "PO202607290001", + "warehouse_id": 1, + "warehouse_name": "默认仓库", + "store_id": 10, + "store_name": "测试货主", + "wave_id": 500, + "wave_no": "W202607290001", + "order_type": "delivery" + }, + "logistics": { + "logistics_code": "SF", + "logistics_name": "顺丰速运", + "logistics_interface_id": 3, + "logistics_interface_name": "顺丰标准", + "platform_code": "PDD" + }, + "status_info": { + "status": 1, + "status_text": "已分配", + "is_back": "N", + "is_intercept": "N", + "is_galaxy_receive": "N" + }, + "weight": { + "weighing_weight": 1250, + "weighing_weight_display": "1.25 kg" + }, + "package": { + "package_material_id": 5, + "package_material_name": "3号纸箱", + "pack_status": "已打包", + "pack_quantity": 3, + "pack_at": "2026-07-29 09:15:00", + "packer_name": "张三" + }, + "print_records": [ + { + "id": 1001, + "printer_name": "打印机-01", + "template_id": 2, + "template_name": "顺丰标准面单", + "platform": "PDD", + "printed_at": "2026-07-29 10:30:00" + } + ], + "print_count": 2, + "printinfo": "{...}", + "ver": "v2.1", + "retry_count": 0, + "create_at": "2026-07-29 08:00:00", + "delete_at": null +} +``` + +#### 查询逻辑要点 + +1. 查询 `wms_order_express` 主记录 +2. 通过 `order_id` 查询同订单下所有运单组成 `sibling_waybills`(含各运单的 `waybill_code`、`business_key`、`waybill_type`) +3. 通过 `order_id` → `OrderDeliveryFactory` 多表遍历查找订单信息 +4. LEFT JOIN `wms_express` 获取物流公司统一名称 +5. LEFT JOIN `pack_task` ON `waybill_code` 获取打包信息 +6. LEFT JOIN `express_print_record` ON `express_no = waybill_code` 获取打印记录列表 +7. 仓库隔离校验 + +--- + +### 3.7 `waybill.warehouse.export` — 运单导出(仓库侧) + +**功能说明**:按筛选条件导出运单列表为 Excel。复用 `waybill.warehouse.list` 的筛选逻辑,去掉分页,全量导出。 + +#### 请求参数 + +同 `waybill.warehouse.list`,不含 `pagination` 参数,可选增加 `exportFields` 指定导出字段。 + +```json +{ + "method": "waybill.warehouse.export", + "where": { "...": "同 waybill.warehouse.list" }, + "sort": { "...": "同 waybill.warehouse.list" }, + "exportFields": ["waybill_code", "order_no", "logistics_name", "weighing_weight", "create_at"] +} +``` + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `where` | `object` | ✗ | 同 `waybill.warehouse.list` 的筛选条件 | +| `sort` | `object` | ✗ | 同 `waybill.warehouse.list` 的排序 | +| `exportFields` | `string[]` | ✗ | 需要导出的字段列表,不传则导出全部字段 | + +--- + +## 四、`methods/system.json` 变更 + +在 `methods.groups[]` 中新增 `waybill.warehouse` group: + +```json +{ + "name": "waybill.warehouse", + "description": "运单号管理(仓库侧)", + "methods": [ + { + "method": "waybill.warehouse.list", + "description": "运单列表(分页+筛选)。仓库隔离。", + "isNeedAuth": false, + "isNeedLogin": true, + "params": [ "... 参数定义 ..." ], + "response": [ "... 返回值定义 ..." ] + }, + { + "method": "waybill.warehouse.detail", + "description": "运单详情(含订单/打印/打包信息)。仓库隔离。", + "isNeedAuth": false, + "isNeedLogin": true, + "params": [ "... 参数定义 ..." ], + "response": [ "... 返回值定义 ..." ] + }, + { + "method": "waybill.warehouse.export", + "description": "运单导出。仓库隔离。", + "isNeedAuth": false, + "isNeedLogin": true, + "params": [ "... 参数定义 ..." ], + "response": [ "... 返回值定义 ..." ] + } + ] +} +``` + +> **预留 group(本期不实现)**:`waybill.store` — 运单号管理(货主侧),按 `store_id` 隔离。 +> +> 完整的 `methods/system.json` method 定义(含 params/response 的 children 详情)在代码实现阶段由 `wms-doc-agent` 补齐。 + +--- + +## 五、文件变更清单 + +| 操作 | 文件路径 | 说明 | +|------|---------|------| +| **新增** | `app/service/systemMethods/waybill/warehouse.js` | 入口层(仓库侧):继承 `MainService`,`systemInit` 声明免鉴权方法,参数校验,委托 `systems/waybill.js` | +| **预留** | `app/service/systemMethods/waybill/store.js` | 入口层(货主侧):本期不创建,后续按需新增 | +| **修改** | `app/service/systems/waybill.js` | 业务层:在现有 `toOrder()` 方法基础上新增 `list()`、`detail()`、`export()` 方法 | +| **修改** | `methods/system.json` | 新增 `waybill.warehouse` group,注册 3 个 method 定义 | +| **新增** | `database/migrations/YYYYMMDDHHmmss-add-waybill-list-indexes.js` | 迁移文件:新增 `idx_warehouse_id_status`、`idx_logistics_code`、`idx_logistics_interface_id`、`idx_warehouse_id_create_at` 索引 | + +--- + +## 六、安全约束 + +| 约束 | 说明 | +|------|------| +| 仓库隔离 | 所有查询自动注入 `warehouse_id = ctx.user.store_id`(系统统一约定),仅返回当前用户所属仓库数据,不可由入参覆盖 | +| 只读 | 本模块一期仅提供只读查询,不涉及运单创建/修改/删除 | +| 鉴权 | 查询接口仅需登录,不做细粒度权限校验(与订单列表保持一致) | + +--- + +## 七、与现有功能的边界划分 + +| 现有功能 | 所属 method | 与新模块关系 | +|---------|------------|-------------| +| 运单号反查订单 | `index.toOrder` | **保留**,独立于新模块。用于 PDA 扫运单号快速定位订单 | +| 订单详情中的运单信息 | `order.detail → expresses[]` | **保留**,不变。新模块提供运单维度的独立视图 | +| 运单包材绑定 | `order.bindExpressPackageMaterial*` | **保留**,不变。仍按订单维度操作 | +| 运单称重更新 | `order.updateExpressWeighingWeight` | **保留**,不变。仍按订单维度操作 | +| 快递号分配 | `order.pendingOrder.allocateExpressCode` | **保留**,不变。仍按订单维度操作 | +| 订单导出(运单模式) | `order.export (export_mode=waybill)` | **保留**,不变。与新模块 `waybill.warehouse.export` 并存 | + +> **核心原则**:新模块不修改任何现有接口,仅新增运单维度的独立查询能力。现有订单维度的运单操作全部保持不动。 + +--- + +## 八、后续扩展方向(不在本期范围) + +| 扩展 | 说明 | +|------|------| +| 运单拦截/解拦截 | 批量操作运单状态 | +| 运单退回标记 | 标记运单退回并记录原因 | +| 运单打印管理 | 批量补打、重新推送电子面单 | +| 运单异常列表 | 独立展示分配失败/打印失败的运单 | +| 运单物流轨迹 | 对接物流轨迹查询接口 | + +--- + +## 九、审阅检查点 + +- [ ] 接口设计是否满足业务需求(运单号独立列表 + 详情) +- [x] ~~仓库隔离策略是否正确~~ → 已核实:全系统统一使用 `ctx.user.store_id` 作为 warehouse_id,与现有模式一致 +- [ ] 列表字段是否完整(是否需要增减字段) +- [ ] 是否需要 JOIN 订单/打印/打包表(性能 vs 信息完整性权衡) +- [ ] 是否需要新增数据库索引 +- [ ] 与现有 `index.toOrder`、`order.*` 接口的边界是否清晰 diff --git a/database/migrations/20260728000000-remove-remote-play-url-from-wms-print-computer.js b/database/migrations/20260728000000-remove-remote-play-url-from-wms-print-computer.js new file mode 100644 index 0000000..89e21fd --- /dev/null +++ b/database/migrations/20260728000000-remove-remote-play-url-from-wms-print-computer.js @@ -0,0 +1,28 @@ +'use strict'; + +module.exports = { + /** + * 移除打印电脑表的 remote_play_url 字段(未被使用)。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口 + * @param {import('sequelize')} Sequelize Sequelize 实例 + * @return {Promise} 无返回值 + */ + async up(queryInterface, Sequelize) { + await queryInterface.removeColumn('wms_print_computer', 'remote_play_url'); + }, + + /** + * 回滚:恢复 remote_play_url 字段。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口 + * @param {import('sequelize')} Sequelize Sequelize 实例 + * @return {Promise} 无返回值 + */ + async down(queryInterface, Sequelize) { + await queryInterface.addColumn('wms_print_computer', 'remote_play_url', { + type: Sequelize.STRING(500), + allowNull: true, + defaultValue: null, + comment: '远程播放地址', + }); + }, +}; diff --git a/database/migrations/20260728100000-remove-recording-config-fields-from-wms-print-computer.js b/database/migrations/20260728100000-remove-recording-config-fields-from-wms-print-computer.js new file mode 100644 index 0000000..8e3c3cd --- /dev/null +++ b/database/migrations/20260728100000-remove-recording-config-fields-from-wms-print-computer.js @@ -0,0 +1,43 @@ +'use strict'; + +module.exports = { + /** + * 移除打印电脑表的录制配置字段(recording_size_value / recording_size_unit / recording_directory), + * 这些字段不再由 WMS 侧管理。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口 + * @param {import('sequelize')} Sequelize Sequelize 实例 + * @return {Promise} 无返回值 + */ + async up(queryInterface, Sequelize) { + await queryInterface.removeColumn('wms_print_computer', 'recording_directory'); + await queryInterface.removeColumn('wms_print_computer', 'recording_size_unit'); + await queryInterface.removeColumn('wms_print_computer', 'recording_size_value'); + }, + + /** + * 回滚:恢复录制配置字段。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口 + * @param {import('sequelize')} Sequelize Sequelize 实例 + * @return {Promise} 无返回值 + */ + async down(queryInterface, Sequelize) { + await queryInterface.addColumn('wms_print_computer', 'recording_size_value', { + type: Sequelize.INTEGER.UNSIGNED, + allowNull: true, + defaultValue: null, + comment: '录制大小数值', + }); + await queryInterface.addColumn('wms_print_computer', 'recording_size_unit', { + type: Sequelize.STRING(10), + allowNull: true, + defaultValue: null, + comment: '录制存储单位:KB/MB/GB/TB', + }); + await queryInterface.addColumn('wms_print_computer', 'recording_directory', { + type: Sequelize.STRING(500), + allowNull: true, + defaultValue: null, + comment: '录制目录路径', + }); + }, +}; diff --git a/database/migrations/20260728110000-restore-recording-directory-to-wms-print-computer.js b/database/migrations/20260728110000-restore-recording-directory-to-wms-print-computer.js new file mode 100644 index 0000000..40133b5 --- /dev/null +++ b/database/migrations/20260728110000-restore-recording-directory-to-wms-print-computer.js @@ -0,0 +1,28 @@ +'use strict'; + +module.exports = { + /** + * 恢复 wms_print_computer 的 recording_directory 字段(录制目录路径)。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口 + * @param {import('sequelize')} Sequelize Sequelize 实例 + * @return {Promise} 无返回值 + */ + async up(queryInterface, Sequelize) { + await queryInterface.addColumn('wms_print_computer', 'recording_directory', { + type: Sequelize.STRING(500), + allowNull: true, + defaultValue: null, + comment: '录制目录路径', + }); + }, + + /** + * 回滚:移除 recording_directory 字段。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口 + * @param {import('sequelize')} Sequelize Sequelize 实例 + * @return {Promise} 无返回值 + */ + async down(queryInterface, Sequelize) { + await queryInterface.removeColumn('wms_print_computer', 'recording_directory'); + }, +}; diff --git a/database/migrations/20260728120000-create-wms-after-sale-work-order.js b/database/migrations/20260728120000-create-wms-after-sale-work-order.js new file mode 100644 index 0000000..6854144 --- /dev/null +++ b/database/migrations/20260728120000-create-wms-after-sale-work-order.js @@ -0,0 +1,215 @@ +'use strict'; + +const TABLE_NAME = 'wms_after_sale_work_order'; + +module.exports = { + up: async (queryInterface, Sequelize) => { + const tables = await queryInterface.showAllTables(); + const exists = tables.some(t => (typeof t === 'string' ? t : t.tableName) === TABLE_NAME); + if (exists) return; + + await queryInterface.createTable(TABLE_NAME, { + id: { + type: Sequelize.BIGINT(20).UNSIGNED, + primaryKey: true, + autoIncrement: true, + allowNull: false, + comment: '主键ID', + }, + warehouse_id: { + type: Sequelize.BIGINT(20).UNSIGNED, + allowNull: false, + comment: '仓库ID', + }, + store_id: { + type: Sequelize.BIGINT(20).UNSIGNED, + allowNull: false, + comment: '货主ID', + }, + work_order_no: { + type: Sequelize.STRING(50), + allowNull: false, + comment: '售后工单号,唯一', + }, + business_type: { + type: Sequelize.STRING(50), + allowNull: false, + comment: '关联业务类型', + }, + business_sub_type: { + type: Sequelize.STRING(50), + allowNull: false, + comment: '关联业务子类型', + }, + business_id: { + type: Sequelize.BIGINT(20).UNSIGNED, + allowNull: false, + comment: '关联业务单据主键ID(多态关联)', + }, + business_no: { + type: Sequelize.STRING(100), + allowNull: true, + comment: '关联业务单据号(冗余)', + }, + direction: { + type: Sequelize.TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 0, + comment: '记账方向:0=未确定 1=入库 2=出库', + }, + status: { + type: Sequelize.TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 0, + comment: '工单状态:0=待处理 1=处理中 2=已完成 3=已关闭 9=已取消', + }, + priority: { + type: Sequelize.TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 50, + comment: '优先级:1~100,数字越大优先级越高', + }, + title: { + type: Sequelize.STRING(200), + allowNull: false, + comment: '工单标题/摘要', + }, + description: { + type: Sequelize.TEXT, + allowNull: true, + comment: '问题描述', + }, + creator_id: { + type: Sequelize.BIGINT(20).UNSIGNED, + allowNull: false, + comment: '创建人ID,关联 account.id;0 表示 AI 自动接待', + }, + creator_snapshot: { + type: Sequelize.TEXT, + allowNull: true, + comment: '创建人信息快照(JSON格式)', + }, + assignee_id: { + type: Sequelize.BIGINT(20).UNSIGNED, + allowNull: true, + comment: '当前处理人ID,关联 account.id', + }, + parent_work_order_id: { + type: Sequelize.BIGINT(20).UNSIGNED, + allowNull: true, + comment: '父工单ID,自关联本表;非空时表示子工单', + }, + current_step: { + type: Sequelize.TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 1, + comment: '当前进度,值为当前正在处理的 step_order 序号', + }, + claim_needed: { + type: Sequelize.TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 0, + comment: '是否需要理赔:0=不需要 1=需要', + }, + claim_amount: { + type: Sequelize.DECIMAL(12, 2), + allowNull: true, + defaultValue: 0.00, + comment: '理赔金额(元)', + }, + claim_status: { + type: Sequelize.TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 0, + comment: '理赔状态:0=未理赔 1=已理赔(单笔结清) 2=月结', + }, + resolution: { + type: Sequelize.TEXT, + allowNull: true, + comment: '处理结果说明', + }, + resolved_at: { + type: Sequelize.DATE, + allowNull: true, + comment: '解决时间', + }, + created_at: { + type: Sequelize.DATE, + allowNull: false, + defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'), + comment: '创建时间', + }, + updated_at: { + type: Sequelize.DATE, + allowNull: false, + defaultValue: Sequelize.literal('CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'), + comment: '更新时间', + }, + deleted_at: { + type: Sequelize.DATE, + allowNull: true, + comment: '软删除时间', + }, + }); + + // 工单号唯一 + await queryInterface.addIndex(TABLE_NAME, ['work_order_no'], { + unique: true, + name: 'uk_work_order_no', + }); + + // 仓库隔离查询 + await queryInterface.addIndex(TABLE_NAME, ['warehouse_id'], { + name: 'idx_warehouse_id', + }); + + // 货主隔离查询 + await queryInterface.addIndex(TABLE_NAME, ['store_id'], { + name: 'idx_store_id', + }); + + // 按业务类型+子类型+单据ID反查工单 + await queryInterface.addIndex(TABLE_NAME, ['business_type', 'business_sub_type', 'business_id'], { + name: 'idx_business_type_subtype_id', + }); + + // 按状态筛选 + await queryInterface.addIndex(TABLE_NAME, ['status'], { + name: 'idx_status', + }); + + // 按处理人查询 + await queryInterface.addIndex(TABLE_NAME, ['assignee_id'], { + name: 'idx_assignee_id', + }); + + // 按父工单查子工单 + await queryInterface.addIndex(TABLE_NAME, ['parent_work_order_id'], { + name: 'idx_parent_work_order_id', + }); + + // 按优先级排序 + await queryInterface.addIndex(TABLE_NAME, ['priority'], { + name: 'idx_priority', + }); + + // 按理赔状态筛选 + await queryInterface.addIndex(TABLE_NAME, ['claim_status'], { + name: 'idx_claim_status', + }); + + // 按时间排序 + await queryInterface.addIndex(TABLE_NAME, ['created_at'], { + name: 'idx_created_at', + }); + + // 软删除查询优化 + await queryInterface.addIndex(TABLE_NAME, ['deleted_at'], { + name: 'idx_deleted_at', + }); + }, + + down: async queryInterface => { + await queryInterface.dropTable(TABLE_NAME); + }, +}; diff --git a/database/migrations/20260728120000-restore-recording-size-fields-to-wms-print-computer.js b/database/migrations/20260728120000-restore-recording-size-fields-to-wms-print-computer.js new file mode 100644 index 0000000..cbe848f --- /dev/null +++ b/database/migrations/20260728120000-restore-recording-size-fields-to-wms-print-computer.js @@ -0,0 +1,35 @@ +'use strict'; + +module.exports = { + /** + * 恢复 wms_print_computer 的 recording_size_value 和 recording_size_unit 字段。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口 + * @param {import('sequelize')} Sequelize Sequelize 实例 + * @return {Promise} 无返回值 + */ + async up(queryInterface, Sequelize) { + await queryInterface.addColumn('wms_print_computer', 'recording_size_value', { + type: Sequelize.INTEGER.UNSIGNED, + allowNull: true, + defaultValue: null, + comment: '录制大小数值', + }); + await queryInterface.addColumn('wms_print_computer', 'recording_size_unit', { + type: Sequelize.STRING(10), + allowNull: true, + defaultValue: null, + comment: '录制存储单位:KB/MB/GB/TB', + }); + }, + + /** + * 回滚:移除 recording_size_value 和 recording_size_unit 字段。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口 + * @param {import('sequelize')} Sequelize Sequelize 实例 + * @return {Promise} 无返回值 + */ + async down(queryInterface, Sequelize) { + await queryInterface.removeColumn('wms_print_computer', 'recording_size_unit'); + await queryInterface.removeColumn('wms_print_computer', 'recording_size_value'); + }, +}; diff --git a/database/migrations/20260728130000-create-wms-after-sale-work-order-step.js b/database/migrations/20260728130000-create-wms-after-sale-work-order-step.js new file mode 100644 index 0000000..3564929 --- /dev/null +++ b/database/migrations/20260728130000-create-wms-after-sale-work-order-step.js @@ -0,0 +1,115 @@ +'use strict'; + +const TABLE_NAME = 'wms_after_sale_work_order_step'; + +module.exports = { + up: async (queryInterface, Sequelize) => { + const tables = await queryInterface.showAllTables(); + const exists = tables.some(t => (typeof t === 'string' ? t : t.tableName) === TABLE_NAME); + if (exists) return; + + await queryInterface.createTable(TABLE_NAME, { + id: { + type: Sequelize.BIGINT(20).UNSIGNED, + primaryKey: true, + autoIncrement: true, + allowNull: false, + comment: '主键ID', + }, + work_order_id: { + type: Sequelize.BIGINT(20).UNSIGNED, + allowNull: false, + comment: '工单ID,关联 wms_after_sale_work_order.id', + }, + step_order: { + type: Sequelize.TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 1, + comment: '步骤序号(从1开始递增)', + }, + step_name: { + type: Sequelize.STRING(100), + allowNull: false, + comment: '步骤名称', + }, + step_status: { + type: Sequelize.TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 0, + comment: '步骤状态:0=待开始 1=进行中 2=已完成 3=已跳过', + }, + operator_id: { + type: Sequelize.BIGINT(20).UNSIGNED, + allowNull: true, + comment: '操作员工ID,关联 account.id', + }, + operator_snapshot: { + type: Sequelize.TEXT, + allowNull: true, + comment: '操作人信息快照(JSON格式)', + }, + action: { + type: Sequelize.STRING(100), + allowNull: true, + comment: '操作动作描述', + }, + remark: { + type: Sequelize.TEXT, + allowNull: true, + comment: '处理备注', + }, + started_at: { + type: Sequelize.DATE, + allowNull: true, + comment: '步骤开始时间', + }, + completed_at: { + type: Sequelize.DATE, + allowNull: true, + comment: '步骤完成时间', + }, + created_at: { + type: Sequelize.DATE, + allowNull: false, + defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'), + comment: '创建时间', + }, + updated_at: { + type: Sequelize.DATE, + allowNull: false, + defaultValue: Sequelize.literal('CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'), + comment: '更新时间', + }, + deleted_at: { + type: Sequelize.DATE, + allowNull: true, + comment: '软删除时间', + }, + }); + + // 按工单查所有步骤 + await queryInterface.addIndex(TABLE_NAME, ['work_order_id'], { + name: 'idx_work_order_id', + }); + + // 按操作人反查 + await queryInterface.addIndex(TABLE_NAME, ['operator_id'], { + name: 'idx_operator_id', + }); + + // 软删除查询优化 + await queryInterface.addIndex(TABLE_NAME, ['deleted_at'], { + name: 'idx_deleted_at', + }); + + // 同一工单下步骤序号唯一(含软删除) + await queryInterface.addIndex(TABLE_NAME, ['work_order_id', 'step_order', 'deleted_at'], { + unique: true, + name: 'uk_work_order_step', + }); + }, + + down: async queryInterface => { + await queryInterface.dropTable(TABLE_NAME); + }, +}; diff --git a/methods/changes/system.json b/methods/changes/system.json index 6913765..f3daf2b 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,47 @@ [ + { + "version": "2026.07.28-system-01", + "date": "2026-07-28", + "type": "added", + "summary": "新增 order.pendingOrder.batchMarkPrinted:批量设置订单为已打印状态,将 print_status 更新为 'fin'", + "methods": [ + "order.pendingOrder.batchMarkPrinted" + ], + "notes": [ + "同步批量更新接口,传入订单ID数组,直接将符合条件的订单 print_status 设为 'fin'。", + "双表查询:先查 current 表(wms_order_delivery_{warehouseId}),未命中的 ID 再兜底查 dispatch 表(wms_order_delivery_{warehouseId}_dispatch)。", + "dispatch 表查询失败仅记录 warn 日志,不影响 current 表已更新的结果。", + "仅允许 step 在 [1,2,3] 且 status 不为 'cancel' 的订单操作,已打印(print_status='fin')的订单会被静默跳过。", + "仓库上下文强制从 ctx.user.store_id 获取,禁止传入外部仓库ID。", + "入参支持 order_ids / orderIds / ids 三种别名,优先级 order_ids > orderIds > ids。", + "返回 updated_count 表示实际更新条数(current + dispatch 合计),ids 原样回传请求的订单ID列表。", + "写入操作日志 operation_code: ORDER_BATCH_MARK_PRINTED。" + ], + "module": "order.pendingOrder" + }, + { + "version": "2026.07.27-system-03", + "date": "2026-07-27", + "type": "changed", + "summary": "storage.receiving 导出接口拆分:export 改为按仓库维度,新增 storeExport 按货主维度导出", + "methods": [ + "storage.receiving.export", + "storage.receiving.exportTaskProgress", + "storage.receiving.storeExport", + "storage.receiving.storeExportTaskProgress" + ], + "notes": [ + "export 改为仓库维度:过滤条件从 store_id(平台激活货主)改为 warehouse_id(ctx.user.store_id),与 getReceivingList 保持一致。", + "exportTaskProgress 同步更新为仓库维度进度查询,任务 ID 前缀 receiving_export_。", + "新增 storeExport:货主维度导出,通过平台激活上下文获取 store_id,过滤逻辑与 getStoreReceivingList 一致。", + "新增 storeExportTaskProgress:货主维度进度查询,复用 exportTaskProgress 的缓存逻辑,任务 ID 前缀 receiving_store_export_。", + "导出格式:双 Sheet Excel(Sheet1=收货单列表 21 列,Sheet2=收货单明细 17 列),通过 ExcelJS stream + uploadService 上传 COS。", + "仓库导出上传路径 exports/receiving/{warehouseId}/,货主导出上传路径 exports/receiving/store/{storeId}/。", + "修复 exportReceivingList 中 where 条件二次解析问题:增加 ctx.whereParsed 复用(与 getStoreReceivingList 一致),避免 prepareWhereContext 已解析后再重复 parseWhereConditions 导致边界条件丢失。", + "命名对齐 entry 侧:storeExport / storeExportTaskProgress 方法名、任务 ID 前缀、上传路径均与 storage.entry.storeExport 模式一致。" + ], + "module": "storage.receiving" + }, { "version": "2026.07.27-system-02", "date": "2026-07-27", diff --git a/methods/system.json b/methods/system.json index c09372e..731ccea 100644 --- a/methods/system.json +++ b/methods/system.json @@ -26015,6 +26015,53 @@ } ] }, + { + "method": "order.pendingOrder.batchMarkPrinted", + "description": "批量设置订单为已打印状态。将给定订单ID列表中属于当前仓库的订单的 print_status 更新为 'fin'。先查 current 表(wms_order_delivery_{warehouseId}),未命中的 ID 再兜底查 dispatch 表(wms_order_delivery_{warehouseId}_dispatch)。仅允许 step 在 [1,2,3] 且 status 不为 'cancel' 的订单操作,已打印的订单会被静默跳过。仓库ID统一使用当前上下文(ctx.user.store_id)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "order_ids / orderIds / ids", + "type": "number[]", + "required": true, + "source": "body", + "description": "订单ID数组;优先级 order_ids > orderIds > ids" + } + ], + "response": [ + { + "name": "updated_count", + "type": "number", + "required": true, + "description": "实际更新的订单数量(已打印的订单会被静默跳过,不计入)" + }, + { + "name": "ids", + "type": "number[]", + "required": true, + "description": "请求的订单ID列表(原样回传)" + } + ], + "errors": [ + { + "code": 400, + "message": "未识别到当前仓库上下文" + }, + { + "code": 400, + "message": "order_ids 参数不能为空或格式错误" + } + ] + }, { "method": "order.bindExpressPackageMaterialByWaybill", "description": "按运单号绑定包材。仅需传入运单号与包材ID,系统自动根据运单号反查对应订单运单记录并绑定包材,无需传入订单ID。",