Clínica — Sistema de Gestión Hospitalaria

Sistema de microservicios para gestionar una clínica de salud — pacientes, citas, admisiones y facturación con autenticación JWT, migraciones automáticas y asistente médico con IA.

  • Java 21
  • Spring
  • Microservices
  • PostgreSQL
  • Redis
  • Docker
  • JWT
GitHub ↗ DeepWiki ↗

Problema

Las clínicas pequeñas y medianas suelen depender de hojas de cálculo o sistemas legacy para manejar citas, expedientes y facturación. El objetivo era construir una plataforma moderna que centralizara todas las operaciones clínicas con seguridad enterprise y escalabilidad real.

Solución

Sistema modular de microservicios donde cada dominio (pacientes, citas, admisiones, facturación, proveedores) corre como servicio independiente. Todos se registran en Eureka para descubrimiento dinámico. Autenticación centralizada con JWT firmado con RSA-256. Asistente médico integrado vía Gemini AI para consultas de soporte.

Arquitectura

  • Eureka Service Discovery — los servicios se registran automáticamente; sin configuración manual de IPs
  • JWT con RSA-256 — token firmado asimétricamente; el servicio de auth emite, cada microservicio valida sin base de datos
  • Multi-database — PostgreSQL para datos transaccionales críticos, MySQL donde el esquema lo justifica; Flyway para migraciones versionadas en ambos
  • Docker Compose — levanta el stack completo (servicios + bases de datos + Eureka dashboard) con un solo comando
  • Spring AI + Gemini — asistente integrado directamente en el flujo de consultas médicas
Cl
Clínica · Sistema de Gestión Hospitalaria
Java 21 · Spring Boot 3.5 · Spring Cloud 2025 · 8 microservicios
▶ Pruébalo — arrastra nodos · click para inspeccionar
externogatewayserviciosIAinfra
HTTPS / JWTverificamédicocoberturafacturaintent →registerClientes ExternosBrowser · Apps · IntegracionesAPI GatewaySpring Cloud Gateway 4.3 · :8080LoggingFilterRateLimitFilter (Redis)AuthFilter JWT RSA-256CircuitBreakerRetryAuth ServiceJWT RSA-256 · :8084 · MySQLPatient ServicePacientes · :8082 · MySQLAdmissions ServiceAtenciones · :8083 · PostgreSQLSuppliers ServiceMédicos · :8085 · MySQLClients ServiceAseguradoras · :8086 · MySQLAI AssistantGemini · Spring AI · :8087 · PGGeminiClientIntent DetectionBilling ServiceFacturación · :8088 · MySQLEureka ServerService Discovery · :8761
cada barra representa un ciclo completo: cliente → gateway → servicio → respuesta
Diagrama de Clínica — Sistema de Gestión Hospitalaria

Decisiones técnicas

Se usó RSA-256 en lugar de HMAC-SHA para JWT porque en arquitectura de microservicios cada servicio solo necesita la clave pública para verificar — sin compartir secretos. Flyway sobre scripts manuales porque en un sistema de salud la trazabilidad de cambios de esquema es un requisito de auditoría.

DOCUMENTACIÓN

Arquitectura Técnica — Clínica

Versión: 1.0
Stack: Java 21 · Spring Boot 3.5 · Spring Cloud 2025.0
Dominio: Gestión hospitalaria — pacientes, admisiones, proveedores, facturación, autenticación, IA

1. Contexto del Problema

Las clínicas medianas operan con múltiples dominios que cambian a ritmos distintos: el registro de pacientes no tiene el mismo ciclo de actualización que la facturación o la gestión de turnos médicos. Unificar todo en un monolito crea acoplamiento innecesario y bloquea el despliegue independiente de cambios críticos.

Adicionalmente, un sistema de salud tiene requisitos no negociables:

  • Auditoría completa — cada cambio en un expediente clínico debe quedar registrado con usuario, fecha y acción.
  • Eliminación segura — los datos médicos no se borran físicamente; se marcan como inactivos con trazabilidad.
  • Seguridad robusta — credenciales en tránsito, tokens de corta vida, bloqueo por intentos fallidos, RBAC por rol profesional.
  • Disponibilidad ante fallos parciales — si el servicio de facturación cae, las admisiones deben seguir funcionando.

2. Visión General del Sistema

                         ┌─────────────────────────────────┐
                         │        Clientes Externos        │
                         │   Browser · Apps · Integraciones│
                         └─────────────┬───────────────────┘
                                       │ HTTPS / JWT
                                       ▼
                    ┌──────────────────────────────────────┐
                    │           API Gateway                │
                    │   Spring Cloud Gateway 4.3           │
                    │  ┌──────────┬──────────┬──────────┐  │
                    │  │ Logging  │Rate Limit│ Retry    │  │
                    │  │ Routing  │  Redis   │Circuit   │  │
                    │  └──────────┴──────────┴──────────┘  │
                    └────┬──────┬──────┬──────┬─────────┬──┘
                         │      │      │      │         │
              ┌──────────┘ ┌────┘      │      └────┐    └──────┐
              ▼            ▼           ▼           ▼           ▼
        ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐ ┌─────────┐
        │ Patient  │ │Admissions│ │ Auth   │ │Suppliers │ │ Clients │
        │ Service  │ │ Service  │ │Service │ │ Service  │ │ Service │
        │  MySQL   │ │PostgreSQL│ │ MySQL  │ │  MySQL   │ │  MySQL  │
        └──────────┘ └──────────┘ └────────┘ └──────────┘ └─────────┘
              │                        │
              ▼                        ▼
        ┌──────────┐           ┌───────────────┐
        │AI Assist │           │ Eureka Server │
        │PostgreSQL│           │   Discovery   │
        └──────────┘           └───────────────┘
                                       ▲
                        Todos los servicios se registran aquí

