yrtv/README.md

YRTV 项目说明 till 1.0.2hotfix

项目概览

YRTV 是一个基于 CS2 比赛数据的综合分析与战队管理平台。它集成了数据采集、ETL 清洗建模、特征挖掘以及现代化的 Web 交互界面。 核心目标是为战队提供数据驱动的决策支持，包括战术分析、队员表现评估、阵容管理（Clubhouse）以及实时战术板功能。

---

您可以使用以下命令快速配置环境： pip install -r requirements.txt

数据来源与处理核心包括：

• 比赛页面的 iframe JSON 数据（iframe_network.json）
• 可选的 demo 文件（.zip/.dem）
• L1A/L2/L3 分层数据库建模与校验

v3.0.0 Release 更新要点

• 核心算法升级: 严格确立 Active Roster (Lineup 1) 为战队平均数据计算基准，修复了雷达图与平均数据的计算偏差。
• Clubhouse 增强:
  • 布局优化为 3 列网格。
  • 新增 OVR (Overall Score) 显示，优先展示真实评分 (Real Rating)，直观反映选手综合实力。
• Tactics 系统:
  • 统一评分逻辑：全站优先采用 L3 core_avg_rating2 (真实评分)，智能回退至 basic_avg_rating。
  • Data Center 数据中心现在完整映射了 Utility、Trading 等高阶战术数据。
• 稳定性修复: 修正了特征服务中的语法错误，增强了对缺失数据的鲁棒性处理。

Web 交互系统 (Core)

基于 Flask + TailwindCSS + Alpine.js 构建的现代化 Web 应用。

核心功能模块

1. Clubhouse (战队管理)

   • Roster Management: 拖拽式管理当前激活阵容 (Active Roster)。
   • Scout System: 全库模糊搜索玩家，支持按 Rating/Matches/KD 排序筛选。
   • Contract System: 模拟签约/解约流程 (Sign/Release)，管理战队资产。
   • Identity: 统一的头像与 ID 显示逻辑 (SteamID/Name)，支持自动生成首字母头像。

2. Tactics Board (战术终端)

   • SPA 架构: 基于 Alpine.js 的单页应用，无刷新切换四大功能区。
   • Board (战术板): 集成 Leaflet.js 的交互式地图，支持战术点位标记。
   • Data (数据中心): 实时查看全队近期数据表现，集成 Utility/Trading 等高阶战术指标。
   • Analysis (深度分析):
     • Chemistry: 任意组合 (2-5人) 的共同比赛胜率与数据分析。
     • Depth: 阵容深度与位置分析。
   • Economy (经济计算): 简单的经济局/长枪局计算器。

3. Match Center (比赛中心)

   • List View:
     • 显示比赛平均 ELO。
     • Party Identification: 自动识别组排车队 (👥 2-5)，并用颜色区分规模 (Indigo/Blue/Purple/Orange)。
     • Result Tracking: 基于 "Our Team" (Active Roster) 的胜负判定 (VICTORY/DEFEAT/CIVIL WAR)。
   • Detail View:
     • 按 Rating 降序排列双方队员。
     • 高亮显示组排关系。
     • 集成 Round-by-Round 经济与事件详情。

4. Player Profile (玩家档案)

   • 综合能力雷达图 (八维数据: Aim, Clutch, Pistol, Defense, Util, Stability, Economy, Pace)。
   • 近期 Rating/KD/ADR 趋势折线图。
   • 详细的历史比赛记录（含 Party info 与 Result）。
   • 头像上传与管理。

自动化与运维

新增 ETL/refresh.py 自动化脚本，用于一键执行全量数据刷新：

• 自动清理旧数据库。
• 顺序执行 L1A -> L2 -> L3 构建。
• 自动处理 schema 迁移。

数据流程

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）
├── ETL/                        # ETL 脚本
│   ├── L1A.py
│   ├── L2_Builder.py
│   ├── L3_Builder.py
│   ├── refresh.py              # [NEW] 一键刷新脚本
│   └── verify/
├── database/                   # SQLite 数据库存储
│   ├── L1A/                    
│   ├── L2/                     
│   ├── L3/                     
│   └── original_json_schema/   
├── web/                        # [NEW] Web 应用程序
│   ├── app.py                  # 应用入口
│   ├── routes/                 # 路由 (matches, players, teams, tactics)
│   ├── services/               # 业务逻辑 (stats, web)
│   ├── templates/              # Jinja2 模板 (TailwindCSS + Alpine.js)
│   └── static/                 # 静态资源 (CSS, JS, Uploads)
└── utils/
    └── json_extractor/         # JSON Schema 抽取工具

环境要求

• Python 3.11.4+
• Flask, Jinja2
• 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：无法识别来源

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