Leonardo
e95ed9b585
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>
21 KiB
title, date, status, players
| title | date | status | players |
|---|---|---|---|
| Pesquisa de mercado — fluxo de compromisso e cobrança | 2026-05-13 | levantamento | 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, 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, 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, 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, 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, Adding a new client.
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, 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, 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, Managing appointment statuses and billing, 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, Submit Electronic Claims, 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, 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, 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.
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, 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, 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, TherapyNotes 4.15 release notes.
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, Recording refunds: an overview, 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, 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.
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
- Bloqueio de tempo é entidade própria, separada de appointment. Nunca um appointment "sem paciente".
- Cadastro mínimo de paciente (1 campo) é aceito; campos pesados só ficam obrigatórios na hora de cobrar plano ou ativar portal.
- Recorrência cria ocorrências independentes para billing; nenhum gera "fatura única da série".
- Edit de uma ocorrência pergunta "esta / todas / futuras" — padrão consagrado.
- Cobrança nunca é gerada na criação do appointment futuro — sempre depois (sessão, status, nota, ou trigger manual).
- 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.
- Deletar pagamento ≠ reembolsar dinheiro — distinção explícita nos 3.
- 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
-
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.
-
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.
-
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).
-
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.
-
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.
-
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.
-
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.
-
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.