OmniRoute Profile 等级一致性修复深度解析：聚合 XP 语义与无效总计的边界处理

导读：在 OmniRoute 的多 API Key 网关场景中，运营者级（operator-wide）Profile 页需要同时展示“所有 Key 合计的 XP”与“由此推算的等级与进度”。本片基于变更记录 fix #11604，讲解其如何通过“等级一律由聚合 XP 逆推”的语义，使等级、经验条与展示的 XP 严格自洽，并剖析 calculateLevel 对 NaN、Infinity、超大数值等无效总计的有界兜底实现，帮助你理解该网关内建 Gamification 引擎的底层数学与 SQL 聚合逻辑。

一、问题背景：Profile 等级为何会与聚合 XP“失配”

OmniRoute 内置了一套 Gamification（成就与等级）体系，XP 按 API Key 分别记账，同时也支持不绑定单个 Key 的“运营者全局 Profile 视图”。当页面同时展示两组数字——汇总显示的 XP 与当前等级/进度条——如果二者来自不同的推导口径，就会暴露明显的自相矛盾：例如 XP 合计已经跨过 2 级阈值，页面却仍显示 1 级。

变更记录 #11604 将此定义为一次 fix(dashboard)：

Keep the Profile level and progress aligned with aggregate XP, including bounded handling for invalid totals.

即两点目标：

1. 对齐口径：Profile 页展示的等级与经验条进度，必须与页面所展示的“聚合 XP”同源同口径；
2. 有界兜底：当总 XP 因数据异常出现非法值（如 NaN、Infinity、负数或超出安全整数范围的巨大数）时，等级计算必须被“钳制”到合法结果，而不是抛错或返回荒谬数值。

配套的另一个变更片段 11604-aggregate-profile-level-pin.md 把这条语义“钉死”为测试契约：getAggregateXp() 现在用 calculateLevel(SUM)（对汇总 XP 求逆）推导 currentLevel，而不是取 MAX(stored current_level)（各 Key 中存储的最高等级），并同步校准了 #3484 相关 fixture 的等级使其贴合 XP 曲线。

失配的典型成因（从实现推导）

• 多 Key 聚合≠单一 Key：Profile 无 apiKeyId 时展示全库合计。两个 Key 各自 100 XP、250 XP（单独都不到 2 级），合计 350 XP 却已超过 2 级门槛；若等级取 MAX(存储等级)，永远是 1，而页面 XP 数字却是 350。
• 存储的等级可能过期/被污染：持久化层缓存了 current_level 字段，一旦历史写入口径变化或手动修正过 XP，缓存的等级就可能与新合计不符。
• 非法总计：SQL SUM 或前端传入的数据若含非有限数、溢出值，直接代入多项式曲线求根会得到 NaN 等级或触发超长回退循环。

二、XP/等级引擎：一条明确的数学曲线

等级体系的核心是一组纯函数，位于 src/lib/gamification/xp.ts，无副作用、无 DB 调用，全部有界逻辑均可单测。

2.1 单级增量曲线

到达第 n 级所需的增量 XP（非累计）为多项式曲线：

export function xpForLevel(level: number): number {
  if (level <= 1) return 0;
  return Math.floor(100 * Math.pow(level, 1.5));
}

参考点：

等级	该级增量 XP（100·n^1.5 向下取整）
1	0（起点）
2	floor(100×2^1.5) = 282
10	3162
50	35355

2.2 累计门槛

cumulativeXpForLevel(level) 累加 2..level 的所有增量，得到到达该级所需的累计 XP。例如到达 2 级的累计门槛就是 282 XP——这正是 #3484 测试注释中提到的“cumulative threshold for level 2 is 282 XP”的由来。

2.3 逆推等级（含全部边界兜底）

export function calculateLevel(totalXp: number): number {
  if (!Number.isFinite(totalXp) || totalXp <= 0) return 1;
  const boundedXp = Math.min(totalXp, Number.MAX_SAFE_INTEGER);

  // 先用逆曲线估算起点，再对照精确的累计门槛双向校正
  let level = Math.max(1, Math.floor(Math.pow((boundedXp * 2.5) / 100, 0.4)));
  while (level > 1 && cumulativeXpForLevel(level) > boundedXp) {
    level -= 1;
  }
  while (cumulativeXpForLevel(level + 1) <= boundedXp) {
    level += 1;
  }
  return level;
}

这里实现了 fix #11604 强调的 bounded handling for invalid totals，共四道防线：

1. 非有限数与负数：NaN、±Infinity、负数或 0 一律回落为 level 1，杜绝 NaN 传播；
2. 上界钳制：有限但超过 Number.MAX_SAFE_INTEGER 的数值被钳到安全整数上限，避免浮点精度导致逆曲线估算与校正循环无法收敛；
3. 下界保护：估算起点 Math.max(1, …) 保证最小 1 级；
4. 精确校正：以累计门槛做双向 while 校正（先回退再前进），保证“恰好等于门槛”的语义是 达到该级（calculateLevel(cumulativeXpForLevel(10)) === 10）。

进度辅助函数 xpToNextLevel(totalXp) 基于 calculateLevel 返回“距下一级还差多少 XP”，与等级口径天然一致。

2.4 等级头衔与徽章档位

展示层还依赖同一输入的派生函数：

• getLevelTitle：Beginner / Explorer / Expert / Master / Legend；
• getLevelTier：bronze / silver / gold / platinum / diamond。

两者阈值与 calculateLevel 独立但保持一致，Profile 页据此渲染头像角标颜色与头衔文案。

