优化

2026-08-13 11:57:33 +08:00
parent 5a48992d78
commit 16dc03a2e2
102 changed files with 3656 additions and 120 deletions
@@ -0,0 +1,41 @@
+USE baiyue_firstleg;
+CREATE TABLE IF NOT EXISTS fl_container_exception_history (
+ id BIGINT UNSIGNED NOT NULL, container_booking_id BIGINT UNSIGNED NOT NULL,
+ action VARCHAR(16) NOT NULL COMMENT 'MARK/CANCEL', reason VARCHAR(500) NOT NULL,
+ operator_id BIGINT UNSIGNED NOT NULL, operator_name VARCHAR(64),
+ operation_id VARCHAR(128) NOT NULL COMMENT '同一操作人幂等键', request_hash CHAR(64) NOT NULL COMMENT '请求摘要',
+ occurred_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+ PRIMARY KEY(id), UNIQUE KEY uk_container_exception_operation(container_booking_id,operator_id,operation_id),
+ KEY idx_container_exception_history(container_booking_id,occurred_at,id),
+ CONSTRAINT fk_container_exception_booking FOREIGN KEY(container_booking_id) REFERENCES fl_container_booking(id),
+ CONSTRAINT chk_container_exception_action CHECK(action IN ('MARK','CANCEL'))
+) ENGINE=InnoDB COMMENT='货柜异常标记及取消历史';
+
+DROP PROCEDURE IF EXISTS phase3_container_exception_add_column;
+DELIMITER $$
+CREATE PROCEDURE phase3_container_exception_add_column(IN p_name VARCHAR(64),IN p_definition TEXT)
+BEGIN
+ IF NOT EXISTS(SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='fl_container_exception_history' AND column_name=p_name) THEN
+  SET @ddl=CONCAT('ALTER TABLE fl_container_exception_history ADD COLUMN ',p_name,' ',p_definition);
+  PREPARE statement FROM @ddl; EXECUTE statement; DEALLOCATE PREPARE statement;
+ END IF;
+END$$
+DELIMITER ;
+CALL phase3_container_exception_add_column('operation_id',"VARCHAR(128) NULL COMMENT '同一操作人幂等键' AFTER operator_name");
+CALL phase3_container_exception_add_column('request_hash',"CHAR(64) NULL COMMENT '请求摘要' AFTER operation_id");
+DROP PROCEDURE phase3_container_exception_add_column;
+UPDATE fl_container_exception_history SET operation_id=CONCAT('LEGACY-',id) WHERE operation_id IS NULL OR operation_id='';
+UPDATE fl_container_exception_history SET request_hash=SHA2(CONCAT(action,'|',container_booking_id,'|',id,'|',reason),256) WHERE request_hash IS NULL OR request_hash='';
+ALTER TABLE fl_container_exception_history MODIFY operation_id VARCHAR(128) NOT NULL, MODIFY request_hash CHAR(64) NOT NULL;
+SET @has_exception_operation_index=(SELECT COUNT(*) FROM information_schema.statistics WHERE table_schema=DATABASE() AND table_name='fl_container_exception_history' AND index_name='uk_container_exception_operation');
+SET @ddl=IF(@has_exception_operation_index=0,'ALTER TABLE fl_container_exception_history ADD UNIQUE KEY uk_container_exception_operation(container_booking_id,operator_id,operation_id)','SELECT 1');
+PREPARE statement FROM @ddl; EXECUTE statement; DEALLOCATE PREPARE statement;
+
+DROP TRIGGER IF EXISTS trg_container_exception_history_before_update;
+DROP TRIGGER IF EXISTS trg_container_exception_history_before_delete;
+DELIMITER $$
+CREATE TRIGGER trg_container_exception_history_before_update BEFORE UPDATE ON fl_container_exception_history FOR EACH ROW
+BEGIN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='货柜异常历史不可修改'; END$$
+CREATE TRIGGER trg_container_exception_history_before_delete BEFORE DELETE ON fl_container_exception_history FOR EACH ROW
+BEGIN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='货柜异常历史不可删除'; END$$
+DELIMITER ;
@@ -206,6 +206,27 @@ CREATE TABLE IF NOT EXISTS fl_container_document (
    CHECK (document_type IN ('DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION', 'DELIVERY_ORDER', 'PICKUP_ORDER'))
 ) ENGINE=InnoDB COMMENT='平台货柜清关、DO与PU文件关联';

