# 📋 Resumo Completo: Regras do Sistema e Roles com Funcionalidades

**Data:** 03/11/2025  
**Sistema:** Maktubia Points - Ecossistema de Fidelização

---

## 🔒 **REGRAS GLOBAIS DO SISTEMA**

### 1. **Regra de Conversão Monetária → Pontos**

#### **Regra Fundamental:**
```
1 Metical (MT) = 10 Pontos Maktubia (FIXO E IMUTÁVEL)
```

#### **Implicações:**
- ✅ **Taxa Fixa:** Nenhum merchant pode alterar a taxa de conversão
- ✅ **Padronização:** Todos os pontos seguem a mesma unidade de cálculo
- ✅ **Interoperabilidade:** Pontos podem ser usados entre todos os merchants
- ✅ **Campanhas:** Podem aplicar multiplicadores (ex.: 2x, 3x) mas NÃO podem alterar a taxa base
- ✅ **Controle:** Taxa controlada apenas pela Administração Maktubia

#### **Fórmula de Cálculo:**
```javascript
Pontos = (Valor em MT * 10) * Multiplicador de Bônus
```

#### **Exemplos:**
| Valor | Multiplicador | Pontos Calculados |
|-------|--------------|-------------------|
| 100 MT | 1.0 (padrão) | 1.000 pontos |
| 100 MT | 2.0 (dobro) | 2.000 pontos |
| 50 MT | 1.5 (50% bônus) | 750 pontos |
| 200 MT | 3.0 (triplo) | 6.000 pontos |

---

### 2. **Regras de Expiração de Pontos**

#### **Regra Padrão:**
```
Pontos NÃO expiram por padrão (cliente acumula indefinidamente)
```

#### **Expiração Opcional:**
- ⚠️ Expiração só ocorre se regra ativa for criada por admin
- ⚠️ Regras podem ser globais (todos os pontos) ou por campanha
- ⚠️ Admin pode criar/atualizar/deletar regras de expiração
- ⚠️ Sistema verifica e expira automaticamente via job diário (00:00)

---

### 3. **Regras de Transferência de Pontos**

#### **Relações Permitidas:**
| De | Para | Requer Amizade | Limite Diário |
|---|------|----------------|---------------|
| Cliente | Cliente | ✅ Sim | 10.000 pontos |
| Merchant | Cliente | ❌ Não | 50.000 pontos |
| Merchant | Merchant | ❌ Não | 100.000 pontos |
| Cliente | Merchant | ❌ Não | 10.000 pontos |
| Cliente | Maktubia | ❌ Não | 10.000 pontos |
| Merchant | Maktubia | ❌ Não | 100.000 pontos |
| Maktubia | Cliente | ❌ Não | Sem limite |
| Maktubia | Merchant | ❌ Não | Sem limite |

#### **Validações:**
- ✅ Validação de saldo suficiente antes de transferir
- ✅ Validação de amizade (apenas Cliente → Cliente)
- ✅ Validação de tipos de usuário permitidos
- ✅ Validação de limites diários por relação
- ✅ Prevenção de auto-transferência
- ✅ Sistema de idempotência (prevenção de duplicatas)

---

### 4. **Regras de Venda de Pontos**

#### **Requisitos:**
- ✅ **KYC Obrigatório:** Conta deve estar verificada (KYC)
- ✅ **Taxa de Desvalorização:** Configurável pela Maktubia (ex.: 0.9 = 90% do valor)
- ✅ **Validação:** Sistema verifica KYC antes de permitir venda

#### **Exemplo:**
```
Cliente vende 1.000 pontos
Taxa de desvalorização: 0.9 (90%)
Valor recebido: 90 MT (ao invés de 100 MT)
```

---

### 5. **Regras de Compra de Pontos**

#### **Funcionamento:**
- ✅ Cliente ou Merchant pode comprar pontos
- ✅ Taxa de conversão: 1 MT = 10 Pontos
- ✅ Integração com meios de pagamento (M-Pesa, cartão, etc.)
- ✅ Registro completo no ledger

---

### 6. **Regras de Resgate de Pontos**

