Revisão de Arquitetura — Oportunidades de Aprofundamento

Problema

O ADR-0001 da moderação declara SubmitForModeration como ponto de entrada único e rejeita a cadeia de jobs "Alternativa B". Mas a alternativa rejeitada está viva: SubmitReport roda IngestContent → ClassifyContent → RouteDecision sincronamente e inline — inclusive a chamada de IA de 1–3s que o ADR existia pra eliminar. O roteamento existe em duas implementações que já divergiram: RouteDecision descarta casos abaixo do threshold; RouteCaseAction nunca descarta. Mesmo conceito, duas respostas.

Deletion test

Deletar a cadeia antiga → a complexidade reaparece em SubmitReport, que teria de ser reescrito sobre o caminho sancionado. Os 3 jobs não são módulos ganhando o próprio sustento; são uma duplicata mantida viva por um único caller.

Solução

Fazer SubmitReport chamar SubmitForModeration com CaseSource::UserReport; deletar os 3 jobs antigos; colapsar todo roteamento em RouteCaseAction, decidindo uma única vez se "dismiss abaixo do threshold" faz parte do roteamento.

Benefícios

Localidade: um só lugar onde bugs de roteamento podem morar. Leverage: um só pipeline pra aprender. Testes: hoje as duas suítes verdes fixam a duplicação no lugar em vez de pegar a divergência; passa a existir uma suíte só, com a convergência assertável.

graph TB
  classDef entry fill:#1e3a5f,stroke:#60a5fa,color:#dbeafe
  classDef dup fill:#2a1215,stroke:#f87171,color:#fecaca
  classDef ok fill:#12161f,stroke:#34d399,color:#d5dae3
  A[auto_detect]:::entry --> SFM[SubmitForModeration]:::ok
  SFM --> SC[ScreenContent]:::ok --> CAR[ClassifyAndRoute]:::ok --> RCA[RouteCaseAction
nunca descarta]:::dup
  B[user_report]:::entry --> SR[SubmitReport
síncrono + IA inline]:::dup
  SR --> IC[IngestContent]:::dup --> CC[ClassifyContent]:::dup --> RD[RouteDecision
descarta < threshold]:::dup
          

graph TB
  classDef entry fill:#1e3a5f,stroke:#60a5fa,color:#dbeafe
  classDef ok fill:#12161f,stroke:#34d399,color:#d5dae3
  A2[auto_detect]:::entry --> SFM2[SubmitForModeration]:::ok
  B2[user_report via SubmitReport]:::entry --> SFM2
  SFM2 --> SC2[ScreenContent]:::ok --> CAR2[ClassifyAndRoute async]:::ok --> RCA2[RouteCaseAction
única regra de rota]:::ok
          

⚠ Hoje o código contradiz o ADR-0001 da moderação — este candidato o realiza, não o reabre.

Problema

O CONTEXT e o ADR dizem que a moderação é dona da política "quando é seguro punir sem humano?". Na prática, essa política é um boolean copiado — classifier_version === 'rules' && suggested_action && author_id — escrito verbatim em dois jobs (uma cópia comprovadamente morta) e re-derivado parcialmente num listener do bot-discord. A regra mais crítica de segurança do sistema não tem interface: é conhecimento folclórico duplicado através do seam.

Deletion test

Não há o que deletar — a política não tem módulo. Esse é exatamente o problema.

Solução

Extrair uma AutoExecutionPolicy (ou método no Case) que responde se um caso pode auto-executar; emitir CaseReadyForEnforcement por um único ponto. O listener do bot passa a confiar no evento em vez de re-derivar elegibilidade.

Benefícios

A regra mais perigosa do sistema (punir sem revisão) vive num único lugar testável. Deleta o branch morto e as re-checagens defensivas. Mudar a política (ex.: permitir IA > 0.98) vira 1 arquivo, não 3 em 2 módulos.

Problema

