feat(firstleg): add compliant carrier schedule queries

2026-08-10 12:20:05 +08:00
parent 5c1c6a1a07
commit edd5108625
21 changed files with 1654 additions and 0 deletions
@@ -0,0 +1,226 @@
+SET NAMES utf8mb4;
+USE baiyue_firstleg;
+
+CREATE TABLE IF NOT EXISTS fl_carrier_schedule_query (
+  id BIGINT UNSIGNED NOT NULL,
+  query_no VARCHAR(40) NOT NULL,
+  customer_id BIGINT UNSIGNED NOT NULL COMMENT '当前产品客户ID',
+  ocean_booking_id BIGINT UNSIGNED NOT NULL,
+  container_booking_id BIGINT UNSIGNED NULL,
+  container_scope_id BIGINT UNSIGNED GENERATED ALWAYS AS (COALESCE(container_booking_id,0)) STORED,
+  carrier_code VARCHAR(16) NOT NULL COMMENT 'MATSON/SML/ZIM/COSCO/EMC/HEDE',
+  tracking_type VARCHAR(32) NOT NULL COMMENT 'BOOKING_NO/BILL_OF_LADING/CONTAINER_NO',
+  tracking_no VARCHAR(128) NOT NULL,
+  official_url VARCHAR(500) NOT NULL,
+  access_mode VARCHAR(32) NOT NULL COMMENT 'PUBLIC_FORM/HCAPTCHA/DYNAMIC_IFRAME',
+  status VARCHAR(24) NOT NULL COMMENT 'READY/MANUAL_REQUIRED/SUCCESS',
+  window_started_at DATETIME(3) NOT NULL,
+  attempt_count INT UNSIGNED NOT NULL DEFAULT 0,
+  next_allowed_at DATETIME(3) NOT NULL,
+  last_attempt_at DATETIME(3) NULL,
+  last_success_at DATETIME(3) NULL,
+  source_updated_at DATETIME(3) NULL,
+  expires_at DATETIME(3) NULL,
+  result_port_schedule_id BIGINT UNSIGNED NULL,
+  last_attempt_status VARCHAR(24) NULL,
+  manual_reason VARCHAR(1000) NULL,
+  last_error_code VARCHAR(64) NULL,
+  last_error_message VARCHAR(1000) NULL,
+  remark VARCHAR(1000) NULL,
+  created_by BIGINT UNSIGNED NOT NULL,
+  created_by_name VARCHAR(64) NULL,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_by BIGINT UNSIGNED NOT NULL,
+  updated_by_name VARCHAR(64) NULL,
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  version INT UNSIGNED NOT NULL DEFAULT 0,
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_carrier_schedule_query_no (query_no),
+  UNIQUE KEY uk_carrier_schedule_query_scope
+    (customer_id,ocean_booking_id,container_scope_id,carrier_code,tracking_type,tracking_no),
+  KEY idx_carrier_schedule_query_due (status,next_allowed_at,id),
+  KEY idx_carrier_schedule_query_customer (customer_id,updated_at,id),
+  KEY idx_carrier_schedule_query_expiry (expires_at,id),
+  CONSTRAINT fk_carrier_schedule_query_booking FOREIGN KEY (ocean_booking_id) REFERENCES fl_ocean_booking(id),
+  CONSTRAINT fk_carrier_schedule_query_container FOREIGN KEY (container_booking_id) REFERENCES fl_container_booking(id),
+  CONSTRAINT fk_carrier_schedule_query_result FOREIGN KEY (result_port_schedule_id) REFERENCES fl_port_schedule(id),
+  CONSTRAINT chk_carrier_schedule_query_customer CHECK (customer_id > 0),
+  CONSTRAINT chk_carrier_schedule_query_carrier CHECK
+    (carrier_code IN ('MATSON','SML','ZIM','COSCO','EMC','HEDE')),
+  CONSTRAINT chk_carrier_schedule_query_tracking CHECK
+    (tracking_type IN ('BOOKING_NO','BILL_OF_LADING','CONTAINER_NO')),
+  CONSTRAINT chk_carrier_schedule_query_access CHECK
+    (access_mode IN ('PUBLIC_FORM','HCAPTCHA','DYNAMIC_IFRAME')),
+  CONSTRAINT chk_carrier_schedule_query_status CHECK
+    (status IN ('READY','MANUAL_REQUIRED','SUCCESS')),
+  CONSTRAINT chk_carrier_schedule_query_attempt CHECK (attempt_count BETWEEN 0 AND 3)
+) ENGINE=InnoDB COMMENT='六家船公司官网查询任务与三天窗口频控';
+
+CREATE TABLE IF NOT EXISTS fl_carrier_schedule_query_attempt (
+  id BIGINT UNSIGNED NOT NULL,
+  query_id BIGINT UNSIGNED NOT NULL,
+  window_attempt_no INT UNSIGNED NOT NULL,
+  carrier_code VARCHAR(16) NOT NULL,
+  access_mode VARCHAR(32) NOT NULL,
+  official_url VARCHAR(500) NOT NULL,
+  attempt_status VARCHAR(24) NOT NULL,
+  coverage_gap TINYINT(1) NOT NULL DEFAULT 0,
+  coverage_gap_code VARCHAR(64) NULL,
+  manual_reason VARCHAR(1000) NULL,
+  error_code VARCHAR(64) NULL,
+  error_message VARCHAR(1000) NULL,
+  operator_id BIGINT UNSIGNED NOT NULL,
+  operator_name VARCHAR(64) NULL,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (id),
+  KEY idx_carrier_schedule_attempt_query (query_id,created_at,id),
+  CONSTRAINT fk_carrier_schedule_attempt_query FOREIGN KEY (query_id) REFERENCES fl_carrier_schedule_query(id),
+  CONSTRAINT chk_carrier_schedule_attempt_no CHECK (window_attempt_no BETWEEN 1 AND 3),
+  CONSTRAINT chk_carrier_schedule_attempt_status CHECK
+    (attempt_status IN ('MANUAL_REQUIRED','SUCCESS','FAILED'))
+) ENGINE=InnoDB COMMENT='船司官网查询尝试不可变审计';
+
+CREATE TABLE IF NOT EXISTS fl_carrier_schedule_query_history (
+  id BIGINT UNSIGNED NOT NULL,
+  query_id BIGINT UNSIGNED NOT NULL,
+  action VARCHAR(24) NOT NULL,
+  from_version INT UNSIGNED NULL,
+  to_version INT UNSIGNED NOT NULL,
+  reason VARCHAR(1000) NULL,
+  before_snapshot JSON NULL,
+  after_snapshot JSON NOT NULL,
+  operator_id BIGINT UNSIGNED NOT NULL,
+  operator_name VARCHAR(64) NULL,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (id),
+  KEY idx_carrier_schedule_history_query (query_id,created_at,id),
+  CONSTRAINT fk_carrier_schedule_history_query FOREIGN KEY (query_id) REFERENCES fl_carrier_schedule_query(id),
+  CONSTRAINT chk_carrier_schedule_history_action CHECK (action IN ('CREATE','ATTEMPT','MANUAL_RESULT'))
+) ENGINE=InnoDB COMMENT='船司查询任务不可变历史';
+
+CREATE TABLE IF NOT EXISTS fl_carrier_schedule_query_operation (
+  id BIGINT UNSIGNED NOT NULL,
+  query_id BIGINT UNSIGNED NULL,
+  operator_id BIGINT UNSIGNED NOT NULL,
+  operation VARCHAR(24) NOT NULL,
+  idempotency_key VARCHAR(128) NOT NULL,
+  request_hash CHAR(64) NOT NULL,
+  status VARCHAR(16) NOT NULL DEFAULT 'PROCESSING',
+  result_json JSON NULL,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  completed_at DATETIME(3) NULL,
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_carrier_schedule_operation (operator_id,idempotency_key),
+  KEY idx_carrier_schedule_operation_query (query_id,created_at,id),
+  CONSTRAINT fk_carrier_schedule_operation_query FOREIGN KEY (query_id) REFERENCES fl_carrier_schedule_query(id),
+  CONSTRAINT chk_carrier_schedule_operation_status CHECK (status IN ('PROCESSING','SUCCESS'))
+) ENGINE=InnoDB COMMENT='船司查询写操作幂等与请求摘要';
+
+DROP TRIGGER IF EXISTS trg_carrier_schedule_query_before_insert;
+DELIMITER $$
+CREATE TRIGGER trg_carrier_schedule_query_before_insert BEFORE INSERT ON fl_carrier_schedule_query FOR EACH ROW
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM fl_ocean_booking booking
+                  WHERE booking.id=NEW.ocean_booking_id AND booking.customer_id=NEW.customer_id) THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='船司查询客户与订舱不一致';
+  END IF;
+  IF NEW.container_booking_id IS NOT NULL AND NOT EXISTS (
+    SELECT 1 FROM fl_ocean_booking_container_allocation allocation
+     WHERE allocation.ocean_booking_id=NEW.ocean_booking_id
+       AND allocation.container_booking_id=NEW.container_booking_id
+  ) THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='船司查询柜次未分配至订舱';
+  END IF;
+END$$
+DELIMITER ;
+
+DROP TRIGGER IF EXISTS trg_carrier_schedule_attempt_before_update;
+DROP TRIGGER IF EXISTS trg_carrier_schedule_attempt_before_delete;
+DROP TRIGGER IF EXISTS trg_carrier_schedule_history_before_update;
+DROP TRIGGER IF EXISTS trg_carrier_schedule_history_before_delete;
+DELIMITER $$
+CREATE TRIGGER trg_carrier_schedule_attempt_before_update BEFORE UPDATE ON fl_carrier_schedule_query_attempt
+FOR EACH ROW BEGIN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='船司查询尝试不可修改'; END$$
+CREATE TRIGGER trg_carrier_schedule_attempt_before_delete BEFORE DELETE ON fl_carrier_schedule_query_attempt
+FOR EACH ROW BEGIN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='船司查询尝试不可删除'; END$$
+CREATE TRIGGER trg_carrier_schedule_history_before_update BEFORE UPDATE ON fl_carrier_schedule_query_history
+FOR EACH ROW BEGIN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='船司查询历史不可修改'; END$$
+CREATE TRIGGER trg_carrier_schedule_history_before_delete BEFORE DELETE ON fl_carrier_schedule_query_history
+FOR EACH ROW BEGIN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='船司查询历史不可删除'; END$$
+DELIMITER ;
+
+USE baiyue_iam;
+DROP PROCEDURE IF EXISTS assert_carrier_schedule_query_permission_ids;
+DELIMITER $$
+CREATE PROCEDURE assert_carrier_schedule_query_permission_ids()
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM iam_permission
+     WHERE (id BETWEEN 5102184 AND 5102188
+            AND permission_code <> CASE id
+              WHEN 5102184 THEN 'platform:firstleg:port-schedule-query:list'
+              WHEN 5102185 THEN 'platform:firstleg:port-schedule-query:view'
+              WHEN 5102186 THEN 'platform:firstleg:port-schedule-query:create'
+              WHEN 5102187 THEN 'platform:firstleg:port-schedule-query:attempt'
+              WHEN 5102188 THEN 'platform:firstleg:port-schedule-query:manual'
+            END)
+        OR (permission_code LIKE 'platform:firstleg:port-schedule-query:%'
+            AND (tenant_id<>0 OR app_code<>'PLATFORM' OR id NOT BETWEEN 5102184 AND 5102188))
+  ) THEN
+    SIGNAL SQLSTATE '45000'
+      SET MESSAGE_TEXT='三期船司查询权限迁移失败：5102184-5102188 ID或权限码被占用';
+  END IF;
+END$$
+DELIMITER ;
+CALL assert_carrier_schedule_query_permission_ids();
+DROP PROCEDURE IF EXISTS assert_carrier_schedule_query_permission_ids;
+
+INSERT INTO iam_permission
+  (id,tenant_id,app_code,permission_type,parent_id,permission_code,permission_name,
+   route_path,http_method,sort_no,status,built_in,deleted)
+VALUES
+  (5102184,0,'PLATFORM','BUTTON',5102180,'platform:firstleg:port-schedule-query:list','查询船司任务',NULL,'GET',40,'ACTIVE',1,0),
+  (5102185,0,'PLATFORM','BUTTON',5102180,'platform:firstleg:port-schedule-query:view','查看船司任务',NULL,'GET',50,'ACTIVE',1,0),
+  (5102186,0,'PLATFORM','BUTTON',5102180,'platform:firstleg:port-schedule-query:create','创建船司任务',NULL,'POST',60,'ACTIVE',1,0),
+  (5102187,0,'PLATFORM','BUTTON',5102180,'platform:firstleg:port-schedule-query:attempt','执行船司查询',NULL,'POST',70,'ACTIVE',1,0),
+  (5102188,0,'PLATFORM','BUTTON',5102180,'platform:firstleg:port-schedule-query:manual','录入人工结果',NULL,'POST',80,'ACTIVE',1,0)
+ON DUPLICATE KEY UPDATE tenant_id=0,app_code='PLATFORM',permission_type=VALUES(permission_type),
+ permission_code=VALUES(permission_code),permission_name=VALUES(permission_name),parent_id=VALUES(parent_id),
+ route_path=VALUES(route_path),http_method=VALUES(http_method),sort_no=VALUES(sort_no),
+ status='ACTIVE',built_in=1,deleted=0;
+
+INSERT IGNORE INTO iam_role_permission(role_id,permission_id,tenant_id)
+SELECT role.id,permission.id,0 FROM iam_role role JOIN iam_permission permission
+  ON permission.tenant_id=0 AND permission.app_code='PLATFORM'
+ AND permission.permission_code LIKE 'platform:firstleg:port-schedule-query:%'
+WHERE role.tenant_id=0 AND role.role_code IN ('PLATFORM_ADMIN','ORDER_OPERATOR');
+
+USE baiyue_firstleg;
+DROP PROCEDURE IF EXISTS assert_carrier_schedule_query_schema;
+DELIMITER $$
+CREATE PROCEDURE assert_carrier_schedule_query_schema()
+BEGIN
+  IF (SELECT COUNT(*) FROM information_schema.tables
+       WHERE table_schema='baiyue_firstleg' AND table_name IN
+         ('fl_carrier_schedule_query','fl_carrier_schedule_query_attempt',
+          'fl_carrier_schedule_query_history','fl_carrier_schedule_query_operation')) <> 4 THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='船司查询任务表未完整创建';
+  END IF;
+  IF (SELECT COUNT(*) FROM baiyue_iam.iam_permission
+       WHERE tenant_id=0 AND id BETWEEN 5102184 AND 5102188
+         AND permission_code LIKE 'platform:firstleg:port-schedule-query:%') <> 5 THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='船司查询任务权限未完整创建';
+  END IF;
+  IF (SELECT COUNT(*)
+        FROM baiyue_iam.iam_role_permission role_permission
+        JOIN baiyue_iam.iam_role role ON role.id=role_permission.role_id
+        JOIN baiyue_iam.iam_permission permission ON permission.id=role_permission.permission_id
+       WHERE role.tenant_id=0 AND role.role_code IN ('PLATFORM_ADMIN','ORDER_OPERATOR')
+         AND permission.tenant_id=0
+         AND permission.permission_code LIKE 'platform:firstleg:port-schedule-query:%') <> 10 THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='船司查询任务角色授权未完整创建';
+  END IF;
+END$$
+DELIMITER ;
+CALL assert_carrier_schedule_query_schema();
+DROP PROCEDURE IF EXISTS assert_carrier_schedule_query_schema;
@@ -0,0 +1,113 @@
+openapi: 3.0.3
+info:
+  title: Carrier Schedule Query API
+  version: 1.0.0
+  description: Six-carrier query tasks with a three-day window, at most three attempts, and explicit manual fallback.
+paths:
+  /api/platform/v1/carrier-schedule-queries/carriers:
+    get:
+      summary: List official carrier sources and compliant access modes
+      responses:
+        '200': {description: MATSON, SML, ZIM, COSCO, EMC and HEDE descriptors}
+  /api/platform/v1/carrier-schedule-queries:
+    get:
+      summary: Query carrier schedule tasks
+      parameters:
+        - {name: customerId, in: query, schema: {type: integer, format: int64, minimum: 1}}
+        - {name: oceanBookingId, in: query, schema: {type: integer, format: int64, minimum: 1}}
+        - {name: containerBookingId, in: query, schema: {type: integer, format: int64, minimum: 1}}
+        - {name: carrierCode, in: query, schema: {$ref: '#/components/schemas/CarrierCode'}}
+        - {name: status, in: query, schema: {$ref: '#/components/schemas/QueryStatus'}}
+        - {name: expired, in: query, schema: {type: boolean}}
+        - {name: keyword, in: query, schema: {type: string, maxLength: 128}}
+        - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
+        - {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 200, default: 20}}
+      responses:
+        '200': {description: Query tasks with source, freshness and rate-limit fields}
+    post:
+      summary: Create a query task linked to a real booking and allocated container
+      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/CreateRequest'}
+      responses:
+        '200': {description: Created task or idempotent replay}
+  /api/platform/v1/carrier-schedule-queries/{queryId}:
+    parameters: [{$ref: '#/components/parameters/QueryId'}]
+    get:
+      summary: Get task, immutable attempts and history
+      responses:
+        '200': {description: Stable task detail}
+  /api/platform/v1/carrier-schedule-queries/{queryId}/history:
+    parameters: [{$ref: '#/components/parameters/QueryId'}]
+    get:
+      summary: Get immutable task history
+      responses:
+        '200': {description: CREATE, ATTEMPT and MANUAL_RESULT history}
+  /api/platform/v1/carrier-schedule-queries/{queryId}/attempts:
+    parameters: [{$ref: '#/components/parameters/QueryId'}]
+    post:
+      summary: Execute the compliant carrier strategy; never bypass captcha or dynamic pages
+      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/AttemptRequest'}
+      responses:
+        '200': {description: MANUAL_REQUIRED with coverageGap when no public structured API is available}
+  /api/platform/v1/carrier-schedule-queries/{queryId}/manual-results:
+    parameters: [{$ref: '#/components/parameters/QueryId'}]
+    post:
+      summary: Link a validated manual port-schedule observation without pretending automated success
+      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/ManualResultRequest'}
+      responses:
+        '200': {description: Successful manual fallback and next query time}
+components:
+  parameters:
+    QueryId: {name: queryId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
+  schemas:
+    CarrierCode: {type: string, enum: [MATSON, SML, ZIM, COSCO, EMC, HEDE]}
+    TrackingType: {type: string, enum: [BOOKING_NO, BILL_OF_LADING, CONTAINER_NO]}
+    QueryStatus: {type: string, enum: [READY, MANUAL_REQUIRED, SUCCESS]}
+    CreateRequest:
+      type: object
+      required: [expectedVersion, customerId, oceanBookingId, carrierCode, trackingType, trackingNo]
+      properties:
+        expectedVersion: {type: integer, minimum: 0, maximum: 0}
+        customerId: {type: integer, format: int64, minimum: 1}
+        oceanBookingId: {type: integer, format: int64, minimum: 1}
+        containerBookingId: {type: integer, format: int64, minimum: 1, nullable: true}
+        carrierCode: {$ref: '#/components/schemas/CarrierCode'}
+        trackingType: {$ref: '#/components/schemas/TrackingType'}
+        trackingNo: {type: string, minLength: 1, maxLength: 128}
+        remark: {type: string, nullable: true, maxLength: 1000}
+    AttemptRequest:
+      type: object
+      required: [expectedVersion]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        reason: {type: string, nullable: true, maxLength: 1000}
+    ManualResultRequest:
+      type: object
+      required: [expectedVersion, portScheduleId, reason]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        portScheduleId: {type: integer, format: int64, minimum: 1}
+        reason: {type: string, minLength: 1, maxLength: 1000}
+    QueryView:
+      type: object
+      required: [query, expired, maxAttempts, nextAllowedAt]
+      properties:
+        query: {type: object, description: Includes source, attemptCount, lastAttemptAt, lastSuccessAt, sourceUpdatedAt and manualReason}
+        expired: {type: boolean}
+        maxAttempts: {type: integer, enum: [3]}
+        nextAllowedAt: {type: string, format: date-time}