333 lines
16 KiB
Markdown
333 lines
16 KiB
Markdown
# Guia de Arquitetura e Fluxo do Banco de Dados - Workbloom ERP
|
|
|
|
Este documento descreve a arquitetura completa, a modelagem das **40 tabelas** em **PostgreSQL** e os fluxos de dados do sistema de emissão fiscal **Workbloom ERP**.
|
|
|
|
O script de instalação correspondente está disponível em [`install_database.sql`](./install_database.sql).
|
|
|
|
---
|
|
|
|
## 1. Módulos do Sistema e Documentos Fiscais Suportados
|
|
|
|
| Módulo Fiscal | Modelo | Descrição |
|
|
| :--- | :--- | :--- |
|
|
| **NF-e** | Modelo 55 | Nota Fiscal Eletrônica de Mercadorias (vendas, compras, devoluções, transferências, importação/exportação). |
|
|
| **NFC-e** | Modelo 65 | Nota Fiscal de Consumidor Eletrônica (frente de caixa, varejo, contingência off-line e QR-Code). |
|
|
| **NFS-e** | Serviços | Nota Fiscal de Serviços Eletrônica (compatível com **Padrão Nacional DPS / Receita Federal** e **Padrão Municipal ABRASF**). |
|
|
| **CT-e** | Modelo 57 | Conhecimento de Transporte Eletrônico (fretes rodoviários, tomadores e componentes tarifários). |
|
|
| **MDF-e** | Modelo 58 | Manifesto Eletrônico de Documentos Fiscais (transporte de cargas, veículos, condutores, seguro e manifesto de NFe/CTe). |
|
|
|
|
---
|
|
|
|
## 2. Visão Macro da Arquitetura
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
subgraph CAMADA_1 ["1. Camada de Acesso & Multi-Tenant"]
|
|
U["👤 usuario & usuario_empresa<br/>(Autenticação, Perfis de Acesso e Filiais)"]
|
|
end
|
|
|
|
subgraph CAMADA_2 ["2. Camada de Governança & Multi-Empresas"]
|
|
EMP["🏢 empresa (Matriz & Filiais via matriz_id)"]
|
|
CFG["⚙️ empresa_configuracao_fiscal (Ambientes SEFAZ, Certificados A1 & Tokens)"]
|
|
SER["🔢 serie_fiscal (Séries Dinâmicas 55, 65, 57, 58, NFS)"]
|
|
end
|
|
|
|
subgraph CAMADA_3 ["3. Camada de Cadastros & Catálogo Tributário"]
|
|
CAD["👥 Clientes, Fornecedores, Transportadoras, Veículos & Condutores"]
|
|
CAT["📦 Produtos (GTIN 'SEM GTIN', NCM, IBS/CBS/IS) & Serviços (LC 116, cTribNac)"]
|
|
end
|
|
|
|
subgraph CAMADA_4 ["4. Camada de Motores de Emissão Fiscal (DF-e)"]
|
|
NFE["📑 NF-e 55 & NFC-e 65 (Mercadorias & PDV)"]
|
|
NFSE["📝 NFS-e Nacional / DPS (Serviços & ADN)"]
|
|
CTE["🚛 CT-e 57 (Transporte de Carga & Frete)"]
|
|
MDFE["🚚 MDF-e 58 (Manifesto de Carga & Viagem)"]
|
|
end
|
|
|
|
CAMADA_1 --> CAMADA_2
|
|
CAMADA_2 --> CAMADA_3
|
|
CAMADA_3 --> CAMADA_4
|
|
CAMADA_2 --> CAMADA_4
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Diagramas Modulares de Relacionamento
|
|
|
|
Para garantir máxima legibilidade, clareza e espaçamento, os relacionamentos foram organizados por domínio funcional:
|
|
|
|
### 3.1. Governança, Matriz/Filiais, Usuários e Séries Fiscais
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
CONT["📊 contador<br/>(CRC / Dados Contábeis)"] -->|assessoria| EMP["🏢 empresa<br/>(Matriz / Filiais)"]
|
|
CERT["🔑 certificado<br/>(ICP-Brasil A1)"] -->|assinatura digital| EMP
|
|
|
|
USU["👤 usuario<br/>(Operadores / Administradores)"] -->|autenticação| UE["🔐 usuario_empresa<br/>(Permissões por Filial)"]
|
|
EMP -->|concede acesso| UE
|
|
|
|
EMP -->|ambientes SEFAZ / tokens| ECF["⚙️ empresa_configuracao_fiscal"]
|
|
EMP -->|numeração e modelos| SF["🔢 serie_fiscal"]
|
|
```
|
|
|
|
---
|
|
|
|
### 3.2. Cadastros Base, Logística e Catálogo Tributário
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
EMP["🏢 empresa"] --> CLI["👥 cliente<br/>(Destinatários / Tomadores)"]
|
|
EMP --> FORN["🏭 fornecedor<br/>(Compras / Insumos)"]
|
|
EMP --> TRANS["🚚 transportadora<br/>(Parceiros de Frete)"]
|
|
EMP --> VEIC["🚛 veiculo<br/>(Tração / Reboques)"]
|
|
EMP --> COND["🪪 condutor<br/>(Motoristas / CNH)"]
|
|
|
|
EMP --> PROD["📦 produto<br/>(GTIN 'SEM GTIN' / NCM / CEST / Reforma IBS-CBS-IS)"]
|
|
UNID["📐 unidade<br/>(UN, KG, LT, CX, M2)"] -->|unidade comercial & tributável| PROD
|
|
|
|
EMP --> SERV["🛠️ servico<br/>(LC 116 / cTribNac / ISS / IBS-CBS)"]
|
|
```
|
|
|
|
---
|
|
|
|
### 3.3. Emissão de Mercadorias (NF-e Modelo 55 & NFC-e Modelo 65)
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
EMP["🏢 empresa (Emitente)"] --> DF["📑 documento_fiscal<br/>(Cabeçalho, Totais & Status DF-e)"]
|
|
SF["🔢 serie_fiscal"] -.->|reserva número| DF
|
|
CLI["👥 cliente"] -->|destinatário / consumidor| DF
|
|
TRANS["🚚 transportadora"] -.->|dados do frete| DF
|
|
|
|
DF --> DFI["📦 documento_fiscal_item<br/>(Produtos, Valores & Impostos Analíticos)"]
|
|
PROD["🏷️ produto"] -->|herança de tributação| DFI
|
|
|
|
DF --> DFP["💳 documento_fiscal_pagamento<br/>(Meios de Pagamento / Troco / TEF)"]
|
|
DF --> DFD["📅 documento_fiscal_duplicata<br/>(Faturas & Parcelas a Receber)"]
|
|
DF --> DFE["⚡ documento_fiscal_evento<br/>(Cancelamento, CC-e & Inutilização)"]
|
|
```
|
|
|
|
---
|
|
|
|
### 3.4. Emissão de Serviços (NFS-e Padrão Nacional & Municipal)
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
EMP["🏢 empresa (Prestadora)"] --> NFSE["📝 nfse<br/>(DPS, Chave 50 dígitos, DANFSe ADN)"]
|
|
SF["🔢 serie_fiscal"] -.->|série RPS / DPS| NFSE
|
|
CLI["👥 cliente"] -->|tomador do serviço| NFSE
|
|
|
|
NFSE --> NFSE_I["🛠️ nfse_item<br/>(Discriminação Analítica dos Serviços)"]
|
|
SERV["📋 servico"] -->|LC 116, cTribNac & Alíquotas| NFSE_I
|
|
|
|
NFSE --> NFSE_E["⚡ nfse_evento<br/>(Cancelamento & Substituição)"]
|
|
```
|
|
|
|
---
|
|
|
|
### 3.5. Emissão de Transporte (CT-e Modelo 57)
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
EMP["🏢 empresa (Transportador Emitente)"] --> CTE["🚛 cte<br/>(Cabeçalho, Origem/Destino IBGE, Tomador)"]
|
|
SF["🔢 serie_fiscal"] -.->|série CT-e| CTE
|
|
CLI["👥 cliente"] -->|tomador do serviço de frete| CTE
|
|
|
|
CTE --> CTE_CV["💰 cte_componente_valor<br/>(Frete Peso, Frete Valor, Pedágio, GRIS)"]
|
|
CTE --> CTE_DR["📑 cte_documento_referenciado<br/>(Chaves das NF-e transportadas)"]
|
|
CTE --> CTE_C["⚖️ cte_carga<br/>(Peso Bruto, Cubagem, Qtd Volumes)"]
|
|
CTE --> CTE_V["🛞 cte_veiculo_rodoviario<br/>(Veículo e Motorista vinculados)"]
|
|
CTE --> CTE_E["⚡ cte_evento<br/>(Cancelamento & CC-e)"]
|
|
```
|
|
|
|
---
|
|
|
|
### 3.6. Manifesto Eletrônico de Documentos Fiscais (MDF-e Modelo 58)
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
EMP["🏢 empresa (Emitente do Manifesto)"] --> MDFE["🚚 mdfe<br/>(Viagem, Modal Rodoviário, Seguro de Carga)"]
|
|
SF["🔢 serie_fiscal"] -.->|série MDF-e| MDFE
|
|
|
|
MDFE --> MDFE_MC["📍 mdfe_municipio_carregamento<br/>(Cidades de Carregamento IBGE)"]
|
|
MDFE --> MDFE_MD["🏁 mdfe_municipio_descarregamento<br/>(Cidades de Descarregamento IBGE)"]
|
|
MDFE --> MDFE_PU["🗺️ mdfe_percurso_uf<br/>(UFs de Trânsito / Passagem)"]
|
|
|
|
MDFE --> MDFE_T["🚛 mdfe_veiculo_tracao<br/>(Caminhão / Cavalo Mecânico)"]
|
|
MDFE --> MDFE_R["🚜 mdfe_veiculo_reboque<br/>(Carretas e Semirreboques)"]
|
|
MDFE --> MDFE_C["🪪 mdfe_condutor<br/>(Motoristas da Viagem)"]
|
|
|
|
MDFE --> MDFE_DR["📑 mdfe_documento_referenciado<br/>(Relação de NF-es e CT-es manifestados)"]
|
|
MDFE --> MDFE_E["⚡ mdfe_evento<br/>(Encerramento, Cancelamento & Incl. Condutor)"]
|
|
```
|
|
|
|
---
|
|
|
|
### 3.7. Rastreabilidade e Integração Logística (NF-e ➔ CT-e ➔ MDF-e)
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
NFE["📦 NF-e (Mercadorias Faturadas)"] -->|Chave NF-e em cte_documento_referenciado| CTE["🚛 CT-e (Prestação do Frete Rodoviário)"]
|
|
CTE -->|Chave CT-e em mdfe_documento_referenciado| MDFE["🚚 MDF-e (Manifesto da Viagem com Veículos e Condutor)"]
|
|
NFE -.->|Carga Própria / Transporte Próprio| MDFE
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Catálogo Completo das 40 Tabelas
|
|
|
|
### 4.1. Autenticação & Multi-Tenant
|
|
1. **`usuario`**: Operadores, administradores e credenciais (hash de senha).
|
|
2. **`usuario_empresa`**: Permissões de usuários por filial ou acesso global.
|
|
|
|
### 4.2. Contabilidade, Empresas & Configurações Fiscais
|
|
3. **`contador`**: Cadastro do escritório de contabilidade (CRC, e-mail, telefone).
|
|
4. **`certificado`**: Certificados digitais ICP-Brasil A1 (arquivo binário e senha).
|
|
5. **`empresa`**: Matriz e Filiais (hierarquia via auto-relacionamento `matriz_id`), CNPJ, Inscrição Estadual e dados cadastrais.
|
|
6. **`empresa_configuracao_fiscal`**: Desacoplamento de ambientes SEFAZ (Produção / Produção Restrita), contingência, tokens CSC (NFC-e) e credenciais de prefeituras/Receita Federal (NFS-e Nacional).
|
|
7. **`serie_fiscal`**: Séries fiscais dinâmicas por filial e por modelo de documento (`55`, `65`, `57`, `58`, `NFS`), controlando a numeração sequencial.
|
|
|
|
### 4.3. Cadastros Base & Apoio Logístico
|
|
8. **`unidade`**: Unidades de medida fiscais (UN, CX, KG, LT, SERV, HORA, etc.).
|
|
9. **`cliente`**: Destinatários de notas de mercadorias, tomadores de serviços e consumidores.
|
|
10. **`fornecedor`**: Fornecedores de insumos e compras.
|
|
11. **`transportadora`**: Transportadoras parceiras para frete de mercadorias.
|
|
12. **`veiculo`**: Veículos de tração e reboques (placa, renavam, tara, capacidade, tipo de rodado/carroceria).
|
|
13. **`condutor`**: Motoristas (nome, CPF, CNH).
|
|
|
|
### 4.4. Catálogo de Itens & Tributação
|
|
14. **`produto`**: Mercadorias com código GTIN (`DEFAULT 'SEM GTIN'`), NCM, CEST, CFOPs, regras de ICMS (CST/CSOSN, MVA, FCP, ST, Redução de Base), PIS, COFINS, IPI e campos da **Reforma Tributária** (**IBS**, **CBS**, **Imposto Seletivo**, `c_classif_trib`, `cBenef`).
|
|
15. **`servico`**: Catálogo de serviços com código da **LC 116/2003** (`item_lista_servico`), CNAE, código tributário municipal, `cTribNac` (Padrão Nacional), alíquotas de ISS, retenções federais (PIS, COFINS, INSS, IRRF, CSLL) e Reforma Tributária (IBS/CBS).
|
|
|
|
### 4.5. Emissão de Mercadorias (NF-e 55 & NFC-e 65)
|
|
16. **`documento_fiscal`**: Cabeçalho, totais de produtos, impostos vigentes e totais da Reforma Tributária.
|
|
17. **`documento_fiscal_item`**: Itens com quantidades, rateios de frete/desconto/seguro e tributação analítica por item.
|
|
18. **`documento_fiscal_pagamento`**: Meios de pagamento (PIX, Cartão, Dinheiro, Boleto, troco e TEF).
|
|
19. **`documento_fiscal_duplicata`**: Faturas e parcelas de cobrança.
|
|
20. **`documento_fiscal_evento`**: Cancelamento, Carta de Correção (CC-e) e Inutilização.
|
|
|
|
### 4.6. Emissão de Serviços (NFS-e Padrão Nacional & Municipal)
|
|
21. **`nfse`**: Cabeçalho da NFS-e com dados da DPS/RPS, chave de acesso de **50 dígitos**, link do DANFSe oficial do ADN (`link_danfse_pdf`), QR-Code, deduções, retenções e valor líquido.
|
|
22. **`nfse_item`**: Discriminação analítica dos serviços prestados.
|
|
23. **`nfse_evento`**: Cancelamento e substituição de NFS-e.
|
|
|
|
### 4.7. Emissão de Transporte (CT-e Modelo 57)
|
|
24. **`cte`**: Conhecimento de Transporte Eletrônico (tomador do frete, cidades início/fim com IBGE, tributação).
|
|
25. **`cte_componente_valor`**: Componentes tarifários (Frete Valor, Frete Peso, Pedágio, GRIS, Taxa de Despacho).
|
|
26. **`cte_documento_referenciado`**: Relação de notas fiscais (NF-e) transportadas.
|
|
27. **`cte_carga`**: Pesagens, volumes e unidades de medida da carga.
|
|
28. **`cte_veiculo_rodoviario`**: Vínculo do frete com veículo e motorista.
|
|
29. **`cte_evento`**: Cancelamento e Cartas de Correção (CC-e) do frete.
|
|
|
|
### 4.8. Emissão de Manifesto de Carga (MDF-e Modelo 58)
|
|
30. **`mdfe`**: Manifesto Eletrônico de Documentos Fiscais (modal, seguro de carga, averbações e totais consolidados).
|
|
31. **`mdfe_municipio_carregamento`**: Pontos de carregamento (código IBGE).
|
|
32. **`mdfe_municipio_descarregamento`**: Pontos de descarregamento (código IBGE).
|
|
33. **`mdfe_percurso_uf`**: UFs de trânsito em transporte interestadual.
|
|
34. **`mdfe_veiculo_tracao`**: Caminhão/veículo de tração.
|
|
35. **`mdfe_veiculo_reboque`**: Carretas e reboques acoplados.
|
|
36. **`mdfe_condutor`**: Motoristas vinculados à viagem.
|
|
37. **`mdfe_documento_referenciado`**: Relação de NF-es e CT-es manifestados.
|
|
38. **`mdfe_evento`**: Encerramento de MDF-e, cancelamento e inclusão de condutor.
|
|
|
|
### 4.9. Administração do ERP
|
|
39. **`configuracao`**: Parâmetros gerais do software.
|
|
40. **`pagamento_empresa`**: Controle de faturamento e mensalidades das empresas clientes.
|
|
|
|
---
|
|
|
|
## 5. Fluxos Operacionais Passo a Passo
|
|
|
|
### 5.1. Fluxo de Emissão de Mercadorias (NF-e / NFC-e)
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
autonumber
|
|
actor Operador as Operador / PDV
|
|
participant API as Workbloom API
|
|
participant DB as Banco PostgreSQL
|
|
participant SEFAZ as SEFAZ (DF-e)
|
|
|
|
Operador->>API: Inicia venda de produtos
|
|
API->>DB: Consulta produto (NCM, CEST, GTIN 'SEM GTIN', CFOP, Impostos)
|
|
API->>DB: Obtém próximo número sequencial em serie_fiscal
|
|
API->>DB: Insere documento_fiscal (Status: DIGITACAO)
|
|
API->>DB: Insere documento_fiscal_item (Cálculo analítico dos tributos)
|
|
API->>DB: Insere documento_fiscal_pagamento (Formas de pagamento + Troco)
|
|
API->>DB: Insere documento_fiscal_duplicata (se parcelado)
|
|
API->>API: Assina XML com certificado digital A1
|
|
API->>SEFAZ: Transmite Lote DF-e
|
|
SEFAZ-->>API: Retorno Autorizado (cStat 100 + Protocolo + Chave 44 dígitos)
|
|
API->>DB: Atualiza documento_fiscal (Status: AUTORIZADA, Protocolo, XML)
|
|
API->>DB: Incrementa ultimo_numero em serie_fiscal
|
|
API-->>Operador: Venda concluída e DANFE/Cupom emitido
|
|
```
|
|
|
|
---
|
|
|
|
### 5.2. Fluxo de Emissão de Serviços (NFS-e Nacional & Municipal)
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
autonumber
|
|
actor Prestador as Prestador de Serviço
|
|
participant API as Workbloom API
|
|
participant DB as Banco PostgreSQL
|
|
participant ADN as ADN / Receita Federal (NFS-e)
|
|
|
|
Prestador->>API: Emite serviço para Tomador (cliente_id)
|
|
API->>DB: Consulta servico (item_lista_servico LC 116, cTribNac, alíquotas)
|
|
API->>DB: Insere nfse (Gera id_dps, Status: DIGITACAO)
|
|
API->>DB: Insere nfse_item (Discriminação detalhada do serviço)
|
|
API->>API: Gera XML da DPS assinado
|
|
API->>ADN: Envia DPS via API REST
|
|
ADN-->>API: Autorizado (Chave de 50 dígitos, link_danfse_pdf, qrcode_url_nfse)
|
|
API->>DB: Atualiza nfse (Status: EMITIDA, chave_acesso 50 dig, link_danfse_pdf)
|
|
API-->>Prestador: NFS-e Autorizada e DANFSe disponível
|
|
```
|
|
|
|
---
|
|
|
|
### 5.3. Fluxo de Logística Integrada (CT-e 57 + MDF-e 58)
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
subgraph ETAPA_1 ["1️⃣ Emissão do CT-e (Modelo 57 - Frete Rodoviário)"]
|
|
C1["Definir Tomador do Frete (Remetente, Destinatário ou Terceiro)"]
|
|
C2["Informar Cidades de Início e Término da Prestação (Códigos IBGE)"]
|
|
C3["Vincular Chaves das NF-e transportadas em cte_documento_referenciado"]
|
|
C4["Compor Valores do Frete (Frete Peso, Frete Valor, Pedágio, GRIS)"]
|
|
C5["Vincular Veículo e Motorista em cte_veiculo_rodoviario"]
|
|
C6["Transmitir e Autorizar na SEFAZ ➔ Gera Chave CT-e (44 dígitos)"]
|
|
|
|
C1 --> C2 --> C3 --> C4 --> C5 --> C6
|
|
end
|
|
|
|
subgraph ETAPA_2 ["2️⃣ Emissão do MDF-e (Modelo 58 - Manifesto de Carga)"]
|
|
M1["Criar Manifesto com UFs de Carregamento e Descarregamento"]
|
|
M2["Informar Rota e UFs de Passagem em mdfe_percurso_uf"]
|
|
M3["Vincular Chaves dos CT-e e NF-e em mdfe_documento_referenciado"]
|
|
M4["Definir Veículo de Tração, Reboques Acoplados e Condutores"]
|
|
M5["Informar Apólice e Averbação do Seguro de Carga"]
|
|
M6["Transmitir e Autorizar na SEFAZ ➔ DAMDFE de Trânsito Liberado"]
|
|
M7["Chegada ao Destino Final: Registrar Evento de ENCERRAMENTO"]
|
|
|
|
M1 --> M2 --> M3 --> M4 --> M5 --> M6 --> M7
|
|
end
|
|
|
|
C6 ==>|Chave CT-e Referenciada| M3
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Boas Práticas para o Desenvolvimento da API
|
|
|
|
1. **UUIDs Controlados pelo Software (Recomendado UUID v7)**:
|
|
- Todas as tabelas principais possuem coluna `"uuid" UUID NOT NULL` sem valor padrão no banco. A sua API/Backend deve gerar o UUID (preferencialmente **UUID v7** por ser ordenado cronologicamente, otimizando os índices B-Tree do PostgreSQL) antes do `INSERT`.
|
|
2. **Transações Atômicas (`BEGIN ... COMMIT`)**:
|
|
- Emita os documentos fiscais (cabeçalho, itens, pagamentos e incremento de série) dentro de uma mesma transação para garantir integridade absoluta.
|
|
3. **Padrão de Precisão Numérica**:
|
|
- Valores monetários (R$): `NUMERIC(15, 2)`.
|
|
- Quantidades, pesos, alíquotas e fatores de conversão: `NUMERIC(15, 4)` (exigência técnica da SEFAZ e Receita Federal).
|
|
4. **Tratamento do GTIN**:
|
|
- Se o produto não tiver código de barras EAN/GTIN cadastrado, o campo no banco já adota o padrão oficial `SEM GTIN` para evitar rejeições 883 e 888 na SEFAZ. |