3. Stack Tecnológico

Capa Tecnología Justificación
Runtime Java 21 Soporte LTS, records, sealed classes, pattern matching
Framework Spring Boot 3.5 + Spring Cloud 2025 Ecosistema maduro para microservicios; auto-configuración, actuator, seguridad
API Gateway Spring Cloud Gateway 4.3 Reactivo (WebFlux); rate limiting, logging y circuit breaker sin código custom
Service Discovery Netflix Eureka Registro dinámico; los servicios se localizan por nombre, no por IP
Seguridad Spring Security 6 + JWT RSA-256 Tokens asimétricos: Auth emite con clave privada, cada servicio valida con pública
Bases de datos MySQL 8 · PostgreSQL 16 MySQL para dominios relacionales simples; PostgreSQL para datos transaccionales
Migraciones Flyway Historial versionado de esquema; obligatorio en sistemas de salud (auditoría)
ORM Hibernate + MapStruct 1.6 JPA estándar; MapStruct genera el código de mapping en compile time (zero reflect)
Resiliencia Resilience4j Circuit breaker, retry con backoff exponencial, fallback declarativo
Cache / Rate Limit Redis 7 Cache distribuida + token bucket para rate limiting en el gateway
IA Spring AI + Gemini API Abstracción portable (Gemini en prod, LM Studio en local)
Contenedores Docker + Compose Stack completo levantable con un solo comando
Testing JUnit 5 + Mockito Pruebas unitarias de servicios, controladores e integraciones
Build Maven multi-módulo Un POM padre gestiona versiones de dependencias para todos los servicios

4. Microservicios — Responsabilidades

4.1 Patient Service (:8082)

Propietario del dominio clínico del paciente.

PatientController
    └── PatientService
          ├── PatientRepository          → Tabla patients (MySQL)
          ├── AllergyRepository          → Tabla allergies
          ├── ChronicDiseaseRepository   → Tabla chronic_diseases
          ├── MedicationRepository       → Tabla current_medications
          ├── FamilyHistoryRepository    → Tabla family_histories
          └── VaccinationRepository      → Tabla vaccination_records

Entidades principales:

Entidad Descripción
Patient Datos demográficos: UUID, tipo/número de identificación, DOB, género, contacto, afiliación
MedicalHistory Historia clínica general del paciente
Allergy Alergias con nivel de severidad
ChronicDisease Enfermedades crónicas diagnosticadas
CurrentMedication Medicamentos activos con dosis y frecuencia
FamilyHistory Antecedentes familiares relevantes
VaccinationRecord Registro de vacunas aplicadas

Soft delete: deleted_at + deleted_by en todas las tablas — los registros nunca se eliminan físicamente.

4.2 Admissions Service (:8083)

Gestiona el ciclo de vida completo de una atención médica.

AttentionController
    └── AttentionService
          ├── AttentionRepository        → Tabla attentions (PostgreSQL)
          ├── AttentionMovementRepository
          ├── AttentionUserHistoryRepository
          └── AuthorizationRepository

Estado de una atención:

[Paciente llega]
      │
      ▼
  CREATED ──────────────────► CANCELLED
      │
      ▼
 IN_PROGRESS
      │
      ├── (facturación validada)
      │
      ▼
 DISCHARGED

Niveles de triage:

Color Prioridad Descripción
RED 1 Emergencia crítica — atención inmediata
ORANGE 2 Emergencia urgente
YELLOW 3 Urgencia moderada
GREEN 4 No urgente
BLUE 5 Consulta rutinaria

4.3 Auth Service (:8084)

Autenticación centralizada. Emite tokens JWT firmados con RSA-256.

AuthController
    ├── AuthenticationService  → Login, logout, refresh token
    ├── UserService            → Registro, cambio de contraseña, bloqueo
    ├── PasswordResetService   → Flujo de reset por token
    └── AuditService           → Registro de todos los eventos de acceso

4.4 Suppliers Service (:8085)

Gestión del personal médico y sus disponibilidades.

DoctorController
    └── DoctorService
          ├── DoctorRepository       → Tabla doctors
          ├── ScheduleRepository     → Tabla doctor_schedules
          └── UnavailabilityRepository → Tabla doctor_unavailability

4.5 Clients Service (:8086)

Proveedores de salud: aseguradoras, EPS, redes de clínicas.

