Principios de Ingeniería de UnoSportClub

Table of Contents

Este documento describe los principios de ingeniería, las mejores prácticas y los estándares que guían el desarrollo de software en el proyecto UnoSportClub. Su objetivo es asegurar la calidad, mantenibilidad, escalabilidad y seguridad de la aplicación.

1. Arquitectura y Diseño

1.1 Principios SOLID

Adoptamos los principios SOLID para diseñar sistemas modulares, flexibles y fáciles de mantener y extender:

Single Responsibility Principle (SRP)

Cada módulo, clase o función debe tener una única razón para cambiar:

  • Servicios Frontend: Cada servicio tiene una única responsabilidad (AuthService, ClientService, BookingService, etc.)

  • Componentes Angular: Componentes enfocados en una sola funcionalidad

  • Middleware Backend: Middleware con responsabilidades específicas (auth, autorización, logging)

  • Rutas Backend: Cada ruta maneja un recurso específico

Open/Closed Principle (OCP)

Las entidades de software (clases, módulos, funciones, etc.) deben estar abiertas para extensión, pero cerradas para modificación:

  • Interfaces y Abstracciones: Interfaces TypeScript para extensión

  • Middleware Extensible: Middleware extensible sin modificar código existente

  • Servicios Abiertos: Servicios abiertos a extensión mediante herencia o composición

  • TODO: Implementar sistema de plugins para funcionalidades extensibles

Liskov Substitution Principle (LSP)

Los objetos de un programa deben ser reemplazables por instancias de sus subtipos sin alterar el funcionamiento correcto del programa:

  • Interfaces Consistentes: Interfaces consistentes en todos los servicios

  • Implementaciones Intercambiables: Implementaciones intercambiables sin romper funcionalidad

  • Abstracciones Bien Definidas: Interfaces TypeScript bien definidas

Interface Segregation Principle (ISP)

Los clientes no deben verse forzados a depender de interfaces que no utilizan:

  • Interfaces Específicas: Interfaces específicas y pequeñas

  • Separación por Funcionalidad: Separación de interfaces por funcionalidad

  • Sin Dependencias Innecesarias: Clientes no dependen de métodos que no usan

Dependency Inversion Principle (DIP)

Los módulos de alto nivel no deben depender de módulos de bajo nivel. Ambos deben depender de abstracciones:

  • Dependencia de Abstracciones: Dependencia de abstracciones, no implementaciones concretas

  • Inyección de Dependencias: Inyección de dependencias mediante inject() function

  • Servicios Basados en Interfaces: Servicios dependen de interfaces, no de clases concretas

1.2 Arquitectura Orientada a Servicios/Microservicios

Cuando sea apropiado, se favorecerá una arquitectura basada en servicios o microservicios para permitir la escalabilidad independiente, la tolerancia a fallos y la flexibilidad en la elección de tecnologías.

Arquitectura Actual:

  • Frontend: 4 aplicaciones Angular independientes (cliente, operador, entrenador, sudo)

  • Backend: Node.js con Express.js (desplegado con PM2)

  • Base de Datos: PostgreSQL (Cloud SQL)

  • Almacenamiento/Caché: Redis

  • Mensajería: Apache Kafka

  • Autenticación: Firebase Auth (servicio externo)

  • Realtime: Sistema Relay con Socket.io (servicio independiente)

  • Infraestructura: Caddy (reverse proxy), PM2 (process manager), Firebase Hosting (frontend)

1.3 Patrones de Diseño

Se fomentará el uso consistente de patrones de diseño probados:

  • Singleton: Servicios con providedIn: 'root' en Angular

  • Dependency Injection: Uso de inject() function

  • Observer Pattern: Signals y Observables para reactividad

  • Service Layer: Separación de lógica de negocio

  • Repository Pattern: Abstracción de acceso a datos

  • Factory Pattern: Para creación de objetos complejos

  • MVC: Separación Model-View-Controller en Angular

2. Calidad del Código y Mantenibilidad

2.1 Convenciones de Código

Se seguirán estrictamente las convenciones de estilo de código definidas para cada lenguaje de programación.

TypeScript Strict Mode

Habilitado completamente (strict: true) con las siguientes configuraciones:

  • noImplicitAny: true - No permite tipos any implícitos

  • strictNullChecks: true - Verificación estricta de null/undefined

  • strictFunctionTypes: true - Verificación estricta de tipos de funciones

  • strictBindCallApply: true - Verificación estricta de bind/call/apply

  • strictPropertyInitialization: true - Propiedades deben inicializarse

  • noUnusedLocals: true - No permite variables locales no usadas

  • noUnusedParameters: true - No permite parámetros no usados

  • noImplicitReturns: true - Todas las rutas de código deben retornar

