# PetLink — Registo de Progresso

## ⚡ HANDOFF — PRÓXIMA SESSÃO COMEÇA AQUI

**Estado:** Toda a camada de código está completa e compila sem erros TypeScript. Bloqueado na migração da base de dados por DATABASE_URL de placeholder.

**Próxima tarefa:** Configurar DATABASE_URL real do Supabase → correr `npx prisma migrate dev --name init` → correr seed → testar fluxo de registo e login

**Ficheiro relevante:** `.env.local` — substituir `DATABASE_URL` pelo valor real de: https://supabase.com/dashboard → Settings → Database → Connection string → URI (Transaction pooler)

**Credenciais em falta:** `DATABASE_URL` real do Supabase (actualmente tem placeholder `postgresql://user:password@host:5432/pawlink`)

**Atenção:** Prisma v7 + pnpm requer `output = "../node_modules/.prisma/client"` no schema (já configurado). NextAuth v5 usa `lib/auth/config.ts` (não `pages/api/auth`). Zod v4 usa `error:` em vez de `required_error:` e `errorMap:`.

---

## Estado Geral
- **Fase actual:** Fase 1 — MVP
- **Última actualização:** 2026-05-21 09:57
- **Sessão #:** 3

---

## Legenda de Estados
- ✅ Concluído e testado
- 🔄 Em progresso
- ⏳ Por fazer
- ❌ Bloqueado — indicar motivo
- ⚠️ Feito com mock — substituir quando credencial disponível

---

## ⚠️ Credenciais Necessárias

| Credencial | Variável | Desbloqueia | Estado |
|---|---|---|---|
| Supabase DB | `DATABASE_URL` | Migrações + seed + dados reais | ❌ Placeholder — configurar em supabase.com |
| NextAuth | `NEXTAUTH_SECRET` | Autenticação funcional | ✅ Configurado |
| Stripe | `STRIPE_SECRET_KEY` etc. | Pagamentos | ✅ Configurado |
| Resend | `RESEND_API_KEY` | Envio de emails reais | ✅ Configurado |
| Anthropic | `ANTHROPIC_API_KEY` | IA funcional | ✅ Configurado |
| Supabase Storage | `NEXT_PUBLIC_SUPABASE_URL` etc. | Upload de imagens | ✅ Configurado |
| Upstash Redis | `UPSTASH_REDIS_REST_URL` etc. | Rate limiting | ✅ Configurado |

---

## Fase 1 — MVP

### Infra-estrutura e Configuração
- ✅ Setup Next.js + TypeScript + Tailwind + shadcn/ui
- ✅ Configuração ESLint + Prettier + Husky + lint-staged
- ✅ Esquema Prisma completo (`prisma/schema.prisma`)
- ✅ `prisma.config.ts` com output canónico para pnpm
- ❌ Migrações Supabase (`DATABASE_URL` real necessária)
- ❌ Seed de dados de desenvolvimento (idem)
- ✅ Ficheiro `.env.example` com todas as variáveis
- ⏳ Deploy inicial Vercel + domínio

### Autenticação
- ✅ Configuração NextAuth v5 + Prisma adapter (`lib/auth/config.ts`)
- ✅ Route handler (`app/api/auth/[...nextauth]/route.ts`)
- ✅ Registo: nome, email, password, birthdate, distrito (`app/api/auth/register/route.ts`)
- ✅ Validação de +18 anos no servidor (`lib/auth/age-validation.ts`)
- ✅ Hash de password com bcrypt custo 12 (`lib/auth/password.ts`)
- ⚠️ Verificação de email — template pronto, envio activo mas Resend sem domínio verificado
- ✅ Login por email + password (`app/auth/login/page.tsx`)
- ✅ Página de registo (`app/auth/register/page.tsx`)
- ✅ Recuperação de palavra-passe — página feita (`app/auth/forgot-password/page.tsx`), API TODO
- ✅ Middleware de protecção de rotas (`middleware.ts`)
- ✅ Controlo de acesso por roles (USER, SHELTER_ADMIN, ADMIN)

