petlink_final/docs/05-fluxos-utilizador.md

# 5. Fluxos de Utilizador

## 5.1 User Stories

| ID | Como... | Quero... | Para... |
|---|---|---|---|
| US-01 | Visitante | Ver animais disponíveis sem criar conta | Descobrir se há animais que me interessem antes de me registar |
| US-02 | Visitante | Filtrar animais por distrito e espécie | Encontrar animais próximos de mim rapidamente |
| US-03 | Visitante | Ver o perfil de um canil com horários | Saber quando posso visitar antes de reservar |
| US-04 | Utilizador | Criar conta com os meus dados | Poder adoptar animais e fazer doações |
| US-05 | Utilizador | Reservar um animal para adopção | Garantir o animal antes de me deslocar ao canil |
| US-06 | Utilizador | Receber email de confirmação da reserva | Ter prova escrita e recordar a data marcada |
| US-07 | Utilizador | Fazer uma doação monetária a um canil | Apoiar financeiramente um canil próximo de mim |
| US-08 | Utilizador | Doar ração ou brinquedos | Contribuir com bens essenciais sem precisar de dinheiro |
| US-09 | Utilizador | Escolher se entrego ou peço recolha | Ter flexibilidade na logística da doação |
| US-10 | Utilizador | Ver o meu histórico de adopções e doações | Acompanhar o meu impacto ao longo do tempo |
| US-11 | Utilizador | Activar o modo escuro | Reduzir cansaço visual ao usar a plataforma |
| US-12 | Utilizador | Alterar a minha palavra-passe | Manter a minha conta segura |
| US-13 | Canil | Gerir os meus animais registados | Ter controlo sobre quais animais estão disponíveis |
| US-14 | Canil | Ver e confirmar reservas recebidas | Preparar o animal para o dia do levantamento |
| US-15 | Canil | Indicar as minhas necessidades actuais | Receber doações específicas do que me faz falta |
| US-16 | Admin | Supervisionar canis e utilizadores | Garantir qualidade e segurança da plataforma |

---

## 5.2 Fluxo de Registo

```
Visitante clica "Criar Conta" (menu — 3 traços, canto superior direito)
    │
    ▼
Preenche formulário:
  • Nome completo
  • Email
  • Palavra-passe (mínimo 8 caracteres, 1 maiúscula, 1 número)
  • Confirmação de palavra-passe
  • Data de nascimento
  • Distrito
  • Checkbox: Concordo com os Termos e Política de Privacidade
    │
    ▼
[Servidor] Valida se idade ≥ 18 anos
    ├── Não → Mostra erro: "É necessário ter 18 ou mais anos para criar conta"
    └── Sim → Continua
    │
    ▼
[Servidor] Verifica se email já existe
    ├── Sim → Mostra erro: "Este email já está registado"
    └── Não → Cria conta com palavra-passe em bcrypt hash
    │
    ▼
Envia email de verificação (Resend)
    │
    ▼
Utilizador confirma email → Redirecionado para página inicial com sessão activa
```

---

## 5.3 Fluxo de Login

```
Utilizador clica "Iniciar Sessão" no menu
    │
    ▼
Preenche email e palavra-passe
    │
    ▼
[Servidor] NextAuth verifica credenciais
    ├── Inválidas → Mostra erro genérico (não especificar qual campo falhou — segurança)
    └── Válidas → Cria sessão JWT
    │
    ▼
Redirecionado para a página onde estava (ou página inicial)
```

---

## 5.4 Fluxo Completo de Adopção

