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
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, enM6_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 comparapayload["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 endocumentation/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ónEN_LIMPIEZA → DISPONIBLE. Cualquier otra transición devuelve403 NO_AUTORIZADO. - No puede tocar
contraindicaciones_incompatiblesbajo ningún escenario — incluso si no mandaestadoen el mismo request. Devuelve403 NO_AUTORIZADO.
Antes de la reforma de roles (2026-06),
GET /camasfiltraba para LIMPIEZA solo las camas enEN_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}/reservasaceptaba 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 deM6_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. Leepayload["rol"]del JWT decodificado y devuelve403 NO_AUTORIZADOsi no matchea.- Routers (
app/routers/camas.py,quirofanos.py,solicitudes.py,auditoria.py) — declaran los roles permitidos por endpoint conDepends(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
rolsino un arraypermissions[]. Migrarrequire_rolesa un modelo de permisos (o a un shim que derive el rol interno desde los permisos) es el trabajo descripto endocumentation/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.