Convenciones de Nombrado

  • Clases: PascalCase (UserService, DashboardComponent)

  • Funciones/Variables: camelCase (getUser, userId)

  • Constantes: UPPER_SNAKE_CASE (API_BASE_URL, MAX_RETRIES)

  • Interfaces: PascalCase con prefijo I opcional (IUser, ClientInterface)

  • Archivos: kebab-case (user-service.ts, dashboard.component.ts)

  • Rutas: kebab-case (/user-profile, /booking-details)

Linting y Formateo

  • ESLint: Configuración estricta con reglas Angular

  • Prettier: Formateo automático de código

  • Husky Pre-commit: Hooks de Git para validaciones antes de commit

  • Lint-staged: Ejecuta linting solo en archivos modificados

  • Angular ESLint Plugin: Reglas específicas de Angular

2.2 Revisiones de Código (Code Reviews)

Todas las Pull Requests (PRs) deben ser revisadas por al menos un compañero de equipo antes de ser fusionadas con la rama principal. Las revisiones deben enfocarse en:

  • Claridad y legibilidad del código

  • Cumplimiento de los requisitos funcionales

  • Adherencia a los principios de diseño y estándares de codificación

  • Robustez y manejo de errores

  • Cobertura de pruebas

Code Review Checklist

  • ✅ No console.log() en código de producción

  • ✅ No any types sin justificación

  • ✅ Todas las funciones tienen JSDoc

  • ✅ Manejo de errores presente

  • ✅ No valores hardcodeados

  • ✅ Código modular y testeable

  • ✅ Consideraciones de performance

  • ✅ Mejores prácticas de seguridad

  • ✅ No delays artificiales (setTimeout, timer, loading states para delays)

2.3 Documentación

El código debe ser autoexplicativo siempre que sea posible. Sin embargo, se requiere documentación explícita para:

  • APIs (OpenAPI/Swagger): Documentación completa de todos los endpoints

  • Módulos Complejos: Documentación para algoritmos no triviales

  • Decisiones de Diseño: Documentación de decisiones arquitectónicas significativas

  • Configuración y Despliegue: Instrucciones claras de instalación y configuración

  • JSDoc: Todas las funciones públicas deben tener JSDoc

  • Comentarios: Solo cuando agregan valor educativo

3. Pruebas

3.1 Tipos de Pruebas

Se implementará una estrategia de pruebas integral que incluya:

Pruebas Unitarias

Para verificar el correcto funcionamiento de unidades individuales de código (funciones, métodos, clases):

  • Servicios: Pruebas unitarias para toda la lógica de negocio

  • Componentes: Pruebas de componentes aislados

  • Validadores: Pruebas de validadores personalizados

  • Utilidades: Pruebas de funciones de utilidad

Pruebas de Integración

Para asegurar que los diferentes componentes del sistema interactúan correctamente entre sí y con servicios externos:

  • API Endpoints: Pruebas de integración de rutas completas

  • Base de Datos: Pruebas de integración con PostgreSQL

  • Firebase Auth: Pruebas de integración con Firebase Authentication

  • Servicios Externos: Pruebas de integración con APIs externas

Pruebas End-to-End (E2E)

Para simular escenarios de usuario real y verificar el flujo completo de la aplicación:

  • Flujos Críticos: Registro, login, creación de reserva, pago

  • Navegación: Flujos completos de usuario

  • Interacciones: Interacciones complejas entre componentes

Pruebas de Rendimiento/Carga

Para evaluar el comportamiento del sistema bajo diferentes volúmenes de carga y usuarios:

  • Carga de Usuarios: Simulación de múltiples usuarios concurrentes

  • Consultas a BD: Optimización de consultas lentas

  • Rendimiento Frontend: Lighthouse scores y métricas de performance

3.2 Cobertura de Pruebas

Se establecerán objetivos de cobertura de pruebas y se monitorearán continuamente:

  • Objetivo de Cobertura: > 80%

  • Cobertura Actual: ⚠️ TODO: Implementar suite completa de tests

  • Monitoreo Continuo: Integración en CI/CD pipeline

  • Reportes: Generación automática de reportes de cobertura

4. Seguridad

4.1 Seguridad por Diseño

La seguridad debe ser una consideración fundamental en cada etapa del ciclo de vida de desarrollo de software (SDLC), desde el diseño hasta la implementación y el despliegue.

4.2 Prácticas de Codificación Segura

Se seguirán las mejores prácticas de codificación segura para prevenir vulnerabilidades comunes (OWASP Top 10):

Validación y Saneamiento de Entradas

  • Frontend: Validadores Angular (Validators.required, Validators.email, etc.)

  • Backend: Validación de esquemas con express-validator

  • Base de Datos: Constraints y tipos de datos

  • Sanitización: Limpieza de datos de entrada antes de procesar