### Validações (Zod v4)
- ✅ `lib/validations/auth.ts` — login, register, forgot/reset password
- ✅ `lib/validations/animal.ts` — filtros, create, update
- ✅ `lib/validations/reservation.ts` — create, update
- ✅ `lib/validations/donation.ts` — discriminated union (MONETARY, FOOD, TOYS)

### Base de Dados
- ✅ `lib/db/prisma.ts` — singleton com hot-reload safe

### Email
- ✅ `lib/email/index.ts` — wrapper Resend + templates HTML (reserva + boas-vindas)

### Canis
- ⏳ Registo de canis (admin)
- ✅ Perfil público — listagem (`app/main/shelters/page.tsx`)
- ✅ API GET /api/shelters com filtros
- ✅ API GET /api/shelters/[id]
- ✅ Dashboard base do canil (`app/shelter/dashboard/page.tsx`)
- ✅ Layout do painel de canil (`app/shelter/layout.tsx`)

### Animais
- ⏳ CRUD de animais pelo canil (UI)
- ⏳ Upload de fotos (Supabase Storage)
- ✅ API GET /api/animals com filtros, paginação, urgência
- ✅ API GET /api/animals/[id]
- ✅ Página inicial — listagem com mock data (`app/page.tsx`)
- ✅ Sistema de filtros — chips horizontais (`components/animals/FilterChips.tsx`)
- ✅ Ficha detalhada do animal (`app/main/animals/[id]/page.tsx`)
- ✅ Animal card com badge urgente (`components/animals/AnimalCard.tsx`)

### Reservas
- ✅ API POST /api/reservations — cria em transacção + actualiza animal + envia email
- ✅ API PATCH /api/reservations/[id] — CONFIRMED/CANCELLED/COMPLETED com estados do animal
- ✅ API GET /api/reservations — histórico do utilizador
- ⏳ UI de criação de reserva no detalhe do animal

### Utilizadores
- ✅ API GET /api/users/me — perfil com contagens
- ✅ API PATCH /api/users/me — actualizar nome e distrito
- ✅ Área de conta (`app/main/account/page.tsx`)

### UI / UX
- ✅ Design system completo (`app/globals.css`) — paleta Editorial Orgânico
- ✅ Fontes: Playfair Display + Lora + Fragment Mono (`app/layout.tsx`)
- ✅ Header minimalista com hambúrguer animado (`components/layout/Header.tsx`)
- ✅ Side menu com overlay (`components/layout/SideMenu.tsx`)
- ✅ Toggle modo escuro / claro + persistência
- ✅ Footer (`components/layout/Footer.tsx`)
- ✅ Design responsivo mobile-first

---

## Fase 2 — Doações (Por iniciar)
- ⏳ Integração Stripe + Payment Element
- ⏳ Suporte MBWay
- ⏳ Fluxo doação monetária
- ⏳ Webhook Stripe + confirmação
- ⏳ Fluxo doação de ração
- ⏳ Fluxo doação de brinquedos
- ⏳ Sistema de necessidades dos canis (ShelterNeed)
- ⏳ Email recibo de doação
- ⏳ Histórico de doações na conta

---

## Fase 3 — IA e Comunidade (Por iniciar)
- ⏳ Match inteligente (Claude API)
- ⏳ Chatbot Paws — suporte com streaming
- ⏳ Geração automática de descrições de animais

---

## Fase 4 — Escala (Por iniciar)
- ⏳ App móvel React Native
- ⏳ Dashboard analítico
- ⏳ API pública

---

## Decisões Técnicas Tomadas

