gitadmin/sass-imobiliaria
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
sass-imobiliaria/.specify/features/016-analytics-dashboard/spec.md

9.9 KiB
Raw Blame History

Feature Specification: Analytics Dashboard (Admin)

Feature Branch: 016-analytics-dashboard Created: 2026-04-14 Status: Draft Input: User description: "Dashboard de Analytics no painel admin para acompanhar acessos ao site."

User Scenarios & Testing (mandatory)

User Story 1 - Visualizar Métricas de Acesso (Priority: P1)

O administrador do sistema acessa a página de analytics no painel admin e visualiza um resumo dos acessos ao site: total de visitas hoje, nesta semana e neste mês, além de um gráfico mostrando a evolução de acessos nos últimos 30 dias.

Why this priority: É o coração do dashboard — sem essa visão consolidada, o administrador não consegue avaliar o desempenho do site. Entrega valor imediato ao permitir compreender tendências de tráfego.

Independent Test: Pode ser testado de forma completa acessando /admin/analytics após algumas visitas registradas. O administrador deve ver os cards de métricas e o gráfico com dados reais.

Acceptance Scenarios:

  1. Given o administrador está autenticado e existem registros de acesso, When ele acessa /admin/analytics, Then vê cards com total de acessos de hoje, da semana atual e do mês atual.
  2. Given o administrador está na página de analytics, When a página carrega, Then um gráfico de linha exibe os acessos diários dos últimos 30 dias.
  3. Given o administrador está na página de analytics, When ele altera o filtro de período para "7 dias", "30 dias" ou "90 dias", Then todas as métricas e gráficos atualizam para refletir o período selecionado.
  4. Given não existe nenhum acesso registrado, When o administrador acessa o dashboard, Then vê métricas zeradas e mensagem indicando ausência de dados.

User Story 2 - Consultar Páginas e Imóveis Mais Acessados (Priority: P2)

O administrador consulta as tabelas que listam as 10 páginas e os 10 imóveis mais visitados do site, para entender quais conteúdos são mais relevantes para os visitantes.

Why this priority: Permite decisões de negócio — quais imóveis destacar, quais páginas otimizar. Depende dos dados de rastreamento já coletados (P1).

Independent Test: Testável de forma independente realizando múltiplas visitas a páginas e imóveis distintos e verificando o ranking exibido no dashboard.

Acceptance Scenarios:

  1. Given existem registros de acesso a múltiplas páginas, When o administrador visualiza o dashboard, Then uma tabela exibe as 10 páginas mais acessadas com o caminho e o total de visitas, ordenadas do maior para o menor.
  2. Given existem registros de visualização de imóveis, When o administrador visualiza o dashboard, Then uma tabela exibe os 10 imóveis mais vistos com título, foto de capa e total de visualizações.
  3. Given há menos de 10 páginas/imóveis distintos com registros, When o administrador visualiza as tabelas, Then a tabela exibe apenas os itens disponíveis (sem erros ou linhas vazias).
  4. Given o administrador aplica um filtro de período, When filtra por "7 dias", Then as tabelas de top páginas e top imóveis refletem somente os acessos dentro do período.

User Story 3 - Rastreamento Automático de Visitas Públicas (Priority: P3)

Cada vez que um visitante acessa uma página pública do site, o sistema registra automaticamente essa visita sem exigir nenhuma ação do usuário, preservando a privacidade ao armazenar um hash do IP em vez do IP completo.

Why this priority: É o mecanismo que alimenta todas as métricas do dashboard. Sem rastreamento, não há dados a exibir. Classificado como P3 pois pode ser implementado em paralelo com as histórias de UI, e os dados iniciais podem ser simulados nos testes.

Independent Test: Testável acessando páginas públicas e verificando no banco de dados que os registros foram criados com os campos corretos (path, timestamp, hash de IP, user agent).

