api / audit /STRUCTURE.md
Mate11
Pirmer commit
5f12c93
|
Raw History Blame Contribute Delete
13 kB

Mapa de Estructura — Módulo 6 (Health Grid)

Generado: 2026-05-03 | Agente A (Structure Mapper)


Árbol de archivos anotado

modulo6/
├── docker-compose.yml          # Orquestación: backend (puerto 8006) + PostgreSQL 16
├── .env                        # Variables de entorno (credenciales activas — NO commitear)
├── README.md                   # Documentación básica del proyecto
└── backend/
    ├── Dockerfile              # Imagen python:3.12-slim, expone puerto 8006
    ├── requirements.txt        # 9 dependencias de producción, todas pinadas con ==
    ├── main.py                 # Punto de entrada FastAPI: app factory, routers, CORS, startup
    ├── config.py               # Settings via pydantic-settings (BaseSettings), lee .env
    ├── database.py             # Engine SQLAlchemy, SessionLocal, Base, get_db()
    ├── models/
    │   ├── __init__.py         # Re-exporta todos los modelos ORM
    │   ├── cama.py             # ORM: Cama (tabla `camas`)
    │   ├── solicitud.py        # ORM: SolicitudInternacion (tabla `solicitudes_internacion`)
    │   └── reserva.py          # ORM: ReservaQuirofano (tabla `reservas_quirofano`)
    ├── schemas/
    │   ├── __init__.py         # Vacío
    │   ├── enums.py            # Todos los Enum de dominio (EstadoCama, TipoSolicitud, etc.)
    │   ├── cama.py             # Pydantic schemas: CamaCreate/Response, AsignacionRequest, etc.
    │   ├── solicitud.py        # Pydantic schemas: Solicitud + webhooks de M1/M2
    │   └── reserva.py          # Pydantic schemas: Reserva + webhooks de M2/M9
    ├── auth/
    │   ├── __init__.py         # Vacío
    │   ├── jwt_handler.py      # create_access_token / decode_token (python-jose)
    │   └── dependencies.py     # get_current_user, require_roles() factory
    ├── services/
    │   ├── __init__.py         # Vacío
    │   ├── external_client.py  # Cliente HTTP centralizado para llamadas a M1/M7/M9/M10/M2
    │   ├── cama_service.py     # Lógica de negocio: camas, asignación, reservas quirófano
    │   └── solicitud_service.py# Lógica de negocio: solicitudes de internación/traslado
    └── routers/
        ├── __init__.py         # Vacío
        ├── camas.py            # Endpoints REST de camas y reservas de quirófano
        ├── solicitudes.py      # Endpoints REST de solicitudes de internación
        └── webhooks.py         # Endpoints inbound de webhooks (M1, M2, M9)

Descripción por módulo

main.py

Propósito: Factory de la aplicación FastAPI. Registra routers, configura CORS, evento de startup (crea tablas), handlers de error globales, health check y endpoint de desarrollo para generar tokens JWT.

Exportaciones clave:

  • app — instancia FastAPI
  • GET /health — health check público
  • GET /api/v1/auth/token — generador de JWT para desarrollo (no protegido)

Dependencias externas: fastapi, sqlalchemy, database.py, config.py, todos los routers.


config.py

Propósito: Centraliza la configuración de la aplicación mediante pydantic-settings. Lee variables del archivo .env.

Variables configuradas:

Variable Descripción
database_url Cadena de conexión PostgreSQL
jwt_secret Clave de firma JWT (default inseguro hardcodeado)
jwt_algorithm Algoritmo JWT (HS256)
access_token_expire_minutes Expiración del token (60 min)
m1_hce_url URL Módulo 1 - HCE
m2_turnos_url URL Módulo 2 - Turnos
m7_facturacion_url URL Módulo 7 - Facturación
m9_monitoreo_url URL Módulo 9 - Monitoreo
m10_core_url URL Módulo 10 - Core

database.py

Propósito: Configuración de SQLAlchemy v2. Crea engine, SessionLocal, Base declarativa y la función generadora get_db() para inyección de dependencias.

Patrón DI: get_db() es un generador que hace yield db en try/finally, garantizando cierre de sesión.


models/cama.py

Propósito: Modelo ORM para la entidad Cama (cama hospitalaria).

Tabla: camas Campos clave: id, numero (String 20), sector, tipo (GENERAL/UCI/PEDIATRICA/NEONATAL/QUIROFANO), estado (DISPONIBLE/OCUPADA/EN_LIMPIEZA/FUERA_DE_SERVICIO), hospital_id, activa, paciente_id, fecha_ultimo_cambio

