Uma ideia.
Um manual.
Seu próximo SaaS.

Atue como engenheiro responsável pelo desenvolvimento e preparação para produção de um SaaS de referências de conteúdos para criação de vídeos. Implemente código funcional; não entregue apenas um protótipo visual.

Leia o repositório e este documento antes de alterar arquivos. Se não houver projeto, crie Next.js + TypeScript + App Router. Use releases estáveis compatíveis, confira a documentação oficial e registre versões no lockfile. Use shadcn/ui e Tailwind, Supabase Auth/PostgreSQL/Storage, Upstash Redis, QStash, SMTP com Resend e hospedagem na Vercel. O idioma de toda experiência é Português Brasil.

O usuário cadastra sua chave da ScrapeCreators e perfis públicos de referência. O sistema coleta até 500 Reels disponíveis por importação, persiste os resultados, permite identificar vídeos com maior desempenho, favoritar, organizar coleções, filtrar e fazer anotações pessoais. Existem usuários e administrador. O usuário pode cadastrar quantos perfis quiser. As credenciais e todos os dados pessoais são isolados por usuário.

Regras permanentes:
1. Todas as configurações de infraestrutura e marca vêm de env, com esquema Zod, separação pública/privada e validação por capacidade. Nunca exponha secrets via NEXT_PUBLIC_, bundles, HTML, logs ou mensagens de erro.
2. Chaves pessoais da ScrapeCreators são cadastradas na aplicação e criptografadas no servidor. Não coloque chaves individuais no .env global. O cliente nunca lê o segredo armazenado; recebe apenas status e trecho mascarado.
3. PostgreSQL é a fonte de verdade. Cache não define permissões, planos, propriedade ou progresso durável. Todas as mutações verificam autenticação, titularidade, suspensão e autorização no servidor.
4. Use RLS e constraints para isolamento. Não use service role em operações normais do usuário. Operações privilegiadas ficam em módulos server-only e validam escopo explicitamente.
5. Nenhuma coleta longa fica em uma única função Vercel. Use tarefas por página, checkpoints, idempotência, outbox transacional e recuperação de interrupções.
6. Consulte https://docs.scrapecreators.com/llms.txt e páginas específicas. Não invente endpoints, parâmetros, campos, métricas ou preços. Campos indisponíveis são null, e a interface mostra “Não disponível”.
7. Use adapters para coleta, cache, storage, fila, e-mail e identidade. Não anuncie portabilidade como simples troca de env onde existem diferenças de protocolo ou modelo de segurança.
8. Não crie assinaturas ou pagamentos fictícios. Sem gateway definido, os planos funcionam por atribuição manual do administrador, claramente identificada. Não inclua geração de vídeos ou roteiros com LLM no MVP.
9. Não inclua dados demonstrativos em produção. Fixtures de teste são explícitas e isoladas.
10. Toda ação deve ter estados de carregamento, vazio, sucesso, erro, autorização negada e integração indisponível, quando aplicável. A acessibilidade e a experiência mobile fazem parte da entrega.

Crie docs/PRODUTO.md, docs/ARQUITETURA.md, docs/SEGURANCA.md e docs/PROGRESSO.md. Registre requisitos, escolhas, limitações e próximos passos. Trabalhe etapa por etapa. Ao encerrar cada etapa, apresente alterações, comandos realmente executados, resultados e pendências. Não declare teste, integração ou deploy bem-sucedido sem evidência. Se faltar credencial, conclua as partes independentes e descreva exatamente o teste real que ficou pendente.

Implemente a base do projeto seguindo o contrato permanente. Nesta etapa priorize ambiente, arquitetura e execução local.

Crie estrutura por funcionalidades e serviços: src/app, src/components, src/features, src/server, src/server/adapters, src/lib/env, src/lib/validation, scripts, supabase/migrations, docs e tests. Mantenha autorização e regras de negócio fora dos componentes React. Marque módulos sensíveis com server-only.

Crie .env.example, .env.development.example e .env.production.example usando o catálogo deste pacote. Forneça instruções para gerar .env.development.local e .env.production.local sem versioná-los. Não use NODE_ENV=dev ou valores diferentes de development/production/test; use APP_ENV para distinguir desenvolvimento, preview e produção.

