Carlos Eduardo Gatti Ferreira

Wealth Tracker — Roadmap Financeiro

Versão: 1.0
Data: Janeiro 2026
Status: Planejamento — Nenhuma implementação ainda

📋 Índice

Fase 1: Modelo de Price Snapshot
Fase 2: Estratégia de Integração de Preços
Fase 3: Roadmap de Métricas
Fase 4: Cashflow + Portfolio = Net Worth
Considerações de Implementação

Fase 1: Modelo de Price Snapshot

Objetivo

Desenhar um modelo de dados para preços históricos que permita:

Múltiplos snapshots de preço por ativo
Histórico completo para análise
Auditoria e rastreabilidade
Cálculo preciso de market value

Proposta de Model Prisma (Design Only)

model AssetPrice {
  id          Int      @id @default(autoincrement())
  assetId     Int
  asset       Asset    @relation(fields: [assetId], references: [id], onDelete: Cascade)
  
  price       Decimal  @db.Decimal(20, 8)  // Suporta cripto e ações
  currency    String   @default("USD")
  
  source      PriceSource  @default(MANUAL)
  recordedAt  DateTime     @default(now())
  
  // Metadata opcional
  exchange    String?      // Ex: "NYSE", "NASDAQ", "BINANCE"
  volume      Decimal?     @db.Decimal(20, 8)
  marketCap   Decimal?     @db.Decimal(20, 2)
  
  createdAt   DateTime     @default(now())
  updatedAt   DateTime     @updatedAt
  
  @@index([assetId, recordedAt])
  @@index([recordedAt])
  @@map("asset_prices")
}

enum PriceSource {
  MANUAL      // Preço inserido manualmente pelo usuário
  YAHOO       // Yahoo Finance API
  POLYGON     // Polygon.io API
  ALPHA_VANTAGE // Alpha Vantage API
  CRYPTO_COMPARE // CryptoCompare API
}

Justificativa de Campos

`assetId`

Tipo: Foreign Key para Asset
Justificativa: Cada snapshot pertence a um ativo específico
Cascade: Se asset for deletado, preços históricos são preservados (ou deletados, dependendo da política)

`price`

Tipo: Decimal(20, 8)
Justificativa:
- Suporta valores muito grandes (market cap de grandes empresas)
- Precisão de 8 casas decimais para criptomoedas
- Evita problemas de ponto flutuante

`currency`

Tipo: String (ISO 4217)
Justificativa: Ativos podem ser negociados em diferentes moedas
Exemplo: AAPL em USD, TSLA em USD, BTC em USD, ações brasileiras em BRL

`source`

Tipo: Enum PriceSource
Justificativa:
- Permite rastrear origem do preço
- Importante para auditoria e confiabilidade
- Permite fallback entre fontes

`recordedAt`

Tipo: DateTime
Justificativa:
- Timestamp do momento em que o preço foi registrado
- Diferente de createdAt (quando foi inserido no banco)
- Permite histórico preciso para cálculos de performance

`exchange`, `volume`, `marketCap`

Tipo: Opcionais
Justificativa:
- Metadata adicional útil para análises futuras
- Não crítico para MVP, mas permite evolução

Índices Propostos

@@index([assetId, recordedAt])  // Busca rápida de histórico por ativo
@@index([recordedAt])            // Busca rápida de preços por data

Justificativa:

Consultas mais comuns serão:
- “Preço mais recente de um ativo” → WHERE assetId = X ORDER BY recordedAt DESC LIMIT 1
- “Preços de todos os ativos em uma data” → WHERE recordedAt = DATE
- “Histórico de preços de um ativo” → WHERE assetId = X ORDER BY recordedAt

Conexão com PortfolioSummary (Futuro)

Estado Atual:

// Backend atual calcula marketValue baseado em lastPrice
marketValue = quantity * lastPrice

Estado Futuro:

// Backend buscará preço mais recente de AssetPrice
const latestPrice = await getLatestPrice(assetId);
marketValue = quantity * latestPrice.price;

Migração Incremental:

Criar tabela AssetPrice (nova, não quebra nada)
Manter lastPrice em Asset (backward compatibility)
Gradualmente migrar: se existe AssetPrice, usar; senão, usar lastPrice
Deprecar lastPrice apenas quando 100% dos ativos tiverem preços reais

