# 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
(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
(CRC / Dados Contábeis)"] -->|assessoria| EMP["🏢 empresa
(Matriz / Filiais)"] CERT["🔑 certificado
(ICP-Brasil A1)"] -->|assinatura digital| EMP USU["👤 usuario
(Operadores / Administradores)"] -->|autenticação| UE["🔐 usuario_empresa
(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
(Destinatários / Tomadores)"] EMP --> FORN["🏭 fornecedor
(Compras / Insumos)"] EMP --> TRANS["🚚 transportadora
(Parceiros de Frete)"] EMP --> VEIC["🚛 veiculo
(Tração / Reboques)"] EMP --> COND["🪪 condutor
(Motoristas / CNH)"] EMP --> PROD["📦 produto
(GTIN 'SEM GTIN' / NCM / CEST / Reforma IBS-CBS-IS)"] UNID["📐 unidade
(UN, KG, LT, CX, M2)"] -->|unidade comercial & tributável| PROD EMP --> SERV["🛠️ servico
(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
(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
(Produtos, Valores & Impostos Analíticos)"] PROD["🏷️ produto"] -->|herança de tributação| DFI DF --> DFP["💳 documento_fiscal_pagamento
(Meios de Pagamento / Troco / TEF)"] DF --> DFD["📅 documento_fiscal_duplicata
(Faturas & Parcelas a Receber)"] DF --> DFE["⚡ documento_fiscal_evento
(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
(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
(Discriminação Analítica dos Serviços)"] SERV["📋 servico"] -->|LC 116, cTribNac & Alíquotas| NFSE_I NFSE --> NFSE_E["⚡ nfse_evento
(Cancelamento & Substituição)"] ``` --- ### 3.5. Emissão de Transporte (CT-e Modelo 57) ```mermaid flowchart TD EMP["🏢 empresa (Transportador Emitente)"] --> CTE["🚛 cte
(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
(Frete Peso, Frete Valor, Pedágio, GRIS)"] CTE --> CTE_DR["📑 cte_documento_referenciado
(Chaves das NF-e transportadas)"] CTE --> CTE_C["⚖️ cte_carga
(Peso Bruto, Cubagem, Qtd Volumes)"] CTE --> CTE_V["🛞 cte_veiculo_rodoviario
(Veículo e Motorista vinculados)"] CTE --> CTE_E["⚡ cte_evento
(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
(Viagem, Modal Rodoviário, Seguro de Carga)"] SF["🔢 serie_fiscal"] -.->|série MDF-e| MDFE MDFE --> MDFE_MC["📍 mdfe_municipio_carregamento
(Cidades de Carregamento IBGE)"] MDFE --> MDFE_MD["🏁 mdfe_municipio_descarregamento
(Cidades de Descarregamento IBGE)"] MDFE --> MDFE_PU["🗺️ mdfe_percurso_uf
(UFs de Trânsito / Passagem)"] MDFE --> MDFE_T["🚛 mdfe_veiculo_tracao
(Caminhão / Cavalo Mecânico)"] MDFE --> MDFE_R["🚜 mdfe_veiculo_reboque
(Carretas e Semirreboques)"] MDFE --> MDFE_C["🪪 mdfe_condutor
(Motoristas da Viagem)"] MDFE --> MDFE_DR["📑 mdfe_documento_referenciado
(Relação de NF-es e CT-es manifestados)"] MDFE --> MDFE_E["⚡ mdfe_evento
(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.