From 2d2b74fad896bed504264f1c819217635d2c2c94 Mon Sep 17 00:00:00 2001 From: Ligbox Spec Hub Date: Wed, 1 Jul 2026 15:06:19 +0000 Subject: [PATCH] =?UTF-8?q?docs(spec-043):=20mapa=20activa=C3=A7=C3=A3o=20?= =?UTF-8?q?cliente=20e=20liga=C3=A7=C3=B5es=20cruzadas?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- projects/ops-desk/VERSION | 17 + .../spec.md | 2 +- .../tasks.md | 2 +- .../PROVISIONING_CLIENT_CARD.md | 3 +- specs/024-openpanel-fossbilling/spec.md | 2 +- .../contracts/foss-bridge-api.md | 2 + .../spec.md | 2 +- .../spec.md | 2 +- .../ROLLBACK.md | 42 +++ .../contracts/activation-field-mapping.md | 335 ++++++++++++++++++ .../contracts/desk-activate-account-api.md | 107 ++++++ specs/043-desk-client-activation-sync/spec.md | 104 ++++++ .../043-desk-client-activation-sync/tasks.md | 39 ++ specs/SPEC-REGISTRY.md | 12 + 14 files changed, 665 insertions(+), 6 deletions(-) create mode 100644 projects/ops-desk/VERSION create mode 100644 specs/043-desk-client-activation-sync/ROLLBACK.md create mode 100644 specs/043-desk-client-activation-sync/contracts/activation-field-mapping.md create mode 100644 specs/043-desk-client-activation-sync/contracts/desk-activate-account-api.md create mode 100644 specs/043-desk-client-activation-sync/spec.md create mode 100644 specs/043-desk-client-activation-sync/tasks.md create mode 100644 specs/SPEC-REGISTRY.md diff --git a/projects/ops-desk/VERSION b/projects/ops-desk/VERSION new file mode 100644 index 0000000..c8b34bc --- /dev/null +++ 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 diff --git a/specs/023-billing-recurrence-desk-visibility/spec.md b/specs/023-billing-recurrence-desk-visibility/spec.md index 1b6a9b3..3f14bf2 100644 --- 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)** --- diff --git a/specs/023-billing-recurrence-desk-visibility/tasks.md b/specs/023-billing-recurrence-desk-visibility/tasks.md index 6fe09aa..fa35bfb 100644 --- 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` diff --git a/specs/024-openpanel-fossbilling/PROVISIONING_CLIENT_CARD.md b/specs/024-openpanel-fossbilling/PROVISIONING_CLIENT_CARD.md index 2c10868..215855a 100644 --- 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 diff --git a/specs/024-openpanel-fossbilling/spec.md b/specs/024-openpanel-fossbilling/spec.md index 3919a47..deec132 100644 --- 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)** --- diff --git a/specs/028-openpanel-ce-ligbox-reengineering/contracts/foss-bridge-api.md b/specs/028-openpanel-ce-ligbox-reengineering/contracts/foss-bridge-api.md index cd8dc83..b490db0 100644 --- 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) diff --git a/specs/028-openpanel-ce-ligbox-reengineering/spec.md b/specs/028-openpanel-ce-ligbox-reengineering/spec.md index 2a69236..36a1b90 100644 --- 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)** --- diff --git a/specs/035-ligbox-mail-bundles-foss-openpanel/spec.md b/specs/035-ligbox-mail-bundles-foss-openpanel/spec.md index 82b4cf1..fa54817 100644 --- 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)** --- diff --git a/specs/043-desk-client-activation-sync/ROLLBACK.md b/specs/043-desk-client-activation-sync/ROLLBACK.md new file mode 100644 index 0000000..5c55a50 --- /dev/null +++ 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.* diff --git a/specs/043-desk-client-activation-sync/contracts/activation-field-mapping.md b/specs/043-desk-client-activation-sync/contracts/activation-field-mapping.md new file mode 100644 index 0000000..a711465 --- /dev/null +++ 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": "", + "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.* diff --git 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 new file mode 100644 index 0000000..62fc640 --- /dev/null +++ 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`* diff --git a/specs/043-desk-client-activation-sync/spec.md b/specs/043-desk-client-activation-sync/spec.md new file mode 100644 index 0000000..be9321a --- /dev/null +++ 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* diff --git a/specs/043-desk-client-activation-sync/tasks.md b/specs/043-desk-client-activation-sync/tasks.md new file mode 100644 index 0000000..8e7e673 --- /dev/null +++ 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 diff --git a/specs/SPEC-REGISTRY.md b/specs/SPEC-REGISTRY.md new file mode 100644 index 0000000..95cd1da --- /dev/null +++ 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