Crie esquema tipado de env, com validação de URL, e-mail, número, booleano explícito e hex de cor. Proíba chave de criptografia vazia/inválida em funcionalidades sensíveis e configuração localhost em produção. Valide grupos ativos: SMTP, QStash, Redis e storage. Um grupo não implementado ou inativo não deve tornar obrigatório um secret sem uso. Não faça chamadas externas nem exija bootstrap admin durante next build.

Não crie variáveis decorativas. Cada env deve ter consumidor ou estar documentada como reservada para adaptador futuro. As chaves S3, REDIS_URL e DATABASE_URL não são exigidas para adaptadores inativos. VERCEL_TOKEN é opcional para automação de deploy e nunca necessário no runtime.

Configurações públicas: nome, URL, suporte, cores e credenciais públicas do Supabase. Prefira carregar marca validada no servidor e repassar somente campos públicos. Se usar NEXT_PUBLIC_, explique que seu valor entra no build e exige novo deploy para mudar.

Implemente interfaces ContentProvider, CacheAdapter, StorageAdapter, JobQueue, Mailer e IdentityProvider; forneça adaptadores concretos na etapa pertinente. Não inclua uma implementação vazia que responda sucesso. QStash publica tarefas; o banco guarda seu estado. Redis pode fornecer cache e rate limit, sem guardar o único registro do trabalho.

Configure scripts dev, build, start, lint, typecheck, test, db:migrate, db:seed, admin:bootstrap, services:configure e env:check. Não deixe comandos inexistentes na documentação. Documente instalação, versões e arquitetura. Execute typecheck e build aplicáveis e registre o resultado real.

Implemente migrations SQL ordenadas para Supabase, com schema, índices, constraints, RLS e grants. Migrations são a fonte do schema. Seeds populam planos/configurações iniciais de forma idempotente. Dados de exemplo só em ambiente de teste ou desenvolvimento com opção explícita.

Modelo mínimo:
- profiles: id da identidade, nome, avatar, fuso horário e preferências não sensíveis.
- user_roles: user_id e papel user/admin. Nenhum usuário edita seu próprio papel. account_status separado, controlado pelo administrador.
- api_credentials: user_id, provider, ciphertext, nonce, tag, key_version, máscara, status e last_validated_at. Uma credencial ativa da ScrapeCreators por usuário no MVP, usada por todos os seus perfis. Rotação substitui a ativa sem expor a antiga.
- reference_accounts: user_id, plataforma, external_id, handle normalizado, URL canônica, nome, bio quando disponível, avatar, seguidores atuais e datas de coleta.
- reference_account_snapshots: métricas do perfil com collected_at para histórico.
- videos: user_id, reference_account_id, plataforma, external_id como texto, shortcode, permalink, caption nullable, data de publicação nullable, duração nullable, thumbnail/source_url nullable, métricas atuais nullable, collected_at e versão do normalizador.
- video_metric_snapshots: observações com video_id, métricas nullable, collected_at e identificação da operação para deduplicação.
- notes, favorites, tags, video_tags, collections e collection_items: tudo pertence a um usuário; notes são privadas e não comentários publicados no Instagram.
- sync_jobs: user_id, profile_id, tipo, status, cursor, contadores, orçamento de requests, checkpoint, motivo final, cancelamento, lease e timestamps.
- sync_job_steps: página/etapa, geração, request ID e estado durável, impedindo repetição de transações.
- outbox_events: eventos internos escritos na mesma transação do checkpoint, tentativas e estado de publicação.
- provider_usage: user_id, job_id, endpoint, requests e créditos somente quando fornecidos; não guardar headers ou credenciais.
- plans, plan_entitlements e subscriptions: plano e atribuição manual com origem explícita, datas e estado.
- audit_logs e legal_acceptances: eventos mínimos e versão dos termos aceitos, sem secrets.

