Convidados acessam o convite pelo link /r/<token> e confirmam a presença de cada pessoa. Ao colar o link no WhatsApp aparece um card com o tema, o nome da festa e a data.
Organizador acessa /admin com senha e:
- cadastra eventos e convites e escolhe o tema visual de cada evento;
- compartilha os links (copiar link, copiar mensagem / WhatsApp);
- acompanha as respostas e exporta a lista de convidados em CSV.
PDFs dos convites: o organizador envia um PDF modelo por evento e o sistema gera um PDF por convite, trocando o link do modelo pelo link /r/<token> de cada família. A geração pode ser individual ou em lote, com progresso.

Stack: Next.js 16 (App Router) · React 19 · TypeScript · Tailwind CSS 4 · PostgreSQL 17 · Drizzle ORM · Python 3.13 + FastAPI + PyMuPDF (serviço de PDFs) · Docker Compose

Documentação

Documento	Para quem	Conteúdo
README.md (este)	Quem desenvolve e mantém o código	Arquitetura, código, banco, desenvolvimento local, como validar mudanças e manutenção do serviço Python
instrucoes.md	Administrador do sistema (quem faz o deploy)	Deploy, variáveis de ambiente, operação, backup, solução de problemas e histórico de versões
MANUAL-USUARIO.md	Organizador da festa (sem conhecimento técnico)	Criar eventos e convites, enviar, acompanhar respostas, CSV, PDFs, experiência do convidado e perguntas frequentes

Cada documento fala com um público. Para deploy, variáveis de ambiente, backup ou erros no servidor, vá direto ao instrucoes.md. Para usar o sistema, vá ao MANUAL-USUARIO.md.

Os problemas mais comuns aparecem nos dois arquivos, de propósito, cada um para o seu público:

instrucoes.md (seção 11): causa técnica e solução no servidor;
MANUAL-USUARIO.md (seção 5): o que o organizador faz e quando chamar o administrador.

Ao mudar um deles, confira o outro.

Arquitetura

Três containers no Docker Compose:

Navegador ──► Cloudflare (HTTPS) ──► app (Next.js :3000) ──► db (PostgreSQL)    volume pgdata
                                          │
                                          │ HTTP interno (http://pdf-service:8000)
                                          ▼
                                     pdf-service (Python)
                                          │
              volume app-storage ◄────────┴── /storage nos dois containers (PDFs)

Serviço	Origem	Papel
`app`	`Dockerfile` (Next standalone)	Páginas, área do organizador, RSVP, rotas de download. Aplica as migrations ao subir
`db`	`postgres:17-alpine`	Banco de dados. Sem porta publicada
`pdf-service`	`pdf-service/Dockerfile`	Personaliza os PDFs. Sem porta publicada: só o `app` o acessa

Os dois containers que gravam arquivos (app e pdf-service) rodam com o mesmo uid/gid 1001, para compartilhar o volume app-storage sem erro de permissão.

Estrutura do código

src/
  app/
    page.tsx                     Página inicial pública (neutra)
    layout.tsx                   Layout raiz; metadataBase vem do APP_URL
    r/[token]/                   Convite: página, loading, not-found, opengraph-image (card do WhatsApp) e Server Action do RSVP
    admin/login/                 Login do organizador
    admin/(painel)/              Área do organizador (layout protegido por sessão)
      page.tsx                   Lista de eventos
      eventos/novo/              Criar evento
      eventos/[id]/              Página do evento, editar, novo convite
      eventos/[id]/exportar/     Rota GET do CSV
      eventos/[id]/pdf/          Rotas GET de status dos PDFs e download do modelo
      eventos/[id]/convites/[conviteId]/pdf/   Rota GET de download do PDF do convite
      convites/[id]/editar/      Editar convite
    admin/actions.ts             Server Actions de eventos e convites
    admin/auth-actions.ts        Server Actions de login, sair e sair de todos
    admin/pdf-actions.ts         Server Actions de PDF (upload do modelo, geração individual e em lote)
  components/
    invitation/                  Componentes do convite (hero, detalhes, lista, RSVP, sucesso, rodapé)
    admin/                       Formulários e componentes do organizador (EventPdf.tsx: tela dos PDFs;
                                 WhatsAppMessageField.tsx: campo e prévia da mensagem do WhatsApp)
    ui/                          Button, Card e Input (tone "theme" = cores do tema; "neutral" = admin)
  db/
    schema.ts                    Tabelas (ver "Banco de dados")
    index.ts                     Pool de conexão com o Postgres
    seed.ts                      Dados de exemplo (convites abc123 e xyz789)
  lib/
    auth.ts                      Sessão do organizador (token aleatório, hash guardado no banco)
    login-rate-limit.ts          Limite de tentativas de login por IP (em memória)
    themes.ts                    Paletas, selos e ícones dos 15 temas
    rsvp.ts                      Regras do prazo de confirmação
    app-url.ts                   Endereço público do app (APP_URL)
    invitation.ts                Consultas do convite público
    organizer.ts                 Consultas da área do organizador e totais de presença
    slugify.ts                   Nomes de arquivo para download
    whatsapp-message.ts          Mensagem do botão WhatsApp: padrão, variáveis, limites e montagem do texto/link
    pdf/                         storage.ts (arquivos), service.ts (cliente do pdf-service), jobs.ts (fila), state.ts (status), types.ts
  types/invitation.ts            Tipos compartilhados do convite
  instrumentation.ts             Na subida do app, encerra gerações de PDF interrompidas
drizzle/                         Migrations SQL geradas pelo drizzle-kit
scripts/migrate.ts               Aplica as migrations (empacotado com esbuild e executado no container)
pdf-service/                     Serviço Python de PDFs (FastAPI + PyMuPDF), com Dockerfile próprio
Dockerfile                       Imagem de produção do app (Next standalone)
compose.yml                      app + db + pdf-service

Banco de dados

Definido em src/db/schema.ts. As migrations ficam em drizzle/ e são aplicadas automaticamente quando o container app sobe.

`events`: festas

Coluna	Tipo	Significado
`id`	uuid	Chave
`name`, `venue`, `address`	text	Nome da festa, local e endereço
`date` / `time`	date / time	Data e horário
`rsvp_deadline`	date, opcional	Último dia para responder (ver Prazo de confirmação)
`theme`	text	Id do tema em `src/lib/themes.ts` (padrão `safari`, só para eventos antigos)
`badge_text` / `footer_text`	text, opcionais	Textos do selo (até 40) e do rodapé (até 120). Vazios usam o padrão do tema
`whatsapp_message`	text, opcional	Modelo da mensagem do botão WhatsApp, com variáveis (`{nome}`, `{link}`...). Vazio usa a mensagem padrão. Ver Mensagem do WhatsApp
`pdf_template_version`	integer	Versão do PDF modelo. `0` = sem modelo; sobe 1 a cada upload
`pdf_template_name` / `pdf_template_updated_at`	text / timestamptz	Nome original e data do modelo atual (só para exibição)
`created_at`	timestamptz	Criação

`invitations`: um convite (link) por família

Coluna	Tipo	Significado
`id`	uuid	Chave
`event_id`	uuid	Evento (apagado em cascata com ele)
`token`	text, único	Código do link `/r/<token>`: 6 bytes aleatórios em base64url (8 caracteres)
`display_name`	text	Nome exibido ("Família Silva")
`responded_at`	timestamptz	Último envio de resposta pela família
`blocked`	boolean, padrão `false`	Bloqueio individual: encerra as respostas deste convite (ver Prazo de confirmação)
`pdf_status`	enum	`not_generated`, `generating`, `generated` ou `error`
`pdf_template_version`	integer	Versão do modelo usada na última geração bem-sucedida
`pdf_generated_at`	timestamptz	Data da última geração bem-sucedida (não nulo = existe arquivo para baixar)
`pdf_error`	text	Última mensagem de erro de geração
`created_at`	timestamptz	Criação

`guests`: pessoas de cada convite

Coluna	Tipo	Significado
`id`	uuid	Chave (mantida ao editar o convite, para preservar a resposta)
`invitation_id`	uuid	Convite (apagado em cascata)
`name`	text	Nome
`type`	enum `guest_type`	`adult`, `teen` ou `child`
`status`	enum `rsvp_status`	`pending`, `confirmed` ou `declined` (valor gravado; ver prazo)
`sort_order`	integer	Ordem na lista
`responded_at`	timestamptz	Quando a pessoa foi respondida

`organizer_sessions`: sessões do `/admin`

Coluna	Significado
`id`	Hash SHA-256 do token do cookie (o token em si nunca é gravado)
`user_agent`	Navegador que fez o login
`created_at` / `expires_at`	Criação e validade (7 dias)

`pdf_jobs`: lotes de geração de PDF

Coluna	Significado
`event_id`	Evento (apagado em cascata)
`status`	`running`, `finished` ou `interrupted`. Índice único parcial: um `running` por evento
`invitation_ids`	jsonb com os convites do lote, na ordem de processamento
`total` / `processed` / `failed`	Contadores do progresso
`created_at` / `finished_at`	Início e fim

Para mudar o banco: altere schema.ts, rode npm run db:generate e confira o SQL gerado em drizzle/.

Como o código funciona

Autenticação do organizador

Senha única: ORGANIZER_PASSWORD, comparada via HMAC com SESSION_SECRET em src/lib/auth.ts (o tempo da comparação não depende da senha).
Sessão: o login cria um token aleatório de 32 bytes no cookie organizer_session (httpOnly, sameSite=lax, secure conforme COOKIE_SECURE). Só o hash vai para organizer_sessions.
- Sair apaga a linha da sessão atual; Sair de todos apaga todas.
- Sessões vencidas são limpas a cada login.
Proteção: requireOrganizer() deve ser chamado em toda página, Server Action e rota da área do organizador. O layout (painel) já chama, mas rotas (route.ts) e Server Actions não passam pelo layout e precisam chamar por conta própria. A rota de status dos PDFs usa isOrganizer() para responder 401 em JSON em vez de redirecionar.
Limite de tentativas (src/lib/login-rate-limit.ts): 5 erros em 15 min bloqueiam o IP por 15 min.
- Os contadores ficam em memória e zeram quando o app reinicia.
- O IP vem de cf-connecting-ip, depois x-forwarded-for e x-real-ip. Esses cabeçalhos só são confiáveis se o servidor aceitar apenas tráfego do Cloudflare.

Convite público e RSVP

src/app/r/[token]/page.tsx sempre renderiza na hora (connection()): o convite muda com respostas e edições.
InvitationView (client) guarda as marcações; o botão marcado fica desativado, então não há "desmarcar".
submitRsvp (src/app/r/[token]/actions.ts) é chamável por POST direto, por isso revalida tudo no servidor:
- token válido;
- prazo aberto;
- todos os guestId pertencem ao convite.
Grava só as pessoas enviadas (confirmed/declined) e atualiza responded_at.
opengraph-image.tsx gera a imagem 1200×630 do card. As URLs absolutas do card usam metadataBase, que vem do APP_URL (src/lib/app-url.ts).
Copiar link, Copiar mensagem e WhatsApp usam window.location.origin, ou seja, o endereço pelo qual o organizador está navegando, e não o APP_URL.

Mensagem do WhatsApp

src/lib/whatsapp-message.ts concentra as regras; é um módulo puro, usado no servidor e no navegador.

Modelo por evento: a coluna events.whatsapp_message guarda o modelo. Vazia, vale DEFAULT_WHATSAPP_MESSAGE. Não há mensagem por convite, por decisão de produto: para um caso especial, o organizador edita o texto no próprio WhatsApp.
Montagem (renderWhatsAppMessage):
- troca {nome}, {evento}, {data}, {hora}, {local}, {endereco}, {icone} e {link};
- chaves desconhecidas ficam como estão;
- sem {link} no modelo, o link é acrescentado numa linha no final.
Envio: ShareInvitation monta o texto com os dados do convite. Copiar mensagem copia esse texto; WhatsApp abre whatsappShareUrl(text) (https://wa.me/?text=<texto codificado>). A formatação do WhatsApp (*negrito*, _itálico_...) passa como texto puro e o próprio app aplica.

Limites (só para a mensagem personalizada):

Constante	Valor	O que limita
`WHATSAPP_MESSAGE_MAX`	950	Caracteres do modelo e do texto final, com as variáveis trocadas
`WHATSAPP_URL_MAX`	2300	Tamanho do link codificado do `wa.me`. Acentos ocupam 6 caracteres e emojis até 12

O WhatsApp não publica um limite oficial: os valores são margens de segurança.

Conferência no servidor (src/app/admin/actions.ts, funções measureWhatsAppMessage e whatsappLimitError):
- ao criar o evento, com os dados do evento e {nome} vazio;
- ao editar o evento, com o nome de cada convite existente;
- ao criar ou editar um convite, com o nome informado.
Nas três, o link é estimado com getAppUrl().origin mais um código de 8 caracteres (sampleInviteLink). Como o botão usa a origem do navegador, o tamanho real pode variar alguns caracteres.
Formulário (WhatsAppMessageField.tsx):
- botões que inserem as variáveis no cursor;
- três contadores: modelo, texto final e link, calculados com dados de exemplo;
- prévia em balão que imita a formatação do WhatsApp.
A expressão regular da prévia usa lookbehind (ES2018, Safari ≥ 16.4) e é criada dentro de try. Sem suporte, a prévia sai sem formatação, em vez de quebrar o formulário.

Prazo de confirmação

src/lib/rsvp.ts:

isRsvpClosed(deadline): o prazo vale até o fim do dia informado, no fuso America/Sao_Paulo.
effectiveStatus(status, closed): depois do prazo, pending é exibido como declined.

O banco não é alterado. Todas as telas e o CSV usam effectiveStatus, então adiar ou apagar o prazo reverte a exibição.

Bloqueio individual: invitations.blocked tem o mesmo efeito do prazo vencido, mas só naquele convite (setInvitationBlocked em src/app/admin/actions.ts). Se só o bloqueio encerrou o convite, a mensagem do convidado sai sem a data; com o prazo também vencido, ela mostra a data.

Temas

src/lib/themes.ts define os 15 temas (paleta, selo, ícones). Os componentes do convite usam classes amber-* do Tailwind, e themeStyle() redefine as variáveis --color-amber-* no contêiner. Assim, trocar o tema troca a paleta inteira sem mexer nos componentes. Para criar um tema, acrescente um objeto ao array themes.

Exportação CSV

GET /admin/eventos/<id>/exportar?status=confirmed|declined|pending (exportar/route.ts):

separador ; com BOM UTF-8, para o Excel em português abrir certo;
valores que começam com = + - @ ganham um apóstrofo, para não virarem fórmula.

PDFs dos convites

Navegador ──► app: valida login, evento e convite
                │  HTTP interno: { event_id, invitation_id, token, template_version }
                ▼
           pdf-service: abre  /storage/events/<evento>/template/modelo-v<versão>.pdf
                        troca os links que contêm INVITE_LINK_PATTERN por <INVITE_LINK_BASE_URL ou APP_URL>/r/<token>
                        grava /storage/events/<evento>/generated/<convite>.pdf

Armazenamento (src/lib/pdf/storage.ts e pdf-service/app/main.py, com a mesma estrutura):

/storage/events/<eventId>/template/modelo-v<versão>.pdf     PDF modelo (só a versão atual fica no disco)
/storage/events/<eventId>/generated/<invitationId>.pdf      PDF personalizado de cada convite

Os caminhos são montados só a partir de ids validados. Nada vindo do navegador vira caminho.

Upload (uploadPdfTemplate):
1. Confere extensão, tamanho (10 MB, PDF_TEMPLATE_MAX_MB em src/lib/pdf/types.ts) e a assinatura %PDF-.
2. Grava modelo-v<n+1>.pdf e chama /templates/inspect; sem link de convite, apaga o arquivo e recusa.
3. Atualiza a versão com condição na versão anterior, para que dois uploads simultâneos não se sobrescrevam.
4. Apaga os modelos antigos.
O limite de corpo das Server Actions é 11mb em next.config.ts e deve acompanhar PDF_TEMPLATE_MAX_MB.
Versão: um PDF com pdf_template_version diferente da do evento é exibido como outdated ("Modelo atualizado — gerar novamente"), calculado em pdfViewStatus (src/lib/pdf/state.ts).
Geração individual (generateInvitationPdfAction):
1. claimInvitation marca o convite como generating só se ele for do evento e ainda não estiver em geração. Isso impede duplicidade.
2. generateForInvitation chama o serviço e grava o resultado. Em caso de erro, mantém pdf_generated_at e o arquivo anterior.
Lote (startPdfBatch → createPdfJob → enqueuePdfJob → runPdfJob, em src/lib/pdf/jobs.ts):
- cria a linha em pdf_jobs, marca os convites e processa um por vez em segundo plano, no próprio processo do Next;
- uma falha não interrompe o lote;
- para trocar por Redis/BullMQ, substitua enqueuePdfJob() por um produtor da fila e chame runPdfJob() no worker.
Reinício: src/instrumentation.ts chama recoverInterruptedPdfWork() na subida. Lotes running viram interrupted e convites generating viram error.
Tela (src/components/admin/EventPdf.tsx): EventPdfProvider guarda o estado e consulta GET .../pdf/status a cada 1,5 s enquanto há geração. A página recria o provider (key) quando a versão do modelo muda.
Exclusão: excluir convite ou evento apaga os arquivos correspondentes (src/app/admin/actions.ts).

Endpoints:

Operação	Tipo	Endereço / função
Upload do PDF modelo	Server Action	`uploadPdfTemplate(eventId, prev, formData)`
Gerar PDF de um convite	Server Action	`generateInvitationPdfAction(eventId, invitationId)`
Gerar PDFs em lote	Server Action	`startPdfBatch(eventId, "all" \| "pending")`
Status da geração	GET	`/admin/eventos/<id>/pdf/status` (JSON; 401 sem sessão)
Download do modelo	GET	`/admin/eventos/<id>/pdf/modelo`
Download do PDF do convite	GET	`/admin/eventos/<id>/convites/<conviteId>/pdf` (confere se o convite é do evento)
pdf-service	GET / POST	`/health`, `/templates/inspect`, `/invitations/generate` (ver Manutenção do pdf-service)

Variáveis de ambiente

A lista completa, com exemplos, está na seção 4 do instrucoes.md. Para desenvolvimento, as que importam fora do Docker são:

Variável	Uso no desenvolvimento
`DATABASE_URL`	Conexão com o Postgres local (`npm run dev`, `db:migrate`, `db:seed`)
`PDF_SERVICE_URL`	`http://localhost:8000` quando o pdf-service roda na sua máquina (padrão `http://pdf-service:8000`)
`STORAGE_DIR`	Pasta dos PDFs; padrão `./storage` (está no `.gitignore`). O pdf-service local precisa apontar para a mesma pasta
`COOKIE_SECURE`	`false` para `http://localhost`

Desenvolvimento local

Requer Node.js 20.9+ e um Postgres acessível. Pode ser só o serviço db do compose, liberando a porta 127.0.0.1:5432 no compose.yml.

npm install
cp .env.example .env      # ajuste DATABASE_URL
npm run db:migrate        # cria as tabelas
npm run db:seed           # opcional: convites de exemplo
npm run dev

Acesse http://localhost:3000. Para abrir pela rede local (ex.: celular), o IP precisa estar em allowedDevOrigins no next.config.ts; sem isso, a página fica em branco.

pdf-service local

Para gerar PDFs no npm run dev, rode o serviço Python apontando para a mesma pasta de armazenamento do app (Python 3.11+):

cd pdf-service
python -m venv .venv
.venv/bin/pip install -r requirements.txt        # Windows: .venv\Scripts\pip
STORAGE_DIR=../storage APP_URL=http://localhost:3000 .venv/bin/uvicorn app.main:app --port 8000 --reload

No .env do app, descomente PDF_SERVICE_URL=http://localhost:8000 e STORAGE_DIR=./storage.

Outra opção é subir só ele pelo compose, liberando a porta temporariamente (ports: ["127.0.0.1:8000:8000"]) e montando ./storage em /storage.

Scripts

Script	O que faz
`npm run dev`	Servidor de desenvolvimento
`npm run build`	Build de produção (Next standalone)
`npm run lint`	ESLint
`npx tsc --noEmit`	Checagem de tipos
`npm run db:generate`	Gera uma nova migration após alterar `src/db/schema.ts`
`npm run db:migrate`	Aplica as migrations no banco do `DATABASE_URL`
`npm run db:seed`	Cria os convites de exemplo (`abc123`, `xyz789`)
`npm run db:studio`	Abre o Drizzle Studio para ver e editar os dados
`npm run build:migrate`	Empacota `scripts/migrate.ts` em `dist/migrate.js` (usado no Dockerfile)

O seed não faz parte da imagem Docker. Para rodá-lo contra o banco do compose, libere a porta do Postgres em 127.0.0.1:5432 no compose.yml e rode npm run db:seed na máquina com o código.

Next.js 16

Esta versão tem mudanças em relação às anteriores. Antes de usar uma API do Next, consulte a documentação instalada em node_modules/next/dist/docs/ (ver AGENTS.md).

Como validar uma mudança

O projeto não tem testes automatizados. Antes de publicar, siga esta ordem:

Tipos e estilo: npx tsc --noEmit e npm run lint (os dois devem terminar sem erros).
Build: npm run build. Se mexeu em pdf-service/, rode também docker compose build pdf-service.
Migrations: se alterou o schema.ts, confira o SQL novo em drizzle/ e aplique num banco de teste (npm run db:migrate).
Teste manual do que mudou. Roteiro mínimo:
- login e logout no /admin;
- criar evento e convite, abrir o link, responder e ver a resposta na página do evento;
- se o evento tiver prazo: conferir a exibição antes e depois dele;
- exportar um CSV;
- WhatsApp: personalizar a mensagem do evento, conferir a prévia e os contadores, clicar em WhatsApp num convite e conferir texto, formatação e link;
- PDFs: enviar o modelo, gerar um convite, baixar e clicar no link, gerar em lote.
Documentação:
- comportamento visível para o organizador ou o convidado → atualize o MANUAL-USUARIO.md, sem termos técnicos;
- variável nova, deploy ou operação do servidor → atualize o instrucoes.md;
- código, banco ou arquitetura → atualize este README;
- mudança publicada → acrescente uma versão na Parte 2 (Histórico de alterações) do instrucoes.md.

Manutenção do `pdf-service` (código Python)

Para quem precisa alterar o serviço Python: mudar a regra de troca do link, atualizar bibliotecas, depurar um erro, etc.

Arquivos

pdf-service/
  Dockerfile          Imagem Python 3.13-slim; roda como uid/gid 1001 (o mesmo do app)
  requirements.txt    Dependências: fastapi, uvicorn, pymupdf
  .dockerignore
  app/
    __init__.py
    main.py           Todo o serviço: endpoints, caminhos e a troca do link

Do lado do Next, os arquivos que "conversam" com o serviço são:

Arquivo	Papel
`src/lib/pdf/service.ts`	Cliente HTTP: monta as chamadas a `/templates/inspect` e `/invitations/generate`, com timeout de 60 s (`GENERATE_TIMEOUT_MS`)
`src/lib/pdf/storage.ts`	Mesma estrutura de pastas usada pelo Python (o app grava o modelo; o Python grava os gerados)
`src/lib/pdf/jobs.ts`	Chama a geração para um convite e para os lotes; grava status e erro no banco
`src/app/admin/pdf-actions.ts`	Upload do modelo: salva o arquivo e chama `/templates/inspect` para validar

⚠️ Regra de ouro: o contrato entre os dois lados (endpoints, campos JSON e estrutura de pastas) existe nos dois códigos. Se mudar de um lado, mude do outro e publique os dois juntos.

Como o `main.py` funciona

Configuração (lida na subida do serviço):

Variável	Padrão	Uso no código
`STORAGE_DIR`	`/storage`	Raiz dos arquivos (`STORAGE_DIR`)
`INVITE_LINK_BASE_URL`	vazio	Base do link novo (`LINK_BASE_URL`). Vazio → usa `APP_URL`
`APP_URL`	vazio	Usado como base do link quando `INVITE_LINK_BASE_URL` está vazio. Os dois vazios → a geração responde erro 500
`INVITE_LINK_PATTERN`	`com.br/r/`	Trecho que identifica o link a trocar (`LINK_PATTERN`)

Alterar uma variável não exige rebuild: edite o .env e rode docker compose up -d pdf-service.

Funções principais:

Função	O que faz
`_template_path(event_id, version)`	Monta `/storage/events/<evento>/template/modelo-v<versão>.pdf`
`_generated_path(event_id, invitation_id)`	Monta `/storage/events/<evento>/generated/<convite>.pdf`
`_inside_storage(path)`	Garante que o caminho final está dentro de `STORAGE_DIR` (proteção contra path traversal)
`_is_invite_link(link)`	Regra que decide se um link é o do convite: `LINK_PATTERN in uri`
`_open_template(path)`	Abre o modelo; 404 se não existe, 422 se não é um PDF legível
`inspect_template`	`POST /templates/inspect`: conta quantos links de convite o modelo tem
`generate_invitation`	`POST /invitations/generate`: troca os links e grava o PDF do convite

Passo a passo da geração (generate_invitation):

Valida os campos recebidos (UUIDs, token só com A-Z a-z 0-9 _ -, versão ≥ 1). Se algum for inválido, o FastAPI responde 422 automaticamente.
Monta o link novo: <INVITE_LINK_BASE_URL>/r/<token> (ou <APP_URL>/r/<token>, se a primeira estiver vazia).
Abre o modelo da versão informada.
Percorre todas as páginas e, em cada uma, todos os links (page.get_links()). Para cada link aprovado por _is_invite_link, troca link["uri"] e chama page.update_link(link).
Se nenhum link foi trocado, responde 422 ("Link do convite não encontrado no PDF modelo.").
Salva num arquivo temporário (*.tmp) na pasta generated/ e só então o renomeia para o nome final (os.replace). Se algo falhar antes disso, o PDF anterior continua intacto e o temporário é apagado.

Contrato HTTP (o que o Next envia e espera):

Endpoint	Corpo enviado	Resposta de sucesso
`GET /health`	—	`{"status": "ok", "storage": true, "link_base_url": true}`
`POST /templates/inspect`	`{"event_id": "<uuid>", "template_version": 3}`	`{"links": 1}`
`POST /invitations/generate`	`{"event_id": "<uuid>", "invitation_id": "<uuid>", "token": "Ab3xY9kL", "template_version": 3}`	`{"links": 1}`

Erros: o serviço responde {"detail": "<mensagem>"}. Quando detail é texto, o Next mostra essa mensagem na tela (no card do convite ou no upload). Mantenha as mensagens em português e úteis para o organizador.

Código	Quando
400	Caminho fora de `STORAGE_DIR`
404	Modelo não encontrado no disco
422	PDF ilegível, link não encontrado ou campos inválidos
500	`APP_URL` e `INVITE_LINK_BASE_URL` ausentes, ou erro inesperado (detalhes completos no log)

Ajustes comuns

a) Mudar o trecho que identifica o link (ex.: só n1b3.com.br/r/)

Não precisa mexer no código. Altere INVITE_LINK_PATTERN no .env e rode docker compose up -d pdf-service.

b) Mudar a regra de identificação (ex.: expressão regular, domínio exato, ignorar maiúsculas)

