api / audit /STRUCTURE.md
Mate11
Pirmer commit
5f12c93
|
Raw History Blame
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()
```