iPrint：智能打印管理平台

企业打印场景的痛点是什么？模板散落在各系统、打印机对接复杂、批量打印需要手写逻辑、Excel 数据还要手动搬运。iPrint 把这些全部收进一个平台：模板管理 → 数据渲染 → CUPS 打印 → 任务追踪，全链路自动化。

一、核心问题：企业打印为什么难？

没有统一平台之前，每个业务系统各自对接打印机、各自管理模板、各自处理 Excel 数据——重复劳动、风格不统一、出错难追溯。

二、iPrint 架构：一个平台，统一打印

三、技术栈全景

四、核心功能模块

4.1 模板管理 — 可视化设计，版本化管理

基于 Hiprint 的 JSON 模板格式，支持拖拽式可视化设计。模板定义了纸张大小、布局、数据绑定（文本、表格、二维码、条形码等），存储在数据库中统一管理。

{
  "code": "TPL-001",
  "name": "销售单模板",
  "templateData": {
    "panels": [{
      "paperType": "A4",
      "width": 210,
      "height": 297,
      "printElements": [
        { "options": { "field": "name", "title": "姓名" } },
        { "options": { "field": "table", "columns": [...] } }
      ]
    }]
  }
}

4.2 渲染引擎 — 模板 + 数据 → HTML / PDF

渲染引擎是 iPrint 的核心能力。将 Hiprint 模板 JSON 与打印数据合并，生成 HTML 预览或通过 wkhtmltopdf 转换为 PDF 文件。

4.3 CUPS 打印 — 单次与批量，异步任务追踪

通过 cups4j 库直接与 CUPS 服务器通信（IPP 协议），支持单次打印和批量打印。每个打印任务独立追踪状态，失败可重试。

4.4 Excel 导入 — 上传即解析，直接打印

上传 .xlsx / .xls 文件，自动识别表头和数据行，解析结果可直接作为批量打印的数据源。典型流程：上传 Excel → 解析 → 提交批量打印 → 查询进度。

{
  "headers": ["姓名", "年龄", "城市"],
  "totalRows": 2,
  "dataList": [
    { "姓名": "张三", "年龄": 25, "城市": "北京" },
    { "姓名": "李四", "年龄": 30, "城市": "上海" }
  ]
}

4.5 双通道认证 — Session + API Key

管理后台通过用户名密码登录（Session 认证），第三方系统通过 X-API-Key 请求头接入。API Key 认证走 Caffeine 缓存加速，先查缓存再查数据库。

五、API 端点一览

认证与用户

模板管理

渲染引擎

CUPS 打印

六、调用示例

单次打印

curl -X POST http://localhost:58080/api/cups/print \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "templateCode": "TPL-001",
    "data": { "name": "张三", "amount": "1000" },
    "printerName": "HP-LaserJet",
    "copies": 1,
    "paperSize": "A4"
  }'

批量打印（Excel → 打印）

# 1. 上传 Excel 解析数据
curl -X POST http://localhost:58080/api/cups/excel/parse \
  -H "X-API-Key: your-api-key" \
  -F "file=@data.xlsx"

# 2. 将解析结果提交批量打印
curl -X POST http://localhost:58080/api/cups/batch/submit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "templateCode": "TPL-001",
    "dataList": [
      { "姓名": "张三", "金额": "1000" },
      { "姓名": "李四", "金额": "2000" }
    ],
    "printerName": "HP-LaserJet"
  }'

# 3. 查询批次进度
curl http://localhost:58080/api/cups/batch/1 \
  -H "X-API-Key: your-api-key"

渲染 HTML 预览

curl -X POST http://localhost:58080/api/engine/render/html \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "code": "TPL-001",
    "printData": [{ "name": "张三", "amount": "1000" }]
  }'

七、本地构建与运行

项目是标准的 Spring Boot + Vue 前后端分离结构，本地开发只需 Java 17 + Maven + PostgreSQL。

环境要求

1. 初始化数据库

# 创建数据库
createdb iboot_iprint

# 导入初始化脚本（含表结构 + 示例数据）
psql -d iboot_iprint -f DatabaseScripts/postgres-init.sql

2. 后端构建运行

# 编译打包（跳过测试加速）
mvn clean package -DskipTests

# 直接运行
java -jar target/iboot-iprint-0.0.1-SNAPSHOT.jar

# 或指定生产配置
java -jar target/iboot-iprint-0.0.1-SNAPSHOT.jar \
  --spring.config.location=config/application-prod.yaml

3. 前端构建

# 进入前端目录
cd iboot-iprint-ui

# 安装依赖
pnpm install

# 开发模式（热更新）
pnpm dev

# 生产构建（输出到后端 static 目录）
pnpm build

4. 配置说明

server:
  port: 58080                  # 服务端口

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/iboot_iprint
    username: postgres
    password: your-password

cups:
  host: localhost              # CUPS 服务器地址
  port: 631                    # CUPS 端口
  batch:
    thread-pool-size: 4        # 并行打印线程数
    task-interval-ms: 500      # 任务提交间隔
    max-batch-size: 5000       # 单批次上限

5. 运行测试

# 全量测试（使用 H2 内存数据库，无需 PostgreSQL）
mvn test

# 访问
# http://localhost:58080
# 默认管理员：admin / 123456

八、项目结构

九、数据模型

十、设计总结

• 统一模板管理：Hiprint JSON 格式，可视化设计器，版本化存储，一处修改全局生效
• 统一渲染引擎：模板 + 数据 → HTML 预览 / PDF 文件，支持编码引用和直接 JSON
• 统一打印通道：CUPS/IPP 协议直连，单次/批量打印，异步任务追踪，失败可重试
• Excel 数据桥接：上传即解析，解析结果直接作为批量打印数据源，零手动搬运
• 双通道认证：Session（管理后台）+ API Key（第三方集成），Caffeine 缓存加速
• 本地构建运行：Maven 一键打包，Java 直接运行，配置外部化，开箱即用