🏗️ Arquitetura - ecosif-reports¶

📋 Visão Geral¶

ecosif-reports é um microserviço Spring Boot especializado na geração de relatórios contábeis utilizando JasperReports. Este serviço processa dados contábeis e os transforma em relatórios formatados em PDF, CSV ou TXT.

🎯 Objetivo do Serviço¶

✅ Geração de relatórios contábeis em múltiplos formatos
✅ Templates reutilizáveis usando JasperReports
✅ Performance para grandes volumes de dados
✅ Consultas de dados para alimentar relatórios

🏛️ Arquitetura em Camadas¶

┌─────────────────────────────────────────────────────────┐
│                  Controllers (REST)                      │
│  • ReportsController (11 endpoints)                     │
│  • PlanoSaldoController (3 endpoints)                   │
│  • LancamentoContabilController (1 endpoint)            │
│  • PreferenciasController (2 endpoints)                 │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                    Services (Lógica)                     │
│  • PrintReportService                                   │
│  • ProcedureBalanceteGeralService                       │
│  • ProcedureBalanceteMensalService                      │
│  • ProcedureRazaoService                                │
│  • RelatorioDiarioGeralService                          │
│  • ... (13 services)                                    │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                 Repositories (JPA)                       │
│  • AccountbalanceRepository                             │
│  • MonthlyAccountBalanceRepository                      │
│  • ChartOfAccountsRepository                            │
│  • ... (31 repositories)                                │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│            ecosif-database (Biblioteca)                  │
│  • Entry • Balance • ChartOfAccounts                    │
│  • Document • Batch • CompanyOptions                    │
│  • ... (52+ entidades)                                  │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                 PostgreSQL Database                      │
│  • Tabelas contábeis                                    │
│  • Procedures de agregação                              │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│              JasperReports Templates                     │
│  • 36+ templates (.jrxml)                               │
│  • Compilados (.jasper)                                 │
└─────────────────────────────────────────────────────────┘

📦 Estrutura de Pacotes¶

io.ecosif.reports
├── controller/         # 5 controllers REST
│   ├── ReportsController.java
│   ├── PlanoSaldoController.java
│   ├── LancamentoContabilController.java
│   ├── PreferenciasController.java
│   └── TesteController.java
├── service/            # Services de geração
│   ├── PrintReportService.java
│   ├── ProcedureBalanceteGeralService.java
│   ├── ProcedureBalanceteMensalService.java
│   ├── ProcedureRazaoService.java
│   └── ... (13 services)
├── repository/         # Repositories JPA (31)
├── model/              # Models e DTOs
│   ├── dto/            # 31 DTOs
│   └── ... (models temporários)
├── helpers/            # Helpers de exportação
│   └── ExportReportsHelper.java
├── config/             # Configurações Spring
│   ├── OpenApiConfig.java
│   ├── JasperReportsConfig.java
│   └── WebSecurityConfig.java
└── procedures/         # Procedures de banco

🔧 Tecnologias e Dependências¶

Core¶

Spring Boot 2.7.18 - Framework base
Spring Data JPA - Persistência
Hibernate - ORM
PostgreSQL 15+ - Banco de dados

Geração de Relatórios¶

JasperReports 6.19.1 - Engine de relatórios
iText 2.1.7 - Geração de PDF
Batik 1.14 - Renderização SVG
Apache POI - Geração de Excel (via JasperReports)

API e Documentação¶

SpringDoc OpenAPI 3.0 - Documentação API

Segurança¶

Spring Security - Autenticação/autorização
JWT (JJWT 0.11.5) - Tokens JWT

Utilitários¶

Lombok 1.18.30 - Redução de boilerplate
ModelMapper 3.1.0 - Mapeamento DTO ↔ Entity

Monitoramento¶

Spring Actuator - Health checks e métricas
Prometheus - Métricas
Datadog APM - Application Performance Monitoring

📊 Componentes Principais¶

Controllers (5)¶

Controller	Endpoints	Responsabilidade
`ReportsController`	11	Geração de relatórios
`PlanoSaldoController`	3	Consultas de saldos
`LancamentoContabilController`	1	Consultas de lançamentos
`PreferenciasController`	2	Preferências de usuário
`TesteController`	6	Endpoints de teste

Services (13+)¶

Principais services:

PrintReportService - Serviço principal de geração
ProcedureBalanceteGeralService - Balancete geral
ProcedureBalanceteMensalService - Balancete mensal
ProcedureBalanceteDiarioService - Balancete diário
ProcedureBalancetePatrimonialService - Balanço patrimonial
ProcedureRazaoService - Razão contábil
RelatorioDiarioGeralService - Diário geral
ProcedureTermoService - Termos de abertura/encerramento
LancamentoContabilService - Consulta de lançamentos
PlanoSaldoService - Consulta de saldos
PreferenciasUsuarioService - Preferências

Repositories (31)¶

AccountbalanceRepository - Saldos de contas
MonthlyAccountBalanceRepository - Saldos mensais
ChartOfAccountsRepository - Plano de contas
EntryRepository - Lançamentos
... (27 mais)

📄 Templates JasperReports¶

O serviço possui 36+ templates organizados por tipo:

Balancetes - Mensal, diário, geral
Patrimonial - Balanço patrimonial, DRE
Razão - Razão contábil
Diário Geral - Diário geral completo
Lançamentos - Listagem de lançamentos
COSIF/CVM - Formatos regulatórios

Localização: src/main/resources/templates/*.jrxml

🔄 Fluxo de Geração de Relatório¶

Controller recebe requisição com parâmetros
Service valida dados e busca informações do banco
Repository executa queries/procedures
Service prepara dados (DTOs, projections)
JasperReports compila template (.jrxml → .jasper)
JasperReports preenche template com dados
ExportHelper exporta para formato solicitado (PDF/CSV/TXT)
Controller retorna relatório em base64

Última Atualização: 2025-12-01