@battle-racing/br-common-lib/docs/REFACTOR_README.md

Common library for all Battle Racing Repositorios

# Battle Racing Common Library

## Descripción General

Battle Racing Common Library es una librería TypeScript compartida que proporciona tipos, constantes, datos y utilidades comunes para todos los repositorios del ecosistema Battle Racing. Esta librería actúa como el núcleo central de tipos y definiciones que garantizan la consistencia y interoperatividad entre los diferentes componentes del sistema.

## Arquitectura del Sistema Battle Racing

El ecosistema Battle Racing está compuesto por **3 proyectos principales** que comparten esta librería común:

### 1. **Web App** (Frontend)

- Interfaz de usuario para controladores y espectadores
- Gestión de juegos, karts y usuarios
- Comunicación en tiempo real vía WebSockets

### 2. **Backend** (API Server)

- Servidor central que maneja la lógica de negocio
- Gestión de bases de datos y estado de juegos
- Coordinación entre todos los componentes del sistema

### 3. **Kart Manager** (Software de Kart)

- **Software instalado en cada kart** (Raspberry Pi)
- Gestiona módulos de hardware conectados al kart físico
- Procesa eventos locales y reporta cambios de estado
- Se comunica con el backend como representante del kart físico
- **Actúa como la fuente de verdad del estado del kart**

## Estructura de la Librería

### 📁 `src/types/`

Contiene todas las definiciones de tipos TypeScript compartidas:

- **`game/`**: Tipos relacionados con juegos (Race, Battle), estados, rankings
- **`kart/`**: Definiciones de karts, estados de hardware, escudos
- **`hardware/`**: Módulos de hardware (speed, screen, RGB, flag, sensors, etc.)
- **`powerUp/`**: Sistema de power-ups y daños
- **`socket/`**: Eventos y parámetros de comunicación WebSocket
- **`gameTrack/`**: Configuración de pistas y checkpoints
- **`user/`**: Usuarios, roles y permisos
- **`checkpoint/`**: Sistema de checkpoints para carreras

### 📁 `src/constants/`

Constantes compartidas del sistema:

- Estados de karts y juegos
- Nombres de módulos de hardware
- Roles de usuario y permisos
- Medios y efectos de flags

### 📁 `src/data/`

Datos estáticos del juego:

- **`all-power-ups.ts`**: Definición completa de todos los power-ups disponibles
- **`all-damages.ts`**: Efectos de daño y sus impactos
- **`role-definitions.ts`**: Definiciones de roles y permisos

### 📁 `src/utils/`

Utilidades compartidas:

- **`roles.utils.ts`**: Funciones helper para gestión de roles

## Sistema de Juegos

### Tipos de Juego

- **Race**: Carrera tradicional con checkpoints y vueltas
- **Battle**: Modo batalla con power-ups y daños

### Power-ups Disponibles

La librería incluye un sistema completo de power-ups con diferentes niveles:

1. **Battle Nitro** (Nivel 1): Duplica velocidad temporalmente
2. **Battle Trap** (Nivel 2): Lanza trampa que ralentiza oponentes
3. **Battle Shot** (Nivel 3): Dispara proyectil a oponente específico
4. **Battle Blue Shot** (Nivel 4): Daño al primer lugar
5. **Battle Shield** (Nivel 4): Escudo protector contra daños
6. **Battle Pulse** (Nivel 5): Ralentiza a todos los oponentes
7. **Battle God** (Nivel 5): Poder máximo con velocidad, escudo y ataques

## Sistema de Hardware

### Módulos de Hardware por Kart

Cada kart está equipado con múltiples módulos controlados independientemente:

- **Speed Module**: Control de velocidad del motor
- **Screen Module**: Pantalla LCD para información del juego
- **RGB Module**: Iluminación LED RGB
- **Flag Module**: Banderas y señales visuales
- **Sound Module**: Sistema de audio
- **Ball Sensor/Disk Thrower**: Sistema de lanzamiento de discos
- **Disk Sensor/Ball Shooter**: Sistema de disparo de bolas
- **Star Laser**: Láseres frontales y traseros
- **Steering Wheel**: Volante con LED
- **Emergency Module**: Sistema de parada de emergencia

### Estados de Hardware

Cada módulo tiene estados detallados para monitoreo y control en tiempo real.

## Comunicación WebSocket

La librería define eventos WebSocket para comunicación entre componentes:

### Eventos Hardware

- Control de módulos individuales
- Suscripción a datos de hardware
- Configuración de módulos

### Eventos Power-up

- Asignación y activación de power-ups
- Aplicación de daños
- Sincronización de estados

### Eventos de Juego

- Actualizaciones de estado de juego
- Rankings y posiciones
- Eventos de checkpoints

## Sistema de Roles y Permisos

Implementa un sistema de control de acceso con roles jerárquicos:

- **Super Admin**: Control total del sistema
- **Admin**: Gestión de juegos y usuarios
- **Controller**: Control de juegos en ejecución
- **Viewer**: Solo visualización

## Instalación y Uso

```bash
npm install @battle-racing/br-common-lib
```

### Importación de Tipos

```typescript
import { Game, Kart, PowerUp, GameTrack, SocketHardwareModulesEventsParams } from '@battle-racing/br-common-lib';
```

### Uso de Constantes

```typescript
import { gameStatus, FLAG_MEDIA_NAME } from '@battle-racing/br-common-lib';
```

### Acceso a Datos

```typescript
import { allPowerUps, allDamages } from '@battle-racing/br-common-lib';
```

## Desarrollo y Contribución

### Compilación

```bash
npm run build
```

### Publicación

```bash
npm run release:patch  # Para cambios menores
npm run release:minor  # Para nuevas funcionalidades
npm run release:major  # Para cambios breaking
```

### Estructura de Desarrollo

- **TypeScript**: Lenguaje principal
- **ESM**: Módulos ES modernos
- **Strict typing**: Tipado estricto en toda la librería
- **Barrel exports**: Re-exports centralizados para fácil importación