# AGENTS.md — New-Barbada Dev ## Contexto do projeto O New-Barbada é uma infraestrutura de campanhas coletivas locais via WhatsApp. Não tratar como: - marketplace; - ecommerce; - Groupon; - plataforma horizontal de descontos; - social commerce genérico. Tratar como: - engine de aquisição coletiva local; - infraestrutura coordenada de campanhas coletivas via WhatsApp; - sistema para reduzir CAC de negócios locais. ## Objetivo técnico atual Criar uma base MVP semi-automatizada para: - cadastrar campanhas; - aprovar campanhas; - criar grupos WhatsApp via Z-API; - registrar participantes; - acompanhar meta mínima; - liberar cupom ou link de agendamento; - encerrar grupos automaticamente; - manter rastreabilidade mínima. Não criar plataforma completa agora. ## Ambiente Servidor dev: ```text Host SSH: barbada-dev Domínio: dev.barbada.com.br Usuário cPanel: devbarbada Home: /home2/devbarbada Web root: /home2/devbarbada/public_html Diretório inicial do webhook: /home2/devbarbada/public_html/webhook Banco MySQL: Database: devbarbada_mvp User: devbarbada_mvp Password: definir em config.php local, nunca commitar Regras obrigatórias Não alterar nada do webhook atual da Quiweb. Não misturar fluxos Quiweb, WHMCS, tickets, financeiro, suporte ou atendimento. Não criar dependência direta excessiva da Z-API sem abstração mínima. Não fazer automação agressiva. Não implementar disparos em massa. Não criar muitos grupos simultâneos. Não usar grupos permanentes. Não expor tokens, senhas ou Client-Token em repositório. Não colocar credenciais reais em arquivos versionados. Não implementar painel completo neste momento. Estrutura técnica desejada Criar estrutura simples: /public_html/webhook /app /Services /Providers /Models /Support /logs /sql config.php config.example.php barbada_webhook.php barbada_cron.php health.php Arquivos iniciais esperados config.php Arquivo local com: DB_HOST DB_NAME DB_USER DB_PASS BARBADA_WEBHOOK_TOKEN ZAPI_INSTANCE_ID ZAPI_TOKEN ZAPI_CLIENT_TOKEN APP_ENV Não versionar. config.example.php Modelo sem senhas reais. health.php Endpoint simples para validar ambiente: https://dev.barbada.com.br/webhook/health.php Deve retornar JSON: { "ok": true, "app": "new-barbada", "env": "dev" } barbada_webhook.php Webhook separado para receber eventos da Z-API. Deve: validar token; ler JSON bruto; salvar evento bruto; identificar tipo do evento; nunca quebrar se payload vier diferente; responder rápido com JSON; logar erros. barbada_cron.php Executado por URL ou CLI para: verificar campanhas expiradas; enviar mensagens finais; marcar campanhas encerradas; chamar leave-group quando aplicável. Abstrações mínimas Criar uma camada: WhatsAppProviderInterface Com métodos: createGroup($name, array $participants) sendText($phone, $message) leaveGroup($groupId) getInviteLink($groupId) Implementação inicial: ZapiProvider Serviços principais Criar serviços simples: CampaignService ParticipantService GroupService EventLogService CampaignService Responsável por: criar campanha; aprovar campanha; ativar campanha; liberar campanha; expirar campanha; fechar campanha. ParticipantService Responsável por: registrar participante; deduplicar por telefone/campanha; atualizar contagem; marcar cupom enviado. GroupService Responsável por: criar grupo; salvar group_id; salvar invite_link; marcar grupo como ativo/encerrado/falhou. EventLogService Responsável por: salvar payload bruto; salvar tipo normalizado; salvar origem; salvar erros. Schema inicial de banco Criar SQL em: /sql/install.sql Tabelas mínimas: sellers campaigns campaign_groups campaign_participants campaign_events sellers Campos mínimos: id name business_name phone city category status created_at updated_at campaigns Campos mínimos: id seller_id name city category offer normal_price collective_price minimum_participants current_participants start_at end_at status coupon_code booking_link created_at updated_at Status possíveis: draft pending_approval approved active goal_reached released expired cancelled closed campaign_groups Campos mínimos: id campaign_id provider provider_instance_id whatsapp_group_id invite_link status failure_reason replaced_by_group_id created_at closed_at campaign_participants Campos mínimos: id campaign_id group_id phone name source opt_in joined_at invite_clicked_at coupon_sent_at status created_at updated_at campaign_events Campos mínimos: id campaign_id group_id participant_id event_type raw_payload normalized_payload source created_at Fluxos MVP-1 1. Aprovação de campanha Por enquanto pode ser manual via script ou seed. Ao aprovar: status muda para approved; sistema cria grupo via Z-API; salva group_id; salva invite_link; campanha muda para active. 2. Entrada de participante Participante pode ser registrado por: evento recebido da Z-API; clique/registro vindo da LP futuramente. Não depender somente do WhatsApp. 3. Meta atingida Quando participantes únicos >= minimum_participants: campanha muda para goal_reached; depois released; envia mensagem no grupo; opcionalmente envia cupom/link individual. 4. Encerramento Quando data_fim vencer: enviar mensagem final; marcar campanha como closed ou expired; chamar leaveGroup; marcar grupo como closed. Mensagens padrão Criação de grupo Campanha Barbada ativa Oferta: {oferta} Cidade: {cidade} Meta: {participantes_atuais}/{meta_minima} Prazo: {data_fim} Convide amigos para liberar a condição especial. Progresso Faltam {faltam} pessoas para liberar a Barbada. Compartilhe o grupo com quem pode se interessar. Ativação Barbada liberada! A campanha atingiu a meta mínima. Cupom: {cupom} Agendamento: {link_agendamento} Validade: {validade} Encerramento Campanha encerrada. Este grupo será finalizado automaticamente. Obrigado por participar da Barbada. Evitar excesso de emojis e mensagens repetitivas. Segurança Validar token do webhook. Nunca exibir segredo em erro. Logs não devem expor tokens. Sanitizar entradas. Usar prepared statements. Salvar payload bruto da Z-API para auditoria. Toda resposta do webhook deve ser JSON. Estilo de implementação PHP simples e claro. Sem framework pesado. Sem overengineering. Código modular, mas mínimo. Preferir funções/classes pequenas. Fallback seguro quando payload vier inesperado. Logs simples em arquivo e eventos no banco. Primeiro objetivo do Codex Antes de implementar automações reais: Criar estrutura de diretórios. Criar config.example.php. Criar health.php. Criar conexão PDO. Criar sql/install.sql. Criar EventLogService. Criar barbada_webhook.php recebendo e salvando payload bruto. Criar barbada_cron.php apenas com resposta de teste. Validar com php -l. Testar health.php via navegador/curl. Não fazer ainda Não criar painel administrativo completo. Não enviar mensagens reais em massa. Não criar múltiplos grupos automaticamente sem aprovação. Não integrar LP completa ainda. Não criar checkout. Não criar marketplace. Não mexer no webhook da Quiweb.