Altere só a função _is_invite_link em pdf-service/app/main.py. Exemplo com expressão regular:

import re

LINK_RE = re.compile(r"^https://(convite\.)?n1b3\.com\.br/r/[A-Za-z0-9_-]+$")

def _is_invite_link(link: dict) -> bool:
    return bool(LINK_RE.match(link.get("uri") or ""))

Ela é usada tanto na validação do upload (inspect) quanto na geração, então as duas continuam coerentes.

c) Mudar o formato do link gravado (ex.: incluir ?origem=pdf)

Altere a linha new_link = f"{LINK_BASE_URL}/r/{req.token}" em generate_invitation. Depois, gere de novo os PDFs dos eventos afetados.

d) Trocar também texto visível ou QR code

O código atual troca só links clicáveis. Trocar texto impresso ou QR code é outra técnica:

Texto: remover o texto antigo (page.add_redact_annot + apply_redactions) e escrever o novo (page.insert_text). Isso pode alterar fonte e posição.
QR code: gerar a imagem do QR (biblioteca qrcode) e sobrepô-la com page.insert_image.

Nos dois casos, teste com o modelo real antes de publicar.

e) Receber um campo novo do Next (ex.: nome da família para escrever no PDF)

Python: adicione o campo em GenerateRequest, ex.: display_name: str = Field(max_length=120).
Next: inclua o campo no post("/invitations/generate", {...}) em src/lib/pdf/service.ts e passe o valor em generateForInvitation (src/lib/pdf/jobs.ts), lendo-o do banco.
Publique os dois serviços juntos (docker compose up -d --build).