Relaciones: reservas (one-to-many → ReservaQuirofano)


models/solicitud.py

Propósito: Modelo ORM para solicitudes de internación (INTERNACION o TRASLADO).

Tabla: solicitudes_internacion Campos clave: id, paciente_id, tipo (INTERNACION/TRASLADO), estado (PENDIENTE/APROBADA/RECHAZADA/EN_PROCESO/COMPLETADA/CANCELADA), prioridad, cama_id_origen, cama_id_destino, diagnostico_ingreso, observaciones


models/reserva.py

Propósito: Modelo ORM para reservas de quirófano.

Tabla: reservas_quirofano Campos clave: id, cama_id, turno_id, medico_id, paciente_id, estado (RESERVADA/EN_CURSO/COMPLETADA/CANCELADA), prioridad (PROGRAMADA/URGENTE/EMERGENCIA), origen (HCE/QUIROFANO/URGENCIAS), fecha_hora_inicio, fecha_hora_fin_estimada


schemas/enums.py

Propósito: Define todos los Enum de dominio del módulo como clases Python str, Enum.

Enums definidos: EstadoCamaEnum, TipoCamaEnum, EstadoSolicitudEnum, TipoSolicitudEnum, PrioridadSolicitudEnum, EstadoReservaEnum, PrioridadQuirofanoEnum, OrigenReservaEnum


auth/jwt_handler.py

Propósito: Creación y decodificación de tokens JWT con python-jose.

Funciones: create_access_token(data, expires_delta, extra), decode_token(token)

Algoritmo: HS256. Incluye exp en payload. El secret se lee de settings.jwt_secret.


auth/dependencies.py

Propósito: Dependencias de FastAPI para autenticación y autorización.

Funciones:

  • get_current_user(token, db) — decodifica JWT, valida usuario en BD
  • require_roles(*roles) — factory que retorna dependencia verificando rol del usuario

services/external_client.py

Propósito: Cliente HTTP centralizado para todas las llamadas salientes a módulos externos. Única fuente de llamadas httpx en el proyecto.

Funciones de integración:

Función Destino Propósito
validar_paciente(paciente_id) M10 Core Verifica existencia del paciente
obtener_contraindicaciones(paciente_id) M1 HCE Lista contraindicaciones médicas
notificar_movimiento_cama(...) M1 HCE Notifica asignación/egreso de cama
notificar_alta_monitoreo(...) M9 Monitoreo Alta del paciente en monitoreo
notificar_baja_monitoreo(...) M9 Monitoreo Baja del paciente en monitoreo
notificar_cama_lista(...) M7 Facturación Aviso de cama lista para facturación
notificar_resultado_quirofano(...) M2 Turnos Resultado de la cirugía al módulo de turnos

Patrón de error: except Exception: return None — fallas silenciadas sin logging.


services/cama_service.py

Propósito: Lógica de negocio para gestión de camas y reservas de quirófano.

Funciones principales:

  • listar_camas(db, filtros) — listado con filtros de sector/tipo/estado
  • crear_cama(db, data) — crea cama validando duplicados
  • obtener_cama(db, cama_id) — detalle con 404 automático
  • actualizar_cama(db, cama_id, data) — actualización parcial
  • desactivar_cama(db, cama_id) — soft delete (activa=False)
  • asignar_cama(db, cama_id, data) — asigna paciente + valida contraindicaciones + notifica M1/M9/M7
  • listar_reservas(db, cama_id, filtros) — reservas de un quirófano
  • crear_reserva(db, cama_id, data) — reserva programada con detección de conflictos
  • obtener_reserva(db, reserva_id) — detalle de reserva
  • actualizar_estado_reserva(db, reserva_id, data) — cambio de estado con transición validada
  • crear_reserva_urgente(db, data) — reserva de emergencia con lógica de desplazamiento

services/solicitud_service.py

Propósito: Lógica de negocio para solicitudes de internación y traslado.

Funciones principales:

  • listar_solicitudes(db, filtros) — listado con filtros de estado/tipo
  • obtener_solicitud(db, solicitud_id) — detalle con 404
  • crear_solicitud_desde_webhook(db, data) — recibe solicitud de M1 HCE
  • actualizar_estado_solicitud(db, solicitud_id, data) — aprobación/rechazo/completado
  • _aprobar_internacion(db, solicitud, cama_id) — asigna cama para internación
  • _aprobar_traslado(db, solicitud) — mueve paciente entre camas

