# Algoritmo de priorización de cirugías urgentes **Módulo 6 · Quirófanos** > Este documento detalla la implementación del algoritmo que resuelve `POST /webhooks/hce/cirugia-urgente`. Es un desarrollo de `M6_DISEÑO.md` §5.5 (que manda como resumen de negocio) y del changelog §14.4 (que resume qué cambió respecto de la versión anterior). Ante cualquier diferencia entre este documento y el código, manda el código — actualizar este archivo si el algoritmo cambia. --- ## 1. El problema que resuelve M1 (HCE) avisa que un médico necesita quirófano **lo antes posible** para una cirugía urgente. Una urgencia tiene prioridad sobre cualquier cirugía que no sea también urgente. El sistema tiene que: 1. Conseguir un quirófano ya, si hay alguno libre. 2. Si no hay ninguno libre, encontrar el quirófano que se va a liberar antes y ocupar ese hueco. 3. Si el próximo turno de ese quirófano tiene una cirugía programada de menor prioridad, reprogramarla (nunca cancelarla) para hacerle lugar a la urgencia. 4. Si ese hueco también está ocupado por otra urgencia, no tocarla y evaluar el siguiente quirófano candidato, hasta encontrar el mejor lugar posible. ## 2. Modelo horario: ASAP, no ventana fija El payload del webhook (`CirugiaUrgenteWebhook`, `app/schemas/reserva.py`) trae `fecha_hora_inicio` y `fecha_hora_fin_estimada`, pero **no se usan como una ventana que haya que respetar tal cual**. Se reinterpretan así: - `no_antes_de = fecha_hora_inicio` — el horario más temprano en el que la cirugía podría arrancar, según M1. - `duracion = fecha_hora_fin_estimada - fecha_hora_inicio` — cuánto va a durar la cirugía. M6 **calcula su propio inicio** (`inicio_elegido`), que puede coincidir con `no_antes_de` (si había quirófano libre) o ser posterior (si hubo que esperar o desplazar). La reserva urgente que se crea usa siempre `inicio_elegido` y `inicio_elegido + duracion`, nunca los valores crudos del webhook. Esto es deliberado: con una ventana fija no existe el concepto de "el quirófano que se libera antes", porque un quirófano está libre en esa ventana exacta o no lo está. El "próximo en liberarse" solo tiene sentido si M6 puede correr el inicio hacia adelante. Campo opcional adicional: `specialty_id` — preferencia de especialidad del quirófano. No es excluyente: si no hay quirófano libre de esa especialidad a tiempo, se usa cualquier otro compatible del hospital antes que dejar la urgencia sin asignar (ver §4). ## 3. Piezas del algoritmo Todo vive en `app/services/cama_service.py`. ### 3.1 `_es_bloqueante(r)` (línea ~559) ```python def _es_bloqueante(r: ReservaQuirofano) -> bool: return r.estado == "EN_CURSO" or r.prioridad == "URGENTE" ``` Una reserva es **bloqueante** si: - está `EN_CURSO` (la cirugía ya está pasando — no se puede tocar bajo ningún concepto), o - es `RESERVADA` con `prioridad == "URGENTE"` (otra urgencia ya confirmada — nunca se desplaza por una urgencia nueva). Las bloqueantes **nunca se reprograman**. Definen cuándo un quirófano se libera de verdad. ### 3.2 `_earliest_start(db, cama_id, no_antes_de, duracion)` (línea ~565) Calcula, para un quirófano puntual, el inicio más temprano factible ("cuándo se libera este quirófano para esta cirugía"). Algoritmo (sweep): 1. Trae las reservas futuras del quirófano con `reserva_crud.get_futuras(db, cama_id, no_antes_de)`: todas las `RESERVADA`/`EN_CURSO` cuyo fin es posterior a `no_antes_de`, ordenadas por inicio. 2. Arranca con `inicio = no_antes_de`, `fin = inicio + duracion`. 3. Mientras exista alguna reserva **bloqueante** que solape `[inicio, fin)` (`r.fecha_hora_inicio < fin and r.fecha_hora_fin_estimada > inicio`), empuja `inicio = r.fecha_hora_fin_estimada` (y recalcula `fin`). Como una reserva empujada puede toparse con otra bloqueante más adelante, el loop se repite hasta que ninguna bloqueante solapa más. 4. Una vez estabilizado `inicio`, junta las **desplazables**: reservas `RESERVADA` **no urgentes** que caen dentro de `[inicio, fin)`. Pueden ser **cero, una o varias**. Devuelve `(inicio, desplazables)`. **Por qué es un sweep y no un "primero, segundo, tercer más próximo"**: empujar sobre una sola bloqueante a la vez y volver a chequear es lo que garantiza encontrar el inicio *real* más temprano, incluso si hay varias bloqueantes en cadena (p. ej. una `EN_CURSO` seguida de una `URGENTE` ya reservada justo después). ### 3.3 `crear_reserva_urgente(db, data)` (línea ~636) Orquesta todo el flujo. Devuelve `(reserva_urgente, reservas_desplazadas, created)`. **Paso 1 — Idempotencia.** Busca por `solicitud_urgencia_hce_id` (`reserva_crud.get_by_urgencia_hce_id`). Si ya existe, devuelve `(existing, [], False)` sin tocar nada más. El router responde `200` en vez de `201` en este caso (ver §6). **Paso 2 — Candidatos.** `cama_crud.get_quirofanos(db, hospital_id=data.hospital_id, exclude_estados=["FUERA_DE_SERVICIO", "BAJA_PERMANENTE", "EN_LIMPIEZA"])`. Dos filtros duros: - **Hospital**: si `data.hospital_id` viene, solo se consideran quirófanos de ese hospital (nunca cruza de sede). Si no viene, se consideran todos. - **Estado operable**: se excluyen quirófanos fuera de servicio, dados de baja o en limpieza — no importa qué tan "libres" estén de reservas, no se les puede asignar una cirugía. Si no queda ningún candidato → `409 SIN_QUIROFANO_COMPATIBLE`. **Paso 3 — Mejor quirófano.** Para cada candidato se calcula `_earliest_start`, y se elige el mínimo con este orden de desempate: ```python def _orden(candidato): q, inicio, _ = candidato specialty_match = 0 if (data.specialty_id is not None and q.specialty_id == data.specialty_id) else 1 return (inicio, specialty_match, q.id) quirofano, inicio_elegido, desplazables = min(candidatos, key=_orden) ``` 1. Menor `inicio` (el que se libera antes gana — esto es lo que en la conversación de diseño se llamó "el próximo en liberarse"). 2. Ante empate, el que matchea `specialty_id` (si se pidió). 3. Ante empate final, menor `id` de quirófano (determinismo). **Paso 4 — Crear la urgente.** Se arma `data_ajustada` (copia de `data` con `fecha_hora_inicio=inicio_elegido` y `fecha_hora_fin_estimada=inicio_elegido + duracion`) y se persiste con `reserva_crud.create_urgente(db, quirofano.id, data_ajustada)` — `origen=EMERGENCIA`, `prioridad=URGENTE`, `estado=RESERVADA`. Se audita (`RESERVA_URGENTE`). **Paso 5 — Reprogramar las desplazadas.** Para cada reserva en `desplazables` (ordenadas por `fecha_hora_inicio`): 1. Se le asigna `desplazada_por_reserva_id = reserva_urgente.id`. 2. Se llama a `reprogramar(db, r, no_antes_de=reserva_urgente.fecha_hora_fin_estimada, motivo=...)` (detalle en §5). 3. Se audita (`RESERVA_DESPLAZADA`), con `detalle={"desplazada_por_reserva_id": ..., "turno_id": ...}`. ## 4. Mapeo caso por caso (narrativa de negocio → código) | Caso descrito | Qué hace el algoritmo | |---|---| | Hay un quirófano disponible ya | `_earliest_start` da `inicio == no_antes_de` para ese quirófano y es el mínimo global → se asigna directo, `reservas_desplazadas = []`. | | Todos ocupados, hay que buscar el que se libera antes | Se corre `_earliest_start` en **todos** los candidatos y se toma el mínimo — no es un recorrido secuencial "primero, segundo, tercero", es un mínimo global sobre todos a la vez. | | El siguiente turno de ese quirófano está libre | La reserva bloqueante (si la hay) libera el quirófano en `r.fecha_hora_fin_estimada`, y no hay ninguna `RESERVADA` justo después → `desplazables = []`, se ocupa ese instante. | | El siguiente turno tiene una programada de menor prioridad | Cae dentro de `[inicio, inicio+duracion)` tras el sweep → entra a `desplazables` → se reprograma (§5), nunca se cancela. | | El siguiente turno es también una urgencia | Es bloqueante (`prioridad == URGENTE`) → nunca se desplaza; `_earliest_start` empuja el inicio más allá de su fin, o directamente ese quirófano deja de ser competitivo y gana otro con un `inicio` menor. | | Hay que seguir buscando el "segundo, tercer más próximo en liberarse" | No hace falta iterarlo a mano: el `min()` sobre todos los candidatos ya contempla, para cada quirófano, cuál es su propio próximo hueco libre real (empujando sobre todas sus bloqueantes en cadena), así que el resultado final ya es "el mejor entre todos los próximos en liberarse". | | Cirugía en curso en el quirófano candidato | Es bloqueante (`estado == EN_CURSO`) → nunca se desplaza; el inicio se empuja hasta `r.fecha_hora_fin_estimada`. | | Varias reservas programadas caen en la ventana elegida | `desplazables` puede tener más de un elemento (ventanas arbitrarias, no slots fijos) → se reprograman todas, en orden de `fecha_hora_inicio`. | | Ningún quirófano operable en el hospital pedido | `409 SIN_QUIROFANO_COMPATIBLE` antes de intentar nada más. | | M1 reintenta el mismo webhook (mismo `solicitud_urgencia_hce_id`) | Se devuelve la reserva ya creada, `reservas_desplazadas = []`, sin crear nada nuevo. Response `200` en vez de `201`. | ## 5. Reprogramación de una reserva desplazada — `reprogramar()` ```python def reprogramar(db: Client, reserva: ReservaQuirofano, no_antes_de: datetime, motivo: str) -> ReservaQuirofano ``` Es el algoritmo que reubica **una** reserva ya desplazada. Se invoca una vez por cada elemento de `desplazables`, con `no_antes_de = reserva_urgente.fecha_hora_fin_estimada` (es decir: "no antes de que termine la cirugía urgente que la corrió"). Pasos: 1. **Duración preservada**: `duracion = reserva.fecha_hora_fin_estimada - reserva.fecha_hora_inicio` (la duración original de la reserva desplazada, no cambia). 2. **Busca hueco libre en el mismo quirófano**: arranca en `no_antes_de` y, mientras `reserva_crud.get_superpuestas(db, reserva.cama_id, inicio, inicio+duracion, exclude_id=reserva.id)` devuelva algo, empuja `inicio` al `fecha_hora_fin_estimada` más tardío de las solapadas. A diferencia de `_earliest_start` (que solo esquiva bloqueantes), acá se esquiva **cualquier** reserva activa — la prioridad es no dejar dos reservas superpuestas en la tabla, no negociar prioridades entre ellas. 3. **Actualiza la reserva en memoria**: nuevo `fecha_hora_inicio`/`fecha_hora_fin_estimada`, y agrega el `motivo` a sus `observaciones` (concatenado si ya tenía algo). 4. **Notifica a M2 si corresponde**: si `reserva.turno_id` existe (la reserva desplazada nació de un turno real, no fue creada por otra urgencia), llama a `turnos.reschedule_turno(turno_id, starts_at, ends_at)` — ver §6. 5. **Persiste**: `reserva_crud.save(db, reserva)`. **Lo que garantiza:** la reserva reprogramada nunca queda con un horario que choque con otra reserva activa del mismo quirófano en la tabla `reservas_quirofano`. **Lo que NO hace todavía (alcance de esta tarea, pendiente para la siguiente):** - No evalúa mover la reserva a **otro quirófano** si el próximo hueco en el suyo es demasiado tardío. - No **cascadea**: si el hueco elegido choca con otra reserva de menor prioridad, hoy simplemente sigue empujando la reserva actual más tarde, en vez de desplazar a esa otra reserva de menor prioridad para acomodarse antes. Estas dos limitaciones están marcadas con `TODO` explícito en el docstring de `reprogramar()` en el código. ## 6. Persistencia y contrato de respuesta - **Bug corregido**: antes, `reserva_crud.save` solo persistía `estado`, `observaciones` y `desplazada_por_reserva_id` — el nuevo horario de una reserva reprogramada nunca quedaba guardado en la tabla `reservas_quirofano` de M6, solo se le avisaba a M2. Ahora `save` también persiste `fecha_hora_inicio` y `fecha_hora_fin_estimada` (`app/crud/reserva.py`). - **`CirugiaUrgenteResponse.reservas_desplazadas`** es una lista (antes era un único objeto `reserva_desplazada` nullable). Cada elemento: `{reserva_id, cama_id, turno_id, prioridad_original, notificado_a_m2}`. - **Códigos de respuesta** (`app/routers/webhooks.py::recibir_cirugia_urgente`): - `201` — se creó una reserva urgente nueva (con o sin desplazamientos). - `200` — idempotencia: ya existía una reserva para ese `solicitud_urgencia_hce_id`. - `409 SIN_QUIROFANO_COMPATIBLE` — no hay ningún quirófano operable para el hospital indicado. - `422` — payload inválido (p. ej. `fecha_hora_inicio >= fecha_hora_fin_estimada`). ## 7. Notificación a M2 (mock) Cuando `reprogramar()` mueve una reserva que tiene `turno_id` (es decir, nació de una reserva programada real, no de otra urgencia), llama a `turnos.reschedule_turno(turno_id, starts_at, ends_at)` (`app/integrations/turnos.py`), que sigue el contrato de `documentation/M2_openapi.json` (`PATCH /appointments/{id}/reschedule`): body `{starts_at, ends_at}` en formato `"YYYY-MM-DD HH:mm:ss"`. Con `MOCK_EXTERNAL_SERVICES=true` (default), **no sale ninguna llamada de red** — decisión de arquitectura documentada en `M6_DISEÑO.md` §7.4 (el mock vive en la capa de clientes, no en la red). Pero a diferencia de una versión anterior que cortaba en silencio, ahora: 1. Arma el payload real (`{starts_at, ends_at}` con el formato de M2) sin importar si está mockeado o no. 2. En modo mock, lo loguea (`[MOCK M2] PATCH .../appointments/{turno_id}/reschedule payload=...`) junto con una respuesta enlatada con la forma real de M2 (`{message, notification_id}` con UUID) — para que quede visible en los logs del backend qué se le habría informado a M2 sobre ese turno. 3. En modo real (`MOCK_EXTERNAL_SERVICES=false`), hace el `PATCH` real contra `M2_TURNOS_URL`. `notificado_a_m2` en la respuesta del webhook se deriva de `bool(reserva.turno_id)` — es `true` si la reserva desplazada tenía turno asociado (sin importar si el modo es mock o real). ## 8. Archivos involucrados | Archivo | Rol | |---|---| | `app/services/cama_service.py` | `_es_bloqueante`, `_earliest_start`, `reprogramar`, `crear_reserva_urgente` — el algoritmo completo. | | `app/crud/reserva.py` | `get_futuras` (reservas activas futuras de un quirófano, para `_earliest_start`), `get_superpuestas` (solapamiento exacto, para `reprogramar` y para chequeos de reservas programadas), `save` (persiste estado + horario + `desplazada_por_reserva_id`), `create_urgente`, `get_by_urgencia_hce_id`. | | `app/schemas/reserva.py` | `CirugiaUrgenteWebhook` (payload entrante, con `specialty_id` opcional), `CirugiaUrgenteResponse` (con `reservas_desplazadas: list[...]`). | | `app/routers/webhooks.py` | `recibir_cirugia_urgente` — arma la respuesta HTTP y decide `200` vs `201`. | | `app/integrations/turnos.py` | `reschedule_turno` — notificación (mock o real) a M2. | | `tests/test_webhooks.py` | Casos de test: quirófano libre, sin compatibles, exclusión de estados no operables, desplazamiento simple y múltiple, `EN_CURSO` bloqueante, `URGENTE` bloqueante con alternativa, idempotencia. | ## 9. Pendiente (fuera de alcance de esta versión) - Diseño completo de `reprogramar()`: cambio de quirófano cuando el hueco propio es muy tardío, y cascada de desplazamientos (cuando el hueco elegido para la reserva desplazada choca con otra de menor prioridad). - Lock transaccional para el caso de dos urgencias concurrentes sobre el mismo conjunto de quirófanos (hoy no hay bloqueo de fila explícito en este flujo). - Qué hacer cuando no hay ningún quirófano operable: hoy es un `409` seco; podría valer la pena escalar o encolar en una versión futura.