Portfolio Buddy 2 - Contexto do Projeto
Pilha Tecnológica
- Frontend: React 19, TypeScript, Vite
- UI: Tailwind CSS, shadcn/ui (apenas sistema de cores)
- Gráficos: Chart.js, react-chartjs-2, plugins chartjs (zoom, annotation, date adapter)
- Estado: React puro (useState, useMemo, useCallback)
- Utilitários de Dados: date-fns para manipulação de datas
- Backend: Supabase (PostgreSQL)
- Deploy: Cloudflare Pages
Propósito do Projeto
Ferramenta de análise de portfólio para investidores e traders de futuros para:
- Comparar estratégias de trading vs ativos benchmark (SPY, GLD)
- Calcular matrizes de correlação entre ativos (Spearman & Pearson)
- Analisar métricas de risco e performance (Sharpe, Sortino, Max DD, etc.)
- Enviar dados de trades via CSV e visualizar resultados
- Aplicar multiplicadores de contrato para ajustar métricas para trading de futuros
- Filtrar dados por intervalo de datas para análise específica de períodos
Problemas Conhecidos e Dívida Técnica
Dívida Técnica Atual
-
Dependência Não Utilizada: Recharts (11.5KB) instalada mas nunca importada
- Deve ser removida do package.json
- Atualmente usando Chart.js
-
Componentes Acima do Limite: Violam padrão de 200 linhas
- PortfolioSection.tsx (591 linhas) → precisa ser refatorado em subcomponentes
- App.tsx (351 linhas) → extrair seções em componentes
- MetricsTable.tsx (242 linhas) → melhorado mas ainda acima do limite
-
Violações de TypeScript: 15 ocorrências de tipo
any- usePortfolio.ts: 11 ocorrências em tipos de trades/métricas
- useMetrics.ts: 4 ocorrências em comparações de ordenação
- dataUtils.ts: 1 ocorrência na interface Metrics
Bugs Conhecidos
- Erros de Upload no Supabase: Erros 500 intermitentes em uploads grandes
- Tratamento de erros aprimorado adicionado no commit 9fb7fdb
- Verificar tratamento de erros nos hooks de upload
- Verificar se os limites de linhas não foram excedidos no plano gratuito
Funcionalidades Recentes Adicionadas
- Cálculo de Sortino Ratio (commits 258ba3a, 9f25040)
- Localização: Implementado inline no PortfolioSection.tsx (linhas 133-158)
- Estado de taxa livre de risco para taxa especificada pelo usuário
- Desvio negativo anualizado usando fator sqrt(365)
- Cálculo de variância corrigido (divide pelo total de retornos, não apenas negativos)
- Exibido na seção de estatísticas do portfólio (linha 535)
- Nota: NÃO está em dataUtils.ts - mantido no componente devido ao contexto do portfólio
- Filtragem por Intervalo de Datas (commit 258ba3a)
- Filtrar dados do portfólio por data início/fim
- Implementado no hook usePortfolio
- Ordenação Avançada Multi-Coluna (hook useSorting)
- Ordenar por múltiplas colunas com prioridade
- Lógica de comparação personalizada por coluna
Restrições Arquiteturais
- Limite de Componentes: Máximo de 200 linhas por componente (atualmente violado por 3 componentes)
- Padrão de Hooks: Hooks personalizados em
/src/hooks/ - Padrão de Utilitários: Funções puras em
/src/utils/ - Segurança de Tipos: TypeScript estrito, sem tipos
any(15 violações existem como dívida técnica) - Gerenciamento de Estado: Apenas hooks React puros - sem Zustand ou TanStack Query
Estrutura de Componentes Chave
src/
├── components/
│ ├── AnalyticsControls.tsx (alternar visualizações Métricas/Portfólio/Correlação)
│ ├── ContractInput.tsx (inputs de multiplicadores de contrato)
│ ├── CorrelationHeatmap.tsx (visualização de correlação)
│ ├── CorrelationSection.tsx (wrapper de análise de correlação)
│ ├── CustomTooltip.tsx (tooltips de gráficos)
│ ├── ErrorList.tsx (exibição de erros)
│ ├── Header.tsx (cabeçalho do app)
│ ├── MasterContractControl.tsx (aplicar valor de contrato a todos)
│ ├── MetricsTable.tsx (exibição e seleção de métricas)
│ ├── PortfolioSection.tsx (gráficos e análise do portfólio - 591 linhas!)
│ ├── SessionComplete.tsx (UI de conclusão)
│ ├── SortableHeader.tsx (cabeçalho de tabela com indicadores de ordenação)
│ ├── UploadedFilesList.tsx (lista de arquivos enviados)
│ └── UploadSection.tsx (envio de arquivos para o Supabase)
├── hooks/
│ ├── useContractMultipliers.ts (gerenciar multiplicadores de contrato)
│ ├── useMetrics.ts (calcular métricas de trading)
│ ├── usePortfolio.ts (dados do portfólio e filtragem por data)
│ └── useSorting.ts (ordenação avançada multi-coluna)
└── utils/
└── dataUtils.ts (cálculos de métricas, parsing CSV, correlações)
Convenções Chave
- Alias de caminho:
@/mapeia parasrc/— use-o para todos os imports internos - shadcn-ui: Apenas tokens de cores — variáveis CSS em
src/index.css, nenhum componente shadcn instalado. Podem ser adicionados posteriormente vianpx shadcn@latest add button, etc. - Fluxo de trabalho Git: Branches de funcionalidade →
git checkout -b feature/nome→ commit convencional (feat:,fix:,chore:) → PR para main - Marca da comunidade: 5minfutures.com comunidade de trading; logotipo Skool em assets; formulário GoHighLevel embutido
Contexto de Migração
Migrando 40 funcionalidades do app antigo (90% completo). Veja o skill migration-tracker para detalhes.