Documento Estratégico Fundacional

# Plataforma de
Saúde Mental

Ecossistema completo para gestão clínica, educação continuada e conexão terapêutica — com modelo de dados real documentado

Versão 2.0 Confidencial Schema Supabase v17.6 PostgreSQL 17 2025
scroll
01

## Visão Geral do Projeto

Este documento descreve de forma completa e minuciosa o projeto de uma Plataforma de Saúde Mental — um ecossistema digital integrado que reúne gestão clínica, educação continuada e conexão entre profissionais e pacientes em um único ambiente.

A versão 2.0 deste documento incorpora a realidade do banco de dados já construído: tabelas reais, enums implementados, funções RPC em produção e decisões arquiteturais que foram tomadas durante o desenvolvimento. Este não é mais um documento de intenções — é o espelho fiel do que existe e do que está sendo construído.

"Não estamos construindo um software de gestão. Estamos construindo o ecossistema que o profissional de saúde mental brasileiro nunca teve."
O que mudou na v2.0: Adicionados os capítulos 11, 12 e 13 com a documentação completa do schema real do banco de dados (Supabase/PostgreSQL 17.6), incluindo as 60+ tabelas do schema público, todos os enums implementados e as principais funções RPC de negócio. O capítulo 07 foi expandido com os tipos de tenant reais. O capítulo 10 foi atualizado com as chaves de plano reais (`plans.target`: patient, therapist, clinic, supervisor).

### Pilares Fundadores

🏛
Confiança Clínica

Seriedade, conformidade com LGPD e segurança de dados sensíveis desde a fundação.

⚡
Redução de Fricção

Cada funcionalidade deve economizar tempo real do profissional, nunca criar mais trabalho.

🕸
Efeito de Rede

Quanto mais profissionais entram, mais o produto vale para cada um deles.

📚
Educação como Aquisição

Conteúdo de microlearning que atrai, engaja e converte o profissional ideal.

🔐
RLS por Design

Row Level Security do Supabase garante que cada tenant só acessa seus próprios dados — sem possibilidade de vazamento cruzado.

🧩
Multi-Tenant Real

A coluna `tenant_id` está em todas as tabelas críticas, garantindo isolamento total por clínica ou terapeuta.

02

## Origem e Motivação

O projeto surgiu da observação direta de um problema recorrente: profissionais de saúde mental altamente capacitados clinicamente, mas completamente despreparados para gerir o aspecto administrativo e financeiro de suas práticas.

A pandemia de COVID-19 acelerou a digitalização do setor — o atendimento online normalizou-se, a demanda por terapia explodiu e o número de profissionais cresceu. Porém, as ferramentas disponíveis no mercado não acompanharam essa evolução em profundidade. Resolvem o agendamento, mas ignoram a clínica. Resolvem o financeiro, mas ignoram o paciente.

A motivação central é construir o produto que o mercado deveria ter criado há anos: uma plataforma que entende que o terapeuta também é paciente, que a clínica é feita de relações humanas, e que educação e prática clínica são inseparáveis.

### O Papel do Parceiro Acadêmico

Um dos diferenciais estratégicos do projeto é a parceria com um profissional em formação em psicologia e já atuante como psicanalista. Essa combinação une a visão clínica prática com o rigor acadêmico, permitindo a produção de conteúdo de microlearning com autoridade real.

Com o tempo, esse parceiro poderá atuar como supervisor clínico dentro da plataforma. O schema já prevê isso: `plans.target = 'supervisor'` e `tenants.kind = 'supervisor'` são tipos nativos do sistema, não adições futuras.

03

## O Problema que Resolvemos

### 1. Fragmentação de Ferramentas

O profissional usa Google Agenda para agendamento, WhatsApp para comunicação, planilha para financeiro, Word para prontuário e e-mail para cobrança. São 5 ferramentas para uma única prática clínica.

### 2. Ausência de Visão Clínica nos Sistemas Atuais

Os softwares existentes tratam o atendimento como uma transação comercial. Não há suporte para acompanhamento de evolução do paciente, aplicação de escalas validadas ou registro estruturado por abordagem terapêutica.

### 3. Isolamento Profissional

Terapeutas trabalham em silos. Não há plataforma que facilite encaminhamentos entre colegas, supervisão clínica estruturada ou rede de colaboração profissional.

### 4. Falta de Educação em Gestão

A formação em psicologia, psicanálise e psiquiatria é excelente clinicamente, mas praticamente nula em gestão. O profissional não sabe precificar, não sabe lidar com inadimplência, não conhece suas obrigações fiscais e de LGPD.

### 5. Experiência do Paciente Negligenciada

O paciente é tratado como destinatário passivo do serviço. Não existe ferramenta que engaje o paciente entre sessões, acompanhe seu humor, envie tarefas terapêuticas ou registre seu progresso de forma visual.

04

## O Mercado e seus Concorrentes

O mercado brasileiro de software para saúde mental está em crescimento acelerado, mas ainda dominado por soluções parciais. Os principais players cobrem bem o básico administrativo, porém falham na profundidade clínica e na experiência do usuário.

Player | Pontos Fortes | Lacunas Críticas
--- | --- | ---
PsicoManager | Prontuário, agendamento sólido | UX datada, sem app do paciente, sem microlearning
Clínica Ágil | Interface moderna, financeiro | Sem escalas clínicas, sem rede entre profissionais
Amplimed | Multi-especialidade, robusto | Complexo demais para terapeuta solo, custo elevado
Nuvem Psicologia | Foco em psicólogos, simples | Funcionalidades limitadas, sem crescimento de produto
Google Agenda + Planilha | Gratuito, familiar | Não é um produto — é um remendo