Nunca receba caminhos de arquivo do Next ou do navegador. Os caminhos devem continuar sendo montados no Python a partir de ids validados.

f) Mudar a estrutura de pastas

Altere juntos _template_path / _generated_path (Python) e templatePath / generatedPdfPath (src/lib/pdf/storage.ts). Arquivos já existentes no volume não são movidos sozinhos: mova-os ou gere tudo de novo, e envie os modelos novamente.

g) Arquivo final maior ou menor

Hoje o PDF é salvo com doc.save(tmp_name), sem recompactar, para preservar o original ao máximo. Para reduzir o tamanho, dá para usar doc.save(tmp_name, garbage=3, deflate=True). Compare visualmente o resultado antes de adotar.

h) Desempenho e tempo limite

Ajuste	Onde
Processos do serviço (padrão 2)	`--workers` no `CMD` do `pdf-service/Dockerfile`
Tempo máximo por PDF (padrão 60 s)	`GENERATE_TIMEOUT_MS` em `src/lib/pdf/service.ts`
Intervalo de atualização da tela (padrão 1,5 s)	`POLL_INTERVAL_MS` em `src/components/admin/EventPdf.tsx`

O lote processa um convite por vez de propósito, para não sobrecarregar o servidor.

i) Atualizar as bibliotecas

