Promociones de Publicaciones — Referencia Técnica

← Volver a Promociones de Publicaciones

Este documento fue reescrito sustancialmente dos veces. Primera pasada: la versión original describía un plan previo a la implementación (presupuestos en USD cobrados con Stripe, adminReviewPromotion, myPostPromotions, postPromotionAnalytics con ROI/desglose diario, mutaciones trackPromotionImpression/trackPromotionClick) que no coincidía con lo que realmente se construyó — la implementación real cobra en monedas y usa nombres de operación diferentes. Segunda pasada (esta): el frontend orientado al creador que se describía a continuación como faltante ya ha sido construido.

Dónde vive esto

Backend

apps/backend/graphql/types/post-promotion.type.js — esquema real, conectado a la API de GraphQL en vivo (no administrativa)
apps/backend/graphql/resolvers/post-promotion.resolver.js — resolvers para todas las operaciones no administrativas, además de las dos operaciones de administrador (adminApprovePromotion/adminRejectPromotion, restringidas mediante MANAGE_PROMOTIONS)
apps/backend/managers/post-managers/post-promotion.manager.js (~635 líneas) — lógica real (no simulada) del ciclo de vida de la campaña
apps/backend/data-access-services/post/post-promotion.access-service.js — consultas a la base de datos de PostPromotion
Clasificación del feed: apps/backend/data-access-services/post/post.access-service.js (getFeed, cerca de la línea WEIGHTS.promotion) otorga a las promociones active un impulso de peso de 0.15 en la clasificación del feed principal — este es el único lugar donde una promoción tiene un efecto real y visible en el producto más allá del propio registro de la campaña.

Frontend

Orientado al creador (apps/frontend-nextjs): construido en esta pasada.
- apps/frontend-nextjs/src/components/CreatePromotionModal.tsx — formulario de creación de campaña: nombre, objetivo, tipo de presupuesto, monto del presupuesto (monedas, con una verificación en vivo de myCoinBalance y el mínimo de 50 monedas aplicado del lado del cliente), fechas de inicio/fin. Deliberadamente no tiene campos de segmentación de audiencia, ya que esos datos son inertes en el backend (ver más abajo) — mostrar una interfaz de segmentación implicaría una capacidad que no existe.
- apps/frontend-nextjs/src/page-components/settings/MyPromotionsPage.tsx (enrutado en /settings/promotions) — lista las campañas mediante myPromotions, estadísticas por campaña mediante promotionStats, y acciones de Pausar/Reanudar/Cancelar según el estado.
- apps/frontend-nextjs/src/components/PostOptionsMenu.tsx — agrega una entrada "Promocionar publicación" / "Ver promoción" restringida al propietario, respaldada por una consulta postPromotion(postId) que está condicionada al estado open del menú (no se ejecuta de forma anticipada en cada renderizado de la tarjeta, para evitar una consulta por publicación en una página que lista muchas publicaciones propias).
- PostCard.tsx sigue renderizando por separado la insignia de solo lectura "Promocionado" (isPromoted, junto a la marca de tiempo) para cualquiera que vea una publicación con una promoción activa. PostModal.tsx no renderiza esta insignia — solo muestra la etiqueta de patrocinador/contenido de marca y el CTA, no el estado de la promoción.
Cola de revisión de administrador (apps/frontend-admin): real. apps/frontend-admin/src/app/promotions/page.tsx — una cola funcional de aprobar/rechazar, restringida mediante MANAGE_PROMOTIONS. Ver Revisión de Promociones de Publicaciones.

Checklist de implementación técnica

Modelo de campaña (tal como está implementado realmente)

Campo	Descripción
`id` / `postId`	ID de la campaña / la publicación que se está promocionando
`campaignName`	Nombre para mostrar
`objective`	Objetivo de la campaña: `reach`, `engagement`, `traffic`, `conversions` o `brand_awareness` (un simple `STRING(50)`, no un enum de GraphQL)
`budgetType`	`daily` o `lifetime`
`budgetAmount`	Monedas, no USD — se cobra por adelantado al crear (mín. 50)
`spentAmount`	Monedas gastadas hasta el momento — todavía no se decrementa por nada (no existe un modelo de costo en monedas por impresión/clic)
`targetAudience`	JSON — se almacena, nunca se aplica
`status`	`pending_review`, `active`, `paused`, `completed`, `rejected`, `cancelled` (la columna del modelo también tiene por defecto `draft`, pero `createPromotion` siempre crea las filas directamente en `pending_review` — `draft` nunca se produce en la práctica)
`startsAt` / `endsAt`	Ventana de la campaña
`impressions` / `clicks`	Se incrementan mediante `trackPromotionImpression`/`trackPromotionClick`, disparados desde `PostCard.tsx` — ver más arriba
`cpm` / `cpc` / `ctr`	Calculados por `promotionStats` a partir de lo que `impressions`/`clicks`/`spentAmount` contengan en ese momento

API de GraphQL

Crear y gestionar una campaña

mutation CreatePostPromotion($input: CreatePostPromotionInput!) {
  createPostPromotion(input: $input) { id campaignName status startsAt endsAt budgetAmount }
}

mutation UpdatePostPromotion($id: ID!, $input: UpdatePostPromotionInput!) {
  updatePostPromotion(id: $id, input: $input) { id status }
}

# pause/resume/cancel all return the updated PostPromotion, not a success wrapper
mutation PausePostPromotion($id: ID!) { pausePostPromotion(id: $id) { id status } }
mutation ResumePostPromotion($id: ID!) { resumePostPromotion(id: $id) { id status } }

# Ends the campaign and refunds unspent budget in coins
mutation CancelPostPromotion($id: ID!) { cancelPostPromotion(id: $id) { id status } }

# Fired from PostCard.tsx for active sponsored posts - soft no-ops, return false rather than throwing
mutation TrackPromotionImpression($promotionId: ID!) { trackPromotionImpression(promotionId: $promotionId) }
mutation TrackPromotionClick($promotionId: ID!) { trackPromotionClick(promotionId: $promotionId) }

Leer campañas y estadísticas

query MyPromotions($status: String) {
  myPromotions(status: $status) { id campaignName status budgetAmount spentAmount startsAt endsAt }
}

query PostPromotion($postId: ID!) { postPromotion(postId: $postId) { id status } }
query PromotionById($id: ID!) { promotionById(id: $id) { id campaignName status } }

query PromotionStats($id: ID!) {
  promotionStats(id: $id) { impressions clicks cpm cpc ctr spentAmount daysRemaining }
}

# Real estimate now, derived from the caller's follower count/engagement/budget -
# still ignores location/demographics/interests, since targetAudience is inert
query EstimateReach($targetAudience: JSON) {
  estimatePromotionReach(targetAudience: $targetAudience) {
    minReach maxReach estimatedReach estimatedImpressions estimatedClicks estimatedCtr
  }
}

Revisión de administrador

query AdminGetPendingPromotions { adminGetPendingPromotions { id campaignName objective budgetType budgetAmount user { username } } }

# Both return the updated PostPromotion, not a success wrapper
mutation AdminApprovePromotion($id: ID!) { adminApprovePromotion(id: $id) { id status reviewedAt } }
mutation AdminRejectPromotion($id: ID!, $reason: String) { adminRejectPromotion(id: $id, reason: $reason) { id status rejectionReason reviewedAt } }

Ver Revisión de Promociones de Publicaciones para el lado del panel de administración.

Dónde vive esto​

Checklist de implementación técnica​

Modelo de campaña (tal como está implementado realmente)​

API de GraphQL​

Crear y gestionar una campaña​

Leer campañas y estadísticas​

Revisión de administrador​