ligbox-ops-platform/spec.md

Spec 027 — Matriz de Acesso por Função (Time Ligbox)

Criado: 2026-06-19
Solicitado por: Roger
Status: Draft → Fase 2 implementada (Desk RBAC)
Prioridade: P0 (governança operacional)
Sistemas: VM112 (Onboard/Mail) · VM122 (Ops Desk) · VM123 (Finance/Hosting)
Depende de: Spec 003 (RBAC base), 004 (cadastro), 015 (módulos), 023/024 (billing), 018 (serviços)
Estende: Spec 003 — não substitui login/MFA/webhooks; adiciona funções e ambientes

---

Resumo

Esta spec define a matriz de acesso ao nível de função para todo o time Ligbox — ops, suporte, financeiro, marketing, SEO, desenvolvimento e funções complementares — com permissões explícitas nos três ambientes operacionais:

VM	IP	Papel
VM112	10.10.10.112	Wizard onboarding, Carbonio mail tenants, API portal
VM122	10.10.10.122	Ligbox Ops Desk (control plane humano)
VM123	10.10.10.123	FOSSBilling, Odoo 16, OpenPanel (financeiro + sites)

Regra de ouro: humanos entram sempre pelo Desk (VM122) ou consolas web dedicadas com conta @ligbox.com.br. SSH direto às VMs é excepção para super_admin e devops — demais funções usam APIs, deep-links e SSO futuro.

Legenda global

Símbolo	Significado
✅	Acesso total (CRUD / executar)
🔒	Só leitura (dados podem ser mascarados)
🔗	Deep-link / abrir consola externa (nova aba) — sem credencial partilhada
⚙️	Só via API Desk (sem SSH)
🤖	Conta de sistema / agente autónomo
❌	Sem acesso

---

1. Catálogo de funções

1.1 Funções ops — já existentes (Spec 003)

ID função	Label Desk	Descrição
super_admin	Super Admin	Roger / dono — users, tenants, purge, config global
ops_lead	Chefe Ops	Gestão operacional, audit, tickets, domínios VM112
technician	Suporte	Tickets atribuídos, assist/takeover wizard, migração
noc	NOC	Monitorização read-only, Wazuh, health — dados sensíveis mascarados

1.2 Funções comercial e negócio (novas)

ID função	Label Desk	Descrição
sales_admin	Sales Admin (Gerente Comercial)	Gestão pipeline, preços, equipa comercial, pedidos FOSS, aprovações
sales_support	Sales Support (Analista Comercial)	Atendimento comercial, pedidos, clientes, CRM — sem config admin
finance	Financeiro	FOSSBilling, Odoo fiscal, validação billing, faturas, inadimplência
marketing	Marketing	Campanhas, landing, produtos FOSS, leads CRM
seo	SEO	DNS público, Search Console, performance web, sites OpenPanel
developer	Developer	Código wizard/Desk, GitHub, deploy, integrações API

Substitui o role genérico sales — usar sempre sales_admin ou sales_support.

1.3 Funções plataforma (recomendadas)

ID função	Label Desk	Porquê
devops	DevOps / Infra	Proxmox, Traefik CT114, pfSense, OpenPanel admin — não confundir com developer
security_analyst	Segurança / SOC	Incidentes, Wazuh rules, resposta — além do noc (só leitura)
content_editor	Conteúdo / CMS	Sites clientes no OpenPanel — cruza marketing mas foco operacional
agentic_operator	Operador Agentes IA	Aprova runbooks e acções dos agentes A0–A7 antes de remediação

1.4 Funções sistema (não humanas)

ID função	Tipo	Descrição
api_service	M2M	Webhooks VM112→122, workers, cron interno
agent_system	IA	Super-utilizador dos 7 agentes (ver secção 6)

1.5 Funções cliente (fora do time — referência)

ID função	Onde	Nota
client_domain_admin	Wizard /admin VM112	Gerente do domínio — não é função Desk
client_readonly	Futuro portal cliente	Spec futura

---

2. Matriz — Ambiente VM112 (Onboard + Mail)