HealthProviderController
    └── HealthProviderService
          ├── HealthProviderRepository → Tabla health_providers
          ├── ContractRepository       → Tabla contracts
          └── PortfolioRepository      → Tabla portfolios

4.6 AI Assistant Service (:8087)

Asistente conversacional con memoria de sesión e integración con el flujo de admisiones.

AIAssistantController
    └── AIAssistantService
          ├── GeminiClient (Spring AI)  → Llamadas a la API de Gemini
          ├── ConversationRepository    → Tabla conversation_history
          └── MessageRepository         → Tabla conversation_messages

El asistente detecta intención en la conversación: si el médico describe síntomas de un paciente, puede iniciar automáticamente la creación de una atención llamando al Admissions Service internamente.

4.7 API Gateway (:8080)

Punto de entrada único para todo el tráfico externo.

Filtros de entrada:
  LoggingFilter   → Registra cada request (método, path, status, tiempo) en PostgreSQL
  RateLimitFilter → Token bucket por usuario en Redis: max N req/seg
  AuthFilter      → Valida JWT (clave pública RSA-256) antes de enrutar

Por cada ruta configurada:
  Resilience4j:
    CircuitBreaker → Abre después de X fallos consecutivos
    Retry          → Backoff exponencial, máx 3 intentos
    TimeLimiter    → Timeout por request

5. Service Discovery — Eureka

Arranque de un microservicio:
  1. Spring Cloud Eureka Client se activa
  2. Servicio publica: { serviceId, host, port, status: UP }
  3. Eureka mantiene heartbeat cada 30s; si falla → marca DOWN
  4. API Gateway consulta el registro para resolver rutas

Sin Eureka: cada servicio necesitaría IPs hardcodeadas
Con Eureka: el gateway resuelve "PATIENT-SERVICE" → IP actual dinámicamente

Beneficio en Docker Compose: al reiniciar un contenedor con nueva IP, Eureka lo re-registra automáticamente. Ninguna configuración cambia.

6. Estrategia de Base de Datos

Cada servicio es dueño exclusivo de su base de datos. No hay JOINs entre servicios.

Servicio Motor Justificación
Patient MySQL 8 Esquema relacional estable, buena integración con Hibernate
Admissions PostgreSQL Enums nativos para triage y estados; mejor soporte para audit triggers
Auth MySQL 8 Tablas de usuarios con índices en email y username
Suppliers MySQL 8 Relaciones médico ↔ especialidad
Clients MySQL 8 Datos de proveedores y contratos
AI Assistant PostgreSQL JSONB para almacenar mensajes con metadata flexible
API Gateway PostgreSQL Logs de analytics: volumen alto de escritura, queries de agregación

Flyway: cada servicio tiene su carpeta db/migration/ con archivos V{n}__{descripcion}.sql. Las migraciones corren automáticamente al arrancar el servicio.

7. Patrones de Resiliencia

7.1 Circuit Breaker

Estado CLOSED (normal):
  Requests pasan al servicio destino

Estado OPEN (servicio caído):
  Se activa cuando la tasa de fallos > umbral configurado
  Las requests fallan rápido → no esperan timeout
  Se llama el método @Fallback

Estado HALF-OPEN (recuperación):
  Permite algunas requests de prueba
  Si tienen éxito → vuelve a CLOSED
  Si fallan → vuelve a OPEN

7.2 Retry con Backoff Exponencial

Intento 1 → falla
Espera 500ms
Intento 2 → falla
Espera 1000ms
Intento 3 → falla
→ Fallback o error al cliente

7.3 Rate Limiting (Redis)

Por cada request que llega al gateway:
  1. Obtiene userId del JWT
  2. Consulta en Redis: tokens_disponibles[userId]
  3. Si tokens > 0 → decrementa y permite
  4. Si tokens = 0 → 429 Too Many Requests
  5. Redis recarga tokens a tasa configurable (token bucket)

8. Asistente IA — Integración

Cliente              AI Service            Admissions Service
   │                     │                        │
   │ POST /chat          │                        │
   │ {"message":"..."}   │                        │
   │─────────────────►   │                        │
   │                     │ Gemini API             │
   │                     │ (Spring AI)            │
   │                     │ ─────────────►         │
   │                     │ ◄─────────────         │
   │                     │                        │
   │                     │ (detecta intención)    │
   │                     │ POST /api/v1/attentions│
   │                     │ ───────────────────►   │
   │                     │ ◄───────────────────   │
   │                     │                        │
   │ ◄─────────────────  │                        │
   │ respuesta + acción  │                        │

Spring AI actúa como capa de abstracción: cambiando la configuración se puede apuntar a Gemini (producción) o a LM Studio (desarrollo local sin costos de API).

9. Decisiones de Diseño Clave

9.1 JWT con RSA-256 en lugar de HMAC-SHA

Decisión: Auth Service firma tokens con una clave privada RSA. Cada microservicio solo tiene la clave pública para verificar.
Por qué: en arquitectura de microservicios con HMAC, todos los servicios necesitarían la misma clave secreta — un secreto compartido entre N servicios es una superficie de ataque N veces mayor. Con RSA asimétrico, comprometer un microservicio no expone la capacidad de emitir tokens.

