Wizard de Onboarding
Visão Geral
O Wizard de Onboarding é um assistente de configuração de 5 etapas que guia novos administradores na configuração inicial do restaurante — desde o tipo de negócio até a importação do cardápio.
| Característica | Detalhe |
|---|---|
| Rota | /t/:slug/admin/onboarding |
| View | frontend-react/src/views/admin/OnboardingWizardView.tsx |
| Componente | frontend-react/src/components/onboarding/OnboardingWizard.tsx |
| Backend | backend/src/tenants/onboarding.controller.ts + onboarding.service.ts |
| Permissão | AllSettings (Admin ou Superadmin) |
O estado do wizard é persistido no backend — o administrador pode sair e retomar de onde parou.
Etapas do Wizard
Etapa 1 — Tipo de Negócio
Selecione o perfil do restaurante. O sistema sugere configurações automáticas baseadas no tipo:
| Tipo | Configuração sugerida |
|---|---|
restaurant | Mesa completa, reservas, cardápio completo |
fast_food | Autoatendimento, sem reservas, pedido rápido |
bar | Comandas, fechamento tardio |
cafe | Cardápio simplificado, pedidos balcão |
pizzeria | Delivery habilitado, tempo de preparo longo |
food_truck | Sem mesas, pedido rápido, delivery |
API: GET /t/:slug/onboarding/suggest-config?businessType=restaurant
Resposta: Configuração sugerida com toggles e defaults por tipo de negócio.
Etapa 2 — Dados Fiscais
Configure CNPJ, regime tributário e razão social:
| Campo | Descrição |
|---|---|
| CNPJ | CNPJ do estabelecimento (para emissão de NF-e/NFS-e) |
| Regime tributário | simples | lucro-presumido | lucro-real |
| Razão social | Nome da empresa conforme CNPJ |
Etapa 3 — Filial Principal
Configura a primeira filial (Branch):
| Campo | Descrição |
|---|---|
| Nome da filial | Nome do ponto de atendimento |
| Endereço | Endereço completo |
| Raio GPS (metros) | Cerca geográfica para auto-aprovação de ponto |
O GPS Fence configurado aqui é usado pela automação de auto-aprovação de ponto quando o colaborador cloca dentro do raio.
Etapa 4 — Formas de Pagamento
Selecione os meios de pagamento aceitos:
| Opção | Descrição |
|---|---|
| PIX | Pagamento via QR Code instantâneo |
| Cartão crédito/débito | Integração com Stone ou Rede |
| Dinheiro | Pagamento em espécie |
| Stone | Gateway Stone (requer serial do terminal) |
| Rede | Gateway Rede (requer credenciais) |
Etapa 5 — Cardápio
Escolha como configurar o cardápio inicial:
| Opção | Ação |
|---|---|
| ✏️ Criar manualmente | Adiciona itens um a um inline |
| 📄 Importar cardápio existente | Redireciona para Importação IA de Cardápio (foto, PDF ou texto) |
| 🚀 Importar arquivo | Abre o Smart Migration Tool embutido — importa CSV/Excel/JSON do cardápio legado e avança o wizard ao concluir |
Estado do Wizard (Backend)
O wizard persiste o estado na entidade Tenant via TenantOnboardingState:
not_started → in_progress (step 1–5) → completedEndpoints de estado:
| Método | Endpoint | Descrição |
|---|---|---|
GET | /t/:slug/onboarding/wizard | Recupera estado atual + respostas salvas |
POST | /t/:slug/onboarding/wizard/init | Inicializa wizard (not_started → in_progress) |
POST | /t/:slug/onboarding/wizard/step | Salva respostas de uma etapa e avança |
POST | /t/:slug/onboarding/wizard/complete | Finaliza e aplica todas as configurações |
Respostas salvas usam merge por dotted-path — cada etapa salva apenas seus próprios campos sem sobrescrever os anteriores.
Aplicação de Configuração
Ao completar o wizard, OnboardingService.applyConfig() executa:
- Cria a Branch principal com nome, endereço e GPS fence configurados
- Ativa os métodos de pagamento selecionados em
PaymentConfig - Atualiza dados fiscais no Tenant (
cnpj,taxRegime,legalName) - Marca
onboardingStatus: completedno Tenant
Importação de Cardápio via IA
Ao escolher "Importar cardápio existente" no wizard (ou acessar diretamente /admin/menu/import):
- Upload ou texto — envie foto do cardápio, PDF ou cole o texto
- Análise por Claude Haiku —
POST /t/:slug/onboarding/menu/import - Tabela de revisão — itens parseados com indicador de confiança
- Seleção e edição — marque/desmarque itens, edite nome/preço/categoria inline
- Confirmação —
POST /t/:slug/onboarding/menu/apply-importcria categorias e itens
Indicadores de confiança:
| Cor | Significado |
|---|---|
| Verde (Alta) | Nome, preço e categoria identificados com certeza |
| Âmbar (Média) | Algum campo incerto ou ambíguo |
| Vermelho (Baixa) | Dados incompletos — revisar antes de confirmar |
Por padrão, apenas itens de alta confiança são pré-selecionados. Itens de baixa confiança requerem seleção manual.