Componentes: onboard.ligbox.com.br · ligbox.com.br · Carbonio · ligbox-wizard API :8090 · SSH · Carbonio Admin

Função	Desk assist / wizard	API VM112	Carbonio admin	SSH VM112	Purge domínio
super_admin	✅ takeover	✅	✅	✅	✅
ops_lead	✅ takeover	✅	🔗	🔗	✅
technician	✅ takeover*	⚙️ assist	🔗	❌	❌
noc	🔒 observar	🔒	❌	❌	❌
finance	🔒 ver sessão	🔒 billing fields	❌	❌	❌
marketing	🔒 funil/leads	🔒	❌	❌	❌
seo	🔒 domínio/DNS	🔒 dns verify	❌	❌	❌
developer	⚙️ dev/staging	✅ API dev key	❌	🔗	❌
sales_admin	🔒 leads + billing	🔒	❌	❌	❌
sales_support	🔒 leads	🔒	❌	❌	❌
devops	🔒 infra status	✅ infra endpoints	🔗	✅	⚙️ com root
security_analyst	🔒 telemetria	🔒	❌	🔗	❌
content_editor	❌	❌	❌	❌	❌
agentic_operator	🔒 + aprovar	⚙️	❌	❌	❌
api_service	🤖 webhooks	🤖	❌	❌	❌

* technician: takeover apenas tickets/sessões atribuídas (Spec 010).

URLs VM112

Recurso	URL
Wizard	https://onboard.ligbox.com.br
API	http://10.10.10.112:8090 (LAN) / Traefik interno
Webmail admin tenant	https://mail.{dominio}/
Painel domínio	https://onboard.ligbox.com.br/admin

---

3. Matriz — Ambiente VM122 (Ops Desk)

Componentes: desk.ligbox.com.br · api.ops.ligbox.com.br · módulos Spec 015

3.1 Módulos Desk × função

Módulo (ID)	super_admin	ops_lead	technician	noc	finance	sales_admin	sales_support	marketing	seo	developer	devops	security_analyst	content_editor	agentic_operator
core (dashboard/tickets)	✅	✅	✅	🔒	🔒	✅	✅	🔒	🔒	🔒	🔒	🔒	🔒	🔒
overview	✅	✅	🔒	🔒	🔒	✅	🔒	🔒	🔒	🔒	🔒	🔒	❌	🔒
overview-home (Serviços)	✅	✅	✅	🔒	🔒	✅	✅	🔒	🔒	🔒	✅	🔒	🔒	🔒
infra / infra2-soc	✅	✅	🔒	🔒	❌	❌	❌	❌	🔒	🔒	✅	✅	❌	🔒
funnel-timing	✅	✅	✅	🔒	🔒	✅	✅	✅	✅	🔒	❌	❌	❌	🔒
wazuh-soc	✅	✅	🔒	🔒	❌	❌	❌	❌	❌	❌	🔒	✅	❌	🔒
leads (abandono CRM)	✅	✅	✅	❌	🔒	✅	✅	✅	✅	❌	❌	❌	❌	❌
events (webhooks)	✅	✅	🔒	🔒 wazuh	🔒 billing	🔒	🔒	🔒	🔒	⚙️	⚙️	🔒	❌	⚙️
tenants	✅	✅	✅	🔒	🔒	✅	🔒	🔒	🔒	🔒	🔒	🔒	❌	🔒
messages (cadastro)	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌
admin-users	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌
billing-recurrence (023)	✅	✅	🔒	❌	✅	✅	🔒	❌	❌	❌	❌	❌	❌	❌
migration (013)	✅	✅	✅	🔒	❌	❌	❌	❌	❌	❌	🔒	❌	❌	❌
assist (010)	✅	✅	✅	🔒	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌
modules (toggle)	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌

3.2 Acções API críticas × função (extensão Spec 003)

