rhhub

Imported from xandroalmeida/my-prompts (engenharira-software/agents/rhhub/AGENTS.md). Install upstream with npx skills add xandroalmeida/my-prompts --skill rhhub. Copyright stays with the author.

1) Visão geral da plataforma

• O repositório reúne duas aplicações que compõem o portal RHhub: um frontend web (rhhub-web) e um backend monolítico (rhhub-toth).
• O backend expõe APIs HTTP para autenticação, operações de "Maat" (cliente/benefícios/pedidos) e "Horus" (operações administrativas), além de endpoints auxiliares (/cep, /aux/cnpj) e saúde/versionamento (/actuator/health, /version) (rhhub-toth/bff/portal/**, rhhub-toth/bff/common/**).
• O frontend organiza telas por módulos (src/views/maat/**, src/views/horus/**) e consome o backend por serviços TypeScript (src/services/**, src/views/**/**_service.ts).
• O objetivo inferível pelo código é suportar gestão de clientes, usuários, benefícios, pedidos/recargas, saldos e integrações operacionais com emissores e serviços externos.
• Responsabilidade principal do frontend: UX, roteamento, sessão do usuário e composição de chamadas HTTP (rhhub-web/src/router/index.ts, rhhub-web/src/services/base_service.ts, rhhub-web/src/services/use_auth.ts).
• Responsabilidade principal do backend: regras de negócio, segurança/autorização, persistência e integrações externas (rhhub-toth/core/**, rhhub-toth/jooq/**, rhhub-toth/external/**).

2) Mapa do repositório

• Estrutura essencial:

plataforma/
  AGENTS.md
  rhhub-web/
    src/
      router/ services/ views/ state/ store/ composables/ layouts/
    public/
    package.json
    vite.config.ts
    .env
    .env.production
  rhhub-toth/
    bff/        (api/common/portal)
    core/       (model/repository/service/usecase/exceptions/helper)
    jooq/
    external/
    flyway/
    http/
    delivery/
    shared/
    mcp/
    connect-sim/
    newrelic/
    pom.xml

• Frontend: código-fonte em rhhub-web/src/**.
• Frontend: configuração/build em rhhub-web/package.json, rhhub-web/vite.config.ts, rhhub-web/.env*.
• Frontend: pipeline em rhhub-web/.github/workflows/deploy-prd.yml.
• Backend: entrypoint em rhhub-toth/http/src/main/java/br/com/rhhub/portal/toth/http/RhhubTothApplication.java.
• Backend: controllers HTTP em rhhub-toth/bff/portal/src/main/java/** e rhhub-toth/bff/common/src/main/java/**.
• Backend: regras de negócio em rhhub-toth/core/usecase/**.
• Backend: persistência em rhhub-toth/jooq/src/main/java/** + migrações em rhhub-toth/flyway/src/main/resources/db/migrations/**.
• Backend: configuração de ambiente em rhhub-toth/shared/src/main/resources/application*.yml.
• Backend: pipelines em rhhub-toth/.github/workflows/build.yml.

3) Stack e tecnologias

• Frontend:

• Linguagem/framework: TypeScript + Vue 3 + Vite 5 (rhhub-web/package.json).

• UI e estado: PrimeVue, PrimeFlex, Pinia, Vue Router (rhhub-web/package.json).

• HTTP: fetch nativo via BaseService (rhhub-web/src/services/base_service.ts).

• Build/lint: yarn dev, yarn build*, yarn lint (rhhub-web/package.json).

• Testes: não há script de testes e não há arquivos de teste detectados no frontend.

• Convenções: telas por módulo em src/views/<dominio>/<codigo>/, serviços próximos da feature em *_service.ts.

• Backend:

• Linguagem/framework: Java 17 + Spring Boot 3.4.4 + Maven multi-módulo (rhhub-toth/pom.xml).

• Persistência: PostgreSQL + Flyway + jOOQ (rhhub-toth/shared/src/main/resources/application.yml, rhhub-toth/flyway/**, rhhub-toth/jooq/pom.xml).

• Integração: OpenFeign e AWS SDK v2 (rhhub-toth/external/src/main/java/**).

• Build/test: mvn package, mvn test (Maven padrão; workflow usa mvn -DskipTests package em rhhub-toth/.github/workflows/build.yml).

• Testes: poucos testes unitários (3 arquivos em core/model e core/usecase).

• Convenções: controllers no BFF, regras em use cases, contratos de repositório em core/repository, implementação em jooq.

4) Arquitetura e organização do código

• Backend:

• Camada de entrada HTTP: http (boot) + bff (controllers/interceptors/handlers).

• Camada de negócio: core/usecase com regras de domínio e orquestração.

• Camada de domínio: core/model e microtypes.

• Camada de acesso a dados: interfaces em core/repository; implementações em jooq.

• Camada de integrações: external (AWS, Feign, metabase, etc.) e delivery (jobs/rotas de integração).

• Padrão observável: arquitetura em camadas com separação tipo ports/adapters (interfaces no core e adapters em módulos externos).

• Frontend:

• Roteamento central em rhhub-web/src/router/index.ts com guardas de autenticação/autorização por sessão.

• Estrutura de UI em layouts (src/layouts/**) e telas por feature (src/views/**).

• Serviços HTTP centralizados em src/services/base_service.ts e especializados por módulo (src/views/**/**_service.ts).

