my-vault/airport-wiki/concepts/aodb/AODB 事件 Schema 草案.md

AODB 事件 Schema 草案

1. 文档定位

本文档定义 AODB MVP 阶段的统一事件信封和关键事件 payload 草案，用于实现、联调和消费者契约评审。

2. 统一事件信封

所有事件必须使用统一 envelope：

{
  "event_id": "uuid",
  "event_type": "PublishedFactUpdated",
  "schema_version": 1,
  "occurred_at": "2026-04-13T16:00:00Z",
  "produced_at": "2026-04-13T16:00:01Z",
  "source": {
    "system": "aodb-flight-service",
    "organization": "airport-ops",
    "channel": "internal"
  },
  "idempotency_key": "string",
  "correlation_id": "string",
  "aggregate_type": "FlightOperation",
  "aggregate_id": "flight_123",
  "quality": {
    "confidence": "confirmed",
    "flags": []
  },
  "payload": {}
}

3. 字段说明

字段	说明	必填
event_id	全局唯一事件 ID	是
event_type	事件类型	是
schema_version	schema 版本	是
occurred_at	业务发生时间	是
produced_at	AODB 产出时间	是
source	来源系统和组织	是
idempotency_key	幂等键	是
correlation_id	关联链路 ID	是
aggregate_type	聚合类型	是
aggregate_id	聚合 ID	是
quality	可信度和数据质量标记	否
payload	事件负载	是

4. 事件列表

4.1 FlightImported

用途：

• 表示计划航班已进入 AODB 标准化流程。

{
  "payload": {
    "flight_id": "flight_123",
    "flight_key": "MU-1234-2026-04-13-1",
    "op_date": "2026-04-13",
    "carrier": "MU",
    "flight_number": "1234",
    "leg_no": "1",
    "batch_id": "ssim_batch_001"
  }
}

4.2 MilestoneObserved

用途：

• 表示接收到一条原始或标准化里程碑观测。

{
  "payload": {
    "observation_id": "obs_001",
    "flight_id": "flight_123",
    "milestone_type": "ALDT",
    "observed_value": "2026-04-13T15:22:00Z",
    "source_sequence": "aidx-889",
    "raw_message_ref": "msg_777"
  }
}

4.3 PublishedFactUpdated

用途：

• 表示 Published Fact 发生变化，是对外共享的关键事件。

{
  "payload": {
    "flight_id": "flight_123",
    "field_name": "ALDT",
    "previous_value": "2026-04-13T15:20:00Z",
    "current_value": "2026-04-13T15:22:00Z",
    "decision_ref": "decision_321",
    "published_state_version": 9
  }
}

4.4 TurnaroundLinked

用途：

• 表示到离港航班形成过站关联。

{
  "payload": {
    "turnaround_id": "ta_001",
    "arrival_flight_id": "flight_arr_001",
    "departure_flight_id": "flight_dep_001",
    "tail_number": "B-1234",
    "link_confidence": "estimated"
  }
}

4.5 ResourceAssigned

用途：

• 表示资源分配已生效。

{
  "payload": {
    "allocation_id": "alloc_001",
    "resource_id": "stand_12",
    "resource_type": "Stand",
    "flight_id": "flight_123",
    "turnaround_id": "ta_001",
    "lock_type": "hard",
    "assignment_source": "manual",
    "validity_window": {
      "start_at": "2026-04-13T15:00:00Z",
      "end_at": "2026-04-13T16:30:00Z"
    }
  }
}

4.6 ResourceConflictDetected

用途：

• 表示资源冲突被识别出来。

{
  "payload": {
    "resource_id": "stand_12",
    "resource_type": "Stand",
    "conflict_type": "time_overlap",
    "affected_allocations": ["alloc_001", "alloc_002"],
    "affected_flights": ["flight_123", "flight_456"],
    "rule_ref": "resource.time-window.v1"
  }
}

4.7 AlertRaised

用途：

• 表示告警进入打开状态。

{
  "payload": {
    "alert_id": "alert_001",
    "alert_type": "resource_conflict",
    "severity": "high",
    "related_aggregate_type": "ResourceAllocation",
    "related_aggregate_id": "alloc_001",
    "summary": "Stand 12 conflict detected"
  }
}

4.8 ManualDecisionRecorded

用途：

• 表示人工裁决已经完成。

{
  "payload": {
    "decision_id": "decision_321",
    "decision_type": "field_override",
    "target_aggregate_type": "FlightOperation",
    "target_aggregate_id": "flight_123",
    "field_name": "ALDT",
    "selected_value": "2026-04-13T15:22:00Z",
    "reason": "tower confirmation",
    "operator": "ops_user_007"
  }
}

4.9 ReviewTaskOpened

用途：

• 表示复核任务已创建。

{
  "payload": {
    "review_task_id": "review_001",
    "review_type": "milestone_conflict",
    "target_aggregate_type": "FlightOperation",
    "target_aggregate_id": "flight_123",
    "reason": "conflicting ALDT observations"
  }
}

5. 版本演进规则

• schema_version 必须随破坏性变更升级。
• 非破坏性新增字段只允许追加，不允许重定义现有字段含义。
• 下游必须按“忽略未知字段”实现兼容。
• 被废弃字段必须至少保留一个发布周期。

6. Topic 建议

Topic	用途	分区键
aodb.flight.events	FlightOperation 和 Published Fact 事件	flight_id
aodb.resource.events	资源分配和冲突事件	flight_id
aodb.alert.events	告警和处置事件	alert_id
aodb.review.events	人工复核和裁决事件	target_aggregate_id

7. 消费者要求

• 必须按 event_id 去重。
• 必须处理至少一次投递。
• 必须把 quality.flags 作为强语义，而不是展示附注。
• 不得把查询接口结果当作事件流补偿来源。