9.2 Flyway sobre scripts manuales

Decisión: todas las migraciones de esquema son archivos Flyway versionados.
Por qué: en un sistema de salud, los cambios de esquema son auditables por regulación. Flyway garantiza que la versión del esquema en producción es exactamente reproducible y no puede aplicarse en orden incorrecto.

9.3 Soft Deletes en todos los dominios

Decisión: ninguna entidad del sistema se elimina con DELETE SQL.
Por qué: los expedientes médicos tienen valor legal. La capacidad de restaurar un registro "eliminado" es un requisito de cumplimiento. El campo deleted_at permite filtrar lógicamente sin perder el dato.

9.4 MapStruct sobre ModelMapper o conversión manual

Decisión: MapStruct genera el código de mapping entre entidades y DTOs en tiempo de compilación.
Por qué: ModelMapper usa reflection en runtime (lento, difícil de debuggear). Mapping manual es verbose y propenso a errores al agregar campos. MapStruct: sin reflection, error de compilación si falta un campo mapeado, tan rápido como código manual.

9.5 Un base de datos por servicio

Decisión: no hay tablas compartidas entre microservicios. Las referencias cruzadas se hacen por ID.
Por qué: el acoplamiento a nivel de esquema es la forma más peligrosa de acoplamiento en microservicios — un cambio de columna en la tabla de pacientes rompe todos los servicios que hacen JOIN directamente. Con bases de datos independientes, cada servicio evoluciona su esquema de forma autónoma.

10. Estructura del Proyecto

Clinica/
├── BackEnd-Clinica/
│   ├── pom.xml                         # POM padre — gestión de dependencias
│   ├── docker-compose.yml              # Stack completo
│   ├── .env                            # Variables de entorno
│   ├── eureka-service/                 # Registro de servicios
│   ├── api-gateway/                    # Gateway + rate limiting + analytics
│   ├── auth-service/                   # JWT, usuarios, roles
│   │   └── src/main/java/.../
│   │       ├── module/entity/          # User, Role, RefreshToken, AuditLog
│   │       ├── module/service/         # Auth, User, PasswordReset
│   │       └── module/controller/      # AuthController
│   ├── patient-service/                # Pacientes y expedientes
│   ├── admissions-service/             # Atenciones, triage, autorizaciones
│   ├── suppliers-service/              # Médicos, especialidades, horarios
│   ├── clients-service/                # Aseguradoras, contratos
│   ├── ai-assistant-service/           # Chat con Gemini / LM Studio
│   └── billing-service/                # Facturación (en desarrollo)
├── FrontEnd-Clinica/                   # Astro 6 (en desarrollo)
└── docs/                               # Este documento y referencia de API

Documento mantenido junto al código — si la arquitectura cambia, actualizar esta descripción.

Referencia de API REST — Clínica

Versión: 1.0
Base URL: http://localhost:8080 (API Gateway)
Autenticación: Bearer JWT (RSA-256) en header Authorization

Convenciones

  • Todos los endpoints requieren Authorization: Bearer <token> salvo los de autenticación.
  • Las respuestas exitosas devuelven 2xx; los errores siguen el formato estándar de Spring.
  • Los UUIDs se expresan como strings en formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
  • Los timestamps usan ISO 8601: 2025-05-19T14:30:00.
  • Soft delete: los registros eliminados tienen deletedAt no nulo y no aparecen en listados normales.

1. Auth Service — /api/v1/auth

POST /login

Autentica un usuario y devuelve access token + refresh token.

Request:

{
  "username": "dr.martinez",
  "password": "SecurePass123!"
}

Response 200 OK:

{
  "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
  "refreshToken": "d4f8a2b1-...",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "user": {
    "id": "a1b2c3d4-...",
    "username": "dr.martinez",
    "email": "martinez@clinica.com",
    "roles": ["ROLE_DOCTOR"]
  }
}

Errores:

Código Causa
401 Credenciales inválidas
423 Cuenta bloqueada por intentos fallidos

POST /refresh

Renueva el access token usando el refresh token.

Request:

{
  "refreshToken": "d4f8a2b1-..."
}

Response 200 OK:

{
  "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
  "expiresIn": 900
}

POST /logout

Invalida el refresh token actual.

Request:

{
  "refreshToken": "d4f8a2b1-..."
}

Response 204 No Content

POST /password-reset/request

Inicia el flujo de restablecimiento de contraseña.

Request:

{
  "email": "martinez@clinica.com"
}

Response 200 OK:

{
  "message": "Si el correo existe, recibirá instrucciones de restablecimiento."
}

POST /password-reset/confirm

Establece la nueva contraseña usando el token recibido.

Request:

{
  "token": "abc123-reset-token",
  "newPassword": "NuevaContraseña456!"
}

Response 200 OK:

{
  "message": "Contraseña actualizada correctamente."
}

2. Patient Service — /api/v1/patients

GET /

Lista todos los pacientes activos con paginación.

Query params:

Param Tipo Default Descripción
page integer 0 Número de página
size integer 20 Elementos por página
sort string lastName,asc Campo y dirección

