chore: 提交当前所有变更,准备开始 allocateSubOrderNumber step=4 改造

This commit is contained in:
liufumingren 2026-07-29 13:57:04 +08:00
parent fb2c00027e
commit 635e86f984
19 changed files with 2792 additions and 31 deletions

View File

@ -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;
};

View File

@ -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;
};

View File

@ -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,

View File

@ -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) {

View File

@ -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>|number|string} [data.order_ids] 订单ID集合(下划线写法)。
* @param {Array<number|string>|number|string} [data.orderIds] 订单ID集合(驼峰别名)。
* @param {Array<number|string>|number|string} [data.ids] 订单ID集合(简写别名)。
* @return {Promise<Object>} 统一 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;

View File

@ -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<Object>} 设置结果
*/
async setRecording(data) {

View File

@ -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',

View File

@ -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<Object>} 更新后的记录
*/
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,
});

View File

@ -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` 记录关键状态变更?

View File

@ -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` 权限记录

View File

@ -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.*` 接口的边界是否清晰

View File

@ -0,0 +1,28 @@
'use strict';
module.exports = {
/**
* 移除打印电脑表的 remote_play_url 字段(未被使用)。
* @param {import('sequelize').QueryInterface} queryInterface 查询接口
* @param {import('sequelize')} Sequelize Sequelize 实例
* @return {Promise<void>} 无返回值
*/
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<void>} 无返回值
*/
async down(queryInterface, Sequelize) {
await queryInterface.addColumn('wms_print_computer', 'remote_play_url', {
type: Sequelize.STRING(500),
allowNull: true,
defaultValue: null,
comment: '远程播放地址',
});
},
};

View File

@ -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<void>} 无返回值
*/
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<void>} 无返回值
*/
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: '录制目录路径',
});
},
};

View File

@ -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<void>} 无返回值
*/
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<void>} 无返回值
*/
async down(queryInterface, Sequelize) {
await queryInterface.removeColumn('wms_print_computer', 'recording_directory');
},
};

View File

@ -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);
},
};

View File

@ -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<void>} 无返回值
*/
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<void>} 无返回值
*/
async down(queryInterface, Sequelize) {
await queryInterface.removeColumn('wms_print_computer', 'recording_size_unit');
await queryInterface.removeColumn('wms_print_computer', 'recording_size_value');
},
};

View File

@ -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);
},
};

View File

@ -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",

View File

@ -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。",