Pular para o conteúdo
ClinicGestor — Docs

0002 — Modelo Consultivo Tri-Lens

Status

Accepted · 2026-04-26 · Autor: Alexandre Calmon + Claude.

Sucessor do “Modelo Consultivo do Superadmin” do v1, agora estendido pra tri-lens dada a tenancy multi-consultancy (ADR 0001).

Contexto

No v1 documentamos “Modelo Consultivo do Superadmin” com dual-lens: lente clínica (operacional) + lente Superadmin (Karla via tudo cross-clinic). Funcionou pra primeira fase mas com tenancy multi-consultancy (ADR 0001) precisa virar tri-lens:

  1. Operacional — clínica usa plataforma no dia a dia (agenda, prontuário, financeiro)
  2. Consultiva — consultancy_owner/admin/analyst usa dados das suas clínicas pra ministrar consultoria operacional (com IA, dashboards, análises)
  3. Analítica — platform_admin (Alexandre) vê métricas agregadas das consultorias e clínicas pra advisory aos consultores parceiros (sem PII)

A principal nuance é que o platform_admin é ainda mais restrito que o superadmin do v1: nada de PII operacional, só agregados.

Decisão

Toda tabela tenant-scoped nasce com policies tri-lens:

-- Padrão pra tabela tenant com PII clínica:
CREATE POLICY "<tabela>_clinic_scope" ON public.<tabela>
  FOR ALL TO authenticated
  USING (public.is_clinic_member(clinic_id))
  WITH CHECK (public.is_clinic_member(clinic_id));


CREATE POLICY "<tabela>_consultancy_lens" ON public.<tabela>
  FOR SELECT TO authenticated
  USING (public.consultancy_has_data_access_to(clinic_id));


-- Sem policy pra platform_admin em tabela com PII!
-- platform_admin acessa só via views agregadas (ver §3 abaixo)

1. Lente operacional (clínica)

  • is_clinic_member(clinic_id) libera acesso à própria clínica
  • Read + write conforme role_key (clinic_owner / clinic_admin / clinic_staff) e permissions_override
  • PII de paciente sempre cifrada (regra inviolável §5.3.3 do AGENTS.md)

2. Lente consultiva (consultancy)

  • consultancy_has_data_access_to(clinic_id) libera SELECT em tabelas com PII clínica
  • Helper retorna true apenas se:
    • Consultor é membro da consultoria atual da clínica OU da attribution
    • E clínica tem data_sharing_with_consultancy = 'granted' (consent explícito)
    • OU existe pacote avulso ativo (Ideia 1.J — consent escopado)
  • Sem write em dados clínicos (consultor aconselha; staff da clínica executa)
  • Read agregado sobre múltiplas clínicas suas via dashboards
  • IA consultiva (consulting_insights, proposal_draft, pre_call_briefing, etc) com escopo da consultoria

3. Lente analítica (platform_admin)

  • is_platform_admin() libera apenas:
    • Tabelas de configuração (platform_settings, platform_pricing_tiers, etc)
    • Views agregadas (consultancy_metrics_daily, platform_kpis_daily, programa_acolhe_kpis_daily)
    • Audit logs (compliance — ver toda movimentação)
    • Tabelas próprias da plataforma (consultancies listing, etc)
    • Tabelas de admin do AI Gateway (ai_providers, ai_models, ai_module_configs)
  • Sem acesso a PII operacional:
    • ❌ Pacientes
    • ❌ Agendamentos individuais
    • ❌ Prontuários
    • ❌ Leads das consultorias
    • ❌ Propostas individuais
    • ❌ Contratos individuais

Views agregadas têm with (security_invoker = on) e policy explícita using (public.is_platform_admin()). Cascata de consent (ADR 0009) filtra automaticamente: clínica que não autorizou consultor (flag A=denied) não entra no agregado mesmo se consultor autorizou plataforma (flag B=granted).

4. Módulo platform_advisor (IA)

10º módulo de IA exclusivo do platform_admin:

  • Recebe apenas métricas agregadas das consultorias
  • Redação stricta: nomes de consultorias podem aparecer (são clientes do platform_admin); nomes de clínicas, pacientes, ou métricas individuais identificáveis são bloqueados
  • Gera advisory pra Alexandre ajudar consultores: “Consultor X tem churn 30% acima da mediana — sugerir treinamento em retenção”
  • Nunca toca em PII de paciente nem em dado individual de clínica

5. Princípio: “todo módulo nasce com as 3 lentes”

Quando criar módulo novo:

  1. Pensar como clínica usa (lente operacional)
  2. Pensar como consultor agrega/analisa cross-clinic (lente consultiva, com consent)
  3. Pensar quais métricas agregadas o platform_admin precisa (lente analítica, sem PII)

Não é “fazer operacional primeiro e adicionar consultivo depois” — é entregar as 3 lentes juntas, ou explicar no ADR específico do módulo por que alguma não se aplica.

Consequências

Positivas

  • Confiança comercial: consultor sabe que dono da plataforma não bisbilhota suas clínicas
  • LGPD-strong: superfície de risco do platform_admin é mínima
  • Vendável: “Sua plataforma é sua. Plataforma vê só o agregado.”
  • Escalável: padrão tri-lens replicável em todo módulo

Negativas

  • Schema mais complexo: cada tabela operacional precisa pensar em qual policy de cada tier
  • Views agregadas precisam ser desenhadas com cuidado: erro de SQL pode vazar dado individual em campo agregado

Riscos

  • Bug em view agregada: select count(*) from clinics where ... em vez de select count(distinct clinic_id) from ... pode ter cardinalidade ruim
  • Bug em redact do platform_advisor: PII chegar até prompt LLM
  • Mitigação: testes específicos por view agregada (cobertura de cardinalidade); tests de redact (regex matchers contra PII conhecida)

Alternativas consideradas

1. Dual-lens (status quo do v1, ampliado)

Manter superadmin mas escopar por consultoria.

  • Prós: simplicidade
  • Contras: mistura privilégios (consultor que vê dados também vê configurações da plataforma); confunde papéis. Rejeitado — princípio de least privilege.

2. Single-lens (paranoid)

Cada nível só vê seu próprio (clínica vê clínica, consultor vê só sua “consultoria entity” sem dados de clínicas, platform_admin só configurações).

  • Prós: separação total
  • Contras: consultor não consegue fazer consultoria sem ver os dados das clínicas dele. Inviabiliza o produto. Rejeitado.

3. Tri-lens com platform_admin vendo dados granulares (status quo do v1 com is_superadmin)

  • Prós: facilita debug + análise pelo dono
  • Contras: viola LGPD em escala (você fica responsável por dado pessoal de centenas de clínicas; pra que precisa ver caso individual?). Rejeitado após decisão estratégica do Alexandre.

Atualizações de documentos exigidas neste ADR

  • AGENTS.md §5.2 (regras de tenancy + tri-lens)
  • BLUEPRINT.md §1 (diagrama tenancy), §3 (camadas de segurança)
  • ADR 0001 (referência cruzada)
  • ADR 0009 (consent em camadas — fundamento da lente consultiva)

Referências

  • ADR 0001 (multi-consultancy foundation)
  • ADR 0009 (consent em camadas)
  • AGENTS.md §5.2, §5.3, §9
  • BLUEPRINT.md §1, §3