Modelo de classes

A fatia é da empresa do documento, e o nó tem que bater com ela

Toda fatia de rateio de um documento da empresa A só aponta para centro de custo corporativo ou da empresa A. A fatia não carrega empresa: a empresa é a do documento — derivada do establishmentId e congelada —, e é contra ela que o companyId efetivo do nó é lido, fatia a fatia, e que o Budget consumido é escolhido (BudgetEntry.companyId). Não há rateio entre empresas na v1 (RN-CC-34, RN-EMP-06, RN-O40); como demanda de várias empresas se consolida é decisão da spec da Cotação, dentro da RN-EMP-26 da Empresa. Validado no documento, não no cadastro, porque o cadastro é anterior ao documento.

O documento tem três eixos, e só três

Quem recebe fiscalmente (establishmentId, com allowsReceiving), quem pediu (requestingEstablishmentId, nunca nulo — igual ao establishmentId quando quem pede é quem recebe —, da mesma empresa e com allowsPurchasing) e a empresa do documento (companyId, derivada do establishmentId validado contra o escopo e congelada). companyId nunca vem do cliente nem do token (RN-EMP-08). Não existe buyerEstablishmentId: quem opera a compra é usuário, resolvido por UserCompanyScope. Estabelecimento de outra empresa como quem pediu é 422 REQUESTING_ESTABLISHMENT_COMPANY_MISMATCH_UNPROCESSABLE (RN-EMP-33, RN-EMP-34). Toda escrita resolve exatamente uma empresa (RN-EMP-26).

Entrega em outra UF é derivada e sempre explicada, nos três caminhos

Quando a UF de entrega difere da do estabelecimento destinatário, a entrega é interestadual — isInterstate no ponto, deliveryIsInterstate na linha, derivados e nunca digitados — e precisa de uma de três explicações: recebedor distinto com deliveryOperationType (RN-DL-20); type = ConstructionSite com defaultCostCenterId, só no ponto cadastrado (RN-DL-07); ou interstateNote, a única explicação do endereço eventual sem recebedor distinto (RN-DL-12). Sem UF divergente, ou com recebedor distinto, interstateNote é recusada; e recebedor distinto exige deliveryOperationType em qualquer UF. Verificada no cadastro do ponto, no uso dele em documento e no endereço eventual (RN-DL-05). É a única invariante do modelo que existe por causa de legislação estadual. O Nexio não calcula o imposto nem enquadra a operação; ele garante que a dimensão exista, esteja congelada na linha e chegue ao ERP fiscal.

Nulo significa a mesma coisa em toda parte — no cadastro

CostCenter.companyId nulo é nó corporativo. ItemSupplier.supplierEstablishmentId nulo vale para todos os estabelecimentos do fornecedor; ItemSupplierPrice.shipToStateCode e companyId nulos valem para qualquer UF e qualquer empresa; SupplierBankAccount.supplierEstablishmentId nulo, para todos os estabelecimentos. GLAccountCompany ausente é conta habilitada. Attachment.companyId nulo é anexo do tenant — visível em qualquer empresa que o usuário enxergue —, porque quatro dos donos com spec não têm empresa (Item e Supplier são vocabulário e cadastro do tenant; SupplierQualification e a proposta bancária pendem de um fornecedor) e o ApprovalRequest é condicional: herda a empresa do alvo quando ele tem uma. O filtro é "empresa no escopo ou empresa nula", a mesma forma de GLAccountCompany e BudgetPolicy — e, para quem não tem empresa nenhuma no escopo, nada; sem essa linha as duas implementações possíveis falham em silêncio — a estrita faz a certidão do fornecedor sumir para todo mundo, a frouxa a mostra a quem não deveria vê-la. BudgetLine.costCenterId e glAccountId nulos valem para qualquer nó e qualquer conta; BudgetPolicy.costCenterId nulo é o padrão do tenant, e BudgetPolicy.companyId nulo vale para todas as empresas — preenchido vence nulo no mesmo nó e no mesmo campo (RN-O37).

Uma convenção só — nulo é "todos", nunca "nenhum" e nunca "não sei". Ela vale para abrangência de cadastro, nunca para acesso: no UserCompanyScope não há nulo nem ausência que libere — sem linha vigente, nenhuma empresa (RN-EMP-15), porque um cadastro abrangente demais aparece numa tela e se corrige, e um acesso abrangente demais entrega dado de outra empresa sem ninguém ver. Exceções, todas declaradas: CostAllocation.glAccountId nulo significa "ainda não escolhida", existe só em rascunho, e a submissão o recusa (RN-CC-29); NumberSequenceCounter.companyId e establishmentId nulos significam "a partição não tem essa dimensão" — decidido pelo scope da configuração, sem valor sentinela (RN-EMP-30); ItemSupplierPrice.freightTerms nulo é "não se aplica", e só existe fora de mercadoria (RN-ITM-27); e, no fornecedor, cnpjRoot, cnpj, establishmentType e registrationStatus nulos significam "não se aplica a este entityType" — decidido pelo tipo de pessoa, nunca pelo usuário (RN-FOR-03). establishmentType tem um segundo nulo, declarado: em Company e MEI é "ainda não verificado" — lido só da consulta à Receita, nunca inferido, e enquanto nulo nada que dependa de "ser matriz" é decidido.

