优化

2026-08-21 16:04:16 +08:00
parent dceec6cbed
commit 0e7df9052a
68 changed files with 3985 additions and 267 deletions
@@ -25,6 +25,14 @@ spring:
      max-file-size: 5MB
      max-request-size: 6MB
 baiyue:
+  carrier-schedule:
+    providers:
+      matson-automated: ${MATSON_TRACKING_ENABLED:false}
+      sml-automated: ${SML_TRACKING_ENABLED:false}
+      zim-official-api-enabled: ${ZIM_TRACKING_ENABLED:false}
+      cosco-official-api-enabled: ${COSCO_OPEN_API_ENABLED:false}
+      emc-automated: ${EMC_TRACKING_ENABLED:false}
+      hede-automated: ${HEDE_TRACKING_ENABLED:false}
  security:
    jwt-secret: ${JWT_SECRET:change-me-to-at-least-32-bytes-long-before-start}
    internal-service-token: ${INTERNAL_SERVICE_TOKEN:change-me-to-an-internal-token-at-least-32-bytes-long}
@@ -12,11 +12,11 @@ CREATE TABLE IF NOT EXISTS fl_carrier_schedule_query (
  tracking_type VARCHAR(32) NOT NULL COMMENT '官网跟踪类型：BOOKING_NO订舱号、BILL_OF_LADING提单号、CONTAINER_NO箱号',
  tracking_no VARCHAR(128) NOT NULL COMMENT '提交至船公司官网的跟踪号码',
  official_url VARCHAR(500) NOT NULL COMMENT '船公司官网查询入口地址快照',
-  access_mode VARCHAR(32) NOT NULL COMMENT '官网访问方式：PUBLIC_FORM公开表单、HCAPTCHA人机校验、DYNAMIC_IFRAME动态页面',
-  status VARCHAR(24) NOT NULL COMMENT '任务状态：READY、MANUAL_REQUIRED、ARRIVED、PICKUP_READY、STOPPED',
+  access_mode VARCHAR(32) NOT NULL COMMENT '船司访问方式：PUBLIC_FORM、PUBLIC_WEB_PROXY、PUBLIC_HTML、HCAPTCHA、OFFICIAL_API',
+  status VARCHAR(24) NOT NULL COMMENT '任务操作状态：READY、MANUAL_REQUIRED、STOPPED',
  trigger_source VARCHAR(32) NOT NULL DEFAULT 'MANUAL' COMMENT '任务触发来源：OUTBOUND_CONFIRM或MANUAL',
-  latest_standard_node VARCHAR(32) NULL COMMENT '最近标准船节点',
-  latest_node_observed_at DATETIME(3) NULL COMMENT '最近标准节点观测时间',
+  latest_standard_node VARCHAR(32) NULL COMMENT '最近实际标准船节点；预计事实不推进',
+  latest_node_observed_at DATETIME(3) NULL COMMENT '最近实际标准节点发生时间',
  stopped_at DATETIME(3) NULL COMMENT '任务停止时间',
  stop_reason VARCHAR(500) NULL COMMENT '任务停止原因',
  lease_owner VARCHAR(64) NULL COMMENT '当前调度租约持有者',
@@ -58,12 +58,13 @@ CREATE TABLE IF NOT EXISTS fl_carrier_schedule_query (
  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')),
+    (access_mode IN ('PUBLIC_FORM','PUBLIC_WEB_PROXY','PUBLIC_HTML','HCAPTCHA','OFFICIAL_API')),
  CONSTRAINT chk_carrier_schedule_query_status CHECK
-    (status IN ('READY','MANUAL_REQUIRED','ARRIVED','PICKUP_READY','STOPPED')),
+    (status IN ('READY','MANUAL_REQUIRED','STOPPED')),
  CONSTRAINT chk_carrier_schedule_query_node CHECK
    (latest_standard_node IS NULL OR latest_standard_node IN
-      ('DEPARTED_WAREHOUSE','AT_ORIGIN_PORT','DEPARTED_ORIGIN_PORT','IN_TRANSIT','ARRIVED','PICKUP_READY')),
+      ('DEPARTED_WAREHOUSE','AT_ORIGIN_PORT','LOADED_ON_VESSEL','DEPARTED_ORIGIN_PORT','IN_TRANSIT',
+       'ARRIVED_DESTINATION_PORT','DISCHARGED_FROM_VESSEL','PICKUP_READY','PICKED_UP','EMPTY_RETURNED')),
  CONSTRAINT chk_carrier_schedule_query_attempt CHECK (attempt_count BETWEEN 0 AND 3)
 ) ENGINE=InnoDB COMMENT='六家船公司官网查询任务与三天窗口频控';