• Estado em src/state/** e Pinia em src/store/index.ts.

• Regras de sessão/token em src/services/use_auth.ts.

• Onde ficam as regras de negócio:

• Regra central fica no backend (rhhub-toth/core/usecase/**).

• Frontend mantém regra de apresentação, fluxo de tela e orchestration de chamadas (rhhub-web/src/views/**, rhhub-web/src/services/**).

5) Integração Frontend ↔ Backend

• Protocolo de integração: REST/JSON sobre HTTP (frontend usa fetch em rhhub-web/src/services/base_service.ts).

• Base URL no frontend: definida por hostname em rhhub-web/src/composables/use_tenant.ts.

• Autenticação:

• Login: POST /auth/login.

• Refresh: PUT /auth/refresh.

• Logout: DELETE /auth/{refreshToken}.

• Evidências: rhhub-web/src/services/use_auth.ts e rhhub-toth/bff/portal/src/main/java/br/com/rhhub/portal/toth/bff/portal/AuthController.java.

• Headers relevantes:

• Authorization: Bearer <token> em chamadas autenticadas (rhhub-web/src/services/base_service.ts).

• X-UDI enviado no login/refresh e demais requests (rhhub-web/src/services/use_auth.ts, rhhub-web/src/services/base_service.ts).

• Erros no frontend:

• BaseService retorna statusCode + data; em 403 redireciona para rota Forbidden (rhhub-web/src/services/base_service.ts).

• Paginação:

• Existem tipos Pageable/ResultPage em rhhub-web/src/services/base_service.ts, mas não há padrão único imposto para todos os endpoints.

• Configuração de ambientes:

• Frontend usa .env/.env.production e mapeamento hardcoded em use_tenant (rhhub-web/.env, rhhub-web/.env.production, rhhub-web/src/composables/use_tenant.ts).

• Backend usa perfis application*.yml e import de Parameter Store AWS em local/dev (rhhub-toth/shared/src/main/resources/application.yml, rhhub-toth/shared/src/main/resources/application-local.yml).

• Exemplo concreto 1 (feature alinhada):

• Chamada frontend: rhhub-web/src/views/maat/mat0008/mat0008_service.ts chama GET /maat/mat0008/{clienteId}/remessas.

• Endpoint backend: rhhub-toth/bff/portal/src/main/java/br/com/rhhub/portal/toth/bff/portal/mat0008/Mat0008Controller.java com @GetMapping("/remessas") em @RequestMapping("/maat/mat0008/{clienteId}").

• Exemplo concreto 2 (auth):

• Chamada frontend: rhhub-web/src/services/use_auth.ts chama POST /auth/login.

• Endpoint backend: rhhub-toth/bff/portal/src/main/java/br/com/rhhub/portal/toth/bff/portal/AuthController.java com @PostMapping("/login") em @RequestMapping("/auth").

• Divergências FE/BE detectadas no código atual:

• Front chama GET /maat/{clienteId}/pedidosEmpresa/resumo (rhhub-web/src/services/pedido_service.ts), mas PedidoEmpresaController não expõe /resumo (rhhub-toth/bff/portal/src/main/java/br/com/rhhub/portal/toth/bff/portal/PedidoEmpresaController.java).

• Front usa upload em /maat/{clienteId}/pedidosEmpresa/{pedidoId}/arquivoSaldo (rhhub-web/src/views/maat/organizacao/pedidos/ImportarSaldoForm.vue), sem endpoint correspondente em PedidoEmpresaController.

• Front mat0007_service chama /cargas-saldos, /saldos, /cancelamento, /situacao/cancelaveis (rhhub-web/src/views/maat/mat0007/mat0007_service.ts), mas backend Mat0007Controller hoje expõe apenas GET /maat/mat0007/{clienteId}/beneficios.

• Front mat0008_service chama /maat/mat0008/{clienteId}/cartoes/* (rhhub-web/src/views/maat/mat0008/mat0008_service.ts), enquanto backend expõe cartões em /maat/cartoes/solicitacoes (rhhub-toth/bff/portal/src/main/java/br/com/rhhub/portal/toth/bff/portal/SolicitacaoCartaoController.java).

• Front possui rota /horus/hrs1001 (rhhub-web/src/views/horus/hrs1001/router.ts), sem controller equivalente no backend.

• Observação: hrsc001/upload-init está alinhado entre frontend e backend (rhhub-web/src/views/horus/hrs0018/hrs0018-ocorrencia.vue, rhhub-toth/bff/portal/src/main/java/br/com/rhhub/portal/toth/bff/portal/hrsc001/Hrsc001Controller.java).

6) Execução local (developer experience)

• Pré-requisitos:

• Java 17 e Maven Wrapper para backend (rhhub-toth/pom.xml, rhhub-toth/mvnw).

• Node.js (workflow usa 18.x) + Yarn para frontend (rhhub-web/.github/workflows/deploy-prd.yml, rhhub-web/package.json).

• PostgreSQL local para perfil local (DB alelo_espelho, porta 5432) (rhhub-toth/shared/src/main/resources/application-local.yml).

• Como rodar backend local:

• cd rhhub-toth

• ./mvnw -pl http -am spring-boot:run (ou .\mvnw.cmd -pl http -am spring-boot:run no Windows)

• Swagger: http://localhost:8080/swagger-ui/index.html (rhhub-toth/README.md).

• Como rodar frontend local:

• cd rhhub-web

• yarn

• yarn dev

• Dev server em http://localhost:3000 (rhhub-web/vite.config.ts).

• Como rodar testes:

• Backend: cd rhhub-toth && ./mvnw test.

• Frontend: não há script de teste definido em rhhub-web/package.json.

• Docker/compose:

• Backend possui Dockerfile para empacotar http/target/http-*.jar com agente New Relic (rhhub-toth/Dockerfile).

• Existe compose apenas para simulador SFTP em rhhub-toth/connect-sim/docker-compose.yml (porta 2222).

• Não existe docker-compose.yml na raiz para subir stack completa FE+BE+DB.

• Problemas comuns detectados:

• Falha de conexão com Postgres local (credenciais/DB esperados no application-local.yml).

• Dependência de AWS Parameter Store em perfil local (spring.config.import: aws-parameterstore:/local/toth/).

• Integrações S3/externas exigem credenciais AWS/configuração de buckets (rhhub-toth/external/aws/**, application.yml).

7) Observabilidade, logs e rastreabilidade

• Logging backend:

• Config em rhhub-toth/http/src/main/resources/logback-spring.xml.

• Console e rolling file em ./logs/toth.log.

• Pattern inclui campos de contexto como requestId, clienteId, userId, requestURI, duration.

• Nível de log:

• Ajustável em rhhub-toth/shared/src/main/resources/application.yml e application-local.yml (logging.level.*).

• Monitoramento:

• Backend usa agente New Relic via -javaagent no rhhub-toth/Dockerfile e config em rhhub-toth/newrelic/newrelic.yml.

• Frontend injeta newrelic-snippet.js apenas em PROD (rhhub-web/index.html, rhhub-web/public/newrelic-snippet.js).

• Frontend nomeia interações de rota via newrelic.interaction() em rhhub-web/src/router/index.ts.

• Lacuna de rastreabilidade:

• Não foi encontrado código preenchendo MDC (MDC.put) para os campos de correlação presentes no pattern de log.

• Existe RequestInfo request-scoped (rhhub-toth/bff/common/src/main/java/br/com/rhhub/portal/toth/bff/common/components/RequestInfo.java), mas sem uso claro para preencher requestId/origens no fluxo HTTP atual.

8) Persistência e integrações externas

• Banco de dados:

• PostgreSQL configurado por spring.datasource.* (rhhub-toth/shared/src/main/resources/application.yml e application-local.yml).

• Migrações:

• Flyway ativo (spring.flyway.enabled: true) com scripts em rhhub-toth/flyway/src/main/resources/db/migrations.

• Quantidade atual de migrações: 34 scripts.

• Acesso a dados:

• Contratos no core (rhhub-toth/core/repository/**).

• Implementações em jOOQ (rhhub-toth/jooq/src/main/java/**).

• Geração jOOQ via profile Maven jooq (rhhub-toth/jooq/pom.xml, rhhub-toth/jooq/jooq-config.xml).

• Integrações externas identificadas:

• AWS S3/presigned URL: rhhub-toth/external/src/main/java/br/com/rhhub/portal/toth/external/aws/**.

• OpenCEP: .../external/opencep/OpencepClient.java.

• OGT: .../external/coletador/ogt/OgtClient.java.

• CNPJ (CNPJA/CNPJWS): .../external/rfb/**.

• Metabase signed URL: .../external/metabase/BiServiceMetabase.java.

• MailerSend: adapter em .../external/mailersend/SendEmailServiceMailersend.java (com implementação comentada/TODO).

9) Segurança

• Autenticação:

• JWT emitido e validado no backend (rhhub-toth/bff/common/src/main/java/br/com/rhhub/portal/toth/bff/common/SecurityTokenComponentJWT.java, .../interceptor/SecurityInterceptor.java).

• Fluxo de login/refresh/logout em AuthController + LoginUsecase.

• Autorização:

• Anotação @AcessoRequerido aplicada em controllers (rhhub-toth/bff/portal/src/main/java/**).

• Enforcement via SecurityAspect (rhhub-toth/bff/common/src/main/java/br/com/rhhub/portal/toth/bff/common/seguranca/SecurityAspect.java).

• Validação de clienteId por escopo de audiência (maat/horus) em ClientIdConverter.

• Riscos evidentes encontrados:

• CORS aberto globalmente com allowedOrigins("*") (rhhub-toth/bff/common/src/main/java/br/com/rhhub/portal/toth/bff/common/interceptor/ConfigInterceptor.java).

• Segredos no repositório:

• token MailerSend em rhhub-toth/shared/src/main/resources/application.yml.

• license key New Relic em rhhub-toth/newrelic/newrelic.yml e snippet frontend (rhhub-web/public/newrelic-snippet.js).

• chave privada em rhhub-toth/connect-sim/keys/app.

• X-UDI enviado pelo frontend, mas sem uso claro no backend para validação/amarração do refresh token.

• LoginUsecase possui TODO para validar origem do refresh token e atualmente persiste userAgent/originIp vazios (rhhub-toth/core/usecase/src/main/java/br/com/rhhub/portal/toth/core/usecase/auth/LoginUsecase.java).

• Boas práticas recomendadas específicas:

• Mover todos os segredos para secret manager/variáveis de ambiente e remover do histórico Git.

• Restringir CORS por ambiente/domínio confiável.

• Implementar correlação de sessão/dispositivo real para refresh token usando cabeçalhos de origem.

• Tornar obrigatório teste de autorização para endpoints sensíveis (@AcessoRequerido + cenários de 401/403).

10) Como desenvolver com segurança neste código

• Onde colocar uma feature nova:

• Backend:

• Controller BFF em rhhub-toth/bff/portal/src/main/java/**.

• Request/response DTO no mesmo módulo BFF.

• Regra de negócio em rhhub-toth/core/usecase/**.

• Contrato de repositório em rhhub-toth/core/repository/**.

• Implementação em rhhub-toth/jooq/src/main/java/** (ou adapter em external/** se integração).

• Migração em rhhub-toth/flyway/src/main/resources/db/migrations/** se houver mudança de schema.

• Frontend:

• Tela/componente em rhhub-web/src/views/**.

• Serviço HTTP em rhhub-web/src/views/**/**_service.ts ou rhhub-web/src/services/**.

• Rota em rhhub-web/src/views/**/router.ts + registro em rhhub-web/src/router/index.ts.

