📐 Camadas - ecosif-querys

📋 Visão Geral

O serviço ecosif-querys segue uma arquitetura em camadas focada em operações de leitura, otimizada para performance e escalabilidade.

🏗️ Estrutura de Camadas

┌─────────────────────────────────────────────────────────┐
│              Camada de Apresentação (REST)              │
│                                                         │
│  BalanceInquiryController                               │
│  • POST /balanceInquiryDetails                          │
│  • POST /generalLedgerQuery                             │
│  • GET /allChartOfAccount/{company}/{branch}            │
│                                                         │
│  Responsabilidades:                                     │
│  • Receber requisições HTTP                             │
│  • Validação básica de entrada                          │
│  • Chamar validação de acesso                           │
│  • Transformar DTOs ↔ JSON                              │
│  • Retornar respostas HTTP                              │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ usa
                     ▼
┌─────────────────────────────────────────────────────────┐
│            Camada de Aplicação (Services)               │
│                                                         │
│  Services                                               │
│  • AccessValidationService                              │
│    - Valida acesso por empresa/filial                   │
│  • BranchService, CompanyService, etc.                  │
│                                                         │
│  Responsabilidades:                                     │
│  • Validação de acesso                                  │
│  • Lógica de negócio para consultas                     │
│  • Orquestração de repositories                         │
│  • Transformação DTO ↔ Entity                           │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ usa
                     ▼
┌─────────────────────────────────────────────────────────┐
│           Camada de Persistência (Repositories)         │
│                                                         │
│  Repositories                                           │
│  • AccountbalanceRepository                             │
│  • MonthlyAccountBalanceRepository                      │
│  • ChartOfAccountsRepository                            │
│  • InquiryRepository (queries customizadas)             │
│                                                         │
│  Responsabilidades:                                     │
│  • Acesso a dados otimizado                             │
│  • Queries customizadas com JOINs                       │
│  • Projeções específicas (DTOs)                         │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ persiste
                     ▼
┌─────────────────────────────────────────────────────────┐
│              Camada de Dados (Entities)                 │
│                                                         │
│  ecosif-database (Biblioteca Compartilhada)             │
│  • Accountbalance • MonthlyAccountBalance               │
│  • ChartOfAccounts • CompanyOptions                     │
│  • ... (52+ entidades)                                  │
└─────────────────────────────────────────────────────────┘

📦 Detalhamento das Camadas

Camada 1: Controllers (REST)

Localização: io.ecosif.querys.company.controller

Características: - Apenas 1 controller (BalanceInquiryController) - 3 endpoints principais - Validação de entrada via @Valid - Validação de acesso via AccessValidationService - Documentação OpenAPI 3.0

Exemplo:

@RestController
@Tag(name = "Balance Inquiry")
@SecurityRequirement(name = "bearerAuth")
public class BalanceInquiryController {

    @PostMapping("/balanceInquiryDetails")
    public ResponseEntity<List<BalanceInquiryResponseDTO>> getBalanceInquiryDetails(
            @Valid @RequestBody BalanceInquiryRequestDTO dto,
            @CurrentUser LocalUser localUser) {

        // Valida acesso
        accessValidationService.validateUserAccess(localUser, dto.getEmpresa(), dto.getFilial());

        // Processa consulta...
    }
}

Camada 2: Services (Validação e Lógica)

Localização: io.ecosif.querys.company.service

Principais Services:

AccessValidationService

Valida acesso do usuário a empresa/filial: - Verifica UserCompanyBranch (acesso direto) - Verifica grupos do usuário (acesso herdado) - Lança exceção 403 Forbidden se sem acesso

Exemplo:

@Service
public class AccessValidationService {

    public void validateUserAccess(LocalUser user, String company, String branch) {
        // Validação de acesso...
        if (!hasAccess) {
            throw new ForbiddenException("Acesso negado");
        }
    }
}

Camada 3: Repositories (Acesso a Dados)

Localização: io.ecosif.querys.company.repository

Características: - Queries otimizadas para leitura - Queries customizadas com @Query - Projeções específicas (interface DTOs)

Exemplo:

@Repository
public interface InquiryRepository extends JpaRepository<...> {

    @Query(value = "SELECT ... FROM ct_lancamento l " +
                   "JOIN ct_documentos d ON ... " +
                   "WHERE ...", nativeQuery = true)
    List<GeneralLedgerQueryResponseDTO> findAccountBalanceByYearAndMonthRange(...);
}

Camada 4: DTOs (Data Transfer Objects)

Localização: io.ecosif.querys.company.dto

Tipos:

1. Request DTOs: - BalanceInquiryRequestDTO - Consulta de saldo - GeneralLedgerQueryRequestDTO - Consulta de razão geral

2. Response DTOs: - BalanceInquiryResponseDTO - Resposta de saldo - GeneralLedgerQueryResponseDTO - Resposta de razão geral (interface) - ChartOfAccountsDTO - Plano de contas

Características: - Validações JSR-303 - Anotações OpenAPI para documentação - Lombok para reduzir boilerplate

🔄 Fluxo de Dados

Fluxo: Consulta de Saldo

Cliente HTTP
    │
    ▼
BalanceInquiryController
    │ Valida entrada (@Valid)
    │ Valida acesso (AccessValidationService)
    │
    ▼
Repositories
    │ MonthlyAccountBalanceRepository
    │ AccountbalanceRepository
    │
    ▼
PostgreSQL
    │ Queries otimizadas
    │
    ▼
Controller
    │ Transforma em DTOs
    │ Calcula saldo inicial
    │
    ▼
Cliente HTTP

🎯 Princípios de Design

1. Separation of Concerns

• Controller: Apresentação HTTP e validação de acesso
• Service: Validação de acesso e orquestração
• Repository: Acesso otimizado a dados

2. Read-Only Focus

• Apenas operações de leitura
• Sem transações de escrita
• Otimizações específicas para queries

3. Access Control First

• Validação de acesso em todos os endpoints
• Centralizada em AccessValidationService
• Consistência garantida

📊 Performance

Otimizações Implementadas

1. Queries Customizadas - JOINs otimizados no InquiryRepository - Projeções específicas (apenas campos necessários)

2. Índices no Banco - Campos frequentemente consultados indexados - Índices compostos para queries complexas

3. Sem Overhead de Escrita - Não há transações pesadas - Não há locks desnecessários

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