Arquitetura

Um projeto por contexto

Organização · Catálogo · Fornecimento · Orçamento · Aprovação · Espinha transacional · Transversais. A fronteira é referência de projeto, não convenção de pasta: o compilador recusa o atalho.

Nenhuma chave estrangeira cruza contexto

Já é regra do produto. Referência entre contextos é id, sem navegação do ORM e sem join no banco — o que mantém a porta de extração aberta sem custo hoje.

A fronteira é testada, não confiada

Um teste de arquitetura no CI reprova referência proibida entre projetos. Sem isso, a fronteira dura até a primeira sexta-feira apertada — e a extração futura vira reescrita em vez de mudança de host.

1 · Contexto não enxerga contexto

Nenhum .Core referencia o .Core de outro contexto — só .Contracts. É a asserção que sustenta todas as outras, e é ela que torna a extração futura um problema de implantação em vez de um refactor.

2 · Domínio não conhece infraestrutura

Tipos sob Domain/ não dependem de ORM, de barramento de mensagem nem de HTTP. É esta asserção que substitui o projeto separado — e é por isso que a economia de projetos não custa a Clean Architecture.

3 · Nenhuma navegação entre contextos

Verificada no modelo do ORM, não no código: nenhuma entidade tem propriedade de navegação nem chave estrangeira para entidade de outro contexto. É a única defesa da fronteira dentro da persistência, e é ela que dá o degrau 4 de graça lá na frente.

4 · Nenhum .Core referencia a persistência

A porta é declarada no domínio e implementada fora. Quebrar isto inverte a dependência sem ninguém perceber, porque o código continua compilando e os testes continuam passando.

5 · Perfil não invade perfil

O Worker não expõe controller nem endpoint sem controller, exceto a verificação de saúde; a API não executa job nem agendador — enfileirar pode. Nenhum host monta middleware que abre rota fora da lista branca da asserção 8. O painel do GrydJobs é middleware, não controller (UseGrydJobsDashboard, que a documentação do framework manda chamar — docs/modules/jobs/getting-started.md:97), só confere autenticação (GrydJobsDashboardAuthFilter.cs:19, commit e4eb5a4f) e mostra e reenfileira os jobs de todos os tenants, com o tenantId e o onBehalfOfUserId do payload à vista. Critério: a rota padrão do painel (/grydjobs/dashboard) responde 404 em todo host do Nexio, e o teste de fumaça de cada perfil confere. E, porque o caminho é parâmetro (GrydJobs.API/ServiceCollectionExtensions.cs:75–93, pathMatch com valor padrão) e o painel é middleware fora do roteamento, montá-lo em outro caminho — UseGrydJobsDashboard("/ops") — passaria nos quatro critérios da asserção 8: por isso o teste reprova o painel em qualquer assembly do Nexio, qualquer que seja o caminho — e não por uma lista de três nomes de método: o Hangfire.AspNetCore fixado em 1.8.23 (Directory.Packages.props:153, commit e4eb5a4f) expõe, ao lado do MapHangfireDashboard, o MapHangfireDashboardWithAuthorizationPolicy e o MapHangfireDashboardWithNoAuthorizationFilters (validação R6), e nome novo entra a cada versão do pacote — enumerar métodos é perder a corrida. O próprio UseGrydJobsDashboard mostra por que a lista não segura: ele chama o painel pelo nome inteiro do tipo, Hangfire.HangfireApplicationBuilderExtensions.UseHangfireDashboard(app, pathMatch, …) (GrydJobs.API/ServiceCollectionExtensions.cs:81). O que se reprova são os tipos e o namespace do painel: o UseGrydJobsDashboard e o que o GrydJobs.API exporta para montá-lo, e todo tipo do painel do Hangfire.AspNetCore — as opções, os filtros de autorização e os métodos de montagem que os recebem. Enquanto o framework não oferece registrar jobs só para enfileirar (demanda de plataforma), a asserção se verifica pelo efeito: o teste de fumaça do perfil API prova que nenhum job executa ali. É o bloqueio 2 impedido de voltar — e ele volta sozinho, na primeira vez que alguém registrar um job “só para testar”.

6 · .Contracts é contrato

Todo tipo publicado é imutável e sem dependência de infraestrutura. No dia em que virar contrato de rede, ele já é serializável — e ninguém precisa descobrir que publicou uma entidade por engano.

7 · O recorte por empresa fecha por construção

Toda entidade com companyId ou establishmentId está registrada no filtro de escopo por empresa; entidade nova sem registro quebra o build. É a mitigação da Trava 4, ao lado da regra de que a resolução que não roda recusa a requisição.

