Preparación del Entorno de Desarrollo

Esta guía detallada te ayudará a configurar tu entorno de desarrollo local para trabajar en UnoSportClub.

Requisitos del Sistema

Software Requerido

  • Node.js: Versión 25 o superior

  • npm: Versión 9 o superior

  • Git: Para control de versiones

  • PostgreSQL: Versión 14 o superior (local o acceso a instancia remota)

  • Firebase CLI: Para gestión de Firebase

  • Angular CLI: Incluido como dependencia del proyecto

Verificar Instalaciones

node --version      # Debe ser v25.x o superior
npm --version       # Debe ser 9.x o superior
git --version
psql --version      # Debe ser PostgreSQL 14+
firebase --version

Herramientas Recomendadas

  • Editor de código: Visual Studio Code (recomendado)

  • Extensiones VS Code:

  • Angular Language Service

  • ESLint

  • Prettier

  • GitLens

  • PostgreSQL

  • Cliente PostgreSQL: pgAdmin, DBeaver, o psql CLI

  • Cliente REST: Postman o Insomnia (para probar APIs)

Configuración Inicial del Proyecto

Clonar el Repositorio

git clone <url-del-repositorio>
cd unosportclub

Instalar Dependencias

# Instalar dependencias del proyecto principal
npm install

# Instalar dependencias de Functions
cd functions
npm install
cd ..

El comando npm install en la raíz ejecutará automáticamente las migraciones de base de datos si las variables de entorno están configuradas.

Configuración de Base de Datos Local

Instalar PostgreSQL

Fedora/RHEL:

sudo dnf install postgresql postgresql-server postgresql-contrib
sudo postgresql-setup --initdb
sudo systemctl enable postgresql
sudo systemctl start postgresql

Ubuntu/Debian:

sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

macOS (Homebrew):

brew install postgresql@14
brew services start postgresql@14

Windows:

Descarga el instalador desde https://www.postgresql.org/download/windows/

Configurar Autenticación (Fedora/RHEL)

En Fedora, PostgreSQL usa autenticación ident por defecto. Para permitir autenticación por contraseña, configura pg_hba.conf:

# Obtener la ruta del archivo de configuración
sudo -u postgres psql -t -c "SHOW hba_file;"

# Hacer backup del archivo
sudo cp /var/lib/pgsql/data/pg_hba.conf /var/lib/pgsql/data/pg_hba.conf.backup

# Cambiar ident por md5 para conexiones locales
sudo sed -i 's/^host.*all.*all.*127.0.0.1\/32.*ident$/host    all             all             127.0.0.1\/32            md5/' /var/lib/pgsql/data/pg_hba.conf
sudo sed -i 's/^host.*all.*all.*::1\/128.*ident$/host    all             all             ::1\/128                 md5/' /var/lib/pgsql/data/pg_hba.conf

# Recargar PostgreSQL
sudo systemctl reload postgresql

Crear Usuario y Bases de Datos

# Conectar como usuario postgres
sudo -u postgres psql

# Crear usuario con contraseña
CREATE USER unosportclub WITH PASSWORD 'unosportclub_password';

# Crear bases de datos (desarrollo y test)
CREATE DATABASE unosportclub OWNER unosportclub;
CREATE DATABASE unosportclub_test OWNER unosportclub;

# Otorgar permisos
GRANT ALL PRIVILEGES ON DATABASE unosportclub TO unosportclub;
GRANT ALL PRIVILEGES ON DATABASE unosportclub_test TO unosportclub;

# Salir
\q

Instalar Extensión btree_gist

La extensión btree_gist es requerida para algunas migraciones:

# Fedora/RHEL: Instalar paquete contrib
sudo dnf install postgresql-contrib

# Crear extensión en ambas bases de datos
sudo -u postgres psql -d unosportclub -c "CREATE EXTENSION IF NOT EXISTS btree_gist;"
sudo -u postgres psql -d unosportclub_test -c "CREATE EXTENSION IF NOT EXISTS btree_gist;"

Configurar Variables de Entorno

Crea el archivo functions/.env:

cd functions
cp .env.example .env

