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
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 FastAPIGET /health— health check públicoGET /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 BDrequire_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/estadocrear_cama(db, data)— crea cama validando duplicadosobtener_cama(db, cama_id)— detalle con 404 automáticoactualizar_cama(db, cama_id, data)— actualización parcialdesactivar_cama(db, cama_id)— soft delete (activa=False)asignar_cama(db, cama_id, data)— asigna paciente + valida contraindicaciones + notifica M1/M9/M7listar_reservas(db, cama_id, filtros)— reservas de un quirófanocrear_reserva(db, cama_id, data)— reserva programada con detección de conflictosobtener_reserva(db, reserva_id)— detalle de reservaactualizar_estado_reserva(db, reserva_id, data)— cambio de estado con transición validadacrear_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/tipoobtener_solicitud(db, solicitud_id)— detalle con 404crear_solicitud_desde_webhook(db, data)— recibe solicitud de M1 HCEactualizar_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.pyes un único archivo monolítico para 5 integraciones distintas- No hay tests (ningún archivo
test_*.pyencontrado) - 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()