Skip to content

Commit 81c65b2

Browse files
erichiroshierichiroshi
committed
docs(readme): update README and readme_pdf
- Add OpenTelemetry + Zipkin to Observability stack section - Add Resilience4j and ShedLock to new Resilience stack section - Mark OpenTelemetry and Rate limiting as completed in Next Steps - Update RefreshTokenCleanupJob section mentioning ShedLock lock distribution - Add Spring Events and Resilience4j to Architectural Decisions section
1 parent 9e34510 commit 81c65b2

File tree

2 files changed

+80
-47
lines changed

2 files changed

+80
-47
lines changed

‎readme.md‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -265,6 +265,11 @@ Uma biblioteca precisa:
265265
- **Micrometer** (abstração de métricas)
266266
- **Prometheus** (coleta de métricas, scrape a cada 10s)
267267
- **Grafana** (dashboards provisionados automaticamente)
268+
- **OpenTelemetry + Zipkin** (tracing distribuído com traceId nos logs)
269+
270+
### Resiliência
271+
- **Resilience4j** (Circuit Breaker + Retry para integrações externas)
272+
- **ShedLock** (lock distribuído para scheduled jobs)
268273

269274
### Testes
270275
- **Testcontainers** (PostgreSQL real em testes de integração)
@@ -418,6 +423,16 @@ Request → Controller → Service → [Cache Hit? → Return]
418423

419424
**Benefício:** Código relacionado fica junto; cada pacote é praticamente auto-contido.
420425

426+
### ✔ Spring Events para desacoplamento de domínios
427+
**Por quê:** Preparação para separação futura em microservices sem introduzir Kafka prematuramente.
428+
429+
**Benefício:** Domínios se comunicam via eventos internos (`ApplicationEventPublisher`) em vez de injeção direta de repositórios entre pacotes. Troca futura por Kafka/RabbitMQ requer mudança mínima.
430+
431+
### ✔ Resilience4j em integrações externas
432+
**Por quê:** Proteger o monolito contra falhas de serviços externos (S3) e preparar os pontos de integração para extração futura.
433+
434+
**Benefício:** Circuit Breaker evita cascata de falhas; Retry com backoff trata falhas transitórias. Padrão já estabelecido para quando LoanService precisar chamar BookService via HTTP.
435+
421436
---
422437

423438
## 📊 Observabilidade
@@ -587,6 +602,7 @@ Limpa automaticamente refresh tokens expirados do banco de dados.
587602

588603
- **Frequência:** Todo dia às 02:00 AM (`cron = "0 0 2 * * *"`)
589604
- **O que faz:** `DELETE FROM tb_refresh_tokens WHERE expiry_date < NOW()`
605+
- **Lock distribuído:** ShedLock garante execução em apenas uma instância (`lockAtLeastFor = "30m"`, `lockAtMostFor = "1h"`)
590606
- **Por quê:** Tokens expirados são deletados ao serem usados (via `validate()`), mas tokens nunca reutilizados acumulam no banco.
591607

