# LabelFlowTSPL

**Repository Path**: zero-vin/label-data-service

## Basic Information

- **Project Name**: LabelFlowTSPL
- **Description**: LabelFlow — 基于 TSPL 协议的开源标签打印服务平台
    Web 端可视化标签设计 + 多数据源绑定 + 所见即所得预览 + Raw TCP 直驱打印机
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-14
- **Last Updated**: 2026-04-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Java, lable, Vue

## README

# 🏷️ 标签数据采集与打印服务平台

> **云发现标签打印系统** — 基于 TSPL 协议的标签模板设计、数据源绑定、预览与打印一站式服务

---

## 📋 技术栈

| 层级 | 技术 |
|------|------|
| **后端** | Spring Boot 3.2.0 + Java 17 |
| **数据库** | PostgreSQL 15 + JPA/Hibernate |
| **缓存** | Redis 7 |
| **前端** | Vue 3 + Element Plus |
| **打印协议** | TSPL（TSC/条码打印机通用协议） |
| **渲染引擎** | Java Graphics2D（统一渲染管线） |
| **条码/二维码** | ZXing 3.5.3 |
| **通信方式** | Raw TCP Socket（端口 9100） |

---

## 🏗️ 项目结构

```
label-data-service/
├── label-common/       # 公共模块（统一响应、异常处理、工具类）
├── label-datasource/   # 数据源模块（数据库/Excel 数据源管理、查询执行）
├── label-template/     # 模板模块（标签设计编译、图片渲染、字体管理）
├── label-print/        # 打印模块（打印机连接、TSPL 指令发送）
├── label-api/          # API 控制器层（REST 接口）
├── label-server/       # 启动模块（Spring Boot 主入口）
└── label-web/          # 前端项目（Vue 3 + Element Plus）
```

---

## 🖨️ 打印管线（统一渲染）

### 核心架构

```
┌─────────────────────────────────────────────────┐
│              统一渲染管线（LabelImageRenderer）      │
│                                                   │
│   design JSON + 数据 + fieldMapping               │
│        │                                          │
│        ▼                                          │
│   Graphics2D 渲染 → BufferedImage                 │
│        │                                          │
│        ├────→ renderToPng() → PNG 字节 → 浏览器预览  │
│        │                                          │
│        └────→ renderToTspl() → TSPL GRAPH 指令      │
│                    │                              │
│                    ▼                              │
│            raw TCP 9100 → 打印机                   │
└─────────────────────────────────────────────────┘
```

### 关键特性

- **预览和打印使用同一套代码**：Graphics2D 渲染为 BufferedImage，再分别输出 PNG（预览）或 GRAPH 指令（打印）
- **TSPL GRAPH 指令**：将整个标签位图转为十六进制像素数据，通过 `GRAPH 0,0,w,h,hexdata` 发送到打印机
- **DPI 自适应**：预览使用 96 DPI（匹配浏览器 CSS），打印使用打印机实际 DPI（203/300/600）
- **Raw TCP 通信**：直接通过 Socket(ip, 9100) 发送文本指令，不依赖厂商 SDK

### 支持的标签元素

| 元素 | 渲染方式 | TSPL 输出 |
|------|---------|-----------|
| 文本 | Graphics2D 绘制 | GRAPH（位图） |
| 条码（CODE128/39/93/EAN13 等） | ZXing 编码 → Graphics2D 画点 | GRAPH（位图） |
| 二维码（QR Code） | ZXing 编码 → Graphics2D 画点 | GRAPH（位图） |
| 线条/矩形/圆形 | Graphics2D 几何绘制 | GRAPH（位图） |
| 表格 | Graphics2D 网格线 | GRAPH（位图） |
| 日期时间 | Java 格式化当前时间 | GRAPH（位图） |
| 序列号 | 自动编号 | GRAPH（位图） |

---

## 🔗 核心 API

