feat(file-print): support ocean booking documents

print/AGENTS.md

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

print/README.md

@@ -112,16 +112,20 @@ X-Request-Id: <optional-correlation-id>
 | `pageSpec.heightMm` | 是 | 固定数值 `297` |
 | `downloadFileName` | 否 | 最多 120 字符，必须以 `.pdf` 结尾，不得含路径或文件系统保留字符 |
 | `documents` | 是 | 1-2000 项；一个元素对应一页，按数组顺序生成 |
-| `documents[].fields` | 否 | 字符串字典，字段值允许换行，单值最多 4000 字符 |
-| `documents[].cargoRows` | 否 | 0-1 项；当前 V1 模板只渲染一行货物，调用方不得发送第二行 |
+| `documents[].fields` | 是 | 只能使用所选模板登记的键；未知键按 `A0422` 拒绝，字段值允许换行，单值最多 4000 字符 |
+| `documents[].cargoRows` | 是 | 恰好 1 项；六个货物字段均必填，空值或第二行按 `A0422` 拒绝 |
 
 托运书模板支持的完整 `fields` 键：`toCompany`、`issuerNameCn`、`issuerNameEn`、`issuerAddress`、`issuerPostalCode`、`issuerTel`、`issuerFax`、`shipper`、`consignee`、`notifyParty`、`picName`、`picTel`、`picFax`、`documentName`、`documentTel`、`documentFax`、`jobNumber`、`etdDate`、`serviceTerm`、`freightTerm`、`apCode`、`apName`、`cargoQuantity`、`transshipment`、`partialShipment`、`oceanVesselVoyage`、`portOfLoading`、`portOfDischarge`、`placeOfDelivery`、`totalPackagesInWords`、`remark`、`carrier`、`bookingAgent`、`printDate`。
 
+托运书必填键固定为：`toCompany`、`shipper`、`consignee`、`notifyParty`、`jobNumber`、`cargoQuantity`、`portOfLoading`、`portOfDischarge`、`placeOfDelivery`、`totalPackagesInWords`；其余登记键可选。
+
 提单确认件模板支持的完整 `fields` 键：`shipper`、`consignee`、`notifyParty`、`bookingNumber`、`ensAmsCutoffDate`、`customsCutoffDate`、`expectedDepartureDate`、`oceanVesselVoyage`、`portOfLoading`、`portOfDischarge`、`placeOfDelivery`、`finalDestination`、`serviceTerm`、`freightTerm`、`shipperLoadCountSeal`、`containerSpec`、`shippedOnBoard`、`draftText`、`totalPackagesInWords`、`containerSummary`、`notes`、`issuePlace`、`issueDate`。
 
-调用方 MUST 只发送所选模板支持的键。当前服务会忽略未知键而不报错，因此调用方必须通过单元测试固定字段映射，避免拼写错误生成缺字段 PDF。空值字段可以省略；不得为了填满模板要求用户重复录入订单、客户、航线或货物中已经存在的数据。
+提单确认件必填键固定为：`shipper`、`consignee`、`notifyParty`、`bookingNumber`、`portOfLoading`、`portOfDischarge`、`placeOfDelivery`、`serviceTerm`、`freightTerm`、`totalPackagesInWords`；其余登记键可选。
 
-未传 `downloadFileName` 时，服务使用 `freight-a4-documents-{requestId}.pdf`。请求体最大 2 MiB，PDF 最大 32 MiB。
+调用方 MUST 只发送所选模板支持的键；Print 会拒绝未知键、缺少必填键、空白必填值及不完整货物行，避免拼写错误生成缺字段 PDF。可选空值可以省略；不得为了填满模板要求用户重复录入订单、客户、航线或货物中已经存在的数据。
+
+未传 `downloadFileName` 时，托运书使用 `{jobNumber}-出口货物托运单.pdf`，提单确认件使用 `{bookingNumber}-提单确认件.pdf`。请求体最大 2 MiB，PDF 最大 32 MiB，成功 `Content-Type` 固定为 `application/pdf`。
 
 ## 3. 响应处理
 

print/src/main/java/com/baiyue/print/controller/InternalPdfController.java

