Admin — Criação de Clientes

Implementado em: 2026-04-02 Status: Ativo

---

Resumo

O painel admin permite criar clientes (tenants) manualmente, sem depender do fluxo automático de signup via Clerk. Útil para onboarding personalizado, demos e clientes enterprise.

---

Fluxo

1. Admin acessa /admin/clients
2. Clica "Novo Cliente"
3. Preenche: Nome da Empresa + Plano
4. Backend gera org_id único (org_manual_{uuid12})
5. Chama provision_tenant():
   • Cria schema PostgreSQL isolado
   • Registra em public.tenants
   • Cria todas as tabelas do tenant
   • Seed de configurações padrão
6. Cliente aparece na lista como "Ativo"

---

Endpoint

POST /admin/tenants

Auth: require_staff_permission("tenants:write")

Request:

{
  "orgName": "Loja do João",
  "planId": 1
}

Response (201):

{
  "id": 5,
  "orgId": "org_manual_a1b2c3d4e5f6",
  "schemaName": "tenant_org_manual_a1b2c3d4e5f6",
  "planId": 1,
  "status": "active",
  "createdAt": "2026-04-02T12:00:00Z",
  "orgName": "Loja do João",
  "metadata": { "api_key": "uuid", "orgName": "Loja do João" }
}

---

Frontend

Página: frontend/src/app/(dashboard)/admin/clients/page.tsx

• Botão "Novo Cliente" no header (azul, gradiente)
• Modal com backdrop blur
• Campo "Nome da Empresa" (input text, autoFocus)
• Campo "Plano" (dropdown carregado via GET /admin/plans)
• Info box: "Um schema PostgreSQL isolado será criado..."
• Botão "Criar Cliente" com loading state ("Provisionando...")
• Invalida cache da lista ao criar

---

Diferença: Criação Manual vs Automática

Aspecto	Manual (Admin)	Automática (Clerk)
Trigger	Botão "Novo Cliente"	Webhook organization.created
org_id	org_manual_{uuid}	org_{clerk_id}
Auth Clerk	Não vinculado	Vinculado ao usuário
Plano	Selecionado pelo admin	Definido no checkout
Uso	Demos, enterprise, onboarding	Self-service (signup)

---

Arquivos

Arquivo	Função
backend-python/app/api/admin.py	Endpoint POST /admin/tenants
backend-python/app/services/tenant/provision_service.py	Provisioning 5 etapas
frontend/src/app/(dashboard)/admin/clients/page.tsx	UI com botão + modal