MVP 1 - Metas - Tecnico¶

Backend¶

Rotas REST:

GET /goals
POST /goals
GET /goals/{goal_id}
PUT /goals/{goal_id}
DELETE /goals/{goal_id}
GET /goals/{goal_id}/plan
POST /goals/simulate

Arquivos-base:

/tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/controllers/goal/routes.py
/tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/controllers/goal/resources.py

Modelo¶

/tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/models/goal.py
/tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/schemas/goal_schema.py

Campos:

title
description
category
target_amount
current_amount
priority
target_date
status

Regra de planejamento¶

Application service:

/tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/application/services/goal_application_service.py

Servico de planejamento:

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

Logica relevante:

calcula valor restante
calcula capacidade com base em renda menos despesas
define aporte projetado
estima meses para atingir a meta
classifica saude da meta
gera recomendacoes

Saudes possiveis na pratica:

completed
on_track
off_track
at_risk

GraphQL¶

Metas tambem estao expostas em GraphQL:

/tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/graphql/queries/goal.py
/tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/graphql/mutations/goal.py

Frontends¶

Estado atual (2026-03-28)¶

Canal	Estado
API	CRUD completo + plano + simulacao
Web	Pagina ativa com lista, filtros, criacao, edicao, exclusao e painel de planejamento (PR #349)
App	Tela ainda nao implementada

Web — artefatos entregues (MVP1-P2, PR #349)¶

Mutations: - useCreateGoalMutation — POST /goals, invalida ["goals","list"] - useUpdateGoalMutation — PATCH /goals/:id, invalida ["goals","list"] - useDeleteGoalMutation — DELETE /goals/:id, invalida ["goals","list"]

Query de planejamento: - useGoalPlanQuery(goalId: Ref<string|null>) — GET /goals/:id/plan, habilitada apenas quando goalId nao e null

Componentes: - GoalForm — NModal + NForm com presets de prazo (1m/3m/6m/1y/custom) e campo de status em modo edicao - GoalPlanPanel — exibe aporte mensal necessario, meses restantes, data projetada e badge de saude

Campos do DTO de criacao: - name (obrigatorio) - description (opcional) - target_amount (obrigatorio) - current_amount (opcional) - target_date (YYYY-MM-DD, opcional) - status (opcional, padrao active)

Contrato esperado entre canais¶

Para metas, o contrato entre web/app e API deve seguir estes principios:

API como fonte canonica de dados persistidos;
valores monetarios em BRL serializados como string decimal;
timestamps em UTC (ISO-8601);
resource_version em update/delete para controle otimista;
idempotency_key nas operacoes mutaveis;
leitura incremental com updated_since, limit, cursor e aplicacao de deleted_at_utc para exclusao logica.

Diagnostico pre-FastAPI¶

Causa raiz¶

metas foi um dominio de API construído antes da consolidacao da semantica REST do MVP 1;
PUT e PATCH acabaram chamando o mesmo update parcial;
simulations e bridges de meta foram evoluindo em paralelo, sem ownership final totalmente explicitado.

Problema¶

o contrato atual e funcional, mas nao e um exemplo limpo de REST estrito;
frontends ainda nao consomem metas em tela, o que mascara pequenos drifts de contrato;
sem normalizacao agora, o dominio entrara no FastAPI carregando ambiguidade desnecessaria.

Solucao planejada¶

definir qual e a semantica canônica de PUT e PATCH para metas;
garantir que goals e simulations tenham ownership de superficie claro;
alinhar docs, OpenAPI e GraphQL ao contrato final;
preservar compatibilidade temporaria apenas onde houver consumidor real.

Proximo hardening planejado¶

Dentro do programa API18, metas entra no mesmo sweep final de consistencia de wallet, com foco em:

semantica REST mais previsivel;
docs e contratos mais homogeneos;
menor variacao arquitetural entre dominios maduros do MVP 1;
preparacao mais limpa para a coexistencia com FastAPI.