OnlineJudge/docs/superpowers/specs/2026-08-03-achievement-system-design.md

成就系统设计

日期：2026-08-03 涉及仓库：OnlineJudge（后端）、ojnext（前端）

目标

给 OJ 加一套日式游戏风格的成就（トロフィー）系统，同时服务两个目的：

1. 激励学生持续刷题 —— 累积型成就，人人拿得到，靠进度条产生拉动力
2. 满足收集欲 —— 隐藏型成就，条件奇葩，靠打码和稀有度产生惊喜

成就是纯荣誉，不发放任何可消费的奖励（积分、道具、权限），不接入经济系统。

核心设计取舍

决策	选择	理由
规则定义位置	数据库可配	加成就不用部署
奇葩条件怎么办	代码注册指标，后台组合条件	可配性和表达力的折中，见下文
判定时机	判题完成后异步（dramatiq）	不阻塞、不拖累判题链路
指标数据来源	用户指标快照表 UserStat	判定 O(1)，与"后台可配"形状对齐
一条成就的条件数	单条件	避免把后台做成规则引擎，复合需求用复合指标解决
与现有题单奖章的关系	分层共存	作用域不同，共享展示层和通知通道

关于"可配性"的边界

这是整个设计的关键，必须对齐认知：

	定义在哪	改动成本
能测量什么（指标）	代码 achievement/metrics.py	写代码 + 部署 + 跑一次 recompute
多少算达成、叫什么、藏不藏	后台表单	纯配置，即时生效

• 「凌晨提交 10 次 → 夜猫子」和「凌晨提交 100 次 → 生活作息已崩坏」是两条成就、同一个指标，纯后台加
• 「代码里写了 goto」是新维度，必须改代码

推论：初始指标清单要一次性铺宽，铺够之后很长一段时间只需要在后台配置。

与现有题单奖章（ProblemSetBadge）的关系

problemset/ 已存在一套奖章系统：

	题单奖章	成就
作用域	绑定单个题单（problemset FK）	全站
条件	3 种，限于该题单进度内	任意注册指标
触发	同步，ProblemSetProgress 更新时	判题后异步
生命周期	随题单删除而删除	独立

采取分层共存，概念上区分：奖章 = 关卡奖励（题单内），成就 = 奖杯（全站累积）。

两套模型各自保留，共享三样东西：

1. 解锁通知通道 —— 奖章现在是静默入库的，学生不知道自己拿到了；接入后终于有反馈
2. 奖杯馆页面 —— 奖章作为其中一个分区，按题单分组展示
3. 咬合点 —— badge_count（已获奖章数）、problemset_completed（完成题单数）成为成就的普通指标，于是可以配出「收集 10 枚奖章」这类元成就

顺带修复现有 problemset/views/oj.py:_check_badges() 的两个缺陷：

• 循环内逐条 exists() 查询（N+1）→ 改为一次查询取全部候选
• UserBadge.objects.create() 未用 get_or_create → 并发重复提交会撞 unique constraint 抛异常

数据模型

新建 Django app achievement/，沿用项目现有结构（models.py / serializers.py / views/{oj,admin}.py / urls/{oj,admin}.py）。

Achievement — 成就定义（管理员可配）

字段	类型	说明
name	TextField	成就名称
description	TextField	成就描述
icon	TextField	emoji 或图标 URL
rarity	TextField(choices)	bronze / silver / gold / platinum
hidden	BooleanField	隐藏成就：未解锁时前端显示 ??? 且描述打码
metric	TextField(choices)	指标名，choices 由代码注册表动态提供
operator	TextField(choices)	gte / lte / eq
threshold	IntegerField	阈值
visible	BooleanField	是否上架；下架的不参与判定也不展示
unlock_count	IntegerField	已解锁人数计数器，解锁时 F()+1
order	IntegerField	排序
create_time	DateTimeField

一条成就 = 一个条件，不支持 AND/OR 组合。理由：组合条件会把后台变成小型规则编辑器，而「AC 100 题且连续登录 30 天」这类需求，注册一个复合指标（约 20 行 Python）远比做通用规则引擎便宜。真需要了再加。

阶梯成就（AC 10 / 50 / 100）就是三条同 metric 不同 threshold 的记录，前端按 metric 自动归组成系列，不需要额外字段。

operator 需要 lte 是因为存在「最短 AC 代码 ≤ 50 字符」这类成就。

UserStat — 指标快照

