Status: Approved · v2 · SPEC-DOMAIN-AUTH-001

depends_on: SPEC-DOMAIN-BASE-001, SPEC-GLOSSARY-001

used_by: IS-MVP-02.1, IS-MVP-02.2, IS-MVP-02.3, IS-MVP-16.1

Usuários, autenticação e onboarding

Conta, sessão, papéis e preservação de ações protegidas por AuthIntent.

Objetivo e limites

Esta especificação define o comportamento canônico do domínio Usuários, autenticação e onboarding no RaizFC. Ela deve ser consultada antes de alterar contratos, mocks, endpoints, telas, permissões ou Increment Specifications relacionados.

Incluído no MVP

• Cadastro por e-mail ou telefone e senha.
• Login, refresh, logout e recuperação de senha.
• Onboarding com nome, apelido, distrito e preferências.
• AuthIntent para retomar ações protegidas.
• Ativação do papel de jogador.

Fora do MVP

• Google Sign-In/SSO.
• Autenticação biométrica.
• Múltiplos perfis de jogador.
• Gestão avançada de dispositivos.

Atores e responsabilidades

Ator	Responsabilidade
Visitante	Lê páginas públicas e pode iniciar apoio anônimo.
Usuário	Conta autenticada; nasce como torcedor.
Jogador	Usuário que ativou perfil esportivo.
Gestor	Usuário com membership em entidade gerenciável.
Operação	Suspende conta e trata solicitações de suporte.

Conceitos canônicos

User

Conta principal. Um usuário pode acumular papéis supporter, player, manager e service_provider.

AuthIntent

Registro temporário e seguro da ação que o visitante tentou executar antes de autenticar. Não guarda segredo nem payload financeiro sensível.

Onboarding

Etapa obrigatória após cadastro para coletar identidade mínima e território.

Role

Capacidade geral do usuário; não substitui permissões por entidade.

Invariantes

• Todo usuário cadastrado possui o papel supporter.
• Uma conta ativa possui e-mail ou telefone verificável e identificador único.
• Um usuário possui no máximo um perfil principal de jogador no MVP.
• AuthIntent expira e só pode ser executado pelo usuário que concluiu o fluxo.
• Recuperação de senha não revela se a conta existe.
• Autorização de gestão depende de membership, não apenas de role manager.

Estados

Estado	Significado	Visibilidade/efeito
pending_onboarding	Conta criada, onboarding incompleto	Pode autenticar, mas é redirecionada ao onboarding.
active	Conta plenamente utilizável	Pode executar ações conforme papéis e permissões.
suspended	Conta bloqueada pela operação	Sessões invalidadas; leitura pública continua anônima.
deleted	Conta desativada/anonimizada	Dados públicos seguem regras de histórico e privacidade.

Transições permitidas

Origem	Ação	Destino	Autoridade	Efeitos
—	register	pending_onboarding	Visitante	Cria supporter e sessão inicial.
pending_onboarding	complete_onboarding	active	Próprio usuário	Define distrito, preferências e optional cheer/follows.
active	activate_player	active	Próprio usuário	Adiciona role player e perfil possivelmente incompleto.
active	suspend	suspended	Operação	Revoga sessões e registra auditoria.
suspended	restore	active	Operação	Reativa conta.
active	request_deletion	deleted	Próprio usuário/operação	Aplica retenção e anonimização.

Permissões

Permission key	Quem recebe por padrão	Ação protegida	Auditoria
auth.manageOwnAccount	Próprio usuário	Editar conta e preferências	Sim para segurança
player.activate	Usuário autenticado	Ativar perfil de jogador	Sim
support.manageAccounts	Operação	Suspender/restaurar conta	Sim

Fluxos funcionais

Cadastro e onboarding

1. Visitante informa nome, e-mail ou telefone e senha.
2. Backend valida duplicidade e cria conta pending_onboarding.
3. Sessão é emitida.
4. Usuário escolhe apelido e distrito obrigatório.
5. Time do coração é opcional; quando escolhido, cria cheer e follow.
6. Preferências sugeridas aparecem pré-marcadas apenas quando alinhadas ao onboarding.
7. Conta passa a active e o AuthIntent, se houver, pode ser retomado.

Login contextual

1. Visitante toca em Seguir, Torcer, Denunciar ou Apoio identificado.
2. Cliente cria AuthIntent com tipo, target e rota de retorno.
3. Usuário faz login ou cadastro.
4. Onboarding é concluído se necessário.
5. Cliente pede execução do intent.
6. Backend revalida alvo, permissão e expiração.
7. A ação é executada uma única vez e a navegação retorna ao contexto original.

Recuperação de senha

1. Usuário informa identificador.
2. Resposta pública é neutra.
3. Se a conta existir, token de curta duração é emitido por provider.
4. Nova senha invalida sessões existentes conforme política.