Toda aprovação humana é uma instância do motor

Onde uma segunda pessoa decide sobre o pedido de outra, o agregado dono submete ao motor (POST /approvals) e aplica o efeito na transação da decisão que conclui a instância, pelo contrato de desfecho do processo; nenhum módulo tem rota própria de aprovar ou rejeitar. Atos unilaterais com motivo — bloqueio e desbloqueio, promoção manual, revogação, substituição, escape de duplicata, expurgo, desligar legal hold — não são aprovação. Princípio 7, RN-AP-28 e RN-AP-38 do Fluxo.

Há segundas pessoas sem instância, todas declaradas na página dona e nenhuma com rota de "aprovar": a confirmação da carga inicial do catálogo (RN-ITM-42) e a da carga inicial bancária (RN-FOR-31) — janela única por tenant, dupla custódia sobre o mesmo arquivo, registro do ato de controle —, a confirmação por segunda pessoa da alteração ChainContact com telefone confiável e fora de trava (RN-FOR-34), a execução, por outra pessoa, da eliminação a pedido de titular quando o arquivo é prova de controle, Permanent ou ainda está sob guarda (RN-ATT-38), a contestação registrada por dentro, que só produz efeito quando outra pessoa confirma (RN-FOR-30), a publicação de política, que não pode ser feita por quem a criou nem por quem a editou (RN-AP-55), e a efetivação das mudanças de parâmetro crítico do motor e da moeda — quem propõe não efetiva (RN-AP-69, RN-CUR-28). Se a dupla custódia fora do motor é uma forma de aprovação ou uma categoria própria de ato de controle está em decisão; até lá, cada uma vale só onde a spec dona a declara, e segunda pessoa sem instância fora delas é defeito.

Três árvores, uma mecânica

CostCenter, CategoryNode e GLAccount compartilham caminho materializado em texto (path com separador nas duas pontas + depth, publicado como level), código imutável, ancestrais sem recursão, allowsPosting só em folha com exceção declarada, vigência opcional, cascata assimétrica de status por rotas próprias de ativar e desativar, move só por PATCH /parent com path como guarda, e version int + expectedVersion como token de concorrência. Uma quarta forma de fazer árvore neste produto seria erro por escolha.

O que é saldo é projeção; o que é fato é linha

BudgetBalance é a única classe do modelo que existe só por desempenho, e a regra que a mantém honesta é ser reconstruível a partir de BudgetEntry a qualquer momento. Ela guarda uma linha por tupla concreta — empresa, centro de custo, conta, balde e estágio —, não por linha de orçamento: o saldo de uma BudgetLine é a soma, lida na hora, das tuplas sob ela nas duas dimensões (RN-O02). Divergência entre projeção e razão é defeito, não decisão. Vale a mesma disciplina do ApprovalEvent, que é append-only — a única escrita é apagar o texto de um comentário por LGPD — e é a prova da trilha: quando um número precisa ser explicado, ele não pode ser uma coluna que alguém somou.

A competência é a data de necessidade, não a do documento

O balde orçamentário de um movimento vem de quando a coisa precisa existir. A requisição de dezembro para entrega em janeiro consome janeiro — o que mata a corrida de fim de ano e faz o compromisso que atravessa a virada já nascer no exercício certo. É por isso que Requisition nasce obrigada a expor data de necessidade por linha, e não só no cabeçalho.

Documento congela; cadastro muda

Preço — a versão e a faixa usadas —, os dois fatores (convNum/convDen da unidade pedida e priceConvNum/priceConvDen da unidade de preço) com a origem deles (factorSource) e a unidade de compra usada, dados do fornecedor, empresa, conta, dados fiscais de quem recebe (taxRegime, icmsTaxpayerStatus, stateRegistration, suframaCode — RN-EMP-37) e o endereço de entrega (RN-DL-09) são copiados para o documento — no nascimento da linha ou na submissão (RN-UOM-10, RN-ITM-37, RN-ITM-39). A cadeia de aprovação é congelada na instância, na submissão (RN-AP-06).

Nenhuma seta deste diagrama é lida em tempo de execução por um documento já emitido — com uma exceção declarada no motor: quem decide cada passo é resolvido na ativação dele (vínculos de centro de custo, membros de grupo, delegação vigente — RN-AP-07), e a reavaliação recasa contra as políticas vigentes na data dela (RN-AP-47).

Aprovador precisa de escopo na empresa do documento