Use UUID internos, timestamptz em UTC, bigint para contagens e texto para IDs externos potencialmente maiores que o inteiro seguro do JavaScript. Não converta null em zero. Defina exclusões em cascata cuidadosamente, retenção e trilha de exclusão de objetos externos.

Crie unicidade por tenant e identidade canônica: perfis por user_id/plataforma/external_id, handles ativos normalizados com estratégia para renomeação, vídeos por user_id/plataforma/external_id, favoritas/associações por seus pares de IDs. Em vídeos colaborativos, preserve todas as associações de origem por tabela de vínculo caso um mesmo vídeo pertença a múltiplos perfis, sem sobrescrever silenciosamente a origem.

Use constraints compostas ou validações transacionais para impedir que um filho do usuário A aponte para perfil, vídeo, tag, coleção ou credencial do usuário B. Ter user_id em uma linha não basta. Não deixe o usuário alterar owner, role, status, plano ou campos internos de execução.

Ative RLS em todas as tabelas acessíveis pela API e teste SELECT/INSERT/UPDATE/DELETE de cada tipo. Segredos devem ficar em schema privado ou tabela sem grants para anon/authenticated; o acesso server-only usa contexto autorizado. Jobs internos, outbox e logs de infraestrutura têm acesso restrito. Evite views que contornem RLS e documente funções SECURITY DEFINER com search_path fixo, grants mínimos e validação de identidade.

Crie buckets privados para avatares e anexos de referência, com policies que verificam tenant no caminho. Valide extensão, MIME real, tamanho e URLs assinadas curtas. Não baixe automaticamente todos os vídeos.

Bootstrap admin usa a API de administração de identidade em script separado, com ADMIN_EMAIL/ADMIN_INITIAL_PASSWORD vindos de env. Nunca grave senha em SQL ou em seed; nunca promova por comparação de e-mail durante o login. Não sobrescreva a senha de admin existente; script deve ser idempotente e abortar conflitos ambíguos. Remova a senha de bootstrap do ambiente após provisionamento.

Entregue migrations, seed, documentação do modelo e teste de isolamento A/B, inclusive inserts com relações cruzadas, views, RPCs e storage. Demonstre aplicação em banco limpo e reexecução segura dos seeds. Migração remota só por comando de provisionamento, nunca automaticamente em requisição ou build.

Implemente Supabase Auth com clientes server/browser separados e fluxo SSR conforme documentação atual. Verifique identidade no servidor usando mecanismo recomendado; não confie apenas em sessão ou JWT fornecido pelo navegador sem validação.

Telas: /entrar, /cadastrar, /esqueci-senha, /redefinir-senha, /confirmar-email e callback de autenticação. Logout é ação real que encerra a sessão e invalida UI/cache sensível, não precisa ser uma página vazia. Redirecionamentos aceitam somente destinos internos seguros. Proteja páginas, Server Actions e Route Handlers; esconder botões não autoriza ações.

Cadastro exige nome, e-mail, senha, confirmação e aceite da versão publicada dos termos. Confirmação de e-mail em produção. Evite enumeração de contas em login e recuperação. Aplique rate limit e mensagens pt-BR. Implemente estados de link inválido/expirado, sessão vencida, usuário suspenso e integração indisponível.

/app/perfil permite editar nome, avatar, fuso, tema, e-mail e senha por fluxos seguros de identidade. Alterações sensíveis e exclusão exigem reautenticação apropriada. A mudança de e-mail mantém verificações do provedor.

Papéis vêm de fonte controlada no servidor. Usuário não altera plano, suspensão ou papel por metadata. Administrador gerencia planos e usuários, mas não recebe leitura automática de chaves ou anotações privadas. Logs administrativos registram ação, autor e alvo sem segredos.

Implemente exportação dos próprios dados e solicitação/exclusão da conta com cancelamento dos jobs, revogação da chave, limpeza dos objetos e processo retomável. Documente retenção técnica e de backups sem prometer exclusão imediata em cópias de segurança.

Execute testes de autorização com A/B, sessão ausente, expirada e conta suspensa. Não invente contas reais de teste nem hardcode credenciais.

