118-基于Python的游戏账号数据可视化分析系统

游戏账号数据可视化分析系统 --- 技术文档

一、项目概述

本系统是一个面向游戏账号交易数据的可视化分析平台，基于 FastAPI + SQLAlchemy 2 + Jinja2 + Bootstrap 5 + ECharts 构建。系统覆盖数据分析、账号浏览、收藏推荐、登录注册和后台管理五大模块，从 data/data.csv（约 25,000 条记录）导入数据后，提供多维度图表分析、个性化推荐、账号对比等能力。

技术栈

层级	技术
后端框架	FastAPI (Python 3.11+)
ORM	SQLAlchemy 2.0 (Mapped 声明式)
数据库	MySQL 8.0 (utf8mb4)
驱动	PyMySQL
模板引擎	Jinja2
数据处理	Pandas
前端框架	Bootstrap 5.3
图表库	ECharts 5.5
认证	Starlette SessionMiddleware + passlib (PBKDF2-SHA256)
测试	pytest + FastAPI TestClient

二、目录结构

复制代码

code/
├── main.py                          # 顶层入口，uvicorn 启动器
├── requirements.txt                 # Python 依赖
├── package.json                     # Node 依赖 (bootstrap, echarts)
├── design_118_game.sql              # MySQL 数据库导出文件
├── data/
│   └── data.csv                     # 原始数据集 (25,485 条)
├── scripts/
│   ├── init_db.py                   # 独立数据库初始化脚本
│   └── sync_steam_covers.py         # 独立 Steam 封面同步脚本
├── tests/
│   └── test_app.py                  # 集成测试
└── app/
    ├── __init__.py
    ├── main.py                      # FastAPI 应用工厂 & 生命周期
    ├── config.py                    # 配置数据类
    ├── database.py                  # SQLAlchemy 引擎 & 会话管理
    ├── models.py                    # ORM 模型 (4 张表)
    ├── security.py                  # 认证 & 会话工具函数
    ├── routers/
    │   ├── __init__.py
    │   ├── auth.py                  # 登录、注册、登出路由
    │   ├── api.py                   # JSON API 路由 (图表、账号、收藏、对比)
    │   ├── admin.py                 # 后台管理路由
    │   └── web.py                   # HTML 页面路由
    ├── services/
    │   ├── __init__.py
    │   ├── seed.py                  # 种子数据 (游戏、默认用户)
    │   ├── ingest.py                # CSV 导入 & 数据规范化
    │   ├── analytics.py             # 分析引擎 (图表、序列化、筛选、基准、对比)
    │   ├── recommendation.py        # 个性化推荐引擎
    │   └── steam.py                 # Steam 封面图抓取
    ├── templates/                   # Jinja2 模板 (17 个)
    │   ├── base.html                # 基础布局
    │   ├── index.html               # 首页
    │   ├── dashboard.html           # 分析看板
    │   ├── accounts.html            # 账号列表
    │   ├── account_detail.html      # 账号详情
    │   ├── insights.html            # 市场洞察
    │   ├── compare.html             # 对比分析
    │   ├── login.html               # 登录
    │   ├── register.html            # 注册
    │   ├── favorites.html           # 收藏
    │   ├── admin.html               # 后台管理首页
    │   ├── admin_accounts.html      # 后台账号列表
    │   ├── admin_account_form.html  # 后台新建/编辑表单
    │   ├── _metric_cards.html       # 指标卡片局部模板
    │   └── _account_card.html       # 账号卡片局部模板
    └── static/
        ├── css/site.css             # 自定义暗色主题 CSS (~1546 行)
        ├── js/app.js                # 前端 JS (ECharts、对比、收藏)
        └── img/*.svg                # 7 个游戏封面 SVG

三、数据库设计

3.1 ER 关系

复制代码

Game (1) ──── (N) GameAccount (1) ──── (N) Favorite (N) ──── (1) User

3.2 表结构

`games` --- 游戏表

字段	类型	说明
id	INT PK	主键
name	VARCHAR(60) UNIQUE	游戏名称
slug	VARCHAR(80) UNIQUE	URL 友好标识
description	VARCHAR(255)	游戏描述
theme_color	VARCHAR(30)	主题色 (默认 #2456f5)
cover_url	VARCHAR(500)	封面图 URL
steam_query	VARCHAR(120) NULL	Steam 搜索关键词
steam_app_id	INT NULL	Steam 应用 ID
mention_count	INT	数据集中被提及次数
created_at	DATETIME	创建时间
updated_at	DATETIME	更新时间

`users` --- 用户表

字段	类型	说明
id	INT PK	主键
username	VARCHAR(50) UNIQUE	用户名
email	VARCHAR(120) UNIQUE	邮箱
password_hash	VARCHAR(255)	密码哈希 (PBKDF2-SHA256)
is_admin	BOOLEAN	是否管理员
last_login_at	DATETIME NULL	最后登录时间
created_at	DATETIME	注册时间
updated_at	DATETIME	更新时间

`game_accounts` --- 游戏账号表

字段	类型	索引	说明
id	INT PK		主键
game_id	INT FK	INDEX	关联游戏
source_key	VARCHAR(40) UNIQUE		数据来源唯一标识 (SHA1)
title	TEXT		账号标题
excerpt	TEXT		描述摘要
price	FLOAT	INDEX	挂牌价格
system_version	VARCHAR(30)		系统版本 (iOS/Android)
account_type	VARCHAR(30)		账号类型 (QQ/微信)
service_region	VARCHAR(60)		服务区
server_name	VARCHAR(80)		服务器名称
published_at	DATETIME NULL	INDEX	上架时间
rank	VARCHAR(50)		段位
second_identity	VARCHAR(30)		二次实名 (可二次/不可二次)
vip_level	VARCHAR(20)	INDEX	贵族等级
skin_count	INT	INDEX	皮肤数量
hero_count	INT		英雄数量
collection_count	INT		典藏数量
peerless_count	INT		无双数量
legend_count	INT		传说数量
star_legend_count	INT		星传说数量
anti_addiction	VARCHAR(30)		防沉迷限制
quality_score	FLOAT	INDEX	综合质量分
title_length	INT		标题字符长度
related_games_json	TEXT		关联游戏 JSON
feature_tags_json	TEXT		特征标签 JSON
raw_title_metrics_json	TEXT		原始标题指标 JSON
created_at	DATETIME		创建时间
updated_at	DATETIME		更新时间

`favorites` --- 收藏表

字段	类型	说明
id	INT PK	主键
user_id	INT FK INDEX	关联用户
account_id	INT FK INDEX	关联账号
created_at	DATETIME	收藏时间
updated_at	DATETIME	更新时间

唯一约束: (user_id, account_id)

四、配置系统

配置通过 app/config.py 中的 Settings 冻结数据类管理，所有值均可通过同名环境变量覆盖。

配置项	默认值	说明
project_name	游戏账号数据可视化分析系统	项目名称
database_url	mysql+pymysql://root:123456@localhost:3306/design_118_game	数据库连接串
dataset_path	data/data.csv	数据集文件路径
secret_key	(内置默认)	Session 签名密钥
session_cookie	design118_session	Cookie 名称
admin_username	admin	默认管理员用户名
admin_email	admin@design118.local	默认管理员邮箱
admin_password	123456	默认管理员密码
default_user_username	user	默认普通用户名
default_user_email	user@design118.local	默认普通用户邮箱
default_user_password	123456	默认普通用户密码
page_size	12	分页每页条数
steam_timeout	15	Steam API 超时 (秒)

使用 @lru_cache 实现单例模式，通过 get_settings() 获取。

五、应用启动流程

5.1 入口

main.py → uvicorn.run("app.main:app", host, port, reload)

5.2 生命周期 (`app/main.py`)

复制代码

启动 (lifespan):
  1. ensure_database()     --- 连接 MySQL，若目标数据库不存在则创建
  2. init_db()             --- 根据 ORM 模型创建所有表
  3. seed_reference_data() --- 写入 7 个游戏种子记录 (upsert)
  4. seed_default_users()  --- 创建/重置 admin 和 user 账户
  5. import_accounts_from_csv(replace=False) --- 增量导入 CSV 数据

5.3 中间件 & 挂载

SessionMiddleware --- Starlette 签名 Cookie 会话
/static → app/static/ --- CSS、JS、图片
/vendor → node_modules/ --- Bootstrap、ECharts

5.4 路由注册

复制代码

auth.router   → /login, /register, /logout
api.router    → /api/* (JSON 接口)
admin.router  → /admin/* (后台管理)
web.router    → /, /dashboard, /accounts, /insights, /compare, /favorites

六、后端架构

6.1 分层结构

复制代码

路由层 (routers/)    ← HTTP 请求分发、表单处理、响应渲染
  ↓ 依赖注入
服务层 (services/)   ← 业务逻辑、数据计算、外部 API 调用
  ↓
数据层 (models.py + database.py) ← ORM 模型、会话管理

6.2 认证体系 (`security.py`)

函数	说明
`hash_password(password)`	PBKDF2-SHA256 哈希
`verify_password(password, hash)`	密码校验
`login_user(request, user)`	写入 session，更新 last_login_at
`logout_user(request)`	清除 session
`get_current_user_optional()`	返回 User 或 None (FastAPI Depends)
`get_current_user()`	返回 User 或 401 (FastAPI Depends)
`require_admin()`	返回管理员 User 或 403 (FastAPI Depends)
`flash(request, msg, category)`	Flash 消息存入 session
`pop_flash(request)`	取出并清除 Flash 消息

6.3 路由模块详解

`auth.py` --- 认证路由

方法	路径	说明
GET	/login	登录页
POST	/login	登录处理 (支持用户名或邮箱)
GET	/register	注册页
POST	/register	注册处理 (校验: 用户名≥3字符, 密码≥6字符, 确认密码一致, 唯一性)
POST	/logout	登出

`api.py` --- JSON API 路由

账号与统计:

方法	路径	说明
GET	/api/summary	全局统计摘要
GET	/api/accounts	分页账号列表 (支持 8 个筛选参数 + 6 种排序)
GET	/api/compare?ids=1,2,3	账号对比数据

收藏 (需登录):

方法	路径	说明
GET	/api/favorites	当前用户收藏列表
POST	/api/favorites/{id}	添加收藏
DELETE	/api/favorites/{id}	取消收藏

推荐:

方法	路径	说明
GET	/api/recommendations	个性化推荐 (登录用户基于画像, 未登录按质量排序)

图表数据 (21 个端点):

端点	图表类型	说明
/api/charts/daily-trend	折线图	每日上架趋势
/api/charts/platform-mix	饼图	平台分布 (QQ/微信/苹果)
/api/charts/publish-hour	柱状图	上架时段分布
/api/charts/weekday-activity	柱状图	星期活跃度
/api/charts/vip-price	折线图	VIP 等级与均价
/api/charts/price-band	柱状图	价格区间分布
/api/charts/quality-band	柱状图	质量分区间分布
/api/charts/skin-value	散点图	皮肤数与价格关系
/api/charts/collection-curve	折线图	典藏数分布曲线
/api/charts/legend-curve	折线图	传说数分布曲线
/api/charts/rank-mix	柱状图	段位分布
/api/charts/game-mix	饼图	游戏分布
/api/charts/game-value	柱状图	各游戏均价
/api/charts/tag-hot	玫瑰图	标签热度
/api/charts/feature-treemap	矩形树图	特征标签分布
/api/charts/identity-premium	柱状图	二次实名溢价
/api/charts/region-top	柱状图	区服 Top 10
/api/charts/related-assets	柱状图	关联资产分布
/api/charts/related-premium	柱状图	关联资产溢价
/api/charts/rank-vip-heatmap	热力图	段位×VIP 等级矩阵
/api/charts/quality-scatter	散点图	质量分与价格散点

所有图表端点均支持 chart_filters 依赖注入的 8 个筛选参数: q, game, system_version, account_type, vip_level, rank, price_min, price_max。

`admin.py` --- 后台管理路由 (需管理员权限)

方法	路径	说明
GET	/admin	管理面板首页
POST	/admin/reseed	重建数据集 (清空后重新导入 CSV)
POST	/admin/sync-covers	同步 Steam 游戏封面
GET	/admin/accounts	账号管理列表 (分页、搜索)
GET	/admin/accounts/new	新建账号表单
POST	/admin/accounts/new	创建账号
GET	/admin/accounts/{id}/edit	编辑账号表单
POST	/admin/accounts/{id}/edit	更新账号
POST	/admin/accounts/{id}/delete	删除账号

`web.py` --- 页面路由

方法	路径	说明
GET	/	首页 (指标卡片、游戏展示、精选/性价比/推荐/最新账号)
GET	/dashboard	分析看板 (筛选器 + 21 个图表)
GET	/accounts	账号列表 (筛选、排序、分页)
GET	/accounts/{id}	账号详情 (基准分析、相似推荐、收藏)
GET	/insights	市场洞察 (标签云、服务器分布、高价/高性价比样本)
GET	/compare	对比分析 (2-3 账号并排、雷达图、指标表)
GET	/favorites	收藏与推荐 (需登录)

七、服务层详解

7.1 数据导入 (`ingest.py`)

导入流程:

复制代码

CSV 文件
  ↓ pandas 读取
原始 DataFrame
  ↓ 字段规范化 (全角转半角、价格提取、时间解析)
规范化 DataFrame
  ↓ 标题特征提取 (正则匹配 21 种标签)
 enriched DataFrame
  ↓ 质量分计算
最终记录
  ↓ 批量写入 (每批 500 条)
数据库

标题特征提取: 通过正则表达式从账号标题中提取:

皮肤数量、英雄数量、典藏数量、无双数量、传说数量、星传说数量
VIP 等级
21 种特征标签 (荣耀水晶、营地、贵族积分、女号、满铭文、金标等)

质量分计算公式:

复制代码

quality = skins × 1.25
        + heroes × 0.45
        + collections × 38
        + peerless × 55
        + legends × 7.5
        + star_legends × 11
        + rank_weight × 25
        + vip_bonus (每级 18)
        + identity_bonus (可二次 +18)
        - anti_addiction_penalty (有防沉迷 -36)

去重机制: 使用标题+价格+服务器的 SHA1 哈希作为 source_key，插入时若已存在则跳过。

7.2 分析引擎 (`analytics.py`)

序列化 (`serialize_account`)

将 ORM 对象转换为前端可用的字典，包含计算字段:

price_text: 格式化价格 (¥1,234)
price_band_label: 价格区间标签 (百元内/百元档/500 档/千元档/万元档)
quality_tier: 质量等级 (S/A/B/C/D)
value_score: 性价比分 (quality_score / price × 100)
hero_line / rarity_line: 英雄/稀有资产摘要文本
cover_theme: 基于 SHA1 的确定性颜色方案 (--cover-primary, --cover-secondary 等 CSS 变量)

筛选器 (`build_filters`)

支持 8 个筛选维度，均通过 SQLAlchemy where 子句实现:

q: 标题模糊搜索 (ILIKE)
game: 游戏名称精确匹配
system_version: 系统版本
account_type: 账号类型
vip_level: VIP 等级
rank: 段位
price_min / price_max: 价格范围

排序模式 (`list_accounts`)

sort 参数	排序方式
latest	published_at DESC
price_asc	price ASC
price_desc	price DESC
quality	quality_score DESC
skins	skin_count DESC
value	value_score DESC (quality_score / price)

账号基准分析 (`get_account_benchmark`)

对单个账号在同游戏范围内计算:

价格百分位、质量百分位、皮肤百分位、性价比百分位
同价段样本数
同价段各项指标中位数
市场评语 (根据价格和质量百分位生成)

对比分析 (`get_compare_payload`)

支持 2-3 个账号并排对比:

指标行: 价格、质量分、皮肤、英雄、典藏、无双、传说、星传说、VIP
摘要卡片: 各维度最高值
雷达图数据: 6 维标准化数值
柱状图数据: 原始数值对比
胜负统计: 每个账号在多少维度领先

7.3 推荐引擎 (`recommendation.py`)

算法: 基于内容的过滤 (Content-Based Filtering)

流程:

若用户未登录 → 返回质量分 Top N
若用户已登录且有收藏:
- 从收藏记录构建用户画像: 平均价格、平均皮肤数、平均质量分、VIP 偏好、游戏偏好、标签偏好、关联游戏偏好
- 取 800 个候选账号，逐个评分

评分权重:

维度	权重	说明
同游戏	+22	与偏好游戏匹配
价格接近度	+16 (满分)	与平均价格越接近越高
皮肤接近度	+16 (满分)	与平均皮肤数越接近越高
质量接近度	+18 (满分)	与平均质量分越接近越高
VIP 匹配	+10	VIP 等级在偏好集中
共享标签	+5.5/个	特征标签匹配数
共享关联游戏	+7/个	关联游戏匹配数
二次身份	+4	可二次实名加分
典藏数	+4/个	典藏数量加分

返回 Top N 及每条推荐的人类可读原因。

7.4 Steam 封面同步 (`steam.py`)

调用 Steam 商店搜索 API (store.steampowered.com/api/storesearch)
按游戏的 steam_query 字段搜索
获取 header.jpg 封面图 URL
更新 games 表的 cover_url 和 steam_app_id

八、前端架构

8.1 模板继承

复制代码

base.html
  ├── index.html
  ├── dashboard.html
  ├── accounts.html
  ├── account_detail.html
  ├── insights.html
  ├── compare.html
  ├── login.html
  ├── register.html
  ├── favorites.html
  ├── admin.html
  ├── admin_accounts.html
  └── admin_account_form.html

局部模板:
  _metric_cards.html   ← 首页、管理面板复用
  _account_card.html   ← 账号列表、首页、收藏、管理面板复用

8.2 CSS 设计系统 (`site.css`)

设计语言: 暗色赛博观测站风格 (Dark Cyber-Observatory)

CSS 自定义属性 (设计令牌):

css 复制代码

--bg: #0a0e17           /* 主背景 */
--panel: #111827        /* 面板背景 */
--line: #1e293b         /* 边框线 */
--line-hover: #334155   /* 悬停边框 */
--primary: #3d9eff      /* 主色调 */
--accent: #7c3aed       /* 强调色 */
--muted: #64748b        /* 次要文字 */
--radius-lg: 16px       /* 大圆角 */
--radius-xl: 20px       /* 超大圆角 */
--font-mono: JetBrains Mono  /* 等宽字体 */
--transition: 0.2s ease  /* 过渡动画 */
--shadow-glow: ...       /* 发光阴影 */

