gitadmin/sass-imobiliaria
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
sass-imobiliaria/specs/025-favoritos-locais/spec.md
MatheusAlves96 cf5603243c
Some checks failed
CI/CD → Deploy via SSH / Build & Push Docker Images (push) Successful in 1m0s
Details
CI/CD → Deploy via SSH / Deploy via SSH (push) Successful in 4m35s
Details
CI/CD → Deploy via SSH / Validate HTTPS & Endpoints (push) Failing after 46s
Details
feat: features 025-032 - favoritos, contatos, trabalhe-conosco, area-cliente, navbar, hero-light-dark, performance-homepage 
- feat(025): favoritos locais com FavoritesContext, HeartButton, PublicFavoritesPage
- feat(026): central de contatos admin (leads/contatos unificados)
- feat(027): configuração da página de contato via admin
- feat(028): trabalhe conosco - candidaturas com upload e admin
- feat(029): UX área do cliente - visitas, comparação, perfil
- feat(030): navbar UX - menu mobile, ThemeToggle, useFavorites
- feat(031): hero light/dark - imagens separadas por tema, upload, preview, seed
- feat(032): performance homepage - Promise.all parallel fetches, sessionStorage cache,
  preload hero image, loading=lazy nos cards, useInView hook, will-change carrossel,
  keyframes em index.css, AgentsCarousel e HomeScrollScene via props
- fix: light mode HomeScrollScene - gradiente, cores de texto, scroll hint

migrations: g1h2i3j4k5l6 (source em leads), h1i2j3k4l5m6 (contact_config),
            i1j2k3l4m5n6 (job_applications), j2k3l4m5n6o7 (hero theme images)
2026-04-22 22:35:17 -03:00

14 KiB
Raw Blame History

Feature Specification: Favoritos Locais para Visitantes Não Autenticados

Feature Branch: 025-favoritos-locais Created: 2026-04-21 Status: Draft

Contexto

O sistema já oferece uma lista de favoritos para usuários autenticados, acessível em /area-do-cliente/favoritos. No entanto, visitantes sem cadastro não podem salvar imóveis de interesse durante a navegação — qualquer imóvel marcado como favorito é esquecido ao trocar de página ou fechar o browser.

Este spec cobre a adição de uma experiência de favoritos para visitantes não autenticados, inteiramente do lado do cliente, sem necessidade de cadastro imediato. Inclui também uma página pública /favoritos acessível a qualquer visitante e a sincronização automática dos favoritos locais com a conta do servidor quando o visitante decide se cadastrar ou fazer login.

User Scenarios & Testing

User Story 1 — Visitante Favorita Imóvel Sem Se Cadastrar (Priority: P1)

Um visitante sem cadastro que encontrou um imóvel interessante na listagem ou na página de detalhes quer marcá-lo como favorito para revisitar depois — sem precisar criar uma conta no momento.

Why this priority: Exigir cadastro para salvar favoritos cria uma barreira de entrada que reduz o engajamento de visitantes em fase de descoberta. Permitir favoritos locais elimina essa fricção e aumenta o tempo médio de sessão e a probabilidade de conversão posterior.

Independent Test: Sem estar logado, clicar no ícone de coração de um card de imóvel na listagem /imoveis, verificar que o ícone muda visualmente para preenchido, navegar para outra página e retornar — o imóvel deve continuar marcado como favorito.

Acceptance Scenarios:

  1. Given um visitante não autenticado na página /imoveis, When ele clica no ícone de favorito de um card, Then o ícone muda para o estado "favoritado" (coração preenchido) instantaneamente e o imóvel é salvo localmente.
  2. Given um visitante não autenticado na página de detalhes de um imóvel, When ele clica no botão de favorito, Then o ícone muda para o estado "favoritado" e o imóvel é salvo localmente.
  3. Given um imóvel já favoritado localmente, When o visitante clica novamente no ícone de favorito, Then o imóvel é removido dos favoritos locais e o ícone volta ao estado vazio.
  4. Given um imóvel favoritado por um visitante não autenticado, When o visitante fecha o browser e reabre o site, Then o ícone de favorito daquele imóvel ainda aparece preenchido.
  5. Given múltiplos imóveis favoritados localmente, When o visitante navega pela listagem, Then todos os imóveis favoritados exibem o ícone preenchido consistentemente.

