# FastPrintAgent

**Repository Path**: mingjiesoft/FastPrintAgent

## Basic Information

- **Project Name**: FastPrintAgent
- **Description**: FastPrint Agent - 轻量级企业打印服务中间件。支持HTTP同步 + MQTT异步双协议，解决跨语言本地及分布式远程打印难题，基于FastReport引擎，提供可视化无代码模板设计，适配内网本地、工控物联网、云端跨地域全场景打印。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 2
- **Created**: 2026-06-24
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastPrint Agent 专业打印服务解决方案

**告别端口映射 / 内网穿透 / 打印任务丢失**

**HTTP同步 + MQTT异步双协议打印中间件，完美适配本地内网 + 云端云服务 + 物联网分布式全场景**

---

## 一、项目简介

FastPrintAgent 是一款轻量、高性能的企业级分布式打印中间件，基于成熟 FastReport 报表引擎开发，核心能力就是解析 JSON 报文，自动转换为报表数据集，无需手写字段映射，在FastReport报表设计器进行拖拽方式设计报表。

内置 HTTP 同步 + MQTT 异步双通信协议，兼顾传统本地对接与物联网云端分布式场景，完美补齐传统HTTP打印存在的内网穿透依赖、动态IP适配差、离线断连丢任务、多设备集群管控困难等短板，一套中间件可同时覆盖局域网本地打印、云端远程打印、工控物联网设备打印全业务场景。

程序支持 Windows 系统服务常驻、桌面客户端双模式运行，彻底解决企业异构系统打印集成复杂、多网点打印分散、报表开发冗余繁琐、多打印机调度不便、云端远程打印连通性差等行业痛点。内置可视化无代码模板设计能力，支持单据在线打印、在线预览、PDF导出归档，是企业信息化、工业自动化、物联网边缘计算场景下通用的标准化打印服务。

---

## 二、HTTP 与 MQTT 协议核心对比（核心差异化优势）

传统HTTP接口在分布式门店、工厂工控、云端远程设备场景中存在天然缺陷，本项目原生集成MQTT协议，针对性解决各类网络与打印任务痛点，两者详细对比如下：

| 对比维度 | 传统 HTTP 打印（同步调用） | 本项目 MQTT 打印（异步推送） |
| --- | --- | --- |
| 网络环境要求 | 必须固定内网IP、需要端口映射、必须暴露端口，存在网络安全风险 | 无需固定IP、无需端口映射、无需暴露本机端口，内网设备联网更安全 |
| 连接模式 | 短连接，请求完成立即断开，网络波动极易丢失打印任务 | 长连接常驻，自动断线重连，支持离线消息缓存，打印任务永不丢失 |
| 使用场景 | 仅限本地局域网、同网段业务系统对接 | 跨网段、跨城市连锁门店、云端远程下发、工控机、物联网终端 |
| 运维难度 | 每台设备单独配置网络，多设备集群运维流程繁琐 | 统一MQTT Broker管理，可批量管控所有打印终端，运维成本极低 |
| 适用人群 | 本地单一系统、局域网内网快速对接需求 | 分布式项目、云端项目、工控物联网、全国多门店集群项目 |

---

## 三、核心优势

- **双协议兼容，无缝平滑切换**：同一套打印模板、同一套业务JSON数据，无需修改业务代码，即可自由切换HTTP、MQTT两种调用方式
- **业务解耦，聚焦核心开发**：将打印能力从业务系统中完全抽离，业务系统无需关注打印机硬件、报表模板、底层打印驱动细节，极简对接即可完成全流程打印
- **企业级统一打印中台**：支持多套异构系统统一接入，规避重复开发打印业务逻辑，实现全网打印机统一调度、统一运维、统一监控
- **全开发语言兼容**：支持 C++、C#、Java、Python、Delphi、PHP、Go 等主流开发语言，统一JSON格式入参，无需适配底层驱动
- **多打印机集中管控**：通过接口可按需指定目标打印机，适配分布式环境下多设备、多打印机一站式调度管理
- **零代码可视化模板设计**：内置FastReport可视化设计器，拖拽即可生成报表，原生支持条码、二维码、电子签章、金额大写自动汇总功能
- **双运行模式稳定可靠**：支持Windows系统服务7×24小时无人值守运行，搭配桌面可视化客户端，同时满足生产环境稳定性与日常调试便捷性需求
- **一站式内置调试工具箱**：集成JSON格式化、Base64图片互转、全量日志追溯、一键模板设计功能，大幅降低接口对接与问题排查成本

---

## 四、适用场景

### 4.1 HTTP 适配场景

- 企业内网ERP、进销存、OA办公、财务报销、CRM客户管理系统单据打印
- 本地单工位、单设备局域网内快速对接打印
- 老旧本地业务系统快速改造，快速接入标准化打印能力

