# 🚀 Plano de Implementação: Ecossistema Completo de Movimentação de Pontos

## 📋 Resumo Executivo

Este documento detalha o plano de implementação para o ecossistema completo de movimentação de pontos conforme especificado em `ECOSSISTEMA_MOVIMENTACAO_PONTOS.md`.

---

## ✅ Status Atual

### **Implementado:**
- ✅ Taxa fixa: 1 MT = 10 Pontos
- ✅ Acumulação por compra (2.1)
- ✅ Transferência P2P Cliente ↔ Cliente (2.4)
- ✅ Sistema de rastreabilidade (ledger)
- ✅ Sistema de Maktubia Friends

### **Parcialmente Implementado:**
- ⚠️ Atribuição direta (precisa endpoints e validações)
- ⚠️ Bônus automático (precisa sistema centralizado)
- ⚠️ Dedução administrativa (precisa permissões)

### **Não Implementado:**
- ❌ Compra de pontos (2.3)
- ❌ Venda de pontos (3.3)
- ❌ Resgate de pontos (3.1)
- ❌ Reembolso em pontos (2.6)
- ❌ Expiração automática (3.4)
- ❌ Relações Merchant ↔ Merchant
- ❌ Relações Maktubia ↔ Cliente/Merchant

---

## 🎯 Fase 1: Atribuição Direta de Pontos (Prioridade Alta)

### **Objetivo:**
Permitir que Merchants e Maktubia atribuam pontos diretamente sem compra.

### **Implementação:**

1. **Serviço:** `services/pointsDirectAssignmentService.js`
   - Função `assignPoints()` - Atribuir pontos diretamente
   - Função `assignBulk()` - Atribuir em massa (CSV/JSON)
   - Validação de permissões
   - Registro no ledger

2. **Controller:** `controllers/pointsAssignmentController.js`
   - `assignPoints()` - Endpoint para atribuição
   - `assignBulk()` - Endpoint para atribuição em massa
   - `listAssignments()` - Listar atribuições

3. **Rotas:** `routes/pointsAssignmentRoutes.js`
   - `POST /api/points/assign`
   - `POST /api/points/assign-bulk`
   - `GET /api/points/assignments`

4. **Validações:**
   - Apenas Merchants e Admins podem atribuir
   - Respeitar taxa fixa: 1 MT = 10 pts
   - Registrar no ledger com `origin_type = 'direct_assignment'`

---

## 🎯 Fase 2: Resgate de Pontos (Prioridade Alta)

### **Objetivo:**
Permitir que clientes usem pontos para pagar compras (total ou parcial).

### **Implementação:**

1. **Serviço:** `services/pointsRedemptionService.js`
   - Função `redeemPoints()` - Resgatar pontos para compra
   - Validação de saldo suficiente
   - Cálculo de valor em MT (pontos / 10)
   - Registro no ledger

2. **Controller:** `controllers/pointsRedemptionController.js`
   - `redeemForPurchase()` - Criar compra usando pontos
   - `partialRedeem()` - Usar pontos parcialmente
   - `listRedemptions()` - Listar resgates

3. **Rotas:** `routes/pointsRedemptionRoutes.js`
   - `POST /api/purchases/redeem`
   - `POST /api/purchases/:id/partial-redeem`
   - `GET /api/points/redemptions`

4. **Integração:**
   - Modificar `Purchase.create()` para aceitar pontos
   - Criar compra com `payment_method = 'points'`
   - Registrar débito no ledger

---

## 🎯 Fase 3: Compra de Pontos (Prioridade Alta)

### **Objetivo:**
Permitir compra de pontos com dinheiro entre diferentes atores.

### **Implementação:**

1. **Tabela:** `points_purchases`
   ```sql
   CREATE TABLE points_purchases (
       purchase_id VARCHAR(64) PRIMARY KEY,
       buyer_id VARCHAR(64) NOT NULL,
       buyer_type VARCHAR(20) NOT NULL, -- 'customer', 'merchant', 'maktubia'
       seller_id VARCHAR(64),
       seller_type VARCHAR(20), -- 'customer', 'merchant', 'maktubia'
       amount_mt NUMERIC(14,2) NOT NULL,
       points_amount BIGINT NOT NULL,
       payment_method VARCHAR(50),
       status VARCHAR(20) DEFAULT 'pending',
       created_at TIMESTAMP DEFAULT NOW()
   );
   ```

2. **Serviço:** `services/pointsPurchaseService.js`
   - Função `purchasePoints()` - Comprar pontos
   - Validação de limites
   - Integração com pagamento (M-Pesa, cartão)
   - Registro no ledger

3. **Controller:** `controllers/pointsPurchaseController.js`
   - `purchasePoints()` - Endpoint para compra
   - `listPurchases()` - Listar compras
   - `verifyPayment()` - Verificar pagamento

4. **Rotas:** `routes/pointsPurchaseRoutes.js`
   - `POST /api/points/purchase`
   - `GET /api/points/purchases`
   - `POST /api/points/purchase/verify`

---

## 🎯 Fase 4: Venda de Pontos (Prioridade Média)

