# US-MGN003-002: Gestion de Permisos

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN003-002 |
| **Modulo** | MGN-003 Roles/RBAC |
| **Sprint** | Sprint 2 |
| **Prioridad** | P0 - Critica |
| **Story Points** | 5 |
| **Estado** | Ready |
| **Autor** | System |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** administrador del sistema
**Quiero** ver el catalogo de permisos disponibles agrupados por modulo
**Para** asignar los permisos correctos a cada rol

---

## Criterios de Aceptacion

### Escenario 1: Listar permisos agrupados

```gherkin
Given un admin autenticado con permiso "permissions:read"
When accede a GET /api/v1/permissions
Then el sistema retorna permisos agrupados por modulo
  And cada modulo incluye nombre y lista de permisos
  And cada permiso incluye code, name, description
  And no incluye permisos deprecados
```

### Escenario 2: Buscar permisos

```gherkin
Given 40 permisos en el sistema
When el admin busca "users"
Then el sistema retorna solo permisos que contienen "users"
  And mantiene agrupacion por modulo
  And la busqueda es case-insensitive
```

### Escenario 3: Mostrar permisos en selector

```gherkin
Given admin creando un nuevo rol
When ve el selector de permisos
Then los permisos estan agrupados por modulo
  And puede expandir/colapsar cada modulo
  And puede seleccionar multiples permisos
  And puede seleccionar "todos" de un modulo
```

### Escenario 4: Wildcard en permisos

```gherkin
Given un rol con permiso "users:*"
When se visualizan los permisos del rol
Then aparece "users:*" como seleccionado
  And indica que incluye todos los permisos de usuarios
  And los permisos individuales aparecen como "incluidos"
```

---

## Mockup / Wireframe

```
Selector de Permisos (en modal de crear/editar rol)
┌────────────────────────────────────────────────────────────────┐
│ Buscar permisos: [________________]     [Seleccionar todos]    │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│ ▼ Gestion de Usuarios (7 permisos)                   [☑ Todos] │
│   ┌──────────────────────────────────────────────────────────┐│
│   │ ☑ users:read    - Leer 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                      ││
│   └──────────────────────────────────────────────────────────┘│
│                                                                 │
│ ▶ Roles y Permisos (6 permisos)                      [☐ Todos] │
│                                                                 │
│ ▶ Inventario (9 permisos)                            [☐ Todos] │
│                                                                 │
│ ▶ Modulo Financiero (7 permisos)                     [☐ Todos] │
│                                                                 │
├────────────────────────────────────────────────────────────────┤
│ Permisos seleccionados: 2                                      │
└────────────────────────────────────────────────────────────────┘
```

---

## Notas Tecnicas

### API Endpoints

```typescript
GET /api/v1/permissions?search=users

// Response
{
  "data": [
    {
      "module": "users",
      "moduleName": "Gestion de Usuarios",
      "permissions": [
        {
          "id": "uuid",
          "code": "users:read",
          "name": "Leer usuarios",
          "description": "Ver listado y detalle de usuarios"
        },
        // ...
      ]
    }
  ]
}
```

### Permisos por Modulo

| Modulo | Cantidad | Ejemplo |
|--------|----------|---------|
| auth | 2 | auth:sessions:read |
| users | 7 | users:read, users:create |
| roles | 6 | roles:read, roles:assign |
| tenants | 3 | tenants:read |
| settings | 2 | settings:update |
| audit | 2 | audit:read |
| reports | 4 | reports:export |
| financial | 7 | financial:transactions:create |
| inventory | 9 | inventory:products:read |

---

## Definicion de Done

- [ ] Endpoint GET /api/v1/permissions
- [ ] Busqueda por texto
- [ ] Agrupacion por modulo
- [ ] Frontend: PermissionSelector component
- [ ] Frontend: Expand/collapse por modulo
- [ ] Frontend: Seleccion multiple
- [ ] Tests unitarios
- [ ] Code review aprobado

---

## Estimacion

| Tarea | Horas |
|-------|-------|
| Backend: Endpoint | 2h |
| Backend: Agrupacion | 1h |
| Backend: Tests | 1h |
| Frontend: PermissionSelector | 5h |
| Frontend: Tests | 2h |
| **Total** | **11h** |

---

## Historial

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