Acção	super_admin	ops_lead	technician	noc	finance	sales_admin	sales_support	marketing	seo	developer	devops	security_analyst	agentic_operator
Fechar ticket	✅	✅	✅*	❌	❌	✅	✅	❌	❌	❌	❌	❌	❌
Assist takeover wizard	✅	✅	✅*	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌
Disparar audit manual	✅	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌
Purge domínio VM112	✅	✅	❌	❌	❌	❌	❌	❌	❌	❌	⚙️	❌	❌
Validar billing (billing_state)	✅	✅	❌	❌	✅	✅	❌	❌	❌	❌	❌	❌	❌
Criar pedido FOSS (VM123)	✅	✅	❌	❌	🔒	✅	✅	❌	❌	⚙️	❌	❌	❌
Ver CNPJ / morada completa	✅	✅	✅	❌ masc.	✅	✅	🔒	🔒	❌	❌	❌	🔒	❌
Gestão utilizadores Desk	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌
PATCH módulos Desk	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌
Deploy API/frontend	✅	❌	❌	❌	❌	❌	❌	❌	✅	✅	❌	❌	❌
Aprovar runbook agente	✅	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	✅	✅

---

4. Matriz — Ambiente VM123 (Finance + Hosting)

Componentes: FOSSBilling · Odoo 16 · OpenPanel · SSH :2523

Função	FOSSBilling Admin	FOSSBilling Cliente	Odoo 16	OpenPanel	OpenAdmin	SSH VM123
super_admin	✅	✅	✅	✅	✅	✅
ops_lead	🔗	🔒	🔗	🔗	🔗	🔗
technician	❌	❌	❌	🔗 site cliente	❌	❌
noc	❌	❌	❌	❌	❌	❌
finance	✅	✅	✅	🔒	🔒	🔗
sales_admin	✅ pedidos+clientes+staff RO	✅	✅ Sales Manager	🔗	🔗 Admin	❌
sales_support	✅ pedidos+clientes	✅	✅ Salesman	🔗 autologin	❌	❌
marketing	🔒 produtos	✅ campanhas	❌	✅ sites	🔗	❌
seo	❌	❌	❌	✅ SEO/hosting	🔗	❌
developer	⚙️ API	❌	⚙️ API	⚙️ bridge	❌	🔗
devops	❌	❌	❌	✅	✅	✅
security_analyst	🔒 logs	❌	❌	🔒	🔒	🔗
content_editor	❌	❌	❌	✅	❌	❌
agentic_operator	❌	❌	❌	❌	❌	❌
api_service	🤖 webhook	❌	🤖	🤖 provision	❌	❌

4.1 Integração APIs VM123 — perfis de produto

Documento completo: contracts/vm123-product-roles.md

Produto	API	Auth	Mapeamento função Desk
FOSSBilling	POST /api/admin/{module}/{action}	Basic admin:API_KEY	Staff groups: ligbox-sales-admin, ligbox-sales-support, ligbox-finance-admin
Odoo 16	XML-RPC /odoo/xmlrpc/2/object	login + API key	group_sale_manager → sales_admin; group_sale_salesman → sales_support
OpenPanel	Bridge :18087 (Community) ou :2087/api (Enterprise)	Bearer JWT / bridge token	sales_support = autologin cliente; devops = OpenAdmin

Diferença Sales Admin vs Sales Support

Capacidade	sales_admin (Gerente)	sales_support (Analista)
Desk — validar billing	✅	❌
Desk — leads / funil	✅	✅
FOSS — criar/editar clientes	✅	✅
FOSS — criar pedidos / hosting	✅	✅
FOSS — faturas / preços / produtos	✅	🔒
FOSS — staff / settings	❌	❌
Odoo — CRM manager	✅	❌
Odoo — CRM user	✅	✅
OpenPanel — OpenAdmin	🔗	❌ (só autologin)
Fechar tickets comerciais	✅	✅

Provisionamento automático (Fase 3): ao aprovar cadastro Desk com função sales_*, API VM122 cria staff FOSS + user Odoo via api_service — ver fluxo no contrato.

URLs VM123

Serviço	URL pública
FOSSBilling Admin	https://financeiro.ligbox.com.br/admin
FOSSBilling Cliente	https://financeiro.ligbox.com.br/login
Odoo 16	https://financeiro.ligbox.com.br/odoo/web/login?db=ligbox
OpenPanel	https://openpanel.ligbox.com.br
OpenAdmin	https://openpanel.ligbox.com.br:2087

