270 lines
7.4 KiB
Markdown
270 lines
7.4 KiB
Markdown
# YRTV 2.0.0 Alpha
|
||
|
||
YRTV 是面向固定 CS2 战队的私人数据站。它不是公共玩家排行榜，而是让队员拥有类似职业选手的个人主页，并为战队提供比赛档案、队内比较、阵容分析、对手情报和战术工具。
|
||
|
||
当前 Alpha 版本已经建立可重复运行的数据流水线、数据库治理和职业主页数据集市，重点服务 active roster。
|
||
|
||
## 当前基线
|
||
|
||
- 208 场比赛
|
||
- 1,181 名采集到的玩家
|
||
- 2,080 条玩家比赛记录
|
||
- 4,315 个回合
|
||
- 33,560 条回合事件
|
||
- 38,423 条经济记录
|
||
- 9 名 active roster 队员
|
||
- 885 条 roster 逐场历史
|
||
- 76 条地图统计
|
||
- 236 条武器统计
|
||
- 54 条时间窗口统计
|
||
- 54 条个人职业纪录
|
||
- 24 项自动化测试通过
|
||
- 28 项数据完整性检查通过
|
||
|
||
数据规模会随导入变化，Admin 数据完整性中心显示的结果是运行时事实。
|
||
|
||
## 核心功能
|
||
|
||
### 玩家职业主页
|
||
|
||
- 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`，不使用伪造分数
|
||
|
||
### 比赛中心
|
||
|
||
- 比赛列表、地图、比分、平均 ELO 和己方结果
|
||
- Active roster 与 Party 识别
|
||
- 双方玩家表现和 Rating 排序
|
||
- Head-to-head 击杀矩阵
|
||
- 回合事件、经济和装备信息
|
||
- 原始比赛数据查看
|
||
|
||
### 战队与战术
|
||
|
||
- 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/
|
||
├── 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
|
||
```
|
||
|
||
## Alpha 限制
|
||
|
||
- 当前主要数据源为 5E iframe 网络响应。
|
||
- 不包含自动网页下载器和 Demo parser。
|
||
- 认证仍是单一 Admin Token，适合私人部署，不适合开放注册。
|
||
- SQLite 适合当前单战队规模，不面向高并发多租户。
|
||
- 部分高级空间能力需要地图边界、路径和 Demo 数据，当前显示 `N/A`。
|
||
- `StatsService` 仍保留部分兼容逻辑，后续会继续按领域拆分。
|
||
|
||
## 版本
|
||
|
||
当前版本：`2.0.0 Alpha`
|
||
|
||
这一版本的目标是建立可信、可恢复、可持续导入的私人战队 HLTV 基线，而不是冻结产品功能。
|