O requirements.txt usa faixas de versão. Para fixar as versões que estão funcionando hoje:

docker compose exec pdf-service pip freeze

Copie as linhas de fastapi, uvicorn, pymupdf (e pydantic, starlette, se quiser fixar tudo) para o requirements.txt com ==, por exemplo pymupdf==1.26.4. Para atualizar:

Troque a versão no requirements.txt.
Rode docker compose build --no-cache pdf-service.
Teste (Testar uma alteração).
Publique (Publicar e desfazer).

Testar uma alteração

Opção 1 — Python na sua máquina, sem Docker (Python 3.11 ou mais novo)

# Windows (PowerShell), dentro da pasta pdf-service
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
$env:STORAGE_DIR = "..\storage"; $env:INVITE_LINK_BASE_URL = "http://localhost:3000"
.venv\Scripts\uvicorn app.main:app --port 8000 --reload

# Linux/macOS
cd pdf-service
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
STORAGE_DIR=../storage INVITE_LINK_BASE_URL=http://localhost:3000 .venv/bin/uvicorn app.main:app --port 8000 --reload

O --reload reinicia o serviço a cada alteração no main.py.

Para testar sem o app, coloque um modelo na pasta esperada. Qualquer UUID serve como id de teste:

storage/events/11111111-1111-1111-1111-111111111111/template/modelo-v1.pdf