### 4.2 MQTT 专属适配场景（核心优势场景）

- **工业工控**：MES生产系统、工位工控机、自动化生产线远程报表打印
- **连锁业态**：餐饮门店、商超零售、物流网点全国分布式远程打印
- **医疗政务**：HIS/LIS政务系统跨网段报表打印、PDF电子文件归档
- **物联网场景**：边缘设备、智能终端、无固定IP设备远程打印任务下发
- **分布式集群**：多厂区、多机房、跨地域设备统一打印调度管理
- **云服务对接**：阿里云 / 腾讯云 / 华为云原生集成，适配云ERP、云MES、云零售、云政务系统跨云远程打印

---

## 五、核心功能详情

### 5.1 标准化双协议接口能力

系统统一JSON入参格式，HTTP同步调用、MQTT异步消息复用同一套业务请求数据，支持直接打印、在线预览、PDF导出归档三大核心能力，业务端无需改动代码即可切换通信方式。

### 5.2 灵活部署能力

提供双重运行模式：Windows系统服务（开机自启、无人值守）、桌面可视化客户端。支持分布式多机器批量部署，完全适配企业长期稳定生产运行环境。

### 5.3 企业级报表能力

基于成熟FastReport报表内核开发，支持复杂嵌套表格、明细数据自动汇总、金额大写自动转换、Base64电子签章嵌入、自定义页面排版，完全满足企业正式单据规范化打印要求。

### 5.4 打印状态监测

实时判断打印机状态、是否离线暂停；识别卡纸、缺纸、打印完成等各类状态。

### 5.5 全能调试工具箱

- **JSON工具**：支持代码格式化、压缩、折叠，快速校验接口请求数据合法性
- **多媒体工具**：图片与Base64字符串双向互转，适配电子签章、业务凭证图片嵌入打印场景
- **模板工具**：一键唤起报表设计器，自动绑定测试数据，快速完成打印模板开发
- **日志工具**：全量留存HTTP、MQTT全部打印请求日志，双击日志可一键回填请求参数，快速复现线上问题

---

## 六、快速开始

### 6.1 安装部署步骤

1. 下载 FastPrint Agent 安装包，解压至电脑纯英文路径，避免中文目录导致程序乱码异常
2. 右键以管理员身份运行「安装服务.bat」脚本，自动完成Windows系统服务安装
3. 服务安装后自动启动，默认HTTP监听端口：9798，支持自定义端口修改
4. 部署完成后程序常驻系统右下角托盘，左键点击图标即可打开客户端主界面进行参数配置
5. 进入计算机服务列表，查看 ASuperService 服务状态为正在运行，即代表部署成功

### 6.2 HTTP 调用基础规范

- 请求方式：HTTP POST
- 请求头：Content-Type: application/json
- 基础服务接口地址：| http://127.0.0.1:9798/api/print |

#### 6.2.1 HTTP最简调用示例

```json
{
  "printApi":"print-report",
  "printTaskId":"123456789",
  "printTemp": "SalesOrder",
  "printer": "",
  "printCn": 1,
  "printData": {
    "title": "销售订单",
    "orderNo": "SO20240520001",
    "customer": "张三",
    "items": [
      {"product": "笔记本电脑", "quantity": 1, "price": 5999},
      {"product": "鼠标", "quantity": 2, "price": 99}
    ]
  }
}
```

### 6.3 MQTT 调用规范（新增，含3个专属参数）

通过MQTT主题下发完整JSON请求报文，新增三个专属业务参数，支持自定义操作类型、唯一任务编号、异步回执主题，实现打印任务全流程异步闭环回调。

#### 6.3.1 MQTT完整请求示例

```json
{
  "printApi": "print-report",
  "printTaskId": "123456789",
  "responseTopic": "print/receive/1234",
  "printTemp": "SalesOrder",
  "printer": "",
  "printCn": 1,
  "printData": {
    "title": "销售订单",
    "orderNo": "SO20240520001",
    "customer": "张三",
    "items": [
      {"product": "笔记本电脑", "quantity": 1, "price": 5999},
      {"product": "鼠标", "quantity": 2, "price": 99}
    ]
  }
}
```

#### 6.3.2 MQTT异步统一状态回执（自动推送至指定回执主题）

```json
{
  "printTaskId": "123456789",
  "state": "success",
  "code": 200
}
```

### 6.4 全功能示例查看

程序支持嵌套明细、金额自动汇总、金额大写转换、Base64电子签章渲染、PDF导出等全业务场景。打开 FastPrint Agent 客户端主界面 → 帮助 → JSON 示例，即可查看完整可直接复用的调试案例。

---

## 七、API 接口文档

### 7.1 HTTP 接口列表

