feat(firstleg): implement container customs workflow

file/src/main/resources/application.yml

@@ -40,8 +40,8 @@ spring:
             read-timeout: 15000
   servlet:
     multipart:
-      max-file-size: 10MB
-      max-request-size: 11MB
+      max-file-size: 50MB
+      max-request-size: 51MB
 rocketmq:
   name-server: ${ROCKETMQ_NAME_SERVER:127.0.0.1:9876}
   producer:
@@ -101,6 +101,15 @@ baiyue:
           max-rows: 200000
           max-attempts: 3
           batch-size: 500
+        LOADING_LIST_BUY_DECLARATION_ITEMS:
+          provider-service: firstleg-service
+          provider-path: /internal/exports/v1/LOADING_LIST_BUY_DECLARATION_ITEMS/batches
+          required-permission: platform:firstleg:customs:manage
+          app-scope: PLATFORM
+          enabled: true
+          max-rows: 200000
+          max-attempts: 3
+          batch-size: 500
         FINANCE_CUSTOMER_ACCOUNT_LIST:
           provider-service: finance-service
           provider-path: /internal/exports/v1/FINANCE_CUSTOMER_ACCOUNT_LIST/batches

file/src/main/resources/openapi/customs-file-and-export-v1.yaml

@@ -0,0 +1,154 @@
+openapi: 3.0.3
+info:
+  title: File Customs Business File and Export Contract
+  version: 1.0.0
+  description: |
+    File 只保存不可变文件对象并生成异步 XLSX，不保存报关状态或业务版本。
+    Firstleg 持有 loadingPlanId、文件版本、完成状态和可见性，并在调用本内部接口前完成 Platform/Client 鉴权。
+    LOADING_LIST_CUSTOMS_SOURCE 与 LOADING_LIST_CUSTOMS_RESULT 均为 CUSTOMER owner scope，tenantId 必须大于 0；
+    客户源文件上传/下载由 Firstleg 校验当前客户，结果文件下载还须由 Firstleg 校验整柜完成和结果可见性。
+    用户侧权限冻结为：Platform 上传结果 platform:firstleg:customs:manage，Platform 下载 platform:firstleg:loading-list:list；
+    Client 上传源文件 merchant:order:edit，Client 下载自身源文件或获准结果 merchant:order:view。
+    买单客户是否有结果入口由 Firstleg 判定，File 不据此增加结果文件或下载入口。
+paths:
+  /internal/file/v1/business-files/{tenantId}/{fileCategory}/{loadingPlanId}:
+    post:
+      summary: 保存报关业务文件对象
+      description: |
+        仅服务令牌可调用。fileCategory 取 LOADING_LIST_CUSTOMS_SOURCE 或 LOADING_LIST_CUSTOMS_RESULT。
+        支持任意文件格式，单文件最多 50MB。operatorId 为已通过 Firstleg 鉴权的实际操作人。
+      parameters:
+        - $ref: '#/components/parameters/InternalToken'
+        - $ref: '#/components/parameters/OperatorId'
+        - $ref: '#/components/parameters/TenantId'
+        - $ref: '#/components/parameters/FileCategory'
+        - $ref: '#/components/parameters/LoadingPlanId'
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file]
+              properties:
+                file: {type: string, format: binary}
+      responses:
+        '200':
+          description: ApiResponse<BusinessFileMetadata>
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/BusinessFileResponse'}
+  /internal/file/v1/business-files/{tenantId}/{fileCategory}/{loadingPlanId}/{fileId}:
+    get:
+      summary: 校验报关文件对象的精确复合归属
+      parameters:
+        - $ref: '#/components/parameters/InternalToken'
+        - $ref: '#/components/parameters/TenantId'
+        - $ref: '#/components/parameters/FileCategory'
+        - $ref: '#/components/parameters/LoadingPlanId'
+        - $ref: '#/components/parameters/FileId'
+      responses:
+        '200':
+          description: ApiResponse<BusinessFileMetadata>
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/BusinessFileResponse'}
+  /internal/file/v1/business-files/{tenantId}/{fileCategory}/{loadingPlanId}/{fileId}/content:
+    get:
+      summary: 下载精确归属的报关文件对象
+      description: 响应固定为 attachment 且 Cache-Control 包含 no-store；用户可见性由 Firstleg 在调用前判定。
+      parameters:
+        - $ref: '#/components/parameters/InternalToken'
+        - $ref: '#/components/parameters/TenantId'
+        - $ref: '#/components/parameters/FileCategory'
+        - $ref: '#/components/parameters/LoadingPlanId'
+        - $ref: '#/components/parameters/FileId'
+      responses:
+        '200':
+          description: 文件内容
+          headers:
+            Cache-Control: {schema: {type: string, example: no-store}}
+            Content-Disposition: {schema: {type: string, example: attachment}}
+          content:
+            application/octet-stream:
+              schema: {type: string, format: binary}
+  /internal/exports/v1/LOADING_LIST_BUY_DECLARATION_ITEMS/batches:
+    post:
+      summary: Firstleg 买单报关明细导出 Provider 契约
+      description: |
+        此路径由 Firstleg 提供、File 调用。一柜一份；parameters 只能包含正整数 loadingPlanId。
+        File 创建该导出任务的唯一 requiredPermission 为 platform:firstleg:customs:manage。
+        Provider 必须按 schemaVersion=1 返回下列固定顺序列，File 校验后生成 XLSX。
+      parameters:
+        - $ref: '#/components/parameters/InternalToken'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/ExportBatchRequest'}
+      responses:
+        '200':
+          description: ApiResponse<ExportBatchResponse>
+components:
+  parameters:
+    InternalToken: {name: X-Internal-Service-Token, in: header, required: true, schema: {type: string}}
+    OperatorId: {name: X-Operator-Id, in: header, required: true, schema: {type: integer, format: int64, minimum: 1}}
+    TenantId: {name: tenantId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}, description: 客户ID；不得使用平台0作用域}
+    FileCategory: {name: fileCategory, in: path, required: true, schema: {type: string, enum: [LOADING_LIST_CUSTOMS_SOURCE, LOADING_LIST_CUSTOMS_RESULT]}}
+    LoadingPlanId: {name: loadingPlanId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+    FileId: {name: fileId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+  schemas:
+    BusinessFileResponse:
+      type: object
+      required: [code, data]
+      properties:
+        code: {type: string, example: '200'}
+        message: {type: string}
+        data: {$ref: '#/components/schemas/BusinessFileMetadata'}
+    BusinessFileMetadata:
+      type: object
+      required: [fileId, tenantId, businessType, businessId, fileName, sha256, contentType, sizeBytes]
+      properties:
+        fileId: {type: string, description: File不可变对象ID，跨前端按字符串传输}
+        tenantId: {type: string, description: CUSTOMER owner scope客户ID}
+        businessType: {type: string, description: fileCategory}
+        businessId: {type: string, description: loadingPlanId}
+        fileName: {type: string}
+        sha256: {type: string}
+        contentType: {type: string}
+        sizeBytes: {type: integer, format: int64, maximum: 52428800}
+    ExportBatchRequest:
+      type: object
+      required: [taskId, tenantId, appCode, requestedBy, dispatchVersion, parameters, limit]
+      properties:
+        taskId: {type: string}
+        tenantId: {type: string, enum: ['0']}
+        appCode: {type: string, enum: [PLATFORM]}
+        requestedBy: {type: string}
+        dispatchVersion: {type: integer}
+        parameters:
+          type: object
+          required: [loadingPlanId]
+          additionalProperties: false
+          properties:
+            loadingPlanId: {type: string, pattern: '^[1-9][0-9]*$'}
+        cursor: {type: string, nullable: true}
+        snapshotToken: {type: string, nullable: true}
+        limit: {type: integer, minimum: 50, maximum: 1000}
+    BuyDeclarationColumns:
+      type: object
+      description: 固定列顺序
+      properties:
+        customerName: {type: string, title: 客户名称}
+        orderNo: {type: string, title: 订单号}
+        inboundCode: {type: string, title: 入仓码}
+        sku: {type: string, title: SKU}
+        chineseName: {type: string, title: 中文品名}
+        englishName: {type: string, title: 英文品名}
+        cartonCount: {type: integer, title: 箱数}
+        productQuantity: {type: integer, title: 产品数量}
+        grossWeight: {type: number, title: 毛重}
+        netWeight: {type: number, title: 净重}
+        volume: {type: number, title: 体积}
+        mark: {type: string, title: 唛头}
+        customerRemark: {type: string, title: 客户备注}