Pular para conteúdo

📋 Regras de Negócio - ecosif-querys

📋 Visão Geral

Este documento descreve as principais regras de negócio implementadas no serviço ecosif-querys.


🔒 Regras de Acesso

Validação de Permissões

Regra: Todo endpoint deve validar se o usuário tem acesso à empresa/filial solicitada.

Validação: - Verifica acesso direto em UserCompanyBranch - Verifica grupos do usuário - Retorna 403 Forbidden se sem acesso


💰 Regras de Consulta de Saldo

Formato de Período

  • Regra: Períodos devem estar no formato MM/YYYY
  • Validação: Regex ^(0[1-9]|1[0-2])/[0-9]{4}$
  • Exemplo: "01/2025", "11/2024"

Range de Períodos

  • Regra: Período inicial não pode ser maior que período final
  • Validação: Comparação numérica após conversão

Cálculo de Saldo Inicial

  • Regra: Se anomesini = baseYearMonth da empresa: usa saldo inicial de Accountbalance
  • Regra: Caso contrário: usa saldo acumulado do mês anterior em MonthlyAccountBalance

📋 Regras de Razão Geral

Filtro de Dias

  • Regra: Se dayStart e dayEnd = 0: retorna todos os dias do mês
  • Regra: Se informados: filtra apenas no intervalo especificado
  • Validação: dayStart não pode ser maior que dayEnd

Ano e Mês

  • Regra: Ano deve estar entre 2000 e 9999
  • Regra: Mês deve estar entre 1 e 12

📊 Regras de Plano de Contas

Ordenação

  • Regra: Ordenação deve ser numérica, não alfabética
  • Implementação: Usa ChartOfAccountsComparator
  • Exemplo: "1.1" < "1.2" < "1.10" (não "1.10" < "1.2")

Configuração

  • Regra: Plano de contas deve estar configurado em CompanyOptions
  • Validação: Verifica se chartOfAccount não está vazio

🔌 Regras dos saldos SPARTS

Consulta GET /sparts/saldos/mensal e GET /sparts/saldos/diario (QRY-01).

  • Conta: só analítica (nrfilhos = 0) do plano da filial (ct_controle.tipoPlano)
  • Lista: entra conta com movimento ou com saldo diferente de zero. Conta zerada fica de fora
  • Movimentos: movimentoDebito é movdeb e movimentoCredito é movcred. movenc não vai na resposta
  • Saldo final: é o saldoacumulado gravado. A consolidação acumula crédito menos débito. O endpoint não recalcula o saldo como inicial + débito − crédito
  • Saldo inicial mensal: saldoacumulado do último mês anterior com linha em ct_plano_saldo. No mês-base, se não houver mês anterior, usa ct_plsaldos.saldoinicial. Sem os dois, fica 0
  • Saldo inicial diário: saldoacumulado da última linha de ct_plano_saldo_dia com data estritamente anterior ao dia pedido, na mesma empresa, filial e conta. Dia sem movimento pode não ter linha; o saldo da última linha anterior permanece. No mês-base, se não houver nenhum dia anterior, usa ct_plsaldos.saldoinicial. Fora do mês-base, sem dia anterior, fica 0
  • Mês-base: ct_controle.anomesbase (MM/aaaa). No plano 02, usa anomesdiabase quando essa data estiver preenchida
  • Identificação: a linha traz idEmpresa, idFilial, ano, mes, contaId, cdConta, cdReduzido e descricao. No diário, dia fica depois de mes. Código numérico com menos de 9 dígitos também localiza o cadastro com zeros à esquerda
  • Página: pagina começa em 0. tamanho padrão 100, máximo 500

⚠️ Validações Implementadas

  1. ✅ Formato de período (MM/YYYY)
  2. ✅ Range de períodos
  3. ✅ Range de dias
  4. ✅ Ano/mês válidos
  5. ✅ Permissões de acesso
  6. ✅ Empresa/filial existentes
  7. ✅ Plano de contas configurado

Última Atualização: 2026-10-08