bugfix-2026-01-23.md

Bugfix 2026-01-23 — Viewer não recebia lições via REST

Contexto

• Backend respondia /v1/catalog com listas vazias (DB Supabase sem seed).
• Viewer, com VITE_USE_REST_SESSION_LESSON=true, não conseguia mapear chapter_id -> lesson_id, gerando lesson_id não encontrado para o capítulo e caindo para WS apenas após erro.

Causa Raiz

• Ambiente de desenvolvimento sem registros em tracks/chapters/lessons; nenhum seed automático.
• Viewer dependia do catálogo REST para iniciar sessão REST; erro não era tratado com fallback limpo.

O que foi feito

1. Fallback no backend: /v1/catalog agora retorna dados derivados de assets/lessons.json quando o DB está vazio (ids lesson_<chapter_id>), mantendo compatibilidade com produção (usa o DB se houver dados).
2. Seeder idempotente: backend/scripts/seed_catalog.py cria/atualiza tracks, capítulos e lições mínimas a partir de assets/lessons.json. Alvo make seed-catalog adicionado e chamado em scripts/dev.sh (best-effort).
3. Hardening do viewer: desabilita o fallback REST se o catálogo vier vazio ou falhar, evita throw, mostra motivo na overlay meta e continua usando WebSocket.
4. Teste: backend/tests/test_catalog_fallback.py garante que o fallback de catálogo retorna lições quando o DB está vazio.

Como reproduzir e validar

1. make backend (ou scripts/dev.sh) — o script de seed roda automaticamente; /v1/catalog deve retornar lições.
2. Em separado: make seed-catalog (idempotente).
3. Abrir o viewer; iniciar capítulo — não deve aparecer erro de lesson_id e a lição carrega via REST ou WS.
4. Teste rápido: PYTHONPATH=backend pytest backend/tests/test_catalog_fallback.py.

Observações

• Analytics continuam desativados se faltarem chaves Supabase (mensagem já existente).
• Fallback não toca produção: só ativa quando as tabelas estão vazias.