Edita functions/.env con tu configuración local:

# Base de datos de desarrollo
DB_HOST=localhost
DB_PORT=5432
DB_NAME=unosportclub
DB_USER=unosportclub
DB_PASSWORD=unosportclub_password

# Base de datos de test
DB_TEST_HOST=localhost
DB_TEST_PORT=5432
DB_TEST_NAME=unosportclub_test
DB_TEST_USER=unosportclub
DB_TEST_PASSWORD=unosportclub_password

# SSL (false para desarrollo local)
DB_SSL=false

# Alternativa: Usar DATABASE_URL
# DATABASE_URL=postgresql://unosportclub:unosportclub_password@localhost:5432/unosportclub
# DATABASE_TEST_URL=postgresql://unosportclub:unosportclub_password@localhost:5432/unosportclub_test

Ejecutar Migraciones y Seeders

# Desde la raíz del proyecto
npm run db:migrate

Esto creará todas las tablas y cargará los datos iniciales.

Verificar Instalación de Base de Datos

# Verificar conexión
PGPASSWORD=unosportclub_password psql -h localhost -U unosportclub -d unosportclub -c "SELECT version();"

# Ver tablas creadas
PGPASSWORD=unosportclub_password psql -h localhost -U unosportclub -d unosportclub -c "\dt"

# O usando el script de prueba del proyecto
npm run db:test

Deberías ver las siguientes tablas:

  • user

  • client

  • document_type

  • court_type

  • court

  • reservation_type

  • reservation_status

  • reservation

  • tariff

  • tariff_class

  • payment_type

  • payment

  • discount

  • class

  • enrollment

  • schema_migrations

Configuración de Firebase

Instalar Firebase CLI

npm install -g firebase-tools

Iniciar Sesión en Firebase

firebase login

Inicializar Firebase en el Proyecto

Si el proyecto aún no está inicializado:

firebase init

Selecciona: * Hosting: Sí (para frontend) * Functions: No (ya no usamos Firebase Functions) * Firestore: No (usamos PostgreSQL) * Storage: Opcional

Configurar Proyecto Firebase

firebase use --add

Selecciona tu proyecto de desarrollo.

Configuración del Editor

Visual Studio Code

Crea o edita .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.preferences.importModuleSpecifier": "relative",
  "files.exclude": {
    "**/.git": true,
    "**/.DS_Store": true,
    "**/node_modules": true,
    "**/dist": true
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/.angular": true
  }
}

Configuración de ESLint

El proyecto usa ESLint con configuración de Google. Asegúrate de tener la extensión instalada y que respete las reglas del proyecto.

Configuración de Prettier

El proyecto incluye configuración de Prettier en package.json. Asegúrate de que tu editor lo respete.

Estructura del Proyecto

Directorios Principales

unosportclub/
├── src/                    # Código fuente Angular (aplicación principal)
├── projects/
│   ├── panel/             # Aplicación panel de administración
│   └── sudo/              # Aplicación panel de control
├── functions/             # Backend (Node.js/Express)
│   ├── server.js          # Servidor Express principal
│   ├── routes/            # Rutas de la API organizadas por namespace
│   ├── relay/             # Sistema Relay (Socket.io)
│   ├── db/                # Migraciones y seeders
│   └── utils/             # Utilidades
├── docs/                   # Documentación
├── dist/                   # Build de producción (generado)
└── firebase.json           # Configuración de Firebase

Archivos Importantes

  • package.json: Dependencias y scripts del proyecto principal

  • functions/package.json: Dependencias y scripts de Functions

  • angular.json: Configuración de Angular

  • tsconfig.json: Configuración de TypeScript

  • firebase.json: Configuración de Firebase Hosting y Functions

  • functions/.env: Variables de entorno (no se sube a Git)

Scripts de Desarrollo

Scripts Principales

# Desarrollo
npm start                  # Inicia servidor de desarrollo Angular
npm run build              # Build de producción
npm run watch              # Build en modo watch

# Base de datos
npm run db:migrate         # Ejecutar migraciones y seeders
npm run db:uninstall       # Eliminar todas las tablas (CUIDADO)

