api / documentation /M6_EVENTOS_RABBITMQ.md
juampisor's picture
Inhabilitacion M7 + docu
a440d33
|
Raw History Blame Contribute Delete
17.2 kB

Bus de eventos del Core (M10): cola y eventos de M6

Health Grid · Módulo 6 (Internación y Gestión de Camas)

Referencia completa de la infraestructura de RabbitMQ/eventos que M6 tiene dada de alta en el Core y de cómo se conecta con el código. Para el contrato genérico del bus (cómo crear colas/eventos/bindings, formato del envelope) ver integrations/M10_integration.md. Para el porqué de la migración y su alcance, ver M6_DISEÑO.md §7.5.


1. Resumen

M6 recibe notificaciones de M1 (HCE), M9 (Monitoreo) y M2 (Turnos) por dos vías en paralelo durante la transición:

  • REST directo (app/routers/webhooks.py) — el mecanismo original, sigue activo sin cambios.
  • Bus de eventos del Core (RabbitMQ, configurado y creado vía la API del Core) — el mecanismo nuevo, hacia el que se está migrando.

Del lado saliente (M6 → M1/M9/M7), el código de publicación al bus ya está escrito y conectado, pero apagado: no hay tráfico real hasta que cada equipo receptor comparta su event_type_id.

Cirugía urgente (POST /webhooks/hce/cirugia-urgente) queda fuera de esta migración — sigue siendo solo REST (ver §5).


2. Infraestructura creada en el Core (real, ya ejecutada)

2.1 Cola

Cola Tipo DLQ
internacion.requests requests internacion.requests.dlq

Creada con:

POST /rabbit/queues
Authorization: Bearer <token cuenta de servicio>
Content-Type: application/json

{ "queue_name": "internacion", "queue_type": "requests" }

M6 es un único consumer sobre esta cola; distingue el tipo de mensaje por event_type_name del envelope (ver §4), igual que antes distinguía por el path del webhook REST.

2.2 Event types entrantes (M1/M9/M2 → M6)

Los 5 eventos que otros módulos usan para mandarle "requests" a M6, todos bindeados a internacion.requests:

event_type_id name Emisor Reemplaza (REST) Payload (schema Pydantic)
14 internacion.solicitud.creada M1 HCE POST /webhooks/hce/solicitud SolicitudHceWebhook
15 internacion.alta-medica.registrada M1 HCE POST /webhooks/hce/alta-medica AltaMedicaWebhook
16 internacion.alerta-emergencia.detectada M9 Monitoreo POST /webhooks/monitoreo/alerta-emergencia AlertaEmergenciaRequest
17 internacion.alerta-resuelta.notificada M9 Monitoreo POST /webhooks/monitoreo/alerta-resuelta AlertaResueltaRequest
18 internacion.turno.cancelado M2 Turnos POST /turnos/{turnoId}/cancelacion CancelacionQuirofanoRequest + turno_id

Todos source_module: "internacion". Ninguno lleva correlation_id/response_event_id: son notificaciones fire-and-forget, no esperan respuesta.

Nota sobre internacion.turno.cancelado (id 18): en el REST equivalente, turno_id viaja en el path (/turnos/{turnoId}/cancelacion). Como el bus no tiene "path", el payload del evento debe incluir turno_id explícitamente junto al resto de los campos de CancelacionQuirofanoRequest (motivo, tipo_cancelacion, timestamp).

Creados con (uno por fila):

POST /events/types
Authorization: Bearer <token cuenta de servicio>
Content-Type: application/json

{ "name": "internacion.solicitud.creada", "description": "...", "source_module": "internacion" }

2.3 Bindings

Los 5 event types de arriba están bindeados a internacion.requests:

POST /rabbit/bindings
Authorization: Bearer <token cuenta de servicio>
Content-Type: application/json

{ "event_id": 14, "queue_name": "internacion.requests" }

(repetido para los ids 15, 16, 17 y 18)

2.4 Lo que NO se creó

No hay ninguna cola ni event type mock/placeholder para el lado saliente (§5). Se decidió explícitamente no generar infraestructura ni tráfico contra el Core compartido para simular a M1/M9/M7 — ver M6_DISEÑO.md §14.6, punto 32.