Nossa plataforma compete em uma categoria nova: ecossistema terapêutico integrado. Enquanto os concorrentes vendem software de gestão, vendemos crescimento profissional, conexão clínica e educação continuada — com a gestão como consequência natural.
05

## Lacunas de Mercado Identificadas

A análise competitiva revelou oportunidades concretas que nenhum player atual preenche de forma satisfatória. São estas lacunas que definem nossa vantagem estratégica.

### Lacuna 1 — Acompanhamento de Progresso Clínico Visual

Nenhum sistema entrega um painel visual que mostre a evolução do paciente sessão a sessão com métricas e gráficos. Nossa tabela `agenda_eventos` já registra cada sessão com status, modalidade e preço — base para dashboards longitudinais.

### Lacuna 2 — Ferramentas para o Paciente entre Sessões

Um módulo do paciente com diário de humor, tarefas terapêuticas e check-ins automáticos é praticamente inexistente no Brasil. A tabela `patients` já prevê `user_id`, permitindo que pacientes tenham login nativo na plataforma.

### Lacuna 3 — Escalas Psicológicas Integradas

PHQ-9, GAD-7, BDI e outras escalas não estão integradas com envio ao paciente, correção automática e gráfico de evolução temporal. O sistema de `determined_commitments` com campos dinâmicos (`determined_commitment_fields`) forma a base técnica para isso.

### Lacuna 4 — Rede de Encaminhamentos

Terapeutas frequentemente precisam encaminhar pacientes para colegas. O campo `patients.encaminhado_por` e o status `'Encaminhado'` já existem na tabela de pacientes. A estrutura de rede é o passo seguinte.

### Lacuna 5 — Módulo de Supervisão Clínica

Nenhum sistema tem módulo específico para supervisores. No nosso schema: `plans.target = 'supervisor'`, `tenants.kind = 'supervisor'` e `plans.max_supervisees` (limite de supervisionados) já estão modelados nativamente.

### Lacuna 6 — Educação em Gestão para a Área

A plataforma de microlearning — produto 2 — é um diferencial único. Conteúdos específicos sobre gestão de clínica, precificação, LGPD aplicada à psicologia e finanças do autônomo.

### Lacuna 7 — IA de Suporte Clínico

Sugestão de bibliografias por apresentação clínica e rascunho de evoluções por voz são funcionalidades com altíssimo valor e quase inexistentes. O campo `agenda_eventos.extra_fields` (jsonb) e os campos de notas estruturadas já preparam o terreno para ingestão de IA.

06

## Arquitetura do Produto

A plataforma é composta por dois produtos complementares que compartilham a mesma base de usuários, infraestrutura Supabase e identidade de marca:

Produto 1
Sistema de Gestão Clínica
Agendamento com recorrência, prontuário, financeiro com Pix/Asaas, multi-papel, escalas clínicas, módulo do paciente, rede de profissionais e supervisão clínica.
Produto 2
Plataforma de Microlearning
Trilhas de microlearning por especialidade, carrossel de slides, quiz, vídeo, banners no sistema e assinatura independente ou inclusa no plano.

### Stack Tecnológica Real

🗄
Supabase (Backend)

PostgreSQL 17.6, Auth, Storage, RLS, Realtime. Hospeda 60+ tabelas do schema público.

🔐
Auth Supabase

JWT com refresh token. `auth.uid()` em todas as RLS policies. Login por e-mail e Google (Apple futuro).

💳
Asaas (Pagamentos)

Integração via webhooks para Pix, boleto. Tabela `payment_settings` guarda configurações por owner.

📬
Notificações

Sistema completo com `notification_queue`, canais (email, WhatsApp, SMS), opt-in por paciente e cleanup automático.

### Como os Dois Produtos se Integram

- O mesmo login (`auth.users` → `profiles`) acessa os dois produtos.
- Banners rotativos dentro do sistema de gestão exibem conteúdos do microlearning — tabela `login_carousel_slides` já existe no schema.
- O modelo de planos (`plans`) pode incluir acesso ao microlearning como benefício por meio de `plan_features`.
- O sistema de módulos (`modules`, `module_features`, `tenant_modules`) controla quais funcionalidades cada tenant tem acesso.

07

## O Sistema Multi-Papel e Multi-Tenant

Um dos diferenciais arquiteturais mais importantes da plataforma é o sistema de multi-papel por usuário combinado com multi-tenant. Na maioria dos concorrentes, um usuário é ou terapeuta ou paciente. Em nossa plataforma, um único usuário pode exercer múltiplos papéis simultaneamente, refletindo a realidade clínica.

Insight central: O terapeuta também faz análise pessoal. Logo, ele é simultaneamente profissional de saúde mental e paciente de outro profissional. O sistema precisa respeitar e suportar essa dualidade de forma natural e sem fricção.

### Os Papéis do Sistema

PAPEL 01
Paciente

Agenda sessões, acessa histórico, responde escalas, usa o diário entre sessões e visualiza tarefas.

profiles.account_type = 'patient'
PAPEL 02
Terapeuta

Gerencia agenda e pacientes, registra prontuário, aplica escalas, emite cobranças e acessa relatórios.

profiles.account_type = 'therapist'
PAPEL 03
Clínica

Gerencia múltiplos terapeutas, controla agenda compartilhada, realiza repasse financeiro e métricas.

profiles.account_type = 'clinic'
PAPEL 04
Supervisor

Acompanha casos de supervisionados com acesso controlado. Plano com limite de supervisionados via `plans.max_supervisees`.

plans.target = 'supervisor'

### Tipos de Tenant — `tenants.kind`

