Modulo-6 / README.md
jpsoron
Update README.md
70170fe unverified
|
Raw History Blame Contribute Delete
13.8 kB
---
title: Modulo 6
emoji: 🚀
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
---
# Health Grid – Módulo 6: Internación y Gestión de Camas
**TPO UADE – Sistema de Gestión Hospitalaria**
Módulo 6 del sistema multi-módulo Health Grid. Gestiona camas hospitalarias, solicitudes de internación/traslado y reservas de quirófano.
---
## Deploy y links
URL APIs: https://modulo-6-api.hf.space/api/v1/
URL Documentación: https://modulo-6-api.hf.space/api/v1/docs
## Levantar el proyecto
**Prerequisitos:** tener Docker instalado y corriendo. Copiar `.env.example` a `.env` y completar `DATABASE_URL` y `JWT_SECRET` antes de arrancar.
### Mac (con Colima)
Colima puede tener problemas de DNS por defecto. Levantarlo así:
```bash
colima start --dns 8.8.8.8
```
Luego:
```bash
cp .env.example .env # completar DATABASE_URL y JWT_SECRET
docker compose up --build
```
### Windows (con Docker Desktop)
Docker Desktop ya maneja DNS automáticamente:
```bash
copy .env.example .env # completar DATABASE_URL y JWT_SECRET
docker compose up --build
```
El backend queda disponible en `http://localhost:7860`.
### Desarrollo local con hot-reload (sin Docker)
```bash
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 7860 --reload
```
> Requiere Python 3.12 y tener el `.env` configurado en la raíz del repo.
### Base de datos
La app usa **Supabase** (PostgreSQL). Al arrancar, `create_all` crea las tablas automáticamente si no existen. Si necesitás resetear las tablas:
```sql
-- Ejecutar en Supabase SQL Editor
DROP TABLE IF EXISTS auditoria CASCADE;
DROP TABLE IF EXISTS reservas_quirofano CASCADE;
DROP TABLE IF EXISTS solicitudes CASCADE;
DROP TABLE IF EXISTS camas CASCADE;
```
Luego reiniciar el contenedor para que las recree.
### Tabla de auditoría
El historial de eventos de camas (solicitudes, asignaciones, traslados, cambios
de estado, bajas y reservas) se guarda en la tabla `auditoria`. Como `supabase-py`
no ejecuta DDL, se crea con un script idempotente que se conecta por `psycopg2`:
```bash
# Requiere DATABASE_URL en el .env (postgresql://USER:PASS@HOST/DB?sslmode=require)
python scripts/create_auditoria_table.py
```
Alternativamente, pegar este SQL en el Supabase SQL Editor:
```sql
CREATE TABLE IF NOT EXISTS auditoria (
id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
entidad TEXT NOT NULL, -- CAMA | SOLICITUD | RESERVA_QUIROFANO
entidad_id TEXT NOT NULL,
cama_id BIGINT, -- denormalizado: historial por cama
evento TEXT NOT NULL,
estado_anterior TEXT,
estado_nuevo TEXT,
paciente_id BIGINT,
usuario_id TEXT,
rol TEXT, -- ADMINISTRATIVO | MEDICO | LIMPIEZA | SISTEMA
origen TEXT NOT NULL DEFAULT 'API', -- API | WEBHOOK | SISTEMA
descripcion TEXT,
detalle JSONB,
hospital_id TEXT,
creado_en TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX IF NOT EXISTS idx_auditoria_cama_id ON auditoria (cama_id);
CREATE INDEX IF NOT EXISTS idx_auditoria_entidad ON auditoria (entidad, entidad_id);
CREATE INDEX IF NOT EXISTS idx_auditoria_paciente_id ON auditoria (paciente_id);
CREATE INDEX IF NOT EXISTS idx_auditoria_creado_en ON auditoria (creado_en DESC);
CREATE INDEX IF NOT EXISTS idx_auditoria_hospital_id ON auditoria (hospital_id);
```
Consulta del historial:
- `GET /api/v1/auditoria` — listado REST con filtros (`cama_id`, `entidad`,
`paciente_id`, `evento`, `fecha_desde`, `fecha_hasta`, `limit`, `offset`).
- `WS /api/v1/auditoria/ws?token=<JWT>` — envía un snapshot del historial
filtrado al conectar y luego empuja cada nuevo evento en tiempo real. Acepta
los mismos filtros como query params. El JWT va en `token` (el navegador no
puede setear el header `Authorization` en WebSocket).
---
## Documentación interactiva
| URL | Descripción |
| ---------------------------------- | ------------------------ |
| http://localhost:7860/api/v1/docs | Swagger UI (interactivo) |
| http://localhost:7860/api/v1/redoc | ReDoc (legible) |
| http://localhost:7860/health | Health check |
---
## Autenticación
El módulo usa JWT (HS256). Para desarrollo, expone un generador de tokens cuando `ENVIRONMENT=development`:
```bash
curl "http://localhost:7860/api/v1/auth/token?usuario=ADMINISTRATIVO&password=any"
```
En producción (`ENVIRONMENT=production`), este endpoint devuelve 404. Los tokens de producción deben provenir de M10 (Core).
Roles válidos: `ADMINISTRATIVO`, `MEDICO`, `LIMPIEZA`.
Usar el token en requests:
```
Authorization: Bearer <token>
```
---
## Variables de entorno requeridas
Copiar `.env.example` a `.env` y completar:
| Variable | Requerida | Descripción |
| ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------ |
| `DATABASE_URL` | **SÍ** | Cadena de conexión Neon (PostgreSQL). Formato: `postgresql://USER:PASS@HOST/DB?sslmode=require&...` |
| `JWT_SECRET` | **SÍ** | Secret de 64+ chars para firmar JWT. Generar con `python -c "import secrets; print(secrets.token_hex(32))"` |
| `JWT_ALGORITHM` | No | Algoritmo JWT (default: `HS256`) |
| `JWT_EXPIRE_MINUTES` | No | Duración del token en minutos (default: `60`) |
| `ENVIRONMENT` | No | `development` o `production` (default: `production`). En `development` habilita `/auth/token` |
| `ALLOWED_ORIGINS` | No | Lista JSON de orígenes CORS permitidos |
| `MOCK_EXTERNAL_SERVICES` | No | `true` = no llama a módulos externos (default: `true`) |
| `HTTP_TIMEOUT_SECONDS` | No | Timeout para llamadas externas en segundos (default: `5.0`) |
| `M1_HCE_URL` | No | URL del Módulo 1 - HCE |
| `M2_TURNOS_URL` | No | URL del Módulo 2 - Turnos |
| `M7_FACTURACION_URL` | No | URL del Módulo 7 - Facturación |
| `M9_MONITOREO_URL` | No | URL del Módulo 9 - Monitoreo |
| `M10_CORE_URL` | No | URL del Módulo 10 - Core |
---
## Endpoints propios
### Camas
| Método | Endpoint | Roles | Descripción |
| -------- | ----------------------------------- | ----------------------- | --------------------------------------------- |
| `GET` | `/api/v1/camas` | MEDICO, ADMIN, LIMPIEZA | Mapa de camas con estadísticas |
| `POST` | `/api/v1/camas` | ADMIN | Crear nueva cama |
| `GET` | `/api/v1/camas/disponibilidad` | MEDICO, ADMIN | Disponibilidad de quirófanos en rango horario |
| `GET` | `/api/v1/camas/{id}` | MEDICO, ADMIN | Detalle de una cama |
| `PATCH` | `/api/v1/camas/{id}` | ADMIN, LIMPIEZA | Actualizar estado/contraindicaciones |
| `DELETE` | `/api/v1/camas/{id}` | ADMIN | Baja permanente (soft delete) |
| `POST` | `/api/v1/camas/{id}/asignar` | ADMIN | Asignación/traslado directo |
| `GET` | `/api/v1/camas/{id}/reservas` | MEDICO, ADMIN | Reservas de un quirófano |
| `POST` | `/api/v1/camas/{id}/reservas` | MEDICO, ADMIN | Crear reserva programada |
| `GET` | `/api/v1/camas/{id}/reservas/{rid}` | MEDICO, ADMIN | Detalle de reserva |
| `PATCH` | `/api/v1/camas/{id}/reservas/{rid}` | ADMIN | Actualizar estado de reserva |
### Solicitudes de Internación
| Método | Endpoint | Roles | Descripción |
| ------- | -------------------------- | ------------- | --------------------------------------- |
| `GET` | `/api/v1/solicitudes` | MEDICO, ADMIN | Listar solicitudes (default: PENDIENTE) |
| `GET` | `/api/v1/solicitudes/{id}` | MEDICO, ADMIN | Detalle (ID formato `SOL-XXXXX`) |
| `PATCH` | `/api/v1/solicitudes/{id}` | ADMIN | Aprobar / rechazar solicitud |
### Webhooks entrantes
| Método | Endpoint | Emisor | Descripción |
| ------ | ---------------------------------------------------- | ------------ | ------------------------------------------------ |
| `POST` | `/api/v1/webhooks/hce/solicitud` | M1 HCE | Recibir solicitud de internación o traslado |
| `POST` | `/api/v1/webhooks/hce/alta-medica` | M1 HCE | Recibir alta médica del paciente |
| `POST` | `/api/v1/webhooks/hce/cirugia-urgente` | M1 HCE | Solicitud de cirugía urgente (desplaza reservas) |
| `POST` | `/api/v1/webhooks/turnos/{id}/cancelacion-quirofano` | M2 Turnos | Cancelar reserva de quirófano |
| `POST` | `/api/v1/webhooks/monitoreo/alerta-emergencia` | M9 Monitoreo | Poner cama en CODIGO_ROJO |
| `POST` | `/api/v1/webhooks/monitoreo/alerta-resuelta` | M9 Monitoreo | Resolver CODIGO_ROJO → OCUPADA |
---
## Mapa de integraciones
```
Módulo 6 (Internación)
│
├── [WEBHOOKS INBOUND]
│ ├── ← M1 HCE POST /webhooks/hce/*
│ ├── ← M2 Turnos POST /webhooks/turnos/*
│ └── ← M9 Monitoreo POST /webhooks/monitoreo/*
│
└── [HTTP OUTBOUND — app/integrations/]
├── → M10 Core :8010 validar paciente
├── → M1 HCE :8001 contraindicaciones + movimientos
├── → M9 Monitoreo :8009 alta/baja monitoreo
├── → M7 Facturación :8007 cama lista (post limpieza)
└── → M2 Turnos :8002 resultado de quirófano
```
Para deshabilitar las llamadas salientes durante desarrollo: `MOCK_EXTERNAL_SERVICES=true`
---
## Estructura del proyecto
```
modulo6/
├── app/ # Código fuente principal
│ ├── main.py # App factory, routers, CORS, startup
│ ├── config.py # Settings con pydantic-settings (lee .env)
│ ├── dependencies.py # BD, JWT y auth (get_db, require_roles)
│ ├── routers/ # Endpoints HTTP (solo input/output)
│ │ ├── camas.py
│ │ ├── solicitudes.py
│ │ └── webhooks.py
│ ├── services/ # Lógica de negocio
│ │ ├── cama_service.py
│ │ └── solicitud_service.py
│ ├── schemas/ # Modelos Pydantic (request/response)
│ │ ├── enums.py
│ │ ├── cama.py
│ │ ├── solicitud.py
│ │ └── reserva.py
│ ├── models/ # Modelos ORM SQLAlchemy
│ │ ├── cama.py
│ │ ├── solicitud.py
│ │ └── reserva.py
│ ├── crud/ # Acceso a datos (sin lógica de negocio)
│ │ ├── cama.py
│ │ ├── solicitud.py
│ │ └── reserva.py
│ └── integrations/ # Clientes HTTP para módulos externos
│ ├── _base.py # Helpers compartidos (timeout, headers)
│ ├── core.py # M10 - validación de pacientes
│ ├── hce.py # M1 - HCE (contraindicaciones, movimientos)
│ ├── turnos.py # M2 - resultado de quirófano
│ ├── facturacion.py # M7 - cama lista
│ └── monitoreo.py # M9 - alta/baja monitoreo
├── tests/ # Tests (espejo de app/)
│ ├── conftest.py # Fixtures: DB en memoria, cliente de test
│ ├── test_camas.py
│ └── test_solicitudes.py
├── backend/ # Código original (preservado)
├── audit/ # Reportes de auditoría técnica
├── Dockerfile # Imagen de producción (sin --reload)
├── docker-compose.yml # Orquestación: backend + PostgreSQL
├── requirements.txt # Dependencias de producción
├── .env.example # Template de variables de entorno
└── README.md # Este archivo
```
---
## Correr tests
```bash
pip install -r requirements-dev.txt
pytest tests/ -v
```