baiyue-firstleg/print/AGENTS.md

Print Service 模块指引

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

• 强制遵守根 ../AGENTS.md 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 Controller → Service → Repository → Mapper，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
• 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 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；渲染变更同时核对页面尺寸、页数、页序、二维码或一维码反向解码和字体嵌入。