Arquitetura do ecosif-masterdata¶

Visão Geral¶

O ecosif-masterdata é um microserviço Spring Boot responsável pelo gerenciamento de todos os dados mestres do sistema eCosif. Ele fornece APIs REST para gerenciar empresas, filiais, planos de contas, calendários, documentos, lançamentos e todas as configurações necessárias para o funcionamento do sistema contábil.

Arquitetura em Camadas¶

O projeto segue a arquitetura em camadas do Spring Boot:

┌─────────────────────────────────────────┐
│          Controller Layer               │
│  (26 Controllers REST)                  │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│           Service Layer                 │
│  (63 Services de Negócio)               │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│         Repository Layer                │
│  (29 Repositories JPA)                  │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│         Database Layer                  │
│         (PostgreSQL + ecosif-database)  │
└─────────────────────────────────────────┘

Componentes Principais¶

1. Controllers (`company/controller/`)¶

26 controllers REST organizados por funcionalidade:

Gestão de Entidades¶

CompanyController: Gerenciamento de empresas
BranchController: Gerenciamento de filiais
ChartOfAccountsController: Gerenciamento do plano de contas
GroupController: Gerenciamento de grupos de usuários

Documentos e Lançamentos¶

DocumentController: Gerenciamento de documentos contábeis
EntryController: Gerenciamento de lançamentos contábeis
BatchController: Gerenciamento de lotes contábeis

Calendários e Períodos¶

CalendarController: Gerenciamento de calendários contábeis
MonthOpeningController: Abertura de meses contábeis
ClosureController: Fechamento de períodos

Configurações¶

CompanyOptionsController: Opções e parâmetros de empresas
ClosureSettingsController: Configurações de fechamento
FundSettingsController: Configurações de fundos
FundTypeController: Tipos de fundos
QuotaCalculationConfigurationController: Configurações de cálculo de cotas
TaxQuotaCalculationController: Cálculo de taxas de cotas

Históricos e Referências¶

HistoryController: Históricos padrão
ReferenceChartOfAccountsController: Planos de contas de referência
ReferenceChartOfAccountsDetailsController: Detalhes de planos de referência
StandardReleaseController: Liberações padrão
StandardReleaseDataController: Dados de liberações padrão

Rotinas e Acessos¶

RoutineController: Rotinas do sistema
RoutineAccessController: Controle de acesso a rotinas

Processamentos¶

ConsolidationController: Processamento de consolidação contábil

Administrativos¶

DockerLogsController: Visualização de logs Docker
UserController: Gerenciamento de usuários da empresa

2. Services (`company/service/`)¶

63 serviços organizados em interfaces e implementações:

Principais Services¶

CompanyService: Lógica de negócio de empresas
BranchService: Lógica de negócio de filiais
ChartOfAccountsService: Lógica de negócio do plano de contas
DocumentService: Lógica de negócio de documentos
EntryService: Lógica de negócio de lançamentos
BatchService: Lógica de negócio de lotes
CalendarService: Lógica de negócio de calendários
ConsolidationService: Lógica de consolidação contábil
AccountBalanceService: Cálculos de saldos de contas
DailyAccountBalanceService: Saldos diários
MonthlyAccountBalanceService: Saldos mensais

Services de Configuração¶

CompanyOptionsService: Opções de empresas
ClosureSettingsService: Configurações de fechamento
FundSettingsService: Configurações de fundos
QuotaCalculationConfigurationService: Configurações de cotas

Services de Referência¶

ReferenceChartOfAccountsService: Planos de referência
ReferenceChartOfAccountsDetailsService: Detalhes de referência
StandardReleaseService: Liberações padrão

3. Repositories (`company/repository/`)¶

29 repositórios JPA para acesso a dados:

CompanyRepository: Acesso a dados de empresas
BranchRepository: Acesso a dados de filiais
ChartOfAccountsRepository: Acesso a dados do plano de contas
DocumentRepository: Acesso a dados de documentos
EntryRepository: Acesso a dados de lançamentos
BatchRepository: Acesso a dados de lotes
CalendarRepository: Acesso a dados de calendários
AccountBalanceRepository: Acesso a saldos de contas
DailyAccountBalanceRepository: Acesso a saldos diários
MonthlyAccountBalanceRepository: Acesso a saldos mensais

E muitos outros...

4. DTOs (`company/dto/`)¶

40+ DTOs para transferência de dados:

CompanyDTO: Dados de empresa
BranchDTO: Dados de filial
ChartOfAccountsDTO: Dados de conta
DocumentDTO: Dados de documento
EntryDTO: Dados de lançamento
BatchDTO: Dados de lote
CalendarDTO: Dados de calendário

E muitos outros específicos para cada entidade.

5. Models (Entidades JPA)¶

As entidades estão na biblioteca compartilhada ecosif-database:

Company: Entidade de empresa
Branch: Entidade de filial
ChartOfAccounts: Entidade de conta contábil
Document: Entidade de documento
Entry: Entidade de lançamento
Batch: Entidade de lote
Calendar: Entidade de calendário
AccountBalance: Entidade de saldo de conta

E muitas outras...

6. Security (`security/`, starter JWT)¶

io.ecosif.security.jwt.TokenProvider / TokenAuthenticationFilter: starter ecosif-spring-boot-starter-security
LocalUserDetailService: resolve usuário a partir do JWT
WebSecurityConfig: stateless; sem oauth2Login server-side

Removido: handlers OAuth2 em security/auth2/ (fluxo legado).

7. Configuration (`config/`)¶

