Sistema de Adoção de Assets

Introdução

O sistema de adoção de assets é uma funcionalidade poderosa que permite aos projetos converterem visitantes em apoiadores (adotantes) ativos. Seja através de um modelo de patrocínio anual ou uma simples adoção simbólica gratuita, o sistema gerencia todo o ciclo de vida do relacionamento com o adotante.

Conceitos Chave

• Tipos de Adoção: Suporta modalidades free (gratuita) e paid (paga via Stripe).
• Status da Adoção: Ciclo de vida completo com estados pending, active, cancelled, expired e suspended.
• Hierarquia de Flags: O projeto decide se a feature está ativa globalmente, enquanto cada asset pode ter sua própria configuração (herança ou override).
• Role Supporter: Adotantes recebem a role supporter no contexto do projeto.

Interface do Usuário

QR Code de Adoção

Cada asset possui uma URL única assinada digitalmente com HMAC, que pode ser convertida em QR Code para acesso físico no local do asset.

Wizard de Adoção

Um fluxo de múltiplos passos (@fw/form-wizard) guia o usuário sem necessidade de autenticação prévia:

1. Identificação: Email.
2. Perfil: Nome e telefone.
3. Localização: Dados geográficos (se necessário).
4. Celebração: Tela final com confetes (react-confetti) para adoções gratuitas ou redirecionamento Stripe para pagas.

Painel de Gestão

Localizado em /account/projects/[id]/adoptions/, permite que gestores do projeto visualizem e exportem a lista de adotantes em uma tabela interativa (@tanstack/react-table).

Modelo de Preços

O preço da adoção é configurado individualmente por asset:

• adoption_price_cents: Valor em centavos.
• adoption_currency: Moeda da transação.

Adoções com preço zero são tratadas automaticamente como free.

Fluxo de Autenticação e Email

O sistema foi desenhado para remover barreiras:

• Se o adotante já tem conta, o vínculo é automático.
• Se o adotante for novo, o sistema cria um perfil via auth.admin.createUser() e envia um convite posterior, permitindo que a adoção aconteça sem fricção de login.

Billing e Stripe

Integração nativa com subscrições anuais do Stripe:

• Redirecionamento seguro para Checkout.
• Processamento assíncrono via webhooks em /api/billing/adoption-webhook/.
• Sincronização automática de renovações, cancelamentos e falhas de pagamento.

Configuração Técnica

Variáveis de Ambiente

• ADOPTION_HASH_SECRET: Chave secreta para geração dos hashes HMAC.
• STRIPE_SECRET_KEY: Para integração financeira.

Referência de API (RPCs)

• generate_adoption_hash(asset_id uuid): Gera hash assinado.
• validate_adoption_hash(asset_id uuid, hash text): Valida hash.
• get_effective_adoption_enabled(asset_id uuid): Resolve herança de flags.

Permissões (RLS)

Acesso à tabela adoptions é protegido por políticas RLS baseadas em permissões de projeto e role supporter.