🏗️ 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)

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

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

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