📐 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:
2. BalanceInquiryRequestDTO - Consulta de saldo

3. GeneralLedgerQueryRequestDTO - Consulta de razão geral

4. Response DTOs:

5. BalanceInquiryResponseDTO - Resposta de saldo
6. GeneralLedgerQueryResponseDTO - Resposta de razão geral (interface)
7. 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
2. JOINs otimizados no InquiryRepository

3. Projeções específicas (apenas campos necessários)

4. Índices no Banco

5. Campos frequentemente consultados indexados

6. Índices compostos para queries complexas

7. Sem Overhead de Escrita

8. Não há transações pesadas
9. Não há locks desnecessários

---

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