🔄 Fluxos - ecosif-moviments

📋 Visão Geral

Este documento descreve os principais fluxos de processamento do serviço ecosif-moviments.

🔄 Fluxo 1: Criar Lançamento Contábil

Descrição

Fluxo completo para criar um lançamento contábil, incluindo validações de partidas dobradas.

Diagrama de Sequência

sequenceDiagram
    participant Client as Cliente
    participant Controller as EntryController
    participant Service as EntryService
    participant DocService as DocumentService
    participant BatchService as BatchService
    participant CalendarService as CalendarService
    participant EntryRepo as EntryRepository
    participant DocRepo as DocumentRepository
    participant BatchRepo as BatchRepository
    participant DB as PostgreSQL

    Client->>Controller: POST /entry (EntryDTO)
    Controller->>Controller: Valida entrada (@Valid)
    Controller->>Service: createEntry(entryDTO)

    Service->>DocRepo: findById(documentId)
    DocRepo->>DB: SELECT * FROM ct_documentos
    DB-->>DocRepo: Document entity
    DocRepo-->>Service: Document

    Service->>BatchRepo: findById(batchId)
    BatchRepo->>DB: SELECT * FROM ct_lote
    DB-->>BatchRepo: Batch entity
    BatchRepo-->>Service: Batch

    Service->>CalendarService: validatePeriodOpen(company, branch, month, year)
    CalendarService-->>Service: Período válido

    Service->>Service: Valida conta contábil
    Service->>Service: Valida partidas dobradas
    Service->>EntryRepo: save(entry)
    EntryRepo->>DB: INSERT INTO ct_lancamento
    DB-->>EntryRepo: Entry salvo
    EntryRepo-->>Service: Entry entity

    Service->>Service: Transforma Entry → EntryDTO
    Service-->>Controller: EntryDTO
    Controller-->>Client: 201 Created

Validações Realizadas

Validação de entrada (JSR-303)
Documento existe
Lote existe e está aberto
Período está aberto (não consolidado)
Conta contábil existe e está ativa
Partidas dobradas (soma débitos = soma créditos)

🔄 Fluxo 2: Importação de Arquivo CSV

Descrição

Fluxo de importação de lançamentos via arquivo CSV.

Diagrama de Sequência

sequenceDiagram
    participant Client as Cliente
    participant Controller as BatchImportController
    participant Service as BatchImportService
    participant Parser as CSV Parser
    participant Validator as Entry Validator
    participant EntryService as EntryService
    participant EntryRepo as EntryRepository
    participant S3Service as S3Service
    participant S3 as AWS S3
    participant DB as PostgreSQL

    Client->>Controller: POST /batch/{id}/import (file)
    Controller->>Service: importEntries(batchId, file, dryRun)

    alt dryRun = false
        Service->>Parser: parseCSV(file)
        Parser-->>Service: List<EntryDTO>

        loop Para cada entrada
            Service->>Validator: validate(entryDTO)
            Validator-->>Service: Validação OK ou erro
        end

        Service->>EntryRepo: saveAll(validEntries)
        EntryRepo->>DB: INSERT múltiplos
        DB-->>EntryRepo: Entries salvos

        Service->>S3Service: uploadFile(file, "imported/")
        S3Service->>S3: PUT object
        S3-->>S3Service: Upload OK

    else dryRun = true
        Service->>Parser: parseCSV(file)
        Parser-->>Service: List<EntryDTO>
        Service->>Service: Apenas valida (não salva)
    end

    Service->>Service: Gera ImportResultDTO
    Service-->>Controller: ImportResultDTO
    Controller-->>Client: 200 OK

Etapas

Upload do arquivo via multipart/form-data
Parse do CSV em objetos EntryDTO
Validação de cada entrada
Persistência (se não for dryRun)
Upload para S3 (pasta imported/)
Retorno com estatísticas

🔄 Fluxo 3: Consolidação Contábil

Descrição

Fluxo assíncrono de consolidação contábil de um período.

Diagrama de Sequência