Fase 2: Estratégia de Integração de Preços

Comparação de APIs

Yahoo Finance (yfinance)

Prós:

✅ Gratuita (sem API key)
✅ Boa cobertura (ações, ETFs, índices)
✅ Fácil de usar
✅ Suporta histórico

Contras:

❌ Sem garantia de uptime
❌ Pode mudar formato sem aviso
❌ Rate limits não documentados
❌ Não oficial (scraping)

Uso Recomendado: MVP / Prototipagem

Polygon.io

Prós:

✅ API oficial e estável
✅ Boa documentação
✅ Suporte a ações, opções, forex, crypto
✅ Dados históricos completos
✅ WebSocket para real-time

Contras:

❌ Pago (free tier limitado)
❌ Requer API key
❌ Rate limits claros mas restritivos

Uso Recomendado: Produção (quando houver budget)

Alpha Vantage

Prós:

✅ API oficial
✅ Free tier generoso (5 calls/min, 500 calls/day)
✅ Boa cobertura de ações e forex
✅ Dados históricos

Contras:

❌ Rate limits baixos
❌ Não ideal para muitos ativos
❌ Crypto limitado

Uso Recomendado: Produção pequena escala

CryptoCompare / CoinGecko

Prós:

✅ Especializado em crypto
✅ Free tier disponível
✅ Boa cobertura de altcoins

Contras:

❌ Apenas crypto
❌ Não cobre ações

Uso Recomendado: Complementar para crypto

Estratégia Recomendada (Híbrida)

┌─────────────────────────────────────────┐
│         Price Fetch Strategy            │
└─────────────────────────────────────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
   ┌────▼────┐            ┌────▼────┐
   │  Stocks │            │  Crypto │
   │  ETFs   │            │  Tokens │
   └────┬────┘            └────┬────┘
        │                       │
   ┌────▼────┐            ┌────▼────┐
   │ Polygon │            │CoinGecko │
   │ (paid)  │            │  (free) │
   └────┬────┘            └────┬────┘
        │                       │
        └───────────┬───────────┘
                    │
            ┌───────▼───────┐
            │  Fallback:    │
            │  Yahoo Finance│
            └───────────────┘

Fluxo de Fetch de Preços

Opção 1: Cron Job (Recomendado)

┌─────────────────────────────────────────────┐
│  Cron Job (a cada hora / 4 horas)          │
└─────────────────────────────────────────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
   ┌────▼────┐            ┌────▼────┐
   │ Fetch   │            │ Fetch   │
   │ Stocks  │            │ Crypto  │
   └────┬────┘            └────┬────┘
        │                       │
        └───────────┬───────────┘
                    │
        ┌───────────▼───────────┐
        │  Save to AssetPrice   │
        │  (batch insert)       │
        └───────────────────────┘

Vantagens:

Preços sempre atualizados
Não depende de requests do usuário
Pode fazer batch de múltiplos ativos

Desvantagens:

Requer infraestrutura de cron
Consome recursos mesmo sem uso

Opção 2: On-Demand (Manual Refresh)

┌─────────────────────────────────────────────┐
│  User clicks "Refresh Prices"              │
└─────────────────────────────────────────────┘
                    │
        ┌───────────▼───────────┐
        │  Get user's assets    │
        │  (from portfolios)    │
        └───────────┬───────────┘
                    │
        ┌───────────▼───────────┐
        │  Fetch prices         │
        │  (rate limited)       │
        └───────────┬───────────┘
                    │
        ┌───────────▼───────────┐
        │  Save to AssetPrice   │
        └───────────────────────┘

Vantagens:

Mais controle do usuário
Não consome recursos desnecessários
Melhor para MVP

Desvantagens:

Preços podem estar desatualizados
Usuário precisa lembrar de atualizar

Opção 3: Híbrida (Recomendada para Produção)

┌─────────────────────────────────────────────┐
│  Cron: Atualiza preços principais          │
│  (S&P 500, principais cryptos)             │
└─────────────────────────────────────────────┘
                    │
        ┌───────────▼───────────┐
        │  On-Demand: Ativos    │
        │  específicos do user   │
        └───────────────────────┘

Rate Limits e Fallback