响应式断点:

991px: 导航栏折叠、网格列数调整
576px: 指标卡片最小高度调整、字号缩小

特效:

毛玻璃效果: backdrop-filter: blur(12px)
渐变边框: ::before 伪元素渐变
卡片悬停: translateY(-2px) + 发光阴影
交错动画: 卡片入场依次淡入上移
骨架屏加载: shimmer 动画

8.3 JavaScript (`app.js`)

对比系统

使用 localStorage 存储对比账号 ID (最多 3 个)
底部固定对比托盘实时渲染
对比按钮状态同步 (已添加/未添加)
选择 2-3 个后跳转 /compare 页面

ECharts 集成

javascript 复制代码

initChart(domId)         // 初始化带暗色主题的 ECharts 实例
loadAndRenderChart(cfg)  // 从 API 加载数据并渲染图表
decorateOption(option)   // 统一暗色主题样式注入

21 个图表配置: 每个包含 URL、数据构建函数、图表类型 (line/bar/pie/heatmap/treemap/scatter/radar/rose)。

收藏功能

收藏按钮通过 data-account-id 绑定
POST /api/favorites/{id} 添加 / DELETE 取消
按钮状态实时更新 (已收藏/未收藏)

8.4 封面图生成

每个账号卡片的封面图是纯 CSS 生成的，而非真实图片:

基于账号属性的 SHA1 哈希生成确定性颜色方案
通过 CSS 自定义属性 --cover-primary, --cover-secondary, --cover-stripe 实现
每个账号拥有独特的渐变色和条纹图案
游戏名称以大字叠加显示

九、页面功能详解

9.1 首页 (`/`)

区块	内容
Hero 面板	指标卡片 (总账号数、中位挂牌价、高价值账号) + 系统介绍
系统能力	4 个功能入口卡片 (分析看板、市场洞察、对比分析、收藏推荐)
市场速览	4 个关键信号 (Apple 溢价、微信溢价、二次实名占比、跨游戏占比)
数据库封面	7 个游戏卡片 (封面图、样本数、均价、最近上架时间)
精选账号	质量分最高的 8 个样本
高性价比	性价比最优的 8 个样本
推荐系统	个性化推荐 (登录用户) 或默认推荐
最新上架	最近上架的 8 个样本

9.2 分析看板 (`/dashboard`)

筛选器: 关键词、游戏、系统版本、账号类型、VIP 等级、段位、价格范围
指标卡片: 总账号数、中位挂牌价、高价值账号
市场速览: 4 个关键信号
21 个图表面板: 按网格排列，支持联动筛选

9.3 账号列表 (`/accounts`)

筛选器: 与看板相同 + 排序方式 (最新/价格升序/价格降序/质量/皮肤/性价比)
账号卡片网格: 展示封面、标题、价格、关键指标
分页控件: 首页/上一页/页码/下一页/末页

