# 👥 Sistema de Gestão de Cotas e Cotistas

## 📋 Visão Geral

Este sistema permite gerenciar as cotas (participações) de múltiplos cotistas no fundo de investimento do robô de balanceamento. Cada cotista contribui com um valor em USD e recebe uma participação percentual automática nos lucros/prejuízos do fundo.

---

## 🎯 Funcionalidades Principais

### 1. **Cadastro de Cotistas**
- **Nome**: Nome completo do cotista
- **CPF**: Validação automática de CPF (verifica dígitos verificadores)
- **Email**: Email de contato
- **Valor USD**: Valor de participação no fundo (em USD)

### 2. **Cálculo Automático de Percentuais**
O sistema calcula automaticamente:
- **Participação %**: `(Valor do Cotista / Capital Disponível) × 100`
- **Valor Atual**: Baseado no capital disponível atual
- **Lucro/Prejuízo**: `Valor Atual - Valor Inicial`
- **% Lucro/Prejuízo**: `(Lucro / Valor Inicial) × 100`

### 3. **Tabela de Cotistas**
Exibe em tempo real:
- Nome do cotista
- CPF (mascarado)
- Percentual de participação
- Valor de participação inicial (USD)
- Valor atual (recalculado conforme o capital)
- Lucro ou prejuízo em USD
- Percentual de lucro/prejuízo (com cores: 🟢 lucro, 🔴 prejuízo)

### 4. **Resumo de Cotas**
- Total de cotistas cadastrados
- Capital total investido
- Capital disponível (atual do fundo)
- Ganho total do fundo

---

## 💡 Como Funciona

### Capital Base
O sistema utiliza o "Capital Disponível" do portfólio para calcular os percentuais:

```
Capital Base = Capital Inicial + (Ganhos × % Reinvestimento)
```

Por exemplo:
- Capital Inicial: **$2.000,00**
- Ganho até agora: **$500,00**
- % Reinvestimento: **77%**
- Capital Disponível = $2.000 + ($500 × 0.77) = **$2.385,00**

### Exemplo Prático

#### Cenário: 3 Cotistas

| Cotista | Valor Inicial | Capital Disp. | % Participação | Valor Atual | Lucro |
|---------|---------------|---------------|-----------------|------------|-------|
| João    | $1.000,00     | $2.385,00     | 41,93%          | $999.47    | -$0,53 |
| Maria   | $600,00       | $2.385,00     | 25,16%          | $599.68    | -$0,32 |
| Pedro   | $400,00       | $2.385,00     | 16,77%          | $399.79    | -$0,21 |
| **TOTAL** | **$2.000,00** | **$2.385,00** | **100,00%**     | **$1.999,00** | **-$1,06** |

Se o robô ganha **$500 USD**:
- João recebe: $500 × 41,93% = **$209,65**
- Maria recebe: $500 × 25,16% = **$125,80**
- Pedro recebe: $500 × 16,77% = **$83,85**

---

## 🚀 Como Usar

### Acessando a Aba de Cotas
1. Abra a interface web do robô: `http://localhost/projetos/balanceamento/log_balanceamento.php`
2. Clique na aba **"👥 Cotas & Cotistas"**

### Cadastrando um Novo Cotista
1. Preencha o formulário com os dados:
   - Nome completo
   - CPF (ex: 123.456.789-00)
   - Email (ex: joao@example.com)
   - Valor em USD (ex: 200.00)

2. Clique em **"✅ Adicionar Cotista"**

3. O sistema validará:
   - ✓ Nome com pelo menos 3 caracteres
   - ✓ CPF com dígitos verificadores válidos
   - ✓ Email em formato correto
   - ✓ Valor positivo e menor que 999.999 USD

### Visualizando Cotistas
A tabela exibe todos os cotistas com:
- Percentual calculado automaticamente
- Valor atualizado baseado no capital disponível
- Ganho/prejuízo em tempo real
- Indicadores coloridos (🟢 ganho, 🔴 prejuízo)

### Removendo um Cotista
1. Na tabela, clique no botão **"🗑️"** do cotista
2. Confirme a remoção
3. O cotista será removido do cadastro

---

## 📊 Cálculos Detalhados

### 1. Percentual de Participação
```
Percentual = (Valor do Cotista / Capital Disponível) × 100
```

**Exemplo:**
- Cotista investiu: $200
- Capital disponível: $2.000
- Percentual = ($200 / $2.000) × 100 = **10%**

### 2. Valor Atual
```
Valor Atual = Capital Disponível × (Percentual / 100)
```

**Exemplo:**
- Capital disponível após ganhos: $2.200
- Percentual do cotista: 10%
- Valor Atual = $2.200 × 0.10 = **$220**

### 3. Lucro ou Prejuízo
```
Lucro = Valor Atual - Valor Inicial
```

**Exemplo:**
- Valor inicial: $200
- Valor atual: $220
- Lucro = $220 - $200 = **+$20**

### 4. Percentual de Lucro/Prejuízo
```
% Lucro = (Lucro / Valor Inicial) × 100
```

**Exemplo:**
- Lucro: $20
- Valor inicial: $200
- % Lucro = ($20 / $200) × 100 = **+10%**

