# 👥 Estrutura: Clientes vs Usuários no Sistema de Pontos

## 📋 **Visão Geral**

No **sistema de pontos/loyalty** (banco `maktubia_points`), os **clientes são usuários** na tabela `users`.

## ✅ **Estrutura Atual**

### 👤 **Tabela `users` (Autenticação e Autorização)**

Todos os clientes que fazem login estão na tabela `users`:

```sql
CREATE TABLE users (
    user_id SERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(120) UNIQUE NOT NULL,
    password_hash TEXT NOT NULL,
    first_name VARCHAR(100) NOT NULL,
    last_name VARCHAR(100) NOT NULL,
    phone VARCHAR(50),
    bi VARCHAR(50),  -- Bilhete de Identidade
    role_id INTEGER REFERENCES roles(role_id),
    is_active BOOLEAN DEFAULT TRUE,
    created_by INTEGER,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_login TIMESTAMP
);
```

**Responsabilidades:**
- ✅ **Login e autenticação** (username + password)
- ✅ **Controle de acesso** (via role_id)
- ✅ **Dados pessoais básicos** (nome, email, telefone, BI)
- ✅ **Status** (ativo/inativo)

### 👥 **Roles Disponíveis**

O sistema possui os seguintes roles:

| Role ID | Role Name | Descrição |
|---------|-----------|-----------|
| 1 | `user` | **Default user role** - Role padrão para clientes |
| 28 | `admin` | Administrador do sistema com acesso total |
| 29 | `manager` | Gerente com acesso a relatórios e aprovações |
| 30 | `agent` | Agente de campo com acesso limitado |
| 31 | `vetter` | Responsável por aprovações e vistoria |
| 37 | `supervisor` | Supervisor de equipe |

### 📊 **Perfil do Cliente (`users_profile`)**

Após o login, o cliente tem um perfil criado automaticamente:

```sql
CREATE TABLE users_profile (
    user_id VARCHAR(64) PRIMARY KEY,  -- Referência ao user_id (convertido para string)
    name TEXT,
    phone TEXT,
    email TEXT,
    level TEXT DEFAULT 'bronze'  -- Nível do cliente (bronze, silver, gold, etc)
);
```

### 💰 **Carteira de Pontos (`wallets`)**

Cada cliente tem uma carteira de pontos:

```sql
CREATE TABLE wallets (
    user_id VARCHAR(64) PRIMARY KEY REFERENCES users_profile(user_id),
    balance NUMERIC(14,2) NOT NULL DEFAULT 0,
    points BIGINT NOT NULL DEFAULT 0,
    updated_at TIMESTAMP DEFAULT NOW()
);
```

## 🔄 **Fluxo de Login do Cliente**

### 1. **Criação do Cliente**

Quando um cliente se registra ou é criado:

```javascript
// Criar usuário na tabela users
const user = await User.create({
    username: "joao.silva",
    email: "joao@example.com",
    password: "senha123",
    first_name: "João",
    last_name: "Silva",
    phone: "+258841234567",
    bi: "1234567890123",
    role_id: 1,  // Role "user" (cliente)
    is_active: true
});
```

### 2. **Login do Cliente**

O cliente faz login através do endpoint `/api/auth/signin` ou `/api/auth/login`:

```javascript
POST /api/auth/signin
{
    "username": "joao.silva",
    "password": "senha123"
}

// Resposta:
{
    "success": true,
    "data": {
        "user": {
            "user_id": 1,
            "username": "joao.silva",
            "email": "joao@example.com",
            "first_name": "João",
            "last_name": "Silva",
            "phone": "+258841234567",
            "bi": "1234567890123",
            "role": {
                "id": 1,
                "name": "user",
                "description": "Default user role"
            },
            "is_active": true
        },
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
}
```

### 3. **Criação Automática de Perfil e Carteira**

Quando o cliente faz login pela primeira vez, o sistema cria automaticamente:
- ✅ Perfil em `users_profile` (se não existir)
- ✅ Carteira em `wallets` (se não existir)

## 🎯 **Resumo: Como Funciona**

### ✅ **Cliente do Sistema de Pontos:**

1. **É um usuário** na tabela `users`
2. **Faz login** através da tabela `users` (username + password)
3. **Tem role** `user` (role_id: 1) - role padrão para clientes
4. **Tem perfil** em `users_profile`
5. **Tem carteira** em `wallets` (para pontos)
6. **Pode acumular pontos** fazendo compras nos estabelecimentos

### ❌ **Não é:**

- ❌ Não é um registro na tabela `customers` (essa tabela é do sistema de microcrédito, não existe neste banco)
- ❌ Não precisa de um registro separado - é apenas um `user` com role `user`

## 📝 **Exemplo Prático**

```javascript
// Cliente se registra
const cliente = await User.create({
    username: "maria.santos",
    email: "maria@example.com",
    password: "senha123",
    first_name: "Maria",
    last_name: "Santos",
    phone: "+258841234568",
    bi: "9876543210987",
    role_id: 1,  // Role "user" = cliente
    is_active: true
});

// Cliente faz login
POST /api/auth/signin
{
    "username": "maria.santos",
    "password": "senha123"
}

// Cliente usa o app, faz compras, acumula pontos
// Sistema atualiza automaticamente `users_profile` e `wallets`
```

## 🔧 **Nota Importante**

Este banco (`maktubia_points`) é **diferente** do sistema de microcrédito:
- ✅ **Sistema de Pontos**: Usa `users` (clientes fazem login)
- ❌ **Sistema de Microcrédito**: Usa `customers` (não fazem login, são gerenciados por agentes)

Os dois sistemas são **separados** e funcionam de forma independente.