优化

firstleg/src/main/resources/db/phase3-customs-schema.sql

@@ -100,6 +100,7 @@ CREATE TABLE IF NOT EXISTS fl_customs_submission_batch (
   customs_case_id BIGINT UNSIGNED NOT NULL COMMENT '所属报关协同单ID',
   batch_no VARCHAR(40) NOT NULL COMMENT '全局唯一代理提交批次号',
   batch_version INT UNSIGNED NOT NULL COMMENT '同一报关协同单内的提交批次版本序号',
+  customs_agent_id BIGINT UNSIGNED NULL COMMENT '本批次报关代理Supplier逻辑ID快照；历史数据无法推导时为空',
   customs_agent_name VARCHAR(128) NOT NULL COMMENT '本批次接收报关资料的报关代理名称快照',
   external_reference VARCHAR(128) NULL COMMENT '报关代理或外部系统返回的业务参考号',
   file_snapshot_json JSON NOT NULL COMMENT '提交时冻结的已审核资料数组；元素包含documentId、fileId、itemCode、documentVersion和fileHash',

firstleg/src/main/resources/db/phase3-smart-loading-schema.sql

@@ -53,7 +53,8 @@ CREATE TABLE IF NOT EXISTS fl_container_booking (
   destination_warehouse_name VARCHAR(128) NULL COMMENT '目的仓名称快照',
   capacity_cbm DECIMAL(18,4) NULL COMMENT '货柜容量m3',
   max_weight_kg DECIMAL(18,3) NULL COMMENT '货柜最大承重kg',
-  terminal_trucking_company VARCHAR(128) NULL COMMENT '码头拖车公司',
+  terminal_trucking_company_id BIGINT UNSIGNED NULL COMMENT '码头拖车Supplier逻辑ID快照；历史数据无法推导时为空',
+  terminal_trucking_company VARCHAR(128) NULL COMMENT '码头拖车公司名称快照',
   loading_at DATETIME(3) NULL COMMENT '计划或实际装柜时间',
   estimated_sailing_at DATETIME(3) NULL COMMENT '预计开船时间',
   actual_sailing_at DATETIME(3) NULL COMMENT '实际开船时间',

firstleg/src/main/resources/openapi/customs-v1.yaml

@@ -57,7 +57,12 @@ paths:
       summary: Submit to customs agent and freeze approved file versions in a batch snapshot
       description: customsAgentId must identify an ACTIVE Warehouse supplier in category CUSTOMS; the persisted agent name is resolved server-side and free text cannot bypass supplier validation.
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/SubmitBatchRequest'}}}}
-      responses: {'200': {description: Submission batch}}
+      responses:
+        '200':
+          description: Submission batch
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/CustomsSubmissionBatch'}
   /api/platform/v1/customs/submission-batches/{batchId}/receipts:
     parameters:
       - {name: batchId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
@@ -103,3 +108,20 @@ components:
         externalReference: {type: string, maxLength: 128, nullable: true}
         note: {type: string, maxLength: 500, nullable: true}
         expectedVersion: {type: integer, minimum: 0}
+    CustomsSubmissionBatch:
+      type: object
+      required: [id, customsCaseId, batchNo, batchVersion, customsAgentName, status, submittedBy, submittedAt]
+      properties:
+        id: {type: string, pattern: '^[1-9][0-9]*$'}
+        customsCaseId: {type: string, pattern: '^[1-9][0-9]*$'}
+        batchNo: {type: string, maxLength: 40}
+        batchVersion: {type: integer, minimum: 1}
+        customsAgentId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true, description: Server-validated CUSTOMS supplier ID snapshot; null only for non-migrated historical rows.}
+        customsAgentName: {type: string, maxLength: 128, description: Server-frozen Warehouse supplier name snapshot.}
+        externalReference: {type: string, maxLength: 128, nullable: true}
+        fileSnapshotJson: {type: string}
+        status: {type: string, enum: [SUBMITTED, ACKNOWLEDGED, REJECTED, COMPLETED]}
+        note: {type: string, maxLength: 500, nullable: true}
+        submittedBy: {type: string, pattern: '^[1-9][0-9]*$'}
+        submittedByName: {type: string, maxLength: 64, nullable: true}
+        submittedAt: {type: string, format: date-time}

firstleg/src/main/resources/openapi/firstleg-v1.yaml

@@ -1234,7 +1234,8 @@ components:
         destinationWarehouseName: {type: string, maxLength: 128, nullable: true}
         capacityCbm: {type: number, exclusiveMinimum: true, minimum: 0, nullable: true}
         maxWeightKg: {type: number, exclusiveMinimum: true, minimum: 0, nullable: true}
-        terminalTruckingCompany: {type: string, maxLength: 128, nullable: true}
+        terminalTruckingCompanyId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true, description: ACTIVE Warehouse Supplier ID validated as TRUCKING}
+        terminalTruckingCompany: {type: string, maxLength: 128, nullable: true, description: Server-frozen Warehouse supplier name snapshot}
         loadingAt: {type: string, format: date-time, nullable: true}
         estimatedSailingAt: {type: string, format: date-time, nullable: true}
         actualSailingAt: {type: string, format: date-time, nullable: true}
@@ -1266,7 +1267,8 @@ components:
         destinationWarehouseName: {type: string, maxLength: 128, nullable: true}
         capacityCbm: {type: number, exclusiveMinimum: true, minimum: 0, nullable: true}
         maxWeightKg: {type: number, exclusiveMinimum: true, minimum: 0, nullable: true}
-        terminalTruckingCompany: {type: string, maxLength: 128, nullable: true}
+        terminalTruckingCompanyId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true, description: ACTIVE Warehouse Supplier ID validated as TRUCKING}
+        terminalTruckingCompany: {type: string, maxLength: 128, nullable: true, description: Optional consistency hint; persisted name always comes from Warehouse and cannot replace the ID}
         loadingAt: {type: string, format: date-time, nullable: true}
         estimatedSailingAt: {type: string, format: date-time, nullable: true}
         actualSailingAt: {type: string, format: date-time, nullable: true}