@@ -74,7 +75,7 @@ CREATE TABLE IF NOT EXISTS fl_carrier_schedule_query_attempt (
  carrier_code VARCHAR(16) NOT NULL COMMENT '本次尝试的船公司编码快照',
  access_mode VARCHAR(32) NOT NULL COMMENT '本次尝试的官网访问方式快照',
  official_url VARCHAR(500) NOT NULL COMMENT '本次尝试使用的官网地址快照',
-  attempt_status VARCHAR(24) NOT NULL COMMENT '尝试结果：MANUAL_REQUIRED需人工处理、SUCCESS成功、FAILED失败',
+  attempt_status VARCHAR(24) NOT NULL COMMENT '供应商调用结果',
  coverage_gap TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否存在自动化覆盖缺口：0否、1是',
  coverage_gap_code VARCHAR(64) NULL COMMENT '自动化覆盖缺口编码',
  manual_reason VARCHAR(1000) NULL COMMENT '转人工处理原因',
@@ -88,13 +89,13 @@ CREATE TABLE IF NOT EXISTS fl_carrier_schedule_query_attempt (
  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'))
+    (attempt_status IN ('SUCCESS','NO_CHANGE','RETRYABLE_FAILURE','PERMANENT_FAILURE','MANUAL_REQUIRED'))
 ) ENGINE=InnoDB COMMENT='船司官网查询尝试不可变审计';

 CREATE TABLE IF NOT EXISTS fl_carrier_schedule_query_history (
  id BIGINT UNSIGNED NOT NULL COMMENT '船司查询任务历史ID',
  query_id BIGINT UNSIGNED NOT NULL COMMENT '所属船司官网查询任务ID',
-  action VARCHAR(24) NOT NULL COMMENT '历史动作：CREATE创建、ATTEMPT执行查询、MANUAL_RESULT录入人工结果',
+  action VARCHAR(24) NOT NULL COMMENT '查询任务业务历史动作',
  from_version INT UNSIGNED NULL COMMENT '变更前任务版本；创建时为空',
  to_version INT UNSIGNED NOT NULL COMMENT '变更后任务版本',
  reason VARCHAR(1000) NULL COMMENT '操作原因或说明',
@@ -107,7 +108,8 @@ CREATE TABLE IF NOT EXISTS fl_carrier_schedule_query_history (
  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','AUTO_CREATE','MANUAL_RESULT','NODE_OBSERVED','PROVIDER_QUERY','STOP'))
+    (action IN ('CREATE','AUTO_CREATE','MANUAL_RESULT','MANUAL_NODE','NODE_OBSERVED',
+      'EXCEPTION_OBSERVED','PROVIDER_QUERY','STOP'))
 ) ENGINE=InnoDB COMMENT='船司查询任务不可变历史';

 CREATE TABLE IF NOT EXISTS fl_carrier_schedule_node_fact (
@@ -115,6 +117,7 @@ CREATE TABLE IF NOT EXISTS fl_carrier_schedule_node_fact (
  query_id BIGINT UNSIGNED NOT NULL COMMENT '所属查询任务ID',
  event_key VARCHAR(192) NOT NULL COMMENT '供应商编码与供应商事件ID组成的幂等键',
  provider_code VARCHAR(32) NOT NULL COMMENT '轨迹供应商编码',
+  provider_event_id VARCHAR(128) NOT NULL COMMENT '供应商稳定事件ID',
  provider_node_code VARCHAR(64) NOT NULL COMMENT '供应商原始节点编码',
  standard_node VARCHAR(32) NOT NULL COMMENT '标准船节点',
  node_sequence INT UNSIGNED NOT NULL COMMENT '标准节点单调序号',
@@ -131,10 +134,35 @@ CREATE TABLE IF NOT EXISTS fl_carrier_schedule_node_fact (
  KEY idx_carrier_schedule_node_timeline (query_id,node_sequence,observed_at,id),
  CONSTRAINT fk_carrier_schedule_node_query FOREIGN KEY (query_id) REFERENCES fl_carrier_schedule_query(id),
  CONSTRAINT chk_carrier_schedule_node_standard CHECK
-    (standard_node IN ('DEPARTED_WAREHOUSE','AT_ORIGIN_PORT','DEPARTED_ORIGIN_PORT','IN_TRANSIT','ARRIVED','PICKUP_READY')),
-  CONSTRAINT chk_carrier_schedule_node_sequence CHECK (node_sequence IN (10,20,30,40,50,60))
+    (standard_node IN ('DEPARTED_WAREHOUSE','AT_ORIGIN_PORT','LOADED_ON_VESSEL','DEPARTED_ORIGIN_PORT',
+      'IN_TRANSIT','ARRIVED_DESTINATION_PORT','DISCHARGED_FROM_VESSEL','PICKUP_READY','PICKED_UP','EMPTY_RETURNED')),
+  CONSTRAINT chk_carrier_schedule_node_sequence CHECK (node_sequence IN (10,20,30,40,50,60,70,80,90,100))
 ) ENGINE=InnoDB COMMENT='供应商标准船节点不可变事实';

+CREATE TABLE IF NOT EXISTS fl_carrier_schedule_exception_fact (
+  id BIGINT UNSIGNED NOT NULL COMMENT '船节点异常事实ID',
+  query_id BIGINT UNSIGNED NOT NULL COMMENT '所属查询任务ID',
+  event_key VARCHAR(192) NOT NULL COMMENT '供应商编码与供应商事件ID组成的幂等键',
+  provider_code VARCHAR(32) NOT NULL COMMENT '供应商编码',
+  provider_event_id VARCHAR(128) NOT NULL COMMENT '供应商稳定事件ID',
+  provider_status VARCHAR(128) NOT NULL COMMENT '供应商原始异常状态',
+  exception_code VARCHAR(32) NOT NULL COMMENT '平台异常编码',
+  active TINYINT(1) NOT NULL COMMENT '1异常发生；0异常解除',
+  observed_at DATETIME(3) NOT NULL COMMENT '供应商观测时间',
+  location_code VARCHAR(32) NULL COMMENT '地点编码',
+  location_name VARCHAR(128) NULL COMMENT '地点名称',
+  source_reference VARCHAR(500) NULL COMMENT '可审计来源引用',
+  raw_payload_hash CHAR(64) NOT NULL COMMENT '原始响应SHA-256',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '事实入库时间',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_carrier_schedule_exception_event (query_id,event_key),
+  KEY idx_carrier_schedule_exception_timeline (query_id,observed_at,id),
+  CONSTRAINT fk_carrier_schedule_exception_query FOREIGN KEY (query_id) REFERENCES fl_carrier_schedule_query(id),
+  CONSTRAINT chk_carrier_schedule_exception_code CHECK
+    (exception_code IN ('CUSTOMS_HOLD','TERMINAL_HOLD','DOCUMENT_HOLD','UNKNOWN_HOLD')),
+  CONSTRAINT chk_carrier_schedule_exception_active CHECK (active IN (0,1))
+) ENGINE=InnoDB COMMENT='船节点异常发生与解除不可变事实';
+
 CREATE TABLE IF NOT EXISTS fl_carrier_schedule_query_operation (
  id BIGINT UNSIGNED NOT NULL COMMENT '船司查询写操作幂等记录ID',
  query_id BIGINT UNSIGNED NULL COMMENT '关联查询任务ID；创建任务落库前允许为空',
@@ -177,6 +205,8 @@ DROP TRIGGER IF EXISTS trg_carrier_schedule_history_before_update;
 DROP TRIGGER IF EXISTS trg_carrier_schedule_history_before_delete;
 DROP TRIGGER IF EXISTS trg_carrier_schedule_node_before_update;
 DROP TRIGGER IF EXISTS trg_carrier_schedule_node_before_delete;
+DROP TRIGGER IF EXISTS trg_carrier_schedule_exception_before_update;
+DROP TRIGGER IF EXISTS trg_carrier_schedule_exception_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$$
@@ -190,6 +220,10 @@ CREATE TRIGGER trg_carrier_schedule_node_before_update BEFORE UPDATE ON fl_carri
 FOR EACH ROW BEGIN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='标准船节点事实不可修改'; END$$
 CREATE TRIGGER trg_carrier_schedule_node_before_delete BEFORE DELETE ON fl_carrier_schedule_node_fact
 FOR EACH ROW BEGIN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='标准船节点事实不可删除'; END$$
+CREATE TRIGGER trg_carrier_schedule_exception_before_update BEFORE UPDATE ON fl_carrier_schedule_exception_fact
+FOR EACH ROW BEGIN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='船节点异常事实不可修改'; END$$
+CREATE TRIGGER trg_carrier_schedule_exception_before_delete BEFORE DELETE ON fl_carrier_schedule_exception_fact
+FOR EACH ROW BEGIN SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='船节点异常事实不可删除'; END$$
 DELIMITER ;

 USE baiyue_iam;
@@ -253,7 +287,7 @@ BEGIN
       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',
-          'fl_carrier_schedule_node_fact')) <> 5 THEN
+          'fl_carrier_schedule_node_fact','fl_carrier_schedule_exception_fact')) <> 6 THEN
    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='船司查询任务表未完整创建';
  END IF;
  IF (SELECT COUNT(*) FROM baiyue_iam.iam_permission
@@ -1,23 +0,0 @@
-openapi: 3.0.3
-info:
-  title: Carrier Schedule Internal Handoff API
-  version: 1.0.0
-  description: Internal-only handoff contract; it is not a platform or merchant frontend API.
-paths:
-  /internal/firstleg/v1/carrier-schedule-queries/{queryId}/stop:
-    post:
-      summary: Stop tracking after the overseas pickup handoff has completed
-      parameters:
-        - {name: queryId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
-        - {name: X-Internal-Service-Token, in: header, required: true, schema: {type: string}}
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required: [reason]
-              properties:
-                reason: {type: string, minLength: 1, maxLength: 500}
-      responses:
-        '200': {description: Idempotent STOPPED task detail}
@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
  title: Carrier Schedule Query API
  version: 1.0.0
-  description: Phase-4 carrier tracking from domestic outbound confirmation through destination pickup readiness.
+  description: Phase-4 carrier tracking from domestic outbound confirmation through actual empty return.
 paths:
  /api/platform/v1/carrier-schedule-queries/carriers:
    get:
@@ -43,18 +43,21 @@ paths:
      summary: Get task, standardized node facts and immutable business history
      x-permission: platform:firstleg:port-schedule-query:list
      responses:
-        '200': {description: Stable task detail}
+        '200':
+          description: Stable task detail
+          content: {application/json: {schema: {$ref: '#/components/schemas/DetailEnvelope'}}}
  /api/platform/v1/carrier-schedule-queries/{queryId}/history:
    parameters: [{$ref: '#/components/parameters/QueryId'}]
    get:
      summary: Get immutable task history
      x-permission: platform:firstleg:port-schedule-query:list
      responses:
-        '200': {description: CREATE, ATTEMPT and MANUAL_RESULT history}
+        '200': {description: Immutable business history; scheduler attempts are not exposed}
  /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
+      description: This legacy port-schedule association does not append a standard node and never stops tracking; phase-4 manual facts use /manual-nodes.
      x-permission: platform:firstleg:port-schedule-query:manual
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
@@ -63,7 +66,24 @@ paths:
          application/json:
            schema: {$ref: '#/components/schemas/ManualResultRequest'}
      responses:
-        '200': {description: Successful manual fallback and next query time}
+        '200':
+          description: Successful manual fallback and next query time
+          content: {application/json: {schema: {$ref: '#/components/schemas/DetailEnvelope'}}}
+  /api/platform/v1/carrier-schedule-queries/{queryId}/manual-nodes:
+    parameters: [{$ref: '#/components/parameters/QueryId'}]
+    post:
+      summary: Append one immutable manual estimated or actual standard-node fact
+      x-permission: platform:firstleg:port-schedule-query:manual
+      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/ManualNodeRequest'}
+      responses:
+        '200':
+          description: Idempotent fact append; only actualAt advances and actual EMPTY_RETURNED stops
+          content: {application/json: {schema: {$ref: '#/components/schemas/DetailEnvelope'}}}
 components:
  parameters:
    QueryId: {name: queryId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
@@ -71,8 +91,11 @@ components:
  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, ARRIVED, PICKUP_READY, STOPPED]}
-    StandardNode: {type: string, enum: [DEPARTED_WAREHOUSE, AT_ORIGIN_PORT, DEPARTED_ORIGIN_PORT, IN_TRANSIT, ARRIVED, PICKUP_READY]}
+    QueryStatus: {type: string, enum: [READY, MANUAL_REQUIRED, STOPPED]}
+    StandardNode:
+      type: string
+      enum: [DEPARTED_WAREHOUSE, AT_ORIGIN_PORT, LOADED_ON_VESSEL, DEPARTED_ORIGIN_PORT, IN_TRANSIT, ARRIVED_DESTINATION_PORT, DISCHARGED_FROM_VESSEL, PICKUP_READY, PICKED_UP, EMPTY_RETURNED]
+    ExceptionCode: {type: string, enum: [CUSTOMS_HOLD, TERMINAL_HOLD, DOCUMENT_HOLD, UNKNOWN_HOLD]}
    CreateRequest:
      type: object
      required: [expectedVersion, customerId, oceanBookingId, carrierCode, trackingType, trackingNo]
@@ -92,9 +115,112 @@ components:
        expectedVersion: {type: integer, minimum: 0}
        portScheduleId: {type: integer, format: int64, minimum: 1}
        reason: {type: string, minLength: 1, maxLength: 1000}
+    ManualNodeRequest:
+      type: object
+      required: [expectedVersion, standardNode, observedAt, reason]
+      description: estimatedAt and actualAt cannot both be null; estimatedAt never advances the latest actual node.
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        standardNode: {$ref: '#/components/schemas/StandardNode'}
+        observedAt: {type: string, format: date-time}
+        estimatedAt: {type: string, format: date-time, nullable: true}
+        actualAt: {type: string, format: date-time, nullable: true}
+        locationCode: {type: string, maxLength: 32, nullable: true}
+        locationName: {type: string, maxLength: 128, nullable: true}
+        reason: {type: string, minLength: 1, maxLength: 1000}
+    Task:
+      type: object
+      required: [id, queryNo, customerId, oceanBookingId, carrierCode, trackingType, trackingNo, status, triggerSource, version]
+      properties:
+        id: {type: integer, format: int64}
+        queryNo: {type: string}
+        customerId: {type: integer, format: int64}
+        oceanBookingId: {type: integer, format: int64}
+        containerBookingId: {type: integer, format: int64, nullable: true}
+        carrierCode: {$ref: '#/components/schemas/CarrierCode'}
+        trackingType: {$ref: '#/components/schemas/TrackingType'}
+        trackingNo: {type: string}
+        officialUrl: {type: string, nullable: true}
+        accessMode: {type: string, nullable: true}
+        status: {$ref: '#/components/schemas/QueryStatus'}
+        triggerSource: {type: string}
+        latestActualNode: {allOf: [{$ref: '#/components/schemas/StandardNode'}], nullable: true}
+        latestActualAt: {type: string, format: date-time, nullable: true}
+        lastSuccessAt: {type: string, format: date-time, nullable: true}
+        sourceUpdatedAt: {type: string, format: date-time, nullable: true}
+        expiresAt: {type: string, format: date-time, nullable: true}
+        resultPortScheduleId: {type: integer, format: int64, nullable: true}
+        manualReason: {type: string, nullable: true}
+        lastErrorCode: {type: string, nullable: true}
+        lastErrorMessage: {type: string, nullable: true}
+        stoppedAt: {type: string, format: date-time, nullable: true}
+        stopReason: {type: string, nullable: true}
+        version: {type: integer, minimum: 0}
    QueryView:
      type: object
      required: [query, expired]
      properties:
-        query: {type: object, description: Includes triggerSource, latestStandardNode, latestNodeObservedAt, source freshness and stop fields; scheduler leases and raw attempts are never exposed}
+        query: {$ref: '#/components/schemas/Task'}
        expired: {type: boolean}
+    NodeFact:
+      type: object
+      required: [id, providerCode, providerEventId, providerNodeCode, standardNode, nodeSequence, observedAt, rawPayloadHash, createdAt]
+      properties:
+        id: {type: integer, format: int64}
+        providerCode: {type: string, maxLength: 32}
+        providerEventId: {type: string, maxLength: 128}
+        providerNodeCode: {type: string, maxLength: 64}
+        standardNode: {$ref: '#/components/schemas/StandardNode'}
+        nodeSequence: {type: integer, enum: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]}
+        observedAt: {type: string, format: date-time}
+        estimatedAt: {type: string, format: date-time, nullable: true}
+        actualAt: {type: string, format: date-time, nullable: true}
+        locationCode: {type: string, maxLength: 32, nullable: true}
+        locationName: {type: string, maxLength: 128, nullable: true}
+        sourceReference: {type: string, maxLength: 500, nullable: true}
+        rawPayloadHash: {type: string, pattern: '^[0-9a-f]{64}$'}
+        createdAt: {type: string, format: date-time}
+    ExceptionFact:
+      type: object
+      required: [id, providerCode, providerEventId, providerStatus, exceptionCode, active, observedAt, rawPayloadHash, createdAt]
+      properties:
+        id: {type: integer, format: int64}
+        providerCode: {type: string, maxLength: 32}
+        providerEventId: {type: string, maxLength: 128}
+        providerStatus: {type: string, maxLength: 128}
+        exceptionCode: {$ref: '#/components/schemas/ExceptionCode'}
+        active: {type: boolean, description: true means hold occurred; false means released}
+        observedAt: {type: string, format: date-time}
+        locationCode: {type: string, maxLength: 32, nullable: true}
+        locationName: {type: string, maxLength: 128, nullable: true}
+        sourceReference: {type: string, maxLength: 500, nullable: true}
+        rawPayloadHash: {type: string, pattern: '^[0-9a-f]{64}$'}
+        createdAt: {type: string, format: date-time}
+    History:
+      type: object
+      required: [id, action, createdAt]
+      properties:
+        id: {type: integer, format: int64}
+        action: {type: string, enum: [CREATE, AUTO_CREATE, MANUAL_RESULT, MANUAL_NODE, NODE_OBSERVED, EXCEPTION_OBSERVED, PROVIDER_QUERY]}
+        fromVersion: {type: integer, nullable: true}
+        toVersion: {type: integer, nullable: true}
+        reason: {type: string, nullable: true}
+        operatorId: {type: integer, format: int64, nullable: true}
+        operatorName: {type: string, nullable: true}
+        createdAt: {type: string, format: date-time}
+    Detail:
+      type: object
+      required: [query, nodes, exceptions, histories]
+      description: Scheduler lease, attempt and internal execution fields are intentionally absent.
+      properties:
+        query: {$ref: '#/components/schemas/QueryView'}
+        nodes: {type: array, items: {$ref: '#/components/schemas/NodeFact'}}
+        exceptions: {type: array, items: {$ref: '#/components/schemas/ExceptionFact'}}
+        histories: {type: array, items: {$ref: '#/components/schemas/History'}}
+    DetailEnvelope:
+      type: object
+      required: [code, data]
+      properties:
+        code: {type: string, example: '200'}
+        message: {type: string, nullable: true}
+        data: {$ref: '#/components/schemas/Detail'}