Arquitetura do Sistema de Adoções

Visão Geral

O sistema de adoções permite que usuários (adotantes) apoiem assets específicos dentro de projetos através de um fluxo simplificado e seguro. A arquitetura foi desenhada para suportar tanto adoções gratuitas quanto pagas, garantindo a integridade dos dados através de validação HMAC e integração robusta com Stripe.

Diagrama de Arquitetura

graph TD
    A[Visitante/QR Code] --> B[Public Route: /adopt/assetId/hash]
    B --> C[HMAC Validation]
    C --> D[FormWizard Composable]
    D --> E{Tipo de Adoção}
    E -->|Gratuita| F[Database: Adoptions Table]
    E -->|Paga| G[Stripe Checkout]
    G --> H[Stripe Webhook]
    H --> F
    F --> I[Management Page]

Schema do Banco de Dados

A tabela adoptions é o núcleo do sistema, contendo 22 colunas para rastrear cada detalhe do ciclo de vida da adoção.

erDiagram
    PROJECT ||--o{ ADOPTION : contains
    ASSET ||--o{ ADOPTION : references
    USER ||--o{ ADOPTION : optionally_linked
    
    ADOPTION {
        uuid id
        uuid project_id
        uuid asset_id
        uuid user_id
        string adopter_email
        string adopter_name
        string adopter_phone
        adoption_status status
        adoption_type type
        string stripe_subscription_id
        string stripe_customer_id
        timestamp started_at
        timestamp expires_at
        timestamp renewed_at
        integer amount_cents
        string currency
        jsonb metadata
        text notes
    }

Enums e Tipos

adoption_status: pending, active, cancelled, expired, suspended.
adoption_type: free, paid.

Sistema de Hash HMAC

Para evitar acessos não autorizados e garantir que apenas pessoas com acesso físico ao asset (via QR Code) iniciem o processo, utilizamos SHA256 HMAC.

Secret: Variável de ambiente ADOPTION_HASH_SECRET.
URL: /adopt/{assetId}/{hash}.
RPCs: generate_adoption_hash e validate_adoption_hash.

@fw/form-wizard

Desenvolvemos um componente de wizard composável e reutilizável para o fluxo de adoção.

Componentes: FormWizard.Step, FormWizard.Progress, FormWizard.Navigation, FormWizard.Completion.
Testes: Cobertura total (13/13 testes passando).

Fluxo de Autenticação e Usuário

O sistema lida de forma inteligente com a identidade do adotante:

Email Existente: A adoção é vinculada diretamente à conta.
Email Novo: O sistema utiliza auth.admin.createUser() para criar uma conta latente, processa a adoção e permite o convite posterior.

Integração Stripe

Adoções pagas são processadas como subscrições anuais.

Checkout: Redirecionamento para Stripe Checkout com metadata.source='adoption'.
Webhook: Endpoint /api/billing/adoption-webhook/.
Eventos Processados: checkout.session.completed, subscription.updated, subscription.deleted, invoice.paid.

Feature Flags Hierárquicas

O controle de disponibilidade segue uma hierarquia rigorosa:

Nível de Projeto: adoption_enabled (boolean). Se false, desabilita tudo no projeto.
Nível de Asset: adoption_enabled (boolean ou NULL). Se NULL, herda do projeto.

RPC principal: get_effective_adoption_enabled.

RLS e Permissões

Políticas: 7 políticas RLS protegem a tabela adoptions.
Roles: Introdução do role supporter no enum project_role.

Caminhos Relevantes

Wizard: apps/web/components/adoptions/form-wizard.tsx
Management: apps/web/app/account/projects/[id]/adoptions/page.tsx
Webhook: apps/web/app/api/billing/adoption-webhook/route.ts
Styles: @fw/ui/celebration-screen

Arquitetura do Sistema de Adoções

On this page