4.4 KiB
4.4 KiB
车辆档案打印功能开发规范
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>模拟表格边框，防止分页截断错位。
- 必须使用标准 HTML
2.2 图片展示 (核心优化)
- 容器: 图片必须放置在表格单元格 (
<td>) 内部。 - 布局方式: 使用 Flex 布局 (
display: flex; flex-wrap: wrap;)。 - 动态宽度逻辑 (Velocity):
- 单张图片: 宽度设为 98% (占满整行)，居中显示。
- 多张图片: 宽度设为 48% (一行两张)，保留 1% 间距。
- 样式代码参考:
<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 数据查询逻辑
所有打印业务需遵循“取最新一条记录”的原则：
- 查询条件:
vehicle_id - 排序: 按业务时间或完成时间 倒序 (
orderByDesc) - 限制: 取第一条 (
LIMIT 1) - 容错:
- 如果记录不存在 (
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>内部。 - 标题样式: 表格内的分类标题（如“竣工检验单”）不需要背景色，字体加粗居中。
- 图片布局: 严格执行“单张全宽、多张半宽”的动态布局规则。
- 纯表格布局: 整个页面（包括标题、信息、四类图片）全部在