📊 Visão Geral Funcional - ecosif-querys

📋 Sobre o Projeto

ecosif-querys é um microserviço Spring Boot especializado em consultas otimizadas de dados contábeis no sistema eCosif. Este serviço foca exclusivamente em operações de leitura, fornecendo endpoints otimizados para visualização, relatórios e análises.

🎯 Objetivo do Serviço

O serviço tem como objetivo fornecer consultas rápidas e eficientes de dados contábeis, com:

• ✅ Performance otimizada - Queries otimizadas para grandes volumes
• ✅ Separação de responsabilidades - Foco em leitura vs escrita
• ✅ Escalabilidade - Pode escalar independentemente
• ✅ Validação de acesso - Controle granular de permissões

🏢 Contexto no Sistema eCosif

O ecosif-querys é parte do ecossistema eCosif, trabalhando em conjunto com:

• ecosif-auth: Autenticação e autorização (fornece tokens JWT)
• ecosif-masterdata: Dados mestres (empresas, planos de contas)
• ecosif-moviments: Lançamentos contábeis (dados que são consultados)
• ecosif-reports: Geração de relatórios (consome este serviço)

📦 Funcionalidades Principais

1. Consultas de Saldo

• Consulta detalhada de saldos por período
• Movimentações de débito e crédito mensais
• Cálculo automático de saldo inicial
• Suporte a períodos customizados

2. Razão Geral (Diário)

• Consulta de razão geral com detalhamento dia a dia
• Filtros por intervalo de dias
• Agregação de dados de múltiplas tabelas
• Ordenação por data, documento e lançamento

3. Plano de Contas

• Listagem completa do plano de contas
• Ordenação numérica hierárquica
• Suporte a contas sintéticas e analíticas

4. Validação de Acesso

• Controle granular por empresa/filial
• Validação de permissões diretas e herdadas
• Suporte a grupos de usuários

📊 Estatísticas

• 1 controller REST
• 3 endpoints documentados
• 13 services com lógica de negócio
• 14 repositories JPA
• 13 DTOs para transferência de dados

🔄 Fluxos Principais

Fluxo de Consulta Básico

1. Cliente autentica e obtém token JWT
   ↓
2. Cliente faz requisição com token
   ↓
3. Serviço valida token e acesso
   ↓
4. Serviço executa query otimizada
   ↓
5. Serviço retorna dados em formato JSON

🎓 Público-Alvo

Usuários Finais

• Contadores e analistas contábeis
• Gestores financeiros
• Usuários que precisam consultar dados contábeis

Integradores

• Desenvolvedores que consomem dados contábeis
• Sistemas externos que precisam de relatórios
• Frontend Angular que exibe dados

📝 Notas Importantes

1. Somente Leitura: Este serviço não modifica dados, apenas consulta
2. Performance: Todas as queries são otimizadas para performance
3. Acesso Controlado: Todas as consultas validam permissões
4. Escalável: Pode ser escalado independentemente para suportar mais carga de leitura

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