📋 Sobre o projeto
Um assistente de finanças pessoais operado por voz. O usuário fala um comando em português, e a aplicação registra o gasto ou responde uma consulta — sem formulário, sem digitar.
🔄 O pipeline de voz
Cada interação percorre quatro estágios:
1 Fala → texto
O Whisper transcreve o áudio enviado pelo usuário.
2 Interpretação e tool calling
O gpt-4o-mini entende a intenção e escolhe qual função Java invocar.
3 Execução do caso de uso
Java e JPA persistem os dados. É aqui que a regra de negócio vive — não no prompt.
4 Texto → fala
O gpt-4o-mini-tts devolve a resposta em áudio.
🧰 As ferramentas expostas à IA
Quatro métodos anotados com @Tool formam todo o vocabulário que o modelo tem à disposição:
| Ferramenta | O que faz |
|---|---|
registrarGasto | Cria uma transação — só o valor é obrigatório |
consultarTotalDoPeriodo | Soma as despesas entre duas datas |
listarGastosDoPeriodo | Lista as transações individuais |
consultarTotalPorCategoria | Agrupa os totais por categoria |
🏛️ Arquitetura em camadas
- domain — lógica central, com zero importações de framework. Contém o
record
Transactione as portas de repositório. - application — casos de uso e integração com a IA:
AssistantService, as anotações@Tool, transcrição e síntese de voz. - infrastructure — adaptadores: persistência JPA e controllers REST.
A dependência aponta sempre para dentro. Trocar o OpenAI por outro provedor, ou o H2 por MySQL, não encosta no domínio.
🔌 Endpoints REST
| Método | Rota | Entrada | Saída |
|---|---|---|---|
| POST | /api/chat | JSON com a mensagem | JSON com a resposta |
| POST | /api/transcribe | Áudio (multipart) | JSON com o texto |
| POST | /api/synthesize | JSON com o texto | audio/mpeg |
| POST | /api/assistant/voice | Áudio (multipart) | audio/mpeg |
Todos eles são documentados em OpenAPI 3.1 pelo
springdoc e podem ser testados direto do navegador em /docs.
⚖️ Decisões técnicas
BigDecimalpara dinheiro, nuncadouble— ponto flutuante binário não representa valores decimais com exatidão.EnumType.STRINGnas categorias: comORDINAL, reordenar o enum corromperia silenciosamente os dados já gravados.- Datas em ISO-8601 nos parâmetros das ferramentas, evitando ambiguidade de formato.
- Retorno das ferramentas em texto, não JSON — controla o que ocupa o contexto do modelo.
- Validação no construtor do domínio, antes de qualquer persistência.
- Erros em RFC 7807 (
problem+json), com detalhe por campo e status adequado: 400 para entrada inválida, 422 para violação de domínio, 413 para upload grande demais.
✅ Testes
São 17 testes automatizados, separados pelo que custam para rodar:
| Tipo | Qtd. | Tempo | Custo |
|---|---|---|---|
| Unitários | 11 | 0,4s | zero |
De fatia (@WebMvcTest, @DataJpaTest) | 5 | 4s | zero |
De contexto (@SpringBootTest) | 1 | 9s | zero |
De integração com a OpenAI (sufixo *IT) | 5 | ~30s | mínimo |
Os testes verificam efeitos — o dado gravado no banco — em vez de afirmar sobre o texto que o modelo produziu, que varia a cada execução.
⏱️ Latência
Registrar um gasto leva cerca de 8,3s e uma consulta, 6,5s. O tempo reflete quatro chamadas à OpenAI por interação: transcrição, duas rodadas de chat e síntese de voz — não lentidão da aplicação em si.