# 🎯 **NOVA LÓGICA DE RELACIONAMENTOS AGENT-CUSTOMER-LOAN**

## 📋 **PROBLEMA IDENTIFICADO**

### ❌ **Lógica Anterior (Limitada)**
- **Relacionamento fixo**: `loans.agent_id` criava vínculo permanente
- **Sem histórico**: Não rastreava qual agente trouxe o cliente originalmente
- **Sem flexibilidade**: Cliente não podia ter diferentes agentes para diferentes empréstimos
- **Comissões incorretas**: Podia pagar comissão para agente errado

### ✅ **Nova Lógica (Flexível e Robusta)**
- **Relacionamento inicial**: Agente que trouxe o cliente (permanente)
- **Relacionamento por empréstimo**: Agente responsável por cada empréstimo (flexível)
- **Histórico completo**: Rastreabilidade de todos os relacionamentos
- **Comissões corretas**: Baseadas no agente correto para cada situação

---

## 🏗️ **ESTRUTURA IMPLEMENTADA**

### 📊 **Novas Tabelas**

#### 1. **`agent_customer_relationships`**
```sql
CREATE TABLE agent_customer_relationships (
    relationship_id SERIAL PRIMARY KEY,
    agent_id INTEGER NOT NULL REFERENCES agents(agent_id),
    customer_id INTEGER NOT NULL REFERENCES customers(customer_id),
    relationship_type VARCHAR(20) NOT NULL CHECK (relationship_type IN ('introduced', 'responsible', 'both')),
    relationship_date DATE NOT NULL DEFAULT CURRENT_DATE,
    is_active BOOLEAN DEFAULT TRUE,
    notes TEXT,
    created_by INTEGER REFERENCES users(user_id),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### 2. **`agent_loan_relationships`**
```sql
CREATE TABLE agent_loan_relationships (
    relationship_id SERIAL PRIMARY KEY,
    agent_id INTEGER NOT NULL REFERENCES agents(agent_id),
    loan_id INTEGER NOT NULL REFERENCES loans(loan_id),
    relationship_type VARCHAR(20) NOT NULL CHECK (relationship_type IN ('originating', 'processing', 'managing')),
    commission_rate DECIMAL(5,2),
    commission_amount DECIMAL(12,2),
    commission_paid BOOLEAN DEFAULT FALSE,
    commission_paid_date DATE,
    relationship_date DATE NOT NULL DEFAULT CURRENT_DATE,
    is_active BOOLEAN DEFAULT TRUE,
    notes TEXT,
    created_by INTEGER REFERENCES users(user_id),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

### 🔧 **Colunas Adicionadas**

#### **Tabela `customers`**
```sql
ALTER TABLE customers ADD COLUMN introduced_by_agent_id INTEGER REFERENCES agents(agent_id);
ALTER TABLE customers ADD COLUMN introduction_date DATE;
ALTER TABLE customers ADD COLUMN current_agent_id INTEGER REFERENCES agents(agent_id);
```

#### **Tabela `loans`**
```sql
ALTER TABLE loans ADD COLUMN originating_agent_id INTEGER REFERENCES agents(agent_id);
ALTER TABLE loans ADD COLUMN processing_agent_id INTEGER REFERENCES agents(agent_id);
ALTER TABLE loans ADD COLUMN managing_agent_id INTEGER REFERENCES agents(agent_id);
```

---

## 🎯 **TIPOS DE RELACIONAMENTOS**

### 👥 **Agent-Customer Relationships**

#### 1. **`introduced`** - Agente que trouxe o cliente
- **Descrição**: Agente que apresentou o cliente ao sistema
- **Permanência**: Relacionamento permanente
- **Comissão**: Comissão de introdução (uma vez)
- **Exemplo**: Agente A trouxe João Silva ao sistema

#### 2. **`responsible`** - Agente responsável pelo cliente
- **Descrição**: Agente que gerencia o relacionamento com o cliente
- **Permanência**: Pode mudar ao longo do tempo
- **Comissão**: Comissão de gestão (contínua)
- **Exemplo**: Agente B agora gerencia João Silva

#### 3. **`both`** - Agente que trouxe E gerencia
- **Descrição**: Agente que fez a introdução e continua gerenciando
- **Permanência**: Relacionamento duplo
- **Comissão**: Comissão de introdução + gestão
- **Exemplo**: Agente A trouxe e continua gerenciando João Silva

### 💰 **Agent-Loan Relationships**

#### 1. **`originating`** - Agente que originou o empréstimo
- **Descrição**: Agente responsável pela criação do empréstimo
- **Comissão**: Comissão de origem (por empréstimo)
- **Exemplo**: Agente A originou o primeiro empréstimo de João

#### 2. **`processing`** - Agente que processou o empréstimo
- **Descrição**: Agente que fez o processamento/aprovação
- **Comissão**: Comissão de processamento
- **Exemplo**: Agente B processou o segundo empréstimo de João

#### 3. **`managing`** - Agente que gerencia o empréstimo
- **Descrição**: Agente responsável pela gestão do empréstimo
- **Comissão**: Comissão de gestão (contínua)
- **Exemplo**: Agente C gerencia o empréstimo de João

---

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

### 📋 **Cenário 1: Cliente Novo**
```
1. Agente A encontra João Silva (cliente potencial)
2. Agente A apresenta João ao sistema (introduced)
3. Agente A cria primeiro empréstimo (originating)
4. Relacionamentos:
   - Agent-Customer: A → João (introduced)
   - Agent-Loan: A → Empréstimo 1 (originating)
```

### 📋 **Cenário 2: Cliente Existente, Novo Empréstimo**
```
1. João Silva já existe no sistema (introduzido por Agente A)
2. Agente B processa novo empréstimo para João
3. Relacionamentos:
   - Agent-Customer: A → João (introduced) [mantido]
   - Agent-Loan: B → Empréstimo 2 (originating) [novo]
```

### 📋 **Cenário 3: Mudança de Agente Responsável**
```
1. João Silva é transferido do Agente A para Agente C
2. Relacionamentos:
   - Agent-Customer: A → João (introduced) [histórico]
   - Agent-Customer: C → João (responsible) [atual]
   - Agent-Loan: A → Empréstimo 1 (originating) [histórico]
   - Agent-Loan: C → Empréstimo 1 (managing) [atual]
```

### 📋 **Cenário 4: Múltiplos Agentes, Um Empréstimo**
```
1. Agente A originou o empréstimo
2. Agente B processou a aprovação
3. Agente C gerencia o empréstimo
4. Relacionamentos:
   - Agent-Loan: A → Empréstimo (originating)
   - Agent-Loan: B → Empréstimo (processing)
   - Agent-Loan: C → Empréstimo (managing)
```

---

## 💰 **CÁLCULO DE COMISSÕES**

### 📊 **Comissões por Tipo de Relacionamento**

#### **Agent-Customer**
- **`introduced`**: 2-5% do valor do primeiro empréstimo
- **`responsible`**: 0.5-1% do valor total dos empréstimos (mensal)
- **`both`**: Introdução + Responsabilidade

#### **Agent-Loan**
- **`originating`**: 3-8% do valor do empréstimo
- **`processing`**: 1-3% do valor do empréstimo
- **`managing`**: 0.5-1% do valor do empréstimo (mensal)

### 🧮 **Exemplo de Cálculo**

```
Cliente: João Silva
Empréstimo 1: MZN 10,000 (Agente A - originating)
Empréstimo 2: MZN 15,000 (Agente B - originating)

Comissões:
- Agente A: 5% de MZN 10,000 = MZN 500 (originating)
- Agente B: 5% de MZN 15,000 = MZN 750 (originating)
- Agente A: 1% de MZN 10,000 = MZN 100/mês (introduced)
- Agente B: 1% de MZN 15,000 = MZN 150/mês (introduced)
```

---

## 🔍 **QUERIES ÚTEIS**

### 📊 **Buscar Clientes de um Agente**
```sql
SELECT 
    c.customer_id,
    c.firstname,
    c.surname,
    acr.relationship_type,
    acr.relationship_date
FROM customers c
JOIN agent_customer_relationships acr ON c.customer_id = acr.customer_id
WHERE acr.agent_id = ? AND acr.is_active = TRUE;
```

### 📊 **Buscar Empréstimos de um Agente**
```sql
SELECT 
    l.loan_id,
    l.loan_app_id,
    l.loan_amount,
    alr.relationship_type,
    alr.commission_amount
FROM loans l
JOIN agent_loan_relationships alr ON l.loan_id = alr.loan_id
WHERE alr.agent_id = ? AND alr.is_active = TRUE;
```

### 📊 **Histórico Completo de um Cliente**
```sql
SELECT 
    c.firstname,
    c.surname,
    a.agent_name,
    acr.relationship_type as customer_relationship,
    acr.relationship_date as customer_date,
    l.loan_app_id,
    alr.relationship_type as loan_relationship,
    alr.relationship_date as loan_date
FROM customers c
LEFT JOIN agent_customer_relationships acr ON c.customer_id = acr.customer_id
LEFT JOIN agents a ON acr.agent_id = a.agent_id
LEFT JOIN loans l ON c.customer_id = l.customer_id
LEFT JOIN agent_loan_relationships alr ON l.loan_id = alr.loan_id
WHERE c.customer_id = ?;
```

### 📊 **Comissões Pendentes**
```sql
SELECT 
    a.agent_name,
    alr.commission_amount,
    alr.relationship_type,
    l.loan_app_id,
    alr.relationship_date
FROM agent_loan_relationships alr
JOIN agents a ON alr.agent_id = a.agent_id
JOIN loans l ON alr.loan_id = l.loan_id
WHERE alr.commission_paid = FALSE AND alr.is_active = TRUE;
```

---

## 🚀 **BENEFÍCIOS DA NOVA LÓGICA**

### ✅ **Flexibilidade**
- Cliente pode ter diferentes agentes para diferentes empréstimos
- Agente pode ser responsável por diferentes aspectos do relacionamento
- Mudanças de responsabilidade são rastreadas

### ✅ **Rastreabilidade**
- Histórico completo de relacionamentos
- Auditoria de mudanças
- Transparência nas comissões

### ✅ **Precisão**
- Comissões calculadas corretamente
- Agente certo recebe o pagamento certo
- Relacionamentos claros e definidos

### ✅ **Escalabilidade**
- Sistema suporta crescimento
- Múltiplos agentes por cliente/empréstimo
- Estrutura preparada para complexidade futura

---

## 🎯 **PRÓXIMOS PASSOS**

1. **Atualizar Controllers**: Modificar controllers para usar nova lógica
2. **Criar Endpoints**: Endpoints para gerenciar relacionamentos
3. **Implementar Cálculo de Comissões**: Sistema automático de comissões
4. **Criar Relatórios**: Relatórios de performance por agente
5. **Dashboard**: Interface para visualizar relacionamentos

---

## 🎉 **SISTEMA PRONTO!**

A nova lógica está implementada e funcionando! O sistema agora suporta:

- ✅ **Relacionamentos flexíveis** entre agentes, clientes e empréstimos
- ✅ **Histórico completo** de todos os relacionamentos
- ✅ **Comissões precisas** baseadas no agente correto
- ✅ **Rastreabilidade** de mudanças e responsabilidades
- ✅ **Escalabilidade** para crescimento futuro

**A lógica está muito mais robusta e reflete a realidade do negócio!** 🚀