Status: Approved · v2 · SPEC-UX-SEARCH-001

depends_on: SPEC-DOMAIN-SEARCH-001

used_by: IS-MVP-03.1, IS-MVP-03.2, IS-MVP-03.3

Telas de busca e descoberta

Busca universal deve ser rápida, neutra, filtrável e útil mesmo sem query.

Objetivo

Busca universal deve ser rápida, neutra, filtrável e útil mesmo sem query.

Pontos de entrada

• Aba Buscar.
• Seletores dentro de gestão.
• Território.

Hierarquia da tela

1. Campo de busca persistente.
2. Sugestões recentes/populares quando vazio.
3. Tabs por tipo: Todos, Times, Jogadores, Jogos, Campeonatos, Torcidas, Campos, Serviços, Lugares.
4. Filtros e ordenação contextuais.
5. Lista/grid de resultados com paginação.
6. Descoberta territorial quando query vazia.

Componentes e comportamento

Universal Result

Imagem, tipo, nome, subtítulo, território, badges e métricas relevantes.

Filter Sheet

Filtros específicos e botão Limpar; mostra quantidade ativa.

Player Filters

Posição, distrito, time, status livre, período e stats públicas com amostra.

Team Filters

Distrito, bairro, categoria, ranking, torcida, seguidores e forma.

Match Filters

Time, campeonato, campo, data, categoria e status.

Suggestions

Corrige grafia e apresenta tipos sem expor dados privados.

Ações do usuário

Ação	Pré-condição	Resultado	Falha/alternativa
Buscar	Texto ou vazio	Resultados/descoberta	Erro recuperável
Aplicar filtros	Filtros válidos	Atualiza URL/state	Validation
Abrir resultado	Público	Página	Merged/404
Limpar	Filtros ativos	Estado base	—

Estados obrigatórios

Estado	Representação	Ação disponível
Typing/debounce	Indicador discreto	—
Loading	Skeleton de resultados	—
No results	Sugestões e limpar filtros	Buscar outro
Partial groups	Alguns tipos falham	Retry grupo
Offline	Histórico/estado preservado	Retry

Autenticação e permissões

• Busca pública.
• Busca contextual de gestão pode retornar dados adicionais somente no fluxo autorizado.

Responsividade

• Mobile filtros em bottom sheet.
• Desktop painel lateral e grid/lista conforme tipo.
• URL web representa query e filtros compartilháveis.

Acessibilidade

• Combobox/autocomplete semântico.
• Resultados anunciados.
• Filtros teclado.
• Badges textuais.

Eventos de produto e observabilidade

• search_submitted
• search_type_changed
• search_filter_applied
• search_result_opened
• search_empty_shown

Dados e endpoints

• GET /search e /search/suggestions.
• Endpoints específicos por tipo.
• GET district/neighborhood discovery.

Critérios de aceite

• Todos os tipos previstos.
• Filtros reais.
• Sem boost pago.
• Privacy/status.
• Query vazia útil.

Pós-MVP

• Mapa, raio, busca semântica e recomendações.

Decisões registradas

• Busca neutra.
• Território central.
• Filtros de stats exigem dados públicos.

Machine summary

spec: SPEC-UX-SEARCH-001
screen_or_flow: Telas de busca e descoberta
required_states:
  - loading
  - success
  - empty
  - error
must_use:
  - contracts
  - service
  - hook
  - design_tokens
must_not:
  - direct_fetch
  - direct_fixture_import
  - hardcoded_brand_colors