Pular para conteúdo

Hierarquia multi-conta

Estado atual

Disponível em produção para operação interna por super_admin.

O MVP permite habilitar uma conta raiz como conta-mãe e criar subcontas operacionais em /app/admin/tenants, sem criar login, convidar cliente ou executar onboarding completo.

Issues: DEV-1842 e DEV-1919

Release: PR #407, merge commit 589e1468

Migrations: 20260826190000 e 20260829200000

O que está funcional

  1. O Super Admin habilita flag_multi_account_enabled na conta raiz.
  2. Em /app/admin/tenants, clica em Nova subconta.
  3. Seleciona a conta-mãe e informa o nome da filha.
  4. O backend autentica a sessão e deriva o ator real.
  5. A RPC transacional cria a subconta e suas estruturas mínimas.
  6. A filha aparece imediatamente na listagem com sua hierarquia e saldo 0/0.

A criação gera apenas:

  • tenant ativo vinculado à conta-mãe;
  • configuração vazia;
  • onboarding pendente na fase 1;
  • carteira ativa com zero créditos;
  • ledger privado de idempotência;
  • auditoria administrativa.

Ela não cria usuário, membership, bônus, CRM, dossiê, editoriais, ideias ou pipelines.

Segurança

  • A hierarquia tem somente um nível: uma subconta não pode ser mãe.
  • parent_tenant_id é imutável depois do INSERT.
  • A conta-mãe precisa ser raiz, ativa, não arquivada e estar com a flag ligada.
  • Hierarquia não concede acesso: sem membership explícita, ninguém da mãe vê a filha automaticamente.
  • A rota autentica antes de validar o payload.
  • A RPC usa SECURITY DEFINER, search_path vazio e execução exclusiva por service_role.
  • anon e authenticated não acessam o ledger nem executam a RPC.
  • Login, callback, recovery, JWT, cookies sb-* e resolveTenant não foram alterados.

Idempotência

Cada criação exige Idempotency-Key.

  • Mesma chave e mesmo payload: retorna a mesma subconta, sem duplicar dados.
  • Mesma chave e payload diferente: retorna conflito.
  • Requisições concorrentes com a mesma chave convergem para um único tenant.

Validação

Preview

O E2E foi executado três vezes no SHA exato promovido. Validou criação pela UI, replay idempotente, concorrência HTTP, ausência de efeitos proibidos, revogação de sessão e cleanup com zero resíduo.

Produção

Em 30/08/2026, um canário isolado executou o caminho real:

  • criação de usuário QA descartável pela API oficial do Supabase;
  • login real e acesso ao Admin;
  • criação pela interface com resposta 201;
  • replay idempotente com resposta 200;
  • validação das estruturas mínimas e dos efeitos proibidos;
  • revogação da sessão;
  • remoção integral das fixtures;
  • auditoria final com zero registros remanescentes.

O harness versionado continua recusando produção. Um canário produtivo só pode ser executado com autorização textual atual, identidade descartável e cleanup fail-closed.

Limites deste MVP

Ainda não estão incluídos:

  • convite ou acesso do cliente à subconta;
  • criação self-service por Owner;
  • papéis e permissões granulares;
  • compra central e distribuição de créditos;
  • onboarding específico de novas subcontas;
  • operação completa de conteúdo no tenant selecionado em todas as superfícies.

Esses itens pertencem às próximas Stories do projeto multi-conta.

Troubleshooting

Sintoma Causa provável Ação
Conta não aparece como mãe Filha, arquivada, sem config ou flag desligada Corrigir em /app/admin/flags
Retry retorna conflito Chave usada com outro payload Fechar e reabrir o diálogo
Usuário da mãe não vê a filha Comportamento esperado sem membership Criar acesso apenas quando a Story de convites existir
Não é possível desabilitar a mãe Existe filha ativa Resolver o lifecycle da filha antes

Referências