Pular para conteúdo

ecosif-moviments — Release Notes e Impacto na Execução

Versão anterior: 0.6.00.x
Versão atual: 0.7.01.x

Este documento descreve as alterações entre a versão 0.6.00.x e a versão 0.7.01.x, em formato de release notes para o cliente, e as mudanças que afetam a execução e a operação do serviço.

1. Resumo executivo

Aspecto 0.6.00.x (antes) 0.7.01.x (atual)
Versão 0.6.00.202503251 0.7.01.202601280
Java 11 17
Spring Boot 2.4.2 2.7.18
JWT JJWT 0.9.1 JJWT 0.11.5 (HMAC 256 bits)
Documentação API Swagger 2.9.2 / Springfox SpringDoc OpenAPI 3.0
Variáveis de ambiente Nomes em minúsculas (ecosif_*) Nomes em MAIÚSCULAS (POSTGRES_*, ECOSIF_*)
Biblioteca partilhada ecosif-database 0.6.00.202503251 ecosif-database 0.7.01.202512010

A atualização exige reconfigurar as variáveis de ambiente e garantir que o context path (ex.: /ecosif-moviments) esteja alinhado com o API Gateway.

2. Novidades e melhorias (release notes para o cliente)

2.1 Segurança e stack

  • Migração para Java 17 e Spring Boot 2.7.18: atualização de runtime e framework para versões com suporte de longo prazo e correções de segurança.
  • JWT (JJWT 0.11.5): validação de tokens com HMAC SHA-256; mesma chave (AUTH_TOKEN_SECRET) que o ecosif-auth.
  • Dockerfile de produção: imagem multi-stage com Amazon Corretto 17 (Alpine), utilizador não-root, health check no Actuator e suporte opcional ao agente Datadog APM.
  • OAuth2 desativável: quando o client id está vazio, o fluxo OAuth2 não é registrado (comportamento alinhado ao ecosif-auth).

2.2 Funcionalidades

  • Documentação OpenAPI 3.0: substituição do Swagger 2 / Springfox por SpringDoc; documentação em /swagger-ui.html e especificação em /v3/api-docs.
  • Tratamento global de exceções: GlobalExceptionHandler para respostas de erro padronizadas.
  • Actuator e métricas: endpoints de health, info e Prometheus expostos para monitorização e orquestração.
  • Importação em lote (S3): integração com AWS S3 para ficheiros IPL (import-files, import-error, imported, import-report, purge); credenciais via variáveis ou IAM role.
  • Consolidação e encerramento: operações assíncronas para consolidação, abertura de mês e purging, com suporte à lib ecosif-database.

2.3 Base de dados e migrações

  • Flyway integrado: migrações opcionais via ECOSIF_FLYWAY_ENABLED; quando ativo, as alterações de schema são aplicadas na subida da aplicação.
  • Schema: entidades e evolução geridas em conjunto com a lib ecosif-database; em produção recomenda-se HIBERNATE_DDL_AUTO=validate.

2.4 Documentação e operação

  • Documentação reorganizada: pasta docs/ com documentos por público (technical, operational, functional) e pasta anotations/ com arquitetura, desenvolvimento, integradores e endpoints.
  • Guia AWS (ECS + API Gateway): documento específico para implantação na Amazon (docs/aws-ecs-api-gateway.md).
  • Logback: configuração por variável LOG_FORMAT (default ou json) para saída em texto ou JSON (LogstashEncoder).

3. Mudanças que afetam a execução do serviço

3.1 Variáveis de ambiente — ação obrigatória

Os nomes das variáveis passaram de minúsculas para MAIÚSCULAS. A aplicação (Spring) lê as variáveis em MAIÚSCULAS; o script de entrypoint do contentor pode ainda aceitar ecosif_port e ecosif_context para compatibilidade, mas recomenda-se usar as novas.

Tabela de equivalência (0.6.00.x → 0.7.01.x):