• Fluxo recomendado request→banco→resposta:

• Front chama BaseService.

• BFF controller valida acesso/contexto e delega para use case.

• Use case aplica regra e usa repositório/interface.

• Adapter jOOQ executa persistência.

• BFF mapeia DTO de saída e retorna ao frontend.

• Onde adicionar testes:

• Backend unitário em core/model/src/test/java e core/usecase/src/test/java (padrão já existente).

• Recomendação: adicionar testes de controller/security para contratos críticos no BFF.

• Frontend: lacuna atual; recomendação de introduzir testes de serviço e de view crítica.

• Checklist de PR:

• Build backend e frontend passam.

• Lint frontend passa.

• Testes mínimos de regra e contrato adicionados/atualizados.

• Migrações Flyway revisadas e idempotentes.

• Endpoint novo aparece no Swagger local e está refletido no serviço frontend.

• Segurança revisada: @AcessoRequerido, validação de clienteId, sem segredos hardcoded.

11) Playbook de debugging

• Passos para investigar bug FE/BE:

• Reproduzir no frontend com tenant correto e usuário com acessos compatíveis (rhhub-web/src/composables/use_tenant.ts, rhhub-web/src/services/use_auth.ts).

• Verificar no DevTools a URL final chamada e headers (Authorization, X-UDI).

