docs(spec-043): mapa activação cliente e ligações cruzadas

Documenta Wizard→Desk→FOSS→OpenPanel→Odoo com contratos, rollback e registo SPEC-REGISTRY antes da implementação das fases de activação. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-01 15:06:19 +00:00 · 2026-07-01 15:06:19 +00:00 · 2d2b74fad8
commit 2d2b74fad8
parent aef9864034
14 changed files with 665 additions and 6 deletions
--- a/projects/ops-desk/VERSION
+++ b/projects/ops-desk/VERSION
@ -0,0 +1,17 @@
+0.14.0-pre-spec043-activation
+
+Specs:
+  043-desk-client-activation-sync — mapa Wizard→FOSS→OpenPanel→Odoo + Activar conta
+  040-desk-design-system-v013      — UserWizard, Access Control Hub
+  041-desk-operational-feed        — Central Operacional
+
+Rollback Spec 043 (antes de activação):
+  git checkout desk-v0.14.0-pre-spec043-activation -- projects/ops-desk/
+
+Rollback UI aprovado v0.13.1:
+  frontend/staging-snapshot/v0.13.1-ac-hub-ui-aprovado-20260625/
+
+Rollback DS v0.13.0:
+  frontend/staging-snapshot/v0.12.2-pre-ds-20260625/
+
+Cache produção: ?v=20260701spec043
--- a/specs/023-billing-recurrence-desk-visibility/spec.md
+++ b/specs/023-billing-recurrence-desk-visibility/spec.md
@ -7,7 +7,7 @@
 **Sistemas:** Wizard VM112 · Desk VM122 · Motor de cobrança (fase 2)  
 **Módulo Desk:** `billing-recurrence` (novo — Spec 015)  
 **Depende de:** Spec 012 (tickets onboarding), Spec 018 (Serviços / clientes), Spec 021 (webhooks)  
-**Relacionado:** Card wizard «Dados da empresa e cobrança» (imagem Roger, 2026-06-17)
+**Relacionado:** Card wizard «Dados da empresa e cobrança» (imagem Roger, 2026-06-17) · **[Spec 043 — mapa campos FOSS/OP/Odoo](../043-desk-client-activation-sync/contracts/activation-field-mapping.md)**

 ---

--- a/specs/023-billing-recurrence-desk-visibility/tasks.md
+++ b/specs/023-billing-recurrence-desk-visibility/tasks.md
@ -20,7 +20,7 @@
 - [x] Deploy api + frontend VM122

 ## Fase 2 — Odoo cobrança
- [ ] Cliente Odoo `res.partner` a partir de `company_profile`
+- [ ] Cliente Odoo `res.partner` a partir de `company_profile` — ver [Spec 043 §6](../043-desk-client-activation-sync/contracts/activation-field-mapping.md)
 - [ ] Produto/plano assinatura e-mail tenant
 - [ ] Integração ASAAS/Iugu
 - [ ] Webhook pagamento → `billing_state`
--- a/specs/024-openpanel-fossbilling/PROVISIONING_CLIENT_CARD.md
+++ b/specs/024-openpanel-fossbilling/PROVISIONING_CLIENT_CARD.md
@ -1,6 +1,7 @@
 # Spec 024 — Card cliente → FOSS → OpenPanel (provisionamento)

-**Roger · 2026-06-17**
+**Roger · 2026-06-17**  
+**Mapa completo (mail + Odoo):** [Spec 043 activation-field-mapping.md](../043-desk-client-activation-sync/contracts/activation-field-mapping.md)

 ## O teu raciocínio está correto

--- a/specs/024-openpanel-fossbilling/spec.md
+++ b/specs/024-openpanel-fossbilling/spec.md
@ -5,7 +5,7 @@
 **Status:** ✅ Concluída (v1 piloto) — 2026-06-17  
 **Prioridade:** P1  
 **Decisão:** **FOSSBilling** + **OpenPanel** + **Odoo V16** · gateway pagamento fase futura  
-**Relacionado:** Spec 023 (Desk 💳), Spec 018 (Serviços)
+**Relacionado:** Spec 023 (Desk 💳), Spec 018 (Serviços) · **[Spec 043 — mapa activação cliente](../043-desk-client-activation-sync/contracts/activation-field-mapping.md)**

 ---

--- a/specs/028-openpanel-ce-ligbox-reengineering/contracts/foss-bridge-api.md
+++ b/specs/028-openpanel-ce-ligbox-reengineering/contracts/foss-bridge-api.md
@ -1,5 +1,7 @@
 # Contrato — Bridge FOSS ↔ OpenPanel (Ligbox v2)

+**Mapa campos completo:** [Spec 043 activation-field-mapping.md](../../043-desk-client-activation-sync/contracts/activation-field-mapping.md)
+
 **Base URL:** `http://10.10.10.123:18087`  
 **Auth:** Bearer token (obtido via POST `/api` com credenciais OpenAdmin)

