# YRTV 项目说明 till 0.5.0

## 项目概览
yrtv这一块。

数据来源与处理核心包括：
- 比赛页面的 iframe JSON 数据（`iframe_network.json`）
- 可选的 demo 文件（`.zip/.dem`）
- L1A/L2/L3 分层数据库建模与校验

## 数据流程
1. **下载与落盘**  
   通过 `downloader/downloader.py` 抓取比赛页面数据，生成 `output_arena/<match_id>/iframe_network.json`，并可同时下载 demo 文件。
2. **L1A 入库（原始 JSON）**  
   `ETL/L1A.py` 将 `output_arena/*/iframe_network.json` 批量写入 `database/L1A/L1A.sqlite`。
3. **L2 入库（结构化事实表/维度表）**  
   `ETL/L2_Builder.py` 读取 L1A 数据，按 `database/L2/schema.sql` 构建维度表与事实表，生成 `database/L2/L2_Main.sqlite`。
4. **L3 入库（特征集市）**
   `ETL/L3_Builder.py` 读取 L2 数据，计算 Basic 及 6 大挖掘能力维度特征，生成 `database/L3/L3_Features.sqlite`。
5. **质量校验与覆盖分析**  
   `ETL/verify/verify_L2.py` 与 `ETL/verify/verify_deep.py` 用于 L2 字段覆盖与逻辑检查。

## 目录结构
```
yrtv/
├── downloader/                 # 下载器（抓取 iframe JSON 与 demo）
│   ├── downloader.py
│   └── README.md
├── ETL/                        # ETL 脚本
│   ├── L1A.py
│   ├── L2_Builder.py
│   ├── L3_Builder.py
│   ├── README.md
│   └── verify/
│       ├── verify_L2.py
│       └── verify_deep.py
├── database/
│   ├── L1A/                    # L1A SQLite 与说明
│   ├── L1B/                    # L1B 目录（demo 解析结果说明）
│   ├── L2/                     # L2 SQLite 与 schema
│   ├── L3/                     # L3 SQLite 与 schema (特征集市)
│   └── original_json_schema/   # schema 扁平化与未覆盖字段清单
└── utils/
    └── json_extractor/         # JSON Schema 抽取工具
```

## 环境要求
- Python 3.11.4+
- Playwright（下载器依赖）
- pandas、numpy（校验脚本依赖）


## 数据库层级说明
### L1A
- **用途**：保存原始 iframe JSON
- **输入**：`output_arena/*/iframe_network.json`
- **输出**：`database/L1A/L1A.sqlite`
- **脚本**：`ETL/L1A.py`

### L1B
- **用途**：保存 demo 解析后的原始数据（由 demoparser2 产出）
- **输出**：`database/L1B/L1B.sqlite`
- 当前仓库提供目录与说明，解析流程需结合外部工具执行

### L2
结构化事实表/维度表数据库，覆盖比赛、玩家、回合与经济等数据：
- **Schema**：`database/L2/schema.sql`
- **输出**：`database/L2/L2_Main.sqlite`
- **核心表**：
  - `dim_players`、`dim_maps`
  - `fact_matches`、`fact_match_teams`
  - `fact_match_players`、`fact_match_players_t`、`fact_match_players_ct`
  - `fact_rounds`、`fact_round_events`、`fact_round_player_economy`

### L3
玩家特征集市 (Player Features Data Mart)，聚合 Basic 及 6 大挖掘能力维度 (STA, BAT, HPS, PTL, T/CT, UTIL)。
- **Schema**：`database/L3/schema.sql`
- **输出**：`database/L3/L3_Features.sqlite`
- **脚本**：`ETL/L3_Builder.py`
- **核心表**：`dm_player_features` (玩家聚合画像)

## JSON Schema 抽取工具
用于分析大量 `iframe_network.json` 的字段结构与覆盖情况，支持动态 Key 归并与多格式输出。

输出内容通常位于 `output_reports/` 或 `database/original_json_schema/`，包括：
- `schema_summary.md`：结构概览
- `schema_flat.csv`：扁平字段列表
- `uncovered_features.csv`：未覆盖字段清单

## 数据源互斥说明
L2 中 `fact_matches.data_source_type` 用于区分数据来源与字段覆盖范围：
- `classic`：含 round_list 详细回合与坐标信息
- `leetify`：含 leetify 评分与经济信息
- `unknown`：无法识别来源

入库逻辑保持互斥：同一场比赛只会按其来源覆盖相应字段，避免重复或冲突。