8 · Lista branca de endpoints por host

Cada host declara a lista branca do que pode expor, e o teste monta o host e lê os endpoints efetivos — tudo o que o roteamento registrou depois do arranque, com controller ou sem: rota de controller, hub, painel e rota aberta por middleware —, reprovando todo endpoint fora da lista. Deixar de referenciar não exclui nada: módulo do framework arrasta a parte de aplicação de outro módulo por referência transitiva — o projeto de infraestrutura do GrydAuth referencia o pacote agregador do GrydAudit (GrydAuth.Infrastructure.csproj:20), que referencia o projeto de controllers dele (GrydAudit.csproj:15), e o contexto de persistência do Nexio herda o do GrydAuth, então todo host recebe o AuditLogsController sem declarar nada (commit e4eb5a4f) —, e o registro de um módulo acrescenta ao host a parte de aplicação dele. Comparar a lista declarada também não basta, e prefixo de rota não serve: a rota real do GrydFiles é versionada (api/v{version}/files). Regra do Nexio: o host retira toda parte de aplicação fora da lista branca, inclusive a que chegou por referência transitiva ou pelo registro do módulo, e não monta endpoint sem controller que a lista não nomeie.

A lista branca, por host — e ela nomeia actions, não assemblies. A razão é uma só, e não muda: o host só expõe o que o produto usa. Nexio.Api: os endpoints do Nexio; do GrydAuth.API, só as actions que o produto usa — autenticação e MFA, usuários, papéis, permissões, preferências, diretório de usuários e o detalhe do próprio tenant (GET /tenants/{id}, TenantsController.cs:69), cujo handler exige vínculo ativo do chamador e responde 404 anti-disclosure —; e, do GrydNotifications.API, só a caixa in-app (UserNotificationsController) e o texto do aviso por tenant (NotificationTemplatesController), que a página de Notificação usa. Do GrydAuth.API ficam de fora as actions de administração de tenants — a lista (TenantsController.cs:38), a busca por domínio (:101), as estatísticas (:129), os filhos e a hierarquia (:154, :178), os usuários do tenant (:448) e toda escrita de tenant e de vínculo (:202 a :539) — e o disjuntor inteiro (CircuitBreakerController), porque o Nexio não tem tela para nenhuma delas: administração de tenant é trilho de plataforma e o disjuntor é operação. Que cinco dessas actions devolvam hoje dados de qualquer tenant a um Admin comum é defeito da plataforma, registrado na demanda de plataforma — a lista branca não existe por causa dele, não o compensa e não muda quando ele for corrigido. Nexio.Portal: as rotas do próprio portal, nenhuma de módulo do framework. Nexio.Worker: a verificação de saúde. Fora de todo host: GrydAudit.API, que expõe a trilha a qualquer usuário autenticado enquanto o GrydAudit não isola tenant (AuditLogsController.cs:17, só autenticação); GrydFiles.API, que deixaria a leitura contornar o CanRead do dono do anexo — o arquivo entra no Nexio só pelo processo, e o dono declara a referência esperada ao confirmar; GrydJobs.API inteiro, controllers e painel, que só conferem autenticação e alcançam os jobs de todos os tenants (asserção 5); GrydReports.API, porque o Nexio usa o relatório em processo; o envio avulso do GrydNotifications.API (NotificationsController), porque a Notificação não tem tela de envio e é por ele que um fileId alheio sai por e-mail (demanda de plataforma); e o hub de notificação, endpoint sem controller (MapHub, GrydNotifications.API/ServiceCollectionExtensions.cs:77) — a caixa in-app se lê pela rota, e entrega em tempo real entra por revisão desta página. Controller ou endpoint novo de módulo do framework fica fora até entrar na lista, e entrar nela é revisão desta página. Critérios: (a) host só com GrydAuth.Infrastructure referenciado → zero endpoints de GrydAudit.API; (b) host de teste que monta o AuditLogsController por referência transitiva sem a retirada → o teste encontra o endpoint e reprova; (c) rota padrão do painel do GrydJobs → 404 em todo host do Nexio, e nenhuma referência aos tipos do painel em assembly do Nexio (asserção 5); (d) hub montado sem estar na lista → o teste reprova; (e) chamada a uma action de administração de tenants ou ao disjuntor do GrydAuth.API em host do Nexio → 404, e o endpoint não aparece na leitura dos endpoints efetivos. Que upload:files, read:files, retain:files e purge:files não possam ir a papel de tenant é requisito do catálogo da plataforma — está na demanda de plataforma, não neste teste.

