agenda: Fase 5 (status change/edit cobrada) + indicadores visuais + UX convenio

DB
- drop agenda_excecoes (substituida por financial_exceptions + lock-edit
  baseado em financial_records)
- financial_records.payment_link (Asaas + link compartilhavel)
- financial_exceptions.consume_on_miss (rotular nao-show consome ou nao)
- billing_contracts.charging_style (upfront/saldo/per_session)

Payment refactor
- paymentSettlement -> paymentMethod (string) + markPaidNow (bool).
  Handler aplica payment_method sempre; status='paid'+paid_at apenas
  quando markPaidNow=true && method != 'link'. Asaas (link) sempre
  liquida via webhook, nunca nasce paid.
- create_financial_record_for_session com pos-RPC patch pra payment_method
  e (opcional) status='paid' quando user marca "ja recebi".

Indicadores visuais (3 canais distintos por estado)
- Paid: barra esquerda emerald-500 4px na agenda (MelissaAgenda),
  pi-check-circle no popover/Resumo.
- Pending: badge \$ amber canto direito (mantido); linha amber no popover/
  Resumo "A receber R\$ X (cobranca pendente)".
- Neutro: sem badge nem barra (compromisso pessoal, bloqueio, ou
  ocorrencia virtual de pacote upfront/saldo).
- Bulk-load de paymentState em _reloadRange etapa 4 (1 query unica em
  financial_records mapeada por agenda_evento_id).
- AgendaEventDialog Resumo lateral ganha linha entre pi-clock e
  pi-map-marker via novo sessionPaymentRecord (sem guard de
  occurrenceMode, contrario ao occFinancialRecord que continua so pra
  Rail/Clinica). 5 estados: paid+paid_at, overdue+venceu, pending+vence,
  sem cobranca c/ valor, sem cobranca s/ valor.

UX de convenio
- InsurancePlanServiceQuickCreateDialog novo: cadastra procedimento
  POR CIMA do AgendaEventDialog sem sair da agenda. Auto-seleciona
  novo procedimento so quando nada estava selecionado antes.
- Caixa cinza "Cadastrar procedimento" sempre visivel quando convenio
  selecionado, com copy variavel (0 procedimentos: chamada urgente;
  1+: "se quiser adicionar mais").
- "+ Novo convenio" toolbar em ConfiguracoesConveniosPage (botao
  estava faltando, empty state mandava clicar em botao inexistente).
- Hint contextual abaixo do card Sessao/Honorarios: convenio = "N da
  guia eh opcional", gratuito = "sem cobranca", particular = sem hint.
  Label "N da Guia" tambem ganhou "(opcional)" no service-picker dialog.

Bug fixes
- pickDbFields whitelist faltando 'modalidade' (useMelissaAgenda.js:74)
  — sessoes avulsas eram salvas como presencial independente da
  escolha visual. Adicionado.
