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`](integrations/M10_integration.md). Para el porqué de la migración y su alcance, ver [`M6_DISEÑO.md`](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:
```http
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):
```http
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`:
```http
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**:
```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`)
```bash
# 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.