Centro de Custo

Trim, maiúsculas, apenas [A-Za-z0-9_-], até 20 caracteres, único por tenant. Nenhuma rota o altera depois da criação.

Não há tipo e não há flag: a distinção é parentId nulo. Nenhuma nomenclatura fixa de "área" e "sub-área" no domínio — a tela nomeia como o cliente chama.

costCenterMaxDepth é opcional, validado na criação e no move, e pode ser levantado sem migração. É gancho declarado, não configuração da v1: o campo é deste documento, o padrão é nulo — profundidade livre — e a entidade de configuração nasce quando o primeiro cliente pedir o teto. Enquanto o valor for nulo não há o que validar, e nenhuma rota o expõe.

O agregado recebe a entidade pai, não o id. Nenhum outro caminho escreve path e depth.

Não há rascunho nem aprovação de cadastro. Criar sob ramo inativo ou fora de vigência é 422, com a cadeia inteira verificada.

PATCH /activate e DELETE. O corpo do PUT não carrega o campo.

Verificada até a raiz por igualdade sobre os caminhos derivados. A recusa não nomeia o ancestral — o breadcrumb já carrega o estado de cada passo.

Só política ativa bloqueia. A recusa é 409 com a contagem, e nada é escrito. A garantia é a trava exclusiva das linhas da subárvore, obtida antes de conferir as políticas e mantida até o fim da transação, contra a trava compartilhada que a criação de política toma no nó — SELECT … FOR UPDATE é um exemplo, e qualquer equivalente serve.

Um nó já no estado alvo não é tocado nem contado. Ativar uma árvore já ativa responde zero.

Nem o do nó, nem o dos descendentes. Mover para dentro da própria subárvore é 422; mover para o pai atual responde 200 sem escrever nem auditar.

E leva o consumo orçamentário junto. O Orçamento lê o consumo pela árvore vigente (RN-O50): as linhas de orçamento do pai antigo deixam de enxergar o gasto já gravado da subárvore, e as do pai novo passam a enxergá-lo, sem movimento no razão. O move não é recusado por isso. Antes de confirmar, a tela do move consulta o Orçamento — GET /budget-lines/move-impact — e mostra as linhas afetadas com o sinal de cada uma antes e depois; o Centro de Custo continua sem conhecer orçamento, e a dependência segue num sentido só.

version int é o token de toda escrita rastreada, inclusive um PUT que só troca o nome: o cliente envia o expectedVersion que leu, e a divergência responde 409. path continua conferido em move, como segunda guarda. A resposta é reler e repetir. Só o path não bastaria: ele muda só em move, e renome, vigência e conta concorrentes passariam sem 409.

Nó com empresa não aceita filho de empresa diferente. Nó corporativo aceita filho de qualquer empresa, e o filho define o escopo dali para baixo.

Validado na criação, na edição e no move. Encerrar um pai encerra a subárvore na mesma data, em cascata, com um registro de auditoria no nó disparado.

Vigência é fato de calendário e isActive é decisão administrativa. Nenhuma das duas apaga documento fechado.

Nasce verdadeiro em folha, falso ao ganhar o primeiro filho. O tenant pode abrir exceção nó a nó.

Owner, Deputy ou Watcher. Vários por nó. Trocar de responsável é encerrar um vínculo e abrir outro.

A tupla é (TenantId, CostCenterId, UserId, Role, período) — exclusão de faixas, com EXCLUDE + btree_gist como exemplo de implementação e verificação na aplicação, sob trava, onde o banco não oferecer equivalente. Checagem em memória sem trava perde a corrida de dois POST simultâneos.

Encerramento aceita apenas data igual ou posterior a hoje. É o que preserva a resposta de "quem tinha autoridade naquela data".

Owners do nó; se vazio, Deputies do nó; se vazio, o pai, até a raiz. A resposta carrega inheritedFrom. Cadeia inteira vazia devolve lista vazia — não é erro aqui.

Dois Owners de R$ 50 mil cobrem até 50 cada. O que acumula é a subida na árvore.

Inativo é estado da conta, não referência errada. Recusar tornaria um nó insalvável por causa do login de alguém. O que esta regra checa é pertencer ao tenant. Alcançar a empresa do nó é a RN-CC-30, que é outra checagem, na mesma escrita.

Percentual com seis casas. Linha sem rateio explícito tem uma fatia de 100% — o caso simples e o rateado percorrem o mesmo código.

