🔄 Fluxos - ecosif-querys

📋 Visão Geral

Este documento descreve os principais fluxos de consulta do serviço ecosif-querys.

🔄 Fluxo 1: Consulta de Saldo Detalhado

Descrição

Consulta os detalhes de saldo de uma conta contábil para um período específico, incluindo movimentações mensais e saldo de abertura.

Diagrama de Sequência

sequenceDiagram
    participant Client as Cliente
    participant Controller as BalanceInquiryController
    participant AccessService as AccessValidationService
    participant OptionsRepo as CompanyOptionsRepository
    participant BalanceRepo as MonthlyAccountBalanceRepository
    participant AccountRepo as AccountbalanceRepository
    participant DB as PostgreSQL

    Client->>Controller: POST /balanceInquiryDetails (DTO)
    Controller->>Controller: Valida entrada (@Valid)

    Controller->>AccessService: validateUserAccess(user, empresa, filial)
    AccessService->>AccessService: Busca UserCompanyBranch
    AccessService->>AccessService: Verifica grupos do usuário
    alt Sem acesso
        AccessService-->>Controller: ForbiddenException (403)
        Controller-->>Client: 403 Forbidden
    else Com acesso
        AccessService-->>Controller: OK

        Controller->>OptionsRepo: findByCompanyAndBranch(empresa, filial)
        OptionsRepo->>DB: SELECT * FROM ct_controle
        DB-->>OptionsRepo: CompanyOptions
        OptionsRepo-->>Controller: Options

        Controller->>Controller: Valida formatos de data
        Controller->>Controller: Calcula baseYearMonth

        Controller->>BalanceRepo: findAccountBalanceByYearAndMonthRange(...)
        BalanceRepo->>DB: SELECT * FROM ct_plano_saldo WHERE empresa=? AND filial=? AND conta_id=? AND ano_mes BETWEEN ? AND ?
        DB-->>BalanceRepo: List<MonthlyAccountBalance>
        BalanceRepo-->>Controller: Balances mensais

        alt anomesini == baseYearMonth
            Controller->>AccountRepo: findByCompanyAndBranchAndContaId(...)
            AccountRepo->>DB: SELECT * FROM ct_plsaldos WHERE empresa=? AND filial=? AND conta_id=?
            DB-->>AccountRepo: Accountbalance
            AccountRepo-->>Controller: Saldo inicial de Accountbalance
        else anomesini != baseYearMonth
            Controller->>BalanceRepo: findInitialAccountBalanceByInitialYearMonth(...)
            BalanceRepo->>DB: SELECT accumulated_balance FROM ct_plano_saldo WHERE ano_mes < ?
            DB-->>BalanceRepo: Saldo anterior
            BalanceRepo-->>Controller: Saldo acumulado anterior
        end

        Controller->>Controller: Monta BalanceInquiryResponseDTO para cada mês
        Controller->>Controller: Define openingBalance em todas as respostas
        Controller-->>Client: 200 OK (List<BalanceInquiryResponseDTO>)
    end

Validações Realizadas

Autenticação - Token JWT válido
Validação de Acesso - Usuário tem acesso à empresa/filial
Formato de Data - MM/YYYY
Range de Datas - anomesini <= anomesfim
Empresa/Filial - Existem e têm configurações

🔄 Fluxo 2: Consulta de Razão Geral (Diário)

Descrição

Consulta a razão geral (diário) de uma conta contábil com detalhamento de lançamentos, permitindo filtrar por intervalo de dias.

Diagrama de Sequência

sequenceDiagram
    participant Client as Cliente
    participant Controller as BalanceInquiryController
    participant AccessService as AccessValidationService
    participant InquiryRepo as InquiryRepository
    participant DB as PostgreSQL

    Client->>Controller: POST /generalLedgerQuery (DTO)
    Controller->>Controller: Valida entrada (@Valid)

    Controller->>AccessService: validateUserAccess(user, empresa, filial)
    AccessService-->>Controller: Acesso válido

    Controller->>Controller: Valida range de dias (dayStart <= dayEnd)

    Controller->>InquiryRepo: findAccountBalanceByYearAndMonthRange(contaId, empresa, filial, year, month, dayStart, dayEnd)

    InquiryRepo->>DB: SELECT 
                       l.lancamento, l.debcre, l.diareferencia,
                       d.documento, d.texto,
                       b.lote,
                       p.cdcontabil, p.descricao,
                       l.valor, l.historico
                     FROM ct_lancamento l
                     JOIN ct_documentos d ON l.docto_id = d.docto_id
                     JOIN ct_lote b ON d.lote_id = b.id
                     JOIN ct_plano p ON l.conta_id = p.conta_id
                     WHERE l.conta_id = ?
                       AND b.empresa = ?
                       AND b.filial = ?
                       AND b.ano = ?
                       AND b.mes = ?
                       AND (l.diareferencia BETWEEN ? AND ? OR ? = 0)
                     ORDER BY l.diareferencia, d.documento, l.lancamento

    DB-->>InquiryRepo: ResultSet (dados agregados)
    InquiryRepo->>InquiryRepo: Mapeia para GeneralLedgerQueryResponseDTO
    InquiryRepo-->>Controller: List<GeneralLedgerQueryResponseDTO>

    Controller-->>Client: 200 OK