9.4 账号详情 (`/accounts/{id}`)

封面区: CSS 生成封面 + 游戏标签 + 价格
元数据: VIP 等级、段位、平台、服务器、上架时间
基准分析: 同价段样本数、质量/皮肤/性价比百分位
资产指标: 6 个指标格 (皮肤、英雄、典藏、无双、传说、星传说)
特征标签: 从标题提取的标签列表
操作按钮: 收藏、加入对比、查看相似
市场定位表: 与同价段中位数对比
画像条: 4 维度百分位可视化
相似推荐: 同游戏、同价段、皮肤数相近的账号

9.5 市场洞察 (`/insights`)

市场速览: 4 个关键信号
标签云: Top 12 热门标签
服务器分布: Top 10 服务器
高价样本: 价格最高的账号
高性价比: 性价比最优的账号

9.6 对比分析 (`/compare`)

摘要卡片: 各维度最高值标注
雷达图: 6 维标准化对比
柱状图: 原始数值对比
胜负表: 每个账号领先维度数
账号卡片并排: 2-3 个账号横向排列
指标对比表: 逐行对比，最优值高亮

9.7 收藏与推荐 (`/favorites`)

需登录访问，未登录重定向到登录页
展示用户收藏的所有账号
基于收藏画像的个性化推荐
无收藏时显示空状态引导