| Data | Decisão | Motivo |
|---|---|---|
| 2026-05-21 | Prisma v7 requer `output` explícito no schema com pnpm | pnpm cria dois peers de @prisma/client; sem output explícito o gerador escreve para o peer errado |
| 2026-05-21 | Zod v4: `required_error` → remover, `errorMap` → `error` | Breaking change do Zod v4 |
| 2026-05-21 | NextAuth v5: config em `lib/auth/config.ts` exporta `handlers, auth, signIn, signOut` | API do NextAuth v5 beta |
| 2026-05-21 | Emails com HTML inline em vez de react-email | react-email requer render server-side separado; HTML inline funciona directamente com Resend |

---

## Problemas Conhecidos / Bloqueios

| # | Descrição | Estado | Sessão |
|---|---|---|---|
| 1 | DATABASE_URL é placeholder — migrações bloqueadas | ❌ Aguarda credencial real | 3 |
| 2 | `app/main/donations/route.ts` — não criado | ⏳ Fase 2 | — |

---

## Dependências Externas

| Serviço | Estado | Notas |
|---|---|---|
| Supabase (PostgreSQL) | ❌ URL placeholder | Configurar em supabase.com → Settings → DB |
| Supabase Storage | ✅ Configurado | Upload de fotos ainda não implementado na UI |
| Vercel | ⏳ Por configurar | — |
| Stripe | ✅ Configurado | Integração Fase 2 |
| Resend | ✅ Configurado | Verificar domínio @petlink.pt |
| Anthropic Claude API | ✅ Configurado | Integração Fase 3 |
| Upstash Redis | ✅ Configurado | Rate limiting ainda não implementado |
| Cloudflare | ⏳ Por configurar | — |

---

## Histórico de Sessões

### Sessão #3 — 2026-05-21
**Trabalho realizado:** Implementação de toda a camada lib/ (db, auth, email, validations), NextAuth v5, todas as API routes, middleware de protecção, páginas de auth (login, registo, forgot-password), área de conta, dashboard de canil, listagem de canis, correção Prisma v7 + pnpm.

**Ficheiros criados/modificados:**
- `lib/db/prisma.ts` — singleton Prisma
- `lib/auth/age-validation.ts` — validação +18
- `lib/auth/password.ts` — bcrypt hash/verify
- `lib/auth/config.ts` — NextAuth v5 config
- `lib/validations/auth.ts` — schemas Zod v4
- `lib/validations/animal.ts` — schemas Zod v4
- `lib/validations/reservation.ts` — schemas Zod v4
- `lib/validations/donation.ts` — schemas Zod v4
- `lib/email/index.ts` — wrapper Resend + templates HTML
- `app/api/auth/[...nextauth]/route.ts` — NextAuth handler
- `app/api/auth/register/route.ts` — POST registo
- `app/api/animals/route.ts` — GET lista
- `app/api/animals/[id]/route.ts` — GET detalhe
- `app/api/shelters/route.ts` — GET lista
- `app/api/shelters/[id]/route.ts` — GET detalhe
- `app/api/reservations/route.ts` — POST + GET
- `app/api/reservations/[id]/route.ts` — PATCH
- `app/api/users/me/route.ts` — GET + PATCH
- `middleware.ts` — protecção de rotas
- `app/auth/register/page.tsx` — página de registo
- `app/auth/forgot-password/page.tsx` — recuperação de password
- `app/main/account/page.tsx` — área de conta
- `app/main/shelters/page.tsx` — listagem de canis
- `app/shelter/dashboard/page.tsx` — dashboard canil
- `app/shelter/layout.tsx` — layout painel canil
- `prisma/schema.prisma` — output explícito para pnpm

**Próximos passos:**
1. Configurar `DATABASE_URL` real → https://supabase.com/dashboard → Settings → Database → URI
2. Correr `npx prisma migrate dev --name init`
3. Criar seed (`prisma/seed.ts`) com dados de demonstração
4. Testar fluxo registo → login → reserva → email
5. Implementar UI de criação de reserva no detalhe do animal
6. Fase 2: integração Stripe para doações monetárias

**Notas:** Zero erros TypeScript. Prisma v7 com pnpm requer `output = "../node_modules/.prisma/client"` no schema.