Implemente identidade visual consistente usando shadcn/ui e Tailwind. Produto provisório Painel de Referências. Nome e cor principal vêm do ambiente. Layout responsivo com sidebar no desktop e navegação em drawer no mobile, cabeçalho com busca e menu do usuário, tema claro/escuro/sistema persistido e sem flash evitável.

Páginas públicas: landing page, planos, entrar, cadastrar, recuperação, termos de uso, política de privacidade e contato/suporte. Políticas são textos preliminares com dados reais do operador a preencher e revisão pendente; não invente CNPJ, endereço ou garantia jurídica. Não publique rotas com placeholders como políticas definitivas.

Área autenticada: Dashboard, Perfis de referência, Detalhe do perfil, Biblioteca de vídeos, Detalhe do vídeo, Coleções, Favoritos, Métricas, Sincronizações, Integrações, Meu plano, Perfil e Configurações. Admin: visão operacional, usuários, planos, atribuições e auditoria.

Modais/drawers: adicionar perfil, editar perfil interno, remover perfil, cadastrar/substituir chave, confirmar cancelamento da coleta, criar coleção, adicionar anotação, editar tags e confirmar exclusão. Não retornar a chave salva a um formulário.

Dashboard mostra perfis cadastrados, vídeos importados, favoritos, jobs em execução e top vídeos com filtros de período/perfil. Biblioteca oferece cards e tabela, paginação server-side, busca, filtros e ordenação. Card: capa, autor, data, visualizações/curtidas/comentários disponíveis, índice de destaque, favorito, origem e data da coleta. Detalhe: abrir original, preview quando disponível, métricas, histórico, notas, tags e coleções.

Mostre esqueletos, empty states orientando a primeira ação, falhas acionáveis e indisponibilidade. Sem métricas simuladas em produção. Não trate vídeos importados como vídeos criados ou contas de referência como contas Instagram conectadas via OAuth. Anotações são pessoais e não são enviadas à rede social.

Formate datas conforme fuso do usuário e números pt-BR. Use labels explícitos, foco visível, teclado, contraste, diálogo acessível, confirmação para ação destrutiva e leitores de tela. Trunque texto só com forma de acessar conteúdo completo. Verifique mobile e desktop em ambos os temas, especialmente overlays, tabelas e sidebar.

Implemente integração real server-side com ScrapeCreators. Consulte novamente https://docs.scrapecreators.com/llms.txt e documentação específica antes de fixar contratos; registre endpoint, campos usados e data de consulta em docs/INTEGRACOES.md. Use https://api.scrapecreators.com como base validada e header x-api-key. Nunca faça chamada autenticada diretamente pelo navegador.

Rotas upstream iniciais documentadas: GET /v1/instagram/profile para resolver perfil público, GET /v1/instagram/user/reels para Reels paginados usando handle ou user_id, e max_id retornado em paging_info para continuação. GET /v1/instagram/post para detalhes/legenda quando solicitado. Confirme parâmetros exatos dessa última rota antes de implementar. Defina um formato normalizado próprio, independente de trim e do JSON original.

Na documentação consultada, Reels pode omitir legenda e vídeos fixados, e visualizações são do Instagram, podendo divergir do total combinado Instagram/Facebook. Registre essas limitações na UI. Não prometa a lista completa dos 500 vídeos mais recentes se a API não garantir cobertura e ordenação. Colete até 500 disponíveis e apresente em ordem de publicação quando a data existir, mantendo a indicação de incompletude. Não filtre por legenda inexistente como se tivesse pesquisado todos os vídeos.

Credenciais: POST para salvar/validar/substituir e DELETE para remover. Validação usa endpoint documentado de saldo ou outra operação mínima confirmada; informe se a validação consumir crédito. Persistência só após validação ou com status pendente explícito. Retorne status, máscara e datas; nunca plaintext.

Criptografe com AES-256-GCM no servidor, nonce novo por escrita, chave base64 de 32 bytes via API_CREDENTIALS_ENCRYPTION_KEY e versão via API_CREDENTIALS_KEY_VERSION. Associe user_id/provider como AAD; nunca reutilize nonce. Implemente política documentada de rotação e ferramenta de recriptografia com keyring temporário seguro. Não derivar chave de senha admin, token Supabase ou senha de usuário. Os testes devem verificar adulteração e isolamento entre tenants.

