From 478ad2ab0d0e10fe52ce7d08730d419b17f040de Mon Sep 17 00:00:00 2001 From: liufumingren Date: Fri, 3 Jul 2026 16:10:46 +0800 Subject: [PATCH] 1 --- _diag6.cjs | 18 + app/model/inbound_direct_log.js | 65 +- app/service/systemMethods/order/base.js | 278 ++++-- .../systemMethods/order/pendingOrder.js | 32 +- .../systemMethods/storage/direct_inbound.js | 71 -- app/service/systemMethods/storage/entry.js | 18 +- app/service/systems/inbound_direct_log.js | 91 +- app/service/systems/receiving_entry_match.js | 40 +- app/service/systems/storage/entry.js | 41 +- app/service/systems/storage/receiving.js | 8 +- ...-lock-unlock-to-wms-storage-transaction.js | 10 +- .../20260702-fix-receipt-a5-template.js | 310 ------- ...20260702-migrate-entry-order-print-data.js | 53 -- .../20260702-seed-receipt-default-template.js | 42 - .../20260702-seed-receipt-print-items-v2.js | 151 --- ...inding-fields-to-wms-inbound-direct-log.js | 100 ++ ...rate-binding-data-to-inbound-direct-log.js | 184 ++++ docs/api-doc-update-spec.example.json | 56 -- docs/api-doc-update-workflow.md | 124 --- docs/combo-goods-api.md | 387 -------- docs/express-model-table-map.md | 33 - docs/file-writer.md | 122 --- docs/notification-event-api.md | 255 ----- docs/notification-webhook-capability.md | 335 ------- docs/order-cancel-db-checklist.md | 97 -- docs/order-delivery-migration-impact.md | 62 -- docs/order-state-machine-dictionary.md | 45 - docs/order-workbench-list-api.md | 188 ---- docs/order_todo.md | 288 ------ docs/print-retry-compensation.md | 65 -- docs/qimen-interface-reference.md | 226 ----- docs/stock-expiry-module.md | 80 -- docs/stock-stockWarehouse-query-rules.md | 178 ---- docs/storage-receiving-api.md | 487 ---------- methods/changes/system.json | 42 + methods/system.json | 873 ++++-------------- skills/entry-order-test-guide.md | 4 +- 37 files changed, 889 insertions(+), 4570 deletions(-) create mode 100644 _diag6.cjs delete mode 100644 app/service/systemMethods/storage/direct_inbound.js delete mode 100644 database/migrations/20260702-fix-receipt-a5-template.js delete mode 100644 database/migrations/20260702-migrate-entry-order-print-data.js delete mode 100644 database/migrations/20260702-seed-receipt-default-template.js delete mode 100644 database/migrations/20260702-seed-receipt-print-items-v2.js create mode 100644 database/migrations/20260703000000-add-binding-fields-to-wms-inbound-direct-log.js create mode 100644 database/migrations/20260703000001-migrate-binding-data-to-inbound-direct-log.js delete mode 100644 docs/api-doc-update-spec.example.json delete mode 100644 docs/api-doc-update-workflow.md delete mode 100644 docs/combo-goods-api.md delete mode 100644 docs/express-model-table-map.md delete mode 100644 docs/file-writer.md delete mode 100644 docs/notification-event-api.md delete mode 100644 docs/notification-webhook-capability.md delete mode 100644 docs/order-cancel-db-checklist.md delete mode 100644 docs/order-delivery-migration-impact.md delete mode 100644 docs/order-state-machine-dictionary.md delete mode 100644 docs/order-workbench-list-api.md delete mode 100644 docs/order_todo.md delete mode 100644 docs/print-retry-compensation.md delete mode 100644 docs/qimen-interface-reference.md delete mode 100644 docs/stock-expiry-module.md delete mode 100644 docs/stock-stockWarehouse-query-rules.md delete mode 100644 docs/storage-receiving-api.md diff --git a/_diag6.cjs b/_diag6.cjs new file mode 100644 index 0000000..cc5f93d --- /dev/null +++ b/_diag6.cjs @@ -0,0 +1,18 @@ +'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/model/inbound_direct_log.js b/app/model/inbound_direct_log.js index 634d27c..918af8b 100644 --- a/app/model/inbound_direct_log.js +++ b/app/model/inbound_direct_log.js @@ -45,6 +45,21 @@ module.exports = app => { allowNull: true, comment: '入库单号(冗余,方便查询)', }, + entry_item_id: { + type: BIGINT(20).UNSIGNED, + allowNull: true, + comment: '入库明细ID', + }, + receiving_detail_id: { + type: INTEGER, + allowNull: true, + comment: '收货明细ID,绑定收货时使用', + }, + status: { + type: ENUM('pending', 'committed', 'released'), + allowNull: true, + comment: '绑定状态:pending=待提交 committed=已提交 released=已释放,非绑定模式为NULL', + }, remark: { type: STRING(500), allowNull: true, @@ -71,10 +86,24 @@ module.exports = app => { allowNull: false, comment: '创建时间', }, + updated_at: { + type: DATE, + allowNull: true, + comment: '更新时间', + }, + deleted_at: { + type: DATE, + allowNull: true, + comment: '软删除时间', + }, }, { tableName: 'wms_inbound_direct_log', comment: '非收货单途径入库直接记录表(导入/PDA入库)', - timestamps: false, + timestamps: true, + createdAt: 'created_at', + updatedAt: 'updated_at', + paranoid: true, + deletedAt: 'deleted_at', indexes: [ { name: 'idx_warehouse_id', @@ -96,8 +125,42 @@ module.exports = app => { name: 'idx_created_at', fields: [ 'created_at' ], }, + { + name: 'idx_entry_item_id', + fields: [ 'entry_item_id' ], + }, + { + name: 'idx_receiving_detail_id', + fields: [ 'receiving_detail_id' ], + }, + { + name: 'idx_status', + fields: [ 'status' ], + }, + { + name: 'uk_entry_receiving_binding', + unique: true, + fields: [ 'entry_item_id', 'receiving_detail_id', 'status' ], + }, ], }); + // 关联关系 + InboundDirectLog.associate = function() { + const { InboundDirectLog, EntryItems, ReceivingDetail } = app.model; + + // 关联入库明细 + InboundDirectLog.belongsTo(EntryItems, { + foreignKey: 'entry_item_id', + as: 'entryItem', + }); + + // 关联收货明细 + InboundDirectLog.belongsTo(ReceivingDetail, { + foreignKey: 'receiving_detail_id', + as: 'receivingDetail', + }); + }; + return InboundDirectLog; }; diff --git a/app/service/systemMethods/order/base.js b/app/service/systemMethods/order/base.js index ec97b04..d9abc80 100644 --- a/app/service/systemMethods/order/base.js +++ b/app/service/systemMethods/order/base.js @@ -1244,8 +1244,11 @@ class OrderBaseService extends MainService { order: [[ 'id', 'ASC' ]], raw: true, }); - const orderItemImagesByStockId = await this.getOrderItemImagesByStockIds(orderItems); - const orderItemsWithImages = this.attachImagesToOrderItems(orderItems, orderItemImagesByStockId); + + // 通过 getStockDetails(带缓存)批量查询 stock_warehouse 标准信息 + // 为 items 附加 image_url、barcodes、item_name 等标准字段 + const orderItemsWithStockInfo = await this.attachStockDetailsToOrderItems(orderItems, warehouseId); + const expresses = await this.getOrderExpressesByOrderId(orderId, order); const logs = await this.getOrderOperationLogs(orderId); @@ -1255,9 +1258,8 @@ class OrderBaseService extends MainService { : []; return { - order, detail: order, - items: orderItemsWithImages, + items: orderItemsWithStockInfo, expresses, waybill_codes: waybillCodes, logs, @@ -1265,93 +1267,205 @@ class OrderBaseService extends MainService { } /** - * 按订单商品批量查询图片并按 stock_id 建立映射。 + * 通过 stock_warehouse 带缓存的标准方法(getStockDetails),批量查询商品详情, + * 将 order_items 仅作为 stock_id 来源,返回 getStockDetails 标准格式数据。 + * 每个结果会附带以下 order_items 关键关联字段: + * - plan_qty:需求量 + * - order_line_no:行号 + * - stock_id:原 order_items 中的 stock_id 关联键 + * - order_item_id:原 order_items 主键 id,供下游(如 pendingOrder)关联使用 + * - order_id:所属订单 id + * * @param {Object[]} orderItems 订单商品列表。 - * @return {Promise>} stock_id 对应的图片 URL 列表。 + * @param {number|string} warehouseId 仓库ID。 + * @return {Promise} 以 stock_warehouse 标准格式为主,附带少量 order_items 关键字段的数据。 */ - async getOrderItemImagesByStockIds(orderItems = []) { + async attachStockDetailsToOrderItems(orderItems = [], warehouseId) { if (!Array.isArray(orderItems) || orderItems.length === 0) { - return new Map(); - } - - const stockIds = [ ...new Set( - orderItems - .map(item => Number(item && item.stock_id)) - .filter(Boolean) - ) ]; - - if (stockIds.length === 0) { - return new Map(); - } - - const fileReferenceModel = this.ctx.model && this.ctx.model.FileReference; - const fileModel = this.ctx.model && this.ctx.model.File; - if (!fileReferenceModel || typeof fileReferenceModel.findAll !== 'function' || !fileModel) { - return new Map(); - } - - try { - const fileReferences = await fileReferenceModel.findAll({ - where: { - business_type: 'stock', - business_id: { - [this.app.Sequelize.Op.in]: stockIds, - }, - }, - include: [{ - model: fileModel, - as: 'file', - attributes: [ 'file_url' ], - required: false, - }], - }); - - const imagesByStockId = new Map(); - for (const reference of fileReferences || []) { - const row = reference && typeof reference.get === 'function' - ? reference.get({ plain: true }) - : reference; - const stockId = Number(row && row.business_id); - const imageUrl = (row && row.file && row.file.file_url) || row?.file_url || row?.url || row?.file_path || ''; - - if (!stockId || !imageUrl) { - continue; - } - - if (!imagesByStockId.has(stockId)) { - imagesByStockId.set(stockId, []); - } - - imagesByStockId.get(stockId).push(String(imageUrl)); - } - - return imagesByStockId; - } catch (error) { - this.ctx.logger?.warn?.('[order.base.detail] 查询订单商品图片失败,已降级为空图片数组', { - error: error.message, - }); - return new Map(); - } - } - - /** - * 将图片映射合并到订单商品列表中。 - * @param {Object[]} orderItems 订单商品列表。 - * @param {Map} imagesByStockId 图片映射。 - * @return {Object[]} 合并后的订单商品列表。 - */ - attachImagesToOrderItems(orderItems = [], imagesByStockId = new Map()) { - if (!Array.isArray(orderItems)) { return []; } - return orderItems.map(item => { + // 构建 stockId → orderItem 关键字段的映射 + const stockIdToOrderItemMap = new Map(); + const stockIdsSet = new Set(); + for (const item of orderItems) { const stockId = Number(item && item.stock_id); - const images = stockId ? (imagesByStockId.get(stockId) || []) : []; + if (stockId) { + stockIdsSet.add(stockId); + // 同一个 stock_id 可能对应多条 order_items 行,保留最后一条的关键字段 + stockIdToOrderItemMap.set(stockId, { + plan_qty: item.plan_qty != null ? item.plan_qty : 0, + order_line_no: item.order_line_no || '', + stock_id: stockId, + order_item_id: item.id != null ? item.id : 0, + order_id: item.order_id != null ? item.order_id : 0, + }); + } + } + + const stockIds = [ ...stockIdsSet ]; + + if (stockIds.length === 0) { + return []; + } + + /** @type {Map} */ + const stockDetailMap = new Map(); + try { + const stockWarehouseSvc = this.ctx.service?.systems?.stockWarehouse; + if (stockWarehouseSvc && typeof stockWarehouseSvc.getStockDetails === 'function') { + const stockDetails = await stockWarehouseSvc.getStockDetails(stockIds, { warehouseId }); + for (const detail of stockDetails) { + stockDetailMap.set(Number(detail.id), detail); + } + } + } catch (error) { + this.ctx.logger?.warn?.('[order.base.attachStockDetailsToOrderItems] 查询 stock_warehouse 详情失败,已降级为原始 items', { + error: error.message, + }); + return []; + } + + // 降级:当 getStockDetails 缓存层没有返回某些 stockId 的数据时,直接查 DB 补齐 + const missedIds = stockIds.filter(sid => !stockDetailMap.has(sid)); + if (missedIds.length > 0) { + this.ctx.logger?.info?.('[order.base.attachStockDetailsToOrderItems] getStockDetails 未返回部分 stock 详情,降级为直接查 DB', { + missedIds, + warehouseId, + }); + try { + const { app } = this; + const [ fallbackStockRows, fallbackBarcodeRows, fallbackImageRows ] = await Promise.all([ + app.model.StockWarehouse.findAll({ + where: { id: { [app.Sequelize.Op.in]: missedIds }, is_valid: 'Y' }, + attributes: [ + 'id', 'item_code', 'item_name', 'sku_property', + 'quantity', 'locked_quantity', 'is_batch_mgmt', + 'is_shelf_life_mgmt', 'is_images', + 'store_id', 'packing_requirements', 'stock_unit', + ], + raw: true, + }), + app.model.StockBarcode.findAll({ + where: { stock_id: { [app.Sequelize.Op.in]: missedIds } }, + attributes: [ 'id', 'barcode', 'stock_id' ], + raw: true, + }), + app.model.FileReference.findAll({ + where: { + business_type: 'stock', + business_id: { [app.Sequelize.Op.in]: missedIds.map(String) }, + }, + include: [{ + model: app.model.File, + as: 'file', + attributes: [ 'file_url' ], + required: false, + }], + order: [[ 'display_order', 'ASC' ]], + raw: true, + }), + ]); + + const fallbackBarcodeMap = new Map(); + for (const row of fallbackBarcodeRows) { + const sid = row.stock_id; + if (!fallbackBarcodeMap.has(sid)) { + fallbackBarcodeMap.set(sid, []); + } + fallbackBarcodeMap.get(sid).push({ + id: row.id, + barcode: row.barcode, + }); + } + + const fallbackImageUrlMap = new Map(); + for (const row of fallbackImageRows) { + const sid = Number(row.business_id); + if (!fallbackImageUrlMap.has(sid)) { + fallbackImageUrlMap.set(sid, []); + } + const url = (row['file.file_url'] && String(row['file.file_url']).trim()) || ''; + if (url) { + fallbackImageUrlMap.get(sid).push(url); + } + } + + for (const row of fallbackStockRows) { + stockDetailMap.set(row.id, { + id: row.id, + item_code: row.item_code, + item_name: row.item_name, + sku_property: row.sku_property || '', + quantity: row.quantity || 0, + locked_quantity: row.locked_quantity || 0, + is_batch_mgmt: row.is_batch_mgmt || 'N', + is_shelf_life_mgmt: row.is_shelf_life_mgmt || 'N', + is_images: row.is_images || 'N', + store_id: row.store_id != null ? Number(row.store_id) : 0, + packing_requirements: row.packing_requirements || '', + stock_unit: row.stock_unit || '', + image_url: fallbackImageUrlMap.get(row.id) || [], + barcodes: fallbackBarcodeMap.get(row.id) || [], + }); + } + } catch (fallbackError) { + this.ctx.logger?.warn?.('[order.base.attachStockDetailsToOrderItems] 降级查询也失败', { + error: fallbackError.message, + }); + } + } + + // 以 getStockDetails 返回的标准格式为主, + // 仅从 order_items 中附加 plan_qty、order_line_no、stock_id、order_item_id、order_id 关键关联字段 + return stockIds.map(stockId => { + const stockDetail = stockDetailMap.get(stockId) || null; + const orderItemFields = stockIdToOrderItemMap.get(stockId) || {}; + + if (!stockDetail) { + return { + id: stockId, + item_code: '', + item_name: '', + sku_property: '', + quantity: 0, + locked_quantity: 0, + is_batch_mgmt: 'N', + is_shelf_life_mgmt: 'N', + is_images: 'N', + store_id: 0, + packing_requirements: '', + stock_unit: '', + image_url: [], + barcodes: [], + plan_qty: orderItemFields.plan_qty || 0, + order_line_no: orderItemFields.order_line_no || '', + stock_id: orderItemFields.stock_id || stockId, + order_item_id: orderItemFields.order_item_id || 0, + order_id: orderItemFields.order_id || 0, + }; + } return { - ...item, - images: [ ...images ], + id: stockDetail.id, + item_code: stockDetail.item_code || '', + item_name: stockDetail.item_name || '', + sku_property: stockDetail.sku_property || '', + quantity: stockDetail.quantity != null ? stockDetail.quantity : 0, + locked_quantity: stockDetail.locked_quantity != null ? stockDetail.locked_quantity : 0, + is_batch_mgmt: stockDetail.is_batch_mgmt || 'N', + is_shelf_life_mgmt: stockDetail.is_shelf_life_mgmt || 'N', + is_images: stockDetail.is_images || 'N', + store_id: stockDetail.store_id != null ? Number(stockDetail.store_id) : 0, + packing_requirements: stockDetail.packing_requirements || '', + stock_unit: stockDetail.stock_unit || '', + image_url: Array.isArray(stockDetail.image_url) ? [ ...stockDetail.image_url ] : [], + barcodes: Array.isArray(stockDetail.barcodes) ? [ ...stockDetail.barcodes ] : [], + plan_qty: orderItemFields.plan_qty || 0, + order_line_no: orderItemFields.order_line_no || '', + stock_id: orderItemFields.stock_id || stockId, + order_item_id: orderItemFields.order_item_id || 0, + order_id: orderItemFields.order_id || 0, }; }); } diff --git a/app/service/systemMethods/order/pendingOrder.js b/app/service/systemMethods/order/pendingOrder.js index 8fa822e..ca5c730 100644 --- a/app/service/systemMethods/order/pendingOrder.js +++ b/app/service/systemMethods/order/pendingOrder.js @@ -564,30 +564,26 @@ class PendingOrderService extends OrderBaseService { order: [[ 'id', 'ASC' ]], raw: true, }); - const orderItemImagesByStockId = await this.getOrderItemImagesByStockIds(orderItems); - const orderItemsWithImages = this.attachImagesToOrderItems(orderItems, orderItemImagesByStockId); - // 收集订单明细中的 stock_id,用于查询商品库存主表信息 - const stockIds = [ ...new Set( - orderItems.map(item => Number(item && item.stock_id)).filter(Boolean) - ) ]; - const stockMap = new Map(); - if (stockIds.length > 0) { - const stockDetails = await this.ctx.service.systems.stockWarehouse.getStockDetails( - stockIds, - { warehouseId } - ); - for (const detail of stockDetails) { - stockMap.set(detail.id, detail); - } - } + // 通过 getStockDetails(带缓存)批量查询 stock_warehouse 标准信息 + // 返回以 stock_warehouse 格式为主、附带 plan_qty / order_line_no / stock_id / order_item_id / order_id 的数据 + const orderItemsWithImages = await this.attachStockDetailsToOrderItems(orderItems, warehouseId); - // 构建 order_item_id → orderItem 的快速查找映射 + // 构建 order_item_id → orderItem 的快速查找映射(仍基于原始 order_items) const orderItemMap = new Map(); for (const item of orderItems) { orderItemMap.set(item.id, item); } + // 构建 stockMap:直接从 attachStockDetailsToOrderItems(已是 stock_warehouse 格式)中按 stock_id 建立映射 + const stockMap = new Map(); + for (const item of orderItemsWithImages) { + const stockId = Number(item.stock_id); + if (stockId) { + stockMap.set(stockId, item); + } + } + // 查询已分配的储位信息(排除已取消的分配记录) const orderItemIds = orderItems.map(item => item.id).filter(Boolean); const pickingMap = new Map(); @@ -642,7 +638,7 @@ class PendingOrderService extends OrderBaseService { } const orderItemsWithPicking = orderItemsWithImages.map(item => ({ ...item, - picking_locations: pickingMap.get(item.id) || [], + picking_locations: pickingMap.get(item.order_item_id) || [], })); const expresses = await this.getOrderExpressesByOrderId(orderId, order); diff --git a/app/service/systemMethods/storage/direct_inbound.js b/app/service/systemMethods/storage/direct_inbound.js deleted file mode 100644 index 651de7d..0000000 --- a/app/service/systemMethods/storage/direct_inbound.js +++ /dev/null @@ -1,71 +0,0 @@ -'use strict'; -const MainService = require('../../main'); -/** - * 系统方法层:storage.directInbound(导入/PDA直接入库相关接口包装层)。 - * 主要职责:统一包装系统方法接口,处理权限、日志等公共逻辑,调用底层 service 实现业务功能。 - */ -class DirectInboundService extends MainService { - constructor(ctx) { - super(ctx); - const _noNeedLogin = ''; - const _noNeedRight = 'getItems,addItem,removeItem,commit'; - const _noNeedLog = 'getItems'; - const _noNeedAuth = 'getItems,addItem,removeItem,commit'; - this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth); - } - - /** - * 获取入库单的导入/PDA 入库信息。 - * @param {Object} data 请求体 - * @param {string} data.entry_order_code 入库单号 - * @return {Promise} 统一成功包装响应 - */ - async getItems(data = {}) { - const { service } = this; - const { entry_order_code } = data || {}; - const result = await service.systems.inboundDirectLog.getItems(entry_order_code); - return this.success('ok', result); - } - - /** - * 按商品增量添加导入/PDA 入库记录。 - * @param {Object} data 请求体 - * @param {number} data.entry_order_id 入库单 ID - * @param {number} data.stock_id 商品SKU ID - * @param {number} data.quantity 入库数量 - * @param {string} data.inbound_type 入库方式:import 或 pda - * @param {string} [data.remark] 备注 - * @return {Promise} 统一成功包装响应 - */ - async addItem(data = {}) { - const { service } = this; - const result = await service.systems.inboundDirectLog.addItem(data); - return this.success('ok', result); - } - - /** - * 提交确认完成导入/PDA 入库,写入库存并触发奇门/API 回传。 - * @param {Object} data 请求体 - * @param {number} data.entry_order_id 入库单 ID - * @return {Promise} 统一成功包装响应 - */ - async commit(data = {}) { - const { service } = this; - const { entry_order_id } = data || {}; - const result = await service.systems.inboundDirectLog.commit(entry_order_id); - return this.success('ok', result); - } - - /** - * 移除一条导入/PDA 入库记录。 - * @param {Object} data 请求体 - * @param {number} data.id 入库记录ID - * @return {Promise} 统一成功包装响应 - */ - async removeItem(data = {}) { - const { service } = this; - const result = await service.systems.inboundDirectLog.removeItem(data); - return this.success('ok', result); - } -} -module.exports = DirectInboundService; diff --git a/app/service/systemMethods/storage/entry.js b/app/service/systemMethods/storage/entry.js index cf25099..e82a358 100644 --- a/app/service/systemMethods/storage/entry.js +++ b/app/service/systemMethods/storage/entry.js @@ -38,10 +38,9 @@ class entryService extends MainService { } /** - * 查询入库单详情。 + * 查询入库单详情。仅通过入库单 ID 定位。 * @param {Object} data 请求体 - * @param {number} [data.id] 入库单ID - * @param {string} [data.entry_order_code] 入库单号 + * @param {number} data.id 入库单ID(必填) * @return {Promise} 统一 success 包装 */ async get(data = {}) { @@ -64,19 +63,6 @@ class entryService extends MainService { return this.success('ok', result); } - /** - * 获取入库单的导入/PDA 直接入库信息(从 storage.entry 模块暴露)。 - * @param {Object} data 请求体 - * @param {string} data.entry_order_code 入库单号 - * @return {Promise} 统一 success 包装 - */ - async getDirectInboundItems(data = {}) { - const { service } = this; - const { entry_order_code } = data || {}; - const result = await service.systems.inboundDirectLog.getItems(entry_order_code); - return this.success('ok', result); - } - /** * 按商品增量添加导入/PDA 直接入库记录(从 storage.entry 模块暴露)。 * @param {Object} data 请求体 diff --git a/app/service/systems/inbound_direct_log.js b/app/service/systems/inbound_direct_log.js index 31d9991..13087e2 100644 --- a/app/service/systems/inbound_direct_log.js +++ b/app/service/systems/inbound_direct_log.js @@ -15,27 +15,21 @@ class InboundDirectLogService extends Service { /** * 获取入库单的受控入库信息(精简版)。 * 返回入库单基本信息、明细列表(含计划数量与已完成数量)、收货单绑定关系。 - * @param {string} entryOrderCode 入库单号 + * @param {number} entryOrderId 入库单ID(必填) * @return {Promise} code/data/message 结构 * - data.entryOrder: { id, entry_order_code, order_status, store_remask } * - data.items: [{ id, stock_id, planned, completed, stock, bindings }] * - data.receivingBindings: 收货单绑定关系列表 */ - async getItems(entryOrderCode) { + async getItems(entryOrderId) { const { ctx, app } = this; - const code = String(entryOrderCode || '').trim(); + const id = Number(entryOrderId || 0); - if (!code) { - return { code: 400, message: 'entry_order_code 必填', data: null }; + if (!id) { + return { code: 400, message: 'id 参数不能为空', data: null }; } - const entryOrder = await ctx.model.EntryOrder.findOne({ - where: { - entry_order_code: code, - warehouse_id: ctx.user.store_id, - is_enabled: 1, - deleted_at: null, - }, + const entryOrder = await ctx.model.EntryOrder.findByPk(id, { include: [ { model: ctx.model.EntryItems, @@ -67,6 +61,11 @@ class InboundDirectLogService extends Service { }); if (!entryOrder) { + return { code: 404, message: '入库单不存在', data: null }; + } + + // 校验仓库权限 + if (entryOrder.warehouse_id !== ctx.user.store_id || !entryOrder.is_enabled) { return { code: 404, message: '入库单不存在或无权访问', data: null }; } @@ -171,13 +170,14 @@ class InboundDirectLogService extends Service { /** @type {Map>} 按 entry_item_id 分组 */ const bindingsMap = new Map(); if (entryItemIds.length > 0) { - // 1. 查绑定关系表 - const bindingRows = await ctx.model.EntryReceivingBinding.findAll({ + // 1. 查绑定关系表(从 InboundDirectLog 中筛选有 receiving_detail_id 的记录) + const bindingRows = await ctx.model.InboundDirectLog.findAll({ where: { entry_item_id: { [app.Sequelize.Op.in]: entryItemIds }, + receiving_detail_id: { [app.Sequelize.Op.ne]: null }, deleted_at: null, }, - attributes: [ 'id', 'entry_item_id', 'receiving_detail_id', 'allocated_quantity', 'status' ], + attributes: [ 'id', 'entry_item_id', 'receiving_detail_id', 'quantity', 'status' ], raw: true, }); @@ -205,7 +205,7 @@ class InboundDirectLogService extends Service { bindingsMap.get(key).push({ detail_id: b.receiving_detail_id, binding_id: b.id, - allocated_quantity: b.allocated_quantity || 0, + allocated_quantity: b.quantity || 0, }); } } @@ -310,10 +310,10 @@ class InboundDirectLogService extends Service { return { ok: false, error: { code: 400, message: `收货明细的商品(system_product_id=${receivingDetail.system_product_id})与传入的 stock_id(${stockId})不匹配` } }; } - // 查询该收货明细已被占用的数量(pending + committed) + // 查询该收货明细已被占用的数量(pending + committed),从 InboundDirectLog 查 const allocatedSum = await ctx.model.query( - `SELECT COALESCE(SUM(allocated_quantity), 0) AS total - FROM wms_entry_receiving_binding + `SELECT COALESCE(SUM(quantity), 0) AS total + FROM wms_inbound_direct_log WHERE receiving_detail_id = :rdId AND status IN ('pending', 'committed') AND deleted_at IS NULL`, { replacements: { rdId: receivingDetailId }, @@ -431,7 +431,7 @@ class InboundDirectLogService extends Service { /** * 将入库直接记录绑定到收货单明细(预占模式,status='pending')。 - * 校验收货明细存在、未取消、可用数量足够后,写入 wms_entry_receiving_binding 并确保主表绑定存在。 + * 校验收货明细存在、未取消、可用数量足够后,写入 wms_inbound_direct_log 并确保主表绑定存在。 * @param {Object} ctx Egg.js 上下文对象 * @param {Object} entryOrder 入库单实例 * @param {Object} item 入库项参数,包含 allocated_quantity、item_code 等可选字段 @@ -463,10 +463,10 @@ class InboundDirectLogService extends Service { return { error: `收货明细不存在(id=${receivingDetailId})` }; } - // 2. 查询已占用(pending + committed)的分配量 + // 2. 查询已占用(pending + committed)的分配量,从 InboundDirectLog 查 const allocatedSum = await ctx.model.query( - `SELECT COALESCE(SUM(allocated_quantity), 0) AS total - FROM wms_entry_receiving_binding + `SELECT COALESCE(SUM(quantity), 0) AS total + FROM wms_inbound_direct_log WHERE receiving_detail_id = :rdId AND status IN ('pending', 'committed') AND deleted_at IS NULL`, { replacements: { rdId: receivingDetailId }, @@ -493,13 +493,22 @@ class InboundDirectLogService extends Service { ...(transaction ? { transaction } : {}), }); - // 4. 写入绑定(status='pending',预占不提交) - const binding = await ctx.model.EntryReceivingBinding.create({ + // 4. 写入绑定到 InboundDirectLog(status='pending',预占不提交) + const binding = await ctx.model.InboundDirectLog.create({ + warehouse_id: entryOrder.warehouse_id, + store_id: entryOrder.store_id, + stock_id: stockId, + quantity: allocatedQty, + inbound_type: item.inbound_type || 'import', + entry_order_id: entryOrder.id, + entry_order_code: entryOrder.entry_order_code, entry_item_id: entryItem?.id || 0, receiving_detail_id: receivingDetailId, - allocated_quantity: allocatedQty, + space_id: item.space_id ? Number(item.space_id) : null, status: 'pending', creator_id: ctx.user?.id || 0, + operator_id: ctx.user?.employees_id || ctx.user?.id || null, + operator_name: ctx.user?.employees_name || '', }, transaction ? { transaction } : {}); return { @@ -819,10 +828,15 @@ class InboundDirectLogService extends Service { try { const processedStockIds = new Set(); - // 查询 pending 绑定:entry_item_id → 收货明细ID + // 查询 pending 绑定:entry_item_id → 收货明细ID(从 InboundDirectLog 查) const entryItemIds = entryItems.map(ei => ei.id); - const pendingBindings = await ctx.model.EntryReceivingBinding.findAll({ - where: { entry_item_id: entryItemIds, status: 'pending', deleted_at: null }, + const pendingBindings = await ctx.model.InboundDirectLog.findAll({ + where: { + entry_item_id: { [app.Sequelize.Op.in]: entryItemIds }, + receiving_detail_id: { [app.Sequelize.Op.ne]: null }, + status: 'pending', + deleted_at: null, + }, attributes: [ 'id', 'entry_item_id', 'receiving_detail_id' ], raw: true, }); @@ -1007,9 +1021,9 @@ class InboundDirectLogService extends Service { }, { transaction }); } - // 将 pending 绑定升级为 committed + // 将 pending 绑定升级为 committed(在 InboundDirectLog 中更新状态) if (pendingBindings.length > 0) { - await ctx.model.EntryReceivingBinding.update( + await ctx.model.InboundDirectLog.update( { status: 'committed', updated_at: new Date() }, { where: { id: pendingBindings.map(b => b.id) }, transaction } ); @@ -1425,16 +1439,17 @@ class InboundDirectLogService extends Service { * @return {Promise} */ async _syncReceivingStorageStatus({ entryItemIds, transaction }) { - const { ctx } = this; + const { ctx, app } = this; - // 查询所有 committed 状态的绑定记录 - const committedBindings = await ctx.model.EntryReceivingBinding.findAll({ + // 查询所有 committed 状态的绑定记录(从 InboundDirectLog 中筛选有 receiving_detail_id 的记录) + const committedBindings = await ctx.model.InboundDirectLog.findAll({ where: { - entry_item_id: entryItemIds, + entry_item_id: { [app.Sequelize.Op.in]: entryItemIds }, + receiving_detail_id: { [app.Sequelize.Op.ne]: null }, status: 'committed', deleted_at: null, }, - attributes: [ 'receiving_detail_id', 'allocated_quantity' ], + attributes: [ 'receiving_detail_id', 'quantity' ], raw: true, transaction, }); @@ -1443,11 +1458,11 @@ class InboundDirectLogService extends Service { return; } - // 按 receiving_detail_id 汇总 allocated_quantity + // 按 receiving_detail_id 汇总 quantity const detailQuantityMap = new Map(); for (const b of committedBindings) { const detailId = b.receiving_detail_id; - const qty = Number(b.allocated_quantity) || 0; + const qty = Number(b.quantity) || 0; detailQuantityMap.set(detailId, (detailQuantityMap.get(detailId) || 0) + qty); } diff --git a/app/service/systems/receiving_entry_match.js b/app/service/systems/receiving_entry_match.js index 37b1538..0bc101e 100644 --- a/app/service/systems/receiving_entry_match.js +++ b/app/service/systems/receiving_entry_match.js @@ -963,10 +963,10 @@ class ReceivingEntryMatchService extends Service { }; } - // 3. 查已 committed 的分配量 + // 3. 查已 committed 的分配量(从 InboundDirectLog 查) const allocatedSum = await ctx.model.query( - `SELECT COALESCE(SUM(allocated_quantity), 0) AS total - FROM wms_entry_receiving_binding + `SELECT COALESCE(SUM(quantity), 0) AS total + FROM wms_inbound_direct_log WHERE receiving_detail_id = :rdId AND status = 'committed' AND deleted_at IS NULL`, { replacements: { rdId: receivingDetailId }, @@ -983,16 +983,34 @@ class ReceivingEntryMatchService extends Service { }; } - // 4. 写入明细绑定 - await ctx.model.EntryReceivingBinding.create({ + // 4. 获取入库单信息以写入 InboundDirectLog + const entryOrder = await ctx.model.EntryOrder.findByPk(entryOrderId, { transaction }); + if (!entryOrder) { + throw { + error_code: 'ENTRY_ORDER_NOT_FOUND', + message: '入库单不存在', + detail: { entry_order_id: entryOrderId }, + }; + } + + // 5. 写入明细绑定到 InboundDirectLog + await ctx.model.InboundDirectLog.create({ + warehouse_id: entryOrder.warehouse_id, + store_id: entryOrder.store_id, + stock_id: expectedSpId || 0, + quantity: qty, + inbound_type: 'import', + entry_order_id: entryOrderId, + entry_order_code: entryOrder.entry_order_code, entry_item_id: entryItemId, receiving_detail_id: receivingDetailId, - allocated_quantity: qty, status: 'committed', creator_id: ctx.currentUser?.id || 0, + operator_id: ctx.currentUser?.employees_id || ctx.currentUser?.id || null, + operator_name: ctx.currentUser?.employees_name || '', }, { transaction }); - // 5. 确保主级绑定存在 + // 6. 确保主级绑定存在 await ctx.model.EntryOrderReceiving.findOrCreate({ where: { entry_order_id: entryOrderId, receiving_id: lockedDetail[0].receiving_id }, defaults: { entry_order_id: entryOrderId, receiving_id: lockedDetail[0].receiving_id }, @@ -1082,9 +1100,11 @@ class ReceivingEntryMatchService extends Service { continue; } - // 2b. 查明细绑定是否存在 - const detailBindings = await ctx.model.EntryReceivingBinding.findAll({ + // 2b. 查明细绑定是否存在(从 InboundDirectLog 查 receiving_detail_id 非空的记录) + const detailBindings = await ctx.model.InboundDirectLog.findAll({ where: { + entry_order_id: entryOrderId, + receiving_detail_id: { [ctx.app.Sequelize.Op.ne]: null }, status: 'committed', deleted_at: null, }, @@ -1095,7 +1115,7 @@ class ReceivingEntryMatchService extends Service { attributes: [], where: { receiving_id: receivingId }, }], - attributes: [ 'id', 'receiving_detail_id', 'allocated_quantity' ], + attributes: [ 'id', 'receiving_detail_id', 'quantity' ], }); if (detailBindings.length === 0) { diff --git a/app/service/systems/storage/entry.js b/app/service/systems/storage/entry.js index 2c74639..cff056d 100644 --- a/app/service/systems/storage/entry.js +++ b/app/service/systems/storage/entry.js @@ -503,34 +503,28 @@ class EntryService extends Service { /** * 查询入库单详情,含商品信息、条码、入库进度。 * @param {Object} data 请求参数 - * @param {number} [data.id] 入库单主键 ID - * @param {string} [data.entry_order_code] 入库单号 + * @param {number} data.id 入库单主键 ID(必填) * @return {Promise} code/data/message 结构,data.entryOrder 为扁平化后的入库单详情 */ async get(data = {}) { const { ctx } = this; const id = Number(data.id || 0); - const entryOrderCode = data.entry_order_code ? String(data.entry_order_code).trim() : ''; const warehouseId = ctx.user.store_id; - if (!id && !entryOrderCode) { + if (!id) { return { code: 400, - message: 'id 或 entry_order_code 至少传一个', + message: 'id 参数不能为空', data: null, }; } const where = { + id, warehouse_id: warehouseId, is_enabled: 1, deleted_at: null, }; - if (id) { - where.id = id; - } else { - where.entry_order_code = entryOrderCode; - } const entryOrder = await ctx.model.EntryOrder.findOne({ where, @@ -705,11 +699,11 @@ class EntryService extends Service { rd.system_product_id, r.receiving_number, rd.actual_quantity, - COALESCE(SUM(erb.allocated_quantity), 0) AS allocated_quantity, - rd.actual_quantity - COALESCE(SUM(erb.allocated_quantity), 0) AS available_quantity + COALESCE(SUM(erb.quantity), 0) AS allocated_quantity, + rd.actual_quantity - COALESCE(SUM(erb.quantity), 0) AS available_quantity FROM wms_receiving_detail rd INNER JOIN wms_receiving r ON r.id = rd.receiving_id AND r.is_deleted = false - LEFT JOIN wms_entry_receiving_binding erb + LEFT JOIN wms_inbound_direct_log erb ON erb.receiving_detail_id = rd.id AND erb.status = 'committed' AND erb.deleted_at IS NULL @@ -987,15 +981,6 @@ class EntryService extends Service { } } - /** - * 获取入库单的导入/PDA 直接入库信息(转发到 inboundDirectLog)。 - * @param {string} entryOrderCode 入库单号 - * @return {Promise} code/data/message 结构 - */ - async getDirectInboundItems(entryOrderCode) { - const { ctx } = this; - return await ctx.service.systems.inboundDirectLog.getItems(entryOrderCode); - } /** * 按商品增量添加导入/PDA 直接入库记录(转发到 inboundDirectLog)。 @@ -1084,8 +1069,8 @@ class EntryService extends Service { const usedMap = new Map(); if (detailIds.length > 0) { const usedRows = await ctx.model.query( - `SELECT receiving_detail_id, COALESCE(SUM(allocated_quantity), 0) AS used_qty - FROM wms_entry_receiving_binding + `SELECT receiving_detail_id, COALESCE(SUM(quantity), 0) AS used_qty + FROM wms_inbound_direct_log WHERE receiving_detail_id IN (:ids) AND status IN ('pending', 'committed') AND deleted_at IS NULL @@ -1170,9 +1155,9 @@ class EntryService extends Service { return { code: 200, message: 'ok', data: { list: [], total: 0 } }; } - // 3. 排除已绑定的收货明细(wms_entry_receiving_binding 中有记录且未软删除) + // 3. 排除已绑定的收货明细(wms_inbound_direct_log 中有记录且未软删除) const notBoundCondition = app.Sequelize.literal( - 'NOT EXISTS (SELECT 1 FROM wms_entry_receiving_binding erb WHERE erb.receiving_detail_id = wms_receiving_detail.id AND erb.deleted_at IS NULL)' + 'NOT EXISTS (SELECT 1 FROM wms_inbound_direct_log erb WHERE erb.receiving_detail_id = wms_receiving_detail.id AND erb.deleted_at IS NULL)' ); // 4. 查询指定商品的未绑定收货明细 @@ -1695,10 +1680,10 @@ class EntryService extends Service { const entryItemIds = entryItems.map(ei => ei.id); const allocatedMap = new Map(); if (receivingDetailIds.length > 0 && entryItemIds.length > 0) { - const bindingRows = await ctx.model.EntryReceivingBinding.findAll({ + const bindingRows = await ctx.model.InboundDirectLog.findAll({ attributes: [ 'receiving_detail_id', - [ app.Sequelize.fn('SUM', app.Sequelize.col('allocated_quantity')), 'total_allocated' ], + [ app.Sequelize.fn('SUM', app.Sequelize.col('quantity')), 'total_allocated' ], ], where: { entry_item_id: { [app.Sequelize.Op.in]: entryItemIds }, diff --git a/app/service/systems/storage/receiving.js b/app/service/systems/storage/receiving.js index cc93682..9a65a2b 100644 --- a/app/service/systems/storage/receiving.js +++ b/app/service/systems/storage/receiving.js @@ -218,10 +218,10 @@ class ReceivingService extends Service { const committedByDetailId = {}; if (detailIds.length > 0) { - const bindingRows = await ctx.model.EntryReceivingBinding.findAll({ + const bindingRows = await ctx.model.InboundDirectLog.findAll({ attributes: [ 'receiving_detail_id', - [ Sequelize.fn('SUM', Sequelize.col('allocated_quantity')), 'committed_sum' ], + [ Sequelize.fn('SUM', Sequelize.col('quantity')), 'committed_sum' ], ], where: { receiving_detail_id: { [Op.in]: detailIds }, @@ -4416,9 +4416,9 @@ class ReceivingService extends Service { return { code: 0, message: '该入库单尚未关联收货单', data: null }; } - // 排除已绑定的收货明细(wms_entry_receiving_binding 中有记录且未软删除) + // 排除已绑定的收货明细(wms_inbound_direct_log 中有记录且未软删除) const notBoundCondition = app.Sequelize.literal( - 'NOT EXISTS (SELECT 1 FROM wms_entry_receiving_binding erb WHERE erb.receiving_detail_id = wms_receiving_detail.id AND erb.deleted_at IS NULL)' + 'NOT EXISTS (SELECT 1 FROM wms_inbound_direct_log erb WHERE erb.receiving_detail_id = wms_receiving_detail.id AND erb.deleted_at IS NULL)' ); // 3. 查出所有未绑定的收货明细(不再在 SQL 层做 barcode 模糊匹配) diff --git a/database/migrations/20260702-add-lock-unlock-to-wms-storage-transaction.js b/database/migrations/20260702-add-lock-unlock-to-wms-storage-transaction.js index 3c0b67b..dd0c5df 100644 --- a/database/migrations/20260702-add-lock-unlock-to-wms-storage-transaction.js +++ b/database/migrations/20260702-add-lock-unlock-to-wms-storage-transaction.js @@ -6,8 +6,9 @@ * UNLOCK:取消分配储位解锁 */ module.exports = { - async up(db) { - await db.query(` + async up(queryInterface) { + const { sequelize } = queryInterface; + await sequelize.query(` ALTER TABLE wms_storage_transaction MODIFY COLUMN transaction_type ENUM( 'INBOUND', 'OUTBOUND', 'TRANSFER_OUT', 'TRANSFER_IN', 'LOCK', 'UNLOCK' @@ -15,8 +16,9 @@ module.exports = { `); }, - async down(db) { - await db.query(` + async down(queryInterface) { + const { sequelize } = queryInterface; + await sequelize.query(` ALTER TABLE wms_storage_transaction MODIFY COLUMN transaction_type ENUM( 'INBOUND', 'OUTBOUND', 'TRANSFER_OUT', 'TRANSFER_IN' diff --git a/database/migrations/20260702-fix-receipt-a5-template.js b/database/migrations/20260702-fix-receipt-a5-template.js deleted file mode 100644 index b8370df..0000000 --- a/database/migrations/20260702-fix-receipt-a5-template.js +++ /dev/null @@ -1,310 +0,0 @@ -'use strict'; - -/** - * 入库单 A5 默认打印模板(ENTRY_ORDER 业务类型)。 - * - * 严格参照出库单"拣货单A5模板"(id=18)的格式与渲染引擎约定: - * - 标签元素(纯文字)使用 custom: true + content + 扁平化样式属性 - * - 数据元素使用 field_code(无 custom)+ 扁平化样式属性 - * - 分割线使用 line 类型 - * - 表格使用 table 类型,rows 数组每项为列定义对象(type: "text", field_code, content, width 等) - * - 字体大小使用 fontSize(字符串类型,如 "10") - * - 加粗使用 bold(布尔类型) - * - textAlign 用于对齐 - * - * 模板布局(A5 148mm×210mm): - * 1. 标题:"入 库 单"(fontSize: 18, bold: true, textAlign: center) - * 2. 分割线 - * 3. 信息区(标签+字段模式,每行左右两列): - * 入库单号:entry_order_code | 业务类型:order_type - * 供应商:supplier_name | 采购单号:purchase_order_code - * 仓库:warehouse_name | 货主:store_name - * 物流公司:logistics_name | 运单号:express_code - * 创建时间:order_create_time | 预期到货:expect_start_time - * 4. 分割线 - * 5. 入库明细标题 - * 6. 表格(6列):商品编码、商品名称、条码、计划数量、已收数量、库存类型 - * - 每列为 type: "text" 的扁平对象(参照 id=18 格式) - * 7. 分割线 - * 8. 单据总行数:total_order_lines - * 9. 备注:remark - * 10. 二维码:entry_order_code - * 11. 打印时间:print_time - */ - -const TABLE = 'wms_print_template'; - -// 基于时间戳生成唯一元素 ID 前缀 -const TS_BASE = Date.now(); - -/** - * 生成模板元素唯一 ID。 - * @param {string} type 元素类型前缀(text/line/table/barcode/qrcode) - * @param {number} seq 序号 - * @return {string} 唯一 ID - */ -function makeId(type, seq) { - return `${type}_${TS_BASE}_${String(seq).padStart(4, '0')}`; -} - -/** - * 生成 text 类型标签元素(纯文字标签,如"入库单号:"),有 custom: true。 - * @param {number} seq 序号 - * @param {number} top 顶部位置(mm) - * @param {number} left 左侧位置(mm) - * @param {number} width 宽度(mm) - * @param {number} height 高度(mm) - * @param {string} content 文字内容 - * @param {string} fontSize 字体大小(字符串类型) - * @param {object} options 可选配置 { bold, textAlign } - * @return {object} 标签元素 - */ -function label(seq, top, left, width, height, content, fontSize, options = {}) { - return { - id: makeId('text', seq), - type: 'text', - top, - left, - width, - height, - custom: true, - content, - fontSize, - bold: options.bold || false, - italic: false, - underline: false, - rotate: 0, - textAlign: options.textAlign || 'left', - lineHeight: height, - }; -} - -/** - * 生成 text 类型数据字段元素(绑定 field_code),无 custom。 - * @param {number} seq 序号 - * @param {number} top 顶部位置(mm) - * @param {number} left 左侧位置(mm) - * @param {number} width 宽度(mm) - * @param {number} height 高度(mm) - * @param {string} fieldCode 字段编码 - * @param {string} fontSize 字体大小(字符串类型) - * @param {object} options 可选配置 { bold, textAlign } - * @return {object} 数据字段元素 - */ -function field(seq, top, left, width, height, fieldCode, fontSize, options = {}) { - return { - id: makeId('text', seq), - type: 'text', - top, - left, - width, - height, - field_code: fieldCode, - fontSize, - bold: options.bold || false, - italic: false, - underline: false, - rotate: 0, - textAlign: options.textAlign || 'left', - lineHeight: height, - }; -} - -/** - * 生成分割线元素。 - * @param {number} seq 序号 - * @param {number} top 顶部位置(mm) - * @param {number} left 左侧位置(mm) - * @param {number} width 宽度(mm) - * @param {number} height 高度(mm) - * @return {object} 分割线元素 - */ -function lineEl(seq, top, left, width, height) { - return { - id: makeId('line', seq), - type: 'line', - top, - left, - width, - height, - }; -} - -/** - * 生成二维码元素。 - * @param {number} seq 序号 - * @param {number} top 顶部位置(mm) - * @param {number} left 左侧位置(mm) - * @param {number} width 宽度(mm) - * @param {number} height 高度(mm) - * @param {string} fieldCode 字段编码 - * @param {string} fontSize 字体大小 - * @return {object} 二维码元素 - */ -function qrcodeEl(seq, top, left, width, height, fieldCode, fontSize) { - return { - id: makeId('qrcode', seq), - type: 'qrcode', - top, - left, - width, - height, - field_code: fieldCode, - fontSize, - bold: false, - italic: false, - underline: false, - rotate: 0, - textAlign: 'center', - lineHeight: 6, - }; -} - -/** - * 生成表格列定义(严格参照 id=18 rows 格式)。 - * 每项为 type: "text" 的扁平对象,同时包含 field_code、content(中文表头)、width、样式属性。 - * @param {number} seq 序号 - * @param {string} fieldCode 字段编码 - * @param {string} content 中文表头内容 - * @param {number} colWidth 列宽(mm) - * @param {string} fontSize 字体大小 - * @param {boolean} bold 是否加粗 - * @param {string} textAlign 对齐方式 - * @return {object} 列定义对象 - */ -function tableColumn(seq, fieldCode, content, colWidth, fontSize, bold, textAlign) { - return { - id: makeId('text', seq), - type: 'text', - field_code: fieldCode, - content, - width: colWidth, - height: 6, - fontSize, - bold: bold || false, - italic: false, - underline: false, - rotate: 0, - textAlign: textAlign || 'left', - lineHeight: 6, - }; -} - -// ─── 构建入库单 A5 模板元素数组 ───────────────────────────── - -const templateContent = [ - - // 1. 标题:入 库 单 - label(1, 6, 0, 148, 10, '入 库 单', '18', { bold: true, textAlign: 'center' }), - - // 2. 分割线 - lineEl(2, 18, 10, 128, 0.5), - - // 3. 信息区 - 第一行:入库单号 | 业务类型 - label(3, 21, 10, 26, 7, '入库单号:', '10'), - field(4, 21, 36, 46, 7, 'entry_order_code', '10'), - label(5, 21, 84, 20, 7, '业务类型:', '10'), - field(6, 21, 104, 34, 7, 'order_type', '10'), - - // 3. 信息区 - 第二行:供应商 | 采购单号 - label(7, 29, 10, 20, 7, '供应商:', '10'), - field(8, 29, 30, 52, 7, 'supplier_name', '10'), - label(9, 29, 84, 26, 7, '采购单号:', '10'), - field(10, 29, 110, 28, 7, 'purchase_order_code', '10'), - - // 3. 信息区 - 第三行:仓库 | 货主 - label(11, 37, 10, 18, 7, '仓库:', '10'), - field(12, 37, 28, 54, 7, 'warehouse_name', '10'), - label(13, 37, 84, 18, 7, '货主:', '10'), - field(14, 37, 102, 36, 7, 'store_name', '10'), - - // 3. 信息区 - 第四行:物流公司 | 运单号 - label(15, 45, 10, 26, 7, '物流公司:', '10'), - field(16, 45, 36, 46, 7, 'logistics_name', '10'), - label(17, 45, 84, 20, 7, '运单号:', '10'), - field(18, 45, 104, 34, 7, 'express_code', '10'), - - // 3. 信息区 - 第五行:创建时间 | 预期到货 - label(19, 53, 10, 26, 7, '创建时间:', '10'), - field(20, 53, 36, 46, 7, 'order_create_time', '10'), - label(21, 53, 84, 26, 7, '预期到货:', '10'), - field(22, 53, 110, 28, 7, 'expect_start_time', '10'), - - // 4. 分割线 - lineEl(23, 62, 10, 128, 0.5), - - // 5. 入库明细标题 - label(24, 65, 10, 128, 7, '入库明细', '11', { bold: true, textAlign: 'left' }), - - // 6. 表格(严格参照 id=18 rows 格式:每列为 type: "text" 对象) - { - id: makeId('table', 25), - type: 'table', - top: 74, - left: 10, - width: 128, - height: 75, - rowHeight: 6, - headerHeight: 6, - rows: [ - tableColumn(26, 'item_code', '商品编码', 22, '9', false, 'left'), - tableColumn(27, 'item_name', '商品名称', 40, '9', false, 'left'), - tableColumn(28, 'item_barcode', '条码', 22, '9', false, 'left'), - tableColumn(29, 'plan_qty', '计划数量', 18, '9', false, 'left'), - tableColumn(30, 'received_qty', '已收数量', 18, '9', false, 'left'), - tableColumn(31, 'inventory_type', '库存类型', 8, '9', false, 'left'), - ], - }, - - // 7. 分割线 - lineEl(32, 151, 10, 128, 0.5), - - // 8. 单据总行数 - label(33, 155, 64, 26, 7, '单据总行数:', '9'), - field(34, 155, 90, 48, 7, 'total_order_lines', '9'), - - // 9. 备注 - label(35, 164, 10, 14, 7, '备注:', '9'), - field(36, 164, 24, 114, 7, 'remark', '9'), - - // 10. 二维码:entry_order_code - qrcodeEl(37, 4, 120, 24, 24, 'entry_order_code', '8'), - - // 11. 打印时间 - label(38, 174, 10, 26, 7, '打印时间:', '9'), - field(39, 174, 36, 102, 7, 'print_time', '9'), - -]; - -module.exports.up = async queryInterface => { - const { sequelize } = queryInterface; - - // 先删除可能存在的旧版本 id=20 - await sequelize.query( - `DELETE FROM \`${TABLE}\` WHERE id = 20`, - { type: sequelize.QueryTypes.DELETE } - ); - - // 插入修正后的入库单 A5 模板(id=20) - await sequelize.query( - `INSERT INTO \`${TABLE}\` - (id, business_type, template_name, platform, warehouse_id, page_width, page_height, template_content, template_type, template_url, is_default, status, create_at, update_at) - VALUES (20, 'ENTRY_ORDER', '入库单A5模板', 'default', NULL, 148, 210, :template_content, 'CUSTOM', '', true, 'ACTIVE', NOW(), NOW())`, - { - replacements: { - template_content: JSON.stringify(templateContent), - }, - type: sequelize.QueryTypes.INSERT, - } - ); -}; - -module.exports.down = async queryInterface => { - const { sequelize } = queryInterface; - await sequelize.query( - `DELETE FROM \`${TABLE}\` WHERE id = 20`, - { type: sequelize.QueryTypes.DELETE } - ); -}; - -module.exports.templateContent = templateContent; diff --git a/database/migrations/20260702-migrate-entry-order-print-data.js b/database/migrations/20260702-migrate-entry-order-print-data.js deleted file mode 100644 index 1b47e12..0000000 --- a/database/migrations/20260702-migrate-entry-order-print-data.js +++ /dev/null @@ -1,53 +0,0 @@ -'use strict'; - -/** - * 将 wms_print_items 和 wms_print_template 表中已存在的入库单打印数据 - * 从 RECEIPT 迁移到 ENTRY_ORDER。 - * - * 背景: - * - RECEIPT 下同时有收货单(platform=warehouse)和入库单(platform=default)的数据 - * - 只有 platform='default' 的才是入库单,需要迁移 - * - platform='warehouse' 的是收货单,保留在 RECEIPT - * - * up: 将 business_type='RECEIPT' AND platform='default' → business_type='ENTRY_ORDER' - * down:将 business_type='ENTRY_ORDER' AND platform='default' → business_type='RECEIPT' - */ - -const PRINT_ITEMS_TABLE = 'wms_print_items'; -const PRINT_TEMPLATE_TABLE = 'wms_print_template'; - -module.exports.up = async queryInterface => { - const { sequelize } = queryInterface; - - // 1) wms_print_items:入库单打印项迁移 - await sequelize.query( - `UPDATE \`${PRINT_ITEMS_TABLE}\` - SET business_type = 'ENTRY_ORDER', updated_at = NOW() - WHERE business_type = 'RECEIPT' AND platform = 'default'` - ); - - // 2) wms_print_template:入库单打印模板迁移 - await sequelize.query( - `UPDATE \`${PRINT_TEMPLATE_TABLE}\` - SET business_type = 'ENTRY_ORDER', update_at = NOW() - WHERE business_type = 'RECEIPT' AND platform = 'default'` - ); -}; - -module.exports.down = async queryInterface => { - const { sequelize } = queryInterface; - - // 1) wms_print_items:入库单打印项回退 - await sequelize.query( - `UPDATE \`${PRINT_ITEMS_TABLE}\` - SET business_type = 'RECEIPT', updated_at = NOW() - WHERE business_type = 'ENTRY_ORDER' AND platform = 'default'` - ); - - // 2) wms_print_template:入库单打印模板回退 - await sequelize.query( - `UPDATE \`${PRINT_TEMPLATE_TABLE}\` - SET business_type = 'RECEIPT', update_at = NOW() - WHERE business_type = 'ENTRY_ORDER' AND platform = 'default'` - ); -}; diff --git a/database/migrations/20260702-seed-receipt-default-template.js b/database/migrations/20260702-seed-receipt-default-template.js deleted file mode 100644 index 6ef39db..0000000 --- a/database/migrations/20260702-seed-receipt-default-template.js +++ /dev/null @@ -1,42 +0,0 @@ -'use strict'; - -/** - * 入库单 A5 默认打印模板(ENTRY_ORDER 业务类型)数据清理迁移。 - * - * 背景: - * 旧版本 migration 已创建了一个格式正确的入库单模板(id=20,扁平化 content/field_code/bold/fontSize 风格)。 - * 本 migration 后来又插入了一个格式错误的模板(id=21,使用了 label+style 包装,与渲染引擎不兼容)。 - * - * 本迁移的作用: - * - 删除格式错误的重复模板 id=21(如果存在) - * - 保留下一个格式正确的模板(id=20)继续使用 - * - * 渲染引擎解析逻辑见 app/service/systemMethods/print.js(customize 分支): - * - 直接读取 item.content / item.fontSize / item.bold / item.textAlign 等扁平化属性 - * - 有 field_code 的元素用 data[field_code] 值覆盖 content - * - 不支持 label / style 对象包装 - */ - -const TABLE = 'wms_print_template'; - -module.exports.up = async queryInterface => { - const { sequelize } = queryInterface; - - // 删除格式错误的重复模板(id=21,使用了 label+style 包装格式) - // 保留格式正确的模板 id=20(扁平化 content/field_code/bold/fontSize 风格) - const [ duplicate ] = await sequelize.query( - `SELECT id FROM \`${TABLE}\` WHERE id = 21 AND business_type = 'ENTRY_ORDER' AND template_name = '入库单A5模板' AND warehouse_id IS NULL AND delete_at IS NULL LIMIT 1`, - { type: sequelize.QueryTypes.SELECT } - ); - - if (duplicate) { - await sequelize.query( - `DELETE FROM \`${TABLE}\` WHERE id = 21`, - { type: sequelize.QueryTypes.DELETE } - ); - } -}; - -module.exports.down = async () => { - // down 不回滚:删除 id=21 是一条清理操作,不需要恢复 -}; diff --git a/database/migrations/20260702-seed-receipt-print-items-v2.js b/database/migrations/20260702-seed-receipt-print-items-v2.js deleted file mode 100644 index f068a2c..0000000 --- a/database/migrations/20260702-seed-receipt-print-items-v2.js +++ /dev/null @@ -1,151 +0,0 @@ -'use strict'; - -/** - * ENTRY_ORDER(入库单)打印项配置 v2 补充。 - * - * 在 v1(20260622150000)基础上新增: - * - entry_order_info 组:15 个新字段(sort_order 14~28) - * - entry_items 表格:columns 从 6 扩展为 11,新增 5 列 - * - entry_items_info 组:17 个独立字段(group_sort=3, sort_order 1~17) - * - * up:INSERT IGNORE + UPDATE 表格配置 - * down:先恢复表格原始配置,再删除新增记录 - */ - -const TABLE = 'wms_print_items'; - -// ─── 新增打印项 ──────────────────────────────────────────────── -const NEW_PRINT_ITEMS = [ - // ─── entry_order_info 组补充(group_sort=1, sort_order 14~28) ── - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '入库单ID', field_code: 'id', field_type: 'number', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 14, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '来源类型', field_code: 'source_type', field_type: 'text', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 15, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '同步状态', field_code: 'sync_status', field_type: 'text', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 16, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '同步返回信息', field_code: 'sync_message', field_type: 'text', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 17, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '仓库ID', field_code: 'warehouse_id', field_type: 'number', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 18, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '货主ID', field_code: 'store_id', field_type: 'number', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 19, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '最迟预期到货时间', field_code: 'expect_end_time', field_type: 'datetime', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 20, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '物流公司编码', field_code: 'logistics_code', field_type: 'text', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 21, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '供应商编码', field_code: 'supplier_code', field_type: 'text', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 22, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '费用是否记录', field_code: 'expense_record', field_type: 'number', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 23, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '是否启用', field_code: 'is_enabled', field_type: 'number', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 24, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '创建时间', field_code: 'created_at', field_type: 'datetime', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 25, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '更新时间', field_code: 'updated_at', field_type: 'datetime', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 26, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '关联仓库名称', field_code: 'warehouse_company_name', field_type: 'text', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 27, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '关联货主名称', field_code: 'store_company_name', field_type: 'text', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 28, required: false, status: 1 }, - - // ─── entry_items_info 独立字段(group_sort=3) ────────────────── - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '商品SKU ID', field_code: 'stock_id', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 1, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '外部商品编码', field_code: 'external_item_code', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 2, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '外部商品ID', field_code: 'external_item_id', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 3, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '仓库商品编码', field_code: 'warehouse_item_code', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 4, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '仓库商品名称', field_code: 'warehouse_item_name', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 5, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '仓库商品规格', field_code: 'warehouse_item_spec', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 6, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '仓库当前库存总量', field_code: 'warehouse_quantity', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 7, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '仓库锁定数量', field_code: 'warehouse_locked_quantity', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 8, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '是否批次管理', field_code: 'warehouse_is_batch_mgmt', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 9, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '是否效期管理', field_code: 'warehouse_is_shelf_life_mgmt', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 10, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '直入已入库数量', field_code: 'direct_inbound_quantity', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 11, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '剩余可入库数量', field_code: 'remaining_quantity', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 12, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '外部业务编码', field_code: 'out_biz_code', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 13, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '订单行号', field_code: 'order_line_no', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 14, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '货主编码', field_code: 'owner_code', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 15, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '库存类型', field_code: 'inventory_type', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 16, required: false, status: 1 }, - { business_type: 'ENTRY_ORDER', platform: 'default', field_name: '已确认收货数量', field_code: 'confirm_quantity', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 17, required: false, status: 1 }, -]; - -// ─── 旧 items 表格配置(v1) ──────────────────────────────────── -const OLD_ITEMS_TABLE_CONFIG = { - columns: 6, - headers: [ '商品编码', '商品名称', '条码', '计划数量', '已收数量', '库存类型' ], -}; - -// ─── 新 items 表格配置(v2 扩展为 11 列) ─────────────────────── -const NEW_ITEMS_TABLE_CONFIG = { - columns: 11, - headers: [ '行号', '商品编码(外部)', '商品名称', '条码', '仓库商品编码', '计划数量', '已收数量', '已确认数量', '直入数量', '剩余可入库', '库存类型' ], -}; - -// ══════════════════════════════════════════════════════════════════ -const NEW_FIELD_CODES = NEW_PRINT_ITEMS.map(it => it.field_code); - -module.exports.up = async queryInterface => { - const { sequelize } = queryInterface; - - // 1) 插入所有新增打印项(幂等) - for (const item of NEW_PRINT_ITEMS) { - await sequelize.query( - `INSERT IGNORE INTO \`${TABLE}\` - (business_type, platform, field_name, field_code, field_type, is_table, table_config, group_field, group_label, group_sort, sort_order, required, status, created_at, updated_at) - VALUES (:business_type, :platform, :field_name, :field_code, :field_type, :is_table, :table_config, :group_field, :group_label, :group_sort, :sort_order, :required, :status, NOW(), NOW())`, - { - replacements: { - business_type: item.business_type, - platform: item.platform, - field_name: item.field_name, - field_code: item.field_code, - field_type: item.field_type, - is_table: item.is_table ? 1 : 0, - table_config: item.table_config ? JSON.stringify(item.table_config) : null, - group_field: item.group_field || null, - group_label: item.group_label || null, - group_sort: item.group_sort || 0, - sort_order: item.sort_order || 0, - required: item.required ? 1 : 0, - status: item.status, - }, - type: sequelize.QueryTypes.INSERT, - } - ); - } - - // 2) 更新 items 表格配置:6 列 → 11 列 - await sequelize.query( - `UPDATE \`${TABLE}\` - SET table_config = :table_config, - updated_at = NOW() - WHERE business_type = 'ENTRY_ORDER' - AND platform = 'default' - AND field_code = 'items'`, - { - replacements: { - table_config: JSON.stringify(NEW_ITEMS_TABLE_CONFIG), - }, - type: sequelize.QueryTypes.UPDATE, - } - ); -}; - -module.exports.down = async queryInterface => { - const { sequelize } = queryInterface; - - // 1) 恢复 items 表格原有配置(columns:6) - await sequelize.query( - `UPDATE \`${TABLE}\` - SET table_config = :table_config, - updated_at = NOW() - WHERE business_type = 'ENTRY_ORDER' - AND platform = 'default' - AND field_code = 'items'`, - { - replacements: { - table_config: JSON.stringify(OLD_ITEMS_TABLE_CONFIG), - }, - type: sequelize.QueryTypes.UPDATE, - } - ); - - // 2) 精确删除本次新增的所有打印项 - if (NEW_FIELD_CODES.length > 0) { - const placeholders = NEW_FIELD_CODES.map(() => '?').join(','); - await sequelize.query( - `DELETE FROM \`${TABLE}\` - WHERE business_type = 'ENTRY_ORDER' - AND platform = 'default' - AND field_code IN (${placeholders})`, - { - replacements: NEW_FIELD_CODES, - type: sequelize.QueryTypes.DELETE, - } - ); - } -}; diff --git a/database/migrations/20260703000000-add-binding-fields-to-wms-inbound-direct-log.js b/database/migrations/20260703000000-add-binding-fields-to-wms-inbound-direct-log.js new file mode 100644 index 0000000..7ff40f3 --- /dev/null +++ b/database/migrations/20260703000000-add-binding-fields-to-wms-inbound-direct-log.js @@ -0,0 +1,100 @@ +'use strict'; + +const TABLE_NAME = 'wms_inbound_direct_log'; + +module.exports = { + up: async (queryInterface, Sequelize) => { + const tables = await queryInterface.showAllTables(); + const exists = tables.some(t => (typeof t === 'string' ? t : t.tableName) === TABLE_NAME); + if (!exists) return; + + const columns = await queryInterface.describeTable(TABLE_NAME); + + // 新增 entry_item_id 字段 + if (!columns.entry_item_id) { + await queryInterface.addColumn(TABLE_NAME, 'entry_item_id', { + type: Sequelize.BIGINT(20).UNSIGNED, + allowNull: true, + defaultValue: null, + comment: '入库明细ID', + }); + } + + // 新增 receiving_detail_id 字段 + if (!columns.receiving_detail_id) { + await queryInterface.addColumn(TABLE_NAME, 'receiving_detail_id', { + type: Sequelize.INTEGER(11), + allowNull: true, + defaultValue: null, + comment: '收货明细ID,绑定收货时使用', + }); + } + + // 新增 status 字段 + if (!columns.status) { + await queryInterface.addColumn(TABLE_NAME, 'status', { + type: Sequelize.ENUM('pending', 'committed', 'released'), + allowNull: true, + defaultValue: null, + comment: '绑定状态:pending=待提交 committed=已提交 released=已释放,非绑定模式为NULL', + }); + } + + // 新增 updated_at 字段 + if (!columns.updated_at) { + await queryInterface.addColumn(TABLE_NAME, 'updated_at', { + type: Sequelize.DATE, + allowNull: true, + defaultValue: null, + comment: '更新时间', + }); + } + + // 新增 deleted_at 字段(软删除) + if (!columns.deleted_at) { + await queryInterface.addColumn(TABLE_NAME, 'deleted_at', { + type: Sequelize.DATE, + allowNull: true, + defaultValue: null, + comment: '软删除时间', + }); + } + + // 新增索引 idx_entry_item_id + await queryInterface.addIndex(TABLE_NAME, [ 'entry_item_id' ], { + name: 'idx_entry_item_id', + }); + + // 新增索引 idx_receiving_detail_id + await queryInterface.addIndex(TABLE_NAME, [ 'receiving_detail_id' ], { + name: 'idx_receiving_detail_id', + }); + + // 新增索引 idx_status + await queryInterface.addIndex(TABLE_NAME, [ 'status' ], { + name: 'idx_status', + }); + + // 新增唯一约束 uk_entry_receiving_binding + await queryInterface.addIndex(TABLE_NAME, [ 'entry_item_id', 'receiving_detail_id', 'status' ], { + name: 'uk_entry_receiving_binding', + unique: true, + }); + }, + + down: async queryInterface => { + // 移除唯一约束 + await queryInterface.removeIndex(TABLE_NAME, 'uk_entry_receiving_binding'); + // 移除索引 + await queryInterface.removeIndex(TABLE_NAME, 'idx_status'); + await queryInterface.removeIndex(TABLE_NAME, 'idx_receiving_detail_id'); + await queryInterface.removeIndex(TABLE_NAME, 'idx_entry_item_id'); + + // 移除字段 + await queryInterface.removeColumn(TABLE_NAME, 'deleted_at'); + await queryInterface.removeColumn(TABLE_NAME, 'updated_at'); + await queryInterface.removeColumn(TABLE_NAME, 'status'); + await queryInterface.removeColumn(TABLE_NAME, 'receiving_detail_id'); + await queryInterface.removeColumn(TABLE_NAME, 'entry_item_id'); + }, +}; diff --git a/database/migrations/20260703000001-migrate-binding-data-to-inbound-direct-log.js b/database/migrations/20260703000001-migrate-binding-data-to-inbound-direct-log.js new file mode 100644 index 0000000..7ec574e --- /dev/null +++ b/database/migrations/20260703000001-migrate-binding-data-to-inbound-direct-log.js @@ -0,0 +1,184 @@ +'use strict'; + +/** + * 数据迁移:将 wms_entry_receiving_binding 存量数据迁移到 wms_inbound_direct_log。 + * + * 背景: + * - wms_entry_receiving_binding 的"入库明细 ↔ 收货明细"绑定能力已迁移到 wms_inbound_direct_log。 + * - 本 migration 负责将 wms_entry_receiving_binding 中的历史数据同步到 wms_inbound_direct_log。 + * + * 字段映射(source → target): + * - entry_item_id / receiving_detail_id / allocated_quantity→quantity / status / creator_id→operator_id + * - created_at→created_at / updated_at→updated_at / deleted_at→deleted_at + * + * 关联补全: + * - entry_order_id / entry_order_code / warehouse_id / store_id:通过 wms_entry_items + wms_entry_order + * - stock_id:从 wms_entry_items + * - inbound_type:固定 'pda' + * - space_id:固定 0 + * + * @description 迁移脚本:20260703000001 + */ + +/** 目标表名 */ +const TARGET_TABLE = 'wms_inbound_direct_log'; +/** 源表名 */ +const SOURCE_TABLE = 'wms_entry_receiving_binding'; + +/** + * 规范化 showAllTables 返回的表名。 + * @param {string|Object} table 表名或表对象。 + * @return {string} 规范化后的表名。 + */ +const normalizeTableName = table => { + if (typeof table === 'string') return table; + return table && typeof table === 'object' ? (table.tableName || table.name || '') : ''; +}; + +/** + * 检查源表是否存在。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口。 + * @return {Promise} 源表是否存在。 + */ +const hasSourceTable = async queryInterface => { + const allTables = await queryInterface.showAllTables(); + const tableSet = new Set((allTables || []).map(normalizeTableName)); + return tableSet.has(SOURCE_TABLE); +}; + +/** + * 检查目标表是否存在。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口。 + * @return {Promise} 目标表是否存在。 + */ +const hasTargetTable = async queryInterface => { + const allTables = await queryInterface.showAllTables(); + const tableSet = new Set((allTables || []).map(normalizeTableName)); + return tableSet.has(TARGET_TABLE); +}; + +/** + * 统计源表总行数。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口。 + * @return {Promise} 源表总行数。 + */ +const countSourceRows = async queryInterface => { + const [ rows ] = await queryInterface.sequelize.query( + `SELECT COUNT(*) AS cnt FROM ${SOURCE_TABLE}`, + { type: queryInterface.sequelize.QueryTypes.SELECT } + ); + return rows ? rows.cnt : 0; +}; + +/** + * 正向迁移:从 wms_entry_receiving_binding 迁移数据到 wms_inbound_direct_log。 + * + * 去重策略:按 (entry_item_id, receiving_detail_id, status) GROUP BY 去重, + * 重复组保留 id 最小的一条,其余跳过并打印数量。 + * + * @param {import('sequelize').QueryInterface} queryInterface 查询接口。 + * @param {typeof import('sequelize')} Sequelize Sequelize 类型集合。 + * @return {Promise} 无返回值。 + */ +module.exports.up = async (queryInterface, Sequelize) => { + void Sequelize; + + // 幂等:源表不存在则跳过 + if (!(await hasSourceTable(queryInterface))) { + console.log('wms_entry_receiving_binding 表不存在,跳过迁移'); + return; + } + + // 幂等:目标表不存在则跳过 + if (!(await hasTargetTable(queryInterface))) { + console.log('wms_inbound_direct_log 表不存在,跳过迁移'); + return; + } + + const totalRows = await countSourceRows(queryInterface); + console.log(`wms_entry_receiving_binding 总行数:${totalRows}`); + + if (totalRows === 0) { + console.log('无数据需要迁移,跳过'); + return; + } + + // 统计去重后跳过的行数 + const [ dupResult ] = await queryInterface.sequelize.query( + `SELECT COUNT(*) AS skip_cnt + FROM ${SOURCE_TABLE} + WHERE id NOT IN ( + SELECT MIN(id) + FROM ${SOURCE_TABLE} + GROUP BY entry_item_id, receiving_detail_id, status + )`, + { type: queryInterface.sequelize.QueryTypes.SELECT } + ); + const skipCount = dupResult ? dupResult.skip_cnt : 0; + if (skipCount > 0) { + console.log(`检测到 ${skipCount} 条重复记录(按 entry_item_id + receiving_detail_id + status 分组去重),将被跳过`); + } + + // 执行 INSERT INTO ... SELECT + const [ insertResult ] = await queryInterface.sequelize.query( + `INSERT INTO ${TARGET_TABLE} + (entry_item_id, receiving_detail_id, quantity, status, + operator_id, created_at, updated_at, deleted_at, + entry_order_id, entry_order_code, warehouse_id, store_id, + stock_id, inbound_type, space_id) + SELECT + b.entry_item_id, + b.receiving_detail_id, + b.allocated_quantity, + b.status, + b.creator_id, + b.created_at, + b.updated_at, + b.deleted_at, + ei.order_id, + eo.entry_order_code, + eo.warehouse_id, + eo.store_id, + ei.stock_id, + 'pda', + 0 + FROM ${SOURCE_TABLE} b + LEFT JOIN wms_entry_items ei ON b.entry_item_id = ei.id + LEFT JOIN wms_entry_order eo ON ei.order_id = eo.id + WHERE b.id IN ( + SELECT MIN(id) + FROM ${SOURCE_TABLE} + GROUP BY entry_item_id, receiving_detail_id, status + )`, + { type: queryInterface.sequelize.QueryTypes.INSERT } + ); + + const insertedCount = insertResult ? (Array.isArray(insertResult) ? insertResult.length : insertResult[1]) : 0; + console.log(`迁移完成:成功插入 ${insertedCount} 行`); +}; + +/** + * 回滚迁移:删除从 wms_entry_receiving_binding 迁移过来的数据。 + * + * 删除条件:receiving_detail_id IS NOT NULL AND entry_item_id IS NOT NULL + * (仅删除有绑定关系的记录,不影响原有 direct-log 数据) + * + * @param {import('sequelize').QueryInterface} queryInterface 查询接口。 + * @return {Promise} 无返回值。 + */ +module.exports.down = async queryInterface => { + if (!(await hasTargetTable(queryInterface))) { + console.log('wms_inbound_direct_log 表不存在,跳过回滚'); + return; + } + + const [ deleteResult ] = await queryInterface.sequelize.query( + `DELETE FROM ${TARGET_TABLE} + WHERE receiving_detail_id IS NOT NULL + AND entry_item_id IS NOT NULL`, + { type: queryInterface.sequelize.QueryTypes.DELETE } + ); + + const deletedCount = deleteResult || 0; + console.log(`回滚完成:删除 ${deletedCount} 行`); +}; diff --git a/docs/api-doc-update-spec.example.json b/docs/api-doc-update-spec.example.json deleted file mode 100644 index 2477ca5..0000000 --- a/docs/api-doc-update-spec.example.json +++ /dev/null @@ -1,56 +0,0 @@ -{ - "docName": "", - "docMeta": { - "updatedAt": "", - "version": "" - }, - "group": { - "groupName": "<分组名称>", - "module": "" - }, - "methods": [ - { - "method": "", - "description": "<接口说明>", - "isNeedAuth": false, - "isNeedLogin": true, - "headers": [], - "params": [ - { - "name": "", - "type": "string", - "required": true, - "source": "body", - "description": "<参数说明>" - } - ], - "response": [ - { - "name": "", - "type": "string", - "required": true, - "description": "<返回字段说明>" - } - ], - "errors": [ - { - "code": 400, - "message": "<错误说明>" - } - ] - } - ], - "change": { - "version": "", - "date": "", - "summary": "<本次变更摘要>", - "methods": [ - "" - ], - "notes": [ - "<变更说明 1>", - "<变更说明 2>" - ], - "type": "updated" - } -} \ No newline at end of file diff --git a/docs/api-doc-update-workflow.md b/docs/api-doc-update-workflow.md deleted file mode 100644 index c5e8343..0000000 --- a/docs/api-doc-update-workflow.md +++ /dev/null @@ -1,124 +0,0 @@ -# API 文档 JSON 固定写入流程 - -## 现有 JSON 结构 - -仓库内现有 API 文档分两类: - -1. `methods/.json` - - 根节点是对象 - - 关键字段固定为 `module`、`description`、`version`、`updatedAt`、`headers`、`methods.groups` - - `methods.groups` 为数组,每个 group 固定为 `groupName`、`module`、`list` - - `list` 中每个 method 固定包含 `method`、`description`、`isNeedAuth`、`isNeedLogin`、`headers`、`params`、`response`、`errors` - -2. `methods/changes/.json` - - 根节点是数组 - - 每条变更记录建议固定包含 `version`、`date`、`summary`、`methods`、`notes` - - 可选补充 `type` - -## 固定输入 spec - -后续 API 文档写入统一通过脚本读取一个 spec JSON 完成,spec 结构固定如下: - -```json -{ - "docName": "system", - "docMeta": { - "updatedAt": "2026-04-15", - "version": "0.3.5" - }, - "group": { - "groupName": "基础模块", - "module": "index" - }, - "methods": [ - { - "method": "index.example", - "description": "接口说明", - "isNeedAuth": false, - "isNeedLogin": true, - "headers": [], - "params": [], - "response": [], - "errors": [] - } - ], - "change": { - "version": "2026.04.15-system-06", - "date": "2026-04-15", - "summary": "一句话说明本次接口文档变更", - "methods": [ - "index.example" - ], - "notes": [ - "补充关键字段说明。" - ], - "type": "updated" - } -} -``` - -说明: - -- `docName` 目前必须对应已存在的 `methods/system.json`、`methods/qimen.json`、`methods/gateway.json` -- `group` 用于定位或创建目标分组 -- `methods` 为要写入的完整 method 文档对象数组,脚本按 `method` 字段 upsert -- `change` 默认必填;仅当明确是纯格式修复且不需要追加历史时,才允许加 `--doc-only` - -注意:所有对 `methods/*.json` 与 `methods/changes/*.json` 的变更必须通过 spec + 脚本完成。spec 是唯一输入来源,不接受直接手写或直接提交目标 JSON 的改动。 - -## 固定命令 - -务必按顺序执行:复制 example -> 编辑 spec -> dry-run -> 修正 -> 正式写入。示例命令(PowerShell): - -先做 dry-run(验证和查看差异): - -```powershell -npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run -``` - -确认 dry-run 输出无误后执行正式写入: - -```powershell -npm run doc:api:update -- --spec=temp/api-doc-update.json -``` - -仅修补主文档且不追加 changes 时(慎用): - -```powershell -npm run doc:api:update -- --spec=temp/api-doc-update.json --doc-only -``` - -## 脚本保证 - -`script/update-api-doc.cjs` 会执行以下动作(脚本为写入守门人): - -- 校验 spec JSON 是否符合固定结构与必填字段 -- 校验目标 `methods/*.json` 与 `methods/changes/*.json` 是否可解析 -- 在 dry-run 模式下不写入,仅打印将要变更的差异并返回校验结果 -- 按 `group` + `method` 做 upsert,避免覆盖或破坏其他分组/方法 -- 检查 change version 是否重复并拒绝冲突写入 -- 尽量保留目标 JSON 原有缩进与换行风格,减少无关 diff - -脚本是对 methods JSON 的唯一写入通道;任何绕过脚本的改动都不被接受。 - -## 推荐流程 - -1. 先核对代码与测试,确认真实接口契约 -2. 如果是 system 参数结构变化,可先执行 `node .\script\tmp-struct-system-params.cjs` -3. 按 [docs/api-doc-update-spec.example.json](docs/api-doc-update-spec.example.json) 复制一份 spec 到 `temp/` 并在该文件上编辑 -4. 先执行 dry-run(`--dry-run`),阅读输出并修正 spec -5. 确认无误后执行正式写入(不带 `--dry-run`) -6. 最后补充必要的 `docs/*.md` 或 `README.md` - -最小示例流程(PowerShell): - -```powershell -# 复制示例到 temp 并编辑 -Copy-Item docs/api-doc-update-spec.example.json temp/api-doc-update.json - -# dry-run -npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run - -# 正式写入 -npm run doc:api:update -- --spec=temp/api-doc-update.json -``` \ No newline at end of file diff --git a/docs/combo-goods-api.md b/docs/combo-goods-api.md deleted file mode 100644 index 5b6ea72..0000000 --- a/docs/combo-goods-api.md +++ /dev/null @@ -1,387 +0,0 @@ -# 组合商品(comboGoods)模块 API 文档 - -## 模块概述 - -组合商品(comboGoods)模块提供组合商品的 CRUD 和搜索功能。组合商品是将多个系统商品(来自 `wms_stock_warehouse`)捆绑在一起的商品概念,用于订单快速选择。 - -**代码文件:** -- 业务逻辑层:`app/service/systems/comboGoods.js` -- 接口包装层:`app/service/systemMethods/comboGoods.js` - -**数据表:** -- `wms_combo_goods`:组合商品主表 -- `wms_combo_goods_item`:组合商品明细表 - ---- - -## 数据库表结构 - -### 主表:wms_combo_goods - -| 字段 | 类型 | 说明 | -|------|------|------| -| id | number | 主键ID | -| combo_code | string | 组合商品编码(唯一) | -| combo_name | string | 组合商品名称 | -| combo_sku_id | number | 组合商品SKU ID | -| custom_code | string\|null | 自定义编码,按货主唯一(排除已删除记录) | -| status | number | 状态:1=启用 0=停用 | -| warehouse_id | number\|null | 仓库ID | -| remark | string | 备注 | -| creator_id | number | 创建人ID | -| editor_id | number | 最后编辑人ID | -| created_at | datetime | 创建时间 | -| updated_at | datetime | 更新时间 | - -### 明细表:wms_combo_goods_item - -| 字段 | 类型 | 说明 | -|------|------|------| -| id | number | 主键ID | -| combo_id | number | 关联的组合商品ID | -| item_goods_sku_id | number | 子商品 stock_id(对应 wms_stock_warehouse.id) | -| item_quantity | number | 子商品数量 | -| sort_order | number | 排序号 | - ---- - -## 约束规则 - -### 商品有效性校验 - -创建/编辑组合商品时,所有子商品必须在 `wms_stock_warehouse` 表中满足以下条件: -- `is_valid = 'Y'`(有效状态) -- `deleted_at IS NULL`(未删除) - -任一子商品不满足条件,操作将被拒绝并返回具体的不合法 stock_id 列表。 - -### 货主一致性校验 - -所有子商品必须属于同一个货主(`store_id` 一致)。跨货主组合将返回错误:「所有子商品必须属于同一个货主,不允许跨货主组合」。 - -### 自定义编码(custom_code)校验 - -`custom_code` 为可选字段(VARCHAR(64)),仅做按货主唯一性校验(排除 status=0 的已删除记录)。 -- **create**:如果传入非空的 `custom_code`,会校验同货主非删除记录中唯一。 -- **update**:如果传入非空的 `custom_code`,会校验同货主非删除记录中唯一(排除自身 id)。 -- 唯一索引:`uk_store_custom_code(warehouse_id, custom_code)`。 - ---- - -## 简记格式说明 - -列表查询和搜索结果中会返回两种简记字段,供前端直接展示: - -### simpleNotation(字符串简记) - -格式:`stock_id|数量,stock_id2|数量` - -示例:`1001|3,1002|5` 表示 stock_id=1001 的商品 3 件 + stock_id=1002 的商品 5 件。 - -### nameNotation(商品名称简记) - -格式:`【数量】商品名称+【数量】商品名称` - -示例:`【3】苹果+【5】香蕉` 表示苹果 3 件 + 香蕉 5 件。 - -商品名称从 `wms_stock_warehouse.item_name` 获取;若 stock_id 无有效商品信息,则显示为 `SKU#stock_id`。 - ---- - -## 接口列表 - -### 1. comboGoods.list — 组合商品列表查询(分页) - -- **鉴权**:不需要(isNeedAuth=false) -- **登录**:需要 - -#### 请求参数 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| pagination | object | 否 | 分页参数 | -| pagination.page | number | 否 | 页码,默认 1 | -| pagination.pageSize | number | 否 | 每页大小,默认 20,最大 200 | -| where | object | 否 | 筛选条件 | -| where.combo_code | string | 否 | 组合商品编码,精确匹配 | -| where.combo_name | string | 否 | 组合商品名称,模糊匹配 | -| where.status | number | 否 | 状态筛选:1=启用 0=停用 | -| where.warehouse_id | number | 否 | 仓库ID筛选 | - -#### 请求示例 - -```json -{ - "method": "comboGoods.list", - "data": { - "pagination": { - "page": 1, - "pageSize": 20 - }, - "where": { - "combo_name": "春节礼包", - "status": 1 - } - } -} -``` - -#### 响应格式 - -```json -{ - "code": 200, - "message": "查询成功", - "data": { - "list": [ - { - "id": 1, - "combo_code": "COMBO-001", - "combo_name": "春节礼包A", - "combo_sku_id": 0, - "custom_code": null, - "status": 1, - "warehouse_id": 1001, - "remark": "", - "creator_id": 10, - "editor_id": 10, - "created_at": "2026-06-01T10:00:00.000Z", - "updated_at": "2026-06-01T10:00:00.000Z", - "items": [ - { - "id": 1, - "combo_id": 1, - "item_goods_sku_id": 1001, - "item_quantity": 3, - "sort_order": 0 - }, - { - "id": 2, - "combo_id": 1, - "item_goods_sku_id": 1002, - "item_quantity": 5, - "sort_order": 1 - } - ], - "simpleNotation": "1001|3,1002|5", - "nameNotation": "【3】苹果+【5】香蕉" - } - ], - "total": 1, - "page": 1, - "pageSize": 20 - } -} -``` - ---- - -### 2. comboGoods.create — 创建组合商品 - -- **鉴权**:需要(isNeedAuth=true) -- **登录**:需要 - -#### 请求参数 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| combo_code | string | 是 | 组合商品编码,全局唯一 | -| combo_name | string | 是 | 组合商品名称 | -| warehouse_id | number | 否 | 仓库ID | -| remark | string | 否 | 备注 | -| custom_code | string | 否 | 自定义编码,传入时校验按货主唯一(排除已删除记录) | -| items | array | 是 | 子商品明细数组 | -| items[].item_goods_sku_id | number | 是 | 子商品 stock_id | -| items[].item_quantity | number | 是 | 子商品数量(正整数) | -| items[].sort_order | number | 否 | 排序号,默认按数组索引 | - -#### 请求示例 - -```json -{ - "method": "comboGoods.create", - "data": { - "combo_code": "COMBO-001", - "combo_name": "春节礼包A", - "warehouse_id": 1001, - "remark": "2026春节促销礼包", - "items": [ - { "item_goods_sku_id": 1001, "item_quantity": 3 }, - { "item_goods_sku_id": 1002, "item_quantity": 5 } - ] - } -} -``` - -#### 响应格式 - -```json -{ - "code": 200, - "message": "创建成功", - "data": { - "id": 1, - "combo_code": "COMBO-001", - "combo_name": "春节礼包A", - "custom_code": null - } -} -``` - -#### 常见错误 - -| 错误信息 | 说明 | -|---------|------| -| 组合商品编码不能为空 | combo_code 未传或为空 | -| 组合商品名称不能为空 | combo_name 未传或为空 | -| 子商品列表不能为空 | items 未传或为空数组 | -| 组合商品编码 "XXX" 已存在 | combo_code 重复 | -| 自定义编码 "XXX" 已被货主其他组合商品使用 | custom_code 在同一货主下重复(排除已删除) | -| 以下子商品不存在或已停用:1001, 1002 | 子商品在 wms_stock_warehouse 中不存在或已停用 | -| 所有子商品必须属于同一个货主,不允许跨货主组合 | 明细中商品的 store_id 不一致 | - ---- - -### 3. comboGoods.update — 编辑组合商品 - -- **鉴权**:需要(isNeedAuth=true) -- **登录**:需要 - -#### 请求参数 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| id | number | 是 | 组合商品ID | -| combo_name | string | 否 | 组合商品名称 | -| warehouse_id | number | 否 | 仓库ID | -| remark | string | 否 | 备注 | -| custom_code | string | 否 | 自定义编码,传入非空值时校验按货主唯一(排除已删除记录和自身 id) | -| status | number | 否 | 状态:1=启用 0=停用 | -| items | array | 否 | 子商品明细数组。传入非空数组时先删旧明细再插入新明细;不传保持原明细不变 | -| items[].item_goods_sku_id | number | 是 | 子商品 stock_id | -| items[].item_quantity | number | 是 | 子商品数量(正整数) | -| items[].sort_order | number | 否 | 排序号 | - -> **注意**:部分更新语义——不传的字段保持原值不变。items 为可选,不传或传空数组则保持原明细不变。 - -#### 请求示例 - -```json -{ - "method": "comboGoods.update", - "data": { - "id": 1, - "combo_name": "春节礼包A(升级版)", - "remark": "更新备注", - "items": [ - { "item_goods_sku_id": 1001, "item_quantity": 5 }, - { "item_goods_sku_id": 1003, "item_quantity": 2 } - ] - } -} -``` - -#### 响应格式 - -```json -{ - "code": 200, - "message": "编辑成功", - "data": { - "id": 1 - } -} -``` - ---- - -### 4. comboGoods.delete — 删除组合商品 - -- **鉴权**:需要(isNeedAuth=true) -- **登录**:需要 - -#### 请求参数 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| id | number | 是 | 组合商品ID | - -> **注意**:删除操作为软删除,仅将 `status` 置为 0(停用),不会物理删除记录。 - -#### 请求示例 - -```json -{ - "method": "comboGoods.delete", - "data": { - "id": 1 - } -} -``` - -#### 响应格式 - -```json -{ - "code": 200, - "message": "删除成功", - "data": { - "id": 1 - } -} -``` - ---- - -### 5. comboGoods.search — 关键字搜索组合商品 - -- **鉴权**:不需要(isNeedAuth=false) -- **登录**:需要 - -#### 请求参数 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| keyword | string | 是 | 搜索关键字,模糊匹配 custom_code、combo_code 和 combo_name,custom_code 匹配项优先排在前面 | -| limit | number | 否 | 最大返回条数,默认 20,最大 100 | - -> **注意**:仅返回启用状态(status=1)的记录。该接口用于手工建单时前端选择组合商品。 - -#### 请求示例 - -```json -{ - "method": "comboGoods.search", - "data": { - "keyword": "礼包", - "limit": 30 - } -} -``` - -#### 响应格式 - -```json -{ - "code": 200, - "message": "搜索成功", - "data": { - "list": [ - { - "id": 1, - "combo_code": "COMBO-001", - "combo_name": "春节礼包A", - "custom_code": null, - "status": 1, - "warehouse_id": 1001, - "items": [ - { "id": 1, "combo_id": 1, "item_goods_sku_id": 1001, "item_quantity": 3, "sort_order": 0 } - ], - "simpleNotation": "1001|3,1002|5", - "nameNotation": "【3】苹果+【5】香蕉" - } - ], - "total": 1 - } -} -``` diff --git a/docs/express-model-table-map.md b/docs/express-model-table-map.md deleted file mode 100644 index 75bddcd..0000000 --- a/docs/express-model-table-map.md +++ /dev/null @@ -1,33 +0,0 @@ -# Express 模型与数据表整理 - -## 一览 - -| 模型文件 | Sequelize key | 数据表 | 当前状态 | -| --- | --- | --- | --- | -| app/model/express.js | Express | wms_express | 已补齐 | -| app/model/express_setting.js | ExpressSetting | wms_express_setting | 已补齐 | -| app/model/order_express.js | OrderExpress | wms_order_express | 已补齐 | -| app/model/order_express_print_data.js | OrderExpressPrintData | wms_order_express_print_data | 已补齐 | -| app/model/express_print_record.js | ExpressPrintRecord | wms_express_print_record | 已补齐 | - -## 关键说明 - -- 本次仅整理模型与真实数据表对齐,不改动业务逻辑与接口行为。 -- 通过 `script/db-query.ps1` 实查,数据库中包含 5 张 express 相关表,上述模型已全部覆盖。 -- 既有字段型快递信息(如 `wms_entry_order.express_code`、`wms_order_delivery.express_code`)仍保留为业务字段,不属于独立主数据表。 - -## 建议的后续收敛 - -- 将 `index.getExpressList` 的配置源(`app.config.expressList`)逐步收敛到 `wms_express`,避免配置与数据表双源。 -- 若后续存在统一查询需求,可新增 `systems/express.js`,统一对 `Express / ExpressSetting / OrderExpress` 的读写入口。 - -## 包材关联字段说明 - -- **新增字段**:`wms_order_express.package_material_id`(可空,BIGINT unsigned)、`wms_order_express.package_material_name_snapshot`(可空,VARCHAR(128))。用于记录订单快递所使用的包材引用与名称快照,`package_material_id` 指向 `wms_package_material.id`。 -- **新增表**:`wms_package_material`(包材主数据表)和 `wms_package_supplier`(包材供应商表),均已在 migration 与 model 中定义;关键索引:`idx_wms_package_material_warehouse_id`、`uk_wms_package_material_warehouse_material_code`、`idx_wms_package_supplier_warehouse_id`、`uk_wms_package_supplier_warehouse_supplier_code`。 -- **索引**:为 `wms_order_express.package_material_id` 新增索引 `idx_wms_order_express_package_material_id`,以支持基于包材的过滤与联表查询。 -- **兼容性**:新增列为可空,不会破坏现有接口契约。若系统存在将 `wms_order_express` 全量返回给外部的接口(未在 methods/system.json 中声明新增字段),请在需要暴露字段的接口中补充文档说明并在变更记录中标注。当前已检查的 system 方法文档未需修改,因此本次不改 methods/system.json(无接口契约变化)。 -- **回滚要点**:迁移的 down 会删除新增列、索引与新增表;回滚前请务必备份或迁移相关业务数据。 - -文档维护者:WMS 文档代理 - diff --git a/docs/file-writer.md b/docs/file-writer.md deleted file mode 100644 index 087e3ee..0000000 --- a/docs/file-writer.md +++ /dev/null @@ -1,122 +0,0 @@ -# 本地文件队列(app.fileWriter) - -本文档说明仓库中提供的本地文件队列写入能力(实现文件:app/lib/file_writer.js),用于把业务数据按 JSON Lines 追加到本地文件并由消费者按需读取处理,适合低延迟、本地持久化、批处理/异步消费场景。 - -**实现要点(写入特性)** -- 串行写入:同一进程内通过内部队列 `enqueue` 串行化写入,保证单进程内顺序性。 -- 强制落盘:每次写入使用文件句柄写入并调用 `handle.sync()` 进行 fsync,尽量保证数据落盘。 -- 自动轮转:当当前文件大小 + 待写入字节数 超过 `maxFileSize` 时,会自增序号并切换到新文件(sequence)。 -- 自动按行轮转:当单个数据文件累计达到 `maxFileLines` 行后,下一条写入会自动切换到下一个 sequence 文件,默认阈值为 `2000` 行。 -- 目录结构:默认 baseDir 下按业务与日期分区: - - baseDir////
/ -- 文件命名:文件前缀包含业务段与进程标识(`---p-`),尾部带序号与扩展名(`fileExtension`,默认 `.log`)。 -- 进度(.progress)断点续传:每个消费者使用独立的隐藏进度文件(以 `..progress` 命名),写入采用临时文件+rename 的原子替换策略,消费端可通过进度恢复消费位置。 -- Worker/进程隔离:写入文件名包含 `machineId`、`workerId` 与 `pid`,不同进程不会写入同一文件,避免互相竞争。 -- 清理策略:基于 `retentionDays` 定期删除过期的数据文件与进度文件。 - -**目录与文件示例** -- 目录:`/path/to/runtime/file-writer/orders/2026/04/09/` -- 数据文件示例:`orders-myhost-worker1-p1234-0001.log` -- 进度文件示例:`.consumer-1.progress`(位于同一分区目录下) - -**配置项说明(config.fileWriter)** -- `baseDir`:基础目录,默认 `path.join(app.baseDir, 'runtime', 'file-writer')`。 -- `maxFileSize`:单文件最大字节数,超过后轮转。支持数字(字节)或带单位字符串(如 `100M`、`1G`)。默认 `100 * 1024 * 1024`(100MB)。 -- `maxFileLines`:单文件最大行数,达到后下一条写入会自动轮转到新的 sequence 文件。默认 `2000`。 -- `retentionDays`:保留天数,超过则删除。设为 `0` 或负值可禁用清理。默认 `7`。 -- `cleanupIntervalMs`:触发清理的最小间隔(毫秒),写入时会基于此决定是否执行清理,设置为 `0` 或负值可禁用定期清理。默认 `3600000`(1 小时)。 -- `sequenceWidth`:文件序号宽度(零填充),默认 `4`(例如 `0001`)。 -- `fileExtension`:数据文件扩展名,默认 `.log`。 -- `progressExtension`:进度文件扩展名,默认 `.progress`。 -- `machineId`、`workerId`(可选):可通过配置覆盖,默认使用主机名与 `process.env.EGG_WORKER_ID`。 - -默认配置位置:`config/config.default.js` 的 `config.fileWriter` 节点。 - -示例(可放入 `config/config.local.js` 覆盖默认): - -```js -const path = require('path'); - -exports.fileWriter = { - baseDir: path.join(__dirname, '..', 'runtime', 'file-writer'), - maxFileSize: '200M', - maxFileLines: 2000, - retentionDays: 14, - cleanupIntervalMs: 60 * 60 * 1000, - sequenceWidth: 4, - fileExtension: '.log', - progressExtension: '.progress', - // machineId: 'my-host', - // workerId: 'worker-1', -}; -``` - -**写入示例(业务侧)** -简单写入(在任何可以访问 `app` 的位置): - -```js -// 在 controller/service 中 -await app.fileWriter.write('orders', { id: 123, event: 'created', payload: { /* ... */ } }); -// 返回对象包含 filePath、sequence、bytesWritten 等信息 -``` - -**消费/读取示例(推荐使用 app.fileWriter 提供的 API)** -推荐使用 `getProgressFilePath` + `consumeFiles` 提供的断点续传能力: - -```js -// 示例:定期或守护进程式消费 orders -async function consumeOrders(app) { - const writer = app.fileWriter; - const progressFile = writer.getProgressFilePath('orders', new Date(), 'order-consumer-1'); - - const result = await writer.consumeFiles({ - businessName: 'orders', - progressFilePath: progressFile, - onRecord: async (record, meta) => { - // record: 解析后的对象 - // meta: { filePath, offset, index } - // 在这里实现消息处理逻辑(去重、入库、调用外部服务等) - }, - parseJson: true, - }); - - return result; // 包含 processedCount 与最新 progress -} -``` - -如需逐文件手动控制消费,也可使用 `readRecords`: - -```js -const res = await app.fileWriter.readRecords(filePath, { startOffset: 0 }); -for (const rec of res.records) { - // 处理 rec -} -// 手动保存进度 -await app.fileWriter.saveProgress(progressFilePath, { - filePath, - offset: res.nextOffset, - processedCount: (previousCount || 0) + res.records.length, -}); -``` - -**进度文件(.progress)格式** -- 保存为 JSON,包含至少字段:`filePath`、`offset`、`processedCount`、`updatedAt`。 -- 写入采用临时文件写入 + `fsync` + `rename` 的方式尽量保证原子性。 - -**注意事项 / 运行时建议** -- 不要通过静态文件服务或外部 URL 直接暴露 `baseDir`(例如 `runtime/`),避免被外部下载或篡改。 -- 多 Worker / 多机部署: - - 默认每个进程生成独立的数据文件(文件名包含 `machineId`、`workerId`、`pid`),不会有多个进程同时写入同一文件。若你的设计需要跨进程全局严格顺序,请在上游统一入口合并写入或使用集中式队列(如 Kafka/Redis)。 - - 消费者可以按进程拆分(针对单进程的文件)或由独立中心消费者按文件目录遍历处理。 - - 可通过配置显式设置 `machineId`/`workerId` 来标识不同实例。 -- 关闭或调整清理策略:若需长期保留数据,请将 `retentionDays` 设为合适值或禁用清理(`0` 或负值)。 -- 性能角度:每次写入触发 fsync 会有性能开销,适合需要高可靠性的场景;若对持久性要求不高,可考虑将写入逻辑改为批量 fsync(此处为实现约束,不建议直接修改核心行为)。 - ---- - -如果希望在项目首页或工具箱中添加跳转链接,建议把一行链接加入到 [README.md](README.md) 或 [AI_TOOLBOX.md](AI_TOOLBOX.md) 的相关位置,指向本文件 `docs/file-writer.md`。 - ----- -**参考实现位置** -- 代码实现:app/lib/file_writer.js -- 默认配置:config/config.default.js -> `config.fileWriter` diff --git a/docs/notification-event-api.md b/docs/notification-event-api.md deleted file mode 100644 index dee3609..0000000 --- a/docs/notification-event-api.md +++ /dev/null @@ -1,255 +0,0 @@ -# 消息通知事件 API 文档(独立于 system) - -## 1. 文档说明 - -本文档描述 **WMS 对外消息通知能力** 的事件 API 约定。 - -特点: - -- **独立于 `/system` 接口** -- 不走 `method=xxx` 的 system 调用方式 -- 由内部业务在关键节点触发 `event` -- 通过 WebHook 向外部系统推送标准 JSON 消息 - -当前已落地事件: - -- `receiving_completed`:收货完成通知 -- `order_cancel_intercepted`:订单取消失败并触发拦截执行通知 -- `store_warehouse_print_quantity_adjusted`:货主面单余额人工调整通知 - ---- - -## 2. 触发方式 - -内部业务在以下位置触发: - -- 文件:`app/service/systems/storage/receiving.js` -- 方法:`completeReceiving()` -- 通知方法:`sendCompletionNotice()` - -触发时机: - -1. 收货单状态更新为 `completed` -2. 收货完成 Excel 报表上传成功或已生成完成结果 -3. 调用: - -```js -await ctx.service.systems.notice.send({ - businessName: 'receiving', - event: 'receiving_completed', - ... -}) -``` - ---- - -## 3. 事件命名规则 - -本能力中,**事件名本身就是通知方法标识**。 - -示例: - -| event | 含义 | -|---|---| -| `receiving_completed` | 收货单完成通知 | -| `order_cancel_intercepted` | 订单取消失败并触发拦截执行通知 | -| `store_warehouse_print_quantity_adjusted` | 货主面单余额人工调整通知 | - -> 当前正式注册的业务事件包括 `receiving_completed`、`order_cancel_intercepted`、`store_warehouse_print_quantity_adjusted`。 - -对于外部订阅方来说,判断消息类型时,优先看: - -- `event` -- `businessName` -- `message.type` - -命名约束: - -- 仅允许小写字母、数字、下划线 -- 首字符不能为数字 -- **禁止使用 `.`** - ---- - -## 4. 当前已落地事件:`receiving_completed` - -### 4.1 业务含义 - -当仓库完成一张收货单时,系统会向绑定的 WebHook 推送一条 `receiving_completed` 通知。 - -### 4.2 推送目标 - -由 `wms_notification_webhook` 决定: - -- 先匹配仓库 `warehouseId` 绑定的接口 -- 若传了 `storeId / ownerId`,再匹配货主绑定的接口 -- `events` 命中以下任一规则即可推送: - - `all` - - `*` - - `receiving_completed` - ---- - -## 5. 请求方式 - -对外固定使用: - -```http -POST -Content-Type: application/json -``` - ---- - -## 6. 收货完成通知 payload - -### 6.1 字段说明 - -| 字段 | 类型 | 说明 | -|---|---|---| -| `traceId` | `string` | 通知追踪 ID | -| `event` | `string` | 固定为 `receiving_completed` | -| `businessName` | `string` | 固定为 `receiving` | -| `warehouseId` | `number` | 仓库 ID | -| `storeId` | `number \| null` | 货主 ID,可为空 | -| `businessId` | `number` | 收货单 ID | -| `occurredAt` | `string` | 发生时间,ISO 格式 | -| `subject` | `object` | 当前主体(仓库) | -| `store` | `object` | 货主信息 | -| `sender` | `object` | 操作人信息 | -| `receivers` | `array` | 接收者占位 | -| `message` | `object` | 消息主体 | -| `metadata` | `object` | 业务扩展信息 | - -### 6.2 示例(带完成报表) - -```json -{ - "traceId": "notice_1775368780099_c6fb8643", - "event": "receiving_completed", - "businessName": "receiving", - "warehouseId": 100000, - "storeId": 200000, - "businessId": 12345, - "occurredAt": "2026-04-05T12:00:00.000Z", - "subject": { - "id": 100000, - "type": "warehouse", - "name": "广州仓", - "code": "", - "config": { - "max_notice_webhook_count": 5, - "default_express_code": "STO", - "default_platform_code": "TB" - } - }, - "store": { - "id": 200000, - "name": "某货主", - "businessLicense": "9144XXXXXXXXXXXX", - "storeRemask": "华南货主" - }, - "sender": { - "id": 10001, - "name": "张三" - }, - "receivers": [], - "message": { - "type": "file", - "title": "收货单RCV202604050001已完成", - "content": "收货单RCV202604050001已完成,匹配商品10件,未匹配商品0件,总数量120,完成人张三。", - "url": "https://cdn.example.com/收货完成_RCV202604050001.xlsx", - "fileName": "收货完成_RCV202604050001.xlsx", - "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", - "body": "收货单RCV202604050001已完成,匹配商品10件,未匹配商品0件,总数量120,完成人张三。" - }, - "metadata": { - "receivingId": 12345, - "receivingNumber": "RCV202604050001", - "warehouseId": 100000, - "storeId": 200000, - "stats": { - "total_details": 10, - "matched_details": 10, - "unmatched_details": 0, - "total_quantity": 120 - }, - "completionReport": { - "fileKey": "收货完成_RCV202604050001.xlsx", - "url": "https://cdn.example.com/收货完成_RCV202604050001.xlsx" - } - } -} -``` - ---- - -## 7. 返回值约定 - -针对当前旧回调接口的约定: - -- 返回 `1` = **成功** -- 返回 `0` = **失败** - ---- - -## 8. 当前可信结论 - -已验证: - -- `GET` 调用旧接口地址可返回 `1` -- `POST {}` 可返回 `1` -- 手工最小 probe JSON 可返回 `1` - -因此: - -> 若 `receiving_completed` 的统一通知实际推送触发远端错误,优先判断为 **payload 字段结构差异导致的远端解析异常**。 - ---- - -## 9. 当前已落地事件:`store_warehouse_print_quantity_adjusted` - -### 9.1 业务含义 - -当仓库侧对某个货主签约关系执行人工面单余额调整后,系统会向相关 WebHook 推送一条 `store_warehouse_print_quantity_adjusted` 通知。 - -### 9.2 推送目标 - -由 `wms_notification_webhook` 决定: - -- 匹配签约仓库 `warehouseId` 绑定的接口 -- 若签约中带有 `storeId`,同步匹配货主绑定的接口 -- `events` 命中以下任一规则即可推送: - - `all` - - `*` - - `store_warehouse_print_quantity_adjusted` - -### 9.3 metadata 关键字段 - -| 字段 | 类型 | 说明 | -|---|---|---| -| `contractId` | `number` | 签约关系 ID | -| `changeType` | `string` | 当前固定为 `manual_adjust` | -| `businessType` | `string \| null` | 业务类型预留字段 | -| `businessId` | `number \| null` | 业务关联 ID,预留给 `wms_order_express.id` | -| `changeQuantity` | `number` | 本次调整值,整数,可正可负 | -| `balanceBefore` | `number` | 调整前余额 | -| `balanceAfter` | `number` | 调整后余额 | -| `reason` | `string` | 调整缘由 | - ---- - -## 10. 后续事件扩展建议 - -下一步可继续补充: - -- `receiving_cancelled` -- `order_cancelled` -- `stock_low` -- `stock_changed` -- `entry_order_created` -- `entry_order_completed` - -保持原则: - -> **一个业务事件 = 一个对外通知 event** diff --git a/docs/notification-webhook-capability.md b/docs/notification-webhook-capability.md deleted file mode 100644 index 3b235f3..0000000 --- a/docs/notification-webhook-capability.md +++ /dev/null @@ -1,335 +0,0 @@ -# 统一消息通知能力文档(草案) - -## 1. 目标 - -用于沉淀 WMS 统一消息通知能力的接口结构、数据模型、事件订阅规则与对外推送格式,作为后续构建“消息通知中心 / WebHook 能力”的基础文档。 - ---- - -## 2. 能力结构 - -当前统一发送入口: - -```js -await ctx.service.systems.notice.send(options) -``` - -当前调用链: - -```text -业务服务 - -> ctx.service.systems.notice.send(options) - -> normalizePayload(options) - -> findMatchedWebhooks(payload) - -> GenericWebhookDriver.send({ hook, payload }) - -> POST JSON 到外部 hook_url -``` - -代码位置: - -- `app/service/systems/notice/index.js` -- `app/service/systems/notice/drivers/generic.js` -- `app/model/notification_webhook.js` - ---- - -## 3. 相关数据模型 - -### 3.1 `wms_notification_webhook` - -用于保存主体绑定的外部 WebHook 配置。 - -核心字段: - -| 字段 | 说明 | -|---|---| -| `store_id` | 主体 ID,可绑定到仓库主体或货主主体 | -| `hook_name` | WebHook 名称 | -| `hook_type` | WebHook 类型,当前支持 `customize` / `wecom` | -| `hook_url` | 推送目标地址 | -| `events` | 订阅事件列表 | -| `status` | 状态,`1=启用`,`0=禁用` | -| `remark` | 备注 | - -### 3.2 `wms_store.subject_config` - -用于保存主体级通知配置。 - -当前已使用字段: - -| 字段 | 说明 | -|---|---| -| `max_notice_webhook_count` | 当前主体最多允许绑定 / 触达的消息推送接口数量,默认 `5` | -| `default_express_code` | 默认快递编码,默认 `STO` | -| `default_platform_code` | 默认平台编码,默认 `TB` | - ---- - -## 4. 事件能力结构建议(独立于 `/system`) - -当前更推荐的能力组织方式是:**内部业务事件 = 对外通知方法标识**,而不是先对外包装成 `/system` method。 - -推荐结构: - -```text -系统内部业务事件 - -> ctx.service.systems.notice.send(options) - -> payload 归一化 - -> 查找匹配的 webhook - -> 按 hook_type 选择 driver - -> 推送到外部系统 -``` - -当前已落地示例: - -| event | 说明 | -|---|---| -| `receiving_completed` | 收货单完成通知 | -| `order_cancel_intercepted` | 订单取消失败并触发拦截执行的通知 | - -> 当前正式注册的业务事件包括 `receiving_completed`、`order_cancel_intercepted`;`all` / `*` 作为通配订阅值继续保留。收货完成事件的独立 API 文档见:`docs/notification-event-api.md`。 - ---- - -## 5. 对内统一发送入参 - -`notice.send(options)` 推荐入参如下: - -| 参数 | 类型 | 必填 | 说明 | -|---|---|---:|---| -| `warehouseId` | `number` | 是 | 仓库 ID | -| `storeId` | `number` | 否 | 货主 ID,可空 | -| `ownerId` | `number` | 否 | 货主 ID 别名,可空 | -| `businessName` | `string` | 是 | 业务名称,如 `receiving` | -| `event` | `string` | 否 | 具体事件,如 `receiving_completed` | -| `messageType` | `string` | 是 | `text / image / file`,兼容中文 | -| `title` | `string` | 否 | 消息标题 | -| `content` | `string/object` | 否 | 消息正文 | -| `url` | `string` | 条件必填 | 图片 / 文件类型时必填 | -| `businessId` | `number|string` | 否 | 业务单据 ID | -| `subject` | `object` | 否 | 主体信息 | -| `sender` | `object` | 否 | 发送者信息 | -| `receivers` | `array` | 否 | 接收者信息 | -| `metadata` | `object` | 否 | 扩展元数据 | - -### 5.1 入参约束 - -- `warehouseId` **必传** -- `storeId / ownerId` **允许为空** -- `messageType = image / file` 时,`url` **必填** -- `event` 命名仅允许小写字母、数字、下划线,且首字符不能为数字;**禁止使用 `.`** - ---- - -## 6. 对外统一推送 payload - -当前对外固定为:`POST + application/json` - -示例: - -```json -{ - "traceId": "notice_xxx", - "event": "receiving_completed", - "businessName": "receiving", - "warehouseId": 100000, - "storeId": 200000, - "businessId": 123, - "occurredAt": "2026-04-05T12:00:00.000Z", - "subject": { - "id": 100000, - "type": "warehouse", - "name": "广州仓", - "code": "", - "config": { - "max_notice_webhook_count": 5, - "default_express_code": "STO", - "default_platform_code": "TB" - } - }, - "store": { - "id": 200000, - "name": "某货主", - "businessLicense": "9144XXXXXXXXXXXX", - "storeRemask": "华南货主" - }, - "sender": {}, - "receivers": [], - "message": { - "type": "text", - "title": "收货完成", - "content": "收货单已完成", - "url": "", - "fileName": "", - "mimeType": "", - "body": "收货单已完成" - }, - "metadata": { - "source": "system" - } -} -``` - ---- - -## 7. 事件订阅规则 - -`events` 字段建议使用数组。 - -支持写法: - -| 写法 | 含义 | -|---|---| -| `all` | 接收全部已注册通知 | -| `*` | 兼容旧配置,等价于 `all` | -| `receiving_completed` | 只接收收货完成事件 | -| `order_cancel_intercepted` | 只接收订单取消拦截事件 | - -> 若需新增其他事件,必须先在 `app/model/notification_webhook.js` 完成注册,否则发送入口会直接拒绝。 - -当前订单取消拦截通知由 `app/service/qimenMethods/order.js` 在拣货状态或打印状态未结束时发送,事件码为 `order_cancel_intercepted`。 - ---- - -## 8. 命中与分发规则 - -当前 `findMatchedWebhooks(payload)` 逻辑: - -1. 先判断 `warehouseId`,并查询该仓库主体绑定的启用接口 -2. 若 `storeId / ownerId` 非空,再查询该货主绑定的启用接口 -3. 过滤条件: - - `status = 1` - - `events` 命中当前消息 -4. 去重规则: - - 优先按 `id` - - 无 `id` 时按 `hook_url` -5. 最终按 `subject_config.max_notice_webhook_count` 限制最大推送数量 - ---- - -## 9. 货主信息补充与缓存 - -若传了 `storeId / ownerId`,当前会补齐货主信息: - -- `wms_store.business_license` -- `wms_store_warehouse.store_remask` - -缓存键: - -```text -warehouse:{warehouseId}store:{storeId}:info -``` - -缓存 TTL: - -```text -600 秒 -``` - -查询顺序: - -1. 优先读缓存 -2. 缓存未命中再查数据库 -3. 查到后回填缓存 -4. 若为空,则推送字段也保持空字符串 - ---- - -## 10. 回调返回值约定 - -对于现有旧接口(如 `notic`、`notic2`)的可信判定约定: - -- 返回 `1` = **成功** -- 返回 `0` = **失败** - ---- - -## 11. 当前可信结论 - -已验证: - -- `GET` 请求可通 -- `POST` 请求可通 -- `POST {}` 可返回 `1` -- 手工最小 probe payload 可返回 `1` - -因此: - -> 若统一 `notice.send()` 的实际推送触发远端报错,优先判断为 **payload 字段结构差异导致的远端解析问题**,而不是地址或请求方式问题。 - ---- - -## 12. 新增功能需要通知时怎么接入 - -当其他功能模块需要新增通知时,建议按下面 4 步接入,避免各自重复造轮子: - -### 12.1 注册事件 - -先在 `app/model/notification_webhook.js` 的 `AVAILABLE_EVENTS` 中登记新的事件编码。 - -要求: - -- 事件名仅允许小写字母、数字、下划线 -- 首字符不能为数字 -- **禁止使用 `.`** -- 未注册的事件,`notice.send()` 会直接拒绝发送 - -### 12.2 在业务 service 调用统一入口 - -在实际业务 service 中调用: - -```js -await ctx.service.systems.notice.send({ - warehouseId, - storeId, // 可选,也可传 ownerId - businessName: 'your_business', - event: 'your_event_code', - messageType: 'text', - title: '通知标题', - content: '通知内容', - businessId, - subject, - sender, - metadata, -}); -``` - -接入原则: - -- `warehouseId` 必传,`storeId / ownerId` 可空 -- 业务侧只负责组装业务语义并调用统一入口 -- 重试、分发、失败日志由 `app/service/systems/notice/index.js` 统一处理 -- 如需图片 / 文件通知,补充 `url`、`fileName`、`mimeType` - -### 12.3 测试验证 - -至少补 2 类验证: - -1. **notice 能力测试**:确认事件注册、WebHook 命中、payload 结构与失败处理符合预期 - - 参考:`test/app/service/systems/notice.test.js` -2. **业务回归测试**:确认业务节点确实会触发通知调用 - - 参考:`test/app/service/systems/storage.receiving.report.test.js` - -若对接的是外部地址,还应额外确认: - -- 返回结果是否符合成功约定(如 `1` / `ok` / `errcode=0`) -- 对方是否能正确解析当前 JSON payload - -### 12.4 文档同步 - -接入完成后,至少同步以下文档: - -- 本文档:补能力边界、接入规则或命中说明 -- `docs/notification-event-api.md`:新增事件说明与 payload 示例 -- 若对外暴露了新的 `/system` 接口或 method,再按需同步 `methods/*.json` - -## 13. 后续扩展建议 - -建议后续继续补充: - -1. 通知发送日志表 -2. 重试队列 / 死信队列 -3. 回调签名与鉴权 -4. WebHook 健康检查 -5. 失败告警与监控面板 -6. system 接口文档同步到 `methods/system.json` diff --git a/docs/order-cancel-db-checklist.md b/docs/order-cancel-db-checklist.md deleted file mode 100644 index d71f579..0000000 --- a/docs/order-cancel-db-checklist.md +++ /dev/null @@ -1,97 +0,0 @@ -# 订单取消 / 状态机 — 库表核对清单(§0.7 执行用) - -> 用途:实施 `order_todo.md` **§2.3a(取消进 M4)** 前,对 **`wms_order_delivery` 及分表** 做只读核对。 -> 不改变数据库;核对结果记录在工单或 `order_todo.md` 修订记录。 - -**PowerShell 提示**:`db-query.ps1` 若遇 **`ConvertFrom-Json` 无效 JSON**(中文注释导致编码问题),可在同一会话先执行 **`chcp 65001`** 再跑查询。 - -## 1. 列出本库所有发货单相关表 - -```sql -SELECT TABLE_NAME -FROM INFORMATION_SCHEMA.TABLES -WHERE TABLE_SCHEMA = DATABASE() - AND ( - TABLE_NAME = 'wms_order_delivery' - OR TABLE_NAME REGEXP '^wms_order_delivery_[0-9]+(_history)?$' - ) -ORDER BY TABLE_NAME; -``` - -## 2. 对每张表核对关键列是否存在 - -将 `YOUR_TABLE` 替换为上一步的表名(含模板表 `wms_order_delivery` 与各仓 `wms_order_delivery_{wh}` / `_history`)。 - -```sql -SELECT COLUMN_NAME, DATA_TYPE, COLUMN_TYPE, IS_NULLABLE, COLUMN_COMMENT -FROM INFORMATION_SCHEMA.COLUMNS -WHERE TABLE_SCHEMA = DATABASE() - AND TABLE_NAME = 'YOUR_TABLE' - AND COLUMN_NAME IN ( - 'status', - 'intercept_status', - 'step', - 'outbound_status', - 'inspection_status', - 'delivery_time', - 'updated_at', - 'create_at' - ) -ORDER BY COLUMN_NAME; -``` - -## 3. 结论填写(人工) - -| 检查项 | 是否满足「取消进 M4」筛选与展示 | -|--------|----------------------------------| -| `status` 含 `cancel` 枚举(与 ORM 一致) | | -| `intercept_status` 含 `cancelled` 等 | | -| `step` 存在且含「9=已关闭」语义 | | -| 若产品要求 **独立「取消进 M4」列** | 缺则走 migration + 模型 + 工厂 DDL | - -## 4. 参考 - -- 模型枚举源:`app/model/order_delivery.js`(`StatusEnum`、`step` 注释) -- 规划说明:仓库根目录 `order_todo.md` §0.7、§2.3a - ---- - -## 5. wms-db-agent 诊断记录(本机一次抽样,2026-04-10) - -> 工具:`script/db-query.ps1`,client **`wms`**,`DATABASE() = wms`。以下为 **只读** 结果摘要;其它环境须自行重跑 §1~§2。 - -### 5.1 匹配到的表 - -| TABLE_NAME | -|------------| -| `wms_order_delivery`(基表/模板) | -| `wms_order_delivery_100000` | -| `wms_order_delivery_1000028` | - -本库本次 **未发现** `*_history` 表。 - -### 5.2 目标列是否存在(Y/N) - -| TABLE_NAME | status | intercept_status | step | outbound_status | inspection_status | -|------------|:------:|:----------------:|:----:|:---------------:|:-----------------:| -| `wms_order_delivery` | Y | **N** | Y | **N** | **N** | -| `wms_order_delivery_100000` | Y | Y | Y | Y | Y | -| `wms_order_delivery_1000028` | Y | Y | Y | Y | Y | - -`delivery_time` / `updated_at` / `create_at` 三张表均有(基表 `updated_at`/`create_at` 为 YES)。 - -### 5.3 与 §0.7 / §2.3a 的对照结论 - -- **分表**(`_100000`、`_1000028`):§0.7 所列 **`status` / `intercept_status` / `step` / `outbound_status` / `inspection_status`** 均存在;`intercept_status` 含 **`cancelled`**,`status` 含 **`cancel`**;**可先不增列**,用组合条件做「取消进 M4」筛选(产品确认 WHERE 口径即可)。 -- **基表** `wms_order_delivery`:**缺** `intercept_status`、`outbound_status`、`inspection_status`;**业务筛选勿依赖基表**,以 **`wms_order_delivery_{warehouseId}`** 为准。 -- **枚举差异**:不同物理表上 **`status` 的 enum 集合不一致**(基表与分表、分表之间均有差异);规则与迁移须 **按仓/按表** 评估,勿假设全局一致。 -- **全量**:当前仅抽样 2 张分表;生产请对 **全部** `wms_order_delivery_*` 重跑本清单;若有 **`_history`** 须单独对齐列集。 - -### 5.4 §3 结论栏(代填,可改) - -| 检查项 | 是否满足「取消进 M4」筛选与展示 | -|--------|----------------------------------| -| `status` 含 `cancel` 枚举(与 ORM 一致) | **分表:是**;基表:部分(见上 enum 差异) | -| `intercept_status` 含 `cancelled` 等 | **分表:是**;**基表:无此列** | -| `step` 存在且含「9=已关闭」语义 | **是**(int NOT NULL,注释一致) | -| 若产品要求 **独立「取消进 M4」列** | **未检出有**;若需要仍须 migration(见 `order-delivery-migration-impact.md`) | diff --git a/docs/order-delivery-migration-impact.md b/docs/order-delivery-migration-impact.md deleted file mode 100644 index d2ebf79..0000000 --- a/docs/order-delivery-migration-impact.md +++ /dev/null @@ -1,62 +0,0 @@ -# `wms_order_delivery*` / `wms_order_items*` 库表变更 — 影响面分析(供决策) - -> 目的:回答「改库是否影响当前所有涉及 order 发货单表的逻辑」;**未连真实库**,结论基于代码静态分析。 -> 关联:`order_todo.md` §0.7、§2.3a;核对清单 `docs/order-cancel-db-checklist.md`。 - ---- - -## 1. 结论摘要(是否可直接做迁移) - -| 变更类型 | 对现有逻辑的典型影响 | 建议 | -|----------|----------------------|------| -| **仅核对列已存在、不做 DDL** | 无 | **推荐先做**(清单 `order-cancel-db-checklist.md`) | -| **新增可空列 + 默认值**(`NULL` 默认 / `DEFAULT`) | Sequelize `create`/`update`/`find` 一般 **不崩**;未赋值的 `create` 不写该列则用库默认 | **低面影响**,但仍须 **同步** `app/model/order_delivery.js` + `order_delivery_factory.js` 的 `createPhysicalTable` DDL,且 **所有已存在分表** 需同一 migration 补列 | -| **新增 NOT NULL 无默认** | 旧 `create`/`bulkCreate` 可能 **插入失败** | **高面影响**,**禁止**在未改全链路前做 | -| **改 ENUM 取值 / 删列 / 改列类型** | `order.*` 列表 where、奇门/入库、报表可能 **全链路受影响** | **高面影响**,须单独评审与回归 | -| **仅改索引 / 注释**(不改列语义) | 一般低;大表加索引注意锁表 | 可个案评估 | - -**当前结论(在未跑 §0.7 清单、未选定「取消进 M4」专用列名之前):** -**不在仓库内自动提交新的 `ALTER` migration。** 代码侧已具备 `status.cancel`、`intercept_status.cancelled`、`step`(含 9 关闭)等枚举(见 `order-state-machine-dictionary.md`),**若跑库确认列已齐全,则「取消进 M4」可先不增列,仅做应用筛选逻辑** — 此时 **无需表迁移**。 -若跑库确认 **缺列** 或产品 **强制** 要独立标记列 → **属有面影响变更**,请在你确认 **列名、类型、默认值、是否只加 current 或含 history** 后再做 migration。 - -**(已更新)** 本机 `wms` 库经 **wms-db-agent** 只读抽样结果见 **`docs/order-cancel-db-checklist.md` §5**:两张分表目标列齐全,**可先不增列**;基表缺列、勿作业务筛选;全量仓与 `_history` 须另跑。 - ---- - -## 2. 代码侧「会吃到表结构」的路径 - -### 2.1 动态模型来源(关键) - -- `OrderDeliveryFactory` / `OrderItemsFactory` 使用 **`app.model.OrderDelivery.rawAttributes`**(及 `OrderItems`)**动态 `define` 每张分表**。 -- **新建物理表**时,`createPhysicalTable` 内 **手写 DDL 片段** 与模型字段 **必须长期一致**,否则新仓新表与 ORM 不一致。 - -### 2.2 业务入口(非穷举,均为 `getCurrentModel` 链) - -| 区域 | 文件 | -|------|------| -| System 订单 method | `app/service/systemMethods/order/*.js`(经 `base.js#getOrderModels`) | -| 业务发货单 | `app/service/systems/delivery_order.js`(`create` / `update` / `bulkCreate` 明细等) | -| 奇门 | `app/service/qimenMethods/deliveryorder.js` | -| 测试 / 探针 | `app/service/apiMethods/test.js`(命名 `WmsOrderDeliveryFactory` 需与挂载一致,否则仅测试路径) | - -### 2.3 写入方式 - -- `DeliveryModel.create(orderData)`、`OrderItemsModel.bulkCreate(lineData)`:**对象字段驱动**;新增 **可空** 列且模型已声明时,旧代码路径 **通常无需改** 即可插入。 - ---- - -## 3. 若你决定「要做加列迁移」时的必做清单 - -1. 产品确认:**列名、含义、是否可空、默认值、是否写 history 表**。 -2. Migration:`findOrderDeliveryTables` 风格 **遍历** `wms_order_delivery` / `wms_order_delivery_*`(及若需要则 `wms_order_items_*`)。 -3. `app/model/order_delivery.js` 增加字段定义。 -4. `app/model/order_delivery_factory.js` 中 **`createPhysicalTable`** 同步列定义。 -5. 回归:`npm run test:local` 中与 `delivery_order` / `order` 相关用例;奇门若有联调则单独测。 - ---- - -## 4. 修订 - -| 日期 | 说明 | -|------|------| -| 2026-04-10 | 初版:静态影响面结论;**未提交 migration** | diff --git a/docs/order-state-machine-dictionary.md b/docs/order-state-machine-dictionary.md deleted file mode 100644 index 658ef31..0000000 --- a/docs/order-state-machine-dictionary.md +++ /dev/null @@ -1,45 +0,0 @@ -# 订单发货单 — 状态机字段字典(骨架 v0) - -> **单一事实来源(代码)**:`app/model/order_delivery.js` 内 `StatusEnum` 与 `step` 定义。 -> 本文档为 **v0 骨架**:便于产品 / 数仓 / 报表对齐;**与数仓字段映射、变更登记** 在后续迭代补全(见 `order_todo.md` §5.2)。 - -## 1. 主状态与步骤 - -| 字段 | 类型(ORM) | 枚举或取值 | 说明(摘自模型注释) | -|------|-------------|------------|----------------------| -| `status` | ENUM | `pedding`, `created`, `cancel`, `error` | 订单状态 | -| `step` | INTEGER | `0` 未审核,`1` 已审核,`2` 处理中,`3` 驳回/异常,`4` 配送中,`5` 已完成,`9` 已关闭 | 订单步骤 | - -## 2. 各环节状态机(ENUM) - -| 字段 | 枚举值 | -|------|--------| -| `sync_status` | `padding`, `fin`, `error` | -| `post_status` | `padding`, `fin`, `timeout`, `error`, `none` | -| `storage_status` | `padding`, `fin`, `error`, `none` | -| `pick_status` | `padding`, `fin`, `error`, `none` | -| `pack_status` | `none`, `padding`, `fin`, `error` | -| `inspection_status` | `none`, `padding`, `running`, `fin`, `error` | -| `print_status` | `none`, `padding`, `fin`, `error` | -| `claim_status` | `none`, `padding`, `fin`, `error` | -| `outbound_status` | `none`, `padding`, `fin`, `error` | -| `lock_status` | `none`, `warehouse`, `store` | -| `intercept_status` | `none`, `requesting`, `requested`, `intercepting`, `intercepted_in_transit`, `intercepted_at_warehouse`, `returning`, `returned`, `delivered_by_mistake`, `timeout`, **`cancelled`**, `failed`, `exception` | - -## 3. 其它与展示相关(非 ENUM) - -| 字段 | 说明 | -|------|------| -| `delivery_time` | 发货时间;与 M6 出库时间策略相关 | -| `create_at` / `updated_at` | 创建 / 更新时间 | - -## 4. 待产品补充(v1+) - -- 「取消进 M4」专用标记:若不用 `status`/`step`/`intercept_status` 组合表达,则 **新增列** 后的字典条目与数仓同步表。 -- 与奇门 **不同步** 的克隆续单字段(见 `order_todo.md` §2.4)。 - -## 5. 修订 - -| 版本 | 说明 | -|------|------| -| v0 | 自 `order_delivery.js` 摘录枚举骨架,无 DB 变更 | diff --git a/docs/order-workbench-list-api.md b/docs/order-workbench-list-api.md deleted file mode 100644 index 7b99c0a..0000000 --- a/docs/order-workbench-list-api.md +++ /dev/null @@ -1,188 +0,0 @@ -# 订单工作台 List 接口说明 - -本文档说明订单工作台(Order Workbench)中可用的 list 接口、参数约定、返回结构与行为要点。 - -**变更记录** -- 本次已在 methods/system.json 中补充以下 method 定义,并在 methods/changes/system.json 中追加变更记录(参见变更文件),用于对外说明新增的 list 接口与分页/where 支持。 - -**新增/确认的接口(method 名称,主入口)** -- order.list —— 订单工作台总列表入口(汇总所有分组) -- order.reviewOrder.list —— 待审核订单工作台(step=0) -- order.pendingOrder.list —— 待处理订单工作台(step in [1,2]) -- order.expectionOrder.list —— 待处理异常订单工作台(step=3) -- order.entrustOrder.list —— 委托外仓订单工作台(outsourced 模型) -- order.deliveryOrder.list —— 配送订单工作台(dispatch 模型,dispatch_lane=m4) -- order.deliveryExpectionOrder.list —— 配送异常订单工作台(dispatch 模型,dispatch_lane=m5) -- order.archiveOrder.list —— 归档订单工作台(history 模型) - -兼容说明:代码中存在若干旧兼容入口(例如 getreviewOrderlist、getdeliveryOrderlist、getpendingOrderlist、getexpectionOrderlist、getentrustOrderlist、getarchiveOrderlist 等),这些为兼容旧调用保留的旧名入口,不作为首选主入口;建议新调用使用上文列出的主入口。 - -**工作台语义(简要)** -- order.list:总列表入口,返回跨分组的订单集合,适用于需要不分组的通用搜索/分页场景。 -- reviewOrder:待审核(审核步骤为未审核)工作台,用于审核操作筛选与展示(默认 step=0)。审核提交接口仅接收 ids,批量审核,严格同仓校验,不做兼容。 -- pendingOrder:待处理工作台,通常包含需要人工或系统继续处理的订单(默认 step in [1,2])。 -- expectionOrder:异常工单集合(默认 step=3),用于定位异常状态订单。 -- entrustOrder:委托外仓相关订单,使用 outsourced 模型。 -- deliveryOrder / deliveryExpectionOrder:配送相关工作台,使用 dispatch 模型,分别以 dispatch_lane=m4 / m5 筛选。 -- archiveOrder:归档历史订单,使用 history 模型。 - -实现要点(参考实现位于 app/service/systemMethods/order/*): -- 模块实现会根据模块名选择不同物理模型(current / dispatch / outsourced / history),由 OrderBaseService#getOrderModel 决定。 -- 每个模块还定义了 `defaultWhere`(例如 reviewOrder 的 step=0 等),请求的 `where` 会与模块默认条件合并后一起用于构造最终查询。 - -参数说明(公共约定) -- pagination: object - - pagination.page: number(可选),页码,从 1 开始,默认 1。 - - pagination.pageSize: number(可选),每页条数,默认 20。注意:服务端对 pageSize 做上限截断,最大不可超过 200(见下)。 -- where: object(可选) - - 统一的筛选条件对象;支持两种写法: - - 标准化结构:{ field: { operator: 'eq'|'in'|'like'|..., value: ..., type?: 'string'|'number' } } - - 简写:{ field: value }(会被自动转换为 { operator: 'eq', value } 或在传数组时转换为 in) - - 服务端会先对 where 做 normalize(兼容简写与 values 字段),再走 parseWhereConditions 生成底层查询条件,最后与模块的 defaultWhere 合并(后者优先级低于请求入参)。 - - 常见可用字段:id、delivery_order_code、order_status、dispatch_lane、quickWhere 等(具体过滤字段以实现解析器支持为准)。 -- sort: object(可选) - - 支持 sortField / sortOrder 或 field / order;实现层会映射到允许的字段集合(如 id、step、status、delivery_time、updated_at 等),默认按 updated_at DESC, id DESC。 - -分页/大小限制 -- 默认 pageSize=20。 -- 最大 pageSize: 200(服务端在 normalizePagination 中对 pageSize 做截断,防止单次请求返回过大数据)。调用方仍应合理控制 pageSize,避免前端一次性请求过多数据。 - -返回结构(公共约定) -- list: array — 当前页的记录数组(每项为订单对象的序列化行,字段视具体模型与序列化而定)。 -- pagination: object - - pagination.page: number — 当前页 - - pagination.pageSize: number — 每页条数(实际返回值为服务端截断后的值) - - pagination.total: number — 符合条件的总记录数 - - pagination.totalPages: number - - pagination.hasPrevious / hasNext: boolean - -订单列表 raw 字段字典(通用) -- 说明:以下字段为所有订单列表的 raw 基础字段;`order.deliveryOrder.list` 和 `order.deliveryExpectionOrder.list` 额外包含 `dispatch_lane`;服务层还会补充 `express_numbers` 与 `waybill_codes` 两个派生字段,二者内容一致,都是该订单绑定的多个快递号。 - -| 字段 | 类型 | 中文语义 | 枚举/说明 | -| --- | --- | --- | --- | -| id | number | 订单主键 ID | 订单记录主键 | -| delivery_order_code | string | 发货单号 | 订单单号 | -| pre_delivery_order_code | string | 预发货单号 | 预发货阶段单号 | -| pre_delivery_order_id | string | 预发货单ID | 预发货记录关联 ID | -| order_type | string | 订单类型 | 业务类型标识 | -| warehouse_code | string | 仓库编码 | 仓库基础编码 | -| order_flag | string | 订单标记 | 订单标签/标记信息 | -| source_platform_code | string | 来源平台编码 | 原始平台编码 | -| source_platform_name | string | 来源平台名称 | 原始平台名称 | -| sys_platform_code | string | 系统平台编码 | 系统内平台编码 | -| sys_platform_name | string | 系统平台名称 | 系统内平台名称 | -| create_at | string | 创建时间 | ISO 时间字符串 | -| delete_at | string | 删除时间 | ISO 时间字符串,通常为空 | -| updated_at | string | 更新时间 | ISO 时间字符串 | -| place_order_time | string | 店铺创建订单时间 | 平台下单时间 | -| pay_time | string | 支付时间 | 支付完成时间 | -| pay_no | string | 支付单号 | 支付流水号 | -| service_code | string | 集包服务编码 | 集包/服务编码 | -| operator_name | string | ERP审核人 | 审核人姓名 | -| operate_time | string | ERP审核时间 | 审核时间 | -| delivery_time | string | 发货时间 | 发货完成时间 | -| shop_nick | string | 店铺名称 | 店铺昵称 | -| seller_nick | string | 卖家名称 | 卖家昵称 | -| buyer_nick | string | 买家名称 | 买家昵称 | -| total_amount | number | 订单总金额 | 金额字段,保留两位小数 | -| item_amount | number | 商品总金额 | 金额字段,保留两位小数 | -| discount_amount | number | 订单折扣金额 | 金额字段,保留两位小数 | -| freight | number | 快递费用 | 金额字段,保留两位小数 | -| ar_amount | number | 应收金额 | 金额字段,保留两位小数 | -| got_amount | number | 已收金额 | 金额字段,保留两位小数 | -| service_fee | number | COD服务费 | 金额字段,保留两位小数 | -| logistics_code | string | 物流公司编码 | 物流公司编码 | -| logistics_name | string | 物流公司名称 | 物流公司名称 | -| sys_logistics_code | string | 系统物流公司编码 | 系统内物流编码 | -| sys_logistics_name | string | 系统物流公司名称 | 系统内物流名称 | -| express_code | string | 面单号前置 | 面单号前缀 | -| logistics_area_code | string | 快递区域编码 | 大头笔/区域编码 | -| delivery_type | string | 发货服务类型 | 发货方式 | -| is_urgency | enum | 是否紧急 | Y=是,N=否 | -| invoice_flag | enum | 是否需要发票 | Y=需要,N=不需要 | -| status | enum | 订单状态 | pedding=待处理,created=已创建,cancel=已取消,error=异常 | -| name | string | 收件人姓名 | 收件人 | -| zip_code | string | 收件人邮编 | 邮编 | -| tel | string | 收件人电话 | 电话号码 | -| mobile | string | 收件人移动电话 | 手机号 | -| email | string | 收件人邮箱 | 邮箱 | -| country_code | string | 国家编码 | 国家/地区编码 | -| province | string | 省份 | 收件地址省 | -| city | string | 城市 | 收件地址市 | -| area | string | 区 | 收件地址区 | -| town | string | 镇 | 收件地址镇 | -| detail_address | string | 详细地址 | 街道/门牌详情 | -| id_type | string | 证件类型 | 证件类型 | -| id_number | number | 证件号码 | 证件号 | -| oaid | string | OAID | 设备/终端标识 | -| sync_status | enum | 同步状态 | padding=待同步,fin=完成,error=失败 | -| store_id | number | 货主ID | 货主主键 | -| store_remark | string | 货主备注 | 来自 wms_store_warehouse.store_remask,服务层按 store_id+warehouse_id 聚合填充 | -| warehouse_id | number | 仓库ID | 仓库主键 | -| from_key | number | 来源键 | 来源系统键值 | -| items | string | 商品JSON字符串 | 原始商品明细 JSON | -| items_count | number | 商品种类数 | SKU 种类数 | -| items_total | number | 商品总数 | 商品件数总和 | -| items_weight | number | 总重量(kg) | 总重量 | -| items_hash | string | MD5哈希值(32位) | 商品明细哈希 | -| items_crc | number | CRC32校验码 | 商品明细校验码 | -| wave_id | number | 波次ID | 0 表示未分配 | -| wave_no | string | 波次号 | 空字符串表示未分配 | -| post_status | enum | 分配快递号状态机 | padding=处理中,fin=完成,timeout=超时,error=失败,none=未开始 | -| storage_status | enum | 分配储位状态机 | padding=处理中,fin=完成,error=失败,none=未开始 | -| pick_status | enum | 拣货状态机 | padding=处理中,fin=完成,error=失败,none=未开始 | -| pack_status | enum | 打包状态机 | none=未开始,padding=处理中,fin=完成,error=失败 | -| inspection_status | enum | 检验状态机 | none=未开始,padding=处理中,running=进行中,fin=完成,error=失败 | -| step | number | 订单步骤 | 0=未审核,1=已审核,2=处理中,3=驳回/异常,4=配送中,5=已完成,9=已关闭 | -| print_status | enum | 打印状态机 | none=未开始,padding=处理中,fin=完成,error=失败 | -| claim_status | enum | 领取状态机 | none=未开始,padding=处理中,fin=完成,error=失败 | -| outbound_status | enum | 出库状态机 | none=未开始,padding=处理中,fin=完成,timeout=超时,error=失败 | -| lock_status | enum | 锁定状态机 | none=未锁定,warehouse=仓库锁定,store=货主锁定 | -| intercept_status | enum | 拦截状态机 | none=未拦截,requesting=请求中,requested=已请求,intercepting=拦截中,intercepted_in_transit=运输中拦截成功,intercepted_at_warehouse=仓库拦截成功,returning=退回中,returned=已退回,delivered_by_mistake=误签收,timeout=超时,cancelled=已取消,failed=失败,exception=异常 | -| dispatch_lane | string | 配送通道/分区 | 仅配送相关列表可能出现,常用于区分 m4 / m5 等通道 | -| express_numbers | array[string] | 快递号列表 | 服务层聚合字段,内容来自 wms_order_express.waybill_code | -| waybill_codes | array[string] | 运单号列表 | 与 express_numbers 内容一致,为兼容前端使用保留 | - -补充说明 -- `express_numbers` 和 `waybill_codes` 都来自订单绑定的多条快递记录,适合前端直接渲染“多个快递号”。 -- `sys_platform_name`、`sys_logistics_name` 已由服务层归一化输出,前端无需再回表查询。 -- `dispatch_lane` 仅在 `order.deliveryOrder.list` / `order.deliveryExpectionOrder.list` 这两个配送类列表中出现;其余列表通常不返回该字段。 - -其他注意事项 -- `where` 的解析与支持的特殊字段由 parseWhereConditions 决定;若需要支持新的复杂筛选(如跨表/聚合条件),请先在解析器和后端模型中确认可支持的 specialFieldMap 与解析策略。 -- 推荐使用标准化 where 结构({ operator, value })以避免歧义;历史简写会被自动规范化,但可读性较差。 -- 兼容入口(get*)保留以兼容历史客户端,但文档与新开发均建议使用上述主入口方法名;兼容入口可能在不同 module 下存在重复实现(index + 子模块),以兼容不同调用路径。 - -方法清单(已在 methods/system.json 中登记) -- order.list -- order.reviewOrder.list -- order.pendingOrder.list -- order.expectionOrder.list -- order.entrustOrder.list -- order.deliveryOrder.list -- order.deliveryExpectionOrder.list -- order.archiveOrder.list - -是否需要补充其它文档同步? -- 建议同步更新: - - 若有门户/前端 API 文档站(自动生成或展示 methods/system.json 的地方),应部署或刷新以展现新增条目。 - - 若存在 SDK 或对接说明(如 qimen 或第三方对接文档),如使用到工作台 list 场景也建议补充示例请求与常用 where 范例。 - -示例请求(简要) - -请求体示例: -{ - "pagination": { "page": 1, "pageSize": 50 }, - "where": { "delivery_order_code": { "operator": "like", "value": "ABC" }, "create_time_start": { "value": "2026-04-01" } }, - "sort": { "sortField": "updated_at", "sortOrder": "DESC" } -} - -响应示例(简要): -{ - "list": [ /* 订单对象数组 */ ], - "pagination": { "page":1, "pageSize":50, "total":1234, "totalPages":25, "hasPrevious":false, "hasNext":true } -} - --- -文档维护者:WMS 文档代理 diff --git a/docs/order_todo.md b/docs/order_todo.md deleted file mode 100644 index e3119ec..0000000 --- a/docs/order_todo.md +++ /dev/null @@ -1,288 +0,0 @@ -# 订单工作台模块 — 规划草案(order_todo) - -> 状态:**计划**,供评审与补充;实现前需与产品、DBA、前端对齐。 -> 关联:`OrderDeliveryFactory` / `OrderItemsFactory`(current / history 物理表)、`order_delivery` / `order_items` 基模型、现有 `order.*` system method。 - ---- - -## 0. 当前订单表、模型、工厂与关联(代码现状分析) - -### 0.1 物理表与工厂命名 - -| 概念 | 物理表名模式 | 说明 | -|------|----------------|------| -| 发货单 current | `wms_order_delivery_{warehouseId}` | 按仓动态建表,`OrderDeliveryFactory.generateTableName(wh, 'current')` | -| 发货单 history | `wms_order_delivery_{warehouseId}_history` | 多 `archive_time` 字段与索引;**业务代码尚未写入/迁移** | -| 订单明细 current | `wms_order_items_{warehouseId}` | `OrderItemsFactory.generateTableName(wh, 'current')` | -| 订单明细 history | `wms_order_items_{warehouseId}_history` | 同上,待迁移任务 | - -基模型 `tableName` 为模板:`wms_order_delivery`、`wms_order_items`(用于 `rawAttributes` 复制到动态表)。 - -### 0.2 基模型 `OrderDelivery`(`app/model/order_delivery.js`) - -- **主键与业务键**:`id`,`delivery_order_code` + `store_id` + `warehouse_id` 唯一索引(动态表工厂内复刻)。 -- **货主 / 仓库**:`store_id`(货主)、`warehouse_id`(仓库);**创建时落 M1/M2 可依据货主(store)侧配置**(配置表/字段待产品定义,当前模型无显式「进审开关」字段)。 -- **状态机字段(枚举在模型内)**:`status`,`sync_status`,`post_status`,`storage_status`,`pick_status`,`pack_status`,`inspection_status`,`print_status`,`claim_status`,`outbound_status`,`lock_status`,`intercept_status`。 -- **业务辅助**:`step`(注释:0 未审核 / 1 已审核 / 2 处理中 / 3 驳回异常 / 4 配送中 / 5 已完成 / 9 已关闭)、`wave_id`、金额与地址收件人、`items`(TEXT JSON 字符串)、`items_hash` / `items_crc` / `items_count` 等。 -- **物流展示相关(主表冗余)**:`logistics_code`、`logistics_name`、`express_code`、`delivery_time` 等;**细粒度快递轨迹**见下文物理表 `wms_order_express`。 - -### 0.3 基模型 `OrderItems`(`app/model/order_items.js`) - -- **关联键**:`order_id` → 发货单 `id`;`item_code`、`item_id`、`stock_id`、`owner_code`、`plan_qty`、价格字段、`extend_props`(JSON)。 -- **索引**:`order_id`、`item_id`、`source_order_code`、`stock_id` 等。 - -动态明细表由工厂 `define` 时复制 `OrderItems.rawAttributes`,并 `copyAssociations` 自基模型。 - -### 0.4 工厂类职责 - -| 工厂 | 文件 | 职责摘要 | -|------|------|----------| -| `OrderDeliveryFactory` | `app/model/order_delivery_factory.js` | `getCurrentModel` / `getHistoryModel` / `getModelByTableName`;不存在则 `createPhysicalTable`;`setupAssociations` 将动态发货单与 **同仓同类型** 动态 `OrderItems` 做 `hasMany` / `belongsTo`;可选 `belongsTo` `Store`(货主/仓库别名) | -| `OrderItemsFactory` | `app/model/order_items_factory.js` | 同上;并发建表锁 `creatingTables`;动态表带 `timestamps: true` | - -**现状**:全仓业务查询路径普遍只调用 **`getCurrentModel`**;**`getHistoryModel` 无业务引用**。 - -### 0.5 其它订单相关物理表(非按仓工厂) - -| 模型 | 表名 | 与订单关系 | -|------|------|--------------| -| `OrderExpress` | `wms_order_express` | `order_id` 关联订单主键;运单、物流接口、星河签收/退回/拦截等标记。**未纳入** `OrderDeliveryFactory` 动态表;若配送域拆分需定义 **order_id 与仓、自然月分区** 的一致性(否则跨表 JOIN 成本高)。 | - -### 0.6 System 层与工厂衔接 - -- `app/service/systemMethods/order/base.js` 中 `getOrderModels(warehouseId)` **仅** `getCurrentModel` 取发货单 + 明细。 -- 列表类:`reviewOrder`、`pendingOrder`、`expectionOrder`、`deliveryOrder`、`archiveOrder` 等均基于上述 **current** 模型。 - -### 0.7 取消相关状态机(代码已有 vs 库表须核对) - -**代码侧(`app/model/order_delivery.js`)已具备、可用于「取消」语义的枚举取值包括:** - -| 位置 | 取值/说明 | -|------|-----------| -| `status` | 枚举含 **`cancel`**(订单状态) | -| `intercept_status` | 枚举含 **`cancelled`** 等拦截/关闭链路 | -| `step` | 整型步骤,注释含 **9 = 已关闭**;近期迁移为各分表补 `step`(见 `database/migrations/20260410150000-replace-audit-status-with-step-on-order-delivery-tables.js`) | - -**实施 §2.3a 前必须执行:** - -0. **核对清单(已产出,小阶段)**:只读 SQL 与步骤见 **`docs/order-cancel-db-checklist.md`**(不在仓库内自动连库执行)。**库表 DDL 变更影响面**见 **`docs/order-delivery-migration-impact.md`**。 -1. **对库**:对 `wms_order_delivery` 及 **`wms_order_delivery_%` 分表** 跑字段清单(`INFORMATION_SCHEMA`),确认 **`status` / `intercept_status` / `step` / `outbound_status`** 等与「取消后进 M4」**筛选用例**是否够用。 -2. **若产品要求独立可辨的「取消进 M4」标记**(例如与 `status=cancel` 但尚未占配送域行的组合区分):**库中无字段则新增**(如 `close_channel`、`cancelled_at`、`m4_reason_code` 等,名称待定),并同步: - - `app/model/order_delivery.js`; - - `OrderDeliveryFactory.createPhysicalTable` 生成的 DDL 模板; - - 已有物理分表的 **补列 migration**(循环 `wms_order_delivery_*`)。 - ---- - -## 1. 目标与范围(含 outsourced) - -### 1.1 工作台模块一览 - -| 模块 | 说明(产品语义) | 规划数据域 | -|------|------------------|------------| -| M1 待审核 | 需审核后进入后续履约 | **仅 current** | -| M2 待处理 | 仓内/出库前正常队列 | **仅 current** | -| M3 待处理异常 | 出库前各环节异常 | **仅 current** | -| M4 配送订单 | 配送链路正常态 | **配送域工厂(首期已落地)**:单表 `wms_order_delivery_dispatch_{wh}` + 列 `dispatch_lane=m4`;**不按自然月拆物理表** | -| M5 配送异常 | 配送链路异常(M4 子集) | **同上表**,`dispatch_lane=m5` 筛选;归档/近三月策略走 **查询与任务**,不必多分表 | -| M6 归档订单 | 冷数据 | **history**(>3 月等策略) | -| **outsourced 外仓发货** | 本仓不履约、推送外仓/三方履约;**已纳入 `OrderDeliveryFactory` 管理的 managed table / schema self-check 体系** | **由工厂统一管理,启动自检自动对齐结构**;仍可结合 current 扩展标记 + 外仓任务表落地 | - -### 1.2 数据分层(与 §0 对齐) - -| 层级 | 表 / 模型 | 时间 / 策略 | -|------|-----------|-------------| -| 热区 M1~M3 / outsourced(规划) | `wms_order_delivery_{wh}`、`wms_order_items_{wh}`(current) | 当日或未闭环;**创建时分流 M1 vs M2 由货主配置决定**;**到期仅克隆续单**,不进 M6(§2.4) | -| 配送区 M4/M5 | **`wms_order_delivery_dispatch_{wh}`**(`OrderDeliveryFactory` 的 dispatch 模式) | **单物理表**;M4/M5 用 **`dispatch_lane`**;**不按自然月拆表**;「约 3 个月」保留为 **列表/归档任务的时间条件**(见 §2.5 落地说明) | -| 冷数据 M6 | `*_history`(仅承接 **M4/M5** 迁入) | **超过 3 个月**等策略;**仅允许 M4/M5 进入 M6**;M1/M2/M3/outsourced **不走 M6 物理归档路径**(见 §2.4) | - ---- - -## 2. 模块规则与状态流转(补充) - -### 2.1 订单创建:进入 M1 或 M2 - -- **规则**:创建时读取 **货主(store)配置**,决定初始进入 **M1(待审核)** 或 **M2(待处理)**。 -- **M1 → M2**:必须通过 **仓内库存校验**(满足可履约)**或** 选择 **推送 outsourced(外仓发货)** 路径之一;具体字段与接口待定义。 -- **M2 ⊥ outsourced(强制互斥)**:同一订单 **不得** 同时处于本仓待处理与外仓履约;进入或退出 M2/outsourced 的切换 **必须在单条(或可串行化的)数据库事务内完成**(状态位 + 外仓任务表等一并提交),失败 **整体回滚**,禁止半开状态。 -- **outsourced**:当前 **无完整状态机**;与 M4 的衔接仍遵守 §2.2 单向规则。 - -### 2.2 进入 M4 的约束(核心) - -| 从 → 到 | 是否允许 | 说明 | -|---------|----------|------| -| **M2 → M4** | **允许(单向)** | M2、**outsourced 仅允许单向落入 M4** | -| **outsourced → M4** | **允许(单向)** | 外仓发货完成后,依赖 **外部通知** 与出库状态机推进 | -| **M1 → M4** | **禁止** | 须先 **切到 M2** 且 **状态机到达出库** 后,再经 **外部通知发货完成** 落入 M4 | -| **M3 → M4** | **禁止** | 须先 **消除异常并回到 M2**,再走与 M2 相同路径进入 M4 | -| **取消订单 → M4** | **允许(专用)** | 见 **§2.3a**:标记取消态后 **直进 M4**,**不可逆**、**零例外** | - -### 2.3 M4 / M5 与外部机制 - -- **M4 ↔ M5 切换**:由 **外部机制** 驱动(承运商回传、网关、人工标记等),不在此文档展开协议。 -- **M4/M5 与 M1~M3**:除下节「补发副本」外,**同一订单在 M1/M2/M3/outsourced 与 M4/M5 不重复占位**:**M1~M3(及 outsourced)为唯一工作台态**;**M4/M5 为配送域单独态**(可理解为 **配送域一条影子/主数据**,与 current 热行通过 `order_id` / `delivery_order_code` / 快照关联)。 - -### 2.3a 订单取消(特殊路径:标记后进 M4) - -- **规则**:发生 **订单取消** 时,须在热区/配送衔接层 **写入取消类状态标记**(状态机字段组合或专用列,见 **§0.7**),并 **直接进入 M4**(配送域占位,用于闭环展示与后续「仅 M4/M5 可进 M6」链路);**不可逆**,**不允许任何业务或技术例外**(含回滚接口、静默改回热区)。 -- **与 §2.2 的关系**:本条为 **取消专用例外**;非取消场景下 **M1/M3 仍禁止直落 M4**(见 §2.2 表)。 -- **库表**:上线前按 **§0.7** 核对;**缺字段则 migration 补充**,禁止仅靠应用层内存状态表达取消进 M4。 - -### 2.4 时间驱动的 M6(不可逆 + 准入白名单) - -- **时间策略**:**所有订单类型均受时间维度约束,不另开例外**;**进入 M6(物理归档)后不可逆**,**不允许任何例外**(不设司法解冻、不设未归档回退通道)。 -- **谁可以进 M6(物理)**:**仅 M4、M5** 对应的配送域数据(及与其绑定的明细快照)允许在满足保留期后 **迁入 `history` / 冷存储**。 -- **谁不可以进 M6**:**M1、M2、M3、outsourced** 热区行 **不允许** 走与 M4/M5 **相同的** M6(history)迁入通道;**到期后仅允许「克隆续单」**:通过 **新行(新主键)** 承接后续履约,原行 **仅改标记**(§2.7),**不得**删/软删、**不得**将原行迁入 M6。 -- **克隆续单 / 补单(首期)**:**不与奇门等平台同步**;定位为 **补单**,由 **人工在仓内/运营侧处理**;系统可提供列表与标记能力,**接口与对账范围以本仓 WMS 为准**。 -- **M4/M5 → M6**:以 **出库时间**(如 `delivery_time` / 出库确认时间)为主键条件之一,满足 **>3 个月**(与 §1.2 口径对齐)后迁入 history;过程 **不可逆**。 - -### 2.5 配送域工厂(首期落地 + 后续) - -- **已实现**:`app/model/order_delivery_factory.js` 的 dispatch 模式;物理表 **`wms_order_delivery_dispatch_{warehouseId}`**(与热区 `wms_order_delivery_{wh}` 命名同族,中间段 **`dispatch`**);**M4/M5 同表**,列 **`dispatch_lane` ENUM('m4','m5')** 区分;**不按自然月拆物理表**。`getDispatchModel(wh)` 为主入口;`getM4Model`/`getM5Model` 复用同一 dispatch 模式返回 **同一模型**。**outsourced 也已经纳入同一工厂管理,应用启动时会通过自检自动对齐 managed table 结构**。 -- **单测**:`test/app/model/order_delivery_dispatch_factory.test.js`;需连库时 `DISPATCH_FACTORY_TEST_MYSQL=1`(见 `config/plugin.js`);留表排查 `KEEP_DISPATCH_FACTORY_TABLES=1`。 -- **仍待**:与 current 的 **副本同步 / 事件驱动**;**强分区事务** 口径改为「单事务内同一 `warehouse_id` + 配送域表」即可(不再绑定 `yyyyMM` 表名);`wms_order_express` 与配送域行关联方案;M6 迁入仍以 **出库时间 + 保留期** 驱动(§2.4)。 - -### 2.6 M4/M5 副本回归 M1 / M2 / M3(补发 / 部分履约) - -- **场景**:配送域需 **重新创建副本** 回到 **M1 或 M2 或 M3**(目标态由业务定)。 -- **强制携带**:**补发标记/补发单**;或 **引用原资料 + 部分商品行** 的 **补发语义**,并 **更新履约目标**(新 `delivery_order_code` 或子单号、关联原单 ID 等,待表设计)。 -- **约束**:回归后重新遵守 **§2.1~2.2** 的互斥与单向规则;原配送域行 **不得删除/软删**,仅 **改标记** 或保留为 **只读关联**(§2.7)。 - -### 2.7 副本、主单与删除策略(硬约束) - -- **禁止物理删除**;**禁止软删除**(不使用 `delete_at` / `paranoid` 等表达「行消失」)。 -- **仅允许**:**改标记**(如 `lifecycle_state`、`superseded_by_id`、`closed_reason`、`is_supplement` 等,具体字段待表设计)或 **克隆** 新行(新主键)承载补发/续履约。 -- **适用范围**:**所有副本**(配送域副本、热区补发单、回归产生的克隆行、引用链上的历史快照)一律同上。 -- **运维级「克隆」语义**:在本规划中特指 **对状态机字段的合法变更**(含批量修正、`step` / 各 `*_status` / 取消标记等),**等价于「把行修正到合规状态」**;**不是**对 §2.3a「取消进 M4」或 §2.4「M6 不可逆」的 **豁免回滚**。若技术上采用「插入新行再改关联」实现修正,仍须满足 **不删旧行、仅标记**(§2.7 首条)。**审批角色与留痕** 见 **§5a 预留**,本期不落地。 - -### 2.8 互斥与唯一性(更新) - -| 关系 | 说明 | -|------|------| -| M1 ⊥ (M2 ∪ M3) | 不变 | -| M2 ⊥ M3 | 不变 | -| **M2 ⊥ outsourced** | **强制互斥**;切换须 **事务**(§2.1) | -| M5 ⊆ M4 | 不变 | -| **M1~M3 / outsourced(热区)** | **同一订单唯一展示态**(互斥集合内择一) | -| **M4 / M5** | **配送域内**可与热区并存为 **影子数据**;列表层需约定「主工作台只显示一侧」避免重复操作 | -| **M6** | **仅 M4/M5 可物理迁入**;**不可逆、零例外**;热区到期 **不进 M6**,**仅允许克隆续单**(§2.4) | - ---- - -## 3. 查询设计任务(列表 + 明细) - -### 3.1 列表查询(各模块) - -**目标**:最小可用字段集 + **足够前端判断订单状态**(含 outsourced 外仓标记若存在)。 - -**原则**: - -- 列表不返回大体积 `items` TEXT;仅标识、各 `*_status`、`outbound_status`、`inspection_status`、`step`、`updated_at` / `delivery_time`、货主/仓编码等。 -- 实现:**按模块常量 `LIST_FIELDS`**;M4/M5/outsourced 在配送域或扩展表就绪后各自维护一份。 - -### 3.2 明细查询 - -- 主单:**可对前端公开**的全部字段(排除密钥、内部调试字段)。 -- 明细行:`OrderItems` 动态表全量可公开字段。 -- **关联**:`Store`/仓库等(以 Sequelize `setupAssociations` / `copyAssociations` 为准,文档列出 **别名 + 字段子集**)。 -- **快递**:**暂不接订阅/路由逻辑**;列表/明细仅展示;**DTO 硬编码字段表 + 中文标签注释**(主表 `logistics_*` + 若联查 `wms_order_express` 则增加运单等字段)。 - -### 3.3 快递展示字段清单(示例) - -| 字段 key | 前端标签 | 说明 | -|----------|----------|------| -| `logistics_name` | 承运商 | 仅展示 | -| `logistics_code` | 物流编码 | 仅展示 | -| `waybill_code`(express 表) | 运单号 | 仅展示 | -| … | … | 不接路由、不订阅 | - ---- - -## 4. 执行任务(分阶段,可微调) - -### 执行进度(小阶段 A-0,最小影响) - -| 日期 | 内容 | -|------|------| -| 2026-04-10 | **无业务代码 / 无 migration 变更**。新增只读交付物:`docs/order-cancel-db-checklist.md`(§0.7 跑库步骤)、`docs/order-state-machine-dictionary.md`(状态机字典 **v0 骨架**,与 `app/model/order_delivery.js` 摘录一致)。**数仓映射、实际跑库结果** 仍待下一小阶段。 | -| 2026-04-10 | **小阶段 A-1(影响面)**:新增 `docs/order-delivery-migration-impact.md`。**结论**:在未跑库确认缺列、且未敲定「取消进 M4」专用列前,**不自动提交 ALTER migration**;若清单验证列已齐,可先 **零表变更** 做应用筛选。详见该文档 **§1**。 | -| 2026-04-10 | **小阶段 A-2(wms-db-agent 只读诊断)**:已对 `wms` 库跑清单;结果写入 **`docs/order-cancel-db-checklist.md` §5**。要点:**分表** `100000`/`1000028` 目标列齐全,可先不增列做筛选;**基表**缺三列、**勿**当业务表用;**无 `_history` 样本**;`chcp 65001` 防 JSON 解析失败。 | -| 2026-04-11 | **基表状态列**:migration `20260410200000-add-status-columns-to-wms-order-delivery-base.js`(按需补列,与热区分表对齐)。**配送域**:`OrderDeliveryFactory` 的 dispatch 模式单表 `wms_order_delivery_dispatch_{wh}` + `dispatch_lane`;当前按单表落地,不再保留「m4/m5 分表 + 自然月表名」方案;单测与 `DISPATCH_FACTORY_TEST_MYSQL` 见上文 §2.5。 | -| 2026-04-11 | **outsourced 收敛**:`outsourced` 纳入 `OrderDeliveryFactory` 的 managed table / schema self-check 体系,沿用启动自检自动对齐结构;旧兼容 shim 已移除,文档与代码统一收口到工厂管理。 | - -### 阶段 A — 文档与规则冻结 - -- [x] 货主配置:「创建进 M1 / M2」的配置项落库位置与变更流程。 -- [ ] M1→M2:库存校验 API、outsourced 推送接口与回写字段。 -- [ ] 外部「发货完成」通知与状态机字段的映射表(落到 `outbound_status` / `step` 等)。 -- [x] **§0.7 清单文档**:`docs/order-cancel-db-checklist.md`(各环境人工执行)。 -- [x] **§0.7 跑库(本机 wms 一次)**:见 `docs/order-cancel-db-checklist.md` §5;**分表列齐**;**其它仓/生产须复跑**。 -- [x] **§0.7 基表状态列 migration**(与分表枚举对齐):`database/migrations/20260410200000-add-status-columns-to-wms-order-delivery-base.js`(已合并进仓库;其它环境须自行 `db:migrate`)。**独立「取消进 M4」业务列** 仍待产品定名后再 migration。 -- [x] **状态机字典 v0 骨架**:`docs/order-state-machine-dictionary.md`(与数仓/报表的 **字段映射表** 仍待补)。 -- [x] **订单表 DDL 影响面分析**:`docs/order-delivery-migration-impact.md`(初版静态结论;**2026-04-11** 起基表状态列以已合并 migration 为准,文档全文若与现网不一致须择机修订)。 - -### 阶段 B — 配送域工厂(3 自然月 + 强分区事务) - -- [x] 配送域建表能力(`OrderDeliveryFactory` 的 dispatch 模式):表 **`wms_order_delivery_dispatch_{warehouseId}`**,**`dispatch_lane`** 区分 M4/M5。 -- [x] M4/M5 **单表** DDL 与动态模型(首期)。 -- [ ] 与 current 的 **副本同步** 或 **事件驱动** 方案(未做)。 -- [ ] `wms_order_express` 与配送域 **order_id**(及仓)一致性方案。 - -### 阶段 C — 归档 M6 + 时间消除 - -- [ ] **仅 M4/M5**:配送域 → history 的 **出库时间** 驱动任务;**不可逆** 校验与审计(**零例外**)。 -- [ ] **M1/M2/M3/outsourced**:到期 **仅克隆续单** 流程(新行 + 原行标记);**禁止** 迁入 M6;前端 **空态/引导续单** 文案。 -- [ ] **取消进 M4**:状态机字段字典、事务边界、与常规 M4 列表的 **展示分区**(避免与正常配送混淆)。 -- [ ] 全库 **禁止 DELETE/软删** 副本与主单的 ORM/脚本审计;运维修正走 **状态机变更**(§2.7);**审批流** 见 **§5a 预留**。 - -### 阶段 D — 补发副本与目标更新 - -- [ ] 补发单模型、原单引用、部分行、目标更新字段;**原行仅标记,禁止删/软删**。 -- [ ] 事务:副本创建 + 热区插入 + 配送域标记 **同一强分区键内** 或可补偿 Saga;与 **M2↔outsourced 事务切换** 共用事务规范文档。 - -### 阶段 E — API / 测试 - -- [ ] `methods/system.json` + changes;互斥与单向集成测试用例。 - ---- - -## 5. 待补充项 — 满足情况说明(已更新) - -> **结论**:原「待补充项」中的 **业务原则 / 边界** 多数已在正文(§0.7、§2.3a、§2.4、§5a)**闭合**,**不再属于「方向未定的拍板」**;但 **可交付的设计稿与成文资产** 仍未完成,须在 **§4 各阶段** 跟踪直至产出。 - -### 5.1 规则层 — 视为已满足(已写入本文档) - -| 原议题 | 满足方式 | -|--------|----------| -| 克隆续单是否与奇门同步 | **已决策:不同步**;首期 **人工补单** — 见 §2.4 | -| 运维审批、留痕格式 | **已决策:本期不做**,仅预留 — 见 **§5a** | -| 取消状态机是否依赖库表 | **已决策:以 DB 为准**,缺列则 migration — 见 **§0.7**、§2.3a | - -### 5.2 交付层 — 尚未满足(须产出成果物,不等同于「原则未拍板」) - -| 事项 | 当前状态 | 建议产出 / 跟踪位置 | -|------|----------|----------------------| -| **取消进 M4** 的配送域 **子类型 / 展示标签**(与正常 M4 区分色、筛选项) | 未完成 | 产品/UI 说明 + 接口 `where` 约定;**§4 阶段 C** | -| **克隆续单** 的 **主键关联、单号规则、权限** | 未完成 | 表设计 + 人工补单 SOP;**§4 阶段 D**(原则「不奇门」已 §2.4) | -| **改标记 / 状态机** 的 **字段字典** 及与 **数仓、报表** 同步 | **骨架已完成(v0)** | 成稿:`docs/order-state-machine-dictionary.md`;**数仓/报表映射与变更登记** 仍未完成 — **§4 阶段 A/C** | - -### 5a. 预留(本期不实现) - -- **运维审批** 角色、工单模板与 **留痕格式**:**本期不做**,仅在技术方案中 **预留扩展点**(配置键、审计表占位名、接口 hook 注释),避免后续硬改核心表结构。 - ---- - -## 6. 修订记录 - -| 日期 | 说明 | -|------|------| -| (首版) | 根据讨论整理计划草案 | -| 补充 | 增加 §0 当前表/模型/工厂/关联分析;outsourced、创建分流、进入 M4 约束、外部驱动 M4/M5、时间进 M6、配送域独立工厂与强分区事务、M4/M5 按出库时间进 M6、补发副本回归 M1/2/3 | -| 补充 | **M2⊥outsourced 且事务进出**;**M6 仅 M4/M5 可物理迁入、不可逆**;热区到期不进 M6;**全副本禁止删/软删、仅标记或克隆**;§2.7 硬约束、§1.2/阶段 C/待补充项同步 | -| 补充 | 热区到期 **仅克隆续单**;**§2.3a 取消→标记→直进 M4、不可逆零例外**;**运维「克隆」= 状态机合法变更** 写入 §2.2/§2.7/阶段 C | -| 补充 | **§0.7** 取消状态机与分表核对/缺列 migration;**克隆续单不奇门同步、首期人工补单**;**字段字典与数仓报表同步**;**§5a 运维审批预留** | -| 补充 | **§5 重写**:区分 **规则层已满足** vs **交付层未完成**;原 checklist 拆入 §5.1 / §5.2 并指向 §4 | -| 2026-04-10 | **小阶段 A-0**:新增 `docs/order-cancel-db-checklist.md`、`docs/order-state-machine-dictionary.md`;§0.7 / §4 阶段 A / §5.2 同步;无代码变更 | -| 2026-04-10 | **小阶段 A-1**:`docs/order-delivery-migration-impact.md`;**未提交 migration**(待你根据跑库 + 列名决策) | -| 2026-04-10 | **小阶段 A-2**:wms-db-agent 只读诊断;`order-cancel-db-checklist.md` §5;**未提交 migration** | -| 2026-04-11 | **配送域单表工厂** + **基表 migration**;§1.2 / §2.5 / §4 阶段 B 勾选与表述同步 | diff --git a/docs/print-retry-compensation.md b/docs/print-retry-compensation.md deleted file mode 100644 index b7b1f2d..0000000 --- a/docs/print-retry-compensation.md +++ /dev/null @@ -1,65 +0,0 @@ -# 打印失败自动补偿(printRetryCompensation)操作说明 - -概述 -- 目的:定时扫描失败或超时的打印记录,按仓库分组并批量触发补打(调用内部方法 `print.retryFailed`)。 -- 实现位置:调度任务文件 [app/schedule/print_retry_compensation.js](app/schedule/print_retry_compensation.js) -- 配置位置:全局配置 `config.printRetryCompensation`(见 `config/config.default.js`) - -如何开启 -1. 在目标环境的配置文件中(例如 `config/config.local.js` 或部署时注入的 config),设置: - -```js -// 示例(config/config.local.js) -module.exports = appInfo => { - const config = exports = {}; - - config.printRetryCompensation = { - enable: true, // 开启自动补偿 - intervalMs: 60 * 1000, // 最小执行间隔(ms),默认 60000 - batchSize: 50, // 每次扫描触发的最大打印记录数,默认 50 - force: false, // 是否以强制方式触发(当前实现不放宽状态判定) - }; - - return config; -}; -``` - -2. 启用后,Egg 的调度器会按文件中的 `schedule.interval`(30s)触发调度器,但实际执行受 `intervalMs` 控制(避免重复执行)。 -3. 部署/重启应用使配置生效。 - -关键参数说明 -- `enable` (boolean):是否启用自动补偿(默认 `false`)。 -- `intervalMs` (number, ms):两次实际执行之间的最小间隔(默认 60000)。注意调度器仍以 30s 触发,但若距离上次执行时间 < intervalMs 将跳过本轮。 -- `batchSize` (number):每次从数据库读出的最大记录数量(默认 50)。 -- `force` (boolean):是否强制补打。当前最小实现中 `force` 参数会被传递到 `print.retryFailed`,但 `getRetryEligibility` 中并未放宽状态检查(注释标注为“最小实现”)。如需放宽,需要修改 `app/service/systemMethods/print.js` 中的 `getRetryEligibility` 实现。 - -行为与兼容性(与代码的一致性要点) -- 调度逻辑: - - 调度入口:[app/schedule/print_retry_compensation.js](app/schedule/print_retry_compensation.js) - - 查询条件:满足任一 send_status 为 `send_failed`,或 print_status 在 `['print_failed','timeout']`,且 `next_retry_at <= now`,并且 `retry_count < max_retry_count`。 - - 按 `warehouse_id` 分组后,逐仓调用: - `ctx.service.systemMethods.print.retryFailed({ print_ids, warehouse_id, force })`。 -- `print.retryFailed` 对 `warehouse_id` 的兼容: - - 支持显式传入 `warehouse_id`,优先使用该值。 - - 若未传入 `warehouse_id`,会回退使用 `ctx.user.store_id`(接口调用者的仓库上下文)。 - - 如果两者均无(例如外部无登录上下文且未传入 `warehouse_id`),方法会返回 400 错误:`warehouse_id 参数缺失,且当前上下文无可用仓库信息`。 -- 返回值要点:成功返回包含 `success_count` / `failed_count` / `skipped_count`、`retried`(尝试项)和 `skipped`(跳过项)摘要;调度器依据 `flag==='success'` 判定调用是否成功。 - -排障要点(常见问题排查) -- 任务一直没有扫描到记录:检查数据库 `PrintRecord` 表中是否存在满足条件的行(`send_status`/`print_status`、`next_retry_at`、`retry_count < max_retry_count`)。 -- 调度被频繁跳过:检查 `config.printRetryCompensation.intervalMs` 与日志中 `ctx.app._printRetryCompensationLastRunAt` 的时间差;若 `_printRetryCompensationRunning` 标识长时间为 true,进程可能在上次运行时异常退出,建议重启应用清理状态。 -- 补打触发但实际发送失败:查看打印服务调用日志(`service.systems.print.index.sendToComputer` 返回值),并查看 `PrintRecord` 的 `error_message` / `fail_code` 字段。 -- 快递/组件离线导致发送失败:`print` 服务会在调用前检查组件在线性(从 Redis 的 `printer:{computerId}:name:{component}:status` 读取,期望值为 `connected`)。请检查对应 Redis key 是否存在并为 `connected`。 -- 打印任务编码冲突:如果出现唯一索引冲突(ER_DUP_ENTRY),日志会有 `打印任务编码冲突` 的警告,系统会按指数退避重试写入映射表。 - -回滚方式 -- 临时回滚:在运行环境配置中将 `printRetryCompensation.enable` 设为 `false` 并重启服务,调度器将不再触发实际补偿逻辑。 -- 速率/批量调整:将 `batchSize` 缩小或增大 `intervalMs`,以控制对打印服务的并发压力。 - -参考位置 -- 调度实现:[app/schedule/print_retry_compensation.js](app/schedule/print_retry_compensation.js) -- 默认配置:[config/config.default.js](config/config.default.js)(`printRetryCompensation` 段) -- 补打实现与仓库兼容性:[app/service/systemMethods/print.js](app/service/systemMethods/print.js) 中 `retryFailed` 与 `getRetryEligibility` 方法 - -附注 -- 本说明以当前代码实现为准(2026-05-20),如修改 `getRetryEligibility` 或补打流程,请同步更新本说明与 `methods/changes` 记录。 \ No newline at end of file diff --git a/docs/qimen-interface-reference.md b/docs/qimen-interface-reference.md deleted file mode 100644 index 70a0a5a..0000000 --- a/docs/qimen-interface-reference.md +++ /dev/null @@ -1,226 +0,0 @@ -# 奇门接口技术备忘 - -## 1. 文档来源 - -- 官方来源:open.taobao.com 文档,docId=118403,页面章节为“5. 接口说明” -- 适用对象:WMS 与 ERP 之间的奇门对接排障、接口回查、协议备忘 -- 本文目标:把官方白皮书里的核心调用约定、接口地图和本地实现入口沉淀到仓库内,便于技术备用 - -## 2. 接入总览 - -奇门接口的统一特征是: - -- 请求方式以 POST 为主 -- query 中携带 app_key、method、v、format、sign_method、sign、timestamp 等标准参数 -- body 使用 XML,根节点通常为 request -- 响应也使用 XML,根节点通常为 response -- 响应通常包含 flag、code、message 三个固定字段 - -官方白皮书中明确说明: - -- 很多接口是同步接口,返回 success 不只是“消息接收成功”,而是代表业务已处理完成 -- 批量接口通常会在一个订单下承载多个 item 或 order 节点 -- 非叶子节点通常允许增加 remark 和 extendProps - -## 3. 通用字段与约定 - -### 3.1 常见主键字段 - -- ownerCode:货主编码 -- warehouseCode:仓库编码,统仓统配等场景常填 OTHER -- itemCode:ERP 商品编码 -- itemId:WMS 商品编码或仓储系统商品 ID,通常是条件必填 -- orderCode:单据编码 -- orderId:仓储系统单据编码 -- outBizCode:外部业务编码,常作为幂等键 - -### 3.2 常见状态枚举 - -订单类状态常见值: - -- NEW:未开始处理 -- ACCEPT:仓库接单 -- PRINT:打印 -- PICK:拣货 -- CHECK:复核 -- PACKAGE:打包 -- WEIGH:称重 -- READY:待提货 -- DELIVERED:已发货 -- PARTDELIVERED:部分发货完成 -- PARTFULFILLED:部分收货完成 -- FULFILLED:收货完成 -- EXCEPTION:异常 -- CANCELED:取消 -- CLOSED:关闭 -- REJECT:拒单 -- REFUSE:客户拒签 -- SIGN:签收 - -库存类常见值: - -- ZP:正品 -- CC:残次 -- JS:机损 -- XS:箱损 -- FP:废品 -- ZT:在途库存 -- DJ:冻结 -- OTHER:其他 - -### 3.3 常见业务规则 - -- 组合商品、条码、批次、生产日期、过期日期、生产批号等字段在多个接口里复用 -- 一些接口对 itemId 有条件必填要求,通常与仓库是否自定义 WMS 商品编码有关 -- 多次收货、多次发货、多次确认类接口会使用 confirmType -- 分批发送时,totalOrderLines 常用于说明总行数,接收方据此判断是否收齐 - -## 4. 接口地图 - -以下为官方文档 5.x 章节的接口目录,按业务域整理。 - -### 4.1 商品与商品映射 - -- 5.1 商品查询接口:taobao.qimen.singleitem.query / singleitem.query -- 5.2 商品同步接口:taobao.qimen.singleitem.synchronize / singleitem.synchronize -- 5.3 商品同步接口(批量):taobao.qimen.items.synchronize / items.synchronize -- 5.4 组合商品接口:taobao.qimen.combineitem.synchronize / combineitem.synchronize -- 5.5 创建前后端商品映射接口:taobao.qimen.itemmapping.create / itemmapping.create -- 5.6 前后端商品映射查询接口:taobao.qimen.itemmapping.query / itemmapping.query - -### 4.2 入库与退货入库 - -- 5.7 入库单创建接口:taobao.qimen.entryorder.create / entryorder.create -- 5.8 入库单确认接口:taobao.qimen.entryorder.confirm / entryorder.confirm -- 5.9 入库单查询接口:taobao.qimen.entryorder.query / entryorder.query -- 5.10 退货入库单创建接口:taobao.qimen.returnorder.create / returnorder.create -- 5.11 退货入库单确认接口:taobao.qimen.returnorder.confirm / returnorder.confirm -- 5.12 退货入库单查询接口:taobao.qimen.returnorder.query / returnorder.query - -### 4.3 出库、发货与确认 - -- 5.13 出库单创建接口:taobao.qimen.stockout.create / stockout.create -- 5.14 出库单确认接口:taobao.qimen.stockout.confirm / stockout.confirm -- 5.15 出库单查询接口:taobao.qimen.stockout.query / stockout.query -- 5.16 发货单创建接口:taobao.qimen.deliveryorder.create / deliveryorder.create -- 5.17 发货单创建接口(批量):taobao.qimen.deliveryorder.batchcreate / deliveryorder.batchcreate -- 5.18 发货单创建结果通知接口(批量):taobao.qimen.deliveryorder.batchcreate.answer / deliveryorder.batchcreate.answer -- 5.19 发货单确认接口:taobao.qimen.deliveryorder.confirm / deliveryorder.confirm -- 5.20 发货单确认接口(批量):taobao.qimen.deliveryorder.batchconfirm / deliveryorder.batchconfirm -- 5.21 发货单查询接口:taobao.qimen.deliveryorder.query / deliveryorder.query - -### 4.4 SN 与订单流水 - -- 5.22 订单SN通知接口:taobao.qimen.order.sn.report / order.sn.report -- 5.23 发货单SN通知接口:taobao.qimen.sn.report / sn.report -- 5.24 订单流水查询接口:taobao.qimen.orderprocess.query / orderprocess.query -- 5.25 订单状态查询接口(批量):taobao.qimen.orderstatus.batchquery / orderstatus.batchquery -- 5.26 订单流水通知接口:taobao.qimen.orderprocess.report / orderprocess.report -- 5.27 订单异常通知接口:taobao.qimen.orderexception.report / orderexception.report - -### 4.5 异常、退货、缺货与挂起 - -- 5.28 退货异常包裹单通知接口:taobao.qimen.returnapply.report / returnapply.report -- 5.29 退货包裹状态通知接口:taobao.qimen.returnpackage.report / returnpackage.report -- 5.30 发货单缺货通知接口:taobao.qimen.itemlack.report / itemlack.report -- 5.31 发货单缺货查询接口:taobao.qimen.itemlack.query / itemlack.query -- 5.32 单据取消接口:taobao.qimen.order.cancel / order.cancel -- 5.33 单据挂起(恢复)接口:taobao.qimen.order.pending / order.pending - -### 4.6 库存、仓库、加工与异动 - -- 5.34 库存查询接口(多商品):taobao.qimen.inventory.query / inventory.query -- 5.35 库存查询接口(多条件):taobao.qimen.stock.query / stock.query -- 5.36 仓库查询接口:taobao.qimen.warehouseinfo.query / warehouseinfo.query -- 5.37 仓库同步接口:taobao.qimen.warehouseinfo.synchronize / warehouseinfo.synchronize -- 5.38 库存盘点通知接口:taobao.qimen.inventory.report / inventory.report -- 5.39 库存盘点查询接口:taobao.qimen.inventorycheck.query / inventorycheck.query -- 5.40 仓内加工单创建接口:taobao.qimen.storeprocess.create / storeprocess.create -- 5.41 仓内加工单确认接口:taobao.qimen.storeprocess.confirm / storeprocess.confirm -- 5.42 库存异动通知接口:taobao.qimen.stockchange.report / stockchange.report - -### 4.7 店铺、波次、调拨、规则与统计 - -- 5.43 店铺同步接口:taobao.qimen.shop.synchronize / shop.synchronize -- 5.44 发货单波次通知接口:taobao.qimen.wavenum.report / wavenum.report -- 5.45 调拨单创建接口:taobao.qimen.transferorder.create / transferorder.create -- 5.46 调拨单查询接口:taobao.qimen.transferorder.query / transferorder.query -- 5.47 调拨单通知接口:taobao.qimen.transferorder.report / transferorder.report -- 5.48 渠道间库存规则设置接口:taobao.qimen.inventoryrule.create / inventoryrule.create -- 5.49 库存汇总报表查询接口:taobao.qimen.inventorysum.query / inventorysum.query -- 5.50 订单出库统计查询接口:taobao.qimen.deliveryordersum.query / deliveryordersum.query - -### 4.8 基础能力 - -- 5.51 心跳接口:taobao.qimen.service.heartbeat / service.heartbeat -- 5.52 供应商信息同步接口:taobao.qimen.supplier.synchronize / supplier.synchronize -- 5.53 配送公司信息查询:taobao.qimen.expressinfo.query / expressinfo.query - -## 5. 官方白皮书里的关键细节 - -### 5.1 商品接口 - -- 单品查询与单品同步字段高度一致,itemCode、itemName、barCode、itemType、brand、重量、尺寸、批次、保质期相关字段都会复用 -- 批量商品同步使用 items 节点包裹 item 列表 -- 组合商品接口的核心是 itemCode、ownerCode、warehouseCode 与子商品清单 - -### 5.2 入库与退货入库 - -- entryorder.create 与 returnorder.create 都是同步创建 -- confirm 接口用于最终状态回告,不只是接收消息 -- 订单行内常包含 itemCode、itemId、planQty、actualQty、inventoryType、batchCode、productDate、expireDate、produceCode -- 入库场景支持 relatedOrders 关联单据信息 - -### 5.3 出库与发货 - -- stockout 更偏普通出库,不强调订单履约语义 -- deliveryorder 更偏订单驱动发货 -- 批量版 create/confirm 接口支持 orders 与 order 节点 -- 发货单确认会带包裹、发票、物流、重量、体积、SN、批次等信息 - -### 5.4 库存与盘点 - -- inventory.query 与 stock.query 都是库存查询,但入参组织方式不同 -- inventory.report 与 inventorycheck.query 用于盘点回传和盘点查询 -- stockchange.report 用于把引起库存变动的单据和库存变化同步给 ERP - -### 5.5 组织与基础资料 - -- warehouseinfo.query / synchronize 处理仓库基础资料 -- shop.synchronize 处理店铺基础资料 -- supplier.synchronize 处理供应商基础资料 -- expressinfo.query 处理配送公司信息 - -## 6. 本地实现落点 - -当前仓库里与奇门相关的本地实现入口主要是: - -- app/service/qimen.js:统一 XML 解析、method 路由与 XML 响应封装 -- app/service/qimenMethods/:具体奇门业务方法实现目录 -- typings/app/service/index.d.ts:qimenMethods 的类型入口 -- methods/qimen.json:当前奇门方法定义与参数结构的主索引 -- methods/changes/qimen.json:奇门文档变更记录副本 - -从代码层看,qimen.js 会先解析 XML,再根据 method 对应到 qimenMethods 下的具体模块调用。 - -## 7. 排障时的实用检查点 - -1. 先确认 method 名是否与官方文档一致,尤其是 singleitem、deliveryorder、entryorder、returnorder、stockout、inventory 这些主模块 -2. 再确认 XML 根节点和字段名是否和官方定义一致,奇门对字段名大小写和层级通常比较敏感 -3. 关注 itemId 是否被误传为空,很多接口里它是条件必填 -4. 关注 warehouseCode 是否在统仓统配场景下正确使用 OTHER -5. 批量接口要核对 totalOrderLines、currentPage、pageSize 和明细数量是否一致 -6. 发生返回 success 但业务未落库时,要继续检查本地实现是否只是接收成功而不是业务处理成功 - -## 8. 结论 - -这份奇门白皮书覆盖了 WMS 与 ERP 对接的完整主干能力,核心可以归纳为: - -- 商品主数据 -- 入库、退货入库、出库、发货 -- SN、流水、状态、异常 -- 库存、盘点、加工、异动 -- 仓库、店铺、供应商、配送公司基础资料 -- 调拨、波次、缺货、规则、统计与心跳 - -在本仓库中,奇门的本地实现已经有统一入口和方法分层,适合把本文作为日常联调与故障排查的快速备忘。 \ No newline at end of file diff --git a/docs/stock-expiry-module.md b/docs/stock-expiry-module.md deleted file mode 100644 index 4c17bce..0000000 --- a/docs/stock-expiry-module.md +++ /dev/null @@ -1,80 +0,0 @@ -# 库存效期模块(定时预警任务) - -本文档基于源码实现(单一事实来源),定位与说明项目中关于库存效期扫描与预警的定时任务行为。实现文件:app/schedule/notice_stock_remaining.js。 - -## 概要 - -- 任务名称/文件:`app/schedule/notice_stock_remaining.js` -- 调度配置:`interval: '30s'`、`type: 'worker'`、`immediate: false`(见文件头部 schedule 配置) -- 目的:扫描启用保质期管理的仓库商品与对应库存(wms_stock_warehouse / wms_storage),对即将到期的库存发送效期预警通知,并通过缓存进行去重。 - -## 主要实现要点(按代码实现逐项说明) - -1. 并发保护 - - 使用进程级标记 `ctx.app._noticeStockRemainingRunning`,若上一轮尚未结束则跳过本次运行。 - -2. 通知去重缓存 - - 缓存键:`notice_stock_remaining_notified_list`(文件常量 `CACHE_KEY`)。 - - 缓存 TTL:24 小时(`CACHE_TTL_SECONDS = 24 * 60 * 60`)。 - - 缓存存储格式兼容数组或对象,读取后标准化为 `storage:{id}` 格式的键集合用于去重。 - -3. 读取候选商品(wms_stock_warehouse) - - 查询条件(stockWhere): - - `is_shelf_life_mgmt: 'Y'` - - `remaining_threshold_days: { [Op.gt]: 0 }`(使用 `Sequelize.Op.gt`) - - 查询字段:`id, item_code, item_name, store_id, warehouse_id, remaining_threshold_days` - - 排序:`remaining_threshold_days ASC, id ASC` - - 结果用于构建 `stockMap`(包含每个 stock 的阈值),并计算 `maxThresholdDays`(用于缩小后续库存扫描时间窗口)。 - -4. 计算候选库存时间窗口 - - 以当前时间 `now`,计算 `maxExpiryDate = new Date(now.getTime() + maxThresholdDays * DAY_MS)`,其中 `DAY_MS = 24 * 60 * 60 * 1000`。 - -5. 查询候选库存记录(wms_storage) - - 查询条件(storageWhere): - - `stock_id` 在上一步筛选得到的 `stockIds` 列表中 - - `is_enabled: 1` - - `delete_at: null`(paranoid 软删除过滤) - - `quantity: { [Op.gt]: 0 }` - - `expiry_date: { [Op.ne]: null, [Op.lte]: maxExpiryDate }`(到期日非空且小于等于计算窗口) - - include:关联 `LocationSpace`(别名 `space`),属性取 `space_code, custom_name`,`required: false`。 - - 排序:`expiry_date ASC, inbound_time ASC, id ASC`。 - - 注意:实现中调用的是 `findAll`(无分页),因此会拉取匹配的全部候选记录并在内存中逐条处理。 - -6. 单条记录处理与判断逻辑 - - 对每条 `storageRecord`: - - 生成去重键 `notifyKey = storage:{storageId}`(若无法解析 id 则跳过)。 - - 若该 `notifyKey` 已存在于缓存集合则跳过(避免重复通知)。 - - 根据 `stockMap` 获取本条记录对应商品的 `thresholdDays`(阈值天数);若不存在或阈值 <= 0 则跳过。 - - 读取 `expiry_date`,将其解析为 Date;若无或解析失败则跳过并记录 warn。 - - 计算剩余天数:`remainingDays = Math.max(0, Math.ceil((expiryDate - now) / DAY_MS))`。 - - 若 `remainingDays > thresholdDays` 则跳过(未达到阈值);否则组装通知并发送。 - -7. 通知发送与元数据 - - 使用通知服务:`ctx.service.systems.notice.send(payload)`。代码中若 `noticeResult.success === false` 则认为发送失败并保留重试;异常时记录错误并继续处理下一条。 - - 通知 payload 包含(示例字段): - - `warehouseId`, `storeId`, `subject`(id/type/name), `businessName: 'storage'`, `event`(常量 `storage_transfer_completed`),`title`, `content`, `businessId: storageId`, `messageType: 'text'` - - `metadata`:包含 `cacheKey`, `storageId`, `stockId`, `notifyKey`, `thresholdDays`, `remainingDays`, `warehouseId`, `storeId`, `stock: { id, item_code, item_name }`, `storage: { id, batch_no, expiry_date (ISO) }` - -8. 回写去重缓存 - - 成功发送后,将 `notifyKey` 添加到 `updatedNotifiedList` 并在本轮结束后使用 `ctx.app.setCacheAsync(CACHE_KEY, dedupedList, CACHE_TTL_SECONDS)` 回写缓存(如果 `setCacheAsync` 可用)。 - -9. 日志与统计 - - 任务会记录候选商品数、候选库存数、实际发送计数与跳过计数;发送失败与异常会记录 warn/error 日志。 - -## 与公开 API 的关系 - -- 任务为内部定时任务(非 system API),其查询条件与模型字段直接对应数据库表 `wms_stock_warehouse` 与 `wms_storage`。 -- 若需要通过 API 查询某个商品的库存明细(包含批次与过期信息),请使用已有的 system 方法 `stock.warehouse.getStockDetail`(该接口支持 `pagination` 与 `group_by_batch`,API 文档位于 `methods/system.json`),与本任务的扫描逻辑互为补充:任务用于主动推送预警,API 用于按需查询。 - -## 注意事项(运维/集成) - -- 通知发送依赖 `ctx.service.systems.notice`,在无该服务或返回异常时任务仅记录日志。 -- 任务扫描不分页:对于极大库存量的仓库,建议评估 `maxThresholdDays` 与索引(`idx_expiry_date` 已存在于模型)对查询性能的影响,或考虑将查询改为分片/分页处理。 -- 去重缓存使用全局缓存接口 `getCacheAsync` / `setCacheAsync`,请保证缓存后台(如 Redis)可用以避免重复通知泛滥。 - -## 实现位置(代码参考) - -- 定时任务文件:app/schedule/notice_stock_remaining.js -- 依赖模型:app/model/stock_warehouse.js、app/model/storage.js、app/model/location_space.js -- 依赖服务:ctx.service.systems.notice - diff --git a/docs/stock-stockWarehouse-query-rules.md b/docs/stock-stockWarehouse-query-rules.md deleted file mode 100644 index f0bad86..0000000 --- a/docs/stock-stockWarehouse-query-rules.md +++ /dev/null @@ -1,178 +0,0 @@ -# stock.warehouse.list 前端查询规则 - -## 目的 - -本文档约束 `stock.warehouse.list` 的 `where` 构造格式,便于前端统一构建查询条件,并与后端解析器保持一致。 - -## 接口入口 - -- 路由:`POST /system` -- method:`stock.warehouse.list` - -## 请求体结构 - -```json -{ - "pagination": { - "page": 1, - "pageSize": 20 - }, - "where": { - "item_code": { - "operator": "like", - "value": "SKU", - "type": "text" - } - } -} -``` - -## where 字段规则 - -`where` 必须是对象,且每个字段值也必须是对象。 - -正确示例: - -```json -{ - "where": { - "item_name": { - "operator": "like", - "value": "鞋", - "type": "text" - } - } -} -``` - -错误示例(会返回解析失败原因): - -```json -{ - "where": { - "item_name": "鞋" - } -} -``` - -## 条件对象结构 - -每个 `where.` 支持: - -- `operator`:操作符,默认 `eq` -- `value`:查询值 -- `type`:值类型(可选) -- `field`:映射到真实字段(一般不需要前端传) - -### 支持操作符 - -- `eq` -- `ne` -- `like` / `contains` -- `startswith` -- `endswith` -- `gt` -- `lt` -- `ge` -- `le` -- `in` -- `notin` -- `between` -- `notbetween` -- `isnull` -- `isnotnull` -- `regexp` -- `notregexp` - -### 支持 type - -- `boolean`:转换为 `Y/N` -- `number`:转换为数字 -- `date`:日期字符串归一化 -- `daterange`:日期数组归一化 -- `text`:逗号分隔字符串拆分数组 - -## 特殊字段说明 - -### barcode - -- 在条码表中先匹配,再回灌 `stock_id` 过滤主表。 -- 推荐:`operator=eq|like`。 - -### prohibited_type - -- 传入的是违禁品类型 `id`。 -- 后端会映射到关联模型进行过滤。 - -### has_bound_item - -- 筛选仓库商品是否已绑定外部商品(货主商品)。 -- `operator`:固定 `eq`(默认)。 -- `value`: - - 已绑定:`true` / `1` / `"Y"` / `"y"` - - 未绑定:`false` / `0` / `"N"` / `"n"` -- 示例: - - 查询已绑定外部商品的仓库商品:`has_bound_item={operator:eq,value:true}` - - 查询未绑定外部商品的仓库商品:`has_bound_item={operator:eq,value:false}` - -## 空值处理 - -以下值会被视为“空条件”并跳过: - -- `null` -- `undefined` -- `""` -- `[]` - -## 排序规则 - -后端只接受以下排序字段: - -- `id` -- `item_code` -- `item_name` -- `quantity` -- `locked_quantity` -- `tag_price` -- `retail_price` -- `create_at` -- `update_at` - -当传入非法排序字段时,会回退为: - -- `sortField=create_at` -- `sortOrder=DESC` - -## 失败返回(解构失败) - -当 `where` 结构不合法时,返回示例: - -```json -{ - "code": 400, - "message": "筛选条件解析失败: 字段 item_code 条件必须是对象", - "data": { - "list": [], - "pagination": { - "page": 1, - "pageSize": 20, - "total": 0, - "totalPages": 0, - "hasPrevious": false, - "hasNext": false - }, - "summary": { - "total_quantity": 0, - "total_locked": 0, - "total_available": 0, - "total_items": 0 - } - } -} -``` - -## 前端建议 - -- 对 `in/notin/between/notbetween` 先做数组校验,再发请求。 -- 对 `where` 做 schema 校验,避免后端 400。 -- 对空输入不构造条件,减少无效查询。 diff --git a/docs/storage-receiving-api.md b/docs/storage-receiving-api.md deleted file mode 100644 index fdee9fe..0000000 --- a/docs/storage-receiving-api.md +++ /dev/null @@ -1,487 +0,0 @@ -# 收货单 API 文档(`storage.receiving`) - -## 1. 文档说明 - -本文档补充 `storage.receiving` 相关 system 方法中的收货明细商品绑定接口,当前重点覆盖: - -- `storage.receiving.bindDetailProduct` - -适用场景: - -- 新增收货单明细后,为该明细绑定系统商品 -- 已绑定商品时,改绑为另一个系统商品 -- 前端或第三方系统对接收货单明细与系统商品的匹配动作 - ---- - -## 2. 统一调用方式 - -该项目的 system 方法统一通过 `/system` 调用,方法名通过 query 参数 `method` 传入。 - -### 请求方式 - -```http -POST /system?method=storage.receiving.bindDetailProduct&v=1.0×tamp={unix_timestamp} -Content-Type: application/json -Authorization: Bearer -platform: web -project: wms -``` - -### 调用示例 - -```bash -curl -X POST "http://127.0.0.1:6060/system?method=storage.receiving.bindDetailProduct&v=1.0×tamp=1712400000" \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -H "platform: web" \ - -H "project: wms" \ - -d '{ - "detail_id": 12345, - "system_product_id": 67890 - }' -``` - -> 说明:该接口通常要求用户已登录,并以当前仓库角色执行;实际仓库上下文来自 `ctx.user.store_id`。 - ---- - -## 3. 接口:`storage.receiving.bindDetailProduct` - -### 3.1 接口用途 - -用于**绑定或改绑收货单明细的系统商品**。 - -调用成功后,系统会按当前仓库商品信息自动回填或更新以下内容: - -- `system_product_id` -- `product_name` -- `product_snapshot` -- `barcode`(有条码时) -- `weight`(商品存在毛重时) -- 箱规尺寸字段(启用箱规时) - -同时会刷新整张收货单的统计信息。 - -### 3.2 请求参数 - -| 字段 | 类型 | 必填 | 说明 | -|---|---:|---|---| -| `detail_id` | `number` | 是 | 收货单明细 ID | -| `id` | `number` | 否 | 兼容字段,可替代 `detail_id` | -| `system_product_id` | `number` | 是 | 要绑定的系统商品 ID(`StockWarehouse.id`) | - -### 3.3 请求体示例 - -```json -{ - "detail_id": 12345, - "system_product_id": 67890 -} -``` - ---- - -## 4. 成功返回示例 - -```json -{ - "flag": "success", - "code": 200, - "message": "绑定商品成功", - "data": { - "detail_id": 12345, - "receiving_id": 10001, - "system_product_id": 67890, - "product_name": "测试商品A" - } -} -``` - -### 返回字段说明 - -| 字段 | 类型 | 说明 | -|---|---:|---| -| `flag` | `string` | 固定为 `success` | -| `code` | `number` | 业务状态码,成功为 `200` | -| `message` | `string` | 返回说明 | -| `data.detail_id` | `number` | 当前绑定的收货单明细 ID | -| `data.receiving_id` | `number` | 收货单 ID | -| `data.system_product_id` | `number` | 当前绑定的系统商品 ID | -| `data.product_name` | `string` | 自动回填的商品名称 | - -> 注意:该项目的 system 方法经常返回 HTTP `200`,业务是否成功请以响应体内的 `code` 和 `message` 为准。 - ---- - -## 5. 业务校验规则 - -接口内部会执行以下校验: - -1. **当前用户必须有仓库上下文** - - 仓库 ID 取自 `ctx.user.store_id` -2. **收货单明细必须存在** -3. **收货单明细必须属于当前仓库** -4. **收货单状态必须为 `receiving`** - - 已完成、已作废等状态不允许继续绑定或改绑 -5. **目标商品必须属于当前仓库** - - 根据 `StockWarehouse.id + warehouse_id` 校验 - ---- - -## 6. 失败返回示例与错误码 - -### 常见失败场景 - -| `code` | `message` 示例 | 含义 | -|---:|---|---| -| `400` | `用户未绑定仓库` | 当前用户无仓库角色上下文 | -| `400` | `收货单明细ID不能为空` | 未传 `detail_id` / `id` | -| `400` | `商品ID不能为空` | 未传 `system_product_id` | -| `400` | `收货单状态不允许绑定或改绑商品` | 当前收货单状态不允许继续操作 | -| `404` | `收货单明细不存在` | 明细不存在或不属于当前仓库 | -| `404` | `商品不存在或不属于当前仓库` | 商品不存在或仓库不匹配 | -| `500` | `绑定商品失败: ` | 服务内部异常 | - -### 失败响应示例 - -```json -{ - "flag": "success", - "code": 404, - "message": "商品不存在或不属于当前仓库" -} -``` - ---- - -## 7. 推荐调用链路 - -典型前端操作顺序如下: - -1. `storage.receiving.create`:创建收货单 -2. `storage.receiving.addDetail`:新增空白明细,拿到 `selectId` -3. `storage.receiving.bindDetailProduct`:绑定系统商品 -4. `storage.receiving.detailChange`:补充数量、箱数、备注等字段 -5. `storage.receiving.completeReceiving`:完成收货 - -其中第 2 步新增明细后,一般会返回: - -```json -{ - "data": { - "selectId": 12345 - } -} -``` - -该 `selectId` 即可直接作为 `bindDetailProduct` 的 `detail_id`。 - ---- - -## 8. 回归验证参考 - -仓库中已有接口级回归用例,可作为联调参考: - -- `test/app/controller/system.storage.receiving.test.js` - -已覆盖的场景包括: - -- 新建收货单后绑定商品 -- 已绑定商品后再次改绑 -- 绑定成功后返回 `detail_id`、`system_product_id`、`product_name` - ---- - -## 9. 实现位置(源码定位) - -### system 方法包装层 - -- 文件:`app/service/systemMethods/storage/receiving.js` -- 方法:`bindDetailProduct(data)` - -### 实际业务实现 - -- 文件:`app/service/systems/storage/receiving.js` -- 方法:`bindDetailProduct(data)` - ---- - -## 10. 当前接口结论 - -`storage.receiving.bindDetailProduct` 当前已支持: - -- **绑定** 收货明细商品 -- **改绑** 收货明细商品 -- 自动回填商品名称、条码、重量、箱规等信息 -- 自动刷新收货单统计数据 - -适合作为收货单明细与系统商品标准匹配接口对外说明使用。 - ---- - -## 11. 接口:storage.receiving.detailChange - -### 11.1 接口用途 - -用于修改收货单明细(明细行)中的数量、箱规、批次与商品信息,并触发收货单统计与相关联动(例如库存/统计刷新与操作日志)。典型场景为:前端在录入收货明细后,补录实际收货数量、箱数、托盘数、批次/生产/到期信息或回写条码与商品名称等。 - -> 注意:方法在 system 层以 `POST /system?method=storage.receiving.detailChange` 调用,需包含 `Authorization: Bearer `,仓库上下文来源于 `ctx.user.store_id`。 - -### 11.2 请求参数 - -| 字段 | 类型 | 必填 | 说明 | -|---|---:|---:|---| -| `id` | `number` | 是 | 收货明细 ID(必填) | -| `receiving_id` | `number` | 是 | 收货单 ID(必填) | -| `actual_quantity` | `number` | 否 | 实际收货数量 | -| `batch_number` | `string` | 否 | 批次号 | -| `production_date` | `string` | 否 | 生产日期(ISO 或可解析的日期字符串) | -| `expiry_date` | `string` | 否 | 到期日期(ISO 或可解析的日期字符串)。若传入的 `expiry_date` 小于当前日期,接口会拒绝并返回 400(见错误码) | -| `box_quantity` | `number` | 否 | 箱数 | -| `boxes_per_pallet` | `number` | 否 | 每托盘箱数 | -| `pallet_quantity` | `number` | 否 | 托盘数 | -| `space_id` | `number` | 否 | 目标库位 ID(可用于回写库位) | -| `remark` | `string` | 否 | 备注 | -| `system_product_id` | `number` | 否 | 系统商品 ID(StockWarehouse.id)。若提供,系统会回填条码、重量、箱规、商品名称与快照等;若不提供,可单独更新 `barcode`/`product_name` | -| `barcode` | `string` | 否 | 条码(当未传 `system_product_id` 时,可单独更新) | -| `product_name` | `string` | 否 | 商品名称(当未传 `system_product_id` 时,可单独更新) | -| `box_width` | `number` | 否 | 箱宽(单位按系统约定) | -| `box_height` | `number` | 否 | 箱高 | -| `box_length` | `number` | 否 | 箱长 | -| `box_remainder` | `number` | 否 | 箱内剩余数量/零散数量(不满箱时的件数) | -| `box_weight` | `number` | 否 | 实测箱重(单位与系统重量一致,如 kg) | -| `weight` | `number` | 否 | 毛重/重量 | - -> 说明:`id` 与 `receiving_id` 为必须校验项,其他字段为可选—仅在传入时会写入/覆盖对应明细字段。传入 `system_product_id` 时,系统优先使用系统商品信息回填字段(前端可只传 `system_product_id` 来自动回填)。 - -### 11.3 请求示例 - -```json -{ - "id": 501, - "receiving_id": 123, - "actual_quantity": 10, - "batch_number": "B20260401", - "production_date": "2026-04-01", - "expiry_date": "2027-04-01", - "box_quantity": 2, - "boxes_per_pallet": 10, - "pallet_quantity": 0, - "space_id": 1001, - "remark": "样例备注", - "system_product_id": 8888 -} -``` - -### 11.4 返回结构(成功) - -成功时返回 `code: 200`,`message` 为 `修改成功`,`data` 中包含基础标识与关键展示字段: - -```json -{ - "code": 200, - "message": "修改成功", - "data": { - "id": 501, - "receiving_id": 123, - "actual_quantity": 1, - "product_name": "测试商品", - "barcode": "", - "system_product_id": null, - "box_remainder": 0, - "box_weight": 0.0, - "updated_at": "2026-04-01T00:00:00.000Z" - } -} -``` - -返回字段说明: - -- `data.id`:收货明细 ID -- `data.receiving_id`:收货单 ID -- `data.actual_quantity`:明细当前的实际收货数量(根据实现,此处返回服务端查询到的明细值) -- `data.product_name`:商品名称(若 `system_product_id` 回填则为系统商品名称) -- `data.barcode`:条码 -- `data.system_product_id`:回填或当前关联的系统商品 ID -- `data.box_remainder`:箱内剩余数量/零散数量(不满箱时的件数) -- `data.box_weight`:实测箱重(单位与系统重量一致) -- `data.updated_at`:明细记录的更新时间 - -### 11.5 常见错误码 - -| code | message 示例 | 含义 | -|---:|---|---| -| `400` | `收货明细ID不能为空` | 未传 `id` | -| `400` | `收货单ID不能为空` | 未传 `receiving_id` | -| `400` | `到期日期已过期,不能录入收货` | `expiry_date` 小于当前日期时返回(禁止录入已过期批次) | -| `400` | `箱数不能为负数` / `托盘数不能为负数` | 非法的箱规数值 | -| `404` | `收货明细不存在` | 明细不存在或不属于当前仓库/收货单状态不允许操作 | -| `500` | `修改失败,请稍后重试` | 服务端异常 | - ---- - -### 11.6 业务要点与实现说明 - -- 若传入 `system_product_id`,服务端尝试读取 `StockWarehouse`(同仓库)并回填:`barcode`(若前端未显式传入),`weight`,`boxes_per_pallet`、`box_height`、`box_width`、`box_length`(若启用箱规),以及 `product_snapshot` 中的货主快照信息。 -- 若未传 `system_product_id`,但传入 `barcode` 或 `product_name`,服务端仍允许更新这两个字段(并把 `system_product_id` 置为 `null`)。 -- 接口会在成功写入明细后触发收货单统计刷新(`updateReceivingStats`)并写操作日志(`RECEIVING_UPDATE_DETAIL`)。 -- 系统存在一个库存效期预警定时任务,逻辑上会扫描启用保质期管理且设置了剩余天数阈值的商品,并按库存到期日筛选候选记录后进行去重通知发送;其判断条件主要依赖 `wms_stock_warehouse.is_shelf_life_mgmt = 'Y'`、`remaining_threshold_days > 0`,以及 `wms_storage.expiry_date`(小于等于当前时间加最大阈值天数)。 - ---- - -## 12. 接口:storage.receiving.getReceivingDetail - -## 接口:storage.receiving.get - -### 用途 - -查询收货单完整信息(含明细 `details`、`images` 等)。 - -### 请求参数 - -| 字段 | 类型 | 必填 | 说明 | -|---|---:|---|---| -| `id` | `number` | 是 | 收货单 ID(source=body) | - -### 返回字段补充 - -- `data.details.*.box_remainder`:number,可选,箱内剩余数量/零散数量(不满箱时的件数),默认 0。 -- `data.details.*.box_weight`:number,可选,实测箱重(单位与系统重量一致,如 kg),默认 0。 - -兼容性:新增字段为可选,旧客户端无需变更。 - -### 12.1 用途 - -查询单张收货单详情,返回收货单头信息与明细(`details`),用于前端展示或二次处理。 - -### 12.2 请求参数 - -| 字段 | 类型 | 必填 | 说明 | -|---|---:|---|---| -| `id` | `number` | 是 | 收货单 ID | -| `pagination` | `object` | 否 | 明细分页参数,支持 `page` / `pageSize` | - -### 12.3 返回示例(成功) - -```json -{ - "code": 200, - "message": "success", - "data": { - "receiving": { - "id": 12345, - "receiving_number": "RCV20260506001", - "details": [ - { - "id": 501, - "product_name": "测试商品", - "actual_quantity": 10, - "box_quantity": 2, - "box_remainder": 0, - "box_weight": 5.2 - } - ], - "pagination": { - "page": 1, - "pageSize": 20, - "total": 1 - } - } - } -} -``` - -### 12.4 返回字段说明(新增) - -- `receiving.details.*.box_remainder`:number,可选,箱内剩余数量/零散数量(不满箱时的件数)。 -- `receiving.details.*.box_weight`:number,可选,实测箱重(单位与系统重量一致,如 kg)。 - -## 13. 接口:storage.receiving.completeReceiving - -### 13.1 用途 - -完成收货操作;完成后系统会发送内部通知/回调,通知中会包含收货单明细层面的箱规回写信息。 - -### 13.2 通知说明(新增字段) - -完成收货时发送的通知 payload/metadata 将在每条明细中包含 `box_remainder` 与 `box_weight`,用于下游系统或前端展示箱内余量与实测箱重。通知示例(结构化示例,字段以实现为准): - -```json -{ - "event": "storage.receiving.completed", - "receiving_id": 12345, - "details": [ - { - "id": 501, - "box_remainder": 0, - "box_weight": 5.2 - } - ], - "metadata": { - "completed_by": 1001, - "completed_at": "2026-05-06T12:00:00.000Z" - } -} -``` - -### 13.3 字段说明(通知/metadata) - -- `details[*].box_remainder`:number,可选,箱内剩余数量/零散数量。 -- `details[*].box_weight`:number,可选,实测箱重,单位同系统重量(例如 kg)。 - -兼容性:上述新增字段为可选字段,旧版消费者在未识别这些字段时可忽略。 - ---- - -## 14. 收货→入库完整流程 - -### 14.1 流程概览 - -收货完成后,商品库存的实际入库通过以下步骤完成: - -1. **创建入库单** → `storage.entry` 系列方法(list/get/cancel/completeEntry) -2. **匹配入库(写库存)** → `storage.inventory.matchPutaway`(**目前唯一的库存写入入库链路**) - -> ⚠️ 注意:`storage.entry.completeEntry` 仅做入库单状态变更(PENDING → COMPLETED),**不涉及库存写入**。库存的实际写入统一由 `storage.inventory.matchPutaway` 完成。 - -### 14.2 完整推荐流程 - -``` -1. storage.receiving.create → 创建收货单 -2. storage.receiving.addDetail → 新增明细,拿到 selectId -3. storage.receiving.bindDetailProduct → 绑定系统商品 -4. storage.receiving.detailChange → 补充数量、批次等 -5. storage.receiving.completeReceiving → 完成收货 - ↓ -6. storage.entry 入库单管理 → 入库单与收货单通过 wms_entry_order_receiving 主表级关联 -7. storage.inventory.matchPutaway → 收货单与入库单匹配,完成库存写入 -8. storage.entry.completeEntry → 入库单状态标记为 COMPLETED(仅状态变更) -``` - -### 14.3 已弃用的方法 - -以下方法已从代码中移除,**不再可用**: - -| 已弃用方法 | 弃用原因 | 替代方案 | -|---|---|---| -| `storage.entry.bindReceivingDetails` | 入库单明细与收货明细逐行绑定(基于 `wms_entry_receiving_binding` 表),关系已改为 `wms_entry_order_receiving` 主表级关联 | 不再需要,入库单与收货单直接通过主表关联 | -| `storage.entry.unbindReceivingDetails` | 同上,逐行解绑已无必要 | 不再需要 | -| `storage.inventory.quickPutaway` | 单一收货单快捷转入库单(已重新实现):按 stock_id 合并收货明细创建入库单(SCRK,自动审批到 PENDING),写入主表级绑定 | `storage.entry.commitDirectInbound`(导入/PDA 入库完成确认) | - -### 14.4 核心方法职责 - -| 方法 | 职责 | 备注 | -|---|---|---| -| `storage.inventory.matchPutaway` | **唯一库存写入入库链路**:接收多个收货单和多个入库单,按商品进行数量匹配,完成库存的实际写入 | 入库后根据来源(QM/API)自动触发回传 | -| `storage.entry.completeEntry` | **仅状态变更**:入库单 PENDING → COMPLETED | 不涉及任何库存写入 | -| `storage.entry.list` | 入库单列表查询 | 支持 CREATING/CREATED/PENDING/COMPLETED/CANCELLED 状态筛选 | -| `storage.entry.get` | 入库单详情查询 | 含 items 及其 bindings | -| `storage.entry.cancel` | 作废入库单(CREATED/PENDING 可作废) | COMPLETED 不可作废 | - -### 14.5 关键数据库表关系 - -- `wms_entry_order_receiving`:入库单与收货单的**主表级关联**(当前方案) -- `wms_entry_receiving_binding`:**已弃用**,不再写入新数据(旧方案:明细级绑定) -- 收货单与入库单不再需要逐明细绑定,通过主表关联即可完成匹配入库 - diff --git a/methods/changes/system.json b/methods/changes/system.json index 85d490c..5956315 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -4673,5 +4673,47 @@ "文档中 isNeedLogin 为 false,但代码 systemMethods/quick/waybill.js 中 _noNeedLogin 为空字符串,未将 toOrder 加入免登录列表,实际需要登录验证,修正文档以与代码一致。" ], "type": "fixed" + }, + { + "version": "2026.07.03-system-01", + "date": "2026-07-03", + "summary": "binding 表弃用文档同步:wms_entry_receiving_binding 已弃用,功能迁移到 wms_inbound_direct_log 表;bindings 描述中表引用更新为 InboundDirectLog", + "methods": [ + "storage.entry.getDirectInboundItems" + ], + "notes": [ + "bindings 数组 description 中 wms_entry_receiving_binding 引用更新为 InboundDirectLog,明确旧表已弃用", + "binding_id description 中 wms_entry_receiving_binding.id 更新为 InboundDirectLog.id", + "allocated_quantity description 中补充来源 InboundDirectLog.quantity", + "wms_inbound_direct_log 表新增字段:entry_item_id、receiving_detail_id、status(ENUM: pending/committed/released)、updated_at、deleted_at" + ], + "type": "updated" + }, + { + "version": "2026.07.03-system-02", + "date": "2026-07-03", + "summary": "binding 表弃用文档同步:wms_entry_receiving_binding 已弃用,功能迁移到 wms_inbound_direct_log 表;bindings 描述中表引用更新为 InboundDirectLog", + "methods": [ + "storage.directInbound.getItems" + ], + "notes": [ + "bindings 数组 description 中更新为来自 InboundDirectLog,明确旧表已弃用", + "binding_id description 更新为 InboundDirectLog.id", + "allocated_quantity description 中补充来源 InboundDirectLog.quantity", + "wms_inbound_direct_log 表新增字段:entry_item_id、receiving_detail_id、status(ENUM: pending/committed/released)、updated_at、deleted_at" + ], + "type": "updated" + }, + { + "version": "2026.07.03-system-03", + "date": "2026-07-03", + "summary": "binding 表弃用文档同步:commitDirectInbound 描述中 EntryReceivingBinding 更新为 InboundDirectLog", + "methods": [ + "storage.entry.commitDirectInbound" + ], + "notes": [ + "commitDirectInbound description 中将 pending 状态的 EntryReceivingBinding 更新为 pending 状态的 InboundDirectLog,与代码实现一致" + ], + "type": "updated" } ] diff --git a/methods/system.json b/methods/system.json index afe7198..49fc145 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.5", - "updatedAt": "2026-07-02", + "version": "0.3.6", + "updatedAt": "2026-07-03", "headers": [ { "name": "platform", @@ -2708,6 +2708,82 @@ "description": "订单不存在或不属于当前仓库" } ] + }, + { + "method": "reviewOrder.detail", + "description": "查询单个订单详情,返回订单头、商品明细和运单信息", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "ids / id / order_id / orderId", + "type": "array|string|number", + "required": true, + "source": "body", + "description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项" + }, + { + "name": "tableType / tablePosition / type / moduleName", + "type": "string", + "required": false, + "source": "body", + "description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等" + } + ], + "response": [ + { + "name": "order", + "type": "object", + "required": true, + "description": "订单头对象(raw 行数据)" + }, + { + "name": "detail", + "type": "object", + "required": true, + "description": "等同于 order" + }, + { + "name": "orderItems / items", + "type": "array", + "required": true, + "description": "商品明细数组" + }, + { + "name": "expresses", + "type": "array", + "required": true, + "description": "运单信息数组" + }, + { + "name": "waybill_codes", + "type": "array", + "required": true, + "description": "去重后的运单号字符串数组" + } + ], + "errors": [ + { + "code": "400", + "message": "订单ID 为空或格式错误" + }, + { + "code": "404", + "message": "订单不存在或不属于当前仓库" + }, + { + "code": "500", + "message": "内部错误" + } + ] } ] }, @@ -18892,9 +18968,90 @@ ] }, { - "groupName": "入库管理", + "groupName": "入库模块", "module": "storage.entry", "list": [ + { + "method": "storage.entry.list", + "description": "入库单列表查询。where.order_status 支持 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。where 新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单(通过 wms_entry_order_receiving 表查询实现)。quickWhere 支持模糊搜索:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头,通过 wms_entry_order_receiving 绑定表关联搜索)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "pagination", + "type": "object", + "required": false, + "source": "body", + "description": "分页参数,支持 page/pageSize" + }, + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;支持 quickWhere、order_status(CREATING/CREATED/PENDING/COMPLETED/CANCELLED)、store_id、order_type、日期区间等字段。新增 expense_record(费用是否记录)筛选,支持 eq/in;值会归一化为 0/1,兼容 true/false、1/0、y/n、yes/no(大小写不敏感,含布尔/字符串/数字写法)。示例:where.expense_record={operator:eq,value:true} 等价 where.expense_record={operator:eq,value:1};where.expense_record={operator:in,value:[true,\"0\",\"yes\",\"n\"]} 会归一化为 [1,0]。若部署环境尚未完成 expense_record 字段迁移,传入该筛选可能返回 400,错误提示为\"当前环境未提供 expense_record 字段,暂不支持该筛选条件,请先完成表结构升级\"。新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单(虚拟字段,不直接对应数据库列,内部通过 wms_entry_order_receiving 表查询实现)。quickWhere 模糊搜索范围:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头,通过 wms_entry_order_receiving 绑定表关联搜索)。" + }, + { + "name": "sort", + "type": "object", + "required": false, + "source": "body", + "description": "排序参数,支持 sortField/sortOrder" + } + ], + "response": [ + { + "name": "list", + "type": "array", + "required": true, + "description": "入库单列表" + }, + { + "name": "pagination", + "type": "object", + "required": true, + "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" + }, + { + "name": "summary", + "type": "object", + "required": true, + "description": "状态汇总(total、pending、creating、created、completed、cancelled)" + }, + { + "name": "list[].receivingBindings", + "type": "array", + "required": false, + "description": "收货单绑定列表(主表级关联),每项含 id、entry_order_id、receiving_id 及 receiving 对象(id、receiving_number、status、storage_status、created_at)" + }, + { + "name": "list[].hasReceiving", + "type": "boolean", + "required": false, + "description": "是否存在收货单绑定" + } + ], + "errors": [ + { + "code": "400", + "message": "筛选条件格式错误", + "description": "筛选条件格式错误" + }, + { + "code": "500", + "message": "查询失败", + "description": "查询失败" + } + ] + }, { "method": "storage.entry.get", "description": "查询入库单详情。返回的 entryOrder 包含顶层 receivingBindings(主表级关联,含关联的收货单信息),不再返回 items[].bindings(明细级绑定)。entryOrder.order_status 可能为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。", @@ -19156,175 +19313,6 @@ } ] }, - { - "method": "storage.entry.getDirectInboundItems", - "description": "获取入库单的导入/PDA 入库信息(精简版)。返回入库单基本信息、明细列表(含计划数量 planned 与已完成数量 completed)、每项明细的收货绑定列表 bindings(含 detail_id、binding_id、allocated_quantity、space_id、space_name),以及收货单绑定关系 receivingBindings。", - "isNeedAuth": false, - "isNeedLogin": true, - "headers": [ - { - "name": "Authorization", - "type": "string", - "required": true, - "description": "Bearer token" - } - ], - "params": [ - { - "name": "entry_order_code", - "type": "string", - "required": true, - "source": "body", - "description": "入库单号" - } - ], - "response": [ - { - "name": "entryOrder", - "type": "object", - "required": true, - "description": "入库单基本信息", - "children": [ - { - "name": "id", - "type": "number", - "required": true, - "description": "入库单ID" - }, - { - "name": "entry_order_code", - "type": "string", - "required": true, - "description": "入库单号" - }, - { - "name": "order_status", - "type": "string", - "required": true, - "description": "入库单状态(CREATED/PENDING/COMPLETED/CANCELLED)" - }, - { - "name": "store_remask", - "type": "string", - "required": true, - "description": "货主商家备注" - } - ] - }, - { - "name": "items", - "type": "array", - "required": true, - "description": "入库明细列表", - "children": [ - { - "name": "id", - "type": "number", - "required": true, - "description": "入库明细ID(wms_entry_items.id)" - }, - { - "name": "stock_id", - "type": "number", - "required": true, - "description": "商品SKU ID" - }, - { - "name": "planned", - "type": "number", - "required": true, - "description": "计划入库数量(对应原 count 字段)" - }, - { - "name": "completed", - "type": "number", - "required": true, - "description": "已完成导入/PDA 入库数量(对应原 direct_inbound_quantity 字段)" - }, - { - "name": "stock", - "type": "object", - "required": true, - "description": "商品详情(含 item_code、item_name、sku_property、barcodes 等缓存字段)" - }, - { - "name": "bindings", - "type": "array", - "required": true, - "description": "该明细的收货单绑定列表(来自 wms_entry_receiving_binding + InboundDirectLog)", - "children": [ - { - "name": "detail_id", - "type": "number", - "required": false, - "description": "收货明细ID(wms_receiving_detail.id),无绑定时可能不存在" - }, - { - "name": "binding_id", - "type": "number", - "required": false, - "description": "绑定记录ID(wms_entry_receiving_binding.id),无绑定时可能不存在" - }, - { - "name": "allocated_quantity", - "type": "number", - "required": false, - "description": "预分配数量" - }, - { - "name": "space_id", - "type": "number", - "required": false, - "description": "存放库位ID(取自 InboundDirectLog)" - }, - { - "name": "space_name", - "type": "string", - "required": false, - "description": "库位名称(取自 wms_location_space.custom_name 或 space_code)" - } - ] - } - ] - }, - { - "name": "receivingBindings", - "type": "array", - "required": true, - "description": "入库单层级的收货单绑定关系列表(wms_entry_order_receiving)", - "children": [ - { - "name": "id", - "type": "number", - "required": true, - "description": "绑定记录ID" - }, - { - "name": "receiving_id", - "type": "number", - "required": true, - "description": "收货单ID" - }, - { - "name": "receiving", - "type": "object", - "required": true, - "description": "收货单信息(id、receiving_number、status、storage_status、created_at)" - } - ] - } - ], - "errors": [ - { - "code": 400, - "message": "entry_order_code 必填" - }, - { - "code": 404, - "message": "入库单不存在或无权访问" - } - ] - }, { "method": "storage.entry.addDirectInboundItem", "description": "按商品增量添加导入/PDA 入库记录(支持单条和批量)。单条模式传 stock_id/quantity/inbound_type/remark,批量模式传 items 数组。批量模式所有商品共享同一个入库单状态校验,任一商品校验失败整批拒绝。若某商品累计入库量超过计划数量则拒绝(PENDING 非绑定模式)。PENDING 状态需传 receiving_detail_id 绑定收货明细;CREATED 人工导入允许超过计划数量;传入 receiving_detail_id 时 quantity 可选(自动计算可用数量),space_id 必填。", @@ -19532,7 +19520,7 @@ }, { "method": "storage.entry.commitDirectInbound", - "description": "提交确认完成导入/PDA 入库。先同步奇门/API 回传,成功后在 onSuccess 回调内开启事务写入库存(wms_stock_warehouse.quantity 增量、wms_stock_transaction 流水),将 pending 状态的 EntryReceivingBinding 更新为 committed,更新入库单状态为 COMPLETED,同步 sync_status=SUCCESS。不足量提交时未入库商品跳过。", + "description": "提交确认完成导入/PDA 入库。先同步奇门/API 回传,成功后在 onSuccess 回调内开启事务写入库存(wms_stock_warehouse.quantity 增量、wms_stock_transaction 流水),将 pending 状态的 InboundDirectLog 更新为 committed,更新入库单状态为 COMPLETED,同步 sync_status=SUCCESS。不足量提交时未入库商品跳过。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -20320,458 +20308,6 @@ } ] }, - { - "groupName": "导入/PDA直接入库", - "module": "storage.directInbound", - "list": [ - { - "method": "storage.directInbound.getItems", - "description": "[@deprecated 已弃用,请使用 storage.entry.getDirectInboundItems 替代] 获取入库单的导入/PDA 入库信息(精简版)。返回入库单基本信息、明细列表(含计划数量 planned 与已完成数量 completed)、每项明细的收货绑定列表 bindings(含 detail_id、binding_id、allocated_quantity、space_id、space_name),以及收货单绑定关系 receivingBindings。", - "isNeedAuth": false, - "isNeedLogin": true, - "headers": [ - { - "name": "Authorization", - "type": "string", - "required": true, - "description": "Bearer token" - } - ], - "params": [ - { - "name": "entry_order_code", - "type": "string", - "required": true, - "source": "body", - "description": "入库单号" - } - ], - "response": [ - { - "name": "entryOrder", - "type": "object", - "required": true, - "description": "入库单基本信息", - "children": [ - { - "name": "id", - "type": "number", - "required": true, - "description": "入库单ID" - }, - { - "name": "entry_order_code", - "type": "string", - "required": true, - "description": "入库单号" - }, - { - "name": "order_status", - "type": "string", - "required": true, - "description": "入库单状态(CREATED/PENDING/COMPLETED/CANCELLED)" - }, - { - "name": "store_remask", - "type": "string", - "required": true, - "description": "货主商家备注" - } - ] - }, - { - "name": "items", - "type": "array", - "required": true, - "description": "入库明细列表", - "children": [ - { - "name": "id", - "type": "number", - "required": true, - "description": "入库明细ID(wms_entry_items.id)" - }, - { - "name": "stock_id", - "type": "number", - "required": true, - "description": "商品SKU ID" - }, - { - "name": "planned", - "type": "number", - "required": true, - "description": "计划入库数量(对应原 count 字段)" - }, - { - "name": "completed", - "type": "number", - "required": true, - "description": "已完成导入/PDA 入库数量(对应原 direct_inbound_quantity 字段)" - }, - { - "name": "stock", - "type": "object", - "required": true, - "description": "商品详情(含 item_code、item_name、sku_property、barcodes 等缓存字段)" - }, - { - "name": "bindings", - "type": "array", - "required": true, - "description": "该明细的收货单绑定列表", - "children": [ - { - "name": "detail_id", - "type": "number", - "required": false, - "description": "收货明细ID" - }, - { - "name": "binding_id", - "type": "number", - "required": false, - "description": "绑定记录ID" - }, - { - "name": "allocated_quantity", - "type": "number", - "required": false, - "description": "预分配数量" - }, - { - "name": "space_id", - "type": "number", - "required": false, - "description": "存放库位ID" - }, - { - "name": "space_name", - "type": "string", - "required": false, - "description": "库位名称" - } - ] - } - ] - }, - { - "name": "receivingBindings", - "type": "array", - "required": true, - "description": "入库单层级的收货单绑定关系列表", - "children": [ - { - "name": "id", - "type": "number", - "required": true, - "description": "绑定记录ID" - }, - { - "name": "receiving_id", - "type": "number", - "required": true, - "description": "收货单ID" - }, - { - "name": "receiving", - "type": "object", - "required": true, - "description": "收货单信息(id、receiving_number、status、storage_status、created_at)" - } - ] - } - ], - "errors": [ - { - "code": 400, - "message": "entry_order_code 必填" - }, - { - "code": 404, - "message": "入库单不存在或无权访问" - } - ] - }, - { - "method": "storage.directInbound.addItem", - "description": "[@deprecated 已弃用,请使用 storage.entry.addDirectInboundItem 替代] 按商品增量添加导入/PDA 入库记录(支持单条和批量)。单条模式传 stock_id/quantity/inbound_type/remark,批量模式传 items 数组。批量模式所有商品共享同一个入库单状态校验,任一商品校验失败整批拒绝。若某商品累计入库量超过计划数量则拒绝。", - "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": "stock_id", - "type": "number", - "required": true, - "source": "body", - "description": "商品SKU ID(对应 wms_stock_warehouse.id)" - }, - { - "name": "quantity", - "type": "number", - "required": true, - "source": "body", - "description": "本次入库数量(正整数)" - }, - { - "name": "inbound_type", - "type": "string", - "required": true, - "source": "body", - "description": "入库方式:import(导入入库)、pda(PDA入库)" - }, - { - "name": "remark", - "type": "string", - "required": false, - "source": "body", - "description": "备注(如导入文件名、PDA操作备注等)" - }, - { - "name": "space_id", - "type": "number", - "required": false, - "source": "body", - "description": "存放库位ID(单条模式),关联 wms_location_space.id;为空时 commit 默认使用库位 1" - }, - { - "name": "items", - "type": "array", - "required": false, - "source": "body", - "description": "批量模式:商品列表,每项包含 stock_id(商品SKU ID, number, 必填)、quantity(入库数量, number, 必填)、inbound_type(import/pda, string, 必填)、space_id(库位ID, number, 可选)、remark(备注, string, 可选)。传入 items 时忽略顶层的 stock_id/quantity/inbound_type/remark/space_id。" - } - ], - "response": [ - { - "name": "id", - "type": "number", - "required": false, - "description": "单条模式返回:新增的入库记录ID" - }, - { - "name": "stock_id", - "type": "number", - "required": false, - "description": "单条模式返回:商品SKU ID" - }, - { - "name": "quantity", - "type": "number", - "required": false, - "description": "单条模式返回:本次入库数量" - }, - { - "name": "inbound_type", - "type": "string", - "required": false, - "description": "单条模式返回:入库方式" - }, - { - "name": "plan_quantity", - "type": "number", - "required": false, - "description": "单条模式返回:该商品计划入库总数" - }, - { - "name": "existing_before", - "type": "number", - "required": false, - "description": "单条模式返回:本次入库前已入库数量" - }, - { - "name": "existing_after", - "type": "number", - "required": false, - "description": "单条模式返回:本次入库后总入库数量" - }, - { - "name": "remaining", - "type": "number", - "required": false, - "description": "单条模式返回:剩余可入库数量" - }, - { - "name": "count", - "type": "number", - "required": false, - "description": "批量模式返回:成功添加的条目数" - }, - { - "name": "total_quantity", - "type": "number", - "required": false, - "description": "批量模式返回:入库总数量" - }, - { - "name": "items", - "type": "array", - "required": false, - "description": "批量模式返回:入库结果列表,每项包含 id/stock_id/quantity/inbound_type/space_id/plan_quantity/existing_before/existing_after/remaining" - } - ], - "errors": [ - { - "code": 400, - "message": "参数校验失败:entry_order_code 必填 / stock_id 必填 / quantity 必须为正整数 / inbound_type 必须为 import 或 pda / 已作废入库单不允许操作 / 已完成的入库单不允许操作 / 入库单中不存在该 stock_id 的商品 / 入库数量超过计划" - }, - { - "code": 404, - "message": "入库单不存在或无权访问" - } - ] - }, - { - "method": "storage.directInbound.commit", - "description": "[@deprecated 已弃用,请使用 storage.entry.commitDirectInbound 替代] 提交确认完成导入/PDA 入库。按实收数量写入库存(wms_storage、wms_stock_transaction),未入库商品跳过不做处理,更新入库单状态为 COMPLETED,并异步触发奇门/API 入库完成回传(按实收数量回传)。", - "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": "id", - "type": "number", - "required": true, - "description": "入库单ID" - }, - { - "name": "entry_order_code", - "type": "string", - "required": true, - "description": "入库单号" - }, - { - "name": "order_status", - "type": "string", - "required": true, - "description": "入库单状态(固定为 COMPLETED)" - }, - { - "name": "sync_status", - "type": "string", - "required": true, - "description": "同步状态(固定为 SUCCESS)" - }, - { - "name": "items_count", - "type": "number", - "required": true, - "description": "入库商品种类数" - }, - { - "name": "total_quantity", - "type": "number", - "required": true, - "description": "入库总数量" - } - ], - "errors": [ - { - "code": 400, - "message": "entry_order_id 必填" - }, - { - "code": 400, - "message": "已作废入库单不允许完成 / 入库单已完成请勿重复提交 / 暂无导入/PDA 入库记录请先添加商品 / 入库单无明细" - }, - { - "code": 404, - "message": "入库单不存在或无权访问" - } - ] - }, - { - "method": "storage.directInbound.removeItem", - "description": "[@deprecated 已弃用,请使用 storage.entry.removeDirectInboundItem 替代] 移除一条导入/PDA 入库记录(仅限未提交的入库单,即状态非 CANCELLED/COMPLETED)。移除后该商品的可入库余量自动恢复。", - "isNeedAuth": false, - "isNeedLogin": true, - "headers": [ - { - "name": "Authorization", - "type": "string", - "required": true, - "description": "Bearer token" - } - ], - "params": [ - { - "name": "id", - "type": "number", - "required": true, - "source": "body", - "description": "入库记录ID(wms_inbound_direct_log.id)" - } - ], - "response": [ - { - "name": "id", - "type": "number", - "required": true, - "description": "已移除的入库记录ID" - }, - { - "name": "stock_id", - "type": "number", - "required": true, - "description": "商品SKU ID" - }, - { - "name": "quantity", - "type": "number", - "required": true, - "description": "移除的入库数量" - }, - { - "name": "inbound_type", - "type": "string", - "required": true, - "description": "入库方式" - } - ], - "errors": [ - { - "code": 400, - "message": "id 必填 / 已作废入库单不允许操作 / 已完成的入库单不允许移除记录" - }, - { - "code": 404, - "message": "入库记录不存在 / 关联入库单不存在或无权访问" - } - ] - } - ] - }, { "groupName": "出库单模块", "module": "storage.stockout", @@ -26348,93 +25884,6 @@ } ] }, - { - "groupName": "入库模块", - "module": "storage", - "list": [ - { - "method": "storage.entry.list", - "description": "入库单列表查询。where.order_status 支持 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。where 新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单(通过 wms_entry_order_receiving 表查询实现)。quickWhere 支持模糊搜索:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头,通过 wms_entry_order_receiving 绑定表关联搜索)。", - "isNeedAuth": false, - "isNeedLogin": true, - "headers": [ - { - "name": "Authorization", - "type": "string", - "required": true, - "description": "Bearer token" - } - ], - "params": [ - { - "name": "pagination", - "type": "object", - "required": false, - "source": "body", - "description": "分页参数,支持 page/pageSize" - }, - { - "name": "where", - "type": "object", - "required": false, - "source": "body", - "description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;支持 quickWhere、order_status(CREATING/CREATED/PENDING/COMPLETED/CANCELLED)、store_id、order_type、日期区间等字段。新增 expense_record(费用是否记录)筛选,支持 eq/in;值会归一化为 0/1,兼容 true/false、1/0、y/n、yes/no(大小写不敏感,含布尔/字符串/数字写法)。示例:where.expense_record={operator:eq,value:true} 等价 where.expense_record={operator:eq,value:1};where.expense_record={operator:in,value:[true,\"0\",\"yes\",\"n\"]} 会归一化为 [1,0]。若部署环境尚未完成 expense_record 字段迁移,传入该筛选可能返回 400,错误提示为\"当前环境未提供 expense_record 字段,暂不支持该筛选条件,请先完成表结构升级\"。新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单(虚拟字段,不直接对应数据库列,内部通过 wms_entry_order_receiving 表查询实现)。quickWhere 模糊搜索范围:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头,通过 wms_entry_order_receiving 绑定表关联搜索)。" - }, - { - "name": "sort", - "type": "object", - "required": false, - "source": "body", - "description": "排序参数,支持 sortField/sortOrder" - } - ], - "response": [ - { - "name": "list", - "type": "array", - "required": true, - "description": "入库单列表" - }, - { - "name": "pagination", - "type": "object", - "required": true, - "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" - }, - { - "name": "summary", - "type": "object", - "required": true, - "description": "状态汇总(total、pending、creating、created、completed、cancelled)" - }, - { - "name": "list[].receivingBindings", - "type": "array", - "required": false, - "description": "收货单绑定列表(主表级关联),每项含 id、entry_order_id、receiving_id 及 receiving 对象(id、receiving_number、status、storage_status、created_at)" - }, - { - "name": "list[].hasReceiving", - "type": "boolean", - "required": false, - "description": "是否存在收货单绑定" - } - ], - "errors": [ - { - "code": "400", - "message": "筛选条件格式错误", - "description": "筛选条件格式错误" - }, - { - "code": "500", - "message": "查询失败", - "description": "查询失败" - } - ] - } - ] - }, { "groupName": "快捷操作", "module": "quick", diff --git a/skills/entry-order-test-guide.md b/skills/entry-order-test-guide.md index 163288c..3638961 100644 --- a/skills/entry-order-test-guide.md +++ b/skills/entry-order-test-guide.md @@ -276,8 +276,8 @@ curl -s -X POST "http://localhost:6060/system?method=storage.entry.quickInbound" | `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` | 入库明细↔收货明细绑定 | id, entry_item_id, receiving_detail_id, quantity | -| `wms_inbound_direct_log` | PDA直入记录 | id, entry_id, item_code, quantity, space_id, receiving_detail_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 |