--- a/specs/028-openpanel-ce-ligbox-reengineering/spec.md
+++ b/specs/028-openpanel-ce-ligbox-reengineering/spec.md
@ -5,7 +5,7 @@
 **Status:** ✅ Implementado (VM123) — E2E FOSS validado  
 **Prioridade:** P0 (hosting comercial sem licença Enterprise paga)  
 **VM alvo:** **VM123** (`10.10.10.123`)  
-**Relacionado:** Spec **024** (FOSS+OpenPanel), Spec **027** (RBAC Desk), Spec **018** (Serviços)
+**Relacionado:** Spec **024** (FOSS+OpenPanel), Spec **027** (RBAC Desk), Spec **018** (Serviços) · **[Spec 043 — mapa activação](../043-desk-client-activation-sync/contracts/activation-field-mapping.md)**

 ---

--- a/specs/035-ligbox-mail-bundles-foss-openpanel/spec.md
+++ b/specs/035-ligbox-mail-bundles-foss-openpanel/spec.md
@ -4,7 +4,7 @@
 **Solicitado por:** Roger  
 **Status:** 📋 Draft — aguarda aprovação comercial + Fase 0  
 **Prioridade:** P1  
-**Relacionado:** Spec **024** (FOSS/OpenPanel) · **028** (bridge CE) · **034** (Nextcloud) · **027** (RBAC) · **010** (Domain Admin) · **018** (catálogo serviços) · **037** ([dns-viewer.md](../037-dns-multi-cloudflare-orchestration/dns-viewer.md))
+**Relacionado:** Spec **024** (FOSS/OpenPanel) · **028** (bridge CE) · **034** (Nextcloud) · **027** (RBAC) · **010** (Domain Admin) · **018** (catálogo serviços) · **037** ([dns-viewer.md](../037-dns-multi-cloudflare-orchestration/dns-viewer.md)) · **[043 mapa activação](../043-desk-client-activation-sync/contracts/activation-field-mapping.md)**

 ---

