MVP 1 - Transacoes - Tecnico

Topologia

REST

Rotas principais:

• POST /transactions
• PUT /transactions/{id}
• DELETE /transactions/{id}
• GET /transactions/summary
• GET /transactions/dashboard
• GET /transactions/list
• GET /transactions/expenses
• GET /transactions/due-range
• GET /transactions/deleted
• PATCH /transactions/restore/{id}
• DELETE /transactions/{id}/force

Arquivo de registro:

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

GraphQL

Tambem ha queries e mutations para transacoes no backend.

Arquivos-base:

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

Modelo de dominio

Arquivos:

• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/models/transaction.py
• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/schemas/transaction_schema.py

Campos relevantes:

• title
• description
• observation
• amount
• currency
• type
• status
• due_date
• start_date
• end_date
• is_recurring
• is_installment
• installment_count
• installment_group_id
• tag_id
• account_id
• credit_card_id
• paid_at
• deleted

Orquestracao de regra

Application service:

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

Pontos fortes da implementacao:

• normalizacao de tipo, status, moeda e datas
• validacao de payload recorrente
• validacao de ownership de referencias
• geracao de parcelas em lote
• soft delete com restauracao

Recursos de leitura

Arquivo:

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

Leituras relevantes:

• resumo mensal
• dashboard mensal
• despesas por periodo
• vencimentos por periodo
• lista de ativas
• lista de deletadas

Pontos arquiteturais relevantes

• o controller virou fachada de compatibilidade
• criacao, update e delete foram extraidos em mixins/arquivos dedicados
• leitura pesada esta em report_resources.py
• payloads novos tentam conviver com payload legado via contrato de compatibilidade

Drift atual com frontends

1. frontends consultam GET /dashboard/overview, mas o backend exposto aqui oferece GET /transactions/dashboard
2. o dashboard de frontend hoje usa fallback visual quando a chamada falha

Riscos tecnicos

• alto peso funcional em transaction_application_service.py
• frontends ainda nao usam plenamente os endpoints reais de transacoes
• a experiencia completa de CRUD ainda nao esta refletida em web/app

Diagnostico pre-FastAPI

Causa raiz

• o dominio de transacoes ficou anos servindo ao mesmo tempo como CRUD, read model de dashboard e camada de compatibilidade com contratos antigos;
• o contrato canônico so foi sendo extraido aos poucos, sem remoção completa dos aliases legados;
• OpenAPI e frontends passaram um periodo longo consumindo snapshots incompletos ou desatualizados.

Problema

• coexistem /transactions, /transactions/list, /transactions/expenses, /transactions/dashboard e /transactions/due-range, com semanticas misturadas;
• parte do custo de leitura ainda e maior que o necessario, em especial no resumo mensal e em listagens derivadas;
• GraphQL nao reflete todo o vocabulário do REST canônico;
• a documentação pública ainda nao reflete com confiança toda a superfície de transações.

Solucao planejada

1. concluir o ARC-09 e consolidar GET /transactions, GET /transactions/{transaction_id} e PATCH /transactions/{transaction_id} como superficie principal;
2. manter aliases legados apenas com deprecação explicita;
3. mover dashboard para GET /dashboard/overview como read model oficial;
4. reduzir custo de consultas mensais e de filtros derivados;
5. alinhar GraphQL e docs ao vocabulário canônico do REST.

Estado real do contrato

O dominio de transacoes esta funcional, mas ainda nao esta estabilizado como contrato canonico de MVP 1.

Principais drifts atuais:

• a colecao canonica esperada por web/app e GET /transactions, mas a API real de leitura esta em GET /transactions/list
• nao existe GET /transactions/{id} como leitura singular canonica
• PUT /transactions/{id} aceita payload parcial, entao hoje ele se comporta como PATCH
• a familia de reads esta fragmentada entre:
• GET /transactions/list
• GET /transactions/summary
• GET /transactions/dashboard
• GET /transactions/expenses
• GET /transactions/due-range
• GET /transactions/deleted
• os parametros de query nao seguem um vocabulario unico
• parte importante da leitura ainda faz ORM e regra direto no controller

Principios obrigatorios de estabilizacao

Todas as rotas deste dominio devem seguir estes principios antes do MVP 2:

• REST estrito por recurso e nao por tela
• semantica HTTP correta
• contratos pequenos, coesos e previsiveis
• separacao clara entre write model, read model e bootstrap de dashboard
• regra de negocio concentrada em services/query services e nao espalhada nos controllers
• Dependency Injection explicita e facilmente testavel
• compatibilidade transitoria so quando houver consumidor real
• paridade clara entre REST e GraphQL quando o recurso existir nos dois transportes

