Manual de Integración

Este manual proporciona información completa sobre la integración, instalación y configuración del sistema UnoSportClub.

Introducción

UnoSportClub es una plataforma web completa para la gestión de clubes deportivos, construida con Angular y Firebase. El sistema está diseñado como una aplicación multi-proyecto que incluye diferentes interfaces para diferentes roles de usuario.

Arquitectura del Sistema

Componentes Principales

El sistema está compuesto por los siguientes componentes:

Frontend (Angular)

Aplicación Principal (unosportclub): Interfaz para usuarios finales
Panel de Operador (panel): Interfaz para operadores del día a día
Panel de Entrenador (trainer): Interfaz para entrenadores
Panel de Control (sudo): Interfaz para super usuarios y administradores

Backend (Firebase Functions + Express)

API REST: Endpoints para todas las operaciones del sistema
Autenticación: Integración con Firebase Authentication
Base de Datos: PostgreSQL para almacenamiento de datos relacionales

Infraestructura

Firebase Hosting: Alojamiento de las aplicaciones frontend
Firebase Functions: Ejecución del backend
Firebase Authentication: Gestión de usuarios y autenticación
PostgreSQL: Base de datos relacional

Flujo de Datos

El sistema sigue una arquitectura cliente-servidor:

El usuario accede a una de las aplicaciones frontend (hosted en Firebase Hosting)
La aplicación se autentica usando Firebase Authentication
Las peticiones a la API se enrutan a Firebase Functions
Las Functions procesan las peticiones y consultan PostgreSQL
Las respuestas se devuelven al cliente

Estructura del Proyecto

Organización de Directorios

unosportclub/
├── projects/              # Proyectos Angular independientes
│   ├── panel/            # Panel de operador
│   ├── trainer/          # Panel de entrenador
│   └── sudo/             # Panel de control
├── src/                  # Aplicación principal Angular
├── functions/            # Backend (Firebase Functions)
│   ├── routes/          # Rutas de la API
│   ├── db/              # Migraciones y seeders
│   └── models/          # Modelos de datos
├── docs/                # Documentación
├── firebase.json        # Configuración de Firebase
└── .firebaserc          # Configuración de proyectos Firebase

Configuración de Hosting Múltiple

El sistema utiliza múltiples sitios de hosting en Firebase:

prod: Aplicación principal (dist/unosportclub/browser)
panel: Panel de operador (dist/panel/browser)
trainer: Panel de entrenador (dist/trainer/browser)
control: Panel de control (dist/sudo/browser)

Cada sitio tiene su propia configuración en firebase.json y se despliega independientemente.

Instalación y Configuración

Ver Guía de Instalación Completa

Resumen de Instalación

Instalar dependencias: npm install
Configurar variables de entorno en functions/.env
Ejecutar migraciones: npm run db:migrate
Construir aplicaciones: npm run build:all
Desplegar: npm run deploy:firebase

Configuración de Entornos

Variables de Entorno

El sistema requiere las siguientes variables de entorno para funcionar:

Base de Datos PostgreSQL

DATABASE_URL=postgresql://usuario:password@host:puerto/nombre_bd

O usando variables individuales:

DB_HOST=localhost
DB_PORT=5432
DB_NAME=unosportclub
DB_USER=postgres
DB_PASSWORD=tu_password
DB_SSL=false

Firebase Configuration

Las configuraciones de Firebase se encuentran en los archivos de entorno de cada proyecto:

src/environments/environment.ts (desarrollo)
src/environments/environment.prod.ts (producción)
projects/*/src/environments/environment.ts
projects/*/src/environments/environment.prod.ts

Configuración de Firebase Authentication

El sistema utiliza Firebase Authentication con los siguientes métodos:

Email/Password
Autenticación mediante tokens JWT

Los roles se gestionan mediante custom claims en Firebase Auth:

admin: Administrador
operator: Operador
trainer: Entrenador
sudo: Super usuario

Integración de Componentes

Comunicación Frontend-Backend

El frontend se comunica con el backend mediante HTTP requests a la API REST:

// Ejemplo de servicio Angular
import { HttpClient } from '@angular/common/http';
import { inject } from '@angular/core';

export class MyService {
  private http = inject(HttpClient);
  private apiUrl = '/api';

  getData() {
    return this.http.get(`${this.apiUrl}/endpoint`);
  }
}

Autenticación y Autorización

El sistema utiliza interceptores HTTP para agregar tokens de autenticación:

// Interceptor de autenticación
export const authInterceptor: HttpInterceptorFn = (req, next) => {
  const auth = inject(Auth);
  const token = await auth.currentUser?.getIdToken();

  if (token) {
    req = req.clone({
      setHeaders: {
        Authorization: `Bearer ${token}`
      }
    });
  }

  return next(req);
};

El backend verifica los tokens y los custom claims para autorizar las peticiones.

Base de Datos

El sistema utiliza PostgreSQL como base de datos relacional. Las migraciones se gestionan mediante scripts en functions/db/migrations/.

Modelo de Datos Principal

Las tablas principales incluyen:

user: Usuarios del sistema (vinculados con Firebase Auth)
client: Información de clientes
court: Canchas deportivas
reservation: Reservas
payment: Pagos
training_class: Clases de entrenamiento
enrollment: Inscripciones a clases

Despliegue

Desarrollo Local

Para desarrollo local:

# Iniciar emuladores de Firebase
firebase emulators:start

# Construir y observar cambios
npm run watch:all

# O usar el comando combinado
npm run dev:firebase

Producción

Para desplegar a producción:

# Construir todas las aplicaciones y desplegar
npm run deploy:firebase

Este comando:

Construye todas las aplicaciones Angular
Despliega las Functions a Firebase
Despliega todos los sitios de hosting

Despliegue Selectivo

Puedes desplegar componentes específicos:

# Solo Functions
firebase deploy --only functions

# Solo Hosting
firebase deploy --only hosting

# Solo una aplicación específica
firebase deploy --only hosting:prod
firebase deploy --only hosting:panel
firebase deploy --only hosting:trainer
firebase deploy --only hosting:control

Gestión de Base de Datos

Migraciones

Las migraciones se ejecutan automáticamente durante npm install o manualmente:

npm run db:migrate

Seeders

Los seeders cargan datos iniciales:

npm run db:seed

Reset de Base de Datos

Para resetear completamente la base de datos (CUIDADO):

npm run db:reset

Monitoreo y Logs

Logs de Firebase Functions

Ver logs en tiempo real:

firebase functions:log --follow

Ver logs de una función específica:

firebase functions:log --only api

Verificación de Estado

Listar todas las funciones desplegadas:

firebase functions:list

Seguridad

Autenticación

Todos los endpoints requieren autenticación (excepto endpoints públicos)
Los tokens JWT se validan en cada petición
Los custom claims determinan los permisos

Autorización

El sistema implementa control de acceso basado en roles (RBAC):

Cada endpoint verifica el rol del usuario
Los middlewares validan los permisos antes de procesar las peticiones

Variables Sensibles

Las variables sensibles (como credenciales de base de datos) deben almacenarse usando Firebase Secret Manager en producción.

Solución de Problemas Comunes

Error de Conexión a Base de Datos

Verifica que PostgreSQL esté corriendo
Verifica las credenciales en functions/.env
Verifica que el firewall permita conexiones
Para bases de datos en la nube, verifica la configuración de SSL

Error de Autenticación

Verifica que Firebase Authentication esté configurado
Verifica que los custom claims estén asignados correctamente
Revisa los logs de Firebase Functions para más detalles

Error de Build

Verifica que todas las dependencias estén instaladas: npm install
Verifica la versión de Node.js (debe ser 22 o superior)
Revisa los errores de TypeScript: npm run build

Próximos Pasos

Una vez completada la integración:

Revisa la Documentación del Desarrollador
Consulta la Referencia de API
Configura dominios personalizados si es necesario
Configura monitoreo y alertas

Actualización del Sistema

Proceso de Actualización

Para actualizar el sistema a una nueva versión:

Backup: Realiza un backup completo antes de actualizar
Revisa el changelog: Consulta los cambios en la nueva versión
Actualiza código: git pull o descarga la nueva versión
Actualiza dependencias: npm install en el proyecto principal y functions/
Ejecuta migraciones: npm run db:migrate si hay nuevas migraciones
Reconstruye: npm run build:all
Despliega: npm run deploy:firebase
Verifica: Prueba las funcionalidades principales

Migraciones de Base de Datos

Si hay nuevas migraciones:

Revisa las migraciones antes de ejecutarlas
Prueba en un entorno de desarrollo primero
Realiza backup antes de ejecutar migraciones
Verifica que las migraciones se completen correctamente

Actualización de Dependencias

Para actualizar dependencias:

# Actualizar dependencias del proyecto principal
npm update

# Actualizar dependencias de Functions
cd functions
npm update
cd ..

Prueba siempre las actualizaciones en un entorno de desarrollo antes de producción.

Mantenimiento Regular

Tareas de Mantenimiento Diarias

Revisar logs de errores
Verificar que los backups se ejecuten correctamente
Monitorear el uso de recursos
Revisar métricas de rendimiento

Tareas de Mantenimiento Semanales

Revisar y limpiar logs antiguos
Verificar la integridad de backups
Analizar métricas de uso
Revisar actualizaciones de seguridad

Tareas de Mantenimiento Mensuales

Actualizar dependencias (si es necesario)
Revisar y optimizar la base de datos
Analizar costos de Firebase
Revisar y actualizar documentación

Monitoreo y Alertas

Configurar Monitoreo

Configura monitoreo para:

Errores críticos: Alertas inmediatas para errores críticos
Rendimiento: Monitoreo de tiempos de respuesta
Disponibilidad: Verificación de que los servicios estén disponibles
Recursos: Monitoreo de uso de CPU, memoria, almacenamiento

Alertas Recomendadas

Configura alertas para:

Errores en Functions
Tiempos de respuesta altos
Fallos en conexión a base de datos
Backups fallidos
Uso de recursos alto