Prevención de Inyección

  • SQL Injection: Prevenido mediante prepared statements

  • XSS (Cross-Site Scripting): Prevenido mediante sanitización y Content Security Policy

  • CSRF (Cross-Site Request Forgery): Protegido por Firebase Auth y SameSite cookies

Gestión Segura de Sesiones y Autenticación

  • Firebase Auth: Maneja la autenticación de usuarios

  • JWT Tokens: Tokens JWT para sesiones

  • Validación de Tokens: Validación de tokens en cada petición a la API

  • Refresh Tokens: Renovación automática de tokens expirados

  • Custom Claims: Roles y permisos mediante Custom Claims

Control de Acceso Basado en Roles (RBAC)

  • Roles Definidos: operator, admin, sudo, trainer, user

  • Middleware de Autorización: Validación de permisos antes de procesar requests

  • Route Guards: Protección de rutas basadas en roles del usuario

  • HTTP Interceptors: Agregan token automáticamente a requests

Cifrado de Datos Sensibles

  • Cifrado en Tránsito: HTTPS/TLS para todas las comunicaciones

  • Cifrado en Reposo: Conexiones SSL/TLS para base de datos

  • Certificados SSL: Gestionados automáticamente por Firebase Hosting y Caddy

  • HSTS: HTTP Strict Transport Security habilitado

Security Headers

Configurados en middleware de Express y Caddy:

  • X-Content-Type-Options: nosniff - Previene MIME type sniffing

  • X-Frame-Options: DENY - Previene clickjacking

  • X-XSS-Protection: 1; mode=block - Protección XSS del navegador

  • Referrer-Policy: strict-origin-when-cross-origin - Control de referrer

  • Content-Security-Policy - Política de seguridad de contenido

  • Strict-Transport-Security - Fuerza HTTPS

4.3 Auditorías de Seguridad

Se realizarán auditorías de seguridad periódicas y pruebas de penetración para identificar y remediar posibles vulnerabilidades:

  • Auditorías Periódicas: Revisión regular de código y configuración

  • Pruebas de Penetración: Identificación proactiva de vulnerabilidades

  • Security Audit: npm audit en cada build

  • Dependencias: Monitoreo de vulnerabilidades en dependencias

5. Despliegue y Operaciones (DevOps)

5.1 Integración Continua / Despliegue Continuo (CI/CD)

Se implementarán pipelines de CI/CD para automatizar la construcción, prueba y despliegue del software:

  • GitHub Actions: Pipelines de CI/CD configurados

  • Build Automático: Construcción automática en cada push

  • Tests Automáticos: Ejecución de tests en cada build

  • Deploy Automático: Despliegue automático a producción tras validaciones

  • Zero-Downtime: Despliegues sin tiempo de inactividad

5.2 Infraestructura como Código (IaC)

La infraestructura se gestionará como código para asegurar la consistencia y la reproducibilidad de los entornos:

  • Firebase Hosting: Configuración mediante firebase.json

  • Cloud SQL: Configuración mediante Google Cloud Console

  • Caddy: Configuración mediante Caddyfile

  • PM2: Configuración mediante ecosystem.config.js

  • TODO: Implementar Terraform o Ansible para infraestructura completa

5.3 Monitoreo y Logging

Se implementarán soluciones robustas de monitoreo y logging:

  • PM2 Logs: Logs centralizados de procesos Node.js

  • Caddy Logs: Logs de acceso y errores del reverse proxy

  • PostgreSQL Logs: Logs de consultas y errores de base de datos

  • Error Tracking: Seguimiento de errores en producción

  • Performance Monitoring: Monitoreo de rendimiento de la aplicación

  • TODO: Implementar solución de monitoreo completa (Sentry, DataDog, etc.)

6. Herramientas y Tecnologías

Se mantendrá una lista actualizada de las herramientas, frameworks y tecnologías preferidas para el desarrollo en UnoSportClub.

6.1 Frontend

  • Angular: 21.0.2

  • Angular Fire: 20.0.1

  • RxJS: 7.8.0

  • Tailwind CSS: 4.1.17

  • Angular Material: 21.0.1

  • FullCalendar: 6.1.19

6.2 Backend

  • Node.js: 22.x o superior

  • Express: 5.1.0

  • Firebase Admin SDK: 13.6.0

  • PostgreSQL Driver (pg): 8.16.3

  • Socket.io: 4.8.1

  • Swagger JSDoc: Documentación

6.3 Herramientas de Desarrollo

  • TypeScript: 5.9.3

  • ESLint: 8.57.0

  • Prettier: 3.2.0

  • Husky: 9.0.0

  • Karma/Jasmine: Testing

  • Vitest: 4.0.8

