Regalos — Referencia técnica

← Volver a Regalos

Dónde vive esto

Backend

• apps/backend/graphql/types/gift.type.js — GiftCatalogItem, Gift, GiftTargetStats, SendGiftInput, SendGiftResponse; queries giftCatalog / giftStatsForTarget / giftsForTarget; mutation sendGift.
• apps/backend/graphql/resolvers/gift.resolver.js — conecta lo anterior con el manager.
• apps/backend/managers/coin-managers/gift.manager.js — catálogo, verificación de saldo, transferencia de monedas, estadísticas.
• apps/backend/database/models/Gift.js + migración 20260721000000-create-gift.js — la tabla gift.
• apps/backend/data-access-services/gift/gift.access-service.js — persistencia de filas Gift + la agregación GROUP BY gift_type detrás de getStatsForTarget.
• apps/backend/graphql/types/post.type.js / post.resolver.js — Post.giftStats: GiftTargetStats! se resuelve por publicación mediante gift.manager#getStatsForTarget, de modo que la consulta del feed obtiene los totales de regalos incluidos en cada publicación en lugar de un giftStatsForTarget aparte por cada tarjeta.

Los regalos en vivo son un sistema separado (live-stream-gift.type.js / live-stream-gift.resolver.js / LiveStreamGift.js, mutation sendLiveGift); no confundas los dos.

Frontend

• apps/frontend-nextjs/src/components/gifts/GiftPicker.tsx — el selector de stickers (carga giftCatalog, llama a sendGift).
• apps/frontend-nextjs/src/components/gifts/GiftsModal.tsx — vista de regalos recibidos por destino (giftStatsForTarget / giftsForTarget).
• Puntos de entrada: components/chat/ChatView.tsx (botón de regalo en el encabezado del chat 1:1), components/PostCard.tsx, components/stories/StoryViewer.tsx, y page-components/LiveRoomPage.tsx (variante en vivo).

GraphQL

type GiftCatalogItem { giftType: String!  label: String!  emoji: String!  coinAmount: Int! }

input SendGiftInput {
  "One of: post, story, clip, user."
  targetType: String!
  targetId: ID!
  giftType: String!
  message: String
}

type SendGiftResponse {
  success: Boolean!
  message: String        # error detail when success is false (e.g. insufficient balance)
  giftType: String
  emoji: String
  coinAmount: Int
  newBalance: Int        # sender's coin balance after the gift
}

extend type Query {
  giftCatalog: [GiftCatalogItem!]!
  giftStatsForTarget(targetType: String!, targetId: ID!): GiftTargetStats!
  giftsForTarget(targetType: String!, targetId: ID!, limit: Int, offset: Int): [Gift!]!
}
extend type Mutation {
  sendGift(input: SendGiftInput!): SendGiftResponse!
}

GiftTargetStats desglosa los regalos acumulados en un destino como byType: [GiftTargetStatItem!] (por sticker: count, totalCoins) más totalCoins / totalGifts.

Notas

• El precio es el coinAmount del catálogo; el manager verifica el saldo del remitente antes de transferir, de modo que sendGift devuelve success:false con un message en lugar de lanzar un error cuando los fondos son insuficientes.
• sendGift también crea una notificación de tipo gift para el destinatario y devuelve el saldo del remitente después del regalo (newBalance, vía coinTransactionManager#getUserBalance); ambas cosas son best-effort y nunca hacen fallar el regalo en sí.
• myGiftablePosts no forma parte de este sistema pese al nombre — vive en top-fans.type.js / top-fans.resolver.js / top-fans.manager.js y lista las publicaciones de pago de un creador ofrecidas como recompensa rewardTopFan (premium_post), usada solo por RewardFanModal.tsx. Consulta la referencia de Top Fans.