feat(firstleg): split customs receipt and final document flow

2026-09-26 13:28:18 +08:00
parent 5a895bf214
commit ff2386e5bf
13 changed files with 405 additions and 110 deletions
@@ -12,6 +12,9 @@ CREATE TABLE IF NOT EXISTS fl_customs_container (
  completed_by BIGINT UNSIGNED NULL COMMENT '完成报关操作人ID',
  completed_by_name VARCHAR(64) NULL COMMENT '完成报关操作人名称快照',
  completed_at DATETIME(3) NULL COMMENT '报关完成时间',
+  broker_submitted_by BIGINT UNSIGNED NULL COMMENT '已将客户确认结果发送给报关行的操作人ID',
+  broker_submitted_by_name VARCHAR(64) NULL COMMENT '发送报关行操作人名称快照',
+  broker_submitted_at DATETIME(3) NULL COMMENT '发送报关行执行时间',
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '聚合创建时间',
  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '聚合更新时间',
  version INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '乐观锁版本号',
@@ -93,10 +96,10 @@ CREATE TABLE IF NOT EXISTS fl_customs_frozen_document_inbound (
 ) ENGINE=InnoDB COMMENT='开始报关时冻结的客户资料覆盖范围';

 CREATE TABLE IF NOT EXISTS fl_customs_completion_document (
-  id BIGINT UNSIGNED NOT NULL COMMENT '报关完成文件ID',
+  id BIGINT UNSIGNED NOT NULL COMMENT '报关行回执文件ID',
  source_document_id BIGINT UNSIGNED NOT NULL COMMENT '一份冻结客户资料严格对应一份完成文件逻辑根',
  file_id BIGINT UNSIGNED NOT NULL COMMENT 'File服务文件ID',
-  file_name VARCHAR(255) NOT NULL COMMENT '完成文件名称快照',
+  file_name VARCHAR(255) NOT NULL COMMENT '回执文件名称快照',
  file_hash CHAR(64) NOT NULL COMMENT '完成文件SHA-256摘要',
  content_type VARCHAR(128) NULL COMMENT '完成文件媒体类型',
  size_bytes BIGINT UNSIGNED NOT NULL COMMENT '完成文件大小（字节）',
@@ -114,7 +117,7 @@ CREATE TABLE IF NOT EXISTS fl_customs_completion_document (
  PRIMARY KEY(id),
  UNIQUE KEY uk_customs_completion_source(source_document_id),
  CONSTRAINT fk_customs_completion_source FOREIGN KEY(source_document_id) REFERENCES fl_customs_customer_document(id)
-) ENGINE=InnoDB COMMENT='报关完成文件当前版本';
+) ENGINE=InnoDB COMMENT='报关行回执当前版本';

 CREATE TABLE IF NOT EXISTS fl_customs_completion_document_version (
  id BIGINT UNSIGNED NOT NULL COMMENT '完成文件版本记录ID',
@@ -133,6 +136,25 @@ CREATE TABLE IF NOT EXISTS fl_customs_completion_document_version (
  CONSTRAINT fk_customs_completion_version FOREIGN KEY(completion_document_id) REFERENCES fl_customs_completion_document(id)
 ) ENGINE=InnoDB COMMENT='报关完成文件不可变覆盖版本';

+CREATE TABLE IF NOT EXISTS fl_customs_final_document (
+  id BIGINT UNSIGNED NOT NULL COMMENT '真实报关完税文件ID',
+  source_document_id BIGINT UNSIGNED NOT NULL COMMENT '对应冻结客户资料ID',
+  file_id BIGINT UNSIGNED NOT NULL COMMENT 'File服务文件ID',
+  file_name VARCHAR(255) NOT NULL COMMENT '真实报关完税文件名称快照',
+  file_hash CHAR(64) NOT NULL COMMENT '真实报关完税文件SHA-256摘要',
+  content_type VARCHAR(128) NULL COMMENT '真实报关完税文件媒体类型',
+  size_bytes BIGINT UNSIGNED NOT NULL COMMENT '真实报关完税文件大小（字节）',
+  uploaded_by BIGINT UNSIGNED NOT NULL COMMENT '上传操作人ID',
+  uploaded_by_name VARCHAR(64) NULL COMMENT '上传操作人名称快照',
+  uploaded_at DATETIME(3) NOT NULL COMMENT '上传时间',
+  version INT UNSIGNED NOT NULL DEFAULT 1 COMMENT '完税文件版本号',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY(id),
+  UNIQUE KEY uk_customs_final_source(source_document_id),
+  CONSTRAINT fk_customs_final_source FOREIGN KEY(source_document_id) REFERENCES fl_customs_customer_document(id)
+) ENGINE=InnoDB COMMENT='真实报关完税文件当前版本';
+
 CREATE TABLE IF NOT EXISTS fl_customs_container_history (
  id BIGINT UNSIGNED NOT NULL COMMENT '报关历史记录ID',
  customs_container_id BIGINT UNSIGNED NOT NULL COMMENT '所属整柜报关聚合ID',
@@ -21,10 +21,17 @@ paths:
      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {$ref: '#/components/requestBodies/ActionBody'}
      responses: {'200': {$ref: '#/components/responses/ContainerResponse'}}
-  /api/platform/v1/customs/loading-plans/documents/{documentId}/completion/upload:
+  /api/platform/v1/customs/loading-plans/{planId}/submit-to-broker:
    post:
-      summary: 上传或覆盖冻结客户资料的一对一完成文件
-      description: 报关行回执按冻结客户资料一对一保存；上传后等待对应客户确认或打回，不自动完成整柜报关。
+      summary: 将客户确认回执发送给报关行执行
+      x-permission: platform:firstleg:customs:manage
+      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {$ref: '#/components/requestBodies/ActionBody'}
+      responses: {'200': {$ref: '#/components/responses/ContainerResponse'}}
+  /api/platform/v1/customs/loading-plans/documents/{documentId}/receipt/upload:
+    post:
+      summary: 上传或覆盖冻结客户资料的一对一报关行回执
+      description: 报关行回执按冻结客户资料一对一保存；上传后等待对应客户确认或打回。
      x-permission: platform:firstleg:customs:manage
      parameters:
        - {$ref: '#/components/parameters/DocumentId'}
@@ -38,9 +45,22 @@ paths:
      x-permission: platform:firstleg:customs:list
      parameters: [{$ref: '#/components/parameters/DocumentId'}]
      responses: {'200': {$ref: '#/components/responses/BinaryResponse'}}
-  /api/platform/v1/customs/loading-plans/documents/{documentId}/completion/download:
+  /api/platform/v1/customs/loading-plans/documents/{documentId}/receipt/download:
    get:
-      summary: 平台下载报关完成文件
+      summary: 平台下载报关行回执
+      x-permission: platform:firstleg:customs:list
+      parameters: [{$ref: '#/components/parameters/DocumentId'}]
+      responses: {'200': {$ref: '#/components/responses/BinaryResponse'}}
+  /api/platform/v1/customs/loading-plans/documents/{documentId}/final/upload:
+    post:
+      summary: 上传真实报关完税文件
+      x-permission: platform:firstleg:customs:manage
+      parameters: [{$ref: '#/components/parameters/DocumentId'}, {$ref: '#/components/parameters/IdempotencyKey'}, {name: expectedVersion, in: query, required: true, schema: {type: integer, minimum: 0}}]
+      requestBody: {$ref: '#/components/requestBodies/FileBody'}
+      responses: {'200': {$ref: '#/components/responses/DocumentResponse'}}
+  /api/platform/v1/customs/loading-plans/documents/{documentId}/final/download:
+    get:
+      summary: 平台下载真实报关完税文件
      x-permission: platform:firstleg:customs:list
      parameters: [{$ref: '#/components/parameters/DocumentId'}]
      responses: {'200': {$ref: '#/components/responses/BinaryResponse'}}
@@ -93,9 +113,15 @@ paths:
      x-permission: merchant:order:view
      parameters: [{$ref: '#/components/parameters/DocumentId'}]
      responses: {'200': {$ref: '#/components/responses/BinaryResponse'}}
-  /api/merchant/v1/customs/documents/{documentId}/completion/download:
+  /api/merchant/v1/customs/documents/{documentId}/receipt/download:
    get:
-      summary: 整柜完成后客户下载对应完成文件
+      summary: 客户下载报关行回执
+      x-permission: merchant:order:view
+      parameters: [{$ref: '#/components/parameters/DocumentId'}]
+      responses: {'200': {$ref: '#/components/responses/BinaryResponse'}}
+  /api/merchant/v1/customs/documents/{documentId}/final/download:
+    get:
+      summary: 整柜完成后客户下载真实报关完税文件
      x-permission: merchant:order:view
      parameters: [{$ref: '#/components/parameters/DocumentId'}]
      responses: {'200': {$ref: '#/components/responses/BinaryResponse'}}
@@ -142,7 +168,7 @@ components:
    ScopeRequest: {type: object, required: [inboundIds, expectedVersion], additionalProperties: false, properties: {inboundIds: {type: array, minItems: 1, maxItems: 200, items: {$ref: '#/components/schemas/LongId'}}, expectedVersion: {type: integer, minimum: 1}}}
    FileView: {type: object, required: [fileId, fileName, fileHash, sizeBytes, version, uploadedAt], properties: {fileId: {$ref: '#/components/schemas/LongId'}, fileName: {type: string}, fileHash: {type: string}, contentType: {type: string, nullable: true}, sizeBytes: {type: integer, format: int64}, version: {type: integer}, uploadedAt: {type: string, format: date-time}}}
    InboundView: {type: object, required: [inboundId, orderId, orderNo, inboundCode, tenantId, customerName, taxMode, covered], properties: {inboundId: {$ref: '#/components/schemas/LongId'}, orderId: {$ref: '#/components/schemas/LongId'}, orderNo: {type: string}, inboundCode: {type: string}, tenantId: {$ref: '#/components/schemas/LongId'}, customerName: {type: string}, taxMode: {type: string, enum: [TAX_REFUND, BUY_DECLARATION]}, covered: {type: boolean}}}
-    DocumentView: {type: object, required: [documentId, tenantId, source, inboundIds, inboundCodes, frozen], properties: {documentId: {$ref: '#/components/schemas/LongId'}, tenantId: {$ref: '#/components/schemas/LongId'}, source: {$ref: '#/components/schemas/FileView'}, inboundIds: {type: array, items: {$ref: '#/components/schemas/LongId'}}, inboundCodes: {type: array, items: {type: string}}, frozen: {type: boolean}, completion: {allOf: [{$ref: '#/components/schemas/FileView'}], nullable: true, description: 退税报关行回执文件}, receiptStatus: {type: string, enum: [PENDING, CONFIRMED, REJECTED], nullable: true}, receiptRejectReason: {type: string, nullable: true}}}
+    DocumentView: {type: object, required: [documentId, tenantId, source, inboundIds, inboundCodes, frozen], properties: {documentId: {$ref: '#/components/schemas/LongId'}, tenantId: {$ref: '#/components/schemas/LongId'}, source: {$ref: '#/components/schemas/FileView'}, inboundIds: {type: array, items: {$ref: '#/components/schemas/LongId'}}, inboundCodes: {type: array, items: {type: string}}, frozen: {type: boolean}, receipt: {allOf: [{$ref: '#/components/schemas/FileView'}], nullable: true, description: 报关行回执文件}, receiptStatus: {type: string, enum: [PENDING, CONFIRMED, REJECTED], nullable: true}, receiptRejectReason: {type: string, nullable: true}, finalDocument: {allOf: [{$ref: '#/components/schemas/FileView'}], nullable: true, description: 真实报关完税文件}}}
    ContainerView: {type: object, required: [aggregateId, loadingPlanId, containerBookingId, status, hasActualCargo, version, taxRefundCount, coveredTaxRefundCount, actualBoxCount, inbounds, documents], properties: {aggregateId: {$ref: '#/components/schemas/LongId'}, loadingPlanId: {$ref: '#/components/schemas/LongId'}, containerBookingId: {$ref: '#/components/schemas/LongId'}, planNo: {type: string}, cabinetNo: {type: string}, containerNo: {type: string, nullable: true}, status: {type: string, enum: [WAITING_CUSTOMER_DOCUMENTS, READY_TO_START, DECLARING, COMPLETED]}, hasActualCargo: {type: boolean, description: 当前完成装柜计划是否仍有实际装柜货物；false时查询成功返回空明细且无需发起报关}, merchantStatus: {type: string, enum: [WAITING_UPLOAD, DOCUMENT_UPLOADED, DECLARING, CUSTOMS_COMPLETED], nullable: true}, version: {type: integer}, taxRefundCount: {type: integer}, coveredTaxRefundCount: {type: integer}, actualBoxCount: {type: integer, format: int64, minimum: 0, description: 当前视角可见的实际装箱数；部分装柜只展示该数量，线下处理后续}, inbounds: {type: array, items: {$ref: '#/components/schemas/InboundView'}}, documents: {type: array, items: {$ref: '#/components/schemas/DocumentView'}}, startedAt: {type: string, format: date-time, nullable: true}, completedAt: {type: string, format: date-time, nullable: true}}}
    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}}}, cursor: {type: string, nullable: true}, snapshotToken: {type: string, nullable: true}, limit: {type: integer, minimum: 1, maximum: 500}}}
    ExportBatchEnvelope: {allOf: [{$ref: '#/components/schemas/ApiEnvelope'}, {type: object, properties: {data: {type: object, properties: {schemaVersion: {type: integer}, schemaHash: {type: string}, snapshotToken: {type: string}, columns: {type: array, items: {type: object}}, rows: {type: array, items: {type: object}}, nextCursor: {type: string}, hasMore: {type: boolean}, totalRows: {type: integer, format: int64, nullable: true}}}}}]}