planetazuzu/codigo0
1
0
Fork 0
Code Issues Pull requests Actions 1 Packages Projects Releases Wiki Activity
codigo0/SPEC.md

15 KiB
Raw Blame History

📋 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.