9 · O filtro de tenant só se desliga no Migrator

Nenhum código do Nexio fora do Nexio.Migrator desliga o filtro de tenant ou a exigência de tenant na leitura, por nenhum dos cinco caminhos que o framework oferece: (1) o desligamento explícito (ITenantDataFilter.Disable(), ITenantDataFilter.cs:31); (2) a escrita direta no estado do filtro que afrouxa a leitura — o sentido importa, e é só este que se proíbe: ligar a exigência de tenant (TenantDataFilterAccessor.RequireTenantOnRead = true) é o que todo job e todo consumidor precisa fazer, porque o contrato só oferece Disable(), e é o que o próprio framework faz (DurableNotificationProcessor.cs:54, DurableNotificationMaintenance.cs:46); por isso a asserção admite um único ponto do Nexio escrevendo nesse estado, e só com o valor true — e esse ponto tem nome, porque teste estático não reprova “fora do ponto único” sem saber qual é ele: é o TenantExecutionScope, no Nexio.Platform, o auxiliar que abre o escopo do tenant do job ou do consumidor, e é aí que a exigência de tenant se liga. O tipo é do Nexio e o nome é declarado aqui: o framework não oferece auxiliar nenhum para isso — cada módulo dele escreve o par “ligar o filtro, exigir tenant” à mão (DurableNotificationProcessor.cs:51–54, commit e4eb5a4f) —, e um teste que reprove por posição precisa de um nome para comparar. E o que se reprova é a referência, não só a escrita: o acessor também expõe Reset() (TenantDataFilterAccessor.cs:47–52), que zera o estado e devolve a exigência de tenant ao padrão false (:30, ?? false) — não é Disable(), não é escrita, não é IgnoreQueryFilters(), não é pedido que se declara entre tenants, não é escopo de grupo e não é SQL cru, de modo que um finally { …Reset(); } num job do Nexio devolveria a leitura ao fail-open com o build verde. Por isso a asserção reprova toda referência ao TenantDataFilterAccessor fora do ponto único — leitura, escrita, Reset() e o que o tipo vier a expor —, e no ponto único admite só a escrita com true; (3) a consulta que ignora os filtros (IgnoreQueryFilters()), que derruba de uma vez o de tenant, o de empresa e o de exclusão lógica — e que o próprio framework usa (FileScanJob.cs:122); (4) o pedido que se declara entre tenants (ICrossTenantRequest, ICrossTenantAuthorizedBy): o comportamento do pipeline do GrydAuth desliga o filtro sozinho quando o chamador tem a permissão que o pedido nomeia (ICrossTenantAuthorizedBy.cs:14; CrossTenantDataFilterBehavior, registrado em GrydAuth.Application/ApplicationServiceRegistration.cs:52, desliga nas l.106–124), sem uma linha de desligamento no código do Nexio; e (5) o escopo de grupo — IGroupScopableQuery com o TenantScopeBehavior (registrado em GrydAuth.Application/ApplicationServiceRegistration.cs:58) —, que não desliga o filtro mas troca o predicado de um tenant por um conjunto deles (TenantScopeApplier.cs:27, TenantQueryFilterExtensions.cs:139–143): falha fechada, e ainda assim leitura de mais de um tenant sem nenhum dos quatro caminhos acima. E a interface não é a única porta desse quinto caminho: o ITenantScopeApplier é serviço registrado (MultiTenancyServiceCollectionExtensions.cs:67) e o TenantContextAccessor.ScopeTenantIds tem setter público estático (:75–78) — um tipo do Nexio que peça o applier ao contêiner, ou escreva no acessor, lê N tenants sem implementar IGroupScopableQuery, que era a única coisa que a asserção reprovava aqui — e o próprio framework diz que é defeito: o acessor documenta que o único escritor é o ITenantScopeApplier, movido pelo TenantScopeBehavior, e que escrever de qualquer outro lugar “bypasses the entitlement check and is a defect” (TenantContextAccessor.cs:72–73). Documentação não quebra build. Por isso ela reprova também o uso do applier e a escrita no ScopeTenantIds, além da interface. E o contêiner não é a única porta do applier: o TenantScopeApplier é public sealed class de construtor público (TenantScopeApplier.cs:13) e TenantScope.Group(…) é fábrica pública (TenantScope.cs:137) — um tipo do Nexio que faça new TenantScopeApplier().Apply(TenantScope.Group(…)) não pede nada ao contêiner, não nomeia a interface e não escreve no acessor (quem escreve é o próprio applier, :27, dentro do Gryd.Infrastructure), não implementa IGroupScopableQuery e lê N tenants com o build verde — e o Apply não confere direito nenhum: quem resolveu o conjunto foi o TenantScopeBehavior, que esse caminho pula. Por isso o alvo aqui é a referência, como no caminho (2): reprovam-se toda referência ao tipo concreto TenantScopeApplier nos assemblies do Nexio e toda fábrica de TenantScope que não seja Single — as duas que existem são Single (TenantScope.cs:106) e Group (:137), e fábrica nova do framework entra reprovada até revisão desta página. Fora dos cinco fica o SQL cru (Database.SqlQuery, ExecuteSql), que não passa por filtro global nenhum. Commit e4eb5a4f. O teste varre os assemblies do Nexio e reprova as chamadas de (1) e (3), toda referência ao TenantDataFilterAccessor fora do ponto único de (2), e nele toda escrita cujo valor não seja true, todo tipo que implemente as interfaces de (4) ou de (5), todo uso do ITenantScopeApplier, toda referência ao tipo concreto TenantScopeApplier, toda fábrica de TenantScope que não seja Single e toda escrita em TenantContextAccessor.ScopeTenantIds, e todo SQL cru sobre tabela de tenant sem predicado de tenant conferido por teste. Desligar o filtro falha aberto: com ele desligado, o código que chamou é a única coisa entre o chamador e os dados de todos os tenants. As exceções são declaradas e nomeadas uma a uma, e exceção nova é revisão desta página: os jobs de módulo do framework que desligam o filtro na própria execução, até a demanda de plataforma de leitura de arquivo sem tenant ser entregue; e o IServerFileStore.OpenReadAsync, que hoje atende o tenant do parâmetro com IgnoreQueryFilters() sem compará-lo com o que está em vigor (EfStoredFileStore.cs:177–186, chamado pelo GrydFilesEmailAttachmentReader.cs:34) — é o caminho do e-mail com anexo, está na demanda de plataforma e sai desta lista quando o tenant nomeado passar a ser conferido. Critério: job ou consumidor do Worker que desliga o filtro, consulta do Nexio com IgnoreQueryFilters(), qualquer referência ao TenantDataFilterAccessor fora do TenantExecutionScope — Reset() inclusive — ou escrita nele com valor diferente de true, comando do Nexio que implementa ICrossTenantAuthorizedBy ou IGroupScopableQuery, tipo do Nexio que peça o ITenantScopeApplier ao contêiner, que referencie o tipo concreto TenantScopeApplier, que chame fábrica de TenantScope diferente de Single ou que escreva em TenantContextAccessor.ScopeTenantIds, e SQL cru sobre tabela de tenant sem predicado de tenant — cada um quebra o build.

