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