# JSON Schema Extractor

用于从大量 5E Arena 比赛数据 (`iframe_network.json`) 中提取、归纳和分析 JSON Schema 的工具。它能够自动处理复杂的嵌套结构，识别动态 Key（如 SteamID、5E ID、Round Number），并生成层级清晰的结构报告。

## ✨ 核心功能

*   **批量处理**: 自动扫描并处理目录下的所有 `iframe_network.json` 文件。
*   **智能归并**:
    *   **动态 Key 掩码**: 自动识别并掩盖 SteamID (`<steamid>`)、5E ID (`<5eid>`) 和回合数 (`<round_n>`)。
    *   **结构合并**: 自动将 `group_1`/`group_2` 合并为 `group_N`，将 `fight`/`fight_t`/`fight_ct` 合并为 `fight_any`。
*   **多格式输出**:
    *   `schema_summary.md`: 易于阅读的 Markdown 层级报告。
    *   `schema_full.json`: 包含类型统计和完整结构的机器可读 JSON。
    *   `schema_flat.csv`: 扁平化的 CSV 字段列表，方便 Excel 查看。
*   **智能分类**: 根据 URL 路径自动将数据归类（如 Match Data, Leetify Rating, Round Data 等）。

## 🚀 快速开始

### 1. 运行提取器

在项目根目录下运行：

```bash
# 使用默认配置 (输入: output_arena, 输出: output_reports/)
python utils/json_extractor/main.py

# 自定义输入输出
python utils/json_extractor/main.py --input my_data_folder --output-md my_report.md
```

### 2. 查看报告

运行完成后，在 `output_reports/` 目录下查看结果：

*   **[schema_summary.md](../../output_reports/schema_summary.md)**: 推荐首先查看此文件，快速了解数据结构。
*   **[schema_flat.csv](../../output_reports/schema_flat.csv)**: 需要查找特定字段（如 `adr`）在哪些层级出现时使用。

## 🛠️ 规则配置

核心规则定义在 `utils/json_extractor/rules.py` 中，你可以根据需要修改：

*   **ID 识别**: 修改 `STEAMID_REGEX` 或 `FIVE_E_ID_REGEX` 正则。
*   **URL 过滤**: 修改 `IGNORE_URL_PATTERNS` 列表以忽略无关请求（如 sentry 日志）。
*   **Key 归并**: 修改 `get_key_mask` 函数来添加新的归并逻辑。

## 📊 结构分析工具

如果需要深入分析某些结构（如 `fight` 对象的变体），可以使用分析脚本：

```bash
python utils/json_extractor/analyze_structure.py
```

该脚本会统计特定字段的覆盖率，并检查不同 API（如 Round API 与 Leetify API）的共存情况。

## 📁 目录结构

```
utils/json_extractor/
├── extractor.py         # 核心提取逻辑 (SchemaExtractor 类)
├── main.py              # 命令行入口
├── rules.py             # 正则与归并规则定义
├── analyze_structure.py # 结构差异分析辅助脚本
└── README.md            # 本说明文件
```