# 📊 Formatação de Dados de Clientes

## 🎯 **Problema Identificado**

Muitos campos estavam aparecendo como `null` na resposta da API, o que pode ser confuso para os usuários finais.

## ✅ **Solução Implementada**

### **1. Dois Formatos Disponíveis**

#### **Formato Original** (padrão)
- Mantém os valores `null` como estão no banco de dados
- Útil para desenvolvimento e integração com outros sistemas
- Endpoint: `GET /api/customers`

#### **Formato Amigável** (novo)
- Substitui `null` por valores amigáveis em português
- Inclui campos calculados úteis
- Endpoint: `GET /api/customers/friendly`

### **2. Valores de Substituição**

| Campo | Valor Original | Valor Amigável |
|-------|----------------|----------------|
| `date_of_birth` | `null` | `"Não informado"` |
| `id_number` | `null` | `"Não informado"` |
| `tax_number` | `null` | `"Não informado"` |
| `home_address` | `null` | `"Não informado"` |
| `mobile` | `null` | `"Não informado"` |
| `home_phone` | `null` | `"Não informado"` |
| `spouse_name` | `null` | `"Não aplicável"` |
| `next_kin_name` | `null` | `"Não informado"` |
| `employer_name` | `null` | `"Não informado"` |

### **3. Campos Calculados Adicionados**

| Campo | Descrição | Exemplo |
|-------|-----------|---------|
| `full_name` | Nome completo | `"Carlos Silva"` |
| `has_contact` | Tem contato (mobile ou home_phone) | `true` |
| `has_employer` | Tem empregador | `false` |
| `has_complete_info` | Tem informações completas | `false` |

## 🔧 **Como Usar**

### **Formato Original**
```bash
GET /api/customers
# ou
GET /api/customers?format=original
```

**Resposta:**
```json
{
  "customer_id": 54,
  "surname": "Silva",
  "firstname": "Carlos",
  "date_of_birth": null,
  "mobile": null,
  "home_phone": "+258211234567"
}
```

### **Formato Amigável**
```bash
GET /api/customers/friendly
# ou
GET /api/customers?format=friendly
```

**Resposta:**
```json
{
  "customer_id": 54,
  "surname": "Silva",
  "firstname": "Carlos",
  "date_of_birth": "Não informado",
  "mobile": "Não informado",
  "home_phone": "+258211234567",
  "full_name": "Carlos Silva",
  "has_contact": true,
  "has_employer": false,
  "has_complete_info": false
}
```

## 📋 **Exemplo Completo**

### **Cliente com Dados Completos (Maria Santos)**
```json
{
  "customer_id": 51,
  "surname": "Santos",
  "firstname": "Maria",
  "title": "Ms.",
  "date_of_birth": "1985-03-14T22:00:00.000Z",
  "id_number": "1234567689",
  "tax_number": "TAX123456",
  "home_address": "Av. Julius Nyerere, 1234, Maputo, Moçambique",
  "geotag": "Confirmed",
  "mobile": "+258 84 123 4567",
  "home_phone": "+258 21 123 456",
  "marital_status": "Married",
  "spouse_name": "Carlos Santos",
  "next_kin_name": "Ana Santos",
  "employer_id": 1,
  "employer_name": "Empresa Exemplo Ltda",
  "created_by": 1,
  "created_at": "2025-10-11T17:43:00.762Z",
  "updated_at": "2025-10-11T17:43:00.762Z",
  "full_name": "Maria Santos",
  "has_contact": true,
  "has_employer": true,
  "has_complete_info": true
}
```

### **Cliente com Dados Mínimos (Carlos Silva)**
```json
{
  "customer_id": 54,
  "surname": "Silva",
  "firstname": "Carlos",
  "title": "Mr.",
  "date_of_birth": "Não informado",
  "id_number": "Não informado",
  "tax_number": "Não informado",
  "home_address": "Rua Teste, 101",
  "geotag": "Not confirmed",
  "mobile": "Não informado",
  "home_phone": "+258211234567",
  "marital_status": "Single",
  "spouse_name": "Não aplicável",
  "next_kin_name": "Não informado",
  "employer_id": null,
  "employer_name": "Não informado",
  "created_by": 1,
  "created_at": "2025-10-11T18:00:51.180Z",
  "updated_at": "2025-10-11T18:00:51.180Z",
  "full_name": "Carlos Silva",
  "has_contact": true,
  "has_employer": false,
  "has_complete_info": false
}
```

## 🎯 **Benefícios**

1. **Clareza**: Valores `null` substituídos por texto amigável
2. **Flexibilidade**: Dois formatos disponíveis conforme necessidade
3. **Informação Extra**: Campos calculados úteis para análise
4. **Compatibilidade**: Formato original mantido para integrações
5. **Usabilidade**: Mais fácil para interfaces de usuário

## 🔄 **Endpoints Disponíveis**

| Endpoint | Formato | Descrição |
|----------|---------|-----------|
| `GET /api/customers` | Original | Dados brutos do banco |
| `GET /api/customers/friendly` | Amigável | Dados formatados |
| `GET /api/customers?format=friendly` | Amigável | Via parâmetro |
| `GET /api/customers/:id` | Original | Cliente específico |
| `GET /api/customers/:id?format=friendly` | Amigável | Cliente específico formatado |

## 📊 **Campos de Status**

### **has_contact**
- `true`: Cliente tem pelo menos um contato (mobile ou home_phone)
- `false`: Cliente não tem nenhum contato

### **has_employer**
- `true`: Cliente tem empregador associado
- `false`: Cliente não tem empregador

### **has_complete_info**
- `true`: Cliente tem data de nascimento, ID number e endereço
- `false`: Cliente não tem todas as informações básicas

---

**📅 Última Atualização**: 2025-01-11  
**👨‍💻 Desenvolvido por**: Sistema de Microcrédito  
**🔧 Versão**: 1.2.0 (Formatação Amigável)