agenciapsilmno/database-novo/tmp/import-doc-relatorios-export.sql

-- Importacao da doc Relatorios e exportacao (Fase 5 #13)
-- Gerado a partir de development/saas-docs/07-relatorios-export-melissa.json
BEGIN;

DO $IMPORT$
DECLARE
    v_doc_id uuid;
BEGIN
    INSERT INTO public.saas_docs (
        titulo, conteudo, categoria, exibir_no_faq, tipo_acesso,
        pagina_path, ordem, ativo, medias
    ) VALUES (
        'Relatórios de sessões e exportação',
        $HTML$<h2>Relatórios de sessões e exportação</h2>

<p>A página <strong>Relatórios</strong> (acessível em <code>/melissa/relatorios</code> ou Prontuários → Relatórios) consolida as sessões num período escolhido com KPIs, gráfico de evolução e tabela detalhada. Você pode <strong>exportar tudo pra PDF, Excel ou CSV</strong> respeitando os filtros aplicados.</p>

<h3>1. Layout 2-col</h3>
<ul>
  <li><strong>Sidebar esquerda</strong> (~280px): cards de estatísticas clicáveis (atuam como filtros) + seletor de período + filtro por status</li>
  <li><strong>Main direita</strong>: gráfico de evolução (Chart.js) + DataTable de sessões filtradas com paginação</li>
</ul>
<p><strong>Mobile</strong> (&lt;1024px): sidebar vira drawer acessado por botão "Filtros" no header.</p>

<h3>2. Filtros de período</h3>
<p>4 opções no seletor:</p>
<ul>
  <li><strong>Esta semana</strong> — domingo a sábado da semana atual</li>
  <li><strong>Este mês</strong> (default) — primeiro dia ao último dia do mês corrente</li>
  <li><strong>Últimos 3 meses</strong> — janela rolante de 3 meses até o fim do mês atual</li>
  <li><strong>Últimos 6 meses</strong> — idem, janela de 6 meses</li>
</ul>
<p>Ao trocar o período, dispara uma nova query no banco. Os KPIs, gráfico e tabela se atualizam.</p>

<h3>3. Estatísticas (KPIs)</h3>
<p>Sidebar mostra cards com contadores do período:</p>
<ul>
  <li><strong>Total de sessões</strong> — todas independente de status</li>
  <li><strong>Realizadas</strong> — concluídas com sucesso</li>
  <li><strong>Faltas</strong> — paciente faltou</li>
  <li><strong>Cancelamentos</strong> — sessão cancelada</li>
  <li><strong>Remarcadas</strong> — paciente remarcou</li>
</ul>
<p>Cada card é <strong>clicável</strong>: filtra a tabela mostrando apenas as sessões daquele status. Clique no mesmo card pra desfazer o filtro.</p>

<h3>4. Gráfico de evolução</h3>
<p>Gráfico de barras/linhas (Chart.js) mostrando a evolução de sessões no período. O agrupamento adapta automaticamente:</p>
<ul>
  <li><strong>Semana / Mês</strong> → agrupa por <strong>dia</strong></li>
  <li><strong>3 meses / 6 meses</strong> → agrupa por <strong>semana ISO</strong> ou <strong>mês ISO</strong></li>
</ul>
<p>Cores por status (verde = realizadas, vermelho = faltas, amarelo = canceladas, azul = remarcadas).</p>

<h3>5. Tabela detalhada</h3>
<p>DataTable com colunas: data/hora, paciente, modalidade, status, valor (se aplicável), forma de pagamento. Paginada (15 por página default), ordenável por qualquer coluna. Status com tag colorida.</p>

<h3>6. Exportação — 3 formatos</h3>
<p>3 botões no topo da tabela (ou header da página dependendo do layout):</p>

<table>
  <thead>
    <tr><th>Botão</th><th>Formato</th><th>Quando usar</th></tr>
  </thead>
  <tbody>
    <tr><td><strong>📄 PDF</strong></td><td>PDF A4</td><td>Apresentar pra contador, anexar a processo, arquivo formal com identidade visual da clínica</td></tr>
    <tr><td><strong>📊 Excel</strong></td><td>XLSX</td><td>Análise no Excel/Google Sheets, fórmulas, gráficos próprios, manipulação fina</td></tr>
    <tr><td><strong>📋 CSV</strong></td><td>CSV UTF-8</td><td>Importar em outro sistema, processamento via script, BI externo</td></tr>
  </tbody>
</table>

<div style="background: rgba(34,197,94,0.06); border: 1px solid rgba(34,197,94,0.25); border-radius: 10px; padding: 12px 14px; margin: 14px 0; font-size: 0.85rem;">
  <strong>🎯 Os filtros aplicados na tela são respeitados</strong> — se você filtrou por "Realizadas" e exportou pra Excel, só as realizadas vão pro arquivo. Período idem. Quer todos os status? clique no card de filtro pra desfazer antes de exportar.
</div>

<h3>7. Detalhes técnicos por formato</h3>

<h4>PDF</h4>
<ul>
  <li>Renderizado client-side via HTML → PDF (mesmo pipeline do gerador de documentos)</li>
  <li>Cabeçalho com KPIs em destaque + tabela A4 abaixo</li>
  <li>Identidade visual: nome da clínica, logo (se cadastrado), data de geração</li>
  <li>Tamanho: 1 página por ~30 sessões; relatórios longos paginam automaticamente com cabeçalho/rodapé fixos</li>
</ul>

<h4>Excel (XLSX)</h4>
<ul>
  <li>Gerado com <code>exceljs</code> (import dinâmico — não infla o bundle inicial)</li>
  <li><strong>Frozen header</strong> — primeira linha fica fixa ao rolar</li>
  <li><strong>Alternating rows</strong> — zebrado pra leitura</li>
  <li>Colunas formatadas: data como data, valor como currency BRL</li>
  <li>Branded — cabeçalho com cor da clínica</li>
</ul>

<h4>CSV</h4>
<ul>
  <li>Vanilla JS — sem dependência externa, gerado instantaneamente</li>
  <li><strong>BOM UTF-8</strong> no início — força Excel a abrir com acentos corretos</li>
  <li><strong>Separador <code>;</code></strong> (padrão pt-BR — Excel BR espera ; em vez de ,)</li>
  <li>Aspas em campos com vírgula ou quebra de linha</li>
</ul>

<h3>8. Nome do arquivo gerado</h3>
<p>Padrão <code>relatorio_sessoes_AAAAMMDD_HHmm.{pdf|xlsx|csv}</code> com timestamp da hora de geração. Garante que múltiplas exportações no mesmo dia não sobrescrevem.</p>

<h3>⚠️ Notas pro desenvolvedor</h3>
<ul>
  <li><strong>Service:</strong> <code>src/services/reportExport.service.js</code> com 3 funções: <code>exportSessionsToPDF</code>, <code>exportSessionsToXLSX</code>, <code>exportSessionsToCSV</code>. Todas aceitam <code>{ sessions, period, statusFilter, tenant }</code>.</li>
  <li><strong>PDF:</strong> usa <code>pdf.service.htmlToPdfBlob</code> (mesmo do gerador de documentos)</li>
  <li><strong>XLSX:</strong> <code>const { default: ExcelJS } = await import('exceljs')</code> — code splitting</li>
  <li><strong>CSV:</strong> vanilla JS com BOM + escape de campos</li>
  <li><strong>Pages:</strong> <code>RelatoriosPage.vue</code> (rota classic/Rail) e <code>MelissaRelatorios.vue</code> (rota Melissa) compartilham o mesmo service</li>
  <li><strong>Pendência:</strong> exportação agendada (envio automático por email no dia 1 de cada mês) — depende do Módulo 6 notifications. Hoje só on-demand.</li>
</ul>$HTML$,
        'Relatórios',
        true,
        'usuario',
        '/melissa/relatorios',
        7,
        true,
        '[{"tipo": "imagem", "url": ""}]'::jsonb
    )
    RETURNING id INTO v_doc_id;

    INSERT INTO public.saas_faq_itens (doc_id, pergunta, resposta, ordem, ativo) VALUES
    (v_doc_id, 'Como vejo um resumo das minhas sessões num período?',
     $FAQ$Abra a página <strong>Relatórios</strong> (menu Prontuários → Relatórios, ou diretamente em <code>/melissa/relatorios</code>). Você escolhe o período na sidebar esquerda (esta semana, este mês, últimos 3 ou 6 meses) e o sistema mostra KPIs em cards, gráfico de evolução e tabela detalhada de cada sessão.$FAQ$, 0, true),

    (v_doc_id, 'Quais períodos posso filtrar?',
     $FAQ$4 opções fixas no seletor: <strong>Esta semana</strong> (domingo a sábado da semana corrente), <strong>Este mês</strong> (default — dia 1 ao último dia do mês atual), <strong>Últimos 3 meses</strong> e <strong>Últimos 6 meses</strong> (janelas rolantes terminando no fim do mês atual). Não há custom date range na UI ainda — pra filtrar uma data específica, exporte pra Excel ou CSV e filtre lá.$FAQ$, 1, true),

    (v_doc_id, 'Como exporto o relatório pra PDF?',
     $FAQ$No topo da página de Relatórios, clique no botão <strong>PDF</strong> (ícone vermelho de arquivo). O sistema renderiza o relatório com KPIs em destaque + tabela A4 e dispara o download. Útil pra apresentar pra contador, anexar a processos ou arquivar formalmente. O PDF traz a identidade visual da clínica (nome, logo se cadastrado, data de geração).$FAQ$, 2, true),

    (v_doc_id, 'Como exporto pra Excel?',
     $FAQ$Botão <strong>Excel</strong> (ícone verde) no topo da página. Gera um arquivo <code>.xlsx</code> com cabeçalho fixo (frozen header), linhas zebradas pra leitura, colunas formatadas (datas como data, valores como moeda BRL) e cabeçalho com cor da clínica. Pronto pra análise no Excel, Google Sheets ou LibreOffice.$FAQ$, 3, true),

    (v_doc_id, 'Quando devo usar CSV em vez de Excel?',
     $FAQ$Use <strong>CSV</strong> quando precisar importar os dados em outro sistema (ERP, BI, banco de dados), fazer processamento via script, ou compartilhar com alguém que não tenha Excel. O arquivo é mais leve e universal. Use <strong>Excel</strong> quando o destino final for análise humana — formatação de moeda, gráficos próprios, fórmulas. Os 2 trazem os mesmos dados.$FAQ$, 4, true),

    (v_doc_id, 'Os filtros aplicados na tela também valem pra exportação?',
     $FAQ$<strong>Sim, sempre.</strong> Se você filtrou por "Realizadas" clicando no card de KPI, só as sessões realizadas vão pro arquivo exportado. Período idem. Quer exportar todos os status? clique no card de filtro pra desfazer (ou clique em outro KPI e depois nele de novo) antes de exportar. Na dúvida, o título do PDF/Excel sempre traz os filtros aplicados na primeira linha.$FAQ$, 5, true),

    (v_doc_id, 'O Excel exportado tem fórmulas ou só dados?',
     $FAQ$Só dados. As colunas vêm formatadas (data como data, valor como moeda BRL) mas sem fórmulas pré-instaladas — você adiciona o que precisar depois (somas, médias, gráficos). Decisão de design: pra evitar conflito com diferentes locales/versões do Excel, exportamos puro e você customiza.$FAQ$, 6, true),

    (v_doc_id, 'Por que o gráfico às vezes mostra dias e às vezes semanas/meses?',
     $FAQ$Agrupamento automático conforme o período pra evitar gráfico ilegível: <strong>Semana / Mês</strong> → 7-31 colunas por dia (legível). <strong>3 meses</strong> → ~13 colunas por semana ISO. <strong>6 meses</strong> → ~26 colunas ou ~6 colunas por mês ISO. Se forçássemos 180 colunas em "6 meses", ficaria ilegível.$FAQ$, 7, true),

    (v_doc_id, 'Posso filtrar o relatório por um paciente específico?',
     $FAQ$Hoje não diretamente na página de Relatórios. Pra ver sessões de um paciente específico, vá no <strong>prontuário do paciente</strong> (aba Sessões) — lá tem timeline completa com filtros próprios. Ou exporte o relatório geral pra Excel/CSV e filtre por nome do paciente no Excel.$FAQ$, 8, true),

    (v_doc_id, 'Consigo ver o relatório de outro terapeuta da clínica?',
     $FAQ$Depende da sua permissão no tenant. Por default, cada terapeuta vê só as próprias sessões. Owners/admins do tenant podem ter acesso aos relatórios consolidados de todos os profissionais — verifique em <strong>Configurações → Equipe</strong> qual é seu papel. Pra solicitar acesso ampliado, fale com o owner do tenant.$FAQ$, 9, true),

    (v_doc_id, 'Como ficam os nomes dos arquivos exportados?',
     $FAQ$Padrão <code>relatorio_sessoes_AAAAMMDD_HHmm.{pdf|xlsx|csv}</code>. Exemplo: <code>relatorio_sessoes_20260522_1430.xlsx</code>. Timestamp garante que múltiplas exportações no mesmo dia não sobrescrevem o anterior — fica fácil organizar versões.$FAQ$, 10, true),

    (v_doc_id, 'Posso agendar exportações automáticas (envio por email mensal)?',
     $FAQ$Ainda não. Hoje a exportação é <strong>on-demand</strong> — você precisa abrir a página e clicar no botão. Exportação agendada (ex: PDF mensal enviado por email no dia 1) está no roadmap pós-MVP, depende do Módulo 6 (notifications factory channel) que ainda não foi implementado. Por enquanto, agende um lembrete pra você abrir a página todo dia 1.$FAQ$, 11, true);

    RAISE NOTICE 'Doc criada: id=%, faq_itens=12', v_doc_id;
END;
$IMPORT$;

COMMIT;