File size: 10,289 Bytes
5f12c93 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 | # Log de Refactorización — Módulo 6
> Fecha: 2026-05-03 | Phase 2 — Reorganización estructural
---
## Resumen de cambios
| Tipo | Cantidad |
|------|----------|
| Archivos creados (nuevos) | 31 |
| Archivos modificados | 2 |
| Archivos preservados (sin tocar) | Todos los de `backend/` |
| Archivos eliminados | 0 |
---
## Archivos creados
### Núcleo de la aplicación
| Archivo creado | Origen | Razón |
|---------------|--------|-------|
| `app/__init__.py` | Nuevo | Marca `app/` como paquete Python |
| `app/main.py` | `backend/main.py` | Reubicación + mejoras: logging estructurado, CORS con orígenes explícitos, guard de entorno en `/auth/token` |
| `app/config.py` | `backend/config.py` | Reubicación + mejoras: `SettingsConfigDict` (pydantic v2), campos obligatorios sin default, `environment`, `allowed_origins`, `http_timeout_seconds` |
| `app/dependencies.py` | `backend/database.py` + `backend/auth/jwt_handler.py` + `backend/auth/dependencies.py` | Fusión de 3 módulos en dependencias compartidas; agrega `db.rollback()` ante excepciones, logging en decode_token |
### Modelos ORM
| Archivo creado | Origen | Razón |
|---------------|--------|-------|
| `app/models/__init__.py` | `backend/models/__init__.py` | Reubicación con re-exports explícitos |
| `app/models/cama.py` | `backend/models/cama.py` | Reubicación; actualiza import de `Base` a `app.dependencies` |
| `app/models/solicitud.py` | `backend/models/solicitud.py` | Reubicación; actualiza import de `Base` |
| `app/models/reserva.py` | `backend/models/reserva.py` | Reubicación; actualiza import de `Base` |
### Schemas Pydantic
| Archivo creado | Origen | Razón |
|---------------|--------|-------|
| `app/schemas/__init__.py` | Nuevo | Marca directorio como paquete |
| `app/schemas/enums.py` | `backend/schemas/enums.py` | Reubicación sin cambios funcionales |
| `app/schemas/cama.py` | `backend/schemas/cama.py` | Mejoras: `AsignacionCamaRequest.tipo` → `Literal["INGRESO","TRASLADO"]`, `field_validator` en campos de texto, `CamaResponse` usa enums en lugar de `str`, agrega `DisponibilidadQuirofanosResponse` |
| `app/schemas/solicitud.py` | `backend/schemas/solicitud.py` | Reubicación; actualiza imports al nuevo path |
| `app/schemas/reserva.py` | `backend/schemas/reserva.py` | Mejoras: `model_validator` verifica `fecha_inicio < fecha_fin` en `ReservaQuirofanoCreateRequest` y `CirugiaUrgenteWebhook` |
### Capa de integración (nueva — extraída de external_client.py)
| Archivo creado | Origen | Razón |
|---------------|--------|-------|
| `app/integrations/__init__.py` | Nuevo | Marca directorio como paquete |
| `app/integrations/_base.py` | `backend/services/external_client.py` (helpers `_post`, `_get`) | Centraliza helpers HTTP; agrega logging de warnings en excepciones (elimina swallow silencioso); timeout configurable via `settings.http_timeout_seconds` |
| `app/integrations/core.py` | `backend/services/external_client.py` (función `validate_patient`) | Aísla M10 en módulo dedicado; imports `datetime` movidos a nivel de módulo |
| `app/integrations/hce.py` | `backend/services/external_client.py` (funciones `get_patient_contraindicaciones`, `notify_movimiento`) | Aísla M1; imports `datetime` movidos a nivel de módulo; función renombrada a `get_contraindicaciones` |
| `app/integrations/monitoreo.py` | `backend/services/external_client.py` (funciones `notify_alta_monitoreo`, `notify_baja_monitoreo`) | Aísla M9; funciones renombradas a `notify_alta`/`notify_baja`; imports `datetime` movidos |
| `app/integrations/facturacion.py` | `backend/services/external_client.py` (función `notify_cama_lista`) | Aísla M7 |
| `app/integrations/turnos.py` | `backend/services/external_client.py` (función `notify_resultado_quirofano`) | Aísla M2 |
### Capa CRUD/Repository (nueva — extraída de services)
| Archivo creado | Origen | Razón |
|---------------|--------|-------|
| `app/crud/__init__.py` | Nuevo | Marca directorio como paquete |
| `app/crud/cama.py` | `backend/services/cama_service.py` (operaciones ORM) | Extrae acceso a BD de la capa de negocio; centraliza `db.query`, `db.add`, `db.commit`, `db.refresh`; elimina duplicación con `solicitud_service` |
| `app/crud/solicitud.py` | `backend/services/solicitud_service.py` (operaciones ORM) | Ídem para solicitudes |
| `app/crud/reserva.py` | `backend/services/cama_service.py` y `solicitud_service.py` (operaciones ORM de reservas) | Consolida operaciones de `ReservaQuirofano` en un solo lugar; elimina import lazy circular |
### Servicios (refactorizados)
| Archivo creado | Origen | Razón |
|---------------|--------|-------|
| `app/services/__init__.py` | Nuevo | Marca directorio como paquete |
| `app/services/cama_service.py` | `backend/services/cama_service.py` | Elimina acceso ORM directo → usa `crud.cama` y `crud.reserva`; elimina imports `and_`, `or_` no usados; extrae función `_verificar_contraindicaciones` (elimina duplicación); usa enums en lugar de strings; reemplaza `external_client.*` con módulos de integración específicos |
| `app/services/solicitud_service.py` | `backend/services/solicitud_service.py` | Ídem; `cancelar_reserva_por_turno` ahora usa `crud.reserva` (elimina import lazy circular); extrae `_verificar_contraindicaciones` común |
### Routers (mejorados)
| Archivo creado | Origen | Razón |
|---------------|--------|-------|
| `app/routers/__init__.py` | Nuevo | Marca directorio como paquete |
| `app/routers/camas.py` | `backend/routers/camas.py` | `POST /reservas` corregido a `require_roles("MEDICO","ADMINISTRATIVO")` (bug de autorización); parámetros de fecha tipados como `datetime` (validación automática); import `JSONResponse` movido al nivel de módulo; query param `estado` tipado con `EstadoCamaEnum`; todos los endpoints tienen `responses={4xx:...}` en OpenAPI |
| `app/routers/solicitudes.py` | `backend/routers/solicitudes.py` | Query params `estado` y `tipo` tipados con enums para validación automática; errores documentados en OpenAPI |
| `app/routers/webhooks.py` | `backend/routers/webhooks.py` | Ruta de cancelación de quirófano unificada bajo prefijo `/webhooks/`; errores documentados; variable `is_new` muerta eliminada |
### Tests
| Archivo creado | Origen | Razón |
|---------------|--------|-------|
| `tests/__init__.py` | Nuevo | Marca directorio como paquete |
| `tests/conftest.py` | Nuevo | Fixtures de BD en memoria (SQLite) y TestClient para testing sin PostgreSQL real |
| `tests/test_camas.py` | Nuevo | Estructura base de tests para router de camas |
| `tests/test_solicitudes.py` | Nuevo | Estructura base de tests para solicitudes y webhooks |
### Infraestructura y documentación
| Archivo | Tipo | Razón |
|---------|------|-------|
| `Dockerfile` | Creado (raíz) | Nuevo Dockerfile a nivel raíz; apunta a `app.main:app`; sin `--reload` |
| `docker-compose.yml` | Modificado | Elimina campo `version:` deprecado; build context actualizado a `.` (raíz); puerto 5432 sin exponer al host; volumen de bind mount actualizado |
| `requirements.txt` | Creado (raíz) | Copia del original con `python-multipart` comentada (no usada) y notas sobre separación dev/prod |
| `.env.example` | Creado | Template completo con todas las variables; instrucciones de generación de JWT secret; ningún valor real |
| `README.md` | Modificado | Documentación completa: propósito, endpoints, mapa de integraciones, variables de entorno, estructura del proyecto, cómo correr tests |
---
## Bugs corregidos durante la refactorización
| Bug | Archivo original | Solución |
|-----|-----------------|---------|
| `POST /camas/{id}/reservas` usaba `get_current_user` sin verificar rol — cualquier usuario autenticado podía crear reservas de quirófano | `backend/routers/camas.py:167` | Cambiado a `require_roles("MEDICO", "ADMINISTRATIVO")` en `app/routers/camas.py` |
| Variable `is_new = reserva_desplazada is not None or True` siempre verdadera, nunca usada | `backend/routers/webhooks.py:78` | Eliminada — la lógica de mensaje se calcula directamente desde `reserva_desplazada` |
| Parámetros `fecha_desde`/`fecha_hasta` de `GET /reservas` como `str` — fechas inválidas generaban 500 | `backend/routers/camas.py:150-151` | Tipados como `Optional[datetime]` en el router nuevo |
| Imports `datetime` dentro de funciones en `external_client.py` | `backend/services/external_client.py:72,90,103,125` | Movidos a nivel de módulo en cada `integrations/*.py` |
| `_get_cama_or_404` duplicada en `cama_service` y `solicitud_service` | Ambos servicios | Consolidada en `crud/cama.py` y usada desde ambos servicios |
| `cancelar_reserva_por_turno` en `solicitud_service` accedía a `ReservaQuirofano` con import lazy (señal de responsabilidad incorrecta) | `backend/services/solicitud_service.py:325` | Usa `crud.reserva.get_by_turno()` — sin import lazy |
| Verificación de contraindicaciones copiada 3 veces | `cama_service`, `solicitud_service` (×2) | Extraída a `_verificar_contraindicaciones()` en cada servicio |
---
## Decisiones de diseño
1. **`backend/` preservado**: el directorio original no fue eliminado — solo se creó la nueva estructura `app/`. Para producción, usar el nuevo `Dockerfile` raíz que solo incluye `app/`.
2. **`dependencies.py` unificado**: se fusionaron `database.py`, `auth/jwt_handler.py` y `auth/dependencies.py` en un único archivo de dependencias compartidas. Esto elimina el subdirectorio `auth/` (cuyo único propósito era autenticación) y centraliza toda la infraestructura transversal.
3. **`integrations/` separado por módulo**: en lugar de un único `external_client.py` monolítico, cada módulo externo (M1, M2, M7, M9, M10) tiene su propio archivo. Esto permite: a) mocking independiente por módulo en tests, b) refactoring aislado de cada integración.
4. **Capa `crud/` sin HTTPException**: los archivos de `crud/` no lanzan `HTTPException` — solo hacen operaciones de BD y devuelven `None` cuando no encuentran registros. Los servicios son los responsables de interpretar `None` como 404.
5. **Migraciones no incluidas**: el proyecto sigue usando `Base.metadata.create_all()` en startup. La adopción de Alembic queda pendiente (ver DEPENDENCY_AUDIT.md sección "Dependencias faltantes").
|