Casos-limite e erros

Cenário	Comportamento esperado	Código/estado
Credencial inválida	Retornar erro genérico sem indicar qual campo falhou	INVALID_CREDENTIALS
AuthIntent expirado	Descartar intent e retornar à página sem executar ação	AUTH_INTENT_EXPIRED
Conta suspensa	Negar login e orientar suporte	ACCOUNT_SUSPENDED
Onboarding incompleto	Permitir sessão, mas exigir conclusão antes de ações sociais	ONBOARDING_REQUIRED
E-mail/telefone duplicado	Bloquear cadastro sem expor detalhes além do necessário	ACCOUNT_ALREADY_EXISTS

Privacidade e exposição pública

• DTO público de usuário nunca expõe e-mail, telefone, sessões ou permissões.
• Apelido pode ser público; nome civil completo não é obrigatório na página pública.
• Tokens, hashes e reset tokens nunca saem da infraestrutura.
• Exclusão de conta deve preservar histórico esportivo quando necessário, substituindo identidade por estado anonimizado.

Notificações e auditoria

• Login em novo dispositivo pode gerar notificação futura; não bloqueia MVP.
• Ativação de jogador gera confirmação in-app.
• Suspensão e restauração registram auditoria operacional.
• Convites de gestão e vínculos são tratados nos domínios correspondentes.

API relacionada

Método	Rota	Acesso	Finalidade
POST	/api/v1/auth/register	Público	Criar conta
POST	/api/v1/auth/login	Público	Autenticar
POST	/api/v1/auth/refresh	Refresh token	Renovar sessão
POST	/api/v1/auth/logout	Autenticado	Encerrar sessão
GET	/api/v1/auth/me	Autenticado	Contexto do usuário
POST	/api/v1/auth/onboarding/complete	Autenticado	Concluir onboarding
POST	/api/v1/auth/intents	Público/opcional	Criar intent
POST	/api/v1/auth/intents/:id/execute	Autenticado	Executar intent
POST	/api/v1/auth/forgot-password	Público	Solicitar recuperação
POST	/api/v1/auth/reset-password	Público com token	Redefinir senha
POST	/api/v1/players/activate	Autenticado	Ativar jogador

Contratos compartilhados

• AuthUserDto
• AuthTokensDto
• AuthSessionDto
• RegisterRequest/Response
• LoginRequest/Response
• CompleteOnboardingRequest
• AuthIntentDto
• AuthIntentType
• ActivatePlayerResponse

Requisitos de UX

• Login e cadastro preservam a ação original.
• Erros são claros sem revelar dados de segurança.
• Onboarding deve ser curto e permitir pular escolhas opcionais.
• Tela Perfil mostra os papéis ativos e entradas para Minha Gestão e Painel do Jogador.
• Sessão expirada durante mutação preserva formulário quando seguro.

Comportamento dos mocks

• Usuários previsíveis: visitor, supporter, player, manager e primary_owner.
• Cenários de credencial inválida, onboarding pendente, conta suspensa e intent expirado.
• Sessão mockada deve alterar o contexto de permissão das chamadas seguintes.
• Forgot password retorna sempre sucesso neutro.

Critérios de aceite

• Usuário nasce supporter.
• Onboarding exige distrito.
• AuthIntent retoma ações protegidas e é idempotente.
• DTOs públicos não expõem dados privados.
• Conta suspensa não executa ações autenticadas.
• Ativação de jogador não cria múltiplos perfis.

Testes obrigatórios

• Cadastro com e-mail e telefone.
• Duplicidade e credencial inválida.
• Refresh/logout.
• Onboarding com e sem time do coração.
• AuthIntent feliz, expirado e executado duas vezes.
• Conta suspensa.
• Recuperação neutra.

Pós-MVP

• SSO Google.
• Gestão visual de dispositivos e sessões.
• MFA para gestores financeiros.
• Login por magic link.

Decisões registradas

• Todo cadastrado é torcedor por padrão.
• Apoio anônimo não exige conta; apoio identificado exige.
• Papéis de usuário e permissões por entidade são conceitos distintos.
• AuthIntent é obrigatório para ações contextuais iniciadas por visitante.

Machine summary

spec: SPEC-DOMAIN-AUTH-001
domain: Usuários, autenticação e onboarding
must_preserve:
  - Todo usuário cadastrado possui o papel supporter.
  - Uma conta ativa possui e-mail ou telefone verificável e identificador único.
  - Um usuário possui no máximo um perfil principal de jogador no MVP.
  - AuthIntent expira e só pode ser executado pelo usuário que concluiu o fluxo.
  - Recuperação de senha não revela se a conta existe.
  - Autorização de gestão depende de membership, não apenas de role manager.
touches:
  - contracts
  - mocks
  - api
  - frontend
  - backend
  - tests
  - documentation