🏗️ Arquitetura - ecosif-moviments

📋 Visão Geral

ecosif-moviments é um microserviço Spring Boot responsável pelo gerenciamento de lançamentos contábeis no sistema eCosif. Ele processa lotes, documentos e lançamentos contábeis, além de realizar importações, consolidações e cálculos de cotas.

🎯 Objetivo do Serviço

✅ Gerenciar lançamentos contábeis (criação, consulta, exclusão)
✅ Processar importações de arquivos IPL e CSV
✅ Executar consolidações contábeis
✅ Calcular cotas tributárias de fundos de investimento
✅ Controlar períodos contábeis (abertura/fechamento)
✅ Realizar purging de dados antigos

🏛️ Arquitetura em Camadas

┌─────────────────────────────────────────────────────────┐
│                  Controllers (REST)                      │
│  • BatchController • DocumentController                 │
│  • EntryController • ConsolidationController            │
│  • BatchImportController • ... (7 mais)                 │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                    Services (Lógica)                     │
│  • BatchService • DocumentService                       │
│  • EntryService • ConsolidationService                  │
│  • BatchImportService • ... (25 mais)                   │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                 Repositories (JPA)                       │
│  • BatchRepository • DocumentRepository                 │
│  • EntryRepository • ... (29 mais)                      │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│            ecosif-database (Biblioteca)                  │
│  • Batch • Document • Entry                             │
│  • Company • Branch • ChartOfAccounts                   │
│  • ... (52+ entidades)                                  │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                 PostgreSQL Database                      │
│  • Tabelas contábeis                                    │
│  • Históricos • Temporárias                             │
└─────────────────────────────────────────────────────────┘

📦 Estrutura de Pacotes

io.ecosif.moviments
├── company/
│   ├── controller/      # 11 controllers REST
│   │   ├── BatchController.java
│   │   ├── DocumentController.java
│   │   ├── EntryController.java
│   │   ├── BatchImportController.java
│   │   ├── ConsolidationController.java
│   │   ├── MonthOpeningController.java
│   │   ├── PurgingController.java
│   │   ├── CalendarController.java
│   │   ├── TaxQuotaCalculationController.java
│   │   ├── ImportReportController.java
│   │   └── AdminController.java
│   ├── service/         # 29 services
│   │   ├── BatchService.java
│   │   ├── DocumentService.java
│   │   ├── EntryService.java
│   │   ├── ConsolidationService.java
│   │   ├── BatchImportService.java
│   │   └── ... (24 mais)
│   ├── repository/      # 31 repositories JPA
│   └── dto/             # 32 DTOs
├── config/              # Configurações Spring
│   ├── OpenApiConfig.java
│   ├── WebSecurityConfig.java
│   ├── WebConfig.java
│   └── ...
├── security/            # Segurança e autenticação
├── importreport/        # Relatórios de importação
└── user/                # Usuários

🔄 Fluxo de Processamento

Fluxo 1: Criar Lançamento

sequenceDiagram
    participant Client as Cliente
    participant Controller as EntryController
    participant Service as EntryService
    participant Validator as Validador
    participant Repository as EntryRepository
    participant DB as PostgreSQL

    Client->>Controller: POST /entry
    Controller->>Service: createEntry(entryDTO)
    Service->>Service: Valida partidas dobradas
    Service->>Service: Valida conta contábil
    Service->>Service: Valida documento
    Service->>Repository: save(entry)
    Repository->>DB: INSERT INTO ct_lancamento
    DB-->>Repository: Entry salvo
    Repository-->>Service: Entry entity
    Service->>Service: Transforma em DTO
    Service-->>Controller: EntryDTO
    Controller-->>Client: 201 Created

Fluxo 2: Importação de Arquivo

sequenceDiagram
    participant Client as Cliente
    participant Controller as BatchImportController
    participant Service as BatchImportService
    participant Parser as Parser CSV/IPL
    participant Repository as Repository
    participant S3 as AWS S3
    participant DB as PostgreSQL

    Client->>Controller: POST /batch/{id}/import
    Controller->>Service: importEntries(batchId, file)
    Service->>Parser: parseFile(file)
    Parser-->>Service: List<EntryDTO>
    Service->>Service: Valida cada entrada
    Service->>Repository: saveAll(entries)
    Repository->>DB: INSERT múltiplos
    Service->>S3: uploadFile(file, imported/)
    S3-->>Service: Upload OK
    Service-->>Controller: ImportResultDTO
    Controller-->>Client: 200 OK

Fluxo 3: Consolidação Contábil

