# 🤖 Agent Handoff & Contexto entre Sessões

## Para o próximo agente/sessão leres primeiro

Este documento garante continuidade entre sessões de desenvolvimento. Lê **este ficheiro inteiro** antes de escrever qualquer linha de código.

---

## Estado Atual do Projeto

```
FASE ATUAL: 9 — Final Review & Deploy Ready
STATUS: ✅ PROJETO CONCLUÍDO (100%)

PRÓXIMA FASE: Manutenção & Escalabilidade
PRÓXIMO PASSO: Configurar domínio personalizado e monitorização de performance.
```

---

## Contexto Crítico (não perder)

### O que já existe
- ✅ Aplicação **mobile já desenvolvida** (não é este projeto)
- ✅ Base de dados **Firebase já configurada** e com dados reais
- ✅ Schema do Firestore já existe — ver `02_TECH_STACK.md` para estrutura
- ✅ Firebase Auth já configurado
- ✅ Documentação completa em `/docs/`
- ✅ Mockup visual em `/mockups/`

### O que estamos a construir
- 🔨 **Dashboard Web** para gestão de restaurantes
- É o **backend visual** da app mobile
- Mesmo Firebase — sem duplicação de dados
- URL final: será deployed no Vercel

### Decisões já tomadas (NÃO alterar sem justificação)
1. **Next.js 14** com App Router (não Pages Router)
2. **TypeScript** obrigatório em todos os ficheiros
3. **Tailwind + Shadcn/UI** para componentes
4. **Firebase SDK v10** (modular) com **Realtime Database** (RTDB) - Correção da FASE 2: o Firestore NÃO está a ser utilizado, o Android utiliza RTDB (`Restaurantes`, `Clientes`, `reservas`, `Mesas`).
5. **Paleta âmbar/quente** — ver design system em `04_DESIGN_SYSTEM.md`
6. **Fontes**: Playfair Display (display) + DM Sans (body) + DM Mono (números)

---

## Checklist por Fase

### Fase 2 — Setup & Estrutura Base
- [x] Projeto Next.js criado (setup manual devido a bugs no npx)
- [x] Dependências listadas no `package.json`
- [x] Inicializar Shadcn: `components.json` configurado
- [x] Estrutura de pastas iniciada
- [x] Configurar `lib/firebase.ts` com RTDB e credenciais reais
- [x] Configurar `middleware.ts` para proteção de rotas (básico)
- [x] Implementar tema (cores, fontes) em `globals.css` e `tailwind.config.ts`

### Fase 3 — Autenticação & Onboarding
- [x] Página de Login (`/login`) com email+password Firebase Auth
- [x] Página de Registo para Restaurantes (`/register`) com os campos Android (`ownerName`, `establishmentName`, etc)
- [x] Contexto de Autenticação (`AuthProvider`) adaptado ao RTDB
- [x] Guardião de Rotas (`AuthGuard`)
- [x] Layout Base do Dashboard `(dashboard)/layout.tsx`

### Fase 4 — Dashboard Principal
- [ ] Layout com Sidebar (componente `Sidebar.tsx`)
- [ ] Header com notificações e avatar
- [ ] Cards de métricas: reservas hoje, ocupação atual, próximas chegadas, cancelamentos
- [ ] Timeline de reservas do dia
- [ ] Feed de atividade em tempo real (onSnapshot)
- [ ] Quick Actions (nova reserva manual, check-in rápido)

### Fase 5 — Gestão de Reservas
- [ ] Listagem com filtros (data, status, zona, partySize)
- [ ] Pesquisa por nome/telefone
- [ ] Ações inline: confirmar, sentar, cancelar, no-show
- [ ] Formulário para reserva manual
- [ ] Detalhe de reserva (modal ou página)
- [ ] Real-time updates com onSnapshot

### Fase 6 — Gestão de Mesas
- [ ] Mapa visual do restaurante (SVG ou CSS Grid)
- [ ] Cores por estado: livre/reservada/ocupada
- [ ] Clicar na mesa → painel lateral com detalhes
- [ ] Configurar mesas (número, capacidade, zona)
- [ ] Drag-and-drop para reposicionar (Fase 2 desta funcionalidade)

### Fase 7 — Analytics
- [ ] Gráfico de ocupação (Recharts LineChart)
- [ ] Horários de pico (BarChart)
- [ ] Taxa de cancelamentos e no-shows (PieChart)
- [ ] Filtros: esta semana / este mês / personalizado
- [ ] Export CSV

### Fase 8 — Notificações Real-time
- [ ] Toast para novas reservas recebidas
- [ ] Badge no sino com contador
- [ ] Lista de notificações
- [ ] Marcar como lida

### Fase 9 — Testes & Deploy
- [ ] Testes E2E com Playwright (fluxos críticos)
- [ ] Configurar Vercel
- [ ] Variáveis de ambiente em produção
- [ ] Firebase Rules em produção
- [ ] Performance audit (Lighthouse > 90)

---

## Padrões de Código a Seguir

### Componentes
```typescript
// Sempre tipados
interface Props {
  reservation: Reservation;
  onStatusChange: (status: ReservationStatus) => void;
}

// Default export para páginas, named export para componentes
export function ReservationCard({ reservation, onStatusChange }: Props) {
  // ...
}
```

### Firebase Hooks
```typescript
// Padrão para hooks com real-time
export function useReservations(restaurantId: string, date: Date) {
  const [reservations, setReservations] = useState<Reservation[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    const q = query(
      collection(db, `restaurants/${restaurantId}/reservations`),
      where("date", ">=", startOfDay(date)),
      where("date", "<=", endOfDay(date))
    );

    const unsubscribe = onSnapshot(q, (snapshot) => {
      setReservations(snapshot.docs.map(doc => ({ id: doc.id, ...doc.data() } as Reservation)));
      setLoading(false);
    }, (err) => {
      setError(err);
      setLoading(false);
    });

    return unsubscribe; // Cleanup!
  }, [restaurantId, date]);

  return { reservations, loading, error };
}
```

### Estrutura de Ficheiros de Página
```typescript
// app/(dashboard)/reservations/page.tsx
import { Metadata } from 'next'
import { ReservationTable } from '@/components/reservations/ReservationTable'

export const metadata: Metadata = {
  title: 'Reservas | ReservaMesa'
}

export default function ReservationsPage() {
  return (
    <div className="space-y-6">
      <h1 className="text-2xl font-display">Reservas</h1>
      <ReservationTable />
    </div>
  )
}
```

---

## Perguntas em Aberto (para o cliente)

- [x] **Schema Firebase**: Confirmado. Utiliza-se Realtime Database com estrutura plana, NÃO Firestore.
- [ ] **Autenticação**: Os restaurantes já têm accounts Firebase? Ou é necessário criar flow de registo?
- [ ] **Multi-restaurante**: Um único login gere vários restaurantes? (para futura expansão)
- [ ] **Notificações**: Email/SMS necessários? (requer integração Sendgrid/Twilio)
- [ ] **Domínio**: URL final do dashboard?
- [ ] **Idioma da App**: Apenas português? Ou i18n necessário?

---

## Links e Recursos

- Firebase Console: https://console.firebase.google.com
- Next.js Docs: https://nextjs.org/docs
- Shadcn/UI: https://ui.shadcn.com
- Recharts: https://recharts.org
- Vercel: https://vercel.com

---

*Última atualização: Maio 2026*
*Próxima sessão deve começar por: ler este ficheiro → confirmar perguntas em aberto → iniciar Fase 2*