clutch/docs/OPTIMIZED_ARCHITECTURE.md

Clutch-IQ & Data Warehouse Optimized Architecture (v4.0)

0. 本仓库目录映射

• L1A（网页抓取原始数据，SQLite）：database/L1/L1.db
• L1B（Demo 快照，Parquet）：data/processed/*.parquet
• L2（结构化数仓，SQLite）：database/L2/L2.db
• L3（特征库，SQLite）：database/L3/L3.db
• 离线 ETL：src/etl/（Demo → Parquet）
• 训练：src/training/train.py
• 在线推理：src/inference/app.py

1. 核心设计理念：混合流批架构 (Hybrid Batch/Stream Architecture)

为了同时满足 大规模历史数据分析 (L2/L3) 和 毫秒级实时胜率预测 (Clutch-IQ)，我们将架构优化为现代化的数据平台模式。

核心变更点：

1. 存储分层: 高频快照（Tick/Frame）使用 Parquet；聚合后的业务/特征数据使用 SQLite。
2. 特征解耦: 引入 Feature Store（特征库） 概念，统一管理离线训练与在线推理使用的特征。
3. 闭环反馈（可选）: 预测结果可回写到 L2/L3，用于后续分析与迭代。

---

2. 优化后的分层架构图

graph TD
    %% Data Sources
    Web[5eplay Web Data] --> L1A
    Demo[CS2 .dem Files] --> L1B
    GSI[Real-time GSI Stream] --> Inference

    %% L1 Layer: Data Lake (Raw)
    subgraph "L1: Data Lake (Raw Ingestion)"
        L1A[L1A: Metadata Store] -- SQLite --> L1A_DB[(database/L1/L1.db)]
        L1B[L1B: Telemetry Engine] -- Parquet --> L1B_Files[(data/processed/*.parquet)]
    end

    %% L2 Layer: Data Warehouse (Clean)
    subgraph "L2: Data Warehouse (Structured)"
        L1A_DB --> L2_ETL
        L1B_Files --> L2_ETL[L2 Processors]
        L2_ETL --> L2_SQL[(database/L2/L2.db)]
        L2_ETL --> L2_Spatial[(L2_Spatial: NavMesh/Grids)]
    end

    %% L3 Layer: Feature Store (Analytics & AI)
    subgraph "L3: Feature Store (Machine Learning)"
        L2_SQL --> L3_Offline
        L2_Spatial --> L3_Offline
        L3_Offline[Offline Feature Build] --> L3_DB[(database/L3/L3.db)]
        L3_Offline -- XGBoost --> Model[Clutch Predictor Model]
        
        L3_DB --> Inference
    end

    %% Application Layer
    subgraph "App: Clutch-IQ Service"
        Inference[Inference Engine]
        Model --> Inference
        Inference --> API[Win Prob API]
    end
    
    API -.-> L2_SQL : Feedback Loop (Log Predictions)

---

3. 层级详细定义与优化点

L1: 数据湖层 (Data Lake)

• L1A (Web Metadata): 保持现状。
  • 存储: SQLite
  • 内容: 比赛元数据、比分。
• L1B (Demo Telemetry) [优化重点]:
  • 变更: 不把 Tick/Frame 快照直接塞进 SQLite。Demo 快照数据量大（64/128 tick/s），SQLite 容易膨胀且读写慢。
  • 优化: 使用 Parquet（列式存储）保存快照，便于批量训练与分析。
  • 优势: 高压缩、高吞吐、与 Pandas/XGBoost 训练流程匹配。

L2: 数仓层 (Data Warehouse)

• L2 Core (Business): 保持现状。
  • 存储: SQLite
  • 内容: 玩家维度 (Dim_Player)、比赛维度 (Fact_Match) 的清洗数据。
• L2 Spatial (Physics) [新增]:
  • 内容: 地图导航网格 (Nav Mesh)、距离矩阵、地图区域划分。
  • 用途: 为 L3 提供物理计算基础（如计算 A 点到 B 点的真实跑图时间，而非直线距离）。

L3: 特征商店层 (Feature Store)

• 定义: 不再只是一个 DB，而是一套特征注册表。
• Offline Store:
  • 从 L2 聚合计算玩家/队伍特征，落到 L3（便于复用与快速查询）。
  • 训练标签（Label）仍来自比赛结果/回合结果（例如 round_winner）。
• Online Store:
  • 在线推理时使用的快速查表数据（例如玩家能力/地图预计算数据）。
  • 例子: 地图距离矩阵（预先算好的点对点距离），推理时查表以降低延迟。

---

4. 全方位评价 (Comprehensive Evaluation)

✅ 优势 (Pros)

1. 高性能 (Performance):

   • 引入 Parquet 解决了海量 Tick 数据的 I/O 瓶颈。
   • 预计算 L2 Spatial 数据，确保实时预测延迟低于 50ms。

2. 可扩展性 (Scalability):

   • L1B 和 L3 的文件式存储架构支持分布式处理（未来可迁移至 Spark/Dask）。
   • 新增地图只需更新 L2 Spatial，不影响模型逻辑。

3. 即时性与准确性平衡 (Real-time Readiness):

   • 架构明确区分了“离线训练”（追求精度，处理慢）和“在线推理”（追求速度，查表为主）。

4. 模块化 (Modularity):

   • L1/L2/L3 职责边界清晰，数据污染风险低。Clutch-IQ 只是 L3 的一个“消费者”，不破坏原有数仓结构。

⚠️ 潜在挑战 (Cons)

1. 技术栈复杂性:

   • 引入 Parquet 需要 Python pyarrow 或 fastparquet 库支持。
   • 需要维护文件系统（File System）和数据库（SQLite）两种存储范式。

2. 冷启动成本:

   • L2 Spatial 需要针对每张地图（Mirage, Inferno, Nuke...）单独构建导航网格数据，前期工作量大。

---

5. 结论

该优化架构从单机分析型向工业级 AI 生产型转变。它不仅能支持当前的胜率预测，更为未来扩展（如：反作弊行为分析、AI 教练系统）打下了坚实的底层基础。