2.0.0 Alpha: Data Refinery

2026-08-08 21:31:56 +08:00
parent fa75081d4d
commit 562775e5db
48 changed files with 4172 additions and 661 deletions
@@ -1,154 +1,269 @@
-# YRTV 项目说明 till 1.0.2hotfix
+# YRTV 2.0.0 Alpha

-## 项目概览
-YRTV 是一个基于 CS2 比赛数据的综合分析与战队管理平台。它集成了数据采集、ETL 清洗建模、特征挖掘以及现代化的 Web 交互界面。
-核心目标是为战队提供数据驱动的决策支持，包括战术分析、队员表现评估、阵容管理（Clubhouse）以及实时战术板功能。
+YRTV 是面向固定 CS2 战队的私人数据站。它不是公共玩家排行榜，而是让队员拥有类似职业选手的个人主页，并为战队提供比赛档案、队内比较、阵容分析、对手情报和战术工具。

---
+当前 Alpha 版本已经建立可重复运行的数据流水线、数据库治理和职业主页数据集市，重点服务 active roster。

-您可以使用以下命令快速配置环境：
-pip install -r requirements.txt
+## 当前基线

-数据来源与处理核心包括：
- 比赛页面的 iframe JSON 数据（`iframe_network.json`）
- 可选的 demo 文件（`.zip/.dem`）
- L1A/L2/L3 分层数据库建模与校验
+- 208 场比赛
+- 1,181 名采集到的玩家
+- 2,080 条玩家比赛记录
+- 4,315 个回合
+- 33,560 条回合事件
+- 38,423 条经济记录
+- 9 名 active roster 队员
+- 885 条 roster 逐场历史
+- 76 条地图统计
+- 236 条武器统计
+- 54 条时间窗口统计
+- 54 条个人职业纪录
+- 24 项自动化测试通过
+- 28 项数据完整性检查通过

-## 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 等高阶战术数据。
- **稳定性修复**: 修正了特征服务中的语法错误，增强了对缺失数据的鲁棒性处理。
+数据规模会随导入变化，Admin 数据完整性中心显示的结果是运行时事实。

-## 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 (经济计算)**: 简单的经济局/长枪局计算器。
+- Rating、K/D、ADR、KAST 等生涯数据
+- Aim、Clutch、Pistol、Defense、Utility、Stability、Economy、Pace 八维能力
+- 生涯、最近 10/20/30 场、最近 30/90 天阶段统计
+- 可切换时间窗口的 Rating 趋势
+- 最高 Rating、最多击杀、最高 ADR、最高 K/D、最多爆头和最长连胜
+- 每项个人纪录可追溯到具体比赛
+- 地图表现、比赛历史、Party 信息、队内排名和留言板
+- 缺失或尚未实现的指标显示为 `N/A`，不使用伪造分数

-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）。
-    -   头像上传与管理。
+- 比赛列表、地图、比分、平均 ELO 和己方结果
+- Active roster 与 Party 识别
+- 双方玩家表现和 Rating 排序
+- Head-to-head 击杀矩阵
+- 回合事件、经济和装备信息
+- 原始比赛数据查看

