rckrdmrd
50a821a415
- HERENCIA-SIMCO.md actualizado con directivas v3.7 y v3.8 - Actualizaciones de configuracion Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
805 lines
32 KiB
Markdown
805 lines
32 KiB
Markdown
---
|
|
id: "VIS-003"
|
|
title: "Especificacion Plataforma SaaS"
|
|
type: "Specification"
|
|
status: "Published"
|
|
priority: "P0"
|
|
version: "1.0.0"
|
|
created_date: "2026-01-07"
|
|
updated_date: "2026-01-10"
|
|
---
|
|
|
|
# Plantilla de Plataforma SaaS Multi-Tenant: Modulos y Funcionalidades Requeridas
|
|
|
|
**Proyecto:** template-saas
|
|
**Version:** 1.0.0
|
|
**Tipo:** Especificacion de Alcances
|
|
**Estado:** Documento de Referencia
|
|
|
|
---
|
|
|
|
## Tabla de Contenidos
|
|
|
|
1. [Arquitectura Multi-Tenant y Separacion de Datos](#1-arquitectura-multi-tenant-y-separacion-de-datos)
|
|
2. [Seguridad, Autenticacion y Gestion de Usuarios](#2-seguridad-autenticacion-y-gestion-de-usuarios)
|
|
3. [Portal de Usuario Final](#3-portal-de-usuario-final)
|
|
4. [Portal de Administrador del Cliente](#4-portal-de-administrador-del-cliente)
|
|
5. [Portal de Superadministrador](#5-portal-de-superadministrador)
|
|
6. [Gestion de Suscripciones y Pagos](#6-gestion-de-suscripciones-y-pagos)
|
|
7. [Integracion de IA y Asistentes Virtuales](#7-integracion-de-ia-y-asistentes-virtuales)
|
|
8. [Integraciones Adicionales y API Publica](#8-integraciones-adicionales-y-api-publica)
|
|
9. [Flujo de Trabajo General](#9-flujo-de-trabajo-general)
|
|
10. [Conclusiones](#10-conclusiones)
|
|
|
|
---
|
|
|
|
## 1. Arquitectura Multi-Tenant y Separacion de Datos
|
|
|
|
Un SaaS multi-tenant es una unica aplicacion que sirve a multiples clientes ("tenants"), manteniendo aislados los datos de cada uno. Esto significa tener una sola base de codigo y estructura de datos comun, pero con mecanismos para separar y aislar los datos de cada organizacion de forma transparente para el cliente.
|
|
|
|
En la practica, existen dos enfoques principales para almacenar datos:
|
|
|
|
### 1.1 Base de datos unica con separacion por tenant
|
|
|
|
Es la opcion mas sencilla de escalar cuando se espera tener muchos clientes pequenos o medianos (por ejemplo, ~1000 tenants). Se anade un identificador de tenant en las tablas para asegurar el aislamiento logico de los datos.
|
|
|
|
**Ventajas:**
|
|
- Las migraciones de esquema se aplican una sola vez para todos los clientes
|
|
- Facilita el mantenimiento
|
|
- Menor overhead operativo
|
|
|
|
**Consideraciones:**
|
|
- Requiere rigor en la capa de acceso a datos para evitar filtraciones de informacion entre tenants
|
|
- Se recomienda usar filtros globales o Row-Level Security (RLS) en el ORM o base de datos
|
|
- Necesita una robusta bateria de tests que garanticen que ninguna consulta exponga datos erroneos
|
|
|
|
### 1.2 Base de datos por tenant (o esquemas separados)
|
|
|
|
Ofrece un aislamiento de datos mas fuerte (incluso a nivel fisico en caso de BD separadas), lo cual puede ser necesario para ciertos clientes de gran tamano o requerimientos regulatorios estrictos.
|
|
|
|
**Ventajas:**
|
|
- Cada tenant tiene su propio conjunto de tablas
|
|
- Evita por diseno la mezcla de datos
|
|
- Cumple requerimientos regulatorios estrictos
|
|
|
|
**Consideraciones:**
|
|
- Con cientos o miles de clientes esta estrategia complica la operacion
|
|
- Las actualizaciones de esquema deben replicarse en todas las bases
|
|
- Exige automatizacion solida para aplicar migraciones y monitorear fallos
|
|
|
|
### 1.3 Enfoque Hibrido (Recomendado)
|
|
|
|
Una aproximacion hibrida puede combinar ambos enfoques:
|
|
- Mantener a la mayoria de clientes en un pool compartido
|
|
- Aislar en una BD propia a aquellos que superen cierto umbral de datos o requieran separacion dedicada
|
|
|
|
### 1.4 Requisitos de Aislamiento
|
|
|
|
La plataforma debe asegurarse de que los datos, usuarios y configuraciones de cada tenant permanezcan aislados entre si. Esto implica:
|
|
|
|
1. **Identificacion del tenant**: La capa de seguridad debe identificar siempre el tenant del usuario en cada solicitud (por ejemplo, mediante el subdominio de la URL de cliente o un identificador en el token de autenticacion)
|
|
2. **Carga de datos correcta**: Cargar solo los datos correspondientes al tenant identificado
|
|
3. **Escalabilidad**: Una arquitectura multi-tenant bien disenada permitira aprovisionar nuevos clientes de forma automatizada y rapida (idealmente self-service) sin necesidad de despliegues adicionales
|
|
|
|
### 1.5 Onboarding de Nuevos Tenants
|
|
|
|
Se puede implementar un onboarding de nuevos tenants donde, tras el registro y pago inicial:
|
|
- Se cree automaticamente su espacio de datos (ya sea un nuevo esquema o entradas en tablas compartidas)
|
|
- Se creen sus usuarios iniciales
|
|
- Se apliquen configuraciones por defecto
|
|
- Se asignen los recursos necesarios sin intervencion manual
|
|
|
|
---
|
|
|
|
## 2. Seguridad, Autenticacion y Gestion de Usuarios
|
|
|
|
Todo SaaS debe incluir un modulo robusto de autenticacion de usuarios.
|
|
|
|
### 2.1 Autenticacion
|
|
|
|
**Requisitos basicos:**
|
|
- Soporte para registro/inicio de sesion seguro
|
|
- Recuperacion de contrasena
|
|
- Verificacion de correo electronico
|
|
- Autenticacion basada en tokens JWT para sesiones seguras y escalables (sin estado en el servidor)
|
|
|
|
**Opciones avanzadas:**
|
|
- OAuth2 u OpenID Connect para soportar Single Sign-On (SSO) corporativo
|
|
- Logins sociales (Google, Facebook, etc.)
|
|
- Metodos sin contrasena (enlaces magicos)
|
|
- Autenticacion multifactor (MFA) para mayor seguridad
|
|
- SSO con proveedores como Okta o Azure AD para clientes empresariales
|
|
|
|
### 2.2 Gestion de Usuarios Multi-Tenant
|
|
|
|
La gestion de usuarios debe contemplar que cada tenant administrara a sus propios usuarios internos:
|
|
|
|
1. **Base de usuarios global**: Aunque la plataforma tenga una base de usuarios global, cada cuenta de cliente (tenant) tendra usuarios asociados unicamente a ese tenant
|
|
2. **Vinculacion al autenticarse**: El sistema debe vincular al usuario con su organizacion/tenant correspondiente (almacenando tenant_id en el perfil del usuario o en sus claims JWT)
|
|
3. **Acceso multi-tenant**: Permitir que un mismo individuo pueda tener acceso a multiples tenants (por ejemplo, un consultor que use varias empresas en la plataforma)
|
|
4. **Implementacion**: Mediante seleccion de organizacion tras el login o mediante URLs/subdominios distintos para cada cliente
|
|
|
|
### 2.3 Control de Acceso por Roles (RBAC)
|
|
|
|
La plataforma debe implementar control de acceso por roles para garantizar que cada usuario solo acceda a las funciones y datos permitidos segun su perfil.
|
|
|
|
**Niveles de roles:**
|
|
- **Roles por tenant**: Cada tenant puede tener roles predefinidos (ej.: Admin, Editor, Lectura) o incluso la capacidad de definir roles personalizados con distintos permisos
|
|
- **Roles globales**: Al nivel de superadministrador (plataforma), roles globales como superadmin u operadores de soporte
|
|
- **Modelo multi-tenant**: Los roles y permisos de un usuario pueden variar de un tenant a otro
|
|
|
|
**Cobertura de permisos:**
|
|
- Acceso a modulos o acciones especificas
|
|
- Ejemplo: Un rol Editor puede crear y editar ciertos registros, pero no gestionar usuarios ni ver facturacion
|
|
|
|
### 2.4 Registro y Verificacion
|
|
|
|
Cuando un nuevo cliente se registra para usar el SaaS (onboarding de un tenant):
|
|
1. Se designa un usuario administrador inicial
|
|
2. Se recolectan datos del cliente (nombre de la organizacion, informacion de pago)
|
|
3. Se recolectan datos del usuario admin (nombre, email)
|
|
4. Se envia un correo de verificacion para confirmar el email antes de activar la cuenta
|
|
5. Al invitar nuevos usuarios, estos reciben correos de invitacion con links de activacion
|
|
|
|
**Requisito**: Integracion de un servicio de correo saliente (por ejemplo SendGrid, AWS SES) para flujos de verificacion, invitaciones, restablecimiento de contrasena, notificaciones, etc.
|
|
|
|
### 2.5 Caracteristicas Adicionales de Seguridad
|
|
|
|
- Politicas de contrasena robustas (longitud minima, complejidad)
|
|
- Proteccion contra ataques de fuerza bruta (limitacion de intentos o CAPTCHA)
|
|
- Registro de actividad de usuarios
|
|
- Modulo de auditoria para registrar eventos importantes (login, cambios de configuracion, operaciones sensibles) asociados a cada usuario y tenant
|
|
- Para clientes empresariales: integracion opciones de provision de usuarios automatica (SCIM) o sincronizacion con directorios corporativos
|
|
|
|
---
|
|
|
|
## 3. Portal de Usuario Final
|
|
|
|
Este portal es la interfaz que utilizan los usuarios finales de cada cliente (es decir, los empleados o usuarios que el cliente tenant ha dado de alta en su cuenta). Suele ser la aplicacion principal donde se consumen las funcionalidades del SaaS ofrecido.
|
|
|
|
### 3.1 Requisitos Generales
|
|
|
|
- Diseno multi-tenant: mostrar unicamente datos de la organizacion actual
|
|
- Aplicar restricciones de permisos segun el rol del usuario
|
|
- Respetar la segmentacion por tenant en cada peticion del frontend al backend
|
|
|
|
### 3.2 Modulos/Paginas Principales
|
|
|
|
#### 3.2.1 Inicio / Dashboard
|
|
|
|
Una pagina principal que ofrece al usuario una vista general, resumenes o KPIs relevantes tras iniciar sesion.
|
|
|
|
**Consideraciones:**
|
|
- Debe considerar el contexto del tenant y del usuario
|
|
- Si el usuario tiene ciertos privilegios puede ver mas datos resumidos de la organizacion
|
|
- Un usuario basico ve solo su propia actividad
|
|
|
|
#### 3.2.2 Perfil de Usuario
|
|
|
|
Seccion donde el usuario puede:
|
|
- Ver y editar su propia informacion personal (nombre, foto, email, etc.)
|
|
- Configurar preferencias
|
|
- Cambiar su contrasena
|
|
- Configurar 2FA si se ofrece
|
|
- Administrar tokens de API personales si corresponde
|
|
- Gestion de notificaciones (suscribirse o darse de baja de ciertos correos)
|
|
|
|
#### 3.2.3 Funciones Core de la Aplicacion
|
|
|
|
La plantilla debe prever espacios para los modulos funcionales propios del servicio que brinda el SaaS:
|
|
|
|
**Gestion de Entidades Basicas:**
|
|
- Paginas de listado, creacion/edicion y visualizacion de detalles
|
|
- Siempre filtrando por los datos del tenant actual
|
|
|
|
**Busquedas y Filtros:**
|
|
- Herramientas para que el usuario busque dentro de sus datos (solo de su empresa) de forma eficiente
|
|
|
|
**Exportaciones/Importaciones:**
|
|
- Funcionalidades para extraer datos (p.ej. CSV, PDF) o cargarlos
|
|
|
|
**Reportes o Visualizaciones:**
|
|
- Modulo generico de informes donde se muestren graficos o tablas de resumen de datos del tenant
|
|
|
|
#### 3.2.4 Soporte y Ayuda Integrada
|
|
|
|
- Seccion de Ayuda/FAQ con documentacion de uso del software, posiblemente contextual por pantalla
|
|
- Sistema de tickets de soporte o chat
|
|
- Integracion con un asistente virtual (IA) que conteste preguntas frecuentes o ayude en la navegacion
|
|
- Datos de contacto o formulario para soporte humano en caso necesario
|
|
|
|
#### 3.2.5 Notificaciones
|
|
|
|
- Centro de notificaciones dentro del portal (icono de campana con dropdown de mensajes)
|
|
- Notificaciones via correo electronico segun la importancia
|
|
- Estructura para manejar notificaciones generadas por distintas acciones del sistema
|
|
|
|
---
|
|
|
|
## 4. Portal de Administrador del Cliente
|
|
|
|
Este portal lo usan los administradores de cada empresa cliente, es decir, quienes contrataron el SaaS y necesitan configurar su espacio y gestionar el uso dentro de su organizacion.
|
|
|
|
### 4.1 Modulos/Paginas Principales
|
|
|
|
#### 4.1.1 Administracion de Usuarios del Tenant
|
|
|
|
El administrador del cliente puede:
|
|
- Dar de alta nuevos usuarios, invitandolos por email
|
|
- Gestionar usuarios existentes (crear, editar, eliminar/desactivar)
|
|
- Asignar roles o permisos a cada usuario
|
|
- Reenvio de invitaciones pendientes
|
|
- Restablecimiento de contrasenas para usuarios (enviando email de reset)
|
|
|
|
#### 4.1.2 Gestion de Roles y Permisos (Opcional Avanzado)
|
|
|
|
Si la plataforma soporta roles personalizados por cliente:
|
|
- Seccion para definir roles nuevos
|
|
- Seleccionar que permisos o modulos habilita cada rol (dentro de los permitidos por la plataforma)
|
|
|
|
#### 4.1.3 Configuracion de la Organizacion
|
|
|
|
Modulo donde el cliente admin configura datos generales de su cuenta/empresa:
|
|
|
|
**Perfil de la organizacion:**
|
|
- Nombre de la empresa
|
|
- Logo (para cierto grado de white-label basico)
|
|
- Direccion, zona horaria, etc.
|
|
|
|
**Preferencias globales del tenant:**
|
|
- Configuracion regional (idioma, formato de fecha)
|
|
- Politicas internas (requisitos de contrasena o SSO si conectan con un IdP propio)
|
|
- Ajustes especificos del producto (activar/desactivar caracteristicas para sus usuarios)
|
|
|
|
#### 4.1.4 Facturacion y Suscripcion
|
|
|
|
Seccion fundamental donde el cliente admin puede ver y administrar su plan de suscripcion:
|
|
|
|
**Informacion disponible:**
|
|
- Plan actual
|
|
- Historial de pagos/facturas
|
|
- Proxima fecha de renovacion
|
|
- Limites de uso (numero de usuarios maximos o cuota de datos segun el plan)
|
|
|
|
**Acciones disponibles (integracion con Stripe):**
|
|
- Actualizar metodo de pago: agregar o cambiar la tarjeta de credito u otro metodo
|
|
- Cambiar de plan: upgrading o downgrading entre planes, calculando prorrateos
|
|
- Cancelar suscripcion: solicitar la cancelacion (efectiva al fin del periodo pagado)
|
|
- Ver facturas: enlaces o PDFs de recibos de Stripe
|
|
|
|
#### 4.1.5 Panel de Control (Dashboard del Admin)
|
|
|
|
Similar al dashboard de usuario, pero enfocado en informacion global de la organizacion:
|
|
- Cuantos usuarios activos tienen
|
|
- Uso del servicio (numero de registros/proyectos creados este mes, etc.)
|
|
- Estado de la suscripcion
|
|
- Alertas importantes ("tarjeta proxima a expirar", "se alcanzo el 90% de la cuota de almacenamiento")
|
|
|
|
#### 4.1.6 Integraciones y API
|
|
|
|
Si la plataforma ofrece integraciones con terceros o API publica:
|
|
|
|
**API Keys:**
|
|
- Generar y revocar claves API para que su organizacion pueda usar la API publica del SaaS
|
|
- Cada tenant debe tener sus credenciales segregadas
|
|
|
|
**Webhooks:**
|
|
- Configurar endpoints de su sistema para recibir notificaciones de eventos
|
|
|
|
**Integraciones OAuth externas:**
|
|
- Conectar con Slack, Zapier, WhatsApp Business u otros servicios
|
|
|
|
**Single Sign-On opcional:**
|
|
- Para clientes empresariales: configurar integracion SSO de su dominio
|
|
|
|
#### 4.1.7 Soporte y Centro de Ayuda
|
|
|
|
- Centro de ayuda con documentacion tecnica o administrativa
|
|
- Canal de soporte directo con el proveedor SaaS
|
|
- Formulario para enviar un ticket, chat en vivo, o chatbot LLM
|
|
|
|
### 4.2 Caracteristica de Impersonacion
|
|
|
|
El admin puede "ver como" un usuario X sin tener que pedirle su contrasena:
|
|
- Util para reproducir problemas reportados
|
|
- Debe estar restringida a roles admin
|
|
- Debe ser auditada (registrar quien impersono a quien y cuando)
|
|
|
|
### 4.3 Objetivo: Self-Service Completo
|
|
|
|
Se busca que el cliente pueda:
|
|
1. Registrarse y crear su tenant sin intervencion humana (auto-provision)
|
|
2. Gestionar usuarios y recursos el mismo
|
|
3. Introducir su tarjeta y manejar sus pagos dentro del portal
|
|
4. Consumir documentacion y soporte preferentemente de forma autonoma
|
|
|
|
---
|
|
|
|
## 5. Portal de Superadministrador
|
|
|
|
Este es el portal usado por el dueno u operador de la plataforma SaaS. Desde aqui se tiene vision y control global de todo el sistema multi-tenant. Es una herramienta interna fundamental para operar el negocio SaaS.
|
|
|
|
### 5.1 Gestion de Tenants (Clientes)
|
|
|
|
Un modulo para ver y administrar todas las cuentas de clientes que han contratado el SaaS.
|
|
|
|
**Vista de tenants:**
|
|
- Lista de tenants activos
|
|
- Informacion: nombre de empresa, plan actual, estado (activo, en prueba, suspendido)
|
|
|
|
**Detalle de cada tenant:**
|
|
- Usuarios registrados
|
|
- Uso de almacenamiento u otros recursos
|
|
- Fecha de alta
|
|
- Ultimo pago
|
|
|
|
**Acciones administrativas:**
|
|
- Suspender o desactivar una cuenta (por incumplimiento de pago o abuso)
|
|
- Cambiar de plan manualmente
|
|
- Otorgar creditos/promociones
|
|
- Restablecer alguna configuracion
|
|
- Eliminar definitivamente un tenant (con backup previo de sus datos)
|
|
- Crear manualmente un nuevo tenant (para ventas enterprise)
|
|
|
|
### 5.2 Administracion Global de Usuarios
|
|
|
|
**Usuarios a nivel plataforma:**
|
|
- Gestionar usuarios internos de la plataforma (operadores de soporte, cuentas de administrador que no pertenecen a un tenant especifico)
|
|
|
|
**Busqueda global:**
|
|
- Listar todos los usuarios registrados en todos los tenants
|
|
- Busquedas globales (por email) para soporte
|
|
|
|
### 5.3 Planes, Billing y Finanzas
|
|
|
|
**Gestion de planes:**
|
|
- Definir y gestionar los planes de suscripcion disponibles (nombre, precios, limites)
|
|
- Crear planes personalizados o descuentos para clientes especificos
|
|
|
|
**Estado de pagos:**
|
|
- Total de ingresos mensuales
|
|
- Metricas de MRR (Monthly Recurring Revenue)
|
|
- Tasa de cancelacion (churn)
|
|
|
|
**Gestion de cupones o promociones:**
|
|
- Aplicar descuentos manualmente
|
|
- Generar codigos de descuento
|
|
|
|
**Cobros manuales:**
|
|
- Marcar como pagado manualmente para clientes offline
|
|
- Extender acceso
|
|
|
|
**Historial de facturas por cliente**
|
|
|
|
### 5.4 Monitorizacion y Metricas Globales
|
|
|
|
**Uso de la plataforma:**
|
|
- Numero de tenants activos
|
|
- Usuarios activos (DAU/MAU)
|
|
- Transacciones realizadas
|
|
- Metricas tecnicas: carga del sistema, tiempos de respuesta promedio
|
|
|
|
**Analitica por tenant:**
|
|
- Uso de un tenant especifico comparado con otros o con su pasado
|
|
- Detectar clientes que crecen (posibles upsell) o con poco uso (riesgo de churn)
|
|
|
|
**Alertas y Logs:**
|
|
- Panel de salud del sistema
|
|
- Alertas de error
|
|
- Logs recientes importantes
|
|
- Integraciones con monitoring (Sentry, NewRelic, etc.)
|
|
|
|
**Reporte global financiero:**
|
|
- Resumen de facturacion total
|
|
- Nuevos clientes este mes
|
|
- Cancelaciones
|
|
|
|
### 5.5 Herramientas de Soporte y Operacion
|
|
|
|
**Impersonacion de Tenant/User:**
|
|
- Entrar en el portal de un cliente como si fueras un admin o usuario de ese tenant
|
|
- Debe quedar registrado
|
|
|
|
**Centro de mensajes o tickets:**
|
|
- Ver las consultas de soporte enviadas por los tenants
|
|
- Seguimiento de escalaciones del chatbot LLM
|
|
|
|
**Gestion de contenido global:**
|
|
- Base de conocimiento publica
|
|
- Anuncios del sistema
|
|
- Plantillas
|
|
|
|
**Configuraciones globales:**
|
|
- Activar o desactivar modulos enteros para todos los clientes
|
|
- Cambiar textos o branding general
|
|
- Configurar integraciones globales (API keys para servicios)
|
|
- Parametros de seguridad global
|
|
|
|
**Mantenimiento:**
|
|
- Modo "solo lectura" o mantenimiento
|
|
- Copias de seguridad on-demand
|
|
- Estado de jobs en background
|
|
|
|
### 5.6 Administracion de IA y Modelos LLM
|
|
|
|
Panel para la integracion de modelos de lenguaje:
|
|
- Escoger que proveedor/modelo usar globalmente por defecto (GPT-4, Claude, Gemini, etc.)
|
|
- Configurar las credenciales de API para esos servicios
|
|
- Definir limites de uso (no mas de X tokens al mes por tenant gratis)
|
|
- Monitorear el consumo de tokens global y por tenant
|
|
- Actualizar conocimiento global o prompt base comun
|
|
|
|
### 5.7 Seguridad del Portal Superadmin
|
|
|
|
El portal superadmin debe estar altamente protegido:
|
|
- MFA obligatorio
|
|
- IP whitelist
|
|
- Cumplimiento de GDPR: capacidad de exportar o eliminar los datos de un tenant completamente
|
|
|
|
---
|
|
|
|
## 6. Gestion de Suscripciones y Pagos
|
|
|
|
Para que el SaaS funcione como negocio, necesita un sistema de pagos recurrentes eficiente.
|
|
|
|
### 6.1 Registro de Suscripcion Inicial
|
|
|
|
Cuando un cliente se da de alta:
|
|
1. Ingresa un metodo de pago (tarjeta de credito usualmente)
|
|
2. Selecciona un plan
|
|
3. El sistema crea en Stripe un Customer y una Subscription asociada al Plan
|
|
|
|
**Recomendaciones:**
|
|
- Ofrecer periodo de prueba gratuito (free trial) opcional
|
|
- Garantia de devolucion
|
|
|
|
### 6.2 Planes y Precios
|
|
|
|
Definir los planes disponibles (por ejemplo: Free, Pro, Enterprise):
|
|
- Precios mensuales/anuales
|
|
- Limites por plan
|
|
|
|
**Caracteristicas de planes:**
|
|
- Numero maximo de usuarios
|
|
- Limite de datos o funcionalidades habilitadas
|
|
|
|
**Soporte de modelos de pricing:**
|
|
- Planes fijos
|
|
- Planes escalonados
|
|
- Billing metered (basado en uso)
|
|
|
|
### 6.3 Cobro Recurrente y Facturacion
|
|
|
|
Stripe se encargara de realizar los cargos automaticamente cada ciclo (ej. mensual).
|
|
|
|
**Manejo de facturas:**
|
|
- Generacion de invoice por cada pago
|
|
- Exponer enlaces a las facturas PDF para descarga
|
|
- Impuestos (IVA, etc.) si es relevante
|
|
|
|
**Retenciones y fallos de pago:**
|
|
- Si una tarjeta es rechazada, Stripe puede reintentar segun estrategia
|
|
- Escuchar eventos (webhook de invoice.payment_failed)
|
|
- Notificar al cliente (mostrar banner "Tu pago ha fallado, actualiza tu tarjeta")
|
|
- Estado de "moroso" donde el tenant no puede acceder hasta resolver pago
|
|
|
|
**Cancelaciones:**
|
|
- Decidir si se corta al instante o al fin del periodo pagado
|
|
- Estados: cancel_scheduled, cancelled
|
|
|
|
**Upgrades/Downgrades:**
|
|
- Stripe prorratea por defecto
|
|
- Aplicar nuevos limites inmediatamente o al siguiente ciclo
|
|
|
|
### 6.4 Portal de Autoservicio
|
|
|
|
**Opcion 1: Customer Portal de Stripe**
|
|
- Portal alojado donde los clientes administran su suscripcion y pagos de manera segura
|
|
- Acelera desarrollo
|
|
|
|
**Opcion 2: Implementacion propia**
|
|
- Mediante la API de Stripe
|
|
- Permite integrar mejor la apariencia y logica custom
|
|
|
|
### 6.5 Webhooks de Stripe
|
|
|
|
La automatizacion requiere webhooks de Stripe para eventos importantes de facturacion:
|
|
- Pago exitoso -> enviar email de bienvenida o habilitar tenant
|
|
- Pago fallido -> notificar al admin
|
|
- Disputa/chargeback -> notificar para accion
|
|
- Suscripcion cancelada por falta de pago -> limitar servicio
|
|
|
|
---
|
|
|
|
## 7. Integracion de IA y Asistentes Virtuales
|
|
|
|
Una caracteristica novedosa que se desea en la plataforma es la integracion de modelos de lenguaje (LLMs) para soporte y automatizacion de tareas.
|
|
|
|
### 7.1 Objetivo
|
|
|
|
Contar con agentes de IA que puedan asistir tanto a los usuarios finales como a los administradores en diversas funciones:
|
|
- Responder preguntas frecuentes
|
|
- Guiar en el uso de la aplicacion
|
|
- Ejecutar acciones dentro del sistema bajo comando natural
|
|
|
|
### 7.2 Proveedor y Modelo
|
|
|
|
La arquitectura debe ser agnostica al proveedor de IA. Disenar un servicio interno ("AI assistant") con capacidad de conectarse a distintos modelos segun configuracion:
|
|
- OpenAI (ChatGPT/GPT-4)
|
|
- Anthropic (Claude)
|
|
- Google (PaLM/Gemini)
|
|
|
|
**Plataformas unificadas recomendadas:**
|
|
- Atlas Cloud
|
|
- Anyscale Endpoints
|
|
- OpenRouter
|
|
- Together.ai
|
|
|
|
**Beneficios:**
|
|
- Una sola API key da acceso a varios LLMs
|
|
- Costos reducidos (hasta 90% mas barato que APIs oficiales)
|
|
- Modelos open-source de alto desempeno (~$1 por millon de tokens)
|
|
|
|
### 7.3 Funcionalidad del Asistente
|
|
|
|
**Rol principal inicial:** Atencion al cliente dentro de la plataforma.
|
|
|
|
**Implementacion:**
|
|
- Chat de soporte donde el usuario pueda preguntar dudas sobre el uso del sistema
|
|
- Asistente contextualizado con la documentacion del SaaS
|
|
- Acceso a datos del usuario (si se le permite)
|
|
|
|
**Ejemplos de uso:**
|
|
- Usuario: "Como puedo agregar un nuevo proyecto?" -> Asistente explica los pasos
|
|
- Admin: "Como cambio el plan de mi suscripcion?" -> Guia correspondiente
|
|
|
|
### 7.4 Agente con Capacidades de Accion
|
|
|
|
**Objetivo avanzado:** Que la IA no solo responda con texto sino que pueda realizar acciones en la plataforma.
|
|
|
|
**Ejemplo:**
|
|
- Admin: "Crea un nuevo usuario con rol de editor llamado Juan Perez con email juan@example.com"
|
|
- Asistente usa APIs internas para crear el usuario
|
|
- Confirma: "He creado el usuario Juan Perez con rol editor"
|
|
|
|
**Implementacion:**
|
|
- Tool use / function calling para el LLM
|
|
- Exponer operaciones de la plataforma (APIs CRUD) que el modelo pueda invocar
|
|
- Frameworks como LangChain para permitir ejecucion de funciones
|
|
|
|
**Seguridad:**
|
|
- Validar credenciales y permisos del usuario en cada accion solicitada
|
|
- El asistente actua siempre en nombre de un usuario autenticado
|
|
- Solo puede hacer lo que ese usuario tiene autorizado
|
|
|
|
### 7.5 Contexto y Datos del Tenant
|
|
|
|
**Integracion con base de datos:**
|
|
- Permitir consultas en lenguaje natural sobre los datos del tenant
|
|
- Ejemplo: "Asistente, cuantos proyectos activos tenemos?" -> Consulta a BD y responde
|
|
|
|
**Enfoque seguro:**
|
|
- Intents predefinidos: entrenar al modelo para reconocer ciertas preguntas y mapearlas a consultas especificas permitidas
|
|
- Evitar consultas arbitrarias no seguras
|
|
|
|
### 7.6 Canales de Interaccion
|
|
|
|
**Chat dentro de la aplicacion web:**
|
|
- Interfaz de chat en los portales (usuario y admin)
|
|
|
|
**WhatsApp Business:**
|
|
- Integracion usando la API de WhatsApp Business (Twilio o Meta's API)
|
|
- Mensajes de WhatsApp se envian al asistente LLM y respuestas vuelven por WhatsApp
|
|
- Cada tenant puede configurar su numero de WhatsApp para soporte
|
|
- Bot de soporte 24/7
|
|
|
|
### 7.7 Costos y Limites de Uso
|
|
|
|
- Invocar modelos de lenguaje genera costos por uso de tokens
|
|
- Plan basico: cierta cantidad de consultas al mes
|
|
- Plan premium: ilimitado o mayor cuota
|
|
- Superadmin puede monitorizar tokens consumidos por tenant y globalmente
|
|
- Cache de respuestas donde sea aplicable
|
|
|
|
### 7.8 Entrenamiento y Mejora Continua
|
|
|
|
- Inicialmente: respuestas basadas en documentacion estatica y reglas programadas
|
|
- Con el tiempo: incorporar aprendizaje (fine-tuning) con preguntas reales
|
|
- Opcion: entrenar al asistente para cada tenant con datos especificos (evaluar privacidad)
|
|
- Opcion segura: limitar a contexto global del software, no datos transaccionales
|
|
|
|
### 7.9 Resumen del Modulo de IA
|
|
|
|
El template SaaS debe incluir:
|
|
1. Componente backend para comunicarse con APIs de IA de distintos proveedores, facilmente conmutables
|
|
2. Claves de API configurables (almacenadas en config del superadmin)
|
|
3. Interfaz de chat en los portales (usuario y admin)
|
|
4. Logica para procesar peticiones: identificar si es pregunta/respuesta o comando que requiere accion
|
|
5. Validacion de permisos y contexto del tenant en acciones
|
|
6. Registro de conversaciones para contexto y auditoria
|
|
7. Integracion opcional con WhatsApp Business API
|
|
8. Configuraciones en panel admin (superadmin y por tenant) para activar/desactivar el asistente
|
|
|
|
**Nota importante:** Esta funcionalidad debe implementarse de forma modular (feature flags para habilitarla cuando este lista, sin acoplarla al core critico).
|
|
|
|
---
|
|
|
|
## 8. Integraciones Adicionales y API Publica
|
|
|
|
Para completar una plataforma SaaS moderna, es importante pensar en la extensibilidad.
|
|
|
|
### 8.1 API Publica
|
|
|
|
Proveer una API REST (o GraphQL) publica para que los clientes puedan integrar el SaaS con sus propias herramientas.
|
|
|
|
**Requisitos:**
|
|
- Respetar multi-tenencia (tokens API scoped a un tenant)
|
|
- Permitir a los admins de tenant generar claves API desde su portal
|
|
- Documentacion de la API (OpenAPI/Swagger)
|
|
- Sistema de autenticacion por token API separado del login interactivo
|
|
|
|
### 8.2 Webhooks
|
|
|
|
Ofrecer webhooks de eventos para permitir a los tenants recibir notificaciones en tiempo real:
|
|
|
|
**Implementacion:**
|
|
- Mecanismo de registro de webhooks (URLs por tenant con ciertos secretos)
|
|
- Envio de eventos cuando algo sucede ("un nuevo usuario fue creado", "se genero un reporte", etc.)
|
|
|
|
### 8.3 Integracion con Herramientas de Terceros
|
|
|
|
Dependiendo del dominio del SaaS, pueden requerirse integraciones con servicios populares:
|
|
- Sincronizar con Google Calendar
|
|
- Enviar notificaciones a Slack
|
|
- WhatsApp
|
|
- etc.
|
|
|
|
**Arquitectura:**
|
|
- Modulo de Integrations donde se listan posibles conexiones
|
|
- Habilitar caso a caso
|
|
|
|
### 8.4 Marketplace o Modulos Plug-and-Play (Avanzado)
|
|
|
|
- Soporte para modularidad para activar funcionalidades extras por tenant
|
|
- Feature flags administrables: superadmin puede activar caracteristica nueva para subset de tenants (beta testers)
|
|
- Configuraciones por tenant para habilitar/deshabilitar modulos
|
|
|
|
---
|
|
|
|
## 9. Flujo de Trabajo General
|
|
|
|
Para ilustrar como encajan todas estas piezas, describimos el flujo desde que un cliente descubre el SaaS hasta que opera y recibe soporte.
|
|
|
|
### 9.1 Onboarding de un Nuevo Cliente
|
|
|
|
1. El interesado visita el sitio marketing del SaaS y decide registrarse
|
|
2. Llena formulario con datos basicos de su organizacion y usuario admin
|
|
3. Elige un plan y provee tarjeta (integracion con Stripe Checkout)
|
|
4. Al confirmar, el sistema:
|
|
- Crea un nuevo tenant en la base de datos
|
|
- Crea el usuario admin ligado a ese tenant, con rol de administrador
|
|
- Suscribe al cliente en Stripe al plan seleccionado
|
|
- Envia correo de bienvenida y verifica email del admin
|
|
- Puede crear datos iniciales de ejemplo (opcional)
|
|
- Redirige al nuevo admin a su Portal Admin de Tenant
|
|
|
|
### 9.2 Configuracion Inicial por el Admin
|
|
|
|
1. El admin entra al portal de administracion de su organizacion
|
|
2. Posiblemente un wizard de bienvenida lo guia por pasos:
|
|
- Confirmar datos de empresa
|
|
- Invitar a sus primeros usuarios
|
|
- Configurar alguna preferencia importante
|
|
3. El admin agrega usuarios via la seccion de gestion de usuarios
|
|
4. Puede subir el logo de su empresa para personalizar su portal
|
|
|
|
### 9.3 Uso Diario por Usuarios Finales
|
|
|
|
1. Los usuarios (invitados) reciben correo, crean su contrasena y acceden al Portal de Usuario Final
|
|
2. Comienzan a utilizar las funcionalidades del SaaS
|
|
3. Toda interaccion pasa por las APIs multi-tenant que validan su token y tenant
|
|
4. Pueden consultar la documentacion de ayuda o preguntar al Asistente AI integrado
|
|
5. Si el asistente no resuelve la duda, pueden levantar un ticket o pedir ayuda a su admin interno
|
|
|
|
### 9.4 Soporte y Escalacion
|
|
|
|
1. Si un usuario final tiene un problema, se dirige al admin de su organizacion
|
|
2. El admin de tenant puede:
|
|
- Usar impersonacion para entrar como ese usuario y ver el problema
|
|
- Consultar logs de actividad para diagnostico
|
|
3. Si requiere ayuda del proveedor, el admin de tenant contacta al soporte global
|
|
4. Un operador del SaaS (superadmin o soporte) recibe el ticket en el Portal Superadmin
|
|
5. Puede revisar el estado del tenant, ver los logs, impersonar al usuario afectado
|
|
6. Responde al ticket o soluciona el inconveniente
|
|
|
|
### 9.5 Facturacion Recurrente
|
|
|
|
**Caso exitoso:**
|
|
1. Cada periodo, Stripe intenta el cobro
|
|
2. El cliente es cobrado automaticamente
|
|
3. La seccion de Facturacion del portal admin se actualiza
|
|
4. El Portal Superadmin registra el ingreso en sus metricas
|
|
|
|
**Caso de fallo:**
|
|
1. El sistema notifica al admin del tenant (emails automaticos y banner en portal)
|
|
2. El superadmin ve en su panel que tenants tienen pagos pendientes
|
|
3. Si tras X dias no se resuelve, el sistema suspende automaticamente el tenant
|
|
4. El admin del tenant suspendido solo puede acceder a la pagina de actualizar pago
|
|
5. Una vez resuelto, se reactiva
|
|
|
|
### 9.6 Escalabilidad y Actualizaciones
|
|
|
|
- A medida que mas clientes se suman, el backend debe escalar (instancias adicionales, balanceadores, base de datos mas robusta, caching)
|
|
- Gracias a la arquitectura multi-tenant, una actualizacion de codigo afecta a todos los tenants a la vez
|
|
- El Portal Superadmin puede tener un modo de "mantenimiento"
|
|
- Con buena automatizacion, se logra cero downtime en despliegues
|
|
- Nuevas funciones se habilitan para todos o por plan
|
|
|
|
### 9.7 Monitoreo Continuo
|
|
|
|
El superadmin utiliza las analiticas globales para:
|
|
- Ver como crece el uso
|
|
- Cuales features son mas utilizadas
|
|
- Detectar anomalias (tenant con actividad inusualmente alta)
|
|
- Vigilar los costos de infraestructura y de IA vs los ingresos
|
|
- Ajustar planes si hace falta
|
|
|
|
### 9.8 Ciclo de Vida del Cliente
|
|
|
|
**Cancelacion:**
|
|
1. El admin de tenant lo hace en su portal (o via aviso a soporte)
|
|
2. El sistema marca su suscripcion para no renovarse
|
|
3. Puede ofrecerse una ultima ventana de reactivacion
|
|
4. Tras cancelacion efectiva, el superadmin puede eliminar o archivar el tenant
|
|
5. Exportar sus datos y luego borrarlos de produccion (cumpliendo GDPR)
|
|
6. El cliente ya no puede acceder y su subdominio se desactiva
|
|
|
|
---
|
|
|
|
## 10. Conclusiones
|
|
|
|
Una plantilla estandar para un SaaS multi-tenant debe integrar todos los componentes mencionados para ser funcional y escalable desde el dia cero.
|
|
|
|
### 10.1 Resumen de Modulos Clave
|
|
|
|
| Modulo | Descripcion |
|
|
|--------|-------------|
|
|
| Base multi-tenant | Aislamiento de datos (tenant IDs o esquemas/BDs), disenada para escalar a cientos o miles de clientes |
|
|
| Autenticacion y gestion de usuarios | Login seguro (JWT, MFA, SSO opcional), control de acceso por roles, invitacion y auto-servicio de usuarios |
|
|
| Portal de Usuarios finales | Funcionalidades nucleo del servicio, experiencia sencilla, notificaciones y ayuda |
|
|
| Portal de Admins de cliente | Autogestion de su instancia: usuarios, configuracion, suscripcion, integraciones y soporte |
|
|
| Portal de Superadmin | Administracion de toda la plataforma: tenants, finanzas, soporte global, monitoreo y configuracion |
|
|
| Suscripciones y Pagos | Stripe para cobros recurrentes, planes con distintas caracteristicas, upgrades/downgrades, facturacion |
|
|
| Asistente IA (LLM) | Soporte automatizado inteligente, arquitectura desacoplada para multiples modelos, acciones con permisos |
|
|
| API y Webhooks | Extensibilidad para que clientes integren el SaaS con otros sistemas, documentacion, gestion de claves |
|
|
| Monitoreo, Alertas y Auditoria | Internos (equipo del SaaS) y expuestos a clientes, confiabilidad, compliance, transparencia |
|
|
|
|
### 10.2 Principios de Diseno
|
|
|
|
- **Documentacion centralizada y modularidad**: Minimizar duplicidad de informacion entre niveles
|
|
- **Base de conocimiento unica con propagacion de mejoras**: Si se mejora algo en el core, automaticamente todos los proyectos hijos reciben esa mejora
|
|
- **Componentes reutilizables y estandarizados**: Iniciar un nuevo SaaS vertical sea cuestion de tomar esta base e implementar solo la logica especifica del dominio
|
|
|
|
### 10.3 Valor del Template
|
|
|
|
Con los alcances definidos, se obtiene una plataforma SaaS completa en lo referente a infraestructura de software como servicio:
|
|
- Cubre administracion de multiples inquilinos
|
|
- Seguridad
|
|
- Pagos
|
|
- Funcionalidades de soporte inteligente
|
|
|
|
Esta plantilla servira como proyecto base sobre el cual construir aplicaciones SaaS especializadas, ahorrando tener que "reinventar" todo el scaffolding comun en cada nuevo desarrollo.
|
|
|
|
---
|
|
|
|
## Control de Versiones del Documento
|
|
|
|
| Version | Fecha | Cambios |
|
|
|---------|-------|---------|
|
|
| 1.0.0 | 2026-01-07 | Version inicial del documento de especificacion |
|
|
|
|
---
|
|
|
|
**Creado:** 2026-01-07
|
|
**Ultima actualizacion:** 2026-01-07
|