328 lines
15 KiB
Markdown
328 lines
15 KiB
Markdown
# 📋 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.**
|