Cada workspace (tenant) tem um tipo imutável definido na criação. Isso determina o comportamento, permissões e funcionalidades disponíveis:

therapist
Terapeuta Solo

Terapeuta autônomo que gerencia sua própria prática. Um tenant por profissional.

clinic_coworking
Clínica Coworking

Múltiplos terapeutas com espaço compartilhado, agenda independente por profissional.

clinic_reception
Clínica com Recepção

Clínica com recepcionista centralizada gerenciando agendamento de múltiplos profissionais.

clinic_full
Clínica Completa

Gestão completa: recepção, financeiro centralizado, repasse, relatórios gerenciais.

supervisor
Workspace de Supervisão

Ambiente dedicado à supervisão clínica. Supervisores acompanham casos de supervisionados.

### Regras de Transição entre Papéis

- Todo usuário começa com `profiles.account_type = 'free'` — sem perfil definido ainda.
- O usuário escolhe se é paciente (`'patient'`) ou terapeuta (`'therapist'`) — o campo é imutável após a escolha.
- Um Terapeuta pode criar ou se vincular a uma Clínica via `tenant_members` com `role = 'tenant_admin'` ou `'therapist'`.
- A tabela `tenant_members` controla quem pertence a qual tenant e com qual papel (admin, terapeuta, recepcionista).
- Um usuário Terapeuta pode simultaneamente ser Paciente de outro terapeuta — os dados são segregados por `tenant_id` e `owner_id`.
- A troca de contexto entre papéis na interface não contamina dados — RLS garante isolamento total no banco.
- Papéis globais de plataforma (ex: editor de microlearning) ficam em `profiles.platform_roles[]`, independentes de tenant.

08

## Módulos do Sistema de Gestão

M1
Autenticação e Multi-Papel

Fundação de toda a plataforma. Usa `auth.users` (Supabase Auth) + `profiles` para dados do usuário. O `profiles.role` controla acesso administrativo ao sistema SaaS; `profiles.account_type` controla o tipo de conta do usuário.

- Login com e-mail, Google e futuramente Apple
- JWT com `auth.uid()` usado em todas as RLS policies
- Middleware de permissão por papel em todas as rotas
- Auditoria via `support_sessions` — admins SaaS podem acessar tenants com token temporário
- `profiles.platform_roles[]` para permissões globais independentes de tenant

M2
Agendamento com Recorrência

Sistema de agenda completo com suporte a sessões recorrentes, exceções, bloqueios e agendamento online pelo paciente. Núcleo operacional do produto.

- `agenda_regras_semanais` — disponibilidade semanal do terapeuta (dia, horário, modalidade)
- `agenda_eventos` — cada sessão individual (status: agendado, realizado, faltou, cancelado, remarcar)
- `recurrence_rules` — regras de recorrência (weekly, biweekly, monthly, yearly, custom_weekdays)
- `recurrence_exceptions` — exceções pontuais: cancelamento, remarcação, feriado
- `agenda_excecoes` — bloqueios e horários extras do terapeuta
- `agendador_solicitacoes` — agendamento online pelos pacientes com aprovação do terapeuta
- Conflito de horário validado pela função `cancelar_eventos_serie()`

M3
Cadastro de Pacientes

Cadastro completo do paciente com dados pessoais, endereço, responsável, notas clínicas e vínculo com terapeuta. Suporta escopo clínica (`patient_scope = 'clinic'`) e terapeuta (`patient_scope = 'therapist'`).

- Tabela `patients` com 40+ campos: dados pessoais, endereço completo, responsável, CPF/RG
- Status do paciente: Ativo, Inativo, Alta, Encaminhado, Arquivado
- `patient_invites` — link de auto-cadastro com token, expiração e limite de usos
- `patient_intake_requests` — ficha de anamnese via link público (função `create_patient_intake_request_v2`)
- `patient_tags` e `patient_groups` — organização e segmentação de pacientes
- `patient_discounts` — descontos por paciente com data de vigência
- Suporte a responsável: campos de nome, telefone, CPF e cobrança no responsável

M4
Financeiro

Controle financeiro completo com receitas, despesas, parcelamentos, repasse para clínica e integração com gateway de pagamento.

- `financial_records` — registro financeiro (receita/despesa) com status: pending, paid, partial, overdue, cancelled, refunded
- Criação automática de cobrança quando sessão é marcada como realizada (trigger `auto_create_financial_record_from_session`)
- `financial_categories` — categorias personalizáveis de receita e despesa
- `billing_contracts` — contratos de cobrança por paciente (preço, frequência, método)
- `therapist_payouts` e `therapist_payout_records` — repasse financeiro para terapeutas em clínicas
- `payment_settings` — configuração de formas de pagamento aceitas (Pix, depósito, dinheiro, cartão, convênio)
- `insurance_plans` e `insurance_plan_services` — gestão de convênios e planos de saúde
- Campo `clinic_fee_pct` e `clinic_fee_amount` para split entre clínica e terapeuta

M5
Notificações

Sistema de notificações multi-canal com fila, agendamento, opt-in por canal e limpeza automática de mensagens antigas.

- `notification_queue` — fila de notificações (pendente → processando → enviado)
- Canais: email, WhatsApp, SMS — opt-in individual por paciente em `notification_preferences`
- `notification_templates` e `email_templates_tenant` — templates personalizáveis por tenant
- Cancelamento automático de notificações quando sessão é cancelada ou paciente faz opt-out
- Cleanup automático de mensagens enviadas/canceladas após 90 dias

M6
Serviços e Precificação

Catálogo de serviços por terapeuta/clínica com vínculo à recorrência e precificação por sessão.