-## 自动化与运维
-新增 `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 字段覆盖与逻辑检查。
+- Active roster 管理
+- 玩家搜索、签入和移出
+- 2-5 人同队比赛与 Chemistry 分析
+- 对手档案和真实交手记录
+- 地图战术板、阵容数据中心和经济工具
+- Wiki、玩家标签、备注和评论
+
+### 数据运营
+
+- Admin 上传 `iframe_network.json`
+- 自动识别唯一 `g161-*` 比赛 ID
+- JSON 结构、必要接口、哈希和重复比赛校验
+- 后台执行 L1 → L2 → L3
+- 实时查看作业阶段、进度、日志和耗时
+- 数据完整性中心与 JSON 报告
+
+## 快速开始
+
+环境要求：
+
+- macOS/Linux
+- Python 3.9+
+- SQLite 3
+
+安装并启动：
+
+```bash
+make install
+
+export SECRET_KEY='replace-with-a-random-secret'
+export ADMIN_TOKEN='replace-with-an-admin-token'
+
+make run
+```
+
+默认地址：
+
+- 应用：`http://127.0.0.1:5000`
+- Admin：`/admin/`
+- 比赛导入：`/admin/import-match`
+- 数据完整性：`/admin/data-integrity`
+
+生产进程入口：
+
+```bash
+.venv/bin/gunicorn wsgi:app
+```
+
+## 常用命令
+
+```bash
+make run       # 启动 Flask
+make check     # 编译检查 + 自动化测试
+make pipeline  # 备份后执行完整 L1 -> L2 -> L3
+
+make l1        # 仅构建 L1
+make l2        # 仅构建 L2
+make l3        # 仅构建 active roster L3
+make l3-all    # 为全部采集玩家构建 L3
+```
+
+正常维护优先使用 `make pipeline`。单层命令主要用于开发和排错。
+
+## 比赛导入
+
+推荐从 Admin 页面上传完整的 `iframe_network.json`。
+
+导入流程：
+
+1. 验证 UTF-8 和 JSON 结构。
+2. 从网络 URL 中提取唯一比赛 ID。
+3. 检查 match 和 round 必要接口。
+4. 计算 SHA256，拒绝相同数据重复导入。
+5. 保存到 `output_arena/<match_id>/iframe_network.json`。
+6. 创建 `etl_jobs` 作业。
+7. 备份 L1/L2/L3。
+8. 串行执行三个 Builder。
+9. 验证目标比赛具有 10 名玩家和回合事实。
+10. 成功提交；失败自动恢复备份。
+
+仓库当前不包含自动访问 5E 网页的下载器，因此首页 URL 输入不会抓取数据。
+
+## 数据架构
+
+```text
+iframe_network.json
+        |
+        v
+L1 raw capture
+        |
+        v
+L2 normalized facts
+        |
+        v
+L3 roster features and profile marts
+        |
+        v
+Flask services and player profiles
+```
+
+### L1：原始层
+
+- 数据库：`database/L1/L1.db`
+- Builder：`database/L1/L1_Builder.py`
+- Grain：每场比赛一份完整网络抓包
+- 核心表：`raw_iframe_network`
+
+### L2：事实层
+
+- 数据库：`database/L2/L2.db`
+- Schema：`database/L2/schema.sql`
+- Builder：`database/L2/L2_Builder.py`
+- 核心表：
+  - `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：特征与主页集市
+
+- 数据库：`database/L3/L3.db`
+- Schema：`database/L3/schema.sql`
+- Builder：`database/L3/L3_Builder.py`
+- 核心表：
+  - `dm_player_features`
+  - `dm_player_match_history`
+  - `dm_player_map_stats`
+  - `dm_player_weapon_stats`
+  - `dm_player_period_stats`
+  - `dm_player_records`
+
+### Web：应用状态
+
+- 数据库：`database/Web/Web_App.sqlite`
+- Schema：`database/Web/schema.sql`
+- 当前 schema version：2
+- 保存 lineup、玩家备注、评论、Wiki、战术板、导入登记和 ETL 作业
+
+## 数据库治理
+
+- 所有运行路径集中定义在 `database/paths.py`
+- 完整编排入口为 `database/pipeline.py`
+- 同一时间只允许一个 pipeline
+- Pipeline 运行前备份 L1/L2/L3
+- 失败时恢复三层数据库，Web 作业日志继续保留
+- 备份位于 `database/backups/`
+- 自动保留最近 3 组备份
+- Web schema 使用 `schema_migrations` 记录版本
+- 高频玩家历史、Party、事件和经济查询具有专用索引
+- 数据库和目录规则详见 `database/README.md`
+
+## 数据质量
+
+Admin 数据完整性中心检查：
+
+- 四个 SQLite 数据库的 `quick_check`
+- 必要表和 Web schema version
+- 玩家比赛、回合事件的引用完整性
+- 每场比赛玩家数量
+- 玩家身份覆盖
+- 高频查询索引
+- Active roster 的 L3 特征覆盖
+- 逐场历史与总场次一致性
+- 真实队内 percentile
+- 地图、武器、时间窗口和职业纪录集市
+- 占位空间指标
+- Web 外键、active lineup 和 pipeline 并发
+- 备份数量与存储规模
+
+运行测试：
+
+```bash
+make check
+```

 ## 目录结构
-```
+
+```text
 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 抽取工具
+├── database/
+│   ├── L1/                 # 原始抓包与 Builder
+│   ├── L2/                 # 事实层、Schema、Processor
+│   ├── L3/                 # 特征层、Schema、Processor
+│   ├── Web/                # 应用数据库 Schema
+│   ├── paths.py            # 统一路径
+│   ├── maintenance.py      # 备份、恢复、健康检查
+│   ├── job_store.py        # ETL 作业状态
+│   └── pipeline.py         # 完整流水线
+├── tests/                  # 自动化测试
+├── utils/                  # JSON 结构分析工具
+├── web/
+│   ├── routes/
+│   ├── services/
+│   ├── templates/
+│   └── static/
+├── Makefile
+├── requirements.txt
+└── wsgi.py
 ```

-## 环境要求
- Python 3.11.4+
- Flask, Jinja2
- Playwright（下载器依赖）
- pandas, numpy（数据处理依赖）
+## Alpha 限制

-## 数据库层级说明
-### L1A
- **用途**：保存原始 iframe JSON
- **输入**：`output_arena/*/iframe_network.json`
- **输出**：`database/L1A/L1A.sqlite`
- **脚本**：`ETL/L1A.py`
+- 当前主要数据源为 5E iframe 网络响应。
+- 不包含自动网页下载器和 Demo parser。
+- 认证仍是单一 Admin Token，适合私人部署，不适合开放注册。
+- SQLite 适合当前单战队规模，不面向高并发多租户。
+- 部分高级空间能力需要地图边界、路径和 Demo 数据，当前显示 `N/A`。
+- `StatsService` 仍保留部分兼容逻辑，后续会继续按领域拆分。

-### 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`
+当前版本：`2.0.0 Alpha`

-### 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`：无法识别来源
-
-入库逻辑保持互斥：同一场比赛只会按其来源覆盖相应字段，避免重复或冲突。
+这一版本的目标是建立可信、可恢复、可持续导入的私人战队 HLTV 基线，而不是冻结产品功能。