9.8 后台管理 (`/admin`)

需管理员权限
操作卡片: 重建数据集、同步 Steam 封面、数据管理入口
指标卡片: 全局统计
最近注册用户: 最近 10 个注册用户
最常被收藏: 收藏数 Top 10 账号
高质量样本: 质量分最高的 8 个账号

9.9 账号数据管理 (`/admin/accounts`)

列表页: 分页表格 (ID、标题、价格、服务器、段位、皮肤数、质量分)、搜索、编辑/删除按钮
新建表单: 所有账号字段的表单
编辑表单: 预填现有数据的表单
删除: 带确认弹窗的删除操作

十、API 接口规范

10.1 通用响应格式

图表 API:

json 复制代码

{
  "labels": ["标签1", "标签2", ...],
  "values": [100, 200, ...]
}

账号列表 API:

json 复制代码

{
  "items": [{ "id": 1, "title": "...", "price": 500, ... }],
  "total": 25000,
  "page": 1,
  "page_size": 12,
  "total_pages": 2084
}

收藏 API:

json 复制代码

{
  "ok": true,
  "is_favorited": true,
  "favorite_total": 5
}

10.2 账号序列化字段

字段	类型	说明
id	int	账号 ID
title	string	标题
excerpt	string	描述
price	float	价格
price_text	string	格式化价格
price_band_label	string	价格区间
quality_score	float	质量分
quality_tier	string	质量等级 (S/A/B/C/D)
value_score	float	性价比分
skin_count	int	皮肤数
hero_count	int	英雄数
collection_count	int	典藏数
rank	string	段位
vip_level	string	VIP 等级
game_name	string	游戏名称
hero_line	string	英雄摘要
rarity_line	string	稀有资产摘要
cover_theme	object	封面颜色方案
recommendation_reason	string	推荐原因 (仅推荐 API)