- `services` — catálogo de serviços (consulta, avaliação, retorno etc.) por owner/tenant
- `recurrence_rule_services` — serviços vinculados a uma recorrência com quantidade, preço unitário e desconto
- Prioridade de preço na sessão: `recurrence_rule_services` > `recurrence_rules.price` > `agenda_eventos.price`
- `professional_pricing` — tabela legada, substituída por `services`

09

## Plataforma de Microlearning

O produto de microlearning é o motor de aquisição orgânica da plataforma. Profissionais chegam pelo conteúdo e descobrem o sistema de gestão. É a estratégia que transforma educação em produto.

Insight-chave: o melhor canal de aquisição de um terapeuta é outro terapeuta. O microlearning cria o contexto social onde isso acontece naturalmente.

### Trilhas de Conteúdo por Abordagem

Gestão de Clínica para Psicólogos (TCC, Gestalt, Humanista)

- Como precificar sua sessão sem culpa e com consciência de mercado
- LGPD na prática clínica: o que você precisa fazer hoje
- Gestão de inadimplência sem comprometer o vínculo terapêutico
- Quando e como reajustar o valor da sessão
- Organização financeira para o profissional autônomo

Gestão de Clínica para Psicanalistas

- Frequência de sessões e modelo de cobrança na psicanálise
- Documentação mínima necessária na clínica psicanalítica
- Como estruturar uma clínica particular sendo psicanalista
- Supervisão e análise pessoal: como e onde buscar

Gestão de Clínica para Psiquiatras

- Receituário, laudos e documentação clínica
- Credenciamento e faturamento com planos de saúde
- Integração com outros profissionais de saúde mental
- Como montar um consultório particular de psiquiatria

Para Clínicas Multiprofissionais

- Como estruturar o repasse financeiro entre profissionais
- Gestão de agenda compartilhada sem conflitos
- Contrato de parceria entre clínica e profissional

10

## Modelo de Negócio e Monetização

O modelo de negócio é SaaS com camada freemium. Os planos são gerenciados pela tabela `plans` com preços em `plan_prices` e vitrine pública em `plan_public`. Cada plano tem um `target` que define para qual tipo de conta ele é válido.

### Estrutura de Planos

Gratuito
Paciente / Terapeuta iniciante
target: patient / therapist

- Até 10 pacientes
- Agendamento básico
- Conteúdo introdutório grátis

Profissional
Terapeuta autônomo
target: therapist

- Pacientes ilimitados
- Prontuário completo
- Financeiro + escalas
- Todas as trilhas de conteúdo

Clínica
Múltiplos terapeutas
target: clinic

- Multi-terapeuta via `tenant_members`
- Repasse financeiro (`therapist_payouts`)
- Agenda compartilhada
- Acesso para toda a equipe

Supervisor
Psicanalistas / supervisores
target: supervisor

- Limite de supervisionados (`max_supervisees`)
- Acesso controlado a casos
- Workspace próprio de supervisão

Conteúdo
Estudante / Paciente curioso
target: patient

- Acesso completo às trilhas
- Sem sistema de gestão
- Assinatura mensal independente

### Infraestrutura de Assinaturas

- Tabela `subscriptions` — assinatura ativa do usuário ou tenant (XOR: ou `user_id` ou `tenant_id`, nunca ambos)
- Status de assinatura: pending, active, past_due, suspended, cancelled, expired
- Tabela `subscription_intents_personal` e `subscription_intents_tenant` — intenção de pagamento antes da ativação
- Função `activate_subscription_from_intent()` — ativa assinatura após confirmação de pagamento
- Função `change_subscription_plan()` — muda plano com log em `subscription_events`
- `entitlements_invalidation` — cache de entitlements é invalidado quando o plano muda
- `plan_prices` — histórico de preços por plano com intervalos (month/year)

11

## Modelo de Dados — Schema Real

Documentação minuciosa das tabelas principais do schema `public` do banco de dados PostgreSQL 17.6 via Supabase. Este capítulo é a referência autoritativa para qualquer decisão de desenvolvimento.

Convenção: Todas as tabelas usam `uuid` como PK via `gen_random_uuid()`. Campos `tenant_id` e `owner_id` estão presentes em todas as tabelas de negócio para garantir isolamento multi-tenant. O campo `deleted_at` implementa soft-delete onde aplicável.

### Tabela: `profiles`

Extensão do `auth.users` do Supabase. Criado automaticamente no signup. Contém dados públicos do usuário e configurações de perfil.

public.profiles 1 registro por auth.users
idPK FK→auth.users uuid Mesmo ID do auth.users
role text Papel no sistema SaaS: saas_admin | tenant_member | portal_user | patient
account_type text Tipo de conta: free | patient | therapist | clinic. Imutável após definição.
platform_roles text[]Papéis globais de plataforma (ex: editor de microlearning). Atribuído pelo saas_admin.
full_name text Nome completo do usuário
avatar_url text URL pública no Supabase Storage
phone text WhatsApp no formato (99) 99999-9999
bio text Breve apresentação pública (máx 300 chars no front)
language text Default: 'pt-BR'
timezone text Default: 'America/Sao_Paulo'
social_custom jsonb Redes sociais adicionais: [{name, url}]

### Tabela: `tenants`

Representa um workspace isolado — pode ser um terapeuta solo, uma clínica ou um workspace de supervisão. O `kind` é imutável após criação.

public.tenants Workspaces isolados multi-tenant
idPK uuid ID único do tenant
name text Nome do workspace (clínica ou nome do terapeuta)
kindNN text therapist | clinic_coworking | clinic_reception | clinic_full | supervisor | clinic (legado) | saas (legado)
created_at timestamptz Data de criação