- goToConveniosConfig removida — fazia router.push("/therapist/
  configuracoes/convenios") mas /configuracoes/* eh rota raiz, nao
  filha. Substituida pelo quick-create inline (#1).
- bloqueioCobrindo + dialogBlockOverlap passados via deps em
  _buildHandlers (refs do useMelissaAgenda nao sao acessiveis no
  escopo de _buildHandlers).

Fase 5 (status change + edit cobrada)
- AgendaStatusChangeConfirmDialog: confirm dialog quando user muda
  status pra realizada/faltou/cancelado, com opcoes de markPaid ou
  gerar cobranca conforme o caso.
- useAgendaBloqueios novo composable: extrai logica de bloqueios
  cinza (background events) do MelissaAgenda.

Doc viva
- src/docs/agenda-compromisso-financeiro-cenarios.html: 13 cenarios
  de teste manual. C1-C4 ja validados. Cada teste validado vira parte
  da doc final pra area de ajuda (pos-Fase 9).

Wiki/handoff
- agenda-compromisso-fluxo e agenda-billing-pesquisa-mercado (decisoes
  arquiteturais sobre billing).
- HANDOFF.md atualizado.

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

Obsidian/Brain/log.md

@@ -14,6 +14,142 @@ Chronological, append-only record of everything that's happened in this wiki.
 
 ---
 
+## [2026-05-18 23:30] session | UX de convenio refinado (3 fixes) + hint contextual
+Touched: none (sem nova wiki page; tudo em codigo + HANDOFF)
+Detalhes: tarde inteira consumida em refinar UX de convenio antes do
+save real do C5. User bateu em 3 problemas seguidos:
+
+1) Botao "Cadastrar" do procedimento navegava pra /pages/notfound.
+   Root cause: goToConveniosConfig prefixava com /therapist|/admin mas
+   /configuracoes/* eh rota raiz sob AppLayout (sibling, nao filho). Em
+   Melissa, convenios mora via secao=cfg-convenios sem URL propria.
+   Fix descartado: user nao queria sair da agenda. Criamos quick-create
+   inline (#2). Removi goToConveniosConfig (dead code).
+
+2) InsurancePlanServiceQuickCreateDialog (novo componente). Mesmo pattern
+   do InsurancePlanQuickCreateDialog. 2 campos: nome + valor que o
+   convenio paga. Wiring em useAgendaEventLifecycle: planServiceQuickDlgOpen
+   + openPlanServiceQuickCreate + onPlanServiceCreated. Apos criar:
+   loadInsurancePlans + auto-seleciona SO se nada estava selecionado
+   antes. UI refatorada: caixa cinza com botao "Cadastrar" SEMPRE
+   visivel quando convenio selecionado, copy varia por contagem
+   (0 procedimentos = chamada urgente; 1+ = "se quiser adicionar mais").
+
+3) Botao "+ Novo convenio" faltando em ConfiguracoesConveniosPage.vue.
+   addingNew=true sem botao pra setar. Empty state mandava clicar em
+   botao inexistente. Fix: toolbar topo com Button label="Novo convenio"
+   @click="addingNew = true". Empty state corrigida.
+
+Hint contextual abaixo do card Sessao/Honorarios. User: "Nº da guia
+eh obrigatorio?" — consegui salvar sem. Tentativa 1: coloquei em
+v-if=occurrenceMode (errado, so Rail/Clinica). Tentativa 2: fluxo
+principal Melissa (linha 2305). Copy: convenio = "Nº da guia eh
+opcional…", gratuito = "Sessão gratuita…", particular = sem hint.
+Label "Nº da Guia" tambem ganhou "(opcional)".
+
+PROXIMO: rodar de fato o save do C5 (Sandor + Unimed + R$ 95). Tudo
+preparado, agora eh testar end-to-end.
+
+## [2026-05-18 21:45] session | Linha de cobranca no popover (3 estados) + Resumo do dialog
+Touched: none (sem nova wiki page)
+Detalhes: extensao do trabalho da sessao anterior (barra verde na agenda).
+User pediu pra popover mostrar tambem o estado pago, nao so pendente.
+Lembrava que "tinha algo assim mas talvez seja pra outra coisa" —
+verifiquei: occFinancialRecord existia mas com guard de occurrenceMode,
+servindo Fase 6 (lock-edit) em Rail/Clinica apenas. Decidi NAO unguardar
+pra nao ativar lock prematuro em Melissa (isso eh C13).
+
+MelissaEventoPanel.vue: showPaymentRow agora cobre paid tambem; novo
+paymentVariant + paymentIcon (pi-check-circle quando pago, pi-dollar
+nos outros); paymentLabel inclui "Pago · R$ X,XX"; CSS com 3
+modificadores .evento-row--pay-{paid|pending|none} + dark mode.
+
+AgendaEventDialog.vue + useAgendaEventLifecycle.js: novo ref
+sessionPaymentRecord (independente do occFinancialRecord). Loader sem
+guard, chamado no mesmo lifecycle. Computed paymentSummary cobre 5
+estados (paid + verde + paid_at, overdue + vermelho + venceu, pending
++ amber + vence, sem cobranca c/ valor, sem cobranca s/ valor). Nova
+linha summary-row entre pi-clock e pi-map-marker em ambas as copias do
+Resumo (mobile inline + desktop floating). CSS com 4 classes
+.aed-pay-summary-row--{paid|pending|overdue|none}.
+
+@cobranca-atualizada do AgendaEventoFinanceiroPanel agora tambem
+dispara loadSessionPaymentRecord pra a linha refrescar quando user
+marca pago pelo panel inline.
+
+PROXIMO: cenario 5 (Sandor + Unimed Nacional, R$ 95, convenio).
+
+## [2026-05-18 21:00] session | Cenario 4 OK + barra esquerda verde pra sessao paga
+Touched: none (decisao salva em memory/, doc HTML atualizado, sem nova wiki page)
+Detalhes: cenario 4 (Joyce R$180 PIX "Ja recebi") testado e passou — toast,
+record paid+pix+paid_at, badge $ removido. User pediu sinalizacao visual
+pra sessao paga "olhar e saber". Brainstorm de 6 opcoes (check verde
+canto, barra esquerda, fundo green-50, $ riscado, so popover, 3 canais
+combinados). User escolheu #6 — 3 canais visuais distintos:
+- pago: barra verde 4px borda esquerda (emerald-500)
+- pendente: badge $ amber canto direito (como antes)
+- neutro: nem um nem outro (sem cobranca / virtual)
+Implementado em MelissaAgenda.vue (classe ma-evt--paid via classNames,
+CSS forca border-left-color !important porque FC seta borderColor inline).
+Doc HTML legenda "Indicadores visuais" expandida pros 3 estados (3 mocks
+empilhados). Estado-alvo do C4 reescrito. Memoria persistida em
+memory/project_agenda_payment_indicators.md (decisao + onde aplicar quando
+replicar em Rail/Clinica). HANDOFF atualizado pra apontar C5 como
+proximo.
+
+## [2026-05-17 02:30] session | Testes C1-C3 + payment refactor + indicadores visuais + fix modalidade
+Touched: agenda-compromisso-fluxo (implicit via HANDOFF.md, sem nova pagina)
+Detalhes: rodada de testes manuais dos cenarios do doc viva
+src/docs/agenda-compromisso-financeiro-cenarios.html. Cenarios 1, 2 e 3 ok.
+
+CENARIO 1 (bloqueio):
+- Fix `bloqueioCobrindo is not defined` em onSelectTime — funcao mora no
+  escopo de useMelissaAgenda mas onSelectTime esta em _buildHandlers.
+  Passada via deps, mesmo padrao do _openStatusDialog.
+- Soft warn de bloqueio sobre slot agora vai DENTRO do dialog (Message
+  warn no topo do step 1) em vez de toast atras do overlay. Novo ref
+  dialogBlockOverlap no composable + nova prop blockOverlapWarning no
+  AgendaEventDialog. Reset nos outros openers.
+- Doc HTML cenario 1 expandido em 1a (criar) + 1b (agendar sobre
+  bloqueio), com mock visual da Message + comparacao agendador publico.
+
+CENARIO 2 (avulsa sem cobranca):
+- Hint chargeMode fonte 0.72rem -> 0.8125rem.
+- Card Frequencia avulsa refeito: era empty state convidando configurar,
+  agora renderiza como "selecionado" com .aed-pay-summary (Tipo: Avulsa
+  / Sessao unica, sem repeticao / botao Editar). Visual identico ao
+  estado configurado de pacote.
+
+CENARIO 3 (avulsa cobrar ao salvar):
+- Refactor paymentSettlement -> paymentMethod + markPaidNow. UI antiga
+  misturava metodo e status num Select unico ("Ja recebi - PIX"). Agora
+  2 controles: Select forma (sem prefixo "Ja recebi") + SelectButton
+  status (pendente / ja recebi). SelectButton oculto quando metodo='link'.
+  Wire em 3 camadas (Dialog -> useAgendaEventActions -> useMelissaAgenda
+  handler avulsa + _createPackageContract).
+- Indicadores visuais de pagamento: bulk-load 1x em _reloadRange etapa 4
+  (financial_records mapeado por agenda_evento_id -> paid|pending|none).
+  normalizeForMelissa injeta paymentState + price. Badge $ amber 16px no
+  canto superior direito do evento da agenda (so sessao+paciente+nao-
+  virtual+!paid). Linha "A receber" amber abaixo do horario no popover
+  (MelissaEventoPanel), texto adaptativo.
+- BUG FIX pickDbFields whitelist faltando 'modalidade' — todas as sessoes
+  avulsas criadas no Melissa ate hoje foram salvas como presencial no DB
+  independente da escolha visual. Adicionado ao allowed[]. Gotcha durador
+  salvo em memory/project_pickdbfields_whitelist.md.
+
+DOC HTML AMPLAMENTE ATUALIZADO:
+- Nova secao topo "★ Indicadores visuais de pagamento" com mocks (badge
+  $ + linha popover) e link em violeta no TOC.
+- Caixa violeta "Indicadores visuais" em cada cenario relevante (C2-C9)
+  descrevendo o que aparece em cada caso.
+- C4 ganhou caixa verde "estado-alvo" (sem badge, sem linha — pago).
+- Receitas dos C2-C4 atualizadas pros 3 controles novos.
+
+PROXIMO: cenario 4 (Joyce, "Ja recebi (dar baixa)"). Apos passar, seguir
+ate C13. Quando todos passarem, replicar em AgendaTerapeutaPage (Rail) e
+AgendaClinicaPage (Clinica). HANDOFF.md reescrito com tudo.
+
 ## [2026-05-05 23:45] session | Blueprint tabular Melissa + restore pacientes
 Touched: none (sem mudança de wiki — handoff em HANDOFF.md)
 Detalhes: criou `blueprints/melissa-table-page-blueprint.md` (~530L, 18 seções);
@@ -601,3 +737,126 @@ ComponentCadastroRapido + PatientCadastroDialog pra uso in-flow.
 
 Database backup gerado: backups/2026-05-11/ (138 tabelas, 141 FKs).
 Dashboard regenerado.
+
+## [2026-05-11 17:00] session | AgendaEventDialog redesign completo + 2º dialog WIP
+Touched: HANDOFF.md (reescrito do zero)
+Detalhes: sessao longa de refator visual + UX do AgendaEventDialog.
+Headers dos 4 cards (Paciente, Data/Horario, Sessao/Honorarios, Frequencia)
+com altura fixa 40px, label so mobile, acoes a direita. Card Paciente
+ganhou toggle Presencial/Online com pi-pencil substituindo SelectButton;
+mini-links Editar/Limpar no lugar dos botoes redondos. Card Data e
+Horario com body em 2 linhas (Data · Duracao / Inicio → Termino). Card
+Sessao/Honorarios (renomeado de Pagamento) com Select dropdown default
+particular + 3 estados (gratuito/empty/configurado-resumo). Card Extras
+renomeado, com botao ? abrindo popover educativo. Layout 50/50 via
+.aed-row-50 (Paciente|Data e Sessao|Frequencia).
+
+DIALOGS NOVOS:
+- serviceDialogOpen: cada servico vira card individual com preco unit,
+  total, botoes colapsaveis (Aplicar desconto, Alterar quantidade);
+  desconto mostra calculo em vermelho; footer fixo com Valor desta
+  sessao em pill tracejada primary; hint educativo Unidades vs
+  Recorrencia
+- freqDialogOpen: empty/resumo, 4 sub-cards (.aed-freq-section: Tipo,
+  Dias, Quantidade, Proximas), chips renovados (.freq-tab borda solida
+  + variant 2-line com 1 mes/4 sessoes), proximas ocorrencias com
+  separador por mes + referencia relativa (em 2 semanas/em 1 mes).
+  "Como interpretar o valor" REMOVIDO.
+
+CONCEITO PACOTE (recorrencia >= 2):
+- isPacote computed: criando >=2 OU editando hasSerie
+- pacoteTotal = totalFromItems × totalOcorrencias
+- Header dialog adapta: "Pacote · 4 Sessoes" / "Sessao do Pacote · Sessao"
+  / "Editar Sessao" / "Nova Sessao"
+- Resumo: modalidade vira "Presencial · Pacote"; wallet mostra total
+  pacote; linha extra "4× R$ 40 = R$ 160"
+- Status da Sessao escondido em pacote
+- pluralCommitment PT-BR (Sessao→Sessoes, Analise→Analises, ão→ões)
+
+MODO EDIÇAO:
+- Cadastro Rapido NAO aparece
+- Cadastro Completo + toggle Modalidade + Ajustar Horario: disabled
+  com tooltip explicativo
+- time-hero ganha --readonly (sem cursor pointer)
+
+OUTROS: animacao de Dialog + backdrop blur REMOVIDOS (so nativo
+PrimeVue); DataTable picker paciente coluna Acao agora frozen
+alignFrozen=right; lista Recorrencias Aplicadas com numeracao 1/2/3
+em badge primary; badge "atual" → "selecionado".
+
+2º DIALOG EMPILHADO (WIP — BLOQUEIO PRA AMANHA):
+- useMelissaAgenda.js: refs novos occDialogOpen/EventRow/StartISO/EndISO
+- onEditSeriesOccurrence agora abre 2º dialog (em vez de mutar
+  dialogEventRow in-place silenciosamente)
+- _buildHandlers recebe occDialog* via deps (sem isso dava
+  ReferenceError em runtime)
+- MelissaLayout.vue: 2º AgendaEventDialog mountado paralelo, refs
+  destruturados como agendaOccDialog* (refs aninhados nao auto-
+  unwrappam no template — pattern conhecido do projeto)
+- Status: ABRE, mas user reportou "nao é essa janela que tem de
+  abrir" — investigar amanha. Provavelmente precisa de prop pra
+  esconder Frequencia + Recorrencias Aplicadas no 2º dialog e
+  ajustar titulo pra "Editar Ocorrencia"
+- Pendente replicar em Rail (AgendaTerapeutaPage L1630 + L3080) e
+  Clinica (AgendaClinicaPage L1119 + L2398) DEPOIS de estabilizar
+  no Melissa
+
+Mudancas NAO commitadas: 5 arquivos (AgendaEventDialog.vue + dois
+QuickCreateDialog + MelissaLayout + useMelissaAgenda). HANDOFF.md
+reescrito do zero documentando tudo.
+
+## [2026-05-12 17:55] session | occurrenceMode no 2º dialog da agenda
+Touched: recorrencia-agenda
+
+## [2026-05-13 14:00] session | pesquisa fluxo agenda Cliniko SimplePractice TherapyNotes
+Touched: none
+nTouched: agenda-billing-pesquisa-mercado, index
+
+## [2026-05-13 21:00] session | Pesquisa mercado agenda billing
+Touched: agenda-billing-pesquisa-mercado, index
+
+## [2026-05-14 sessao continua] session | AgendaEventDialog testes manuais + correcoes
+Touched: none (apenas logs detalhados; sem nova pagina wiki)
+Detalhes: User testou fluxo de criacao avulsa (Henrique Lima Souza) e
+recorrente (Donald Winnicott, 4×R$40) passo-a-passo. Achados/correcoes:
+(1) Bug badge financeiro "Despesa" — campo `type` faltava em BASE_SELECT
+de useFinancialRecords.js (caia em else → "Despesa"). Fix: adicionar type
+no SELECT. (2) E5 toggle Presencial/Online: removido :disabled="isEdit"
+(habilitado em ediçao tambem). (3) E6 Ajustar Horario: trocado por
+v-if="!isEdit || !hasSerie" — visivel em criacao E em avulsa em edicao;
+escondido em série recorrente (politica "esconder em vez de disabled"
+salva na memoria, vale apenas pra agenda). (4) Botao cog + popover sobre
+horarios online no time picker — padrao espelhado do Card Extras, linka
+pra /melissa/agenda-config (ou /configuracoes/agenda fora do Melissa).
+(5) Bug visual: pill --current + --online-cfg perdia destaque selected
+porque online-cfg !important ganhava da cascade. Fix: regra combo com
+mais especificidade. (6) Time picker vazava dia/hora/duracao pro card
+principal quando fechado sem confirmar — snapshot ao abrir + revert no
+@hide se _tpCommitted=false (added Cancelar button no footer). (7)
+Opção C1 implementada — checkbox bool gerarCobrancaAoSalvar substituido
+por SelectButton chargeMode com opcoes dinamicas:
+  - Avulsa: Não / Gerar cobrança
+  - Recorrente: Não / Pacote único / 1 por sessão
+Handler em useMelissaAgenda agora suporta 3 modos: 'session' (1
+financial_record, igual Fase 1 original), 'package' (1 billing_contract
+inline em vez de confirm.require pós-save), 'per_session' (materializa N
+agenda_eventos + cria N financial_records via RPC, respeitando
+recurrence_exceptions). _offerBillingContract removido (codigo morto).
+useAgendaEventActions.gerarCobrancaAoSalvar → chargeMode. ESLint: 0
+erros novos. Vitest useAgendaEventComposer.spec: 76/76 passed.
+
+## [2026-05-13 22:00] session | Fase 1 — drop agenda_excecoes + render bloqueios cinza
+Touched: agenda-compromisso-fluxo
+Detalhes: Fase 1 da auditoria fase-a-fase concluida. Auditoria revelou
+agenda_excecoes orfa (0 refs em src/, embora policies+trigger+enums
+existissem) e bloqueios nunca renderizados no FullCalendar (so impediam
+criacao). Aplicado: (1) migration 20260513000001_drop_agenda_excecoes.sql
+dropa tabela+enums+trigger; (2) agendaMappers.buildBloqueioBackgroundEvents
+renderiza dia-cheio/com-hora/recorrente como background event #6b728033;
+(3) composable useAgendaBloqueios reusavel (load aceita owner unico OU
+array); (4) wire nos 3 layouts (Melissa via useMelissaAgenda+MelissaAgenda,
+Rail via AgendaTerapeutaPage, Clinica via AgendaClinicaPage com multi-owner);
+(5) docs/schema_map.md e db.config.json limpos. ESLint 0 novos errors;
+agendaMappers.spec 40/40 passed. Pendente: rodar migration no banco local
++ validacao visual nos 3 layouts. Plano de 8 fases salvo em
+[[agenda-compromisso-fluxo]]; pesquisa de mercado em [[agenda-billing-pesquisa-mercado]].

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'`