💎 Sistema de Shares/NAV

Visão Geral

O sistema de shares é o coração do Crypto Dashboard. Garante que cada participante do fundo tem uma propriedade justa e proporcional, independentemente de quando entrou ou saiu.

Por que Shares?

Problema sem shares:

Dia 1: João deposita €1000
Dia 30: Mercado sobe 50% → Fundo vale €1500
Dia 30: Maria deposita €1500

Como dividir o fundo agora?
- João: depositou €1000 (33%)
- Maria: depositou €1500 (50%)
❌ TOTAL = 83%? Não fecha!
❌ João não deve ter apenas 33% - ele estava desde o início!

Solução com shares:

Dia 1: João deposita €1000 → recebe 1000 shares (NAV/share = €1.00)
       Total fundo: €1000, Total shares: 1000
       
Dia 30: Mercado sobe 50% → Fundo vale €1500
        NAV/share = €1500 ÷ 1000 = €1.50
        
Dia 30: Maria deposita €1500 → recebe 1000 shares (€1500 ÷ €1.50)
        Total fundo: €3000, Total shares: 2000
        
Propriedade:
✅ João: 1000 shares = 50% do fundo = €1500
✅ Maria: 1000 shares = 50% do fundo = €1500
✅ TOTAL: 100% 🎯

Conceitos Fundamentais

NAV (Net Asset Value)

Definição: Valor líquido total do fundo

Fórmula:

NAV Total = Caixa Disponível + Valor das Holdings em Cripto

Componentes:

1. Caixa Disponível:

Caixa = Σ Depósitos 
      - Σ Levantamentos 
      - Σ (Compras + Fees de Compra)
      + Σ (Vendas - Fees de Venda)

2. Valor das Holdings:

Para cada ativo:
    Holdings[ativo] = Σ Quantidades Compradas - Σ Quantidades Vendidas
    Valor[ativo] = Holdings[ativo] × Preço Atual

Total Holdings = Σ Valor[todos os ativos]

NAV por Share

Definição: Preço de cada share do fundo

Fórmula:

NAV/share = NAV Total do Fundo ÷ Total de Shares em Circulação

Caso Especial - Primeiro Depósito:

if total_shares == 0:
    return 1.0  # Inicializa com NAV/share = €1.00

Evolução:

• 📈 Mercado sobe: NAV/share aumenta
• 📉 Mercado desce: NAV/share diminui
• 💰 Novo depósito: NAV/share mantém-se (shares proporcionais)
• 💸 Levantamento: NAV/share mantém-se (queima shares proporcionais)

Operações

1. Depósito (Allocate Shares)

Fluxo:

1. Utilizador deposita X euros
2. Sistema calcula NAV/share ANTES do depósito
3. Shares atribuídas = X ÷ NAV/share
4. Registo criado em t_user_shares
5. Total shares aumenta

2. Levantamento (Burn Shares)

Fluxo:

1. Utilizador levanta X euros
2. Sistema calcula NAV/share ANTES do levantamento
3. Shares a queimar = X ÷ NAV/share
4. Validação: utilizador tem shares suficientes?
5. Registo negativo criado em t_user_shares
6. Total shares diminui

3. Transações de Cripto

Importante: Compras e vendas de cripto NÃO afetam shares!

Porquê?

• Compra: Trocamos caixa por cripto → NAV mantém-se → shares mantêm-se
• Venda: Trocamos cripto por caixa → NAV mantém-se → shares mantêm-se
• Apenas variações de preço de mercado mudam o NAV/share

Ownership (Propriedade)

Cálculo de Ownership %

Fórmula:

Ownership % = (Shares do Utilizador ÷ Total Shares) × 100

Valor em EUR do Utilizador

Fórmula:

Valor do Utilizador = Shares do Utilizador × NAV/share

Histórico de Shares

Tabela t_user_shares

Características:

• ✅ Imutável: Registos nunca são alterados (audit trail)
• ✅ Completo: Cada movimento tem contexto completo (NAV, shares, etc)
• ✅ Auditável: Pode-se reconstruir histórico completo

Boas Práticas

✅ DO

• Sempre chamar allocate_shares_on_deposit() APÓS inserir em t_user_capital_movements
• Sempre chamar burn_shares_on_withdrawal() APÓS inserir debit
• Validar shares suficientes antes de levantamentos
• Usar transações de BD para garantir atomicidade
• Preservar todo o histórico em t_user_shares
• Testar cálculos com arredondamentos

❌ DON'T

• ❌ Nunca alterar registos em t_user_shares (imutável)
• ❌ Nunca permitir total_shares_after negativo
• ❌ Nunca calcular NAV incluindo admins
• ❌ Nunca usar float para valores monetários (usar Decimal)
• ❌ Nunca assumir que NAV/share é fixo