1.5 架构原则
学习目标
完成本节后，你将能够：
- 理解当前 repo 为什么向 v4 wide events 演进。
- 解释为什么列表视图和详情视图读不同形态的数据。
- 在修改数据模型时识别性能风险。
1.5.1 当前原则摘要
仓库内的 .agents/ARCHITECTURE_PRINCIPLES.md 给出了核心方向：
- observation/event 是主要分析单位，trace 是相关性句柄。
- 保留高基数上下文，方便探索 unknown unknowns。
- 偏向宽事件，而不是后续再拼接 metrics/logs/traces。
- 列表和聚合视图读 compact projection。
- 大字段只在详情页或必要场景读取。
- API contract 要有规模意识：时间窗口、字段选择、分页。
1.5.2 对代码结构的影响
这些原则直接解释了几个设计：
| 设计 | 原因 |
|---|---|
events_full | 保留完整 input/output/metadata 和丰富上下文 |
events_core | 给列表和常见查询一个轻量投影 |
event-query-builder | 控制字段选择、排序、tenant filter |
FilterState | 前端筛选语义需要能稳定 lower 到查询 |
ClickhouseWriter | 高吞吐写入需要批量、重试和错误处理 |
1.5.3 修改数据模型前的检查
| 问题 | 为什么重要 |
|---|---|
| 这个字段是否属于宽事件 | 决定是否进入 ClickHouse |
| 列表页是否需要它 | 决定是否进入 events_core |
| 是否可能很大 | 决定是否只存在 events_full 或 S3 |
| 是否用于过滤/排序 | 决定是否要索引或列映射 |
| 是否跨租户 | 必须带 project_id |