Casos de Uso — Adoções

Introdução

Este documento detalha os principais casos de uso do sistema de adoções, cobrindo fluxos de usuário final, gestão administrativa e integrações financeiras.

UC-301: Adoção Gratuita via QR Code (Novo Usuário)

• Descrição: Um visitante escaneia o QR Code de um asset habilitado para adoção gratuita e completa o fluxo sem ter conta no sistema.
• Atores: Visitante.
• Pré-condições: Asset com adoption_enabled ativo e preço configurado como zero ou nulo.
• Passos:
  1. Escanear QR Code com link assinado (HMAC).
  2. Inserir email no wizard.
  3. Preencher dados de perfil.
  4. Finalizar adoção.
• Resultado Esperado: Conta latente criada via auth.admin.createUser(), adoção registrada na tabela adoptions com status active.
• Pós-condições: Visitante recebe tela de celebração com confetes.

UC-302: Adoção Gratuita via QR Code (Usuário Existente)

• Descrição: Um usuário já autenticado escaneia o QR Code e completa a adoção.
• Atores: Usuário autenticado.
• Pré-condições: Sessão ativa no navegador.
• Passos: Identificar email já logado, pular etapas de perfil se já preenchidas, confirmar adoção.
• Resultado Esperado: Adoção vinculada ao user_id existente.
• Pós-condições: Adoção visível no perfil do usuário.

UC-303: Adoção Paga via QR Code → Stripe Checkout

• Descrição: Usuário escolhe um asset com preço definido e realiza pagamento anual.
• Atores: Adotante.
• Pré-condições: Asset com adoption_price_cents > 0.
• Passos: Completar wizard inicial, ser redirecionado para Stripe Checkout, realizar pagamento.
• Resultado Esperado: Criação de checkout session com metadata.source='adoption'.
• Pós-condições: Aguardar webhook para ativar adoção.

UC-304: Renovação Anual Automática (Webhook)

• Descrição: Stripe processa a renovação da assinatura anual e notifica o sistema.
• Atores: Stripe (Sistema).
• Pré-condições: Adoção paga ativa com subscrição recorrente.
• Passos: Stripe envia invoice.paid, webhook processa o evento, atualiza renewed_at e expires_at.
• Resultado Esperado: Registro de adoção atualizado com nova data de expiração.
• Pós-condições: Adoção permanece active.

UC-305: Cancelamento de Adoção

• Descrição: Usuário ou gestor cancela a assinatura/adoção.
• Atores: Adotante ou Gestor.
• Pré-condições: Adoção ativa.
• Passos: Cancelar via Stripe ou painel administrativo, webhook processa customer.subscription.deleted.
• Resultado Esperado: Status da adoção alterado para cancelled.
• Pós-condições: Benefícios de adoção removidos após data de expiração.

UC-306: Gestor Visualiza Adoções

• Descrição: O gestor do projeto acessa a lista de todos os adotantes.
• Atores: Gestor de Projeto.
• Pré-condições: Permissões administrativas no projeto.
• Passos: Acessar /account/projects/[id]/adoptions/.
• Resultado Esperado: Visualização da tabela com 6 colunas incluindo nome, asset, status e valor.
• Pós-condições: Possibilidade de exportar dados para relatórios.

UC-307: Feature Flag Desabilitada no Projeto

• Descrição: Tentativa de acesso a adoções em um projeto onde a flag está desativada.
• Atores: Visitante.
• Pré-condições: adoption_enabled = false no nível de projeto.
• Passos: Tentar acessar URL de adoção.
• Resultado Esperado: Redirecionamento para 404 ou mensagem de funcionalidade indisponível.
• Pós-condições: Nenhuma adoção permitida.

UC-308: Override de Flag no Asset

• Descrição: Desabilitar adoção em um asset específico, mesmo com projeto habilitado.
• Atores: Gestor.
• Pré-condições: Configurar adoption_enabled como false diretamente no asset.
• Passos: Tentar escanear QR Code do asset específico.
• Resultado Esperado: Bloqueio do fluxo de adoção apenas para este asset.
• Pós-condições: Outros assets do projeto continuam permitindo adoções.

UC-309: Hash HMAC Inválida (Tentativa Não Autorizada)

• Descrição: Usuário tenta acessar a página de adoção alterando manualmente a URL ou hash.
• Atores: Atacante ou Erro de link.
• Pré-condições: URL com hash alterado.
• Passos: Acessar /adopt/[assetId]/[invalidHash].
• Resultado Esperado: RPC validate_adoption_hash retorna false, acesso negado.
• Pós-condições: Nenhuma informação sensível exposta.

UC-310: Adoção Rápida em Evento/Feira

• Descrição: Fluxo otimizado para adoções massivas durante eventos presenciais.
• Atores: Público de evento.
• Pré-condições: QR Codes impressos e expostos.
• Passos: Escaneamento rápido, preenchimento de email e nome apenas, confirmação instantânea.
• Resultado Esperado: Registro rápido sem necessidade de download de app ou login complexo.
• Pós-condições: Alta taxa de conversão de visitantes presenciais.