+CREATE TABLE IF NOT EXISTS fl_container_exception_history (
+  id BIGINT UNSIGNED NOT NULL, container_booking_id BIGINT UNSIGNED NOT NULL,
+  action VARCHAR(16) NOT NULL, reason VARCHAR(500) NOT NULL,
+  operator_id BIGINT UNSIGNED NOT NULL, operator_name VARCHAR(64) NULL,
+  operation_id VARCHAR(128) NOT NULL, request_hash CHAR(64) NOT NULL,
+  occurred_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), PRIMARY KEY(id),
+  UNIQUE KEY uk_container_exception_operation(container_booking_id,operator_id,operation_id),
+  KEY idx_container_exception_history(container_booking_id,occurred_at,id),
+  CONSTRAINT fk_container_exception_booking FOREIGN KEY(container_booking_id) REFERENCES fl_container_booking(id),
+  CONSTRAINT chk_container_exception_action CHECK(action IN ('MARK','CANCEL'))
+) ENGINE=InnoDB COMMENT='货柜异常标记及取消原因历史';
+
+DROP TRIGGER IF EXISTS trg_container_exception_history_before_update;
+DROP TRIGGER IF EXISTS trg_container_exception_history_before_delete;
+DELIMITER $$
+CREATE TRIGGER trg_container_exception_history_before_update BEFORE UPDATE ON fl_container_exception_history FOR EACH ROW
+BEGIN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='货柜异常历史不可修改'; END$$
+CREATE TRIGGER trg_container_exception_history_before_delete BEFORE DELETE ON fl_container_exception_history FOR EACH ROW
+BEGIN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='货柜异常历史不可删除'; END$$
+DELIMITER ;
+
 CREATE TABLE IF NOT EXISTS fl_loading_plan_history (
  id BIGINT UNSIGNED NOT NULL COMMENT '装柜操作历史ID（雪花ID）',
  loading_plan_id BIGINT UNSIGNED NOT NULL COMMENT '智能装柜计划ID',
@@ -210,7 +210,7 @@ paths:
  /api/platform/v1/containers/{id}:
    get:
      summary: 查询平台货柜详情
-      description: 需要 platform:firstleg:container:view 权限
+      description: 需要 platform:firstleg:container:list 权限
      parameters:
        - {$ref: '#/components/parameters/ContainerBookingId'}
      responses:
@@ -25,8 +25,8 @@ paths:
  /api/platform/v1/first-leg/loading-plans/{planId}:
    get:
      summary: 查询预装清单详情
+      x-permission: platform:firstleg:preload:list
      description: 返回同一装柜计划的汇总、冻结明细和完整操作历史。
-      x-permission: platform:firstleg:preload:view
      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}]
      responses:
        '200': {$ref: '#/components/responses/PreloadDetailResponse'}
@@ -63,15 +63,16 @@ paths:
  /api/platform/v1/first-leg/loading-lists/{planId}:
    get:
      summary: 查询装柜清单详情
-      description: 返回已确认计划的汇总、冻结明细和操作历史，全部只读。
-      x-permission: platform:firstleg:loading-list:view
+      description: 返回已确认计划的汇总、冻结明细和操作历史，全部只读；查看权限与分页列表权限独立。
+      x-permission: platform:firstleg:loading-list:list
      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}]
      responses:
        '200': {$ref: '#/components/responses/ConfirmedDetailResponse'}
  /api/platform/v1/first-leg/loading-lists/{planId}/customs:
    get:
      summary: 查询装柜清单出口报关文档
-      x-permission: platform:firstleg:loading-list:view
+      x-permission: platform:firstleg:loading-list:list
+      description: 查询出口报关文档；写入与完成继续要求 platform:firstleg:customs:manage。
      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}]
      responses:
        '200': {$ref: '#/components/responses/BusinessDocumentResponse'}