Valide URL de perfil Instagram, aceite handle e URL, remova querystring e normalize. Não busque URLs arbitrárias fornecidas pelo usuário. Construa URLs upstream a partir de base permitida; bloqueie host interno, protocolos alternativos e redirects perigosos. Para imagens externas use política restrita de host, tamanho e tipo; nunca permita proxy aberto.

Provider trata timeout, status HTTP, success=false, JSON inválido, saldo insuficiente, chave inválida, perfil privado/inexistente, 429 e erros transitórios. Mensagens pt-BR são úteis e não incluem segredo ou corpo bruto sensível. Use timeout com AbortController, retries limitados apenas para falhas transitórias e respeite Retry-After.

Null significa desconhecido. Preserve IDs externos como string. Guarde somente dados brutos necessários, com retenção explícita, nunca headers de autenticação. Legenda/transcrição são enriquecimento sob demanda com orçamento próprio, sem 500 chamadas extras automáticas. O MVP não precisa de transcrição.

Implemente teste de contrato com fixtures sanitizadas e integração real opcional com chave autorizada. Registre requests e créditos reportados pelo provedor, distinguindo estimativas, dados confirmados e consumo desconhecido.

Implemente importação assíncrona confiável na Vercel. POST autenticado de sincronização cria job e outbox em uma transação e responde 202 com job_id. Não bloqueie a página aguardando toda a coleta. Credencial usada sempre pertence ao dono do perfil e deve continuar ativa antes de cada chamada.

Cada tarefa processa uma página ou lote pequeno dentro do limite da função. Payload contém apenas identificadores opacos de job/step; não contém chave API, senha ou credencial descriptografada. O worker resolve tenant e perfil pelo banco e não confia em user_id externo. Revalide plano, suspensão, cancelamento e credencial.

Verifique Upstash-Signature com SDK oficial, chaves atual/próxima, corpo bruto e URL correta. Não permita endpoint de worker sem autenticação nem bypass de assinatura em produção. Proteja callbacks de falha e endpoints de manutenção separadamente. Sem assinatura válida, nenhuma alteração no banco nem chamada upstream.

Durabilidade: PostgreSQL guarda job, etapa, cursor, contagem, leases, tentativas e checkpoint. Claim/lease é atômico, com expiração e fencing/generation para impedir commit por worker antigo. Gravação dos vídeos, snapshots, checkpoint e evento da próxima etapa ocorre em transação. Unique keys deduplicam gravações e passos.

QStash entrega ao menos uma vez; não prometa exactly-once para chamadas externas. Uma queda após chamada upstream pode repetir consumo sem mecanismo de idempotência oferecido pelo provedor. Documente essa janela e reduza-a com checkpoints, requests rastreados e leases. Locks Redis são auxiliares, não a única defesa.

Publicação da outbox é repetível e reconciliada. Implemente dispatcher protegido e rotina de recuperação acionável por scheduler compatível com o plano escolhido. Documente provisionamento. Não dependa apenas de publicar a próxima mensagem antes de retornar, pois banco e QStash não têm transação distribuída.

Critérios de parada: até 500 vídeos únicos novos/importados conforme modo, fim documentado da paginação, orçamento máximo de páginas/requests, cursor repetido, cancelamento ou erro terminal. Lote vazio com indicação de continuação tem tentativas limitadas, não encerra automaticamente sem avaliar contrato. Não faça loop infinito nem repita todas as 500 entradas em cada refresh.

Estados: na fila, executando, concluído, parcial, falhou, cancelado; separar motivo e completude. Job que atinge 500 é coleta limitada, não catálogo completo. Se chegar ao fim com 130, mostre 130. Em erro depois de 200, preserve 200 e marque parcial. Grave dados página a página e mantenha contadores de recebidos, únicos, atualizados e descartados.

