ligbox-ops-platform/specs/017-vm112-domain-orchestration/spec.md

Feature Specification: Domínios VM112 — Purge & Histórico (017)

Criado: 2026-06-16
Actualizado: 2026-06-19 (extensões Spec 026 · Spec 032)
Solicitado por: Roger
Status: v1 + v2 concluídos · Fase 3 VM112 pendente
Prioridade: P1 (testes E2E + padrão de limpeza)
Sistema: Desk VM122 + Wizard VM112
Módulo: vm112-domains
UI purge: página Serviços (Spec 018)
UI histórico: Eventos → Histórico de purges

---

Resumo

Técnicos Admin (super_admin, ops_lead) executam purge completo de domínios VM112 (Carbonio, site, portal, Cloudflare, Traefik/SNI, registos Desk) a partir da página Serviços, com timeline ao vivo no drawer lateral.

v2 (2026-06-16): cada purge fica persistido em SQLite e consultável em Eventos → Histórico de purges — lista clicável + modal com timeline, utilizador e serviços removidos.

Uso inicial: limpar domínios de teste para reentrarem no wizard. Futuro: padrão de limpeza de dados por domínio.

---

Módulo Desk (Spec 015)

Campo	Valor
id	vm112-domains
label	Domínios VM112
default_enabled	true
nav_views	(vazio — purge na página Serviços, histórico em Eventos)

---

RBAC

Acção	Perfis
Executar purge (Serviços)	super_admin, ops_lead + senha Root
Ver histórico de purges (Eventos)	super_admin, ops_lead
Listar / detalhe job purge	super_admin, ops_lead

Técnicos technician e noc não acedem.

---

UI — Serviços (Spec 018)

Tile E-mail Tenant → modal purge

1. Resumo — domínio, mail host, admin portal, contas Carbonio, zona CF
2. Infra — passos get_status() (Carbonio, DNS, SNI, Traefik)
3. Contas — lista e-mails Carbonio
4. Zona perigosa — Purge (Admin only)
   • Aviso irreversível
   • Confirmação: digitar domínio exacto
   • Campo senha Root (Desk)
   • Botão «Apagar domínio e todos os dados»
5. Drawer lateral vm112-purge-drawer — timeline em tempo real durante execução

---

API Desk (VM122)

Método	Path	Descrição
GET	/api/v1/vm112/domains?q=	Lista domínios orquestrados (proxy VM112)
GET	/api/v1/vm112/domains/{domain}	Detalhe + infra status
POST	/api/v1/vm112/domains/{domain}/purge/jobs	Recomendado — purge async + polling
GET	/api/v1/vm112/purge/jobs/{job_id}	Estado / timeline do job
POST	/api/v1/vm112/purge/jobs/{job_id}/recover	Recuperar job após timeout UI
GET	/api/v1/vm112/purge/jobs?limit=&offset=	v2 — lista histórico persistido
POST	/api/v1/vm112/domains/{domain}/purge/stream	Purge SSE (legado Traefik)
POST	/api/v1/vm112/domains/{domain}/purge	Purge síncrono (legado)

Body purge:

{
  "confirm_domain": "iofficebooks.com",
  "root_password": "********"
}

Validações purge:

1. user.role ∈ {super_admin, ops_lead}
2. verify_password(root_password, hash do user root)
3. confirm_domain === domínio (case-insensitive)
4. Domínio ∉ blocklist (ligbox.com.br, etc.)
5. Proxy VM112 POST /api/admin/domains/{domain}/purge com X-Api-Key

Pós-purge Desk: apagar audit_domains, webhook_events, tickets, assist_sessions, audit_checks com referência ao domínio.

---

API VM112

Método	Path	Auth
GET	/api/admin/domains	X-Api-Key
GET	/api/admin/domains/{domain}	X-Api-Key
POST	/api/admin/domains/{domain}/purge	X-Api-Key
GET	/api/admin/domains/purge-jobs/{job_id}	X-Api-Key (memória, efémero)

Purge VM112 (ordem):

1. Apagar contas Carbonio (zmprov da)
2. Apagar domínio Carbonio (zmprov dd)
3. Remover portal users com planned_corporate_email no domínio
4. Apagar /opt/ligbox-sites/domains/{domain}/
5. Apagar zona Cloudflare (se existir na conta Ibytera)
6. Remover mail.{domain} do SNI + routers Traefik (CT114)
7. Apagar logs sessão JSONL com referência ao domínio

---

Fase 2 — Jobs async + polling (implementado)

POST /api/v1/vm112/domains/{domain}/purge/jobs inicia thread em background.
UI faz polling GET /api/v1/vm112/purge/jobs/{id} a cada 2s.

Motivo: SSE longo falhava via Traefik (504 / Failed to fetch ~60–79s).
Fix nginx Desk: proxy_read_timeout 600s em frontend/nginx.conf.

Persistência SQLite (vm112_purge_jobs) criada nesta fase — base para v2.

---

Fase 2 — SSE (implementado, legado)

POST /api/v1/vm112/domains/{domain}/purge/stream · text/event-stream