3. Credenciales y conexión

  • API REST del Core (alta de colas/eventos/bindings, POST /events/log): cuenta de servicio de M6, CORE_SERVICE_EMAIL/CORE_SERVICE_PASSWORD (.env). Es la misma cuenta que M6 ya usa para las llamadas salientes a M1/M2/M7/M10 (app/integrations/core_auth.py::get_service_token).
  • Broker RabbitMQ (consumo directo de la cola): las mismas credenciales — el email de la cuenta de servicio ya está provisionado como usuario de RabbitMQ (confirmado: POST /rabbit/queues y POST /rabbit/bindings exigen que el usuario autenticado exista como usuario de RabbitMQ, y ambas llamadas funcionaron).
  • Host/puerto/vhost del broker: pendiente de conseguir con el equipo de Core — hoy son placeholders (localhost:5672, vhost /). Sin este dato, el consumer no puede conectar de verdad (ver §6).

4. Formato de los mensajes

El mensaje que llega por RabbitMQ tiene un envelope externo (lo arma el Core), y adentro un payload que viaja como string JSON:

{
  "event_type_id": 15,
  "event_type_name": "internacion.alta-medica.registrada",
  "source_module": "internacion",
  "publisher_module": "hce",
  "log_id": 89,
  "payload": "{\"paciente_id\": 999, \"medico_firmante_id\": 1, \"tipo_alta\": \"ALTA_MEDICA\", \"timestamp\": \"2026-07-09T12:00:00Z\"}",
  "published_at": "2026-07-10T01:24:06Z"
}

El consumer de M6 (§6) parsea primero el envelope, después el payload interno, y recién ahí valida contra el schema Pydantic correspondiente.


5. Qué queda fuera de esta migración

Cirugía urgente (POST /webhooks/hce/cirugia-urgente) no tiene evento en el bus. El webhook REST devuelve sincrónicamente qué quirófano/reserva se asignó y qué reservas se desplazaron; no existe hoy un canal de respuesta asíncrono equivalente. Migrarla requeriría acordar con M1 un evento de respuesta (correlation_id + response_event_id, como el patrón billing/appointments de M10_integration.md). Sigue siendo solo REST.

Los 5 endpoints REST de app/routers/webhooks.py (equivalentes a los eventos de §2.2) se mantienen activos sin cambios mientras dura la transición. No hay fecha de corte: se retiran cuando M1, M9 y M2 confirmen que ya publican por la cola.


6. Lado entrante: el consumer (app/integrations/rabbit_consumer.py)

Cliente async sobre aio-pika. Por cada mensaje de internacion.requests:

  1. Parsea el envelope externo y extrae event_type_name y payload (como string).

  2. Parsea payload con json.loads.

  3. Despacha por event_type_name (dispatch()) a la misma función de servicio que usa el router REST — sin lógica de negocio nueva:

    event_type_name Función de servicio
    internacion.solicitud.creada solicitud_service.recibir_solicitud
    internacion.alta-medica.registrada solicitud_service.procesar_alta_medica
    internacion.alerta-emergencia.detectada solicitud_service.procesar_alerta_emergencia
    internacion.alerta-resuelta.notificada solicitud_service.procesar_alerta_resuelta
    internacion.turno.cancelado solicitud_service.cancelar_reserva_por_turno
  4. Si el procesamiento fue exitoso, hace ack. Si el JSON es malformado, el event_type_name no está mapeado, o el servicio de negocio lanza una excepción, hace reject(requeue=False) — el mensaje cae a internacion.requests.dlq en vez de reintentarse en loop.

La deduplicación por id de origen (solicitud_hce_id, etc., exigida en M6_DISEÑO.md §6) sigue viviendo dentro de esas mismas funciones de servicio — no se reimplementó nada.

Wiring: app/main.py arranca rabbit_consumer.run_consumer() como task de asyncio en el lifespan, solo si settings.rabbitmq_consumer_enabled es True (default False — ver §3, falta el broker real). Al apagar la app, la task se cancela prolijamente.

Verificado en vivo (2026-07): se publicó un evento real contra el id 15 (POST /events/log) y se confirmó que dispatch() lo procesa de punta a punta: parseo → validación Pydantic → procesar_alta_medica → la cama pasa a EN_LIMPIEZA → ack. Esto prueba la lógica de consumo; falta conectar contra el broker real para que corra en producción.


7. Lado saliente: el publisher (app/integrations/core_events.py)

publish_event(event_type_id: int | None, payload: dict, publisher_module: str = "internacion") -> bool:

  • Si event_type_id is None → no-op: loguea a nivel info y devuelve True, sin ningún request HTTP.
  • Si hay un id configurado → POST /events/log real contra el Core ({"event_type_id", "publisher_module", "payload": json.dumps(payload)}).

