eCosif — Master Data

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

Documentos e Lançamentos

Calendários e Períodos

Configurações

Históricos e Referências

Rotinas e Acessos

Processamentos

Administrativos

2. Services (company/service/)

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

Principais Services

Services de Configuração

Services de Referência

3. Repositories (company/repository/)

29 repositórios JPA para acesso a dados:

E muitos outros...

4. DTOs (company/dto/)

40+ DTOs para transferência de dados:

E muitos outros específicos para cada entidade.

5. Models (Entidades JPA)

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

E muitas outras...

6. Security (security/, starter JWT)

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

7. Configuration (config/)

8. Integration (company/integration/)

Tecnologias Utilizadas

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

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

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

Observabilidade

Health Checks

Métricas

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