luis.erlacher/Dashboard-Automatizase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
2015b130d0
Dashboard-Automatizase/docs/prd.md
Luis Erlacher e24daee8a6 Initial commit from Create Next App
2025-10-05 21:17:43 -03:00

25 KiB
Raw Blame History

AutomatizaSE Portal - Product Requirements Document (PRD)

1. Goals and Background Context

Goals

  • Fornecer interface web simples para clientes conectarem instâncias WhatsApp via EvolutionAPI
  • Permitir autorização OAuth do Google Calendar de forma direta e segura
  • Criar POC funcional e responsiva (mobile + desktop) em tempo mínimo
  • Garantir autenticação segura via Supabase com recuperação de senha
  • Exibir status de conexões (WhatsApp e Google Calendar) de forma clara

Background Context

A AutomatizaSE necessita de uma interface web simplificada para que seus clientes possam gerenciar conexões de WhatsApp através da EvolutionAPI e autorizar integrações com Google Calendar. Atualmente, não existe uma interface amigável para usuários finais realizarem essas operações, exigindo acesso direto às APIs ou configurações manuais complexas.

Este projeto visa criar uma POC (Proof of Concept) rápida e funcional que centralize essas operações em um portal autenticado, permitindo que clientes não-técnicos realizem essas integrações de forma autônoma e segura. O projeto utilizará Supabase como backend completo e NextJS para o frontend, aproveitando infraestrutura existente e minimizando tempo de setup.

Change Log

Date Version Description Author
2025-10-05 1.0 Versão inicial do PRD John (PM Agent)

2. Requirements

Functional Requirements

FR1: O sistema deve permitir login de usuários via email/senha usando Supabase Auth unificado

FR2: O sistema deve permitir recuperação de senha via SMTP da AutomatizaSE (gerenciado pelo Supabase)

FR3: O sistema deve exibir instâncias do WhatsApp como cards individuais (estilo EvolutionAPI), mostrando nome da instância, status de conexão, e ações disponíveis

FR4: O sistema deve integrar diretamente com a EvolutionAPI para visualizar status de cada instância (conectado/desconectado)

FR5: Cada card de instância deve fornecer botão "Gerar QR Code" que chama endpoint da EvolutionAPI para gerar e exibir QR code de conexão do WhatsApp

FR6: Cada card de instância deve fornecer botão "Desconectar" que chama endpoint da EvolutionAPI para desconectar a instância do WhatsApp

FR7: O sistema NÃO deve permitir criar ou excluir instâncias da EvolutionAPI via interface

FR8: O sistema deve exibir link/botão "Conectar Google Calendar" que redireciona para endpoint OAuth do n8n

FR9: O sistema deve exibir status visual de conexão do Google Calendar (conectado ✅ ou não conectado ❌)

FR10: O sistema deve armazenar dados no schema portal do Supabase (separado do schema public existente)

FR11: O sistema deve permitir que usuário re-autentique Google Calendar com email diferente ao clicar novamente no botão OAuth

Non-Functional Requirements

NFR1: O sistema deve ser responsivo e funcionar em dispositivos mobile e desktop

NFR2: O sistema deve usar tema escuro como padrão

NFR3: O sistema deve usar cores azuis como cor primária (identidade AutomatizaSE)

NFR4: O sistema deve exibir rodapé com "Copyright by AutomatizaSE"

NFR5: O sistema deve carregar e exibir status de conexões em até 3 segundos

NFR6: O sistema deve validar credenciais e tokens de forma segura usando variáveis de ambiente

NFR7: O sistema deve ser implantável rapidamente com configuração mínima (POC)

3. User Interface Design Goals

Overall UX Vision

Portal minimalista focado em duas ações principais: gerenciar conexões WhatsApp e autorizar Google Calendar. Interface limpa, direta, sem distrações, com feedback visual claro de status de conexões. Usuário deve conseguir completar qualquer tarefa em até 3 cliques.

Key Interaction Paradigms

  • Card-based interface para instâncias WhatsApp (similar à EvolutionAPI)
  • Status badges visuais (verde/vermelho) para feedback imediato
  • Modal/Overlay para exibição de QR code
  • Single-click OAuth para Google Calendar
  • Auto-refresh de status após ações