Estratégia de Fallback

// Pseudocódigo (não implementar ainda)

async function fetchPrice(asset: Asset): Promise<Price> {
  // 1. Tentar fonte primária
  try {
    return await polygonApi.getPrice(asset.ticker);
  } catch (error) {
    // 2. Fallback para fonte secundária
    try {
      return await yahooFinance.getPrice(asset.ticker);
    } catch (error) {
      // 3. Se tudo falhar, usar último preço conhecido
      return await getLastKnownPrice(asset.id);
    }
  }
}

Rate Limit Handling

// Pseudocódigo (não implementar ainda)

class PriceFetcher {
  private rateLimiter: Map<string, number[]> = new Map();
  
  async fetchWithRateLimit(source: string, ticker: string) {
    const now = Date.now();
    const calls = this.rateLimiter.get(source) || [];
    
    // Remover calls antigas (última hora)
    const recentCalls = calls.filter(time => now - time < 3600000);
    
    if (recentCalls.length >= MAX_CALLS_PER_HOUR) {
      throw new RateLimitError('Rate limit exceeded');
    }
    
    // Registrar call
    recentCalls.push(now);
    this.rateLimiter.set(source, recentCalls);
    
    // Fazer fetch
    return await this.fetchPrice(source, ticker);
  }
}

Onde Isso Entra no Backend Atual

Estrutura Proposta (Sem Implementar)

backend/
├── src/
│   ├── assets/
│   │   ├── assets.service.ts      (existente)
│   │   ├── assets.resolver.ts     (existente)
│   │   └── assets.module.ts       (existente)
│   │
│   ├── pricing/                    (NOVO - não criar ainda)
│   │   ├── pricing.service.ts     // Lógica de fetch
│   │   ├── pricing.resolver.ts    // GraphQL queries
│   │   ├── pricing.module.ts
│   │   ├── providers/
│   │   │   ├── polygon.provider.ts
│   │   │   ├── yahoo.provider.ts
│   │   │   └── cryptocompare.provider.ts
│   │   └── jobs/
│   │       └── price-sync.job.ts  // Cron job
│   │
│   └── portfolios/
│       └── portfolios.service.ts  (modificar depois)

Evitando Recalcular Tudo a Cada Request

Estratégia de Cache

┌─────────────────────────────────────────────┐
│  Request: PortfolioSummary                  │
└─────────────────────────────────────────────┘
                    │
        ┌───────────▼───────────┐
        │  Check cache          │
        │  (Redis / Memory)     │
        └───────────┬───────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
   ┌────▼────┐            ┌────▼────┐
   │ Cache   │            │ Cache   │
   │ Hit     │            │ Miss    │
   └────┬────┘            └────┬────┘
        │                       │
        │              ┌────────▼────────┐
        │              │ Fetch latest    │
        │              │ prices from DB  │
        │              └────────┬────────┘
        │                       │
        └───────────┬───────────┘
                    │
        ┌───────────▼───────────┐
        │  Calculate summary    │
        │  (with cached prices) │
        └───────────────────────┘

Cache Strategy:

Preços: Cache por 5-15 minutos (dependendo da volatilidade)
Portfolio Summary: Cache por 1-2 minutos
Invalidação: Quando novo preço é inserido

Fase 3: Roadmap de Métricas

MVP Metrics (Implementar Primeiro)

1. Portfolio Value

Definição: Soma do valor de mercado de todas as posições

Cálculo:

Portfolio Value = Σ(quantity × currentPrice)

Prioridade: 🔴 Alta
Complexidade: Baixa
Dependências: Price Snapshot (Fase 1)

2. Cost Basis

Definição: Valor total investido (já implementado)

Cálculo:

Cost Basis = Σ(quantity × averageCost)

Prioridade: 🟢 Já implementado
Status: ✅ Completo

3. Unrealized Gain/Loss

Definição: Diferença entre valor atual e custo

Cálculo:

Unrealized G/L = Portfolio Value - Cost Basis
Unrealized G/L % = (Unrealized G/L / Cost Basis) × 100

Prioridade: 🔴 Alta
Complexidade: Baixa
Dependências: Portfolio Value

4. Allocation %

Definição: Percentual de cada ativo/tipo no portfolio

