optimize+注释

backend/app/services/matching_service.py

@@ -1,3 +1,7 @@
+"""
+匹配服务：根据用户兴趣关键词（精确 + 语义）推荐事件
+打分融合：匹配分 + 标签相关度 + 热度 + 新鲜度加成
+"""
 import os
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
@@ -123,7 +127,7 @@ def recommend_events_for_user(
         else PREFERENCE_SEMANTIC_THRESHOLD
     )
 
-    # 读取用户兴趣词
+    # 1. 读取用户兴趣词
     preferences = (
         db.query(UserTopicPreference)
         .filter(UserTopicPreference.user_id == user_id)
@@ -136,7 +140,7 @@ def recommend_events_for_user(
     if not preference_keywords:
         return []
 
-    # 读取候选事件（先做时间和热度过滤，避免全表扫描）
+    # 2. 读取候选事件（时间 + 热度过滤，避免全表扫描）
     time_limit = utcnow() - timedelta(hours=hours)
     events = (
         db.query(UnifiedEvent)
@@ -177,7 +181,7 @@ def recommend_events_for_user(
     if not event_topics:
         return []
 
-    # 批量编码用户词和标签词，避免逐条调用模型
+    # 3. 批量编码用户词与标签词，减少模型调用次数
     unique_preference_keywords = list(dict.fromkeys(preference_keywords))
     unique_topic_keywords = list(dict.fromkeys([row[1] for row in topic_rows if row[1]]))
     pref_vec_map = _build_keyword_embedding_map(unique_preference_keywords)
@@ -196,7 +200,7 @@ def recommend_events_for_user(
         semantic_hits: list[dict[str, Any]] = []
         score = 0.0
 
-        # 对事件标签逐个匹配用户兴趣
+        # 对每个事件标签做精确匹配或语义匹配
         for topic_keyword, topic_relevance in topic_list:
             normalized_topic = _normalize_text(topic_keyword)
             topic_relevance_score = float(topic_relevance) if topic_relevance is not None else 50.0