rckrdmrd/erp-core
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
main
erp-core/docs/01-fase-foundation/MGN-003-roles/requerimientos/RF-ROLE-002.md

8.2 KiB
Raw Permalink Blame History

RF-ROLE-002: Gestion de Permisos

Identificacion

Campo Valor
ID RF-ROLE-002
Modulo MGN-003 Roles/RBAC
Prioridad P0 - Critica
Estado Ready
Fecha 2025-12-05

Descripcion

El sistema debe mantener un catalogo de permisos que definen las acciones granulares que los usuarios pueden realizar. Los permisos se agrupan por modulo y se asignan a roles. El sistema soporta permisos jerarquicos donde un permiso padre implica todos sus hijos.

Actores

Actor Descripcion
Super Admin Puede ver todos los permisos del sistema
Admin Puede ver permisos disponibles para su tenant
Sistema Registra nuevos permisos al instalar modulos

Precondiciones

  1. Usuario autenticado con permiso permissions:read
  2. Permisos base del sistema inicializados

Catalogo de Permisos

Estructura de Permisos

Los permisos siguen el patron modulo:accion o modulo:recurso:accion:

users:read           - Leer usuarios
users:create         - Crear usuarios
users:update         - Actualizar usuarios
users:delete         - Eliminar usuarios
users:*              - Todos los permisos de usuarios (wildcard)

inventory:products:read    - Leer productos
inventory:products:create  - Crear productos
inventory:*                - Todo el modulo inventario

Permisos por Modulo

Modulo Auth (MGN-001)

Permiso Descripcion
auth:sessions:read Ver sesiones activas
auth:sessions:revoke Revocar sesiones

Modulo Users (MGN-002)

Permiso Descripcion
users:read Listar y ver usuarios
users:create Crear usuarios
users:update Actualizar usuarios
users:delete Eliminar usuarios
users:activate Activar/desactivar usuarios
users:export Exportar lista de usuarios
users:import Importar usuarios

Modulo Roles (MGN-003)

Permiso Descripcion
roles:read Listar y ver roles
roles:create Crear roles
roles:update Actualizar roles
roles:delete Eliminar roles
roles:assign Asignar roles a usuarios
permissions:read Ver permisos disponibles

Modulo Tenants (MGN-004)

Permiso Descripcion
tenants:read Ver configuracion del tenant
tenants:update Actualizar configuracion
tenants:billing Gestionar facturacion

Modulo Settings (MGN-006)

Permiso Descripcion
settings:read Ver configuracion
settings:update Modificar configuracion

Modulo Audit (MGN-007)

Permiso Descripcion
audit:read Ver logs de auditoria
audit:export Exportar logs

Modulo Reports (MGN-009)

Permiso Descripcion
reports:read Ver reportes
reports:create Crear reportes personalizados
reports:export Exportar reportes
reports:schedule Programar reportes

Modulo Financial (MGN-010)

Permiso Descripcion
financial:accounts:read Ver cuentas contables
financial:accounts:manage Gestionar cuentas
financial:transactions:read Ver transacciones
financial:transactions:create Crear transacciones
financial:transactions:approve Aprobar transacciones
financial:reports:read Ver reportes financieros

Modulo Inventory (MGN-011)

Permiso Descripcion
inventory:products:read Ver productos
inventory:products:create Crear productos
inventory:products:update Actualizar productos
inventory:products:delete Eliminar productos
inventory:stock:read Ver stock
inventory:stock:adjust Ajustar stock
inventory:movements:read Ver movimientos
inventory:movements:create Crear movimientos

Flujo Principal

Listar Permisos Disponibles

1. Admin accede a Configuracion > Roles > Nuevo/Editar
2. Sistema carga lista de permisos agrupados por modulo
3. Sistema muestra solo permisos habilitados para el tenant
4. Admin puede expandir/colapsar grupos
5. Admin puede buscar permisos por nombre

Ver Permisos de un Rol

1. Admin accede a detalle de un rol
2. Sistema muestra permisos agrupados por modulo
3. Sistema indica cuales son heredados vs directos
4. Sistema muestra descripcion de cada permiso

Reglas de Negocio

ID Regla
RN-001 Permisos son inmutables por usuarios
RN-002 Permisos se registran por el sistema al instalar modulos
RN-003 Permiso wildcard (*) incluye todas las acciones del modulo
RN-004 Tenant solo ve permisos de modulos que tiene activos
RN-005 Codigo de permiso unico globalmente
RN-006 Permisos pueden estar activos o deprecados

Jerarquia de Permisos

users:*                     (Wildcard - todos los permisos de users)
├── users:read
├── users:create
├── users:update
├── users:delete
├── users:activate
├── users:export
└── users:import

inventory:*                 (Wildcard - todo inventario)
├── inventory:products:*    (Wildcard - productos)
│   ├── inventory:products:read
│   ├── inventory:products:create
│   ├── inventory:products:update
│   └── inventory:products:delete
├── inventory:stock:*
│   ├── inventory:stock:read
│   └── inventory:stock:adjust
└── inventory:movements:*
    ├── inventory:movements:read
    └── inventory:movements:create

Criterios de Aceptacion

Escenario 1: Listar permisos disponibles

Given un admin autenticado
When solicita GET /api/v1/permissions
Then el sistema retorna permisos agrupados por modulo
  And cada permiso incluye code, name, description
  And solo incluye permisos de modulos activos en el tenant

Escenario 2: Buscar permisos

Given lista de 50 permisos
When el admin busca "users"
Then el sistema retorna solo permisos que contienen "users"
  And mantiene agrupacion por modulo

Escenario 3: Validar wildcard

Given un rol con permiso "users:*"
When se verifica si tiene "users:delete"
Then el sistema confirma que SI tiene el permiso
  And el permiso es heredado (no directo)

Escenario 4: Permisos por modulo deshabilitado

Given tenant sin modulo de inventario activo
When admin lista permisos disponibles
Then NO aparecen permisos de "inventory:*"

Notas Tecnicas

API Endpoints

// Listar todos los permisos
GET /api/v1/permissions
// Query params: ?search=users&module=users

// Response 200
{
  "data": [
    {
      "module": "users",
      "moduleName": "Gestion de Usuarios",
      "permissions": [
        {
          "id": "perm-uuid",
          "code": "users:read",
          "name": "Leer usuarios",
          "description": "Permite ver listado y detalle de usuarios",
          "isDeprecated": false
        },
        // ...
      ]
    },
    {
      "module": "roles",
      "moduleName": "Roles y Permisos",
      "permissions": [...]
    }
  ]
}

// Listar permisos de un rol
GET /api/v1/roles/:roleId/permissions

// Response 200
{
  "direct": ["users:read", "users:create"],
  "inherited": ["users:update"],  // via wildcard
  "all": ["users:read", "users:create", "users:update"]
}

Modelo de Datos

interface Permission {
  id: string;
  code: string;           // users:read
  name: string;           // Leer usuarios
  description: string;
  module: string;         // users
  parentCode?: string;    // users:* (para jerarquia)
  isDeprecated: boolean;
  createdAt: Date;
}

Dependencias

ID Descripcion
RF-ROLE-001 Roles que contienen permisos
MGN-004 Tenants para filtrar por modulos activos

Estimacion

Tarea Puntos
Backend: Seed de permisos 2
Backend: Endpoint listar 2
Backend: Logica wildcard 3
Backend: Tests 2
Frontend: PermissionsList component 2
Frontend: Tests 1
Total 12 SP

Historial

Version Fecha Autor Cambios
1.0 2025-12-05 System Creacion inicial