Empresa e Estabelecimento

Modo isolado · N organizações, uma empresa cada

Cada CNPJ vira um tenant, opcionalmente sob um tenant Group. O isolamento é estrutural: o dado da empresa A não é filtrado do dado da empresa B, ele está em outra fronteira. É o modo para quem tem restrição de verdade — empresas concorrentes dentro do mesmo grupo, sociedade com terceiros, exigência de auditoria independente.

O que custa: catálogo, fornecedores homologados, estrutura de centro de custo, papéis e alçadas são recadastrados por empresa, e não sincronizam. Aprovação consolidada não existe. Relatório do grupo exige leitura cross-tenant.

Modo consolidado · uma organização, N empresas

O tenant é o grupo econômico. Cadastro mestre é único e compartilhado; documento, orçamento, conta contábil e alçada são por empresa. O isolamento entre empresas passa a ser escopo — companyId vindo do token, nunca do cliente.

O que ganha: matriz aprova pedido de filial com uma política, não com integração. Fornecedor é homologado uma vez. Consolidado do grupo é consulta comum.

O critério de qual vender

Não é tamanho do grupo nem número de CNPJs. É uma pergunta só: as empresas do grupo podem ver o cadastro mestre umas das outras? Catálogo, fornecedores, estrutura de centro de custo, tabela de preço. Sim — que é o caso da maioria dos grupos brasileiros, porque a estrutura é espelhada mesmo — consolidado. Não — tenants separados, e o cliente aceita duplicar cadastro.

A pergunta é sobre mestre, não sobre documento. Esconder as requisições da empresa B do usuário da empresa A o modo consolidado faz bem; o que ele não faz é esconder que a empresa B existe.

Na dúvida, consolidado

Um tenant consolidado consegue se comportar como isolado: escopa todo usuário a uma empresa, nunca cria registro corporativo, e na prática ninguém vê nada da outra. O inverso não existe sem cross-tenant. Migração entre os dois é dolorosa nos dois sentidos — juntar catálogos com códigos colidindo, ou partir documentos — então erra-se para o lado reversível por configuração.

A garantia muda de natureza — e isso precisa ser dito

No modo isolado a separação é estrutural: é outro tenant. No consolidado ela vira filtro, e filtro é aplicação. É um rebaixamento real, e o desenho abaixo existe para devolver a força perdida — não para fingir que ela não se perdeu.

O conjunto permitido é resolvido no servidor, a cada requisição

O token é do GrydAuth e não muda — ele traz userId, tenantId, papéis e permissões, e não traz empresa. A partir desses dois primeiros, o nexio-service resolve o conjunto de empresas permitidas no mesmo ponto em que já monta o contexto do tenant: uma leitura indexada em UserCompanyScope, dentro da requisição, sem cache entre requisições até que se prove gargalo.

O cliente pode mandar um establishmentId — ele precisa, porque o usuário escolhe no formulário. O que ele não pode é que o valor seja aceito: em escrita, é validado contra o conjunto resolvido e fora dele responde 404; em listagem, o conjunto resolvido é o filtro, e um companyId na query apenas intersecta com ele. Nunca substitui.

Se o tenant é RLS, a empresa entra na mesma política

Onde o isolamento de tenant já é row-level security no Postgres, o conjunto resolvido entra na mesma policy — SET LOCAL na transação e a política lendo current_setting — e a separação volta a ser estrutural, sem depender de claim. Onde o filtro de tenant é aplicação, a empresa não piora nada: é o mesmo nível de risco que já se aceita hoje.

Fora de escopo responde 404, não 403

Empresa que existe mas não está no escopo do usuário se comporta como empresa que não existe. É a mesma decisão já tomada em COST_CENTER_NOT_FOUND — "não existe neste tenant, inclusive quando existe em outro". 403 confirmaria a existência do registro, que é metade do que um atacante quer.

A tabela só estreita — nunca concede

UserCompanyScope não dá organização, não dá papel e não dá permissão: quem decide isso continua sendo o token do GrydAuth. Ela só responde em quais empresas daquele tenant o que o token já concedeu tem efeito. A consequência prática importa: uma linha órfã — usuário removido da organização no gryd — é inerte, porque o token nunca mais traz aquele tenant. Não existe escalonamento de privilégio possível por este caminho, e por isso a ausência de chave estrangeira para o gryd não é uma fragilidade.

O que precisa ser garantido é o outro lado: companyId tem que ser de uma empresa do mesmo tenant da linha. Aí a chave é composta e local, dentro do esquema do Nexio: (tenantId, companyId) referenciando companies(tenantId, id), com índice único do lado da empresa. O banco recusa; ninguém precisa lembrar de validar.