Response 200 OK:

{
  "content": [
    {
      "id": "p1a2b3c4-...",
      "identificationNumber": "1234567890",
      "identificationType": "CC",
      "firstName": "Carlos",
      "lastName": "Rodríguez",
      "dateOfBirth": "1985-03-15",
      "gender": "MALE",
      "phone": "+57 310 555 0101",
      "email": "c.rodriguez@email.com",
      "insuranceAffiliation": "EPS Sura",
      "createdAt": "2025-01-10T09:00:00"
    }
  ],
  "totalElements": 142,
  "totalPages": 8,
  "size": 20,
  "number": 0
}

POST /

Registra un nuevo paciente.

Request:

{
  "identificationNumber": "9876543210",
  "identificationType": "CC",
  "firstName": "María",
  "lastName": "González",
  "dateOfBirth": "1990-07-22",
  "gender": "FEMALE",
  "phone": "+57 311 555 0202",
  "email": "m.gonzalez@email.com",
  "address": "Calle 45 # 12-34, Bogotá",
  "insuranceAffiliation": "EPS Sanitas"
}

Response 201 Created:

{
  "id": "p9z8y7x6-...",
  "identificationNumber": "9876543210",
  "firstName": "María",
  "lastName": "González",
  "createdAt": "2025-05-19T10:15:00"
}

GET /{id}

Retorna el perfil completo de un paciente con toda su historia clínica.

Response 200 OK:

{
  "id": "p1a2b3c4-...",
  "firstName": "Carlos",
  "lastName": "Rodríguez",
  "dateOfBirth": "1985-03-15",
  "gender": "MALE",
  "medicalHistory": {
    "bloodType": "O+",
    "notes": "Paciente con historial de alergias estacionales."
  },
  "allergies": [
    {
      "id": "al001",
      "substance": "Penicilina",
      "severity": "HIGH",
      "reaction": "Anafilaxia"
    }
  ],
  "chronicDiseases": [
    {
      "id": "cd001",
      "name": "Hipertensión arterial",
      "diagnosedAt": "2018-06-01"
    }
  ],
  "currentMedications": [
    {
      "id": "med001",
      "name": "Losartán",
      "dosage": "50mg",
      "frequency": "Once daily"
    }
  ],
  "vaccinationRecords": [
    {
      "id": "vac001",
      "vaccine": "COVID-19 — Pfizer",
      "appliedAt": "2021-04-15",
      "nextDoseAt": "2021-05-06"
    }
  ]
}

PUT /{id}

Actualiza los datos demográficos de un paciente.

Request: (campos a modificar)

{
  "phone": "+57 310 555 9999",
  "address": "Carrera 7 # 80-15, Bogotá"
}

Response 200 OK: paciente actualizado

DELETE /{id}

Soft delete del paciente (marca deletedAt).

Response 204 No Content

POST /{id}/allergies

Agrega una alergia al historial del paciente.

Request:

{
  "substance": "Ibuprofeno",
  "severity": "MEDIUM",
  "reaction": "Urticaria"
}

Response 201 Created

POST /{id}/vaccinations

Registra una vacuna aplicada.

Request:

{
  "vaccine": "Influenza estacional",
  "appliedAt": "2025-03-10",
  "nextDoseAt": "2026-03-10",
  "appliedBy": "Dr. Pérez"
}

Response 201 Created

3. Admissions Service — /api/v1/attentions

GET /

Lista atenciones con filtros opcionales.

Query params:

Param Tipo Descripción
status string CREATED, IN_PROGRESS, DISCHARGED, CANCELLED
triage string RED, ORANGE, YELLOW, GREEN, BLUE
date string Fecha en formato YYYY-MM-DD
doctorId UUID Filtrar por médico asignado

Response 200 OK:

{
  "content": [
    {
      "id": "att001-...",
      "patientId": "p1a2b3c4-...",
      "patientName": "Carlos Rodríguez",
      "triageLevel": "YELLOW",
      "status": "IN_PROGRESS",
      "assignedDoctorId": "doc001-...",
      "createdAt": "2025-05-19T08:30:00"
    }
  ],
  "totalElements": 18
}

POST /

Crea una nueva atención médica.

Request:

{
  "patientId": "p1a2b3c4-...",
  "triageLevel": "ORANGE",
  "reason": "Dolor torácico agudo con irradiación al brazo izquierdo",
  "assignedDoctorId": "doc001-...",
  "authorizationCode": "EPS-2025-001234"
}

Response 201 Created:

{
  "id": "att999-...",
  "status": "CREATED",
  "triageLevel": "ORANGE",
  "createdAt": "2025-05-19T14:22:00"
}

GET /{id}

Retorna los detalles completos de una atención.

Response 200 OK:

{
  "id": "att001-...",
  "patientId": "p1a2b3c4-...",
  "triageLevel": "YELLOW",
  "status": "IN_PROGRESS",
  "reason": "Fiebre alta y tos seca",
  "assignedDoctorId": "doc001-...",
  "movements": [
    {
      "id": "mov001",
      "fromStatus": "CREATED",
      "toStatus": "IN_PROGRESS",
      "performedBy": "dr.martinez",
      "timestamp": "2025-05-19T09:05:00"
    }
  ],
  "authorization": {
    "code": "EPS-2025-001234",
    "status": "APPROVED",
    "provider": "EPS Sura"
  }
}