6.4 Infraestructura

  • Caddy: Reverse proxy y load balancer

  • PM2: Gestión de procesos Node.js

  • Firebase Hosting: CDN y hosting estático

  • Cloud SQL: Base de datos PostgreSQL

  • Redis: (Opcional) Para escalado horizontal del sistema Relay

Las decisiones sobre nuevas tecnologías deben pasar por un proceso de revisión y aprobación.

7. Gestión de Versiones (Version Control)

Se utilizará Git para el control de versiones, siguiendo un flujo de trabajo de ramificación (branching strategy) claro:

  • GitFlow o Trunk Based Development: Estrategia de ramificación definida

  • Mensajes de Commit: Descriptivos y concisos siguiendo convenciones

  • Pull Requests: Requeridas para cambios en rama principal

  • Code Review: Obligatorio antes de merge

7.1 Convenciones de Commit

Formato de mensajes de commit:

<type>(<scope>): <subject>

<body>

<footer>

Tipos: * feat: Nueva característica * fix: Corrección de bug * docs: Documentación * style: Formateo, sin cambio de lógica * refactor: Refactorización de código * perf: Mejora de performance * test: Agregar o actualizar tests * chore: Build, dependencies, etc.

8. Métricas de Calidad

8.1 Objetivos del Proyecto

Métrica Objetivo Estado Actual

TypeScript Errors

0

✅ Cumplido

ESLint Warnings

0

✅ Cumplido

Test Coverage

> 80%

⚠️ TODO: Implementar

Bundle Size

< 500KB

✅ Cumplido

Lighthouse Score

> 90

⚠️ TODO: Medir

Security Issues

0

✅ Cumplido

Accessibility Issues

0

⚠️ TODO: Auditar

Code Duplication

< 5%

⚠️ TODO: Medir

8.2 Pre-Deployment Checklist

  • Todos los errores TypeScript resueltos (tsc --noEmit)

  • Todos los tests pasando (ng test)

  • Sin warnings ESLint (ng lint)

  • Tamaño de bundle aceptable

  • Lighthouse score > 90

  • Security audit pasado (npm audit)

  • Sin errores de consola en dev tools

  • Diseño responsive probado

  • Testing cross-browser (Chrome, Firefox, Safari, Edge)

  • Auditoría de accesibilidad pasada

  • Performance perfilado

  • Git history limpio

  • Documentación actualizada

  • Variables de entorno configuradas

9. Patrones Angular Específicos

9.1 Standalone Components

  • Todos los componentes son standalone (sin NgModules)

  • standalone: true implícito (no se declara explícitamente)

  • Imports explícitos en cada componente

  • Mejor tree-shaking y optimización de bundles

9.2 Signals para Gestión de Estado

  • Signals en lugar de Observables para estado local

  • signal() para estado mutable

  • computed() para estado derivado

  • effect() para efectos secundarios

  • No usar mutate(), preferir update() o set()

9.3 Dependency Injection

  • Uso de inject() function en lugar de constructor injection

  • providedIn: 'root' para servicios singleton

  • Injection tokens para valores configurables

9.4 Reactive Forms

  • Formularios reactivos en lugar de template-driven

  • Validación en múltiples capas

  • Validadores personalizados reutilizables

9.5 Lazy Loading

  • Carga diferida de rutas con loadComponent

  • Code splitting automático

  • Reducción del bundle inicial

10. Performance

10.1 Objetivos de Performance

  • Bundle Inicial: < 500KB

  • Chunks Lazy: < 50KB cada uno

  • Lighthouse Score: > 90

  • Time to Interactive (TTI): < 3 segundos

  • First Contentful Paint (FCP): < 1.8 segundos

10.2 Optimizaciones

  • Lazy Loading: Carga diferida de módulos

  • Code Splitting: División automática de código

  • Tree Shaking: Eliminación de código no usado

  • Minificación: Compresión de código

  • Caché: Caché de assets estáticos

  • CDN: Distribución global mediante Firebase Hosting

11. Accesibilidad (WCAG 2.1 Level AA)

11.1 Requisitos de Accesibilidad

  • Contraste de Colores: ≥ 4.5:1

  • Navegación por Teclado: Navegación completa por teclado

  • ARIA Labels: Donde sea necesario

  • Indicadores de Foco: Visibles y claros

  • No Dependencia de Color: Información no depende solo de color

  • Semantic HTML: Uso de etiquetas semánticas apropiadas

12. Referencias

Este documento es dinámico y se actualizará a medida que el proyecto UnoSportClub evolucione y se adopten nuevas mejores prácticas.