User Story 2 — Visitante Acessa a Página Pública de Favoritos (Priority: P1)

Um visitante não autenticado que favoritou imóveis quer ver todos os seus imóveis salvos em uma única página, com informações resumidas e acesso direto à página de detalhes de cada um.

Why this priority: Sem uma página dedicada, os favoritos locais têm valor limitado — o usuário não consegue revisitar rapidamente os imóveis que marcou. A página /favoritos é o destino principal da funcionalidade e torna a experiência comparável à dos usuários autenticados.

Independent Test: Favoritar 3 imóveis como visitante não autenticado, navegar para /favoritos, verificar que os 3 imóveis aparecem com foto, título, preço e link para o detalhe.

Acceptance Scenarios:

  1. Given um visitante não autenticado com imóveis favoritados localmente, When ele acessa /favoritos, Then a página exibe todos os imóveis salvos com foto, título, preço e link para a página de detalhes.
  2. Given a página /favoritos com imóveis exibidos, When o visitante clica no ícone de remoção de um imóvel, Then o imóvel é removido da lista imediatamente, sem recarregar a página.
  3. Given um visitante não autenticado sem nenhum favorito salvo, When ele acessa /favoritos, Then uma mensagem de estado vazio é exibida com orientação para navegar na listagem e salvar imóveis.
  4. Given a página /favoritos acessível sem autenticação, When um visitante não autenticado acessa /favoritos diretamente pela URL, Then a página carrega normalmente sem redirecionar para login.
  5. Given a página /favoritos com imóveis exibidos, When o visitante clica no card de um imóvel, Then é redirecionado para a página de detalhes daquele imóvel.

User Story 3 — Banner de Incentivo ao Cadastro na Página de Favoritos (Priority: P2)

Um visitante não autenticado na página /favoritos é informado de que pode salvar sua lista de favoritos permanentemente criando uma conta, e recebe um caminho claro para o cadastro.

Why this priority: A página /favoritos é o momento de maior intenção do visitante — ele demonstrou interesse explícito em imóveis e está revisitando-os. É o ponto de conversão mais natural para incentivar o cadastro.

Independent Test: Acessar /favoritos sem estar autenticado e verificar que um banner/card de convite ao cadastro é exibido, com botão para criar conta e explicação dos benefícios de sincronização.

Acceptance Scenarios:

  1. Given um visitante não autenticado na página /favoritos, When a página é carregada, Then um banner informativo é exibido explicando que criar uma conta permite salvar os favoritos na nuvem e acessá-los em qualquer dispositivo.
  2. Given o banner de incentivo visível, When o visitante clica em "Criar conta", Then é redirecionado para a página de cadastro.
  3. Given o banner de incentivo visível, When o visitante clica em "Entrar", Then é redirecionado para a página de login com retorno automático para /favoritos após autenticação.
  4. Given um usuário autenticado na página /favoritos, When a página é carregada, Then o banner de incentivo ao cadastro não é exibido.

User Story 4 — Sincronização de Favoritos Locais ao Fazer Login (Priority: P2)

Um visitante que acumulou favoritos locais e decide se autenticar tem seus favoritos locais automaticamente mesclados com os favoritos já salvos em sua conta, sem precisar refavoritar os imóveis manualmente.

Why this priority: Sem sincronização, o usuário perde toda a lista de favoritos locais ao fazer login, o que penaliza exatamente o comportamento desejado (visitar imóveis, favoritar e depois se cadastrar). A perda de dados cria frustração e desincentiva o uso da funcionalidade.

