convite-rael/openspec-poc-convite-aniversario.md

OpenSpec — Contexto e Diretrizes da POC do Convite de Aniversário

1. Objetivo

Construir uma POC (Proof of Concept) de um convite digital de aniversário de 1 ano utilizando Next.js.

A POC deve validar a experiência visual e funcional do convite antes da implementação da infraestrutura completa de RSVP, banco de dados, autenticação administrativa, automações e integração com WhatsApp.

O resultado deve parecer próximo de um produto real para permitir apresentação e aprovação da próxima fase.

2. Contexto

O produto final será uma plataforma de convites digitais personalizados.

Cada família/convidado poderá receber um link exclusivo, por exemplo:

https://convite.exemplo.com/r/AbC123xyz

O convite poderá conter:

• nome do aniversariante;
• idade;
• data;
• horário;
• local;
• tema visual;
• mensagem personalizada;
• lista de convidados daquele convite;
• confirmação de presença.

A POC não precisa implementar o backend definitivo.

3. Escopo da POC

Deve possuir

• Next.js;
• React;
• TypeScript;
• Tailwind CSS;
• página inicial;
• página /r/[token];
• dados mockados em TypeScript/JSON;
• convite personalizado;
• lista de convidados;
• RSVP funcionando no frontend;
• feedback de confirmação;
• layout mobile-first;
• tema Safari.

Exemplo de dados:

{
  token: "abc123",
  event: {
    name: "1º Aniversário do Arthur",
    date: "15 de novembro de 2026",
    time: "16:00",
    venue: "Espaço Festa",
    address: "Belo Horizonte - MG"
  },
  invitation: {
    displayName: "Família Silva"
  },
  guests: [
    { id: "1", name: "João", type: "adult", status: "pending" },
    { id: "2", name: "Maria", type: "adult", status: "pending" },
    { id: "3", name: "Pedro", type: "child", status: "pending" }
  ]
}

4. RSVP

O usuário deve conseguir:

• confirmar um convidado;
• recusar um convidado;
• alterar a seleção antes do envio;
• confirmar presença;
• visualizar uma mensagem de sucesso.

Na POC não é obrigatório PostgreSQL.

Pode usar React state ou localStorage.

A interface deve ser preparada para futuramente substituir o mock por uma API.

5. Fluxo

WhatsApp
   ↓
abre link personalizado
   ↓
convite
   ↓
dados da festa
   ↓
lista de convidados
   ↓
seleção de presença
   ↓
confirmar
   ↓
mensagem de sucesso

6. Design

Tema inicial: Safari / animais da selva.

Elementos possíveis:

• leão;
• elefante;
• girafa;
• folhas;
• árvores;
• animais infantis;
• natureza;
• ilustrações infantis.

A aparência deve ser:

• infantil;
• elegante;
• alegre;
• moderna;
• adequada para aniversário de 1 ano.

Evitar aparência genérica de formulário.

7. Responsividade

Mobile-first é obrigatório.

Principal cenário:

WhatsApp → Android/iPhone → Browser → Convite

Também deve funcionar em tablet e desktop.

8. Arquitetura da POC

Next.js
│
├── páginas
├── componentes
├── dados mockados
└── camada de domínio

O acesso aos dados deve ser centralizado, permitindo futuramente:

Mock → API → PostgreSQL

Evitar espalhar dados mockados pelos componentes.

9. Estrutura sugerida

app/
├── page.tsx
├── r/
│   └── [token]/
│       └── page.tsx
└── globals.css

components/
├── invitation/
│   ├── InvitationHero.tsx
│   ├── EventDetails.tsx
│   ├── GuestList.tsx
│   ├── RsvpSelector.tsx
│   ├── ConfirmationSuccess.tsx
│   └── InvitationFooter.tsx
└── ui/

data/
└── invitations.ts

types/
└── invitation.ts

lib/
└── invitation.ts

public/
└── images/

A estrutura pode ser alterada se o OpenSpec encontrar uma organização melhor.

10. Modelo de domínio

Criar tipos explícitos.

export type GuestType = "adult" | "child";

export type RsvpStatus =
  | "pending"
  | "confirmed"
  | "declined";

export interface Guest {
  id: string;
  name: string;
  type: GuestType;
  status: RsvpStatus;
}

export interface InvitationEvent {
  name: string;
  date: string;
  time: string;
  venue: string;
  address: string;
}

export interface Invitation {
  token: string;
  event: InvitationEvent;
  displayName: string;
  guests: Guest[];
}

11. Requisitos funcionais

RF01 — Acessar convite

Permitir acessar:

/r/[token]

RF02 — Personalização

Apresentar o nome do grupo/convidado.

Exemplo:

Família Silva, esperamos vocês!

RF03 — Dados do evento

Exibir:

• nome;
• data;
• horário;
• local;
• endereço.

RF04 — Lista de convidados

Exibir todos os convidados associados.

RF05 — Seleção

Permitir:

• presente;
• não presente.

RF06 — Confirmação

Validar que existe pelo menos uma resposta.

Após confirmar:

• mostrar feedback;
• impedir envio duplicado enquanto processa;
• mostrar resumo das respostas.

RF07 — Estado

Na POC o estado pode ficar no cliente.

12. Requisitos não funcionais

RNF01 — Responsividade

Mobile-first.

RNF02 — Performance

Evitar bibliotecas pesadas sem necessidade.

