api / documentation /M6_DISEÑO.md
juampisor's picture
Arreglo
ea9df53
|
Raw History Blame Contribute Delete
69.8 kB
# Módulo 6 — Internación y Gestión de Camas
**Health Grid · Documento de diseño (fuente de la verdad)**
> 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.
> 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.
---
## 1. Contexto y responsabilidad del módulo
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.
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.
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.
Funcionalidades, según el enunciado:
- **Mapa de camas:** ocupación en tiempo real por piso, sector y tipo de cama.
- **Gestión de ingresos:** admisión desde guardia o cirugía programada.
- **Pases de piso:** traslados internos y liberación de recursos.
- **Cierre de episodio:** el alta médica dispara la limpieza de la unidad y la facturación final.
- **Quirófanos:** reservas programadas y manejo de urgencias con desplazamiento.
---
## 2. Stack tecnológico y justificación
| Capa | Tecnología | Justificación |
|------|-----------|---------------|
| Frontend | React / Next.js | SPA con actualización en vivo del mapa de camas y la auditoría vía Supabase Realtime. Ecosistema maduro para dashboards operativos. |
| 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. |
| Cliente HTTP saliente | httpx | Cliente async, necesario para no bloquear el event loop al llamar a M1, M2, M7, M9 y M10. |
| Persistencia | PostgreSQL (Supabase) | Datos relacionales con integridad transaccional. La asignación de cama y el cambio de estado deben ser atómicos para evitar doble ocupación. |
| Tiempo real | Supabase Realtime | El mapa de camas y el historial de auditoría necesitan push: cuando una cama cambia de estado o se registra un evento, todos los tableros abiertos lo ven sin polling. Se eligió por sobre un hub WebSocket in-process porque el backend corre en un único proceso uvicorn en HF Spaces sin estado compartido entre workers — Supabase Realtime hace el fan-out de cambios en `camas`/`auditoria` directamente a los clientes suscriptos, sin código adicional en el backend (ver §9). |
### Por qué REST sincrónico + webhooks, y no solo uno
La integración mezcla dos naturalezas y elegimos la herramienta por caso, no una sola para todo:
- **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.
- **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.
Esta separación es la decisión arquitectónica central del módulo y hay que poder defenderla en la entrega.
---
## 3. Arquitectura
```
┌─────────────────────────────────────────────────────────────┐
│ FRONTEND — React/Next.js │
│ Mapa de camas · Ingresos · Solicitudes · Quirófanos · Auditoría│
└───────────────┬─────────────────────────▲────────────────────┘
REST API │ Supabase Realtime (cliente directo,
│ tablas `camas` y `auditoria`)
┌───────────────▼────────────────────────────────────────────────┐
│ BACKEND — FastAPI │
│ Routers: Camas (CRUD) · Quirófanos · Solicitudes · Auditoría │
│ (GET) · Webhooks (entrantes M1/M9) │
│ Capa de servicios: lógica de negocio · validaciones · │
│ contraindicaciones · desplazamiento de reservas · │
│ máquina de estados de cama · alta médica │
│ Clientes HTTP (httpx): llamadas salientes a M1·M2·M7·M9·M10 │
└───────────────┬───────────────────────────────────┬───────────┘
PostgreSQL│ REST saliente│ + webhooks
┌───────────────▼──────────┐ ┌─────────────────────▼──────────┐
│ PERSISTENCIA — Supabase │ │ MÓDULOS EXTERNOS │
│ (Postgres + Realtime) │ │ M10 Core (call) │
│ Camas · Quirófanos · │ │ M1 HCE (call + recv) │
│ Reservas · Solicitudes ·│ │ M2 Turnos (call) │
│ Auditoría │ │ M7 Facturación (call) │
└──────────────────────────┘ │ M9 Monitoreo (call + recv) │
└─────────────────────────────────┘
```
**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.
**El backend no implementa push en tiempo real.** El frontend se conecta directo a Supabase Realtime (con el anon key, de solo lectura vía RLS) y escucha cambios en las tablas `camas` y `auditoria`. El backend solo escribe en Postgres; Supabase hace el fan-out a los clientes suscriptos. Esto saca toda la complejidad de pub/sub del backend (no hay hub in-process, no hay problema de multi-worker) a cambio de exponer el anon key de Supabase al frontend, lo cual es seguro porque las políticas RLS de esas tablas son de solo `SELECT`.
---
## 4. Modelo de dominio
### 4.1 Entidades
- **Cama:** unidad física de internación. Identificada por `id` (integer). Atributos clave: `numero` (integer), `piso` (integer), `sector`, `tipo`, `estado`, `paciente_id` (nullable integer), `hospital_id`, `specialty_id` (nullable integer), `contraindicaciones_incompatibles` (lista de strings).
- **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.
- **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.
- **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`).
- **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.
- **Evento de auditoría:** registro append-only de cada mutación relevante sobre `CAMA`, `SOLICITUD` o `RESERVA_QUIROFANO` (solicitudes, aprobaciones/rechazos, asignaciones, traslados, cambios de estado, bajas, alta médica, código rojo, reservas de quirófano). Vive en la tabla `auditoria`, con `cama_id` denormalizado para poder recuperar "todo lo que pasó con la cama X" sin importar qué entidad originó el evento. Detalle completo del modelo y los eventos en `docs/superpowers/specs/2026-06-26-auditoria-cama-design.md`.
### 4.2 Enumeraciones (catálogos cerrados)
```
SectorEnum = UTI | SALA_COMUN | QUIROFANO | GUARDIA | NEONATOLOGIA
TipoCamaEnum = ESTANDAR | PEDIATRICA | AISLAMIENTO | CRITICA | CIRUGIA
EstadoCamaEnum = DISPONIBLE | OCUPADA | EN_LIMPIEZA | FUERA_DE_SERVICIO
| BAJA_PERMANENTE | CODIGO_ROJO
OrigenIngresoEnum = GUARDIA | CIRUGIA_PROGRAMADA
TipoAltaEnum = ALTA_MEDICA | ALTA_VOLUNTARIA | TRASLADO_EXTERNO | DEFUNCION
TipoSolicitudEnum = INTERNACION | TRASLADO
EstadoSolicitudEnum = PENDIENTE | APROBADA | RECHAZADA
AccionResolucionEnum = APROBAR | APROBAR_CON_CAMBIO | RECHAZAR
PrioridadSolicitudEnum= MUY_BAJA | BAJA | MEDIA | ALTA | MUY_ALTA | URGENTE (6 niveles)
PrioridadQuirofanoEnum= MUY_BAJA | BAJA | MEDIA | ALTA | MUY_ALTA | URGENTE (6 niveles)
Reserva.origen = PROGRAMADA | EMERGENCIA
Reserva.estado = RESERVADA | EN_CURSO | COMPLETADA | CANCELADA
TipoAsignacion = INGRESO | TRASLADO (campo `tipo` de asignación de cama)
```
> 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.
### 4.3 Máquina de estados de una Cama
```
asignar (INGRESO/TRASLADO destino)
DISPONIBLE ───────────────────────────────────────► OCUPADA
▲ │
│ limpieza completada │ alta médica / traslado (cama origen)
│ (→ webhook CAMA_LISTA a M7) ▼
EN_LIMPIEZA ◄──────────────────────────────────── (libera recurso)
OCUPADA ──── alerta emergencia M9 ──► CODIGO_ROJO ──── alerta resuelta M9 ──► OCUPADA
cualquier estado ── mantenimiento (PATCH) ──► FUERA_DE_SERVICIO ──► DISPONIBLE
cualquier estado ── DELETE ──► BAJA_PERMANENTE (terminal, no reversible)
```
Reglas de transición:
- Solo se asigna sobre `DISPONIBLE`. Intentar asignar sobre `OCUPADA`/`EN_LIMPIEZA`/`FUERA_DE_SERVICIO` devuelve `409 Conflict`.
- `CODIGO_ROJO` es un overlay sobre `OCUPADA`: la alerta resuelta vuelve a `OCUPADA`, no a `DISPONIBLE`.
- Al trasladar, la cama **origen** pasa a `EN_LIMPIEZA` y la **destino** a `OCUPADA` en la misma transacción.
- `BAJA_PERMANENTE` es terminal: una cama dada de baja no vuelve al circuito.
### 4.4 Máquina de estados de una Solicitud
```
PENDIENTE ── APROBAR / APROBAR_CON_CAMBIO ──► APROBADA (ejecuta ingreso/traslado)
PENDIENTE ── RECHAZAR ───────────────────────► RECHAZADA (no ejecuta nada)
```
Resolver es idempotente respecto del estado: una solicitud ya resuelta devuelve `409` ante un nuevo intento de resolución.
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.
### 4.5 Máquina de estados de una Reserva de quirófano
```
RESERVADA ──► EN_CURSO ──► COMPLETADA
│
└──► CANCELADA (por cancelación de turno M2, o por desplazamiento de una urgencia)
```
---
## 5. Flujos de negocio
### 5.1 Ingreso por internación (flujo principal)
1. Un médico solicita cama desde HCE. M1 hace `POST /webhooks/hce/solicitud` con `tipo=INTERNACION`. M6 crea la solicitud en estado `PENDIENTE`.
2. El administrativo ve la cola en el frontend (`GET /solicitudes?estado=PENDIENTE`).
3. El administrativo resuelve con `PATCH /solicitudes/{solicitudId}`:
- **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**.
- **RECHAZAR:** no se asigna nada.
4. M6 dispara, según el caso:
- Evento `SOLICITUD_RESUELTA` a M1 (bus del Core; el REST directo se deprecó 2026-07, ver §7.2).
- `POST /internacion/ingreso` a M1 (sincrónico) si hubo asignación — registra el movimiento en el historial clínico (corrección 2026-07, antes pegaba a un path inexistente).
- webhook `ALTA_MONITOREO` a M9 si hubo asignación.
5. El cambio de estado de la cama queda persistido en `camas`; Supabase Realtime lo propaga al mapa sin intervención adicional del backend (§9).
Si `origen = CIRUGIA_PROGRAMADA`, antes de aprobar se valida el turno quirúrgico contra M2 (`GET /api/v1/appointments/{appointmentId}`).
### 5.2 Traslado / pase de piso
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`).
2. En la misma transacción: cama origen `→ EN_LIMPIEZA`, cama destino `→ OCUPADA`.
3. Salientes: `POST /internacion/ingreso` a M1 (reenvía el mismo `id_episodio` de la cama origen — M1 lo trata como un movimiento más del mismo episodio, no como uno nuevo), webhook `BAJA_MONITOREO` (cama origen) y `ALTA_MONITOREO` (cama destino) a M9.
### 5.3 Cierre de episodio (alta médica)
1. M1 hace `POST /webhooks/hce/alta-medica` (`paciente_id`, `medico_firmante_id`, `tipo_alta`).
2. M6 cierra el episodio, libera la cama (`OCUPADA → EN_LIMPIEZA`) y dispara webhook `BAJA_MONITOREO` a M9.
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.
### 5.4 Cirugía programada
`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`) — vía manual, o automáticamente por horario (ver abajo).
**Auto-transición por horario.** `cama_service.procesar_transiciones_automaticas` (invocada por `POST /api/v1/internal/reservas/tick`, `app/routers/internal.py`) avanza sola las reservas que no se resolvieron a mano: al llegar `fecha_hora_inicio`, una reserva `RESERVADA` pasa a `EN_CURSO`; al llegar `fecha_hora_fin_estimada`, una `EN_CURSO` pasa a `COMPLETADA`. Reusa `update_reserva_estado` tal cual — mismos side-effects que la transición manual (cama a `OCUPADA`/`EN_LIMPIEZA`, auditoría con `rol=SISTEMA`). Que el filtro de origen sea `estado=RESERVADA` ya resuelve "si no se canceló, arranca sola": una reserva `CANCELADA` nunca es candidata, sin lógica adicional. El tick es idempotente: una reserva ya transicionada no vuelve a matchear el filtro en la siguiente pasada.
El endpoint no usa `get_current_user` (no hay un usuario humano detrás de un cron) — se protege con un secreto compartido simple (`settings.internal_tick_secret`, header `X-Internal-Token`). Está pensado para que lo dispare un **cron externo** (GitHub Actions con `schedule:`, o cron-job.org), no un scheduler en memoria: el deploy de M6 en HF Spaces es del tier gratuito, que duerme el contenedor tras inactividad — un loop interno de `asyncio`/APScheduler se congelaría junto con el proceso. La propia request del cron despierta el Space si estaba dormido y ejecuta el chequeo. Se descartó también `pg_cron` de Supabase: sobrevive al sleep, pero reimplementar los side-effects de `update_reserva_estado` en SQL duplicaría la máquina de estados en dos lenguajes.
Margen de precisión aceptable: con un cron cada 1–5 minutos, una cirugía puede reflejarse en el sistema hasta ese margen tarde respecto del horario real — razonable para este caso de uso.
### 5.5 Cirugía urgente con priorización ASAP
1. M1 hace `POST /webhooks/hce/cirugia-urgente`. `fecha_hora_inicio` se interpreta como "no antes de" y `fecha_hora_fin_estimada - fecha_hora_inicio` como la duración de la cirugía — **no** una ventana fija: M6 decide el horario real.
2. M6 considera los quirófanos compatibles: mismo `hospital_id`, excluidos `FUERA_DE_SERVICIO`/`BAJA_PERMANENTE`/`EN_LIMPIEZA`. Para cada uno calcula el **inicio más temprano factible** (`earliest_start`): arranca en "no antes de" y lo empuja cada vez que choca con una reserva **bloqueante** (`EN_CURSO`, o `RESERVADA` con prioridad `URGENTE` — estas nunca se desplazan) hasta que ninguna bloqueante solapa más. Se elige el quirófano con menor `earliest_start`; empata por preferencia de `specialty_id` (si vino en el webhook) y luego por menor `id` de quirófano.
3. Si en el hueco elegido caían reservas `PROGRAMADA` (no urgentes), **se reprograman** — nunca se cancelan — vía el algoritmo `reprogramar()` (busca el próximo hueco libre para esa reserva y notifica el nuevo horario a M2 si tiene `turno_id`). Cada reserva desplazada guarda `desplazada_por_reserva_id` apuntando a la urgente que la corrió. Puede haber **más de una** reserva desplazada si varias caían dentro de la ventana.
4. La respuesta incluye la reserva urgente creada y, si hubo, la lista `reservas_desplazadas` (puede tener 0, 1 o más elementos). Si `solicitud_urgencia_hce_id` ya se había procesado, se devuelve `200` con la reserva existente (idempotencia) en vez de crear una nueva.
> El algoritmo `reprogramar()` de esta sección tiene una implementación mínima (evita solapar horarios, pero no cascadea desplazamientos ni cambia de quirófano si el hueco es demasiado tardío). Diseño completo: pendiente, tarea siguiente.
### 5.6 Cancelación de turno quirúrgico desde M2
`POST /turnos/{turnoId}/cancelacion` (entrante desde M2). M6 busca la reserva asociada al turno y la pasa a `CANCELADA`, liberando el quirófano.
### 5.7 Código rojo (Monitoreo)
1. M9 detecta emergencia y hace `POST /webhooks/monitoreo/alerta-emergencia` (`paciente_id`).
2. M6 localiza la cama del paciente, la pone en `CODIGO_ROJO` (Supabase Realtime lo propaga al mapa automáticamente) y registra el evento en HCE (`POST /hce/episodios/{episodioId}/eventos`).
3. Al estabilizarse, M9 hace `POST /webhooks/monitoreo/alerta-resuelta` y la cama vuelve a `OCUPADA`.
---
## 6. Reglas de negocio y validaciones
- **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.
- **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`.
- **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).
- **Resolución única:** una solicitud `APROBADA` o `RECHAZADA` no se puede volver a resolver → `409`.
- **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.
- **Desplazamiento solo por urgencia:** una reserva `PROGRAMADA` solo se reprograma automáticamente por una `EMERGENCIA` (nunca por otra programada), y nunca se cancela por este motivo — ver §5.5. Reservas `EN_CURSO` o ya `URGENTE` nunca se desplazan.
---
## 7. Integraciones
### 7.1 Webhooks entrantes (otros módulos → M6)
| Endpoint | Emisor | Disparador |
|----------|--------|-----------|
| `POST /webhooks/hce/solicitud` | M1 HCE | Médico solicita internar o trasladar un paciente |
| `POST /webhooks/hce/cirugia-urgente` | M1 HCE | Médico solicita cirugía urgente |
| `POST /webhooks/hce/alta-medica` | M1 HCE | Médico da el alta |
| `POST /webhooks/monitoreo/alerta-emergencia` | M9 Monitoreo | Código rojo detectado por sensores |
| `POST /webhooks/monitoreo/alerta-resuelta` | M9 Monitoreo | Emergencia estabilizada |
| `POST /turnos/{turnoId}/cancelacion` | M2 Turnos | Se cancela/reprograma un turno quirúrgico |
### 7.2 Webhooks salientes (M6 → otros módulos)
| Evento | Receptor | Endpoint receptor / evento del bus | Cuándo |
|--------|----------|-------------------|--------|
| `SOLICITUD_RESUELTA` | M1 HCE | Solo evento (`event_type_id=25`) — el REST se deprecó 2026-07: `POST /hce/solicitudes/{id}/resultado` no existe en el contrato real de M1 | Al aprobar o rechazar una solicitud |
| `ALTA_MONITOREO` | M9 Monitoreo | `POST /webhooks/internacion/alta-monitoreo` (REST); evento `event_type_id=26`, activo — confirmado por M9. Payload incluye `cama_id` (destino) | Al asignar cama (ingreso o destino de traslado) |
| `BAJA_MONITOREO` | M9 Monitoreo | `POST /webhooks/internacion/baja-monitoreo` (REST); evento `event_type_id=27`, activo — confirmado por M9. Payload incluye `cama_id` (origen) | Al dar el alta o al trasladar (cama origen) |
| `CAMA_LISTA` / `CIERRE_INTERNACION` | M7 Facturación | **Pausado 2026-07** (`facturacion_cierre_habilitado=false`) — no se manda ni REST ni evento; código listo (`event_type_id=19`) para reactivar poniendo la variable en `true` | Al completar limpieza post-alta (`EN_LIMPIEZA → DISPONIBLE`) |
**M7 confirmó su integración por escrito** (`documentation/integrations/M7_integration.md`):
cola `facturacion.requests`, `event_type_id: 19`, `publisher_module: "modulo_6"`. El
payload del evento es mucho más rico que el REST (que sigue siendo solo el mínimo de
siempre): `{evento: CIERRE_INTERNACION, idEventoExterno, idInternacionExterna,
idEpisodioExterno, idPacienteExterno, fechaIngreso, fechaAlta, tipoAlta, timestampEvento}`
(`app/integrations/facturacion.py::notify_cama_lista`). `timestampEvento` es obligatorio
por contrato — M7 rechaza el evento si falta.
Para armar ese payload, M6 empezó a persistir datos del episodio en curso directamente en
la fila de `Cama` (`solicitud_hce_id`, `fecha_ingreso`, `alta_tipo`, `alta_timestamp` —
ver `app/models/cama.py`), seteados al aprobar la solicitud y al procesar el alta médica,
y limpiados al cerrar el episodio (`cama_service.py`, tras `notify_cama_lista`). En un
traslado, el episodio (fecha de ingreso e id de internación original) se **hereda de la
cama origen**, no de la solicitud de traslado — es la misma internación, solo cambió de
cama física.
**`idEpisodioExterno` viaja como `None`, a propósito:** ningún webhook de M1 lo provee hoy
(ni `SolicitudHceWebhook` ni `AltaMedicaWebhook` tienen ese campo). Pendiente coordinar
con M1 que lo agregue a `AltaMedicaWebhook` — ver `documentation/M6_INTEGRACION_M1_HCE.md`.
M7 confirmó que sin ese dato el evento no se rechaza, queda pendiente de completar del
lado de ellos.
### 7.3 APIs externas consumidas (REST sincrónico)
| Módulo | Endpoint | Cuándo |
|--------|----------|--------|
| M10 Core | `GET /usuarios/{pacienteId}` | Al aprobar una internación (datos del paciente) |
| M1 HCE | `GET /hce/pacientes/{pacienteId}/contraindicaciones` | Al aprobar una internación |
| M1 HCE | `POST /internacion/ingreso` | Al asignar cama o trasladar (movimiento unificado — corrección 2026-07, path real, antes apuntaba a `/hce/movimientos`, inexistente) |
| ~~M1 HCE `POST /hce/solicitudes/{solicitudHceId}/resultado`~~ | — | **Retirado 2026-07** — path inexistente en M1; `SOLICITUD_RESUELTA` ahora es solo evento del bus (§7.2) |
| M1 HCE | `POST /hce/episodios/{episodioId}/eventos` | Al recibir una alerta de emergencia de M9 |
| M1 HCE | `GET /api/v1/pacientes/{pacienteId}` | Consulta bajo demanda del front (2026-07) — datos básicos del paciente en el detalle de cama |
| M1 HCE | `GET /api/v1/pacientes/{pacienteId}/ficha-medica` | Consulta bajo demanda del front (2026-07) — página de detalle de cama |
| M1 HCE | `GET /api/v1/pacientes/{pacienteId}/antecedentes` | Consulta bajo demanda del front (2026-07) — página de detalle de cama |
| M2 Turnos | `GET /api/v1/appointments/{appointmentId}` | Al aprobar solicitud con `origen=CIRUGIA_PROGRAMADA` |
> **Corrección 2026-07:** esta tabla documentaba antes `GET /hce/pacientes/{pacienteId}`
> (con prefijo `/hce/`) para el detalle de paciente — ese path nunca existió realmente en
> M1 (mismo tipo de desvío doc-vs-código que `contraindicaciones`, ver punto 1 del
> changelog más abajo). El endpoint real, verificado en vivo contra M1
> (`documentation/integrations/openapi_docs/M1_openapi.json`), es
> `GET /api/v1/pacientes/{pacienteId}` — sin prefijo `/hce/` — y es el que consume
> `app.integrations.hce.get_paciente`.
Los tres endpoints de M1 marcados "consulta bajo demanda" son proxies puros expuestos por
M6 (`GET /api/v1/pacientes/{id}`, `/ficha-medica` y `/antecedentes`, ver
`app/routers/pacientes.py`) — a diferencia del resto de esta tabla, no se disparan desde
un flujo de negocio interno sino que el front los llama directamente cuando el usuario
abre el detalle de una cama. `hce.get_paciente`/`get_ficha_medica`/`get_antecedentes` no
distinguen "paciente sin ese dato" de "M1 no respondió": ambos casos devuelven `None` y el
router responde `404` — simplificación aceptada, documentada en el docstring de esas
funciones.
### 7.4 Estrategia de mock (2da entrega)
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.
### 7.5 Bus de eventos del Core (M10): migración en curso
Los webhooks REST de §7.1 tienen dos problemas: (1) exigen `get_current_user` (JWT de
usuario) pero M1/M9/M2 no tienen un usuario humano detrás de un webhook — no hay forma
legítima de que llamen hoy sin credenciales que no deberían tener; (2) son integraciones
point-to-point ad hoc, cuando el Core ya expone un bus de eventos pensado para esto
(`documentation/integrations/M10_integration.md`, "Tutorial: Comunicación entre
microservicios"): *"RabbitMQ para escuchar; Core para configurar y publicar."* Migrar a
la cola resuelve el problema de auth (se consume con credenciales RabbitMQ propias, no un
JWT de usuario) y suma at-least-once delivery + DLQ que hoy no existen.
**Lado entrante — ya migrado, en paralelo con REST.** Cola propia `internacion.requests`
(+ `internacion.requests.dlq`) y 5 event types bindeados, dados de alta en el Core real:
| Evento | Id | Reemplaza (REST) | Emisor | Payload |
|---|---|---|---|---|
| `internacion.solicitud.creada` | 14 | `POST /webhooks/hce/solicitud` | M1 | `SolicitudHceWebhook` |
| `internacion.alta-medica.registrada` | 15 | `POST /webhooks/hce/alta-medica` | M1 | `AltaMedicaWebhook` |
| `internacion.alerta-emergencia.detectada` | 16 | `POST /webhooks/monitoreo/alerta-emergencia` | M9 | `AlertaEmergenciaRequest` |
| `internacion.alerta-resuelta.notificada` | 17 | `POST /webhooks/monitoreo/alerta-resuelta` | M9 | `AlertaResueltaRequest` |
| `internacion.turno.cancelado` | 18 | `POST /turnos/{turnoId}/cancelacion` | M2 | `CancelacionQuirofanoRequest` + `turno_id` (viaja en el payload; en el REST equivalente viene del path) |
Los 5 son notificaciones fire-and-forget (sin `correlation_id`/`response_event_id`), y
reusan tal cual los schemas Pydantic del webhook REST equivalente. El consumer
(`app/integrations/rabbit_consumer.py`) despacha por `event_type_name` a la misma función
de servicio que ya usa el router REST (`solicitud_service.recibir_solicitud`,
`procesar_alta_medica`, `procesar_alerta_emergencia`, `procesar_alerta_resuelta`,
`cancelar_reserva_por_turno`) — cero lógica de negocio nueva, incluida la deduplicación
por id de origen (§6). Gateado por `settings.rabbitmq_consumer_enabled` (default `False`:
falta el host/puerto/vhost real del broker compartido — las credenciales sí son las
mismas `core_service_email`/`core_service_password` de siempre).
**Los endpoints REST de §7.1 se mantienen activos sin cambios** durante la transición —
cada equipo (M1/M9/M2) migra su emisor a su propio ritmo; se retiran recién cuando los
tres confirmen que publican por la cola.
**Cirugía urgente queda excluida** de esta migración: `POST /webhooks/hce/cirugia-urgente`
devuelve sincrónicamente qué quirófano/reserva se asignó y qué reservas se desplazaron —
no hay hoy un canal async equivalente. Migrarla requiere antes acordar con M1 un evento de
respuesta (`correlation_id` + `response_event_id`). Sigue siendo solo REST.
**Lado saliente — los 4 `event_type_id` reales ya se compartieron**, pero no las 4
notificaciones están dual-write ni activas hoy:
- `ALTA_MONITOREO=26`/`BAJA_MONITOREO=27` (M9): dual-write completo (REST + evento), activos.
`monitoreo.notify_alta`/`notify_baja` llevan además `cama_id` en el payload desde esta
corrección (2026-07) — destino en el alta, origen en la baja.
- `SOLICITUD_RESUELTA=25` (M1): **ya no es dual-write** — el REST se deprecó (2026-07, el path
no existe en el contrato real de M1); ahora es evento-only.
- `CAMA_LISTA/CIERRE_INTERNACION=19` (M7): **pausado** (2026-07,
`facturacion_cierre_habilitado=false`) — ni evento ni REST hasta reactivarlo.
El evento y la cola de cada notificación los crea y posee **el receptor** (M1/M9/M7), no M6 —
misma regla del tutorial que aplica al revés en §7.1.
`app/integrations/core_events.py::publish_event(event_type_id, payload)` sigue siendo un
no-op explícito si `event_type_id is None`.
---
## 8. Contrato de API (recursos propios)
Lista de endpoints implementados por M6. Para la forma exacta de cada body, ver el spec OpenAPI.
**Camas** (`Camas`)
- `GET /camas` — mapa completo. Filtros: `piso`, `sector`, `estado`, `hospital_id`.
- `POST /camas` — alta de cama.
- `GET /camas/{camaId}` — detalle.
- `PATCH /camas/{camaId}` — actualizar `estado` o `contraindicaciones_incompatibles`.
- `DELETE /camas/{camaId}` — baja permanente.
- `POST /camas/{camaId}/asignar` — asignar o trasladar paciente. Body: `tipo` (`INGRESO`/`TRASLADO`), `paciente_id`, `cama_origen_id` (solo traslado).
**Quirófanos** (`Quirófanos`)
- `GET /quirofanos` · `POST /quirofanos` · `GET /quirofanos/{quirofanoId}` · `PATCH /quirofanos/{quirofanoId}`
- `GET /quirofanos/disponibilidad` — requiere `desde`, `hasta`; opcional `hospital_id`, `specialty_id`.
- `GET /quirofanos/{quirofanoId}/reservas` · `POST /quirofanos/{quirofanoId}/reservas`
- `GET /quirofanos/{quirofanoId}/reservas/{reservaId}` · `PATCH /quirofanos/{quirofanoId}/reservas/{reservaId}`
**Solicitudes** (`Solicitudes`)
- `GET /solicitudes` — filtros `estado`, `tipo`, `hospital_id`.
- `GET /solicitudes/{solicitudId}` — detalle.
- `PATCH /solicitudes/{solicitudId}` — resolver (`APROBAR` / `APROBAR_CON_CAMBIO` / `RECHAZAR`).
**Auditoría** (`Auditoría`)
- `GET /auditoria` — historial de eventos con filtros (`cama_id`, `entidad`, `entidad_id`, `paciente_id`, `evento`, `rol`, `usuario_id`, `hospital_id`, `fecha_desde`, `fecha_hasta`, `limit`, `offset`). Roles `ADMINISTRATIVO`, `MEDICO`. Snapshot REST; el tiempo real lo entrega Supabase Realtime directamente al frontend (§9).
**Webhooks entrantes** — ver §7.1.
Matriz completa de qué rol puede hacer qué en cada endpoint: ver `documentation/roles.md`.
---
## 9. Tiempo real (Supabase Realtime)
El mapa de camas y el historial de auditoría se actualizan en vivo sin polling agresivo. La implementación **no pasa por el backend de M6**: el frontend se conecta directo a Supabase Realtime con el cliente JS (`@supabase/supabase-js`) usando el anon key, y se suscribe a cambios `postgres_changes` sobre dos tablas:
- **`camas`** — eventos `INSERT`/`UPDATE`. El mapa de camas escucha la tabla completa; el detalle de una cama escucha filtrado por `id=eq.{camaId}`.
- **`auditoria`** — evento `INSERT`. La pantalla de detalle de cama escucha filtrado por `cama_id=eq.{camaId}` para mostrar el historial de esa cama en vivo.
**Por qué no un WebSocket propio:** se evaluó y se descartó un hub in-process (`AuditoriaHub`) que mantuviera en memoria las conexiones WS activas y hubiera publicado los deltas. Se descartó porque solo es válido para un único proceso uvicorn (que es el caso hoy, sin `--workers`), pero rompe en cuanto se escale a múltiples workers o procesos — cada uno solo vería sus propias conexiones. Supabase Realtime resuelve el fan-out a nivel de base de datos, sin ese problema, y sin código de pub/sub que mantener en el backend.
**Habilitación (una vez, en Supabase):**
```sql
ALTER PUBLICATION supabase_realtime ADD TABLE camas;
ALTER PUBLICATION supabase_realtime ADD TABLE auditoria;
```
Ambas tablas necesitan una policy RLS de `SELECT` abierta (`USING (true)`) para que el cliente con el anon key —que no tiene una sesión de Supabase Auth— pueda recibir los eventos. El backend sigue escribiendo con la `service_role` key, que bypassea RLS; el anon key del frontend es de solo lectura por diseño de Supabase, así que exponerlo en el cliente no abre una vía de escritura no autorizada.
**Patch quirúrgico, no refetch:** el frontend no hace un `GET` completo cada vez que llega un evento. El payload del evento Realtime (`payload.new`) ya trae la fila actualizada; el frontend la normaliza y actualiza solo esa entidad en el estado local (hooks `use-beds.ts` / `use-bed.ts` / `use-auditoria.ts` del frontend `TPO-DA2`). Esto evita perder scroll o producir un parpadeo de pantalla completa en cada actualización.
**Fallback:** `use-beds.ts` mantiene un polling de seguridad cada 5 minutos por si se cae la conexión Realtime del cliente.
---
## 10. Persistencia
Tablas principales en PostgreSQL (Supabase): `camas` (incluye quirófanos), `reservas_quirofano`, `solicitudes`, `auditoria`.
- **`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. Además de sus columnas originales, `camas` guarda los datos del **episodio en curso** (`solicitud_hce_id`, `fecha_ingreso`, `alta_tipo`, `alta_timestamp`) — necesarios para el payload rico que M7 pide al cerrar la internación (§7.2, §14). Se setean al aprobar la solicitud y al procesar el alta médica, y se limpian al notificar a M7. Decisión: no se creó una tabla `episodios` separada (mencionada en versiones previas de este documento como plan, nunca implementada) — para el alcance actual (una cama activa = un episodio en curso, sin necesidad de historizar episodios pasados) alcanza con estas columnas en `camas`, siguiendo el mismo patrón ya usado por `ultimo_movimiento_tipo`.
- **`auditoria`** es el log append-only de auditoría de `CAMA`/`SOLICITUD`/`RESERVA_QUIROFANO`, instrumentado explícitamente en la capa de servicios (no triggers, no middleware) para capturar el actor del JWT y el contexto de negocio completo. Registrar un evento es *best-effort*: nunca propaga una excepción que rompa la operación de negocio. Habilitada para Supabase Realtime (§9). Modelo completo, enums y puntos de instrumentación en `docs/superpowers/specs/2026-06-26-auditoria-cama-design.md`.
- 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.
---
## 11. Seguridad
Login centralizado en el Core (M10) vía **SSO**, integrado (no mockeado). La sesión de M6 es **siempre** un JWT HS256 propio (`app/dependencies.py::create_access_token`/`decode_token`), con un claim `rol` directo — no hay un modo de validación distinto por-request. Lo que agrega el Core es la forma de *adquirir* ese token:
- El frontend obtiene del Core un **ticket** de un solo uso (`POST /auth/sso-ticket`, requiere que el usuario ya esté logueado en el Core) y llega a M6 con ese ticket.
- M6 lo canjea server-to-server: `POST /api/v1/auth/sso-exchange` (`app/routers/auth.py`, habilitado con `settings.sso_enabled`) llama a `core_auth.exchange_sso_ticket`, que hace `POST /auth/sso-exchange` contra el Core (`https://api.healthcare.cantero.ar` en el entorno compartido) y recibe `{user, token}` (`models.AuthResponse`). El `token` del Core (RS256, `{exp, iat, permissions[], user_id}`) **no se reenvía ni se guarda** — solo se usa `user` para resolver el rol.
- El callback del browser (`/auth/sso?ticket=…&redirect=…`) y la validación anti-open-redirect del `redirect` son responsabilidad del **frontend** — fuera de este backend.
**Resolución de rol (viene en el canje, no en el JWT):** `user.roles[]` de la respuesta (`models.User.roles`, cada uno con `name`) trae el/los rol(es) del usuario en el Core. `core_auth.map_core_roles_to_internal` los traduce al rol interno de M6 vía la tabla `CORE_ROLE_TO_INTERNAL`:
| Rol Core | Rol interno M6 |
|---|---|
| `admin_internacion` | `ADMINISTRATIVO` |
| `Medico` | `MEDICO` |
| `limpieza` | `LIMPIEZA` |
| `admin` | `ADMINISTRATIVO` (super-admin del Core) |
| cualquier otro / ninguno | sin acceso a M6 → `403` en el canje |
No hay verificación de JWT del Core por-request: todo se resuelve **una sola vez**, en el canje — a partir de `user.roles[]` si el Core lo puebla, o si no vía el fallback `GET /roles` (ver §14.11). M6 emite entonces su propio JWT HS256 (`create_access_token(sub=str(user_id), rol=rol)`) y lo devuelve junto con el rol y los datos básicos del usuario. `get_current_user` (`app/dependencies.py`) valida ese token localmente en cada request — misma forma `{"sub", "rol"}` de siempre; `require_roles`, la auditoría y los routers no cambiaron.
**Llamadas salientes:** una cuenta de servicio propia (`core_auth.get_service_token`, login contra `POST /auth/login` del Core) autentica las llamadas de M6 a M1/M2/M7/M10 (adjuntado automático en `app/integrations/_base.py::_headers`), incluidas las disparadas por webhooks entrantes donde no hay usuario humano. Es independiente del flujo SSO — se habilita con `CORE_SERVICE_EMAIL`/`CORE_SERVICE_PASSWORD`.
**Fuera de alcance de esta integración:**
- Permisos granulares (`camas:read`, etc.) — el Core no expone `permissions:manage` a la cuenta de servicio hoy, ni tiene permisos de dominio M6 en su catálogo; migrar `require_roles` a permisos cuando eso cambie.
- Autenticación de webhooks entrantes (`/webhooks/*` sigue exigiendo JWT de usuario) — pendiente acordar secreto compartido/firma con el Bus de Eventos.
- Refresh de sesión: al vencer el JWT de M6, el usuario vuelve a pasar por SSO.
---
## 12. Convenciones
- **Timestamps:** ISO 8601 en UTC con sufijo `Z` (`2025-01-15T10:30:00Z`).
- **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-`).
- **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.
- **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.
- **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.
---
## 13. Supuestos y decisiones abiertas
- **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.
- **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.
- **Autenticación de webhooks entrantes:** pendiente acordar el mecanismo con el Bus de Eventos de Core.
---
## 14. Changelog de correcciones al contrato
### 14.1 Aplicadas al spec
1. **Contraindicaciones duplicado.** Se eliminó `/pacientes/{pacienteId}/contraindicaciones`. Queda el canónico **`GET /hce/pacientes/{pacienteId}/contraindicaciones`** con `pacienteId: integer`.
2. **`POST /camas/{camaId}/asignar`.** Se eliminó el path param fantasma `quirofanoId` y `camaId` quedó como **`integer`**.
3. **Turnos (M2).** Se parametrizaron los IDs hardcodeados: **`/api/v1/appointments/{appointmentId}`**, `.../cancel` y `.../reschedule`, con `appointmentId: integer`.
4. **`AsignacionCamaResponse.tipo`.** Era `string` libre (el Request ya estaba bien). Se corrigió a enum **`{INGRESO, TRASLADO}`** para que Request y Response coincidan.
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.
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`.
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`.
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`.
9. **`WebhookCamaLista.evento` (EXTRA D).** Era `string` libre. Corregido a enum **`{CAMA_LISTA}`**, consistente con `WebhookAltaMonitoreo.evento` y `WebhookBajaMonitoreo.evento`.
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`.
11. **`Cama.numero` tipo corregido.** Era `string` en el modelo y schema. Corregido a **`integer`** para reflejar que el número de cama es siempre un valor numérico.
12. **`numero` de quirófano unificado a `integer`.** `QuirofanoCreateRequest.numero` y `QuirofanoResponse.numero` declaraban `string` (ej. `"Q01"`), inconsistente con que el quirófano comparte la tabla `camas`, donde `numero` es `integer` (corrección #11). No puede ser de los dos tipos a la vez. Se unifica a **`integer`** en ambos schemas y en el bloque `quirofanos[].numero` de la respuesta de `GET /quirofanos/disponibilidad`. Consecuencia asumida: los números de quirófano son numéricos (no admiten códigos alfanuméricos tipo `"Q01"`); si en el futuro se necesitan alfanuméricos, hay que migrar la columna `camas.numero` a `string` y revertir #11, lo que también afecta a las camas comunes.
13. **Alineación con M2 (`M2_openapi.json`).** Tras recibir el contrato real de M2 ("Módulo 2 - Gestión de turnos 1.0.0") se corrigió la integración:
- **`turno_id` → `integer`** en todo M6 (reserva de quirófano y solicitud de internación por cirugía programada): los ids de turno de M2 son enteros (`/appointments/{id}`, ej. `326`), no strings tipo `"TURNO-5501"`.
- **Cancelación: solo entrante.** M6 ya **no** cancela turnos en M2. La cancelación de quirófano siempre llega como webhook entrante (`POST /turnos/{turno_id}/cancelacion`), tal como M2 documenta (envía webhook a M6 al cancelar `DELETE /appointments/{id}` para turnos de quirófano).
- **Desplazamiento por urgencia → reschedule, no cancel.** Cuando una cirugía urgente desplaza a una reserva programada, M6 **reprograma** la programada vía `PATCH /appointments/{id}/reschedule` (la mueve a continuación de la urgente, preservando su duración); la programada conserva estado `RESERVADA`. Antes se la cancelaba y se llamaba a un endpoint inexistente (`/turnos/{id}/resultado-quirofano`). **Supuesto a confirmar con M2:** el nuevo horario se calcula como "inmediatamente después de la urgente, misma duración", que puede chocar con las reglas de horario/duración de M2 documentadas para `reschedule`.
- **Se eliminó `get_turno`.** M6 no consulta turnos en M2 hoy; el cliente `GET /turnos/{id}` (path y enum de estado inexistentes en M2) era código muerto y se quitó.
14. **Alineación con M7 (`DesarrolloAPPS2-BE-main`).** Tras revisar el backend real de M7 (Spring Boot, `InternacionM6Request` + `IntegracionService.procesarEventoInternacionM6`) se corrigió `notify_cama_lista` (`POST /api/v1/webhooks/internacion/cama-lista`), manteniendo el evento mínimo de "cama lista" (no migramos al `cierre-episodio` rico):
- **Idempotencia.** Se agrega `idEventoExterno` derivado de forma estable (`M6-CAMA-LISTA-{cama_id}-{paciente_id}-{fecha_alta}`). M7 usa ese campo como `idempotencyKey`; antes no lo mandábamos y M7 caía a una clave que incluía nuestro `timestamp_evento = now()`, con lo que un reintento del mismo alta se tomaba como evento nuevo (riesgo de facturar dos veces).
- **Se quitaron `obra_social_id` y `numero_afiliado`** del payload: no están en el DTO de M7 y los ignoraba. La cobertura la obtiene M7 directamente de M1/HCE.
- **`m7_facturacion_url` corregido** de `:8007` a **`:8080`** (puerto real de M7).
- **Decisión de diseño: M6 no es intermediario del episodio.** No enviamos `idEpisodioExterno` ni datos de internación/actos médicos. Sin episodio, M7 deja el evento en `RECIBIDO_PENDIENTE_DATOS` y no factura automáticamente: **es M7 quien debe pedirle a M1 los datos del episodio/cobertura**, no M6 reenviárselos. Por eso se descartó migrar a `POST /api/integracion/internacion/cierre-episodio` (el endpoint "recomendado" por M7), que exige ese payload rico.
### 14.2 Pendientes
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.
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.
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).
### 14.3 Auditoría y tiempo real (2026-06)
15. **Tabla `auditoria` agregada.** Nuevo recurso `GET /auditoria` (roles `ADMINISTRATIVO`, `MEDICO`) con historial filtrable de eventos sobre `CAMA`/`SOLICITUD`/`RESERVA_QUIROFANO`. Instrumentado en la capa de servicios, best-effort (nunca rompe la operación de negocio). Detalle en `docs/superpowers/specs/2026-06-26-auditoria-cama-design.md`.
16. **Reemplazo de WebSocket in-process por Supabase Realtime.** La primera versión de auditoría en tiempo real se implementó con un hub WebSocket in-process (`app/realtime.py`, endpoint `WS /auditoria/ws`). Se **eliminó** y se reemplazó por Supabase Realtime, consumido directo por el frontend sobre las tablas `camas` y `auditoria` (§9). Razón: el hub in-process solo funciona con un único proceso uvicorn; Supabase Realtime no tiene esa limitación y elimina código de pub/sub del backend. El backend ya no expone ningún endpoint WebSocket.
17. **Rol LIMPIEZA: alcance de lectura ampliado, escritura más restringida.** Antes, `GET /camas` filtraba para LIMPIEZA solo las camas en `EN_LIMPIEZA`. Ahora LIMPIEZA ve **todas** las camas (igual que MEDICO/ADMINISTRATIVO), pero la única escritura permitida es la transición `EN_LIMPIEZA → DISPONIBLE` vía `PATCH /camas/{camaId}`, enforced en `cama_service.update_cama` (no solo en el frontend). Se cerró además un loophole donde LIMPIEZA podía modificar `contraindicaciones_incompatibles` enviándolo sin acompañar un cambio de `estado`.
18. **Rol MEDICO: removido permiso de escritura indebido.** `POST /quirofanos/{quirofanoId}/reservas` (crear reserva de quirófano) aceptaba el rol `MEDICO`, pese a que MEDICO debe ser estrictamente de solo lectura sobre todo el dominio de M6. Corregido a solo `ADMINISTRATIVO`. Matriz completa de permisos por rol en `documentation/roles.md`.
### 14.4 Cirugía urgente: algoritmo de priorización ASAP (2026-06)
19. **Reescritura del algoritmo de §5.5.** La implementación original asumía una ventana horaria fija enviada por M1 y solo verificaba si estaba libre; si no, desplazaba (reprogramando) la única reserva superpuesta de menor prioridad, sin distinguir reservas `EN_CURSO` (que ya está ocurriendo, no se puede tocar) de `RESERVADA`, sin filtrar por `hospital_id`/estado operable del quirófano, y sin soportar más de una reserva desplazada. Se reemplazó por un algoritmo ASAP: `fecha_hora_inicio` del webhook pasa a interpretarse como "no antes de" y la duración se deriva de `fecha_hora_fin_estimada - fecha_hora_inicio`; M6 calcula el inicio más temprano factible entre los quirófanos compatibles (`_earliest_start`, `app/services/cama_service.py`) y puede desplazar **varias** reservas `PROGRAMADA` si caen dentro de la ventana elegida. Las reservas `EN_CURSO` o ya `URGENTE` son bloqueantes y nunca se desplazan.
20. **Contrato de respuesta cambiado.** `CirugiaUrgenteResponse.reserva_desplazada` (objeto u `null`) se reemplazó por `reservas_desplazadas` (array, puede tener 0, 1 o más elementos). Actualizar `M6_openapi.json` y cualquier cliente que integre contra este webhook.
21. **`CirugiaUrgenteWebhook.specialty_id` agregado** (opcional): preferencia de especialidad del quirófano a asignar; si no viene o no hay quirófano libre de esa especialidad, se usa cualquier quirófano compatible del hospital (la urgencia nunca queda sin asignar por esto).
22. **Idempotencia devuelve `200`, no `201`.** Antes el webhook respondía siempre `201`, incluso cuando `solicitud_urgencia_hce_id` ya existía (reintento de M1). Corregido: `200` para el caso idempotente, `201` solo cuando se crea una reserva nueva.
23. **Filtro de quirófanos por hospital y por estado operable.** El algoritmo original no filtraba por `hospital_id` (podía asignar una urgencia a un quirófano de otra sede) ni excluía quirófanos `EN_LIMPIEZA` (además de los ya excluidos `FUERA_DE_SERVICIO`/`BAJA_PERMANENTE`). Corregido en `crear_reserva_urgente`.
24. **Bug de persistencia corregido.** `reserva_crud.save` solo persistía `estado`/`observaciones`/`desplazada_por_reserva_id`; el nuevo horario de una reserva reprogramada nunca se guardaba en la tabla `reservas_quirofano` de M6 (solo se notificaba a M2). Ahora `save` también persiste `fecha_hora_inicio`/`fecha_hora_fin_estimada`.
25. **Seam `reprogramar()`.** Se introdujo `cama_service.reprogramar(db, reserva, no_antes_de, motivo)` como interfaz estable que consume el algoritmo de urgencia para reubicar una reserva desplazada. La implementación actual es mínima (evita solapar horarios en el mismo quirófano) — el diseño completo (cascada, cambio de quirófano) queda pendiente como tarea siguiente.
### 14.5 SSO del Core y eliminación del lookup de roles (2026-07)
26. **Nuevo endpoint `POST /auth/sso-exchange`.** Canjea un ticket SSO de un solo uso del Core (`app/routers/auth.py`, activo con `SSO_ENABLED=true`) por una sesión propia de M6: JWT HS256 con el rol ya resuelto. Request `{ticket}`; response `{token, user, rol}`; errores `401` (ticket inválido/usado/expirado), `403` (roles del usuario sin mapeo a M6), `404` (SSO deshabilitado), `502` (Core inalcanzable). Actualizar `M6_openapi.json` con este endpoint.
27. **Eliminado el lookup `GET /roles` y la verificación de JWT del Core por-request.** El rol ya no se resuelve con una llamada aparte cacheada: viene directo en `user.roles[]` de la respuesta del canje SSO (`models.AuthResponse` → `models.User` → `models.Role`). Se retiraron `core_auth.resolve_user_roles`, `_fetch_roles_index`, `verify_core_token`, `get_signing_key` y sus caches (`_roles_index_cache`, `_jwks_cache`); con ellos, las settings `jwks_cache_ttl_seconds`/`core_roles_cache_ttl_seconds`. Se conserva `map_core_roles_to_internal` (§11), que ahora traduce `user.roles[].name` en vez de un índice cacheado.
28. **`app/config.py::auth_mode` reemplazado por `sso_enabled`.** Ya no existe un modo de validación por-request alternativo — la sesión de M6 es siempre HS256 propia. `sso_enabled` (default `False`) solo habilita/deshabilita el endpoint de canje.
### 14.6 Migración de webhooks entrantes al bus de eventos del Core (2026-07)
29. **Cola `internacion.requests` + 5 event types dados de alta en el Core real** (ids 14–18: `internacion.solicitud.creada`, `internacion.alta-medica.registrada`, `internacion.alerta-emergencia.detectada`, `internacion.alerta-resuelta.notificada`, `internacion.turno.cancelado`), bindeados a esa cola. Reemplazan, en paralelo con REST durante la transición, a los webhooks entrantes de §7.1 (excepto cirugía urgente, excluida — ver §7.5).
30. **Nuevo consumer `app/integrations/rabbit_consumer.py`** (`aio-pika`, gateado por `settings.rabbitmq_consumer_enabled`, default `False` hasta tener host/puerto/vhost real del broker). Despacha por `event_type_name` a las mismas funciones de servicio que ya usa el router REST — sin lógica de negocio nueva.
31. **Nuevo publisher `app/integrations/core_events.py::publish_event`** para las 4 notificaciones salientes de §7.2. No-op explícito mientras el `event_type_id` correspondiente sea `None` (default hasta que M1/M9/M7 compartan el suyo — cada uno crea y posee su propio evento, no M6). Las 4 funciones `notify_*` (`hce.notify_resultado_solicitud`, `monitoreo.notify_alta`/`notify_baja`, `facturacion.notify_cama_lista`) quedan en dual-write: REST sin cambios + `publish_event` adicional.
32. **Sin infraestructura mock creada en el Core para el lado saliente.** Se descartó explícitamente crear event types/colas placeholder en el Core compartido para simular a M1/M9/M7 — hubiera generado tráfico real sin receptor. El código queda listo y probado; activar la publicación real es cambiar 4 valores de config, sin tocar código.
### 14.7 Eliminación de código zombie en la integración con M7/M9 (2026-07)
33. **Eliminado `facturacion.notify_cierre_cama`.** Apuntaba a `POST /api/v1/webhooks/internacion/cierre-cama`, un endpoint que nunca estuvo en la tabla de webhooks salientes (§7.2) ni pasó por la revisión contra el backend real de M7 que sí tuvo `notify_cama_lista` (changelog #14). Estaba activamente cableada en `procesar_alta_medica` y era **bloqueante**: `if not facturacion.notify_cierre_cama(...): raise 502` — con `mock_external_services=False` en producción, cualquier alta médica real hubiera fallado con `502` contra un endpoint que M7 nunca implementó. Sin test para el camino real (pasaba siempre por el atajo de `mock_external_services=True`).
34. **Corregido el gating bloqueante de `monitoreo.notify_baja` en `procesar_alta_medica`.** Era el único de los 5 call sites de `notify_alta`/`notify_baja` en todo el código que trataba la llamada como bloqueante (`if not ...: raise 502`); los otros 4 (`cama_service.py` ingreso/traslado, `solicitud_service.py` aprobar internación/traslado) ya la tratan fire-and-forget. Alineado con el resto del código y con el principio de §2 ("que el receptor esté caído no debe revertir el alta del paciente"): ahora es `monitoreo.notify_baja(paciente_id)` sin gate.
35. **El alta médica ya no depende de M7 ni M9 para completarse.** La notificación real a M7 (`CAMA_LISTA`) sigue ocurriendo, fire-and-forget, más adelante en el flujo (al completar la limpieza, `cama_service.py`). Blindado con tests: `test_alta_medica_ok_aunque_monitoreo_falle` y `test_alta_medica_no_llama_a_facturacion` (`tests/test_webhooks.py`).
### 14.8 Auto-transición de reservas de quirófano por horario (2026-07)
36. **Nuevo `cama_service.procesar_transiciones_automaticas`** (§5.4): avanza `RESERVADA→EN_CURSO` y `EN_CURSO→COMPLETADA` según `fecha_hora_inicio`/`fecha_hora_fin_estimada`, reusando `update_reserva_estado` — mismos side-effects que la transición manual, cero lógica de negocio duplicada. Nuevas queries `reserva_crud.get_pendientes_de_inicio`/`get_pendientes_de_fin`.
37. **Nuevo endpoint `POST /api/v1/internal/reservas/tick`** (`app/routers/internal.py`), protegido con secreto compartido (`settings.internal_tick_secret`, header `X-Internal-Token`) en vez de JWT de sesión — no hay usuario humano detrás de un cron. Pensado para dispararse desde un cron externo (GitHub Actions/cron-job.org), no un scheduler en memoria: el deploy en HF Spaces (tier gratuito) duerme el contenedor tras inactividad, y un loop interno se congelaría con él. Verificado en vivo contra la base real: primer tick transicionó reservas vencidas (`{"iniciadas":7,"completadas":7}`), el segundo tick inmediato confirmó la idempotencia (`{"iniciadas":0,"completadas":0}`).
### 14.9 Integración real con M7: evento `facturacion.internacion.cama-lista.requested` (2026-07)
38. **M7 confirmó su integración por escrito** (`documentation/integrations/M7_integration.md`): cola `facturacion.requests`, `event_type_id: 19` (activado en config, ya no `None`), `publisher_module: "modulo_6"`. Verificado en vivo: `POST /events/log` contra el Core real con este `event_type_id` devuelve `201`.
39. **Payload rico, distinto del REST.** El evento del Core lleva `{evento: CIERRE_INTERNACION, idEventoExterno, idInternacionExterna, idEpisodioExterno, idPacienteExterno, fechaIngreso, fechaAlta, tipoAlta, timestampEvento}` — mucho más rico que el REST de siempre (que M7 documenta como fallback/testing manual y no cambió). `notify_cama_lista` ahora arma **dos payloads distintos** para los dos canales (`app/integrations/facturacion.py`).
40. **Nuevas columnas en `camas`: `solicitud_hce_id`, `fecha_ingreso`, `alta_tipo`, `alta_timestamp`** (§10). Sin esto, M6 no tenía cómo reconstruir el payload rico en el momento de `notify_cama_lista` — esos datos ocurrían antes (aprobación de solicitud, alta médica) y se perdían. Se setean en `_aprobar_internacion`/`_aprobar_traslado`/`procesar_alta_medica` y se limpian al cerrar el episodio. En un traslado, se heredan de la cama origen (mismo episodio), no de la solicitud de traslado.
41. **`core_events.publish_event` gana el parámetro `publisher_module`** (default `"internacion"`, sin cambiar los otros 3 call sites de M1/M9). M7 es el primero en confirmar por escrito que espera `"modulo_6"`.
42. **`solicitud_service.procesar_alta_medica` cambia de firma**: recibe el `AltaMedicaWebhook` completo en vez de solo `paciente_id`, para poder persistir `tipo_alta`/`timestamp` en la cama. Actualizados los dos call sites (`app/routers/webhooks.py`, `app/integrations/rabbit_consumer.py`).
43. **Bloqueante externo, documentado explícitamente: `idEpisodioExterno` viaja como `None`.** Ningún webhook de M1 provee ese dato hoy. Pendiente coordinar con M1 que lo agregue a `AltaMedicaWebhook` (ver `documentation/M6_INTEGRACION_M1_HCE.md`). Confirmado con M7 (vía su documentación) que el evento no se rechaza por esto — queda pendiente de completar de su lado.
44. **Revierte parcialmente la decisión del changelog #14** ("M6 no es intermediario del episodio... no enviamos idEpisodioExterno"). Esa decisión asumía que el payload rico era una recomendación opcional de M7; ahora M7 confirmó por escrito que es el contrato real de la integración final, no una opción descartable.
### 14.10 Corrección del payload de `CIERRE_INTERNACION` contra el contrato real de M7 (2026-07)
Una prueba end-to-end contra el broker real de RabbitMQ mostró que el evento a M7 nunca se
publicaba (`facturacion_cama_lista_event_type_id` resolvía a `None` en el deploy pese a
`event_type_id=19` estar documentado como activo — variable no seteada realmente en HF, no un
bug de código). Auditando el payload contra `M7_integration.md` de punta a punta se
encontraron 3 desvíos reales del contrato, corregidos en `app/integrations/facturacion.py`:
45. **Timestamps con sufijo `Z`, no `+00:00`.** `datetime.isoformat()` sobre un `datetime`
aware UTC produce `+00:00`; el contrato de M7 (y el resto del proyecto) usa `Z`. Nuevo
helper `_iso_z()` aplicado a `fechaIngreso`, `fechaAlta` y `timestampEvento` en ambos
payloads (evento y REST).
46. **`idPacienteExterno` como `string`, no `int`.** El ejemplo de M7 lo muestra entre
comillas (`"10500"`); el código mandaba el `int` de `cama.paciente_id`. Corregido a
`str(paciente_id)`. Mismo criterio queda documentado para `idEpisodioExterno` cuando deje
de ser `None`.
47. **Se sacan `camaId` y `camasUtilizadas` del payload del evento** (el REST fallback
conserva `camaId`, que nunca tuvo contrato escrito de M7). Ninguno de los dos es parte
del listado de campos que confirmó M7 ni del que documenta el changelog #39 de esta misma
sección — `camasUtilizadas` existía solo para alimentar una reconstrucción de tramos vía
`auditoria` (`_reconstruir_tramos`/`_tramo_desde_cama`, eliminadas) que M7 nunca pidió.
48. **Corrección del #46 (2026-07): `idPacienteExterno` vuelve a ser número, no `string`.**
Con acceso al código real de M7 (`documentation/modulo7-impl/`, compartido para
diagnosticar por qué el evento seguía sin llegarles pese al `201` del Core) se confirmó
que `InternacionM6Request.idPacienteExterno` es `Long` — el ejemplo en comillas de
`M7_integration.md` que motivó el #46 estaba desactualizado respecto a su propio código.
Revertido a número JSON en ambos payloads. El sufijo `Z` del #45 no se revierte: sus
campos de fecha son `OffsetDateTime`, que parsea `Z` y `+00:00` indistintamente, así que
no había nada que corregir ahí. Diagnóstico completo (por qué el consumer de M7 puede no
estar recibiendo nada aunque el payload esté bien) y checklist de corrección para su
equipo en `documentation/integrations/M7_debugging_evento_no_recibido.md`.
49. **`idEpisodioExterno` deja de ser una constante `None` y pasa a `cama.episodio_id`
(entero).** Hasta ahora el campo era literalmente `None` hardcodeado en
`notify_cama_lista` — no había ninguna fuente de datos. Se agregó la columna
`episodio_id` a `Cama` (mismo patrón que `solicitud_hce_id`/`alta_tipo`), un campo
homónimo opcional en `AltaMedicaWebhook`, y se persiste en `procesar_alta_medica` y se
limpia al cerrar el episodio (`cama_service.py`, junto al resto de los datos del
episodio). Mientras M1 no mande `episodio_id` en el webhook, sigue viajando `None` — el
comportamiento actual no cambia, solo queda la plomería lista para cuando M1 lo agregue
(`M6_INTEGRACION_M1_HCE.md` §4.3, pedido ahora como `integer` en vez de `string` para
mantener consistencia con `idPacienteExterno`). **Pendiente de correr en Supabase:**
`ALTER TABLE camas ADD COLUMN IF NOT EXISTS episodio_id integer;`.
50. **`episodio_id` se mueve de `AltaMedicaWebhook` a `SolicitudHceWebhook` (corrección
2026-07 del punto 49).** El punto 49 asumía que M1 podía mandar `episodio_id` recién en
el alta; al confirmar el dominio real con el equipo de M1, resultó que **M1 crea el
episodio al crear la solicitud**, no al darla de alta — así que el campo nunca iba a
llegar poblado por ese webhook. Se corrigió:
- `episodio_id` pasa a `SolicitudHceWebhook`, requerido para `tipo=INTERNACION`
(validado en `solicitud_service.resolver_solicitud`, mismo patrón que
`cama_asignada_id`) — si falta, se rechaza la aprobación (`400`) en vez de dejar que
el evento a M7 salga con `idEpisodioExterno: null`.
- Se agregó `episodio_id` a `Solicitud` (modelo + `crud/solicitud.py`). **Pendiente de
correr en Supabase:** `ALTER TABLE solicitudes ADD COLUMN IF NOT EXISTS episodio_id integer;`.
- `_aprobar_internacion` copia `sol.episodio_id → cama.episodio_id` al aprobar.
- `_aprobar_traslado` (y el segundo camino de traslado, `cama_service.asignar_cama`)
**heredan** `episodio_id` de la cama origen — es el mismo episodio del paciente, no
uno nuevo, así que M1 no lo manda en el traslado.
- `procesar_alta_medica` ya **no** toca `cama.episodio_id` — antes lo pisaba con el
valor (siempre `None`) del webhook de alta, justo antes de disparar
`notify_cama_lista`, así que el evento a M7 salía con el episodio vacío pese a que ya
estaba cargado correctamente desde la internación.
- Corregido también un gap real en `cama_service.update_cama`: la cama que un paciente
deja por **traslado** no limpiaba `episodio_id`/`solicitud_hce_id`/`fecha_ingreso` al
liberarse (`EN_LIMPIEZA → DISPONIBLE`) — solo lo hacía el camino de alta. Ahora ambos
caminos limpian el episodio de la cama que se abandona; solo `alta_tipo`/
`alta_timestamp` siguen siendo específicos de alta.
### 14.11 Reintroducción del lookup de roles (2026-07)
Una prueba end-to-end contra el Core real (login → ticket → `sso-exchange`) reveló que
`user.roles[]` viene **vacío** en la respuesta del canje SSO, pese a que el schema del Core lo
declara (`models.User.roles[]`) — contradiciendo el supuesto del changelog #27, que asumió que
siempre venía poblado y en base a eso eliminó el lookup aparte. Resultado antes del fix: **todo**
usuario recibía `403` en `sso-exchange`.
48. **`core_auth.resolve_user_roles`/`_fetch_roles_index` reintroducidos** (habían sido
retirados en #27), como **fallback**: `app/routers/auth.py::sso_exchange` solo los invoca
cuando `user.roles[]` viene vacío en el canje, no en reemplazo del camino feliz. Si el Core
algún día puebla `roles[]` en el canje, el fallback deja de dispararse sin más cambios.
49. **Fuente del fallback: `GET /roles`, no `GET /users/{id}`.** `GET /users/{id}` sería la
opción obvia por id de usuario, pero exige el permiso `users:read`, que la cuenta de
servicio de M6 no tiene. Tampoco existe un endpoint directo user-id→roles en el Core
(`/roles/{id}` toma un **role** id, no un user id; `/users/{id}/roles` solo expone
POST/DELETE). Lo único legible por la cuenta de servicio es `GET /roles` (permiso
`roles:read`), que devuelve cada rol con su `users[]` embebido — de ahí se arma un índice
`user_id → [roles]` en memoria, sin cache (se llama sólo en el fallback, ya de por sí poco
frecuente).
50. **No se reintroducen** `verify_core_token`/`get_signing_key` ni sus caches
(`jwks_cache_ttl_seconds`) — esa parte de #27 seguía siendo correcta: no hay verificación de
JWT del Core por-request, la sesión de M6 sigue siendo siempre HS256 propia.