### Tabela: `tenant_members`

Vincula usuários a tenants com um papel específico. Um usuário pode pertencer a múltiplos tenants (ex: terapeuta em duas clínicas).

public.tenant_members Membros por workspace
tenant_idFK→tenants uuid Workspace ao qual pertence
user_idFK→profiles uuid Usuário membro
role text Papel no tenant: tenant_admin | therapist | receptionist | viewer
status text active | invited | suspended

### Tabela: `patients`

Registro completo do paciente. O campo `patient_scope` define se o paciente pertence à clínica ou a um terapeuta específico. Quando `patient_scope = 'therapist'`, o campo `therapist_member_id` é obrigatório.

public.patients ~40 campos por paciente
idPK uuid ID único do paciente
tenant_idFK→tenants NN uuid Workspace ao qual pertence
owner_idFK→profiles uuid Quem criou/é responsável pelo paciente
responsible_member_idNN uuid Membro responsável pelo paciente no tenant
therapist_member_id uuid Terapeuta vinculado (obrigatório quando patient_scope = 'therapist')
user_idFK→profiles uuid Conta de login do paciente (quando é usuário nativo)
patient_scope text'clinic' | 'therapist' — define a quem o paciente pertence
status text Ativo | Inativo | Alta | Encaminhado | Arquivado
nome_completoNN text Nome completo do paciente
cpf text CPF sem formatação (validado por regex ^\d{11}$)
data_nascimento date Data de nascimento
cobranca_no_responsavel boolean Cobrar no responsável em vez do paciente
notas_internas text Notas privadas do terapeuta (não visíveis ao paciente)

### Tabela: `agenda_eventos`

Cada sessão individual na agenda. Gerada manualmente ou automaticamente por regras de recorrência. O campo `billed` controla se já foi gerada cobrança.

public.agenda_eventos Sessões e bloqueios de agenda
idPK uuid ID único do evento
tenant_idNN uuid Workspace
owner_idNN uuid Terapeuta dono do evento
patient_idFK→patients uuid Paciente da sessão (null em bloqueios)
tipo tipo_evento_agenda'sessao' | 'bloqueio'
status status_evento_agenda agendado | realizado | faltou | cancelado | remarcar
inicio_emNN timestamptz Início da sessão (com timezone)
fim_emNN timestamptz Fim da sessão — constraint: fim_em > inicio_em
modalidade text'presencial' | 'online' — default: 'presencial'
recurrence_idFK→recurrence_rules uuid Regra de recorrência que gerou este evento
price numeric(10,2)Valor da sessão em BRL
billed boolean true = cobrança já foi gerada para esta sessão
extra_fields jsonb Campos customizáveis por abordagem/tenant
insurance_plan_id uuid Plano de saúde da sessão (quando convênio)

### Tabela: `financial_records`

Registro financeiro central. Gerado automaticamente por trigger quando sessão é marcada como realizada. Suporta parcelamento, split de comissão e múltiplos status.

public.financial_records Receitas e despesas
idPK uuid ID único
owner_idNN uuid Terapeuta dono do registro
tenant_id uuid Clínica (quando em contexto de clínica)
type financial_record_type'receita' | 'despesa'
amountNN numeric(10,2)Valor bruto
discount_amount numeric(10,2)Desconto aplicado
final_amount numeric(10,2)Valor final após desconto
clinic_fee_pct numeric(5,2)Percentual da clínica (0–100)
clinic_fee_amount numeric(10,2)Valor absoluto da taxa da clínica
net_amount numeric(10,2)GENERATED: amount - clinic_fee_amount (valor líquido do terapeuta)
statusNN text pending | paid | partial | overdue | cancelled | refunded
agenda_evento_idFK→agenda_eventos uuid Sessão que originou a cobrança
installments smallint Número de parcelas (default: 1)
installment_group uuid UUID que agrupa parcelas de um mesmo parcelamento
deleted_at timestamptz Soft-delete — null = registro ativo

### Tabela: `recurrence_rules`

Regras de recorrência de sessões. Define o padrão de repetição (semanal, quinzenal etc.) com data de início e fim opcional. Gera os `agenda_eventos` automaticamente.

public.recurrence_rules Padrões de sessões recorrentes
type recurrence_type weekly | biweekly | monthly | yearly | custom_weekdays
interval smallint Intervalo entre ocorrências (ex: 2 para quinzenal)
weekdays smallint[]Dias da semana (0=Dom, 1=Seg...6=Sab) para custom_weekdays
start_time / end_time time Horário de início e fim da sessão
duration_min smallint Duração em minutos (default: 50)
open_ended boolean true = sem data de fim definida
status text ativo | pausado | cancelado
price numeric(10,2)Preço padrão da sessão desta recorrência
modalidade text'presencial' | 'online'
insurance_plan_id uuid Convênio vinculado a esta recorrência

### Tabelas de Suporte — Referência Rápida

