This commit is contained in:
liufumingren 2026-07-03 16:56:39 +08:00
parent 962e06787f
commit 5d7964132e
14 changed files with 391 additions and 847 deletions

View File

@ -1,18 +0,0 @@
'use strict';
const { loadDeployConfig, quoteForBash, runSsh } = require('./script/deploy-lib.cjs');
const config = loadDeployConfig('production');
const script = [
'echo \"=== v2 完整 Model 配置(行70-100)===\"',
'sed -n \"70,100p\" ' + quoteForBash(config.deployRoot + '/v2/app/model/inbound_direct_log.js'),
'echo \"\"',
'echo \"=== v2 完整 Model 配置(行95-120)===\"',
'sed -n \"95,120p\" ' + quoteForBash(config.deployRoot + '/v2/app/model/inbound_direct_log.js'),
'echo \"\"',
'echo \"=== current.md 指向 ===\"',
'cat ' + quoteForBash(config.deployRoot + '/current.md'),
'echo \"\"',
'echo \"=== nginx upstream 指向 ===\"',
'cat ' + quoteForBash(config.deployRoot + '/nginx-upstream.conf'),
].join('\n');
console.log(runSsh(config, script, { stdio: 'pipe' }));

View File

@ -1053,9 +1053,9 @@ class indexService extends MainService {
constructor(ctx) {
super(ctx);
const _noNeedLogin = 'getI18nMessage,putI18nCollect,test,getCainiaoStfTemplates,polyapiAuthorizeUrl';
const _noNeedRight = 'loginToIm,getI18nMessage,putI18nCollect,fastWhereTree,loadStores,getImages,getCOSUploadConfig,uploadSuccessNotify,getMessageDetail,searchSpace,listInterfaceTypes,getLocationTypeList,getQimenAppList,getExpressList,getExpressProductTypeList,getPlatformList,getPrintPlatformList,getPlatformOauthLink,listenPlatformOauthBind,recognizeLicensePlate,getCainiaoStfTemplates,getPrintPlatformTemplateList,polyapiAuthorizeUrl';
const _noNeedRight = 'loginToIm,getI18nMessage,putI18nCollect,fastWhereTree,loadStores,getImages,getCOSUploadConfig,uploadSuccessNotify,getMessageDetail,searchSpace,listInterfaceTypes,getLocationTypeList,getQimenAppList,getExpressList,getExpressProductTypeList,getPlatformList,getPrintPlatformList,getPlatformOauthLink,listenPlatformOauthBind,recognizeLicensePlate,getCainiaoStfTemplates,getPrintPlatformTemplateList,polyapiAuthorizeUrl,toOrder';
const _noNeedLog = '*';
const _noNeedAuth = 'loginToIm,getI18nMessage,putI18nCollect,fastWhereTree,loadStores,getImages,getMessageDetail,searchSpace,listInterfaceTypes,getLocationTypeList,getQimenAppList,getExpressList,getExpressProductTypeList,getPlatformList,getPrintPlatformList,getPlatformOauthLink,listenPlatformOauthBind,recognizeLicensePlate,test,getCainiaoStfTemplates,getPrintPlatformTemplateList,polyapiAuthorizeUrl';
const _noNeedAuth = 'loginToIm,getI18nMessage,putI18nCollect,fastWhereTree,loadStores,getImages,getMessageDetail,searchSpace,listInterfaceTypes,getLocationTypeList,getQimenAppList,getExpressList,getExpressProductTypeList,getPlatformList,getPrintPlatformList,getPlatformOauthLink,listenPlatformOauthBind,recognizeLicensePlate,test,getCainiaoStfTemplates,getPrintPlatformTemplateList,polyapiAuthorizeUrl,toOrder';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
async fastWhereTree(data) {
@ -3314,5 +3314,19 @@ class indexService extends MainService {
code: 200,
});
}
/**
* 根据运单号快速查询订单 ID 及其所属波次信息。
*
* @param {Object} data 请求参数。
* @param {string} data.waybill_code 运单号。
* @return {Promise<Object>} 统一成功包装响应,包含 order_id 和 waves 数组。
*/
async toOrder(data = {}) {
const { service } = this;
const { waybill_code: waybillCode } = data;
const result = await service.systems.waybill.toOrder({ waybill_code: waybillCode });
return this.success('查询成功', result);
}
}
module.exports = indexService;

View File