Acceptance Scenarios:

  1. Given um visitante acessa qualquer página pública (home, listagem, detalhe, sobre, contato), When a página é carregada, Then um registro de acesso é criado com caminho, horário, hash do IP e user agent.
  2. Given um visitante acessa a página de detalhe de um imóvel, When a página carrega, Then o registro de acesso é associado ao ID do imóvel correspondente, incrementando seu contador de visualizações.
  3. Given uma requisição é feita para rotas administrativas (/admin/*) ou de autenticação (/api/auth/*), When qualquer usuário acessa essas rotas, Then nenhum registro de acesso é criado (rastreamento excluído).
  4. Given o mesmo visitante acessa múltiplas páginas em sequência, When os acessos são registrados, Then cada acesso gera um registro separado com seu próprio timestamp.

Edge Cases

  • O que acontece se o banco de dados estiver indisponível no momento do registro de uma visita? O acesso do visitante não deve ser bloqueado — o rastreamento deve falhar silenciosamente.
  • Como o sistema lida com bots/crawlers? User agent é armazenado mas não há filtro automático de bots na v1 (pode ser adicionado posteriormente).
  • O que acontece se um imóvel referenciado em um acesso for deletado? O registro de acesso deve ser mantido, com property_id referenciando um imóvel inexistente (integridade referencial relaxada ou via soft delete).
  • Como se comporta o gráfico se houver dias sem nenhum acesso no período selecionado? O gráfico deve exibir esses dias com valor zero, sem lacunas na linha do tempo.
  • O dashboard exibe dados em tempo real ou com delay? Os dados refletem os acessos até o momento da consulta (sem polling automático na v1).

Requirements (mandatory)

Functional Requirements

  • FR-001: O sistema DEVE registrar automaticamente cada acesso a páginas públicas com: caminho da URL, data/hora do acesso, user agent e hash anonimizado do IP.
  • FR-002: O sistema DEVE associar o registro de acesso ao ID do imóvel quando a página visitada for a de detalhe de um imóvel.
  • FR-003: O sistema NÃO DEVE registrar acessos a rotas administrativas (/admin/*) nem a rotas de autenticação (/api/auth/*).
  • FR-004: O sistema DEVE disponibilizar ao administrador cards de métricas com total de acessos do dia atual, da semana atual e do mês atual.
  • FR-005: O sistema DEVE disponibilizar ao administrador um gráfico de linha com o total de acessos por dia para o período selecionado.
  • FR-006: O sistema DEVE disponibilizar ao administrador uma tabela com as 10 páginas mais acessadas (caminho + total de acessos) para o período selecionado.
  • FR-007: O sistema DEVE disponibilizar ao administrador uma tabela com os 10 imóveis mais visualizados (título + foto de capa + total de visualizações) para o período selecionado.
  • FR-008: O administrador DEVE conseguir filtrar todas as métricas e rankings por período: últimos 7 dias, últimos 30 dias ou últimos 90 dias.
  • FR-009: O rastreamento de acessos NÃO DEVE impactar a disponibilidade das páginas públicas — falhas no registro devem ser silenciosas para o visitante.
  • FR-010: O IP do visitante DEVE ser armazenado exclusivamente como hash irreversível, nunca em texto claro.
  • FR-011: Somente administradores autenticados DEVEM ter acesso aos dados de analytics.

Key Entities (include if feature involves data)

  • Registro de Acesso (PageView): Representa uma visita a uma página pública. Atributos: identificador único, caminho da URL visitada, referência opcional ao imóvel visualizado, data/hora do acesso, hash do IP do visitante, user agent do navegador.
  • Resumo de Analytics (Summary): Agregação calculada a partir dos registros de acesso, contendo totais por período (dia/semana/mês) e séries temporais diárias.
  • Ranking de Páginas: Lista ordenada das páginas com maior número de acessos em um período, com caminho e contagem.
  • Ranking de Imóveis: Lista ordenada dos imóveis com maior número de visualizações em um período, com título, foto e contagem.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: O administrador consegue visualizar as métricas de acesso em menos de 3 segundos após acessar a página de analytics.
  • SC-002: 100% dos acessos a páginas públicas são registrados sem impactar o tempo de resposta percebido pelo visitante (registro assíncrono ou com overhead inferior a 50ms por requisição).
  • SC-003: O dashboard exibe corretamente métricas zeradas quando não há dados para o período selecionado, sem erros ou telas em branco.
  • SC-004: A troca de filtro de período atualiza todas as métricas, gráfico e tabelas em menos de 2 segundos.
  • SC-005: Nenhum dado pessoal identificável (IP completo) é armazenado — auditoria deve confirmar que apenas hashes são persistidos.
  • SC-006: Acessos a rotas de administração (/admin/*) não aparecem nos registros de analytics após 1 semana de uso em produção.

Assumptions

  • O sistema de autenticação de administradores já está implementado e funcional (feature 005/007).
  • A tabela de imóveis (properties) já existe com os campos de título e foto de capa.
  • O painel admin já possui layout e navegação estabelecidos — a página de analytics será adicionada como nova rota dentro da estrutura existente.
  • A privacidade de IPs via hash é suficiente para conformidade com boas práticas; conformidade formal com LGPD/GDPR fica fora do escopo desta feature.
  • Não há requisito de exportação de dados (CSV/PDF) nesta versão.
  • Filtros de período são globais — não há filtro por tipo de dispositivo, origem de tráfego ou localização geográfica nesta versão (v1).
  • Os dados de analytics não precisam de paginação na v1 — top 10 é o limite exibido nas tabelas.
  • O rastreamento é implementado no lado do servidor (middleware backend), não no frontend, para garantir consistência mesmo em casos de bloqueadores de JavaScript.