yrtv/docs/WebRDD.md

YRTV 网站需求规格说明书 (RDD)

1. 项目概述 (Overview)

1.1 项目背景

YRTV 是一个面向 CS2 战队数据洞察与战术研判的 Web 平台，旨在通过 Web 界面提供可视化的数据查询、战队管理、战术模拟及深度分析功能。

1.2 核心目标

• 数据可视化: 将复杂的 SQLite 比赛数据转化为易读的图表、雷达图和趋势线。
• 战术研判: 提供阵容模拟、协同分析及地图热点情报，辅助战术决策。
• 交互体验: 通过轻量级前端交互（筛选、对比、点赞、白板）提升数据使用效率。
• 实时动态: 追踪战队成员的实时竞技状态与近期比赛动态，营造“战队大厅”氛围。

1.3 技术栈规划

• 后端框架: Python Flask (轻量级，易于集成现有 ETL 脚本)
• 数据库:
  • L2: SQLite (database/L2/L2_Main.sqlite) - 基础事实数据 (Read-Only for Web)
  • L3: SQLite (database/L3/L3_Features.sqlite) - 高级衍生特征 (Read-Only for Web)
  • Web: SQLite (database/Web/Web_App.sqlite) - [新增] 业务数据 (用户、评论、阵容配置、策略板存档)
• 模板引擎: Jinja2 (服务端渲染)
• 前端样式: Tailwind CSS (CDN 引入，快速开发) + PC-First 响应式设计 (适配手机、平板与桌面端)，主题色紫色，可切换黑白模式。
• 前端交互:
  • 图表: Chart.js / ECharts (雷达图、趋势图)
  • 交互: Alpine.js 或原生 JS (处理模态框、异步请求)
  • 拖拽: SortableJS (阵容调整)
  • 地图: Leaflet.js 或简单 Canvas (热力图/策略板)

---

2. 系统架构 (Architecture)

2.1 目录结构规划

yrtv/
├── web/
│   ├── app.py              # Flask 应用入口
│   ├── config.py           # 配置文件
│   ├── routes/             # 路由模块
│   │   ├── main.py         # 首页与通用 (Home)
│   │   ├── players.py      # 玩家模块 (List, Detail, Compare)
│   │   ├── teams.py        # 战队模块 (Lineup, Stats)
│   │   ├── matches.py      # 比赛模块 (List, Detail, Demo)
│   │   ├── tactics.py      # 战术模块 (Lineup Builder, Map, Nade)
│   │   ├── wiki.py         # 知识库模块 (Wiki, Docs)
│   │   └── admin.py        # 管理后台 (ETL Trigger, User Mgmt)
│   ├── services/           # 业务逻辑层 (连接 L2/L3/Web DB)
│   │   ├── stats_service.py # 基础数据查询 (L2)
│   │   ├── feature_service.py # 高级特征查询 (L3)
│   │   ├── wiki_service.py  # 知识库管理
│   │   └── user_service.py  # 用户与评论管理
│   ├── static/             # 静态资源
│   │   ├── css/
│   │   ├── js/
│   │   └── images/
│   └── templates/          # Jinja2 模板
│       ├── base.html
│       ├── components/
│       ├── home/
│       ├── players/
│       ├── teams/
│       ├── matches/
│       ├── tactics/
│       ├── wiki/
│       └── admin/
├── database/               # 数据存储
│   ├── L1A/                # 原始爬虫数据
│   ├── L2/                 # 结构化事实数据
│   ├── L3/                 # 衍生特征库 (Feature Store)
│   └── Web/                # [新增] 业务数据库 (User, Comment, Wiki)
└── ETL/                    # 数据处理层 (ETL Pipeline)
    ├── L1A.py              # L1A Ingest
    ├── L2_Builder.py       # L2 Transform
    └── L3_Builder.py       # L3 Feature Engineering (原 feature_store.py 逻辑)

2.2 数据流向

1. ETL 层 (数据处理核心):
   • L1 (Raw): 爬虫 -> JSON 存储。
   • L2 (Fact): JSON -> 清洗/标准化 -> Fact/Dim Tables。
   • L3 (Features): L2 -> 聚合/滑窗计算/模型推理 -> Player/Team Derived Features。数据处理逻辑收敛于 ETL 目录下的脚本，Web 端仅负责读取 L2/L3 结果。
2. Service 层: Flask Service 仅负责 SQL 查询与简单的业务组装（如评论关联），不再包含复杂的数据计算逻辑。
3. View 层: Jinja2 渲染 HTML。
4. Client 层: 浏览器交互。

2.3 开发与启动 (Development & Startup)

• 启动方式:
  • 在项目根目录下运行: python web/app.py
  • 访问地址: http://127.0.0.1:5000

---

3. 功能需求详解 (Functional Requirements)

3.1 首页 (Home)

• 功能: 平台入口与导航聚合。
• 内容:
  • Hero 区域: 平台定位文案（"JKTV CS2 队伍数据洞察平台"）。
  • Live / 战队状态看板 (New):
    • 正在进行: 如果监测到战队成员（配置列表内）正在进行比赛（通过 5E 接口轮询或最近 10 分钟内有数据更新），显示 "LIVE" 状态卡片。
    • 近期战况: 滚动显示战队成员最近结束的 5 场比赛结果（胜负、比分、MVP）。
    • 状态概览: 类似 GitHub Contribution 的热力日历，展示战队本月的活跃度。
  • 快捷入口卡片:
    • "战术指挥中心": 跳转至阵容模拟。
    • "近期比赛": 跳转至最新一场比赛详情。
    • "数据中心": 跳转至多维对比。
  • 比赛解析器: 输入 5E 比赛链接，点击按钮触发后台 ETL 任务（异步），前端显示 Loading 状态或 Toast 提示。