Atualização incremental busca conteúdos recentes, faz upsert e para segundo política explícita de sobreposição. Atualização de métricas de vídeos antigos é tarefa separada com seleção/budget; não prometa refrescar tudo apenas porque encontrou vídeos recentes já conhecidos. Preserve notas, favoritos e coleções em qualquer sync.

Limite concorrência global e por usuário, cooldown por perfil e retries com backoff. Pelo menos uma importação ativa por perfil, com índice único parcial ou regra transacional equivalente. Cache keys incluem tenant, credencial versionada e parâmetros. Revogar credencial cancela novos trabalhos e invalida cache pertinente.

UI usa polling com backoff para progresso, sem chave privilegiada no navegador. Cancelamento é cooperativo e impede novas páginas; não promete desfazer uma requisição já enviada. “Retomar” cria etapa segura a partir do último checkpoint.

Teste entrega duplicada, callbacks inválidos, crash nas janelas críticas, cursor repetido, perfil com menos de 500, saldo insuficiente, revogação da chave, cancelamento, timeout, suspensão e falha ao publicar a outbox. Documente desenvolvimento local: worker/dispatcher local restrito ou túnel HTTPS externo autorizado para callbacks QStash, com credenciais de desenvolvimento.

Implemente operações reais da biblioteca com consulta e paginação no servidor. Evite carregar toda a biblioteca no navegador. Toda operação usa sessão e escopo do proprietário, validado no servidor e pelas políticas do banco.

Filtros: perfis, período de publicação, período de coleta, visualizações mínimas, curtidas, comentários, tags, favoritos, coleção, existência de nota e disponibilidade de legenda. Ordenar por mais recentes, visualizações, índice de destaque e engajamento. Trate datas desconhecidas explicitamente; filtros de publicação não podem inventar a data faltante.

Busca em handle, nome, legenda disponível, tags e notas próprias, com estratégia PostgreSQL documentada e índices adequados. Mostre cobertura da busca quando legendas não foram enriquecidas. Use paginação estável com desempate por ID e parâmetros validados. Proteja busca contra consultas caras com limites e debounce.

CRUD de notas em texto seguro, favoritos, tags, coleções e associações. Escape conteúdo e impeça XSS; não renderize HTML arbitrário da API ou das anotações. Uploads opcionais usam StorageAdapter, bucket privado e limites de MIME/tamanho. Não publique comentários na rede social.

Detalhe do vídeo abre link canônico original e permite preview quando mídia disponível. URLs da mídia podem expirar; apresente fallback e atualização sob demanda com orçamento. Não baixe mídia indiscriminadamente nem transforme o sistema em mirror de vídeos.

Exports CSV e JSON de dados próprios são paginados/limitados ou assíncronos se grandes. Escape CSV contra formula injection. URLs de download são assinadas e expiram; outro usuário não consegue acessá-las. Remoção de perfil confirma consequências e preserva ou apaga notas conforme política explícita apresentada ao usuário.

Valide persistência após reload, combinações de filtros, ordenação, CRUD e isolamento A/B. Evite N+1 e limite campos da resposta.

Implemente painéis sobre os dados realmente coletados. Chame o resultado de índice de destaque na amostra, não previsão garantida de viralização. Toda métrica exibe data de coleta, quantidade de vídeos elegíveis, período, perfil e cobertura.

Indicadores separados:
1. Popularidade absoluta: views Instagram disponíveis.
2. Engajamento por views = (likes + comments) / views * 100, somente com todos os campos conhecidos e views > 0. Não inclua shares/saves inexistentes.
3. Desempenho relativo do perfil = views do vídeo / mediana das views dos vídeos elegíveis do mesmo perfil e janela de publicação. Sugestão inicial: 90 dias, mínimo 10 vídeos, configuráveis. Mediana zero ou amostra insuficiente produz “Dados insuficientes”. Inclua o vídeo na amostra de forma explícita e determinística; registre fórmula/versionamento.
4. Views por seguidores = views / seguidores observados * 100, somente denominador conhecido e > 0; indique data dos seguidores e que não são necessariamente os seguidores na publicação.
5. Crescimento observado = diferença entre snapshots sucessivos. Velocidade observada = diferença / horas entre coletas válidas; não confundir views/idade do vídeo com crescimento medido. Quedas podem ser correções do provedor, não transforme em zero silenciosamente.