--- a/specs/043-desk-client-activation-sync/ROLLBACK.md
+++ b/specs/043-desk-client-activation-sync/ROLLBACK.md
@ -0,0 +1,42 @@
+# Rollback — Spec 043 Activar conta
+
+**Roger · 2026-07-01**
+
+## Tags Git
+
+| Tag | Conteúdo |
+|-----|----------|
+| `desk-v0.14.0-pre-spec043-activation` | Baseline **antes** de implementar Fases 1–6 |
+| `desk-v0.14.1-spec043-fase1` | Após Fase 1 (preview UI + API) |
+
+## Reverter código Desk (VM122)
+
+```bash
+cd /opt/ligbox-spec-hub/repos/ligbox-ops-platform
+
+# Voltar ao estado pré-Spec 043 (só billing + mapper)
+git checkout desk-v0.14.0-pre-spec043-activation -- \
+  projects/ops-desk/api/app/billing_routes.py \
+  projects/ops-desk/api/app/billing_store.py \
+  projects/ops-desk/api/app/activation_mapper.py \
+  projects/ops-desk/frontend/assets/billing-ui.js \
+  projects/ops-desk/frontend/assets/auth.js \
+  projects/ops-desk/VERSION
+
+# Reiniciar API Desk
+systemctl restart ligbox-desk-api   # ou serviço equivalente na VM122
+```
+
+## Reverter só Fase 1 (manter docs Spec 043)
+
+```bash
+git checkout desk-v0.14.0-pre-spec043-activation -- projects/ops-desk/
+```
+
+## Documentação
+
+A pasta `specs/043-desk-client-activation-sync/` é segura manter — não afecta produção.
+
+---
+
+*Actualizar esta tabela quando cada fase for concluída e taggeada.*
--- a/specs/043-desk-client-activation-sync/contracts/activation-field-mapping.md
+++ b/specs/043-desk-client-activation-sync/contracts/activation-field-mapping.md
@ -0,0 +1,335 @@
+# Contrato — Mapeamento de campos: Ativação cliente (Wizard → Desk → FOSS → OpenPanel → Odoo)
+
+**Spec:** [043](../spec.md)  
+**Versão:** 1.0 · 2026-07-01 · Roger  
+**Status:** Fonte única de verdade para sincronização de painéis  
+
+---
+
+## 1. Visão geral do fluxo
+
+| Fase | Actor | Evento / acção | Persistência |
+|------|-------|----------------|--------------|
+| A | Cliente VM112 | Preenche card empresa + confirma | Sessão wizard |
+| B | Wizard VM112 | Emite `company.validated` | — |
+| C | Desk VM122 | Upsert `billing_accounts` | SQLite VM122 |
+| D | Staff Desk | Clica **Activar conta** | Audit log |
+| E | Desk → FOSS | `client/create` + `order/create` + activate | FOSS DB |
+| F | FOSS → OpenPanel | Módulo OpenPanel ou bridge `POST /api/users` | OpenPanel |
+| G | Desk → Odoo | `res.partner` create/update | Odoo DB `ligbox` |
+| H | Desk → Wizard | `POST /api/internal/provision/mail-bundle` | Carbonio VM112 |
+
+**Specs de origem:** [023](../../023-billing-recurrence-desk-visibility/spec.md) · [024 PROVISIONING_CLIENT_CARD](../../024-openpanel-fossbilling/PROVISIONING_CLIENT_CARD.md) · [035](../../035-ligbox-mail-bundles-foss-openpanel/spec.md) · [028 bridge](../../028-openpanel-ce-ligbox-reengineering/contracts/foss-bridge-api.md)
+
+---
+
+## 2. Card wizard — «Dados da empresa e cobrança»
+
+**Onde:** VM112 wizard, gate `company_gate` (após conta/domínio).  
+**Spec:** [023 § Gatilho](../../023-billing-recurrence-desk-visibility/spec.md)
+
+### 2.1 Campos do formulário (UI wizard)
+
+| ID campo wizard | Label UI (referência) | Tipo | Obrigatório | Notas |
+|-----------------|----------------------|------|-------------|-------|
+| `trade_name` | Nome fantasia | text | sim | Nome comercial |
+| `legal_name` | Razão social | text | sim | NF / contrato |
+| `tax_id_type` | Tipo documento | enum | sim | `cnpj` \| `cpf` |
+| `tax_id` | CNPJ / CPF | text | sim | Só dígitos ou formatado |
+| `email_billing` | E-mail de cobrança | email | sim | Pode ≠ admin@dom |
+| `payment_method` | Forma de pagamento | select | não | Fase 2 (boleto/PIX) |
+| `address.country` | País | text | sim | Default `BR` |
+| `address.city` | Cidade | text | sim | |
+| `address.postal_code` | CEP | text | sim | |
+| `address.street` | Endereço | text | não | Se existir no wizard |
+| `address.state` | UF | text | não | |
+| `phone_landline` | Telefone fixo | tel | não | Mascarado NOC no Desk |
+| `phone_mobile` | Celular | tel | não | |
+| `contact_phone` | Telefone contacto | tel | não | Alias legacy |
+| `email_legal` | E-mail jurídico | email | não | Se distinto do billing |
+| `confirm_billing` | Aceito política de cobrança | bool | sim | Gate submit |
+| `confirm_accurate` | Dados correctos | bool | sim | Gate submit |
+
+### 2.2 Campos do gerente / responsável (conta admin)
+
+**Specs:** [035 §5.1](../../035-ligbox-mail-bundles-foss-openpanel/spec.md) · wizard `account.create`
+
+| ID campo | Origem | Exemplo | Notas |
+|----------|--------|---------|-------|
+| `domain` | Validação domínio | `ligbox.com.br` | Chave única `billing_accounts` |
+| `manager_email` | Conta admin criada | `admin@ligbox.com.br` | = email Carbonio gerente |
+| `manager_name` | Card responsável / display name | João Silva | Nome pessoa responsável |
+| `admin_password` | Wizard (não replicar em logs) | — | Só FOSS/OP se gerada para hub |
+
+### 2.3 Payload webhook `company.validated`
+
+```json
+{
+  "event": "company.validated",
+  "domain": "empresa.com.br",
+  "session_id": "<uuid>",
+  "data": {
+    "billing_state": "awaiting_billing_validation",
+    "company_profile": {
+      "trade_name": "Empresa LTDA",
+      "legal_name": "Empresa Serviços LTDA",
+      "tax_id_type": "cnpj",
+      "tax_id": "00000000000191",
+      "email_billing": "financeiro@empresa.com.br",
+      "payment_method": "",
+      "confirm_billing": true,
+      "confirm_accurate": true,
+      "address": {
+        "country": "BR",
+        "city": "São Paulo",
+        "postal_code": "01310-100",
+        "street": "",
+        "state": "SP"
+      },
+      "manager_name": "João Silva",
+      "manager_email": "admin@empresa.com.br"
+    }
+  }
+}
+```
+
+> `manager_name` / `manager_email` podem vir no `company_profile` ou no nível `data` — Desk deve normalizar para `billing_accounts` + provisionamento.
+
+---
+
+## 3. Desk VM122 — `billing_accounts`
+
+**Spec:** [023 § Modelo de dados](../../023-billing-recurrence-desk-visibility/spec.md)  
+**Código:** `billing_store.upsert_from_company_validated()`
+
+| Coluna SQLite | Origem | Descrição |
+|---------------|--------|-----------|
+| `domain` | webhook | PK lógica |
+| `session_id` | webhook | Correlação funil |
+| `ticket_id` | handler | Ticket `[billing-validation]` |
+| `tax_id` | `company_profile.tax_id` | |
+| `legal_name` | `company_profile.legal_name` | |
+| `trade_name` | `company_profile.trade_name` | |
+| `email_billing` | `company_profile.email_billing` | |
+| `company_profile_json` | JSON completo | Snapshot imutável + extras |
+| `billing_state` | `data.billing_state` | Ver tabela §3.1 |
+| `recurrence_active` | 0 até pagamento | |
+| `external_customer_id` | pós FOSS | FOSS `client.id` |
+| `external_subscription_id` | pós Odoo/FOSS | Assinatura |
+| `plan_code` | staff / produto | ex. `ligbox-mail-business` |
+| `activated_at` | pós «Activar conta» | ISO8601 |
+| `activated_by` | username staff | Audit |
+
+### 3.1 Estados `billing_state`
+
+| Estado | Significado | Próximo passo |
+|--------|-------------|----------------|
+| `policy_pending` | Card visto, não confirmado | Aguardar cliente |
+| `awaiting_billing_validation` | `company.validated` | Staff revisa |
+| `provisioning` | Activar conta em curso | FOSS/OP/Odoo |
+| `billing_active` | Recorrência activa | Monitorizar |
+| `billing_paused` | Suspenso | — |
+| `billing_cancelled` | Cancelado | Histórico |
+
+---
+
+## 4. FOSSBilling (VM123) — primeiro destino API
+
+**Spec:** [024](../../024-openpanel-fossbilling/spec.md) · [035 foss-products](../../035-ligbox-mail-bundles-foss-openpanel/foss-products.md)  
+**API base:** `https://financeiro.ligbox.com.br/api/admin/`  
+**Código Desk:** `vm123/foss_client.py` (staff hoje; **client create — a implementar**)
+
+### 4.1 Cliente FOSS (`client/create`)
+
+| Campo FOSS API | Origem Desk / wizard | Transformação |
+|----------------|----------------------|---------------|
+| `email` | `manager_email` ou `email_billing` | lower-case; preferir `manager_email` para login cliente |
+| `first_name` | `manager_name` (primeiro token) | split nome |
+| `last_name` | `manager_name` (resto) | opcional |
+| `company` | `legal_name` ou `trade_name` | razão social |
+| `company_vat` | `tax_id` | CNPJ/CPF |
+| `phone` | `phone_mobile` \|\| `contact_phone` | |
+| `address_1` | `address.street` | |
+| `city` | `address.city` | |
+| `state` | `address.state` | |
+| `postcode` | `address.postal_code` | |
+| `country` | `address.country` | `BR` |
+| `currency` | fixo | `BRL` |
+| `status` | fixo | `active` |
+| `custom_*` | `domain` | custom field `ligbox_domain` (configurar no FOSS) |
+
+**Guardar em Desk:** `billing_accounts.external_customer_id` = `client.id`
+
+### 4.2 Pedido FOSS (`order/create` + activate)
+
+| Campo FOSS | Origem | Valores mail bundle |
+|------------|--------|---------------------|
+| `client_id` | passo anterior | |
+| `product_id` / `slug` | `plan_code` | `ligbox-mail-starter` \| `business` \| `enterprise` \| `custom` |
+| `period` | comercial | `1M` mensal |
+| `domain` | `domain` | custom field pedido |
+| `manager_email` | custom field | [035](../../035-ligbox-mail-bundles-foss-openpanel/spec.md) |
+| `manager_name` | custom field | |
+| `config[seats]` | bundle custom | 10–50 |
+| `config[mail_gb]` | bundle custom | |
+| `config[files_gb]` | bundle custom | |
+
+**Activar hosting:** FOSS chama módulo OpenPanel → bridge (passo 5).
+
+---
+
+## 5. OpenPanel (VM123) — tipo de contrato / hosting
+
+**Spec:** [028](../../028-openpanel-ce-ligbox-reengineering/spec.md) · [bridge API](../../028-openpanel-ce-ligbox-reengineering/contracts/foss-bridge-api.md)  
+**Trigger:** FOSS order paid/activated **ou** Desk directo (fallback)
+
+### 5.1 Mapeamento bridge `POST /api/users`
+
+| Campo bridge | Origem | Regra |
+|--------------|--------|-------|
+| `username` | derivado de `domain` | 7 chars + dígito ([024 card](../../024-openpanel-fossbilling/PROVISIONING_CLIENT_CARD.md)) |
+| `password` | gerado ou `panel_password` | entregar ao gerente |
+| `email` | `manager_email` | |
+| `plan_name` | `plan_code` | Ver tabela §5.2 |
+| `domain` | `domain` | domínio cliente |
+
+### 5.2 Planos OpenPanel ↔ produtos FOSS
+
+| `plan_name` OpenPanel | Produto FOSS | Serviço |
+|-----------------------|--------------|---------|
+| `ligbox-mail-starter` | `ligbox-mail-starter` | Email bundle 10 seats |
+| `ligbox-mail-business` | `ligbox-mail-business` | 25 seats |
+| `ligbox-mail-enterprise` | `ligbox-mail-enterprise` | 50 seats |
+| `ligbox-mail-custom` | `ligbox-mail-custom` | Config options |
+| `ligbox-site-cms` | site CMS | [024](../../024-openpanel-fossbilling/PROVISIONING_CLIENT_CARD.md) |
+
+### 5.3 Metadata JSON no user hub (mail)
+
+**Spec:** [035 §6.2](../../035-ligbox-mail-bundles-foss-openpanel/spec.md)
+
+```json
+{
+  "bundle_type": "ligbox_mail",
+  "max_seats": 25,
+  "mail_gb_per_seat": 30,
+  "files_gb_per_seat": 200,
+  "easydmarc": true,
+  "wizard_domain": "empresa.com.br",
+  "manager_name": "João Silva",
+  "manager_email": "admin@empresa.com.br"
+}
+```
+
+**Guardar em Desk:** `company_profile_json.openpanel_username` + `openpanel_domain` após resposta bridge.
+
+---
+
+## 6. Odoo 16 (VM123) — empresa / financeiro
+
+**Spec:** [023 § Motor cobrança Fase 2](../../023-billing-recurrence-desk-visibility/spec.md)  
+**API:** XML-RPC `res.partner`  
+**Código Desk:** `vm123/odoo_client.py` (**create partner cliente — a implementar**)
+
+### 6.1 `res.partner` (empresa cliente)
+
+| Campo Odoo | Origem wizard / Desk | Notas |
+|------------|----------------------|-------|
+| `name` | `legal_name` | Razão social |
+| `display_name` | `trade_name` | Se suportado |
+| `vat` | `tax_id` | CNPJ formatado BR |
+| `email` | `email_billing` | Contacto financeiro |
+| `phone` | `phone_mobile` | |
+| `street` | `address.street` | |
+| `city` | `address.city` | |
+| `zip` | `address.postal_code` | |
+| `country_id` | `address.country` | resolver `res.country` BR |
+| `company_type` | fixo | `company` |
+| `customer_rank` | fixo | `1` |
+| `ref` | `domain` | referência interna Ligbox |
+| `comment` | JSON curto | `manager_email`, `foss_client_id`, `session_id` |
+
+**Guardar em Desk:** `external_subscription_id` ou campo dedicado `odoo_partner_id` (adicionar coluna fase 2).
+
+### 6.2 Fase 2 — assinatura / vendas
+
+| Odoo model | Origem | Spec |
+|------------|--------|------|
+| `sale.subscription` | `plan_code` + preço FOSS | 023 |
+| `account.move` | pagamentos ASAAS/Iugu | 023 fase 2 |
+
+---
+
+## 7. Wizard VM112 — provisionamento mail (pós-activação)
+
+**Spec:** [035 §5.2 webhook](../../035-ligbox-mail-bundles-foss-openpanel/spec.md)
+
+```
+POST https://desk.ligbox.com.br/api/v1/billing/webhook/foss/order-activated
+  → Desk orquestra
+POST http://10.10.10.112/api/internal/provision/mail-bundle
+```
+
+| Campo mail-bundle | Origem |
+|-------------------|--------|
+| `domain` | `domain` |
+| `admin_email` | `manager_email` |
+| `admin_name` | `manager_name` |
+| `seats` | `config.seats` |
+| `mail_gb_per_seat` | `config.mail_gb` |
+| `files_gb_per_seat` | `config.files_gb` |
+| `foss_order_id` | FOSS order |
+
+---
+
+## 8. Matriz resumo — um olhar
+
+| Campo negócio | Wizard | Desk DB | FOSS client | FOSS order | OpenPanel | Odoo partner |
+|---------------|:------:|:-------:|:-----------:|:----------:|:---------:|:------------:|
+| Domínio | ✅ | ✅ | custom | custom | ✅ domain | ref |
+| Razão social | ✅ | ✅ | company | — | — | name |
+| Nome fantasia | ✅ | ✅ | — | — | — | display |
+| CNPJ/CPF | ✅ | ✅ | company_vat | — | — | vat |
+| Email cobrança | ✅ | ✅ | alt email | — | — | email |
+| Email gerente | ✅ | profile | email | custom | email | comment |
+| Nome responsável | ✅ | profile | first/last | custom | metadata | — |
+| Plano / bundle | — | plan_code | — | product | plan_name | subscription* |
+| Morada | ✅ | JSON | address_* | — | — | street/city/zip |
+| Telefone | ✅ | JSON | phone | — | — | phone |
+
+\* Fase 2 Odoo
+
+---
+
+## 9. RBAC — quem activa
+
+**Specs:** [027](../../027-desk-rbac-function-matrix/spec.md) · [039](../../039-ligbox-ops-authorization-catalog/spec.md)
+
+| Acção | Funções |
+|-------|---------|
+| Ver `company_profile` completo | super_admin, ops_lead, finance, sales_admin |
+| **Activar conta** (disparar FOSS+OP+Odoo) | super_admin, ops_lead, finance |
+| Ver mascarado (NOC) | noc — CNPJ/email mascarados |
+
+---
+
+## 10. Idempotência e erros
+
+| Cenário | Comportamento |
+|---------|---------------|
+| FOSS client já existe (email) | Reutilizar `client.id`, não duplicar |
+| OpenPanel user exists | Erro controlado; staff resolve manual |
+| Odoo partner exists | `write` update em vez de `create` |
+| Falha parcial | `billing_state=provisioning` + log steps em `provision_json` |
+| Retry staff | Seguro se ids externos já gravados |
+
+---
+
+## 11. Histórico de versões
+
+| Versão | Data | Autor | Alteração |
+|--------|------|-------|-----------|
+| 1.0 | 2026-07-01 | Roger / Cursor | Documento inicial Spec 043 |
+
+---
+
+*Manter sincronizado com alterações em VM112 wizard, FOSS custom fields e Odoo localização BR.*
--- a/specs/043-desk-client-activation-sync/contracts/desk-activate-account-api.md
+++ b/specs/043-desk-client-activation-sync/contracts/desk-activate-account-api.md
@ -0,0 +1,107 @@
+# Contrato — API Desk «Activar conta» (planeada)
+
+**Spec:** [043](../spec.md) · depende de [activation-field-mapping.md](./activation-field-mapping.md)
+
+**Status:** 📋 Planeada — não implementada  
+**Base URL:** `https://desk.ligbox.com.br/api/v1`
+
+---
+
+## POST `/billing/accounts/{id}/activate`
+
+Dispara sequência FOSS → OpenPanel → Odoo → (opcional) wizard mail-bundle.
+
+### Autenticação
+
+Bearer session Desk + RBAC: `finance` \| `ops_lead` \| `super_admin` ([039](../../039-ligbox-ops-authorization-catalog/spec.md))
+
+### Request body
+
+```json
+{
+  "plan_code": "ligbox-mail-business",
+  "config": {
+    "seats": 25,
+    "mail_gb": 30,
+    "files_gb": 200
+  },
+  "provision_mail": true,
+  "notes": "Validado por Roger — contrato verbal OK"
+}
+```
+
+| Campo | Obrigatório | Descrição |
+|-------|-------------|-----------|
+| `plan_code` | sim | Slug produto FOSS / `plan_name` OpenPanel |
+| `config` | se `ligbox-mail-custom` | seats, mail_gb, files_gb |
+| `provision_mail` | não (default true) | Chamar wizard mail-bundle após FOSS |
+| `notes` | não | Audit log |
+
+### Response 200
+
+```json
+{
+  "ok": true,
+  "billing_account_id": 42,
+  "domain": "empresa.com.br",
+  "billing_state": "provisioning",
+  "steps": {
+    "foss": { "client_id": 101, "order_id": 55, "created": true },
+    "openpanel": { "username": "empresa1x", "domain": "empresa.com.br", "success": true },
+    "odoo": { "partner_id": 88, "created": true },
+    "wizard": { "provisioned": true, "mail_host": "mail.empresa.com.br" }
+  },
+  "activated_at": "2026-07-01T12:00:00Z",
+  "activated_by": "roger"
+}
+```
+
+### Response 207 (parcial)
+
+```json
+{
+  "ok": false,
+  "billing_state": "provisioning",
+  "steps": {
+    "foss": { "client_id": 101, "order_id": 55 },
+    "openpanel": { "error": "user already exists" },
+    "odoo": { "partner_id": 88 }
+  },
+  "message": "OpenPanel falhou — FOSS e Odoo OK"
+}
+```
+
+### Erros
+
+| HTTP | Condição |
+|------|----------|
+| 400 | `plan_code` inválido ou `billing_state` não permite activação |
+| 403 | RBAC insuficiente |
+| 404 | `billing_account` não existe |
+| 409 | Já `billing_active` |
+| 502 | FOSS/Odoo indisponível |
+
+---
+
+## GET `/billing/accounts/{id}/activation-preview`
+
+Devolve payload **read-only** com mapeamento que será enviado a FOSS/OP/Odoo (para UI staff antes de confirmar).
+
+### Response 200
+
+```json
+{
+  "domain": "empresa.com.br",
+  "company_profile": { "...": "..." },
+  "mapped": {
+    "foss_client": { "email": "admin@empresa.com.br", "company": "...", "company_vat": "..." },
+    "openpanel": { "plan_name": "ligbox-mail-business", "domain": "empresa.com.br" },
+    "odoo_partner": { "name": "...", "vat": "...", "email": "..." }
+  },
+  "billing_state": "awaiting_billing_validation"
+}
+```
+
+---
+
+*Implementar em `projects/ops-desk/api/app/billing_routes.py` + `vm123/client_provision.py`*
--- a/specs/043-desk-client-activation-sync/spec.md
+++ b/specs/043-desk-client-activation-sync/spec.md
@ -0,0 +1,104 @@
+# Spec 043 — Sincronização Cliente: Wizard → Desk → FOSS → OpenPanel → Odoo
+
+**Criado:** 2026-07-01  
+**Solicitado por:** Roger  
+**Status:** 🚧 **Fase 1 em curso** — preview UI + API; Fases 2–6 pendentes  
+**Prioridade:** P0 (orquestração comercial Ligbox)  
+**Sistemas:** VM112 Wizard · VM122 Desk · VM123 FOSS/Odoo/OpenPanel  
+
+---
+
+## Resumo
+
+Esta spec **unifica e documenta** o mapeamento de dados desde o card **«Dados da empresa e cobrança»** no wizard (VM112) até aos três painéis financeiros/hosting na VM123:
+
+1. **FOSSBilling** — cliente + pedido + activação hosting (primeiro destino API)
+2. **OpenPanel** — tipo de contrato / plano / domínio hub (via bridge ou módulo FOSS)
+3. **Odoo 16** — empresa (`res.partner`) e fluxo financeiro
+
+O Desk (VM122) é o **orquestrador**: recebe `company.validated`, persiste `billing_accounts`, e expõe acção staff **«Activar conta»** que dispara a sequência documentada.
+
+**Documento mestre de campos:** [contracts/activation-field-mapping.md](./contracts/activation-field-mapping.md)
+
+---
+
+## Specs relacionadas (leitura obrigatória)
+
+| Spec | Relação |
+|------|---------|
+| [023](../023-billing-recurrence-desk-visibility/spec.md) | Card empresa, `company.validated`, `billing_accounts`, estados |
+| [024](../024-openpanel-fossbilling/spec.md) | Stack VM123, FOSS+Odoo+OpenPanel |
+| [024 PROVISIONING_CLIENT_CARD](../024-openpanel-fossbilling/PROVISIONING_CLIENT_CARD.md) | Campos card → FOSS → OP (site CMS) |
+| [028](../028-openpanel-ce-ligbox-reengineering/spec.md) | Bridge `:18087`, re-engenharia CE |
+| [028 foss-bridge-api](../028-openpanel-ce-ligbox-reengineering/contracts/foss-bridge-api.md) | Contrato API bridge |
+| [035](../035-ligbox-mail-bundles-foss-openpanel/spec.md) | Bundles mail, `manager_name`, webhook `order-activated` |
+| [001](../001-webhook-vm112-integration/spec.md) | Webhooks VM112 → Desk |
+| [004](../004-onboard-funnel-events/spec.md) | Funil onboarding |
+| [027](../027-desk-rbac-function-matrix/spec.md) | Quem pode activar conta |
+| [039](../039-ligbox-ops-authorization-catalog/spec.md) | `vm123_foss.*`, `vm123_openpanel.*`, Odoo |
+| [040](../040-desk-design-system-v013/spec.md) | UI staff Access Control Hub |
+
+---
+
+## Arquitectura
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│ VM112 — Wizard / Domain Admin (onboard.ligbox.com.br)                    │
+│  Card «Dados da empresa e cobrança» + conta admin@{domínio}              │
+└───────────────────────────────┬─────────────────────────────────────────┘
+                                │ webhook company.validated (+ account.created)
+                                ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ VM122 — Ligbox Ops Desk                                                  │
+│  billing_accounts · ticket [billing-validation] · UI «Activar conta»     │
+└───────────────────────────────┬─────────────────────────────────────────┘
+                                │ sequência staff (Spec 043)
+          ┌─────────────────────┼─────────────────────┐
+          ▼                     ▼                     ▼
+   FOSSBilling :8092      Bridge :18087          Odoo :8069
+   (cliente+order)        (OpenPanel user)       (res.partner)
+          │                     │                     │
+          └─────────────────────┴─────────────────────┘
+                                │
+                                ▼
+                    Wizard provision mail-bundle (VM112 Carbonio)
+```
+
+---
+
+## Entregáveis desta spec
+
+| Artefacto | Path |
+|-----------|------|
+| **Mapa de campos** | [contracts/activation-field-mapping.md](./contracts/activation-field-mapping.md) |
+| **API Desk (planeada)** | [contracts/desk-activate-account-api.md](./contracts/desk-activate-account-api.md) |
+| **Tasks implementação** | [tasks.md](./tasks.md) |
+
+---
+
+## Código de referência (VM122)
+
+| Módulo | Path |
+|--------|------|
+| Billing store | `projects/ops-desk/api/app/billing_store.py` ou `legacy-app/billing_store.py` |
+| Webhook ingress | `projects/ops-desk/api/app/main.py` (`company.validated`) |
+| FOSS client | `projects/ops-desk/api/app/vm123/foss_client.py` |
+| Odoo client | `projects/ops-desk/api/app/vm123/odoo_client.py` |
+| OpenPanel client | `projects/ops-desk/api/app/vm123/openpanel_client.py` |
+| UI ficha cliente | `projects/ops-desk/frontend/assets/billing-ui.js` |
+
+---
+
+## Regras de negócio (Roger)
+
+1. Wizard **não cobra** no card empresa — só recolhe e valida ([023](../023-billing-recurrence-desk-visibility/spec.md)).
+2. **FOSS recebe primeiro** os dados do cliente (create client + order).
+3. **OpenPanel** reflecte o **tipo de serviço** (`plan_name` + metadata mail).
+4. **Odoo** recebe a **empresa** para gestão financeira (`res.partner`).
+5. Um **gerente** por domínio: `admin@{domínio}` + `manager_name` / `manager_email`.
+6. Staff activa após revisão OPS — não automático sem RBAC ([027](../027-desk-rbac-function-matrix/spec.md)).
+
+---
+
+*Roger · Spec 043 · documentação viva — actualizar quando campos wizard ou APIs VM123 mudarem*
--- a/specs/043-desk-client-activation-sync/tasks.md
+++ b/specs/043-desk-client-activation-sync/tasks.md
@ -0,0 +1,39 @@
+# Spec 043 — Tasks
+
+## Documentação
+- [x] Spec índice `spec.md`
+- [x] Contrato `activation-field-mapping.md`
+- [x] Contrato API `desk-activate-account-api.md`
+- [x] Ligações cruzadas specs 023/024/028/035
+- [x] Registo em `SPEC-REGISTRY.md`
+
+## Fase 1 — Desk preview UI
+- [x] `GET /billing/accounts/{id}/activation-preview`
+- [x] Botão **Activar conta** em `billing-ui.js` (só roles autorizados)
+- [x] Modal confirmação com 3 colunas FOSS / OpenPanel / Odoo
+- [ ] Deploy VM122 + validação Roger
+
+## Fase 2 — FOSS client + order
+- [ ] `foss_client.create_client()` conforme mapa §4
+- [ ] `foss_client.create_order()` + activate hosting
+- [ ] Custom fields FOSS: `ligbox_domain`, `manager_name`, `manager_email`
+- [ ] Persistir `external_customer_id`
+
+## Fase 3 — OpenPanel
+- [ ] Confirmar fluxo via módulo FOSS vs bridge directo
+- [ ] Metadata JSON mail no user hub
+- [ ] Persistir `openpanel_username` em `company_profile_json`
+
+## Fase 4 — Odoo empresa
+- [ ] `odoo_client.upsert_customer_partner()` conforme mapa §6
+- [ ] Coluna `odoo_partner_id` em `billing_accounts`
+- [ ] Deep-link Odoo na ficha cliente
+
+## Fase 5 — Wizard mail-bundle
+- [ ] `POST /billing/accounts/{id}/activate` com `provision_mail`
+- [ ] Webhook `order-activated` alinhado com [035](../035-ligbox-mail-bundles-foss-openpanel/spec.md)
+
+## Fase 6 — Testes E2E
+- [ ] Domínio teste: wizard → company.validated → activate → FOSS+OP+Odoo
+- [ ] Idempotência retry
+- [ ] RBAC NOC mascarado
--- a/specs/SPEC-REGISTRY.md
+++ b/specs/SPEC-REGISTRY.md
@ -0,0 +1,12 @@
+# Registo de Specs — Ligbox Ops Platform
+
+| Spec | Pasta | Escopo | Versão Desk |
+|------|-------|--------|-------------|
+| 027 | `027-desk-rbac-function-matrix/` | Matriz RBAC | — |
+| 039 | `039-ligbox-ops-authorization-catalog/` | Catálogo acções | — |
+| **040** | **`040-desk-design-system-v013/`** | **UserWizard + Access Control Hub + Governance API** | **0.13.1-ac-hub-ui-aprovado-roger** |
+| **041** | **`041-desk-operational-feed/`** | **Central Operacional (ex-Mensagens) + ops-inbox API** | **0.13.0** |
+| **042** | **`042-ligbox-nettools-portal/`** | **NetTools — 23 ferramentas OSS em nettools.ligbox.com.br** | — |
+| **043** | **`043-desk-client-activation-sync/`** | **Mapa campos Wizard→Desk→FOSS→OpenPanel→Odoo + API Activar conta** | — |
+
+Atualizado: 2026-07-01 · Roger · Spec 043 mapeamento activação cliente