codigo0/SPEC.md

# 📋 SPEC - Especificación Maestra del Proyecto
## EMERGES TES - Guía Digital de Protocolos de Emergencias

**Última actualización:** 2025-02-02  
**Versión:** 2.1  
**Estado:** Activo - Fuente de Verdad del Proyecto

---

## 🎯 PARTE 1: QUÉ Y POR QUÉ (Antes del Cómo)

### 1.1 ¿Qué es EMERGES TES?

**EMERGES TES** es una **aplicación web progresiva (PWA)** diseñada como herramienta de referencia rápida para **Técnicos de Emergencias Sanitarias (TES)** y profesionales de emergencias médicas.

**No es:**
- ❌ Un sistema de diagnóstico automático
- ❌ Una herramienta de IA que toma decisiones clínicas
- ❌ Un sustituto de la formación reglada del profesional
- ❌ Un reemplazo del criterio clínico

**Sí es:**
- ✅ Un **socio cognitivo** que reduce la carga cognitiva en emergencias
- ✅ Una herramienta de **consulta rápida** (< 2 clics para información crítica)
- ✅ Un sistema **offline-first** que funciona sin conexión
- ✅ Una plataforma de **formación continua** con contenido estructurado

---

### 1.2 ¿Por qué existe este proyecto?

#### Problema que resuelve

**Contexto del usuario (TES en emergencias):**
- Ambiente de **alta presión y estrés**
- Necesidad de información **inmediata** (< 30 segundos)
- Uso frecuente en **condiciones adversas** (móvil, offline, bajo presión)
- Requisito de **precisión absoluta** (errores pueden ser críticos)

**Problemas específicos que aborda:**

1. **Acceso rápido a información crítica**
   - Dosis de fármacos en emergencias
   - Secuencias de protocolos (RCP, Shock, Vía Aérea)
   - Calculadoras médicas (Glasgow, perfusiones, dosis pediátricas)

2. **Reducción de errores humanos**
   - Validación de dosis por edad/peso
   - Recordatorios de pasos críticos
   - Alertas de contraindicaciones

3. **Estandarización de procedimientos**
   - Protocolos basados en guías oficiales (ERC, AHA, SEMES)
   - Consistencia en actuaciones
   - Trazabilidad de decisiones

4. **Formación continua**
   - Manual estructurado navegable
   - Guías formativas asociadas a protocolos
   - Modos de práctica/simulación

---

### 1.3 Principios de Diseño (Por qué así)

#### 1.3.1 Andragogía Clínica y Stress-Ready Design

**Por qué:** Los adultos aprenden mejor cuando el conocimiento tiene relevancia directa y se conecta con experiencia previa. En emergencias, la carga cognitiva debe minimizarse.

**Aplicación:**
- **Orientación al problema:** Estructura por problemas clínicos, no categorías teóricas
- **Autonomía:** Navegación no lineal, acceso directo a secciones críticas
- **Experiencia previa:** Terminología estándar (HL7 FHIR cuando aplique)
- **Procesamiento sensorial:** Jerarquía visual (Lookability), multimodalidad
- **Simulación:** Modos de práctica para transferir habilidades al mundo real

**Referencia:** `docs/ANDRAGOGIA_STRESS_READY_112.md`

#### 1.3.2 Offline-First

**Por qué:** Las emergencias ocurren en zonas rurales o con baja cobertura. La autonomía del profesional no puede depender de conexión a internet.

**Aplicación:**
- Contenido estático embebido en el bundle
- Service Worker para cacheo agresivo
- Funcionalidad completa sin backend (Fase A)

#### 1.3.3 Type Safety y Validación Estricta

**Por qué:** Errores en dosis o protocolos pueden ser críticos. El sistema debe prevenir errores en tiempo de compilación y runtime.

**Aplicación:**
- TypeScript estricto (sin `any`)
- Validación Zod en runtime
- Guard clauses obligatorias en componentes

