📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados em Especialização em Backend com Java e Spring Boot. Recomendado revisar antes de começar.

🚀 Controle de Gastos com Spring Boot e HTMX (v1)

v1.0 — CRUD Básico, Spring Data JPA, H2 Database e Server-Driven UI com HTMX

Trilha de Especialização Pedagógica — Projeto 1 de 4

🎓 Nível Profissional Simulado: Desenvolvedor Java Júnior. Todo desenvolvedor backend Java precisa dominar o ecossistema Spring Boot (Controllers, Services, Repositories, JPA Entities). Com HTMX, você constrói aplicações modernas e interativas sem precisar de frameworks JavaScript pesados.

—`

🎯 Objetivo & Escopo do Projeto

Construir do zero a primeira versão (v1) do Sistema de Controle de Gastos Pessoais, implementando operações de cadastro, listagem e exclusão de lançamentos financeiros com Spring Boot 3, persistência com Spring Data JPA, banco em memória H2 e interface reativa com Thymeleaf + HTMX.

—`

🧑‍💼 Fase 1 — Levantamento de Requisitos

O Briefing do Cliente (Usuário Individual de Finanças)

“Preciso de um sistema simples onde eu possa lançar meus gastos do dia a dia com descrição, valor e data. Quero ver a lista dos meus gastos em uma tabela com o valor total somado e poder excluir lançamentos errados clicando em um botão sem a página inteira piscar ou recarregar.”

Requisitos Funcionais (RF) e Não-Funcionais (RNF)

ID Tipo Descrição Origem no Briefing
RF01 Funcional Cadastrar novos lançamentos financeiros (descrição, valor em reais e data). “lançar meus gastos do dia a dia”
RF02 Funcional Listar todos os gastos em ordem cronológica com formatação monetária. “ver a lista dos meus gastos”
RF03 Funcional Excluir um gasto específico com atualização atômica da tabela via HTMX. “excluir lançamentos sem recarregar”
RNF01 Não-Funcional Resposta da interface em menos de 100ms utilizando HTMX swaps (hx-target). Interatividade sem SPA
RNF02 Não-Funcional Banco em memória H2 configurado para inicialização rápida de desenvolvimento. Agilidade Local

—`

📋 Fase 2 — Backlog & User Stories

ID User Story Prioridade
US01 Como usuário, quero cadastrar uma despesa e vê-la adicionada na tabela imediatamente. Alta
US02 Como usuário, quero excluir uma despesa com um clique sem recarregar a tela. Alta

Quadro Kanban da Sprint

User Story To Do Doing Done
US01 — Cadastro de Gastos     ✅
US02 — Exclusão Dinâmica HTMX     ✅

—`

🌿 Fase 3 — Engenharia em Equipe (Git Flow & Setup)

# Branch da funcionalidade
git checkout -b feature/US01-crud-gastos-htmx

# Executar a aplicacao via Maven Wrapper
./mvnw spring-boot:run

—`

🛠️ Fase 4 — Implementação Guiada (GastoController.java)

@Controller
@RequestMapping("/gastos")
public class GastoController {

    private final GastoRepository repository;

    public GastoController(GastoRepository repository) {
        this.repository = repository;
    }

    @GetMapping
    public String listar(Model model) {
        model.addAttribute("gastos", repository.findAll());
        return "gastos/index";
    }

    @PostMapping
    public String criar(@ModelAttribute Gasto gasto, Model model) {
        repository.save(gasto);
        model.addAttribute("gastos", repository.findAll());
        return "gastos/index :: tabela-gastos"; // Retorna apenas o fragmento HTML para o HTMX
    }
}

—`

🚀 Como Executar no Laboratório

1. Abra o terminal na pasta deste projeto

No seu editor/IDE, abra a pasta deste projeto (File > Open Folder) ou navegue via terminal:

cd javaweb_gastos_01_htmx

2. Execute a aplicação e os testes

./mvnw spring-boot:run
./mvnw test

[!TIP] Dica para execução a partir da raiz do repositório: Se você abriu o repositório completo no VS Code, basta navegar até a pasta antes de executar: cd proj_aplicacoes_full_stack/projetos/javaweb_gastos_01_htmx`

🧭 Decisões de Arquitetura (ADRs)

—`

🧪 Testes de Validação & Asserções

# Executar testes unitarios com JUnit 5
./mvnw test

—`

✅ Checkpoint Final

  1. CRUD de gastos persistindo no banco H2.
  2. Requisições HTMX substituindo o fragmento da tabela de forma reativa.
⬅️ Ver Todos os Projetos no Super-Hub 🏠 Página Inicial do Portal