ROUND_HALF_UP em cada fatia, diferença apurada contra o total da linha e somada à fatia de maior valor; empate pelo menor order. Determinístico, e o total sempre fecha.

Esta regra cita, não declara. O limiar é um só por tenant, em percentual e em valor — vale o menor dos dois, e o valor absoluto é o teto do limiar —, e o dono dele é a RN-AP-15, na configuração de tenant do fluxo de aprovação: materialidade muda a cadeia e não o rateio, e pelo motor universal nenhum módulo tem parâmetro próprio de aprovação. O que este documento garante é o efeito sobre o rateio: a fatia imaterial é absorvida pela maior para efeito de alçada — e continua contabilizada integralmente. "Integralmente" quer dizer que o orçamento sempre vê a decomposição integral e que Block numa fatia absorvida recusa a submissão do mesmo jeito. Materialidade é roteamento, nunca orçamento — as mesmas palavras da RN-O38. Mesma disciplina com que a RN-CC-23 virou a regra única do resíduo: mesma regra em dois lugares é uma regra; duas regras parecidas é uma armadilha.

Com operation, affectedCount e pathPrefix — mais previousPath num move e endedOn numa cascata de vigência. Descendente varrido não ganha registro próprio.

Vale para toda rota, e para os dois escopos: id de outro tenant e id de empresa que o usuário não alcança. 403 confirmaria que o registro existe em algum lugar.

Ordenação topológica no servidor, pai referenciado por código, idempotente por código, ciclo recusado nomeando os códigos envolvidos.

includeDeleted=true, search onde nada o consome, sortBy fora do mapa e managerUserId que não é GUID continuam sendo 400.

glAccountId é anulável só em rascunho. Na submissão, toda fatia tem conta com allowsPosting; a falta responde 422 ALLOCATION_GL_ACCOUNT_REQUIRED_UNPROCESSABLE. Alinhada ao razão orçamentário.

Criar ou reativar um CostCenterAssignment exige que companyOf(nodeId) esteja no conjunto de empresas resolvido para aquele usuário em UserCompanyScope. Nó corporativo (sem empresa) exige escopo completo — linha vigente de UserCompanyScope em cada empresa ativa do tenant, no instante da verificação (RN-EMP-27); ausência de linha é nenhuma empresa, e não existe concessão "todas as empresas": um nó sem empresa recebe rateio de qualquer empresa do tenant, então quem responde por ele vai receber documento de todas, e escopo parcial faria a RN-AP-39 derrubar a cadeia justamente nos casos que o nó corporativo existe para cobrir. Exigir o conjunto apenas "não vazio" seria autorizar o vínculo que o motor depois recusa. Por quê: fora de escopo, a empresa responde 404 para aquela pessoa — ela não conseguiria nem abrir o documento que o vínculo a manda aprovar. Sem esta regra o vínculo nasce inerte, e o defeito só aparece meses depois, na primeira requisição, quando o nível resolve vazio e a decisão cai no aprovador de reserva. O erro passa a acontecer na tela do admin, no momento em que ele tem contexto para corrigi-lo.

Isto não concede privilégio. Escopo não é permissão: dar escopo numa empresa não autoriza nada que o token da pessoa já não autorize — só diz onde o que ela já pode fazer tem efeito. Por isso a exigência é barata: o admin concede o escopo e o vínculo passa a valer, sem que ninguém ganhe um verbo novo. A revogação posterior do escopo não apaga o vínculo — deixa-o dormente, e é aí que a defesa em profundidade do motor entra (RN-AP-39).

Nulo = sem alçada: o vínculo não cobre valor nenhum e o motor sobe a árvore. Autoridade sem teto existe só com hasUnlimitedAuthority = true, e nesse caso approvalLimit e approvalLimitCurrency são nulos. As três colunas nunca são lidas em separado.

Por quê: com o campo opcional, nulo lido como "sem teto" faria todo vínculo criado sem preencher a alçada nascer com autoridade infinita, que é falha aberta no ponto exato em que o dinheiro é decidido. Ariba, Coupa e Protheus tratam limite ausente como zero.

approvalLimitCurrency é obrigatória quando há approvalLimit e nula quando não há. O nó corporativo não tem empresa e por isso não herda moeda funcional de lugar nenhum — ele declara a dele como qualquer outro. A comparação da alçada converte o valor da fatia para esta moeda, com a taxa congelada na submissão, e registra taxa e data no evento de aprovação; par sem cotação vigente é recusa declarada.

