feat: Initial commit of Clutch-IQ project

docs/DATABASE_LOGICAL_STRUCTURE.md

@@ -0,0 +1,109 @@
+# Database Logical Structure (ER Diagram)
+
+This diagram illustrates the logical relationships and data flow between the storage layers (L1, L2, L3) in the optimized architecture.
+
+```mermaid
+erDiagram
+    %% ==========================================
+    %% L1 LAYER: RAW DATA (Data Lake)
+    %% ==========================================
+    
+    L1A_raw_iframe_network {
+        string match_id PK
+        json content "Raw API Response"
+        timestamp processed_at
+    }
+
+    L1B_tick_snapshots_parquet {
+        string match_id FK
+        int tick
+        int round
+        json player_states "Positions, HP, Equip"
+        json bomb_state
+        string file_path "Parquet File Location"
+    }
+
+    %% ==========================================
+    %% L2 LAYER: DATA WAREHOUSE (Structured)
+    %% ==========================================
+
+    dim_players {
+        string steam_id_64 PK
+        string username
+        float rating
+        float avg_clutch_win_rate
+    }
+
+    dim_maps {
+        int map_id PK
+        string map_name "de_mirage"
+        string nav_mesh_path
+    }
+
+    fact_matches {
+        string match_id PK
+        int map_id FK
+        timestamp start_time
+        int winner_team
+        int final_score_ct
+        int final_score_t
+    }
+
+    fact_rounds {
+        string round_id PK
+        string match_id FK
+        int round_num
+        int winner_side
+        string win_reason "Elimination/Bomb/Time"
+    }
+
+    L2_Spatial_NavMesh {
+        string map_name PK
+        string zone_id
+        binary distance_matrix "Pre-calculated paths"
+    }
+
+    %% ==========================================
+    %% L3 LAYER: FEATURE STORE (AI Ready)
+    %% ==========================================
+
+    L3_Offline_Features {
+        string snapshot_id PK
+        float feature_tpi "Time Pressure Index"
+        float feature_crossfire "Tactical Score"
+        float feature_equipment_diff
+        int label_is_win "Target Variable"
+    }
+
+    %% ==========================================
+    %% RELATIONSHIPS
+    %% ==========================================
+
+    %% L1 -> L2 Flow
+    L1A_raw_iframe_network ||--|{ fact_matches : "Extracts to"
+    L1A_raw_iframe_network ||--|{ dim_players : "Extracts to"
+    L1B_tick_snapshots_parquet }|--|| fact_matches : "Belongs to"
+    L1B_tick_snapshots_parquet }|--|| fact_rounds : "Details"
+
+    %% L2 Relations
+    fact_matches }|--|| dim_maps : "Played on"
+    fact_rounds }|--|| fact_matches : "Part of"
+    
+    %% L2 -> L3 Flow (Feature Engineering)
+    L3_Offline_Features }|--|| L1B_tick_snapshots_parquet : "Computed from"
+    L3_Offline_Features }|--|| L2_Spatial_NavMesh : "Uses Physics from"
+    L3_Offline_Features }|--|| dim_players : "Enriched with"
+```
+
+## 结构说明 (Structure Explanation)
+
+1.  **L1 源数据层**:
+    *   **左上 (L1A)**: 传统的数据库表，存储比赛结果元数据。
+    *   **左下 (L1B)**: **虚线框表示的文件系统**。虽然物理上是 Parquet 文件，但在逻辑上它是一张巨大的“Tick 级快照表”，通过 `match_id` 与其他层关联。
+
+2.  **L2 数仓层**:
+    *   **核心 (Dim/Fact)**: 标准的星型模型。`fact_matches` 是核心事实表，关联 `dim_players` (人) 和 `dim_maps` (地)。
+    *   **空间 (Spatial)**: 独立的查找表逻辑，为每一张 `dim_maps` 提供物理距离计算支持。
+
+3.  **L3 特征层**:
+    *   **右侧 (Features)**: 这是宽表（Wide Table），每一行直接对应模型的一个训练样本。它不存储原始数据，而是存储**计算后的数值** (如 TPI 指数)，直接由 L1B (位置) + L2 Spatial (距离) + Dim Players (能力) 融合计算而来。