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

# AODB 事件 Schema 草案

## 1. 文档定位

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

## 2. 统一事件信封

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

```json
{
  "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 标准化流程。

```json
{
  "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`

用途：

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

```json
{
  "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 发生变化，是对外共享的关键事件。

```json
{
  "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`

用途：

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

```json
{
  "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`

用途：

- 表示资源分配已生效。

```json
{
  "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`

用途：

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

```json
{
  "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`

用途：

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

```json
{
  "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`

用途：

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

```json
{
  "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`

用途：

- 表示复核任务已创建。

```json
{
  "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` 作为强语义，而不是展示附注。
- 不得把查询接口结果当作事件流补偿来源。