first commit
This commit is contained in:
+333
@@ -0,0 +1,333 @@
|
||||
# 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.
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user