Los 4 puntos de notificación saliente de M6 (M6_DISEÑO.md §7.2):

Función Notificación Receptor Config del event_type_id Estado
hce.notify_resultado_solicitud SOLICITUD_RESUELTA M1 HCE hce_solicitud_resuelta_event_type_id Activo — solo evento, event_type_id=25
monitoreo.notify_alta ALTA_MONITOREO M9 Monitoreo monitoreo_alta_event_type_id Activo — event_type_id=26, confirmado por M9
monitoreo.notify_baja BAJA_MONITOREO M9 Monitoreo monitoreo_baja_event_type_id Activo — event_type_id=27, confirmado por M9
facturacion.notify_cama_lista CIERRE_INTERNACION (facturacion.internacion.cama-lista.requested) M7 Facturación facturacion_cama_lista_event_type_id Pausado — facturacion_cierre_habilitado=false, no se manda nada (ni evento ni REST)

El evento/cola de cada notificación lo crea y comparte el módulo receptor, no M6 (misma regla que aplica al revés en §2.2). Su payload es distinto entre sí — ver app/integrations/facturacion.py::notify_cama_lista y M6_DISEÑO.md §7.2/§14.9 para el detalle completo del de M7, incluido el bloqueante de idEpisodioExterno.

Corrección 2026-07 — SOLICITUD_RESUELTA deja de ser dual-write. M1 estaba leyendo las aprobaciones como rechazadas. Se detectó que el REST directo (POST /hce/solicitudes/{id}/ resultado) apuntaba a un path que no existe en el contrato real de M1 (su OpenAPI expone POST /solicitudes-cama/{id}/resolver con el schema SolicitudCamaResolver, que usa el campo decision: aceptada|rechazada, no resultado: APROBADA|RECHAZADA). Se deprecó el REST directo — hce.notify_resultado_solicitud ahora publica solo el evento del bus. Pendiente de confirmar con M1: si su consumer de eventos usa el mismo vocabulario decision/aceptada en vez de resultado/APROBADA, el problema original podría persistir por el bus — no se tocó el payload del evento en esta corrección, solo se sacó el REST.

Pausa manual 2026-07 — CIERRE_INTERNACION (M7) desactivado. Nueva setting facturacion_cierre_habilitado (default false) corta notify_cama_lista antes de armar cualquier payload — no sale ni evento ni REST a M7 mientras esté en false. Reactivar poniendo la variable en true (sin otro cambio de código).

Corrección 2026-07 (cama_id en los eventos de M9): ALTA_MONITOREO/BAJA_MONITOREO ahora llevan también cama_id en el payload — M9 lo necesita para saber a qué cama corresponde el alta/baja de monitoreo. Regla de qué cama va en cada notificación: en un ingreso, notify_alta lleva la cama destino; en un traslado, notify_baja lleva la cama origen (la que el paciente deja) y notify_alta lleva la cama destino (la nueva); en un alta médica, notify_baja lleva la cama que se libera. Ver app/integrations/monitoreo.py.

Corrección 2026-07 (auditoría contra el contrato real de M7): una prueba end-to-end contra el broker real mostró que el evento a M7 nunca salía (facturacion_cama_lista_event_type_id resolvía a None en el deploy pese a estar documentado como activo — variable no seteada realmente en HF, no un bug de código; verificar con GET /api/v1/_debug/settings). De paso se auditó el payload contra M7_integration.md y se corrigieron 3 desvíos reales: los timestamps iban con sufijo +00:00 en vez de Z, idPacienteExterno iba como int en vez del string que mostraba el ejemplo de la doc, y el payload incluía camaId/camasUtilizadas — dos campos que ni M7_integration.md ni M6_DISEÑO.md §7.2 documentan como parte del evento acordado (se sacaron, junto con la reconstrucción de tramos vía auditoria que solo existía para alimentarlos).

Segunda corrección (2026-07, tras acceder al código real de M7): con el repo de M7 disponible (documentation/modulo7-impl/) se confirmó que InternacionM6Request.idPacienteExterno es Long, no String — el ejemplo de M7_integration.md que motivó el cambio anterior estaba desactualizado respecto al código. Se revirtió idPacienteExterno a número JSON en ambos payloads (evento y REST). El sufijo Z no hizo falta revertirlo: fechaIngreso/fechaAlta/timestampEvento son OffsetDateTime, que parsea Z y +00:00 indistintamente. Diagnóstico completo y checklist de corrección para el equipo de M7 (por qué el evento sigue sin llegarles pese al 201 del Core) en documentation/integrations/M7_debugging_evento_no_recibido.md.