Cálculo:

Allocation % = (Asset Value / Portfolio Value) × 100

Prioridade: 🟡 Média
Complexidade: Baixa
Status: ✅ Parcialmente implementado

Advanced Metrics (Implementar Depois)

1. Time-Weighted Return (TWR)

Definição: Retorno ajustado por tempo, ignorando depósitos/saques

Cálculo:

TWR = [(1 + r1) × (1 + r2) × ... × (1 + rn)] - 1

Prioridade: 🟡 Média
Complexidade: Alta
Uso: Comparar performance de diferentes períodos

2. Money-Weighted Return (MWR)

Definição: Retorno ajustado por valor investido (IRR)

Cálculo:

Resolve: NPV = 0
Onde: Σ(CFt / (1 + MWR)^t) = 0

Prioridade: 🟡 Média
Complexidade: Muito Alta
Uso: Performance real considerando timing de investimentos

3. Volatility (Desvio Padrão)

Definição: Medida de variação dos retornos

Cálculo:

Volatility = √(Σ(ri - r̄)² / n)

Prioridade: 🟢 Baixa
Complexidade: Média
Uso: Medir risco do portfolio

4. Max Drawdown

Definição: Maior queda desde o pico

Cálculo:

Max Drawdown = (Peak - Trough) / Peak

Prioridade: 🟢 Baixa
Complexidade: Baixa
Uso: Entender pior cenário histórico

UX Metrics (Visualização)

1. Monthly Performance

Definição: Retorno mensal do portfolio

Visualização:

Gráfico de barras (últimos 12 meses)
Cor verde/vermelha baseada em positivo/negativo

Prioridade: 🟡 Média
Complexidade: Baixa

2. Annual Performance

Definição: Retorno anual (YTD, 1Y, 3Y, 5Y)

Visualização:

Cards com percentuais
Comparação ano a ano

Prioridade: 🟡 Média
Complexidade: Média

3. Comparison vs Benchmark

Definição: Performance relativa ao S&P 500 ou outro índice

Visualização:

Gráfico de linha comparativo
Portfolio vs S&P 500

Prioridade: 🟢 Baixa
Complexidade: Alta (requer dados de benchmark)

Priorização de Métricas

Fase 1 (MVP - 2-4 semanas):
├── Portfolio Value ✅
├── Cost Basis ✅
├── Unrealized G/L ✅
└── Allocation % ✅

Fase 2 (Intermediário - 1-2 meses):
├── Monthly Performance
├── Annual Performance
└── Volatility

Fase 3 (Avançado - 3+ meses):
├── Time-Weighted Return
├── Money-Weighted Return
├── Max Drawdown
└── Benchmark Comparison

Fase 4: Cashflow + Portfolio = Net Worth

Definição de Net Worth

Net Worth = Total Assets - Total Liabilities

No contexto do Wealth Tracker:

Net Worth = 
  Cash Balance +
  Investment Portfolio Value +
  Other Assets -
  Recurring Expenses (projected) -
  Other Liabilities

Componentes do Net Worth

1. Cash Balance

Fonte: Cashflow module

Cálculo:

Cash Balance = 
  Initial Balance +
  Σ(Income entries) -
  Σ(Expense entries) -
  Σ(Recurring expenses projected)

Prioridade: 🔴 Alta
Status: Dados disponíveis no Cashflow

2. Investment Portfolio Value

Fonte: Portfolio module

Cálculo:

Portfolio Value = Σ(quantity × currentPrice)

Prioridade: 🔴 Alta
Status: Depende de Price Snapshot (Fase 1)

3. Recurring Expenses (Projected)

Fonte: Cashflow Recurring

Cálculo:

Projected Expenses = Σ(monthlyRecurringAmount)

Prioridade: 🟡 Média
Uso: Mostrar compromissos futuros

4. Other Assets / Liabilities

Fonte: Novo módulo (futuro)

Exemplos:

Real estate
Loans
Credit card debt

Prioridade: 🟢 Baixa (futuro)

Visualização no Dashboard

Layout Proposto