Core Screens and Views

  • Login Screen - Email/senha com link "Esqueci minha senha"
  • Dashboard Principal - Cards de instâncias WhatsApp + Card Google Calendar
  • Modal QR Code - Exibição do QR code com instruções
  • Password Recovery - Tela de recuperação de senha

Accessibility

WCAG AA - Contraste adequado em tema escuro, navegação por teclado, labels descritivos

Branding

  • Cores primárias: Azul AutomatizaSE (tons de azul para botões, links, highlights)
  • Tema: Escuro (background escuro, texto claro)
  • Tipografia: Sans-serif moderna e legível
  • Logo: AutomatizaSE no header
  • Rodapé: "Copyright by AutomatizaSE"
  • Inspiração visual: Interface EvolutionAPI (cards, status badges, layout limpo)

Target Platforms

Web Responsive - Desktop (1920x1080+) e Mobile (375px+), priorizar mobile-first approach

4. Technical Assumptions

Repository Structure

Monorepo - Projeto NextJS único contendo frontend e API routes

Service Architecture

Monolith com API Routes do NextJS - Frontend NextJS com API routes para comunicação com EvolutionAPI e Supabase. Supabase gerencia autenticação, banco de dados (schema portal), e recuperação de senha via SMTP.

Testing Requirements

Manual Testing - POC focada em validação manual, sem suite de testes automatizados inicialmente. Conveniente incluir logs detalhados para debugging.

Additional Technical Assumptions

  • Framework: NextJS 14+ (App Router)
  • UI Components: Shadcn/ui ou TailwindCSS puro para tema escuro e componentes
  • Auth: Supabase Auth (unificado com projeto existente)
  • Database: Supabase PostgreSQL, schema portal
  • EvolutionAPI: Integração via fetch/axios com endpoints REST
  • OAuth Google Calendar: Redirecionamento para n8n webhook (n8n gerencia credenciais)
  • Deployment: Vercel (recomendado para NextJS) ou outra plataforma com suporte a variáveis de ambiente
  • Environment Variables: 
    EVOLUTION_API_URL
EVOLUTION_API_KEY
EVOLUTION_INSTANCE_NAMES (comma-separated)
N8N_OAUTH_URL
SUPABASE_URL
SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY
NEXT_PUBLIC_SITE_URL
  • Estado: Usar React state/hooks para gerenciar status de conexões, evitar bibliotecas de estado pesadas
  • Polling: Implementar polling simples (ex: a cada 5s) para atualizar status de instâncias WhatsApp se necessário

5. Epic List

Epic 1: Foundation & Authentication Estabelecer projeto NextJS, configurar Supabase (schema portal, auth unificado), implementar login/recuperação de senha, e criar dashboard básico com layout e branding AutomatizaSE.

Epic 2: WhatsApp Management via EvolutionAPI Integrar com EvolutionAPI para exibir instâncias como cards, visualizar status de conexão, gerar QR codes para conexão, e desconectar instâncias.

Epic 3: Google Calendar OAuth Integration Implementar botão de autorização OAuth que redireciona para n8n, exibir status de conexão do Google Calendar, e permitir re-autenticação.

6. Epic Details

Epic 1: Foundation & Authentication

Objetivo: Estabelecer base sólida do projeto NextJS com autenticação funcional via Supabase, permitindo que usuários façam login, recuperem senha, e acessem dashboard com branding AutomatizaSE. Epic entrega valor imediato com sistema de auth completo e interface pronta para receber features.

Story 1.1: Setup do Projeto NextJS com TailwindCSS e Estrutura Base

Como desenvolvedor, Eu quero configurar projeto NextJS 14+ com TailwindCSS e estrutura de pastas, Para que a base do projeto esteja pronta para desenvolvimento rápido.

Acceptance Criteria:

  1. Projeto NextJS 14+ inicializado com App Router
  2. TailwindCSS configurado com tema escuro como padrão
  3. Cores azuis da AutomatizaSE definidas no tailwind.config.js como cores primárias
  4. Estrutura de pastas criada: /app, /components, /lib, /types
  5. Arquivo .env.local.example criado com todas as variáveis de ambiente necessárias
  6. Arquivo README.md com instruções de setup e variáveis de ambiente
  7. Aplicação roda localmente em localhost:3000 sem erros

