docs(qa): RAG implementado e provado, e a cadeia do audio

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014eDYqCWr7Zrs99vLjqGj8r

Author: melgarafael

docs/testing/user-journey-map.md

@@ -281,3 +281,46 @@ espaço e acento, que era o gatilho do defeito #6.
 | 28 | 🟠 **CI vermelho por lentidão, não por defeito.** O teste que abre processo filho (`npx tsx`) leva ~5s e o timeout padrão do vitest é 5s — derrubou a `main` num PR que só mexia em documentação | corrigido — timeout explícito de 60s; 3 rodadas seguidas verdes. O controle positivo continua provando o aparato |
 
 **Nota de ambiente:** o `.env` da VPS foi apontado para `ghcr.io/...:latest` durante o QA, porque o fluxo de release novo fixa a imagem numa tag (`1.1.0`) e as correções desta sessão estão à frente dela. Para voltar ao comportamento de release, basta repor `APP_IMAGE` com a tag desejada.
+
+## RAG do tenant — implementado e provado (2026-07-30)
+
+Autorizado pelo dono, o RAG saiu do stub. **Cinco defeitos encadeados**: cada
+conserto revelava o próximo, e nenhum aparecia sem rodar de verdade.
+
+| # | Defeito | Como apareceu |
+|---|---|---|
+| 29 | Handler de `knowledge_source.updated` era stub declarado | só `nuvemshop.product_synced` indexava — e a Nuvemshop vem desligada |
+| 30 | `ON CONFLICT` apontava para constraint **inexistente** | *"there is no unique or exclusion constraint matching"* — TODO chunk falhava. **O mesmo alvo errado estava no caminho de produto**: o RAG nunca gravou um chunk, para nenhuma fonte |
+| 31 | `token_count` é NOT NULL e ninguém preenchia | *"null value in column token_count"* |
+| 32 | 🔴 Versão **vazia** era marcada `ready` e **ativada** | numa instalação com base funcionando, uma indexação com problema trocaria a base boa por uma vazia — o agente perderia o RAG em silêncio |
+| 33 | Fonte tipo `policy` era criada **vazia**, conteúdo descartado | a rota só tratava `source_type === "faq"`; política enviada com markdown voltava 201 com o conteúdo no lixo |
+| 34 | 🔴 Limiar padrão **0.72** descartava toda paráfrase | medido: relevante 0.49–0.85, irrelevante 0.27. Só a pergunta **literal** passava — o RAG parecia quebrado funcionando bem |
+
+**Decisão de arquitetura tomada** (a que faltava para destravar): a reindexação
+**reconstrói UMA versão com TODAS as fontes**, em vez de uma versão por fonte —
+a busca recebe um único `kb_version_id` e o agente aponta para uma única versão
+ativa; uma versão por fonte faria o FAQ desativar o catálogo e vice-versa.
+
+**Prova final, medida:** FAQ (4 itens) + Política (2 itens) → versão 5 com 6
+chunks, ativa. Busca atravessando as duas fontes:
+
+| Pergunta | Acerto | Semelhança |
+|---|---|---|
+| "quanto tempo demora pra chegar em BH?" | FAQ — prazo BH | 0.653 |
+| "e se eu quiser devolver o produto?" | Política — devolução | 0.649 |
+| "tem garantia?" | Política — garantia | 0.690 |
+| "aceita pix?" | FAQ — pagamento | 0.490 |
+
+E a tela ganhou o cadastro que faltava: o botão "Configurar" era stub `disabled`
+com um toast que nunca aparecia.
+
+## Áudio do WhatsApp
+
+| # | Defeito | Estado |
+|---|---|---|
+| 35 | 🔴 **A transcrição mandava a chave da Anthropic para a OpenAI.** O Whisper é da OpenAI, mas recebia `llm.apiKey` (provedor de chat da org) → `transcription_401` em toda tentativa, com a `OPENAI_API_KEY` certa no `.env` | corrigido — fallback de ambiente para OpenAI, simétrico ao que a Anthropic já tinha |
+| 36 | 🟠 **O agente responde ANTES de a mídia ser derivada** — dispatch às 20:24:22, derivação pedida às 20:25:03 | **aberto**: é ordenação de pipeline, não conserto pontual |
+
+Prova: áudio real recebido (`type: audio`), agente respondeu *"não consigo ouvi-lo"*.
+Com o 35 corrigido a transcrição passa a rodar; o 36 faz a PRIMEIRA resposta
+ainda sair antes dela.