优化

2026-08-06 11:49:51 +08:00
parent a11e47fe3b
commit 7dd92f1c84
91 changed files with 6233 additions and 174 deletions
@@ -52,6 +52,54 @@ paths:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
+  /internal/print/v1/pdfs/freight-a4-documents:
+    post:
+      summary: Generate an A4 sea-freight document PDF
+      operationId: generateFreightA4DocumentPdf
+      security:
+        - internalServiceToken: []
+      parameters:
+        - $ref: '#/components/parameters/RequestId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FreightA4PdfRequest'
+      responses:
+        '200':
+          description: PDF generation succeeded, or a business error was returned as ApiResponse JSON.
+          headers:
+            Content-Disposition:
+              description: UTF-8 attachment filename. Present only for a successful PDF.
+              schema:
+                type: string
+            Cache-Control:
+              schema:
+                type: string
+                example: no-store
+            X-Print-Page-Count:
+              schema:
+                type: integer
+                minimum: 1
+                maximum: 2000
+            X-Request-Id:
+              schema:
+                type: string
+          content:
+            application/pdf:
+              schema:
+                type: string
+                format: binary
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiError'
+        '413':
+          description: Request body exceeds the configured limit.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiError'
 components:
  securitySchemes:
    internalServiceToken:
@@ -112,6 +160,66 @@ components:
          minLength: 1
          maxLength: 34
          pattern: '^[\\x20-\\x7E]+$'
+    FreightA4PdfRequest:
+      type: object
+      required: [templateCode, pageSpec, documents]
+      properties:
+        templateCode:
+          type: string
+          enum: [SEA_FREIGHT_SHIPPING_INSTRUCTION_A4_V1, BILL_OF_LADING_CONFIRMATION_A4_V1]
+        pageSpec:
+          $ref: '#/components/schemas/FreightA4PageSpec'
+        downloadFileName:
+          type: string
+          maxLength: 120
+          example: BYSE2607044-托运书.pdf
+        documents:
+          type: array
+          minItems: 1
+          maxItems: 2000
+          description: One document item renders one A4 page in request order.
+          items:
+            $ref: '#/components/schemas/FreightA4Document'
+    FreightA4PageSpec:
+      type: object
+      required: [widthMm, heightMm]
+      properties:
+        widthMm:
+          type: number
+          enum: [210]
+        heightMm:
+          type: number
+          enum: [297]
+    FreightA4Document:
+      type: object
+      properties:
+        fields:
+          type: object
+          additionalProperties:
+            type: string
+            maxLength: 4000
+          description: Template field map. Known keys are documented in the print module README.
+        cargoRows:
+          type: array
+          maxItems: 1
+          description: V1 templates render at most one cargo row. Callers must not send additional rows.
+          items:
+            $ref: '#/components/schemas/FreightA4CargoRow'
+    FreightA4CargoRow:
+      type: object
+      properties:
+        marksAndNos:
+          type: string
+        quantity:
+          type: string
+        packaging:
+          type: string
+        descriptionOfGoods:
+          type: string
+        grossWeight:
+          type: string
+        measurement:
+          type: string
    ApiError:
      type: object
      required: [code, message]