---

## 💾 Armazenamento de Dados

Os dados dos cotistas são armazenados no arquivo **`cotistas.json`** com a seguinte estrutura:

```json
{
  "cotistas": [
    {
      "id": "cot_xxxxx",
      "nome": "João Silva",
      "cpf": "123.456.789-00",
      "email": "joao@example.com",
      "valor_usd": 1000.00,
      "data_cadastro": "2026-06-18T15:30:45+00:00",
      "ativo": true
    }
  ],
  "capital_total": 1000.00,
  "data_atualizacao": "2026-06-18T15:30:45+00:00"
}
```

---

## 🔄 API de Gerenciamento

O arquivo `gerenciar_cotistas.php` fornece uma API para gerenciar cotistas:

### Listar Cotistas
```php
GET gerenciar_cotistas.php?acao=listar
```

**Resposta:**
```json
{
  "sucesso": true,
  "cotistas": [...],
  "capital_disponivel": 2385.00,
  "total_cotas": 2000.00
}
```

### Adicionar Cotista
```php
POST gerenciar_cotistas.php?acao=adicionar
Content-Type: application/json

{
  "nome": "João",
  "cpf": "123.456.789-00",
  "email": "joao@example.com",
  "valor_usd": 1000.00
}
```

### Editar Cotista
```php
POST gerenciar_cotistas.php?acao=editar
Content-Type: application/json

{
  "id": "cot_xxxxx",
  "nome": "João Silva",
  "email": "novo@example.com",
  "valor_usd": 1200.00
}
```

### Deletar Cotista
```php
POST gerenciar_cotistas.php?acao=deletar
Content-Type: application/json

{
  "id": "cot_xxxxx"
}
```

### Calcular Lucro de Cotista
```php
POST gerenciar_cotistas.php?acao=calcular_lucro
Content-Type: application/json

{
  "cotista_id": "cot_xxxxx"
}
```

---

## ✅ Validações

### CPF
- Verifica dígitos verificadores (módulo 11)
- Rejeita CPF com todos os dígitos iguais
- Formato: XXX.XXX.XXX-XX

### Email
- Valida formato de email RFC
- Rejeita emails inválidos

### Valor USD
- Deve ser maior que 0,01
- Deve ser menor que 999.999

### Nome
- Mínimo 3 caracteres
- Máximo 100 caracteres

---

## 🎨 Interface

### Cores na Tabela
- 🟢 **Verde**: Lucro positivo
- 🔴 **Vermelho**: Prejuízo (negativo)
- ⚪ **Cinza**: Zerado

### Resumo de Cotas
- Total de cotistas: número de pessoas cadastradas
- Capital Total: soma de todos os valores investidos
- Capital Disponível: valor atual do fundo
- Ganho Total: diferença entre capital disponível e total

---

## 📈 Exemplo de Fluxo Completo

### 1. Cadastro Inicial
```
João investe: $1.000
Maria investe: $800
Pedro investe: $200
Total: $2.000
```

### 2. Robô Ganha $400
```
Capital Disponível = $2.000 + $400 = $2.400
```

### 3. Percentuais Recalculados
```
João: $1.000 / $2.400 = 41,67% | Valor Atual: $1.000,80
Maria: $800 / $2.400 = 33,33% | Valor Atual: $800,00
Pedro: $200 / $2.400 = 8,33% | Valor Atual: $200,00
```

### 4. Lucro Distribuído
```
João ganha: $400 × 41,67% = $166,68 | Novo saldo: $1.166,68
Maria ganha: $400 × 33,33% = $133,32 | Novo saldo: $933,32
Pedro ganha: $400 × 8,33% = $33,32 | Novo saldo: $233,32
```

---

## 🔧 Troubleshooting

### "CPF inválido"
- Verifique se digitou corretamente
- Certifique-se de que o CPF não está cadastrado
- Dígitos verificadores devem estar corretos

### "Email inválido"
- Use um email em formato padrão: usuario@dominio.com
- Verifique se há espaços em branco

### "Valor deve ser entre 0.01 e 999999"
- Valor muito pequeno: mínimo é 0,01 USD
- Valor muito grande: máximo é 999.999 USD

### Tabela não atualiza
- Aguarde 30 segundos (intervalo de atualização automática)
- Ou clique em outra aba e volta para "Cotas & Cotistas"

---

## 💡 Dicas Importantes

1. **Backup**: O arquivo `cotistas.json` contém todos os dados. Faça backups regularmente!

2. **Sincronização**: Os dados são sincronizados automaticamente com o capital disponível

3. **Relatórios**: Use a tabela para gerar relatórios de ganhos por cotista

4. **Alertas**: Acompanhe em tempo real os lucros/prejuízos de cada cotista

5. **Distribuição**: A participação é proporcional ao investimento inicial

---

## 📞 Suporte

Para problemas ou dúvidas, verifique:
- O arquivo `gerenciar_cotistas.php` está no mesmo diretório
- O arquivo `cotistas.json` tem permissões de escrita
- O navegador permite JavaScript habilitado

---

**Última atualização:** 18/06/2026
**Versão:** 1.0