10 · Quem resolve a porta de cada escopo é o consumidor declarado

O Nexio é consumidor registrado do módulo de arquivo, e em processo o módulo não confere permissão: o que autoriza é o consumidor registrado para o escopo, o ato e o autor declarado (RN-GF-28 do GrydFiles). Quem registra escopo repete a asserção no próprio repositório — e é esta. Sem ela, qualquer assembly do processo que alcance a porta de nexio.attachment retira a guarda de um anexo ou pede a eliminação dele, e não há permissão nenhuma para barrar.

Os consumidores declarados, e as duas portas. A porta amarrada ao escopo nexio.attachment — reservar, confirmar, declarar referência esperada, ligar e retirar guarda, pedir eliminação — é resolvida só pelo adaptador de arquivo do Nexio.Platform, o único assembly do Nexio registrado para esse escopo; e a porta de conteúdo no servidor (IServerFileStore, RN-GF-06 — por onde o job lê a planilha de importação já liberada) é referenciada só por ele. Nenhum .Core, nenhum host e nenhum outro adaptador resolve a porta do escopo nem referencia a porta de conteúdo: o domínio declara a sua porta e o adaptador a implementa (asserção 4). Consumidor novo é revisão desta página, como a lista branca da asserção 8.

O alvo é quem resolve a porta, não quem passa o texto. Escopo é constante de compilação: o compilador a embute em cada chamador, e nenhum teste de dependência entre assemblies vê quem passou nexio.attachment — a asserção “só o consumidor registrado passa o escopo” é inverificável enquanto o escopo for argumento. Por isso o escopo sai das assinaturas e a porta se resolve por um tipo-marca do próprio consumidor: um tipo que mora no assembly registrado para aquele escopo, de modo que resolver a porta obrigue a referenciar esse assembly e a dependência apareça. Como a plataforma amarra o tipo-marca ao registro é decisão dela, e o pedido está na demanda de plataforma.