O filtro é por pessoa, nunca por nível: toda resolução — ativação, delegação, reatribuição, escalonamento e reserva — só dá tarefa a quem tem conta ativa, act:approvals (e a permissão do nível, em PermissionHolder), linha vigente de UserCompanyScope na empresa do documento — e ausência de linha é nenhuma empresa — e não está entre os excluídos da instância (RN-AP-59). Nos tipos que caminham a árvore isso é garantido antes, no vínculo, que só é criado para quem alcança a empresa do nó (RN-CC-30, RN-EMP-27); nos demais, a publicação exige gente elegível em cada empresa que a política alcança (RN-AP-40). Nível que o filtro esvazia cai no reserva — fallbackApproverType · fallbackApproverRef, tarefa ByFallback —, marca resolvedOutOfScope no passo e avisa a controladoria (RN-AP-39); em processo com valor, o reserva segue authorityExceededBehavior (RN-AP-58). Nos processos cujo assunto não tem empresa vale só a permissão. Sem isso, o motor produz tarefa para quem não consegue abrir o documento.

O escopo só estreita, falha fechada e nunca atravessa a organização

UserCompanyScope não concede organização, papel nem permissão — isso continua vindo do token do GrydAuth. Ela responde apenas em quais empresas daquele tenant o que o token já concedeu tem efeito, e responde fechado: sem linha vigente, nenhuma empresa — não existe nulo nem ausência que libere, qualquer que seja o número de empresas (RN-EMP-15). Resolução que não roda não libera: falha com 500, nunca com conjunto mais amplo (RN-EMP-25). Fora do escopo é 404.

O que precisa ser garantido do lado do produto: a empresa é do mesmo tenant da linha — chave composta e local, (tenantId, companyId) → companies(tenantId, id) —; as vigências da mesma pessoa na mesma empresa não se cruzam, a mesma mecânica do CostCenterAssignment; e a concessão não escala entre empresas: só se concede o que se alcança (RN-EMP-19), nunca além da própria vigência (RN-EMP-42, com onGrantorChange gravado na concessão), ninguém mexe nas próprias linhas (RN-EMP-41), e toda empresa, ativa ou inativa, mantém uma linha vigente sem validTo de pessoa ativa com update:company-scopes (RN-EMP-24).

Anexo não tem dono no banco, e por isso tem três guardas

Nenhuma chave estrangeira liga o Attachment ao documento dono nem ao StoredFile. A integridade é mantida por três mecanismos que só valem juntos: o registro de descritores por ownerType, que derruba a inicialização quando um módulo registra dono sem descritor completo; o evento de descarte de rascunho, que é o caminho normal; e a varredura diária (attachment-orphan-sweep), que é a rede de segurança, libera a referência só quando o último estado conhecido do dono era rascunho e reporta o que encontra. Dono de módulo ainda ausente não é varrido: ausência de módulo não é ausência de dono. Órfão não é ocorrência normal — é sintoma de um consumidor que esqueceu de publicar o evento.

Revogar libera o arquivo só quando o documento é rascunho nunca submetido

Fora do rascunho nunca submetido a FileReference não é liberada e o blob continua preso: liberar faria o arquivo morrer no fim da carência e a auditoria receber a lápide do GrydFiles, guardando o registro da prova e perdendo a prova. A referência de documento que já passou por alguém sai por dois caminhos só: o fim da guarda — 31/12 do ano do fechamento do dono mais os anos congelados no anexo, liberado pelo job attachment-guard-release — ou a eliminação a pedido de titular; e nenhum dos dois com guarda legal ativa. Guarda legal é ato por caso, nunca propriedade do tipo.

Dois CNPJs com o mesmo nome são coisas diferentes

Establishment é comprador; SupplierEstablishment é vendedor. Por isso o vínculo do item com o fornecedor, e todo o agregado do fornecedor, usam supplierEstablishmentId, e não o nome curto, que seria ambíguo em toda consulta.

Motivo é dado, nunca regra

Nenhum ReasonCode muda fluxo, estado ou permissão — quem decide comportamento é o motor de aprovação, a política de orçamento e a máquina de estados do documento. E o corolário: motivo escolhido por máquina não é ReasonCode — é enum. BudgetEntryReason ficou fora do catálogo porque deixá-lo dentro daria ao tenant o poder de renomear ou desabilitar um valor de que o motor depende, que é exatamente a porta que esta regra existe para fechar. As duas perguntas convivem no mesmo movimento do razão: "por que este movimento existe" é da máquina; "por que a pessoa fez isso" é do catálogo, e só existe quando houve pessoa. A única exceção é requiresComment, que é comportamento de formulário. E o que o ato guarda é a chave mais o código e o rótulo congelados: renomear o código não pode reescrever a decisão que alguém tomou lendo o rótulo antigo, e o relatório agrupa pelo código congelado, nunca pelo id — a sobreposição do tenant cria linha nova com id novo (RN-RSN-18).

Nenhum aviso carrega valor sob permissão

Quantia, saldo, preço, total e limite de alçada não entram no corpo de uma notificação — ela carrega identificação, contexto e link. A regra é positiva: toda variável declara a sua classe — Identifier, Label, DateOrCount ou Link —, e texto digitado por uma pessoa (comentário, justificativa, descrição) nunca é variável. É verificada na semeadura, não em tempo de execução: variável sem classe, ou de classe fora das quatro, derruba a inicialização, e a lista de nomes proibidos fica como segunda malha. O motivo é que a permissão do destinatário não existe no momento em que o texto é montado — e o e-mail encaminhado no dia seguinte não tem correção.