Independent Test: Favoritar 3 imóveis sem estar logado (A, B, C). Fazer login em uma conta que já tem o imóvel A nos favoritos do servidor. Navegar para /area-do-cliente/favoritos e verificar que A, B e C aparecem — sem duplicatas.

Acceptance Scenarios:

  1. Given um visitante com imóveis A, B e C favoritados localmente, When ele faz login com sucesso, Then os imóveis B e C (que não estavam nos favoritos do servidor) são adicionados automaticamente à conta do servidor.
  2. Given que o imóvel A já estava nos favoritos do servidor antes do login, When o visitante faz login com A, B e C nos favoritos locais, Then o imóvel A não é duplicado nos favoritos do servidor.
  3. Given que a sincronização foi realizada com sucesso, When o login é concluído, Then os favoritos locais são removidos do armazenamento local do browser.
  4. Given um visitante sem nenhum favorito local, When ele faz login, Then nenhuma operação de merge é realizada e os favoritos do servidor não são alterados.
  5. Given que a sincronização falha por erro de rede após o login, When o visitante acessa a área de favoritos, Then os favoritos locais são preservados (não apagados) para retentativa futura.

Edge Cases

  • O que acontece com os favoritos locais quando o visitante usa o modo de navegação anônima (aba privada)?
  • Como o sistema exibe o estado de carregamento enquanto busca os dados dos imóveis favoritados na página /favoritos?
  • O que acontece se um imóvel favoritado localmente for removido ou desativado no sistema antes de o visitante acessar /favoritos?
  • Como o ícone de favorito se comporta em imóveis que aparecem em múltiplos contextos (listagem, detalhe, resultados de busca) simultaneamente na mesma sessão?
  • O que acontece com os favoritos locais ao fazer logout — eles são mantidos ou limpos?
  • Como o sistema lida com uma lista muito grande de favoritos locais (ex.: 50+ imóveis) em termos de desempenho na página /favoritos?
  • O que acontece se o visitante tentar acessar /favoritos em um browser que não suporta armazenamento local?

Requirements

Functional Requirements

Grupo 1 — Favoritar Sem Autenticação

  • FR-001: O sistema DEVE permitir que visitantes não autenticados adicionem e removam imóveis de uma lista de favoritos local sem exigir cadastro ou login.
  • FR-002: O estado de favorito (favoritado ou não) de cada imóvel DEVE ser persistido entre sessões do browser para visitantes não autenticados.
  • FR-003: O ícone de favorito em cards de listagem e na página de detalhes DEVE refletir o estado local em tempo real para visitantes não autenticados.
  • FR-004: O toggle de favorito DEVE funcionar de forma idêntica (mesma interface visual e resposta imediata) tanto para usuários autenticados quanto para visitantes não autenticados.

Grupo 2 — Página Pública de Favoritos

  • FR-005: O sistema DEVE disponibilizar uma rota pública /favoritos acessível sem autenticação que exiba todos os imóveis favoritados pelo visitante.
  • FR-006: A página /favoritos DEVE buscar os dados atualizados de cada imóvel favoritado pelo seu identificador e exibi-los com foto, título, preço, tipo, número de quartos, área e link para o detalhe.
  • FR-007: A página /favoritos DEVE exibir um estado vazio com orientação de navegação quando o visitante não tiver nenhum favorito salvo.
  • FR-008: O visitante DEVE poder remover imóveis individualmente da lista na página /favoritos sem recarregar a página.
  • FR-009: A página /favoritos NÃO DEVE redirecionar visitantes não autenticados para a página de login.

Grupo 3 — Banner de Incentivo ao Cadastro

  • FR-010: A página /favoritos DEVE exibir um banner de incentivo ao cadastro quando o visitante não estiver autenticado, explicando os benefícios de sincronização entre dispositivos.
  • FR-011: O banner DEVE conter ações claras para cadastro e para login, com retorno automático à página /favoritos após autenticação.
  • FR-012: O banner de incentivo ao cadastro NÃO DEVE ser exibido para usuários autenticados.