┌─────────────────────────────────────────────┐
│         NET WORTH DASHBOARD                 │
├─────────────────────────────────────────────┤
│                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐ │
│  │   Cash   │  │Portfolio │  │   Net    │ │
│  │ $10,000  │  │ $50,000  │  │ $60,000  │ │
│  └──────────┘  └──────────┘  └──────────┘ │
│                                             │
│  ┌───────────────────────────────────────┐ │
│  │     Net Worth Over Time (Chart)       │ │
│  │     [Line chart: last 12 months]      │ │
│  └───────────────────────────────────────┘ │
│                                             │
│  ┌───────────────────────────────────────┐ │
│  │     Breakdown by Category             │ │
│  │     [Pie chart: Cash vs Investments] │ │
│  └───────────────────────────────────────┘ │
│                                             │
│  ┌───────────────────────────────────────┐ │
│  │     Recurring Expenses (Projected)    │ │
│  │     - Netflix: $14.99/month          │ │
│  │     - Rent: $1,200/month              │ │
│  └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

Exemplos de Gráficos

1. Net Worth Over Time

Tipo: Line Chart
Eixo X: Meses (últimos 12)
Eixo Y: Valor em USD
Séries:

Net Worth Total (linha principal)
Cash Balance (área preenchida)
Portfolio Value (área preenchida)

2. Allocation Breakdown

Tipo: Pie/Donut Chart
Categorias:

Cash (%)
Stocks (%)
Crypto (%)
Other (%)

3. Cashflow vs Investments

Tipo: Stacked Bar Chart
Eixo X: Meses
Eixo Y: Valor
Séries:

Income (verde)
Expenses (vermelho)
Investment Contributions (azul)

Integração com Módulos Existentes

Fluxo de Dados

┌─────────────────┐
│  Cashflow       │
│  - Entries      │
│  - Recurring    │
└────────┬────────┘
         │
         │ Cash Balance
         │ Recurring Expenses
         │
┌────────▼────────┐
│  Net Worth      │
│  Calculator     │
└────────┬────────┘
         │
         │ Portfolio Value
         │
┌────────▼────────┐
│  Portfolio      │
│  - Holdings     │
│  - Prices       │
└─────────────────┘

API GraphQL Proposta (Não Implementar Ainda)

type NetWorthSummary {
  totalNetWorth: Float!
  cashBalance: Float!
  portfolioValue: Float!
  recurringExpensesMonthly: Float!
  breakdown: NetWorthBreakdown!
  history: [NetWorthPoint!]!
}

type NetWorthBreakdown {
  cash: Float!
  stocks: Float!
  crypto: Float!
  other: Float!
}

type NetWorthPoint {
  date: DateTime!
  total: Float!
  cash: Float!
  portfolio: Float!
}

Considerações de Implementação

Ordem de Implementação

Fase 1: Price Snapshot (base para tudo)
Fase 2: Integração de preços (dados reais)
Fase 3: Métricas básicas (Portfolio Value, G/L)
Fase 4: Net Worth (unificação)

Dependências

Net Worth
  ├── Cash Balance (Cashflow) ✅ Existe
  ├── Portfolio Value (Portfolio + Prices) ⏳ Fase 1
  └── Recurring Expenses (Cashflow) ✅ Existe

Considerações de Implementação

Princípios de Evolução Incremental

Additive Only: Sempre adicionar, nunca remover
Backward Compatible: Código antigo continua funcionando
Feature Flags: Permitir ativar/desativar features gradualmente
Migration Strategy: Migrações opcionais, não obrigatórias

Estratégia de Rollout

Fase 1: Price Snapshot (2-3 semanas)

Criar tabela AssetPrice
Manter lastPrice em Asset (compatibilidade)
Permitir inserção manual de preços
Não quebra nada existente

Fase 2: Integração de Preços (3-4 semanas)

Implementar providers (Polygon, Yahoo)
Criar cron job (opcional)
Permitir refresh manual
Fallback para lastPrice se API falhar

Fase 3: Métricas (2-3 semanas)

Implementar cálculos de Portfolio Value
Adicionar métricas ao PortfolioSummary
Manter campos antigos por compatibilidade

Fase 4: Net Worth (2-3 semanas)

Criar NetWorthSummary resolver
Integrar Cashflow + Portfolio
Adicionar dashboard
Não modifica módulos existentes

Riscos e Mitigações

Risco 1: Breaking Changes

Mitigação:

Manter campos antigos
Feature flags
Versionamento de API

Risco 2: Performance

Mitigação:

Cache agressivo
Background jobs para cálculos pesados
Indexação adequada

Risco 3: Rate Limits de APIs

Mitigação:

Múltiplos providers (fallback)
Rate limiting próprio
Cache de preços

Risco 4: Dados Inconsistentes

Mitigação:

Validação de dados
Logs de auditoria
Alertas para preços muito antigos

Métricas de Sucesso

Técnicas

✅ Zero breaking changes
✅ Performance mantida (< 500ms para PortfolioSummary)
✅ 99.9% uptime de price fetching

Produto

✅ Usuários conseguem ver Net Worth real
✅ Preços atualizados automaticamente
✅ Métricas úteis para decisões

Conclusão

Este roadmap fornece uma base sólida para evoluir o Wealth Tracker de um sistema baseado em custo para um sistema completo de gestão de patrimônio com preços reais de mercado.

Próximos Passos:

Revisar este documento com o time
Priorizar fases baseado em necessidade de negócio
Implementar Fase 1 (Price Snapshot) quando aprovado
Iterar incrementalmente

Importante: Este documento é um plano. Nenhuma implementação deve ser feita sem aprovação explícita e sem seguir os princípios de evolução incremental descritos aqui.

Documento criado em: Janeiro 2026
Última atualização: Janeiro 2026
Status: Planejamento — Aguardando aprovação para implementação

Carlos Eduardo Gatti Ferreira

Wealth Tracker — Roadmap Financeiro

📋 Índice

Fase 1: Modelo de Price Snapshot

Objetivo

Proposta de Model Prisma (Design Only)

Justificativa de Campos

assetId

price

currency

source

recordedAt

exchange, volume, marketCap

Índices Propostos

Conexão com PortfolioSummary (Futuro)

Fase 2: Estratégia de Integração de Preços

Comparação de APIs

Yahoo Finance (yfinance)

Polygon.io

Alpha Vantage

CryptoCompare / CoinGecko

Estratégia Recomendada (Híbrida)

Fluxo de Fetch de Preços

Opção 1: Cron Job (Recomendado)

Opção 2: On-Demand (Manual Refresh)

Opção 3: Híbrida (Recomendada para Produção)

Rate Limits e Fallback

Estratégia de Fallback

Rate Limit Handling

Onde Isso Entra no Backend Atual

Estrutura Proposta (Sem Implementar)

Evitando Recalcular Tudo a Cada Request

Estratégia de Cache

Fase 3: Roadmap de Métricas

MVP Metrics (Implementar Primeiro)

1. Portfolio Value

2. Cost Basis

3. Unrealized Gain/Loss

4. Allocation %

Advanced Metrics (Implementar Depois)

1. Time-Weighted Return (TWR)

2. Money-Weighted Return (MWR)

3. Volatility (Desvio Padrão)

4. Max Drawdown

UX Metrics (Visualização)

1. Monthly Performance

2. Annual Performance

3. Comparison vs Benchmark

Priorização de Métricas

Fase 4: Cashflow + Portfolio = Net Worth

Definição de Net Worth

Componentes do Net Worth

1. Cash Balance

2. Investment Portfolio Value

3. Recurring Expenses (Projected)

4. Other Assets / Liabilities

Visualização no Dashboard

Layout Proposto

Exemplos de Gráficos

1. Net Worth Over Time

2. Allocation Breakdown

3. Cashflow vs Investments

Integração com Módulos Existentes

Fluxo de Dados

API GraphQL Proposta (Não Implementar Ainda)

Considerações de Implementação

Ordem de Implementação

Dependências

Considerações de Implementação

Princípios de Evolução Incremental

Estratégia de Rollout

Fase 1: Price Snapshot (2-3 semanas)

Fase 2: Integração de Preços (3-4 semanas)

Fase 3: Métricas (2-3 semanas)

Fase 4: Net Worth (2-3 semanas)

Riscos e Mitigações

Risco 1: Breaking Changes

Risco 2: Performance

Risco 3: Rate Limits de APIs

Risco 4: Dados Inconsistentes

`assetId`

`price`

`currency`

`source`

`recordedAt`

`exchange`, `volume`, `marketCap`