#### 1.3.4 Clean Architecture (Backend)

**Por qué:** Separación clara de responsabilidades facilita mantenimiento, testing y evolución del sistema.

**Aplicación:**
- Domain Layer aislado (no depende de nadie)
- Application Layer orquesta casos de uso
- Infrastructure Layer maneja detalles técnicos
- Presentation Layer expone API REST

---

### 1.4 Dominios de Negocio Identificados

| Dominio | Entidad Principal | Propósito |
|---------|-------------------|-----------|
| **Protocolos Clínicos** | `Procedure` / `ContentItem` | Secuencias de acciones ordenadas temporalmente para emergencias |
| **Fármacos** | `Drug` | Referencias farmacológicas con dosis, indicaciones, contraindicaciones |
| **Guías de Refuerzo** | `Guide` / `ContentItem` (type: 'guide') | Contenido formativo estructurado en secciones |
| **Herramientas Clínicas** | Checklists, Pathways, Calculadoras | Herramientas interactivas para apoyo a decisiones |
| **Glosario** | `GlossaryTerm` | Términos médicos con definiciones y relaciones |
| **Medios Audiovisuales** | `MediaResource` | Imágenes, videos, documentos asociados a contenido |
| **Contexto Clínico** | `PatientContext`, `Vitals` | Estado del paciente (simulado) para herramientas |

---

## 🏗️ PARTE 2: CÓMO (Arquitectura y Stack)

### 2.1 Stack Tecnológico

#### Frontend
- **Framework:** React 19.2.3 + TypeScript 5.8.3
- **Build Tool:** Vite 7.3.1
- **Routing:** React Router 6.30.1
- **UI:** Tailwind CSS 3.4.17 + shadcn/ui + Radix UI
- **Validación:** Zod 4.3.6
- **Markdown:** react-markdown + remark/rehype
- **PWA:** Service Worker + Manifest
- **Testing:** Vitest 4.0.17 + Testing Library

#### Backend
- **Runtime:** Node.js
- **Framework:** Express 4.18.2 + TypeScript 5.9.3
- **Base de Datos:** PostgreSQL
- **Query Builder:** pg (native)
- **Validación:** Zod 4.3.5
- **Autenticación:** JWT + bcrypt
- **Seguridad:** Helmet + CORS + express-rate-limit
- **Logging:** Winston
- **Cache:** Redis (ioredis)

#### Infraestructura
- **Containerización:** Docker + docker-compose
- **Process Manager:** PM2
- **CI/CD:** GitHub Actions
- **Hosting:** GitHub Pages (frontend) + VPS (backend)

---

### 2.2 Arquitectura

#### Backend: Clean Architecture (Simplificada)

```
┌─────────────────────────────────────────┐
│  PRESENTATION LAYER                      │
│  Routes + Middleware + Validators        │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  APPLICATION LAYER                      │
│  Services (lógica de negocio)           │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  DOMAIN LAYER                           │
│  Entities + Value Objects + Interfaces  │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  INFRASTRUCTURE LAYER                   │
│  Repositories + Database + Storage     │
└─────────────────────────────────────────┘
```

**Estado actual:**
- ✅ Domain Layer bien definido y aislado
- ⚠️ Application Layer existe como `services/` pero no completamente separada
- ⚠️ Infrastructure Layer no tiene carpeta explícita (implementaciones mezcladas)
- ✅ Presentation Layer bien definida

**Objetivo:** Separación completa Application/Infrastructure en carpetas explícitas.

#### Frontend: Arquitectura por Capas Funcional

```
src/
├── pages/          → Route components (Presentation)
├── components/     → UI components (Presentation)
├── hooks/          → Custom hooks (Application logic)
├── services/       → API adapters (Infrastructure)
├── data/           → Static data (Domain-like)
├── clinical/       → Domain logic (calculations, patient)
├── tools/          → Domain tools (checklists, calculators)
├── types/          → Type definitions
├── utils/          → Utilities
└── validators/     → Input validation (Zod)
```