### **Objetivo:**
Permitir venda de pontos (conversão para MT) com taxa de desvalorização.

### **Implementação:**

1. **Tabela:** `points_sales`
   ```sql
   CREATE TABLE points_sales (
       sale_id VARCHAR(64) PRIMARY KEY,
       seller_id VARCHAR(64) NOT NULL,
       seller_type VARCHAR(20) NOT NULL,
       buyer_id VARCHAR(64),
       buyer_type VARCHAR(20),
       points_amount BIGINT NOT NULL,
       amount_mt NUMERIC(14,2) NOT NULL,
       sale_rate NUMERIC(10,4) NOT NULL, -- Taxa de venda (pode ser < 10)
       kyc_verified BOOLEAN DEFAULT FALSE,
       status VARCHAR(20) DEFAULT 'pending',
       created_at TIMESTAMP DEFAULT NOW()
   );
   ```

2. **Serviço:** `services/pointsSaleService.js`
   - Função `sellPoints()` - Vender pontos
   - Validação KYC obrigatória
   - Cálculo com taxa de desvalorização
   - Registro no ledger

3. **Controller:** `controllers/pointsSaleController.js`
   - `sellPoints()` - Endpoint para venda
   - `listSales()` - Listar vendas
   - `getSaleRate()` - Obter taxa atual

4. **Configuração:**
   - Taxa de venda configurável (ex.: 1 MT = 8 pontos na venda)
   - Validação KYC obrigatória

---

## 🎯 Fase 5: Expiração Automática (Prioridade Média)

### **Objetivo:**
Implementar sistema de expiração de pontos (global ou por campanha).

### **Implementação:**

1. **Tabela:** `points_expiration_rules`
   ```sql
   CREATE TABLE points_expiration_rules (
       rule_id SERIAL PRIMARY KEY,
       rule_type VARCHAR(20) NOT NULL, -- 'global', 'campaign'
       campaign_id VARCHAR(64),
       expiration_days INTEGER NOT NULL,
       active BOOLEAN DEFAULT TRUE,
       created_at TIMESTAMP DEFAULT NOW()
   );
   ```

2. **Tabela:** `points_expiration_log`
   ```sql
   CREATE TABLE points_expiration_log (
       log_id SERIAL PRIMARY KEY,
       user_id VARCHAR(64) NOT NULL,
       points_amount BIGINT NOT NULL,
       expiration_date DATE NOT NULL,
       expired_at TIMESTAMP,
       created_at TIMESTAMP DEFAULT NOW()
   );
   ```

3. **Serviço:** `services/pointsExpirationService.js`
   - Função `checkAndExpire()` - Verificar e expirar pontos
   - Job agendado (cron)
   - Notificações antes da expiração

4. **Job:** `jobs/pointsExpirationJob.js`
   - Executar diariamente
   - Verificar pontos próximos de expirar
   - Enviar notificações
   - Expirar pontos vencidos

---

## 🎯 Fase 6: Reembolso em Pontos (Prioridade Média)

### **Objetivo:**
Permitir reembolso de compras em pontos em vez de MT.

### **Implementação:**

1. **Modificar:** `models/PurchasesModel.js`
   - Adicionar método `refundInPoints()`
   - Calcular pontos (valor / 10)
   - Registrar no ledger

2. **Controller:** `controllers/purchaseController.js`
   - Adicionar endpoint `refundInPoints()`

3. **Rota:**
   - `POST /api/purchases/:id/refund-points`

---

## 🎯 Fase 7: Relações Adicionais (Prioridade Baixa)

### **Objetivo:**
Expandir transferências para todos os tipos de relação.

### **Implementação:**

1. **Modificar:** `controllers/transferController.js`
   - Suportar todos os tipos de usuário
   - Validação de permissões por tipo
   - Limites diferentes por relação

2. **Tipos de relação:**
   - Cliente ↔ Cliente ✅ (já implementado)
   - Merchant ↔ Cliente
   - Merchant ↔ Merchant
   - Cliente/Merchant ↔ Maktubia

---

## 📊 Ordem de Implementação Recomendada

1. **Fase 1:** Atribuição Direta (mais simples, alta demanda)
2. **Fase 2:** Resgate de Pontos (crítico para uso real)
3. **Fase 3:** Compra de Pontos (complementa resgate)
4. **Fase 4:** Venda de Pontos (liquidez)
5. **Fase 5:** Expiração (controle de passivo)
6. **Fase 6:** Reembolso (complemento)
7. **Fase 7:** Relações adicionais (expansão)

---

## 🔒 Regras de Segurança

1. **Taxa Fixa:** Sempre respeitar 1 MT = 10 Pontos
2. **Rastreabilidade:** Todos os pontos registrados no ledger
3. **Permissões:** Validar permissões por tipo de operação
4. **KYC:** Obrigatório para venda de pontos
5. **Limites:** Configuráveis por tipo de usuário/operação
6. **Auditoria:** Log completo de todas as operações

---

**Documento criado para guiar implementação faseada do ecossistema completo.**