|
Download audit/STRUCTURE.md from Modulo-6/api: direct link, hf CLI and curl.
- Browser
- Download file 13 kB
-
https://huggingface.co/spaces/Modulo-6/api/resolve/main/audit/STRUCTURE.md
- Command line
-
hf download hf://spaces/Modulo-6/api/audit/STRUCTURE.md
-
curl -L -o STRUCTURE.md https://huggingface.co/spaces/Modulo-6/api/resolve/main/audit/STRUCTURE.md
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() | |
| ``` | |