diff --git a/_diag6.cjs b/_diag6.cjs deleted file mode 100644 index cc5f93d..0000000 --- a/_diag6.cjs +++ /dev/null @@ -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' })); diff --git a/app/service/systemMethods/index.js b/app/service/systemMethods/index.js index 2ad7b8f..2db538f 100644 --- a/app/service/systemMethods/index.js +++ b/app/service/systemMethods/index.js @@ -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} 统一成功包装响应,包含 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; diff --git a/app/service/systemMethods/order/pendingOrder.js b/app/service/systemMethods/order/pendingOrder.js index ca5c730..359e912 100644 --- a/app/service/systemMethods/order/pendingOrder.js +++ b/app/service/systemMethods/order/pendingOrder.js @@ -2834,6 +2834,7 @@ class PendingOrderService extends OrderBaseService { detailAddress, zipCode: String(requestData.zip_code || '').trim(), }, + seller_message: String(requestData.remark || '').trim(), }, orderLines: { orderLine: orderLineItems, diff --git a/app/service/systemMethods/order/recheckOrder.js b/app/service/systemMethods/order/recheckOrder.js index 158f5ca..ea39d53 100644 --- a/app/service/systemMethods/order/recheckOrder.js +++ b/app/service/systemMethods/order/recheckOrder.js @@ -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, diff --git a/app/service/systemMethods/quick/waybill.js b/app/service/systemMethods/quick/waybill.js deleted file mode 100644 index a53863c..0000000 --- a/app/service/systemMethods/quick/waybill.js +++ /dev/null @@ -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} 统一成功包装响应,包含 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; diff --git a/app/service/systemMethods/storage/entry.js b/app/service/systemMethods/storage/entry.js index e82a358..808062e 100644 --- a/app/service/systemMethods/storage/entry.js +++ b/app/service/systemMethods/storage/entry.js @@ -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} 统一 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} 统一 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} 统一 success 包装 */ - async removeDirectInboundItem(data = {}) { + async removeItem(data = {}) { const { service } = this; const result = await service.systems.inboundDirectLog.removeItem(data); return this.success('ok', result); diff --git a/app/service/systems/order_express.js b/app/service/systems/order_express.js index 15f0562..9f6e347 100644 --- a/app/service/systems/order_express.js +++ b/app/service/systems/order_express.js @@ -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); diff --git a/app/service/systems/quick/waybill.js b/app/service/systems/quick/waybill.js deleted file mode 100644 index 1864517..0000000 --- a/app/service/systems/quick/waybill.js +++ /dev/null @@ -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} 包含 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; diff --git a/app/service/systems/storage/entry.js b/app/service/systems/storage/entry.js index cff056d..ea0ca8f 100644 --- a/app/service/systems/storage/entry.js +++ b/app/service/systems/storage/entry.js @@ -992,7 +992,7 @@ class EntryService extends Service { * @param {Array} [data.items] 商品列表(批量模式) * @return {Promise} 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} 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} code/data/message 结构 */ - async removeDirectInboundItem(data = {}) { + async removeItem(data = {}) { const { ctx } = this; return await ctx.service.systems.inboundDirectLog.removeItem(data); } diff --git a/app/service/systems/waybill.js b/app/service/systems/waybill.js new file mode 100644 index 0000000..79fcd49 --- /dev/null +++ b/app/service/systems/waybill.js @@ -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} 包含 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; diff --git a/methods/changes/system.json b/methods/changes/system.json index 5956315..3f0fea3 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -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: 更新描述以反映实际逻辑流程" + ] } ] diff --git a/methods/system.json b/methods/system.json index 49fc145..857bb52 100644 --- a/methods/system.json +++ b/methods/system.json @@ -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", + "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": "未找到该运单号对应的订单" - } - ] - } - ] } ] } diff --git a/skills/entry-order-test-guide.md b/skills/entry-order-test-guide.md deleted file mode 100644 index 3638961..0000000 --- a/skills/entry-order-test-guide.md +++ /dev/null @@ -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 -``` - -测试账号:`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×tamp=2026-06-27+10:00:00&sign=XXX - - - - TEST-ENTRY-001 - WH001 - JYCK - - - - SKU001 - 100 - - - -``` - -### 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="" - 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`":`"`"}" - -# 审核收货单 -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`":`"`"}" -``` - -### 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`":`"`",`"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`":`"`"}" -``` - -### 4.7 PDA上架 + 提交 - -```powershell -# 添加直入记录(绑定模式) -$addItemBody = @{ - entry_id="" - receiving_detail_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`":`"`"}" -``` - -### 4.8 虚拟直入(跳过收货单) - -```powershell -$quickBody = @{ - entry_id="" - items=@( - @{ - item_code="SKU001" - quantity=50 - 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 -``` - -## 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 失败 | 同步失败 | diff --git a/tmp/verify_migration.cjs b/tmp/verify_migration.cjs deleted file mode 100644 index 310d0f5..0000000 --- a/tmp/verify_migration.cjs +++ /dev/null @@ -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); - } -})();