user         OneToOneField(User)
metrics      JSONField   # {"accepted_count": 42, "midnight_submissions": 3, ...}
update_time  DateTimeField

所有指标存一个 JSONB，不开固定列 —— 加新指标零迁移。

不复用 UserProfile.accepted_number / submission_number。 UserStat 是成就系统唯一的指标源，口径自己闭环，避免两处计数器互相漂移。

UserAchievement — 解锁记录

user          ForeignKey(User)
achievement   ForeignKey(Achievement)
unlock_time   DateTimeField
backfilled    BooleanField   # 见"历史数据补发"
unique_together (user, achievement)
index (user, -unlock_time)

全站获得率不实时聚合，读 Achievement.unlock_count / 分母。

分母定义：User.objects.filter(is_disabled=False).count()，Redis 缓存 1 小时。不用"有过提交的用户数"之类的动态口径 —— 分母会随时间波动，导致同一个成就的获得率忽高忽低，学生会觉得是 bug。

指标注册表

achievement/metrics.py，key → 指标类的注册表。管理员后台 metric 下拉框的选项即这张表的 key 列表。

每个指标实现两个方法：

@metric("midnight_submissions", "凌晨提交次数", "0:00–5:00 之间的提交")
class MidnightSubmissions:
    def on_submission(self, metrics, sub, ctx):
        """增量：判题后原地更新 metrics dict"""
        if 0 <= timezone.localtime(sub.create_time).hour < 5:
            metrics["midnight_submissions"] += 1

    def recompute(self, user):
        """全量：backfill / 口径变更 / 兜底重算"""
        return Submission.objects.filter(user_id=user.id, ...).count()

recompute 是安全网：加新指标、改口径、怀疑数据漂移时，一条管理命令全站重算，不依赖增量逻辑的历史正确性。

ctx 是每次判题预先查好一次的共享上下文（这道题此前提交次数、是否首次 AC、今天已 AC 题数等），所有指标复用，避免各自查库。

极小值型指标的初始值陷阱

min_ac_code_chars 这类"越小越好"的指标不能初始化为 0，否则「最短 AC 代码 ≤ 50 字符」对从未 AC 过的新用户恒成立（0 <= 50），注册当天就白送一个白金奖杯。

规则：指标未产生过有效值时，key 在 metrics 中不存在（而非置 0）。判定第 6 步遇到 metric 不在 metrics 里的成就直接跳过。

这条对所有指标统一适用，累积型指标（缺失即视为未达标）行为不变，极小值型指标由此被正确保护。前端进度条同理：指标缺失时显示 0 / N 而不是拿缺失值参与计算。

初始指标清单

累积型（养习惯，人人可得）

key	含义
accepted_count	去重 AC 题目数
submission_count	提交总数
max_ac_streak_days	最长连续 AC 天数
active_days	有提交的累计天数
languages_used	用过的语言种类数
contest_joined	参加过的比赛数
badge_count	获得的题单奖章数
problemset_completed	完成的题单数

隐藏型（收集癖，奇葩维度）

key	含义
first_try_ac_count	一发入魂：首次提交即 AC 的次数
midnight_submissions	0:00–5:00 的提交次数
compile_error_count	编译错误累计次数
max_wa_before_ac	屡败屡战：单题失败最多次后终于通过
max_ac_in_one_day	单日最多 AC 题数
min_ac_code_chars	最短 AC 代码字符数（配 lte）
max_code_lines	最长代码行数

判定流程

判题完成后（judge/ 现有链路末端）投递 dramatiq 任务：

check_achievements(user_id, submission_id)
  1. select_for_update 取 UserStat（无则建）
  2. 预查一次 ctx
  3. 遍历注册表，各指标增量更新 metrics JSONB
  4. 保存 UserStat
  5. 一次查询取出：visible=True 且该用户尚未解锁的全部 Achievement
  6. 内存中比对 metric / operator / threshold —— 零额外查询
  7. bulk_create UserAchievement(ignore_conflicts=True)
  8. F() 批量 +1 unlock_count
  9. WebSocket 推送新解锁列表

第 5 步一次取全部候选、第 6 步纯内存比对，是刻意与现有 _check_badges() 逐条查询相反的写法。整个任务对一次判题只多 3~4 条 SQL。

任务内异常全部捕获并记日志 —— 成就算错绝不能影响判题结果，这也是选异步的意义。

第 9 步的推送封装为 achievement/notify.py 中的独立函数，题单奖章解锁时也调用它。

前端：奖杯馆