Tercera corrección (2026-07): idEpisodioExterno deja de ser una constante None. Ahora sale de cama.episodio_id (columna nueva, mismo patrón que solicitud_hce_id), como número entero — consistente con idPacienteExterno.

Cuarta corrección (2026-07): la fuente real de episodio_id es la solicitud, no el alta. Se pidió originalmente a M1 en internacion.alta-medica.registrada (§4.3 de M6_INTEGRACION_M1_HCE.md), asumiendo que M1 lo tenía recién al dar el alta. El dominio real es otro: M1 crea el episodio al crear la solicitud. El campo se movió a internacion.solicitud.creada (requerido para tipo=INTERNACION), se persiste en Solicitud, se copia a cama.episodio_id al aprobar la internación, se hereda de la cama origen en el traslado (mismo paciente, mismo episodio), y se limpia de la cama que un paciente abandona —por alta o por traslado— cuando esa cama se libera de verdad. El webhook de alta médica ya no toca episodio_id en absoluto: antes lo pisaba con None justo antes de mandar el evento a M7, que es lo que causaba el idEpisodioExterno: null pese a que el episodio ya estaba cargado. Ver M6_DISEÑO.md §14 punto 50 y M6_INTEGRACION_M1_HCE.md §4.3 para el detalle completo.

Pendiente correr en Supabase: ALTER TABLE solicitudes ADD COLUMN IF NOT EXISTS episodio_id integer; (la de camas ya está aplicada).


8. Configuración (app/config.py / .env)

# Consumer entrante
RABBITMQ_CONSUMER_ENABLED=false   # true cuando se tenga el broker real
RABBITMQ_HOST=localhost           # placeholder — pendiente el dato real del broker compartido
RABBITMQ_PORT=5672
RABBITMQ_VHOST=/
INTERNACION_REQUESTS_QUEUE=internacion.requests

# Publisher saliente:
HCE_SOLICITUD_RESUELTA_EVENT_TYPE_ID=25   # solo evento — REST deprecado
MONITOREO_ALTA_EVENT_TYPE_ID=26
MONITOREO_BAJA_EVENT_TYPE_ID=27
FACTURACION_CAMA_LISTA_EVENT_TYPE_ID=19
FACTURACION_CIERRE_HABILITADO=false        # pausa manual — M7 no recibe nada mientras esté en false

Las credenciales del broker (login/password en aio_pika.connect_robust) son CORE_SERVICE_EMAIL/CORE_SERVICE_PASSWORD, ya definidas para el resto de la integración con el Core — no hay settings de usuario/password nuevas para RabbitMQ.


9. Pendientes

  • Host/puerto/vhost reales del broker RabbitMQ compartido — sin esto, RABBITMQ_CONSUMER_ENABLED=true no puede conectar. Único bloqueante para que el consumer corra contra el broker de verdad.
  • event_type_id de M1 (SOLICITUD_RESUELTA) — resuelto: M1 confirmó event_type_id=25, ya activo.
  • event_type_id de M9 (ALTA_MONITOREO, BAJA_MONITOREO) — resuelto: M9 confirmó event_type_id=26/27, ya activos.
  • event_type_id de M7 (CAMA_LISTA) — resuelto: M7 confirmó event_type_id=19, ya activo.
  • episodio_id de M1 — pendiente que M1 agregue este campo a internacion.solicitud.creada (requerido para tipo=INTERNACION, ya no a alta-medica — ver corrección 2026-07 en §7 de este doc). Ver M6_DISEÑO.md §14 punto 50 y documentation/M6_INTEGRACION_M1_HCE.md §4.3.
  • Coordinar con M1/M9/M2 la migración de sus emisores hacia los 5 eventos entrantes de §2.2, y una fecha de retiro de los webhooks REST equivalentes una vez confirmada.
  • Cirugía urgente (§5): decisión pendiente de si migrar a un patrón request/response por eventos, condicionada a acordar el evento de respuesta con M1.

10. Tests

  • tests/test_rabbit_consumer.py — despacho por event_type_name, manejo de payload malformado, ack/reject.
  • tests/test_core_events.py — publish_event no-op sin id / publica con id; los 4 notify_* siguen haciendo el mismo request REST de siempre y además llaman a publish_event (hoy inerte).
  • tests/test_webhooks.py — la vía REST entrante, sin cambios.