3.2 玩家模块 (Players)

3.2.1 玩家列表 PlayerList

• 筛选/搜索: 按 ID/昵称搜索，按 K/D、Rating、MVP 等指标排序。
• 展示: 卡片式布局，显示头像、ID、主队、核心数据 (Rating, K/D, ADR)。

3.2.2 玩家详情 PlayerProfile

• 基础信息: 头像、SteamID、5E ID、注册时间。可以手动分配Tag。
• 核心指标: 赛季平均 Rating, ADR, KAST, 首杀成功率等。
• 能力雷达图: 计算规则需在 Service 层定义。
• 趋势图: 近 10/20 场比赛 Rating 走势 (Chart.js)。
• 评价板: 类似于虎扑评分，用户可点赞/踩，显示热门评价（需新增 web_comments 表）。增加访问次数统计。
• 管理区 (Admin Only): 修改备注、上传自定义头像。

3.3 战队模块 (Teams)

• 阵容视图: 展示当前核心阵容，手动添加。
• 角色分组: 手动标签将玩家分组。
• 统计概览: 战队整体胜率、近期战绩、地图胜率分布，个人关键数据。

3.4 比赛模块 (Matches)

3.4.1 比赛列表 MatchList

• 筛选: 按地图、日期范围筛选。
• 展示: 列表视图，显示时间、地图、比分、胜负、MVP。

3.4.2 比赛详情 MatchDetail

• 头部: 比分板（CT/T 分数）、地图、时长、Demo 下载链接。
• 数据表: 双方队伍的完整数据表（K, D, A, FK, FD, ADR, Rating, KAST, AWP Kills 等）。
  • 利用 fact_match_players 中的丰富字段。
• 原始数据: 提供 JSON 格式的原始数据查看/下载（raw_iframe_network 提取）。

3.5 战术模块 (Tactics)

3.5.1 化学反应与战术深度分析 (Deep Analysis)

• 阵容组建: 交互式界面，从玩家池拖拽 5 名玩家进入“首发名单”。
• 阵容评估: 实时计算该 5 人组合的平均能力雷达。
• 共同经历: 查询这 5 人共同参与过的比赛场次及胜率。
• 协同矩阵: 选择特定阵容，展示两两之间的协同数据（如：A 补枪 B 的次数，A 与 B 同时在场时的胜率）。
• 最佳/短板分析: 基于历史数据分析该阵容在特定地图上的强弱项。

3.5.2 数据对比 Data Center

• 多选对比: 选择多名玩家，并在同一雷达图/柱状图中对比各项数据。
• 地图筛选: 查看特定玩家在特定地图上的表现差异。

3.5.3 道具与策略板 (Grenades & Strategy Board)

• 道具管理:
  • 道具计算: 提供特定点位（如 Inferno 香蕉道）的烟雾弹/燃烧弹投掷模拟（基于坐标距离与轨迹公式）。
  • 道具库: 预设主流地图的常见道具点位（图片/视频展示），支持管理员添加新点位。
• 实时互动策略板:
  • 分地图绘制: 基于 Leaflet.js 或 Canvas，加载 CS2 高清鸟瞰图。
  • 实时协同: 支持 WebSocket 多人同屏绘制（类似 Excalidraw），即时同步画笔轨迹与标记。
  • 快照保存: 支持一键保存当前战术板状态为图片或 JSON，生成分享链接/加入知识库。

3.5.4 经济计算器 (Economy Calculator)

• 功能: 模拟 CS2 经济系统，辅助指挥决策。
• 输入: 设定当前回合胜负、存活人数、炸弹状态、当前连败奖励。
• 输出: 预测下一回合敌我双方的经济状况（最小/最大可用资金），给出起枪建议（Eco/Force/Full Buy）。

3.6 知识库 (Knowledge Base / Wiki)

• 架构: 典型的 Wiki 布局。
  • 左侧: 全局文档树状目录（支持多级折叠）。
  • 右侧: 当前文档的页内大纲（TOC）。
  • 中间: Markdown 渲染的正文区域。
• 功能:
  • 快速编辑: 提供 Web 端 Markdown 编辑器，支持实时预览。
  • 简单验证: 简单的密码或 Token 验证即可保存修改，降低贡献门槛。
  • 文件管理: 支持新建、重命名、删除文档，自动生成目录结构。

3.7 管理后台 (Admin)

• 鉴权: 简单的 Session/Token 登录。
• 数据管理:
  • 手动触发增量/全量 ETL。
  • 上传 demo 文件或修正比赛数据。
• 配置: 管理员账号管理、全局公告设置。查看网站访问数等后台统计。

3.8 管理后台查询工具 (SQL Runner)

• 功能: 提供一个 Web 版的 SQLite 查询窗口。
• 限制: 只读权限（防止 DROP/DELETE），仅供高级用户进行自定义数据挖掘。

---

Second Stage: Demo 深度解析管线 (Future)

• 目标: 引入 demoparser2 (或类似开源库) 实现本地 Demo 文件的深度解析，获取比 Web 爬虫更细粒度的原子级数据。
• Pipeline:
  1. Ingest: 自动/手动上传 .dem 文件。
  2. Parse: 调用 demoparser2 提取每 tick/每事件数据 (Player Position, Grenade Trajectory, Weapon Firing)。
  3. Store: 将海量原子数据存入 ClickHouse 或优化的 SQLite 分表 (L1B/L2+)。
  4. Analyze: 产出高级分析指标（如：真实拉枪反应时间、道具覆盖效率、非预瞄击杀率）。
  5. Visualize: 在前端复盘页面实现 2D 回放 (2D Replay) 功能。