```
1. DESCOBERTA
   ├── Página inicial → lista todos os animais disponíveis (SSR)
   ├── Filtros disponíveis: distrito, espécie, raça, sexo, esterilizado, faixa etária
   └── Animais urgentes têm badge "Urgente" destacado

2. DETALHES DO ANIMAL
   ├── Clica no animal → abre ficha completa
   ├── Galeria de fotos
   ├── Informações: nome, espécie, raça, idade, sexo, esterilizado, descrição
   └── Secção do canil → nome, distrito
        └── Clica no canil → modal/página com:
             • Morada completa
             • Horário de funcionamento (dia a dia)
             • Telefone e email

3. RESERVA
   ├── Clica "Adoptar"
   ├── [Sem sessão] → Redirect para login/registo com mensagem explicativa
   ├── [Com sessão] → Abre calendário de reservas
   ├── Dias disponíveis: dias em que o canil está aberto e sem reservas em excesso
   ├── Selecciona data → formulário de confirmação
   │    • Nome do utilizador (pré-preenchido)
   │    • Data seleccionada
   │    • Nome do animal e canil
   │    • Nota opcional para o canil
   └── Confirma

4. PÓS-RESERVA
   ├── Animal muda para status RESERVED
   ├── Email de confirmação enviado (Resend):
   │    • Assunto: "Reserva confirmada — [Nome do Animal] no [Nome do Canil]"
   │    • Data e hora de levantamento
   │    • Morada do canil
   │    • Horário de funcionamento
   │    • Instruções para cancelamento
   └── Reserva visível em "Conta → As Minhas Adopções"

5. DIA DO LEVANTAMENTO
   ├── Utilizador dirige-se ao canil na data marcada
   ├── Canil confirma levantamento → status muda para COMPLETED
   └── Animal muda para status ADOPTED
```

---

## 5.5 Fluxo de Doação — Monetária

```
Clica "Fazer Doação"
    │
    ▼
[Sem sessão] → Redirect para login com mensagem: "Para doar é necessário ter conta"
[Com sessão, <18 anos] → Confirmação extra de data de nascimento
    │
    ▼
Escolhe tipo: MONETÁRIA
    │
    ▼
Escolhe canil:
  ┌── "Da minha localidade" → lista canis no distrito do utilizador
  └── "Outra localidade" → pesquisa por distrito/nome do canil
    │
    ▼
Insere montante (mínimo: 1€)
    │
    ▼
Escolhe método de pagamento:
  ┌── Cartão de Crédito/Débito
  └── MBWay (introduz número de telemóvel)
    │
    ▼
Stripe processa pagamento (dados nunca passam nos nossos servidores)
    │
    ▼
Confirmação:
  • Página de sucesso com animação
  • Email com recibo de doação
  • Visível em "Conta → Histórico de Doações"
```

---

## 5.6 Fluxo de Doação — Ração / Brinquedos

```
Escolhe tipo: RAÇÃO ou BRINQUEDOS
    │
    ▼
Lista de canis que necessitam e aceitam este tipo de donativo
(baseada nas ShelterNeeds activas)
    │
    ▼
Selecciona canil
    │
    ▼
[RAÇÃO] Especifica:
  • Tipo: Seca / Húmida
  • Para: Cão / Gato
  • Faixa etária: Adulto / Filhote / Sénior

[BRINQUEDOS] Especifica:
  • Categoria: Mordedor / Pelúcia / Interactivo / Corda
    │
    ▼
Escolhe modalidade de entrega:
  ┌── "Levo eu ao canil"
  │    └── Mostra horários e morada do canil seleccionado
  └── "Quero recolha em casa"
       ├── Confirma/edita morada de recolha
       └── Selecciona data e período preferencial (manhã/tarde)
    │
    ▼
Confirmação:
  • Canil recebe notificação com todos os detalhes
  • Utilizador recebe email de confirmação
  • Visível em "Conta → Histórico de Doações"
```

---

## 5.7 Navegação e Menu

O menu é acedido pelos **3 traços no canto superior direito** e contém:

**Sem sessão:**
- Iniciar Sessão
- Criar Conta

**Com sessão:**
- A Minha Conta (nome do utilizador)
- As Minhas Adopções
- Histórico de Doações
- Definições
  - Dados da Conta
  - Alterar Palavra-passe
  - Modo Escuro / Claro (toggle)
- Terminar Sessão