Nulo = todas. Em toda parte.

UserCompanyScope.companyId nulo é acesso a todas as empresas. CostCenter.companyId nulo é nó corporativo. GLAccountCompany ausente é conta habilitada. Uma convenção só, em três lugares, em vez de três invenções — e nunca "nenhum" nem "não sei".

Nulo é escolha explícita, não o valor que sobra. No cadastro, "vale para todas as empresas" é uma opção marcada, com o efeito escrito ao lado — nunca o comportamento de um campo que ninguém preencheu.

Sugerida em cascata, escolhida por gente

A conta da fatia de rateio é sugerida por, nesta ordem: 1 Item.defaultGlAccountId, 2 CategoryNode.defaultGlAccountId do nó do item, subindo a árvore de categoria até achar, 3 vazio. Sempre editável por quem tem permissão, e sempre com a origem visível na interface — "sugerida pela categoria Materiais de escritório" é a diferença entre um campo que o usuário confere e um campo que ele ignora.

Nenhuma das duas árvores manda na outra

Centro de custo responde quem paga; conta contábil responde que natureza é o gasto. A linha carrega as duas, e derivar uma da outra é o erro que transforma relatório contábil em relatório gerencial errado. Os dois eixos se cruzam na fatia de rateio e em nenhum outro lugar.

O Nexio classifica, não escritura

A conta existe para que o documento saia classificado e a integração com o ERP não precise adivinhar. Partida dobrada, encerramento, razão e balancete continuam do outro lado. Essa fronteira precisa estar escrita porque é a primeira coisa que um controller pede na demo.

Quando os dois são de empresas diferentes

Permitido, e só permitido, quando o usuário tem escopo nas duas empresas. É a única regra necessária: quem pode ver as duas pode relacionar as duas.

A transferência contábil fica fora

Empresa A comprou para a empresa B gera, no mundo real, um acerto entre elas — nota de transferência, rateio intercompany, ou um lançamento manual. Isso é ERP e continua sendo ERP. O que o Nexio faz é registrar o fato com precisão suficiente para que o acerto seja possível, o que é exatamente o que o campo entrega.

CNPJ alfanumérico — em produção desde 31/07/2026

Coluna varchar, nunca numérica, dos dois lados do produto. Os 12 primeiros caracteres aceitam A–Z; os 2 dígitos verificadores continuam numéricos e o cálculo usa ASCII − 48. Já era regra em Supplier; entra idêntica em Company e Establishment.

IBS e CBS obrigatórios na NF-e desde 03/08/2026

Documento fiscal eletrônico não é autorizado sem os campos de IBS e CBS preenchidos, com a alíquota de teste de 1% (0,1% IBS e 0,9% CBS) durante 2026. O Nexio não emite NF-e — mas recebe, e toda nota que chegar já vem com esses campos. O módulo de nota e o three-way match nascem tendo que lê-los.

Para esta spec a consequência é uma só, e é a razão de o estabelecimento existir: os campos que decidem tributação e crédito estão espalhados nos dois níveis — regime na empresa, contribuinte de ICMS, Suframa e município IBGE no estabelecimento. Modelar filial como endereço perde metade deles.

O que continua fora

Parametrização fiscal completa — CFOP, CST, substituição tributária, benefícios estaduais, regra de crédito por operação — é spec própria, junto com a nota fiscal. Aqui nascem apenas os portadores de identidade fiscal, e eles nascem certos.

1 · Seed a partir do que já existe

Para cada tenant: uma Company com code = "0001", cnpjRoot extraída de TenantSettings.cnpj e legalName do nome do tenant; um Establishment Headquarters com o CNPJ completo e code = "0001". Campos fiscais entram como pendência de preenchimento, não como bloqueio.

2 · TenantSettings.cnpj sai no mesmo release

Manter os dois por um ciclo cria a segunda fonte de verdade que a Decisão 2 existe para impedir. Sai junto ou não sai.

3 · Renomes sem dado

cost_centers.legal_entity_id → company_id. Nenhuma tabela do gryd é tocada. Nasce uma tabela no esquema do Nexio, user_company_scopes, vazia — e vazia significa "todo mundo enxerga todas as empresas", que é exatamente o comportamento de hoje. ApprovalPolicy também não ganha coluna: o critério resolve. Todos anuláveis e todos vazios: nenhum backfill, nenhuma janela.

4 · Tenants existentes não mudam de comportamento

Com uma empresa por tenant, o seletor não aparece, a numeração continua única e o escopo não recorta nada. A migração é invisível para quem tem um CNPJ só — que é o teste de que o modelo está certo.