#### **Funcionamento:**
- ✅ Cliente pode usar pontos para pagar compras
- ✅ Taxa de conversão: 10 Pontos = 1 MT
- ✅ Pagamento total ou parcial com pontos
- ✅ Validação de saldo suficiente

---

### 7. **Regras de Reembolso em Pontos**

#### **Funcionamento:**
- ✅ Apenas compras confirmadas podem ser reembolsadas
- ✅ Apenas Merchant ou Admin pode reembolsar
- ✅ Taxa de conversão: 1 MT = 10 Pontos
- ✅ Status da compra muda para 'refunded'

---

### 8. **Regras de Rastreabilidade**

#### **Sistema de Ledger:**
- ✅ Todos os pontos são rastreáveis
- ✅ Origem de cada ponto é registrada
- ✅ Cadeia de transferências é mantida
- ✅ Sistema FIFO (First In, First Out) para transferências

#### **Tipos de Origem:**
- `purchase` - Pontos de compra
- `direct_assignment` - Atribuição direta
- `transfer` - Transferência de outro usuário
- `purchase_points` - Compra de pontos
- `sale_points` - Venda de pontos
- `refund` - Reembolso de compra
- `redemption` - Resgate de pontos
- `system_bonus` - Bônus automático do sistema
- `campaign` - Pontos de campanha
- `expiration` - Pontos expirados (débito)

---

### 9. **Regras de Segurança Financeira**

#### **Validações:**
- ✅ Validação rigorosa de valores monetários
- ✅ Validação de saldo antes de operar
- ✅ Prevenção de saldos negativos
- ✅ Transações atômicas (ACID)
- ✅ Row-level locking (prevenção de race conditions)
- ✅ Sistema de idempotência (prevenção de duplicatas)
- ✅ Verificações de integridade pós-transação

#### **Isolamento de Transações:**
```sql
SET TRANSACTION ISOLATION LEVEL REPEATABLE READ;
```

#### **Row-Level Locking:**
```sql
SELECT points, balance FROM wallets 
WHERE user_id = $1 FOR UPDATE NOWAIT;
```

---

## 👥 **ROLES E FUNCIONALIDADES**

**IMPORTANTE:** O sistema possui apenas **3 roles**:
1. **Admin** - Administrador do sistema
2. **Merchant** - Merchant (identificado implicitamente quando tem estabelecimento)
3. **User** - Cliente padrão

---

### 1. **Role: `admin` (Administrador)**

#### **Descrição:**
Administrador do sistema com acesso total a todas as funcionalidades.

#### **Permissões:**
```json
{
  "*": ["*"]
}
```
**Acesso Total:** Pode fazer qualquer operação no sistema.

#### **Funcionalidades:**
- ✅ **Gerenciamento de Usuários:**
  - Criar, ler, atualizar, deletar usuários
  - Atribuir roles a usuários
  - Ativar/desativar usuários

- ✅ **Gerenciamento de Estabelecimentos:**
  - Criar, ler, atualizar, deletar estabelecimentos
  - Gerenciar QR codes
  - Aprovar/rejeitar estabelecimentos

- ✅ **Gerenciamento de Campanhas:**
  - Criar, ler, atualizar, deletar campanhas
  - Aprovar/rejeitar campanhas
  - Gerenciar multiplicadores de bônus

- ✅ **Gerenciamento de Compras:**
  - Ver todas as compras
  - Confirmar/rejeitar compras
  - Reembolsar compras em pontos

- ✅ **Gerenciamento de Pontos:**
  - Atribuir pontos diretamente (individual e em massa)
  - Comprar pontos
  - Vender pontos
  - Transferir pontos para qualquer usuário
  - Ajustar pontos administrativamente

- ✅ **Gerenciamento de Expiração:**
  - Criar/atualizar/deletar regras de expiração
  - Verificar e expirar pontos
  - Listar pontos expirando/expirados

- ✅ **Relatórios e Dashboard:**
  - Acessar todos os relatórios
  - Exportar dados
  - Ver métricas completas

- ✅ **Sistema:**
  - Gerenciar roles e permissões
  - Configurar taxas de conversão (via código)
  - Gerenciar configurações globais

