Skip to content

Architecture

WONGIII edited this page Jul 15, 2026 · 1 revision

网站实现方式

技术栈

层级 技术 用途
框架 Next.js 15 (App Router) 全栈 Web 框架,SSR + API Routes
语言 TypeScript 类型安全
样式 Tailwind CSS 原子化 CSS,暗色/亮色适配
数据库 SQLite (better-sqlite3) 单文件零配置,WAL 模式
认证 JWT (jose) + bcryptjs 无状态 token,HttpOnly cookie
数据源 GameTools Network API BF6 公开战绩 API
字体 Bebas Neue (Google Fonts) 战地风格标题字体
字体大小 body 18px 大屏阅读体验

架构总览

浏览器
  │
  ▼
Next.js 15 App Router
  ├── src/app/api/          ← 后端 API(Route Handlers)
  │   ├── profile/          ← 玩家查询 + 战绩转换
  │   ├── auth/             ← JWT 注册/登录/登出
  │   ├── admin/            ← 管理后台 CRUD
  │   ├── suspicion/        ← 匿名举报
  │   ├── contact/          ← 工单系统
  │   └── admin/refresh-all ← 全量刷新
  │
  ├── src/app/              ← 前端页面(Server + Client Components)
  │   ├── page.tsx          ← 首页(搜索框 + 服务状态)
  │   ├── player/           ← 玩家详情页
  │   ├── admin/            ← 管理后台页
  │   ├── my/               ← 用户中心
  │   └── contact/          ← 联系我们
  │
  ├── src/components/       ← React 组件
  │   ├── PlayerClient.tsx   ← 主战绩展示(3层导航 + 战报 + 标记)
  │   ├── AuthContext.tsx    ← 认证状态上下文
  │   └── SponsorContext.tsx ← 赞助者名字颜色系统
  │
  ├── src/lib/              ← 核心库
  │   ├── db.ts             ← SQLite 数据层
  │   ├── gametools.ts      ← GameTools API 客户端
  │   ├── delta.ts          ← 战报差分引擎
  │   ├── poller.ts         ← 后台轮询器
  │   ├── builder.ts        ← TRN 格式转换器
  │   ├── auth.ts           ← JWT 签名/验证
  │   └── types.ts          ← TypeScript 类型定义
  │
  └── src/instrumentation.ts ← 服务启动钩子(轮询器入口)

数据流

首次查询

用户输入名称
  → GET /api/profile?query=xxx
  → Promise.allSettled([origin, steam, psn, xbox])
  → 四平台并行探测,取首个命中
  → fetchStats(name, platform)  // seperation=true,含赛季数据
  → fetchProfileById(userId)    // 仅取 rank/头像
  → buildTrnProfileResponse()   // GameTools → TRN 格式
  → upsertProfile()             // 入库 + 生成首条战报
  → 返回 TRN JSON 给前端

缓存命中

用户输入名称
  → getProfile(query) 命中 DB 缓存
  → touchSearchTimestamp(userId)  // 更新搜索时间戳
  → refreshInBackground(query)   // 不 await,后台刷新
  → 立即返回缓存数据(秒开)

后台刷新

refreshInBackground(query)
  → tryPlatform(query, storedPlatform)  // 优先用数据库记录的平台
  → fetchStats(name, platform)          // seperation=true
  → fetchProfileById(userId)
  → buildTrnProfileResponse()
  → upsertProfile()                     // hash 对比后决定是否生成战报

自动轮询

instrumentation.ts → startBackgroundPoller()
  ↓ 每 300 秒
listProfileIdentifiers()  // 从 DB 取所有玩家
  ↓ 分级过滤
赞助者 → 每圈都查
24h 内搜索过 → 10 分钟一次
其他 → 跳过
  ↓
fetchStatsBatchByIds()  // POST /bf6/multiple/ seperation=false 批量
  ↓ 逐人对比 hash
hash 变了 → fetchProfileById() + buildTrnProfileResponse() + upsertProfile()
hash 没变 → 跳过(零 DB 写入)

数据库设计

SQLite 单文件 data/bf6.db,WAL 模式。

表 Key 用途
profiles platform_user_identifier 玩家当前 TRN 完整快照 + 搜索时间戳
matches id 战报增量历史(append-only)
users id 用户账号(JWT 认证)
sponsors platform_user_identifier 赞助者等级
player_suspicion_reports id 匿名举报记录
contact_messages id 工单
settings key 为 admin_password 系统配置
verified_streamers platform_user_identifier 认证主播

profiles 表

platform_user_identifier TEXT PRIMARY KEY  -- 游戏 nucleus ID
platform                 TEXT              -- 平台 (origin/steam/psn/xbox)
name                     TEXT              -- 玩家名
update_hash              TEXT              -- SHA-1 计数器哈希
updated_at               TEXT              -- 最后刷新时间
last_searched_at         TEXT              -- 上次被搜索时间
trn_profile_json         TEXT              -- TRN 格式完整 JSON

matches 表

