Settings

Status: 🟢 Estável (identidade + branding + pixel + compliance + domínios) Code: backend/app/modules/settings UI: frontend/src/app/(admin)/[slug]/admin/settings Última revisão deste doc: 2026-05-13 por Felipe + Claude Dependências fortes: fonte de kill switches centrais (council, agents, ai_auto_reply); custom domains com Traefik

1. Identidade

O que faz (uma frase)

Configurações por tenant: identity (nome, logo, contato, kill switches Conselho/Agentes), branding (cores, fonts), pixels (Meta, GA4, GTM, TikTok, Hotjar, Clarity, LinkedIn), compliance (LGPD, DPO), custom domains (DNS verification + Traefik YAML), legal entities (CNPJs lado vendedor).

Por que existe (negócio)

Sem este módulo:

• Branding hardcoded.
• Pixels manuais em cada landing page.
• Sem self-service de domínio próprio.
• Compliance docs avulsos.

Com Settings:

• Mais Consciente customiza visual completo (cores, logo).
• Pixel Meta + GA4 + Hotjar setado uma vez → todas as páginas aplicam.
• go.maisconsciente.com.br cadastrado → DNS verify → Traefik provisiona SSL automaticamente.
• LGPD compliance documentada (DPO, controlador, base legal, retention).

Status atual

Em prod, tudo deployado. Kill switches separados (Conselho council_enabled vs Agentes ai_auto_reply_enabled) — memória [[conselho-e-agentes-kill-switches-separados]].

2. Cases de uso reais

Case 1: Felipe customiza branding

UI → cores primária/secundária/accent → save → PUT /branding upsert → tenant.branding propagado pra UI via GET /public-bundle (SSR Next).

Case 2: Custom domain go.maisconsciente.com.br

1. UI /settings/domains → "Adicionar" → backend gera verification_token.
2. Felipe coloca TXT _mandir-verify.go.maisconsciente.com.br=<token> no DNS.
3. Beat check_pending_domains (10min) → DNS lookup → match → status=active + Redis update + Traefik YAML escrito + SSL provision.
4. go.maisconsciente.com.br resolve pra Suite.

Case 3: Kill switch Conselho

Felipe vai pra /admin/council/advisors → toggle "Conselho" off → PATCH /api/council/settings {council_enabled: false} → próxima @conselho no grupo é silenciosamente ignorada.

3. Oportunidades de negócio

• Whitelabel completo: branding + custom domain + pixel = produto sob marca própria do cliente.
• DNS as a service: wizards step-by-step por registrar (Namecheap, GoDaddy, Registro.br) — UX killer.
• Compliance pack vendido: LGPD docs prontos pra setores regulados.

4. Arquitetura interna

Arquivos

• models.py — 6 tabelas.
• service.py (~500 linhas).
• tasks.py — check_pending_domains (Beat 10min).
• routes.py — 22 endpoints.

Tasks

5. Tabelas (6)

settings_identity ⭐

settings_branding

Cores (primary, secondary, accent), fonts, custom CSS. UNIQUE per tenant.

settings_pixel

UNIQUE (tenant_id, provider).

settings_compliance

LGPD: privacy_policy_url, terms_url, dpo_name, dpo_email, controller, legal_basis, CNPJ company info. UNIQUE per tenant.

settings_domain

settings_legal_entity

CNPJs do tenant (lado vendedor). UNIQUE (tenant_id, cnpj).

Relacionamentos cross-módulo

6. API / Endpoints (22)

Prefixo /api/settings.

Identity / Branding / Compliance (6)

GET/PUT /identity, /branding, /compliance (upsert).

Pixels (3)

GET /pixels, PUT /pixels (upsert por provider), DELETE /pixels/{provider}.

Domains (5)

GET/POST /domains, PUT /domains/{id}, POST /domains/{id}/verify, GET /domains/{id}/dns-instructions (passo-a-passo por registrador), DELETE /domains/{id}.

Legal Entities (4)

GET/POST/PATCH/DELETE /legal-entities.

Public Bundle (1)

GET /public-bundle — chamado SSR Next, sem secrets.

7. Configuração

Env vars

8. Operações + Troubleshooting

Sintoma: Domain stuck em pending

Diagnóstico: Verificar TXT record DNS — dig TXT _mandir-verify.<domain>. Fix: Garantir TXT registrado, aguardar propagação (até 24h), wait beat ou re-trigger POST /domains/{id}/verify.

Sintoma: SSL não emitiu

Causa: Let's Encrypt rate limit ou DNS propagation lag. Fix: Aguardar 5-10min após status=active.

9. Limitações e débitos técnicos

10. Histórico

Em prod desde Suite v2. Kill switch Conselho separado em mig 0111 (memória [[conselho-e-agentes-kill-switches-separados]]).