@@ -68,13 +68,7 @@ public class InternalPdfController {
             @Valid @RequestBody FreightA4PdfDtos.Request request,
             HttpServletRequest servletRequest) {
         tokenGuard.verify(internalToken);
-        String requestId = CorrelationContext.requestId(servletRequest);
-        FreightA4PdfDtos.Request effectiveRequest = request;
-        if (request.downloadFileName() == null && requestId != null && !requestId.isBlank()) {
-            effectiveRequest = new FreightA4PdfDtos.Request(request.templateCode(), request.pageSpec(),
-                    "freight-a4-documents-" + requestId + ".pdf", request.documents());
-        }
-        FreightA4PdfService.GeneratedPdf pdf = freightA4PdfService.generate(effectiveRequest);
+        FreightA4PdfService.GeneratedPdf pdf = freightA4PdfService.generate(request);
         byte[] content = pdf.content();
 
         ContentDisposition disposition = ContentDisposition.attachment()

print/src/main/java/com/baiyue/print/service/FreightA4PdfService.java

@@ -27,7 +27,25 @@ public class FreightA4PdfService {
     private static final int MAX_FILE_NAME_CODE_POINTS = 120;
     private static final int MAX_FIELD_KEY_CODE_POINTS = 80;
     private static final int MAX_FIELD_VALUE_CODE_POINTS = 4000;
-    private static final int MAX_CARGO_ROWS = 50;
+    private static final Set<String> SHIPPING_FIELDS = Set.of(
+            "toCompany", "issuerNameCn", "issuerNameEn", "issuerAddress", "issuerPostalCode",
+            "issuerTel", "issuerFax", "shipper", "consignee", "notifyParty", "picName", "picTel",
+            "picFax", "documentName", "documentTel", "documentFax", "jobNumber", "etdDate",
+            "serviceTerm", "freightTerm", "apCode", "apName", "cargoQuantity", "transshipment",
+            "partialShipment", "oceanVesselVoyage", "portOfLoading", "portOfDischarge",
+            "placeOfDelivery", "totalPackagesInWords", "remark", "carrier", "bookingAgent", "printDate");
+    private static final Set<String> SHIPPING_REQUIRED_FIELDS = Set.of(
+            "toCompany", "shipper", "consignee", "notifyParty", "jobNumber", "cargoQuantity",
+            "portOfLoading", "portOfDischarge", "placeOfDelivery", "totalPackagesInWords");
+    private static final Set<String> BILL_FIELDS = Set.of(
+            "shipper", "consignee", "notifyParty", "bookingNumber", "ensAmsCutoffDate",
+            "customsCutoffDate", "expectedDepartureDate", "oceanVesselVoyage", "portOfLoading",
+            "portOfDischarge", "placeOfDelivery", "finalDestination", "serviceTerm", "freightTerm",
+            "shipperLoadCountSeal", "containerSpec", "shippedOnBoard", "draftText",
+            "totalPackagesInWords", "containerSummary", "notes", "issuePlace", "issueDate");
+    private static final Set<String> BILL_REQUIRED_FIELDS = Set.of(
+            "shipper", "consignee", "notifyParty", "bookingNumber", "portOfLoading",
+            "portOfDischarge", "placeOfDelivery", "serviceTerm", "freightTerm", "totalPackagesInWords");
     private static final BigDecimal A4_WIDTH_MM = new BigDecimal("210");
     private static final BigDecimal A4_HEIGHT_MM = new BigDecimal("297");
     private static final Set<String> SUPPORTED_TEMPLATES = Set.of(
@@ -99,35 +117,45 @@ public class FreightA4PdfService {
 
         List<FreightA4PdfDtos.Document> documents = new ArrayList<>(request.documents().size());
         for (int index = 0; index < request.documents().size(); index++) {
-            documents.add(normalizeDocument(request.documents().get(index), index));
+            documents.add(normalizeDocument(templateCode, request.documents().get(index), index));
         }
-        return new NormalizedRequest(templateCode, normalizeFileName(request.downloadFileName()),
+        return new NormalizedRequest(templateCode,
+                normalizeFileName(request.downloadFileName(), templateCode, documents.get(0)),
                 List.copyOf(documents));
     }
 
-    private FreightA4PdfDtos.Document normalizeDocument(FreightA4PdfDtos.Document document, int index) {
+    private FreightA4PdfDtos.Document normalizeDocument(String templateCode,
+                                                        FreightA4PdfDtos.Document document, int index) {
         if (document == null) {
             invalid("documents[" + index + "] is required");
         }
         Map<String, String> fields = new LinkedHashMap<>();
         if (document.fields() != null) {
+            Set<String> allowed = FreightA4PdfDtos.SHIPPING_INSTRUCTION_TEMPLATE.equals(templateCode)
+                    ? SHIPPING_FIELDS : BILL_FIELDS;
             for (Map.Entry<String, String> entry : document.fields().entrySet()) {
                 String key = normalizeRequiredLine(entry.getKey(), field(index, "fields key"));
                 if (key.codePointCount(0, key.length()) > MAX_FIELD_KEY_CODE_POINTS) {
                     invalid(field(index, "fields." + key) + " key is too long");
                 }
+                if (!allowed.contains(key)) {
+                    invalid(field(index, "fields." + key) + " is not supported by " + templateCode);
+                }
                 fields.put(key, normalizeOptionalBlock(entry.getValue(), field(index, "fields." + key)));
             }
         }
-        List<FreightA4PdfDtos.CargoRow> rows = new ArrayList<>();
-        if (document.cargoRows() != null) {
-            if (document.cargoRows().size() > MAX_CARGO_ROWS) {
-                invalid(field(index, "cargoRows") + " must not contain more than " + MAX_CARGO_ROWS + " items");
-            }
-            for (int rowIndex = 0; rowIndex < document.cargoRows().size(); rowIndex++) {
-                rows.add(normalizeCargoRow(document.cargoRows().get(rowIndex), index, rowIndex));
+        Set<String> required = FreightA4PdfDtos.SHIPPING_INSTRUCTION_TEMPLATE.equals(templateCode)
+                ? SHIPPING_REQUIRED_FIELDS : BILL_REQUIRED_FIELDS;
+        for (String key : required) {
+            if (!fields.containsKey(key) || fields.get(key).isBlank()) {
+                invalid(field(index, "fields." + key) + " is required by " + templateCode);
             }
         }
+        List<FreightA4PdfDtos.CargoRow> rows = new ArrayList<>();
+        if (document.cargoRows() == null || document.cargoRows().size() != 1) {
+            invalid(field(index, "cargoRows") + " must contain exactly one item");
+        }
+        rows.add(normalizeCargoRow(document.cargoRows().get(0), index, 0));
         return new FreightA4PdfDtos.Document(Map.copyOf(fields), List.copyOf(rows));
     }
 
@@ -138,19 +166,22 @@ public class FreightA4PdfService {
         }
         String prefix = "documents[" + documentIndex + "].cargoRows[" + rowIndex + "].";
         return new FreightA4PdfDtos.CargoRow(
-                normalizeOptionalBlock(row.marksAndNos(), prefix + "marksAndNos"),
-                normalizeOptionalBlock(row.quantity(), prefix + "quantity"),
-                normalizeOptionalBlock(row.packaging(), prefix + "packaging"),
-                normalizeOptionalBlock(row.descriptionOfGoods(), prefix + "descriptionOfGoods"),
-                normalizeOptionalBlock(row.grossWeight(), prefix + "grossWeight"),
-                normalizeOptionalBlock(row.measurement(), prefix + "measurement"));
+                normalizeRequiredBlock(row.marksAndNos(), prefix + "marksAndNos"),
+                normalizeRequiredBlock(row.quantity(), prefix + "quantity"),
+                normalizeRequiredBlock(row.packaging(), prefix + "packaging"),
+                normalizeRequiredBlock(row.descriptionOfGoods(), prefix + "descriptionOfGoods"),
+                normalizeRequiredBlock(row.grossWeight(), prefix + "grossWeight"),
+                normalizeRequiredBlock(row.measurement(), prefix + "measurement"));
     }
 
-    private String normalizeFileName(String value) {
-        if (value == null) {
-            return "freight-a4-documents.pdf";
+    private String normalizeFileName(String value, String templateCode, FreightA4PdfDtos.Document firstDocument) {
+        String candidate = value;
+        if (candidate == null) {
+            candidate = FreightA4PdfDtos.SHIPPING_INSTRUCTION_TEMPLATE.equals(templateCode)
+                    ? firstDocument.field("jobNumber") + "-出口货物托运单.pdf"
+                    : firstDocument.field("bookingNumber") + "-提单确认件.pdf";
         }
-        String normalized = normalizeRequiredLine(value, "downloadFileName");
+        String normalized = normalizeRequiredLine(candidate, "downloadFileName");
         if (normalized.codePointCount(0, normalized.length()) > MAX_FILE_NAME_CODE_POINTS) {
             invalid("downloadFileName must not exceed 120 characters");
         }
@@ -165,6 +196,12 @@ public class FreightA4PdfService {
         return normalized;
     }
 
+    private String normalizeRequiredBlock(String value, String field) {
+        String normalized = normalizeOptionalBlock(value, field);
+        if (normalized.isBlank()) invalid(field + " must not be blank");
+        return normalized;
+    }
+
     private String normalizeRequiredLine(String value, String field) {
         String normalized = normalizeOptionalBlock(value, field);
         if (normalized.isBlank()) {

print/src/main/resources/openapi/print-internal-v1.yaml

@@ -173,6 +173,7 @@ components:
           type: string
           maxLength: 120
           example: BYSE2607044-托运书.pdf
+          description: 未传时托运书为{jobNumber}-出口货物托运单.pdf，提单确认件为{bookingNumber}-提单确认件.pdf
         documents:
           type: array
           minItems: 1
@@ -192,21 +193,77 @@ components:
           enum: [297]
     FreightA4Document:
       type: object
+      required: [fields, cargoRows]
+      x-template-contracts:
+        SEA_FREIGHT_SHIPPING_INSTRUCTION_A4_V1:
+          required: [toCompany, shipper, consignee, notifyParty, jobNumber, cargoQuantity, portOfLoading, portOfDischarge, placeOfDelivery, totalPackagesInWords]
+          optional: [issuerNameCn, issuerNameEn, issuerAddress, issuerPostalCode, issuerTel, issuerFax, picName, picTel, picFax, documentName, documentTel, documentFax, etdDate, serviceTerm, freightTerm, apCode, apName, transshipment, partialShipment, oceanVesselVoyage, remark, carrier, bookingAgent, printDate]
+        BILL_OF_LADING_CONFIRMATION_A4_V1:
+          required: [shipper, consignee, notifyParty, bookingNumber, portOfLoading, portOfDischarge, placeOfDelivery, serviceTerm, freightTerm, totalPackagesInWords]
+          optional: [ensAmsCutoffDate, customsCutoffDate, expectedDepartureDate, oceanVesselVoyage, finalDestination, shipperLoadCountSeal, containerSpec, shippedOnBoard, draftText, containerSummary, notes, issuePlace, issueDate]
       properties:
         fields:
           type: object
-          additionalProperties:
-            type: string
-            maxLength: 4000
-          description: Template field map. Known keys are documented in the print module README.
+          additionalProperties: false
+          description: 只能提交所选模板登记的键；未知键和缺少必填键返回A0422。
+          properties:
+            toCompany: {$ref: '#/components/schemas/FreightField'}
+            issuerNameCn: {$ref: '#/components/schemas/FreightField'}
+            issuerNameEn: {$ref: '#/components/schemas/FreightField'}
+            issuerAddress: {$ref: '#/components/schemas/FreightField'}
+            issuerPostalCode: {$ref: '#/components/schemas/FreightField'}
+            issuerTel: {$ref: '#/components/schemas/FreightField'}
+            issuerFax: {$ref: '#/components/schemas/FreightField'}
+            shipper: {$ref: '#/components/schemas/FreightField'}
+            consignee: {$ref: '#/components/schemas/FreightField'}
+            notifyParty: {$ref: '#/components/schemas/FreightField'}
+            picName: {$ref: '#/components/schemas/FreightField'}
+            picTel: {$ref: '#/components/schemas/FreightField'}
+            picFax: {$ref: '#/components/schemas/FreightField'}
+            documentName: {$ref: '#/components/schemas/FreightField'}
+            documentTel: {$ref: '#/components/schemas/FreightField'}
+            documentFax: {$ref: '#/components/schemas/FreightField'}
+            jobNumber: {$ref: '#/components/schemas/FreightField'}
+            etdDate: {$ref: '#/components/schemas/FreightField'}
+            serviceTerm: {$ref: '#/components/schemas/FreightField'}
+            freightTerm: {$ref: '#/components/schemas/FreightField'}
+            apCode: {$ref: '#/components/schemas/FreightField'}
+            apName: {$ref: '#/components/schemas/FreightField'}
+            cargoQuantity: {$ref: '#/components/schemas/FreightField'}
+            transshipment: {$ref: '#/components/schemas/FreightField'}
+            partialShipment: {$ref: '#/components/schemas/FreightField'}
+            oceanVesselVoyage: {$ref: '#/components/schemas/FreightField'}
+            portOfLoading: {$ref: '#/components/schemas/FreightField'}
+            portOfDischarge: {$ref: '#/components/schemas/FreightField'}
+            placeOfDelivery: {$ref: '#/components/schemas/FreightField'}
+            totalPackagesInWords: {$ref: '#/components/schemas/FreightField'}
+            remark: {$ref: '#/components/schemas/FreightField'}
+            carrier: {$ref: '#/components/schemas/FreightField'}
+            bookingAgent: {$ref: '#/components/schemas/FreightField'}
+            printDate: {$ref: '#/components/schemas/FreightField'}
+            bookingNumber: {$ref: '#/components/schemas/FreightField'}
+            ensAmsCutoffDate: {$ref: '#/components/schemas/FreightField'}
+            customsCutoffDate: {$ref: '#/components/schemas/FreightField'}
+            expectedDepartureDate: {$ref: '#/components/schemas/FreightField'}
+            finalDestination: {$ref: '#/components/schemas/FreightField'}
+            shipperLoadCountSeal: {$ref: '#/components/schemas/FreightField'}
+            containerSpec: {$ref: '#/components/schemas/FreightField'}
+            shippedOnBoard: {$ref: '#/components/schemas/FreightField'}
+            draftText: {$ref: '#/components/schemas/FreightField'}
+            containerSummary: {$ref: '#/components/schemas/FreightField'}
+            notes: {$ref: '#/components/schemas/FreightField'}
+            issuePlace: {$ref: '#/components/schemas/FreightField'}
+            issueDate: {$ref: '#/components/schemas/FreightField'}
         cargoRows:
           type: array
+          minItems: 1
           maxItems: 1
-          description: V1 templates render at most one cargo row. Callers must not send additional rows.
+          description: V1模板固定恰好一行货物，六个字段均必填且非空。
           items:
             $ref: '#/components/schemas/FreightA4CargoRow'
     FreightA4CargoRow:
       type: object
+      required: [marksAndNos, quantity, packaging, descriptionOfGoods, grossWeight, measurement]
       properties:
         marksAndNos:
           type: string
@@ -220,6 +277,9 @@ components:
           type: string
         measurement:
           type: string
+    FreightField:
+      type: string
+      maxLength: 4000
     ApiError:
       type: object
       required: [code, message]

print/src/test/java/com/baiyue/print/controller/InternalPdfControllerTest.java

@@ -172,6 +172,11 @@ class InternalPdfControllerTest {
                 .contains("application/pdf:")
                 .contains("application/json:")
                 .contains("name: X-Internal-Service-Token")
+                .contains("SEA_FREIGHT_SHIPPING_INSTRUCTION_A4_V1:")
+                .contains("BILL_OF_LADING_CONFIRMATION_A4_V1:")
+                .contains("additionalProperties: false")
+                .contains("minItems: 1")
+                .contains("required: [marksAndNos, quantity, packaging, descriptionOfGoods, grossWeight, measurement]")
                 .contains("maximum: 2000");
     }
 

print/src/test/java/com/baiyue/print/renderer/FreightA4ChineseLayoutContractTest.java

@@ -0,0 +1,25 @@
+package com.baiyue.print.renderer;
+
+import org.junit.jupiter.api.Test;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class FreightA4ChineseLayoutContractTest {
+    @Test
+    void freezesChineseTitlesAndBilingualLayoutLabels() throws Exception {
+        String source = Files.readString(Path.of(
+            "src/main/java/com/baiyue/print/renderer/FreightA4Renderer.java"));
+
+        assertThat(source).contains(
+            "出口货物托运单", "提单确认件",
+            "Shipper(Full Name & Address)(托运人)", "Consignee(收货人)", "Notify Party(通知人)",
+            "Ocean Vessel/Voy(船名航次)", "Port of Loading(起运港)",
+            "Part of Discharge(卸货港)", "Place of Delivery(交货地)",
+            "Marks & Nos\\n(标志和号码)", "Description of Goods(品名)",
+            "Gross Weight(Kilos)\\n毛重(公斤)", "Measurement(CBM)\\n体积(立方米)",
+            "截关日期", "预计开航日期", "SHIPPED ON BOARD");
+    }
+}

print/src/test/java/com/baiyue/print/service/FreightA4PdfServiceGenerationTest.java

@@ -37,7 +37,8 @@ class FreightA4PdfServiceGenerationTest {
             assertA4(document);
             String text = new PDFTextStripper().getText(document);
             assertThat(text).contains("Sea Freight Shipping Instructions", "Job Nbr",
-                    "BYSE2607044", "CAR ACCESSORIES", "SAY SIX HUNDRED AND FIFTY NINE PACKAGES ONLY.");
+                    "BYSE2607044", "CAR ACCESSORIES",
+                    "SAY SIX HUNDRED AND FIFTY NINE PACKAGES ONLY.");
         }
     }
 

print/src/test/java/com/baiyue/print/service/FreightA4PdfServiceValidationTest.java

@@ -25,7 +25,7 @@ class FreightA4PdfServiceValidationTest {
     @Test
     void rejectsUnsupportedTemplateCode() {
         assertValidationFailure(new FreightA4PdfDtos.Request("UNKNOWN",
-                pageSpec(), "a4.pdf", List.of(document())), "templateCode");
+                pageSpec(), "a4.pdf", List.of(shippingDocument())), "templateCode");
     }
 
     @Test
@@ -33,18 +33,59 @@ class FreightA4PdfServiceValidationTest {
         assertValidationFailure(new FreightA4PdfDtos.Request(
                 FreightA4PdfDtos.SHIPPING_INSTRUCTION_TEMPLATE,
                 new FreightA4PdfDtos.PageSpec(new BigDecimal("100"), new BigDecimal("100")),
-                "a4.pdf", List.of(document())), "pageSpec.widthMm");
+                "a4.pdf", List.of(shippingDocument())), "pageSpec.widthMm");
     }
 
     @Test
     void allowsMultilineDocumentFields() {
         FreightA4PdfDtos.Request request = new FreightA4PdfDtos.Request(
                 FreightA4PdfDtos.SHIPPING_INSTRUCTION_TEMPLATE,
-                pageSpec(), "a4.pdf", List.of(document()));
+                pageSpec(), "a4.pdf", List.of(shippingDocument()));
 
         assertThatCode(() -> service.generate(request)).doesNotThrowAnyException();
     }
 
+    @Test
+    void rejectsMissingRequiredFieldForSelectedTemplate() {
+        var fields = new java.util.HashMap<>(shippingDocument().fields());
+        fields.remove("jobNumber");
+        assertValidationFailure(request(FreightA4PdfDtos.SHIPPING_INSTRUCTION_TEMPLATE,
+            new FreightA4PdfDtos.Document(fields, cargoRows())), "fields.jobNumber is required");
+    }
+
+    @Test
+    void rejectsUnknownFieldInsteadOfSilentlyIgnoringTypo() {
+        var fields = new java.util.HashMap<>(shippingDocument().fields());
+        fields.put("jobNubmer", "OB-260831-0001");
+        assertValidationFailure(request(FreightA4PdfDtos.SHIPPING_INSTRUCTION_TEMPLATE,
+            new FreightA4PdfDtos.Document(fields, cargoRows())), "fields.jobNubmer is not supported");
+    }
+
+    @Test
+    void requiresExactlyOneCompleteCargoRow() {
+        assertValidationFailure(request(FreightA4PdfDtos.SHIPPING_INSTRUCTION_TEMPLATE,
+            new FreightA4PdfDtos.Document(shippingDocument().fields(), List.of())),
+            "cargoRows must contain exactly one item");
+        assertValidationFailure(request(FreightA4PdfDtos.SHIPPING_INSTRUCTION_TEMPLATE,
+            new FreightA4PdfDtos.Document(shippingDocument().fields(), List.of(cargo(), cargo()))),
+            "cargoRows must contain exactly one item");
+        assertValidationFailure(request(FreightA4PdfDtos.SHIPPING_INSTRUCTION_TEMPLATE,
+            new FreightA4PdfDtos.Document(shippingDocument().fields(), List.of(
+                new FreightA4PdfDtos.CargoRow("", "1", "PACKAGES", "GOODS", "1 KGS", "1 CBM")))),
+            "marksAndNos must not be blank");
+    }
+
+    @Test
+    void derivesStableChineseFileNamesFromBusinessNumbers() {
+        var shipping = service.generate(request(FreightA4PdfDtos.SHIPPING_INSTRUCTION_TEMPLATE,
+            shippingDocument()));
+        var bill = service.generate(request(FreightA4PdfDtos.BILL_CONFIRMATION_TEMPLATE,
+            billDocument()));
+
+        assertThat(shipping.fileName()).isEqualTo("OB-260831-0001-出口货物托运单.pdf");
+        assertThat(bill.fileName()).isEqualTo("BK-20260831-提单确认件.pdf");
+    }
+
     private void assertValidationFailure(FreightA4PdfDtos.Request request, String messagePart) {
         assertThatThrownBy(() -> service.generate(request))
                 .isInstanceOfSatisfying(BizException.class, exception -> {
@@ -53,12 +94,36 @@ class FreightA4PdfServiceValidationTest {
                 });
     }
 
+    private FreightA4PdfDtos.Request request(String template, FreightA4PdfDtos.Document document) {
+        return new FreightA4PdfDtos.Request(template, pageSpec(), null, List.of(document));
+    }
+
     private FreightA4PdfDtos.PageSpec pageSpec() {
         return new FreightA4PdfDtos.PageSpec(new BigDecimal("210"), new BigDecimal("297"));
     }
 
-    private FreightA4PdfDtos.Document document() {
-        return new FreightA4PdfDtos.Document(Map.of("shipper", "A\nB"),
-                List.of(new FreightA4PdfDtos.CargoRow("N/M", "1", "PACKAGES", "GOODS", "1 KGS", "1 CBM")));
+    private FreightA4PdfDtos.Document shippingDocument() {
+        return new FreightA4PdfDtos.Document(Map.of(
+            "toCompany", "订舱代理", "shipper", "A\nB", "consignee", "C", "notifyParty", "N",
+            "jobNumber", "OB-260831-0001", "cargoQuantity", "1*40HQ", "portOfLoading", "NINGBO",
+            "portOfDischarge", "LOS ANGELES", "placeOfDelivery", "LOS ANGELES",
+            "totalPackagesInWords", "SAY ONE PACKAGE ONLY."), cargoRows());
+    }
+
+    private FreightA4PdfDtos.Document billDocument() {
+        return new FreightA4PdfDtos.Document(Map.of(
+            "shipper", "A", "consignee", "C", "notifyParty", "N", "bookingNumber", "BK-20260831",
+            "portOfLoading", "NINGBO", "portOfDischarge", "LOS ANGELES",
+            "placeOfDelivery", "LOS ANGELES", "serviceTerm", "CY-CY",
+            "freightTerm", "FREIGHT PREPAID", "totalPackagesInWords", "SAY ONE PACKAGE ONLY."),
+            cargoRows());
+    }
+
+    private List<FreightA4PdfDtos.CargoRow> cargoRows() {
+        return List.of(cargo());
+    }
+
+    private FreightA4PdfDtos.CargoRow cargo() {
+        return new FreightA4PdfDtos.CargoRow("N/M", "1", "PACKAGES", "GOODS", "1 KGS", "1 CBM");
     }
 }