# US-MGN002-001: CRUD de Usuarios (Admin)

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN002-001 |
| **Modulo** | MGN-002 Users |
| **Sprint** | Sprint 2 |
| **Prioridad** | P0 - Critica |
| **Story Points** | 8 |
| **Estado** | Ready |
| **Autor** | System |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** administrador del sistema
**Quiero** poder crear, ver, editar y eliminar usuarios
**Para** gestionar el acceso de los empleados a la plataforma ERP

---

## Criterios de Aceptacion

### Escenario 1: Crear usuario exitosamente

```gherkin
Given un administrador autenticado con permiso "users:create"
When crea un usuario con:
  | email      | nuevo@empresa.com |
  | firstName  | Juan              |
  | lastName   | Perez             |
  | roleIds    | [admin-role-id]   |
Then el sistema crea el usuario con status "pending_activation"
  And envia email de invitacion al usuario
  And responde con status 201
  And el body contiene el usuario creado sin password
```

### Escenario 2: Listar usuarios con paginacion

```gherkin
Given 50 usuarios en el tenant actual
When el admin solicita GET /api/v1/users?page=2&limit=10
Then el sistema retorna usuarios 11-20
  And incluye meta con total, pages, hasNext, hasPrev
```

### Escenario 3: Buscar usuarios por texto

```gherkin
Given usuarios con nombres "Juan", "Juana", "Pedro"
When el admin busca con search="juan"
Then el sistema retorna "Juan" y "Juana"
  And no retorna "Pedro"
```

### Escenario 4: Soft delete de usuario

```gherkin
Given un usuario activo con id "user-123"
When el admin elimina el usuario
Then el campo deleted_at se establece
  And el campo deleted_by tiene el ID del admin
  And el usuario no aparece en listados
  And el usuario no puede hacer login
```

### Escenario 5: No puede eliminarse a si mismo

```gherkin
Given un admin con id "admin-123"
When intenta eliminar su propio usuario
Then el sistema responde con status 400
  And el mensaje es "No puedes eliminarte a ti mismo"
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  [Logo]   Usuarios                    [+ Nuevo Usuario]          |
+------------------------------------------------------------------+
| Buscar: [___________________] [Filtros ▼]                        |
+------------------------------------------------------------------+
| ☐ | Avatar | Nombre        | Email              | Estado | Roles |
|---|--------|---------------|--------------------|---------|----- |
| ☐ | 👤     | Juan Perez    | juan@empresa.com   | Activo  | Admin|
| ☐ | 👤     | Maria Lopez   | maria@empresa.com  | Activo  | User |
| ☐ | 👤     | Pedro Garcia  | pedro@empresa.com  | Inactivo| User |
+------------------------------------------------------------------+
| Mostrando 1-10 de 50                    [< Anterior] [Siguiente >]|
+------------------------------------------------------------------+

Modal: Crear Usuario
┌──────────────────────────────────────────────────────────────────┐
│                        NUEVO USUARIO                              │
├──────────────────────────────────────────────────────────────────┤
│  Email*           [_______________________________]              │
│  Nombre*          [_______________________________]              │
│  Apellido*        [_______________________________]              │
│  Telefono         [_______________________________]              │
│  Roles            [Select roles...               ▼]              │
│                   ☑ Admin  ☐ Manager  ☐ User                     │
│                                                                   │
│  [  Cancelar  ]                    [ Crear Usuario ]             │
└──────────────────────────────────────────────────────────────────┘
```

---

## Notas Tecnicas

### API Endpoints

```typescript
// Crear usuario
POST /api/v1/users
{
  "email": "nuevo@empresa.com",
  "firstName": "Juan",
  "lastName": "Perez",
  "phone": "+521234567890",
  "roleIds": ["role-uuid"]
}

// Response 201
{
  "id": "user-uuid",
  "email": "nuevo@empresa.com",
  "firstName": "Juan",
  "lastName": "Perez",
  "status": "pending_activation",
  "isActive": false,
  "createdAt": "2025-12-05T10:00:00Z",
  "roles": [{ "id": "role-uuid", "name": "admin" }]
}

// Listar usuarios
GET /api/v1/users?page=1&limit=20&search=juan&status=active&sortBy=createdAt&sortOrder=DESC

// Response 200
{
  "data": [...],
  "meta": {
    "total": 50,
    "page": 1,
    "limit": 20,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}
```

### Permisos Requeridos

| Accion | Permiso |
|--------|---------|
| Crear | users:create |
| Listar | users:read |
| Ver detalle | users:read |
| Actualizar | users:update |
| Eliminar | users:delete |
| Activar/Desactivar | users:update |

---

## Definicion de Done

- [ ] Endpoint POST /api/v1/users implementado
- [ ] Endpoint GET /api/v1/users con paginacion y filtros
- [ ] Endpoint GET /api/v1/users/:id
- [ ] Endpoint PATCH /api/v1/users/:id
- [ ] Endpoint DELETE /api/v1/users/:id (soft delete)
- [ ] Validaciones de permisos (RBAC)
- [ ] Email de invitacion enviado
- [ ] Frontend: UsersListPage con tabla
- [ ] Frontend: Modal crear/editar usuario
- [ ] Tests unitarios (>80% coverage)
- [ ] Tests e2e pasando
- [ ] Code review aprobado

---

## Dependencias

| ID | Descripcion |
|----|-------------|
| RF-AUTH-001 | Login para autenticacion |
| RF-ROLE-001 | Roles para asignacion |
| EmailService | Para enviar invitaciones |

---

## Estimacion

| Tarea | Horas |
|-------|-------|
| Backend: CRUD endpoints | 6h |
| Backend: Paginacion y filtros | 3h |
| Backend: Tests | 3h |
| Frontend: UsersListPage | 4h |
| Frontend: UserForm modal | 3h |
| Frontend: Tests | 2h |
| **Total** | **21h** |

---

## Historial

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