# 🔄 Sistema de Interoperabilidade Multi-Merchant

## 📋 Visão Geral

Sistema completo que permite que pontos criados/emitidos por um Merchant A numa campanha específica possam ser resgatados por um cliente num Merchant B, desde que exista autorização explícita entre os merchants para partilha da campanha.

---

## 🎯 Funcionalidades Implementadas

### ✅ 1. Sistema de Autorizações entre Merchants

**Tabela:** `campaign_merchant_authorizations`

Permite que um merchant emissor autorize explicitamente outros merchants a aceitar resgates de pontos de suas campanhas.

**Características:**
- ✅ Autorização explícita e obrigatória
- ✅ Revogação preventiva (bloqueio antes do resgate)
- ✅ Rastreabilidade completa (quem autorizou, quando, quem revogou)
- ✅ Validação de merchants diferentes (não pode autorizar a si mesmo)

### ✅ 2. Sistema de Liquidação (Settlements)

**Tabela:** `merchant_settlements`

Registra obrigações financeiras entre merchants quando um resgate ocorre em merchant diferente do emissor.

**Características:**
- ✅ Registro automático de obrigações financeiras
- ✅ Liquidação T+1 (configurável)
- ✅ Rastreabilidade completa (redemption_id, purchase_id, campaign_id)
- ✅ Status de processamento (pending, processed, cancelled, failed)
- ✅ Resumo de obrigações pendentes por merchant

### ✅ 3. Validação de Autorização no Resgate

**Serviço:** `pointsRedemptionService.js`

Modificado para verificar autorização antes de permitir resgate.

**Validações:**
- ✅ Verifica se pontos pertencem a uma campanha
- ✅ Verifica se merchant resgatador tem autorização ativa
- ✅ Bloqueia resgate se autorização foi revogada
- ✅ Cria settlement automaticamente quando necessário

---

## 🔄 Fluxo Funcional

### **1. Merchant 1 cria pontos para uma campanha X**

```http
POST /api/campaigns
{
    "campaign_name": "Campanha X",
    "establishment_id": 1,
    "accumulation_rate": 0.1,
    ...
}
```

**Resultado:** Campanha criada, pontos podem ser acumulados pelos clientes.

---

### **2. Cliente recebe e acumula pontos pertencentes à campanha X**

Pontos são registrados no `points_ledger` com:
- `origin_type = 'campaign'`
- `original_origin_id = campaign_id`

---

### **3. Merchant 1 autoriza Merchant 2 para aceitar resgates da campanha X**

```http
POST /api/campaigns/:campaignId/authorizations
{
    "redeemer_merchant_id": 2,
    "notes": "Autorização para aceitar resgates"
}
```

**Resultado:** Autorização criada e ativa.

---

### **4. Cliente tenta resgatar pontos acumulados em Merchant 2**

```http
POST /api/points/redeem
{
    "establishment_id": 2,
    "points_amount": 1000,
    "purchase_amount_mt": 100
}
```

**Processo:**
1. ✅ Sistema verifica origem dos pontos (campanha X)
2. ✅ Sistema verifica se Merchant 2 tem autorização ativa
3. ✅ Sistema verifica se autorização não foi revogada
4. ✅ Se autorizado, permite resgate
5. ✅ Se não autorizado, bloqueia resgate com erro

**Resultado:** Resgate permitido ou bloqueado.

---

### **5. Após o resgate, Merchant 2 entrega o produto/serviço ao cliente**

Cliente recebe produto/serviço do Merchant 2.

---

### **6. Sistema registra obrigação financeira**

**Automático:** Sistema cria registro em `merchant_settlements`:
- `issuer_merchant_id`: Merchant 1 (deve pagar)
- `redeemer_merchant_id`: Merchant 2 (deve receber)
- `amount_mt`: 100 MT (1000 pontos / 10)
- `settlement_date`: T+1 (amanhã)
- `status`: pending

---

### **7. Maktubia processa liquidação**

```http
POST /api/settlements/:id/process
{
    "payment_method": "bank_transfer",
    "transaction_reference": "TXN123456",
    "notes": "Liquidação processada"
}
```

**Resultado:** Settlement marcado como `processed`, Merchant 1 paga Merchant 2.

---

## 📊 Estrutura do Banco de Dados

### **Tabela: `campaign_merchant_authorizations`**

```sql
CREATE TABLE campaign_merchant_authorizations (
    authorization_id SERIAL PRIMARY KEY,
    campaign_id INTEGER NOT NULL,
    issuer_merchant_id INTEGER NOT NULL, -- Merchant que criou a campanha
    redeemer_merchant_id INTEGER NOT NULL, -- Merchant autorizado a aceitar resgates
    is_active BOOLEAN DEFAULT TRUE,
    authorized_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    revoked_at TIMESTAMP,
    revoked_by INTEGER REFERENCES users(user_id),
    notes TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(campaign_id, redeemer_merchant_id),
    CONSTRAINT chk_different_merchants CHECK (issuer_merchant_id != redeemer_merchant_id)
);
```

### **Tabela: `merchant_settlements`**

```sql
CREATE TABLE merchant_settlements (
    settlement_id SERIAL PRIMARY KEY,
    settlement_number VARCHAR(50) UNIQUE, -- SET-20241104-0001
    redemption_id VARCHAR(64),
    purchase_id VARCHAR(64),
    issuer_merchant_id INTEGER NOT NULL, -- Merchant que emitiu os pontos (deve pagar)
    redeemer_merchant_id INTEGER NOT NULL, -- Merchant que aceitou o resgate (deve receber)
    campaign_id INTEGER REFERENCES campaigns(campaign_id),
    points_redeemed INTEGER NOT NULL,
    amount_mt NUMERIC(14,2) NOT NULL, -- points_redeemed / 10
    status VARCHAR(20) DEFAULT 'pending', -- pending, processed, cancelled, failed
    settlement_date DATE, -- T+1 ou configurável
    processed_at TIMESTAMP,
    processed_by INTEGER REFERENCES users(user_id),
    payment_method VARCHAR(50),
    transaction_reference VARCHAR(100),
    notes TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    CONSTRAINT chk_settlement_different_merchants CHECK (issuer_merchant_id != redeemer_merchant_id)
);
```