E chame os endpoints, em outro terminal:

curl http://localhost:8000/health
curl -X POST http://localhost:8000/templates/inspect -H "Content-Type: application/json" -d "{\"event_id\":\"11111111-1111-1111-1111-111111111111\",\"template_version\":1}"
curl -X POST http://localhost:8000/invitations/generate -H "Content-Type: application/json" -d "{\"event_id\":\"11111111-1111-1111-1111-111111111111\",\"invitation_id\":\"22222222-2222-2222-2222-222222222222\",\"token\":\"TESTE123\",\"template_version\":1}"

O PDF sai em storage/events/1111…/generated/22222222-2222-2222-2222-222222222222.pdf. Abra-o e confira:

o link aponta para http://localhost:3000/r/TESTE123;
o resto do PDF está igual ao modelo.

Para testar junto com o app no npm run dev, veja pdf-service local.

Opção 2 — No servidor, com Docker

docker compose up -d --build pdf-service
docker compose ps pdf-service             # aguarde ficar "healthy"
docker compose logs -f pdf-service

Depois teste pela tela: envie o modelo (valida o inspect), gere o PDF de um convite e baixe-o.

O serviço não tem porta publicada. Para chamá-lo direto, use o app como ponte:

docker compose exec app wget -qO- http://pdf-service:8000/health

