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.

Aspecto	Descrição
Packaging	`jar` (sem `spring-boot-maven-plugin`)
Conteúdo	Entidades JPA, utilitários (ex.: `ChartOfAccountsComparator`)
Consumidores	ecosif-auth, ecosif-masterdata, ecosif-moviments, ecosif-querys, ecosif-reports, ecosif-compliance, etc.

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.

Abordagem	Onde é usada	Responsável
Entidades	Persistência, mapeamento ORM	ecosif-database
DTOs	API REST, contratos entre serviços	Cada serviço consumidor
Projections	Consultas que retornam subconjuntos de campos	Cada serviço consumidor

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¶

Tecnologia	Versão	Uso na biblioteca
Java	17	Linguagem
Spring Boot (parent)	2.7.18	BOM e convenções
Spring Data JPA	2.7.x	Anotações JPA e suporte a entidades
PostgreSQL Driver	runtime	Compatibilidade com o banco do ecossistema
Lombok	1.18.30	Getters/Setters/ToString nas entidades
Hibernate Validator	-	Validações JSR-303 (@NotNull, @Size, etc.)
JJWT	0.11.5	Suporte a JWT (usado pelos consumidores que compartilham o classpath)
ModelMapper	3.1.0	Mapeamento (uso nos serviços)
Apache Commons Lang3	3.12.0	Utilitários
AWS (Secrets Manager, etc.)	2.4.2 / 3.0.1	Configuração em serviços que usam a lib

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.