Por quê: limite de alçada pode estar em qualquer ISO 4217 — o de um diretor regional em USD, o de um gerente em BRL —, e um limite sem moeda faz o motor comparar BRL com USD em silêncio — e comparação silenciosa de moedas no ponto da alçada erra por um fator de cinco sem avisar ninguém.

CostAllocation.allocationId é gerado na criação da fatia e preservado em toda edição do documento. order é ordem de exibição e desempate de arredondamento (RN-CC-23), nunca identidade.

Por quê: a chave de idempotência do razão orçamentário usa a fatia (RN-O34). Chaveada por order, a reedição do rateio de 70/30 para 50/50 reusava order = 1, 2 e fazia o movimento corretivo colidir no índice único e ser descartado em silêncio.

CostAllocation não carrega empresa. A regra "fatia só aponta para nó corporativo ou nó da empresa A" é apurada contra a empresa do documento, e o Budget consumido é o dessa empresa (RN-O40). Não há rateio entre empresas na v1; compra centralizada opera no estabelecimento de cada empresa, por escopo.

Por quê: matriz e filial são a mesma Company, então empresa na fatia só importaria entre empresas diferentes — o caso que a v1 não tem, e uma coluna que só pode receber um valor é campo que ninguém testa. Rateio entre empresas, quando vier, é coluna nova preenchida a partir do documento, sem migração de chave no razão, que já guarda companyId.

PATCH …/assignments/{id}/authority altera as três colunas de alçada do vínculo vigente, com expectedVersion e registro do valor anterior na trilha. PATCH …/assignments/{id}/reactivate reabre vínculo encerrado com validFrom igual ou posterior a hoje, refazendo as checagens de sobreposição (RN-CC-17) e de alcance da empresa do nó (RN-CC-30). Papel, pessoa e vigência continuam mudando só por encerrar e abrir (RN-CC-16).

Por quê: a RN-CC-30 fala em "criar ou reativar" um vínculo, e reativar não existia em endpoint nenhum; e approvalLimit não era declarado imutável nem tinha rota que o alterasse — corrigir a alçada de alguém obrigava a encerrar o vínculo e abrir outro, o que reescreve a resposta de "quem tinha autoridade" por um motivo que não é troca de responsável.

companyId só muda por PUT enquanto o nó não tem filho, vínculo (CostCenterAssignment) nem uso declarado por outro módulo — fatia de documento submetido, linha ou política de orçamento, política de aprovação. Cada módulo consumidor implementa a consulta de uso definida no .Contracts do Centro de Custo, que pergunta sem conhecer o consumidor. Depois do primeiro uso, 409 COST_CENTER_COMPANY_IMMUTABLE_CONFLICT. No PATCH /parent para pai de empresa X, todo nó da subárvore movida precisa ser de X; um só que não seja recusa o move inteiro com 422 COST_CENTER_COMPANY_MISMATCH_UNPROCESSABLE, listando os códigos. Pai corporativo aceita qualquer subárvore.

Por quê: trocar a empresa de um nó usado mudaria a pessoa jurídica de fatias já aprovadas e a verba que elas consomem; e validar só o nó movido deixaria entrar, por baixo dele, filhos de outra empresa sob um pai que não os admite.

Arquivo com coluna de responsável exige create:cost-centers e update:cost-center-assignments; sem a segunda, o lote inteiro é recusado com 403 COST_CENTER_IMPORT_ASSIGNMENTS_FORBIDDEN. Para cada nó presente no arquivo com a coluna preenchida, o conjunto de responsáveis do arquivo é o desejado: vínculo que saiu é encerrado (validTo = hoje) e vínculo que entrou é aberto, pelas regras de sempre (RN-CC-16, RN-CC-17, RN-CC-18, RN-CC-30). Nó ausente do arquivo, ou com a coluna vazia, não é tocado. Vínculo importado nasce sem alçada; alçada só pela rota própria (RN-CC-35).

Por quê: update:cost-center-assignments é separada de update de propósito, e o Owner é o aprovador mais usado; quem só importa não pode criar aprovador, e reimportar não pode reescrever o histórico de quem respondia pelo nó.

externalCode, quando preenchido, é único por (tenant, companyId), e nó corporativo (companyId nulo) conta como uma empresa só: dois corporativos não têm o mesmo código externo. Violação: 409 COST_CENTER_EXTERNAL_CODE_ALREADY_EXISTS.

Por quê: a integração casa as bases por esse código; com nulo distinto de nulo, dois corporativos com o mesmo código fariam o ERP lançar no nó errado sem erro nenhum.