Story 1.2: Configurar Supabase Schema portal e Auth

Como desenvolvedor, Eu quero configurar schema portal no Supabase e integrar auth unificado, Para que o sistema possa armazenar dados isolados e autenticar usuários.

Acceptance Criteria:

  1. Schema portal criado no Supabase (separado de public)
  2. Tabela portal.user_settings criada (ex: campos user_id, created_at, updated_at)
  3. Supabase Auth configurado com SMTP da AutomatizaSE para recuperação de senha
  4. Cliente Supabase inicializado no NextJS (/lib/supabase.ts)
  5. Variáveis de ambiente SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY funcionando
  6. Teste de conexão com Supabase executado com sucesso (query simples)

Story 1.3: Implementar Página de Login

Como usuário, Eu quero fazer login com email e senha, Para que eu possa acessar o dashboard de forma segura.

Acceptance Criteria:

  1. Página de login (/app/login/page.tsx) criada com tema escuro
  2. Formulário contém campos: Email, Senha
  3. Botão "Entrar" chama Supabase Auth (signInWithPassword)
  4. Validação de campos (email válido, senha não vazia) com feedback visual
  5. Mensagens de erro exibidas para credenciais inválidas
  6. Usuário autenticado é redirecionado para /dashboard
  7. Link "Esqueci minha senha" visível e funcional
  8. Logo/Nome "AutomatizaSE" exibido no topo da página
  9. Página é responsiva (mobile e desktop)

Story 1.4: Implementar Recuperação de Senha

Como usuário, Eu quero recuperar minha senha por email, Para que eu possa acessar minha conta caso esqueça a senha.

Acceptance Criteria:

  1. Página de recuperação (/app/reset-password/page.tsx) criada
  2. Formulário contém campo: Email
  3. Botão "Enviar email de recuperação" chama Supabase resetPasswordForEmail
  4. Email de recuperação é enviado via SMTP da AutomatizaSE (configurado no Supabase)
  5. Mensagem de sucesso exibida após envio: "Email enviado! Verifique sua caixa de entrada"
  6. Tratamento de erro se email não existir
  7. Link de volta para login disponível
  8. Página é responsiva

Story 1.5: Criar Dashboard Básico com Layout e Branding

Como usuário autenticado, Eu quero acessar dashboard com branding da AutomatizaSE, Para que eu tenha uma interface inicial clara e profissional.

Acceptance Criteria:

  1. Página de dashboard (/app/dashboard/page.tsx) protegida (apenas usuários autenticados)
  2. Middleware ou guard redireciona não-autenticados para /login
  3. Header exibe logo/nome "AutomatizaSE" e botão de logout
  4. Rodapé exibe "Copyright by AutomatizaSE"
  5. Layout usa tema escuro e cores azuis como primária
  6. Conteúdo placeholder: "Bem-vindo ao Portal AutomatizaSE"
  7. Botão "Sair" funcional (logout e redirect para /login)
  8. Dashboard é responsivo

Epic 2: WhatsApp Management via EvolutionAPI

Objetivo: Integrar portal com EvolutionAPI para permitir que usuários visualizem instâncias WhatsApp como cards, gerem QR codes para conexão, e desconectem instâncias. Epic entrega controle completo de WhatsApp através de interface amigável.

Story 2.1: Integrar com EvolutionAPI para Listar Instâncias

Como desenvolvedor, Eu quero integrar com EvolutionAPI para buscar status de instâncias, Para que o sistema possa exibir informações em tempo real.

Acceptance Criteria:

  1. Arquivo /lib/evolutionapi.ts criado com funções para chamar EvolutionAPI
  2. Variáveis EVOLUTION_API_URL, EVOLUTION_API_KEY, EVOLUTION_INSTANCE_NAMES configuradas
  3. Função getInstanceStatus(instanceName) retorna status (connected/disconnected)
  4. Função trata erros de rede e retorna mensagem apropriada
  5. Parse de EVOLUTION_INSTANCE_NAMES para array de instâncias
  6. Logs de debug registram chamadas à API e respostas
  7. Teste manual confirma que API retorna dados corretamente

Story 2.2: Exibir Cards de Instâncias WhatsApp com Status