# Testing
npm test                   # Ejecutar tests de Angular

Scripts del Backend

cd functions

# Desarrollo
node server.js            # Inicia servidor Express (puerto 3000 por defecto)
npm run lint              # Verificar código con ESLint

# Testing
npm test                  # Ejecutar tests
npm run test:watch        # Tests en modo watch
npm run test:coverage     # Tests con cobertura

Variables de Entorno del Backend

El servidor backend requiere las siguientes variables de entorno en functions/.env:

# Base de datos
DATABASE_URL=postgresql://usuario:password@host:puerto/database

# Redis (opcional, para escalado horizontal del Relay)
REDIS_URL=redis://localhost:6379

# Sistema Relay (opcional)
REALTIME_ENABLED=true

# Puerto del servidor (opcional, default: 3000)
PORT=3000

Servidor Backend Local

Iniciar Servidor Backend

cd functions
node server.js

El servidor estará disponible en: * API REST: http://localhost:3000/api * Health Check: http://localhost:3000/health * Swagger Docs: http://localhost:3000/api/api-docs * Sistema Relay: http://localhost:3000/realtime (si está habilitado)

Iniciar con PM2 (Producción Local)

cd functions
pm2 start server.js --name unosportclub-api
pm2 logs unosportclub-api

Flujo de Trabajo de Desarrollo

1. Crear una Rama

git checkout -b feature/nombre-de-la-feature

2. Desarrollo Local

# Terminal 1: Servidor Angular
npm start

# Terminal 2: Servidor Backend (Express)
cd functions
node server.js

# Terminal 3: Base de datos (si es necesario)
psql -U unosportclub -d unosportclub

# Opcional: Redis (si usas escalado horizontal del Relay)
redis-server

3. Ejecutar Tests

# Tests de Angular
npm test

# Tests de Functions
cd functions
npm test

4. Verificar Código

# Lint de Functions
cd functions
npm run lint

# Build para verificar errores de TypeScript
npm run build

5. Commit y Push

git add .
git commit -m "feat: descripción del cambio"
git push origin feature/nombre-de-la-feature

Configuración de Git

.gitignore

El proyecto incluye un .gitignore que excluye:

  • node_modules/

  • dist/

  • .env y functions/.env

  • Archivos de build y cache

  • Archivos del IDE

Hooks de Git (Opcional)

Puedes configurar pre-commit hooks para ejecutar lint y tests automáticamente usando herramientas como husky.

Solución de Problemas Comunes

Error: Puerto ya en uso

Si el puerto 4200 (Angular) o 3000 (Backend) está en uso:

# Encontrar proceso usando el puerto
lsof -i :4200
lsof -i :3000

# Matar el proceso
kill -9 <PID>

# O cambiar el puerto del backend
cd functions
PORT=3001 node server.js

Error: Variables de Entorno No Cargadas

Asegúrate de que: * El archivo functions/.env existe * Las variables están correctamente formateadas * No hay espacios alrededor del = en las variables

Error: Base de Datos No Conecta

Verifica: * PostgreSQL está corriendo: sudo systemctl status postgresql * Las credenciales en .env son correctas * El usuario tiene permisos: GRANT ALL PRIVILEGES ON DATABASE unosportclub TO unosportclub; * En Fedora, verifica que pg_hba.conf use md5 en lugar de ident para conexiones locales * La extensión btree_gist está instalada: sudo dnf install postgresql-contrib

Error: Migraciones No Se Ejecutan

# Ejecutar manualmente
npm run db:migrate

# Ver estado de migraciones
psql -U unosportclub -d unosportclub -c "SELECT * FROM schema_migrations;"

Error: Build de Angular Falla

# Limpiar cache
rm -rf node_modules .angular dist
npm install
npm run build

Recursos Adicionales

Documentación

Enlaces Externos

Próximos Pasos

Una vez configurado tu entorno:

  1. Revisa la Arquitectura del Software

  2. Familiarízate con el Modelo de Datos

  3. Explora la Referencia de API

  4. Revisa los Flujos de Trabajo principales

  5. Consulta el Proceso de Desarrollo