PATCH /{id}/status

Cambia el estado de una atención.

Request:

{
  "newStatus": "DISCHARGED",
  "notes": "Paciente estabilizado, alta con prescripción."
}

Response 200 OK

Transiciones válidas:

Estado actual Estados destino válidos
CREATED IN_PROGRESS, CANCELLED
IN_PROGRESS DISCHARGED, CANCELLED
DISCHARGED (estado final)
CANCELLED (estado final)

4. Suppliers Service — /api/v1/doctors

GET /

Lista médicos activos con su especialidad.

Response 200 OK:

{
  "content": [
    {
      "id": "doc001-...",
      "firstName": "Ana",
      "lastName": "Martínez",
      "specialty": "Cardiología",
      "licenseNumber": "RM-12345",
      "email": "a.martinez@clinica.com",
      "status": "ACTIVE"
    }
  ]
}

GET /{id}/schedule

Retorna el horario semanal del médico.

Response 200 OK:

{
  "doctorId": "doc001-...",
  "schedule": [
    {
      "dayOfWeek": "MONDAY",
      "startTime": "08:00",
      "endTime": "14:00"
    },
    {
      "dayOfWeek": "WEDNESDAY",
      "startTime": "14:00",
      "endTime": "20:00"
    }
  ]
}

POST /{id}/unavailability

Registra un período de no disponibilidad (vacaciones, incapacidad, etc.).

Request:

{
  "reason": "Vacaciones",
  "startDate": "2025-07-01",
  "endDate": "2025-07-15"
}

Response 201 Created

5. Clients Service — /api/v1/health-providers

GET /

Lista todos los proveedores de salud (aseguradoras, EPS).

Response 200 OK:

{
  "content": [
    {
      "id": "hp001-...",
      "name": "EPS Sura",
      "nit": "890903790-1",
      "type": "EPS",
      "contactEmail": "contratos@sura.com.co",
      "status": "ACTIVE"
    }
  ]
}

GET /{id}/contracts

Retorna los contratos activos con un proveedor.

Response 200 OK:

{
  "providerId": "hp001-...",
  "contracts": [
    {
      "id": "con001-...",
      "number": "CLN-2025-001",
      "startDate": "2025-01-01",
      "endDate": "2025-12-31",
      "coverageType": "FULL",
      "status": "ACTIVE"
    }
  ]
}

6. AI Assistant Service — /api/v1/ai

POST /chat

Envía un mensaje al asistente y recibe respuesta con posibles acciones ejecutadas.

Request:

{
  "sessionId": "session-abc123",
  "message": "El paciente Carlos Rodríguez, CC 1234567890, llega con dolor torácico severo, necesito registrar atención urgente nivel ROJO"
}

Response 200 OK:

{
  "sessionId": "session-abc123",
  "reply": "He registrado la atención de urgencia para Carlos Rodríguez (CC 1234567890) con triage RED. ID de atención: att999-...",
  "actionsPerformed": [
    {
      "type": "CREATE_ATTENTION",
      "attentionId": "att999-...",
      "triageLevel": "RED",
      "patientId": "p1a2b3c4-..."
    }
  ],
  "timestamp": "2025-05-19T14:22:05"
}

GET /conversations/{sessionId}

Retorna el historial de una sesión de conversación.

Response 200 OK:

{
  "sessionId": "session-abc123",
  "messages": [
    {
      "role": "USER",
      "content": "El paciente Carlos Rodríguez...",
      "timestamp": "2025-05-19T14:22:00"
    },
    {
      "role": "ASSISTANT",
      "content": "He registrado la atención de urgencia...",
      "timestamp": "2025-05-19T14:22:05"
    }
  ]
}

7. Códigos de Error Comunes

Código Significado
400 Solicitud malformada o datos de validación inválidos
401 Token ausente, expirado o firma inválida
403 El rol del usuario no tiene permiso para este recurso
404 Recurso no encontrado
409 Conflicto de estado (ej. transición de estado inválida)
422 Entidad no procesable (regla de negocio violada)
429 Rate limit excedido — demasiadas solicitudes
500 Error interno del servidor
503 Servicio no disponible (circuit breaker abierto)

Formato de error estándar:

{
  "timestamp": "2025-05-19T14:30:00",
  "status": 422,
  "error": "Unprocessable Entity",
  "message": "No se puede dar de alta una atención CANCELLED.",
  "path": "/api/v1/attentions/att001-..."
}

Documentación mantenida junto al código — los ejemplos reflejan el comportamiento actual de la API.

Seguridad — Clínica

Versión: 1.0
Stack: Spring Security 6 · JWT RSA-256 · Redis · Resilience4j

1. Modelo de Seguridad

El sistema implementa múltiples capas de seguridad que operan de forma independiente. El fallo de una capa no compromete las demás.

