feat: 排行榜按用户最高分去重，避免一人霸榜

README.md

@@ -165,3 +165,10 @@ python -m unittest discover -s test -p test_upload_form_limits.py -v
 ### 排行榜图片路径
 
 `/facescore/leaderboard`、`/facescore/app/leaderboard`、`/facescore/wechat/leaderboard` 的 GET/POST 响应中，`items[]` 增加 `file_path` 字符串，原样返回图片表中的路径（例如 `face/example.webp`）。新查询和缓存命中均包含该字段；不是新增完整 URL，也不改变前端当前头像展示。无路径时返回空字符串。本次字段扩展不需要数据库迁移。
+
+### 排行榜按用户去重（2026-09-30）
+
+为避免单一用户多次上传高分照片霸占排行榜前排（“一人霸榜”）：
+- 排行榜查询（`/facescore/leaderboard`、`/facescore/app/leaderboard`、`/facescore/wechat/leaderboard`）按用户标识（`nickname`）去重，每个用户仅保留最高分的一条记录进榜；若未提供昵称（匿名上传）则独立保留每张记录。
+- 排名计算（`/facescore/rank`、`/facescore/app/rank`、`/facescore/wechat/rank`）同步按用户最高分口径聚合统计，保证测完打分结果页的排位与排行榜数据完全自洽。
+- 本次改动纯逻辑优化，不需要数据库迁移。

database.py

