# Print Service 模块指引

## 数据库访问与中文注释约束

- 强制继承 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则；该节是分层、SQL 执行和方法/核心逻辑中文注释的唯一维护处，本模块不另设例外。

## 职责边界

- 本模块是无数据库的无状态 PDF 渲染服务；调用方传入完整 `labels[]` 或 `documents[]`，模块在内存中生成一次性多页 PDF 并同步返回。
- 不保存模板、任务、历史或文件，不连接数据库、File 服务或打印机，不反查或修正业务数据。
- `INBOUND_MARK_V1` 箱唛不接收或展示 SKU（包括一件代发箱唛），二维码仅编码稳定箱码；SKU 明细由一件代发 A4 托盘信息单展示，不能重新加入箱唛版面。
- 当前只有箱唛 `INBOUND_MARK_V1` 使用 100×100 mm；托盘标不得复用该模板。横向 A4 托盘模板包括 `FBA_PALLET_A4_LANDSCAPE_V1` 与 `PALLET_A4_LANDSCAPE_V1`，纵向 A4 包括 `DROPSHIP_PALLET_A4_V2`，其他 A4 单据为 `SEA_FREIGHT_SHIPPING_INSTRUCTION_A4_V1`、`BILL_OF_LADING_CONFIRMATION_A4_V1`、`DISPATCH_BILL_OF_LADING_A4_V2`。FBA 模板由国内和海外统一使用，每托一页，只展示 SCK8 等 FBA 仓码、完整托盘号的 Code 128 条码和完整托盘号；141 等内部编号保留在托盘号中。一件代发展示托盘 Code 128、目的仓、每页最多 10 行入仓码/客户昵称和 34 行 SKU，超量由调用方按同一托盘自动续页，不展示状态、重量或体积。新尺寸或布局必须使用新模板编码。

## 快速索引

| 功能 | 入口 |
|---|---|
| 调用方接入指南 | `README.md` |
| 国内/海外统一 FBA 托盘标 | `dto/FbaPalletPdfDtos.java`、`service/FbaPalletPdfService.java`、`renderer/FbaPalletRenderer.java`；内部 `/internal/print/v1/pdfs/fba-pallet-labels`，回归 `src/test/java/com/baiyue/print/service/FbaPalletPdfServiceTest.java` |
| 非 FBA 通用托盘标 | `dto/GenericPalletPdfDtos.java`、`service/GenericPalletPdfService.java`、`renderer/GenericPalletRenderer.java`；内部 `/internal/print/v1/pdfs/pallet-a4-labels` |
| 应用入口 | `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/dropship-pallet-a4-documents`、`/internal/print/v1/pdfs/freight-a4-documents`） |
| 内部令牌校验 | `controller/InternalServiceTokenGuard.java` |
| 请求与响应模型 | `dto/InboundMarkPdfDtos.java`、`dto/DropshipPalletA4PdfDtos.java`、`dto/FreightA4PdfDtos.java`、`dto/DispatchBolPdfDtos.java` |
| 固定模板与渲染 | `renderer/InboundMarkV1Renderer.java`、`renderer/DropshipPalletA4Renderer.java`、`renderer/FreightA4Renderer.java`、`renderer/DispatchBolRenderer.java`、`renderer/PdfQrRenderer.java`、`renderer/PdfUnits.java` |
| 请求校验与资源保护 | `controller/PrintRequestSizeFilter.java`、`service/InboundMarkPdfService.java`、`service/FreightA4PdfService.java`、`service/DispatchBolPdfService.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/test/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`；渲染变更同时核对页面尺寸、页数、页序、二维码或一维码反向解码和字体嵌入。