"Me dê o User por trás desta conta externa" tem 3 portas de entrada no identity (login OAuth, runtime/ETL, import) e a query ExternalIdentity::where(provider, external_account_id) hand-rolled em mais 4 call sites na moderação e no bot — ignorando o FindExternalIdentity e seu cache de 2 dias que o ADR-0001 usa como mitigação de risco. Cada caminho assume invariantes diferentes: um cria Character inline, outro via CharacterInitializer, o login OAuth não cria Character nenhum. E o pior: CreateAccountByExternalIdentity e FindExternalIdentity não filtram model_type = user — podem resolver uma credencial de infraestrutura como se fosse uma pessoa. O ADR-0001 §4 do identity proíbe exatamente isso.

Deletion test

As actions têm callers reais — não são pass-through. Falham na metade da localidade: o conhecimento "conta → pessoa" não concentra; um fix do bug de model_type precisa ser feito em 4–5 lugares e vai divergir de novo.

Solução

Um módulo profundo — ResolveUserFromProvider — dono de toda a resolução: lookup com model_type=user, criação com sufixo, e as garantias pós-criação (Profile + Character). As 3 portas do identity e os 4 call sites externos chamam através dele. O provider vira parâmetro (tirando o IdentityProvider::Discord hard-coded do domínio "platform-agnostic" da moderação).

Benefícios

A regra pessoa-vs-infraestrutura e o invariante "todo User tem Character e Profile" viram assertáveis uma vez. O cache do ADR volta a valer em todo o pipeline. LinkExternalIdentity e CreateAccountByExternalIdentity hoje não têm teste nenhum — o drift é invisível pro CI.

Problema

O contrato documentado faz do Identity a fundação mais profunda — todos dependem dele. Na realidade, Identity importa 7 siblings de volta (ex.: ResolveUserContext cria Character do gamification; IdentityProvider::getClient() conhece as 4 integrações). O grafo não é um DAG, é um nó: carregar Identity transitivamente carrega as integrações; não dá pra raciocinar sobre sua interface isoladamente. E como nenhum composer.json declara nada, o Composer nunca vai reclamar.

Deletion test

O núcleo (User, ExternalIdentity, OAuth) ganha o sustento — 100+ usos. As arestas pra cima são a complexidade que deveria morar nos consumidores.

Solução

Inverter as 7 arestas via seam de contrato/evento: Identity expõe interfaces que as integrações implementam e registram (o padrão OAuthClientContract já existe — falta inverter quem conhece quem), e emite eventos (já faz com AccountsMerged). Depois, declarar as arestas reais em cada composer.json com ^1.0.0.

Benefícios

O nó vira DAG; cada inversão é um adapter real (a integração se registra) em vez do Identity hard-codear use He4rt\IntegrationTwitch\…. Habilita o C5 (arch tests) a travar a direção pra sempre.

Problema

135 arquivos de teste nos módulos, zero testes de arquitetura. As regras de dependência do CONTEXT-MAP, a regra da fundação Identity e o ban de casts array soltos são interface documentada sem seam de enforcement — por isso o C4 cresceu invisível. As guidelines do projeto referenciam NoLooseArrayCastsTest.php como o gate mecânico; o arquivo não existe. E o CONTEXT-MAP descreve onboarding/squads/events como contextos vivos quando seus src/ estão vazios.

Solução

Testes arch() do Pest que codificam o CONTEXT-MAP como constraint executável: Identity não importa siblings; moderation não importa bot/integrações; apresentação nunca é importada; migrations não referenciam tenants; casts soltos banidos. Marcar módulos vazios como "scaffold" no mapa.

Benefícios

Converte regra documentada em seam real: a violação falha no CI no ponto da mudança (localidade), em vez de acumular como no panorama. É o candidato mais barato do relatório e protege todos os outros.

Problema

