Imported from xandroalmeida/my-prompts (
engenharira-software/agents/rhhub/AGENTS.md). Install upstream withnpx 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/**erhhub-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 emrhhub-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:
fetchnativo viaBaseService(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 usamvn -DskipTests packageemrhhub-toth/.github/workflows/build.yml). -
Testes: poucos testes unitários (3 arquivos em
core/modelecore/usecase). -
Convenções: controllers no BFF, regras em use cases, contratos de repositório em
core/repository, implementação emjooq.
4) Arquitetura e organização do código
-
Backend:
-
Camada de entrada HTTP:
http(boot) +bff(controllers/interceptors/handlers). -
Camada de negócio:
core/usecasecom regras de domínio e orquestração. -
Camada de domínio:
core/modele microtypes. -
Camada de acesso a dados: interfaces em
core/repository; implementações emjooq. -
Camada de integrações:
external(AWS, Feign, metabase, etc.) edelivery(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.tscom 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.tse especializados por módulo (src/views/**/**_service.ts). -
Estado em
src/state/**e Pinia emsrc/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
fetchemrhhub-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.tserhhub-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-UDIenviado no login/refresh e demais requests (rhhub-web/src/services/use_auth.ts,rhhub-web/src/services/base_service.ts). -
Erros no frontend:
-
BaseServiceretornastatusCode+data; em403redireciona para rotaForbidden(rhhub-web/src/services/base_service.ts). -
Paginação:
-
Existem tipos
Pageable/ResultPageemrhhub-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.productione mapeamento hardcoded emuse_tenant(rhhub-web/.env,rhhub-web/.env.production,rhhub-web/src/composables/use_tenant.ts). -
Backend usa perfis
application*.ymle 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.tschamaGET /maat/mat0008/{clienteId}/remessas. -
Endpoint backend:
rhhub-toth/bff/portal/src/main/java/br/com/rhhub/portal/toth/bff/portal/mat0008/Mat0008Controller.javacom@GetMapping("/remessas")em@RequestMapping("/maat/mat0008/{clienteId}"). -
Exemplo concreto 2 (auth):
-
Chamada frontend:
rhhub-web/src/services/use_auth.tschamaPOST /auth/login. -
Endpoint backend:
rhhub-toth/bff/portal/src/main/java/br/com/rhhub/portal/toth/bff/portal/AuthController.javacom@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), masPedidoEmpresaControllernã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 emPedidoEmpresaController. -
Front
mat0007_servicechama/cargas-saldos,/saldos,/cancelamento,/situacao/cancelaveis(rhhub-web/src/views/maat/mat0007/mat0007_service.ts), mas backendMat0007Controllerhoje expõe apenasGET /maat/mat0007/{clienteId}/beneficios. -
Front
mat0008_servicechama/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-initestá 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(DBalelo_espelho, porta5432) (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:runno 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
Dockerfilepara empacotarhttp/target/http-*.jarcom agente New Relic (rhhub-toth/Dockerfile). -
Existe compose apenas para simulador SFTP em
rhhub-toth/connect-sim/docker-compose.yml(porta2222). -
Não existe
docker-compose.ymlna 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.ymleapplication-local.yml(logging.level.*). -
Monitoramento:
-
Backend usa agente New Relic via
-javaagentnorhhub-toth/Dockerfilee config emrhhub-toth/newrelic/newrelic.yml. -
Frontend injeta
newrelic-snippet.jsapenas em PROD (rhhub-web/index.html,rhhub-web/public/newrelic-snippet.js). -
Frontend nomeia interações de rota via
newrelic.interaction()emrhhub-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
RequestInforequest-scoped (rhhub-toth/bff/common/src/main/java/br/com/rhhub/portal/toth/bff/common/components/RequestInfo.java), mas sem uso claro para preencherrequestId/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.ymleapplication-local.yml). -
Migrações:
-
Flyway ativo (
spring.flyway.enabled: true) com scripts emrhhub-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
@AcessoRequeridoaplicada 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
clienteIdpor escopo de audiência (maat/horus) emClientIdConverter. -
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.ymle snippet frontend (rhhub-web/public/newrelic-snippet.js). -
chave privada em
rhhub-toth/connect-sim/keys/app. -
X-UDIenviado pelo frontend, mas sem uso claro no backend para validação/amarração do refresh token. -
LoginUsecasepossuiTODOpara validar origem do refresh token e atualmente persisteuserAgent/originIpvazios (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 emexternal/**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.tsourhhub-web/src/services/**. -
Rota em
rhhub-web/src/views/**/router.ts+ registro emrhhub-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/javaecore/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 declienteId, 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.loge exceções tratadas porGlobalExceptionHandler. -
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-simquando 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-composecompleto para FE+BE+Postgres+dependências locais. -
Média: padronizar rastreabilidade com request-id efetivo em todo request logado.