三、聚合语义的实现：SQL 求和 + 逆推，而非取 MAX

真正落实“等级与展示 XP 对齐”的是持久化层的聚合函数 src/lib/db/gamification.ts：

export function getAggregateXp(): UserLevelRow {
  const row = db()
    .prepare(
      `SELECT COALESCE(SUM(total_xp), 0) AS total_xp,
              MAX(updated_at) AS updated_at
       FROM user_levels`
    )
    .get() as { total_xp: number; updated_at: string | null };
  const totalXp = row?.total_xp ?? 0;
  return {
    apiKeyId: "*",
    totalXp,
    currentLevel: calculateLevel(totalXp),   // 关键：由 SUM 逆推，而非 MAX(current_level)
    updatedAt: row?.updated_at ?? "",
  };
}

设计要点：

• SUM(total_xp) 与 Profile 页展示的合计 XP 使用同一条数据源，随后立即用纯函数 calculateLevel 推导等级——等级与 XP 的“失配窗口”被从架构上消除；
• 空表时 COALESCE(..., 0) 兜底为 0 XP、level 1，不会抛错；
• 标记为 apiKeyId: "*" 表示运营者全局视图；
• 注释与变更片段均强调此行为对应 #3484 引入的“dashboard profile 无 key 场景”，#11604 修正了此前可能取 MAX(stored current_level) 造成的偏差。

每个 Key 自身的写入同样保持口径一致：updateLevel/奖励落库时以 calculateLevel(amount) 同步写 current_level（src/lib/db/gamification.ts），确保单 Key 行内 total_xp ↔ current_level 永远符合 XP 曲线，聚合层因此有了可靠的输入。

四、路由入口：有 Key 与无 Key 的“双模式”

等级查询经由管理鉴权接口 src/app/api/gamification/level/route.ts 暴露：

export async function GET(request: NextRequest) {
  const authError = await requireManagementAuth(request);
  if (authError) return authError;

  const apiKeyId = new URL(request.url).searchParams.get("apiKeyId");
  const level = apiKeyId ? getXp(apiKeyId) : getAggregateXp();
  return NextResponse.json({ level }, { headers: CORS_HEADERS });
}

• 携带 ?apiKeyId=xxx：返回单 Key 的 getXp（其内部同样对存储行做 total_xp/current_level 一致性读取）；
• 不携带参数（dashboard Profile 页场景）：返回 getAggregateXp()，即本次修复的核心路径；
• 全程经 requireManagementAuth 收敛到管理作用域，属 LOCAL_ONLY 非派生子进程接口。

同族的 /api/gamification/badges、/badges/earned 在无 Key 时返回“任意 Key 已解锁的去重徽章集合”（getAllEarnedBadges 以 MIN(unlocked_at) 去重），与 Profile 聚合视图配套。

五、Profile 页的消费端：进度条与等级同源

Dashboard 的 Profile 页面 src/app/(dashboard)/dashboard/profile/page.tsx/dashboard/profile/page.tsx) 直接消费 /api/gamification/level 的返回值 { level, totalXp, ... }：

• 等级数字、等级头衔、tier 角标均由 level 派生；
• 进度条以“当前级内 XP ÷ 到达下一级所需 XP”计算百分比：

const xpProgress = xpForNext > 0 ? (xpInCurrentLevel / xpForNext) * 100 : 0;

其中当前级内 XP 与下一级门槛分别由 totalXp、cumulativeXpForLevel(level) 换算而来。由于服务端已保证 level = calculateLevel(sum(total_xp))，前端展示的“XP 数字 / 等级 / 进度百分比”三者必然指向同一个数学事实，不再出现“合计够了却不升级”或“进度超过 100%”的错位界面。

六、测试契约：把一致性钉进回归套件

本次修复并非一次性补丁，而是有完整的测试固锚，防止后续回归：

• tests/unit/gamification/aggregate-profile-3484.test.ts：覆盖空账本（0 XP → level 1，不抛错）、跨 Key 求和后按合计逆推等级（100 + 250 = 350 → level 2，尽管两个 Key 单独都只有 1 级）、以及徽章聚合去重；这是 #11604/#3484 语义的直接回归防线；
• tests/unit/gamification/xp.test.ts：逐项验证无效总计的有界处理——负数/NaN/±Infinity 回落 level 1、Number.MAX_VALUE 被钳到与 MAX_SAFE_INTEGER 等价、以及 1..100 每一档精确累计门槛都能被 calculateLevel 精确命中；
• tests/unit/gamification/db-gamification.test.ts：验证持久层读写与 updateLevel 的落库一致性；
• 运行入口沿用仓库统一的测试编排（npm test / vitest 分片配置 vitest.config.ts）。

七、小结：一条可复用的“展示一致”原则

从本次修复可以提炼出可迁移的设计经验：凡是页面同时展示“总量”与“由总量派生的状态量”，两者必须共用同一条推导链路——OmniRoute 的做法是聚合层只做 SUM，随后一律经纯函数 calculateLevel 逆推，彻底弃用对可能过期的冗余字段（MAX(current_level)）的依赖；同时把非法输入的兜底下沉到纯函数层（非有限数回落、超大数钳制、双向校正），让 UI 在任何脏数据下都不会渲染出 NaN 或无限循环推导的等级。这种“纯函数计算 + SQL 只做聚合 + 展示层单向消费”的分层，对任何含排行榜、经验值、信誉分等成长体系的网关类项目都具备直接参考价值。