---

### 2. **Role: `user` (Cliente)**

#### **Descrição:**
Cliente padrão do sistema. Usuário final que acumula e usa pontos.

#### **Permissões:**
```json
{
  "purchases": ["read", "create"],
  "transfers": ["read", "create"],
  "friends": ["read", "create", "accept", "reject"],
  "rewards": ["read", "redeem"],
  "profile": ["read", "update"]
}
```

#### **Funcionalidades:**
- ✅ **Compras:**
  - Criar compras (scan de QR code)
  - Ver suas compras
  - Acumular pontos automaticamente

- ✅ **Transferências:**
  - Transferir pontos para outros clientes (direto, sem necessidade de amizade)
  - Transferir pontos para merchants
  - Transferir pontos para Maktubia
  - Ver histórico de transferências

- ✅ **Maktubia Friends:**
  - Adicionar amigos
  - Aceitar/rejeitar solicitações de amizade
  - Ver lista de amigos
  - **NOTA:** Maktubia Friends não é mais obrigatório para transferências (transferências são diretas)

- ✅ **Pontos:**
  - Ver saldo de pontos
  - Comprar pontos
  - Vender pontos (requer KYC)
  - Resgatar pontos em compras
  - Ver histórico de pontos

- ✅ **Perfil:**
  - Ver seu perfil
  - Atualizar informações pessoais
  - Ver nível (bronze, silver, gold, etc.)

- ✅ **Recompensas:**
  - Ver recompensas disponíveis
  - Resgatar recompensas com pontos

---

### 3. **Role: `merchant` (Merchant - Implícito)**

#### **Descrição:**
Merchant é identificado pelo sistema quando um usuário tem um estabelecimento criado (`created_by`).

#### **Permissões:**
- Não tem role específica, mas tem permissões implícitas baseadas em ownership

#### **Funcionalidades:**
- ✅ **Gerenciamento de Estabelecimento Próprio:**
  - Gerenciar seu estabelecimento
  - Criar/atualizar/deletar seu estabelecimento
  - Gerenciar QR codes do seu estabelecimento

- ✅ **Gerenciamento de Campanhas:**
  - Criar campanhas para seu estabelecimento
  - Atualizar campanhas do seu estabelecimento
  - Gerenciar multiplicadores de bônus

- ✅ **Gerenciamento de Compras:**
  - Ver compras do seu estabelecimento
  - Confirmar/rejeitar compras do seu estabelecimento
  - Reembolsar compras em pontos

- ✅ **Gerenciamento de Pontos:**
  - Atribuir pontos diretamente a clientes
  - Transferir pontos para clientes
  - Transferir pontos para outros merchants
  - Transferir pontos para Maktubia
  - Comprar pontos
  - Vender pontos (requer KYC)

- ✅ **Relatórios:**
  - Ver relatórios do seu estabelecimento
  - Ver dashboard do seu estabelecimento

---

**NOTA:** O role `maktubia` é tratado como sinônimo de `admin` no sistema. Quando um usuário tem role `admin`, ele também tem permissões de emissor-mestre de pontos (Maktubia).

---

## 📊 **MATRIZ DE PERMISSÕES POR ROLE**

