# Arquitetura do PedeLá

## Princípios

- Desenvolver por fases, preservando a stack existente.
- Manter pedidos, preços e estado operacional no servidor.
- Guardar snapshots dos produtos e adicionais no pedido para preservar o
  histórico.
- Utilizar `Decimal` para valores monetários.
- Tratar a caixa de entrada do restaurante como a fonte operacional dos
  pedidos; integrações externas são notificações, não o registo do pedido.
- Não guardar credenciais de provedores nos registos do restaurante nem
  simular entregas de notificações.

## Stack

- Next.js App Router para páginas e Route Handlers.
- TypeScript strict e Tailwind CSS 4.
- MariaDB/MySQL com Prisma para persistência, em desenvolvimento e produção.
- Zod será utilizado para validar os dados recebidos nos limites da aplicação.
- Regras de negócio serão extraídas para serviços server-side à medida que as
  funcionalidades forem implementadas.

## Organização por perfil

```text
src/
  app/
    (cliente)/         menu, carrinho, fatura e APIs públicas do cliente
    (atendente)/       caixa de pedidos, endpoints da equipa e dev local
    (admin)/           gestão do restaurante, bootstrap e convites
    (superadmin)/      acesso global e bootstrap do superadmin
    api/health/        health check global
    page.tsx           landing page
    layout.tsx         layout global
  features/
    cliente/           componentes, serviços, validações e estado do cliente
    atendente/         caixa de entrada e consultas de pedidos
    admin/             gestão de restaurante e imagens de produtos
  shared/
    auth/              sessões e primitives de autenticação comuns
    components/        branding, navegação e formulários partilhados
  lib/
    db/                acesso partilhado à base de dados
    format-currency.ts utilitário partilhado de apresentação
prisma/
  schema.prisma        modelo relacional MySQL comum
  migrations/          histórico ativo de migrations MySQL
  postgresql-migrations/ histórico PostgreSQL antigo, preservado e inativo
  seed.ts              dados locais repetíveis para desenvolvimento
```

O Prisma 6 carrega migrations de `prisma/migrations`. Esta pasta contém o
histórico MySQL ativo; o histórico PostgreSQL antigo foi preservado em
`prisma/postgresql-migrations` e não é usado pela aplicação nem pelos comandos
Prisma ativos.

Os route groups entre parênteses organizam as páginas sem alterar os URLs
públicos. As pastas de `features` guardam a implementação do perfil; APIs de
domínio permanecem junto do respetivo route group. O schema, a base de dados,
o layout e utilitários transversais ficam partilhados porque são usados por
vários perfis. URLs antigos `/staff/[restaurantSlug]` redirecionam para as
rotas separadas de atendente ou administrador durante a migração.

O modelo Prisma inicial estabelece restaurantes, utilizadores administrativos,
clientes, catálogo, opções, pedidos, snapshots de linhas, pagamentos, horário
comercial, auditoria e entregas de notificações. Modelos de marketing, fidelidade
e carrinho serão adicionados nas fases correspondentes.

O menu público consulta categorias, produtos e opções ativas no MySQL por
slug do restaurante. O seed de desenvolvimento pode ser reexecutado e não é uma
fonte de dados alternativa à base de dados.

## Receção de pedidos e WhatsApp

1. O backend valida o pedido e calcula os preços usando os dados do banco.
2. A criação do pedido e o registo do histórico são feitos numa transação.
3. A equipa consulta e atualiza o pedido através da caixa de entrada do painel.
4. Se o restaurante tiver ativado notificações e configurado um número, o
   sistema cria uma entrega WhatsApp pendente numa outbox persistida.
5. Um adaptador de provedor autorizado envia a notificação usando credenciais
   configuradas no ambiente de execução. O estado só passa a enviado após
   confirmação do provedor.
6. Falhas e tentativas ficam registadas; não apagam nem duplicam o pedido.

`RestaurantSettings.whatsappRecipientNumber` é o destinatário configurável do
restaurante. `WHATSAPP_ACCESS_TOKEN` e `WHATSAPP_PHONE_NUMBER_ID` identificam o
canal emissor e são segredos de execução, nunca devolvidos ao browser. O número
de destino deverá ser normalizado em formato internacional (E.164). Uma
integração real também deverá respeitar os requisitos de templates, consentimento
e políticas vigentes do provedor.

No MVP inicial, a integração externa permanece desligada por omissão. A ausência
de credenciais não impede a persistência do pedido nem a sua apresentação na
caixa de entrada.

## Segurança e consistência

- Preços, descontos, taxas e totais são calculados no servidor.
- Cada tentativa de checkout terá uma chave de idempotência por restaurante.
- A página de tracking utilizará token aleatório não previsível, independente
  do número público do pedido.
- Autorização de equipa será validada no servidor e isolada por restaurante.
- A conta de histórico do cliente é identificada por email confirmado; número
  de telefone é apenas contacto e nunca permite reclamar uma conta. A criação
  ou reposição do código de cliente exige um código temporário enviado para esse
  email.
- Contas antigas sem email confirmado não são automaticamente associadas por
  telefone ou pelo código legado; a recuperação aguarda um meio independente de
  provar a posse da conta, para não reabrir a apropriação de contas no checkout.
- Tokens de integração não são guardados no schema inicial.
- Erros externos devem ser sanitizados antes de serem apresentados a clientes.