0.4.1: L2ver2 finished

2026-01-24 00:43:05 +08:00
parent 879f63302c
commit 1deda4393c
8 changed files with 1277 additions and 271 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,135 @@
+# YRTV 项目说明
+
+## 项目概览
+yrtv这一块。
+
+数据来源与处理核心包括：
+- 比赛页面的 iframe JSON 数据（`iframe_network.json`）
+- 可选的 demo 文件（`.zip/.dem`）
+- L1A/L2 分层数据库建模与校验
+
+## 数据流程
+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. **质量校验与覆盖分析**  
+   `ETL/verify/verify_L2.py` 与 `ETL/verify/verify_deep.py` 用于字段覆盖、分布、空值和互斥逻辑的检查。
+
+## 目录结构
+```
+yrtv/
+├── downloader/                 # 下载器（抓取 iframe JSON 与 demo）
+│   ├── downloader.py
+│   └── README.md
+├── ETL/                        # ETL 脚本
+│   ├── L1A.py
+│   ├── L2_Builder.py
+│   ├── README.md
+│   └── verify/
+│       ├── verify_L2.py
+│       └── verify_deep.py
+├── database/
+│   ├── L1A/                    # L1A SQLite 与说明
+│   ├── L1B/                    # L1B 目录（demo 解析结果说明）
+│   ├── L2/                     # L2 SQLite 与 schema
+│   └── original_json_schema/   # schema 扁平化与未覆盖字段清单
+└── utils/
+    └── json_extractor/         # JSON Schema 抽取工具
+```
+
+## 环境要求
+- Python 3.9+
+- Playwright（下载器依赖）
+- pandas、numpy（校验脚本依赖）
+
+项目默认 Python 路径：
+```
+C:/ProgramData/anaconda3/python.exe
+```
+
+## 快速开始
+### 1. 下载比赛数据
+进入项目根目录运行（默认示例 URL）：
+```
+C:/ProgramData/anaconda3/python.exe downloader/downloader.py
+```
+
+指定比赛 URL：
+```
+C:/ProgramData/anaconda3/python.exe downloader/downloader.py --url https://arena.5eplay.com/data/match/g161-20260118222715609322516
+```
+
+批量下载（从文本文件读取 URL 列表）：
+```
+C:/ProgramData/anaconda3/python.exe downloader/downloader.py --url-list downloader/gamelist/match_list_2026.txt
+```
+
+### 2. 生成 L1A 数据库
+```
+C:/ProgramData/anaconda3/python.exe ETL/L1A.py
+```
+
+### 3. 生成 L2 数据库
+```
+C:/ProgramData/anaconda3/python.exe ETL/L2_Builder.py
+```
+
+### 4. 校验与覆盖检查
+```
+C:/ProgramData/anaconda3/python.exe ETL/verify/verify_L2.py
+C:/ProgramData/anaconda3/python.exe ETL/verify/verify_deep.py
+```
+
+## 数据库层级说明
+### 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`
+
+## JSON Schema 抽取工具
+用于分析大量 `iframe_network.json` 的字段结构与覆盖情况，支持动态 Key 归并与多格式输出。
+
+常用命令：
+```
+C:/ProgramData/anaconda3/python.exe utils/json_extractor/main.py
+```
+
+输出内容通常位于 `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`：无法识别来源
+
+入库逻辑保持互斥：同一场比赛只会按其来源覆盖相应字段，避免重复或冲突。
+
+## 常用文件定位
+- 下载器入口：[downloader.py](file:///c:/Users/Administrator/Documents/trae_projects/yrtv/downloader/downloader.py)
+- L1A 入库脚本：[L1A.py](file:///c:/Users/Administrator/Documents/trae_projects/yrtv/ETL/L1A.py)
+- L2 构建脚本：[L2_Builder.py](file:///c:/Users/Administrator/Documents/trae_projects/yrtv/ETL/L2_Builder.py)
+- L2 Schema：[schema.sql](file:///c:/Users/Administrator/Documents/trae_projects/yrtv/database/L2/schema.sql)
+- 覆盖检查：[verify_L2.py](file:///c:/Users/Administrator/Documents/trae_projects/yrtv/ETL/verify/verify_L2.py)
+- 深度校验：[verify_deep.py](file:///c:/Users/Administrator/Documents/trae_projects/yrtv/ETL/verify/verify_deep.py)