Cliente
  │
  ▼
[1] TLS / HTTPS ────────── cifrado en tránsito
  │
  ▼
[2] Rate Limiting ─────── protección contra fuerza bruta / DoS
  │
  ▼
[3] JWT Validation ─────── identidad y roles verificados
  │
  ▼
[4] RBAC ──────────────── autorización por rol
  │
  ▼
Microservicio
  │
  ▼
[5] Audit Log ──────────── trazabilidad completa

2. Autenticación — JWT RSA-256

2.1 Arquitectura Asimétrica

Auth Service                    Microservicios
     │                               │
     │  Tiene:                       │  Tienen:
     │  ┌─────────────────┐          │  ┌─────────────────┐
     │  │ Clave privada   │          │  │ Clave pública   │
     │  │ (firma tokens)  │          │  │ (verifica firma)│
     │  └─────────────────┘          │  └─────────────────┘
     │                               │
     │  JWT firmado                  │
     │ ──────────────────────────►   │
     │                               │  ¿Firma válida? → permitir

Ventaja de seguridad: si un microservicio es comprometido, el atacante solo obtiene la clave pública — no puede emitir tokens nuevos. Solo el Auth Service puede firmar.

2.2 Estructura del Token

Header:
{
  "alg": "RS256",
  "typ": "JWT"
}

Payload:
{
  "sub": "a1b2c3d4-...",          // userId (UUID)
  "username": "dr.martinez",
  "roles": ["ROLE_DOCTOR"],
  "iat": 1716134400,              // issued at
  "exp": 1716135300               // expires at (15 min)
}

Signature:
  RSA-SHA256(base64(header) + "." + base64(payload), privateKey)

2.3 Tiempos de Vida

Token Duración Renovable
Access token 15 min Sí, con refresh token
Refresh token 7 días No — requiere login nuevo al expirar

Los access tokens de corta vida limitan la ventana de exposición si un token es interceptado.

2.4 Flujo de Autenticación

[1] Cliente → POST /api/v1/auth/login
      {username, password}

[2] Auth Service:
      · Busca usuario por username
      · Verifica BCrypt(password, hash_almacenado)
      · Si OK: genera access token (RSA-256) + refresh token UUID
      · Guarda refresh token en base de datos (hasheado)
      · Registra evento en AuditLog

[3] Respuesta:
      {accessToken, refreshToken, expiresIn: 900}

[4] Cliente guarda tokens (seguro, no en localStorage)

[5] Requests subsecuentes:
      Authorization: Bearer <accessToken>

[6] Al expirar (401):
      POST /api/v1/auth/refresh
      {refreshToken} → nuevo accessToken

2.5 Logout y Revocación

POST /api/v1/auth/logout
  {refreshToken}

Auth Service:
  · Marca refresh token como REVOKED en base de datos
  · El access token sigue siendo técnicamente válido hasta expirar
    (corta duración = ventana máxima de 15 min)
  · Registra evento de logout en AuditLog

3. Bloqueo de Cuenta

El sistema registra intentos de login fallidos y bloquea automáticamente la cuenta para prevenir ataques de fuerza bruta.

Intento de login fallido:
  1. Incrementa failed_attempts en tabla users
  2. Si failed_attempts >= MAX_ATTEMPTS (configurable):
     · Establece account_locked_until = NOW() + LOCKOUT_DURATION
     · Registra evento ACCOUNT_LOCKED en AuditLog

Login con cuenta bloqueada:
  → HTTP 423 Locked
  → Mensaje: "Cuenta bloqueada. Intente nuevamente después de las HH:MM."

Desbloqueo:
  · Automático: cuando account_locked_until < NOW()
  · Manual: administrador puede resetear failed_attempts

4. RBAC — Control de Acceso Basado en Roles

4.1 Roles del Sistema

Rol Descripción
ROLE_ADMIN Acceso total — gestión de usuarios y configuración
ROLE_DOCTOR Gestión de atenciones, acceso a historias clínicas
ROLE_NURSE Triage, actualización de estados de atención
ROLE_RECEPTIONIST Registro de pacientes, creación de atenciones
ROLE_BILLING Acceso al módulo de facturación

4.2 Matriz de Permisos

Recurso ADMIN DOCTOR NURSE RECEPTIONIST BILLING
Crear paciente ✓ ✓ ✗ ✓ ✗
Ver historia clínica ✓ ✓ ✓ ✗ ✗
Modificar historia clínica ✓ ✓ ✗ ✗ ✗
Crear atención ✓ ✓ ✓ ✓ ✗
Cambiar estado atención ✓ ✓ ✓ ✗ ✗
Acceder facturación ✓ ✗ ✗ ✗ ✓
Gestionar médicos ✓ ✗ ✗ ✗ ✗
Gestionar usuarios ✓ ✗ ✗ ✗ ✗
Chat con IA ✓ ✓ ✓ ✓ ✗

4.3 Implementación

Los roles viajan dentro del JWT. Cada microservicio extrae los roles del claim roles y aplica @PreAuthorize en los controladores:

