Download documentation/algoritmo_urgencias.md from Modulo-6/api: direct link, hf CLI and curl.
- Browser
- Download file 15.5 kB
-
https://huggingface.co/spaces/Modulo-6/api/resolve/main/documentation/algoritmo_urgencias.md
- Command line
-
hf download hf://spaces/Modulo-6/api/documentation/algoritmo_urgencias.md
-
curl -L -o algoritmo_urgencias.md https://huggingface.co/spaces/Modulo-6/api/resolve/main/documentation/algoritmo_urgencias.md
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 deM6_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:
- Conseguir un quirófano ya, si hay alguno libre.
- Si no hay ninguno libre, encontrar el quirófano que se va a liberar antes y ocupar ese hueco.
- 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.
- 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)
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
RESERVADAconprioridad == "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):
- Trae las reservas futuras del quirófano con
reserva_crud.get_futuras(db, cama_id, no_antes_de): todas lasRESERVADA/EN_CURSOcuyo fin es posterior ano_antes_de, ordenadas por inicio. - Arranca con
inicio = no_antes_de,fin = inicio + duracion. - Mientras exista alguna reserva bloqueante que solape
[inicio, fin)(r.fecha_hora_inicio < fin and r.fecha_hora_fin_estimada > inicio), empujainicio = r.fecha_hora_fin_estimada(y recalculafin). Como una reserva empujada puede toparse con otra bloqueante más adelante, el loop se repite hasta que ninguna bloqueante solapa más. - Una vez estabilizado
inicio, junta las desplazables: reservasRESERVADAno 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_idviene, 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:
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)
- 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"). - Ante empate, el que matchea
specialty_id(si se pidió). - Ante empate final, menor
idde 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):
- Se le asigna
desplazada_por_reserva_id = reserva_urgente.id. - Se llama a
reprogramar(db, r, no_antes_de=reserva_urgente.fecha_hora_fin_estimada, motivo=...)(detalle en §5). - Se audita (
RESERVA_DESPLAZADA), condetalle={"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()
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:
- Duración preservada:
duracion = reserva.fecha_hora_fin_estimada - reserva.fecha_hora_inicio(la duración original de la reserva desplazada, no cambia). - Busca hueco libre en el mismo quirófano: arranca en
no_antes_dey, mientrasreserva_crud.get_superpuestas(db, reserva.cama_id, inicio, inicio+duracion, exclude_id=reserva.id)devuelva algo, empujainicioalfecha_hora_fin_estimadamá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. - Actualiza la reserva en memoria: nuevo
fecha_hora_inicio/fecha_hora_fin_estimada, y agrega elmotivoa susobservaciones(concatenado si ya tenía algo). - Notifica a M2 si corresponde: si
reserva.turno_idexiste (la reserva desplazada nació de un turno real, no fue creada por otra urgencia), llama aturnos.reschedule_turno(turno_id, starts_at, ends_at)— ver §6. - 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.savesolo persistíaestado,observacionesydesplazada_por_reserva_id— el nuevo horario de una reserva reprogramada nunca quedaba guardado en la tablareservas_quirofanode M6, solo se le avisaba a M2. Ahorasavetambién persistefecha_hora_inicioyfecha_hora_fin_estimada(app/crud/reserva.py). CirugiaUrgenteResponse.reservas_desplazadases una lista (antes era un único objetoreserva_desplazadanullable). 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 esesolicitud_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:
- Arma el payload real (
{starts_at, ends_at}con el formato de M2) sin importar si está mockeado o no. - 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. - En modo real (
MOCK_EXTERNAL_SERVICES=false), hace elPATCHreal contraM2_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
409seco; podría valer la pena escalar o encolar en una versión futura.