# 📋 ESPECIFICACIÓN TÉCNICA Y ESTADO DEL SISTEMA (Spec-Driven Development)
**Proyecto:** PULSOCORP - Sistema de Analítica, Monitoreo y Gestión Operativa  
**Base de Datos Objetivo:** `pulsocorp_db` (MySQL)  
**Versión Actual:** `2.0.0` (Módulo de Sedes, Horarios por Turno y Clasificación Dinámica)  
**Estado:** ✅ **Completamente Funcional / Servidor Activo / En Producción Local**  
**Última Actualización:** 2026-08-23  

---

## 1. 🎯 Propósito y Visión del Sistema
PULSOCORP es una plataforma corporativa desarrollada con arquitectura SPA (Single Page Application) y Backend RESTful en Node.js/Express. Su objetivo es centralizar, auditar, clasificar dinámicamente y visualizar en tiempo real más de 237,000 pulsaciones operativas de 35 redes registradas en `contadores`, permitiendo auditar la asistencia por sedes físicas y turnos horarios según el día de la semana sin alterar las tablas legacy protegidas.

---

## 2. 🏛️ Arquitectura y Stack Tecnológico

```
[ Cliente Web (SPA Vanilla JS + Chart.js + CSS Moderno) ]
                         │
                    HTTP / JSON (REST + JWT Bearer)
                         ▼
        [ Servidor Express 5 + Middlewares ]
          ├── Morgan (Logging)
          ├── CORS
          ├── JWT Auth & Role Middleware
          └── Static File Serving (public/)
                         │
             mysql2/promise Pool (15 conn limit)
                         ▼
            [ MySQL: pulsocorp_db ]
          ├── [PROTEGIDA] usuarios (id, nombre, email, PASSWORD, rol...)
          ├── [PROTEGIDA] contadores (id, nombre, contador, ultima_pulsacion) -> REDES
          ├── [PROTEGIDA] pulsaciones (id, nombre_persona, fecha_hora, ip_usuario, user_agent)
          ├── [NUEVA] sedes (id, nombre, direccion, activo, fecha_creacion)
          ├── [NUEVA] horarios_sede (id, sede_id, dia_semana, nombre_turno, hora_inicio, hora_fin, activo)
          ├── [NUEVA] redes (id, nombre, descripcion, activo)
          ├── [NUEVA] sedes_red (id, red_id, contador_id, sede_id)
          └── [NUEVA] schema_migrations (id, version, nombre, aplicada_en)
```

---

## 3. 🗄️ Modelo de Datos y Esquemas

### 3.1 Tablas Legacy y Protegidas
* **`usuarios`**: Cuentas de acceso con roles (`admin`, `usuario`).
* **`contadores`**: Representan las 35 Redes de liderazgo (`ASENCIOS`, `CERVANTES`, `BARBA`, etc.).
* **`pulsaciones`**: Registro histórico y en tiempo real de marcaciones. `nombre_persona` almacena la Red de la persona.

### 3.2 Nuevas Tablas Operativas
* **`sedes`**: Locales físicos y auditorios de recepción.
* **`horarios_sede`**: Configuración de turnos horarios por sede física y día de la semana (0=Domingo a 6=Sábado).
* **`schema_migrations`**: Registro y trazabilidad de versiones de base de datos.

---

## 4. 🔌 Catálogo de Endpoints REST

### 4.1 Sedes Físicas (`/api/sedes`)
* `GET /api/sedes`: Listado de sedes con total de horarios configurados.
* `GET /api/sedes/:id`: Detalle de sede con sus horarios.
* `POST /api/sedes`: Crear sede física (Admin).
* `PUT /api/sedes/:id`: Modificar sede física (Admin).
* `DELETE /api/sedes/:id`: Eliminar sede física (Admin).

### 4.2 Horarios por Sede (`/api/horarios`, `/api/sedes/:id/horarios`)
* `GET /api/sedes/:id/horarios`: Horarios de una sede ordenados por día y hora.
* `POST /api/sedes/:id/horarios`: Crear turno con validación de no solapamiento y `hora_inicio < hora_fin` (Admin).
* `PUT /api/horarios/:id`: Actualizar turno con validación de colisión (Admin).
* `DELETE /api/horarios/:id`: Eliminar turno (Admin).

### 4.3 Reportes Analíticos (`/api/reports`)
* `GET /api/reports/horarios`: Clasifica pulsaciones dinámicamente según la sede evaluada y sus turnos (`Dentro de turno (Turno X)`, `Fuera de horario`, `Sin horario configurado`).
* `GET /api/reports/redes`: Consolidado general de redes con ranking y % de participación.
* `GET /api/reports/fuera-horario`: Detección de anomalías y marcaciones fuera de turnos.
* `GET /api/reports/export/csv`: Exportación de reportes de horarios y redes a formato CSV UTF-8 con BOM.

### 4.4 Autenticación & Dashboard General
* `/api/auth/*`: Login, perfil y CRUD de usuarios.
* `/api/kpis`, `/api/analytics/*`, `/api/pulsaciones`: Métricas globales y bitácora.

---

## 5. 🛡️ Sistema de Integridad y Seguridad de Migraciones
Ubicado en `scripts/`:
* `database-protection.js`: Detector de SQL peligroso sobre tablas legacy.
* `migration-safety-check.js`: Generador de baselines con hashes SHA-256 por lotes.
* `migration.js`: Ejecutor con soporte para `--dry-run` y `--apply`.
* `verify-integrity.js`: Comparador de baselines antes y después.

---

## 6. 🧪 Pruebas Automatizadas
Ubicadas en `tests/test-suite.js`:
* Creación y gestión de sedes.
* Configuración de turnos en domingo.
* Rechazo de horarios solapados y formatos inválidos.
* Clasificación dinámica en reportes y exportación CSV.

Para ejecutar la suite de pruebas:
```bash
node tests/test-suite.js
```