michangarrito/docs/01-epicas/MCH-029-infraestructura-saas.md

id	type	title	code	status	phase	priority	created_at	updated_at	simco_version	dependencies
EPIC-MCH-029	Epic	MCH-029: Infraestructura SaaS Avanzada	MCH-029	Planificado	7	P0	2026-01-10	2026-01-10	4.0.1	blocks depends_on MCH-030 MCH-032 MCH-033

MCH-029: Infraestructura SaaS Avanzada

Metadata

• Codigo: MCH-029
• Fase: 7 - Expansion
• Prioridad: P0 (Critica)
• Estado: Planificado
• Story Points: 24
• Sprint Objetivo: Sprint 6-7

Descripcion

Implementar infraestructura SaaS empresarial que incluye sistema de Email Multi-proveedor, Storage Abstracto en la nube, Redis como cache/queue, Webhooks Outbound con reintentos y Rate Limiting por plan. Esta epica es la base para las capacidades SaaS avanzadas.

Objetivos

1. Establecer sistema de email multi-proveedor con fallback
2. Implementar storage abstracto compatible con S3/R2/MinIO
3. Configurar Redis para cache y colas
4. Habilitar webhooks outbound con estrategia de reintentos
5. Implementar rate limiting por plan de suscripcion

Alcance

Incluido

• Email transaccional con SendGrid, SES y SMTP
• Storage cloud con URLs firmadas
• Redis cache con TTL configurable
• BullMQ para procesamiento en background
• Rate limiting con token bucket
• Webhooks con firma HMAC-SHA256

Excluido

• Push notifications (ver MCH-034)
• Email marketing masivo
• CDN para assets estaticos

Arquitectura

                     ┌─────────────────────────────────────┐
                     │        MCH-029: Infraestructura     │
                     └─────────────────────────────────────┘
                                       │
        ┌──────────────┬──────────────┼──────────────┬──────────────┐
        ▼              ▼              ▼              ▼              ▼
  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
  │  Email   │  │  Storage │  │   Redis  │  │ Webhooks │  │   Rate   │
  │ Provider │  │ Provider │  │  Cache   │  │ Outbound │  │ Limiting │
  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘
       │             │             │             │             │
  ┌────┴────┐  ┌────┴────┐        │        ┌────┴────┐        │
  │SendGrid │  │   S3    │        │        │ BullMQ  │        │
  │   SES   │  │   R2    │        │        │  Queue  │        │
  │  SMTP   │  │  MinIO  │        │        │         │        │
  └─────────┘  └─────────┘        │        └─────────┘        │
                                  │                            │
                            ┌─────┴────────────────────────────┘
                            │          Redis Server            │
                            └──────────────────────────────────┘

Entregables

Entregable	Estado	Sprint	Ubicacion
Email module con multi-provider	Planificado	6	apps/backend/src/modules/email/
Storage module abstracto	Planificado	6	apps/backend/src/modules/storage/
Redis cache/queue config	Planificado	6	apps/backend/src/modules/redis/
Webhooks module	Planificado	7	apps/backend/src/modules/webhooks/
Rate limiting guard	Planificado	7	apps/backend/src/common/guards/
DDL storage schema	Planificado	6	database/schemas/12-storage.sql
DDL webhooks schema	Planificado	7	database/schemas/15-webhooks.sql

Dependencias

Depende de

• Ninguna (epica base de infraestructura)

Bloquea a

• MCH-030 (Auth Social) - requiere email para verificacion
• MCH-032 (Feature Flags) - requiere Redis para cache
• MCH-033 (Onboarding) - requiere infraestructura completa

---

Historias de Usuario

MCH-US-101: Email Multi-proveedor

Como administrador del sistema Quiero enviar emails transaccionales via multiples proveedores Para garantizar entrega y tener fallback

Story Points: 5

Criterios de Aceptacion:

• [CA-101-1] Soporta SendGrid como proveedor principal
• [CA-101-2] Soporta AWS SES como fallback
• [CA-101-3] Soporta SMTP generico como ultimo recurso
• [CA-101-4] Templates reutilizables con variables Handlebars
• [CA-101-5] Tracking de entrega (opens, clicks si proveedor soporta)
• [CA-101-6] Rate limiting por tenant (max emails/hora)

Tareas:

ID	Tarea	Tipo	SP
MCH-TT-101-01	DDL tabla email_templates	DDL	0.5
MCH-TT-101-02	DDL tabla email_logs	DDL	0.5
MCH-TT-101-03	Servicio EmailProviderFactory	Backend	0.5
MCH-TT-101-04	Implementar SendGridProvider	Backend	1
MCH-TT-101-05	Implementar SESProvider	Backend	1
MCH-TT-101-06	Implementar SMTPProvider	Backend	0.5
MCH-TT-101-07	Controlador EmailController	Backend	0.5
MCH-TT-101-08	Tests unitarios	Test	0.5
MCH-TT-101-09	Documentacion INT-010	Docs	0