**Estado actual:** Arquitectura funcional orientada a React, no Clean Architecture estricta.

---

### 2.3 Modelo de Datos

#### Entidades Principales

**ContentItem** (Protocolos, Guías, Manuales, Checklists)
- `id`, `type`, `slug`, `level`, `title`, `content` (JSON), `priority`, `status`, `version`

**Drug** (Fármacos)
- `id`, `slug`, `genericName`, `tradeName`, `category`, `adultDose`, `pediatricDose`, `routes`, `indications`, `contraindications`

**GlossaryTerm** (Glosario)
- `id`, `term`, `abbreviation`, `category`, `definition`, `relatedTerms`

**MediaResource** (Medios)
- `id`, `type`, `path`, `fileUrl`, `title`, `tags`, `block`, `chapter`

**Referencia completa:** Ver `backend/src/domain/entities/`

---

### 2.4 Principios Técnicos Consolidados

1. **Value Objects (Híbrido):** Entidades usan tipos simples; Value Objects en servicios para validación
2. **Serialización (Mappers):** Mappers separados en `infrastructure/mappers/`; Domain NO tiene `toJSON`
3. **IDs (Application Layer):** UUIDs generados en Application Layer, pasados a entidades
4. **Validación (Híbrido):** Básicas en Domain (`create()`), complejas en Application Services; Zod en Application
5. **Fechas (ISO 8601 Strings):** `string` con formato ISO 8601, NO `Date` nativo
6. **Arrays (readonly T[]):** `readonly string[]` para arrays inmutables
7. **Opcionales (Híbrido):** `?` para opcionales, `| null` cuando null tiene significado
8. **Errores (Personalizados):** `DomainError`, `ValidationError`, `BusinessRuleError`
9. **Versionado (Números Enteros):** `version: number`, NO semantic versioning
10. **JSONB (Union Types):** Union types para `content`, NO `Record<string, unknown>`

**Referencia completa:** `.cursorrules` (sección "Decisiones Técnicas Consolidadas")

---

### 2.5 Decisiones SDD (Checklist – Fuente de Verdad)

Marco: **Desarrollo Impulsado por Especificaciones (SDD)**. Respuestas consolidadas en `docs/ENTREVISTA_SDD_RESPUESTAS.md`.

| Categoría | Decisión clave | Impacto |
|-----------|----------------|---------|
| **Dominio** | Problema: información correcta e inmediata en emergencias; usuario: TES en escena + admin en panel; reglas puras en BUSINESS_LOGIC.md | Andragogía y stress-ready; reglas estables frente a tecnología |
| **Arquitectura** | Backend: Clean (Domain → Application → Infrastructure → Presentation). Frontend: capas funcional React | Mantenibilidad; aislamiento del dominio en backend |
| **Aislamiento** | Lógica de negocio independiente de framework y BD en backend; frontend con dominio explícito | Menor deuda técnica; tests más claros |
| **Estructura carpetas** | Por tipos técnicos / capas; no Feature-driven | Consistencia con Clean Architecture |
| **Framework** | React 19 + Vite (SPA, CSR). No Next.js 15 ni Angular 2025 | Offline-first; control del bundle y PWA |
| **Renderizado** | CSR (SPA); lazy loading; contenido estático embebido | Rendimiento y uso sin red |
| **Datos** | PostgreSQL (relacional, ACID). Backend propio; no BaaS como núcleo | Integridad y relaciones |
| **Offline-First** | Sí: Service Worker, contenido embebido, IndexedDB para Content Pack | Disponibilidad sin cobertura |
| **Seguridad/Validación** | Zod en todos los puntos de entrada; PII solo en panel (JWT, roles) | Consistencia y seguridad |
| **Gobernanza** | .cursorrules estrictas (no any, readonly, Zod, errores dominio, mappers) | Calidad del código (humano e IA) |
| **TDD** | No obligatorio en legacy; adoptable para flujos críticos nuevos | Reducción deuda de comprensión |

