# Onboarding

**Para quem:** novo produtor, organizador, curador ou escola  
**Última revisão:** 2026-07-13  
**Rotas relacionadas:** `/guides`, `/guides?code=`, `/seller`

---

## O que você consegue fazer

- Criar conta na Subcena
- Ativar seu perfil com convite de role
- Criar sua primeira organização
- Conectar pagamentos via Stripe (exceto curadores)

---

## Pré-requisitos

- Convite da equipe Subcena (link com `?code=`) **ou** acesso admin/manager para auto-ativação
- Navegador com cookies habilitados (auth Clerk)

---

## Passo a passo

### Passo 1 — Criar conta

1. Acesse [subcena.com/guides](https://subcena.com/guides)
2. Clique em **entrar ou criar conta**
3. Complete o cadastro via Clerk (e-mail, Google, etc.)

O checklist marca este passo como concluído quando você está autenticado.

### Passo 2 — Ativar perfil como organizador

1. Abra o link de convite recebido: `https://subcena.com/guides?code={código}`
2. Na tela de convite, confira sua função (gerente, curadoria, produtora/casa, escola)
3. Clique em **aceitar convite**

Isso define seu `users.role` na plataforma e remove o convite usado.

Se o convite não aparecer, verifique se o link está completo e se você está logado com a conta correta.

### Passo 3 — Criar organização

Com role ativa, escolha o tipo de organização:

| Tipo | Quem pode criar | Rota |
|------|-----------------|------|
| **Casa** (venue) | admin, manager, organizer | `/seller/new-organization?type=venue` |
| **Produtora** | admin, manager, organizer | `/seller/new-organization?type=producer` |
| **Curadoria** | admin, manager, curator | `/seller/new-curation` |
| **Escola** | admin, manager, school | `/hub/seller/new-school` |

Os botões aparecem no passo 3 do checklist em `/guides` quando você tem permissão e ainda não tem organização.

Após criar com `source=onboarding`, você volta para `/guides`. Caso contrário, vai para a página pública da org (`/{slug}`).

### Passo 4 — Ativar pagamentos (Stripe)

**Curadores:** este passo é omitido do checklist — curadoria não exige Stripe no onboarding.

Para os demais:

1. No passo 4 de `/guides`, clique em **criar perfil comercial**
2. Complete o onboarding da Stripe quando solicitado
3. Aguarde status **Ativo** com pagamentos e saques habilitados

Guia completo: [Stripe e taxas](../pagamentos/stripe-e-taxas.md).

---

## Roles da plataforma

| Role | Label | Pode criar |
|------|-------|------------|
| `admin` | administrador | Tudo + painel admin |
| `manager` | gerente | Convites, orgs, curadorias, escolas |
| `organizer` | produtora/casa | Casa e produtora |
| `curator` | curadoria | Curadoria |
| `school` | escola | Escola |
| `collaborator` | colaboradora | Acesso limitado (sem criação de org) |

Convites são gerados em `/seller` por admin (manager, curator, organizer, school) ou manager (curator, organizer, school).

---

## O que acontece nos bastidores

- Convites ficam na tabela de invitations com `password` único usado na URL `?code=`
- `updateUserRole` valida o código, define `users.role` e apaga o convite
- Stripe Connect é vinculado ao **usuário** (`users.stripeConnectId`), não à organização
- O checklist em `/guides` é calculado em tempo real com queries Convex

---

## Problemas comuns

| Sintoma | Causa provável | O que fazer |
|---------|----------------|-------------|
| "Convite não encontrado" | Código inválido ou já usado | Peça novo convite à equipe Subcena |
| Não vejo botão de criar org | Role ainda não ativa | Aceite o convite no passo 2 |
| Não vejo opção de curadoria | Role não é curator/manager/admin | Peça convite com role correta |
| Escola não abre pelo /guides | Link incorreto na UI | Use `/hub/seller/new-school` diretamente |
| Passo 4 não completa | Stripe pendente | Complete configuração no Stripe |

---

## Referências de código (time interno)

- `app/guides/page.tsx` — checklist interativo
- `app/seller/page.tsx` — hub e geração de convites
- `convex/users.ts` — `updateUserRole`, `createInviteForUser`, `getInvitationByPassword`
- `convex/schema/social.ts` — roles e invitations