|
Download documentation/roles.md from Modulo-6/api: direct link, hf CLI and curl.
- Browser
- Download file 8.56 kB
-
https://huggingface.co/spaces/Modulo-6/api/resolve/6d76dbb2a8d2a751cc49fa06e2ed33f9f6be5aa0/documentation/roles.md
- Command line
-
hf download hf://spaces/Modulo-6/api@6d76dbb2a8d2a751cc49fa06e2ed33f9f6be5aa0/documentation/roles.md
-
curl -L -o roles.md https://huggingface.co/spaces/Modulo-6/api/resolve/6d76dbb2a8d2a751cc49fa06e2ed33f9f6be5aa0/documentation/roles.md
8.56 kB
| # Roles y permisos — Módulo 6 | |
| **Health Grid · Internación y Gestión de Camas** | |
| > Fuente de verdad de qué puede hacer cada rol en M6. La forma exacta de cada endpoint está en `M6_openapi.json`; las reglas de negocio y máquinas de estado, en `M6_DISEÑO.md`. Este documento es la matriz de autorización. | |
| --- | |
| ## 1. Roles del sistema | |
| M6 reconoce tres roles, transportados en el JWT (`payload["rol"]`) y validados en cada endpoint con `require_roles(...)` (`app/dependencies.py`): | |
| | Rol | Perfil | Alcance general | | |
| |---|---|---| | |
| | `ADMINISTRATIVO` | Gestión operativa de camas, quirófanos y solicitudes | Acceso total — lectura y escritura sobre todo el dominio de M6 | | |
| | `MEDICO` | Personal médico | Estrictamente de **solo lectura** sobre todo el dominio de M6, salvo crear reservas de quirófano (caso intencional, ver §3) | | |
| | `LIMPIEZA` | Personal de limpieza/mantenimiento de camas | Lee todas las camas; la única escritura permitida es finalizar la limpieza de una cama propia (`EN_LIMPIEZA → DISPONIBLE`) | | |
| No hay rol `SISTEMA` autenticado por JWT: los eventos disparados por webhooks entrantes (M1 HCE, M9 Monitoreo, M2 Turnos) no llevan actor humano y se registran en la auditoría con `rol = SISTEMA`, `origen = WEBHOOK` (ver `docs/superpowers/specs/2026-06-26-auditoria-cama-design.md`). | |
| --- | |
| ## 2. Principios de diseño | |
| - **MEDICO es de solo lectura.** Ningún endpoint de escritura (`POST`/`PATCH`/`DELETE`) sobre camas, quirófanos o solicitudes acepta el rol MEDICO. La única excepción intencional es crear reservas de cirugía — ver §3. | |
| - **ADMINISTRATIVO tiene control total.** Es el único rol que puede dar de alta/baja camas y quirófanos, asignar pacientes, resolver solicitudes y modificar reservas. | |
| - **LIMPIEZA está acotado al mínimo necesario.** Ve el mapa completo de camas (para saber dónde está parado y planificar), pero solo puede ejecutar una transición de estado muy específica. La restricción se aplica **a nivel de servicio** (`app/services/cama_service.py`), no solo en el frontend — un request directo a la API con un JWT de LIMPIEZA que intente otra cosa es rechazado igual. | |
| - **La autorización es por rol, no por permisos granulares.** `require_roles(*roles)` es un dependency de FastAPI que compara `payload["rol"]` contra una lista fija por endpoint. No hay un sistema de permisos (`camas:read`, `camas:write`, etc.) — eso es parte del plan de integración con el Core API de auth (M10), documentado en `documentation/M1_integration.md`, todavía no ejecutado. | |
| --- | |
| ## 3. Matriz de permisos por endpoint | |
| `✓` permitido · `✗` prohibido (403) · `✓*` permitido con restricción adicional aplicada en la capa de servicio | |
| ### Camas | |
| | Endpoint | ADMINISTRATIVO | MEDICO | LIMPIEZA | | |
| |---|:---:|:---:|:---:| | |
| | `GET /camas` — mapa completo | ✓ | ✓ | ✓ | | |
| | `POST /camas` — alta de cama | ✓ | ✗ | ✗ | | |
| | `GET /camas/{camaId}` — detalle | ✓ | ✓ | ✓ | | |
| | `PATCH /camas/{camaId}` — cambiar estado / contraindicaciones | ✓ | ✗ | ✓* | | |
| | `DELETE /camas/{camaId}` — baja permanente | ✓ | ✗ | ✗ | | |
| | `POST /camas/{camaId}/asignar` — asignar/trasladar paciente | ✓ | ✗ | ✗ | | |
| **`✓*` en `PATCH /camas/{camaId}` para LIMPIEZA** — restricción aplicada en `cama_service.update_cama`: | |
| - Solo puede cambiar `estado`, y únicamente la transición `EN_LIMPIEZA → DISPONIBLE`. Cualquier otra transición devuelve `403 NO_AUTORIZADO`. | |
| - No puede tocar `contraindicaciones_incompatibles` bajo ningún escenario — incluso si no manda `estado` en el mismo request. Devuelve `403 NO_AUTORIZADO`. | |
| > Antes de la reforma de roles (2026-06), `GET /camas` filtraba para LIMPIEZA solo las camas en `EN_LIMPIEZA`. Ahora ve el mapa completo; lo que cambió es exclusivamente el alcance de escritura. | |
| ### Quirófanos | |
| | Endpoint | ADMINISTRATIVO | MEDICO | LIMPIEZA | | |
| |---|:---:|:---:|:---:| | |
| | `GET /quirofanos/disponibilidad` | ✓ | ✓ | ✗ | | |
| | `GET /quirofanos` — listado | ✓ | ✓ | ✗ | | |
| | `POST /quirofanos` — alta | ✓ | ✗ | ✗ | | |
| | `GET /quirofanos/{quirofanoId}` — detalle | ✓ | ✓ | ✗ | | |
| | `PATCH /quirofanos/{quirofanoId}` — actualizar | ✓ | ✗ | ✗ | | |
| | `GET /quirofanos/{quirofanoId}/reservas` — listar reservas | ✓ | ✓ | ✗ | | |
| | `POST /quirofanos/{quirofanoId}/reservas` — crear reserva | ✓ | ✗ | ✗ | | |
| | `GET /quirofanos/{quirofanoId}/reservas/{reservaId}` — detalle reserva | ✓ | ✓ | ✗ | | |
| | `PATCH /quirofanos/{quirofanoId}/reservas/{reservaId}` — cambiar estado reserva | ✓ | ✗ | ✗ | | |
| LIMPIEZA no tiene ningún acceso a quirófanos — no es parte de su responsabilidad operativa. | |
| > **Corrección 2026-06:** `POST /quirofanos/{quirofanoId}/reservas` aceptaba MEDICO. Era la única escritura que tenía ese rol en todo M6, inconsistente con el principio de "MEDICO solo lectura". Se removió — ver changelog §14.3 de `M6_DISEÑO.md`. | |
| ### Solicitudes | |
| | Endpoint | ADMINISTRATIVO | MEDICO | LIMPIEZA | | |
| |---|:---:|:---:|:---:| | |
| | `GET /solicitudes` — listado | ✓ | ✓ | ✗ | | |
| | `GET /solicitudes/{solicitudId}` — detalle | ✓ | ✓ | ✗ | | |
| | `PATCH /solicitudes/{solicitudId}` — aprobar/rechazar | ✓ | ✗ | ✗ | | |
| Solo ADMINISTRATIVO resuelve solicitudes de internación/traslado, incluso si fue un médico quien las originó desde HCE (M1) — la decisión de qué cama concreta se asigna es administrativa, no clínica (ver `M6_DISEÑO.md` §1). | |
| ### Auditoría | |
| | Endpoint | ADMINISTRATIVO | MEDICO | LIMPIEZA | | |
| |---|:---:|:---:|:---:| | |
| | `GET /auditoria` — historial de eventos | ✓ | ✓ | ✗ | | |
| LIMPIEZA no tiene acceso al historial de auditoría — no necesita visibilidad sobre el log completo de movimientos clínicos/administrativos para hacer su trabajo. | |
| ### Webhooks entrantes | |
| Los endpoints bajo `/webhooks/*` (recepción de eventos de M1 HCE, M9 Monitoreo, M2 Turnos) **no usan `require_roles`** — no hay un usuario humano autenticado por JWT en esas llamadas. La autenticación de webhooks entrantes es un punto pendiente de definir con el Bus de Eventos de Core (ver `M6_DISEÑO.md` §13). | |
| --- | |
| ## 4. Implementación | |
| - **`app/dependencies.py`** — `require_roles(*roles)` es el dependency de FastAPI que se usa en cada router. Lee `payload["rol"]` del JWT decodificado y devuelve `403 NO_AUTORIZADO` si no matchea. | |
| - **Routers** (`app/routers/camas.py`, `quirofanos.py`, `solicitudes.py`, `auditoria.py`) — declaran los roles permitidos por endpoint con `Depends(require_roles(...))`. Esta es la primera línea de defensa; cubre la mayoría de los casos porque la mayoría de las restricciones son "todo o nada" por endpoint. | |
| - **Capa de servicio** (`app/services/cama_service.py::update_cama`) — segunda línea de defensa para LIMPIEZA, porque su restricción no es "todo o nada" sobre el endpoint: `PATCH /camas/{camaId}` está permitido para LIMPIEZA, pero con una regla fina sobre *qué* puede cambiar y *bajo qué condición de estado previo*. Esa lógica no se puede expresar en el dependency de FastAPI — vive donde está el contexto de negocio completo (estado actual de la cama, qué campos vinieron en el body). | |
| **Regla general para agregar una restricción nueva:** si es "este rol no puede llamar a este endpoint en absoluto", va en el router con `require_roles`. Si es "este rol puede llamar al endpoint pero con una condición sobre el contenido del request o el estado del recurso", va en el servicio — nunca confiar solo en que el frontend oculte el botón. | |
| --- | |
| ## 5. Testing | |
| Los tests de autorización por rol viven junto a los tests de cada router (`tests/test_camas.py`, `tests/test_quirofanos.py`, `tests/test_solicitudes.py`, `tests/test_auditoria.py`), usando los fixtures `admin_headers`, `medico_headers`, `limpieza_headers` de `tests/conftest.py`. Cada endpoint restringido tiene al menos un test que verifica `403` para el/los rol(es) sin permiso, y un test de happy path para el rol permitido. | |
| --- | |
| ## 6. Fuera de alcance / pendiente | |
| - **Permisos granulares vía Core API (M10).** El JWT del Core API real no transporta un campo `rol` sino un array `permissions[]`. Migrar `require_roles` a un modelo de permisos (o a un shim que derive el rol interno desde los permisos) es el trabajo descripto en `documentation/M1_integration.md`, todavía no ejecutado. | |
| - **Autenticación de webhooks entrantes.** Hoy no hay verificación de origen en `/webhooks/*` más allá de lo que ya documente cada integración puntual. Pendiente acordar mecanismo (secreto compartido o firma) con el Bus de Eventos de Core. | |