id                        TEXT PRIMARY KEY
platform_user_identifier  TEXT              -- 关联 profiles
created_at                TEXT              -- 战报生成时间
from_hash                 TEXT              -- 旧哈希(首条为 NULL)
to_hash                   TEXT              -- 新哈希
match_json                TEXT              -- TRN match 格式 JSON

战报差分引擎

核心文件:src/lib/delta.ts

匹配策略

  • 新旧 profile 的 segments 按 type + metadata.name 配对
  • 每个配对项的所有 counter 逐字段相减(new.value - old.value,负数归零)
  • 衍生指标(KPM/KD/SPM/胜率/命中率)从 delta 值重新计算

过滤规则

  • 聚合项("All"/"Total"/"Official" 等)自动过滤
  • careerPlayerRank(当前等级)不计入 counter 变动
  • overview 所有 counter + 全组 delta 均为零 → 不生成战报
  • 单个组项 delta 全零 → 不出现在结果中

差异计算举例

武器:kills、headshots、shotsFired、shotsHit、timeEquipped、damage、hipfireKills、scopedKills、multiKills 等 15+ 字段

载具:kills、damage、timeIn、destroyed、roadKills、distanceTraveled、spawns 等 12+ 字段

兵种:kills、deaths、score、timePlayed、assists、revives、spawns 等 10+ 字段

模式/地图/装备同样全覆盖。

战报 JSON 结构

{
  "attributes": {"type": "delta", "id": "uuid"},
  "metadata": {"timestamp": "2026-07-15T08:04:00Z"},
  "segments": [{
    "type": "overview",
    "attributes": {"accountId": "1009230165587"},
    "stats": {
      "kills":      {"value": 22, "displayValue": "22", "displayType": "Number"},
      "kd":         {"value": 1.47, "displayValue": "1.47", "displayType": "NumberPrecision2"},
      "killsPerMinute": {"value": 0.46, "displayValue": "0.46", "displayType": "NumberPrecision2"},
      ...
    },
    "metadata": {
      "gamemodes": [{"key": "gm_征服", "metadata": {"name": "征服", "imageUrl": "..."}, "stats": {...}}],
      "levels":    [{"key": "map_xxx", "metadata": {"name": "解放峰", "imageUrl": "..."}, "stats": {...}}],
      "kits":      [...],
      "weapons":   [...],
      "vehicles":  [...],
      "gadgets":   [...]
    }
  }]
}

与旧格式兼容

前端 MatchesDetail 自动检测格式——有 overview.metadata 嵌套组用新渲染,否则走旧平铺 segments 渲染。

GameTools API 交互

端点使用

端点 参数 用途 时机
GET /bf6/stats/ seperation=true 含赛季拆分,完整数据 首次查询、后台刷新
GET /bf6/stats/ seperation=false 仅聚合统计,快 批量轮询(hash 对比)
POST /bf6/multiple/ seperation=false 批量 20 人查一次 自动轮询
GET /bf6/profile/ - rank/头像/玩家卡 所有刷新路径
GET /bf6/search/ - 搜索玩家名 前端搜索框快捷搜索

缓存策略

  • 只有含 userId 的响应才缓存(避免 EA/PSN 的空结果污染缓存)
  • 缓存 TTL:stats 180s、profile 300s、search 60s
  • 内存缓存,重启清空

平台映射

origin → ea
steam  → steam
psn    → psn
xbox   → xbl

前端页面

首页

  • 搜索框(支持名称/ID)
  • 后台服务 + GameTools API 健康状态
  • 赞助者展示、统计数据

玩家详情页(PlayerClient.tsx)

三层导航:

L1: 全部 / 战报 / 全面战争 / 禁区冲突 / 标记
L2: 生涯 / SEASON 3 / SEASON 2 / SEASON 1
L3: 总览 / 武器 / 载具 / 装备 / 兵种 / 模式 / 地图 / 近战
  • 生涯总览:所有赛季聚合,百分位柱状图
  • 战报:折叠列表,展开查看全段详情
  • 赛季分类:按 season 拆分,每类独立展示
  • 标记:匿名举报 + 社区可信度

管理后台

选项卡:赞助者 / 留言 / 标记审核 / 主播 / 用户 / 密码

认证系统

  • JWT 签名(jose 库),HttpOnly cookie
  • 注册:用户名 + 密码,bcrypt 哈希
  • 管理员密码存 settings 表,fallback 到 ADMIN_PASSWORD 环境变量

赞助者名字颜色系统

6 级分层:

等级 CSS 效果
站长 彩虹渐变 + 光晕
Tier 1 金色渐变
Tier 2 紫色渐变
Tier 3 蓝色渐变
Tier 4 绿色渐变
协助者 银色

通过 SponsorContext 全局注入,组件内直接用 CSS class 渲染。

部署

  • 端口:3000
  • 数据库:data/bf6.db(卷挂载持久化)
  • 轮询器:instrumentation.ts 自动启动,环境变量 BF6_POLL_INTERVAL_SECONDS 可调
  • 反向代理:Nginx → http://127.0.0.1:3000