|
Download audit/ARCHITECTURE_REVIEW.md from Modulo-6/api: direct link, hf CLI and curl.
- Browser
- Download file 11.5 kB
-
https://huggingface.co/spaces/Modulo-6/api/resolve/main/audit/ARCHITECTURE_REVIEW.md
- Command line
-
hf download hf://spaces/Modulo-6/api/audit/ARCHITECTURE_REVIEW.md
-
curl -L -o ARCHITECTURE_REVIEW.md https://huggingface.co/spaces/Modulo-6/api/resolve/main/audit/ARCHITECTURE_REVIEW.md
11.5 kB
| # RevisiΓ³n de Arquitectura β MΓ³dulo 6 (Health Grid) | |
| > Fecha: 2026-05-03 | Agente E (Architecture Reviewer) | Stack: FastAPI Β· SQLAlchemy (sync) Β· PostgreSQL | |
| --- | |
| ## Diagrama de capas ACTUAL | |
| ``` | |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| β CLIENTES β | |
| β (M1 HCE Β· M2 Turnos Β· M9 Monitoreo Β· Browser) β | |
| βββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββ | |
| β HTTP | |
| βββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββ | |
| β ROUTERS (camas.py Β· solicitudes.py Β· webhooks.py) β | |
| β [!] LΓ³gica de agregaciΓ³n de estados en router β | |
| β [!] ConstrucciΓ³n de dicts anΓ³nimos sin schema β | |
| β [!] Import lazy dentro de handler β | |
| βββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββ | |
| β llamadas a funciones directas | |
| βββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββ | |
| β SERVICES (cama_service.py Β· solicitud_service.py) β | |
| β [!] db.query/add/commit/refresh sin capa repositorio β | |
| β [!] HTTPException lanzadas desde capa de servicio β | |
| β [!] Imports lazy para evitar ciclos β | |
| βββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββ | |
| β acceso ORM directo (sin repositorio) | |
| βββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββ | |
| β MODELOS ORM (cama.py Β· solicitud.py Β· reserva.py) β | |
| β [OK] Bien separados de los schemas Pydantic β | |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| β CLIENTE EXTERNO β services/external_client.py β | |
| β [OK] Todas las llamadas outbound centralizadas aquΓ β | |
| β [!] httpx SΓNCRONO en app async β bloquea event loop β | |
| β [!] except Exception silencioso, sin logging ni retry β | |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| ``` | |
| --- | |
| ## Diagrama de capas IDEAL propuesto | |
| ``` | |
| CLIENTES | |
| β | |
| βΌ | |
| ROUTERS β solo validaciΓ³n de input y presentaciΓ³n de output | |
| β | |
| βΌ | |
| SERVICES β lΓ³gica de negocio pura (sin HTTPException, sin db.commit) | |
| β | |
| βΌ | |
| REPOSITORIES β toda la interacciΓ³n ORM (una clase por entidad) | |
| β | |
| βΌ | |
| MODELOS ORM | |
| INTEGRATIONS/ β clientes HTTP async, con excepciones tipadas y logging | |
| βββ hce.py β M1 | |
| βββ turnos.py β M2 | |
| βββ facturacion.py β M7 | |
| βββ monitoreo.py β M9 | |
| βββ core.py β M10 | |
| ``` | |
| --- | |
| ## Hallazgos por categorΓa | |
| ### 1. SeparaciΓ³n de capas | |
| | Hallazgo | Archivo:lΓnea | Impacto | | |
| |----------|--------------|---------| | |
| | Contadores de estado calculados en el router (`count("DISPONIBLE")`) | `routers/camas.py:70-78` | MEDIO | | |
| | ConstrucciΓ³n de dict anΓ³nimo de respuesta de disponibilidad sin schema | `routers/camas.py:39-53` | MEDIO | | |
| | Workaround `{**s.__dict__, "id": s.solicitud_id}` en lugar de schema correcto | `routers/solicitudes.py:23,36,48` | BAJO | | |
| | Import lazy `JSONResponse` dentro del body del handler | `routers/camas.py:172` | BAJO | | |
| **Veredicto:** No hay acceso directo a BD en routers. Los problemas son lΓ³gica de presentaciΓ³n que se filtrΓ³ al router. Arquitectura ~90% correcta en esta capa. | |
| --- | |
| ### 2. Capa de repositorio AUSENTE (hallazgo mΓ‘s importante) | |
| No existe una capa CRUD/Repository separada. Todo el acceso ORM (`db.query`, `db.add`, `db.commit`, `db.refresh`) estΓ‘ embebido directamente en los servicios. | |
| | Hallazgo | Archivo | Impacto | | |
| |----------|---------|---------| | |
| | `db.query/add/commit/refresh` directos en capa de servicio | `cama_service.py`, `solicitud_service.py` | ALTO | | |
| | `_get_cama_or_404` definida dos veces en dos servicios distintos | `cama_service.py:23-27` / `solicitud_service.py:37-44` | MEDIO | | |
| | `cancelar_reserva_por_turno` en `solicitud_service` accede al modelo `ReservaQuirofano` con import lazy | `solicitud_service.py:325` | ALTO | | |
| **Consecuencias:** Dificultad para testear servicios sin base de datos real, lΓ³gica de acceso a datos dispersa, duplicaciΓ³n de queries. | |
| --- | |
| ### 3. Imports circulares potenciales | |
| | Hallazgo | Archivo:lΓnea | Causa raΓz | | |
| |----------|--------------|-----------| | |
| | Import lazy para romper ciclo entre servicios | `solicitud_service.py:325` | `solicitud_service` opera sobre `ReservaQuirofano` que pertenece al dominio de camas | | |
| | Import lazy de schema dentro de funciΓ³n de servicio | `cama_service.py:395` | Dependencia cruzada entre schemas | | |
| **SoluciΓ³n:** Mover `cancelar_reserva_por_turno` al dominio de camas/reservas. Los imports lazy son una seΓ±al de diseΓ±o de dependencias incorrecto, no la soluciΓ³n. | |
| --- | |
| ### 4. Aislamiento de llamadas externas | |
| | Hallazgo | Archivo:lΓnea | Severidad | | |
| |----------|--------------|-----------| | |
| | `httpx.post/get` **sΓncrono** en app FastAPI async β bloquea event loop | `external_client.py:19-34` | CRΓTICO | | |
| | `except Exception: return None` silencia todos los errores sin log | `external_client.py:25,33` | ALTO | | |
| | Llamadas externas fire-and-forget intercaladas con `db.commit()` β inconsistencia posible | `cama_service.py:194-198` / `solicitud_service.py:205-206` | MEDIO | | |
| | No hay mecanismo de retry ni circuit breaker | `external_client.py` completo | MEDIO | | |
| | Imports `datetime` dentro de funciones | `external_client.py:72,89,105,126` | BAJO | | |
| **Punto positivo:** Todas las llamadas HTTP outbound estΓ‘n centralizadas en `external_client.py`. NingΓΊn router ni servicio llama directamente a `httpx`. Esto es correcto y facilita la migraciΓ³n. | |
| --- | |
| ### 5. God files | |
| | Archivo | LΓneas | Responsabilidades mezcladas | | |
| |---------|--------|---------------------------| | |
| | `services/cama_service.py` | ~501 | CRUD camas, estados, contraindicaciones, CRUD reservas, conflictos de horario, reservas urgentes con desplazamiento, notificaciones externas | | |
| | `services/solicitud_service.py` | ~353 | RecepciΓ³n, listado, resoluciΓ³n, alta mΓ©dica, alertas, cancelaciΓ³n de reservas de quirΓ³fano | | |
| **RecomendaciΓ³n:** Dividir `cama_service.py` en `cama_service.py` + `reserva_service.py`. | |
| --- | |
| ### 6. InyecciΓ³n de dependencias | |
| | Aspecto | Estado | | |
| |---------|--------| | |
| | `get_db()` como generador en `database.py` | β Correcto | | |
| | `require_roles()` factory pattern en `auth/dependencies.py` | β Correcto | | |
| | SesiΓ³n de BD nunca creada ad-hoc en handlers | β Correcto | | |
| | `external_client.py` como funciones puras no inyectables | β οΈ Impide mocking en tests | | |
| --- | |
| ### 7. ConflaciΓ³n Schema / Model ORM | |
| | Aspecto | Estado | | |
| |---------|--------| | |
| | Schemas Pydantic y modelos ORM claramente separados | β Correcto | | |
| | `ConfigDict(from_attributes=True)` aplicado correctamente | β Correcto | | |
| | `CamaResponse.tipo/estado/sector: str` en lugar de enum | β οΈ Debilita validaciΓ³n de salida y documentaciΓ³n OpenAPI | | |
| | `SolicitudResponse` campos enumerados como `str` | β οΈ Mismo problema | | |
| | `AsignacionCamaRequest.tipo: str` libre en lugar de `Literal` | β οΈ Sin restricciΓ³n de dominio | | |
| --- | |
| ### 8. Completitud del contrato OpenAPI | |
| | MΓ©trica | Valor | | |
| |---------|-------| | |
| | Endpoints con `response_model` explΓcito | **10 / 18 (56%)** | | |
| | Endpoints con respuesta anΓ³nima / dict | **8 / 18 (44%)** | | |
| | Errores 4xx/5xx documentados en OpenAPI | **0 / 18 (0%)** | | |
| | Query params tipados con enum | **0 / 5 filtros relevantes** | | |
| **Endpoints sin `response_model`:** | |
| - `GET /camas/disponibilidad` | |
| - `POST /camas/{id}/reservas` | |
| - `POST /webhooks/hce/solicitud` | |
| - `POST /webhooks/hce/alta-medica` | |
| - `POST /webhooks/hce/cirugia-urgente` | |
| - `POST /webhooks/turnos/{id}/cancelacion-quirofano` | |
| - `POST /webhooks/monitoreo/alerta-emergencia` | |
| - `POST /webhooks/monitoreo/alerta-resuelta` | |
| - `GET /auth/token` | |
| **CalificaciΓ³n global del contrato OpenAPI: 4 / 10** | |
| Los consumidores de la API no tienen contrato formal de errores. NingΓΊn endpoint documenta `401/403/404/409/422/502`. | |
| --- | |
| ## Recomendaciones priorizadas | |
| ### Prioridad 1 β CrΓtico / Inmediato | |
| 1. **Migrar `external_client.py` a `httpx.AsyncClient` async** β las llamadas sΓncronas bloquean el event loop de FastAPI, limitando la concurrencia a 1 request efectivo por llamada externa. | |
| 2. **Eliminar el default del JWT secret** en `config.py:9` β hacerlo campo obligatorio sin default. | |
| 3. **Corregir CORS** β listar orΓgenes explΓcitos en lugar de wildcard con `allow_credentials=True`. | |
| ### Prioridad 2 β Alto | |
| 4. **Crear capa de repositorio** β extraer `db.query/add/commit/refresh` a clases `CamaRepository`, `SolicitudRepository`, `ReservaRepository` bajo `backend/crud/`. | |
| 5. **Mover `cancelar_reserva_por_turno`** de `solicitud_service` al dominio de reservas para eliminar import lazy y responsabilidad incorrecta. | |
| 6. **Agregar `response_model`** a los 8 endpoints que lo omiten β crear schemas Pydantic para respuestas anΓ³nimas. | |
| 7. **Loguear y tipar errores del cliente externo** β reemplazar `except Exception: return None` por logging + excepciΓ³n de dominio tipada (`ExternalServiceError`). | |
| ### Prioridad 3 β Medio | |
| 8. **Dividir `cama_service.py`** en `cama_service.py` (gestiΓ³n de camas) y `reserva_service.py` (quirΓ³fanos). | |
| 9. **Usar enums en campos de respuesta y query params** β `CamaResponse.tipo/estado/sector`, filtros en GET endpoints. | |
| 10. **Documentar errores en OpenAPI** con `responses={401: ..., 403: ..., 404: ..., 409: ..., 502: ...}`. | |
| 11. **Mover lΓ³gica de agregaciΓ³n** de router al servicio (`routers/camas.py:70-78`). | |
| 12. **Mover todos los imports lazy** al encabezado del mΓ³dulo y resolver las dependencias circulares por diseΓ±o. | |
| ### Prioridad 4 β Bajo / Backlog | |
| 13. Convertir el `external_client.py` monolΓtico en mΓ³dulos separados por integraciΓ³n (`integrations/hce.py`, `integrations/monitoreo.py`, etc.). | |
| 14. Separar reservas de quirΓ³fano en router dedicado `routers/quirofanos.py`. | |
| 15. Proteger `/auth/token` con feature flag `settings.debug_mode`. | |
| 16. Agregar tests unitarios con mocks del repositorio. | |