升鲜宝通用打印控件
数据库表结构及数据字典
版本：V1.0 数据库：MySQL 字符集：utf8mb4 生成日期：2020-06-30
适用范围：Java Spring Boot + Vue3 + Element Plus + hiprint 的升鲜宝通用打印能力中心。
1. 设计说明
本数据字典基于升鲜宝 hiprint 通用打印控件设计，覆盖打印业务、打印字段、打印模板、默认模板、模板版本、模板字段解析、打印日志、打印任务、静默打印客户端与回调记录。
• 默认模板唯一性：使用 sys_print_template_default 做强约束，不仅依赖模板表 is_default 冗余字段。
• 软删除唯一索引：所有需要复用编码的表统一使用 delete_token，未删除为 0，删除后写入 id。
• 字段权限：sys_print_field 保存 permission_code、sensitive_level、mask_rule，模板保存和打印阶段均需后端校验。
• 多明细表：sys_print_detail_group 定义 details、fees、packages 等明细分组；hiprint 表格 options.field 使用 detail_code。
• 日志明细：sys_print_log 记录主日志，sys_print_log_item 记录每张业务单据的结果。
• 模板版本回滚：sys_print_template_version 保存每次快照，回滚生成新版本，不覆盖历史版本。
• 静默打印协议：通过 sys_print_client、sys_print_client_printer、sys_print_task、sys_print_callback 支撑客户端、打印机、任务和回调。
2. 升鲜宝通用字段约定
| 字段 | 类型 | 说明 |
|---|---|---|
| id | BIGINT | 主键ID，自增 |
| tenant_id | BIGINT NOT NULL DEFAULT 0 | 租户ID；0 表示平台默认 |
| org_id | BIGINT NOT NULL DEFAULT 0 | 组织ID；0 表示全部组织，仅作用域表使用 |
| shop_id | BIGINT NOT NULL DEFAULT 0 | 门店ID；0 表示全部门店，仅作用域表使用 |
| remark | VARCHAR(500) | 备注 |
| create_by / create_name / create_time | BIGINT / VARCHAR(50) / DATETIME | 创建人、创建人名称、创建时间 |
| update_by / update_name / update_time | BIGINT / VARCHAR(50) / DATETIME | 修改人、修改人名称、修改时间 |
| deleted | TINYINT NOT NULL DEFAULT 0 | 逻辑删除：0否，1是 |
| delete_token | BIGINT NOT NULL DEFAULT 0 | 唯一索引软删除标记；未删除 0，删除后写入 id |
3. 表清单
| 序号 | 表名 | 中文名 | 用途 |
|---|---|---|---|
| 1 | sys_print_business | 打印业务定义表 | 定义哪些业务单据支持通用打印，例如采购订单、销售订单、入库单、出库单、客户对账单、商品标签等。 |
| 2 | sys_print_detail_group | 打印明细分组定义表 | 定义一个业务下可打印的多个明细表，例如商品明细 details、费用明细 fees、包装明细 packages。 |
| 3 | sys_print_field | 打印字段定义表 | 定义某个业务类型可拖拽、可打印的字段，并提供字段权限、脱敏、格式化和多明细归属信息。 |
| 4 | sys_print_template | 打印模板表 | 保存 hiprint 模板 JSON、纸张信息、当前版本、模板 Hash 和模板启用状态。 |
| 5 | sys_print_template_default | 打印默认模板关系表 | 保证同一租户、组织、门店、业务编码下只有一个默认模板，并支持门店模板覆盖组织/租户模板。 |
| 6 | sys_print_template_version | 打印模板版本表 | 保存每次创建、保存、回滚后的模板快照。回滚时生成新版本，不覆盖历史版本。 |
| 7 | sys_print_template_field | 打印模板字段使用表 | 记录模板 JSON 解析出来的字段清单，用于保存校验、字段权限复核、影响范围分析。 |
| 8 | sys_print_log | 打印日志主表 | 记录一次预览、浏览器打印或静默打印的主日志，保留请求、客户端、模板和总体状态。 |
| 9 | sys_print_log_item | 打印日志明细表 | 记录一次打印中每一张业务单据的打印结果，便于追踪单据打印历史和批量部分失败。 |
| 10 | sys_print_task | 打印任务表 | 用于批量打印、静默打印、异步打印的任务主表，支持客户端状态回传和幂等控制。 |
| 11 | sys_print_task_item | 打印任务明细表 | 记录打印任务中每个业务单据的任务状态，支持批量任务部分成功、失败重试。 |
| 12 | sys_print_client | 静默打印客户端表 | 登记本地打印客户端或中转打印客户端，用于在线检测、版本控制、打印机列表同步和安全认证。 |
| 13 | sys_print_client_printer | 静默打印客户端打印机表 | 保存客户端同步的打印机列表，支持指定打印机、默认打印机和状态展示。 |
| 14 | sys_print_callback | 打印回调记录表 | 记录静默打印结果回调和业务回调，支持失败重试、响应追踪和问题排查。 |
4. 数据表字段字典
4.1 sys_print_business（打印业务定义表）
用途：定义哪些业务单据支持通用打印，例如采购订单、销售订单、入库单、出库单、客户对账单、商品标签等。
| 字段名 | 数据类型 | 可空 | 默认值 | 键 | 说明 |
|---|---|---|---|---|---|
| id | BIGINT AUTO_INCREMENT | 否 | PK | 主键ID | |
| tenant_id | BIGINT | 否 | 0 | 租户ID，0表示平台默认 | |
| business_code | VARCHAR(100) | 否 | UK字段 | 业务编码，如 PURCHASE_ORDER | |
| business_name | VARCHAR(100) | 否 | 业务名称，如采购订单 | ||
| module_code | VARCHAR(100) | 是 | 模块编码，如 pur、sale、wms、fin、pms | ||
| business_category | VARCHAR(50) | 是 | 业务分类：ORDER单据、BILL对账、LABEL标签等 | ||
| main_table | VARCHAR(100) | 是 | 主业务表名 | ||
| main_key_field | VARCHAR(100) | 否 | 'id' | 主业务表主键字段 | |
| data_api | VARCHAR(255) | 是 | 自定义打印取数接口 | ||
| provider_bean | VARCHAR(150) | 是 | 后端 PrintDataProvider Bean 名称 | ||
| enabled | TINYINT | 否 | 1 | 是否启用：0否，1是 | |
| sort_no | INT | 否 | 0 | 排序号 | |
| remark | VARCHAR(500) | 是 | 备注 | ||
| create_by | BIGINT | 是 | 创建人ID | ||
| create_name | VARCHAR(50) | 是 | 创建人名称 | ||
| create_time | DATETIME | 否 | CURRENT_TIMESTAMP | 创建时间 | |
| update_by | BIGINT | 是 | 修改人ID | ||
| update_name | VARCHAR(50) | 是 | 修改人名称 | ||
| update_time | DATETIME | 是 | NULL ON UPDATE CURRENT_TIMESTAMP | 修改时间 | |
| deleted | TINYINT | 否 | 0 | 逻辑删除：0否，1是 | |
| delete_token | BIGINT | 否 | 0 | 软删除唯一标记：0未删除，删除后写入id |
| 类型 | 名称 | 字段/表达式 |
|---|---|---|
| UNIQUE | uk_business_code_live | tenant_id, business_code, delete_token |
| INDEX | idx_module_code | module_code |
| INDEX | idx_enabled | enabled, deleted |
• delete_token=0 表示未删除；删除后写入 id，确保业务编码可复用。
4.2 sys_print_detail_group（打印明细分组定义表）
用途：定义一个业务下可打印的多个明细表，例如商品明细 details、费用明细 fees、包装明细 packages。
| 字段名 | 数据类型 | 可空 | 默认值 | 键 | 说明 |
|---|---|---|---|---|---|
| id | BIGINT AUTO_INCREMENT | 否 | PK | 主键ID | |
| tenant_id | BIGINT | 否 | 0 | 租户ID，0表示平台默认 | |
| business_code | VARCHAR(100) | 否 | UK字段 | 业务编码 | |
| detail_code | VARCHAR(100) | 否 | '' | UK字段 | 明细编码，同时作为 hiprint 表格控件 options.field，如 details |
| detail_name | VARCHAR(100) | 否 | 明细名称，如商品明细 | ||
| table_field | VARCHAR(100) | 否 | '' | 打印数据中的数组字段名，默认等于 detail_code | |
| source_table | VARCHAR(100) | 是 | 明细来源表 | ||
| parent_key_field | VARCHAR(100) | 否 | 'id' | 主表关联字段 | |
| detail_key_field | VARCHAR(100) | 否 | 'id' | 明细主键字段 | |
| data_api | VARCHAR(255) | 是 | 单独明细取数接口，可为空 | ||
| enabled | TINYINT | 否 | 1 | 是否启用：0否，1是 | |
| sort_no | INT | 否 | 0 | 排序号 | |
| remark | VARCHAR(500) | 是 | 备注 | ||
| create_by | BIGINT | 是 | 创建人ID | ||
| create_name | VARCHAR(50) | 是 | 创建人名称 | ||
| create_time | DATETIME | 否 | CURRENT_TIMESTAMP | 创建时间 | |
| update_by | BIGINT | 是 | 修改人ID | ||
| update_name | VARCHAR(50) | 是 | 修改人名称 | ||
| update_time | DATETIME | 是 | NULL ON UPDATE CURRENT_TIMESTAMP | 修改时间 | |
| deleted | TINYINT | 否 | 0 | 逻辑删除：0否，1是 | |
| delete_token | BIGINT | 否 | 0 | 软删除唯一标记：0未删除，删除后写入id |
| 类型 | 名称 | 字段/表达式 |
|---|---|---|
| UNIQUE | uk_detail_group_live | tenant_id, business_code, detail_code, delete_token |
| INDEX | idx_detail_business | tenant_id, business_code, enabled, deleted |
• 多明细表约定：表格控件 options.field 使用 detail_code，表格列字段只使用字段本身，如 productName。
4.3 sys_print_field（打印字段定义表）
用途：定义某个业务类型可拖拽、可打印的字段，并提供字段权限、脱敏、格式化和多明细归属信息。
| 字段名 | 数据类型 | 可空 | 默认值 | 键 | 说明 |
|---|---|---|---|---|---|
| id | BIGINT AUTO_INCREMENT | 否 | PK | 主键ID | |
| tenant_id | BIGINT | 否 | 0 | 租户ID，0表示平台默认 | |
| business_code | VARCHAR(100) | 否 | UK字段 | 业务编码 | |
| field_scope | VARCHAR(30) | 否 | UK字段 | 字段范围：MAIN主表、DETAIL明细、SYSTEM系统、CUSTOM自定义 | |
| detail_code | VARCHAR(100) | 否 | '' | UK字段 | 明细编码，主表/系统/自定义字段为空字符串 |
| field_code | VARCHAR(100) | 否 | UK字段 | 字段编码，如 orderNo、productName | |
| field_path | VARCHAR(200) | 否 | 字段路径，如 orderNo、details.productName、sys.printTime | ||
| field_name | VARCHAR(100) | 否 | 字段名称，如采购单号 | ||
| field_type | VARCHAR(50) | 否 | 'text' | 字段类型：text、number、decimal、date、datetime、image、barcode、qrcode、table | |
| data_type | VARCHAR(50) | 是 | Java 数据类型或数据库类型 | ||
| source_table | VARCHAR(100) | 是 | 来源表 | ||
| source_column | VARCHAR(100) | 是 | 来源字段 | ||
| dict_code | VARCHAR(100) | 是 | 字典编码 | ||
| formatter | VARCHAR(500) | 是 | 前端格式化函数标识或后端格式化规则 | ||
| default_value | VARCHAR(500) | 是 | 默认值 | ||
| test_data | VARCHAR(500) | 是 | 设计器测试数据 | ||
| width | INT | 是 | 默认宽度，单位按 hiprint 配置 | ||
| visible | TINYINT | 否 | 1 | 字段面板是否可见：0否，1是 | |
| required | TINYINT | 否 | 0 | 是否必选：0否，1是 | |
| permission_code | VARCHAR(200) | 是 | 字段权限编码，如 print.field.PURCHASE_ORDER.details.price | ||
| sensitive_level | VARCHAR(30) | 否 | 'NORMAL' | 敏感级别：NORMAL、SENSITIVE、SECRET | |
| mask_rule | VARCHAR(50) | 是 | 脱敏规则：NONE、MOBILE、AMOUNT、HIDE 等 | ||
| sort_no | INT | 否 | 0 | 排序号 | |
| remark | VARCHAR(500) | 是 | 备注 | ||
| create_by | BIGINT | 是 | 创建人ID | ||
| create_name | VARCHAR(50) | 是 | 创建人名称 | ||
| create_time | DATETIME | 否 | CURRENT_TIMESTAMP | 创建时间 | |
| update_by | BIGINT | 是 | 修改人ID | ||
| update_name | VARCHAR(50) | 是 | 修改人名称 | ||
| update_time | DATETIME | 是 | NULL ON UPDATE CURRENT_TIMESTAMP | 修改时间 | |
| deleted | TINYINT | 否 | 0 | 逻辑删除：0否，1是 | |
| delete_token | BIGINT | 否 | 0 | 软删除唯一标记：0未删除，删除后写入id |
| 类型 | 名称 | 字段/表达式 |
|---|---|---|
| UNIQUE | uk_field_live | tenant_id, business_code, field_scope, detail_code, field_code, delete_token |
| UNIQUE | uk_field_path_live | tenant_id, business_code, field_path, delete_token |
| INDEX | idx_business_scope | tenant_id, business_code, field_scope, visible, deleted |
| INDEX | idx_permission_code | permission_code |
| INDEX | idx_detail_code | tenant_id, business_code, detail_code |
• 字段权限必须由后端校验；前端隐藏字段不能作为安全边界。
4.4 sys_print_template（打印模板表）
用途：保存 hiprint 模板 JSON、纸张信息、当前版本、模板 Hash 和模板启用状态。
| 字段名 | 数据类型 | 可空 | 默认值 | 键 | 说明 |
|---|---|---|---|---|---|
| id | BIGINT AUTO_INCREMENT | 否 | PK | 主键ID | |
| tenant_id | BIGINT | 否 | 0 | 租户ID，0表示平台默认 | |
| org_id | BIGINT | 否 | 0 | 组织ID，0表示全部组织 | |
| shop_id | BIGINT | 否 | 0 | 门店ID，0表示全部门店 | |
| business_code | VARCHAR(100) | 否 | 业务编码 | ||
| template_code | VARCHAR(100) | 否 | UK字段 | 模板编码 | |
| template_name | VARCHAR(100) | 否 | 模板名称 | ||
| template_type | VARCHAR(50) | 否 | 'NORMAL' | 模板类型：NORMAL普通、LABEL标签、BATCH批量 | |
| paper_type | VARCHAR(50) | 是 | 纸张类型：A4、A5、CUSTOM 等 | ||
| paper_width | DECIMAL(10,2) | 是 | 纸张宽度，单位 mm | ||
| paper_height | DECIMAL(10,2) | 是 | 纸张高度，单位 mm | ||
| template_json | LONGTEXT | 否 | hiprint 模板 JSON | ||
| preview_json | LONGTEXT | 是 | 预览测试数据 JSON | ||
| callback_url | VARCHAR(255) | 是 | 打印完成后业务回调地址 | ||
| version_no | INT | 否 | 1 | 当前版本号 | |
| current_version_id | BIGINT | 是 | 当前版本快照ID | ||
| template_hash | VARCHAR(64) | 是 | template_json 标准化后的 SHA-256 | ||
| last_save_time | DATETIME | 是 | 最后保存时间 | ||
| is_default | TINYINT | 否 | 0 | 是否默认模板冗余标记，实际唯一性以 sys_print_template_default 为准 | |
| enabled | TINYINT | 否 | 1 | 是否启用：0否，1是 | |
| remark | VARCHAR(500) | 是 | 备注 | ||
| create_by | BIGINT | 是 | 创建人ID | ||
| create_name | VARCHAR(50) | 是 | 创建人名称 | ||
| create_time | DATETIME | 否 | CURRENT_TIMESTAMP | 创建时间 | |
| update_by | BIGINT | 是 | 修改人ID | ||
| update_name | VARCHAR(50) | 是 | 修改人名称 | ||
| update_time | DATETIME | 是 | NULL ON UPDATE CURRENT_TIMESTAMP | 修改时间 | |
| deleted | TINYINT | 否 | 0 | 逻辑删除：0否，1是 | |
| delete_token | BIGINT | 否 | 0 | 软删除唯一标记：0未删除，删除后写入id |
| 类型 | 名称 | 字段/表达式 |
|---|---|---|
| UNIQUE | uk_template_code_live | tenant_id, template_code, delete_token |
| INDEX | idx_template_scope | tenant_id, org_id, shop_id, business_code, deleted |
| INDEX | idx_template_default | tenant_id, org_id, shop_id, business_code, is_default, deleted |
| INDEX | idx_template_hash | template_hash |
| INDEX | idx_enabled | enabled, deleted |
| CHECK | CHECK (JSON_VALID(template_json)) | |
| CHECK | CHECK (preview_json IS NULL OR JSON_VALID(preview_json)) |
• 同一作用域默认模板唯一性由 sys_print_template_default 表强约束。
4.5 sys_print_template_default（打印默认模板关系表）
用途：保证同一租户、组织、门店、业务编码下只有一个默认模板，并支持门店模板覆盖组织/租户模板。
| 字段名 | 数据类型 | 可空 | 默认值 | 键 | 说明 |
|---|---|---|---|---|---|
| id | BIGINT AUTO_INCREMENT | 否 | PK | 主键ID | |
| tenant_id | BIGINT | 否 | 0 | 租户ID，0表示平台默认 | |
| org_id | BIGINT | 否 | 0 | 组织ID，0表示全部组织 | |
| shop_id | BIGINT | 否 | 0 | 门店ID，0表示全部门店 | |
| business_code | VARCHAR(100) | 否 | UK字段 | 业务编码 | |
| template_id | BIGINT | 否 | 默认模板ID | ||
| template_code | VARCHAR(100) | 是 | 模板编码冗余 | ||
| template_name | VARCHAR(100) | 是 | 模板名称冗余 | ||
| scope_level | VARCHAR(30) | 否 | 'SHOP' | 作用域级别：PLATFORM、TENANT、ORG、SHOP | |
| remark | VARCHAR(500) | 是 | 备注 | ||
| create_by | BIGINT | 是 | 创建人ID | ||
| create_name | VARCHAR(50) | 是 | 创建人名称 | ||
| create_time | DATETIME | 否 | CURRENT_TIMESTAMP | 创建时间 | |
| update_by | BIGINT | 是 | 修改人ID | ||
| update_name | VARCHAR(50) | 是 | 修改人名称 | ||
| update_time | DATETIME | 是 | NULL ON UPDATE CURRENT_TIMESTAMP | 修改时间 | |
| deleted | TINYINT | 否 | 0 | 逻辑删除：0否，1是 | |
| delete_token | BIGINT | 否 | 0 | 软删除唯一标记：0未删除，删除后写入id |
| 类型 | 名称 | 字段/表达式 |
|---|---|---|
| UNIQUE | uk_template_default_live | tenant_id, org_id, shop_id, business_code, delete_token |
| INDEX | idx_default_template | template_id |
| INDEX | idx_default_lookup | tenant_id, org_id, shop_id, business_code, deleted |
• 查询默认模板建议按 shop -> org -> tenant -> platform 的优先级回退。
4.6 sys_print_template_version（打印模板版本表）
用途：保存每次创建、保存、回滚后的模板快照。回滚时生成新版本，不覆盖历史版本。
| 字段名 | 数据类型 | 可空 | 默认值 | 键 | 说明 |
|---|---|---|---|---|---|
| id | BIGINT AUTO_INCREMENT | 否 | PK | 主键ID | |
| tenant_id | BIGINT | 否 | 0 | 租户ID，0表示平台默认 | |
| template_id | BIGINT | 否 | UK字段 | 模板ID | |
| template_code | VARCHAR(100) | 是 | 模板编码 | ||
| business_code | VARCHAR(100) | 否 | 业务编码 | ||
| template_name | VARCHAR(100) | 否 | 版本快照中的模板名称 | ||
| version_no | INT | 否 | UK字段 | 版本号 | |
| template_json | LONGTEXT | 否 | 模板 JSON 快照 | ||
| template_hash | VARCHAR(64) | 是 | 模板 JSON SHA-256 | ||
| preview_json | LONGTEXT | 是 | 预览数据 JSON 快照 | ||
| operate_type | VARCHAR(50) | 否 | 'SAVE' | 操作类型：CREATE、SAVE、ROLLBACK | |
| rollback_from_version_no | INT | 是 | 回滚来源版本号 | ||
| source_version_id | BIGINT | 是 | 来源版本ID | ||
| change_remark | VARCHAR(500) | 是 | 变更说明 | ||
| enabled | TINYINT | 否 | 1 | 版本是否可用：0否，1是 | |
| create_by | BIGINT | 是 | 创建人ID | ||
| create_name | VARCHAR(50) | 是 | 创建人名称 | ||
| create_time | DATETIME | 否 | CURRENT_TIMESTAMP | 创建时间 |
| 类型 | 名称 | 字段/表达式 |
|---|---|---|
| UNIQUE | uk_template_version | template_id, version_no |
| INDEX | idx_template_id | template_id |
| INDEX | idx_business_code | business_code |
| INDEX | idx_template_hash | template_hash |
| CHECK | CHECK (JSON_VALID(template_json)) | |
| CHECK | CHECK (preview_json IS NULL OR JSON_VALID(preview_json)) |
• 如果模板内容 Hash 未变化，建议不生成新版本。
4.7 sys_print_template_field（打印模板字段使用表）
用途：记录模板 JSON 解析出来的字段清单，用于保存校验、字段权限复核、影响范围分析。
| 字段名 | 数据类型 | 可空 | 默认值 | 键 | 说明 |
|---|---|---|---|---|---|
| id | BIGINT AUTO_INCREMENT | 否 | PK | 主键ID | |
| tenant_id | BIGINT | 否 | 0 | 租户ID，0表示平台默认 | |
| template_id | BIGINT | 否 | UK字段 | 模板ID | |
| business_code | VARCHAR(100) | 否 | 业务编码 | ||
| field_scope | VARCHAR(30) | 否 | 字段范围：MAIN、DETAIL、SYSTEM、CUSTOM | ||
| detail_code | VARCHAR(100) | 否 | '' | 明细编码，非明细字段为空字符串 | |
| field_code | VARCHAR(100) | 否 | 字段编码 | ||
| field_path | VARCHAR(200) | 否 | UK字段 | 字段路径 | |
| permission_code | VARCHAR(200) | 是 | 字段权限编码快照 | ||
| sensitive_level | VARCHAR(30) | 否 | 'NORMAL' | 敏感级别快照 | |
| create_time | DATETIME | 否 | CURRENT_TIMESTAMP | 创建时间 | |
| deleted | TINYINT | 否 | 0 | 逻辑删除：0否，1是 | |
| delete_token | BIGINT | 否 | 0 | 软删除唯一标记：0未删除，删除后写入id |
| 类型 | 名称 | 字段/表达式 |
|---|---|---|
| UNIQUE | uk_template_field_live | template_id, field_path, delete_token |
| INDEX | idx_template_field_business | tenant_id, business_code, field_scope, detail_code |
| INDEX | idx_template_field_permission | permission_code |
• 模板保存成功后重建本表，打印时再次根据用户权限校验。
4.8 sys_print_log（打印日志主表）
用途：记录一次预览、浏览器打印或静默打印的主日志，保留请求、客户端、模板和总体状态。
| 字段名 | 数据类型 | 可空 | 默认值 | 键 | 说明 |
|---|---|---|---|---|---|
| id | BIGINT AUTO_INCREMENT | 否 | PK | 主键ID | |
| tenant_id | BIGINT | 否 | 0 | 租户ID，0表示平台默认 | |
| org_id | BIGINT | 否 | 0 | 组织ID，0表示全部组织 | |
| shop_id | BIGINT | 否 | 0 | 门店ID，0表示全部门店 | |
| log_no | VARCHAR(100) | 否 | UK字段 | 打印日志编号 | |
| task_no | VARCHAR(100) | 是 | 打印任务编号 | ||
| request_id | VARCHAR(100) | 是 | 幂等请求ID | ||
| client_id | VARCHAR(100) | 是 | 静默打印客户端ID | ||
| business_code | VARCHAR(100) | 否 | 业务编码 | ||
| business_name | VARCHAR(100) | 是 | 业务名称 | ||
| template_id | BIGINT | 是 | 模板ID | ||
| template_code | VARCHAR(100) | 是 | 模板编码 | ||
| template_name | VARCHAR(100) | 是 | 模板名称 | ||
| template_version_no | INT | 是 | 模板版本号 | ||
| business_ids | LONGTEXT | 否 | 打印业务ID列表 JSON | ||
| print_mode | VARCHAR(50) | 否 | 'BROWSER' | 打印方式：PREVIEW、BROWSER、SILENT | |
| print_status | VARCHAR(50) | 否 | 'SUBMITTED' | 打印状态：PREVIEWED、PRINT_DIALOG、SUBMITTED、PRINTING、SUCCESS、PARTIAL_SUCCESS、FAIL、CANCEL、UNKNOWN | |
| printer_name | VARCHAR(100) | 是 | 打印机名称 | ||
| print_count | INT | 否 | 1 | 打印份数 | |
| error_code | VARCHAR(100) | 是 | 错误编码 | ||
| error_message | TEXT | 是 | 错误信息 | ||
| request_param | LONGTEXT | 是 | 请求参数 JSON | ||
| callback_status | VARCHAR(50) | 是 | 回调状态 | ||
| callback_message | TEXT | 是 | 回调结果 | ||
| client_ip | VARCHAR(50) | 是 | 客户端IP | ||
| user_agent | VARCHAR(500) | 是 | 浏览器信息 | ||
| start_time | DATETIME | 是 | 开始时间 | ||
| end_time | DATETIME | 是 | 结束时间 | ||
| duration_ms | BIGINT | 是 | 耗时毫秒 | ||
| remark | VARCHAR(500) | 是 | 备注 | ||
| create_by | BIGINT | 是 | 打印人ID | ||
| create_name | VARCHAR(50) | 是 | 打印人名称 | ||
| create_time | DATETIME | 否 | CURRENT_TIMESTAMP | 打印时间 | |
| update_by | BIGINT | 是 | 修改人ID | ||
| update_name | VARCHAR(50) | 是 | 修改人名称 | ||
| update_time | DATETIME | 是 | NULL ON UPDATE CURRENT_TIMESTAMP | 修改时间 | |
| deleted | TINYINT | 否 | 0 | 逻辑删除：0否，1是 |
| 类型 | 名称 | 字段/表达式 |
|---|---|---|
| UNIQUE | uk_log_no | log_no |
| UNIQUE | uk_log_request | tenant_id, request_id |
| INDEX | idx_log_business | tenant_id, business_code, create_time |
| INDEX | idx_log_template | template_id |
| INDEX | idx_log_task_no | task_no |
| INDEX | idx_log_client_id | client_id |
| INDEX | idx_log_status | print_status, create_time |
| INDEX | idx_log_create_by | create_by, create_time |
| CHECK | CHECK (JSON_VALID(business_ids)) | |
| CHECK | CHECK (request_param IS NULL OR JSON_VALID(request_param)) |
• 浏览器打印不能可靠判断是否真正出纸，建议状态记录为 PRINT_DIALOG 或 UNKNOWN。
4.9 sys_print_log_item（打印日志明细表）
用途：记录一次打印中每一张业务单据的打印结果，便于追踪单据打印历史和批量部分失败。
| 字段名 | 数据类型 | 可空 | 默认值 | 键 | 说明 |
|---|---|---|---|---|---|
| id | BIGINT AUTO_INCREMENT | 否 | PK | 主键ID | |
| tenant_id | BIGINT | 否 | 0 | 租户ID，0表示平台默认 | |
| org_id | BIGINT | 否 | 0 | 组织ID，0表示全部组织 | |
| shop_id | BIGINT | 否 | 0 | 门店ID，0表示全部门店 | |
| log_id | BIGINT | 否 | UK字段 | 打印日志ID | |
| business_code | VARCHAR(100) | 否 | UK字段 | 业务编码 | |
| business_id | BIGINT | 否 | UK字段 | 业务ID | |
| business_no | VARCHAR(100) | 是 | 业务单号 | ||
| template_id | BIGINT | 是 | 模板ID | ||
| template_name | VARCHAR(100) | 是 | 模板名称 | ||
| print_mode | VARCHAR(50) | 否 | 打印方式 | ||
| print_status | VARCHAR(50) | 否 | 'SUBMITTED' | 打印状态 | |
| printer_name | VARCHAR(100) | 是 | 打印机名称 | ||
| print_count | INT | 否 | 1 | 打印份数 | |
| error_code | VARCHAR(100) | 是 | 错误编码 | ||
| error_message | TEXT | 是 | 错误信息 | ||
| create_by | BIGINT | 是 | 打印人ID | ||
| create_name | VARCHAR(50) | 是 | 打印人名称 | ||
| create_time | DATETIME | 否 | CURRENT_TIMESTAMP | 创建时间 | |
| update_time | DATETIME | 是 | NULL ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
| 类型 | 名称 | 字段/表达式 |
|---|---|---|
| UNIQUE | uk_log_business | log_id, business_code, business_id |
| INDEX | idx_business_trace | tenant_id, business_code, business_id, create_time |
| INDEX | idx_log_item_status | print_status, create_time |
| INDEX | idx_log_item_template | template_id |
• 业务单据详情页可按 tenant_id + business_code + business_id 查询打印历史。
4.10 sys_print_task（打印任务表）
用途：用于批量打印、静默打印、异步打印的任务主表，支持客户端状态回传和幂等控制。
| 字段名 | 数据类型 | 可空 | 默认值 | 键 | 说明 |
|---|---|---|---|---|---|
| id | BIGINT AUTO_INCREMENT | 否 | PK | 主键ID | |
| tenant_id | BIGINT | 否 | 0 | 租户ID，0表示平台默认 | |
| org_id | BIGINT | 否 | 0 | 组织ID，0表示全部组织 | |
| shop_id | BIGINT | 否 | 0 | 门店ID，0表示全部门店 | |
| task_no | VARCHAR(100) | 否 | UK字段 | 任务编号 | |
| request_id | VARCHAR(100) | 是 | 幂等请求ID | ||
| log_id | BIGINT | 是 | 关联打印日志ID | ||
| client_id | VARCHAR(100) | 是 | 静默打印客户端ID | ||
| business_code | VARCHAR(100) | 否 | 业务编码 | ||
| template_id | BIGINT | 否 | 模板ID | ||
| template_version_no | INT | 是 | 模板版本号 | ||
| business_ids | LONGTEXT | 否 | 业务ID列表 JSON | ||
| task_status | VARCHAR(50) | 否 | 'WAITING' | 任务状态：WAITING、SUBMITTED、CLIENT_RECEIVED、PRINTING、SUCCESS、PARTIAL_SUCCESS、FAIL、CANCEL、UNKNOWN | |
| print_mode | VARCHAR(50) | 否 | 'BROWSER' | 打印方式 | |
| printer_name | VARCHAR(100) | 是 | 打印机名称 | ||
| print_count | INT | 否 | 1 | 打印份数 | |
| render_mode | VARCHAR(50) | 否 | 'HIPRINT_JSON' | 渲染方式：HIPRINT_JSON、HTML、PDF | |
| payload_hash | VARCHAR(64) | 是 | 打印载荷 SHA-256 | ||
| result_message | TEXT | 是 | 任务结果信息 | ||
| error_code | VARCHAR(100) | 是 | 错误编码 | ||
| error_message | TEXT | 是 | 错误信息 | ||
| start_time | DATETIME | 是 | 开始时间 | ||
| end_time | DATETIME | 是 | 结束时间 | ||
| duration_ms | BIGINT | 是 | 耗时毫秒 | ||
| remark | VARCHAR(500) | 是 | 备注 | ||
| create_by | BIGINT | 是 | 创建人ID | ||
| create_name | VARCHAR(50) | 是 | 创建人名称 | ||
| create_time | DATETIME | 否 | CURRENT_TIMESTAMP | 创建时间 | |
| update_by | BIGINT | 是 | 修改人ID | ||
| update_name | VARCHAR(50) | 是 | 修改人名称 | ||
| update_time | DATETIME | 是 | NULL ON UPDATE CURRENT_TIMESTAMP | 修改时间 | |
| deleted | TINYINT | 否 | 0 | 逻辑删除：0否，1是 |
| 类型 | 名称 | 字段/表达式 |
|---|---|---|
| UNIQUE | uk_task_no | task_no |
| UNIQUE | uk_task_request | tenant_id, request_id |
| INDEX | idx_task_status | task_status, create_time |
| INDEX | idx_task_business | tenant_id, business_code, create_time |
| INDEX | idx_task_client | client_id, task_status |
| INDEX | idx_task_template | template_id |
| CHECK | CHECK (JSON_VALID(business_ids)) |
• 静默打印回调根据 task_no 和 request_id 做幂等更新。
4.11 sys_print_task_item（打印任务明细表）
用途：记录打印任务中每个业务单据的任务状态，支持批量任务部分成功、失败重试。
| 字段名 | 数据类型 | 可空 | 默认值 | 键 | 说明 |
|---|---|---|---|---|---|
| id | BIGINT AUTO_INCREMENT | 否 | PK | 主键ID | |
| tenant_id | BIGINT | 否 | 0 | 租户ID，0表示平台默认 | |
| org_id | BIGINT | 否 | 0 | 组织ID，0表示全部组织 | |
| shop_id | BIGINT | 否 | 0 | 门店ID，0表示全部门店 | |
| task_id | BIGINT | 否 | UK字段 | 任务ID | |
| task_no | VARCHAR(100) | 否 | 任务编号 | ||
| business_code | VARCHAR(100) | 否 | UK字段 | 业务编码 | |
| business_id | BIGINT | 否 | UK字段 | 业务ID | |
| business_no | VARCHAR(100) | 是 | 业务单号 | ||
| item_status | VARCHAR(50) | 否 | 'WAITING' | 明细状态：WAITING、SUBMITTED、PRINTING、SUCCESS、FAIL、CANCEL、UNKNOWN | |
| printer_name | VARCHAR(100) | 是 | 打印机名称 | ||
| print_count | INT | 否 | 1 | 打印份数 | |
| error_code | VARCHAR(100) | 是 | 错误编码 | ||
| error_message | TEXT | 是 | 错误信息 | ||
| start_time | DATETIME | 是 | 开始时间 | ||
| end_time | DATETIME | 是 | 结束时间 | ||
| create_time | DATETIME | 否 | CURRENT_TIMESTAMP | 创建时间 | |
| update_time | DATETIME | 是 | NULL ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
| 类型 | 名称 | 字段/表达式 |
|---|---|---|
| UNIQUE | uk_task_business | task_id, business_code, business_id |
| INDEX | idx_task_item_no | task_no |
| INDEX | idx_task_item_business | tenant_id, business_code, business_id, create_time |
| INDEX | idx_task_item_status | item_status, create_time |
• 任务失败重试时可只重试 FAIL 的明细。
4.12 sys_print_client（静默打印客户端表）
用途：登记本地打印客户端或中转打印客户端，用于在线检测、版本控制、打印机列表同步和安全认证。
| 字段名 | 数据类型 | 可空 | 默认值 | 键 | 说明 |
|---|---|---|---|---|---|
| id | BIGINT AUTO_INCREMENT | 否 | PK | 主键ID | |
| tenant_id | BIGINT | 否 | 0 | 租户ID，0表示平台默认 | |
| org_id | BIGINT | 否 | 0 | 组织ID，0表示全部组织 | |
| shop_id | BIGINT | 否 | 0 | 门店ID，0表示全部门店 | |
| client_id | VARCHAR(100) | 否 | UK字段 | 客户端唯一编码，如 SXBC-STORE1001-POS01 | |
| client_name | VARCHAR(100) | 否 | 客户端名称 | ||
| client_type | VARCHAR(50) | 否 | 'LOCAL' | 客户端类型：LOCAL本机、GATEWAY中转 | |
| client_version | VARCHAR(50) | 是 | 客户端版本号 | ||
| protocol_version | VARCHAR(50) | 是 | 协议版本号 | ||
| os_name | VARCHAR(100) | 是 | 操作系统 | ||
| host | VARCHAR(100) | 是 | 客户端主机地址 | ||
| port | INT | 是 | 客户端端口 | ||
| status | VARCHAR(50) | 否 | 'OFFLINE' | 状态：ONLINE在线、OFFLINE离线、DISABLED禁用 | |
| heartbeat_time | DATETIME | 是 | 最后心跳时间 | ||
| token_version | INT | 否 | 1 | 认证 token 版本，用于失效旧 token | |
| min_protocol_version | VARCHAR(50) | 是 | 最低兼容协议版本 | ||
| enabled | TINYINT | 否 | 1 | 是否启用：0否，1是 | |
| remark | VARCHAR(500) | 是 | 备注 | ||
| create_by | BIGINT | 是 | 创建人ID | ||
| create_name | VARCHAR(50) | 是 | 创建人名称 | ||
| create_time | DATETIME | 否 | CURRENT_TIMESTAMP | 创建时间 | |
| update_by | BIGINT | 是 | 修改人ID | ||
| update_name | VARCHAR(50) | 是 | 修改人名称 | ||
| update_time | DATETIME | 是 | NULL ON UPDATE CURRENT_TIMESTAMP | 修改时间 | |
| deleted | TINYINT | 否 | 0 | 逻辑删除：0否，1是 | |
| delete_token | BIGINT | 否 | 0 | 软删除唯一标记：0未删除，删除后写入id |
| 类型 | 名称 | 字段/表达式 |
|---|---|---|
| UNIQUE | uk_print_client_live | tenant_id, client_id, delete_token |
| INDEX | idx_client_scope | tenant_id, org_id, shop_id, status, deleted |
| INDEX | idx_client_heartbeat | heartbeat_time |
• 本地客户端默认只监听 127.0.0.1；远程中转客户端必须经过 token 和签名校验。
4.13 sys_print_client_printer（静默打印客户端打印机表）
用途：保存客户端同步的打印机列表，支持指定打印机、默认打印机和状态展示。
| 字段名 | 数据类型 | 可空 | 默认值 | 键 | 说明 |
|---|---|---|---|---|---|
| id | BIGINT AUTO_INCREMENT | 否 | PK | 主键ID | |
| tenant_id | BIGINT | 否 | 0 | 租户ID，0表示平台默认 | |
| org_id | BIGINT | 否 | 0 | 组织ID，0表示全部组织 | |
| shop_id | BIGINT | 否 | 0 | 门店ID，0表示全部门店 | |
| client_id | VARCHAR(100) | 否 | UK字段 | 客户端唯一编码 | |
| printer_name | VARCHAR(100) | 否 | UK字段 | 打印机名称 | |
| printer_type | VARCHAR(50) | 是 | 打印机类型：NORMAL普通、LABEL标签等 | ||
| is_default | TINYINT | 否 | 0 | 是否客户端默认打印机：0否，1是 | |
| printer_status | VARCHAR(50) | 否 | 'UNKNOWN' | 打印机状态：READY、OFFLINE、ERROR、PAPER_EMPTY、UNKNOWN | |
| driver_name | VARCHAR(200) | 是 | 驱动名称 | ||
| paper_support | VARCHAR(500) | 是 | 支持纸张，逗号分隔或 JSON | ||
| last_sync_time | DATETIME | 是 | 最后同步时间 | ||
| enabled | TINYINT | 否 | 1 | 是否启用：0否，1是 | |
| remark | VARCHAR(500) | 是 | 备注 | ||
| create_by | BIGINT | 是 | 创建人ID | ||
| create_name | VARCHAR(50) | 是 | 创建人名称 | ||
| create_time | DATETIME | 否 | CURRENT_TIMESTAMP | 创建时间 | |
| update_by | BIGINT | 是 | 修改人ID | ||
| update_name | VARCHAR(50) | 是 | 修改人名称 | ||
| update_time | DATETIME | 是 | NULL ON UPDATE CURRENT_TIMESTAMP | 修改时间 | |
| deleted | TINYINT | 否 | 0 | 逻辑删除：0否，1是 | |
| delete_token | BIGINT | 否 | 0 | 软删除唯一标记：0未删除，删除后写入id |
| 类型 | 名称 | 字段/表达式 |
|---|---|---|
| UNIQUE | uk_client_printer_live | tenant_id, client_id, printer_name, delete_token |
| INDEX | idx_printer_client | client_id, enabled, deleted |
| INDEX | idx_printer_status | printer_status |
| INDEX | idx_printer_default | tenant_id, client_id, is_default |
• 打印任务提交前建议校验 printer_name 是否存在且状态为 READY。
4.14 sys_print_callback（打印回调记录表）
用途：记录静默打印结果回调和业务回调，支持失败重试、响应追踪和问题排查。
| 字段名 | 数据类型 | 可空 | 默认值 | 键 | 说明 |
|---|---|---|---|---|---|
| id | BIGINT AUTO_INCREMENT | 否 | PK | 主键ID | |
| tenant_id | BIGINT | 否 | 0 | 租户ID，0表示平台默认 | |
| org_id | BIGINT | 否 | 0 | 组织ID，0表示全部组织 | |
| shop_id | BIGINT | 否 | 0 | 门店ID，0表示全部门店 | |
| callback_no | VARCHAR(100) | 否 | UK字段 | 回调编号 | |
| task_no | VARCHAR(100) | 是 | 打印任务编号 | ||
| log_id | BIGINT | 是 | 打印日志ID | ||
| request_id | VARCHAR(100) | 是 | 幂等请求ID | ||
| callback_type | VARCHAR(50) | 否 | 'SILENT_RESULT' | 回调类型：SILENT_RESULT、BUSINESS_CALLBACK | |
| callback_url | VARCHAR(255) | 是 | 回调地址 | ||
| callback_status | VARCHAR(50) | 否 | 'WAITING' | 回调状态：WAITING、SUCCESS、FAIL、IGNORE | |
| retry_count | INT | 否 | 0 | 已重试次数 | |
| max_retry_count | INT | 否 | 3 | 最大重试次数 | |
| request_body | LONGTEXT | 是 | 回调请求内容 JSON | ||
| response_body | LONGTEXT | 是 | 回调响应内容 | ||
| error_message | TEXT | 是 | 错误信息 | ||
| next_retry_time | DATETIME | 是 | 下次重试时间 | ||
| remark | VARCHAR(500) | 是 | 备注 | ||
| create_by | BIGINT | 是 | 创建人ID | ||
| create_name | VARCHAR(50) | 是 | 创建人名称 | ||
| create_time | DATETIME | 否 | CURRENT_TIMESTAMP | 创建时间 | |
| update_by | BIGINT | 是 | 修改人ID | ||
| update_name | VARCHAR(50) | 是 | 修改人名称 | ||
| update_time | DATETIME | 是 | NULL ON UPDATE CURRENT_TIMESTAMP | 修改时间 | |
| deleted | TINYINT | 否 | 0 | 逻辑删除：0否，1是 |
| 类型 | 名称 | 字段/表达式 |
|---|---|---|
| UNIQUE | uk_callback_no | callback_no |
| INDEX | idx_callback_task | task_no |
| INDEX | idx_callback_log | log_id |
| INDEX | idx_callback_request | request_id |
| INDEX | idx_callback_status | callback_status, next_retry_time |
| CHECK | CHECK (request_body IS NULL OR JSON_VALID(request_body)) |
• 重要业务状态变更不能只依赖前端，应以后端或客户端可信回调为准。
5. 枚举数据字典
field_scope 字段范围
| 值 | 名称 | 说明 |
|---|---|---|
| MAIN | 主表字段 | 单据头字段 |
| DETAIL | 明细字段 | 商品明细、费用明细、包装明细等 |
| SYSTEM | 系统字段 | 打印时间、打印人、公司名称等 |
| CUSTOM | 自定义字段 | 后端动态计算字段，如金额大写 |
field_type 字段类型
| 值 | 名称 | 说明 |
|---|---|---|
| text | 文本 | 普通文本 |
| number | 数字 | 整数 |
| decimal | 小数 | 金额、数量 |
| date | 日期 | yyyy-MM-dd |
| datetime | 日期时间 | yyyy-MM-dd HH:mm:ss |
| image | 图片 | 商品图、签名图 |
| barcode | 条形码 | 商品条码 |
| qrcode | 二维码 | 溯源码、单据码 |
| table | 表格 | 明细表或批量表格 |
template_type 模板类型
| 值 | 名称 | 说明 |
|---|---|---|
| NORMAL | 普通模板 | A4/A5 单据 |
| LABEL | 标签模板 | 商品标签、箱标 |
| BATCH | 批量模板 | 多单据连续打印 |
print_mode 打印方式
| 值 | 名称 | 说明 |
|---|---|---|
| PREVIEW | 预览 | 只预览不打印 |
| BROWSER | 浏览器打印 | 调用浏览器打印窗口 |
| SILENT | 静默打印 | 通过本地客户端或 WebSocket 打印 |
print_status 打印状态
| 值 | 名称 | 说明 |
|---|---|---|
| PREVIEWED | 已预览 | 已生成预览 |
| PRINT_DIALOG | 打印窗口已打开 | 浏览器打印只建议记录到此状态 |
| SUBMITTED | 已提交 | 任务已提交 |
| PRINTING | 打印中 | 客户端正在打印 |
| SUCCESS | 成功 | 静默客户端确认成功 |
| PARTIAL_SUCCESS | 部分成功 | 批量中部分单据成功 |
| FAIL | 失败 | 打印失败 |
| CANCEL | 取消 | 取消打印 |
| UNKNOWN | 未知 | 无法确认最终结果 |
task_status 任务状态
| 值 | 名称 | 说明 |
|---|---|---|
| WAITING | 等待中 | 待提交 |
| SUBMITTED | 已提交 | 已提交到客户端或队列 |
| CLIENT_RECEIVED | 客户端已接收 | 静默客户端确认接收 |
| PRINTING | 打印中 | 执行中 |
| SUCCESS | 成功 | 全部成功 |
| PARTIAL_SUCCESS | 部分成功 | 部分成功部分失败 |
| FAIL | 失败 | 全部失败或任务失败 |
| CANCEL | 取消 | 任务取消 |
| UNKNOWN | 未知 | 状态未知 |
sensitive_level 敏感级别
| 值 | 名称 | 说明 |
|---|---|---|
| NORMAL | 普通 | 普通字段 |
| SENSITIVE | 敏感 | 需要权限或脱敏 |
| SECRET | 高敏 | 无权限应拒绝打印 |
operate_type 模板版本操作类型
| 值 | 名称 | 说明 |
|---|---|---|
| CREATE | 创建 | 创建模板 |
| SAVE | 保存 | 保存模板 |
| ROLLBACK | 回滚 | 由历史版本回滚生成的新版本 |
client_status 客户端状态
| 值 | 名称 | 说明 |
|---|---|---|
| ONLINE | 在线 | 心跳正常 |
| OFFLINE | 离线 | 心跳超时 |
| DISABLED | 禁用 | 后台禁用 |
printer_status 打印机状态
| 值 | 名称 | 说明 |
|---|---|---|
| READY | 就绪 | 可打印 |
| OFFLINE | 离线 | 打印机离线 |
| ERROR | 错误 | 打印机错误 |
| PAPER_EMPTY | 缺纸 | 打印机缺纸 |
| UNKNOWN | 未知 | 未获取状态 |
callback_status 回调状态
| 值 | 名称 | 说明 |
|---|---|---|
| WAITING | 等待 | 待回调或待重试 |
| SUCCESS | 成功 | 回调成功 |
| FAIL | 失败 | 回调失败 |
| IGNORE | 忽略 | 无需回调或人工忽略 |
6. 关键落库规则
6.1 默认模板唯一性
默认模板以 sys_print_template_default 为唯一事实来源，唯一键为 tenant_id + org_id + shop_id + business_code + delete_token。模板表 is_default 只作为冗余展示字段。
6.2 软删除唯一索引
所有需要复用编码的表均包含 delete_token。未删除记录 delete_token=0；逻辑删除时同时设置 deleted=1、delete_token=id。这样既保留历史，又允许重新创建相同编码。
6.3 多明细表 hiprint 字段约定
主表字段直接使用 orderNo；系统字段使用 sys.printTime；自定义字段使用 custom.amountCn；明细表字段在字段定义中使用 details.productName，但 hiprint 表格控件 options.field 必须使用 details，表格列字段使用 productName。
6.4 字段权限
模板设计字段面板、模板保存字段解析、打印数据取数均要校验 sys_print_field.permission_code。高敏字段无权限时应拒绝打印，敏感字段可按 mask_rule 脱敏。
6.5 打印状态可信度
浏览器打印不能可靠确认用户是否真实出纸，因此 BROWSER 模式建议记录 PRINT_DIALOG 或 UNKNOWN；只有静默客户端可信回调后才记录 SUCCESS 或 FAIL。