Print Service 模块指引

职责边界

本模块是无数据库的无状态 PDF 渲染服务；调用方传入完整 labels[] 或 documents[]，模块在内存中生成一次性多页 PDF 并同步返回。
不保存模板、任务、历史或文件，不连接数据库、File 服务或打印机，不反查或修正业务数据。
当前支持 INBOUND_MARK_V1（100mm x 100mm）、SEA_FREIGHT_SHIPPING_INSTRUCTION_A4_V1 和 BILL_OF_LADING_CONFIRMATION_A4_V1（均为 210mm x 297mm）；新尺寸或布局必须使用新模板编码，不得静默改变既有 V1。

功能	入口
调用方接入指南	`README.md`
应用入口	`src/main/java/com/baiyue/print/PrintServiceApplication.java`
健康状态 API	`controller/PrintHealthController.java`（`/api/platform/v1/print/status`）
内部 PDF API	`controller/InternalPdfController.java`（`/internal/print/v1/pdfs/inbound-marks`、`/internal/print/v1/pdfs/freight-a4-documents`）
内部令牌校验	`controller/InternalServiceTokenGuard.java`
请求与响应模型	`dto/InboundMarkPdfDtos.java`、`dto/FreightA4PdfDtos.java`
固定模板与渲染	`renderer/InboundMarkV1Renderer.java`、`renderer/FreightA4Renderer.java`、`renderer/PdfQrRenderer.java`、`renderer/PdfUnits.java`
请求校验与资源保护	`controller/PrintRequestSizeFilter.java`、`service/InboundMarkPdfService.java`、`service/FreightA4PdfService.java`、`service/PdfGenerationLimiter.java`
PDF 参数配置	`config/PrintPdfProperties.java`
接口契约	`src/main/resources/openapi/print-internal-v1.yaml`
字体及授权	`src/main/resources/fonts/NotoSansSC-Bold.ttf`、`src/main/resources/fonts/OFL.txt`
本地/Nacos 配置	`src/main/resources/application.yml`、`../config/nacos/{local,cn}/print-service.yml`
端到端与架构约束测试	`src/test/java/com/baiyue/print/acceptance/InboundMarkPdfAcceptanceTest.java`、`src/test/java/com/baiyue/print/service/FreightA4PdfServiceGenerationTest.java`、`src/test/java/com/baiyue/print/acceptance/PrintStatelessArchitectureTest.java`

内部 PDF 接口不加入 Gateway 公网路由；调用方必须先完成业务权限和数据范围校验，再携带共享内部令牌调用。
其他模块接入时先读 README.md 和 OpenAPI，在调用模块内声明 DTO 并从既有业务数据自动映射；不得依赖 Print 的 Java DTO，不得新增要求用户重复填写打印字段的表单。
A4 V1 每个 document 的 cargoRows 固定恰好 1 项且六个货物字段均非空；两个模板分别使用冻结的允许键与必填键，未知键、缺字段或额外货物行必须返回 A0422，不得静默忽略。
成功响应为 application/pdf，业务校验、鉴权和生成失败响应为 application/json；Controller 不得固定声明只产生 PDF，具体契约以 OpenAPI 为准。
不得重新引入已删除的 src/main/resources/db/print.sql，也不得引入数据源、MyBatis、MySQL、本地临时文件或异步任务队列；失败时整次请求失败，不返回部分 PDF。
中文字体必须从 classpath 加载并嵌入 PDF，不得依赖宿主机或容器系统字体；更新字体时同步归档授权文件。
修改后至少从父目录运行 mvn -pl print -am test；渲染变更同时核对页面尺寸、页数、页序、二维码反向解码和字体嵌入。