E o teste estático sozinho não fecha. Chave de texto, Type montado em execução e reflexão (IServiceProvider.GetService(Type)) alcançam a porta sem deixar dependência entre assemblies — é o mesmo defeito da constante embutida, um nível acima. Por isso esta asserção tem duas metades, e a segunda roda em execução, sobre o contêiner montado. Critérios: (a) assembly do Nexio fora da lista que resolve a porta de nexio.attachment, ou que referencia a IServerFileStore → quebra o build, e continua quebrando se esse assembly declarar a mesma constante de escopo por conta própria; (b) nenhuma assinatura da porta usada pelo Nexio tem parâmetro de escopo, e nenhum assembly do Nexio alcança, por caminho nenhum, uma porta em que o escopo seja argumento; (c) em execução, falha na resolução — e nenhuma chamada chega à IFileService com aquele escopo — em dois casos: pedir ao contêiner a porta de um escopo não registrado, por tipo-marca de quem não registrou, por chave de texto ou por Type montado em execução; e pedir a porta de um escopo registrado — nexio.attachment — por Type montado em execução, por tipo-marca obtido em execução ou pelo tipo-marca de quem não registrou aquela porta. O alvo dos dois é o mesmo: o pedido sem referência estática ao assembly do consumidor, registrado ou não — limitar a verificação ao escopo sem registro a deixa um nível abaixo do requisito, porque reflexão sobre o tipo-marca de um escopo registrado resolve a porta e nem o (a) nem a metade não registrada a veem. O padrão existe no repositório do framework (JobExecutionAdapters.cs:235, :303 e HangfireJobActivator.cs:43, commit e4eb5a4f) — não é hipótese. O teste de fumaça de cada perfil confere os dois casos. É o que o (a) não dá: o que o (c) reprova não aparece como dependência entre assemblies.

Intenção de leitura declarada na consulta

Toda consulta nasce dizendo se é somente-leitura. Sem isso, o degrau 2 vira auditoria de todos os handlers em vez de mudança de roteamento. E a regra que vem junto é dura: saldo de orçamento, estado de aprovação e qualquer leitura dentro de transação vêm sempre do primário — réplica tem atraso, e atraso quebra ler o que se acabou de escrever. Só relatório, listagem e busca vão para réplica.

tenantId como primeira coluna dos índices

Não basta a coluna existir na tabela: ela precisa liderar o índice. É a chave de partição do degrau 5 e o que faz o filtro global ser barato em toda consulta. Refazer índice em tabela povoada é janela de manutenção; nascer certo é uma linha de configuração.

Particionar por período o razão e a trilha de aprovação, desde a criação

O razão de orçamento (BudgetEntry) e a trilha de aprovação (ApprovalEvent) são append-only e crescem para sempre. A trilha de auditoria da plataforma fica fora: a tabela é do GrydAudit, e o Nexio não decide a chave dela. Particionar tabela vazia é trivial; particionar tabela com anos de dado é migração longa com janela. O preço a pagar é declarado: a coluna de período entra na chave primária — decisão barata agora, cara depois.

Token de versão otimista

As specs já pedem version inteiro e expectedVersion na escrita. A entidade base do framework não tem coluna de versão, e alterar a base é mudança que atravessa todos os módulos — então o token é coluna do agregado do Nexio. Onde a corrida é sobre estado, há precedente melhor na própria plataforma: marcar a coluna de estado como token de concorrência, que é como o vínculo entre tenants resolve duas decisões simultâneas.

Saldo por tupla, sob trava das linhas que podem recusar ou exigir aprovação

O razão continua append-only; o saldo é materializado por tupla concreta — empresa, centro de custo folha, conta folha, balde e estágio — e atualizado na mesma transação do lançamento. O saldo de uma linha de orçamento é a soma das tuplas sob ela, lida na hora. A trava cai sobre o conjunto de linhas candidatas da tupla cuja política pode recusar ou exigir aprovação (Block, RequireApproval), em ordem de id, e a soma é lida sob a trava. Sem trava, duas aprovações simultâneas leem o saldo antigo e a verba estoura sem que ninguém tenha aprovado o estouro; fora de ordem, duas decisões sobre as mesmas linhas se travam uma à outra. Linha que só avisa não trava. A regra está no Orçamento.

Idempotência na borda

Toda rota de ato e todo consumidor de fila aceitam chave de idempotência: repetir a mesma chave devolve o mesmo resultado e não duplica efeito. É o par obrigatório da entrega “pelo menos uma vez” do ADR 4, e é também o que protege o duplo clique do usuário.