0.6.00.x (antigo) 0.7.01.x (atual) Observação
ecosif_port ECOSIF_MOVIMENTS_PORT Porta HTTP do serviço (ex.: 8080 ou 8082).
ecosif_context SERVER_SERVLET_CONTEXT_PATH Path da aplicação (ex.: /ecosif-moviments para API Gateway).
ecosif_db_server POSTGRES_HOST Host do PostgreSQL.
ecosif_db_port POSTGRES_PORT Porta do PostgreSQL (ex.: 5432).
ecosif_db_login POSTGRES_DB Nome da base de dados.
ecosif_db_user POSTGRES_USER Utilizador do banco (ex.: ecosif_moviments).
ecosif_db_password POSTGRES_PASSWORD Senha (usar repositório de segredos).
hibertenate_mode HIBERNATE_DDL_AUTO Em produção use validate; schema segue a lib ecosif-database / Flyway.
ecosif_flyway ECOSIF_FLYWAY_ENABLED true para aplicar migrações na subida; false para desativar.
auth_token_secret AUTH_TOKEN_SECRET Chave JWT (igual à do ecosif-auth).
token_expiration TOKEN_EXPIRATION Tempo de vida do token em ms (ex.: 86400000).
ecosif_cors ECOSIF_CORS Origens CORS permitidas (ex.: https://app.ecosif.banco.com.br).
auth2_clientid AUTH2_CLIENT_ID OAuth2 Google (opcional); se vazio, OAuth2 fica desativado.
auth2_secret AUTH2_SECRET OAuth2 Google (opcional).
ecosif_logshow ECOSIF_LOGSHOW Exibir SQL nos logs (ex.: false em prod).
ecosif_logmode_* ECOSIF_LOGMODE_ROOT, ECOSIF_LOGMODE_SPRING, etc. Níveis de log.
log_format LOG_FORMAT Nome do logback: default ou json.
swagger_enabled (removido) SpringDoc está sempre disponível.
(conforme uso) ECOSIF_ENVIRONMENT Identificador de ambiente (padrão: prod).

Variáveis de pool HikariCP: na versão atual estão com valores fixos no application.yml; não é necessário configurar ecosif_hk_*.

AWS S3 (importação em lote): AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_S3_BUCKET — manter conforme documentação operacional (pastas: import-files, import-error, imported, import-report, purge).

3.2 Context path e API Gateway

  • Na versão 0.6.00.x o path podia ser / ou outro via ecosif_context.
  • Na versão 0.7.01.x, para integrar com um API Gateway único (ex.: https://app.ecosif.banco.com.br/ecosif-moviments), é obrigatório definir:
  • SERVER_SERVLET_CONTEXT_PATH=/ecosif-moviments
  • O health check passa a ser: /ecosif-moviments/actuator/health (ou o path que configurou).
  • Exemplos de endpoints:
  • API de lançamentos/lotes: https://<domínio>/ecosif-moviments/api/...
  • Swagger UI: https://<domínio>/ecosif-moviments/swagger-ui.html
  • OpenAPI JSON: https://<domínio>/ecosif-moviments/v3/api-docs

3.3 Docker e imagem

  • Imagem base: Amazon Corretto 17 (Alpine) em vez de 11.
  • Entrypoint: o contentor usa conf/entrypoint.sh (porta e context path; opcionalmente Datadog APM com USEDATADOG=true).
  • Porta: configurável via ECOSIF_MOVIMENTS_PORT (ex.: 8080 ou 8082). O health check do Dockerfile usa variável de porta; em ambiente com context path, o ALB/API Gateway deve usar /<context-path>/actuator/health (ex.: /ecosif-moviments/actuator/health).

3.4 Dependência local (ecosif-database)

  • O build da aplicação requer o JAR ecosif-database-0.7.01.202512010.jar (ou versão compatível indicada no pom.xml) na pasta libs/.
  • Em ambiente de build (CI/CD ou Docker build), essa dependência deve estar disponível; em runtime apenas o JAR da aplicação é necessário.

4. Checklist de atualização (0.6.00.x → 0.7.01.x)

Status plataforma eCosif (ecosif-structure / develop): concluído.
Em deploy de cliente, revalidar CORS (URL do SPA), Flyway na primeira implantação e health/Swagger no ambiente alvo.

  • [x] Variáveis de ambiente: substituir todas as variáveis antigas (minúsculas) pelas novas (MAIÚSCULAS) na task definition, docker-compose ou ficheiro de configuração.
  • [x] Context path: definir SERVER_SERVLET_CONTEXT_PATH=/ecosif-moviments (ou o path acordado) se o serviço for exposto via API Gateway — stack usa ECOSIF_MOVIMENTS_CONTEXT_PATH / -Dserver.servlet.context-path.
  • [x] Health check: atualizar o path para /ecosif-moviments/actuator/health (ou o path correspondente) no ALB, API Gateway ou orquestrador — healthcheck do Compose alinhado.
  • [x] Flyway: ECOSIF_FLYWAY_ENABLED=true na stack; cliente deve fazer backup e confirmar permissões do utilizador da base na primeira implantação.
  • [x] CORS: ECOSIF_CORS configurável na stack (ex.: localhost/dev); cliente deve confirmar a URL exata do frontend em homolog/prod.
  • [x] JWT: a mesma AUTH_TOKEN_SECRET deve ser usada no ecosif-auth e no ecosif-moviments (e nos demais serviços que validam o JWT) — alinhado ao pen-test auth (JWT cross-service).
  • [x] Runtime: garantir que o ambiente de execução (host, ECS, Kubernetes) usa Java 17 (ou a imagem Docker Temurin/Corretto 17 fornecida).
  • [x] Documentação: após o deploy, validar acesso a SpringDoc (/swagger-ui.html / /v3/api-docs) e /ecosif-moviments/actuator/health conforme o context path configurado.

5. Referências

Equipe eCosif · Release Notes ecosif-moviments (0.6.00.x → 0.7.01.x)