log: sessao 22/05 - Melissa UX overhaul + 5 saas-docs (Fases 2-5)

Sessao completa de ~14 commits. 2 grandes blocos:

BLOCO 1 — Melissa UI overhaul: tray bottom-right (substitui topbar
band), mobile collapse parcial em <md, busca global unificada
(MelissaBusca ganha "Ir para [data]", popover da agenda deletado),
dock com 4 builtins, hero resumo com cancelado/remarcado, settings+
ajuda click-outside, cronometro evento-aware (botao ⏱ na timeline +
sessionPlan + confirm fechar), documents edit in-place via
document_generated.documento_id, wire-up dos 5 botoes do preview.

BLOCO 2 — 5 docs saas novas (03-07 em development/saas-docs/) +
SQL imports + 60 FAQs total. Cobertura: aba Documentos paciente,
pagina Templates, Assinatura eletronica, Emissao de recibo
profissional, Relatorios + 3 formatos de export.

Memorias adicionadas:
- feedback_tailwind_utility_load_order (hidden perde pra CSS base
  do componente por ordem de carga Vite)
- project_documents_reedit_in_place (linkage documento_id + editingDocId)

PROXIMA SESSAO (23/05): Fase 6 restante (C12 antecipar UX iter —
unico item de codigo da lista de ontem), Fase 7 restante (regressao
Agenda C7-C13, validacao manual). Antes/depois: panorama MVP no
ROADMAP canonico — ainda restam #12 papel timbrado, #15 NFS-e,
§1.5 Sentry, Asaas Fase B, M4 cutover, validacao centralizada
de forms.

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

HANDOFF.md

@@ -1,147 +1,448 @@
-# HANDOFF — 2026-05-08 (MelissaPaciente — port completo + iteração de UX)
+# HANDOFF — 2026-05-20 (C10 ✅ + C11 ✅ + C12 ⏳ deferido · testando C13)
 
-Documento de continuidade. **Quando voltar, comece lendo esta página.**
+Documento de continuidade. **Quando voltar, comece lendo esta página até o fim.**
 
-> **🟢 PLANO DE 8 FASES COMPLETO** — `MelissaPaciente.vue` (~2400L) é a versão
+> **🎯 SE A FORÇA CAIR / SESSÃO PERDER CONTEXTO:** C10 e C11 fechados.
-> Melissa nativa do `PatientProntuario.vue` legacy (3593L). Todas as 7 abas
+> **C12 fluxo crítico OK no DB mas UX confusa** — adiado pra iterar
-> entregues, wire-up final feito (Dialog → route `/melissa/paciente?id=X`).
+> pós-Rail/Clínica (memória project_c12_antecipar_iterar). Agora
-> 5 composables + utils compartilhados extraídos.
+> **testando C13** (edit cobrada — invariante imutabilidade SimplePractice).
+> Implementação JÁ existe (Fase 6 do commit 1feb711 — Message com cadeado +
+> AgendaEventoFinanceiroPanel embedded). Só validação visual + persistência.
 
-> **🟢 ITERAÇÃO PÓS-FASE 8** — Várias rodadas de feedback do user com fixes:
+> **🟢 14 COMMITS NO DIA**. C10 (5/5), C11 (4/4), C12 deferred (DB OK),
-> full-width, sidebar "Voltar pra Pacientes" (no lugar de Configurações),
+> reverse transition trava implementada, popover watch sync implementado.
-> editar inline, openWhatsapp fix, dialog Lançamento, dialog Nova Sessão
+> Pós-C13: replicar Rail (AgendaTerapeutaPage) + Clínica (AgendaClinicaPage)
-> com `AgendaEventDialog` real, recorrências do paciente.
+> + iterar C12 UX + doc de ajuda (pendência separada).
 
-> **🟢 COMMITADO + PUSHED** — Working tree limpa.
+### C13 — passos de teste (próximo)
+Paciente: **João Almeida Martins** (sessão 20/05 9:00 realizada + paid R$ 40 maquininha) ou **André Green 20/05** (paid PIX).
+
+Esperado ao abrir o AgendaEventDialog:
+- Message azul com cadeado: "Cobrança de R$ X já emitida..."
+- AgendaEventoFinanceiroPanel renderiza embaixo do Message
+- Card "Aplicar alterações em" oculto (v-if="!occFinancialRecord")
+- Só horário/observações editáveis; valor/serviços/tipo travados
+
+### C11 sub-test results
+| # | Teste | DB validado |
+|---|---|---|
+| 11A | Realizada + markPaid PIX | sessions_used 0→1, record paid R$ 40 PIX |
+| 11B | Falta + Descontar saldo | sessions_used 1→2, sem multa |
+| 11C | Falta + Multa SEM consumir | sessions_used stays 2, multa pending R$ 30 |
+| 11D | Cancelado + default_consume_on_miss=true | sessions_used 2→3, sem multa (>2h) |
+
+### Bugs descobertos + corrigidos durante C11
+- UI "Como cobrar?" com options "Já recebi" misturadas → refatorado pra "Já recebi?" radio Sim/Não + select condicional
+- `billing_contracts` sem coluna `updated_at` → UPDATE falhava silently em Promise.allSettled (root cause do saldo não incrementar). Trocado pra awaits sequenciais com error handling explícito
+- Reverse transitions deixavam multa órfã → dialog reverse implementado com radio "cancelar pending" + "devolver saldo" + warning pra paid
+- Botão "Gerar cobrança" em sessão encerrada → bloqueado
+- Lock total em cancelado/faltou: Editar sessão some, status mudanças disabled exceto Agendada (recovery)
+- Label "A cobrar R$ X" em pacote saldo state=none → "Aguardando uso do pacote"
+- Badge $ amber em pacote saldo state=none → suprimido
+- billing_contract_id não amarrado em alguns flows → link universal antes dos blocos forward
+- Reverse saldo decrementar: refresh sessions_used FRESH do DB antes do UPDATE (anti-race)
+
+### Pendências mapeadas pós-C13
+- **Popover snapshot**: `eventoSelecionado.value = ev` é snapshot. Fix: guardar ev.id, derivar via computed
+- ~~Reverse transitions~~ ✓ implementado ahead of schedule
+- **Cleanup teste**: Otto sessão 5364f631 leftover (não-critical)
+
+### C10 sub-test results
+| # | Teste | DB validado | Notas |
+|---|---|---|---|
+| A | Realizada sem markPaid | ✅ status=realizado, record=pending | Bubble do C9 funcionou |
+| A2 | Realizada + markPaid maquininha | ✅ status=realizado, record=paid, payment_method=cartao_maquininha, paid_at set | João Almeida |
+| B | Faltou + multa R$ 30 (fixed_fee) | ✅ original cancelled + nova multa "Multa por falta · sessão dd/mm/aa" | Otto Rank |
+| C | Cancelado >2h antecedência | ✅ original cancelled, sem multa | Otto / Karen |
+| C2 | Cancelado tardio (<2h) full charge | ✅ original cancelled + nova "Taxa de cancelamento tardio · sessão dd/mm/aa" | Karen Horney |
+
+### Pendências mapeadas durante C10 — pós-C13
+- **Reverse transitions**: faltou/cancelado → agendado deixa multa órfã. Implementar confirm dialog oferecendo auto-cancelar multa.
+- **Popover snapshot**: `eventoSelecionado.value = ev` é snapshot, não acompanha _paymentStateMap. Fix: guardar ev.id, derivar via computed.
+- **Cleanup teste**: Otto sessão 5364f631 às 19:30 UTC tem record pending R$ 40 leftover do teste A original. Apagar quando convenient.
+
+Memórias relevantes:
+- `project_agenda_reverse_transitions.md`
+- `project_melissa_popover_snapshot.md`
+
+### Code-fix aplicado em 20/05 (pré-C10)
+- **`useMelissaAgenda.js:1450-1505`** — `_applyStatusDecisions` agora cancela
+  o `ctx.pendingRecord` quando faltou/cancelado (com ou sem multa). Antes
+  inseria a multa mas DEIXAVA o original pending → cobrança dupla
+  (R$ 200 + R$ 30 = R$ 230). Audit trail vai em `notes` do record
+  cancelado, descrição da multa nova carrega data: "Multa por falta · sessão 20/05/26".
+- **`useAgendaFinanceiro.js:59`** — fix dormente `'fixed'` → `'fixed_fee'`
+  (off-by-key contra schema; path nunca exercitado na Melissa, mas iria
+  quebrar se algum dia fosse).
+
+### Financial exceptions seedadas (tenant Bruno Terapeuta / owner Leonardo)
+- `patient_no_show` → `fixed_fee R$ 30`
+- `patient_cancellation` → `full`, `min_hours_notice=2`, `default_consume_on_miss=true`
 
 ---
 
-## 🚦 STATUS — Working tree LIMPA
+## 🔴 PRÓXIMO PASSO IMEDIATO — Cenário 10 (Status change AVULSA)
 
-```
+Doc HTML diz: testar status change numa sessão avulsa com cobrança pendente,
-On branch main
+mudando entre realizado / faltou / cancelado. As consequências financeiras
-Your branch is up to date with 'origin/main'.
+seguem `financial_exceptions` (regras configuradas pelo terapeuta sobre o
-nothing to commit, working tree clean
+que acontece com a cobrança nesses casos).
-```
+
+Possíveis pacientes pra teste: usar Joyce, Sándor ou outro com cobrança
+avulsa pendente já criada.
+
+**Esperado** (depende das `financial_exceptions` configuradas no tenant):
+- Realizada: status muda; cobrança permanece (caminho default)
+- Faltou: pode ter regra → cobrança 100% (paciente paga falta) ou cancela
+- Cancelado: pode ter regra → cancelar cobrança ou cobrar parcial
+
+Conferir:
+- `STATUS_TO_EXCEPTION` mapping em `useAgendaFinanceiro.js`
+- `getFinancialExceptionRule(tenantId, exceptionType)` retorna a regra
+- `handleStatusChange` orquestra: agenda update + financial adjust
+
+Após C10: C11 (status change pacote saldo — usar a infra do Usar/Revogar)
+→ C12 (antecipar pagamento) → C13 (edit cobrada).
+
+Quando todos passarem, replicar em **Rail** (`AgendaTerapeutaPage.vue`) e
+**Clínica** (`AgendaClinicaPage.vue`).
 
 ---
 
-## 📦 Histórico de commits da sessão (mais recente → mais antigo)
+## 📦 O que foi feito em 20/05 madrugada (C9 + rowGroup financeiro + bubble cobranca-atualizada)
 
-| # | Hash | Resumo |
+### Cenário 9 ✅ (Per-session — Michael Balint 12 × R$ 150)
-|---|------|--------|
+Testado e passou. Criou-se 1 rule + 12 agenda_eventos materializadas + 12 financial_records pending. Sem billing_contract. Cada sessão com badge $ amber individual. **Sem nenhuma `linha de pacote`** no popover (não tem contract → não aparece). Conforme esperado.
-| 24 | `6ad91e7` | passa preset-commitment-id pro AgendaEventDialog (fix botão Salvar sumido) |
+
-| 23 | `cf1cd67` | pré-popula eventRow com commitment_id + paciente nome/avatar/status |
+### `/melissa/financeiro-lancamentos` agrupado por paciente
-| 22 | `73788c7` | AgendaEventDialog: lockType auto-seleciona commitment "Sessão" (fix jornada/billing/freq sumidos) |
+- DataTable com `rowGroupMode='subheader'` + `groupRowsBy='patient_id'`
-| 21 | `30d09eb` | AgendaEventDialog: props lockType + lockPatient + slot #headerLeft (aditivos) |
+- Default: todos os grupos da página expandidos (watcher popula `expandedGroups` com unique patient_ids quando `recordsGrouped` muda)
-| 20 | `88dff50` | (REVERTIDO em 30d09eb) usa AgendaEventDialog GLOBAL via inject |
+- Header de grupo: avatar pequeno + nome + badge "N lançamento(s)"
-| 19 | `b040e15` | header custom do dialog Nova Sessão (ícone + título + nome) |
+- Click no chevron contrai/expande (auto via PrimeVue `expandableRowGroups`)
-| 18 | `42a39ed` | dialog Nova Sessão usa "Frequência" estilo AgendaEventDialog |
+- Sort estável: ordena outer por nome do paciente, preserva inner order (pai → filhos de multas/taxas)
-| 17 | `9e76e4e` | bloco "Recorrências do paciente" na Tab Agenda |
+
-| 16 | `f1d6fba` | dialog nova sessão integra useRecurrence (recorrência semanal) |
+### Bubble-up `@cobranca-atualizada`
-| 15 | `a8ab13b` | dialog inline nova sessão + createSession mutation |
+Antes: `AgendaEventoFinanceiroPanel.@cobranca-atualizada` disparava só `loadOccFinancialRecord` (interno do dialog). O `_paymentStateMap` da agenda ficava stale → card no FC só atualizava ao trocar de view.
-| 14 | `21c71f7` | addFinancial navega pra Financeiro + novo botão Agendar |
+
-| 13 | `64005a5` | fix openWhatsapp + dialog inline novo lançamento financeiro |
+Agora: `AgendaEventDialog._onCobrancaAtualizada` faz duas coisas:
-| 12 | `301a712` | editPatient abre PatientCadastroDialog INLINE (sem sair) |
+1. `loadOccFinancialRecord()` — refresca estado interno do dialog
-| 11 | `5d2c389` | fix sidebar cards encolhendo + gap das abas main |
+2. `emit('cobranca-atualizada')` — bubble pra MelissaLayout
-| 10 | `159b80d` | full-width + sidebar "Voltar pra Pacientes" no lugar de Configurações |
+
-| 9 | `71ee51d` | **Fase 8** wire-up final (Dialog → route /melissa/paciente?id=X) |
+MelissaLayout escuta nos 2 dialogs (principal + occurrenceMode) e chama `onCobrancaAtualizada` que dispara `M.refetch() + refetchEventosHoje()`. Resultado: card na agenda passa pra borda verde imediatamente após marcar pago.
-| 8 | `167e864` | **Fase 7** Tabs Documentos + Conversas (KPIs + embed componentes existentes) |
-| 7 | `e7c0f6c` | **Fase 6** Tab Financeiro + mark paid (mutation que legacy não tem) |
-| 6 | `8a8d2e0` | **Fase 5** Tab Agenda (KPIs + filtros + grupos por mês + ações) |
-| 5 | `1278e93` | **Fase 4** Tab Prontuário MVP (evolução via session.observacoes) |
-| 4 | `4fc0e3a` | **Fase 3** Tab Perfil (6 sections stacked + anchors) |
-| 3 | `ab7526b` | **Fase 2** Tab Visão Geral (4 KPIs + timeline + msgs + notas) |
-| 2 | `df61cc4` | **Fase 1** Foundation (5 composables + skeleton 7 tabs + slug paciente) |
-| 1 | `f3f0d83` | (pré-MelissaPaciente) preview teleport 3-way no Agendador/LinkExterno + chrome 6 páginas |
 
 ---
 
-## 📂 Arquivos novos / modificados
+## 📦 O que foi feito em 19/05 madrugada (C8 + Usar/Revogar saldo + UI de pacote)
 
-### NOVOS — composables + utils compartilhados
+### Cenário 8 ✅ (Pacote SALDO — Otávio Souza Ferreira 12 × R$ 50)
-- `src/features/patients/composables/usePatientDetail.js` (~108L) — patient + groups + tags
+Testado e validado. Contract criado com `charging_style='saldo'`, 0 events materializadas, 0 records. Modelo Cliniko: sessões materializam on-demand via Usar.
-- `src/features/patients/composables/usePatientSessions.js` (~155L) — agenda_eventos + computeds + `updateStatus`/`createSession` mutations
-- `src/features/patients/composables/usePatientFinancial.js` (~155L) — financial_records + computeds + `markPaid`/`markUnpaid`/`createRecord` mutations
-- `src/features/patients/composables/usePatientMessages.js` (~80L) — conversation_messages + computeds
-- `src/features/patients/composables/usePatientDocuments.js` (~110L) — documents + computeds (topType, pendentes, sizeTotalFormatted)
-- `src/features/patients/composables/usePatientRecurrences.js` (~110L) — recurrence_rules + cancel/reactivate + ativas/canceladas computeds
-- `src/features/patients/utils/patientFormatters.js` (~280L) — fmt* helpers + STATUS_LABEL/SEVERITY + tagStyle (luminance) + DOC_TYPE_LABEL + chConvLabel + recordStatus + RECORD_STATUS_LABEL + WEEKDAY_LABEL + fmtRecurrenceLabel/Fim
 
-### NOVO — página Melissa
+### UI do pacote (saldo + upfront)
-- `src/layout/melissa/MelissaPaciente.vue` (~2400L) — 7 abas funcionais, header custom, sidebar com Voltar pra Pacientes, dialog Lançamento inline, dialog Nova Sessão usando AgendaEventDialog real
+- **`_ruleContractMap`** em useMelissaAgenda: bulk-load agora popula contract info (id, style, totalSessions, sessionsUsed, packagePrice) por `recurrence_id`. Query usa `recurrence_rules.patient_id` como fonte autoritativa (cobre saldo sem materializadas).
+- **Normalize** injeta `contract` no evento → popover acessa via `ev.contract`.
+- **Popover** (`MelissaEventoPanel`): nova linha colorida abaixo do payment:
+  - Saldo: violeta `"Pacote saldo · N/M usadas"` + botão verde **"Usar"** (paymentState=none) OU vermelho **"Revogar"** (paymentState=pending)
+  - Upfront: verde `"Pacote · N/M realizadas"` (sem botão; cobrança já tratada)
+- **AgendaEventDialog**: info card mt-4 (saldo violeta / upfront emerald) com header (pacote+contador), body (total/per-session/restam), botão "Usar agora" ou "Revogar uso", hint explicando o modelo. Gateado por `occFinancialLoading` (spinner durante carga) pra evitar piscar entre estados.
 
-### MODIFICADOS — wire-up
+### Handlers Usar/Revogar atômicos
-- `src/layout/melissa/MelissaLayout.vue` — entry SECOES.paciente + render condicional `<MelissaPaciente :patient-id="String(route.query.id || '')" @close="fecharSecao" />`
+**`onUsarSessao`** em MelissaLayout (aceita payload do popover OU do dialog):
-- `src/layout/melissa/MelissaPacientes.vue` — `abrirProntuario` agora navega via `router.push('/melissa/paciente', query: { id })`. Removeu `<PatientProntuario>` Dialog. Watch em `route.query.edit` pra abrir cadastro full quando vem de `MelissaPaciente.editPatient`.
+1. Materializa virtual se necessário (preserva `determined_commitment_id` da regra)
-- `src/layout/melissa/MelissaAgenda.vue` — `abrirProntuarioPorId` igual. Removeu Dialog legacy.
+2. Status='realizado' + link `billing_contract_id`
-- `src/layout/melissa/composables/useMelissaAgenda.js` — adicionou `onCreateEventoForPatient(patientId)` (não usado mais após reverter inject, mas mantido)
+3. `create_financial_record_for_session` RPC com per-session amount
-- `src/features/agenda/components/AgendaEventDialog.vue` — **3 props aditivas** (lockType, lockPatient, slot #headerLeft) + watch que auto-seleciona commitment "Sessão" quando lockType. **Zero regressão (301 specs passando)**.
+4. Incrementa `billing_contracts.sessions_used`
+5. Se atingiu total → contract `status='completed'`
+6. Toast verde + fecha popover/dialog
+
+**`onRevogarSessao`** desfaz tudo:
+1. Cancela financial_record (status='cancelled')
+2. Decrementa sessions_used (não fica negativo)
+3. Reativa contract se estava completed
+4. Status volta pra 'agendado'
+5. Bloqueia se record já está `paid` (precisa estorno formal pelo Financeiro)
+6. **Backfill** de `determined_commitment_id` se NULL (fix de legado)
+
+### Fix: enum status_evento_agenda
+Era `'realizada'` no insert/update, DB exige `'realizado'` (masculino). Corrigido em todas as ocorrências.
+
+### Fix: campo "Título" indevido no dialog
+Sessão sem `determined_commitment_id` → `selectedCommitment=null` → `isSessionEvent=false` → mostra campo Título (que é só pra não-sessão). Fix: 
+- Materialize do Usar inclui `determined_commitment_id` da regra
+- Update path do Usar (sessão real após revogar) backfilla via query da rule
+- Revogar também backfilla — garante consistência mesmo sem novo Usar
+- SQL massivo de backfill disponível no HANDOFF pra limpar rows legadas
+
+### Fix: "Gerar fatura" não cabe em sessão de saldo
+Hide do botão "Gerar fatura" no popover quando há `contractInfo`. Geraria cobrança solta sem incrementar saldo → duplicação. Fluxo correto: usar "Usar".
+
+### Recorrências Aplicadas: cores + badges
+- Header stats: total **azul**, realizadas **verde**, faltaram **amber**, canceladas **cinza**, remarcadas **violeta**
+- Pills: badge sólido por status (Realizado=emerald-600, Faltou=amber-600, Cancelado=stone-500, Remarcado=violet-600)
+
+### Race condition no dialog
+- AgendaEventDialog mostrava botões "Usar"/"Revogar" baseado em `occFinancialRecord` que carrega async
+- Durante load (~500ms), botão errado podia aparecer → snap pro correto depois
+- Fix: spinner "Verificando estado…" enquanto `occFinancialLoading=true`; botões só renderizam após
+- Popover decidiu manter como está (race window pequena, fechar/reabrir resolve)
 
 ---
 
-## 🟡 PENDENTES PRA PRÓXIMA SESSÃO
+## 📦 O que foi feito em 19/05 noite (C7 + lock-edit + propagação cross-week)
 
-User mencionou: **"tem alguns ajustes pra fazer nessa tela ainda"** após o último fix
+### Cenário 7 ✅ (Pacote UPFRONT — Ana Souza Ferreira)
-do botão Salvar (commit `6ad91e7`). Ajustes específicos não foram detalhados ainda
+Testado e validado. Usuária criou Ana, R$ 200/sessão × 4 = R$ 800, marcou como pago em dinheiro pelo Financeiro. Visualização correta em mês AND em semana navegando pelas 4 semanas.
-— próxima sessão começa pelo feedback do user no dialog Nova Sessão.
 
-### Pendentes conhecidos (não ditos pelo user, mas observados)
+### Fase 6 (lock-edit cobrada) ativada em Melissa
-- **PatientProntuario.vue legacy (3593L)** continua existindo intocado. Usado por:
+Antes: `loadOccFinancialRecord` tinha guard `if (!props.occurrenceMode) return;` — só carregava em Rail/Clínica (edição de ocorrência). Em Melissa, `sessionPaymentRecord` paralelo alimentava só o Resumo lateral, sem trigger de lock.
-  - `TherapistDashboard.vue` (homepage role therapist sem Melissa)
+
-  - `PatientsListPage.vue` (rota `/therapist/patients`)
+Agora unificado: `occFinancialRecord` carrega em ambos modos:
-  - Quando user troca pra Melissa em `/account/profile`, vê a versão nativa
+- Card Sessão / Honorários ganha **Tag** (em vez de Select billingType) quando há cobrança
-  - Pra deletar de vez precisa portar TherapistDashboard + PatientsListPage também
+- Body do card mostra **Message "Cobrança de R$ X já emitida"** + cadeado
-- **Tab Prontuário** é MVP usando `agenda_eventos.observacoes` como evolução. Quando schema clínico (`anamnese`, `clinical_notes`, `plano_terapeutico`) for adicionado, vira o real
+- Tipo de cobrança (Particular/Convênio/Gratuito) bloqueado
-- **2 errors pré-existentes em MelissaLayout.vue** (duplicate key 'financeiro' L242, empty block L1130) — não foram tocados durante o port
+- Edição de serviços/preço bloqueada
+
+### Propagação cross-week de pacote upfront pago/pendente
+**Bug descoberto durante C7:** ao navegar pra semanas futuras (onde só virtual da Ana 2/3/4 aparecia, sem real event paid na view), o `_rulePaymentMap` era zerado pelo else branch do bulk-load → virtuais perdiam estado paid.
+
+Fix em `useMelissaAgenda.js _reloadRange`:
+- Maps (paymentStateMap, amountMap, rulePaymentMap) inicializados SEMPRE no início
+- Propagação agora roda **independente de realIds.length** (ie, mesmo em semanas só-com-virtuais)
+- Coleta `ruleIdsInView` de TODOS eventos da view (reais + virtuais com recurrence_id)
+- Cross-week query: pra cada rule em view, busca QUALQUER evento sibling (inclusive em outras semanas) + seus records paid/pending → determina estado do contrato
+- Propaga estado pra eventos reais (via map) + virtuais (via rulePaymentMap acessado pelo normalize)
+
+### Atalho "Gerar fatura" no popover
+- Pill amber pequeno ao lado de "A cobrar R$ X" no popover (`paymentVariant === 'none' && !is_occurrence`)
+- Click → `gerarCobrancaManual` direto, fecha popover pra impedir double-click
+- Tooltip: "Gerar fatura agora"
+
+### Info de pacote no popover
+- Header agora mostra `Sessão · Pacote · N sessões` (computed `seriesLabel` lê de `_raw` do rule)
+
+### Botão "Excluir série inteira"
+- Novo emit `delete-series` em `MelissaEventoPanel` + botão ao lado de "Excluir sessão" quando evento tem `recurrence_id`
+- Handler `onDeleteSeries` em MelissaLayout faz hard delete: `financial_records` pendentes → `agenda_eventos` materializados → `recurrence_rules` (CASCADE leva exceptions + rule_services)
+- Bloqueia se algum record tem `status='paid'` (estornar primeiro)
+
+### RPC `create_financial_record_for_session` ignora cancelled
+**Migration 20260519000001:** idempotência da RPC passou a filtrar `AND status != 'cancelled'` além de `deleted_at IS NULL`. Antes: cancelar cobrança sem querer → todo "Gerar fatura" subsequente retornava o cancelado em vez de criar nova. Toast verde mentindo.
+
+Memória durável em `memory/project_rpc_idempotency_cancelled.md`.
+
+### `cancel_session` exception some da agenda
+- `useRecurrence.expandRules` agora pula ocorrência com `exception.type === 'cancel_session'` (era visível com status cancelado; doc dizia "some da agenda" mas código mantinha)
+- `patient_missed` / `therapist_canceled` / `holiday_block` permanecem visíveis como histórico
+
+### `recurrence_exceptions` cancel idempotente
+- Cancel de ocorrência (virtual e materializada) usa `upsert` com `onConflict: 'recurrence_id,original_date'` — não quebra mais com unique violation quando há exception zumbi de tentativa anterior.
+
+### Visualização paid/pending de upfront em virtuais
+- `MelissaEventoPanel.showPaymentRow` antes excluía virtuais incondicionalmente. Agora só esconde quando `paymentState === 'none'` (saldo/sem pacote continua limpo; upfront propagado mostra).
+- `MelissaAgenda.fcEvents`: removida exigência de `!is_occurrence` no `isPaidSession` e no badge $ pendente. Virtuais herdadas via propagação mostram borda verde/badge amber.
+
+### `onVerLancamentos` cobre virtual de upfront
+- Antes: virtual sempre toast "Sem lançamentos". Agora: busca records via siblings da série pra encontrar o do pacote. Saldo/sem pacote continua com toast.
+
+### Confirmação 3 decisões UX (não codar)
+Antes de C7, user perguntou e concordou:
+1. Editar serviço já lançado e pago → **NÃO** (cobrança fiscal imutável)
+2. Alternar Particular/Convênio/Gratuito em série com cobrança ativa → **NÃO** (mesma razão)
+3. "Gerar fatura" extra em sessão coberta por contrato upfront → **NÃO** (duplicaria cobrança)
+Tudo isso o lock-edit (Fase 6 ativada acima) cobre.
 
 ---
 
-## 🧠 Conhecimento adicional acumulado nesta sessão
+## 📦 O que foi feito em 18/05
 
-### Decisões arquiteturais
+### Cenário 4 (Joyce · "Já recebi") ✅
-1. **`MelissaPaciente` segue o padrão Melissa** (mesmo prefix `mpa-`, glass chrome, sidebar 320px à esquerda, drawer mobile). Diferente das outras Melissa Pages: **largura total** (sem `right: max(...)`) porque conteúdo (KPIs grid + tabelas + timeline) precisa de espaço.
+- Testado e passou: toast "Cobrança paga R$ 180,00 recebido via PIX", record nasceu `paid + payment_method=pix + paid_at=now()`.
 
-2. **Reuso do `AgendaEventDialog`** via 2 props aditivas (`lockType` + `lockPatient`) + slot `#headerLeft` — caminho A escolhido após discussão honesta sobre drift risk de duplicação.
+### Novo indicador: barra esquerda verde para sessão paga
+- Brainstorm de 6 opções; user escolheu #6 (3 canais visuais distintos por estado).
+- `MelissaAgenda.vue:395-419` — computa `isPaidSession` (sessão+paciente+não-virtual+`paymentState==='paid'`) e adiciona classe `ma-evt--paid` ao FC event (combina com `ma-evt--inactive-patient` se ambos).
+- `MelissaAgenda.vue:2325-2335` — CSS força `border-left-color: #10b981 !important` (emerald-500, 4px). `!important` necessário porque FC seta `borderColor` inline. Trata também list view (`.fc-list-event-dot`).
+- Doc HTML atualizado: legenda "Indicadores visuais" agora descreve **3 estados** (pendente / pago / neutro) com 3 mocks empilhados; estado-alvo do C4 reescrito mencionando a barra verde.
+- Decisão salva em `memory/project_agenda_payment_indicators.md`.
 
-3. **Inject vs state local** — `MelissaPaciente` injeta `MELISSA_AGENDA_KEY` SÓ pra ler dados pesados (commitmentOptions, workRules, etc) e mantém state LOCAL pro dialog (sessaoDialogOpen/EventRow/StartISO/EndISO). Não colide com dialog global da Agenda.
+### Linha "Cobrança" no popover + Resumo do dialog
+- **Popover `MelissaEventoPanel`** — antes só mostrava amber "A receber R$ X" pra pendente. Agora cobre os 3 estados, com cor + ícone por variante:
+  - `paid` → `pi-check-circle` verde, label **"Pago · R$ X,XX"**
+  - `pending` → `pi-dollar` amber, label **"A receber R$ X (cobrança pendente)"** (mantido)
+  - `none` → `pi-dollar` amber, label **"A cobrar R$ X"** ou **"Cobrança ainda não gerada"** (mantido)
+  - CSS reescrito em 3 modificadores `.evento-row--pay-{paid|pending|none}` (com dark mode).
+- **Resumo lateral do `AgendaEventDialog`** — nova linha entre `pi-clock` e `pi-map-marker` em ambas as cópias (mobile inline + desktop floating).
+  - Novo ref `sessionPaymentRecord` em `useAgendaEventLifecycle.js:104+` (sem guard de `occurrenceMode`, contrário ao `occFinancialRecord` que continua só pra Rail/Clínica). Loader `loadSessionPaymentRecord` chamado no mesmo lifecycle.
+  - Computed `paymentSummary` em `AgendaEventDialog.vue:951+` retorna `{icon, cls, label}` pra 5 casos: paid (verde + paid_at), overdue (vermelho + due_date), pending (amber + due_date), sem cobrança c/ valor (neutro), sem cobrança s/ valor (neutro).
+  - `@cobranca-atualizada` do `AgendaEventoFinanceiroPanel` agora também dispara `loadSessionPaymentRecord` pra a linha refrescar.
+  - **Importante:** `occFinancialRecord` (que aciona lock-edit) NÃO foi tocado de propósito — esse é território da Fase 6/C13 (Edit cobrada). Manter dois refs separados evita ativar lock prematuro em Melissa.
 
-4. **Inicialização do dialog**: precisa passar **TANTO** `determined_commitment_id` no eventRow **QUANTO** prop `presetCommitmentId` separada. O resetForm lê o primeiro pra popular `form.commitment_id`; o lifecycle lê o segundo pra decidir step inicial. Sem ambos, cair em race condition (lifecycle reset desfaz selectCommitment).
+### Preparação do C5 (Sándor + Unimed Nacional) — UX de convênio refinado (3 issues)
 
-5. **Pré-popular paciente_nome/avatar/status no eventRow** é obrigatório pra não-edit — o composer só faz fetch async do nome quando isEdit=true.
+User tentou rodar C5 e bateu em 3 problemas seguidos. Cada um virou um fix:
 
-### Hotspots de drift no `AgendaEventDialog`
+1. **Botão "Cadastrar" do procedimento navegava pra `/pages/notfound`**
-Arquivo tem 5 composables que fazem o trabalho pesado: `useAgendaEventComposer` (state + computeds), `useAgendaEventActions` (save/delete), `useAgendaEventLifecycle` (watchers + init), `useAgendaEventPickerBilling` (selectCommitment, paciente picker), `agendaEventHelpers` (utils). Mexer aqui é seguro pelo coverage de **301 specs**.
+   - Root cause: `goToConveniosConfig` em `AgendaEventDialog.vue` prefixava com `/therapist` ou `/admin`, mas `/configuracoes/*` é rota **raiz** sob `AppLayout` (sibling, não filho). Em Melissa, convênios mora dentro do próprio layout via `secao: 'cfg-convenios'` (sem URL própria).
+   - Fix descartado: o user não queria sair da agenda. Em vez disso, criamos um quick-create inline (ver #2). `goToConveniosConfig` foi removida (dead code virou armadilha).
 
-### Slug `/melissa/paciente?id=<uuid>`
+2. **Quick-create de procedimento inline (sem sair da agenda)**
-Registrado em `MelissaLayout.vue` SECOES + adicionado a `MELISSA_NON_CONFIG_SLUGS`. ID vem via query param. Funciona pra deep-link.
+   - Novo componente `InsurancePlanServiceQuickCreateDialog.vue` (modelo do `InsurancePlanQuickCreateDialog`). 2 campos: nome do procedimento + valor que o convênio paga. Insere em `insurance_plan_services` pro `insurance_plan_id` ativo.
+   - Wiring em `useAgendaEventLifecycle.js`: novo `planServiceQuickDlgOpen` + `openPlanServiceQuickCreate()` + `onPlanServiceCreated(service)`. Após criar, recarrega `loadInsurancePlans` e **auto-seleciona** o novo procedimento **só quando nada estava selecionado antes** (preserva escolha quando user já tinha selecionado X e está só cadastrando Y pra próxima).
+   - UI refatorada (`AgendaEventDialog.vue:3110+`): a caixa cinza com botão "Cadastrar" agora aparece **sempre** que um convênio está selecionado. Quando 0 procedimentos: **"Este convênio ainda não tem procedimentos cadastrados."** Quando 1+: **"Se quiser adicionar mais procedimentos a este convênio:"**.
+   - `planServiceQuickDlgOpen` adicionado ao `anyChildDialogOpen` pra esconder o Resumo flutuante enquanto o quick-create está aberto.
+
+3. **Botão "+ Novo convênio" faltando em `/melissa/cfg-convenios` (e na rota canônica também)**
+   - Root cause: `ConfiguracoesConveniosPage.vue` tinha o form de "Novo convênio" condicionado a `addingNew === true`, mas **nenhum botão setava esse flag**. Empty state mandava "Clique em 'Novo convênio'" sem botão pra clicar.
+   - Fix: toolbar simples no topo do template `<template v-else>` com `<Button label="Novo convênio" icon="pi pi-plus" @click="addingNew = true">`. Empty state corrigida pra apontar pro botão certo.
+
+### Hint contextual abaixo do card Sessão / Honorários
+
+- User pediu mensagem clarificando que "Nº da guia" é opcional em convênio.
+- **Tentativa 1 (errou o lugar):** coloquei o hint em `AgendaEventDialog.vue:1826` dentro do bloco `v-if="occurrenceMode"` (só edita ocorrência em Rail/Clínica). User não viu.
+- **Tentativa 2 (correta):** adicionado em `AgendaEventDialog.vue:2305+` (fluxo principal Melissa, fora do occurrenceMode). Mantive a tentativa 1 também — não atrapalha, só ativa em outro contexto.
+- Texto: convênio = **"Nº da guia é opcional — você pode salvar a sessão e preencher depois, quando o convênio responder."** Gratuito = **"Sessão gratuita — nenhum lançamento será gerado no Financeiro."** Particular = sem hint (não há ambiguidade).
+- Condição: `isSessionEvent && !occFinancialRecord && billingType === 'convenio'|'gratuito'`. Esconde quando há cobrança paga/pendente (lock-edit) — Message do panel já cobre.
+- CSS: `.aed-billing-hint` em `AgendaEventDialog.vue:3558+` — barra esquerda primary, fundo neutro leve, fonte 0.78rem.
+- Label do "Nº da Guia" no service-picker dialog também ganhou **(opcional)**.
 
 ---
 
-## 🛠️ Comandos úteis
+## 📦 O que foi feito antes (16/05 noite/madrugada)
 
-```bash
+### Cenário 1 (Bloqueio) ✅
-# Specs do agenda (regression check pro AgendaEventDialog)
-npx vitest run src/features/agenda/composables/__tests__
 
-# Lint só dos arquivos do MelissaPaciente
+1. **Fix `bloqueioCobrindo is not defined`** — função estava no escopo de `useMelissaAgenda` mas `onSelectTime` mora no `_buildHandlers` (outro escopo). Passada via `deps`. Mesmo padrão que `_openStatusDialog`.
-npx eslint src/layout/melissa/MelissaPaciente.vue src/features/patients/composables/usePatient*.js src/features/patients/utils/patientFormatters.js
+2. **Soft warn dentro do dialog** em vez de toast atrás do overlay — novo ref `dialogBlockOverlap` no composable + nova prop `blockOverlapWarning` no `AgendaEventDialog` + Message warn no topo do step 1. Reset nos outros openers (`onCreateEvento`, `onCreateEventoForPatient`, `onEditEvento`).
+3. **Doc HTML Cenário 1 expandido** em 1a (criar bloqueio) + 1b (agendar sobre bloqueio), com mock visual da Message + comparação com agendador público (que veta).
 
-# Testar visualmente
+### Cenário 2 (Avulsa sem cobrança) ✅
-npm run dev
+
-# → http://localhost:5173/melissa/paciente?id=<uuid-real-de-paciente>
+4. **Fonte da hint chargeMode** subiu de `0.72rem` → `0.8125rem` (acima de `text-xs`).
-```
+5. **Card Frequência avulsa** refeito — antes era empty state convidando configurar; agora renderiza com `.aed-pay-summary` (mesma estrutura do estado configurado: "Tipo: Avulsa · Sessão única, sem repetição" + botão Editar).
+6. Doc HTML Cenário 2 atualizado.
+
+### Cenário 3 (Avulsa cobrar ao salvar) ✅
+
+7. **Refactor payment: `paymentSettlement` → `paymentMethod` + `markPaidNow`**
+   - UI antiga misturava método e status num único Select ("Já recebi — PIX").
+   - Agora 2 controles: Select forma (Enviar link / PIX / Dinheiro / Depósito / Cartão maquininha — SEM prefixo "Já recebi —") + SelectButton status (Cobrança pendente / Já recebi (dar baixa)).
+   - SelectButton só aparece quando método ≠ link (Asaas só liquida via webhook).
+   - Watcher força `markPaidNow=false` se voltar pra 'link'.
+   - Wire: AgendaEventDialog → useAgendaEventActions → useMelissaAgenda (handler avulsa + `_createPackageContract`).
+8. **Indicadores visuais de pagamento** (novidade da sessão):
+   - Bulk-load de `financial_records` em `_reloadRange` etapa 4 (1 query única, mapa eventId → 'paid' | 'pending' | 'none').
+   - `normalizeForMelissa` agora injeta `paymentState` + `price` no evento.
+   - **Badge $ no canto** dos eventos da agenda — círculo amber 16px no canto superior direito. Só pra sessão + paciente + não-virtual + paymentState !== 'paid'.
+   - **Linha "A receber"** no popover (`MelissaEventoPanel`) — texto adaptativo: "A receber R$ X (cobrança pendente)" se pending, "A cobrar R$ X" se none, "Cobrança ainda não gerada" se sem valor.
+9. **🐛 Bug fix `pickDbFields` faltando `modalidade`** — sessões avulsas eram salvas sem modalidade, DB caía no default 'presencial' independente da escolha. Adicionado ao whitelist em `useMelissaAgenda.js:74`. **TODAS as sessões avulsas criadas no Melissa antes desse fix estão como 'presencial' no DB** — pode precisar rodar UPDATE manual no banco se quiser corrigir histórico. Gotcha salvo em `memory/project_pickdbfields_whitelist.md`.
+10. **Doc HTML atualizada amplamente**:
+    - Nova seção topo `★ Indicadores visuais de pagamento` com mocks (badge $ + linha popover) e link em violeta no TOC.
+    - Caixa violeta "Indicadores visuais" em cada cenário relevante (C2-C9).
+    - C4 ganhou caixa verde "estado-alvo" (sem badge, sem linha — pago).
+    - Receita do C3 e C4 atualizadas com os 3 controles (Cobrança ao salvar / Forma de pagamento / Status do pagamento) e opções limpas (sem prefixo "Já recebi —").
 
 ---
 
-## ▶️ Próxima sessão — onde retomar
+## 🧭 Onde estamos no plano de 9 fases
 
-1. **Ler primeiro**: este HANDOFF.md (você já está nele)
+| Fase | Status |
-2. **Aguardar feedback do user** sobre ajustes específicos no dialog Nova Sessão (mencionou que tem mais alguma coisa)
+|---|---|
-3. **Possíveis frentes**:
+| **1** Compromisso SEM paciente | ✅ |
-   - Polish do dialog Nova Sessão pós-feedback
+| **2** Compromisso COM paciente | ✅ testado (C1-C3 done) |
-   - Port do TherapistDashboard pra remover dependência do PatientProntuario legacy
+| **3** Recorrência + replicar occurrenceMode Rail/Clínica | ⏳ |
-   - Schema clínico (anamnese/evolução) pra Tab Prontuário sair do MVP
+| **4** Modo disparo cobrança híbrido | ⚠️ parcial |
-4. **Antes de mexer em `AgendaEventDialog`**: rodar `npx vitest run src/features/agenda/composables/__tests__` (301 specs) pra confirmar baseline limpo
+| **5** Status change → confirm dialog | 🔄 Melissa codado + indicadores visuais done; falta testar (C10-C12) + replicar Rail/Clínica |
+| **6** Edit cobrada | ✅ |
+| **7** Pagamento separado | ⏳ |
+| **8** Refund/credit note | ⏳ |
+| **9** Plano Inicial | 📋 |
 
-Boa sessão!
+---
+
+## 📋 Roteiro de testes restantes (`src/docs/agenda-compromisso-financeiro-cenarios.html`)
+
+| # | Cenário | Status |
+|---|---|---|
+| 1 | Bloqueio (criar + agendar sobre) | ✅ |
+| 2 | Avulsa sem cobrança | ✅ |
+| 3 | Avulsa cobrar ao salvar | ✅ |
+| 4 | Avulsa "já recebi" no salvar | ✅ |
+| 5 | Avulsa convênio (Sándor + Unimed) | ✅ |
+| 6 | Recorrente sem pacote (Maria Magali / Anna Freud) | ✅ |
+| 7 | Pacote upfront (Ana Souza Ferreira 4 × R$ 200) | ✅ |
+| 8 | Pacote saldo (Otávio 12 × R$ 50) | ✅ |
+| 9 | 1 por sessão (Michael Balint 12 × R$ 150) | ✅ |
+| **10** | **Status change avulsa (realizado/faltou/cancelado)** | 🔴 **PRÓXIMO** |
+| 10 | Status change avulsa (realizado/faltou/cancelado) | ⏳ |
+| 11 | Status change pacote saldo | ⏳ |
+| 12 | Antecipar pagamento (Carl Jung) | ⏳ |
+| 13 | Edit cobrada | ⏳ (parcialmente — lock ativo em Melissa pós-19/05 noite) |
+
+---
+
+## 📋 Como retomar amanhã (cego)
+
+1. `git status` — confirmar working tree intacto
+2. **Ler HANDOFF até o fim**
+3. Abrir `src/docs/agenda-compromisso-financeiro-cenarios.html` no browser pra ver o estado atual do doc viva
+4. **Começar pelo Cenário 4** (Joyce, "Já recebi (dar baixa)")
+5. Cada cenário que passar:
+   - Atualizar status pra ✅ aqui no HANDOFF
+   - Se descobrir bug ou texto divergente, corrigir código + doc na hora
+6. Quando todos os 13 passarem: replicar em **Rail** e **Clínica**
+7. Adicionar `professional_cancellation` no `STATUS_TO_EXCEPTION`
+8. Marcar Fase 5 como ✅
+9. Decidir Fase 4 (modo disparo cobrança híbrido) OU Fase 3 (replicar occurrenceMode)
+
+---
+
+## 🚨 Pendência IMPORTANTE — não esquecer
+
+**Pós-Fase 9** (quando concluirmos TODAS as fases 1-9):
+- User vai passar prompt específico pra criar **documentação completa da parte de ajuda** do sistema
+- Está em `memory/project_pendencia_doc_ajuda.md`
+- O doc `agenda-compromisso-financeiro-cenarios.html` já está sendo escrito de forma que vira a doc final pra usuário (cada teste validado vira parte da doc)
+
+**Histórico modalidade='presencial' no DB:**
+- Bug do `pickDbFields` afetou TODAS as sessões avulsas criadas no Melissa até 16/05/2026
+- Se quiser corrigir histórico, rodar UPDATE manual identificando sessões cuja modalidade visual era online (não há como saber retroativamente — perdido)
+- Going forward o fix já cobre
+
+---
+
+## ⚠️ Gotchas duráveis (atualizados)
+
+- **`MelissaBloqueios.vue` admin ≠ `BloqueioDialog` (4 modos)** — casos distintos
+- **`agenda_excecoes` foi dropada** em 13/05
+- **`financial_records.type` undefined sem `type` no BASE_SELECT** — fix 14/05 cedo
+- **`financial_records.description` undefined sem `description` no BASE_SELECT** — fix 14/05 noite
+- **`handleStatusChange` em `useAgendaFinanceiro.js` está ÓRFÃO** — não reativar
+- **`_openStatusDialog` + `bloqueioCobrindo` + `dialogBlockOverlap`** declarados no `useMelissaAgenda` mas usados em `_buildHandlers` — passados via `deps`. **NÃO ESQUECER ao replicar em Rail/Clínica**
+- **`billing_contracts.charging_style`** distingue upfront/saldo/per_session
+- **Ocorrência virtual tem `id="rec::<rule>::<date>"`** — detectar via `typeof === 'string' && startsWith('rec::')` antes de query Supabase
+- **`chargeMode` default dinâmico:** `'session'` em avulsa, `'none'` em recorrente
+- **Toast atrás do overlay do dialog** — usar Message no topo do dialog em vez de toast quando contexto for dentro de dialog modal
+- **Cuidado com `pickDbFields` whitelist** — `useMelissaAgenda.js:74` descarta campos não listados silenciosamente. Sintoma: campo escolhido na UI mas DB tem valor default. Memória: `memory/project_pickdbfields_whitelist.md`
+- **`paymentSettlement` foi renomeado** em 16/05 — agora `paymentMethod` (string) + `markPaidNow` (bool). Handler aplica `payment_method` sempre, `status='paid'` só quando markPaidNow=true && method!='link'
+- **Bulk-load de paymentState em `_reloadRange` etapa 4** — 1 query única em `financial_records` mapeada por `agenda_evento_id`. Anota `paymentState` no normalize. Badge na agenda + linha popover lêem daqui
+
+---
+
+## 🧠 Decisões persistidas (memory/)
+
+**Indicadores visuais (16/05):**
+- Badge $ no canto: só sessão + paciente + não-virtual + !paid
+- Linha popover: 3 textos (a receber pending / a cobrar none / cobrança não gerada)
+- Bulk-load 1x por _reloadRange, não query por evento
+- Ocorrências virtuais sempre paymentState='none' (cobertas por contrato)
+
+**Payment refactor (16/05):**
+- Separar método (forma) de status (já pago?) — controles independentes na UI
+- Método 'link' (Asaas) força markPaidNow=false (gateway externo)
+- Wire format: `arg.paymentMethod` + `arg.markPaidNow` (no lugar de `arg.paymentSettlement`)
+
+**Bugs evitar repetir:**
+- Sempre adicionar campo novo ao `pickDbFields.allowed` quando adicionar coluna em agenda_eventos
+- Sempre adicionar campo novo ao `BASE_SELECT` quando query custom
+- Detectar `is_occurrence` ou `rec::` antes de query por UUID
+- Refs/funções do composable principal NÃO ficam acessíveis em `_buildHandlers` — passar via `deps`
+- Toast dentro de dialog modal fica atrás do overlay — usar Message

Obsidian/Brain/wiki/agenda-billing-pesquisa-mercado.md

@@ -0,0 +1,228 @@
+---
+title: Pesquisa de mercado — fluxo de compromisso e cobrança
+date: 2026-05-13
+status: levantamento
+players: Cliniko, SimplePractice, TherapyNotes
+---
+
+## Contexto do produto
+
+SaaS BR pra clínicas de psicologia, multi-tenant. Agenda + paciente + recorrência já funcionando. Invariante "cobrança emitida é imutável pelo dialog da agenda" já implementada (padrão SimplePractice). Auditando fase-a-fase o fluxo antes de fechar gaps. Restrições fiscais BR: PIX, NFS-e, LGPD.
+
+Cross-links: [[recorrencia-agenda]], [[index]]
+
+---
+
+## 1. Criação de compromisso SEM paciente
+
+### Cliniko
+- **Default:** existe entidade dedicada chamada **Unavailable block**. Não é appointment — não interfere em relatórios clínicos. Funciona como bloqueio puro de calendário (almoço, reunião, férias, manutenção).
+- **Admin pode:** criar **Unavailable block types** customizados (nome, duração default, cor). Aceita arquivamento individual ("Archive" remove o bloco).
+- **Fonte:** [Scheduling time off](https://help.cliniko.com/en/articles/1023892-scheduling-time-off), [Changing Your Calendar to Time Blocks](https://help.cliniko.com/en/articles/1024048-changing-your-calendar-to-time-blocks).
+
+### SimplePractice
+- **Default:** duas entidades distintas — **Calendar event** (cinza escuro, para reunião, supervisão, tempo pessoal) e **Out of office (OOO) block** (cinza claro, para indisponibilidade que deve bloquear request de agendamento). Calendar events também podem ser recorrentes.
+- **Admin pode:** marcar evento como recorrente; OOO bloqueia automaticamente o widget de pedidos de horário online.
+- **Fonte:** [Creating a calendar event](https://support.simplepractice.com/hc/en-us/articles/41930878513933-Creating-a-calendar-event), [Managing out of office blocks](https://support.simplepractice.com/hc/en-us/articles/41931023345165-Managing-out-of-office-blocks).
+
+### TherapyNotes
+- **Default:** dois tipos — **Scheduled Event** (atividade não-clínica: reunião, supervisão, treinamento; aparece no calendário do clínico) e **Unavailable** (vetar agendamento de pacientes em horários específicos: férias, almoço, compromisso pessoal). Ambos suportam descrição, duração e recorrência sem vincular paciente.
+- **Admin pode:** decidir clínico-alvo, frequência (one-time ou recurring), texto livre.
+- **Fonte:** [Schedule Non-Clinical Events](https://support.therapynotes.com/hc/en-us/articles/30661451456667-Schedule-Non-Clinical-Events), [Quick Start: Scheduling](https://support.therapynotes.com/hc/en-us/articles/30661279632539-Quick-Start-Scheduling).
+
+**Convergência:** os 3 têm entidade não-clínica separada de "appointment" — nunca usam appointment-sem-paciente como hack.
+
+---
+
+## 2. Criação de compromisso COM paciente
+
+### Cliniko
+- **Default:** appointment exige paciente + appointment type + data/hora + practitioner. Paciente pode ser criado on-the-fly direto do dialog do appointment com apenas nome (descrição/categoria são opcionais).
+- **Admin pode:** definir custom patient fields opcionais; appointment type carrega billable items default associados.
+- **Fonte:** [Booking an appointment](https://help.cliniko.com/en/articles/1024061-booking-an-appointment), [Set up appointment types](https://help.cliniko.com/en/articles/1023911-set-up-appointment-types).
+
+### SimplePractice
+- **Default:** appointment exige cliente. Existe entidade intermediária chamada **Prospective client / Inquiry** — perfil parcial usado pra leads vindos de contact form ou pedido online. Pode-se enviar intake antes mesmo de aceitar o appointment (perfil definitivo só nasce ao aceitar).
+- **Admin pode:** mandar link de agendamento; criar task de follow-up; enviar intake; rodar prescreener; converter inquiry em client.
+- **Fonte:** [Managing prospective clients on the Inquiries page](https://support.simplepractice.com/hc/en-us/articles/33726366744589-Managing-prospective-clients-on-the-Inquiries-page), [Adding a new client](https://support.simplepractice.com/hc/en-us/articles/12416306860429-Adding-a-new-client-and-navigating-your-Clients-and-contacts-list).
+
+### TherapyNotes
+- **Default:** appointment clínico exige client + clinician + appointment type + date. Cliente novo precisa pelo menos de **last name**; demais campos (DOB, endereço, e-mail, sexo administrativo, HIPAA acknowledgment) só viram obrigatórios quando se vai submeter claim de plano ou ativar portal.
+- **Admin pode:** liberar last-name-only para um "stub client" que recebe billable items mas não é submetível a plano até completar cadastro.
+- **Fonte:** [Add a New Client](https://support.therapynotes.com/hc/en-us/articles/30661347776539-Add-a-New-Client), [Schedule a Clinical Appointment](https://support.therapynotes.com/hc/en-us/articles/30661407698203-Schedule-a-Clinical-Appointment).
+
+**Convergência:** todos aceitam appointment com cadastro de paciente mínimo. SimplePractice é o único com camada formal de "lead" pré-prontuário.
+
+---
+
+## 3. Cobrança / fatura — quando é gerada?
+
+### Cliniko
+- **Default:** invoice é **explicitamente criada** pelo usuário a partir do appointment (botão "Create invoice" no card do compromisso). Não há geração automática no agendamento.
+- **Admin pode:** vincular billable items / produtos a um appointment type, então o "Create invoice" já vem populado. Em fluxo de pagamento online, a invoice é gerada e marcada como paga automaticamente no momento do pagamento confirmando o appointment.
+- **Fonte:** [Create an invoice](https://help.cliniko.com/en/articles/1023907-create-an-invoice), [Relate billable items and products to an appointment type](https://help.cliniko.com/en/articles/1023847-relate-billable-items-and-products-to-an-appointment-type).
+
+### SimplePractice
+- **Default:** geração **automática**, configurável globalmente entre Daily (overnight, à meia-noite do timezone da prática), Monthly ou Manual. Status do appointment determina se vira invoice: apenas appointments com status **Show**, **Late canceled** ou **No show** geram invoice automaticamente.
+- **Admin pode:** escolher daily/monthly/manual em Settings → Client billing → Client billing documents. Recomendação oficial: Daily quando cobra na hora da sessão; Monthly quando fecha o mês.
+- **Fonte:** [Setting up your billing and automations](https://support.simplepractice.com/hc/en-us/articles/207925643-Setting-up-your-billing-and-automations), [Managing appointment statuses and billing](https://support.simplepractice.com/hc/en-us/articles/360018410872-Managing-appointment-statuses-and-billing), [Best practices for time-of-session billing](https://support.simplepractice.com/hc/en-us/articles/115000837406-Best-practices-for-time-of-session-billing).
+
+### TherapyNotes
+- **Default:** billing line item é gerado **quando a nota da sessão é completada e assinada** pelo clínico. Cada appointment tem aba Billing acessível direto do dialog, mas o disparo de claim/invoice depende de note signed.
+- **Admin pode:** configurar default billing method por payer; o To-Do list cria o lembrete pra submeter claim ou gerar CMS-1500 assim que a nota é assinada.
+- **Fonte:** [Billing Overview](https://support.therapynotes.com/hc/en-us/articles/30661437130139-Billing-Overview), [Submit Electronic Claims](https://support.therapynotes.com/hc/en-us/articles/30661415430811-Submit-Electronic-Claims), [Quick Start: Billing](https://support.therapynotes.com/hc/en-us/articles/30661397280155-Quick-Start-Billing).
+
+**Convergência:** ninguém cobra no momento de criar o appointment (futuro). Cliniko = manual sob demanda. SimplePractice = automático pós-sessão (status driven). TherapyNotes = automático pós-assinatura de nota (clinical-doc driven).
+
+---
+
+## 4. Recorrência (séries) — billing
+
+### Cliniko
+- **Default:** repeating appointment (daily/weekly/fortnightly/monthly). Cada ocorrência é **appointment independente**; invoice continua sendo manual por ocorrência. Pra pacotes, recomenda usar **patient cases + account credit**: cobra o pacote inteiro upfront, o crédito fica no perfil do paciente e é consumido por cada invoice subsequente.
+- **Admin pode:** decidir entre invoice-por-sessão (manual ou via pagamento online) ou pacote upfront via account credit.
+- **Fonte:** [Book repeating appointments](https://help.cliniko.com/en/articles/1777286-book-repeating-appointments), [Tracking packages with patient cases and account credit](https://help.cliniko.com/en/articles/6477363-tracking-packages-with-patient-cases-and-account-credit).
+
+### SimplePractice
+- **Default:** série de até 100 ocorrências, recorrência semanal/mensal/anual. Cada ocorrência é independente para billing — invoice é criada na ocorrência conforme regra global daily/monthly. Editar uma ocorrência pergunta "just this one" ou "all in series". Ao deletar série inteira incluindo passado, **passa por cima** de ocorrências sem nota ou invoice anexada; ocorrências com invoice/nota são preservadas.
+- **Admin pode:** ajustar fee de ocorrência já faturada via **fee adjustment invoice** (novo doc que ajusta o saldo, não toca a invoice original — esse é exatamente o padrão "cobrança emitida imutável" já adotado no projeto).
+- **Fonte:** [Managing recurring appointments](https://support.simplepractice.com/hc/en-us/articles/41930568779021-Managing-recurring-appointments), [Creating invoices](https://support.simplepractice.com/hc/en-us/articles/207925663-Creating-invoices).
+
+### TherapyNotes
+- **Default:** recurring appointments indefinidos ou com data-fim. Cada ocorrência tem nota e billing independentes — billing line item nasce com a assinatura de cada nota individualmente.
+- **Admin pode:** cancelar "só esta" ou "todas futuras" da série; alertas podem ser anexados à série inteira.
+- **Fonte:** [Quick Start: Scheduling](https://support.therapynotes.com/hc/en-us/articles/30661279632539-Quick-Start-Scheduling).
+
+**Convergência:** os 3 tratam ocorrência como unidade de billing. Pacote upfront é exceção (Cliniko via account credit). Nenhum gera "fatura única da série".
+
+---
+
+## 5. No-show / cancelamento tardio
+
+### Cliniko
+- **Default:** plataforma não impõe fee; fornece ferramenta — terms of use no online booking + janela mínima de cancelamento (lock). Se paciente pagou full upfront online, ele **não consegue** cancelar pelo link; deposit parcial libera cancelamento.
+- **Admin pode:** configurar minimum notice (várias opções entre "sem restrição" e "vários dias"); redigir política nos terms of use; aplicar fee manualmente via invoice.
+- **Fonte:** [Restrict when a patient can cancel an appointment](https://help.cliniko.com/en/articles/1150562-restrict-when-a-patient-can-cancel-an-appointment), [Let patients cancel their appointments](https://help.cliniko.com/en/articles/1023945-let-patients-cancel-their-appointments).
+
+### SimplePractice
+- **Default:** statuses formais — **No show** e **Late canceled** (ambos billable, ambos geram invoice como qualquer Show quando auto-billing está ativo). Cancelamento dentro da janela permitida vira status não-billable.
+- **Admin pode:** definir janela (24h ou 48h são presets) em Settings; statuses vão pra Client billing summary; appointments late-canceled aparecem em vermelho no calendário.
+- **Fonte:** [Setting up your practice's cancellation policy](https://support.simplepractice.com/hc/en-us/articles/360046771271-Setting-up-your-practice-s-cancellation-policy), [Managing appointment statuses and billing](https://support.simplepractice.com/hc/en-us/articles/360018410872-Managing-appointment-statuses-and-billing).
+
+### TherapyNotes
+- **Default:** **Missed Appointment Note** dedicada — registra ausência e tem checkbox que automaticamente cria billing line item para fee de cancelamento. TherapyPortal mostra warning ao paciente quando ele tenta cancelar fora da janela.
+- **Admin pode:** habilitar/desabilitar criação automática de fee; configurar valor; texto da política aparece no portal.
+- **Fonte:** [Complete a Missed Appointment Note](https://support.therapynotes.com/hc/en-us/articles/30661183276315-Complete-a-Missed-Appointment-Note), [TherapyNotes 4.15 release notes](https://blog.therapynotes.com/version-4-15).
+
+**Convergência:** todos têm conceito de "cobrar pelo no-show". SimplePractice é o mais automatizado (status billable triggera invoice junto com os outros). TherapyNotes é o mais explícito (note dedicada + checkbox). Cliniko é o mais manual.
+
+---
+
+## 6. Reembolso / cancelamento de cobrança emitida
+
+### Cliniko
+- **Default:** invoice criada por engano pode ser **arquivada** (Archive button). **Número fiscal não retorna** — invoice 000001 arquivada não pode ser reemitida com o mesmo número. Reembolso real usa botão **Reverse** que cria credit note com itens negativos; usuário escolhe **Create credit & refund** (devolve dinheiro) ou **Create credit** (vira account credit). Para desfazer um refund, arquiva-se a credit note.
+- **Fonte:** [Archive an invoice](https://help.cliniko.com/en/articles/1359931-archive-an-invoice), [Recording refunds: an overview](https://help.cliniko.com/en/articles/4372587-recording-refunds-an-overview), [Undo a refund](https://help.cliniko.com/en/articles/4521200-undo-a-refund).
+
+### SimplePractice
+- **Default:** invoice paga **não deve ser deletada** (deletar quebra alocação de pagamento). Refund full ou parcial é fluxo separado. Pagamentos cash/check/external podem ser deletados se foram erro; pagamento online com cartão não pode ser deletado, só refunded. Para mudar fee de invoice já emitida, usa **fee adjustment invoice** (novo doc com diff).
+- **Fonte:** [Navigating client payments](https://support.simplepractice.com/hc/en-us/articles/8497757602957-Navigating-client-payments), [Managing unallocated client payments](https://support.simplepractice.com/hc/en-us/articles/42078634883469-Managing-unallocated-client-payments).
+
+### TherapyNotes
+- **Default:** **deletar pagamento ≠ refund** — deletar só remove o registro, não devolve dinheiro. Refund usa botão **Enter Refund** no Patient Accounting do tab Billing. Refund de payer (plano) tem opção dedicada que marca valor negativo automaticamente.
+- **Fonte:** [Edit, Delete and Refund Client Payments](https://support.therapynotes.com/hc/en-us/articles/30661497068443-Edit-Delete-and-Refund-Client-Payments).
+
+**Convergência:** os 3 distinguem "anular registro" de "estornar dinheiro". Os 3 preservam histórico fiscal (Cliniko via número não-reaproveitável + credit note; SimplePractice via fee adjustment; TherapyNotes via refund line item). Padrão "cobrança imutável" do projeto está alinhado com o estado da arte.
+
+---
+
+## Tabela comparativa 3 × 6
+
+| Etapa | Cliniko | SimplePractice | TherapyNotes |
+|---|---|---|---|
+| 1. Compromisso sem paciente | Unavailable block (tipos customizáveis) | Calendar event + OOO block (2 entidades) | Scheduled Event + Unavailable (2 tipos) |
+| 2. Compromisso com paciente | Quick-create paciente (nome basta) | Lead (Inquiry) → cliente formal | Last name basta; demais campos só pra claim |
+| 3. Quando gera cobrança | Manual via botão no appointment | Automático overnight (Daily/Monthly/Manual) condicionado a status billable | Quando nota da sessão é assinada |
+| 4. Recorrência billing | Ocorrência individual ou pacote upfront (account credit) | Série até 100; ocorrência individual; fee adjustment para edit pós-fatura | Ocorrência individual; billing nasce na assinatura de cada nota |
+| 5. No-show / late cancel | Política em terms of use; lock manual | Statuses billable (No show / Late canceled); janela 24h/48h | Missed Appointment Note com checkbox auto-fee |
+| 6. Refund / cancel cobrança | Archive + Reverse → credit note | Não deletar invoice paga; fee adjustment + refund | Enter Refund (delete ≠ refund) |
+
+---
+
+## Consenso de mercado
+
+1. **Bloqueio de tempo é entidade própria**, separada de appointment. Nunca um appointment "sem paciente".
+2. **Cadastro mínimo de paciente** (1 campo) é aceito; campos pesados só ficam obrigatórios na hora de cobrar plano ou ativar portal.
+3. **Recorrência cria ocorrências independentes** para billing; nenhum gera "fatura única da série".
+4. **Edit de uma ocorrência pergunta "esta / todas / futuras"** — padrão consagrado.
+5. **Cobrança nunca é gerada na criação do appointment futuro** — sempre depois (sessão, status, nota, ou trigger manual).
+6. **Cobrança emitida é imutável**; ajustes vêm via documento novo (credit note, fee adjustment invoice, refund line item). Validação direta do invariante do projeto.
+7. **Deletar pagamento ≠ reembolsar dinheiro** — distinção explícita nos 3.
+8. **Janela de cancelamento configurável + política em texto livre** é o mínimo.
+
+## Divergência
+
+- **Quem aciona a cobrança:** Cliniko = humano clica. SimplePractice = job overnight via status. TherapyNotes = assinatura de nota clínica. Três paradigmas distintos.
+- **Lead / prospect:** SimplePractice tem entidade formal (Inquiry). Cliniko e TherapyNotes esperam o paciente já ter perfil mínimo.
+- **No-show fee:** SimplePractice = mais automatizado (status billable). TherapyNotes = mais auditável (note dedicada). Cliniko = mais manual.
+- **Pacote upfront:** Cliniko documenta explicitamente via account credit. SimplePractice/TherapyNotes não têm pacote nativo — cobram ocorrência a ocorrência.
+- **Reaproveitamento de número de invoice arquivada:** Cliniko proíbe (alinhado com fiscal BR via NFS-e). Outros não documentam regra equivalente.
+
+---
+
+## Perguntas-chave pro produto decidir
+
+1. **O que dispara a cobrança no fluxo padrão?**
+   a) Manual (humano clica) — máxima auditabilidade, exige disciplina (Cliniko).
+   b) Job automático com base em status do appointment (SimplePractice) — pouco atrito, dependente de status estar correto.
+   c) Assinatura de nota da sessão (TherapyNotes) — vincula clínica e financeira, atrasa cobrança se nota demora.
+   **Trade-off:** quanto mais automático, menos atrito mas mais risco de cobrança errada; quanto mais manual, mais fricção mas auditoria perfeita.
+
+2. **Devemos ter conceito formal de "lead/contato" antes de prontuário?**
+   a) Sim — entidade Inquiry separada com pipeline (modelo SimplePractice).
+   b) Não — paciente nasce na quick-create do agendamento com nome só (modelo Cliniko/TherapyNotes).
+   **Trade-off:** Inquiry casa com funil comercial mas duplica entidade; quick-create é simples mas dificulta funil de pré-vendas.
+
+3. **Recorrência cobra cada ocorrência ou suporta pacote upfront?**
+   a) Só ocorrência individual (SimplePractice/TherapyNotes).
+   b) Suporta também pacote upfront com saldo (Cliniko via patient case + account credit).
+   **Trade-off:** pacote upfront atende prática que vende "10 sessões antecipado"; ocorrência-a-ocorrência casa direto com NFS-e brasileira (1 nota por serviço).
+
+4. **No-show vira invoice automática ou exige ação manual?**
+   a) Automático — status "No show" / "Late canceled" entram no auto-billing como Show (SimplePractice).
+   b) Semi — note dedicada com checkbox que controla geração (TherapyNotes).
+   c) Manual — admin cria invoice de no-show à mão (Cliniko).
+   **Trade-off:** automático reduz perda mas pode constranger paciente sem revisão; manual exige rotina disciplinada.
+
+5. **Edição de uma ocorrência de série recorrente: o que faz com cobrança já emitida?**
+   a) Bloqueia edição (invariante atual — alinhado com SimplePractice "fee adjustment invoice" preservando original).
+   b) Permite edição com nova cobrança suplementar (delta).
+   c) Permite edição e refaz a cobrança (cancela + recria).
+   **Trade-off:** opção a é a mais defensável fiscalmente (NFS-e já transmitida não pode ser silenciosamente mutada); b atende UX; c é perigoso mas familiar.
+
+6. **Janela de cancelamento: presets ou livre?**
+   a) Presets (24h / 48h) com texto da política livre (SimplePractice).
+   b) Configuração granular por appointment type (Cliniko).
+   c) Cliente final só vê warning, sem lock (TherapyNotes).
+   **Trade-off:** presets cobrem 90% dos casos; granular casa com clínica que tem terapia de grupo + casal + individual com janelas diferentes.
+
+7. **Reembolso preserva o documento fiscal original?**
+   a) Sim, sempre — credit note nova, número fiscal original nunca volta (Cliniko + alinhado com NFS-e brasileira: cancelamento ≠ deletar).
+   b) Sim, mas via fee adjustment que não toca a invoice (SimplePractice).
+   c) Sim, refund é line item separado (TherapyNotes).
+   **Trade-off:** modelo brasileiro de NFS-e exige (a) ou (c); SimplePractice (b) só funciona em mercados sem NF transmitida por API.
+
+8. **Pagamento via PIX (e cartão online) confirma e marca invoice paga automaticamente?**
+   a) Sim — pagamento confirmado dispara appointment confirmado + invoice paga (Cliniko online payment).
+   b) Pagamento é entidade separada que pode ser alocada/desalocada (SimplePractice).
+   **Trade-off:** auto-confirm é UX premium mas exige tolerância a falhas de webhook do PSP; pagamento desalocado é seguro mas exige conciliação.
+
+---
+
+## Implicações imediatas pro projeto
+
+- O invariante "cobrança emitida é imutável" já implementado é consenso de mercado — manter.
+- "Compromisso sem paciente" precisa virar entidade própria (block/event), não um appointment com paciente null. Ver [[recorrencia-agenda]] para integração com expansão de série.
+- Recorrência por ocorrência individual é o caminho seguro (cabe em NFS-e). Pacote upfront fica para fase 2.
+- Disparo de cobrança: avaliar híbrido SimplePractice (status-driven) + TherapyNotes (note-signed), com fallback manual estilo Cliniko.
+- Perguntas 1, 4, 5, 7, 8 são pré-requisito pra fechar o gap atual de billing antes de F1 de fiscal.

Obsidian/Brain/wiki/agenda-compromisso-fluxo.md

@@ -0,0 +1,216 @@
+---
+title: Plano de auditoria fase-a-fase — fluxo de compromisso da agenda
+date: 2026-05-13
+status: em-andamento
+related: [[agenda-billing-pesquisa-mercado]], [[recorrencia-agenda]]
+---
+
+## Contexto
+
+Auditoria do ciclo completo de compromisso da agenda, fase-a-fase, validando cada etapa contra a [[agenda-billing-pesquisa-mercado|pesquisa de mercado]] (Cliniko / SimplePractice / TherapyNotes). Cada fase tem 3 entregas: **auditar o que existe**, **decidir o gap**, **codar**.
+
+## Decisões já tomadas (5 das 8 perguntas)
+
+| # | Decisão |
+|---|---|
+| 1 | Disparo de cobrança: **híbrido configurável** (manual / status-driven / note-signed) |
+| 4 | No-show: **semi-automático via dialog de confirmação** ao mudar status |
+| 5 | Edit de cobrada: **bloqueia** (já implementado) |
+| 7 | Refund: **credit note nova** (alinhado NFS-e) |
+| 8 | Pagamento: **entidade separada** de financial_records |
+
+Pendentes: #2 (lead/Inquiry), #3 (pacote upfront), #6 (janela de cancelamento — provavelmente já resolvido por `min_hours_notice` em `financial_exceptions`).
+
+---
+
+## Plano de 8 fases
+
+Ordem por dependência ("o que destrava o quê") e por estado atual.
+
+### ✅ Fase 1 — Compromisso SEM paciente (bloqueio/feriado/exceção) — **CONCLUÍDA 2026-05-13**
+
+**Auditoria fez:**
+- ✅ `agenda_excecoes` é tabela órfã (0 referências em src/) — apesar de schema, policies, trigger e enums existentes
+- ✅ `agenda_bloqueios` é a entidade canônica usada pelos 3 layouts
+- ✅ `BloqueioDialog` (4 modos: horário/período/dia/feriados) é compartilhado por Melissa Agenda (via `MelissaLayout.vue:2186`), Rail e Clínica
+- ✅ `MelissaBloqueios.vue` tem form inline próprio pra **admin/edit** (caso de uso legítimo distinto do dialog de 4 modos)
+- ✅ Bloqueios não eram renderizados no FullCalendar — apenas impediam criação. UX inconsistente vs pausas/feriados que aparecem como background events
+- ⚠️ Tipos customizáveis de bloqueio: descartado no MVP (sem cliente real)
+- ⚠️ Robustez de `marcarSessoesParaRemarcar`: adiado pra Fase 5 (status change)
+
+**Aplicado:**
+1. Migration `20260513000001_drop_agenda_excecoes.sql` — dropa tabela + 2 enums + trigger; policies caem com CASCADE
+2. `agendaMappers.js`: nova função `buildBloqueioBackgroundEvents(bloqueios, rangeStart, rangeEnd)` — renderiza bloqueios como background events cinza (`#6b728033`), suporta dia-inteiro, com hora, e recorrente semanal
+3. Novo composable `useAgendaBloqueios.js` — load por owner único OU array (multi-owner pra Clínica), `buildEventsForRange` reutilizável
+4. Wire em `useMelissaAgenda` + `MelissaAgenda.vue` — bloqueios concatenados ao `fcEvents`
+5. Wire em `AgendaTerapeutaPage` — bloqueios concatenados ao `calendarEvents`
+6. Wire em `AgendaClinicaPage` — bloqueios consolidados de todos os ownerIds
+7. Refs stale removidas de `database-novo/docs/schema_map.md` e `database-novo/db.config.json`
+
+**Verificação:**
+- ESLint nos arquivos modificados: 0 errors novos (11 pré-existentes em código não-tocado)
+- Vitest `agendaMappers.spec.js`: 40/40 tests passed
+- ⚠️ **Falta rodar a migration no banco local** (pendente de execução manual; arquivo SQL pronto)
+- ⚠️ **Falta validar visualmente** nos 3 layouts (Melissa/Rail/Clínica) — verificar que bloqueios aparecem em cinza após criar pelo BloqueioDialog
+
+---
+
+### 🟢 Fase 2 — Compromisso COM paciente
+**Estado:** dialog refatorado em 11/05 (cards 40px, picker DataTable, 50/50 layout, 3 estados Sessão/Honorários, conceito Pacote, resumo flutuante). Working tree.
+
+**Auditar:**
+- Fluxo de cadastro mínimo de paciente in-line (já existe via `PatientCadastroDialog` quick mode?)
+- Decidir #2 (Inquiry/lead separado ou só quick-create)
+- Modalidade presencial/online consistente
+
+**Gap potencial:**
+- Quick-create exige só nome ou mais campos? (Cliniko: só nome; TherapyNotes: só last name)
+- Decisão #2 (Inquiry/lead) — adiar pra v2 provável
+
+**Codar:** ajustes pequenos, principalmente UX. Provavelmente quase nada novo.
+
+---
+
+### 🟢 Fase 3 — Recorrência
+**Estado:** modelo "1 real + N-1 virtual" + `occurrenceMode` no 2º dialog estabilizado em 12/05. Ver [[recorrencia-agenda]].
+
+**Auditar:**
+- `occurrenceMode` já replicado em Melissa; falta Rail (`AgendaTerapeutaPage` L1630 + L3080) e Clínica (`AgendaClinicaPage` L1119 + L2398)
+- Decisão #3 (pacote upfront via account credit) — adiar provável
+
+**Codar:** replicar `occurrenceMode` em Rail/Clínica. Talvez add de pacote upfront (Cliniko model) numa fase futura.
+
+---
+
+### 🟠 Fase 4 — Cobrança: modo de disparo configurável (DECISÃO #1)
+**Estado:** Fase 1 atual ("Gerar cobrança ao salvar") existe como checkbox em criação avulsa+particular. Não tem setting de modo.
+
+**Auditar:**
+- Onde vive a config? Card novo em `/configuracoes/excecoes-financeiras` ou página irmã `/configuracoes/cobranca-defaults`?
+- Granularidade: por tenant (clínica), por owner (terapeuta), ou ambos com herança?
+
+**Gap:**
+- Tabela/coluna nova pra `charge_trigger_mode` enum (`manual` / `status_driven` / `note_signed`)
+- UI de config
+- Job overnight pra modo `status_driven` (Supabase edge function + cron)
+- Trigger no signature de nota pra `note_signed` (depende de modulo de notas; nao temos)
+- Checkbox atual da agenda passa a fazer sentido **só em modo manual** (ou vira override universal?)
+
+**Codar:**
+1. Migration: setting de modo (tenant_billing_settings ou colunas em agenda_configuracoes)
+2. UI de config
+3. Job pra modo status_driven (avaliar se entra na v1 ou v2)
+4. Refator do checkbox atual pra respeitar o modo
+
+---
+
+### 🟠 Fase 5 — Status change → cobrança com confirm dialog (DECISÃO #4)
+**Estado:** lógica automática roda em `useAgendaFinanceiro.handleStatusChange`. Consulta regra em `financial_exceptions`, cria/ajusta/cancela `financial_record` SEM perguntar.
+
+**Auditar:**
+- Quais status disparam: hoje só `faltou` e `cancelado` (mapping `STATUS_TO_EXCEPTION`)
+- `professional_cancellation` na tabela mas não no mapping
+- Onde `handleStatusChange` é chamado (quais entradas de status change disparam)
+
+**Gap:**
+- Confirm dialog ao mudar status pra `faltou` / `cancelado`: *"Aplicar cobrança de R$X conforme regra? [Sim / Não / Editar valor]"*
+- Adicionar `professional_cancellation` ao mapping (status atual da agenda inclui? checar)
+- Decidir: dialog aparece **sempre** ou só quando `charge_mode !== 'none'`
+
+**Codar:**
+1. Dialog componente novo (`AgendaStatusChargeConfirmDialog.vue`)
+2. Interceptar `handleStatusChange` antes da aplicação automática
+3. Adicionar `professional_cancellation` no mapping
+4. Toast diferenciado pra "aplicado/recusado/editado"
+
+---
+
+### 🟢 Fase 6 — Edit de cobrada (DECISÃO #5 — JÁ IMPLEMENTADO)
+**Estado:** `propagateToSerie` filtra por `financial_records` em status imutável. UI lock em `AgendaEventDialog` via `occFinancialRecord`. Working tree.
+
+**Auditar:** validar contra cenários reais (testar série com 4 sessões, 2 cobradas, 2 abertas; editar template; verificar que cobranças não mudam).
+
+**Codar:** zero (talvez add de aviso UX se faltar clareza).
+
+---
+
+### 🔴 Fase 7 — Pagamento como entidade separada (DECISÃO #8)
+**Estado:** hoje `financial_records.paid_at` marca pagamento (acoplado). Não tem entidade `payments` independente.
+
+**Auditar:**
+- Como financial_records.paid_at é usado hoje (queries de receita, dashboards, conciliação)
+- Webhook PSP existente? (provável que PIX e cartão sejam manuais hoje)
+
+**Gap:**
+- Migration: tabela `payments` (id, amount, method, paid_at, source, allocated_to_record_id NULL-able)
+- Alocação manual de pagamento "solto" a um financial_record
+- Pagamento parcial (1 payment cobre N records ou 1 record recebe N payments?)
+- Repo + composable + UI
+
+**Codar:** fase pesada — provavelmente sub-dividir.
+
+---
+
+### 🔴 Fase 8 — Reembolso / credit note (DECISÃO #7)
+**Estado:** hoje só tem `financial_records.status='cancelled'`. Não preserva original como doc fiscal.
+
+**Auditar:** processo fiscal atual (já emite NFS-e? quando? como cancela?)
+
+**Gap:**
+- Migration: tabela `credit_notes` (id, original_record_id, amount, reason, issued_at)
+- Constraint: credit note tem valor ≤ |original|
+- UI no Financeiro pra "Reembolsar"
+- Integração com NFS-e (pode ser separada)
+
+**Codar:** fase pesada — provavelmente sub-dividir.
+
+---
+
+### 🟣 Fase 9 — Plano Inicial (entrevista + N sessões regulares)
+**Estado:** apenas conceito; nada codado.
+
+**Pedido do user (2026-05-14):** clínica cobra **1 entrevista inicial** (valor X) + **4 sessões regulares** (valor Y cada). É o "plano de entrada" pra novos pacientes. User faz isso manualmente hoje na clínica dele.
+
+**Conceito:**
+- Config nas settings da agenda do tenant:
+  - Toggle "Habilitar plano inicial"
+  - Valor entrevista (R$)
+  - Qtd de sessões regulares (default 4)
+  - Valor por sessão regular (R$)
+  - (Opcional) Texto/descrição que aparece no fluxo
+- Quando user cria 1ª sessão de **paciente novo** (sem histórico):
+  - Sistema oferece: "Aplicar plano inicial? Entrevista R$ X + 4× R$ Y = total R$ Z"
+  - Ao aceitar, materializa 5 sessões com `price` diferenciado: 1ª = X, demais = Y
+  - Pode ser tratado como 1 série recorrente "especial" com 1ª ocorrência destacada
+  - OU como 2 entidades distintas (1 avulsa entrevista + 1 série de 4)
+
+**Decisões pendentes:**
+- Estrutura: série única com 1ª diferenciada OU avulsa + série separada?
+- Onde fica a config: `agenda_configuracoes` (jsonb adicional?) ou tabela nova `intake_plans`?
+- "Paciente novo" = sem sessões anteriores? Ou marcador manual no cadastro?
+- Plano único do tenant ou múltiplos planos (avaliação clínica, avaliação neuropsi, etc)?
+
+**Cabe na Fase 4 (cobrança)?** Não — Fase 4 é só modo de disparo; aqui é estrutura de pacote pré-configurado. Fica como Fase 9 separada.
+
+---
+
+## Ordem sugerida de execução
+
+| Ordem | Fase | Razão |
+|---|---|---|
+| 1ª | **Fase 1** | Curta, validação, define se tem cleanup de tabelas necessário |
+| 2ª | **Fase 5** | Destrava UX urgente (confirm dialog evita cobrar errado) |
+| 3ª | **Fase 4** | Híbrido configurável — destrava racional do checkbox atual |
+| 4ª | **Fase 2** | Quase 100% pronta, validar e finalizar |
+| 5ª | **Fase 3** | Replicar `occurrenceMode` em Rail/Clínica |
+| 6ª | **Fase 6** | Já feito; só testar |
+| 7ª | **Fase 7** | Refator estrutural pesado — entra depois das fases UX |
+| 8ª | **Fase 8** | Depende fiscal NFS-e — pode ir pra v2 |
+| 9ª | **Fase 9** | Plano Inicial (entrevista + 4 sessões) — pedido do user, conceito pronto, codar pós-7 |
+
+## Como cada fase termina
+
+1. Página da fase na wiki é atualizada com o resultado
+2. Commit dedicado com prefixo `agenda(fase-N): ...`
+3. Update no [[index]] da wiki
+4. Entrada no `log.md`

Obsidian/Brain/wiki/index.md

@@ -24,6 +24,9 @@ _(summaries of specific sources you've ingested)_
 
 _(synthesized answers to questions you've asked, filed back as pages)_
 
+- [[agenda-billing-pesquisa-mercado]] — comparativo Cliniko / SimplePractice / TherapyNotes do ciclo compromisso→cobrança (6 etapas), consenso/divergência e 8 perguntas-chave pro produto
+- [[agenda-compromisso-fluxo]] — plano de auditoria fase-a-fase (8 fases) do ciclo de compromisso da agenda; ordem de execução + decisões já tomadas
+
 ---
 
 *This index is maintained by Claude via `/wiki-brain`. Do not edit by hand unless you know what you're doing.*

Obsidian/Brain/wiki/recorrencia-agenda.md

@@ -81,11 +81,66 @@ WHERE patient_id IS NULL
 
 Causa raiz já corrigida em 2026-05-11 (guard contra `rid` null em `onUpdateSeriesEvent`), mas o pattern de query é útil pra catch futuros.
 
+## Invariante de cobrança em séries — "cobrança emitida é imutável"
+
+**Padrão adotado (SimplePractice / TherapyNotes / Cliniko):** `financial_records` em status `pending`/`paid`/`overdue` são **imutáveis pelo dialog da agenda**. Ajustes só via fluxo do Financeiro (cancelar + refaturar). Garante:
+- Trilha fiscal estável.
+- Paciente não vê valor "mágico" mudando.
+- Dashboards de MRR e projeção consistentes.
+
+### Como o sistema honra a invariante
+
+**1. Lock no `occurrenceMode`** (`AgendaEventDialog.vue`):
+- Card "Sessão / Honorários" detecta `occFinancialRecord` via query `financial_records` filtrada por `agenda_evento_id` + status `in ('pending','paid','overdue')`.
+- Se record existe → renderiza apenas `AgendaEventoFinanceiroPanel` + mensagem de lock + Tag de status. Select de billingType e botão "Editar itens" desaparecem.
+- Se record não existe (virtual ou materializado sem cobrança) → edição livre, marca `services_customized=true` ao salvar.
+- Card "Aplicar alterações em" também é ocultado quando há cobrança (mudanças estruturais não se aplicam — usuário só pode mexer em status/horário).
+
+**2. Filtro em `propagateToSerie`** (`useCommitmentServices.js`):
+- Após filtrar eventos elegíveis (recurrence_id + opcionalmente fromDate + opcionalmente services_customized=false), faz 1 query batch em `financial_records` pra coletar `agenda_evento_id` lockados.
+- Remove esses IDs da lista de elegíveis antes de fazer `delete + insert` de `commitment_services`.
+- Resultado: editar template da regra **nunca toca** ocorrências cobradas, mesmo em escopo `todos`.
+
+**3. Aviso fixo no dialog pai** (em `isEdit && hasSerie`):
+- Mensagem inline abaixo do `AgendaEventoFinanceiroPanel`: "Alterações de tipo ou serviços afetam apenas sessões futuras ainda não cobradas. Cobranças já emitidas permanecem inalteradas — para ajustá-las, acesse o Financeiro."
+
+### Opção `todos_sem_excecao` removida da UI
+
+- O nome confundia (sugeria "ignorar cobranças") quando na verdade era "ignorar customização operacional" (`services_customized=true`).
+- Backend mantém o caso pra compat, mas `editScopeOptions` agora só retorna 3 valores: `somente_este`, `este_e_seguintes`, `todos`.
+- Mercado consolidado (SimplePractice etc) não expõe override de customizações — admin que precisa reseta sessão-a-sessão.
+
+### Onde está cada peça
+- `src/features/agenda/composables/useAgendaEventLifecycle.js` — `loadOccFinancialRecord` + `occFinancialRecord` ref
+- `src/features/agenda/components/AgendaEventDialog.vue` — card lock/unlock + aviso pai
+- `src/features/agenda/composables/useCommitmentServices.js:162` — `propagateToSerie` com filtro financial_records
+- `src/features/agenda/composables/useAgendaEventComposer.js:91` — `editScopeOptions` com 3 valores
+- `src/components/agenda/AgendaEventoFinanceiroPanel.vue` — UI do fluxo Financeiro embarcado
+
+## 2º dialog empilhado — edição de ocorrência (occurrenceMode)
+
+Quando o user clica "Editar" em uma pill da lista "Recorrências Aplicadas", abre um **segundo `AgendaEventDialog` empilhado** por cima do principal. Ele compartilha o mesmo componente, mas com a prop `occurrenceMode=true` que muda comportamento:
+
+- **Título:** `Pacote · X de Y Sessões` (computa `occurrenceIndex` via `currentRecurrenceDate` + `serieEvents`) em vez do padrão `Sessão do Pacote · {nome}`.
+- **Layout enxuto:** renderiza apenas 4 cards na ordem: (1) Dados da Recorrência (read-only summary), (2) Status, (3) Horário, (4) Aplicar alterações em. Tudo o resto (paciente-hero, fields-grid, serie-panel, sessão/honorários, frequência, extras, resumo mobile) fica oculto via `v-if="!occurrenceMode"`.
+- **Escopo `Aplicar alterações em`:** migrou do `composer-right` do dialog pai pra dentro do dialog de ocorrência. O pai não mostra mais esse card — pra mudar escopo, o user obrigatoriamente vai pela pill.
+- **Horário editável:** botão "Ajustar horário" não fica `:disabled="isEdit"` no occurrenceMode (no pai sim — data/horário do pacote inteiro é imutável após criação).
+
+Stack relevante:
+- `MelissaLayout.vue:2160` monta o 2º dialog passando `:occurrenceMode="true"` + `eventRow={ ...row, recurrence_date, _is_virtual }` via refs `agendaOccDialog*` (destructurados de `useMelissaAgenda` no setup — refs aninhados não auto-unwrap no template).
+- `useMelissaAgenda.onEditSeriesOccurrence` popula `occDialogEventRow` + abre `occDialogOpen=true`. Substituiu o pattern antigo de mutar `dialogEventRow` in-place (que trocava silenciosamente os dados do dialog atual).
+- `useAgendaEventLifecycle.onPillEditClick` emite `editSeriesOccurrence({ id, recurrence_date, inicio_em, fim_em, is_virtual })`.
+
+**Pendente replicar:** Rail (`AgendaTerapeutaPage`) e Clínica (`AgendaClinicaPage`) ainda têm só o dialog principal — o 2º só existe no Melissa por enquanto.
+
 ## Referências de código
 
 - `src/features/agenda/composables/useRecurrence.js` — `loadAndExpand`, `expandRules`, `mergeWithStoredSessions`, `buildOccurrence`
-- `src/layout/melissa/composables/useMelissaAgenda.js:809` — `onUpdateSeriesEvent`
+- `src/layout/melissa/composables/useMelissaAgenda.js:817` — `onEditSeriesOccurrence`
+- `src/layout/melissa/composables/useMelissaAgenda.js:837` — `onUpdateSeriesEvent`
 - `src/features/agenda/composables/useAgendaEventActions.js:65` — watcher do form.status
 - `src/features/patients/composables/usePatientSessions.js:189` — `updateStatus` com materialização
+- `src/features/agenda/components/AgendaEventDialog.vue` — props `occurrenceMode`, computeds `occurrenceIndex` / `occurrenceTotalSessions` / `headerMainLabel`
 - `src/layout/melissa/MelissaLayout.vue:655` — `updateEventoStatus` do `MelissaEventoPanel`
+- `src/layout/melissa/MelissaLayout.vue:2160` — 2º AgendaEventDialog empilhado
 - `src/layout/melissa/MelissaAgenda.vue:244` — `VIEW_MAP.lista = 'listAll'`

blueprints/composable-blueprint.md

@@ -0,0 +1,514 @@
+# Composable Blueprint
+
+> **Stack:** Vue 3 Composition API + Pinia (para state global) + Supabase via repository
+> **Canônicos:** `src/features/agenda/composables/useAgendaEvents.js`, `useAgendaClinicEvents.js`, `useAgendaSettings.js`
+> **Aplicável:** todo composable que orquestra estado reativo sobre uma repository
+
+---
+
+## 1. Princípio
+
+Composable é **wrapper fino** sobre a repository. Responsabilidade:
+- Manter **estado reativo** (data + loading + error)
+- Chamar a repository (delegação 1:1)
+- (Opcional) Cachear com stale-while-revalidate
+- (Opcional) Compor outros composables
+
+**Não faz:**
+- Lógica de banco direta (vai no repository)
+- Lógica de UI (vai no componente)
+- Manipulação de DOM
+- I/O direto fora do repository
+
+> Regra de ouro: **se o composable tem `from('...')` do Supabase, ele virou repository disfarçado — refatorar.**
+
+---
+
+## 2. Estrutura de arquivos
+
+```
+src/features/<modulo>/composables/
+├── use<Entity>.js              # CRUD básico (thin wrapper)
+├── use<Entity>Clinic.js        # variant clinic-scoped (se aplicável)
+├── use<Entity>Settings.js      # config/preferences (com cache opt-in)
+├── use<Entity>Lifecycle.js     # orquestrador de estados (se domain complexo)
+└── <entity>Helpers.js          # funções puras auxiliares (não-composable)
+```
+
+**Convenção de nome:** sempre `use<Entity>...`. Funções helpers de domínio NÃO usam prefixo `use` — não são composables.
+
+---
+
+## 3. State shape canônico
+
+Todo composable expõe **no mínimo** este shape:
+
+```js
+const rows = ref([]);       // ou single ref dependendo do domínio
+const loading = ref(false); // boolean
+const error = ref('');      // string vazia, não null — facilita v-if
+```
+
+**Decisões importantes:**
+
+| Refs | Tipo | Inicial | Por quê |
+|---|---|---|---|
+| `loading` | `boolean` | `false` | Padrão V3 — UI binda `:disabled="loading"` direto |
+| `error` | `string` | `''` (vazio) | `v-if="error"` é falsy-friendly; sem null check |
+| `rows`/data | `Array` ou objeto | `[]` ou `null` | Reset pra `[]` em erro de load — UI fica previsível |
+
+**Anti-pattern:** misturar `error = ref(null)` num composable e `error = ref('')` em outro. Canonize `''` no projeto inteiro.
+
+---
+
+## 4. Tipos de composable (3 patterns)
+
+### Tipo A — Thin wrapper (default) · referência: `useAgendaClinicEvents.js`
+
+CRUD direto, sem cache, com loading/error em TODA operação:
+
+```js
+import { ref } from 'vue';
+import { listX, createX, updateX, deleteX } from '@/features/<modulo>/services/<feature>Repository';
+
+export function useX() {
+    const rows = ref([]);
+    const loading = ref(false);
+    const error = ref('');
+
+    async function loadRange({ startISO, endISO, ...scope } = {}) {
+        loading.value = true;
+        error.value = '';
+        try {
+            rows.value = await listX({ startISO, endISO, ...scope });
+        } catch (e) {
+            error.value = e?.message || 'Falha ao carregar.';
+            rows.value = [];
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function create(payload, opts = {}) {
+        loading.value = true;
+        error.value = '';
+        try {
+            return await createX(payload, opts);
+        } catch (e) {
+            error.value = e?.message || 'Falha ao criar.';
+            throw e;  // ← re-throw: composable repassa o erro pro componente decidir
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function update(id, patch, opts = {}) { /* idem */ }
+    async function remove(id, opts = {}) { /* idem */ }
+
+    return { rows, loading, error, loadRange, create, update, remove };
+}
+```
+
+**Por que re-throw nas mutações?** Componente precisa saber se o `await` falhou pra:
+- Mostrar toast
+- Não fechar modal
+- Não navegar
+- Manter form com dados
+
+`error.value` é só pra estado reativo persistente. Mutação síncrona precisa de throw também.
+
+### Tipo B — Thin wrapper "extra-leve" · referência: `useAgendaEvents.js`
+
+Variant aceitável quando mutações **não precisam de loading**:
+
+```js
+async function create(payload) {
+    return createX(payload);  // ← repassa erro nativamente; componente try/catch
+}
+```
+
+**Quando usar:** UIs onde criar/editar tem feedback próprio (skeleton no item criado, optimistic UI, etc.). Default é o Tipo A.
+
+### Tipo C — Cache com stale-while-revalidate · referência: `useAgendaSettings.js`
+
+Para dados raros/pesados (settings, preferences, listas estáveis):
+
+```js
+import { ref } from 'vue';
+import { getX } from '../services/<feature>Repository';
+import { useMelissaCacheStore, MELISSA_CACHE_TTL } from '@/stores/melissaCacheStore';
+
+export function useX(opts = {}) {
+    const useCache = !!opts.cache;
+    const cache = useCache ? useMelissaCacheStore() : null;
+
+    const data = ref(null);
+    const loading = ref(false);
+    const error = ref('');
+
+    async function _doFetch() {
+        const result = await getX();
+        data.value = result;
+        if (cache) {
+            const key = result?.owner_id || 'anon';
+            cache.set('xKey', result, key);
+        }
+        return result;
+    }
+
+    async function load() {
+        if (cache) {
+            const cached = cache.get('xKey', undefined, MELISSA_CACHE_TTL.xKey);
+            if (cached) {
+                data.value = cached;
+                _doFetch().catch((e) => console.warn('[useX] revalidate', e));
+                return;
+            }
+        }
+
+        loading.value = true;
+        error.value = '';
+        try {
+            await _doFetch();
+        } catch (e) {
+            error.value = e?.message || 'Falha ao carregar.';
+            data.value = null;
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    return { data, loading, error, load };
+}
+```
+
+**Decisões do Tipo C:**
+
+- **`opts.cache` default `false`** — páginas de configuração que editam settings esperam mudança imediata após salvar, então cache opt-in.
+- **Cache key inclui scope** (`owner_id`/`tenant_id`) — invalida automaticamente em troca de usuário/tenant.
+- **TTL constants no store** — `MELISSA_CACHE_TTL.<feature>` (não hardcoded no composable).
+- **Stale-while-revalidate:** retorna cached SE existe + dispara fetch em background (sem await).
+- **Revalidate fail é warn**, não error — UI já tem dados válidos do cache.
+
+---
+
+## 5. Convenções de nomenclatura
+
+### Funções
+
+| Operação | Nome canônico | Variantes aceitas |
+|---|---|---|
+| Listar com filtro | `loadRange` / `loadMy<X>` | `load<Scope><Range>` |
+| Criar | `create` | `create<Scope>` (se houver ambiguidade) |
+| Atualizar | `update` | `update<Scope>` |
+| Remover | `remove` | `remove<Scope>` (nunca `delete` — palavra reservada) |
+| Recarregar | `refresh` | `reload` |
+| Limpar estado | `reset` / `clear` | — |
+
+**Scope sufixo** quando o composable serve múltiplos contextos: `loadMyRange` (terapeuta) vs `loadClinicRange` (admin).
+
+### State refs
+
+- `rows` — coleção principal (array)
+- `record` — single (quando faz sentido)
+- `data` — genérico (settings, config)
+- `loading` — boolean único; se há múltiplos `loading` (load vs save), nomear: `loadingList`, `saving`
+- `error` — string única; mesmo princípio: `loadError`, `saveError` se precisar
+
+---
+
+## 6. Anatomia padrão de uma operação `load*`
+
+```js
+async function loadXxx(args) {
+    // 1. Validação leve (early return, não throw)
+    if (!args?.required) return;
+
+    // 2. State flag
+    loading.value = true;
+    error.value = '';
+
+    try {
+        // 3. Delegate pra repository (UMA chamada — se múltiplas, Promise.all)
+        const result = await listX(args);
+
+        // 4. Mutate state
+        rows.value = result;
+    } catch (e) {
+        // 5. Erro humano + reset de data (UI fica previsível)
+        error.value = e?.message || 'Mensagem PT-BR genérica.';
+        rows.value = [];
+    } finally {
+        // 6. Sempre limpar loading
+        loading.value = false;
+    }
+}
+```
+
+**Por que early-return em vez de throw na validação?** Composable é wrapper — chamadas inválidas (ex: `ownerId` ainda não chegou no mount) não devem quebrar UI. Throw fica pra repository.
+
+---
+
+## 7. Múltiplos fetches paralelos
+
+Quando uma operação precisa de N queries:
+
+```js
+async function _doFetch() {
+    const [cfg, rules, profile] = await Promise.all([
+        getMyAgendaSettings(),
+        getMyWorkSchedule(),
+        getMyProfile()
+    ]);
+    settings.value = cfg;
+    workRules.value = rules;
+    profile.value = profile;
+}
+```
+
+**Regras:**
+- `Promise.all` (não `Promise.allSettled`) — falha de qualquer query falha a operação inteira
+- Exception: quando uma query é opcional/best-effort → `Promise.allSettled` + processa por result
+- **Nunca** sequenciar fetches independentes (await + await + await)
+
+---
+
+## 8. Composição de composables
+
+Composable pode usar outros composables, mas:
+
+```js
+// ✅ certo — composição estrutural
+export function useAgendaEventLifecycle() {
+    const events = useAgendaEvents();
+    const billing = useAgendaFinanceiro();
+    const settings = useAgendaSettings({ cache: true });
+
+    async function realizar(eventId) {
+        // orquestra os 3
+    }
+
+    return { ...events, realizar, ... };
+}
+
+// ❌ errado — não compor pra economizar 1 linha
+export function useOnlyToWrapList() {
+    const { rows, loadMyRange } = useAgendaEvents();
+    return { rows, loadMyRange };  // ← isso é um re-export inútil
+}
+```
+
+**Regra:** compõe quando há **orquestração**. Se é só forward, importa direto.
+
+---
+
+## 9. Anti-patterns (NÃO fazer)
+
+### ❌ Composable que tem `supabase.from('...')` direto
+
+```js
+// ❌ — violação de camadas
+export function useFoo() {
+    async function load() {
+        const { data } = await supabase.from('foo').select('*');
+    }
+}
+```
+
+✅ Move pra repository, composable só delega.
+
+### ❌ `error` ora `null`, ora `''`, ora `Error`
+
+Canonize `string` (default `''`). Errors do JS dão `e?.message || 'fallback PT-BR'`.
+
+### ❌ Não resetar `rows` em erro de load
+
+```js
+// ❌
+async function loadRange() {
+    try { rows.value = await listX(); } catch (e) { error.value = e.message; }
+    // rows.value mantém dados antigos = UI mostra coisa stale + alerta de erro
+}
+```
+
+✅ Reset `rows.value = []` no catch — UI fica determinística.
+
+### ❌ Não re-throw mutações
+
+```js
+// ❌
+async function create(payload) {
+    try { return await createX(payload); }
+    catch (e) { error.value = e.message; }
+    // componente faz `await create()` e nunca sabe que falhou
+}
+```
+
+✅ Re-throw após setar `error.value`.
+
+### ❌ `Promise.all` quando uma falha é aceitável
+
+Quando uma das queries pode falhar sem invalidar as outras, usar `Promise.allSettled`. Comum em listings que enriquece com lookups opcionais.
+
+### ❌ State global em variável módulo
+
+```js
+// ❌ — vaza entre componentes que compartilham o composable
+const rows = ref([]);
+export function useFoo() {
+    return { rows };
+}
+```
+
+✅ State sempre DENTRO da `function useFoo()`. Se precisar global, use Pinia store.
+
+### ❌ Composable que faz `watch` no próprio state pra "side effect"
+
+```js
+// ❌
+const rows = ref([]);
+watch(rows, () => { /* save algo */ });
+```
+
+✅ Mover `watch` pro componente — composable não decide quando salvar.
+
+**Exceção:** watch pra sincronizar com prop externa do composable (`watchEffect(() => loadRange(props.range))`) é OK.
+
+### ❌ Composable retornando objeto enorme
+
+Se o `return` tem 20+ chaves, o composable está fazendo coisa demais. Quebrar em N composables menores ou extrair Pinia store.
+
+---
+
+## 10. Cache store (Tipo C complementar)
+
+Quando criar um composable Tipo C, garantir que existe entry em:
+
+- `src/stores/melissaCacheStore.js` — `MELISSA_CACHE_TTL.<feature>` constante (TTL em ms)
+- `.get(key, scope, ttl)` retorna valor ou null
+- `.set(key, value, scope)` salva com timestamp
+- Invalidação manual: `.invalidate('<feature>')`
+
+**TTL guidelines:**
+
+| Tipo de dado | TTL sugerido |
+|---|---|
+| Settings/preferences | 5 min |
+| Listas estáveis (specialties, plans) | 30 min |
+| Catálogo (services, pricing) | 10 min |
+| Multi-tenant lookups | 5 min |
+| Anything user-edited | NÃO cachear (Tipo A) |
+
+---
+
+## 11. Checklist de auditoria por módulo
+
+Quando rodar `/audit-module <nome>`, validar cada composable:
+
+- [ ] Não tem `supabase.from(...)` direto — só importa da repository
+- [ ] State shape: `rows`/`data`, `loading: boolean`, `error: string`
+- [ ] `error` é string, default `''`
+- [ ] Reset de data em erro de load (`rows.value = []`)
+- [ ] Mutações re-throw após setar error.value
+- [ ] Nomenclatura: `loadRange`/`load<Scope>`, `create`, `update`, `remove`
+- [ ] `remove` não `delete` (palavra reservada)
+- [ ] Validação leve usa early-return (não throw)
+- [ ] Múltiplos fetches em `Promise.all` (não sequencial)
+- [ ] State DENTRO da `function use*()` (não em variável de módulo)
+- [ ] Sem `watch` em própria state pra side effect (mover pro componente)
+- [ ] Helpers de domínio em arquivo separado sem prefixo `use`
+- [ ] Se cacheia (Tipo C): `opts.cache` opt-in, default `false`; TTL em `MELISSA_CACHE_TTL`; cache key inclui scope
+- [ ] Return statement com chaves explícitas (não `return { ...state, ...actions }` opaco)
+- [ ] Return ≤ 15 chaves (>15 = composable fazendo coisa demais)
+
+Divergências viram items em `dev_auditoria_items` com:
+- `categoria`: `padronizacao`
+- `tag`: `padronizacao:<modulo>`
+- `severidade`: alta se camada quebrada (composable com `from()`); média se viola convenção (error null vs ''); baixa se cosmético (nome de função)
+
+---
+
+## 12. Exemplo completo (template)
+
+```js
+/*
+| Arquivo: src/features/patients/composables/usePatients.js
+*/
+import { ref } from 'vue';
+import {
+    listPatients,
+    createPatient,
+    updatePatient,
+    deletePatient
+} from '@/features/patients/services/patientsRepository';
+
+export function usePatients() {
+    const rows = ref([]);
+    const loading = ref(false);
+    const error = ref('');
+
+    async function loadRange({ search, status, tenantId } = {}) {
+        loading.value = true;
+        error.value = '';
+        try {
+            rows.value = await listPatients({ search, status, tenantId });
+        } catch (e) {
+            error.value = e?.message || 'Falha ao carregar pacientes.';
+            rows.value = [];
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function create(payload) {
+        loading.value = true;
+        error.value = '';
+        try {
+            return await createPatient(payload);
+        } catch (e) {
+            error.value = e?.message || 'Falha ao criar paciente.';
+            throw e;
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function update(id, patch) {
+        loading.value = true;
+        error.value = '';
+        try {
+            return await updatePatient(id, patch);
+        } catch (e) {
+            error.value = e?.message || 'Falha ao atualizar paciente.';
+            throw e;
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function remove(id) {
+        loading.value = true;
+        error.value = '';
+        try {
+            await deletePatient(id);
+        } catch (e) {
+            error.value = e?.message || 'Falha ao remover paciente.';
+            throw e;
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    return { rows, loading, error, loadRange, create, update, remove };
+}
+```
+
+---
+
+## 13. Referências
+
+- Canônicos: `src/features/agenda/composables/useAgendaEvents.js`, `useAgendaClinicEvents.js`, `useAgendaSettings.js`
+- Repository pareado: `blueprints/repository-blueprint.md`
+- Cache store: `src/stores/melissaCacheStore.js`
+- Tracker: `dev_auditoria_items` com tag `padronizacao:<modulo>`
+- Estratégia: `development/02-auditoria/PADRONIZACAO.md`

blueprints/quick-create-overlay-blueprint.md

@@ -0,0 +1,431 @@
+# Quick-Create Overlay Blueprint
+
+> **Status:** Pattern **universal**. Promovido de agenda-only em 2026-05-20 após audit baseline (`development/02-auditoria/AUDIT_BASELINE.md`) identificar 3 candidates já em produção fora da agenda.
+> **Stack:** Vue 3 + PrimeVue Dialog
+> **Canônicos:**
+> - `src/features/agenda/components/ServiceQuickCreateDialog.vue` (referência completa)
+> - `src/features/agenda/components/InsurancePlanQuickCreateDialog.vue`
+> - `src/features/agenda/components/InsurancePlanServiceQuickCreateDialog.vue`
+> **Legacy a refatorar (supabase direto, sem repository):**
+> - `src/components/CadastroRapidoMedico.vue` → migrar pra `features/medicos/components/` (módulo 1 da Fase 1)
+> - `src/components/CadastroRapidoConvenio.vue` → migrar pra `features/insurance/components/`
+> - `src/components/ComponentCadastroRapido.vue` → migrar pra path apropriado conforme dono da entidade
+
+---
+
+## 1. Princípio
+
+**Problema:** usuário está num fluxo (ex: agendar uma sessão) e precisa de uma entidade dependente que ainda não existe (serviço, convênio, plano). Navegar pra outra página significa **perder o contexto** do form em progresso.
+
+**Solução:** mini-dialog **por cima** do dialog/fluxo atual, com **campos mínimos** pra criar a entidade, e ao salvar **pré-seleciona** ela no select que disparou o quick-create.
+
+**Regra absoluta:** criar dependência faltante em **qualquer fluxo** deve **abrir overlay POR CIMA, nunca navegar pra fora**. Aplicável em todo o sistema desde a promoção do blueprint (2026-05-20). Origem do pattern: agenda (memória `feedback_agenda_inline_quick_create`, agora generalizada).
+
+---
+
+## 2. Quando aplicar (vs alternativas)
+
+| Situação | Solução |
+|---|---|
+| Fluxo crítico travado por dependência faltante (form em progresso) | **Quick-create overlay** ✅ |
+| Cadastro completo, com todos os campos | Página dedicada `/entity/new` ou Dialog full |
+| Apenas selecionar item existente | Select com busca; sem botão "+" |
+| Onboarding ou setup wizard | Não — fluxo é a página inteira, não um overlay |
+
+**Anti-uso:** quick-create NÃO é "shortcut pra criar do menu lateral". É **fallback contextual** quando o form atual depende de algo que falta. O parent **precisa estar pronto pra receber o evento `created`** e usar o ID.
+
+---
+
+## 3. Estrutura do componente `<Entity>QuickCreateDialog.vue`
+
+```vue
+<script setup>
+import { ref, watch } from 'vue';
+import { useToast } from 'primevue/usetoast';
+// CANÔNICO: importar da repository do feature dono da entidade.
+// LEGACY: 3 componentes em src/components/ usam supabase direto — refatorar quando módulo dono for tocado na Fase 1.
+import { createX } from '@/features/<feature>/services/<feature>Repository';
+
+const props = defineProps({
+    modelValue: { type: Boolean, default: false },
+    ownerId: { type: String, default: '' },
+    initialName: { type: String, default: '' }  // pré-preenche do search atual do select
+});
+const emit = defineEmits(['update:modelValue', 'created']);
+
+const toast = useToast();
+const tenantStore = useTenantStore();
+
+const visible = ref(props.modelValue);
+watch(() => props.modelValue, (v) => { visible.value = v; });
+watch(visible, (v) => emit('update:modelValue', v));
+
+const form = ref({ /* só campos MÍNIMOS obrigatórios + 1-2 opcionais úteis */ });
+const saving = ref(false);
+
+// Resetar form toda vez que abre
+watch(() => props.modelValue, (v) => {
+    if (v) form.value = { /* defaults + initialName */ };
+});
+
+const canSave = () => /* validação leve */;
+
+async function onSave() {
+    if (!canSave()) return;
+
+    saving.value = true;
+    try {
+        // Sanitize (trim + maxlength slice + nullif vazio) ANTES de chamar repository
+        const payload = {
+            name: form.value.name.trim().slice(0, 120),
+            // ...resto sanitizado
+        };
+
+        // Repository injeta owner_id (uid logado) + tenant_id (store) + faz uniqueness check
+        // e throw em erro. Quick-create só decide o que mostrar ao usuário.
+        const data = await createX(payload);
+
+        toast.add({ severity: 'success', summary: '<Entity> criado', life: 2200 });
+        emit('created', data);  // ← parent usa data.id pra pré-selecionar
+        visible.value = false;
+    } catch (e) {
+        // Repository pode throw com message conhecido (ex: "Nome em uso") — mostra como warn ou error
+        const isDup = /em uso|já existe|duplicate/i.test(e?.message || '');
+        toast.add({
+            severity: isDup ? 'warn' : 'error',
+            summary: isDup ? 'Nome em uso' : 'Falha ao criar',
+            detail: e?.message || 'Erro inesperado',
+            life: 4000
+        });
+    } finally {
+        saving.value = false;
+    }
+}
+</script>
+
+<!--
+LEGACY-NOTE (2026-05-20): os 3 quick-creates em src/components/ (CadastroRapidoMedico,
+CadastroRapidoConvenio, ComponentCadastroRapido) ainda usam supabase direto. Padrão acima
+é o CANÔNICO pós-promoção. Refator vai acontecer no módulo correspondente da Fase 1.
+-->
+
+<template>
+    <Dialog
+        v-model:visible="visible"
+        modal
+        :draggable="false"
+        :closable="!saving"
+        header="Novo <entity>"
+        class="w-[94vw] max-w-md"
+    >
+        <!-- Campos mínimos: 3-5 inputs, nada mais -->
+        <div class="flex flex-col gap-3 pt-1"> ... </div>
+
+        <template #footer>
+            <Button label="Cancelar" text :disabled="saving" @click="visible = false" />
+            <Button label="Salvar" :loading="saving" :disabled="!canSave()" @click="onSave" />
+        </template>
+    </Dialog>
+</template>
+```
+
+---
+
+## 4. Contrato canônico de props/emits
+
+### Props (sempre)
+
+| Prop | Tipo | Default | Função |
+|---|---|---|---|
+| `modelValue` | `Boolean` | `false` | Visibilidade do dialog. Two-way via `v-model`. |
+| `ownerId` | `String` | `''` | Owner_id (terapeuta). Default: usuário logado. |
+| `initialName` | `String` | `''` | Pré-preenche o campo nome com o search atual do select (UX win). |
+
+### Props (opcionais por entidade)
+
+- `parentId` (`String`) — quando a entidade tem hierarquia (ex: `plan_id` em `plan_service`)
+- `defaultDurationMin` (`Number`) — quando faz sentido herdar valor do contexto
+- Outras herdadas do contexto, **nunca** mais que 3 props extras (senão vira form pesado, não quick-create)
+
+### Emits
+
+| Evento | Payload | Quando |
+|---|---|---|
+| `update:modelValue` | `Boolean` | `v-model` two-way |
+| `created` | `Object` (row inserida completa) | Após insert bem-sucedido |
+
+**Nunca emitir** `cancelled`, `closed`, `error` — parent não precisa saber dessas distinções; `update:modelValue=false` cobre.
+
+---
+
+## 5. Integração no parent
+
+### Slot do botão `+` ao lado do select
+
+```vue
+<div class="flex gap-2 items-center">
+    <Select v-model="selectedServiceId" :options="services" optionLabel="name" optionValue="id" class="flex-1" />
+    <Button
+        icon="pi pi-plus"
+        v-tooltip.top="'Cadastrar novo serviço'"
+        severity="secondary"
+        size="small"
+        @click="openServiceQuickCreate"
+    />
+</div>
+```
+
+### Lock do dialog parent
+
+Parent **precisa** travar seu próprio `dismissableMask` e `closeOnEscape` enquanto qualquer quick-create child está aberto, senão clicar fora fecha tudo:
+
+```vue
+<Dialog
+    v-model:visible="parentVisible"
+    :dismissableMask="!anyChildDialogOpen"
+    :closeOnEscape="!anyChildDialogOpen"
+    ...
+>
+```
+
+```js
+const serviceQuickCreateOpen = ref(false);
+const insuranceQuickCreateOpen = ref(false);
+const anyChildDialogOpen = computed(() =>
+    serviceQuickCreateOpen.value || insuranceQuickCreateOpen.value
+);
+```
+
+### Renderização dos quick-creates DENTRO do parent
+
+```vue
+<!-- DENTRO do template do parent dialog, antes do </Dialog> -->
+<ServiceQuickCreateDialog
+    v-model="serviceQuickCreateOpen"
+    :owner-id="ownerId"
+    :initial-name="serviceSearchText"
+    @created="onServiceCreated"
+/>
+```
+
+### Handler `on<Entity>Created`
+
+```js
+function onServiceCreated(row) {
+    // 1. Inserir na lista local (sem re-fetch)
+    services.value = [row, ...services.value];
+    // 2. Pré-selecionar no select
+    selectedServiceId.value = row.id;
+    // 3. (Opcional) Focar o próximo campo
+    nextTick(() => priceInputRef.value?.focus());
+}
+```
+
+### Handler `openXQuickCreate`
+
+```js
+function openServiceQuickCreate() {
+    serviceSearchText.value = currentSearchInSelect.value;  // capture pra initialName
+    serviceQuickCreateOpen.value = true;
+}
+```
+
+---
+
+## 6. Convenções de UX
+
+### Campos mínimos absolutos
+
+Quick-create **não é cadastro completo**. Inclui só:
+- 1 campo obrigatório principal (nome)
+- 1-2 campos obrigatórios secundários (preço, duração)
+- 1 campo opcional (descrição)
+
+Resto (categorias, tags, configurações avançadas) edita depois em `/entity/:id`.
+
+### Maxlength visível
+
+```vue
+<InputText v-model="form.name" maxlength="120" />
+```
+
+Slice no save: `.trim().slice(0, 120)` — defesa em profundidade.
+
+### Botão "+" sempre `size="small"` `severity="secondary"`
+
+Discrição visual — não compete com CTA do dialog parent.
+
+### Toast em vez de inline error
+
+Mini-dialog não tem espaço pra banner de erro. Toast no canto superior direito (padrão PrimeVue) basta.
+
+### `autofocus` no primeiro input
+
+```vue
+<InputText autofocus v-model="form.name" />
+```
+
+Usuário já está em modo "digitar" — pular o clique no input.
+
+### `:loading="saving"` no botão Salvar
+
+Spinner + disabled simultâneo. PrimeVue já dá o efeito visual.
+
+---
+
+## 7. Anti-patterns (NÃO fazer)
+
+### ❌ Navegar pra rota nova no botão "+"
+
+```js
+// ❌ — destrói o form em progresso
+function openServiceQuickCreate() {
+    router.push('/saas/services/new');
+}
+```
+
+✅ Abre o overlay.
+
+### ❌ Quick-create que pede 10 campos
+
+Se a entidade exige cadastro complexo (campos condicionais, validações cruzadas, upload de arquivo), **não cabe num quick-create**. Use página dedicada e aceite que o usuário perde contexto. Ou crie um wizard.
+
+### ❌ Sem `dups check` antes do insert
+
+```js
+// ❌ — usuário clica 2x, cria duplicata silenciosa
+await supabase.from('services').insert(payload).select().single();
+```
+
+✅ `ilike` por `name` antes; aborta com warn toast.
+
+### ❌ Não emitir o objeto completo no `created`
+
+```js
+// ❌
+emit('created', { id: data.id });  // parent precisa de mais que id
+
+// ❌ pior ainda
+emit('created');  // parent não sabe o que foi criado
+```
+
+✅ `emit('created', data)` — row completa do banco.
+
+### ❌ Não capturar `initialName` do search atual
+
+Quando usuário digita "Sessão 50min" no select e clica "+", o `initialName=` deve já vir preenchido. Senão usuário re-digita.
+
+### ❌ Parent sem `anyChildDialogOpen` no lock
+
+Sem o lock, clicar fora do quick-create child fecha o parent inteiro. Bug clássico.
+
+### ❌ Re-fetch da lista após `created`
+
+```js
+// ❌ — round-trip desnecessário; o evento já trouxe o row
+async function onServiceCreated() {
+    await loadServices();
+}
+```
+
+✅ Inserir o `row` recebido direto na lista local; só re-fetch se houver lógica de ordenação complexa.
+
+### ❌ Múltiplos quick-creates abertos ao mesmo tempo
+
+Permitir abrir um quick-create de plano de saúde enquanto outro de serviço está aberto = stack visual confuso. Force fechar o atual antes de abrir o próximo, OU mantenha o lock no `anyChildDialogOpen` que cobre.
+
+---
+
+## 8. Sanitização (memória `feedback_sanitizacao`)
+
+Toda entrada de quick-create:
+
+```js
+const name = form.value.name?.trim().slice(0, 120) || null;
+const description = form.value.description?.trim().slice(0, 500) || null;
+const price = form.value.price != null ? Number(form.value.price) : null;
+```
+
+Padrão: `trim()` → `slice(maxlength)` → `nullif vazio` → cast tipo.
+
+Pro upload (não comum em quick-create, mas se houver): mime allowlist + size check antes de submitter.
+
+---
+
+## 9. Promotion History & Path Convention
+
+### Histórico
+
+- **2026-05-04** — Pattern nasceu em `features/agenda/` com 3 quick-creates (Service, InsurancePlan, InsurancePlanService). Documentado como **agenda-only** com promotion criteria explícito.
+- **2026-05-20** — Audit baseline identificou 3 candidates já em produção fora da agenda: `CadastroRapidoMedico.vue`, `CadastroRapidoConvenio.vue`, `ComponentCadastroRapido.vue` (todos `supabase` direto, em `src/components/`). Promotion criteria atingida 3×. **Blueprint promovido pra universal.**
+
+### Path convention pós-promoção
+
+| Caso | Path | Exemplo |
+|---|---|---|
+| Entidade pertence a 1 feature claro | `src/features/<feature>/components/<Entity>QuickCreateDialog.vue` | `features/medicos/components/MedicoQuickCreateDialog.vue` |
+| Entidade é cross-feature (raro) | `src/components/quick-create/<Entity>QuickCreateDialog.vue` | (nenhum hoje) |
+
+**Anti-pattern:** quick-create morando em `src/components/` raiz sem subpasta — perde discoverability e mistura com componentes utilitários.
+
+### Plano de migração dos 3 legacy
+
+Cada refator acontece **quando o módulo dono for tocado na Fase 1**:
+
+| Componente atual | Path destino | Quando | Fix obrigatório |
+|---|---|---|---|
+| `src/components/CadastroRapidoMedico.vue` | `src/features/medicos/components/MedicoQuickCreateDialog.vue` | Módulo 1 (Home/Components) — pode criar `features/medicos/` se ainda não existe | Migrar pra repository; usar `_tenantGuards` |
+| `src/components/CadastroRapidoConvenio.vue` | `src/features/insurance/components/InsurancePlanQuickCreateDialog.vue` (consolidar com o existente na agenda?) | Módulo 1 | Idem; **verificar se duplica `features/agenda/components/InsurancePlanQuickCreateDialog.vue`** |
+| `src/components/ComponentCadastroRapido.vue` | depende do que cria | Módulo 1 | Idem |
+
+### Boilerplate DRY (futuro, não-prioritário)
+
+Quando houver 5+ quick-creates seguindo o pattern, considerar:
+
+- `useQuickCreateLock()` composable que encapsula `anyChildDialogOpen` (DRY entre parent dialogs com 2+ children)
+- `<BaseQuickCreateDialog>` wrapper component com slots `#fields`, `#footer-extra` e props padrão
+
+**Não fazer agora** — 6 instâncias ainda é pouco pra inflar abstração. Pattern atual (cada quick-create standalone) é fácil de entender e copiar.
+
+---
+
+## 10. Checklist de auditoria
+
+Aplica-se a **todo quick-create do sistema** pós-promoção (2026-05-20):
+
+- [ ] Path correto (feature folder se entidade pertence a 1 feature; `src/components/quick-create/` se cross-feature)
+- [ ] Nome do arquivo: `<Entity>QuickCreateDialog.vue` (PascalCase)
+- [ ] Props canônicas: `modelValue`, `ownerId`, `initialName`
+- [ ] Emits canônicos: `update:modelValue`, `created`
+- [ ] `Dialog` com `modal`, `:draggable="false"`, `:closable="!saving"`
+- [ ] Form reset quando abre (`watch modelValue`)
+- [ ] Sanitização: `trim() + slice(maxlength) + nullif` ANTES de chamar repository
+- [ ] **Insert via repository** (não supabase direto) — repository injeta `owner_id`+`tenant_id` e faz uniqueness check
+- [ ] Toast feedback em success/warn/error (warn quando erro for "nome em uso", error caso contrário)
+- [ ] Emit `created` com row completo (não só id)
+- [ ] Parent: `anyChildDialogOpen` computed lock
+- [ ] Parent: `dismissableMask` e `closeOnEscape` bindados ao lock
+- [ ] Parent: handler `on<Entity>Created` insere row na lista local e pré-seleciona
+- [ ] Parent: `initialName` capturado do search atual do select
+- [ ] Botão "+": `size="small"` `severity="secondary"` `v-tooltip`
+- [ ] `autofocus` no primeiro input
+- [ ] `:loading="saving"` + `:disabled="!canSave()"` no Salvar
+- [ ] Máximo 3-5 inputs no form (senão não é quick-create — vira página dedicada)
+
+Divergências viram items em `dev_auditoria_items` com:
+- `categoria`: `padronizacao`
+- `tag`: `padronizacao:<modulo>` (módulo dono da entidade)
+- `severidade`: **alta** se usa supabase direto em vez de repository, ou viola lock (vaza dismiss); **média** se viola contrato (emits/props); **baixa** se cosmético
+
+---
+
+## 11. Referências
+
+- Canônicos: `src/features/agenda/components/ServiceQuickCreateDialog.vue`, `InsurancePlanQuickCreateDialog.vue`, `InsurancePlanServiceQuickCreateDialog.vue`
+- Parent integrador: `src/features/agenda/components/AgendaEventDialog.vue` (linhas ~3081-3107, ~3170, ~3274, ~3307)
+- Legacy a refatorar: `src/components/CadastroRapidoMedico.vue`, `CadastroRapidoConvenio.vue`, `ComponentCadastroRapido.vue`
+- Dialog base: `blueprints/dialog-blueprint.md`
+- Repository pareado: `blueprints/repository-blueprint.md`
+- Audit baseline: `development/02-auditoria/AUDIT_BASELINE.md` (3 candidates descobertos em 2026-05-20)
+- Memória: `feedback_agenda_inline_quick_create.md` (superseded — pattern agora universal), `feedback_sanitizacao.md`
+- Estratégia: `development/02-auditoria/PADRONIZACAO.md`

blueprints/repository-blueprint.md

@@ -0,0 +1,379 @@
+# Repository Blueprint
+
+> **Stack:** Supabase JS client + Vue 3 (Pinia stores)
+> **Canônico:** `src/features/agenda/services/` (validado em C1-C13 + análise sênior 2026-05-20)
+> **Aplicável:** todo módulo com acesso a tabela `*` com `tenant_id`
+
+---
+
+## 1. Princípio
+
+Camada **thin** entre Supabase e composables. **Funções puras** + **tenant guards** + **SELECT canônico**. Sem classes, sem state, sem singletons. Idempotente, testável, descartável.
+
+Composable orquestra estado e cache. **Repository só fala com o banco.**
+
+---
+
+## 2. Estrutura de arquivos
+
+```
+src/features/<modulo>/services/
+├── _tenantGuards.js              # SHARED entre repositories do feature
+├── <feature>Selects.js           # SELECT canônico + helpers de flatten
+├── <feature>Repository.js        # CRUD escopo terapeuta (owner_id = uid)
+└── <feature>ClinicRepository.js  # CRUD escopo clínica (se aplicável)
+```
+
+**Regra do `_tenantGuards.js`:** se o feature tem 2+ repositories (terapeuta + clínica), os guards saem pra arquivo compartilhado. Se só tem 1, pode ficar no topo do próprio repo.
+
+---
+
+## 3. Tenant guards canônicos
+
+Copiar **literal** de `src/features/agenda/services/_tenantGuards.js`:
+
+```js
+import { supabase } from '@/lib/supabase/client';
+
+export function assertTenantId(tenantId) {
+    if (!tenantId || tenantId === 'null' || tenantId === 'undefined') {
+        throw new Error('Tenant ativo inválido. Selecione a clínica/tenant antes de operar.');
+    }
+}
+
+export async function getUid() {
+    const { data, error } = await supabase.auth.getUser();
+    if (error) throw error;
+    const uid = data?.user?.id;
+    if (!uid) throw new Error('Usuário não autenticado.');
+    return uid;
+}
+
+export function assertIsoRange(startISO, endISO) {
+    if (!startISO || !endISO) throw new Error('Intervalo inválido (startISO/endISO).');
+}
+
+export function sanitizeOwnerIds(ownerIds) {
+    return (ownerIds || []).filter((id) => typeof id === 'string' && id && id !== 'null' && id !== 'undefined');
+}
+```
+
+**Por quê string `'null'`/`'undefined'`?** Vindo de URL params/localStorage stringificado, esses casos aparecem como string literal. Defesa em profundidade.
+
+---
+
+## 4. SELECT canônico
+
+**Extrair pra constante exportada.** Inline SELECT em 3 lugares = divergência sutil (FKs explícitas em uns, não em outros) = bug.
+
+```js
+/**
+ * Select canônico de <tabela> com joins.
+ *
+ * FKs explícitas (obrigatórias quando há múltiplas colunas apontando pra mesma tabela):
+ *   - <tabela>_<col>_fkey
+ */
+export const <FEATURE>_SELECT = `
+  id, owner_id, tenant_id, ...,
+  patients!<tabela>_<col>_fkey (
+    id, nome_completo, avatar_url, status
+  )
+`.trim();
+```
+
+E o **flatten helper** ao lado:
+
+```js
+/**
+ * Achata o aninhamento de patients dentro da row.
+ * Mantém ambas formas (flat + nested) pra compat com call sites variados.
+ */
+export function flatten<Feature>Row(r) {
+    if (!r) return r;
+    const patient = r.patients || null;
+    return {
+        ...r,
+        paciente_nome: patient?.nome_completo || r.paciente_nome || '',
+        paciente_avatar: patient?.avatar_url || r.paciente_avatar || '',
+        paciente_status: patient?.status || r.paciente_status || ''
+    };
+}
+```
+
+---
+
+## 5. Convenções de assinatura
+
+### Funções puras exportadas
+
+```js
+// ✅ certo
+export async function listMyEvents({ startISO, endISO, ownerId, tenantId } = {}) { ... }
+
+// ❌ errado — classe com state
+class AgendaRepository {
+  async list() { ... }
+}
+```
+
+### Args nomeados (destructure)
+
+Posicionais quebram com refator. Default `= {}` evita TypeError se chamarem sem args.
+
+### `tenantId` opcional → resolve via store
+
+Helper local no repository:
+
+```js
+import { useTenantStore } from '@/stores/tenantStore';
+import { assertTenantId } from './_tenantGuards';
+
+function resolveTenantId(tenantIdArg) {
+    const tenantStore = useTenantStore();
+    const tenantId = tenantIdArg || tenantStore.activeTenantId;
+    assertTenantId(tenantId);
+    return tenantId;
+}
+```
+
+Por que opcional? Composable pode passar `tenantId` explícito (testes, multi-tenant ops). Default chega via store.
+
+### Errors throw, nunca silent
+
+```js
+const { data, error } = await supabase.from('...').select(...);
+if (error) throw error;  // ✅
+// ❌ if (error) return null;
+// ❌ if (error) console.error(error);
+```
+
+Composable decide se faz `try/catch` + toast.
+
+### Ranges half-open
+
+```js
+// ✅ certo — half-open
+.gte('inicio_em', startISO).lt('inicio_em', endISO)
+
+// ❌ errado — fechado, gera off-by-one no último ms
+.gte('inicio_em', startISO).lte('inicio_em', endISO)
+```
+
+### Strip campos legados antes de insert/update
+
+```js
+// eslint-disable-next-line no-unused-vars
+const { paciente_id: _dropped, ...safePayload } = payload;
+```
+
+Quando há migração de coluna em andamento ou campo virtual no UI.
+
+---
+
+## 6. Operações CRUD — pattern
+
+### Create (owner-scoped)
+
+```js
+export async function create<Feature>(payload) {
+    if (!payload) throw new Error('Payload vazio.');
+    const uid = await getUid();
+    const tid = resolveTenantId();
+
+    const { paciente_id: _dropped, ...rest } = payload;
+    const insertPayload = { ...rest, tenant_id: tid, owner_id: uid };
+
+    const { data, error } = await supabase
+        .from('<tabela>')
+        .insert([insertPayload])
+        .select(<FEATURE>_SELECT)
+        .single();
+
+    if (error) throw error;
+    return flatten<Feature>Row(data);
+}
+```
+
+**Sempre:**
+- `tenant_id` injetado do store (não aceita do payload)
+- `owner_id` injetado do uid logado (ignora do payload — clinic-scoped variant pode aceitar explícito)
+- `.select(...)` + `.single()` retorna o registro completo
+
+### Update
+
+```js
+export async function update<Feature>(id, patch, { tenantId } = {}) {
+    if (!id) throw new Error('ID inválido.');
+    if (!patch) throw new Error('Patch vazio.');
+    const tid = resolveTenantId(tenantId);
+
+    const { paciente_id: _dropped, ...safePatch } = patch;
+
+    const { data, error } = await supabase
+        .from('<tabela>')
+        .update(safePatch)
+        .eq('id', id)
+        .eq('tenant_id', tid)  // ← defesa em profundidade — RLS reforça no banco
+        .select(<FEATURE>_SELECT)
+        .single();
+
+    if (error) throw error;
+    return flatten<Feature>Row(data);
+}
+```
+
+### Delete
+
+```js
+export async function delete<Feature>(id, { tenantId } = {}) {
+    if (!id) throw new Error('ID inválido.');
+    const tid = resolveTenantId(tenantId);
+
+    const { error } = await supabase
+        .from('<tabela>')
+        .delete()
+        .eq('id', id)
+        .eq('tenant_id', tid);
+
+    if (error) throw error;
+    return true;
+}
+```
+
+### List (range query)
+
+```js
+export async function list<Feature>({ startISO, endISO, ownerId, tenantId } = {}) {
+    assertIsoRange(startISO, endISO);
+    const uid = ownerId || (await getUid());
+    const tid = resolveTenantId(tenantId);
+
+    const { data, error } = await supabase
+        .from('<tabela>')
+        .select(<FEATURE>_SELECT)
+        .eq('tenant_id', tid)
+        .eq('owner_id', uid)
+        .gte('inicio_em', startISO)
+        .lt('inicio_em', endISO)
+        .order('inicio_em', { ascending: true });
+
+    if (error) throw error;
+    return (data || []).map(flatten<Feature>Row);
+}
+```
+
+### Clinic-scoped variant (admin/secretaria)
+
+Diferenças em relação ao owner-scoped:
+- `tenantId` **obrigatório explícito** (sem default via store — admin pode operar em qualquer tenant onde tem permissão)
+- `ownerIds` é array (multi-terapeuta no mosaico) → `sanitizeOwnerIds` antes do `.in(...)`
+- Permite definir `owner_id` no create (admin cria pra qualquer terapeuta do tenant)
+- Sem `excludeMirror` automático — depende do uso
+
+Referência: `src/features/agenda/services/agendaClinicRepository.js`
+
+---
+
+## 7. Anti-patterns (NÃO fazer)
+
+### ❌ Inline SELECT espalhado
+
+```js
+// ❌ em useFoo.js
+const { data } = await supabase.from('events').select('id, owner_id, patient_id, ...');
+
+// ❌ em fooRepository.js
+const { data } = await supabase.from('events').select('id, owner_id, ...');  // ← divergente
+```
+
+✅ Extrair pra `<feature>Selects.js`.
+
+### ❌ `useTenantStore()` em vários arquivos
+
+```js
+// ❌ em 5 arquivos diferentes
+const tenantStore = useTenantStore();
+const tid = tenantStore.activeTenantId;
+if (!tid) throw new Error('...');
+```
+
+✅ `resolveTenantId(tenantIdArg)` no topo do repo.
+
+### ❌ Aceitar `owner_id` do payload em create owner-scoped
+
+```js
+// ❌ permite usuário criar evento "de outro terapeuta"
+await supabase.from('events').insert({ ...payload, tenant_id: tid });
+```
+
+✅ Sempre injetar `owner_id` do uid logado (sobrescreve qualquer valor do payload).
+
+### ❌ `delete()` sem `.eq('tenant_id', tid)`
+
+```js
+// ❌ RLS deveria pegar, mas defesa em profundidade
+await supabase.from('events').delete().eq('id', id);
+```
+
+✅ Sempre filtra `.eq('tenant_id', tid)` mesmo com RLS ativo.
+
+### ❌ Return null em erro
+
+```js
+// ❌
+if (error) {
+    console.error(error);
+    return null;
+}
+```
+
+✅ `throw error`. Composable decide o que fazer.
+
+### ❌ Range fechado
+
+```js
+// ❌ — `2026-05-20` no `endISO` faz aparecer o dia inteiro do 20
+.gte('inicio_em', startISO).lte('inicio_em', endISO)
+```
+
+✅ Half-open: `.gte(...).lt(...)`. Caller passa `endISO` como o início do próximo bucket.
+
+### ❌ `paciente_id` (ou outro campo legado) chegando ao banco
+
+A migração já dropou colunas legadas. Strip no `safePayload` evita 400 silencioso.
+
+---
+
+## 8. Checklist de auditoria por módulo
+
+Quando rodar `/audit-module <nome>`, validar:
+
+- [ ] `services/_tenantGuards.js` existe (ou inline se 1 repo só)
+- [ ] `services/<feature>Selects.js` existe e exporta `<FEATURE>_SELECT`
+- [ ] `services/<feature>Repository.js` é pure functions (sem classe/state)
+- [ ] `resolveTenantId(tenantIdArg)` local — não `useTenantStore()` espalhado
+- [ ] Toda operação injeta `tenant_id` no insert/update
+- [ ] Create owner-scoped injeta `owner_id` do uid logado (ignora do payload)
+- [ ] Update/delete filtram `.eq('id').eq('tenant_id', tid)` — defesa em profundidade
+- [ ] FKs explícitas nos joins (`<tabela>!<fk_name>`)
+- [ ] Errors `throw`, nunca silent
+- [ ] Ranges half-open (`gte + lt`)
+- [ ] Strip de campos legados em insert/update
+- [ ] Clinic-scoped variant (se existe) sem default via store, tenantId obrigatório
+- [ ] `flatten<Feature>Row` definido se há joins aninhados
+
+Divergências viram items em `dev_auditoria_items` com:
+- `categoria`: `padronizacao`
+- `tag`: `padronizacao:<modulo>`
+- `severidade`: alta se viola segurança (tenant leak), média se viola convenção, baixa se cosmético
+- `arquivo`: path do arquivo
+- `solucao`: referência ao item do checklist
+
+---
+
+## 9. Referências
+
+- Canônico: `src/features/agenda/services/`
+- Variant clinic: `src/features/agenda/services/agendaClinicRepository.js`
+- Tracker: `dev_auditoria_items` com tag `padronizacao:<modulo>`
+- Decisões macro: `development/02-auditoria/PADRONIZACAO.md`

database-novo/db.config.json

@@ -22,7 +22,10 @@
       "seed_015_document_templates.sql",
       "seed_030_dev_phases_items.sql",
       "seed_031_dev_auditoria.sql",
-      "seed_032_dev_competitors.sql"
+      "seed_032_dev_competitors.sql",
+      "seed_040_clinical_note_templates.sql",
+      "seed_050_specialties.sql",
+      "seed_060_consent_forms_extra.sql"
     ],
     "test_data": [
       "seed_020_test_data.sql"
@@ -106,7 +109,7 @@
       "contact_email_types", "contact_emails"
     ],
     "Agenda / Agendamento": [
-      "agenda_eventos", "agenda_bloqueios", "agenda_configuracoes", "agenda_excecoes",
+      "agenda_eventos", "agenda_bloqueios", "agenda_configuracoes",
       "agenda_online_slots", "agenda_regras_semanais",
       "agenda_slots_bloqueados_semanais", "agenda_slots_regras",
       "agendador_configuracoes", "agendador_solicitacoes"

database-novo/docs/schema_map.md

@@ -43,13 +43,12 @@ Mapa completo do banco de dados PostgreSQL 17, extraído de `schema.sql` (2026-0
 | `module_features` | Features por módulo |
 | `tenant_modules` | Módulos ativos por tenant |
 
-### Agenda (11 tabelas)
+### Agenda (10 tabelas)
 | Tabela | Descrição |
 |--------|-----------|
 | `agenda_bloqueios` | Bloqueios de horário |
 | `agenda_configuracoes` | Configurações da agenda por tenant_member |
 | `agenda_eventos` | Eventos da agenda (sessões, bloqueios) |
-| `agenda_excecoes` | Exceções na agenda (horários extras, bloqueios pontuais) |
 | `agenda_online_slots` | Slots de agendamento online |
 | `agenda_regras_semanais` | Regras semanais de disponibilidade |
 | `agenda_slots_bloqueados_semanais` | Slots bloqueados na semana |

database-novo/migrations/20260513000001_drop_agenda_excecoes.sql

@@ -0,0 +1,32 @@
+-- ============================================================================
+-- Drop agenda_excecoes (tabela órfã) + tipos relacionados
+-- ----------------------------------------------------------------------------
+-- A tabela `public.agenda_excecoes` foi criada num design anterior pra
+-- representar "exceções no horário de trabalho" (almoço extra, atendimento
+-- fora do padrão, etc) mas nunca foi integrada à UI. Auditoria em
+-- 2026-05-13 confirmou 0 referências em src/. As funcionalidades equivalentes
+-- vivem em:
+--   - public.agenda_bloqueios            — bloqueios (período, dia, horário, feriado)
+--   - public.agenda_configuracoes.pausas_semanais (jsonb) — pausas semanais
+--   - public.feriados                    — feriados nacionais/municipais
+--
+-- Esta migration:
+--   1) Dropa o trigger tg_agenda_excecoes_updated_at
+--   2) Dropa a tabela public.agenda_excecoes (CASCADE pra cair policies)
+--   3) Dropa os enums tipo_excecao_agenda e status_excecao_agenda
+--      (verificados: usados APENAS por agenda_excecoes)
+-- ============================================================================
+
+BEGIN;
+
+-- 1. Trigger (idempotente)
+DROP TRIGGER IF EXISTS tg_agenda_excecoes_updated_at ON public.agenda_excecoes;
+
+-- 2. Tabela (CASCADE leva policies junto)
+DROP TABLE IF EXISTS public.agenda_excecoes CASCADE;
+
+-- 3. Enums órfãos
+DROP TYPE IF EXISTS public.tipo_excecao_agenda;
+DROP TYPE IF EXISTS public.status_excecao_agenda;
+
+COMMIT;

database-novo/migrations/20260514000001_financial_records_payment_link.sql

@@ -0,0 +1,24 @@
+-- ============================================================================
+-- Adiciona coluna payment_link em financial_records
+-- ----------------------------------------------------------------------------
+-- Quando a cobrança for paga via gateway externo (Asaas, Stripe, Mercado Pago)
+-- e o terapeuta escolher "Enviar link de pagamento" no AgendaEventDialog, o
+-- link de cobrança gerado pelo gateway é salvo aqui. UI da lista do Financeiro
+-- usa esse campo pra exibir ícone clicável (external-link).
+--
+-- Campo nullable: registros sem integração de gateway (PIX manual, dinheiro,
+-- depósito, cartão maquininha) ficam com payment_link = NULL.
+--
+-- Preparação pra Fase 7 (Pagamento como entidade separada) — quando a
+-- integração Asaas estiver completa, o webhook vai preencher esse campo.
+-- ============================================================================
+
+BEGIN;
+
+ALTER TABLE public.financial_records
+    ADD COLUMN IF NOT EXISTS payment_link text;
+
+COMMENT ON COLUMN public.financial_records.payment_link IS
+    'URL externa de cobrança (Asaas/Stripe/etc) quando payment_method indica gateway. Null em pagamentos manuais.';
+
+COMMIT;

database-novo/migrations/20260514000002_financial_exceptions_consume_on_miss.sql

@@ -0,0 +1,22 @@
+-- ============================================================================
+-- Adiciona coluna default_consume_on_miss em financial_exceptions
+-- ----------------------------------------------------------------------------
+-- Define o comportamento padrão pro saldo de pacote quando o status muda
+-- pra "faltou" ou "cancelado":
+--   true  → desconta 1 sessão do pacote (sessions_used += 1) por padrão
+--   false → não consome saldo (sessão fica disponível pra remarcar)
+--
+-- O dialog de confirmação que aparece ao mudar status sugere essa decisão
+-- mas o terapeuta pode override caso a caso. Padrão começa false (mais
+-- benevolente ao paciente).
+-- ============================================================================
+
+BEGIN;
+
+ALTER TABLE public.financial_exceptions
+    ADD COLUMN IF NOT EXISTS default_consume_on_miss boolean DEFAULT false NOT NULL;
+
+COMMENT ON COLUMN public.financial_exceptions.default_consume_on_miss IS
+    'Default pro toggle "Descontar do saldo" no dialog de status change. false = não consome (paciente pode remarcar); true = consome (sessão perdida).';
+
+COMMIT;

database-novo/migrations/20260514000003_billing_contracts_charging_style.sql

@@ -0,0 +1,31 @@
+-- ============================================================================
+-- Adiciona coluna charging_style em billing_contracts
+-- ----------------------------------------------------------------------------
+-- Identifica como o pacote foi cobrado na criação:
+--   'upfront'    → 1 financial_record total criado na hora; sessões só
+--                  consomem saldo, não geram nova cobrança
+--   'saldo'      → sem financial_record na criação; cada sessão realizada
+--                  gera 1 cobrança individual e incrementa sessions_used
+--   'per_session'→ N financial_records já criados na materialização da série
+--                  (chargeMode='per_session' do AgendaEventDialog)
+--
+-- Sem esse campo, o handler de status change não saberia distinguir entre
+-- "já tudo pago, só atualizar status" vs "criar cobrança nova".
+-- ============================================================================
+
+BEGIN;
+
+ALTER TABLE public.billing_contracts
+    ADD COLUMN IF NOT EXISTS charging_style text DEFAULT 'saldo';
+
+-- Constraint pra restringir aos 3 valores válidos
+ALTER TABLE public.billing_contracts
+    DROP CONSTRAINT IF EXISTS billing_contracts_charging_style_chk;
+ALTER TABLE public.billing_contracts
+    ADD CONSTRAINT billing_contracts_charging_style_chk
+        CHECK (charging_style = ANY (ARRAY['upfront'::text, 'saldo'::text, 'per_session'::text]));
+
+COMMENT ON COLUMN public.billing_contracts.charging_style IS
+    'Estilo de cobrança: upfront (1 record total no início), saldo (cobra por sessão realizada), per_session (N records já criados).';
+
+COMMIT;

database-novo/migrations/20260519000001_create_financial_record_ignore_cancelled.sql

@@ -0,0 +1,86 @@
+-- ============================================================================
+-- create_financial_record_for_session: idempotência ignora cancelled
+-- ----------------------------------------------------------------------------
+-- Bug: a função recusava criar um novo financial_record quando já existia
+-- um record cancelled pro mesmo agenda_evento_id, porque a checagem de
+-- idempotência só filtrava `deleted_at IS NULL` (e cancel preserva
+-- deleted_at = NULL pra manter auditoria).
+--
+-- Consequência: user cancelava cobrança sem querer e ficava preso — todo
+-- "Gerar cobrança" subsequente retornava o registro cancelado sem inserir
+-- nova linha (frontend recebia data, achava sucesso, mas DB ficava como
+-- estava).
+--
+-- Fix: adiciona `AND status != 'cancelled'` na checagem. Cancelled passa a
+-- ser tratado como "sem cobrança ativa" pra idempotência. Audit history
+-- continua preservado (rows cancelled permanecem na tabela).
+--
+-- Idempotente: CREATE OR REPLACE substitui a função existente.
+-- ============================================================================
+
+BEGIN;
+
+CREATE OR REPLACE FUNCTION public.create_financial_record_for_session(
+    p_tenant_id uuid,
+    p_owner_id uuid,
+    p_patient_id uuid,
+    p_agenda_evento_id uuid,
+    p_amount numeric,
+    p_due_date date
+) RETURNS SETOF public.financial_records
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path TO 'public'
+    AS $$
+DECLARE
+  v_existing public.financial_records%ROWTYPE;
+  v_new      public.financial_records%ROWTYPE;
+BEGIN
+  -- Idempotência: retorna o registro existente se já foi criado.
+  -- Ignora cancelled (treat as "no active record") pra permitir regenerar
+  -- cobrança após cancelamento.
+  SELECT * INTO v_existing
+  FROM public.financial_records
+  WHERE agenda_evento_id = p_agenda_evento_id
+    AND deleted_at IS NULL
+    AND status != 'cancelled'
+  LIMIT 1;
+
+  IF FOUND THEN
+    RETURN NEXT v_existing;
+    RETURN;
+  END IF;
+
+  -- Cria o novo registro
+  INSERT INTO public.financial_records (
+    tenant_id,
+    owner_id,
+    patient_id,
+    agenda_evento_id,
+    amount,
+    discount_amount,
+    final_amount,
+    status,
+    due_date
+  ) VALUES (
+    p_tenant_id,
+    p_owner_id,
+    p_patient_id,
+    p_agenda_evento_id,
+    p_amount,
+    0,
+    p_amount,
+    'pending',
+    p_due_date
+  )
+  RETURNING * INTO v_new;
+
+  -- Marca o evento da agenda como billed = true
+  UPDATE public.agenda_eventos
+    SET billed = TRUE
+  WHERE id = p_agenda_evento_id;
+
+  RETURN NEXT v_new;
+END;
+$$;
+
+COMMIT;

database-novo/migrations/20260520000001_clinical_notes_tables.sql

@@ -0,0 +1,165 @@
+-- ============================================================================
+-- Cria tabelas do prontuário clínico
+-- ----------------------------------------------------------------------------
+-- Núcleo do prontuário: notas clínicas (anamnese, evolução, plano), com
+-- versionamento (audit trail) e templates (SOAP/DAP/BIRP/livre).
+--
+-- Decisões (sessão de modelagem 2026-05-20):
+--   • Tabela única `clinical_notes` discriminada por `note_type` (não 1 tabela
+--     por tipo). Templates customizáveis exigem flexibilidade.
+--   • `content_text` (livre) + `content_structured` (jsonb) coexistem na mesma
+--     row — UI prioriza conforme template; busca/edit rápido sempre tem text.
+--   • Versionamento via snapshot completo (não diff) em `clinical_note_versions`
+--     — restore trivial e audit visualization friendly. Trigger de versionamento
+--     criado em migration separada.
+--   • Instrumentos de avaliação (GAD-7, PHQ-9, etc) ficam pra Fase 2.
+--   • RLS: owner-only (terapeuta responsável). Sem clinic-wide read — CFP exige
+--     sigilo entre profissionais. Policies em migration separada.
+-- ============================================================================
+
+BEGIN;
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 1. clinical_notes — núcleo do prontuário
+-- ──────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS public.clinical_notes (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id uuid NOT NULL,
+    owner_id uuid NOT NULL,                              -- terapeuta responsável
+    patient_id uuid NOT NULL REFERENCES public.patients(id) ON DELETE RESTRICT,
+    session_event_id uuid REFERENCES public.agenda_eventos(id) ON DELETE SET NULL,
+    note_type text NOT NULL,
+    template_id uuid,                                    -- FK adicionada após criar templates
+    title text,
+    content_text text,
+    content_structured jsonb,
+    pinned boolean DEFAULT false NOT NULL,
+    is_draft boolean DEFAULT false NOT NULL,
+    created_at timestamp with time zone DEFAULT now() NOT NULL,
+    updated_at timestamp with time zone DEFAULT now() NOT NULL,
+    created_by uuid NOT NULL,
+    updated_by uuid,
+    deleted_at timestamp with time zone,
+    deleted_by uuid,
+    CONSTRAINT clinical_notes_note_type_check CHECK (note_type IN (
+        'anamnese',
+        'evolucao_sessao',
+        'plano_terapeutico',
+        'observacao_livre',
+        'resumo_caso'
+    )),
+    CONSTRAINT clinical_notes_content_present_check CHECK (
+        content_text IS NOT NULL OR content_structured IS NOT NULL
+    )
+);
+
+COMMENT ON TABLE public.clinical_notes IS
+    'Notas clínicas do prontuário (anamnese, evolução de sessão, plano, observações). Owner-only via RLS — CFP exige sigilo.';
+COMMENT ON COLUMN public.clinical_notes.session_event_id IS
+    'Sessão associada (quando aplicável). Anamnese/plano/resumo podem ter NULL.';
+COMMENT ON COLUMN public.clinical_notes.content_text IS
+    'Conteúdo em texto livre (sempre disponível pra busca/edit rápido).';
+COMMENT ON COLUMN public.clinical_notes.content_structured IS
+    'Conteúdo em formato estruturado quando há template ativo (jsonb dos campos preenchidos).';
+
+CREATE INDEX IF NOT EXISTS idx_clinical_notes_patient_recent
+    ON public.clinical_notes (tenant_id, patient_id, created_at DESC)
+    WHERE deleted_at IS NULL;
+CREATE INDEX IF NOT EXISTS idx_clinical_notes_owner
+    ON public.clinical_notes (owner_id)
+    WHERE deleted_at IS NULL;
+CREATE INDEX IF NOT EXISTS idx_clinical_notes_session
+    ON public.clinical_notes (session_event_id)
+    WHERE session_event_id IS NOT NULL AND deleted_at IS NULL;
+CREATE INDEX IF NOT EXISTS idx_clinical_notes_type
+    ON public.clinical_notes (tenant_id, patient_id, note_type)
+    WHERE deleted_at IS NULL;
+CREATE INDEX IF NOT EXISTS idx_clinical_notes_pinned
+    ON public.clinical_notes (tenant_id, patient_id)
+    WHERE pinned = true AND deleted_at IS NULL;
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 2. clinical_note_versions — audit trail (snapshot completo)
+-- ──────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS public.clinical_note_versions (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    note_id uuid NOT NULL REFERENCES public.clinical_notes(id) ON DELETE CASCADE,
+    tenant_id uuid NOT NULL,
+    version_number integer NOT NULL,
+    title text,
+    content_text text,
+    content_structured jsonb,
+    change_reason text,                                  -- 'criacao' | 'edicao' | livre
+    created_at timestamp with time zone DEFAULT now() NOT NULL,
+    created_by uuid NOT NULL,
+    CONSTRAINT clinical_note_versions_unique UNIQUE (note_id, version_number)
+);
+
+COMMENT ON TABLE public.clinical_note_versions IS
+    'Snapshot completo de cada versão de clinical_notes. Criado via trigger AFTER INSERT OR UPDATE.';
+
+CREATE INDEX IF NOT EXISTS idx_clinical_note_versions_recent
+    ON public.clinical_note_versions (note_id, version_number DESC);
+CREATE INDEX IF NOT EXISTS idx_clinical_note_versions_audit
+    ON public.clinical_note_versions (created_by, created_at DESC);
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 3. clinical_note_templates — templates SOAP/DAP/BIRP/anamnese padrão
+-- ──────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS public.clinical_note_templates (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id uuid,                                      -- NULL = template global do sistema
+    owner_id uuid,                                       -- NULL = template do tenant inteiro
+    key text NOT NULL,                                   -- 'soap', 'dap', 'birp', 'anamnese_padrao', ...
+    name text NOT NULL,
+    note_type text NOT NULL,
+    description text,
+    structure jsonb NOT NULL,                            -- [{key, label, type, required, hint}]
+    is_system boolean DEFAULT false NOT NULL,
+    is_global boolean DEFAULT false NOT NULL,
+    active boolean DEFAULT true NOT NULL,
+    created_at timestamp with time zone DEFAULT now() NOT NULL,
+    updated_at timestamp with time zone DEFAULT now() NOT NULL,
+    CONSTRAINT clinical_note_templates_note_type_check CHECK (note_type IN (
+        'anamnese',
+        'evolucao_sessao',
+        'plano_terapeutico',
+        'observacao_livre',
+        'resumo_caso'
+    )),
+    CONSTRAINT clinical_note_templates_scope_check CHECK (
+        -- Sistema: ambos NULL e is_system=true
+        -- Tenant-wide: tenant_id presente, owner_id NULL
+        -- Owner: ambos presentes
+        (is_system = true AND tenant_id IS NULL AND owner_id IS NULL)
+        OR (is_system = false AND tenant_id IS NOT NULL)
+    )
+);
+
+COMMENT ON TABLE public.clinical_note_templates IS
+    'Templates de notas clínicas. Escopo: sistema (is_system, sem tenant), tenant-wide (tenant_id sem owner), owner (ambos).';
+
+CREATE INDEX IF NOT EXISTS idx_clinical_note_templates_active
+    ON public.clinical_note_templates (note_type)
+    WHERE active = true;
+CREATE INDEX IF NOT EXISTS idx_clinical_note_templates_tenant
+    ON public.clinical_note_templates (tenant_id, note_type)
+    WHERE tenant_id IS NOT NULL AND active = true;
+CREATE INDEX IF NOT EXISTS idx_clinical_note_templates_owner
+    ON public.clinical_note_templates (owner_id, note_type)
+    WHERE owner_id IS NOT NULL AND active = true;
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 4. FK de clinical_notes.template_id (criada agora que templates existe)
+-- ──────────────────────────────────────────────────────────────────────────
+
+ALTER TABLE public.clinical_notes
+    ADD CONSTRAINT clinical_notes_template_fkey
+    FOREIGN KEY (template_id)
+    REFERENCES public.clinical_note_templates(id)
+    ON DELETE SET NULL;
+
+COMMIT;

database-novo/migrations/20260520000002_clinical_notes_rls.sql

@@ -0,0 +1,111 @@
+-- ============================================================================
+-- RLS policies do prontuário clínico
+-- ----------------------------------------------------------------------------
+-- Padrão MAIS RESTRITIVO que agenda — CFP exige sigilo profissional entre
+-- terapeutas do mesmo tenant. Default: APENAS o owner (terapeuta responsável)
+-- lê e escreve. Sem clinic-wide read.
+--
+-- Compartilhamento com supervisor / outro terapeuta vai requerer policy
+-- específica baseada em tabela `clinical_note_shares` (Fase 2).
+--
+-- Templates seguem regra mais aberta:
+--   • Sistema (is_system): todos authenticated leem
+--   • Tenant-wide (tenant_id): membros do tenant leem; tenant_admin edita
+--   • Owner: só o owner lê/edita
+-- ============================================================================
+
+BEGIN;
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- clinical_notes — owner only
+-- ──────────────────────────────────────────────────────────────────────────
+
+ALTER TABLE public.clinical_notes ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY clinical_notes_owner_select
+    ON public.clinical_notes FOR SELECT TO authenticated
+    USING (owner_id = auth.uid() AND deleted_at IS NULL);
+
+CREATE POLICY clinical_notes_owner_insert
+    ON public.clinical_notes FOR INSERT TO authenticated
+    WITH CHECK (
+        owner_id = auth.uid()
+        AND public.is_tenant_member(tenant_id)
+    );
+
+CREATE POLICY clinical_notes_owner_update
+    ON public.clinical_notes FOR UPDATE TO authenticated
+    USING (owner_id = auth.uid())
+    WITH CHECK (owner_id = auth.uid());
+
+-- DELETE só por soft-delete (UPDATE deleted_at). Hard delete bloqueado em RLS.
+-- Backup/admin pode dropar via psql -U supabase_admin se preciso.
+CREATE POLICY clinical_notes_no_hard_delete
+    ON public.clinical_notes FOR DELETE TO authenticated
+    USING (false);
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- clinical_note_versions — read-only pelo owner da nota
+-- ──────────────────────────────────────────────────────────────────────────
+
+ALTER TABLE public.clinical_note_versions ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY clinical_note_versions_owner_select
+    ON public.clinical_note_versions FOR SELECT TO authenticated
+    USING (
+        EXISTS (
+            SELECT 1 FROM public.clinical_notes cn
+            WHERE cn.id = clinical_note_versions.note_id
+              AND cn.owner_id = auth.uid()
+        )
+    );
+
+-- INSERT só via trigger (SECURITY DEFINER). Sem policy de UPDATE/DELETE —
+-- versões são imutáveis. Trigger usa role bypass.
+CREATE POLICY clinical_note_versions_no_write
+    ON public.clinical_note_versions FOR INSERT TO authenticated
+    WITH CHECK (false);
+CREATE POLICY clinical_note_versions_no_update
+    ON public.clinical_note_versions FOR UPDATE TO authenticated
+    USING (false);
+CREATE POLICY clinical_note_versions_no_delete
+    ON public.clinical_note_versions FOR DELETE TO authenticated
+    USING (false);
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- clinical_note_templates — escopo escalonado
+-- ──────────────────────────────────────────────────────────────────────────
+
+ALTER TABLE public.clinical_note_templates ENABLE ROW LEVEL SECURITY;
+
+-- SELECT: sistema (qualquer authenticated) + tenant-wide (membros) + owner (próprio)
+CREATE POLICY clinical_note_templates_select
+    ON public.clinical_note_templates FOR SELECT TO authenticated
+    USING (
+        active = true
+        AND (
+            is_system = true
+            OR (tenant_id IS NOT NULL AND public.is_tenant_member(tenant_id))
+        )
+    );
+
+-- INSERT/UPDATE/DELETE: só owner ou tenant_admin do tenant
+-- Templates do sistema (is_system) nunca alteráveis via UI — só via seed/migration.
+CREATE POLICY clinical_note_templates_owner_write
+    ON public.clinical_note_templates TO authenticated
+    USING (
+        is_system = false
+        AND (
+            owner_id = auth.uid()
+            OR (owner_id IS NULL AND public.is_tenant_admin(tenant_id))
+        )
+    )
+    WITH CHECK (
+        is_system = false
+        AND (
+            owner_id = auth.uid()
+            OR (owner_id IS NULL AND public.is_tenant_admin(tenant_id))
+        )
+    );
+
+COMMIT;

database-novo/migrations/20260520000003_clinical_notes_versioning.sql

@@ -0,0 +1,117 @@
+-- ============================================================================
+-- Trigger de versionamento automático de clinical_notes
+-- ----------------------------------------------------------------------------
+-- A cada INSERT ou UPDATE relevante em clinical_notes, cria snapshot completo
+-- em clinical_note_versions. Função é SECURITY DEFINER pra bypassar a RLS
+-- (que bloqueia INSERT direto em clinical_note_versions).
+--
+-- Versionamento dispara em:
+--   • INSERT — registra criação (version_number = 1)
+--   • UPDATE em content_text, content_structured ou title — registra edição
+--
+-- Mudanças em pinned/is_draft NÃO disparam versionamento (mudança de UI/state,
+-- não de conteúdo).
+-- ============================================================================
+
+BEGIN;
+
+CREATE OR REPLACE FUNCTION public.fn_clinical_note_version()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+    next_version integer;
+    reason text;
+BEGIN
+    SELECT COALESCE(MAX(version_number), 0) + 1
+      INTO next_version
+      FROM public.clinical_note_versions
+     WHERE note_id = NEW.id;
+
+    IF TG_OP = 'INSERT' THEN
+        reason := 'criacao';
+    ELSIF TG_OP = 'UPDATE' THEN
+        IF NEW.deleted_at IS NOT NULL AND OLD.deleted_at IS NULL THEN
+            reason := 'soft_delete';
+        ELSIF NEW.deleted_at IS NULL AND OLD.deleted_at IS NOT NULL THEN
+            reason := 'restore';
+        ELSE
+            reason := 'edicao';
+        END IF;
+    ELSE
+        reason := 'desconhecido';
+    END IF;
+
+    INSERT INTO public.clinical_note_versions (
+        note_id,
+        tenant_id,
+        version_number,
+        title,
+        content_text,
+        content_structured,
+        change_reason,
+        created_at,
+        created_by
+    ) VALUES (
+        NEW.id,
+        NEW.tenant_id,
+        next_version,
+        NEW.title,
+        NEW.content_text,
+        NEW.content_structured,
+        reason,
+        now(),
+        COALESCE(NEW.updated_by, NEW.created_by)
+    );
+
+    RETURN NEW;
+END;
+$$;
+
+COMMENT ON FUNCTION public.fn_clinical_note_version() IS
+    'Snapshot completo de clinical_notes a cada INSERT/UPDATE relevante. SECURITY DEFINER bypassa RLS pra escrever em clinical_note_versions (que bloqueia INSERT direto).';
+
+CREATE TRIGGER trg_clinical_notes_version_insert
+    AFTER INSERT ON public.clinical_notes
+    FOR EACH ROW
+    EXECUTE FUNCTION public.fn_clinical_note_version();
+
+CREATE TRIGGER trg_clinical_notes_version_update
+    AFTER UPDATE OF content_text, content_structured, title, deleted_at
+    ON public.clinical_notes
+    FOR EACH ROW
+    WHEN (
+        OLD.content_text IS DISTINCT FROM NEW.content_text
+        OR OLD.content_structured IS DISTINCT FROM NEW.content_structured
+        OR OLD.title IS DISTINCT FROM NEW.title
+        OR OLD.deleted_at IS DISTINCT FROM NEW.deleted_at
+    )
+    EXECUTE FUNCTION public.fn_clinical_note_version();
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- Trigger para updated_at automático
+-- ──────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.fn_clinical_notes_updated_at()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+    NEW.updated_at := now();
+    RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER trg_clinical_notes_updated_at
+    BEFORE UPDATE ON public.clinical_notes
+    FOR EACH ROW
+    EXECUTE FUNCTION public.fn_clinical_notes_updated_at();
+
+CREATE TRIGGER trg_clinical_note_templates_updated_at
+    BEFORE UPDATE ON public.clinical_note_templates
+    FOR EACH ROW
+    EXECUTE FUNCTION public.fn_clinical_notes_updated_at();
+
+COMMIT;

database-novo/migrations/20260520000004_documents_clinical_note_link.sql

@@ -0,0 +1,46 @@
+-- ============================================================================
+-- Liga documents a clinical_notes (preenche FK órfã)
+-- ----------------------------------------------------------------------------
+-- A coluna `documents.session_note_id` existia desde antes apontando pra uma
+-- tabela `session_notes` que nunca foi criada. Agora que `clinical_notes`
+-- existe e abrange anamnese/evolução/plano (não só sessão), renomeia pra
+-- `clinical_note_id` e adiciona FK constraint.
+--
+-- PRÉ-CHECK: a query abaixo deve retornar 0 antes de rodar esta migration.
+--   SELECT count(*) FROM public.documents WHERE session_note_id IS NOT NULL;
+-- Se houver dados, eles são órfãos (referenciam tabela inexistente) — limpar
+-- antes de adicionar a FK constraint, ou ela falha.
+-- ============================================================================
+
+BEGIN;
+
+-- 1. Limpa eventuais órfãos (FK nunca foi enforced, mas valor pode ter sido
+--    setado por código no front antes da migration). Defesa em profundidade.
+UPDATE public.documents
+   SET session_note_id = NULL
+ WHERE session_note_id IS NOT NULL
+   AND NOT EXISTS (
+       SELECT 1 FROM public.clinical_notes cn
+        WHERE cn.id = documents.session_note_id
+   );
+
+-- 2. Rename
+ALTER TABLE public.documents
+    RENAME COLUMN session_note_id TO clinical_note_id;
+
+-- 3. FK constraint
+ALTER TABLE public.documents
+    ADD CONSTRAINT documents_clinical_note_fkey
+    FOREIGN KEY (clinical_note_id)
+    REFERENCES public.clinical_notes(id)
+    ON DELETE SET NULL;
+
+-- 4. Index pra reverse lookup (documentos de uma nota)
+CREATE INDEX IF NOT EXISTS idx_documents_clinical_note
+    ON public.documents (clinical_note_id)
+    WHERE clinical_note_id IS NOT NULL AND deleted_at IS NULL;
+
+COMMENT ON COLUMN public.documents.clinical_note_id IS
+    'Vínculo opcional a uma nota clínica (anexar PDF a anamnese/evolução). Renomeado de session_note_id em 2026-05-20.';
+
+COMMIT;

database-novo/migrations/20260520000005_accept_tenant_invite_rpc.sql

@@ -0,0 +1,95 @@
+-- ============================================================================
+-- RPC accept_tenant_invite — destrava o fluxo de aceitar convite
+-- ----------------------------------------------------------------------------
+-- Recebe o token UUID do invite. Em uma transação (SECURITY DEFINER):
+--   1. Lê invite ATIVO (não accepted, não revoked, não expired)
+--   2. INSERT em tenant_members com role do invite + user_id = auth.uid()
+--   3. UPDATE invite com accepted_at + accepted_by
+--
+-- Retorna jsonb { ok, tenant_id, role } em sucesso ou throw com mensagem PT-BR.
+--
+-- Chamada pelo features/tenantship/services/tenantInvitesRepository.acceptInvite().
+-- Stub anterior tava jogando erro PT-BR explicando isso. Agora funciona.
+-- ============================================================================
+
+BEGIN;
+
+CREATE OR REPLACE FUNCTION public.accept_tenant_invite(p_token uuid)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+    v_uid uuid;
+    v_invite record;
+    v_existing_member record;
+BEGIN
+    -- Quem está aceitando — auth.uid() pega do JWT
+    v_uid := auth.uid();
+    IF v_uid IS NULL THEN
+        RAISE EXCEPTION 'Sessão inválida (sem user autenticado).';
+    END IF;
+
+    -- 1. Lê invite ativo. Lock via FOR UPDATE pra evitar race.
+    SELECT id, tenant_id, email, role, accepted_at, revoked_at, expires_at
+      INTO v_invite
+      FROM public.tenant_invites
+     WHERE token = p_token
+     FOR UPDATE;
+
+    IF NOT FOUND THEN
+        RAISE EXCEPTION 'Convite não encontrado. Verifique o link.';
+    END IF;
+
+    IF v_invite.revoked_at IS NOT NULL THEN
+        RAISE EXCEPTION 'Convite revogado pelo administrador.';
+    END IF;
+
+    IF v_invite.accepted_at IS NOT NULL THEN
+        RAISE EXCEPTION 'Convite já foi aceito anteriormente.';
+    END IF;
+
+    IF v_invite.expires_at IS NOT NULL AND v_invite.expires_at < now() THEN
+        RAISE EXCEPTION 'Convite expirado. Peça um novo ao administrador.';
+    END IF;
+
+    -- 2. Idempotência: se já é membro do tenant, só marca invite aceito.
+    SELECT id, role, status
+      INTO v_existing_member
+      FROM public.tenant_members
+     WHERE tenant_id = v_invite.tenant_id
+       AND user_id = v_uid
+     LIMIT 1;
+
+    IF v_existing_member.id IS NULL THEN
+        INSERT INTO public.tenant_members (tenant_id, user_id, role, status)
+        VALUES (v_invite.tenant_id, v_uid, v_invite.role, 'active');
+    ELSIF v_existing_member.status <> 'active' THEN
+        UPDATE public.tenant_members
+           SET status = 'active', role = v_invite.role
+         WHERE id = v_existing_member.id;
+    END IF;
+    -- (se já está ativo, deixa como tá — convite aceito não rebaixa)
+
+    -- 3. Marca invite como aceito
+    UPDATE public.tenant_invites
+       SET accepted_at = now(), accepted_by = v_uid
+     WHERE id = v_invite.id;
+
+    RETURN jsonb_build_object(
+        'ok', true,
+        'tenant_id', v_invite.tenant_id,
+        'role', v_invite.role
+    );
+END;
+$$;
+
+COMMENT ON FUNCTION public.accept_tenant_invite(uuid) IS
+    'Aceita convite de membership. SECURITY DEFINER pra criar tenant_members em nome do user logado. Lock FOR UPDATE no invite previne race condition.';
+
+-- Permite que qualquer authenticated chame (precisa do token UUID válido pra entrar).
+REVOKE ALL ON FUNCTION public.accept_tenant_invite(uuid) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION public.accept_tenant_invite(uuid) TO authenticated;
+
+COMMIT;

database-novo/migrations/20260521000001_asaas_gateway_tables.sql

@@ -0,0 +1,138 @@
+-- ============================================================================
+-- Asaas Gateway — Tier 1 (cobrança de paciente) — schema foundation
+-- ----------------------------------------------------------------------------
+-- Cria 3 tabelas novas + adiciona 4 colunas em payment_settings.
+-- Schema preparado pra Fase 3 do ROADMAP (gateway de pagamento).
+--
+-- ⚠️ Não habilita o gateway sozinho. Requer:
+--   - Edge Functions deployadas
+--   - API keys configuradas em payment_settings
+--   - Webhook setado no dashboard Asaas
+--
+-- Ver: development/02-auditoria/DESIGN_ASAAS_GATEWAY.md
+-- ============================================================================
+
+BEGIN;
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 1. asaas_customers — mapping patient ↔ Asaas customer
+-- ──────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS public.asaas_customers (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id uuid NOT NULL,
+    patient_id uuid NOT NULL REFERENCES public.patients(id) ON DELETE CASCADE,
+    asaas_customer_id text NOT NULL,
+    environment text NOT NULL DEFAULT 'sandbox' CHECK (environment IN ('sandbox', 'prod')),
+    -- dados cacheados (sincronizados quando atualizar patient)
+    name text NOT NULL,
+    email text,
+    cpf_cnpj text,
+    phone text,
+    address jsonb,
+    created_at timestamptz DEFAULT now() NOT NULL,
+    updated_at timestamptz DEFAULT now() NOT NULL,
+    deleted_at timestamptz,
+    CONSTRAINT asaas_customers_unique_per_env UNIQUE (tenant_id, patient_id, environment)
+);
+
+COMMENT ON TABLE public.asaas_customers IS
+    'Mapping de pacientes para Asaas customers (1:1 por environment). Cacheado pra evitar re-criação a cada cobrança.';
+
+CREATE INDEX IF NOT EXISTS idx_asaas_customers_lookup
+    ON public.asaas_customers (tenant_id, patient_id)
+    WHERE deleted_at IS NULL;
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 2. asaas_payments — 1 row por cobrança gerada
+-- ──────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS public.asaas_payments (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id uuid NOT NULL,
+    financial_record_id uuid NOT NULL REFERENCES public.financial_records(id) ON DELETE CASCADE,
+    asaas_customer_id uuid REFERENCES public.asaas_customers(id),
+    asaas_payment_id text NOT NULL,
+    asaas_invoice_id text,
+    environment text NOT NULL DEFAULT 'sandbox' CHECK (environment IN ('sandbox', 'prod')),
+    billing_type text NOT NULL CHECK (billing_type IN ('PIX', 'BOLETO', 'CREDIT_CARD', 'UNDEFINED')),
+    status text NOT NULL,
+    value numeric(10, 2) NOT NULL,
+    net_value numeric(10, 2),
+    due_date date NOT NULL,
+    payment_date timestamptz,
+    invoice_url text,
+    payment_url text,
+    bank_slip_url text,
+    pix_qr_code text,
+    pix_copy_paste text,
+    created_at timestamptz DEFAULT now() NOT NULL,
+    updated_at timestamptz DEFAULT now() NOT NULL,
+    cancelled_at timestamptz,
+    CONSTRAINT asaas_payments_unique_per_env UNIQUE (asaas_payment_id, environment)
+);
+
+COMMENT ON TABLE public.asaas_payments IS
+    'Cobranças geradas no Asaas. Status raw do Asaas; mapeamento pra financial_records.status acontece no JS.';
+
+CREATE INDEX IF NOT EXISTS idx_asaas_payments_record
+    ON public.asaas_payments (financial_record_id);
+CREATE INDEX IF NOT EXISTS idx_asaas_payments_lookup
+    ON public.asaas_payments (tenant_id, status, due_date)
+    WHERE cancelled_at IS NULL;
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 3. asaas_webhook_events — idempotência + audit
+-- ──────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS public.asaas_webhook_events (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    event_id text,
+    event_type text NOT NULL,
+    asaas_payment_id text,
+    payload jsonb NOT NULL,
+    processed_at timestamptz,
+    processing_error text,
+    received_at timestamptz DEFAULT now() NOT NULL
+);
+
+COMMENT ON TABLE public.asaas_webhook_events IS
+    'Audit + idempotência de webhooks Asaas. event_id usado pra dedupe (Asaas faz retry).';
+
+-- event_id UNIQUE quando preenchido (Asaas nem sempre manda)
+CREATE UNIQUE INDEX IF NOT EXISTS idx_asaas_webhook_events_event_id
+    ON public.asaas_webhook_events (event_id)
+    WHERE event_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_asaas_webhook_events_payment
+    ON public.asaas_webhook_events (asaas_payment_id);
+
+CREATE INDEX IF NOT EXISTS idx_asaas_webhook_events_unprocessed
+    ON public.asaas_webhook_events (received_at)
+    WHERE processed_at IS NULL;
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 4. payment_settings — colunas pra config Asaas por tenant
+-- ──────────────────────────────────────────────────────────────────────────
+-- API keys plaintext nesta migration. Em produção, mover pra pgsodium/Vault.
+
+ALTER TABLE public.payment_settings
+    ADD COLUMN IF NOT EXISTS asaas_api_key_sandbox text,
+    ADD COLUMN IF NOT EXISTS asaas_api_key_prod text,
+    ADD COLUMN IF NOT EXISTS asaas_environment text DEFAULT 'sandbox'
+        CHECK (asaas_environment IN ('sandbox', 'prod')),
+    ADD COLUMN IF NOT EXISTS asaas_webhook_token text,
+    ADD COLUMN IF NOT EXISTS asaas_enabled boolean DEFAULT false NOT NULL;
+
+COMMENT ON COLUMN public.payment_settings.asaas_api_key_sandbox IS
+    'API key Asaas SANDBOX. PLAINTEXT por enquanto — migrar pra Vault em prod.';
+COMMENT ON COLUMN public.payment_settings.asaas_api_key_prod IS
+    'API key Asaas PRODUÇÃO. PLAINTEXT por enquanto — migrar pra Vault em prod.';
+COMMENT ON COLUMN public.payment_settings.asaas_environment IS
+    'Qual key usar: sandbox (testes) ou prod (real). Default sandbox por segurança.';
+COMMENT ON COLUMN public.payment_settings.asaas_webhook_token IS
+    'Token customizado pra webhook receiver validar. Setar mesmo valor no dashboard Asaas.';
+COMMENT ON COLUMN public.payment_settings.asaas_enabled IS
+    'Flag que controla se gateway Asaas está habilitado pro tenant. Default false (opt-in).';
+
+COMMIT;

database-novo/migrations/20260521000002_asaas_gateway_rls.sql

@@ -0,0 +1,72 @@
+-- ============================================================================
+-- Asaas Gateway — RLS policies
+-- ----------------------------------------------------------------------------
+-- Owner-scoped: cada terapeuta vê só os customers/payments do seu tenant.
+-- INSERT/UPDATE bloqueado client-side — só Edge Functions (service role)
+-- podem escrever. Browser só lê (pra exibir QR code, status, etc).
+--
+-- API keys em payment_settings: já tem RLS (não duplica).
+-- ============================================================================
+
+BEGIN;
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- asaas_customers
+-- ──────────────────────────────────────────────────────────────────────────
+ALTER TABLE public.asaas_customers ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY asaas_customers_member_select
+    ON public.asaas_customers FOR SELECT TO authenticated
+    USING (public.is_tenant_member(tenant_id));
+
+-- INSERT/UPDATE/DELETE bloqueados — Edge Functions usam service_role que bypassa RLS
+CREATE POLICY asaas_customers_no_client_write
+    ON public.asaas_customers FOR INSERT TO authenticated
+    WITH CHECK (false);
+CREATE POLICY asaas_customers_no_client_update
+    ON public.asaas_customers FOR UPDATE TO authenticated
+    USING (false);
+CREATE POLICY asaas_customers_no_client_delete
+    ON public.asaas_customers FOR DELETE TO authenticated
+    USING (false);
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- asaas_payments
+-- ──────────────────────────────────────────────────────────────────────────
+ALTER TABLE public.asaas_payments ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY asaas_payments_member_select
+    ON public.asaas_payments FOR SELECT TO authenticated
+    USING (public.is_tenant_member(tenant_id));
+
+CREATE POLICY asaas_payments_no_client_write
+    ON public.asaas_payments FOR INSERT TO authenticated
+    WITH CHECK (false);
+CREATE POLICY asaas_payments_no_client_update
+    ON public.asaas_payments FOR UPDATE TO authenticated
+    USING (false);
+CREATE POLICY asaas_payments_no_client_delete
+    ON public.asaas_payments FOR DELETE TO authenticated
+    USING (false);
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- asaas_webhook_events
+-- ──────────────────────────────────────────────────────────────────────────
+-- Audit table — saas_admin lê pra debug. Members não veem.
+ALTER TABLE public.asaas_webhook_events ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY asaas_webhook_events_saas_admin_select
+    ON public.asaas_webhook_events FOR SELECT TO authenticated
+    USING (public.is_saas_admin());
+
+CREATE POLICY asaas_webhook_events_no_client_write
+    ON public.asaas_webhook_events FOR INSERT TO authenticated
+    WITH CHECK (false);
+CREATE POLICY asaas_webhook_events_no_update
+    ON public.asaas_webhook_events FOR UPDATE TO authenticated
+    USING (false);
+CREATE POLICY asaas_webhook_events_no_delete
+    ON public.asaas_webhook_events FOR DELETE TO authenticated
+    USING (false);
+
+COMMIT;

database-novo/migrations/20260521000003_profiles_professional_registration.sql

@@ -0,0 +1,71 @@
+-- ============================================================================
+-- Compliance CFP — Tipo de registro profissional (ROADMAP item #5)
+-- ----------------------------------------------------------------------------
+-- Adiciona campos de registro profissional ao perfil. Necessário pra emissão
+-- de recibos/laudos válidos (CFP exige tipo, número e UF do conselho).
+--
+-- Conselhos comuns no Brasil:
+--   CRP     — Psicólogo
+--   CRM     — Médico
+--   CRFa    — Fonoaudiólogo
+--   CREFITO — Fisioterapeuta / Terapeuta Ocupacional
+--   CRESS   — Assistente Social
+--   CRN     — Nutricionista
+--   RMS     — Residência Multiprofissional (Saúde)
+--   outro   — Catch-all (campo livre na UI)
+-- ============================================================================
+
+BEGIN;
+
+ALTER TABLE public.profiles
+    ADD COLUMN IF NOT EXISTS professional_registration_type text,
+    ADD COLUMN IF NOT EXISTS professional_registration_number text,
+    ADD COLUMN IF NOT EXISTS professional_registration_uf text;
+
+-- CHECK não pode ser ADD IF NOT EXISTS — guard com DO block
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+        WHERE conname = 'profiles_registration_type_check'
+    ) THEN
+        ALTER TABLE public.profiles
+            ADD CONSTRAINT profiles_registration_type_check CHECK (
+                professional_registration_type IS NULL
+                OR professional_registration_type = ANY (ARRAY[
+                    'CRP',
+                    'CRM',
+                    'CRFa',
+                    'CREFITO',
+                    'CRESS',
+                    'CRN',
+                    'RMS',
+                    'outro'
+                ])
+            );
+    END IF;
+END $$;
+
+-- UF check (regex pra 2 chars uppercase ou NULL)
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+        WHERE conname = 'profiles_registration_uf_check'
+    ) THEN
+        ALTER TABLE public.profiles
+            ADD CONSTRAINT profiles_registration_uf_check CHECK (
+                professional_registration_uf IS NULL
+                OR professional_registration_uf ~ '^[A-Z]{2}$'
+            );
+    END IF;
+END $$;
+
+COMMENT ON COLUMN public.profiles.professional_registration_type IS
+    'Tipo de registro profissional. Obrigatório pra emitir recibos/laudos. ROADMAP item #5.';
+COMMENT ON COLUMN public.profiles.professional_registration_number IS
+    'Número do registro (ex: 06/12345 ou 123456). Formato livre — UI ajuda com mask se relevante.';
+COMMENT ON COLUMN public.profiles.professional_registration_uf IS
+    'UF do conselho (2 chars uppercase). Alguns conselhos exigem regionalização (CRP 06/SP, CRP 03/BA).';
+
+COMMIT;

database-novo/migrations/20260521000004_specialties.sql

@@ -0,0 +1,79 @@
+-- ============================================================================
+-- Compliance CFP — Especialidades do profissional (ROADMAP item #9)
+-- ----------------------------------------------------------------------------
+-- Catálogo de especialidades/abordagens + join many-to-many com profiles.
+-- Profissional pode ter múltiplas especialidades (clínica + jurídica, etc).
+-- ============================================================================
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS public.specialties (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    key text UNIQUE NOT NULL,
+    name text NOT NULL,
+    category text,
+    is_system boolean DEFAULT false NOT NULL,
+    active boolean DEFAULT true NOT NULL,
+    created_at timestamptz DEFAULT now() NOT NULL
+);
+
+COMMENT ON TABLE public.specialties IS
+    'Catálogo global de especialidades/abordagens psicológicas (ROADMAP item #9). is_system=true pra entries seedadas.';
+
+CREATE INDEX IF NOT EXISTS idx_specialties_active ON public.specialties (active, category, name);
+
+CREATE TABLE IF NOT EXISTS public.profile_specialties (
+    profile_id uuid NOT NULL REFERENCES public.profiles(id) ON DELETE CASCADE,
+    specialty_id uuid NOT NULL REFERENCES public.specialties(id) ON DELETE RESTRICT,
+    other_label text,
+    created_at timestamptz DEFAULT now() NOT NULL,
+    PRIMARY KEY (profile_id, specialty_id)
+);
+
+COMMENT ON TABLE public.profile_specialties IS
+    'M:N entre profile e specialty. other_label preenchido só quando specialty.key=outra (custom user-defined).';
+
+CREATE INDEX IF NOT EXISTS idx_profile_specialties_profile ON public.profile_specialties (profile_id);
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- RLS
+-- ──────────────────────────────────────────────────────────────────────────
+
+ALTER TABLE public.specialties ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.profile_specialties ENABLE ROW LEVEL SECURITY;
+
+-- specialties: read-only pra todos authenticated (catálogo público); só saas_admin escreve
+CREATE POLICY specialties_authenticated_read
+    ON public.specialties FOR SELECT TO authenticated
+    USING (active = true);
+
+CREATE POLICY specialties_saas_admin_write
+    ON public.specialties TO authenticated
+    USING (public.is_saas_admin())
+    WITH CHECK (public.is_saas_admin());
+
+-- profile_specialties: cada user gerencia o próprio
+CREATE POLICY profile_specialties_owner_select
+    ON public.profile_specialties FOR SELECT TO authenticated
+    USING (profile_id = auth.uid());
+
+CREATE POLICY profile_specialties_owner_insert
+    ON public.profile_specialties FOR INSERT TO authenticated
+    WITH CHECK (profile_id = auth.uid());
+
+CREATE POLICY profile_specialties_owner_delete
+    ON public.profile_specialties FOR DELETE TO authenticated
+    USING (profile_id = auth.uid());
+
+-- Tenant_admin pode VER specialties dos membros (pra cards públicos / perfil clínica)
+CREATE POLICY profile_specialties_tenant_admin_read
+    ON public.profile_specialties FOR SELECT TO authenticated
+    USING (
+        EXISTS (
+            SELECT 1 FROM public.tenant_members tm
+            WHERE tm.user_id = profile_specialties.profile_id
+              AND public.is_tenant_admin(tm.tenant_id)
+        )
+    );
+
+COMMIT;

database-novo/migrations/20260521000005_document_templates_consent_types.sql

@@ -0,0 +1,44 @@
+-- ============================================================================
+-- Compliance CFP #6 — Tipos de consent form (LGPD + Gravação)
+-- ----------------------------------------------------------------------------
+-- Estende o CHECK constraint de document_templates.tipo para acomodar dois
+-- novos tipos de consent form exigidos pela LGPD e pela prática clínica:
+--   • termo_lgpd          — Consentimento de tratamento de dados pessoais
+--   • autorizacao_gravacao — Autorização de gravação de sessão (áudio/vídeo)
+--
+-- ROADMAP item #1.2 #6 (Biblioteca de consent forms editáveis).
+-- ============================================================================
+
+BEGIN;
+
+ALTER TABLE public.document_templates
+    DROP CONSTRAINT IF EXISTS dt_tipo_check;
+
+ALTER TABLE public.document_templates
+    ADD CONSTRAINT dt_tipo_check CHECK (
+        tipo = ANY (ARRAY[
+            'declaracao_comparecimento',
+            'atestado_psicologico',
+            'relatorio_acompanhamento',
+            'recibo_pagamento',
+            'termo_consentimento',
+            'encaminhamento',
+            'contrato_servicos',
+            'tcle',
+            'autorizacao_menor',
+            'laudo_psicologico',
+            'parecer_psicologico',
+            'termo_sigilo',
+            'declaracao_inicio_tratamento',
+            'termo_alta',
+            'tcle_online',
+            'termo_lgpd',
+            'autorizacao_gravacao',
+            'outro'
+        ])
+    );
+
+COMMENT ON COLUMN public.document_templates.tipo IS
+    'Tipo do template. Inclui consent forms (tcle, tcle_online, autorizacao_menor, termo_sigilo, termo_lgpd, autorizacao_gravacao).';
+
+COMMIT;

database-novo/migrations/20260521000006_sign_document_rpcs.sql

@@ -0,0 +1,251 @@
+-- ============================================================================
+-- Compliance CFP #7 — RPCs de assinatura eletrônica
+-- ----------------------------------------------------------------------------
+-- Cria 2 RPCs que registram assinatura capturando IP server-side (anti-spoof)
+-- via inet_client_addr() e user-agent via request headers do Supabase.
+--
+--   • sign_document_by_signature_id — paciente logado assina via portal
+--   • sign_document_by_token        — terceiro assina via share link público
+--
+-- ROADMAP item #1.2 #7 (Assinatura eletrônica pelo paciente no portal,
+-- simples, com IP+timestamp). Não usa ICP-Brasil — é assinatura simples
+-- com audit trail (IP, UA, timestamp, hash SHA-256 do documento).
+-- ============================================================================
+
+BEGIN;
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 1. sign_document_by_signature_id
+-- ----------------------------------------------------------------------------
+-- Para signatários LOGADOS no portal/sistema. SECURITY INVOKER — a RLS de
+-- document_signatures continua aplicando (signatario_id = auth.uid() ou
+-- tenant_members). RPC só serve pra centralizar captura de IP + UA + hash.
+-- ──────────────────────────────────────────────────────────────────────────
+CREATE OR REPLACE FUNCTION public.sign_document_by_signature_id(
+    p_signature_id uuid,
+    p_hash_documento text DEFAULT NULL
+) RETURNS public.document_signatures
+LANGUAGE plpgsql
+SECURITY INVOKER
+AS $$
+DECLARE
+    v_row public.document_signatures;
+    v_ip  inet;
+    v_ua  text;
+BEGIN
+    IF p_signature_id IS NULL THEN
+        RAISE EXCEPTION 'p_signature_id obrigatório' USING ERRCODE = '22023';
+    END IF;
+
+    -- Captura IP e UA do request (best-effort — pode vir NULL em alguns ambientes)
+    v_ip := inet_client_addr();
+    BEGIN
+        v_ua := current_setting('request.headers', true)::json ->> 'user-agent';
+    EXCEPTION WHEN OTHERS THEN
+        v_ua := NULL;
+    END;
+
+    UPDATE public.document_signatures
+       SET status         = 'assinado',
+           ip             = v_ip,
+           user_agent     = v_ua,
+           assinado_em    = now(),
+           hash_documento = COALESCE(p_hash_documento, hash_documento),
+           atualizado_em  = now()
+     WHERE id = p_signature_id
+       AND status IN ('pendente', 'enviado')
+     RETURNING * INTO v_row;
+
+    IF v_row.id IS NULL THEN
+        RAISE EXCEPTION 'Assinatura não encontrada ou já processada' USING ERRCODE = 'P0002';
+    END IF;
+
+    RETURN v_row;
+END;
+$$;
+
+COMMENT ON FUNCTION public.sign_document_by_signature_id(uuid, text) IS
+    'Assinatura via portal logado. Captura IP/UA server-side. RLS aplica (SECURITY INVOKER).';
+
+GRANT EXECUTE ON FUNCTION public.sign_document_by_signature_id(uuid, text) TO authenticated;
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 2. sign_document_by_token
+-- ----------------------------------------------------------------------------
+-- Para signatários NÃO LOGADOS via share link público. SECURITY DEFINER —
+-- bypassa RLS. Valida o share_link (token, ativo, expira_em, usos_max),
+-- localiza o signatário PENDENTE associado ao documento (signatario_email
+-- opcional p/ desambiguar quando há múltiplos), assina, incrementa usos.
+-- ──────────────────────────────────────────────────────────────────────────
+CREATE OR REPLACE FUNCTION public.sign_document_by_token(
+    p_token text,
+    p_signature_id uuid DEFAULT NULL,
+    p_hash_documento text DEFAULT NULL
+) RETURNS public.document_signatures
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+    v_link    public.document_share_links;
+    v_sig     public.document_signatures;
+    v_ip      inet;
+    v_ua      text;
+BEGIN
+    IF p_token IS NULL OR length(p_token) < 32 THEN
+        RAISE EXCEPTION 'Token inválido' USING ERRCODE = '22023';
+    END IF;
+
+    -- Valida share_link
+    SELECT * INTO v_link
+      FROM public.document_share_links
+     WHERE token = p_token
+       AND ativo = true
+       AND expira_em > now()
+       AND usos < usos_max
+     LIMIT 1;
+
+    IF v_link.id IS NULL THEN
+        RAISE EXCEPTION 'Link expirado, inválido ou esgotado' USING ERRCODE = 'P0002';
+    END IF;
+
+    -- Localiza a signature pendente do documento. Se p_signature_id veio,
+    -- é desambiguação (multi-signatário); senão pega a primeira pendente
+    -- por ordem.
+    IF p_signature_id IS NOT NULL THEN
+        SELECT * INTO v_sig
+          FROM public.document_signatures
+         WHERE id = p_signature_id
+           AND documento_id = v_link.documento_id
+           AND status IN ('pendente', 'enviado')
+         LIMIT 1;
+    ELSE
+        SELECT * INTO v_sig
+          FROM public.document_signatures
+         WHERE documento_id = v_link.documento_id
+           AND status IN ('pendente', 'enviado')
+         ORDER BY ordem ASC, criado_em ASC
+         LIMIT 1;
+    END IF;
+
+    IF v_sig.id IS NULL THEN
+        RAISE EXCEPTION 'Nenhuma assinatura pendente para este documento' USING ERRCODE = 'P0002';
+    END IF;
+
+    -- Captura IP/UA
+    v_ip := inet_client_addr();
+    BEGIN
+        v_ua := current_setting('request.headers', true)::json ->> 'user-agent';
+    EXCEPTION WHEN OTHERS THEN
+        v_ua := NULL;
+    END;
+
+    -- Assina
+    UPDATE public.document_signatures
+       SET status         = 'assinado',
+           ip             = v_ip,
+           user_agent     = v_ua,
+           assinado_em    = now(),
+           hash_documento = COALESCE(p_hash_documento, hash_documento),
+           atualizado_em  = now()
+     WHERE id = v_sig.id
+     RETURNING * INTO v_sig;
+
+    -- Incrementa contador de usos do share_link
+    UPDATE public.document_share_links
+       SET usos = usos + 1
+     WHERE id = v_link.id;
+
+    RETURN v_sig;
+END;
+$$;
+
+COMMENT ON FUNCTION public.sign_document_by_token(text, uuid, text) IS
+    'Assinatura via share link público. SECURITY DEFINER — valida token, captura IP/UA, incrementa usos. p_signature_id é opcional pra desambiguar multi-signatário.';
+
+GRANT EXECUTE ON FUNCTION public.sign_document_by_token(text, uuid, text) TO anon, authenticated;
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 3. get_signable_document_by_token
+-- ----------------------------------------------------------------------------
+-- View helper que retorna info do documento + signatários pendentes via token,
+-- sem assinar. Permite a página pública renderizar antes do click.
+-- SECURITY DEFINER porque share_link tem RLS pública mas documents+signatures
+-- têm RLS por owner/tenant.
+-- ──────────────────────────────────────────────────────────────────────────
+CREATE OR REPLACE FUNCTION public.get_signable_document_by_token(
+    p_token text
+) RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+    v_link public.document_share_links;
+    v_doc  public.documents;
+    v_sigs jsonb;
+BEGIN
+    IF p_token IS NULL OR length(p_token) < 32 THEN
+        RAISE EXCEPTION 'Token inválido' USING ERRCODE = '22023';
+    END IF;
+
+    SELECT * INTO v_link
+      FROM public.document_share_links
+     WHERE token = p_token
+       AND ativo = true
+       AND expira_em > now()
+       AND usos < usos_max
+     LIMIT 1;
+
+    IF v_link.id IS NULL THEN
+        RETURN jsonb_build_object('valid', false, 'error', 'expired_or_invalid');
+    END IF;
+
+    SELECT * INTO v_doc
+      FROM public.documents
+     WHERE id = v_link.documento_id
+       AND deleted_at IS NULL
+     LIMIT 1;
+
+    IF v_doc.id IS NULL THEN
+        RETURN jsonb_build_object('valid', false, 'error', 'document_not_found');
+    END IF;
+
+    SELECT jsonb_agg(
+        jsonb_build_object(
+            'id', s.id,
+            'signatario_tipo', s.signatario_tipo,
+            'signatario_nome', s.signatario_nome,
+            'signatario_email', s.signatario_email,
+            'ordem', s.ordem,
+            'status', s.status,
+            'assinado_em', s.assinado_em
+        ) ORDER BY s.ordem
+    ) INTO v_sigs
+      FROM public.document_signatures s
+     WHERE s.documento_id = v_doc.id;
+
+    RETURN jsonb_build_object(
+        'valid', true,
+        'document', jsonb_build_object(
+            'id', v_doc.id,
+            'nome_original', v_doc.nome_original,
+            'mime_type', v_doc.mime_type,
+            'tamanho_bytes', v_doc.tamanho_bytes,
+            'bucket_path', v_doc.bucket_path,
+            'storage_bucket', v_doc.storage_bucket,
+            'tipo_documento', v_doc.tipo_documento
+        ),
+        'signatures', COALESCE(v_sigs, '[]'::jsonb),
+        'expira_em', v_link.expira_em,
+        'usos_restantes', v_link.usos_max - v_link.usos
+    );
+END;
+$$;
+
+COMMENT ON FUNCTION public.get_signable_document_by_token(text) IS
+    'Retorna documento + signatários pendentes via token. Usado pela página pública antes de assinar.';
+
+GRANT EXECUTE ON FUNCTION public.get_signable_document_by_token(text) TO anon, authenticated;
+
+COMMIT;

database-novo/migrations/20260521000007_list_my_signatures_rpc.sql

@@ -0,0 +1,102 @@
+-- ============================================================================
+-- Compliance CFP #7 — RPC list_my_signatures (portal do paciente)
+-- ----------------------------------------------------------------------------
+-- Retorna as solicitações de assinatura do paciente logado (auth.uid()
+-- associado a patients.user_id). SECURITY DEFINER pra bypassar a RLS de
+-- document_signatures (que hoje só libera pra tenant_members).
+--
+-- Cada item já vem com o share_link.token associado, pra que o portal
+-- aponte direto pra /shared/document/:token onde o usuário vai assinar.
+-- O link público é gerado quando o terapeuta solicita a assinatura.
+-- ============================================================================
+
+BEGIN;
+
+CREATE OR REPLACE FUNCTION public.list_my_signatures(
+    p_status text[] DEFAULT NULL
+) RETURNS TABLE (
+    signature_id    uuid,
+    documento_id    uuid,
+    tenant_id       uuid,
+    signatario_tipo text,
+    status          text,
+    ordem           smallint,
+    assinado_em     timestamptz,
+    criado_em       timestamptz,
+    -- Documento
+    nome_original   text,
+    tipo_documento  text,
+    mime_type       text,
+    -- Share link (primeiro válido encontrado pro doc)
+    share_token     text,
+    share_expira_em timestamptz
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+    v_uid uuid;
+BEGIN
+    v_uid := auth.uid();
+    IF v_uid IS NULL THEN
+        RAISE EXCEPTION 'Sessão inválida' USING ERRCODE = '28000';
+    END IF;
+
+    RETURN QUERY
+    SELECT
+        s.id                      AS signature_id,
+        s.documento_id            AS documento_id,
+        s.tenant_id               AS tenant_id,
+        s.signatario_tipo         AS signatario_tipo,
+        s.status                  AS status,
+        s.ordem                   AS ordem,
+        s.assinado_em             AS assinado_em,
+        s.criado_em               AS criado_em,
+        d.nome_original           AS nome_original,
+        d.tipo_documento          AS tipo_documento,
+        d.mime_type               AS mime_type,
+        sl.token                  AS share_token,
+        sl.expira_em              AS share_expira_em
+    FROM public.document_signatures s
+    JOIN public.documents d ON d.id = s.documento_id AND d.deleted_at IS NULL
+    LEFT JOIN LATERAL (
+        SELECT token, expira_em
+        FROM public.document_share_links
+        WHERE documento_id = d.id
+          AND ativo = true
+          AND expira_em > now()
+          AND usos < usos_max
+        ORDER BY criado_em DESC
+        LIMIT 1
+    ) sl ON true
+    WHERE (
+        -- signatario_id direto (quando registrado)
+        s.signatario_id = v_uid
+        OR
+        -- Fallback: paciente pelo email (quando signatario_id veio NULL)
+        s.signatario_email = (SELECT email FROM auth.users WHERE id = v_uid)
+        OR
+        -- Fallback: paciente pelo patient_id (documents.patient_id -> patients.user_id)
+        d.patient_id IN (SELECT p.id FROM public.patients p WHERE p.user_id = v_uid)
+    )
+    AND (p_status IS NULL OR s.status = ANY (p_status))
+    ORDER BY
+        CASE s.status
+            WHEN 'pendente' THEN 0
+            WHEN 'enviado'  THEN 1
+            WHEN 'assinado' THEN 2
+            WHEN 'recusado' THEN 3
+            WHEN 'expirado' THEN 4
+            ELSE 99
+        END,
+        s.criado_em DESC;
+END;
+$$;
+
+COMMENT ON FUNCTION public.list_my_signatures(text[]) IS
+    'Lista signatures do paciente logado (auth.uid()) cruzando por signatario_id, email ou patient.user_id. Inclui share_token pra link de assinatura.';
+
+GRANT EXECUTE ON FUNCTION public.list_my_signatures(text[]) TO authenticated;
+
+COMMIT;

database-novo/migrations/20260521000008_recibo_uses_terapeuta_registro.sql

@@ -0,0 +1,35 @@
+-- ============================================================================
+-- ROADMAP #1.4 #14 — Recibo profissional usa terapeuta_registro genérico
+-- ----------------------------------------------------------------------------
+-- O template recibo_pagamento (seed_015) usa "Psicólogo(a) — CRP {{terapeuta_crp}}".
+-- Como agora suportamos múltiplos conselhos (CRP/CRM/CRFa/CREFITO/CRESS/CRN/RMS)
+-- via #5 (migration 20260521000003), o recibo precisa ser CFP-agnóstico.
+--
+-- Esta migration substitui no recibo_pagamento:
+--   "Psicólogo(a) — CRP {{terapeuta_crp}}"  →  "{{terapeuta_registro}}"
+-- e atualiza variaveis[] removendo terapeuta_crp + adicionando terapeuta_registro.
+--
+-- {{terapeuta_registro}} é auto-formatado server-side como "CRP 12345/SP",
+-- "CRM 12345/SP" etc, então não precisa de "Psicólogo(a) —" hardcoded.
+-- ============================================================================
+
+BEGIN;
+
+UPDATE public.document_templates
+SET corpo_html = REPLACE(
+    corpo_html,
+    'Psicólogo(a) — CRP {{terapeuta_crp}}',
+    '{{terapeuta_registro}}'
+),
+variaveis = ARRAY(
+    SELECT DISTINCT v FROM (
+        SELECT unnest(variaveis) v
+        UNION ALL
+        SELECT 'terapeuta_registro'
+    ) sub
+    WHERE v <> 'terapeuta_crp'
+),
+updated_at = now()
+WHERE tipo = 'recibo_pagamento' AND is_global = true;
+
+COMMIT;

database-novo/migrations/20260521000009_profiles_registration_type_other.sql

@@ -0,0 +1,21 @@
+-- ============================================================================
+-- Compliance CFP #5 — campo livre quando tipo de registro = 'outro'
+-- ----------------------------------------------------------------------------
+-- Migration 20260521000003 adicionou professional_registration_type com CHECK
+-- limitado a 8 valores (CRP/CRM/CRFa/CREFITO/CRESS/CRN/RMS/outro). Quando o
+-- profissional escolhe 'outro', precisa informar qual conselho/instituição
+-- (ex: associações privadas, conselhos não-listados).
+--
+-- Esta migration adiciona professional_registration_type_other (text livre),
+-- que só é preenchido quando type = 'outro'.
+-- ============================================================================
+
+BEGIN;
+
+ALTER TABLE public.profiles
+    ADD COLUMN IF NOT EXISTS professional_registration_type_other text;
+
+COMMENT ON COLUMN public.profiles.professional_registration_type_other IS
+    'Nome livre do conselho/instituição quando professional_registration_type = ''outro''. Aparece em recibos/laudos no lugar do tipo padrão.';
+
+COMMIT;

database-novo/seeds/seed_040_clinical_note_templates.sql

@@ -0,0 +1,151 @@
+-- ============================================================================
+-- Seed dos templates do sistema de prontuário clínico
+-- ----------------------------------------------------------------------------
+-- Templates is_system=true, sem tenant_id, sem owner_id.
+-- Cobrem os 4 tipos mais comuns de nota clínica em psicologia:
+--   • Anamnese padrão CFP-style
+--   • Evolução: SOAP / DAP / BIRP
+--   • Plano terapêutico padrão
+--
+-- structure jsonb segue schema:
+--   [
+--     { key, label, type, required?, hint?, options? },
+--     ...
+--   ]
+-- type: 'text' | 'textarea' | 'select' | 'date' | 'multiselect'
+-- ============================================================================
+
+BEGIN;
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 1. Anamnese padrão (CFP)
+-- ──────────────────────────────────────────────────────────────────────────
+INSERT INTO public.clinical_note_templates (
+    key, name, note_type, description, structure, is_system, is_global, active
+) VALUES (
+    'anamnese_padrao',
+    'Anamnese Padrão',
+    'anamnese',
+    'Estrutura padrão de anamnese clínica em psicologia. Pode ser preenchida em 1-3 sessões iniciais.',
+    '[
+        {"key": "queixa_principal", "label": "Queixa principal", "type": "textarea", "required": true, "hint": "O que trouxe o paciente à terapia"},
+        {"key": "historia_queixa", "label": "História da queixa", "type": "textarea", "hint": "Quando começou, evolução, fatores agravantes/atenuantes"},
+        {"key": "historia_vida", "label": "História de vida", "type": "textarea", "hint": "Infância, adolescência, eventos marcantes"},
+        {"key": "antecedentes_psicologicos", "label": "Antecedentes psicológicos", "type": "textarea", "hint": "Tratamentos anteriores, medicações, internações"},
+        {"key": "antecedentes_medicos", "label": "Antecedentes médicos", "type": "textarea", "hint": "Doenças, cirurgias, medicações em uso"},
+        {"key": "antecedentes_familiares", "label": "Antecedentes familiares", "type": "textarea", "hint": "Histórico familiar de transtornos psicológicos/psiquiátricos"},
+        {"key": "vida_atual_relacionamentos", "label": "Relacionamentos atuais", "type": "textarea"},
+        {"key": "vida_atual_trabalho_estudo", "label": "Trabalho / estudo atual", "type": "textarea"},
+        {"key": "hipoteses_iniciais", "label": "Hipóteses iniciais", "type": "textarea", "hint": "Hipóteses do terapeuta — não compartilhar com paciente"},
+        {"key": "plano_inicial", "label": "Plano terapêutico inicial", "type": "textarea"}
+    ]'::jsonb,
+    true,
+    true,
+    true
+);
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 2. Evolução SOAP (Subjective, Objective, Assessment, Plan)
+-- ──────────────────────────────────────────────────────────────────────────
+INSERT INTO public.clinical_note_templates (
+    key, name, note_type, description, structure, is_system, is_global, active
+) VALUES (
+    'soap',
+    'Evolução SOAP',
+    'evolucao_sessao',
+    'Padrão internacional: Subjetivo (relato do paciente), Objetivo (observações), Avaliação (análise), Plano (próximos passos).',
+    '[
+        {"key": "subjetivo", "label": "S — Subjetivo", "type": "textarea", "required": true, "hint": "O que o paciente relatou; humor; queixas verbalizadas"},
+        {"key": "objetivo", "label": "O — Objetivo", "type": "textarea", "hint": "Observações do terapeuta: comportamento, afeto, aparência, postura"},
+        {"key": "avaliacao", "label": "A — Avaliação", "type": "textarea", "required": true, "hint": "Análise clínica, hipóteses, evolução"},
+        {"key": "plano", "label": "P — Plano", "type": "textarea", "required": true, "hint": "Intervenções planejadas, tarefas, foco da próxima sessão"}
+    ]'::jsonb,
+    true,
+    true,
+    true
+);
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 3. Evolução DAP (Data, Assessment, Plan)
+-- ──────────────────────────────────────────────────────────────────────────
+INSERT INTO public.clinical_note_templates (
+    key, name, note_type, description, structure, is_system, is_global, active
+) VALUES (
+    'dap',
+    'Evolução DAP',
+    'evolucao_sessao',
+    'Mais conciso que SOAP: Dados (relato + observações), Avaliação, Plano.',
+    '[
+        {"key": "dados", "label": "D — Dados", "type": "textarea", "required": true, "hint": "Relato + observações em texto único"},
+        {"key": "avaliacao", "label": "A — Avaliação", "type": "textarea", "required": true},
+        {"key": "plano", "label": "P — Plano", "type": "textarea", "required": true}
+    ]'::jsonb,
+    true,
+    true,
+    true
+);
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 4. Evolução BIRP (Behavior, Intervention, Response, Plan)
+-- ──────────────────────────────────────────────────────────────────────────
+INSERT INTO public.clinical_note_templates (
+    key, name, note_type, description, structure, is_system, is_global, active
+) VALUES (
+    'birp',
+    'Evolução BIRP',
+    'evolucao_sessao',
+    'Foco em intervenção: Comportamento observado, Intervenção aplicada, Resposta do paciente, Plano.',
+    '[
+        {"key": "behavior", "label": "B — Comportamento", "type": "textarea", "required": true, "hint": "Comportamento/queixa observada na sessão"},
+        {"key": "intervention", "label": "I — Intervenção", "type": "textarea", "required": true, "hint": "Técnicas ou abordagens aplicadas pelo terapeuta"},
+        {"key": "response", "label": "R — Resposta", "type": "textarea", "required": true, "hint": "Como o paciente respondeu à intervenção"},
+        {"key": "plano", "label": "P — Plano", "type": "textarea", "required": true}
+    ]'::jsonb,
+    true,
+    true,
+    true
+);
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 5. Evolução livre (CFP-style — texto único)
+-- ──────────────────────────────────────────────────────────────────────────
+INSERT INTO public.clinical_note_templates (
+    key, name, note_type, description, structure, is_system, is_global, active
+) VALUES (
+    'evolucao_livre',
+    'Evolução Livre',
+    'evolucao_sessao',
+    'Texto único, sem estrutura — pra quem prefere prosa contínua estilo CFP tradicional.',
+    '[
+        {"key": "evolucao", "label": "Evolução", "type": "textarea", "required": true, "hint": "Texto único descrevendo a sessão"}
+    ]'::jsonb,
+    true,
+    true,
+    true
+);
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 6. Plano terapêutico padrão
+-- ──────────────────────────────────────────────────────────────────────────
+INSERT INTO public.clinical_note_templates (
+    key, name, note_type, description, structure, is_system, is_global, active
+) VALUES (
+    'plano_terapeutico_padrao',
+    'Plano Terapêutico Padrão',
+    'plano_terapeutico',
+    'Estrutura básica de plano: objetivos, estratégia, recursos, prazo estimado.',
+    '[
+        {"key": "objetivos_gerais", "label": "Objetivos gerais", "type": "textarea", "required": true, "hint": "O que o paciente quer alcançar"},
+        {"key": "objetivos_especificos", "label": "Objetivos específicos / metas", "type": "textarea", "hint": "Metas mensuráveis"},
+        {"key": "estrategia_terapeutica", "label": "Estratégia terapêutica", "type": "textarea", "required": true, "hint": "Abordagem teórica, técnicas previstas"},
+        {"key": "recursos_indicados", "label": "Recursos / intervenções indicadas", "type": "textarea"},
+        {"key": "duracao_estimada", "label": "Duração estimada", "type": "text", "hint": "Ex: 6 meses, indeterminado"},
+        {"key": "criterios_alta", "label": "Critérios de alta", "type": "textarea"},
+        {"key": "encaminhamentos", "label": "Encaminhamentos paralelos", "type": "textarea", "hint": "Psiquiatria, médico, outras especialidades"}
+    ]'::jsonb,
+    true,
+    true,
+    true
+);
+
+COMMIT;

database-novo/seeds/seed_050_specialties.sql

@@ -0,0 +1,57 @@
+-- ============================================================================
+-- Seed: Especialidades do sistema (ROADMAP item #9)
+-- ----------------------------------------------------------------------------
+-- Lista canônica de especialidades + abordagens psicológicas no Brasil.
+-- is_system=true; usuário escolhe múltiplas; 'outra' permite custom via
+-- profile_specialties.other_label.
+-- ============================================================================
+
+BEGIN;
+
+INSERT INTO public.specialties (key, name, category, is_system, active) VALUES
+    -- Especialidades CFP (psicologia)
+    ('psicologia_clinica',          'Psicologia Clínica',                       'psicologia', true, true),
+    ('psicologia_hospitalar',       'Psicologia Hospitalar',                    'psicologia', true, true),
+    ('neuropsicologia',             'Neuropsicologia',                          'psicologia', true, true),
+    ('psicologia_organizacional',   'Psicologia Organizacional e do Trabalho',  'psicologia', true, true),
+    ('psicologia_escolar',          'Psicologia Escolar e Educacional',         'psicologia', true, true),
+    ('psicologia_juridica',         'Psicologia Jurídica',                      'psicologia', true, true),
+    ('psicologia_esporte',          'Psicologia do Esporte',                    'psicologia', true, true),
+    ('psicologia_social',           'Psicologia Social',                        'psicologia', true, true),
+    ('psicologia_transito',         'Psicologia do Trânsito',                   'psicologia', true, true),
+
+    -- Abordagens teóricas
+    ('psicanalise',                 'Psicanálise',                              'abordagem',  true, true),
+    ('tcc',                         'Terapia Cognitivo-Comportamental (TCC)',   'abordagem',  true, true),
+    ('psicodrama',                  'Psicodrama',                               'abordagem',  true, true),
+    ('gestalt_terapia',             'Gestalt-terapia',                          'abordagem',  true, true),
+    ('analise_comportamento',       'Análise do Comportamento (ABA)',           'abordagem',  true, true),
+    ('humanista',                   'Abordagem Humanista (Rogers)',             'abordagem',  true, true),
+    ('sistemica_familiar',          'Terapia Sistêmica Familiar',               'abordagem',  true, true),
+    ('logoterapia',                 'Logoterapia (Frankl)',                     'abordagem',  true, true),
+    ('analitica_jung',              'Psicologia Analítica (Jung)',              'abordagem',  true, true),
+
+    -- Públicos
+    ('infantil',                    'Atendimento Infantil',                     'publico',    true, true),
+    ('adolescentes',                'Atendimento de Adolescentes',              'publico',    true, true),
+    ('casais',                      'Terapia de Casal',                         'publico',    true, true),
+    ('familia',                     'Terapia Familiar',                         'publico',    true, true),
+    ('grupos',                      'Atendimento de Grupos',                    'publico',    true, true),
+    ('idosos',                      'Atendimento de Idosos / Gerontologia',     'publico',    true, true),
+    ('lgbtqia',                     'Atendimento LGBTQIA+',                     'publico',    true, true),
+
+    -- Temas
+    ('ansiedade',                   'Transtornos de Ansiedade',                 'tema',       true, true),
+    ('depressao',                   'Depressão',                                'tema',       true, true),
+    ('tdah',                        'TDAH',                                     'tema',       true, true),
+    ('autismo',                     'Transtorno do Espectro Autista',           'tema',       true, true),
+    ('luto',                        'Luto e Perdas',                            'tema',       true, true),
+    ('dependencia_quimica',         'Dependência Química',                      'tema',       true, true),
+    ('transtornos_alimentares',     'Transtornos Alimentares',                  'tema',       true, true),
+    ('trauma',                      'Trauma e Estresse Pós-Traumático',         'tema',       true, true),
+
+    -- Catch-all
+    ('outra',                       'Outra',                                    'outro',      true, true)
+ON CONFLICT (key) DO NOTHING;
+
+COMMIT;

database-novo/seeds/seed_060_consent_forms_extra.sql

@@ -0,0 +1,74 @@
+-- ============================================================================
+-- Compliance CFP #6 — Consent forms extra (LGPD + Gravação) + LGPD amend
+-- ----------------------------------------------------------------------------
+-- Adiciona 2 templates globais novos exigidos pra completar a biblioteca de
+-- consent forms do ROADMAP item #1.2 #6:
+--   • termo_lgpd           — Consentimento LGPD (tratamento de dados pessoais)
+--   • autorizacao_gravacao — Autorização de gravação de sessão
+--
+-- Também atualiza o template tcle_online existente pra incluir cláusula
+-- explícita de LGPD (estava mencionando criptografia mas não a Lei 13.709/2018
+-- nem direitos do titular).
+--
+-- Pré-requisito: migration 20260521000005_document_templates_consent_types.sql
+-- já aplicada (adiciona 'termo_lgpd' e 'autorizacao_gravacao' ao CHECK).
+-- ============================================================================
+
+BEGIN;
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 1. Termo de Consentimento LGPD (tratamento de dados pessoais)
+-- ──────────────────────────────────────────────────────────────────────────
+INSERT INTO public.document_templates (
+    id, tenant_id, owner_id, nome_template, tipo, descricao,
+    corpo_html, cabecalho_html, rodape_html,
+    variaveis, is_global, ativo
+) VALUES (
+    gen_random_uuid(), NULL, NULL,
+    'Termo de Consentimento LGPD',
+    'termo_lgpd',
+    'Consentimento específico para tratamento de dados pessoais conforme Lei nº 13.709/2018 (LGPD).',
+    E'<h2 style="text-align:center; margin-bottom:30px;">TERMO DE CONSENTIMENTO PARA TRATAMENTO DE DADOS PESSOAIS</h2>\n\n<p>Em conformidade com a <strong>Lei Geral de Proteção de Dados Pessoais — Lei nº 13.709/2018 (LGPD)</strong>, eu, <strong>{{paciente_nome}}</strong>, CPF nº <strong>{{paciente_cpf}}</strong>, declaro ter sido informado(a) e <strong>consinto livremente</strong> com o tratamento dos meus dados pessoais nos termos abaixo.</p>\n\n<h3>1. Controlador dos dados</h3>\n<p><strong>{{terapeuta_nome}}</strong>, Psicólogo(a) — CRP <strong>{{terapeuta_crp}}</strong>, atuando em <strong>{{clinica_nome}}</strong>, com endereço em <strong>{{clinica_endereco}}</strong>, atua como controlador dos dados pessoais coletados.</p>\n\n<h3>2. Dados tratados</h3>\n<p>Serão coletados e tratados os seguintes dados:</p>\n<ul>\n  <li><strong>Identificação:</strong> nome, CPF, RG, data de nascimento, endereço, telefone, e-mail;</li>\n  <li><strong>Dados sensíveis de saúde:</strong> histórico clínico, hipóteses diagnósticas, evolução terapêutica, prescrições, encaminhamentos (Art. 11 LGPD);</li>\n  <li><strong>Dados de pagamento:</strong> valores, formas de pagamento, recibos emitidos;</li>\n  <li><strong>Registros de atendimento:</strong> data, horário, modalidade e duração das sessões.</li>\n</ul>\n\n<h3>3. Finalidade e base legal</h3>\n<p>Os dados serão utilizados exclusivamente para:</p>\n<ul>\n  <li><strong>Execução do contrato</strong> de prestação de serviços psicológicos (Art. 7º, V e Art. 11, II, "a" da LGPD);</li>\n  <li>Cumprimento de <strong>obrigações legais e regulatórias</strong> (Resoluções CFP, retenção de prontuário por 5 anos — Art. 1º Res. CFP 001/2009);</li>\n  <li>Proteção da <strong>vida e incolumidade física</strong> do titular ou de terceiros, quando necessário (Art. 11, II, "f" LGPD);</li>\n  <li>Emissão de documentos solicitados (recibos, atestados, declarações).</li>\n</ul>\n\n<h3>4. Compartilhamento</h3>\n<p>Os dados <strong>não serão compartilhados</strong> com terceiros, exceto:</p>\n<ul>\n  <li>Mediante <strong>autorização expressa</strong> do titular (ex: encaminhamentos);</li>\n  <li>Por <strong>determinação judicial</strong> ou requisição legal de autoridade competente;</li>\n  <li>Para <strong>processadores</strong> contratados (plataforma de prontuário eletrônico, serviços de armazenamento em nuvem), com cláusulas de confidencialidade e proteção equivalentes.</li>\n</ul>\n\n<h3>5. Armazenamento e retenção</h3>\n<p>Os dados serão mantidos pelo prazo mínimo de <strong>5 anos</strong> após o término do acompanhamento, conforme exigência do CFP (Resolução nº 001/2009), em ambiente eletrônico criptografado com controle de acesso restrito ao profissional responsável.</p>\n\n<h3>6. Direitos do titular (Art. 18 LGPD)</h3>\n<p>O(A) titular pode, a qualquer momento, solicitar ao controlador:</p>\n<ul>\n  <li>Confirmação da existência de tratamento;</li>\n  <li>Acesso aos seus dados;</li>\n  <li>Correção de dados incompletos, inexatos ou desatualizados;</li>\n  <li>Anonimização, bloqueio ou eliminação de dados desnecessários ou tratados em desconformidade;</li>\n  <li>Portabilidade dos dados;</li>\n  <li>Revogação deste consentimento, nos termos do §5º do Art. 8º (sem prejuízo do tratamento legalmente exigido).</li>\n</ul>\n\n<h3>7. Contato</h3>\n<p>Para exercer seus direitos ou esclarecer dúvidas: <strong>{{terapeuta_email}}</strong> · <strong>{{terapeuta_telefone}}</strong>.</p>\n\n<p style="margin-top:30px;">Declaro que <strong>li, compreendi e consinto</strong> livremente com o tratamento dos meus dados pessoais conforme descrito acima.</p>\n\n<p style="margin-top:20px;">{{cidade_estado}}, {{data_atual_extenso}}.</p>\n\n<div style="display:flex; justify-content:space-between; margin-top:80px;">\n  <div style="text-align:center; width:45%;">\n    <hr style="border:none; border-top:1px solid #333; margin-bottom:8px;" />\n    <strong>{{paciente_nome}}</strong><br/>\n    Titular dos dados — CPF: {{paciente_cpf}}\n  </div>\n  <div style="text-align:center; width:45%;">\n    <hr style="border:none; border-top:1px solid #333; margin-bottom:8px;" />\n    <strong>{{terapeuta_nome}}</strong><br/>\n    Controlador — CRP {{terapeuta_crp}}\n  </div>\n</div>',
+    E'<div style="text-align:center;">\n  <strong>{{clinica_nome}}</strong><br/>\n  <span style="font-size:10pt; color:#666;">{{clinica_endereco}}</span>\n</div>',
+    E'<div style="text-align:center; font-size:9pt; color:#999;">\n  Documento regido pela Lei nº 13.709/2018 (LGPD) e pelo Código de Ética Profissional do Psicólogo.\n</div>',
+    ARRAY['paciente_nome','paciente_cpf','terapeuta_nome','terapeuta_crp','terapeuta_email','terapeuta_telefone','cidade_estado','data_atual_extenso','clinica_nome','clinica_endereco'],
+    true, true
+);
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 2. Autorização para Gravação de Sessão
+-- ──────────────────────────────────────────────────────────────────────────
+INSERT INTO public.document_templates (
+    id, tenant_id, owner_id, nome_template, tipo, descricao,
+    corpo_html, cabecalho_html, rodape_html,
+    variaveis, is_global, ativo
+) VALUES (
+    gen_random_uuid(), NULL, NULL,
+    'Autorização para Gravação de Sessão',
+    'autorizacao_gravacao',
+    'Autorização específica do paciente para gravação de áudio/vídeo das sessões (supervisão, ensino, registro clínico).',
+    E'<h2 style="text-align:center; margin-bottom:30px;">AUTORIZAÇÃO PARA GRAVAÇÃO DE SESSÃO</h2>\n\n<p>Eu, <strong>{{paciente_nome}}</strong>, CPF nº <strong>{{paciente_cpf}}</strong>, declaro ter sido devidamente informado(a) pelo(a) psicólogo(a) <strong>{{terapeuta_nome}}</strong>, CRP <strong>{{terapeuta_crp}}</strong>, e <strong>AUTORIZO</strong> a gravação das sessões de atendimento psicológico nas condições abaixo.</p>\n\n<h3>1. Tipo de gravação</h3>\n<p>Modalidade autorizada: <strong>{{tipo_gravacao}}</strong> (áudio, vídeo ou ambos).</p>\n\n<h3>2. Finalidade</h3>\n<p>As gravações serão utilizadas exclusivamente para:</p>\n<ul>\n  <li><strong>{{finalidade_gravacao}}</strong></li>\n</ul>\n<p>Finalidades comuns: registro clínico para análise posterior do profissional; supervisão técnica com supervisor identificado; uso didático em formação (com anonimização); pesquisa científica (mediante consentimento adicional específico).</p>\n\n<h3>3. Compartilhamento</h3>\n<p>As gravações são <strong>confidenciais</strong>. Não serão compartilhadas com terceiros, exceto quando:</p>\n<ul>\n  <li>Houver autorização expressa e por escrito do(a) titular;</li>\n  <li>Para fins de supervisão técnica, com o(a) supervisor(a) identificado(a) — <strong>{{supervisor_nome}}</strong> (quando aplicável);</li>\n  <li>Anonimizadas, para fins didáticos ou de pesquisa (com novo consentimento específico).</li>\n</ul>\n\n<h3>4. Armazenamento e descarte</h3>\n<p>As gravações serão armazenadas em ambiente criptografado, com acesso restrito ao(à) profissional responsável, pelo prazo de <strong>{{prazo_retencao}}</strong>, após o qual serão definitivamente eliminadas, conforme a LGPD (Lei nº 13.709/2018).</p>\n\n<h3>5. Direitos do(a) paciente</h3>\n<ul>\n  <li>Revogar esta autorização a qualquer tempo, com efeito sobre gravações futuras;</li>\n  <li>Solicitar a eliminação imediata de gravações específicas;</li>\n  <li>Solicitar cópia da gravação para fins próprios;</li>\n  <li>Ser informado(a) sobre cada utilização (supervisão, pesquisa).</li>\n</ul>\n\n<h3>6. Considerações éticas</h3>\n<p>A presente autorização está em conformidade com o Código de Ética Profissional do Psicólogo, com a Resolução CFP nº 010/2005 (sigilo profissional) e com a Lei nº 13.709/2018 (LGPD). A negativa de gravação <strong>não prejudica</strong> o atendimento psicológico, que prosseguirá normalmente.</p>\n\n<p style="margin-top:30px;">Declaro que <strong>li, compreendi e autorizo</strong> a gravação das sessões nos termos acima.</p>\n\n<p style="margin-top:20px;">{{cidade_estado}}, {{data_atual_extenso}}.</p>\n\n<div style="display:flex; justify-content:space-between; margin-top:80px;">\n  <div style="text-align:center; width:45%;">\n    <hr style="border:none; border-top:1px solid #333; margin-bottom:8px;" />\n    <strong>{{paciente_nome}}</strong><br/>\n    CPF: {{paciente_cpf}}\n  </div>\n  <div style="text-align:center; width:45%;">\n    <hr style="border:none; border-top:1px solid #333; margin-bottom:8px;" />\n    <strong>{{terapeuta_nome}}</strong><br/>\n    Psicólogo(a) — CRP {{terapeuta_crp}}\n  </div>\n</div>',
+    E'<div style="text-align:center;">\n  <strong>{{clinica_nome}}</strong><br/>\n  <span style="font-size:10pt; color:#666;">{{clinica_endereco}}</span>\n</div>',
+    E'<div style="text-align:center; font-size:9pt; color:#999;">\n  Autorização regida pelo Código de Ética do Psicólogo (CFP 010/2005) e pela Lei nº 13.709/2018 (LGPD).\n</div>',
+    ARRAY['paciente_nome','paciente_cpf','terapeuta_nome','terapeuta_crp','tipo_gravacao','finalidade_gravacao','supervisor_nome','prazo_retencao','cidade_estado','data_atual_extenso','clinica_nome','clinica_endereco'],
+    true, true
+);
+
+-- ──────────────────────────────────────────────────────────────────────────
+-- 3. Amend tcle_online com cláusula LGPD explícita
+-- ----------------------------------------------------------------------------
+-- O template original (seed_015) menciona criptografia mas não cita a LGPD
+-- explicitamente nem os direitos do titular. Acrescenta uma seção 5.
+-- ──────────────────────────────────────────────────────────────────────────
+UPDATE public.document_templates
+SET corpo_html = REPLACE(
+    corpo_html,
+    '<h3>4. Limitações</h3>',
+    E'<h3>5. Proteção de Dados (LGPD)</h3>\n<p>O atendimento online é regido pela <strong>Lei Geral de Proteção de Dados — Lei nº 13.709/2018 (LGPD)</strong>. Você tem direito a (Art. 18 LGPD): confirmar a existência de tratamento dos seus dados; acessar seus dados; corrigir dados incompletos ou inexatos; solicitar eliminação dos dados após o término do tratamento (resguardados os prazos legais de retenção do CFP); e revogar este consentimento a qualquer momento. Para exercê-los, contate <strong>{{terapeuta_email}}</strong>.</p>\n\n<h3>6. Limitações</h3>'
+),
+variaveis = ARRAY['paciente_nome','paciente_cpf','plataforma_online','terapeuta_nome','terapeuta_crp','terapeuta_email','cidade_estado','data_atual_extenso','clinica_nome','clinica_endereco'],
+descricao = 'Consentimento específico para atendimento psicológico por meios tecnológicos (Resolução CFP nº 11/2018) + cláusula LGPD.',
+updated_at = now()
+WHERE tipo = 'tcle_online' AND is_global = true;
+
+COMMIT;

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-busca.sql

@@ -0,0 +1,168 @@
+-- Importação da doc Fase 1 (Busca global + Recently viewed)
+-- Gerado a partir de development/saas-docs/01-busca-global-melissa.json
+BEGIN;
+
+DO $IMPORT$
+DECLARE
+    v_doc_id uuid;
+BEGIN
+    -- 1) Cria a doc principal
+    INSERT INTO public.saas_docs (
+        titulo, conteudo, categoria, exibir_no_faq, tipo_acesso,
+        pagina_path, ordem, ativo, medias
+    ) VALUES (
+        'Busca global e Acessados recentemente',
+        $HTML$<h2>Busca global no Layout Melissa</h2>
+
+<p>A <strong>busca global</strong> é o atalho mais rápido para encontrar pacientes, sessões, documentos e cadastros recebidos sem precisar navegar pelos menus. Você acessa pelo <em>dock central</em> do Layout Melissa ou usando o atalho de teclado <kbd>Ctrl</kbd> + <kbd>K</kbd> (em qualquer página do Melissa).</p>
+
+<h3>1. Como abrir</h3>
+<p>Localize o campo de busca no dock central do Melissa. Ele aparece como um botão com o ícone de lupa e o placeholder <em>"Buscar paciente, agenda, atalho…"</em>, com o atalho <kbd>Ctrl K</kbd> indicado no canto direito.</p>
+
+<div style="border: 1px solid #cbd5e1; border-radius: 12px; padding: 0 14px; height: 44px; max-width: 480px; display: flex; align-items: center; gap: 10px; background: #1e2333; color: #cbd5e1; font-family: 'Segoe UI', sans-serif; margin: 12px 0;">
+  <i class="pi pi-search" style="font-size: 0.95rem;"></i>
+  <span style="flex: 1; font-size: 0.9rem;">Buscar paciente, agenda, atalho…</span>
+  <span style="font-size: 0.62rem; padding: 2px 7px; border-radius: 4px; background: rgba(255,255,255,0.1); border: 1px solid rgba(255,255,255,0.15); letter-spacing: 0.05em;">Ctrl K</span>
+</div>
+
+<p><strong>Três jeitos de abrir:</strong></p>
+<ul>
+  <li>Clicando no campo no dock central</li>
+  <li>Pressionando <kbd>Ctrl + K</kbd> (Windows/Linux) ou <kbd>⌘ + K</kbd> (Mac) em qualquer página</li>
+  <li>Pelo menu lateral, opção "Buscar" (quando disponível)</li>
+</ul>
+
+<h3>2. O Dialog Spotlight</h3>
+<p>Ao abrir, o sistema mostra um <strong>diálogo centralizado</strong> com o input grande no topo e os resultados em colunas abaixo. Isso é o padrão Spotlight (igual ao usado em macOS, Linear, GitHub, Slack).</p>
+
+<div style="background: var(--surface-card, #fff); border: 1px solid #e2e8f0; border-radius: 14px; max-width: 520px; box-shadow: 0 12px 32px rgba(0,0,0,0.15); overflow: hidden; margin: 12px 0; font-family: 'Segoe UI', sans-serif;">
+  <div style="padding: 14px 18px; border-bottom: 1px solid #e2e8f0; display: flex; align-items: center; gap: 12px;">
+    <i class="pi pi-search" style="color: #64748b;"></i>
+    <span style="flex: 1; color: #94a3b8; font-size: 1.05rem;">Buscar paciente, agenda, atalho…</span>
+    <span style="font-size: 0.65rem; padding: 2px 8px; border-radius: 4px; background: #f1f5f9; border: 1px solid #e2e8f0; color: #64748b;">Esc</span>
+  </div>
+  <div style="padding: 6px;">
+    <div style="text-transform: uppercase; letter-spacing: 0.18em; color: #64748b; font-size: 0.62rem; font-weight: 700; padding: 8px 10px 4px; opacity: 0.75;">Acessados recentemente</div>
+    <div style="display: flex; align-items: center; gap: 10px; padding: 9px 10px; border-radius: 8px;">
+      <span style="width: 32px; height: 32px; display: grid; place-items: center; border-radius: 7px; background: rgba(244,114,182,0.18); color: #ec4899; font-size: 0.9rem;">
+        <i class="pi pi-user"></i>
+      </span>
+      <div style="flex: 1;">
+        <div style="font-size: 0.88rem; font-weight: 500;">André Green</div>
+        <div style="font-size: 0.74rem; color: #64748b;">andre@email.com</div>
+      </div>
+      <i class="pi pi-arrow-right" style="color: #94a3b8; font-size: 0.75rem;"></i>
+    </div>
+  </div>
+</div>
+
+<h3>3. Onde a busca procura</h3>
+<p>Digitando <strong>pelo menos 2 caracteres</strong>, o sistema dispara uma busca completa em 5 categorias:</p>
+<ul>
+  <li><strong style="color: #ec4899;">Pacientes</strong> — por nome completo, e-mail, telefone ou CPF</li>
+  <li><strong style="color: #6366f1;">Sessões</strong> — por título ou nome do paciente, em qualquer data</li>
+  <li><strong style="color: #0ea5e9;">Documentos</strong> — por nome do arquivo ou descrição</li>
+  <li><strong style="color: #f97316;">Cadastros recebidos</strong> — solicitações de novos pacientes pendentes</li>
+  <li><strong>Atalhos</strong> — ações rápidas como "Agenda", "Financeiro", etc.</li>
+</ul>
+
+<p>Cada categoria aparece com um <strong>ícone colorido distinto</strong> para facilitar a leitura visual. Os resultados são limitados aos 6 mais relevantes por categoria.</p>
+
+<h3>4. Como navegar nos resultados</h3>
+<p>Você pode usar o mouse ou o teclado:</p>
+<ul>
+  <li><kbd>↑</kbd> / <kbd>↓</kbd> — navegar entre os resultados</li>
+  <li><kbd>Enter</kbd> — abrir o item selecionado</li>
+  <li><kbd>Esc</kbd> — fechar o diálogo</li>
+  <li><kbd>Clique no backdrop</kbd> — fecha também</li>
+</ul>
+
+<h3>5. Acessados recentemente</h3>
+<p>Quando você abre a busca <strong>sem digitar nada</strong>, a primeira seção mostra <strong>"Acessados recentemente"</strong> — os últimos 5 pacientes que você visitou (em qualquer dispositivo deste navegador).</p>
+
+<div style="background: #f8fafc; border: 1px solid #e2e8f0; border-radius: 8px; padding: 12px 16px; margin: 12px 0; font-size: 0.88rem; color: #475569;">
+  <strong>💡 Dica:</strong> Use Ctrl+K + Enter para reabrir o último paciente acessado em 2 segundos.
+</div>
+
+<p>Esses 5 pacientes ficam salvos no seu navegador (não no banco de dados), então:</p>
+<ul>
+  <li>São <strong>privados</strong> — outros usuários não veem</li>
+  <li>São <strong>por navegador</strong> — se trocar do Chrome pro Firefox, a lista recomeça</li>
+  <li><strong>Persistem</strong> após fechar o navegador (localStorage)</li>
+  <li>Auto-rotacionam: ao acessar o 6º paciente, o mais antigo sai</li>
+</ul>
+
+<h3>6. Clique nos resultados</h3>
+<p>Ao clicar:</p>
+<ul>
+  <li><strong>Paciente</strong> → abre o prontuário (<code>/melissa/paciente?id=…</code>)</li>
+  <li><strong>Sessão</strong> → abre o evento na agenda</li>
+  <li><strong>Documento</strong> → abre o prontuário do paciente na aba Documentos</li>
+  <li><strong>Cadastro recebido</strong> → vai pra lista de Cadastros recebidos</li>
+  <li><strong>Atalho</strong> → navega pra seção (Agenda, Financeiro, etc.)</li>
+</ul>
+
+<h3>7. Tema claro × escuro</h3>
+<p>O Dialog adapta automaticamente as cores conforme o tema escolhido em <strong>Meu Perfil → Preferências</strong>. Texto, fundos e bordas seguem as configurações do sistema. Apenas os ícones por categoria (paciente rosa, sessão índigo, documento azul, cadastro laranja) mantêm a mesma cor para preservar a identificação visual rápida.</p>
+
+<h3>⚠️ Notas pro desenvolvedor</h3>
+<p>Atualmente o componente <code>MelissaBusca.vue</code> <strong>não tem atributos <code>id</code></strong> em seus elementos. Para o sistema de highlight da ajuda funcionar (links <code>data-highlight</code>), sugere-se adicionar:</p>
+<ul>
+  <li><code>id="melissa-busca-trigger"</code> no botão de trigger no dock</li>
+  <li><code>id="melissa-busca-dialog"</code> no Dialog</li>
+  <li><code>id="melissa-busca-input"</code> no input dentro do Dialog</li>
+  <li><code>id="melissa-busca-recent"</code> no grupo de Acessados recentemente</li>
+</ul>$HTML$,
+        'Navegação',
+        true,
+        'usuario',
+        '/melissa',
+        1,
+        true,
+        '[{"tipo": "imagem", "url": ""}]'::jsonb
+    )
+    RETURNING id INTO v_doc_id;
+
+    -- 2) Insere os 12 FAQ items vinculados
+    INSERT INTO public.saas_faq_itens (doc_id, pergunta, resposta, ordem, ativo) VALUES
+    (v_doc_id, 'Como abrir a busca rapidamente?',
+     $FAQ$Use o atalho <kbd>Ctrl + K</kbd> (Windows/Linux) ou <kbd>⌘ + K</kbd> (Mac) em qualquer página do Melissa. Você também pode clicar diretamente no campo de busca no dock central.$FAQ$, 0, true),
+
+    (v_doc_id, 'Posso buscar paciente por telefone ou CPF?',
+     $FAQ$Sim. A busca de pacientes encontra pelo <strong>nome completo, e-mail, telefone ou CPF</strong>. Digite pelo menos 2 caracteres e aguarde os resultados.$FAQ$, 1, true),
+
+    (v_doc_id, 'O que aparece em "Acessados recentemente"?',
+     $FAQ$Os últimos 5 pacientes que você abriu pelo prontuário, em ordem do mais recente pro mais antigo. A lista aparece quando você abre a busca <strong>sem digitar nada</strong>.$FAQ$, 2, true),
+
+    (v_doc_id, 'Outros usuários veem meus "Acessados recentemente"?',
+     $FAQ$Não. A lista é <strong>privada e local</strong> — fica salva apenas no seu navegador atual (localStorage). Se você logar em outro navegador ou computador, a lista começa vazia naquele dispositivo.$FAQ$, 3, true),
+
+    (v_doc_id, 'Quantos caracteres preciso digitar pra começar a buscar?',
+     $FAQ$<strong>Pelo menos 2</strong>. Buscas de 1 caractere são muito amplas e não disparam pesquisa. A partir de 2 caracteres, o sistema aguarda 200ms (tempo de digitação) antes de consultar o banco — assim você não dispara dezenas de buscas digitando rápido.$FAQ$, 4, true),
+
+    (v_doc_id, 'Por que minha busca não retorna nada?',
+     $FAQ$Verifique: (1) digitou pelo menos 2 caracteres; (2) o termo está sem erros graves de digitação (a busca tolera pequenas variações via similarity); (3) o paciente/sessão realmente existe no seu cadastro. Se persistir, faça uma busca mais ampla — ex: apenas o primeiro nome.$FAQ$, 5, true),
+
+    (v_doc_id, 'O que cada cor de ícone significa?',
+     $FAQ$Cada categoria tem uma cor própria: <strong style="color: #ec4899;">Rosa</strong> = Paciente, <strong style="color: #6366f1;">Índigo</strong> = Sessão da agenda, <strong style="color: #0ea5e9;">Azul</strong> = Documento, <strong style="color: #f97316;">Laranja</strong> = Cadastro recebido pendente. Atalhos vêm em cinza neutro.$FAQ$, 6, true),
+
+    (v_doc_id, 'Como navegar pelos resultados sem usar o mouse?',
+     $FAQ$Use as setas do teclado <kbd>↑</kbd> e <kbd>↓</kbd> para navegar entre os itens e <kbd>Enter</kbd> para abrir o selecionado. Pra fechar sem selecionar, use <kbd>Esc</kbd>.$FAQ$, 7, true),
+
+    (v_doc_id, 'Posso buscar documentos pelo nome do paciente?',
+     $FAQ$Sim. A busca de documentos cruza pelo nome do arquivo, descrição e <strong>nome do paciente vinculado</strong>. Ao clicar num resultado de documento, você é levado direto pra aba Documentos do prontuário daquele paciente.$FAQ$, 8, true),
+
+    (v_doc_id, 'Como limpar a lista de "Acessados recentemente"?',
+     $FAQ$Hoje não há um botão na interface — a lista é gerenciada automaticamente (limite de 5, mais antigo cai quando você acessa um novo). Pra limpar manualmente, você pode apagar os dados do site no seu navegador (Configurações → Privacidade → Limpar dados de navegação → escopo "localStorage").$FAQ$, 9, true),
+
+    (v_doc_id, 'A busca encontra sessões antigas ou só as de hoje?',
+     $FAQ$Encontra sessões de <strong>qualquer data</strong> — passadas e futuras. O grupo "Agenda de hoje" mostra apenas as do dia atual (preview rápido); o grupo "Sessões" inclui todas as outras encontradas no banco. Cada item mostra a data e horário da sessão.$FAQ$, 10, true),
+
+    (v_doc_id, 'Os atalhos (Agenda, Financeiro, etc.) sempre aparecem?',
+     $FAQ$Sim. Quando o campo está vazio, mostramos 4 atalhos padrão. Conforme você digita, os atalhos que combinam com sua busca permanecem visíveis (junto com os resultados do banco).$FAQ$, 11, true);
+
+    RAISE NOTICE 'Doc criada: id=%, faq_itens=12', v_doc_id;
+END;
+$IMPORT$;
+
+COMMIT;

database-novo/tmp/import-doc-cronometro.sql

@@ -0,0 +1,168 @@
+-- Importacao da doc do Cronometro de sessao (Melissa)
+-- Gerado a partir de development/saas-docs/02-cronometro-melissa.json
+BEGIN;
+
+DO $IMPORT$
+DECLARE
+    v_doc_id uuid;
+BEGIN
+    -- 1) Cria a doc principal
+    INSERT INTO public.saas_docs (
+        titulo, conteudo, categoria, exibir_no_faq, tipo_acesso,
+        pagina_path, ordem, ativo, medias
+    ) VALUES (
+        'Cronômetro de sessão',
+        $HTML$<h2>Cronômetro de sessão</h2>
+
+<p>O <strong>cronômetro de sessão</strong> acompanha o tempo decorrido durante o atendimento e é integrado com a agenda. Quando aberto a partir de uma sessão em andamento, ele já vem com o paciente pré-selecionado e dispara automaticamente.</p>
+
+<h3>1. Três jeitos de abrir</h3>
+<ul>
+  <li>Pelo botão <strong>⏱</strong> ao lado do relógio gigante do dashboard (abre vazio, escolha o paciente — ou deixe como atividade livre)</li>
+  <li>Pelo botão <strong>⏱</strong> que aparece sobre os cards de sessão em curso na timeline horizontal/vertical do dashboard</li>
+  <li>Pelo CTA <strong>"Iniciar cronômetro"</strong> no card <em>"Próximo paciente"</em> quando a sessão está em andamento</li>
+</ul>
+<p>Os dois últimos pré-selecionam o paciente da sessão e disparam o timer automaticamente.</p>
+
+<h3>2. Sessão em curso na timeline</h3>
+<p>Quando uma sessão entra em andamento (horário atual entre início e fim do evento), aparece um ícone <strong>⏱</strong> pulsando no canto superior direito do card do evento. O pulso é sutil, em verde — só pra sinalizar que dá pra cronometrar dali.</p>
+
+<div style="display: flex; align-items: center; gap: 8px; background: #6366f1; color: white; padding: 4px 10px; border-radius: 4px; max-width: 320px; position: relative; margin: 12px 0; font-family: 'Segoe UI', sans-serif;">
+  <span style="font-size: 0.85rem; font-weight: 600;">11:00 – Larissa Almeida</span>
+  <span style="position: absolute; top: 3px; right: 3px; width: 22px; height: 22px; display: grid; place-items: center; background: rgba(0,0,0,0.45); border: 1px solid rgba(255,255,255,0.4); border-radius: 999px; color: white; box-shadow: 0 0 0 4px rgba(16,185,129,0.25);">
+    <i class="pi pi-stopwatch" style="font-size: 0.7rem;"></i>
+  </span>
+</div>
+
+<p>Clicar no <strong>⏱</strong> <strong>não abre o evento</strong> — abre o cronômetro pré-configurado pra essa sessão.</p>
+
+<h3>3. Programado vs tempo real</h3>
+<p>Quando aberto via timeline ou card "Próximo paciente", o cronômetro mostra o <strong>horário programado original da sessão</strong> sob o select de paciente. Se você abriu depois do horário previsto, aparece um badge laranja <strong>"atrasada X min"</strong>.</p>
+
+<div style="background: rgba(15,23,42,0.85); color: #cbd5e1; padding: 14px; border-radius: 10px; max-width: 360px; font-family: 'Segoe UI', sans-serif; margin: 12px 0;">
+  <label style="font-size: 0.62rem; text-transform: uppercase; letter-spacing: 0.15em; color: rgba(255,255,255,0.5); display: block; margin-bottom: 8px;">Paciente / atividade</label>
+  <div style="background: rgba(255,255,255,0.06); border: 1px solid rgba(255,255,255,0.15); padding: 9px 14px; border-radius: 10px; font-size: 0.9rem;">Larissa Almeida</div>
+  <div style="display: flex; align-items: center; gap: 6px; margin-top: 8px; padding: 4px 0;">
+    <i class="pi pi-calendar" style="font-size: 0.7rem; color: rgba(255,255,255,0.55);"></i>
+    <span style="font-size: 0.78rem; color: rgba(255,255,255,0.7);">Programado: 11:00 – 11:50</span>
+    <span style="margin-left: 4px; padding: 1px 8px; border-radius: 999px; background: rgba(251,146,60,0.18); color: rgb(253,186,116); font-size: 0.7rem; font-weight: 500; border: 1px solid rgba(251,146,60,0.35);">atrasada 8 min</span>
+  </div>
+</div>
+
+<p>⚠️ <strong>O cronômetro NÃO desconta o tempo de atraso automaticamente.</strong> Ele conta a duração configurada cheia (50min padrão) a partir do clique. A info "atrasada" é só pra você decidir se quer encerrar antes ou estender.</p>
+
+<h3>4. Anatomia do dialog</h3>
+<ul>
+  <li><strong>Header:</strong> rótulo "Cronômetro" + status (<em>Pronto</em> / <em>Em andamento</em> / <em>Pausado</em>)</li>
+  <li><strong>Botão Minimizar:</strong> recolhe pro chip no dock</li>
+  <li><strong>Botão X (Encerrar sem salvar):</strong> descarta a sessão (com confirmação se houver atividade)</li>
+  <li><strong>Select de paciente:</strong> pode trocar manualmente; opção <em>"— Atividade livre"</em> pra usos sem paciente</li>
+  <li><strong>Programado + badge de atraso:</strong> só aparece quando aberto via evento da agenda</li>
+  <li><strong>Display gigante mm:ss:</strong> vira vermelho quando passa do tempo planejado (mostra <code>-mm:ss</code>)</li>
+  <li><strong>±5 min:</strong> estende ou encurta o tempo configurado a qualquer momento</li>
+  <li><strong>Botão grande inferior:</strong> ▶ Começar / ⏹ Parar</li>
+</ul>
+
+<h3>5. Minimizar e restaurar</h3>
+<p>Click no <strong>botão minimizar</strong> (ou click fora do dialog) <strong>recolhe</strong> o cronômetro pra um <strong>chip flutuante no dock</strong> (canto inferior esquerdo, ao lado do ψ). O timer continua rodando em background. Click no chip restaura o dialog em tela cheia.</p>
+
+<div style="display: inline-flex; align-items: center; gap: 10px; padding: 8px 14px 8px 12px; background: rgba(15,23,42,0.85); border: 1px solid rgba(255,255,255,0.18); border-radius: 999px; color: #cbd5e1; font-family: 'Segoe UI', sans-serif; box-shadow: 0 8px 24px rgba(0,0,0,0.25); margin: 12px 0;">
+  <i class="pi pi-stopwatch" style="font-size: 0.85rem; color: #6ee7b7;"></i>
+  <span style="font-variant-numeric: tabular-nums; font-weight: 500; font-size: 0.85rem;">48:13</span>
+  <span style="font-size: 0.72rem; color: rgba(255,255,255,0.6); padding-left: 6px; border-left: 1px solid rgba(255,255,255,0.18);">Larissa Almeida</span>
+</div>
+
+<p>Em mobile (telas &lt;768px), o chip mostra só o ícone + tempo — sem o nome do paciente — pra caber no dock estreito. O nome continua acessível ao restaurar.</p>
+
+<h3>6. Parar (salva) vs Fechar (descarta)</h3>
+<p>Duas ações diferentes pra terminar — a escolha importa:</p>
+<ul>
+  <li><strong>⏹ Parar</strong> (botão grande inferior): encerra a contagem e <strong>SALVA o tempo decorrido no banco</strong> (evento <code>session-end</code> com elapsed em segundos). Caminho normal de fim de sessão.</li>
+  <li><strong>X Encerrar sem salvar</strong> (header): descarta. Pede <strong>confirmação</strong> se há sessão em andamento ou tempo decorrido — não fecha por acidente. Se o cronômetro está limpo (não iniciado, sem tempo), fecha direto.</li>
+  <li><strong>Click fora / Minimizar</strong>: NÃO encerra. Esconde o dialog e mantém o timer rodando como chip no dock.</li>
+</ul>
+
+<h3>7. Quando o tempo acaba</h3>
+<p>Aos <strong>50 minutos cronometrados</strong> (ou conforme configurado), o sistema toca um <strong>som curto</strong> uma única vez. O display vira <strong>vermelho</strong> e continua contando em negativo (mostra <code>-mm:ss</code>). <strong>Não há corte automático</strong> — você decide quando parar.</p>
+
+<p>O toque pode ser trocado em <strong>Configurações → Cronômetro → Som de término</strong>. Opções: sino, gong, soft, silêncio.</p>
+
+<h3>8. Persistência (reload-safe)</h3>
+<p>Se você fechar a aba ou recarregar o navegador com cronômetro ativo, ao voltar o sistema <strong>retoma exatamente de onde parou</strong> — descontando automaticamente o tempo passado entre fechar e abrir. O snapshot fica no <code>localStorage</code> do navegador, atualizado a cada mudança de estado.</p>
+
+<p><strong>Limite de segurança:</strong> se passar de 24h sem voltar à aba, o restore não acumula o tempo perdido (proteção contra mudanças do relógio do sistema).</p>
+
+<h3>9. Cronômetro já ativo</h3>
+<p>Existe <strong>um cronômetro por vez</strong>. Se você clicar no <strong>⏱</strong> de outra sessão enquanto há cronômetro rodando, o sistema mostra um toast <strong>"Cronômetro já ativo"</strong> com o nome do paciente atual — <strong>e não troca</strong>. Pare o cronômetro atual antes de iniciar outro.</p>
+
+<h3>10. Atividade livre (sem paciente)</h3>
+<p>Você pode abrir o cronômetro sem paciente (botão ⏱ do dashboard, sem clicar em evento específico) e selecionar <em>"— Atividade livre (sem paciente)"</em> no dropdown. Útil pra:</p>
+<ul>
+  <li>Pausa cronometrada</li>
+  <li>Pomodoro pessoal</li>
+  <li>Atendimento informal não cadastrado</li>
+</ul>
+<p>Atividade livre <strong>não emite session-end</strong> ao parar (não há paciente pra vincular o tempo).</p>
+
+<h3>⚠️ Notas pro desenvolvedor</h3>
+<p>Atualmente o componente <code>MelissaCronometro.vue</code> <strong>não tem atributos <code>id</code></strong> em seus elementos. Para o sistema de highlight da ajuda funcionar (links <code>data-highlight</code>), sugere-se adicionar:</p>
+<ul>
+  <li><code>id="crono-trigger-hero"</code> no botão ⏱ ao lado do relógio (<code>MelissaHeroClock.vue</code>)</li>
+  <li><code>id="crono-trigger-timeline"</code> nos botões ⏱ overlay (<code>MelissaTimelineHoje.vue</code>)</li>
+  <li><code>id="crono-dialog"</code> no panel principal (<code>.mc-panel</code>)</li>
+  <li><code>id="crono-stop-btn"</code> no botão Parar (caminho do salvamento)</li>
+  <li><code>id="crono-close-btn"</code> no X (caminho do descarte)</li>
+</ul>$HTML$,
+        'Sessão',
+        true,
+        'usuario',
+        '/melissa',
+        2,
+        true,
+        '[{"tipo": "imagem", "url": ""}]'::jsonb
+    )
+    RETURNING id INTO v_doc_id;
+
+    -- 2) Insere os 12 FAQ items vinculados
+    INSERT INTO public.saas_faq_itens (doc_id, pergunta, resposta, ordem, ativo) VALUES
+    (v_doc_id, 'Como começo o cronômetro da Larissa que chegou agora pra sessão?',
+     $FAQ$Quando o horário programado da Larissa estiver dentro da janela do evento (já começou na agenda), aparece um botão <strong>⏱</strong> pulsando em verde no canto superior direito do card da sessão na timeline. Clique nele — o cronômetro abre com a Larissa pré-selecionada e <strong>já começa a contar automaticamente</strong>. Alternativa: clique no botão <em>"Iniciar cronômetro"</em> no card "Próximo paciente" do dashboard (mesmo efeito).$FAQ$, 0, true),
+
+    (v_doc_id, 'O cronômetro continua se eu fechar a aba do navegador?',
+     $FAQ$<strong>Sim.</strong> O estado é salvo no <code>localStorage</code> a cada mudança (paciente, play, pause, ajustes). Ao reabrir a aba (ou recarregar), o cronômetro retoma do ponto correto — o tempo passado entre fechar e abrir é descontado automaticamente. Limite: se passar de 24h, o sistema não acumula esse tempo (proteção contra mudanças do relógio do sistema).$FAQ$, 1, true),
+
+    (v_doc_id, 'Cliquei no X com sessão rodando, perdi o tempo?',
+     $FAQ$Não, o sistema <strong>pede confirmação antes</strong>. Quando há sessão em andamento ou tempo decorrido sem salvar, aparece um diálogo <em>"Encerrar sessão sem salvar?"</em>. Você precisa clicar em <strong>"Encerrar sem salvar"</strong> (botão vermelho) pra confirmar o descarte. Se o cronômetro estiver limpo (não iniciado, sem tempo), o X fecha direto — não há nada pra preservar.$FAQ$, 2, true),
+
+    (v_doc_id, 'Posso ter dois cronômetros rodando ao mesmo tempo?',
+     $FAQ$Não. Existe <strong>um cronômetro por vez</strong>. Se você clicar no <strong>⏱</strong> de outra sessão enquanto já há um cronômetro ativo, o sistema mostra um toast <em>"Cronômetro já ativo — sessão de X em andamento"</em> e <strong>não troca</strong>. Pare ou descarte o atual antes de iniciar outro.$FAQ$, 3, true),
+
+    (v_doc_id, 'O que significa o badge laranja "atrasada 8 min"?',
+     $FAQ$Significa que <strong>o cronômetro foi aberto 8 minutos depois do horário programado</strong> da sessão na agenda. Por exemplo: sessão programada pra 11:00, você inicia o cronômetro às 11:08. O badge é apenas informativo — o cronômetro continua contando a duração configurada cheia (50min padrão) a partir do clique. Você decide se vai encerrar antes pra terminar no horário previsto ou deixar rodar pra dar a sessão completa.$FAQ$, 4, true),
+
+    (v_doc_id, 'O cronômetro desconta o tempo de atraso automaticamente?',
+     $FAQ$<strong>Não.</strong> A decisão fica com você. Cada clínica e cada terapeuta tem uma política diferente pra atraso (alguns dão sessão cheia, outros encerram no horário programado, outros estendem). O cronômetro mostra a info do atraso pra você decidir, mas conta sempre a duração configurada cheia a partir do clique.$FAQ$, 5, true),
+
+    (v_doc_id, 'Que som toca quando o tempo acaba?',
+     $FAQ$Por padrão, um <strong>som de sino curto</strong>, uma única vez. Você pode trocar em <strong>Configurações → Cronômetro → Som de término</strong>. Opções: sino, gong, soft, silêncio. O som toca <strong>exatamente na transição</strong> de tempo positivo pra zero/negativo — não repete. Depois disso o display continua contando em negativo (vermelho) até você parar.$FAQ$, 6, true),
+
+    (v_doc_id, 'Como adiciono mais tempo na sessão sem reiniciar?',
+     $FAQ$Use os botões <strong>+5 min</strong> e <strong>-5 min</strong> ao redor do display gigante. Funcionam a qualquer momento — antes, durante ou depois do tempo acabar. Cada clique soma ou desconta 5 minutos. Se o tempo já está negativo (passou do limite), +5min volta a contagem pra positivo.$FAQ$, 7, true),
+
+    (v_doc_id, 'Onde fica salvo o tempo final da sessão?',
+     $FAQ$Quando você clica em <strong>⏹ Parar</strong>, o tempo cronometrado é gravado no banco vinculado à sessão da agenda (na tabela <code>agenda_eventos</code>, campo de duração real). Esse caminho é o oficial — <strong>fechar pelo X descarta sem salvar</strong>. Sessões com menos de 5 segundos cronometrados são ignoradas (proteção contra start/stop acidentais).$FAQ$, 8, true),
+
+    (v_doc_id, 'Posso usar o cronômetro pra coisas que não são sessão de paciente?',
+     $FAQ$Sim. Selecione <em>"— Atividade livre (sem paciente)"</em> no dropdown de paciente. Útil pra pausa cronometrada, pomodoro pessoal, atendimento informal não cadastrado. Atividade livre <strong>não dispara session-end</strong> ao parar — não há paciente pra vincular o tempo no DB.$FAQ$, 9, true),
+
+    (v_doc_id, 'Como minimizo o cronômetro pra continuar trabalhando?',
+     $FAQ$Clique no botão <strong>minimizar</strong> no header (ícone <code>—</code>) ou simplesmente <strong>clique fora do dialog</strong>. O cronômetro vira um chip flutuante no dock (canto inferior esquerdo, ao lado do ψ) e continua contando em background. Pra restaurar: clique no chip. Em mobile, o chip mostra só ícone + tempo (sem nome) pra caber no dock estreito.$FAQ$, 10, true),
+
+    (v_doc_id, 'Como mudo o paciente no cronômetro já aberto?',
+     $FAQ$Basta clicar no <strong>select de paciente</strong> e escolher outro. A troca é imediata — não reinicia o tempo decorrido (a contagem continua igual). Útil quando você abriu o cronômetro no paciente errado e quer corrigir sem perder o tempo já contado. Mas atenção: o <em>session-end</em> ao parar vai vincular o tempo ao paciente que estiver selecionado <em>no momento da parada</em>.$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;

development/02-auditoria/AUDIT_BASELINE.md

@@ -0,0 +1,302 @@
+# Audit Baseline — 6 Módulos vs Blueprints
+
+> **Data:** 2026-05-20
+> **Método:** 6 agentes Explore em paralelo, cada um auditou 1 módulo contra os 3 blueprints (repository, composable, quick-create overlay)
+> **Saída:** mapa exato do trabalho da Fase 1 da Padronização Sweep
+
+---
+
+## Sumário Executivo
+
+| # | Módulo | Estado | Alta | Média | Baixa | Bloqueador |
+|---|---|---|---|---|---|---|
+| 1 | Home / Components | Parcial | 3 | 2 | 2 | — |
+| 2 | Pacientes | Parcial | 4 | 6 | 2 | — |
+| 3 | Prontuário | **Embrionário** | 3 | 3 | 0 | Schema clínico ausente |
+| 4 | Financeiro | **Órfão** | 6 | 3 | 1 | Overlap com agenda + double-billing risk |
+| 5 | Multi-tenant | Parcial | 2 | 3 | 2 | **Convites/membership inexistem** |
+| 6 | Notificações | **Embrionário** | 5 | 3 | 1 | 3 canais fragmentados, SMS envio só stub |
+
+**Totais:** 23 alta · 20 média · 8 baixa = **51 divergências catalogadas** + 4 gaps estruturais.
+
+---
+
+## Surpresas (descobertas que mudam o plano)
+
+### 🚨 1. Convites/membership de tenant — gap apenas no front (CORRIGIDO 2026-05-20)
+
+Agente Multi-tenant disse: **não existe** repository/composable pra `sendInvite(tenantId, email)`, `acceptInvite(inviteId)`, `listTenantMembers(tenantId)`. **Correção:** a tabela `public.tenant_invites` JÁ EXISTE no schema (`tenants_multi_tenant.sql:100`) com campos completos (id, tenant_id, email, role CHECK ['therapist','secretary'], token, invited_by, expires_at default 7d, accepted_at/by, revoked_at/by). Falta APENAS UI + composables/services no front.
+
+Recomendação: criar `features/tenantship/` com services + composables + página `/admin/members` usando a tabela existente. Sem migration de schema necessária. Reduz escopo de 0.5.D.
+
+### 🚨 2. Lógica de billing duplicada agenda ↔ financeiro — risco de double-billing
+
+`useAgendaFinanceiro.gerarCobrancaManual()` (composables raiz) e `useFinancialRecords.createRecord()` (composables raiz) **chamam a mesma RPC** `create_financial_record_for_session`. Sem coordenação = race condition silenciosa.
+
+`useAgendaFinanceiro.handleStatusChange()` ainda relê `financial_records` direto via `.select('id').eq('agenda_evento_id', ...)` — query que deveria viver só no useFinancialRecords.
+
+Recomendação: consolidar em 1 composable orquestrador, ou separar responsabilidades com coordenação explícita via fila.
+
+### 🚨 3. Quick-create overlay — promotion criteria atingida ANTES da hora
+
+Blueprint documentei como "agenda-only, promover quando aparecer 2º caso de uso". Agente Home descobriu **3 quick-create candidatos JÁ em produção**, fora da agenda:
+
+- `src/components/CadastroRapidoMedico.vue` (supabase direto)
+- `src/components/CadastroRapidoConvenio.vue` (supabase direto)
+- `src/components/ComponentCadastroRapido.vue` (genérico, supabase direto)
+
+São o 2º, 3º e 4º casos. **Promover agora** muda o blueprint de "agenda-only" pra universal, e dá fix em 3 componentes ao mesmo tempo.
+
+### 🚨 4. Prontuário sem schema clínico
+
+Agente Prontuário: o "Prontuário" hoje é shell de abas que reusa `usePatientSessions`. Schema vazio pra anamnese, evolução clínica, plano terapêutico. **Não dá pra padronizar antes de modelar.**
+
+Recomendação: adicionar etapa "modelagem schema clínico" como pré-requisito pro módulo 3 da Fase 1.
+
+### 🟡 5. `error = ref(null)` vs `ref('')` confirmado como divergência sistêmica
+
+Aparece em pacientes, financeiro, alguns lugares de notificações. Confirma a canonicalização do composable blueprint (`''` default). Fix mecânico, fácil de aplicar.
+
+### 🟡 6. Setup Wizard tem 8 queries supabase inline
+
+Já estava no `project_graphify_findings_20260504` ("Setup Wizard cohesion 0.05"). Agora quantificado: 8 queries (linhas 419, 429, 446, 595, 626, 656, 681, 706). Fix: criar `setupRepository.js` + `useSetupWizard.js`.
+
+---
+
+## Cross-cutting patterns (não específicos a 1 módulo)
+
+| Pattern | Onde aparece | Severidade | Fix |
+|---|---|---|---|
+| `error = ref(null)` | Pacientes, Financeiro, partes de Notificações | Média | Mecânico: `ref('')` |
+| `supabase.from(...)` em composable | Pacientes (4 composables), Financeiro (2), Notificações (3+), Multi-tenant (1) | Alta | Extrair pra repository |
+| SELECT inline em vez de constante | Pacientes (3), Financeiro, Notificações | Média | Extrair pra `<feature>Selects.js` |
+| UPDATE/DELETE sem `.eq('tenant_id', tid)` | Pacientes (2), Financeiro (3) | Alta | Defesa em profundidade |
+| `getUid()` / `useTenantStore()` duplicados | Múltiplos composables | Baixa | Helper compartilhado |
+| State em variável módulo (vaza entre instâncias) | `usePatientFinancial._lastPatientId` | Alta | Mover DENTRO da `function use*()` |
+| `_tenantGuards.js` ausente em todo módulo não-agenda | Todos | Média | Replicar pattern |
+
+---
+
+## Detalhamento por Módulo
+
+### 1. Home / Components base
+
+**Estado:** Parcial. Falta camada de repository. 3 quick-creates espalhados fazem supabase direto.
+
+**Arquivos-chave:**
+- `src/views/pages/HomeCards.vue` — roteador de perfis + RPC de auditoria interna
+- `src/layout/melissa/MelissaLayout.vue` — orquestrador (~90 imports, monolítico)
+- `src/components/CadastroRapidoMedico.vue` — quick-create supabase direto
+- `src/components/CadastroRapidoConvenio.vue` — quick-create supabase direto
+- `src/components/ComponentCadastroRapido.vue` — quick-create genérico supabase direto
+
+**Divergências:**
+
+| Sev | Tipo | Local | Problema | Fix |
+|---|---|---|---|---|
+| ~~Alta~~ ✅ | quick-create | `CadastroRapidoMedico.vue:150` | ~~`supabase.from()` direto sem repository~~ | **RESOLVIDO 2026-05-20 (M1.1):** `features/medicos/services/medicosRepository.js` criado + componente refatorado pra usar `useMedicos` composable |
+| ~~Alta~~ ✅ | quick-create | `CadastroRapidoConvenio.vue:98` | ~~`supabase.from()` inline~~ | **RESOLVIDO 2026-05-20 (M1.2):** `features/insurance/services/insurancePlansRepository.js` criado + componente usa `useInsurancePlans` composable. Bônus: agenda `InsurancePlanQuickCreateDialog.vue` também migrado. |
+| ~~Alta~~ ✅ | quick-create | `ComponentCadastroRapido.vue:263` | ~~`insert()` sem validação `tenant_id`+`owner_id`~~ | **RESOLVIDO 2026-05-20 (M1.3):** componente usa `usePatients.create()`; tenant resolvido via `getMyActiveMember()` (helper novo em tenantship); repository injeta `owner_id = auth.uid()` sempre, ignora payload. |
+| ~~Média~~ ✅ | composable | `CadastroRapidoMedico.vue:49-58` | ~~`getTenantId()` via fallback query em vez de store~~ | **RESOLVIDO 2026-05-20 (M1.1):** removido — repository usa `resolveTenantId()` canônico |
+| ~~Média~~ ✅ | composable | `CadastroRapidoConvenio.vue:94-100` | ~~`loadPlans()` sem `.eq('tenant_id', tid)`~~ | **RESOLVIDO 2026-05-20 (M1.2):** repository agora filtra por tenant_id + owner_id |
+| ~~Baixa~~ ✅ | outro | `HomeCards.vue:23-33` | ~~`TEST_ACCOUNTS` hardcoded~~ | **RESOLVIDO 2026-05-20 (M1.4):** extraído pra `src/config/devTestAccounts.js` |
+| Baixa | outro | `MelissaLayout.vue:1-150` | 90+ imports, monolítico | Refactor Fase 2 (M1.6 — sessão dedicada) |
+
+### 2. Pacientes
+
+**Estado:** Parcial. `patientsRepository` é o ÚNICO repo padronizado fora da agenda (8/10 conformidade). Composables têm violações de camada.
+
+**Arquivos-chave:**
+- `src/features/patients/services/patientsRepository.js` — referência parcial
+- `src/features/patients/composables/usePatients.js` — thin wrapper (falha em error type)
+- `src/features/patients/composables/usePatientDetail.js` — supabase direto
+- `src/features/patients/composables/usePatientFinancial.js` — supabase direto + estado módulo
+- `src/features/patients/composables/usePatientSessions.js` — supabase direto
+- `src/components/ui/PatientCreatePopover.vue` — padrão OK (não é quick-create overlay)
+
+**Divergências:**
+
+| Sev | Tipo | Local | Problema | Fix |
+|---|---|---|---|---|
+| ~~Alta~~ ✅ | repo | `patientsRepository.js:64` | ~~`createPatient` aceita `owner_id` do payload~~ | **RESOLVIDO 2026-05-20 (spillover M1.3):** repository sempre injeta `owner_id = await getUid()`; strip `owner_id` do payload via destructure. |
+| ~~Alta~~ ✅ | composable | `usePatientDetail.js:13-40` | ~~supabase direto em 4 funções~~ | **RESOLVIDO 2026-05-20 (M2.2):** 4 funções migradas pra patientsRepository |
+| ~~Alta~~ ✅ | composable | `usePatientFinancial.js:21,156-164` | ~~`_lastPatientId` em variável módulo + supabase direto~~ | **RESOLVIDO 2026-05-20 (M2.3):** state movido DENTRO da function; mutations via repository |
+| ~~Alta~~ ✅ | composable | `usePatientSessions.js:33-44, 127-182` | ~~supabase direto em 2 mutations~~ | **RESOLVIDO 2026-05-20 (M2.4):** list+create+updateStatus via repository (com helper findSessionByRecurrence pra materialização) |
+| ~~Média~~ ✅ | composable | `usePatients.js:22` | ~~`error = ref(null)` viola canon~~ | **RESOLVIDO 2026-05-20 (spillover M1.3):** `error = ref('')` canon do composable-blueprint. |
+| ~~Média~~ ✅ | composable | `usePatientDetail.js:69` | ~~Funções internas retornam `null` silencioso em erro~~ | **RESOLVIDO 2026-05-20 (M2.2):** repository functions throw em vez de return null |
+| Média | composable | `usePatientFinancial.js:149-191, usePatientSessions.js:140-182` | Mutations retornam `{ok, data?, error?}` em vez de throw | Padrão preservado por compat com callers; fix posterior em sessão dedicada |
+| ~~Média~~ ✅ | composable | `usePatientRecurrences.js:34` | ~~`.select('*')` inline~~ | **RESOLVIDO 2026-05-20 (M2.1):** `PATIENT_RECURRENCE_RULES_SELECT` em patientsSelects.js |
+| ~~Média~~ ✅ | composable | `usePatientMessages.js:29, usePatientDocuments.js:30, usePatientSessions.js:38` | ~~SELECT inline sem constante~~ | **RESOLVIDO 2026-05-20 (M2.1):** 5 constantes em patientsSelects.js |
+| ~~Média~~ ✅ | composable | `usePatientFinancial.js:127-130, usePatientSessions.js:211-274` | ~~Mutações sem `.eq('tenant_id', tid)`~~ | **RESOLVIDO 2026-05-20 (M2.3+M2.4):** todas mutations no repository usam `.eq('tenant_id', tid)` |
+| ~~Baixa~~ ✅ | composable | `usePatients.js:45` | ~~`remove` não re-throw~~ | **RESOLVIDO 2026-05-20 (M2.6):** Tipo A canônico completo |
+| Baixa | composable | `usePatientSessions.js:67` | Filtro de virtual occurrences encapsulado no composable | Documentar como legado pré-refactor |
+
+### 3. Prontuário/Evolução
+
+**Estado:** **Embrionário.** Mal-existe. Aba "Prontuário evolutivo" é placeholder vazio.
+
+**Arquivos-chave:**
+- `src/features/patients/prontuario/PatientProntuario.vue` (188 KB) — shell de abas
+- `src/features/patients/prontuario/PatientConversationsTab.vue` (11.8 KB) — timeline supabase direto
+- `usePatientSessions.js` reusado (não é prontuário-específico)
+
+**Divergências:**
+
+| Sev | Tipo | Local | Problema | Fix |
+|---|---|---|---|---|
+| Alta | composable | `PatientProntuario.vue:29` | supabase direto pra `conversation_messages`, `agenda_eventos`, `financial_records`, `documents`, `patient_groups`, `patient_tags` | Extrair `usePatientConversations`, `usePatientFinancial`, `usePatientDocuments` |
+| Alta | repo | (não existe) | Nenhum repository pras tabelas do prontuário | Criar `patientFinancialRepository.js`, `patientDocumentsRepository.js` |
+| Alta | composable | `PatientConversationsTab.vue:8` | Query direto a `conversation_messages` | Mover pra repository |
+| Média | gap | `PatientProntuario.vue:1950` | Aba "Prontuário" é placeholder vazio — schema clínico não modelado | **Decidir modelo: `patient_notes`? `clinic_sessions`? `patient_clinical_notes`?** |
+| Média | composable | `usePatientSessions.js:38` | Queries inline a `agenda_eventos`, `recurrence` | Mover pra `patientSessionsRepository.js` |
+| Média | repo | `PatientProntuario.vue:381-384` | `updateSessionStatus` mutação inline em componente | Mover pra repository |
+
+**Gaps estruturais:**
+1. Repository layer ausente (3 repositories a criar)
+2. Composable layer incompleto (3 composables a criar)
+3. **Schema clínico inexistente** — anamnese, evolução, plano terapêutico não modelados
+4. PatientProntuario.vue é monolítico (188 KB) — refactor candidate
+
+### 4. Financeiro
+
+**Estado:** **Órfão.** Módulo existe mas sem camada repository; composables raiz fazem supabase direto.
+
+**Arquivos-chave:**
+- `src/features/financeiro/pages/FinanceiroPage.vue` — supabase direto inline
+- `src/features/financeiro/pages/FinanceiroDashboardPage.vue` — RPC direto inline
+- `src/composables/useFinancialRecords.js` — composable raiz com supabase inline (sem repository)
+- `src/composables/useAgendaFinanceiro.js` — orquestrador agenda-financeiro com lógica duplicada
+
+**Divergências:**
+
+| Sev | Tipo | Local | Problema | Fix |
+|---|---|---|---|---|
+| Alta | repo | `useFinancialRecords.js:294` | UPDATE sem `.eq('tenant_id', tid)` | Defesa em profundidade |
+| Alta | repo | `useAgendaFinanceiro.js:194, 215` | UPDATE sem `.eq('tenant_id', tid)` em 2 pontos | Idem |
+| Alta | composable | `useFinancialRecords.js:58` | `error = ref(null)` | `ref('')` |
+| Alta | camada | `useFinancialRecords.js` (todo) | supabase direto viola blueprint | Extrair pra `financeiro/services/financialRecordsRepository.js` |
+| Alta | camada | `useAgendaFinanceiro.js:191, 205, 209` | supabase direto | Mover pra repository ou RPC wrapper |
+| Alta | overlap | `useAgendaFinanceiro.js:114-151` + `useFinancialRecords.js:157-189` | **Lógica duplicada de criação de cobrança** — ambos chamam mesma RPC | Consolidar em 1 composable orquestrador |
+| Média | convenção | `FinanceiroPage.vue:22-51` | supabase direto em componente | Mover pra composable |
+| Média | convenção | `FinanceiroDashboardPage.vue:68, 78, 144` | RPC inline em componente | Criar `useFinancialDashboard` |
+| Média | SELECT | `useFinancialRecords.js:40-51` | BASE_SELECT constante OK, mas sem `flatten<Feature>Row` | Adicionar helper se joins aninhados |
+| Baixa | cosmético | `FinanceiroPage.vue:27-40` | Formatadores BRL/Date duplicados na dashboard | Extrair pra `financeiro/utils/formatters.js` |
+
+**Overlap crítico com agenda:**
+- `useAgendaFinanceiro.gerarCobrancaManual()` vs `useFinancialRecords.createRecord()` chamam mesma RPC — **risco double-billing em race condition**
+- `useAgendaFinanceiro.handleStatusChange()` relê `financial_records` (linhas 191, 205) — query que pertence a `useFinancialRecords`
+- Ambos importam `useTenantStore` + `getUid()` inline (duplicação)
+
+### 5. Multi-tenant
+
+**Estado:** Parcial. Stores OK. **Gap crítico: convites/membership inexistem.** SetupWizard e SaasTenantFeaturesPage com queries inline.
+
+**Arquivos-chave:**
+- `src/stores/tenantStore.js` — Pinia store + memberships read-only via RPC
+- `src/stores/tenantFeaturesStore.js` — computed store + TTL cache + RPC
+- `src/stores/entitlementsStore.js` — view-based (`v_tenant_entitlements`, `v_user_entitlements`)
+- `src/features/setup/SetupWizardPage.vue` — 8 queries supabase inline
+- `src/views/pages/saas/SaasTenantFeaturesPage.vue` — 4 queries inline
+- `src/features/clinic/components/ModuleRow.vue` — dumb component OK
+
+**Divergências:**
+
+| Sev | Tipo | Local | Problema | Fix |
+|---|---|---|---|---|
+| ~~Alta~~ ✅ | composable | `SaasTenantFeaturesPage.vue:124-129` | ~~4 queries supabase direto~~ | **RESOLVIDO 2026-05-20 (M5 quick win):** extraído pra `src/services/tenantFeatureAdminService.js`. |
+| Alta | repository | `SetupWizardPage.vue:419, 429, 446, 595, 626, 656, 681, 706` | 8 supabase queries inline em página | Criar `setupRepository.js` + `useSetupWizard.js` |
+| Média | store | `tenantFeaturesStore.js:134` | `fetchForTenant` faz `from('tenant_features')` direto | Wrapper em `tenantFeaturesRepository.js` |
+| Média | store | `entitlementsStore.js:136, 177` | Queries em views direto | Aceitar como read-only com comentário |
+| Média | convention | `SaasTenantFeaturesPage.vue:33-53` | Error pattern inconsistente | Usar toast |
+| Baixa | naming | `tenantFeaturesStore.js:52` | `loadedForTenantId` vs `tenantId` ambíguo | Renomear |
+| Baixa | cosmetic | `SetupWizardPage.vue:60` | `isClinicRole` via string matching | Usar `useRoleGuard` |
+
+**Gap crítico — convites/membership:**
+
+Grep por `tenant_members`, `tenant_invite`, `convite`, `invitation` retornou **zero** em `features/`. Não existe:
+- Repository para `sendInvite(tenantId, email)`
+- Repository para `acceptInvite(inviteId)`
+- Repository para `listTenantMembers(tenantId)`
+- Composable wrapper
+- Página `/admin/members` pra gestão
+
+**Recomendação:** criar `features/tenantship/` (ou `features/team/`) completo. Bloqueador de MVP.
+
+### 6. Notificações
+
+**Estado:** **Embrionário.** Fragmentado em 3+ canais (WhatsApp Evolution, WhatsApp Twilio, SMS Twilio, in-app, notices globais), sem padronização.
+
+**Arquivos-chave:**
+- `src/features/notices/noticeService.js` — supabase direto sem repository
+- `src/features/conversations/CRMConversasPage.vue` — página complexa, lógica não extraída
+- `src/composables/useConversations.js` — query + business logic + supabase direto
+- `src/composables/useNotifications.js` — toast + realtime + polling
+- `src/stores/notificationStore.js` — in-app puro (OK)
+- `src/stores/conversationDrawerStore.js` — mistura send WhatsApp/SMS + templates
+- `src/stores/twilioWhatsappStore.js` — estado Twilio subcontas
+- `src/views/pages/notifications/SmsChannelSetupPage.vue` — credenciais via supabase
+- `src/views/pages/therapist/NotificationsHistoryPage.vue` — sync com store
+
+**Divergências:**
+
+| Sev | Tipo | Local | Problema | Fix |
+|---|---|---|---|---|
+| Alta | repo | `noticeService.js:28-44` | SELECT inline | Criar `notices/noticeSelects.js` |
+| Alta | composable | `useConversations.js:85-91` | supabase direto, sem repository | Criar `conversations/services/conversationsRepository.js` |
+| Alta | repo | `useConversations.js:229-244` | SELECT inline em `loadThreadMessages()` | Extrair pra repository |
+| Alta | gap | `conversationDrawerStore.js:339-346` | Edge function invoke direto sem fallback/retry | Criar `sendMessageService.js` com error handling |
+| Alta | canais | `conversationDrawerStore.js:327-377` | Lógica de envio WhatsApp (Evolution + Twilio) sem abstração | Factory por canal |
+| Média | error | `useNotifications.js:117-145` | Realtime/polling sem try/catch | Wrap |
+| Média | repo | `conversationDrawerStore.js:414-449` | `loadTemplates()` sem `.eq('tenant_id', ...)` no 2º select | Adicionar guard |
+| Média | naming | `SmsChannelSetupPage.vue:84-102` | Query sem SELECT canônico | Extrair |
+| Baixa | cosmético | `useConversations.js:165-184` | Channel filter hardcoded ['whatsapp','sms','email'] | Exportar `CHANNEL_TYPES` const |
+
+**Canais identificados:**
+1. WhatsApp (Evolution API) — Parcial
+2. WhatsApp (Twilio) — Parcial
+3. SMS (Twilio) — **Stub** (só setup, sem envio)
+4. In-app (browser notifications) — Funcional
+5. Global Notices — Funcional
+
+**Gaps estruturais:**
+- Repositórios inexistem (conversas, mensagens, canais)
+- `_tenantGuards.js` ausente
+- SELECT canônico fragmentado
+- Composables fat (`useConversations` faz 3 coisas)
+- SMS envio não implementado (só credenciais)
+
+---
+
+## Próximos passos
+
+### Ajustes ao plano original
+
+**Fase 0** — concluída. Audit baseline pronto.
+
+**Fase 1** — sequenciamento revisado considerando as 4 surpresas:
+
+| Ordem | Módulo | Pré-requisito | Observação |
+|---|---|---|---|
+| 1 | **Home/Components** | — | Inclui promover quick-create blueprint (3 candidates já existem) + criar `medicos/` e `insurance/` features |
+| 1.5 | **Quick-create blueprint promotion** | — | Mover blueprint de "agenda-only" pra universal; refatorar 3 CadastroRapido components em paralelo |
+| 2 | **Pacientes** | — | `patientsRepository` já parcial; fix 4 composables com supabase direto |
+| 3 | **Prontuário (parcial)** | **Decisão de schema clínico** | Sem schema, só dá pra criar repositories pras tabelas existentes (financial_records, documents) |
+| 4 | **Financeiro** | Decisão sobre overlap com agenda | Resolver double-billing risk ANTES de refactor |
+| 5 | **Multi-tenant + Convites** | — | Criar `tenantship/` feature inteiro (gap crítico) |
+| 6 | **Notificações** | — | Pesado: 3 canais, abstração por factory |
+
+### Decisões pendentes (precisa de você)
+
+1. **Quick-create blueprint:** promover pra universal agora ou manter agenda-only? (recomendo promover — promotion criteria atingida)
+2. **Schema clínico do prontuário:** modelar agora (bloqueador) ou empurrar pra Fase 1 estendida?
+3. **Overlap billing agenda↔financeiro:** consolidar em 1 composable OU separar com coordenação via fila? (recomendo consolidar)
+4. **Convites/membership:** criar feature `tenantship/` separada OU absorver em `clinic/`? (recomendo separada — semântica diferente)
+5. **`dev_auditoria_items` no banco:** popular agora os 51 itens via SQL OU UI uma a uma? (recomendo SQL batch insert — mais rápido pra começar Fase 1)
+
+---
+
+## Referências
+
+- Blueprints: `blueprints/repository-blueprint.md`, `composable-blueprint.md`, `quick-create-overlay-blueprint.md`
+- Estratégia: `development/02-auditoria/PADRONIZACAO.md`
+- Memória: `project_padronizacao_sweep.md`, `project_graphify_findings_20260504.md`

development/02-auditoria/DESIGN_ASAAS_GATEWAY.md

@@ -0,0 +1,325 @@
+# Design — Asaas Gateway (Tier 1: Cobrança de Paciente · PIX + Boleto)
+
+> **Data:** 2026-05-21
+> **Tipo:** Design doc + foundation (sem credenciais reais ainda)
+> **Resolve:** Item #1-#3 da Fase 1 do ROADMAP (Monetização)
+> **Decisões confirmadas:** Tier 1 primeiro (paciente paga terapeuta) · PIX + Boleto · Approach foundation com stops
+
+---
+
+## 1. Estado atual
+
+### 1.1 O que JÁ EXISTE no projeto
+
+- **Edge Function `asaas-webhook`** (`supabase/functions/asaas-webhook/index.ts`) — porém só lida com `whatsapp_credit_purchases`. Token `ASAAS_WEBHOOK_TOKEN` validado.
+- **Edge Function `create-whatsapp-credit-charge`** — cria cobrança Asaas para créditos WhatsApp. Pattern de chamada à API Asaas estabelecido.
+- **Tabela `whatsapp_credit_purchases`** com coluna `asaas_payment_id`. Modelo: 1 purchase ↔ 1 Asaas payment.
+- **Coluna `financial_records.payment_link`** (migration 20260514000001) — espera o URL Asaas quando integração existir.
+- **Tabela `payment_settings`** com pix_chave, deposito_*, etc — config manual de pagamento por owner (NÃO é Asaas).
+- **Asaas mencionado em 9 arquivos client** — todos relacionados a WhatsApp credits ou docs.
+
+### 1.2 O que FALTA pra patient billing
+
+- Schema: tabelas `asaas_customers` (mapping patient → Asaas customer) e `asaas_payments` (1 row por cobrança gerada)
+- Schema: ENCRYPTED storage da API key Asaas por tenant (se modelo B — ver §3)
+- Edge Function `asaas-create-customer-patient` — upsert customer no Asaas
+- Edge Function `asaas-create-payment-record` — gera cobrança a partir de financial_record
+- Edge Function `asaas-cancel-payment` — cancela
+- Edge Function `asaas-webhook` ESTENDIDA — handler pra eventos de financial_records (atualmente só whatsapp_credit_purchases)
+- Cliente JS: `asaasGatewayService.js` em `features/financeiro/services/`
+- UI: botão "Gerar cobrança Asaas" no record do `financial_records` (não escopo desta sessão)
+
+---
+
+## 2. Arquitetura
+
+### 2.1 Camadas
+
+```
+┌─────────────────────────────────────────────────┐
+│  Browser (Vue)                                   │
+│  ├ asaasGatewayService.js                       │
+│  │   • createPaymentForRecord(recordId, opts)   │  ← invoca Edge Function via supabase.functions.invoke
+│  │   • cancelPayment(asaasPaymentId)            │
+│  │   • getPaymentInfo(asaasPaymentId)           │
+└─────────────────────────────────────────────────┘
+                       ↓
+┌─────────────────────────────────────────────────┐
+│  Supabase Edge Functions (Deno)                  │
+│  ├ asaas-create-customer-patient                │
+│  │   • Recebe patient_id                         │
+│  │   • Upsert asaas_customers (cache)            │
+│  │   • Chama Asaas POST /customers               │
+│  ├ asaas-create-payment-record                  │
+│  │   • Recebe financial_record_id + method      │
+│  │   • Garante customer existe (cascade)         │
+│  │   • Chama Asaas POST /payments                │
+│  │   • Salva asaas_payments + update financial_records.payment_link │
+│  ├ asaas-cancel-payment                          │
+│  │   • Asaas DELETE /payments/:id                │
+│  └ asaas-webhook (EXTENDER)                     │
+│      • Adiciona handler pra events linkados a  │
+│        financial_records (não só credits)        │
+└─────────────────────────────────────────────────┘
+                       ↓
+┌─────────────────────────────────────────────────┐
+│  Asaas REST API (sandbox/prod)                   │
+└─────────────────────────────────────────────────┘
+```
+
+### 2.2 Por que Edge Functions e não client-side?
+
+**Crítico:** API key do Asaas NUNCA pode chegar ao browser. Browser vê script + DevTools = key vaza = qualquer pessoa cria cobrança em nome da plataforma/tenant. Edge Functions rodam server-side, key fica em env vars do Supabase.
+
+---
+
+## 3. Modelo de negócio (DECISÃO PENDENTE)
+
+**Quem detém a conta Asaas que recebe o dinheiro?**
+
+### Opção A — Plataforma (marketplace)
+- 1 conta Asaas global da plataforma AgenciaPsi
+- Plataforma recebe TUDO + repassa pra terapeutas (split payment ou reconciliação manual)
+- Asaas tem feature de SubAccounts/Split — pode ser configurado
+- **Pros:** simples, 1 chave ENV no Supabase
+- **Cons:** plataforma fica como intermediadora financeira (regulatório + impostos + compliance)
+
+### Opção B — Tenant-level (recommended pra MVP solo-therapist)
+- Cada tenant tem SUA conta Asaas
+- API key encrypted em `payment_settings.asaas_api_key` (Supabase Vault ou pgsodium)
+- Terapeuta recebe direto na própria conta
+- Edge Function lê chave do tenant requisitante
+- **Pros:** sem complexidade regulatória pra plataforma
+- **Cons:** terapeuta precisa configurar Asaas próprio (UX onboarding)
+
+### Opção C — Híbrido
+- Plataforma cobra mensalidade SaaS via SUA Asaas (Tier 2 — fora desta sessão)
+- Terapeuta cobra paciente via SUA Asaas (Tier 1)
+- 2 contas em mundos separados
+
+**Recomendação desta sessão:** **Opção B (Tenant-level)** pra Tier 1. Tier 2 (SaaS subscriptions) decide depois — pode ser A com mesma infra.
+
+---
+
+## 4. Schema additions
+
+### 4.1 Tabela `asaas_customers`
+
+Mapping patient ↔ Asaas customer. Cacheado (não recriar a cada cobrança).
+
+```sql
+CREATE TABLE public.asaas_customers (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id uuid NOT NULL,
+    patient_id uuid NOT NULL REFERENCES patients(id) ON DELETE CASCADE,
+    asaas_customer_id text NOT NULL,
+    -- ambiente: sandbox ou prod (mesmo patient pode ter ambos)
+    environment text NOT NULL DEFAULT 'prod' CHECK (environment IN ('sandbox', 'prod')),
+    -- dados cacheados (sincronizados quando atualizar)
+    name text NOT NULL,
+    email text,
+    cpf_cnpj text,
+    phone text,
+    address jsonb,
+    -- audit
+    created_at timestamptz DEFAULT now() NOT NULL,
+    updated_at timestamptz DEFAULT now() NOT NULL,
+    deleted_at timestamptz,
+    UNIQUE (tenant_id, patient_id, environment)
+);
+
+CREATE INDEX idx_asaas_customers_lookup
+    ON public.asaas_customers (tenant_id, patient_id)
+    WHERE deleted_at IS NULL;
+```
+
+### 4.2 Tabela `asaas_payments`
+
+1 row por cobrança Asaas gerada. Link com financial_record.
+
+```sql
+CREATE TABLE public.asaas_payments (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id uuid NOT NULL,
+    financial_record_id uuid NOT NULL REFERENCES financial_records(id) ON DELETE CASCADE,
+    asaas_customer_id uuid REFERENCES asaas_customers(id),
+    asaas_payment_id text NOT NULL,
+    asaas_invoice_id text,
+    environment text NOT NULL DEFAULT 'prod' CHECK (environment IN ('sandbox', 'prod')),
+    billing_type text NOT NULL CHECK (billing_type IN ('PIX', 'BOLETO', 'CREDIT_CARD', 'UNDEFINED')),
+    status text NOT NULL,  -- raw Asaas status; mapeamento pra financial_records.status no JS
+    value numeric(10, 2) NOT NULL,
+    net_value numeric(10, 2),
+    due_date date NOT NULL,
+    payment_date timestamptz,
+    invoice_url text,
+    payment_url text,        -- URL pra paciente abrir e pagar
+    bank_slip_url text,      -- PDF boleto
+    pix_qr_code text,        -- base64 do QR
+    pix_copy_paste text,     -- payload PIX
+    -- audit
+    created_at timestamptz DEFAULT now() NOT NULL,
+    updated_at timestamptz DEFAULT now() NOT NULL,
+    cancelled_at timestamptz,
+    UNIQUE (asaas_payment_id, environment)
+);
+
+CREATE INDEX idx_asaas_payments_record
+    ON public.asaas_payments (financial_record_id);
+CREATE INDEX idx_asaas_payments_lookup
+    ON public.asaas_payments (tenant_id, status, due_date);
+```
+
+### 4.3 Tabela `asaas_webhook_events`
+
+Idempotência + audit. Cada webhook recebido vai aqui ANTES de processar.
+
+```sql
+CREATE TABLE public.asaas_webhook_events (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    event_id text,                          -- id que Asaas mandar (se mandar)
+    event_type text NOT NULL,               -- PAYMENT_RECEIVED, PAYMENT_OVERDUE, etc
+    asaas_payment_id text,                  -- pra linkar com asaas_payments
+    payload jsonb NOT NULL,                 -- raw event pra debug
+    processed_at timestamptz,               -- quando processou; NULL = pendente/falha
+    processing_error text,
+    received_at timestamptz DEFAULT now() NOT NULL,
+    UNIQUE (event_id) DEFERRABLE INITIALLY DEFERRED
+);
+
+CREATE INDEX idx_asaas_webhook_events_payment
+    ON public.asaas_webhook_events (asaas_payment_id);
+```
+
+### 4.4 Coluna ENCRYPTED na `payment_settings`
+
+Tenant-level API key (Opção B). Usa pgsodium ou Supabase Vault.
+
+```sql
+-- Sandbox e prod separados — terapeuta começa em sandbox, migra pra prod quando OK.
+ALTER TABLE public.payment_settings
+    ADD COLUMN IF NOT EXISTS asaas_api_key_sandbox text,  -- prefixado com "$pgsodium-encrypted$" via trigger
+    ADD COLUMN IF NOT EXISTS asaas_api_key_prod text,
+    ADD COLUMN IF NOT EXISTS asaas_environment text DEFAULT 'sandbox' CHECK (asaas_environment IN ('sandbox', 'prod')),
+    ADD COLUMN IF NOT EXISTS asaas_webhook_token text;
+```
+
+**⚠️ Atenção:** API keys EM TEXTO NA TABELA é vulnerabilidade séria. Em produção precisa Supabase Vault (pgsodium) ou KMS externo. Pra MVP sandbox dá pra deixar plaintext + RLS restritiva, mas tem que documentar como dívida.
+
+---
+
+## 5. Status mapping Asaas → financial_records
+
+| Asaas | financial_records.status |
+|---|---|
+| PENDING | pending |
+| RECEIVED / CONFIRMED | paid |
+| RECEIVED_IN_CASH | paid (manual) |
+| OVERDUE | overdue |
+| REFUNDED / CHARGEBACK_REQUESTED | refunded |
+| DELETED / CHARGEBACK_DISPUTE | cancelled |
+
+---
+
+## 6. Flow completo (happy path) — Tier 1 PIX
+
+1. Terapeuta cria sessão na agenda → trigger gera `financial_records` row (status=pending, payment_method=null, payment_link=null)
+2. Terapeuta vê record na UI e clica **"Gerar cobrança Asaas (PIX)"**
+3. Cliente JS chama `asaasGatewayService.createPaymentForRecord(recordId, { method: 'PIX' })`
+4. Service invoca Edge Function `asaas-create-payment-record`
+5. Edge Function:
+   - Lê financial_record + patient + tenant_settings (API key)
+   - Garante asaas_customers row (chama asaas-create-customer-patient se não existe)
+   - POST `https://sandbox.asaas.com/api/v3/payments` com `customer`, `value`, `dueDate`, `billingType=PIX`, `externalReference=<financial_record_id>`
+   - Asaas retorna `id`, `invoiceUrl`, e (pra PIX) `id` de QR code
+   - Edge Function chama POST `/payments/:id/pixQrCode` pra pegar QR base64
+   - INSERT em `asaas_payments` com toda metadata
+   - UPDATE `financial_records.payment_link = invoiceUrl, payment_method = 'pix_asaas'`
+6. Service retorna `{ paymentUrl, qrCode, copyPaste }` pro cliente
+7. UI mostra QR code + link pra paciente
+8. Paciente paga via PIX
+9. Asaas dispara webhook PAYMENT_RECEIVED → Edge Function `asaas-webhook`:
+   - INSERT em `asaas_webhook_events` (idempotência via event_id)
+   - Busca `asaas_payment` por `asaas_payment_id`
+   - Se status=='paid' já: skip
+   - UPDATE `asaas_payments.status='RECEIVED'`, `payment_date=now()`
+   - UPDATE `financial_records.status='paid'`, `paid_at=now()`
+   - Marca event como `processed_at=now()`
+
+---
+
+## 7. Decisões de implementação
+
+| Decisão | Confirmada |
+|---|---|
+| Tier 1 (paciente paga terapeuta) primeiro | ✅ |
+| PIX + boleto primeiro (cartão depois) | ✅ |
+| Modelo tenant-level (Opção B) | ⚠️ PROPOSTO — confirme antes de implementar |
+| Sandbox first, prod depois | ⚠️ default — confirme |
+| Storage de API key plaintext em `payment_settings` (com RLS) pra MVP | ⚠️ DÍVIDA conhecida — vault depois |
+| `externalReference` no Asaas = financial_records.id | ⚠️ PROPOSTO — facilita reconciliação |
+| Webhook compartilha mesma Edge Function (`asaas-webhook` estendida) | ⚠️ PROPOSTO — evita duplicar token validation |
+
+---
+
+## 8. Checklist do que VOCÊ precisa fornecer
+
+Antes da Fase B (implementação real):
+
+- [ ] Criar conta Asaas (https://asaas.com)
+- [ ] Habilitar PIX (gera chave PIX automática) + Boleto na conta
+- [ ] Pegar API key de SANDBOX (Configurações → Integrações)
+- [ ] Configurar webhook no Asaas: `https://<seu-projeto>.supabase.co/functions/v1/asaas-webhook` + token
+- [ ] Setar ENV vars no Supabase (Dashboard → Edge Functions → Secrets):
+  - `ASAAS_API_URL_SANDBOX=https://sandbox.asaas.com/api/v3`
+  - `ASAAS_API_URL_PROD=https://api.asaas.com/v3`
+  - `ASAAS_WEBHOOK_TOKEN=<token-aleatorio>` (já existe? checar)
+- [ ] Decidir modelo de negócio (Opção A/B/C — §3) — recomendo **B** pra MVP solo
+
+---
+
+## 9. Phasing — entrega faseada
+
+### Fase A — Foundation (esta sessão)
+- [x] Design doc (este arquivo)
+- [ ] Migration de schema (asaas_customers + asaas_payments + asaas_webhook_events + colunas em payment_settings)
+- [ ] Client service `asaasGatewayService.js` (skeleton)
+- [ ] Edge Function stubs (3 novas + nota sobre estender webhook existente)
+- [ ] README/Checklist no service file
+
+### Fase B — Implementação real (próxima sessão, requer credenciais + decisões §7)
+- [ ] Edge Functions: chamadas reais ao Asaas
+- [ ] Webhook extension: handler pra `financial_records`
+- [ ] UI: botão "Gerar cobrança Asaas" no card do financial_record
+- [ ] UI: dialog mostrando QR code PIX + link boleto
+
+### Fase C — Onboarding (após B testar)
+- [ ] Página de config Asaas no `/configuracoes/financeiro`
+- [ ] Wizard pra terapeuta inserir API key + testar conexão
+- [ ] Migration de sandbox→prod com confirm
+
+### Fase D — Avançado (futuro)
+- [ ] Cartão on file (Asaas tokenizado)
+- [ ] Auto-billing recorrente (sessão realizada → gera Asaas automático)
+- [ ] Split payment se Opção A
+- [ ] Cobrança SaaS (Tier 2)
+
+---
+
+## 10. Riscos conhecidos
+
+1. **API key vazada** — se plaintext em `payment_settings`, qualquer breach da DB compromete. **Mitigação:** RLS restritiva + Vault em produção.
+2. **Duplicate billing** — webhook dispara 2× (retry Asaas). **Mitigação:** `asaas_webhook_events.event_id` UNIQUE + check de status atual antes de mutar.
+3. **Cancelamento race** — paciente paga enquanto terapeuta cancela. **Mitigação:** UPDATE `financial_records` só se `status='pending'` (CAS).
+4. **Reconciliação manual** — se webhook falha 3× e dá up, paciente pagou mas record fica pending. **Mitigação:** Edge Function `asaas-sync-payments` (manual trigger) que consulta `/payments` por externalReference e força update.
+5. **CPF/CNPJ obrigatório no Asaas** — paciente sem CPF não pode receber cobrança. **Mitigação:** validação client-side antes de chamar service.
+
+---
+
+## 11. Referências
+
+- Asaas API docs: https://docs.asaas.com/
+- Existing webhook pattern: `supabase/functions/asaas-webhook/index.ts`
+- Migration `financial_records.payment_link`: `20260514000001_financial_records_payment_link.sql`
+- Memory: `project_agenda_billing_decisoes` (decisões #1, #4, #5, #7, #8 confirmadas; #2/#3/#6 pendentes)
+- ROADMAP: `development/04-roadmap/ROADMAP.md` Fase 1.1 (#1-#4 Monetização)

development/02-auditoria/DESIGN_BILLING_ORCHESTRATOR.md

@@ -0,0 +1,480 @@
+# Design — useBillingOrchestrator
+
+> **Data:** 2026-05-20
+> **Tipo:** Design doc (sem código). Implementação fica pra Módulo 4 (Financeiro) da Fase 1.
+> **Resolve:** decisão 7 do PADRONIZACAO.md — overlap billing agenda ↔ financeiro com risco de double-billing.
+
+---
+
+## 1. Problema atual
+
+### 1.1 Três caminhos pra criar cobrança
+
+Cobrança de sessão hoje pode ser criada por **3 lugares diferentes**:
+
+| # | Caminho | Arquivo | Quando |
+|---|---|---|---|
+| A | Botão "Gerar cobrança" manual | `useAgendaFinanceiro.gerarCobrancaManual()` (linha 114) | User clica explicitamente em sessão sem cobrança |
+| B | Mudança de status na agenda | `useAgendaFinanceiro.handleStatusChange()` (linha 163) | User troca status (agendado→faltou, etc) |
+| C | Decisões aplicadas no Melissa | `useMelissaAgenda._applyStatusDecisions()` (linha 1450) | User confirma transição de status no fluxo Melissa |
+
+**Os 3 chamam a mesma RPC** `create_financial_record_for_session`. Sem coordenação central. Resultado: race condition silenciosa possível.
+
+### 1.2 UPDATEs diretos espalhados
+
+`handleStatusChange` também faz UPDATE/SELECT em `financial_records` direto (linhas 191, 194, 205, 208) — queries que **pertencem ao useFinancialRecords** mas são duplicadas aqui pra evitar import circular.
+
+### 1.3 State em variável de módulo (vaza)
+
+`useAgendaFinanceiro.js:38`:
+```js
+const _exceptionsCache = new Map();  // ← módulo-level, vaza entre instâncias
+```
+
+Quando user troca de tenant, cache não invalida automaticamente. Memória `useAgendaFinanceiro.invalidateExceptionsCache()` precisa ser chamada manualmente em vários lugares.
+
+### 1.4 Cenários de double-billing concretos
+
+1. **Race manual + status:** user clica "Gerar cobrança" + muda status pra "faltou" em < 200ms. Path A insere registro pending; Path B detecta sessão sem `billed` (já que ainda não chegou) e cria outro registro pela exceção.
+2. **Realizado vindo de faltou paid:** sessão estava `faltou` com multa paid. User volta pra `agendado` → `realizado`. Path B/C podem regerar cobrança em cima da multa paid existente (memória `project_rpc_idempotency_cancelled` foi um fix relacionado mas não cobre todo o problema).
+3. **Pacote saldo + adicional:** sessão de pacote `billing_contract_id` setado bloqueia Path A (linha 116). Mas Path B/C podem **não checar** esse campo em alguma branch — risco de cobrança individual em sessão de pacote.
+
+---
+
+## 2. Goals & Non-goals
+
+### Goals
+1. **Single entry point** pra qualquer mudança de billing relacionada a evento da agenda.
+2. **Idempotência garantida** — chamar 2× a mesma intenção produz o mesmo resultado.
+3. **State machine explícito** de transições de status com consequências financeiras claras.
+4. **Reverse transitions** tratadas (realizado→agendado, faltou→agendado, cancelado→agendado).
+5. **Orchestrador NUNCA toca supabase direto** — só via repository e composable de financeiro.
+6. **Cache de regras de exceção** vive na instância do composable, não em módulo.
+
+### Non-goals (fora deste escopo)
+1. Implementação — só design. Código vem na Fase 1 Módulo 4.
+2. Refator de `useFinancialRecords` em si (extrair pra repository) — vai junto no Módulo 4.
+3. Gateway de pagamento (Asaas) — Fase 3 do ROADMAP.
+4. Repasse a terapeutas — `therapist_payouts` separado.
+5. UI/UX de confirmação de reverse transitions — já mapeado em memória `project_agenda_reverse_transitions`, implementação no Módulo 4.
+
+---
+
+## 3. State machine de transições
+
+### 3.1 Status válidos
+
+Enum `status_evento_agenda` (do schema): `agendado | realizado | faltou | cancelado | remarcar`
+
+### 3.2 Matriz `from → to`
+
+|  | →agendado | →realizado | →faltou | →cancelado | →remarcar |
+|---|---|---|---|---|---|
+| **agendado→** | — | ✅ FORWARD | ✅ FORWARD | ✅ FORWARD | ✅ FORWARD |
+| **realizado→** | ⚠️ REVERSE | — | ⚠️ REVERSE | ⚠️ REVERSE | ❌ inválida |
+| **faltou→** | ⚠️ REVERSE | ⚠️ CROSS | — | ⚠️ CROSS | ❌ inválida |
+| **cancelado→** | ⚠️ REVERSE | ⚠️ CROSS | ⚠️ CROSS | — | ❌ inválida |
+| **remarcar→** | ✅ FORWARD | ✅ FORWARD | ✅ FORWARD | ✅ FORWARD | — |
+
+### 3.3 Tabela de consequências financeiras
+
+| Transição | Ação financeira default | Decisão do user (override) |
+|---|---|---|
+| `agendado→realizado` | Criar pending (se ainda não billed) com `amount = event.price` | Marcar como já recebido (forma de pagamento) |
+| `agendado→faltou` | Consultar `financial_exceptions[patient_no_show]` → criar multa OR cancelar existente | Consumir saldo de pacote (se aplicável) |
+| `agendado→cancelado` | Consultar `financial_exceptions[patient_cancellation]` + `min_hours_notice` → criar taxa de cancelamento tardio OR cancelar existente | — |
+| `realizado→agendado` | **REVERSE:** se record `paid` existe → confirm dialog (refund_paid). Se `pending` → soft-cancel. Se `paid+package`: refund + devolver saldo | Reverter manualmente sem auto |
+| `realizado→faltou` | **CROSS:** reverter realizado + aplicar regra de no-show. Se já paid → manter pago e converter em multa | — |
+| `faltou→agendado` | **REVERSE:** cancelar multa pending. Se multa paid → confirm dialog (refund) | — |
+| `cancelado→agendado` | **REVERSE:** cancelar taxa de cancelamento (se houver) | — |
+| `*→remarcar` | Manter cobrança existente, atualizar `due_date` quando reagendar | — |
+
+### 3.4 Pacote (billing_contract_id presente)
+
+**Sobre qualquer transição:** se `event.billing_contract_id` não-nulo, **não criar nem cancelar `financial_records` individual**. Em vez disso:
+- `agendado→realizado`: incrementa `billing_contracts.sessions_used`
+- `agendado→faltou` ou `agendado→cancelado` com `default_consume_on_miss=true`: incrementa `sessions_used`
+- `realizado→agendado`: decrementa `sessions_used` (refresh FRESH do DB antes, memória `project_agenda_reverse_transitions`)
+
+Memória relevante: `project_cross_week_propagation` — bulk-load tem que rodar mesmo sem reais na view + query records cross-week por recurrence_id.
+
+---
+
+## 4. API shape
+
+### 4.1 Signature do composable
+
+```js
+export function useBillingOrchestrator() {
+    // ─── State ──────────────────────────────────────────────────
+    const loading = ref(false);     // operação async em andamento
+    const error = ref('');          // string vazia default (canon do composable-blueprint)
+
+    // ─── Public actions ─────────────────────────────────────────
+
+    /**
+     * Orquestra mudança de status de um evento + consequências financeiras.
+     * Single entry point — substitui os 3 caminhos atuais.
+     *
+     * @param {Object} params
+     * @param {Object} params.event              - row de agenda_eventos completa
+     * @param {string} params.fromStatus
+     * @param {string} params.toStatus
+     * @param {Object} [params.decisions]        - overrides do user (ver decisões pendentes seção 5)
+     * @returns {Promise<{ok, actions: Array<BillingAction>, error?}>}
+     */
+    async function applyStatusChange(params) { ... }
+
+    /**
+     * Gera cobrança manual pra evento sem cobrança ainda. Idempotente.
+     * Bloqueia se billing_contract_id presente.
+     */
+    async function generateChargeForEvent(event, options = {}) { ... }
+
+    /**
+     * Lista records financeiros vinculados ao evento.
+     */
+    async function fetchRecordsForEvent(eventId) { ... }
+
+    /**
+     * Cancela TODOS os records pending/overdue de um evento (soft).
+     * Use APENAS em reverse transitions confirmadas pelo user.
+     */
+    async function cancelRecordsForEvent(eventId, reason) { ... }
+
+    /**
+     * Lê regra de exceção financeira com cache local (instância).
+     */
+    async function getExceptionRule(tenantId, exceptionType) { ... }
+
+    function invalidateRules() { ... }  // chama em troca de tenant
+
+    return {
+        loading, error,
+        applyStatusChange, generateChargeForEvent,
+        fetchRecordsForEvent, cancelRecordsForEvent,
+        getExceptionRule, invalidateRules
+    };
+}
+```
+
+### 4.2 Tipos relevantes
+
+```js
+/** @typedef {Object} BillingAction
+ *  Resultado de uma operação. Compõe o array `actions` retornado por applyStatusChange.
+ * @property {string} type           - 'created' | 'updated' | 'cancelled' | 'paid' | 'package_consumed' | 'package_returned' | 'noop'
+ * @property {string} [recordId]
+ * @property {number} [amount]
+ * @property {string} [reason]
+ */
+
+/** @typedef {Object} BillingDecisions
+ *  Overrides explícitos do user. Quando ausente, orchestrator decide via regras.
+ * @property {boolean} [consumePackageSession]    - faltou/cancelado: consumir saldo de pacote
+ * @property {'auto'|'always'|'never'} [applyNoShowFee]  - aplicar multa em faltou
+ * @property {'cancel_pending'|'refund_paid'|'manual'} [reverseCleanup]  - reverse: como tratar records existentes
+ */
+```
+
+### 4.3 Exemplo de uso (caller)
+
+```js
+// Em AgendaEventDialog.vue (ou onde quer que aplique status change)
+import { useBillingOrchestrator } from '@/features/financeiro/composables/useBillingOrchestrator';
+
+const billing = useBillingOrchestrator();
+
+async function onStatusChange(novoStatus, decisoes) {
+    const result = await billing.applyStatusChange({
+        event: eventoAtual.value,
+        fromStatus: eventoAtual.value.status,
+        toStatus: novoStatus,
+        decisions: decisoes  // pode ser undefined — orchestrator usa regras default
+    });
+
+    if (!result.ok) {
+        toast.add({ severity: 'error', summary: 'Falha', detail: result.error });
+        return;
+    }
+
+    // result.actions é narrativa do que aconteceu — use pra UI feedback
+    for (const action of result.actions) {
+        if (action.type === 'created') showCreatedToast(action.amount);
+        else if (action.type === 'cancelled') showCancelledToast();
+        // ...
+    }
+}
+```
+
+---
+
+## 5. Arquitetura interna
+
+### 5.1 Dependências (camadas)
+
+```
+useBillingOrchestrator
+        │
+        ├──> useFinancialRecords (thin wrapper)
+        │       │
+        │       └──> financialRecordsRepository
+        │               │
+        │               └──> supabase (RPC + tabela)
+        │
+        ├──> useBillingContracts (composable a criar — pacotes)
+        │       │
+        │       └──> billingContractsRepository
+        │
+        ├──> useFinancialExceptions (composable — regras de exceção)
+        │       │
+        │       └──> financialExceptionsRepository
+        │
+        └──> useAgendaEvents (THIN — só pra propagação reativa, não pra writes)
+                │
+                └──> agendaRepository (já existe)
+```
+
+**Regra absoluta:** orchestrator não importa `supabase` diretamente. Só dos composables/repositories acima.
+
+### 5.2 Internals
+
+```js
+// PRIVATE — não exportado
+const _rulesCache = new Map();  // ← agora DENTRO da function, vive com a instância
+
+async function _resolveBillingState(eventId) {
+    // Snapshot completo: records[], contract?, exceptionRule?
+    // Pra decidir transição sem race conditions.
+    const records = await financialRecords.fetchByEvent(eventId);
+    const packageInfo = event.billing_contract_id
+        ? await billingContracts.fetch(event.billing_contract_id)
+        : null;
+    return { records, packageInfo };
+}
+
+async function _runTransition(event, fromStatus, toStatus, decisions, state) {
+    const key = `${fromStatus}→${toStatus}`;
+    const handler = TRANSITION_HANDLERS[key];
+    if (!handler) {
+        throw new Error(`Transição inválida: ${key}`);
+    }
+    return handler({ event, decisions, state });
+}
+
+const TRANSITION_HANDLERS = {
+    'agendado→realizado': _handleRealizado,
+    'agendado→faltou': _handleFaltou,
+    // ... 1 handler por transição válida
+};
+
+async function _handleRealizado({ event, decisions, state }) {
+    if (event.billing_contract_id) {
+        return _consumePackageSession(event);
+    }
+
+    // Sessão avulsa — criar pending se não tem record ativo
+    const hasActive = state.records.some(r => ['pending','overdue','paid'].includes(r.status));
+    if (hasActive) {
+        return [{ type: 'noop', reason: 'Record já existe' }];
+    }
+    const record = await financialRecords.create({
+        patient_id: event.patient_id,
+        agenda_evento_id: event.id,
+        amount: event.price,
+        due_date: _eventDateISO(event)
+    });
+    return [{ type: 'created', recordId: record.id, amount: event.price }];
+}
+
+async function _handleFaltou({ event, decisions, state }) {
+    if (event.billing_contract_id) {
+        return decisions?.consumePackageSession ?? state.exceptionRule?.default_consume_on_miss
+            ? _consumePackageSession(event)
+            : [{ type: 'noop' }];
+    }
+
+    const rule = await getExceptionRule(event.tenant_id, 'patient_no_show');
+    if (!rule || rule.charge_mode === 'none') {
+        return _cancelExistingPending(state.records);
+    }
+    // ... lógica completa
+}
+```
+
+### 5.3 Idempotência — como o orchestrator garante
+
+Antes de criar record:
+```js
+// 1. Snapshot da state ANTES da decisão (já feito em _resolveBillingState)
+// 2. Verificar se record ativo já existe pro evento+intenção
+const existingActive = state.records.find(r =>
+    ['pending', 'overdue', 'paid'].includes(r.status)
+);
+if (existingActive) {
+    // Decidir: noop, update, ou criar segundo (raro — multa em cima de sessão paid)
+}
+
+// 3. Locks otimistas via UPDATE com .eq('status', expectedStatus)
+//    Se conflito, refresh + re-decide
+```
+
+Antes de update/cancel:
+```js
+// Sempre filtra .eq('tenant_id', tid) defesa em profundidade
+// (corrige divergências do audit baseline)
+```
+
+Para mudanças de pacote:
+```js
+// REFRESH FRESH do banco antes do UPDATE (memória project_agenda_reverse_transitions)
+const currentContract = await billingContracts.fetch(id);
+await billingContracts.update(id, {
+    sessions_used: currentContract.sessions_used - 1
+});
+```
+
+### 5.4 RPC `create_financial_record_for_session` — usar como single insert path
+
+A RPC já existe e tem idempotência (memória `project_rpc_idempotency_cancelled` foi fix recente). Orchestrator usa ela como **única forma de criar record de sessão**. INSERT direto fica APENAS pra `createManualRecord` (lançamento avulso sem evento), que continua em `useFinancialRecords.createManualRecord`.
+
+---
+
+## 6. Plano de migração (faseado, Módulo 4)
+
+### Fase A — Foundation (preparar terreno)
+1. Criar `features/financeiro/services/` com:
+   - `_tenantGuards.js` (copy do agenda)
+   - `financialSelects.js` (extrair `BASE_SELECT` atual)
+   - `financialRecordsRepository.js` (extrair queries do `useFinancialRecords`)
+   - `financialExceptionsRepository.js` (novo — pra `financial_exceptions`)
+   - `billingContractsRepository.js` (novo — pra `billing_contracts`)
+2. Adicionar `.eq('tenant_id', tid)` em todas operações (fix do audit alta sev).
+
+### Fase B — Composables refatorados (sem mudar callers)
+1. Mover `useFinancialRecords.js` pra `features/financeiro/composables/`.
+2. Refatorar pra usar repository (thin wrapper). Aplicar canon `error = ref('')`.
+3. Criar `features/financeiro/composables/useFinancialExceptions.js`.
+4. Criar `features/financeiro/composables/useBillingContracts.js`.
+5. Criar `features/financeiro/composables/useBillingOrchestrator.js` com signature acima.
+6. Callers ainda usam `useFinancialRecords` direto + `useAgendaFinanceiro` — **nada quebra ainda**.
+
+### Fase C — Migração de callers (1 por vez)
+1. Migrar `AgendaEventDialog.vue` pra `useBillingOrchestrator.applyStatusChange` em vez de `useAgendaFinanceiro.handleStatusChange`.
+2. Migrar `useMelissaAgenda._applyStatusDecisions` (linha 1450-1505) pra orchestrator.
+3. Migrar todos os callers de `useAgendaFinanceiro.gerarCobrancaManual` → `useBillingOrchestrator.generateChargeForEvent`.
+
+### Fase D — Cleanup
+1. Deletar `src/composables/useAgendaFinanceiro.js` (callers todos migrados).
+2. Deletar `src/composables/useFinancialRecords.js` raiz (versão refatorada vive em `features/financeiro/composables/`).
+3. Remover `_exceptionsCache` módulo-level (já estava no novo composable).
+
+### Sanity checks pós-migração
+- E2E Playwright: criar sessão → realizar com pagamento → mudar pra faltou → confirmar reverse → verificar contract.sessions_used. **NUNCA double-billing.**
+- Memory `project_agenda_billing_decisoes` — confirmar 5 decisões mantidas (#1 híbrido, #4 semi-auto no-show, #5 bloqueia edit cobrada, #7 credit note, #8 pagamento separado).
+
+---
+
+## 7. Decisões resolvidas (2026-05-20)
+
+### 7.1 ✅ `applyStatusChange` faz APENAS financeiro
+
+Signature final: `applyStatusChange({ event, fromStatus, toStatus, decisions })` retorna `{ ok, actions[], needsConfirmation?, error? }`. Caller é responsável por atualizar a agenda separadamente (`agendaRepository.update()`).
+
+**Consequência:** orchestrator stateless quanto à agenda. Caller faz wrapping:
+```js
+await agendaEvents.update(event.id, { status: novoStatus });
+const billing = await billingOrchestrator.applyStatusChange({ ... });
+// Se billing.needsConfirmation, mostrar dialog. Se erro, considerar rollback do status.
+```
+
+### 7.2 ✅ Reverse confirm via `needsConfirmation` no return
+
+Quando orchestrator detecta reverse com record paid (realizado paid → agendado) ou pacote saldo consumido:
+
+```js
+// Primeira chamada — sem decisions
+const r = await billingOrchestrator.applyStatusChange({ event, fromStatus: 'realizado', toStatus: 'agendado' });
+// r = { ok: false, needsConfirmation: true, options: [
+//   { key: 'cancel_pending', label: 'Cancelar cobrança pendente', amount: 200 },
+//   { key: 'refund_paid', label: 'Estornar pagamento', amount: 200 },
+//   { key: 'manual', label: 'Resolver manualmente depois' }
+// ] }
+
+// Caller mostra dialog → user escolhe → re-chama
+const r2 = await billingOrchestrator.applyStatusChange({
+    event, fromStatus: 'realizado', toStatus: 'agendado',
+    decisions: { reverseCleanup: 'refund_paid' }
+});
+// r2 = { ok: true, actions: [{ type: 'refunded', recordId, amount }] }
+```
+
+### 7.3 ✅ Transação via RPC `apply_billing_status_transition`
+
+Toda mudança financeira de transição roda em RPC dedicada. Tudo ou nada. RPC entra como migration durante Módulo 4. Composable orchestrator faz apenas:
+1. Resolve state atual (snapshot read-only)
+2. Calcula decisões (state machine no JS)
+3. Chama RPC com plano completo (`p_actions jsonb`)
+4. RPC executa em ordem dentro de uma transação SQL
+
+Signature proposta da RPC:
+```sql
+CREATE FUNCTION public.apply_billing_status_transition(
+    p_tenant_id uuid,
+    p_event_id uuid,
+    p_actions jsonb  -- [{ kind: 'create_record', amount, due_date }, { kind: 'cancel_record', record_id }, ...]
+) RETURNS jsonb;  -- { ok, applied: [...], failed?: { kind, reason } }
+```
+
+### 7.4 ✅ Decisões #2/#3/#6 de billing — sessão dedicada antes do Módulo 4
+
+Marcar sessão dedicada (~1h) pra fechar memória `project_agenda_billing_decisoes` antes da implementação. **Bloqueador parcial do Módulo 4** — orchestrator pode ser parcialmente implementado, mas a state machine só fica completa após resolver essas 3 decisões.
+
+> ⚠️ **Pendência rastreada:** adicionar item em `dev_auditoria_items` ou agenda recorrente. Vai aparecer como **TODO inicial** na sessão de implementação do Módulo 4.
+
+---
+
+## 8. Open questions (não-bloqueantes pro design)
+
+1. **`patient_timeline` integration:** quando orchestrator cria/cancela record, devia emitir evento `pagamento_recebido` / `pagamento_vencido` em `patient_timeline`? Hoje o enum suporta, mas não vejo inserts. **Sugestão:** adicionar como trigger no banco (não no orchestrator) — fica resiliente a chamadas que escapam do orchestrator.
+
+2. **Gateway webhook (Asaas):** quando Asaas dispara webhook "paid", quem processa? Edge function dedicada que chama `financialRecords.markAsPaid(id, 'pix')`, sem passar por orchestrator (orchestrator é só pra mudanças via agenda). Documentar como caminho separado válido.
+
+3. **Repasse a terapeuta (`therapist_payouts`):** quando record fica `paid`, gera entrada em `therapist_payout_records`? Hoje não. Decisão: trigger no banco que escuta UPDATE em `financial_records.status` → cria payout. Fora do escopo do orchestrator.
+
+4. **`patient_assessments` (Fase 2):** notas clínicas com escalas têm relação com billing? Improvável — assessments são clínicos, não-monetizados. Confirmar quando implementar.
+
+---
+
+## 9. Cross-references
+
+- Memórias relevantes:
+  - `project_rpc_idempotency_cancelled.md` — RPCs ignoram cancelled
+  - `project_billing_contracts_no_updated_at.md` — gotcha de UPDATE silently failing
+  - `project_agenda_billing_decisoes.md` — 5 decisões base
+  - `project_agenda_reverse_transitions.md` — confirm dialogs pra reverter
+  - `project_cross_week_propagation.md` — pacote upfront cross-week
+  - `project_c12_antecipar_iterar.md` — antecipar pacote (Watch sync resolveu snapshot stale)
+- Audit baseline divergências Financeiro: ver `AUDIT_BASELINE.md` seção 4
+- Blueprints: `repository-blueprint.md` + `composable-blueprint.md`
+- ROADMAP: Fase 1 itens 1-4 (Monetização)
+
+---
+
+## 10. Checklist pra implementação (Módulo 4 da Fase 1)
+
+- [ ] 5 repositories criados em `features/financeiro/services/`
+- [ ] 4 composables criados em `features/financeiro/composables/`
+- [ ] `useBillingOrchestrator` com signature acima
+- [ ] State machine completa (todas transições da matriz 3.2)
+- [ ] Cache de regras dentro da instância (não módulo-level)
+- [ ] Idempotência testada (chamada 2× = noop)
+- [ ] `.eq('tenant_id', tid)` em todas mutações (defesa em profundidade)
+- [ ] RPC `apply_billing_status_transition` (decisão 7.3 opção B)
+- [ ] AgendaEventDialog migrado pra orchestrator
+- [ ] useMelissaAgenda._applyStatusDecisions migrado
+- [ ] gerarCobrancaManual callers migrados
+- [ ] useAgendaFinanceiro.js deletado
+- [ ] useFinancialRecords.js raiz deletado
+- [ ] E2E test cobrindo reverse transition (realizado paid → agendado)
+- [ ] Confirm dialogs UI implementados (memória project_agenda_reverse_transitions)

development/02-auditoria/PADRONIZACAO.md

@@ -0,0 +1,177 @@
+# Padronização — Sweep estrutural pré-MVP
+
+> **Iniciado:** 2026-05-20
+> **Deadline MVP:** 3+ meses (lançamento limpo, sem usuários)
+> **Escopo MVP:** Pacientes + Agenda + Billing + Prontuário + Financeiro avançado + Multi-tenant
+
+---
+
+## Diagnóstico
+
+Sistema tem ~487 arquivos Vue, ~75-80% MVP-ready, padronização irregular. **Agenda passou por C1-C13 + análise sênior** — é o único módulo com profundidade arquitetural. Outros módulos têm divergências (composables sem `tenant_id` consistente, SELECTs inline, page layouts inconsistentes, dialogs que não seguem o blueprint).
+
+Sem padronizar antes de escalar features novas (Fase 1 do ROADMAP), cada gap vira dívida composta.
+
+---
+
+## Estratégia em 1 frase
+
+**Agenda é a referência madura.** Extrair seus padrões em blueprints → propagar módulo a módulo → tracking em `dev_auditoria_items` com tag `padronizacao:<modulo>`. **Não tocar agenda** até a Fase 4 (apenas pendências residuais).
+
+---
+
+## Fases
+
+### Fase 0 — Fundação (3-5 dias)
+
+Extrair os blueprints faltantes a partir da agenda:
+
+- [x] `melissa-page-blueprint.md` — já existe
+- [x] `melissa-table-page-blueprint.md` — já existe
+- [x] `dialog-blueprint.md` — já existe
+- [x] `repository-blueprint.md` — entregável 1 (2026-05-20)
+- [x] `composable-blueprint.md` — entregável 2 (2026-05-20)
+- [x] `quick-create-overlay-blueprint.md` — entregável 3 (2026-05-20). Documentado como **agenda-only** com promotion criteria explícito.
+
+E baseline:
+
+- [x] Update graphify do código atual (`graphify update src/` rodou 2026-05-20)
+- [x] Audit baseline por módulo → ver `development/02-auditoria/AUDIT_BASELINE.md` (2026-05-20). 51 divergências catalogadas + 4 surpresas estruturais. **Pendente:** popular `dev_auditoria_items` no banco (decisão de batch insert vs UI).
+
+### Fase 0.5 — Pré-Fase 1 setups (pós-audit baseline)
+
+Decisões 6-9 introduzem 4 entregáveis novos antes da Fase 1:
+
+- [x] **0.5.A** Atualizar `quick-create-overlay-blueprint.md` de "agenda-only" pra universal (2026-05-20) — header reescrito, seção 9 virou "Promotion History", path convention adicionada, checklist generalizado, memória `feedback_agenda_inline_quick_create` marcada como superseded
+- [x] **0.5.B** Schema clínico modelado (2026-05-20). 4 migrations + 1 seed escritos em `database-novo/migrations/20260520000001..4_clinical_notes_*.sql` e `database-novo/seeds/seed_040_clinical_note_templates.sql`. **Não executado** — aguardando review do user pra rodar `node db.cjs migrate`. Tabelas: `clinical_notes` + `clinical_note_versions` (audit trail via trigger snapshot) + `clinical_note_templates` (6 templates do sistema: anamnese, SOAP, DAP, BIRP, evolução livre, plano padrão). FK órfã `documents.session_note_id` renomeada pra `clinical_note_id` com constraint. RLS: owner-only (CFP sigilo).
+- [x] **0.5.C** Design doc `useBillingOrchestrator` (2026-05-20) — `development/02-auditoria/DESIGN_BILLING_ORCHESTRATOR.md`. State machine de 10 transições, dependências em 4 composables/5 repositories, plano de migração faseado em 4 fases (A/B/C/D), checklist de implementação. **4 decisões resolvidas:** (1) `applyStatusChange` só financeiro, agenda separada; (2) reverse confirm via `needsConfirmation` no return; (3) transação via RPC dedicada `apply_billing_status_transition`; (4) sessão dedicada pra decisões billing #2/#3/#6 antes do Módulo 4.
+- [x] **0.5.D** Scaffold da feature `tenantship/` (2026-05-20). 7 arquivos criados em `src/features/tenantship/`: `_tenantGuards.js`, `tenantInvitesSelects.js` + `Repository.js`, `tenantMembersSelects.js` + `Repository.js`, `useTenantInvites.js`, `useTenantMembers.js`. Funções funcionais (não-stub) usando tabela existente `tenant_invites` + view `v_tenant_members_with_profiles`. **2 pendências documentadas no código:** (1) `acceptInvite()` é stub PT-BR explicando que precisa de RPC `accept_tenant_invite(p_token uuid)` — migration a criar; (2) `sendInvite()` só insere row — envio de email/WhatsApp fica pra Módulo 6 (Notificações).
+
+### Fase 1 — Padronização módulo a módulo (4-6 semanas) — **em andamento**
+
+Ordem confirmada com usuário:
+
+| # | Módulo | Por que aqui | Status |
+|---|---|---|---|
+| 1 | **Home/Dashboard + Components base** | Alta visibilidade. Inclui refactor dos 3 quick-creates promovidos (decisão 6). | ✅ **Concluído 2026-05-20** (exceto M1.6 — MelissaLayout decomposition, deferida) |
+| 2 | **Pacientes** | Núcleo de dados — alimenta agenda, prontuário, financeiro. | ✅ **Concluído 2026-05-20** (aguarda teste batch) |
+| 3 | **Prontuário/Evolução** | Schema clínico já modelado (decisão 7). | ✅ **Foundation 2026-05-20** — repositories + composables prontos. Ativa quando migrations 0.5.B rodarem. UI da aba "Prontuário evolutivo" fica pra sessão dedicada. |
+| 4 | **Financeiro/Billing** | `useBillingOrchestrator` desenhado (decisão 8). | ✅ **Foundation 2026-05-20** — 3 repositories + 4 composables novos. State machine completa + migração dos 3 callers BLOQUEADA pelas decisões #2/#3/#6 — fica pra sessão dedicada. Old `useAgendaFinanceiro.js` + `useFinancialRecords.js` continuam em paralelo. |
+| 5 | **Multi-tenant + Tenantship** | Inclui implementar feature `tenantship/` (decisão 9). | ✅ **Concluído 2026-05-20.** MembersPage em `src/views/pages/admin/MembersPage.vue` (CRUD de membros + convites) + rota `/admin/members` registrada em `routes.clinic.js`. Migration `20260520000005_accept_tenant_invite_rpc.sql` criada (RPC SECURITY DEFINER com lock FOR UPDATE anti-race). `tenantInvitesRepository.acceptInvite` agora chama RPC real (não mais stub). SaasTenantFeaturesPage refatorada — 4 queries inline + 1 RPC extraídos pra `src/services/tenantFeatureAdminService.js`. **SetupWizardPage (2648 linhas) deferido** — refator de arquivo monolítico precisa sessão dedicada. |
+| 6 | **Notificações (WhatsApp/Email)** | Depende de tudo acima. | ✅ **Foundation 2026-05-20** — `noticesSelects.js` criado + `noticeService.js` refatorado pra usar constantes. `features/conversations/services/` com repository + selects. Channel factory + refactor de `useConversations.js` (fat composable) deferidos — sessão dedicada. SMS send ainda stub. |
+
+#### Módulo 1 — sub-entregáveis
+
+- [x] **M1.1** Criar `features/medicos/` (`_tenantGuards.js`, `medicosSelects.js`, `medicosRepository.js`, `useMedicos.js`) + refatorar `CadastroRapidoMedico.vue` pra usar repository (2026-05-20). Caller único (PatientsCadastroPage) — props/emits preservados. Zero referências `supabase`/`useTenantStore`/`getOwnerId`/`getTenantId` legacy no componente. **Testado pelo user ✅**
+- [x] **M1.2** Criar `features/insurance/` (`_tenantGuards.js`, `insurancePlansSelects.js`, `insurancePlansRepository.js` com `findByName` pra uniqueness check, `useInsurancePlans.js`) + refatorar `CadastroRapidoConvenio.vue` + `InsurancePlanQuickCreateDialog.vue` (bônus da agenda) (2026-05-20). Repository agora faz duplicate check case-insensitive antes de criar — quick-create blueprint compliance. Aguardando teste.
+- [x] **M1.3** Refatorado `ComponentCadastroRapido.vue` pra usar `usePatients` composable + `getMyActiveMember()` (novo helper em `tenantship/services/tenantMembersRepository.js`) (2026-05-20). Path NÃO mudou (continua em `src/components/`) — move pra `features/patients/components/` fica pra cleanup de M2. Props deprecated mantidas pra backwards-compat dos 8 callers. **Spillover M2:** fix `patientsRepository.createPatient` (audit alta — sempre injeta owner_id do uid logado, ignora payload) + `usePatients.error: ref('')` (audit média — canon). Aguardando teste.
+- [x] **M1.4** Extraído `TEST_ACCOUNTS` de `HomeCards.vue` pra `src/config/devTestAccounts.js` (2026-05-20). HomeCards importa do novo arquivo; 6 usages funcionam idênticos.
+- [x] **M1.5** Deletado `AgendaEventDialog.vue.bak` (não estava no git, 155KB órfão no disco) (2026-05-20).
+- [ ] **M1.6** Decomposição parcial `MelissaLayout.vue` (sessão dedicada — pode ficar pra depois)
+
+#### Módulo 2 — sub-entregáveis (2026-05-20, sem pausas de teste)
+
+- [x] **M2.1** Criar `patientsSelects.js` (11 constantes — PATIENTS_SELECT_BASE + cross-feature: sessões, financial, documents, messages, recurrences, support_contacts, groups, tags). Estender `patientsRepository.js` com 15 funções novas + `resolveTenantId` helper local. Cross-feature reads ficam no patients até M4/M6 padronizarem (documentado nos comments).
+- [x] **M2.2** `usePatientDetail.js` refatorado — 4 funções internas (getPatientById, getPatientRelations, getGroupsByIds, getTagsByIds) movidas pra repository. Composable agora é thin wrapper.
+- [x] **M2.3** `usePatientFinancial.js` refatorado — `_lastPatientId` movido DENTRO da function (audit alta resolvida: state não vaza mais entre instâncias). 4 mutations (load/markPaid/markUnpaid/createRecord) delegam ao repository.
+- [x] **M2.4** `usePatientSessions.js` refatorado — list+create+updateStatus via repository. Pattern virtual→materialize preservado usando `findSessionByRecurrence` + `createPatientSession` com recurrence_id/date. Recurrence expansion (useRecurrence) intacta. `supabase.auth.getUser()` mantido como context resolution (não é data query).
+- [x] **M2.5** Quatro composables simples refatorados em paralelo: `usePatientMessages`, `usePatientDocuments`, `usePatientRecurrences`, `usePatientSupportContacts`. Cada um delega list+mutations ao repository.
+- [x] **M2.6** Cleanups: `usePatients.js` upgraded pra Tipo A canônico completo (load/getById/create/update/remove com loading/error/re-throw consistente).
+
+**Resultado:** zero `supabase.from(...)` em qualquer composable de `features/patients/composables/`. Todos os 8 composables seguem Tipo A do blueprint. `_lastPatientId` não vaza mais.
+| 2 | **Pacientes** | Núcleo de dados — alimenta agenda, prontuário, financeiro. |
+| 3 | **Prontuário/Evolução** | Schema clínico já modelado (decisão 7). Migration já aplicada. |
+| 4 | **Financeiro/Billing** | `useBillingOrchestrator` já desenhado (decisão 8). |
+| 5 | **Multi-tenant + Tenantship** | Inclui implementar feature `tenantship/` (decisão 9). |
+| 6 | **Notificações (WhatsApp/Email)** | Depende de tudo acima. |
+
+**Por módulo, sempre:**
+1. Ler estado atual
+2. Diff vs blueprints
+3. Listar divergências em `dev_auditoria_items` (tag `padronizacao:<modulo>` + severidade)
+4. Plano de fix
+5. Executar
+6. Testar (persistir HANDOFF+wiki+memória **antes** do teste manual)
+7. Commit
+8. Atualizar tracker
+9. Log no wiki
+
+### Fase 2 — Hotspots Graphify (paralela)
+
+Do `project_graphify_findings_20260504`:
+- [ ] `convertToPatient` duplicado
+- [ ] Supabase client triplo
+- [ ] 348 nós fracos
+- [ ] Setup Wizard cohesion 0.05
+
+### Fase 3 — Gaps de MVP (Fase 1 do ROADMAP)
+
+- [🟡] **Gateway Asaas (Fase A foundation 2026-05-21)** — Design doc + 2 migrations (tables + RLS) + client service + 3 Edge Function stubs (create-payment-record, cancel-payment, sync-payment). Schema: `asaas_customers`, `asaas_payments`, `asaas_webhook_events` + 5 colunas em `payment_settings`. Fase B (implementação real) depende de credenciais + decisão modelo negócio (A/B/C). Ver `development/02-auditoria/DESIGN_ASAAS_GATEWAY.md`.
+- [x] **Compliance CFP (#5/#6/#7/#8/#9 todos done · 2026-05-21)** —
+  - #5 (registro profissional): migration `20260521000003_profiles_professional_registration.sql` — adiciona `professional_registration_type` (CHECK 8 conselhos) + `_number` + `_uf`.
+  - #6 (consent forms editáveis): migration `20260521000005_document_templates_consent_types.sql` estende CHECK com `termo_lgpd` + `autorizacao_gravacao`. `seed_060_consent_forms_extra.sql` insere 2 templates novos (LGPD + Gravação) + UPDATE no `tcle_online` adicionando cláusula LGPD. Biblioteca completa: TCLE base, tcle_online (telehealth), autorizacao_menor, termo_sigilo, termo_lgpd, autorizacao_gravacao + UI já existente (`DocumentTemplatesPage` + `DocumentTemplateEditor`).
+  - #7 (assinatura eletrônica no portal): 2 migrations RPC — `20260521000006` cria `sign_document_by_signature_id` + `sign_document_by_token` + `get_signable_document_by_token` (IP/UA capturados server-side via `inet_client_addr()` + `current_setting('request.headers')`); `20260521000007` cria `list_my_signatures` (cruzamento auth.uid() por 3 caminhos). `DocumentSignatures.service` estendido. `useDocumentSignatures` composable novo. `PortalDocumentos.vue` lista pendências do paciente logado. `SharedDocumentPage.vue` estendida com painel azul de assinatura (aviso LGPD + checkbox aceite + Assinar/Recusar). `DocumentSignatureDialog` (terapeuta-side, já existia) ganha checkbox "Gerar link público" + select de validade + bloco com URL gerado/copy.
+  - #8 (nome social): JÁ INTEGRADO — `patients.nome_social` schema existia + UI em 7 arquivos.
+  - #9 (especialidades): `20260521000004_specialties.sql` (tabela + profile_specialties M:N + RLS) + `seed_050_specialties.sql` (33 specialties) + `src/services/specialtiesService.js`.
+- [x] **Recibo profissional PDF (#14 · 2026-05-21)** — `valorExtenso.js` helper pt-BR. `DocumentGenerate.service` puxa registro profissional do profile (auto-formato `CRP 12345/SP`), formata `cpf_cnpj` do tenant, computa `valor`+`valor_extenso`, mapeia `templateTipo` → `tipo_documento` (recibo_pagamento → 'recibo'). Migration `20260521000008` substitui `{{terapeuta_crp}}` por `{{terapeuta_registro}}` no template — universal pra qualquer conselho. `emitirReciboParaSessao(eventoId, opts)` é quick path one-call. Botão "Emitir recibo" no `AgendaEventoFinanceiroPanel` quando `record.status === 'paid'`. #15 NFS-e ainda em aberto.
+- [x] **§1.3 UX block 3/4 (#10 + #11 + #13 · 2026-05-21)** —
+  - #10 Busca global: `GlobalSearch.vue` (RPC `search_global`) já estava completo no AppTopbar/Rail. **MelissaBusca promovida** de client-side preview pra RPC com debounce 200ms + searchSeq. 3 grupos novos (rpc-appointments, rpc-documents, rpc-intakes). `@paciente` no MelissaLayout corrigido pra navegar pro paciente clicado (era bug — ignorava payload).
+  - #11 Recently viewed: `composables/useRecentPatients.js` (localStorage por user_id, max 5, dedup, eventos sync entre instâncias). `registerPatientVisit` chamado em `MelissaPaciente.loadAll` + `PatientProntuario.loadDetail`. Grupo "Acessados recentemente" no GlobalSearch + MelissaBusca quando query vazia.
+  - #13 Relatórios export: `services/reportExport.service.js` com 3 funções (PDF via pdf.service, Excel via exceljs com import dinâmico, CSV vanilla). 3 botões no header de `RelatoriosPage.vue` e `MelissaRelatorios.vue`.
+- [ ] **#12 Papel timbrado (BLOQUEADO)** — código no UniaoApp (projeto externo). Quando user importar o código, plugar como variável `cabecalho_html`/`rodape_html` global em `document_templates` ou criar setting `tenants.letterhead_html`.
+- [ ] NFS-e emissão (#15) — Esforço L, decisão de provider pendente (Focus NF-e vs prefeitura direta).
+- [ ] E2E Playwright crítico (#16)
+- [ ] Sentry (#18)
+
+### Fase 4 — Agenda residual
+
+- [x] **Popover snapshot stale** (commit `f83315b` durante C11) — watch em `MelissaLayout` cobre virtual→materializada.
+- [x] **Reverse transition confirm dialogs** (commit `5684297` durante C11) — `ctx.reverseArtifacts` + dialog.
+- [x] **Decomposição agenda (Fases A+B1+B2 · 2026-05-21)** — `useMelissaAgenda.js` saiu de 3033L → 2042L (-991L, ~33%). 3 utils + 1 service novo (`agendaBilling.service`).
+  - Fase A: `features/agenda/utils/{eventoTipo,dbFields,timeHelpers,colors}.js`
+  - Fase B1 (commit `e7e3d1b`): service ganha `computeSeriePrice`, `generateOccurrenceDates`, `loadStatusChangeContext`, `needsStatusConfirmDialog`.
+  - Fase B2 (commit `049dd91`): service ganha `applyStatusDecisions`, `createPackageContract`, `materializeAndChargePerSession`.
+- [x] **Replicação Rail + Clínica (Fases C+D · 2026-05-21)** —
+  - Composable novo `useAgendaStatusChange` (Tipo A wrapper) reusável em qualquer page.
+  - Fase C (commit `034c2c0`): `AgendaTerapeutaPage.onUpdateSeriesEvent` refatorado + `AgendaStatusChangeConfirmDialog` plugado. Antes era `update(id, {status})` cru; agora cobre multa + pacote saldo + reverse.
+  - Fase D (commit `6807b44`): `AgendaClinicaPage` espelha Fase C com adaptações (`updateClinic`+`createClinic` recebem `tenantId` arg).
+- [x] **C12 antecipar UX iter** (commits `9c518a2` + `b7f3c23`) — "Trocar método" pattern (UPDATE em vez de cancel cycle) + filtro cancelled no dialog Lançamentos.
+- [ ] **Indicadores visuais 3 canais** (barra esquerda verde / badge $ amber / neutro) — replicar no Rail/Clínica. Custom event classNames do FullCalendar, requer `_paymentStateMap` bulk-load igual ao Melissa.
+- [ ] **Popover Rail antecipar/revogar/trocar método** — Rail não tem popover separado (usa AgendaEventDialog direto), precisa refactor maior pra acomodar.
+- [ ] **Doc de ajuda completa** — user enviará prompt específico.
+
+---
+
+## Decisões tomadas
+
+### Estratégicas iniciais (2026-05-20)
+1. **Ordem dos módulos** ✅ Confirmada acima
+2. **Tracker** ✅ Reusar `dev_auditoria_items` com tag `padronizacao:<modulo>`. Zero migration. View materializada agrupa por módulo se virar útil pra UI.
+3. **Cadência** ✅ Validação por entregável (cada blueprint vira sessão antes de propagar)
+4. **Agenda intocada** ✅ Até Fase 4
+5. **Skills novas** Só `/audit-module <nome>` — minimalista. Outras só se emergir necessidade.
+
+### Pós-audit baseline (2026-05-20)
+6. **Quick-create blueprint** ✅ **Promover pra universal** (3 candidates já existem fora da agenda). Refatorar `CadastroRapidoMedico.vue` + `CadastroRapidoConvenio.vue` + `ComponentCadastroRapido.vue` em paralelo no módulo 1.
+7. **Schema clínico do prontuário** ✅ **Modelar agora** (sessão dedicada antes da Fase 1). Sai com migration pronta de `patient_notes`/`clinic_sessions`/anamnese/evolução/plano terapêutico.
+8. **Overlap billing agenda ↔ financeiro** ✅ **Consolidar em 1 composable orquestrador** (`useBillingOrchestrator`). Resolve risco double-billing antes do refactor de Financeiro.
+9. **Convites/membership** ✅ **Feature separada `tenantship/`** com services + composables + página `/admin/members`. Semântica clara: gestão de membership.
+
+---
+
+## Antipadrão a evitar
+
+- ❌ Refatorar tudo de uma vez (= nunca lançar)
+- ❌ Tocar agenda durante a sweep (= regressão garantida)
+- ❌ Pular o tracking em `dev_auditoria_items` (= perder rastreabilidade)
+- ❌ Aplicar blueprint sem antes auditar divergências (= refazer trabalho)
+
+---
+
+## Referências
+
+- Blueprints: `D:\leonohama\AgenciaPsi.com.br\Sistema\agenciapsi-primesakai\blueprints/`
+- Agenda canônica: `src/features/agenda/services/` + `src/features/agenda/composables/useAgendaEvents.js`
+- Tracker: tabela `dev_auditoria_items` (UI em `/saas/desenvolvimento`)
+- Memória: `project_padronizacao_sweep.md`
+- ROADMAP de features (não confundir): `development/04-roadmap/ROADMAP.md`

src/components/AjudaDrawer.vue

@@ -15,7 +15,7 @@
 |--------------------------------------------------------------------------
 -->
 <script setup>
-import { ref, computed } from 'vue';
+import { ref, computed, watch, onBeforeUnmount } from 'vue';
 import { useRoute, useRouter } from 'vue-router';
 import { useAjuda } from '@/composables/useAjuda';
 
@@ -73,6 +73,24 @@ function fechar() {
     faqAbertos.value = {};
     closeDrawer();
 }
+
+// ── Fechar ao clicar fora ─────────────────────────────────────
+// Listener so existe enquanto o drawer esta aberto. Clique nos botoes
+// que abrem/fecham o drawer (marcados com data-ajuda-toggle) sao
+// ignorados — senao fecha aqui e o @click reabre.
+function onDocMouseDown(e) {
+    if (!drawerOpen.value) return;
+    const t = e.target;
+    if (!(t instanceof Element)) return;
+    if (t.closest('.ajuda-panel')) return;        // dentro do drawer
+    if (t.closest('[data-ajuda-toggle]')) return; // botao trigger
+    closeDrawer();
+}
+watch(drawerOpen, (open) => {
+    if (open) document.addEventListener('mousedown', onDocMouseDown, true);
+    else document.removeEventListener('mousedown', onDocMouseDown, true);
+});
+onBeforeUnmount(() => document.removeEventListener('mousedown', onDocMouseDown, true));
 // ── Highlight de elemento na página ──────────────────────────
 async function handleDocClick(e) {
     const anchor = e.target.closest('a[data-highlight]');

src/components/AppOfflineOverlay.vue

@@ -17,31 +17,61 @@
 <script setup>
 import { ref, onMounted, onBeforeUnmount } from 'vue';
 
-const isOnline = ref(true); // começa como true; detecta em onMounted
+// ── Estado ────────────────────────────────────────────────────
+// Começa otimista (true) — só marca offline com confirmação dupla.
+const isOnline = ref(true);
 const wasOffline = ref(false);
 const showReconnected = ref(false);
 
 let pollTimer = null;
 let reconnectedTimer = null;
+let consecutiveFailures = 0;
 
-// ── Detecção real: tenta buscar um recurso minúsculo ──────────
+// Em DEV, ignora completamente o polling: Vite HMR + dev server podem
+// disparar falhas pontuais que geram falso positivo constante. Em DEV,
+// só confia em navigator.onLine + eventos nativos (mais conservador).
+const IS_DEV = import.meta.env?.DEV === true;
+
+// Tolerância: precisa N falhas seguidas pra considerar offline. Evita
+// falso positivo de slow request / HMR rebuild / network blip.
+const FAILURE_THRESHOLD = 2;
+const POLL_INTERVAL = IS_DEV ? 60_000 : 30_000;
+const FETCH_TIMEOUT = 8_000;
+
+// ── Detecção: navigator.onLine primeiro, fetch como confirmação ──
+//
+// navigator.onLine é a fonte autoritativa do browser. Se for true,
+// quase certo que tem rede física. Se for false, com certeza offline.
+// O fetch só serve pra detectar "rede funciona mas servidor parado".
 async function checkConnectivity() {
+    // 1) Browser offline = confia direto, sem fetch
+    if (typeof navigator !== 'undefined' && navigator.onLine === false) {
+        consecutiveFailures = FAILURE_THRESHOLD;
+        setOffline();
+        return;
+    }
+
+    // 2) Browser online — confirma com HEAD no favicon (rápido, cacheável)
     try {
-        // favicon do próprio app (cache busted) — não depende de rede externa
         await fetch('/favicon.ico?_t=' + Date.now(), {
             method: 'HEAD',
             cache: 'no-store',
-            signal: AbortSignal.timeout(4000)
+            signal: AbortSignal.timeout(FETCH_TIMEOUT)
         });
+        consecutiveFailures = 0;
         setOnline();
     } catch {
-        setOffline();
+        consecutiveFailures++;
+        // Só marca offline após N falhas consecutivas — evita falso positivo
+        // de slow request, HMR rebuild, transient blip.
+        if (consecutiveFailures >= FAILURE_THRESHOLD) {
+            setOffline();
+        }
     }
 }
 
 function setOnline() {
     if (!isOnline.value && wasOffline.value) {
-        // acabou de reconectar
         showReconnected.value = true;
         if (reconnectedTimer) clearTimeout(reconnectedTimer);
         reconnectedTimer = setTimeout(() => {
@@ -59,19 +89,25 @@ function setOffline() {
 }
 
 // ── Eventos nativos do browser ────────────────────────────────
+// navigator.onLine + offline/online events são SUPER confiáveis pra
+// estado real (sem rede física, wifi caiu, etc). Outros falsos
+// positivos vinham só do fetch agressivo.
 function onBrowserOffline() {
+    consecutiveFailures = FAILURE_THRESHOLD;
     setOffline();
 }
 function onBrowserOnline() {
+    consecutiveFailures = 0;
     checkConnectivity();
-} // confirma antes de marcar online
+}
 
 onMounted(() => {
     window.addEventListener('offline', onBrowserOffline);
     window.addEventListener('online', onBrowserOnline);
 
-    // Polling a cada 10 s — captura quedas que não disparam evento
+    // Polling defensivo — captura quedas que não disparam evento
-    pollTimer = setInterval(checkConnectivity, 10_000);
+    // (raras, ex: DNS travado em wifi público).
+    pollTimer = setInterval(checkConnectivity, POLL_INTERVAL);
 
     // Verifica estado atual ao montar (útil se já começou offline)
     checkConnectivity();

src/components/CadastroRapidoConvenio.vue

@@ -24,8 +24,7 @@
 <script setup>
 import { ref, computed, watch } from 'vue'
 import { useToast } from 'primevue/usetoast'
-import { supabase } from '@/lib/supabase/client'
+import { useInsurancePlans } from '@/features/insurance/composables/useInsurancePlans'
-import { useTenantStore } from '@/stores/tenantStore'
 
 // ─────────────────────────────────────────────────────────
 const props = defineProps({
@@ -34,35 +33,13 @@ const props = defineProps({
 })
 const emit = defineEmits(['update:modelValue', 'update:visible', 'selected'])
 
-const toast       = useToast()
+const toast = useToast()
-const tenantStore = useTenantStore()
+const insuranceStore = useInsurancePlans()
-
-// ─────────────────────────────────────────────────────────
-// Auth / tenant helpers
-// ─────────────────────────────────────────────────────────
-async function getOwnerId () {
-  const { data, error } = await supabase.auth.getUser()
-  if (error) throw error
-  const uid = data?.user?.id
-  if (!uid) throw new Error('Sessão inválida.')
-  return uid
-}
-async function getTenantId () {
-  const tid = tenantStore.tenantId || tenantStore.currentTenantId || tenantStore.tenant?.id
-  if (tid) return tid
-  const ownerId = await getOwnerId()
-  const { data, error } = await supabase
-    .from('tenant_members').select('tenant_id')
-    .eq('user_id', ownerId).eq('status', 'active')
-    .order('created_at', { ascending: false }).limit(1).single()
-  if (error) throw error
-  return data?.tenant_id
-}
 
 // ─────────────────────────────────────────────────────────
 // Estado
 // ─────────────────────────────────────────────────────────
-const plans      = ref([])
+const plans      = insuranceStore.rows  // alias reativo da lista do composable
 const loading    = ref(false)
 const searchTerm = ref('')
 
@@ -93,19 +70,11 @@ const selectedPlan = computed(() =>
 // ─────────────────────────────────────────────────────────
 async function loadPlans () {
   loading.value = true
-  try {
+  await insuranceStore.loadForOwner()
-    const ownerId = await getOwnerId()
+  if (insuranceStore.error.value) {
-    const { data, error } = await supabase
+    toast.add({ severity: 'error', summary: 'Erro', detail: insuranceStore.error.value, life: 3500 })
-      .from('insurance_plans')
+  }
-      .select('id, name, notes, default_value, active')
+  loading.value = false
-      .eq('owner_id', ownerId)
-      .eq('active', true)
-      .order('name', { ascending: true })
-    if (error) throw error
-    plans.value = data || []
-  } catch (e) {
-    toast.add({ severity: 'error', summary: 'Erro', detail: e?.message || 'Falha ao carregar convênios.', life: 3500 })
-  } finally { loading.value = false }
 }
 
 watch(() => props.visible, (v) => {
@@ -143,26 +112,17 @@ async function savePlan () {
   if (!name) { formErr.value = 'Informe o nome do convênio.'; return }
   saving.value = true; formErr.value = ''
   try {
-    const ownerId  = await getOwnerId()
+    // Repository injeta owner_id + tenant_id, sanitiza strings, faz uniqueness check (case-insensitive).
-    const tenantId = await getTenantId()
+    const data = await insuranceStore.create({
-    const payload = {
-      owner_id:      ownerId,
-      tenant_id:     tenantId,
       name,
-      notes:         String(newPlan.value.notes || '').trim() || null,
+      notes: newPlan.value.notes || null,
-      default_value: newPlan.value.default_value !== '' ? Number(newPlan.value.default_value) : null,
+      default_value: newPlan.value.default_value !== '' ? newPlan.value.default_value : null,
-      active:        true,
+    })
-    }
-    const { data, error } = await supabase
-      .from('insurance_plans').insert(payload)
-      .select('id, name, notes, default_value, active').single()
-    if (error) throw error
-    plans.value = [...plans.value, data].sort((a, b) => a.name.localeCompare(b.name))
     toast.add({ severity: 'success', summary: 'Convênio criado', detail: `"${data.name}" adicionado.`, life: 2500 })
     selectPlan(data)
   } catch (e) {
     const msg = e?.message || ''
-    formErr.value = /duplicate/i.test(msg) ? 'Já existe um convênio com esse nome.' : (msg || 'Falha ao criar.')
+    formErr.value = msg || 'Falha ao criar.'
   } finally { saving.value = false }
 }
 

src/components/CadastroRapidoMedico.vue

@@ -22,9 +22,8 @@
 <script setup>
 import { ref, computed, watch } from 'vue'
 import { useToast }      from 'primevue/usetoast'
-import { supabase }      from '@/lib/supabase/client'
-import { useTenantStore } from '@/stores/tenantStore'
 import { digitsOnly, fmtPhone } from '@/utils/validators'
+import { useMedicos } from '@/features/medicos/composables/useMedicos'
 
 // ─────────────────────────────────────────────────────────
 const props = defineProps({
@@ -33,37 +32,15 @@ const props = defineProps({
 })
 const emit = defineEmits(['update:visible', 'created', 'selected'])
 
-const toast       = useToast()
+const toast = useToast()
-const tenantStore = useTenantStore()
+const medicosStore = useMedicos()
-
-// ─────────────────────────────────────────────────────────
-// Auth / tenant
-// ─────────────────────────────────────────────────────────
-async function getOwnerId () {
-  const { data, error } = await supabase.auth.getUser()
-  if (error) throw error
-  const uid = data?.user?.id
-  if (!uid) throw new Error('Sessão inválida.')
-  return uid
-}
-async function getTenantId () {
-  const tid = tenantStore.tenantId || tenantStore.currentTenantId || tenantStore.tenant?.id
-  if (tid) return tid
-  const ownerId = await getOwnerId()
-  const { data, error } = await supabase
-    .from('tenant_members').select('tenant_id')
-    .eq('user_id', ownerId).eq('status', 'active')
-    .order('created_at', { ascending: false }).limit(1).single()
-  if (error) throw error
-  return data?.tenant_id
-}
 
 // ─────────────────────────────────────────────────────────
 // Views: 'list' | 'create' | 'edit'
 // ─────────────────────────────────────────────────────────
 const view       = ref('list')
-const medicos    = ref([])
+const medicos    = medicosStore.rows  // alias reativo da lista carregada pelo composable
-const loading    = ref(false)
+const loading    = ref(false)         // local — só pra UI da list view (composable usa loading próprio internamente)
 const searchTerm = ref('')
 const editingId  = ref(null)   // uuid do médico sendo editado
 
@@ -134,19 +111,11 @@ const filteredMedicos = computed(() => {
 // ─────────────────────────────────────────────────────────
 async function loadMedicos () {
   loading.value = true
-  try {
+  await medicosStore.loadForOwner()
-    const ownerId = await getOwnerId()
+  if (medicosStore.error.value) {
-    const { data, error } = await supabase
+    toast.add({ severity: 'error', summary: 'Erro', detail: medicosStore.error.value, life: 3500 })
-      .from('medicos')
+  }
-      .select('id, nome, crm, especialidade, telefone_profissional, clinica, cidade, estado')
+  loading.value = false
-      .eq('owner_id', ownerId)
-      .eq('ativo', true)
-      .order('nome', { ascending: true })
-    if (error) throw error
-    medicos.value = data || []
-  } catch (e) {
-    toast.add({ severity: 'error', summary: 'Erro', detail: e?.message || 'Falha ao carregar médicos.', life: 3500 })
-  } finally { loading.value = false }
 }
 
 watch(() => props.visible, async (v) => {
@@ -166,31 +135,28 @@ watch(() => props.visible, async (v) => {
 })
 
 async function loadMedicoForEdit (id) {
-  try {
+  const data = await medicosStore.fetchById(id)
-    const ownerId = await getOwnerId()
+  if (!data) {
-    const { data, error } = await supabase
+    toast.add({ severity: 'error', summary: 'Erro', detail: medicosStore.error.value || 'Médico não encontrado.', life: 3000 })
-      .from('medicos').select('*').eq('id', id).eq('owner_id', ownerId).single()
-    if (error) throw error
-    form.value = {
-      nome:                data.nome || '',
-      crm:                 data.crm || '',
-      especialidade:       data.especialidade || '',
-      especialidade_outra: '',
-      telefone_profissional: data.telefone_profissional ? fmtPhone(data.telefone_profissional) : '',
-      telefone_pessoal:      data.telefone_pessoal      ? fmtPhone(data.telefone_pessoal)      : '',
-      email:               data.email || '',
-      clinica:             data.clinica || '',
-      cidade:              data.cidade || '',
-      estado:              data.estado || 'SP',
-      observacoes:         data.observacoes || '',
-    }
-    editingId.value = id
-    view.value = 'edit'
-  } catch (e) {
-    toast.add({ severity: 'error', summary: 'Erro', detail: e?.message || 'Falha ao carregar médico.', life: 3000 })
     view.value = 'list'
     loadMedicos()
+    return
   }
+  form.value = {
+    nome:                data.nome || '',
+    crm:                 data.crm || '',
+    especialidade:       data.especialidade || '',
+    especialidade_outra: '',
+    telefone_profissional: data.telefone_profissional ? fmtPhone(data.telefone_profissional) : '',
+    telefone_pessoal:      data.telefone_pessoal      ? fmtPhone(data.telefone_pessoal)      : '',
+    email:               data.email || '',
+    clinica:             data.clinica || '',
+    cidade:              data.cidade || '',
+    estado:              data.estado || 'SP',
+    observacoes:         data.observacoes || '',
+  }
+  editingId.value = id
+  view.value = 'edit'
 }
 
 // ─────────────────────────────────────────────────────────
@@ -229,44 +195,31 @@ async function saveMedico () {
   const isUpdate = !!editingId.value
 
   try {
-    const ownerId  = await getOwnerId()
+    // Payload: owner_id e tenant_id são injetados pelo repository.
-    const tenantId = await getTenantId()
+    // Repository sanitiza trim/nullif em strings; componente só normaliza telefones (digits-only).
-
     const payload = {
-      owner_id:  ownerId,
-      tenant_id: tenantId,
       nome,
-      crm:                   String(form.value.crm || '').trim() || null,
+      crm:                   form.value.crm || null,
       especialidade:         especialidadeFinal.value,
       telefone_profissional: form.value.telefone_profissional ? digitsOnly(form.value.telefone_profissional) : null,
       telefone_pessoal:      form.value.telefone_pessoal      ? digitsOnly(form.value.telefone_pessoal)      : null,
-      email:                 String(form.value.email || '').trim() || null,
+      email:                 form.value.email || null,
-      clinica:               String(form.value.clinica || '').trim() || null,
+      clinica:               form.value.clinica || null,
-      cidade:                String(form.value.cidade || '').trim() || null,
+      cidade:                form.value.cidade || null,
-      estado:                String(form.value.estado || '').trim() || null,
+      estado:                form.value.estado || null,
-      observacoes:           String(form.value.observacoes || '').trim() || null,
+      observacoes:           form.value.observacoes || null,
-      ativo: true,
     }
 
-    let data
+    const data = isUpdate
-    if (isUpdate) {
+      ? await medicosStore.update(editingId.value, payload)
-      const { data: d, error } = await supabase
+      : await medicosStore.create(payload)
-        .from('medicos').update({ ...payload, updated_at: new Date().toISOString() })
+
-        .eq('id', editingId.value).eq('owner_id', ownerId)
+    toast.add({
-        .select('id, nome, crm, especialidade, telefone_profissional, clinica, cidade, estado')
+      severity: 'success',
-        .single()
+      summary: isUpdate ? 'Médico atualizado' : 'Médico cadastrado',
-      if (error) throw error
+      detail: `Dr(a). ${data.nome} ${isUpdate ? 'atualizado' : 'adicionado'}.`,
-      data = d
+      life: 2500
-      toast.add({ severity: 'success', summary: 'Médico atualizado', detail: `Dr(a). ${data.nome} atualizado.`, life: 2500 })
+    })
-    } else {
-      const { data: d, error } = await supabase
-        .from('medicos').insert(payload)
-        .select('id, nome, crm, especialidade, telefone_profissional, clinica, cidade, estado')
-        .single()
-      if (error) throw error
-      data = d
-      toast.add({ severity: 'success', summary: 'Médico cadastrado', detail: `Dr(a). ${data.nome} adicionado.`, life: 2500 })
-    }
 
     emit(isUpdate ? 'selected' : 'created', data)
     emit('selected', data)

src/components/ComponentCadastroRapido.vue

@@ -25,10 +25,13 @@ import { useToast } from 'primevue/usetoast';
 import InputMask from 'primevue/inputmask';
 import Message from 'primevue/message';
 
-import { supabase } from '@/lib/supabase/client';
+// Audit alta (2026-05-20): substituir supabase direto por repository pattern.
+import { usePatients } from '@/features/patients/composables/usePatients';
+import { getMyActiveMember } from '@/features/tenantship/services/tenantMembersRepository';
 const { canSee } = useRoleGuard();
 const route = useRoute();
 const router = useRouter();
+const patientsStore = usePatients();
 
 const isOnPatientsPage = computed(() => {
     const p = String(route.path || '');
@@ -145,31 +148,6 @@ function normalizePhoneDigits(v) {
     return sanitizeDigits(v);
 }
 
-async function getOwnerId() {
-    const { data, error } = await supabase.auth.getUser();
-    if (error) throw error;
-    const user = data?.user;
-    if (!user?.id) throw new Error('Usuário não encontrado. Faça login novamente.');
-    return user.id;
-}
-
-/**
- * Pega tenant_id + member_id do usuário logado.
- */
-async function resolveTenantContextOrFail() {
-    const { data: authData, error: authError } = await supabase.auth.getUser();
-    if (authError) throw authError;
-    const uid = authData?.user?.id;
-    if (!uid) throw new Error('Sessão inválida.');
-
-    const { data, error } = await supabase.from('tenant_members').select('id, tenant_id').eq('user_id', uid).eq('status', 'active').order('created_at', { ascending: false }).limit(1).single();
-
-    if (error) throw error;
-    if (!data?.tenant_id || !data?.id) throw new Error('Responsible member not found');
-
-    return { tenantId: data.tenant_id, memberId: data.id };
-}
-
 /* ----------------------------
  * Gerador (nome/email/telefone)
  * ---------------------------- */
@@ -219,8 +197,17 @@ function generateUser() {
     });
 }
 
-function patientsListRoute() {
+// Rota de destino do "Salvar e ver paciente". Em melissa, prefere a
+// view individual do paciente recém-criado (id vem de data.id no
+// emit('created')); fallback pra lista.
+function patientViewRoute(patientId) {
     const p = String(route.path || '');
+    if (p.startsWith('/melissa') && patientId) {
+        return { path: '/melissa/paciente', query: { id: String(patientId) } };
+    }
+    if (p.startsWith('/melissa')) {
+        return '/melissa/pacientes';
+    }
     return p.startsWith('/therapist') ? '/therapist/patients' : '/admin/pacientes';
 }
 
@@ -240,29 +227,30 @@ async function submit(mode = 'only') {
 
     saving.value = true;
     try {
-        const ownerId = await getOwnerId();
+        // Resolve tenant_member ativo via repository (audit: não mais supabase direto)
-        const { tenantId, memberId } = await resolveTenantContextOrFail();
+        const member = await getMyActiveMember();
+        if (!member?.id || !member?.tenant_id) {
+            throw new Error('Responsible member not found');
+        }
 
-        // extraPayload antes; tenant/responsible forçados depois (não podem ser sobrescritos sem querer)
+        // Payload canônico — campos hardcoded da tabela patients.
+        // Props deprecated (tableName/ownerField/etc) são ignoradas internamente.
+        // owner_id é injetado pelo repository (auth.uid()) — não passamos aqui.
+        // extraPayload pode trazer status, observações, etc.
         const payload = {
             ...props.extraPayload,
-
+            tenant_id: member.tenant_id,
-            [props.ownerField]: ownerId,
+            responsible_member_id: member.id,
-            [props.tenantField]: tenantId,
+            nome_completo: nome,
-            [props.responsibleMemberField]: memberId,
+            email_principal: email.toLowerCase(),
-
+            telefone: normalizePhoneDigits(tel)
-            [props.nameField]: nome,
-            [props.emailField]: email.toLowerCase(),
-            [props.phoneField]: normalizePhoneDigits(tel)
         };
 
         Object.keys(payload).forEach((k) => {
             if (payload[k] === undefined) delete payload[k];
         });
 
-        const { data, error } = await supabase.from(props.tableName).insert(payload).select().single();
+        const data = await patientsStore.create(payload);
-
-        if (error) throw error;
 
         toast.add({
             severity: 'success',
@@ -273,7 +261,10 @@ async function submit(mode = 'only') {
 
         emit('created', data);
         if (props.closeOnCreated) close();
-        if (mode === 'view') await router.push(patientsListRoute());
+        if (mode === 'view') {
+            const pid = data?.id || null;
+            await router.push(patientViewRoute(pid));
+        }
     } catch (err) {
         const msg = err?.message || err?.details || 'Não foi possível criar o paciente.';
         errorMsg.value = msg;
@@ -355,10 +346,10 @@ async function submit(mode = 'only') {
                 <!-- Na rota de pacientes OU em fluxo (hideViewListButton): só "Salvar" / "Salvar e fechar" -->
                 <Button v-if="isOnPatientsPage" label="Salvar" :loading="saving" :disabled="saving" @click="submit('only')" />
                 <Button v-else-if="hideViewListButton" label="Salvar e fechar" :loading="saving" :disabled="saving" @click="submit('only')" />
-                <!-- Standalone fora da lista: "Salvar e fechar" + "Salvar e ver pacientes" -->
+                <!-- Standalone fora da lista: "Salvar e fechar" + "Salvar e ver paciente" -->
                 <template v-else>
                     <Button label="Salvar e fechar" severity="secondary" outlined :loading="saving" :disabled="saving" @click="submit('only')" />
-                    <Button label="Salvar e ver pacientes" :loading="saving" :disabled="saving" @click="submit('view')" />
+                    <Button label="Salvar e ver paciente" :loading="saving" :disabled="saving" @click="submit('view')" />
                 </template>
             </div>
         </template>

src/components/agenda/AgendaEventoFinanceiroPanel.vue

@@ -36,6 +36,7 @@ import { useConfirm } from 'primevue/useconfirm';
 
 import { supabase } from '@/lib/supabase/client';
 import { useAgendaFinanceiro } from '@/composables/useAgendaFinanceiro';
+import { emitirReciboParaSessao } from '@/services/DocumentGenerate.service';
 
 // ── props / emits ─────────────────────────────────────────────────────────────
 const props = defineProps({
@@ -56,6 +57,7 @@ const { gerarCobrancaManual, loading: finLoading, error: finError } = useAgendaF
 const record = ref(null); // financial_record vinculado
 const fetching = ref(false);
 const generating = ref(false);
+const emittingRecibo = ref(false);
 
 // ── opções de método de pagamento ─────────────────────────────────────────────
 const PAYMENT_METHODS = [
@@ -100,16 +102,35 @@ const scenario = computed(() => {
 
 const canAct = computed(() => record.value && (record.value.status === 'pending' || record.value.status === 'overdue'));
 
+// Sessão encerrada (não rolou) — bloqueia geração de cobrança nova.
+// Multa em cancelado/faltou deve passar pelo AgendaStatusChangeConfirmDialog,
+// não por "Gerar cobrança" solto que ignora o motivo.
+const isSessaoEncerrada = computed(() => {
+    const s = String(props.evento?.status || '').toLowerCase();
+    return s === 'cancelado' || s === 'cancelada' || s === 'faltou';
+});
+const semCobrancaLabel = computed(() => {
+    const s = String(props.evento?.status || '').toLowerCase();
+    if (s === 'cancelado' || s === 'cancelada') return 'Sessão cancelada · sem cobrança ativa';
+    if (s === 'faltou') return 'Sessão não realizada · sem cobrança ativa';
+    return 'Sem cobrança gerada';
+});
+
 // ── buscar financial_record pelo evento ───────────────────────────────────────
 async function fetchRecord() {
     if (!props.evento.id) return;
 
     fetching.value = true;
     try {
+        // Ignora records cancelados — permite que o user gere nova cobrança
+        // após cancelar (caso comum: cancelou sem querer ou quer recobrar).
+        // Sem esse filtro, o scenario ficava em 'com-cobranca' mostrando
+        // o cancelado, e o botão "Gerar cobrança" sumia.
         const { data, error } = await supabase
             .from('financial_records')
             .select('id, amount, discount_amount, final_amount, status, due_date, paid_at, payment_method')
             .eq('agenda_evento_id', props.evento.id)
+            .neq('status', 'cancelled')
             .order('created_at', { ascending: false })
             .limit(1)
             .maybeSingle();
@@ -205,6 +226,27 @@ function requestCancel() {
         }
     });
 }
+
+// ── Emitir recibo PDF da sessão ─────────────────────────────────────────────
+// Gera, salva (Storage + documents/document_generated) e baixa um recibo
+// pré-preenchido com paciente/sessão/valor/forma de pagamento + registro
+// profissional do terapeuta (CRP/CRM/CRFa etc — auto-formatado).
+async function onEmitirRecibo() {
+    if (emittingRecibo.value) return;
+    emittingRecibo.value = true;
+    try {
+        await emitirReciboParaSessao(props.evento.id, {
+            patientId: props.evento.patient_id || props.evento.paciente_id,
+            valor: record.value?.final_amount ?? record.value?.amount ?? props.evento.price,
+            formaPagamento: paymentLabel(record.value?.payment_method)
+        });
+        toast.add({ severity: 'success', summary: 'Recibo emitido', detail: 'PDF baixado e salvo nos documentos do paciente.', life: 3000 });
+    } catch (e) {
+        toast.add({ severity: 'error', summary: 'Erro ao emitir recibo', detail: e?.message || 'Tente novamente.', life: 4500 });
+    } finally {
+        emittingRecibo.value = false;
+    }
+}
 </script>
 
 <template>
@@ -230,10 +272,13 @@ function requestCancel() {
             <div v-else-if="scenario === 'sem-cobranca'" class="fin-panel__body fin-panel__body--empty">
                 <div class="flex items-center gap-2 text-[var(--text-color-secondary)]">
                     <i class="pi pi-minus-circle text-sm opacity-50" />
-                    <span class="text-sm">Sem cobrança gerada</span>
+                    <span class="text-sm">{{ semCobrancaLabel }}</span>
                 </div>
-                <Button label="Gerar cobrança" icon="pi pi-plus" size="small" class="rounded-full mt-2" :loading="generating || finLoading" @click="onGerarCobranca" />
+                <!-- Botão "Gerar cobrança" só aparece em status ativo (agendado/realizado).
-                <div v-if="props.evento.price" class="text-xs text-[var(--text-color-secondary)] mt-1">Valor da sessão: {{ fmtBRL(props.evento.price) }}</div>
+                     Pra cancelado/faltou: sessão não aconteceu → cobrança nova não cabe
+                     aqui. Pra registrar multa, usar o dialog de status change. -->
+                <Button v-if="!isSessaoEncerrada" label="Gerar cobrança" icon="pi pi-plus" size="small" class="rounded-full mt-2" :loading="generating || finLoading" @click="onGerarCobranca" />
+                <div v-if="props.evento.price && !isSessaoEncerrada" class="text-xs text-[var(--text-color-secondary)] mt-1">Valor da sessão: {{ fmtBRL(props.evento.price) }}</div>
             </div>
 
             <!-- ── Carregando o financial_record ────────────────────────────────── -->
@@ -270,6 +315,20 @@ function requestCancel() {
                     <Button label="Receber" icon="pi pi-check" size="small" class="rounded-full flex-1" @click="openPayDialog" />
                     <Button icon="pi pi-times" size="small" severity="danger" outlined class="rounded-full h-7 w-7" v-tooltip.top="'Cancelar cobrança'" @click="requestCancel" />
                 </div>
+
+                <!-- Ação: pago — emitir recibo PDF -->
+                <div v-else-if="record.status === 'paid'" class="flex gap-1.5 mt-3">
+                    <Button
+                        label="Emitir recibo"
+                        icon="pi pi-file-pdf"
+                        size="small"
+                        outlined
+                        class="rounded-full flex-1"
+                        :loading="emittingRecibo"
+                        v-tooltip.top="'Gera PDF e salva nos documentos do paciente'"
+                        @click="onEmitirRecibo"
+                    />
+                </div>
             </div>
         </div>
 

src/components/search/GlobalSearch.vue

@@ -15,9 +15,11 @@ import InputText from 'primevue/inputtext';
 import { supabase } from '@/lib/supabase/client';
 import { useTenantStore } from '@/stores/tenantStore';
 import { searchPages } from './pagesIndex';
+import { useRecentPatients } from '@/composables/useRecentPatients';
 
 const router = useRouter();
 const tenantStore = useTenantStore();
+const { items: recentPatients, hasItems: hasRecentPatients } = useRecentPatients();
 
 // ────────────────────────────────────────────────────────────
 // State
@@ -67,9 +69,14 @@ const filteredPages = computed(() => {
 // ────────────────────────────────────────────────────────────
 // Flat list pra navegação por teclado
 // ────────────────────────────────────────────────────────────
+// Recently-viewed só aparece quando a query está vazia — não polui resultados de busca.
+const showRecent = computed(() => !query.value.trim() && hasRecentPatients.value);
+const recentItems = computed(() => showRecent.value ? (recentPatients.value || []).slice(0, 5) : []);
+
 const flatList = computed(() => {
     const out = [];
     filteredActions.value.forEach((a, i)         => out.push({ group: 'actions',      item: a, idx: i }));
+    recentItems.value.forEach((p, i)             => out.push({ group: 'recent',       item: p, idx: i }));
     results.value.patients.forEach((p, i)        => out.push({ group: 'patients',     item: p, idx: i }));
     results.value.intakes.forEach((r, i)         => out.push({ group: 'intakes',      item: r, idx: i }));
     results.value.appointments.forEach((a, i)    => out.push({ group: 'appointments', item: a, idx: i }));
@@ -195,6 +202,16 @@ function onInputKeydown(e) {
 }
 
 async function goTo(entry) {
+    // Recent patients: usa id pra navegar pro prontuário do paciente
+    if (entry?.group === 'recent' && entry?.item?.id) {
+        showPanel.value = false;
+        query.value = '';
+        resetResults();
+        activeIndex.value = -1;
+        await router.push({ path: '/therapist/patients/' + entry.item.id });
+        return;
+    }
+
     const target = entry?.item?.to || entry?.item?.deeplink || entry?.item?.path;
     if (!target) return;
     showPanel.value = false;
@@ -266,6 +283,27 @@ const kbdModifier = kbdIsMac ? '⌘' : 'Ctrl';
             </div>
 
             <template v-else>
+                <!-- Acessados recentemente (só quando query vazia) -->
+                <div v-if="showRecent" class="gs-group">
+                    <div class="gs-group__title">Acessados recentemente</div>
+                    <button
+                        v-for="(p, i) in recentItems"
+                        :key="'rp-' + p.id"
+                        type="button"
+                        class="gs-item"
+                        :class="{ 'is-active': findFlatIndex('recent', i) === activeIndex }"
+                        @mouseenter="activeIndex = findFlatIndex('recent', i)"
+                        @click="goTo({ group: 'recent', item: p, idx: i })"
+                    >
+                        <span class="gs-item__icon"><i class="pi pi-history" /></span>
+                        <span class="gs-item__main">
+                            <span class="gs-item__label">{{ p.nome }}</span>
+                            <span class="gs-item__sub">{{ p.extras?.telefone || p.extras?.email || 'Abrir prontuário' }}</span>
+                        </span>
+                        <i class="gs-item__go pi pi-arrow-right" />
+                    </button>
+                </div>
+
                 <!-- Ações -->
                 <div v-if="filteredActions.length" class="gs-group">
                     <div class="gs-group__title">{{ query.trim() ? 'Ações' : 'Atalhos' }}</div>

src/components/search/pagesIndex.js

@@ -34,7 +34,7 @@ export const PAGES = [
     { id: 'p_t_medicos',          label: 'Médicos referenciadores',       icon: 'pi pi-user-edit',    sublabel: 'Médicos que encaminham pacientes',    path: '/therapist/patients/medicos',              roles: ['therapist'],                       keywords: kw('medicos','encaminhadores','referenciadores','indicacao') },
     { id: 'p_t_link_externo',     label: 'Link de cadastro externo',      icon: 'pi pi-link',         sublabel: 'Link público pra pacientes',          path: '/therapist/patients/link-externo',         roles: ['therapist'],                       keywords: kw('link','externo','publico','cadastro paciente','convite') },
     { id: 'p_t_cad_recebidos',    label: 'Cadastros recebidos',           icon: 'pi pi-inbox',        sublabel: 'Pacientes aguardando aceite',         path: '/therapist/patients/cadastro/recebidos',   roles: ['therapist'],                       keywords: kw('recebidos','pendentes','aceitar','intake','novos') },
-    { id: 'p_t_doc_templates',    label: 'Templates de documentos',       icon: 'pi pi-file-edit',    sublabel: 'Modelos reutilizáveis',               path: '/therapist/documents/templates',           roles: ['therapist'],                       keywords: kw('templates','modelos','contratos','documentos') },
+    { id: 'p_cfg_doc_templates',  label: 'Modelos de documentos',         icon: 'pi pi-file-edit',    sublabel: 'Configurações → Documentos',          path: '/configuracoes/documentos/templates',      roles: ['therapist','admin'],               keywords: kw('templates','modelos','contratos','documentos','recibo','atestado','laudo','tcle','lgpd','consent') },
     { id: 'p_t_online_sched',     label: 'Agendamento online',            icon: 'pi pi-globe',        sublabel: 'Página pública de agendamento',       path: '/therapist/online-scheduling',             roles: ['therapist'],                       keywords: kw('online','publico','agendar','landing','pagina','site') },
     { id: 'p_t_ag_recebidos',     label: 'Agendamentos recebidos',        icon: 'pi pi-calendar-plus',sublabel: 'Solicitações da agenda pública',      path: '/therapist/agendamentos-recebidos',        roles: ['therapist'],                       keywords: kw('solicitacoes','recebidos','publico','pedidos') },
     { id: 'p_t_fin_lanc',         label: 'Lançamentos financeiros',       icon: 'pi pi-list',         sublabel: 'Entradas e saídas',                   path: '/therapist/financeiro/lancamentos',        roles: ['therapist'],                       keywords: kw('lancamentos','entradas','saidas','fluxo de caixa','receitas','despesas') },

src/components/ui/JoditEmailEditor.vue

@@ -117,14 +117,14 @@ function buildConfig() {
     ];
 
     // Toolbar completa para o corpo do e-mail
+    // Botões hr (linha horizontal), eraser (apagar formatação) e source (HTML)
+    // foram removidos — não funcionavam de forma esperada.
     const bodyButtons = [
         'bold', 'italic', 'underline', 'strikethrough', '|',
         'ul', 'ol', '|',
         'font', 'fontsize', 'brush', 'paragraph', '|',
         'align', '|',
-        'link', 'table', '|',
+        'link', 'table'
-        'hr', 'eraser', '|',
-        'source'
     ];
 
     return {
@@ -194,7 +194,24 @@ watch(
 
 // ── API exposta ───────────────────────────────────────────────
 defineExpose({
-    insertHTML: (html) => jodit?.selection.insertHTML(html)
+    insertHTML: (html) => jodit?.selection.insertHTML(html),
+    // Salva markers da seleção atual antes do foco sair do editor
+    // (ex: usuário abre drawer e perde o cursor). Retorna o array de
+    // markers que pode ser passado pra restoreSelection depois.
+    saveSelection: () => {
+        if (!jodit) return null;
+        try { return jodit.selection.save(); }
+        catch { return null; }
+    },
+    // Restaura selection a partir dos markers salvos. Re-foca o editor.
+    restoreSelection: (markers) => {
+        if (!jodit) return;
+        try {
+            jodit.focus();
+            if (markers) jodit.selection.restore(markers);
+        } catch { /* silencioso */ }
+    },
+    focus: () => jodit?.focus()
 });
 </script>
 

src/components/ui/PatientCadastroDialog.vue

@@ -65,11 +65,22 @@ const router = useRouter();
 
 const isOnPatientsPage = computed(() => {
     const p = String(route.path || '');
-    return p.includes('/patients') || p.includes('/pacientes');
+    // /melissa/paciente (singular — prontuário) é página de paciente.
+    // /melissa/pacientes (plural — lista) também.
+    return p.includes('/patients') || p.includes('/pacientes') || p.startsWith('/melissa/paciente');
 });
 
-function patientsListRoute() {
+// Rota de destino quando o usuário pede "Salvar e ver paciente":
+// — no Melissa, abre o prontuário do paciente (singular, via query id)
+// — no Therapist/Admin, volta pra lista (não há rota dedicada de view).
+function patientViewRoute(patientId) {
     const p = String(route.path || '');
+    if (p.startsWith('/melissa') && patientId) {
+        return { path: '/melissa/paciente', query: { id: String(patientId) } };
+    }
+    if (p.startsWith('/melissa')) {
+        return '/melissa/pacientes';
+    }
     return p.startsWith('/therapist') ? '/therapist/patients' : '/admin/pacientes';
 }
 
@@ -82,7 +93,9 @@ async function onCreated(data) {
     isOpen.value = false;
     emit('created', data);
     if (pendingMode.value === 'view') {
-        await router.push(patientsListRoute());
+        // data.id vem do PatientsCadastroPage (criação ou edição)
+        const pid = data?.id || props.patientId || null;
+        await router.push(patientViewRoute(pid));
     }
 }
 </script>
@@ -197,10 +210,10 @@ async function onCreated(data) {
                 <!-- Na rota de pacientes OU em fluxo (hideViewListButton): só um botao -->
                 <Button v-if="isOnPatientsPage" label="Salvar" :loading="!!pageRef?.saving?.value" :disabled="!!pageRef?.saving?.value || !!pageRef?.deleting?.value" @click="submitWith('only')" />
                 <Button v-else-if="hideViewListButton" label="Salvar e fechar" :loading="!!pageRef?.saving?.value" :disabled="!!pageRef?.saving?.value || !!pageRef?.deleting?.value" @click="submitWith('only')" />
-                <!-- Standalone fora da lista: "Salvar e fechar" + "Salvar e ver pacientes" -->
+                <!-- Standalone fora da lista: "Salvar e fechar" + "Salvar e ver paciente" -->
                 <template v-else>
                     <Button label="Salvar e fechar" severity="secondary" outlined :loading="pendingMode === 'only' && !!pageRef?.saving?.value" :disabled="!!pageRef?.saving?.value || !!pageRef?.deleting?.value" @click="submitWith('only')" />
-                    <Button label="Salvar e ver pacientes" :loading="pendingMode === 'view' && !!pageRef?.saving?.value" :disabled="!!pageRef?.saving?.value || !!pageRef?.deleting?.value" @click="submitWith('view')" />
+                    <Button label="Salvar e ver paciente" :loading="pendingMode === 'view' && !!pageRef?.saving?.value" :disabled="!!pageRef?.saving?.value || !!pageRef?.deleting?.value" @click="submitWith('view')" />
                 </template>
             </div>
         </template>

src/composables/useAgendaFinanceiro.js

@@ -56,7 +56,7 @@ const STATUS_TO_EXCEPTION = {
 function calcChargeAmount(originalAmount, rule) {
     if (!rule || rule.charge_mode === 'none') return 0;
     if (rule.charge_mode === 'full') return originalAmount;
-    if (rule.charge_mode === 'fixed') return rule.charge_value ?? 0;
+    if (rule.charge_mode === 'fixed_fee') return rule.charge_value ?? 0;
     if (rule.charge_mode === 'percentage') {
         const pct = rule.charge_pct ?? 0;
         return parseFloat(((originalAmount * pct) / 100).toFixed(2));

src/composables/useFinancialRecords.js

@@ -39,9 +39,9 @@ async function getUid() {
 
 const BASE_SELECT = `
   id, tenant_id, owner_id, patient_id, agenda_evento_id,
-  amount, discount_amount, final_amount,
+  type, amount, discount_amount, final_amount,
-  status, due_date, paid_at, payment_method,
+  status, due_date, paid_at, payment_method, payment_link,
-  notes, created_at, updated_at,
+  description, notes, created_at, updated_at,
   patients!patient_id (
     id, nome_completo, identification_color
   ),

src/composables/useRecentPatients.js

@@ -0,0 +1,171 @@
+/*
+|--------------------------------------------------------------------------
+| Agência PSI
+|--------------------------------------------------------------------------
+| Arquivo: src/composables/useRecentPatients.js
+|
+| Tracking dos últimos pacientes acessados pelo usuário logado.
+| Armazenado em localStorage por user_id pra isolar sessões diferentes
+| no mesmo browser (multi-conta).
+|
+| Usado pelo GlobalSearch.vue / MelissaBusca.vue como "recently viewed"
+| quando o input está vazio, e pode ser embedido em dashboards.
+|--------------------------------------------------------------------------
+*/
+import { ref, computed, onMounted, onBeforeUnmount } from 'vue';
+import { supabase } from '@/lib/supabase/client';
+
+const MAX_ITEMS = 5;          // top N exibido
+const STORAGE_PREFIX = 'agpsi:recent-patients:';
+const STORAGE_EVENT = 'agpsi:recent-patients:changed';
+
+function storageKey(userId) {
+    return `${STORAGE_PREFIX}${userId || 'anon'}`;
+}
+
+function loadFromStorage(userId) {
+    try {
+        const raw = localStorage.getItem(storageKey(userId));
+        if (!raw) return [];
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    } catch {
+        return [];
+    }
+}
+
+function saveToStorage(userId, items) {
+    try {
+        localStorage.setItem(storageKey(userId), JSON.stringify(items));
+        // Notifica outras instâncias do composable nesta mesma aba
+        window.dispatchEvent(new CustomEvent(STORAGE_EVENT, { detail: { userId } }));
+    } catch {
+        // Quota cheia / modo privado — silenciar
+    }
+}
+
+/**
+ * @returns composable reativo com `items` (array de pacientes recentes),
+ *          `addVisit(patient)` e `clear()`.
+ *
+ * Forma do patient esperado em addVisit:
+ *   { id: string, nome: string, ... } — extras (avatar, telefone, etc) são opt-in
+ *
+ * Forma do item armazenado:
+ *   { id, nome, visited_at: ISO, extras: {} }
+ */
+export function useRecentPatients() {
+    const userId = ref(null);
+    const items = ref([]);
+
+    async function resolveUserId() {
+        if (userId.value) return userId.value;
+        const { data } = await supabase.auth.getUser();
+        userId.value = data?.user?.id || 'anon';
+        return userId.value;
+    }
+
+    async function refresh() {
+        const uid = await resolveUserId();
+        items.value = loadFromStorage(uid);
+    }
+
+    async function addVisit(patient) {
+        if (!patient?.id) return;
+        const uid = await resolveUserId();
+        const current = loadFromStorage(uid);
+
+        const entry = {
+            id: String(patient.id),
+            nome: patient.nome_completo || patient.nome_social || patient.nome || '(sem nome)',
+            visited_at: new Date().toISOString(),
+            extras: {
+                nome_social: patient.nome_social || null,
+                avatar_url: patient.avatar_url || null,
+                telefone: patient.telefone || null,
+                email: patient.email_principal || patient.email || null
+            }
+        };
+
+        // Remove duplicata + insere no topo + limita a MAX_ITEMS
+        const dedup = current.filter(x => x.id !== entry.id);
+        dedup.unshift(entry);
+        const trimmed = dedup.slice(0, MAX_ITEMS);
+
+        saveToStorage(uid, trimmed);
+        items.value = trimmed;
+    }
+
+    async function remove(patientId) {
+        const uid = await resolveUserId();
+        const current = loadFromStorage(uid);
+        const filtered = current.filter(x => String(x.id) !== String(patientId));
+        saveToStorage(uid, filtered);
+        items.value = filtered;
+    }
+
+    async function clear() {
+        const uid = await resolveUserId();
+        saveToStorage(uid, []);
+        items.value = [];
+    }
+
+    // Sincroniza entre instâncias do composable na mesma aba
+    function onChange() {
+        refresh();
+    }
+    function onStorage(ev) {
+        if (typeof ev?.key === 'string' && ev.key.startsWith(STORAGE_PREFIX)) {
+            refresh();
+        }
+    }
+
+    onMounted(() => {
+        refresh();
+        window.addEventListener(STORAGE_EVENT, onChange);
+        window.addEventListener('storage', onStorage);
+    });
+
+    onBeforeUnmount(() => {
+        window.removeEventListener(STORAGE_EVENT, onChange);
+        window.removeEventListener('storage', onStorage);
+    });
+
+    const hasItems = computed(() => items.value.length > 0);
+
+    return {
+        items,
+        hasItems,
+        addVisit,
+        remove,
+        clear,
+        refresh
+    };
+}
+
+// ── Stateless helpers — usáveis fora de componentes (ex: action handlers) ──
+
+/**
+ * Registra uma visita SEM usar Vue reactivity. Útil pra hooks que não
+ * estão dentro de setup() (ex: router.beforeEach, navigation guards).
+ */
+export async function registerPatientVisit(patient) {
+    if (!patient?.id) return;
+    const { data } = await supabase.auth.getUser();
+    const uid = data?.user?.id || 'anon';
+    const current = loadFromStorage(uid);
+    const entry = {
+        id: String(patient.id),
+        nome: patient.nome_completo || patient.nome_social || patient.nome || '(sem nome)',
+        visited_at: new Date().toISOString(),
+        extras: {
+            nome_social: patient.nome_social || null,
+            avatar_url: patient.avatar_url || null,
+            telefone: patient.telefone || null,
+            email: patient.email_principal || patient.email || null
+        }
+    };
+    const dedup = current.filter(x => x.id !== entry.id);
+    dedup.unshift(entry);
+    saveToStorage(uid, dedup.slice(0, MAX_ITEMS));
+}

src/composables/useTopbarDevMenuExtras.js

@@ -0,0 +1,134 @@
+/*
+|--------------------------------------------------------------------------
+| Agência PSI
+|--------------------------------------------------------------------------
+| Arquivo: src/composables/useTopbarDevMenuExtras.js
+|
+| Extras DEV-only que aparecem dentro do mesmo botão "sliders" do topbar
+| (junto com o switcher de planos do useTopbarPlanMenu). Adiciona:
+|
+|   1) Switcher de layout (rail | melissa) — UPDATE em user_settings +
+|      localStorage + hard reload pra router decidir redirect.
+|
+|   2) Atalhos rápidos pra testar M1.3 (ComponentCadastroRapido nos
+|      diversos callers) e M1.1/M1.2 (CadastroRapidoMedico/Convenio).
+|
+| Visibilidade: assume que o caller só renderiza o menu se `showPlanDevMenu`
+| já estiver true (DEV + permissão). Não duplica essa lógica aqui.
+|
+| Uso em AppTopbar.vue / MelissaLayout.vue:
+|   const { devExtrasModel } = useTopbarDevMenuExtras();
+|   const combinedDevMenuModel = computed(() => [
+|       ...planMenuModel.value,
+|       { separator: true },
+|       ...devExtrasModel.value
+|   ]);
+|   <Menu :model="combinedDevMenuModel" ... />
+|--------------------------------------------------------------------------
+*/
+import { computed } from 'vue';
+import { useRouter } from 'vue-router';
+import { useToast } from 'primevue/usetoast';
+import { supabase } from '@/lib/supabase/client';
+import { useLayout } from '@/layout/composables/layout';
+
+export function useTopbarDevMenuExtras() {
+    const router = useRouter();
+    const toast = useToast();
+    const { layoutConfig } = useLayout();
+
+    const currentVariant = computed(() => layoutConfig.variant || 'classic');
+    const isRailLike = computed(() => currentVariant.value === 'rail' || currentVariant.value === 'classic');
+    const isMelissa = computed(() => currentVariant.value === 'melissa');
+
+    async function setLayoutAndReload(variant) {
+        try {
+            const { data, error: authErr } = await supabase.auth.getUser();
+            if (authErr) throw authErr;
+            const uid = data?.user?.id;
+            if (!uid) throw new Error('Sem sessão.');
+
+            const { error } = await supabase
+                .from('user_settings')
+                .upsert(
+                    {
+                        user_id: uid,
+                        layout_variant: variant,
+                        updated_at: new Date().toISOString()
+                    },
+                    { onConflict: 'user_id' }
+                );
+            if (error) throw error;
+
+            // Fast path: router.beforeEach/guards lêem localStorage antes do fetch
+            try {
+                localStorage.setItem('layout_variant', variant);
+            } catch (_) {
+                // ignore (Safari private mode etc.)
+            }
+
+            toast.add({ severity: 'success', summary: `Layout: ${variant}`, life: 1200 });
+
+            // Hard reload pra router redirecionar pra raiz correta
+            setTimeout(() => window.location.assign('/'), 250);
+        } catch (e) {
+            toast.add({
+                severity: 'error',
+                summary: 'Erro ao trocar layout',
+                detail: e?.message || 'Falha desconhecida.',
+                life: 4500
+            });
+        }
+    }
+
+    function goto(path) {
+        // router.push em vez de location.assign — mantém SPA + dev tools abertos.
+        // Se o guard redirecionar (ex: Melissa mode bloqueia /therapist/...),
+        // o usuário verá o redirect — sinal de que precisa trocar layout primeiro.
+        router.push(path).catch(() => {});
+    }
+
+    const devExtrasModel = computed(() => [
+        // ─── Layout ────────────────────────────────────────
+        { label: 'Layout (DEV)', icon: 'pi pi-th-large', disabled: true },
+        {
+            label: isRailLike.value ? 'Rail (atual)' : 'Rail',
+            icon: isRailLike.value ? 'pi pi-check' : 'pi pi-bars',
+            disabled: isRailLike.value,
+            command: () => setLayoutAndReload('rail')
+        },
+        {
+            label: isMelissa.value ? 'Melissa (atual)' : 'Melissa',
+            icon: isMelissa.value ? 'pi pi-check' : 'pi pi-window-maximize',
+            disabled: isMelissa.value,
+            command: () => setLayoutAndReload('melissa')
+        },
+
+        { separator: true },
+
+        // ─── Atalhos pra testar Módulo 1 ───────────────────
+        { label: 'Testar Módulo 1 (DEV)', icon: 'pi pi-bullseye', disabled: true },
+        {
+            label: '→ Cadastro Paciente (M1.1 + M1.2)',
+            icon: 'pi pi-user-plus',
+            command: () => goto('/therapist/patients/cadastro')
+        },
+        {
+            label: '→ Lista de Pacientes (M1.3-E)',
+            icon: 'pi pi-list',
+            command: () => goto('/therapist/patients')
+        },
+        {
+            label: '→ Melissa Agenda (M1.3-B)',
+            icon: 'pi pi-calendar',
+            command: () => goto('/melissa/agenda')
+        },
+        {
+            label: '→ Melissa Pacientes (M1.3-B)',
+            icon: 'pi pi-users',
+            command: () => goto('/melissa/pacientes')
+        }
+    ]);
+
+    return { devExtrasModel };
+}

src/config/devTestAccounts.js

@@ -0,0 +1,29 @@
+/*
+|--------------------------------------------------------------------------
+| Agência PSI
+|--------------------------------------------------------------------------
+| Arquivo: src/config/devTestAccounts.js
+|
+| Contas de teste seedadas pelo banco para QA/dev. Usado em HomeCards.vue
+| pra prefill de login (botão "Entrar como..." em dev).
+|
+| ⚠️ Senhas em texto — só vale porque o banco local tem essas mesmas senhas
+| seedadas (seed_001/002/003). Em produção, este arquivo segue compilado
+| mas o flag `isDev` em HomeCards.vue garante que os botões não aparecem.
+|
+| Pra gate em build de produção (remover do bundle), tratar como import
+| dinâmico no futuro ou condicional via `import.meta.env.DEV` no consumidor.
+|--------------------------------------------------------------------------
+*/
+
+export const TEST_ACCOUNTS = {
+    clinic_admin: { email: 'clinica3@agenciapsi.com.br', password: 'Teste@123' },
+    therapist: { email: 'terapeuta@agenciapsi.com.br', password: 'Teste@123' },
+    supervisor: { email: 'supervisor@agenciapsi.com.br', password: 'Teste@123' },
+    patient: { email: 'paciente@agenciapsi.com.br', password: 'Teste@123' },
+    saas: { email: 'saas@agenciapsi.com.br', password: 'Teste@123' },
+    editor: { email: 'editor@agenciapsi.com.br', password: 'Teste@123' },
+    therapist2: { email: 'therapist2@agenciapsi.com.br', password: 'Teste@123' },
+    therapist3: { email: 'therapist3@agenciapsi.com.br', password: 'Teste@123' },
+    secretary: { email: 'secretary@agenciapsi.com.br', password: 'Teste@123' }
+};

src/features/agenda/components/AgendaStatusChangeConfirmDialog.vue

@@ -0,0 +1,671 @@
+<!--
+|--------------------------------------------------------------------------
+| Agência PSI
+|--------------------------------------------------------------------------
+| Criado e desenvolvido por Leonardo Nohama
+|
+| Tecnologia aplicada à escuta.
+| Estrutura para o cuidado.
+|
+| Arquivo: src/features/agenda/components/AgendaStatusChangeConfirmDialog.vue
+| Data: 2026
+| Local: São Carlos/SP — Brasil
+|--------------------------------------------------------------------------
+| © 2026 — Todos os direitos reservados
+|--------------------------------------------------------------------------
+-->
+<script setup>
+/*
+ * AgendaStatusChangeConfirmDialog — Dialog que aparece ao mudar status
+ * de uma sessão (realizado/faltou/cancelado). Mostra defaults vindos da
+ * config (financial_exceptions, billing_contracts) e permite override
+ * caso a caso pelo terapeuta/clínica antes de aplicar.
+ *
+ * 5 variantes de renderização baseadas em (novoStatus, eventoContext):
+ *  - faltou/cancelado + avulsa            → bloco multa
+ *  - faltou/cancelado + pacote saldo      → bloco saldo + bloco multa
+ *  - faltou/cancelado + pacote upfront    → bloco multa (saldo n/a)
+ *  - realizado + avulsa pendente          → bloco "registrar pagamento"
+ *  - realizado + pacote saldo             → bloco "gerar cobrança no pacote"
+ *
+ * Emit 'confirm' com objeto descrevendo o que o handler deve fazer:
+ *  {
+ *    consumeSaldo: bool,        // só relevante em pacote saldo + faltou/cancelado
+ *    applyFine: bool,           // se vai cobrar multa
+ *    fineAmount: number|null,   // valor da multa (editavel)
+ *    markPaid: bool,            // realizado avulsa → marcar paga
+ *    paymentMethod: string,     // método se markPaid ou gerar cobrança
+ *    generatePackageCharge: bool // realizado em pacote saldo → criar record
+ *  }
+ */
+import { ref, computed, watch } from 'vue';
+
+const props = defineProps({
+    modelValue: { type: Boolean, default: false },
+    evento: { type: Object, default: null },
+    novoStatus: { type: String, default: '' }, // 'realizado' | 'faltou' | 'cancelado' | 'agendado' (reverse)
+    regraExcecao: { type: Object, default: null }, // row de financial_exceptions ou null
+    billingContract: { type: Object, default: null }, // row de billing_contracts ou null
+    billingContractStyle: { type: String, default: null }, // 'upfront' | 'saldo' | null
+    // Quando avulsa+pendente e novoStatus='realizado': financial_record relacionado
+    pendingRecord: { type: Object, default: null },
+    // Quando pacote saldo + realizado + record paid pré-existente (C12 antecipado):
+    // dialog não oferece "Gerar cobrança" — só confirma consumo de saldo.
+    existingPaidRecord: { type: Object, default: null },
+    // Preço da sessão (pra calcular multa percentual e cobrança de pacote saldo)
+    sessionPrice: { type: Number, default: 0 },
+    // Reverse transition (novoStatus='agendado'): artefatos a desfazer.
+    // { previousStatus, activeRecords[], saldoConsumed }
+    reverseArtifacts: { type: Object, default: null }
+});
+
+const emit = defineEmits(['update:modelValue', 'confirm']);
+
+// ─── State interno (refs editáveis) ─────────────────────────────────────
+const consumeSaldo = ref(false);
+const applyFine = ref(false);
+const fineAmount = ref(0);
+const markPaid = ref(true); // default em realizado: já recebeu
+const paymentMethod = ref('pix'); // método em "como recebeu" ou "como cobrar"
+const generatePackageCharge = ref(true); // realizado em pacote saldo: gera por padrão
+// ─── Reverse transition state (novoStatus='agendado') ──────────────────
+// Decisões pra desfazer ao reverter pra agendado.
+const reverseCancelPending = ref(true);   // cancela records pending/overdue
+const reverseRestoreSaldo = ref(true);    // devolve 1 ao saldo do pacote
+// Records 'paid' não têm radio — só warning textual (estorno é manual).
+
+// Reset/init ao abrir
+watch(
+    () => props.modelValue,
+    (open) => {
+        if (!open) return;
+        // Defaults baseados em context
+        consumeSaldo.value = !!props.regraExcecao?.default_consume_on_miss;
+        applyFine.value = _calcInitialFineApply();
+        fineAmount.value = _calcInitialFineAmount();
+        // Default markPaid:
+        // - Avulsa realizada (showRegistrarPagto): default false (manter pendente)
+        // - Pacote saldo realizada (showCobrancaPacote): default false (gerar pendente)
+        // Em ambos casos o user precisa selecionar ativamente "Sim, já recebi"
+        // pra registrar paid — evita marcar paid sem querer.
+        markPaid.value = false;
+        // paymentMethod default depende do contexto. Inicia 'pending' (que cai
+        // no select de "Como vai cobrar?" quando markPaid=false). Quando user
+        // troca pra "Sim, já recebi", precisa escolher PIX/Dinheiro/etc.
+        paymentMethod.value = 'pending';
+        generatePackageCharge.value = true;
+        // Reverse transition: defaults safer = cancela records pendentes +
+        // devolve saldo (typical recovery flow). Records paid não têm radio.
+        reverseCancelPending.value = true;
+        reverseRestoreSaldo.value = true;
+    }
+);
+
+// ─── Computeds: o que renderizar ────────────────────────────────────────
+const isFaltouOrCancelado = computed(() => props.novoStatus === 'faltou' || props.novoStatus === 'cancelado');
+const isRealizado = computed(() => props.novoStatus === 'realizado');
+const isReverseAgendado = computed(() => props.novoStatus === 'agendado');
+const isAvulsa = computed(() => !props.billingContract);
+const isPacoteSaldo = computed(() => props.billingContract?.type === 'package' && props.billingContractStyle === 'saldo');
+const isPacoteUpfront = computed(() => props.billingContract?.type === 'package' && props.billingContractStyle === 'upfront');
+
+// Reverse transition: derivados pra renderizar blocos
+const reversePendingRecords = computed(() => {
+    const recs = props.reverseArtifacts?.activeRecords || [];
+    return recs.filter((r) => r.status === 'pending' || r.status === 'overdue');
+});
+const reversePaidRecords = computed(() => {
+    const recs = props.reverseArtifacts?.activeRecords || [];
+    return recs.filter((r) => r.status === 'paid');
+});
+const reverseHasPaid = computed(() => reversePaidRecords.value.length > 0);
+const reverseHasPending = computed(() => reversePendingRecords.value.length > 0);
+const reverseShowSaldo = computed(() => isReverseAgendado.value && !!props.reverseArtifacts?.saldoConsumed);
+const reversePreviousStatusLabel = computed(() => {
+    const s = props.reverseArtifacts?.previousStatus;
+    if (s === 'realizado') return 'Realizada';
+    if (s === 'faltou') return 'Faltou';
+    if (s === 'cancelado') return 'Cancelado';
+    return s || 'estado anterior';
+});
+
+// Mostrar bloco multa: faltou/cancelado + regra existe + charge_mode != 'none'
+const showFineBlock = computed(() => isFaltouOrCancelado.value && props.regraExcecao && props.regraExcecao.charge_mode !== 'none');
+
+// Mostrar bloco saldo: faltou/cancelado + pacote saldo
+const showSaldoBlock = computed(() => isFaltouOrCancelado.value && isPacoteSaldo.value);
+
+// Mostrar bloco "registrar pagamento": realizado + avulsa pendente
+const showRegistrarPagto = computed(() => isRealizado.value && isAvulsa.value && props.pendingRecord && props.pendingRecord.status === 'pending');
+
+// Mostrar bloco "cobrança no pacote": realizado + pacote saldo + SEM paid pré-existente
+// (se já tem paid via antecipação, mostra o bloco "já pago" em vez deste)
+const showCobrancaPacote = computed(() => isRealizado.value && isPacoteSaldo.value && !props.existingPaidRecord);
+// Mostrar bloco "já paga via antecipação": realizado + pacote saldo + paid pré-existente
+const showAlreadyPaid = computed(() => isRealizado.value && isPacoteSaldo.value && !!props.existingPaidRecord);
+
+// ─── Header ────────────────────────────────────────────────────────────
+const headerTitle = computed(() => {
+    const labels = {
+        realizado: '✓ Marcar como Realizado',
+        faltou: '⚠ Marcar como Faltou',
+        cancelado: '✕ Marcar como Cancelado',
+        agendado: '↺ Reativar sessão (voltar pra Agendada)'
+    };
+    return labels[props.novoStatus] || 'Atualizar status';
+});
+
+// ─── Sub-info do evento ────────────────────────────────────────────────
+const pacienteNome = computed(() => props.evento?.paciente_nome || props.evento?.patients?.nome_completo || 'Paciente');
+const dataHora = computed(() => {
+    const ini = props.evento?.inicio_em;
+    if (!ini) return '';
+    try {
+        const d = new Date(ini);
+        return d.toLocaleString('pt-BR', { dateStyle: 'short', timeStyle: 'short' });
+    } catch {
+        return '';
+    }
+});
+const isSerieSemPacote = computed(() => {
+    // Série recorrente que não criou billing_contract (chargeMode='none' no save).
+    // Detecta via recurrence_id/serie_id na row sem contract carregado.
+    if (props.billingContract) return false;
+    const e = props.evento;
+    return !!(e?.recurrence_id || e?.serie_id || e?.is_occurrence);
+});
+
+const tipoTag = computed(() => {
+    if (isPacoteSaldo.value) return `Pacote saldo: ${props.billingContract.sessions_used ?? 0} de ${props.billingContract.total_sessions ?? '?'} usadas`;
+    if (isPacoteUpfront.value) return `Pacote upfront: R$ ${_fmtBRL(props.billingContract.package_price)} pago`;
+    if (isSerieSemPacote.value) return 'Série recorrente (sem pacote)';
+    if (props.pendingRecord) return `Avulsa: R$ ${_fmtBRL(props.pendingRecord.final_amount || props.pendingRecord.amount)} pendente`;
+    return 'Avulsa';
+});
+
+// ─── Labels e options ──────────────────────────────────────────────────
+const paymentMethodOptions = [
+    { value: 'pix', label: 'PIX' },
+    { value: 'dinheiro', label: 'Dinheiro' },
+    { value: 'deposito', label: 'Depósito' },
+    { value: 'cartao_maquininha', label: 'Cartão (maquininha)' }
+];
+// Opções pra "Como vai cobrar?" quando markPaid=false (sessão pendente
+// no pacote saldo). 'pending' = só registra como pendente, terapeuta
+// cobra depois pelo /financeiro. 'link' = gera link Asaas e marca
+// payment_method='asaas' no record (pós-confirm o handler updata).
+const paymentMethodOptionsPending = [
+    { value: 'pending', label: 'Apenas registrar como pendente' },
+    { value: 'link', label: 'Enviar link de pagamento (Asaas)' }
+];
+
+const regraResumo = computed(() => {
+    const r = props.regraExcecao;
+    if (!r) return '';
+    if (r.charge_mode === 'full') return `Sessão completa = R$ ${_fmtBRL(props.sessionPrice)}`;
+    if (r.charge_mode === 'fixed_fee') return `Taxa fixa: R$ ${_fmtBRL(r.charge_value)}`;
+    if (r.charge_mode === 'percentage') return `${r.charge_pct}% da sessão = R$ ${_fmtBRL((props.sessionPrice * (r.charge_pct ?? 0)) / 100)}`;
+    return 'Sem cobrança';
+});
+
+// ─── Helpers ───────────────────────────────────────────────────────────
+function _fmtBRL(v) {
+    return Number(v ?? 0).toLocaleString('pt-BR', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+}
+
+function _calcInitialFineAmount() {
+    const r = props.regraExcecao;
+    if (!r) return 0;
+    if (r.charge_mode === 'full') return Number(props.sessionPrice) || 0;
+    if (r.charge_mode === 'fixed_fee') return Number(r.charge_value) || 0;
+    if (r.charge_mode === 'percentage') return parseFloat((((Number(props.sessionPrice) || 0) * (Number(r.charge_pct) || 0)) / 100).toFixed(2));
+    return 0;
+}
+
+function _calcInitialFineApply() {
+    // Se regra existe e charge_mode != 'none': default true
+    // Exceção: cancelado fora da janela min_hours_notice → default false (paciente cancelou dentro do prazo)
+    const r = props.regraExcecao;
+    if (!r || r.charge_mode === 'none') return false;
+    if (props.novoStatus === 'cancelado' && r.min_hours_notice != null && props.evento?.inicio_em) {
+        const horasAteSessao = (new Date(props.evento.inicio_em).getTime() - Date.now()) / (1000 * 60 * 60);
+        // Se cancelou COM MAIS antecedência que min → sem multa por padrão
+        if (horasAteSessao >= Number(r.min_hours_notice)) return false;
+    }
+    return true;
+}
+
+// Texto explicativo de porquê a multa veio (des)marcada por padrão.
+// Aparece abaixo do checkbox no bloco multa pra deixar a regra visível
+// ao terapeuta no momento da decisão.
+const fineDefaultReason = computed(() => {
+    const r = props.regraExcecao;
+    if (!r || r.charge_mode === 'none') return '';
+    if (props.novoStatus !== 'cancelado' || r.min_hours_notice == null || !props.evento?.inicio_em) return '';
+    const horasAteSessao = (new Date(props.evento.inicio_em).getTime() - Date.now()) / (1000 * 60 * 60);
+    const min = Number(r.min_hours_notice);
+    const horasFmt = horasAteSessao < 0
+        ? `${Math.abs(horasAteSessao).toFixed(1)}h após o início`
+        : horasAteSessao < 1
+          ? `${Math.round(horasAteSessao * 60)}min antes`
+          : `${horasAteSessao.toFixed(1)}h antes`;
+    if (horasAteSessao >= min) {
+        return `Cancelou ${horasFmt} da sessão. Regra: multa apenas quando cancelamento ocorre com menos de ${min}h de antecedência → sem multa por padrão.`;
+    }
+    return `Cancelou ${horasFmt} da sessão (menos que os ${min}h da regra) → multa aplicada por padrão.`;
+});
+
+// ─── Actions ───────────────────────────────────────────────────────────
+function onConfirm() {
+    // markPaid agora é considerado em DOIS contextos:
+    // 1. Avulsa pendente (showRegistrarPagto): paciente já pagou a cobrança?
+    // 2. Pacote saldo realizado (showCobrancaPacote): já recebeu o valor da sessão?
+    // Em ambos casos: markPaid=true → record vira paid; false → fica pending.
+    const considerMarkPaid = showRegistrarPagto.value || (showCobrancaPacote.value && generatePackageCharge.value);
+    emit('confirm', {
+        consumeSaldo: showSaldoBlock.value ? consumeSaldo.value : false,
+        applyFine: showFineBlock.value ? applyFine.value : false,
+        fineAmount: showFineBlock.value && applyFine.value ? Number(fineAmount.value) || 0 : 0,
+        markPaid: considerMarkPaid ? markPaid.value : false,
+        paymentMethod: paymentMethod.value,
+        generatePackageCharge: showCobrancaPacote.value ? generatePackageCharge.value : false,
+        // Reverse transition: só relevante quando novoStatus='agendado'
+        reverseCancelPending: isReverseAgendado.value ? reverseCancelPending.value : false,
+        reverseRestoreSaldo: isReverseAgendado.value ? reverseRestoreSaldo.value : false
+    });
+    emit('update:modelValue', false);
+}
+
+function onCancel() {
+    emit('update:modelValue', false);
+}
+</script>
+
+<template>
+    <Dialog
+        :visible="modelValue"
+        modal
+        :draggable="false"
+        :style="{ width: '480px', maxWidth: '96vw' }"
+        :breakpoints="{ '640px': '98vw' }"
+        @update:visible="emit('update:modelValue', $event)"
+    >
+        <template #header>
+            <div class="asccd-head">
+                <div class="asccd-head__title">{{ headerTitle }}</div>
+            </div>
+        </template>
+
+        <div class="flex flex-col gap-4">
+            <!-- Resumo do evento -->
+            <div class="asccd-summary">
+                <div class="asccd-summary__name">{{ pacienteNome }}</div>
+                <div class="asccd-summary__meta">
+                    <span v-if="dataHora">{{ dataHora }}</span>
+                    <span class="asccd-summary__tag">{{ tipoTag }}</span>
+                </div>
+            </div>
+
+            <!-- ─── Reverse transition: voltar pra Agendada (com artefatos) ── -->
+            <div v-if="isReverseAgendado" class="asccd-block">
+                <div class="asccd-block__title">
+                    <i class="pi pi-info-circle" />
+                    Reverter status de <b>{{ reversePreviousStatusLabel }}</b> pra <b>Agendada</b>
+                </div>
+                <small class="asccd-hint">Esta sessão tem ações financeiras vinculadas. Escolha o que fazer com cada uma antes de reverter:</small>
+
+                <!-- Records pendentes -->
+                <div v-if="reverseHasPending" class="asccd-block mt-3">
+                    <div class="asccd-block__title">
+                        <i class="pi pi-money-bill" />
+                        Cobrança pendente vinculada
+                    </div>
+                    <ul class="asccd-list">
+                        <li v-for="r in reversePendingRecords" :key="r.id">
+                            <span class="font-medium">{{ r.description || 'Cobrança' }}</span>
+                            <span> · R$ {{ _fmtBRL(r.final_amount || r.amount) }}</span>
+                        </li>
+                    </ul>
+                    <div class="asccd-radio-group mt-2">
+                        <label class="asccd-radio">
+                            <input type="radio" :value="true" v-model="reverseCancelPending" />
+                            <span><b>Cancelar</b> a(s) cobrança(s) — recomendado</span>
+                        </label>
+                        <label class="asccd-radio">
+                            <input type="radio" :value="false" v-model="reverseCancelPending" />
+                            <span><b>Manter</b> ativa(s) — sessão volta agendada mas cobrança continua aberta</span>
+                        </label>
+                    </div>
+                </div>
+
+                <!-- Records pagos: warning sem ação -->
+                <div v-if="reverseHasPaid" class="asccd-info mt-3">
+                    <i class="pi pi-exclamation-triangle" />
+                    <div>
+                        <b>Atenção:</b> Esta sessão tem cobrança(s) já paga(s) ({{ reversePaidRecords.length }} record(s)).
+                        Reverter o status NÃO estorna o pagamento automaticamente — pra estornar use o /financeiro.
+                    </div>
+                </div>
+
+                <!-- Saldo consumido em pacote -->
+                <div v-if="reverseShowSaldo" class="asccd-block mt-3">
+                    <div class="asccd-block__title">
+                        <i class="pi pi-wallet" />
+                        Saldo do pacote consumido
+                    </div>
+                    <div class="asccd-fine-rule">Saldo atual: {{ billingContract?.sessions_used ?? '?' }} de {{ billingContract?.total_sessions ?? '?' }} usadas</div>
+                    <div class="asccd-radio-group mt-2">
+                        <label class="asccd-radio">
+                            <input type="radio" :value="true" v-model="reverseRestoreSaldo" />
+                            <span><b>Devolver</b> 1 sessão ao saldo — recomendado</span>
+                        </label>
+                        <label class="asccd-radio">
+                            <input type="radio" :value="false" v-model="reverseRestoreSaldo" />
+                            <span><b>Manter</b> saldo consumido — sessão volta agendada mas saldo continua decrementado</span>
+                        </label>
+                    </div>
+                </div>
+            </div>
+
+            <!-- ─── Bloco SALDO (pacote saldo + faltou/cancelado) ────────── -->
+            <div v-if="showSaldoBlock" class="asccd-block">
+                <div class="asccd-block__title">
+                    <i class="pi pi-wallet" />
+                    O que fazer com a vaga do pacote?
+                </div>
+                <div class="asccd-radio-group">
+                    <label class="asccd-radio">
+                        <input type="radio" :value="false" v-model="consumeSaldo" />
+                        <span><b>Remarcar</b> — não consome saldo (paciente pode remarcar)</span>
+                    </label>
+                    <label class="asccd-radio">
+                        <input type="radio" :value="true" v-model="consumeSaldo" />
+                        <span><b>Descontar</b> — sessão perdida ({{ billingContract?.sessions_used ?? 0 }} → {{ (billingContract?.sessions_used ?? 0) + 1 }})</span>
+                    </label>
+                </div>
+            </div>
+
+            <!-- ─── Bloco MULTA (faltou/cancelado com regra configurada) ── -->
+            <div v-if="showFineBlock" class="asccd-block">
+                <div class="asccd-block__title">
+                    <i class="pi pi-money-bill" />
+                    Aplicar multa?
+                </div>
+                <div class="asccd-fine-rule">Regra atual: {{ regraResumo }}</div>
+                <div class="asccd-fine-row">
+                    <Checkbox v-model="applyFine" inputId="asccd-apply-fine" binary />
+                    <label for="asccd-apply-fine" class="cursor-pointer">Aplicar multa</label>
+                    <InputNumber
+                        v-model="fineAmount"
+                        :disabled="!applyFine"
+                        mode="currency"
+                        currency="BRL"
+                        locale="pt-BR"
+                        :min="0"
+                        size="small"
+                        class="asccd-fine-input"
+                    />
+                </div>
+                <small v-if="fineDefaultReason" class="asccd-hint">
+                    <i class="pi pi-info-circle" /> {{ fineDefaultReason }}
+                </small>
+                <small v-if="isPacoteUpfront" class="asccd-hint">
+                    ℹ Pacote já pago; multa entra como cobrança adicional avulsa.
+                </small>
+            </div>
+
+            <!-- Pacote upfront sem multa configurada: aviso -->
+            <div v-if="isFaltouOrCancelado && isPacoteUpfront && !showFineBlock" class="asccd-info">
+                <i class="pi pi-info-circle" />
+                Pacote já foi pago. Nenhuma multa configurada — só atualiza o status.
+            </div>
+
+            <!-- ─── Bloco REGISTRAR PAGAMENTO (realizado + avulsa pendente) ── -->
+            <div v-if="showRegistrarPagto" class="asccd-block">
+                <div class="asccd-block__title">
+                    <i class="pi pi-check-circle" />
+                    A sessão foi paga?
+                </div>
+                <div class="asccd-radio-group">
+                    <label class="asccd-radio">
+                        <input type="radio" :value="false" v-model="markPaid" />
+                        <span>Não, manter cobrança pendente</span>
+                    </label>
+                    <label class="asccd-radio">
+                        <input type="radio" :value="true" v-model="markPaid" />
+                        <span>Sim, registrar pagamento</span>
+                    </label>
+                </div>
+                <div v-if="markPaid" class="asccd-method-row">
+                    <label class="asccd-method-label">Como recebeu?</label>
+                    <Select
+                        v-model="paymentMethod"
+                        :options="paymentMethodOptions"
+                        optionLabel="label"
+                        optionValue="value"
+                        size="small"
+                        class="asccd-method-select"
+                    />
+                </div>
+            </div>
+
+            <!-- ─── Bloco "JÁ PAGA via antecipação" (C12 fluxo de retorno) ─── -->
+            <div v-if="showAlreadyPaid" class="asccd-block">
+                <div class="asccd-block__title">
+                    <i class="pi pi-check-circle" />
+                    Sessão já paga via antecipação
+                </div>
+                <div class="asccd-info">
+                    <i class="pi pi-info-circle" />
+                    <div>
+                        Cobrança de <b>R$ {{ _fmtBRL(existingPaidRecord.final_amount || existingPaidRecord.amount) }}</b>
+                        já foi registrada como paga ({{ existingPaidRecord.payment_method || 'método não definido' }}).
+                        Marcar como Realizada vai <b>consumir 1 sessão do saldo</b>
+                        ({{ billingContract?.sessions_used ?? 0 }} → {{ (billingContract?.sessions_used ?? 0) + 1 }}/{{ billingContract?.total_sessions ?? '?' }}).
+                    </div>
+                </div>
+            </div>
+
+            <!-- ─── Bloco COBRANÇA NO PACOTE (realizado + pacote saldo) ──── -->
+            <div v-if="showCobrancaPacote" class="asccd-block">
+                <div class="asccd-block__title">
+                    <i class="pi pi-money-bill" />
+                    Gerar cobrança no pacote?
+                </div>
+                <div class="asccd-fine-rule">Valor da sessão: R$ {{ _fmtBRL(sessionPrice) }}</div>
+                <div class="asccd-fine-row">
+                    <Checkbox v-model="generatePackageCharge" inputId="asccd-gen-charge" binary />
+                    <label for="asccd-gen-charge" class="cursor-pointer">Gerar cobrança e consumir 1 sessão</label>
+                </div>
+                <!-- Sub-question 1: a sessão já foi paga? (espelha o padrão da avulsa) -->
+                <div v-if="generatePackageCharge" class="asccd-radio-group mt-2">
+                    <label class="asccd-radio">
+                        <input type="radio" :value="false" v-model="markPaid" />
+                        <span>Não, gerar como cobrança pendente</span>
+                    </label>
+                    <label class="asccd-radio">
+                        <input type="radio" :value="true" v-model="markPaid" />
+                        <span>Sim, já recebi</span>
+                    </label>
+                </div>
+                <!-- Sub-question 2a: se "Já recebi" → método de recebimento (sem prefixo) -->
+                <div v-if="generatePackageCharge && markPaid" class="asccd-method-row">
+                    <label class="asccd-method-label">Como recebeu?</label>
+                    <Select
+                        v-model="paymentMethod"
+                        :options="paymentMethodOptions"
+                        optionLabel="label"
+                        optionValue="value"
+                        size="small"
+                        class="asccd-method-select"
+                    />
+                </div>
+                <!-- Sub-question 2b: se "Pendente" → forma de cobrança (link Asaas vs registrar simples) -->
+                <div v-if="generatePackageCharge && !markPaid" class="asccd-method-row">
+                    <label class="asccd-method-label">Como vai cobrar?</label>
+                    <Select
+                        v-model="paymentMethod"
+                        :options="paymentMethodOptionsPending"
+                        optionLabel="label"
+                        optionValue="value"
+                        size="small"
+                        class="asccd-method-select"
+                    />
+                </div>
+            </div>
+        </div>
+
+        <template #footer>
+            <Button label="Cancelar" severity="secondary" outlined size="small" @click="onCancel" />
+            <Button label="Confirmar" icon="pi pi-check" size="small" @click="onConfirm" />
+        </template>
+    </Dialog>
+</template>
+
+<style scoped>
+.asccd-head__title {
+    font-size: 1rem;
+    font-weight: 700;
+    color: var(--text-color);
+}
+.asccd-summary {
+    display: flex;
+    flex-direction: column;
+    gap: 0.2rem;
+    padding: 0.65rem 0.85rem;
+    border-radius: 6px;
+    background: color-mix(in srgb, var(--p-primary-500) 4%, var(--surface-card));
+    border: 1px solid var(--surface-border);
+}
+.asccd-summary__name {
+    font-size: 0.92rem;
+    font-weight: 700;
+    color: var(--text-color);
+}
+.asccd-summary__meta {
+    font-size: 0.74rem;
+    color: var(--text-color-secondary);
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    flex-wrap: wrap;
+}
+.asccd-summary__tag {
+    display: inline-block;
+    padding: 1px 7px;
+    border-radius: 999px;
+    background: color-mix(in srgb, var(--p-primary-500) 12%, transparent);
+    color: var(--p-primary-color);
+    font-weight: 600;
+    font-size: 0.68rem;
+    text-transform: uppercase;
+    letter-spacing: 0.02em;
+}
+
+.asccd-block {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+    padding: 0.75rem 0.85rem;
+    border-radius: 6px;
+    border: 1px solid var(--surface-border);
+    background: var(--surface-card);
+}
+.asccd-block__title {
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
+    font-size: 0.85rem;
+    font-weight: 600;
+    color: var(--text-color);
+}
+.asccd-block__title i {
+    color: var(--p-primary-color);
+    font-size: 0.85rem;
+}
+
+.asccd-radio-group {
+    display: flex;
+    flex-direction: column;
+    gap: 0.4rem;
+}
+.asccd-radio {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-size: 0.82rem;
+    color: var(--text-color);
+    cursor: pointer;
+}
+.asccd-radio input[type='radio'] {
+    accent-color: var(--p-primary-color);
+    cursor: pointer;
+}
+
+.asccd-fine-rule {
+    font-size: 0.74rem;
+    color: var(--text-color-secondary);
+    font-style: italic;
+}
+.asccd-fine-row {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    flex-wrap: wrap;
+}
+.asccd-fine-input {
+    flex: 1;
+    min-width: 8rem;
+}
+
+.asccd-method-row {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    flex-wrap: wrap;
+    margin-top: 0.25rem;
+}
+.asccd-method-label {
+    font-size: 0.78rem;
+    color: var(--text-color);
+    font-weight: 500;
+    flex-shrink: 0;
+}
+.asccd-method-select {
+    flex: 1;
+    min-width: 12rem;
+}
+
+.asccd-info {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.6rem 0.85rem;
+    border-radius: 6px;
+    background: color-mix(in srgb, var(--blue-400, #60a5fa) 8%, var(--surface-card));
+    border: 1px solid color-mix(in srgb, var(--blue-400, #60a5fa) 30%, transparent);
+    font-size: 0.78rem;
+    color: var(--text-color);
+}
+.asccd-info i {
+    color: var(--blue-600, #2563eb);
+    flex-shrink: 0;
+}
+
+.asccd-hint {
+    font-size: 0.7rem;
+    color: var(--text-color-secondary);
+    font-style: italic;
+}
+
+.asccd-list {
+    margin-top: 0.3rem;
+    padding-left: 1.2rem;
+    font-size: 0.78rem;
+    color: var(--text-color);
+}
+.asccd-list li {
+    list-style: disc;
+    padding: 0.1rem 0;
+}
+</style>

src/features/agenda/components/InsurancePlanQuickCreateDialog.vue

@@ -18,18 +18,19 @@
 <script setup>
 import { ref, watch } from 'vue';
 import { useToast } from 'primevue/usetoast';
-import { supabase } from '@/lib/supabase/client';
+import { useInsurancePlans } from '@/features/insurance/composables/useInsurancePlans';
-import { useTenantStore } from '@/stores/tenantStore';
 
 const props = defineProps({
     modelValue: { type: Boolean, default: false },
+    // ownerId mantido por compat — repository sempre injeta owner_id = auth.uid() logado.
+    // Nos fluxos atuais (AgendaEventDialog), o usuário logado já é o owner.
     ownerId: { type: String, default: '' },
     initialName: { type: String, default: '' }
 });
 const emit = defineEmits(['update:modelValue', 'created']);
 
 const toast = useToast();
-const tenantStore = useTenantStore();
+const insuranceStore = useInsurancePlans();
 
 const visible = ref(props.modelValue);
 watch(() => props.modelValue, (v) => { visible.value = v; });
@@ -56,29 +57,25 @@ const canSave = () => !!form.value.name?.trim();
 
 async function onSave() {
     if (!canSave()) return;
-    const ownerId = props.ownerId || (await supabase.auth.getUser()).data?.user?.id;
-    const tid = tenantStore.activeTenantId || tenantStore.tenantId;
-    if (!ownerId || !tid) {
-        toast.add({ severity: 'error', summary: 'Sem contexto', detail: 'Owner ou tenant ausentes.', life: 3500 });
-        return;
-    }
     saving.value = true;
     try {
-        const payload = {
+        // Repository injeta owner_id + tenant_id, sanitiza, e faz uniqueness check.
-            owner_id: ownerId,
+        const data = await insuranceStore.create({
-            tenant_id: tid,
+            name: form.value.name,
-            name: form.value.name.trim().slice(0, 120),
+            default_value: form.value.default_value,
-            default_value: form.value.default_value != null ? Number(form.value.default_value) : null,
+            notes: form.value.notes
-            notes: form.value.notes?.trim().slice(0, 500) || null,
+        });
-            active: true
-        };
-        const { data, error } = await supabase.from('insurance_plans').insert(payload).select().single();
-        if (error) throw error;
         toast.add({ severity: 'success', summary: 'Convênio criado', life: 2200 });
         emit('created', data);
         visible.value = false;
     } catch (e) {
-        toast.add({ severity: 'error', summary: 'Falha ao criar convênio', detail: e?.message || 'Erro inesperado', life: 4000 });
+        const isDup = /existe um convênio/i.test(e?.message || '');
+        toast.add({
+            severity: isDup ? 'warn' : 'error',
+            summary: isDup ? 'Nome em uso' : 'Falha ao criar convênio',
+            detail: e?.message || 'Erro inesperado',
+            life: 4000
+        });
     } finally {
         saving.value = false;
     }
@@ -93,7 +90,6 @@ async function onSave() {
         :closable="!saving"
         header="Novo convênio"
         class="w-[94vw] max-w-md"
-        pt:mask:class="backdrop-blur-sm"
     >
         <div class="flex flex-col gap-3 pt-1">
             <FloatLabel variant="on">

src/features/agenda/components/InsurancePlanServiceQuickCreateDialog.vue

@@ -0,0 +1,130 @@
+<!--
+|--------------------------------------------------------------------------
+| Agência PSI
+|--------------------------------------------------------------------------
+| Arquivo: src/features/agenda/components/InsurancePlanServiceQuickCreateDialog.vue
+| Data: 2026-05-18
+|
+| Mini-dialog pra cadastrar procedimento dentro de um convênio SEM sair
+| do AgendaEventDialog. Mesmo pattern do InsurancePlanQuickCreateDialog —
+| emite `created` com a row inserida; o parent recarrega os planos e
+| (opcionalmente) auto-seleciona o novo procedimento.
+|
+| Campos:
+|   name *     — Ex: "Consulta psicológica", "Avaliação", "Sessão online"
+|   value *    — Valor que o convênio paga pra clínica nesse procedimento
+|--------------------------------------------------------------------------
+-->
+<script setup>
+import { ref, watch } from 'vue';
+import { useToast } from 'primevue/usetoast';
+import { supabase } from '@/lib/supabase/client';
+
+const props = defineProps({
+    modelValue: { type: Boolean, default: false },
+    insurancePlanId: { type: String, default: '' },
+    insurancePlanName: { type: String, default: '' }
+});
+const emit = defineEmits(['update:modelValue', 'created']);
+
+const toast = useToast();
+
+const visible = ref(props.modelValue);
+watch(() => props.modelValue, (v) => { visible.value = v; });
+watch(visible, (v) => emit('update:modelValue', v));
+
+const form = ref({
+    name: '',
+    value: null
+});
+const saving = ref(false);
+
+watch(() => props.modelValue, (v) => {
+    if (v) {
+        form.value = { name: '', value: null };
+    }
+});
+
+const canSave = () => !!form.value.name?.trim() && form.value.value != null && form.value.value > 0;
+
+async function onSave() {
+    if (!canSave()) return;
+    if (!props.insurancePlanId) {
+        toast.add({ severity: 'error', summary: 'Convênio ausente', detail: 'Selecione um convênio antes de cadastrar procedimento.', life: 3500 });
+        return;
+    }
+    saving.value = true;
+    try {
+        const payload = {
+            insurance_plan_id: props.insurancePlanId,
+            name: form.value.name.trim().slice(0, 120),
+            value: Number(form.value.value),
+            active: true
+        };
+        const { data, error } = await supabase.from('insurance_plan_services').insert(payload).select().single();
+        if (error) throw error;
+        toast.add({ severity: 'success', summary: 'Procedimento cadastrado', life: 2200 });
+        emit('created', data);
+        visible.value = false;
+    } catch (e) {
+        toast.add({ severity: 'error', summary: 'Falha ao criar procedimento', detail: e?.message || 'Erro inesperado', life: 4000 });
+    } finally {
+        saving.value = false;
+    }
+}
+</script>
+
+<template>
+    <Dialog
+        v-model:visible="visible"
+        modal
+        :draggable="false"
+        :closable="!saving"
+        class="w-[94vw] max-w-md"
+    >
+        <template #header>
+            <div class="flex flex-col">
+                <span class="text-base font-semibold">Novo procedimento</span>
+                <span v-if="insurancePlanName" class="text-xs text-color-secondary">{{ insurancePlanName }}</span>
+            </div>
+        </template>
+
+        <div class="flex flex-col gap-3 pt-1">
+            <FloatLabel variant="on">
+                <InputText id="ips-name" v-model="form.name" class="w-full" autofocus maxlength="120" />
+                <label for="ips-name">Nome do procedimento *</label>
+            </FloatLabel>
+
+            <FloatLabel variant="on">
+                <InputNumber
+                    id="ips-value"
+                    v-model="form.value"
+                    mode="currency"
+                    currency="BRL"
+                    locale="pt-BR"
+                    :min="0"
+                    :max="999999"
+                    class="w-full"
+                />
+                <label for="ips-value">Valor que o convênio paga *</label>
+            </FloatLabel>
+
+            <p class="text-xs text-color-secondary -mt-1">
+                <i class="pi pi-info-circle mr-1" />
+                Esse é o valor que a clínica recebe — não o que o paciente paga.
+            </p>
+        </div>
+
+        <template #footer>
+            <Button label="Cancelar" severity="secondary" outlined class="rounded-full" :disabled="saving" @click="visible = false" />
+            <Button
+                label="Cadastrar"
+                icon="pi pi-check"
+                :loading="saving"
+                :disabled="!canSave()"
+                class="rounded-full"
+                @click="onSave"
+            />
+        </template>
+    </Dialog>
+</template>

src/features/agenda/components/ServiceQuickCreateDialog.vue

@@ -110,7 +110,6 @@ async function onSave() {
         :closable="!saving"
         header="Novo serviço"
         class="w-[94vw] max-w-md"
-        pt:mask:class="backdrop-blur-sm"
     >
         <div class="flex flex-col gap-3 pt-1">
             <FloatLabel variant="on">

src/features/agenda/composables/__tests__/useAgendaEventComposer.spec.js

@@ -159,9 +159,10 @@ describe('isFirstOccurrence', () => {
 });
 
 describe('editScopeOptions', () => {
-    it('retorna 4 opções', () => {
+    it('retorna 3 opções (todos_sem_excecao removido da UI em 2026-05-12)', () => {
         const { composer } = setup();
-        expect(composer.editScopeOptions.value).toHaveLength(4);
+        expect(composer.editScopeOptions.value).toHaveLength(3);
+        expect(composer.editScopeOptions.value.map((o) => o.value)).toEqual(['somente_este', 'este_e_seguintes', 'todos']);
     });
     it('"este_e_seguintes" disabled quando isFirstOccurrence', () => {
         const serieEvents = ref([{ recurrence_date: '2026-05-15' }, { recurrence_date: '2026-05-22' }]);

src/features/agenda/composables/useAgendaBloqueios.js

@@ -0,0 +1,98 @@
+/*
+|--------------------------------------------------------------------------
+| Agência PSI
+|--------------------------------------------------------------------------
+| Criado e desenvolvido por Leonardo Nohama
+|
+| Tecnologia aplicada à escuta.
+| Estrutura para o cuidado.
+|
+| Arquivo: src/features/agenda/composables/useAgendaBloqueios.js
+| Data: 2026
+| Local: São Carlos/SP — Brasil
+|--------------------------------------------------------------------------
+| © 2026 — Todos os direitos reservados
+|--------------------------------------------------------------------------
+*/
+// useAgendaBloqueios
+// Carrega e expõe rows de public.agenda_bloqueios + computed de events
+// background pra renderizar no FullCalendar (cinza). Usado pelos 3 layouts
+// da agenda (Melissa, Terapeuta/Rail, Clínica).
+//
+// Contrato:
+//   - load(ownerId, rangeStart, rangeEnd)
+//       carrega bloqueios cujo data_inicio esteja dentro do range OU que
+//       sejam recorrentes (data_inicio pode estar em qualquer ponto, mas
+//       o build de events filtra pra emitir só dentro do range visível)
+//   - bloqueios          ref(Array)
+//   - loading            ref(Bool)
+//   - error              ref(String)
+//   - buildEventsForRange(rangeStart, rangeEnd)
+//       wrapper sobre agendaMappers.buildBloqueioBackgroundEvents
+
+import { ref } from 'vue';
+import { supabase } from '@/lib/supabase/client';
+import { buildBloqueioBackgroundEvents } from '@/features/agenda/services/agendaMappers';
+
+export function useAgendaBloqueios() {
+    const bloqueios = ref([]);
+    const loading = ref(false);
+    const error = ref('');
+
+    // ownerIdOrIds: string (1 owner) ou Array<string> (multi-owner, Clínica).
+    async function load(ownerIdOrIds, rangeStart, rangeEnd) {
+        if (!ownerIdOrIds) return;
+        const ids = Array.isArray(ownerIdOrIds)
+            ? ownerIdOrIds.filter(Boolean)
+            : [ownerIdOrIds];
+        if (!ids.length) return;
+        loading.value = true;
+        error.value = '';
+        try {
+            const isoStart = _toISODate(rangeStart);
+            const isoEnd = _toISODate(rangeEnd);
+
+            // Query: recorrentes (qualquer data) OU não-recorrentes com
+            // data_inicio <= isoEnd e (data_fim ?? data_inicio) >= isoStart.
+            // 2 queries simples + merge pra evitar string-building frágil.
+            const baseNonRec = supabase
+                .from('agenda_bloqueios')
+                .select('*')
+                .eq('recorrente', false)
+                .lte('data_inicio', isoEnd)
+                .or(`data_fim.gte.${isoStart},and(data_fim.is.null,data_inicio.gte.${isoStart})`);
+            const baseRec = supabase
+                .from('agenda_bloqueios')
+                .select('*')
+                .eq('recorrente', true);
+
+            const [{ data: nonRec, error: e1 }, { data: rec, error: e2 }] = await Promise.all([
+                ids.length === 1 ? baseNonRec.eq('owner_id', ids[0]) : baseNonRec.in('owner_id', ids),
+                ids.length === 1 ? baseRec.eq('owner_id', ids[0]) : baseRec.in('owner_id', ids)
+            ]);
+            if (e1) throw e1;
+            if (e2) throw e2;
+            bloqueios.value = [...(nonRec || []), ...(rec || [])];
+        } catch (e) {
+            error.value = e?.message || 'Falha ao carregar bloqueios.';
+            bloqueios.value = [];
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    function buildEventsForRange(rangeStart, rangeEnd) {
+        return buildBloqueioBackgroundEvents(bloqueios.value, rangeStart, rangeEnd);
+    }
+
+    return { bloqueios, loading, error, load, buildEventsForRange };
+}
+
+function _toISODate(d) {
+    if (!d) return null;
+    const dt = d instanceof Date ? d : new Date(d);
+    const y = dt.getFullYear();
+    const m = String(dt.getMonth() + 1).padStart(2, '0');
+    const day = String(dt.getDate()).padStart(2, '0');
+    return `${y}-${m}-${day}`;
+}

src/features/agenda/composables/useAgendaEventActions.js

@@ -48,6 +48,25 @@ export function useAgendaEventActions({
     servicePickerSel,
     selectedPlanService,
     saveCommitmentItems,
+    // chargeMode (Opção C1, 2026-05-13): ref string com modo de cobrança.
+    // Valores: 'none' | 'session' (avulsa) | 'package' | 'per_session' (recorrente).
+    // O emit('save') leva chargeMode no payload; handler em useMelissaAgenda
+    // decide o que criar (financial_record | billing_contract | N events+records).
+    // Substituiu o boolean gerarCobrancaAoSalvar.
+    chargeMode,
+    // packageStyle (2026-05-14): só relevante em chargeMode='package'.
+    // Valores: 'upfront' (cria 1 financial_record total + materializa 1ª ocorrência)
+    // | 'saldo' (só billing_contract, sem financial_record imediato — Cliniko).
+    packageStyle,
+    // paymentMethod (refatorado 2026-05-16): forma de recebimento quando
+    // avulsa+session OU pacote+upfront. Valores: 'link' (Asaas, status pending)
+    // | 'pix' | 'dinheiro' | 'deposito' | 'cartao_maquininha'. Status do
+    // record é controlado pelo markPaidNow abaixo, não pela forma.
+    paymentMethod,
+    // markPaidNow (refatorado 2026-05-16): boolean. Quando true E método !== 'link',
+    // handler marca o financial_record como paid (paciente pagou na hora).
+    // Quando false, record nasce pending independente do método.
+    markPaidNow,
     props,
     emit
 }) {
@@ -62,88 +81,88 @@ export function useAgendaEventActions({
     const samePatientConflict = ref(null);
 
     // ────────────────────────────────────────────────────────────────────
-    // 1. Watcher do form.status — confirma cancelar/remarcar via dialog
+    // 1. Watcher do form.status
-    //    e persiste no banco IMEDIATAMENTE. Reverte se cancelar.
+    //    Fase 5 (2026-05-14): pra realizado/faltou/cancelado, emit
-    //    Antes vivia no .vue; testado em isolamento agora.
+    //    `updateSeriesEvent` pro parent abrir o AgendaStatusChangeConfirmDialog
+    //    (com regras de exceção, saldo de pacote, etc). Sem confirm.require
+    //    aqui — o dialog do parent é a fonte canônica.
+    //    Pra remarcado mantém path antigo (confirm.require simples).
+    //    Se user cancelar o dialog: parent chama onReject pra reverter o form.
     // ────────────────────────────────────────────────────────────────────
     watch(
         () => composer.form.value?.status,
         async (newVal, oldVal) => {
             if (_skipStatusWatch.value) return;
             if (!composer.isEdit.value || !composer.form.value?.id) return;
-            if (newVal !== 'cancelado' && newVal !== 'remarcado') return;
+
+            const isStatusComDialog = ['realizado', 'faltou', 'cancelado'].includes(newVal);
+            const isRemarcado = newVal === 'remarcado';
+            if (!isStatusComDialog && !isRemarcado) return;
 
             _prevStatus.value = oldVal;
-            const isCancelar = newVal === 'cancelado';
 
+            // Fase 5: emit pro parent abrir AgendaStatusChangeConfirmDialog.
+            // Parent decide o que fazer e chama onReject() se user cancelar.
+            if (isStatusComDialog) {
+                const formId = composer.form.value.id;
+                const isVirtual = !!composer.form.value.is_occurrence || (typeof formId === 'string' && formId.startsWith('rec::'));
+                emit('updateSeriesEvent', {
+                    id: isVirtual ? null : formId,
+                    status: newVal,
+                    recurrence_date:
+                        composer.form.value.recurrence_date ||
+                        composer.form.value.original_date ||
+                        String(composer.form.value.inicio_em || '').slice(0, 10),
+                    inicio_em: composer.form.value.inicio_em,
+                    fim_em: composer.form.value.fim_em,
+                    is_virtual: isVirtual,
+                    // Form completo — handler usa pra resolver recurrence_id, billing_contract_id, etc
+                    row: { ...composer.form.value },
+                    // Callback pra reverter status no form se user cancelar o dialog do parent.
+                    // _skipStatusWatch evita loop recursivo no watcher.
+                    onReject: () => {
+                        _skipStatusWatch.value = true;
+                        composer.form.value.status = _prevStatus.value;
+                        Promise.resolve().then(() => {
+                            _skipStatusWatch.value = false;
+                        });
+                    }
+                });
+                return;
+            }
+
+            // Path legacy pra 'remarcado': confirm.require simples + UPDATE direto.
             confirm.require({
-                header: isCancelar ? 'Cancelar sessão' : 'Remarcar sessão',
+                header: 'Remarcar sessão',
-                message: isCancelar
+                message: 'Tem certeza que deseja marcar esta sessão para remarcação? O status será salvo imediatamente.',
-                    ? 'Tem certeza que deseja cancelar esta sessão? O status será salvo imediatamente.'
+                icon: 'pi pi-refresh',
-                    : 'Tem certeza que deseja marcar esta sessão para remarcação? O status será salvo imediatamente.',
-                icon: isCancelar ? 'pi pi-times-circle' : 'pi pi-refresh',
                 acceptLabel: 'Sim, confirmar',
                 rejectLabel: 'Não',
-                acceptSeverity: isCancelar ? 'danger' : 'warn',
+                acceptSeverity: 'warn',
                 accept: async () => {
                     try {
-                        // Se o evento é ocorrência VIRTUAL de recorrência
-                        // (id "rec::..." sem row real em agenda_eventos),
-                        // delega pro parent — useMelissaAgenda.onUpdateSeriesEvent
-                        // e AgendaTerapeutaPage.onUpdateSeriesEvent materializam
-                        // a linha antes de aplicar status. Sem essa delegação,
-                        // UPDATE direto em id virtual quebra com PostgreSQL
-                        // "invalid input syntax for type uuid".
                         const formId = composer.form.value.id;
-                        const isVirtual =
+                        const isVirtual = !!composer.form.value.is_occurrence || (typeof formId === 'string' && formId.startsWith('rec::'));
-                            !!composer.form.value.is_occurrence ||
-                            (typeof formId === 'string' && formId.startsWith('rec::'));
 
                         if (isVirtual) {
                             emit('updateSeriesEvent', {
-                                id: null, // sem row real
+                                id: null,
                                 status: newVal,
-                                recurrence_date:
+                                recurrence_date: composer.form.value.recurrence_date || composer.form.value.original_date || String(composer.form.value.inicio_em || '').slice(0, 10),
-                                    composer.form.value.recurrence_date ||
-                                    composer.form.value.original_date ||
-                                    String(composer.form.value.inicio_em || '').slice(0, 10),
                                 inicio_em: composer.form.value.inicio_em,
                                 fim_em: composer.form.value.fim_em,
                                 is_virtual: true,
-                                // Form completo do dialog — handler usa pra resolver
-                                // recurrence_id/patient_id sem depender de dialogEventRow.
                                 row: { ...composer.form.value }
                             });
-                            toast.add({
+                            toast.add({ severity: 'success', summary: 'Status atualizado', detail: `Sessão marcada como ${labelStatusSessao(newVal)}.`, life: 3000 });
-                                severity: 'success',
-                                summary: 'Status atualizado',
-                                detail: `Sessão marcada como ${labelStatusSessao(newVal)}.`,
-                                life: 3000
-                            });
                             return;
                         }
-
+                        const { data, error } = await supabase.from('agenda_eventos').update({ status: newVal }).eq('id', formId).select().single();
-                        const { data, error } = await supabase
-                            .from('agenda_eventos')
-                            .update({ status: newVal })
-                            .eq('id', formId)
-                            .select()
-                            .single();
                         if (error) throw error;
-                        toast.add({
+                        toast.add({ severity: 'success', summary: 'Status atualizado', detail: `Sessão marcada como ${labelStatusSessao(newVal)}.`, life: 3000 });
-                            severity: 'success',
-                            summary: 'Status atualizado',
-                            detail: `Sessão marcada como ${labelStatusSessao(newVal)}.`,
-                            life: 3000
-                        });
                         emit('updated', data);
                     } catch (e) {
-                        toast.add({
+                        toast.add({ severity: 'error', summary: 'Erro', detail: e?.message || 'Não foi possível atualizar o status.', life: 4000 });
-                            severity: 'error',
-                            summary: 'Erro',
-                            detail: e?.message || 'Não foi possível atualizar o status.',
-                            life: 4000
-                        });
                         composer.form.value.status = _prevStatus.value;
                     }
                 },
@@ -327,6 +346,24 @@ export function useAgendaEventActions({
             editMode: emitEditMode,
             recurrence_id: emitRecurrenceId,
             original_date: emitOriginalDate,
+            // _occurrenceMode: flag pra distinguir save do 2o dialog empilhado
+            // (editar UMA ocorrencia) do save do dialog pai. Handler decide qual
+            // dialog fechar — sem isso, fechava sempre o pai. 2026-05-12.
+            _occurrenceMode: !!props.occurrenceMode,
+            // chargeMode (Opção C1, 2026-05-13): handler decide entre criar
+            // financial_record (avulsa+session), billing_contract (recorrente+package)
+            // ou materializar N ocorrências + N records (recorrente+per_session).
+            // UI no .vue garante valores válidos por modo.
+            chargeMode: chargeMode?.value ?? 'none',
+            // packageStyle (2026-05-14): handler em useMelissaAgenda usa pra
+            // decidir entre upfront (1 record total + materializa 1ª) ou
+            // saldo (só contrato).
+            packageStyle: packageStyle?.value ?? 'upfront',
+            // paymentMethod + markPaidNow (refatorado 2026-05-16): substituem
+            // o antigo paymentSettlement. Handler aplica payment_method (sempre)
+            // e status=paid+paid_at apenas quando markPaidNow=true && method!='link'.
+            paymentMethod: paymentMethod?.value ?? 'link',
+            markPaidNow: markPaidNow?.value === true,
             // legado — mantido para compatibilidade
             serie_id: props.eventRow?.serie_id ?? null,
             serviceItems: composer.isSessionEvent.value ? commitmentItems.value.slice() : null,

src/features/agenda/composables/useAgendaEventComposer.js

@@ -88,11 +88,14 @@ export function useAgendaEventComposer(props, emit, extras = {}) {
         return false;
     });
 
+    // 'todos_sem_excecao' removido da UI em 2026-05-12 — padrao SimplePractice
+    // nao expoe override de customizacoes (e destrutivo e raro). Backend ainda
+    // suporta caso outro fluxo precise, mas dialog so oferece os 3 escopos
+    // padrao do mercado.
     const editScopeOptions = computed(() => [
         { value: 'somente_este', label: 'Somente esta sessão' },
         { value: 'este_e_seguintes', label: 'Esta e as seguintes', disabled: isFirstOccurrence.value },
-        { value: 'todos', label: 'Todas da série' },
+        { value: 'todos', label: 'Todas da série' }
-        { value: 'todos_sem_excecao', label: 'Todas sem exceção' }
     ]);
 
     // ── 4. Recorrência (criação) ───────────────────────────────────

src/features/agenda/composables/useAgendaEventLifecycle.js

@@ -96,6 +96,29 @@ export function useAgendaEventLifecycle({
     const sendingReminder = ref(false);
     const serviceQuickDlgOpen = ref(false);
     const insuranceQuickDlgOpen = ref(false);
+    const planServiceQuickDlgOpen = ref(false);
+
+    // occurrenceMode: financial_record da ocorrencia atual (se existir).
+    // Usado pra travar edicao de tipo/servicos quando ja ha cobranca emitida
+    // (padrao SimplePractice — cobranca emitida e imutavel; ajustes via fluxo
+    // do Financeiro, nao via dialog). 2026-05-12.
+    const occFinancialRecord = ref(null);
+    const occFinancialLoading = ref(false);
+
+    // sessionPaymentRecord (2026-05-18): financial_record da sessão (mesmo
+    // shape do occFinancialRecord) mas SEM o guard de occurrenceMode.
+    // Carregado em qualquer edit de sessão pra alimentar a linha "Cobrança"
+    // do Resumo lateral do AgendaEventDialog. Não dispara lock — esse
+    // continua via occFinancialRecord (território da Fase 6/C13).
+    const sessionPaymentRecord = ref(null);
+
+    // sessionContract (2026-05-19 noite): billing_contract ativo do paciente
+    // quando a sessão pertence a uma série com pacote (upfront ou saldo).
+    // Usado pra exibir info card no dialog explicando o pacote (qtd
+    // sessões usadas/restantes, valor, comportamento). Pra saldo, é a
+    // única forma do user entender o que tá acontecendo (nada aparece
+    // no /financeiro até realizar sessão).
+    const sessionContract = ref(null);
 
     // ── computeds locais ───────────────────────────────────────
     const serieCountByStatus = computed(() => {
@@ -192,6 +215,149 @@ export function useAgendaEventLifecycle({
         }
     }
 
+    // ── occurrence financial record loader ────────────────────
+    // Tenta 3 caminhos pra encontrar um record relevante:
+    //   1) Record direto por agenda_evento_id (materializada com cobrança própria)
+    //   2) Se a sessão pertence a contrato upfront PAGO, sintetiza um record
+    //      'paid' com o package_price → assim TODAS as ocorrências da série
+    //      mostram "Cobrança paga" no dialog (cobertas pelo pacote pago).
+    //   3) Senão, null → card unlocked.
+    async function loadOccFinancialRecord() {
+        occFinancialRecord.value = null;
+        // Guard de occurrenceMode REMOVIDO em 2026-05-19 — necessario pra
+        // que o lock de "edit cobrada" (Fase 6) tambem ative em Melissa,
+        // nao so em Rail/Clinica. Padrao SimplePractice: cobranca emitida
+        // eh imutavel pelo dialog; ajustes via estorno no Financeiro.
+        const evId = props.eventRow?.id;
+        const ruleId = props.eventRow?.recurrence_id;
+        const patientId = props.eventRow?.paciente_id || props.eventRow?.patient_id;
+        occFinancialLoading.value = true;
+        try {
+            // 1) Record direto (materializada que tem agenda_evento_id real)
+            const isVirtualId = typeof evId === 'string' && evId.startsWith('rec::');
+            if (evId && !isVirtualId) {
+                const { data, error } = await supabase
+                    .from('financial_records')
+                    .select('id, amount, final_amount, status, due_date, paid_at, payment_method')
+                    .eq('agenda_evento_id', evId)
+                    .in('status', ['pending', 'paid', 'overdue'])
+                    .order('created_at', { ascending: false })
+                    .limit(1)
+                    .maybeSingle();
+                if (error) throw error;
+                if (data) {
+                    occFinancialRecord.value = data;
+                    return;
+                }
+            }
+            // 2) Sintetiza record 'paid' quando há contrato upfront pago.
+            //    A 1ª materializada tem o record real; siblings (virtuais ou
+            //    materializadas sem cobrança individual) herdam status do
+            //    contrato pra UI mostrar "Cobrança paga" coerentemente.
+            if (ruleId && patientId) {
+                const { data: contracts } = await supabase
+                    .from('billing_contracts')
+                    .select('id, package_price, charging_style, status')
+                    .eq('patient_id', patientId)
+                    .eq('type', 'package')
+                    .eq('status', 'active')
+                    .order('created_at', { ascending: false });
+                const upfront = (contracts || []).find((c) => c.charging_style === 'upfront');
+                if (upfront) {
+                    // Confere se há record PAGO ligado a qualquer evento do
+                    // mesmo recurrence_id (ou seja, contrato foi quitado).
+                    const { data: siblingEvents } = await supabase
+                        .from('agenda_eventos')
+                        .select('id')
+                        .eq('recurrence_id', ruleId);
+                    const ids = (siblingEvents || []).map((e) => e.id);
+                    if (ids.length) {
+                        // Pega o record mais recente NAO cancelado (paid OU
+                        // pending OU overdue). Pacote upfront tem 1 record
+                        // unico cobrindo toda a serie — qualquer status dele
+                        // trava as siblings (cobranca ja emitida, imutavel).
+                        const { data: anyRec } = await supabase
+                            .from('financial_records')
+                            .select('id, amount, final_amount, status, due_date, paid_at, payment_method')
+                            .in('agenda_evento_id', ids)
+                            .in('status', ['paid', 'pending', 'overdue'])
+                            .order('created_at', { ascending: false })
+                            .limit(1)
+                            .maybeSingle();
+                        if (anyRec) {
+                            // Sintetiza usando o package_price (não o per-session
+                            // que pode ter mudado depois de editar).
+                            occFinancialRecord.value = {
+                                ...anyRec,
+                                amount: upfront.package_price,
+                                final_amount: upfront.package_price,
+                                _synthesized: true
+                            };
+                            return;
+                        }
+                    }
+                }
+            }
+            occFinancialRecord.value = null;
+        } catch (e) {
+            console.warn('[occurrence] erro ao carregar financial_record:', e?.message);
+            occFinancialRecord.value = null;
+        } finally {
+            occFinancialLoading.value = false;
+        }
+    }
+
+    // sessionPaymentRecord loader (2026-05-18): mesma query, sem guard
+    // de occurrenceMode. Alimenta a linha "Cobrança" do Resumo do dialog
+    // em qualquer edit de sessão (Melissa/Rail/Clínica) com eventRow.id.
+    async function loadSessionPaymentRecord() {
+        sessionPaymentRecord.value = null;
+        const evId = props.eventRow?.id;
+        if (!evId) return;
+        try {
+            const { data, error } = await supabase
+                .from('financial_records')
+                .select('id, amount, final_amount, status, due_date, paid_at, payment_method')
+                .eq('agenda_evento_id', evId)
+                .in('status', ['pending', 'paid', 'overdue'])
+                .order('created_at', { ascending: false })
+                .limit(1)
+                .maybeSingle();
+            if (error) throw error;
+            sessionPaymentRecord.value = data ?? null;
+        } catch (e) {
+            console.warn('[session-payment] erro ao carregar financial_record:', e?.message);
+            sessionPaymentRecord.value = null;
+        }
+    }
+
+    // loadSessionContract (2026-05-19 noite): busca billing_contract ativo
+    // do paciente quando o evento pertence a uma série com pacote. Usado
+    // pra info card no dialog explicando o pacote saldo/upfront.
+    async function loadSessionContract() {
+        sessionContract.value = null;
+        const patientId = props.eventRow?.paciente_id || props.eventRow?.patient_id;
+        const ruleId = props.eventRow?.recurrence_id;
+        // Só faz sentido pra sessão de série
+        if (!patientId || !ruleId) return;
+        try {
+            const { data, error } = await supabase
+                .from('billing_contracts')
+                .select('id, type, total_sessions, sessions_used, package_price, charging_style, status, active_from')
+                .eq('patient_id', patientId)
+                .eq('type', 'package')
+                .eq('status', 'active')
+                .order('created_at', { ascending: false })
+                .limit(1)
+                .maybeSingle();
+            if (error) throw error;
+            sessionContract.value = data ?? null;
+        } catch (e) {
+            console.warn('[session-contract] erro ao carregar:', e?.message);
+            sessionContract.value = null;
+        }
+    }
+
     function onPillEditClick(ev) {
         emit('editSeriesOccurrence', {
             id: ev.id,
@@ -278,6 +444,26 @@ export function useAgendaEventLifecycle({
         }
     }
 
+    // Quick-create de procedimento (insurance_plan_services) — inline,
+    // sem sair do dialog. Trigger no card Sessao/Honorarios quando o
+    // convenio selecionado nao tem procedimentos ou quando user quer
+    // adicionar mais. Apos criar, recarrega os planos pra refletir no
+    // computed planServices.
+    function openPlanServiceQuickCreate() {
+        if (!composer.form.value.insurance_plan_id) return;
+        planServiceQuickDlgOpen.value = true;
+    }
+    async function onPlanServiceCreated(service) {
+        await loadInsurancePlans(props.planOwnerId || props.ownerId);
+        // Auto-seleciona o procedimento recem-criado se o user nao
+        // tinha nenhum selecionado ainda (caso comum: convenio sem
+        // procedimentos -> cadastra o primeiro -> ja entra selecionado).
+        if (service?.id && !pickerBilling.selectedPlanService.value) {
+            pickerBilling.selectedPlanService.value = service.id;
+            pickerBilling.onProcedureSelect(service.id);
+        }
+    }
+
     // ── lembrete WhatsApp manual (8.2) ─────────────────────────
     async function onSendManualReminder() {
         if (!composer.form.value?.id) return;
@@ -349,7 +535,22 @@ export function useAgendaEventLifecycle({
             if (composer.hasSerie.value) loadSerieEvents();
             else serieEvents.value = [];
 
-            if (composer.isEdit.value) {
+            // occurrenceMode: carrega financial_record desta ocorrencia
+            // pra decidir se o card Sessao/Honorarios fica locked (cobranca
+            // ja emitida) ou unlocked (sem cobranca, edicao livre).
+            loadOccFinancialRecord();
+
+            // sessionPaymentRecord: carrega em qualquer edit (Melissa
+            // tambem) pra alimentar a linha "Cobrança" do Resumo lateral.
+            loadSessionPaymentRecord();
+            loadSessionContract();
+
+            // occurrenceMode: editando UMA ocorrencia de serie ja existente —
+            // tipo de compromisso ja foi escolhido (paciente + sessao). Pular
+            // step 1 incondicionalmente. Defesa em camadas: useMelissaAgenda
+            // ja seta is_occurrence=true na row (faz isEdit=true), mas se outro
+            // call site esquecer essa flag o guard aqui salva.
+            if (props.occurrenceMode || composer.isEdit.value) {
                 composer.step.value = 2;
             } else {
                 const preset = props.presetCommitmentId;
@@ -452,11 +653,19 @@ export function useAgendaEventLifecycle({
         sendingReminder,
         serviceQuickDlgOpen,
         insuranceQuickDlgOpen,
+        planServiceQuickDlgOpen,
+        occFinancialRecord,
+        occFinancialLoading,
+        sessionPaymentRecord,
         // computeds
         serieCountByStatus,
         pillDeleteMenuItems,
         // series
         loadSerieEvents,
+        loadOccFinancialRecord,
+        loadSessionPaymentRecord,
+        sessionContract,
+        loadSessionContract,
         onPillEditClick,
         onPillStatusChange,
         onPillDeleteClick,
@@ -468,6 +677,8 @@ export function useAgendaEventLifecycle({
         onServiceCreated,
         openInsuranceQuickCreate,
         onInsuranceCreated,
+        openPlanServiceQuickCreate,
+        onPlanServiceCreated,
         // reminder
         onSendManualReminder
     };

src/features/agenda/composables/useAgendaStatusChange.js

@@ -0,0 +1,147 @@
+/*
+|--------------------------------------------------------------------------
+| Agência PSI
+|--------------------------------------------------------------------------
+| Arquivo: src/features/agenda/composables/useAgendaStatusChange.js
+|
+| Composable Tipo A que orquestra o fluxo de status change da agenda
+| usando agendaBilling.service. Reusável em Melissa / Rail / Clínica.
+|
+| Uso:
+|   const { applyStatusChange, dialogOpen, dialogProps, onDialogConfirm,
+|           onDialogCancel } = useAgendaStatusChange({ toast });
+|
+|   // No handler:
+|   await applyStatusChange({ eventoId, row, novoStatus });
+|
+|   // No template:
+|   <AgendaStatusChangeConfirmDialog
+|     v-model="dialogOpen"
+|     :evento="dialogProps.evento"
+|     :novoStatus="dialogProps.novoStatus"
+|     :regraExcecao="dialogProps.regraExcecao"
+|     :billingContract="dialogProps.billingContract"
+|     :billingContractStyle="dialogProps.billingContractStyle"
+|     :pendingRecord="dialogProps.pendingRecord"
+|     :sessionPrice="dialogProps.sessionPrice"
+|     @confirm="onDialogConfirm"
+|     @update:modelValue="(v) => !v && onDialogCancel()"
+|   />
+|--------------------------------------------------------------------------
+*/
+
+import { ref } from 'vue';
+import { supabase } from '@/lib/supabase/client';
+import { useTenantStore } from '@/stores/tenantStore';
+import {
+    loadStatusChangeContext,
+    needsStatusConfirmDialog,
+    applyStatusDecisions
+} from '@/features/agenda/services/agendaBilling.service';
+
+/**
+ * @param {object} [opts]
+ * @param {object} [opts.toast]   instância de useToast (PrimeVue). Opcional.
+ * @returns composable com state reativo + applyStatusChange
+ */
+export function useAgendaStatusChange({ toast = null } = {}) {
+    const tenantStore = useTenantStore();
+
+    // Dialog state — bindar no template
+    const dialogOpen = ref(false);
+    const dialogProps = ref({});
+    let _resolveDialog = null;
+
+    function _openDialog(propsObj) {
+        return new Promise((resolve) => {
+            dialogProps.value = propsObj;
+            dialogOpen.value = true;
+            _resolveDialog = resolve;
+        });
+    }
+
+    function onDialogConfirm(decision) {
+        if (_resolveDialog) _resolveDialog(decision);
+        _resolveDialog = null;
+        dialogOpen.value = false;
+    }
+
+    function onDialogCancel() {
+        if (_resolveDialog) _resolveDialog(null);
+        _resolveDialog = null;
+        dialogOpen.value = false;
+    }
+
+    /**
+     * Coordena: load context → mostra dialog se preciso → aplica decisões.
+     *
+     * @param {object} args
+     * @param {string} args.eventoId   uuid (null pra ocorrências virtuais ainda)
+     * @param {object} args.row        row do agenda_eventos (pode ser parcial)
+     * @param {string} args.novoStatus 'realizado' | 'faltou' | 'cancelado' | 'agendado'
+     *
+     * @returns {Promise<{ applied: boolean, decision: object|null, ctx: object }>}
+     *          applied=true se passou pelo applyStatusDecisions.
+     *          decision=null se user cancelou o dialog.
+     */
+    async function applyStatusChange({ eventoId, row, novoStatus }) {
+        const ownerId = (await supabase.auth.getUser()).data?.user?.id || null;
+        const tenantId = tenantStore.activeTenantId || tenantStore.tenantId || tenantStore.tenant?.id || null;
+
+        // 1) Carrega contexto
+        const ctx = await loadStatusChangeContext({
+            supabase,
+            row,
+            eventoId,
+            status: novoStatus,
+            ownerId,
+            tenantId
+        });
+
+        // 2) Dialog se preciso
+        let decision = null;
+        if (needsStatusConfirmDialog(novoStatus, ctx)) {
+            decision = await _openDialog({
+                evento: row,
+                novoStatus,
+                regraExcecao: ctx.regraExcecao,
+                billingContract: ctx.billingContract,
+                billingContractStyle: ctx.billingContract?.charging_style || null,
+                pendingRecord: ctx.pendingRecord,
+                sessionPrice: row?.price ?? null
+            });
+            if (!decision) {
+                // user cancelou
+                return { applied: false, decision: null, ctx };
+            }
+        } else {
+            // Sem dialog — default decision vazia (só aplicar status change básico)
+            decision = {};
+        }
+
+        // 3) Aplica decisões
+        await applyStatusDecisions({
+            supabase,
+            toast,
+            eventoId,
+            row,
+            novoStatus,
+            ctx,
+            decision,
+            ownerId,
+            tenantId
+        });
+
+        return { applied: true, decision, ctx };
+    }
+
+    return {
+        // dialog state — pra template
+        dialogOpen,
+        dialogProps,
+        onDialogConfirm,
+        onDialogCancel,
+        // main action
+        applyStatusChange
+    };
+}

src/features/agenda/composables/useCommitmentServices.js

@@ -157,8 +157,16 @@ export function useCommitmentServices() {
     // Atualiza commitment_services nos agenda_eventos com recurrence_id = ruleId
     // onde services_customized = false (não foram editados individualmente).
     //
+    // Invariante adicional (2026-05-12, padrão SimplePractice): NUNCA propaga
+    // para eventos que já têm financial_record emitido (status pending/paid/
+    // overdue). Cobranças emitidas são imutáveis — ajustes só via fluxo do
+    // Financeiro. Sem isso, mudar o template da regra mudaria silenciosamente
+    // o valor referenciado por uma cobrança já entregue ao paciente.
+    //
     // opts.fromDate: string ISO 'YYYY-MM-DD' — limita a ocorrências a partir
     //   dessa data inclusive (escopo 'este_e_seguintes'). null = todas da série.
+    // opts.ignoreCustomized: bypass do filtro services_customized=false
+    //   (escopo 'todos_sem_excecao' operacional — NÃO afeta filtro financeiro).
     async function propagateToSerie(ruleId, items, { fromDate = null, ignoreCustomized = false } = {}) {
         if (!ruleId) return;
 
@@ -177,8 +185,23 @@ export function useCommitmentServices() {
         if (queryError) throw queryError;
         if (!events?.length) return;
 
+        // Filtra OUT eventos que já têm financial_record emitido. Uma query
+        // em batch evita N round-trips. Status considerados imutáveis: pending,
+        // paid, overdue. cancelled é ok propagar (record foi descartado).
+        const eventIds = events.map((e) => e.id);
+        const { data: lockedEvents, error: frErr } = await supabase
+            .from('financial_records')
+            .select('agenda_evento_id')
+            .in('agenda_evento_id', eventIds)
+            .in('status', ['pending', 'paid', 'overdue']);
+        if (frErr) throw frErr;
+        const lockedSet = new Set((lockedEvents || []).map((r) => r.agenda_evento_id));
+        const eligibleEvents = events.filter((ev) => !lockedSet.has(ev.id));
+
+        if (!eligibleEvents.length) return;
+
         // Para cada evento elegível: delete + insert (padrão idempotente)
-        for (const ev of events) {
+        for (const ev of eligibleEvents) {
             const { error: delErr } = await supabase.from('commitment_services').delete().eq('commitment_id', ev.id);
             if (delErr) throw delErr;
 

src/features/agenda/composables/useFinancialExceptions.js

@@ -66,7 +66,8 @@ export function useFinancialExceptions() {
                         charge_mode: payload.charge_mode,
                         charge_value: payload.charge_value ?? null,
                         charge_pct: payload.charge_pct ?? null,
-                        min_hours_notice: payload.min_hours_notice ?? null
+                        min_hours_notice: payload.min_hours_notice ?? null,
+                        default_consume_on_miss: !!payload.default_consume_on_miss
                     })
                     .eq('id', payload.id);
                 if (err) throw err;
@@ -78,7 +79,8 @@ export function useFinancialExceptions() {
                     charge_mode: payload.charge_mode,
                     charge_value: payload.charge_value ?? null,
                     charge_pct: payload.charge_pct ?? null,
-                    min_hours_notice: payload.min_hours_notice ?? null
+                    min_hours_notice: payload.min_hours_notice ?? null,
+                    default_consume_on_miss: !!payload.default_consume_on_miss
                 });
                 if (err) throw err;
             }

src/features/agenda/composables/useRecurrence.js

@@ -247,8 +247,16 @@ export function expandRules(rules, exceptions, rangeStart, rangeEnd) {
             if (exception) handledExIds.add(exception.id);
 
             // ── exceção: cancela esta ocorrência ──
-            if (exception?.type === 'cancel_session' || exception?.type === 'patient_missed' || exception?.type === 'therapist_canceled' || exception?.type === 'holiday_block') {
+            // cancel_session = cancel preemptivo (terapeuta apagou antes de
-                // ainda inclui no calendário mas com status especial
+            // qualquer interação) → SOME da agenda (honra o "Ela some da
+            // agenda" do diálogo de exclusão).
+            if (exception?.type === 'cancel_session') {
+                continue;
+            }
+            // Demais cancelamentos são HISTÓRICO (paciente faltou, terapeuta
+            // cancelou após começar, feriado) → permanecem visíveis com
+            // status especial pra ficar no registro.
+            if (exception?.type === 'patient_missed' || exception?.type === 'therapist_canceled' || exception?.type === 'holiday_block') {
                 occurrences.push(buildOccurrence(rule, date, iso, exception));
                 continue;
             }

src/features/agenda/pages/AgendaClinicaPage.vue

@@ -34,6 +34,13 @@ import { useRecurrence } from '@/features/agenda/composables/useRecurrence';
 import { useCommitmentServices } from '@/features/agenda/composables/useCommitmentServices';
 import { useDeterminedCommitments } from '@/features/agenda/composables/useDeterminedCommitments';
 import { useFeriados } from '@/composables/useFeriados';
+import { useAgendaBloqueios } from '@/features/agenda/composables/useAgendaBloqueios';
+
+// Fase D (replicação Clínica): adopta agendaBilling.service via composable
+// reutilizável. Cobre status change com confirm dialog + multa + reverse +
+// pacote saldo/upfront (C7-C13 de Melissa, espelho da Fase C do Rail).
+import { useAgendaStatusChange } from '@/features/agenda/composables/useAgendaStatusChange';
+import AgendaStatusChangeConfirmDialog from '@/features/agenda/components/AgendaStatusChangeConfirmDialog.vue';
 
 import { mapAgendaEventosToCalendarEvents, minutesToDuration } from '@/features/agenda/services/agendaMappers';
 import { useAgendaSettings } from '@/features/agenda/composables/useAgendaSettings';
@@ -52,6 +59,50 @@ const _queryDate = route.query.date ? new Date(route.query.date + 'T12:00:00') :
 // -------------------- feriados --------------------
 const { fcEvents: feriadoFcEvents, load: loadFeriados } = useFeriados();
 
+// -------------------- bloqueios (background events cinza) --------------------
+const { bloqueios: bloqueioRows, load: loadBloqueios, buildEventsForRange: buildBloqueioEvents } = useAgendaBloqueios();
+
+// Detecta se um range [start, end] cai dentro de algum bloqueio carregado.
+// Cobre dia-inteiro, janela horária e recorrência semanal. Não veta criação
+// (só agendador público veta), mas sinaliza pro user via toast.
+function bloqueioCobrindo(start, end) {
+    const arr = bloqueioRows?.value || [];
+    if (!arr.length || !start) return null;
+    const dStart = start instanceof Date ? start : new Date(start);
+    const dEnd = end instanceof Date ? end : new Date(end || start);
+    const isoDay = `${dStart.getFullYear()}-${String(dStart.getMonth() + 1).padStart(2, '0')}-${String(dStart.getDate()).padStart(2, '0')}`;
+    const dow = dStart.getDay();
+    const hhmmStart = dStart.getHours() * 60 + dStart.getMinutes();
+    const hhmmEnd = dEnd.getHours() * 60 + dEnd.getMinutes();
+    const parseHM = (s) => {
+        if (!s) return null;
+        const [h, m] = String(s).split(':').map(Number);
+        return Number.isFinite(h) ? h * 60 + (m || 0) : null;
+    };
+    for (const b of arr) {
+        if (!b) continue;
+        if (b.recorrente && b.dia_semana != null) {
+            if (Number(b.dia_semana) !== dow) continue;
+        } else {
+            const di = b.data_inicio;
+            const df = b.data_fim || b.data_inicio;
+            if (!di) continue;
+            if (isoDay < di || isoDay > df) continue;
+        }
+        const bhi = parseHM(b.hora_inicio);
+        const bhf = parseHM(b.hora_fim);
+        if (bhi == null || bhf == null) return b;
+        if (hhmmStart < bhf && hhmmEnd > bhi) return b;
+    }
+    return null;
+}
+const bloqueioFcEvents = computed(() => {
+    const s = currentRange.value.start;
+    const e = currentRange.value.end;
+    if (!s || !e) return [];
+    return buildBloqueioEvents(s, e);
+});
+
 onMounted(async () => {
     const tid = tenantStore.activeTenantId || tenantStore.tenantId || tenantStore.tenant?.id || null;
     if (tid) loadFeriados(tid);
@@ -457,6 +508,15 @@ const ownerOptions = computed(() => staffCols.value.map((p) => ({ label: p.title
 // -------------------- events --------------------
 const { loading: loadingEvents, error: eventsError, rows, loadClinicRange, createClinic, updateClinic, removeClinic } = useAgendaClinicEvents();
 
+// Fase D: status change com confirm dialog + billing (Melissa pattern).
+const {
+    dialogOpen: statusDialogOpen,
+    dialogProps: statusDialogProps,
+    onDialogConfirm: onStatusDialogConfirm,
+    onDialogCancel: onStatusDialogCancel,
+    applyStatusChange
+} = useAgendaStatusChange({ toast });
+
 const { loadAndExpand, createRule, updateRule, cancelRule, splitRuleAt, cancelRuleFrom, upsertException } = useRecurrence();
 
 const { saveRuleItems, propagateToSerie } = useCommitmentServices();
@@ -535,7 +595,7 @@ const allEvents = computed(() => {
         .filter(Boolean);
     const occEvents = mapAgendaEventosToCalendarEvents(occRows);
 
-    return [...base, ...occEvents, ...feriadoFcEvents.value];
+    return [...base, ...occEvents, ...feriadoFcEvents.value, ...bloqueioFcEvents.value];
 });
 
 // -------------------- eventos fora da jornada --------------------
@@ -925,6 +985,15 @@ async function openDialogCreate({ ownerId, start, end }) {
 }
 
 async function onSlotSelect({ ownerId, start, end }) {
+    const bloqHit = bloqueioCobrindo(start, end);
+    if (bloqHit) {
+        toast.add({
+            severity: 'warn',
+            summary: 'Horário bloqueado',
+            detail: `Este horário está dentro do bloqueio "${bloqHit.titulo || 'Bloqueio'}". A sessão será criada mesmo assim.`,
+            life: 5000
+        });
+    }
     await openDialogCreate({ ownerId, start, end });
 }
 
@@ -937,6 +1006,10 @@ async function onEventClick(info) {
     if (!ev) return;
 
     const ep = ev.extendedProps || {};
+
+    // Bloqueios/pausas são background events — ignorar click.
+    if (ep.kind === 'bloqueio' || ep.kind === 'break') return;
+
     dialogEventRow.value = {
         id: ep.isOccurrence ? null : ev.id || null,
         owner_id: ep.owner_id,
@@ -1131,38 +1204,58 @@ function onEditSeriesOccurrence({ id, recurrence_date, inicio_em, fim_em, is_vir
 async function onUpdateSeriesEvent({ id, status, recurrence_date, inicio_em, fim_em, is_virtual }) {
     const tid = tenantId.value;
     try {
-        if (id) {
+        const row = dialogEventRow.value || {};
-            await updateClinic(id, { status }, { tenantId: tid });
+
-            return;
+        // 1) Materializar virtual se preciso (resolve eventoId real)
+        let eventoId = id;
+        if (!id) {
+            if (!is_virtual || !inicio_em) return;
+            const rid = row.recurrence_id ?? row.serie_id ?? null;
+            const rDate = recurrence_date || inicio_em?.slice(0, 10);
+            const { data: existing } = await supabase
+                .from('agenda_eventos')
+                .select('id')
+                .eq('recurrence_id', rid)
+                .eq('recurrence_date', rDate)
+                .maybeSingle();
+            if (existing?.id) {
+                eventoId = existing.id;
+            } else {
+                // Materializa com status='agendado'; o status final aplica
+                // após applyStatusChange ramificar pelo dialog se preciso.
+                const created = await createClinic(
+                    {
+                        owner_id: dialogOwnerId.value || clinicOwnerId.value,
+                        tenant_id: tid,
+                        recurrence_id: rid,
+                        recurrence_date: rDate,
+                        tipo: 'sessao',
+                        status: 'agendado',
+                        inicio_em,
+                        fim_em,
+                        visibility_scope: 'public',
+                        titulo: row.titulo || 'Sessão',
+                        patient_id: row.patient_id || row.paciente_id || null,
+                        determined_commitment_id: row.determined_commitment_id || null
+                    },
+                    { tenantId: tid }
+                );
+                eventoId = created?.id || null;
+            }
         }
-        if (!is_virtual || !inicio_em) return;
 
-        const rid = dialogEventRow.value?.recurrence_id ?? dialogEventRow.value?.serie_id ?? null;
+        // 2) Atualiza status no DB
-        const rDate = recurrence_date || inicio_em?.slice(0, 10);
+        if (eventoId) {
+            await updateClinic(eventoId, { status }, { tenantId: tid });
+        }
 
-        const { data: existing } = await supabase.from('agenda_eventos').select('id').eq('recurrence_id', rid).eq('recurrence_date', rDate).maybeSingle();
+        // 3) Fluxo de billing (load context + dialog + apply)
+        const rowWithStatus = { ...row, id: eventoId, status, inicio_em, fim_em };
+        const { applied } = await applyStatusChange({ eventoId, row: rowWithStatus, novoStatus: status });
 
-        if (existing?.id) {
+        // 4) Refetch se aplicou (UI reflete novo estado)
-            await updateClinic(existing.id, { status }, { tenantId: tid });
+        if (applied && typeof loadClinicRange === 'function') {
-        } else {
+            await loadClinicRange();
-            const row = dialogEventRow.value || {};
-            await createClinic(
-                {
-                    owner_id: dialogOwnerId.value || clinicOwnerId.value,
-                    tenant_id: tid,
-                    recurrence_id: rid,
-                    recurrence_date: rDate,
-                    tipo: 'sessao',
-                    status,
-                    inicio_em,
-                    fim_em,
-                    visibility_scope: 'public',
-                    titulo: row.titulo || 'Sessão',
-                    patient_id: row.patient_id || row.paciente_id || null,
-                    determined_commitment_id: row.determined_commitment_id || null
-                },
-                { tenantId: tid }
-            );
         }
     } catch (e) {
         toast.add({ severity: 'warn', summary: 'Erro', detail: e?.message || 'Falha ao atualizar status.', life: 3000 });
@@ -1686,6 +1779,10 @@ async function _reloadRange() {
         allMerged.push(...merged.filter((r) => r.is_occurrence));
     }
     _occurrenceRows.value = allMerged;
+
+    // Bloqueios (background events) — load assíncrono em paralelo. Recebe
+    // o array de owners da clínica pra agregar todos numa query batch.
+    loadBloqueios(ownerIds.value, start, end);
 }
 
 // Ocorrências virtuais geradas pelo useRecurrence
@@ -2401,6 +2498,21 @@ function goRecorrencias() {
     <!-- Dialog de Bloqueio -->
     <BloqueioDialog v-model="bloqueioDialogOpen" :mode="bloqueioMode" :workRules="workRules" :settings="settings" :ownerId="clinicOwnerId" :tenantId="tenantId || ''" @saved="refetch" />
 
+    <!-- Fase D: confirma status change com decisões de billing
+         (multa, consumir saldo, gerar cobrança, reverse transition). -->
+    <AgendaStatusChangeConfirmDialog
+        v-model="statusDialogOpen"
+        :evento="statusDialogProps.evento"
+        :novoStatus="statusDialogProps.novoStatus"
+        :regraExcecao="statusDialogProps.regraExcecao"
+        :billingContract="statusDialogProps.billingContract"
+        :billingContractStyle="statusDialogProps.billingContractStyle"
+        :pendingRecord="statusDialogProps.pendingRecord"
+        :sessionPrice="statusDialogProps.sessionPrice"
+        @confirm="onStatusDialogConfirm"
+        @update:modelValue="(v) => !v && onStatusDialogCancel()"
+    />
+
     <!-- Dialog: feriados próximos (todos os dias úteis — bloqueados e pendentes) -->
     <Dialog v-model:visible="feriadosAlertaOpen" modal :draggable="false" header="Feriados nos próximos 30 dias" :style="{ width: '520px', maxWidth: '96vw' }">
         <div class="flex flex-col gap-3">

src/features/agenda/pages/AgendaTerapeutaPage.vue

@@ -47,6 +47,14 @@ import { useRecurrence } from '@/features/agenda/composables/useRecurrence';
 import { useCommitmentServices } from '@/features/agenda/composables/useCommitmentServices';
 import { useDeterminedCommitments } from '@/features/agenda/composables/useDeterminedCommitments';
 import { useFeriados } from '@/composables/useFeriados';
+import { useAgendaBloqueios } from '@/features/agenda/composables/useAgendaBloqueios';
+
+// Fase C (replicação Rail): adopta agendaBilling.service via composable
+// reutilizável. Cobre status change com confirm dialog + multa + reverse +
+// pacote saldo/upfront (C7-C13 de Melissa).
+import { useAgendaStatusChange } from '@/features/agenda/composables/useAgendaStatusChange';
+import { createPackageContract, materializeAndChargePerSession } from '@/features/agenda/services/agendaBilling.service';
+import AgendaStatusChangeConfirmDialog from '@/features/agenda/components/AgendaStatusChangeConfirmDialog.vue';
 
 import { mapAgendaEventosToCalendarEvents, buildWeeklyBreakBackgroundEvents, minutesToDuration } from '@/features/agenda/services/agendaMappers';
 
@@ -118,6 +126,16 @@ watch(eventsLoading, (val) => {
     if (!val) eventsHasLoaded.value = true;
 });
 
+// Fase C: orquestrador de status change (Melissa pattern). Cobre confirm
+// dialog + multa + reverse + pacote saldo/upfront via agendaBilling.service.
+const {
+    dialogOpen: statusDialogOpen,
+    dialogProps: statusDialogProps,
+    onDialogConfirm: onStatusDialogConfirm,
+    onDialogCancel: onStatusDialogCancel,
+    applyStatusChange
+} = useAgendaStatusChange({ toast });
+
 const { loadAndExpand, createRule, updateRule, cancelRule, splitRuleAt, cancelRuleFrom, upsertException } = useRecurrence();
 
 const { saveRuleItems, propagateToSerie } = useCommitmentServices();
@@ -129,6 +147,57 @@ const ownerId = computed(() => settings.value?.owner_id || '');
 // -----------------------------
 const { fcEvents: feriadoFcEvents, load: loadFeriados } = useFeriados();
 
+// -----------------------------
+// Bloqueios (background events cinza no FC)
+// -----------------------------
+const { bloqueios: bloqueioRows, load: loadBloqueios, buildEventsForRange: buildBloqueioEvents } = useAgendaBloqueios();
+const bloqueioFcEvents = computed(() => {
+    const s = currentRange.value.start;
+    const e = currentRange.value.end;
+    if (!s || !e) return [];
+    return buildBloqueioEvents(s, e);
+});
+
+// Detecta se um range [start, end] cai dentro de algum bloqueio carregado.
+// Cobre bloqueios dia-inteiro (sem hora) e bloqueios com janela horária.
+// Recorrentes semanais cobertos via dia_semana.
+function bloqueioCobrindo(start, end) {
+    const arr = bloqueioRows?.value || [];
+    if (!arr.length || !start) return null;
+    const dStart = start instanceof Date ? start : new Date(start);
+    const dEnd = end instanceof Date ? end : new Date(end || start);
+    const isoDay = `${dStart.getFullYear()}-${String(dStart.getMonth() + 1).padStart(2, '0')}-${String(dStart.getDate()).padStart(2, '0')}`;
+    const dow = dStart.getDay();
+    const hhmmStart = dStart.getHours() * 60 + dStart.getMinutes();
+    const hhmmEnd = dEnd.getHours() * 60 + dEnd.getMinutes();
+
+    const parseHM = (s) => {
+        if (!s) return null;
+        const [h, m] = String(s).split(':').map(Number);
+        return Number.isFinite(h) ? h * 60 + (m || 0) : null;
+    };
+
+    for (const b of arr) {
+        if (!b) continue;
+        // Recorrente semanal
+        if (b.recorrente && b.dia_semana != null) {
+            if (Number(b.dia_semana) !== dow) continue;
+        } else {
+            const di = b.data_inicio;
+            const df = b.data_fim || b.data_inicio;
+            if (!di) continue;
+            if (isoDay < di || isoDay > df) continue;
+        }
+        // Bloqueio sem hora = dia inteiro
+        const bhi = parseHM(b.hora_inicio);
+        const bhf = parseHM(b.hora_fim);
+        if (bhi == null || bhf == null) return b;
+        // Sobreposição de janela
+        if (hhmmStart < bhf && hhmmEnd > bhi) return b;
+    }
+    return null;
+}
+
 onMounted(async () => {
     const tid = tenantStore.activeTenantId || tenantStore.tenantId || tenantStore.tenant?.id || null;
     if (tid) loadFeriados(tid);
@@ -599,7 +668,7 @@ const calendarEvents = computed(() => {
 
     const breaks = settings.value && currentRange.value.start && currentRange.value.end ? buildWeeklyBreakBackgroundEvents(settings.value.pausas_semanais, currentRange.value.start, currentRange.value.end) : [];
 
-    return [...base, ...occEvents, ...breaks, ...feriadoFcEvents.value];
+    return [...base, ...occEvents, ...breaks, ...feriadoFcEvents.value, ...bloqueioFcEvents.value];
 });
 
 const visibleTitle = computed(() => {
@@ -1460,9 +1529,23 @@ function onCreateFromButton() {
 function onSelectTime(selection) {
     const durMin = settings.value?.session_duration_min ?? settings.value?.duracao_padrao_minutos ?? 50;
     const rawStart = selection.start instanceof Date ? selection.start : new Date(selection.start);
+    const rawEnd = selection.end instanceof Date ? selection.end : (selection.end ? new Date(selection.end) : new Date(rawStart.getTime() + durMin * 60000));
     const startISO = rawStart.toISOString();
     const endISO = new Date(rawStart.getTime() + durMin * 60000).toISOString();
 
+    // Aviso de bloqueio — não impede criação (regra: só agendador público
+    // veta), mas sinaliza pro terapeuta que ele tá agendando em cima de
+    // um bloqueio próprio.
+    const bloqHit = bloqueioCobrindo(rawStart, rawEnd);
+    if (bloqHit) {
+        toast.add({
+            severity: 'warn',
+            summary: 'Horário bloqueado',
+            detail: `Este horário está dentro do bloqueio "${bloqHit.titulo || 'Bloqueio'}". A sessão será criada mesmo assim.`,
+            life: 5000
+        });
+    }
+
     dialogEventRow.value = {
         owner_id: ownerId.value,
         terapeuta_id: null,
@@ -1485,6 +1568,10 @@ function onEventClick(info) {
     if (!ev) return;
     const ep = ev.extendedProps || {};
 
+    // Bloqueios/pausas são background events — ignorar click pra não abrir
+    // dialog de compromisso em cima de bloqueio (visual cinza ≠ compromisso).
+    if (ep.kind === 'bloqueio' || ep.kind === 'break') return;
+
     dialogEventRow.value = {
         id: ep.isOccurrence ? null : ev.id || null,
         owner_id: ep.owner_id,
@@ -1641,37 +1728,60 @@ function onEditSeriesOccurrence({ id, recurrence_date, inicio_em, fim_em, is_vir
 
 async function onUpdateSeriesEvent({ id, status, recurrence_date, inicio_em, fim_em, is_virtual }) {
     try {
-        if (id) {
+        const row = dialogEventRow.value || {};
-            await update(id, { status });
+
-            return;
+        // 1) Materializar virtual se preciso (resolve `eventoId` real)
+        let eventoId = id;
+        if (!id) {
+            if (!is_virtual || !inicio_em) return;
+            const rid = row.recurrence_id ?? row.serie_id ?? null;
+            const rDate = recurrence_date || inicio_em?.slice(0, 10);
+            const { data: existing } = await supabase
+                .from('agenda_eventos')
+                .select('id')
+                .eq('recurrence_id', rid)
+                .eq('recurrence_date', rDate)
+                .maybeSingle();
+            if (existing?.id) {
+                eventoId = existing.id;
+                // Status atualiza só depois do dialog/applyStatusChange decidir
+            } else {
+                // Materializa criando com status='agendado' — o status final
+                // é aplicado por applyStatusChange (que pode ramificar pelo
+                // dialog se houver decisão a tomar)
+                const created = await create({
+                    owner_id: ownerId.value,
+                    tenant_id: clinicTenantId.value,
+                    recurrence_id: rid,
+                    recurrence_date: rDate,
+                    tipo: 'sessao',
+                    status: 'agendado',
+                    inicio_em,
+                    fim_em,
+                    visibility_scope: 'public',
+                    titulo: row.titulo || 'Sessão',
+                    patient_id: row.patient_id || row.paciente_id || null,
+                    determined_commitment_id: row.determined_commitment_id || null,
+                    price: row.price ?? null
+                });
+                eventoId = created?.id || null;
+            }
         }
-        if (!is_virtual || !inicio_em) return;
 
-        const rid = dialogEventRow.value?.recurrence_id ?? dialogEventRow.value?.serie_id ?? null;
+        // 2) Atualiza status NO DB (applyStatusChange só cuida de billing — não
-        const rDate = recurrence_date || inicio_em?.slice(0, 10);
+        //    do status do agenda_evento em si). Antes do dialog pra ctx.row
+        //    refletir o novo status do evento.
+        if (eventoId) {
+            await update(eventoId, { status });
+        }
 
-        // Verifica se já foi materializado antes (evita violação de constraint)
+        // 3) Aplica fluxo de billing (load context + dialog se preciso + apply)
-        const { data: existing } = await supabase.from('agenda_eventos').select('id').eq('recurrence_id', rid).eq('recurrence_date', rDate).maybeSingle();
+        const rowWithStatus = { ...row, id: eventoId, status, inicio_em, fim_em };
+        const { applied } = await applyStatusChange({ eventoId, row: rowWithStatus, novoStatus: status });
 
-        if (existing?.id) {
+        // 4) Se aplicou (e não cancelou via dialog), refetch pra UI refletir
-            await update(existing.id, { status });
+        if (applied) {
-        } else {
+            await loadMyRange?.();
-            const row = dialogEventRow.value || {};
-            await create({
-                owner_id: ownerId.value,
-                tenant_id: clinicTenantId.value,
-                recurrence_id: rid,
-                recurrence_date: rDate,
-                tipo: 'sessao',
-                status,
-                inicio_em,
-                fim_em,
-                visibility_scope: 'public',
-                titulo: row.titulo || 'Sessão',
-                patient_id: row.patient_id || row.paciente_id || null,
-                determined_commitment_id: row.determined_commitment_id || null,
-                price: row.price ?? null
-            });
         }
     } catch (e) {
         toast.add({ severity: 'warn', summary: 'Erro', detail: e?.message || 'Falha ao atualizar status.', life: 3000 });
@@ -2243,6 +2353,10 @@ async function _reloadRange() {
     // 3. separa ocorrências virtuais (eventos reais já estão em rows.value)
     _occurrenceRows.value = merged.filter((r) => r.is_occurrence);
     logEvent('AgendaTerapeutaPage', '_reloadRange: ocorrências virtuais', { count: _occurrenceRows.value.length });
+
+    // 4. bloqueios (background events). Async em paralelo — não bloqueia
+    // render do calendário; bloqueioFcEvents é computed e atualiza sozinho.
+    loadBloqueios(ownerId.value, start, end);
 }
 
 // Ref auxiliar para ocorrências virtuais geradas pelo useRecurrence
@@ -3229,6 +3343,21 @@ onBeforeUnmount(() => {
 
     <!-- Dialog: Prontuário -->
     <PatientProntuario :key="selectedPatient?.id || 'none'" v-model="prontuarioOpen" :patient="selectedPatient" @close="closeProntuario" />
+
+    <!-- Fase C: confirma status change com decisões de billing
+         (multa, consumir saldo, gerar cobrança, reverse transition). -->
+    <AgendaStatusChangeConfirmDialog
+        v-model="statusDialogOpen"
+        :evento="statusDialogProps.evento"
+        :novoStatus="statusDialogProps.novoStatus"
+        :regraExcecao="statusDialogProps.regraExcecao"
+        :billingContract="statusDialogProps.billingContract"
+        :billingContractStyle="statusDialogProps.billingContractStyle"
+        :pendingRecord="statusDialogProps.pendingRecord"
+        :sessionPrice="statusDialogProps.sessionPrice"
+        @confirm="onStatusDialogConfirm"
+        @update:modelValue="(v) => !v && onStatusDialogCancel()"
+    />
 </template>
 
 <style scoped>
@@ -3383,19 +3512,13 @@ onBeforeUnmount(() => {
 .fc-event.evt-session.evt-has-color {
     color: #fff !important;
 }
-.fc-event.evt-block {
+/* Bloqueios são background events (cinza ~20%, inline em _makeBloqueioEvent).
-    background-color: #ef4444 !important;
+   A regra .fc-event.evt-block antiga pintava de vermelho — removida.
-    border-color: #dc2626 !important;
+   Deixar o backgroundColor inline (#6b728033) vencer. */
-    color: #fff !important;
-    opacity: 0.75;
-}
 /* dayGridMonth: o dot também precisa de cor */
 .fc-daygrid-event.evt-session .fc-event-main {
     color: #fff;
 }
-.fc-daygrid-event.evt-block .fc-event-main {
-    color: #fff;
-}
 
 /* Evento customizado — fora do scoped pois é HTML injetado pelo FullCalendar */
 .ev-custom {

src/features/agenda/services/agendaBilling.service.js

@@ -0,0 +1,816 @@
+/*
+|--------------------------------------------------------------------------
+| Agência PSI — agendaBilling service (Fase B1)
+|--------------------------------------------------------------------------
+| Helpers e loaders relacionados a billing da agenda, extraídos de
+| useMelissaAgenda.js pra serem reusados em Rail/Clínica.
+|
+| Esta sessão (Fase B1) cobre só read-only + helpers puros:
+|   - computeSeriePrice          (puro)
+|   - generateOccurrenceDates    (puro)
+|   - loadStatusChangeContext    (read-only DB)
+|   - needsStatusConfirmDialog   (puro)
+|
+| Fase B2 (mutations) extrairá: applyStatusDecisions, createPackageContract,
+| materializeAndChargePerSession.
+|
+| Convenção: funções recebem `supabase` explícito (não usa import direto)
+| pra facilitar teste + reuso fora do contexto Vue. Nenhuma função aqui
+| dispara toast — caller decide.
+|--------------------------------------------------------------------------
+*/
+
+import { dateToISO } from '@/features/agenda/utils/timeHelpers';
+
+// ── Helpers puros ─────────────────────────────────────────────────────────
+
+/**
+ * Calcula o valor total da série a partir dos commitmentItems.
+ *
+ * @param {object} recorrencia { qtdSessoes, commitmentItems, serieValorMode }
+ * @returns {{ n, perSessao, packagePrice }}
+ */
+export function computeSeriePrice(recorrencia) {
+    const items = recorrencia?.commitmentItems || [];
+    const n = recorrencia?.qtdSessoes || 1;
+    const totalPorSessao = items.reduce((s, i) => s + (i.final_price ?? 0), 0);
+    const pacoteFechado = recorrencia?.serieValorMode === 'dividir';
+    return {
+        n,
+        perSessao: pacoteFechado ? totalPorSessao / n : totalPorSessao,
+        packagePrice: pacoteFechado ? totalPorSessao : totalPorSessao * n
+    };
+}
+
+/**
+ * Gera lista de datas ISO ('YYYY-MM-DD') a partir de uma rule de recorrência.
+ * Pula datas em exceptionDates (Set). Para até `max` datas. Suporta weekly
+ * (interval=1 ou 2 pra quinzenal) e custom_weekdays.
+ *
+ * @param {object} rule { start_date, interval, weekdays, type }
+ * @param {number} max
+ * @param {Set<string>} exceptionDates
+ * @returns {string[]}
+ */
+export function generateOccurrenceDates(rule, max, exceptionDates = new Set()) {
+    const dates = [];
+    const start = new Date(`${rule.start_date}T00:00:00`);
+    const interval = Math.max(1, rule.interval || 1);
+    const weekdays = Array.isArray(rule.weekdays) && rule.weekdays.length
+        ? rule.weekdays.map(Number)
+        : [start.getDay()];
+    const isCustom = rule.type === 'custom_weekdays';
+
+    const cursor = new Date(start);
+    let safety = 0;
+    while (dates.length < max && safety < 365 * 3) {
+        const iso = dateToISO(cursor);
+        const dow = cursor.getDay();
+        const inWeekdays = weekdays.includes(dow);
+        if (inWeekdays && !exceptionDates.has(iso)) {
+            dates.push(iso);
+        }
+        if (isCustom) {
+            cursor.setDate(cursor.getDate() + 1);
+        } else if (inWeekdays) {
+            cursor.setDate(cursor.getDate() + 7 * interval);
+        } else {
+            cursor.setDate(cursor.getDate() + 1);
+        }
+        safety++;
+    }
+    return dates;
+}
+
+/**
+ * Decide se o dialog de confirmação de status change deve ser exibido.
+ *
+ * Pure: depende só do ctx montado por loadStatusChangeContext.
+ *
+ * Regras:
+ *   - faltou/cancelado: mostra se há regra de exceção com charge_mode != 'none'
+ *                       OU pacote saldo/upfront
+ *   - realizado:        mostra se há pending record OU pacote saldo
+ *   - agendado:         (reverse) mostra se há artefatos a desfazer
+ */
+export function needsStatusConfirmDialog(status, ctx) {
+    const isFaltouOrCancel = status === 'faltou' || status === 'cancelado';
+    const isRealizado = status === 'realizado';
+    const isAgendado = status === 'agendado';
+    const hasRegraComCobranca = ctx?.regraExcecao && ctx.regraExcecao.charge_mode !== 'none';
+    const isPacoteSaldo = ctx?.billingContract?.charging_style === 'saldo';
+    const isPacoteUpfront = ctx?.billingContract?.charging_style === 'upfront';
+    const hasPending = !!ctx?.pendingRecord;
+
+    if (isFaltouOrCancel) {
+        return hasRegraComCobranca || isPacoteSaldo || isPacoteUpfront;
+    }
+    if (isRealizado) {
+        return hasPending || isPacoteSaldo;
+    }
+    if (isAgendado) {
+        const r = ctx?.reverseArtifacts;
+        if (!r) return false;
+        const hasActiveRecords = (r.activeRecords?.length || 0) > 0;
+        return hasActiveRecords || r.saldoConsumed;
+    }
+    return false;
+}
+
+// ── Loaders (read-only DB) ────────────────────────────────────────────────
+
+/**
+ * Carrega contexto pra decisão de status change.
+ *
+ * Read-only. Não dispara toast (caller decide). Tolerante a erros parciais
+ * (loga warn e segue com null).
+ *
+ * @param {object} opts
+ * @param {object} opts.supabase   instância do client
+ * @param {object} opts.row        row do agenda_eventos (pode ser parcial — usa fallbacks)
+ * @param {string} opts.eventoId   uuid (null pra ocorrências virtuais não materializadas)
+ * @param {string} opts.status     'realizado' | 'faltou' | 'cancelado' | 'agendado'
+ * @param {string} opts.ownerId    auth.uid() (resolvido pelo caller)
+ * @param {string} opts.tenantId   activeTenantId
+ *
+ * @returns {Promise<{
+ *   regraExcecao,
+ *   billingContract,
+ *   pendingRecord,
+ *   existingPaidRecord,
+ *   reverseArtifacts: { previousStatus, activeRecords, saldoConsumed } | null
+ * }>}
+ */
+export async function loadStatusChangeContext({ supabase, row, eventoId, status, ownerId, tenantId }) {
+    const ctx = {
+        regraExcecao: null,
+        billingContract: null,
+        pendingRecord: null,
+        existingPaidRecord: null,
+        reverseArtifacts: null
+    };
+
+    // 1) Regra de exceção (faltou → patient_no_show, cancelado → patient_cancellation)
+    const exceptionTypeMap = { faltou: 'patient_no_show', cancelado: 'patient_cancellation' };
+    const excType = exceptionTypeMap[status];
+    if (excType && tenantId) {
+        try {
+            const { data } = await supabase
+                .from('financial_exceptions')
+                .select('*')
+                .eq('tenant_id', tenantId)
+                .eq('exception_type', excType)
+                .or(`owner_id.eq.${ownerId},owner_id.is.null`)
+                .order('owner_id', { ascending: false, nullsLast: true })
+                .limit(1)
+                .maybeSingle();
+            ctx.regraExcecao = data ?? null;
+        } catch (e) {
+            console.warn('[agendaBilling] regra de exceção:', e?.message);
+        }
+    }
+
+    // 2) Billing contract — 3 caminhos: row.billing_contract_id direto → query
+    //    agenda_eventos.billing_contract_id (recém-materializada) → contrato
+    //    ativo do paciente (virtuais).
+    const patientId = row?.patient_id ?? row?.paciente_id ?? null;
+    const contractId = row?.billing_contract_id ?? null;
+    if (contractId) {
+        try {
+            const { data } = await supabase
+                .from('billing_contracts')
+                .select('*')
+                .eq('id', contractId)
+                .maybeSingle();
+            ctx.billingContract = data ?? null;
+        } catch (e) {
+            console.warn('[agendaBilling] contract via id direto:', e?.message);
+        }
+    }
+    if (!ctx.billingContract && eventoId) {
+        try {
+            const { data: ev } = await supabase
+                .from('agenda_eventos')
+                .select('billing_contract_id')
+                .eq('id', eventoId)
+                .maybeSingle();
+            if (ev?.billing_contract_id) {
+                const { data: c } = await supabase
+                    .from('billing_contracts')
+                    .select('*')
+                    .eq('id', ev.billing_contract_id)
+                    .maybeSingle();
+                ctx.billingContract = c ?? null;
+            }
+        } catch (e) {
+            console.warn('[agendaBilling] contract via agenda_evento:', e?.message);
+        }
+    }
+    if (!ctx.billingContract && patientId && tenantId) {
+        try {
+            const { data: c } = await supabase
+                .from('billing_contracts')
+                .select('*')
+                .eq('tenant_id', tenantId)
+                .eq('patient_id', patientId)
+                .eq('status', 'active')
+                .eq('type', 'package')
+                .order('created_at', { ascending: false })
+                .limit(1)
+                .maybeSingle();
+            ctx.billingContract = c ?? null;
+        } catch (e) {
+            console.warn('[agendaBilling] contract via patient_id:', e?.message);
+        }
+    }
+
+    // 3) Pending record
+    if (eventoId) {
+        try {
+            const { data } = await supabase
+                .from('financial_records')
+                .select('*')
+                .eq('agenda_evento_id', eventoId)
+                .in('status', ['pending', 'overdue'])
+                .order('created_at', { ascending: false })
+                .limit(1)
+                .maybeSingle();
+            ctx.pendingRecord = data ?? null;
+        } catch (e) {
+            console.warn('[agendaBilling] pending record:', e?.message);
+        }
+    }
+
+    // 3b) Paid record pré-existente (caso C12: antecipar pagamento).
+    if (eventoId) {
+        try {
+            const { data } = await supabase
+                .from('financial_records')
+                .select('id, status, amount, final_amount, paid_at, payment_method')
+                .eq('agenda_evento_id', eventoId)
+                .eq('status', 'paid')
+                .order('paid_at', { ascending: false })
+                .limit(1)
+                .maybeSingle();
+            ctx.existingPaidRecord = data ?? null;
+        } catch (e) {
+            console.warn('[agendaBilling] existing paid record:', e?.message);
+        }
+    }
+
+    // 4) Reverse transition (status novo='agendado'): artefatos a desfazer.
+    if (status === 'agendado' && eventoId) {
+        ctx.reverseArtifacts = {
+            previousStatus: row?.status || null,
+            activeRecords: [],
+            saldoConsumed: false
+        };
+        try {
+            const { data: evRow } = await supabase
+                .from('agenda_eventos')
+                .select('status, billing_contract_id')
+                .eq('id', eventoId)
+                .maybeSingle();
+            if (evRow) {
+                ctx.reverseArtifacts.previousStatus = evRow.status;
+            }
+            const { data: recs } = await supabase
+                .from('financial_records')
+                .select('id, status, amount, final_amount, description, paid_at, payment_method')
+                .eq('agenda_evento_id', eventoId)
+                .neq('status', 'cancelled')
+                .order('created_at', { ascending: false });
+            ctx.reverseArtifacts.activeRecords = recs || [];
+            // Heurística saldo consumido: billing_contract_id + previousStatus
+            // ≠ 'agendado' + style=saldo. Falso positivo é mitigado pela escolha
+            // do user no dialog de "devolver saldo".
+            const wasInActiveState = evRow?.billing_contract_id && evRow.status && evRow.status !== 'agendado';
+            ctx.reverseArtifacts.saldoConsumed = wasInActiveState && ctx.billingContract?.charging_style === 'saldo';
+        } catch (e) {
+            console.warn('[agendaBilling] reverse artifacts:', e?.message);
+        }
+    }
+
+    return ctx;
+}
+
+// ── Mutations (Fase B2 — side effects DB) ─────────────────────────────────
+
+const _BRL = (v) => Number(v ?? 0).toLocaleString('pt-BR', { style: 'currency', currency: 'BRL' });
+
+/**
+ * Aplica as decisões tomadas no dialog de status change (reverse / consume
+ * saldo / multa / mark paid / cobrança pacote).
+ *
+ * Recebe deps explícitas (supabase, toast, ownerId, tenantId) em vez de
+ * capturar via closure. Toast pode ser null — quando chamado fora de UI
+ * (ex: background job), erros viram exceções no caller.
+ *
+ * Mantém a lógica idêntica à versão inline original em useMelissaAgenda.
+ *
+ * @param {object} opts
+ * @param {object} opts.supabase
+ * @param {object} [opts.toast]    — `{ add: fn }`. Opcional.
+ * @param {string} opts.eventoId
+ * @param {object} opts.row
+ * @param {string} opts.novoStatus
+ * @param {object} opts.ctx        — saída de loadStatusChangeContext
+ * @param {object} opts.decision
+ * @param {string} opts.ownerId
+ * @param {string} opts.tenantId
+ */
+export async function applyStatusDecisions({ supabase, toast, eventoId, row, novoStatus, ctx, decision, ownerId, tenantId }) {
+    const uid = ownerId;
+    const patientId = row?.patient_id ?? row?.paciente_id ?? null;
+    const tasks = [];
+    const tx = (entry) => { if (toast?.add) toast.add(entry); };
+
+    // ─── REVERSE TRANSITION (novoStatus='agendado' com artefatos a desfazer) ──
+    if (novoStatus === 'agendado' && ctx.reverseArtifacts) {
+        const r = ctx.reverseArtifacts;
+        // 1) Cancelar records pending/overdue
+        if (decision.reverseCancelPending && (r.activeRecords?.length || 0) > 0) {
+            const pendingIds = r.activeRecords.filter((rec) => rec.status === 'pending' || rec.status === 'overdue').map((rec) => rec.id);
+            if (pendingIds.length > 0) {
+                try {
+                    const today = new Date().toISOString().slice(0, 10);
+                    const reason = `Cancelada via reversão de status (${r.previousStatus} → agendado) em ${today}`;
+                    for (const id of pendingIds) {
+                        const { error: cErr } = await supabase
+                            .from('financial_records')
+                            .update({
+                                status: 'cancelled',
+                                notes: `[${today}] ${reason}`,
+                                updated_at: new Date().toISOString()
+                            })
+                            .eq('id', id);
+                        if (cErr) throw cErr;
+                    }
+                } catch (e) {
+                    console.error('[agendaBilling/reverse] erro cancelando records:', e?.message);
+                    tx({ severity: 'warn', summary: 'Cobrança', detail: e?.message || 'Falha ao cancelar cobranças', life: 5000 });
+                }
+            }
+        }
+
+        // 2) Devolver saldo
+        if (decision.reverseRestoreSaldo && r.saldoConsumed && ctx.billingContract?.id) {
+            try {
+                const { data: freshContract, error: fetchErr } = await supabase
+                    .from('billing_contracts')
+                    .select('sessions_used, total_sessions, status')
+                    .eq('id', ctx.billingContract.id)
+                    .maybeSingle();
+                if (fetchErr) throw fetchErr;
+                const currentUsed = freshContract?.sessions_used ?? 0;
+                const totalSessions = freshContract?.total_sessions ?? 0;
+                const newUsed = Math.max(0, currentUsed - 1);
+                const patch = { sessions_used: newUsed };
+                if (currentUsed >= totalSessions) {
+                    patch.status = 'active';
+                }
+                const { error: dErr } = await supabase.from('billing_contracts').update(patch).eq('id', ctx.billingContract.id);
+                if (dErr) throw dErr;
+            } catch (e) {
+                console.error('[agendaBilling/reverse] erro decrementando saldo:', e?.message);
+                tx({ severity: 'warn', summary: 'Saldo do pacote', detail: e?.message || 'Falha ao devolver saldo', life: 5000 });
+            }
+        }
+
+        // 3) Desamarrar billing_contract_id (só se devolveu saldo)
+        if (decision.reverseRestoreSaldo && r.saldoConsumed) {
+            try {
+                await supabase.from('agenda_eventos').update({ billing_contract_id: null, updated_at: new Date().toISOString() }).eq('id', eventoId);
+            } catch (e) {
+                console.warn('[agendaBilling/reverse] erro desamarrando billing_contract_id:', e?.message);
+            }
+        }
+
+        tx({ severity: 'success', summary: 'Sessão reativada', detail: 'Status revertido pra agendada.', life: 2500 });
+        return;
+    }
+
+    // 1) Consumir saldo
+    if (decision.consumeSaldo && ctx.billingContract?.id) {
+        tasks.push(
+            supabase
+                .from('billing_contracts')
+                .update({ sessions_used: (ctx.billingContract.sessions_used ?? 0) + 1 })
+                .eq('id', ctx.billingContract.id)
+        );
+    }
+
+    // 1b) Amarra evento ao contrato (universal pra forward em pacote)
+    const isForwardStatus = novoStatus === 'realizado' || novoStatus === 'faltou' || novoStatus === 'cancelado';
+    if (isForwardStatus && ctx.billingContract?.id && eventoId) {
+        tasks.push(
+            supabase
+                .from('agenda_eventos')
+                .update({ billing_contract_id: ctx.billingContract.id, updated_at: new Date().toISOString() })
+                .eq('id', eventoId)
+        );
+    }
+
+    // 2) Aplicar multa
+    if (decision.applyFine && decision.fineAmount > 0) {
+        const dueIso = row.inicio_em ? new Date(row.inicio_em).toISOString().slice(0, 10) : new Date().toISOString().slice(0, 10);
+        const sessaoLabel = row.inicio_em ? new Date(row.inicio_em).toLocaleDateString('pt-BR', { day: '2-digit', month: '2-digit', year: '2-digit' }) : '';
+        const fineDesc = novoStatus === 'faltou' ? `Multa por falta · sessão ${sessaoLabel}` : `Taxa de cancelamento tardio · sessão ${sessaoLabel}`;
+        const finePayload = {
+            owner_id: uid,
+            tenant_id: tenantId,
+            patient_id: patientId,
+            agenda_evento_id: eventoId,
+            amount: decision.fineAmount,
+            final_amount: decision.fineAmount,
+            description: fineDesc.trim(),
+            status: 'pending',
+            due_date: dueIso,
+            type: 'receita'
+        };
+        tasks.push(
+            supabase
+                .from('financial_records')
+                .insert(finePayload)
+                .then(({ error }) => {
+                    if (error) {
+                        console.warn('[agendaBilling] INSERT multa falhou:', error?.message, 'payload:', finePayload);
+                        throw error;
+                    }
+                })
+        );
+    }
+
+    // 2b) Cancelar cobrança original (faltou/cancelado + pendingRecord)
+    const isFaltouOuCancelado = novoStatus === 'faltou' || novoStatus === 'cancelado';
+    if (isFaltouOuCancelado && ctx.pendingRecord?.id) {
+        const reasonText = decision.applyFine
+            ? novoStatus === 'faltou'
+                ? 'Cancelada — substituída por multa de no-show'
+                : 'Cancelada — substituída por taxa de cancelamento tardio'
+            : novoStatus === 'faltou'
+              ? 'Cancelada — sessão não realizada (paciente faltou)'
+              : 'Cancelada — sessão cancelada';
+        const today = new Date().toISOString().slice(0, 10);
+        const noteEntry = `[${today}] ${reasonText}`;
+        const noteText = ctx.pendingRecord.notes ? `${ctx.pendingRecord.notes}\n${noteEntry}` : noteEntry;
+        tasks.push(
+            supabase
+                .from('financial_records')
+                .update({
+                    status: 'cancelled',
+                    notes: noteText,
+                    updated_at: new Date().toISOString()
+                })
+                .eq('id', ctx.pendingRecord.id)
+        );
+    }
+
+    // 3) Realizado avulsa pendente: marcar pendingRecord como pago (ou só status)
+    if (decision.markPaid && ctx.pendingRecord?.id) {
+        tasks.push(
+            supabase
+                .from('financial_records')
+                .update({
+                    status: 'paid',
+                    paid_at: new Date().toISOString(),
+                    payment_method: decision.paymentMethod || 'pix',
+                    updated_at: new Date().toISOString()
+                })
+                .eq('id', ctx.pendingRecord.id)
+        );
+    }
+
+    // 4-pre) Realizado em pacote saldo + paid pré-existente (C12)
+    const hasAnticipatedPayment = novoStatus === 'realizado' && ctx.billingContract?.charging_style === 'saldo' && ctx.existingPaidRecord?.id;
+    if (hasAnticipatedPayment) {
+        if (tasks.length > 0) {
+            const results = await Promise.allSettled(tasks);
+            const failed = results.filter((r) => r.status === 'rejected');
+            if (failed.length > 0) {
+                console.warn('[agendaBilling/realizada-paid] tasks com falha:', failed.map((f) => f.reason?.message));
+            }
+        }
+        try {
+            const { data: freshContract, error: fetchErr } = await supabase
+                .from('billing_contracts')
+                .select('sessions_used, total_sessions, status')
+                .eq('id', ctx.billingContract.id)
+                .maybeSingle();
+            if (fetchErr) throw fetchErr;
+            const currentUsed = freshContract?.sessions_used ?? 0;
+            const newUsed = currentUsed + 1;
+            const patch = { sessions_used: newUsed };
+            if (newUsed >= (freshContract?.total_sessions ?? 0)) {
+                patch.status = 'completed';
+            }
+            const { error: incErr } = await supabase.from('billing_contracts').update(patch).eq('id', ctx.billingContract.id);
+            if (incErr) throw incErr;
+            tx({ severity: 'success', summary: 'Sessão consumida', detail: `Saldo: ${newUsed}/${freshContract?.total_sessions ?? '?'}. Pagamento já estava registrado.`, life: 4000 });
+        } catch (e) {
+            console.error('[agendaBilling/realizada-paid] erro consumindo saldo:', e?.message);
+            tx({ severity: 'warn', summary: 'Saldo do pacote', detail: e?.message || 'Falha ao consumir saldo', life: 5000 });
+        }
+        return;
+    }
+
+    // 4) Realizado em pacote saldo: amarra + cria cobrança + incrementa saldo
+    if (decision.generatePackageCharge && ctx.billingContract?.id) {
+        const amount = Number(row.price ?? (ctx.billingContract.total_sessions > 0 ? (Number(ctx.billingContract.package_price) || 0) / ctx.billingContract.total_sessions : 0));
+        const dueIso = row.inicio_em ? new Date(row.inicio_em).toISOString().slice(0, 10) : new Date().toISOString().slice(0, 10);
+
+        try {
+            const { error: linkErr } = await supabase.from('agenda_eventos').update({ billing_contract_id: ctx.billingContract.id, updated_at: new Date().toISOString() }).eq('id', eventoId);
+            if (linkErr) throw linkErr;
+        } catch (e) {
+            console.error('[agendaBilling] erro amarrando billing_contract_id:', e?.message);
+            tx({ severity: 'warn', summary: 'Pacote — amarração', detail: e?.message || 'Falha ao amarrar sessão ao pacote', life: 5000 });
+        }
+
+        try {
+            const { error: rpcErr } = await supabase.rpc('create_financial_record_for_session', {
+                p_tenant_id: tenantId,
+                p_owner_id: uid,
+                p_patient_id: patientId,
+                p_agenda_evento_id: eventoId,
+                p_amount: amount,
+                p_due_date: dueIso
+            });
+            if (rpcErr) throw rpcErr;
+        } catch (e) {
+            console.error('[agendaBilling] erro RPC create_financial_record_for_session:', e?.message);
+            tx({ severity: 'error', summary: 'Cobrança', detail: e?.message || 'Falha ao gerar cobrança do pacote', life: 7000 });
+        }
+
+        try {
+            const newUsed = (ctx.billingContract.sessions_used ?? 0) + 1;
+            const patchContract = { sessions_used: newUsed };
+            if (newUsed >= (ctx.billingContract.total_sessions ?? 0)) {
+                patchContract.status = 'completed';
+            }
+            const { error: incErr } = await supabase.from('billing_contracts').update(patchContract).eq('id', ctx.billingContract.id);
+            if (incErr) throw incErr;
+        } catch (e) {
+            console.error('[agendaBilling] erro incrementando sessions_used:', e?.message);
+            tx({ severity: 'warn', summary: 'Saldo do pacote', detail: e?.message || 'Falha ao atualizar saldo do pacote', life: 6000 });
+        }
+    }
+
+    // Roda tudo em paralelo
+    const results = await Promise.allSettled(tasks);
+    const failed = results.filter((r) => r.status === 'rejected');
+    if (failed.length > 0) {
+        const firstErr = failed[0].reason?.message || 'sem detalhe';
+        tx({ severity: 'error', summary: 'Erro ao aplicar decisões', detail: `${failed.length} ação(ões) falharam: ${firstErr}`, life: 7000 });
+        console.error('[agendaBilling] falhas em applyStatusDecisions:', failed.map((f) => f.reason));
+    } else if (tasks.length > 0) {
+        tx({ severity: 'success', summary: 'Status atualizado', detail: 'Decisões aplicadas.', life: 2500 });
+    }
+
+    // Pós-processamento do record gerado pelo pacote saldo
+    if (decision.generatePackageCharge && eventoId) {
+        try {
+            const { data: newRec } = await supabase
+                .from('financial_records')
+                .select('id')
+                .eq('agenda_evento_id', eventoId)
+                .order('created_at', { ascending: false })
+                .limit(1)
+                .single();
+            if (newRec?.id) {
+                if (decision.markPaid) {
+                    await supabase
+                        .from('financial_records')
+                        .update({
+                            status: 'paid',
+                            paid_at: new Date().toISOString(),
+                            payment_method: decision.paymentMethod,
+                            updated_at: new Date().toISOString()
+                        })
+                        .eq('id', newRec.id);
+                } else if (decision.paymentMethod === 'link') {
+                    await supabase
+                        .from('financial_records')
+                        .update({ payment_method: 'asaas', updated_at: new Date().toISOString() })
+                        .eq('id', newRec.id);
+                }
+            }
+        } catch { /* silencioso */ }
+    }
+}
+
+/**
+ * Cria billing_contract de pacote (upfront ou saldo). Materializa 1ª
+ * ocorrência + 1 financial_record (estilo upfront), ou só o contrato
+ * (estilo saldo).
+ *
+ * Retorna { toast: { severity, summary, detail, life } } — caller mostra.
+ */
+export async function createPackageContract({ supabase, rule, normalized, recorrencia, tenantId, packageStyle = 'upfront', paymentMethod = 'link', markPaidNow = false }) {
+    const { n, packagePrice } = computeSeriePrice(recorrencia);
+    try {
+        const { data: createdContract, error: contractErr } = await supabase
+            .from('billing_contracts')
+            .insert({
+                owner_id: normalized.owner_id,
+                tenant_id: tenantId,
+                patient_id: normalized.paciente_id,
+                type: 'package',
+                total_sessions: n,
+                sessions_used: 0,
+                package_price: packagePrice,
+                status: 'active',
+                charging_style: packageStyle === 'saldo' ? 'saldo' : 'upfront'
+            })
+            .select('id')
+            .single();
+        if (contractErr) throw contractErr;
+        const contractId = createdContract?.id ?? null;
+
+        if (packageStyle === 'saldo') {
+            return {
+                toast: {
+                    severity: 'success',
+                    summary: 'Pacote criado (saldo)',
+                    detail: `${n} sessões — total ${_BRL(packagePrice)}. Cobranças individuais conforme sessões.`,
+                    life: 3500
+                }
+            };
+        }
+
+        const durMin = rule.duration_min || 50;
+        const [hh, mm] = String(rule.start_time || '00:00:00').slice(0, 5).split(':').map(Number);
+        const firstISO = rule.start_date;
+        const startDt = new Date(`${firstISO}T00:00:00`);
+        startDt.setHours(hh, mm, 0, 0);
+        const endDt = new Date(startDt.getTime() + durMin * 60 * 1000);
+
+        const { data: createdEvent, error: evErr } = await supabase
+            .from('agenda_eventos')
+            .insert({
+                owner_id: rule.owner_id,
+                tenant_id: tenantId,
+                terapeuta_id: rule.therapist_id ?? null,
+                recurrence_id: rule.id,
+                recurrence_date: firstISO,
+                tipo: 'sessao',
+                status: 'agendado',
+                titulo: normalized.titulo || 'Sessão',
+                inicio_em: startDt.toISOString(),
+                fim_em: endDt.toISOString(),
+                patient_id: normalized.paciente_id,
+                determined_commitment_id: normalized.determined_commitment_id ?? null,
+                modalidade: rule.modalidade || normalized.modalidade || 'presencial',
+                price: packagePrice,
+                billing_contract_id: contractId,
+                visibility_scope: normalized.visibility_scope || 'public'
+            })
+            .select('id')
+            .single();
+        if (evErr) throw evErr;
+
+        const { error: cobErr } = await supabase.rpc('create_financial_record_for_session', {
+            p_tenant_id: tenantId,
+            p_owner_id: rule.owner_id,
+            p_patient_id: normalized.paciente_id ?? null,
+            p_agenda_evento_id: createdEvent.id,
+            p_amount: packagePrice,
+            p_due_date: firstISO
+        });
+        if (cobErr) throw cobErr;
+
+        const paidNow = markPaidNow === true && paymentMethod !== 'link';
+        const { data: recRow } = await supabase
+            .from('financial_records')
+            .select('id')
+            .eq('agenda_evento_id', createdEvent.id)
+            .order('created_at', { ascending: false })
+            .limit(1)
+            .single();
+        if (recRow?.id) {
+            const patch = {
+                updated_at: new Date().toISOString(),
+                payment_method: paymentMethod === 'link' ? 'asaas' : paymentMethod
+            };
+            if (paidNow) {
+                patch.status = 'paid';
+                patch.paid_at = new Date().toISOString();
+            }
+            await supabase.from('financial_records').update(patch).eq('id', recRow.id);
+        }
+
+        const methodLabel = {
+            pix: 'PIX',
+            dinheiro: 'dinheiro',
+            deposito: 'depósito',
+            cartao_maquininha: 'cartão (maquininha)'
+        }[paymentMethod] || null;
+        return {
+            toast: {
+                severity: 'success',
+                summary: paidNow ? 'Pacote pago' : 'Pacote criado',
+                detail: paidNow
+                    ? `${n} sessões — ${_BRL(packagePrice)} recebido via ${methodLabel}.`
+                    : `${n} sessões — total ${_BRL(packagePrice)} com vencimento em ${firstISO.split('-').reverse().join('/')}.`,
+                life: 4000
+            }
+        };
+    } catch (e) {
+        return {
+            toast: {
+                severity: 'warn',
+                summary: 'Pacote não gerado',
+                detail: e?.message || 'Falha ao criar contrato. Você pode gerar manualmente pelo Financeiro.',
+                life: 5000
+            }
+        };
+    }
+}
+
+/**
+ * chargeMode='per_session': materializa todas as N ocorrências + 1 financial_record
+ * por ocorrência. Falha parcial é tolerada (retorna toast warn).
+ */
+export async function materializeAndChargePerSession({ supabase, rule, normalized, recorrencia, tenantId }) {
+    const { n, perSessao } = computeSeriePrice(recorrencia);
+    try {
+        const exceptionDates = new Set((recorrencia.conflitos || []).map((c) => c.date));
+        const dates = generateOccurrenceDates(rule, n + exceptionDates.size, exceptionDates).slice(0, n);
+
+        const durMin = rule.duration_min || 50;
+        const [hh, mm] = String(rule.start_time || '00:00:00').slice(0, 5).split(':').map(Number);
+        const rows = dates.map((iso) => {
+            const startDt = new Date(`${iso}T00:00:00`);
+            startDt.setHours(hh, mm, 0, 0);
+            const endDt = new Date(startDt.getTime() + durMin * 60 * 1000);
+            return {
+                owner_id: rule.owner_id,
+                tenant_id: tenantId,
+                terapeuta_id: rule.therapist_id ?? null,
+                recurrence_id: rule.id,
+                recurrence_date: iso,
+                tipo: 'sessao',
+                status: 'agendado',
+                titulo: normalized.titulo || 'Sessão',
+                inicio_em: startDt.toISOString(),
+                fim_em: endDt.toISOString(),
+                patient_id: normalized.paciente_id,
+                determined_commitment_id: normalized.determined_commitment_id ?? null,
+                modalidade: rule.modalidade || normalized.modalidade || 'presencial',
+                price: perSessao,
+                visibility_scope: normalized.visibility_scope || 'public'
+            };
+        });
+
+        const { data: createdEvents, error: evErr } = await supabase.from('agenda_eventos').insert(rows).select('id, inicio_em');
+        if (evErr) throw evErr;
+
+        let okCount = 0;
+        let failCount = 0;
+        for (const ev of createdEvents || []) {
+            try {
+                const dueDate = ev.inicio_em ? new Date(ev.inicio_em).toISOString().slice(0, 10) : new Date().toISOString().slice(0, 10);
+                const { error: cobErr } = await supabase.rpc('create_financial_record_for_session', {
+                    p_tenant_id: tenantId,
+                    p_owner_id: rule.owner_id,
+                    p_patient_id: normalized.paciente_id ?? null,
+                    p_agenda_evento_id: ev.id,
+                    p_amount: perSessao,
+                    p_due_date: dueDate
+                });
+                if (cobErr) throw cobErr;
+                okCount++;
+            } catch {
+                failCount++;
+            }
+        }
+
+        if (failCount === 0) {
+            return {
+                toast: {
+                    severity: 'success',
+                    summary: `${okCount} cobranças geradas`,
+                    detail: `${_BRL(perSessao)} por sessão. Total: ${_BRL(perSessao * okCount)}.`,
+                    life: 4000
+                }
+            };
+        }
+        return {
+            toast: {
+                severity: 'warn',
+                summary: 'Cobranças parcialmente geradas',
+                detail: `${okCount} ok, ${failCount} falharam. Gere as faltantes manualmente pelo Financeiro.`,
+                life: 6000
+            }
+        };
+    } catch (e) {
+        return {
+            toast: {
+                severity: 'warn',
+                summary: 'Falha ao materializar série',
+                detail: e?.message || 'Sessões podem ter sido criadas em parte. Confira no Financeiro.',
+                life: 6000
+            }
+        };
+    }
+}

src/features/agenda/services/agendaMappers.js

@@ -214,6 +214,109 @@ export function buildWeeklyBreakBackgroundEvents(pausas, rangeStart, rangeEnd) {
     return out;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// buildBloqueioBackgroundEvents
+// Renderiza rows de public.agenda_bloqueios como background events cinza
+// no FullCalendar. Suporta:
+//   - Bloqueio de dia inteiro (hora_inicio/fim NULL) → background do dia todo
+//   - Bloqueio com janela horária → background no intervalo
+//   - Bloqueio recorrente semanal (recorrente=true + dia_semana 0-6) →
+//     repetido em todas as ocorrências do dow no range
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function buildBloqueioBackgroundEvents(bloqueios, rangeStart, rangeEnd) {
+    if (!Array.isArray(bloqueios) || bloqueios.length === 0) return [];
+    if (!rangeStart || !rangeEnd) return [];
+
+    const out = [];
+    const dayMs = 24 * 60 * 60 * 1000;
+    const startMs = startOfDay(rangeStart).getTime();
+    const endMs = rangeEnd.getTime();
+
+    for (const b of bloqueios) {
+        if (!b) continue;
+        const titulo = b.titulo || 'Bloqueio';
+
+        // Recorrente semanal: itera o range varrendo dias-da-semana iguais
+        if (b.recorrente && b.dia_semana != null) {
+            const dow = Number(b.dia_semana);
+            if (!Number.isFinite(dow) || dow < 0 || dow > 6) continue;
+            const hi = asTime(b.hora_inicio);
+            const hf = asTime(b.hora_fim);
+            for (let ts = startMs; ts < endMs; ts += dayMs) {
+                const d = new Date(ts);
+                if (d.getDay() !== dow) continue;
+                if (hi && hf) {
+                    out.push(_makeBloqueioEvent(b.id ?? null, d, hi, hf, titulo));
+                } else {
+                    out.push(_makeBloqueioDayEvent(b.id ?? null, d, titulo));
+                }
+            }
+            continue;
+        }
+
+        // Não recorrente: usa data_inicio e (opcional) data_fim
+        const di = _parseISODate(b.data_inicio);
+        if (!di) continue;
+        const df = _parseISODate(b.data_fim) ?? di;
+
+        // Range de dias do bloqueio (inclusive)
+        for (let cur = di.getTime(); cur <= df.getTime(); cur += dayMs) {
+            const d = new Date(cur);
+            // Filtra fora do range visível pra evitar lixo
+            if (d.getTime() + dayMs < startMs || d.getTime() > endMs) continue;
+            const hi = asTime(b.hora_inicio);
+            const hf = asTime(b.hora_fim);
+            if (hi && hf) {
+                out.push(_makeBloqueioEvent(b.id ?? null, d, hi, hf, titulo));
+            } else {
+                out.push(_makeBloqueioDayEvent(b.id ?? null, d, titulo));
+            }
+        }
+    }
+
+    return out;
+}
+
+function _makeBloqueioEvent(id, date, timeStart, timeEnd, titulo) {
+    const tag = id ?? `blq-${date.getTime()}-${timeStart}-${timeEnd}`;
+    return {
+        id: `blq-${tag}`,
+        title: titulo,
+        start: combineDateTimeISO(date, timeStart),
+        end: combineDateTimeISO(date, timeEnd),
+        display: 'background',
+        overlap: false,
+        backgroundColor: '#6b728033', // cinza ~20%
+        extendedProps: { kind: 'bloqueio', bloqueioId: id, label: titulo }
+    };
+}
+
+function _makeBloqueioDayEvent(id, date, titulo) {
+    const yyyy = date.getFullYear();
+    const mm = String(date.getMonth() + 1).padStart(2, '0');
+    const dd = String(date.getDate()).padStart(2, '0');
+    const dateStr = `${yyyy}-${mm}-${dd}`;
+    const tag = id ?? `blq-${dateStr}`;
+    return {
+        id: `blq-day-${tag}`,
+        title: titulo,
+        start: dateStr,
+        allDay: true,
+        display: 'background',
+        overlap: false,
+        backgroundColor: '#6b728033',
+        extendedProps: { kind: 'bloqueio', bloqueioId: id, label: titulo }
+    };
+}
+
+function _parseISODate(s) {
+    if (!s) return null;
+    const m = String(s).match(/^(\d{4})-(\d{2})-(\d{2})/);
+    if (!m) return null;
+    return new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // minutesToDuration / tituloFallback
 // ─────────────────────────────────────────────────────────────────────────────

src/features/agenda/utils/colors.js

@@ -0,0 +1,28 @@
+/*
+|--------------------------------------------------------------------------
+| Agência PSI — paleta de cores da agenda
+|--------------------------------------------------------------------------
+| Mapping (tipo, status, isOccurrence) → hex color. Usado pelo card do
+| FullCalendar (borderColor/backgroundColor) e popovers de evento.
+|
+| Status manda mais do que tipo: realizado/faltou/cancelado têm cores
+| dedicadas (emerald/red/slate) independentes do tipo.
+|
+| Extraído de useMelissaAgenda.js (Fase A) pra reuso em Rail/Clínica.
+|--------------------------------------------------------------------------
+*/
+
+export function pickColor(tipo, status, isOccurrence) {
+    const s = String(status || '').toLowerCase();
+    if (s === 'realizado' || s === 'realizada') return '#10b981'; // emerald-500
+    if (s === 'faltou') return '#ef4444';                          // red-500
+    if (s === 'cancelado' || s === 'cancelada') return '#94a3b8';  // slate-400
+
+    const t = String(tipo || '').toLowerCase();
+    if (t === 'bloqueio') return '#64748b';                        // slate-500
+    if (t === 'supervisao' || t === 'supervisão') return '#a855f7'; // purple-500
+    if (t === 'reuniao' || t === 'reunião') return '#0ea5e9';      // sky-500
+
+    // Sessão default — distingue virtual (violet-500) vs real (indigo-500)
+    return isOccurrence ? '#8b5cf6' : '#6366f1';
+}

src/features/agenda/utils/dbFields.js

@@ -0,0 +1,34 @@
+/*
+|--------------------------------------------------------------------------
+| Agência PSI — whitelist de campos do agenda_eventos
+|--------------------------------------------------------------------------
+| Whitelist canônica de campos aceitos na tabela agenda_eventos pra INSERT/
+| UPDATE via cliente. Filtra qualquer chave não-prevista (defesa contra bug
+| onde payload acidentalmente carrega field defaultado pelo banco — como
+| modalidade='presencial' do bug de 2026-05-16).
+|
+| Memoria: project_pickdbfields_whitelist.md — antes era inline em
+| useMelissaAgenda.js. Extraído na Fase A.
+|--------------------------------------------------------------------------
+*/
+
+const ALLOWED_FIELDS = [
+    'tenant_id', 'owner_id', 'terapeuta_id', 'patient_id',
+    'tipo', 'status', 'titulo', 'observacoes', 'modalidade',
+    'inicio_em', 'fim_em', 'visibility_scope',
+    'mirror_of_event_id', 'mirror_source',
+    'determined_commitment_id', 'titulo_custom', 'extra_fields',
+    'recurrence_id', 'recurrence_date',
+    'price', 'insurance_plan_id', 'insurance_guide_number',
+    'insurance_value', 'insurance_plan_service_id'
+];
+
+export function pickDbFields(obj) {
+    const out = {};
+    for (const k of ALLOWED_FIELDS) {
+        if (obj[k] !== undefined) out[k] = obj[k];
+    }
+    return out;
+}
+
+export { ALLOWED_FIELDS };

src/features/agenda/utils/eventoTipo.js

@@ -0,0 +1,37 @@
+/*
+|--------------------------------------------------------------------------
+| Agência PSI — utils de tipo de evento (agenda)
+|--------------------------------------------------------------------------
+| Helpers puros pra classificar/normalizar tipo de evento. Extraídos de
+| useMelissaAgenda.js (Fase A da decomposição agenda) pra reuso em
+| Rail/Clínica + utility puro testável.
+|--------------------------------------------------------------------------
+*/
+
+export const EVENTO_TIPO = Object.freeze({ SESSAO: 'sessao', BLOQUEIO: 'bloqueio' });
+export const EVENTO_TIPOS_VALIDOS = new Set([EVENTO_TIPO.SESSAO, EVENTO_TIPO.BLOQUEIO]);
+
+// Limite máximo de duração de sessão (regra de negócio Melissa). DB constraint
+// session_duration_min_chk permite 10–240; convencionamos 120 (2h) aqui pra
+// evitar slots gigantes acidentais. Futuro: ler de agenda_configuracoes se
+// max_session_duration_min for adicionado.
+export const MAX_SESSION_MINUTES = 120;
+
+export function normalizeEventoTipo(t, fallback = EVENTO_TIPO.SESSAO) {
+    const s = String(t || '').trim().toLowerCase();
+    if (!s) return fallback;
+    if (s.includes('sess')) return EVENTO_TIPO.SESSAO;
+    if (s.includes('bloq') || s.includes('ocup')) return EVENTO_TIPO.BLOQUEIO;
+    return EVENTO_TIPOS_VALIDOS.has(s) ? s : fallback;
+}
+
+export function deriveEventoTipoForNewEvent(payload) {
+    const vis = String(payload?.visibility_scope || '').toLowerCase();
+    const title = String(payload?.titulo || '').toLowerCase();
+    if (vis === 'busy_only' || title.includes('ocup')) return EVENTO_TIPO.BLOQUEIO;
+    return EVENTO_TIPO.SESSAO;
+}
+
+export function deriveTituloDefaultByTipo(tipo) {
+    return normalizeEventoTipo(tipo, EVENTO_TIPO.SESSAO) === EVENTO_TIPO.BLOQUEIO ? 'Ocupado' : 'Sessão';
+}

src/features/agenda/utils/timeHelpers.js

@@ -0,0 +1,46 @@
+/*
+|--------------------------------------------------------------------------
+| Agência PSI — utils de tempo/data (agenda)
+|--------------------------------------------------------------------------
+| Helpers puros pra manipulação de tempo na agenda. Extraídos de
+| useMelissaAgenda.js (Fase A) pra reuso em Rail/Clínica.
+|--------------------------------------------------------------------------
+*/
+
+const UUID_RX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export function isUuid(v) {
+    return UUID_RX.test(String(v || ''));
+}
+
+/**
+ * Soma minutos a um time "HH:MM" e retorna "HH:MM:SS".
+ * Tolerante a input vazio (default 09:00).
+ */
+export function addMinutesToTime(timeStr, minutes) {
+    const [h, m] = String(timeStr || '09:00').split(':').map(Number);
+    const total = h * 60 + m + Number(minutes || 0);
+    const hh = Math.floor(total / 60);
+    const mm = total % 60;
+    return `${String(hh).padStart(2, '0')}:${String(mm).padStart(2, '0')}:00`;
+}
+
+/**
+ * ISO timestamp → hora decimal (ex: "2026-05-21T14:30:00Z" → 14.5).
+ * Usa hora local (não UTC) — propósito de exibição no calendário.
+ */
+export function isoToDecimalHour(iso) {
+    if (!iso) return 0;
+    const d = new Date(iso);
+    return d.getHours() + d.getMinutes() / 60;
+}
+
+/**
+ * Date object → "YYYY-MM-DD" (formato ISO date sem hora).
+ */
+export function dateToISO(d) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, '0');
+    const dd = String(d.getDate()).padStart(2, '0');
+    return `${y}-${m}-${dd}`;
+}

src/features/conversations/services/_tenantGuards.js

@@ -0,0 +1,22 @@
+/*
+|--------------------------------------------------------------------------
+| Agência PSI
+|--------------------------------------------------------------------------
+| Arquivo: src/features/conversations/services/_tenantGuards.js
+|--------------------------------------------------------------------------
+*/
+import { supabase } from '@/lib/supabase/client';
+
+export function assertTenantId(tenantId) {
+    if (!tenantId || tenantId === 'null' || tenantId === 'undefined') {
+        throw new Error('Tenant ativo inválido. Selecione a clínica antes de acessar conversas.');
+    }
+}
+
+export async function getUid() {
+    const { data, error } = await supabase.auth.getUser();
+    if (error) throw error;
+    const uid = data?.user?.id;
+    if (!uid) throw new Error('Usuário não autenticado.');
+    return uid;
+}

src/features/conversations/services/conversationsRepository.js

@@ -0,0 +1,115 @@
+/*
+|--------------------------------------------------------------------------
+| Agência PSI
+|--------------------------------------------------------------------------
+| Arquivo: src/features/conversations/services/conversationsRepository.js
+|
+| Repository de conversas (threads + messages). Foundation pra Módulo 6.
+|
+| ⚠️ src/composables/useConversations.js (existente) AINDA tem supabase direto.
+| Migração pra usar este repository fica pra sessão dedicada (composable é fat
+| e mistura listing + threading + realtime — audit baseline pediu split em
+| useConversationsList + useConversationThreadDetail).
+|
+| Channel send (WhatsApp Evolution/Twilio, SMS Twilio) NÃO está aqui — é
+| operação cross-canal que precisa de factory dedicada (ver audit alta:
+| conversationDrawerStore lógica de envio sem abstração).
+|--------------------------------------------------------------------------
+*/
+import { supabase } from '@/lib/supabase/client';
+import { useTenantStore } from '@/stores/tenantStore';
+import { assertTenantId } from './_tenantGuards';
+import {
+    CONVERSATION_THREAD_SELECT,
+    CONVERSATION_MESSAGE_SELECT,
+    CONVERSATION_MESSAGE_SELECT_BRIEF
+} from './conversationsSelects';
+
+function resolveTenantId(tenantIdArg) {
+    const tenantStore = useTenantStore();
+    const tenantId = tenantIdArg || tenantStore.activeTenantId || tenantStore.tenantId;
+    assertTenantId(tenantId);
+    return tenantId;
+}
+
+// ─── Threads ─────────────────────────────────────────────────────────────
+
+/**
+ * Lista threads do tenant. Limit 500 (default UI usage), ordem desc por
+ * last_message_at.
+ */
+export async function listThreads({ tenantId, limit = 500 } = {}) {
+    const tid = resolveTenantId(tenantId);
+
+    const { data, error } = await supabase.from('conversation_threads').select(CONVERSATION_THREAD_SELECT).eq('tenant_id', tid).order('last_message_at', { ascending: false }).limit(limit);
+
+    if (error) throw error;
+    return data || [];
+}
+
+/**
+ * Lê thread por id.
+ */
+export async function getThreadById(threadId, { tenantId } = {}) {
+    if (!threadId) throw new Error('threadId obrigatório.');
+    const tid = resolveTenantId(tenantId);
+
+    const { data, error } = await supabase.from('conversation_threads').select(CONVERSATION_THREAD_SELECT).eq('id', threadId).eq('tenant_id', tid).maybeSingle();
+
+    if (error) throw error;
+    return data || null;
+}
+
+/**
+ * Atualiza thread (assigned_to, kanban_status, etc).
+ */
+export async function updateThread(threadId, patch, { tenantId } = {}) {
+    if (!threadId) throw new Error('threadId obrigatório.');
+    const tid = resolveTenantId(tenantId);
+
+    const { data, error } = await supabase.from('conversation_threads').update({ ...patch, updated_at: new Date().toISOString() }).eq('id', threadId).eq('tenant_id', tid).select(CONVERSATION_THREAD_SELECT).single();
+
+    if (error) throw error;
+    return data;
+}
+
+// ─── Messages ────────────────────────────────────────────────────────────
+
+/**
+ * Lista mensagens de uma thread. Limit 500 desc por created_at.
+ */
+export async function listMessagesByThread(threadId, { tenantId, limit = 500 } = {}) {
+    if (!threadId) return [];
+    const tid = resolveTenantId(tenantId);
+
+    const { data, error } = await supabase.from('conversation_messages').select(CONVERSATION_MESSAGE_SELECT).eq('tenant_id', tid).eq('thread_id', threadId).order('created_at', { ascending: true }).limit(limit);
+
+    if (error) throw error;
+    return data || [];
+}
+
+/**
+ * Lista mensagens por paciente (brief — sem attachments pesados).
+ * Usado em prontuário (PatientConversationsTab).
+ */
+export async function listMessagesByPatient(patientId, { tenantId, limit = 200 } = {}) {
+    if (!patientId) return [];
+    const tid = resolveTenantId(tenantId);
+
+    const { data, error } = await supabase.from('conversation_messages').select(CONVERSATION_MESSAGE_SELECT_BRIEF).eq('tenant_id', tid).eq('patient_id', patientId).order('created_at', { ascending: false }).limit(limit);
+
+    if (error) throw error;
+    return data || [];
+}
+
+/**
+ * Atualiza kanban_status de uma mensagem (in-app workflow).
+ */
+export async function updateMessageKanban(messageId, kanbanStatus, { tenantId } = {}) {
+    if (!messageId) throw new Error('messageId obrigatório.');
+    const tid = resolveTenantId(tenantId);
+
+    const { error } = await supabase.from('conversation_messages').update({ kanban_status: kanbanStatus, updated_at: new Date().toISOString() }).eq('id', messageId).eq('tenant_id', tid);
+
+    if (error) throw error;
+}

src/features/conversations/services/conversationsSelects.js

@@ -0,0 +1,35 @@
+/*
+|--------------------------------------------------------------------------
+| Agência PSI
+|--------------------------------------------------------------------------
+| Arquivo: src/features/conversations/services/conversationsSelects.js
+|
+| SELECTs canônicos de conversation_threads e conversation_messages.
+| Threads usa `*` porque a UI usa muitos campos derivados (last_message_at,
+| unread_count, assigned_to, contact_number, patient_name, etc).
+|--------------------------------------------------------------------------
+*/
+
+/** Thread — UI usa praticamente todos os campos. */
+export const CONVERSATION_THREAD_SELECT = '*';
+
+/** Mensagem — campos canônicos pra timeline. */
+export const CONVERSATION_MESSAGE_SELECT = `
+    id, tenant_id, thread_id, patient_id, body, direction, channel,
+    created_at, sent_at, delivered_at, read_at,
+    kanban_status, status, contact_number, attachments
+`
+    .replace(/\s+/g, ' ')
+    .trim();
+
+/** Mensagem brief — listings em prontuário (sem campos pesados). */
+export const CONVERSATION_MESSAGE_SELECT_BRIEF = `
+    id, body, direction, created_at, channel, kanban_status
+`
+    .replace(/\s+/g, ' ')
+    .trim();
+
+/**
+ * Canais identificados no sistema (memória audit baseline M6).
+ */
+export const CHANNEL_TYPES = Object.freeze(['whatsapp', 'sms', 'email', 'in_app']);

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'
+    step.value = 'select'
-        reset()
+    reset()
-        await Promise.all([
+    await Promise.all([
-            fetchTemplates(),
+        fetchTemplates(),
-            props.patientId ? loadVariables(props.patientId, props.agendaEventoId) : Promise.resolve()
+        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
+            })
+        }
     }
 })
 
@@ -79,11 +121,19 @@ const editableVars = computed(() => {
             key,
             label: meta?.label || key,
             grupo: meta?.grupo || 'Outros',
+            source: meta?.source || '',
             value: variables.value[key] || ''
         }
     })
 })
 
+// Estatística pro topo: quantos campos vieram do auto-fill vs vazios
+const varStats = computed(() => {
+    const total = editableVars.value.length
+    const filled = editableVars.value.filter(v => String(variables.value[v.key] || '').trim() !== '').length
+    return { total, filled, empty: total - filled }
+})
+
 const varGroups = computed(() => {
     const groups = {}
     for (const v of editableVars.value) {
@@ -101,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) {
@@ -145,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>
@@ -192,17 +249,54 @@ function close() {
         </div>
 
         <!-- Step 2: Editar variaveis -->
-        <div v-else-if="step === 'edit'" class="flex flex-col gap-4">
+        <div v-else-if="step === 'edit'" class="flex flex-col gap-5">
+            <!-- Resumo do preenchimento automático -->
+            <div
+                v-if="varStats.total"
+                class="flex items-center gap-2 text-xs px-3 py-2 rounded-lg"
+                :class="varStats.empty === 0
+                    ? 'bg-green-500/10 text-green-700 dark:text-green-400'
+                    : 'bg-amber-500/10 text-amber-700 dark:text-amber-400'"
+            >
+                <i :class="varStats.empty === 0 ? 'pi pi-check-circle' : 'pi pi-info-circle'" />
+                <span v-if="varStats.empty === 0">
+                    Todos os {{ varStats.total }} campos foram preenchidos automaticamente.
+                </span>
+                <span v-else>
+                    {{ varStats.filled }} de {{ varStats.total }} preenchidos. Os campos vazios mostram onde cadastrar o dado.
+                </span>
+            </div>
+
+            <!-- Erro de carregamento de variáveis -->
+            <div
+                v-if="genError"
+                class="flex items-center gap-2 text-xs px-3 py-2 rounded-lg bg-red-500/10 text-red-600"
+            >
+                <i class="pi pi-exclamation-circle" />
+                <span>{{ genError }}</span>
+            </div>
+
             <div v-for="(vars, grupo) in varGroups" :key="grupo">
-                <div class="text-xs font-semibold uppercase tracking-wider text-[var(--text-color-secondary)] mb-2">{{ grupo }}</div>
+                <div class="text-xs font-semibold uppercase tracking-wider text-[var(--text-color-secondary)] mb-3">{{ grupo }}</div>
-                <div class="grid grid-cols-1 sm:grid-cols-2 gap-3">
+                <div class="grid grid-cols-1 sm:grid-cols-2 gap-4">
                     <div v-for="v in vars" :key="v.key" class="flex flex-col gap-1">
-                        <label class="text-xs text-[var(--text-color-secondary)]">{{ v.label }}</label>
+                        <FloatLabel variant="on">
-                        <InputText
+                            <InputText
-                            :modelValue="variables[v.key] || ''"
+                                :id="`docgen-var-${v.key}`"
-                            @update:modelValue="onVarChange(v.key, $event)"
+                                :modelValue="variables[v.key] || ''"
-                            class="w-full"
+                                @update:modelValue="onVarChange(v.key, $event)"
-                        />
+                                class="w-full"
+                                :invalid="!String(variables[v.key] || '').trim()"
+                            />
+                            <label :for="`docgen-var-${v.key}`">{{ v.label }}</label>
+                        </FloatLabel>
+                        <small
+                            v-if="!String(variables[v.key] || '').trim() && v.source"
+                            class="text-[0.65rem] text-[var(--text-color-secondary)] flex items-center gap-1 ml-1"
+                        >
+                            <i class="pi pi-link text-[0.55rem]" />
+                            {{ v.source }}
+                        </small>
                     </div>
                 </div>
             </div>
@@ -254,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/components/DocumentSignatureDialog.vue

@@ -17,6 +17,7 @@ import {
     listSignatures,
     getSignatureStatus
 } from '@/services/DocumentSignatures.service'
+import { createShareLink, buildShareUrl } from '@/services/DocumentShareLinks.service'
 
 const props = defineProps({
     visible: { type: Boolean, default: false },
@@ -42,6 +43,11 @@ const TIPOS_SIGNATARIO = [
 const signatarios = ref([])
 const patientEmails = ref([])
 
+// Geracao de share link p/ assinatura via portal/whatsapp
+const generateLink = ref(true)
+const linkExpiracaoHoras = ref(168) // 7 dias default
+const generatedShareUrl = ref('')
+
 function addSignatario() {
     signatarios.value.push({ tipo: 'paciente', nome: '', email: '' })
 }
@@ -81,6 +87,7 @@ function useEmail(email) {
 watch(() => props.visible, async (v) => {
     if (v && props.doc) {
         signatarios.value = []
+        generatedShareUrl.value = ''
         loading.value = true
         try {
             const [sigs, status] = await Promise.all([
@@ -99,6 +106,13 @@ watch(() => props.visible, async (v) => {
     }
 })
 
+function copyShareUrl() {
+    if (!generatedShareUrl.value) return
+    navigator.clipboard.writeText(generatedShareUrl.value)
+        .then(() => toast.add({ severity: 'success', summary: 'Link copiado', life: 1800 }))
+        .catch(() => toast.add({ severity: 'warn', summary: 'Falha ao copiar', detail: 'Copie manualmente.', life: 2200 }))
+}
+
 // ── Status badge ────────────────────────────────────────────
 
 const statusColor = computed(() => {
@@ -146,9 +160,39 @@ async function submit() {
     saving.value = true
     try {
         const result = await createSignatureRequests(props.doc.id, signatarios.value)
-        toast.add({ severity: 'success', summary: 'Solicitação enviada', detail: `${result.length} signatário(s) adicionado(s).`, life: 3000 })
+
-        emit('requested', result)
+        // Gera share link público quando habilitado — o paciente abre /shared/document/:token
-        emit('update:visible', false)
+        // e assina via fluxo público (RPC sign_document_by_token captura IP/UA server-side).
+        if (generateLink.value) {
+            try {
+                const link = await createShareLink(props.doc.id, {
+                    expiracaoHoras: Number(linkExpiracaoHoras.value) || 168,
+                    usosMax: Math.max(signatarios.value.length * 3, 5)
+                })
+                generatedShareUrl.value = buildShareUrl(link.token)
+                toast.add({
+                    severity: 'success',
+                    summary: 'Solicitação criada',
+                    detail: `${result.length} signatário(s). Link de assinatura gerado.`,
+                    life: 3500
+                })
+            } catch (linkErr) {
+                toast.add({
+                    severity: 'warn',
+                    summary: 'Signatários criados, mas falhou o link',
+                    detail: linkErr?.message || 'Tente gerar o link na ação "Compartilhar".',
+                    life: 4500
+                })
+            }
+        } else {
+            toast.add({ severity: 'success', summary: 'Solicitação enviada', detail: `${result.length} signatário(s) adicionado(s).`, life: 3000 })
+        }
+
+        emit('requested', { signatures: result, shareUrl: generatedShareUrl.value })
+
+        // Mantém dialog aberto se gerou link — pra terapeuta copiar.
+        // Fecha automaticamente se não gerou link.
+        if (!generatedShareUrl.value) emit('update:visible', false)
     } catch (e) {
         toast.add({ severity: 'error', summary: 'Erro', detail: e?.message || 'Falha ao solicitar assinatura.' })
     } finally {
@@ -263,6 +307,49 @@ function close() {
                 </div>
             </div>
 
+            <!-- Toggle: gerar link público -->
+            <div class="flex items-start gap-3 p-3 rounded-lg border border-blue-200 bg-blue-50/40">
+                <Checkbox v-model="generateLink" :binary="true" inputId="cb-gen-link" class="mt-0.5" />
+                <div class="flex-1">
+                    <label for="cb-gen-link" class="text-sm font-medium text-[var(--text-color)] cursor-pointer">
+                        Gerar link público para assinatura
+                    </label>
+                    <div class="text-xs text-[var(--text-color-secondary)] mt-0.5">
+                        Cria um link em <code>/shared/document/&lt;token&gt;</code> pra enviar via WhatsApp, e-mail ou copiar. O paciente assina sem precisar logar (IP, navegador e timestamp são registrados server-side).
+                    </div>
+                    <div v-if="generateLink" class="mt-2 flex items-center gap-2">
+                        <label class="text-xs text-[var(--text-color-secondary)]">Validade:</label>
+                        <Select
+                            v-model="linkExpiracaoHoras"
+                            :options="[
+                                { value: 24, label: '24 horas' },
+                                { value: 72, label: '3 dias' },
+                                { value: 168, label: '7 dias' },
+                                { value: 720, label: '30 dias' }
+                            ]"
+                            optionLabel="label"
+                            optionValue="value"
+                            class="!text-xs w-32"
+                        />
+                    </div>
+                </div>
+            </div>
+
+            <!-- Link gerado (após submit) -->
+            <div v-if="generatedShareUrl" class="p-3 rounded-lg border border-emerald-200 bg-emerald-50/40">
+                <div class="flex items-center gap-2 mb-2">
+                    <i class="pi pi-link text-emerald-600" />
+                    <div class="text-sm font-medium text-emerald-800">Link de assinatura gerado</div>
+                </div>
+                <div class="flex items-center gap-2">
+                    <InputText :modelValue="generatedShareUrl" readonly class="w-full !text-xs" />
+                    <Button icon="pi pi-copy" size="small" class="!h-8 shrink-0" v-tooltip.top="'Copiar link'" @click="copyShareUrl" />
+                </div>
+                <div class="text-[0.7rem] text-[var(--text-color-secondary)] mt-1.5">
+                    Envie este link para o(a) paciente. Eles podem assinar diretamente sem precisar criar conta.
+                </div>
+            </div>
+
             <!-- Emails cadastrados do paciente -->
             <div class="p-3 rounded-lg border border-[var(--surface-border)] bg-[var(--surface-ground)]">
                 <div class="text-xs font-semibold uppercase tracking-wider text-[var(--text-color-secondary)] mb-2">E-mails do paciente</div>

src/features/documents/components/DocumentTemplateEditor.vue

@@ -9,7 +9,7 @@
 |--------------------------------------------------------------------------
 -->
 <script setup>
-import { ref, watch, computed } from 'vue'
+import { ref, watch, computed, onMounted, onBeforeUnmount } from 'vue'
 import { useDocumentTemplates } from '../composables/useDocumentTemplates'
 import JoditEmailEditor from '@/components/ui/JoditEmailEditor.vue'
 
@@ -23,6 +23,8 @@ const emit = defineEmits(['update:modelValue', 'save', 'cancel'])
 const { TIPOS_TEMPLATE, TEMPLATE_VARIABLES, variablesGrouped, previewHtml } = useDocumentTemplates()
 
 const activeTab = ref('editor')  // editor | preview
+// Sub-tab do editor (centro do layout 3-col): qual seção renderiza
+const editorTab = ref('corpo')  // cabecalho | corpo | rodape
 
 // ── Form reativo synced com modelValue ──────────────────────
 
@@ -70,13 +72,43 @@ function insertVariable(varKey) {
         rodape_html: editorRodape
     }
     const editorRef = editorMap[cursorField.value]
+
+    // No mobile: fecha drawer + defere insertHTML pós-transição.
+    // Restaura a selection capturada quando o drawer abriu (cursor
+    // original do usuário) antes de inserir → variável aparece no
+    // ponto certo do texto, não no final.
+    if (isMobile.value) {
+        drawerOpen.value = false;
+        const markers = savedSelection.value;
+        setTimeout(() => {
+            try {
+                if (markers && editorRef?.value?.restoreSelection) {
+                    editorRef.value.restoreSelection(markers);
+                }
+                if (editorRef?.value?.insertHTML) {
+                    editorRef.value.insertHTML(tag);
+                } else {
+                    // Fallback se a API expose falhar
+                    form.value[cursorField.value] = (form.value[cursorField.value] || '') + tag;
+                }
+            } catch {
+                form.value[cursorField.value] = (form.value[cursorField.value] || '') + tag;
+            }
+            if (!form.value.variaveis.includes(varKey)) {
+                form.value.variaveis = [...form.value.variaveis, varKey];
+            }
+            savedSelection.value = null;
+        }, 280);
+        return;
+    }
+
+    // Desktop: insertHTML mantém posição do cursor (foco já tá no editor)
     if (editorRef?.value?.insertHTML) {
         editorRef.value.insertHTML(tag)
     } else {
         form.value[cursorField.value] = (form.value[cursorField.value] || '') + tag
     }
 
-    // Adiciona a variavel na lista se nao estiver
     if (!form.value.variaveis.includes(varKey)) {
         form.value.variaveis = [...form.value.variaveis, varKey]
     }
@@ -87,129 +119,756 @@ function insertVariable(varKey) {
 function onSave() {
     emit('save', { ...form.value })
 }
+
+// ── Mobile drawer (espelha padrão MelissaBloqueios/Templates) ─
+// No mobile, form (col 1) + variáveis (col 3) viram tabs dentro
+// de um drawer único. Só o editor (col 2) fica visível na tela.
+const drawerOpen = ref(false);
+const drawerTab = ref('form'); // form | vars
+const isMobile = ref(false);
+let _mqMobile = null;
+function _onMqMobileChange(e) {
+    isMobile.value = e.matches;
+    if (!e.matches) drawerOpen.value = false;
+}
+// Selection salva do editor ativo no momento de abrir o drawer de
+// variáveis. Permite inserir na posição original do cursor mesmo
+// depois do user navegar pelo drawer/perder foco.
+const savedSelection = ref(null);
+
+function openDrawer(tab) {
+    drawerTab.value = tab || 'form';
+    // Quando abre "Variáveis", salva selection do editor ativo agora
+    // (cursor original do usuário) pra restaurar depois da inserção.
+    if (tab === 'vars') {
+        const editorMap = {
+            cabecalho_html: editorCabecalho,
+            corpo_html: editorCorpo,
+            rodape_html: editorRodape
+        };
+        const editorRef = editorMap[cursorField.value];
+        savedSelection.value = editorRef?.value?.saveSelection?.() || null;
+    } else {
+        savedSelection.value = null;
+    }
+    drawerOpen.value = true;
+}
+function fecharDrawer() {
+    drawerOpen.value = false;
+    savedSelection.value = null;
+}
+
+onMounted(() => {
+    if (typeof window !== 'undefined' && window.matchMedia) {
+        _mqMobile = window.matchMedia('(max-width: 1023px)');
+        isMobile.value = _mqMobile.matches;
+        try { _mqMobile.addEventListener('change', _onMqMobileChange); }
+        catch { _mqMobile.addListener(_onMqMobileChange); }
+    }
+});
+
+onBeforeUnmount(() => {
+    if (_mqMobile) {
+        try { _mqMobile.removeEventListener('change', _onMqMobileChange); }
+        catch { _mqMobile.removeListener(_onMqMobileChange); }
+    }
+});
+
 </script>
 
+<style scoped>
+/* ═══════ Page chrome (preenche o espaço do container pai) ═══════ */
+.dte-page {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+    min-height: 0;
+    /* padding pra não grudar nas bordas do container pai (mdt-body) */
+    padding: 12px;
+    /* fallback pra quando o pai não é flex */
+    height: 100%;
+}
+
+.dte-toolbar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 10px;
+    padding: 12px 16px;
+    background: var(--surface-card);
+    border: 1px solid var(--surface-border);
+    border-radius: 10px;
+    flex-shrink: 0;
+}
+.dte-toolbar__title {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 0.92rem;
+    font-weight: 600;
+    color: var(--text-color);
+}
+.dte-toolbar__title > i {
+    color: var(--text-color-secondary);
+    opacity: 0.7;
+}
+.dte-toolbar__tabs {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+}
+
+/* ═══════ 3-col grid (form / editor / variáveis) ═══════ */
+.dte-cols {
+    flex: 1;
+    min-height: 0;
+    display: grid;
+    grid-template-columns: minmax(240px, 280px) minmax(0, 1fr) minmax(220px, 260px);
+    gap: 12px;
+    align-items: stretch;
+}
+
+/* COL 1 — Form metadados */
+.dte-side {
+    background: var(--surface-card);
+    border: 1px solid var(--surface-border);
+    border-radius: 10px;
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    overflow: hidden;
+}
+.dte-side__head {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 12px 14px;
+    border-bottom: 1px solid var(--surface-border);
+    font-size: 0.85rem;
+    font-weight: 600;
+    color: var(--text-color);
+    flex-shrink: 0;
+}
+.dte-side__head > i {
+    color: var(--text-color-secondary);
+    opacity: 0.7;
+}
+.dte-side__body {
+    flex: 1;
+    min-height: 0;
+    overflow-y: auto;
+    padding: 14px;
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+    scrollbar-width: thin;
+}
+.dte-field {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+}
+.dte-field label {
+    font-size: 0.72rem;
+    font-weight: 600;
+    color: var(--text-color-secondary);
+}
+
+/* COL 2 — Editor com sub-tabs */
+.dte-main {
+    background: var(--surface-card);
+    border: 1px solid var(--surface-border);
+    border-radius: 10px;
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    overflow: hidden;
+}
+.dte-main__tabs {
+    display: flex;
+    align-items: center;
+    gap: 0;
+    border-bottom: 1px solid var(--surface-border);
+    background: var(--surface-ground);
+    flex-shrink: 0;
+}
+.dte-tab {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    padding: 12px 18px;
+    background: transparent;
+    border: none;
+    border-bottom: 2px solid transparent;
+    color: var(--text-color-secondary);
+    font-size: 0.85rem;
+    font-weight: 600;
+    cursor: pointer;
+    transition: color 140ms ease, border-color 140ms ease, background-color 140ms ease;
+    font-family: inherit;
+}
+.dte-tab:hover {
+    color: var(--text-color);
+    background: color-mix(in srgb, var(--p-primary-color) 4%, transparent);
+}
+.dte-tab.is-active {
+    color: var(--p-primary-color);
+    border-bottom-color: var(--p-primary-color);
+    background: color-mix(in srgb, var(--p-primary-color) 6%, transparent);
+}
+.dte-tab > i { font-size: 0.82rem; }
+
+.dte-main__editor {
+    flex: 1;
+    min-height: 0;
+    overflow: hidden;
+    padding: 14px;
+    background: var(--surface-card);
+    display: flex;
+    flex-direction: column;
+}
+.dte-editor-wrap {
+    flex: 1;
+    min-height: 450px;
+    display: flex;
+    flex-direction: column;
+}
+.dte-editor-wrap > * {
+    flex: 1;
+    min-height: 0;
+    display: flex;
+    flex-direction: column;
+}
+
+/* Força o Jodit interno a expandir 100% da altura disponível
+   (substitui o height: minHeight em pixels que o JoditEmailEditor seta) */
+.dte-editor-wrap :deep(.jodit-container) {
+    flex: 1 !important;
+    height: 100% !important;
+    min-height: 450px !important;
+    display: flex !important;
+    flex-direction: column !important;
+}
+.dte-editor-wrap :deep(.jodit-workplace) {
+    flex: 1 !important;
+    min-height: 0 !important;
+}
+.dte-editor-wrap :deep(.jodit-wysiwyg) {
+    min-height: 100% !important;
+}
+
+/* COL 3 — Variáveis */
+.dte-vars {
+    background: var(--surface-card);
+    border: 1px solid var(--surface-border);
+    border-radius: 10px;
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    overflow: hidden;
+}
+.dte-vars__head {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 12px 14px 8px;
+    font-size: 0.85rem;
+    font-weight: 600;
+    color: var(--text-color);
+    flex-shrink: 0;
+}
+.dte-vars__head > i {
+    color: var(--p-primary-color);
+}
+.dte-vars__hint {
+    margin: 0 14px 6px;
+    font-size: 0.72rem;
+    color: var(--text-color-secondary);
+    line-height: 1.4;
+    flex-shrink: 0;
+}
+.dte-vars__hint strong {
+    color: var(--text-color);
+}
+.dte-vars__list {
+    flex: 1;
+    min-height: 0;
+    overflow-y: auto;
+    padding: 4px 10px 12px;
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+    scrollbar-width: thin;
+}
+.dte-vars__group {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+}
+.dte-vars__group-title {
+    font-size: 0.62rem;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.1em;
+    color: var(--text-color-secondary);
+    opacity: 0.75;
+    padding: 0 4px;
+}
+.dte-vars__group-items {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+}
+.dte-vars__btn {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    padding: 6px 8px;
+    background: transparent;
+    border: none;
+    border-radius: 6px;
+    color: var(--text-color);
+    font-size: 0.74rem;
+    text-align: left;
+    cursor: pointer;
+    transition: background-color 120ms ease, color 120ms ease;
+    font-family: inherit;
+}
+.dte-vars__btn:hover {
+    background: color-mix(in srgb, var(--p-primary-color) 10%, transparent);
+    color: var(--p-primary-color);
+}
+.dte-vars__btn-brace {
+    font-family: 'JetBrains Mono', 'Consolas', monospace;
+    font-size: 0.66rem;
+    color: var(--p-primary-color);
+    opacity: 0.6;
+}
+.dte-vars__btn-label {
+    flex: 1;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+/* ═══════ Preview ═══════ */
+/* Container externo: scroll vertical interno + fundo sutil.
+   NÃO usa flex (que limitava a altura intrínseca do doc) — usa
+   block normal com o doc centralizado via margin auto. */
+.dte-preview {
+    flex: 1;
+    min-height: 0;
+    overflow-y: auto;
+    background: var(--surface-ground);
+    border: 1px solid var(--surface-border);
+    border-radius: 10px;
+    padding: 24px;
+}
+.dte-preview__doc {
+    background: white;
+    color: #1a1a1a;
+    border-radius: 6px;
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);
+    width: 100%;
+    max-width: 794px; /* ≈ A4 a 96dpi */
+    margin: 0 auto;
+    padding: 48px 56px;
+    font-family: 'Segoe UI', Arial, sans-serif;
+    font-size: 12pt;
+    line-height: 1.6;
+    min-height: 500px;
+    /* Garante que o background-white cresce com o conteúdo
+       (em vez de ficar travado no min-height quando o doc é grande) */
+    box-sizing: border-box;
+    height: auto;
+    overflow: visible;
+}
+.dte-preview__header {
+    text-align: center;
+    margin-bottom: 20px;
+    padding-bottom: 12px;
+    border-bottom: 1px solid #ccc;
+}
+.dte-preview__body {
+    min-height: 300px;
+}
+.dte-preview__footer {
+    margin-top: 32px;
+    padding-top: 12px;
+    border-top: 1px solid #ccc;
+    text-align: center;
+    font-size: 10pt;
+    color: #666;
+}
+
+/* ═══════ Toolbar mobile actions (botões "Identificação" / "Variáveis") ═══════ */
+.dte-toolbar__mobile-actions {
+    display: none;
+    align-items: center;
+    gap: 6px;
+}
+.dte-mobile-btn {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 7px 12px;
+    border-radius: 8px;
+    border: 1px solid var(--surface-border);
+    background: var(--surface-ground);
+    color: var(--text-color);
+    cursor: pointer;
+    font-size: 0.78rem;
+    font-weight: 600;
+    flex-shrink: 0;
+    font-family: inherit;
+    transition: background-color 120ms ease;
+}
+.dte-mobile-btn:hover { background: color-mix(in srgb, var(--p-primary-color) 8%, transparent); }
+.dte-mobile-btn > i { color: var(--p-primary-color); font-size: 0.82rem; }
+
+/* ═══════ Mobile drawer (form + variáveis em tabs) ═══════ */
+.dte-mobile-drawer {
+    position: fixed;
+    top: 0; left: 0;
+    height: 100vh;
+    height: 100dvh;
+    width: min(360px, 92vw);
+    z-index: 80;
+    background: var(--surface-card);
+    border-right: 1px solid var(--surface-border);
+    transform: translateX(-100%);
+    transition: transform 250ms cubic-bezier(0.4, 0, 0.2, 1);
+    color: var(--text-color);
+    font-family: 'Segoe UI', system-ui, -apple-system, sans-serif;
+    display: flex;
+    flex-direction: column;
+    box-shadow: 4px 0 24px rgba(0, 0, 0, 0.18);
+}
+.dte-mobile-drawer.is-open { transform: translateX(0); }
+/* Durante a transição de saída, drawer ignora eventos pra não capturar
+   touch/click "perdidos" e prevenir trava no Jodit. */
+.dte-mobile-drawer:not(.is-open) { pointer-events: none; }
+
+.dte-mobile-drawer__tabs {
+    display: flex;
+    align-items: stretch;
+    gap: 0;
+    border-bottom: 1px solid var(--surface-border);
+    background: var(--surface-ground);
+    flex-shrink: 0;
+}
+.dte-drawer-tab {
+    flex: 1;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 6px;
+    padding: 12px 14px;
+    background: transparent;
+    border: none;
+    border-bottom: 2px solid transparent;
+    color: var(--text-color-secondary);
+    font-size: 0.82rem;
+    font-weight: 600;
+    cursor: pointer;
+    font-family: inherit;
+    transition: color 140ms ease, border-color 140ms ease, background-color 140ms ease;
+}
+.dte-drawer-tab:hover {
+    color: var(--text-color);
+    background: color-mix(in srgb, var(--p-primary-color) 4%, transparent);
+}
+.dte-drawer-tab.is-active {
+    color: var(--p-primary-color);
+    border-bottom-color: var(--p-primary-color);
+}
+.dte-drawer-tab > i { font-size: 0.82rem; }
+
+.dte-drawer-close {
+    width: 44px;
+    display: grid;
+    place-items: center;
+    background: transparent;
+    border: none;
+    color: var(--text-color-secondary);
+    cursor: pointer;
+    border-left: 1px solid var(--surface-border);
+    transition: background-color 120ms ease, color 120ms ease;
+}
+.dte-drawer-close:hover {
+    background: var(--surface-ground);
+    color: var(--text-color);
+}
+
+.dte-mobile-drawer__pane {
+    flex: 1;
+    min-height: 0;
+    overflow-y: auto;
+    display: flex;
+    flex-direction: column;
+    scrollbar-width: thin;
+}
+.dte-mobile-drawer__pane > .dte-side,
+.dte-mobile-drawer__pane > .dte-vars {
+    border: none;
+    border-radius: 0;
+    flex: 1;
+    width: 100%;
+}
+
+.dte-mobile-drawer__backdrop {
+    position: fixed;
+    inset: 0;
+    background: rgba(0, 0, 0, 0.45);
+    backdrop-filter: blur(4px);
+    -webkit-backdrop-filter: blur(4px);
+    z-index: 79;
+}
+.dte-drawer-fade-enter-active,
+.dte-drawer-fade-leave-active { transition: opacity 200ms ease; }
+.dte-drawer-fade-enter-from,
+.dte-drawer-fade-leave-to { opacity: 0; }
+
+/* ═══════ Mobile (<1024px): só o editor visível ═══════ */
+@media (max-width: 1023px) {
+    /* Editor ocupa tela inteira — col 1 e col 3 viram drawer */
+    .dte-cols {
+        grid-template-columns: 1fr;
+        overflow: hidden;
+    }
+    .dte-cols > .dte-side,
+    .dte-cols > .dte-vars { display: none; }
+
+    /* Mostra os botões "Identificação" / "Variáveis" no header */
+    .dte-toolbar__mobile-actions { display: inline-flex; }
+
+    /* Esconde o título canônico no mobile (espaço pros botões) */
+    .dte-toolbar__title > span { display: none; }
+    .dte-toolbar__title > i { display: none; }
+
+    .dte-preview {
+        padding: 12px;
+    }
+    .dte-preview__doc {
+        padding: 24px 18px;
+    }
+}
+</style>
+
 <template>
-    <div class="flex flex-col gap-3 xl:gap-4">
+    <!-- ══ Mobile drawer (form + variáveis em tabs) ════════════ -->
-        <!-- ══ Card: Identificação ══════════════════════════════ -->
+    <Transition name="dte-drawer-fade">
-        <div class="rounded-md border border-[var(--surface-border,#e2e8f0)] bg-[var(--surface-card,#fff)] overflow-hidden">
+        <div
-            <div class="flex items-center gap-2 px-4 py-3 border-b border-[var(--surface-border,#e2e8f0)]">
+            v-show="isMobile && drawerOpen"
-                <i class="pi pi-tag text-[var(--text-color-secondary)] opacity-60" />
+            class="dte-mobile-drawer"
-                <span class="font-semibold text-sm">Identificação</span>
+            :class="{ 'is-open': drawerOpen }"
+        >
+            <div class="dte-mobile-drawer__tabs">
+                <button
+                    type="button"
+                    class="dte-drawer-tab"
+                    :class="{ 'is-active': drawerTab === 'form' }"
+                    @click="drawerTab = 'form'"
+                >
+                    <i class="pi pi-tag" />
+                    <span>Identificação</span>
+                </button>
+                <button
+                    type="button"
+                    class="dte-drawer-tab"
+                    :class="{ 'is-active': drawerTab === 'vars' }"
+                    @click="drawerTab = 'vars'"
+                >
+                    <i class="pi pi-code" />
+                    <span>Variáveis</span>
+                </button>
+                <button
+                    type="button"
+                    class="dte-drawer-close"
+                    v-tooltip.bottom="'Fechar'"
+                    @click="fecharDrawer"
+                >
+                    <i class="pi pi-times" />
+                </button>
             </div>
-            <div class="p-4 flex flex-col gap-3">
+            <div id="dte-mobile-drawer-form" v-show="drawerTab === 'form'" class="dte-mobile-drawer__pane" />
-                <div class="grid grid-cols-1 sm:grid-cols-[1fr_220px] gap-3">
+            <div id="dte-mobile-drawer-vars" v-show="drawerTab === 'vars'" class="dte-mobile-drawer__pane" />
-                    <div class="flex flex-col gap-1">
+        </div>
-                        <label class="text-xs font-semibold text-[var(--text-color-secondary)]">Nome do template</label>
+    </Transition>
+    <Transition name="dte-drawer-fade">
+        <div
+            v-show="isMobile && drawerOpen"
+            class="dte-mobile-drawer__backdrop"
+            @click="fecharDrawer"
+        />
+    </Transition>
+
+    <div class="dte-page">
+        <!-- ══ Toggle Editor / Preview no topo ══════════════════ -->
+        <div class="dte-toolbar">
+            <!-- Botões "Identificação" e "Variáveis" — mobile-only -->
+            <div class="dte-toolbar__mobile-actions">
+                <button
+                    type="button"
+                    class="dte-mobile-btn"
+                    v-tooltip.bottom="'Identificação do template'"
+                    @click="openDrawer('form')"
+                >
+                    <i class="pi pi-tag" />
+                    <span>Identificação</span>
+                </button>
+                <button
+                    type="button"
+                    class="dte-mobile-btn"
+                    v-tooltip.bottom="'Inserir variáveis'"
+                    @click="openDrawer('vars')"
+                >
+                    <i class="pi pi-code" />
+                    <span>Variáveis</span>
+                </button>
+            </div>
+            <div class="dte-toolbar__title">
+                <i class="pi pi-file-edit" />
+                <span>Conteúdo do documento</span>
+            </div>
+            <div class="dte-toolbar__tabs">
+                <Button
+                    label="Editor"
+                    icon="pi pi-pencil"
+                    :severity="activeTab === 'editor' ? undefined : 'secondary'"
+                    :outlined="activeTab !== 'editor'"
+                    size="small"
+                    class="rounded-full"
+                    @click="activeTab = 'editor'"
+                />
+                <Button
+                    label="Preview"
+                    icon="pi pi-eye"
+                    :severity="activeTab === 'preview' ? undefined : 'secondary'"
+                    :outlined="activeTab !== 'preview'"
+                    size="small"
+                    class="rounded-full"
+                    @click="activeTab = 'preview'"
+                />
+            </div>
+        </div>
+
+        <!-- ══ EDITOR — 3 colunas (form / editor / variáveis) ══ -->
+        <div v-show="activeTab === 'editor'" class="dte-cols">
+            <!-- ─── COL 1 (esquerda): Form de metadados — teleporta pro drawer no mobile ─── -->
+            <Teleport to="#dte-mobile-drawer-form" :disabled="!isMobile">
+            <aside class="dte-side">
+                <div class="dte-side__head">
+                    <i class="pi pi-tag" />
+                    <span>Identificação</span>
+                </div>
+                <div class="dte-side__body">
+                    <div class="dte-field">
+                        <label>Nome do template</label>
                         <InputText v-model="form.nome_template" placeholder="Ex: Declaração de comparecimento" class="w-full" />
                     </div>
-                    <div class="flex flex-col gap-1">
+                    <div class="dte-field">
-                        <label class="text-xs font-semibold text-[var(--text-color-secondary)]">Tipo</label>
+                        <label>Tipo</label>
                         <Select v-model="form.tipo" :options="TIPOS_TEMPLATE" optionLabel="label" optionValue="value" class="w-full" />
                     </div>
-                </div>
+                    <div class="dte-field">
-                <div class="flex flex-col gap-1">
+                        <label>Descrição</label>
-                    <label class="text-xs font-semibold text-[var(--text-color-secondary)]">Descrição</label>
+                        <Textarea v-model="form.descricao" placeholder="Breve descrição do template" class="w-full" rows="3" autoResize />
-                    <InputText v-model="form.descricao" placeholder="Breve descrição do template" class="w-full" />
-                </div>
-                <div class="flex flex-col gap-1">
-                    <label class="text-xs font-semibold text-[var(--text-color-secondary)]">URL do logo (opcional)</label>
-                    <InputText v-model="form.logo_url" placeholder="https://..." class="w-full" />
-                </div>
-            </div>
-        </div>
-
-        <!-- ══ Card: Conteúdo ═══════════════════════════════════ -->
-        <div class="rounded-md border border-[var(--surface-border,#e2e8f0)] bg-[var(--surface-card,#fff)] overflow-hidden">
-            <div class="flex items-center justify-between gap-2 px-4 py-3 border-b border-[var(--surface-border,#e2e8f0)]">
-                <div class="flex items-center gap-2 min-w-0">
-                    <i class="pi pi-file-edit text-[var(--text-color-secondary)] opacity-60" />
-                    <span class="font-semibold text-sm">Conteúdo do documento</span>
-                </div>
-                <!-- Tabs: Editor / Preview -->
-                <div class="flex items-center gap-1">
-                    <Button
-                        :label="'Editor'"
-                        icon="pi pi-pencil"
-                        :severity="activeTab === 'editor' ? undefined : 'secondary'"
-                        :outlined="activeTab !== 'editor'"
-                        size="small"
-                        class="rounded-full"
-                        @click="activeTab = 'editor'"
-                    />
-                    <Button
-                        :label="'Preview'"
-                        icon="pi pi-eye"
-                        :severity="activeTab === 'preview' ? undefined : 'secondary'"
-                        :outlined="activeTab !== 'preview'"
-                        size="small"
-                        class="rounded-full"
-                        @click="activeTab = 'preview'"
-                    />
-                </div>
-            </div>
-
-            <!-- Editor -->
-            <div v-show="activeTab === 'editor'" class="p-4 flex flex-col lg:flex-row gap-4">
-                <!-- Campos HTML -->
-                <div class="flex-1 min-w-0 flex flex-col gap-3">
-                    <div class="flex flex-col gap-1" @focusin="cursorField = 'cabecalho_html'">
-                        <label class="text-xs font-semibold text-[var(--text-color-secondary)]">Cabeçalho</label>
-                        <JoditEmailEditor ref="editorCabecalho" v-model="form.cabecalho_html" :minHeight="120" layoutButtons :logoUrl="form.logo_url" />
                     </div>
-
+                    <div class="dte-field">
-                    <div class="flex flex-col gap-1" @focusin="cursorField = 'corpo_html'">
+                        <label>URL do logo (opcional)</label>
-                        <label class="text-xs font-semibold text-[var(--text-color-secondary)]">Corpo do documento</label>
+                        <InputText v-model="form.logo_url" placeholder="https://..." class="w-full" />
-                        <JoditEmailEditor ref="editorCorpo" v-model="form.corpo_html" :minHeight="350" />
-                    </div>
-
-                    <div class="flex flex-col gap-1" @focusin="cursorField = 'rodape_html'">
-                        <label class="text-xs font-semibold text-[var(--text-color-secondary)]">Rodapé</label>
-                        <JoditEmailEditor ref="editorRodape" v-model="form.rodape_html" :minHeight="120" layoutButtons :logoUrl="form.logo_url" />
                     </div>
                 </div>
+            </aside>
+            </Teleport>
 
-                <!-- Painel de variáveis -->
+            <!-- ─── COL 2 (centro): Tabs Cabeçalho/Corpo/Rodapé + editor ─── -->
-                <div class="w-full lg:w-[240px] shrink-0">
+            <main class="dte-main">
-                    <div class="lg:sticky lg:top-3 rounded-md border border-[var(--surface-border,#e2e8f0)] bg-[var(--surface-ground,#f8fafc)]/50 overflow-hidden">
+                <div class="dte-main__tabs">
-                        <div class="flex items-center gap-2 px-3 py-2 border-b border-[var(--surface-border,#e2e8f0)]">
+                    <button
-                            <i class="pi pi-code text-[var(--text-color-secondary)] opacity-60 text-xs" />
+                        type="button"
-                            <span class="font-semibold text-xs">Variáveis</span>
+                        class="dte-tab"
-                        </div>
+                        :class="{ 'is-active': editorTab === 'cabecalho' }"
-                        <div class="px-3 pt-2 text-[0.68rem] text-[var(--text-color-secondary)] opacity-75 italic">Clique para inserir no campo ativo</div>
+                        @click="editorTab = 'cabecalho'"
-                        <div class="flex flex-col gap-3 p-3 max-h-[500px] overflow-y-auto">
+                    >
-                            <div v-for="(vars, grupo) in variablesGrouped" :key="grupo">
+                        <i class="pi pi-align-left" />
-                                <div class="text-[0.62rem] font-semibold uppercase tracking-wider text-[var(--text-color-secondary)] mb-1">{{ grupo }}</div>
+                        <span>Cabeçalho</span>
-                                <div class="flex flex-col gap-0.5">
+                    </button>
-                                    <button
+                    <button
-                                        v-for="v in vars"
+                        type="button"
-                                        :key="v.key"
+                        class="dte-tab"
-                                        class="text-left text-xs px-2 py-1 rounded-md bg-transparent border-none hover:bg-[var(--primary-color,#6366f1)]/10 hover:text-[var(--primary-color,#6366f1)] transition-colors truncate cursor-pointer"
+                        :class="{ 'is-active': editorTab === 'corpo' }"
-                                        :title="v.key"
+                        @click="editorTab = 'corpo'"
-                                        @click="insertVariable(v.key)"
+                    >
-                                    >
+                        <i class="pi pi-align-justify" />
-                                        <span class="font-mono text-[0.62rem] opacity-60">&lbrace;&lbrace;</span>
+                        <span>Corpo</span>
-                                        {{ v.label }}
+                    </button>
-                                        <span class="font-mono text-[0.62rem] opacity-60">&rbrace;&rbrace;</span>
+                    <button
-                                    </button>
+                        type="button"
-                                </div>
+                        class="dte-tab"
-                            </div>
+                        :class="{ 'is-active': editorTab === 'rodape' }"
+                        @click="editorTab = 'rodape'"
+                    >
+                        <i class="pi pi-align-center" />
+                        <span>Rodapé</span>
+                    </button>
+                </div>
+
+                <div class="dte-main__editor">
+                    <div v-show="editorTab === 'cabecalho'" class="dte-editor-wrap" @focusin="cursorField = 'cabecalho_html'">
+                        <JoditEmailEditor ref="editorCabecalho" v-model="form.cabecalho_html" :minHeight="450" layoutButtons :logoUrl="form.logo_url" />
+                    </div>
+                    <div v-show="editorTab === 'corpo'" class="dte-editor-wrap" @focusin="cursorField = 'corpo_html'">
+                        <JoditEmailEditor ref="editorCorpo" v-model="form.corpo_html" :minHeight="450" />
+                    </div>
+                    <div v-show="editorTab === 'rodape'" class="dte-editor-wrap" @focusin="cursorField = 'rodape_html'">
+                        <JoditEmailEditor ref="editorRodape" v-model="form.rodape_html" :minHeight="450" layoutButtons :logoUrl="form.logo_url" />
+                    </div>
+                </div>
+            </main>
+
+            <!-- ─── COL 3 (direita): Variáveis disponíveis — teleporta pro drawer no mobile ─── -->
+            <Teleport to="#dte-mobile-drawer-vars" :disabled="!isMobile">
+            <aside class="dte-vars">
+                <div class="dte-vars__head">
+                    <i class="pi pi-code" />
+                    <span>Variáveis</span>
+                </div>
+                <p class="dte-vars__hint">
+                    Clique para inserir no
+                    <strong>{{ editorTab === 'cabecalho' ? 'Cabeçalho' : editorTab === 'rodape' ? 'Rodapé' : 'Corpo' }}</strong>.
+                </p>
+                <div class="dte-vars__list">
+                    <div v-for="(vars, grupo) in variablesGrouped" :key="grupo" class="dte-vars__group">
+                        <div class="dte-vars__group-title">{{ grupo }}</div>
+                        <div class="dte-vars__group-items">
+                            <button
+                                v-for="v in vars"
+                                :key="v.key"
+                                class="dte-vars__btn"
+                                :title="v.key"
+                                @click="insertVariable(v.key)"
+                            >
+                                <span class="dte-vars__btn-brace">&lbrace;&lbrace;</span>
+                                <span class="dte-vars__btn-label">{{ v.label }}</span>
+                                <span class="dte-vars__btn-brace">&rbrace;&rbrace;</span>
+                            </button>
                         </div>
                     </div>
                 </div>
-            </div>
+            </aside>
-
+            </Teleport>
-            <!-- Preview -->
-            <div v-show="activeTab === 'preview'" class="p-4">
-                <div class="rounded-md border border-[var(--surface-border,#e2e8f0)] bg-white overflow-hidden">
-                    <div class="p-6 text-black" style="font-family: 'Segoe UI', Arial, sans-serif; font-size: 12pt; line-height: 1.6;">
-                        <div v-if="form.cabecalho_html" class="text-center mb-4 pb-3 border-b border-gray-300" v-html="renderedCabecalho" />
-                        <div class="min-h-[300px]" v-html="renderedPreview" />
-                        <div v-if="form.rodape_html" class="mt-8 pt-3 border-t border-gray-300 text-center text-[10pt] text-gray-500" v-html="renderedRodape" />
-                    </div>
-                </div>
-            </div>
         </div>
 
+        <!-- ══ PREVIEW — full width ════════════════════════════ -->
+        <div v-show="activeTab === 'preview'" class="dte-preview">
+            <div class="dte-preview__doc">
+                <div v-if="form.cabecalho_html" class="dte-preview__header" v-html="renderedCabecalho" />
+                <div class="dte-preview__body" v-html="renderedPreview" />
+                <div v-if="form.rodape_html" class="dte-preview__footer" v-html="renderedRodape" />
+            </div>
+        </div>
     </div>
 </template>

src/features/documents/composables/useDocumentGenerate.js

@@ -47,8 +47,15 @@ export function useDocumentGenerate() {
         error.value = null;
         try {
             variables.value = await loadAllVariables(patientId, agendaEventoId);
+            // Hint útil pra diagnostico: se vier objeto mas todos campos vazios,
+            // sinaliza que perfil/clínica/paciente provavelmente nao tem dados.
+            const filled = Object.values(variables.value).filter(v => String(v ?? '').trim() !== '').length;
+            if (filled === 0) {
+                error.value = 'Nenhum dado foi encontrado pra auto-preencher. Verifique o cadastro do paciente, perfil e clínica.';
+            }
         } catch (e) {
-            error.value = e?.message || 'Erro ao carregar dados do paciente.';
+            console.error('[useDocumentGenerate.loadVariables] falha:', e);
+            error.value = e?.message || 'Erro ao carregar dados pra preenchimento.';
             variables.value = {};
         } finally {
             loading.value = false;
@@ -92,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;
@@ -111,7 +121,9 @@ export function useDocumentGenerate() {
                 patientId,
                 dadosPreenchidos: { ...variables.value },
                 pdfBlob: blob,
-                templateNome
+                templateNome,
+                templateTipo: selectedTemplate.value.tipo,
+                editingDocId
             });
             generatedDocs.value.unshift(result);
             return result;

src/features/documents/composables/useDocumentSignatures.js

@@ -0,0 +1,167 @@
+/*
+|--------------------------------------------------------------------------
+| Agência PSI
+|--------------------------------------------------------------------------
+| Arquivo: src/features/documents/composables/useDocumentSignatures.js
+| Composable Tipo A (thin wrapper) sobre DocumentSignatures.service.
+|--------------------------------------------------------------------------
+*/
+import { ref } from 'vue';
+import {
+    createSignatureRequests,
+    listSignatures,
+    getSignatureStatus,
+    refuseSignature,
+    signByPortal,
+    signByToken,
+    getSignableDocumentByToken,
+    listMySignatures,
+    hashDocument
+} from '@/services/DocumentSignatures.service';
+
+export function useDocumentSignatures() {
+    const signatures = ref([]);
+    const loading = ref(false);
+    const error = ref('');
+    const status = ref(null); // { total, assinados, pendentes, status }
+
+    async function fetchForDocument(documentoId) {
+        if (!documentoId) {
+            signatures.value = [];
+            status.value = null;
+            return [];
+        }
+        loading.value = true;
+        error.value = '';
+        try {
+            const [list, st] = await Promise.all([
+                listSignatures(documentoId),
+                getSignatureStatus(documentoId)
+            ]);
+            signatures.value = Array.isArray(list) ? list : [];
+            status.value = st || null;
+            return signatures.value;
+        } catch (e) {
+            error.value = e?.message || 'Falha ao carregar assinaturas.';
+            signatures.value = [];
+            status.value = null;
+            throw e;
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function requestSignatures(documentoId, signatarios = []) {
+        loading.value = true;
+        error.value = '';
+        try {
+            const rows = await createSignatureRequests(documentoId, signatarios);
+            signatures.value = [...signatures.value, ...rows];
+            return rows;
+        } catch (e) {
+            error.value = e?.message || 'Falha ao solicitar assinaturas.';
+            throw e;
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function sign(signatureId, { hashDocumento = null } = {}) {
+        loading.value = true;
+        error.value = '';
+        try {
+            const updated = await signByPortal(signatureId, hashDocumento);
+            const idx = signatures.value.findIndex(s => s.id === signatureId);
+            if (idx >= 0) signatures.value.splice(idx, 1, updated);
+            return updated;
+        } catch (e) {
+            error.value = e?.message || 'Falha ao assinar documento.';
+            throw e;
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function refuse(signatureId) {
+        loading.value = true;
+        error.value = '';
+        try {
+            const updated = await refuseSignature(signatureId);
+            const idx = signatures.value.findIndex(s => s.id === signatureId);
+            if (idx >= 0) signatures.value.splice(idx, 1, updated);
+            return updated;
+        } catch (e) {
+            error.value = e?.message || 'Falha ao recusar assinatura.';
+            throw e;
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function signWithToken(token, signatureId = null, { hashDocumento = null } = {}) {
+        loading.value = true;
+        error.value = '';
+        try {
+            return await signByToken(token, signatureId, hashDocumento);
+        } catch (e) {
+            error.value = e?.message || 'Falha ao assinar via link.';
+            throw e;
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function loadMine(statusFilter = null) {
+        loading.value = true;
+        error.value = '';
+        try {
+            const rows = await listMySignatures(statusFilter);
+            signatures.value = Array.isArray(rows) ? rows : [];
+            return signatures.value;
+        } catch (e) {
+            error.value = e?.message || 'Falha ao carregar minhas assinaturas.';
+            signatures.value = [];
+            throw e;
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    async function loadByToken(token) {
+        loading.value = true;
+        error.value = '';
+        try {
+            const payload = await getSignableDocumentByToken(token);
+            if (!payload?.valid) {
+                error.value = payload?.error === 'expired_or_invalid'
+                    ? 'Link expirado ou inválido.'
+                    : payload?.error === 'document_not_found'
+                        ? 'Documento não encontrado.'
+                        : 'Token inválido.';
+                return null;
+            }
+            signatures.value = Array.isArray(payload.signatures) ? payload.signatures : [];
+            return payload;
+        } catch (e) {
+            error.value = e?.message || 'Falha ao validar token.';
+            throw e;
+        } finally {
+            loading.value = false;
+        }
+    }
+
+    return {
+        signatures,
+        status,
+        loading,
+        error,
+        fetchForDocument,
+        requestSignatures,
+        sign,
+        refuse,
+        signWithToken,
+        loadByToken,
+        loadMine,
+        hashDocument
+    };
+}