RNF03 — Acessibilidade

Utilizar:

• HTML semântico;
• labels;
• foco visível;
• contraste adequado;
• botões reais;
• navegação por teclado.

RNF04 — Componentização

Evitar uma única página gigante.

RNF05 — Manutenibilidade

Separar regras de negócio da apresentação sempre que fizer sentido.

13. Fora do escopo da POC

Não implementar ainda:

• PostgreSQL;
• Prisma;
• autenticação administrativa;
• Cloudflare Access;
• Cloudflare Tunnel;
• Nginx Proxy Manager;
• n8n;
• WhatsApp API;
• envio automático;
• geração de PDF;
• QR Code obrigatório;
• painel administrativo;
• analytics;
• cadastro real de convidados;
• upload administrativo;
• LGPD completa;
• sistema multi-evento.

14. Preparação para evolução

Manter a separação:

UI
 ↓
Domain / Model
 ↓
Data Source

Criar, por exemplo:

getInvitationByToken(token)

Na POC:

return mockInvitations.find(...)

Futuramente:

getInvitationByToken()
        ↓
API
        ↓
PostgreSQL

15. Token

Na POC pode ser estático e sem segurança definitiva.

No produto final:

randomBytes()
       ↓
token público
       ↓
SHA-256
       ↓
tokenHash no banco

Não antecipar segurança complexa na POC.

16. Critérios de aprovação

A POC estará aprovada quando for possível demonstrar:

Cenário 1

Abrir /r/abc123 e visualizar um convite completo.

Cenário 2

Abrir /r/xyz789 e visualizar dados diferentes.

Cenário 3

Selecionar:

João  → Confirmado
Maria → Confirmado
Pedro → Recusado

e enviar.

Cenário 4

Visualizar mensagem final com as respostas.

Cenário 5

Executar o fluxo corretamente em celular.

17. Critérios visuais

• primeira impressão de convite real;
• tema Safari consistente;
• boa hierarquia visual;
• animações discretas;
• textos legíveis;
• botões claros;
• RSVP intuitivo;
• boa experiência mobile;
• sem aparência de formulário administrativo;
• carregamento rápido.

18. Diretriz para o OpenSpec

Trabalhar em ciclos:

PROPOSE
   ↓
REVIEW
   ↓
APPLY
   ↓
VERIFY

Antes do APPLY, verificar:

1. atende à POC;
2. não adiciona complexidade desnecessária;
3. não antecipa funcionalidades da fase 2;
4. contempla mobile;
5. permite substituir mock por API;
6. design adequado para aniversário;
7. componentes com responsabilidades claras.

19. Regra principal

Não implementar funcionalidades futuras apenas porque são tecnicamente interessantes.

Exemplo: não adicionar PostgreSQL apenas porque ele será utilizado na versão final.

A pergunta da POC é:

Este convite é suficientemente bom para obter aprovação?

Somente depois da aprovação:

POC aprovada
     ↓
API
     ↓
PostgreSQL
     ↓
tokens reais
     ↓
admin
     ↓
Cloudflare
     ↓
automação

20. Fases planejadas

Fase 1 — POC visual

Next.js
React
TypeScript
Tailwind
Mock

Objetivo: aprovação do convite.

Fase 2 — Backend

Next.js API
PostgreSQL
Prisma

Objetivo: dados reais e RSVP persistente.

Fase 3 — Infraestrutura

Cloudflare Tunnel
Cloudflare Access
Rate limiting
Backups

Objetivo: publicação segura.

Fase 4 — Administração

/admin

Objetivo: gerenciar eventos, famílias e convidados.

Fase 5 — Automação

n8n
WhatsApp
lembretes

Objetivo: automatizar comunicação.

21. Visão futura

                         WhatsApp
                            │
                            ▼
                     convite.n1b3.com.br
                            │
                            ▼
                      Cloudflare
                            │
                            ▼
                    Cloudflare Tunnel
                            │
                            ▼
                       Next.js
                    ┌───────┴────────┐
                    │                │
                  Web               API
                    │                │
                    └───────┬────────┘
                            │
                         Prisma
                            │
                            ▼
                       PostgreSQL
                            │
                ┌───────────┴───────────┐
                │                       │
             RSVP                    Admin
                │                       │
                └───────────┬───────────┘
                            │
                           n8n
                            │
                    ┌───────┼────────┐
                    │       │        │
                 WhatsApp  Email   Outros

22. Princípio central

A POC deve ser:

pequena no escopo, mas com aparência de produto real.

O objetivo imediato é validar:

DESIGN
   +
EXPERIÊNCIA
   +
RSVP
   +
PERSONALIZAÇÃO

A infraestrutura definitiva pode esperar.

23. Resultado esperado

Ao final da POC deverá existir uma aplicação Next.js executável localmente com:

/
└── apresentação

/r/abc123
└── convite personalizado

/r/xyz789
└── outro convite personalizado

Fluxo:

abrir convite
      ↓
visualizar
      ↓
selecionar convidados
      ↓
confirmar
      ↓
feedback de sucesso

24. Decisão arquitetural registrada

POC = Next.js + React + TypeScript + Tailwind + dados mockados.

Backend, PostgreSQL, Prisma, Cloudflare, autenticação, n8n e WhatsApp ficam fora do escopo da POC.

A POC deve permitir a substituição futura do mock por uma API sem refatoração completa da interface.