# 🔄 Movimentação de Pontos no Ecossistema Maktubia

**Versão:** 2.0 (com taxa fixa 1 MT = 10 pts e novas relações)

---

## ✅ 1. Princípio Base

Toda a atribuição de pontos no ecossistema obedece à conversão fixa e inalterável:

**1 MT = 10 Pontos Maktubia**

Nenhum merchant pode alterar esta conversão, podendo apenas aplicar multiplicadores (ex.: 2x, 3x).

---

## ✅ 2. Formas de Adicionar / Receber Pontos (Crédito)

### ✔ 2.1. Acumulação por Compra (evento principal no sistema)

**Status:** ✅ Implementado

Cliente acumula pontos ao adquirir um produto/serviço num merchant aderente.

**Exemplo:** 250 MT → 2.500 pts

**Implementação:**
- `models/PurchasesModel.js` - Criação e confirmação de compras
- `controllers/purchaseController.js` - Endpoint de scan de QR code
- Usa `calculatePoints()` com taxa fixa de 10 pontos por MT

---

### ✔ 2.2. Atribuição Direta de Pontos (sem compra)

**Status:** ⚠️ Parcial - Precisa implementar

Tanto o Merchant como a Maktubia podem atribuir pontos manualmente ou através de ficheiro (upload CSV ou API).

**Usos típicos:**
- Compensação de clientes (ex.: pedido atrasado → 500 pts)
- Oferta promocional ("registo vale 100 pts")
- Bónus de boas-vindas ou aniversário
- Campanha de marketing interna
- Reposição de pontos após erro

**Todos os pontos atribuídos desta forma continuam a respeitar 1 MT = 10 pts (valor contabilístico).**

**A Maktubia, quando atribui pontos, actua como um merchant emissor (banco emissor de pontos).**

**Implementação Necessária:**
- `services/pointsDirectAssignmentService.js` - Serviço para atribuição direta
- `controllers/pointsAssignmentController.js` - Controller para atribuição
- `routes/pointsAssignmentRoutes.js` - Rotas para atribuição
- Endpoints:
  - `POST /api/points/assign` - Atribuir pontos diretamente
  - `POST /api/points/assign-bulk` - Atribuir pontos em massa (CSV/JSON)
  - `GET /api/points/assignments` - Listar atribuições

---

### ✔ 2.3. Compra de Pontos com Dinheiro

**Status:** ❌ Não implementado

O cliente ou merchant pode comprar pontos a Maktubia ou a outro actor da rede (caso ativado).

**Exemplo:** 100 MT = 1.000 pts

**A compra pode ocorrer entre:**
- Cliente ↔ Cliente
- Cliente ↔ Merchant
- Merchant ↔ Merchant
- Cliente ↔ Maktubia
- Merchant ↔ Maktubia

**Implementação Necessária:**
- `services/pointsPurchaseService.js` - Serviço para compra de pontos
- `controllers/pointsPurchaseController.js` - Controller para compra
- `routes/pointsPurchaseRoutes.js` - Rotas para compra
- Tabela `points_purchases` - Registrar compras de pontos
- Integração com meios de pagamento (M-Pesa, cartão, etc.)
- Endpoints:
  - `POST /api/points/purchase` - Comprar pontos
  - `GET /api/points/purchases` - Listar compras de pontos
  - `POST /api/points/purchase/verify` - Verificar pagamento

---

### ✔ 2.4. Transferência de Pontos (P2P ou B2B)

**Status:** ✅ Implementado (P2P entre Clientes)

Um utilizador pode enviar pontos a outro utilizador da plataforma, com limites e autenticação.

**Status Atual:**
- ✅ Transferência Cliente ↔ Cliente (P2P via Maktubia Friends)
- ❌ Transferência Merchant ↔ Cliente
- ❌ Transferência Merchant ↔ Merchant
- ❌ Transferência Cliente/Merchant ↔ Maktubia

