add aodb detailed planning artifacts and adrs

2026-04-13 16:12:54 +08:00
parent 973c745762
commit 66d081faaf
15 changed files with 1069 additions and 0 deletions
@@ -0,0 +1,252 @@
+# 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` 作为强语义，而不是展示附注。
+- 不得把查询接口结果当作事件流补偿来源。