• Confirmar existência do endpoint no backend (controller + mapping) antes de depurar regra.

• Conferir guardas/autorização: token válido, audiência (aud), @AcessoRequerido, ClientIdConverter.

• Checar logs do backend em rhhub-toth/logs/toth.log e exceções tratadas por GlobalExceptionHandler.

• Validar dados persistidos e migração correspondente no Postgres/Flyway.

• Bugs de contrato FE/BE (muito comuns aqui):

• Comparar serviço frontend (*_service.ts) com controller backend (path + verbo + payload).

• Se divergente, alinhar no mesmo PR em ambos os lados e validar pelo Swagger.

• Bugs de upload/arquivos:

• Verificar endpoint de upload-init/presigned URL e bucket configurado (external/aws/s3/**).

• Validar credenciais AWS e configuração local da integração (incluindo connect-sim quando aplicável).

12) Lacunas e melhorias recomendadas

• Documentação faltante:

• rhhub-web/README.md é genérico (template Vue) e não descreve arquitetura/fluxos RHhub.

• rhhub-toth/README.md é mínimo e não cobre setup completo.

• Não há guia único oficial de integração FE/BE e contrato por módulo.

• Dívidas técnicas evidentes:

• Divergências reais entre serviços frontend e endpoints backend (mat0007, mat0008/cartões, pedidosEmpresa/resumo, upload arquivoSaldo, hrs1001).

• Cobertura de testes baixa no backend e inexistente no frontend.

• Segredos sensíveis versionados no repositório.

• CORS permissivo em produção por padrão de código.

• Campos de correlação em log sem preenchimento consistente de contexto.

• Melhorias de alto impacto (prioridade):

• Alta: estabelecer contrato único orientado a OpenAPI (geração/validação automática de cliente frontend).

• Alta: corrigir imediatamente gestão de segredos (rotate + secret manager + limpeza do histórico Git).

• Alta: fechar CORS por ambiente e adicionar validação de origem/dispositivo no refresh token.

• Alta: criar suíte mínima de testes de contrato (controllers BFF + serviços frontend críticos).

• Média: adicionar docker-compose completo para FE+BE+Postgres+dependências locais.

• Média: padronizar rastreabilidade com request-id efetivo em todo request logado.