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. 优化后的分层架构图

```mermaid
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 教练系统）打下了坚实的底层基础。