| Funcionalidade | Admin | User | Merchant |
|----------------|-------|------|----------|
| **Usuários** |
| Criar usuários | ✅ | ❌ | ❌ |
| Ver usuários | ✅ | ❌ | ❌ |
| Atualizar usuários | ✅ | ❌ | ❌ |
| Deletar usuários | ✅ | ❌ | ❌ |
| **Estabelecimentos** |
| Criar estabelecimentos | ✅ | ❌ | ✅ (próprio) |
| Ver estabelecimentos | ✅ | ❌ | ✅ (próprio) |
| Atualizar estabelecimentos | ✅ | ❌ | ✅ (próprio) |
| Deletar estabelecimentos | ✅ | ❌ | ✅ (próprio) |
| **Campanhas** |
| Criar campanhas | ✅ | ❌ | ✅ (próprio) |
| Ver campanhas | ✅ | ❌ | ✅ (próprio) |
| Atualizar campanhas | ✅ | ❌ | ✅ (próprio) |
| Deletar campanhas | ✅ | ❌ | ✅ (próprio) |
| **Compras** |
| Criar compras | ✅ | ✅ | ❌ |
| Ver compras | ✅ | ✅ (próprias) | ✅ (próprio) |
| Confirmar compras | ✅ | ❌ | ✅ (próprio) |
| Rejeitar compras | ✅ | ❌ | ✅ (próprio) |
| Reembolsar compras | ✅ | ❌ | ✅ (próprio) |
| **Pontos** |
| Atribuir pontos | ✅ | ❌ | ✅ |
| Transferir pontos | ✅ | ✅ | ✅ |
| Comprar pontos | ✅ | ✅ | ✅ |
| Vender pontos | ✅ | ✅ | ✅ |
| Resgatar pontos | ✅ | ✅ | ❌ |
| **Expiração** |
| Criar regras | ✅ | ❌ | ❌ |
| Verificar expiração | ✅ | ❌ | ❌ |
| **Relatórios** |
| Ver relatórios | ✅ | ❌ | ✅ (próprio) |
| Exportar relatórios | ✅ | ❌ | ❌ |
| **Dashboard** |
| Ver dashboard | ✅ | ❌ | ✅ (próprio) |

---

## 🔐 **REGRAS DE SEGURANÇA POR OPERAÇÃO**

### **Transferências:**
- ✅ Validação de saldo suficiente
- ✅ Validação de tipos permitidos
- ✅ Validação de limites diários
- ✅ Prevenção de auto-transferência
- ✅ Sistema de idempotência
- ✅ **NOTA:** Transferências são diretas (sem necessidade de Maktubia Friends)

### **Compras:**
- ✅ Validação de estabelecimento
- ✅ Validação de QR code
- ✅ Cálculo automático de pontos (taxa fixa)
- ✅ Transações atômicas
- ✅ Row-level locking

### **Venda de Pontos:**
- ✅ Validação de KYC obrigatória
- ✅ Taxa de desvalorização configurável
- ✅ Validação de saldo suficiente

### **Reembolsos:**
- ✅ Apenas compras confirmadas
- ✅ Apenas Merchant ou Admin
- ✅ Validação de ownership

### **Atribuição de Pontos:**
- ✅ Apenas Merchant ou Admin
- ✅ Validação de permissões
- ✅ Taxa fixa respeitada

---

## 📝 **NOTAS IMPORTANTES**

1. **Taxa de Conversão:** Sempre 1 MT = 10 Pontos (imutável)
2. **Expiração:** Pontos não expiram por padrão
3. **Rastreabilidade:** Todos os pontos são rastreáveis via ledger
4. **Segurança:** Todas as operações financeiras usam transações atômicas
5. **Limites:** Limites diários aplicados por tipo de relação
6. **KYC:** Obrigatório para venda de pontos
7. **Transferências:** Diretas (sem necessidade de Maktubia Friends)

---

**Última Atualização:** 03/11/2025  
**Status:** ✅ Sistema Completo e Funcional

---

## ⚠️ **NOTA IMPORTANTE SOBRE ROLES**

O sistema possui apenas **3 roles**:
1. **Admin** - Administrador do sistema (role explícito no banco de dados)
2. **User** - Cliente padrão (role explícito no banco de dados)
3. **Merchant** - Merchant (identificado implicitamente quando um usuário tem um estabelecimento criado - `created_by`)

**Roles removidas do sistema:**
- ❌ `manager` - Não existe mais
- ❌ `supervisor` - Não existe mais
- ❌ `employee` - Não existe mais
- ❌ `cashier` - Não existe mais
- ❌ `vetter` - Não existe mais
- ❌ `agent` - Não existe mais
- ❌ `reader` - Não existe mais

**Merchant é identificado implicitamente:**
- Um usuário é considerado Merchant quando ele tem um estabelecimento criado (`created_by = user_id`)
- Não precisa de role específica no banco de dados
- O sistema verifica automaticamente se um usuário é Merchant consultando a tabela `establishments`