@ -2834,6 +2834,7 @@ class PendingOrderService extends OrderBaseService {
detailAddress,
zipCode: String(requestData.zip_code || '').trim(),
},
seller_message: String(requestData.remark || '').trim(),
},
orderLines: {
orderLine: orderLineItems,

View File

@ -1218,7 +1218,7 @@ class RecheckOrderService extends OrderBaseService {
continue;
}
resultMap.set(hash, {
id: row.id != null ? Number(row.id) : null,
id: row.package_material_id,
code: String(row.package_material_code || '').trim() || null,
name: String(row.package_material_name || '').trim() || null,
spec: String(row.package_material_spec || '').trim() || null,

View File

@ -1,35 +0,0 @@
'use strict';
const MainService = require('../../main');
/**
* 系统方法层:quick.waybill(运单号快速查询接口包装层)。
* 主要职责:统一包装系统方法接口,处理权限、日志等公共逻辑,调用底层 service 实现业务功能。
*/
class QuickWaybillMethodService extends MainService {
constructor(ctx) {
super(ctx);
const _noNeedLogin = '';
const _noNeedRight = 'toOrder';
const _noNeedLog = '';
const _noNeedAuth = 'toOrder';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
/**
* 根据运单号快速查询订单 ID。
* 查询 wms_order_express 表中 status=1 的有效记录,返回对应的 order_id。
*
* @param {Object} data 请求参数。
* @param {string} data.waybill_code 运单号。
* @return {Promise<Object>} 统一成功包装响应,包含 order_id。
*/
async toOrder(data = {}) {
const { service } = this;
const { waybill_code: waybillCode } = data;
const result = await service.systems.quick.waybill.toOrder({ waybill_code: waybillCode });
return this.success('查询成功', result);
}
}
module.exports = QuickWaybillMethodService;

View File

@ -9,9 +9,9 @@ class entryService extends MainService {
constructor(ctx) {
super(ctx);
const _noNeedLogin = '';
const _noNeedRight = 'list,get,cancel,getPrintData,getDirectInboundItems,addDirectInboundItem,commitDirectInbound,removeDirectInboundItem,quickInbound,receivingCompare,queryEntryLogs,getReceivingDetailsForBind,reviewEntry,containerList';
const _noNeedRight = 'list,get,cancel,getPrintData,getDirectInboundItems,addItem,commit,removeItem,quickInbound,receivingCompare,queryEntryLogs,getReceivingDetailsForBind,reviewEntry,containerList';
const _noNeedLog = 'list,get,getPrintData,reviewEntry,containerList';
const _noNeedAuth = 'list,get,cancel,getPrintData,getDirectInboundItems,addDirectInboundItem,commitDirectInbound,removeDirectInboundItem,bindReceiving,quickInbound,receivingCompare,unbindReceiving,queryEntryLogs,getReceivingDetailsForBind,reviewEntry,containerList';
const _noNeedAuth = 'list,get,cancel,getPrintData,getDirectInboundItems,addItem,commit,removeItem,bindReceiving,quickInbound,receivingCompare,unbindReceiving,queryEntryLogs,getReceivingDetailsForBind,reviewEntry,containerList';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
@ -73,7 +73,7 @@ class entryService extends MainService {
* @param {Array} [data.items] 商品列表(批量模式)
* @return {Promise<Object>} 统一 success 包装
*/
async addDirectInboundItem(data = {}) {
async addItem(data = {}) {
const { service } = this;
const result = await service.systems.inboundDirectLog.addItem(data);
return this.success('ok', result);
@ -85,7 +85,7 @@ class entryService extends MainService {
* @param {number} data.entry_order_id 入库单 ID
* @return {Promise<Object>} 统一 success 包装
*/
async commitDirectInbound(data = {}) {
async commit(data = {}) {
const { service } = this;
const { entry_order_id } = data || {};
const result = await service.systems.inboundDirectLog.commit(entry_order_id);
@ -98,7 +98,7 @@ class entryService extends MainService {
* @param {number} data.id 入库记录ID
* @return {Promise<Object>} 统一 success 包装
*/
async removeDirectInboundItem(data = {}) {
async removeItem(data = {}) {
const { service } = this;
const result = await service.systems.inboundDirectLog.removeItem(data);
return this.success('ok', result);

View File

@ -287,23 +287,66 @@ class OrderExpressService extends Service {
);
}
// 查询订单所属波次
// 先查运单表校验运单是否存在
const orderExpressModel = this.ctx.model && this.ctx.model.OrderExpress;
if (!orderExpressModel || typeof orderExpressModel.findOne !== 'function') {
throw this.createBusinessError('运单模型未初始化', 500);
}
const expressRow = await orderExpressModel.findOne({
where: {
order_id: normalizedOrderId,
delete_at: null,
},
attributes: [ 'id', 'order_id', 'waybill_code', 'business_key' ],
raw: true,
});
if (!expressRow) {
throw this.createBusinessError('运单号不存在', 404);
}
// 依次查询多个订单表获取波次信息:current → history → dispatch
const orderDeliveryFactory = this.ctx.model && this.ctx.model.OrderDeliveryFactory;
if (!orderDeliveryFactory || typeof orderDeliveryFactory.getCurrentModel !== 'function') {
throw this.createBusinessError('订单模型未初始化', 500);
}
const orderDeliveryModel = await orderDeliveryFactory.getCurrentModel(warehouseId);
const orderRow = await orderDeliveryModel.findOne({
where: { id: normalizedOrderId, warehouse_id: warehouseId },
attributes: [ 'id', 'wave_id', 'wave_no' ],
raw: true,
});
const orderTableOrders = [
{ label: 'current', getModel: () => orderDeliveryFactory.getCurrentModel(warehouseId) },
{ label: 'history', getModel: () => orderDeliveryFactory.getHistoryModel(warehouseId) },
{ label: 'dispatch', getModel: () => orderDeliveryFactory.getDispatchModel(warehouseId) },
];
// 订单不存在 → 兼容前端传入 wave_id 的场景,尝试按波次查询
let orderRow = null;
let orderDeliveryModel = null;
for (const entry of orderTableOrders) {
try {
const model = await entry.getModel();
if (!model || typeof model.findOne !== 'function') {
continue;
}
const row = await model.findOne({
where: { id: normalizedOrderId, warehouse_id: warehouseId },
attributes: [ 'id', 'wave_id', 'wave_no' ],
raw: true,
});
if (row) {
orderRow = row;
orderDeliveryModel = model;
break;
}
} catch (_err) {
// 该表可能不存在,继续尝试下一张表
continue;
}
}
// 所有表都找不到 → 兼容前端传入 wave_id 的场景,尝试按波次查询
if (!orderRow) {
const fallbackModel = await orderDeliveryFactory.getCurrentModel(warehouseId);
return await this._tryWaveCompatibility(
normalizedOrderId, normalizedWaybillCode, normalizedWeight, warehouseId, orderDeliveryModel
normalizedOrderId, normalizedWaybillCode, normalizedWeight, warehouseId, fallbackModel
);
}
@ -385,18 +428,41 @@ class OrderExpressService extends Service {
const orderId = Number(expressRow.order_id || 0);
// 查询订单所属波次
// 依次查询多个订单表获取波次信息:current → history → dispatch
const orderDeliveryFactory = this.ctx.model && this.ctx.model.OrderDeliveryFactory;
if (!orderDeliveryFactory || typeof orderDeliveryFactory.getCurrentModel !== 'function') {
throw this.createBusinessError('订单模型未初始化', 500);
}
const orderDeliveryModel = await orderDeliveryFactory.getCurrentModel(warehouseId);
const orderRow = await orderDeliveryModel.findOne({
where: { id: orderId, warehouse_id: warehouseId },
attributes: [ 'id', 'wave_id', 'wave_no' ],
raw: true,
});
const orderTableOrders = [
{ label: 'current', getModel: () => orderDeliveryFactory.getCurrentModel(warehouseId) },
{ label: 'history', getModel: () => orderDeliveryFactory.getHistoryModel(warehouseId) },
{ label: 'dispatch', getModel: () => orderDeliveryFactory.getDispatchModel(warehouseId) },
];
let orderRow = null;
let orderDeliveryModel = null;
for (const entry of orderTableOrders) {
try {
const model = await entry.getModel();
if (!model || typeof model.findOne !== 'function') {
continue;
}
const row = await model.findOne({
where: { id: orderId, warehouse_id: warehouseId },
attributes: [ 'id', 'wave_id', 'wave_no' ],
raw: true,
});
if (row) {
orderRow = row;
orderDeliveryModel = model;
break;
}
} catch (_err) {
// 该表可能不存在,继续尝试下一张表
continue;
}
}
if (!orderRow) {
throw this.createBusinessError('运单号对应的订单不存在', 404);

View File

@ -1,42 +0,0 @@
'use strict';
const MainService = require('../../main');
/**
* 业务逻辑层:quick.waybill(运单号快速查询)。
*/
class QuickWaybillService extends MainService {
/**
* 根据运单号查询有效订单ID。
* 仅查询 wms_order_express 表中 status=1 的记录。
*
* @param {Object} params 查询参数。
* @param {string} params.waybill_code 运单号,不可为空。
* @return {Promise<Object>} 包含 order_id 的对象。
* @throws {Error} 当 waybill_code 为空或未找到匹配记录时抛出业务错误。
*/
async toOrder({ waybill_code: waybillCode }) {
const { ctx } = this;
if (!waybillCode || !String(waybillCode).trim()) {
this.throwError('运单号不能为空');
}
const record = await ctx.model.OrderExpress.findOne({
where: {
waybill_code: String(waybillCode).trim(),
status: 1,
},
attributes: [ 'order_id' ],
raw: true,
});
if (!record) {
this.throwError('未找到该运单号对应的订单');
}
return { order_id: record.order_id };
}
}
module.exports = QuickWaybillService;

View File

@ -992,7 +992,7 @@ class EntryService extends Service {
* @param {Array} [data.items] 商品列表(批量模式)
* @return {Promise<Object>} code/data/message 结构
*/
async addDirectInboundItem(data = {}) {
async addItem(data = {}) {
const { ctx } = this;
return await ctx.service.systems.inboundDirectLog.addItem(data);
}
@ -1002,7 +1002,7 @@ class EntryService extends Service {
* @param {string} entryOrderCode 入库单号
* @return {Promise<Object>} code/data/message 结构
*/
async commitDirectInbound(entryOrderCode) {
async commit(entryOrderCode) {
const { ctx } = this;
return await ctx.service.systems.inboundDirectLog.commit(entryOrderCode);
}
@ -1013,7 +1013,7 @@ class EntryService extends Service {
* @param {number} data.id 入库记录ID
* @return {Promise<Object>} code/data/message 结构
*/
async removeDirectInboundItem(data = {}) {
async removeItem(data = {}) {
const { ctx } = this;
return await ctx.service.systems.inboundDirectLog.removeItem(data);
}

View File

@ -0,0 +1,131 @@
'use strict';
const MainService = require('../main');
/**
* 业务逻辑层:waybill(运单号快速查询)。
*/
class WaybillService extends MainService {
/**
* 根据运单号查询有效订单ID,并返回该订单所属波次下所有订单ID列表。
*
* 查询流程:
* 1. 通过运单号查询 wms_order_express 表获取 order_id 和 warehouse_id。
* 2. 通过 order_id 遍历多表(current/history/dispatch)获取 wave_id 和 wave_no。
* 3. 若有有效波次(wave_id > 0),遍历多表查询该波次下所有订单的 ID 列表。
*
* @param {Object} params 查询参数。
* @param {string} params.waybill_code 运单号,不可为空。
* @return {Promise<Object>} 包含 order_id 和 waves 数组的对象。
* @throws {Error} 当 waybill_code 为空或未找到匹配记录时抛出业务错误。
*/
async toOrder({ waybill_code: waybillCode }) {
const { ctx } = this;
if (!waybillCode || !String(waybillCode).trim()) {
this.throwError('运单号不能为空');
}
const record = await ctx.model.OrderExpress.findOne({
where: {
waybill_code: String(waybillCode).trim(),
status: 1,
},
attributes: [ 'order_id', 'warehouse_id' ],
raw: true,
});
if (!record) {
this.throwError('未找到该运单号对应的订单');
}
const { order_id: orderId, warehouse_id: expressWarehouseId } = record;
// 获取 warehouse_id:优先从 ctx.user.store_id,回退到运单记录中的 warehouse_id
const warehouseId =
(ctx.user && ctx.user.store_id) ? ctx.user.store_id : expressWarehouseId;
// 构建多表遍历查询队列:current → history → dispatch
const orderDeliveryFactory =
ctx.model && ctx.model.OrderDeliveryFactory;
const tableOrders = [
{
label: 'current',
getModel: () => orderDeliveryFactory.getCurrentModel(warehouseId),
},
{
label: 'history',
getModel: () => orderDeliveryFactory.getHistoryModel(warehouseId),
},
{
label: 'dispatch',
getModel: () => orderDeliveryFactory.getDispatchModel(warehouseId),
},
];
// 遍历多表查询订单的 wave_id 和 wave_no
let orderRow = null;
for (const entry of tableOrders) {
try {
const model = await entry.getModel();
if (!model || typeof model.findOne !== 'function') {
continue;
}
const row = await model.findOne({
where: { id: orderId, warehouse_id: warehouseId },
attributes: [ 'id', 'wave_id', 'wave_no' ],
raw: true,
});
if (row) {
orderRow = row;
break;
}
} catch (_err) {
continue;
}
}
// 无订单记录或 wave_id 无效,返回空 waves
if (!orderRow || !orderRow.wave_id || Number(orderRow.wave_id) <= 0) {
return { order_id: orderId, waves: [] };
}
const { wave_id: waveId, wave_no: waveNo } = orderRow;
// 遍历多表查询该波次下所有订单的 ID 列表
const orderIds = [];
for (const entry of tableOrders) {
try {
const model = await entry.getModel();
if (!model || typeof model.findAll !== 'function') {
continue;
}
const rows = await model.findAll({
where: { wave_id: waveId, warehouse_id: warehouseId },
attributes: [ 'id' ],
raw: true,
});
for (const row of rows) {
if (!orderIds.includes(row.id)) {
orderIds.push(row.id);
}
}
} catch (_err) {
continue;
}
}
return {
order_id: orderId,
waves: [
{
wave_id: waveId,
wave_no: waveNo,
order_ids: orderIds,
},
],
};
}
}
module.exports = WaybillService;

View File

@ -1,4 +1,20 @@
[
{
"version": "2026.07.03-system-01",
"date": "2026-07-03",
"type": "updated",
"summary": "将 quick.waybill.toOrder 迁移为 index.toOrder 并移入基础模块,新增 waves 返回字段",
"methods": [
"quick.waybill.toOrder",
"index.toOrder"
],
"notes": [
"移除快捷操作(quick)模块分组,原 quick.waybill.toOrder 方法从 methods/system.json 删除。",
"在基础模块(index)新增 index.toOrder 方法:入参仍为 waybill_code,响应从单一 order_id 扩展为 order_id + waves 结构。",
"waves 为数组,每项含 wave_id(波次ID)、wave_no(波次号)、order_ids(波次下所有订单ID列表),无波次时为空数组。",
"查询路径:运单号 → wms_order_express(status=1)→ order_id + warehouse_id → 遍历 current/history/dispatch 表获取波次信息 → 再遍历多表获取同波次所有订单ID。"
]
},
{
"date": "2026-06-24",
"type": "addition",
@ -4138,18 +4154,18 @@
{
"version": "2026.06.23-system-13",
"date": "2026-06-23",
"summary": "新增 storage.entry.* 下 4 个 DirectInbound 方法:getDirectInboundItems、addDirectInboundItem、commitDirectInbound、removeDirectInboundItem,原 storage.directInbound.* 方法保留向后兼容并标记 deprecated",
"summary": "新增 storage.entry.* 下 4 个 DirectInbound 方法:getDirectInboundItems、addItem、commit、removeItem,原 storage.directInbound.* 方法保留向后兼容并标记 deprecated",
"methods": [
"storage.entry.getDirectInboundItems",
"storage.entry.addDirectInboundItem",
"storage.entry.commitDirectInbound",
"storage.entry.removeDirectInboundItem"
"storage.entry.addItem",
"storage.entry.commit",
"storage.entry.removeItem"
],
"notes": [
"storage.entry.getDirectInboundItems:获取入库单的导入/PDA 入库信息,参数与响应格式同原 storage.directInbound.getItems",
"storage.entry.addDirectInboundItem:按商品增量添加导入/PDA 入库记录(支持单条和批量),参数与响应格式同原 storage.directInbound.addItem",
"storage.entry.commitDirectInbound:提交确认完成导入/PDA 入库,按实收数量写入库存并异步回传奇门/API,参数与响应格式同原 storage.directInbound.commit",
"storage.entry.removeDirectInboundItem:移除一条导入/PDA 入库记录,参数与响应格式同原 storage.directInbound.removeItem",
"storage.entry.addItem:按商品增量添加导入/PDA 入库记录(支持单条和批量),参数与响应格式同原 storage.directInbound.addItem",
"storage.entry.commit:提交确认完成导入/PDA 入库,按实收数量写入库存并异步回传奇门/API,参数与响应格式同原 storage.directInbound.commit",
"storage.entry.removeItem:移除一条导入/PDA 入库记录,参数与响应格式同原 storage.directInbound.removeItem",
"底层 inbound_direct_log.js 实现不变,仅入口从 storage.directInbound 模块迁入 storage.entry 模块"
],
"type": "added"
@ -4166,9 +4182,9 @@
],
"notes": [
"storage.directInbound.getItems → 替代方法 storage.entry.getDirectInboundItems",
"storage.directInbound.addItem → 替代方法 storage.entry.addDirectInboundItem",
"storage.directInbound.commit → 替代方法 storage.entry.commitDirectInbound",
"storage.directInbound.removeItem → 替代方法 storage.entry.removeDirectInboundItem",
"storage.directInbound.addItem → 替代方法 storage.entry.addItem",
"storage.directInbound.commit → 替代方法 storage.entry.commit",
"storage.directInbound.removeItem → 替代方法 storage.entry.removeItem",
"旧方法保留向后兼容,参数与响应格式不变,仅入口模块变更"
],
"type": "deprecated"
@ -4176,13 +4192,13 @@
{
"version": "2026.06.23-system-15",
"date": "2026-06-23",
"summary": "storage.inventory.matchPutaway 标记 deprecated,替代方案为 storage.entry.commitDirectInbound",
"summary": "storage.inventory.matchPutaway 标记 deprecated,替代方案为 storage.entry.commit",
"methods": [
"storage.inventory.matchPutaway"
],
"notes": [
"storage.inventory.matchPutaway 已弃用,请迁移至 storage.entry.commitDirectInbound",
"commitDirectInbound 提供导入/PDA 入库完成确认功能,按实收数量写入库存并异步回传"
"storage.inventory.matchPutaway 已弃用,请迁移至 storage.entry.commit",
"commit 提供导入/PDA 入库完成确认功能,按实收数量写入库存并异步回传"
],
"type": "deprecated"
},
@ -4198,7 +4214,7 @@
"notes": [
"storage.entry.bindReceivingDetails:已从代码中删除,明细级绑定收货单功能下线。入库单与收货单关系改为 wms_entry_order_receiving 主表级关联。",
"storage.entry.unbindReceivingDetails:已从代码中删除,明细级解绑功能下线。",
"storage.inventory.matchPutaway:已从代码中删除,匹配入库功能下线。替代方案为 storage.entry.commitDirectInbound。",
"storage.inventory.matchPutaway:已从代码中删除,匹配入库功能下线。替代方案为 storage.entry.commit。",
"storage.inventory.quickPutaway:之前已标记 [已删除],本次确认条目保留(与 matchPutaway 同一 group,保留作为历史参考)。",
"storage.entry.create / addDetail / deleteDetail / detailChange:systems 层方法已删除,但从未在 system.json 中暴露为 API method,无需文档变更。"
],
@ -4518,9 +4534,9 @@
{
"version": "2026.06.30-system-02",
"date": "2026-06-30",
"summary": "storage.entry.addDirectInboundItem 入参变更:entry_order_code → entry_order_id(number);quantity 改为可选(传入 receiving_detail_id 时自动计算);新增 receiving_detail_id/allocated_quantity 参数支持 PDA 上架收货明细绑定模式;space_id 绑定模式下必填",
"summary": "storage.entry.addItem 入参变更:entry_order_code → entry_order_id(number);quantity 改为可选(传入 receiving_detail_id 时自动计算);新增 receiving_detail_id/allocated_quantity 参数支持 PDA 上架收货明细绑定模式;space_id 绑定模式下必填",
"methods": [
"storage.entry.addDirectInboundItem"
"storage.entry.addItem"
],
"notes": [
"入参 entry_order_code(string) → entry_order_id(number),与底层 inboundDirectLog.addItem 实现对齐",
@ -4538,9 +4554,9 @@
{
"version": "2026.06.30-system-03",
"date": "2026-06-30",
"summary": "storage.entry.commitDirectInbound 入参变更:entry_order_code → entry_order_id(number),与底层 inboundDirectLog.commit 实现对齐",
"summary": "storage.entry.commit 入参变更:entry_order_code → entry_order_id(number),与底层 inboundDirectLog.commit 实现对齐",
"methods": [
"storage.entry.commitDirectInbound"
"storage.entry.commit"
],
"notes": [
"入参 entry_order_code(string) → entry_order_id(number),与底层 inboundDirectLog.commit(entryOrderId) 实现对齐",
@ -4558,7 +4574,7 @@
],
"notes": [
"入参 entry_order_code(string) → entry_order_id(number),与底层 inboundDirectLog.commit(entryOrderId) 实现对齐",
"该方法已标记 deprecated,推荐使用 storage.entry.commitDirectInbound"
"该方法已标记 deprecated,推荐使用 storage.entry.commit"
],
"type": "updated"
},
@ -4707,13 +4723,35 @@
{
"version": "2026.07.03-system-03",
"date": "2026-07-03",
"summary": "binding 表弃用文档同步:commitDirectInbound 描述中 EntryReceivingBinding 更新为 InboundDirectLog",
"summary": "binding 表弃用文档同步:commit 描述中 EntryReceivingBinding 更新为 InboundDirectLog",
"methods": [
"storage.entry.commitDirectInbound"
"storage.entry.commit"
],
"notes": [
"commitDirectInbound description 中将 pending 状态的 EntryReceivingBinding 更新为 pending 状态的 InboundDirectLog,与代码实现一致"
"commit description 中将 pending 状态的 EntryReceivingBinding 更新为 pending 状态的 InboundDirectLog,与代码实现一致"
],
"type": "updated"
},
{
"version": "2026-07-03-entry-get-params-fix",
"date": "2026-07-03",
"type": "updated",
"summary": "修正 storage.entry.get 文档:id 改为必填;移除未实现的 entry_order_code 参数;修正错误码与实际返回一致;补充 available_receiving_details 响应字段;修正 remaining_quantity 计算公式及 warehouse_image_url 实际行为",
"methods": [
"storage.entry.get"
],
"notes": [
"params: 移除 entry_order_code(代码中从未使用该参数),id 从 required=false 改为 required=true",
"params: id 描述从'二选一'改为'必填'",
"errors: 400 的 message 从'参数错误:id 与 entry_order_code 至少提供一个'改为'id 参数不能为空'",
"errors: 移除不存在的 404 error,入库单不存在时实际返回 code=0, message='入库单不存在或无权访问'",
"errors: 删除不存在的 500 error",
"response: 新增 entryOrder.items[].available_receiving_details 字段及其描述",
"response: remaining_quantity 描述从 'count - received_quantity - direct_inbound_quantity' 修正为 'max(0, count - received_quantity)'",
"response: warehouse_image_url 描述从 StockWarehouse.image_url 改为'当前固定返回空字符串'",
"response: warehouse_is_images 类型从 number(0/1) 改为 string(Y/N),与 StockWarehouse.is_images 实际存储一致",
"response: warehouse_quantity/warehouse_locked_quantity/warehouse_is_batch_mgmt/warehouse_is_shelf_life_mgmt 补充无匹配时为 null 的说明",
"description: 更新描述以反映实际逻辑流程"
]
}
]

View File

@ -1607,6 +1607,64 @@
}
],
"errors": []
},
{
"method": "index.toOrder",
"description": "根据运单号快速查询订单ID及其所属波次下所有订单ID列表。查询流程:1) 通过运单号查询 wms_order_express 表(status=1)获取 order_id 和 warehouse_id;2) 遍历多表(current/history/dispatch)获取 wave_id 和 wave_no;3) 若有有效波次则再遍历多表查询该波次下所有订单的 ID 列表。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [],
"params": [
{
"name": "waybill_code",
"type": "string",
"required": true,
"source": "body",
"description": "运单号"
}
],
"response": [
{
"name": "order_id",
"type": "number",
"required": true,
"description": "订单ID"
},
{
"name": "waves",
"type": "array",
"required": true,
"description": "波次列表,无波次时为空数组。每项含 wave_id(波次ID,number)、wave_no(波次号,string)、order_ids(波次下所有订单ID列表,number[])"
},
{
"name": "waves[].wave_id",
"type": "number",
"required": true,
"description": "波次ID"
},
{
"name": "waves[].wave_no",
"type": "string",
"required": true,
"description": "波次号"
},
{
"name": "waves[].order_ids",
"type": "array<number>",
"required": true,
"description": "该波次下所有订单的 ID 列表"
}
],
"errors": [
{
"code": 405,
"message": "运单号不能为空"
},
{
"code": 405,
"message": "未找到该运单号对应的订单"
}
]
}
]
},
@ -18968,7 +19026,7 @@
]
},
{
"groupName": "入库模块",
"groupName": "入库单",
"module": "storage.entry",
"list": [
{
@ -19054,7 +19112,7 @@
},
{
"method": "storage.entry.get",
"description": "查询入库单详情。返回的 entryOrder 包含顶层 receivingBindings(主表级关联,含关联的收货单信息),不再返回 items[].bindings(明细级绑定)。entryOrder.order_status 可能为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。",
"description": "查询入库单详情。通过入库单 ID 定位,关联 Store、EntryItems、EntryOrderReceiving→Receiving,并通过仓库商品详情、直接入库进度、收货单可用明细进行数据合并。entryOrder.order_status 可能为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
@ -19069,16 +19127,9 @@
{
"name": "id",
"type": "number",
"required": false,
"required": true,
"source": "body",
"description": "入库单ID,与 entry_order_code 二选一"
},
{
"name": "entry_order_code",
"type": "string",
"required": false,
"source": "body",
"description": "入库单号,与 id 二选一"
"description": "入库单ID(必填)"
}
],
"response": [
@ -19086,37 +19137,37 @@
"name": "entryOrder",
"type": "object",
"required": true,
"description": "入库单详情,包含 items 数组和 receivingBindings(主表级收货单关联数组)。items 每项含 external_item_code / external_item_id / warehouse_item_code / warehouse_item_name / warehouse_item_spec / count / received_quantity / confirm_quantity / warehouse_quantity / warehouse_locked_quantity / warehouse_is_batch_mgmt / warehouse_is_shelf_life_mgmt / warehouse_image_url / warehouse_is_images / barcodes / direct_inbound_quantity / remaining_quantity"
"description": "入库单详情,包含 items 数组、receivingBindings(主表级收货单关联数组)。items 每项含 external_item_code / external_item_id / warehouse_item_code / warehouse_item_name / warehouse_item_spec / count / received_quantity / confirm_quantity / warehouse_quantity / warehouse_locked_quantity / warehouse_is_batch_mgmt / warehouse_is_shelf_life_mgmt / warehouse_image_url / warehouse_is_images / barcodes / direct_inbound_quantity / remaining_quantity / available_receiving_details"
},
{
"name": "entryOrder.items[].external_item_code",
"type": "string",
"required": true,
"description": "外部商品编码"
"description": "外部商品编码(源自 EntryItems.item_code)"
},
{
"name": "entryOrder.items[].external_item_id",
"type": "number",
"required": true,
"description": "外部商品ID"
"description": "外部商品ID(源自 EntryItems.item_id)"
},
{
"name": "entryOrder.items[].warehouse_item_code",
"type": "string",
"required": true,
"description": "仓库商品编码"
"description": "仓库商品编码(StockWarehouse.item_code),无匹配时为空字符串"
},
{
"name": "entryOrder.items[].warehouse_item_name",
"type": "string",
"required": true,
"description": "仓库商品名称"
"description": "仓库商品名称(StockWarehouse.item_name),无匹配时为空字符串"
},
{
"name": "entryOrder.items[].warehouse_item_spec",
"type": "string",
"required": true,
"description": "仓库商品规格(sku_property)"
"description": "仓库商品规格(StockWarehouse.sku_property),无匹配时为空字符串"
},
{
"name": "entryOrder.items[].count",
@ -19140,55 +19191,61 @@
"name": "entryOrder.items[].warehouse_quantity",
"type": "number",
"required": true,
"description": "仓库当前库存总量(StockWarehouse.quantity)"
"description": "仓库当前库存总量(StockWarehouse.quantity),无匹配时为 null"
},
{
"name": "entryOrder.items[].warehouse_locked_quantity",
"type": "number",
"required": true,
"description": "仓库锁定数量(StockWarehouse.locked_quantity)"
"description": "仓库锁定数量(StockWarehouse.locked_quantity),无匹配时为 null"
},
{
"name": "entryOrder.items[].warehouse_is_batch_mgmt",
"type": "string",
"required": true,
"description": "是否批次管理(StockWarehouse.is_batch_mgmt),Y/N"
"description": "是否批次管理(StockWarehouse.is_batch_mgmt),Y/N;无匹配时为 null"
},
{
"name": "entryOrder.items[].warehouse_is_shelf_life_mgmt",
"type": "string",
"required": true,
"description": "是否效期管理(StockWarehouse.is_shelf_life_mgmt),Y/N"
"description": "是否效期管理(StockWarehouse.is_shelf_life_mgmt),Y/N;无匹配时为 null"
},
{
"name": "entryOrder.items[].warehouse_image_url",
"type": "string",
"required": true,
"description": "商品图片 URL(StockWarehouse.image_url)"
"description": "商品图片 URL,当前固定返回空字符串 ''"
},
{
"name": "entryOrder.items[].warehouse_is_images",
"type": "number",
"type": "string",
"required": true,
"description": "是否有图片(StockWarehouse.is_images),0/1"
"description": "是否有图片(StockWarehouse.is_images),Y/N;无匹配时为 null"
},
{
"name": "entryOrder.items[].barcodes",
"type": "array",
"required": true,
"description": "条码列表,每项含 { id, barcode, sku_property }"
"description": "条码列表,每项含 { id, barcode, sku_property };无匹配时为空数组 []"
},
{
"name": "entryOrder.items[].direct_inbound_quantity",
"type": "number",
"required": true,
"description": "导入/PDA 已入库数量(InboundDirectLog 聚合)"
"description": "导入/PDA 已入库数量(InboundDirectLog 按 stock_id 聚合),无记录时为 0"
},
{
"name": "entryOrder.items[].remaining_quantity",
"type": "number",
"required": true,
"description": "剩余可入库数量(count - received_quantity - direct_inbound_quantity,最小为 0)"
"description": "剩余可入库数量 = max(0, count - received_quantity),最小为 0"
},
{
"name": "entryOrder.items[].available_receiving_details",
"type": "array",
"required": true,
"description": "可匹配的收货单明细及剩余可用量。每项含 receiving_id / receiving_number / receiving_detail_id / actual_quantity / allocated_quantity / available_quantity。仅返回收货单状态未完成且未完全入库的明细。无匹配时为空数组 []"
},
{
"name": "entryOrder.receivingBindings",
@ -19200,15 +19257,15 @@
"errors": [
{
"code": "400",
"message": "参数错误:id 与 entry_order_code 至少提供一个"
"message": "id 参数不能为空"
},
{
"code": "404",
"message": "入库单不存在"
"code": "0",
"message": "入库单不存在或无权访问"
},
{
"code": "500",
"message": "查询失败"
"code": "200",
"message": "查询成功"
}
]
},
@ -19267,54 +19324,7 @@
]
},
{
"method": "storage.entry.completeEntry",
"description": "完成入库单。仅将入库单状态从 PENDING 变更为 COMPLETED,不涉及库存写入(库存写入统一由 storage.entry.commitDirectInbound 完成)。仅 PENDING(已审核)状态可完成;CREATED(已创建待审核)状态需先审核(→PENDING)后再完成;CANCELLED(已作废)状态不允许完成。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "entry_order_id",
"type": "number",
"required": true,
"source": "body",
"description": "入库单ID"
}
],
"response": [
{
"name": "entry_order_id",
"type": "number",
"required": true,
"description": "入库单ID"
},
{
"name": "order_status",
"type": "string",
"required": true,
"description": "入库单状态,完成时为 COMPLETED"
}
],
"errors": [
{
"code": 400,
"message": "当前入库单状态不允许完成(仅 PENDING 状态可完成)"
},
{
"code": 404,
"message": "入库单不存在或无权访问"
}
]
},
{
"method": "storage.entry.addDirectInboundItem",
"method": "storage.entry.addItem",
"description": "按商品增量添加导入/PDA 入库记录(支持单条和批量)。单条模式传 stock_id/quantity/inbound_type/remark,批量模式传 items 数组。批量模式所有商品共享同一个入库单状态校验,任一商品校验失败整批拒绝。若某商品累计入库量超过计划数量则拒绝(PENDING 非绑定模式)。PENDING 状态需传 receiving_detail_id 绑定收货明细;CREATED 人工导入允许超过计划数量;传入 receiving_detail_id 时 quantity 可选(自动计算可用数量),space_id 必填。",
"isNeedAuth": false,
"isNeedLogin": true,
@ -19519,7 +19529,7 @@
]
},
{
"method": "storage.entry.commitDirectInbound",
"method": "storage.entry.commit",
"description": "提交确认完成导入/PDA 入库。先同步奇门/API 回传,成功后在 onSuccess 回调内开启事务写入库存(wms_stock_warehouse.quantity 增量、wms_stock_transaction 流水),将 pending 状态的 InboundDirectLog 更新为 committed,更新入库单状态为 COMPLETED,同步 sync_status=SUCCESS。不足量提交时未入库商品跳过。",
"isNeedAuth": false,
"isNeedLogin": true,
@ -19598,7 +19608,7 @@
]
},
{
"method": "storage.entry.removeDirectInboundItem",
"method": "storage.entry.removeItem",
"description": "移除一条导入/PDA 入库记录(仅限未提交的入库单,即状态非 CANCELLED/COMPLETED)。移除后该商品的可入库余量自动恢复。",
"isNeedAuth": false,
"isNeedLogin": true,
@ -19656,101 +19666,6 @@
}
]
},
{
"method": "storage.entry.bindReceivingDetails",
"description": "批量绑定入库单明细与收货单明细。绑定只能使用关联收货单中匹配的 stock_id(通过 system_product_id 映射),且不能超出收货单明细的可用数量(actual_quantity - 已 committed 的 allocated_quantity)。支持部分成功:校验通过的写入绑定,不通过的在 failed 列表中返回原因。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "entry_order_id",
"type": "number",
"required": true,
"source": "body",
"description": "入库单ID"
},
{
"name": "bindings",
"type": "array",
"required": true,
"source": "body",
"description": "绑定列表,每项包含 entry_item_id、receiving_detail_id、allocated_quantity"
}
],
"response": [
{
"name": "success",
"type": "array",
"required": true,
"description": "成功绑定的列表,每项包含 entry_item_id、receiving_detail_id、allocated_quantity"
},
{
"name": "failed",
"type": "array",
"required": true,
"description": "绑定失败的列表,每项包含 entry_item_id、receiving_detail_id、allocated_quantity、error_code、message、detail",
"items": {
"type": "object",
"properties": {
"entry_item_id": {
"type": "number",
"description": "入库单明细ID"
},
"receiving_detail_id": {
"type": "number",
"description": "收货单明细ID"
},
"allocated_quantity": {
"type": "number",
"description": "请求分配的数量"
},
"error_code": {
"type": "string",
"description": "错误码,可能值:ENTRY_ITEM_NOT_FOUND(入库明细不存在)、STOCK_NOT_FOUND(商品不存在)、RECEIVING_DETAIL_MISMATCH(收货明细与入库商品不匹配)、RECEIVING_DETAIL_NOT_FOUND(收货明细不存在)、INSUFFICIENT_AVAILABLE_QUANTITY(超出可用数量)、ENTRY_ORDER_STATUS_INVALID(入库单状态不允许绑定)"
},
"message": {
"type": "string",
"description": "中文错误描述,可直接展示给用户"
},
"detail": {
"type": "object",
"description": "错误上下文数据,根据 error_code 不同包含不同字段。如 INSUFFICIENT_AVAILABLE_QUANTITY 时包含 available_quantity 和 requested_quantity"
}
}
}
},
{
"name": "success_count",
"type": "number",
"required": true,
"description": "成功数量"
},
{
"name": "failed_count",
"type": "number",
"required": true,
"description": "失败数量"
}
],
"errors": [
{
"code": 400,
"message": "参数校验失败:entry_order_id 必填 / bindings 必填且为非空数组 / 入库单状态不允许绑定时,所有 bindings 均返回 failed 且 error_code 为 ENTRY_ORDER_STATUS_INVALID"
},
{
"code": 404,
"message": "入库单不存在或无权访问"
}
]
},
{
"method": "storage.entry.quickInbound",
"description": "快捷直入(虚拟入库):将入库单所有商品按明细数量一键直入到虚拟库位(space_id=2),跳过收货/质检流程,入库单状态变为COMPLETED。仅支持 CREATED 状态的入库单;CANCELLED(已作废)、COMPLETED(已完成)、PENDING 等其他状态均拒绝操作。事务内操作:更新入库明细收货量、累加库存总量、写入库存流水、写入虚拟库位库存、变更入库单状态为 COMPLETED。事务外异步回传奇门/API。",
@ -25883,46 +25798,6 @@
]
}
]
},
{
"groupName": "快捷操作",
"module": "quick",
"list": [
{
"method": "quick.waybill.toOrder",
"description": "根据运单号快速查询订单ID。查询 wms_order_express 表中 status=1 的有效记录,返回对应的 order_id。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [],
"params": [
{
"name": "waybill_code",
"type": "string",
"required": true,
"source": "body",
"description": "运单号"
}
],
"response": [
{
"name": "order_id",
"type": "number",
"required": true,
"description": "订单ID"
}
],
"errors": [
{
"code": 405,
"message": "运单号不能为空"
},
{
"code": 405,
"message": "未找到该运单号对应的订单"
}
]
}
]
}
]
}

View File

@ -1,449 +0,0 @@
# 入库单推送全流程测试指南
## 1. 全流程概述
```
奇门推送 entryorder.create → 创建入库单(CREATED)
→ bindReceiving(绑定收货单)
→ reviewEntry(CREATED→PENDING)
→ addItem(PDA上架,传 receiving_detail_id + space_id)
→ commit(提交入库+奇门同步→COMPLETED)
或 quickInbound(虚拟直入,跳过收货单,CREATED→COMPLETED)
```
### 流程说明
| 阶段 | method | 状态变化 | 说明 |
|------|--------|----------|------|
| 奇门创建 | `qimen.entryorder.create` | (无)→CREATED | 奇门 XML 推送,创建入库单及明细 |
| 绑定收货单 | `storage.entry.bindReceiving` | CREATED→CREATED | 将入库单与收货单关联 |
| 审核 | `storage.entry.reviewEntry` | CREATED→PENDING | 审核通过,允许上架,**必须已绑定收货单** |
| PDA上架 | `storage.directInbound.addItem` | PENDING→PENDING | PDA扫码上架,传 `receiving_detail_id` + `space_id` |
| 提交入库 | `storage.directInbound.commit` | PENDING→COMPLETED | 先奇门同步,再写库存 |
| 虚拟直入 | `storage.entry.quickInbound` | CREATED→COMPLETED | 跳过收货单,一键完成入库 |
## 2. 关键接口列表
| 步骤 | method | 说明 | 入口 |
|------|--------|------|------|
| 创建 | `qimen.entryorder.create` | 奇门推送 XML 创建入库单 | /qimen |
| 绑定 | `storage.entry.bindReceiving` | 绑定收货单到入库单 | /system |
| 审核 | `storage.entry.reviewEntry` | CREATED→PENDING,需已绑定 | /system |
| 上架 | `storage.directInbound.addItem` | PDA添加,可选绑定收货明细 | /system |
| 提交 | `storage.directInbound.commit` | 同步奇门+写库存→COMPLETED | /system |
| 虚拟 | `storage.entry.quickInbound` | 一键虚拟入库 | /system |
| 对照 | `storage.entry.receivingCompare` | 入库单 vs 收货单明细对照 | /system |
| 查询 | `storage.directInbound.getItems` | 查询直入记录 | /system |
| 日志 | `storage.entry.queryEntryLogs` | 查询入库单操作日志 | /system |
## 3. 踩坑点
### 3a. 端口
配置文件(`config/config.local.js`)中端口是 **6060**,不是 Egg.js 默认的 7001。
```powershell
# 确认端口
Select-String -Path "config/config.local.js" -Pattern "port"
```
### 3b. app_key 双重角色
- **签名用**:`config.qimen.appKey`(如 `23535631`),用于奇门请求的 MD5 签名计算
- **validateApi 查询匹配用**:请求参数中的 `app_key`(如 `23060081`),用于匹配 `wms_api_app` 表记录
- **两个值不同**,签名的 `app_key` 不参与 `wms_api_app` 绑定查询
### 3c. 奇门签名
- **签名算法**:`secret + sortedParams + xmlBody + secret` → MD5 → 大写
- **签名不验证入站请求**:qimen 入口无 `verifyTopRequest` 校验
- **使用已有合约配置**:从 `wms_api_app` 表读取,不要无中生有创建新配置
### 3d. itemId 必传
- `itemId` 为空时,按 `item_code + app_key + warehouse_id + store_id` 查询 `StockStore`
- `app_key` 不匹配会导致找不到商品
- **建议一律传 `itemId`** 以避免匹配问题
### 3e. 服务器重启
修改代码后需完全重启:
```powershell
taskkill /F /IM node.exe
npm run dev
```
端口被占用排查:
```powershell
netstat -ano | findstr :6060
```
### 3f. /system 接口需要 headers
```http
platform: web
project: wms
Authorization: Bearer <JWT_TOKEN>
```
测试账号:`liufumingren` / `111111`
获取 token:
```powershell
curl -X POST http://localhost:6060/system?method=user.login `
-H "platform: web" `
-H "project: wms" `
-H "Content-Type: application/json" `
-d '{"username":"liufumingren","password":"111111"}'
```
### 3g. 先同步后写库
`quickInbound` 和 `commit` 的执行顺序已改为:
1. 先调用 `qimenEntrySync` 同步到奇门/ERP
2. 同步成功后才写库存
3. 同步失败不写库存,只标记为 `FAILED`
### 3h. 绑定模式
`addItem` 传 `receiving_detail_id` 时进入绑定模式:
- **忽略 `quantity` 字段**,实际数量从 `ReceivingDetail.actual_quantity` 取值
- **必须传 `space_id`**(库位ID)
- **允许超过入库单 `planQty`**,不受计划数量限制
## 4. 快速测试脚本示例
### 4.1 准备工作:获取 Token
```powershell
$loginBody = @{username="liufumingren";password="111111"} | ConvertTo-Json
$loginResp = curl -s -X POST "http://localhost:6060/system?method=user.login" `
-H "platform: web" -H "project: wms" `
-H "Content-Type: application/json" `
-d $loginBody
$token = ($loginResp | ConvertFrom-Json).data.token
Write-Host "Token: $token"
```
### 4.2 创建入库单(奇门推送)
```xml
POST /qimen?method=entryorder.create&app_key=23060081&customerId=4&v=1.0&format=xml&sign_method=md5&timestamp=2026-06-27+10:00:00&sign=XXX
<request>
<entryOrder>
<entryOrderCode>TEST-ENTRY-001</entryOrderCode>
<warehouseCode>WH001</warehouseCode>
<orderType>JYCK</orderType>
</entryOrder>
<orderLines>
<orderLine>
<itemCode>SKU001</itemCode>
<planQty>100</planQty>
</orderLine>
</orderLines>
</request>
```
### 4.3 创建收货单
```powershell
$rcvBody = @{
delivery_method="truck"
loading_method="without_pallet"
store_id=1000000
} | ConvertTo-Json
curl -s -X POST "http://localhost:6060/system?method=storage.receiving.create" `
-H "platform: web" -H "project: wms" `
-H "Authorization: Bearer $token" `
-H "Content-Type: application/json" `
-d $rcvBody
```
### 4.4 添加收货明细
```powershell
$detailBody = @{
receiving_id="<RECEIVING_ID>"
item=@{
product_name="测试商品"
actual_quantity=86
}
} | ConvertTo-Json
curl -s -X POST "http://localhost:6060/system?method=storage.receiving.addDetail" `
-H "platform: web" -H "project: wms" `
-H "Authorization: Bearer $token" `
-H "Content-Type: application/json" `
-d $detailBody
```
### 4.5 完成收货 + 审核
```powershell
# 完成收货
curl -s -X POST "http://localhost:6060/system?method=storage.receiving.completeReceiving" `
-H "platform: web" -H "project: wms" `
-H "Authorization: Bearer $token" `
-H "Content-Type: application/json" `
-d "{`"receiving_id`":`"<RECEIVING_ID>`"}"
# 审核收货单
curl -s -X POST "http://localhost:6060/system?method=storage.receiving.reviewReceiving" `
-H "platform: web" -H "project: wms" `
-H "Authorization: Bearer $token" `
-H "Content-Type: application/json" `
-d "{`"receiving_id`":`"<RECEIVING_ID>`"}"
```
### 4.6 绑定入库单 + 审核
```powershell
# 绑定收货单
curl -s -X POST "http://localhost:6060/system?method=storage.entry.bindReceiving" `
-H "platform: web" -H "project: wms" `
-H "Authorization: Bearer $token" `
-H "Content-Type: application/json" `
-d "{`"entry_id`":`"<ENTRY_ID>`",`"receiving_id`":`"<RECEIVING_ID>`"}"
# 审核入库单
curl -s -X POST "http://localhost:6060/system?method=storage.entry.reviewEntry" `
-H "platform: web" -H "project: wms" `
-H "Authorization: Bearer $token" `
-H "Content-Type: application/json" `
-d "{`"entry_id`":`"<ENTRY_ID>`"}"
```
### 4.7 PDA上架 + 提交
```powershell
# 添加直入记录(绑定模式)
$addItemBody = @{
entry_id="<ENTRY_ID>"
receiving_detail_id="<RECEIVING_DETAIL_ID>"
space_id="<SPACE_ID>"
item_code="SKU001"
} | ConvertTo-Json
curl -s -X POST "http://localhost:6060/system?method=storage.directInbound.addItem" `
-H "platform: web" -H "project: wms" `
-H "Authorization: Bearer $token" `
-H "Content-Type: application/json" `
-d $addItemBody
# 提交入库
curl -s -X POST "http://localhost:6060/system?method=storage.directInbound.commit" `
-H "platform: web" -H "project: wms" `
-H "Authorization: Bearer $token" `
-H "Content-Type: application/json" `
-d "{`"entry_id`":`"<ENTRY_ID>`"}"
```
### 4.8 虚拟直入(跳过收货单)
```powershell
$quickBody = @{
entry_id="<ENTRY_ID>"
items=@(
@{
item_code="SKU001"
quantity=50
space_id="<SPACE_ID>"
}
)
} | ConvertTo-Json
curl -s -X POST "http://localhost:6060/system?method=storage.entry.quickInbound" `
-H "platform: web" -H "project: wms" `
-H "Authorization: Bearer $token" `
-H "Content-Type: application/json" `
-d $quickBody
```
## 5. 数据库关键表
| 表 | 用途 | 关键字段 |
|----|------|----------|
| `wms_entry_order` | 入库单主表 | id, entry_order_code, order_status, sync_status |
| `wms_entry_items` | 入库单明细 | id, entry_id, item_id, item_code, plan_quantity, actual_quantity |
| `wms_receiving` | 收货单主表 | id, receiving_code, status, store_id |
| `wms_receiving_detail` | 收货单明细 | id, receiving_id, product_name, actual_quantity |
| `wms_entry_order_receiving` | 入库单↔收货单主表绑定 | id, entry_id, receiving_id |
| `wms_entry_receiving_binding` | [已弃用] 入库明细↔收货明细绑定(已迁至 InboundDirectLog) | id, entry_item_id, receiving_detail_id, quantity |
| `wms_inbound_direct_log` | PDA直入记录 + 入库明细↔收货明细绑定 | id, entry_id, entry_item_id, item_code, quantity, space_id, receiving_detail_id, status, updated_at, deleted_at |
| `wms_api_app` | 奇门应用绑定配置 | id, app_key, app_secret, warehouse_id, store_id |
| `wms_operation_log` | 操作日志 | id, target_type, target_id, action, operator, created_at |
## 6. 状态机速查
| 状态 | 含义 | 可执行操作 |
|------|------|------------|
| `CREATED` | 已创建,待绑定/审核 | bindReceiving, reviewEntry, quickInbound, cancel |
| `PENDING` | 已审核,待上架 | addItem, commit, cancel |
| `COMPLETED` | 已完成 | 不可操作 |
| `CANCELLED` | 已取消 | 不可操作 |
| `FAILED` | 同步失败 | 重试或取消 |
## 7. 常见问题排查
### 7.1 找不到入库单
- 检查奇门 XML 中 `warehouseCode` 是否匹配 `wms_api_app` 中的 `warehouse_id`
- 检查 `app_key` 是否已在 `wms_api_app` 表中配置
### 7.2 reviewEntry 报错"未绑定收货单"
- CREATED 状态且未调用 `bindReceiving` 时,审核会被拒绝
- 先调用 `bindReceiving` 绑定收货单
### 7.3 addItem 报错"缺少 space_id"
- 绑定模式下(传了 `receiving_detail_id`)必须同时传 `space_id`
- `space_id` 对应库位表主键
### 7.4 commit 后库存未变化
- 检查 `qimenEntrySync` 是否返回成功
- 同步失败时标记为 `FAILED` 状态,库存不会写入
- 查看 `wms_operation_log` 中的错误信息
### 7.5 端口被占用
```powershell
# 查找占用进程
netstat -ano | findstr :6060
# 强制结束
taskkill /F /PID <PID>
```
## 8. 变更历史
| 日期 | 版本 | 变更内容 |
|------|------|----------|
| 2026-06-27 | v1.0 | 初始版本,覆盖入库单全流程测试指南 |
## 8. 问题清单与修复基准(来自 issues.txt)
### 问题 1:缺失收货单直接转入库单的快捷入口
- **现状**:收货单创建后,必须先手动创建入库单(走奇门或 OpenAPI),再通过 bindReceiving 绑定
- **修复后应支持**:storage.receiving.createEntryOrder(receiving_id) → 自动创建入库单并绑定主表关系
### 问题 2:addItem 状态机校验不完整
- **2a**:CREATED + 已绑定收货单 → 应拒绝(当前只强制要求传 receiving_detail_id)
- **2b**:PENDING + 已绑定 + 无明细ID → 应拒绝(当前未区分 CREATED/PENDING)
- **2c**:PENDING + 无绑定 → 应拒绝(PENDING 只能走 PDA 上架,必须已绑定收货单)
- **2d**:CREATED 人工导入 → 应允许超过 planQty(当前非绑定模式不允许超量)
**修复后校验矩阵:**
| 状态 | 有绑定 | 携带明细ID | 应允许 | 超 planQty |
|------|--------|-----------|--------|-----------|
| CREATED | 否 | 否 | ✅ 人工后台导入 | ✅ 允许 |
| CREATED | 是 | - | ❌ 拒绝 | - |
| PENDING | 否 | - | ❌ 拒绝 | - |
| PENDING | 是 | 否 | ❌ 拒绝 | - |
| PENDING | 是 | 是 | ✅ PDA上架 | ✅ 允许 |
### 问题 3:状态机定义
`
CREATING → CREATED → PENDING → COMPLETED
↑ ↓ ↑
└── 重试推送 ────────┘ │
CANCELLED ←────────┘
`
- CREATED:等待人工绑定和审核,可走人工后台导入(不限制 planQty),可走虚拟直入
- PENDING:已审核,待上架/上架中,必须已绑定收货单,必须携带 receiving_detail_id
- COMPLETED:已完成,不可操作
### 问题 4:entryorderConfirm 增量回传应移除
- 统一走 qimenEntrySync 全量同步,actualQty = item.count
- 移除 entry_order.js 的 entryorderConfirm 方法
### 问题 5:completeEntry 应作废
- commit 已包含所有实质性工作(写库存、同步奇门、推进 COMPLETED)
- completeEntry 无独立存在意义
### 问题 6:入库单取消
- 6a:取消时调用 qimenEntrySync,orderLines 全部 actualQty=0,通知 ERP 关闭
- 6b:sync_status=SUCCESS 的入库单不允许取消(已通知 ERP 入库完成)
- 允许取消的状态:sync_status != 'SUCCESS' 且 order_status NOT IN ('COMPLETED','CANCELLED')
## 9. 完整测试场景
### 场景 A:奇门创建 + 收货单 + PDA上架(完整链路)
`
1. qimen.entryorder.create → CREATED
2. storage.receiving.create → 收货单
3. storage.receiving.addDetail → 收货明细
4. storage.receiving.completeReceiving → 完成收货
5. storage.receiving.reviewReceiving → 审核收货单
6. storage.entry.bindReceiving → 绑定入库单↔收货单
7. storage.entry.receivingCompare → 对照预览
8. storage.entry.reviewEntry → CREATED→PENDING
9. storage.directInbound.addItem(receiving_detail_id) → PDA上架+明细绑定
10. storage.directInbound.commit → 奇门同步+写库存→COMPLETED
`
### 场景 B:人工后台导入(无收货单)
`
1. qimen.entryorder.create → CREATED
2. storage.directInbound.addItem(无 receiving_detail_id) → 人工导入
3. storage.directInbound.commit → 奇门同步+写库存→COMPLETED
`
### 场景 C:虚拟直入
`
1. qimen.entryorder.create → CREATED
2. storage.entry.quickInbound → 奇门同步+写库存→COMPLETED(一步完成)
`
### 场景 D:取消入库单
`
1. 入库单 CREATED/PENDING 且 sync_status != SUCCESS
2. storage.entry.cancel → ①发送 qimenEntrySync(all actualQty=0) → ②更新 order_status=CANCELLED
`
## 10. 数据库校验检查点
修复完成后,以下 SQL 可用于验证各场景正确性:
\\\sql
-- 验证入库单状态
SELECT id, entry_order_code, order_status, sync_status, sync_message FROM wms_entry_order WHERE id = ?;
-- 验证入库明细收货量
SELECT id, item_code, count, received_quantity, confirm_quantity FROM wms_entry_items WHERE order_id = ?;
-- 验证主表绑定
SELECT * FROM wms_entry_order_receiving WHERE entry_order_id = ?;
-- 验证明细绑定
SELECT id, entry_item_id, receiving_detail_id, allocated_quantity, status FROM wms_entry_receiving_binding WHERE entry_item_id IN (SELECT id FROM wms_entry_items WHERE order_id = ?);
-- 验证直入记录
SELECT id, stock_id, quantity, space_id FROM wms_inbound_direct_log WHERE entry_order_id = ?;
-- 验证库存写入
SELECT id, stock_id, batch_no, quantity, receiving_id, production_date, expiry_date FROM wms_storage WHERE entry_order_id = ?;
-- 验证操作日志
SELECT id, business_type, business_id, operation_code, message FROM wms_operation_log WHERE business_id = ? AND business_type = 'entry_order' ORDER BY created_at DESC;
\\\
## 11. 已知操作码清单
| operationCode | 触发接口 | 说明 |
|---------------|---------|------|
| ENTRY_ORDER_CREATE | qimen/OpenAPI entryorder.create | 入库单创建 |
| ENTRY_ORDER_REVIEW | storage.entry.reviewEntry | 审核通过 CREATED→PENDING |
| DIRECT_INBOUND_ADD | storage.directInbound.addItem | 直入记录添加 |
| DIRECT_INBOUND_COMMIT | storage.directInbound.commit | 提交入库 COMPLETED |
| DIRECT_INBOUND_REMOVE | storage.directInbound.removeItem | 移除直入记录 |
| QUICK_INBOUND | storage.entry.quickInbound | 虚拟直入完成 |
| QUICK_INBOUND_FAILED | quickInbound/commit 失败 | 同步失败 |

View File

@ -1,37 +0,0 @@
'use strict';
(async () => {
try {
const cfg = require('../database/config.js').production;
const mysql = require('mysql2/promise');
const conn = await mysql.createConnection({
host: cfg.host,
user: cfg.username || cfg.user,
password: cfg.password,
database: cfg.database,
port: cfg.port || 3306,
});
const migrationName = '20260507100000-create-wms_order_wave_strategy_match.js';
const schema = cfg.database;
const [metaRows] = await conn.query('SELECT name FROM SequelizeMeta WHERE name = ? LIMIT 1', [migrationName]);
const migrationInMeta = (metaRows.length && metaRows.length > 0) ? true : false;
const [tableRows] = await conn.query('SELECT TABLE_NAME FROM information_schema.tables WHERE table_schema = ? AND table_name = ?', [schema, 'wms_order_wave_strategy_match']);
const tableExists = (tableRows.length && tableRows.length > 0) ? true : false;
const [columnsRows] = await conn.query('SELECT COLUMN_NAME FROM information_schema.columns WHERE table_schema = ? AND table_name = ? AND COLUMN_NAME IN (?,?,?,?,?)', [schema, 'wms_order_wave_strategy_match', 'id','warehouse_id','order_id','strategy_id','create_time']);
const columns = (columnsRows || []).map(r => r.COLUMN_NAME);
const [idxRows] = await conn.query('SELECT DISTINCT INDEX_NAME FROM information_schema.statistics WHERE table_schema = ? AND table_name = ? AND INDEX_NAME IN (?,?)', [schema, 'wms_order_wave_strategy_match', 'idx_warehouse_order', 'idx_warehouse_strategy']);
const indices = (idxRows || []).map(r => r.INDEX_NAME);
console.log(JSON.stringify({ migrationInMeta, tableExists, columns, indices }, null, 2));
await conn.end();
process.exit(0);
} catch (err) {
console.error('ERROR:', err && err.message ? err.message : err);
process.exit(2);
}
})();