Files

T

claudecio f7f052fcb4 fix: ajustar permissões de arquivos e diretórios para o projeto

2026-09-09 19:17:17 -03:00

16 KiB

Executable File

Raw Permalink Blame History

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.

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

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

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

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)

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)

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)

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)

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)

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

usuario: Operadores, administradores e credenciais (hash de senha).
usuario_empresa: Permissões de usuários por filial ou acesso global.

4.2. Contabilidade, Empresas & Configurações Fiscais

contador: Cadastro do escritório de contabilidade (CRC, e-mail, telefone).
certificado: Certificados digitais ICP-Brasil A1 (arquivo binário e senha).
empresa: Matriz e Filiais (hierarquia via auto-relacionamento matriz_id), CNPJ, Inscrição Estadual e dados cadastrais.
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).
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

unidade: Unidades de medida fiscais (UN, CX, KG, LT, SERV, HORA, etc.).
cliente: Destinatários de notas de mercadorias, tomadores de serviços e consumidores.
fornecedor: Fornecedores de insumos e compras.
transportadora: Transportadoras parceiras para frete de mercadorias.
veiculo: Veículos de tração e reboques (placa, renavam, tara, capacidade, tipo de rodado/carroceria).
condutor: Motoristas (nome, CPF, CNH).

4.4. Catálogo de Itens & Tributação

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).
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)

documento_fiscal: Cabeçalho, totais de produtos, impostos vigentes e totais da Reforma Tributária.
documento_fiscal_item: Itens com quantidades, rateios de frete/desconto/seguro e tributação analítica por item.
documento_fiscal_pagamento: Meios de pagamento (PIX, Cartão, Dinheiro, Boleto, troco e TEF).
documento_fiscal_duplicata: Faturas e parcelas de cobrança.
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)

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.
nfse_item: Discriminação analítica dos serviços prestados.
nfse_evento: Cancelamento e substituição de NFS-e.

4.7. Emissão de Transporte (CT-e Modelo 57)

cte: Conhecimento de Transporte Eletrônico (tomador do frete, cidades início/fim com IBGE, tributação).
cte_componente_valor: Componentes tarifários (Frete Valor, Frete Peso, Pedágio, GRIS, Taxa de Despacho).
cte_documento_referenciado: Relação de notas fiscais (NF-e) transportadas.
cte_carga: Pesagens, volumes e unidades de medida da carga.
cte_veiculo_rodoviario: Vínculo do frete com veículo e motorista.
cte_evento: Cancelamento e Cartas de Correção (CC-e) do frete.

4.8. Emissão de Manifesto de Carga (MDF-e Modelo 58)

mdfe: Manifesto Eletrônico de Documentos Fiscais (modal, seguro de carga, averbações e totais consolidados).
mdfe_municipio_carregamento: Pontos de carregamento (código IBGE).
mdfe_municipio_descarregamento: Pontos de descarregamento (código IBGE).
mdfe_percurso_uf: UFs de trânsito em transporte interestadual.
mdfe_veiculo_tracao: Caminhão/veículo de tração.
mdfe_veiculo_reboque: Carretas e reboques acoplados.
mdfe_condutor: Motoristas vinculados à viagem.
mdfe_documento_referenciado: Relação de NF-es e CT-es manifestados.
mdfe_evento: Encerramento de MDF-e, cancelamento e inclusão de condutor.

4.9. Administração do ERP

configuracao: Parâmetros gerais do software.
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)

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)

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)

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

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.
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.
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).
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.

16 KiB Executable File Raw Permalink Blame History