@@ -0,0 +1,60 @@
+openapi: 3.0.3
+info: {title: Firstleg Container Overview API, version: 1.0.0}
+paths:
+  /api/platform/v1/containers/{id}/overview:
+    get:
+      operationId: getContainerOverview
+      description: '权限：platform:firstleg:container:list'
+      parameters: [{$ref: '#/components/parameters/ContainerId'}]
+      responses: {'200': {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/OverviewEnvelope'}}}}}
+  /api/platform/v1/containers/{id}/exception:
+    parameters: [{$ref: '#/components/parameters/ContainerId'}]
+    post: {operationId: markContainerException, description: '权限：platform:firstleg:container:edit', parameters: [{name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}], requestBody: {$ref: '#/components/requestBodies/ExceptionRequest'}, responses: {'200': {description: OK}}}
+    delete: {operationId: cancelContainerException, description: '权限：platform:firstleg:container:edit', parameters: [{name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}], requestBody: {$ref: '#/components/requestBodies/ExceptionRequest'}, responses: {'200': {description: OK}}}
+  /api/platform/v1/containers/{id}/documents/{documentType}:
+    get:
+      operationId: getContainerDocument
+      description: '权限：platform:firstleg:container:list；仅DO/PU，completed恒为false'
+      parameters: [{$ref: '#/components/parameters/ContainerId'}, {$ref: '#/components/parameters/DocumentType'}]
+      responses: {'200': {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/DocumentEnvelope'}}}}}
+  /api/platform/v1/containers/{id}/documents/{documentType}/upload:
+    post:
+      operationId: uploadContainerDocument
+      description: '权限：platform:firstleg:container:edit；仅DO/PU，无完成动作'
+      parameters: [{$ref: '#/components/parameters/ContainerId'}, {$ref: '#/components/parameters/DocumentType'}, {name: Idempotency-Key, in: header, required: true, schema: {type: string}}]
+      requestBody: {required: true, content: {multipart/form-data: {schema: {type: object, required: [file, expectedVersion], properties: {file: {type: string, format: binary}, expectedVersion: {type: integer, minimum: 0}, operationReason: {type: string, maxLength: 500}}}}}}
+      responses: {'200': {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/DocumentEnvelope'}}}}}
+  /api/platform/v1/containers/{id}/documents/{documentType}/{fileId}/download:
+    get:
+      operationId: downloadContainerDocument
+      description: '权限：platform:firstleg:container:list；Firstleg代理File内部下载，不向调用方暴露内部令牌'
+      parameters: [{$ref: '#/components/parameters/ContainerId'}, {$ref: '#/components/parameters/DocumentType'}, {name: fileId, in: path, required: true, schema: {type: integer, format: int64}}]
+      responses: {'200': {description: file bytes, content: {application/octet-stream: {schema: {type: string, format: binary}}}}}
+components:
+  parameters:
+    ContainerId: {name: id, in: path, required: true, schema: {type: integer, format: int64}}
+    DocumentType: {name: documentType, in: path, required: true, schema: {type: string, enum: [DELIVERY_ORDER, PICKUP_ORDER]}, description: '通用单证仅支持DO/PU；清关使用 /clearance，出口报关使用 loading-list 专用接口'}
+  requestBodies:
+    ExceptionRequest: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ExceptionRequest'}}}}
+  schemas:
+    OverviewEnvelope: {type: object, properties: {code: {type: string}, message: {type: string}, data: {$ref: '#/components/schemas/Overview'}}}
+    DocumentEnvelope: {type: object, properties: {code: {type: string}, message: {type: string}, data: {$ref: '#/components/schemas/Document'}}}
+    Overview:
+      type: object
+      properties:
+        container: {$ref: '#/components/schemas/Container'}
+        loadingPlanId: {type: integer, format: int64}
+        pda: {$ref: '#/components/schemas/PdaSummary'}
+        documents: {type: array, items: {$ref: '#/components/schemas/Document'}}
+        exception: {$ref: '#/components/schemas/ExceptionState'}
+        exceptionHistory: {type: array, items: {$ref: '#/components/schemas/ExceptionHistory'}}
+        timeline: {type: array, items: {$ref: '#/components/schemas/TimelineEntry'}}
+    Container: {type: object, properties: {id: {type: integer, format: int64}, bookingNo: {type: string}, cabinetNo: {type: string}, containerNo: {type: string}, status: {type: string}, warehouseId: {type: integer, format: int64}, warehouseName: {type: string}, voyageNo: {type: string}, vesselName: {type: string}, version: {type: integer, minimum: 0}}}
+    PdaSummary: {type: object, properties: {taskId: {type: integer, format: int64}, loadingPlanId: {type: integer, format: int64}, containerBookingId: {type: integer, format: int64}, taskStatus: {type: string}, taskVersion: {type: integer}, itemCount: {type: integer}, completedItemCount: {type: integer}, unresolvedItemCount: {type: integer}, photoCounts: {type: array, items: {$ref: '#/components/schemas/PhotoCount'}}, photos: {type: array, items: {$ref: '#/components/schemas/Photo'}}, exceptionReasons: {type: array, items: {type: string}}}}
+    PhotoCount: {type: object, properties: {evidenceType: {type: string}, count: {type: integer}}}
+    Photo: {type: object, properties: {evidenceId: {type: integer, format: int64}, tenantId: {type: integer, format: int64}, inboundId: {type: integer, format: int64}, evidenceType: {type: string}, fileId: {type: integer, format: int64}, fileName: {type: string}, status: {type: string}, downloadPath: {type: string}, uploadedAt: {type: string, format: date-time}}}
+    Document: {type: object, properties: {id: {type: integer, format: int64}, documentType: {type: string}, fileId: {type: integer, format: int64}, fileName: {type: string}, fileHash: {type: string}, uploadedBy: {type: integer, format: int64}, uploadedByName: {type: string}, uploadedAt: {type: string, format: date-time}, version: {type: integer}, completed: {type: boolean}}}
+    ExceptionState: {type: object, properties: {active: {type: boolean}, reason: {type: string}, markedBy: {type: integer, format: int64}, markedByName: {type: string}, markedAt: {type: string, format: date-time}}}
+    ExceptionHistory: {type: object, properties: {id: {type: integer, format: int64}, action: {type: string, enum: [MARK, CANCEL]}, reason: {type: string}, operatorId: {type: integer, format: int64}, operatorName: {type: string}, occurredAt: {type: string, format: date-time}}}
+    TimelineEntry: {type: object, properties: {eventType: {type: string}, detail: {type: string}, operatorId: {type: integer, format: int64}, operatorName: {type: string}, occurredAt: {type: string, format: date-time}}}
+    ExceptionRequest: {type: object, required: [expectedVersion, reason], properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, maxLength: 500}}}