@mai-kit/analysis

@mai-kit/analysis 提供玩家成绩取得后的纯分析能力：重算 Best50、评估升分候选、 比较两份 B50 快照、汇总 Rating 构成与里程碑缺口。包内不请求查分器或曲目 API， 输入由 @mai-kit/prober 与 @mai-kit/database 等调用方准备。

示例

重算 Best50

import { recalculateBests } from "@mai-kit/analysis";

const bests = recalculateBests(scores, (score) => newSongIds.has(score.id));

查找能抬 B15/B35 的加分候选（全曲 + 真实 B50 地板）

import { rankBestsUpgradeCandidates } from "@mai-kit/analysis";

// 目标至少 SSS+（评级下限）；也可只传 targetAchievement: 100.5
const candidates = rankBestsUpgradeCandidates(entries, {
  currentBests: bests,
  isNewSong,
  minRate: "sssp",
  limit: 10,
});

Rating 构成与整千缺口

import { summarizeBestsRating, ratingGapToNextThousand } from "@mai-kit/analysis";

const summary = summarizeBestsRating(bests);
const gap = ratingGapToNextThousand(summary.total);

接口与模型

接口	描述
BestsChartChange	两份 B50 中同一谱面的变化。
BestsComparison	两份 B50 快照的比较结果。
BestsEntry	B50 中的一张谱面及其分区和名次。
RatedScore	含单曲 Rating 的成绩；用于需要精确比较 Rating 的分析。
ScoreUpgrade	单张谱面提升到目标达成率后的结果。
ScoreWithLevelValue	带精确定数的成绩输入。

B50 分析

函数	描述
recalculateBests	从全量成绩重新选出新曲 B15 与旧曲 B35。

升分分析

名称	描述
RankBestsUpgradeOptions	rankBestsUpgradeCandidates 的选项。
RankUpgradeOptions	rankUpgradeCandidates 的选项。
analyzeScoreUpgrade	计算一张谱面提升到目标达成率后的单曲 Rating 增量。
rankBestsUpgradeCandidates	在全曲成绩中，找出刷到目标达成率后能抬高 B15 或 B35 总分的谱面。
rankUpgradeCandidates	按单曲 Rating 增量排列候选（不考虑 B15/B35）。
resolveUpgradeTarget	解析「目标达成率」：可用评级下限、显式达成率，或两者取较高。

快照对比

函数	描述
compareBests	比较两份 B50 快照。

Rating 构成

名称	描述
BestsRatingSummary	B50 Rating 构成：新曲 B15 / 旧曲 B35 贡献与 tail（区底）。
RatingMilestoneGap	Rating 里程碑缺口（如下一整千、或自定义目标）。
ratingGapToNextThousand	计算到下一个整千（如 15_823 → 16_000）还差多少 Rating。
ratingGapToTarget	计算到指定目标 Rating 的缺口。
summarizeBestsRating	汇总一份 B50 的 Rating 构成（分区合计、占比、区底）。