# 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() ```