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¶

Estado atual (2026-03-29)¶

Canal	Estado
API	CRUD completo + valorizacao + operacoes
Web	MVP1-P3 entregue e mergeado (PR #350) — WalletEntryForm, WalletPositionsPanel, WalletAllocationSection
App	Tela ainda nao implementada

Web — artefatos entregues (MVP1-P3, PR #350)¶

Mutations: - useCreateWalletEntryMutation — POST /wallet, invalida ["wallet","entries"] e ["wallet","summary"] - useDeleteWalletEntryMutation — DELETE /wallet/:id, invalida ["wallet","entries"] e ["wallet","summary"]

Componentes: - WalletEntryForm — NModal + NForm com campos dinamicos: ticker path (quantity obrigatoria) vs value path (current_value obrigatorio); campos opcionais: annual_rate, description - WalletPositionsPanel — grid responsivo de cards com nome, ticker badge, tipo badge, valor atual e percentual de variacao - WalletAllocationSection — agrupa entradas por asset_type com barras de progresso NProgress e percentuais

Payload de criacao: - ticker (opcional — aciona modo ticker) - asset_type (obrigatorio) - name (obrigatorio) - quantity (obrigatorio se ticker presente) - current_value (obrigatorio se ticker ausente) - annual_rate (opcional — renda fixa) - description (opcional)

Pagina: - app/pages/portfolio.vue — botao "Adicionar ativo", integra os 3 novos componentes e ambas as mutations

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.

Diagnostico pre-FastAPI¶

Causa raiz¶

wallet nasceu como modulo funcionalmente rico, mas com naming e semantica pouco uniformes;
parte das rotas usa camelCase em query params e parte da documentacao dos frontends ainda espera endpoints que nao existem mais;
a superficie REST cresceu primeiro, enquanto GraphQL ficou com um recorte diferente da carteira e dos investimentos.

Problema¶

wallet mistura cadastro de item, historico, valorizacao e operacoes com vocabulários diferentes;
startDate/finalDate em valorizacao nao conversa com start_date/end_date de outros dominios;
frontends ainda carregam expectativas antigas, como /wallet/summary;
PUT continua sendo usado como update parcial em pontos do dominio.

Solucao planejada¶

normalizar wallet para REST estrito, com vocabulário unico de query params;
explicitar ownership entre wallet e investments no GraphQL;
manter valorizacao e historico como read models claros, separados da colecao principal;
alinhar docs publicas e frontends com os endpoints que realmente existem;
preparar a superficie para controle otimista e idempotencia em etapa posterior.

Proximo hardening planejado¶

Dentro do programa API18, carteira entra em um sweep final de consistencia para:

reduzir semantica legada residual em endpoints de update;
reforcar a canonicidade entre surface REST, docs e consumers;
aproximar o modulo do mesmo padrao de previsibilidade ja aplicado em transacoes;
preservar o comportamento atual de negocio e o modelo de valorizacao.