📋 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=baseYearMonthda empresa: usa saldo inicial deAccountbalance - Regra: Caso contrário: usa saldo acumulado do mês anterior em
MonthlyAccountBalance
📋 Regras de Razão Geral¶
Filtro de Dias¶
- Regra: Se
dayStartedayEnd= 0: retorna todos os dias do mês - Regra: Se informados: filtra apenas no intervalo especificado
- Validação:
dayStartnão pode ser maior quedayEnd
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
chartOfAccountnã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émovdebemovimentoCreditoémovcred.movencnão vai na resposta - Saldo final: é o
saldoacumuladogravado. 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:
saldoacumuladodo último mês anterior com linha emct_plano_saldo. No mês-base, se não houver mês anterior, usact_plsaldos.saldoinicial. Sem os dois, fica 0 - Saldo inicial diário:
saldoacumuladoda última linha dect_plano_saldo_diacom 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, usact_plsaldos.saldoinicial. Fora do mês-base, sem dia anterior, fica 0 - Mês-base:
ct_controle.anomesbase(MM/aaaa). No plano02, usaanomesdiabasequando essa data estiver preenchida - Identificação: a linha traz
idEmpresa,idFilial,ano,mes,contaId,cdConta,cdReduzidoedescricao. No diário,diafica depois demes. Código numérico com menos de 9 dígitos também localiza o cadastro com zeros à esquerda - Página:
paginacomeça em 0.tamanhopadrão 100, máximo 500
⚠️ Validações Implementadas¶
- ✅ Formato de período (MM/YYYY)
- ✅ Range de períodos
- ✅ Range de dias
- ✅ Ano/mês válidos
- ✅ Permissões de acesso
- ✅ Empresa/filial existentes
- ✅ Plano de contas configurado
Última Atualização: 2026-10-08