---

MCH-US-102: Storage Abstracto

Como usuario Quiero subir archivos (imagenes, facturas) a la nube Para tener respaldo seguro y acceso desde cualquier dispositivo

Story Points: 8

Criterios de Aceptacion:

• [CA-102-1] Soporta AWS S3 como proveedor principal
• [CA-102-2] Soporta Cloudflare R2 como alternativa economica
• [CA-102-3] Soporta MinIO para desarrollo local
• [CA-102-4] Limites de almacenamiento por plan (Basic: 1GB, Pro: 10GB, Enterprise: 100GB)
• [CA-102-5] Organizacion de archivos en carpetas virtuales
• [CA-102-6] URLs firmadas con expiracion configurable
• [CA-102-7] Metadata de archivos (size, mime_type, upload_date)
• [CA-102-8] Validacion de tipos MIME permitidos

Tareas:

ID	Tarea	Tipo	SP
MCH-TT-102-01	DDL schema storage (files, folders, usage)	DDL	1
MCH-TT-102-02	Servicio StorageProviderFactory	Backend	0.5
MCH-TT-102-03	Implementar S3Provider	Backend	1.5
MCH-TT-102-04	Implementar R2Provider	Backend	1
MCH-TT-102-05	Implementar MinIOProvider	Backend	0.5
MCH-TT-102-06	Controlador StorageController	Backend	1
MCH-TT-102-07	Middleware limite por plan	Backend	0.5
MCH-TT-102-08	Generacion URLs firmadas	Backend	0.5
MCH-TT-102-09	Tests unitarios e integracion	Test	1
MCH-TT-102-10	Documentacion INT-011	Docs	0.5

---

MCH-US-103: Redis Cache y Queue

Como sistema Quiero utilizar Redis como cache y queue Para mejorar rendimiento y procesar tareas en background

Story Points: 3

Criterios de Aceptacion:

• [CA-103-1] Cache de sesiones JWT con TTL
• [CA-103-2] Cache de configuracion de tenant
• [CA-103-3] Queue para emails, webhooks, notificaciones via BullMQ
• [CA-103-4] Health check endpoint de Redis
• [CA-103-5] Metricas de uso (hits/misses, queue length)

Tareas:

ID	Tarea	Tipo	SP
MCH-TT-103-01	Configuracion Redis module	Backend	0.5
MCH-TT-103-02	Cache service con TTL	Backend	0.5
MCH-TT-103-03	BullMQ integration	Backend	0.5
MCH-TT-103-04	Queue processors base	Backend	0.5
MCH-TT-103-05	Health check endpoint	Backend	0.25
MCH-TT-103-06	Tests	Test	0.5
MCH-TT-103-07	Documentacion INT-013	Docs	0.25

---

MCH-US-104: Webhooks Outbound

Como administrador de tenant Quiero configurar webhooks para recibir notificaciones de eventos Para integrar con sistemas externos

Story Points: 5

Criterios de Aceptacion:

• [CA-104-1] CRUD de endpoints webhook por tenant
• [CA-104-2] Seleccion de eventos a suscribirse (order.created, payment.completed, etc)
• [CA-104-3] Firma de payloads con HMAC-SHA256
• [CA-104-4] Reintentos con exponential backoff (1s, 2s, 4s, 8s, 16s)
• [CA-104-5] Logs de entregas con response status

Tareas:

ID	Tarea	Tipo	SP
MCH-TT-104-01	DDL schema webhooks (endpoints, deliveries)	DDL	0.5
MCH-TT-104-02	Servicio WebhookService	Backend	1
MCH-TT-104-03	Job processor con BullMQ	Backend	1
MCH-TT-104-04	Firma HMAC de payloads	Backend	0.5
MCH-TT-104-05	Controlador WebhooksController	Backend	0.5
MCH-TT-104-06	UI en portal admin	Frontend	0.5
MCH-TT-104-07	Tests	Test	0.5
MCH-TT-104-08	Documentacion INT-014	Docs	0.5

---

MCH-US-112: Rate Limiting por Plan

Como sistema Quiero limitar las solicitudes API segun el plan del tenant Para garantizar uso justo y proteger la infraestructura

Story Points: 3

Criterios de Aceptacion:

• [CA-112-1] Limite de requests/minuto configurable por plan
• [CA-112-2] Limite de requests/dia configurable por plan
• [CA-112-3] Headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
• [CA-112-4] Respuesta 429 Too Many Requests con Retry-After
• [CA-112-5] Bypass para webhooks internos y health checks

Tareas:

ID	Tarea	Tipo	SP
MCH-TT-112-01	Implementar middleware RateLimitGuard	Backend	0.5
MCH-TT-112-02	Configuracion limites en plans	Backend	0.5
MCH-TT-112-03	Almacenamiento contadores en Redis	Backend	0.5
MCH-TT-112-04	Headers de respuesta	Backend	0.25
MCH-TT-112-05	Tests	Test	0.5
MCH-TT-112-06	Documentar en ADR-0009	Docs	0.25

