feat(stockout): 出库单转订单全链路(receiverInfo 落库、出库单默认快递、updateInfo、TRANSFERRED)

- toOrder:create_channel=STOCKOUT、库存锁转移、收货必填校验、同快递/兜底平台、转单后置 TRANSFERRED(禁止一键出库)

- stockout.create:解析 receiverInfo 13 字段落库,快递兜底改用出库单默认快递(stockout_default_express_code,默认 ZT 自提)

- 新增 storage.stockout.updateInfo:收货/地址/快递/平台修改,仅 CREATED/PENDING,收货缺失禁止提交

- 迁移:wms_order_stockout 新增 receiver_* 13 列、order_status 增 TRANSFERRED、source_platform 两列

- 附带:storeWarehouse.createUser、奇门取消订单配送表幂等、express_platform Uint64 打包、方法与变更文档同步
This commit is contained in:
liufumingren 2026-08-25 23:40:42 +08:00
parent c0331cd68f
commit b07d7bca33
16 changed files with 1775 additions and 93 deletions

File diff suppressed because one or more lines are too long

View File

@ -56,10 +56,10 @@ module.exports = app => {
comment: '来源类型',
},
order_status: {
type: ENUM('CREATING', 'CREATED', 'PENDING', 'COMPLETED', 'CANCELLED'),
type: ENUM('CREATING', 'CREATED', 'PENDING', 'COMPLETED', 'CANCELLED', 'TRANSFERRED'),
allowNull: false,
defaultValue: 'CREATED',
comment: '订单状态:CREATING=创建中, CREATED=已创建待审核, PENDING=已审核, COMPLETED=已完成, CANCELLED=已作废',
comment: '订单状态:CREATING=创建中, CREATED=已创建待审核, PENDING=已审核, COMPLETED=已完成, CANCELLED=已作废, TRANSFERRED=已转订单',
},
sync_status: {
type: ENUM('PENDING', 'SUCCESS', 'FAILED'),
@ -107,6 +107,81 @@ module.exports = app => {
allowNull: true,
comment: '备注',
},
receiver_company: {
type: STRING(200),
allowNull: true,
comment: '收件人公司名称(receiverInfo.company)',
},
receiver_name: {
type: STRING(50),
allowNull: true,
comment: '收件人姓名(receiverInfo.name)',
},
receiver_zip_code: {
type: STRING(50),
allowNull: true,
comment: '收件人邮编(receiverInfo.zipCode)',
},
receiver_tel: {
type: STRING(50),
allowNull: true,
comment: '收件人固定电话(receiverInfo.tel)',
},
receiver_mobile: {
type: STRING(50),
allowNull: true,
comment: '收件人移动电话(receiverInfo.mobile)',
},
receiver_email: {
type: STRING(50),
allowNull: true,
comment: '收件人电子邮箱(receiverInfo.email)',
},
receiver_country_code: {
type: STRING(50),
allowNull: true,
comment: '收件人国家二字码(receiverInfo.countryCode)',
},
receiver_province: {
type: STRING(50),
allowNull: true,
comment: '收件人省份(receiverInfo.province)',
},
receiver_city: {
type: STRING(50),
allowNull: true,
comment: '收件人城市(receiverInfo.city)',
},
receiver_area: {
type: STRING(50),
allowNull: true,
comment: '收件人区域(receiverInfo.area)',
},
receiver_town: {
type: STRING(50),
allowNull: true,
comment: '收件人村镇(receiverInfo.town)',
},
receiver_detail_address: {
type: STRING(200),
allowNull: true,
comment: '收件人详细地址(receiverInfo.detailAddress)',
},
receiver_id: {
type: STRING(50),
allowNull: true,
comment: '收件人证件号(receiverInfo.id)',
},
source_platform_code: {
type: STRING(50),
allowNull: true,
comment: '来源平台编码(转订单时优先使用,为空时兜底平台)',
},
source_platform_name: {
type: STRING(200),
allowNull: true,
comment: '来源平台名称快照',
},
express_code: {
type: STRING(50),
allowNull: true,
@ -252,6 +327,11 @@ module.exports = app => {
return this.order_status === 'CANCELLED';
};
/** 判断订单是否已转销售订单 */
OrderStockout.prototype.isTransferred = function() {
return this.order_status === 'TRANSFERRED';
};
/** 当前订单是否允许审核 */
OrderStockout.prototype.canConfirm = function() {
return [ 'CREATED', 'PENDING' ].includes(this.order_status);

View File

@ -119,6 +119,14 @@ module.exports = app => {
required: false,
description: '货主在当前仓下默认使用的快递编码',
}),
Object.freeze({
key: 'stockout_default_express_code',
name: '出库单默认快递',
type: 'list',
default: 'ZT',
required: false,
description: '货主在当前仓下出库单默认使用的快递编码,默认 ZT 自提',
}),
Object.freeze({
key: 'default_platform_code',
name: '默认平台',
@ -729,6 +737,10 @@ module.exports = app => {
value: normalizePolicyConfigOptionValue(item),
label: String(item.name || item.code || ''),
})),
stockout_default_express_code: expressRows.map(item => ({
value: normalizePolicyConfigOptionValue(item),
label: String(item.name || item.code || ''),
})),
default_platform_code: platformRows.map(item => ({
value: normalizePolicyConfigOptionValue(item),
label: String(item.name || item.code || ''),

View File

@ -179,10 +179,35 @@ class orderServer extends MainService {
});
if (!existingOrder) {
// current 表未命中时回退查询配送域表(dispatch):
// 订单已流转到配送表中且已取消,视为取消成功(幂等),直接返回
const DispatchModel = await ctx.model.OrderDeliveryFactory.getDispatchModel(info.warehouseId);
const dispatchOrder = await DispatchModel.findOne({
where: {
delivery_order_code: orderCode,
warehouse_id: info.warehouseId,
store_id: info.storeId,
},
transaction,
lock: transaction.LOCK.UPDATE,
});
if (dispatchOrder && String(dispatchOrder.status || '').trim() === 'cancel') {
await transaction.rollback();
return this.success('取消订单成功');
}
await transaction.rollback();
return this.fail('未找到对应的订单');
}
// 幂等处理:订单在配送表中且已取消,直接返回取消成功
const currentStatus = String(existingOrder.status || '').trim();
if (currentStatus === 'cancel') {
await transaction.rollback();
return this.success('取消订单成功');
}
const pickStatus = String(existingOrder.pick_status || 'none').trim();
const printStatus = String(existingOrder.print_status || 'none').trim();

View File

@ -40,6 +40,91 @@ class stockoutServer extends MainService {
const totalOrderLines = deliveryOrder.totalOrderLines || orderLine.length;
// 快递编码解析(简化口径,独立于订单兜底链):
// 1. 货主开启 enable_external_express_code 且传了 logisticsCode 时,按
// wms_express_setting 映射 → 系统快递列表 匹配;
// 2. 未传 / 未开启 / 匹配不到 → 使用出库单兜底快递编码(stockout_default_express_code,
// 默认 ZT 自提),不再回退订单默认快递;不走订单的快递策略漏斗(matchPolicy)。
let expressCode = null;
let expressName = null;
try {
const deliveryOrderService = ctx.service.systems.deliveryOrder;
const policyConfig = await deliveryOrderService.getStoreWarehousePolicyConfig(storeId, warehouseId);
const expressList = await ctx.service.systems.express.getExpressList();
const findExpress = code => {
const upperCode = String(code || '').trim().toUpperCase();
if (!upperCode || !Array.isArray(expressList)) {
return null;
}
return expressList.find(item => item
&& String(item.code || item.value || '').trim().toUpperCase() === upperCode) || null;
};
const externalCode = String(deliveryOrder.logisticsCode || '').trim();
const enableExternal = deliveryOrderService.normalizePolicyFlag(
policyConfig && policyConfig.enable_external_express_code
);
if (enableExternal && externalCode) {
// 1) wms_express_setting 外部编码映射 → 系统快递编码
const settingSnapshot = await deliveryOrderService.resolveExpressSettingSnapshot(externalCode, warehouseId);
if (settingSnapshot && settingSnapshot.expressCode) {
const sysCode = String(settingSnapshot.expressCode).trim();
const sysItem = findExpress(sysCode);
expressCode = sysCode;
expressName = sysItem
? String(sysItem.name || sysItem.label || sysCode).trim()
: String(settingSnapshot.name || sysCode).trim();
} else {
// 2) 系统快递列表直接匹配
const matched = findExpress(externalCode);
if (matched) {
expressCode = String(matched.code || matched.value || externalCode).trim();
expressName = String(matched.name || matched.label || expressCode).trim();
}
}
}
if (!expressCode) {
// 兜底:出库单兜底快递编码(货主配置,默认 ZT 自提),不回退订单默认快递
const fallbackCode = String(policyConfig && policyConfig.stockout_default_express_code || '').trim() || 'ZT';
const fallbackItem = findExpress(fallbackCode);
expressCode = fallbackItem
? String(fallbackItem.code || fallbackItem.value || fallbackCode).trim()
: fallbackCode;
expressName = fallbackItem
? String(fallbackItem.name || fallbackItem.label || fallbackCode).trim()
: fallbackCode;
}
} catch (err) {
ctx.logger.warn(`[stockout.create] 快递编码解析失败,保持为空: ${err.message}`);
}
// 收件人信息解析(receiverInfo 13 个标准字段落库,供转订单与确认回传使用)
const receiver = deliveryOrder.receiverInfo && typeof deliveryOrder.receiverInfo === 'object'
? deliveryOrder.receiverInfo
: {};
const receiverFields = {
receiver_company: receiver.company,
receiver_name: receiver.name,
receiver_zip_code: receiver.zipCode,
receiver_tel: receiver.tel,
receiver_mobile: receiver.mobile,
receiver_email: receiver.email,
receiver_country_code: receiver.countryCode,
receiver_province: receiver.province,
receiver_city: receiver.city,
receiver_area: receiver.area,
receiver_town: receiver.town,
receiver_detail_address: receiver.detailAddress,
receiver_id: receiver.id,
};
for (const key of Object.keys(receiverFields)) {
const rawValue = receiverFields[key];
receiverFields[key] = rawValue === undefined || rawValue === null
? null
: String(rawValue).trim() || null;
}
// 第一步:校验所有商品是否在 StockStore 中存在,并收集有效明细
const errors = [];
const items = [];
@ -114,6 +199,9 @@ class stockoutServer extends MainService {
? new Date(deliveryOrder.createTime)
: null,
remark: deliveryOrder.remark || null,
express_code: expressCode,
express_name: expressName,
...receiverFields,
warehouse_id: warehouseId,
store_id: storeId,
qimen_owner_code: items[0].ownerCode,

View File

@ -61,6 +61,7 @@ const CREATE_CHANNEL_LABELS = Object.freeze({
MANUAL: '手工单',
API: '接口',
QM: '奇门',
STOCKOUT: '出库转单',
});
const ORDER_TABLE_TYPE_ALIASES = Object.freeze({
current: 'current',

View File

@ -26,11 +26,12 @@ class StorageDeliveryService extends MainService {
}
/**
* 出库单跳转订单占位接口(兼容转发)。
* @return {Promise<Object>} 占位失败结果
* 出库单转订单(兼容转发)。
* @param {Object} data 请求体
* @return {Promise<Object>} 转订单结果
*/
async toOrder() {
return await this.ctx.service.systemMethods.storage.stockout.toOrder();
async toOrder(data = {}) {
return await this.ctx.service.systemMethods.storage.stockout.toOrder(data);
}
/**

View File

@ -103,11 +103,265 @@ class StorageStockoutService extends MainService {
}
/**
* 出库单转订单占位接口。
* @return {Promise<Object>} 统一失败包装响应
* 出库单转订单。
*
* 将非订单出库单(wms_order_stockout)转为正式销售订单:
* 1. 新订单 create_channel 固定为 STOCKOUT;
* 2. 释放出库单占用的库存锁定,转由新订单重新锁定;
* 3. 转单成功后原出库单置为 CANCELLED,并记录已转订单号(幂等)。
*
* 仅 CREATED / PENDING 状态的出库单允许转单;建单失败时自动补偿恢复出库单锁定。
*
* @param {Object} data 请求体
* @param {number} data.id 出库单ID(必填)
* @param {string} [data.delivery_order_code] 新订单号,不传自动生成(SK 前缀)
* @param {Object} [data.receiverInfo] 收件人信息(name/mobile/tel/province/city/area/town/detailAddress/zipCode)
* @return {Promise<Object>} 统一成功/失败包装响应
*/
async toOrder() {
return this.fail('接口暂未开放');
async toOrder(data = {}) {
const { ctx } = this;
const id = Number(data.id || 0);
if (!id) {
return this.fail('缺少出库单ID');
}
const warehouseId = Number(ctx.user && ctx.user.store_id) || 0;
if (warehouseId <= 0) {
return this.fail('缺少仓库上下文');
}
const order = await ctx.model.OrderStockout.findOne({
where: { id, warehouse_id: warehouseId, deleted_at: null },
});
if (!order) {
return this.fail('出库单不存在');
}
// 幂等:已转订单的出库单直接返回原订单信息
const currentExtendProps =
order.extend_props && typeof order.extend_props === 'object' && !Array.isArray(order.extend_props)
? order.extend_props
: {};
if (currentExtendProps.transferred_order_id) {
return this.success('出库单已转订单', {
id: order.id,
stockout_order_code: order.stockout_order_code,
order_id: currentExtendProps.transferred_order_id,
delivery_order_code: currentExtendProps.transferred_order_code || '',
});
}
if (![ 'CREATED', 'PENDING' ].includes(order.order_status)) {
return this.fail(`出库单当前状态(${order.order_status})不允许转订单`);
}
const items = await ctx.model.OrderStockoutItems.findAll({
where: { order_id: order.id },
order: [[ 'id', 'ASC' ]],
raw: true,
});
if (!items || items.length === 0) {
return this.fail('出库单没有明细,无法转订单');
}
// 收货信息:出库单已存的 receiver_* 字段为基础,接口传入的非空 receiverInfo 字段覆盖
const storedReceiverInfo = {
company: order.receiver_company || '',
name: order.receiver_name || '',
zipCode: order.receiver_zip_code || '',
tel: order.receiver_tel || '',
mobile: order.receiver_mobile || '',
email: order.receiver_email || '',
countryCode: order.receiver_country_code || '',
province: order.receiver_province || '',
city: order.receiver_city || '',
area: order.receiver_area || '',
town: order.receiver_town || '',
detailAddress: order.receiver_detail_address || '',
};
const passedReceiverInfo = data.receiverInfo && typeof data.receiverInfo === 'object'
? data.receiverInfo
: {};
const receiverInfo = { ...storedReceiverInfo };
for (const [ key, value ] of Object.entries(passedReceiverInfo)) {
if (value !== undefined && value !== null && String(value).trim() !== '') {
receiverInfo[key] = String(value).trim();
}
}
// 收货信息必填校验:name、(tel/mobile) 其一、省市区镇详细地址,缺失禁止转订单
const missingFields = [];
if (!String(receiverInfo.name || '').trim()) {
missingFields.push('name(收件人姓名)');
}
const receiverTel = String(receiverInfo.tel || '').trim();
const receiverMobile = String(receiverInfo.mobile || '').trim();
if (!receiverTel && !receiverMobile) {
missingFields.push('tel/mobile(固定电话或移动电话至少一项)');
}
const addressFields = [
[ 'province', '省' ],
[ 'city', '市' ],
[ 'area', '区' ],
[ 'town', '镇' ],
[ 'detailAddress', '详细地址' ],
];
for (const [ key, label ] of addressFields) {
if (!String(receiverInfo[key] || '').trim()) {
missingFields.push(`${key}(${label})`);
}
}
if (missingFields.length > 0) {
return this.fail(`收货信息缺失,不能转订单:缺少 ${missingFields.join('、')}`);
}
const stockStoreService = ctx.service.systems.stockStore;
const lockMeta = {
orderType: 'QM_STOCKOUT',
orderNo: order.stockout_order_code,
orderId: order.id,
};
// 第一步:释放出库单占用的库存锁定(新订单创建时会重新锁定)
const releaseTransaction = await ctx.model.transaction();
try {
for (const item of items) {
const qty = Number(item.plan_qty) || 0;
if (qty <= 0) continue;
const releaseResult = await stockStoreService.lockItemStorages(
item.stock_id,
-qty,
releaseTransaction,
null,
{ ...lockMeta, remark: '出库单转订单释放锁定' }
);
if (!releaseResult.success) {
throw new Error(`库存${item.stock_id}释放锁定失败: ${releaseResult.error}`);
}
}
await releaseTransaction.commit();
} catch (err) {
await releaseTransaction.rollback().catch(() => {});
ctx.logger.error(`[stockout.toOrder] 释放出库单锁定失败: ${err.message}`);
return this.fail(`转订单失败:${err.message}`);
}
// 第二步:创建订单(create_channel=STOCKOUT,内部重新锁定库存)
// 快递编码沿用出库单已解析的 express_code(系统快递编码),平台不传 sourcePlatformCode 走兜底平台
const deliveryOrderCode = String(data.delivery_order_code || '').trim()
|| `SK${Date.now()}${Math.floor(Math.random() * 9000) + 1000}`;
const orderLines = items.map((item, idx) => ({
itemCode: item.item_code || '',
itemId: Number(item.item_id) || 0,
itemName: item.item_name || '',
planQty: Number(item.plan_qty) || 0,
stockId: Number(item.stock_id) || 0,
inventoryType: item.inventory_type || '',
orderLineNo: String(item.order_line_no || idx + 1),
ownerCode: item.owner_code || '',
sourceOrderCode: order.stockout_order_code,
}));
const addOrderData = {
request: {
deliveryOrder: {
deliveryOrderCode,
orderType: order.order_type || 'QTCK',
createChannel: 'STOCKOUT',
logisticsCode: order.express_code || '',
sourcePlatformCode: order.source_platform_code || '',
receiverInfo,
remark: order.remark || '',
sourceOrderCode: order.stockout_order_code,
},
orderLines: { orderLine: orderLines },
},
};
const info = {
storeId: order.store_id,
warehouseId,
appKey: (ctx.user && ctx.user.app_key) || '',
};
let addOrderResult = null;
try {
addOrderResult = await ctx.service.systems.deliveryOrder.addOrder(addOrderData, info, 'STOCKOUT');
} catch (err) {
addOrderResult = { success: false, message: err.message, data: null };
}
const orderId = addOrderResult && addOrderResult.data && addOrderResult.data.orderId;
const isDuplicate = !!(addOrderResult && addOrderResult.success && addOrderResult.message === '订单已存在');
if (!addOrderResult || !addOrderResult.success || !orderId || isDuplicate) {
// 建单失败/订单号重复:补偿恢复出库单锁定
await this._restoreStockoutLocks(stockStoreService, items, lockMeta, ctx);
return this.fail(`转订单失败:${(addOrderResult && addOrderResult.message) || '订单创建失败'}`);
}
// 第三步:标记出库单已转订单(状态推进到 TRANSFERRED,该状态下禁止一键出库)
try {
await ctx.model.OrderStockout.update(
{
order_status: 'TRANSFERRED',
sync_message: `已转订单 ${deliveryOrderCode}`,
extend_props: {
...currentExtendProps,
transferred_order_id: orderId,
transferred_order_code: deliveryOrderCode,
transferred_at: new Date(),
},
updated_at: new Date(),
},
{ where: { id: order.id } }
);
} catch (updateErr) {
// 订单已创建成功,仅出库单标记失败:记录告警,不回滚订单
ctx.logger.error(`[stockout.toOrder] 标记出库单已转失败: ${updateErr.message}`);
}
return this.success('转订单成功', {
id: order.id,
stockout_order_code: order.stockout_order_code,
order_id: orderId,
delivery_order_code: deliveryOrderCode,
step: addOrderResult.data.step,
});
}
/**
* 转订单失败时恢复出库单库存锁定(补偿)。
* @param {Object} stockStoreService 库存服务
* @param {Array} items 出库单明细
* @param {Object} lockMeta 锁元信息
* @param {Object} ctx 请求上下文
* @return {Promise<void>} 无返回值
*/
async _restoreStockoutLocks(stockStoreService, items, lockMeta, ctx) {
const restoreTransaction = await ctx.model.transaction();
try {
for (const item of items) {
const qty = Number(item.plan_qty) || 0;
if (qty <= 0) continue;
const restoreResult = await stockStoreService.lockItemStorages(
item.stock_id,
qty,
restoreTransaction,
null,
{ ...lockMeta, remark: '出库单转订单失败恢复锁定' }
);
if (!restoreResult.success) {
throw new Error(`库存${item.stock_id}恢复锁定失败: ${restoreResult.error}`);
}
}
await restoreTransaction.commit();
} catch (err) {
await restoreTransaction.rollback().catch(() => {});
ctx.logger.error(`[stockout.toOrder] 恢复出库单锁定失败: ${err.message}`);
}
}
/**
@ -392,6 +646,153 @@ class StorageStockoutService extends MainService {
waybill_codes: order.waybill_codes,
});
}
/**
* 修改出库单信息。
*
* 可修改范围:收件人(name/tel/mobile 等)、地址(province/city/area/town/detailAddress 等)、
* 快递编码(express_code,自动解析 express_name)、来源平台(source_platform_code/name)。
* 未传入的字段不修改;快递编码与平台相关字段不传即保持原值。
*
* 限制:仅 CREATED / PENDING 状态允许修改;修改后收货信息不完整(name、(tel/mobile) 其一、
* 省市区镇详细地址缺任一)时禁止提交。
*
* @param {Object} data 请求体
* @param {number} data.id 出库单ID(必填)
* @param {string} [data.name] 收件人姓名
* @param {string} [data.tel] 固定电话
* @param {string} [data.mobile] 移动电话
* @param {string} [data.company] 公司名称
* @param {string} [data.email] 电子邮箱
* @param {string} [data.zipCode] 邮编
* @param {string} [data.countryCode] 国家二字码
* @param {string} [data.province] 省份
* @param {string} [data.city] 城市
* @param {string} [data.area] 区/县
* @param {string} [data.town] 镇/街道
* @param {string} [data.detailAddress] 详细地址
* @param {string} [data.express_code] 快递公司编码(自动解析 express_name)
* @param {string} [data.source_platform_code] 来源平台编码
* @param {string} [data.source_platform_name] 来源平台名称
* @return {Promise<Object>} 统一成功/失败包装响应
*/
async updateInfo(data = {}) {
const { ctx } = this;
const id = Number(data.id || 0);
if (!id) {
return this.fail('缺少出库单ID');
}
const warehouseId = Number(ctx.user && ctx.user.store_id) || 0;
if (warehouseId <= 0) {
return this.fail('缺少仓库上下文');
}
const order = await ctx.model.OrderStockout.findOne({
where: { id, warehouse_id: warehouseId, deleted_at: null },
});
if (!order) {
return this.fail('出库单不存在');
}
if (![ 'CREATED', 'PENDING' ].includes(order.order_status)) {
return this.fail(`出库单当前状态(${order.order_status})不允许修改`);
}
const updateData = { updated_at: new Date() };
// 收件人 / 地址字段:传入才更新,空串置 NULL
const receiverFieldMap = {
receiver_name: 'name',
receiver_tel: 'tel',
receiver_mobile: 'mobile',
receiver_company: 'company',
receiver_email: 'email',
receiver_zip_code: 'zipCode',
receiver_country_code: 'countryCode',
receiver_province: 'province',
receiver_city: 'city',
receiver_area: 'area',
receiver_town: 'town',
receiver_detail_address: 'detailAddress',
receiver_id: 'id',
};
for (const [ column, param ] of Object.entries(receiverFieldMap)) {
if (data[param] !== undefined) {
updateData[column] = data[param] === null
? null
: String(data[param]).trim() || null;
}
}
// 快递编码:传入才更新,并自动解析 express_name(与 updateExpress 同口径)
if (data.express_code !== undefined) {
const expressCode = String(data.express_code || '').trim();
if (expressCode) {
let expressName = '';
try {
const expressMap = await ctx.service.systems.setting.express.getSystemExpressMap();
const info = expressMap.get(expressCode.toUpperCase());
expressName = info ? info.name : '';
} catch (e) {
ctx.logger.warn('[updateInfo] 解析快递名称失败: ' + e.message);
}
updateData.express_code = expressCode;
updateData.express_name = expressName;
} else {
updateData.express_code = null;
updateData.express_name = null;
}
}
// 来源平台:传入才更新,空串置 NULL
if (data.source_platform_code !== undefined) {
updateData.source_platform_code = String(data.source_platform_code || '').trim() || null;
}
if (data.source_platform_name !== undefined) {
updateData.source_platform_name = String(data.source_platform_name || '').trim() || null;
}
// 修改后的收货信息完整性校验:name、(tel/mobile) 其一、省市区镇详细地址必填,缺失禁止提交
const mergedReceiver = {
name: updateData.receiver_name !== undefined ? updateData.receiver_name : order.receiver_name,
tel: updateData.receiver_tel !== undefined ? updateData.receiver_tel : order.receiver_tel,
mobile: updateData.receiver_mobile !== undefined ? updateData.receiver_mobile : order.receiver_mobile,
province: updateData.receiver_province !== undefined ? updateData.receiver_province : order.receiver_province,
city: updateData.receiver_city !== undefined ? updateData.receiver_city : order.receiver_city,
area: updateData.receiver_area !== undefined ? updateData.receiver_area : order.receiver_area,
town: updateData.receiver_town !== undefined ? updateData.receiver_town : order.receiver_town,
detailAddress: updateData.receiver_detail_address !== undefined ? updateData.receiver_detail_address : order.receiver_detail_address,
};
const missingFields = [];
if (!String(mergedReceiver.name || '').trim()) {
missingFields.push('name(收件人姓名)');
}
if (!String(mergedReceiver.tel || '').trim() && !String(mergedReceiver.mobile || '').trim()) {
missingFields.push('tel/mobile(固定电话或移动电话至少一项)');
}
const addressFields = [
[ 'province', '省' ],
[ 'city', '市' ],
[ 'area', '区' ],
[ 'town', '镇' ],
[ 'detailAddress', '详细地址' ],
];
for (const [ key, label ] of addressFields) {
if (!String(mergedReceiver[key] || '').trim()) {
missingFields.push(`${key}(${label})`);
}
}
if (missingFields.length > 0) {
return this.fail(`收货信息缺失,禁止提交:缺少 ${missingFields.join('、')}`);
}
await ctx.model.OrderStockout.update(updateData, { where: { id: order.id } });
const updated = await ctx.model.OrderStockout.findByPk(order.id, { raw: true });
return this.success('修改成功', updated);
}
}
module.exports = StorageStockoutService;

View File

@ -29,9 +29,9 @@ class StoreWarehouseStoreService extends MainService {
constructor(ctx) {
super(ctx);
const _noNeedLogin = '';
const _noNeedRight = 'list,sign,confirmSign,unbind,rename,openAccount,getPolicyConfig,getPolicyConfigFields,savePolicyConfig,listApiConfig,saveApiConfig,deleteQimenConfig,queryPrintQuantityLogs,queryStorePrintQuantityLogs,exportStorePrintQuantityLogs,exportStorePrintQuantityLogsTaskProgress,adjustPrintQuantity';
const _noNeedRight = 'list,sign,confirmSign,unbind,rename,openAccount,createUser,getPolicyConfig,getPolicyConfigFields,savePolicyConfig,listApiConfig,saveApiConfig,deleteQimenConfig,queryPrintQuantityLogs,queryStorePrintQuantityLogs,exportStorePrintQuantityLogs,exportStorePrintQuantityLogsTaskProgress,adjustPrintQuantity';
const _noNeedLog = '*';
const _noNeedAuth = 'list,sign,confirmSign,unbind,rename,openAccount,getPolicyConfig,getPolicyConfigFields,savePolicyConfig,listApiConfig,saveApiConfig,deleteQimenConfig,queryPrintQuantityLogs,queryStorePrintQuantityLogs,exportPrintQuantityLogs,exportStorePrintQuantityLogs,exportStorePrintQuantityLogsTaskProgress,adjustPrintQuantity';
const _noNeedAuth = 'list,sign,confirmSign,unbind,rename,openAccount,createUser,getPolicyConfig,getPolicyConfigFields,savePolicyConfig,listApiConfig,saveApiConfig,deleteQimenConfig,queryPrintQuantityLogs,queryStorePrintQuantityLogs,exportStorePrintQuantityLogs,exportStorePrintQuantityLogsTaskProgress,adjustPrintQuantity';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
@ -421,6 +421,43 @@ class StoreWarehouseStoreService extends MainService {
}
}
/**
* 为货主创建用户:按用户名查找账号,不存在则注册并随机生成密码返回,
* 两种情况统一完成货主工号绑定与货主管理员角色(id=5)授权。
*
* @param {Object} data 请求数据。
* @param {string} data.username 用户名(必填)。
* @param {number|string} data.store_id 货主 ID(必填)。
* @return {Promise<Object>} 统一响应结果。
*/
async createUser(data = {}) {
const targetService = this.service && this.service.systems && this.service.systems.storeWarehouse;
if (!targetService || typeof targetService.createUser !== 'function') {
return this.fail('创建货主用户失败', {
code: 500,
});
}
try {
const requestData = normalizeStoreWarehousePayload(data);
const {
username,
store_id,
} = requestData;
const result = await targetService.createUser({
username,
store_id,
});
return this.success('ok', result);
} catch (error) {
return this.fail(error.message || '创建货主用户失败', {
code: Number(error.code) || 500,
});
}
}
/**
* 提交面单余额变更日志导出任务。
* 入参条件与 queryPrintQuantityLogs 的 where 语义一致,异步执行,立即返回 task_id。

View File

@ -93,6 +93,52 @@ function isValidCainiaoTemplateUrl(templateUrl) {
const DEFAULT_CAINIAO_TEMPLATE_URL = 'http://cloudprint.cainiao.com/cloudprint/template/getStandardTemplate.json?template_id=288948';
/**
* 将仓库ID/订单ID/业务键三段标识打包为 64 位无符号整数(Uint64)。
*
* 位宽分配("不够的补位"由左移自动补 0 完成):
* - warehouse_id:高 24 bit(hex 6 位,0x000000 ~ 0xFFFFFF)
* - order_id :中 32 bit(hex 8 位,0x00000000 ~ 0xFFFFFFFF)
* - business_key:低 8 bit (hex 2 位,0x00 ~ 0xFF)
* 合计 64 bit,拼出的 hex 固定 16 位(不足高位补 0)。
*
* 例:f425c_3948e_1 → hex 补位 0f425c0003948e01 → 1099542414161645057
*
* 纯函数(幂等):不含时间/随机因素,相同入参必然输出相同 Uint64,可安全重试。
*
* @param {number|string} warehouseId 仓库ID。
* @param {number|string} orderId 订单ID。
* @param {number|string} businessKey 业务键(1=主单号,>1=子单号)。
* @return {string} Uint64 的十进制字符串(超过 JS 安全整数 2^53,必须用字符串形式传输/序列化)。
*/
/* eslint-disable no-bitwise -- Uint64 位打包/拆解必须使用位运算 */
function toUint64(warehouseId, orderId, businessKey) {
const wh = BigInt(Number(warehouseId) || 0);
const oid = BigInt(Number(orderId) || 0);
const bk = BigInt(Number(businessKey) || 0);
if (wh < 0n || wh > 0xFFFFFFn) throw new Error(`toUint64: warehouse_id 超出 24 位范围: ${warehouseId}`);
if (oid < 0n || oid > 0xFFFFFFFFn) throw new Error(`toUint64: order_id 超出 32 位范围: ${orderId}`);
if (bk < 0n || bk > 0xFFn) throw new Error(`toUint64: business_key 超出 8 位范围: ${businessKey}`);
return ((wh << 40n) | (oid << 8n) | bk).toString();
}
/**
* 将 Uint64 反向拆解为仓库ID/订单ID/业务键(toUint64 的逆运算)。
*
* @param {string|number|bigint} value Uint64 值(十进制字符串/数字/BigInt 均可)。
* @return {{ warehouseId: number, orderId: number, businessKey: number }} 拆解结果。
*/
function fromUint64(value) {
const v = BigInt(value);
if (v < 0n || v > 0xFFFFFFFFFFFFFFFFn) throw new Error(`fromUint64: 超出 64 位范围: ${value}`);
return {
warehouseId: Number(v >> 40n),
orderId: Number((v >> 8n) & 0xFFFFFFFFn),
businessKey: Number(v & 0xFFn),
};
}
/* eslint-enable no-bitwise */
/**
* 快递平台服务类。
*
@ -717,7 +763,9 @@ class ExpressPlatformService extends MainService {
logistictype: expressListItem[listByWarehousePlatformCode.platform_code] || '',
providercode: expressListItem[listByWarehousePlatformCode.platform_code] || order.logistics_code || '',
numpackage: order.package_count || '1',
businesstype: listByWarehousePlatformCode.product_type,
Businesstype: listByWarehousePlatformCode.product_type,
Expresstype: listByWarehousePlatformCode.product_type,
ProductType: listByWarehousePlatformCode.product_type || '',
transtype: '0',
transtypecode: '1',
mainsubpaymode: '1',
@ -735,7 +783,6 @@ class ExpressPlatformService extends MainService {
height: Number(order.height) || 0,
volume: Number(order.volume) || 0,
ispickup: listByWarehousePlatformCode.ispickup ?? 0,
ProductType: listByWarehousePlatformCode.product_type || '',
Sipshopid: listByWarehousePlatformCode.platform_shop_id || '',
oaid: order.oaid || '',
cpcode: expressListItem[listByWarehousePlatformCode.platform_code] || '',
@ -894,10 +941,11 @@ class ExpressPlatformService extends MainService {
}
}
if (matchedPlatform.platid === 672) {
if (!order.source_order_codes) {
/* if (!order.source_order_codes) {
throw new Error('订单数据错误,缺失平台订单号');
}
playload.object_Id = order.source_order_codes.split(',')[0];
*/
playload.object_Id = toUint64(order.warehouse_id, order.id, order_tmp.business_key);
if (!order.extend_props.ewaybill_order_code) {
throw new Error('订单数据错误,参数不全缺失extend_props.ewaybill_order_code,请复制次信息给ERP方反馈');
}
@ -2389,7 +2437,7 @@ class ExpressPlatformService extends MainService {
object_id: `${order_tmp.order_delivery.warehouse_id}_${order_tmp.order_delivery.id}_${order_tmp.business_key}`,
order_info: {
order_channels_type: 'PDD',
trade_order_list: order_tmp.order_delivery && order_tmp.order_delivery.source_order_codes ? order_tmp.order_delivery.source_order_codes.split(',') : [ order_tmp.order_delivery && order_tmp.order_delivery.delivery_order_code || '' ],
trade_order_list: [`${order_tmp.order_delivery.warehouse_id}_${order_tmp.order_delivery.id}_${order_tmp.business_key}`],
},
package_info: {
items: (order_tmp.order_delivery && order_tmp.order_delivery.orderItems || []).map(item => ({
@ -2397,6 +2445,7 @@ class ExpressPlatformService extends MainService {
count: item.plan_qty,
})) || [],
id: `${order_tmp.order_delivery.warehouse_id}_${order_tmp.order_delivery.id}_${order_tmp.business_key}`,
total_packages_count: order_tmp.business_key || 1,
},
recipient: {
address: {
@ -2443,6 +2492,9 @@ class ExpressPlatformService extends MainService {
},
};
console.log('拼多多平台接口构建的请求参数', JSON.stringify(pddPayload, null, 2));
await this.app.setCacheAsync('Pddquery', JSON.stringify(pddPayload), 3600);
// 这里写一个调用pdd_client的入参示例
//
//
@ -2491,6 +2543,8 @@ class ExpressPlatformService extends MainService {
data: builtRequest.requestBody,
});
await this.app.setCacheAsync('Pddresult', JSON.stringify(response), 3600);
const responseData = response && Object.prototype.hasOwnProperty.call(response, 'data')
? response.data
: response;
@ -2791,4 +2845,8 @@ class ExpressPlatformService extends MainService {
}
}
// 静态挂载 Uint64 工具:供回包解析(SPH object_Id 反解)等场景复用
ExpressPlatformService.toUint64 = toUint64;
ExpressPlatformService.fromUint64 = fromUint64;
module.exports = ExpressPlatformService;

View File

@ -3276,6 +3276,167 @@ class SettingStoreWarehouseService extends Service {
throw error;
}
}
/**
* 为货主创建用户:按用户名查询账号,不存在则注册账号并返回随机生成的密码,
* 两种情况统一完成货主工号绑定与货主管理员角色(wms_role.id=5)授权,幂等执行。
* 货主审核中(wms_store.status=2)时自动转为启用(1)。
*
* @param {Object} [data={}] 请求参数。
* @param {string} data.username 用户名(必填,3-50 位字母、数字或下划线)。
* @param {number|string} data.store_id 货主 ID(必填)。
* @return {Promise<Object>} 响应对象,data 包含 account_id、username、store_id、created;
* 仅新建账号时返回 password 明文密码。
* @throws {Error} 参数缺失或格式非法时抛出 400,货主不存在时抛出 404,
* 货主管理员角色未初始化时抛出 500。
*/
async createUser(data = {}) {
const { ctx } = this;
const {
username: rawUsername,
store_id: rawStoreId,
} = data;
// 1. 校验必填参数
const username = this.normalizeText(rawUsername, 'username', 50);
if (!username) {
throw this.createError('username 参数不能为空', 400);
}
if (!/^[a-zA-Z0-9_]{3,50}$/.test(username)) {
throw this.createError('用户名格式不合法,需为 3-50 位字母、数字或下划线', 400);
}
const storeId = this.toPositiveNumber(rawStoreId, 'store_id');
// 2. 校验货主存在(同时取 status 用于后续审核中状态修正)
const store = await ctx.model.Store.findOne({
where: { id: storeId },
attributes: [ 'id', 'status' ],
});
if (!store) {
throw this.createError('货主不存在', 404);
}
// 3. 查询账号是否存在
const existingAccount = await ctx.model.Account.findOne({
where: { username },
attributes: [ 'id', 'username' ],
});
// 4. 随机生成密码(仅新建账号时使用)
const randomPassword = crypto.randomBytes(8).toString('base64').replace(/[+/=]/g, '')
.slice(0, 12);
// 5. 事务内执行账号创建与授权绑定
const transaction = await ctx.model.transaction();
try {
// 5.0 货主审核中(status=2)时自动转为启用(1),store 实例在事务外查询,更新时显式传入事务
if (Number(store.status) === 2) {
await store.update({ status: 1 }, { transaction });
}
let accountId = null;
let created = false;
if (existingAccount) {
// 账号已存在:不创建、不返回密码
accountId = Number(existingAccount.id);
created = false;
} else {
// 账号不存在:复用注册服务,email/real_name 使用占位兜底
const registerResult = await ctx.service.systems.auth.user.register({
username,
password: randomPassword,
email: `${username}@placeholder.local`,
real_name: username,
}, transaction);
accountId = Number(registerResult.userId);
created = true;
}
// 6. 货主工号绑定(幂等:已存在但 status=0 时恢复为 1)
const [ employee ] = await ctx.model.AccountStoreEmployee.findOrCreate({
where: {
account_id: accountId,
store_id: storeId,
},
defaults: {
account_id: accountId,
store_id: storeId,
status: 1,
real_name: username,
},
transaction,
});
if (Number(employee.status) !== 1) {
await employee.update({
status: 1,
}, { transaction });
}
// 7. 确认货主管理员角色(wms_role.id=5)已初始化
const storeAdminRole = await ctx.model.Role.findByPk(5, { transaction });
if (!storeAdminRole) {
throw this.createError('货主管理员角色(id=5)未初始化', 500);
}
// 8. 授予货主管理员角色(幂等:findOrCreate)
await ctx.model.EmployeeRole.findOrCreate({
where: {
employee_id: employee.id,
role_id: 5,
},
defaults: {
employee_id: employee.id,
role_id: 5,
},
transaction,
});
await transaction.commit();
// 9. 记录操作日志(不影响业务主流程)
try {
await ctx.service.systems.operationLog.createOperationLog({
businessType: 'store',
businessId: storeId,
operationCode: 'STORE_CREATE_USER',
operator: {
id: ctx.user?.employees_id || ctx.user?.id,
name: ctx.user?.employees_name || '',
},
extras: {
storeId: Number(storeId),
accountId: Number(accountId),
created,
},
beforeChanges: null,
});
} catch (logErr) {
ctx.logger.warn('[storeWarehouse.createUser] 写入操作日志失败,不影响业务', logErr);
}
// 10. 组装响应:仅新建账号时返回明文密码
const resultData = {
account_id: accountId,
username,
store_id: storeId,
created,
};
if (created) {
resultData.password = randomPassword;
}
return {
code: 200,
data: resultData,
};
} catch (error) {
await transaction.rollback();
throw error;
}
}
}
module.exports = SettingStoreWarehouseService;

View File

@ -0,0 +1,66 @@
'use strict';
const TABLE = 'wms_order_stockout';
/**
* 为出库单主表添加收件人信息字段(对应奇门 stockout.create 报文 receiverInfo 节点)。
*
* 字段与奇门 receiverInfo 一一对应,列名统一加 receiver_ 前缀避免与订单表口径混淆。
*/
module.exports = {
up: async (queryInterface, Sequelize) => {
const columns = await queryInterface.describeTable(TABLE);
const receiverColumns = [
{ name: 'receiver_company', type: Sequelize.STRING(200), comment: '收件人公司名称(receiverInfo.company)' },
{ name: 'receiver_name', type: Sequelize.STRING(50), comment: '收件人姓名(receiverInfo.name)' },
{ name: 'receiver_zip_code', type: Sequelize.STRING(50), comment: '收件人邮编(receiverInfo.zipCode)' },
{ name: 'receiver_tel', type: Sequelize.STRING(50), comment: '收件人固定电话(receiverInfo.tel)' },
{ name: 'receiver_mobile', type: Sequelize.STRING(50), comment: '收件人移动电话(receiverInfo.mobile)' },
{ name: 'receiver_email', type: Sequelize.STRING(50), comment: '收件人电子邮箱(receiverInfo.email)' },
{ name: 'receiver_country_code', type: Sequelize.STRING(50), comment: '收件人国家二字码(receiverInfo.countryCode)' },
{ name: 'receiver_province', type: Sequelize.STRING(50), comment: '收件人省份(receiverInfo.province)' },
{ name: 'receiver_city', type: Sequelize.STRING(50), comment: '收件人城市(receiverInfo.city)' },
{ name: 'receiver_area', type: Sequelize.STRING(50), comment: '收件人区域(receiverInfo.area)' },
{ name: 'receiver_town', type: Sequelize.STRING(50), comment: '收件人村镇(receiverInfo.town)' },
{ name: 'receiver_detail_address', type: Sequelize.STRING(200), comment: '收件人详细地址(receiverInfo.detailAddress)' },
{ name: 'receiver_id', type: Sequelize.STRING(50), comment: '收件人证件号(receiverInfo.id)' },
];
for (const item of receiverColumns) {
if (!columns[item.name]) {
await queryInterface.addColumn(TABLE, item.name, {
type: item.type,
allowNull: true,
comment: item.comment,
});
}
}
},
down: async queryInterface => {
const columns = await queryInterface.describeTable(TABLE);
const receiverColumnNames = [
'receiver_company',
'receiver_name',
'receiver_zip_code',
'receiver_tel',
'receiver_mobile',
'receiver_email',
'receiver_country_code',
'receiver_province',
'receiver_city',
'receiver_area',
'receiver_town',
'receiver_detail_address',
'receiver_id',
];
for (const name of receiverColumnNames) {
if (columns[name]) {
await queryInterface.removeColumn(TABLE, name);
}
}
},
};

View File

@ -0,0 +1,68 @@
'use strict';
const TABLE = 'wms_order_stockout';
/**
* 出库单补充迁移:
* 1. order_status ENUM 追加 TRANSFERRED(已转订单),转订单成功后使用该状态;
* 2. 新增平台字段 source_platform_code / source_platform_name(修改接口"平台相关"与转订单回传使用)。
*/
module.exports = {
up: async (queryInterface, Sequelize) => {
const columns = await queryInterface.describeTable(TABLE);
// 1. order_status ENUM 追加 TRANSFERRED(保持默认值与原注释)
const statusType = String(columns.order_status && columns.order_status.type || '').toUpperCase();
if (statusType && !statusType.includes("'TRANSFERRED'")) {
await queryInterface.sequelize.query(
'ALTER TABLE `wms_order_stockout` MODIFY COLUMN `order_status` '
+ 'ENUM(\'CREATING\',\'CREATED\',\'PENDING\',\'COMPLETED\',\'CANCELLED\',\'TRANSFERRED\') '
+ 'NOT NULL DEFAULT \'CREATED\' '
+ 'COMMENT \'订单状态:CREATING=创建中, CREATED=已创建待审核, PENDING=已审核, COMPLETED=已完成, CANCELLED=已作废, TRANSFERRED=已转订单\''
);
}
// 2. 平台字段
if (!columns.source_platform_code) {
await queryInterface.addColumn(TABLE, 'source_platform_code', {
type: Sequelize.STRING(50),
allowNull: true,
comment: '来源平台编码(转订单时优先使用,为空时兜底平台)',
});
}
if (!columns.source_platform_name) {
await queryInterface.addColumn(TABLE, 'source_platform_name', {
type: Sequelize.STRING(200),
allowNull: true,
comment: '来源平台名称快照',
});
}
},
down: async queryInterface => {
const columns = await queryInterface.describeTable(TABLE);
// 已转订单的行先回退为已作废,再收缩 ENUM
const statusType = String(columns.order_status && columns.order_status.type || '').toUpperCase();
if (statusType && statusType.includes("'TRANSFERRED'")) {
await queryInterface.sequelize.query(
'UPDATE `wms_order_stockout` SET `order_status` = \'CANCELLED\' WHERE `order_status` = \'TRANSFERRED\''
);
await queryInterface.sequelize.query(
'ALTER TABLE `wms_order_stockout` MODIFY COLUMN `order_status` '
+ 'ENUM(\'CREATING\',\'CREATED\',\'PENDING\',\'COMPLETED\',\'CANCELLED\') '
+ 'NOT NULL DEFAULT \'CREATED\' '
+ 'COMMENT \'订单状态:CREATING=创建中, CREATED=已创建待审核, PENDING=已审核, COMPLETED=已完成, CANCELLED=已作废\''
);
}
if (columns.source_platform_code) {
await queryInterface.removeColumn(TABLE, 'source_platform_code');
}
if (columns.source_platform_name) {
await queryInterface.removeColumn(TABLE, 'source_platform_name');
}
},
};

View File

@ -1,4 +1,50 @@
[
{
"version": "2026.08.25-stockout-create-express-fallback-zt",
"date": "2026-08-25",
"summary": "stockout.create 快递兜底口径调整:兜底仅使用出库单兜底快递编码(policy_config.stockout_default_express_code,默认 ZT 自提),不再回退订单默认快递(default_express_code/全局 STO);快递解析改为独立实现,不再复用订单侧 resolveExpressSnapshot 兜底链。",
"methods": [
"stockout.create"
],
"notes": [
"qimenMethods/stockout.js create 快递解析重写:开启 enable_external_express_code 且传 logisticsCode 时按 wms_express_setting 映射 → 系统快递列表匹配;未传/未开启/匹配不到时取 stockout_default_express_code(为空则 'ZT'),从系统快递列表解析名称,仍不存在则编码=名称=ZT",
"app/model/store_warehouse.js POLICY_CONFIG_FIELDS:新增 stockout_default_express_code(名称:出库单默认快递,type list,default 'ZT'),getPolicyConfigFieldListWithOptions 同步注入快递选项,与 default_express_code 表现一致",
"注意:ZT 需在系统快递列表中维护(自提),否则出库单 express_code/express_name 直接落库 ZT"
],
"type": "updated",
"module": "stockout"
},
{
"version": "2026.08.25-stockout-create-receiver-info",
"date": "2026-08-25",
"summary": "stockout.create 解析 receiverInfo 落库(13 个标准字段)并接入出库单兜底快递编码:快递解析在未传 logisticsCode 或匹配不到时,优先使用货主合约配置 stockout_default_express_code(出库单兜底快递),为空再回退 default_express_code/全局 STO。",
"methods": [
"stockout.create"
],
"notes": [
"qimenMethods/stockout.js create 新增 receiverInfo 解析:company/name/zipCode/tel/mobile/email/countryCode/province/city/area/town/detailAddress/id 共 13 字段落库 receiver_* 列(空值转 NULL)",
"快递解析改为传入覆盖默认快递后的 expressPolicyConfig(default_express_code = stockout_default_express_code || default_express_code)复用 resolveExpressSnapshot 匹配链路",
"app/model/store_warehouse.js POLICY_CONFIG_FIELDS 新增 stockout_default_express_code(type list,默认空,描述:出库单未传快递编码或匹配不到时使用的兜底快递编码)",
"receiverInfo 中的 idType/idNumber 扩展字段暂不落库(数据库未建列)"
],
"type": "updated",
"module": "stockout"
},
{
"version": "2026.08.25-stockout-create-express-resolve",
"date": "2026-08-25",
"summary": "stockout.create 新增 logisticsCode 快递编码解析(简化口径):货主开启 enable_external_express_code 时按 wms_express_setting → 系统快递列表匹配,匹配不到(含未开启)一律兜底默认快递,不走订单快递策略漏斗(matchPolicy)。解析结果落库 express_code/express_name。",
"methods": [
"stockout.create"
],
"notes": [
"qimenMethods/stockout.js create 在事务外解析 deliveryOrder.logisticsCode:调 deliveryOrder.getStoreWarehousePolicyConfig 读策略开关 + deliveryOrder.resolveExpressSnapshot(编码映射+兜底,不含策略漏斗),取 sysLogisticsCode/sysLogisticsName 落库 express_code/express_name",
"解析失败仅告警不阻断建单(express_code/express_name 保持 NULL),confirm 前仍可走 storage.stockout.updateExpress 手工补填",
"注意:出库单 express_code 存系统快递编码,stockout.confirm 出站回传 logisticsCode 时直接使用该值"
],
"type": "updated",
"module": "stockout"
},
{
"version": "2026.07.01-qimen-01",
"date": "2026-07-01",

View File

@ -1,4 +1,87 @@
[
{
"version": "2026.08.25-stockout-updateInfo-transferred",
"date": "2026-08-25",
"type": "added",
"summary": "新增 storage.stockout.updateInfo 修改出库单信息接口,并引入 TRANSFERRED 状态:转订单成功后出库单置为 TRANSFERRED(已转订单),该状态下禁止一键出库。",
"methods": [
"storage.stockout.updateInfo",
"storage.stockout.toOrder"
],
"notes": [
"storage.stockout.updateInfo:修改范围限收件人(name/tel/mobile/company/email)、地址(province/city/area/town/detailAddress/zipCode/countryCode)、快递编码(express_code,自动解析 express_name)、来源平台(source_platform_code/name),未传入不修改;仅 CREATED/PENDING 状态允许修改(400);修改后收货信息不完整(name、(tel/mobile) 其一、省市区镇详细地址)禁止提交并列出缺失字段",
"数据库迁移 20260825180000-add-transferred-status-and-platform-to-wms-order-stockout.js:order_status ENUM 追加 TRANSFERRED + 新增 source_platform_code(50)/source_platform_name(200) 列,开发库已执行并核验",
"app/model/order_stockout.js:ENUM 补 TRANSFERRED、新增两平台字段、新增 isTransferred() 辅助方法",
"storage.stockout.toOrder:转单成功后 order_status 置 TRANSFERRED(原 CANCELLED);deliveryOrder.sourcePlatformCode 优先用出库单已存平台,为空走兜底平台;confirm(一键出库)经 canConfirm 拒绝 TRANSFERRED 状态",
"同步更新 methods/system.json:新增 updateInfo 接口文档,更新 toOrder 描述与状态说明"
],
"module": "storage.stockout"
},
{
"version": "2026.08.25-stockout-toOrder-receiver-validate",
"date": "2026-08-25",
"type": "fixed",
"summary": "storage.stockout.toOrder 增加收货信息必填校验与同快递建单:name、(tel/mobile) 至少一项、省市区镇详细地址缺失时拒绝转单并提示缺失字段;收货信息优先接口传入,未传回填出库单已存的 receiver_* 字段;新订单快递编码沿用出库单 express_code(相同快递),平台不传 sourcePlatformCode 走兜底平台。",
"methods": [
"storage.stockout.toOrder"
],
"notes": [
"app/service/systemMethods/storage/stockout.js toOrder:释放锁前先合并收货信息(storedReceiverInfo 从出库单 receiver_company/name/zip_code/tel/mobile/email/country_code/province/city/area/town/detail_address 回填,接口 receiverInfo 非空字段覆盖)并逐项校验,缺项返回 fail 提示缺失字段列表",
"建单参数:logisticsCode = 出库单 express_code(create 时已解析的系统快递编码),不传 sourcePlatformCode(resolvePlatformSnapshot 自动使用合约兜底平台)",
"同步更新 methods/system.json 中 storage.stockout.toOrder 的 description 与 receiverInfo 参数说明"
],
"module": "storage.stockout"
},
{
"version": "2026.08.25-stockout-receiver-info-db",
"date": "2026-08-25",
"type": "added",
"summary": "wms_order_stockout 表新增 13 个收件人字段(receiver_* 前缀),对应奇门 stockout.create 报文 receiverInfo 节点(company/name/zipCode/tel/mobile/email/countryCode/province/city/area/town/detailAddress/id),为出库单解析收件人信息与转订单回填做准备。",
"methods": [
"storage.stockout.toOrder",
"stockout.create"
],
"notes": [
"database/migrations/20260825170000-add-receiver-info-to-wms-order-stockout.js 新增 13 列:receiver_company(200)/receiver_name(50)/receiver_zip_code(50)/receiver_tel(50)/receiver_mobile(50)/receiver_email(50)/receiver_country_code(50)/receiver_province(50)/receiver_city(50)/receiver_area(50)/receiver_town(50)/receiver_detail_address(200)/receiver_id(50),均允许 NULL;up/down 均带 describeTable 幂等保护",
"app/model/order_stockout.js 同步新增 13 个字段定义(remark 与 express_code 之间)",
"开发库已执行迁移并核验 SHOW COLUMNS 全部落库;生产库需在发布时按 db-migration-envs 规范执行"
],
"module": "storage.stockout"
},
{
"version": "2026.08.25-storage.stockout.toOrder",
"date": "2026-08-25",
"type": "added",
"summary": "storage.stockout.toOrder 从占位接口落地为真实实现:将非订单出库单(wms_order_stockout)转为正式销售订单,新订单 create_channel 固定为 STOCKOUT;转单时释放出库单库存锁定(QM_STOCKOUT)并转由新订单重新锁定,成功后原出库单置为 CANCELLED 并写入 extend_props.transferred_order_id(幂等,重复调用直接返回已转订单信息)。",
"methods": [
"storage.stockout.toOrder"
],
"notes": [
"app/service/systemMethods/storage/stockout.js toOrder 实现:入参 id(出库单ID,必填)、delivery_order_code(可选,不传自动生成 SK 前缀单号)、receiverInfo(可选收件人信息);校验出库单存在且 order_status 为 CREATED/PENDING(否则 400),extend_props.transferred_order_id 存在时幂等返回已转订单",
"锁转移:事务内逐明细 lockItemStorages(-plan_qty, orderType=QM_STOCKOUT) 释放出库单锁 → 调 deliveryOrder.addOrder(data, info, 'STOCKOUT') 建单并重新锁库存 → 建单失败/订单号重复时 _restoreStockoutLocks 补偿恢复锁定;建单成功后更新出库单 order_status=CANCELLED 并记录 transferred_order_id/transferred_order_code/transferred_at",
"新订单明细手工单风格传 stockId(wms_stock_warehouse.id),sourceOrderCode 写入出库单号便于追溯;create_channel=STOCKOUT 不触发 addOrder 的 API/QM 异步流程,也不会被自动同步任务推送",
"app/service/systemMethods/storage/delivery.js toOrder 兼容转发改为透传 data 参数",
"app/service/systemMethods/order/base.js CREATE_CHANNEL_LABELS 新增 STOCKOUT: '出库转单',订单工作台渠道列正确显示中文标签",
"同步更新 methods/system.json 中 storage.stockout.toOrder 接口文档"
],
"module": "storage.stockout"
},
{
"version": "2026.08.25-storeWarehouse.store.createUser",
"date": "2026-08-25",
"type": "added",
"summary": "新增 storeWarehouse.store.createUser:为货主创建用户。按用户名查询平台账号:账号不存在则自动注册并随机生成 12 位密码返回;两种情况统一完成货主工号绑定并授予货主管理员角色(wms_role.id=5)。幂等:重复调用不会重复创建账号或绑定。",
"methods": [
"storeWarehouse.store.createUser"
],
"notes": [
"app/service/systems/store_warehouse.js 新增 createUser:校验 username(必填 + 3-50 位字母数字下划线,400)与 store_id(必填正整数,400)→ 货主存在校验(404)→ 按用户名查询账号(不存在则复用 auth.user.register 注册并随机生成 12 位密码)→ 事务内 AccountStoreEmployee.findOrCreate 绑定货主工号(已存在且 status!=1 时恢复为 1)→ 校验货主管理员角色 wms_role.id=5 已初始化(缺失抛 500)→ EmployeeRole.findOrCreate 授予角色(幂等)",
"app/service/systemMethods/storeWarehouse/store.js 新增 createUser 包装方法;构造器 _noNeedRight/_noNeedAuth 白名单加入 createUser(isNeedLogin=true 需登录、isNeedAuth=false)",
"响应 data:account_id、username、store_id、created(是否本次新建账号;false 表示账号已存在仅完成授权)、password(仅 created=true 时返回 12 位随机明文密码)",
"同步更新 methods/system.json 中 storeWarehouse.store.createUser 接口文档"
],
"module": "storeWarehouse"
},
{
"version": "2026.08.25-returnUnpack.forceRecord",
"date": "2026-08-25",

View File

@ -1,8 +1,8 @@
{
"module": "system",
"description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内",
"version": "0.3.35",
"updatedAt": "2026-08-22",
"version": "0.3.36",
"updatedAt": "2026-08-25",
"headers": [
{
"name": "platform",
@ -23226,8 +23226,8 @@
},
{
"method": "storage.stockout.toOrder",
"name": "出库单转订单(占位)",
"description": "占位接口,暂未开放。当前仅保留方法名用于后续扩展,逻辑暂不能使用。参数 id / delivery_order_code 暂未启用。",
"name": "出库单转订单",
"description": "将非订单出库单转为正式销售订单:新订单 create_channel 固定为 STOCKOUT;转单时释放出库单占用的库存锁定并转由新订单重新锁定;转单成功后原出库单置为 TRANSFERRED(已转订单,该状态禁止一键出库)并记录已转订单号(幂等,重复调用返回原订单信息)。仅 CREATED / PENDING 状态允许转单;建单失败自动补偿恢复出库单锁定。收货信息必填:name、(tel/mobile) 至少一项、省市区镇详细地址,缺失返回错误禁止转单;收货信息优先接口传入,未传回填出库单已存的收件人字段;快递编码沿用出库单已解析的 express_code,平台优先使用出库单已存 source_platform_code,为空使用兜底平台。",
"isNeedAuth": false,
"isNeedLogin": true,
"isNeedRight": false,
@ -23243,30 +23243,65 @@
{
"name": "id",
"type": "number",
"required": false,
"required": true,
"source": "body",
"description": "预留参数,暂未启用;当前仅保留字段名用于后续扩展。"
"description": "出库单ID(必填)"
},
{
"name": "delivery_order_code",
"type": "string",
"required": false,
"source": "body",
"description": "预留参数,暂未启用;当前仅保留字段名用于后续扩展。"
"description": "新订单号,不传自动生成(SK 前缀)"
},
{
"name": "receiverInfo",
"type": "object",
"required": false,
"source": "body",
"description": "收件人信息(name/mobile/tel/province/city/area/town/detailAddress/zipCode 等),不传时回填出库单已存的收件人字段;name、(tel/mobile) 其一、省市区镇详细地址必填,缺失则报错不能转订单"
}
],
"response": [
{
"name": "_note",
"name": "id",
"type": "number",
"required": true,
"description": "出库单ID"
},
{
"name": "stockout_order_code",
"type": "string",
"required": true,
"description": "出库单号"
},
{
"name": "order_id",
"type": "number",
"required": true,
"description": "新订单ID"
},
{
"name": "delivery_order_code",
"type": "string",
"required": true,
"description": "新订单号"
},
{
"name": "step",
"type": "number",
"required": false,
"description": "占位接口,当前无有效业务响应"
"description": "订单步骤(0=待审核,1=待处理)"
}
],
"errors": [
{
"code": "405",
"description": "占位接口,暂未开放"
"code": "400",
"description": "出库单不存在 / 状态不允许转单 / 无明细 / 订单创建失败"
},
{
"code": "500",
"description": "释放或恢复库存锁定失败"
}
]
},
@ -23497,6 +23532,154 @@
"description": "express_codes 必须是数组或 null"
}
]
},
{
"method": "storage.stockout.updateInfo",
"name": "修改出库单信息",
"description": "修改出库单信息:收件人(name/tel/mobile/company/email 等)、地址(province/city/area/town/detailAddress/zipCode/countryCode)、快递编码(express_code,自动解析 express_name)、来源平台(source_platform_code/source_platform_name)。未传入的字段不修改;修改后收货信息不完整(name、(tel/mobile) 其一、省市区镇详细地址缺任一)禁止提交。仅 CREATED/PENDING 状态允许修改。",
"isNeedAuth": true,
"isNeedLogin": true,
"isNeedRight": false,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "出库单ID(必填)"
},
{
"name": "name",
"type": "string",
"required": false,
"source": "body",
"description": "收件人姓名"
},
{
"name": "tel",
"type": "string",
"required": false,
"source": "body",
"description": "收件人固定电话"
},
{
"name": "mobile",
"type": "string",
"required": false,
"source": "body",
"description": "收件人移动电话"
},
{
"name": "company",
"type": "string",
"required": false,
"source": "body",
"description": "收件人公司名称"
},
{
"name": "email",
"type": "string",
"required": false,
"source": "body",
"description": "收件人电子邮箱"
},
{
"name": "zipCode",
"type": "string",
"required": false,
"source": "body",
"description": "邮编"
},
{
"name": "countryCode",
"type": "string",
"required": false,
"source": "body",
"description": "国家二字码"
},
{
"name": "province",
"type": "string",
"required": false,
"source": "body",
"description": "省份"
},
{
"name": "city",
"type": "string",
"required": false,
"source": "body",
"description": "城市"
},
{
"name": "area",
"type": "string",
"required": false,
"source": "body",
"description": "区/县"
},
{
"name": "town",
"type": "string",
"required": false,
"source": "body",
"description": "镇/街道"
},
{
"name": "detailAddress",
"type": "string",
"required": false,
"source": "body",
"description": "详细地址"
},
{
"name": "express_code",
"type": "string",
"required": false,
"source": "body",
"description": "快递公司编码,传入后自动解析 express_name"
},
{
"name": "source_platform_code",
"type": "string",
"required": false,
"source": "body",
"description": "来源平台编码"
},
{
"name": "source_platform_name",
"type": "string",
"required": false,
"source": "body",
"description": "来源平台名称"
}
],
"response": [
{
"name": "data",
"type": "object",
"required": true,
"description": "更新后的出库单完整记录(wms_order_stockout 表字段,含 receiver_*、express_*、source_platform_* 等)"
}
],
"errors": [
{
"code": "400",
"description": "缺少出库单ID / 出库单不存在 / 状态不允许修改"
},
{
"code": "400",
"description": "收货信息缺失,禁止提交(列出缺失字段)"
}
]
}
]
},
@ -26763,6 +26946,98 @@
"message": "签约关系不存在"
}
]
},
{
"method": "storeWarehouse.store.createUser",
"description": "为货主创建用户:按用户名查询平台账号,账号不存在则自动注册并随机生成 12 位密码返回;两种情况统一完成货主工号绑定并授予货主管理员角色(wms_role.id=5)。幂等:重复调用不会重复创建账号或绑定",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token(当前登录主体操作)"
}
],
"params": [
{
"name": "username",
"type": "string",
"required": true,
"source": "body",
"description": "用户名,3-50 位字母、数字或下划线,全局唯一"
},
{
"name": "store_id",
"type": "number",
"required": true,
"source": "body",
"description": "货主 ID"
}
],
"response": [
{
"name": "account_id",
"type": "number",
"required": true,
"description": "账号 ID"
},
{
"name": "username",
"type": "string",
"required": true,
"description": "用户名"
},
{
"name": "store_id",
"type": "number",
"required": true,
"description": "货主 ID"
},
{
"name": "created",
"type": "boolean",
"required": true,
"description": "是否本次新建账号;false 表示账号已存在仅完成授权"
},
{
"name": "password",
"type": "string",
"required": false,
"description": "仅 created=true 时返回:随机生成的初始明文密码(12 位,随机大小写字母/数字)"
}
],
"errors": [
{
"code": 400,
"message": "username 参数不能为空"
},
{
"code": 400,
"message": "用户名格式不合法,需为 3-50 位字母、数字或下划线"
},
{
"code": 400,
"message": "store_id 参数不能为空"
},
{
"code": 401,
"message": "未提供有效的认证令牌"
},
{
"code": 404,
"message": "货主不存在"
},
{
"code": 500,
"message": "货主管理员角色(id=5)未初始化"
},
{
"code": 500,
"message": "服务内部错误"
}
]
}
]
},