# 车辆档案打印功能开发规范

## 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>` 内部。
    *   **标题样式**: 表格内的分类标题（如“竣工检验单”）**不需要**背景色，字体加粗居中。
    *   **图片布局**: 严格执行“单张全宽、多张半宽”的动态布局规则。