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

depends_on: SPEC-DOMAIN-TERRITORY-001, SPEC-DOMAIN-PLAYER-001, SPEC-DOMAIN-TEAM-001

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

Busca e descoberta

Busca universal pública, filtros por tipo e descoberta territorial neutra.

Objetivo e limites

Esta especificação define o comportamento canônico do domínio Busca e descoberta no RaizFC. Ela deve ser consultada antes de alterar contratos, mocks, endpoints, telas, permissões ou Increment Specifications relacionados.

Incluído no MVP

• Busca universal por texto.
• Tipos player, team, championship, torcida, field, service, district, neighborhood e match.
• Filtros avançados por tipo.
• Sugestões/autocomplete.
• Descoberta por distrito/bairro.

Fora do MVP

• Busca semântica por IA.
• Mapa/raio.
• Boost pago.
• Recomendação personalizada avançada.

Atores e responsabilidades

Ator	Responsabilidade
Visitante	Busca entidades públicas.
Usuário	Recebe descoberta contextual e histórico opcional.
Gestor	Encontra jogadores, times e serviços para fluxos de gestão.
Sistema	Indexa DTOs públicos e aplica privacidade/status.

Conceitos canônicos

Search Document

Representação pública indexável.

Universal Search

Consulta agregada multi-tipo.

Discovery Section

Coleção editorial/algorítmica por território e atividade.

Search Badge

Contexto como Provisório, Livre, Final ou Abandonado.

Invariantes

• Somente dados públicos e permitidos entram no índice.
• Patrocínio não altera ordenação.
• Entidade suspended não aparece.
• Abandoned pode aparecer com prioridade menor e badge.
• Draft de campeonato não aparece.
• Jogador privado não aparece.
• Ordenação combina relevância textual, atividade/confiabilidade e contexto, sem substituir filtros explícitos.

Estados

Estado	Significado	Visibilidade/efeito
indexed	Disponível	Busca normal.
hidden	Não indexável	Privacidade/status.
stale	Aguardando atualização	Pode usar último snapshot com cautela.
removed	Excluído do índice	Não retorna.

Transições permitidas

Origem	Ação	Destino	Autoridade	Efeitos
—	index	indexed	Indexer	Cria documento.
indexed	hide	hidden	Privacidade/status	Remove resultados.
indexed	mark_stale	stale	Sistema	Agenda rebuild.
any	remove	removed	Indexer	Exclui.

Permissões

Permission key	Quem recebe por padrão	Ação protegida	Auditoria
search.public	Público	Buscar DTOs públicos	Não
search.managementContext	Gestor	Busca contextual adicional	Não
search.reindex	Sistema/operação	Reindexar	Sim

Fluxos funcionais

Busca universal

1. Cliente envia q, types, território e paginação.
2. Backend normaliza consulta.
3. Aplica filtros de status/privacidade.
4. Busca índices/queries por tipo.
5. Unifica resultados em SearchResultDto com score interno.
6. Retorna grupos/ordem e sugestões.

Busca de jogadores

1. Filtros incluem posição, distrito, status livre, time, stats públicas e período.
2. Métricas derivadas usam partidas validadas.
3. Ordenação por média só aparece quando amostra mínima é satisfeita.

Descoberta territorial

1. Página de distrito/bairro pede coleções de times, jogos, campeonatos, torcidas e serviços.
2. Ordenação prioriza atividade recente e confiabilidade, não pagamento.

Casos-limite e erros

Cenário	Comportamento esperado	Código/estado
Query vazia	Retornar sugestões/descoberta, não erro	—
Filtro inválido	Validation error por campo	VALIDATION_ERROR
Entidade merged	Retornar canônica/redirect	ENTITY_MERGED
Stats privadas	Ignorar filtro/resultado que exigiria exposição	PRIVACY_FILTERED
Página além do fim	Lista vazia com meta válida	—

Privacidade e exposição pública

• Histórico de busca do usuário não é público.
• Autocomplete não revela e-mail/telefone.
• Filtros de stats respeitam privacidade.
• Busca de gestão pode retornar mais contexto somente após permission check.

Notificações e auditoria

• Não gera notificações comuns.
• Mudança de status/privacidade dispara reindex interno e observabilidade.

API relacionada

Método	Rota	Acesso	Finalidade
GET	/api/v1/search	Público	Universal
GET	/api/v1/search/suggestions	Público	Autocomplete
GET	/api/v1/search/teams	Público	Times
GET	/api/v1/search/players	Público	Jogadores
GET	/api/v1/search/matches	Público	Partidas
GET	/api/v1/search/championships	Público	Campeonatos
GET	/api/v1/search/torcidas	Público	Torcidas
GET	/api/v1/search/fields	Público	Campos
GET	/api/v1/search/services	Público	Serviços
GET	/api/v1/districts/:id/discovery	Público	Descoberta

Contratos compartilhados

• SearchResultType
• SearchResultDto
• SearchBadgeDto
• UniversalSearchQuery/Response
• TeamSearchFilters
• PlayerSearchFilters
• MatchSearchFilters
• DiscoverySectionDto

Requisitos de UX

• Aba Buscar inicia universal e permite trocar tipo sem perder query.
• Filtros aparecem em bottom sheet no mobile e painel lateral no desktop.
• Resultados deixam claro tipo, território, badges e métricas relevantes.
• Busca vazia oferece descoberta territorial.

Comportamento dos mocks

• Resultados multi-tipo.
• Empty, typo/suggestions, suspended filtered, abandoned badge, private player.
• Filtros funcionais, não apenas decorativos.

Critérios de aceite

• Público sem login.
• Privacidade/status respeitados.
• Sem boost pago.
• Filtros por tipo.
• Paginação/meta consistente.

Testes obrigatórios

• Index visibility.
• Relevância básica.
• Filtros.
• Merged/suspended/private.
• Universal aggregation.
• Pagination.

Pós-MVP

• Busca semântica, geográfica, recomendação e mapas.

Decisões registradas

• Busca é neutra.
• Território é filtro central.
• Patrocínio não compra posição.

Machine summary

spec: SPEC-DOMAIN-SEARCH-001
domain: Busca e descoberta
must_preserve:
  - Somente dados públicos e permitidos entram no índice.
  - Patrocínio não altera ordenação.
  - Entidade suspended não aparece.
  - Abandoned pode aparecer com prioridade menor e badge.
  - Draft de campeonato não aparece.
  - Jogador privado não aparece.
  - Ordenação combina relevância textual, atividade/confiabilidade e contexto, sem substituir filtros explícitos.
touches:
  - contracts
  - mocks
  - api
  - frontend
  - backend
  - tests
  - documentation