# Auditoria Funcional — ScoreOdonto (estado atual + roadmap V1/V2/V3)

> Documento mestre da auto-auditoria (read-only). Gerado a partir do código em 2026-06-15.
> **Nota de nomenclatura:** NÃO existe módulo "Delivery" separado. O antigo "Delivery" foi
> renomeado e é o marketplace de **Profissionais** (propostas clínica→profissional).
> Onde o prompt de benchmark cita "Delivery", leia-se **Profissionais**.

---

## PARTE I — Arquitetura funcional atual

**Papéis (9):** `superadmin, admin, donoclinica, donoconsultorio, dentista, biomedico, protetico, funcionario, paciente`.

**Modelo multi-tenant:** workspaces = linhas em `clinicas` (tipo `clinica` ou `pessoal`); acesso via `vinculos`; isolamento por `clinica_id` (auditado e endurecido em 8 rodadas de segurança). É um diferencial maduro.

### Inventário de telas (40+), por domínio

| Domínio | Telas | Acesso |
|---|---|---|
| Núcleo clínico | Dashboard, Agenda, Pacientes, Ortodontia (OrthoView/PhotoWorkspace/Reports/Annotator), Meus Tratamentos, Lançar GTO | dono/admin/funcionário/dentista/bio/protético |
| Catálogos | Dentistas, Especialidades, Procedimentos, Planos/Convênios | dono/admin/funcionário |
| Financeiro/Comercial | Financeiro, Relatórios, Orçamentos, **Contratos (motor)**, Gestão de Leads | dono/admin/funcionário |
| Marketplace/Recursos | Locação de Salas, **Profissionais (marketplace)**, Diretório Prof., RX/Radiografias, Dispositivos RX | quase todos |
| Tutoria (orto) | Ser Tutor, Painel Tutor, Gestão Tutores | dentista/admin |
| Gestão | Minhas Clínicas, Equipe/Usuários (RBAC), Plugins, Configurações, Notificações | dono/admin |
| Onboarding/Auth | Landing, Login, OnboardingChat, Cadastro Dentista, Criar Clínica, Aguardando Convite, Contato Público | público |
| Superadmin | SuperAdminView (stats/usuários/clínicas/logs/financeiro/notificações), UpdateDb, Sync | superadmin |

### Menu (real)
Visão Geral · Agenda · Pacientes · Lançar GTO · Ortodontia · Financeiro · Relatórios · Orçamentos · Contratos · Gestão de Leads · Meus Tratamentos · Minhas Clínicas · Dentistas · Especialidades · Procedimentos · Planos/Convênios · Equipe/Usuários · Diretório Prof. · Tutoria (3) · Notificações · Plugins · Configurações.

Menu base + filtro `accessByRole` + RBAC por cargo (`funcoes.permissoes/nivel`; array vazio herda o menu do papel). Paciente vê só Tratamentos/Notificações/Config.
Não há: menus contextuais (botão direito), menus dentro de tabelas, breadcrumbs. Navegação é hash-route + cards/modais.

### Backend
≈150 endpoints. Guards: `authGuard / tenantGuard / superadminGuard / adminGuard`. Auditoria via `audit_log`. Tempo real em `/api/ws`.

---

## PARTE II — Gap analysis

### Forte (vantagem competitiva)
- Multitenant/multiempresa (workspaces universais; isolamento por clínica auditado).
- Agenda — anti-overbooking GLOBAL (mesma pessoa não dobra entre clínicas), faltas/reagendar/confirmar/reencaminhar, pendências "a reagendar", presença em tempo real, importar Google.
- Prontuário clínico — odontograma FDI + fotos (avaliação); Ortodontia completa (tratamento/evoluções/documentação fotográfica com anotador/escala + PDFs de tutoria); RX (plugin + laudos); GTO/guias.
- Contratos — motor universal (modelos+variáveis, gerador, assinatura interna com IP/hash, vigência/alertas, 28 modelos de catálogo). Acima da média de mercado.
- Marketplace (salas anti-conflito triplo + **Profissionais** com propostas/diretório).
- RBAC por cargo/nível + realtime.

