# 📋 API de Usuários - Documentação Completa

## 🔐 Autenticação
Todos os endpoints (exceto login) requerem autenticação via JWT token no header:
```
Authorization: Bearer <seu_jwt_token>
```

## 📊 Estrutura de Dados do Usuário

### Campos Obrigatórios:
- `username` (string): Nome de usuário único
- `email` (string): Email válido e único
- `password` (string): Senha (mínimo 6 caracteres)
- `first_name` (string): Primeiro nome
- `last_name` (string): Sobrenome
- `role_id` (integer): ID do role (1=admin, 2=manager, 3=agent, 4=vetter)

### Campos Opcionais:
- `phone` (string): Telefone de contato
- `is_active` (boolean): Status ativo (padrão: true)
- `created_by` (integer): ID do usuário que criou este usuário (automático)

### Campos de Auditoria (somente leitura):
- `created_by` (integer): ID do usuário que criou este usuário
- `createdBy` (object): Objeto com informações completas do usuário que criou
  - `user_id` (integer): ID do criador
  - `username` (string): Username do criador
  - `email` (string): Email do criador
  - `first_name` (string): Primeiro nome do criador
  - `last_name` (string): Sobrenome do criador
  - `phone` (string): Telefone do criador
  - `is_active` (boolean): Status do criador
  - `role_name` (string): Role do criador
- `created_at` (timestamp): Data de criação
- `updated_at` (timestamp): Data da última atualização
- `last_login` (timestamp): Último login

## 🎯 Roles Disponíveis

| ID | Nome | Descrição | Permissões |
|----|------|-----------|------------|
| 1 | admin | Administrador do sistema | Acesso total a todos os módulos |
| 2 | manager | Gerente | Acesso a relatórios e aprovações |
| 3 | agent | Agente de campo | Acesso limitado a empréstimos e clientes |
| 4 | vetter | Responsável por aprovações | Acesso a aprovações e vistoria |

---

## 🚀 ENDPOINTS CRUD

### 1. 🔑 **LOGIN** (Não requer autenticação)
```http
POST /api/users/login
```

**Body:**
```json
{
  "username": "admin",
  "password": "admin123"
}
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "user": {
      "user_id": 1,
      "username": "admin",
      "email": "admin@microcredito.com",
      "first_name": "Admin",
      "last_name": "Sistema",
      "phone": null,
      "role_id": 1,
      "is_active": true,
      "last_login": "2025-10-11T14:28:12.970Z",
      "created_at": "2025-10-11T13:01:34.028Z",
      "updated_at": "2025-10-11T13:01:34.028Z",
      "role_name": "admin",
      "role_description": "Administrador do sistema com acesso total",
      "permissions": {
        "loans": ["create", "read", "update", "delete", "approve"],
        "users": ["create", "read", "update", "delete"],
        "reports": ["read", "export"],
        "payments": ["create", "read", "update", "delete"],
        "customers": ["create", "read", "update", "delete"]
      }
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "message": "Login realizado com sucesso"
}
```

---

### 2. 📝 **CREATE USER** (Requer autenticação)
```http
POST /api/users
```

**Body:**
```json
{
  "username": "joao.silva",
  "email": "joao.silva@microcredito.com",
  "password": "senha123",
  "first_name": "João",
  "last_name": "Silva",
  "phone": "+258 84 123 4567",
  "role_id": 3,
  "is_active": true
}
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "user_id": 2,
    "username": "joao.silva",
    "email": "joao.silva@microcredito.com",
    "first_name": "João",
    "last_name": "Silva",
    "phone": "+258 84 123 4567",
    "role_id": 3,
    "is_active": true,
    "created_at": "2025-10-11T16:31:00.000Z"
  },
  "message": "Usuário criado com sucesso"
}
```

---

### 3. 📋 **GET ALL USERS** (Requer autenticação)
```http
GET /api/users?page=1&limit=10&search=joao&role_id=3&is_active=true
```

**Parâmetros de Query:**
- `page` (opcional): Número da página (padrão: 1)
- `limit` (opcional): Itens por página (padrão: 10)
- `search` (opcional): Busca por username, email, first_name, last_name
- `role_id` (opcional): Filtrar por role
- `is_active` (opcional): Filtrar por status ativo

