# Implementação do Relatório de Perguntas Frequentes (Frequent Questions Report)

## Objetivo

Implementar um novo relatório no dashboard do Chatwoot que exiba as perguntas mais frequentes (motivos de contato) clusterizados automaticamente por IA, utilizando os dados extraídos durante a resolução das conversas.

## Contexto

Diferente da funcionalidade de FAQ do Captain AI (que foca em RAG para o assistente responder), este relatório foca em **insights gerenciais**. Ele utiliza o `AutoLabelJob` para extrair uma pergunta canônica e o `ClusterJob` para agrupar essas perguntas em temas comuns.

## Passos Realizados

### Backend

1. **Modelo e Migração**:
   - Criação da tabela `frequent_questions` (`account_id`, `label`, `question_text`, `occurrence_count`, `cluster_date`).
   - Arquivo: `db/migrate/20260119150720_create_frequent_questions.rb`.
   - Modelo: `app/models/frequent_question.rb`.
2. **Associação em Account**:
   - Adicionada associação `has_many :frequent_questions` no modelo `Account` para permitir acesso direto via `Current.account`.
3. **Extração de Dados**:
   - O `AutoLabelJob` (`app/jobs/conversations/auto_label_job.rb`) extrai a dúvida canônica e salva em `conversation.additional_attributes['ai_canonical_question']`.
4. **Processamento de Clusters**:
   - Criação do `Conversations::ClusterJob` (`app/jobs/conversations/cluster_job.rb`) para agrupar as perguntas canônicas e consolidar as contagens.
   - Agendamento diário (00:00 UTC) em `config/schedule.yml`.
5. **API**:
   - Controller: `app/controllers/api/v1/accounts/frequent_questions_controller.rb`.
   - Rota: `/api/v1/accounts/:account_id/frequent_questions`.
   - View: `app/views/api/v1/accounts/frequent_questions/index.json.jbuilder`.

### Frontend

1. **API Client**: `app/javascript/dashboard/api/frequentQuestions.js`.
2. **Traduções**: Adicionadas chaves `FREQUENT_QUESTIONS` em `app/javascript/dashboard/i18n/locale/pt_BR/report.json`.
3. **Componente de UI**: `app/javascript/dashboard/routes/dashboard/settings/reports/FrequentQuestionsIndex.vue` redesenhado com padrão premium (ReportHeader, V4Button, estados de loading, sombras suaves).
4. **Roteamento**: Adicionada rota `frequent_questions` em `app/javascript/dashboard/routes/dashboard/settings/reports/reports.routes.js`.
5. **Navegação**: Link adicionado ao Sidebar em `app/javascript/dashboard/components-next/sidebar/Sidebar.vue`.

## Como Validar ou Reverter

### Validação

1. Navegue até **Relatórios** > **Perguntas Frequentes**.
2. Verifique se a lista de clusters é exibida corretamente.
3. Para testar o processamento, rode: `bundle exec rails runner script/generate_test_questions.rb`.

### Reversão

1. Remover a rota em `config/routes.rb`.
2. Reverter os arquivos de frontend alterados.
3. Dropar a tabela: `bundle exec rails db:rollback`.

## Observações Técnicas (Riscos e Decisões)

- **Risco de Performance**: O agrupamento via LLM pode ser caro. O `ClusterJob` foi agendado diariamente para mitigar custo e processamento em tempo real.
- **Diferenciação**: Explicitamente separado do Captain FAQ para evitar poluição da base de conhecimento do assistente com dados puramente analíticos.
- **Blocker Externo**: Houve um erro de `TypeError` na gem `annotaterb` durante as migrações no ambiente (problema preexistente), mas a tabela foi criada com sucesso e a execução pôde prosseguir.