**Implementação Necessária:**
- Expandir `controllers/transferController.js` para suportar todos os tipos
- Validação de permissões por tipo de usuário
- Limites diferentes por tipo de relação

---

### ✔ 2.5. Bónus Automático do Sistema

**Status:** ⚠️ Parcial

Maktubia pode emitir pontos centralmente por:
- Campanhas globais
- Gamificação
- Cashback digital
- Sistema de indicação

**Implementação Necessária:**
- `services/systemBonusService.js` - Serviço para bônus automáticos
- `controllers/systemBonusController.js` - Controller para bônus
- Integração com sistema de campanhas globais
- Sistema de gamificação
- Programa de indicação (referral)

---

### ✔ 2.6. Reembolso em Pontos

**Status:** ❌ Não implementado

Em caso de devolução, o cliente pode receber o valor convertido em pontos em vez de MT.

**Exemplo:** devolução de 200 MT → 2.000 pts

**Implementação Necessária:**
- `services/refundService.js` - Serviço para reembolsos
- `controllers/refundController.js` - Controller para reembolsos
- Endpoint:
  - `POST /api/purchases/:id/refund` - Reembolsar em pontos
  - Opção: reembolso em MT ou pontos

---

## ✅ 3. Formas de Subtrair / Usar Pontos (Débito)

### ✔ 3.1. Resgate de Pontos para Comprar Produtos/Serviços

**Status:** ❌ Não implementado

Cliente usa pontos como pagamento total ou parcial ao merchant.

**Implementação Necessária:**
- `services/pointsRedemptionService.js` - Serviço para resgate
- `controllers/pointsRedemptionController.js` - Controller para resgate
- Integração com criação de compras
- Endpoints:
  - `POST /api/purchases/redeem` - Criar compra usando pontos
  - `POST /api/purchases/:id/partial-redeem` - Usar pontos parcialmente
  - Validação de saldo suficiente

---

### ✔ 3.2. Transferência de Pontos (emissor perde saldo)

**Status:** ✅ Implementado (P2P Cliente)

Cliente ou merchant envia pontos para outra conta da rede.

**Status Atual:** Apenas Cliente → Cliente

---

### ✔ 3.3. Venda de Pontos (Conversão Pontos → Meticais)

**Status:** ❌ Não implementado

Cliente ou merchant pode vender pontos à Maktubia, a outro merchant ou a outro cliente.

**⚠ Taxa de recompra não é igual à taxa de emissão (existe desvalorização, definida pela Maktubia).**

**⚠ Venda de pontos só é permitida para contas verificadas (KYC).**

**Implementação Necessária:**
- `services/pointsSaleService.js` - Serviço para venda de pontos
- `controllers/pointsSaleController.js` - Controller para venda
- Tabela `points_sales` - Registrar vendas de pontos
- Taxa de desvalorização configurável
- Validação KYC obrigatória
- Endpoints:
  - `POST /api/points/sell` - Vender pontos
  - `GET /api/points/sales` - Listar vendas
  - `GET /api/points/sale-rate` - Obter taxa de venda atual

---

### ✔ 3.4. Expiração Automática de Pontos

**Status:** ❌ Não implementado

Pontos expiram por regra global ou por campanha específica.

**Implementação Necessária:**
- `services/pointsExpirationService.js` - Serviço para expiração
- Job agendado (cron) para verificar e expirar pontos
- Tabela `points_expiration_rules` - Regras de expiração
- Notificações antes da expiração
- Endpoints:
  - `GET /api/points/expiring` - Listar pontos próximos de expirar
  - `GET /api/points/expired` - Listar pontos expirados

---

### ✔ 3.5. Dedução Administrativa

**Status:** ⚠️ Parcial

Usado em casos de fraude, erro ou correcção de sistema.

**Implementação Necessária:**
- `services/pointsAdjustmentService.js` - Serviço para ajustes administrativos
- Permissões de admin obrigatórias
- Auditoria completa de todas as deduções
- Endpoints:
  - `POST /api/points/adjust` - Ajuste administrativo (admin only)
  - `GET /api/points/adjustments` - Listar ajustes