### Parcial
- Financeiro — só lançamentos receita/despesa + dashboard. Falta contas a pagar/receber estruturado, vencimentos, baixa.
- CRM — só Leads + conversão→paciente. Sem funil/oportunidades/campanhas.
- Convênios — "Planos/Convênios" é catálogo simples; sem regras de cobertura/repasse/glosa.
- Comunicação — notificações in-app/realtime + webhooks WhatsApp na infra; sem disparo de WhatsApp/SMS/e-mail pelo app; sem lembretes automáticos de consulta.
- Relatórios — só `productivity`.
- RH — dentistas/horários/equipe/funções; sem escalas/ponto/folha; repasse só na tutoria (manual).
- Mobile — web responsivo; sem PWA/app.

### Ausente
- Estoque (produtos, lotes, validade, inventário, compras, fornecedores).
- Financeiro avançado: fluxo de caixa, DRE, centros de custo, conciliação bancária, comissões/rateios/repasse estruturados, gateways PIX/cartão/boleto, carnês/parcelamento.
- Prontuário: anamnese estruturada, periodontograma, assinatura do paciente no prontuário, consentimento (TCLE).
- Agenda: lista de espera, recorrência, bloqueios, recursos/equipamentos como agendáveis.
- CRM: funil, campanhas, automações (WhatsApp), pipeline de orçamento.
- **Profissionais:** atendimento geolocalizado/geodistância (gap já mapeado), avaliações/reputação. (Não confundir com "Delivery" — é a evolução do módulo Profissionais.)

### Obsoleto / dívida técnica
- `UpdateDbView`/`Sync` (legado de planilha) — manter só superadmin.
- `/fotos/:id/raw` públicas por id (mitigado com URL assinada; ideal evoluir).
- Orçamento gera um "Contrato" (documento) — convém unificar o fluxo orçamento→contrato no motor.

---

## PARTE III — Roadmap (V1 / V2 / V3)

Matriz: Impacto (I) · Retorno financeiro (R) · Esforço (E) — escala 1–5.

### V1 — Quick wins (alto I, baixo E)
| Item | I | R | E |
|---|---|---|---|
| Anamnese + TCLE estruturados no prontuário | 5 | 3 | 2 |
| Lembretes automáticos de consulta (WhatsApp/e-mail via webhook existente) | 5 | 4 | 2 |
| Agenda: bloqueios + lista de espera (reaproveitar "interesses"/anti-overbooking) | 4 | 3 | 2 |
| Contas a pagar/receber sobre o `financeiro` atual (status/vencimento/baixa) | 5 | 4 | 3 |
| Orçamento → Contrato → Financeiro (ligar os 3 que já existem) | 5 | 5 | 3 |
| Pacote de relatórios essenciais (produção, faltas, financeiro por período, conversão de leads) | 4 | 3 | 2 |

### V2 — Diferenciação e receita (alto R)
| Item | I | R | E |
|---|---|---|---|
| Comissões/Repasse profissional (agenda→procedimento→financeiro→profissional) | 5 | 5 | 4 |
| Gateways de pagamento (PIX/cartão/boleto) + carnês/parcelamento | 4 | 5 | 4 |
| CRM com funil + WhatsApp + automações (sobre Leads) | 5 | 5 | 4 |
| Fluxo de caixa + centros de custo | 4 | 4 | 3 |
| Periodontograma + evolução clínica padronizada | 4 | 2 | 3 |
| Contratos: partes externas por link + PDF server-side + Clicksign | 4 | 3 | 4 |

### V3 — Plataforma
| Item | I | R | E |
|---|---|---|---|
| Estoque completo (lotes/validade/inventário/compras/fornecedores) + integração financeira | 4 | 3 | 5 |
| DRE + conciliação bancária | 3 | 4 | 5 |
| RH: escalas/ponto/produção/folha | 3 | 3 | 5 |
| App/PWA mobile | 4 | 3 | 4 |
| Profissionais: atendimento/geodistância + avaliações/reputação | 3 | 3 | 4 |
| BI/Dashboards configuráveis + alertas automatizados | 3 | 3 | 4 |

---

## Mapa de conexões entre telas

### Já existe
- Agenda → Novo Agendamento → busca Paciente → cria agendamento.
- Lead → Converter → Paciente (+ 1º agendamento).
- Agendamento → Solicitar Avaliação → novo slot vinculado.
- Paciente → tile Orçamentos → gera contrato/print.
- Sala → Reserva → anti-conflito.
- Profissional (marketplace) → Proposta → notificação.

