# Schema Map — AgenciaPsi

Mapa completo do banco de dados PostgreSQL 17, extraído de `schema.sql` (2026-03-23).
**84 tabelas** no schema `public` + tabelas de infraestrutura (auth, storage, realtime).

## Domínios

### Core (11 tabelas)
| Tabela | Descrição |
|--------|-----------|
| `profiles` | Perfil do usuário (role, account_type, full_name, platform_roles) |
| `tenants` | Organizações (clínicas, terapeutas solo, supervisores) |
| `tenant_members` | Vínculo usuário↔tenant com role (tenant_admin, therapist, secretary, etc.) |
| `tenant_invites` | Convites pendentes para ingressar em um tenant |
| `tenant_features` | Overrides de features por tenant (exceções comerciais) |
| `tenant_feature_exceptions_log` | Log de alterações em tenant_features |
| `saas_admins` | Administradores da plataforma |
| `owner_users` | Mapeamento owner_id→user_id para RLS |
| `user_settings` | Configurações pessoais do usuário |
| `company_profiles` | Perfil da empresa/clínica (logo, endereço, etc.) |
| `dev_user_credentials` | Credenciais de teste (apenas dev) |

### Plans & Billing (20 tabelas)
| Tabela | Descrição |
|--------|-----------|
| `plans` | Planos disponíveis (key, target, price_cents, max_supervisees) |
| `plan_prices` | Preços por intervalo (month/year) com versionamento |
| `plan_features` | Vínculo plano↔feature com limites (limits jsonb) |
| `plan_public` | Info pública dos planos (para página de preços) |
| `plan_public_bullets` | Bullets de marketing dos planos |
| `features` | Features do sistema (key, name, descricao) |
| `entitlements_invalidation` | Cache invalidation de entitlements |
| `subscriptions` | Assinaturas ativas (user_id XOR tenant_id) |
| `subscription_events` | Histórico de eventos de assinatura |
| `subscription_intents_personal` | Intenções de assinatura pessoal |
| `subscription_intents_tenant` | Intenções de assinatura de tenant |
| `subscription_intents_legacy` | Intenções legadas |
| `billing_contracts` | Contratos de cobrança |
| `addon_credits` | Créditos de add-ons por tenant |
| `addon_products` | Produtos add-on disponíveis |
| `addon_transactions` | Transações de add-ons |
| `modules` | Módulos do sistema |
| `module_features` | Features por módulo |
| `tenant_modules` | Módulos ativos por tenant |

### Agenda (11 tabelas)
| Tabela | Descrição |
|--------|-----------|
| `agenda_bloqueios` | Bloqueios de horário |
| `agenda_configuracoes` | Configurações da agenda por tenant_member |
| `agenda_eventos` | Eventos da agenda (sessões, bloqueios) |
| `agenda_excecoes` | Exceções na agenda (horários extras, bloqueios pontuais) |
| `agenda_online_slots` | Slots de agendamento online |
| `agenda_regras_semanais` | Regras semanais de disponibilidade |
| `agenda_slots_bloqueados_semanais` | Slots bloqueados na semana |
| `agenda_slots_regras` | Regras de slots |
| `recurrence_rules` | Regras de recorrência de sessões |
| `recurrence_exceptions` | Exceções a recorrências |
| `recurrence_rule_services` | Serviços vinculados a recorrências |

### Agendador Online (2 tabelas)
| Tabela | Descrição |
|--------|-----------|
| `agendador_configuracoes` | Configurações do agendador online público |
| `agendador_solicitacoes` | Solicitações de agendamento recebidas |

### Pacientes (8 tabelas)
| Tabela | Descrição |
|--------|-----------|
| `patients` | Pacientes vinculados a um tenant |
| `patient_groups` | Grupos de pacientes (sistema + customizados) |
| `patient_group_patient` | Vínculo paciente↔grupo |
| `patient_tags` | Tags personalizadas |
| `patient_patient_tag` | Vínculo paciente↔tag |
| `patient_intake_requests` | Solicitações de cadastro (triagem) |
| `patient_invites` | Convites para portal do paciente |
| `patient_discounts` | Descontos por paciente |

### Compromissos Determinados (4 tabelas)
| Tabela | Descrição |
|--------|-----------|
| `determined_commitments` | Tipos de compromisso (sessão, leitura, supervisão, etc.) |
| `determined_commitment_fields` | Campos customizados por tipo de compromisso |
| `commitment_services` | Serviços vinculados a compromissos |
| `commitment_time_logs` | Logs de tempo por compromisso |