Checklist antes de publicar uma alteração:

GET /health responde "status": "ok".
Upload de um modelo válido é aceito; um PDF sem o link é recusado com mensagem clara.
O PDF gerado abre normalmente, o link leva a <APP_URL>/r/<token> (ou <INVITE_LINK_BASE_URL>/r/<token>, se definida) e o layout, as imagens, as fontes e os demais links continuam iguais.
Um erro proposital (ex.: apagar o modelo do disco) aparece como "Erro ao gerar" no card, com a mensagem, e o PDF anterior continua disponível.
A geração em lote termina e mostra o total correto.
Se o contrato mudou, o app também foi alterado e publicado junto.

Publicar e desfazer

Publicar:

O que mudou	Comando
Só `pdf-service/` (código ou `requirements.txt`)	`docker compose up -d --build pdf-service`
Só variáveis `INVITE_LINK_*` no `.env`	`docker compose up -d pdf-service`
Contrato (Python e Next)	`docker compose up -d --build`

Publicar o pdf-service não derruba os convites nem o RSVP: só a geração de PDFs fica indisponível por alguns segundos.
Evite publicar durante uma geração em lote. Se acontecer, os convites que falharem ficam com erro e basta clicar em Gerar só pendentes e com erro.
Se a alteração muda o PDF gerado (regra, formato do link etc.), os PDFs antigos não são refeitos sozinhos. Use Gerar PDFs de todos os convites em cada evento.