Classificações sugestivas por razão: >=2x destaque, >=5x muito acima da mediana, >=10x excepcional na amostra. Limiares configuráveis; nunca trate como regra científica ou promessa de desempenho. Dados faltantes e amostras fracas não geram classificação positiva.

Evite comparar formatos/plataformas incompatíveis e misturar perfis sem normalização. Para ranking agregado, defina amostra por perfil e regras explícitas. Use ranking de views e ranking relativo em painéis distintos.

Gráficos: evolução das views observadas por vídeo, melhores vídeos do período, distribuição de desempenho por perfil e volume de referências importadas. Use datas de publicação para tendências editoriais e de coleta para progresso operacional, com labels distintos. Ausência de snapshots mostra “Ainda sem histórico”, nunca série fabricada.

Implemente queries indexadas, cache segregado e invalidação ao coletar novos dados. Testes de fórmula cobrem null, zero, poucos vídeos, mediana, outliers, fuso, snapshots repetidos e quedas.

Implemente planos como entidades reais no banco, com atribuição administrativa no MVP e checkout desativado até existir gateway escolhido. A interface informa quando a ativação é manual. Não invente preço definitivo, assinatura paga, cobrança recorrente, webhook ou botão que aparenta pagamento funcional.

Seeds usam catálogo configurável por PLAN_CATALOG_JSON, sem secrets, com códigos, nomes, descrição, preço exibido opcional e recursos. Um valor vazio de preço é “Consultar”, não gratuito. Seed idempotente não sobrescreve mudanças administrativas sem flag explícita. DEFAULT_PLAN_CODE precisa existir.

Todos os planos permitem número ilimitado de perfis, conforme requisito. Limites de coleta simultânea, cooldown, orçamento de requests por job e recursos são controles operacionais descritos claramente. A chave individual paga o consumo da ScrapeCreators; a assinatura do SaaS não implica créditos incluídos.

Página Meu plano mostra plano atribuído, recursos, forma de ativação e uso conhecido. Administrador cria/edita planos, atribui plano, define datas, suspende/reactiva usuário e consulta jobs/erros/uso operacional. Toda mutação administrativa verifica role no servidor, registra auditoria e valida campos.

Administradores não veem plaintext de chave nem conteúdo privado por padrão. Mantenha visualização operacional com dados mínimos. Suspensão bloqueia ações e interrompe continuidade dos jobs, inclusive quando service role for usada no worker.

Prepare interface BillingProvider para integração futura, sem implementação fictícia. Registre futuras exigências: webhook assinado, eventos idempotentes, conciliação, valores em centavos, cancelamento e atualização server-side. Não há gateway ou cobrança real nesta entrega.

Teste atribuição, expiração quando aplicável, plano ausente, suspensão, acesso admin por usuário comum e tentativa de alterar plano diretamente pela API.

Implemente Mailer via SMTP, com configuração por env; inicialmente use Resend como servidor SMTP. Confirme host, porta, credenciais e TLS na documentação atual do provedor. Não use porta 587 com secure=true indiscriminadamente; trate TLS direto e STARTTLS corretamente. Valide remetente, domínio e templates pt-BR.

Separe mensagens transacionais da aplicação dos e-mails de autenticação Supabase. Definir SMTP_HOST no .env da Vercel não altera automaticamente Supabase Auth hospedado. Implemente script services:configure que lê env e provisiona configuração Auth via Management API autorizada, ou gere instruções exatas para o painel se a automação não for possível. O token de Management API é exclusivo de provisionamento, não do runtime. Não imprimir secrets nem gravá-los em artefatos de saída.

Inclua configuração de Site URL, allowlist de redirects de dev/produção/preview e templates de confirmação/reset. Permita confirmação explícita do destino de provisionamento para evitar confusão entre projetos. Comando deve mostrar projeto e alterações não sensíveis. Documente DNS obrigatório no provedor de e-mail: o script da aplicação não cria registros DNS sem acesso específico.