Como usuário, Eu quero ver minhas instâncias WhatsApp como cards com status, Para que eu saiba quais estão conectadas ou desconectadas.

Acceptance Criteria:

  1. Componente WhatsAppInstanceCard.tsx criado
  2. Dashboard exibe grid/lista de cards (um para cada instância em EVOLUTION_INSTANCE_NAMES)
  3. Cada card mostra: Nome da instância, Status badge (verde "Connected" ou vermelho "Disconnected")
  4. Layout dos cards segue design similar à imagem de referência da EvolutionAPI
  5. Cards são responsivos (stack em mobile, grid em desktop)
  6. Status é carregado via getInstanceStatus ao montar o componente
  7. Loading state exibido enquanto status carrega
  8. Erro de API exibe mensagem amigável no card

Story 2.3: Implementar Geração e Exibição de QR Code

Como usuário, Eu quero gerar e visualizar QR code de conexão do WhatsApp, Para que eu possa conectar minha conta WhatsApp à instância.

Acceptance Criteria:

  1. Botão "Gerar QR Code" adicionado em cada card de instância
  2. Função generateQRCode(instanceName) em /lib/evolutionapi.ts chama endpoint da EvolutionAPI
  3. Modal/Overlay exibe QR code retornado pela API
  4. Modal contém: QR code (imagem), instruções ("Escaneie com seu WhatsApp"), botão "Fechar"
  5. Botão é desabilitado se instância já está conectada
  6. Loading indicator exibido durante geração do QR code
  7. Erro de API exibe mensagem no modal: "Falha ao gerar QR code. Tente novamente"
  8. Modal é responsivo

Story 2.4: Implementar Desconexão de Instância WhatsApp

Como usuário, Eu quero desconectar minha instância WhatsApp, Para que eu possa trocar de conta ou resolver problemas de conexão.

Acceptance Criteria:

  1. Botão "Desconectar" adicionado em cada card de instância
  2. Função disconnectInstance(instanceName) em /lib/evolutionapi.ts chama endpoint da EvolutionAPI
  3. Confirmação exibida antes de desconectar: "Tem certeza que deseja desconectar?"
  4. Botão é visível apenas se instância está conectada
  5. Loading indicator exibido durante desconexão
  6. Após sucesso, status do card atualiza para "Disconnected"
  7. Mensagem de sucesso exibida: "Instância desconectada com sucesso"
  8. Erro de API exibe mensagem: "Falha ao desconectar. Tente novamente"
  9. Botões "Criar" e "Excluir" NÃO estão presentes (conforme FR7)

Epic 3: Google Calendar OAuth Integration

Objetivo: Permitir que usuários autorizem integração com Google Calendar através de OAuth gerenciado pelo n8n, exibindo status de conexão de forma clara. Epic completa funcionalidade de integrações do portal.

Story 3.1: Criar Card/Botão OAuth do Google Calendar

Como usuário, Eu quero ver um card/seção para Google Calendar com botão de autorização, Para que eu possa iniciar o processo de OAuth.

Acceptance Criteria:

  1. Componente GoogleCalendarCard.tsx criado
  2. Card exibido no dashboard abaixo/ao lado dos cards WhatsApp
  3. Card contém: Título "Google Calendar", Botão "Conectar Google Calendar"
  4. Botão redireciona para N8N_OAUTH_URL (variável de ambiente)
  5. Card usa tema escuro e cores azuis consistentes
  6. Card é responsivo

Story 3.2: Implementar Callback e Atualização de Status OAuth

Como usuário, Eu quero ser redirecionado de volta ao portal após autorizar Google Calendar, Para que eu veja confirmação de que a autorização foi bem-sucedida.

Acceptance Criteria:

  1. Rota de callback /app/auth/google/callback/page.tsx criada (se necessário para receber query params)
  2. Se n8n redireciona com ?success=true, exibir mensagem: "Google Calendar conectado com sucesso!"
  3. Status do card atualiza para "Conectado ✅"
  4. Tabela no schema portal (ex: portal.integrations) armazena status OAuth se aplicável
  5. Tratamento de erro se n8n retornar ?error=...

Story 3.3: Exibir Status de Conexão do Google Calendar

Como usuário, Eu quero ver se meu Google Calendar está conectado ou não, Para que eu saiba o status atual da integração.

