打印服务

2026-08-04 18:54:22 +08:00
parent b7d36d4766
commit dc2f844467
44 changed files with 2576 additions and 110 deletions
@@ -2,20 +2,32 @@

 ## 职责边界

- 本模块定义打印中心独立服务边界；当前只包含应用入口、状态接口、配置和数据库骨架。
- 打印模板版本、任务状态机、PDF/标签生成、重试和幂等尚未完整实现；开始扩展前必须先核对阶段需求，不从原型自动扩大范围。
+- 本模块是无数据库的无状态 PDF 渲染服务；调用方传入完整 `labels[]`，模块在内存中生成一次性多页 PDF 并同步返回。
+- 不保存模板、任务、历史或文件，不连接数据库、File 服务或打印机，不反查或修正业务数据。
+- 首版只支持 `INBOUND_MARK_V1` 和 `100mm x 100mm`；新尺寸或布局必须使用新模板编码，不得静默改变 V1。

 ## 快速索引

 | 功能 | 入口 |
 |---|---|
+| 调用方接入指南 | `README.md` |
 | 应用入口 | `src/main/java/com/baiyue/print/PrintServiceApplication.java` |
-| 当前状态 API | `controller/PrintHealthController.java`（`/api/platform/v1/print/status`） |
-| 数据库骨架 | `src/main/resources/db/print.sql` |
+| 健康状态 API | `controller/PrintHealthController.java`（`/api/platform/v1/print/status`） |
+| 内部 PDF API | `controller/InternalPdfController.java`（`/internal/print/v1/pdfs/inbound-marks`） |
+| 内部令牌校验 | `controller/InternalServiceTokenGuard.java` |
+| 请求与响应模型 | `dto/InboundMarkPdfDtos.java` |
+| 固定模板与二维码渲染 | `renderer/InboundMarkV1Renderer.java`、`renderer/PdfQrRenderer.java`、`renderer/PdfUnits.java` |
+| 请求校验与资源保护 | `controller/PrintRequestSizeFilter.java`、`service/InboundMarkPdfService.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/acceptance/PrintStatelessArchitectureTest.java` |

 ## 修改与验证

- 订单服务只应提交打印请求，不自行生成面单或操作打印机；生成文件通过 File 服务引用。
- 新增任务处理时设计明确的状态机、幂等键、失败重试、模板版本与权限边界。
- 当前无专属测试时，不为小改动引入整套新测试框架；至少从父目录运行 `mvn -pl print -am test` 并记录接口验证。
+- 内部 PDF 接口不加入 Gateway 公网路由；调用方必须先完成业务权限和数据范围校验，再携带共享内部令牌调用。
+- 成功响应为 `application/pdf`，业务校验、鉴权和生成失败响应为 `application/json`；Controller 不得固定声明只产生 PDF，具体契约以 OpenAPI 为准。
+- 不得重新引入已删除的 `src/main/resources/db/print.sql`，也不得引入数据源、MyBatis、MySQL、本地临时文件或异步任务队列；失败时整次请求失败，不返回部分 PDF。
+- 中文字体必须从 classpath 加载并嵌入 PDF，不得依赖宿主机或容器系统字体；更新字体时同步归档授权文件。
+- 修改后至少从父目录运行 `mvn -pl print -am test`；渲染变更同时核对页面尺寸、页数、页序、二维码反向解码和字体嵌入。