[Hugo-JC]

Resumo

• Faz o endpoint de pesquisa musical consultar primeiro a YouTube Data API v3.
• Remove o filtro rígido de categoria 10 na pesquisa: videoclipes oficiais classificados como Entertainment ou People & Blogs também podem aparecer.
• Mantém a exigência de vídeos incorporáveis, porque o Musify usa o player oficial do YouTube.
• Usa Audius como fallback quando o YouTube não devolve resultados ou está indisponível.
• Adiciona descoberta regional do YouTube em /api/music/trending.
• Adiciona /api/music/recommendations, usando os vídeos curtidos da conta OAuth como sinais para procurar música relacionada.
• Adiciona /api/music/providers para diagnóstico seguro da configuração dos providers, sem expor chaves.
• Isola a cache de recomendações por canal e adiciona testes de pesquisa, prioridade, fallback e cache.
• Adiciona workflow CI para Ruff (regras essenciais) e pytest.

Limite intencional deste PR

Este PR altera apenas o backend e documentação. O adaptador atual do frontend ainda assume o formato específico do Audius em api.ts; será necessária uma integração frontend separada para mapear o modelo YouTube (videoId, source, artists) e entregar as faixas ao player oficial. Por isso, a pesquisa e reprodução YouTube na interface ainda não ficam validadas por este PR.

Validação automatizada

• GitHub Actions: passed no commit 914e81452e1c983ba578f9c5344f9591051a1a16.
• Ruff: passed.
• Pytest: passed.
• Não foi feita uma chamada real à YouTube Data API, porque depende da chave configurada no ambiente de execução.

Teste manual após configuração

1. Confirmar GET /api/music/providers e verificar youtube.configured: true.
2. Procurar uma música que não exista no Audius e confirmar que GET /api/music/search?q=... responde com provider: youtube.
3. Procurar uma música que exista no Audius mas também no YouTube e confirmar prioridade YouTube.
4. Desligar/indisponibilizar a YouTube API e confirmar fallback Audius.
5. Ligar uma conta YouTube com vídeos curtidos e consultar GET /api/music/recommendations; confirmar personalized: true quando os gostos estão disponíveis.

Estado: continua em draft; não fazer merge até a integração frontend e a validação funcional de ponta a ponta.