saas-docs: doc Relatorios e exportacao (Fase 5 #13)

Doc 07 cobrindo a pagina de Relatorios + 3 formatos de exportacao:
- Layout 2-col (sidebar stats+filtros, main grafico+tabela)
- 4 periodos (semana/mes/3m/6m), agrupamento auto (dia vs week ISO
  vs month ISO)
- 5 KPIs clicaveis como filtros (total/realizadas/faltas/canc/remarc)
- Grafico Chart.js com cores por status
- DataTable paginada + status com tag colorida
- Export PDF (HTML->PDF A4, KPIs + tabela)
- Export Excel XLSX (exceljs dinamico, frozen header, alternating
  rows, branded, formatos data+currency)
- Export CSV (vanilla, BOM UTF-8, separador ; pt-BR)
- Filtros aplicados na tela respeitados na exportacao
- Nome do arquivo com timestamp pra evitar overwrite
- Notas dev: reportExport.service.js, pdf.service, exceljs lazy load

12 FAQs: como ver, periodos disponiveis, exportar PDF/Excel/CSV,
quando usar qual formato, filtros respeitados, formulas, agrupamento
do grafico, filtrar por paciente, ver outro terapeuta, nome do
arquivo, exportacao agendada (pendente).

categoria='Relatórios', pagina_path='/melissa/relatorios', ordem=7.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

database-novo/tmp/backfill-document-generated-link.sql

@@ -0,0 +1,39 @@
+-- Backfill: linkar document_generated.documento_id em registros antigos
+-- pra suportar re-edicao in-place de documentos gerados.
+--
+-- O codigo novo (DocumentGenerate.service.js saveGeneratedDocument) ja
+-- preenche o documento_id no INSERT pra criacoes novas. Este script eh
+-- one-off pra docs gerados ANTES desse fix.
+--
+-- Match: dg.pdf_path = d.bucket_path + match de tenant/patient pra evitar
+-- linkar a doc errado em caso colidente. Registros sem match (paths que
+-- nao existem mais em documents — docs deletados/cleanup) ficam orfaos
+-- com documento_id=NULL: nao quebra nada, so nao tem caminho de re-edit.
+
+BEGIN;
+
+UPDATE public.document_generated dg
+SET documento_id = d.id
+FROM public.documents d
+WHERE dg.documento_id IS NULL
+  AND dg.pdf_path = d.bucket_path
+  AND dg.patient_id = d.patient_id
+  AND dg.tenant_id = d.tenant_id
+  AND d.deleted_at IS NULL;
+
+-- Relatorio pos-backfill
+DO $REPORT$
+DECLARE
+    v_linked int;
+    v_orphans int;
+BEGIN
+    SELECT count(*) FILTER (WHERE documento_id IS NOT NULL),
+           count(*) FILTER (WHERE documento_id IS NULL)
+    INTO v_linked, v_orphans
+    FROM public.document_generated;
+    RAISE NOTICE 'document_generated: % linked, % orphans (sem documents correspondente)',
+        v_linked, v_orphans;
+END;
+$REPORT$;
+
+COMMIT;

database-novo/tmp/import-doc-assinatura-eletronica.sql

@@ -0,0 +1,166 @@
+-- Importacao da doc Assinatura eletronica de documentos (Fase 3 #7)
+-- Gerado a partir de development/saas-docs/05-assinatura-eletronica-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 (
+        'Assinatura eletrônica de documentos',
+        $HTML$<h2>Assinatura eletrônica de documentos</h2>
+
+<p>O sistema permite enviar documentos clínicos (TCLE, contratos, autorizações, laudos) pro paciente assinar <strong>sem que ele precise ter login</strong>. O fluxo registra a assinatura com hash do conteúdo, IP, user-agent e timestamp — gerando um audit trail compliance LGPD/CFP.</p>
+
+<h3>1. Visão geral do fluxo</h3>
+<ol>
+  <li><strong>Terapeuta</strong> abre o documento no prontuário e clica em <em>Assinar</em></li>
+  <li>Adiciona os signatários (nome + email) e ativa <em>"Gerar link público para assinatura"</em></li>
+  <li>Sistema cria signature requests + um <strong>link público temporário</strong> com token</li>
+  <li>Terapeuta copia a URL e envia pro paciente (WhatsApp, email, SMS — manual por enquanto)</li>
+  <li><strong>Paciente</strong> abre o link em qualquer navegador, lê o documento, marca o checkbox de aceite LGPD e clica <em>Assinar</em></li>
+  <li>Sistema computa SHA-256 do PDF baixado, registra assinatura via RPC server-side (IP/UA capturados pelo banco)</li>
+  <li>Terapeuta vê o status atualizado no documento (pendente → assinado)</li>
+</ol>
+
+<h3>2. Lado terapeuta — criar solicitação</h3>
+<p>No preview de um documento (na aba <em>Documentos</em> do prontuário), clique no botão <strong>Assinar</strong> na sidebar de ações. O <em>DocumentSignatureDialog</em> abre com:</p>
+<ul>
+  <li><strong>Lista de signatários:</strong> adicione um ou mais — pra cada um, nome + email são obrigatórios. O paciente principal vem pré-preenchido se disponível.</li>
+  <li><strong>Toggle "Gerar link público para assinatura"</strong> (default ON): cria um share_link junto com as signature requests. Sem isso, só fica a request registrada — o paciente precisa logar no portal pra assinar.</li>
+  <li><strong>Select de validade do link:</strong> 24h / 3 dias / 7 dias / 30 dias. Default 7 dias (168h).</li>
+  <li><strong>Submit:</strong> cria as requests + link e mostra a URL pronta pra copiar.</li>
+</ul>
+
+<h3>3. Lado paciente — link público (sem login)</h3>
+<p>Ao abrir o link <code>/shared/document/:token</code>, o paciente vê:</p>
+<ul>
+  <li><strong>Preview do PDF</strong> inline (iframe)</li>
+  <li><strong>Painel azul</strong> embaixo do preview com:
+    <ul>
+      <li>Aviso LGPD/CFP explicando o que vai ser registrado</li>
+      <li>Checkbox <em>"Li o documento e concordo com seu conteúdo"</em> (bloqueia botões até marcado)</li>
+      <li>Select de signatário (se houver mais de um cadastrado)</li>
+      <li>Botões <strong>Assinar</strong> (emerald) e <strong>Recusar</strong> (rose)</li>
+    </ul>
+  </li>
+</ul>
+
+<p>Ao clicar Assinar:</p>
+<ol>
+  <li>Sistema baixa o PDF e computa <strong>SHA-256</strong> client-side (proof of integrity — se o doc foi alterado depois, hash não bate)</li>
+  <li>Chama a RPC <code>sign_document_by_token</code> passando o hash</li>
+  <li>RPC captura <strong>IP via inet_client_addr()</strong> e <strong>user-agent via current_setting('request.headers')</strong> — server-side, à prova de spoof client-side</li>
+  <li>Registra em <code>document_signatures</code>: timestamp, hash, IP, UA, status='assinado'</li>
+  <li>Mostra tela de confirmação "Documento assinado com sucesso"</li>
+</ol>
+
+<h3>4. Audit trail registrado</h3>
+<p>Cada assinatura grava:</p>
+<ul>
+  <li><strong>signatario_id</strong> (se o signatário tem cadastro como paciente vinculado)</li>
+  <li><strong>signatario_nome</strong> e <strong>signatario_email</strong> (do que foi cadastrado pelo terapeuta)</li>
+  <li><strong>assinado_em</strong> — timestamp da RPC (server time, não client clock)</li>
+  <li><strong>assinatura_hash</strong> — SHA-256 do PDF no momento da assinatura</li>
+  <li><strong>ip_address</strong> — capturado server-side (anti-spoof)</li>
+  <li><strong>user_agent</strong> — header HTTP via current_setting</li>
+  <li><strong>status</strong> — pendente / enviado / assinado / recusado / expirado</li>
+</ul>
+
+<div style="background: rgba(16,185,129,0.08); border: 1px solid rgba(16,185,129,0.3); border-radius: 10px; padding: 12px 14px; margin: 14px 0; font-size: 0.85rem;">
+  <strong>🛡️ Por que server-side?</strong> Capturar IP/UA no banco via <code>inet_client_addr()</code> é anti-spoof: o cliente não consegue forjar valores arbitrários. Garante que o audit trail reflete a sessão HTTP real, não um POST manipulado.
+</div>
+
+<h3>5. Recusar a assinatura</h3>
+<p>O paciente pode <strong>recusar</strong> em vez de assinar — útil se ele não concorda com o conteúdo. Click em <strong>Recusar</strong> abre um <em>confirm</em>; ao confirmar, o sistema registra a recusa (com timestamp + IP/UA da mesma forma) e marca a request como <code>status='recusado'</code>. O terapeuta vê isso na lista de signature requests e pode entrar em contato pra ajustar o documento.</p>
+
+<h3>6. Portal do paciente — lista de pendências</h3>
+<p>Pacientes logados no portal (<code>/portal/documentos</code>) veem uma lista de TODOS os documentos solicitados pra eles, com KPIs no topo:</p>
+<ul>
+  <li><strong>Total</strong> · <strong>Pendentes</strong> · <strong>Assinados</strong> · <strong>Recusados</strong></li>
+</ul>
+<p>Filtro por status (todos / pendentes / assinados) + lista. Click em <strong>Assinar agora</strong> num item pendente leva pro <code>/shared/document/:token</code> (mesma página pública, mas com auth já garantida via portal).</p>
+
+<h3>7. Expiração e múltiplos usos</h3>
+<ul>
+  <li><strong>Validade do link:</strong> configurada na criação (24h/3d/7d/30d). Após expirar, retorna 410 Gone. Terapeuta pode gerar novo link pelo botão <em>Compartilhar</em> no preview do doc.</li>
+  <li><strong>Limite de usos:</strong> calculado como <code>max(signatários × 3, 5)</code> — gerar 1 signatário dá 5 usos disponíveis (margem de erro / reload / multi-device).</li>
+  <li><strong>Cada assinatura é única:</strong> mesmo signatário não consegue assinar 2x — a RPC bloqueia se já houver registro com status=assinado.</li>
+</ul>
+
+<h3>8. Múltiplos signatários</h3>
+<p>Documentos como termo de autorização de menor podem precisar de 2+ assinaturas (responsável legal + paciente menor, ou os dois pais). O dialog aceita N signatários; cada um recebe sua própria entry em <code>document_signatures</code>. O link público é o mesmo — quando o paciente abre, escolhe qual signatário ele é no select e assina apenas a sua entry.</p>
+
+<h3>9. Validade legal</h3>
+<p>A assinatura eletrônica registrada pelo sistema atende:</p>
+<ul>
+  <li><strong>LGPD (Lei 13.709/2018):</strong> consentimento explícito registrado com timestamp, IP e UA — base legal Art. 7º I</li>
+  <li><strong>Código de Ética CFP:</strong> documento clínico com identificação inequívoca do signatário (nome+email+IP+hash)</li>
+  <li><strong>MP 2200-2/2001 (ICP-Brasil):</strong> assinatura <em>simples</em> com integridade via hash — não é certificado A1/A3, mas é válida pra documentos sem exigência ICP</li>
+</ul>
+<p>⚠️ Pra documentos que exigem ICP-Brasil (notarial, procuração com poderes especiais), use uma plataforma externa de assinatura qualificada — esse fluxo não substitui.</p>
+
+<h3>⚠️ Notas pro desenvolvedor</h3>
+<ul>
+  <li><strong>RPCs:</strong> <code>sign_document_by_signature_id</code> (paciente logado no portal), <code>sign_document_by_token</code> (link público), <code>get_signable_document_by_token</code> (resolve token → doc + signature_request), <code>list_my_signatures</code> (lista do paciente, cruza por signatario_id, signatario_email e patient.user_id)</li>
+  <li><strong>Service:</strong> <code>DocumentSignatures.service.js</code> com wrappers <code>signByPortal</code>, <code>signByToken</code>, <code>getSignableDocumentByToken</code>, <code>listMySignatures</code>, <code>hashDocument</code>, <code>refuseSignature</code>, <code>createSignatureRequests</code>, <code>createShareLink</code>, <code>buildShareUrl</code></li>
+  <li><strong>Composable:</strong> <code>useDocumentSignatures</code> (Tipo A blueprint)</li>
+  <li><strong>UI lado terapeuta:</strong> <code>DocumentSignatureDialog.vue</code> (component)</li>
+  <li><strong>UI lado paciente:</strong> <code>PortalDocumentos.vue</code> (portal logado) + <code>SharedDocumentPage.vue</code> (link público)</li>
+  <li><strong>Notificação automática</strong> (paciente recebe email/WA quando signature criada) — pendente, depende de Módulo 6 (notifications factory channel)</li>
+</ul>$HTML$,
+        'Documentos',
+        true,
+        'usuario',
+        '/melissa/paciente',
+        5,
+        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 peço pra um paciente assinar um documento (TCLE, contrato, autorização)?',
+     $FAQ$Na aba <strong>Documentos</strong> do prontuário, clique no doc → no preview, clique em <strong>Assinar</strong> (sidebar de ações). O dialog abre. Adicione o paciente como signatário (nome + email), mantenha <em>"Gerar link público para assinatura"</em> marcado, escolha validade (7 dias é o default) e clique em <strong>Solicitar</strong>. O sistema cria a request e mostra uma URL pra copiar. Envie pro paciente via WhatsApp, email, SMS — como preferir.$FAQ$, 0, true),
+
+    (v_doc_id, 'Como o paciente assina sem ter login no sistema?',
+     $FAQ$Ele abre o link público (<code>/shared/document/:token</code>) em qualquer navegador. Vê o PDF inline, lê o aviso LGPD/CFP, marca o checkbox <em>"Li o documento e concordo"</em>, e clica <strong>Assinar</strong>. O sistema computa hash SHA-256 do PDF, chama a RPC server-side que captura IP/User-Agent e registra a assinatura. Nada de cadastro, nada de senha.$FAQ$, 1, true),
+
+    (v_doc_id, 'Que informação fica registrada quando ele assina?',
+     $FAQ$Tudo que precisa pra audit compliance: <strong>nome e email</strong> do signatário (do cadastro), <strong>timestamp server-side</strong> (não do relógio do cliente), <strong>hash SHA-256 do PDF</strong> no momento da assinatura (qualquer alteração posterior invalida a integridade), <strong>IP</strong> e <strong>User-Agent</strong> capturados pelo banco via <code>inet_client_addr()</code> e <code>current_setting('request.headers')</code> — anti-spoof. Tudo fica em <code>public.document_signatures</code>.$FAQ$, 2, true),
+
+    (v_doc_id, 'O terapeuta também precisa assinar o documento?',
+     $FAQ$Depende do tipo. Pra atestados, laudos e declarações, geralmente sim — você gera o PDF a partir do template (que já contém seu nome + registro profissional + assinatura digitalizada se você incluiu no rodapé). Pra contratos e termos com paciente como contraparte, você adiciona você mesmo como segundo signatário no dialog antes de enviar. Cada um abre o link e assina sua entry separadamente.$FAQ$, 3, true),
+
+    (v_doc_id, 'O link tem validade? E se expirar?',
+     $FAQ$Tem. Você escolhe 24h, 3 dias, 7 dias ou 30 dias na hora de criar (default 7d). Depois disso o link retorna erro 410 Gone. Se o paciente não assinou a tempo, gere um novo link: no preview do doc, clique em <strong>Compartilhar</strong> ou abra o dialog de assinatura novamente — vai criar outro token. Limite de usos do link: ~5 (margem pra reload/multi-device), depois também expira.$FAQ$, 4, true),
+
+    (v_doc_id, 'E se o paciente recusar a assinatura?',
+     $FAQ$Tem botão <strong>Recusar</strong> ao lado do <em>Assinar</em>. Clique pede confirmação; ao confirmar, a request fica com <code>status='recusado'</code> com timestamp e IP/UA registrados igual à assinatura. Você vê o status na lista de pendências do doc e na aba do prontuário. Geralmente: ajuste o conteúdo do documento e envie nova solicitação.$FAQ$, 5, true),
+
+    (v_doc_id, 'O paciente pode assinar depois pelo Portal sem precisar do link?',
+     $FAQ$Sim, se ele tem conta de portal. Em <strong>/portal/documentos</strong> aparece a lista de tudo que está pendente pra ele assinar, com KPIs (total, pendentes, assinados, recusados) e botão <strong>Assinar agora</strong> que leva pra mesma página de assinatura. Útil pra pacientes que perderam o link no WhatsApp — eles loga e acha tudo num lugar só.$FAQ$, 6, true),
+
+    (v_doc_id, 'Como compartilho o link com o paciente — tem envio automático?',
+     $FAQ$Hoje o envio é <strong>manual</strong>: o dialog gera a URL, você copia e cola onde quiser (WhatsApp, email, SMS, AirDrop, QR code, link em conversa direta). Envio automático (notificação por WA/email quando signature é criada) está no roadmap, depende do Módulo 6 (notifications factory channel) que ainda não foi implementado.$FAQ$, 7, true),
+
+    (v_doc_id, 'A assinatura tem validade legal mesmo sem certificado ICP-Brasil?',
+     $FAQ$Pra documentos clínicos comuns (TCLE, contrato de prestação, autorizações, declarações entre terapeuta-paciente), <strong>sim</strong>. A assinatura simples com timestamp + hash + IP + UA atende LGPD (Art. 7º I — consentimento explícito) e o Código de Ética do CFP. Pra documentos que exigem certificado ICP-Brasil (notarial, procuração com poderes especiais), use uma plataforma externa de assinatura qualificada — esse fluxo não substitui.$FAQ$, 8, true),
+
+    (v_doc_id, 'O paciente consegue editar o documento antes de assinar?',
+     $FAQ$Não. O paciente <strong>só visualiza</strong> — o PDF é renderizado em iframe e a integridade é garantida pelo hash SHA-256 computado no momento da assinatura. Se o conteúdo precisar mudar, é você que ajusta o documento (editar via template ou regenerar) e envia nova solicitação. A assinatura antiga (se houve) fica registrada com o hash do conteúdo antigo — o doc atual tem hash diferente, mostrando que mudou.$FAQ$, 9, true),
+
+    (v_doc_id, 'Como cancelo uma solicitação de assinatura?',
+     $FAQ$Hoje não há um botão "cancelar" direto na UI. O caminho é: ignore (deixa expirar pelo prazo do link) ou peça pro admin marcar como <code>status='expirado'</code> no banco. Em versões futuras teremos botão de cancelar na lista de pendências do doc.$FAQ$, 10, true),
+
+    (v_doc_id, 'Posso pedir mais de uma pessoa pra assinar o mesmo documento?',
+     $FAQ$Sim. Pra termos com múltiplos signatários (autorização de atendimento de menor com 2 pais, contrato com responsável legal + paciente), adicione cada um como signatário separado no dialog. Cada um vira uma entry em <code>document_signatures</code>. O link público é o mesmo — quando o signatário abre, escolhe quem ele é no select acima dos botões e assina apenas a entry dele. Útil também pra você incluir si mesmo (terapeuta) + paciente num contrato bilateral.$FAQ$, 11, true);
+
+    RAISE NOTICE 'Doc criada: id=%, faq_itens=12', v_doc_id;
+END;
+$IMPORT$;
+
+COMMIT;

database-novo/tmp/import-doc-documentos-paciente.sql

@@ -0,0 +1,173 @@
+-- Importacao da doc da aba Documentos do paciente (Fase 2)
+-- Gerado a partir de development/saas-docs/03-documentos-paciente-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 (
+        'Documentos do paciente',
+        $HTML$<h2>Documentos do paciente</h2>
+
+<p>A aba <strong>Documentos</strong> do prontuário (em <code>/melissa/paciente?id=...&amp;tab=documentos</code>) centraliza tudo que está vinculado àquele paciente: arquivos enviados por upload, documentos gerados a partir de templates (atestados, declarações, recibos, laudos…), e tudo que precisa ser compartilhado ou assinado.</p>
+
+<h3>1. Layout 2-col</h3>
+<p>A página tem 2 colunas:</p>
+<ul>
+  <li><strong>Sidebar esquerda (~240px):</strong> lista de tipos de documento com contadores. Click num tipo filtra a lista. "Todos" mostra tudo.</li>
+  <li><strong>Main direita:</strong> grid de cards dos documentos do tipo selecionado, com paginação a partir de 12 itens.</li>
+</ul>
+<p>No <strong>mobile</strong> (&lt;1024px), a sidebar vira um drawer acessado pelo botão "Tipos" no header.</p>
+
+<h3>2. Toolbar (header)</h3>
+<p>3 botões no topo:</p>
+<ul>
+  <li><strong>↻ Atualizar:</strong> refetch da lista (ícone spinner quando carregando)</li>
+  <li><strong>📄 Gerar:</strong> abre o dialog de geração a partir de template (vide seção 5)</li>
+  <li><strong>⬆ Upload</strong> (botão primário): abre o dialog de envio de arquivo (vide seção 3)</li>
+</ul>
+
+<h3>3. Upload de arquivo</h3>
+<p>Click no botão <strong>Upload</strong> abre um dialog que aceita:</p>
+<ul>
+  <li><strong>Drag-and-drop</strong> ou seleção manual</li>
+  <li>Formatos: PDF, imagens (JPG, PNG, WebP), Word, Excel, texto</li>
+  <li>Metadados opcionais: <strong>tipo</strong>, <strong>categoria</strong>, <strong>descrição</strong>, <strong>tags</strong>, <strong>visibilidade</strong> (privado / compartilhado supervisor / compartilhado portal paciente)</li>
+</ul>
+<p>Após o upload, o arquivo aparece na lista do tipo escolhido (ou "Outro" se você não selecionou).</p>
+
+<h3>4. Tipos de documento (sidebar)</h3>
+<p>Cada documento é classificado em um tipo. Tipos disponíveis:</p>
+<ul>
+  <li><strong>Laudo</strong> — laudo psicológico, parecer</li>
+  <li><strong>Atestado</strong> — atestado psicológico</li>
+  <li><strong>Declaração</strong> — comparecimento, início de tratamento, encaminhamento</li>
+  <li><strong>Recibo</strong> — recibos de pagamento gerados</li>
+  <li><strong>Receita</strong> — receituários (uso raro em psicologia)</li>
+  <li><strong>Exame</strong> — laudos/resultados de exames trazidos pelo paciente</li>
+  <li><strong>Termo assinado</strong> — TCLE, autorizações</li>
+  <li><strong>Relatório externo</strong> — relatórios de acompanhamento gerados</li>
+  <li><strong>Identidade</strong> — RG, CPF, CNH (cópias)</li>
+  <li><strong>Convênio</strong> — carteirinhas, autorizações de convênio</li>
+  <li><strong>Outro</strong> — fallback pra tudo que não se encaixa nos tipos acima</li>
+</ul>
+<p>O contador ao lado de cada tipo mostra quantos docs daquele tipo o paciente tem. Tipos vazios ficam com opacidade reduzida.</p>
+
+<h3>5. Gerar a partir de template</h3>
+<p>Click no botão <strong>Gerar</strong> abre o <em>DocumentGenerateDialog</em> em 3 passos:</p>
+<ol>
+  <li><strong>Selecionar template:</strong> grid com todos os templates ativos (globais + do tenant). Click num card seleciona.</li>
+  <li><strong>Editar variáveis:</strong> os campos do template aparecem com FloatLabel. Variáveis que vêm do sistema (nome do paciente, CRP do terapeuta, CNPJ da clínica etc) já vêm preenchidas automaticamente. Banner no topo conta "X de Y preenchidos". Campos vazios mostram um hint embaixo explicando onde cadastrar o dado (ex: <em>"Perfil → Registro Profissional"</em>).</li>
+  <li><strong>Preview:</strong> iframe sandboxed renderizando o HTML do template com as vars substituídas. Daqui você pode voltar pra editar, só baixar o PDF (sem salvar no sistema), ou salvar como documento do paciente.</li>
+</ol>
+
+<div style="background: rgba(34,197,94,0.08); border: 1px solid rgba(34,197,94,0.25); border-radius: 10px; padding: 12px 14px; margin: 14px 0; font-size: 0.85rem; color: var(--text-color);">
+  <strong>💡 Auto-fill cobre:</strong> dados do paciente, terapeuta (incluindo registro profissional formatado tipo "CRP 12345/SP"), clínica/tenant (incluindo CNPJ formatado), data atual em formato curto e por extenso, e — se a sessão for vinculada — valor da sessão em número e por extenso.
+</div>
+
+<h3>6. Editar um documento gerado (re-edição in-place)</h3>
+<p>Documentos gerados a partir de template podem ser <strong>re-editados</strong> mantendo o mesmo registro (ID, audit trail e link com o paciente preservados). Click em <strong>Editar</strong> no card do doc ou na sidebar do preview:</p>
+
+<ol>
+  <li>O sistema busca o template original + os valores que você usou na primeira geração</li>
+  <li>Abre o dialog em modo edição (header amber "Editar documento") pulando direto pro passo 2 (variáveis pré-preenchidas)</li>
+  <li>Você ajusta o que precisar → Preview → <strong>Substituir documento</strong></li>
+  <li>O PDF é regenerado e substitui o anterior no Storage; o doc fica com o mesmo ID, audit trail intacto</li>
+</ol>
+
+<p><strong>Documento legado</strong> (sem registro de geração ou que era um upload): o dialog mostra um toast e cai no fluxo normal de "selecione um template". Ao salvar, ele linka o doc existente ao novo template/valores.</p>
+
+<h3>7. Preview do documento</h3>
+<p>Click num card abre o <em>DocumentPreviewDialog</em>:</p>
+<ul>
+  <li><strong>Preview inline:</strong> iframe pra PDF, imagem renderizada direto, fallback "Preview não disponível" pra outros formatos</li>
+  <li><strong>Sidebar de detalhes</strong> (direita): tipo, categoria, visibilidade, descrição, tags</li>
+  <li><strong>5 botões de ação</strong> no rodapé da sidebar:
+    <ul>
+      <li><strong>Baixar</strong> — download direto do arquivo</li>
+      <li><strong>Editar</strong> — abre o generate dialog em modo edição (seção 6)</li>
+      <li><strong>Compartilhar</strong> — gera link compartilhável (seção 8)</li>
+      <li><strong>Assinar</strong> — fluxo de assinatura eletrônica (seção 9)</li>
+      <li><strong>Excluir</strong> (vermelho) — soft-delete com confirmação</li>
+    </ul>
+  </li>
+</ul>
+
+<h3>8. Compartilhar</h3>
+<p>Gera um link público temporário pro paciente acessar o documento sem precisar de login. Configurável:</p>
+<ul>
+  <li>Tempo de expiração (1h, 24h, 7 dias, custom)</li>
+  <li>Senha opcional</li>
+  <li>Permitir download ou só visualização</li>
+</ul>
+<p>O status compartilhado fica visível na sidebar de detalhes do preview.</p>
+
+<h3>9. Assinar</h3>
+<p>Fluxo de assinatura eletrônica (modal). O documento original recebe uma <strong>página adicional de assinatura</strong> com timestamp e identificação do signatário. A assinatura é registrada em <code>document_signatures</code> com hash do conteúdo original (proof of integrity).</p>
+
+<h3>10. Excluir e recuperar</h3>
+<p>Excluir é <strong>soft-delete</strong>: o documento ganha <code>deleted_at</code> mas o arquivo permanece no Storage e o registro fica preservado por <strong>5 anos</strong> (compliance LGPD/CFP). Pra recuperar, vá em <strong>Configurações → Lixo de documentos</strong>.</p>
+
+<h3>⚠️ Notas pro desenvolvedor</h3>
+<p>O componente <code>MelissaPatientDocuments.vue</code> reusa do <code>features/documents</code>:</p>
+<ul>
+  <li><code>useDocuments</code> — composable de fetch/CRUD/URLs assinadas</li>
+  <li><code>DocumentCard</code>, <code>DocumentUploadDialog</code>, <code>DocumentPreviewDialog</code>, <code>DocumentGenerateDialog</code>, <code>DocumentSignatureDialog</code>, <code>DocumentShareDialog</code></li>
+</ul>
+<p>O linkage <code>document_generated.documento_id</code> (FK pra <code>documents</code>) é o que viabiliza a re-edição in-place. Docs gerados antes da migration de linkage precisam do backfill SQL em <code>database-novo/tmp/backfill-document-generated-link.sql</code>.</p>$HTML$,
+        'Documentos',
+        true,
+        'usuario',
+        '/melissa/paciente',
+        3,
+        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 envio um documento que já existe (PDF/imagem do paciente)?',
+     $FAQ$Na aba <strong>Documentos</strong> do prontuário, click no botão <strong>Upload</strong> (azul, no canto superior direito). Você pode arrastar o arquivo pra área do dialog ou clicar pra selecionar. Antes de enviar, preencha o tipo, descrição e tags se quiser — assim o doc já vai pra categoria certa na sidebar.$FAQ$, 0, true),
+
+    (v_doc_id, 'Como gero um documento (atestado, declaração, recibo) a partir de template?',
+     $FAQ$Click no botão <strong>Gerar</strong> no header da aba Documentos do paciente. O dialog abre em 3 passos: (1) escolha o template, (2) confira as variáveis pré-preenchidas (e ajuste se necessário), (3) preview e <em>Salvar documento</em>. O PDF é gerado e salvo automaticamente no prontuário.$FAQ$, 1, true),
+
+    (v_doc_id, 'As variáveis (CRP, nome, CNPJ etc) preenchem sozinhas mesmo?',
+     $FAQ$Sim, sempre que possível. O sistema busca: dados do paciente (nome, CPF, RG, endereço, telefone, email…), do terapeuta (nome, email, telefone, e o registro profissional formatado tipo <em>CRP 12345/SP</em>), da clínica (nome, endereço, telefone, CNPJ formatado), data atual em formato curto e por extenso. Se você abriu o gerador a partir de uma sessão, os dados da sessão (valor, data) também entram. Campos vazios mostram embaixo um hint dizendo onde cadastrar o dado faltante.$FAQ$, 2, true),
+
+    (v_doc_id, 'Posso editar um documento gerado sem refazer tudo do zero?',
+     $FAQ$Sim. Click em <strong>Editar</strong> no card do documento (ou na sidebar do preview). O dialog abre em <em>modo edição</em> com o template original já selecionado e <strong>todos os valores que você usou anteriormente preenchidos</strong>. Você ajusta o que precisa, confere o preview e click em <em>Substituir documento</em>. O PDF é regenerado e substitui o anterior, mas o ID e o audit trail do doc continuam os mesmos.$FAQ$, 3, true),
+
+    (v_doc_id, 'Posso editar um documento que foi feito por upload (não por template)?',
+     $FAQ$Sim, mas o fluxo é diferente: como não há template original, o sistema mostra um aviso e abre o dialog em modo "selecione um template". Ao salvar, ele <strong>substitui o arquivo enviado por um PDF gerado</strong> e linka ao novo template. Útil pra "converter" um upload manual em algo padronizado. Se você só quer trocar o arquivo, exclua o doc e faça upload do novo.$FAQ$, 4, true),
+
+    (v_doc_id, 'Como compartilho um documento com o paciente sem ele precisar logar?',
+     $FAQ$No preview, click em <strong>Compartilhar</strong>. Um dialog gera um link público temporário com opção de tempo de expiração (1h, 24h, 7 dias, custom) e senha opcional. O paciente acessa pelo link, sem login. O status fica visível na sidebar de detalhes do doc.$FAQ$, 5, true),
+
+    (v_doc_id, 'Como assino eletronicamente um documento?',
+     $FAQ$No preview, click em <strong>Assinar</strong>. O fluxo adiciona uma página de assinatura ao PDF com timestamp e identificação. A assinatura é registrada com hash do conteúdo original — qualquer alteração posterior invalida a integridade. Ideal pra laudos, declarações e atestados que precisam de validade legal.$FAQ$, 6, true),
+
+    (v_doc_id, 'Excluí um documento por engano, dá pra recuperar?',
+     $FAQ$Sim. Exclusão é <strong>soft-delete</strong> — o documento ganha um marcador <code>deleted_at</code> mas continua no banco e o arquivo permanece no Storage. Pra recuperar, vá em <strong>Configurações → Lixo de documentos</strong>. O período de retenção é de <strong>5 anos</strong> (compliance LGPD e regulamentação CFP), depois o arquivo é purgado permanentemente.$FAQ$, 7, true),
+
+    (v_doc_id, 'Por que alguns documentos aparecem na categoria "Outro"?',
+     $FAQ$Documentos enviados por upload sem tipo definido caem em "Outro" automaticamente. Documentos gerados a partir de templates cujo tipo não está mapeado pras categorias padrão (declarações, atestados, laudos, etc) também — exemplos: contrato de prestação de serviços, autorização para gravação, termo de consentimento. Você pode mover o doc pra outra categoria editando o tipo na hora do upload ou via menu de ações no card.$FAQ$, 8, true),
+
+    (v_doc_id, 'Quais formatos de arquivo posso fazer upload?',
+     $FAQ$PDF, imagens (JPG, PNG, WebP, GIF), documentos Office (DOCX, XLSX, PPTX), texto simples (TXT, CSV) e formatos compactados (ZIP). Pra qualquer formato fora dessa lista, salve como PDF antes. O preview inline só funciona pra PDF e imagens — outros formatos mostram a opção "Baixar arquivo" no lugar.$FAQ$, 9, true),
+
+    (v_doc_id, 'Como o sistema garante que o documento não vaza pra outros profissionais?',
+     $FAQ$Cada documento tem um campo de <strong>visibilidade</strong>: <em>Privado</em> (só você vê), <em>Compartilhado com supervisor</em> (você + seu supervisor) ou <em>Compartilhado com portal do paciente</em> (o paciente também vê pelo portal). O default é Privado. RLS (Row Level Security) no banco bloqueia leitura por terceiros, independente da visibilidade. URLs do Storage são assinadas e expiram em 1h.$FAQ$, 10, true),
+
+    (v_doc_id, 'Os botões da sidebar do preview (Baixar/Editar/Compartilhar/Assinar/Excluir) não funcionavam, foi corrigido?',
+     $FAQ$Sim. Bug conhecido até 2026-05-22: o <code>DocumentPreviewDialog</code> emitia os 5 eventos mas o componente pai não os escutava, então nada acontecia ao clicar. Agora todos os 5 botões funcionam normalmente e o de Editar abre o dialog de geração em modo edição.$FAQ$, 11, true);
+
+    RAISE NOTICE 'Doc criada: id=%, faq_itens=12', v_doc_id;
+END;
+$IMPORT$;
+
+COMMIT;

database-novo/tmp/import-doc-documentos-templates.sql

@@ -0,0 +1,122 @@
+-- Importacao da doc da pagina de Templates de documentos (Fase 2)
+-- Gerado a partir de development/saas-docs/04-documentos-templates-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 (
+        'Templates de documentos',
+        $HTML$<h2>Templates de documentos</h2>
+
+<p>A página <strong>Templates de documentos</strong> (acessível pelo menu Prontuários → Templates de documentos, ou diretamente em <code>/melissa/documentos-templates</code>) é onde você gerencia os modelos usados pra gerar atestados, declarações, recibos, laudos e outros documentos clínicos.</p>
+
+<h3>1. Globais vs Tenant (Seus templates)</h3>
+<p>A lista é dividida em 2 grupos:</p>
+<ul>
+  <li><strong>Templates padrão (globais)</strong> — vêm pré-instalados com o sistema (Declaração de Comparecimento, Atestado Psicológico, Recibo de Pagamento, Laudo Psicológico, Parecer, Encaminhamento, etc). São <strong>read-only</strong> — você não pode editar nem desativar, mas pode duplicar pra personalizar.</li>
+  <li><strong>Seus templates (tenant)</strong> — os que você criou ou duplicou. Editáveis, removíveis (desativação soft-delete).</li>
+</ul>
+<p>Todos os templates ativos do tenant (globais + seus) ficam disponíveis na hora de gerar um documento pro paciente.</p>
+
+<h3>2. Lista de templates</h3>
+<p>Cards em grid mostrando: nome, tipo, descrição, badge "padrão" pros globais. No card de cada template do tenant há um menu de 3 pontos com: <strong>Duplicar</strong>, <strong>Editar</strong>, <strong>Desativar</strong>. Pros globais, só <strong>Duplicar</strong> (e click no card abre a Preview).</p>
+
+<h3>3. Preview de template global (read-only)</h3>
+<p>Click num template padrão abre a Preview — iframe sandbox renderizando o HTML completo (cabeçalho + corpo + rodapé) com estilos de A4 simulando o PDF final. Header tem botão <strong>Duplicar</strong> pra você levar pros seus templates.</p>
+
+<h3>4. Criar novo template</h3>
+<p>Botão <strong>+ Novo template</strong> abre o editor em modo "create". Campos:</p>
+<ul>
+  <li><strong>Nome</strong> e <strong>tipo</strong> (declaração, atestado, recibo, laudo, etc) — define a categoria do documento gerado</li>
+  <li><strong>Descrição</strong> opcional — aparece na lista</li>
+  <li><strong>Cabeçalho</strong> (top fixo) — geralmente nome da clínica, endereço, CNPJ</li>
+  <li><strong>Corpo</strong> (conteúdo principal) — o texto do documento com variáveis interpoladas</li>
+  <li><strong>Rodapé</strong> (bottom fixo) — assinatura, contato, observações</li>
+</ul>
+
+<h3>5. Editor rich-text + variáveis</h3>
+<p>Cada bloco (cabeçalho/corpo/rodapé) tem editor WYSIWYG com formatação, listas, tabelas e inserção de imagens. Ao clicar no botão de <strong>variáveis</strong>, abre um menu com todas as variáveis disponíveis. Click numa insere <code>{{nome_da_variavel}}</code> no cursor.</p>
+
+<div style="background: rgba(99,102,241,0.08); border: 1px solid rgba(99,102,241,0.25); border-radius: 10px; padding: 12px 14px; margin: 14px 0; font-size: 0.85rem; color: var(--text-color);">
+  <strong>💡 Variáveis disponíveis:</strong> <code>{{paciente_nome}}</code>, <code>{{paciente_cpf}}</code>, <code>{{paciente_rg}}</code>, <code>{{paciente_email}}</code>, <code>{{terapeuta_nome}}</code>, <code>{{terapeuta_registro}}</code> (CRP 12345/SP formatado), <code>{{terapeuta_telefone}}</code>, <code>{{clinica_nome}}</code>, <code>{{clinica_cnpj}}</code>, <code>{{data_atual}}</code>, <code>{{data_atual_extenso}}</code>, e — se gerado a partir de sessão — <code>{{valor}}</code>, <code>{{valor_extenso}}</code>, <code>{{data_sessao}}</code>. Lista completa no dropdown do editor.
+</div>
+
+<h3>6. Mobile (drawer pros templates)</h3>
+<p>Em telas &lt;1024px a lista vira um drawer com botão "Templates" no header. Click num item fecha o drawer e mostra o preview/editor ocupando a tela toda.</p>
+
+<h3>7. Duplicar</h3>
+<p>Duplicar copia o template (incluindo cabeçalho, corpo, rodapé e variáveis) pra <em>Seus templates</em> com sufixo <em>"(cópia)"</em> no nome. Você edita à vontade depois.</p>
+
+<h3>8. Desativar (soft-delete)</h3>
+<p>Templates do tenant podem ser <strong>desativados</strong> (não excluídos). Ficam marcados com <code>ativo = false</code> e somem da lista padrão e do dropdown de geração — mas o registro permanece no banco, e documentos antigos gerados a partir desse template continuam acessíveis. Pra reativar, marque "incluir desativados" no filtro (futuro — atualmente só via DB).</p>
+
+<h3>9. Tipos de template</h3>
+<p>Cada template tem um <strong>tipo</strong>. O tipo determina automaticamente qual categoria o documento gerado terá no prontuário do paciente:</p>
+<ul>
+  <li><code>declaracao_comparecimento</code>, <code>declaracao_inicio_tratamento</code>, <code>encaminhamento</code> → categoria <strong>Declaração</strong></li>
+  <li><code>atestado_psicologico</code> → categoria <strong>Atestado</strong></li>
+  <li><code>laudo_psicologico</code>, <code>parecer_psicologico</code> → categoria <strong>Laudo</strong></li>
+  <li><code>recibo_pagamento</code> → categoria <strong>Recibo</strong></li>
+  <li><code>relatorio_acompanhamento</code> → categoria <strong>Relatório externo</strong></li>
+  <li>Outros tipos (<code>termo_consentimento</code>, <code>contrato_servicos</code>, <code>autorizacao_*</code>, <code>outro</code>) → categoria <strong>Outro</strong></li>
+</ul>
+
+<h3>⚠️ Notas pro desenvolvedor</h3>
+<p>O componente <code>MelissaDocumentosTemplates.vue</code> reusa <code>useDocumentTemplates</code> + <code>DocumentTemplateEditor</code>. A lista de tipos vem do composable (<code>TIPOS_TEMPLATE</code>). O mapeamento tipo de template → tipo do documento gerado vive em <code>DocumentGenerate.service.js</code> (<code>TEMPLATE_TYPE_TO_DOC_TYPE</code>). RLS no banco: templates globais (<code>is_global = true</code>) tem leitura aberta; templates do tenant respeitam <code>tenant_id</code>.</p>$HTML$,
+        'Documentos',
+        true,
+        'usuario',
+        '/melissa/documentos-templates',
+        4,
+        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, 'Pra que serve a página de Templates?',
+     $FAQ$Pra você gerenciar os <strong>modelos</strong> que serão usados na hora de gerar atestados, declarações, recibos, laudos e outros documentos clínicos. Cada template tem cabeçalho, corpo e rodapé com variáveis interpoladas (nome do paciente, CRP, data, etc) — quando você usa o botão <em>Gerar</em> num prontuário, é um desses templates que está sendo aplicado.$FAQ$, 0, true),
+
+    (v_doc_id, 'Por que não consigo editar os templates padrão (com badge "padrão")?',
+     $FAQ$Templates marcados como <strong>globais</strong> (badge azul "padrão") vêm pré-instalados com o sistema e são compartilhados entre todos os tenants. Não dá pra editar pra preservar a versão de referência. Pra personalizar um, click em <strong>Duplicar</strong> — uma cópia vai pra <em>Seus templates</em> e ali você edita à vontade.$FAQ$, 1, true),
+
+    (v_doc_id, 'Como uso uma variável no template?',
+     $FAQ$No editor (cabeçalho, corpo ou rodapé), posicione o cursor onde quer a variável e clique no botão de <strong>variáveis</strong> na barra de ferramentas. Um menu lista todas as variáveis disponíveis agrupadas por categoria. Click numa variável insere <code>{{nome_da_variavel}}</code> no cursor. Na hora de gerar o documento, esse placeholder é substituído pelo valor real.$FAQ$, 2, true),
+
+    (v_doc_id, 'Quais variáveis estão disponíveis?',
+     $FAQ$Agrupadas por categoria — <strong>Paciente:</strong> nome, CPF, RG, data nascimento, email, telefone, endereço. <strong>Terapeuta:</strong> nome, email, telefone, registro profissional (formatado tipo "CRP 12345/SP"), tipo/número/UF do registro separados. <strong>Clínica:</strong> nome, endereço, telefone, CNPJ. <strong>Sessão:</strong> data, hora, valor, valor por extenso, forma de pagamento, modalidade. <strong>Geral:</strong> data atual, data atual por extenso. Lista completa visível no menu de variáveis do editor.$FAQ$, 3, true),
+
+    (v_doc_id, 'Posso recuperar um template que eu desativei?',
+     $FAQ$Sim, mas hoje só via banco de dados (administrador). Desativar é <strong>soft-delete</strong>: o template ganha <code>ativo = false</code> e some da lista. Documentos antigos gerados com ele continuam acessíveis. Em versões futuras teremos um filtro "mostrar desativados" pra reativar via UI.$FAQ$, 4, true),
+
+    (v_doc_id, 'Como duplico um template padrão pra personalizar?',
+     $FAQ$Click no card do template padrão pra abrir a <strong>Preview</strong>. No header da preview tem um botão <strong>Duplicar</strong>. Confirme — a cópia aparece em <em>Seus templates</em> com sufixo "(cópia)" no nome. Em seguida click em <strong>Editar</strong> nessa cópia pra ajustar texto, variáveis, cabeçalho, rodapé.$FAQ$, 5, true),
+
+    (v_doc_id, 'Qual a diferença prática entre template Global e do Tenant?',
+     $FAQ$Globais são compartilhados entre todos os tenants (vêm com o sistema) e são <strong>read-only</strong>. Templates do tenant pertencem só à sua clínica/conta e são editáveis. Ambos aparecem juntos na hora de gerar um documento — você não precisa duplicar pra usar um global, só pra personalizar. Se um global atende, use direto.$FAQ$, 6, true),
+
+    (v_doc_id, 'Posso usar imagens no template (logo da clínica, assinatura digitalizada)?',
+     $FAQ$Sim. O editor aceita inserção de imagens via toolbar. Recomendado: PNG ou JPG com tamanho moderado (logo até 200x80px, assinatura até 300x120px). Imagens muito grandes inflam o PDF gerado. Pra incluir o logo da clínica, prefira colocar no <strong>cabeçalho</strong> — assim aparece no topo de toda página do PDF.$FAQ$, 7, true),
+
+    (v_doc_id, 'O cabeçalho e rodapé aparecem em todas as páginas do PDF?',
+     $FAQ$Sim. O renderizador usa CSS <code>@page</code> com cabeçalho fixo no topo e rodapé fixo no rodapé de cada página gerada. Documentos curtos (1 página) você não percebe; documentos longos (laudos extensos) repetem cabeçalho/rodapé automaticamente. Útil pra manter identificação da clínica em todas as folhas.$FAQ$, 8, true),
+
+    (v_doc_id, 'Como sei se um template tem variável obrigatória?',
+     $FAQ$Hoje não há marcação "obrigatória" — todas as variáveis declaradas no template aparecem como editáveis na hora de gerar. Se uma vier vazia (porque não cadastrou no perfil/paciente/etc), o sistema mostra um hint embaixo do campo dizendo onde cadastrar (ex: <em>"Perfil → Registro Profissional"</em>). Você pode gerar mesmo com vazias — o placeholder fica como <code>{{variavel}}</code> no PDF, mas isso quase nunca é desejado.$FAQ$, 9, true),
+
+    (v_doc_id, 'Tem limite de templates por tenant?',
+     $FAQ$Não há limite hard no banco. Em planos free pode haver limite por contrato (verifique seu plano em Configurações → Plano). Recomendado manter o conjunto enxuto (10-20 templates) pra não poluir o dropdown na hora de gerar — se você não usa, desative.$FAQ$, 10, true),
+
+    (v_doc_id, 'Os templates são compartilhados entre os terapeutas do mesmo tenant?',
+     $FAQ$Sim. Todos os templates do tenant ficam disponíveis pra todos os usuários ativos do mesmo tenant (clínica). Quem cria/edita pode ser qualquer um com permissão de edição — não há "templates privados por usuário" no momento. Se precisar isolar templates por terapeuta, organize por nome (ex: "Atestado · Dra. Ana").$FAQ$, 11, true);
+
+    RAISE NOTICE 'Doc criada: id=%, faq_itens=12', v_doc_id;
+END;
+$IMPORT$;
+
+COMMIT;

database-novo/tmp/import-doc-recibo-profissional.sql

@@ -0,0 +1,143 @@
+-- Importacao da doc Emissao de recibo profissional (Fase 4 #14)
+-- Gerado a partir de development/saas-docs/06-recibo-profissional-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 (
+        'Emissão de recibo profissional',
+        $HTML$<h2>Emissão de recibo profissional</h2>
+
+<p>Quando uma sessão é registrada como <strong>paga</strong>, o sistema oferece um botão <em>Emitir recibo</em> que gera um PDF profissional pré-preenchido com todos os dados do paciente, terapeuta, clínica e da sessão — sem precisar passar pelo fluxo "Gerar a partir de template" manual.</p>
+
+<h3>1. Quando o botão aparece</h3>
+<p>O botão <strong>Emitir recibo</strong> (outlined, ícone PDF) aparece no <em>painel financeiro do evento</em> (<code>AgendaEventoFinanceiroPanel</code>) — dentro do modal de uma sessão — somente quando:</p>
+<ul>
+  <li>A sessão tem um <strong>financial_record vinculado</strong> (foi gerada cobrança via "Receber")</li>
+  <li>O status do record é <strong><code>paid</code></strong> (pagamento já registrado)</li>
+</ul>
+<p>Em sessões de pacote (status='contrato'), sem cobrança gerada, pendente, ou cancelada — o botão não aparece. Use o fluxo manual de <em>Gerar</em> na aba Documentos pra emitir recibos de casos especiais.</p>
+
+<h3>2. O que o recibo traz preenchido automaticamente</h3>
+<ul>
+  <li><strong>Paciente:</strong> nome, CPF, RG (do cadastro do paciente)</li>
+  <li><strong>Sessão:</strong> data e hora, modalidade</li>
+  <li><strong>Valor:</strong> número (R$ 150,00) <strong>e por extenso</strong> ("cento e cinquenta reais")</li>
+  <li><strong>Forma de pagamento:</strong> PIX, dinheiro, cartão, maquininha, etc — vindo do financial_record</li>
+  <li><strong>Terapeuta:</strong> nome completo + registro profissional formatado ("CRP 12345/SP")</li>
+  <li><strong>Clínica:</strong> nome, endereço, telefone, CNPJ formatado</li>
+  <li><strong>Data atual:</strong> em formato curto (22/05/2026) e por extenso ("22 de maio de 2026")</li>
+</ul>
+
+<h3>3. Registro profissional genérico</h3>
+<p>O sistema suporta <strong>qualquer conselho profissional</strong>, não só CRP. A formatação é automática a partir do que está cadastrado no <em>Perfil → Registro Profissional</em>:</p>
+<ul>
+  <li><strong>CRP</strong> 12345/SP (psicologia)</li>
+  <li><strong>CRM</strong> 67890/RJ (medicina)</li>
+  <li><strong>CRFa</strong> 11111/MG (fonoaudiologia)</li>
+  <li><strong>CREFITO</strong> 22222/SP (fisioterapia)</li>
+  <li><strong>CRESS</strong> 33333/RS (serviço social)</li>
+  <li><strong>CRN</strong> 44444/SP (nutrição)</li>
+  <li>Ou personalizado via tipo "Outro" + nome livre</li>
+</ul>
+<p>No template, a variável <code>{{terapeuta_registro}}</code> sempre traz o registro formatado, independente do conselho. Tem também variáveis individuais: <code>{{terapeuta_registro_tipo}}</code>, <code>{{terapeuta_registro_numero}}</code>, <code>{{terapeuta_registro_uf}}</code> pra uso fino.</p>
+
+<h3>4. Valor por extenso</h3>
+<p>Helper interno (<code>src/utils/valorExtenso.js</code>) converte número pra extenso em pt-BR completo até 999 milhões:</p>
+
+<div style="background: rgba(99,102,241,0.06); border: 1px solid rgba(99,102,241,0.2); border-radius: 10px; padding: 12px 14px; margin: 12px 0; font-family: 'IBM Plex Mono', monospace; font-size: 0.82rem;">
+  <strong>R$ 1,00</strong> → "um real"<br>
+  <strong>R$ 150,00</strong> → "cento e cinquenta reais"<br>
+  <strong>R$ 1.234,56</strong> → "mil duzentos e trinta e quatro reais e cinquenta e seis centavos"<br>
+  <strong>R$ 0,50</strong> → "cinquenta centavos"<br>
+  <strong>R$ 1.000.000,00</strong> → "um milhão de reais"
+</div>
+
+<p>Pluralização correta (real/reais, centavo/centavos), tratamento de centavos isolados ("R$ 0,X"), milhar com "mil" sem "um", milhão/milhões.</p>
+
+<h3>5. Onde o recibo é salvo</h3>
+<p>Ao clicar <strong>Emitir recibo</strong>:</p>
+<ol>
+  <li>Sistema busca o template global <code>recibo_pagamento</code></li>
+  <li>Carrega todas as variáveis (auto-fill descrito acima)</li>
+  <li>Gera o PDF</li>
+  <li>Faz upload pro bucket <code>generated-docs</code></li>
+  <li>Insere registros em <code>documents</code> e <code>document_generated</code> (com linkage)</li>
+  <li>Dispara <strong>download</strong> automático no browser</li>
+  <li>Toast "Recibo emitido — PDF baixado e salvo nos documentos do paciente"</li>
+</ol>
+<p>O recibo aparece na aba <em>Documentos</em> do prontuário do paciente sob a categoria <strong>Recibo</strong>. Pode ser editado in-place, compartilhado ou assinado eletronicamente normalmente.</p>
+
+<h3>6. Quick path vs flow manual</h3>
+<p>São <strong>2 caminhos</strong> pra gerar o mesmo PDF:</p>
+<ul>
+  <li><strong>Quick path</strong> (este): clica num botão e pronto. Recibo da sessão paga, valor exato do record, forma de pagamento idem.</li>
+  <li><strong>Flow manual</strong>: aba Documentos → Gerar → escolhe template "Recibo de Pagamento" → edita valores manualmente → preview → salva.</li>
+</ul>
+<p>Use o quick path no fluxo normal. Use o manual quando precisar emitir recibo de algo que não está vinculado a sessão (consulta avulsa) ou quando precisar ajustar valores.</p>
+
+<h3>⚠️ Notas pro desenvolvedor</h3>
+<ul>
+  <li><strong>Service:</strong> <code>emitirReciboParaSessao(eventoId, { patientId?, valor?, formaPagamento? })</code> em <code>DocumentGenerate.service.js</code>. Quick path one-call: busca template, carrega vars, gera, salva, download.</li>
+  <li><strong>Helper extenso:</strong> <code>src/utils/valorExtenso.js</code> — pt-BR até 999 milhões. Atenção: zero retorna "zero reais", inputs inválidos retornam string vazia.</li>
+  <li><strong>Mapeamento:</strong> <code>TEMPLATE_TYPE_TO_DOC_TYPE['recibo_pagamento'] = 'recibo'</code> garante que o doc gerado vai pra categoria certa na sidebar.</li>
+  <li><strong>Template:</strong> migration <code>20260521000008_recibo_uses_terapeuta_registro.sql</code> trocou <code>"Psicólogo(a) - CRP {{terapeuta_crp}}"</code> por <code>{{terapeuta_registro}}</code> no template global. Universal pra qualquer conselho.</li>
+  <li><strong>Botão UI:</strong> <code>AgendaEventoFinanceiroPanel.vue</code> linha ~320, branch <code>v-else-if="record.status === 'paid'"</code>.</li>
+</ul>$HTML$,
+        'Financeiro',
+        true,
+        'usuario',
+        '/melissa/agenda',
+        6,
+        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 emito um recibo pra uma sessão que recebi o pagamento?',
+     $FAQ$Abra a sessão no calendário da agenda → no painel <em>Cobrança</em> dentro do modal, com o pagamento já registrado (status <strong>Pago</strong>), aparece o botão <strong>Emitir recibo</strong>. Clique uma vez. O sistema gera o PDF, salva nos documentos do paciente e dispara o download automaticamente. Toast confirma a operação.$FAQ$, 0, true),
+
+    (v_doc_id, 'Por que o botão "Emitir recibo" não aparece na minha sessão?',
+     $FAQ$O botão só aparece quando o financial_record da sessão tem <strong>status = pago</strong>. Possíveis motivos: (1) você não gerou cobrança ainda — clique em <em>Receber</em> pra registrar o pagamento primeiro; (2) cobrança está pendente — registre o recebimento; (3) sessão é de pacote (status='contrato') — pacotes não emitem recibo por sessão, use o fluxo manual em <em>Documentos → Gerar</em>; (4) cobrança foi cancelada — gere uma nova.$FAQ$, 1, true),
+
+    (v_doc_id, 'O valor por extenso vem certo ("cento e cinquenta reais")?',
+     $FAQ$Sim, com gramática pt-BR correta até 999 milhões. Exemplos: R$ 1,00 → "um real", R$ 150,00 → "cento e cinquenta reais", R$ 1.234,56 → "mil duzentos e trinta e quatro reais e cinquenta e seis centavos", R$ 0,50 → "cinquenta centavos". Pluralização real/reais e centavo/centavos automática.$FAQ$, 2, true),
+
+    (v_doc_id, 'O recibo funciona pra qualquer conselho profissional (CRM, CRFa…)?',
+     $FAQ$<strong>Sim.</strong> O template usa a variável <code>{{terapeuta_registro}}</code> que se adapta ao tipo de registro cadastrado no seu Perfil. Funciona pra CRP (psicologia), CRM (medicina), CRFa (fonoaudiologia), CREFITO (fisioterapia), CRESS (serviço social), CRN (nutrição), e qualquer outro conselho — incluindo "Outro" com nome livre. A formatação genérica fica tipo "CRP 12345/SP", "CRM 67890/RJ", etc.$FAQ$, 3, true),
+
+    (v_doc_id, 'Onde o recibo fica salvo depois de emitido?',
+     $FAQ$Em <strong>2 lugares</strong>: (1) baixado automaticamente no seu computador via download do navegador; (2) salvo na aba <em>Documentos</em> do prontuário do paciente, na categoria <strong>Recibo</strong> da sidebar. Daí você pode reabrir, compartilhar com o paciente, enviar pra assinar, ou editar in-place se precisar ajustar.$FAQ$, 4, true),
+
+    (v_doc_id, 'Posso emitir recibo de algo que não é sessão (consulta avulsa, pacote)?',
+     $FAQ$Sim, mas pelo <strong>fluxo manual</strong>: vá na aba <em>Documentos</em> do paciente → botão <strong>Gerar</strong> → escolha o template <em>"Recibo de Pagamento"</em>. Você preenche os valores na mão (valor, forma de pagamento, descrição) já que não vem de uma sessão específica. O resto (CRP, paciente, clínica) auto-completa igual.$FAQ$, 5, true),
+
+    (v_doc_id, 'Meu CRP/CRM aparece vazio no recibo, o que fazer?',
+     $FAQ$Cadastre seu registro profissional em <strong>Perfil → Registro Profissional</strong>. Selecione o tipo (CRP/CRM/CRFa/…/Outro), número e UF. Salve. Próximos recibos gerados já trazem formatado. Pra atualizar recibos antigos, abra o doc na aba Documentos do paciente e use <em>Editar</em> — o sistema vai puxar o registro atualizado.$FAQ$, 6, true),
+
+    (v_doc_id, 'O CNPJ da clínica aparece formatado no recibo?',
+     $FAQ$Sim, automaticamente. Em <strong>Configurações → Negócio (Tenant)</strong>, cadastre o CPF ou CNPJ no campo unificado. O sistema detecta pela quantidade de dígitos: 11 dígitos formata como CPF (XXX.XXX.XXX-XX), 14 como CNPJ (XX.XXX.XXX/XXXX-XX). O recibo usa a variável <code>{{clinica_cnpj}}</code> que sai formatada.$FAQ$, 7, true),
+
+    (v_doc_id, 'Errei o valor do recibo, posso corrigir sem gerar outro?',
+     $FAQ$Sim. Vá na aba <em>Documentos</em> do paciente → abra o recibo no preview → clique em <strong>Editar</strong>. O dialog abre em modo edição com o template do recibo já carregado e os valores anteriores preenchidos. Ajuste o que precisa → <em>Substituir documento</em>. O PDF é regenerado e substitui o anterior, mantendo o mesmo ID e audit trail.$FAQ$, 8, true),
+
+    (v_doc_id, 'Posso enviar o recibo pro paciente assinar?',
+     $FAQ$Sim. Recibos são documentos como qualquer outro — abra na aba Documentos → preview → botão <strong>Assinar</strong> na sidebar. Gera link público temporário, paciente abre sem login, marca aceite LGPD, assina. Útil pra recibos de valores altos ou contratos de pacote onde você quer registro formal da concordância.$FAQ$, 9, true),
+
+    (v_doc_id, 'Recibo de uma sessão antiga vai com a data de hoje ou a data da sessão?',
+     $FAQ$<strong>As duas</strong>. O recibo traz a <em>data da sessão</em> ("Referente ao atendimento de 15/03/2026") e a <em>data atual de emissão</em> ("São Carlos, 22 de maio de 2026") no rodapé. Importante pra fiscal — a data de emissão indica quando o documento foi formalmente criado, mesmo que a sessão tenha sido meses atrás.$FAQ$, 10, true),
+
+    (v_doc_id, 'Posso reemitir um recibo que já foi emitido pra mesma sessão?',
+     $FAQ$Sim, mas com cuidado. Clicar em <strong>Emitir recibo</strong> de novo gera um <strong>novo PDF</strong> e salva como novo documento na aba — você fica com 2 recibos da mesma sessão. Pra apenas atualizar (sem duplicar), edite o existente em <em>Documentos → preview → Editar</em>. Se duplicar por engano, exclua o antigo (soft-delete preserva por 5 anos no Lixo).$FAQ$, 11, true);
+
+    RAISE NOTICE 'Doc criada: id=%, faq_itens=12', v_doc_id;
+END;
+$IMPORT$;
+
+COMMIT;

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

@@ -0,0 +1,165 @@
+-- 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;

src/features/documents/components/DocumentGenerateDialog.vue

@@ -13,12 +13,19 @@ import { ref, watch, computed } from 'vue'
 import { useToast } from 'primevue/usetoast'
 import { useDocumentGenerate } from '../composables/useDocumentGenerate'
 import { useDocumentTemplates } from '../composables/useDocumentTemplates'
+import { loadGeneratedFromDocId } from '@/services/DocumentGenerate.service'
 
 const props = defineProps({
     visible: { type: Boolean, default: false },
     patientId: { type: String, default: null },
     patientName: { type: String, default: '' },
-    agendaEventoId: { type: String, default: null }
+    agendaEventoId: { type: String, default: null },
+    // Modo edicao: ID de um documents.id existente. Quando setado, o dialog
+    // busca o template_id + dados_preenchidos do document_generated vinculado,
+    // pre-seleciona o template e popula as variaveis. Save vira UPDATE
+    // in-place (preserva documents.id e audit). Doc sem registro generated
+    // (uploaded direto) cai no flow normal de "select template".
+    editingDocId: { type: String, default: null }
 })
 
 const emit = defineEmits(['update:visible', 'generated'])
@@ -52,13 +59,48 @@ const {
 // ── Reset ao abrir ──────────────────────────────────────────
 
 watch(() => props.visible, async (v) => {
-    if (v) {
+    if (!v) return;
     step.value = 'select'
     reset()
     await Promise.all([
         fetchTemplates(),
         props.patientId ? loadVariables(props.patientId, props.agendaEventoId) : Promise.resolve()
     ])
+
+    // Modo edicao: tenta carregar o registro do generated, pre-seleciona
+    // template e popula vars com dados_preenchidos (sobrescreve auto-vars
+    // — preserva customizacao anterior do user). Se nao houver linkage
+    // (doc uploaded direto), continua no flow normal de "select template".
+    if (props.editingDocId) {
+        const gen = await loadGeneratedFromDocId(props.editingDocId)
+        if (gen?.template_id) {
+            try {
+                await selectTemplate(gen.template_id)
+                // Merge: dados_preenchidos override auto-loaded variables.
+                // Mantemos as vars que o user nao tinha customizado da vez
+                // anterior (pra caso o template tenha vars novas adicionadas
+                // depois) — pegamos as keys auto + sobrescreve com generated.
+                const saved = gen.dados_preenchidos || {}
+                Object.entries(saved).forEach(([k, val]) => {
+                    setVariable(k, val == null ? '' : String(val))
+                })
+                step.value = 'edit'
+            } catch (e) {
+                toast.add({
+                    severity: 'warn',
+                    summary: 'Template original não encontrado',
+                    detail: 'Selecione um template para regenerar o documento.',
+                    life: 3500
+                })
+            }
+        } else {
+            toast.add({
+                severity: 'info',
+                summary: 'Documento legado',
+                detail: 'Sem dados de edição. Selecione um template para regenerar.',
+                life: 3500
+            })
+        }
     }
 })
 
@@ -109,8 +151,15 @@ function onVarChange(key, val) {
 
 async function onGenerate() {
     try {
-        const result = await generateAndSave(props.patientId)
+        const result = await generateAndSave(props.patientId, props.editingDocId || null)
-        toast.add({ severity: 'success', summary: 'Documento salvo', detail: 'Disponível nos documentos do paciente.', life: 3000 })
+        toast.add({
+            severity: 'success',
+            summary: props.editingDocId ? 'Documento atualizado' : 'Documento salvo',
+            detail: props.editingDocId
+                ? 'PDF substituído com os novos valores.'
+                : 'Disponível nos documentos do paciente.',
+            life: 3000
+        })
         emit('generated', result)
         close()
     } catch (e) {
@@ -153,10 +202,10 @@ function close() {
         <template #header>
             <div class="flex items-center gap-3">
                 <span class="flex items-center justify-center w-8 h-8 rounded-lg bg-green-500/10">
-                    <i class="pi pi-file-pdf text-green-600" />
+                    <i :class="editingDocId ? 'pi pi-pencil text-amber-600' : 'pi pi-file-pdf text-green-600'" />
                 </span>
                 <div>
-                    <div class="text-base font-semibold">Gerar documento</div>
+                    <div class="text-base font-semibold">{{ editingDocId ? 'Editar documento' : 'Gerar documento' }}</div>
                     <div class="text-xs text-[var(--text-color-secondary)]">
                         <template v-if="step === 'select'">Selecione um template</template>
                         <template v-else-if="step === 'edit'">{{ selectedTemplate?.nome_template }} — {{ patientName }}</template>
@@ -299,7 +348,7 @@ function close() {
                     />
                     <Button
                         v-if="step === 'preview'"
-                        label="Salvar documento"
+                        :label="editingDocId ? 'Substituir documento' : 'Salvar documento'"
                         icon="pi pi-check"
                         @click="onGenerate"
                         :loading="generating"

src/features/documents/composables/useDocumentGenerate.js

@@ -99,9 +99,12 @@ export function useDocumentGenerate() {
     // ── Gerar PDF (client-side) ────────────────────────────
 
     /**
-     * Gera PDF blob, faz download, salva no Storage + banco.
+     * Gera PDF blob, salva no Storage + banco.
+     * @param {string} patientId
+     * @param {string|null} editingDocId - se setado, UPDATE no doc existente
+     *   (in-place replace de PDF + metadados, preserva documents.id e audit).
      */
-    async function generateAndSave(patientId) {
+    async function generateAndSave(patientId, editingDocId = null) {
         if (!selectedTemplate.value) throw new Error('Nenhum template selecionado.');
 
         loading.value = true;
@@ -119,7 +122,8 @@ export function useDocumentGenerate() {
                 dadosPreenchidos: { ...variables.value },
                 pdfBlob: blob,
                 templateNome,
-                templateTipo: selectedTemplate.value.tipo
+                templateTipo: selectedTemplate.value.tipo,
+                editingDocId
             });
             generatedDocs.value.unshift(result);
             return result;

src/layout/melissa/MelissaPatientDocuments.vue

@@ -57,6 +57,10 @@ const signatureDlg = ref(false);
 const shareDlg = ref(false);
 const selectedDoc = ref(null);
 const previewUrl = ref('');
+// Ref dedicado pro modo edicao do generate dialog. Separado do selectedDoc
+// (que tambem alimenta preview/share/sign/delete) pra evitar vazar "edit
+// state" pro "Gerar" do header quando o user so abre preview e fecha.
+const editingDoc = ref(null);
 
 // ── Tipo selecionado (filtro pela sidebar) ────────────────
 // null = todos os tipos
@@ -123,9 +127,15 @@ async function onPreview(doc) {
 function onDownload(doc) { download(doc); }
 
 function onEdit(doc) {
-    selectedDoc.value = doc;
+    // Abre o DocumentGenerateDialog em modo edicao (editingDocId passado).
-    // Reusa preview dialog em modo "ver" — edit completo só via DocumentsListPage
+    // Dialog busca template + dados_preenchidos do document_generated e
-    onPreview(doc);
+    // pre-popula tudo, pulando direto pra step 'edit'. Save substitui o PDF
+    // in-place no Storage e atualiza documents (preserva id + audit trail).
+    // Docs uploaded direto (sem registro generated) caem no flow normal de
+    // "select template" com um toast info.
+    editingDoc.value = doc;
+    previewDlg.value = false; // fecha preview se estiver aberto
+    generateDlg.value = true;
 }
 
 function onDelete(doc) {
@@ -380,13 +390,24 @@ onBeforeUnmount(() => {
             :doc="selectedDoc"
             :preview-url="previewUrl"
             @updated="fetchDocuments"
+            @download="onDownload"
+            @edit="onEdit"
+            @share="(d) => { previewDlg = false; onShare(d); }"
+            @sign="(d) => { previewDlg = false; onSign(d); }"
+            @delete="(d) => { previewDlg = false; onDelete(d); }"
         />
+        <!-- editing-doc-id vem do ref editingDoc dedicado — so e setado
+             via onEdit (botao Editar). "Gerar" no header usa generateDlg=true
+             com editingDoc=null, abrindo limpo. Limpa editingDoc no
+             fechamento pra nao vazar pro proximo Gerar. -->
         <DocumentGenerateDialog
             v-if="patientId"
-            v-model:visible="generateDlg"
+            :visible="generateDlg"
             :patient-id="patientId"
             :patient-name="patientName"
+            :editing-doc-id="editingDoc?.id || null"
             @generated="onGenerated"
+            @update:visible="(v) => { generateDlg = v; if (!v) editingDoc = null; }"
         />
         <DocumentSignatureDialog
             :visible="signatureDlg"

src/services/DocumentGenerate.service.js

@@ -404,9 +404,10 @@ export async function printDocument(template, variables = {}) {
  * @param {string} params.patientId
  * @param {object} params.dadosPreenchidos - snapshot dos dados usados
  * @param {Blob}   params.pdfBlob - PDF gerado (opcional — pode ser null se so print)
- * @returns {object} registro criado
+ * @param {string} [params.editingDocId] - se setado, re-edita doc existente (UPDATE)
+ * @returns {object} registro criado/atualizado em document_generated
  */
-export async function saveGeneratedDocument({ templateId, patientId, dadosPreenchidos, pdfBlob, templateNome, templateTipo }) {
+export async function saveGeneratedDocument({ templateId, patientId, dadosPreenchidos, pdfBlob, templateNome, templateTipo, editingDocId = null }) {
     const ownerId = await getOwnerId();
     const tenantId = await getActiveTenantId(ownerId);
 
@@ -428,8 +429,57 @@ export async function saveGeneratedDocument({ templateId, patientId, dadosPreenc
         if (upErr) throw upErr;
     }
 
-    // Registra na tabela document_generated
+    // ─── MODO EDIT (UPDATE in-place) ─────────────────────────
-    const { data, error } = await supabase
+    // Re-edicao: preserva documents.id (e o audit trail), substitui o PDF
+    // no Storage, atualiza metadados. Best-effort cleanup do PDF antigo.
+    if (editingDocId) {
+        const { data: oldDoc } = await supabase
+            .from('documents')
+            .select('bucket_path, storage_bucket')
+            .eq('id', editingDocId)
+            .single();
+
+        const docPatch = {
+            tipo_documento: mapTipoDocumento(templateTipo),
+            descricao: `Gerado a partir do template: ${templateNome || 'documento'}`
+        };
+        if (pdfPath) {
+            docPatch.bucket_path = pdfPath;
+            docPatch.storage_bucket = BUCKET;
+            docPatch.tamanho_bytes = pdfBlob?.size || null;
+            docPatch.nome_original = filename.replace(/_/g, ' ').replace('.pdf', '') + '.pdf';
+        }
+        const { error: upDocErr } = await supabase
+            .from('documents')
+            .update(docPatch)
+            .eq('id', editingDocId);
+        if (upDocErr) throw upDocErr;
+
+        // Atualiza document_generated. Pode nao existir (docs legados sem
+        // linkage) — INSERT nesse caso, com documento_id apontando pro doc.
+        const { data: existingGen } = await supabase
+            .from('document_generated')
+            .select('id')
+            .eq('documento_id', editingDocId)
+            .maybeSingle();
+
+        let data;
+        if (existingGen) {
+            const genPatch = {
+                template_id: templateId,
+                dados_preenchidos: dadosPreenchidos || {}
+            };
+            if (pdfPath) genPatch.pdf_path = pdfPath;
+            const { data: updated, error: upGenErr } = await supabase
+                .from('document_generated')
+                .update(genPatch)
+                .eq('id', existingGen.id)
+                .select('*')
+                .single();
+            if (upGenErr) throw upGenErr;
+            data = updated;
+        } else {
+            const { data: inserted, error: insGenErr } = await supabase
                 .from('document_generated')
                 .insert({
                     template_id: templateId,
@@ -438,17 +488,31 @@ export async function saveGeneratedDocument({ templateId, patientId, dadosPreenc
                     dados_preenchidos: dadosPreenchidos || {},
                     pdf_path: pdfPath,
                     storage_bucket: BUCKET,
-            gerado_por: ownerId
+                    gerado_por: ownerId,
+                    documento_id: editingDocId
                 })
                 .select('*')
                 .single();
+            if (insGenErr) throw insGenErr;
+            data = inserted;
+        }
 
-    if (error) throw error;
+        // Cleanup do PDF antigo no Storage. Falha silenciosa — arquivo orfao
+        // nao quebra nada, so ocupa espaco minimo.
+        if (oldDoc?.bucket_path && oldDoc.bucket_path !== pdfPath && oldDoc.storage_bucket) {
+            supabase.storage.from(oldDoc.storage_bucket).remove([oldDoc.bucket_path])
+                .catch((e) => console.warn('[saveGeneratedDocument] cleanup antigo falhou:', e));
+        }
 
-    // Registra na tabela documents para aparecer na lista do paciente
+        return data;
-    // Reutiliza o mesmo arquivo do bucket generated-docs (sem upload duplicado)
+    }
+
+    // ─── MODO CREATE (insert) ────────────────────────────────
+    // Insere documents primeiro pra capturar o id e linkar em
+    // document_generated via documento_id (FK).
+    let documentoId = null;
     if (pdfPath) {
-        await supabase
+        const { data: newDoc, error: insDocErr } = await supabase
             .from('documents')
             .insert({
                 owner_id: ownerId,
@@ -465,9 +529,52 @@ export async function saveGeneratedDocument({ templateId, patientId, dadosPreenc
                 visibilidade: 'privado',
                 status_revisao: 'aprovado',
                 uploaded_by: ownerId
-            });
+            })
+            .select('id')
+            .single();
+        if (insDocErr) throw insDocErr;
+        documentoId = newDoc?.id || null;
     }
 
+    // Registra em document_generated com o linkage documento_id preenchido
+    const { data, error } = await supabase
+        .from('document_generated')
+        .insert({
+            template_id: templateId,
+            patient_id: patientId,
+            tenant_id: tenantId,
+            dados_preenchidos: dadosPreenchidos || {},
+            pdf_path: pdfPath,
+            storage_bucket: BUCKET,
+            gerado_por: ownerId,
+            documento_id: documentoId
+        })
+        .select('*')
+        .single();
+
+    if (error) throw error;
+
+    return data;
+}
+
+// ── Buscar generated existente pra modo edit ─────────────────
+
+/**
+ * Busca o registro document_generated vinculado a um documents.id.
+ * Retorna template_id + dados_preenchidos pra pre-popular o dialog.
+ * Null se nao houver linkage (docs uploaded direto, sem template).
+ */
+export async function loadGeneratedFromDocId(documentoId) {
+    if (!documentoId) return null;
+    const { data, error } = await supabase
+        .from('document_generated')
+        .select('id, template_id, dados_preenchidos, pdf_path, gerado_em')
+        .eq('documento_id', documentoId)
+        .maybeSingle();
+    if (error) {
+        console.error('[loadGeneratedFromDocId]', error);
+        return null;
+    }
     return data;
 }