122 lines
6.3 KiB
Markdown
122 lines
6.3 KiB
Markdown
# Feature Specification: Pré-preenchimento Self-Service → Wizard (016)
|
|
|
|
**Criado:** 2026-06-16
|
|
**Solicitado por:** Roger
|
|
**Status:** Implementação
|
|
**Prioridade:** P0 (regressão UX onboarding)
|
|
**Sistema:** Portal VM112 (`ibytera-mail-portal`) — wizard `/onboard`
|
|
**Relacionado:** Spec 012 (ticket no `onboarding.started`), chat bruto `CHAT_BRUTO_ONBOARD_INFRA_SUPORTE_20260603`
|
|
|
|
---
|
|
|
|
## Resumo
|
|
|
|
Quando o utilizador preenche o **card Self-Service** na landing (hero) ou chega via **«Criar Meu Servidor Agora»**, os dados declarados devem **propagar automaticamente** para o wizard de onboarding, em especial no **passo «Conta admin»** (criação da conta do administrador no Carbonio).
|
|
|
|
**Regra de ouro:** dados do Self-Service **têm prioridade** sobre estado antigo do wizard guardado em `sessionStorage` (domínio/localPart de sessão anterior não pode apagar o que o utilizador acabou de declarar na landing).
|
|
|
|
---
|
|
|
|
## Origem dos dados (landing)
|
|
|
|
| Campo Self-Service | Label UI | Chave persistência |
|
|
|--------------------|----------|-------------------|
|
|
| E-mail corporativo do administrador | `admin@suaempresa.com.br` | `localStorage.ligbox_planned_email` |
|
|
| Senha | campo Senha | `sessionStorage.ibytera_onboard_admin_password` |
|
|
| Login portal | telefone/nickname | `sessionStorage` (portal login id — fora do escopo conta admin) |
|
|
|
|
**Botões equivalentes:** card **Self-Service** (hero) e CTA **«Criar Meu Servidor Agora»** (scroll para o mesmo card).
|
|
|
|
**Fluxos que disparam pré-preenchimento:**
|
|
|
|
1. **Registo** → 2FA TOTP → `finishOnboarding()` → redirect `/onboard`
|
|
2. **Login** (ou login + 2FA) → redirect `/onboard`
|
|
|
|
---
|
|
|
|
## Destino no wizard (passo Conta admin — step 2)
|
|
|
|
Ao abrir ou regressar a este passo, **três valores** devem estar preenchidos:
|
|
|
|
| # | Origem Self-Service | Campo wizard | Exemplo |
|
|
|---|---------------------|--------------|---------|
|
|
| 1 | E-mail corporativo completo | `localPart` + `domain` (parte local + domínio) | `admin` + `suaempresa.com.br` |
|
|
| 2 | Domínio extraído do e-mail | `domain` (passo 0 também) | `suaempresa.com.br` |
|
|
| 3 | Senha | `password` (mascarada, reutilização) | via `AdminPasswordField` |
|
|
|
|
**Passo 0 (Domínio):** se `ligbox_planned_email` existir, o campo domínio deve iniciar com o domínio do e-mail e mostrar banner informativo.
|
|
|
|
**Passo 3 (Rever e criar):** senha em modo `confirm` — mascarada, reutilizada; revelar com olho exige re-autenticação portal (2FA).
|
|
|
|
---
|
|
|
|
## Comportamento funcional
|
|
|
|
### FR-001 — Persistência imediata no registo
|
|
Após registo portal com sucesso (antes do TOTP), gravar:
|
|
- `setAdminPassword(password)`
|
|
- `localStorage.ligbox_planned_email` = e-mail corporativo normalizado (lowercase, trim)
|
|
|
|
### FR-002 — Prioridade Self-Service sobre wizard state
|
|
Se `ligbox_planned_email` **ou** senha em `sessionStorage` existirem ao montar `/onboard`:
|
|
- **Ignorar** `domain` / `localPart` / `notifyEmail` antigos de `ibytera_onboard_wizard_state` para pré-preenchimento
|
|
- Aplicar valores derivados do Self-Service
|
|
|
|
### FR-003 — Sincronização no mount
|
|
`useEffect` no wizard reaplica pré-preenchimento se o utilizador navegou landing → onboard na mesma aba.
|
|
|
|
### FR-004 — Senha não vai para wizard state JSON
|
|
Senha permanece **apenas** em `sessionStorage` (`onboardPassword.js`) — nunca em `saveWizardState()`.
|
|
|
|
### FR-005 — Revelação de senha
|
|
Ícone olho → modal re-autenticação portal (`PasswordRevealAuth`); visível 30s; opção «Definir senha diferente».
|
|
|
|
### FR-006 — Sem Self-Service
|
|
Utilizador entra directo em `/onboard` sem landing: campos vazios ou defaults (`admin`, domínio manual) — sem regressão.
|
|
|
|
---
|
|
|
|
## Critérios de aceitação
|
|
|
|
1. **Given** registo com `admin@empresa.com` + senha `MinhaSenh@8` + TOTP concluído, **When** abre `/onboard` passo Conta admin, **Then** vê `admin@empresa.com`, domínio `empresa.com`, senha reutilizada (mascarada).
|
|
2. **Given** wizard state antigo com domínio `outro.com` em sessionStorage, **When** novo registo com `admin@novo.com`, **Then** domínio no wizard é `novo.com` (não `outro.com`).
|
|
3. **Given** login com `planned_corporate_email` da API, **When** redirect `/onboard`, **Then** campos pré-preenchidos.
|
|
4. **Given** F5 na mesma aba após Self-Service, **When** wizard recarrega, **Then** e-mail/domínio/senha mantêm-se (localStorage + sessionStorage).
|
|
5. **Given** nova aba sem storage, **When** `/onboard` directo, **Then** sem pré-preenchimento (comportamento legítimo).
|
|
|
|
---
|
|
|
|
## Implementação (referência código VM112 — `/opt/ligbox-wizard`)
|
|
|
|
| Ficheiro | Função |
|
|
|----------|--------|
|
|
| `frontend/src/sessionPersist.js` | `beginOnboardingForEmail()`, `syncWizardWithPlannedEmail()`, `applyPlannedEmailPrefill()`, `loadWizardStateForOnboard()` |
|
|
| `frontend/src/portalAuth.js` | `setPortalOnboardCredentials()` → `sessionStorage.ligbox_onboard_password` |
|
|
| `frontend/src/onboardPassword.js` | alias leitura/escrita na mesma chave `ligbox_onboard_password` (wizard) |
|
|
| `frontend/src/ligbox/components/SelfServiceCard.jsx` | registo/login/TOTP → `beginOnboardingForEmail` + credenciais |
|
|
| `frontend/src/App.jsx` | `loadWizardStateForOnboard()` no init + `useEffect` de sync |
|
|
| `frontend/src/AdminPasswordField.jsx` | senha mascarada + reveal com `verifyStepUp` (2FA) |
|
|
|
|
---
|
|
|
|
## Fora de escopo
|
|
|
|
- Enviar senha para VM122 / webhooks / Desk (nunca)
|
|
- Pré-preencher a partir de cookies cross-domain
|
|
- Sincronizar com Carbonio antes de `POST /account/create`
|
|
|
|
---
|
|
|
|
## Regressão conhecida (corrigida nesta spec)
|
|
|
|
**Causas identificadas (2026-06-16):**
|
|
|
|
1. Wizard state antigo em `sessionStorage` (`ligbox_onboard_wizard_state`) mantinha `domain`/`localPart` de sessão anterior e bloqueava o e-mail novo do Self-Service.
|
|
2. Senha gravada em chave errada (`ibytera_onboard_admin_password` em código de dev) enquanto o portal em produção lia `ligbox_onboard_password`.
|
|
3. E-mail só ia para `localStorage` após TOTP completo — registo sem `beginOnboardingForEmail()` deixava o wizard sem âncora.
|
|
|
|
**Fix aplicado:**
|
|
|
|
- `syncWizardWithPlannedEmail()` + `ligbox_wizard_planned_email` como âncora — descarta wizard stale quando o e-mail muda.
|
|
- `loadWizardStateForOnboard()` aplica sempre domínio/localPart/notify a partir de `ligbox_planned_email`.
|
|
- `SelfServiceCard` chama `beginOnboardingForEmail()` + `setPortalOnboardCredentials()` no registo, login e fim do TOTP.
|