sequenceDiagram
    participant Client as Cliente
    participant Controller as ConsolidationController
    participant Service as ConsolidationService
    participant Async as @Async Executor
    participant EntryRepo as EntryRepository
    participant BalanceService as AccountBalanceService
    participant BalanceRepo as AccountBalanceRepository
    participant CalendarService as CalendarService
    participant CalendarRepo as CalendarRepository
    participant DB as PostgreSQL

    Client->>Controller: POST /runconsolidation
    Controller->>Service: runConsolidation(dto)
    Service->>Async: executeAsync(consolidationTask)
    Service-->>Controller: 200 OK (iniciado)
    Controller-->>Client: 200 OK

    Note over Async,DB: Processamento Assíncrono

    Async->>Service: processConsolidation(dto)
    Service->>EntryRepo: findByBatchPeriod(company, branch, year, month)
    EntryRepo->>DB: SELECT * FROM ct_lancamento WHERE...
    DB-->>EntryRepo: List<Entry>
    EntryRepo-->>Service: Entries

    Service->>Service: Agrupa por conta contábil
    Service->>Service: Calcula saldos (débito - crédito)

    loop Para cada conta
        Service->>BalanceService: updateBalance(contaId, saldo)
        BalanceService->>BalanceRepo: saveOrUpdate(balance)
        BalanceRepo->>DB: INSERT/UPDATE ct_plano_saldo
    end

    Service->>CalendarService: markAsConsolidated(company, branch, month, year)
    CalendarService->>CalendarRepo: updateConsolidated(calendar)
    CalendarRepo->>DB: UPDATE ct_calendario SET consolidated=true

    Service->>Service: Log de conclusão

Características

✅ Assíncrono - Não bloqueia requisição HTTP
✅ Processamento em lote - Calcula todos os saldos
✅ Atualização de calendário - Marca período como consolidado
✅ Transacional - Rollback em caso de erro

🔄 Fluxo 4: Cálculo de Cotas Tributárias

Descrição

Fluxo para calcular valor de cotas de fundos de investimento.

Diagrama de Sequência

sequenceDiagram
    participant Client as Cliente
    participant Controller as TaxQuotaCalculationController
    participant Service as TaxQuotaCalculationService
    participant OptionsRepo as CompanyOptionsRepository
    participant CalendarRepo as CalendarRepository
    participant EquityRepo as EquityAccountRepository
    participant QuotaConfigRepo as QuotaCalculationConfigurationRepository
    participant BalanceService as AccountBalanceService
    participant DB as PostgreSQL

    Client->>Controller: GET /taxquotacalculation/{company}/{branch}?confirmed=false
    Controller->>Service: calculateQuota(company, branch, confirmed)

    Service->>OptionsRepo: findByCompanyAndBranch(company, branch)
    OptionsRepo->>DB: SELECT * FROM ct_controle
    DB-->>OptionsRepo: CompanyOptions
    OptionsRepo-->>Service: Options

    Service->>Service: Valida: usa calendário?
    Service->>CalendarRepo: findByCompanyAndBranchAndMonthAndYear(...)
    CalendarRepo->>DB: SELECT * FROM ct_calendario
    DB-->>Service: Calendar

    Service->>Service: Valida: mês consolidado?
    Service->>Service: Busca dia livre (indicator.indexOf("0"))

    Service->>EquityRepo: findByCompanyAndBranch(company, branch)
    EquitRepo->>DB: SELECT * FROM ct_conta_patrimonio
    DB-->>Service: List<EquityAccount>

    Service->>BalanceService: calculatePatrimonioLiquido(accounts)
    BalanceService-->>Service: Valor do PL

    Service->>QuotaConfigRepo: findByCompanyAndBranch(company, branch)
    QuotaConfigRepo->>DB: SELECT * FROM ct_parametro_fundo
    DB-->>Service: QuotaCalculationConfiguration

    Service->>Service: Calcula número de cotas
    Service->>Service: Calcula valor da cota (PL / número de cotas)

    alt confirmed = false
        Service-->>Controller: Preview (302 Found)
        Controller-->>Client: [data, valorCota, PL, numCotas]
    else confirmed = true
        Service->>QuotaConfigRepo: updateQuotaValue(...)
        Service->>QuotaDetailsService: saveQuotaDetails(...)
        Service-->>Controller: 200 OK
        Controller-->>Client: 200 OK
    end

