# 📝 CADASTRO AGGIOS - FLUXO COMPLETO (5 STEPS)

---

## 📋 Índice

1. [Visão Geral](#visão-geral)
2. [Estrutura de Steps](#estrutura-de-steps)
3. [Step 1: Dados Pessoais](#step-1-dados-pessoais)
4. [Step 2: Empresa Básico](#step-2-empresa-básico)
5. [Step 3: Localização e Contato](#step-3-localização-e-contato)
6. [Step 4: Escolher Domínio](#step-4-escolher-domínio)
7. [Step 5: Personalização](#step-5-personalização)
8. [Endpoints](#endpoints)
9. [Validações](#validações)
10. [Fluxo Técnico](#fluxo-técnico)

---

## 🎯 Visão Geral

O cadastro de agências na plataforma Aggios é dividido em **5 etapas** bem equilibradas, onde o usuário preenche:

1. Dados pessoais (admin)
2. Dados da empresa (básico)
3. Localização e contato (empresa)
4. Escolhe seu domínio
5. Personaliza o painel

**URL**: `dash.aggios.app/cadastro`

**Endpoint final**: Redireciona para `{slug}.aggios.app/welcome`

**Tempo médio**: 5-10 minutos

**Taxa de conversão esperada**: 60%+

---

## 📐 Estrutura de Steps

A barra de progresso mostra visualmente o progresso:

```
●○○○○  Step 1: Dados Pessoais
○●○○○  Step 2: Empresa Básico
○○●○○  Step 3: Localização e Contato (MESCLADO)
○○○●○  Step 4: Escolher Domínio
○○○○●  Step 5: Personalização
```

Cada step tem objetivo claro e validação independente.

---

## 🔐 STEP 1: DADOS PESSOAIS

**URL**: `dash.aggios.app/cadastro/step-1` ou `dash.aggios.app/cadastro`

**Tempo estimado**: 2-3 minutos

**Objetivo**: Capturar dados do admin que vai gerenciar a agência

### O que o user vê

```
┌────────────────────────────────────────────────┐
│ Criar Agência Aggios                           │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                │
│ Etapa 1 de 5: Dados Pessoais                  │
│ ●○○○○  (barra de progresso)                  │
│                                                │
│ Seu Nome Completo: *                          │
│ [_______________________________]              │
│                                                │
│ Email Pessoal: *                              │
│ [_______________________________]              │
│ (será usado para login)                       │
│                                                │
│ Telefone/Celular: *                           │
│ [_______________________________]              │
│ formato: (XX) XXXXX-XXXX                      │
│                                                │
│ WhatsApp: (opcional)                          │
│ ☑ Mesmo número do telefone acima              │
│ OU:                                            │
│ [_______________________________]              │
│                                                │
│ Senha: *                                       │
│ [_______________________________]              │
│ • Mín 8 caracteres                            │
│ • 1 letra maiúscula                           │
│ • 1 número                                     │
│ • 1 caractere especial (!@#$%^&*)            │
│                                                │
│ Confirmar Senha: *                            │
│ [_______________________________]              │
│                                                │
│ ☑ Concordo com Termos de Uso                 │
│ ☑ Desejo receber newsletters                 │
│                                                │
│ [CANCELAR]  [PRÓXIMA ETAPA →]                │
│                                                │
└────────────────────────────────────────────────┘
```

### Campos Coletados

- Nome Completo (obrigatório)
- Email Pessoal (obrigatório, será login)
- Telefone/Celular (obrigatório)
- WhatsApp (opcional - pode ser igual ao telefone)
- Senha (obrigatório, com requisitos de força)
- Confirmação de Senha (obrigatório)
- Aceitar Termos (obrigatório)
- Newsletter (opcional)

### Comportamentos da UI

**Validação em Tempo Real:**
- Email: valida se já existe (com pequena pausa para não bombardear servidor)
- Telefone: auto-formata conforme digita
- WhatsApp: auto-formata conforme digita
- Força de senha: mostra indicador visual com requisitos

**Máscara de Telefone:**
- User digita: 9999999999
- Sistema transforma em: (11) 9999-9999
- Transforma automaticamente

**WhatsApp:**
- Se marca "Mesmo número do telefone" → campo desaparece
- Se desmarcar → campo aparece para preenchimento

**Botão Próxima Etapa:**
- Desabilitado enquanto formulário incompleto
- Habilitado quando tudo preenchido
- Scroll até primeiro erro se houver problema

### Validações

- Nome: mínimo 3 caracteres
- Email: formato válido + não pode existir no banco
- Telefone: formato (XX) XXXXX-XXXX
- WhatsApp: formato (XX) XXXXX-XXXX (opcional)
- Senha: 8+ caracteres, 1 maiúscula, 1 número, 1 especial
- Confirmação: deve ser igual à senha
- Terms: deve estar marcado

---

## 🏢 STEP 2: EMPRESA BÁSICO

**URL**: `dash.aggios.app/cadastro/step-2`

**Tempo estimado**: 3-4 minutos

**Objetivo**: Capturar informações básicas da agência

### O que o user vê

```
┌────────────────────────────────────────────────┐
│ Criar Agência Aggios                           │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                │
│ Etapa 2 de 5: Empresa Básico                  │
│ ○●○○○  (barra de progresso)                  │
│                                                │
│ Nome da Agência: *                            │
│ [_______________________________]              │
│ (ex: IdeaPages, DevStudio, etc)              │
│                                                │
│ CNPJ da Empresa: *                            │
│ [__.__.__/__-__]                              │
│ (ex: 12.345.678/0001-90)                      │
│ ℹ️ Será usado para emissão de recibos         │
│                                                │
│ Descrição (breve): *                          │
│ [_______________________________]              │
│ [_______________________________]              │
│ [_______________________________]              │
│ (máx 300 caracteres)                          │
│                                                │
│ Website/Portfolio (opcional):                 │
│ [_______________________________]              │
│ (ex: https://idealpages.com.br)              │
│                                                │
│ Segmento/Indústria: *                        │
│ [Agência Digital ▼]                          │
│                                                │
│ Tamanho da Equipe:                            │
│ [1-10 pessoas ▼]                             │
│                                                │
│ [← ANTERIOR]  [PRÓXIMA ETAPA →]             │
│                                                │
└────────────────────────────────────────────────┘
```

### Campos Coletados

- Nome da Agência (obrigatório, 3-100 caracteres)
- CNPJ (obrigatório, 14 dígitos com validação)
- Descrição Breve (obrigatório, 10-300 caracteres)
- Website/Portfolio (opcional)
- Segmento/Indústria (obrigatório, dropdown)
- Tamanho da Equipe (obrigatório, dropdown)

### Comportamentos da UI

**CNPJ:**
- Auto-formata: 12345678000190 → 12.345.678/0001-90
- Valida dígitos verificadores (algoritmo CNPJ)
- Mostra status visual: ✓ válido, ✗ inválido/duplicado
- Se duplicado: "Este CNPJ já está registrado"

**Descrição:**
- Contador de caracteres em tempo real: 47/300
- Quando atinge máximo: não permite mais digitação
- Mostra em cores: verde (ok), amarelo (perto do máximo)

**Dropdown com Busca:**
- Segmento: pode filtrar por busca
- Tamanho: opções fixas (1-10, 11-50, 51-100, 100+)

**Botão Anterior:**
- Sempre disponível
- Volta para Step 1 com dados preenchidos

### Validações

- Nome empresa: 3-100 caracteres, sem caracteres especiais
- CNPJ: 14 dígitos + dígitos verificadores válidos + não duplicado
- Descrição: 10-300 caracteres
- Website: URL válida (opcional)
- Indústria: obrigatório selecionar
- Tamanho: obrigatório selecionar

### Opções de Indústrias

- Agência Digital
- Agência Full-Stack
- Consultoria
- SaaS
- E-commerce
- Software House
- Outra

---

## 📍 STEP 3: LOCALIZAÇÃO E CONTATO

**URL**: `dash.aggios.app/cadastro/step-3`

**Tempo estimado**: 3-4 minutos

**Objetivo**: Capturar dados de localização e contato comercial (MESCLADO em uma tela)

**Motivo da Mesclagem**: Dois grupos relacionados (endereço físico + contato), economiza step sem prejudicar UX

### O que o user vê

```
┌────────────────────────────────────────────────┐
│ Criar Agência Aggios                           │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                │
│ Etapa 3 de 5: Localização e Contato          │
│ ○○●○○  (barra de progresso)                  │
│                                                │
│ ── LOCALIZAÇÃO ──                             │
│                                                │
│ CEP: *                                         │
│ [_____-___]  [BUSCAR CEP]                    │
│ (ex: 01310-100)                               │
│                                                │
│ Estado: *                                      │
│ [São Paulo                              ▼]    │
│                                                │
│ Cidade: *                                      │
│ [São Paulo                              ▼]    │
│ (dropdown com busca)                          │
│                                                │
│ Bairro: *                                      │
│ [_______________________________]              │
│                                                │
│ Rua/Avenida: *                                │
│ [_______________________________]              │
│                                                │
│ Número: *                                      │
│ [___________]                                  │
│                                                │
│ Complemento: (opcional)                       │
│ [_______________________________]              │
│ (ex: Apt 1234, Sala 500)                      │
│                                                │
│ ── CONTATO DA EMPRESA ──                      │
│                                                │
│ Email Comercial: *                            │
│ [_______________________________]              │
│ (ex: contato@idealpages.com.br)              │
│                                                │
│ Telefone da Empresa: *                        │
│ [_______________________________]              │
│ (ex: (11) 3333-4444)                         │
│                                                │
│ WhatsApp Empresarial: (opcional)              │
│ ☑ Mesmo número do telefone acima              │
│ OU:                                            │
│ [_______________________________]              │
│                                                │
│ [← ANTERIOR]  [PRÓXIMA ETAPA →]             │
│                                                │
└────────────────────────────────────────────────┘
```

### Campos Coletados - Localização

- CEP (obrigatório, 8 dígitos, busca com ViaCEP)
- Estado/UF (obrigatório, dropdown com 27 opções)
- Cidade (obrigatório, dropdown com busca)
- Bairro (obrigatório, mínimo 3 caracteres)
- Rua/Avenida (obrigatório, mínimo 3 caracteres)
- Número (obrigatório, 1-5 dígitos)
- Complemento (opcional, máximo 100 caracteres)

### Campos Coletados - Contato

- Email Comercial (obrigatório)
- Telefone da Empresa (obrigatório)
- WhatsApp Empresarial (opcional, pode ser igual ao telefone)

### Comportamentos da UI

**CEP - Busca com ViaCEP:**

Quando user digita um CEP válido:
1. Sistema aguarda 1-2 segundos (debounce)
2. Faz requisição para ViaCEP
3. Se encontrado: auto-preenche Estado, Cidade, Bairro, Rua
4. User completa Número e Complemento
5. Se não encontrado: campos ficam em branco para preenchimento manual

**Feedback Visual do CEP:**
- ⏳ Amarelo enquanto busca
- ✓ Verde quando encontrado
- ✗ Vermelho quando não encontrado

**Dropdown de Cidades:**
- Ao clicar em "Cidade"
- Abre dropdown com opções do Estado selecionado
- Pode digitar para filtrar (ex: digita "cam" → mostra "Campinas")
- Seleciona e fecha

**Máscara de CEP:**
- User digita: 01310100
- Sistema transforma em: 01310-100
- Auto-formata conforme digita

**WhatsApp - Checkbox:**
- Se marca "Mesmo número do telefone" → campo WhatsApp desaparece
- Se desmarcar → campo WhatsApp aparece

**Seções Visuais:**
- "LOCALIZAÇÃO" em destaque (para separar dos contatos)
- "CONTATO DA EMPRESA" em destaque (segunda seção)
- Divisão visual clara entre as duas seções

### Validações

**Localização:**
- CEP: 8 dígitos válidos
- CEP: encontrado em ViaCEP OU preenchido manualmente com dados corretos
- Estado: selecionado de lista (27 UFs)
- Cidade: selecionada de lista
- Bairro: 3+ caracteres
- Rua: 3+ caracteres
- Número: 1-5 dígitos numéricos

**Contato:**
- Email: formato válido
- Telefone: formato válido (XX) XXXX-XXXX
- WhatsApp: formato válido (XX) XXXXX-XXXX (opcional)

---

## 🌐 STEP 4: ESCOLHER DOMÍNIO

**URL**: `dash.aggios.app/cadastro/step-4`

**Tempo estimado**: 1-2 minutos

**Objetivo**: User escolhe o slug (domínio) para seu painel

**Importância**: Decisão importante, mostra sugestões automáticas

### O que o user vê

```
┌────────────────────────────────────────────────┐
│ Criar Agência Aggios                           │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                │
│ Etapa 4 de 5: Escolha seu Domínio             │
│ ○○○●○  (barra de progresso)                  │
│                                                │
│ Seu painel estará em:                          │
│ https://[_____________].aggios.app             │
│                                                │
│ Dicas:                                         │
│ • Use nome da sua agência (sem espaços)       │
│ • Apenas letras, números e hífen              │
│ • Mínimo 3 caracteres                         │
│                                                │
│ ┌──────────────────────────────────────────┐  │
│ │ idealpages                            ✓ │  │
│ │ (verde + checkmark = disponível)        │  │
│ └──────────────────────────────────────────┘  │
│                                                │
│ 🔗 https://idealpages.aggios.app              │
│                                                │
│ [USAR ESTE]                                   │
│                                                │
│ ── OU ESCOLHA OUTRO ──                        │
│                                                │
│ Prefere outro?                                │
│ [_______________________________]              │
│                                                │
│ [VERIFICAR DISPONIBILIDADE]                   │
│                                                │
│ ┌──────────────────────────────────────────┐  │
│ │ idealpages-studio                     ✓ │  │
│ │ (disponível - verde)                    │  │
│ └──────────────────────────────────────────┘  │
│                                                │
│ 🔗 https://idealpages-studio.aggios.app       │
│                                                │
│ [USAR ESTE]                                   │
│                                                │
│ ┌──────────────────────────────────────────┐  │
│ │ idealpages-admin                      ✗ │  │
│ │ ❌ Domínio reservado (não disponível)    │  │
│ └──────────────────────────────────────────┘  │
│                                                │
│ [← ANTERIOR]  [PRÓXIMA ETAPA →]             │
│                                                │
└────────────────────────────────────────────────┘
```

### Campos Coletados

- Slug/Domínio (obrigatório, única decisão neste step)

### Comportamentos da UI

**Sugestão Automática:**
- Ao chegar na página, sistema pega nome da empresa
- Transforma em slug válido (exemplo: "IdeaPages" → "idealpages")
- Já mostra pronto com ✓ se disponível
- User pode usar sugestão ou escolher outro

**Validação em Tempo Real:**
- User digita em "Prefere outro?"
- Sistema aguarda 1-2 segundos (debounce)
- Verifica se slug é válido e disponível
- Mostra resultado visual: ✓ (verde), ✗ (vermelho), ⏳ (amarelo verificando)

**Auto-Formatação:**
- "IdeaPages" → "idealpages" (lowercase automático)
- "Ideal Pages" → "ideal-pages" (espaço vira hífen)
- "Ideal___Pages" → "ideal-pages" (múltiplos hífens viram um)
- Remove caracteres inválidos automaticamente

**Botão "Usar Este":**
- Só fica ativado para slugs com ✓
- Desativado para slugs com ✗
- Ao clicar: salva escolha, permite ir para próximo step

### Validações

- Comprimento: 3-50 caracteres
- Formato: apenas a-z, 0-9, hífen (-)
- Estrutura: não começa/termina com hífen
- Reservados: não é palavra reservada do sistema
- Unicidade: não existe no banco

### Palavras Reservadas (Não Permitidas)

admin, api, dash, app, www, mail, blog, shop, store, support, help, docs, status, aggios, login, register, signup, oauth, webhook

---

## 🎨 STEP 5: PERSONALIZAÇÃO

**URL**: `dash.aggios.app/cadastro/step-5`

**Tempo estimado**: 2-3 minutos

**Objetivo**: Personalizar visual do painel (logo, cores, configurações)

**Final da jornada**: Último step antes da criação

### O que o user vê

```
┌────────────────────────────────────────────────┐
│ Criar Agência Aggios                           │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                │
│ Etapa 5 de 5: Personalização do Painel       │
│ ○○○○●  (barra de progresso)                  │
│                                                │
│ ── LOGO E IDENTIDADE ──                       │
│                                                │
│ Logotipo: (opcional)                          │
│ ┌──────────────────────────────────────────┐  │
│ │ [📁 SELECIONAR ARQUIVO]                  │  │
│ │ Ou arraste um arquivo aqui               │  │
│ │                                          │  │
│ │ Formatos: JPG, PNG, SVG                 │  │
│ │ Tamanho máximo: 5MB                     │  │
│ │ Recomendado: 1024x1024px                │  │
│ │                                          │  │
│ │ ℹ️ Será exibido no topo do seu painel   │  │
│ └──────────────────────────────────────────┘  │
│                                                │
│ ── CORES DO PAINEL ──                         │
│                                                │
│ Cor Primária: *                               │
│ ┌────────────────────────────────────────┐   │
│ │ [███] #3B82F6 (Azul padrão)            │   │
│ │ [ESCOLHER COR]                         │   │
│ └────────────────────────────────────────┘   │
│                                                │
│ Cor Secundária: (opcional)                    │
│ ┌────────────────────────────────────────┐   │
│ │ [███] #10B981 (Verde padrão)           │   │
│ │ [ESCOLHER COR]                         │   │
│ └────────────────────────────────────────┘   │
│                                                │
│ ── PREVIEW EM TEMPO REAL ──                  │
│ ┌──────────────────────────────────────────┐  │
│ │ ┌────────────────────────────────────┐  │  │
│ │ │ IdeaPages                          │  │  │
│ │ │ (com logo se tiver)                │  │  │
│ │ └────────────────────────────────────┘  │  │
│ │                                         │  │
│ │ ████████████████████████████████████ │  │ ← cor primária
│ │                                         │  │
│ │ ┌────────────────────────────────────┐  │  │
│ │ │ 📊 Dashboard                       │  │  │
│ │ │ Bem-vindo ao seu painel!           │  │  │
│ │ │                                    │  │  │
│ │ │ [Botão com cor primária]           │  │  │
│ │ │ [Botão com cor secundária]         │  │  │
│ │ └────────────────────────────────────┘  │  │
│ └──────────────────────────────────────────┘  │
│                                                │
│ ── CONFIGURAÇÕES ──                           │
│                                                │
│ ☑ Permitir que clientes façam upload        │
│   de arquivos nos projetos                  │
│                                                │
│ ☑ Ativar portal de cliente automaticamente   │
│   para novos projetos                       │
│                                                │
│ [← ANTERIOR] [FINALIZAR E CRIAR AGÊNCIA]    │
│                                                │
└────────────────────────────────────────────────┘
```

### Campos Coletados

- Logo (opcional, arquivo JPG/PNG/SVG, máx 5MB)
- Cor Primária (obrigatório, hex color)
- Cor Secundária (opcional, hex color)
- Permitir Upload de Clientes (checkbox, padrão: true)
- Ativar Portal de Cliente (checkbox, padrão: true)

### Comportamentos da UI

**Upload de Logo:**
- Área drag & drop: user pode arrastar arquivo diretamente
- Clique para selecionar: abre file picker
- Progresso visual: barra de upload enquanto sobe arquivo
- Preview: mostra imagem após upload
- Opção de remover: botão X para descartar

**Color Picker:**
- Clica em "ESCOLHER COR" → abre modal
- Modal oferece:
  - Paleta de cores predefinidas (rápido)
  - Picker customizado com gradiente
  - Slider de brilho (claro/escuro)
  - Input direto de hex (#RRGGBB)
- Confirmar/Cancelar na modal
- Preview em tempo real no painel

**Preview em Tempo Real:**
- Ao escolher cores: preview atualiza instantaneamente
- Ao fazer upload de logo: aparece no preview
- Mostra como ficará o painel da agência
- Lado a lado com os controles

**Checkboxes (Configurações):**
- "Permitir upload de clientes": já vem marcado por padrão
- "Portal cliente automático": já vem marcado por padrão
- User pode desmarcar se quiser (não recomendado)

**Botão Final:**
- "FINALIZAR E CRIAR AGÊNCIA": botão destaque
- Desabilitado se Cor Primária não estiver preenchida
- Ao clicar: começa processo de criação

### Validações

- Logo: JPG, PNG, SVG (opcional), máximo 5MB
- Cor Primária: formato hex válido (#RRGGBB)
- Cor Secundária: formato hex válido (opcional)

---

## 🔌 ENDPOINTS

### Autenticação e Cadastro

**POST /auth/signup/step-1**
- Recebe dados pessoais
- Valida email + telefone + senha
- Cria entrada temporária (signup_temp)
- Retorna tempUserId para próximos steps

**POST /auth/signup/step-2**
- Recebe dados da empresa
- Valida CNPJ + nomes + indústria
- Atualiza signup_temp
- Retorna success

**POST /auth/signup/step-3**
- Recebe localização e contato
- Valida CEP + endereço + emails/telefones
- Atualiza signup_temp
- Retorna success

**POST /auth/signup/step-4**
- Recebe slug do domínio
- Valida disponibilidade + formato
- Atualiza signup_temp
- Retorna success

**POST /auth/signup/step-5**
- Recebe personalização (logo, cores, configs)
- Valida tudo
- Executa TRANSAÇÃO:
  - Cria tenant
  - Cria user admin
  - Deleta signup_temp
  - Gera JWT
- Retorna token + tenant + redirectUrl

### Validações Auxiliares

**GET /auth/check-slug?slug=idealpages**
- Verifica se slug está disponível
- Retorna: available (true/false)
- Usado em tempo real na Step 4

**GET /api/cep/:cep**
- Busca CEP em ViaCEP
- Retorna: estado, cidade, bairro, rua
- Integração: ViaCEP API (gratuita)
- Cache: 24 horas em Redis

**POST /upload/logo**
- Faz upload de logo para Minio (S3-compatible)
- Retorna URL da imagem
- Validações: tamanho, formato

---

## ✅ VALIDAÇÕES

### STEP 1 - Dados Pessoais

**Nome Completo:**
- Mínimo 3 caracteres
- Sem números no meio
- Máximo 100 caracteres

**Email:**
- Formato válido (RFC 5322)
- Não pode existir no banco
- Verificação com debounce (1-2 segundos)

**Telefone:**
- Formato: (XX) XXXXX-XXXX
- 10-11 dígitos totais
- Números válidos (começa de 0-9)

**WhatsApp:**
- Formato: (XX) XXXXX-XXXX (opcional)
- Se preenchido: deve ser válido
- Pode ser igual ao telefone

**Senha:**
- Mínimo 8 caracteres
- 1 letra maiúscula (A-Z)
- 1 número (0-9)
- 1 caractere especial (!@#$%^&*)
- Máximo 128 caracteres

**Confirmação Senha:**
- Deve ser exatamente igual à senha

**Terms:**
- Deve estar marcado para prosseguir

---

### STEP 2 - Empresa Básico

**Nome Empresa:**
- 3-100 caracteres
- Sem caracteres especiais
- Sem números apenas

**CNPJ:**
- Exatamente 14 dígitos (sem formatação)
- Dígitos verificadores válidos (algoritmo CNPJ)
- Não pode estar duplicado no banco
- Deve estar ativo na Receita Federal

**Descrição:**
- Mínimo 10 caracteres
- Máximo 300 caracteres
- Deve descrever a agência

**Website:**
- URL válida (opcional)
- Deve começar com https:// ou http://
- Domínio válido

**Indústria:**
- Obrigatório selecionar de lista predefinida

**Tamanho Equipe:**
- Obrigatório selecionar de opções: 1-10, 11-50, 51-100, 100+

---

### STEP 3 - Localização e Contato

**CEP:**
- Exatamente 8 dígitos (sem formatação)
- Deve estar cadastrado em ViaCEP
- Se não encontrado: aceita preenchimento manual

**Estado (UF):**
- Obrigatório selecionar de 27 UFs
- Dois caracteres (SP, MG, RJ, etc)

**Cidade:**
- Obrigatório selecionar de lista (por UF)
- Válida para o estado escolhido

**Bairro:**
- Mínimo 3 caracteres
- Máximo 100 caracteres
- Sem números exclusivamente

**Rua/Avenida:**
- Mínimo 3 caracteres
- Máximo 200 caracteres
- Pode conter números

**Número:**
- 1-5 dígitos numéricos
- Obrigatório

**Complemento:**
- Máximo 100 caracteres (opcional)
- Exemplos: Apt 1234, Sala 500, Loja 2

**Email Comercial:**
- Formato válido
- Obrigatório
- Diferente do email pessoal (em regra, mas não obrigatório)

**Telefone Empresa:**
- Formato: (XX) XXXX-XXXX ou (XX) XXXXX-XXXX
- 10-11 dígitos
- Obrigatório

**WhatsApp Empresa:**
- Formato: (XX) XXXXX-XXXX (opcional)
- Se preenchido: deve ser válido
- Pode ser igual ao telefone

---

### STEP 4 - Domínio

**Slug:**
- Comprimento: 3-50 caracteres
- Caracteres permitidos: a-z, 0-9, hífen (-)
- Não pode começar com hífen
- Não pode terminar com hífen
- Não pode ser palavra reservada
- Não pode estar duplicado no banco

---

### STEP 5 - Personalização

**Logo:**
- Formatos aceitos: JPG, PNG, SVG (opcional)
- Tamanho máximo: 5MB
- Resolução recomendada: 1024x1024px

**Cor Primária:**
- Formato hex válido (#RRGGBB)
- Obrigatório

**Cor Secundária:**
- Formato hex válido (opcional)
- Padrão: #10B981 (verde)

**Checkboxes:**
- Valores: true/false
- Nenhuma validação especial

---

## 🔄 FLUXO TÉCNICO

### Fluxo Geral

User acessa `dash.aggios.app/cadastro`
↓
Sistema verifica JWT (não logado)
↓
Redireciona para `/cadastro/step-1`
↓
User preenche Step 1 (Dados Pessoais)
↓
Frontend valida
↓
POST /auth/signup/step-1
↓
Backend valida
↓
INSERT signup_temp
↓
Armazena tempUserId em localStorage
↓
Redireciona /cadastro/step-2

### Fluxo Completo

```
Step 1 → Valida + POST → INSERT signup_temp
   ↓
Step 2 → Valida + POST → UPDATE signup_temp
   ↓
Step 3 → Valida + ViaCEP + POST → UPDATE signup_temp
   ↓
Step 4 → Valida + Check slug + POST → UPDATE signup_temp
   ↓
Step 5 → Valida + Upload logo + POST → TRANSAÇÃO
   ↓
TRANSAÇÃO (Backend):
├─ Valida tempUserId
├─ Valida todos dados
├─ CREATE tenant
├─ CREATE user (admin)
├─ DELETE signup_temp
├─ Gera JWT
└─ COMMIT
   ↓
Response: success + token + tenant + redirectUrl
   ↓
Frontend:
├─ Armazena JWT
├─ Armazena tenantSlug
├─ Redireciona para: {slug}.aggios.app/welcome
```

### Tratamento de Erros

**Se validação frontend falhar:**
- Mostra erros inline abaixo de cada campo
- Destaca campos com erro (vermelho)
- Scroll automático até primeiro erro
- User corrige e tenta novamente

**Se backend retornar erro:**
- Toast com mensagem de erro (em vermelho)
- User permanece na mesma página
- Formulário mantém valores preenchidos
- User pode corrigir e tentar novamente

**Se sessão expirar:**
- signup_temp é deletado após 24 horas
- Redireciona pra login
- User perde progresso
- Pode começar do zero

**Se houver problema na transação final:**
- Rollback automático (desfaz tudo)
- Retorna erro específico
- User fica em Step 5
- Pode tentar novamente

---

## 📊 Estatísticas Esperadas

**Tempo médio de conclusão**: 5-10 minutos

**Taxa de conclusão esperada**: 60%+

**Pontos de drop-off provável**:
- Step 1 (não quer criar conta): ~15%
- Step 2 (CNPJ problemático): ~10%
- Step 3 (endereço): ~5%
- Step 4 (domínio indecisão): ~5%
- Step 5 (logo/cores): ~5%

---

## 🎯 Resumo Final

```
✅ CADASTRO FINAL: 5 STEPS

Step 1: Dados Pessoais (5 campos)
        - Nome, email, telefone, whatsapp, senha
        - 2-3 minutos
        - Taxa drop: ~15%

Step 2: Empresa Básico (6 campos)
        - Nome, CNPJ, descrição, website, indústria, tamanho
        - 3-4 minutos
        - Taxa drop: ~10%

Step 3: Localização e Contato (10 campos) ← MESCLADO
        - CEP, estado, cidade, bairro, rua, número, complemento
        - Email, telefone, whatsapp
        - 3-4 minutos
        - Taxa drop: ~10%

Step 4: Domínio (1 campo)
        - Escolher slug
        - 1-2 minutos
        - Taxa drop: ~5%

Step 5: Personalização (3 campos)
        - Logo, cores primária/secundária, checkboxes
        - 2-3 minutos
        - Taxa drop: ~5%

TOTAL: 25 campos distribuídos equilibradamente

BENEFÍCIOS:
✅ 5 steps (não assusta usuário)
✅ Distribuição lógica (cada step tem objetivo)
✅ Step 3 mesclado (10 campos, bem organizado com seções)
✅ Validação granular (erro em um step não afeta outro)
✅ Melhor taxa de conversão (menos drop-off)
✅ Progress visual (user sabe onde está)
✅ Fácil retomar se desistir (dados salvos em DB)
```

---

**Versão**: 1.0  
**Data**: 04/12/2025  
**Status**: Pronto para desenvolvimento  
**Detalhamento**: Lógica e UX (sem código técnico)