# 🎯 **ATUALIZAÇÃO DAS TABELAS AGENTS E PAYMENTS**

## 📋 **RESUMO DAS ALTERAÇÕES**

### ✅ **Tabela `agents` Atualizada**
- **Suporte a 3 tipos de agentes**: `employee`, `user`, `external`
- **Relacionamentos flexíveis**: `employee_id`, `user_id` ou dados externos
- **Campos adicionais**: `agent_type`, `id_number`, `tax_number`, `bank_account`, `bank_name`, `hire_date`
- **Controle de status**: `Active`, `Inactive`, `Terminated`

### ✅ **Tabela `payments` Atualizada**
- **Suporte a múltiplos tipos de pagamento**: `loan_payment`, `agent_commission`, `employee_salary`, `employee_bonus`, `customer_refund`, `other`
- **Relacionamentos flexíveis**: `loan_id`, `agent_id`, `customer_id`, `employee_id` (pelo menos um deve ser preenchido)
- **Controle de status**: `Pending`, `Completed`, `Failed`, `Cancelled`
- **Métodos de pagamento**: `cash`, `bank_transfer`, `mobile_money`, `check`, `other`

---

## 🏗️ **ESTRUTURA DAS TABELAS**

### 📊 **Tabela `agents`**
```sql
CREATE TABLE agents (
    agent_id SERIAL PRIMARY KEY,
    agent_name VARCHAR(200) NOT NULL,
    agent_code VARCHAR(50) UNIQUE NOT NULL,
    agent_type VARCHAR(20) NOT NULL CHECK (agent_type IN ('employee', 'user', 'external')),
    employee_id INTEGER REFERENCES employees(employee_id) ON DELETE SET NULL,
    user_id INTEGER REFERENCES users(user_id) ON DELETE SET NULL,
    commission_rate DECIMAL(5,2) DEFAULT 0.00,
    phone VARCHAR(20),
    email VARCHAR(100),
    address TEXT,
    id_number VARCHAR(50),
    tax_number VARCHAR(50),
    bank_account VARCHAR(100),
    bank_name VARCHAR(100),
    status VARCHAR(20) DEFAULT 'Active' CHECK (status IN ('Active', 'Inactive', 'Terminated')),
    hire_date DATE,
    created_by INTEGER REFERENCES users(user_id),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

### 💰 **Tabela `payments`**
```sql
CREATE TABLE payments (
    payment_id SERIAL PRIMARY KEY,
    payment_type VARCHAR(20) NOT NULL CHECK (payment_type IN ('loan_payment', 'agent_commission', 'employee_salary', 'employee_bonus', 'customer_refund', 'other')),
    amount DECIMAL(12,2) NOT NULL,
    currency VARCHAR(3) DEFAULT 'MZN',
    payment_method VARCHAR(20) NOT NULL CHECK (payment_method IN ('cash', 'bank_transfer', 'mobile_money', 'check', 'other')),
    payment_date DATE NOT NULL,
    description TEXT,
    reference_number VARCHAR(100),
    
    -- Relacionamentos (pelo menos um deve ser preenchido)
    loan_id INTEGER REFERENCES loans(loan_id) ON DELETE CASCADE,
    agent_id INTEGER REFERENCES agents(agent_id) ON DELETE CASCADE,
    customer_id INTEGER REFERENCES customers(customer_id) ON DELETE CASCADE,
    employee_id INTEGER REFERENCES employees(employee_id) ON DELETE CASCADE,
    
    -- Status e controle
    status VARCHAR(20) DEFAULT 'Pending' CHECK (status IN ('Pending', 'Completed', 'Failed', 'Cancelled')),
    processed_by INTEGER REFERENCES users(user_id),
    processed_at TIMESTAMP,
    
    -- Auditoria
    created_by INTEGER REFERENCES users(user_id),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

---

## 🎯 **TIPOS DE AGENTES**

### 1. **Agente Funcionário** (`employee`)
- **Descrição**: Funcionário da empresa
- **Campos obrigatórios**: `employee_id`
- **Campos opcionais**: `user_id`
- **Comissão**: 3.0% - 8.0%
- **Benefícios**: Salário fixo + Comissão + Benefícios da empresa

### 2. **Agente Usuário** (`user`)
- **Descrição**: Usuário do sistema
- **Campos obrigatórios**: `user_id`
- **Comissão**: 4.0% - 7.0%
- **Benefícios**: Comissão + Acesso ao sistema

### 3. **Agente Externo** (`external`)
- **Descrição**: Pessoa externa à empresa
- **Campos obrigatórios**: `id_number`, `tax_number`, `bank_account`
- **Comissão**: 5.0% - 10.0%
- **Benefícios**: Comissão mais alta + Flexibilidade

---

## 💰 **TIPOS DE PAGAMENTO**

### 1. **Pagamento de Empréstimo** (`loan_payment`)
- **Descrição**: Pagamento de parcela de empréstimo
- **Campos obrigatórios**: `loan_id`
- **Métodos**: `cash`, `bank_transfer`, `mobile_money`, `check`

### 2. **Comissão de Agente** (`agent_commission`)
- **Descrição**: Comissão paga ao agente
- **Campos obrigatórios**: `agent_id`
- **Métodos**: `bank_transfer`, `cash`

### 3. **Salário de Funcionário** (`employee_salary`)
- **Descrição**: Salário mensal do funcionário
- **Campos obrigatórios**: `employee_id`
- **Métodos**: `bank_transfer`

### 4. **Bônus de Funcionário** (`employee_bonus`)
- **Descrição**: Bônus de performance
- **Campos obrigatórios**: `employee_id`
- **Métodos**: `bank_transfer`, `cash`

### 5. **Reembolso para Cliente** (`customer_refund`)
- **Descrição**: Reembolso de pagamento em excesso
- **Campos obrigatórios**: `customer_id`
- **Métodos**: `cash`, `bank_transfer`, `mobile_money`

### 6. **Outros** (`other`)
- **Descrição**: Outros tipos de pagamento
- **Campos obrigatórios**: Nenhum específico
- **Métodos**: Todos disponíveis

---

## 📊 **DADOS DE EXEMPLO INSERIDOS**

### **Agentes**
- **AGT001**: Carlos Mendes (Funcionário)
- **AGT002**: Maria Santos (Usuário)
- **AGT003**: Pedro Fernandes (Externo)

### **Pagamentos**
- **4 pagamentos de empréstimo**: Total MZN 3,850.00
- **1 comissão de agente**: MZN 50.00
- **1 salário de funcionário**: MZN 25,000.00
- **1 bônus de funcionário**: MZN 5,000.00
- **1 reembolso para cliente**: MZN 200.00

---

## 🔗 **RELACIONAMENTOS**

### **Agents**
- `employee_id` → `employees(employee_id)`
- `user_id` → `users(user_id)`
- `created_by` → `users(user_id)`

### **Payments**
- `loan_id` → `loans(loan_id)`
- `agent_id` → `agents(agent_id)`
- `customer_id` → `customers(customer_id)`
- `employee_id` → `employees(employee_id)`
- `processed_by` → `users(user_id)`
- `created_by` → `users(user_id)`

---

## 📈 **ÍNDICES CRIADOS**

### **Agents**
- `idx_agents_agent_type`
- `idx_agents_employee_id`
- `idx_agents_user_id`
- `idx_agents_agent_code`

### **Payments**
- `idx_payments_payment_type`
- `idx_payments_payment_date`
- `idx_payments_status`
- `idx_payments_loan_id`
- `idx_payments_agent_id`
- `idx_payments_customer_id`
- `idx_payments_employee_id`
- `idx_payments_reference_number`
- `idx_payments_processed_by`

---

## 🎯 **FUNCIONALIDADES IMPLEMENTADAS**

### ✅ **Agents**
- Suporte a 3 tipos de agentes
- Relacionamentos flexíveis
- Controle de comissões
- Dados bancários para pagamentos
- Status de ativação

### ✅ **Payments**
- Múltiplos tipos de pagamento
- Relacionamentos flexíveis
- Controle de status
- Métodos de pagamento diversos
- Auditoria completa

### ✅ **Sistema**
- Índices para performance
- Constraints de integridade
- Dados de exemplo
- Relacionamentos corretos

---

## 🚀 **PRÓXIMOS PASSOS**

1. **Implementar CRUD para Agents**
2. **Implementar CRUD para Payments**
3. **Criar relatórios de comissões**
4. **Implementar cálculos automáticos**
5. **Criar dashboard de pagamentos**

---

## 📝 **ARQUIVOS CRIADOS**

- `update-agents-and-payments-tables.js` - Script de atualização inicial
- `update-payments-table-structure.js` - Atualização da estrutura de payments
- `fix-payments-loan-id-constraint.js` - Correção da constraint loan_id
- `agents-and-payments-examples.js` - Exemplos de dados
- `AGENTS_AND_PAYMENTS_UPDATE_SUMMARY.md` - Este resumo

---

## 🎉 **SISTEMA ATUALIZADO COM SUCESSO!**

O sistema agora suporta:
- ✅ **Agentes flexíveis** (funcionários, usuários, externos)
- ✅ **Pagamentos múltiplos** (empréstimos, comissões, salários, bônus, reembolsos)
- ✅ **Relacionamentos corretos** entre todas as entidades
- ✅ **Performance otimizada** com índices
- ✅ **Integridade de dados** com constraints
- ✅ **Auditoria completa** de todas as operações

**O sistema está pronto para implementar os CRUDs de Agents e Payments!** 🚀