Os passos de recompensa — achar Character → wallet → Credit → incrementar XP → mutar a interação — estão copiados verbatim em TrackActivity e ApproveInteraction. O invariante "coins e XP andam juntos, atomicamente" é conhecimento que cada caller re-implementa. Pior: o XP é dado com $character->increment('experience') cru, ignorando o próprio IncrementExperience do gamification — existem dois caminhos de XP divergentes, e nenhum toca level-up: a tabela character_levelup não tem uma escrita sequer no repo.

Deletion test

Deletar o bloco inline → reaparece idêntico nos dois callers. Comportamento que ganha o sustento, mas sem lar — a assinatura de um módulo profundo faltando.

Solução

Uma action AwardReward(Character, RewardDTO) (dona: gamification) encapsulando wallet + Credit + XP via IncrementExperience + level-up, transacional. Os dois callers viram uma chamada. É também o gancho natural pro C7 (GitHub) e pra decidir o destino da superfície morta do C12.

Benefícios

Atomicidade coins+XP assertável uma vez (hoje nenhum teste cobre). Um lugar decide "XP mudou → subiu de nível?". Nova moeda/hook/auditoria = 1 arquivo.

Problema

O CONTEXT-MAP apresenta o evento como o seam do integration-github com o resto do sistema, e o ADR-0002 do onboarding especifica um listener dele. O lado emissor existe e é testado; o lado consumidor não existe. Uma contribuição no GitHub entra no lake e não gera XP, coins, nem sinal de onboarding. É um seam com zero adapters — junto com outros 3 eventos órfãos, enquanto o tráfego real entre módulos vai por import direto de model (panel-admin → moderation 53×).

Deletion test

Deletar o evento hoje → nada quebra fora do teste do próprio dispatch. Fiação morta.

Solução

Um listener no activity (ex.: AwardGithubContribution) mapeando o evento pra um TrackActivityDTO (provider github, externalRef = ref da contribuição) e chamando TrackActivity — que já tem idempotência e o pipeline de recompensa (e que o C6 aprofunda). Direção de dependência permanece legal: activity depende do evento, nunca o inverso.

Benefícios

Toda fonte de contribuição (Discord, dev.to, GitHub) passa pelo mesmo funil de ingestão. O caminho fim-a-fim "PR aprovado → coins na wallet" vira assertável — hoje é impossível testar porque não existe.

Problema

O que conta como falso positivo, o que é uma fila saudável, o que é cumprir SLA — são definições de domínio, não formatação. Elas vivem atrás de uma interface Livewire onde teste de domínio não chega, e a fórmula de FP-rate está escrita duas vezes (componente + widget), podendo divergir em silêncio. Os testes existentes só fazem assertSuccessful — nenhum valor é assertado.

Deletion test

Deletar o Livewire/widgets → as definições teriam de ser reconstruídas por qualquer caller futuro (relatório, API, alerta). Regras ganhando o sustento, no módulo errado.

Solução

Extrair um read-model He4rt\Moderation\Reporting (FalsePositiveRate, SlaCompliance, ModerationHealth, ModeratorScoreboard) com métodos que recebem período e devolvem valores tipados. Livewire e widgets viram adapters finos. O padrão saudável já existe no próprio painel: as query classes do Marketing são exatamente isso, e são testadas.

Benefícios

Uma regra, um lugar, N consumidores (dashboard, export, alerta). Fórmulas viram unit-testáveis no domínio em vez de alcançáveis só bootando a página.

Problema

As entidades Discord no painel são espelho do sync (integration-discord/src/Sync). O scaffold commitado (HEAD atual) registra Create/Edit e Delete/DeleteBulk — um caminho de escrita da apresentação sobre dados que o próximo sync sobrescreve silenciosamente. Contraria o CONTEXT.md do panel-admin ("never writes domain data"). A direção da dependência está certa; a superfície de mutação está errada.

Deletion test

Deletar as páginas Create/Edit + Forms → nenhuma capacidade se perde (edições seriam revertidas pelo sync). Pass-through que não deveria existir.

Solução

