Documentação Funcional — ecosif-database
Público-alvo: Clientes / Negócio / Product Owner
Módulo: ecosif-database
1. Objetivo do Módulo no Ecossistema
O ecosif-database é o modelo de dados compartilhado do ecossistema ds-ecosif. Ele não entrega telas nem APIs diretamente ao usuário final; garante que todos os serviços (autenticação, cadastros, lançamentos, consultas, relatórios, compliance) usem as mesmas definições de empresas, filiais, usuários, plano de contas, lançamentos e documentos.
Em linguagem de negócio:
- O que é: Um “dicionário único” de dados contábeis e cadastrais usado por todos os sistemas eCosif.
- Para que serve: Evitar divergência entre módulos (ex.: um serviço entender “empresa” ou “lançamento” de forma diferente do outro) e permitir evolução do modelo em um só lugar.
- Quem se beneficia: O negócio (dados consistentes), os desenvolvedores (menos duplicação) e a operação (menos integrações frágeis).
2. Funcionalidades em Linguagem de Negócio
Tradução do que o modelo de dados suporta (entidades da biblioteca) para capacidades de negócio:
| Capacidade de negócio | O que o módulo fornece (modelo) |
|---|---|
| Cadastro de empresas | Estrutura de dados para empresa (razão social, CNPJ/CPF, endereço, tipo etc.). |
| Multi-filial | Estrutura de filiais por empresa (nome, inscrições, endereço). |
| Plano de contas | Estrutura de contas contábeis (código, descrição, natureza, nível, indicadores de rateio, patrimônio, etc.). |
| Lançamentos contábeis | Estrutura de documentos e lançamentos (débito/crédito, conta, histórico, valor, data de referência). |
| Lotes contábeis | Estrutura de lotes por empresa/filial/ano/mês para agrupar documentos. |
| Saldos e históricos | Estrutura para saldos (diário, mensal, histórico) e para históricos de documentos e lançamentos. |
| Usuários e acesso | Estrutura de usuário (nome, perfil, validade de senha, troca de senha) e vínculo usuário–empresa–filial. |
| Grupos e permissões | Estrutura de grupos e rotinas (permissões por grupo). |
| Calendário e encerramentos | Estrutura de calendário contábil e de encerramento. |
| Fundos e cotas | Estrutura para parâmetros de fundos, tipo de fundo, valor da cota e configurações COSIF. |
| Plano de contas referencial | Estrutura de plano referencial e seus detalhes. |
| Lançamentos padronizados | Estrutura de padrões de lançamento e dados padronizados. |
Nenhuma dessas funcionalidades é “executada” dentro do ecosif-database; elas são implementadas pelos serviços que usam esta biblioteca (masterdata, movimentos, relatórios, etc.). O ecosif-database apenas padroniza os dados que essas funcionalidades manipulam.
3. Glossário de Termos
Termos encontrados no código e no domínio, com significado em linguagem de negócio:
| Termo | Significado |
|---|---|
| Empresa (Company) | Cadastro da pessoa jurídica ou física no sistema (razão social, CNPJ/CPF, endereço). |
| Filial (Branch) | Unidade de uma empresa (matriz ou filial) com suas próprias inscrições e endereço. |
| Plano de contas (Chart of Accounts) | Conjunto de contas contábeis (código, descrição, natureza débito/crédito, nível hierárquico). |
| Conta contábil | Item do plano de contas ao qual são vinculados lançamentos (débito/crédito). |
| Lançamento (Entry) | Movimentação contábil (uma linha de débito ou de crédito) ligada a um documento e a uma conta. |
| Documento (Document) | Agrupamento de lançamentos (ex.: um documento com várias linhas débito/crédito). |
| Lote (Batch) | Conjunto de documentos por empresa, filial, ano e mês (organização contábil). |
| Histórico (History) | Texto padrão ou código de histórico usado nos lançamentos. |
| Saldo | Saldo de conta em um período (diário, mensal) ou em momento específico; há entidades de histórico de saldo. |
| Encerramento (Closure) | Processo/configuração de fechamento contábil (período). |
| Calendário (Calendar) | Calendário contábil (dias úteis, períodos). |
| Usuário (User) | Pessoa que acessa o sistema (nome, perfil, validade de senha, troca de senha). |
| Grupo (Group) | Conjunto de usuários com permissões comuns. |
| Rotina (Routine) | Funcionalidade ou tela do sistema; acesso é controlado por grupo. |
| COSIF | Referência ao padrão contábil (Comissão de Valores Mobiliários); usado em entidades de fundos e controles. |
| Rateio | Distribuição de valor entre contas (indicadores no plano de contas). |
| Conta patrimônio (Equity) | Conta do patrimônio líquido. |
| Padronizado (Standard Release) | Modelo de lançamento padronizado e seus dados. |
| Tabelas temporárias (*Temp, *Tmp) | Estruturas usadas em processamentos (importação, cálculos intermediários), não necessariamente persistidas a longo prazo como cadastro. |
4. Posicionamento no Ecossistema
flowchart LR
subgraph Negócio["Negócio"]
U[Usuário final]
end
subgraph Servicos["Serviços ds-ecosif"]
A[ecosif-auth]
M[ecosif-masterdata]
V[ecosif-moviments]
Q[ecosif-querys]
R[ecosif-reports]
C[ecosif-compliance]
end
subgraph Lib["ecosif-database"]
E[Modelo de dados único]
end
U --> A
U --> M
U --> V
U --> Q
U --> R
U --> C
A --> E
M --> E
V --> E
Q --> E
R --> E
C --> E
- ecosif-database = modelo de dados compartilhado (empresas, filiais, plano de contas, lançamentos, usuários, etc.).
- Serviços = implementam regras, APIs e telas; todos leem e escrevem usando o mesmo modelo.
- Usuário final = interage apenas com os serviços; não “vê” o ecosif-database, mas depende da consistência que ele garante.
5. Resumo para Clientes / Negócio
- O que é: Biblioteca que define o “dicionário” de dados contábeis e cadastrais do eCosif.
- Objetivo: Unificar o modelo de dados entre todos os módulos (auth, cadastros, lançamentos, relatórios, compliance).
- Funcionalidades (em termos de negócio): Suporta cadastro de empresas e filiais, plano de contas, lançamentos e documentos, lotes, saldos, usuários e permissões, calendário, encerramentos e fundos/cotas — sempre como estrutura de dados usada pelos outros sistemas.
- Glossário: Empresa, Filial, Plano de contas, Lançamento, Documento, Lote, Histórico, Saldo, Encerramento, Usuário, Grupo, Rotina, COSIF, Rateio, etc., conforme tabela acima.
Para detalhes técnicos para desenvolvedores, veja ../architecture/modelo_e_consumo.md. Para variáveis de ambiente, infra e logs, veja ../deploy/variaveis_e_logs.md.