36 lines
3.4 KiB
Markdown
36 lines
3.4 KiB
Markdown
# 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`；渲染变更同时核对页面尺寸、页数、页序、二维码反向解码和字体嵌入。
|