Acceptance Criteria:

  1. Card Google Calendar exibe status badge: Verde "Conectado ✅" ou Cinza "Não conectado ❌"
  2. Se conectado, botão muda para "Reconectar" (permite trocar email OAuth)
  3. Status é carregado ao montar o componente (via Supabase ou lógica de verificação)
  4. Loading state exibido enquanto status carrega
  5. Usuário pode clicar "Reconectar" para re-autorizar com email diferente (conforme FR11)

7. Checklist Results Report

Executive Summary

Overall PRD Completeness: 85% ✅

MVP Scope Appropriateness: Just Right - Escopo minimalista adequado para POC com features essenciais bem priorizadas

Readiness for Architecture Phase: READY - O PRD está suficientemente completo para que o Architect possa iniciar o design técnico. Pequenos gaps não bloqueiam o progresso.

Most Critical Concerns:

  • Falta de seção explícita sobre "Future Enhancements" (out of scope para versões futuras)
  • NFRs de segurança e confiabilidade poderiam ser mais detalhados
  • Ausência de critérios específicos de validação do MVP

Category Analysis Table

Category Status Critical Issues
1. Problem Definition & Context PARTIAL Falta quantificação de impacto e user research formal
2. MVP Scope Definition PARTIAL Falta seção "Future Enhancements" e critérios de validação do MVP
3. User Experience Requirements PASS Fluxos de usuário implícitos mas não documentados explicitamente
4. Functional Requirements PASS Excelente - requirements claros, testáveis, e bem estruturados
5. Non-Functional Requirements PARTIAL Segurança, backup/recovery, e availability pouco detalhados
6. Epic & Story Structure PASS Epics e stories bem quebrados, sequenciais, com ACs claros
7. Technical Guidance PASS Direção técnica clara, constraints bem comunicados
8. Cross-Functional Requirements PARTIAL Falta deployment frequency e monitoring detalhado
9. Clarity & Communication PASS Documentação clara, estruturada, e versionada

Top Issues by Priority

BLOCKERS: Nenhum - PRD está pronto para arquitetura

HIGH:

  1. Adicionar seção "Future Enhancements" para clarificar o que fica fora do MVP
  2. Definir critérios específicos de validação do MVP (como saberemos que a POC foi bem-sucedida?)

MEDIUM: 3. Detalhar NFRs de segurança (HTTPS obrigatório, armazenamento seguro de API keys, etc.) 4. Documentar user flows explicitamente (login → dashboard → conectar WhatsApp) 5. Especificar requisitos de monitoring (logs, error tracking)

LOW: 6. Incluir quantificação de impacto do problema (ex: "clientes gastam 15min configurando manualmente") 7. Definir deployment frequency esperada (daily? weekly?)

MVP Scope Assessment

Scope Appropriate: ✅ O MVP está bem dimensionado para POC

Features bem priorizadas:

  • ✅ Auth básico sem registro público (admin cria usuários manualmente)
  • ✅ Cards de instâncias sem CRUD
  • ✅ OAuth delegado ao n8n (reduz complexidade)
  • ✅ 1 cliente inicialmente (valida conceito antes de escalar)

Possíveis cortes adicionais (se timeline apertar):

  • Recuperação de senha (admin pode resetar manualmente via Supabase)
  • Status auto-refresh (usuário pode recarregar página manualmente)

Features essenciais (não cortar):

  • Login/Auth
  • Visualização de instâncias e status
  • Gerar QR code
  • Botão OAuth Google Calendar

Complexity Concerns:

  • ⚠️ Integração com EvolutionAPI pode ter edge cases não previstos (rate limiting, timeouts)
  • ⚠️ Flow de OAuth via n8n pode ter problemas de redirect se não testado previamente

Timeline Realism: Muito realista para POC rápida. Com dev experiente em NextJS: 1-2 semanas

Technical Readiness

Clarity of Technical Constraints: ✅ Excelente

  • Stack bem definido (NextJS, Supabase, TailwindCSS)
  • Variáveis de ambiente documentadas
  • Architecture direction clara (Monolith)

Identified Technical Risks:

  1. EvolutionAPI availability/stability - Se API cair, portal fica inutilizável
  2. OAuth flow via n8n - Redirect de volta para portal precisa funcionar perfeitamente
  3. Supabase schema portal isolation - Garantir que não há conflito com schema public

