# 👥 Endpoints: Clientes e Funcionários

## 📋 **Visão Geral**

Dois novos endpoints foram criados para separar clientes e funcionários:

- **`/api/users/customers`** - Retorna apenas clientes (users com role "user")
- **`/api/users/employees`** - Retorna apenas funcionários (users com roles diferentes de "user")

## 🔗 **Endpoints**

### 1. **Listar Clientes**

```http
GET /api/users/customers
```

**Autenticação:** ✅ Requerida (Bearer Token)

**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): Buscar por username, email, first_name ou last_name
- `is_active` (opcional): Filtrar por status ativo (`true`/`false`)

**Exemplo de Requisição:**
```bash
curl -X GET "http://localhost:8000/api/users/customers?page=1&limit=10&search=joao&is_active=true" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Resposta de Sucesso (200):**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "username": "joao.silva",
      "email": "joao@example.com",
      "firstName": "João",
      "lastName": "Silva",
      "fullName": "João Silva",
      "phone": "+258841234567",
      "bi": "1234567890123",
      "isActive": true,
      "lastLogin": "2025-11-01T12:00:00.000Z",
      "createdAt": "2025-10-01T10:00:00.000Z",
      "updatedAt": "2025-11-01T12:00:00.000Z",
      "points": 0,
      "level": "Bronze",
      "pointsToNextLevel": 250,
      "role": {
        "id": 1,
        "name": "user",
        "description": "Default user role"
      },
      "permissions": {},
      "createdBy": null,
      "metrics": {
        "totalActions": 0,
        "totalCustomersCreated": 0,
        "totalLoansCreated": 0,
        "daysSinceLastLogin": 1,
        "activityStatus": "active"
      }
    }
  ],
  "pagination": {
    "total": 50,
    "page": 1,
    "limit": 10,
    "totalPages": 5,
    "hasNextPage": true,
    "hasPrevPage": false
  },
  "meta": {
    "showing": "1-10 de 50",
    "currentPage": 1,
    "perPage": 10,
    "type": "customers"
  }
}
```

### 2. **Listar Funcionários**

```http
GET /api/users/employees
```

**Autenticação:** ✅ Requerida (Bearer Token)

**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): Buscar por username, email, first_name ou last_name
- `is_active` (opcional): Filtrar por status ativo (`true`/`false`)

**Exemplo de Requisição:**
```bash
curl -X GET "http://localhost:8000/api/users/employees?page=1&limit=10&search=admin&is_active=true" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Resposta de Sucesso (200):**
```json
{
  "success": true,
  "data": [
    {
      "id": 2,
      "username": "admin",
      "email": "admin@example.com",
      "firstName": "Admin",
      "lastName": "Sistema",
      "fullName": "Admin Sistema",
      "phone": "+258841234568",
      "bi": null,
      "isActive": true,
      "lastLogin": "2025-11-01T12:00:00.000Z",
      "createdAt": "2025-09-01T10:00:00.000Z",
      "updatedAt": "2025-11-01T12:00:00.000Z",
      "role": {
        "id": 28,
        "name": "admin",
        "description": "Administrador do sistema com acesso total"
      },
      "permissions": {
        "users": ["create", "read", "update", "delete"],
        "establishments": ["create", "read", "update", "delete"],
        "campaigns": ["create", "read", "update", "delete"]
      },
      "createdBy": null,
      "metrics": {
        "totalActions": 150,
        "totalCustomersCreated": 50,
        "totalLoansCreated": 30,
        "daysSinceLastLogin": 0,
        "activityStatus": "active"
      }
    }
  ],
  "pagination": {
    "total": 5,
    "page": 1,
    "limit": 10,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  },
  "meta": {
    "showing": "1-5 de 5",
    "currentPage": 1,
    "perPage": 10,
    "type": "employees"
  }
}
```

## 📊 **Diferenças entre os Endpoints**

### **`/api/users/customers`**
- ✅ Retorna apenas usuários com **role "user"** (role_id: 1)
- ✅ Inclui campos relacionados a pontos (`points`, `level`, `pointsToNextLevel`)
- ✅ Indicado para gerenciar clientes do sistema de pontos/loyalty

### **`/api/users/employees`**
- ✅ Retorna usuários com **qualquer role diferente de "user"**
  - `admin` (role_id: 28)
  - `manager` (role_id: 29)
  - `agent` (role_id: 30)
  - `vetter` (role_id: 31)
  - `supervisor` (role_id: 37)
  - Qualquer outro role (exceto "user")
- ✅ Inclui permissões específicas do role
- ✅ Indicado para gerenciar funcionários/staff do sistema

## 🔍 **Filtros e Busca**

Ambos os endpoints suportam os mesmos filtros:

### **Busca (`search`)**
Busca por:
- `username`
- `email`
- `first_name`
- `last_name`

### **Status (`is_active`)**
- `true` - Apenas usuários ativos
- `false` - Apenas usuários inativos
- Não fornecido - Todos os usuários

### **Paginação**
- `page` - Número da página (começa em 1)
- `limit` - Itens por página (padrão: 10)

## 📝 **Exemplos de Uso**

### **Buscar clientes ativos:**
```javascript
GET /api/users/customers?is_active=true&limit=20
```

### **Buscar funcionários com busca:**
```javascript
GET /api/users/employees?search=admin&page=1&limit=10
```

### **Buscar todos os funcionários:**
```javascript
GET /api/users/employees?page=1&limit=100
```

## 🔐 **Autenticação**

Ambos os endpoints requerem autenticação via Bearer Token:

```http
Authorization: Bearer YOUR_JWT_TOKEN
```

## ⚠️ **Notas Importantes**

1. **Diferença entre `/api/users/employees` e `/api/employees`:**
   - `/api/users/employees` - Retorna **users** com roles de funcionários
   - `/api/employees` - Retorna registros da **tabela employees** (dados de RH)

2. **Clientes são users:**
   - No sistema de pontos, clientes são `users` com role "user"
   - Eles fazem login através da tabela `users`
   - Têm perfil em `users_profile` e carteira em `wallets`

3. **Funcionários podem ser users:**
   - Funcionários do sistema são `users` com roles diferentes de "user"
   - Podem também ter registros na tabela `employees` (dados de RH)

## 🎯 **Casos de Uso**

### **Caso 1: Listar todos os clientes do sistema**
```javascript
GET /api/users/customers
```

### **Caso 2: Buscar cliente específico**
```javascript
GET /api/users/customers?search=joao.silva
```

### **Caso 3: Listar funcionários administradores**
```javascript
GET /api/users/employees?search=admin
```

### **Caso 4: Listar funcionários inativos**
```javascript
GET /api/users/employees?is_active=false
```

## ✅ **Resumo**

| Endpoint | Filtro | Retorna |
|----------|--------|---------|
| `/api/users/customers` | role_id = 1 (role "user") | Apenas clientes |
| `/api/users/employees` | role_id != 1 (roles diferentes de "user") | Apenas funcionários |
| `/api/users` | Sem filtro | Todos os usuários |