十一、部署与运行

11.1 环境要求

Python 3.11+
MySQL 8.0+
Node.js (仅用于安装 bootstrap 和 echarts)

11.2 安装步骤

bash 复制代码

# 1. 安装 Python 依赖
pip install -r requirements.txt

# 2. 安装前端依赖
npm install

# 3. 配置数据库 (可选，通过环境变量)
export DATABASE_URL="mysql+pymysql://user:pass@localhost:3306/design_118_game"

# 4. 启动应用
python main.py

启动后自动执行:

创建数据库 (如不存在)
创建表结构
写入种子数据 (7 个游戏 + 2 个默认用户)
增量导入 CSV 数据

11.3 默认账户

角色	用户名	密码
管理员	admin	123456
普通用户	user	123456

11.4 访问地址

复制代码

http://127.0.0.1:8000

11.5 独立脚本

bash 复制代码

# 重新初始化数据库并全量导入
python scripts/init_db.py --replace

# 同步 Steam 游戏封面
python scripts/sync_steam_covers.py

十二、测试

12.1 运行测试

bash 复制代码

pytest tests/ -v

12.2 测试覆盖

测试用例	说明
test_public_pages_and_chart_apis	所有公开页面可访问、21 个图表 API 返回正确格式、筛选参数生效
test_register_favorite_and_recommendation_flow	注册 → 登录 → 收藏 CRUD → 推荐 API
test_admin_login_and_dashboard	管理员登录 → 后台面板访问
test_default_user_login	普通用户登录 → 收藏页访问