Características

Query Complexa - Múltiplos JOINs para agregar dados
Filtro de Dias - Opcional, filtra por intervalo de dias
Ordenação - Por dia, documento e lançamento
Projeção - Apenas campos necessários (DTO interface)

🔄 Fluxo 3: Listar Plano de Contas

Descrição

Lista o plano de contas completo de uma empresa/filial, ordenado numericamente de forma hierárquica.

Diagrama de Sequência

sequenceDiagram
    participant Client as Cliente
    participant Controller as BalanceInquiryController
    participant AccessService as AccessValidationService
    participant OptionsRepo as CompanyOptionsRepository
    participant ChartRepo as ChartOfAccountsRepository
    participant Comparator as ChartOfAccountsComparator
    participant DB as PostgreSQL

    Client->>Controller: GET /allChartOfAccount/{company}/{branch}

    Controller->>AccessService: validateUserAccess(user, company, branch)
    AccessService-->>Controller: Acesso válido

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

    Controller->>Controller: Valida se chartOfAccount está configurado

    Controller->>ChartRepo: findByPlanOrderByCdAccountingAsc(plan)
    ChartRepo->>DB: SELECT * FROM ct_plano WHERE tipo = ? ORDER BY cdcontabil ASC
    DB-->>ChartRepo: List<ChartOfAccounts>
    ChartRepo-->>Controller: Charts

    Controller->>Controller: Transforma em ChartOfAccountsDTO
    Controller->>Comparator: Ordena usando ChartOfAccountsComparator
    Note over Comparator: Ordenação numérica:<br/>1.1 < 1.2 < 1.10
    Comparator-->>Controller: List ordenada numericamente

    Controller-->>Client: 200 OK (List<ChartOfAccountsDTO>)

Ordenação Numérica

O ChartOfAccountsComparator garante ordenação correta: - Divide códigos por ponto (.) - Compara cada parte numericamente - Resultado: "1.1" < "1.2" < "1.10" (não alfabeticamente)

🔐 Fluxo 4: Validação de Acesso

Descrição

Fluxo detalhado de validação de acesso do usuário a uma empresa/filial.

Diagrama de Sequência

sequenceDiagram
    participant Controller
    participant AccessService as AccessValidationService
    participant UserBranchRepo as UserCompanyBranchRepository
    participant UserGroupRepo as UserGroupRepository
    participant BranchRepo as BranchRepository
    participant DB as PostgreSQL

    Controller->>AccessService: validateUserAccess(user, company, branch)

    alt Usuário é ADMIN
        AccessService-->>Controller: OK (admin tem acesso total)
    else Usuário não é ADMIN
        AccessService->>UserBranchRepo: findByUserIdAndCompanyAndBranch(userId, companyId, branchId)
        UserBranchRepo->>DB: SELECT * FROM gr_filial_usuario WHERE user_id=? AND company=? AND branch=?
        DB-->>UserBranchRepo: UserCompanyBranch (se existir)

        alt Tem acesso direto
            AccessService-->>Controller: OK
        else Não tem acesso direto
            AccessService->>UserGroupRepo: findByUserId(userId)
            UserGroupRepo->>DB: SELECT * FROM gr_grupo_usuario WHERE userid=?
            DB-->>UserGroupRepo: List<UserGroup>
            UserGroupRepo-->>AccessService: Groups

            AccessService->>AccessService: Verifica se algum grupo tem acesso
            AccessService->>BranchRepo: Verifica permissões por grupo

            alt Tem acesso via grupo
                AccessService-->>Controller: OK
            else Sem acesso
                AccessService-->>Controller: ForbiddenException (403)
            end
        end
    end

📊 Resumo dos Fluxos

Fluxo	Tipo	Complexidade	Performance
Consulta de Saldo	Leitura	Média	Otimizada
Razão Geral	Leitura	Alta (JOINs)	Otimizada
Plano de Contas	Leitura	Baixa	Muito rápida
Validação de Acesso	Leitura	Média	Cacheável

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