100 lines
4.4 KiB
Markdown
100 lines
4.4 KiB
Markdown
# 车辆档案打印功能开发规范
|
||
|
||
## 1. 核心技术栈
|
||
* **模板引擎**: Velocity (`.html.vm`)
|
||
* **PDF生成**: Gotenberg (HTML转PDF)
|
||
* **水印处理**: PDFBox (`PdfWatermarkUtil`)
|
||
* **存储**: OSS (图片URL处理)
|
||
|
||
## 2. 通用样式与布局规范 (Template)
|
||
所有打印模板位于 `src/main/resources/templates/vehicle/` 目录下。
|
||
|
||
### 2.1 页面布局
|
||
* **纸张设置**: A4 纵向 (Vertical)。
|
||
* **容器宽度**: `.page-content` 宽度建议设置为 **99%** 或留出微小边距，防止浏览器预览或打印时**右侧边框**被截断。
|
||
* **表格样式**:
|
||
* 必须使用标准 HTML `<table>`。
|
||
* 边框合并: `border-collapse: collapse;`。
|
||
* 边框线条: 统一使用细线 (`1px solid #000` 或 `#333`)，避免出现粗细不一的视觉效果。
|
||
* **禁止**使用 `<div>` 模拟表格边框，防止分页截断错位。
|
||
|
||
### 2.2 图片展示 (核心优化)
|
||
* **容器**: 图片必须放置在表格单元格 (`<td>`) 内部。
|
||
* **布局方式**: 使用 Flex 布局 (`display: flex; flex-wrap: wrap;`)。
|
||
* **动态宽度逻辑** (Velocity):
|
||
* **单张图片**: 宽度设为 **98%** (占满整行)，居中显示。
|
||
* **多张图片**: 宽度设为 **48%** (一行两张)，保留 1% 间距。
|
||
* **样式代码参考**:
|
||
```html
|
||
<div style="display: flex; flex-wrap: wrap; justify-content: flex-start;">
|
||
#if($images.size() == 1)
|
||
#set($widthStyle = "width: 98%;")
|
||
#else
|
||
#set($widthStyle = "width: 48%;")
|
||
#end
|
||
#foreach($img in $images)
|
||
<div style="$!widthStyle height: 350px; margin: 1%; display: flex; align-items: center; justify-content: center; border: 1px solid #eee;">
|
||
<img src="$!img" style="max-width: 100%; max-height: 100%; object-fit: contain;" />
|
||
</div>
|
||
#end
|
||
</div>
|
||
```
|
||
|
||
### 2.3 水印设置
|
||
* **位置调整**: 为防止 A4 纵向打印时最后一行水印被截断，Y 轴偏移量需增加。
|
||
* **代码位置**: `PdfWatermarkUtil.java`
|
||
* **参数**: `y + 100` (原为 `y + 50`)。
|
||
|
||
---
|
||
|
||
## 3. 后端接口开发规范 (Java)
|
||
|
||
### 3.1 接口定义
|
||
* **Controller**: `VehicleFileController`
|
||
* **Service**: `IVehicleFilePrintService`
|
||
* **请求方式**: `POST` (支持批量打印)
|
||
* **参数**: `List<Long> vehicleIds`
|
||
* **响应**: `void` (写入 `HttpServletResponse` 流，Content-Type: `application/pdf`)
|
||
|
||
### 3.2 数据查询逻辑
|
||
所有打印业务需遵循“**取最新一条记录**”的原则：
|
||
1. **查询条件**: `vehicle_id`
|
||
2. **排序**: 按业务时间或完成时间 **倒序** (`orderByDesc`)
|
||
3. **限制**: 取第一条 (`LIMIT 1`)
|
||
4. **容错**:
|
||
* 如果记录不存在 (`null`)，跳过该车辆 (`continue`)。
|
||
* **数据补全**: 如果业务表中缺失关键信息（如 `plateNumber`），**必须**回查 `hot_vehicle` 基础表进行补全。
|
||
|
||
### 3.3 图片URL处理
|
||
* 数据库中图片通常以逗号分隔字符串存储 (`img1.jpg,img2.jpg`)。
|
||
* **必须**使用 `splitUrls` 方法分割为 `List<String>`。
|
||
* **必须**通过 `ossService.selectUrlByIds` 处理（如需签名或转换）。
|
||
|
||
---
|
||
|
||
## 4. 具体业务模块规范
|
||
|
||
### 4.1 车辆年审报告 (Inspection Report)
|
||
* **接口地址**: `/vehicle/file/inspectionReport`
|
||
* **数据源表**: `hot_vehicle_annual_review`
|
||
* **关键字段**: `review_date` (年审日期), `image_urls` (附件)
|
||
* **模板文件**: `inspectionReport.html.vm`
|
||
* **特殊要求**:
|
||
* 评定等级需转义 (1=一级, 2=二级)。
|
||
* 所有附件图片需放入表格行中。
|
||
|
||
### 4.2 车辆二级维护记录 (Maintenance Record)
|
||
* **接口地址**: `/vehicle/file/maintenanceRecord`
|
||
* **数据源表**: `hot_vehicle_maintenance`
|
||
* **关键字段**:
|
||
* `finish_time` (完成时间 - 排序依据)
|
||
* `entry_inspect_image_urls` (进厂检验单)
|
||
* `process_inspect_image_urls` (过程检验单)
|
||
* `final_inspect_image_urls` (竣工检验单)
|
||
* `factory_cert_image_urls` (出厂合格证)
|
||
* **模板文件**: `maintenanceRecord.html.vm`
|
||
* **特殊要求**:
|
||
* **纯表格布局**: 整个页面（包括标题、信息、四类图片）全部在 `<table>` 内部。
|
||
* **标题样式**: 表格内的分类标题（如“竣工检验单”）**不需要**背景色，字体加粗居中。
|
||
* **图片布局**: 严格执行“单张全宽、多张半宽”的动态布局规则。
|