# 📄 Implementação: Documentos Moçambicanos

## ✅ Mudanças Implementadas

### 1. **Substituição do campo `BI` por `tipo_documento` e `numero_documento`**

#### Campos Adicionados:
- `tipo_documento` (VARCHAR(20)): Tipo de documento moçambicano
- `numero_documento` (VARCHAR(50)): Número do documento

#### Tipos de Documentos Suportados:
- **BI** (Bilhete de Identidade): 9 dígitos + 1 letra (ex: 123456789A)
- **PASSAPORTE**: Formato variável, geralmente letras e números (6-20 caracteres)
- **DIRE** (Documento de Identificação de Residente Estrangeiro): 8-20 caracteres
- **CARTA_CONDUCAO**: 2 letras + 6-8 dígitos (ex: AB123456)
- **OUTRO**: Sem validação de formato específico (3-50 caracteres)

### 2. **Constraints UNIQUE**

#### Campos com UNIQUE:
- `numero_documento`: UNIQUE (apenas valores não nulos)
- `phone`: UNIQUE (apenas valores não nulos)
- `email`: UNIQUE (apenas valores não nulos)

### 3. **Email Opcional**

- `email` não é mais obrigatório (removido `NOT NULL`)
- Validação de formato quando fornecido
- Verificação de unicidade quando fornecido

### 4. **Validação de Documentos**

#### Validador Criado: `utils/documentValidator.js`

**Funções disponíveis:**
- `validateDocumentNumber(tipoDocumento, numeroDocumento)`: Valida formato baseado no tipo
- `validatePhoneNumber(phone)`: Valida formato moçambicano
- `validateEmail(email)`: Valida formato de email
- `validateUserDocument(data)`: Valida todos os campos de uma vez

#### Formatos Aceites:

**BI:**
- Formato: 9 dígitos + 1 letra
- Exemplo: `123456789A`

**Passaporte:**
- Formato: Letras seguidas de números
- Tamanho: 6-20 caracteres
- Exemplo: `AB123456`

**DIRE:**
- Formato: Letras e/ou números
- Tamanho: 8-20 caracteres

**Carta de Condução:**
- Formato: 2 letras + 6-8 dígitos
- Exemplo: `AB123456`

**Telefone Moçambicano:**
- Formatos aceites:
  - `+258XXXXXXXXX` (código internacional)
  - `258XXXXXXXXX` (sem +)
  - `8XXXXXXXX` (formato local)
  - `84XXXXXXXX` (formato alternativo)

### 5. **Métodos Adicionados ao Modelo**

#### `UsersModel.js`:
- `findByPhone(phone)`: Buscar usuário por telefone
- `findByDocumentNumber(numeroDocumento)`: Buscar usuário por número de documento

### 6. **Controller Atualizado**

#### `userController.js`:
- Validação de tipo e número de documento
- Verificação de unicidade de `numero_documento`, `phone` e `email`
- Email opcional na criação de usuário
- Resposta inclui `tipoDocumento` e `numeroDocumento`

## 📋 Migration SQL

### Arquivo: `database/migrate-users-document-types.sql`

**O que faz:**
1. Adiciona colunas `tipo_documento` e `numero_documento`
2. Migra dados existentes de `bi` para `numero_documento` (assumindo tipo "BI")
3. Remove constraint `NOT NULL` do `email`
4. Adiciona constraints UNIQUE para `numero_documento`, `phone` e `email`
5. Adiciona constraint CHECK para `tipo_documento` válido
6. **NÃO remove** a coluna `bi` automaticamente (comentado por segurança)

**Para executar:**
```sql
\i database/migrate-users-document-types.sql
```

Ou via psql:
```bash
psql -U seu_usuario -d maktubia_points -f database/migrate-users-document-types.sql
```

## 🔄 Compatibilidade

### Durante a Migração:
- O código verifica dinamicamente quais colunas existem
- Suporta tanto `bi` quanto `tipo_documento`/`numero_documento`
- Resposta inclui ambos os formatos para compatibilidade

### Após a Migração:
- Remover coluna `bi` manualmente quando todos os dados estiverem migrados
- Atualizar código para remover referências a `bi`

## 📝 Exemplo de Uso

### Criar Usuário com Documento:

```json
POST /api/users
{
  "username": "joao.silva",
  "email": "joao@example.com",  // Opcional
  "password": "SenhaSegura123!",
  "first_name": "João",
  "last_name": "Silva",
  "phone": "+258841234567",  // UNIQUE
  "tipo_documento": "BI",
  "numero_documento": "123456789A",  // UNIQUE
  "role_id": 1
}
```

### Resposta:

```json
{
  "success": true,
  "data": {
    "id": 123,
    "username": "joao.silva",
    "email": "joao@example.com",
    "firstName": "João",
    "lastName": "Silva",
    "phone": "+258841234567",
    "tipoDocumento": "BI",
    "numeroDocumento": "123456789A",
    "bi": null,  // Mantido para compatibilidade
    "isActive": true,
    ...
  }
}
```

## ⚠️ Notas Importantes

1. **Unicidade**: `numero_documento`, `phone` e `email` são únicos (apenas valores não nulos)
2. **Email Opcional**: Email não é mais obrigatório, mas se fornecido deve ser válido e único
3. **Validação**: Formato do documento é validado baseado no tipo
4. **Migração**: Dados existentes de `bi` são migrados automaticamente para `numero_documento` (tipo "BI")
5. **Compatibilidade**: Código suporta ambos os formatos durante a migração

## 🚀 Próximos Passos

1. Executar migration SQL
2. Testar criação de usuários com diferentes tipos de documentos
3. Verificar unicidade de `numero_documento`, `phone` e `email`
4. Remover coluna `bi` após confirmação de migração completa
5. Atualizar frontend para usar novos campos