routers/camas.py

Propósito: Endpoints REST para gestión de camas y reservas de quirófano. Solo parsea input, llama service, retorna response.

Endpoints:

Método Path Roles Descripción
GET /api/v1/camas MEDICO/ADMIN/LIMPIEZA Listar camas con filtros
POST /api/v1/camas ADMIN Crear cama
GET /api/v1/camas/disponibilidad MEDICO/ADMIN Disponibilidad de quirófanos
GET /api/v1/camas/{id} MEDICO/ADMIN/LIMPIEZA Detalle de cama
PATCH /api/v1/camas/{id} ADMIN Actualizar cama
DELETE /api/v1/camas/{id} ADMIN Desactivar cama
POST /api/v1/camas/{id}/asignar MEDICO/ADMIN Asignar paciente
GET /api/v1/camas/{id}/reservas MEDICO/ADMIN Listar reservas quirófano
POST /api/v1/camas/{id}/reservas MEDICO/ADMIN* Crear reserva quirófano
GET /api/v1/camas/{id}/reservas/{rid} MEDICO/ADMIN Detalle reserva
PATCH /api/v1/camas/{id}/reservas/{rid} MEDICO/ADMIN Actualizar estado reserva

*⚠️ POST /reservas usa get_current_user en lugar de require_roles — bug de autorización.


routers/solicitudes.py

Propósito: Endpoints REST para solicitudes de internación.

Endpoints:

Método Path Roles Descripción
GET /api/v1/solicitudes MEDICO/ADMIN Listar solicitudes con filtros
GET /api/v1/solicitudes/{id} MEDICO/ADMIN Detalle de solicitud
PATCH /api/v1/solicitudes/{id} MEDICO/ADMIN Aprobar/rechazar/actualizar

routers/webhooks.py

Propósito: Endpoints inbound para eventos enviados por módulos externos.

Endpoints:

Método Path Origen Evento
POST /api/v1/webhooks/hce/solicitud M1 HCE Nueva solicitud de internación
POST /api/v1/webhooks/hce/alta-medica M1 HCE Alta médica del paciente
POST /api/v1/webhooks/hce/cirugia-urgente M1 HCE Solicitud de cirugía urgente
POST /api/v1/webhooks/turnos/{turno_id}/cancelacion-quirofano M2 Turnos Cancelación de turno quirúrgico
POST /api/v1/webhooks/monitoreo/alerta-emergencia M9 Monitoreo Alerta de emergencia activa
POST /api/v1/webhooks/monitoreo/alerta-resuelta M9 Monitoreo Resolución de alerta

Resumen de arquitectura observada

El proyecto implementa una arquitectura de 4 capas:

Router (HTTP) → Service (negocio) → ORM Model (datos) → PostgreSQL
                     ↓
              external_client.py → Módulos externos (M1/M2/M7/M9/M10)

Inyección de dependencias: correctamente implementada mediante Depends(get_db) para sesión de BD y Depends(require_roles(...)) para autorización.

Separación de concerns: mayoritariamente respetada — los routers no contienen lógica de negocio. Las llamadas HTTP salientes están centralizadas en external_client.py.

Puntos débiles arquitectónicos:

  • No existe capa CRUD/Repository separada — los services acceden directamente al ORM
  • external_client.py es un único archivo monolítico para 5 integraciones distintas
  • No hay tests (ningún archivo test_*.py encontrado)
  • La lógica de errores de integración está silenciada (fallas no visibles)

Mapa de integraciones externas

Módulo 6 (Internación)
    │
    ├── [INBOUND WEBHOOKS]
    │   ├── ← M1 HCE (solicitud, alta-medica, cirugia-urgente)
    │   ├── ← M2 Turnos (cancelacion-quirofano)
    │   └── ← M9 Monitoreo (alerta-emergencia, alerta-resuelta)
    │
    └── [OUTBOUND HTTP]
        ├── → M10 Core   :8010 — validar_paciente()
        ├── → M1 HCE     :8001 — obtener_contraindicaciones(), notificar_movimiento_cama()
        ├── → M9 Monitoreo:8009 — notificar_alta/baja_monitoreo()
        ├── → M7 Facturación:8007 — notificar_cama_lista()
        └── → M2 Turnos  :8002 — notificar_resultado_quirofano()