RBAC.md
Roles, Permisos, Scopes y Multi-tenant
1. Principio
Todo acceso está controlado por rol, pertenencia y scope.
El multi-tenant no se agrega después: está diseñado desde los cimientos via django-tenants.
Los feature flags se validan en el backend — el frontend nunca es la última línea de defensa.
2. Roles del sistema
| Rol |
Scope |
Descripción |
super_admin |
Global |
Administración del SaaS. Opera exclusivamente en esquema public. No accede a schemas de tenants via API |
empresa_admin |
Tenant |
Administración completa del tenant: sucursales, usuarios, catálogo, configuración |
sucursal_admin |
Sucursal |
Gestión de su sucursal: stock, caja, usuarios asignados. Sin acceso a otras sucursales |
cajero |
Sucursal |
Operación del POS y apertura/cierre de caja de su sucursal. No ve el descuadre |
vendedor |
Sucursal |
Operación del POS únicamente. Sin acceso a caja ni stock |
viewer |
Sucursal |
Solo lectura en su sucursal asignada |
3. Scopes
| Scope |
Descripción |
global |
Acceso total entre tenants. Solo super_admin |
tenant |
Acceso a toda la empresa. Solo empresa_admin |
sucursal |
Acceso a una sucursal específica |
own |
Solo recursos propios del usuario |
4. Matriz de permisos
| Recurso |
Acción |
super_admin |
empresa_admin |
sucursal_admin |
cajero |
vendedor |
viewer |
| Empresas (Tenants) |
CRUD |
Sí |
No |
No |
No |
No |
No |
| Suscripciones / Feature Flags |
Modificar |
Sí |
No |
No |
No |
No |
No |
| Suscripciones |
Ver |
Sí |
Sí |
No |
No |
No |
No |
| Sucursales |
CRUD |
Sí |
Sí |
No |
No |
No |
No |
| Usuarios |
Crear / Asignar |
Sí |
Sí |
No |
No |
No |
No |
| Usuarios |
Ver |
Sí |
Sí |
Sí |
No |
No |
No |
| Productos |
CRUD |
Sí |
Sí |
Sí |
No |
No |
No |
| Productos |
Ver |
Sí |
Sí |
Sí |
Sí |
Sí |
Sí |
| Precios |
Actualización masiva |
Sí |
Sí |
Sí |
No |
No |
No |
| Stock |
Ver |
Sí |
Sí |
Sí |
Sí |
Sí |
Sí |
| Stock |
Ajustar manualmente |
Sí |
Sí |
Sí |
No |
No |
No |
| Caja |
Abrir |
Sí |
Sí |
Sí |
Sí |
No |
No |
| Caja |
Cerrar (ciego) |
Sí |
Sí |
Sí |
Sí |
No |
No |
| Caja |
Ver descuadre |
Sí |
Sí |
Sí |
No |
No |
No |
| Ventas |
Crear |
Sí |
Sí |
Sí |
Sí |
Sí |
No |
| Ventas |
Ver historial |
Sí |
Sí |
Sí |
Sí |
Sí |
Sí |
| Entidades Comerciales |
CRUD |
Sí |
Sí |
Sí |
No |
No |
No |
| Importador masivo |
Ejecutar |
Sí |
Sí |
Sí |
No |
No |
No |
| Reportes |
Ver |
Sí |
Sí |
Sí |
No |
No |
Sí |
5. Reglas multi-tenant
super_admin nunca accede a schemas de tenants directamente via API de negocio.- Toda query en schema de tenant usa el
search_path activo gestionado por django-tenants.
- Un usuario puede tener roles distintos en distintas sucursales de la misma empresa.
- Un usuario no puede inferir datos de otro tenant bajo ninguna circunstancia.
- Los feature flags se validan en
core_api antes de procesar cualquier operación avanzada.
6. Regla crítica — Cierre de caja ciego
- El endpoint de cierre de caja nunca devuelve el saldo esperado al
cajero.
- El
cajero solo puede declarar el monto físico contado.
- El descuadre se calcula en el backend y es visible exclusivamente para
sucursal_admin y superiores.
- Cualquier endpoint que exponga el saldo esperado a un
cajero es una violación de seguridad crítica.
7. Tests mínimos de permisos
Para cada endpoint sensible:
- Usuario sin login no accede.
- Usuario de otro tenant no accede.
- Rol insuficiente recibe
403 Forbidden.
- Cajero no puede ver el descuadre de caja.
- Rol correcto accede y la acción queda auditada.
8. Prohibiciones
- No confiar en filtros del frontend para determinar accesos.
- No exponer el saldo esperado de caja al cajero bajo ningún formato.
- No asumir que un usuario pertenece a una sola sucursal.
- No devolver objetos de otro tenant aunque se conozca el ID.
- No permitir operaciones avanzadas (Fase 2+) sin validar el feature flag en el backend.