Integração Desk → VM123 (fase 2–3): ficha «Conta do cliente» (Spec 023) abre deep-link FOSS/Odoo; finance, sales_admin e sales_support com botões API no drawer.

---

5. Matriz — Consolas externas (deep-link a partir do Desk)

Consola	super_admin	ops_lead	technician	noc	finance	sales_admin	sales_support	marketing	seo	developer	devops	security_analyst
Cloudflare DNS	✅	✅	🔗	❌	❌	🔒	🔒	🔒	✅	❌	✅	❌
Traefik CT114	✅	🔗	❌	❌	❌	❌	❌	❌	❌	🔗	✅	❌
Proxmox host	✅	🔗	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌
pfSense API	✅	🔗	❌	❌	❌	❌	❌	❌	❌	❌	✅	🔗
Wazuh VM104	✅	✅	🔒	🔒	❌	❌	❌	❌	❌	❌	🔒	✅
GitHub itecnologys/*	✅	🔒	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌
Google Search Console	❌	❌	❌	❌	❌	❌	❌	🔗	✅	❌	❌	❌
FOSSBilling Admin	✅	🔗	❌	❌	✅	✅	🔒	🔒	❌	❌	❌	❌
Odoo ligbox	✅	🔗	❌	❌	✅	✅	🔒	❌	❌	❌	❌	❌

---

6. Agentes IA (Agentics) — responsabilidades e governança

Os 7 agentes (VISÃO_PLATAFORMA A0–A7) não são utilizadores humanos. Operam com role agent_system e token dedicado.

Agente	ID	Responsabilidade	Dados que lê	Acções que executa	Aprovação humana
Orchestrator	A0	Roteamento e síntese multi-agente	Todos os feeds	Delegar tarefas	agentic_operator / ops_lead
Node Health	A1	CPU, RAM, serviços Carbonio	VM112 metrics	Alertas, tickets	Auto para info; ops_lead para restart
Infra Mail	A2	DNS, LE, Traefik, nginx	DNS, certs, SNI	Sugerir/fix DNS	devops ou ops_lead antes de aplicar
Deliverability	A3	SPF/DKIM/DMARC	DNS mail	Relatórios	seo / technician revisão
Security Mail	A4	amavis, spam, clamav	Filas, logs mail	Quarentena sugerida	security_analyst
Wazuh SOC	A5	Correlação SIEM	VM104 Wazuh	Alertas Desk	security_analyst / noc
Support Copilot	A6	Assistência tickets	Tickets, timeline	Rascunho resposta	technician envia
Remediation	A7	Runbooks	Playbooks aprovados	Executar após OK	agentic_operator obrigatório

Quem gere agentes no Desk

Função	Ver sugestões agente	Aprovar runbook A7	Configurar prompts/modelos
super_admin	✅	✅	✅
ops_lead	✅	✅	🔒
agentic_operator	✅	✅	❌
security_analyst	✅ A4/A5	✅ scope segurança	❌
developer	⚙️	❌	✅
Demais	❌ ou 🔒 resumo	❌	❌

---

7. Cadastro e atribuição de função (fluxo)

Estende Spec 004:

1. Candidato regista-se em desk.ligbox.com.br/register.html com @ligbox.com.br
2. super_admin aprova em Mensagens e escolhe função (lista secção 1 — incl. sales_admin / sales_support)
3. Ativação 2-de-3 (e-mail, telefone, TOTP)
4. Desk aplica módulos e permissões conforme matriz desta spec
5. Contas FOSS/Odoo/OpenPanel (VM123) criadas via provisionamento Fase 3 (api_service) ou manualmente — nunca partilhar password root VM

Mapeamento função → módulos default (activação)

Função	Módulos ON por defeito
sales_admin	core, leads, funnel-timing, overview-home, billing-recurrence, tenants
sales_support	core, leads, funnel-timing, overview-home, tenants
finance	core, overview-home, billing-recurrence, events (billing)
marketing	core, leads, funnel-timing, overview-home
seo	core, funnel-timing, overview-home, leads
developer	core, events, infra (read), overview
devops	core, infra, infra2-soc, overview-home, events
security_analyst	core, infra2-soc, wazuh-soc, events
content_editor	core + acesso OpenPanel (fora Desk)
agentic_operator	core, overview, events, infra2-soc

Mapeamento função → VM123 (provisionamento)

Função	FOSS group	Odoo	OpenPanel
sales_admin	ligbox-sales-admin	Sales Manager	OpenAdmin Admin
sales_support	ligbox-sales-support	Salesman	autologin apenas
finance	ligbox-finance-admin	Account Manager	read-only

Ver contracts/vm123-product-roles.md.

---

8. Implementação técnica (fases)

Fase 1 — Documentação + enum (esta spec) ✅

• Publicar matriz; alinhar Roger
• Actualizar permissions.py com constantes ALL_FUNCTIONS

Fase 2 — RBAC Desk (VM122) ✅

• Expandir ROLES em api/app/permissions.py
• ROLE_MODULES map em registry.py (Spec 015)
• UI: labels pt-BR no cadastro (Spec 004)
• Testes: verify-rbac-matrix.sh por função

Fase 3 — Deep-links + APIs VM123 ✅ (MVP)

• Drawer «Conta do cliente» → FOSS/Odoo via /api/v1/vm123/links/client
• Endpoints /api/v1/vm123/* (contrato vm123-product-roles.md)
• Provisionamento staff FOSS + user Odoo ao activar cadastro (provision_desk_user)
• Pré-requisito Odoo: instalar apps sale + account na VM123 para grupos standard existirem

Fase 4 — Agentes

• Service account agent_system + fila aprovação agentic_operator
• Auditoria de cada acção A7

---

9. Requisitos funcionais

• FR-027-001: Sistema MUST suportar no mínimo 13 funções humanas (secção 1) incluindo sales_admin e sales_support.
• FR-027-002: Cada função MUST ter módulos Desk activos por defeito conforme secção 7.
• FR-027-003: Nenhuma função excepto super_admin e devops MUST ter SSH root às VMs por defeito.
• FR-027-004: Função noc MUST continuar a mascarar CNPJ, morada e e-mails billing (Spec 003).
• FR-027-005: Função finance MUST poder transicionar billing_state (Spec 023).
• FR-027-006: Agentes A0–A7 MUST NOT autenticar como humanos; usam agent_system.
• FR-027-007: Acções A7 (remediação) MUST exigir aprovação agentic_operator ou ops_lead.
• FR-027-008: Cadastro MUST restringir e-mail a @ligbox.com.br para funções internas.
• FR-027-009: sales_admin MUST poder validar billing_state e criar pedidos FOSS; sales_support MUST NOT validar billing nem aceder OpenAdmin.
• FR-027-010: Provisionamento VM123 MUST usar APIs em contracts/vm123-product-roles.md — sem credenciais root partilhadas.

---

10. Fora de âmbito (esta spec)

• SSO Google/Azure
• Permissões por tenant isolado (multi-empresa Ligbox)
• Cliente final (client_domain_admin) — permanece no wizard VM112
• Criação automática de contas Linux nas VMs (usar contas app)

---

11. Documentos relacionados

Spec	Relação
003	RBAC base (4 roles) — pai
004	Cadastro e atribuição de perfil
015	Registry módulos Desk
010	Assist / takeover
013	Migração e-mail
018	Serviços / clientes
023	Billing Desk
024	VM123 finance stack + APIs produto
021	Telemetria / segurança wizard

---

12. Critérios de aceite

• Roger valida matriz secções 2–6 e Sales Admin vs Support
• permissions.py inclui 13 funções + testes 403
• Cadastro Desk lista sales_admin e sales_support no approve
• Grupos FOSS ligbox-sales-admin e ligbox-sales-support criados na VM123
• sales_admin abre FOSS + Odoo a partir do Desk
• sales_support cria pedido FOSS sem OpenAdmin
• Contrato vm123-product-roles.md referenciado no deploy VM122

---

Roger — validar secção 4.1 (APIs VM123) e limites Sales Admin vs Support antes da Fase 2.