---

## 📊 PARTE 3: ESTADO ACTUAL Y GAPS

### 3.1 Estado de Implementación

| Componente | Estado | Cobertura |
|------------|--------|-----------|
| **Frontend PWA** | ✅ Funcional | Tests en aumento (objetivo: 80%) |
| **Backend API** | ✅ Capas Application/Infrastructure | Tests unitarios (Glossary, Content, Validation) + integración API |
| **Protocolos** | ✅ Completos | 50+ protocolos (categoría Escena vacía; ver contenido faltante) |
| **Fármacos** | ✅ Completos | 100+ fármacos |
| **Guías Formativas** | ✅ Completas | Guías asociadas a protocolos |
| **Herramientas Clínicas** | ✅ Funcionales | Checklists, calculadoras, pathways |
| **Glosario** | ⚠️ Backend completo (API + migración) | Frontend no consume aún `/api/glossary` |
| **Medios** | ✅ Upload mejorado + interfaz gestión | Validación Zod, MediaManagerPage con errores inline |
| **Validación Médica** | ✅ Workflow completo | ValidationService, IValidationRepository, rutas delegadas |

### 3.2 Gaps Identificados

#### Arquitectura
- ✅ Backend: Separación Application/Infrastructure en uso (servicios, repos, ValidationService)
- ⚠️ Frontend: Arquitectura funcional React (no Clean Architecture estricta)

#### Testing
- ✅ Backend: Tests unitarios (GlossaryService, ContentService, ValidationService) y tests integración API
- ⚠️ Frontend: Cobertura en aumento; objetivo 80% documentado

#### Funcionalidades Pendientes
- ⚠️ Glosario: Frontend debe consumir `/api/glossary` (hoy usa datos locales en `pharmaceutical-terminology.ts` si aplica)
- ✅ Medios: Upload e interfaz de gestión implementados
- ✅ Validación Médica: Workflow completo (ValidationService + rutas)

---

## 🎫 PARTE 4: PLAN DE EJECUCIÓN (BACKLOG)

**Documentos de control:** `docs/QUE_FALTA.md`, `docs/BACKLOG_MICRO_TICKETS.md`, `docs/CONTENIDO_FALTANTE.md`

**Fases ya ejecutadas (resumen):**
1. **Fase 1: Fundación y Refactorización** — Schemas Zod, refactor procedures/drugs, http-responses
2. **Fase 2: Glosario** — Schema BD, repositorio, servicio, API, migración frontend→backend
3. **Fase 3: Validación Médica** — ValidationService, IValidationRepository, ContentStatus, rutas
4. **Fase 4: Medios** — Upload mejorado (Zod, safeExtension), interfaz MediaManagerPage
5. **Fase 5: Testing** — Tests backend (servicios + API), tests frontend (hooks, utils, componentes)

**Pendiente de contenido (no técnico):** Ver `docs/CONTENIDO_FALTANTE.md` (protocolos Escena, guías, términos glosario).

---

## 📚 REFERENCIAS

- **Entrevista SDD (respuestas consolidadas):** `docs/ENTREVISTA_SDD_RESPUESTAS.md`
- **Arquitectura:** `.cursorrules`
- **Reglas de negocio puras:** `docs/BUSINESS_LOGIC.md`
- **Andragogía:** `docs/ANDRAGOGIA_STRESS_READY_112.md`
- **Checklist:** `docs/CHECKLIST_ANTES_ACEPTAR_CAMBIOS.md`
- **Auditoría Técnica:** `docs/AUDITORIA_TECNICA_COMPLETA_TECH_LEAD.md`
- **Control Proyecto:** `docs/CONTROL_PROYECTO.md`

---

**Este documento es la fuente de verdad del proyecto. Cualquier decisión arquitectónica o de diseño debe alinearse con este SPEC.**