# Indice de Requerimientos Funcionales - MGN-003 Roles/RBAC

## Resumen del Modulo

| Campo | Valor |
|-------|-------|
| **Modulo** | MGN-003 |
| **Nombre** | Roles y RBAC |
| **Descripcion** | Control de acceso basado en roles |
| **Total RFs** | 4 |
| **Story Points** | 64 |
| **Estado** | Ready |
| **Fecha** | 2025-12-05 |

---

## Lista de Requerimientos

| ID | Nombre | Prioridad | SP | Estado |
|----|--------|-----------|-----|--------|
| [RF-ROLE-001](./RF-ROLE-001.md) | CRUD de Roles | P0 | 20 | Ready |
| [RF-ROLE-002](./RF-ROLE-002.md) | Gestion de Permisos | P0 | 12 | Ready |
| [RF-ROLE-003](./RF-ROLE-003.md) | Asignacion de Roles a Usuarios | P0 | 17 | Ready |
| [RF-ROLE-004](./RF-ROLE-004.md) | Guards y Middlewares RBAC | P0 | 15 | Ready |

---

## Diagrama de Dependencias

```
                    ┌─────────────────┐
                    │  RF-AUTH-001    │
                    │  (Login/JWT)    │
                    └────────┬────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    MGN-003: Roles/RBAC                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────┐          ┌─────────────────┐              │
│  │  RF-ROLE-002    │◄─────────│  RF-ROLE-001    │              │
│  │  Permisos       │          │  CRUD Roles     │              │
│  └────────┬────────┘          └────────┬────────┘              │
│           │                            │                        │
│           │         ┌──────────────────┘                        │
│           │         │                                           │
│           ▼         ▼                                           │
│  ┌─────────────────────────────┐                               │
│  │      RF-ROLE-003            │                               │
│  │  Asignacion Roles-Usuarios  │                               │
│  └─────────────┬───────────────┘                               │
│                │                                                │
│                ▼                                                │
│  ┌─────────────────────────────┐                               │
│  │      RF-ROLE-004            │                               │
│  │  Guards y Middlewares       │                               │
│  └─────────────────────────────┘                               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                             │
                             ▼
              ┌──────────────────────────┐
              │  Todos los endpoints     │
              │  del sistema usan RBAC   │
              └──────────────────────────┘
```

---

## Arquitectura del Sistema RBAC

```
┌─────────────────────────────────────────────────────────────────┐
│                        RBAC Architecture                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌─────────┐      ┌─────────┐      ┌─────────────┐            │
│   │  User   │──────│  Role   │──────│ Permission  │            │
│   └─────────┘  M:N └─────────┘  M:N └─────────────┘            │
│                                                                  │
│   Un usuario puede tener multiples roles                        │
│   Un rol puede tener multiples permisos                         │
│   Permisos efectivos = Union de permisos de todos los roles    │
│                                                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Formato de Permisos:  modulo:accion                           │
│                         modulo:recurso:accion                   │
│                                                                  │
│   Wildcards:            users:*  (todas las acciones)           │
│                         inventory:products:*                     │
│                                                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Flujo de Validacion:                                          │
│                                                                  │
│   Request → JwtGuard → TenantGuard → RbacGuard → Controller    │
│                                          │                       │
│                                          ▼                       │
│                                   ┌─────────────┐               │
│                                   │   Cache     │               │
│                                   │  (5 min)    │               │
│                                   └─────────────┘               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

---

## Roles del Sistema (Built-in)

| Rol | Slug | Permisos Base | Modificable |
|-----|------|---------------|-------------|
| Super Administrador | super_admin | Todos (*) | No |
| Administrador | admin | Gestion tenant | Solo extender |
| Gerente | manager | Lectura + reportes | Solo extender |
| Usuario | user | Acceso basico | Solo extender |
| Invitado | guest | Solo dashboard | Solo extender |

---

## Catalogo de Permisos por Modulo

### MGN-001 Auth (2 permisos)
- `auth:sessions:read`
- `auth:sessions:revoke`

### MGN-002 Users (7 permisos)
- `users:read`, `users:create`, `users:update`, `users:delete`
- `users:activate`, `users:export`, `users:import`

### MGN-003 Roles (6 permisos)
- `roles:read`, `roles:create`, `roles:update`, `roles:delete`
- `roles:assign`, `permissions:read`

### MGN-004 Tenants (3 permisos)
- `tenants:read`, `tenants:update`, `tenants:billing`

### MGN-006 Settings (2 permisos)
- `settings:read`, `settings:update`

### MGN-007 Audit (2 permisos)
- `audit:read`, `audit:export`

### MGN-009 Reports (4 permisos)
- `reports:read`, `reports:create`, `reports:export`, `reports:schedule`

### MGN-010 Financial (6 permisos)
- `financial:accounts:read`, `financial:accounts:manage`
- `financial:transactions:read`, `financial:transactions:create`, `financial:transactions:approve`
- `financial:reports:read`

### MGN-011 Inventory (8 permisos)
- `inventory:products:read`, `inventory:products:create`, `inventory:products:update`, `inventory:products:delete`
- `inventory:stock:read`, `inventory:stock:adjust`
- `inventory:movements:read`, `inventory:movements:create`

**Total: ~40 permisos base**

---

## Estimacion Total

| Capa | Story Points |
|------|--------------|
| Backend: Endpoints | 15 |
| Backend: Guards/Decorators | 10 |
| Backend: Logica permisos | 8 |
| Backend: Cache | 4 |
| Backend: Tests | 10 |
| Frontend: RolesPage | 6 |
| Frontend: PermissionSelector | 4 |
| Frontend: RoleAssignment | 5 |
| Frontend: Tests | 6 |
| **Total** | **68 SP** |

> Nota: Los 64 SP indicados en resumen corresponden a la suma de RF individuales.
> La estimacion detallada es de 68 SP incluyendo integracion.

---

## Definition of Done del Modulo

- [ ] RF-ROLE-001: CRUD de roles completo
- [ ] RF-ROLE-002: Catalogo de permisos seeded
- [ ] RF-ROLE-003: Asignacion roles-usuarios funcional
- [ ] RF-ROLE-004: Guards aplicados a todos los endpoints
- [ ] Cache de permisos implementado
- [ ] Tests unitarios > 80% coverage
- [ ] Tests e2e de flujos RBAC
- [ ] Documentacion Swagger completa
- [ ] Code review aprobado
- [ ] Security review aprobado

---

## Notas de Implementacion

### Orden Recomendado

1. **Primero**: RF-ROLE-002 (Permisos) - Seed inicial de permisos
2. **Segundo**: RF-ROLE-001 (Roles) - CRUD de roles con permisos
3. **Tercero**: RF-ROLE-003 (Asignacion) - Vincular usuarios y roles
4. **Cuarto**: RF-ROLE-004 (Guards) - Proteger todos los endpoints

### Consideraciones de Seguridad

- Nunca revelar que permiso falta en errores 403
- Logs de acceso denegado para auditoria
- Super Admin no debe poder eliminarse a si mismo
- Cache de permisos debe invalidarse al cambiar roles
- Validar permisos en CADA request (no confiar en frontend)

---

## Historial

| Version | Fecha | Autor | Cambios |
|---------|-------|-------|---------|
| 1.0 | 2025-12-05 | System | Creacion inicial con 4 RFs |
