Pular para conteúdo

0017 — Adota xadm-comum-web: dedup da infra web da casa

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-08-07 · Decidido em: 2026-08-07

Contexto. Adotar a xadm-mensageria (0016) arrasta transitivamente a xadm-comum-web, que duplica infra que o Integrador tinha local desde antes da extração das libs da casa (o app predata a extração). No boot o contexto falhava com NonUniqueBeanException: UnifiedErrorResponseProcessor (ambos @Replaces(Hateoas)), HealthController (/health), VersaoInfo (InfoSource). É a Fase 1 da iniciativa libs+contrato aplicada ao Integrador — o app passa a consumir a infra web compartilhada em vez de espelhá-la.

Decisão.

  • Adotar a lib, não isolar. As 4 classes locais (ProblemDetail, UnifiedErrorResponseProcessor, HealthController, VersaoInfo) eram verbatim idênticas às da lib (só pacote/javadoc diferiam) — removidas; imports repointados para br.com.xadm.comum.web.*. Preterido: @Replaces app-side pra neutralizar a colisão — deixaria duas cópias divergindo; a colisão é sinal de que o app deve consumir a lib.
  • Não migrar o que não colide/tem overlap. Os handlers/exceptions app-specific (GlobalExceptionHandler, ServerException/UnauthorizedException) não têm equivalente na lib (conjunto diferente: a lib tem BadRequest/NotFound/Conflict/Forbidden) — ficam locais, só repoint do ProblemDetail. Regra: mesmo nome ≠ mesmo corpo — caracterizar antes de deduplicar.
  • SentryInitializer: evoluir a lib, não regredir. O da lib 0.1.0 divergiu (não tinha a tag cliente multi-tenant nem o skip dev/test que o app usa). Em vez de adotar o divergente (regressão de observabilidade), a xadm-comum-web subiu para 0.2.0 com paridade; o app pina 0.2.0 direto (Gradle resolve acima do transitivo 0.1.0 da mensageria — sem re-release dela). Pendência (lib): os 3 casos de tag cliente do antigo SentryInitializerTest do app devem virar teste de regressão no repo xadm-commons (o app não os tem mais — sem eles, uma mudança futura da lib derruba a tag em silêncio para todos os apps).
  • Guarda de model imutável no GlobalViewModel. O ViewModelProcessor do app roda em todo render e fazia model.put(...); a tela /admin/mensageria da lib devolve um model imutável (Map.of) → UnsupportedOperationException → 500. Corrigido: muta in-place e, se o model for imutável, refaz numa cópia mutável e a substitui (setModel). Armadilha reusável (qualquer app que adote uma view de lib com ViewModelProcessor global).

Consequências. ./gradlew check sobe o contexto com a xadm-mensageria no classpath sem colisão; /health ({status, versao}) e os corpos RFC-7807 seguem idênticos (a suíte existente é a rede, sem mudar asserção — prova de paridade). Consumo por versão: correção na casa chega ao app por bump.

Fora de escopo: a xadm-comum-web em si (repo xadm-commons); adotar xadm-seguranca (o fetcher de sessão local do 003 já basta para o gate da tela, ver 0016). Revisto: a xadm-seguranca foi adotada depois — ver 0018. E os handlers app-specific (ServerExceptionHandler/UnauthorizedExceptionHandler) que este DR manteve locais foram dropados no 0019: a comum-web 0.5.0 passou a logar no UnifiedErrorResponseProcessor, então as exceções viram PortadoraDeProblema e a lib renderiza o corpo (sem handler dedicado).