# hiprint-spring-boot

**Repository Path**: zkool/hiprint-spring-boot

## Basic Information

- **Project Name**: hiprint-spring-boot
- **Description**: 基于 hiprint 打印引擎的 Spring Boot 组件（starter），提供「打印模板管理 + 可选登录鉴权」能力，可作为一个独立模块引入任意 Spring Boot 项目，开箱即用。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-09-18
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# hiprint-spring-boot

基于 [hiprint](http://hiprint.io/) 、[vue-plugin-hiprint](https://gitee.com/CcSimple/vue-plugin-hiprint) 打印引擎的 **Spring Boot 组件（starter）**，提供「打印模板管理 + 可选登录鉴权」能力，可作为一个独立模块引入任意 Spring Boot 项目，开箱即用。

- 模板管理 REST API（分页查询 / 详情 / 新增 / 修改 / 删除），数据落关系型数据库（Spring Data JDBC）
- 内置可视化设计器页面与模板管理页面
- 可选安全：内置账号密码登录（默认关闭），或对接宿主统一登录 / SSO
- token 鉴权机制：支持 `?token=` 页面参数与请求头两种传递方式

> ⚠️ **声明**：本项目部分内容由 **AI 辅助生成**，如有错误或不妥之处，请联系作者 **QQ：2459501893** 纠正，感谢理解与支持。
>
> 💬 **技术交流**：点击群号 [671213642](https://qm.qq.com/q/xLZ6ofjqRG) 加入QQ群聊

> 演示地址：<https://zkool.github.io/html/hiprint/index.html>

---

## 快速开始

按你的 Spring Boot 版本选择对应依赖：

**Spring Boot 2.x**

```xml
<dependency>
    <groupId>io.github.zkool</groupId>
    <artifactId>hiprint-spring-boot-core</artifactId>
    <version>1.0.0</version>
</dependency>
```

**Spring Boot 3.x / 4.x**

```xml
<dependency>
    <groupId>io.github.zkool</groupId>
    <artifactId>hiprint-spring-boot3-core</artifactId>
    <version>1.0.0</version>
</dependency>
```

只要依赖在 classpath 上即自动装配（`HiPrintAutoConfiguration` 通过 `@ComponentScan` / `@EnableJdbcRepositories` 完成），**无需任何额外注解**。
需准备 `hiprint_template` 表（建表脚本见仓库 `sql/` 目录）。

> 启动项目后即可访问：http://host:port/hiprint/index.html
> 
> 也可将 **hiprint/index.html** 配置到你业务系统中的菜单管理中。

---

## 后端对接指南

### 1. 配置项（`hiprint.*`）

```yaml
hiprint:
  enabled: true                 # 是否启用打印组件（默认 true）
  max-page-size: 500           # 单页最大条数，防止一次拉取过多
  default-user: system         # 审计字段 create_by / update_by 的默认值
  security:
    enabled: false             # 是否开启登录鉴权（默认 false，关闭时与旧版一致，不拦截任何请求）
    username: hiprint          # 内置登录用户名
    password: hiprint@123      # 内置登录密码
    token-expire-seconds: 1800 # token 有效期（秒，默认 30 分钟，采用滑动过期）
```

### 2. 安全模式

| 模式 | 触发条件 | 行为 |
| --- | --- | --- |
| 关闭（默认） | `security.enabled=false` | 不拦截任何请求 |
| 内置模式 | `security.enabled=true` 且宿主未提供 `HiPrintTokenService` | 提供 `/hiprint/login.html` 登录页与 `/hiprint/api/login`、`/hiprint/api/logout`；页面未登录重定向登录页，接口未登录返回 401 JSON |
| 宿主模式 | 宿主提供 `HiPrintTokenService` Bean | 内置登录接口与内置 token 服务均不注册，由宿主接管；页面/接口未登录均返回 401 JSON，由宿主前端自行处理跳转 |

> token 采用内存存储（进程级，重启即失效），适用于演示与轻量防护；活跃会话在有效期过半后自动顺延（滑动过期），避免使用中突然被踢下线。

### 3. 自定义登录（宿主模式）

只需提供一个 `HiPrintTokenService` Bean，即可接管鉴权：

```java
public interface HiPrintTokenService {
    boolean verifyToken(String token);     // 校验 token 是否有效
    String getUsername(String token);      // 取用户名（token 有效时）
    List<String> getPermissions(String token); // 取权限列表（token 有效时）
}
```

```java
@Configuration
public class MySecurityConfig {
    @Bean
    public HiPrintTokenService hiPrintTokenService() {
        return new MyTokenServiceImpl(); // 对接你的统一登录 / SSO
    }
}
```

```json
//通过实现扩展接口HiPrintTokenService，来实现与集成系统对接登录token、操作权限。可参考如下两个实现

//DefaultHiPrintTokenService：内置默认实现
io.github.zkool.hiprint.security.DefaultHiPrintTokenService implements HiPrintTokenService

//MyHiPrintTokenService：集成系统对接示例实现
io.github.zkool.hiprint.app.MyHiPrintTokenService implements HiPrintTokenService
```

### 4. 模板 REST API

基础路径：`/hiprint/api/templates`

| 方法 | 路径 | 说明 | 所需权限（内置模式） |
| --- | --- | --- | --- |
| GET | `/hiprint/api/templates` | 分页列表 | `hiprint:template:view` |
| GET | `/hiprint/api/templates/{templateCode}` | 模板详情 | `hiprint:template:view` |
| POST | `/hiprint/api/templates` | 新增模板 | `hiprint:template:create` |
| PUT | `/hiprint/api/templates/{templateCode}` | 更新模板（乐观锁） | `hiprint:template:update` |
| DELETE | `/hiprint/api/templates/{templateCode}` | 删除模板 | `hiprint:template:delete` |

**接口权限标识符**：`HiPrintTemplateController` 的 5 个接口方法均标注了 `@HiPrintPermission`，共涉及 4 个权限标识符（`hiprint:template:view` 被「列表」与「详情」两个查询接口共用）：

| 权限标识符 | 保护接口 | 含义 |
| --- | --- | --- |
| `hiprint:template:view` | `GET /api/templates`、`GET /api/templates/{templateCode}` | 模板查看（只读）：分页查询模板列表、获取模板详情。设计器拉取 `templateJson` 渲染打印依赖此权限，**三方系统对接主入口建议至少具备该权限** |
| `hiprint:template:create` | `POST /api/templates` | 模板新增：创建模板（写入 `templateJson` / `demoData` / 模板名称 / 备注等） |
| `hiprint:template:update` | `PUT /api/templates/{templateCode}` | 模板修改：更新模板内容，设计器「保存」即走此接口（含乐观锁 `version` 校验） |
| `hiprint:template:delete` | `DELETE /api/templates/{templateCode}` | 模板删除：删除指定模板 |

> **校验规则**：`@HiPrintPermission` 仅当 `hiprint.security.enabled=true` 时生效（关闭时拦截器直接放行）。`HiPrintAuthInterceptor` 在请求进入方法前校验：当前 token 的权限列表需**包含注解要求的全部权限**，或包含 `*` 超级权限，否则返回 `403`。内置默认账号拥有 `*` 超级权限，故内置模式下默认账号不受限制；宿主模式下由你自己的 `HiPrintTokenService.getPermissions(...)` 返回权限集合，字符串需与注解 `value()` **完全一致**（或含 `*`）方能放行。


登录接口（仅内置模式）：

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/hiprint/api/login` | 登录，返回 `{ token }` |
| POST | `/hiprint/api/logout` | 登出 |

- 统一返回体 `R<T>`：`{ "code": 200, "msg": "...", "data": ... }`，成功 `code=200`。
- 权限注解 `@HiPrintPermission("hiprint:template:view")` 仅在内置模式下生效；内置模式默认账号拥有 `*` 超级权限。宿主模式下权限由你自己的 `HiPrintTokenService.getPermissions(...)` 控制。
- 三方系统对接主入口是 `GET /hiprint/api/templates/{templateCode}`，拿到 `templateJson` 后在前端交给 hiprint 渲染并打印。

### 5. 模板实体 `HiPrintTemplate`

| 字段 | 说明 |
| --- | --- |
| `templateCode` | 业务编码，**表主键**，由调用方赋值（非自增） |
| `templateName` | 模板名称 |
| `templateJson` | hiprint 设计器导出的模板 JSON |
| `demoData` | 设计器演示数据 JSON（仅用于设计 / 预览） |
| `version` | 乐观锁版本号，由框架维护，更新冲突时抛 `OptimisticLockingFailureException` |
| `remark` / `createBy` / `createTime` / `updateBy` / `updateTime` | 审计字段 |

---

## 前端对接指南

### 1. 模板管理/模板设计器页面集成

业务系统配置模板管理页菜单：`/hiprint/index.html`

> 如果开启登录鉴权，则访问模板管理页时传递token参数 `/hiprint/index.html?token=xxx`。

### 2. 各业务单据页面取模板并打印（对接主流程）

```js
// 1. 拉取模板 JSON
fetch('/hiprint/api/templates/' + templateCode, {
    headers: { token: getBizToken() }
})
.then(r => r.json())
.then(res => {
    const templateJson = res.data.templateJson;
    // 2. 交给 vue-plugin-hiprint / hiprint 渲染并打印
    //    hiprint.init({ providers: [ { ... } ] });
    //    const hiprintTemplate = new hiprint.PrintTemplate({ template: templateJson });
    //    hiprintTemplate.print({}, { /* 打印数据 */ });
});
```

---

## 模块结构

| 模块 | 说明 |
| --- | --- |
| `hiprint-spring-boot-core` | 组件核心：自动配置、安全拦截、模板 REST API、前端静态资源 |
| `hiprint-spring-boot-app` | 可运行示例应用，含自定义 `HiPrintTokenService` 示例（`MyHiPrintTokenService`） |

> 更多文档：
> - 总体设计：[doc/01-总体设计.md](doc/01-总体设计.md)
> - 接口与对接指南：[doc/02-接口与对接指南.md](doc/02-接口与对接指南.md)
> - 发布到 Maven Central 的注意事项：[doc/03-boo3版发布指南.md](doc/03-boo3版发布指南.md)

---

## 许可证

本项目以 MIT License发布。