Manual del Desarrollador de UnoSportClub

Manual técnico del monorepo v0.4.x: Angular 21, Express 5, PostgreSQL, OAuth2 local y despliegue Docker/GHCR.

1. Introducción

UnoSportClub gestiona reservas de canchas, pagos, clases, eventos panel (PMV), tickets, contabilidad NIIF y operación multi-rol (cliente, operador, entrenador, sudo, contabilidad).

Documentación detallada: Arquitectura, API, Modelo de datos, Diagramas, Entornos y releases, CI/CD.

2. Inicio rápido

2.1 Requisitos

  • Node.js 24.x (alineado con CI; ver package.json engines >=24)

  • npm 9+

  • PostgreSQL 14+

  • Git

2.2 Clonar e instalar

El repositorio es un monorepo único (sin submódulos Git):

git clone --branch develop git@github.com:cortex-ia-com-co/unosportclub.git
cd unosportclub
npm install
cp .env.example .env

2.3 Base de datos y API

cd functions
cp .env.example .env
node db/install.js
node db/install-accounting.js

API local: http://localhost:6000/api (ver xref:development-environment.adoc).

2.4 Desarrollo local (5 SPAs + backend)

Desde la raíz del monorepo:

npm run dev:serve

| Puerto | Aplicación | |--------|------------| | 6000 | API Express (/api) | | 6100 | App cliente (src/) | | 6101 | Panel operador | | 6102 | Panel entrenador | | 6103 | Panel sudo | | 6104 | Contabilidad NIIF |

Alternativa por app: npm start, npm run start:panel, etc.

2.5 Pruebas y build

npm test
npm run build:production:all
cd docs && npm run build:local

Módulos recientes (v0.4.1)

3. Estructura del monorepo

Ruta Contenido

src/

SPA app cliente

projects/panel/

Panel operador

projects/trainer/

Panel entrenador

projects/sudo/

Panel superusuario

projects/accounting/

Contabilidad NIIF

projects/common/

Librería @cortex-ia-com-co/common

functions/

API Express, migraciones, OAuth2 local

docs/

Sitio Antora (esta documentación)

docker/

Nginx template + entrypoint imagen unificada

Dockerfile

Imagen producción → GHCR

Autenticación: OAuth2 local (OIDC + JWT RS256). Datos: PostgreSQL principal + DB_NAME_ACCOUNTING. Tiempo real: Socket.io (Relay). Despliegue: imagen Docker unificada (ver Despliegue con Caddy y Docker).

4. Buenas prácticas

  • Estándares de código y hora mural (reservation-wall-time)

  • JWT en rutas protegidas; validar entrada en backend

  • Consultas parametrizadas; transacciones en operaciones críticas

  • npm test antes de PR; TDD en backend (functions/tests)

  • Signals y standalone en Angular; ver Metodología de Desarrollo Ágil

5. Contribución

  1. Fork → rama descriptiva → cambios → npm test

  2. Pull Request a develop con descripción clara

  3. Issues: https://github.com/cortex-ia-com-co/unosportclub/issues

6. Referencias