Aplicar a seção 5 do próprio plano commitado: converter os 5 resources pra read-only (ViewRecord + ViewAction, sem bulk), assertar /create → 404, e a migration de índice pra tabela de event logs (237k linhas). O repo está sentado no estado intermediário que o plano existe pra corrigir.

Benefícios

O painel deixa de ser um segundo caminho de escrita divergente pro estado sincronizado. Interface pequena e honesta: 5 resources read-only.

Problema

A remoção do multi-tenancy (commit 0e40e92e) foi ~95% completa em comportamento, mas deixou 3 caminhos de leitura vivos: uma coluna Filament searchable/sortable sobre a relação tenant que o Message não define mais; o ConnectionHub consultando um morph type extinto; e o CommunityReport consultando uma tabela dropada — falha dura em runtime. Além disso, o ADR-0001 do identity ainda ensina um passo de merge ("sync tenant memberships") que o MergeAccountsAction não executa — a interface documentada mente sobre seus invariantes. E OAuthFlowException::tenantNotFound() é um error mode que nunca pode disparar.

Deletion test

Detritos puros: deletar as 3 referências não exige substituto — apontam pro nada.

Solução

Remover coluna/queries/factory morto; nota de supersedência no ADR-0001 do identity (resolução = (provider, external_account_id, model_type=user) global, merge sem tenants); arch test barrando novas referências a tenants (entra no C5).

Benefícios

Remove erros latentes de runtime; o ADR volta a descrever o algoritmo real; leitor de migration não é enganado a achar que o sistema ainda é multi-tenant.

Problema

Cada integração re-deriva a mesma interface: envelope materializado + jsonb payload + chave de dedup + insert idempotente + "acabou de chegar evento novo". Os 4 mecanismos são incompatíveis (o do Twitch bypassa casts com json_encode manual e re-query — footgun real), e o seam "evento novo" tem 3 formatos: projector direto, event() e Observer. Quem entende um lake não entende os outros; a 5ª integração re-aprende tudo. O próprio time já reconheceu que é o mesmo conceito: o ADR do WhatsApp renomeou a tabela "alinhando com o sibling discord_event_logs" — convergência de nome sem convergência de código.

Solução

Um mecanismo compartilhado — RawEventStore::record(dedupKey, envelope, payload): {model, wasNew} — dono de: colunas canônicas, cast jsonb, hook de sanitize, upsert idempotente e sinal uniforme de "era novo". Cada integração fornece só a estratégia de chave e o callback de projeção. Tabelas continuam separadas.

Benefícios

Bugs de idempotência/sanitize consertados 1×, não 4×. Integração nº 5 = chave + callback. Um lugar pra provar idempotência e tolerância a payload venenoso.

⚠ Respeitar os ADRs do WhatsApp (0002/0003): UUIDv5 determinístico, ingest síncrono 2xx-após-commit, derive-later e sanitize são decisões defendidas — o módulo compartilhado tem de ser mecanismo, não política: estratégia de chave e fan-out plugáveis, ou re-quebra o ADR.

Problema

Deletion test em escala de módulo: events desaparece sem que complexidade reapareça em lugar nenhum (a própria migration dele derruba suas 7 tabelas). Todo o ciclo de vida Meeting/Feedback do community é inalcançável — nada chama as Actions; só os models são lidos como dados pela Season. E o gamification apresenta uma interface rica (níveis, reputação, badges, bônus diário) da qual só o contador de XP e a wallet estão ligados — ~34 arquivos que humanos e agentes de IA precisam ler e descartar a cada navegação.

Solução

Remover events; encolher community aos models vivos (ou marcar explicitamente como inerte com CONTEXT.md); pro gamification, decisão de produto por feature: ligar level-up/badges no seam AwardReward do C6, ou deletar a superfície dormante e registrar no roadmap. Não deixar "level-up" como comportamento implícito-mas-ausente atrás de uma escrita viva de XP.

Benefícios

Superfície honesta: o que existe funciona, o que não funciona não existe. Navegabilidade (humana e de IA) melhora imediatamente; 0 testes perdidos porque não há nenhum.