---

## ✅ 4. Relações Permitidas no Ecossistema Maktubia

As seguintes transacções de pontos são permitidas na plataforma:

### 1. Cliente ↔ Cliente
**Status:** ✅ Implementado (via Maktubia Friends)

- ✅ Cliente pode transferir pontos para outro cliente
- ❌ Cliente pode comprar ou vender pontos a outro cliente (se esta função estiver activada)

### 2. Merchant ↔ Cliente
**Status:** ⚠️ Parcial

- ✅ Merchant pode atribuir pontos ao cliente (por compra - implementado)
- ⚠️ Merchant pode atribuir pontos manualmente (precisa implementar)
- ❌ Cliente pode usar pontos para pagar produtos/serviços ao merchant (resgate)
- ❌ Merchant pode comprar pontos para usar em campanhas
- ❌ Cliente pode comprar pontos ao merchant

### 3. Merchant ↔ Merchant
**Status:** ❌ Não implementado

- ❌ Merchant pode transferir pontos a outro merchant
- ❌ Merchant pode comprar pontos de outro merchant

### 4. Maktubia ↔ Cliente
**Status:** ❌ Não implementado

- ❌ Maktubia pode vender pontos ao cliente
- ❌ Maktubia pode atribuir pontos ao cliente (bónus, campanhas globais)
- ❌ Maktubia pode recomprar pontos do cliente

### 5. Maktubia ↔ Merchant
**Status:** ❌ Não implementado

- ❌ Maktubia pode vender pontos ao merchant
- ❌ Maktubia pode comprar pontos ao merchant
- ❌ Maktubia pode atribuir pontos a merchants

---

## ✅ 5. Novas Regras de Controlo

### 1. Maktubia é único emissor-mestre
A Maktubia actua como Banco Central dos Pontos.

**Implementação Necessária:**
- Sistema de controle de emissão de pontos
- Limites de emissão por merchant
- Rastreabilidade completa de origem

### 2. Rastreabilidade de origem
Todos os pontos no sistema têm origem rastreável:
- ✅ Pontos Merchant (via compras)
- ✅ Pontos Transferidos (via ledger)
- ❌ Pontos Maktubia (precisa implementar marcação)
- ❌ Pontos Comprados (precisa implementar)

### 3. Merchants não podem criar pontos autonomamente
Merchants apenas "emitem" dentro do seu saldo de campanha autorizado.

**Implementação Necessária:**
- Sistema de saldo de campanha por merchant
- Limites de emissão por merchant
- Validação antes de atribuir pontos

### 4. Limites e taxas
A compra/venda/transferência de pontos pode ter:
- Limites diários
- Taxa de comissão
- Verificação de identidade (KYC)

**Implementação Necessária:**
- Sistema de limites configuráveis
- Sistema de taxas/comissões
- Integração com KYC

---

## ✅ 6. Impacto da Conversão Fixa 1 MT = 10 Pts

- ✅ Permite liquidez dos pontos entre comerciantes
- ✅ Torna resgate e contabilização transparente
- ✅ Evita inflação de pontos por merchant
- ✅ Permite cálculo económico real (passivo de pontos)
- ✅ Facilita integração com meios de pagamento
- ✅ Permite criação futura de "mercado de pontos" regulado

---

## 📋 Próximos Passos de Implementação

### Prioridade Alta:
1. **Atribuição Direta de Pontos** (2.2)
2. **Resgate de Pontos** (3.1)
3. **Compra de Pontos** (2.3)
4. **Expiração de Pontos** (3.4)

### Prioridade Média:
5. **Venda de Pontos** (3.3)
6. **Reembolso em Pontos** (2.6)
7. **Bônus Automático** (2.5)
8. **Relações adicionais** (4)

### Prioridade Baixa:
9. **Dedução Administrativa** (3.5)
10. **Sistema de limites e taxas** (5.4)

---

**Documento criado para guiar a implementação completa do ecossistema de movimentação de pontos.**