Desfazer: antes de copiar a versão nova, guarde uma cópia da pasta atual:

cp -r pdf-service pdf-service.bak-$(date +%F)

Se der problema, volte a cópia e reconstrua:

rm -rf pdf-service && mv pdf-service.bak-AAAA-MM-DD pdf-service
docker compose up -d --build pdf-service

Depuração

Logs: cada geração registra PDF gerado convite=... evento=... links=N. Erros inesperados aparecem com o traceback completo:
```
docker compose logs --since 30m pdf-service
```
Mais detalhes: troque level=logging.INFO por level=logging.DEBUG em logging.basicConfig e acrescente log.debug(...) onde precisar. Reconstrua o serviço depois.

Inspecionar os links de um PDF: dentro do container, liste os links de um modelo:

docker compose exec pdf-service python -c "import fitz,sys; d=fitz.open(sys.argv[1]); [print(p.number+1, l.get('uri')) for p in d for l in p.get_links()]" /storage/events/<eventId>/template/modelo-v<versão>.pdf

Mostra a página e a URI de cada link. É útil para entender por que um modelo foi recusado.

Erro só no app ("Serviço de PDF indisponível"): o app não conseguiu falar com o serviço. Veja:
- se o container está healthy;
- a variável PDF_SERVICE_URL (no compose deve ser http://pdf-service:8000);
- o log do app, que mostra o erro de conexão.

Deploy

Deploy, publicação no Cloudflare, atualização de versão, backup e solução de problemas estão no instrucoes.md (Parte 1).

Languages

TypeScript 94.7%

Python 2.6%

CSS 1.3%

Dockerfile 1.1%

JavaScript 0.3%

README.md Unescape Escape

Convites Digitais