Serviço backend de alto desempenho e resiliência que automatiza integralmente o ciclo de vida de contratos de locação residencial: cadastra a locação, orquestra a geração do contrato, envia para assinatura eletrônica na PandaDoc, acompanha cada etapa por webhooks assíncronos com idempotência estrita e dispara sozinho as ações pós-assinatura (ativação da locação, agendamento de vistoria, emissão da primeira cobrança e notificações simuladas).
Propósito do repositório: projeto de estudo de engenharia de software pragmática com Kotlin, Spring Boot, PostgreSQL, Apache Kafka e Docker.
As regras de negócio canônicas (R1 a R10) residem emdocs/plano-de-negocio.md, e o desenho de engenharia emdocs/arquitetura-tecnica.md. Decisões de design posteriores ao guia ficam registradas emdocs/adr/. As diretrizes de desenvolvimento e governança estão emAGENTS.mdedocs/agents/. Utilize exclusivamente dados fictícios (R10).
- Regras de Negócio Fundamentais (R1 a R10)
- Pilha Tecnológica Fixada
- Arquitetura e Fluxo Orientado a Eventos
- Ciclo de Vida do Contrato (Máquina de Estados)
- Coleção Bruno: Demonstração Interativa por Jornadas
- Catálogo de Endpoints e Problem Details (RFC 9457)
- Executando o Ambiente Local
- Variáveis de Ambiente e Configuração
- Preparando a PandaDoc (Checklist do Dia 1)
- Estratégia e Pirâmide de Testes (347 Testes)
- Estrutura do Projeto e Decisões Arquiteturais (ADRs)
- Resiliência, Operação e Troubleshooting
Important
Precedência Canônica: As regras R1 a R10 (docs/plano-de-negocio.md §8)
constituem os invariantes absolutos de negócio da aplicação e prevalecem rigorosamente sobre qualquer ADR, princípio de
design ou detalhe de infraestrutura.
A stack técnica é estritamente fixada e controlada via Version Catalog (gradle/libs.versions.toml) e BOM gerenciado:
| Tecnologia ou Área | Versão / Configuração | Papel e Justificativa de Engenharia |
|---|---|---|
| Linguagem | Kotlin 2.4.21 |
Null-safety nativa, sealed classes exaustivas e imutabilidade de domínio. |
| Plataforma / JVM | Java 25 LTS (Eclipse Temurin) |
Toolchain fixada, compilação moderna e execução de alta performance. |
| Framework Base | Spring Boot 4.1.1 |
Spring Framework 7.0.7, Jackson 3 e inicialização otimizada sem open classes. |
| Persistência Relacional | PostgreSQL 18.6 |
Spring Data JDBC e JdbcClient (SQL explícito, sem sobrecarga de JPA/Hibernate). Ver Diagrama ER. |
| Mensageria Distribuída | Apache Kafka 4.3.1 (KRaft) |
Broker em modo KRaft (sem ZooKeeper) e biblioteca cliente kafka-clients 4.2. |
| Automação de Build | Gradle 9.8.1 |
Build determinístico, checagem de warnings (-Werror) e geração de app.jar. |
| Testes de Integração | Testcontainers 2.0.5 (2.x) |
Subida real de instâncias de PostgreSQL e Kafka para validação rigorosa. |
| Mocking de APIs Externas | WireMock 3.13.2 (ADR-014) |
Isolamento completo da API da PandaDoc com testes de rate limit e resiliência. |
| Arquitetura Estática | ArchUnit 1.5.1 (ADR-014) |
Validação automatizada contínua das 16 regras do monólito modular hexagonal. |
| Containers | Docker / Compose v5+ | Ambientes padronizados para desenvolvimento local e pipelines de CI. |
O sistema foi concebido como um monólito modular hexagonal composto por quatro módulos de fronteiras bem delimitadas
(shared, lease, contract, notification):
- Fase Prévia Síncrona (
lease): O ciclo inicia emPOST /api/v1/leases, que valida as regras estruturais e de dados pessoais (R2, R10) e cria a locação residencial em estadoDRAFT. Por ser uma operação atômica de cadastro cadastral sem integrações externas, ela é persistida diretamente no PostgreSQL sem emitir eventos de mensageria. - Ponto de Partida Contratual & Fronteira Modular (
contract → lease): A chamadaPOST /api/v1/leases/{id}/contractsverifica a unicidade (R1) e consome a porta de leituraLeaseLookupPort(implementada pela ponteLeaseLookupAdapter) para compor os signatários. O agregadoContracté persistido emDRAFTjuntamente com o eventoContractRequestedna tabelaoutbox_eventsem uma única transação ACID, devolvendoHTTP 202 Acceptedde imediato. - Orquestração Assíncrona com Provedor Externo: Chamadas de rede externas síncronas são terminantemente proibidas
nas requisições do usuário. O
OutboxRelaydescarrega os eventos no Kafka KRaft e oOrchestratorConsumerrealiza as chamadas REST com a PandaDoc de forma assíncrona, controlando janelas de taxa de requisição (rate limiting). - Ingestão Segura de Webhooks (Transactional Inbox - R7): O endpoint
/webhooks/pandadocvalida o HMAC-SHA256 sobre bytes brutos em tempo constante e persiste o corpo integral bruto emwebhook_inbox+outbox_events, respondendoHTTP 200 OKrápido (< 30ms). OProviderEventsConsumerconsome cada item com deduplicação estrita (R6) e aplica as transições de estado (R5). - Gatilhos Pós-Assinatura Reativos (R8) e Notificações: Quando o contrato atinge o estado terminal
COMPLETED, o eventoContractCompletedé publicado no Kafka. OPostSignatureConsumerdisparaRunPostSignatureActions, que aciona a portaLeaseActivationPortpara transicionar a locação paraACTIVEno módulolease, além de registrar a vistoria e a 1ª fatura. Paralelamente, oNotificationConsumerregistra o envio simulado de alertas aos signatários.
flowchart TD
subgraph Cliente["Cliente / Web Browser"]
ReqLease["1. POST /api/v1/leases"]
ReqContract["3. POST /api/v1/leases/{id}/contracts"]
end
subgraph ModLease["Módulo Lease"]
UCRegLease["RegisterLease (Use Case)"]
AggLease["Aggregate Lease<br/>(DRAFT / ACTIVE)"]
UCActLease["ActivateLease (Use Case)"]
end
subgraph ModContract["Módulo Contract"]
UCReqContract["RequestContract (Use Case)"]
BridgeLookup["LeaseLookupPort (Ponte)"]
AggContract["Aggregate Contract<br/>(DRAFT a COMPLETED)"]
Orchestrator["OrchestratorConsumer"]
WebHookRecv["POST /webhooks/pandadoc<br/>(ReceiveProviderWebhook)"]
ProviderConsumer["ProviderEventsConsumer"]
AppProvider["ProcessProviderWebhookItem<br/>& ApplyProviderUpdate"]
PostSigConsumer["PostSignatureConsumer"]
RunPostSig["RunPostSignatureActions<br/>(Regra R8)"]
BridgeActivation["LeaseActivationPort (Ponte)"]
end
subgraph ModShared["Módulo Shared (Transversal)"]
OutboxTable[("outbox_events")]
InboxTable[("webhook_inbox")]
Relay["OutboxRelay (@Scheduled)"]
end
subgraph ModNotif["Módulo Notification"]
NotifConsumer["NotificationConsumer"]
NotifLog[("notifications_log<br/>(Simulado)")]
end
subgraph Broker["Apache Kafka (KRaft)"]
TopicContract["locasign.contract.events.v1"]
TopicWebhooks["locasign.pandadoc.webhooks.v1"]
end
subgraph Externo["Provedor PandaDoc"]
PandaDocAPI["PandaDoc REST API"]
end
%% 1. Cadastro de Locação
ReqLease -->|1 . Cria Locação| UCRegLease
UCRegLease -->|2 . Persiste DRAFT| AggLease
%% 2. Solicitação de Contrato & Ponte
ReqContract -->|3 . Solicita Contrato| UCReqContract
UCReqContract -.->|4 . Consulta Snapshot| BridgeLookup
BridgeLookup -.->|Lê Dados| AggLease
UCReqContract -->|5 . ACID: Salva DRAFT| AggContract
UCReqContract -->|5 . Grava ContractRequested| OutboxTable
UCReqContract -.->|6 . Resposta Rápida 202 Accepted| Cliente
%% 3. Outbox Relay & Orquestração PandaDoc
Relay -->|7 . Polling Outbox| OutboxTable
Relay -->|8 . Publica ContractRequested| TopicContract
TopicContract -->|9 . Consome Evento| Orchestrator
Orchestrator -->|10 . REST POST /documents & send| PandaDocAPI
%% 4. Webhooks, Inbox e Transições
PandaDocAPI -.->|11 . Webhook HTTPS com HMAC| WebHookRecv
WebHookRecv -->|12 . Grava Bruto no Inbox| InboxTable
WebHookRecv -->|12 . Grava no Outbox| OutboxTable
WebHookRecv -.->|13 . Resposta Rápida 200 OK| PandaDocAPI
Relay -->|14 . Publica WebhookReceived| TopicWebhooks
TopicWebhooks -->|15 . Consome Webhook| ProviderConsumer
ProviderConsumer -->|16 . Processa Item| AppProvider
AppProvider -->|17 . Transiciona Status| AggContract
%% 5. Conclusão, Pós-Assinatura (R8) e Notificações
AggContract -.->|18 . Emite ContractCompleted| OutboxTable
Relay -->|19 . Publica ContractCompleted| TopicContract
TopicContract -->|20 . Reação Pós-Assinatura| PostSigConsumer
PostSigConsumer -->|21 . Executa Ações R8| RunPostSig
RunPostSig -->|22 . Ativa Locação| BridgeActivation
BridgeActivation -->|23 . Dispara Ativação| UCActLease
UCActLease -->|24 . Status ACTIVE| AggLease
TopicContract -->|20 . Consome Evento| NotifConsumer
NotifConsumer -->|21 . Registra Log Notificação| NotifLog
O ciclo de vida do contrato residencial é governado pelo agregado Contract e pela política determinística centralizada
ContractTransitionPolicy (Kotlin puro, sem dependências de infraestrutura). Conforme a regra R5, o status nunca
regride e estados terminais são absolutamente imutáveis.
[DRAFT] ➔ [GENERATED] ➔ [SENT] ➔ [VIEWED] ➔ [PARTIALLY_SIGNED] ➔ [COMPLETED] 🏆
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
[CANCELLED] [CANCELLED] [CANCELLED, [CANCELLED, [CANCELLED,
DECLINED, DECLINED, DECLINED,
EXPIRED] EXPIRED] EXPIRED]
stateDiagram-v2
classDef draft fill: #E2E8F0, stroke: #64748B, stroke-width: 2px, color: #0F172A
classDef inProgress fill: #DBEAFE, stroke: #2563EB, stroke-width: 2px, color: #1E40AF
classDef completed fill: #DCFCE7, stroke: #16A34A, stroke-width: 3px, color: #166534
classDef terminal fill: #FEE2E2, stroke: #DC2626, stroke-width: 2px, color: #991B1B
[*] --> DRAFT: POST /contracts<br/>(202 Accepted)
DRAFT --> GENERATED: Documento criado<br/>na PandaDoc
GENERATED --> SENT: Enviado aos<br/>signatários
SENT --> VIEWED: Locatário visualizou<br/>documento
VIEWED --> PARTIALLY_SIGNED: Locatário assinou<br/>(Ordem 1)
PARTIALLY_SIGNED --> COMPLETED: Imobiliária assinou<br/>(Ordem 2)
DRAFT --> CANCELLED: Cancelamento com<br/>motivo (R9)
GENERATED --> CANCELLED: Cancelamento com<br/>motivo (R9)
SENT --> CANCELLED: Cancelamento com<br/>motivo (R9)
VIEWED --> CANCELLED: Cancelamento com<br/>motivo (R9)
PARTIALLY_SIGNED --> CANCELLED: Cancelamento com<br/>motivo (R9)
SENT --> DECLINED: Signatário recusou<br/>assinar
VIEWED --> DECLINED: Signatário recusou<br/>assinar
PARTIALLY_SIGNED --> DECLINED: Signatário recusou<br/>assinar
SENT --> EXPIRED: Prazo de 7 dias<br/>esgotado (R4)
VIEWED --> EXPIRED: Prazo de 7 dias<br/>esgotado (R4)
PARTIALLY_SIGNED --> EXPIRED: Prazo de 7 dias<br/>esgotado (R4)
COMPLETED --> [*]: Dispara Ações<br/>Pós-Assinatura (R8)
CANCELLED --> [*]: Histórico auditado<br/>(permite v2 - R1, R9)
DECLINED --> [*]: Histórico auditado<br/>(permite v2 - R1, R9)
EXPIRED --> [*]: Histórico auditado<br/>(permite v2 - R1, R9)
class DRAFT draft
class GENERATED,SENT,VIEWED,PARTIALLY_SIGNED inProgress
class COMPLETED completed
class CANCELLED,DECLINED,EXPIRED terminal
| Categoria | Estados | Comportamento e Regras de Negócio |
|---|---|---|
| Em Andamento | DRAFT, GENERATED, SENT, VIEWED, PARTIALLY_SIGNED |
Aceitam transições estritamente progressivas (avanço monotônico de progresso ordinal). |
| Terminais Estritos | COMPLETED 🏆CANCELLED 🚫DECLINED ❌EXPIRED ⏰ |
Estritamente imutáveis (R5): Não aceitam nenhuma mutação subsequente. Tentativas via API devolvem HTTP 409 Conflict (/problems/contract-final). |
| Eventos Tardios | Webhooks desordenados na rede (ex: VIEWED após COMPLETED) |
Tratamento Defensivo: Em vez de quebrar a transação com erro 500 ou regredir o status, a política sinaliza IGNORED_TRANSITION. O evento é registrado na auditoria mas o estado final permanece intacto. |
// ContractTransitionPolicy.kt — Decisão Determinística sem Frameworks
object ContractTransitionPolicy {
fun decide(current: ContractStatus, target: ContractStatus): TransitionDecision = when {
current == target -> TransitionDecision.NoOp
current.isFinal -> TransitionDecision.Reject("Contrato em estado final ($current) é imutável.")
target.isFinal || target.progress > current.progress -> TransitionDecision.Apply
else -> TransitionDecision.Reject("A transição $current -> $target regrediria o status.")
}
}Note
Saltos para Frente (ADR-010): Como a PandaDoc não garante a retransmissão de webhooks intermediários perdidos na
internet, transições diretas com saltos (ex.: de SENT diretamente para COMPLETED) são formalmente autorizadas para
garantir a convergência do estado real.
O repositório disponibiliza uma coleção completa e pronta para importação no cliente de APIs Bruno (padrão
OpenCollection
YAML) em http/demonstracao-do-plano-de-negocio:
http/demonstracao-do-plano-de-negocio/
├── opencollection.yml # Metadados e variáveis globais da coleção
├── collection.bru # Documentação unificada para o cliente Bruno
├── README.md # Guia detalhado de uso e roteiro da coleção
├── environments/
│ └── Local.yml # Ambiente Local (baseUrl: http://localhost:8080)
├── 01-fluxo-feliz/ # 📁 01 - Fluxo Feliz (Ponta a Ponta) (8 requisições)
├── 02-cenarios-de-erro/ # 📁 02 - Cenários de Erro e Regras de Negócio (13 requisições)
├── 03-operacao-e-resiliencia/ # 📁 03 - Operação e Resiliência (6 requisições)
└── 04-infraestrutura-e-observabilidade/ # 📁 04 - Infraestrutura e Observabilidade (4 requisições)
- Organização Visual em 4 Pastas: Permite testar o fluxo feliz do início ao fim sem poluição de erros, ou auditar exclusivamente a robustez defensiva da aplicação.
- Automação Pós-Resposta de Variáveis: As requisições de sucesso (
01-cadastra-locacao,03-solicita-contratoe08-solicita-nova-versao) extraem e definem automaticamente as variáveisleaseIdecontractId, permitindo execução contínua sem cópia e cola manual. - Isolamento de Erros: As requisições de teste de erro
404utilizam identificadores nulos deliberados (00000000-0000-0000-0000-000000000000), garantindo que não sobrescrevam as variáveis do contrato em teste. - Comandos cURL Embutidos: Cada um dos 31 arquivos
.ymlpossui um blocodocscom o comandocurlequivalente pronto para execução direta no terminal.
Consulte o Guia Completo da Coleção para o roteiro detalhado.
| Método | Caminho | Perfil de Acesso | Descrição e Status Esperado |
|---|---|---|---|
POST |
/api/v1/leases |
Público | Cadastra nova locação residencial (201 Created). |
GET |
/api/v1/leases/{id} |
Público | Consulta detalhes da locação e contrato ativo (200 OK). |
POST |
/api/v1/leases/{id}/contracts |
Público | Solicita confecção do contrato ou nova versão (202 Accepted). |
GET |
/api/v1/contracts/{id} |
Público | Consulta status atual, signatários e prazos (200 OK). |
GET |
/api/v1/contracts/{id}/history |
Público | Linha do tempo cronológica com trilha de auditoria (200 OK). |
POST |
/api/v1/contracts/{id}/cancel |
Público | Cancelamento formal de contrato com justificativa (202 Accepted). |
POST |
/webhooks/pandadoc |
PandaDoc | Ingestão de webhooks assinado via HMAC-SHA256 (200 OK). |
POST |
/api/v1/contracts/{id}/reconcile |
Operador (X-Admin-Token) |
Força reconciliação manual com a API da PandaDoc (202 Accepted). |
POST |
/api/v1/admin/dead-letters/{topic}/replay |
Operador (X-Admin-Token) |
Reenvia mensagens represadas na DLT para o tópico original (200 OK). |
GET |
/actuator/health |
Público | Health check consolidado de banco e broker Kafka (200 OK). |
GET |
/actuator/metrics/locasign.* |
Público | Métricas dimensionais Micrometer de transições e webhooks (200 OK). |
GET |
/v3/api-docs / /swagger-ui.html |
Público | Especificação OpenAPI 3.1 e documentação interativa Swagger. |
🔍 Clique aqui para expandir o Diagrama de Sequência Ponta a Ponta e a Legenda das Regras por Endpoint
sequenceDiagram
autonumber
actor Corretor as "👤 Corretor / Cliente"
participant API as "⚡ LocaSign API"
participant DB as "🐘 PostgreSQL 18"
participant Kafka as "📨 Apache Kafka"
participant PandaDoc as "🐼 PandaDoc Cloud"
actor Locatario as "📱 Locatário (Tenant)"
actor Imobiliaria as "🏢 Imobiliária (Agency)"
actor Operador as "🛠️ Operador (Admin)"
%% 1. Cadastro de Locação
Note over Corretor, DB: 1. Cadastro da Locação (Regras R2, R10)
Corretor ->> API: POST /api/v1/leases (Dados cadastrais)
API ->> API: Validação Bean Validation e Cpf mod 11 (R2, R10)
API ->> DB: INSERT INTO leases (status: DRAFT)
API -->> Corretor: HTTP 201 Created (Location: /leases/:id)
Corretor ->> API: GET /api/v1/leases/:id
API -->> Corretor: HTTP 200 OK (Dados da locação com CPF mascarado)
%% 2. Solicitação de Contrato
Note over Corretor, Kafka: 2. Solicitação de Contrato (Regras R1, R2, R3, R4)
Corretor ->> API: POST /api/v1/leases/:id/contracts
API ->> API: Valida Unicidade R1 - rejeita se já existir contrato ativo (409)
API ->> DB: ACID Commit - contracts (DRAFT) + outbox_events
API -->> Corretor: HTTP 202 Accepted (Location: /contracts/:id)
Corretor ->> API: GET /api/v1/contracts/:id (Acompanhamento)
API -->> Corretor: HTTP 200 OK (status: DRAFT, prazo de 7 dias - R4)
%% 3. Orquestração Assíncrona & PandaDoc
Note over DB, PandaDoc: 3. Outbox Relay e Envio PandaDoc (Regras R3, R4)
DB ->> API: OutboxRelay - SELECT FOR UPDATE SKIP LOCKED
API ->> Kafka: Publica ContractRequested (locasign.contract.events.v1)
Kafka ->> API: OrchestratorConsumer consome evento (markProcessed)
API ->> PandaDoc: POST /public/v1/documents (Signing Order 1: Locatario, 2: Imobiliaria)
PandaDoc -->> API: Retorna doc_id (doc_123)
API ->> PandaDoc: POST /public/v1/documents/doc_123/send
PandaDoc -->> API: HTTP 200 OK (Contrato enviado)
API ->> DB: UPDATE contracts (status: SENT)
%% 4. Webhooks de Assinatura & Arquivamento de PDF
Note over PandaDoc, DB: 4. Assinatura Sequencial, Webhook Seguro e Arquivamento (Regras R3, R5, R6, R7)
PandaDoc ->> Locatario: Notificação de assinatura por e-mail/SMS (Ordem 1)
Locatario ->> PandaDoc: Assina digitalmente o documento
PandaDoc ->> API: POST /webhooks/pandadoc (document_state_changed)
API ->> API: Valida assinatura HMAC-SHA256 em tempo constante (R7)
API ->> DB: INSERT INTO webhook_inbox + outbox_events (HTTP 200 rápido)
DB ->> API: OutboxRelay publica ProviderWebhookReceived
Kafka ->> API: ProviderEventsConsumer processa evento com deduplicação (R6)
API ->> DB: UPDATE contracts (status: PARTIALLY_SIGNED)
PandaDoc ->> Imobiliaria: Libera link de assinatura para Imobiliária (Ordem 2)
Imobiliaria ->> PandaDoc: Assina digitalmente o documento
PandaDoc ->> API: POST /webhooks/pandadoc (status: document.completed)
API ->> API: Valida HMAC-SHA256 em tempo constante
API ->> DB: Grava no Inbox e atualiza contracts (status: COMPLETED)
PandaDoc ->> API: POST /webhooks/pandadoc (event: document_completed_pdf_ready)
API ->> DB: Grava no Inbox e Outbox (HTTP 200 rápido)
Kafka ->> API: ProviderEventsConsumer consome e aciona ArchiveSignedDocument (R6)
API ->> PandaDoc: GET /public/v1/documents/:id/pdf (Download protegido)
API ->> DB: Salva PDF no storage e registra caminho em contracts
%% 5. Gatilho Pós-Assinatura
Note over API, DB: 5. Gatilho Pós-Assinatura Reativo (Regra R8)
API ->> Kafka: Publica ContractCompleted (locasign.contract.events.v1)
Kafka ->> API: PostSignatureConsumer consome ContractCompleted (R6)
API ->> DB: Ativa Locação (leases status: ACTIVE)
API ->> DB: Agenda Vistoria de Entrada do Imóvel (post_signature_actions)
API ->> DB: Registra Primeira Fatura e Cobrança (post_signature_actions)
Kafka ->> API: NotificationConsumer consome ContractCompleted (R6)
API ->> DB: Registra notificação aos envolvidos (notifications_log)
%% 6. Operações, Histórico & Resiliência
Note over Operador, Kafka: 6. Auditoria, Cancelamento e Resiliência (Regras R1, R5, R6, R9)
Corretor ->> API: GET /api/v1/contracts/:id/history (Auditoria imutável)
API -->> Corretor: HTTP 200 OK (Trilha cronológica com eventos tardios ignorados)
Corretor ->> API: POST /api/v1/contracts/:id/cancel (motivo: Dados incorretos - R9)
API ->> DB: Transiciona para CANCELLED e desocupa locação para v2 (R1, R9)
API -->> Corretor: HTTP 202 Accepted
Kafka ->> API: DocumentAnnulmentConsumer consome ContractCancelled (R6)
API ->> PandaDoc: PATCH /public/v1/documents/:id/status (anula o documento, fora da requisição)
Operador ->> API: POST /api/v1/contracts/:id/reconcile (Header: X-Admin-Token)
API ->> PandaDoc: GET /public/v1/documents/:id (Reconciliação manual de status)
API -->> Operador: HTTP 202 Accepted
Operador ->> API: POST /api/v1/admin/dead-letters/:topic/replay (Header: X-Admin-Token)
API ->> Kafka: Reenvia mensagens represadas na DLT ao tópico original (R6)
API -->> Operador: HTTP 200 OK
| Método | Caminho | Regras de Negócio Aplicadas | Comportamento de Domínio e Validações | Respostas Típicas (RFC 9457) |
|---|---|---|---|---|
POST |
/api/v1/leases |
R2, R10 | Cadastra a locação residencial em estado DRAFT. Valida Bean Validation (@NotNull, @NotBlank, @Positive) e invariantes no value object Cpf (algoritmo módulo 11), Email (RFC 5322), aluguel positivo e prazo de 1 a 120 meses. Garante mascaramento estrito de dados pessoais em logs e DTOs. |
201 Created (Location: /leases/{id})400 Bad Request (campos ausentes)422 Unprocessable (/problems/business-rule) |
GET |
/api/v1/leases/{id} |
R1, R10 | Consulta os dados cadastrais da locação e projeta o contrato ativo associado (se houver). Comprova que no máximo 1 contrato não terminal pode coexistir na mesma locação. Retorna os dados com o CPF do locatário mascarado (Cpf.masked()). |
200 OK404 Not Found (/problems/not-found) |
POST |
/api/v1/leases/{id}/contracts |
R1, R2, R3, R4 | Ponto de partida do ciclo de vida contratual. Consulta a locação e valida a Regra R1: se já existir contrato não terminal, rejeita imediatamente com HTTP 409 Conflict. Agregado nasce em DRAFT, define prazo de 7 dias (R4), estabelece a ordem sequencial de assinatura (R3) e grava atomicamente o estado e o evento em outbox_events no PostgreSQL 18. |
202 Accepted (Location: /contracts/{id})404 Not Found409 Conflict (/problems/active-contract-exists) |
GET |
/api/v1/contracts/{id} |
R3, R4, R5, R10 | Consulta o estado atual da máquina de estados (DRAFT a COMPLETED), os signatários associados com suas respectivas ordens de assinatura (1: Locatário, 2: Imobiliária) e o prazo limite de expiração calculado pelo BusinessClock. Dados pessoais saem estritamente mascarados. |
200 OK404 Not Found (/problems/not-found) |
GET |
/api/v1/contracts/{id}/history |
R5, R10 | Linha do tempo cronológica com trilha de auditoria completa e imutável. Exibe cada transição de status com timestamp exato, autor/origem (API, PANDADOC, JOB) e registra eventuais webhooks atrasados ignorados pela política defensiva (IGNORED_TRANSITION). |
200 OK404 Not Found (/problems/not-found) |
POST |
/api/v1/contracts/{id}/cancel |
R1, R5, R9 | Cancelamento formal de contrato com justificativa obrigatória (reason). Se o contrato já estiver em estado final (COMPLETED, CANCELLED, DECLINED, EXPIRED), rejeita com HTTP 409 Conflict (R5). Se válido, transiciona para CANCELLED, preserva o histórico e desocupa a locação, viabilizando a emissão de uma nova versão v2/v3 (R1, R9). |
202 Accepted400 Bad Request (sem motivo)404 Not Found409 Conflict (/problems/contract-final) |
POST |
/webhooks/pandadoc |
R3, R5, R6, R7, R8 | Receptor HTTP assíncrono para eventos da PandaDoc. Valida a assinatura HMAC-SHA256 sobre bytes brutos em tempo constante (MessageDigest.isEqual). Se inválido, rejeita prontamente com HTTP 401 Unauthorized. Se válido, grava bruto atômico em webhook_inbox + outbox_events e devolve HTTP 200 OK rápido (< 30ms - R7). O consumidor Kafka subsequente deduplica a mensagem (R6), aplica a transição segura (R5) e aciona o pós-assinatura em COMPLETED (R8). |
200 OK (gravação imediata)401 Unauthorized (HMAC inválido) |
POST |
/api/v1/contracts/{id}/reconcile |
R3, R5, R6 | Rota de suporte operacional protegida pelo header X-Admin-Token. Força consulta síncrona à API da PandaDoc (GET /public/v1/documents/{id}) para reconciliar o status do contrato caso algum webhook tenha sido perdido na internet. Aplica a transição via ContractTransitionPolicy com idempotência estrita. |
202 Accepted401 Unauthorized (token inválido/ausente)404 Not Found (/problems/not-found) |
POST |
/api/v1/admin/dead-letters/{topic}/replay |
R6 | Rota de resiliência protegida por X-Admin-Token. Permite ao operador reenviar mensagens represadas no tópico de dead-letter (.dlt) de volta ao tópico Kafka original. Graças à idempotência estrita (R6), mensagens que já haviam sido processadas com sucesso são descartadas pelos consumidores sem efeitos colaterais duplicados. |
200 OK401 Unauthorized (token ausente/inválido)400 Bad Request (tópico inválido) |
Em conformidade com a RFC 9457 (Problem Details for HTTP APIs), todas as falhas de validação e violações de regras de negócio retornam payloads JSON padronizados:
| Código HTTP | Tipo (type) |
Descrição da Ocorrência |
|---|---|---|
400 Bad Request |
/problems/validation |
Campos obrigatórios ausentes, parâmetros malformados ou justificativa vazia. |
401 Unauthorized |
— | Assinatura HMAC-SHA256 ausente ou inválida no webhook (nunca devolve 410). |
403 Forbidden |
— | Tentativa de acesso a rotas operacionais sem o cabeçalho X-Admin-Token. |
404 Not Found |
/problems/not-found |
Locação, contrato ou tópico de mensageria inexistente no sistema. |
409 Conflict |
/problems/active-contract-exists |
Tentativa de solicitar novo contrato para locação com contrato ativo (R1). |
409 Conflict |
/problems/contract-final |
Tentativa de alterar contrato em estado terminal imutável (R5). |
413 Too Large |
/problems/payload-too-large |
Corpo do webhook acima do limite (1 MiB por padrão), recusado antes do HMAC. |
422 Unprocessable |
/problems/business-rule |
Violação de regra de domínio (CPF inválido, data passada, aluguel <= 0) (R2). |
- Java 25 LTS instalado no sistema operacional (Eclipse Temurin recomendado).
- Docker ou Rancher Desktop ativo (com suporte a Docker Compose).
Este é o modo mais ágil para desenvolvimento diário:
# 1. Sobe PostgreSQL 18.6 e Apache Kafka 4.3.1 (KRaft) em segundo plano
docker compose up -d
# 2. Define as variáveis recomendadas para o ambiente local (webhook e token admin)
$env:PANDADOC_WEBHOOK_SHARED_KEY = "segredo"
$env:ADMIN_TOKEN = "abc123"
# 3. Executa a aplicação Spring Boot com perfil local
.\gradlew.bat bootRun --args="--spring.profiles.active=local"# 1. Sobe PostgreSQL 18.6 e Apache Kafka 4.3.1 (KRaft) em segundo plano
docker compose up -d
# 2. Define as variáveis recomendadas para o ambiente local (webhook e token admin)
export PANDADOC_WEBHOOK_SHARED_KEY="segredo"
export ADMIN_TOKEN="abc123"
# 3. Executa a aplicação Spring Boot com perfil local
./gradlew bootRun --args='--spring.profiles.active=local'Acesse no navegador:
- Health Check: http://localhost:8080/actuator/health (banco e Kafka devem
estar
UP) - Swagger UI: http://localhost:8080/swagger-ui.html
Para subir todos os componentes (banco, broker e a aplicação compilada em container) em um único comando:
docker compose --profile app up -d --buildO arquivo compose.yml possui perfis modulares adicionais:
-
Kafka UI (Interface Web de Mensageria):
docker compose --profile tools up -d
Acesse o painel em http://localhost:8081 para inspecionar tópicos, offsets e mensagens de DLT.
-
Túnel HTTPS Público para Webhooks (Cloudflare):
docker compose --profile tunnel up -d docker compose logs tunnel # exibe a URL pública HTTPS gerada -
Encerrando os Containers com Segurança:
# Encerra os serviços mantendo os volumes persistidos docker compose down # CUIDADO: o comando abaixo apaga banco de dados e mensagens do Kafka! # docker compose down -v
Para validar localmente todo o ciclo de vida sem depender de uma conta externa da PandaDoc, utilize o roteiro abaixo com a coleção Bruno ou scripts de terminal:
- Ative o ambiente
Localno canto superior direito do Bruno (definebaseUrl = http://localhost:8080). - Execute
01 - Cadastra a locação: responde201 Createde armazena oleaseId. - Execute
02 - Consulta a locação: status inicialREGISTERED. - Execute
03 - Solicita o contrato: responde202 Acceptede armazena ocontractId(status inicialDRAFT). - Execute
04 - Acompanha o status: confirma contrato emDRAFT.
Por segurança e conformidade (Regra R7 e ADR-012), a aplicação exige validação criptográfica HMAC no endpoint
/webhooks/pandadoc?signature=....
- Pelo Bruno: abra
01 - Fluxo Feliz / 06 - Webhook PandaDoc, altere no JSON"status": "document.viewed"para"status": "document.completed"e defina"has_completed": true. O script Pre-Request calcula o HMAC automaticamente utilizando a chave configurada (segredo) e envia com sucesso (200 OK). - Pelo PowerShell no Windows (Script Rápido):
$contractId = "COLE_AQUI_O_CONTRACT_ID" $secret = "segredo" $payload = @" [{"event":"document_state_changed","data":{"id":"doc_123","date_modified":"$([System.DateTime]::UtcNow.ToString('o'))","status":"document.completed","metadata":{"contract_id":"$contractId"},"recipients":[{"email":"maria@example.com","role":"Locatario","has_completed":true},{"email":"alianca@example.com","role":"Imobiliaria","has_completed":true}]}}] "@ $bytes = [System.Text.Encoding]::UTF8.GetBytes($payload) $hmac = New-Object System.Security.Cryptography.HMACSHA256 $hmac.Key = [System.Text.Encoding]::UTF8.GetBytes($secret) $sig = [System.BitConverter]::ToString($hmac.ComputeHash($bytes)).Replace('-', '').ToLower() Invoke-RestMethod -Uri "http://localhost:8080/webhooks/pandadoc?signature=$sig" -Method Post -Headers @{"Content-Type"="application/json";"X-PandaDoc-Webhook-Event-Id"=[System.Guid]::NewGuid().ToString()} -Body $bytes
- Pelo Bash no Linux/WSL2:
PANDADOC_WEBHOOK_SHARED_KEY=segredo bash scripts/send-signed-webhook.sh scripts/samples/document-state-changed.json
- Contrato: ao consultar novamente (
GET /api/v1/contracts/{{contractId}}), o status estaráCOMPLETED. - Histórico:
GET /api/v1/contracts/{{contractId}}/historyexibe toda a trilha de auditoria gravada. - Locação Ativada:
GET /api/v1/leases/{{leaseId}}mostra que o status da locação mudou sozinho paraACTIVE, comactivatedAtdevidamente preenchido. - Efeitos Pós-Assinatura: as tabelas
post_signature_actions(vistoria e primeira cobrança) enotifications_logsão registradas de forma assíncrona via consumidores Kafka.
Defina as variáveis no ambiente ou em um arquivo .env na raiz do projeto (nunca versione o .env). A aplicação inicia
mesmo sem as credenciais da PandaDoc, permitindo testar cadastros e o fluxo local:
| Variável | Padrão | Descrição e Impacto |
|---|---|---|
DB_URL |
jdbc:postgresql://localhost:5432/locasign |
URL de conexão JDBC ao PostgreSQL. |
DB_USERNAME / DB_PASSWORD |
locasign / locasign |
Credenciais do banco de dados relacional. |
DB_POOL_MAX_SIZE |
10 |
Máximo de conexões do pool Hikari; só aumente após teste de carga. |
DB_POOL_CONNECTION_TIMEOUT |
5000 |
Espera máxima por uma conexão do pool, em ms; mantém o webhook rápido (R7). |
KAFKA_BOOTSTRAP_SERVERS |
localhost:9092 |
Endereço do broker Kafka (kafka:29092 na rede interna do Compose). |
KAFKA_MAX_POLL_RECORDS |
10 |
Máximo de registros retornados por poll no consumer Kafka (RL1). |
PANDADOC_API_KEY |
(vazio) | Chave de API da PandaDoc (utilize chave sandbox no desenvolvimento). |
PANDADOC_TEMPLATE_ID |
(vazio) | UUID do modelo de contrato configurado no painel da PandaDoc. |
PANDADOC_WEBHOOK_SHARED_KEY |
(vazio) | Chave secreta compartilhada para cálculo do HMAC-SHA256 dos webhooks. |
PANDADOC_WEBHOOK_MAX_BODY_BYTES |
1048576 |
Tamanho máximo do corpo do webhook em bytes (1 MiB); acima disso, HTTP 413. |
PANDADOC_BASE_URL |
https://api.pandadoc.com/public/v1 |
URL base da API REST da PandaDoc. |
PANDADOC_DOWNLOAD_ENABLED |
false |
Se true, realiza o download do PDF assinado (exige chave de produção). |
PANDADOC_RATE_LIMIT_PER_MINUTE |
8 |
Limite defensivo por minuto (abaixo do teto de 10/min do sandbox). |
AGENCY_SIGNER_NAME / _EMAIL |
(vazio) | Nome e e-mail padrão do representante da imobiliária (signatário 2). |
CONTRACT_SIGNATURE_DEADLINE_DAYS |
7 |
Prazo limite em dias para conclusão das assinaturas (R4). |
RECONCILIATION_STALE_AFTER |
10m |
Tempo sem atualização antes de a reconciliação consultar o provedor (RC4). |
APP_TIMEZONE |
America/Sao_Paulo |
Fuso horário canônico para cálculos de datas de vigência e prazos. |
ADMIN_TOKEN |
(vazio) | Habilita operações sensíveis via cabeçalho X-Admin-Token. Vazio desabilita (403). |
ARCHIVE_DIRECTORY |
./data/signed-documents |
Diretório local de armazenamento dos documentos PDFs concluídos. |
- Crie uma conta na PandaDoc (o plano de avaliação inclui sandbox e produção).
- Em Settings → API and Integrations, ative o acesso à API e gere uma chave de Sandbox.
- Crie um modelo de contrato com os papéis de signatário exatos:
LocatarioeImobiliaria. - Configure no modelo os tokens de preenchimento automático:
[Locatario.Nome],[Locatario.CPF],[Imovel.Endereco],[Aluguel.Valor],[Locacao.Inicio],[Locacao.Prazo].
- Copie o UUID do modelo e configure na variável
PANDADOC_TEMPLATE_ID. - Suba o túnel HTTPS (
docker compose --profile tunnel up -d, confira a URL gerada comdocker compose logs tunnel) e registre o webhook para a URLhttps://<url-do-tunel>/webhooks/pandadoccom os eventos:document_state_changed,recipient_completed,document_creation_failed,document_completed_pdf_readyedocument_deleted.
- Copie a chave secreta compartilhada e preencha em
PANDADOC_WEBHOOK_SHARED_KEY.
A aplicação conta com uma esteira rigorosa de 347 testes automatizados com 100% de aprovação, cobrindo todas as camadas da arquitetura hexagonal (formalizada no ADR-014):
▲
/ \
/E2E\ LocaSignE2EIT (2 testes)
/-----\ Fluxo assíncrono completo: REST ➔ Outbox ➔ Kafka ➔ WireMock ➔ Webhook ➔ Ativação
/ IT \
/---------\ Testcontainers (PostgreSQL 18.6 + Kafka 4.3.1 KRaft) (34 testes)
/ WireMock \ Persistência real, índices parciais (R1), outbox, inbox e idempotência (R6, R7, R8)
/-------------\
/ ArchUnit \ WireMock e Infra PandaDoc (25 testes)
/-----------------\ Contratos REST, resiliência HTTP/1.1, rate limit 429, backoff e tradução de erros
/ Web Slices \
/---------------------\ HexagonalArchitectureTest (13 testes)
/ Unitários de Domínio\ Fronteiras arquiteturais do AGENTS.md §5 (docs/agents/arquitetura.md §6)
/_________________________\
@WebMvcTest com MockMvcTester (38 testes)
Validação Jakarta Bean Validation, RFC 9457 Problem Details e segurança do operador
Domínio, Casos de Uso com Fakes e Utilitários (229 testes)
Agregados Contract e Lease, políticas de transição (R5), value objects, mappers e consumers
# Executa apenas os testes rápidos que não necessitam de Docker (unitários, fatias web, wiremock e archunit)
.\gradlew.bat test --tests "*Test" --console=plain # Windows PowerShell
./gradlew test --tests "*Test" --console=plain # Linux / macOS
# Executa todos os testes (incluindo testes de integração *IT via Testcontainers; exige Docker ativo)
.\gradlew.bat test --console=plain # Windows PowerShell
./gradlew test --console=plain # Linux / macOS
# Gate completo de qualidade da CI (compilação sem warnings, testes e geração do build/libs/app.jar)
.\gradlew.bat build --console=plain # Windows PowerShell
./gradlew build --console=plain # Linux / macOSsrc/main/kotlin/br/com/locasign/
├── shared/ # Transversal: value objects (Cpf, Email, Money), inbox, outbox, DLT, Time
├── lease/ # Módulo de locação (cadastro, consulta e ciclo de vida de Lease)
├── contract/ # Núcleo de contratos: agregado Contract, políticas de transição, PandaDoc, jobs
└── notification/ # Módulo assíncrono de notificações simuladas aos envolvidos
Cada módulo organiza-se rigorosamente nas camadas:
interfaces (web/kafka) ➔ app (casos de uso, portas de entrada HTTP e portas de saída) ➔ domain (Kotlin puro) ➔
infra (adapters).
As decisões de engenharia que expandem ou refinam o guia inicial estão formalizadas em docs/adr/:
- ADR-011: Transações Curtas com TransactionRunner —
Elimina conexões de banco presas durante chamadas lentas à PandaDoc, abandonando
@Transactionale AOP em favor de blocos funcionais explícitos. - ADR-012: Comportamentos Confirmados da PandaDoc — Validação HMAC sobre bytes brutos do corpo, download protegido de PDF assinado e retentativas defensivas em códigos HTTP 409/404.
- ADR-013: Ajustes de Implementação do LocaSign — Localização
canônica de Value Objects, colunas para backoff de outbox e proteção de endpoints operacionais com
X-Admin-Token. - ADR-014: Estratégia e Ferramentas de Testes — Padronização
das convenções
*Teste*IT, incorporação do WireMock para isolamento HTTP e ArchUnit para garantia estática da arquitetura. - ADR-015: Convenção de KDoc Estruturado — Padrão unificado de documentação técnica em português brasileiro destacando comportamento técnico e responsabilidade única (SRP).
- ADR-016: Anulação Assíncrona do Documento na
PandaDoc —
Remove a chamada síncrona à PandaDoc do
POST /cancele do job de expiração, delegando ao novo consumerDocumentAnnulmentConsumervia eventos do outbox com retentativa e DLT. - ADR-017: Ajustes de Resiliência e Performance da
Auditoria —
Blindagem de limites de entrada (
Moneye DTOs), teto de 1 MiB no webhook (HTTP 413 pré-inbox), abort imediato do lote do outbox em falha de broker, índices parciais para housekeeping (Migration V2), taxa de limitador diferenciada por chamador e reconciliação sem falsas regressões.
O broker Kafka no Docker Compose anuncia dois endereços distintos:
PLAINTEXT://kafka:29092— exclusivo para comunicação entre containers (como o containerapp).EXTERNAL://localhost:9092— exclusivo para clientes no host da máquina física (sua IDE ou./gradlew bootRun).
Se a aplicação inicia mas não consegue produzir ou consumir mensagens, certifique-se de queKAFKA_BOOTSTRAP_SERVERSestá apontando para o endereço correto de acordo com onde a aplicação está rodando.
Se o receptor /webhooks/pandadoc responder sistematicamente 401 Unauthorized, verifique:
- Se a variável
PANDADOC_WEBHOOK_SHARED_KEYestá preenchida exatamente com a mesma chave gerada no painel da PandaDoc. - A validação HMAC-SHA256 é calculada estritamente sobre os bytes brutos do corpo HTTP recebido; qualquer alteração ou formatação intermediária invalida o hash.
- Utilize o script de teste local:
PANDADOC_WEBHOOK_SHARED_KEY=segredo scripts/send-signed-webhook.sh scripts/samples/document-state-changed.json
Mensagens com falhas irrecuperáveis após 3 tentativas com backoff exponencial são enviadas automaticamente para
<topico>.dlt. Para reprocessá-las após a resolução do problema:
curl -X POST "http://localhost:8080/api/v1/admin/dead-letters/locasign.contract.events.v1/replay" \
-H "X-Admin-Token: seu_token_configurado"Como todos os consumidores da aplicação são rigorosamente idempotentes (R6), a reexecução de mensagens da DLT nunca gera efeitos duplicados indesejados.