api / documentation /roles.md
juampisor's picture
Documentacion
d53b1d7
|
Raw History Blame
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.