Grupo 4 — Sincronização no Login

  • FR-013: Ao concluir o processo de autenticação com sucesso, o sistema DEVE verificar se há favoritos locais armazenados no browser.
  • FR-014: Caso existam favoritos locais, o sistema DEVE adicionar à conta do servidor apenas os imóveis que ainda não constam nos favoritos do usuário, evitando duplicatas.
  • FR-015: Após a sincronização bem-sucedida, o sistema DEVE limpar os favoritos locais do browser.
  • FR-016: Em caso de falha na sincronização, os favoritos locais DEVEM ser preservados para retentativa e o usuário DEVE ser informado discretamente.
  • FR-017: Usuários que fazem login sem favoritos locais NÃO DEVEM ter os favoritos do servidor alterados.

Key Entities

  • Favorito Local: Registro do lado do cliente representando o interesse de um visitante em um imóvel. Identificado pelo property_id do imóvel. Não tem representação no banco de dados — existe exclusivamente no armazenamento local do browser do visitante.
  • Imóvel (Property): Unidade imobiliária com identificador único, título, preço, tipo, área, quartos e fotos. Consultado pelo identificador na página /favoritos para exibir informações atualizadas.
  • Lista de Favoritos Locais: Conjunto de property_ids armazenados localmente pelo visitante, sem limite explícito de tamanho nesta versão.

Success Criteria

Measurable Outcomes

  • SC-001: Visitantes não autenticados conseguem favoritar um imóvel em 1 clique, sem fluxo de cadastro ou modal intermediário.
  • SC-002: O estado de favorito é preservado em 100% das navegações entre páginas e reabertas de browser (sem autenticação).
  • SC-003: Visitantes conseguem acessar e visualizar todos os seus imóveis favoritados em /favoritos em menos de 3 segundos após o carregamento da página.
  • SC-004: Após o login, 100% dos favoritos locais que não estavam no servidor são sincronizados automaticamente, sem nenhuma ação adicional do usuário.
  • SC-005: Zero duplicatas de favoritos são criadas no servidor durante o processo de merge ao fazer login.
  • SC-006: A página /favoritos é acessível sem autenticação — 0% de redirecionamentos indesejados para a tela de login para visitantes não autenticados.
  • SC-007: O banner de incentivo ao cadastro na página /favoritos exibe claramente os benefícios e os caminhos para cadastro e login em uma leitura de menos de 10 segundos.

Assumptions

  • Os identificadores (property_id) dos imóveis são valores estáveis e únicos que não mudam após a criação do imóvel.
  • O contexto de autenticação já expõe o estado do usuário (autenticado/não autenticado) de forma acessível aos componentes de favorito existentes.
  • A página /area-do-cliente/favoritos (para usuários autenticados) permanece inalterada por este spec; a nova página /favoritos é um destino separado.
  • Imóveis removidos ou desativados no sistema durante o período em que estavam favoritados localmente são tratados exibindo um estado de "imóvel indisponível" na página /favoritos, sem remover automaticamente da lista local.
  • A lista de favoritos locais NÃO é sincronizada em tempo real entre múltiplos dispositivos do mesmo visitante (sem autenticação não há como identificar o usuário entre dispositivos).
  • Favoritos locais são mantidos após o logout — um usuário que se desloga não perde imóveis que eventualmente tenha favoritado antes de se autenticar naquela sessão.
  • O backend já possui ou pode receber uma rota para consultar múltiplos imóveis por lista de identificadores, usada pela página /favoritos para buscar dados em lote.
  • Não há novas tabelas ou alterações no banco de dados nesta feature — toda a persistência para visitantes não autenticados é exclusivamente client-side.