v0.3.0 · Next.js App Router · Better Auth · WCL cache

LogForge Backend API

面向前端和移动端集成的可视化接口说明。公开 WCL 查询接口负责缓存和代理，收藏接口依赖 Better Auth session cookie。

查看接口返回首页

Request flowTTL 1 hour

ClientWeb / Expo app携带查询参数或 Better Auth cookie 发起请求

NextRoute handlers校验枚举、解析请求体、返回统一 JSON

CachePostgreSQL + Drizzle缓存 WCL servers、search、detail、rankings

WCLWarcraft Logs GraphQL缓存失效后刷新上游数据

11documented endpoints

6public WCL routes

4session-only favorite routes

1hWCL cache TTL

通用约定

所有接口默认返回 JSON，错误响应使用统一的 error 字段。

WCL flavor

official, titan, anniversary

Region slug

US, CN, EU, KR, TW

Auth scope

/api/wcl/favorites* 需要 Better Auth 登录态

接口参考

使用顶部搜索或分组筛选快速定位接口。

GET

Liveness Check

/health

Public

用途

进程级健康检查。适合平台、负载均衡或 uptime monitor 判断服务是否存活。

200 OK

Response

{
  "status": "ok",
  "service": "logforge-backend",
  "checks": {
    "process": "ok"
  }
}

GET

Readiness Check

/ready

Public

用途

依赖级 readiness 检查。数据库和关键认证配置可用时返回 ready，否则返回 503。

200 ready503 not_ready

Response

{
  "status": "ready",
  "service": "logforge-backend",
  "checks": {
    "database": "ok",
    "config": {
      "databaseUrl": true,
      "authUrl": true,
      "betterAuthSecret": true,
      "googleOAuth": true
    }
  }
}

ANY

Better Auth Handler

/api/auth/*

Better Auth

用途

Better Auth 接管的认证路由，支持 Google OAuth、Expo 和 Next cookies。

参数	必填	说明
App name	-	LogForge
Base URL	-	BETTER_AUTH_URL，默认 http://localhost:3000
Database	-	PostgreSQL via Drizzle adapter

GETPOST

Client

import { authClient } from "@/lib/auth-client";

await authClient.signIn.social({
  provider: "google",
});

GET

Available Regions

/api/wcl/regions

Public

用途

获取指定 WCL flavor 可用地区。上游失败时返回配置中的 fallback 地区。

参数	必填	说明
flavor	是	official, titan, anniversary

200400 invalid flavor502 upstream

cURL

curl "http://localhost:3000/api/wcl/regions?flavor=titan"

GET

Region Servers

/api/wcl/servers

Public · Cached

用途

获取指定 flavor 和 region 下的服务器列表，结果会写入 region servers cache。

参数	必填	说明
flavor	是	WCL flavor
regionSlug	是	WCL region slug
regionId	否	不传时按 fallback 顺序推导

200400 invalid input502 upstream

Response

{
  "servers": [
    { "id": 1, "name": "时光", "slug": "时光" }
  ],
  "lastRefreshedAt": "2026-04-29T08:00:00.000Z"
}

GET

Character Search

/api/wcl/characters/search

Public · Cached

用途

按角色名搜索指定地区服务器中的角色。空搜索词会直接返回空结果。

参数	必填	说明
flavor	是	WCL flavor
regionSlug	是	WCL region slug
searchTerm	否	角色名；空值返回空数组

200400 invalid input502 upstream

Response

{
  "results": [
    {
      "id": "123456",
      "name": "Player",
      "classID": 1,
      "className": "Warrior",
      "classSlug": "warrior",
      "serverName": "时光",
      "serverSlug": "时光"
    }
  ],
  "lastRefreshedAt": "2026-04-29T08:00:00.000Z"
}

GET

Character Detail

/api/wcl/characters/{id}

Public · Cached

用途

获取 WCL 角色详情和可用分区/副本信息。未找到角色时 character 为 null。

参数	必填	说明
Path id	是	WCL 角色 ID
flavor	是	WCL flavor

200400 invalid flavor502 upstream

Response shape

{
  "character": {
    "id": 123456,
    "name": "Player",
    "classID": 1,
    "className": "Warrior",
    "classSlug": "warrior",
    "level": 60,
    "server": { "id": 1, "name": "时光", "slug": "时光" },
    "specs": [],
    "zones": []
  },
  "lastRefreshedAt": "2026-04-29T08:00:00.000Z"
}

GET

Character Rankings

/api/wcl/characters/{id}/rankings

Public · Cached

用途

获取角色在指定副本、指标、专精和分区下的排名数据；每秒指标会还原 WCL zoneRankings 的内部偏移值。

参数	必填	说明
Path id	是	数字字符串 WCL 角色 ID
flavor	是	WCL flavor
metric	是	dps, hps, bossdps
zoneId	是	WCL zone ID
specSlug	否	空值代表全部专精
partitionId	否	空值代表默认分区

200400 invalid input502 upstream

cURL

curl "http://localhost:3000/api/wcl/characters/123456/rankings?flavor=titan&metric=dps&zoneId=1049"

GET

List Favorites

/api/wcl/favorites

Session required

用途

返回当前登录用户的收藏角色列表，按 lastUpdatedAt 倒序排列。

200401 unauthorized

cURL

curl "http://localhost:3000/api/wcl/favorites" \
  -H "Cookie: better-auth.session_token=..."

POST

Add Favorite

/api/wcl/favorites

Session required

用途

新增或更新一个收藏角色。相同用户、flavor 和角色 id 会执行 upsert。

参数	必填	说明
id	是	WCL 角色 ID
flavor	是	WCL flavor
regionSlug	是	WCL region slug
serverSlug	是	服务器 slug
serverName	是	服务器名称
characterName	是	角色名
classSlug	否	职业 slug
preferredZoneId	否	偏好 zone ID
lastUpdatedAt	否	毫秒时间戳

200400 invalid favorite401 unauthorized

Body

{
  "id": "123456",
  "flavor": "titan",
  "regionSlug": "CN",
  "serverSlug": "时光",
  "serverName": "时光",
  "characterName": "Player",
  "classSlug": "warrior",
  "preferredZoneId": 1049,
  "lastUpdatedAt": 1777449600000
}

DELETE

Delete Favorite

/api/wcl/favorites/{id}

Session required

用途

删除当前登录用户指定 flavor 下的收藏角色。

参数	必填	说明
Path id	是	WCL 角色 ID
flavor	是	WCL flavor

200400 invalid favorite401 unauthorized

cURL

curl -X DELETE "http://localhost:3000/api/wcl/favorites/123456?flavor=titan" \
  -H "Cookie: better-auth.session_token=..."

POST

Sync Favorites

/api/wcl/favorites/sync

Session required

用途

用客户端收藏列表覆盖服务端当前用户收藏；按 flavor:id 去重，最多 200 个。

200400 invalid favorites401 unauthorized

Body

{
  "favorites": [
    {
      "id": "123456",
      "flavor": "titan",
      "regionSlug": "CN",
      "serverSlug": "时光",
      "serverName": "时光",
      "characterName": "Player",
      "lastUpdatedAt": 1777449600000
    }
  ]
}