rckrdmrd 094493625c feat: Documentation and orchestration updates

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-07 05:35:34 -06:00

6.6 KiB

Raw Blame History

id	title	type	epic	status	project	version	created_date	updated_date
BA-008-PAYMENTS	BA-008: Modulo de Payments	Module Definition	BA-008	Draft	betting-analytics	1.0.0	2026-01-04	2026-01-04

BA-008: Modulo de Payments

Version: 1.0.0 Fecha: 2026-01-04 Estado: Definicion Prioridad: Alta

Descripcion General

El modulo de Payments proporciona la integracion con Stripe para gestionar suscripciones, pagos y facturacion del sistema SaaS de Betting Analytics.

Objetivos

Integrar Stripe como pasarela de pagos
Gestionar planes de suscripcion (Free, Pro, Enterprise)
Implementar checkout flow con Stripe Elements
Automatizar facturacion y cobros recurrentes
Gestionar creditos de prediccion por tenant

Planes de Suscripcion

Planes:
  free:
    nombre: "Free"
    precio: $0/mes
    limites:
      predicciones_mes: 50
      modelos_max: 1
      historico_dias: 30
      usuarios_max: 1
    features:
      - Predicciones basicas
      - 1 modelo standard
      - Soporte comunidad

  pro:
    nombre: "Pro"
    precio: $39/mes
    stripe_price_id: ba_pro_monthly
    limites:
      predicciones_mes: 500
      modelos_max: 3
      historico_dias: 365
      usuarios_max: 5
    features:
      - Todo de Free
      - Modelos avanzados
      - API access
      - Soporte email

  enterprise:
    nombre: "Enterprise"
    precio: $149/mes
    stripe_price_id: ba_enterprise_monthly
    limites:
      predicciones_mes: unlimited
      modelos_max: unlimited
      historico_dias: unlimited
      usuarios_max: unlimited
    features:
      - Todo de Pro
      - Modelos custom
      - SLA garantizado
      - Soporte dedicado

Productos Stripe

Productos:
  ba_pro_monthly:
    type: subscription
    nombre: "Betting Analytics Pro"
    precio: $39/mes
    billing_interval: monthly
    metadata:
      plan_code: pro
      predictions: 500

  ba_enterprise_monthly:
    type: subscription
    nombre: "Betting Analytics Enterprise"
    precio: $149/mes
    billing_interval: monthly
    metadata:
      plan_code: enterprise
      predictions: unlimited

  ba_predictions_100:
    type: one_time
    nombre: "Pack 100 Predicciones"
    precio: $9
    metadata:
      product_type: credits
      credits_amount: 100

Entidades del Dominio

Subscription

Entidad: Subscription
Descripcion: Suscripcion activa de un tenant
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - plan_id: UUID (FK)
  - stripe_subscription_id: string
  - stripe_customer_id: string
  - status: enum [active, past_due, canceled, incomplete, trialing]
  - current_period_start: timestamp
  - current_period_end: timestamp
  - cancel_at_period_end: boolean
  - created_at: timestamp
  - updated_at: timestamp

Relaciones:
  - N:1 con Tenant
  - N:1 con Plan
  - 1:N con Invoice

Invoice

Entidad: Invoice
Descripcion: Factura de Stripe
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - subscription_id: UUID (FK)
  - stripe_invoice_id: string
  - amount_due: decimal
  - amount_paid: decimal
  - currency: string
  - status: enum [draft, open, paid, void, uncollectible]
  - invoice_pdf_url: string
  - paid_at: timestamp
  - created_at: timestamp

PredictionCredit

Entidad: PredictionCredit
Descripcion: Balance de creditos por tenant
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK, unico)
  - credits_included: integer
  - credits_remaining: integer
  - credits_used: integer
  - credits_extra: integer
  - resets_at: timestamp
  - created_at: timestamp
  - updated_at: timestamp

Notas:
  - credits_remaining se resetea cada periodo
  - credits_extra no expiran

Webhooks Stripe

Eventos:
  - customer.subscription.created:
      accion: Crear Subscription en BD
  - customer.subscription.updated:
      accion: Actualizar status/periodo
  - customer.subscription.deleted:
      accion: Marcar como canceled
  - invoice.payment_succeeded:
      accion: Registrar pago, resetear creditos
  - invoice.payment_failed:
      accion: Marcar past_due, notificar
  - checkout.session.completed:
      accion: Activar plan o creditos

Funcionalidades

F-008.1: Gestion de Suscripciones

ID	Funcionalidad	Descripcion	Prioridad
F-008.1.1	Ver planes	Listar planes disponibles	Alta
F-008.1.2	Suscribirse	Checkout con Stripe	Alta
F-008.1.3	Cambiar plan	Upgrade/downgrade	Media
F-008.1.4	Cancelar	Cancelar al final del periodo	Media

F-008.2: Facturacion

ID	Funcionalidad	Descripcion	Prioridad
F-008.2.1	Ver facturas	Historial de facturas	Alta
F-008.2.2	Descargar PDF	Obtener factura PDF	Media
F-008.2.3	Portal billing	Redirect a Stripe portal	Alta

F-008.3: Creditos

ID	Funcionalidad	Descripcion	Prioridad
F-008.3.1	Ver balance	Creditos restantes	Alta
F-008.3.2	Comprar extra	Pack de creditos	Media
F-008.3.3	Consumir	Decrementar al predecir	Alta

API Endpoints

Base: /api/v1/billing

Endpoints:
  GET /billing/plans:
    Descripcion: Listar planes disponibles
    Response: 200 OK

  POST /billing/checkout:
    Descripcion: Crear sesion de checkout
    Body: { plan_code, success_url, cancel_url }
    Response: 200 { checkout_url }

  GET /billing/subscription:
    Descripcion: Suscripcion actual del tenant
    Response: 200 OK

  POST /billing/subscription/cancel:
    Descripcion: Cancelar al final del periodo
    Response: 200 OK

  GET /billing/invoices:
    Descripcion: Historial de facturas
    Response: 200 OK (paginado)

  GET /billing/credits:
    Descripcion: Balance de creditos
    Response: 200 OK

  POST /billing/credits/purchase:
    Descripcion: Comprar creditos extra
    Body: { pack_id }
    Response: 200 { checkout_url }

  POST /billing/webhook:
    Descripcion: Webhook de Stripe
    Headers: { stripe-signature }
    Response: 200 OK

Dependencias

Dependencias:
  - BA-007 (tenants): Multi-tenancy
  - BA-001 (auth): Autenticacion

Servicios Externos:
  - Stripe API
  - Stripe Webhooks

Catalogos:
  - shared/catalog/payments/

Criterios de Aceptacion

Usuario puede ver planes y precios
Checkout redirect a Stripe funciona
Webhooks actualizan estado correctamente
Creditos se resetean cada periodo
Portal de billing funciona
Facturas se pueden descargar

Documento generado por: NEXUS Orchestration Fecha: 2026-01-04

6.6 KiB Raw Blame History