---

Resumen de Story Points

Historia	SP	Sprint
MCH-US-101: Email Multi-proveedor	5	6
MCH-US-102: Storage Abstracto	8	6
MCH-US-103: Redis Cache y Queue	3	6
MCH-US-104: Webhooks Outbound	5	7
MCH-US-112: Rate Limiting	3	7
TOTAL	24	6-7

---

Criterios de Aceptacion de Epica

• Email enviado exitosamente con cada proveedor
• Archivos subidos a S3 con URL firmada funcional
• Redis cache reduce latencia en >50%
• Webhook entregado con reintentos exitosos
• Rate limiting bloquea requests excedentes
• Cobertura de tests >80%
• Documentacion de integraciones completa

Notas Tecnicas

• Redis: Puerto 6379, DB 0 para cache, DB 1 para queues
• S3 Region: us-east-1 (default)
• R2 Region: auto
• Email Rate: Max 1000/tenant/hora en plan Pro

Integraciones Relacionadas

• INT-010: Email Providers
• INT-011: Storage Cloud
• INT-013: Redis Cache
• INT-014: Webhooks Outbound

ADRs Relacionados

• ADR-0006: Storage Abstraction
• ADR-0007: Webhook Retry Strategy
• ADR-0009: Rate Limiting Strategy
• ADR-0011: Email Multi-provider

---

Especificaciones Tecnicas Detalladas

Email: Templates Incluidos (Ref: SAAS-013)

Key	Descripcion
welcome	Email de bienvenida
password_reset	Reset de contrasena
invitation	Invitacion a tenant
notification	Notificacion generica
order_confirmation	Confirmacion de pedido
payment_reminder	Recordatorio de pago (fiados)

Storage: Flujo de Upload (Ref: SAAS-011)

1. Cliente solicita upload URL
   POST /storage/upload-url
   Body: { filename, mimeType, sizeBytes, folder?, visibility? }

2. Backend valida:
   - Tipo MIME permitido
   - Extension no bloqueada
   - Tamano dentro de limite
   - Espacio disponible

3. Backend genera presigned URL (AWS SDK v3)
   - Expira en 15 minutos
   - Limite de tamano

4. Cliente sube directo a S3/R2
   PUT [presigned-url]

5. Cliente confirma
   POST /storage/confirm
   Body: { uploadId, metadata? }

6. Backend crea registro en storage.files

Storage: Limites por Plan

Plan	Storage	Max Archivo
Changarrito	500 MB	10 MB
Tiendita	2 GB	50 MB
Tienda Pro	10 GB	100 MB

Webhooks: Eventos Disponibles (Ref: SAAS-010)

Evento	Descripcion	Payload
sale.created	Venta registrada	Sale object
sale.cancelled	Venta cancelada	{ saleId }
customer.created	Cliente creado	Customer
fiado.created	Fiado registrado	Fiado
fiado.payment	Abono a fiado	FiadoPayment
inventory.low	Stock bajo	{ productId, current, min }
order.created	Pedido WhatsApp	Order
order.status_changed	Cambio estado pedido	Order + prevStatus
subscription.created	Nueva suscripcion	Subscription
subscription.cancelled	Suscripcion cancelada	Subscription

Webhooks: Logica de Reintentos

Intento 1: Inmediato
Intento 2: +1 minuto
Intento 3: +5 minutos
Intento 4: +30 minutos
Intento 5: +2 horas
Intento 6: +6 horas
Despues: Marcar como fallido

Webhooks: Headers Enviados

X-Webhook-Signature: t=1704067200000,v1=abc123...
X-Webhook-Id: <webhook-uuid>
X-Webhook-Event: sale.created
X-Webhook-Timestamp: 1704067200000
X-Webhook-Delivery: <delivery-uuid>

Webhooks: Limites por Plan

Plan	Webhooks	Eventos/mes
Changarrito	2	5,000
Tiendita	5	20,000
Tienda Pro	10	100,000

Rate Limiting: Limites por Plan

Plan	Requests/min	Requests/dia
Changarrito	60	10,000
Tiendita	120	50,000
Tienda Pro	300	200,000

---

Referencia Template-SaaS

Esta epica esta alineada con los siguientes modulos de template-saas:

Modulo SAAS	Version	Elementos Integrados
SAAS-010 Webhooks	1.0.0	Eventos, reintentos, firma HMAC
SAAS-011 Storage	1.0.0	Presigned URLs, limites, providers
SAAS-013 Email	1.0.0	Multi-provider, templates

Ver documentacion fuente en projects/template-saas/docs/01-modulos/

---

Ultima actualizacion: 2026-01-13 Autor: Architecture Team Alineacion: template-saas v1.0.0