打印台管理变更

This commit is contained in:
liufumingren 2026-05-14 15:57:51 +08:00
parent e980512db7
commit 736ad34351
10 changed files with 857 additions and 214 deletions

View File

@ -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;
};

View File

@ -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<Object>} 规范化后的快递绑定打印机配置。
*/
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;
};

View File

@ -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<Object>} 返回新增结果。
*/
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<Object>} 返回更新结果。
*/
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<Object>} data.express 快递绑定数组,必填。
* @param {number|string} data.print_station_id 打印台 ID,必填。
* @returns {Promise<Object>} 保存结果。
*/
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 });
}
}

View File

@ -0,0 +1,37 @@
'use strict';
module.exports = {
/**
* 为打印台表新增主体配置字段。
* @param {import('sequelize').QueryInterface} queryInterface 查询接口
* @param {import('sequelize')} Sequelize Sequelize 实例
* @returns {Promise<void>} 无返回值
*/
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<void>} 无返回值
*/
async down(queryInterface) {
const tableDefinition = await queryInterface.describeTable('wms_print_stations');
if (!tableDefinition.subject_config) {
return;
}
await queryInterface.removeColumn('wms_print_stations', 'subject_config');
},
};

View File

@ -0,0 +1,85 @@
'use strict';
module.exports = {
/**
* 删除已弃用的打印台快递关联表。
* @param {import('sequelize').QueryInterface} queryInterface 查询接口
* @param {import('sequelize')} Sequelize Sequelize 实例
* @returns {Promise<void>} 无返回值
*/
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<void>} 无返回值
*/
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',
});
},
};

View File

@ -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 层的散落操作。

View File

@ -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": "保存失败或内部错误" }
]
}
]
},

View File

@ -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 不能为空/
);
});
});

View File

@ -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, /参数错误/);
});
});

View File

@ -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);