@@ -759,16 +759,22 @@ async def get_face_score_rank(
     region_percentile = 0.0
 
     try:
-        # 排行榜按每次评分记录排名；/rank 必须使用完全相同的记录口径。
+        # 排行榜按用户最高分去重；/rank 必须使用完全相同的用户最高分去重口径。
+        user_key_expr = "(CASE WHEN nickname IS NOT NULL AND nickname != '' THEN nickname ELSE CONCAT('id_', id) END)"
         g_stats_row = await fetch_one(
             f"""
             SELECT COUNT(*) AS t,
-                   COALESCE(SUM(CASE WHEN {score_expr} > %s THEN 1 ELSE 0 END), 0) + 1 AS r
-            FROM tpl_app_processed_images
-            WHERE category = 'face'
-              AND {scope}
-              AND updated_at >= DATE_SUB(NOW(), INTERVAL {days_limit} DAY)
-              AND score > 0
+                   COALESCE(SUM(CASE WHEN max_score > %s THEN 1 ELSE 0 END), 0) + 1 AS r
+            FROM (
+                SELECT {user_key_expr} AS user_key,
+                       MAX({score_expr}) AS max_score
+                FROM tpl_app_processed_images
+                WHERE category = 'face'
+                  AND {scope}
+                  AND updated_at >= DATE_SUB(NOW(), INTERVAL {days_limit} DAY)
+                  AND score > 0
+                GROUP BY user_key
+            ) AS ranked_users
             """,
             (score_val, client_source)
         )
@@ -787,12 +793,17 @@ async def get_face_score_rank(
             r_stats_row = await fetch_one(
                 f"""
                 SELECT COUNT(*) AS t,
-                       COALESCE(SUM(CASE WHEN {score_expr} > %s THEN 1 ELSE 0 END), 0) + 1 AS r
-                FROM tpl_app_processed_images
-                WHERE category = 'face' AND region = %s
-                  AND {scope}
-                  AND updated_at >= DATE_SUB(NOW(), INTERVAL {days_limit} DAY)
-                  AND score > 0
+                       COALESCE(SUM(CASE WHEN max_score > %s THEN 1 ELSE 0 END), 0) + 1 AS r
+                FROM (
+                    SELECT {user_key_expr} AS user_key,
+                           MAX({score_expr}) AS max_score
+                    FROM tpl_app_processed_images
+                    WHERE category = 'face' AND region = %s
+                      AND {scope}
+                      AND updated_at >= DATE_SUB(NOW(), INTERVAL {days_limit} DAY)
+                      AND score > 0
+                    GROUP BY user_key
+                ) AS ranked_users
                 """,
                 (score_val, region_code, client_source)
             )
@@ -869,7 +880,7 @@ async def _get_cached_face_score_leaderboard(
 ) -> Dict[str, Any]:
     """
     获取颜值评分记录排行榜 Top N (支持地区榜与全球榜)。
-    每次评分都是独立榜单记录，不再按用户最高分去重。
+    按用户（nickname）去重，每个用户仅保留最高分记录；无昵称的匿名记录独立保留。
     """
     from region_code_utils import get_country_name_by_region_code
     scope = _ranking_scope(client_source, "candidate")
@@ -905,6 +916,8 @@ async def _get_cached_face_score_leaderboard(
     success = True
     items = []
     candidate_score_expr = "(CASE WHEN candidate.score <= 10.0 THEN candidate.score * 10.0 ELSE candidate.score END)"
+    better_score_expr = "(CASE WHEN better.score <= 10.0 THEN better.score * 10.0 ELSE better.score END)"
+    better_scope = _ranking_scope(client_source, "better")
     try:
         if region_code:
             query = f"""
@@ -914,10 +927,26 @@ async def _get_cached_face_score_leaderboard(
                 WHERE candidate.category = 'face' AND candidate.score > 0 AND candidate.region = %s
                   AND {scope}
                   AND candidate.updated_at >= DATE_SUB(NOW(), INTERVAL {days_limit} DAY)
+                  AND (
+                      candidate.nickname IS NULL
+                      OR candidate.nickname = ''
+                      OR NOT EXISTS (
+                          SELECT 1
+                          FROM tpl_app_processed_images AS better
+                          WHERE better.nickname = candidate.nickname
+                            AND better.category = 'face' AND better.score > 0 AND better.region = %s
+                            AND {better_scope}
+                            AND better.updated_at >= DATE_SUB(NOW(), INTERVAL {days_limit} DAY)
+                            AND (
+                                {better_score_expr} > {candidate_score_expr}
+                                OR ({better_score_expr} = {candidate_score_expr} AND better.id < candidate.id)
+                            )
+                      )
+                  )
                 ORDER BY score DESC, candidate.id ASC
                 LIMIT {safe_limit}
             """
-            rows = await fetch_all(query, (region_code, client_source))
+            rows = await fetch_all(query, (region_code, client_source, region_code, client_source))
         else:
             query = f"""
                 SELECT candidate.id, {candidate_score_expr} AS score, candidate.region,
@@ -926,12 +955,35 @@ async def _get_cached_face_score_leaderboard(
                 WHERE candidate.category = 'face' AND candidate.score > 0
                   AND {scope}
                   AND candidate.updated_at >= DATE_SUB(NOW(), INTERVAL {days_limit} DAY)
+                  AND (
+                      candidate.nickname IS NULL
+                      OR candidate.nickname = ''
+                      OR NOT EXISTS (
+                          SELECT 1
+                          FROM tpl_app_processed_images AS better
+                          WHERE better.nickname = candidate.nickname
+                            AND better.category = 'face' AND better.score > 0
+                            AND {better_scope}
+                            AND better.updated_at >= DATE_SUB(NOW(), INTERVAL {days_limit} DAY)
+                            AND (
+                                {better_score_expr} > {candidate_score_expr}
+                                OR ({better_score_expr} = {candidate_score_expr} AND better.id < candidate.id)
+                            )
+                      )
+                  )
                 ORDER BY score DESC, candidate.id ASC
                 LIMIT {safe_limit}
             """
-            rows = await fetch_all(query, (client_source,))
+            rows = await fetch_all(query, (client_source, client_source))
 
+        seen_users = set()
         for row in rows:
+            raw_nick = str(row.get("nickname") or "").strip()
+            user_key = raw_nick if raw_nick else f"id_{row.get('id')}"
+            if user_key in seen_users:
+                continue
+            seen_users.add(user_key)
+
             row_id = int(row.get("id") or 0)
             score_val = round(float(row.get("score") or 0.0), 2)
             row_region = row.get("region") or region_code or "US"

test/test_ranking_consistency.py

@@ -43,7 +43,7 @@ class RankingConsistencyTest(unittest.IsolatedAsyncioTestCase):
         database._RANK_CACHE.clear()
         database._LEADERBOARD_CACHE.clear()
 
-    async def test_rank_counts_individual_score_records(self):
+    async def test_rank_counts_unique_users_highest_scores(self):
         fetch_one = AsyncMock(side_effect=[{"t": 40, "r": 7}, {"t": 3, "r": 1}])
         with patch.object(database, "fetch_one", fetch_one):
             result = await database.get_face_score_rank(88.85, "CN")
@@ -53,11 +53,11 @@ class RankingConsistencyTest(unittest.IsolatedAsyncioTestCase):
         self.assertEqual(40, result["global_total"])
         self.assertEqual(1, result["region_rank"])
         self.assertEqual(3, result["region_total"])
-        self.assertNotIn("GROUP BY nickname", fetch_one.await_args_list[0].args[0])
+        self.assertIn("GROUP BY user_key", fetch_one.await_args_list[0].args[0])
         self.assertEqual((88.85, "android"), fetch_one.await_args_list[0].args[1])
         self.assertEqual((88.85, "CN", "android"), fetch_one.await_args_list[1].args[1])
 
-    async def test_leaderboard_keeps_each_record_and_marks_current_device(self):
+    async def test_leaderboard_deduplicates_by_user_and_keeps_highest_score(self):
         rows = [
             {
                 "id": 4,
@@ -83,17 +83,64 @@ class RankingConsistencyTest(unittest.IsolatedAsyncioTestCase):
             result = await database.get_face_score_leaderboard(None, 50, "current-device")
 
         self.assertTrue(result["success"])
-        self.assertEqual(2, result["total_records"])
+        self.assertEqual(1, result["total_records"])
+        self.assertEqual(1, len(result["items"]))
         self.assertEqual(88.85, result["items"][0]["score"])
         self.assertTrue(result["items"][0]["is_current_user"])
-        self.assertTrue(result["items"][1]["is_current_user"])
         self.assertEqual("android_release_current-device", result["items"][0]["nickname"])
         self.assertEqual("小星星", result["items"][0]["display_name"])
         query = fetch_all.await_args_list[0].args[0]
-        self.assertNotIn("NOT EXISTS", query)
+        self.assertIn("NOT EXISTS", query)
+        self.assertIn("better.nickname = candidate.nickname", query)
         self.assertIn("ORDER BY score DESC, candidate.id ASC", query)
         self.assertIn("LIMIT 50", query)
 
+    async def test_leaderboard_keeps_multiple_unique_users_and_anonymous_records(self):
+        rows = [
+            {
+                "id": 1,
+                "score": 95.0,
+                "region": "CN",
+                "nickname": "user_a",
+                "extra_metadata": '{"gender":"Male","age":"22"}',
+                "updated_at": "2026-09-25 10:00:00",
+            },
+            {
+                "id": 2,
+                "score": 90.0,
+                "region": "CN",
+                "nickname": "user_a",
+                "extra_metadata": '{"gender":"Male","age":"22"}',
+                "updated_at": "2026-09-24 10:00:00",
+            },
+            {
+                "id": 3,
+                "score": 92.0,
+                "region": "CN",
+                "nickname": "user_b",
+                "extra_metadata": '{"gender":"Female","age":"24"}',
+                "updated_at": "2026-09-25 11:00:00",
+            },
+            {
+                "id": 4,
+                "score": 91.0,
+                "region": "CN",
+                "nickname": None,  # 匿名记录
+                "extra_metadata": '{"gender":"Female","age":"23"}',
+                "updated_at": "2026-09-25 12:00:00",
+            },
+        ]
+        fetch_all = AsyncMock(return_value=rows)
+        with patch.object(database, "fetch_all", fetch_all):
+            result = await database.get_face_score_leaderboard(None, 50, client_source="wechat")
+
+        self.assertTrue(result["success"])
+        # user_a (95) 保留，user_a (90) 被去重；user_b (92) 保留；匿名 (91) 保留
+        self.assertEqual(3, result["total_records"])
+        self.assertEqual([95.0, 92.0, 91.0], [i["score"] for i in result["items"]])
+        self.assertEqual([1, 2, 3], [i["rank"] for i in result["items"]])
+        self.assertEqual(["user_a", "user_b", ""], [i["nickname"] for i in result["items"]])
+
     async def test_different_limits_do_not_share_partial_cache(self):
         fetch_all = AsyncMock(return_value=[])
         with patch.object(database, "fetch_all", fetch_all):