140 lines
5.5 KiB
Markdown
140 lines
5.5 KiB
Markdown
|
# 报表打印系统架构与使用说明
|
|||
|
|
|
|||
|
|
本文档详细介绍了当前报表打印系统的架构设计、核心组件及其使用方法。
|
|||
|
|
|
|||
|
|
## 1. 架构设计概览
|
|||
|
|
|
|||
|
|
本系统采用 **Provider 模式** 与 **流式任务构建 (Builder Pattern)** 相结合的设计，旨在实现报表生成的解耦、灵活配置与高扩展性。
|
|||
|
|
|
|||
|
|
### 核心组件
|
|||
|
|
|
|||
|
|
1. **IReportDataProvider (报表数据提供者)**
|
|||
|
|
* **职责**：定义单一报表的元数据（模版、标题、类型）和数据准备逻辑。
|
|||
|
|
* **优势**：将业务逻辑从 Service 层剥离，每个报表对应一个 Provider，互不干扰，易于维护。
|
|||
|
|
* **关键方法**：
|
|||
|
|
* `getReportType()`: 唯一标识（如 `APPLICATION_FORM`）。
|
|||
|
|
* `prepareData(params)`: 准备模版所需的数据。
|
|||
|
|
* `getCoverProviderType()`: 定义关联的封面类型（支持自动封面）。
|
|||
|
|
|
|||
|
|
2. **ReportPrintJob (打印任务构建器)**
|
|||
|
|
* **职责**：负责组装打印任务。它像一条流水线，可以按需添加封面、报表片段、设置公章/水印等。
|
|||
|
|
* **特性**：
|
|||
|
|
* **链式调用**：`createJob().addCover().addBatch().render()`。
|
|||
|
|
* **混合布局**：自动处理横向 (Landscape) 与纵向 (Portrait) 页面的合并。
|
|||
|
|
* **上下文注入**：支持注入 CompanyId 用于公章/水印生成。
|
|||
|
|
|
|||
|
|
3. **ReportRenderService (渲染服务)**
|
|||
|
|
* **职责**：底层的渲染引擎。
|
|||
|
|
* **功能**：
|
|||
|
|
* 解析 Velocity 模版。
|
|||
|
|
* 调用 Gotenberg 进行 HTML 转 PDF。
|
|||
|
|
* 处理水印 (Watermark) 和电子公章 (Seal)。
|
|||
|
|
* 合并多个 PDF 片段。
|
|||
|
|
|
|||
|
|
## 2. 现有报表类型
|
|||
|
|
|
|||
|
|
目前系统已实现的 Provider 如下：
|
|||
|
|
|
|||
|
|
| 报表类型 (Type) | Provider 类 | 描述 |
|
|||
|
|
| :--- | :--- | :--- |
|
|||
|
|
| `APPLICATION_FORM` | `DriverApplicationFormProvider` | 驾驶员应聘申请表 |
|
|||
|
|
| `ID_CARD_SCAN` | `IdCardScanProvider` | 身份证扫描件 |
|
|||
|
|
| `DRIVER_LICENSE_COPY` | `DriverLicenseCopyProvider` | 驾驶证复印件 |
|
|||
|
|
| `QUALIFICATION_CERTIFICATE_COPY` | `QualificationCertificateCopyProvider` | 从业资格证复印件 |
|
|||
|
|
| `QUALIFICATION_REVIEW` | `QualificationReviewProvider` | 资格审查及技能考核登记表 |
|
|||
|
|
| `ACCIDENT_RECORD` | `AccidentRecordProvider` | 安全行车事故记录 (横向) |
|
|||
|
|
| `VIOLATION_RECORD` | `ViolationRecordProvider` | 违章记录 (横向) |
|
|||
|
|
| `ANNUAL_ASSESSMENT_RECORD` | `AnnualAssessmentRecordProvider` | 年度考核记录 |
|
|||
|
|
| `MEDICAL_EXAMINATION_REPORT` | `MedicalExaminationReportProvider` | 体检报告 |
|
|||
|
|
| `REWARD_PUNISHMENT_RECORD` | `RewardPunishmentRecordProvider` | 奖惩记录表 |
|
|||
|
|
|
|||
|
|
## 3. 使用方法 (开发指南)
|
|||
|
|
|
|||
|
|
### 3.1 创建新报表
|
|||
|
|
|
|||
|
|
1. **定义 Provider**：
|
|||
|
|
新建一个类实现 `IReportDataProvider`，并注册为 Spring Bean (`@Component`)。
|
|||
|
|
```java
|
|||
|
|
@Component
|
|||
|
|
public class MyReportProvider implements IReportDataProvider {
|
|||
|
|
@Override
|
|||
|
|
public String getReportType() { return "MY_REPORT"; }
|
|||
|
|
|
|||
|
|
@Override
|
|||
|
|
public String getTemplateCode() { return "templates/my/report.html.vm"; }
|
|||
|
|
|
|||
|
|
@Override
|
|||
|
|
public Map<String, Object> prepareData(Map<String, Object> params) {
|
|||
|
|
// 准备数据...
|
|||
|
|
return Map.of("data", "value");
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
2. **创建 Velocity 模版**：
|
|||
|
|
在 `src/main/resources/templates/my/report.html.vm` 中编写 HTML。
|
|||
|
|
|
|||
|
|
### 3.2 调用打印服务
|
|||
|
|
|
|||
|
|
在业务 Service 中注入 `ReportRenderService` 和 `providerMap`，然后使用链式调用：
|
|||
|
|
|
|||
|
|
#### 场景 A：单个报表打印 (带自动封面)
|
|||
|
|
|
|||
|
|
```java
|
|||
|
|
public byte[] printMyReport(List<String> ids) {
|
|||
|
|
// 1. 获取 Provider
|
|||
|
|
IReportDataProvider provider = providerMap.get("MY_REPORT");
|
|||
|
|
|
|||
|
|
// 2. 构建任务
|
|||
|
|
return reportRenderService.createJob(providerMap::get) // 传入查找器以支持自动封面
|
|||
|
|
.withCompanyId(companyId) // 设置公司ID（用于公章）
|
|||
|
|
.addCover(provider) // 自动添加关联封面
|
|||
|
|
.addBatch(provider, ids, "id") // 批量添加报表内容
|
|||
|
|
.useSeal(true) // 启用公章
|
|||
|
|
.render(); // 渲染并返回 PDF
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 场景 B：一键打印 (多报表合并)
|
|||
|
|
|
|||
|
|
```java
|
|||
|
|
public byte[] printAll(List<String> driverIds, List<String> types) {
|
|||
|
|
var job = reportRenderService.createJob(providerMap::get)
|
|||
|
|
.withCompanyId(companyId)
|
|||
|
|
.useSeal(false); // 全局公章开关
|
|||
|
|
|
|||
|
|
for (String id : driverIds) {
|
|||
|
|
// 1. 为每个驾驶员添加一个独立封面
|
|||
|
|
job.addCover("COMMON_COVER", Map.of(
|
|||
|
|
"title", "驾驶员档案",
|
|||
|
|
"subtitle", "张三"
|
|||
|
|
));
|
|||
|
|
|
|||
|
|
// 2. 依次添加选中的报表
|
|||
|
|
for (String type : types) {
|
|||
|
|
job.add(providerMap.get(type), Map.of("driverId", id));
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
return job.render();
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.3 进阶配置
|
|||
|
|
|
|||
|
|
* **横向布局**：在 Provider 中重写 `isLandscape()` 返回 `true`，或者在 Job 中调用 `.isLandscape(true)` (通常由 Provider
|
|||
|
|
决定)。
|
|||
|
|
* **自定义封面**：Provider 可重写 `getCoverProviderType()` 指定特定封面，或重写 `getCoverData()` 自定义封面参数。
|
|||
|
|
* **水印控制**：`job.useWatermark(true).watermarkText("自定义水印")`。
|
|||
|
|
|
|||
|
|
## 4. 模版工具支持
|
|||
|
|
|
|||
|
|
模版中内置了 `$tool` 工具类 (`ReportVelocityTool`)，提供常用功能：
|
|||
|
|
|
|||
|
|
* `$tool.getDictLabel('type', value)`: 字典翻译
|
|||
|
|
* `$tool.formatDate(date, 'yyyy-MM-dd')`: 日期格式化
|
|||
|
|
* `$tool.getOssUrls(urlStr)`: 解析 OSS 图片链接
|
|||
|
|
* `$tool.numberToChinese(num)`: 数字转中文大写
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
*文档生成日期：2026-03-01*
|