Epic/create charge

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
   push:
-    branches: [develop, main]
+    branches: ["epic/**", develop, main]
   pull_request:
     branches: [main]
 

README.md

@@ -1,14 +1,19 @@
 # payment-api
 
-Fundação de um core de pagamentos Pix em Java — infraestrutura, observabilidade e pipeline CI/CD prontos; domínio em construção.
+Core de pagamentos Pix em Java — Hexagonal Architecture, observabilidade e pipeline CI/CD. EPIC-001 (criar cobrança) implementado e testado.
 
 [![CI](https://github.com/lmoraesdev/java-payment-hexagonal/actions/workflows/ci.yml/badge.svg)](https://github.com/lmoraesdev/java-payment-hexagonal/actions/workflows/ci.yml)
 ![Java](https://img.shields.io/badge/Java-21-blue?logo=openjdk&logoColor=white)
 ![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5.3-6DB33F?logo=springboot&logoColor=white)
 
 ## Status
 
-A plataforma está completa: serviços sobem, métricas chegam no Grafana, traces no Jaeger, testes de integração passam com Testcontainers. O que ainda não existe é o domínio de negócio — entidades, casos de uso, portas e adapters de persistência/mensageria. Esses são os próximos passos (ver [Roadmap](#roadmap)).
+| EPIC | Descrição | Status |
+|---|---|---|
+| EPIC-001 | Criar cobrança — domínio, persistência, REST, tratamento de erros, testes | ✅ Concluído |
+| EPIC-002 | Buscar cobrança (`GET /charges/{id}`) + idempotência | 🔲 Roadmap |
+| EPIC-003 | Publicar `ChargeCreated` no Kafka | 🔲 Roadmap |
+| EPIC-008 | Flyway — migrações de schema versionadas | 🔲 Roadmap |
 
 ## Stack
 
@@ -19,112 +24,143 @@ A plataforma está completa: serviços sobem, métricas chegam no Grafana, trace
 | PostgreSQL | 18 | Persistência principal |
 | Kafka (KRaft) | 3.9 | Event streaming — sem Zookeeper |
 | Redis | 7 | Cache / idempotência (pré-instalado, profile `cache`) |
+| SpringDoc OpenAPI | 2.8.17 | Swagger UI + spec OpenAPI 3 |
 | Prometheus + Grafana | latest | Métricas + dashboard Payment Overview pré-provisionado |
 | Jaeger + OpenTelemetry | latest | Distributed tracing via OTLP HTTP |
-| Testcontainers | 1.21 | Testes de integração com banco real |
+| Testcontainers | 1.21 | Testes de integração com PostgreSQL 18 real |
 | Spotless (GJF AOSP) | 2.43 | Formatação automática de código |
 | Checkstyle | 3.5 | Verificação de estilo |
 
 ## Arquitetura
 
 O projeto segue Arquitetura Hexagonal (Ports & Adapters): o domínio não conhece Spring, JPA nem Kafka. Frameworks e infraestrutura ficam nas bordas; a lógica de negócio fica isolada e testável sem container.
 
-Decisões de projeto:
-- **Observabilidade desde o início** — Prometheus, Grafana e Jaeger estão na infra antes do primeiro use case existir. Métricas e traces não são afterthought.
-- **Logging estruturado 5W1H** — cada log emite JSON com `where`, `why`, `when`, `who`, `what`, `how` + `traceId`/`spanId` injetados automaticamente pelo Micrometer MDC. Facilita correlação em produção.
-- **Event-driven preparado** — Kafka configurado com KRaft (sem Zookeeper), consumer/producer prontos no `application.yml`. Nenhum evento publicado ainda.
-
 ```
 com.lmoraesdev.payment
 ├── adapter
-│   ├── in.web              ← PingController, GlobalExceptionHandler
-│   └── out
-│       ├── messaging       ← (roadmap — Kafka producers)
-│       └── persistence     ← (roadmap — JPA repositories)
+│   ├── in.web              ← ChargeController, GlobalExceptionHandler, DTOs
+│   └── out.persistence     ← ChargeJpaEntity, ChargeMapper, ChargeRepositoryAdapter
 ├── application
-│   ├── port.in             ← (roadmap — interfaces de entrada)
-│   ├── port.out            ← (roadmap — interfaces de saída)
-│   └── usecase             ← (roadmap — casos de uso)
+│   ├── port.in             ← CreateCharge (interface), CreateChargeCommand, CreateChargeResult
+│   ├── port.out            ← ChargeRepository (interface)
+│   └── usecase             ← CreateChargeService
 ├── config
-│   └── logging             ← Log5w1h, Logger5w1hBuilder
+│   ├── logging             ← Log5w1h, Logger5w1hBuilder (structured 5W1H logging)
+│   └── OpenApiConfig       ← SpringDoc / Swagger UI
 └── domain
-    ├── event               ← (roadmap — domain events)
-    ├── exception           ← DomainException (base abstrata com código de erro)
-    └── model               ← (roadmap — entidades e value objects)
+    ├── exception           ← DomainException (base), InvalidAmountException
+    └── model               ← Charge, Money, ChargeStatus
 ```
 
-Especificação do domínio planejado (Charge Pix, máquina de estados, Money, idempotência): [`docs/architecture.md`](docs/architecture.md).
+Decisões de projeto:
+- **Domínio puro** — `Charge`, `Money`, `ChargeStatus` sem nenhuma anotação de framework
+- **Armazenamento monetário em centavos** — `amount_centavos BIGINT` no banco; `Money` normaliza para scale=2 no domínio; o mapper converte nos dois sentidos. Elimina risco de ponto flutuante em operações financeiras.
+- **Erros tipados** — `InvalidAmountException extends DomainException` → 422; genéricos → 500
+- **Logging estratégico** — só o use case loga o evento de negócio (`charge_created`); controller e adapters não logam (OTel/Jaeger cobre o fluxo)
+- **Problem Details (RFC 9457)** — todos os erros retornam `ProblemDetail` com `traceId`
+- **Observabilidade desde o início** — Prometheus, Grafana e Jaeger na infra antes do primeiro use case
 
 ## Como rodar
 
-**Pré-requisitos:** Docker Desktop com WSL2 integration habilitada; contexto Docker configurado para `default` (`docker context use default`).
+**Pré-requisitos:** Docker Desktop com WSL2 integration habilitada; contexto Docker configurado para `default`.
 
 ```bash
 # 1. Variáveis de ambiente
 cp .env.example .env
 
-# 2. Subir infra + app (sem Redis)
+# 2. Subir infra + app
 make up
-# equivalente: docker compose up -d --build
 
 # 3. Subir com Redis (profile cache)
 docker compose --profile cache up -d --build
+```
+
+## API
+
+### Criar cobrança
+
+```http
+POST /charges
+Content-Type: application/json
+
+{"amount": 150.00}
+```
+
+**201 Created**
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "status": "ACTIVE",
+  "amount": 150.00,
+  "createdAt": "2025-06-05T18:00:00Z"
+}
+```
 
-# 4. Verificar status
-docker compose ps
+**400 Bad Request** (amount inválido)
+```json
+{
+  "status": 400,
+  "title": "Validation failed",
+  "detail": "Um ou mais campos são inválidos",
+  "errors": { "amount": "must be greater than 0" },
+  "traceId": "abc123..."
+}
 ```
 
 ## Endpoints e observabilidade
 
 | URL | O que se vê |
 |---|---|
+| `http://localhost:8080/swagger-ui.html` | Swagger UI — documentação interativa da API |
+| `http://localhost:8080/v3/api-docs` | Spec OpenAPI 3 em JSON |
 | `http://localhost:8080/ping` | `{"status":"pong"}` — smoke test |
 | `http://localhost:8080/actuator/health` | Status do app, banco e dependências |
 | `http://localhost:8080/actuator/prometheus` | Métricas no formato Prometheus |
-| `http://localhost:8090` | Kafka UI — tópicos, consumer groups, mensagens |
 | `http://localhost:9090` | Prometheus — séries temporais, targets ativos |
-| `http://localhost:3000` | Grafana — dashboard "Payment Overview" (admin/admin) |
+| `http://localhost:3000` | Grafana — dashboard "Payment Overview" (credenciais do `.env`) |
 | `http://localhost:16686` | Jaeger — traces distribuídos por operação |
+| `http://localhost:8090` | Kafka UI — tópicos, consumer groups, mensagens |
 
 ## Testes
 
 ```bash
-# Unitários — sem Docker, rápido
-make test
-# equivalente: ./mvnw test
+# Unitários — sem Docker, rápido (~2s)
+./mvnw test
 
-# Integração — sobe PostgreSQL 18 via Testcontainers
-make verify
-# equivalente: ./mvnw verify
+# Integração + cobertura — sobe PostgreSQL 18 via Testcontainers
+./mvnw verify
 ```
 
+| Teste | Tipo | O que cobre |
+|---|---|---|
+| `MoneyTest` | Unit | Validação de amount (7 casos table-driven) |
+| `ChargeTest` | Unit | `create()`, `restore()`, `equals/hashCode` |
+| `CreateChargeServiceTest` | Unit | Sucesso (3 valores) + erros de validação |
+| `ChargeRepositoryIT` | Integration | Round-trip save/findById com PostgreSQL 18 real |
+| `ChargeControllerIT` | Integration | POST 201, POST 400 Problem Details |
+
 Convenção de nomes:
-- `*Test.java` — testes unitários, executados pelo Surefire
-- `*IT.java` — testes de integração, executados pelo Failsafe
+- `*Test.java` — unitários, Surefire
+- `*IT.java` — integração, Failsafe + Testcontainers
 
-O teste `PaymentApiApplicationIT` valida que o contexto Spring sobe corretamente contra um banco PostgreSQL real, sem mocks.
+Relatório JaCoCo gerado em `target/site/jacoco/index.html` após `./mvnw verify`.
 
 ## CI/CD
 
 | Trigger | Job | O que roda |
 |---|---|---|
-| Push para `develop` ou `main` | Lint + Unit Tests | `spotless:check` → `checkstyle:check` → `mvnw test` |
+| Push para `epic/**`, `develop` ou `main` | Lint + Unit Tests | `spotless:check` → `checkstyle:check` → `mvnw test` |
 | Push para `main` ou PR → `main` | Full Verify + Docker Build | `mvnw verify` (unit + integração) → `docker build` |
 
-O job de integração roda apenas no caminho para `main`, mantendo o ciclo de feedback rápido no `develop`.
-
 ## Padrões
 
-**Formatação e estilo:**
-
 ```bash
 ./mvnw spotless:apply   # formata (Google Java Format, AOSP 4-space)
 ./mvnw spotless:check   # verifica (roda no CI)
 ./mvnw checkstyle:check # estilo (roda no CI)
 ```
 
-**Git hooks** (ativar uma vez por clone):
-
+**Git hooks** — shell scripts em `.githooks/` (ativar uma vez por clone):
 ```bash
 git config core.hooksPath .githooks
 ```
@@ -134,13 +170,14 @@ git config core.hooksPath .githooks
 | `commit-msg` | Valida formato Conventional Commits |
 | `pre-push` | Executa `./mvnw verify` antes de subir |
 
-Formato de commit: `tipo(escopo): descrição` — tipos aceitos: `feat fix docs style refactor test chore build ci perf revert`.
+Formato de commit: `tipo(escopo): descrição` — tipos: `feat fix docs style refactor test chore build ci perf revert`.
 
-**Makefile:**
+> **Nota:** os hooks são scripts shell nativos (`.githooks/`). Husky está previsto para substituí-los em versão futura.
 
+**Makefile:**
 ```
 make up       # docker compose up -d --build
-make down     # docker compose down (mantém volumes)
+make down     # docker compose down
 make clean    # docker compose down -v (remove volumes)
 make logs     # docker compose logs -f app
 make test     # ./mvnw test
@@ -149,19 +186,6 @@ make format   # ./mvnw spotless:apply
 make db       # psql no container postgres
 ```
 
-## Roadmap
-
-O que está especificado em [`docs/architecture.md`](docs/architecture.md) e ainda não implementado:
-
-- [ ] Entidade `Charge` com value object `Money` e `ChargeStatus`
-- [ ] Máquina de estados (`PENDING → ACTIVE → PAID / EXPIRED / CANCELLED`)
-- [ ] Caso de uso `CreateCharge` com idempotência por header
-- [ ] Adapter de persistência JPA (`ChargeRepository`)
-- [ ] Publicação de eventos de domínio no Kafka (`ChargeCreated`, `ChargePaid`, etc.)
-- [ ] Consumer para eventos externos (webhook/notificação)
-- [ ] Uso do Redis para cache de idempotência e locks
-- [ ] Endpoints REST de cobrança (`POST /charges`, `GET /charges/{id}`)
-
 ---
 
 [Leandro Moraes](https://github.com/lmoraesdev)