Superficie canonica alvo

CRUD de dominio

• GET /transactions
• GET /transactions/{transaction_id}
• POST /transactions
• PATCH /transactions/{transaction_id}
• DELETE /transactions/{transaction_id}
• PATCH /transactions/{transaction_id}/restore

Leituras especializadas de MVP 1

• GET /transactions/summary
• GET /transactions/due-range
• GET /transactions/deleted

Fora do dominio de transacoes

• GET /dashboard/overview

GET /transactions/dashboard deve existir apenas como compatibilidade transitoria enquanto web/app migram integralmente para /dashboard/overview.

Superficie a deprecar

• GET /transactions/list
• deve ser absorvido por GET /transactions
• GET /transactions/expenses
• deve virar filtro da colecao canonica, nao endpoint proprio
• PUT /transactions/{transaction_id}
• deve ser deprecado em favor de PATCH /transactions/{transaction_id}
• DELETE /transactions/{transaction_id}/force
• deve ficar tratado como rota operacional/avancada, nao como superficie principal do produto

Proximo hardening planejado

No programa API18, transacoes entram em um sweep final de:

• reducao de complexidade acidental no dominio;
• eliminacao de leituras com N+1 conhecido;
• reducao de serializacao e paginacao em memoria nas leituras mais quentes;
• reforco da separacao entre command path, query path e read models;
• preservacao integral do contrato canônico ja estabilizado no MVP 1.

Esse bloco e o principal multiplicador de performance e manutenibilidade do backend.

Contrato recomendado por endpoint

GET /transactions

Objetivo:

• lista canonica de transacoes do usuario autenticado

Query params canonicamente aceitos:

• page
• per_page
• type
• status
• start_date
• end_date
• tag_id
• account_id
• credit_card_id
• source
• include_deleted apenas se houver uso real; default false

Resposta:

• data.items
• meta.pagination
• meta.filters

Cada item deve trazer so o necessario para listagem:

• id
• title
• amount
• currency
• type
• status
• due_date
• paid_at
• source
• is_recurring
• is_installment
• installment_count
• referencias resumidas de tag, account e credit_card quando existirem

Nao deve trazer:

• agregados de dashboard
• saldo consolidado
• payloads volumosos de detalhe se a tela for so lista

GET /transactions/{transaction_id}

Objetivo:

• detalhe canonico de uma transacao

Resposta recomendada:

• identity
• core
• money
• schedule
• installment
• references
• provenance
• timestamps

Campos relevantes:

• id
• title
• description
• observation
• amount
• currency
• type
• status
• due_date
• paid_at
• start_date
• end_date
• is_recurring
• is_installment
• installment_count
• installment_group_id
• tag
• account
• credit_card
• source
• external_id
• bank_name
• created_at
• updated_at

user_id nao deve ser campo publico necessario aqui, porque o recurso ja esta scoped ao proprio usuario autenticado.

GET /transactions/summary

Objetivo:

• resumo mensal financeiro

Regra:

• deve devolver agregados mensais
• nao deve misturar ledger paginado no mesmo contrato canonico

Se houver necessidade de lista do mes:

• usar GET /transactions?start_date=...&end_date=...

GET /transactions/due-range

Objetivo:

• leitura especializada de vencimentos

Regra:

• manter apenas se houver tela ou fluxo claro de acompanhamento de vencimentos
• vocabulario de parametros deve convergir para o mesmo padrao temporal do dominio

Direcao arquitetural

REST

• controllers finos
• validacao e orquestracao em application/query services
• serializers/presenters compartilhados
• alias de compatibilidade explicitamente temporarios

GraphQL

Paridade minima esperada:

• transactions
• transaction(id)
• createTransaction
• updateTransaction
• deleteTransaction

Views especializadas como transactionSummary e transactionDueRange podem continuar, mas devem nascer do mesmo core de leitura.

Ordem recomendada de execucao

1. publicar GET /transactions como colecao canonica
2. publicar GET /transactions/{transaction_id} como detalhe canonico
3. introduzir PATCH /transactions/{transaction_id} e manter PUT apenas como compatibilidade
4. mover dashboard canonico para GET /dashboard/overview
5. deprecar GET /transactions/list e GET /transactions/expenses
6. unificar parametros de query
7. alinhar REST, GraphQL, OpenAPI, Postman e tipos gerados
8. extrair query services compartilhados para preparar a migracao do MVP 2 em FastAPI