Pular para conteúdo

MVP 1 - Carteira - Tecnico

Backend

Entradas

Rotas principais:

  • POST /wallet
  • GET /wallet
  • PUT /wallet/{investment_id}
  • DELETE /wallet/{investment_id}
  • GET /wallet/{investment_id}/history

Arquivo:

  • /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/controllers/wallet/entry_resources.py

Operacoes

Rotas principais:

  • POST /wallet/{investment_id}/operations
  • GET /wallet/{investment_id}/operations
  • PUT /wallet/{investment_id}/operations/{operation_id}
  • DELETE /wallet/{investment_id}/operations/{operation_id}
  • GET /wallet/{investment_id}/operations/summary

Arquivo:

  • /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/controllers/wallet/operation_resources.py

Valorizacao

Rotas principais:

  • GET /wallet/valuation
  • GET /wallet/valuation/history
  • GET /wallet/{investment_id}/valuation

Arquivo:

  • /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/controllers/wallet/valuation_resources.py

Modelo e validacao

Arquivos:

  • /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/models/wallet.py
  • /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/schemas/wallet_schema.py

Classes de ativo aceitas:

  • custom
  • stock
  • fii
  • etf
  • bdr
  • crypto
  • cdb
  • cdi
  • lci
  • lca
  • tesouro
  • fund

Regras tecnicas relevantes

  • ativos de mercado exigem ticker
  • ticker implica quantidade
  • ticker e valor manual nao coexistem
  • renda fixa exige annual_rate
  • historico de alteracao fica em JSON mutavel no proprio item

Valorizacao

Arquivo central:

  • /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/services/portfolio_valuation_service.py

Fontes de valorizacao:

  • preco de mercado via BRAPI
  • custo base de operacoes
  • valor estimado na criacao
  • projecao de renda fixa
  • valor manual

Observabilidade e resiliencia

Para o bloco de carteira, a integracao com BRAPI deve operar com:

  • cache-aside e fallback para ultima cotacao valida;
  • sinalizacao explicita de stale_quote=true quando a cotacao atual nao estiver disponivel;
  • logs estruturados por ticker, origem, latencia, status HTTP e correlation_id;
  • monitoracao minima de:
  • disponibilidade da consulta;
  • cache_hit_rate;
  • latencia p95;
  • frequencia de resposta stale.

O objetivo operacional nao e bloquear a experiencia quando a BRAPI degradar, e sim manter o produto utilizavel com degradacao controlada.

Web e App

Web

  • pagina: /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-web/app/pages/carteira.vue
  • composable: /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-web/app/composables/useWallet.ts

App

  • tela: /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-app/app/(private)/carteira.tsx
  • hook: /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-app/hooks/queries/use-wallet-query.ts

Gap tecnico atual

Os frontends consultam:

  • GET /wallet/summary

Mas o backend exposto neste recorte mostra:

  • GET /wallet/valuation
  • GET /wallet/valuation/history
  • GET /wallet

Consequencia:

  • web e app exibem placeholders quando a integracao falha
  • o contrato ainda precisa ser alinhado

Contrato esperado entre canais

Para metas e carteira, web e app devem convergir para um contrato unico com a API como source of truth, incluindo:

  • serializacao monetaria em BRL como string decimal;
  • timestamps em UTC (ISO-8601);
  • resource_version para concorrencia otimista;
  • idempotency_key nas operacoes mutaveis;
  • suporte a leitura incremental com updated_since, cursor e exclusao logica via deleted_at_utc.