Areas Needing Architect Investigation:

  1. EvolutionAPI endpoints específicos - Quais endpoints exatos para status, QR code, disconnect?
  2. Error handling strategy - Como tratar falhas de API (retry? timeout? user feedback?)
  3. Polling vs WebSockets - Status de instâncias deve usar polling ou real-time?
  4. Supabase RLS policies - Como garantir que usuários só veem suas próprias instâncias?

Recommendations

Immediate Actions (antes de passar para Architect):

  1. Adicionar seção "Out of Scope / Future Enhancements"

    ## Out of Scope (Future Enhancements)
- Registro público de usuários (admin gerencia usuários manualmente)
- Dashboard administrativo multi-tenant
- Criação/exclusão de instâncias WhatsApp via interface
- Gerenciamento avançado de Google Calendar (visualização de eventos, criação)
- Analytics e relatórios
- Histórico de conexões
- Notificações push/email

  2. Adicionar critérios de validação do MVP

    ## MVP Success Criteria
- ✅ Cliente consegue fazer login em <30s
- ✅ Cliente visualiza status de instâncias corretamente
- ✅ Cliente gera QR code e conecta WhatsApp em <2min
- ✅ Cliente autoriza Google Calendar via OAuth sem erros
- ✅ Zero configuração manual necessária (além de .env)

Improvements for Quality (opcional, mas recomendado):

  1. Adicionar user flow diagram (pode ser texto simples):

    1. Login → 2. Dashboard → 3a. Selecionar instância → 4a. Gerar QR / Desconectar
                         → 3b. Clicar OAuth → 4b. Autorizar Google → 5b. Retorno ao dashboard

  2. Detalhar NFRs de segurança:

    **NFR8:** Comunicação com EvolutionAPI e Supabase deve usar HTTPS
**NFR9:** API keys armazenadas apenas em variáveis de ambiente (nunca hardcoded)
**NFR10:** Tokens OAuth armazenados de forma criptografada no Supabase

Next Steps:

  1. ✅ Revisar e incorporar recommendations acima (opcional, mas melhora qualidade)
  2. ✅ Passar PRD para Architect para design técnico detalhado
  3. ✅ Architect deve investigar endpoints específicos da EvolutionAPI
  4. ✅ Architect deve definir error handling strategy e RLS policies do Supabase

Final Decision

✅ READY FOR ARCHITECT

O PRD está suficientemente completo, bem estruturado, e fornece direção clara para o Architect iniciar o design técnico. Os gaps identificados são menores e não bloqueiam o progresso. Recomenda-se incorporar as melhorias sugeridas, mas não é obrigatório para prosseguir.

Pontos Fortes do PRD:

  • Functional requirements excelentes e testáveis
  • Epic/Story breakdown apropriado para AI agents
  • Technical assumptions claras
  • Escopo MVP bem dimensionado

Áreas de Atenção para o Architect:

  • Investigar endpoints EvolutionAPI
  • Definir error handling robusto
  • Planejar Supabase RLS policies
  • Considerar polling vs real-time para status

8. Next Steps

UX Expert Prompt

Crie design detalhado da interface do AutomatizaSE Portal baseado no PRD em docs/prd.md.

Foco em:
- Tema escuro com cores azuis (AutomatizaSE branding)
- Cards de instâncias WhatsApp (referência: interface EvolutionAPI)
- Layout responsivo mobile-first
- Fluxos: Login → Dashboard → Ações (QR code, OAuth)

Entregáveis: Wireframes, componentes UI, guia de estilos, protótipo navegável (Figma/similar).

Architect Prompt

Crie arquitetura técnica detalhada para o AutomatizaSE Portal baseado no PRD em docs/prd.md.

Requisitos críticos:
- NextJS 14+ (App Router) + Supabase (schema 'portal')
- Integração direta com EvolutionAPI (investigar endpoints: status, QR code, disconnect)
- OAuth Google Calendar via n8n (redirect flow)
- Error handling robusto e RLS policies do Supabase

Entregáveis: Arquitetura de componentes, estrutura de pastas, estratégia de estado, error handling, diagramas de sequência, decisões técnicas documentadas.