# 🎯 **SISTEMA DE INTERAÇÕES COM CLIENTES**

## 📋 **PROBLEMA RESOLVIDO**

### ❌ **Problema Anterior**
- **Sem histórico**: Não havia registro de tentativas de contato
- **Sem comentários**: Não havia lugar para anotar o que o cliente disse
- **Sem rastreamento**: Não sabíamos quantas vezes tentamos contatar
- **Sem organização**: Informações espalhadas e perdidas

### ✅ **Solução Implementada**
- **Histórico completo**: Todas as interações registradas
- **Comentários detalhados**: O que o cliente disse e prometeu
- **Rastreamento de contatos**: Tentativas com e sem sucesso
- **Organização por prioridade**: Urgente, alta, média, baixa
- **Acompanhamento**: Próximas ações e datas

---

## 🏗️ **ESTRUTURA IMPLEMENTADA**

### 📊 **Tabelas Criadas**

#### 1. **`customer_interactions`** - Interações com Clientes
```sql
CREATE TABLE customer_interactions (
    interaction_id SERIAL PRIMARY KEY,
    customer_id INTEGER NOT NULL REFERENCES customers(customer_id),
    loan_id INTEGER REFERENCES loans(loan_id),
    interaction_type VARCHAR(20) NOT NULL, -- phone_call, sms, email, visit, meeting, other
    contact_method VARCHAR(20) NOT NULL,   -- phone, mobile, email, in_person, whatsapp, other
    contact_status VARCHAR(20) NOT NULL,   -- successful, no_answer, busy, wrong_number, customer_unavailable, other
    interaction_purpose VARCHAR(50) NOT NULL, -- payment_reminder, payment_overdue, loan_inquiry, customer_service, follow_up, new_loan_offer, other
    subject VARCHAR(200) NOT NULL,
    description TEXT NOT NULL,
    customer_response TEXT,
    customer_promise TEXT,
    next_action TEXT,
    next_contact_date DATE,
    priority VARCHAR(10) DEFAULT 'medium', -- low, medium, high, urgent
    is_resolved BOOLEAN DEFAULT FALSE,
    resolved_date DATE,
    resolved_by INTEGER REFERENCES users(user_id),
    created_by INTEGER NOT NULL REFERENCES users(user_id),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### 2. **`debt_comments`** - Comentários sobre Dívidas
```sql
CREATE TABLE debt_comments (
    comment_id SERIAL PRIMARY KEY,
    customer_id INTEGER NOT NULL REFERENCES customers(customer_id),
    loan_id INTEGER REFERENCES loans(loan_id),
    comment_type VARCHAR(20) NOT NULL, -- payment_issue, customer_explanation, payment_promise, dispute, resolution, other
    comment_category VARCHAR(20) NOT NULL, -- overdue, partial_payment, payment_plan, financial_difficulty, dispute, resolution, other
    title VARCHAR(200) NOT NULL,
    comment_text TEXT NOT NULL,
    is_private BOOLEAN DEFAULT FALSE,
    is_resolved BOOLEAN DEFAULT FALSE,
    resolved_date DATE,
    resolved_by INTEGER REFERENCES users(user_id),
    created_by INTEGER NOT NULL REFERENCES users(user_id),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### 3. **`contact_history`** - Histórico de Contatos
```sql
CREATE TABLE contact_history (
    history_id SERIAL PRIMARY KEY,
    customer_id INTEGER NOT NULL REFERENCES customers(customer_id),
    contact_type VARCHAR(20) NOT NULL, -- phone_call, sms, email, visit, meeting, whatsapp, other
    contact_direction VARCHAR(10) NOT NULL, -- inbound, outbound
    contact_number VARCHAR(20),
    contact_email VARCHAR(100),
    contact_duration INTEGER, -- em segundos para chamadas
    contact_status VARCHAR(20) NOT NULL, -- successful, no_answer, busy, wrong_number, customer_unavailable, voicemail, other
    contact_reason VARCHAR(100),
    contact_notes TEXT,
    follow_up_required BOOLEAN DEFAULT FALSE,
    follow_up_date DATE,
    created_by INTEGER REFERENCES users(user_id),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### 4. **`payment_promises`** - Promessas de Pagamento
```sql
CREATE TABLE payment_promises (
    promise_id SERIAL PRIMARY KEY,
    customer_id INTEGER NOT NULL REFERENCES customers(customer_id),
    loan_id INTEGER REFERENCES loans(loan_id),
    promise_date DATE NOT NULL,
    promise_amount DECIMAL(12,2) NOT NULL,
    promise_type VARCHAR(20) NOT NULL, -- full_payment, partial_payment, payment_plan, extension, other
    promise_status VARCHAR(20) DEFAULT 'pending', -- pending, fulfilled, broken, modified, cancelled
    actual_payment_date DATE,
    actual_payment_amount DECIMAL(12,2),
    payment_method VARCHAR(50),
    promise_notes TEXT,
    customer_commitment TEXT,
    is_reminder_sent BOOLEAN DEFAULT FALSE,
    reminder_sent_date DATE,
    created_by INTEGER NOT NULL REFERENCES users(user_id),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

---

## 🎯 **TIPOS DE INTERAÇÕES**

### 📞 **Tipos de Interação**
- **`phone_call`**: Ligação telefônica
- **`sms`**: Mensagem SMS
- **`email`**: Email
- **`visit`**: Visita pessoal
- **`meeting`**: Reunião
- **`other`**: Outros

### 📱 **Métodos de Contato**
- **`phone`**: Telefone fixo
- **`mobile`**: Telemóvel
- **`email`**: Email
- **`in_person`**: Pessoalmente
- **`whatsapp`**: WhatsApp
- **`other`**: Outros

### 📊 **Status do Contato**
- **`successful`**: Bem-sucedido
- **`no_answer`**: Sem resposta
- **`busy`**: Ocupado
- **`wrong_number`**: Número errado
- **`customer_unavailable`**: Cliente indisponível
- **`other`**: Outros

### 🎯 **Propósito da Interação**
- **`payment_reminder`**: Lembrete de pagamento
- **`payment_overdue`**: Pagamento em atraso
- **`loan_inquiry`**: Consulta de empréstimo
- **`customer_service`**: Atendimento ao cliente
- **`follow_up`**: Acompanhamento
- **`new_loan_offer`**: Oferta de novo empréstimo
- **`other`**: Outros

### ⚠️ **Prioridades**
- **`urgent`**: Urgente
- **`high`**: Alta
- **`medium`**: Média
- **`low`**: Baixa

---

## 🔄 **CENÁRIOS DE USO**

### 📋 **Cenário 1: Cliente com Pagamento em Atraso**
```
Situação: Cliente tem pagamento em atraso de 15 dias
Ação: Ligação telefônica para lembrar sobre o pagamento
Resultado: Cliente promete pagar até sexta-feira

Interação:
- Tipo: phone_call
- Método: mobile
- Status: successful
- Propósito: payment_overdue
- Resposta: "Cliente disse que teve problemas financeiros mas prometeu pagar até sexta-feira"
- Promessa: "Pagamento de MZN 950 até sexta-feira"
- Próxima ação: "Ligar novamente na sexta-feira para confirmar"
- Prioridade: high
```

### 📋 **Cenário 2: Tentativa de Contato sem Sucesso**
```
Situação: Cliente não atende o telefone
Ação: Tentativa de ligação
Resultado: Sem resposta

Interação:
- Tipo: phone_call
- Método: mobile
- Status: no_answer
- Propósito: payment_overdue
- Resposta: null
- Próxima ação: "Tentar contato novamente amanhã em horário diferente"
- Prioridade: medium
```

### 📋 **Cenário 3: Cliente Explica Situação Financeira**
```
Situação: Cliente explica dificuldades financeiras
Ação: Ligação de atendimento ao cliente
Resultado: Cliente explica situação e promete pagamento parcial

Interação:
- Tipo: phone_call
- Método: mobile
- Status: successful
- Propósito: customer_service
- Resposta: "Cliente está passando por dificuldades financeiras devido à perda do emprego"
- Promessa: "Pagamento parcial de MZN 300 na próxima semana"
- Próxima ação: "Avaliar possibilidade de reestruturação do empréstimo"
- Prioridade: medium
```

### 📋 **Cenário 4: Visita Pessoal**
```
Situação: Visita ao cliente para acompanhamento
Ação: Visita pessoal
Resultado: Cliente agradece e confirma pagamento

Interação:
- Tipo: visit
- Método: in_person
- Status: successful
- Propósito: follow_up
- Resposta: "Cliente agradeceu a visita e confirmou que está fazendo o possível"
- Promessa: "Pagamento de MZN 500 na próxima semana"
- Próxima ação: "Acompanhar pagamento prometido"
- Prioridade: medium
```

### 📋 **Cenário 5: Resolução da Situação**
```
Situação: Cliente efetuou pagamento
Ação: Ligação de confirmação
Resultado: Situação resolvida

Interação:
- Tipo: phone_call
- Método: mobile
- Status: successful
- Propósito: follow_up
- Resposta: "Cliente confirmou o pagamento e agradeceu pela paciência"
- Resolvido: true
- Prioridade: low
```

---

## 💰 **COMENTÁRIOS SOBRE DÍVIDAS**

### 📝 **Tipos de Comentários**
- **`payment_issue`**: Problema com pagamento
- **`customer_explanation`**: Explicação do cliente
- **`payment_promise`**: Promessa de pagamento
- **`dispute`**: Disputa
- **`resolution`**: Resolução
- **`other`**: Outros

### 📊 **Categorias de Comentários**
- **`overdue`**: Em atraso
- **`partial_payment`**: Pagamento parcial
- **`payment_plan`**: Plano de pagamento
- **`financial_difficulty`**: Dificuldade financeira
- **`dispute`**: Disputa
- **`resolution`**: Resolução
- **`other`**: Outros

### 💬 **Exemplo de Comentário**
```
Título: "Cliente com dificuldades financeiras temporárias"
Tipo: customer_explanation
Categoria: financial_difficulty
Texto: "Cliente explicou que perdeu o emprego temporariamente e está procurando novo trabalho. Tem histórico de bom pagador. Sugerir plano de pagamento flexível."
Privado: false
```

---

## 📞 **HISTÓRICO DE CONTATOS**

### 📊 **Direção do Contato**
- **`inbound`**: Cliente ligou para nós
- **`outbound`**: Nós ligamos para o cliente

### 📱 **Tipos de Contato**
- **`phone_call`**: Ligação telefônica
- **`sms`**: SMS
- **`email`**: Email
- **`visit`**: Visita
- **`meeting`**: Reunião
- **`whatsapp`**: WhatsApp
- **`other`**: Outros

### 📝 **Exemplo de Histórico**
```
Tipo: phone_call
Direção: outbound
Número: +258 84 222 2222
Duração: 180 segundos
Status: successful
Motivo: Lembrete de pagamento em atraso
Notas: Cliente atendeu na segunda tentativa. Muito educado e comprometido com o pagamento.
Follow-up: true
Data: 2024-01-26
```

---

## 🤝 **PROMESSAS DE PAGAMENTO**

### 💰 **Tipos de Promessa**
- **`full_payment`**: Pagamento total
- **`partial_payment`**: Pagamento parcial
- **`payment_plan`**: Plano de pagamento
- **`extension`**: Extensão
- **`other`**: Outros

### 📊 **Status da Promessa**
- **`pending`**: Pendente
- **`fulfilled`**: Cumprida
- **`broken`**: Quebrada
- **`modified`**: Modificada
- **`cancelled`**: Cancelada

### 💬 **Exemplo de Promessa**
```
Data da promessa: 2024-01-26
Valor prometido: MZN 950.00
Tipo: full_payment
Status: pending
Notas: Cliente prometeu pagar o valor total em atraso
Compromisso: "Vou fazer o pagamento até sexta-feira, tenho certeza que conseguirei o dinheiro."
Lembrete enviado: false
```

---

## 🔍 **QUERIES ÚTEIS**

### 📊 **Buscar Interações de um Cliente**
```sql
SELECT 
    ci.interaction_id,
    ci.subject,
    ci.interaction_type,
    ci.contact_status,
    ci.priority,
    ci.created_at
FROM customer_interactions ci
WHERE ci.customer_id = ? 
ORDER BY ci.created_at DESC;
```

### 📊 **Buscar Interações Pendentes**
```sql
SELECT 
    ci.interaction_id,
    ci.subject,
    ci.priority,
    ci.next_contact_date,
    c.firstname,
    c.surname
FROM customer_interactions ci
JOIN customers c ON ci.customer_id = c.customer_id
WHERE ci.is_resolved = FALSE
ORDER BY ci.priority DESC, ci.next_contact_date ASC;
```

### 📊 **Buscar Promessas de Pagamento Pendentes**
```sql
SELECT 
    pp.promise_id,
    pp.promise_date,
    pp.promise_amount,
    pp.promise_type,
    c.firstname,
    c.surname
FROM payment_promises pp
JOIN customers c ON pp.customer_id = c.customer_id
WHERE pp.promise_status = 'pending'
ORDER BY pp.promise_date ASC;
```

### 📊 **Estatísticas de Contatos**
```sql
SELECT 
    contact_status,
    COUNT(*) as count
FROM contact_history
WHERE created_at >= CURRENT_DATE - INTERVAL '30 days'
GROUP BY contact_status;
```

---

## 🚀 **BENEFÍCIOS DO SISTEMA**

### ✅ **Rastreabilidade Completa**
- Histórico de todas as tentativas de contato
- Registro de sucessos e falhas
- Acompanhamento de promessas

### ✅ **Organização**
- Prioridades claras (urgente, alta, média, baixa)
- Próximas ações definidas
- Datas de follow-up

### ✅ **Comunicação**
- O que o cliente disse
- O que o cliente prometeu
- Como o cliente reagiu

### ✅ **Gestão**
- Status de resolução
- Quem criou e quem resolveu
- Timestamps de todas as ações

### ✅ **Relatórios**
- Estatísticas de contatos
- Taxa de sucesso
- Tempo médio de resolução

---

## 🎯 **PRÓXIMOS PASSOS**

1. **Criar Controllers**: Implementar CRUD para todas as tabelas
2. **Criar Endpoints**: APIs para gerenciar interações
3. **Dashboard**: Interface para visualizar interações
4. **Relatórios**: Relatórios de performance de contatos
5. **Notificações**: Alertas para follow-ups pendentes
6. **Integração**: Integrar com sistema de pagamentos

---

## 🎉 **SISTEMA IMPLEMENTADO!**

### ✅ **O que foi criado:**
- **4 tabelas** para rastrear interações
- **Índices** para performance
- **Dados de exemplo** para demonstração
- **Model** para operações de banco
- **Documentação** completa

### 🚀 **Sistema pronto para:**
- ✅ Rastrear todas as interações com clientes
- ✅ Registrar comentários sobre dívidas
- ✅ Manter histórico de contatos
- ✅ Acompanhar promessas de pagamento
- ✅ Organizar por prioridades
- ✅ Gerar relatórios e estatísticas

**Agora você tem um sistema completo para gerenciar todas as interações com clientes!** 🎯