ligbox-ops-platform/specs/037-dns-multi-cloudflare-orchestration/client-cf-account-lifecycle.md

Anexo 037-B — Conta Cloudflare por cliente (e-mail proj + handoff gestor)

Parent: spec.md · Spec 037
Solicitado por: Roger · 2026-06-22
Status: 📋 Regra definida — implementação Fase 2

---

Regra de negócio (Roger)

Novos clientes que escolhem vir para Cloudflare gerenciada pela Ligbox recebem uma conta Cloudflare dedicada (não zona partilhada nas contas mãe ligit/itecnologys/ibytera a longo prazo).

Fase A — Onboarding (conta sob controlo Ligbox)

Campo	Valor
E-mail titular / membro inicial	proj_{id}@ligbox.com.br (ex.: proj_005@ligbox.com.br)
Nome da conta CF	Dados do domínio do cliente (ex.: Empresa XYZ — empresa.com.br)
Zona DNS	cliente.com.br criada nesta conta
Gestão	Ligbox opera via API token / membro admin Ligbox

O proj_{id} vem do ID de projeto/onboarding (sequencial ou UUID curto no wizard / Ops Desk).

Fase B — Handoff (conta estável)

Quando a conta estiver setada e a funcionar (DNS verificado + conta email Carbonio criada + infra OK):

1. Convidar admin@{dominio_cliente} (ou e-mail indicado no wizard) como gestor na conta Cloudflare.
2. Role sugerida: Administrator (ou custom com Zone DNS + Read mínimo se preferirem).
3. Manter proj_{id}@ligbox.com.br como membro técnico Ligbox (não remover até handoff confirmado).
4. Registar em domain_registry: cf_account_id, cf_member_client_email, handoff_status.

Opcional futuro: promover e-mail do cliente a owner principal e rebaixar proj_* a read-only — depende da política Cloudflare Tenant.

---

Fluxo wizard (alvo Fase 2)

sequenceDiagram
  participant W as Wizard VM112
  participant CF as Cloudflare API
  participant M as Mail ligbox.com.br
  participant C as Cliente

  W->>W: Gera project_id (ex. 005)
  W->>M: Cria proj_005@ligbox.com.br + senha
  W->>C: Entrega credenciais projeto (wizard)
  W->>CF: POST /accounts (name=cliente.com.br)
  Note over CF: Membro inicial proj_005@ligbox.com.br
  W->>CF: POST /zones (account_id novo)
  W->>CF: upsert MX/SPF/DMARC
  W->>C: NS no registrador
  C->>C: Propaga DNS
  W->>W: dns/verify OK + account/create OK
  W->>CF: POST /accounts/{id}/members (admin@cliente.com.br)
  CF->>C: Convite gestor
  W->>M: Notifica ops + cliente

---

Relação com Fase 1 (actual)

Fase 1 (hoje)	Fase 2 (regra Roger)
Zona nova em conta partilhada ibytera	Conta CF nova por cliente
Token único conta mãe	Token scoped por cf_account_id cliente
Sem proj_*@ligbox.com.br	E-mail projeto Ligbox como membro inicial
Sem handoff gestor	Convite admin@dominio pós-go-live

Transição: Fase 1 mantém-se até Tenant API / tokens prontos; novos clientes premium ou flag dedicated_cf_account: true usam Fase 2.

---

Pré-requisitos técnicos

1. E-mails proj_*@ligbox.com.br

• O agente Ligbox cria caixa real no Carbonio (ligbox.com.br) via project_identity.provision_project_email().
• Entrega senha ao cliente no wizard (uma vez) — ver project-email-identity.md.
• Padrão: proj_{project_id:03d}@ligbox.com.br.
• Referenciado em: CF member, domain_registry, webhooks DNS, activity_log.

2. API Cloudflare

Operação	Endpoint	Permissão
Criar conta	POST /accounts	Tenant admin (organização Ligbox)
Criar zona	POST /zones	Account Zone Edit na conta nova
Convidar gestor	POST /accounts/{id}/members	Account User Management
Abuse contact	settings.abuse_contact_email	Pode ser admin@cliente.com.br desde Fase A

POST /accounts está limitado a tenant admins. Se Ligbox ainda não tiver Tenant, alternativa interina: zonas na conta mãe (Fase 1) até activar Tenant.

3. Registo interno (VM112)

Ficheiro ou DB por domínio (/var/lib/ligbox-wizard/cf_client_accounts/{domain}.json):

{
  "domain": "empresa.com.br",
  "project_id": "005",
  "ligbox_email": "proj_005@ligbox.com.br",
  "cloudflare_account_id": "…",
  "cloudflare_account_name": "Empresa XYZ — empresa.com.br",
  "zone_id": "…",
  "client_manager_email": null,
  "handoff_status": "pending",
  "created_at": "2026-06-22T12:00:00Z",
  "handoff_at": null
}

4. Gatilho handoff

Automático quando todos verdadeiros:

• GET /dns/verify/{domain} → ready: true
• POST /account/create → sucesso
• infrastructure.ready (se aplicável)

Então: POST /dns/cloudflare/handoff-manager com { domain, manager_email: "admin@empresa.com.br" }.

---

Endpoints planeados (Fase 2)

Método	Path	Descrição
POST	/dns/cloudflare/provision-client-account	Cria conta CF + zona + registo proj_*
POST	/dns/cloudflare/handoff-manager	Convida gestor do domínio cliente
GET	/dns/cloudflare/client-account/{domain}	Estado handoff (ops)

---

Critérios de aceitação (Fase 2)

1. Cliente novo → conta CF com nome do domínio e membro proj_{id}@ligbox.com.br.
2. Zona + apontamentos mail na conta do cliente, não na mãe ibytera.
3. Após go-live → convite admin@cliente.com.br enviado e registado.
4. proj_* permanece acessível à Ligbox para suporte.
5. BYO / registrador não passam por este fluxo.

---

Pergunta em aberto (Roger)

Formato do project_id: sequencial 005 (proj_005@) ou slug do domínio (proj_empresa-com-br@)? Recomendação: sequencial numérico — mais limpo e alinhado ao exemplo.