Validações

Opções da empresa existem
Usa calendário (useCalendar = true)
Mês consolidado (consolidated = true)
Dia livre disponível no calendário
Contas PL configuradas
Patrimônio líquido positivo
Número de cotas > 0

🔄 Fluxo 5: Abertura de Novo Mês

Descrição

Fluxo para abrir um novo período contábil.

Diagrama de Sequência

sequenceDiagram
    participant Client as Cliente
    participant Controller as MonthOpeningController
    participant OptionsRepo as CompanyOptionsRepository
    participant CalendarRepo as CalendarRepository
    participant BatchRepo as BatchRepository
    participant DB as PostgreSQL

    Client->>Controller: POST /monthOpening/{company}/{branch}
    Controller->>OptionsRepo: findByCompanyAndBranch(company, branch)
    OptionsRepo->>DB: SELECT * FROM ct_controle
    DB-->>OptionsRepo: CompanyOptions
    OptionsRepo-->>Controller: Options

    Controller->>Controller: Atualiza currentYearMonth
    Controller->>OptionsRepo: save(options)

    Controller->>Controller: Verifica se calendário existe
    Controller->>CalendarRepo: findByCompanyAndBranchAndMonthAndYear(...)

    alt Calendário não existe
        Controller->>Controller: Cria novo calendário
        Controller->>Controller: Gera indicadores de dias (2=fechado, 0=livre, 1=fds, *=futuro)
        Controller->>CalendarRepo: save(calendar)
        CalendarRepo->>DB: INSERT INTO ct_calendario
    end

    Controller->>BatchRepo: findByCompanyAndBranchOrderByBatchAsc(...)
    BatchRepo->>DB: SELECT * FROM ct_lote ORDER BY...
    DB-->>BatchRepo: List<Batch>
    BatchRepo-->>Controller: Batches

    Controller->>Controller: Calcula primeiro/último lançamento
    Controller->>Controller: Monta MonthOpeningDTO
    Controller-->>Client: 201 Created

🔄 Fluxo 6: Purging de Dados

Descrição

Fluxo para arquivar ou restaurar dados antigos (purge).

Diagrama de Sequência

sequenceDiagram
    participant Client as Cliente
    participant Controller as PurgingController
    participant Service as PurgingService
    participant BranchRepo as BranchRepository
    participant OptionsRepo as CompanyOptionsRepository
    participant CalendarRepo as CalendarRepository
    participant HistoryService as History Service
    participant S3Service as S3Service
    participant S3 as AWS S3
    participant DB as PostgreSQL

    Client->>Controller: POST /purging (PurgingDTO)
    Controller->>BranchRepo: findAllById(selectedBranchIds)
    BranchRepo->>DB: SELECT * FROM gr_filial
    DB-->>BranchRepo: List<Branch>

    loop Para cada empresa/filial
        Controller->>OptionsRepo: findByCompanyAndBranch(...)
        Controller->>Service: purgeData(company, branch, ...)

        alt doSend = true (Enviar para histórico)
            Service->>CalendarRepo: getCalEntryForPurging(...)
            Service->>Service: Valida: todos consolidados?

            Service->>HistoryService: moveToHistory(...)
            HistoryService->>DB: INSERT INTO ct_histo_*
            HistoryService->>DB: DELETE FROM ct_lancamento
            HistoryService->>DB: DELETE FROM ct_documentos

            Service->>S3Service: uploadDump(...)
            S3Service->>S3: PUT dump file
        else doSend = false (Restaurar do histórico)
            Service->>HistoryService: restoreFromHistory(...)
            HistoryService->>DB: INSERT FROM ct_histo_*
            HistoryService->>DB: DELETE FROM ct_histo_*
        end
    end

    Controller-->>Client: 200 OK (List<String> erros)

📊 Resumo dos Fluxos

Fluxo	Tipo	Assíncrono	Complexidade
Criar Lançamento	Síncrono	❌	Média
Importação CSV	Síncrono	❌	Alta
Consolidação	Assíncrono	✅	Alta
Cálculo Cotas	Síncrono	❌	Alta
Abertura Mês	Síncrono	❌	Baixa
Purging	Síncrono	❌	Alta

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