Pular para conteúdo

MVP 1 - Dashboard - Tecnico

Backend

Endpoint principal:

  • GET /transactions/dashboard

Arquivo:

  • /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/controllers/transaction/report_resources.py

Payload de saida:

  • mes
  • totais de receita, despesa e saldo
  • contagens
  • categorias de topo

Web

Pagina:

  • /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-web/app/pages/dashboard.vue

Composables:

  • /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-web/app/composables/useDashboard.ts

Comportamento atual:

  • consome GET /dashboard/overview
  • se der erro, usa dashboardPlaceholder
  • permite selecao de mes localmente sobre os dados carregados

App

Tela:

  • /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-app/app/(private)/dashboard.tsx

Hook:

  • /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-app/hooks/queries/use-dashboard-query.ts

Comportamento atual:

  • tambem consome GET /dashboard/overview
  • se der erro, usa placeholder
  • extrai snapshot mensal em memoria

Estado atual (2026-03-28)

Integracao real em producao. Gaps resolvidos:

  • endpoint alinhado para GET /dashboard/overview?month=YYYY-MM
  • mapper dual-path: suporta contrato rico (period/summary/comparison) e contrato simplificado (month/totals/top_categories)
  • wrapper v2 { success, message, data } stripado por unwrapV2() antes do mapeamento
  • composable useChartSeriesMapper (MIC-33, PR #348) centraliza cores e labels das series de grafico

Composables e servicos ativos

Artefato Caminho Funcao
useDashboardOverviewQuery app/features/dashboard/queries/ query principal com normalizeFilters
mapDashboardOverviewDto app/features/dashboard/services/dashboard-overview.mapper.ts mapper dual-path
useChartSeriesMapper app/composables/useChartSeriesMapper/ normaliza timeseries para series de grafico com tokens de cor
DashboardTimeseriesChart app/components/dashboard/ consome useChartSeriesMapper, cores por tokens

Filtros de periodo suportados

  • current_month → mes corrente
  • 1m, 3m, 6m, 12m → meses anteriores
  • custom → inicio e fim via date picker (requer ambas as datas)

Recomendacao tecnica

  • decidir um contrato canônico
  • alinhar API e frontends para o mesmo endpoint
  • manter placeholder apenas como experiencia de desenvolvimento, nao como estado permanente de producao
  • placeholder eliminado; dados reais em staging
  • cartao de credito fora deste pacote inicial
  • proximos: enriquecer timeseries (dados diarios vs mensais dependem de janela de consulta do backend)

Diagnostico pre-FastAPI

Causa raiz

  • dashboard nasceu acoplado ao dominio de transacoes;
  • web e app evoluiram para um endpoint proprio (/dashboard/overview) antes de a API consolidar essa fronteira;
  • isso deixou uma duplicidade conceitual entre read model de dashboard e operacoes do dominio de transacoes.

Problema

  • o backend ainda carrega heranca de /transactions/dashboard;
  • frontends ja pensam em dashboard como read model proprio;
  • sem uma decisao final, o FastAPI herdara uma fronteira confusa entre agregacao de dashboard e CRUD financeiro.

Solucao planejada

  1. oficializar GET /dashboard/overview como contrato canonico do dashboard;
  2. manter /transactions/dashboard apenas como compatibilidade transitória;
  3. documentar dashboard como read model derivado de transacoes, e nao como parte do CRUD de transacoes;
  4. alinhar GraphQL e docs a essa ownership.

Papel do dashboard na estabilizacao do MVP 1

Para o MVP 1 estabilizado:

  • dashboard nao deve morar semanticamente dentro do dominio de transacoes
  • transacoes continuam sendo a base de calculo
  • mas a leitura de produto deve sair por um read model proprio: GET /dashboard/overview

Isso reduz tres problemas atuais:

  • evita inflar o contrato de /transactions com dados que nao sao de colecao
  • permite filtros de periodo focados em leitura de produto
  • desacopla bootstrap de tela das rotas operacionais do dominio

Contrato canonico esperado

GET /dashboard/overview deve responder perguntas de produto, nao de CRUD:

  • qual o saldo consolidado
  • como o periodo selecionado fechou
  • como receita, despesa e saldo evoluiram
  • quais agregados principais a home precisa mostrar

O que faz sentido trazer:

  • saldo atual
  • serie mensal do periodo
  • totais de receita e despesa
  • balance do periodo
  • recortes agregados de apoio a leitura da tela

O que nao faz sentido trazer:

  • ledger completo de transacoes
  • payload detalhado de item individual
  • semantica de colecao/paginacao de CRUD

Regra de convivio com transacoes

Durante a migracao:

  • GET /transactions/dashboard pode permanecer como alias/compat
  • novos consumidores devem usar GET /dashboard/overview
  • a fonte de agregacao pode continuar vindo do core de analytics de transacoes
  • o endpoint de dashboard deve ser tratado como read model de produto