十三、已知问题

scripts/init_db.py 导入错误: 引用了 seed_admin_user，但实际函数名为 seed_default_users，直接运行脚本会触发 ImportError。
Session 密钥硬编码: config.py 中 secret_key 有内置默认值，生产环境应通过环境变量覆盖。
密码明文默认值: 默认管理员和用户密码为 123456，仅适用于开发环境。

118-基于Python的游戏账号数据可视化分析系统

游戏账号数据可视化分析系统 --- 技术文档

一、项目概述

技术栈

二、目录结构

三、数据库设计

3.1 ER 关系

3.2 表结构

games --- 游戏表

users --- 用户表

game_accounts --- 游戏账号表

favorites --- 收藏表

四、配置系统

五、应用启动流程

5.1 入口

5.2 生命周期 (app/main.py)

5.3 中间件 & 挂载

5.4 路由注册

六、后端架构

6.1 分层结构

6.2 认证体系 (security.py)

6.3 路由模块详解

auth.py --- 认证路由

api.py --- JSON API 路由

admin.py --- 后台管理路由 (需管理员权限)

web.py --- 页面路由

七、服务层详解

7.1 数据导入 (ingest.py)

7.2 分析引擎 (analytics.py)

序列化 (serialize_account)

筛选器 (build_filters)

排序模式 (list_accounts)

账号基准分析 (get_account_benchmark)

对比分析 (get_compare_payload)

7.3 推荐引擎 (recommendation.py)

7.4 Steam 封面同步 (steam.py)

八、前端架构

8.1 模板继承

8.2 CSS 设计系统 (site.css)

8.3 JavaScript (app.js)

对比系统

ECharts 集成

收藏功能

8.4 封面图生成

九、页面功能详解

9.1 首页 (/)

9.2 分析看板 (/dashboard)

9.3 账号列表 (/accounts)

9.4 账号详情 (/accounts/{id})

9.5 市场洞察 (/insights)

9.6 对比分析 (/compare)

9.7 收藏与推荐 (/favorites)

9.8 后台管理 (/admin)

9.9 账号数据管理 (/admin/accounts)

十、API 接口规范

10.1 通用响应格式

10.2 账号序列化字段

十一、部署与运行

11.1 环境要求

11.2 安装步骤

11.3 默认账户

11.4 访问地址

11.5 独立脚本

十二、测试

12.1 运行测试

12.2 测试覆盖

十三、已知问题

`games` --- 游戏表

`users` --- 用户表

`game_accounts` --- 游戏账号表

`favorites` --- 收藏表

5.2 生命周期 (`app/main.py`)

6.2 认证体系 (`security.py`)

`auth.py` --- 认证路由

`api.py` --- JSON API 路由

`admin.py` --- 后台管理路由 (需管理员权限)

`web.py` --- 页面路由

7.1 数据导入 (`ingest.py`)

7.2 分析引擎 (`analytics.py`)

序列化 (`serialize_account`)

筛选器 (`build_filters`)

排序模式 (`list_accounts`)

账号基准分析 (`get_account_benchmark`)

对比分析 (`get_compare_payload`)

7.3 推荐引擎 (`recommendation.py`)

7.4 Steam 封面同步 (`steam.py`)

8.2 CSS 设计系统 (`site.css`)

8.3 JavaScript (`app.js`)

9.1 首页 (`/`)

9.2 分析看板 (`/dashboard`)

9.3 账号列表 (`/accounts`)

9.4 账号详情 (`/accounts/{id}`)

9.5 市场洞察 (`/insights`)

9.6 对比分析 (`/compare`)

9.7 收藏与推荐 (`/favorites`)

9.8 后台管理 (`/admin`)

9.9 账号数据管理 (`/admin/accounts`)