Download documentation/M6_DISEÑO.md from Modulo-6/api: direct link, hf CLI and curl.
- Browser
- Download file 69.8 kB
-
https://huggingface.co/spaces/Modulo-6/api/resolve/main/documentation/M6_DISE%C3%91O.md
- Command line
-
hf download hf://spaces/Modulo-6/api/documentation/M6_DISEÑO.md
-
curl -L -o M6_DISEÑO.md https://huggingface.co/spaces/Modulo-6/api/resolve/main/documentation/M6_DISE%C3%91O.md
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=QUIROFANOytipo=CIRUGIA. Comparte tabla y máquina de estados con Cama (ver decisión en §10). Se expone bajo su propio recurso/quirofanospor claridad de API, pero internamente es la misma entidad. - Solicitud: pedido de internación o traslado originado en HCE (M1). Identificada por
idstring (SOL-00123) y vinculada al id de origensolicitud_hce_id. Vive en estadoPENDIENTEhasta 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,SOLICITUDoRESERVA_QUIROFANO(solicitudes, aprobaciones/rechazos, asignaciones, traslados, cambios de estado, bajas, alta médica, código rojo, reservas de quirófano). Vive en la tablaauditoria, concama_iddenormalizado 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 endocs/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 sobreOCUPADA/EN_LIMPIEZA/FUERA_DE_SERVICIOdevuelve409 Conflict. CODIGO_ROJOes un overlay sobreOCUPADA: la alerta resuelta vuelve aOCUPADA, no aDISPONIBLE.- Al trasladar, la cama origen pasa a
EN_LIMPIEZAy la destino aOCUPADAen la misma transacción. BAJA_PERMANENTEes 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)
- Un médico solicita cama desde HCE. M1 hace
POST /webhooks/hce/solicitudcontipo=INTERNACION. M6 crea la solicitud en estadoPENDIENTE. - El administrativo ve la cola en el frontend (
GET /solicitudes?estado=PENDIENTE). - 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, setpaciente_id), y abre el episodio. - RECHAZAR: no se asigna nada.
- 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 (
- M6 dispara, según el caso:
- Evento
SOLICITUD_RESUELTAa M1 (bus del Core; el REST directo se deprecó 2026-07, ver §7.2). POST /internacion/ingresoa 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_MONITOREOa M9 si hubo asignación.
- Evento
- 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
- Llega como solicitud (
POST /webhooks/hce/solicitudcontipo=TRASLADO,cama_origen_id,cama_destino_solicitada_id) o se ejecuta directo por el administrativo (POST /camas/{camaId}/asignarcontipo=TRASLADO,cama_origen_id). - En la misma transacción: cama origen
→ EN_LIMPIEZA, cama destino→ OCUPADA. - Salientes:
POST /internacion/ingresoa M1 (reenvía el mismoid_episodiode la cama origen — M1 lo trata como un movimiento más del mismo episodio, no como uno nuevo), webhookBAJA_MONITOREO(cama origen) yALTA_MONITOREO(cama destino) a M9.
5.3 Cierre de episodio (alta médica)
- M1 hace
POST /webhooks/hce/alta-medica(paciente_id,medico_firmante_id,tipo_alta). - M6 cierra el episodio, libera la cama (
OCUPADA → EN_LIMPIEZA) y dispara webhookBAJA_MONITOREOa M9. - Cuando el personal marca la limpieza terminada (
PATCH /camas/{camaId}conestado=DISPONIBLEdesdeEN_LIMPIEZA), M6 dispara webhookCAMA_LISTAa M7 con el resumen del episodio (obra social, número de afiliado, diagnósticos de ingreso/egreso, fechas ycamas_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
- M1 hace
POST /webhooks/hce/cirugia-urgente.fecha_hora_iniciose interpreta como "no antes de" yfecha_hora_fin_estimada - fecha_hora_iniciocomo la duración de la cirugía — no una ventana fija: M6 decide el horario real. - M6 considera los quirófanos compatibles: mismo
hospital_id, excluidosFUERA_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, oRESERVADAcon prioridadURGENTE— estas nunca se desplazan) hasta que ninguna bloqueante solapa más. Se elige el quirófano con menorearliest_start; empata por preferencia despecialty_id(si vino en el webhook) y luego por menoridde quirófano. - Si en el hueco elegido caían reservas
PROGRAMADA(no urgentes), se reprograman — nunca se cancelan — vía el algoritmoreprogramar()(busca el próximo hueco libre para esa reserva y notifica el nuevo horario a M2 si tieneturno_id). Cada reserva desplazada guardadesplazada_por_reserva_idapuntando a la urgente que la corrió. Puede haber más de una reserva desplazada si varias caían dentro de la ventana. - La respuesta incluye la reserva urgente creada y, si hubo, la lista
reservas_desplazadas(puede tener 0, 1 o más elementos). Sisolicitud_urgencia_hce_idya se había procesado, se devuelve200con 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)
- M9 detecta emergencia y hace
POST /webhooks/monitoreo/alerta-emergencia(paciente_id). - 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). - Al estabilizarse, M9 hace
POST /webhooks/monitoreo/alerta-resueltay la cama vuelve aOCUPADA.
6. Reglas de negocio y validaciones
- Compatibilidad de contraindicaciones: antes de asignar, M6 cruza las
contraindicaciones_incompatiblesde la cama contra las contraindicaciones del paciente (traídas de HCE). Si hay intersección, la asignación se rechaza con422. Ejemplo: cama conALERGIA_LATEXincompatible no puede recibir un paciente con esa alergia. - Disponibilidad atómica: la asignación valida estado
DISPONIBLEy cambia aOCUPADAdentro 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/CIRUGIAa una internación común). - Resolución única: una solicitud
APROBADAoRECHAZADAno 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
PROGRAMADAsolo se reprograma automáticamente por unaEMERGENCIA(nunca por otra programada), y nunca se cancela por este motivo — ver §5.5. ReservasEN_CURSOo yaURGENTEnunca 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) |
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 quecontraindicaciones, ver punto 1 del changelog más abajo). El endpoint real, verificado en vivo contra M1 (documentation/integrations/openapi_docs/M1_openapi.json), esGET /api/v1/pacientes/{pacienteId}— sin prefijo/hce/— y es el que consumeapp.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_bajallevan ademáscama_iden 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}— actualizarestadoocontraindicaciones_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— requieredesde,hasta; opcionalhospital_id,specialty_id.GET /quirofanos/{quirofanoId}/reservas·POST /quirofanos/{quirofanoId}/reservasGET /quirofanos/{quirofanoId}/reservas/{reservaId}·PATCH /quirofanos/{quirofanoId}/reservas/{reservaId}
Solicitudes (Solicitudes)
GET /solicitudes— filtrosestado,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). RolesADMINISTRATIVO,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— eventosINSERT/UPDATE. El mapa de camas escucha la tabla completa; el detalle de una cama escucha filtrado porid=eq.{camaId}.auditoria— eventoINSERT. La pantalla de detalle de cama escucha filtrado porcama_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.
camasguarda también los quirófanos (sector=QUIROFANO,tipo=CIRUGIA). Es la decisión de modelo que explica queQuirofanoResponse.estadouseEstadoCamaEnumy queReservaQuirofanoResponsereferencie la cama. Alternativa rechazada: tablaquirofanosseparada, que duplicaría la máquina de estados de disponibilidad. Además de sus columnas originales,camasguarda 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 tablaepisodiosseparada (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 encamas, siguiendo el mismo patrón ya usado porultimo_movimiento_tipo.auditoriaes el log append-only de auditoría deCAMA/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 endocs/superpowers/specs/2026-06-26-auditoria-cama-design.md.- La asignación de cama (validar
DISPONIBLE→ setOCUPADA+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 consettings.sso_enabled) llama acore_auth.exchange_sso_ticket, que hacePOST /auth/sso-exchangecontra el Core (https://api.healthcare.cantero.aren el entorno compartido) y recibe{user, token}(models.AuthResponse). Eltokendel Core (RS256,{exp, iat, permissions[], user_id}) no se reenvía ni se guarda — solo se usauserpara resolver el rol. - El callback del browser (
/auth/sso?ticket=…&redirect=…) y la validación anti-open-redirect delredirectson 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 exponepermissions:managea la cuenta de servicio hoy, ni tiene permisos de dominio M6 en su catálogo; migrarrequire_rolesa 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. soninteger.Solicitud.idy los ids de origen externos (solicitud_hce_id,solicitud_urgencia_hce_id) sonstringcon 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 (NoAutenticadopara401,NoAutorizadopara403,ErrorValidacionpara400/422), referenciados con$refen todos los endpoints para mantener consistencia. - Códigos HTTP:
400payload malformado ·401sin token / token inválido ·403rol sin permiso ·404recurso inexistente ·409conflicto de estado (cama ocupada, solicitud ya resuelta) ·422regla de negocio violada (contraindicación incompatible) ·502falla 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_iden reservas:ReservaQuirofanoResponse.cama_idapunta al quirófano. Es confuso por la decisión de modelar quirófano como cama. Deuda técnica: renombrar aquirofano_iden 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
Contraindicaciones duplicado. Se eliminó
/pacientes/{pacienteId}/contraindicaciones. Queda el canónicoGET /hce/pacientes/{pacienteId}/contraindicacionesconpacienteId: integer.POST /camas/{camaId}/asignar. Se eliminó el path param fantasmaquirofanoIdycamaIdquedó comointeger.Turnos (M2). Se parametrizaron los IDs hardcodeados:
/api/v1/appointments/{appointmentId},.../cancely.../reschedule, conappointmentId: integer.AsignacionCamaResponse.tipo. Erastringlibre (el Request ya estaba bien). Se corrigió a enum{INGRESO, TRASLADO}para que Request y Response coincidan.Escala de prioridad unificada.
PrioridadSolicitudEnumse expandió de 4 a 6 niveles{MUY_BAJA, BAJA, MEDIA, ALTA, MUY_ALTA, URGENTE}, idéntica aPrioridadQuirofanoEnum. Resuelve la decisión que antes quedaba abierta.GET /api/v1/appointments/{appointmentId}(EXTRA A). Los camposconfirmed_at,checked_in_at,cancelled_at,completed_atusaban"type": "null", inválido en OpenAPI 3.0.1. Corregidos astring/format: date-time/nullable: true.POST /turnos/{turnoId}/cancelacion(EXTRA B). Los responses400,401,403eran strings vacíos sin schema. Apuntan ahora a los componentes reutilizablesErrorValidacion,NoAutenticadoyNoAutorizado.Solicitud.accion(EXTRA C). Era$refdirecto aAccionResolucionEnumsinnullable. Una solicitudPENDIENTEno tiene acción de resolución. Corregido anullable: true.WebhookCamaLista.evento(EXTRA D). Erastringlibre. Corregido a enum{CAMA_LISTA}, consistente conWebhookAltaMonitoreo.eventoyWebhookBajaMonitoreo.evento.Ext_MovimientoRequest.resultado(EXTRA E). Erastringlibre pese a que la description decía "APROBADA o RECHAZADA". Tipado como enum{APROBADA, RECHAZADA},nullable: true.Cama.numerotipo corregido. Erastringen el modelo y schema. Corregido aintegerpara reflejar que el número de cama es siempre un valor numérico.numerode quirófano unificado ainteger.QuirofanoCreateRequest.numeroyQuirofanoResponse.numerodeclarabanstring(ej."Q01"), inconsistente con que el quirófano comparte la tablacamas, dondenumeroesinteger(corrección #11). No puede ser de los dos tipos a la vez. Se unifica aintegeren ambos schemas y en el bloquequirofanos[].numerode la respuesta deGET /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 columnacamas.numeroastringy revertir #11, lo que también afecta a las camas comunes.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→integeren 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 cancelarDELETE /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 estadoRESERVADA. 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 parareschedule. - Se eliminó
get_turno. M6 no consulta turnos en M2 hoy; el clienteGET /turnos/{id}(path y enum de estado inexistentes en M2) era código muerto y se quitó.
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 alcierre-episodiorico):- Idempotencia. Se agrega
idEventoExternoderivado de forma estable (M6-CAMA-LISTA-{cama_id}-{paciente_id}-{fecha_alta}). M7 usa ese campo comoidempotencyKey; antes no lo mandábamos y M7 caía a una clave que incluía nuestrotimestamp_evento = now(), con lo que un reintento del mismo alta se tomaba como evento nuevo (riesgo de facturar dos veces). - Se quitaron
obra_social_idynumero_afiliadodel payload: no están en el DTO de M7 y los ignoraba. La cobertura la obtiene M7 directamente de M1/HCE. m7_facturacion_urlcorregido de:8007a:8080(puerto real de M7).- Decisión de diseño: M6 no es intermediario del episodio. No enviamos
idEpisodioExternoni datos de internación/actos médicos. Sin episodio, M7 deja el evento enRECIBIDO_PENDIENTE_DATOSy 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 aPOST /api/integracion/internacion/cierre-episodio(el endpoint "recomendado" por M7), que exige ese payload rico.
- Idempotencia. Se agrega
14.2 Pendientes
securityglobal vacío. El spec declara el esquemaBearerAuthpero dejasecurityvacío a nivel raíz. Falta declararsecurity: [{ BearerAuth: [] }]para que la protección sea explícita en el contrato.WebhookCamaListacampos obligatorios. Más allá del enum deevento, conviene marcareventoypaciente_idcomorequired, en línea con los otros webhooks salientes.- Renombrar
cama_iden reservas de quirófano.ReservaQuirofanoResponse.cama_idapunta al quirófano. Renombrar aquirofano_idcuando se coordine con el frontend (ver §13).
14.3 Auditoría y tiempo real (2026-06)
- Tabla
auditoriaagregada. Nuevo recursoGET /auditoria(rolesADMINISTRATIVO,MEDICO) con historial filtrable de eventos sobreCAMA/SOLICITUD/RESERVA_QUIROFANO. Instrumentado en la capa de servicios, best-effort (nunca rompe la operación de negocio). Detalle endocs/superpowers/specs/2026-06-26-auditoria-cama-design.md. - 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, endpointWS /auditoria/ws). Se eliminó y se reemplazó por Supabase Realtime, consumido directo por el frontend sobre las tablascamasyauditoria(§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. - Rol LIMPIEZA: alcance de lectura ampliado, escritura más restringida. Antes,
GET /camasfiltraba para LIMPIEZA solo las camas enEN_LIMPIEZA. Ahora LIMPIEZA ve todas las camas (igual que MEDICO/ADMINISTRATIVO), pero la única escritura permitida es la transiciónEN_LIMPIEZA → DISPONIBLEvíaPATCH /camas/{camaId}, enforced encama_service.update_cama(no solo en el frontend). Se cerró además un loophole donde LIMPIEZA podía modificarcontraindicaciones_incompatiblesenviándolo sin acompañar un cambio deestado. - Rol MEDICO: removido permiso de escritura indebido.
POST /quirofanos/{quirofanoId}/reservas(crear reserva de quirófano) aceptaba el rolMEDICO, pese a que MEDICO debe ser estrictamente de solo lectura sobre todo el dominio de M6. Corregido a soloADMINISTRATIVO. Matriz completa de permisos por rol endocumentation/roles.md.
14.4 Cirugía urgente: algoritmo de priorización ASAP (2026-06)
- 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) deRESERVADA, sin filtrar porhospital_id/estado operable del quirófano, y sin soportar más de una reserva desplazada. Se reemplazó por un algoritmo ASAP:fecha_hora_iniciodel webhook pasa a interpretarse como "no antes de" y la duración se deriva defecha_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 reservasPROGRAMADAsi caen dentro de la ventana elegida. Las reservasEN_CURSOo yaURGENTEson bloqueantes y nunca se desplazan. - Contrato de respuesta cambiado.
CirugiaUrgenteResponse.reserva_desplazada(objeto unull) se reemplazó porreservas_desplazadas(array, puede tener 0, 1 o más elementos). ActualizarM6_openapi.jsony cualquier cliente que integre contra este webhook. CirugiaUrgenteWebhook.specialty_idagregado (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).- Idempotencia devuelve
200, no201. Antes el webhook respondía siempre201, incluso cuandosolicitud_urgencia_hce_idya existía (reintento de M1). Corregido:200para el caso idempotente,201solo cuando se crea una reserva nueva. - 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ófanosEN_LIMPIEZA(además de los ya excluidosFUERA_DE_SERVICIO/BAJA_PERMANENTE). Corregido encrear_reserva_urgente. - Bug de persistencia corregido.
reserva_crud.savesolo persistíaestado/observaciones/desplazada_por_reserva_id; el nuevo horario de una reserva reprogramada nunca se guardaba en la tablareservas_quirofanode M6 (solo se notificaba a M2). Ahorasavetambién persistefecha_hora_inicio/fecha_hora_fin_estimada. - Seam
reprogramar(). Se introdujocama_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)
- Nuevo endpoint
POST /auth/sso-exchange. Canjea un ticket SSO de un solo uso del Core (app/routers/auth.py, activo conSSO_ENABLED=true) por una sesión propia de M6: JWT HS256 con el rol ya resuelto. Request{ticket}; response{token, user, rol}; errores401(ticket inválido/usado/expirado),403(roles del usuario sin mapeo a M6),404(SSO deshabilitado),502(Core inalcanzable). ActualizarM6_openapi.jsoncon este endpoint. - Eliminado el lookup
GET /rolesy la verificación de JWT del Core por-request. El rol ya no se resuelve con una llamada aparte cacheada: viene directo enuser.roles[]de la respuesta del canje SSO (models.AuthResponse→models.User→models.Role). Se retiraroncore_auth.resolve_user_roles,_fetch_roles_index,verify_core_token,get_signing_keyy sus caches (_roles_index_cache,_jwks_cache); con ellos, las settingsjwks_cache_ttl_seconds/core_roles_cache_ttl_seconds. Se conservamap_core_roles_to_internal(§11), que ahora traduceuser.roles[].nameen vez de un índice cacheado. app/config.py::auth_modereemplazado porsso_enabled. Ya no existe un modo de validación por-request alternativo — la sesión de M6 es siempre HS256 propia.sso_enabled(defaultFalse) solo habilita/deshabilita el endpoint de canje.
14.6 Migración de webhooks entrantes al bus de eventos del Core (2026-07)
- 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). - Nuevo consumer
app/integrations/rabbit_consumer.py(aio-pika, gateado porsettings.rabbitmq_consumer_enabled, defaultFalsehasta tener host/puerto/vhost real del broker). Despacha porevent_type_namea las mismas funciones de servicio que ya usa el router REST — sin lógica de negocio nueva. - Nuevo publisher
app/integrations/core_events.py::publish_eventpara las 4 notificaciones salientes de §7.2. No-op explícito mientras elevent_type_idcorrespondiente seaNone(default hasta que M1/M9/M7 compartan el suyo — cada uno crea y posee su propio evento, no M6). Las 4 funcionesnotify_*(hce.notify_resultado_solicitud,monitoreo.notify_alta/notify_baja,facturacion.notify_cama_lista) quedan en dual-write: REST sin cambios +publish_eventadicional. - 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)
- Eliminado
facturacion.notify_cierre_cama. Apuntaba aPOST /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í tuvonotify_cama_lista(changelog #14). Estaba activamente cableada enprocesar_alta_medicay era bloqueante:if not facturacion.notify_cierre_cama(...): raise 502— conmock_external_services=Falseen producción, cualquier alta médica real hubiera fallado con502contra un endpoint que M7 nunca implementó. Sin test para el camino real (pasaba siempre por el atajo demock_external_services=True). - Corregido el gating bloqueante de
monitoreo.notify_bajaenprocesar_alta_medica. Era el único de los 5 call sites denotify_alta/notify_bajaen todo el código que trataba la llamada como bloqueante (if not ...: raise 502); los otros 4 (cama_service.pyingreso/traslado,solicitud_service.pyaprobar 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 esmonitoreo.notify_baja(paciente_id)sin gate. - 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_falleytest_alta_medica_no_llama_a_facturacion(tests/test_webhooks.py).
14.8 Auto-transición de reservas de quirófano por horario (2026-07)
- Nuevo
cama_service.procesar_transiciones_automaticas(§5.4): avanzaRESERVADA→EN_CURSOyEN_CURSO→COMPLETADAsegúnfecha_hora_inicio/fecha_hora_fin_estimada, reusandoupdate_reserva_estado— mismos side-effects que la transición manual, cero lógica de negocio duplicada. Nuevas queriesreserva_crud.get_pendientes_de_inicio/get_pendientes_de_fin. - Nuevo endpoint
POST /api/v1/internal/reservas/tick(app/routers/internal.py), protegido con secreto compartido (settings.internal_tick_secret, headerX-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)
- M7 confirmó su integración por escrito (
documentation/integrations/M7_integration.md): colafacturacion.requests,event_type_id: 19(activado en config, ya noNone),publisher_module: "modulo_6". Verificado en vivo:POST /events/logcontra el Core real con esteevent_type_iddevuelve201. - 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_listaahora arma dos payloads distintos para los dos canales (app/integrations/facturacion.py). - 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 denotify_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_medicay se limpian al cerrar el episodio. En un traslado, se heredan de la cama origen (mismo episodio), no de la solicitud de traslado. core_events.publish_eventgana el parámetropublisher_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".solicitud_service.procesar_alta_medicacambia de firma: recibe elAltaMedicaWebhookcompleto en vez de solopaciente_id, para poder persistirtipo_alta/timestampen la cama. Actualizados los dos call sites (app/routers/webhooks.py,app/integrations/rabbit_consumer.py).- Bloqueante externo, documentado explícitamente:
idEpisodioExternoviaja comoNone. Ningún webhook de M1 provee ese dato hoy. Pendiente coordinar con M1 que lo agregue aAltaMedicaWebhook(verdocumentation/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. - 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:
Timestamps con sufijo
Z, no+00:00.datetime.isoformat()sobre undatetimeaware UTC produce+00:00; el contrato de M7 (y el resto del proyecto) usaZ. Nuevo helper_iso_z()aplicado afechaIngreso,fechaAltaytimestampEventoen ambos payloads (evento y REST).idPacienteExternocomostring, noint. El ejemplo de M7 lo muestra entre comillas ("10500"); el código mandaba elintdecama.paciente_id. Corregido astr(paciente_id). Mismo criterio queda documentado paraidEpisodioExternocuando deje de serNone.Se sacan
camaIdycamasUtilizadasdel payload del evento (el REST fallback conservacamaId, 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 —camasUtilizadasexistía solo para alimentar una reconstrucción de tramos víaauditoria(_reconstruir_tramos/_tramo_desde_cama, eliminadas) que M7 nunca pidió.Corrección del #46 (2026-07):
idPacienteExternovuelve a ser número, nostring. Con acceso al código real de M7 (documentation/modulo7-impl/, compartido para diagnosticar por qué el evento seguía sin llegarles pese al201del Core) se confirmó queInternacionM6Request.idPacienteExternoesLong— el ejemplo en comillas deM7_integration.mdque motivó el #46 estaba desactualizado respecto a su propio código. Revertido a número JSON en ambos payloads. El sufijoZdel #45 no se revierte: sus campos de fecha sonOffsetDateTime, que parseaZy+00:00indistintamente, 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 endocumentation/integrations/M7_debugging_evento_no_recibido.md.idEpisodioExternodeja de ser una constanteNoney pasa acama.episodio_id(entero). Hasta ahora el campo era literalmenteNonehardcodeado ennotify_cama_lista— no había ninguna fuente de datos. Se agregó la columnaepisodio_idaCama(mismo patrón quesolicitud_hce_id/alta_tipo), un campo homónimo opcional enAltaMedicaWebhook, y se persiste enprocesar_alta_medicay se limpia al cerrar el episodio (cama_service.py, junto al resto de los datos del episodio). Mientras M1 no mandeepisodio_iden el webhook, sigue viajandoNone— 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 comointegeren vez destringpara mantener consistencia conidPacienteExterno). Pendiente de correr en Supabase:ALTER TABLE camas ADD COLUMN IF NOT EXISTS episodio_id integer;.episodio_idse mueve deAltaMedicaWebhookaSolicitudHceWebhook(corrección 2026-07 del punto 49). El punto 49 asumía que M1 podía mandarepisodio_idrecié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_idpasa aSolicitudHceWebhook, requerido paratipo=INTERNACION(validado ensolicitud_service.resolver_solicitud, mismo patrón quecama_asignada_id) — si falta, se rechaza la aprobación (400) en vez de dejar que el evento a M7 salga conidEpisodioExterno: null.- Se agregó
episodio_idaSolicitud(modelo +crud/solicitud.py). Pendiente de correr en Supabase:ALTER TABLE solicitudes ADD COLUMN IF NOT EXISTS episodio_id integer;. _aprobar_internacioncopiasol.episodio_id → cama.episodio_idal aprobar._aprobar_traslado(y el segundo camino de traslado,cama_service.asignar_cama) heredanepisodio_idde la cama origen — es el mismo episodio del paciente, no uno nuevo, así que M1 no lo manda en el traslado.procesar_alta_medicaya no tocacama.episodio_id— antes lo pisaba con el valor (siempreNone) del webhook de alta, justo antes de dispararnotify_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 limpiabaepisodio_id/solicitud_hce_id/fecha_ingresoal liberarse (EN_LIMPIEZA → DISPONIBLE) — solo lo hacía el camino de alta. Ahora ambos caminos limpian el episodio de la cama que se abandona; soloalta_tipo/alta_timestampsiguen 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.
core_auth.resolve_user_roles/_fetch_roles_indexreintroducidos (habían sido retirados en #27), como fallback:app/routers/auth.py::sso_exchangesolo los invoca cuandouser.roles[]viene vacío en el canje, no en reemplazo del camino feliz. Si el Core algún día pueblaroles[]en el canje, el fallback deja de dispararse sin más cambios.- Fuente del fallback:
GET /roles, noGET /users/{id}.GET /users/{id}sería la opción obvia por id de usuario, pero exige el permisousers: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}/rolessolo expone POST/DELETE). Lo único legible por la cuenta de servicio esGET /roles(permisoroles:read), que devuelve cada rol con suusers[]embebido — de ahí se arma un índiceuser_id → [roles]en memoria, sin cache (se llama sólo en el fallback, ya de por sí poco frecuente). - No se reintroducen
verify_core_token/get_signing_keyni 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.