From c51e9332d116a4e381b6ebfad716a0991e5e38ae Mon Sep 17 00:00:00 2001
From: yuetsh <517252939@qq.com>
Date: Mon, 3 Aug 2026 23:46:55 -0600
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=88=90=E5=B0=B1=E7=B3=BB=E7=BB=9F?=
 =?UTF-8?q?=E8=AE=BE=E8=AE=A1=E6=96=B9=E6=A1=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

日式游戏风格的全站成就系统设计：代码注册指标、后台配置条件、
判题后异步判定、前端奖杯馆。与现有题单奖章分层共存。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../2026-08-03-achievement-system-design.md   | 289 ++++++++++++++++++
 1 file changed, 289 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-03-achievement-system-design.md

diff --git a/docs/superpowers/specs/2026-08-03-achievement-system-design.md b/docs/superpowers/specs/2026-08-03-achievement-system-design.md
new file mode 100644
index 0000000..59c58e0
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-03-achievement-system-design.md
@@ -0,0 +1,289 @@
+# 成就系统设计
+
+日期：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 列表。
+
+每个指标实现两个方法：
+
+```python
+@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：
+
+```python
+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` 手动跑即可）