type	Conteúdo
step	{ label, at, status, detail }
heartbeat	{ elapsed } — cada 5s
error	purge falhou
done	{ desk, vm112, domain }

Ordem: validação → VM112 (heartbeat) → passos VM112 → passos Desk → concluído.

---

v2 — Histórico de purges (implementado 2026-06-16)

Problema resolvido

Antes	Depois
Timeline só ao vivo no drawer	Histórico persistente no Desk
Dados em SQLite sem UI	Lista + modal de detalhe
VM112 jobs em memória (efémero)	Fonte de verdade: VM122 ops.db
Purges «desapareciam» ao fechar modal	Consulta por domínio, data, utilizador

Nota: purges antes da persistência (ex.: betinsport.com) não aparecem no histórico.

UI — Eventos

• Aba Webhooks (existente)
• Aba Histórico de purges (Admin only)
• Lista: Job ID, domínio, status, utilizador, resumo Desk, data, duração VM112
• Clique na linha → modal com:
  1. Cabeçalho (domínio, status, utilizador, data, job id)
  2. Removido no Desk — webhook_events, tickets, audit_domains, assist_sessions, audit_checks
  3. Removido na VM112 — Carbonio, portal, site, Cloudflare, Traefik
  4. Timeline completa (timeline_json)

Persistência

Campo	Valor
Base	/var/lib/ligbox-ops-platform/ops.db (Docker: /data/ops.db)
Tabela	vm112_purge_jobs
Colunas	timeline_json, desk_json, vm112_json, by_user, status, created_at

Ficheiros v2

Ficheiro	Alteração
api/app/vm112_purge_jobs.py	list_jobs(), schema, persistência
api/app/vm112_domains_routes.py	GET /purge/jobs
frontend/assets/app.js	renderPurgeHistory(), modal, aba Eventos
frontend/index.html	Toolbar Eventos + purge-history-modal
frontend/assets/styles.css	Estilos lista/modal

Critérios de aceitação v2

1. Admin vê aba «Histórico de purges» em Eventos.
2. Lista mostra purges com status, utilizador, data e resumo Desk.
3. Clique abre modal com timeline completa e contagens por serviço.
4. Badges correctos: done, error, running, queued.
5. technician / noc não vêem a aba.

Consulta manual (SSH VM122)

sqlite3 /var/lib/ligbox-ops-platform/ops.db \
  "SELECT id, domain, status, by_user, created_at FROM vm112_purge_jobs ORDER BY created_at DESC;"

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://desk.ligbox.com.br/api/v1/vm112/purge/jobs/57845ca1c5c64b53"

---

Extensão — Spec 026 (purge Traefik validation)

Validação YAML + smoke onboard pós-remoção Traefik (CT114). Incidente 2026-06-19: dynamic.yml inválido após purge → 404 global no onboard.

Spec dedicada: specs/026-purge-traefik-validation/spec.md

---

Extensão — Spec 032 (purge autorização extra)

Domínios em PURGE_EXTRA_AUTH_DOMAINS (ex.: myvexx.com) exigem código de autorização gerado pelo root em Infra (senha Root), além da validação purge normal.

Camada	Regra
Blocklist	ligbox.com.br, itecnologys.com — purge proibido
Extra auth	Código único + senha Root
Normal	Senha Root (Spec 017 v1)

Spec dedicada: specs/032-purge-domain-extra-auth/spec.md
UI geração: Infraestrutura → «Códigos autorização purge»
UI consumo: Serviços → modal purge (campo código)

---

Fase 3 — VM112 passos em tempo real (pendente)

VM112 (/opt/ligbox-wizard) emitir passos individuais durante execução (Carbonio, CF, Traefik) em vez de bloco único + heartbeat. Alterações no wizard, não só no Desk.

---

Critérios de aceitação (v1)

1. Admin executa purge a partir de Serviços.
2. Purge com senha root errada → erro na timeline.
3. Purge com domínio confirmado errado → HTTP 400.
4. Após purge, domínio ausente em Carbonio, ligbox-sites e Desk.
5. Drawer mostra progresso ao vivo; job persiste em SQLite.

---

Fora de escopo

• Purge parcial (só contas, só DNS)
• Scheduler de limpeza automática
• Export CSV/PDF do histórico
• Filtro por domínio/data na lista de histórico
• Retenção automática / purge de jobs antigos
• Link directo Serviços → histórico do domínio

---

Conclusão (2026-06-16)

A Spec 017 cobre o ciclo completo de purge de domínio VM112:

Fase	Entrega	Estado
v1	Purge completo via Serviços + validação Root	✅
Fase 2	Jobs async, polling, persistência SQLite	✅
Fase 2 SSE	Timeline drawer (legado)	✅
v2	Histórico em Eventos — lista + modal audit trail	✅
032	Códigos autorização extra (myvexx.com) — Infra + Serviços	✅
026	Validação Traefik pós-purge	✅
Fase 3	Passos VM112 em tempo real no wizard	⏳

Purges registados (exemplo): myvexx.com, diarissima.com, ibytera.com — visíveis em Eventos → Histórico de purges.

Próximo passo natural: Fase 3 no wizard VM112; depois filtros/export no histórico se necessário.