juampisor commited on
Commit
476c19b
·
1 Parent(s): 569fa5c

Added documentation. Included definitive design document.

Browse files
.DS_Store ADDED
Binary file (6.15 kB). View file
 
documentation/CONSIGNA.md ADDED
@@ -0,0 +1,126 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # TRABAJO PRÁCTICO OBLIGATORIO: HEALTH GRID
2
+
3
+ **Institución:** UADE
4
+ **Materia:** DESARROLLO DE APLICACIONES II
5
+ **Profesor:** Ing. Joaquín Timerman
6
+
7
+ La red de hospitales "Health Grid" busca unificar sus procesos médicos y administrativos. Actualmente, la información de los pacientes está dispersa en silos, lo que dificulta la atención coordinada. Se solicita desarrollar una plataforma modular y distribuida que integre desde la Historia Clínica Electrónica hasta el monitoreo de pacientes en tiempo real.
8
+
9
+ ---
10
+
11
+ ## REQUERIMIENTOS GENERALES
12
+
13
+ * Cada grupo estará integrado por siete alumnos como máximo.
14
+ * Cada grupo diseñará y desarrollará un módulo específico.
15
+ * Cada módulo deberá integrarse con otros de acuerdo con las reglas de negocio establecidas en este documento.
16
+ * La integración será por medio de APIs RESTful y/o eventos asincrónicos, quedando la elección del método a criterio de cada grupo.
17
+ * Los mismos deberán estar justificados y correctamente defendidos en las entregas parciales y final.
18
+ * Las tecnologías utilizadas para desarrollar cada módulo quedarán a criterio de cada grupo.
19
+ * Las mismas deberán estar justificadas y correctamente defendidas en las entregas parciales y final.
20
+ * Se deberá documentar correctamente las APIs con herramientas como Swagger o Postman.
21
+
22
+ ---
23
+
24
+ ## LISTADO DE MÓDULOS
25
+
26
+ ### 1. Historia Clínica Electrónica
27
+ Es el repositorio central de datos médicos. Debe gestionar el registro de cada consulta, diagnóstico y tratamiento.
28
+ * **Registro Clínico:** Creación y actualización de la ficha médica del paciente (antecedentes, alergias, cirugías, etc.).
29
+ * **Evolución Médica:** Carga de notas de consulta por parte de profesionales de salud.
30
+ * **Consulta Externa:** Exponer un servicio para que otros módulos consulten si un paciente tiene contraindicaciones médicas antes de un estudio o medicación.
31
+ * **Notificación Crítica:** Emitir un evento asincrónico cuando se detecte una patología de notificación obligatoria.
32
+
33
+ ### 2. Gestión de Turnos y Agendas
34
+ Administra la disponibilidad de profesionales y espacios físicos.
35
+ * **Calendario Profesional:** Gestión de la disponibilidad horaria por médico, especialidad y sede.
36
+ * **Reserva de Turnos:** Flujo de reserva para pacientes, permitiendo filtrar por cercanía o primera disponibilidad.
37
+ * **Recordatorios:** Envío de notificaciones automáticas 24 horas antes del turno (vía evento asincrónico).
38
+ * **Presentismo:** Registro de llegada del paciente para disparar el flujo de atención en sala de espera.
39
+
40
+ ### 3. Farmacia e Insumos Hospitalarios
41
+ Controla el stock de medicamentos en farmacia y depósitos.
42
+ * **Dispensación de Recetas:** Validación y entrega de medicamentos basados en la receta electrónica emitida en HCE.
43
+ * **Gestión de Inventario:** Control de stock físico en farmacia central y depósitos de piso.
44
+ * **Alertas de Stock:** Generación automática de pedidos de compra cuando un insumo crítico llega al punto de reorden.
45
+ * **Trazabilidad:** Registro de qué lote de medicamento se entregó a cada paciente.
46
+
47
+ ### 4. Laboratorio de Análisis Clínicos
48
+ Gestión de pedidos de laboratorio y carga de resultados.
49
+ * **Gestión de Ordenes:** Recepción de pedidos de análisis desde el Portal del Paciente o Médicos.
50
+ * **Carga de Resultados:** Interfaz para bioquímicos donde puedan cargar valores y observaciones técnicas.
51
+ * **Publicación de Resultados:** Al guardar un resultado finalizado, debe impactar automáticamente en la HCE y notificar al paciente.
52
+ * **Validación de Rangos:** Marcado automático de valores fuera de rango normal.
53
+
54
+ ### 5. Diagnóstico por Imágenes
55
+ Gestión de estudios como Rayos X, Tomografías y Resonancias.
56
+ * **Catálogo de Estudios:** Gestión de turnos específicos para equipos de alta complejidad (Tomógrafos, Resonadores, etc.).
57
+ * **Informe Médico:** Herramienta para que el radiólogo redacte el informe vinculado a la imagen.
58
+ * **Visualizador Lite:** Interfaz para que el médico solicitante pueda ver el informe y el link a la imagen almacenada.
59
+ * **Integración de Resultados:** Envío del informe finalizado a la HCE de forma sincrónica.
60
+
61
+ ### 6. Internación y Gestión de Camas
62
+ Administra la ocupación de camas, ingresos a guardia y quirófanos.
63
+ * **Mapa de Camas:** Visualización en tiempo real de la ocupación por piso, sector y tipo de cama (UTI, Sala Común, etc.).
64
+ * **Gestión de Ingresos:** Registro de admisión desde Guardia o Cirugía programada.
65
+ * **Pases de Piso:** Gestión de traslados internos del paciente y liberación de recursos.
66
+ * **Cierre de Episodio:** Proceso de alta médica que dispara el evento para la limpieza de la unidad y la facturación final.
67
+
68
+ ### 7. Facturación y Obras Sociales
69
+ Liquida las prestaciones médicas a las aseguradoras y gestiona cobros particulares.
70
+ * **Nomenclador Médico:** Gestión de precios y convenios por cada obra social o prepaga.
71
+ * **Liquidación de prestaciones:** Recopilación de todos los actos médicos (consultas, estudios, descartables) realizados a un paciente.
72
+ * **Auditoría de Cuentas:** Proceso de validación de facturas antes del envío a la entidad pagadora.
73
+ * **Gestión de Coseguros:** Cálculo y cobro de excedentes o copagos al paciente.
74
+
75
+ ### 8. Portal del Paciente y Telemedicina
76
+ Interfaz para que el ciudadano interactúe con el sistema.
77
+ * **Mi Salud:** Visualización de turnos próximos, historial de recetas y resultados de laboratorio.
78
+ * **Sala Virtual:** Integración de videollamada para consultas de baja complejidad.
79
+ * **Pagos Online:** Sección para pagar coseguros o turnos particulares utilizando saldo de tarjetas o billeteras virtuales (Pueden simular la integración).
80
+ * **Perfil y Notificaciones:** Centro de notificaciones en tiempo real para alertas de salud y turnos.
81
+
82
+ ### 9. Monitoreo de Pacientes
83
+ Simula el procesamiento de datos provenientes de dispositivos médicos.
84
+ * **Ingesta de Telemetría:** Simulación de recepción de datos de sensores (frecuencia cardíaca, SpO2, etc.) mediante colas de mensajes.
85
+ * **Motor de Reglas:** Evaluación en tiempo real de los datos recibidos (ej: si HR>120 por 2 minutos, generar alerta).
86
+ * **Panel de Monitoreo:** Dashboard para enfermería con el estado de los pacientes.
87
+ * **Alertas de Emergencia:** Envío de evento de alta prioridad al Módulo de Internación ante un código rojo detectado por sensores.
88
+
89
+ ### 10. Core
90
+ Gestión centralizada de usuarios (médicos, administrativos, pacientes), permisos y configuración global.
91
+ * **Maestro de Usuarios:** Gestión de identidades para médicos, enfermeros, administrativos, bioquímicos y pacientes.
92
+ * **Control de Acceso:** Definición de qué módulos y acciones puede realizar cada rol. Autenticación por JWT para todos los módulos.
93
+ * **Maestro de Sedes y Especialidades:** Configuración global que consumen los módulos de Turnos e Integración.
94
+ * **Bus de Eventos:** Configuración y auditoría de los canales de integración entre todos los módulos del sistema.
95
+
96
+ ---
97
+
98
+ ## ENTREGAS
99
+
100
+ ### Primera entrega:
101
+ * Mocks de cada vista (Frontend).
102
+ * Contratos de APIs (Backend).
103
+
104
+ ### Segunda entrega:
105
+ * Módulo completamente funcional con las integraciones mockeadas.
106
+
107
+ ### Entrega final:
108
+ * Módulo completamente funcional e integrado al resto del sistema.
109
+ * README con instrucciones para instalar y ejecutar el módulo.
110
+
111
+ ---
112
+
113
+ ## Anexo - Glosario de Términos de Dominio
114
+
115
+ ### Conceptos Asistenciales (Atención al paciente)
116
+ * **HCE (Historia Clínica Electrónica):** Registro longitudinal de la información de salud de un individuo, generada en uno o más encuentros en cualquier entorno de prestación de cuidados.
117
+ * **Episodio / Encuentro Médico:** Una interacción específica entre un paciente y un profesional de la salud (una consulta, una internación, una guardia). Cada episodio debe generar un registro en la HCE.
118
+ * **Triage:** Proceso de selección y clasificación de pacientes en los servicios de urgencias basado en sus necesidades terapéuticas y recursos disponibles, no necesariamente por orden de llegada.
119
+ * **Evolución:** Nota clínica redactada por el profesional de salud durante un encuentro donde se describe el estado actual, el plan de tratamiento y las observaciones del paciente.
120
+ * **Receta Electrónica:** Orden digital emitida por un médico para la dispensación de medicamentos.
121
+
122
+ ### Conceptos Administrativos y Financieros
123
+ * **Nomenclador Médico:** Catálogo de todas las prestaciones médicas (consultas, cirugías, estudios) identificadas por un código único y una descripción. Es la base para la facturación.
124
+ * **Prestación Médica:** Cualquier acción, servicio o estudio realizado a un paciente que tiene un costo asociado y debe ser registrado para su cobro.
125
+ * **Coseguro / Copago:** Monto de dinero que el paciente debe abonar por una prestación médica, el cual no está cubierto por su obra social o prepaga.
126
+ * **Auditoría Médica:** Proceso de revisión de las prestaciones realizadas para asegurar que cumplen con las normas médicas y administrativas antes de ser facturadas a la obra social.
documentation/M6_DISEÑO.md ADDED
@@ -0,0 +1,351 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Módulo 6 — Internación y Gestión de Camas
2
+
3
+ **Health Grid · Documento de diseño (fuente de la verdad)**
4
+
5
+ > Este documento es la fuente de verdad de **arquitectura, dominio, máquinas de estado, flujos de negocio, reglas de negocio e integraciones** del módulo.
6
+ > El **contrato OpenAPI** (`MA_modulo_openapi.json` / Apidog) es la fuente de verdad de la **forma exacta** de cada request y response. Cuando haya diferencia entre la firma concreta de un endpoint y lo escrito acá, manda el spec; cuando haya diferencia sobre *qué hace* un endpoint o *qué reglas aplica*, manda este documento. Toda corrección al contrato listada en el changelog del final debe reflejarse también en el spec.
7
+
8
+ ---
9
+
10
+ ## 1. Contexto y responsabilidad del módulo
11
+
12
+ Health Grid es una plataforma hospitalaria modular y distribuida. Cada módulo es un servicio independiente que se integra con el resto vía REST sincrónico y webhooks (HTTP POST) asincrónicos.
13
+
14
+ El Módulo 6 administra el **recurso físico de internación**: camas y quirófanos. Su responsabilidad es saber, en todo momento, qué cama ocupa cada paciente, mediar las solicitudes de internación y traslado que llegan desde la Historia Clínica Electrónica, gestionar las reservas de quirófano (programadas y urgentes), y propagar al resto del sistema los cambios de estado que tienen consecuencias clínicas, administrativas o de facturación.
15
+
16
+ El módulo **no** decide internaciones ni altas. Esas decisiones son clínicas y nacen en HCE (M1). M6 ejecuta, valida la disponibilidad del recurso, y le da a un administrativo la última palabra sobre qué cama concreta se asigna.
17
+
18
+ Funcionalidades, según el enunciado:
19
+
20
+ - **Mapa de camas:** ocupación en tiempo real por piso, sector y tipo de cama.
21
+ - **Gestión de ingresos:** admisión desde guardia o cirugía programada.
22
+ - **Pases de piso:** traslados internos y liberación de recursos.
23
+ - **Cierre de episodio:** el alta médica dispara la limpieza de la unidad y la facturación final.
24
+ - **Quirófanos:** reservas programadas y manejo de urgencias con desplazamiento.
25
+
26
+ ---
27
+
28
+ ## 2. Stack tecnológico y justificación
29
+
30
+ | Capa | Tecnología | Justificación |
31
+ |------|-----------|---------------|
32
+ | Frontend | React (JS) | SPA con actualización en vivo del mapa de camas vía WebSocket. Ecosistema maduro para dashboards operativos. |
33
+ | Backend | Python + FastAPI | Tipado con Pydantic que valida los contratos en runtime, generación automática del OpenAPI que ya estamos usando como contrato, y soporte nativo de async para las llamadas salientes concurrentes. |
34
+ | Cliente HTTP saliente | httpx | Cliente async, necesario para no bloquear el event loop al llamar a M1, M2, M7, M9 y M10. |
35
+ | Persistencia | PostgreSQL | Datos relacionales con integridad transaccional. La asignación de cama y el cambio de estado deben ser atómicos para evitar doble ocupación. |
36
+ | Tiempo real | WebSocket | El mapa de camas necesita push: cuando una cama cambia de estado, todos los tableros abiertos lo ven sin polling. |
37
+
38
+ ### Por qué REST sincrónico + webhooks, y no solo uno
39
+
40
+ La integración mezcla dos naturalezas y elegimos la herramienta por caso, no una sola para todo:
41
+
42
+ - **Sincrónico (REST saliente con httpx)** cuando M6 necesita una respuesta para continuar su propia transacción: validar contraindicaciones del paciente en HCE antes de asignar la cama, traer datos del paciente desde Core, o registrar el movimiento en HCE. Si esa llamada falla, la operación de M6 no puede darse por exitosa.
43
+ - **Asincrónico (webhooks, HTTP POST "fire-and-forget")** cuando M6 notifica un hecho ya consumado que el receptor procesa a su ritmo: avisarle a Monitoreo que arranque/pare el seguimiento, o a Facturación que la cama quedó lista. Que el receptor esté caído no debe revertir el alta del paciente.
44
+
45
+ Esta separación es la decisión arquitectónica central del módulo y hay que poder defenderla en la entrega.
46
+
47
+ ---
48
+
49
+ ## 3. Arquitectura
50
+
51
+ ```
52
+ ┌─────────────────────────────────────────────────────────────┐
53
+ │ FRONTEND — React │
54
+ │ Mapa de camas · Ingresos · Solicitudes · Quirófanos │
55
+ └───────────────┬─────────────────────────▲────────────────────┘
56
+ REST API │ │ WebSocket (mapa)
57
+ ┌───────────────▼─────────────────────────┴────────────────────┐
58
+ │ BACKEND — FastAPI │
59
+ │ Routers: Camas (CRUD + WS) · Quirófanos · Solicitudes · │
60
+ │ Webhooks (entrantes M1/M9) │
61
+ │ Capa de servicios: lógica de negocio · validaciones · │
62
+ │ contraindicaciones · desplazamiento de reservas · │
63
+ │ máquina de estados de cama · alta médica │
64
+ │ Clientes HTTP (httpx): llamadas salientes a M1·M2·M7·M9·M10 │
65
+ └───────────────┬───────────────────────────────────┬──────────┘
66
+ PostgreSQL│ REST saliente│ + webhooks
67
+ ┌───────────────▼──────────┐ ┌─────────────────────▼──────────┐
68
+ │ PERSISTENCIA — Postgres │ │ MÓDULOS EXTERNOS │
69
+ │ Camas · Quirófanos · │ │ M10 Core (call) │
70
+ │ Reservas · Solicitudes ·│ │ M1 HCE (call + recv) │
71
+ │ Episodios · Eventos │ │ M2 Turnos (call) │
72
+ └──────────────────────────┘ │ M7 Facturación (call) │
73
+ │ M9 Monitoreo (call + recv) │
74
+ └─────────────────────────────────┘
75
+ ```
76
+
77
+ **Regla de capas:** los routers solo orquestan (parsean request, llaman al servicio, arman response). Toda la lógica de negocio, las validaciones y las máquinas de estado viven en la capa de servicios. Las llamadas salientes pasan siempre por los clientes HTTP, nunca directo desde un router. Esto mantiene la lógica testeable sin levantar la red y permite mockear los módulos externos en la 2da entrega cambiando solo la capa de clientes.
78
+
79
+ ---
80
+
81
+ ## 4. Modelo de dominio
82
+
83
+ ### 4.1 Entidades
84
+
85
+ - **Cama:** unidad física de internación. Identificada por `id` (integer). Atributos clave: `numero`, `piso`, `sector`, `tipo`, `estado`, `paciente_id` (nullable), `hospital_id`, `specialty_id` (nullable), `contraindicaciones_incompatibles` (lista de strings).
86
+ - **Quirófano:** **es una especialización de Cama** con `sector=QUIROFANO` y `tipo=CIRUGIA`. Comparte tabla y máquina de estados con Cama (ver decisión en §10). Se expone bajo su propio recurso `/quirofanos` por claridad de API, pero internamente es la misma entidad.
87
+ - **Solicitud:** pedido de internación o traslado originado en HCE (M1). Identificada por `id` string (`SOL-00123`) y vinculada al id de origen `solicitud_hce_id`. Vive en estado `PENDIENTE` hasta que un administrativo la resuelve.
88
+ - **Reserva de quirófano:** ocupación de un quirófano en una ventana horaria, programada o de emergencia. Una urgente puede desplazar a una programada (`desplazada_por_reserva_id`).
89
+ - **Episodio de internación:** abstracción de negocio que empieza cuando se aprueba una solicitud de internación (se asigna la primera cama) y termina cuando M1 notifica el alta médica. Atraviesa una o más camas (traslados). Es lo que se reporta a Facturación al cierre.
90
+ - **Evento:** registro de auditoría de cada cambio relevante (entrante o saliente), para trazabilidad y para el Bus de Eventos de Core.
91
+
92
+ ### 4.2 Enumeraciones (catálogos cerrados)
93
+
94
+ ```
95
+ SectorEnum = UTI | SALA_COMUN | QUIROFANO | GUARDIA | NEONATOLOGIA
96
+ TipoCamaEnum = ESTANDAR | PEDIATRICA | AISLAMIENTO | CRITICA | CIRUGIA
97
+ EstadoCamaEnum = DISPONIBLE | OCUPADA | EN_LIMPIEZA | FUERA_DE_SERVICIO
98
+ | BAJA_PERMANENTE | CODIGO_ROJO
99
+ OrigenIngresoEnum = GUARDIA | CIRUGIA_PROGRAMADA
100
+ TipoAltaEnum = ALTA_MEDICA | ALTA_VOLUNTARIA | TRASLADO_EXTERNO | DEFUNCION
101
+
102
+ TipoSolicitudEnum = INTERNACION | TRASLADO
103
+ EstadoSolicitudEnum = PENDIENTE | APROBADA | RECHAZADA
104
+ AccionResolucionEnum = APROBAR | APROBAR_CON_CAMBIO | RECHAZAR
105
+ PrioridadSolicitudEnum= MUY_BAJA | BAJA | MEDIA | ALTA | MUY_ALTA | URGENTE (6 niveles)
106
+ PrioridadQuirofanoEnum= MUY_BAJA | BAJA | MEDIA | ALTA | MUY_ALTA | URGENTE (6 niveles)
107
+ Reserva.origen = PROGRAMADA | EMERGENCIA
108
+ Reserva.estado = RESERVADA | EN_CURSO | COMPLETADA | CANCELADA
109
+ TipoAsignacion = INGRESO | TRASLADO (campo `tipo` de asignación de cama)
110
+ ```
111
+
112
+ > Solicitudes y quirófanos comparten la misma escala de prioridad de 6 niveles. Las dos enums se mantienen separadas por claridad semántica, pero sus valores son idénticos.
113
+
114
+ ### 4.3 Máquina de estados de una Cama
115
+
116
+ ```
117
+ asignar (INGRESO/TRASLADO destino)
118
+ DISPONIBLE ───────────────────────────────────────► OCUPADA
119
+ ▲ │
120
+ │ limpieza completada │ alta médica / traslado (cama origen)
121
+ │ (→ webhook CAMA_LISTA a M7) ▼
122
+ EN_LIMPIEZA ◄──────────────────────────────────── (libera recurso)
123
+
124
+ OCUPADA ──── alerta emergencia M9 ──► CODIGO_ROJO ──── alerta resuelta M9 ──► OCUPADA
125
+
126
+ cualquier estado ── mantenimiento (PATCH) ──► FUERA_DE_SERVICIO ──► DISPONIBLE
127
+ cualquier estado ── DELETE ──► BAJA_PERMANENTE (terminal, no reversible)
128
+ ```
129
+
130
+ Reglas de transición:
131
+ - Solo se asigna sobre `DISPONIBLE`. Intentar asignar sobre `OCUPADA`/`EN_LIMPIEZA`/`FUERA_DE_SERVICIO` devuelve `409 Conflict`.
132
+ - `CODIGO_ROJO` es un overlay sobre `OCUPADA`: la alerta resuelta vuelve a `OCUPADA`, no a `DISPONIBLE`.
133
+ - Al trasladar, la cama **origen** pasa a `EN_LIMPIEZA` y la **destino** a `OCUPADA` en la misma transacción.
134
+ - `BAJA_PERMANENTE` es terminal: una cama dada de baja no vuelve al circuito.
135
+
136
+ ### 4.4 Máquina de estados de una Solicitud
137
+
138
+ ```
139
+ PENDIENTE ── APROBAR / APROBAR_CON_CAMBIO ──► APROBADA (ejecuta ingreso/traslado)
140
+ PENDIENTE ── RECHAZAR ───────────────────────► RECHAZADA (no ejecuta nada)
141
+ ```
142
+
143
+ Resolver es idempotente respecto del estado: una solicitud ya resuelta devuelve `409` ante un nuevo intento de resolución.
144
+
145
+ Mientras la solicitud está `PENDIENTE`, los campos de resolución (`accion`, `motivo`, `resuelto_por`, `timestamp_resolucion`) son `null`. Se completan recién al resolverla, por eso en el contrato son nullable.
146
+
147
+ ### 4.5 Máquina de estados de una Reserva de quirófano
148
+
149
+ ```
150
+ RESERVADA ──► EN_CURSO ──► COMPLETADA
151
+ │
152
+ └──► CANCELADA (por cancelación de turno M2, o por desplazamiento de una urgencia)
153
+ ```
154
+
155
+ ---
156
+
157
+ ## 5. Flujos de negocio
158
+
159
+ ### 5.1 Ingreso por internación (flujo principal)
160
+
161
+ 1. Un médico solicita cama desde HCE. M1 hace `POST /webhooks/hce/solicitud` con `tipo=INTERNACION`. M6 crea la solicitud en estado `PENDIENTE`.
162
+ 2. El administrativo ve la cola en el frontend (`GET /solicitudes?estado=PENDIENTE`).
163
+ 3. El administrativo resuelve con `PATCH /solicitudes/{solicitudId}`:
164
+ - **APROBAR / APROBAR_CON_CAMBIO:** M6, dentro de una transacción, valida disponibilidad y compatibilidad de la cama (§6), consulta contraindicaciones en HCE y datos del paciente en Core, asigna la cama (`estado → OCUPADA`, set `paciente_id`), y **abre el episodio**.
165
+ - **RECHAZAR:** no se asigna nada.
166
+ 4. M6 dispara, según el caso:
167
+ - `POST /hce/solicitudes/{solicitudHceId}/resultado` (sincrónico) y webhook `SOLICITUD_RESUELTA` a M1.
168
+ - `POST /hce/movimientos` (sincrónico) si hubo asignación.
169
+ - webhook `ALTA_MONITOREO` a M9 si hubo asignación.
170
+ 5. El cambio de estado de la cama se emite por WebSocket al mapa.
171
+
172
+ Si `origen = CIRUGIA_PROGRAMADA`, antes de aprobar se valida el turno quirúrgico contra M2 (`GET /api/v1/appointments/{appointmentId}`).
173
+
174
+ ### 5.2 Traslado / pase de piso
175
+
176
+ 1. Llega como solicitud (`POST /webhooks/hce/solicitud` con `tipo=TRASLADO`, `cama_origen_id`, `cama_destino_solicitada_id`) o se ejecuta directo por el administrativo (`POST /camas/{camaId}/asignar` con `tipo=TRASLADO`, `cama_origen_id`).
177
+ 2. En la misma transacción: cama origen `→ EN_LIMPIEZA`, cama destino `→ OCUPADA`.
178
+ 3. Salientes: `POST /hce/movimientos`, webhook `BAJA_MONITOREO` (cama origen) y `ALTA_MONITOREO` (cama destino) a M9.
179
+
180
+ ### 5.3 Cierre de episodio (alta médica)
181
+
182
+ 1. M1 hace `POST /webhooks/hce/alta-medica` (`paciente_id`, `medico_firmante_id`, `tipo_alta`).
183
+ 2. M6 cierra el episodio, libera la cama (`OCUPADA → EN_LIMPIEZA`) y dispara webhook `BAJA_MONITOREO` a M9.
184
+ 3. Cuando el personal marca la limpieza terminada (`PATCH /camas/{camaId}` con `estado=DISPONIBLE` desde `EN_LIMPIEZA`), M6 dispara webhook `CAMA_LISTA` a M7 con el resumen del episodio (obra social, número de afiliado, diagnósticos de ingreso/egreso, fechas y `camas_utilizadas`). Esto arranca la liquidación.
185
+
186
+ ### 5.4 Cirugía programada
187
+
188
+ `POST /quirofanos/{quirofanoId}/reservas` crea una reserva `PROGRAMADA` en estado `RESERVADA`. Disponibilidad consultable con `GET /quirofanos/disponibilidad?desde&hasta&specialty_id`. El estado se avanza con `PATCH /quirofanos/{quirofanoId}/reservas/{reservaId}` (`EN_CURSO`, `COMPLETADA`, `CANCELADA`).
189
+
190
+ ### 5.5 Cirugía urgente con desplazamiento
191
+
192
+ 1. M1 hace `POST /webhooks/hce/cirugia-urgente`.
193
+ 2. M6 busca un quirófano compatible en la ventana. Si está libre, reserva `EMERGENCIA`. Si está ocupado por una `PROGRAMADA`, **la desplaza**: la programada pasa a `CANCELADA` y la urgente se crea con referencia inversa; la urgente guarda `desplazada_por_reserva_id` apuntando a la desplazada.
194
+ 3. La respuesta incluye la reserva creada y, si hubo, la `reserva_desplazada`.
195
+
196
+ ### 5.6 Cancelación de turno quirúrgico desde M2
197
+
198
+ `POST /turnos/{turnoId}/cancelacion` (entrante desde M2). M6 busca la reserva asociada al turno y la pasa a `CANCELADA`, liberando el quirófano.
199
+
200
+ ### 5.7 Código rojo (Monitoreo)
201
+
202
+ 1. M9 detecta emergencia y hace `POST /webhooks/monitoreo/alerta-emergencia` (`paciente_id`).
203
+ 2. M6 localiza la cama del paciente, la pone en `CODIGO_ROJO`, notifica a enfermería (WebSocket al mapa) y registra el evento en HCE (`POST /hce/episodios/{episodioId}/eventos`).
204
+ 3. Al estabilizarse, M9 hace `POST /webhooks/monitoreo/alerta-resuelta` y la cama vuelve a `OCUPADA`.
205
+
206
+ ---
207
+
208
+ ## 6. Reglas de negocio y validaciones
209
+
210
+ - **Compatibilidad de contraindicaciones:** antes de asignar, M6 cruza las `contraindicaciones_incompatibles` de la cama contra las contraindicaciones del paciente (traídas de HCE). Si hay intersección, la asignación se rechaza con `422`. Ejemplo: cama con `ALERGIA_LATEX` incompatible no puede recibir un paciente con esa alergia.
211
+ - **Disponibilidad atómica:** la asignación valida estado `DISPONIBLE` y cambia a `OCUPADA` dentro de la misma transacción de base de datos, para que dos administrativos no asignen la misma cama. Conflicto → `409`.
212
+ - **Compatibilidad sector/tipo:** la cama asignada debe ser coherente con la necesidad clínica de la solicitud (criterio a definir y documentar; mínimamente, no asignar `QUIROFANO`/`CIRUGIA` a una internación común).
213
+ - **Resolución única:** una solicitud `APROBADA` o `RECHAZADA` no se puede volver a resolver → `409`.
214
+ - **Idempotencia de webhooks entrantes:** los webhooks de M1 y M9 traen ids de origen (`solicitud_hce_id`, etc.). M6 debe deduplicar por ese id para tolerar reintentos sin duplicar solicitudes ni movimientos.
215
+ - **Desplazamiento solo por urgencia:** una reserva `PROGRAMADA` solo se cancela automáticamente por una `EMERGENCIA`; nunca por otra programada.
216
+
217
+ ---
218
+
219
+ ## 7. Integraciones
220
+
221
+ ### 7.1 Webhooks entrantes (otros módulos → M6)
222
+
223
+ | Endpoint | Emisor | Disparador |
224
+ |----------|--------|-----------|
225
+ | `POST /webhooks/hce/solicitud` | M1 HCE | Médico solicita internar o trasladar un paciente |
226
+ | `POST /webhooks/hce/cirugia-urgente` | M1 HCE | Médico solicita cirugía urgente |
227
+ | `POST /webhooks/hce/alta-medica` | M1 HCE | Médico da el alta |
228
+ | `POST /webhooks/monitoreo/alerta-emergencia` | M9 Monitoreo | Código rojo detectado por sensores |
229
+ | `POST /webhooks/monitoreo/alerta-resuelta` | M9 Monitoreo | Emergencia estabilizada |
230
+ | `POST /turnos/{turnoId}/cancelacion` | M2 Turnos | Se cancela/reprograma un turno quirúrgico |
231
+
232
+ ### 7.2 Webhooks salientes (M6 → otros módulos)
233
+
234
+ | Evento | Receptor | Endpoint receptor | Cuándo |
235
+ |--------|----------|-------------------|--------|
236
+ | `SOLICITUD_RESUELTA` | M1 HCE | `POST /hce/solicitudes/{solicitudHceId}/resultado` | Al aprobar o rechazar una solicitud |
237
+ | `ALTA_MONITOREO` | M9 Monitoreo | `POST /webhooks/internacion/alta-monitoreo` | Al asignar cama (ingreso o destino de traslado) |
238
+ | `BAJA_MONITOREO` | M9 Monitoreo | `POST /webhooks/internacion/baja-monitoreo` | Al dar el alta o al trasladar (cama origen) |
239
+ | `CAMA_LISTA` | M7 Facturación | `POST /webhooks/internacion/cama-lista` | Al completar limpieza post-alta (`EN_LIMPIEZA → DISPONIBLE`) |
240
+
241
+ ### 7.3 APIs externas consumidas (REST sincrónico)
242
+
243
+ | Módulo | Endpoint | Cuándo |
244
+ |--------|----------|--------|
245
+ | M10 Core | `POST /auth/validate-token` | En cada request (middleware JWT) |
246
+ | M10 Core | `GET /usuarios/{pacienteId}` | Al aprobar una internación (datos del paciente) |
247
+ | M1 HCE | `GET /hce/pacientes/{pacienteId}/contraindicaciones` | Al aprobar una internación |
248
+ | M1 HCE | `GET /hce/pacientes/{pacienteId}` | Al mostrar el detalle del paciente internado en una cama |
249
+ | M1 HCE | `POST /hce/movimientos` | Al asignar cama o trasladar (movimiento unificado) |
250
+ | M1 HCE | `POST /hce/solicitudes/{solicitudHceId}/resultado` | Al resolver una solicitud |
251
+ | M1 HCE | `POST /hce/episodios/{episodioId}/eventos` | Al recibir una alerta de emergencia de M9 |
252
+ | M2 Turnos | `GET /api/v1/appointments/{appointmentId}` | Al aprobar solicitud con `origen=CIRUGIA_PROGRAMADA` |
253
+
254
+ ### 7.4 Estrategia de mock (2da entrega)
255
+
256
+ Todos los endpoints `[EXT]` (los que expone otro módulo) se mockean localmente para la 2da entrega. El mock vive en la capa de clientes HTTP: la misma interfaz que en producción, pero devolviendo respuestas canned. Esto permite que la 3ra entrega solo cambie la URL base del cliente, sin tocar la lógica de servicios.
257
+
258
+ ---
259
+
260
+ ## 8. Contrato de API (recursos propios)
261
+
262
+ Lista de endpoints implementados por M6. Para la forma exacta de cada body, ver el spec OpenAPI.
263
+
264
+ **Camas** (`Camas`)
265
+ - `GET /camas` — mapa completo. Filtros: `piso`, `sector`, `estado`, `hospital_id`.
266
+ - `POST /camas` — alta de cama.
267
+ - `GET /camas/{camaId}` — detalle.
268
+ - `PATCH /camas/{camaId}` — actualizar `estado` o `contraindicaciones_incompatibles`.
269
+ - `DELETE /camas/{camaId}` — baja permanente.
270
+ - `POST /camas/{camaId}/asignar` — asignar o trasladar paciente. Body: `tipo` (`INGRESO`/`TRASLADO`), `paciente_id`, `cama_origen_id` (solo traslado).
271
+
272
+ **Quirófanos** (`Quirófanos`)
273
+ - `GET /quirofanos` · `POST /quirofanos` · `GET /quirofanos/{quirofanoId}` · `PATCH /quirofanos/{quirofanoId}`
274
+ - `GET /quirofanos/disponibilidad` — requiere `desde`, `hasta`; opcional `hospital_id`, `specialty_id`.
275
+ - `GET /quirofanos/{quirofanoId}/reservas` · `POST /quirofanos/{quirofanoId}/reservas`
276
+ - `GET /quirofanos/{quirofanoId}/reservas/{reservaId}` · `PATCH /quirofanos/{quirofanoId}/reservas/{reservaId}`
277
+
278
+ **Solicitudes** (`Solicitudes`)
279
+ - `GET /solicitudes` — filtros `estado`, `tipo`, `hospital_id`.
280
+ - `GET /solicitudes/{solicitudId}` — detalle.
281
+ - `PATCH /solicitudes/{solicitudId}` — resolver (`APROBAR` / `APROBAR_CON_CAMBIO` / `RECHAZAR`).
282
+
283
+ **Webhooks entrantes** — ver §7.1.
284
+
285
+ ---
286
+
287
+ ## 9. Tiempo real (WebSocket)
288
+
289
+ El mapa de camas se suscribe a un canal WebSocket. Cada vez que una cama cambia de estado (asignación, traslado, alta, limpieza, código rojo), el backend publica el delta y todos los tableros conectados se actualizan sin polling. El canal es solo de salida hacia el frontend; las acciones siguen yendo por REST. El WebSocket no se documenta en OpenAPI (la spec 3.0 no lo soporta); su contrato de mensajes se mantiene en este documento.
290
+
291
+ Formato de mensaje propuesto (a confirmar): `{ "tipo": "CAMA_ACTUALIZADA", "cama_id", "estado", "paciente_id", "timestamp" }`.
292
+
293
+ ---
294
+
295
+ ## 10. Persistencia
296
+
297
+ Tablas principales en PostgreSQL: `camas` (incluye quirófanos), `reservas_quirofano`, `solicitudes`, `episodios`, `eventos`.
298
+
299
+ - **`camas`** guarda también los quirófanos (`sector=QUIROFANO`, `tipo=CIRUGIA`). Es la decisión de modelo que explica que `QuirofanoResponse.estado` use `EstadoCamaEnum` y que `ReservaQuirofanoResponse` referencie la cama. Alternativa rechazada: tabla `quirofanos` separada, que duplicaría la máquina de estados de disponibilidad.
300
+ - **`episodios`** referencia al paciente y mantiene la lista de camas atravesadas para el reporte a Facturación.
301
+ - **`eventos`** es el log de auditoría (entrante/saliente) para trazabilidad y para el Bus de Eventos de Core.
302
+ - La asignación de cama (validar `DISPONIBLE` → set `OCUPADA` + `paciente_id`) se hace en una transacción con bloqueo de fila para evitar doble ocupación.
303
+
304
+ ---
305
+
306
+ ## 11. Seguridad
307
+
308
+ Autenticación por JWT centralizada en Core (M10). Un middleware en FastAPI valida el token en cada request entrante (`POST /auth/validate-token` contra M10), salvo los webhooks entrantes, que se autentican por el mecanismo que acuerde el Bus de Eventos (secreto compartido o firma). El esquema es `BearerAuth` (HTTP Bearer, formato JWT) y aplica de forma global. La autorización por rol (qué acción puede hacer cada rol) usa los permisos definidos por Core.
309
+
310
+ > El spec actual declara el esquema `BearerAuth` pero deja el `security` global vacío. Hay que declarar `security: [{ BearerAuth: [] }]` a nivel raíz para que la protección sea explícita en el contrato.
311
+
312
+ ---
313
+
314
+ ## 12. Convenciones
315
+
316
+ - **Timestamps:** ISO 8601 en UTC con sufijo `Z` (`2025-01-15T10:30:00Z`).
317
+ - **IDs:** `Cama.id`, `Quirofano.id`, `paciente_id`, etc. son `integer`. `Solicitud.id` y los ids de origen externos (`solicitud_hce_id`, `solicitud_urgencia_hce_id`) son `string` con prefijo (`SOL-`, `HCE-SOL-`).
318
+ - **Naming de campos:** español para campos internos del dominio (`paciente_id`, `cama_solicitada_id`). Se conservan en inglés los campos que cruzan desde otros módulos y son configuración global de Core (`specialty_id`, `hospital_id`) o convención técnica (`created_at`), para no introducir traducción en el límite entre módulos.
319
+ - **Errores:** dos schemas de body. `Error` (`codigo`, `mensaje`, `detalle?`) para errores de negocio o auth; `ErrorValidacion` (`codigo`, `mensaje`, `errores[]`) para validación de payload. Las respuestas de error se exponen vía componentes de response reutilizables (`NoAutenticado` para `401`, `NoAutorizado` para `403`, `ErrorValidacion` para `400`/`422`), referenciados con `$ref` en todos los endpoints para mantener consistencia.
320
+ - **Códigos HTTP:** `400` payload malformado · `401` sin token / token inválido · `403` rol sin permiso · `404` recurso inexistente · `409` conflicto de estado (cama ocupada, solicitud ya resuelta) · `422` regla de negocio violada (contraindicación incompatible) · `502` falla al llamar a un módulo externo.
321
+
322
+ ---
323
+
324
+ ## 13. Supuestos y decisiones abiertas
325
+
326
+ - **Compatibilidad sector/tipo en la asignación:** falta definir la matriz exacta de qué tipo de cama admite qué necesidad clínica. Hoy solo está claro que un quirófano no se usa para internación común.
327
+ - **Naming `cama_id` en reservas:** `ReservaQuirofanoResponse.cama_id` apunta al quirófano. Es confuso por la decisión de modelar quirófano como cama. Deuda técnica: renombrar a `quirofano_id` en el contrato cuando se pueda coordinar con el frontend.
328
+ - **Autenticación de webhooks entrantes:** pendiente acordar el mecanismo con el Bus de Eventos de Core.
329
+
330
+ ---
331
+
332
+ ## 14. Changelog de correcciones al contrato
333
+
334
+ ### 14.1 Aplicadas al spec
335
+
336
+ 1. **Contraindicaciones duplicado.** Se eliminó `/pacientes/{pacienteId}/contraindicaciones`. Queda el canónico **`GET /hce/pacientes/{pacienteId}/contraindicaciones`** con `pacienteId: integer`.
337
+ 2. **`POST /camas/{camaId}/asignar`.** Se eliminó el path param fantasma `quirofanoId` y `camaId` quedó como **`integer`**.
338
+ 3. **Turnos (M2).** Se parametrizaron los IDs hardcodeados: **`/api/v1/appointments/{appointmentId}`**, `.../cancel` y `.../reschedule`, con `appointmentId: integer`.
339
+ 4. **`AsignacionCamaResponse.tipo`.** Era `string` libre (el Request ya estaba bien). Se corrigió a enum **`{INGRESO, TRASLADO}`** para que Request y Response coincidan.
340
+ 5. **Escala de prioridad unificada.** `PrioridadSolicitudEnum` se expandió de 4 a 6 niveles **`{MUY_BAJA, BAJA, MEDIA, ALTA, MUY_ALTA, URGENTE}`**, idéntica a `PrioridadQuirofanoEnum`. Resuelve la decisión que antes quedaba abierta.
341
+ 6. **`GET /api/v1/appointments/{appointmentId}` (EXTRA A).** Los campos `confirmed_at`, `checked_in_at`, `cancelled_at`, `completed_at` usaban `"type": "null"`, inválido en OpenAPI 3.0.1. Corregidos a `string` / `format: date-time` / `nullable: true`.
342
+ 7. **`POST /turnos/{turnoId}/cancelacion` (EXTRA B).** Los responses `400`, `401`, `403` eran strings vacíos sin schema. Apuntan ahora a los componentes reutilizables `ErrorValidacion`, `NoAutenticado` y `NoAutorizado`.
343
+ 8. **`Solicitud.accion` (EXTRA C).** Era `$ref` directo a `AccionResolucionEnum` sin `nullable`. Una solicitud `PENDIENTE` no tiene acción de resolución. Corregido a `nullable: true`.
344
+ 9. **`WebhookCamaLista.evento` (EXTRA D).** Era `string` libre. Corregido a enum **`{CAMA_LISTA}`**, consistente con `WebhookAltaMonitoreo.evento` y `WebhookBajaMonitoreo.evento`.
345
+ 10. **`Ext_MovimientoRequest.resultado` (EXTRA E).** Era `string` libre pese a que la description decía "APROBADA o RECHAZADA". Tipado como enum **`{APROBADA, RECHAZADA}`**, `nullable: true`.
346
+
347
+ ### 14.2 Pendientes
348
+
349
+ 1. **`security` global vacío.** El spec declara el esquema `BearerAuth` pero deja `security` vacío a nivel raíz. Falta declarar **`security: [{ BearerAuth: [] }]`** para que la protección sea explícita en el contrato.
350
+ 2. **`WebhookCamaLista` campos obligatorios.** Más allá del enum de `evento`, conviene marcar `evento` y `paciente_id` como `required`, en línea con los otros webhooks salientes.
351
+ 3. **Renombrar `cama_id` en reservas de quirófano.** `ReservaQuirofanoResponse.cama_id` apunta al quirófano. Renombrar a `quirofano_id` cuando se coordine con el frontend (ver §13).
documentation/M6_arquitectura.png ADDED