From 736ad343515adbda5ddbbf54c3359ded73f83832 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Thu, 14 May 2026 15:57:51 +0800 Subject: [PATCH] =?UTF-8?q?=E6=89=93=E5=8D=B0=E5=8F=B0=E7=AE=A1=E7=90=86?= =?UTF-8?q?=E5=8F=98=E6=9B=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- app/model/print_station_express.js | 86 ----- app/model/print_stations.js | 98 +++++- app/service/systemMethods/print.js | 98 ++++-- ...dd-subject-config-to-wms_print_stations.js | 37 ++ ...14123000-drop-wms_print_station_express.js | 85 +++++ docs/express-model-table-map.md | 4 +- methods/system.json | 323 ++++++++++++------ test/app/model/print_stations.test.js | 101 ++++++ .../systemMethods/print.savePrinters.test.js | 193 +++++++++++ .../service/systemMethods/print.send.test.js | 46 +++ 10 files changed, 857 insertions(+), 214 deletions(-) delete mode 100644 app/model/print_station_express.js create mode 100644 database/migrations/20260514110000-add-subject-config-to-wms_print_stations.js create mode 100644 database/migrations/20260514123000-drop-wms_print_station_express.js create mode 100644 test/app/model/print_stations.test.js create mode 100644 test/app/service/systemMethods/print.savePrinters.test.js diff --git a/app/model/print_station_express.js b/app/model/print_station_express.js deleted file mode 100644 index 602c022..0000000 --- a/app/model/print_station_express.js +++ /dev/null @@ -1,86 +0,0 @@ -'use strict'; - -module.exports = app => { - const { INTEGER, BIGINT, STRING, DATE, TINYINT } = app.Sequelize; - const PrintStationExpress = app.model.define('print_station_express', { - id: { - type: INTEGER.UNSIGNED, - autoIncrement: true, - primaryKey: true, - comment: '自增主键ID', - }, - print_station_id: { - type: STRING(32), - allowNull: false, - comment: '打印台ID,关联wms_print_stations表的print_station_id', - }, - express_id: { - type: STRING(32), - allowNull: false, - comment: '快递ID', - }, - express_name: { - type: STRING(50), - allowNull: false, - comment: '快递名称,冗余字段,便于查询', - }, - printer_name: { - type: STRING(100), - allowNull: false, - comment: '绑定的打印机名称', - }, - creator_id: { - type: BIGINT.UNSIGNED, - allowNull: false, - comment: '创建人工号ID', - }, - creator_name: { - type: STRING(50), - allowNull: false, - comment: '创建人名称', - }, - create_at: { - type: DATE, - allowNull: false, - comment: '创建时间', - }, - update_at: { - type: DATE, - allowNull: false, - comment: '更新时间', - }, - deleted: { - type: TINYINT, - allowNull: false, - defaultValue: 0, - comment: '软删除标记:0-未删除,1-已删除', - }, - }, { - tableName: 'wms_print_station_express', - freezeTableName: true, - underscored: false, - timestamps: false, - indexes: [ - { - unique: true, - name: 'uk_print_station_express', - fields: [ 'print_station_id', 'express_id', 'deleted' ], - }, - { - name: 'idx_print_station_id', - fields: [ 'print_station_id' ], - }, - { - name: 'idx_express_id', - fields: [ 'express_id' ], - }, - { - name: 'idx_creator_id', - fields: [ 'creator_id' ], - }, - ], - comment: '打印台快递-打印机绑定关系表', - }); - - return PrintStationExpress; -}; diff --git a/app/model/print_stations.js b/app/model/print_stations.js index f4cb348..51278fe 100644 --- a/app/model/print_stations.js +++ b/app/model/print_stations.js @@ -1,7 +1,83 @@ 'use strict'; module.exports = app => { - const { INTEGER, BIGINT, STRING, DATE, TINYINT } = app.Sequelize; + const { INTEGER, BIGINT, STRING, DATE, TINYINT, JSON: JSON_TYPE } = app.Sequelize; + + const DEFAULT_SUBJECT_CONFIG = Object.freeze({ + express_bind_printer: Object.freeze([]), + }); + + /** + * 规范化快递绑定打印机配置。 + * + * @param {Array|null|undefined|string} rawList 原始快递绑定打印机配置。 + * @return {Array} 规范化后的快递绑定打印机配置。 + */ + const normalizeExpressBindPrinter = rawList => { + if (rawList === undefined || rawList === null || rawList === '') { + return []; + } + + if (!Array.isArray(rawList)) { + throw new Error('subject_config.express_bind_printer 必须是数组'); + } + + return rawList.map((item, index) => { + const basePath = `subject_config.express_bind_printer[${index}]`; + if (!item || typeof item !== 'object' || Array.isArray(item)) { + throw new Error(`${basePath} 必须是对象`); + } + + const printerName = String(item.printer_name === undefined || item.printer_name === null ? '' : item.printer_name).trim(); + if (!printerName) { + throw new Error(`${basePath}.printer_name 不能为空`); + } + + const expressCode = String(item.express_code === undefined || item.express_code === null ? '' : item.express_code).trim(); + if (!expressCode) { + throw new Error(`${basePath}.express_code 不能为空`); + } + + return { + printer_name: printerName, + express_code: expressCode, + }; + }); + }; + + /** + * 规范化打印台主体配置。 + * + * @param {Object|string|null|undefined} rawValue 原始主体配置。 + * @return {Object} 规范化后的主体配置。 + */ + const normalizeSubjectConfig = rawValue => { + if (rawValue === undefined || rawValue === null || rawValue === '') { + return { + ...DEFAULT_SUBJECT_CONFIG, + express_bind_printer: [], + }; + } + + let parsed = rawValue; + if (typeof parsed === 'string') { + try { + parsed = JSON.parse(parsed); + } catch (error) { + throw new Error('subject_config 必须是合法 JSON 对象'); + } + } + + if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) { + throw new Error('subject_config 必须是对象'); + } + + return { + ...parsed, + express_bind_printer: normalizeExpressBindPrinter(parsed.express_bind_printer), + }; + }; + const PrintStations = app.model.define('print_stations', { id: { type: INTEGER.UNSIGNED, @@ -60,6 +136,23 @@ module.exports = app => { defaultValue: 0, comment: '软删除标记:0-未删除,1-已删除', }, + subject_config: { + type: JSON_TYPE, + allowNull: true, + defaultValue: { ...DEFAULT_SUBJECT_CONFIG, express_bind_printer: [] }, + comment: '打印台主体配置', + get() { + return normalizeSubjectConfig(this.getDataValue('subject_config')); + }, + set(value) { + this.setDataValue('subject_config', normalizeSubjectConfig(value)); + }, + validate: { + isValidSubjectConfig(value) { + normalizeSubjectConfig(value); + }, + }, + }, }, { tableName: 'wms_print_stations', freezeTableName: true, @@ -99,5 +192,8 @@ module.exports = app => { comment: '打印台信息表', }); + PrintStations.DEFAULT_SUBJECT_CONFIG = DEFAULT_SUBJECT_CONFIG; + PrintStations.normalizeSubjectConfig = normalizeSubjectConfig; + return PrintStations; }; diff --git a/app/service/systemMethods/print.js b/app/service/systemMethods/print.js index e359306..114b342 100644 --- a/app/service/systemMethods/print.js +++ b/app/service/systemMethods/print.js @@ -31,9 +31,9 @@ class PrintService extends MainService { /** * 发送打印任务到打印电脑。 - * 仅在 type=customize 时要求 template、page_width、page_height、template_content。 + * 仅在 type=customize 时要求 printer、template、page_width、page_height、template_content。 * @param {Object} _data 打印请求参数 - * @param {string} _data.printer 打印机名称 + * @param {string} [_data.printer] 打印机名称(type=customize 必填,type=express 可不传) * @param {string} _data.type 打印类型,支持 customize/express * @param {Object} [_data.template] 打印模板对象(customize 必填) * @param {Object} _data.data 打印业务数据 @@ -59,6 +59,9 @@ class PrintService extends MainService { let processedData = {}; switch (type) { case 'customize': { + if (printer === undefined || printer === null || printer === '') { + return this.fail('type=customize 时 printer 参数不能为空', { code: 400 }); + } if (!template || typeof template !== 'object' || Array.isArray(template)) { return this.fail('type=customize 时 template 参数不能为空', { code: 400 }); } @@ -326,13 +329,14 @@ class PrintService extends MainService { /** * 3. 添加打印台 * @param {Object} data { id, name, computer_id, custom_barcode } + * @returns {Promise} 返回新增结果。 */ async add(data) { const { ctx } = this; const warehouse_id = ctx.user.store_id; - const { name, computer_id, custom_barcode } = data; + const { name, computer_id, custom_barcode, subject_config } = data; if (!name || !computer_id) return this.fail('参数错误', 1001); - const newItem = await ctx.model.PrintStations.create({ + const createPayload = { warehouse_id, name, computer_id, @@ -343,7 +347,17 @@ class PrintService extends MainService { create_at: new Date(), update_at: new Date(), deleted: 0, - }); + }; + + if (Object.prototype.hasOwnProperty.call(data, 'subject_config')) { + try { + createPayload.subject_config = ctx.model.PrintStations.normalizeSubjectConfig(subject_config); + } catch (error) { + return this.fail(error.message, 1001); + } + } + + const newItem = await ctx.model.PrintStations.create(createPayload); return this.success('添加打印台成功', { data: newItem, code: 0 }); } async hasName(data) { @@ -357,10 +371,11 @@ class PrintService extends MainService { /** * 3. 修改打印台 * @param {Object} data { id, name, computer_id, custom_barcode } + * @returns {Promise} 返回更新结果。 */ async updateItem(data) { const { ctx } = this; - const { id, name, computer_id, custom_barcode } = data; + const { id, name, computer_id, custom_barcode, subject_config } = data; if (!id) return this.fail('参数错误', 1001); const item = await ctx.model.PrintStations.findOne({ where: { id } }); if (!item) return this.fail('打印台不存在', 1002); @@ -368,6 +383,13 @@ class PrintService extends MainService { if (name !== undefined) item.name = name; if (computer_id !== undefined) item.computer_id = computer_id; if (custom_barcode !== undefined) item.custom_barcode = custom_barcode; + if (Object.prototype.hasOwnProperty.call(data, 'subject_config')) { + try { + item.subject_config = ctx.model.PrintStations.normalizeSubjectConfig(subject_config); + } catch (error) { + return this.fail(error.message, 1001); + } + } await item.save(); return this.success('success', { data: null, code: 0 }); } @@ -417,34 +439,52 @@ class PrintService extends MainService { } /** - * 8. 保存打印台的快递-打印机绑定 - * @param {Object} data { defaultPrinter, express, print_station_id } + * 8. 保存打印台的默认打印机与快递绑定打印机配置。 + * @param {Object} data 请求参数。 + * @param {string} data.defaultPrinter 默认打印机名称,必填。 + * @param {Array} data.express 快递绑定数组,必填。 + * @param {number|string} data.print_station_id 打印台 ID,必填。 + * @returns {Promise} 保存结果。 */ async savePrinters(data) { const { ctx } = this; - const { defaultPrinter, express } = data; - // express: [{ express_id, name }] - if (!defaultPrinter || !Array.isArray(express)) return this.fail('参数错误', 1001); - // TODO: 需根据打印台ID、快递ID等实际业务调整 - // 这里只做示例保存,实际应覆盖原有绑定 - // 1. 保存默认打印机 - // 2. 保存 express 打印机绑定 - // 3. 需用 PrintStationExpress model - // 示例:批量保存 - for (const item of express) { - await ctx.model.PrintStationExpress.upsert({ - print_station_id: data.print_station_id, // 需传入 - express_id: item.express_id, - express_name: item.name, - printer_name: item.name, - is_default: item.name === defaultPrinter ? 1 : 0, - creator_id: ctx.user?.id || '', - creator_name: ctx.user?.name || '', - create_at: new Date(), - update_at: new Date(), + const { defaultPrinter, express, print_station_id } = data; + if (!defaultPrinter || !Array.isArray(express) || !print_station_id) return this.fail('参数错误', { code: 1001 }); + + const item = await ctx.model.PrintStations.findOne({ + where: { + id: print_station_id, deleted: 0, - }); + }, + }); + if (!item) return this.fail('打印台不存在', { code: 1002 }); + + const expressBindPrinter = express.map(expressItem => { + const sourceItem = expressItem && typeof expressItem === 'object' ? expressItem : {}; + return { + printer_name: sourceItem.printer_name || sourceItem.name || defaultPrinter, + express_code: sourceItem.express_code || sourceItem.express_id, + }; + }); + + const rawSubjectConfig = item.subject_config && typeof item.subject_config === 'object' && !Array.isArray(item.subject_config) + ? item.subject_config + : {}; + const mergedSubjectConfig = { + ...rawSubjectConfig, + express_bind_printer: expressBindPrinter, + }; + + try { + item.subject_config = ctx.model.PrintStations.normalizeSubjectConfig(mergedSubjectConfig); + } catch (error) { + return this.fail(error.message, { code: 1001 }); } + + item.default_printer_name = defaultPrinter; + item.update_at = new Date(); + await item.save(); + return this.success('success', { data: null, code: 0 }); } } diff --git a/database/migrations/20260514110000-add-subject-config-to-wms_print_stations.js b/database/migrations/20260514110000-add-subject-config-to-wms_print_stations.js new file mode 100644 index 0000000..58ca8d1 --- /dev/null +++ b/database/migrations/20260514110000-add-subject-config-to-wms_print_stations.js @@ -0,0 +1,37 @@ +'use strict'; + +module.exports = { + /** + * 为打印台表新增主体配置字段。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口 + * @param {import('sequelize')} Sequelize Sequelize 实例 + * @returns {Promise} 无返回值 + */ + async up(queryInterface, Sequelize) { + const tableDefinition = await queryInterface.describeTable('wms_print_stations'); + if (tableDefinition.subject_config) { + return; + } + + await queryInterface.addColumn('wms_print_stations', 'subject_config', { + type: Sequelize.JSON, + allowNull: true, + comment: '打印台主体配置', + }); + }, + + /** + * 回滚删除打印台表主体配置字段。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口 + * @param {import('sequelize')} Sequelize Sequelize 实例 + * @returns {Promise} 无返回值 + */ + async down(queryInterface) { + const tableDefinition = await queryInterface.describeTable('wms_print_stations'); + if (!tableDefinition.subject_config) { + return; + } + + await queryInterface.removeColumn('wms_print_stations', 'subject_config'); + }, +}; diff --git a/database/migrations/20260514123000-drop-wms_print_station_express.js b/database/migrations/20260514123000-drop-wms_print_station_express.js new file mode 100644 index 0000000..48b61ba --- /dev/null +++ b/database/migrations/20260514123000-drop-wms_print_station_express.js @@ -0,0 +1,85 @@ +'use strict'; + +module.exports = { + /** + * 删除已弃用的打印台快递关联表。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口 + * @param {import('sequelize')} Sequelize Sequelize 实例 + * @returns {Promise} 无返回值 + */ + async up(queryInterface, Sequelize) { + await queryInterface.sequelize.query( + 'DROP TABLE IF EXISTS `wms_print_station_express`' + ); + }, + + /** + * 回滚重建打印台快递关联表(核心字段与唯一索引)。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口 + * @param {import('sequelize')} Sequelize Sequelize 实例 + * @returns {Promise} 无返回值 + */ + async down(queryInterface, Sequelize) { + await queryInterface.createTable('wms_print_station_express', { + id: { + type: Sequelize.INTEGER.UNSIGNED, + autoIncrement: true, + primaryKey: true, + allowNull: false, + comment: '主键ID', + }, + print_station_id: { + type: Sequelize.STRING(255), + allowNull: false, + comment: '打印台ID', + }, + express_id: { + type: Sequelize.STRING(255), + allowNull: false, + comment: '快递公司ID', + }, + express_name: { + type: Sequelize.STRING(255), + allowNull: true, + comment: '快递公司名称', + }, + printer_name: { + type: Sequelize.STRING(255), + allowNull: true, + comment: '打印机名称', + }, + creator_id: { + type: Sequelize.BIGINT.UNSIGNED, + allowNull: true, + comment: '创建人ID', + }, + creator_name: { + type: Sequelize.STRING(255), + allowNull: true, + comment: '创建人名称', + }, + create_at: { + type: Sequelize.DATE, + allowNull: true, + comment: '创建时间', + }, + update_at: { + type: Sequelize.DATE, + allowNull: true, + comment: '更新时间', + }, + deleted: { + type: Sequelize.TINYINT, + allowNull: false, + defaultValue: 0, + comment: '删除标记:0未删除,1已删除', + }, + }); + + await queryInterface.addIndex('wms_print_station_express', { + fields: [ 'print_station_id', 'express_id', 'deleted' ], + unique: true, + name: 'uk_print_station_express', + }); + }, +}; diff --git a/docs/express-model-table-map.md b/docs/express-model-table-map.md index 72f403b..fa9a110 100644 --- a/docs/express-model-table-map.md +++ b/docs/express-model-table-map.md @@ -9,16 +9,14 @@ | 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 | 已补齐 | -| app/model/print_station_express.js | PrintStationExpress | wms_print_station_express | 已存在 | ## 关键说明 - 本次仅整理模型与真实数据表对齐,不改动业务逻辑与接口行为。 -- 通过 `script/db-query.ps1` 实查,数据库中包含 6 张 express 相关表,上述模型已全部覆盖。 +- 通过 `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_print_station_express` 与 `wms_express_print_record` 做关联查询封装,减少 systemMethods 层的散落操作。 diff --git a/methods/system.json b/methods/system.json index 4dda07d..51a08b2 100644 --- a/methods/system.json +++ b/methods/system.json @@ -7270,7 +7270,7 @@ }, { "method": "print.getList", - "description": "print.getList 接口", + "description": "查询当前仓库下的打印台列表,支持分页与 where 条件筛选(支持字段:id、name、computer_id、custom_barcode)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -7287,29 +7287,113 @@ "type": "number", "required": false, "source": "body", - "description": "page 参数" + "description": "页码,默认 1" }, { "name": "pageSize", "type": "number", "required": false, "source": "body", - "description": "pageSize 参数" + "description": "每页数量,默认 20" }, { "name": "where", "type": "object", "required": false, "source": "body", - "description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;当前支持 id、name、computer_id、custom_barcode。示例:where.name={operator:like,value:热敏}; where.computer_id={operator:eq,value:PC-01}。" + "description": "筛选条件对象;支持字段:id(等值)、name、computer_id、custom_barcode;推荐使用 { operator, value, type } 标准结构" } ], - "response": [], - "errors": [] + "response": [ + { + "name": "data", + "type": "object", + "required": true, + "description": "返回数据对象,包含 list 与 pagination", + "children": [ + { + "name": "list", + "type": "array", + "required": true, + "description": "打印台列表", + "children": [ + { + "name": "id", + "type": "number", + "description": "打印台 ID" + }, + { + "name": "name", + "type": "string", + "description": "打印台名称" + }, + { + "name": "computer_id", + "type": "number", + "description": "关联打印电脑 ID" + }, + { + "name": "custom_barcode", + "type": "string", + "description": "自定义条码" + }, + { + "name": "default_printer_name", + "type": "string", + "description": "默认打印机名称" + }, + { + "name": "subject_config", + "type": "object", + "description": "打印台的 subject_config 配置" + }, + { + "name": "is_online", + "type": "number", + "description": "打印电脑在线状态,1=在线,0=离线" + }, + { + "name": "components", + "type": "array", + "description": "电脑组件在线信息,数组项包含 name/is_online", + "children": [ + { + "name": "name", + "type": "string", + "description": "组件名称" + }, + { + "name": "is_online", + "type": "number", + "description": "组件是否在线,1/0" + } + ] + } + ] + }, + { + "name": "pagination", + "type": "object", + "required": true, + "description": "分页信息,包含 page、pageSize、total、totalPages、hasPrevious、hasNext" + } + ] + } + ], + "errors": [ + { + "code": "400", + "description": "参数格式错误或 where 中包含非法字段" + }, + { + "code": "500", + "description": "查询失败或内部错误" + } + ] }, { "method": "print.getItem", - "description": "print.getItem 接口", + "description": "查询单个打印台详情,返回打印台对象(raw 行记录,含 subject_config)", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -7326,15 +7410,38 @@ "type": "number", "required": true, "source": "body", - "description": "id 参数" + "description": "打印台 ID,必填" } ], - "response": [], - "errors": [] + "response": [ + { + "name": "data", + "type": "object", + "required": true, + "description": "打印台原始记录(PrintStation raw),字段示例", + "children": [ + { "name": "id", "type": "number", "description": "打印台 ID" }, + { "name": "name", "type": "string", "description": "打印台名称" }, + { "name": "computer_id", "type": "number", "description": "关联打印电脑 ID" }, + { "name": "custom_barcode", "type": "string", "description": "自定义条码" }, + { "name": "default_printer_name", "type": "string", "description": "默认打印机名称" }, + { "name": "subject_config", "type": "object", "description": "打印台 subject_config 配置(见下文)" }, + { "name": "create_at", "type": "string", "description": "创建时间" }, + { "name": "update_at", "type": "string", "description": "更新时间" }, + { "name": "deleted", "type": "number", "description": "软删除标识,1=已删除" }, + { "name": "warehouse_id", "type": "number", "description": "所属仓库 ID" } + ] + } + ], + "errors": [ + { "code": "400", "description": "参数错误:缺少 id 或 id 格式不正确" }, + { "code": "404", "description": "打印台不存在" }, + { "code": "500", "description": "内部错误" } + ] }, { "method": "print.add", - "description": "print.add 接口", + "description": "新增打印台:关联打印电脑并可保存 subject_config(会由模型 normalizeSubjectConfig 校验)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -7346,37 +7453,36 @@ } ], "params": [ + { "name": "computer_id", "type": "number", "required": true, "source": "body", "description": "关联的打印电脑 ID(必填)" }, + { "name": "name", "type": "string", "required": true, "source": "body", "description": "打印台名称(必填)" }, + { "name": "custom_barcode", "type": "string", "required": false, "source": "body", "description": "自定义条码" }, + { "name": "default_printer_name", "type": "string", "required": false, "source": "body", "description": "默认打印机名称" }, { - "name": "computer_id", - "type": "number", - "required": true, - "source": "body", - "description": "computer_id 参数" - }, - { - "name": "name", - "type": "string", - "required": true, - "source": "body", - "description": "name 参数" - }, - { - "name": "custom_barcode", - "type": "string", + "name": "subject_config", + "type": "object", "required": false, "source": "body", - "description": "custom_barcode 参数" - }, - { - "name": "default_printer_name", - "type": "string", - "required": false, - "source": "body", - "description": "default_printer_name 参数" + "description": "打印台的主题/业务配置(可选,若存在将调用模型 normalizeSubjectConfig 进行校验)", + "children": [ + { + "name": "express_bind_printer", + "type": "array", + "description": "快递与打印机绑定数组,数组项仅包含 { express_code, printer_name }", + "children": [ + { "name": "express_code", "type": "string", "required": true, "description": "快递编码,必填" }, + { "name": "printer_name", "type": "string", "required": true, "description": "打印机名称,必填" } + ] + } + ] } ], - "response": [], - "errors": [] + "response": [ + { "name": "data", "type": "object", "required": true, "description": "新建的打印台对象(raw)" } + ], + "errors": [ + { "code": "400", "description": "参数错误:缺少必填字段(computer_id/name)或 subject_config 格式不合法" }, + { "code": "500", "description": "创建失败或内部错误" } + ] }, { "method": "print.hasName", @@ -7412,7 +7518,7 @@ }, { "method": "print.updateItem", - "description": "print.updateItem 接口", + "description": "更新打印台信息:支持更新 name、computer_id、custom_barcode、default_printer_name 以及 subject_config(会走 normalizeSubjectConfig)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -7424,41 +7530,42 @@ } ], "params": [ + { "name": "id", "type": "number", "required": true, "source": "body", "description": "打印台 ID(必填)" }, + { "name": "computer_id", "type": "number", "required": false, "source": "body", "description": "要更新的打印电脑 ID" }, + { "name": "custom_barcode", "type": "string", "required": false, "source": "body", "description": "自定义条码" }, + { "name": "name", "type": "string", "required": false, "source": "body", "description": "打印台名称" }, + { "name": "default_printer_name", "type": "string", "required": false, "source": "body", "description": "默认打印机名称" }, { - "name": "id", - "type": "number", - "required": true, - "source": "body", - "description": "id 参数" - }, - { - "name": "computer_id", - "type": "number", + "name": "subject_config", + "type": "object", "required": false, "source": "body", - "description": "computer_id 参数" - }, - { - "name": "custom_barcode", - "type": "string", - "required": false, - "source": "body", - "description": "custom_barcode 参数" - }, - { - "name": "name", - "type": "string", - "required": false, - "source": "body", - "description": "name 参数" + "description": "subject_config(可选),传入将替换/规范化配置", + "children": [ + { + "name": "express_bind_printer", + "type": "array", + "description": "快递-打印机绑定数组,数组项仅包含 { express_code, printer_name }", + "children": [ + { "name": "express_code", "type": "string", "required": true, "description": "快递编码,必填" }, + { "name": "printer_name", "type": "string", "required": true, "description": "打印机名称,必填" } + ] + } + ] } ], - "response": [], - "errors": [] + "response": [ + { "name": "data", "type": "object", "required": false, "description": "更新结果,通常返回 null" } + ], + "errors": [ + { "code": "400", "description": "参数错误(缺少 id 或 subject_config 格式不合法)" }, + { "code": "404", "description": "打印台不存在" }, + { "code": "500", "description": "更新失败或内部错误" } + ] }, { "method": "print.del", - "description": "print.del 接口", + "description": "批量删除(软删除)打印台:将指定 ids 的记录标记为 deleted=1。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -7473,17 +7580,22 @@ { "name": "ids", "type": "array", - "required": false, + "required": true, "source": "body", - "description": "ids 参数" + "description": "要删除的打印台 ID 数组,必须为非空数组(示例: [1,2,3])" } ], - "response": [], - "errors": [] + "response": [ + { "name": "data", "type": "object", "required": false, "description": "返回空数据结构,表示操作成功" } + ], + "errors": [ + { "code": "400", "description": "参数错误:ids 必须为非空数组" }, + { "code": "500", "description": "删除失败或内部错误" } + ] }, { "method": "print.getComputer", - "description": "print.getComputer 接口", + "description": "查询当前仓库下状态为 1 的打印电脑列表(raw 列表)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -7495,12 +7607,28 @@ } ], "params": [], - "response": [], - "errors": [] + "response": [ + { + "name": "data", + "type": "array", + "required": true, + "description": "打印电脑数组,每项为打印电脑的原始记录", + "children": [ + { "name": "id", "type": "number", "description": "打印电脑 ID" }, + { "name": "name", "type": "string", "description": "打印电脑名称或标识" }, + { "name": "status", "type": "number", "description": "状态,1=启用" }, + { "name": "warehouse_id", "type": "number", "description": "所属仓库 ID" } + ] + } + ], + "errors": [ + { "code": "400", "description": "未识别到当前仓库上下文" }, + { "code": "500", "description": "查询失败或内部错误" } + ] }, { "method": "print.getComputerPrinter", - "description": "print.getComputerPrinter 接口", + "description": "获取指定打印电脑的打印机列表(从 redis: printer:{id}:printerList 读取并返回 data 数组,通常为打印机名称数组或对象数组)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -7517,15 +7645,20 @@ "type": "number", "required": true, "source": "body", - "description": "id 参数" + "description": "打印电脑 ID,必填" } ], - "response": [], - "errors": [] + "response": [ + { "name": "data", "type": "array", "required": true, "description": "打印机数组,通常为字符串名称数组或打印机对象数组(取决于 redis 存储格式)" } + ], + "errors": [ + { "code": "400", "description": "参数错误:缺少 id" }, + { "code": "500", "description": "读取 Redis 或解析数据失败" } + ] }, { "method": "print.savePrinters", - "description": "print.savePrinters 接口", + "description": "保存 default_printer_name 与 subject_config.express_bind_printer。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -7537,30 +7670,30 @@ } ], "params": [ - { - "name": "defaultPrinter", - "type": "string", - "required": true, - "source": "body", - "description": "defaultPrinter 参数" - }, + { "name": "defaultPrinter", "type": "string", "required": true, "source": "body", "description": "默认打印机名称(必填),会写入打印台的 `default_printer_name` 字段" }, { "name": "express", "type": "array", - "required": false, + "required": true, "source": "body", - "description": "express 参数" + "description": "快递与打印机绑定数组(必填)。每项应包含首选字段 `express_code`(string)和 `printer_name`(string)。为兼容历史字段,也接受 `express_id`(可映射为 `express_code`)和 `name`(可映射为 `printer_name`)。接口实现会将结果序列化后写入打印台的 `subject_config.express_bind_printer`。", + "children": [ + { "name": "express_code", "type": "string", "required": false, "description": "首选:快递编码(string),实现中优先使用该字段" }, + { "name": "printer_name", "type": "string", "required": false, "description": "首选:打印机名称(string),实现中优先使用该字段" }, + { "name": "express_id", "type": "number|string", "required": false, "description": "兼容字段:历史的 express_id,可映射为 express_code 使用" }, + { "name": "name", "type": "string", "required": false, "description": "兼容字段:历史的 name,可映射为 printer_name 使用" } + ] }, - { - "name": "print_station_id", - "type": "number", - "required": false, - "source": "body", - "description": "print_station_id 参数" - } + { "name": "print_station_id", "type": "number", "required": true, "source": "body", "description": "目标打印台 ID(必填)。接口会根据此 ID 更新对应打印台记录的 default_printer_name 与 subject_config.express_bind_printer" } ], - "response": [], - "errors": [] + "response": [ + { "name": "data", "type": "object", "required": false, "description": "成功不返回业务数据,语义为成功(实现中返回 { data: null, code: 0 })" } + ], + "errors": [ + { "code": "400", "description": "参数错误:defaultPrinter/express/print_station_id 格式或缺失" }, + { "code": "404", "description": "打印台不存在:未找到对应 print_station_id 的打印台记录" }, + { "code": "500", "description": "保存失败或内部错误" } + ] } ] }, diff --git a/test/app/model/print_stations.test.js b/test/app/model/print_stations.test.js new file mode 100644 index 0000000..2e7215d --- /dev/null +++ b/test/app/model/print_stations.test.js @@ -0,0 +1,101 @@ +'use strict'; + +const assert = require('node:assert/strict'); + +/** + * 构造 print_stations 模型测试所需的最小 Sequelize 类型集合。 + * @returns {Object} Sequelize 类型集合。 + */ +function createSequelizeTypes() { + const makeType = sql => ({ + toSql() { + return sql; + }, + }); + + const integerType = makeType('INTEGER'); + integerType.UNSIGNED = makeType('INTEGER UNSIGNED'); + + return { + INTEGER: integerType, + BIGINT: { + UNSIGNED: makeType('BIGINT UNSIGNED'), + }, + STRING: length => makeType(`VARCHAR(${length})`), + DATE: makeType('DATETIME'), + TINYINT: makeType('TINYINT'), + JSON: makeType('JSON'), + }; +} + +/** + * 构造加载 print_stations 模型所需的最小应用对象。 + * @returns {Object} 应用对象。 + */ +function createApp() { + return { + Sequelize: createSequelizeTypes(), + model: { + define(name, attributes, options) { + return { + name, + rawAttributes: attributes, + options, + }; + }, + }, + }; +} + +describe('test/app/model/print_stations.test.js', () => { + it('should return empty express_bind_printer by default', () => { + const PrintStations = require('../../../app/model/print_stations')(createApp()); + + const normalized = PrintStations.normalizeSubjectConfig(null); + + assert.deepEqual(PrintStations.DEFAULT_SUBJECT_CONFIG, { + express_bind_printer: [], + }); + assert.deepEqual(normalized, { + express_bind_printer: [], + }); + }); + + it('should normalize express_bind_printer list', () => { + const PrintStations = require('../../../app/model/print_stations')(createApp()); + + const normalized = PrintStations.normalizeSubjectConfig({ + express_bind_printer: [ + { + printer_name: ' 打印机A ', + express_code: ' STO ', + }, + ], + }); + + assert.deepEqual(normalized.express_bind_printer, [ + { + printer_name: '打印机A', + express_code: 'STO', + }, + ]); + }); + + it('should throw with field path when express_bind_printer item is invalid', () => { + const PrintStations = require('../../../app/model/print_stations')(createApp()); + + assert.throws( + () => { + PrintStations.normalizeSubjectConfig({ + express_bind_printer: [ + { + printer_name: '', + express_code: 'STO', + }, + ], + }); + }, + /subject_config\.express_bind_printer\[0\]\.printer_name 不能为空/ + ); + }); +}); diff --git a/test/app/service/systemMethods/print.savePrinters.test.js b/test/app/service/systemMethods/print.savePrinters.test.js new file mode 100644 index 0000000..df9c9b2 --- /dev/null +++ b/test/app/service/systemMethods/print.savePrinters.test.js @@ -0,0 +1,193 @@ +'use strict'; + +const assert = require('node:assert/strict'); +const PrintService = require('../../../../app/service/systemMethods/print'); + +/** + * 构造 savePrinters 测试上下文。 + * @param {Object} [options] 测试选项。 + * @param {Object|null} [options.stationItem] 打印台模型实例。 + * @returns {{ctx: Object, calls: Object, stationItem: Object|null}} 测试上下文与调用记录。 + */ +function createContext(options = {}) { + const calls = { + findOneArgs: [], + normalizeSubjectConfigArgs: [], + saveCount: 0, + }; + + const stationItem = options.stationItem || { + id: 1, + deleted: 0, + default_printer_name: '旧默认打印机', + subject_config: { + keep_field: 'keep-value', + express_bind_printer: [ + { + printer_name: '旧打印机', + express_code: 'OLD', + }, + ], + }, + async save() { + calls.saveCount += 1; + }, + }; + + const ctx = { + app: { + config: { + jwt: {}, + }, + Sequelize: {}, + }, + user: { + store_id: 100000, + }, + model: { + PrintStations: { + async findOne(payload) { + calls.findOneArgs.push(payload); + return options.stationItem === null ? null : stationItem; + }, + normalizeSubjectConfig(config) { + calls.normalizeSubjectConfigArgs.push(config); + if (!config || typeof config !== 'object' || Array.isArray(config)) { + throw new Error('subject_config 必须是对象'); + } + if (!Array.isArray(config.express_bind_printer)) { + throw new Error('subject_config.express_bind_printer 必须是数组'); + } + const normalizedList = config.express_bind_printer.map((item, index) => { + const printerName = String(item.printer_name === undefined || item.printer_name === null ? '' : item.printer_name).trim(); + const expressCode = String(item.express_code === undefined || item.express_code === null ? '' : item.express_code).trim(); + if (!printerName) { + throw new Error(`subject_config.express_bind_printer[${index}].printer_name 不能为空`); + } + if (!expressCode) { + throw new Error(`subject_config.express_bind_printer[${index}].express_code 不能为空`); + } + return { + printer_name: printerName, + express_code: expressCode, + }; + }); + + return { + ...config, + express_bind_printer: normalizedList, + }; + }, + }, + }, + }; + + return { ctx, calls, stationItem }; +} + +describe('test/app/service/systemMethods/print.savePrinters.test.js', () => { + it('正常保存时应写入 print_stations.subject_config.express_bind_printer', async () => { + const { ctx, calls, stationItem } = createContext(); + const service = new PrintService(ctx); + + const result = await service.savePrinters({ + defaultPrinter: '默认打印机A', + print_station_id: 11, + express: [ + { + express_code: 'STO', + printer_name: '申通打印机', + }, + ], + }); + + assert.equal(result.flag, 'success'); + assert.equal(result.code, 0); + assert.equal(calls.saveCount, 1); + assert.equal(stationItem.default_printer_name, '默认打印机A'); + assert.equal(stationItem.subject_config.keep_field, 'keep-value'); + assert.deepEqual(stationItem.subject_config.express_bind_printer, [ + { + printer_name: '申通打印机', + express_code: 'STO', + }, + ]); + assert.equal(calls.findOneArgs.length, 1); + assert.deepEqual(calls.findOneArgs[0], { + where: { + id: 11, + deleted: 0, + }, + }); + }); + + it('express 使用 express_id 与 name 时应兼容映射为 express_code 与 printer_name', async () => { + const { ctx, stationItem } = createContext(); + const service = new PrintService(ctx); + + const result = await service.savePrinters({ + defaultPrinter: '默认打印机B', + print_station_id: 12, + express: [ + { + express_id: 'YTO', + name: '圆通打印机', + }, + ], + }); + + assert.equal(result.flag, 'success'); + assert.equal(result.code, 0); + assert.deepEqual(stationItem.subject_config.express_bind_printer, [ + { + printer_name: '圆通打印机', + express_code: 'YTO', + }, + ]); + }); + + it('print_station_id 不存在时应返回失败', async () => { + const { ctx, calls } = createContext({ stationItem: null }); + const service = new PrintService(ctx); + + const result = await service.savePrinters({ + defaultPrinter: '默认打印机C', + print_station_id: 999999, + express: [ + { + express_code: 'ZTO', + printer_name: '中通打印机', + }, + ], + }); + + assert.equal(result.flag, 'failure'); + assert.equal(result.code, 1002); + assert.match(result.message, /打印台不存在/); + assert.equal(calls.saveCount, 0); + }); + + it('缺少 defaultPrinter 或 express 时应返回参数错误', async () => { + const { ctx: ctxA } = createContext(); + const serviceA = new PrintService(ctxA); + const resultA = await serviceA.savePrinters({ + print_station_id: 13, + express: [], + }); + + assert.equal(resultA.flag, 'failure'); + assert.equal(resultA.code, 1001); + assert.match(resultA.message, /参数错误/); + + const { ctx: ctxB } = createContext(); + const serviceB = new PrintService(ctxB); + const resultB = await serviceB.savePrinters({ + defaultPrinter: '默认打印机D', + print_station_id: 14, + }); + + assert.equal(resultB.flag, 'failure'); + assert.equal(resultB.code, 1001); + assert.match(resultB.message, /参数错误/); + }); +}); diff --git a/test/app/service/systemMethods/print.send.test.js b/test/app/service/systemMethods/print.send.test.js index bc1d673..fb943ce 100644 --- a/test/app/service/systemMethods/print.send.test.js +++ b/test/app/service/systemMethods/print.send.test.js @@ -57,6 +57,27 @@ function createContext() { } describe('test/app/service/systemMethods/print.send.test.js', () => { + it('type=express 不传 printer 时应发送成功并调用 sendToComputer', async () => { + const { ctx, calls } = createContext(); + const service = new PrintService(ctx); + + const result = await service.send({ + computerId: 'PC-00', + type: 'express', + data: { + order_no: 'SO10000', + }, + timestamp: '1709999999', + count: 1, + }); + + assert.equal(result.flag, 'success'); + assert.equal(result.code, 200); + assert.equal(calls.sendToComputerPayloads.length, 1); + assert.equal(calls.printRecordUpdatePayloads.length, 1); + assert.equal(calls.printRecordUpdatePayloads[0].status, 'sent'); + }); + it('type=express 不传 template 时应发送成功并调用 sendToComputer', async () => { const { ctx, calls } = createContext(); const service = new PrintService(ctx); @@ -79,6 +100,31 @@ describe('test/app/service/systemMethods/print.send.test.js', () => { assert.equal(calls.printRecordUpdatePayloads[0].status, 'sent'); }); + it('type=customize 不传 printer 时应返回失败且提示 printer', async () => { + const { ctx, calls } = createContext(); + const service = new PrintService(ctx); + + const result = await service.send({ + computerId: 'PC-03', + type: 'customize', + template: { + page_width: 100, + page_height: 60, + template_content: [], + }, + data: { + order_no: 'SO10003', + }, + timestamp: '1710000002', + count: 1, + }); + + assert.equal(result.flag, 'failure'); + assert.equal(result.code, 400); + assert.match(result.message, /printer/); + assert.equal(calls.sendToComputerPayloads.length, 0); + }); + it('type=customize 不传 template 时应返回失败且提示 template', async () => { const { ctx, calls } = createContext(); const service = new PrintService(ctx);