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):

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)

  1. 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.
  2. 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.
  3. 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.
  4. 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)

  1. 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.
  2. 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.
  3. 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).
  4. 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.
  5. 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.
  6. 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.
  7. 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)

  1. 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.
  2. 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.
  3. 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)

  1. 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).
  2. 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.
  3. 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.
  4. 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)

  1. 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).
  2. 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.
  3. 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)

  1. 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.
  2. 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)

  1. 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.
  2. 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).
  3. 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.
  4. 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".
  5. 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).
  6. 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.
  7. 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:

  1. 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).

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

  3. 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ó.

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

  5. 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;.

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

  1. 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.
  2. 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).
  3. 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.