**Resposta:**
```json
{
  "success": true,
  "data": {
    "data": [
      {
        "user_id": 1,
        "username": "admin",
        "email": "admin@microcredito.com",
        "first_name": "Admin",
        "last_name": "Sistema",
        "phone": null,
        "is_active": true,
        "last_login": "2025-10-11T14:28:12.970Z",
        "created_at": "2025-10-11T13:01:34.028Z",
        "updated_at": "2025-10-11T13:01:34.028Z",
        "created_by": null,
        "role_name": "admin",
        "role_description": "Administrador do sistema com acesso total",
        "createdBy": null
      },
      {
        "user_id": 2,
        "username": "maria.manager",
        "email": "maria.manager@microcredito.com",
        "first_name": "Maria",
        "last_name": "Fernandes",
        "phone": "+258 84 555 1234",
        "is_active": true,
        "last_login": null,
        "created_at": "2025-10-11T14:39:58.837Z",
        "updated_at": "2025-10-11T14:39:58.837Z",
        "created_by": 1,
        "role_name": "manager",
        "role_description": "Gerente com acesso a relatórios e aprovações",
        "createdBy": {
          "user_id": 1,
          "username": "admin",
          "email": "admin@microcredito.com",
          "first_name": "Admin",
          "last_name": "Sistema",
          "phone": null,
          "is_active": true,
          "role_name": "admin"
        }
      }
    ],
    "total": 2,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}
```

---

### 4. 🔍 **GET USER BY ID** (Requer autenticação)
```http
GET /api/users/1
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "user_id": 1,
    "username": "admin",
    "email": "admin@microcredito.com",
    "first_name": "Admin",
    "last_name": "Sistema",
    "phone": null,
    "role_id": 1,
    "is_active": true,
    "last_login": "2025-10-11T14:28:12.970Z",
    "created_at": "2025-10-11T13:01:34.028Z",
    "updated_at": "2025-10-11T13:01:34.028Z",
    "role_name": "admin",
    "role_description": "Administrador do sistema com acesso total",
    "permissions": {
      "loans": ["create", "read", "update", "delete", "approve"],
      "users": ["create", "read", "update", "delete"],
      "reports": ["read", "export"],
      "payments": ["create", "read", "update", "delete"],
      "customers": ["create", "read", "update", "delete"]
    }
  }
}
```

---

### 5. ✏️ **UPDATE USER** (Requer autenticação)
```http
PUT /api/users/2
```

**Body:**
```json
{
  "first_name": "João Carlos",
  "last_name": "Silva Santos",
  "phone": "+258 84 987 6543",
  "role_id": 2,
  "is_active": false
}
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "user_id": 2,
    "username": "joao.silva",
    "email": "joao.silva@microcredito.com",
    "first_name": "João Carlos",
    "last_name": "Silva Santos",
    "phone": "+258 84 987 6543",
    "role_id": 2,
    "is_active": false,
    "updated_at": "2025-10-11T16:35:00.000Z"
  },
  "message": "Usuário atualizado com sucesso"
}
```

---

### 6. 🔒 **CHANGE PASSWORD** (Requer autenticação)
```http
PUT /api/users/2/change-password
```

**Body:**
```json
{
  "current_password": "senha123",
  "new_password": "novaSenha456"
}
```

**Resposta:**
```json
{
  "success": true,
  "message": "Senha alterada com sucesso"
}
```

---

### 7. 👤 **GET PROFILE** (Requer autenticação)
```http
GET /api/users/profile
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "user_id": 1,
    "username": "admin",
    "email": "admin@microcredito.com",
    "first_name": "Admin",
    "last_name": "Sistema",
    "phone": null,
    "role_id": 1,
    "is_active": true,
    "last_login": "2025-10-11T14:28:12.970Z",
    "created_at": "2025-10-11T13:01:34.028Z",
    "updated_at": "2025-10-11T13:01:34.028Z",
    "role_name": "admin",
    "role_description": "Administrador do sistema com acesso total",
    "permissions": {
      "loans": ["create", "read", "update", "delete", "approve"],
      "users": ["create", "read", "update", "delete"],
      "reports": ["read", "export"],
      "payments": ["create", "read", "update", "delete"],
      "customers": ["create", "read", "update", "delete"]
    }
  }
}
```

---

### 8. ✏️ **UPDATE PROFILE** (Requer autenticação)
```http
PUT /api/users/profile
```