592608
### LoanService.markOverdue()
@@ -611,8 +627,8 @@ Marca como `OVERDUE` empréstimos com `status = WAITING_RETURN` e `dueDate < hoj
611627

612628
## 🔮 Próximos Passos
613629

614-
- [ ] **Rate limiting** — Bucket4j ou Resilience4j
615-
- [ ] **OpenTelemetry** — Tracing distribuído
630+
- [x] **Rate limiting** — Bucket4j ou Resilience4j
631+
- [x] **OpenTelemetry** — Tracing distribuído
616632
- [ ] **Deploy em cloud** — AWS ECS ou Render
617633
- [ ] **HATEOAS** — Hypermedia links
618634
- [ ] **WebSockets** — Notificações real-time de devolução

‎readme_pdf.md‎

Lines changed: 62 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -18,25 +18,25 @@ Upload de imagens de capa com AWS S3
1818

1919
## Índice
2020

21-
- [Visão Geral](#-visão-geral)
22-
- [Requisitos](#-requisitos)
23-
- [Quick Start](#-quick-start)
24-
- [Modo Desenvolvimento](#-modo-desenvolvimento-recomendado-para-avaliação)
25-
- [Modo Produção](#-modo-produção-simulado)
26-
- [Variáveis de Ambiente](#-variáveis-de-ambiente)
27-
- [Problema que Resolve](#-problema-que-este-projeto-resolve)
28-
- [Stack Tecnológica](#-stack-tecnológica)
29-
- [Arquitetura](#-arquitetura)
30-
- [Decisões Arquiteturais](#-decisões-arquiteturais)
31-
- [Observabilidade](#-observabilidade)
32-
- [Estratégia de Testes](#-estratégia-de-testes)
33-
- [Endpoints Principais](#-endpoints-principais)
34-
- [Upload de Imagens (AWS S3)](#-upload-de-imagens-aws-s3)
35-
- [Agendamentos (Scheduled Jobs)](#-agendamentos-scheduled-jobs)
36-
- [Métricas do Projeto](#-métricas-do-projeto)
37-
- [Próximos Passos](#-próximos-passos)
38-
- [Screenshots](#-screenshots)
39-
- [Contribuições](#-como-contribuir)
21+
- [Visão Geral](#visão-geral)
22+
- [Requisitos](#requisitos)
23+
- [Quick Start](#quick-start)
24+
- [Modo Desenvolvimento](#modo-desenvolvimento-recomendado-para-avaliação)
25+
- [Modo Produção](#modo-produção-simulado)
26+
- [Variáveis de Ambiente](#variáveis-de-ambiente)
27+
- [Problema que Resolve](#problema-que-este-projeto-resolve)
28+
- [Stack Tecnológica](#stack-tecnológica)
29+
- [Arquitetura](#arquitetura)
30+
- [Decisões Arquiteturais](#decisões-arquiteturais)
31+
- [Observabilidade](#observabilidade)
32+
- [Estratégia de Testes](#estratégia-de-testes)
33+
- [Endpoints Principais](#endpoints-principais)
34+
- [Upload de Imagens (AWS S3)](#upload-de-imagens-aws-s3)
35+
- [Agendamentos (Scheduled Jobs)](#agendamentos-scheduled-jobs)
36+
- [Métricas do Projeto](#métricas-do-projeto)
37+
- [Próximos Passos](#próximos-passos)
38+
- [Screenshots](#screenshots)
39+
- [Contribuições](#como-contribuir)
4040
- [Autor](#autor)
4141

4242
---
@@ -257,6 +257,11 @@ Uma biblioteca precisa:
257257
- **Micrometer** (abstração de métricas)
258258
- **Prometheus** (coleta de métricas, scrape a cada 10s)
259259
- **Grafana** (dashboards provisionados automaticamente)
260+
- **OpenTelemetry + Zipkin** (tracing distribuído com traceId nos logs)
261+
262+
### Resiliência
263+
- **Resilience4j** (Circuit Breaker + Retry para integrações externas)
264+
- **ShedLock** (lock distribuído para scheduled jobs)
260265

261266
### Testes
262267
- **Testcontainers** (PostgreSQL real em testes de integração)
@@ -410,6 +415,16 @@ Request → Controller → Service → [Cache Hit? → Return]
410415

411416
**Benefício:** Código relacionado fica junto; cada pacote é praticamente auto-contido.
412417

418+
### ✔ Spring Events para desacoplamento de domínios
419+
**Por quê:** Preparação para separação futura em microservices sem introduzir Kafka prematuramente.
420+
421+
**Benefício:** Domínios se comunicam via eventos internos (`ApplicationEventPublisher`) em vez de injeção direta de repositórios entre pacotes. Troca futura por Kafka/RabbitMQ requer mudança mínima.
422+
423+
### ✔ Resilience4j em integrações externas
424+
**Por quê:** Proteger o monolito contra falhas de serviços externos (S3) e preparar os pontos de integração para extração futura.
425+
426+
**Benefício:** Circuit Breaker evita cascata de falhas; Retry com backoff trata falhas transitórias. Padrão já estabelecido para quando LoanService precisar chamar BookService via HTTP.
427+
413428
---
414429

415430
## Observabilidade
@@ -493,46 +508,46 @@ Relatório HTML: `build/reports/jacoco/test/html/index.html`
493508
### Autenticação
494509
| Método | Endpoint | Descrição | Auth |
495510
|--------|----------|-----------|------|
496-
| POST | `/auth/login` | Login — retorna access + refresh token | ❌ |
497-
| POST | `/auth/refresh` | Renova access token (token rotation) | ❌ |
498-
| POST | `/auth/logout` | Invalida o refresh token | ❌ |
511+
| POST | `/auth/login` | Login — retorna access + refresh token | X |
512+
| POST | `/auth/refresh` | Renova access token (token rotation) | X |
513+
| POST | `/auth/logout` | Invalida o refresh token | X |
499514

500515
### Livros
501516
| Método | Endpoint | Descrição | Auth |
502517
|--------|----------|-----------|------|
503-
| GET | `/api/v1/books` | Lista livros paginado (com cache Redis) | ✅ |
504-
| GET | `/api/v1/books/{id}` | Busca por ID (com cache Redis) | ✅ |
505-
| POST | `/api/v1/books` | Cria livro | ✅ |
506-
| DELETE | `/api/v1/books/{id}` | Remove livro | 🔐 ADMIN |
507-
| POST | `/api/v1/books/{id}/picture` | Upload de imagem de capa (S3) | ✅ |
518+
| GET | `/api/v1/books` | Lista livros paginado (com cache Redis) | ✔ |
519+
| GET | `/api/v1/books/{id}` | Busca por ID (com cache Redis) | ✔ |
520+
| POST | `/api/v1/books` | Cria livro | ✔ |
521+
| DELETE | `/api/v1/books/{id}` | Remove livro | ADMIN |
522+
| POST | `/api/v1/books/{id}/picture` | Upload de imagem de capa (S3) | ✔ |
508523

509524
### Autores
510525
| Método | Endpoint | Descrição | Auth |
511526
|--------|----------|-----------|------|
512-
| GET | `/api/v1/authors` | Lista autores paginado | ✅ |
513-
| GET | `/api/v1/authors/{id}` | Busca por ID | ✅ |
514-
| POST | `/api/v1/authors` | Cria autor | ✅ |
515-
| DELETE | `/api/v1/authors/{id}` | Remove autor | 🔐 ADMIN |
527+
| GET | `/api/v1/authors` | Lista autores paginado | ✔ |
528+
| GET | `/api/v1/authors/{id}` | Busca por ID | ✔ |
529+
| POST | `/api/v1/authors` | Cria autor | ✔ |
530+
| DELETE | `/api/v1/authors/{id}` | Remove autor | ADMIN |
516531

517532
### Categorias
518533
| Método | Endpoint | Descrição | Auth |
519534
|--------|----------|-----------|------|
520-
| GET | `/api/v1/categories` | Lista categorias paginado | ✅ |
521-
| GET | `/api/v1/categories/{id}` | Busca por ID | ✅ |
522-
| POST | `/api/v1/categories` | Cria categoria | 🔐 ADMIN |
523-
| DELETE | `/api/v1/categories/{id}` | Remove categoria | 🔐 ADMIN |
535+
| GET | `/api/v1/categories` | Lista categorias paginado | ✔ |
536+
| GET | `/api/v1/categories/{id}` | Busca por ID | ✔ |
537+
| POST | `/api/v1/categories` | Cria categoria | ADMIN |
538+
| DELETE | `/api/v1/categories/{id}` | Remove categoria | ADMIN |
524539

525540
### Empréstimos
526541
| Método | Endpoint | Descrição | Auth |
527542
|--------|----------|-----------|------|
528-
| POST | `/api/v1/loans` | Cria empréstimo | ✅ |
529-
| GET | `/api/v1/loans/{id}` | Busca por ID (apenas dono ou ADMIN) | ✅ |
530-
| GET | `/api/v1/loans/me` | Lista meus empréstimos | ✅ |
531-
| GET | `/api/v1/loans` | Lista todos os empréstimos | 🔐 ADMIN |
532-
| GET | `/api/v1/loans/user/{userId}` | Lista empréstimos por usuário | 🔐 ADMIN |
533-
| GET | `/api/v1/loans/overdue` | Lista empréstimos vencidos | 🔐 ADMIN |
534-
| PATCH | `/api/v1/loans/{id}/return` | Registra devolução | ✅ |
535-
| PATCH | `/api/v1/loans/{id}/cancel` | Cancela empréstimo | ✅ |
543+
| POST | `/api/v1/loans` | Cria empréstimo | ✔ |
544+
| GET | `/api/v1/loans/{id}` | Busca por ID (apenas dono ou ADMIN) | ✔ |
545+
| GET | `/api/v1/loans/me` | Lista meus empréstimos | ✔ |
546+
| GET | `/api/v1/loans` | Lista todos os empréstimos | ADMIN |
547+
| GET | `/api/v1/loans/user/{userId}` | Lista empréstimos por usuário | ADMIN |
548+
| GET | `/api/v1/loans/overdue` | Lista empréstimos vencidos | ADMIN |
549+
| PATCH | `/api/v1/loans/{id}/return` | Registra devolução | ✔ |
550+
| PATCH | `/api/v1/loans/{id}/cancel` | Cancela empréstimo | ✔ |
536551

537552
**Documentação interativa (profile dev):** http://localhost:8080/swagger-ui/index.html
538553

@@ -579,6 +594,8 @@ Limpa automaticamente refresh tokens expirados do banco de dados.
579594

580595
- **Frequência:** Todo dia às 02:00 AM (`cron = "0 0 2 * * *"`)
581596
- **O que faz:** `DELETE FROM tb_refresh_tokens WHERE expiry_date < NOW()`
597+
- **Lock distribuído:** ShedLock garante execução em apenas uma instância (`lockAtLeastFor = "30m"`, `lockAtMostFor = "1h"`)
598+
582599
- **Por quê:** Tokens expirados são deletados ao serem usados (via `validate()`), mas tokens nunca reutilizados acumulam no banco.
583600

584601
### LoanService.markOverdue()
@@ -603,8 +620,8 @@ Marca como `OVERDUE` empréstimos com `status = WAITING_RETURN` e `dueDate < hoj
603620

604621
## Próximos Passos
605622

606-
- [ ] **Rate limiting** — Bucket4j ou Resilience4j
607-
- [ ] **OpenTelemetry** — Tracing distribuído
623+
- [x] **Rate limiting** — Bucket4j ou Resilience4j
624+
- [x] **OpenTelemetry** — Tracing distribuído
608625
- [ ] **Deploy em cloud** — AWS ECS ou Render
609626
- [ ] **HATEOAS** — Hypermedia links
610627
- [ ] **WebSockets** — Notificações real-time de devolução

0 commit comments

Comments
 (0)