sequenceDiagram
    participant Client as Cliente
    participant Controller as ConsolidationController
    participant Service as ConsolidationService
    participant Async as @Async
    participant Repository as Repository
    participant DB as PostgreSQL

    Client->>Controller: POST /runconsolidation
    Controller->>Service: runConsolidation(dto)
    Service->>Async: executeAsync()
    Async->>Service: Processa consolidação
    Service->>Repository: Busca lançamentos
    Service->>Service: Calcula saldos
    Service->>Repository: Atualiza saldos
    Repository->>DB: UPDATE ct_plano_saldo
    Service->>Service: Atualiza calendário
    Service-->>Async: Consolidação completa
    Async-->>Client: 200 OK (async)

🔧 Tecnologias e Dependências

Core

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

API e Documentação

SpringDoc OpenAPI 3.0 - Documentação API
Springfox Swagger 2 - Compatibilidade (legado)

Segurança

Spring Security - Autenticação/autorização
JWT (JJWT 0.11.5) - Tokens JWT
OAuth2 Client - Integração OAuth2 (opcional)

Utilitários

Lombok 1.18.30 - Redução de boilerplate
ModelMapper 3.1.0 - Mapeamento DTO ↔ Entity
Apache Commons Lang3 - Utilitários

AWS

AWS SDK 2.20.0 - Integração com S3
Spring Cloud AWS - Integração Spring/AWS

Monitoramento

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

Migrações

Flyway - Migrações de banco de dados

📊 Componentes Principais

Controllers (11)

Controller	Responsabilidade
`BatchController`	CRUD de lotes
`DocumentController`	CRUD de documentos
`EntryController`	CRUD de lançamentos
`BatchImportController`	Importação de arquivos CSV
`ImportReportController`	Importação de arquivos IPL
`ConsolidationController`	Consolidação contábil
`MonthOpeningController`	Abertura de mês
`CalendarController`	Operações de calendário
`TaxQuotaCalculationController`	Cálculo de cotas
`PurgingController`	Limpeza de dados
`AdminController`	Operações administrativas

Services (29)

Principais services:

BatchService - Lógica de negócio de lotes
DocumentService - Lógica de negócio de documentos
EntryService - Lógica de negócio de lançamentos
ConsolidationService - Processamento de consolidação
BatchImportService - Processamento de importações
CalendarService - Gerenciamento de calendário
TaxQuotaCalculationService - Cálculo de cotas tributárias
PurgingService - Limpeza e arquivamento

Repositories (31)

Repositórios JPA para todas as entidades, usando Spring Data JPA.

🔐 Segurança

Autenticação JWT

Token obtido via ecosif-auth
Validação via TokenAuthenticationFilter
Header: Authorization: Bearer <token>

Autorização

Baseada em rotinas e grupos (via ecosif-database)
Validação de permissões por empresa/filial

📈 Performance

Otimizações

Paginação em listagens (tamanho configurável)
@Async para operações longas (consolidação)
Lazy Loading em relacionamentos JPA
Connection Pool (HikariCP)

Cache

Cache de configurações (CompanyOptions)
Cache de calendários

🔄 Processamento Assíncrono

Operações assíncronas:

Consolidação contábil - Processamento em background
Importação de arquivos grandes - Processamento assíncrono

Configurado via @EnableAsync e @Async.

📝 Design Patterns

Repository Pattern - Abstração de acesso a dados
Service Layer - Lógica de negócio isolada
DTO Pattern - Separação entre camadas
Factory Pattern - Criação de entidades complexas
Strategy Pattern - Diferentes estratégias de importação

🗄️ Integração com Banco de Dados

Entidades Principais

Batch - Lotes contábeis
Document - Documentos contábeis
Entry - Lançamentos contábeis
ChartOfAccounts - Plano de contas
Accountbalance - Saldos de contas
Calendar - Calendário contábil

Migrações

Flyway gerencia versões do schema
Migrações em src/main/resources/db/migration/

🌐 Integração com AWS S3

Uso

Upload de arquivos importados - Pasta imported/
Download de arquivos para importação - Pasta import-files/
Arquivos de erro - Pasta import-error/
Relatórios de importação - Pasta import-report/
Dumps de purging - Pasta purge/

📊 Monitoramento

Health Checks

Endpoint: /actuator/health
Verifica conexão com banco
Verifica status da aplicação

Métricas

Endpoint: /actuator/prometheus
Métricas JVM
Métricas de HTTP requests
Métricas customizadas

Logs

Estruturado (JSON) via Logback
Integração com Datadog
Níveis configuráveis por pacote

Última Atualização: 2025-11-27