US-047 — Control de acceso por rol

Detalle de la historia¶

Historia¶

Como administrador de FleteChat, quiero que cada rol del backoffice (administrador, operador, gestor de precios) vea y pueda ejecutar únicamente las funciones que le corresponden, para proteger la separación de responsabilidades y reducir el riesgo de errores o accesos indebidos.

Persona de usuario¶

Aplica al rol admin en cuanto a configuración; aplica a todos los usuarios del backoffice en cuanto a cumplimiento de permisos. Clientes finales no interactúan con el backoffice y quedan fuera del alcance de esta historia.

Contexto de negocio¶

FleteChat distingue tres roles en v1.0 (ver PR-184): admin (configuración global, catálogos, asignaciones corporativas, usuarios), operator (operación cotidiana: clientes, embarques, handoff, actualización de estatus, reportes), price_manager (listas de precios). Mezclar responsabilidades —por ejemplo, que un operator desactive una modalidad o edite una lista— es fuente conocida de errores y de zonas grises de accountability. Separar por rol mantiene claridad y deja el audit log legible.

El enforcement debe ser doble: en la UI (un usuario no ve botones ni menús para funciones que no puede ejecutar) y en la API (cualquier petición fuera de rol devuelve 403). El primero mejora experiencia; el segundo protege contra abuso intencional o accidental. Ninguno de los dos alcanza por sí solo.

Criterios de aceptación¶

Roles definidos¶

1. v1.0 define exactamente tres roles (ver PR-184): admin, operator, price_manager. No hay permisos granulares ad-hoc ni combinaciones personalizadas (ver PR-185); los permisos de cada rol se fijan en la matriz de permisos documentada.
2. La matriz de permisos por rol está declarada y forma parte de la documentación del sistema; cada permiso referencia las historias que lo usan (por ejemplo, "gestionar catálogo de servicios — admin — US-042").

Enforcement¶

1. En la UI, cada usuario ve sólo los menús, secciones, botones y acciones autorizados para su rol. Las funciones no autorizadas no aparecen (no están ocultas deshabilitadas: simplemente no se renderizan).
2. En la API, toda solicitud a un recurso o acción fuera del permiso del rol del usuario devuelve 403 Forbidden con mensaje genérico. El backend nunca confía en el cliente para enforcement.
3. Los controles aplican también a acciones de lectura sensibles (por ejemplo, ver listas de precios): no se trata sólo de "no editar", se trata de qué se puede ver.

Cambio de rol y refresco¶

1. Cambiar el rol de un usuario tiene efecto en el siguiente login (ver PR-186). Sesiones activas no se ven afectadas hasta que expiren o el usuario cierre sesión; esto evita cambios inesperados a mitad de operación.
2. El admin puede forzar el cierre de sesión de un usuario desde la gestión de usuarios (ver historia correspondiente); el cambio de rol tiene efecto inmediato tras ese cierre.

Audit log¶

1. Cada cambio en la asignación de rol a un usuario queda auditado (ver historia de gestión de usuarios). Cada denegación 403 registra mínimo usuario, rol, recurso, acción y timestamp (para detectar patrones de uso indebido).

Edge cases¶

• Usuario con rol operator intenta llegar por URL directa a una sección de admin. El backend devuelve 403; la UI muestra "no tiene acceso" y redirige a la sección de inicio del rol.
• Usuario con sesión activa recibe un cambio de rol. La sesión actual conserva el rol anterior; al cerrar sesión (o expirar), el próximo login refleja el nuevo rol.
• Admin intenta removerse permisos a sí mismo (degradarse a operator). Permitido; pierde acceso a las funciones de admin en el siguiente login. Si queda un solo admin y se degrada, el sistema rechaza (ver historia de gestión de usuarios y PR-190).
• Nuevo rol propuesto en el futuro. v1.0 no soporta roles nuevos sin cambio de código: el catálogo de roles es cerrado. Agregar un rol requiere versión posterior.
• Permisos heredados entre roles. En v1.0 los roles son independientes: admin no hereda automáticamente los permisos de operator por decisión explícita (excepto donde se declare explícitamente, como en US-038 donde admin accede a funciones de consulta de operator). La matriz de permisos documenta cada excepción.

Tamaño, prioridad y tipo¶

• Tamaño: M
• Prioridad: P0 — fundacional para todo el backoffice; sin control de acceso no hay MVP seguro.
• Tipo: feature

Premisas¶

La historia está redactada bajo las siguientes premisas. Si alguna cambia, la historia debe revisarse y ajustarse en consecuencia. Todas deben ser confirmadas por el cliente antes de cerrar la historia.

• PR-184 — Tres roles en v1.0. El sistema define exactamente tres roles: admin, operator, price_manager. Agregar un rol nuevo requiere versión posterior.
• PR-185 — Permisos por rol, no granulares. Los permisos se asignan por rol; no hay edición granular por usuario. Simplifica la gestión y reduce errores de configuración.
• PR-186 — Cambio de rol en el siguiente login. Cambiar el rol de un usuario afecta sesiones futuras. Sesiones activas conservan el rol con el que se autenticaron hasta cerrar sesión o expirar.

Refinamiento y Definition of Ready¶

Notas¶

Checklist¶

• ✅ Historia escrita en formato Como / Quiero / Para
• ✅ Persona de usuario identificada
• ✅ Contexto de negocio documentado
• ✅ Criterios de aceptación observables y pass/fail
• ✅ Edge cases relevantes listados
• ✅ Tamaño y prioridad asignados
• ⬜ Premisas PR-184 a PR-186 confirmadas por el cliente
• ⬜ Reglas de negocio aplicables aprobadas
• ⬜ Requerimientos funcionales aplicables aprobados
• ⬜ Historia aprobada formalmente por el cliente