Tabela | Finalidade | Observação
--- | --- | ---
`subscriptions` | Assinatura ativa do usuário ou tenant | XOR: user_id OU tenant_id
`plans` | Planos disponíveis com preço e target | target: patient/therapist/clinic/supervisor
`plan_features` | Features incluídas em cada plano | Vincula plans ↔ features
`features` | Catálogo de funcionalidades | Chave técnica imutável
`modules` + `tenant_modules` | Módulos disponíveis por tenant | Controle granular de acesso
`notification_queue` | Fila de notificações multi-canal | Email, WhatsApp, SMS
`patient_invites` | Links de auto-cadastro para pacientes | Token + expiração + limite de usos
`patient_intake_requests` | Fichas de anamnese via link público | Aprovadas pelo terapeuta
`billing_contracts` | Contratos de cobrança por paciente | Preço, frequência, método
`services` | Catálogo de serviços do terapeuta | Substitui professional_pricing
`insurance_plans` | Convênios e planos de saúde | Vinculado a sessões e recorrências
`therapist_payouts` | Repasse financeiro do terapeuta | Período, sessões, valor líquido
`support_sessions` | Sessões de suporte do saas_admin | Token temporário com TTL (1–120 min)
`user_settings` | Preferências de UI por usuário | Theme, layout, modo de menu
`feriados` | Feriados nacionais/locais | Integração com bloqueios de agenda
`global_notices` | Avisos da plataforma para usuários | Com dismissal individual
`saas_docs` + `saas_faq` | Documentação e FAQ da plataforma | Com votos de utilidade

12

## Enums e Tipos — Referência Completa

O schema define enums PostgreSQL para todos os campos com valores discretos. Isso garante integridade de dados no nível do banco — sem strings inválidas passando pelo sistema.

### Enums do Schema `public`

status_evento_agenda public
agendado realizado faltou cancelado remarcar
recurrence_type public
weekly biweekly monthly yearly custom_weekdays
tipo_evento_agenda public
sessao bloqueio
recurrence_exception_type public
cancel_session reschedule_session patient_missed therapist_canceled holiday_block
financial_record_type public
receita despesa
status_agenda_serie public
ativo pausado cancelado
tipo_excecao_agenda public
bloqueio horario_extra
status_excecao_agenda public
pendente ativo arquivado
determined_field_type public
text textarea number date select boolean
commitment_log_source public
manual auto

### Constraints de Texto — Equivalentes a Enums

Alguns campos usam `CHECK` constraints em vez de enums PostgreSQL. São igualmente seguros no banco:

Tabela.Coluna | Valores Permitidos
--- | ---
`profiles.role` | saas_admin | tenant_member | portal_user | patient
`profiles.account_type` | free | patient | therapist | clinic
`tenants.kind` | therapist | clinic_coworking | clinic_reception | clinic_full | clinic | saas | supervisor
`patients.status` | Ativo | Inativo | Alta | Encaminhado | Arquivado
`patients.patient_scope` | clinic | therapist
`financial_records.status` | pending | paid | partial | overdue | cancelled | refunded
`subscriptions.status` | pending | active | past_due | suspended | cancelled | expired
`subscriptions.interval` | month | year
`plans.target` | patient | therapist | clinic | supervisor
`therapist_payouts.status` | pending | paid | cancelled
`agenda_eventos.modalidade` | presencial | online
`user_settings.theme_mode` | light | dark
`user_settings.layout_variant` | classic | rail

13

## Funções RPC — Lógica de Negócio no Banco

O sistema usa extensivamente funções PostgreSQL SECURITY DEFINER para encapsular lógica de negócio complexa e garantir atomicidade. Todas são chamadas via `supabase.rpc()` no frontend.

Atenção arquitetural: Funções SECURITY DEFINER executam com as permissões do dono da função (supabase_admin), não do usuário chamador. Isso permite operações que burlariam o RLS de forma controlada. Use com responsabilidade.

### Funções Críticas de Negócio

Função | O que faz | Observação crítica
--- | --- | ---
`create_clinic_tenant(p_name)` | Cria um tenant do tipo 'clinic' e já vincula o usuário atual como tenant_admin | Atômico: cria tenant + tenant_members em uma transação
`activate_subscription_from_intent(p_intent_id)` | Ativa assinatura após pagamento confirmado (intent.status = 'paid') | Valida target (clinic/therapist/supervisor). Suporta todos os 3 tipos.
`change_subscription_plan(p_subscription_id, p_new_plan_id)` | Muda o plano de uma assinatura ativa com log em subscription_events | Valida compatibilidade de target (clinic ≠ therapist)
`cancel_subscription(p_subscription_id)` | Cancela assinatura e invalida cache de entitlements | Logs em subscription_events, invalida entitlements_invalidation
`create_financial_record_for_session(...)` | Cria cobrança para uma sessão, com idempotência (não duplica) | Marca billed=true na agenda_eventos após criar
`auto_create_financial_record_from_session()` | Trigger: cria financial_record automaticamente quando sessão é marcada como realizada | Prioridade de preço: recurrence_rule_services > recurrence_rules.price > agenda_eventos.price
`create_patient_intake_request_v2(p_token, p_payload)` | Cria ficha de anamnese via link público com validação do token | Valida token, expiração, limite de usos e processa 30+ campos do paciente
`cancelar_eventos_serie(p_serie_id, p_a_partir_de)` | Cancela todos os eventos futuros de uma série recorrente | Não cancela eventos já realizados
`cancel_recurrence_from(p_recurrence_id, p_from_date)` | Encerra uma recorrência a partir de uma data, ajustando end_date | Se from_date <= start_date, cancela a recorrência inteira
`create_therapist_payout(p_tenant_id, p_therapist_id, p_period_start, p_period_end)` | Calcula e registra repasse financeiro para terapeuta em uma clínica | Agrega sessões realizadas no período com cálculo de comissão
`create_support_session(p_tenant_id, p_ttl_minutes)` | Cria sessão temporária de acesso ao suporte (saas_admin only) | TTL: 1–120 minutos. Valida role = 'saas_admin'
`cancel_patient_pending_notifications(patient_id, channel, evento_id)` | Cancela notificações pendentes de um paciente por canal ou evento | Chamada por trigger quando sessão é cancelada ou paciente faz opt-out
`can_delete_patient(p_patient_id)` | Verifica se é seguro deletar um paciente (sem eventos, recorrências ou contratos) | Retorna boolean — chame antes de qualquer DELETE em patients