### 打印机管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/printers` | 获取所有打印机 |
| GET | `/api/v1/printers/{id}` | 获取单个打印机 |
| GET | `/api/v1/printers/discover` | 发现网络打印机 |
| POST | `/api/v1/printers/add-by-ip` | 通过 IP 添加打印机 |
| DELETE | `/api/v1/printers/{id}` | 删除打印机 |
| POST | `/api/v1/printers/{id}/test` | 测试连接 |
| GET | `/api/v1/printers/{id}/status` | 获取状态 |
| POST | `/api/v1/printers/{id}/calibrate` | 校准打印机 |

### 模板管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/templates` | 获取所有模板 |
| POST | `/api/v1/templates` | 创建模板 |
| PUT | `/api/v1/templates/{id}` | 更新模板 |
| DELETE | `/api/v1/templates/{id}` | 删除模板 |
| POST | `/api/v1/templates/{id}/render` | 渲染预览图片（PNG） |

### 数据源管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/datasources` | 获取所有数据源 |
| POST | `/api/v1/datasources` | 创建数据源 |
| POST | `/api/v1/datasources/{id}/execute` | 执行查询 |

### 打印任务
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/print-jobs/direct-print` | 直接打印（同步） |
| POST | `/api/v1/print-jobs` | 提交任务（异步队列） |
| GET | `/api/v1/print-jobs` | 查询任务列表 |
| POST | `/api/v1/print-jobs/{id}/cancel` | 取消任务 |

---

## 🔧 配置信息

### 服务配置
- **端口**: 8090
- **数据库**: PostgreSQL @ /label_db
- **Redis**: :6379 (db=5)

### 打印机连接
- **协议**: TSPL over TCP
- **端口**: 9100
- **DPI**: 203 / 300 / 600（自动检测或数据库配置）
- **超时**: 连接 5s / 打印 10s

### 字体管理
- 无系统字体预装，完全由用户上传
- 支持 `.ttf` / `.ttc` 格式，最大 50MB
- 存储路径: `~/.cenlak/fonts/`
- 上传后自动注册到 JVM 并刷新缓存

---

## 📊 渲染 DPI 换算

```
预览: 96 DPI  →  1mm = 3.78px  (匹配浏览器 CSS)
打印: 203 DPI →  1mm = 8 dots  (常见条码打印机)
打印: 300 DPI →  1mm = 11.8 dots
打印: 600 DPI →  1mm = 23.6 dots

公式: dots = round(mm × dpi / 25.4)
```

---

## 🗄️ 数据库表

| 表名 | 说明 |
|------|------|
| `label_template` | 标签模板（含 design JSON 和字段映射） |
| `datasource_config` | 数据源配置（数据库连接/Excel） |
| `printer_info` | 打印机信息（IP、端口、DPI、在线状态） |
| `print_job` | 打印任务记录 |
| `label_font` | 用户上传字体 |
| `db_connection` | 数据库连接配置 |
| `datasource_category` | 数据源分类 |

---

## 🚀 部署

```bash
# 后端
cd /home/shkjadmin/projects/label-data-service
mvn package -DskipTests -pl label-server -am
java -jar label-server/target/label-server-1.0.0-SNAPSHOT.jar

# 前端
cd label-web
npm install
npx vite build
```

---

## 📝 Git 分支

- **分支**: `label-data-service`
- **远程**: ``
- **最近提交**:
  - `c1409de` — 移除系统字体预装，仅支持用户上传字体
  - `a302523` — 字体回退链适配服务器环境
  - `3409d2a` — 前端预览文本不再被截断
  - `a38e401` — 统一渲染管线（预览和打印同一套代码）

---

## ⚠️ 重要决策记录

1. **TSPL 协议**: 打印机品牌为 TSC，使用 TSPL 协议而非 ZPL
2. **统一渲染管线**: 预览和打印共用 Graphics2D 渲染，确保预览图与实际打印一致
3. **RAW TCP 通信**: 不依赖厂商 SDK，直接 Socket 9100 端口发送文本指令
4. **无系统字体预装**: 字体完全由用户上传管理，避免环境差异
5. **变量替换规则**: 有值替换，无值保留 `{{var}}` 占位符（前后端一致）

---

*最后更新: 2026-04-14*