WebSecurityConfig: Configuração de segurança
OpenApiConfig: Configuração do Swagger/OpenAPI
GlobalExceptionHandler: Tratamento global de exceções
AppProperties: Propriedades da aplicação
WebConfig: Configurações web (CORS, etc.)

8. Integration (`company/integration/`)¶

IntegrationService: Integração com APIs externas (CNPJ, CEP)

Tecnologias Utilizadas¶

Java 17: Linguagem de programação
Spring Boot 2.7.18: Framework Java
Spring Security: Segurança e autenticação
Spring Data JPA: Persistência de dados
PostgreSQL: Banco de dados
ecosif-database: Biblioteca compartilhada de entidades JPA
ModelMapper: Mapeamento entre entidades e DTOs
Flyway: Migrações de banco de dados (desabilitado atualmente)
SpringDoc OpenAPI 3.0: Documentação da API (Swagger)
JJWT 0.11.5: Biblioteca para JWT
Lombok: Redução de boilerplate
Maven: Gerenciamento de dependências
AWS SDK: Integração com AWS S3 (opcional)

Fluxo de Dados¶

Fluxo Típico de Criação de Lançamento¶

sequenceDiagram
    participant C as Cliente
    participant EC as EntryController
    participant ES as EntryService
    participant ER as EntryRepository
    participant DB as Database
    participant DS as DocumentService
    participant CS as CalendarService

    C->>EC: POST /entry
    EC->>ES: save(entryDTO)
    ES->>CS: Validar calendário
    CS-->>ES: Dia disponível
    ES->>DS: Validar documento
    DS-->>ES: Documento válido
    ES->>ER: save(entry)
    ER->>DB: INSERT INTO entry
    DB-->>ER: Entry criado
    ER-->>ES: Entry
    ES-->>EC: EntryDTO
    EC-->>C: 201 Created

Fluxo de Consolidação¶

sequenceDiagram
    participant C as Cliente
    participant CC as ConsolidationController
    participant CS as ConsolidationService
    participant ES as EntryService
    participant ABS as AccountBalanceService
    participant DB as Database

    C->>CC: POST /runconsolidation
    CC->>CS: runConsolidation(dto)
    CS->>ES: Buscar lançamentos
    ES->>DB: SELECT entries
    DB-->>ES: Entries
    ES-->>CS: List<Entry>
    CS->>ABS: Calcular saldos
    ABS->>DB: UPDATE/INSERT balances
    DB-->>ABS: Saldos atualizados
    ABS-->>CS: Consolidado
    CS-->>CC: GenericResponse
    CC-->>C: 200 OK

Banco de Dados¶

Schema¶

O schema é gerenciado pela biblioteca ecosif-database que contém todas as entidades JPA.

Principais Tabelas¶

gr_empresa: Empresas
gr_filial: Filiais
ct_plano_contas: Plano de contas
ct_documento: Documentos
ct_lancamento: Lançamentos
ct_lote: Lotes
ct_calendario: Calendários
ct_saldos: Saldos de contas
ct_saldos_diarios: Saldos diários
ct_saldos_mensais: Saldos mensais

E muitas outras...

Flyway¶

Atualmente Flyway está desabilitado (flyway.enabled: false). As migrações são gerenciadas pela biblioteca ecosif-database ou aplicadas manualmente.

Integração com Outros Serviços¶

ecosif-auth¶

O ecosif-masterdata valida tokens JWT emitidos pelo ecosif-auth. Todos os endpoints (exceto /actuator/** e /swagger-ui/**) requerem autenticação.

ecosif-moviments¶

Pode consumir dados mestres do ecosif-masterdata para processar lançamentos.

ecosif-querys¶

Consulta dados mestres para gerar relatórios e consultas.

APIs Externas¶

Consulta CNPJ: Integração com API externa para validação de CNPJ
Consulta CEP: Integração com API externa para busca de CEP

Segurança¶

Autenticação JWT¶

Todos os endpoints protegidos validam tokens JWT através do TokenAuthenticationFilter.

Multi-Tenancy¶

O sistema suporta isolamento de dados por empresa e filial. Muitos endpoints requerem parâmetros company e branch.

Permissões¶

Alguns endpoints verificam permissões do usuário através de: - UserCompanyBranchService: Associações usuário-empresa-filial - RoutineAccessService: Permissões de acesso a rotinas

Configuração¶

Variáveis de Ambiente Principais¶

POSTGRES_HOST: Host do PostgreSQL
POSTGRES_DB: Nome do banco
POSTGRES_USER: Usuário do banco
POSTGRES_PASSWORD: Senha do banco
AUTH_TOKEN_SECRET: Chave secreta JWT (mesma do ecosif-auth)
ECOSIF_MASTERDATA_PORT: Porta do servidor (padrão: 8081)
AWS_ACCESS_KEY_ID: Chave AWS (opcional, para S3)
AWS_SECRET_ACCESS_KEY: Secret AWS (opcional)
AWS_S3_BUCKET: Bucket S3 (opcional)

Observabilidade¶

Health Checks¶

/actuator/health: Status da aplicação e banco de dados

Métricas¶

/actuator/prometheus: Métricas Prometheus

Logs¶

Configurável via variáveis de ambiente: - LOG_FORMAT: Formato de log (default, json, spring) - ECOSIF_LOGMODE_ROOT: Nível de log root - ECOSIF_LOGMODE_SPRING: Nível de log Spring - ECOSIF_LOGMODE_HIBERNATE_SQL: Nível de log SQL

Datadog¶

Suporte a Datadog APM (opcional, via variáveis de ambiente).

Próximos Passos¶

Para mais informações: - Camadas: Detalhes das camadas - Fluxos: Fluxos detalhados do sistema