### Triggers Automáticos

- Sessão realizada → cobrança criada: Trigger `auto_create_financial_record_from_session` dispara quando `agenda_eventos.status` muda para `'realizado'`. Cria `financial_record` com status `'pending'` e vencimento 7 dias após a sessão.
- Sessão cancelada → notificações canceladas: Trigger `cancel_notifications_on_session_cancel` cancela todas as notificações pendentes relacionadas à sessão.
- Opt-out do paciente → notificações canceladas: Trigger `cancel_notifications_on_opt_out` cancela notificações do canal específico quando paciente faz opt-out.

14

## Estratégia de Fases de Desenvolvimento

O desenvolvimento é organizado em quatro fases estratégicas. A infraestrutura de banco de dados (tenants, profiles, agenda, financeiro, notificações) já está substancialmente implementada — o foco atual é na experiência de produto sobre ela.

FASE 1 MVP e Validação
Meses 1–3

- Sistema multi-papel funcional e sólido — `profiles`, `tenants`, `tenant_members` implementados
- Agendamento completo com recorrência e lembretes via e-mail e WhatsApp
- Cadastro de pacientes com vínculo terapeuta-paciente e ficha de anamnese online
- Prontuário com anotações de sessão em `agenda_eventos.extra_fields`
- Financeiro básico: cobrança automática por trigger, integração Asaas (Pix)
- LGPD implementada: criptografia, consentimento, auditoria via `support_sessions`
- Beta fechado com 10–20 terapeutas reais
- Landing page de microlearning com 1 trilha inicial

FASE 2 Diferenciação Clínica
Meses 4–8

- Escalas psicológicas integradas (PHQ-9, GAD-7, BDI) usando `determined_commitments` com campos dinâmicos
- Dashboard de evolução do paciente com gráficos longitudinais
- Módulo do paciente: diário de humor, tarefas, visualização de agenda (PWA)
- Relatórios e laudos com template e exportação em PDF
- Módulo de Clínica: tenant kind `clinic_*`, repasse financeiro (`therapist_payouts`)
- Prontuário completo com campos estruturados por abordagem via `extra_fields`
- Expansão do microlearning: 3–5 trilhas completas
- Meta: 100 terapeutas pagantes, churn abaixo de 5%/mês

FASE 3 Rede e Crescimento
Meses 9–18

- Diretório de terapeutas: pacientes encontram profissionais usando `profiles` públicos
- Rede de encaminhamentos estruturada — status `'Encaminhado'` em `patients` com rastreio
- Módulo de supervisão clínica — tenant kind `'supervisor'` + plano `target='supervisor'` + `max_supervisees`
- Programa de indicação com benefícios para terapeutas indicadores
- Expansão para clínicas multiprofissionais — kind `clinic_full`
- Meta: 1.000 terapeutas ativos, 20+ clínicas, efeito de rede ativado

FASE 4 Inteligência e Escala
18+ meses

- IA de suporte clínico: sugestão bibliográfica por CID, rascunho de evolução por voz — ingerindo `agenda_eventos.extra_fields`
- Alertas de risco baseados em padrões comportamentais do paciente
- Integração com planos de saúde: tabelas `insurance_plans`, `insurance_plan_services` já existem no schema
- API aberta para parceiros — `profiles.platform_roles` já suporta roles de API
- Expansão internacional para mercados lusófonos

15

## Cronograma do MVP (3 Meses)

Cronograma desenhado para um time com frontend e backend separados, priorizando entregas que gerem valor real para o primeiro usuário no prazo de 2 a 3 meses. A infraestrutura de banco já existe — o trabalho é de produto, UX e integração.

MÊS 1 Fundação Sólida
Frontend
Backend
Entrega
Sem
1–2
Telas de login, cadastro, seleção de account_type, navegação base por papel
Auth Supabase, profiles criado no signup, middleware de permissão por role e account_type
Usuário cria conta, define se é terapeuta ou paciente e navega no ambiente correto
Sem
3–4
Dashboard por papel, perfil do usuário, criação de tenant (clínica/solo)
RPC create_clinic_tenant, tenant_members, RLS policies por tenant_id
Terapeuta cria workspace, convida colegas — multi-tenant funcionando
MÊS 2 Core do Produto
Frontend
Backend
Entrega
Sem
1–2
Tela de agenda do terapeuta, configuração de disponibilidade (agenda_regras_semanais)
CRUD de agenda_regras_semanais, recurrence_rules, geração de agenda_eventos
Terapeuta configura agenda semanal com recorrência
Sem
3–4
Cadastro de pacientes, ficha de anamnese, link de auto-cadastro
CRUD patients, patient_invites, create_patient_intake_request_v2, notificações de agendamento
Paciente agenda sessão via link, terapeuta recebe notificação
MÊS 3 Fechar o Ciclo e Lançar
Frontend
Backend
Entrega
Sem
1–2
Tela financeira, histórico de sessões, status de pagamento (financial_records)
Integração Asaas (Pix), trigger auto_create_financial_record_from_session, webhooks
Ciclo financeiro completo: sessão realizada → cobrança automática → confirmação Pix
Sem
3–4
Anotações de sessão em extra_fields, UX refinado, landing page de microlearning
Revisão de segurança, RLS audit via support_sessions, ambiente de produção, monitoramento
Beta com 10–20 terapeutas reais
16

## Riscos e Mitigações

RLS mal configurada vazando dados entre tenants