新页面 ojnext/src/oj/achievement/index.vue，路由 /achievement?name=xxx（不传 = 自己），与现有 /user?name=xxx 约定一致，公开查看他人成就天然成立。路由 meta 保持 requiresAuth: true，与 /user 一致。

页面结构

1. 顶部总览条 —— 总完成度大字百分比，右侧四档稀有度计数（🥉 12/20　🥈 5/15　🥇 2/10　💎 0/1）。白金档留给「全收集」类成就。

2. 成就网格，三种视觉状态：

状态	显示内容
已解锁	彩色图标、名称、描述、解锁日期、全站获得率（「仅 3.2% 的人获得」）
未解锁·公开	灰度图标、描述可见、进度条（42/100）
未解锁·隐藏	剪影/问号、名称 ???、描述打码，仅露稀有度

3. 分区 tab：全部 / 已获得 / 未获得 / 题单奖章。最后一个 tab 按题单分组，复用现有 getUserBadges。

日式味道来自三个细节：进度条（未解锁也看得见离目标多远，拉动力来源）、获得率（炫耀的硬通货）、隐藏成就打码（收集欲来源）。获得率低于 5% 的自动加稀有闪光边框。

解锁弹窗

AchievementToast.vue，复用 shared/composables/websocket：

• 右下角滑入、奖杯光效、3 秒淡出
• 多个同时解锁排队依次弹出，不重叠堆积
• 题单奖章解锁复用同一组件

炫耀入口

• oj/user/index.vue 个人主页加成就摘要区：最近 5 枚 + 完成度 + 跳转奖杯馆
• oj/rank/list.vue 排行榜每行挂最稀有的 1–2 枚徽章

历史数据补发

老用户已积累数百次 AC，上线当天必须补发，否则成就系统对现有用户是空的。

python manage.py recompute_achievements [--user <id>] [--silent]

遍历用户 → 对每个指标调 recompute() 重建 UserStat → 判定 → bulk_create。

补发不伪造解锁时间

UserAchievement.backfilled 为 True 的记录，前端不显示具体日期，只显示「已获得」。把数百条历史成就全盖上上线当天的时间戳，会让「最近获得」板块从第一天起就失去意义。

首次上线使用 --silent

不推送通知 —— 学生一登录被 30 个奖杯糊脸是灾难。改为个人主页顶部一条一次性提示：「成就系统上线了，你已解锁 23 个成就 →」。

--silent 是开关而非硬编码：以后加了新指标再跑重算时应当正常推送。

阈值下调的补发

管理员把阈值从 100 调到 50 时，已达标的老用户不会自动解锁（判定只在判题时发生）。解法：Achievement 保存时若为新建或阈值降低，触发一个只扫这一条成就的 dramatiq 任务。

实现陷阱：用 JSONB 筛选达标用户时，UserStat.objects.filter(metrics__accepted_count__gte=50) 在 Django JSONField 上走的是 JSON 值比较，数字按字符串序比较（"9" > "50"），结果错误。必须显式 cast：

from django.db.models.functions import Cast
from django.db.models.fields.json import KeyTextTransform

UserStat.objects.annotate(
    v=Cast(KeyTextTransform("accepted_count", "metrics"), IntegerField())
).filter(v__gte=50)

API

用户侧（achievement/urls/oj.py）

路径	说明
GET /api/achievements?name=<username>	奖杯馆数据：全部成就定义 + 该用户解锁状态 + 进度值 + 获得率。隐藏且未解锁的成就，name/description 在序列化层就替换为占位符，不下发真实内容
GET /api/achievements/summary?name=<username>	个人主页摘要：完成度、各稀有度计数、最近 5 枚

管理侧（achievement/urls/admin.py）

路径	说明
GET/POST/PUT/DELETE /api/admin/achievement	成就 CRUD
GET /api/admin/achievement/metrics	可用指标列表（key + 中文名 + 说明），供后台下拉框

管理列表页必须显示每条成就的 unlock_count —— 阈值配错（手滑写成 10000）时学生永远拿不到也永远不会来问，这个计数器是唯一的仪表盘。配置一周后仍为 0，多半是配错而非太难。

不做的事（YAGNI）

• 成就不发放任何可消费奖励，不接积分/道具/权限体系
• 不做 AND/OR 组合条件
• 不做成就的用户自定义展示顺序、不做「佩戴徽章」
• 不做事件流表（AchievementEvent）
• 不做定时全量兜底扫描（recompute_achievements 手动跑即可）