---

## 🔐 Regras de Segurança e Validação

### **1. Autorização Obrigatória**

- ❌ Cliente **NÃO pode** resgatar pontos de campanha em merchant não autorizado
- ✅ Cliente **PODE** resgatar pontos de campanha em merchant autorizado
- ✅ Cliente **PODE** resgatar pontos não relacionados a campanha em qualquer merchant

### **2. Revogação Preventiva**

- ✅ Merchant emissor pode revogar autorização a qualquer momento
- ❌ Resgates pendentes são bloqueados se autorização for revogada
- ✅ Resgates já processados não são afetados

### **3. Taxa de Conversão Fixa**

- ✅ **1 MT = 10 Pontos** (fixo e imutável)
- ✅ Settlement usa esta taxa: `amount_mt = points_redeemed / 10`

### **4. Liquidação T+1**

- ✅ Settlement criado com `settlement_date = T+1` (amanhã)
- ✅ Configurável para outros períodos (T+0, T+2, etc.)

---

## 📡 Endpoints da API

### **Autorizações**

#### **Criar Autorização**
```http
POST /api/campaigns/:campaignId/authorizations
Authorization: Bearer <token>
{
    "redeemer_merchant_id": 2,
    "notes": "Autorização para aceitar resgates"
}
```

#### **Buscar Autorizações de uma Campanha**
```http
GET /api/campaigns/:campaignId/authorizations?is_active=true
Authorization: Bearer <token>
```

#### **Revogar Autorização**
```http
POST /api/campaigns/authorizations/:id/revoke
Authorization: Bearer <token>
```

#### **Buscar Autorizações de um Merchant (como resgatador)**
```http
GET /api/merchants/:merchantId/authorizations?is_active=true
Authorization: Bearer <token>
```

---

### **Settlements (Liquidações)**

#### **Buscar Settlements Pendentes (como emissor - deve pagar)**
```http
GET /api/merchants/:merchantId/settlements/pending/issuer?page=1&limit=20
Authorization: Bearer <token>
```

#### **Buscar Settlements Pendentes (como resgatador - deve receber)**
```http
GET /api/merchants/:merchantId/settlements/pending/redeemer?page=1&limit=20
Authorization: Bearer <token>
```

#### **Processar Settlement (apenas admin/Maktubia)**
```http
POST /api/settlements/:id/process
Authorization: Bearer <token>
{
    "payment_method": "bank_transfer",
    "transaction_reference": "TXN123456",
    "notes": "Liquidação processada"
}
```

#### **Obter Resumo de Obrigações Pendentes**
```http
GET /api/merchants/:merchantId/settlements/summary
Authorization: Bearer <token>
```

**Resposta:**
```json
{
    "success": true,
    "data": {
        "as_issuer": {
            "pending_count": 5,
            "total_amount_mt_pending": 500.00,
            "earliest_settlement_date": "2024-11-05"
        },
        "as_redeemer": {
            "pending_count": 3,
            "total_amount_mt_pending": 300.00,
            "earliest_settlement_date": "2024-11-05"
        }
    }
}
```

---

## 🚀 Como Usar

### **1. Executar Schema SQL**

```bash
psql -U postgres -d maktubia_points -f database/create-multi-merchant-interoperability.sql
```

### **2. Testar Autorização**

```bash
# Merchant 1 autoriza Merchant 2
curl -X POST http://localhost:3000/api/campaigns/1/authorizations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "redeemer_merchant_id": 2,
    "notes": "Autorização para aceitar resgates"
  }'
```

### **3. Testar Resgate com Autorização**

```bash
# Cliente resgata pontos em Merchant 2
curl -X POST http://localhost:3000/api/points/redeem \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "establishment_id": 2,
    "points_amount": 1000,
    "purchase_amount_mt": 100
  }'
```

### **4. Verificar Settlement Criado**

```bash
# Ver settlements pendentes
curl -X GET http://localhost:3000/api/merchants/1/settlements/pending/issuer \
  -H "Authorization: Bearer <token>"
```

---

## 📝 Notas Importantes

1. **Taxa de Conversão:** Sempre 1 MT = 10 Pontos (fixo e imutável)
2. **Autorização Explícita:** Obrigatória para resgates entre merchants diferentes
3. **Revogação Preventiva:** Merchant emissor pode revogar antes do resgate
4. **Liquidação T+1:** Padrão, mas configurável
5. **Rastreabilidade:** Todos os resgates e settlements são rastreados

---

## ✅ Status da Implementação

- ✅ Schema de banco de dados criado
- ✅ Models implementados
- ✅ Controllers implementados
- ✅ Rotas registradas
- ✅ Validação de autorização no resgate
- ✅ Criação automática de settlements
- ✅ Sistema de liquidação implementado

---

## 🔮 Próximos Passos (Opcional)

- [ ] Job agendado para processar settlements automaticamente (T+1)
- [ ] Notificações para merchants sobre settlements pendentes
- [ ] Dashboard de liquidações para Maktubia
- [ ] Relatórios de interoperabilidade multi-merchant
- [ ] Configuração de período de liquidação por merchant