### Falta ligar (o "tecido conjuntivo" — maior ganho de V1/V2)
- Procedimento realizado (agenda) → lançamento Financeiro → Comissão → Repasse profissional.
- Orçamento aprovado → Contrato (motor) → Financeiro (parcelas).
- Contrato assinado → vigência → cobrança recorrente.
- Estoque ← consumo por procedimento.

> Diagnóstico central: módulos fortes, pouco conectados. O maior retorno não é criar
> módulos novos, e sim LIGAR agenda↔financeiro↔contrato↔profissional.

---

## Síntese por cenário
- Clínica/Consultório: prontos; faltam financeiro avançado + comissões.
- Dentista autônomo: workspace "pessoal" já funciona; falta repasse/produção.
- Biomédico: áreas/especialidades ok; harmonização (contrato já criado); falta agenda estética dedicada.
- Locação de salas: maduro; falta integrar reserva→financeiro/contrato de locação (o motor já tem o modelo).
- **Profissionais (marketplace, ex-"Delivery"):** maduro; falta avaliações/reputação, fechamento via contrato e geodistância.
- Multiempresa/Multitenant: o ponto mais forte — base sólida para escalar.

---

# DEEP-DIVE 1 — Financeiro + Comissões/Repasse (2026-06-15)

## A) Checklist da tela Financeiro
- **Objetivo:** registrar/acompanhar lançamentos (receita/despesa) por status.
- **Acesso:** Menu → Financeiro; dono/admin/funcionário (escopo por clínica, `tenantGuard`).
- **Dados:** lista (paciente, descrição, valor, vencimento, status) + KPIs Recebido/Pendente/Atrasado.
- **Tabela `financeiro`:** `id, clinica_id, pacientenome(texto), descricao, valor, datavencimento, status(Pago/Pendente/Atrasado), formapagamento, tipo(RECEITA/DESPESA)`. 0 linhas.
- **Botões:** Filtrar(status) · Novo lançamento · linha: Confirmar pagamento, Gerar recibo (download), Excluir.
- **Integrações:** PARCIAL — `LancarProcedimentoModal → saveFinanceiro` (procedimento gera 1 lançamento). Nenhuma outra.
- **Limitações:** soma por status; "Atrasado" manual.

## B) Diagnóstico — Financeiro é uma "ilha"
A `financeiro` não tem chaves de ligação: `pacientenome` é texto (não FK); não há `profissional_id`, `agendamento_id`, `procedimento_id`, `orcamento_id`, `contrato_id`. Despesa = só `tipo=DESPESA` (sem fornecedor/centro de custo/recorrência). **Comissão/Repasse inexistente** (`procedimentos.valorparticular` sem %; `dentistas` sem repasse). A maior alavanca é a FK **`profissional_id`** — sem ela, não há comissão, repasse nem relatório de produção.

## C) Fluxo conectado proposto
Agenda (paciente+dentista+procedimento) → concluído → LANÇAMENTO (com FKs) → regra de COMISSÃO → REPASSE por período. Orçamento aprovado → Contrato (motor) → parcelas (contas a receber). Despesa → fornecedor/centro de custo → fluxo de caixa/DRE.

## D) Evolução do modelo
- **V1:** FKs em `financeiro` (`paciente_id, profissional_id, procedimento_id, agendamento_id, contrato_id, origem`); `pago_em`; job de "Atrasado"; contas a pagar (fornecedor/centro de custo/recorrente); relatórios essenciais.
- **V2:** `comissao_regras` (por procedimento/profissional/convênio; %/fixo/produção; base bruta/líquida); `comissao_valor` no lançamento; `repasses` (consolida por profissional/período) formalizado pelos modelos "Contrato por Comissão/Produção/Percentual" do motor.

## E) Regras de comissão por cenário
Dentista da clínica (% líquido por especialidade/convênio); autônomo (100%, ou taxa de sala); sala alugada (receita − aluguel, liga `sala_reservas`); biomédico/harmonização (% + material parametrizável); Profissionais/marketplace (contrato de comissão define %); multiempresa (repasse consolidado por unidade).

> Backlog acionável do V1 Financeiro: ver `BACKLOG-FINANCEIRO-V1.md`.