15. 数据驱动决策：从免费 Analytics 到智能推荐

-- 我们的 AnalyticsEvent 表结构
CREATE TABLE "analytics_events" (
  "id" VARCHAR PRIMARY KEY,
  "event_name" VARCHAR NOT NULL,        -- 事件名，如 'photo_view'
  "timestamp" TIMESTAMP NOT NULL,       -- 客户端的上报时间
  "date" DATE NOT NULL,                 -- 分区字段，便于按天查询和归档
  "session_id" VARCHAR NOT NULL,        -- 会话ID，追踪用户的单次访问路径
  "user_id" VARCHAR,                    -- 登录用户的ID
  "page" VARCHAR NOT NULL,              -- 事件发生的页面
  "referrer" VARCHAR,                   -- 来源页面
  "properties" JSONB,                   -- 核心！灵活的JSON字段，存放事件的自定义属性
  "performance" JSONB,                  -- 存放Core Web Vitals等性能数据
  "server_timestamp" BIGINT,            -- 服务端收到的时间戳
  "environment" VARCHAR DEFAULT 'production'
);

// 客户端的 AnalyticsLogger (核心思想)
class AnalyticsLogger {
  private eventQueue: AnalyticsEvent[] = []; // 这是我们的“信箱”
  private flushInterval = 5000; // 每5秒去邮局“投递”一次

  trackEvent(eventName, properties) {
    this.eventQueue.push({ eventName, properties, ... });

    // 如果信攒够了10封，或者5秒钟到了，就去投递
    if (this.eventQueue.length >= 10) {
      this.flush();
    }
  }

  private async flush() {
    const eventsToSend = [...this.eventQueue];
    this.eventQueue = []; // 清空信箱

    // 异步发送，不阻塞用户操作
    // keepalive: true 保证了即使用户关闭页面，这个请求也会尽力发出去
    fetch('/api/analytics', {
      method: 'POST',
      body: JSON.stringify({ events: eventsToSend }),
      keepalive: true
    }).catch(err => {
      // 如果发送失败，把没送出去的信再放回信箱的最前面
      this.eventQueue.unshift(...eventsToSend);
    });
  }
}

// 服务端 API: /api/analytics
export async function POST(request: NextRequest) {
  try {
    const { events } = await request.json()

    // 数据验证和清洗
    const validEvents = events.map((event) => ({
      /* ... 增加IP、UA等信息 ... */
    }))

    // 关键：把写入数据库这个耗时操作，扔到后台去执行，不等待它完成
    prisma.analyticsEvent
      .createMany({
        data: validEvents,
        skipDuplicates: true,
      })
      .catch((err) => {
        // 如果写入失败，就记录到错误日志，不影响主流程
        console.error('Analytics write to DB failed:', err)
      })

    // 立即告诉客户端：“我收到信了，你继续忙你的吧”
    return NextResponse.json({ success: true })
  } catch (error) {
    return NextResponse.json({ error: 'Invalid request' }, { status: 400 })
  }
}

// 从Analytics数据中，我们可以提炼出这样的用户偏好画像
function analyzeUserPreferences(userId: string) {
  const userEvents = await prisma.analyticsEvent.findMany({
    where: {
      userId,
      eventName: { in: ['photo_view', 'photo_like', 'photo_comment'] },
    },
    // ...
  })

  return {
    viewedPhotos: extractViewedPhotos(userEvents),
    likedPhotos: extractLikedPhotos(userEvents),
    avgViewTime: calculateAverageViewTime(userEvents),
    preferredStyles: inferStylePreferences(userEvents), // 比如：更喜欢“黑白”或“街头”风格
  }
}

# 伪代码：多路召回策略
def multi_recall_strategy(user_id, collection_id):
    candidates = set()

    # 策略一：协同过滤，找与你品味相似的人喜欢过的照片
    similar_users = find_similar_users(user_id)
    for user in similar_users:
        candidates.update(get_user_liked_photos(user, collection_id))

    # 策略二：内容相似性，找与你历史喜欢的照片风格相似的照片
    user_preferences = get_user_style_preferences(user_id)
    candidates.update(find_photos_with_similar_style(user_preferences))

    # 策略三：热门召回，把近期最火的照片也加进来
    candidates.update(get_popular_photos(collection_id, time_window='7d'))

    # 策略四：探索召回，随机加入一些新照片，防止信息茧房
    candidates.update(get_recent_photos(collection_id, limit=10))

    return list(candidates)

# 伪代码：轻量级双塔精排
def lightweight_ranking_model(user_embedding, photo_embeddings):
    scores = []
    for photo_emb in photo_embeddings:
        # 通过计算用户向量和每个照片向量的“余弦相似度”
        # 我们可以得出一个分数，代表用户对这张照片的可能偏好度
        similarity_score = cosine_similarity(user_embedding, photo_emb)
        scores.append(similarity_score)

    return scores

# 伪代码：业务规则干预
def apply_business_policies(ranked_photos, user_context):
    final_list = []
    for photo, score in ranked_photos:
        # 新用户冷启动：给新用户多推荐一些热门内容
        if user_context.get('is_new_user'):
            if photo.is_popular:
                score *= 1.2

        # 多样性策略：避免同一个摄影师的照片霸屏
        if count_photographer(final_list, photo.photographer) > 3:
            score *= 0.8

        # 打散策略：避免相似风格的照片扎堆出现
        # ...

        final_list.append((photo, score))

    # 重新排序后返回
    return sorted(final_list, key=lambda x: x[1], reverse=True)

# 完整的推荐流程
def recommend_photos_for_collection(user_id: str, collection_id: str, limit: int = 20):
    """
    为collection详情页生成个性化照片排序
    """
    # 1. 获取候选照片
    candidate_photos = get_collection_photos(collection_id)

    # 2. 多路召回
    recall_results = multi_recall_strategy(user_id, collection_id, candidate_photos)

    # 3. 合并召回结果
    merged_candidates = merge_recall_results(recall_results)

    # 4. 生成用户和照片的embedding
    user_embedding = generate_user_embedding(user_id)
    photo_embeddings = [generate_photo_embedding(photo) for photo in merged_candidates]

    # 5. 精排打分
    ranking_scores = lightweight_ranking_model(user_embedding, photo_embeddings)

    # 6. 应用业务策略
    user_context = get_user_context(user_id)
    final_recommendations = apply_business_policies(
        list(zip(merged_candidates, ranking_scores)),
        user_context
    )

    return final_recommendations[:limit]