### Financeiro (9 tabelas)
| Tabela | Descrição |
|--------|-----------|
| `financial_records` | Lançamentos financeiros (receita/despesa) |
| `financial_categories` | Categorias de lançamento |
| `financial_exceptions` | Exceções financeiras |
| `payment_settings` | Configurações de pagamento por tenant |
| `professional_pricing` | Precificação por profissional |
| `therapist_payouts` | Repasses a terapeutas |
| `therapist_payout_records` | Registros de repasse |
| `services` | Serviços oferecidos |
| `insurance_plans` + `insurance_plan_services` | Convênios e serviços por convênio |

### Notificações (10 tabelas)
| Tabela | Descrição |
|--------|-----------|
| `notification_channels` | Canais de notificação por tenant |
| `notification_logs` | Logs de envio |
| `notification_preferences` | Preferências do paciente (opt-in/out) |
| `notification_queue` | Fila de envio |
| `notification_schedules` | Agendamentos de notificação |
| `notification_templates` | Templates WhatsApp/SMS (default + tenant) |
| `notifications` | Notificações in-app |
| `email_templates_global` | Templates de email globais (plataforma) |
| `email_templates_tenant` | Overrides de templates por tenant |
| `email_layout_config` | Configuração de layout de email |

### SaaS Admin / UI (8 tabelas)
| Tabela | Descrição |
|--------|-----------|
| `saas_docs` | Documentação da plataforma |
| `saas_doc_votos` | Votos em docs |
| `saas_faq` | Categorias de FAQ |
| `saas_faq_itens` | Itens de FAQ |
| `feriados` | Feriados nacionais/regionais |
| `global_notices` | Avisos globais da plataforma |
| `login_carousel_slides` | Slides do carrossel de login |
| `notice_dismissals` | Dismissals de avisos por usuário |

### Suporte (1 tabela)
| Tabela | Descrição |
|--------|-----------|
| `support_sessions` | Sessões de suporte técnico |

---

## Views Principais

| View | Descrição |
|------|-----------|
| `v_tenant_active_subscription` | Subscription ativa por tenant |
| `v_user_active_subscription` | Subscription ativa por user |
| `v_tenant_entitlements` | Features habilitadas por tenant (via plano) |
| `v_tenant_entitlements_full` | Entitlements + limits + plan info |
| `v_tenant_entitlements_json` | Entitlements agregados como JSON |
| `v_user_entitlements` | Features habilitadas por user (via plano) |
| `v_tenant_members_with_profiles` | Membros do tenant com dados do perfil |
| `v_tenant_staff` | Staff do tenant (membros + convites) |
| `v_tenant_people` | Todas as pessoas do tenant |
| `v_plan_active_prices` | Preços ativos dos planos |
| `v_public_pricing` | Preços públicos para página de marketing |
| `v_subscription_health` | Saúde das subscriptions |
| `v_cashflow_projection` | Projeção de fluxo de caixa |
| `v_commitment_totals` | Totais de compromissos |
| `v_patient_groups_with_counts` | Grupos com contagem de pacientes |
| `v_tag_patient_counts` | Tags com contagem de pacientes |
| `subscription_intents` | View unificada de intenções (com INSTEAD OF trigger) |
| `owner_feature_entitlements` | Entitlements por owner |
| `current_tenant_id` | Tenant ativo do usuário corrente |

---

## Funções Críticas

| Função | Tipo | Descrição |
|--------|------|-----------|
| `tenant_has_feature(uuid, text)` | Query | Verifica se tenant tem feature (plano + override) |
| `user_has_feature(uuid, text)` | Query | Verifica se user tem feature via plano pessoal |
| `has_feature(uuid, text)` | Query | Alias genérico |
| `seed_determined_commitments(uuid)` | Seed | Cria 5 tipos de compromisso nativos por tenant |
| `seed_default_patient_groups(uuid)` | Seed | Cria 3 grupos de pacientes padrão |
| `seed_default_financial_categories(uuid)` | Seed | Cria categorias financeiras padrão |
| `subscriptions_validate_scope()` | Trigger | Valida XOR (user_id vs tenant_id) por target |
| `activate_subscription_from_intent(uuid)` | RPC | Ativa subscription a partir de intent |
| `handle_new_user()` | Trigger | Cria profile + tenant pessoal ao cadastrar |
| `ensure_personal_tenant()` | RPC | Garante que o user tem um tenant pessoal |
| `populate_notification_queue()` | Cron | Popula fila de notificações |
| `agendador_slots_disponiveis(text, date)` | RPC | Retorna slots disponíveis para agendamento |

---

## Enums (public schema)

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