| 接口功能 | 请求地址 |
| --- | --- |
| 直接打印、打印预览、PDF导出 | http://127.0.0.1:9798/api/print |

### 7.2 公共请求参数（HTTP/MQTT通用）

| 参数名 | 类型 | 必填 | 参数说明 |
| --- | --- | --- | --- |
| printApi | string | 是 | 对应接口执行能力：1.print-report(直接打印);2.show-report(打印预览);3.export-pdf(PDF导出) |
| printTaskId | string | 是 | 业务端自定义唯一任务编号，用于匹配回执消息，实现打印任务溯源 |
| printTemp | string | 是 | FastReport 模板文件名，存放于程序 PrintTemplate 目录，仅传文件名称，无需携带 `.frx` 后缀 |
| printer | string | 是 | 目标打印机全称；调用优先级：指定打印机 > 程序默认打印机 > 系统默认打印机 |
| printCn | int | 是 | 打印份数，默认值为1 |
| exportFileName | string | 否 | 仅PDF导出接口生效，填写本地文件完整保存路径；<br>1. 仅适配 export-pdf 接口；<br>2. 需要保证目标目录拥有文件写入权限；<br>3. 调用示例：`"D:\\PDF\\test.pdf"`；<br>4. 为避免PDF中文乱码、文字空白、字体缺失问题，模板设计时所有中文文本控件，必须选用微软雅黑、宋体、黑体等系统兼容中文字体，禁止使用无中文适配的特殊字体 |
| printData | object | 是 | 1. 业务打印核心数据集；<br>2. 字段后缀添加 `_base64image`，程序可自动识别并渲染Base64格式图片；<br>3. 支持中文键名，模板可视化设计时可读性更强；<br>4. printData节点下不支持二次嵌套对象（Object），可支持多层数组（Array）嵌套，具体规范可参考客户端内置JSON示例 |

### 7.3 MQTT 专属新增参数（MQTT版本v5.0）

| 参数名 | 类型 | 必填 | 参数说明 |
| --- | --- | --- | --- |
| responseTopic | string | 是 | 打印任务执行完成后，程序推送执行结果的自定义MQTT回执主题 |

### 7.4 统一响应参数说明

#### 7.4.1 成功响应

```json
{
  "printTaskId": "123456789",
  "state": "success",
  "code": 200
}
```

#### 7.4.2 失败响应

```json
{
  "printTaskId": "123456789",
  "state": "error",
  "code": 500,
  "message": "缺少printer字段"
}
```

---

## 八、客户端使用指南

### 8.1 系统托盘功能

程序后台常驻系统右下角托盘，无前台窗口占用系统资源，左键点击托盘图标即可快速打开客户端主操作界面。

### 8.2 主界面核心功能

- **打印调试**：内置JSON编辑器、Base64双向转换工具，支持一键打印、预览、PDF导出操作
- **模板设计**：自动绑定JSON测试数据，一键打开报表设计器，零代码快速制作打印模板
- **日志查询**：全量记录HTTP、MQTT全部打印请求日志，双击日志可一键回填参数，快速复现问题
- **参数设置**：支持自定义HTTP端口、默认打印机、MQTT服务连接地址与账号密码
- **帮助中心**：内置注册激活入口、全套JSON调用示例、完整图文接入教程

---

## 九、模板设计教程

1. 打开客户端主界面，切换至打印调试页面
2. 粘贴业务JSON请求数据，或直接读取历史请求日志回填参数
3. 点击模板设计按钮，程序自动生成空白报表模板并绑定对应业务数据集
4. 拖拽表格、条码、二维码、图片、文本等控件，完成报表页面布局排版
5. 将页面控件绑定printData内对应业务字段，调整字体、页边距、分页规则
6. 保存模板文件，文件自动存入程序PrintTemplate目录，接口直接填写模板名即可调用

---

## 十、授权注册说明

- **免费试用**：软件安装完成后自动激活30天全功能免费试用，无功能阉割、无接口调用次数限制
- **正式授权**：在客户端帮助页面复制设备机器码，联系商务人员获取注册码完成永久激活

| 版本类型 | 授权方式 | 适用场景 |
| --- | --- | --- |
| 标准版 | 单台电脑永久授权 | 个人开发者、小微企业、单台工控机独立部署场景 |
| 企业版（推荐） | 企业不限设备授权 | 多设备办公、工厂车间、连锁门店、分布式集群打印场景 |

---

## 十一、版本迭代规划

- **当前版本V1.2**：正式新增MQTT异步通信协议，支持异步消息下发、自定义回执主题、任务ID全链路溯源，补齐云端及物联网远程打印能力

---

## 十二、联系方式

正式授权采购、技术对接、功能定制、私有化部署相关咨询：

**倪杰 13506316883（微信同号）**

Star支持本项目，后续持续更新优化双协议打印核心能力