O risco mais crítico do sistema. Toda query deve filtrar por `tenant_id = auth.uid()` ou similar. Testar com usuário de tenant B tentando acessar dados do tenant A. Usar `support_sessions` para auditoria. Code review obrigatório em toda RLS policy nova.

Impacto Alto Prob. Médio
Trigger financeiro falhando silenciosamente

O trigger `auto_create_financial_record_from_session` usa EXCEPTION WHEN OTHERS com RAISE WARNING — nunca bloqueia a agenda. Monitorar logs do Supabase para warnings. Implementar painel de sessões `billed=false` com status `'realizado'` como alerta de cobrança perdida.

Impacto Médio Prob. Médio
Integração de pagamento subestimada

Reservar pelo menos 2 semanas dedicadas para a integração com Asaas. Testar todos os fluxos de webhook, falha de pagamento e conciliação. A tabela `payment_settings` já existe — focar na lógica de webhook e mapeamento de status.

Impacto Médio Prob. Alto
Dados sensíveis sem criptografia

Implementar criptografia em repouso para prontuários e anotações desde o início. O campo `notas_internas` dos pacientes e `extra_fields` das sessões são os mais críticos. Usar Supabase Vault para secrets. Tratar como requisito não-negociável.

Impacto Alto Prob. Baixo
Complexidade do sistema multi-tenant na UI

O schema suporta todos os tipos de tenant, mas a UI precisa ser simples. Terapeuta solo não deve ver opções de clínica. Usar `tenants.kind` para esconder/mostrar funcionalidades. Criar versão simplificada do onboarding para `kind='therapist'`.

Impacto Médio Prob. Alto
Adoção lenta pelos terapeutas

Beta fechado com 10–20 terapeutas antes do lançamento público. Onboarding em 5 minutos. Plano gratuito generoso. Microlearning como canal de aquisição orgânica. Usar `global_notices` para comunicação de novidades in-app.

Impacto Alto Prob. Médio
Escopo crescente comprometendo o prazo

O schema já tem muitas funcionalidades implementadas (convênios, repasse, supervisão). Resistir à tentação de ativar tudo no MVP. Usar o sistema de `modules` e `tenant_modules` para liberar features gradualmente por tenant, sem reescrever código.

Impacto Alto Prob. Alto
17

## Estratégia de Adoção e Crescimento

### O Funil de Aquisição

📢
Topo do Funil — Conteúdo

Microlearning gratuito atrai terapeutas buscando aprender gestão. SEO em conteúdo de blog e trilhas. Presença no Instagram e LinkedIn com dicas de gestão clínica.

🔬
Meio do Funil — Experimentação

Plano gratuito com limite generoso (`account_type = 'free'`). Onboarding em 5 minutos. O terapeuta experimenta sem compromisso e vê valor antes de pagar.

💳
Fundo do Funil — Conversão

Quando ultrapassa o limite do plano gratuito, a conversão é natural. O sistema de `subscription_intents` facilita o checkout sem atrito.

🔒
Retenção — Profundidade

Escalas clínicas, prontuário acumulado em `agenda_eventos` e histórico financeiro criam lock-in legítimo. O custo de sair é alto porque os dados clínicos estão na plataforma.

🌐
Expansão — Indicação

Programa de indicação: terapeuta indica colega, ambos ganham benefício. O sistema de `patient_invites` é o modelo para o sistema de indicação de terapeutas.

### Estratégia de Beta — Os Primeiros 20 Terapeutas

- Recrutar manualmente via LinkedIn, grupos de psicólogos no WhatsApp e Facebook, indicações pessoais.
- Oferecer 6 meses gratuitos no plano Profissional em troca de uso semanal e feedback honesto — configurado via `subscriptions` com `source = 'manual'`.
- Realizar call de 30 minutos com cada beta-tester após 2 semanas de uso.
- Observar onde travam no onboarding, o que tentam fazer e não encontram, o que elogiam espontaneamente.
- Usar esses aprendizados para uma rodada de ajustes de 2 semanas antes do lançamento público.
- Transformar os melhores beta-testers em embaixadores com benefícios permanentes.

18

## Visão de Longo Prazo

Em 5 anos, a plataforma deve ser reconhecida como a infraestrutura da saúde mental brasileira — o ambiente onde profissionais aprendem, trabalham, colaboram e crescem.

Visão de longo prazo: Ser para o terapeuta brasileiro o que a Bloomberg é para o mercado financeiro — a plataforma que nenhum profissional sério consegue imaginar trabalhar sem ela.
🗺
Plataforma de Referência Nacional

O maior diretório de terapeutas do Brasil, com pacientes encontrando profissionais por abordagem, especialidade e localização. Base técnica: `profiles` públicos com bio e redes sociais.

🎓
Educação Continuada Reconhecida

Certificações reconhecidas pelo mercado. Parcerias com conselhos profissionais e universidades. Base: plataforma de microlearning e `platform_roles`.

🤖
IA Clínica de Suporte

Assistente que apoia na documentação, sugestão de intervenções e identificação de padrões de risco — ingerindo `agenda_eventos.extra_fields` e histórico longitudinal.

🌍
Expansão Lusófona

Portugal, Angola e Moçambique como mercados naturais. O schema já prevê `profiles.language` e `profiles.timezone` para internacionalização.

💚
Impacto Social Mensurável

Contribuir para o aumento da qualidade e acessibilidade do cuidado em saúde mental no Brasil, com métricas públicas de impacto.

Este documento é vivo. Deve ser revisado e atualizado a cada fase concluída, incorporando os aprendizados do mercado, as decisões do time e as evoluções do schema de banco de dados.