@PreAuthorize("hasAnyRole('DOCTOR', 'ADMIN')")
@GetMapping("/{id}")
public ResponseEntity<PatientResponse> getPatient(@PathVariable UUID id) { ... }

@PreAuthorize("hasRole('ADMIN')")
@DeleteMapping("/{id}")
public ResponseEntity<Void> deletePatient(@PathVariable UUID id) { ... }

No se realiza ninguna llamada al Auth Service en tiempo de request — los roles están en el token, la validación es local.

5. Rate Limiting

El API Gateway implementa un token bucket por usuario usando Redis.

5.1 Algoritmo Token Bucket

Estado inicial: tokens_disponibles[userId] = CAPACITY (ej. 100)

Por cada request:
  IF tokens_disponibles[userId] > 0:
    DECREMENT tokens_disponibles[userId]
    ALLOW request
  ELSE:
    RETURN 429 Too Many Requests

Recarga (cada segundo):
  tokens_disponibles[userId] = MIN(CAPACITY, tokens + REFILL_RATE)

5.2 Cabeceras de Respuesta

El gateway incluye información de rate limiting en las respuestas:

X-RateLimit-Remaining: 47
X-RateLimit-Limit: 100
X-RateLimit-Reset: 1716134460

5.3 Escenarios de Protección

Escenario Protección
Fuerza bruta en login Rate limit + bloqueo de cuenta tras N fallos
Scraping de pacientes Rate limit por userId impide extracción masiva
DoS desde un usuario 429 rápido, sin carga al microservicio
DoS desde IP anónima Rate limit aplicado antes de validar JWT

6. Auditoría

Cada evento de seguridad queda registrado en la tabla audit_logs del Auth Service.

6.1 Eventos Registrados

Evento Campos guardados
LOGIN_SUCCESS userId, username, IP, timestamp
LOGIN_FAILED username, IP, timestamp, intento número N
ACCOUNT_LOCKED userId, IP, timestamp
LOGOUT userId, IP, timestamp
TOKEN_REFRESHED userId, timestamp
PASSWORD_CHANGED userId, IP, timestamp
PASSWORD_RESET userId, email, IP, timestamp

6.2 Soft Delete y Auditoría de Datos

Todas las entidades clínicas tienen campos de trazabilidad:

deleted_at   DATETIME    NULL   -- null = activo
deleted_by   VARCHAR(50) NULL   -- username que eliminó
created_at   DATETIME    NOT NULL DEFAULT NOW()
updated_at   DATETIME    NOT NULL DEFAULT NOW() ON UPDATE NOW()
created_by   VARCHAR(50) NOT NULL
updated_by   VARCHAR(50) NOT NULL

Esto garantiza:

  • ¿Quién creó un registro? → created_by
  • ¿Quién lo modificó por última vez? → updated_by
  • ¿Quién lo "eliminó" y cuándo? → deleted_by, deleted_at
  • Reproducibilidad completa del estado de cualquier registro en cualquier momento

7. Seguridad en Tránsito

Externo → Gateway:      HTTPS (TLS 1.2/1.3) — obligatorio en producción
Gateway → Microservicio: HTTP interno en red Docker (red privada, sin exposición pública)
Microservicio → BD:      Conexión autenticada por usuario/contraseña de base de datos

Las credenciales de base de datos y las claves RSA se inyectan vía variables de entorno (.env), nunca hardcodeadas en el código fuente.

8. Decisiones de Diseño

8.1 RSA-256 en lugar de HMAC-SHA256

Problema: con HMAC, todos los microservicios necesitan la misma clave secreta para verificar tokens. Un secreto compartido entre N servicios multiplica la superficie de ataque por N.

Solución: clave privada RSA solo en el Auth Service (firma). Clave pública en cada microservicio (verificación). Comprometer un microservicio no expone la capacidad de emitir tokens.

8.2 Refresh Token Hasheado en Base de Datos

Problema: si la base de datos de Auth es comprometida, los refresh tokens expuestos permitirían impersonar usuarios indefinidamente.

Solución: el refresh token almacenado en base de datos es el hash SHA-256 del valor real. El cliente guarda el valor original; la base de datos guarda el hash. Un dump de la base de datos no revela tokens usables.

8.3 No Verificación de Roles en Auth Service por Request

Problema: centralizar la autorización en Auth Service crea un punto único de fallo. Si cae, ningún microservicio puede verificar permisos.

Solución: los roles viajan en el JWT. Cada microservicio valida la firma del token (con clave pública, sin llamada de red) y aplica RBAC localmente. Auth Service no está en el hot path de cada request.

8.4 Rate Limiting en Gateway, No en Microservicios

Problema: si el rate limiting está en cada microservicio, un atacante puede bypassearlo llamando directamente a puertos internos.

Solución: el rate limiting se aplica en el API Gateway, que es el único punto de entrada expuesto. Los puertos de los microservicios no son accesibles desde fuera de la red Docker.

Documento mantenido junto al código — las configuraciones específicas (umbrales, duraciones) se definen en application.yml de cada servicio.
Diagrama de Clínica — Sistema de Gestión Hospitalaria
IMÁGENES