StorageAdapter usa bucket privado, paths por tenant, upload limitado e URLs assinadas. Configure buckets e policies por migração/rotina versionada conforme ferramenta suportada. Integração S3 é futura: documente migração de bytes, mapeamento de paths, reemissão de URLs e substituição das policies. Não exija S3_ACCESS_KEY_ID no caminho ativo Supabase.

CacheAdapter Upstash REST é concreto. Redis nativo requer outro adaptador e conexão segura. QueueAdapter QStash é concreto. BullMQ exige worker persistente, retries/leases, scheduler e infraestrutura próprios; REDIS_URL não transforma automaticamente o QStash em BullMQ.

Para migração de Supabase, mantenha schema de domínio em SQL PostgreSQL e documente dependências específicas: auth.users, auth.uid(), PostgREST, funções, storage e identidade. Elabore checklist de migração que inclui credenciais, sessões, permissões, IDs e políticas. Não remova RLS para fingir portabilidade.

Teste envio SMTP com destinatário autorizado e integração de autenticação quando houver credenciais. Sem acesso, declare teste pendente. Evite envio automático em build ou seed. Crie scripts seguros para verificação das capacidades sem operações destrutivas.

Revise o código implementado como produto para produção. Corrija falhas encontradas antes de declarar pronto. Não execute deploy de código inseguro apenas para obter URL.

Segurança: isolamento por usuário em API/SQL/storage/cache/exports; secrets no bundle e git; service role isolada; CSRF/origin e validação de entradas nas mutações; XSS; SSRF; redirects; uploads; rotação da chave; logs redigidos; rate limit; autorização e suspensão em workers; policies e índices. Use security headers adequados e CSP compatível com recursos realmente usados, sem abrir domínios indiscriminadamente.

Confiabilidade: jobs duráveis, recuperação de outbox, idempotência, limites, falhas upstream, cleanup, migrations reproduzíveis, bootstrap idempotente, backup e restauração documentados. Defina métricas de fila, taxa de falha e jobs travados. Health endpoint público não vaza configuração; readiness e diagnósticos detalhados são protegidos.

Validação mínima: lint/typecheck/build; testes de fórmulas e contrato; integração de RLS/ownership; testes de fila e assinaturas; fluxo E2E cadastrar/confirmar/entrar/cadastrar chave/adicionar perfil/importar/filtrar/anotar/favoritar/sair; tentativa cruzada A/B; fluxo admin. E2E pode usar fixture isolada, mas não substitui smoke test real da integração. Testes não enviam e-mail para terceiros nem consomem créditos ilimitadamente.

Desempenho: paginação, ausência de N+1, índices, payloads mínimos, cache por tenant, limite de concorrência e funções Node curtas. Faça QA visual em celular/desktop, claro/escuro e teclado. Registre resultados realmente observados.

Entregue README e docs/DEPLOY.md com etapas em ordem: criar serviços separados para dev/prod; configurar env; aplicar migrations; seeds; provisionar Auth/SMTP/buckets; bootstrap admin; configurar Vercel Development/Preview/Production; publicar; configurar callback/scheduler; executar smoke test; remover senha admin/token de provisionamento do runtime; ativar observabilidade. Preview nunca aponta por padrão para banco, fila ou chave de criptografia de produção.

Variáveis em Vercel devem ser cadastradas nas configurações do projeto ou via CLI com escopo correto, não enviadas como .env secreto no repositório. Exponha publicamente apenas variáveis allowlisted. Redeploy depois de alterações em valores embutidos no build. Não configure migrations automaticamente no build.

Inclua plano de rollback com migrations compatíveis, recuperação de dados e limites conhecidos. Não diga que free tier suporta produção em qualquer escala: confira quotas atuais escolhidas e documente requisitos de upgrade sem inventar números.

Ao concluir, entregue tabela requisito/implementação/evidência/pendência. Diferencie: código preparado, validado localmente, validado com serviços reais e publicado. Liste configuração externa pendente de forma precisa. “Pronto para produção” só quando integrações essenciais, isolamento, callbacks, SMTP e deploy real forem verificados.