waitlist-launch — Fluxo de implementação de página de lista de espera
Extraído da implementação real de fare-waitlist (2026-07, early-fare.hengshiou.com, referência de implementação:
/Users/xiuxiu/Documents/個人事宜/1_Projects/fare-waitlist).
Princípio central: KV é a única fonte de verdade para a lista, antispam não gasta escrita no KV, todas as configurações públicas são via variáveis de runtime, sem analytics não há tráfego, copy constrói confiança por antipush.
Três arquivos de papel (carregar sob demanda, não ler todos de uma vez)
| Arquivo | Papel | Quando ler |
|---|---|---|
references/architecture.md | Arquiteto de informação | Leitura obrigatória ao iniciar: lista de 9 perguntas prévias, fluxo de seis fases, contratos API/KV (podem ser copiados), fronteira entre var e secret, tabela de permissões de ferramentas, manual de verificação, armadilhas conhecidas |
references/copywriting.md | Especialista em marketing | Ler ao escrever copy da página, copy de compartilhamento, imagem OG, planejar canais de tráfego: fórmula de H1 de dor, estrutura do lede, fórmula de consent, diretrizes de antipush, playbook de canais + código de atribuição ref |
references/operations.md | Gerente de produto | Ler ao validar antes do lançamento e operar após o lançamento: lista de verificação do gate (níveis obrigatório/recomendado), indicadores de sucesso versus vaidade, ritmo de retenção, limites de decisão, template de backlog de iteração |
Fluxo de execução (visão do orquestrador)
- Entrevista prévia: Faça as 9 perguntas da seção 1 do
architecture.mdao usuário; não comece sem respostas. Atenção especial: o handle da comunidade deve ser verificado (grep no código-fonte do site existente do usuário ou confirmação pessoal), não adivinhe com a memória do modelo. - Reconhecimento da situação: Se for um repositório existente, faça
git logpara verificar; confirme a conta logada no wrangler e as permissões da zone. - Implementação por fases (detalhes e definição de Done no
architecture.md§2):- Fase 1: Construção básica do site (Worker + assets + KV + domínio personalizado)
- Fase 2: Sincronização da lista com Resend (best-effort + ops/sync idempotente para reabastecimento)
- Fase 3: Antispam tripla camada (honeypot → rate limiting nativo → Turnstile, tudo sem escrita no KV)
- Fase 4: Rodapé de marca pessoal (discreto, peso visual menor que o CTA)
- Fase 5: Camada de exposição (og:image → referral → analytics, nesta ordem, todos modificam index.html)
- Fase 6: Validação de deploy (lista de smoke + cache-buster)
- Copy: Cada espaço de copy (H1/lede/bullets/consent/cartão de prova/frase de compartilhamento) aplica as fórmulas do
copywriting.md; a frase de desistência honesta deve ser verdadeira. - Gate de lançamento: Marque cada item da seção 1 do
operations.md; nenhum item "obrigatório" pode falhar para lançar. Sem analytics configurado, não comece a direcionar tráfego. - Pós-lançamento: Canais usam código ref para atribuição (
copywriting.md§4); retenha quando a lista ultrapassar 100; prova social de número de pessoas só exibe após ultrapassar o limite (operations.md§3).
Disciplina de delegação (com múltiplos subagentes)
- Múltiplas tarefas modificando o mesmo arquivo (típico: as três subtarefas da camada de exposição modificam index.html) → delegar sequencialmente, não em paralelo.
- Cada tarefa delegada a um subagente deve conter: quais arquivos pode modificar, definição de Done, exigência de evidência real (captura de tela/saída curl), não pode commit/deploy.
- O orquestrador valida diff + inspeciona visualmente os artefatos-chave (imagens devem ser lidas) tarefa por tarefa, faz commit por tarefa, após todas concluídas, faz um único deploy + smoke online.
- Relatório de entrega com quatro itens: branch, hash do commit, se já foi deployado, se o worktree foi limpo.
O que o usuário precisa fazer manualmente (não automatizável, avisar com antecedência)
- Criar Turnstile site no dashboard da CF (obter site key + secret)
- Criar Web Analytics site no dashboard da CF (obter beacon token; OAuth do wrangler não tem permissão RUM, não é possível criar via API)
- Resend: criar audience, gerar API key dedicada (não reutilizar de outros sites), verificar DNS do domínio de envio
- Ao vincular domínio personalizado pela primeira vez, pode ser necessário confirmar DNS/certificado no dashboard
O código já é escrito no modo runtime var (/api/health fornece dinamicamente ao frontend); quando as credenciais estiverem prontas, preencha var/secret
refaça o deploy para ativar, sem modificar o código — isso permite que "esperar credenciais" não bloqueie o desenvolvimento.
Armadilhas mais comuns (lista completa no architecture.md §5.3)
- Captura de tela OG com headless Chrome:
--force-device-scale-factor=1(retina gera 2x) +--virtual-time-budget=4000(esperar webfont), após capturar, inspecione visualmente (fonte de fallback, órfãs no título). - Após deploy, cache de borda retorna HTML antigo → validar com
?cb=<timestamp>. - Turnstile online força que curl não consiga testar
/api/join→ testes de contrato (casos normal/duplicado/honeypot) só funcionam localmente comwrangler dev(sem secret é ignorado automaticamente). - Honeypot/rate limiting retornam sucesso suave mas não retornam refCode (sem informação ao bot); já na lista retorna already + mesmo refCode (idempotente).
- Chave de API exposta em diálogo/arquivo → mudar imediatamente para secret.