ecosif-reports — 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.202601282
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-reports) 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), usuário não-root, fontes instaladas para geração de relatórios (DejaVu, Liberation), 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.
Geração de relatórios: JasperReports para balancete diário/mensal, razão, balanço patrimonial, DRE, listagem de lançamentos, COSIF 4010/4016, diário geral; exportação em PDF, CSV e TXT (iText, Batik).
Actuator e métricas: endpoints de health, info e Prometheus expostos para monitoração e orquestração.
Modo headless: execução em servidor sem display gráfico (java.awt.headless=true) para geração de relatórios.
Integração S3 (opcional): configuração de bucket e pastas para uso futuro, se o módulo consumir arquivos no S3.

2.3 Base de dados

Somente leitura: o serviço não altera o schema (ddl-auto: none no application.yml); Flyway está desabilitado por padrão. Dados vêm das mesmas tabelas (ct_, gr_) usadas por masterdata e moviments.
Procedures e repositórios: consultas e procedures para alimentar os relatórios; pool HikariCP com tamanho reduzido (máx. 20) em relação a outros módulos.

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 container 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_REPORTS_PORT`	Porta HTTP do serviço (ex.: 8080 ou 8084).
`ecosif_context`	`SERVER_SERVLET_CONTEXT_PATH`	Path da aplicação (ex.: `/ecosif-reports` 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`	Usuário do banco (ex.: `ecosif_reports`).
`ecosif_db_password`	`POSTGRES_PASSWORD`	Senha (usar repositório de segredos).
`hibertenate_mode`	(fixo no YAML: `none`)	O serviço não altera schema; override via propriedade é possível se necessário.
`ecosif_flyway`	(Flyway desabilitado no YAML)	Migrações não são executadas por este serviço.
`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.

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

AWS S3 (quando utilizado): AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_S3_BUCKET — manter conforme documentação operacional.

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-reports), é obrigatório definir:
SERVER_SERVLET_CONTEXT_PATH=/ecosif-reports
O health check passa a ser: /ecosif-reports/actuator/health (ou o path que configurou).
Exemplos de endpoints:
API de relatórios: https://<domínio>/ecosif-reports/api/...
Swagger UI: https://<domínio>/ecosif-reports/swagger-ui.html
OpenAPI JSON: https://<domínio>/ecosif-reports/v3/api-docs

3.3 Docker e imagem

Imagem base: Amazon Corretto 17 (Alpine) em vez de 11; inclui fontes (DejaVu, Liberation) para geração de relatórios.
Entrypoint: o container usa conf/entrypoint.sh (porta e context path; opcionalmente Datadog APM com USEDATADOG=true).
Porta: configurável via ECOSIF_REPORTS_PORT (ex.: 8080 ou 8084). 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-reports/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), headless no runtime 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 arquivo de configuração.
[x] Context path: definir SERVER_SERVLET_CONTEXT_PATH=/ecosif-reports (ou o path acordado) se o serviço for exposto via API Gateway — stack usa ECOSIF_REPORTS_CONTEXT_PATH / -Dserver.servlet.context-path.
[x] Health check: atualizar o path para /ecosif-reports/actuator/health (ou o path correspondente) no ALB, API Gateway ou orquestrador — healthcheck do Compose alinhado.
[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-reports (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] Headless: java.awt.headless=true definido em Application e JasperReportsConfig; não sobrescrever em ambientes sem display.
[x] Documentação: após o deploy, validar acesso a SpringDoc (/swagger-ui.html / /v3/api-docs) e /ecosif-reports/actuator/health conforme o context path configurado.

5. Referências

Variáveis e operação: ambiente/variaveis_operacionais.md
Deploy AWS (ECS + API Gateway): ambiente/aws-ecs-api-gateway.md
Documentação técnica: arquitetura/arquitetura.md

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