**Body:**
```json
{
  "first_name": "Administrador",
  "last_name": "Principal",
  "phone": "+258 84 111 2222"
}
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "user_id": 1,
    "username": "admin",
    "email": "admin@microcredito.com",
    "first_name": "Administrador",
    "last_name": "Principal",
    "phone": "+258 84 111 2222",
    "role_id": 1,
    "is_active": true,
    "updated_at": "2025-10-11T16:40:00.000Z"
  },
  "message": "Perfil atualizado com sucesso"
}
```

---

### 9. 📊 **GET USER STATS** (Requer autenticação)
```http
GET /api/users/stats
```

**Resposta:**
```json
{
  "success": true,
  "data": {
    "total_users": 5,
    "active_users": 4,
    "recent_logins": 3,
    "admin_users": 1
  }
}
```

---

### 10. 🚪 **LOGOUT** (Requer autenticação)
```http
POST /api/users/logout
```

**Resposta:**
```json
{
  "success": true,
  "message": "Logout realizado com sucesso"
}
```

---

### 11. 🗑️ **DELETE USER** (Requer autenticação)
```http
DELETE /api/users/2
```

**Resposta:**
```json
{
  "success": true,
  "message": "Usuário removido com sucesso"
}
```

---

## 📝 Exemplos de Dados para Criação

### 👨‍💼 **Gerente**
```json
{
  "username": "maria.manager",
  "email": "maria.manager@microcredito.com",
  "password": "manager123",
  "first_name": "Maria",
  "last_name": "Fernandes",
  "phone": "+258 84 555 1234",
  "role_id": 2,
  "is_active": true
}
```

### 👨‍💻 **Agente de Campo**
```json
{
  "username": "carlos.agent",
  "email": "carlos.agent@microcredito.com",
  "password": "agent123",
  "first_name": "Carlos",
  "last_name": "Mendes",
  "phone": "+258 84 777 8888",
  "role_id": 3,
  "is_active": true
}
```

### 🔍 **Responsável por Aprovações**
```json
{
  "username": "ana.vetter",
  "email": "ana.vetter@microcredito.com",
  "password": "vetter123",
  "first_name": "Ana",
  "last_name": "Rodrigues",
  "phone": "+258 84 999 0000",
  "role_id": 4,
  "is_active": true
}
```

---

## ⚠️ Códigos de Erro

| Código | Descrição |
|--------|-----------|
| 400 | Dados inválidos ou campos obrigatórios ausentes |
| 401 | Não autorizado (token inválido ou ausente) |
| 403 | Acesso negado (sem permissão) |
| 404 | Usuário não encontrado |
| 409 | Username ou email já existem |
| 500 | Erro interno do servidor |

---

## 🔧 Exemplo de Uso com cURL

### Login:
```bash
curl -X POST http://localhost:8000/api/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'
```

### Criar Usuário:
```bash
curl -X POST http://localhost:8000/api/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_JWT_TOKEN" \
  -d '{
    "username": "novo.usuario",
    "email": "novo@microcredito.com",
    "password": "senha123",
    "first_name": "Novo",
    "last_name": "Usuário",
    "phone": "+258 84 123 4567",
    "role_id": 3,
    "is_active": true
  }'
```

### Listar Usuários:
```bash
curl -X GET "http://localhost:8000/api/users?page=1&limit=10" \
  -H "Authorization: Bearer SEU_JWT_TOKEN"
```

---

## 🎯 Resumo dos Endpoints

| Método | Endpoint | Descrição | Autenticação |
|--------|----------|-----------|--------------|
| POST | `/api/users/login` | Login | ❌ |
| POST | `/api/users` | Criar usuário | ✅ |
| GET | `/api/users` | Listar usuários | ✅ |
| GET | `/api/users/:id` | Buscar usuário por ID | ✅ |
| PUT | `/api/users/:id` | Atualizar usuário | ✅ |
| PUT | `/api/users/:id/change-password` | Alterar senha | ✅ |
| GET | `/api/users/profile` | Perfil do usuário logado | ✅ |
| PUT | `/api/users/profile` | Atualizar perfil | ✅ |
| GET | `/api/users/stats` | Estatísticas de usuários | ✅ |
| POST | `/api/users/logout` | Logout | ✅ |
| DELETE | `/api/users/:id` | Deletar usuário | ✅ |

**Total: 11 endpoints completos para gerenciamento de usuários!** 🚀