Toggles de IA por empresa, integração e message type

O Lefia permite controle granular do uso de IA por scope. Por padrão a IA fica ligada em tudo; a tabela ai_settings só armazena overrides explícitos.

Hierarquia de resolução

Quando um endpoint de IA é chamado, o sistema procura a regra mais específica e usa o enabled dela. Se nenhuma regra existe, default = ON.

message_type   →  integration  →  empresa  →  default ON
  (mais específico)                            (default)

Exemplo: empresa "Acme" tem regra "IA off no tenant" mas integração "Acme/SAP-DEV" tem regra "IA on" — chamadas dentro dessa integração vão usar IA. Mensagens em outras integrações da Acme ficam off.

Onde os toggles são aplicados

Endpoint	Toggle aplicado?
`POST /api/ai/diagnose`	✅ sim — checa tenant/integration/message_type da mensagem
`POST /api/mapeamentos/interpret-log`	✅ sim — checa tenant/integration
`POST /api/mapeamentos/create-message-type`	✅ sim — pula sugerir mapping IA se off (cria o mt sem IA)
`POST /api/mapeamentos/suggest-mapping`	❌ não — admin tool
`POST /api/mapeamentos/suggest-format`	❌ não — admin tool
`paraphraseDescriptions` (lib)	❌ não — admin tool

**Por que admin tools (suggest-*) não respeitam toggle?** Eles operam sobre catálogos de campos/standards (não payload de cliente final). O risco de PII é mitigado pelo pipeline de redaction (FT-PII-REDACTION). Toggle universal entra em versão futura.

Como configurar

/admin/ai-settings (super_admin only)
"Adicionar regra"
Selecione empresa → opcional integração → opcional message_type → marque como Desligada/Ligada → motivo (recomendado pra audit)

Comportamento quando IA está off

O endpoint retorna HTTP 200 com payload:

{
  "ai_disabled": true,
  "level": "tenant" | "integration" | "message_type",
  "reason": "..."
}

A UI deve detectar ai_disabled e mostrar mensagem amigável ao usuário.

Auditoria

Toda criação/atualização/exclusão de regra é registrada em audit_events com action ai_settings.created / ai_settings.updated / ai_settings.deleted.

Cache

Resolução de toggle usa cache em memória de 60 segundos por tenant. Após criar/editar/excluir uma regra, o cache do tenant é invalidado automaticamente. Em ambientes multi-instância (Vercel Functions), cada instância tem cache próprio — propagação efetiva em até 60s.

Schema

Tabela ai_settings em /supabase/migrations/20260506000000_ai_settings.sql. UNIQUE em (tenant_id, integration_id, message_type_id) com sentinela pra nullables (gotcha conhecido do Postgres). RLS: super_admin escreve/lê tudo, membro do tenant só lê.

Veja também

pipeline-mensagens-fluxos — fluxos completos do retry/DLQ
pii-redaction-llm — redaction antes da IA, atua independente do toggle
certificado-digital-mtls — mTLS pra SEFAZ