Documentação Técnica — ecosif-database

Público-alvo: Desenvolvedores
Módulo: ecosif-database (biblioteca JAR)

1. Natureza do Módulo

O ecosif-database não é uma aplicação Spring Boot executável. É uma biblioteca Maven (packaging: jar) que centraliza as entidades JPA e utilitários de domínio compartilhados pelos serviços do ecossistema ds-ecosif.

2. Design de Camadas nos Consumidores

Os serviços que dependem desta biblioteca seguem o padrão em camadas. O ecosif-database fornece apenas a camada de modelo (entidades); Controller, Service e Repository ficam nos próprios serviços.

flowchart TB
    subgraph Servico["Serviço consumidor (ex: ecosif-masterdata)"]
        C[Controller]
        S[Service]
        R[Repository]
    end
    subgraph Lib["ecosif-database (JAR)"]
        E[Entidades JPA]
        U[Utilitários]
    end
    C --> S
    S --> R
    R --> E
    S --> U

• Controller: expõe REST; recebe/retorna DTOs ou IDs; chama Service.
• Service: regras de negócio; usa Repository (entidades desta lib) e utilitários (ex.: ChartOfAccountsComparator).
• Repository: interfaces Spring Data JPA nos serviços; tipo das entidades vem do ecosif-database.

Esta biblioteca não contém Controller, Service nem Repository — apenas model e util.

3. Como os Módulos Consomem a lib ecosif-database

3.1 Dependência Maven

No pom.xml do serviço:

<dependency>
    <groupId>io.ecosif.database</groupId>
    <artifactId>ecosif-database</artifactId>
    <version>0.7.01.202512010</version>
</dependency>

O JAR pode ser resolvido pelo repositório local (mvn install) ou pelo CodeArtifact (conforme distributionManagement no pom.xml da lib).

3.2 Entity Scan e Repositories

O serviço precisa escanear as entidades desta lib e definir onde estão os repositórios (no pacote do serviço):

@SpringBootApplication
@EntityScan(basePackages = "io.ecosif.database")
@EnableJpaRepositories(basePackages = "io.ecosif.masterdata") // pacote do serviço
public class Application {
    // ...
}

• @EntityScan("io.ecosif.database") — carrega todas as entidades JPA do JAR.
• @EnableJpaRepositories — aponta para o pacote onde estão as interfaces JpaRepository do serviço (que usam as entidades da lib).

3.3 Fluxo de Uso da Biblioteca

sequenceDiagram
    participant App as Aplicação consumidora
    participant EntityScan as EntityScan
    participant Repo as Repository (no serviço)
    participant DB as PostgreSQL

    App->>EntityScan: Inicialização Spring
    EntityScan->>EntityScan: Carrega io.ecosif.database.*
    App->>Repo: findById(Company, 1L)
    Repo->>DB: SELECT ... FROM gr_empresa
    DB-->>Repo: ResultSet
    Repo-->>App: Company (entidade da lib)

4. DTOs vs Projections

4.1 Papel desta Biblioteca

O ecosif-database expõe apenas entidades JPA (e um utilitário). Não define DTOs nem interfaces de projection.

4.2 Boas Práticas nos Serviços Consumidores

• Não expor entidades JPA diretamente na API REST — usar DTOs para controle de campos e versão do contrato.
• Projections (Spring Data) — para listagens e relatórios que não precisam da entidade inteira, reduzindo carga e N+1:
• Interface projection: interface CompanySummary { Long getId(); String getFiscalName(); }
• Class-based (DTO) projection quando precisar de construtor ou lógica.
• ModelMapper / MapStruct — mapear Entidade ↔ DTO nos serviços; a lib já traz modelmapper como dependência indireta (usada nos serviços que a consomem).

5. Estrutura de Pacotes e Entidades

io.ecosif.database
├── company/
│   ├── model/          # Entidades de domínio contábil e cadastral
│   │   ├── Company.java       → gr_empresa
│   │   ├── Branch.java       → gr_filial
│   │   ├── ChartOfAccounts.java → ct_plano
│   │   ├── Entry.java        → ct_lancamento
│   │   ├── Document.java     → ct_documentos
│   │   ├── Batch.java        → ct_lote
│   │   └── ... (50+ entidades)
│   └── util/
│       └── ChartOfAccountsComparator.java
└── user/
    └── model/
        └── User.java   → gr_user

5.1 Diagrama de Entidades Principais (Domínio Contábil)

erDiagram
    Company ||--o{ Branch : "possui"
    Company ||--o{ ChartOfAccounts : "plano de contas"
    Branch ||--o{ Batch : "lotes"
    Batch ||--o{ Document : "documentos"
    Document ||--o{ Entry : "lançamentos"
    ChartOfAccounts ||--o{ Entry : "conta"
    User }o--|| UserCompanyBranch : "acesso"
    Branch ||--o{ UserCompanyBranch : "filial"
    Company ||--o{ UserCompanyBranch : "empresa"

    Company : Long id
    Company : String taxId
    Company : String fiscalName
    Branch : Long id
    Branch : String company
    Branch : String branch
    ChartOfAccounts : Long id
    ChartOfAccounts : String cdAccounting
    Document : Long id
    Document : Long batchId
    Entry : Long id
    Entry : Long documentId
    Entry : Long contaId
    Batch : Long id
    User : Long id

6. Tecnologias e Dependências

7. Utilitário: ChartOfAccountsComparator

Ordenação numérica de códigos de plano de contas (ex.: 1.1, 1.2.1, 1.10.1), evitando ordenação alfabética incorreta.

Exemplo de uso no serviço:

import io.ecosif.database.company.util.ChartOfAccountsComparator;

List<String> accountCodes = Arrays.asList("1.10.1", "1.1", "1.2.1");
accountCodes.sort(new ChartOfAccountsComparator());
// Resultado: ["1.1", "1.2.1", "1.10.1"]

8. Convenções de Código

• Entidades: javax.persistence.* (JPA 2.x), Lombok @Getter, @Setter, @ToString.
• Nomes de tabelas: prefixos gr_* (cadastros gerais), ct_* (contábil).
• IDs: @GeneratedValue(strategy = GenerationType.IDENTITY).
• Validação: @NotNull, @Size onde aplicável.

Para variáveis de ambiente, requisitos de infra e logs, veja ../deploy/variaveis_e_logs.md. Para visão de negócio e glossário, veja ../user/visao_geral.md.