Top Fans — Referencia técnica

← Volver a Top Fans

Dónde vive esto

Backend

• apps/backend/graphql/types/top-fans.type.js — TopFan, GiftablePost, RewardTopFanInput, RewardTopFanResponse; queries topFans / myGiftablePosts / topFanIds; mutation rewardTopFan.
• apps/backend/graphql/resolvers/top-fans.resolver.js
• apps/backend/managers/*/top-fans.manager.js — combina regalos + propinas + comentarios en la clasificación y aplica las recompensas.

Frontend

• apps/frontend-nextjs/src/page-components/TopFansPage.tsx (con ruta en /top-fans) — la tabla de clasificación.
• apps/frontend-nextjs/src/components/rewards/RewardFanModal.tsx — el flujo de recompensa.

GraphQL

type TopFan {
  user: User!
  rank: Int!
  giftCoins: Int!   giftCount: Int!
  tipCoins: Int!    tipCount: Int!
  commentsCount: Int!
  totalCoins: Int!  # giftCoins + tipCoins
  score: Int!       # blended ranking (coins + comments weighted)
}

input RewardTopFanInput {
  fanUserId: ID!
  "coins | free_subscription | creator_subscription | premium_post"
  rewardType: String!
  amount: Int            # required for coins
  conversationId: ID     # required for free_subscription (group access)
  postId: ID             # required for premium_post
  message: String
}

extend type Query {
  "period: week | month | all (default month)"
  topFans(period: String, limit: Int): [TopFan!]!
  myGiftablePosts(limit: Int): [GiftablePost!]!
  topFanIds(userId: ID!, period: String, limit: Int): [ID!]!
}
extend type Mutation {
  rewardTopFan(input: RewardTopFanInput!): RewardTopFanResponse!
}

Notas

• topFans clasifica a los propios fans del creador que está viendo; topFanIds(userId) clasifica a los fans de cualquier creador para que sus seguidores puedan recibir una insignia en comentarios/feed.
• El score combina las monedas de regalos, las monedas de propinas y el número de comentarios; totalCoins es el subtotal exclusivo de monedas (regalos + propinas).
• Las recompensas reutilizan sistemas existentes: coins es una transferencia de monedas, free_subscription otorga acceso a la conversación, premium_post desbloquea una publicación de pago para el fan.