Merge pull request 'feat(superadmin): página Secretária IA (motivos de liga/desliga por sessão)' (#5) from feat/newwhats-satelite into main

Nova aba no super admin (/superadmin/secretaria): tabela com quem ligou/desligou a
Secretária de cada número, quando e o MOTIVO do desligamento. Endpoint
/api/superadmin/secretaria-desligamentos (superadminGuard) busca o log global no
motor (resolve um e-mail de dono pareado; log é global). Item no Sidebar + rotas.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitea/workflows/build.yml

@@ -40,6 +40,9 @@ jobs:
           GIT_COMMIT: ${{ steps.vars.outputs.commit }}
           BUILD_TIME: ${{ steps.vars.outputs.build_time }}
           APP_ENV: PROD
+          # SCOREO_DB_PASS tem fail-fast `:?` no compose (runtime). No build é só interpolado,
+          # nunca entra na imagem (é `environment:`, não build-arg) — placeholder satisfaz o compose.
+          SCOREO_DB_PASS: build-placeholder
         run: docker compose build scoreodonto-backend scoreodonto-frontend
 
       - name: Publicar por COMMIT (:<sha> + :latest), com retry p/ 499

.gitignore

@@ -12,11 +12,21 @@ backend/test-db-users.js
 backend/test-db-users.cjs
 backend/pg-convert.js
 
-# Override local de ambiente DEV (aponta o banco p/ pgdev) — NÃO versionar
+# Segredos de ambiente — NÃO versionar (qualquer nível)
 .env
+**/.env
+backend/.env
+.secrets
+**/.secrets
+*.dump
+backend/server.js.bak
 
 # Dependências e caches locais
 node_modules/
 frontend/node_modules/
 backend/node_modules/
 .claude/
+
+# backups de env (segredos) — nunca versionar
+*.env.bak*
+backend/.env.bak*

LEIA.md

@@ -0,0 +1,15 @@
+# LEIA
+
+A documentação deste projeto **NÃO fica aqui**. Fonte única (em português):
+**`git.clube67.com/ruicesar/Documentos-Unicos`**  ·  local: `/home/deploy/stack/documentos-unicos/`
+Comece pelo `LEIA-PRIMEIRO.md`.
+
+- Universal (vale para todos): `deploy/` e `infra/`
+- Específico deste projeto, **só se diferir** do universal: `projetos/scoreodonto.com/`
+
+## Regras-chave
+- **Sempre testar em `https://dev.<dominio>`** antes de qualquer coisa.
+- **Pedir aprovação** do administrador antes de **produção** ou de **novas melhorias/implementações**.
+- **Em dúvida, consultar `desuso/`** (só consulta/histórico) — instrução nova vai **sempre** na doc oficial.
+- **Não duplicar**: se o tema já existe, não recriar. Preferir doc **universal**; o que diferir vai em `projetos/scoreodonto.com/` (citando o que difere).
+- **Nunca** criar documentação solta no projeto. **Tudo em português.**

ScoreOdonto_Skills_Enterprise/00_LEIA_PRIMEIRO.md

@@ -0,0 +1,35 @@
+# SCOREODONTO ENTERPRISE SKILLS
+
+## REGRA Nº 1 — NÃO QUEBRAR O QUE JÁ FUNCIONA
+
+Antes de qualquer alteração:
+
+- Auditar impacto.
+- Identificar dependências.
+- Identificar telas afetadas.
+- Identificar APIs afetadas.
+- Identificar tabelas afetadas.
+- Identificar permissões afetadas.
+- Identificar integrações afetadas.
+
+PROIBIDO:
+
+- Refatorar sem auditoria.
+- Remover funcionalidades existentes sem validação.
+- Alterar identidade visual aprovada.
+- Alterar fluxo financeiro sem mapeamento.
+- Alterar entidades centrais sem documentação.
+
+Toda implementação deve seguir:
+
+Auditoria → Planejamento → Aprovação → Implementação → Validação.
+
+Arquitetura oficial:
+
+Pessoa → Vínculo → Workspace
+
+Workspaces:
+- Clínica
+- Consultório
+- Laboratório
+- Sala

ScoreOdonto_Skills_Enterprise/FASE_01_ARQUITETURA/SKILL_ModelagemMestra.md

@@ -0,0 +1,69 @@
+# SKILL — Modelagem Mestra
+
+> **Skill raiz.** Todas as demais skills herdam destas regras. Baseado em evidências reais do
+> `backend/server.js` e do schema. Antes de qualquer alteração: **Auditoria → Planejamento → Aprovação → Implementação → Validação.**
+
+## Conceito de negócio
+O ScoreOdonto **não é um sistema de clínica**; é uma **plataforma de pessoas** que atuam dentro de
+workspaces. A clínica é apenas **um tipo de workspace**. A arquitetura oficial é:
+
+```
+Pessoa → Vínculo → Workspace → Serviços → Marketplace → Financeiro
+```
+
+## Objetivo da skill
+Fixar o modelo mental único do sistema, para que nenhum módulo volte ao paradigma legado
+"Clínica → tudo". Toda entidade nova deve se posicionar nessa cadeia.
+
+## Entidades centrais (fonte da verdade)
+| Camada | Tabela real | Papel |
+|---|---|---|
+| Pessoa | `usuarios` | Identidade única (login). Âncora de tudo. |
+| Vínculo | `vinculos` | Liga pessoa↔workspace com papel e RBAC. |
+| Workspace | `clinicas` (`tipo` ∈ pessoal/consultorio/clinica) + `salas` | Contexto operacional. |
+| Capacidades | `usuario_plugins`, `usuario_areas` | Atributos da pessoa (não do workspace). |
+
+## Relacionamentos
+- `usuarios (1) → (N) vinculos (N) → (1) clinicas` — uma pessoa, vários workspaces, papel por workspace.
+- `clinicas.owner_id → usuarios.id` — todo workspace tem dono.
+- Ao registrar, cria-se automaticamente um **workspace pessoal** (`clinicas.tipo='pessoal'`).
+
+## Regras obrigatórias
+1. **A pessoa (`usuarios`) é a âncora.** Capacidades (áreas, plugins, tutor) pertencem à pessoa.
+2. **Clínica/Consultório/Sala/Laboratório são `tipo` de workspace**, nunca entidades de topo.
+3. **Todo dado operacional é escopado por workspace** (`clinica_id`) via `tenantGuard`.
+4. **Nunca duplicar a pessoa** para representá-la em outro workspace — use `vinculos`.
+5. **Migração aditiva**: colunas novas via `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` (padrão atual).
+
+## Casos de uso
+- Dentista atende em 3 clínicas → 1 `usuarios` + 3 `vinculos`.
+- Profissional autônomo sem clínica → `usuarios` + workspace `tipo='pessoal'`.
+- Locador de sala → `usuarios` + `salas` (workspace `tipo='sala'`).
+
+## Anti-padrões (PROIBIDO)
+- ❌ Criar tabela-entidade nova "espelhando" a pessoa por workspace (vide débito de `dentistas`).
+- ❌ Tratar `clinica` como raiz hierárquica do sistema.
+- ❌ Guardar identidade/capacidade no workspace em vez de na pessoa.
+- ❌ Escrever dado operacional sem `clinica_id`.
+
+## Impactos em outros módulos
+Esta skill governa **todas**: Pessoa, Workspace, Vínculos, Multiempresa, RBAC e todos os módulos
+de negócio. Qualquer conflito com ela é defeito de modelagem (gravidade ALTA).
+
+## Débitos conhecidos (legado clínica-cêntrico ainda vivo)
+- `pacientes` (sem `usuario_id`, preso à clínica) e `dentistas` (tabela paralela a `usuarios`).
+- Workspace dividido em 2 tabelas (`clinicas` + `salas`).
+> Ver `../FASE_08_AUDITORIA/SKILL_Entidades.md`.
+
+```mermaid
+flowchart TD
+  P[Pessoa · usuarios] --> V[Vínculo · vinculos]
+  V --> W{Workspace}
+  W -->|tipo=clinica| C[Clínica]
+  W -->|tipo=consultorio| K[Consultório]
+  W -->|tipo=sala| S[Sala]
+  W -->|tipo=pessoal| PP[Workspace Pessoal]
+  P --> CAP[Capacidades · areas/plugins]
+  W --> OP[Operação · pacientes/agenda/financeiro]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_01_ARQUITETURA/SKILL_Multiempresa.md

@@ -0,0 +1,48 @@
+# SKILL — Multiempresa (Tenancy)
+
+> Herda de `SKILL_ModelagemMestra.md`. Regra de isolamento de dados entre workspaces.
+
+## Conceito de negócio
+Cada workspace é um inquilino (tenant). Dados de uma clínica **nunca** podem vazar para outra.
+A mesma pessoa pode transitar entre tenants via vínculos, mas os **dados ficam no tenant**.
+
+## Objetivo
+Garantir isolamento por `clinica_id` em 100% da operação e impedir queries sem escopo.
+
+## Entidades envolvidas
+- Toda tabela operacional tem `clinica_id` (`pacientes`, `agendamentos`, `financeiro`,
+  `procedimentos_realizados`, `orcamentos`, `contratos`, `repasses`, `glosas`, `protese_os`…).
+- `audit_log` por `clinica_id`.
+
+## Relacionamentos / mecanismo real
+- **`tenantGuard`** (middleware) injeta `req.clinicaId` e é exigido na maioria das 277 rotas.
+- **`authGuard`** é o plano de identidade (rotas `me/*`) — sem tenant.
+- O cliente envia o workspace ativo; o backend valida o vínculo antes de servir dados.
+
+## Regras obrigatórias
+1. **Toda query operacional filtra `clinica_id = $req.clinicaId`.** Sem exceção.
+2. Rota que toca dado de clínica usa `tenantGuard`; rota de identidade usa `authGuard`.
+3. `superadmin` é o único plano transversal (gestão global) — auditar com cuidado.
+4. Marketplace cross-tenant (salas/propostas) é **acoplamento intencional** e explícito.
+
+## Casos de uso
+- Listar pacientes → sempre do `clinica_id` ativo.
+- Trocar workspace → recomputar tudo no novo `clinica_id`.
+
+## Anti-padrões
+- ❌ `SELECT ... FROM pacientes` sem `clinica_id`.
+- ❌ Confiar em `clinica_id` vindo do corpo do request sem validar o vínculo.
+- ❌ Agregar entre clínicas fora dos fluxos de marketplace/superadmin.
+
+## Impactos
+Base de segurança de TODOS os módulos. Falha aqui = vazamento de dados (gravidade ALTA) + risco LGPD.
+
+```mermaid
+flowchart TD
+  REQ[Request] --> AG{Guard}
+  AG -->|authGuard| ID[Identidade · me/*]
+  AG -->|tenantGuard| TEN[req.clinicaId]
+  TEN --> Q[Query SEMPRE com clinica_id]
+  Q --> DB[(Postgres)]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_01_ARQUITETURA/SKILL_Pessoa.md

@@ -0,0 +1,48 @@
+# SKILL — Pessoa
+
+> Herda de `SKILL_ModelagemMestra.md`. A Pessoa é a **âncora única** do sistema.
+
+## Conceito de negócio
+Toda interação no ScoreOdonto parte de uma **pessoa** (humano com login). Papéis (dentista,
+biomédico, protético, paciente, tutor, dono) são **facetas** da mesma pessoa, não entidades separadas.
+
+## Objetivo
+Garantir que identidade, capacidades e histórico fiquem na pessoa — nunca duplicados por workspace.
+
+## Entidades envolvidas
+- `usuarios` — identidade (login, `role` global, `is_tutor`).
+- `usuario_areas` — áreas de atuação (multi-área; ref. `areas`).
+- `usuario_plugins` — capacidades/add-ons por pessoa (`me/plugins`).
+- `vinculos` — onde a pessoa atua e com qual papel.
+
+## Relacionamentos
+- `usuarios (1) → (N) vinculos` — pessoa em vários workspaces.
+- `usuarios (1) → (N) usuario_areas` e `(N) usuario_plugins`.
+- Marketplace de profissionais: `propostas_profissional.profissional_id → usuarios.id`.
+
+## Regras obrigatórias
+1. **Uma pessoa = um `usuarios`** (idealmente deduplicado por CPF/e-mail).
+2. **Capacidades vivem na pessoa**, não no workspace.
+3. `role` global em `usuarios` só para `superadmin`; os demais papéis vêm de `vinculos.role`.
+4. Toda rota de identidade usa `authGuard` (não `tenantGuard`).
+
+## Casos de uso
+- Pessoa é dentista numa clínica e dono de sala em outra → 2 vínculos, papéis distintos.
+- Pessoa ativa o plugin de Salas → grava em `usuario_plugins` (vale em qualquer dispositivo).
+
+## Anti-padrões
+- ❌ Criar `dentistas`/`proteticos` como tabela de identidade paralela (débito atual de `dentistas`).
+- ❌ Persistir capacidade só no `localStorage` sem refletir em `usuario_plugins` (risco de divergência).
+
+## Impactos em outros módulos
+Base de Vínculos, RBAC, Marketplace, Tutoria, Pessoas (Fase 3). Mudou a pessoa → reflete em todos.
+
+```mermaid
+flowchart LR
+  U[usuarios] --> A[usuario_areas]
+  U --> PL[usuario_plugins]
+  U --> V[vinculos]
+  U --> PR[propostas_profissional]
+  V --> WS[Workspaces]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_01_ARQUITETURA/SKILL_RBAC.md

@@ -0,0 +1,47 @@
+# SKILL — RBAC (Controle de Acesso)
+
+> Herda de `SKILL_Vinculos.md`. Define quem vê e faz o quê, por papel e função, no workspace ativo.
+
+## Conceito de negócio
+Acesso é decidido pelo **papel da pessoa no workspace ativo** + permissões finas da `funcao`.
+O frontend espelha o backend: menu e telas seguem a mesma matriz de papéis.
+
+## Objetivo
+Padronizar a decisão de acesso e manter front/back coerentes (sem permissão hardcoded).
+
+## Entidades / mecanismo real
+- **Backend:** `tenantGuard`/`authGuard`; `vinculos.role` + `funcoes` (permissões); `usuarios.role` só p/ `superadmin`.
+- **Frontend:** `App.tsx → isViewAllowed(view, role)` e o filtro de menu em `components/Sidebar.tsx`.
+- Papéis: `superadmin` (global), `admin`/`donoclinica`/`donoconsultorio` (amplo), `funcionario`,
+  `dentista`, `biomedico`, `protetico`, `paciente`, `donosala`.
+
+## Regras obrigatórias
+1. **Decisão por papel/função**, nunca por identidade individual.
+2. Quando a `funcao` define permissões explícitas (`permissoes[]`), elas **prevalecem** sobre o default do papel.
+3. Telas `superadmin*` e o catálogo de `plugins` são **exclusivos do superadmin**.
+4. Workspace `tipo='sala'` restringe o menu a painel da sala/conta/notificações.
+5. **Mudou regra de acesso no backend → atualizar `isViewAllowed` e `Sidebar` no mesmo PR.**
+
+## Casos de uso
+- Biomédico não vê Ortodontia/RX (não-odonto) — regra explícita no menu.
+- Cargo customizado com `permissoes:['agenda','financeiro']` → menu reduzido a isso.
+
+## Anti-padrões
+- ❌ Liberar tela no front sem proteger a rota no back (e vice-versa).
+- ❌ Checar `if (email === 'x')`.
+- ❌ Esquecer de espelhar a permissão nos dois lados (front/back divergentes).
+
+## Impactos
+Governa todo o menu, todas as rotas e a experiência por papel. Ver `../FASE_08_AUDITORIA/SKILL_Rotas.md`.
+
+```mermaid
+flowchart TD
+  P[Pessoa] --> V[vinculo.role no workspace ativo]
+  V --> F{tem funcao com permissoes?}
+  F -->|sim| PERM[usa permissoes da funcao]
+  F -->|não| DEF[usa default do papel]
+  PERM --> UI[Sidebar + isViewAllowed]
+  DEF --> UI
+  UI --> API[rota protegida por guard]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_01_ARQUITETURA/SKILL_Vinculos.md

@@ -0,0 +1,46 @@
+# SKILL — Vínculos
+
+> Herda de `SKILL_ModelagemMestra.md`. O vínculo é a **ponte** pessoa↔workspace e o lugar do papel.
+
+## Conceito de negócio
+Uma pessoa não "é" dentista no sistema — ela **tem um vínculo de papel dentista** num workspace.
+Mudou de workspace, muda o papel. É o que permite multi-clínica sem duplicar a pessoa.
+
+## Objetivo
+Centralizar papel + RBAC na relação, nunca na identidade nem no workspace.
+
+## Entidades envolvidas
+- `vinculos(id, usuario_id, clinica_id, role, setor_id, funcao_id)`.
+- `funcoes` (cargos com permissões) e `setores` — por workspace.
+- Constraint real de papéis (`vinculos_role_check`):
+  `paciente, dentista, biomedico, protetico, funcionario, donoclinica, donoconsultorio, donosala, admin`.
+
+## Relacionamentos
+- `vinculos.usuario_id → usuarios.id`; `vinculos.clinica_id → clinicas.id`.
+- `vinculos.funcao_id → funcoes.id` (permissões finas); `vinculos.setor_id → setores.id`.
+
+## Regras obrigatórias
+1. **Papel operacional vem do vínculo** (`vinculos.role`), não de `usuarios` (exceto `superadmin`).
+2. **N vínculos por pessoa** — multi-workspace é nativo. Nunca duplicar a pessoa.
+3. A permissão efetiva = papel do vínculo **+** permissões da `funcao` (quando houver).
+4. Remover acesso = remover/alterar o vínculo, jamais apagar a pessoa.
+
+## Casos de uso
+- Convidar membro: cria `vinculos` com `role` + `funcao_id`.
+- Profissional sai da clínica: deleta o vínculo; histórico e identidade permanecem.
+
+## Anti-padrões
+- ❌ Guardar papel em tabela-recurso (débito de `dentistas`).
+- ❌ Permissão hardcoded por e-mail/nome em vez de papel/função.
+
+## Impactos
+Base direta de RBAC, Multiempresa, Gestão de Equipe e do menu/`isViewAllowed` do frontend.
+
+```mermaid
+flowchart LR
+  U[usuarios] --> VN[vinculos: role, setor, funcao]
+  VN --> CL[clinicas/workspace]
+  VN --> FU[funcoes: permissões]
+  VN --> SE[setores]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_01_ARQUITETURA/SKILL_Workspace.md

@@ -0,0 +1,50 @@
+# SKILL — Workspace
+
+> Herda de `SKILL_ModelagemMestra.md`. Workspace é o **contexto operacional** onde a pessoa atua.
+
+## Conceito de negócio
+Todo dado operacional (pacientes, agenda, financeiro) pertence a um **workspace**, nunca diretamente
+à pessoa. A clínica é o workspace mais comum, mas é só um `tipo`.
+
+## Objetivo
+Padronizar o conceito de workspace e impedir o retorno ao modelo clínica-cêntrico.
+
+## Entidades envolvidas
+- `clinicas` — tabela de workspace. Colunas-chave: `tipo` (`pessoal`|`consultorio`|`clinica`),
+  `owner_id`, `cor`, `geo` (PostGIS). **Hoje "clinicas" É a tabela de workspaces.**
+- `salas` — workspace `tipo='sala'` (tabela separada — débito de unificação).
+- `vinculos` — quem pertence ao workspace e com qual papel.
+
+## Relacionamentos
+- `clinicas.owner_id → usuarios.id`.
+- Operação: `pacientes.clinica_id`, `agendamentos.clinica_id`, `financeiro.clinica_id`, etc.
+- Agregação no app: `GET /api/me/workspaces` → `listarWorkspaces()` reúne clínicas (via vínculo) + salas.
+
+## Regras obrigatórias
+1. **Tudo que é operacional carrega `clinica_id`** e passa por `tenantGuard`.
+2. O **workspace ativo** (cacheado no cliente) governa menu, permissões e dados visíveis.
+3. `tipo='sala'` **isola o contexto** (menu reduzido: painel da sala/conta/notificações).
+4. Workspace pessoal (`tipo='pessoal'`) é criado automaticamente no registro.
+
+## Casos de uso
+- Trocar de workspace no seletor → recarrega contexto (cor de marca, menu, dados).
+- Sala como workspace → usuário cai em `sala-home`, sem acesso à operação clínica.
+
+## Anti-padrões
+- ❌ Ler/gravar operação sem `clinica_id`.
+- ❌ Tratar `salas` e `clinicas` como conceitos distintos na lógica de negócio (são ambos workspace).
+- ❌ Vazar dados entre workspaces (sempre filtrar por `req.clinicaId`).
+
+## Impactos
+Governa Multiempresa, RBAC e todos os módulos de Workspace (Fase 2) e operação.
+
+```mermaid
+flowchart TD
+  WS[Workspace] -->|clinicas.tipo| T1[clinica]
+  WS --> T2[consultorio]
+  WS --> T3[pessoal]
+  WS -->|salas| T4[sala]
+  WS --> OP[pacientes / agenda / financeiro · clinica_id]
+  WS --> VN[vinculos · membros + papéis]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_02_NEGOCIO/SKILL_Clinicas.md

@@ -0,0 +1,42 @@
+# SKILL — Clínicas (Workspace)
+
+> Herda de `SKILL_Workspace.md`. Tipo de workspace mais completo do sistema.
+
+## O que é?
+Workspace `clinicas.tipo='clinica'` — a empresa odontológica com equipe, pacientes e operação plena.
+
+## Quem usa?
+Donos (`donoclinica`/`admin`), funcionários, dentistas, biomédicos, protéticos vinculados.
+
+## Quais módulos possui?
+Dashboard, Agenda, Pacientes, Ortodontia, Próteses/GTO, Financeiro, Comissões, Repasses, Glosas,
+Orçamentos, Contratos, Relatórios, Leads, Equipe/RBAC, Planos/Procedimentos/Especialidades,
+RX (plugin), Configurações. (Menu completo — ver `../FASE_08_AUDITORIA/SKILL_Rotas.md`.)
+
+## Quais receitas gera?
+Produção de procedimentos (RECEITA), contratos/cobrança, recuperação de glosas. Paga repasses (DESPESA).
+> Detalhe do dinheiro em `../FASE_04_FINANCEIRO/`.
+
+## Quais permissões possui?
+Donos/admin: acesso amplo (menos telas `superadmin`). Demais papéis: subconjunto por papel/função (RBAC).
+
+## Entidades envolvidas
+`clinicas` + toda a operação por `clinica_id` + `vinculos`/`funcoes`/`setores`.
+
+## Regras obrigatórias
+1. Operação sempre escopada por `clinica_id` (`tenantGuard`).
+2. A clínica é **um tipo de workspace**, não a raiz do sistema.
+3. Equipe entra por vínculo; permissões por papel/função.
+
+## Anti-padrões
+- ❌ Assumir "uma clínica por usuário" (a pessoa pode ter várias).
+- ❌ Tratar clínica como dona da pessoa.
+
+```mermaid
+flowchart LR
+  CL[Clínica] --> EQ[Equipe via vinculos]
+  CL --> PAC[Pacientes]
+  CL --> AG[Agenda]
+  CL --> FIN[Financeiro → Comissão → Repasse]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_02_NEGOCIO/SKILL_Consultorios.md

@@ -0,0 +1,37 @@
+# SKILL — Consultórios (Workspace)
+
+> Herda de `SKILL_Workspace.md`. Variante enxuta da clínica.
+
+## O que é?
+Workspace `clinicas.tipo='consultorio'` — operação individual/pequena de um profissional-dono.
+Mesma tabela e mecânica da clínica; muda o `tipo` e o papel do dono (`donoconsultorio`).
+
+## Quem usa?
+`donoconsultorio` (profissional que opera por conta própria) e eventuais membros.
+
+## Quais módulos possui?
+Os mesmos da clínica (herda a operação), normalmente com equipe menor. O `tipo` distingue rótulo/UX,
+não um conjunto de tabelas separado.
+
+## Quais receitas gera?
+Iguais às da clínica (produção, contratos), em escala individual.
+
+## Quais permissões possui?
+`donoconsultorio` tem acesso amplo (não-`superadmin`), idêntico ao dono de clínica.
+
+## Regras obrigatórias
+1. **Consultório = `tipo` de workspace**, não um módulo nem uma entidade separada.
+2. `donoconsultorio` é o **papel do dono**; o `tipo='consultorio'` é o **workspace**.
+3. Não criar tabelas próprias de "consultório" — reutilizar a operação por `clinica_id`.
+
+## Anti-padrões / Débito conhecido
+- ⚠️ Acoplamento **role↔tipo** (`donoconsultorio`⇄`tipo='consultorio'`): decisão duplicada.
+  Ao ramificar lógica, prefira o `tipo` do workspace, não a role.
+- ❌ Duplicar telas/tabelas só para "consultório".
+
+```mermaid
+flowchart LR
+  K[Consultório · tipo=consultorio] --> OWN[Dono · donoconsultorio]
+  K --> OP[Operação reutilizada por clinica_id]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_02_NEGOCIO/SKILL_Delivery.md

@@ -0,0 +1,43 @@
+# SKILL — Delivery (Profissionais temporários) — ALVO / ROADMAP
+
+> Herda de `SKILL_Marketplace.md`. **ATENÇÃO: não existe no código hoje.** Esta skill descreve o conceito-alvo
+> e as **sementes reais** sobre as quais ele se apoiaria — sem inventar funcionalidade.
+
+## O que NÃO existe hoje (estado real)
+Não há nenhuma implementação de "delivery"/plantão/diária de profissional: sem contratação temporária,
+sem vínculo por período, sem pagamento de profissional avulso. Buscas por `delivery/temporario/plantao/
+freela/substituto` no `server.js` **não retornam feature** — apenas os fragmentos abaixo.
+
+## Sementes reais já existentes (base para o alvo)
+1. **Marketplace de Profissionais**: `profissionais-disponiveis`, `profissionais/marketplace`, `propostas`
+   (clínica→profissional). Hoje só **mensagem/conexão**, status `pendente`.
+2. **Modelos de período** (vindos das Salas): `RESERVA_MODELOS = ['hora','turno','diaria','semanal','mensal']`
+   e `valor_diaria`/`diaria_consulta` — o conceito de **diária** já está modelado para salas.
+3. **Vínculos temporários**: `vinculos` já suporta papel por workspace — a base para um vínculo com prazo.
+
+## Conceito-alvo (Delivery)
+Profissional aceita uma **escala temporária** numa clínica (ex.: diária/turno), com início/fim, valor e
+pagamento — unindo a proposta de profissional ao modelo de período e a um vínculo com prazo.
+
+## O que faltaria (lacunas — descrever, NÃO implementar)
+- Evoluir `propostas_profissional` de mensagem → **acordo com período + valor + aceite**.
+- Vínculo temporário (`vinculos` com janela de validade) e seu encerramento automático.
+- Captura de pagamento (mesma lacuna de Salas) e repasse ao profissional avulso.
+
+## Regras obrigatórias (se um dia evoluir)
+1. Construir **sobre as sementes** (propostas + modelos de período + vínculos), sem entidade paralela nova.
+2. Manter Pessoa→Vínculo→Workspace: delivery é **vínculo temporário**, não nova classe de pessoa.
+3. Seguir Auditoria → Planejamento → **Aprovação** antes de qualquer implementação.
+
+## Anti-padrões
+- ❌ Documentar/assumir Delivery como se existisse.
+- ❌ Criar tabela/role nova "delivery" em vez de reusar `vinculos` + `propostas`.
+
+```mermaid
+flowchart LR
+  PROF[Profissional · perfil] --> PROP[Proposta hoje: mensagem]
+  PROP -. alvo .-> ACORDO[Acordo: período + valor + aceite]
+  ACORDO -. alvo .-> VT[vinculo temporário]
+  VT -. alvo .-> PAY[(pagamento + repasse)]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_02_NEGOCIO/SKILL_Laboratorios.md

@@ -0,0 +1,46 @@
+# SKILL — Laboratórios (Workspace-alvo)
+
+> Herda de `SKILL_Workspace.md`. **Atenção:** o estado ATUAL difere da arquitetura-alvo.
+
+## O que é? (estado real hoje)
+Hoje o laboratório é um **cadastro interno por clínica** (`protese_laboratorios`), usado nas Ordens de
+Serviço de prótese e no **custo lab** que abate comissão. **Não** tem identidade própria nem login,
+**não** cruza clínicas. (Modelo "A — cadastro auxiliar".)
+
+## Arquitetura-alvo (declarada no LEIA-PRIMEIRO)
+O laboratório é listado como **tipo de workspace** (Clínica/Consultório/Laboratório/Sala). Ou seja,
+a visão oficial é elevá-lo a **participante/operador do ecossistema**, não apenas lookup.
+
+## Quem usa?
+Protéticos/laboratórios e as clínicas que enviam OS. (O protético-pessoa é tratado em
+`../FASE_03_PESSOAS/SKILL_Proteticos.md` — não confundir pessoa com laboratório.)
+
+## Quais módulos possui? (hoje)
+Cadastro de laboratório + produtos (`protese_produtos`) + OS (`protese_os`, `protese_os_evento`,
+`protese_os_foto`). Integra com Comissões via custo lab.
+
+## Quais receitas gera?
+Indireta hoje (operacional: custo lab compõe a margem). Como workspace, poderia faturar produção própria.
+
+## Quais permissões possui?
+Hoje: dentro do RBAC da clínica que cadastra. Como workspace: teria papéis/vínculos próprios.
+
+## Regras obrigatórias
+1. **Não confundir** laboratório (fornecedor/operador) com protético (pessoa).
+2. Enquanto for cadastro, manter `clinica_id` e custo lab consistentes com Comissões.
+3. Qualquer evolução para workspace é decisão arquitetural → seguir Auditoria→Aprovação (não implementar aqui).
+
+## Anti-padrões
+- ❌ Tratar o laboratório como pessoa (login) sendo cadastro, ou vice-versa.
+- ❌ Recadastrar o mesmo laboratório em cada clínica como se fossem distintos (limitação atual a registrar).
+
+```mermaid
+flowchart LR
+  subgraph Hoje
+    LAB[protese_laboratorios · cadastro por clínica] --> OS[protese_os] --> COM[custo lab → Comissão]
+  end
+  subgraph Alvo
+    LABW[Laboratório · workspace] --> OPR[Opera no ecossistema]
+  end
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_02_NEGOCIO/SKILL_Marketplace.md

@@ -0,0 +1,44 @@
+# SKILL — Marketplace
+
+> Herda de `../FASE_01_ARQUITETURA/SKILL_Workspace.md` e `SKILL_Pessoa.md`. O marketplace só existe
+> porque a base é **Pessoa → Vínculo → Workspace** (atores cruzam fronteiras de clínica).
+
+## Conceito
+O marketplace conecta **pessoas/workspaces** entre si, cross-tenant. São **três frentes** reais hoje,
+em maturidades diferentes:
+
+| Frente | O que existe | Receita |
+|---|---|---|
+| **Salas (locação)** | CRUD + `salas/marketplace` + reservas (`sala_reservas`), modelos `hora/turno/diaria/semanal/mensal` com `valor_*` | `valor` registrado, **sem gateway** |
+| **Profissionais** | `profissionais/perfil`, `profissionais/marketplace`, `profissionais-disponiveis`, `propostas` (clínica→profissional) | **Só mensagem**, sem cobrança |
+| **Tutoria orto** | candidatura paga (MercadoPago) + solicitações | ✅ **única automatizada** (`comissao_pct`) |
+
+## Entidades / rotas reais
+- Salas: `salas`, `sala_reservas` · `GET/POST/PUT /api/salas*`, `/api/sala-reservas*`.
+- Profissionais: `propostas_profissional` (`status='pendente'`, dup-check por clínica+profissional) ·
+  `/api/profissionais/*`, `/api/propostas*`. Perfil = `usuarios` (nível pessoa, `authGuard`).
+- Tutoria: ver `../FASE_03_PESSOAS/SKILL_Tutores.md`.
+
+## Permissões
+- Salas: plugin `locacao-salas` (sempre ON), todos menos `superadmin`.
+- Profissionais: plugin `profissionais-marketplace`, clínicos exceto `paciente`.
+- O catálogo de plugins é exclusivo do `superadmin`.
+
+## Regras obrigatórias
+1. Marketplace é **cross-tenant intencional** — mas cada lado continua isolado por `clinica_id`/workspace.
+2. **Sinalizar lacunas de pagamento** (salas/profissionais), nunca presumir transação concluída.
+3. Proposta de profissional hoje é **conexão (mensagem)**, não contratação — não inventar fluxo inexistente.
+
+## Anti-padrões
+- ❌ Acoplar marketplace à clínica (Modelo A) — ele depende da pessoa/workspace (Modelo B).
+- ❌ Tratar reserva/proposta como paga.
+
+```mermaid
+flowchart LR
+  P[Pessoa/Workspace] --> S[Salas: reserva valor/modelo]
+  P --> PR[Profissionais: perfil + proposta]
+  P --> T[Tutoria: MercadoPago]
+  S -. falta .-> PAY[(gateway)]
+  PR -. falta .-> CONTR[(contratação/cobrança)]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_02_NEGOCIO/SKILL_Salas.md

@@ -0,0 +1,43 @@
+# SKILL — Salas (Workspace + Marketplace)
+
+> Herda de `SKILL_Workspace.md`. Único workspace que já nasce no modelo novo + marketplace.
+
+## O que é?
+Workspace `tipo='sala'` (tabela `salas`) que pode ser **locado** a terceiros. Plugin `locacao-salas`
+é **sempre ativo** (capability de plataforma).
+
+## Quem usa?
+- **Locador** (`donosala` ou qualquer conta): cadastra e administra salas ("Minhas Salas").
+- **Locatário** (qualquer profissional): busca e reserva ("Alugar Salas").
+
+## Quais módulos possui?
+Painel da sala (`sala-home`), marketplace de salas, reservas (`sala_reservas`), geolocalização (PostGIS `geo`).
+
+## Quais receitas gera?
+**Potencial.** `sala_reservas` já tem `valor`, `modelo` e workflow de status (`pendente`→`aceita`),
+mas **não há captura de pagamento** (gateway) — o fluxo financeiro **não fecha** hoje.
+> É a alavanca de receita mais próxima de destravar. Ver `../FASE_04_FINANCEIRO/SKILL_Faturamento.md`.
+
+## Quais permissões possui?
+Workspace `tipo='sala'` **isola** o contexto: menu só painel da sala/conta/notificações.
+Os itens "Minhas Salas"/"Alugar Salas" são de plugin (todos menos `superadmin`).
+
+## Entidades envolvidas
+`salas`, `sala_reservas` (cross-tenant: locação entre workspaces distintos).
+
+## Regras obrigatórias
+1. Reserva é **cross-tenant intencional** — validar disponibilidade (anti-overbooking de sala).
+2. Contexto de sala isola da clínica (não misturar operação clínica no workspace de sala).
+3. `valor` da reserva é registrado; **pagamento real é externo** (lacuna a sinalizar, não assumir).
+
+## Anti-padrões
+- ❌ Assumir que a reserva foi paga (não há gateway).
+- ❌ Vazar dados da clínica para o contexto de sala.
+
+```mermaid
+flowchart LR
+  SAL[Sala · workspace] --> MKT[Marketplace de salas]
+  MKT --> RES[sala_reservas: valor, status]
+  RES -. falta .-> PAY[(Pagamento/gateway)]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_03_PESSOAS/SKILL_Biomedicos.md

@@ -0,0 +1,39 @@
+# SKILL — Biomédicos (Pessoa)
+
+> Herda de `../FASE_01_ARQUITETURA/SKILL_Pessoa.md`. Profissional de **biomedicina estética**, não-odonto.
+
+## Perfil
+Pessoa (`usuarios`) com vínculo `biomedico`. Tem **catálogo próprio** (especialidades/procedimentos de
+biomedicina) — semeável via `POST /api/me/seed-biomedicina`. Multi-área pelo perfil (`usuario_areas`/`areas`).
+
+## Fluxos
+- Agenda própria + Tratamentos + lançamento de procedimentos do seu catálogo.
+- **Sem** itens odontológicos (Ortodontia, RX, tutoria orto) — separação explícita no menu.
+
+## Permissões (RBAC)
+Menu: `dashboard, agenda, tratamentos, especialidades, procedimentos, clinicas, notificacoes,
+configuracoes, diretorio-profissionais`. Não vê Ortodontia/RX/tutoria.
+
+## Marketplace
+Publica perfil no diretório de Profissionais; recebe propostas; pode locar/alugar salas.
+
+## Financeiro
+Produção gera RECEITA/Comissão no workspace onde atua (mesma mecânica de `comissao_regras`/Repasse).
+
+## Regras obrigatórias
+1. Catálogo de biomedicina é **da área**, não misturar com catálogo odonto.
+2. Identidade/áreas na pessoa; papel no vínculo.
+3. Não expor telas odonto ao papel `biomedico` (regra de menu já existente).
+
+## Anti-padrões
+- ❌ Vazar Ortodontia/RX para o menu do biomédico.
+- ❌ Duplicar a pessoa por local de atuação.
+
+```mermaid
+flowchart LR
+  B[Biomédico · usuarios] --> V[vinculo role=biomedico]
+  B --> AR[usuario_areas: biomedicina]
+  V --> AG[Agenda] --> PR[Procedimento área] --> COM[Comissão→Repasse]
+  B --> MKT[Diretório/Propostas]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_03_PESSOAS/SKILL_Dentistas.md

@@ -0,0 +1,45 @@
+# SKILL — Dentistas (Pessoa)
+
+> Herda de `../FASE_01_ARQUITETURA/SKILL_Pessoa.md` e `SKILL_Vinculos.md`.
+
+## Perfil
+Pessoa (`usuarios`) com vínculo de papel `dentista` num workspace. É o clínico odontológico completo.
+**Débito conhecido:** existe também a tabela `dentistas` (recurso de agenda por clínica, com `usuario_id`
+opcional) — a MESMA pessoa pode aparecer como `usuarios` + `dentistas`. Tratar `dentistas` como
+**projeção de agenda**, não como identidade. Ver `../FASE_08_AUDITORIA/SKILL_Entidades.md`.
+
+## Fluxos
+- Atende na Agenda → registra Procedimento Realizado → gera RECEITA/Comissão.
+- Ortodontia completa (triagem, plano, evoluções, fotos, contenção).
+- Pode pedir tutoria de orto e/ou ser tutor (ver `SKILL_Tutores.md`).
+
+## Permissões (RBAC)
+Menu odonto: `dashboard, agenda, ortodontia, proteses, tratamentos, clinicas, configuracoes,
+candidatura-tutor, diretorio-profissionais` (+ RX e tutoria-painel conforme plugin/aprovação).
+**NÃO** vê telas administrativas globais nem `superadmin`.
+
+## Marketplace
+- Publica perfil no diretório de Profissionais (`profissionais/perfil`, nível pessoa via `authGuard`).
+- Recebe propostas de clínicas (`propostas_profissional`).
+- Pode locar/alugar salas (plugin `locacao-salas`).
+
+## Financeiro
+Gera comissão sobre procedimentos realizados (regra `comissao_regras`); recebe via Repasse.
+Ver `../FASE_04_FINANCEIRO/SKILL_Comissoes.md` e `SKILL_Repasses.md`.
+
+## Regras obrigatórias
+1. Identidade e capacidades na pessoa; papel no vínculo (multi-clínica nativo).
+2. Não duplicar a pessoa para representá-la em outra clínica — novo `vinculo`.
+3. `dentistas` é recurso de agenda, não fonte de identidade.
+
+## Anti-padrões
+- ❌ Hardcodar permissão por e-mail. ❌ Criar identidade do dentista fora de `usuarios`.
+
+```mermaid
+flowchart LR
+  D[Dentista · usuarios] --> V[vinculo role=dentista]
+  V --> AG[Agenda] --> PR[Procedimento] --> COM[Comissão→Repasse]
+  D --> MKT[Diretório/Propostas] 
+  D --> TUT[Tutoria orto]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_03_PESSOAS/SKILL_Pacientes.md

@@ -0,0 +1,41 @@
+# SKILL — Pacientes (Pessoa — com débito de modelagem)
+
+> Herda de `../FASE_01_ARQUITETURA/SKILL_Pessoa.md`. **Atenção:** estado atual contraria a arquitetura-alvo.
+
+## Perfil (estado real hoje)
+O paciente é registrado em `pacientes` com `clinica_id` e **sem `usuario_id`** — ou seja, **pertence à
+clínica**, não ao ecossistema. O mesmo CPF em 2 clínicas vira **2 registros** (sem prontuário único).
+Há resíduo legado: existem INSERTs com e sem `clinica_id`. Ver `../FASE_08_AUDITORIA/SKILL_Entidades.md`.
+
+## Fluxos
+- Origem: cadastro direto **ou** conversão de Lead (`leads/:id/converter` cria paciente + agendamento).
+- Agenda, Orçamento, Procedimentos, Ortodontia, RX, Receita/Exame, Score, Faltas, Família.
+
+## Permissões (RBAC)
+- Operadores (funcionário/donos) gerenciam pacientes da clínica ativa.
+- O **paciente-usuário** (papel `paciente`, quando existe login) vê só: `tratamentos, notificacoes, configuracoes`.
+
+## Privacidade / LGPD
+O modelo atual (paciente preso à clínica) **favorece isolamento** — cada clínica é controladora dos
+seus dados. Compartilhar histórico entre clínicas exigiria base legal/consentimento. **Não** presumir
+"paciente do ecossistema" sem decisão arquitetural + jurídica.
+
+## Marketplace / Financeiro
+Não participa de marketplace. É **origem de RECEITA** (procedimentos, contratos), nunca recebe repasse.
+
+## Regras obrigatórias
+1. Paciente sempre escopado por `clinica_id` (tenancy).
+2. **Não** unificar pacientes entre clínicas sem aprovação (impacto LGPD direto).
+3. Conversão de lead é anti-overbooking — preservar a checagem.
+
+## Anti-padrões / Débito
+- ⚠️ Falta de identidade de pessoa no paciente é o maior atrito com o modelo Pessoa→Workspace (gravidade ALTA).
+- ❌ Deduplicar/“mesclar” pacientes entre clínicas sem base legal.
+
+```mermaid
+flowchart LR
+  L[Lead] -->|converter| PAC[Paciente · clinica_id]
+  PAC --> AG[Agenda] --> PR[Procedimento] --> FIN[RECEITA]
+  PAC --> ORC[Orçamento] --> CON[Contrato]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_03_PESSOAS/SKILL_Proteticos.md

@@ -0,0 +1,42 @@
+# SKILL — Protéticos (Pessoa)
+
+> Herda de `../FASE_01_ARQUITETURA/SKILL_Pessoa.md`. **Não confundir** com o Laboratório (entidade/fornecedor):
+> ver `../FASE_02_NEGOCIO/SKILL_Laboratorios.md`.
+
+## Perfil
+Pessoa (`usuarios`) com vínculo `protetico` — profissional do laboratório. É **profissional do
+ecossistema** (modelo B da auditoria), não um "fornecedor" abstrato. O fornecedor é o **laboratório**.
+
+## Fluxos
+- Agenda própria + Próteses (OS de laboratório: `protese_os`, produtos, materiais, custo lab, entrega).
+- Lança GTO (guia de tratamento) quando aplicável.
+
+## Permissões (RBAC)
+Menu: `dashboard, agenda, proteses, tratamentos, lancar-gto, clinicas, notificacoes, configuracoes,
+diretorio-profissionais`. Sem Ortodontia/RX/pacientes clínicos.
+
+## Marketplace
+Perfil no diretório de Profissionais; propostas; salas (plugin).
+
+## Financeiro
+O **custo lab** das próteses **abate a base de comissão** do procedimento (entra em `computeComissoes`).
+Ver `../FASE_04_FINANCEIRO/SKILL_Comissoes.md`.
+
+## Conflito conceitual a vigiar (gravidade baixa)
+A faceta "fornecedor" pertence ao **laboratório** (cadastro `protese_laboratorios`), não à pessoa.
+Manter pessoa (protético) e laboratório (entidade) **separados e bem ligados**.
+
+## Regras obrigatórias
+1. Protético = pessoa/profissional; Laboratório = entidade/fornecedor. Não fundir.
+2. Custo lab consistente com Comissões.
+
+## Anti-padrões
+- ❌ Tratar o protético como cadastro de fornecedor (ou o laboratório como login).
+
+```mermaid
+flowchart LR
+  PT[Protético · usuarios] --> V[vinculo role=protetico]
+  V --> OS[Próteses/OS] --> CL[custo lab → Comissão]
+  PT -. usa .-> LAB[Laboratório · fornecedor]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_03_PESSOAS/SKILL_Secretarias.md

@@ -0,0 +1,34 @@
+# SKILL — Secretárias / Recepção (Pessoa)
+
+> Herda de `../FASE_01_ARQUITETURA/SKILL_Pessoa.md` e `SKILL_RBAC.md`.
+> **Importante:** no código **não existe role `secretaria`** — a secretária é o papel `funcionario`
+> (eventualmente com `funcao` customizada para refinar permissões).
+
+## Perfil
+Pessoa (`usuarios`) com vínculo `funcionario`. Opera o front-office da clínica (não-clínico).
+
+## Fluxos
+- Leads (captar/converter), Pacientes, Agenda, Financeiro, Orçamentos, Contratos, Relatórios, Glosas.
+
+## Permissões (RBAC)
+Menu padrão do `funcionario`: `dashboard, leads, pacientes, agenda, financeiro, tratamentos,
+lancar-gto, proteses, relatorios, glosas, orcamentos, contratos, clinicas, notificacoes, configuracoes,
+diretorio-profissionais`. Permissões podem ser **estreitadas por `funcao`** (RBAC fino) no workspace.
+
+## Marketplace / Financeiro
+Não participa de marketplace como profissional. Opera o financeiro da clínica, mas **não recebe comissão/repasse**.
+
+## Regras obrigatórias
+1. "Secretária" = papel `funcionario` + `funcao` opcional. Não criar role nova sem decisão arquitetural.
+2. Para restringir acesso, use **`funcao` com `permissoes[]`** (prevalece sobre o default do papel).
+
+## Anti-padrões
+- ❌ Inventar role `secretaria` no código (quebra a constraint `vinculos_role_check`).
+- ❌ Dar a funcionário telas de superadmin/admin global.
+
+```mermaid
+flowchart LR
+  S[Secretária · usuarios] --> V[vinculo role=funcionario + funcao]
+  V --> FO[Leads/Agenda/Pacientes/Financeiro]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_03_PESSOAS/SKILL_Tutores.md

@@ -0,0 +1,42 @@
+# SKILL — Tutores de Ortodontia (Pessoa)
+
+> Herda de `../FASE_01_ARQUITETURA/SKILL_Pessoa.md`. Única faceta com **receita de plataforma automatizada**.
+
+## Perfil
+Pessoa (`usuarios`) com flag `is_tutor=true` após **candidatura paga** (MercadoPago). Não é uma role de
+vínculo — é uma **capacidade da pessoa** (atributo), liberada pelo painel de tutoria.
+
+## Fluxos
+- Candidatura (`tutoria/candidaturas`) → pagamento (`preferences` MercadoPago) → `mp-webhook` ativa o tutor.
+- Tutor resolve solicitações de orto (`ortho_tutoring_request`), troca mensagens/pacotes de fotos.
+- Gestão pelo superadmin (`admin/candidaturas`, `admin/repasses`, `admin/tutor-config`).
+
+## Permissões (RBAC)
+- `candidatura-tutor`: disponível a dentistas.
+- `tutoria-painel`: **só para tutores aprovados** (`is_tutor`).
+- `admin-gestao-tutores`: **só superadmin**.
+
+## Marketplace / Financeiro (modelo de receita)
+- Configuração global em `ortho_tutor_config` (`comissao_pct`, default **20%**, `taxa_inscricao`, chave PIX,
+  credenciais MercadoPago).
+- Cada consultoria registra `valor_consultoria`, `comissao_pct`, `valor_tutor`, `status_repasse`.
+- **A plataforma fica com a comissão (`comissao_pct`)**; o tutor recebe `valor_tutor` (repasse próprio,
+  distinto do repasse de clínica em `../FASE_04_FINANCEIRO/SKILL_Repasses.md`).
+
+## Regras obrigatórias
+1. `is_tutor` é capacidade da pessoa — não criar role de vínculo "tutor".
+2. Pagamento via MercadoPago é idempotente (webhook). Não duplicar ativação.
+3. Repasse de tutoria é fluxo próprio (não confundir com repasse de comissão de clínica).
+
+## Anti-padrões
+- ❌ Ativar tutor sem confirmar pagamento (webhook/`confirmar-pagamento`).
+- ❌ Misturar `comissao_pct` da tutoria com `comissao_regras` da clínica.
+
+```mermaid
+flowchart LR
+  D[Dentista] --> CAND[Candidatura]
+  CAND -->|MercadoPago| WH[mp-webhook] --> T[is_tutor=true]
+  T --> REQ[Solicitações orto]
+  REQ --> $[valor_tutor + comissão plataforma]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_04_FINANCEIRO/SKILL_Assinaturas.md

@@ -0,0 +1,34 @@
+# SKILL — Assinaturas (da plataforma / SaaS)
+
+> Herda de `SKILL_Financeiro.md`. **Receita da PLATAFORMA** (não da clínica). Hoje é manual.
+
+## Conceito
+Assinatura é a relação de **cobrança da plataforma com a pessoa/conta** — a monetização do SaaS.
+**Distinta** de `contrato_assinaturas` (aceite de contratos da clínica). Não confundir.
+
+## Entidades / mecanismo real
+- `assinaturas(id, usuario_id, status, valor, validade, created_at)`.
+- Gestão pelo **superadmin**: `PUT /api/superadmin/assinaturas/:userId` (define status/valor/validade) e
+  `GET|PUT /api/superadmin/pricing` (tabela de preços).
+- **Estado atual: cobrança MANUAL** (superadmin define) — **não há gateway/recorrência automática**.
+
+## Receita
+É a alavanca de **receita recorrente da plataforma** mais direta (base multiempresa + pricing já existem),
+porém ainda não automatizada. Ver auditoria estratégica (`documentação/AUDITORIA-ESTRATEGICA-MODELAGEM.md`).
+
+## Regras obrigatórias
+1. Assinatura é **da pessoa/conta** (`usuario_id`), coerente com Pessoa→Workspace.
+2. Só `superadmin` gerencia (`superadminGuard`).
+3. Não confundir com assinatura de contrato nem com repasse.
+
+## Anti-padrões
+- ❌ Tratar `assinaturas` como assinatura de documento.
+- ❌ Assumir recorrência/gateway que não existe (cobrança é manual hoje).
+
+```mermaid
+flowchart LR
+  SA[superadmin] --> PRC[pricing]
+  SA --> ASS[assinaturas: usuario_id, status, valor, validade]
+  ASS -. falta .-> GW[(gateway/recorrência)]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_04_FINANCEIRO/SKILL_Comissoes.md

@@ -0,0 +1,38 @@
+# SKILL — Comissões
+
+> Herda de `SKILL_Financeiro.md`. Cálculo da remuneração do profissional sobre a produção.
+
+## Conceito
+Comissão = **(base − custo_lab) × percentual**. A base é a produção do profissional no período; o custo
+lab (próteses) é abatido antes do percentual.
+
+## Entidades / mecanismo real
+- `comissao_regras(id, clinica_id, procedimento_id, profissional_id, percentual, custo_lab)`.
+- Função `computeComissoes(pool, clinicaId, {inicio, fim, base, profissionalId})` agrega a produção.
+- Três níveis de regra (precedência): **override por profissional** > **por procedimento** > **padrão da clínica**.
+
+## Regras obrigatórias
+1. Custo lab **sempre abatido** antes do percentual.
+2. Lançamentos com `sem_comissao=true` (garantia/reabertura do mesmo profissional, despesa de repasse) **não entram**.
+3. Base configurável (produção × recebido) — respeitar o parâmetro `base`.
+4. Mudou regra de comissão → auditar impacto em Repasses (não recalcular repasses já fechados).
+
+## Fluxos
+Produção (`procedimentos_realizados` → `financeiro` RECEITA) → `computeComissoes` → **Repasse** (fechar).
+
+## Anti-padrões
+- ❌ Ignorar `custo_lab` no cálculo. ❌ Comissionar lançamento `sem_comissao`.
+- ❌ Alterar percentual e recalcular retroativamente repasses fechados (snapshot é imutável).
+
+## Permissões
+Definição de regras: donos/admin. Ver `../FASE_01_ARQUITETURA/SKILL_RBAC.md`.
+
+```mermaid
+flowchart LR
+  PROD[Produção do período] --> BASE[base]
+  LAB[custo_lab próteses] --> CALC
+  BASE --> CALC[(base − custo_lab) × %]
+  REG[comissao_regras: prof > proc > clínica] --> CALC
+  CALC --> REP[Repasse]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_04_FINANCEIRO/SKILL_Contratos.md

@@ -0,0 +1,36 @@
+# SKILL — Contratos
+
+> Herda de `SKILL_Financeiro.md`. Formalização de acordos (paciente/profissional ↔ clínica) e cobrança.
+
+## Conceito
+Contrato transforma um acordo (orçamento, remuneração, prestação) em documento com **modelo + variáveis +
+partes + assinaturas**, podendo **gerar cobrança** no financeiro.
+
+## Entidades / fluxo real
+- `contrato_modelos` (modelos com variáveis `{{...}}`, categorias: remuneração, prestação, etc.).
+- `contratos` / instâncias (`status`: rascunho → aguardando_assinatura → assinado → vigente → encerrado/cancelado).
+- `contrato_partes` (as partes do contrato) e `contrato_assinaturas` (aceite por parte: assinado_em, ip,
+  user_agent, hash) — **assinatura eletrônica de contrato** (≠ assinatura de plataforma, ver `SKILL_Assinaturas.md`).
+- Ações: `enviar` (cria assinaturas pendentes), `assinar`, `gerar-cobranca` (→ `financeiro`), `cancelar`, `duplicar`.
+
+## Variáveis de remuneração (já modeladas)
+`{{PERCENTUAL}}`, `{{PERCENTUAL_REPASSE}}`, `{{VALOR}}`, `{{BASE_REPASSE}}`, `{{PRAZO_REPASSE}}` — contratos
+de comissão/percentual referenciam o mesmo conceito de Repasse.
+
+## Regras obrigatórias
+1. Respeitar a máquina de estados (não pular rascunho→vigente sem assinatura).
+2. `gerar-cobranca` cria lançamento em `financeiro` (`origem='contrato'`, `contrato_id`).
+3. Assinatura grava trilha (ip/user_agent/hash) — não remover (valor probatório).
+
+## Anti-padrões
+- ❌ Confundir `contrato_assinaturas` (assinatura do documento) com `assinaturas` (mensalidade da plataforma).
+- ❌ Encerrar/cancelar sem auditoria.
+
+```mermaid
+flowchart LR
+  M[contrato_modelos] --> I[contratos: rascunho]
+  I --> E[enviar → assinaturas pendentes]
+  E --> A[assinar → assinado/vigente]
+  A --> COB[gerar-cobranca → financeiro]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_04_FINANCEIRO/SKILL_Faturamento.md

@@ -0,0 +1,49 @@
+# SKILL — Faturamento (visão consolidada do dinheiro)
+
+> Herda de `SKILL_Financeiro.md`. Mapa de **onde o dinheiro nasce, para onde vai e quem é o responsável.**
+
+## As três camadas de receita (estado real)
+1. **Receita da clínica** (operacional): produção de procedimentos, contratos/cobrança, recuperação de glosas.
+   Responsável: a clínica. Tabela: `financeiro` (RECEITA).
+2. **Receita do profissional** (repasse): comissão sobre a produção. Responsável: clínica paga; profissional recebe.
+   Tabelas: `comissao_regras` → `repasses` → `financeiro` (DESPESA).
+3. **Receita da plataforma**: (a) **Tutoria** — `comissao_pct` via MercadoPago (**automatizada**);
+   (b) **Assinaturas** — SaaS por conta (**manual**, sem gateway); (c) **Locação de salas** — `valor` na
+   reserva, **sem captura de pagamento** (lacuna).
+
+## Mapa origem → destino → responsável
+| Origem | Tabela | Destino | Responsável |
+|---|---|---|---|
+| Procedimento (RECEITA) | `financeiro` | caixa da clínica | Clínica |
+| Contrato (cobrança) | `financeiro` | caixa da clínica | Clínica |
+| Convênio − Glosa | `glosas`/`financeiro` | recupera receita | Clínica |
+| Comissão → Repasse pago | `repasses`→`financeiro` DESPESA | profissional | Clínica paga |
+| Tutoria | `ortho_tutoring_request` + MercadoPago | plataforma (`comissao_pct`) + tutor (`valor_tutor`) | Plataforma |
+| Assinatura SaaS | `assinaturas` | plataforma | Plataforma (manual) |
+| Locação de sala | `sala_reservas.valor` | locador | — (sem gateway) |
+
+## Regras obrigatórias
+1. Não misturar as três camadas: clínica ≠ profissional ≠ plataforma.
+2. Toda lacuna de captura (salas, assinaturas) deve ser **sinalizada, não presumida como paga**.
+3. Mudança em qualquer camada → mapear efeito nas demais antes (ver `../FASE_08_AUDITORIA/SKILL_Fluxos.md`).
+
+## Oportunidades (já mapeadas, não implementar aqui)
+- Gateway na **Locação de Salas** (receita mais próxima) e **recorrência das Assinaturas**.
+
+```mermaid
+flowchart TD
+  subgraph Clínica
+    PR[Procedimento] --> R[financeiro RECEITA]
+    CON[Contrato] --> R
+    R --> GL[Glosas]
+  end
+  subgraph Profissional
+    R --> COM[Comissão] --> REP[Repasse] --> D[financeiro DESPESA]
+  end
+  subgraph Plataforma
+    TUT[Tutoria · MercadoPago] --> PLT[comissao_pct + valor_tutor]
+    ASS[Assinaturas · manual] --> PLT
+    SAL[Salas · valor] -. falta gateway .-> PLT
+  end
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_04_FINANCEIRO/SKILL_Financeiro.md

@@ -0,0 +1,41 @@
+# SKILL — Financeiro (núcleo do caixa)
+
+> Herda de `../FASE_01_ARQUITETURA/SKILL_Multiempresa.md`. Tabela central do dinheiro: `financeiro`.
+
+## Conceito
+`financeiro` registra **RECEITA** e **DESPESA** da clínica (escopo `clinica_id`). É o caixa unificado de
+onde derivam comissões, repasses e glosas.
+
+## Entidades / colunas-chave (reais)
+`financeiro(id, clinica_id, descricao, valor, tipo['RECEITA'|'DESPESA'], status['Pago'|'Pendente'|...],
+formapagamento, datavencimento, data_competencia, pago_em, paciente_id, profissional_id, procedimento_id,
+agendamento_id, realizado_id, contrato_id, origem, centro_custo, fornecedor, sem_comissao, deleted_at)`.
+
+## Origens (origem=...)
+- `procedimento` — gerado ao lançar Procedimento Realizado (RECEITA, se `valor>0`).
+- `contrato` — cobrança de contrato (`gerar-cobranca`).
+- `repasse` — DESPESA ao pagar repasse (`centro_custo='COMISSÕES'`, `sem_comissao=true`).
+- Lançamento manual (avulso) — RECEITA/DESPESA direto na tela.
+
+## Regras obrigatórias
+1. Todo lançamento carrega `clinica_id` e `tipo`.
+2. **`sem_comissao`** marca o que NÃO deve gerar repasse (garantia, despesa de repasse).
+3. **`deleted_at`** = soft-delete (estorno reversível). Nunca DELETE físico de lançamento conciliado.
+4. RECEITA de procedimento é **opcional** (`valor>0` e `gerarLancamento!==false`) — alterar muda o caixa.
+
+## Fluxos a jusante
+RECEITA → base de **Comissão**; DESPESA de repasse fecha o ciclo. Recebíveis de convênio → **Glosas**.
+
+## Anti-padrões
+- ❌ Apagar lançamento fisicamente. ❌ Lançar sem `clinica_id`/`tipo`.
+- ❌ Recriar comissão a partir de despesa de repasse (use `sem_comissao`).
+
+```mermaid
+flowchart LR
+  PR[Procedimento] -->|origem=procedimento| R[financeiro RECEITA]
+  CON[Contrato] -->|gerar-cobranca| R
+  RP[Repasse pago] -->|origem=repasse| D[financeiro DESPESA]
+  R --> COM[Comissão]
+  R --> GL[Glosas]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_04_FINANCEIRO/SKILL_Repasses.md

@@ -0,0 +1,35 @@
+# SKILL — Repasses
+
+> Herda de `SKILL_Comissoes.md`. Fechamento e pagamento da comissão ao profissional.
+
+## Conceito
+Repasse é o **snapshot imutável** da comissão de um profissional num período, que vira **DESPESA** quando pago.
+
+## Entidades / fluxo real
+- `repasses(id, clinica_id, profissional_id, inicio, fim, base, base_valor, custo_lab_total,
+  comissao_valor, qtd_lancamentos, detalhes(JSON), status['fechado'|'pago'|'cancelado'], pago_em,
+  financeiro_id, comprovante_*)`.
+- `POST /repasses/fechar` → calcula via `computeComissoes` e grava `status='fechado'` (snapshot em `detalhes`).
+- `POST /repasses/:id/pagar` → cria `financeiro` DESPESA (`origem='repasse'`, `centro_custo='COMISSÕES'`,
+  `sem_comissao=true`) e marca `status='pago'` + `financeiro_id`.
+- `POST /repasses/:id/cancelar` → se estava pago, **estorna** a DESPESA (soft-delete) e zera `financeiro_id`.
+- Comprovante: `POST /repasses/:id/comprovante`.
+
+## Regras obrigatórias
+1. Só paga repasse **fechado**. O snapshot (`detalhes`) é **imutável** após fechar.
+2. DESPESA de repasse nasce com `sem_comissao=true` (não recomissionar).
+3. Cancelamento é **reversível** (estorno por soft-delete) — preservar.
+4. Toda transição registra `audit_log` (`registrarAudit`). Manter.
+
+## Anti-padrões
+- ❌ Editar valores de um repasse fechado (refazer = cancelar + novo fechamento).
+- ❌ Pagar sem gerar a DESPESA correspondente (quebra a conciliação).
+
+```mermaid
+flowchart LR
+  COM[Comissão do período] --> F[fechar → repasses status=fechado]
+  F --> P[pagar → financeiro DESPESA]
+  P --> C{cancelar?}
+  C -->|sim| EST[estorna DESPESA soft-delete]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_05_UIUX/SKILL_Acessibilidade.md

@@ -0,0 +1,25 @@
+# SKILL — Acessibilidade
+
+> Base mínima de a11y, sem regredir a identidade visual. Pragmático para o estado atual.
+
+## Estado atual (honesto)
+O app prioriza densidade/visual; a11y é **básica**. Esta skill fixa o mínimo a manter/melhorar sem
+quebrar o design.
+
+## Regras obrigatórias
+1. **Contraste**: texto sobre a cor de marca deve ser legível (a marca é escura → texto branco). Evitar
+   cinza-claro sobre branco em informação essencial.
+2. **Alvos de toque** no mobile ≥ ~40px (os botões do bottom nav/menu já respeitam).
+3. **Foco**: usar `focus:ring-brand` (já existe) em controles interativos; não remover outline sem substituto.
+4. **Semântica**: `<button>` para ação, `<a>` para navegação; ícone-só precisa de `aria-label`/título.
+5. **Estados**: feedback de loading/disabled (`disabled:opacity-60`) e toasts para resultado de ação.
+
+## Como auditar
+```bash
+grep -rnE "onClick" frontend/views/<View>.tsx | grep -ivE "aria-label|title|>.*<"   # ícones-botão sem rótulo
+```
+
+## Anti-padrões
+- ❌ Remover outline de foco sem alternativa. ❌ Ícone clicável sem rótulo acessível.
+- ❌ Texto essencial com contraste insuficiente. ❌ Sacrificar a identidade visual aprovada por a11y (equilibrar).
+</content>

ScoreOdonto_Skills_Enterprise/FASE_05_UIUX/SKILL_Containers.md

@@ -0,0 +1,39 @@
+# SKILL — Containers & Identidade Visual (REGRA RÍGIDA)
+
+> Herda de `SKILL_DesktopWidth.md`. Preservar a identidade visual aprovada. **Não inventar design.**
+
+## Padrão real de container (não regredir)
+- **Wrapper de página:** `max-w-7xl mx-auto` + `p-4 md:p-8` (definido em `App.tsx`).
+- **Cards:** fundo branco, bordas suaves (`border-gray-200`), cantos arredondados (`rounded-xl`/`2xl`),
+  sombra leve. Tipografia de rótulo em caixa-alta, peso forte (`font-bold/black uppercase` em labels/menus).
+- **Sidebar:** `w-64`, branca, item ativo pintado com a **cor de marca**.
+
+## Cor de marca (token oficial — NÃO hardcodar)
+- Variável CSS `--brand-color`, vinda de `activeWorkspace.cor` (default `#2563eb`; superadmin `#dc2626`).
+- Classes utilitárias existentes: `bg-brand`, `text-brand`, `border-brand`, `hover:bg-brand`, `focus:ring-brand`.
+- **Sempre** usar o token/classe de marca para realce — nunca cravar um hex novo.
+
+## Regras obrigatórias
+1. **Preservar cores, estilos e identidade visual** aprovados — alterações visuais exigem aprovação.
+2. Realce/seleção usa **a cor do workspace** (`--brand-color`), não cor fixa.
+3. Reutilizar componentes existentes (`PageHeader`, `Toast`, `StackModal`, `EmptyState`, `Header`) — não recriar.
+4. Espaçamento e raio consistentes com o resto do app (não introduzir novo sistema de spacing).
+
+## Anti-padrões
+- ❌ Hardcodar `#2563eb` (ou qualquer hex) em vez de `var(--brand-color)`/classes `*-brand`.
+- ❌ Criar um novo "design system" paralelo ou trocar a tipografia/raio/sombra padrão.
+- ❌ Container de página fora do `max-w-7xl mx-auto`.
+- ❌ Recriar modal/toast/header quando já existe componente.
+
+## Validação
+- A tela nova é **indistinguível em estilo** das telas existentes? Se não, parar.
+- Trocar de workspace muda o realce conforme a cor da clínica? (token funcionando)
+
+```mermaid
+flowchart TD
+  WS[workspace.cor] --> VAR[--brand-color]
+  VAR --> BR[classes *-brand / realces]
+  COMP[Componentes existentes] --> UI[Tela consistente]
+  WRAP[max-w-7xl mx-auto] --> UI
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_05_UIUX/SKILL_Dashboard.md

@@ -0,0 +1,22 @@
+# SKILL — Dashboard
+
+> Tela inicial por papel. Herda de `SKILL_GridSystem.md` + `SKILL_DesktopWidth.md`.
+
+## O que é
+Visão consolidada (KPIs) de entrada. Dados via `GET /api/dashboard/stats`. View: `views/Dashboard.tsx`.
+Cada papel tem seu ponto de entrada (`getDefaultViewForRole`): superadmin → overview; sala → painel da sala;
+paciente → tratamentos; demais → dashboard.
+
+## Padrão de layout (real)
+- KPIs em grid `grid-cols-2 md:grid-cols-4` (cards compactos), dentro do wrapper `max-w-7xl mx-auto`.
+- Realce com a cor do workspace; números grandes + rótulo caixa-alta.
+
+## Regras obrigatórias
+1. KPIs vêm do backend (`/api/dashboard/stats`) — não recalcular no cliente de forma divergente.
+2. Respeitar o teto de largura (`max-w-7xl`) e o grid mobile-first (ver GridSystem).
+3. Conteúdo do dashboard segue o papel/permissões (não mostrar KPI que o papel não pode ver).
+
+## Anti-padrões
+- ❌ Dashboard full-width esticado. ❌ KPI financeiro para papel sem acesso a financeiro.
+- ❌ Recriar cards fora do padrão visual.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_05_UIUX/SKILL_DesignSystem.md

@@ -0,0 +1,29 @@
+# SKILL — Design System (REGRA RÍGIDA)
+
+> Tokens e padrões visuais REAIS do app. **Preservar a identidade aprovada. Não inventar.**
+> Herda de `SKILL_Containers.md`.
+
+## Stack
+React 19 + **Tailwind 4** + lucide-react (ícones). Sem biblioteca de componentes externa.
+
+## Cor de marca (token oficial)
+- `--brand-color` ← `activeWorkspace.cor` (default `#2563eb`; superadmin `#dc2626`).
+- Classes utilitárias: `bg-brand`, `text-brand`, `border-brand`, `hover:bg-brand`, `focus:ring-brand`.
+- **Sempre** o token/classe — nunca um hex novo cravado.
+
+## Tipografia & forma (observado)
+- Rótulos/menus/badges: **caixa-alta**, peso forte (`font-bold`/`font-black uppercase`, `tracking`).
+- Cantos arredondados (`rounded-xl`/`2xl`), bordas suaves (`border-gray-200`), sombra leve.
+- Ícones lucide-react com tamanho consistente (`size={16..22}`).
+
+## Componentes a reutilizar (não recriar)
+`PageHeader`, `Header`, `Sidebar`, `Toast`/`ToastContainer`, `StackModal`, `EmptyState`, `ConfirmContext`(`useConfirm`), `ToothIcon`.
+
+## Regras obrigatórias
+1. Realce/seleção usa a cor do workspace (`--brand-color`).
+2. Reutilizar os componentes acima; modal/toast/confirm já existem.
+3. Manter spacing/raio/sombra consistentes — não introduzir novo sistema.
+
+## Anti-padrões
+- ❌ Hex hardcoded. ❌ Novo design system paralelo. ❌ Recriar modal/toast/header. ❌ Trocar tipografia/raio padrão.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_05_UIUX/SKILL_DesktopWidth.md

@@ -0,0 +1,44 @@
+# SKILL — Desktop Width (REGRA RÍGIDA)
+
+> Objetivo desta skill: **impedir que qualquer agente estique divs, quebre o desktop ou invente layout.**
+> Tudo abaixo reflete a convenção REAL do código (`frontend/App.tsx`, Tailwind 4). Não inventar valores.
+
+## Regra de ouro
+**O conteúdo de toda página vive dentro do wrapper canônico:**
+```
+<div className="max-w-7xl mx-auto"> ... </div>
+```
+Esse wrapper já existe globalmente em `App.tsx` (a área de conteúdo é `max-w-7xl mx-auto` com `p-4 md:p-8`).
+`max-w-7xl` = **1280px** centralizado. **NUNCA** remover, sobrepor ou furar esse limite.
+
+## Regras obrigatórias
+1. **PROIBIDO `w-screen`, `100vw`, `max-w-none` ou `max-w-full`** em containers de página no desktop.
+2. **PROIBIDO full-width**: nada de conteúdo encostando nas bordas da viewport em telas largas.
+3. **Largura máxima de conteúdo = `max-w-7xl` (1280px)**, centralizado com `mx-auto`. É o padrão do app.
+4. Subseções podem ser mais estreitas (`max-w-2xl`, `max-w-3xl`, `max-w-md` para formulários) — **nunca mais largas** que o wrapper.
+5. **Sidebar fixa `w-64` (256px)** — não alterar sem auditoria de UX.
+6. Em ultrawide (>1280px) a sobra vira **margem lateral** (centralização), nunca esticão de conteúdo.
+
+## Padrão real observado (não regredir)
+- Wrapper de página: `max-w-7xl mx-auto` + `p-4 md:p-8`.
+- Larguras de cards/formulários: `max-w-md / 2xl / 3xl` conforme densidade.
+- Breakpoints usados: `sm:` `md:` `lg:` (o `xl:` é raro — **não** introduzir layouts dependentes de `xl/2xl` sem necessidade).
+
+## Anti-padrões (o que QUEBRA o desktop)
+- ❌ Trocar `max-w-7xl` por `max-w-full`/`w-full` no nível da página.
+- ❌ Criar grids que se expandem indefinidamente em telas largas.
+- ❌ Remover o `mx-auto` (conteúdo cola à esquerda).
+- ❌ Inventar nova paleta/identidade (ver Containers/DesignSystem).
+
+## Validação obrigatória antes de entregar
+- Conferir em **desktop largo** (≥1920px): conteúdo centralizado, margens laterais, sem esticão.
+- Conferir em **mobile**: `p-4`, coluna única, sem overflow horizontal.
+
+```mermaid
+flowchart LR
+  V[Viewport larga] --> M1[margem]
+  V --> C[max-w-7xl · 1280px · mx-auto]
+  V --> M2[margem]
+  C --> CONT[Conteúdo da página]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_05_UIUX/SKILL_GridSystem.md

@@ -0,0 +1,40 @@
+# SKILL — Grid System (REGRA RÍGIDA)
+
+> Herda de `SKILL_DesktopWidth.md`. Layout responsivo **mobile-first**, como já feito no app.
+
+## Padrão real (não regredir)
+O app é **mobile-first**: começa em coluna única e cresce por breakpoint. Convenção observada:
+```
+grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3   (cards/listas)
+grid grid-cols-2 md:grid-cols-4                   (KPIs/contadores)
+```
+Breakpoints em uso: `sm:` `md:` `lg:` (predominantes); `xl:` é raro — **não** depender dele.
+
+## Regras obrigatórias
+1. **Mobile-first sempre:** definir o estado base (1 coluna) e escalar com `md:`/`lg:`.
+2. **Teto de colunas em `lg:`** (até `lg:grid-cols-4`). Não criar grids que multiplicam colunas em ultrawide.
+3. Usar `gap-*` consistente com o app; não misturar grid com float/posicionamento absoluto para layout.
+4. Tabelas largas: scroll interno (`overflow-x-auto`), **nunca** estourar o `max-w-7xl`.
+5. Formulários: largura contida (`max-w-md/2xl`) e centralizada, não full-width.
+
+## Casos de uso
+- Dashboard de KPIs: `grid-cols-2 md:grid-cols-4`.
+- Lista de cards: `grid-cols-1 md:grid-cols-2 lg:grid-cols-3`.
+- Form de cadastro: `max-w-2xl mx-auto`.
+
+## Anti-padrões
+- ❌ `grid-cols-6`/`grid-cols-12` que esticam em telas largas sem teto.
+- ❌ Layout que só foi testado em desktop (quebra no mobile).
+- ❌ Conteúdo de grid ultrapassando o wrapper `max-w-7xl`.
+- ❌ Introduzir dependência de `xl:`/`2xl:` para o layout funcionar.
+
+## Validação
+- Mobile (1 coluna, sem overflow), tablet (`md:`), desktop (`lg:`), ultrawide (centralizado, sem esticão).
+
+```mermaid
+flowchart LR
+  B[grid-cols-1 · base/mobile] --> M[md:grid-cols-2/3]
+  M --> L[lg:grid-cols-3/4 · TETO]
+  L --> X[ultrawide: centraliza, não estica]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_05_UIUX/SKILL_Responsividade.md

@@ -0,0 +1,23 @@
+# SKILL — Responsividade (REGRA RÍGIDA)
+
+> Mobile-first, como o app já é. Herda de `SKILL_GridSystem.md`.
+
+## Padrão real (não regredir)
+- **Mobile-first**: estado base = mobile; cresce com `sm:`/`md:`/`lg:` (uso: `sm:`≈238, `md:`≈186, `lg:`≈100; `xl:` raro≈8).
+- **Sidebar**: `w-64` fixa no desktop; off-canvas no mobile (drawer com overlay `bg-black/50 md:hidden`).
+- **Bottom nav mobile** por papel (`BOTTOM_TABS` em `App.tsx`) com `+ Mais`.
+- Padding de página `p-4 md:p-8`; safe-area no bottom nav (`env(safe-area-inset-bottom)`).
+
+## Regras obrigatórias
+1. Toda tela nova **funciona no mobile** (coluna única, sem overflow horizontal) E no desktop.
+2. Não depender de `xl:`/`2xl:` para o layout funcionar.
+3. Sidebar drawer no mobile; conteúdo dentro de `max-w-7xl mx-auto`.
+4. Tabelas largas → `overflow-x-auto` (scroll interno), nunca estourar o container.
+
+## Validação (obrigatória antes de entregar)
+- Mobile (≤640): 1 coluna, sem scroll horizontal, bottom nav ok.
+- Tablet (`md`), Desktop (`lg`), Ultrawide (centraliza, sem esticar).
+
+## Anti-padrões
+- ❌ Testar só no desktop. ❌ Overflow horizontal no mobile. ❌ Layout que quebra sem `xl:`.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_06_MODULOS/SKILL_Agenda.md

@@ -0,0 +1,28 @@
+# SKILL — Módulo Agenda
+
+> Coração operacional. RBAC: capability `'agenda'` (staff clínico, bloqueia paciente).
+
+## O que é
+Agendar/confirmar/remarcar consultas, controle de presença, anti-overbooking e pendências de reagendamento.
+
+## Entidades
+`agendamentos`, `agenda_presenca`, `agenda_pendencias`, `interesses_agenda`, `dentistas`+`dentistas_horarios`.
+
+## Rotas principais
+- `GET/POST /api/agendamentos`, `PUT/DELETE /api/agendamentos/:id`
+- Ações `/:id`: `confirmar`, `falta`, `remarcar`, `restaurar`, `reencaminhar`, `solicitar-avaliacao`
+- `GET/POST /api/agenda/presenca`, `GET /api/agenda/{pendencias,atividade}`, `POST /api/agenda/pendencias/:id/resolver`
+- `POST /api/agenda/importar-google`, horários: `GET /api/dentistas/:id/horarios`, `POST/DELETE /api/dentistas/horarios`
+
+## Regras de negócio (reais)
+- **Anti-overbooking**: checa conflito ANTES de criar (ex.: conversão de lead não cria paciente se o slot está ocupado).
+- **Falta** abre pendência e impacta o **score** do paciente.
+- **Presença/confirmação** libera o lançamento financeiro a jusante.
+- Tempo real via WebSocket (`wsBroadcast('agenda', ...)`) → refetch instantâneo na clínica.
+
+## Impactos a jusante
+Procedimento realizado → Financeiro → Comissão. Integra Google Calendar (importar).
+
+## Anti-padrões
+- ❌ Remover a checagem de overbooking. ❌ Mutação de agenda sem `registrarAudit`. ❌ Expor agenda ao paciente.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_06_MODULOS/SKILL_CRM.md

@@ -0,0 +1,28 @@
+# SKILL — Módulo CRM (Leads)
+
+> Topo do funil comercial. RBAC: capability `'leads'` (funcionário + dono).
+
+## O que é
+Captar interessados e **converter** em paciente + agendamento (início do ciclo clínico).
+
+## Entidades
+`leads` (status: Novo|Convertido|Arquivado), `interesses_agenda`, gera `pacientes` + `agendamentos`.
+
+## Rotas
+`GET/POST /api/leads`, `POST /api/leads/:id/converter`. Origem pública: `PublicContactForm`/`/api/interesses`.
+
+## Regra de negócio central (verificada)
+`POST /api/leads/:id/converter`:
+1. valida que o lead não foi convertido (409 se já foi);
+2. checa **anti-overbooking** do slot ANTES de criar (evita paciente órfão);
+3. cria o **paciente**; 4) cria o **agendamento** inicial (se slot válido e livre).
+
+## Impactos a jusante
+Paciente → Agenda → atendimento → Financeiro.
+
+## Oportunidade (do mapa funcional)
+CRM é a entrada; integrar com WhatsApp/origem de marketing é alavanca de crescimento (hoje básico).
+
+## Anti-padrões
+- ❌ Converter sem anti-overbooking. ❌ Duplicar paciente na reconversão. ❌ Expor leads a papel clínico/paciente.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_06_MODULOS/SKILL_Documentos.md

@@ -0,0 +1,25 @@
+# SKILL — Módulo Documentos (Receitas, Exames, Contratos, Mídia)
+
+> Geração e guarda de documentos clínicos/jurídicos e mídia. Cruza Prontuário e Contratos.
+
+## O que é
+Receitas, pedidos de exame, contratos (com assinatura eletrônica) e arquivos (fotos, comprovantes, PDFs).
+
+## Entidades
+`modelos_receita`/`items_receita`, `pedidos_exame`/`items_pedido_exame`,
+`contratos`/`contrato_modelos`/`contrato_partes`/`contrato_assinaturas`, e fotos por entidade
+(`*_foto`). PDFs no frontend via `jspdf`.
+
+## Acesso à mídia (padrão real)
+Arquivos são servidos por **URL assinada**: `/api/.../raw?t=signMedia(id)` — sem token de sessão.
+A URL só é entregue a quem já passou pelo guard da listagem. **Não** gatear o `/raw` por capability
+(quebraria a imagem); a proteção é o token assinado + a lista gateada.
+
+## Contratos (assinatura)
+`contrato_assinaturas` grava trilha probatória (ip, user_agent, hash do corpo). É **registro de aceite** —
+não remover. Capability `'contratos'` (funcionário+dono). Ver `../FASE_04_FINANCEIRO/SKILL_Contratos.md`.
+
+## Anti-padrões
+- ❌ Servir mídia sem URL assinada. ❌ Gatear `/raw` por capability. ❌ Apagar trilha de assinatura.
+- ❌ Confundir assinatura de contrato (`contrato_assinaturas`) com assinatura de plataforma (`assinaturas`).
+</content>

ScoreOdonto_Skills_Enterprise/FASE_06_MODULOS/SKILL_Prontuario.md

@@ -0,0 +1,28 @@
+# SKILL — Módulo Prontuário (Paciente + Ortodontia)
+
+> O histórico clínico do paciente. Detalhes acessíveis a staff clínico (capability `'agenda'`).
+
+## O que é
+Prontuário do paciente: dados, família, score, faltas, procedimentos realizados, receitas, pedidos de exame,
+e o tratamento **ortodôntico** completo.
+
+## Entidades
+`pacientes`, `procedimentos_realizados`(+foto), `modelos_receita`/`items_receita`, `pedidos_exame`/`items_pedido_exame`,
+`avaliacoes`/`avaliacao_foto`; **orto**: `ortho_tratamento`, `ortho_evolucao`, `ortho_photo`(+session/annotation).
+
+## Rotas
+`GET/POST/PUT /api/pacientes[...]`, `GET /api/pacientes/:id/{score,faltas,familia}`,
+`GET/POST /api/orto/tratamentos[/:id/{evolucoes,finalizar}]`, `/api/orto/{sessoes,fotos}`, `/api/avaliacoes`.
+
+## Regras de negócio
+- **Ortodontia** tem triagem, diagnóstico, plano, evoluções, fotos e contenção (vide `frontend/types.ts`).
+- `procedimentos_realizados` gera RECEITA (opcional por valor) e alimenta comissão.
+- **`OrthoView` (dentista) cria/edita paciente** → por isso o cap de mutação de paciente é `'agenda'` (clínico), não `'pacientes'`.
+
+## Privacidade/LGPD
+Paciente é **da clínica** (escopo `clinica_id`), não do ecossistema. Não compartilhar histórico entre clínicas
+sem base legal — ver `../FASE_03_PESSOAS/SKILL_Pacientes.md`.
+
+## Anti-padrões
+- ❌ Vazar prontuário entre clínicas. ❌ Gatear mutação de paciente a `'pacientes'` (bloquearia o dentista do Ortho).
+</content>

ScoreOdonto_Skills_Enterprise/FASE_06_MODULOS/SKILL_Proteses.md

@@ -0,0 +1,25 @@
+# SKILL — Módulo Próteses / GTO
+
+> Controle de laboratório. Liga-se à Comissão pelo **custo lab**. Ver `../FASE_03_PESSOAS/SKILL_Proteticos.md`.
+
+## O que é
+Ordens de Serviço de prótese (produto, dentes, material, custo lab, prazo, entrega) e GTO (guia de tratamento).
+
+## Entidades
+`protese_os`, `protese_os_evento`, `protese_os_foto`, `protese_produtos`, `protese_laboratorios`;
+GTO legado: `gto_builders`/`gto_items`, `guias_odontologicas`.
+
+## Rotas
+`GET/POST /api/protese/os`, `GET /api/protese/os/:id`, `POST /api/protese/os/:id/{status,foto}`,
+`GET/POST/PUT/DELETE /api/protese/produtos`, `GET /api/protese/laboratorios[/:id/produtos]`, `GET /api/protese/bancada`.
+
+## Regra de negócio central
+O **custo lab** da prótese **abate a base de comissão** do procedimento (`computeComissoes` =
+`(base − custo_lab) × %`). Mexer aqui afeta o repasse — ver `../FASE_04_FINANCEIRO/SKILL_Comissoes.md`.
+
+## Papéis
+Protético (pessoa, profissional do ecossistema) opera; laboratório = fornecedor (cadastro hoje).
+
+## Anti-padrões
+- ❌ Alterar custo lab sem considerar o efeito na comissão. ❌ Confundir protético (pessoa) com laboratório (fornecedor).
+</content>

ScoreOdonto_Skills_Enterprise/FASE_06_MODULOS/SKILL_Radiologia.md

@@ -0,0 +1,24 @@
+# SKILL — Módulo Radiologia (RX)
+
+> Plugin `rx-scoreodonto`. Radiografias são ODONTOLÓGICAS (papéis odonto, não bio/protético).
+
+## O que é
+Captura/gestão de radiografias e dos dispositivos (PCs/sensores) por clínica. Integra com o produto externo
+**rx.scoreodonto.com** (server + client.exe) — ver `documentos-unicos/projetos/rx.scoreodonto.com*`.
+
+## Rotas
+`GET /api/rx/{config,devices,images,patients,health}`, `PUT /api/rx/config`, `POST /api/rx/devices`.
+Views: `plugins/RXPlugin.tsx` (RX/Radiografias), `RxConfigView` (Dispositivos RX).
+
+## Permissões (do Sidebar real)
+- **RX/Radiografias**: dentista + donos/funcionário (papéis odonto). **Biomédico e protético NÃO veem RX.**
+- **Dispositivos RX**: admin/donos + superadmin.
+- Requer o plugin `rx-scoreodonto` ativo na conta.
+
+## Integração
+O RX é um sistema próprio (auto-update do client via `/updates/latest.yml`) — **não quebrar** esse mecanismo.
+Aqui é só a ponte (config/devices/images) dentro do ScoreOdonto.
+
+## Anti-padrões
+- ❌ Expor RX a biomédico/protético. ❌ Acoplar a lógica do client.exe aqui. ❌ Mexer no `/updates/` do RX por engano.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_06_MODULOS/SKILL_Tutoria.md

@@ -0,0 +1,26 @@
+# SKILL — Módulo Tutoria de Ortodontia
+
+> **Única receita de plataforma automatizada hoje** (MercadoPago). Ver `../FASE_03_PESSOAS/SKILL_Tutores.md`.
+
+## O que é
+Dentista vira **tutor** (pagando inscrição) e atende solicitações de orto de outros dentistas; a plataforma
+fica com uma comissão sobre a consultoria.
+
+## Entidades
+`ortho_tutor_config` (`comissao_pct` default 20, `taxa_inscricao`, chave PIX, credenciais MP),
+`ortho_tutor_profile`, `ortho_tutor_candidatura`, `ortho_tutoring_request`/`message`/`photo_package`.
+
+## Rotas
+`POST /api/tutoria/candidaturas[/:id/pagamento]`, `POST /api/tutoria/mp-webhook` (público),
+`GET/POST /api/tutoria/solicitacoes[...]`, admin: `/api/admin/{candidaturas,repasses,tutor-config}`.
+
+## Fluxo de receita (verificado)
+Candidatura → **MercadoPago** (`checkout/preferences`) → `mp-webhook` (idempotente) ativa `is_tutor` →
+solicitações registram `valor_consultoria`, `comissao_pct`, `valor_tutor`, `status_repasse`.
+
+## Permissões
+`candidatura-tutor` (dentistas), `tutoria-painel` (só tutores aprovados, `is_tutor`), `admin-gestao-tutores` (superadmin).
+
+## Anti-padrões
+- ❌ Ativar tutor sem confirmar pagamento. ❌ Misturar `comissao_pct` da tutoria com a comissão de clínica.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_07_INFRA/SKILL_BuildOnce.md

@@ -0,0 +1,33 @@
+# SKILL — Build Once → Promote → Deploy
+
+> Orientação de infra oficial. Fonte: `documentos-unicos/deploy/`. Implementação de referência: scoreodonto.com.
+
+## Conceito
+**Push** na `main` builda a imagem **uma vez** e publica por **commit** (`:<sha>` + `:latest`) — **sem deploy**.
+A **tag `vX.Y.Z`** **re-tagueia** essa MESMA imagem (mesmo digest, sem rebuild) e deploya. **Produção nunca builda.**
+
+## Garantia central
+A imagem em produção é **byte-idêntica** à que foi buildada e testada. A tag é só um rótulo de release
+sobre um artefato imutável. Validado em scoreodonto (`:v1.0.16` == `:471c2c2`, mesmo digest).
+
+## Fluxo real
+```
+PUSH main (commit C) → CI build 1x → publica :C + :latest        (NÃO deploya)
+TAG vX.Y.Z (em C)    → CI re-tag :C → :vX.Y.Z (sem rebuild) + deploy (up --no-build)
+```
+
+## Regras obrigatórias
+1. **Produção só executa imagem pronta** (`pull` + `up -d --no-build`). Nunca `build` na VPS1.
+2. **Tag exige commit já publicado** (push antes). Sem isso o CI **falha de propósito** (não builda na tag).
+3. Versão nasce da **tag git**, injetada em runtime (`APP_VERSION`), não escrita à mão.
+4. Push e tag exigem **autorização explícita do administrador**.
+
+## Anti-padrões
+- ❌ Buildar em produção. ❌ Tag sem push. ❌ Versão hardcoded em arquivo.
+
+```mermaid
+flowchart LR
+  PUSH[push main · commit C] --> B[CI build 1x] --> REG[registry :C + :latest]
+  TAG[tag vX.Y.Z] --> PROM[CI re-tag :C→:vX.Y.Z] --> DEP[VPS1 up --no-build]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_07_INFRA/SKILL_CICD.md

@@ -0,0 +1,32 @@
+# SKILL — CI/CD (Gitea Actions)
+
+> Herda de `SKILL_BuildOnce.md`. Automação de build/promote/deploy por evento git.
+
+## Conceito
+O pipeline roda no **Gitea Actions**, runner `vps4-builder` (VPS4, rootless, **instance-scoped** — atende
+todos os repos). Workflow: `.gitea/workflows/build.yml`.
+
+## Gatilhos reais
+- **Push na `main`** → job build: builda `scoreodonto-*:<sha>` e **publica no registry** (não deploya).
+- **Tag `v*`** → job promote/deploy: re-tag (digest idêntico) → `deploy-prod.sh` na VPS1.
+
+## Regras obrigatórias
+1. O runner builda; **produção só consome**. Não mover build para a VPS1.
+2. Segredos do CI vêm de **secrets do Gitea**, nunca commitados no repo. (Ver `⚠️ SKILL_PostgreSQL`/Registry.)
+3. Tag só promove se o commit já está no registry (senão falha proposital).
+4. Manter o pipeline idempotente e auditável (logs do run).
+
+## Pré-requisitos
+- Gitea Actions habilitado no repo; runner `vps4-builder` online; `docker login` no registry.
+- SSH VPS4→VPS1 para o passo de deploy (rsync/`deploy-prod.sh`).
+
+## Anti-padrões
+- ❌ Credencial em texto no `build.yml`. ❌ Deploy manual fora do pipeline sem registrar.
+- ❌ Pipeline que builda na tag (quebra o Build-Once).
+
+```mermaid
+flowchart LR
+  PUSH[push main] --> RUN[vps4-builder] --> REG[(registry)]
+  TAG[tag v*] --> RUN2[vps4-builder promote] --> SSH[VPS1 deploy-prod.sh]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_07_INFRA/SKILL_DeployImutavel.md

@@ -0,0 +1,33 @@
+# SKILL — Deploy Imutável & Rollback
+
+> Herda de `SKILL_BuildOnce.md`. Como promover e reverter sem rebuild.
+
+## Conceito
+O deploy troca **qual imagem** roda, não o código no servidor. Reverter = apontar para outra imagem.
+
+## Fluxo real
+- Promover: `deploy-prod.sh <tag>` na VPS1 → `pull` + `docker compose -f docker-compose.prod.yml up -d --no-build`.
+- `docker-compose.prod.yml` usa `image:` do registry, `APP_VERSION`/`GIT_COMMIT` em runtime.
+- Rollback: `deploy-prod.sh <ref-anterior>` (segundos/minutos, só troca imagem).
+
+## Regras obrigatórias
+1. **Referência confiável = commit (`:<sha>`)**. Tags antigas (pré-Build-Once) podem ter sido republicadas.
+2. **Migrações são aditivas** (`ADD COLUMN IF NOT EXISTS`) → voltar o código é seguro (schema extra fica inerte).
+3. **Backup do banco antes de release sensível** (container `pg_dump -Fc` → `/home/deploy/backups/`).
+4. Validar `/api/version` e `/api/health` após deploy.
+
+## Pré-requisitos de PROD (uma vez, por projeto)
+- Arquivo de segredos presente na VPS1 (env_file do compose) — **copiado manualmente, fora do git** (chmod 600).
+- `docker login git.clube67.com` na VPS1 (para o `pull`).
+
+## Anti-padrões
+- ❌ Reverter via rebuild. ❌ Migração destrutiva (DROP/ALTER que apaga) — quebra rollback.
+- ❌ Confiar em tag `:vX.Y.Z` como imutável se for anterior ao Build-Once.
+
+```mermaid
+flowchart LR
+  REG[(registry)] --> PULL[VPS1 pull :ref] --> UP[up -d --no-build]
+  UP --> CHK[/api/version + /api/health/]
+  CHK -->|quebrou| RB[deploy-prod.sh ref-anterior]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_07_INFRA/SKILL_DockerRootless.md

@@ -0,0 +1,34 @@
+# SKILL — Docker Rootless & Roteamento
+
+> Herda de `SKILL_DeployImutavel.md`. Como os containers rodam e são expostos.
+
+## Topologia real
+- **Rede privada WireGuard** `10.99.0.0/24`.
+- **VPS1 (produção):** Docker **rootless** — comandos usam `DOCKER_HOST=unix:///run/user/1000/docker.sock`.
+  Roda Traefik (borda TLS) + apps (scoreodonto, rx, newwhats, subdomínio, mercado).
+- **VPS4 (dev+builder):** Docker rootless; roda `dev.<projeto>` (imagem buildada, **não** HMR) + runner.
+- **Roteamento (Traefik na VPS1):** termina TLS e roteia por host:
+  `scoreodonto.com` → containers de produção locais; `dev.scoreodonto.com` → `10.99.0.4:8020` (VPS4) via WireGuard.
+
+## Regras obrigatórias
+1. Na VPS1, sempre exportar `DOCKER_HOST` rootless antes de comandos `docker`.
+2. Exposição pública **só via Traefik** (TLS `certresolver=le`); apps não publicam porta na internet.
+3. `dev.<projeto>` é descartável (VPS4); produção é a real (VPS1) — **confirmar DEV ou PROD antes de agir**.
+4. Editar dev exige **rebuild + recreate** (não há hot-reload no container atual).
+
+## ⚠️ Para abrir produção
+- Garantir que apenas Traefik exponha portas; conferir labels de roteador/host por app.
+- Rede WireGuard fechada; serviços de dados (VPS3) **nunca** expostos à internet.
+
+## Anti-padrões
+- ❌ `docker` na VPS1 sem `DOCKER_HOST` rootless. ❌ Publicar porta de app direto na internet.
+- ❌ Confundir `dev.` (VPS4) com produção (VPS1).
+
+```mermaid
+flowchart LR
+  NET[Internet] -->|TLS| TR[Traefik VPS1]
+  TR -->|host scoreodonto.com| APP[containers prod]
+  TR -->|host dev.*| WG[WireGuard → VPS4:8020]
+  APP --> DADOS[(VPS3 dados · só rede privada)]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_07_INFRA/SKILL_Gitea.md

@@ -0,0 +1,30 @@
+# SKILL — Gitea (código + registry + CI)
+
+> Herda de `SKILL_CICD.md`. A VPS3 concentra a "fonte da verdade" do código.
+
+## Papel real
+- **Código:** Gitea na **VPS3** é a fonte da verdade (repo `ruicesar/scoreodonto.com`).
+- **Registry:** Container Registry embutido do Gitea (ver `SKILL_Registry.md`).
+- **CI:** Gitea Actions + runner `vps4-builder` (ver `SKILL_CICD.md`).
+- Doc oficial da stack: repo `ruicesar/Documentos-Unicos` (local `documentos-unicos/`).
+
+## Regras obrigatórias
+1. **Nunca `git push --force` na `main`.** Push/tag exigem autorização do administrador.
+2. **Segredos via Gitea Secrets / webhooks**, nunca commitados.
+3. Idioma português em commits/docs (regra da stack).
+4. Webhooks/Actions antigos desligados não devem ser reativados sem auditoria.
+
+## ⚠️ Higiene de repositório (para abrir produção)
+- **Não versionar `.env`/segredos.** Hoje `backend/.env` está rastreado — corrigir e **rotacionar** as
+  credenciais expostas (ver `SKILL_PostgreSQL`). Confirmar `.gitignore` cobrindo `**/.env` e `.secrets`.
+
+## Anti-padrões
+- ❌ `push --force` na main. ❌ Commitar segredo. ❌ Reativar webhook legado sem auditoria.
+
+```mermaid
+flowchart LR
+  DEV[VPS4 dev] -->|push| GITEA[Gitea VPS3]
+  GITEA --> ACT[Actions · vps4-builder]
+  GITEA --> REG[(Registry)]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_07_INFRA/SKILL_PostGIS.md

@@ -0,0 +1,25 @@
+# SKILL — PostGIS (geolocalização)
+
+> Herda de `SKILL_PostgreSQL.md`. Extensão geoespacial usada por busca por proximidade.
+
+## Onde é usado (real)
+- Coluna `geo geography(Point,4326)` em `clinicas` e `salas` (e `cep_geo` para CEP→coordenada).
+- Suporta o **marketplace de salas** (achar salas próximas) e geocódigo de endereço.
+- O container `pgdev` é uma imagem **PostGIS** (dev espelha a capacidade da produção).
+
+## Regras obrigatórias
+1. Usar `geography(Point,4326)` (lat/long padrão) — não inventar SRID.
+2. Índice espacial (GIST) quando houver busca por distância em volume.
+3. Geocódigo (`cep_geo`) é cache — tratar ausência com fallback, não quebrar o cadastro.
+
+## Anti-padrões
+- ❌ Guardar lat/long como texto solto em vez de tipo geográfico.
+- ❌ Busca por proximidade sem índice (varredura completa).
+
+```mermaid
+flowchart LR
+  END[Endereço/CEP] --> GEO[cep_geo → ponto]
+  GEO --> SAL[salas.geo]
+  SAL --> PROX[busca por proximidade · marketplace]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_07_INFRA/SKILL_PostgreSQL.md

@@ -0,0 +1,32 @@
+# SKILL — PostgreSQL (dados)
+
+> Herda de `../FASE_01_ARQUITETURA/SKILL_Multiempresa.md`. Banco de produção e isolamento de dev.
+
+## Topologia real
+- **Produção:** PostgreSQL no host da **VPS3** (`10.99.0.3:5432`), banco `scoreodonto`, user `scoreodonto_user`.
+- **DEV isolado:** container **`pgdev`** (PostGIS) na VPS4, banco `scoreodonto_dev`, user `devadmin` —
+  **não toca produção**. `pg-dev-refresh.sh` / `pg-dev-reset.sh` para repuxar/limpar.
+- Acesso via WireGuard (`10.99.0.0/24`). Sem shell na VPS3 → operar por container (`pg_dump`/`pg_restore`).
+
+## Regras obrigatórias
+1. **Toda query operacional filtra `clinica_id`** (tenancy — ver Multiempresa).
+2. **Migrações aditivas** no boot (`CREATE TABLE/ADD COLUMN IF NOT EXISTS`). Nunca DROP/ALTER destrutivo.
+3. **Backup antes de release sensível**: `pg_dump -Fc` → `/home/deploy/backups/`.
+4. Testar migração arriscada **sempre em `pgdev`** antes da produção.
+
+## ⚠️ SEGREDOS (crítico para abrir produção)
+- **A senha do banco NÃO pode ficar em arquivo versionado nem como default em `docker-compose.yml`.**
+  Hoje há default hardcoded no compose (`SCOREO_DB_PASS:-...`) e `backend/.env` está **rastreado no git** —
+  isso vaza credenciais. Segredos devem vir de **env_file fora do git** (chmod 600) ou secrets do CI.
+- Rotacionar qualquer credencial que tenha entrado no histórico do git.
+
+## Anti-padrões
+- ❌ Query sem `clinica_id`. ❌ Migração destrutiva. ❌ Senha no compose/`.env` versionado.
+
+```mermaid
+flowchart LR
+  APP[Backend VPS1] -->|WireGuard| PG[(Postgres VPS3 · scoreodonto)]
+  DEVAPP[Backend DEV VPS4] --> PGDEV[(pgdev · scoreodonto_dev)]
+  PG --> BKP[/home/deploy/backups · pg_dump -Fc/]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_07_INFRA/SKILL_Registry.md

@@ -0,0 +1,25 @@
+# SKILL — Registry de Imagens
+
+> Herda de `SKILL_BuildOnce.md`. Onde os artefatos imutáveis vivem.
+
+## Conceito
+Registry = **Container Registry embutido do Gitea** (`git.clube67.com`, namespace `ruicesar/`).
+Não há `registry:2` separado. Imagens: `git.clube67.com/ruicesar/scoreodonto-{backend,frontend}:<tag>`.
+
+## Regras obrigatórias
+1. Imagem por **commit** (`:<sha>`) é a fonte; `:vX.Y.Z` é alias imutável do mesmo digest.
+2. `docker login git.clube67.com` na VPS1 (pull) e no runner (push) — credenciais via secrets, não no git.
+3. **Imagem enxuta**: `.dockerignore` deve excluir `node_modules`, `data/`, dumps, mídia pesada.
+   (Lição do RX: camadas grandes davam PUT 500/499 no registry.)
+4. Não sobrescrever uma tag de release com código diferente (quebra a imutabilidade).
+
+## Anti-padrões
+- ❌ Republicar `:vX.Y.Z` apontando para outro código. ❌ Empurrar imagem gigante (sem `.dockerignore`).
+- ❌ Guardar credencial do registry em arquivo versionado.
+
+```mermaid
+flowchart LR
+  RUN[runner build] -->|push :sha| REG[(Gitea Registry · ruicesar/)]
+  REG -->|pull :ref| VPS1[Produção]
+```
+</content>

ScoreOdonto_Skills_Enterprise/FASE_08_AUDITORIA/SKILL_APIs.md

@@ -0,0 +1,28 @@
+# SKILL — Auditoria de APIs
+
+> Como mapear e evoluir a API sem quebrar consumidores. Complementa `SKILL_Rotas.md`.
+
+## Realidade
+- **~277 rotas** REST `/api/*` num único `backend/server.js` (Express monolítico, ~516 KB). Sem camada de
+  controllers/services separada.
+- Guards: `authGuard` (identidade), `tenantGuard` (tenant), `requireCapability*` (cargo), `superadminGuard`.
+- Endpoints transversais: `GET /api/version`, `GET /api/health` (ver FASE_09); mídia por **URL assinada**
+  (`/raw?t=signMedia(...)`).
+- Frontend consome via `services/backend.ts` (`HybridBackend`/`apiFetch`).
+
+## Como auditar
+```bash
+grep -oE "app\.(get|post|put|delete|patch)\('[^']+" backend/server.js | sort -u   # todas as rotas
+grep -rn "API_URL}/<recurso>" frontend/services/backend.ts                         # consumidores
+```
+
+## Regras obrigatórias
+1. **Nunca** mudar o caminho/contrato de uma rota sem achar TODOS os consumidores (`services/backend.ts` + views).
+2. Toda rota nova: definir guard correto (identidade vs tenant vs cargo) — ver `SKILL_Permissoes.md`.
+3. Erros consistentes (`{ error }` / `{ success:false, message }` conforme o padrão vizinho).
+4. Rota que toca dado de clínica → `clinica_id` + `tenantGuard`.
+
+## Anti-padrões
+- ❌ Quebrar contrato sem mapear consumidores. ❌ Rota sensível sem guard de cargo.
+- ❌ Mídia sem token assinado. ❌ Inventar convenção de resposta diferente da do arquivo.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_08_AUDITORIA/SKILL_Banco.md

@@ -0,0 +1,27 @@
+# SKILL — Auditoria de Banco
+
+> Como inspecionar e mexer no banco sem quebrar. Herda de `../FASE_07_INFRA/SKILL_PostgreSQL.md`.
+
+## Realidade
+- **PostgreSQL** (PostGIS) na VPS3 (`10.99.0.3`), banco `scoreodonto`. ~70 tabelas acessadas por **SQL direto**
+  (`pg`), via helpers `buildInsert`/`buildUpdate`. **Prisma é vestigial** (4 modelos GTO legados).
+- DEV isolado: container `pgdev` (banco `scoreodonto_dev`). Mexer aqui tem zero impacto em produção.
+- **Migrações aditivas no boot**: blocos `CREATE TABLE IF NOT EXISTS` / `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`.
+
+## Regras obrigatórias
+1. **Só aditivo** (add tabela/coluna). Nunca DROP/ALTER destrutivo → quebra rollback (ver Deploy Imutável).
+2. **Toda query operacional filtra `clinica_id`** (tenancy).
+3. Validar migração arriscada **no `pgdev`** antes; **backup `pg_dump -Fc`** antes de release sensível.
+4. Sem shell na VPS3 → operar por container (`pg_dump`/`pg_restore`/`psql`).
+
+## Como auditar (via container, com creds do `.env`)
+```bash
+# tabelas e colunas
+grep -niE "CREATE TABLE IF NOT EXISTS|ADD COLUMN IF NOT EXISTS" backend/server.js
+# índices declarados
+grep -niE "CREATE INDEX" backend/server.js
+```
+
+## Anti-padrões
+- ❌ Migração destrutiva. ❌ Query sem `clinica_id`. ❌ Mexer direto na produção sem testar no `pgdev`/backup.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_08_AUDITORIA/SKILL_Botoes.md

@@ -0,0 +1,28 @@
+# SKILL — Auditoria de Botões
+
+> Como rastrear o que cada botão faz (rota → tabela → fluxo) antes de mexer. Base:
+> `documentação/MAPA-FUNCIONAL-COMPLETO.md` (Etapa 3).
+
+## Método
+Para cada botão: **rótulo → handler no front → método HTTP/rota → tabela impactada → fluxo a jusante**.
+
+## Exemplos reais (verificados)
+| Botão (tela) | Rota | Tabela | Próximo fluxo |
+|---|---|---|---|
+| Novo Agendamento (Agenda) | `POST /api/agendamentos` | `agendamentos` | Procedimento → Financeiro |
+| Confirmar Presença (Agenda) | `POST /api/agenda/presenca` | `agenda_presenca` | libera lançamento |
+| Lançar Procedimento (Pacientes) | `POST /api/procedimentos-realizados` | `procedimentos_realizados` (+`financeiro`) | Comissão → Repasse |
+| Fechar Repasse (Comissões) | `POST /api/repasses/fechar` | `repasses` | Pagar → DESPESA |
+| Gerar Contrato (Contratos) | `POST /api/contratos/instancias` | `contratos` | gerar-cobrança → Financeiro |
+| Converter (Leads) | `POST /api/leads/:id/converter` | `pacientes` + `agendamentos` | atendimento |
+
+## Como auditar
+```bash
+grep -oE ">[A-ZÀ-Ú][a-zà-úA-ZÀ-Ú /]{3,28}<" frontend/views/<View>.tsx   # rótulos
+# depois localize o onClick → método do HybridBackend → rota em services/backend.ts
+```
+
+## Anti-padrões
+- ❌ Alterar a ação de um botão sem mapear a tabela e o fluxo a jusante (sobretudo financeiro).
+- ❌ Botão que muta sem confirmação onde o padrão da tela usa `useConfirm`.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_08_AUDITORIA/SKILL_Entidades.md

@@ -0,0 +1,29 @@
+# SKILL — Auditoria de Entidades
+
+> Como verificar se as entidades estão bem classificadas. Herda de
+> `../FASE_01_ARQUITETURA/SKILL_ModelagemMestra.md`. Detalhe em `documentação/AUDITORIA-ESTRATEGICA-MODELAGEM.md`.
+
+## Entidades-âncora (corretas)
+- `usuarios` (Pessoa) · `vinculos(usuario_id, clinica_id, role, setor_id, funcao_id)` (Vínculo+RBAC)
+- `clinicas(tipo: pessoal|consultorio|clinica, owner_id)` + `salas(tipo='sala')` (Workspaces)
+- `usuario_areas`, `usuario_plugins`, `funcoes` (capacidades/cargo)
+
+## Débitos de modelagem (gravidade ALTA — vigiar)
+- **`dentistas`**: tabela paralela a `usuarios` (mesma pessoa duplicada por clínica, `usuario_id` opcional)
+  → tratar como **projeção de agenda**, não identidade.
+- **`pacientes`**: tem `clinica_id` e **não** `usuario_id` (preso à clínica, não-portável); há 2 variantes de
+  INSERT (com/sem `clinica_id`) — resíduo legado.
+- **MÉDIA**: workspace dividido em 2 tabelas (`clinicas` + `salas`); acoplamento role↔tipo (`donoconsultorio`).
+
+## Como auditar
+```bash
+grep -niE "CREATE TABLE" backend/server.js | sort           # tabelas reais (banco é SQL puro, Prisma vestigial)
+grep -oiE "(FROM|JOIN|INTO|UPDATE) [a-z_]+" backend/server.js | awk '{print $2}' | sort | uniq -c | sort -rn
+```
+Para cada entidade, pergunte: é **Pessoa**, **Vínculo**, **Workspace**, **capacidade** ou **dado operacional**?
+Se não encaixa, é candidata a má-classificação.
+
+## Anti-padrões
+- ❌ Criar tabela-entidade que espelha a pessoa por workspace (repetir o erro de `dentistas`).
+- ❌ Dado operacional sem `clinica_id`. ❌ Identidade fora de `usuarios`.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_08_AUDITORIA/SKILL_Fluxos.md

@@ -0,0 +1,47 @@
+# SKILL — Auditoria de Fluxos
+
+> Objetivo: ensinar a **mapear o fluxo de negócio ponta a ponta antes de alterar** — sobretudo o do dinheiro.
+> Regra Nº1: não quebrar o que funciona. Toda mudança em fluxo financeiro exige mapeamento prévio.
+
+## Fluxo principal (núcleo — verificado no código)
+```
+Lead ─converter→ Paciente + Agendamento ─presença→ Procedimento Realizado
+   → Financeiro RECEITA (origem='procedimento', flag sem_comissao)
+   → Comissão = (base − custo_lab) × %   [comissao_regras + computeComissoes]
+   → Repasse FECHADO → pagar → Financeiro DESPESA (origem='repasse', centro_custo='COMISSÕES')
+```
+Ramos: Orçamento → Contrato → `gerar-cobranca` → Financeiro; Glosas sobre recebíveis de convênio.
+
+## Pontos sensíveis (não quebrar)
+1. **RECEITA é opcional** no procedimento (`valor>0` e `gerarLancamento!==false`) — alterar isso muda o caixa.
+2. **`sem_comissao`** propaga garantia/reabertura e o repasse pago (evita recomissionar). Manter.
+3. **Repasse cancelado estorna** a despesa (soft-delete). Preservar a reversibilidade.
+4. **Anti-overbooking** na conversão de lead e na agenda — não remover a checagem.
+5. **Marketplace**: só Tutoria captura pagamento (MercadoPago); Salas tem `valor` sem gateway.
+
+## Como auditar um fluxo (comandos)
+```bash
+# Achar o handler de uma etapa
+grep -n "repasses/fechar\|procedimentos-realizados\|leads/:id/converter" backend/server.js
+# Ver o que cada etapa INSERE/ATUALIZA
+grep -nE "INSERT INTO (financeiro|repasses|procedimentos_realizados)" backend/server.js
+# Conferir auditoria
+grep -n "registrarAudit" backend/server.js | head
+```
+
+## Checklist antes de alterar um fluxo
+1. Onde começa, onde termina, o que cada etapa grava (tabela + colunas)?
+2. Há `audit_log` (`registrarAudit`) na etapa? Manter.
+3. A mudança afeta comissão/repasse/caixa? Mapear o impacto a jusante.
+4. Existe reversão (estorno/soft-delete)? Não quebrá-la.
+5. Validar em `dev.scoreodonto.com` com banco `pgdev` antes de qualquer promoção.
+
+## Anti-padrões
+- ❌ Alterar geração de RECEITA/DESPESA sem mapear o efeito em Comissões/Repasses.
+- ❌ Remover flags `sem_comissao`/`deleted_at` (quebram não-duplicação e estorno).
+- ❌ Mexer no fluxo sem reproduzir ponta a ponta em DEV.
+
+## Entregável
+Diagrama Mermaid do fluxo + tabela etapa→tabela→efeito + riscos. (Modelo:
+`documentação/MAPA-FUNCIONAL-COMPLETO.md`, Etapas 4 e 8.)
+</content>

ScoreOdonto_Skills_Enterprise/FASE_08_AUDITORIA/SKILL_Performance.md

@@ -0,0 +1,28 @@
+# SKILL — Auditoria de Performance
+
+> Onde olhar antes de otimizar. Sem micro-otimização cega — medir primeiro.
+
+## Pontos de atenção reais
+- **`server.js` monolítico** (~516 KB): carga cognitiva alta, mas não é gargalo de runtime por si.
+- **Guards fazem queries por request**: `tenantGuard` (1 SELECT em `vinculos`) + `requireCapability` (1–2
+  SELECTs em `usuarios`/`vinculos`/`funcoes`). Aceitável; se virar gargalo, considerar cache curto do papel.
+- **Catálogos/listas**: `GET /api/{procedimentos,especialidades,planos,dentistas,pacientes,agendamentos}` —
+  garantir índices em `clinica_id` e filtros corretos.
+- **PostGIS**: busca por proximidade (salas) precisa de índice GIST em `geo`.
+- **Cache DragonflyDB** (`/1`): usado para acelerar; `/api/health` reporta latência de banco e cache.
+
+## Como auditar
+```bash
+grep -niE "CREATE INDEX" backend/server.js                 # índices existentes
+grep -niE "SELECT .* FROM (pacientes|agendamentos)" backend/server.js | head   # queries quentes
+curl -s https://<projeto>/api/health   # latency_ms de database/cache
+```
+
+## Regras obrigatórias
+1. **Medir** (latências do `/api/health`, EXPLAIN) antes de otimizar.
+2. Índice em toda coluna usada em filtro frequente (`clinica_id`, FKs, status).
+3. Não introduzir N+1 em loop de query; preferir `IN`/JOIN.
+
+## Anti-padrões
+- ❌ Otimizar sem medir. ❌ Remover guard "para acelerar" (quebra segurança). ❌ Lista sem filtro por `clinica_id`.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_08_AUDITORIA/SKILL_Permissoes.md

@@ -0,0 +1,36 @@
+# SKILL — Auditoria de Permissões (RBAC)
+
+> Como o controle de acesso REAL funciona hoje e como auditá-lo. Herda de
+> `../FASE_01_ARQUITETURA/SKILL_RBAC.md`. Implementado no backend nesta stack.
+
+## Três planos de autorização (backend)
+1. **Identidade** — `authGuard`: valida o JWT (assinado com `JWT_SECRET`), popula `req.authUser.userId`.
+2. **Tenant** — `tenantGuard`: valida que o usuário tem **vínculo** com a `clinica_id` pedida (ou é dono da
+   sala); seta `req.clinicaId`. Sem vínculo → 403 `[TENANT VIOLATION]`.
+3. **Cargo (capability)** — `requireCapability(cap)` / `requireCapabilityRow(cap, tabela)` /
+   `requireCapabilityFromOrders(cap, tabela)`: exige a capability no workspace ativo. **Superadmin** → `superadminGuard` (checa `usuarios.role` no banco).
+
+## `capabilityCore` (espelha o `isViewAllowed` do frontend)
+- superadmin global → ok;
+- dono (`donoclinica`/`donoconsultorio`/`admin`, `CAP_OWNER_ROLES`) → ok;
+- cargo com `funcoes.permissoes` (JSONB) explícitas → ok se inclui a capability;
+- senão, **mapa padrão por papel** (`CAP_DEFAULTS`, cópia fiel do frontend).
+
+## Cobertura (99 rotas gateadas)
+financeiro (`'financeiro'`/`'comissoes'`/`'glosas'`), equipe (`'gestao-equipe'`), cadastros
+(`'dentistas'`/`'especialidades'`/`'procedimentos'`/`'planos'`, incl. `/reorder`), operação clínica
+(`'agenda'`/`'leads'`), orçamentos/contratos. Marketplace (salas/propostas) = autorização por **posse** no handler.
+
+## Como auditar
+```bash
+grep -nE "tenantGuard|authGuard|requireCapability|superadminGuard" backend/server.js   # guards por rota
+grep -nE "CAP_DEFAULTS|CAP_OWNER_ROLES" backend/server.js                              # matriz de papéis
+```
+Regra de ouro: **a capability do backend tem que casar com o `isViewAllowed`/Sidebar do frontend**.
+
+## Anti-padrões
+- ❌ Rota sensível só com `tenantGuard` (membersia ≠ cargo).
+- ❌ `authGuard` puro em rota que toca dado de clínica (falta tenant).
+- ❌ Capability no backend divergente do menu do frontend.
+- ❌ Confiar em estado do cliente (`localStorage`/preview) para autorizar.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_08_AUDITORIA/SKILL_Rotas.md

@@ -0,0 +1,43 @@
+# SKILL — Auditoria de Rotas
+
+> Objetivo: ensinar qualquer agente a **mapear e entender as rotas antes de alterar** — front e back.
+> Regra Nº1: não quebrar o que funciona. Sempre Auditoria → Planejamento → Aprovação.
+
+## Onde a verdade está
+- **Frontend (navegação):** `frontend/App.tsx` — `ROUTE_MAP` (URL→view), `VIEW_TO_ROUTE` (view→URL),
+  `renderView()` (view→componente), `isViewAllowed()` (RBAC), e o filtro de menu em `components/Sidebar.tsx`.
+  Não há `react-router` — o roteamento é próprio.
+- **Backend (API):** `backend/server.js` — **277 rotas** `app.<método>('/api/...')`, quase todas com `tenantGuard`.
+
+## Como mapear (comandos de auditoria)
+```bash
+# Rotas de API (método + caminho)
+grep -oE "app\.(get|post|put|delete|patch)\('[^']+" backend/server.js | sort -u
+# Rotas do frontend (URL → view)
+sed -n '/ROUTE_MAP/,/};/p' frontend/App.tsx
+# Permissões por papel
+sed -n '/isViewAllowed/,/^  };/p' frontend/App.tsx
+sed -n '/menuItems/,/];/p' frontend/components/Sidebar.tsx
+```
+
+## Checklist antes de mexer numa rota
+1. A URL existe em **ambos** `ROUTE_MAP` e `VIEW_TO_ROUTE`? (senão deep-link quebra)
+2. Qual `isViewAllowed`/menu libera essa view e para quais papéis?
+3. Qual rota de API ela consome? Tem `tenantGuard` (escopo de clínica)?
+4. Quais tabelas a rota toca? (ver `SKILL_Banco.md`/`SKILL_Entidades.md`)
+5. Alterou acesso no back? **Espelhe** em `isViewAllowed` + `Sidebar` no mesmo PR.
+
+## Débitos conhecidos a vigiar (já auditados)
+- `/comissoes`, `/glosas`, `/cadastro-dentista`: existem em `VIEW_TO_ROUTE` mas **faltam em `ROUTE_MAP`**
+  → deep-link/refresh cai em `dashboard`. (Documentado em `MAPA-FUNCIONAL-COMPLETO.md`.)
+- `/admin/sync`: rota existe, mas `isViewAllowed` retorna `false` sempre (tela inacessível).
+
+## Anti-padrões
+- ❌ Adicionar view sem registrar nas DUAS direções (`ROUTE_MAP` + `VIEW_TO_ROUTE`).
+- ❌ Liberar tela no menu sem proteger a rota de API correspondente.
+- ❌ Alterar caminho de API sem buscar todos os consumidores no frontend (`services/backend.ts`).
+
+## Entregável da auditoria
+Tabela URL → view → componente → papéis → rota(s) de API → tabelas, + riscos. (Modelo:
+`documentação/MAPA-FUNCIONAL-COMPLETO.md`, Etapa 1.)
+</content>

ScoreOdonto_Skills_Enterprise/FASE_09_OBSERVABILIDADE/SKILL_Diagnosticos.md

@@ -0,0 +1,28 @@
+# SKILL — Diagnósticos (runbook de incidente)
+
+> Passo a passo quando algo quebra. Combina Health, Logs, Deploy Imutável.
+
+## Triagem rápida
+1. `GET /api/health` — `database down` (503)? `cache degraded`? `version` esperada?
+2. `GET /api/version` — bate com a tag que deveria estar no ar?
+3. `docker ps` (rootless) — container `Up`? reiniciando (`RestartCount`)?
+4. `docker logs --tail 80 <container>` — erro no boot? `[PG]`/`[DRAGONFLY]` conectaram?
+
+## Causas comuns (reais nesta stack)
+- **`env file .secrets/.env not found`** → falta o env_file no host (VPS1). Copiar manualmente (fora do git).
+- **`database down`** → Postgres VPS3 inacessível (WireGuard) ou credencial errada.
+- **`cache down`** → Dragonfly/`ping()` (degradável; não derruba).
+- **Migração** falhou no boot → ver log `[MIGRATION]`.
+
+## Recuperação
+- App quebrado pós-deploy → **rollback por imagem** (segundos): `deploy-prod.sh <ref-anterior>` (ver Deploy Imutável).
+- Dado corrompido → restaurar `pg_dump` de `/home/deploy/backups/` (caso extremo).
+
+## Regras obrigatórias
+1. Diagnosticar com `/api/health` + logs **antes** de mexer.
+2. Preferir **rollback de imagem** a "consertar em produção no quente".
+3. Reproduzir/testar a correção no `dev` (`pgdev`) antes de promover.
+
+## Anti-padrões
+- ❌ Editar código direto na VPS1. ❌ Mexer no banco de produção sem backup. ❌ Deploy às cegas sem health.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_09_OBSERVABILIDADE/SKILL_HealthChecks.md

@@ -0,0 +1,26 @@
+# SKILL — Health Checks
+
+> Como saber se o app está vivo e saudável, sem SSH. Fonte: `documentos-unicos/deploy/versionamento.md`.
+
+## Endpoint real
+`GET /api/health` → `{ status, version, commit, environment, uptime_s, checks }`:
+- **`database`** é crítico: se cair → `status: down` + **HTTP 503**.
+- **`cache`** (DragonflyDB) é opcional: se cair → `status: degraded` (HTTP 200); `disabled` se desligado.
+- Cada check traz `latency_ms` — útil para perceber lentidão de banco/cache.
+
+## Como usar
+```bash
+curl -s https://<projeto>/api/health        # produção
+curl -s https://dev.<projeto>/api/health    # dev
+```
+
+## Regras obrigatórias
+1. **Validar `/api/health` após todo deploy** (e na rotina de monitoramento).
+2. `database down` (503) é incidente → investigar conexão VPS1→VPS3 / Postgres.
+3. `cache down/degraded` não derruba o app, mas registre (ex.: pré-existente no RX — `redis.ping()`).
+4. Não remover/alterar o contrato do `/api/health` (monitor externo depende dele).
+
+## Anti-padrões
+- ❌ Deploy sem checar health. ❌ Tornar o cache crítico (deve ser degradável).
+- ❌ Vazar segredo/detalhe interno no payload do health.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_09_OBSERVABILIDADE/SKILL_Logs.md

@@ -0,0 +1,28 @@
+# SKILL — Logs & Auditoria
+
+> Onde está o rastro do que aconteceu. Dois níveis: log de aplicação e trilha de auditoria persistida.
+
+## Auditoria de negócio (persistida)
+- Tabela **`audit_log`** (`clinica_id, entidade, entidade_id, acao, actor_id, actor_nome, detalhes, at`),
+  gravada por `registrarAudit(...)` em mutações sensíveis (procedimento, repasse, comissão, contrato, equipe…).
+- **Imutável** — é o rastro de quem fez o quê. Mutações financeiras/RBAC devem registrar.
+- `login_log` registra acessos (visível em SuperAdmin → Acessos).
+
+## Log de aplicação (runtime)
+- `console.*` no `server.js` (boot, `[PG] Connected`, `[DRAGONFLY] Connected`, `[WS] broadcast`,
+  `[TENANT VIOLATION]`, `[CLINICA] Created`…). Visível em `docker logs <container>` (rootless).
+
+## Como usar
+```bash
+DOCKER_HOST=unix:///run/user/1000/docker.sock docker logs --tail 50 <container>
+grep -n "registrarAudit" backend/server.js   # pontos auditados
+```
+
+## Regras obrigatórias
+1. Toda mutação sensível (dinheiro, cargo, contrato) chama `registrarAudit`. **Não** remover.
+2. **Nunca** logar segredo/credencial/token.
+3. `[TENANT VIOLATION]` no log = tentativa de acesso cross-tenant → investigar.
+
+## Anti-padrões
+- ❌ Mutação sensível sem auditoria. ❌ Logar dado pessoal/segredo. ❌ Apagar `audit_log`.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_09_OBSERVABILIDADE/SKILL_VersionamentoRuntime.md

@@ -0,0 +1,26 @@
+# SKILL — Versionamento em Runtime
+
+> De onde vem a versão exibida e por que ela é confiável. Herda de `../FASE_07_INFRA/SKILL_BuildOnce.md`.
+
+## Como funciona (real)
+- A versão **nasce da tag git** (`vX.Y.Z`) e é **injetada no deploy em runtime** (`APP_VERSION`), não escrita à
+  mão (não existe mais `constants.ts`/`update-version.js`).
+- `commit` e `build` são **carimbados na imagem** (imutáveis, propriedade do artefato).
+- Em **DEV** aparece `dev`; o número só existe em produção.
+- Exposição: `GET /api/version` → `{ name, version, commit, build, environment }`. O frontend **não embute**
+  versão — lê de `/api/version` (fonte única = backend). Mostrada no rodapé (canto inf. direito) e em
+  Configurações → "Sobre o sistema".
+
+## Como verificar
+```bash
+curl -s https://<projeto>/api/version   # → vX.Y.Z · <commit> · PROD
+```
+
+## Regras obrigatórias
+1. **Não** hardcodar versão em arquivo — só a tag define.
+2. A MESMA imagem promovida sob a tag = `commit`/`build` imutáveis + `version`/`environment` em runtime.
+3. Conferir `/api/version` após deploy (bate com a tag promovida?).
+
+## Anti-padrões
+- ❌ Escrever versão manualmente. ❌ Frontend embutir versão. ❌ Rebuild na tag (quebra o build-once).
+</content>

ScoreOdonto_Skills_Enterprise/FASE_10_ROADMAP/SKILL_Backlog.md

@@ -0,0 +1,26 @@
+# SKILL — Backlog (Roadmap)
+
+> Itens reais levantados nas auditorias e na sessão de hardening. Não inventar; manter atualizado.
+
+## Segurança / produção (parcialmente feito em DEV)
+- ✅ JWT rotacionado (dev+prod); `.env` fora do git; `.dockerignore`; senhas fora do compose; RBAC por cargo (99 rotas).
+- ⬜ Provisionar `SCOREO_DB_PASS` na VPS1; push imagem limpa `v1.0.19`; rotacionar DB/cache/API keys.
+
+## Correções (do MAPA-FUNCIONAL)
+- ⬜ Deep-links residuais já tratados (`/comissoes`, `/glosas`); revisar outros se surgirem.
+- ⬜ RECEITA de procedimento opcional → decidir se vira padrão (risco de caixa).
+- ⬜ Estado de plugins divergente cliente/servidor (`localStorage` vs `usuario_plugins`).
+
+## Modelagem (do AUDITORIA-ESTRATEGICA)
+- ⬜ `dentistas` como projeção da pessoa; `pacientes` com identidade (LGPD/jurídico antes).
+- ⬜ Unificar workspace (`clinicas`+`salas`); entidade "rede" acima da clínica.
+
+## Receita (do SKILL_Monetizacao)
+- ⬜ Gateway na Locação de Salas; recorrência das Assinaturas; marketplace premium.
+
+## Limpeza
+- ⬜ Órfã `OrthoReports.tsx`; `SyncView` desativada; `server.js.bak`/scripts legados.
+
+## Regra
+Backlog reflete a **realidade**; ao concluir, marcar ✅ com referência ao commit/PR.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_10_ROADMAP/SKILL_Escalabilidade.md

@@ -0,0 +1,24 @@
+# SKILL — Escalabilidade (Roadmap)
+
+> O que o modelo suporta em 5 anos e onde estão os gargalos. Base: `AUDITORIA-ESTRATEGICA-MODELAGEM.md`.
+
+## O que JÁ escala (base Pessoa→Vínculo→Workspace)
+- Pessoa em **múltiplos workspaces** (N `vinculos`), workspace pessoal automático, salas/tutoria/marketplace.
+
+## Gargalos conhecidos
+| Cenário | Suporta? | Gargalo |
+|---|---|---|
+| Dentista em várias clínicas | parcial | `dentistas` **duplica a pessoa** por clínica (agenda/horários presos ao `dentistas.id`) |
+| Paciente entre clínicas | não | `pacientes` preso à clínica, sem identidade de pessoa (não-portável) |
+| Redes de clínicas | não | **não existe entidade "rede/grupo"** acima da clínica (workspaces são planos) |
+| Visão consolidada da pessoa | não | tenancy de `clinica_id` único impede agregar cross-clínica |
+| Profissionais temporários (delivery) | não | sem contrato/pagamento/vínculo temporário (ver `../FASE_02_NEGOCIO/SKILL_Delivery.md`) |
+| Locação/Tutoria/Marketplace | sim/parcial | falta captura de pagamento (salas) |
+
+## Direção (sem propor implementação)
+Consolidar a **Pessoa** como âncora única (unificar `dentistas`→projeção; paciente→identidade) destrava
+multi-clínica, redes e portabilidade. Coexistir os 2 modelos é o que gera as contradições de gravidade ALTA.
+
+## Anti-padrões
+- ❌ Duplicar a pessoa por workspace. ❌ Tratar clínica como raiz. ❌ Operação sem `clinica_id`.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_10_ROADMAP/SKILL_Monetizacao.md

@@ -0,0 +1,25 @@
+# SKILL — Monetização (Roadmap)
+
+> O que gera (ou pode gerar) receita. Base: `documentação/MAPA-FUNCIONAL-COMPLETO.md` + `AUDITORIA-ESTRATEGICA-MODELAGEM.md`.
+
+## Três camadas de receita (estado real)
+1. **Receita da clínica** (operacional): produção, contratos/cobrança, recuperação de glosas.
+2. **Receita do profissional** (repasse de comissão).
+3. **Receita da PLATAFORMA**:
+   - **Tutoria** — MercadoPago + `comissao_pct`: **única automatizada hoje**. ✅
+   - **Assinaturas SaaS** (`assinaturas`/`superadmin/pricing`): existe, mas **manual** (sem gateway/recorrência).
+   - **Locação de salas** (`sala_reservas.valor`): registra valor, **sem captura de pagamento**.
+
+## Alavancas (ordem de retorno mais rápido)
+1. **Gateway na Locação de Salas** — reserva + `valor` já existem; falta cobrança + taxa da plataforma.
+2. **Recorrência das Assinaturas SaaS** — base multiempresa + pricing prontos; falta gateway/automação.
+3. **Marketplace de Profissionais premium** — taxa de match/destaque (hoje só mensagem).
+4. **Escalar Tutoria** (já fatura).
+
+## Regras
+- Toda lacuna de captura deve ser **sinalizada, não presumida como paga**.
+- Não misturar as 3 camadas (clínica ≠ profissional ≠ plataforma).
+
+## Anti-padrões
+- ❌ Assumir que reserva/assinatura foi paga. ❌ Construir cobrança fora do modelo Pessoa→Workspace.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_10_ROADMAP/SKILL_Priorizacao.md

@@ -0,0 +1,22 @@
+# SKILL — Priorização (Roadmap)
+
+> Como decidir a ordem. Critérios concretos para esta stack.
+
+## Critérios (em ordem)
+1. **Não quebrar o que funciona** (REGRA Nº 1) — auditar impacto antes.
+2. **Segurança / pré-produção** primeiro (abrir a usuários reais exige base segura) — ver `SKILL_Backlog`.
+3. **Receita mais rápida com menor esforço** — alavanca onde a infra já existe (ex.: gateway de salas).
+4. **Destravar arquitetura** (unificar Pessoa) — alto valor, maior esforço/risco → deliberado, não no susto.
+5. **Esforço × risco × reversibilidade** — preferir mudanças aditivas e reversíveis (build-once/rollback).
+
+## Fluxo obrigatório por item
+`Auditoria → Planejamento → Aprovação → Implementação (em DEV/`pgdev`) → Validação → Promoção`.
+
+## Recomendação estratégica única (da auditoria)
+Assumir a **Pessoa como âncora** e **parar de manter o legado clínica-cêntrico em paralelo** — é a coexistência
+dos dois modelos que gera as contradições graves. Mas: só após segurança/produção estável e com aprovação.
+
+## Anti-padrões
+- ❌ Implementar sem auditoria/aprovação. ❌ Priorizar features novas sobre segurança pré-lançamento.
+- ❌ Refator arquitetural grande sem janela e rollback.
+</content>

backend/.dockerignore

@@ -0,0 +1,28 @@
+# Segredos e ambiente — NUNCA entram na imagem
+.env
+.env.*
+*.secret
+.secrets
+
+# Dependências e caches (reinstalados no build)
+node_modules
+npm-debug.log
+
+# Artefatos locais / backups / dados que não pertencem à imagem
+*.bak
+server.js.bak
+sessions/
+media/
+data/
+bkp/
+*.dump
+
+# Diagnóstico temporário
+test-db-users.js
+test-db-users.cjs
+pg-convert.js
+
+# Diversos
+.git
+.DS_Store
+*.log

backend/.env

@@ -1,45 +0,0 @@
-# ─────────────────────────────────────────────
-# Server
-# ─────────────────────────────────────────────
-PORT=8018
-NODE_ENV=development
-JWT_SECRET=scoreodonto_jwt_secret_forte_2026
-
-# ─────────────────────────────────────────────
-# PostgreSQL (Prisma)
-# ─────────────────────────────────────────────
-DATABASE_URL="postgresql://scoreodonto_user:clube67_scoreodonto_pass_9903@10.99.0.3:5432/scoreodonto?schema=public"
-
-# ─────────────────────────────────────────────
-# DragonflyDB (compatível com Redis)
-# ─────────────────────────────────────────────
-DRAGONFLY_URL=redis://:clube67_dragonfly_pass_9903@10.99.0.3:6379/1
-DRAGONFLY_TTL_SECONDS=86400
-
-# ─────────────────────────────────────────────
-# NATS JetStream
-# ─────────────────────────────────────────────
-NATS_URL=nats://10.99.0.3:4222
-
-# ─────────────────────────────────────────────
-# Temporal.io
-# ─────────────────────────────────────────────
-TEMPORAL_ADDRESS=10.99.0.3:7233
-TEMPORAL_NAMESPACE=default
-TEMPORAL_TASK_QUEUE=scoreodonto-queue
-
-# ─────────────────────────────────────────────
-# IA (OpenAI + Google Gemini)
-# ─────────────────────────────────────────────
-OPENAI_API_KEY=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
-GEMINI_API_KEY=AIza...
-
-# ─────────────────────────────────────────────
-# WhatsApp / Baileys
-# ─────────────────────────────────────────────
-BAILEYS_SESSIONS_PATH=/home/deploy/scoreodonto-sessions
-
-# ─────────────────────────────────────────────
-# Frontend (CORS)
-# ─────────────────────────────────────────────
-FRONTEND_URL=http://localhost:3013

backend/.env.example

@@ -0,0 +1,26 @@
+# Modelo de variáveis de ambiente do backend (SEM segredos).
+# Copie para .env e preencha com valores REAIS. O .env NÃO é versionado.
+PORT=8018
+NODE_ENV=production
+
+# Segredo de assinatura dos tokens JWT — gerar com: openssl rand -hex 48
+JWT_SECRET=
+
+# Banco e cache (não versionar valores reais)
+DATABASE_URL=postgresql://USER:SENHA@HOST:5432/BANCO?schema=public
+DRAGONFLY_URL=redis://:SENHA@HOST:6379/1
+DRAGONFLY_TTL_SECONDS=3600
+
+# Mensageria / workflows
+NATS_URL=nats://HOST:4222
+TEMPORAL_ADDRESS=HOST:7233
+TEMPORAL_NAMESPACE=default
+TEMPORAL_TASK_QUEUE=scoreodonto
+
+# Chaves de IA (rotacionáveis apenas nos painéis dos provedores)
+OPENAI_API_KEY=
+GEMINI_API_KEY=
+
+# Caminhos / front
+BAILEYS_SESSIONS_PATH=/app/sessions
+FRONTEND_URL=https://scoreodonto.com

backend/newwhats/INTEGRACAO-MOTOR.md

@@ -0,0 +1,70 @@
+# Integração NewWhats (satélite) — scoreodonto.com ↔ Motor
+
+> **Único deste projeto** (scoreodonto.com). Clonado e **adaptado ao domínio
+> odonto** a partir do satélite do `mercado.clube67.com`. Backend **ESM** — sem o
+> host de plugins do mercado; é um módulo registrado no `server.js`. v1.0.0.
+
+## ⚠️ Regra de registro bidirecional (obrigatória)
+- Toda mudança que toque o contrato (rotas, payloads, auth, webhook) **deve ser
+  registrada no motor** e na doc central
+  `documentos-unicos/projetos/newwhats.clube67.com/integracao-satelites.md`.
+- Toda mudança no motor que afete o contrato **deve ser refletida aqui**.
+- O satélite é um **braço inteligente do motor** — consome/alimenta, não duplica.
+
+## Diferenças vs o satélite do mercado
+- **ESM** (não CommonJS) e **sem PluginManager** — registrado via
+  `registerNewwhats(app, pool)` no `server.js`.
+- **Config por ENV** (não tabela `plugin_configs`): `NEWWHATS_URL`,
+  `NEWWHATS_INTEGRATION_KEY`, `NEWWHATS_WEBHOOK_SECRET`, `NEWWHATS_CLINICA_ID`.
+- **Negócio adaptado ao odonto**: `/nw/*` e `sync-knowledge` usam
+  clínica/especialidades/dentistas/procedimentos/planos (multi-tenant por
+  `clinica_id`), no lugar de clubes/sorteio/vagas.
+- **Removidos** (não úteis aqui): `media-transcribe` (o motor já transcreve —
+  ver Fase 5), `smart-router`, `personas`, `follow-up-detector`, `context-builder`
+  (heurísticas específicas do mercado). Reavaliar se necessário.
+
+## Arquivos
+| Arquivo | Papel |
+|---|---|
+| `config.js` | lê a config da integração das ENV |
+| `auth.js` | `nwAuth` — valida `x-nw-key`/Bearer nas rotas `/nw/*` |
+| `routes.js` | `/nw/*` odonto: `/ping`, `/clinica`, `/especialidades`, `/dentistas`, `/procedimentos`, `/planos` |
+| `sync-knowledge.js` | `buildKnowledgeText(pool, clinicaId)` + `syncKnowledge(pool)` → motor `/api/secretaria/*` |
+| `webhook-receiver.js` | `POST /api/webhook/newwhats` (HMAC) — `message.new`, `session.status` (enxuto) |
+| `proxy.js` | `/api/nw/v1/*` → motor `/api/ext/v1/*` (injeta `x-nw-key`) |
+| `index.js` | `registerNewwhats(app, pool)` — registra tudo |
+| `manifest.json` | metadados + `config_env` |
+
+## Contrato (resumo)
+- **Satélite → Motor**: proxy `/api/nw/v1/*` → ext-api `/api/ext/v1/*` (Bearer/x-nw-key);
+  `sync-knowledge` → `/api/secretaria/*`.
+- **Motor → Satélite**: webhook `POST /api/webhook/newwhats` (HMAC `webhook_secret`);
+  Secretária consulta `/nw/*` (`integration_key`).
+
+## Frontend (React SPA)
+- Plugin `newwhats` registrado em `frontend/views/PluginsView.tsx` (catálogo
+  PLUGINS) — **config exclusiva do superadmin** (a view `plugins` já é gateada em
+  `App.tsx isViewAllowed`).
+- `ALWAYS_ON` em `pluginRegistry.ts` → Inbox/Secretária aparecem para **todos** os
+  usuários (a ativação por plugin é localStorage e não propaga entre contas).
+- Views: `frontend/views/WaInboxView.tsx` (conversas/thread/envio) e
+  `WaSecretariaView.tsx` (ask) — consomem `/api/nw/v1/*`. **Estágio 1** (funcional,
+  visual aproximado do motor; refinar para ficar idêntico).
+- Sidebar: itens WHATSAPP + SECRETÁRIA IA (gated por `isPluginActive('newwhats')`).
+
+## Pendências / TODO
+- [ ] **Segurança**: gatear o proxy `/api/nw/v1/*` com a auth do scoreodonto (hoje
+      aberto — qualquer um que alcance a rota é proxiado ao motor).
+- [x] **Ponte de config** (feito): config persiste na tabela `settings`
+      (`id=newwhats_config`); backend lê do DB com fallback ENV
+      (`config.js loadConfigFromDb`). UI dedicada (`NewwhatsConfigModal`) com
+      **dropdown de clínicas**, secrets que mantêm valor se em branco e **Testar
+      conexão** (`GET /api/nw/status`). Endpoints superadmin: `GET/PUT /api/nw/config`,
+      `GET /api/nw/clinicas`, `GET /api/nw/status`.
+- [ ] `webhook message.new`: capturar lead / acionar fluxo (hoje só loga).
+- [ ] Proxy WS (`/api/nw/v1/stream`) — só o REST foi portado (Inbox sem tempo real).
+- [ ] Parear scoreodonto com o motor (criar apiKey/pair + agente) e preencher as ENV.
+- [ ] Endpoint/admin para disparar `syncKnowledge` (hoje exportado, sem rota).
+- [ ] Refinar Inbox/Secretária para ficarem idênticas ao motor.
+
+> Fonte da verdade do contrato: `documentos-unicos/projetos/newwhats.clube67.com/`.

backend/newwhats/agenda-bridge.js

@@ -0,0 +1,694 @@
+// Ponte de agenda: expõe /api/nw/agenda/* para o MOTOR (tools da Secretária)
+// operarem na agenda REAL do scoreodonto — em vez do calendário isolado do motor.
+//
+// Segurança: chamada server-to-server autenticada por segredo compartilhado
+// (header x-nw-agenda-secret === webhookSecret configurado). Todo acesso é
+// preso ao clinica_id enviado (o motor conhece a clínica da instância).
+//
+// Endpoints:
+//   GET  /slots  — horários livres (jornada dos dentistas − agendamentos)
+//   POST /book   — cria agendamento real (anti-overbooking + vínculo de paciente)
+import express from 'express';
+import { getConfig } from './config.js';
+import { cautelasParaIA } from './checklist-defs.js';
+import { resolverFeriado, feriadoNacionalNome } from './feriados.js';
+
+const SLOT_MIN = 60;        // duração/espaçamento padrão do slot (1h entre atendimentos)
+const HORIZON_DAYS = 7;     // janela padrão de busca
+const MAX_SLOTS = 20;       // quantos slots RETORNAR (após ordenar por horário)
+const CANDIDATE_CAP = 240;  // teto de GERAÇÃO (clínica + salas competem por horário)
+// Fallback quando a CLÍNICA não configurou horário de funcionamento: comercial
+// padrão (seg–sex 08–18). Uma vez configurado (clinicas_horarios), manda ele.
+const DEFAULT_INI = '08:00';
+const DEFAULT_FIM = '18:00';
+const DIAS_NOME = ['domingo', 'segunda-feira', 'terça-feira', 'quarta-feira', 'quinta-feira', 'sexta-feira', 'sábado'];
+
+const pad = (n) => String(n).padStart(2, '0');
+const ymd = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+const fmt = (d) => `${ymd(d)} ${pad(d.getHours())}:${pad(d.getMinutes())}:00`;
+const hm = (t) => String(t ?? '').slice(0, 5);   // 'HH:MM:SS'|Date → 'HH:MM'
+
+// Interseção de duas listas de janelas [ini,fim] (strings 'HH:MM'). Retorna as
+// sobreposições (ex.: clínica 08–18 ∩ dentista 13–20 = 13–18).
+function interseccao(a, b) {
+  const out = [];
+  for (const [ai, af] of a) for (const [bi, bf] of b) {
+    const ini = ai > bi ? ai : bi;
+    const fim = af < bf ? af : bf;
+    if (ini < fim) out.push([ini, fim]);
+  }
+  return out;
+}
+
+// Carrega o horário de FUNCIONAMENTO da clínica → { byDow: Map<dow,[[ini,fim]]>, hasConfig }.
+async function carregarHorariosClinica(pool, clinicaId) {
+  const byDow = new Map();
+  let hasConfig = false;
+  try {
+    const { rows } = await pool.query(
+      `SELECT dia_semana, hora_inicio, hora_fim FROM clinicas_horarios WHERE clinica_id = $1 AND ativo = 1`,
+      [clinicaId]);
+    hasConfig = rows.length > 0;
+    for (const r of rows) {
+      const arr = byDow.get(r.dia_semana) || [];
+      arr.push([hm(r.hora_inicio), hm(r.hora_fim)]);
+      byDow.set(r.dia_semana, arr);
+    }
+  } catch { /* tabela pode não existir ainda → cai no fallback */ }
+  return { byDow, hasConfig };
+}
+
+// Carrega as folgas (por data) dos dentistas da clínica → Map<dentista_id,[{ini,fim}]>.
+async function carregarFolgas(pool, clinicaId) {
+  const byDent = new Map();
+  try {
+    const { rows } = await pool.query(
+      `SELECT f.dentista_id, to_char(f.data_inicio,'YYYY-MM-DD') AS ini, to_char(f.data_fim,'YYYY-MM-DD') AS fim
+         FROM dentistas_folgas f JOIN dentistas d ON d.id = f.dentista_id
+        WHERE d.clinica_id = $1`, [clinicaId]);
+    for (const r of rows) {
+      const arr = byDent.get(r.dentista_id) || [];
+      arr.push([r.ini, r.fim]);
+      byDent.set(r.dentista_id, arr);
+    }
+  } catch { /* tabela pode não existir ainda */ }
+  return byDent;
+}
+const emFolga = (folgas, dateStr) => (folgas || []).some(([i, f]) => dateStr >= i && dateStr <= f);
+
+// Janelas de funcionamento da CLÍNICA num dia específico, já considerando feriado.
+// Retorna { janelas: [[ini,fim]], fechado: bool, motivo: string|null }.
+async function janelasClinicaNoDia(pool, clinicaId, dateStr, dow, clinicHours) {
+  const fer = await resolverFeriado(pool, clinicaId, dateStr);
+  if (fer && fer.fecha) return { janelas: [], fechado: true, motivo: `Feriado: ${fer.nome}` };
+  // Feriado com horário especial (fecha=0 + horas) sobrepõe o horário normal.
+  if (fer && !fer.fecha && fer.hora_inicio && fer.hora_fim) {
+    return { janelas: [[hm(fer.hora_inicio), hm(fer.hora_fim)]], fechado: false, motivo: `Horário especial (${fer.nome})` };
+  }
+  // Horário normal do dia da semana.
+  let janelas;
+  if (clinicHours.hasConfig) {
+    janelas = (clinicHours.byDow.get(dow) || []).map(([i, f]) => [i, f]);
+  } else {
+    janelas = (dow >= 1 && dow <= 5) ? [[DEFAULT_INI, DEFAULT_FIM]] : [];
+  }
+  if (!janelas.length) return { janelas: [], fechado: true, motivo: DIAS_NOME[dow] === 'domingo' || DIAS_NOME[dow] === 'sábado' ? `Fechado (${DIAS_NOME[dow]})` : 'Fechado neste dia' };
+  return { janelas, fechado: false, motivo: null };
+}
+
+// Overbooking: MESMA regra do server.js (agrupa o dentista por usuario_id/email,
+// para o mesmo profissional atuando em clínicas diferentes). Cópia da lógica —
+// se a regra do scoreodonto mudar, revisar aqui também.
+async function findConflict(db, dentistaId, start, end, excludeId = null) {
+  if (!dentistaId || !start) return null;
+  const { rows: dr } = await db.query('SELECT usuario_id, email FROM dentistas WHERE id = $1', [dentistaId]);
+  let ids = [dentistaId];
+  const uid = dr[0]?.usuario_id || null;
+  const email = (dr[0]?.email || '').trim().toLowerCase() || null;
+  if (uid) {
+    const { rows } = await db.query('SELECT id FROM dentistas WHERE usuario_id = $1', [uid]);
+    if (rows.length) ids = rows.map((r) => r.id);
+  } else if (email) {
+    const { rows } = await db.query('SELECT id FROM dentistas WHERE lower(trim(email)) = $1', [email]);
+    if (rows.length) ids = rows.map((r) => r.id);
+  }
+  const { rows } = await db.query(
+    `SELECT id FROM agendamentos
+      WHERE dentistaid = ANY($1)
+        AND (status IS NULL OR lower(status) NOT IN ('cancelado','falta','remarcar'))
+        AND start_time < $3 AND COALESCE(end_time, start_time) > $2
+        AND ($4::text IS NULL OR id <> $4)
+      LIMIT 1`,
+    [ids, start, end || start, excludeId]);
+  return rows[0] || null;
+}
+
+export function createAgendaBridge(pool) {
+  const router = express.Router();
+
+  // Auth server-to-server por segredo compartilhado.
+  router.use((req, res, next) => {
+    const secret = getConfig().webhookSecret;
+    if (!secret || req.headers['x-nw-agenda-secret'] !== secret) {
+      return res.status(401).json({ error: 'Segredo da ponte inválido' });
+    }
+    next();
+  });
+
+  // ── GET /slots ──────────────────────────────────────────────────────────────
+  // Query: clinica_id (obrig.), dentista_id?, date? (YYYY-MM-DD), days?, duration?
+  router.get('/slots', async (req, res) => {
+    const clinicaId = String(req.query.clinica_id || '');
+    if (!clinicaId) return res.status(400).json({ error: 'clinica_id obrigatório' });
+    const dentistaId = req.query.dentista_id ? String(req.query.dentista_id) : null;
+    const duration = Math.max(10, parseInt(req.query.duration, 10) || SLOT_MIN);
+    const days = Math.min(30, Math.max(1, parseInt(req.query.days, 10) || HORIZON_DAYS));
+    const from = req.query.date ? new Date(`${req.query.date}T00:00:00`) : new Date();
+    const periodo = req.query.periodo ? String(req.query.periodo).toLowerCase() : null; // manha|tarde
+
+    try {
+      // Dentistas no escopo da clínica.
+      const dParams = [clinicaId];
+      let dWhere = 'clinica_id = $1';
+      if (dentistaId) { dParams.push(dentistaId); dWhere += ` AND id = $${dParams.length}`; }
+      const { rows: dentistas } = await pool.query(`SELECT id, nome FROM dentistas WHERE ${dWhere}`, dParams);
+      if (!dentistas.length) return res.json({ slots: [], motivo: 'Nenhum dentista cadastrado na clínica.' });
+
+      // Jornada dos DENTISTAS (dentistas_horarios) — opcional, por dentista.
+      const { rows: horarios } = await pool.query(
+        `SELECT dentista_id, dia_semana, hora_inicio, hora_fim
+           FROM dentistas_horarios WHERE clinica_id = $1 AND ativo = 1`, [clinicaId]);
+      const hoursBy = new Map();
+      for (const h of horarios) { const a = hoursBy.get(h.dentista_id) || []; a.push(h); hoursBy.set(h.dentista_id, a); }
+
+      // Horário de FUNCIONAMENTO da clínica (config do dono) — a "casca" externa.
+      const clinicHours = await carregarHorariosClinica(pool, clinicaId);
+      // Folgas por data dos dentistas (férias/indisponibilidade).
+      const folgasBy = await carregarFolgas(pool, clinicaId);
+
+      const start0 = new Date(from); start0.setHours(0, 0, 0, 0);
+      const end0 = new Date(start0); end0.setDate(end0.getDate() + days);
+      const { rows: busy } = await pool.query(
+        `SELECT dentistaid, start_time, end_time FROM agendamentos
+          WHERE clinica_id = $1 AND start_time >= $2 AND start_time < $3
+            AND (status IS NULL OR lower(status) NOT IN ('cancelado','falta','remarcar'))`,
+        [clinicaId, start0.toISOString(), end0.toISOString()]);
+      const busyBy = new Map();
+      for (const bz of busy) { const a = busyBy.get(bz.dentistaid) || []; a.push(bz); busyBy.set(bz.dentistaid, a); }
+
+      const now = new Date();
+      const slots = [];
+      for (let i = 0; i < days && slots.length < CANDIDATE_CAP; i++) {
+        const day = new Date(start0); day.setDate(day.getDate() + i);
+        const dow = day.getDay();
+        // Janelas da CLÍNICA no dia (já considera feriado). Fechado → pula o dia.
+        const { janelas: clinicWins, fechado } = await janelasClinicaNoDia(pool, clinicaId, ymd(day), dow, clinicHours);
+        if (fechado || !clinicWins.length) continue;
+        for (const dent of dentistas) {
+          if (slots.length >= CANDIDATE_CAP) break;
+          if (emFolga(folgasBy.get(dent.id), ymd(day))) continue; // dentista de folga nesse dia
+          const cfg = hoursBy.get(dent.id);
+          // Dentista: se configurou jornada, usa a do dia; senão, atende sempre
+          // que a clínica está aberta. Efetivo = CLÍNICA ∩ DENTISTA.
+          const dentWins = (cfg && cfg.length)
+            ? cfg.filter((h) => h.dia_semana === dow).map((h) => [hm(h.hora_inicio), hm(h.hora_fim)])
+            : clinicWins;
+          const windows = interseccao(clinicWins, dentWins);
+          const bs = busyBy.get(dent.id) || [];
+          for (const [ini, fim] of windows) {
+            const [hi, mi] = String(ini).split(':').map(Number);
+            const [hf, mf] = String(fim).split(':').map(Number);
+            let t = new Date(day); t.setHours(hi, mi || 0, 0, 0);
+            const limit = new Date(day); limit.setHours(hf, mf || 0, 0, 0);
+            while (t.getTime() + duration * 60000 <= limit.getTime() && slots.length < CANDIDATE_CAP) {
+              const s = new Date(t);
+              const e = new Date(t.getTime() + duration * 60000);
+              t = e;
+              if (s <= now) continue;
+              if (bs.some((b) => new Date(b.start_time) < e && new Date(b.end_time || b.start_time) > s)) continue;
+              slots.push({ dentista_id: dent.id, dentista_nome: dent.nome, start: fmt(s), end: fmt(e) });
+            }
+          }
+        }
+      }
+
+      // ── B (salas): slots do dentista num QUARTO alugado (sala_reservas aprovada).
+      // Disponibilidade = janela da reserva [inicio,fim]; casa o dentista da clínica
+      // pelo usuario_id. Respeita folgas e agendamentos existentes (por dentista).
+      if (slots.length < CANDIDATE_CAP) {
+        try {
+          const { rows: reservas } = await pool.query(
+            `SELECT r.sala_id, r.inicio, r.fim, s.nome AS sala_nome, d.id AS dentista_id, d.nome AS dentista_nome
+               FROM sala_reservas r
+               JOIN salas s     ON s.id = r.sala_id
+               JOIN dentistas d ON d.usuario_id = r.profissional_usuario_id
+              WHERE d.clinica_id = $1
+                AND lower(coalesce(r.status,'')) NOT IN ('cancelada','cancelado','recusada','recusado','rejeitada','pendente','negada')
+                AND r.fim > $2 AND r.inicio < $3
+              ORDER BY r.inicio`,
+            [clinicaId, start0.toISOString(), end0.toISOString()]);
+          const step = duration * 60000;
+          for (const rv of reservas) {
+            if (slots.length >= CANDIDATE_CAP) break;
+            const bs = busyBy.get(rv.dentista_id) || [];
+            const rIni = new Date(rv.inicio), rFim = new Date(rv.fim);
+            let t = new Date(Math.max(rIni.getTime(), start0.getTime(), now.getTime()));
+            const off = (t.getTime() - rIni.getTime()) % step;
+            if (off !== 0) t = new Date(t.getTime() + (step - off)); // alinha ao grid da reserva
+            while (t.getTime() + step <= rFim.getTime() && slots.length < CANDIDATE_CAP) {
+              const s = new Date(t), e = new Date(t.getTime() + step); t = e;
+              if (s <= now) continue;
+              if (emFolga(folgasBy.get(rv.dentista_id), ymd(s))) continue;
+              if (bs.some((b) => new Date(b.start_time) < e && new Date(b.end_time || b.start_time) > s)) continue;
+              slots.push({ dentista_id: rv.dentista_id, dentista_nome: rv.dentista_nome, start: fmt(s), end: fmt(e), sala_id: rv.sala_id, local: rv.sala_nome });
+            }
+          }
+        } catch { /* sala_reservas pode não existir */ }
+      }
+
+      let out = slots.sort((a, b) => a.start.localeCompare(b.start));
+      // Filtro manhã/tarde (a Secretária pergunta o período antes de oferecer).
+      if (periodo === 'manha' || periodo === 'manhã') out = out.filter((s) => parseInt(s.start.slice(11, 13), 10) < 12);
+      else if (periodo === 'tarde') out = out.filter((s) => parseInt(s.start.slice(11, 13), 10) >= 12);
+      res.json({ slots: out.slice(0, MAX_SLOTS) });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
+  // ── GET /status ──────────────────────────────────────────────────────────────
+  // Situação de funcionamento da clínica p/ a Secretária SABER quando responder
+  // "estamos fechados". Query: clinica_id (obrig.), date? (YYYY-MM-DD, def: hoje BR).
+  // Retorna: hoje (aberto/motivo/horários), próximo dia aberto, grade da semana e
+  // próximos feriados.
+  router.get('/status', async (req, res) => {
+    const clinicaId = String(req.query.clinica_id || '');
+    if (!clinicaId) return res.status(400).json({ error: 'clinica_id obrigatório' });
+    try {
+      // "Hoje" no fuso de Brasília (o servidor pode rodar em UTC).
+      const hojeBR = req.query.date
+        ? String(req.query.date)
+        : new Date().toLocaleDateString('en-CA', { timeZone: 'America/Sao_Paulo' }); // YYYY-MM-DD
+      const clinicHours = await carregarHorariosClinica(pool, clinicaId);
+      const dateAt = (str) => new Date(`${str}T12:00:00`); // meio-dia: evita borda de fuso
+      const addYmd = (str, k) => { const d = dateAt(str); d.setDate(d.getDate() + k); return ymd(d); };
+      const statusDoDia = async (str) => {
+        const dow = dateAt(str).getDay();
+        const r = await janelasClinicaNoDia(pool, clinicaId, str, dow, clinicHours);
+        return {
+          data: str, dia_semana: dow, dia_nome: DIAS_NOME[dow],
+          aberto: !r.fechado && r.janelas.length > 0, motivo: r.motivo,
+          horarios: r.janelas.map(([i, f]) => ({ inicio: i, fim: f })),
+        };
+      };
+
+      // Grade dos próximos 7 dias (inclui hoje).
+      const semana = [];
+      for (let k = 0; k < 7; k++) semana.push(await statusDoDia(addYmd(hojeBR, k)));
+      const hoje = semana[0];
+      // Próximo dia aberto: primeiro aberto na semana; se nenhum, varre +14.
+      let proximo = semana.find((s) => s.aberto) || null;
+      if (!proximo) for (let k = 7; k <= 21; k++) { const s = await statusDoDia(addYmd(hojeBR, k)); if (s.aberto) { proximo = s; break; } }
+
+      // Próximos feriados (45 dias) — clínica (1 query) + nacionais (em memória).
+      const feriados = [];
+      let excMap = new Map();
+      try {
+        const { rows } = await pool.query(
+          `SELECT data, nome, fecha, recorrente FROM feriados WHERE clinica_id = $1`, [clinicaId]);
+        for (const r of rows) {
+          const ds = (r.data instanceof Date) ? ymd(r.data) : String(r.data).slice(0, 10);
+          excMap.set(ds, r);
+          if (r.recorrente === 1) excMap.set('R' + ds.slice(5), r);
+        }
+      } catch { /* tabela pode não existir */ }
+      for (let k = 0; k < 45; k++) {
+        const str = addYmd(hojeBR, k);
+        const exc = excMap.get(str) || excMap.get('R' + str.slice(5));
+        if (exc) { if (exc.fecha !== 0) feriados.push({ data: str, nome: exc.nome, origem: 'clinica' }); continue; }
+        const nac = feriadoNacionalNome(str);
+        if (nac) feriados.push({ data: str, nome: nac, origem: 'nacional' });
+      }
+
+      res.json({ hoje, proximo_aberto: proximo, semana, feriados_proximos: feriados.slice(0, 8) });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
+  // ── POST /pedido ──────────────────────────────────────────────────────────────
+  // A Secretária IA registra um pedido de horário FORA da janela livre (zona cinza:
+  // mais cedo/mais tarde) para a SECRETÁRIA HUMANA confirmar. A IA não agenda esses.
+  // Body: { clinica_id, data (YYYY-MM-DD), hora (HH:MM), hora_fim?, dentista_nome?,
+  //         nome_cliente, telefone?, procedimento? }
+  router.post('/pedido', async (req, res) => {
+    const b = req.body || {};
+    if (!b.clinica_id || !b.data || !b.hora) return res.status(400).json({ error: 'clinica_id, data e hora obrigatórios' });
+    try {
+      // Dia totalmente fechado (feriado/fechamento) → não adianta criar pedido.
+      const fer = await resolverFeriado(pool, b.clinica_id, b.data);
+      if (fer && fer.fecha) return res.json({ ok: false, motivo: `Fechado nesse dia (${fer.nome}).` });
+      // Resolve o dentista pelo nome (opcional).
+      let dentistaId = null;
+      if (b.dentista_nome) {
+        const { rows } = await pool.query(
+          `SELECT id FROM dentistas WHERE clinica_id = $1 AND lower(nome) LIKE '%'||lower($2)||'%' LIMIT 1`,
+          [b.clinica_id, b.dentista_nome]);
+        dentistaId = rows[0]?.id || null;
+      }
+      const id = `ped_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+      await pool.query(
+        `INSERT INTO agenda_pedidos (id, clinica_id, dentista_id, data, hora_inicio, hora_fim, paciente_nome, paciente_telefone, procedimento, status)
+           VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,'pendente')`,
+        [id, b.clinica_id, dentistaId, b.data, hm(b.hora), b.hora_fim ? hm(b.hora_fim) : null,
+         b.nome_cliente || null, (String(b.telefone || '').replace(/\D/g, '')) || null, b.procedimento || null]);
+      res.json({ ok: true, pedido_id: id });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  // ── POST /duvida ──────────────────────────────────────────────────────────────
+  // Encaminha uma DÚVIDA/caso incerto à secretária humana (sem agendar). Cria um
+  // agenda_pedidos tipo='duvida' com o resumo; entra na mesma fila de pendentes.
+  router.post('/duvida', async (req, res) => {
+    const b = req.body || {};
+    if (!b.clinica_id || !b.resumo) return res.status(400).json({ error: 'clinica_id e resumo obrigatórios' });
+    try {
+      const id = `ped_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+      await pool.query(
+        `INSERT INTO agenda_pedidos (id, clinica_id, tipo, resumo, paciente_nome, paciente_telefone, status)
+           VALUES ($1,$2,'duvida',$3,$4,$5,'pendente')`,
+        [id, b.clinica_id, String(b.resumo).slice(0, 2000),
+         b.nome_cliente || null, (String(b.telefone || '').replace(/\D/g, '')) || null]);
+      res.json({ ok: true, pedido_id: id });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  // ── GET /contexto ─────────────────────────────────────────────────────────────
+  // Contexto clínico p/ a Secretária: dentistas + especialidades + "situações"
+  // (regras da clínica). Query: clinica_id.
+  router.get('/contexto', async (req, res) => {
+    const clinicaId = String(req.query.clinica_id || '');
+    if (!clinicaId) return res.status(400).json({ error: 'clinica_id obrigatório' });
+    try {
+      const { rows: dentistas } = await pool.query(
+        `SELECT nome, especialidade, especialidades FROM dentistas WHERE clinica_id = $1 AND ativo IS DISTINCT FROM 0 ORDER BY nome`, [clinicaId]);
+      let situacoes = [];
+      try {
+        const { rows } = await pool.query(`SELECT texto FROM agenda_situacoes WHERE clinica_id = $1 AND ativo = 1 ORDER BY ordem, created_at`, [clinicaId]);
+        situacoes = rows.map((r) => r.texto);
+      } catch { /* tabela pode não existir ainda */ }
+      // Cautelas do checklist do dono (declaração × dados reais) → a IA não chuta.
+      let cautelas = [];
+      try {
+        const respostas = {};
+        const { rows } = await pool.query(`SELECT chave, resposta FROM agenda_checklist WHERE clinica_id = $1`, [clinicaId]);
+        for (const r of rows) respostas[r.chave] = r.resposta == null ? null : Number(r.resposta);
+        const nPac = await pool.query(`SELECT COUNT(*) n FROM pacientes WHERE clinica_id = $1`, [clinicaId]).then((x) => Number(x.rows[0]?.n || 0)).catch(() => 0);
+        cautelas = cautelasParaIA(respostas, { dentistas: dentistas.length, pacientes: nPac });
+      } catch { /* checklist novo/indisponível */ }
+      res.json({
+        dentistas: dentistas.map((d) => ({
+          nome: d.nome,
+          especialidades: Array.isArray(d.especialidades) ? d.especialidades : (d.especialidade ? [d.especialidade] : []),
+        })),
+        situacoes,
+        cautelas,
+      });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  // ── GET /dentista-contato ─────────────────────────────────────────────────────
+  // Resolve o WhatsApp de um dentista da clínica (Parte A: a IA aciona o Dr).
+  // Query: clinica_id (obrig.), nome? OU dentista_id?
+  router.get('/dentista-contato', async (req, res) => {
+    const clinicaId = String(req.query.clinica_id || '');
+    if (!clinicaId) return res.status(400).json({ error: 'clinica_id obrigatório' });
+    try {
+      const params = [clinicaId]; let where = 'clinica_id = $1';
+      if (req.query.dentista_id) { params.push(String(req.query.dentista_id)); where += ` AND id = $${params.length}`; }
+      else if (req.query.nome) { params.push(String(req.query.nome)); where += ` AND lower(nome) LIKE '%'||lower($${params.length})||'%'`; }
+      const { rows } = await pool.query(
+        `SELECT id, nome, telefone FROM dentistas WHERE ${where} AND ativo IS DISTINCT FROM 0 ORDER BY nome LIMIT 1`, params);
+      if (!rows.length) return res.json({ encontrado: false });
+      const d = rows[0];
+      const tel = String(d.telefone || '').replace(/\D/g, '');
+      res.json({ encontrado: true, dentista_id: d.id, nome: d.nome, telefone: tel || null });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  // ── POST /book ────────────────────────────────────────────────────────────────
+  // Body: { clinica_id, dentista_id, start, end?, paciente_nome, paciente_celular, procedimento? }
+  router.post('/book', async (req, res) => {
+    const b = req.body || {};
+    if (!b.clinica_id || !b.dentista_id || !b.start) {
+      return res.status(400).json({ error: 'clinica_id, dentista_id e start obrigatórios' });
+    }
+    const end = b.end || new Date(new Date(b.start).getTime() + SLOT_MIN * 60000).toISOString();
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      const conflict = await findConflict(client, b.dentista_id, b.start, end);
+      if (conflict) { await client.query('ROLLBACK'); return res.status(409).json({ error: 'Horário já ocupado.', conflict_id: conflict.id }); }
+
+      // Vincula paciente pelo telefone (escopo da clínica; casa pelos últimos 8 dígitos).
+      let pacienteId = null;
+      let pacienteCriado = false;
+      if (b.paciente_celular) {
+        const tel = String(b.paciente_celular).replace(/\D/g, '').slice(-8);
+        if (tel) {
+          const { rows } = await client.query(
+            `SELECT id FROM pacientes
+              WHERE clinica_id = $1 AND regexp_replace(coalesce(telefone,''),'\\D','','g') LIKE '%'||$2 LIMIT 1`,
+            [b.clinica_id, tel]);
+          pacienteId = rows[0]?.id || null;
+        }
+      }
+      // Não encontrado → cria um paciente mínimo (lead do WhatsApp vira paciente).
+      if (!pacienteId && b.paciente_nome) {
+        const pid = `pac_${Date.now()}_${Math.random().toString(36).substring(2, 7)}`;
+        await client.query(
+          'INSERT INTO pacientes (id, nome, telefone, clinica_id) VALUES ($1,$2,$3,$4)',
+          [pid, b.paciente_nome, b.paciente_celular || null, b.clinica_id]);
+        pacienteId = pid;
+        pacienteCriado = true;
+      }
+      const { rows: dd } = await client.query('SELECT setor_id FROM dentistas WHERE id = $1 AND clinica_id = $2', [b.dentista_id, b.clinica_id]);
+      const setorId = dd[0]?.setor_id || null;
+
+      const id = `ag_${Date.now()}_${Math.random().toString(36).substring(2, 7)}`;
+      const { rows: ins } = await client.query(
+        `INSERT INTO agendamentos
+           (id, clinica_id, pacientenome, pacientecelular, pacienteid, dentistaid, procedimento,
+            start_time, end_time, status, setor_id, created_by_nome, created_at, updated_at, sala_id)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,'agendado',$10,'Secretária IA',NOW(),NOW(),$11)
+         RETURNING id, start_time, end_time, dentistaid`,
+        [id, b.clinica_id, b.paciente_nome || 'Cliente WhatsApp', b.paciente_celular || null,
+         pacienteId, b.dentista_id, b.procedimento || 'Consulta', b.start, end, setorId, b.sala_id || null]);
+      await client.query('COMMIT');
+      res.json({ ok: true, agendamento: ins[0], paciente_vinculado: !!pacienteId, paciente_criado: pacienteCriado });
+    } catch (e) {
+      try { await client.query('ROLLBACK'); } catch { /* ignore */ }
+      res.status(500).json({ error: e.message });
+    } finally {
+      client.release();
+    }
+  });
+
+  // ── GET /encaixe/analisar ─────────────────────────────────────────────────────
+  // Fluxo de "adiantar consulta": dado um dia (e horário desejado), diz se o horário
+  // está OCUPADO (por quem) e qual o horário LIVRE mais cedo que dá para oferecer/
+  // encaixar — incluindo a janela FLEX (zona cinza), pois na contenção a Secretária
+  // pode usá-la. Query: clinica_id, dentista_id?, data (YYYY-MM-DD), hora? (HH:MM).
+  router.get('/encaixe/analisar', async (req, res) => {
+    const clinicaId = String(req.query.clinica_id || '');
+    const data = String(req.query.data || '');
+    if (!clinicaId || !data) return res.status(400).json({ error: 'clinica_id e data obrigatórios' });
+    const dentistaId = req.query.dentista_id ? String(req.query.dentista_id) : null;
+    const horaDesejada = req.query.hora ? String(req.query.hora).slice(0, 5) : null;
+    try {
+      const day = new Date(`${data}T00:00:00`);
+      const dow = day.getDay();
+      const dParams = [clinicaId]; let dWhere = 'clinica_id = $1 AND ativo IS DISTINCT FROM 0';
+      if (dentistaId) { dParams.push(dentistaId); dWhere += ` AND id = $${dParams.length}`; }
+      const { rows: dentistas } = await pool.query(`SELECT id, nome FROM dentistas WHERE ${dWhere}`, dParams);
+      if (!dentistas.length) return res.json({ mais_cedo: null, contestado: null });
+
+      const clinicHours = await carregarHorariosClinica(pool, clinicaId);
+      const { janelas: clinicWins, fechado } = await janelasClinicaNoDia(pool, clinicaId, data, dow, clinicHours);
+      if (fechado || !clinicWins.length) return res.json({ mais_cedo: null, contestado: null, motivo: 'fechado' });
+
+      // Jornada FLEX-inclusiva (usa hora_*_flex quando houver — a zona cinza entra no encaixe).
+      const { rows: horarios } = await pool.query(
+        `SELECT dentista_id,
+                COALESCE(hora_inicio_flex, hora_inicio) AS hora_inicio,
+                COALESCE(hora_fim_flex, hora_fim) AS hora_fim
+           FROM dentistas_horarios WHERE clinica_id = $1 AND ativo = 1 AND dia_semana = $2`, [clinicaId, dow]);
+      const hoursBy = new Map();
+      for (const h of horarios) { const a = hoursBy.get(h.dentista_id) || []; a.push([hm(h.hora_inicio), hm(h.hora_fim)]); hoursBy.set(h.dentista_id, a); }
+
+      const start0 = new Date(day); start0.setHours(0, 0, 0, 0);
+      const end0 = new Date(start0); end0.setDate(end0.getDate() + 1);
+      const { rows: busy } = await pool.query(
+        `SELECT id, dentistaid, pacientenome, pacientecelular, start_time, end_time FROM agendamentos
+          WHERE clinica_id=$1 AND start_time>=$2 AND start_time<$3
+            AND (status IS NULL OR lower(status) NOT IN ('cancelado','falta','remarcar'))`,
+        [clinicaId, start0.toISOString(), end0.toISOString()]);
+      const busyBy = new Map();
+      for (const bz of busy) { const a = busyBy.get(bz.dentistaid) || []; a.push(bz); busyBy.set(bz.dentistaid, a); }
+
+      // Quem ocupa o horário desejado (direto, sem depender do grid).
+      let contestado = null;
+      if (horaDesejada) {
+        const alvo = new Date(`${data}T${horaDesejada}:00`);
+        const occ = busy.find((b) => new Date(b.start_time) <= alvo && new Date(b.end_time || b.start_time) > alvo)
+                 || busy.find((b) => fmt(new Date(b.start_time)).slice(11, 16) === horaDesejada);
+        if (occ) {
+          const dn = dentistas.find((d) => d.id === occ.dentistaid);
+          contestado = { agendamento_id: occ.id, dentista_id: occ.dentistaid, dentista_nome: dn?.nome || null,
+            paciente_nome: occ.pacientenome || null, paciente_celular: occ.pacientecelular || null,
+            start: fmt(new Date(occ.start_time)), hora: fmt(new Date(occ.start_time)).slice(11, 16) };
+        }
+      }
+
+      // Slots LIVRES do dia (flex-inclusivo).
+      const now = new Date(); const dur = SLOT_MIN; const livres = [];
+      for (const dent of dentistas) {
+        const dw = (hoursBy.get(dent.id) && hoursBy.get(dent.id).length) ? hoursBy.get(dent.id) : clinicWins;
+        const windows = interseccao(clinicWins, dw);
+        const bs = busyBy.get(dent.id) || [];
+        for (const [ini, fim] of windows) {
+          const [hi, mi] = String(ini).split(':').map(Number);
+          const [hf, mf] = String(fim).split(':').map(Number);
+          let t = new Date(day); t.setHours(hi, mi || 0, 0, 0);
+          const limit = new Date(day); limit.setHours(hf, mf || 0, 0, 0);
+          while (t.getTime() + dur * 60000 <= limit.getTime()) {
+            const s = new Date(t), e = new Date(t.getTime() + dur * 60000); t = e;
+            if (s <= now) continue;
+            if (bs.some((b) => new Date(b.start_time) < e && new Date(b.end_time || b.start_time) > s)) continue;
+            livres.push({ dentista_id: dent.id, dentista_nome: dent.nome, start: fmt(s), end: fmt(e), hora: fmt(s).slice(11, 16) });
+          }
+        }
+      }
+      livres.sort((a, b) => a.start.localeCompare(b.start));
+      // mais_cedo = livre imediatamente ANTES do desejado (o mais perto por baixo); senão o 1º livre.
+      let mais_cedo = null;
+      if (horaDesejada) {
+        const antes = livres.filter((s) => s.hora < horaDesejada);
+        mais_cedo = antes.length ? antes[antes.length - 1] : (livres[0] || null);
+      } else {
+        mais_cedo = livres[0] || null;
+      }
+      res.json({ mais_cedo, contestado, total_livres: livres.length });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  // ── POST /encaixe/mover ───────────────────────────────────────────────────────
+  // Move um agendamento existente para um novo horário (o A aceitou adiantar).
+  // Body: { clinica_id, agendamento_id, start, end? }.
+  router.post('/encaixe/mover', async (req, res) => {
+    const b = req.body || {};
+    if (!b.clinica_id || !b.agendamento_id || !b.start) return res.status(400).json({ error: 'clinica_id, agendamento_id e start obrigatórios' });
+    const end = b.end || new Date(new Date(b.start).getTime() + SLOT_MIN * 60000).toISOString();
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      const { rows } = await client.query('SELECT id, dentistaid FROM agendamentos WHERE id=$1 AND clinica_id=$2 FOR UPDATE', [b.agendamento_id, b.clinica_id]);
+      const ag = rows[0];
+      if (!ag) { await client.query('ROLLBACK'); return res.status(404).json({ error: 'Agendamento não encontrado.' }); }
+      const conflict = await findConflict(client, ag.dentistaid, b.start, end, b.agendamento_id);
+      if (conflict) { await client.query('ROLLBACK'); return res.status(409).json({ error: 'Horário de destino já ocupado.' }); }
+      await client.query('UPDATE agendamentos SET start_time=$1, end_time=$2, updated_at=NOW() WHERE id=$3', [b.start, end, b.agendamento_id]);
+      await client.query('COMMIT');
+      res.json({ ok: true });
+    } catch (e) { try { await client.query('ROLLBACK'); } catch { /* ignore */ } res.status(500).json({ error: e.message }); }
+    finally { client.release(); }
+  });
+
+  // ════════ Cadastro de pacientes (Secretária super inteligente) ════════════════
+  const soDigitos = (v) => String(v || '').replace(/\D/g, '');
+  function idadeDe(dob) {
+    if (!dob) return null;
+    const s = String(dob).trim();
+    let d = null, m = s.match(/^(\d{4})-(\d{2})-(\d{2})/);
+    if (m) d = new Date(+m[1], +m[2] - 1, +m[3]);
+    else { m = s.match(/^(\d{2})\/(\d{2})\/(\d{4})/); if (m) d = new Date(+m[3], +m[2] - 1, +m[1]); }
+    if (!d || isNaN(d.getTime())) return null;
+    const n = new Date(); let a = n.getFullYear() - d.getFullYear();
+    const mo = n.getMonth() - d.getMonth();
+    if (mo < 0 || (mo === 0 && n.getDate() < d.getDate())) a--;
+    return a >= 0 && a < 130 ? a : null;
+  }
+
+  // GET /pacientes/lookup?clinica_id=&phone= — quem está cadastrado NESTE número (a família).
+  router.get('/pacientes/lookup', async (req, res) => {
+    const clinicaId = String(req.query.clinica_id || '');
+    const tel = soDigitos(req.query.phone).slice(-8);
+    if (!clinicaId || !tel) return res.status(400).json({ error: 'clinica_id e phone obrigatórios' });
+    try {
+      const { rows } = await pool.query(
+        `SELECT id, nome, cpf, telefone, datanascimento, convenio, grupofamiliarid, grupofamiliarrelacao
+           FROM pacientes
+          WHERE clinica_id = $1 AND regexp_replace(coalesce(telefone,''),'\\D','','g') LIKE '%'||$2
+          ORDER BY (grupofamiliarrelacao = 'titular' OR grupofamiliarrelacao IS NULL) DESC, nome`,
+        [clinicaId, tel]);
+      res.json({
+        encontrados: rows.length,
+        pacientes: rows.map((p) => ({
+          id: p.id, nome: p.nome, cpf: p.cpf || null,
+          data_nascimento: p.datanascimento || null, idade: idadeDe(p.datanascimento),
+          convenio: p.convenio || null, relacao: p.grupofamiliarrelacao || null, grupo_id: p.grupofamiliarid || null,
+        })),
+      });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  // POST /pacientes — cadastra/atualiza. Dedup por CPF; idade por nascimento; grupo familiar
+  // (dependente vinculado ao titular via grupofamiliarid = id do titular).
+  router.post('/pacientes', async (req, res) => {
+    const b = req.body || {};
+    if (!b.clinica_id || !b.nome) return res.status(400).json({ error: 'clinica_id e nome obrigatórios' });
+    const cpf = soDigitos(b.cpf);
+    const telefone = b.telefone ? soDigitos(b.telefone) : null;
+    const idade = idadeDe(b.data_nascimento);
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      // 1) Dedup forte por CPF (identificador confiável — evita duplicar quem já existe).
+      let existente = null;
+      if (cpf) {
+        const { rows } = await client.query(
+          `SELECT * FROM pacientes WHERE clinica_id=$1 AND regexp_replace(coalesce(cpf,''),'\\D','','g')=$2 LIMIT 1`, [b.clinica_id, cpf]);
+        existente = rows[0] || null;
+      }
+      // 2) Resolve o RESPONSÁVEL (para dependentes): por id, cpf ou telefone (o titular do número).
+      let responsavel = null;
+      if (b.responsavel_id) {
+        const { rows } = await client.query('SELECT * FROM pacientes WHERE id=$1 AND clinica_id=$2', [b.responsavel_id, b.clinica_id]); responsavel = rows[0] || null;
+      } else if (b.responsavel_cpf) {
+        const { rows } = await client.query(`SELECT * FROM pacientes WHERE clinica_id=$1 AND regexp_replace(coalesce(cpf,''),'\\D','','g')=$2 LIMIT 1`, [b.clinica_id, soDigitos(b.responsavel_cpf)]); responsavel = rows[0] || null;
+      } else if (b.responsavel_telefone) {
+        const { rows } = await client.query(
+          `SELECT * FROM pacientes WHERE clinica_id=$1 AND regexp_replace(coalesce(telefone,''),'\\D','','g') LIKE '%'||$2
+             AND (grupofamiliarrelacao='titular' OR grupofamiliarrelacao IS NULL) ORDER BY nome LIMIT 1`,
+          [b.clinica_id, soDigitos(b.responsavel_telefone).slice(-8)]); responsavel = rows[0] || null;
+      }
+      // Dependente = tem responsável OU menor de 18 (padrão) sem marcar eh_titular.
+      const ehDependente = !!responsavel || (idade != null && idade < 18 && !b.eh_titular);
+      let relacao = b.relacao || (ehDependente ? (idade != null && idade < 18 ? 'filho(a)' : 'dependente') : (b.eh_titular ? 'titular' : null));
+      // Telefone do dependente sem número próprio → herda o do responsável (compartilhado).
+      let telFinal = telefone;
+      if (ehDependente && !telFinal && responsavel && responsavel.telefone) telFinal = soDigitos(responsavel.telefone);
+      // 3) Grupo familiar: titular vira cabeça (grupofamiliarid = id do titular) + grupos_familiares.
+      let grupoId = null;
+      if (ehDependente && responsavel) {
+        grupoId = responsavel.grupofamiliarid || responsavel.id;
+        if (!responsavel.grupofamiliarid) {
+          await client.query(`UPDATE pacientes SET grupofamiliarid=$1, grupofamiliarrelacao=COALESCE(grupofamiliarrelacao,'titular') WHERE id=$1`, [responsavel.id]);
+        }
+        await client.query(`INSERT INTO grupos_familiares (id, nome, responsavel_id, created_at) VALUES ($1,$2,$3,NOW()) ON CONFLICT (id) DO NOTHING`, [grupoId, responsavel.nome, responsavel.id]);
+      }
+      // 4) Atualiza (dedup) OU cria.
+      if (existente) {
+        await client.query(
+          `UPDATE pacientes SET nome=$2, telefone=COALESCE($3,telefone), email=COALESCE($4,email),
+             convenio=COALESCE($5,convenio), datanascimento=COALESCE($6,datanascimento),
+             grupofamiliarid=COALESCE($7,grupofamiliarid), grupofamiliarrelacao=COALESCE($8,grupofamiliarrelacao) WHERE id=$1`,
+          [existente.id, b.nome, telFinal, b.email || null, b.convenio || null, b.data_nascimento || null, grupoId, relacao]);
+        await client.query('COMMIT');
+        return res.json({ ok: true, atualizado: true, paciente: { id: existente.id, nome: b.nome, relacao, grupo_id: grupoId, idade } });
+      }
+      const id = `pac_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+      await client.query(
+        `INSERT INTO pacientes (id, clinica_id, nome, cpf, telefone, email, convenio, datanascimento, grupofamiliarid, grupofamiliarrelacao)
+           VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)`,
+        [id, b.clinica_id, b.nome, cpf || null, telFinal, b.email || null, b.convenio || null, b.data_nascimento || null, grupoId, relacao]);
+      await client.query('COMMIT');
+      res.json({ ok: true, criado: true, paciente: { id, nome: b.nome, cpf: cpf || null, relacao, grupo_id: grupoId, idade, dependente: ehDependente } });
+    } catch (e) {
+      try { await client.query('ROLLBACK'); } catch { /* ignore */ }
+      res.status(500).json({ error: e.message });
+    } finally { client.release(); }
+  });
+
+  return router;
+}

backend/newwhats/agenda-config.js

@@ -0,0 +1,404 @@
+// Config de horários/feriados — API para o FRONTEND do scoreodonto (dono/dentista).
+// Auth: JWT do scoreodonto (Authorization: Bearer). Ownership:
+//   - Horário da CLÍNICA + feriados  → só o DONO (clinicas.owner_id / vínculo dono).
+//   - Horário do DENTISTA            → o próprio dentista (dentistas.usuario_id) OU o dono.
+//
+// Montado em /api/nw/agenda-config pelo registerNewwhats.
+import express from 'express';
+import jwt from 'jsonwebtoken';
+import { feriadosNacionais } from './feriados.js';
+import { CHECKLIST_QUESTOES, pendenciasDeConfig } from './checklist-defs.js';
+
+function authFromReq(req) {
+  try {
+    const tk = (req.headers['authorization'] || '').replace(/^Bearer\s+/i, '').trim();
+    if (!tk) return null;
+    const p = jwt.verify(tk, process.env.JWT_SECRET);
+    return { userId: p.userId || null, email: (p.email || '').toLowerCase() || null };
+  } catch { return null; }
+}
+
+// É dono do workspace (clínica)? owner_id direto OU vínculo dono/admin.
+async function isDono(pool, clinicaId, userId) {
+  if (!clinicaId || !userId) return false;
+  try {
+    const { rows: cl } = await pool.query('SELECT owner_id FROM clinicas WHERE id = $1', [clinicaId]);
+    if (cl[0]?.owner_id && cl[0].owner_id === userId) return true;
+    const { rows: v } = await pool.query(
+      `SELECT 1 FROM vinculos WHERE clinica_id = $1 AND usuario_id = $2
+         AND role IN ('donoclinica','donoconsultorio','admin') LIMIT 1`, [clinicaId, userId]);
+    return v.length > 0;
+  } catch { return false; }
+}
+
+const uid = (p) => `${p}_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+const hhmm = (v) => { const m = String(v ?? '').match(/^(\d{1,2}):(\d{2})/); return m ? `${m[1].padStart(2, '0')}:${m[2]}` : null; };
+
+export function createAgendaConfig(pool) {
+  const router = express.Router();
+
+  router.use((req, res, next) => {
+    const auth = authFromReq(req);
+    if (!auth) return res.status(401).json({ error: 'Sessão inválida.' });
+    req.nwUser = auth;
+    next();
+  });
+
+  // ── Horário de FUNCIONAMENTO da clínica (dono) ────────────────────────────────
+  router.get('/clinica/:clinicaId/horarios', async (req, res) => {
+    try {
+      const { rows } = await pool.query(
+        `SELECT id, dia_semana, to_char(hora_inicio,'HH24:MI') AS hora_inicio,
+                to_char(hora_fim,'HH24:MI') AS hora_fim, ativo
+           FROM clinicas_horarios WHERE clinica_id = $1 ORDER BY dia_semana, hora_inicio`,
+        [req.params.clinicaId]);
+      res.json({ horarios: rows });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  // Substitui TODA a grade da clínica (mais simples e previsível que patch por dia).
+  // Body: { horarios: [{ dia_semana, hora_inicio, hora_fim }] }
+  router.put('/clinica/:clinicaId/horarios', async (req, res) => {
+    const clinicaId = req.params.clinicaId;
+    if (!(await isDono(pool, clinicaId, req.nwUser.userId)))
+      return res.status(403).json({ error: 'Apenas o dono pode configurar o horário da clínica.' });
+    const linhas = Array.isArray(req.body?.horarios) ? req.body.horarios : [];
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      await client.query('DELETE FROM clinicas_horarios WHERE clinica_id = $1', [clinicaId]);
+      for (const h of linhas) {
+        const dow = Number(h.dia_semana); const ini = hhmm(h.hora_inicio); const fim = hhmm(h.hora_fim);
+        if (!(dow >= 0 && dow <= 6) || !ini || !fim || ini >= fim) continue;
+        await client.query(
+          `INSERT INTO clinicas_horarios (id, clinica_id, dia_semana, hora_inicio, hora_fim, ativo)
+             VALUES ($1,$2,$3,$4,$5,1)`, [uid('ch'), clinicaId, dow, ini, fim]);
+      }
+      await client.query('COMMIT');
+      res.json({ ok: true });
+    } catch (e) { try { await client.query('ROLLBACK'); } catch {} res.status(500).json({ error: e.message }); }
+    finally { client.release(); }
+  });
+
+  // ── Horário do DENTISTA (o próprio dentista ou o dono) ────────────────────────
+  router.get('/dentista/:dentistaId/horarios', async (req, res) => {
+    try {
+      const { rows } = await pool.query(
+        `SELECT id, dia_semana, to_char(hora_inicio,'HH24:MI') AS hora_inicio,
+                to_char(hora_fim,'HH24:MI') AS hora_fim,
+                to_char(hora_inicio_flex,'HH24:MI') AS hora_inicio_flex,
+                to_char(hora_fim_flex,'HH24:MI') AS hora_fim_flex, ativo
+           FROM dentistas_horarios WHERE dentista_id = $1 ORDER BY dia_semana, hora_inicio`,
+        [req.params.dentistaId]);
+      res.json({ horarios: rows });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  router.put('/dentista/:dentistaId/horarios', async (req, res) => {
+    const dentistaId = req.params.dentistaId;
+    let dent;
+    try { const { rows } = await pool.query('SELECT clinica_id, usuario_id FROM dentistas WHERE id = $1', [dentistaId]); dent = rows[0]; }
+    catch (e) { return res.status(500).json({ error: e.message }); }
+    if (!dent) return res.status(404).json({ error: 'Dentista não encontrado.' });
+    const ehProprio = dent.usuario_id && dent.usuario_id === req.nwUser.userId;
+    const ehDono = await isDono(pool, dent.clinica_id, req.nwUser.userId);
+    if (!ehProprio && !ehDono)
+      return res.status(403).json({ error: 'Só o próprio dentista (ou o dono) pode configurar estes horários.' });
+    const linhas = Array.isArray(req.body?.horarios) ? req.body.horarios : [];
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      await client.query('DELETE FROM dentistas_horarios WHERE dentista_id = $1', [dentistaId]);
+      for (const h of linhas) {
+        const dow = Number(h.dia_semana); const ini = hhmm(h.hora_inicio); const fim = hhmm(h.hora_fim);
+        if (!(dow >= 0 && dow <= 6) || !ini || !fim || ini >= fim) continue;
+        // Janela estendida (zona cinza): flex_inicio ≤ inicio e flex_fim ≥ fim.
+        let fIni = hhmm(h.hora_inicio_flex), fFim = hhmm(h.hora_fim_flex);
+        if (fIni && fIni >= ini) fIni = null;   // só vale se for MAIS cedo
+        if (fFim && fFim <= fim) fFim = null;   // só vale se for MAIS tarde
+        await client.query(
+          `INSERT INTO dentistas_horarios (id, dentista_id, clinica_id, dia_semana, hora_inicio, hora_fim, hora_inicio_flex, hora_fim_flex, ativo)
+             VALUES ($1,$2,$3,$4,$5,$6,$7,$8,1)`, [uid('dh'), dentistaId, dent.clinica_id, dow, ini, fim, fIni, fFim]);
+      }
+      await client.query('COMMIT');
+      res.json({ ok: true });
+    } catch (e) { try { await client.query('ROLLBACK'); } catch {} res.status(500).json({ error: e.message }); }
+    finally { client.release(); }
+  });
+
+  // ── Folgas/férias do DENTISTA por data (o próprio dentista ou o dono) ─────────
+  async function guardDentista(pool, dentistaId, user) {
+    const { rows } = await pool.query('SELECT clinica_id, usuario_id FROM dentistas WHERE id = $1', [dentistaId]);
+    const dent = rows[0];
+    if (!dent) return { ok: false, code: 404, msg: 'Dentista não encontrado.' };
+    const ehProprio = dent.usuario_id && dent.usuario_id === user.userId;
+    const ehDono = await isDono(pool, dent.clinica_id, user.userId);
+    if (!ehProprio && !ehDono) return { ok: false, code: 403, msg: 'Só o próprio dentista (ou o dono) pode alterar.' };
+    return { ok: true, dent };
+  }
+
+  router.get('/dentista/:dentistaId/folgas', async (req, res) => {
+    try {
+      const { rows } = await pool.query(
+        `SELECT id, to_char(data_inicio,'YYYY-MM-DD') AS data_inicio, to_char(data_fim,'YYYY-MM-DD') AS data_fim, motivo
+           FROM dentistas_folgas WHERE dentista_id = $1 AND data_fim >= CURRENT_DATE ORDER BY data_inicio`,
+        [req.params.dentistaId]);
+      res.json({ folgas: rows });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  // Body: { data_inicio (YYYY-MM-DD), data_fim? (def = inicio), motivo? }
+  router.post('/dentista/:dentistaId/folgas', async (req, res) => {
+    const g = await guardDentista(pool, req.params.dentistaId, req.nwUser).catch((e) => ({ ok: false, code: 500, msg: e.message }));
+    if (!g.ok) return res.status(g.code).json({ error: g.msg });
+    const b = req.body || {};
+    if (!b.data_inicio) return res.status(400).json({ error: 'data_inicio obrigatória' });
+    const fim = b.data_fim && b.data_fim >= b.data_inicio ? b.data_fim : b.data_inicio;
+    try {
+      const { rows } = await pool.query(
+        `INSERT INTO dentistas_folgas (id, dentista_id, clinica_id, data_inicio, data_fim, motivo)
+           VALUES ($1,$2,$3,$4,$5,$6)
+         RETURNING id, to_char(data_inicio,'YYYY-MM-DD') AS data_inicio, to_char(data_fim,'YYYY-MM-DD') AS data_fim, motivo`,
+        [uid('fol'), req.params.dentistaId, g.dent.clinica_id, b.data_inicio, fim, b.motivo || null]);
+      res.status(201).json(rows[0]);
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  router.delete('/dentista/:dentistaId/folgas/:id', async (req, res) => {
+    const g = await guardDentista(pool, req.params.dentistaId, req.nwUser).catch((e) => ({ ok: false, code: 500, msg: e.message }));
+    if (!g.ok) return res.status(g.code).json({ error: g.msg });
+    try { await pool.query('DELETE FROM dentistas_folgas WHERE id = $1 AND dentista_id = $2', [req.params.id, req.params.dentistaId]); res.json({ ok: true }); }
+    catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  // ── Feriados/fechamentos (dono) ───────────────────────────────────────────────
+  // Lista os NACIONAIS (computados) + as exceções da clínica de um ano.
+  router.get('/clinica/:clinicaId/feriados', async (req, res) => {
+    const clinicaId = req.params.clinicaId;
+    const ano = Number(req.query.ano) || new Date().getFullYear();
+    try {
+      const nac = Object.entries(feriadosNacionais(ano)).map(([data, nome]) => ({ data, nome, origem: 'nacional' }));
+      const { rows: exc } = await pool.query(
+        `SELECT id, to_char(data,'YYYY-MM-DD') AS data, nome, fecha,
+                to_char(hora_inicio,'HH24:MI') AS hora_inicio, to_char(hora_fim,'HH24:MI') AS hora_fim, recorrente
+           FROM feriados WHERE clinica_id = $1 AND (extract(year from data) = $2 OR recorrente = 1) ORDER BY data`,
+        [clinicaId, ano]);
+      res.json({ nacionais: nac, excecoes: exc.map((e) => ({ ...e, origem: 'clinica' })) });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  // Cria uma exceção da clínica (fechamento/ponte/horário especial). Dono.
+  // Body: { data (YYYY-MM-DD), nome, fecha?(bool), hora_inicio?, hora_fim?, recorrente?(bool) }
+  router.post('/clinica/:clinicaId/feriados', async (req, res) => {
+    const clinicaId = req.params.clinicaId;
+    if (!(await isDono(pool, clinicaId, req.nwUser.userId)))
+      return res.status(403).json({ error: 'Apenas o dono pode configurar feriados/fechamentos.' });
+    const b = req.body || {};
+    if (!b.data || !b.nome) return res.status(400).json({ error: 'data e nome obrigatórios' });
+    const fecha = b.fecha === false ? 0 : 1;
+    const ini = fecha ? null : hhmm(b.hora_inicio);
+    const fim = fecha ? null : hhmm(b.hora_fim);
+    try {
+      const { rows } = await pool.query(
+        `INSERT INTO feriados (id, clinica_id, data, nome, fecha, hora_inicio, hora_fim, recorrente)
+           VALUES ($1,$2,$3,$4,$5,$6,$7,$8)
+         RETURNING id, to_char(data,'YYYY-MM-DD') AS data, nome, fecha, recorrente`,
+        [uid('fer'), clinicaId, b.data, b.nome, fecha, ini, fim, b.recorrente ? 1 : 0]);
+      res.status(201).json(rows[0]);
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  router.delete('/clinica/:clinicaId/feriados/:id', async (req, res) => {
+    if (!(await isDono(pool, req.params.clinicaId, req.nwUser.userId)))
+      return res.status(403).json({ error: 'Apenas o dono pode remover feriados/fechamentos.' });
+    try {
+      await pool.query('DELETE FROM feriados WHERE id = $1 AND clinica_id = $2', [req.params.id, req.params.clinicaId]);
+      res.json({ ok: true });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  // ── Situações / regras da clínica (dono) — a "área de situações" da Secretária ─
+  router.get('/clinica/:clinicaId/situacoes', async (req, res) => {
+    try {
+      const { rows } = await pool.query(`SELECT id, texto, ativo, ordem FROM agenda_situacoes WHERE clinica_id = $1 ORDER BY ordem, created_at`, [req.params.clinicaId]);
+      res.json({ situacoes: rows });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+  // Substitui toda a lista. Body: { situacoes: [texto] }
+  router.put('/clinica/:clinicaId/situacoes', async (req, res) => {
+    const clinicaId = req.params.clinicaId;
+    if (!(await isDono(pool, clinicaId, req.nwUser.userId))) return res.status(403).json({ error: 'Apenas o dono pode configurar as situações.' });
+    const linhas = Array.isArray(req.body?.situacoes) ? req.body.situacoes : [];
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      await client.query('DELETE FROM agenda_situacoes WHERE clinica_id = $1', [clinicaId]);
+      let i = 0;
+      for (const s of linhas) {
+        const t = String(s || '').trim(); if (!t) continue;
+        await client.query(`INSERT INTO agenda_situacoes (id, clinica_id, texto, ativo, ordem) VALUES ($1,$2,$3,1,$4)`, [uid('sit'), clinicaId, t, i++]);
+      }
+      await client.query('COMMIT'); res.json({ ok: true });
+    } catch (e) { try { await client.query('ROLLBACK'); } catch {} res.status(500).json({ error: e.message }); }
+    finally { client.release(); }
+  });
+
+  // ── Checklist do DONO + pendências (só o dono do workspace) ───────────────────
+  // Conta dentistas/pacientes reais da clínica p/ conferir contra as respostas.
+  async function contagens(clinicaId) {
+    const q = async (sql) => { try { const { rows } = await pool.query(sql, [clinicaId]); return Number(rows[0]?.n || 0); } catch { return 0; } };
+    const dentistas = await q(`SELECT COUNT(*) n FROM dentistas WHERE clinica_id = $1 AND ativo IS DISTINCT FROM 0`);
+    const pacientes = await q(`SELECT COUNT(*) n FROM pacientes WHERE clinica_id = $1`);
+    return { dentistas, pacientes };
+  }
+  async function respostasChecklist(clinicaId) {
+    const map = {};
+    try { const { rows } = await pool.query('SELECT chave, resposta FROM agenda_checklist WHERE clinica_id = $1', [clinicaId]); for (const r of rows) map[r.chave] = r.resposta == null ? null : Number(r.resposta); } catch { /* tabela nova */ }
+    return map;
+  }
+
+  router.get('/clinica/:clinicaId/checklist', async (req, res) => {
+    const clinicaId = req.params.clinicaId;
+    if (!(await isDono(pool, clinicaId, req.nwUser.userId))) return res.status(403).json({ error: 'Apenas o dono acessa o checklist.' });
+    try {
+      const map = await respostasChecklist(clinicaId);
+      res.json({ questoes: CHECKLIST_QUESTOES.map((q) => ({ ...q, resposta: map[q.chave] ?? null })) });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+  // Salva respostas. Body: { respostas: { chave: 1|0|null } }
+  router.put('/clinica/:clinicaId/checklist', async (req, res) => {
+    const clinicaId = req.params.clinicaId;
+    if (!(await isDono(pool, clinicaId, req.nwUser.userId))) return res.status(403).json({ error: 'Apenas o dono pode configurar o checklist.' });
+    const respostas = req.body?.respostas || {};
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      for (const q of CHECKLIST_QUESTOES) {
+        if (!(q.chave in respostas)) continue;
+        const v = respostas[q.chave];
+        const r = v === 1 || v === true ? 1 : v === 0 || v === false ? 0 : null;
+        await client.query(
+          `INSERT INTO agenda_checklist (clinica_id, chave, resposta, updated_at) VALUES ($1,$2,$3,now())
+             ON CONFLICT (clinica_id, chave) DO UPDATE SET resposta = EXCLUDED.resposta, updated_at = now()`,
+          [clinicaId, q.chave, r]);
+      }
+      await client.query('COMMIT'); res.json({ ok: true });
+    } catch (e) { try { await client.query('ROLLBACK'); } catch {} res.status(500).json({ error: e.message }); }
+    finally { client.release(); }
+  });
+
+  // Área de pendências do DONO — engloba TUDO: pendências de config (checklist ×
+  // banco) + a fila operacional (pedidos de horário + dúvidas aguardando humano).
+  router.get('/clinica/:clinicaId/pendencias', async (req, res) => {
+    const clinicaId = req.params.clinicaId;
+    if (!(await isDono(pool, clinicaId, req.nwUser.userId))) return res.status(403).json({ error: 'Apenas o dono acessa as pendências.' });
+    try {
+      const counts = await contagens(clinicaId);
+      const respostas = await respostasChecklist(clinicaId);
+      const config = pendenciasDeConfig(respostas, counts);
+      let horarios = 0, duvidas = 0;
+      try {
+        const { rows } = await pool.query(
+          `SELECT COALESCE(tipo,'horario') tipo, COUNT(*) n FROM agenda_pedidos WHERE clinica_id = $1 AND status = 'pendente' GROUP BY 1`, [clinicaId]);
+        for (const r of rows) { if (r.tipo === 'duvida') duvidas = Number(r.n); else horarios = Number(r.n); }
+      } catch { /* tabela nova */ }
+      res.json({
+        contagens: counts,
+        config,
+        operacionais: { horarios, duvidas, total: horarios + duvidas },
+        total: config.length + horarios + duvidas,
+      });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  // ── Pedidos pendentes (zona cinza) — a secretária humana confirma/recusa ──────
+  async function ehMembro(clinicaId, userId) {
+    if (await isDono(pool, clinicaId, userId)) return true;
+    try { const { rows } = await pool.query('SELECT 1 FROM vinculos WHERE clinica_id = $1 AND usuario_id = $2 LIMIT 1', [clinicaId, userId]); return rows.length > 0; }
+    catch { return false; }
+  }
+
+  router.get('/clinica/:clinicaId/pedidos', async (req, res) => {
+    if (!(await ehMembro(req.params.clinicaId, req.nwUser.userId))) return res.status(403).json({ error: 'Sem acesso.' });
+    const status = req.query.status ? String(req.query.status) : 'pendente';
+    try {
+      const { rows } = await pool.query(
+        `SELECT p.id, COALESCE(p.tipo,'horario') AS tipo, p.resumo,
+                to_char(p.data,'YYYY-MM-DD') AS data, to_char(p.hora_inicio,'HH24:MI') AS hora_inicio,
+                to_char(p.hora_fim,'HH24:MI') AS hora_fim, p.paciente_nome, p.paciente_telefone, p.procedimento,
+                p.dentista_id, d.nome AS dentista_nome, p.status, p.created_at
+           FROM agenda_pedidos p LEFT JOIN dentistas d ON d.id = p.dentista_id
+          WHERE p.clinica_id = $1 AND p.status = $2 ORDER BY p.created_at DESC LIMIT 100`,
+        [req.params.clinicaId, status]);
+      res.json({ pedidos: rows, total: rows.length });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  // Confirma → cria o agendamento real e marca o pedido como confirmado.
+  // Body: { dentista_id? (se o pedido não tinha), duracao_min? }
+  router.post('/clinica/:clinicaId/pedidos/:id/confirmar', async (req, res) => {
+    const clinicaId = req.params.clinicaId;
+    if (!(await ehMembro(clinicaId, req.nwUser.userId))) return res.status(403).json({ error: 'Sem acesso.' });
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      const { rows } = await client.query('SELECT * FROM agenda_pedidos WHERE id = $1 AND clinica_id = $2 FOR UPDATE', [req.params.id, clinicaId]);
+      const ped = rows[0];
+      if (!ped) { await client.query('ROLLBACK'); return res.status(404).json({ error: 'Pedido não encontrado.' }); }
+      if (ped.status !== 'pendente') { await client.query('ROLLBACK'); return res.status(409).json({ error: 'Pedido já resolvido.' }); }
+      const dentistaId = req.body?.dentista_id || ped.dentista_id;
+      if (!dentistaId) { await client.query('ROLLBACK'); return res.status(400).json({ error: 'Escolha o dentista para confirmar.' }); }
+      const dur = Math.max(10, Number(req.body?.duracao_min) || 30);
+      const hi = String(ped.hora_inicio).slice(0, 5);
+      const start = `${(ped.data instanceof Date ? ped.data.toISOString().slice(0, 10) : String(ped.data).slice(0, 10))} ${hi}:00`;
+      const endD = new Date(`${start.replace(' ', 'T')}`); endD.setMinutes(endD.getMinutes() + dur);
+      const end = `${start.slice(0, 10)} ${String(endD.getHours()).padStart(2, '0')}:${String(endD.getMinutes()).padStart(2, '0')}:00`;
+      const { rows: dd } = await client.query('SELECT setor_id FROM dentistas WHERE id = $1', [dentistaId]);
+      const agId = `ag_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+      await client.query(
+        `INSERT INTO agendamentos (id, clinica_id, pacientenome, pacientecelular, dentistaid, procedimento,
+           start_time, end_time, status, setor_id, sala_id, created_by_nome, created_at, updated_at)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,'agendado',$9,$10,'Secretária (confirmado)',NOW(),NOW())`,
+        [agId, clinicaId, ped.paciente_nome || 'Cliente WhatsApp', ped.paciente_telefone || null, dentistaId,
+         ped.procedimento || 'Consulta', start, end, dd[0]?.setor_id || null, ped.sala_id || null]);
+      await client.query(`UPDATE agenda_pedidos SET status='confirmado', agendamento_id=$1, resolved_at=NOW(), resolved_by=$2 WHERE id=$3`,
+        [agId, req.nwUser.userId, req.params.id]);
+      await client.query('COMMIT');
+      res.json({ ok: true, agendamento_id: agId });
+    } catch (e) { try { await client.query('ROLLBACK'); } catch {} res.status(500).json({ error: e.message }); }
+    finally { client.release(); }
+  });
+
+  // Resolve uma DÚVIDA (tipo='duvida') sem criar agendamento — a humana já
+  // decidiu/atendeu (ou vai agendar manualmente uma avaliação).
+  router.post('/clinica/:clinicaId/pedidos/:id/resolver', async (req, res) => {
+    if (!(await ehMembro(req.params.clinicaId, req.nwUser.userId))) return res.status(403).json({ error: 'Sem acesso.' });
+    try {
+      await pool.query(`UPDATE agenda_pedidos SET status='resolvido', resolved_at=NOW(), resolved_by=$1 WHERE id=$2 AND clinica_id=$3 AND status='pendente'`,
+        [req.nwUser.userId, req.params.id, req.params.clinicaId]);
+      res.json({ ok: true });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  router.post('/clinica/:clinicaId/pedidos/:id/recusar', async (req, res) => {
+    if (!(await ehMembro(req.params.clinicaId, req.nwUser.userId))) return res.status(403).json({ error: 'Sem acesso.' });
+    try {
+      await pool.query(`UPDATE agenda_pedidos SET status='recusado', resolved_at=NOW(), resolved_by=$1 WHERE id=$2 AND clinica_id=$3 AND status='pendente'`,
+        [req.nwUser.userId, req.params.id, req.params.clinicaId]);
+      res.json({ ok: true });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  // Lista dentistas da clínica (p/ a UI do dono escolher quem configurar / e o
+  // dentista achar seu registro). Retorna também se o usuário logado é o dentista.
+  router.get('/clinica/:clinicaId/dentistas', async (req, res) => {
+    try {
+      const { rows } = await pool.query(
+        `SELECT id, nome, usuario_id, ativo FROM dentistas WHERE clinica_id = $1 ORDER BY ordem NULLS LAST, nome`,
+        [req.params.clinicaId]);
+      res.json({ dentistas: rows.map((d) => ({ ...d, eh_voce: d.usuario_id === req.nwUser.userId })) });
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  return router;
+}

backend/newwhats/agenda-schema.js

@@ -0,0 +1,118 @@
+// Schema (idempotente) das tabelas de horário/feriado usadas pela Secretária.
+// Chamado uma vez no registerNewwhats. Espelha os tipos de `dentistas_horarios`.
+//
+//  clinicas_horarios — horário de FUNCIONAMENTO da clínica (config do DONO).
+//  feriados          — EXCEÇÕES da clínica (fechamento/ponte/horário especial);
+//                      os feriados NACIONAIS são computados (ver feriados.js).
+
+export async function ensureAgendaSchema(pool) {
+  try {
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS clinicas_horarios (
+        id           varchar PRIMARY KEY,
+        clinica_id   varchar NOT NULL,
+        dia_semana   integer NOT NULL,          -- 0=domingo … 6=sábado
+        hora_inicio  time without time zone NOT NULL,
+        hora_fim     time without time zone NOT NULL,
+        ativo        smallint DEFAULT 1
+      )`);
+    await pool.query(`CREATE INDEX IF NOT EXISTS idx_clinicas_horarios_clinica ON clinicas_horarios (clinica_id)`);
+
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS feriados (
+        id           varchar PRIMARY KEY,
+        clinica_id   varchar NOT NULL,
+        data         date NOT NULL,
+        nome         varchar NOT NULL,
+        fecha        smallint DEFAULT 1,        -- 1=fechado o dia; 0=abre em horário especial
+        hora_inicio  time without time zone,    -- horário especial (quando fecha=0)
+        hora_fim     time without time zone,
+        recorrente   smallint DEFAULT 0,        -- 1=repete todo ano (mesmo dia/mês)
+        created_at   timestamptz DEFAULT now()
+      )`);
+    await pool.query(`CREATE INDEX IF NOT EXISTS idx_feriados_clinica_data ON feriados (clinica_id, data)`);
+
+    // ── dentistas_folgas — folga/férias/indisponibilidade por DATA do dentista.
+    // O dentista (ou o dono) marca dias em que NÃO atende; o /slots pula.
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS dentistas_folgas (
+        id           varchar PRIMARY KEY,
+        dentista_id  varchar NOT NULL,
+        clinica_id   varchar,
+        data_inicio  date NOT NULL,
+        data_fim     date NOT NULL,      -- inclusive; = data_inicio p/ 1 dia
+        motivo       varchar,
+        created_at   timestamptz DEFAULT now()
+      )`);
+    await pool.query(`CREATE INDEX IF NOT EXISTS idx_dentistas_folgas_dent ON dentistas_folgas (dentista_id, data_inicio, data_fim)`);
+
+    // ── B (salas): agendamentos.sala_id — permite agendar num quarto alugado.
+    // Aditivo/nullable: NÃO afeta o fluxo existente (clínica) quando nulo.
+    await pool.query(`ALTER TABLE agendamentos ADD COLUMN IF NOT EXISTS sala_id varchar`);
+
+    // ── Janela ESTENDIDA do dentista (zona cinza): a IA agenda livre em
+    // [hora_inicio, hora_fim]; entre a estendida e a livre exige confirmação
+    // humana. Nulo = sem zona cinza (só a janela livre).
+    await pool.query(`ALTER TABLE dentistas_horarios ADD COLUMN IF NOT EXISTS hora_inicio_flex time without time zone`);
+    await pool.query(`ALTER TABLE dentistas_horarios ADD COLUMN IF NOT EXISTS hora_fim_flex    time without time zone`);
+
+    // ── agenda_pedidos — pedidos da ZONA CINZA aguardando a secretária humana.
+    // A IA cria (status 'pendente') e diz "vou confirmar"; a humana confirma
+    // (vira agendamento) ou recusa.
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS agenda_pedidos (
+        id             varchar PRIMARY KEY,
+        clinica_id     varchar NOT NULL,
+        dentista_id    varchar,
+        sala_id        varchar,
+        data           date NOT NULL,
+        hora_inicio    time without time zone NOT NULL,
+        hora_fim       time without time zone,
+        paciente_nome  varchar,
+        paciente_telefone varchar,
+        procedimento   varchar,
+        origem         varchar DEFAULT 'secretaria_ia',
+        status         varchar DEFAULT 'pendente',   -- pendente | confirmado | recusado
+        agendamento_id varchar,                        -- preenchido ao confirmar
+        created_at     timestamptz DEFAULT now(),
+        resolved_at    timestamptz,
+        resolved_by    varchar
+      )`);
+    await pool.query(`CREATE INDEX IF NOT EXISTS idx_agenda_pedidos_clinica_status ON agenda_pedidos (clinica_id, status, created_at)`);
+    // Pedido também serve para DÚVIDAS (sem horário): tipo + resumo; data/hora nullable.
+    await pool.query(`ALTER TABLE agenda_pedidos ADD COLUMN IF NOT EXISTS tipo   varchar DEFAULT 'horario'`);  // horario | duvida
+    await pool.query(`ALTER TABLE agenda_pedidos ADD COLUMN IF NOT EXISTS resumo text`);
+    await pool.query(`ALTER TABLE agenda_pedidos ALTER COLUMN data DROP NOT NULL`).catch(() => {});
+    await pool.query(`ALTER TABLE agenda_pedidos ALTER COLUMN hora_inicio DROP NOT NULL`).catch(() => {});
+
+    // ── agenda_situacoes — "área de situações": regras da clínica que a Secretária
+    // IA deve seguir (ex.: "plano X não cobre canal posterior — ofereça avaliação").
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS agenda_situacoes (
+        id          varchar PRIMARY KEY,
+        clinica_id  varchar NOT NULL,
+        texto       text NOT NULL,
+        ativo       smallint DEFAULT 1,
+        ordem       integer DEFAULT 0,
+        created_at  timestamptz DEFAULT now()
+      )`);
+    await pool.query(`CREATE INDEX IF NOT EXISTS idx_agenda_situacoes_clinica ON agenda_situacoes (clinica_id)`);
+
+    // ── agenda_checklist — respostas Sim/Não do DONO sobre a clínica (ver
+    // checklist-defs.js). Conferidas contra o banco → geram pendências de config
+    // e deixam a Secretária cautelosa. resposta: 1=sim, 0=não, NULL=não respondido.
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS agenda_checklist (
+        clinica_id  varchar NOT NULL,
+        chave       varchar NOT NULL,
+        resposta    smallint,
+        updated_at  timestamptz DEFAULT now(),
+        PRIMARY KEY (clinica_id, chave)
+      )`);
+    return true;
+  } catch (e) {
+    // Não derruba o boot do satélite se o banco estiver indisponível no momento.
+    console.error('[newwhats] ensureAgendaSchema falhou:', e.message);
+    return false;
+  }
+}

backend/newwhats/auth.js

@@ -0,0 +1,25 @@
+// Middleware de auth das rotas /nw/* — valida a integration_key enviada pelo
+// motor NewWhats. Aceita header x-nw-key ou Authorization: Bearer <key>.
+import { timingSafeEqual } from 'crypto'
+import { getConfig } from './config.js'
+
+export function nwAuth(req, res, next) {
+  const key = req.headers['x-nw-key']
+    || (req.headers['authorization'] || '').replace(/^Bearer\s+/i, '').trim()
+
+  if (!key) {
+    return res.status(401).json({ error: 'Chave de integração ausente. Use o header x-nw-key.' })
+  }
+
+  const stored = getConfig().integrationKey
+  if (!stored) {
+    return res.status(503).json({ error: 'Integração NewWhats não configurada (NEWWHATS_INTEGRATION_KEY).' })
+  }
+
+  const a = Buffer.from(stored)
+  const b = Buffer.from(key)
+  if (a.length !== b.length || !timingSafeEqual(a, b)) {
+    return res.status(403).json({ error: 'Chave de integração inválida.' })
+  }
+  next()
+}

backend/newwhats/checklist-defs.js

@@ -0,0 +1,99 @@
+// Checklist do DONO do workspace: perguntas Sim/Não sobre a clínica que a
+// Secretária IA usa para saber quando PODE agendar sozinha e quando deve ter
+// cautela. As respostas são conferidas contra o banco (dentistas/pacientes):
+// quando a declaração do dono não bate com os dados, geramos uma PENDÊNCIA
+// para ele configurar/cadastrar — e a IA fica cautelosa (encaminha ao humano).
+//
+// Fonte única: config (UI), consistência (pendências) e injeção no cérebro
+// (cautelas) consomem esta mesma definição para nunca divergirem.
+
+export const CHECKLIST_QUESTOES = [
+  {
+    chave: 'multi_dentista',
+    pergunta: 'A clínica tem mais de um dentista?',
+    ajuda: 'Se sim, a Secretária não pode assumir um único dentista nem "clínico geral" por padrão — precisa saber quem atende cada paciente.',
+  },
+  {
+    chave: 'pacientes_cadastrados',
+    pergunta: 'Os pacientes já estão cadastrados no sistema (/pacientes)?',
+    ajuda: 'Mesmo que sim, o cadastro pode estar INCOMPLETO (nem todos os familiares). A Secretária confirma a identidade antes de agendar e encaminha ao humano quando não reconhece quem fala.',
+  },
+  {
+    chave: 'telefone_compartilhado',
+    pergunta: 'Um mesmo telefone pode ser de vários pacientes (família)?',
+    ajuda: 'Ex.: o número está no cadastro do filho, mas quem manda mensagem é a mãe. Se sim, a Secretária SEMPRE confirma com quem está falando e para quem é o atendimento — nunca assume pelo número.',
+  },
+  {
+    chave: 'dentista_fixo',
+    pergunta: 'Cada paciente tem um dentista de referência (fixo)?',
+    ajuda: 'Se sim, um paciente de retorno deve voltar para o MESMO dentista — a IA não deve agendá-lo no clínico geral.',
+  },
+];
+
+const sim = (r, k) => r[k] === 1;
+const nao = (r, k) => r[k] === 0;
+
+// Pendências de CONFIG do dono: a declaração não bate com o banco.
+// counts = { dentistas, pacientes }.
+export function pendenciasDeConfig(respostas, counts) {
+  const r = respostas || {};
+  const dentistas = Number(counts?.dentistas || 0);
+  const pacientes = Number(counts?.pacientes || 0);
+  const P = [];
+
+  if (sim(r, 'multi_dentista') && dentistas <= 1)
+    P.push({ chave: 'multi_dentista', severidade: 'alta', titulo: 'Cadastre os demais dentistas',
+      detalhe: `Você indicou que a clínica tem mais de um dentista, mas há apenas ${dentistas} cadastrado. A Secretária não consegue direcionar cada paciente ao dentista certo — cadastre os outros dentistas.` });
+  if (nao(r, 'multi_dentista') && dentistas > 1)
+    P.push({ chave: 'multi_dentista', severidade: 'media', titulo: 'Confirme quantos dentistas atendem',
+      detalhe: `Você indicou um único dentista, mas há ${dentistas} cadastrados no sistema. Ajuste a resposta ou os cadastros.` });
+
+  if (sim(r, 'pacientes_cadastrados') && pacientes === 0)
+    P.push({ chave: 'pacientes_cadastrados', severidade: 'alta', titulo: 'Cadastre os pacientes',
+      detalhe: 'Você indicou que os pacientes estão cadastrados, mas não há nenhum paciente no sistema. A Secretária não reconhece quem já é paciente.' });
+  if (r['pacientes_cadastrados'] == null || nao(r, 'pacientes_cadastrados'))
+    P.push({ chave: 'pacientes_cadastrados', severidade: 'media', titulo: 'Complete o cadastro de pacientes',
+      detalhe: 'Enquanto os pacientes não estiverem cadastrados, a Secretária vai encaminhar todo retorno para a secretária humana confirmar (não agenda sozinha).' });
+
+  if (sim(r, 'dentista_fixo') && dentistas <= 1 && sim(r, 'multi_dentista'))
+    P.push({ chave: 'dentista_fixo', severidade: 'media', titulo: 'Cadastre os dentistas de referência',
+      detalhe: 'Você indicou que cada paciente tem um dentista fixo, mas o sistema ainda não tem os dentistas todos cadastrados para fazer esse vínculo.' });
+
+  if (sim(r, 'telefone_compartilhado'))
+    P.push({ chave: 'telefone_compartilhado', severidade: 'media', titulo: 'Complete o cadastro de cada familiar',
+      detalhe: 'Como um mesmo telefone pode ser de vários pacientes (ex.: cadastrado só no filho, mas quem fala é a mãe), a Secretária vai SEMPRE confirmar quem está falando e não assume pelo número. Mantenha cada familiar cadastrado e vinculado ao número para ela acertar mais e encaminhar menos ao humano.' });
+
+  return P;
+}
+
+// Cautelas para injetar no cérebro da IA (texto direto no system prompt).
+export function cautelasParaIA(respostas, counts) {
+  const r = respostas || {};
+  const dentistas = Number(counts?.dentistas || 0);
+  const pacientes = Number(counts?.pacientes || 0);
+  const C = [];
+
+  const multi = sim(r, 'multi_dentista') || dentistas > 1;
+  const temPacientes = pacientes > 0 || sim(r, 'pacientes_cadastrados');
+  const telShared = sim(r, 'telefone_compartilhado') || (temPacientes && r['telefone_compartilhado'] == null);
+
+  if (multi)
+    C.push('A clínica tem MAIS DE UM dentista: NUNCA assuma um dentista nem "clínico geral" por padrão para quem já é paciente. Descubra/pergunte qual dentista atende. Sem certeza → encaminhe ao humano.');
+  if (sim(r, 'multi_dentista') && dentistas <= 1)
+    C.push('ATENÇÃO: o sistema ainda não tem todos os dentistas cadastrados. Para pacientes de retorno ou que pedem um dentista específico, encaminhe ao humano — NÃO agende no clínico geral.');
+  if (sim(r, 'dentista_fixo'))
+    C.push('Cada paciente tem um dentista fixo: um retorno deve voltar ao MESMO dentista. Se você não sabe qual é (falta cadastro), encaminhe ao humano.');
+
+  // Identidade de quem fala — o cadastro é incompleto e o telefone é ambíguo.
+  if (temPacientes)
+    C.push('IDENTIDADE: o cadastro pode estar INCOMPLETO. Ao achar um paciente pelo telefone, NÃO assuma que é quem está falando — confirme o NOME de quem fala e PARA QUEM é o atendimento antes de qualquer coisa.');
+  if (telShared)
+    C.push('TELEFONE COMPARTILHADO: um mesmo número pode ser de vários da família (ex.: está no cadastro do filho, mas quem fala é a mãe; ou perguntam pelo tratamento do marido). SEMPRE pergunte com quem você fala e de quem é o atendimento; se a pessoa/atendimento não bater com o cadastro do número, encaminhe ao humano — não agende no paciente errado.');
+  if (pacientes === 0 || nao(r, 'pacientes_cadastrados'))
+    C.push('O cadastro de pacientes está incompleto: você NÃO consegue confirmar histórico nem o dentista de quem diz já ser paciente. Nesses casos, encaminhe ao humano em vez de agendar.');
+
+  // Profissional citado que não existe na lista de dentistas (sempre possível).
+  C.push('PROFISSIONAL NÃO CADASTRADO: se o cliente citar um dentista/profissional que NÃO está na lista de dentistas acima (ex.: prótese com um Dr. de fora), NÃO invente nem agende — encaminhe ao humano com encaminhar_humano e diga NO RESUMO que o profissional citado não está cadastrado, para o dono cadastrá-lo.');
+
+  return C;
+}

backend/newwhats/config.js

@@ -0,0 +1,64 @@
+// Config da integração com o motor NewWhats.
+// Fonte: tabela `settings` (id='newwhats_config') — editável pelo super-admin na UI.
+// Fallback: variáveis de ambiente (NEWWHATS_*), úteis para bootstrap/deploy.
+//
+//   NEWWHATS_URL / motorUrl              URL do motor
+//   NEWWHATS_INTEGRATION_KEY / integrationKey  x-nw-key
+//   NEWWHATS_WEBHOOK_SECRET / webhookSecret    HMAC do webhook
+//   NEWWHATS_CLINICA_ID / clinicaId      clínica que este satélite atende
+
+let cache = null; // { motorUrl, integrationKey, webhookSecret, clinicaId } | null
+
+function fromEnv() {
+  return {
+    motorUrl:       (process.env.NEWWHATS_URL || '').replace(/\/$/, ''),
+    integrationKey:  process.env.NEWWHATS_INTEGRATION_KEY || '',
+    webhookSecret:   process.env.NEWWHATS_WEBHOOK_SECRET || '',
+    clinicaId:       process.env.NEWWHATS_CLINICA_ID || '',
+  };
+}
+
+// DB (se houver valor) tem prioridade; ENV preenche o que faltar.
+export function getConfig() {
+  const env = fromEnv();
+  if (!cache) return env;
+  return {
+    motorUrl:       (cache.motorUrl || env.motorUrl || '').replace(/\/$/, ''),
+    integrationKey:  cache.integrationKey || env.integrationKey || '',
+    webhookSecret:   cache.webhookSecret || env.webhookSecret || '',
+    clinicaId:       cache.clinicaId || env.clinicaId || '',
+  };
+}
+
+export function isConfigured() {
+  const c = getConfig();
+  return Boolean(c.motorUrl && c.integrationKey);
+}
+
+// Carrega a config do banco para o cache (chamado no boot e após salvar).
+export async function loadConfigFromDb(pool) {
+  try {
+    const { rows } = await pool.query("SELECT data FROM settings WHERE id = 'newwhats_config'");
+    cache = rows[0]?.data || {};
+  } catch {
+    if (!cache) cache = {};
+  }
+  return getConfig();
+}
+
+// Persiste no banco e atualiza o cache.
+export async function saveConfigToDb(pool, cfg) {
+  const data = {
+    motorUrl:       (cfg.motorUrl || '').replace(/\/$/, ''),
+    integrationKey:  cfg.integrationKey || '',
+    webhookSecret:   cfg.webhookSecret || '',
+    clinicaId:       cfg.clinicaId || '',
+  };
+  await pool.query(
+    `INSERT INTO settings (id, category, data) VALUES ('newwhats_config', 'integration', $1)
+     ON CONFLICT (id) DO UPDATE SET data = EXCLUDED.data`,
+    [JSON.stringify(data)]
+  );
+  cache = data;
+  return getConfig();
+}

backend/newwhats/feriados.js

@@ -0,0 +1,92 @@
+// Feriados nacionais brasileiros (fixos + móveis) + resolução com exceções da
+// clínica (tabela `feriados`). Usado pela agenda-bridge para a Secretária saber
+// quando é feriado e o /slots pular esses dias.
+//
+// Fixos: datas nacionais. Móveis: derivados da Páscoa (Computus de Meeus).
+// Consciência Negra (20/11) é nacional desde 2024 (Lei 14.759/2023).
+
+const pad = (n) => String(n).padStart(2, '0');
+const ymd = (y, m, d) => `${y}-${pad(m)}-${pad(d)}`;
+
+// Domingo de Páscoa (algoritmo de Meeus/Jones/Butcher) — retorna {mes, dia}.
+function pascoa(ano) {
+  const a = ano % 19;
+  const b = Math.floor(ano / 100);
+  const c = ano % 100;
+  const d = Math.floor(b / 4);
+  const e = b % 4;
+  const f = Math.floor((b + 8) / 25);
+  const g = Math.floor((b - f + 1) / 3);
+  const h = (19 * a + b - d - g + 15) % 30;
+  const i = Math.floor(c / 4);
+  const k = c % 4;
+  const l = (32 + 2 * e + 2 * i - h - k) % 7;
+  const m = Math.floor((a + 11 * h + 22 * l) / 451);
+  const mes = Math.floor((h + l - 7 * m + 114) / 31);
+  const dia = ((h + l - 7 * m + 114) % 31) + 1;
+  return { mes, dia };
+}
+
+// Soma dias a uma data (UTC, evita fuso) → 'YYYY-MM-DD'.
+function addDias(y, m, d, delta) {
+  const base = new Date(Date.UTC(y, m - 1, d));
+  base.setUTCDate(base.getUTCDate() + delta);
+  return ymd(base.getUTCFullYear(), base.getUTCMonth() + 1, base.getUTCDate());
+}
+
+// Mapa { 'YYYY-MM-DD': 'Nome do feriado' } dos feriados NACIONAIS do ano.
+export function feriadosNacionais(ano) {
+  const p = pascoa(ano);
+  const py = ano, pm = p.mes, pd = p.dia;
+  const map = {
+    [ymd(ano, 1, 1)]:   'Confraternização Universal',
+    [ymd(ano, 4, 21)]:  'Tiradentes',
+    [ymd(ano, 5, 1)]:   'Dia do Trabalho',
+    [ymd(ano, 9, 7)]:   'Independência do Brasil',
+    [ymd(ano, 10, 12)]: 'Nossa Senhora Aparecida',
+    [ymd(ano, 11, 2)]:  'Finados',
+    [ymd(ano, 11, 15)]: 'Proclamação da República',
+    [ymd(ano, 11, 20)]: 'Consciência Negra',
+    [ymd(ano, 12, 25)]: 'Natal',
+    // Móveis (relativos ao Domingo de Páscoa)
+    [addDias(py, pm, pd, -48)]: 'Carnaval (segunda-feira)',
+    [addDias(py, pm, pd, -47)]: 'Carnaval (terça-feira)',
+    [addDias(py, pm, pd, -2)]:  'Sexta-feira Santa',
+    [addDias(py, pm, pd, 60)]:  'Corpus Christi',
+  };
+  return map;
+}
+
+// Nome do feriado nacional numa data 'YYYY-MM-DD', ou null.
+export function feriadoNacionalNome(dateStr) {
+  const ano = Number(String(dateStr).slice(0, 4));
+  if (!ano) return null;
+  return feriadosNacionais(ano)[dateStr] ?? null;
+}
+
+// Resolve o feriado de uma data para uma clínica: nacional OU exceção da clínica
+// (tabela `feriados`, que também pode ANULAR um dia — ver `fecha`). Retorna
+// { fecha: bool, nome, hora_inicio?, hora_fim? } ou null (dia normal).
+//
+// Regras:
+//  - Exceção da clínica tem prioridade (permite abrir num feriado nacional, ou
+//    fechar num dia comum, ou definir horário especial).
+//  - Sem exceção: cai no feriado nacional (fecha o dia inteiro).
+export async function resolverFeriado(pool, clinicaId, dateStr) {
+  try {
+    const mmdd = String(dateStr).slice(5); // 'MM-DD'
+    const { rows } = await pool.query(
+      `SELECT nome, fecha, hora_inicio, hora_fim FROM feriados
+        WHERE clinica_id = $1
+          AND (data = $2 OR (recorrente = 1 AND to_char(data,'MM-DD') = $3))
+        ORDER BY (data = $2) DESC LIMIT 1`,
+      [clinicaId, dateStr, mmdd]);
+    if (rows.length) {
+      const r = rows[0];
+      return { fecha: r.fecha !== false, nome: r.nome || 'Fechamento', hora_inicio: r.hora_inicio || null, hora_fim: r.hora_fim || null, origem: 'clinica' };
+    }
+  } catch { /* tabela pode não existir ainda */ }
+  const nac = feriadoNacionalNome(dateStr);
+  if (nac) return { fecha: true, nome: nac, hora_inicio: null, hora_fim: null, origem: 'nacional' };
+  return null;
+}

backend/newwhats/index.js

@@ -0,0 +1,182 @@
+// Integração NewWhats (satélite) para o scoreodonto — ESM, adaptada do mercado.
+// Registra rotas no app Express existente.
+//
+// Uso no server.js:
+//   import { registerNewwhats } from './newwhats/index.js'
+//   registerNewwhats(app, pool, { superadminGuard })
+import { createRoutes } from './routes.js'
+import { createWebhookReceiver } from './webhook-receiver.js'
+import { createRestProxy, createAccountsRoute, provisionNewwhatsAccount } from './proxy.js'
+import { getConfig, isConfigured, loadConfigFromDb, saveConfigToDb } from './config.js'
+import { Readable } from 'node:stream'
+
+export { syncKnowledge, buildKnowledgeText } from './sync-knowledge.js'
+export { createWsTunnel } from './proxy.js'
+
+// Provisiona (eager) a conta do email no motor NewWhats, best-effort e idempotente.
+// Chamado no cadastro de usuário/clínica do scoreodonto: "assim que a conta nasce
+// aqui, já nasce lá — pronta esperando quando a pessoa for mexer com WhatsApp".
+export async function provisionNewwhatsAccountEager(pool, email) {
+  try {
+    const cfg = getConfig()
+    if (!cfg.motorUrl || !cfg.integrationKey || !email) return false
+    return await provisionNewwhatsAccount(pool, cfg, email)
+  } catch { return false }
+}
+import { createAgendaBridge } from './agenda-bridge.js'
+import { createAgendaConfig } from './agenda-config.js'
+import { ensureAgendaSchema } from './agenda-schema.js'
+
+// Valida uma chave contra o motor. Envia um email-sonda (a chave mestra exige
+// x-nw-email). 200 = ok com dados; 404 = chave válida mas email-sonda inexistente
+// (= chave OK); 401 = chave inválida.
+async function testMotorKey(motorUrl, key) {
+  try {
+    const r = await fetch(`${motorUrl}/api/ext/v1/sessions`, {
+      headers: { 'x-nw-key': key, 'x-nw-email': 'probe@nw.local' },
+    });
+    if (r.ok || r.status === 404) return { ok: true, detail: 'Conexão OK' };
+    return { ok: false, detail: `Motor respondeu ${r.status}` };
+  } catch (e) {
+    return { ok: false, detail: `Motor inacessível: ${e.message}` };
+  }
+}
+
+export function registerNewwhats(app, pool, opts = {}) {
+  // passthrough middleware caso o guard não seja fornecido (dev)
+  const superadminGuard = opts.superadminGuard || ((_req, _res, next) => next());
+
+  // ── Ponte de agenda (motor → agenda real do scoreodonto) ───────────────────
+  // Auth própria por segredo compartilhado (x-nw-agenda-secret). Server-to-server.
+  app.use('/api/nw/agenda', createAgendaBridge(pool));
+
+  // ── Schema de horários/feriados (idempotente) + config (dono/dentista) ─────
+  // clinicas_horarios + feriados; usados pela agenda-bridge (Secretária) e pelas
+  // telas de configuração do scoreodonto.
+  ensureAgendaSchema(pool).catch((e) => console.error('[newwhats] schema agenda:', e?.message));
+  app.use('/api/nw/agenda-config', createAgendaConfig(pool));
+
+  // ── Proxy de MÍDIA: /api/nw/media/* → motor ────────────────────────────────
+  // A mídia/avatar vivem no motor (Wasabi ou local). O Wasabi é servido por
+  // /api/storage/view/* (plugin UnifiedStorageProvider, que cobre Wasabi + fallback
+  // local); a mídia local ANTIGA fica no /media estático. Tentamos o storage do
+  // plugin primeiro e caímos no /media se der 404. Same-origin no <img>/<video>.
+  app.use('/api/nw/media', async (req, res) => {
+    if (req.method !== 'GET') { res.status(405).end(); return; }
+    const cfg = getConfig();
+    if (!cfg.motorUrl) { res.status(503).end(); return; }
+    const rest = req.path.replace(/^\//, '');
+    const base = cfg.motorUrl.replace(/\/$/, '');
+    const headers = {};
+    if (req.headers.range) headers.range = req.headers.range;
+    const candidates = [`${base}/api/storage/view/${rest}`, `${base}/media/${rest}`];
+    try {
+      let r = null;
+      for (const url of candidates) {
+        r = await fetch(url, { headers });
+        if (r.status !== 404) break; // achou (ou erro que não é 404) → usa esse
+      }
+      res.status(r.status);
+      for (const h of ['content-type', 'content-length', 'content-range', 'accept-ranges', 'cache-control', 'content-disposition']) {
+        const v = r.headers.get(h);
+        if (v) res.setHeader(h, v);
+      }
+      // Mídia é imutável (path único por arquivo) → cache longo no browser.
+      if (!res.getHeader('cache-control')) res.setHeader('cache-control', 'public, max-age=604800, immutable');
+      if (r.body) Readable.fromWeb(r.body).pipe(res);
+      else res.end();
+    } catch (e) {
+      res.status(502).json({ error: `Mídia indisponível: ${e.message}` });
+    }
+  });
+
+  // Carrega a config do banco para o cache (não bloqueia o boot).
+  loadConfigFromDb(pool).then((c) =>
+    console.log(`[newwhats] config carregada — ${isConfigured() ? 'configurada' : 'AGUARDANDO config'} (clinica=${c.clinicaId || '—'})`)
+  ).catch(() => {});
+
+  // ── Config (super-admin) ───────────────────────────────────────────────────
+  // GET: nunca devolve os segredos em claro — só se estão definidos.
+  app.get('/api/nw/config', superadminGuard, (_req, res) => {
+    const c = getConfig();
+    res.json({
+      motorUrl: c.motorUrl,
+      clinicaId: c.clinicaId,
+      hasIntegrationKey: Boolean(c.integrationKey),
+      hasWebhookSecret: Boolean(c.webhookSecret),
+      configured: isConfigured(),
+    });
+  });
+
+  // PUT: secrets em branco MANTÊM o valor atual (não precisa redigitar).
+  app.put('/api/nw/config', superadminGuard, async (req, res) => {
+    try {
+      const cur = getConfig();
+      const b = req.body || {};
+      const next = {
+        motorUrl:       (b.motorUrl ?? cur.motorUrl) || '',
+        clinicaId:      (b.clinicaId ?? cur.clinicaId) || '',
+        integrationKey: b.integrationKey ? String(b.integrationKey) : cur.integrationKey,
+        webhookSecret:  b.webhookSecret ? String(b.webhookSecret) : cur.webhookSecret,
+      };
+      await saveConfigToDb(pool, next);
+      res.json({ ok: true, configured: isConfigured() });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
+  // Aplica um TOKEN de pareamento — auto-configura URL + chave + segredo do webhook.
+  // Token = "nwpair_" + base64url(JSON({ u: motorUrl, k: integrationKey, s: webhookSecret })).
+  // A clínica continua sendo escolhida localmente (o motor não conhece os IDs daqui).
+  app.post('/api/nw/config/token', superadminGuard, async (req, res) => {
+    try {
+      let raw = String((req.body || {}).token || '').trim();
+      raw = raw.replace(/^nwpair[_:]\s*/i, '');
+      let p;
+      try { p = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8')); }
+      catch { return res.status(400).json({ error: 'Token inválido (não foi possível decodificar).' }); }
+
+      const motorUrl = (p.u || p.url || '').replace(/\/$/, '');
+      const integrationKey = p.k || p.key || p.integrationKey || '';
+      const webhookSecret = p.s || p.secret || p.webhookSecret || '';
+      if (!motorUrl || !integrationKey) {
+        return res.status(400).json({ error: 'Token incompleto (faltam URL ou chave).' });
+      }
+
+      // Valida a chave contra o motor ANTES de salvar.
+      const { ok: motorOk, detail } = await testMotorKey(motorUrl, integrationKey);
+      if (!motorOk) return res.status(400).json({ error: `Token não validou no motor: ${detail}` });
+
+      const cur = getConfig();
+      await saveConfigToDb(pool, { motorUrl, integrationKey, webhookSecret: webhookSecret || cur.webhookSecret, clinicaId: cur.clinicaId });
+      res.json({ ok: true, configured: isConfigured(), motorUrl, hasWebhookSecret: Boolean(webhookSecret || cur.webhookSecret), detail });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
+  // Lista de clínicas para o dropdown.
+  app.get('/api/nw/clinicas', superadminGuard, async (_req, res) => {
+    try {
+      const { rows } = await pool.query('SELECT id, nome_fantasia FROM clinicas ORDER BY nome_fantasia');
+      res.json(rows);
+    } catch (e) { res.status(500).json({ error: e.message }); }
+  });
+
+  // Testa a conexão com o motor (usa a config atual).
+  app.get('/api/nw/status', superadminGuard, async (_req, res) => {
+    const c = getConfig();
+    if (!c.motorUrl || !c.integrationKey) return res.json({ configured: false, motorOk: false, detail: 'URL ou chave ausente' });
+    const { ok, detail } = await testMotorKey(c.motorUrl, c.integrationKey);
+    res.json({ configured: true, motorOk: ok, detail });
+  });
+
+  // ── Operação ────────────────────────────────────────────────────────────────
+  app.use('/nw', createRoutes(pool));                 // Secretária do motor consulta a clínica
+  app.use(createWebhookReceiver(pool));               // webhook motor → satélite
+  app.get('/api/nw/accounts', createAccountsRoute(pool)); // seletor multi-conta da inbox (próprias + liberadas) — ANTES do catch-all
+  app.use('/api/nw/v1', createRestProxy(pool));       // proxy do inbox → motor (express 5: use, não wildcard) + enforcement de ownership
+
+  console.log('[newwhats] integração registrada (/nw, /api/webhook/newwhats, /api/nw/v1/*, /api/nw/config)');
+}

backend/newwhats/manifest.json

@@ -0,0 +1,21 @@
+{
+  "id": "newwhats",
+  "name": "NewWhats — Integração WhatsApp (Odonto)",
+  "version": "1.0.0",
+  "project": "scoreodonto.com",
+  "description": "Satélite do motor NewWhats adaptado ao domínio odontológico: expõe /nw/* (clínica, especialidades, dentistas, procedimentos, planos) para a Secretária IA, recebe webhooks do motor e faz proxy do inbox. Config por variáveis de ambiente (ESM, sem tabela plugin_configs).",
+  "runtime": "esm-module",
+  "entry": "index.js#registerNewwhats",
+  "features": [
+    "Rotas /nw/* (dados da clínica para a Secretária IA)",
+    "sync-knowledge (base de conhecimento odonto → motor)",
+    "Webhook receiver (message.new, session.status) com HMAC",
+    "Proxy REST /api/nw/v1/* → motor /api/ext/v1/*"
+  ],
+  "config_env": [
+    { "key": "NEWWHATS_URL",             "required": true,  "help": "URL do motor NewWhats." },
+    { "key": "NEWWHATS_INTEGRATION_KEY", "required": true,  "help": "x-nw-key: valida /nw/* e é injetada no proxy. Igual à apiKey criada no motor." },
+    { "key": "NEWWHATS_WEBHOOK_SECRET",  "required": false, "help": "Segredo HMAC para validar x-nw-signature nos webhooks. Recomendado." },
+    { "key": "NEWWHATS_CLINICA_ID",      "required": true,  "help": "Qual clínica este satélite atende (multi-tenant)." }
+  ]
+}

backend/newwhats/proxy.js

@@ -0,0 +1,466 @@
+// Proxy REST: /api/nw/v1/* (frontend) → motor /api/ext/v1/*.
+//
+// Segurança: valida o JWT do scoreodonto (só usuário logado acessa).
+// Resolução de conta: SEMPRE via x-nw-email (chave mestra resolve o tenant pelo
+// email). Todo usuário da clínica tem conta própria no motor — se o motor não
+// conhecer o email, é erro (404 "conta não encontrada"), não há fallback.
+// O email vem SEMPRE do token verificado — nunca do cliente.
+import net from 'node:net';
+import tls from 'node:tls';
+import jwt from 'jsonwebtoken';
+import { getConfig } from './config.js';
+
+function authFromReq(req) {
+  try {
+    const tk = (req.headers['authorization'] || '').replace(/^Bearer\s+/i, '').trim();
+    if (!tk) return null;
+    const p = jwt.verify(tk, process.env.JWT_SECRET);
+    const email = (p.email || '').toLowerCase() || null;
+    if (!email) return null;
+    return { email, userId: p.userId || null };
+  } catch { return null; }
+}
+
+// Resolve o dono do workspace (clínica OU sala). Retorna o userId dono ou null.
+async function resolveOwnerId(pool, clinicaId) {
+  if (!pool || !clinicaId) return null;
+  try {
+    const { rows: cl } = await pool.query('SELECT owner_id FROM clinicas WHERE id = $1', [clinicaId]);
+    if (cl.length) {
+      if (cl[0].owner_id) return cl[0].owner_id;
+      // Clínicas antigas sem owner_id: dono = vínculo donoclinica/donoconsultorio.
+      const { rows: v } = await pool.query(
+        "SELECT usuario_id FROM vinculos WHERE clinica_id = $1 AND role IN ('donoclinica','donoconsultorio') ORDER BY id LIMIT 1",
+        [clinicaId]);
+      return v[0]?.usuario_id || null;
+    }
+    const { rows: sl } = await pool.query('SELECT owner_usuario_id FROM salas WHERE id = $1', [clinicaId]);
+    return sl[0]?.owner_usuario_id || null;
+  } catch { return null; }
+}
+
+// Resolve o dono do workspace COM e-mail. Retorna { ownerId, email } ou null.
+// Usado para a inbox compartilhada: a caixa da clínica vive na conta (tenant) do
+// dono no motor, então falamos com o motor usando o e-mail DELE.
+async function resolveOwner(pool, clinicaId) {
+  const ownerId = await resolveOwnerId(pool, clinicaId);
+  if (!ownerId) return null;
+  try {
+    const { rows } = await pool.query('SELECT lower(email) AS email FROM usuarios WHERE id = $1', [ownerId]);
+    return { ownerId, email: rows[0]?.email || null };
+  } catch { return { ownerId, email: null }; }
+}
+
+// Autoriza (ou nega 403) uma ação sensível de sessão de WhatsApp.
+// Mapeamento das ações do motor:
+//   POST   /sessions              → scan INICIAL (criar)  → só o dono
+//   GET    /sessions/:id/qr       → re-scan (parear QR)   → dono OU can_rescan
+//   POST   /sessions/:id/connect  → re-scan (reconectar)  → dono OU can_rescan
+//   DELETE /sessions/:id          → excluir               → dono OU can_delete
+// Retorna { ok: true } ou { ok: false, status, error }.
+async function guardSessionAction(pool, req, tail, userId) {
+  const method = req.method.toUpperCase();
+  const m = tail.match(/^\/sessions(?:\/([^/?]+)(\/qr|\/connect)?)?/);
+  if (!m) return { ok: true }; // não é uma rota de sessão
+
+  const instanceId = m[1] || null;
+  const sub = m[2] || null;
+
+  const isCreate  = method === 'POST'   && !instanceId;                    // POST /sessions
+  const isRescan  = (method === 'GET' && sub === '/qr') ||
+                    (method === 'POST' && sub === '/connect');             // parear/reconectar
+  const isDelete  = method === 'DELETE' && instanceId && !sub;             // DELETE /sessions/:id
+
+  if (!isCreate && !isRescan && !isDelete) return { ok: true }; // GET lista / etc → livre
+
+  const clinicaId = req.headers['x-nw-clinica'] ? String(req.headers['x-nw-clinica']) : null;
+  if (!clinicaId) return { ok: false, status: 403, error: 'Workspace não identificado para esta ação.' };
+
+  const ownerId = await resolveOwnerId(pool, clinicaId);
+  if (ownerId && ownerId === userId) return { ok: true }; // dono: poder total
+
+  // Scan inicial é exclusivo do dono — não delegável.
+  if (isCreate) return { ok: false, status: 403, error: 'Apenas o dono pode conectar um novo WhatsApp.' };
+
+  // Re-scan / exclusão: exigem delegação por sessão.
+  if (!instanceId) return { ok: false, status: 403, error: 'Sessão não identificada.' };
+  let authz = null;
+  try {
+    const { rows } = await pool.query(
+      'SELECT can_rescan, can_delete FROM wa_session_authz WHERE clinica_id = $1 AND instance_id = $2 AND usuario_id = $3',
+      [clinicaId, instanceId, userId]);
+    authz = rows[0] || null;
+  } catch { /* nega por padrão */ }
+
+  if (isRescan && authz?.can_rescan) return { ok: true };
+  if (isDelete && authz?.can_delete) return { ok: true };
+
+  return {
+    ok: false, status: 403,
+    error: isDelete
+      ? 'Somente o dono pode excluir esta sessão. Peça autorização de exclusão.'
+      : 'Somente o dono pode reconectar esta sessão. Peça autorização de re-scan.',
+  };
+}
+
+// Auto-provisiona (idempotente) a conta do email no motor, via chave mestra.
+// Usado como self-heal quando o motor responde "Conta não encontrada".
+export async function provisionNewwhatsAccount(pool, cfg, email) {
+  if (!cfg.motorUrl || !cfg.integrationKey || !email) return false;
+  let name = email;
+  try {
+    if (pool) {
+      const { rows } = await pool.query('SELECT nome FROM usuarios WHERE lower(email) = $1', [email.toLowerCase()]);
+      if (rows[0]?.nome) name = rows[0].nome;
+    }
+  } catch { /* usa email como nome */ }
+  try {
+    const r = await fetch(`${cfg.motorUrl}/api/ext/v1/satellites/accounts`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'x-nw-key': cfg.integrationKey },
+      body: JSON.stringify({ email, name }),
+    });
+    return r.ok;
+  } catch { return false; }
+}
+
+// Monta a assinatura do operador para prefixar mensagens: primeiro nome; se houver
+// outro membro do workspace com o MESMO primeiro nome, desambigua com "Nome I." (inicial
+// do primeiro sobrenome). Retorna null se não houver nome.
+export async function operatorSignature(pool, userId, clinicaId) {
+  if (!pool || !userId) return null;
+  try {
+    const { rows } = await pool.query('SELECT nome FROM usuarios WHERE id = $1', [userId]);
+    const full = String(rows[0]?.nome || '').trim();
+    if (!full) return null;
+    const parts = full.split(/\s+/);
+    const first = parts[0];
+    let ambiguous = false;
+    if (clinicaId) {
+      const { rows: m } = await pool.query(
+        `SELECT u.nome FROM vinculos v JOIN usuarios u ON u.id = v.usuario_id
+         WHERE v.clinica_id = $1 AND u.id <> $2`, [clinicaId, userId]);
+      ambiguous = m.some(x => String(x.nome || '').trim().split(/\s+/)[0].toLowerCase() === first.toLowerCase());
+    }
+    if (ambiguous && parts.length > 1 && parts[1][0]) {
+      return `${first} ${parts[1][0].toUpperCase()}.`;
+    }
+    return first;
+  } catch { return null; }
+}
+
+// Gate de acesso a ÁREAS (Inbox / Secretária). Dono passa sempre; os demais só com
+// delegação (can_inbox / can_secretaria) do dono em alguma sessão do workspace.
+async function guardAreaAccess(pool, tail, userId, clinicaId) {
+  const isSecretaria = /^\/(secretaria|sec)(\/|$|\?)/.test(tail);
+  const isInbox = /^\/(inbox|conversations)(\/|$|\?)/.test(tail);
+  if (!isSecretaria && !isInbox) return { ok: true };
+  if (!pool || !clinicaId) return { ok: true }; // sem workspace resolvido, não barra aqui
+  const ownerId = await resolveOwnerId(pool, clinicaId);
+  if (ownerId && ownerId === userId) return { ok: true };
+  const col = isSecretaria ? 'can_secretaria' : 'can_inbox';
+  try {
+    const { rows } = await pool.query(
+      `SELECT 1 FROM wa_session_authz WHERE clinica_id = $1 AND usuario_id = $2 AND ${col} = true LIMIT 1`,
+      [clinicaId, userId]);
+    if (rows.length) return { ok: true };
+  } catch { /* nega por padrão */ }
+  return { ok: false, status: 403, error: isSecretaria ? 'Sem acesso à Secretária. Peça autorização ao dono.' : 'Sem acesso ao Inbox. Peça autorização ao dono.' };
+}
+
+// Gate de ações DESTRUTIVAS no inbox (apagar conversa / apagar mensagem).
+// Só o dono ou quem tiver can_delete_msg. (Complementa o gate de acesso ao inbox.)
+async function guardInboxDestructive(pool, method, tail, userId, clinicaId) {
+  const isDeleteChat = method === 'DELETE' && /^\/inbox\/[^/]+\/?(\?|$)/.test(tail);
+  const isClearMsgs  = method === 'DELETE' && /^\/inbox\/[^/]+\/messages\/?(\?|$)/.test(tail);   // limpar conversa (todas as msgs)
+  const isDeleteMsg  = method === 'DELETE' && /^\/inbox\/[^/]+\/messages\/[^/]+/.test(tail);
+  if (!isDeleteChat && !isClearMsgs && !isDeleteMsg) return { ok: true };
+  if (!pool || !clinicaId) return { ok: true };
+  const ownerId = await resolveOwnerId(pool, clinicaId);
+  if (ownerId && ownerId === userId) return { ok: true };
+  try {
+    const { rows } = await pool.query(
+      'SELECT 1 FROM wa_session_authz WHERE clinica_id = $1 AND usuario_id = $2 AND can_delete_msg = true LIMIT 1',
+      [clinicaId, userId]);
+    if (rows.length) return { ok: true };
+  } catch { /* nega por padrão */ }
+  return { ok: false, status: 403, error: 'Sem permissão para apagar conversas/mensagens. Peça autorização ao dono.' };
+}
+
+export function createRestProxy(pool) {
+  return async function restProxy(req, res) {
+    const cfg = getConfig();
+    if (!cfg.motorUrl || !cfg.integrationKey) {
+      return res.status(503).json({ error: 'Integração NewWhats não configurada.' });
+    }
+    const auth = authFromReq(req);
+    if (!auth) return res.status(401).json({ error: 'Sessão inválida (faça login no scoreodonto).' });
+    const { email, userId } = auth;
+
+    const tail = req.originalUrl.replace(/^\/api\/nw\/v1/, '');
+    const clinicaId = req.headers['x-nw-clinica'] ? String(req.headers['x-nw-clinica']) : null;
+
+    // Enforcement de ownership/permissões antes de repassar ao motor.
+    const guard = await guardSessionAction(pool, req, tail, userId);
+    if (!guard.ok) return res.status(guard.status).json({ error: guard.error });
+
+    // Gate de acesso às áreas Inbox / Secretária.
+    const area = await guardAreaAccess(pool, tail, userId, clinicaId);
+    if (!area.ok) return res.status(area.status).json({ error: area.error });
+
+    // Gate de ações destrutivas do inbox (apagar conversa/mensagem).
+    const destructive = await guardInboxDestructive(pool, req.method, tail, userId, clinicaId);
+    if (!destructive.ok) return res.status(destructive.status).json({ error: destructive.error });
+
+    // Assinatura do operador: prefixa o texto enviado com "*Nome:*\n" (identifica quem
+    // respondeu numa caixa compartilhada). O ":" fica DENTRO do negrito para que TODOS
+    // os dispositivos (contato/outros operadores) e jids vejam "Nome:" em negrito
+    // consistente — não só a nossa UI. Só no envio de texto por humano.
+    if (req.method === 'POST' && /^\/inbox\/[^/]+\/send$/.test(tail) && req.body && typeof req.body.text === 'string' && req.body.text.trim()) {
+      const sig = await operatorSignature(pool, userId, clinicaId);
+      if (sig) req.body.text = `*${sig}:*\n${req.body.text}`;
+    }
+
+    // Conta-alvo no motor. Por padrão é a do próprio usuário (e-mail do JWT). Mas a
+    // inbox da clínica vive na conta (tenant) do DONO — então, nas rotas de inbox,
+    // se o usuário NÃO é dono do workspace e chegou até aqui (guardAreaAccess já
+    // exigiu can_inbox), falamos com o motor como o dono. Assim, logado como ele
+    // mesmo, o usuário vê a caixa do número da clínica no seletor — sem trocar de
+    // login. Só a inbox comuta a conta; demais rotas seguem com o e-mail próprio.
+    let targetEmail = email;
+    if (/^\/(inbox|conversations)(\/|$|\?)/.test(tail) && clinicaId) {
+      const owner = await resolveOwner(pool, clinicaId);
+      if (owner && owner.ownerId !== userId && owner.email) targetEmail = owner.email;
+    }
+
+    const url = `${cfg.motorUrl}/api/ext/v1${tail}`;
+
+    // Upload de arquivo grande: o corpo é multipart e NÃO passa pelo body-parser JSON
+    // (o stream chega intacto). Encaminhamos o stream cru ao motor, preservando o
+    // Content-Type (com boundary) — sem base64, sem limite de JSON.
+    const isMultipart = /multipart\/form-data/i.test(req.headers['content-type'] || '');
+
+    const opts = { method: req.method, headers: {
+      'x-nw-key': cfg.integrationKey,
+      'x-nw-email': targetEmail,
+      // clínica do workspace ativo (modelo de canal) — repassa ao motor se veio.
+      ...(req.headers['x-nw-clinica'] ? { 'x-nw-clinica': String(req.headers['x-nw-clinica']) } : {}),
+      ...(isMultipart
+        ? { 'content-type': req.headers['content-type'] }
+        : { 'Content-Type': 'application/json' }),
+    } };
+    if (isMultipart) {
+      opts.body = req;          // stream cru do upload → motor
+      opts.duplex = 'half';     // exigido pelo fetch (undici) ao enviar stream
+    } else if (!['GET', 'HEAD'].includes(req.method) && req.body && Object.keys(req.body).length) {
+      opts.body = JSON.stringify(req.body);
+    }
+
+    try {
+      let r = await fetch(url, opts);
+      let text = await r.text();
+      // Self-heal: a conta ainda não foi espelhada no motor. Provisiona (idempotente)
+      // e refaz o request UMA vez — assim "quando a pessoa for mexer, tudo funciona".
+      if (r.status === 404 && /conta n[ãa]o encontrada/i.test(text) && targetEmail) {
+        const ok = await provisionNewwhatsAccount(pool, cfg, targetEmail);
+        if (ok) { r = await fetch(url, opts); text = await r.text(); }
+      }
+      res.status(r.status);
+      try { res.json(JSON.parse(text)); } catch { res.send(text); }
+    } catch (e) {
+      res.status(502).json({ error: `Motor indisponível: ${e.message}` });
+    }
+  };
+}
+
+// ── GET /api/nw/accounts — contas de WhatsApp que o usuário logado pode operar ──
+//
+// Alimenta o seletor de número da inbox (multi-conta, SEM trocar de login) e o
+// ícone (i) de papéis. Junta: (1) as sessões da PRÓPRIA conta do usuário no motor
+// e (2) as sessões LIBERADAS pelo dono (can_inbox por sessão em wa_session_authz),
+// buscadas no motor com o e-mail do dono. Cada item traz o papel (sec_numbers).
+export function createAccountsRoute(pool) {
+  return async function accountsRoute(req, res) {
+    const cfg = getConfig();
+    if (!cfg.motorUrl || !cfg.integrationKey) {
+      return res.status(503).json({ error: 'Integração NewWhats não configurada.' });
+    }
+    const auth = authFromReq(req);
+    if (!auth) return res.status(401).json({ error: 'Sessão inválida (faça login no scoreodonto).' });
+    const { email, userId } = auth;
+
+    const motorGet = async (path, asEmail) => {
+      try {
+        const r = await fetch(`${cfg.motorUrl}/api/ext/v1${path}`, {
+          headers: { 'x-nw-key': cfg.integrationKey, 'x-nw-email': asEmail },
+        });
+        if (!r.ok) return [];
+        const j = await r.json();
+        return Array.isArray(j) ? j : [];
+      } catch { return []; }
+    };
+
+    try {
+      // Papéis (sec_numbers) são resolvidos no motor pela CONTA (x-nw-email). Um
+      // usuário sem conta no motor (ex.: recepcionista que só existe no scoreodonto)
+      // não tem números próprios — então o papel de cada número LIBERADO precisa ser
+      // buscado com o e-mail do DONO da sessão, não do usuário logado. Cache por e-mail.
+      const numbersCache = new Map();
+      const numbersFor = async (asEmail) => {
+        if (!numbersCache.has(asEmail)) {
+          const nums = await motorGet('/secretaria/numbers', asEmail);
+          numbersCache.set(asEmail, new Map(nums.map((n) => [n.instance_id, n])));
+        }
+        return numbersCache.get(asEmail);
+      };
+      const metaFrom = (roleMap, instanceId, fallbackName) => {
+        const n = roleMap.get(instanceId) || {};
+        return { role: n.role || null, label: n.label || fallbackName || null, area: n.area || null, notes: n.notes || null };
+      };
+
+      const out = [];
+      const seen = new Set();
+      const pushWith = (s, roleMap, extra) => {
+        if (!s || seen.has(s.id)) return;
+        seen.add(s.id);
+        out.push({
+          instanceId: s.id, phone: s.phone || null, name: s.name || null,
+          status: s.status || null, avatar: s.avatar || null,
+          ...metaFrom(roleMap, s.id, s.name), ...extra,
+        });
+      };
+
+      // 1) Sessões PRÓPRIAS (conta do próprio usuário no motor) — papel da própria conta.
+      const ownRoles = await numbersFor(email);
+      for (const s of await motorGet('/sessions', email)) {
+        pushWith(s, ownRoles, { clinicaId: null, ownerEmail: email, ownerNome: null, own: true, canInbox: true });
+      }
+
+      // 2) Sessões LIBERADAS por outros donos (can_inbox por sessão).
+      const { rows: grants } = await pool.query(
+        `SELECT DISTINCT clinica_id, instance_id FROM wa_session_authz
+         WHERE usuario_id = $1 AND can_inbox = true`, [userId]);
+      const byClinica = new Map();
+      for (const g of grants) {
+        if (!byClinica.has(g.clinica_id)) byClinica.set(g.clinica_id, new Set());
+        byClinica.get(g.clinica_id).add(g.instance_id);
+      }
+      for (const [clinicaId, allowed] of byClinica) {
+        const owner = await resolveOwner(pool, clinicaId);
+        if (!owner || !owner.email || owner.ownerId === userId) continue; // dono próprio já veio em (1)
+        let ownerNome = null;
+        try {
+          const { rows } = await pool.query('SELECT nome FROM usuarios WHERE id = $1', [owner.ownerId]);
+          ownerNome = rows[0]?.nome || null;
+        } catch { /* opcional */ }
+        const ownerRoles = await numbersFor(owner.email);  // papéis dos números vêm da conta do DONO
+        for (const s of await motorGet('/sessions', owner.email)) {
+          if (allowed.has(s.id)) pushWith(s, ownerRoles, { clinicaId, ownerEmail: owner.email, ownerNome, own: false, canInbox: true });
+        }
+      }
+
+      res.json(out);
+    } catch (e) {
+      res.status(502).json({ error: `Falha ao montar contas: ${e.message}` });
+    }
+  };
+}
+
+// ── Túnel WebSocket: /api/nw/v1/stream (browser) → motor /api/ext/v1/stream ──
+//
+// O inbox em tempo real do motor (QR, status da sessão, mensagens novas) roda
+// sobre WebSocket. Aqui abrimos um túnel TCP bruto socket↔socket e injetamos a
+// x-nw-key no handshake com o motor — a chave nunca chega ao browser.
+//
+// Auth do usuário: o browser NÃO envia header Authorization no upgrade WS, então
+// o JWT do scoreodonto vem por ?token= (mesmo esquema do /api/ws do app). Só
+// usuário logado abre o túnel; o token fica local — não é repassado ao motor.
+//
+// Motor: autentica o /api/ext/v1/stream pela x-nw-key + x-nw-email (a chave é a
+// mestra; o tenant é resolvido pelo email do usuário) e exige o path EXATO, sem
+// query — por isso reescrevemos um request-line limpo. O email vem do JWT.
+//
+// Conta-alvo do stream: por padrão a própria. Se o browser mandar ?clinica= (a
+// conta ativa do seletor) e o usuário não for o dono mas tiver can_inbox nela,
+// o stream passa a ser o do DONO — assim a caixa compartilhada recebe mensagens
+// novas em tempo real. Mesma regra do proxy REST (reescrita de x-nw-email).
+export function createWsTunnel(pool) {
+  return async function wsTunnel(req, clientSocket, head) {
+    const fail = (statusLine) => {
+      try { clientSocket.write(`HTTP/1.1 ${statusLine}\r\n\r\n`); } catch { /* socket já morto */ }
+      clientSocket.destroy();
+    };
+
+    // Auth: JWT do scoreodonto no query string (?token=); conta ativa em ?clinica=.
+    let token, clinica;
+    try {
+      const u = new URL(req.url, 'http://localhost');
+      token = u.searchParams.get('token');
+      clinica = u.searchParams.get('clinica');
+    } catch { return fail('400 Bad Request'); }
+    let email, userId;
+    try {
+      const p = jwt.verify(token, process.env.JWT_SECRET);
+      email = (p.email || '').toLowerCase();
+      userId = p.userId || null;
+    } catch { return fail('401 Unauthorized'); }
+    if (!email) return fail('401 Unauthorized');
+
+    // Reescrita da conta-alvo p/ a caixa compartilhada (só leitura via can_inbox).
+    let targetEmail = email;
+    if (clinica && pool && userId) {
+      try {
+        const owner = await resolveOwner(pool, clinica);
+        if (owner && owner.email && owner.ownerId !== userId) {
+          const { rows } = await pool.query(
+            'SELECT 1 FROM wa_session_authz WHERE clinica_id = $1 AND usuario_id = $2 AND can_inbox = true LIMIT 1',
+            [clinica, userId]);
+          if (rows.length) targetEmail = owner.email;
+        }
+      } catch { /* mantém a própria conta */ }
+    }
+
+    const cfg = getConfig();
+    if (!cfg.motorUrl || !cfg.integrationKey) return fail('503 Service Unavailable');
+
+    let target;
+    try { target = new URL(cfg.motorUrl); }
+    catch { return fail('502 Bad Gateway'); }
+    const isHttps = target.protocol === 'https:';
+    const host = target.hostname;
+    const port = Number(target.port) || (isHttps ? 443 : 80);
+
+    const onConnect = () => {
+      // Reescreve o handshake: path EXATO + Host do motor + x-nw-key.
+      // Preserva os headers do WS (sec-websocket-*, upgrade, connection).
+      const headers = Object.entries(req.headers)
+        .filter(([k]) => !['host', 'x-nw-key', 'x-nw-email'].includes(k.toLowerCase()))
+        .map(([k, v]) => `${k}: ${v}`)
+        .join('\r\n');
+
+      proxySocket.write(
+        `${req.method} /api/ext/v1/stream HTTP/1.1\r\n` +
+        `Host: ${host}\r\n` +
+        `x-nw-key: ${cfg.integrationKey}\r\n` +
+        `x-nw-email: ${targetEmail}\r\n` +
+        `${headers}\r\n\r\n`
+      );
+      if (head && head.length) proxySocket.write(head);
+
+      proxySocket.pipe(clientSocket);
+      clientSocket.pipe(proxySocket);
+    };
+
+    const proxySocket = isHttps
+      ? tls.connect({ host, port, servername: host }, onConnect)
+      : net.connect(port, host, onConnect);
+
+    proxySocket.on('error', (err) => {
+      console.error('[newwhats] túnel WS erro:', err.message);
+      clientSocket.destroy();
+    });
+    clientSocket.on('error', () => proxySocket.destroy());
+    clientSocket.on('close', () => proxySocket.destroy());
+    proxySocket.on('close', () => clientSocket.destroy());
+  };
+}

backend/newwhats/routes.js

@@ -0,0 +1,98 @@
+// Rotas /nw/* — a Secretária IA do motor consulta os dados desta clínica.
+// Adaptado do satélite mercado para o domínio ODONTO (scoreodonto).
+// Todas as rotas exigem a integration_key (nwAuth).
+import { Router } from 'express'
+import { nwAuth } from './auth.js'
+import { getConfig } from './config.js'
+
+const money = (v) =>
+  v == null ? null : `R$ ${Number(v).toFixed(2).replace('.', ',')}`
+
+// Resolve a clínica-alvo: query ?clinica_id= tem prioridade; senão a do config.
+function resolveClinicaId(req) {
+  return String(req.query.clinica_id || getConfig().clinicaId || '').trim()
+}
+
+export function createRoutes(pool) {
+  const router = Router()
+  router.use(nwAuth)
+
+  const needClinica = (req, res) => {
+    const id = resolveClinicaId(req)
+    if (!id) res.status(400).json({ error: 'clinica_id ausente (configure NEWWHATS_CLINICA_ID ou passe ?clinica_id=).' })
+    return id
+  }
+
+  router.get('/ping', (_req, res) =>
+    res.json({ ok: true, service: 'scoreodonto', ts: new Date().toISOString() }))
+
+  // Dados da clínica
+  router.get('/clinica', async (req, res) => {
+    const id = needClinica(req, res); if (!id) return
+    try {
+      const { rows } = await pool.query(
+        `SELECT nome_fantasia, telefone, cidade, estado, logradouro, numero, bairro, cep
+         FROM clinicas WHERE id = $1`, [id])
+      res.json(rows[0] || null)
+    } catch (e) { res.status(500).json({ error: e.message }) }
+  })
+
+  // Especialidades atendidas
+  router.get('/especialidades', async (req, res) => {
+    const id = needClinica(req, res); if (!id) return
+    try {
+      const { rows } = await pool.query(
+        `SELECT nome, descricao, area FROM especialidades
+         WHERE clinica_id = $1 AND ativo::int = 1 ORDER BY ordem NULLS LAST, nome`, [id])
+      res.json(rows)
+    } catch (e) { res.status(500).json({ error: e.message }) }
+  })
+
+  // Dentistas + horários de atendimento
+  router.get('/dentistas', async (req, res) => {
+    const id = needClinica(req, res); if (!id) return
+    try {
+      const { rows: dentistas } = await pool.query(
+        `SELECT id, nome, especialidade FROM dentistas
+         WHERE clinica_id = $1 AND ativo::int = 1 ORDER BY ordem NULLS LAST, nome`, [id])
+      for (const d of dentistas) {
+        const { rows: hr } = await pool.query(
+          `SELECT dia_semana, hora_inicio, hora_fim FROM dentistas_horarios
+           WHERE dentista_id = $1 AND ativo::int = 1 ORDER BY dia_semana, hora_inicio`, [d.id])
+        d.horarios = hr
+        delete d.id
+      }
+      res.json(dentistas)
+    } catch (e) { res.status(500).json({ error: e.message }) }
+  })
+
+  // Procedimentos + valor particular + valores por plano
+  router.get('/procedimentos', async (req, res) => {
+    const id = needClinica(req, res); if (!id) return
+    try {
+      const { rows: procs } = await pool.query(
+        `SELECT id, nome, descricao, categoria, valorparticular FROM procedimentos
+         WHERE clinica_id = $1 AND ativo::int = 1 ORDER BY ordem NULLS LAST, nome`, [id])
+      for (const p of procs) {
+        const { rows: vp } = await pool.query(
+          `SELECT planonome, valor FROM procedimentos_valores_planos WHERE procedimentoid = $1`, [p.id])
+        p.valor_particular = money(p.valorparticular)
+        p.valores_planos = vp.map((x) => ({ plano: x.planonome, valor: money(x.valor) }))
+        delete p.id; delete p.valorparticular
+      }
+      res.json(procs)
+    } catch (e) { res.status(500).json({ error: e.message }) }
+  })
+
+  // Planos / convênios aceitos
+  router.get('/planos', async (req, res) => {
+    const id = needClinica(req, res); if (!id) return
+    try {
+      const { rows } = await pool.query(
+        `SELECT nome, tipo, descontopadrao FROM planos WHERE clinica_id = $1 ORDER BY nome`, [id])
+      res.json(rows)
+    } catch (e) { res.status(500).json({ error: e.message }) }
+  })
+
+  return router
+}

backend/newwhats/sync-knowledge.js

@@ -0,0 +1,135 @@
+// sync-knowledge.js (ODONTO) — monta o nó de conhecimento da Secretária IA com
+// os dados reais da clínica e sincroniza com o motor NewWhats.
+// Adaptado do satélite mercado. Fluxo:
+//   1. Lê dados do banco (clínica, especialidades, dentistas, procedimentos, planos)
+//   2. Monta texto estruturado do knowledge node
+//   3. PUT/POST no motor (/api/secretaria/*) — rotas internas, sem auth de sessão
+import { getConfig } from './config.js'
+
+const money = (v) => v == null ? null : `R$ ${Number(v).toFixed(2).replace('.', ',')}`
+const DIAS = ['Domingo', 'Segunda', 'Terça', 'Quarta', 'Quinta', 'Sexta', 'Sábado']
+
+async function motorFetch(motorUrl, method, path, body) {
+  const res = await fetch(`${motorUrl}/api/secretaria${path}`, {
+    method,
+    headers: { 'Content-Type': 'application/json' },
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  if (!res.ok) throw new Error(`Motor ${method} /api/secretaria${path} → ${res.status}: ${(await res.text()).slice(0, 200)}`)
+  return res.json()
+}
+
+export async function buildKnowledgeText(pool, clinicaId) {
+  const lines = []
+  const q = (sql, params) => pool.query(sql, params).then((r) => r.rows)
+
+  const [clinica] = await q(
+    `SELECT nome_fantasia, telefone, cidade, estado, logradouro, numero, bairro
+     FROM clinicas WHERE id = $1`, [clinicaId])
+  const nome = clinica?.nome_fantasia || 'Nossa clínica odontológica'
+
+  lines.push(`=== ${nome.toUpperCase()} ===`)
+  lines.push(`Clínica odontológica. Atendimento via WhatsApp.`)
+  if (clinica?.telefone) lines.push(`Telefone: ${clinica.telefone}`)
+  if (clinica?.logradouro) {
+    const end = [clinica.logradouro, clinica.numero, clinica.bairro, clinica.cidade, clinica.estado].filter(Boolean).join(', ')
+    lines.push(`Endereço: ${end}`)
+  }
+  lines.push('')
+
+  // Especialidades
+  const esp = await q(
+    `SELECT nome, descricao FROM especialidades WHERE clinica_id = $1 AND ativo::int = 1 ORDER BY ordem NULLS LAST, nome`, [clinicaId])
+  if (esp.length) {
+    lines.push(`=== ESPECIALIDADES ATENDIDAS ===`)
+    for (const e of esp) lines.push(`• ${e.nome}${e.descricao ? ` — ${e.descricao}` : ''}`)
+    lines.push('')
+  }
+
+  // Dentistas + horários
+  const dentistas = await q(
+    `SELECT id, nome, especialidade FROM dentistas WHERE clinica_id = $1 AND ativo::int = 1 ORDER BY ordem NULLS LAST, nome`, [clinicaId])
+  if (dentistas.length) {
+    lines.push(`=== DENTISTAS ===`)
+    for (const d of dentistas) {
+      lines.push(`• ${d.nome}${d.especialidade ? ` (${d.especialidade})` : ''}`)
+      const hr = await q(
+        `SELECT dia_semana, hora_inicio, hora_fim FROM dentistas_horarios
+         WHERE dentista_id = $1 AND ativo::int = 1 ORDER BY dia_semana, hora_inicio`, [d.id])
+      if (hr.length) {
+        const fmt = hr.map((h) => `${DIAS[h.dia_semana] ?? h.dia_semana} ${String(h.hora_inicio).slice(0, 5)}-${String(h.hora_fim).slice(0, 5)}`)
+        lines.push(`  Atende: ${fmt.join(' | ')}`)
+      }
+    }
+    lines.push('')
+  }
+
+  // Procedimentos + valores
+  const procs = await q(
+    `SELECT id, nome, categoria, valorparticular FROM procedimentos
+     WHERE clinica_id = $1 AND ativo::int = 1 ORDER BY ordem NULLS LAST, nome`, [clinicaId])
+  if (procs.length) {
+    lines.push(`=== PROCEDIMENTOS E VALORES ===`)
+    for (const p of procs) {
+      const part = p.valorparticular != null ? ` — particular: ${money(p.valorparticular)}` : ''
+      lines.push(`• ${p.nome}${p.categoria ? ` [${p.categoria}]` : ''}${part}`)
+      const vp = await q(
+        `SELECT planonome, valor FROM procedimentos_valores_planos WHERE procedimentoid = $1`, [p.id])
+      const comValor = vp.filter((x) => x.valor != null)
+      if (comValor.length) lines.push(`  Por plano: ${comValor.map((x) => `${x.planonome} ${money(x.valor)}`).join(', ')}`)
+    }
+    lines.push('')
+  }
+
+  // Planos / convênios
+  const planos = await q(
+    `SELECT nome, tipo, descontopadrao FROM planos WHERE clinica_id = $1 ORDER BY nome`, [clinicaId])
+  if (planos.length) {
+    lines.push(`=== PLANOS / CONVÊNIOS ACEITOS ===`)
+    for (const pl of planos) {
+      const desc = pl.descontopadrao ? ` — desconto padrão ${pl.descontopadrao}%` : ''
+      lines.push(`• ${pl.nome}${pl.tipo ? ` (${pl.tipo})` : ''}${desc}`)
+    }
+    lines.push('')
+  }
+
+  lines.push(`=== ATENDIMENTO ===`)
+  lines.push(`Para agendar, remarcar ou tirar dúvidas, fale pelo WhatsApp.`)
+  lines.push(`Dúvidas sobre valores, convênios ou disponibilidade: informe que vai encaminhar para a equipe.`)
+
+  return lines.join('\n')
+}
+
+export async function syncKnowledge(pool) {
+  const cfg = getConfig()
+  if (!cfg.motorUrl) throw new Error('NEWWHATS_URL não configurado')
+  if (!cfg.clinicaId) throw new Error('NEWWHATS_CLINICA_ID não configurado')
+
+  const knowledgeText = await buildKnowledgeText(pool, cfg.clinicaId)
+
+  const agents = await motorFetch(cfg.motorUrl, 'GET', '/agents')
+  if (!agents.length) throw new Error('Nenhum agente no motor. Crie um agente na Secretária IA.')
+  const agent = agents.find((a) => a.active) || agents[0]
+
+  const nodes = await motorFetch(cfg.motorUrl, 'GET', `/agents/${agent.id}/nodes`)
+  const kn = nodes.find((n) => n.type === 'knowledge')
+
+  let nodeId
+  const title = 'Base de Conhecimento — Clínica Odontológica'
+  if (kn) {
+    await motorFetch(cfg.motorUrl, 'PUT', `/nodes/${kn.id}`, {
+      title, content: knowledgeText, active: true, sort_order: kn.sort_order ?? 3,
+    })
+    nodeId = kn.id
+  } else {
+    const created = await motorFetch(cfg.motorUrl, 'POST', `/agents/${agent.id}/nodes`, {
+      type: 'knowledge', title, content: knowledgeText, sort_order: 3,
+    })
+    nodeId = created.id
+  }
+
+  return {
+    ok: true, agent_id: agent.id, agent: agent.name, node_id: nodeId,
+    chars: knowledgeText.length, preview: knowledgeText, synced_at: new Date().toISOString(),
+  }
+}

backend/newwhats/webhook-receiver.js

@@ -0,0 +1,52 @@
+// Receptor de webhooks do motor NewWhats (motor → satélite).
+//   POST /api/webhook/newwhats
+//   Header x-nw-signature: sha256=HMAC-SHA256(webhook_secret, rawBody)
+//   Eventos: message.new (nova mensagem WA), session.status (conexão da instância)
+//
+// Versão ENXUTA p/ scoreodonto: valida HMAC, registra o evento e deixa ganchos
+// (TODO) para captura de lead / auto-resposta. NÃO porta o auto-responder do
+// mercado (a Secretária do motor já responde via /secretaria/ask).
+import { Router } from 'express'
+import { createHmac, timingSafeEqual } from 'crypto'
+import { getConfig } from './config.js'
+
+function verifySignature(secret, rawBody, sigHeader) {
+  if (!sigHeader) return false
+  const expected = Buffer.from('sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex'))
+  const received = Buffer.from(String(sigHeader))
+  return expected.length === received.length && timingSafeEqual(expected, received)
+}
+
+export function createWebhookReceiver(_pool) {
+  const router = Router()
+
+  router.post('/api/webhook/newwhats', async (req, res) => {
+    try {
+      const secret = getConfig().webhookSecret
+      if (secret) {
+        const rawBody = req.rawBody ?? Buffer.from(JSON.stringify(req.body))
+        if (!verifySignature(secret, rawBody, req.headers['x-nw-signature'])) {
+          return res.status(401).json({ error: 'Assinatura inválida' })
+        }
+      } else {
+        console.warn('[nw-webhook] NEWWHATS_WEBHOOK_SECRET ausente — assinatura ignorada')
+      }
+
+      const { event, data } = req.body || {}
+      if (event === 'message.new') {
+        // TODO(odonto): registrar lead / acionar fluxo. Hoje só loga.
+        console.log(`[nw-webhook] message.new de ${data?.author ?? data?.pushName ?? '?'}: ${String(data?.body ?? '').slice(0, 60)}`)
+      } else if (event === 'session.status') {
+        console.log(`[nw-webhook] session.status → ${data?.instanceId}: ${data?.status}`)
+      } else {
+        console.log(`[nw-webhook] evento não tratado: ${event}`)
+      }
+      res.json({ ok: true })
+    } catch (e) {
+      console.error('[nw-webhook] erro:', e.message)
+      res.status(500).json({ error: e.message })
+    }
+  })
+
+  return router
+}

dev-build.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Build + sobe o ambiente de DEV (porta 8020 / dev.scoreodonto.com) carimbando
+# a VERSÃO a partir do git — para que /api/version (e o rótulo no app) deixe de
+# mostrar apenas "dev".
+#
+#   Uso (NA VPS):   ./dev-build.sh
+#
+# Diferença p/ produção: a prod consome imagem versionada e injeta a tag em
+# runtime (deploy-prod.sh). Em DEV buildamos local, então derivamos a versão do
+# git AQUI (no host, onde o .git existe) e passamos como build-args do compose.
+# =============================================================================
+set -euo pipefail
+cd "$(dirname "$0")"
+
+export DOCKER_HOST=unix:///run/user/1000/docker.sock
+
+# Versão semântica + commit + carimbo de build, derivados do git.
+#   APP_VERSION -> ex.: v1.0.18-16-g6adf353 (tag mais próxima + distância + sha)
+#   GIT_COMMIT  -> sha curto
+export APP_VERSION="$(git describe --tags --always --dirty 2>/dev/null || echo dev)"
+export GIT_COMMIT="$(git rev-parse --short HEAD 2>/dev/null || echo dev)"
+export BUILD_TIME="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+export APP_ENV="DEV"
+
+echo "──────────────────────────────────────────────────────────────"
+echo " Build ScoreOdonto → DEV (porta 8020)"
+echo "   APP_VERSION = $APP_VERSION"
+echo "   GIT_COMMIT  = $GIT_COMMIT"
+echo "   BUILD_TIME  = $BUILD_TIME"
+echo "──────────────────────────────────────────────────────────────"
+
+docker compose up -d --build scoreodonto-backend scoreodonto-frontend nginx
+
+echo
+echo -n "  versão no ar (DEV): "
+sleep 8
+curl -s --max-time 10 http://localhost:8020/api/version || echo "(ainda subindo — confira em alguns segundos)"
+echo
+echo "✅ DEV buildado com versão carimbada."

doc/AGENDA-COLETA-LAB.md

@@ -0,0 +1,47 @@
+# Agenda & Coleta do laboratório
+
+> Desenho + implementação (24/jun/2026). Gap apontado na auditoria: o lab não tem agenda de
+> produção nem coleta logística (só "próximas entregas" por prazo e custódia de posse).
+
+## Conceito
+- **Coleta** = o lab **busca** o trabalho na clínica (trabalho vai p/ o laboratório).
+- **Entrega** = o lab **leva** o trabalho de volta (trabalho volta p/ a clínica).
+- Cada agendamento tem data/hora, endereço, responsável, observação e status
+  (`agendada | realizada | cancelada`). Ligado a uma OS.
+- **Integra com a custódia:** ao marcar `realizada`, a custódia muda automaticamente
+  (coleta→`laboratorio`, entrega→`clinica`) e entra no histórico da OS. Sem dado duplicado.
+
+## Modelo
+```sql
+CREATE TABLE protese_coleta (
+  id TEXT PRIMARY KEY,
+  os_id TEXT NOT NULL,
+  clinica_id TEXT,
+  laboratorio_id TEXT,
+  protetico_id TEXT,
+  tipo TEXT NOT NULL,            -- coleta | entrega
+  data_hora TIMESTAMPTZ,
+  endereco TEXT,
+  responsavel TEXT,
+  observacao TEXT,
+  status TEXT DEFAULT 'agendada', -- agendada | realizada | cancelada
+  created_by TEXT,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+## Endpoints
+- `POST /api/protese/os/:id/coleta` — agenda (clínica ou lab).
+- `GET /api/protese/lab/agenda` — coletas/entregas do lab (cronológica) + próximas entregas por prazo.
+- `POST /api/protese/coleta/:id/status` — `realizada` (move a custódia) | `cancelada`.
+- GET detalhe da OS passa a trazer `coletas[]`.
+
+## UI
+- **Lab — tela Agenda** (`lab-agenda`, novo item de menu): linha do tempo de coletas/entregas
+  agendadas + entregas previstas (prazo da OS), com ação "marcar realizada".
+- **OS (aba Monitoramento)** — agendar coleta/entrega ao lado da custódia (mesmo contexto físico).
+
+## Decisões
+- 1 coleta por OS (MVP). Agrupar várias OS numa rota/motoboy fica como evolução.
+- `realizada` é a fonte única do movimento físico (atualiza custódia) — evita registrar custódia
+  e coleta em separado.

doc/ANALISE-AREA-RECEPCAO-TC.md

@@ -0,0 +1,158 @@
+# Análise — Área da Recepção / Coordenação de Tratamentos (Treatment Coordinator)
+
+> Gatilho (23/jun/2026): `recep.consulttclinic@gmail.com` lançou uma prótese mas **não tinha
+> a aba para acompanhá-la**. Análise do gap + recomendação fundamentada em modelos validados
+> de software odontológico. Conecta com `FASE2-PROTETICO-AREA.md` (o outro lado do fluxo).
+
+---
+
+## 1. Diagnóstico (DEV `scoreodonto_dev`)
+
+| Entidade | Achado |
+|---|---|
+| Dono | `consulttclinic@gmail.com` → *Rui Cesar*, `donoclinica` |
+| Funcionária | `recep.consulttclinic@gmail.com` (`u_1780962424310_cqsxn`), role `funcionario`, vínculo na **CONSULTT CLINIC LTDA** (`c_1780871001549_koqa3o`) |
+| Cargo | função "Recepcionista" (`fnc_1780962382528_m28go`) |
+| Permissões (antes) | `["agenda","ortodontia","contratos","tratamentos","pacientes","lancar-gto"]` |
+| Prótese lançada | OS `pos_1782228267898_zgfzn` — Prótese Total, paciente ABIGAIR, R$600, protético "Zeca Andrade Fake", status `solicitado`, **via GTO** (`gto_item_id=QOJWR6D`) |
+
+**Gap exato:** o cargo tinha `lancar-gto` (lançar) mas **não** `proteses` (acompanhar). O RBAC da
+`Sidebar.tsx` é literal (`return wsPerms.includes(item.id)`), então a OS criada por ela ficava
+**invisível** para ela própria. A Fase 1 (GTO→OS) funcionou; o problema era de **configuração de
+cargo**, não de arquitetura.
+
+---
+
+## 2. Modelos validados (referência externa)
+
+- **Papel = "Treatment Coordinator" + Front Desk.** É a ponte entre paciente e equipe clínica:
+  sequencia planos multi-etapa, conduz o aceite do caso (case acceptance), arranjo financeiro e
+  follow-up até a conclusão — exatamente "gerir tratamentos" de ponta a ponta.
+- **RBAC por papel é o padrão.** Permissões mapeadas a papéis, não a indivíduos; o front desk
+  recebe agenda/cadastro/cobrança, tipicamente **sem notas clínicas**. O ScoreOdonto já faz isso
+  via `funcoes.permissoes[]`.
+- **Prótese = "Lab Case", acompanhada pelo front desk.** No Dentrix Lab Case Manager: clínico cria
+  a prescrição → status *Sent* → **o front desk muda para *Received* quando volta do lab** →
+  *Finished* ao assentar. Ou seja: acompanhar a OS de prótese é, por modelo consagrado, **atribuição
+  da recepção** — o acesso que faltava.
+
+Fontes:
+- The Role of a Treatment Coordinator — https://www.dentalmanagers.com/blog/role-of-treatment-coordinator-in-dental-practice/
+- What Does a Treatment Plan Coordinator Do? — https://www.teero.com/blog/treatment-plan-coordinator
+- Dental Software User Permissions (Curve) — https://www.curvedental.com/blog/dental-software-user-permissions
+- RBAC in Healthcare — https://www.accountablehq.com/post/role-based-access-control-rbac-in-healthcare-benefits-examples-and-best-practices
+- Manage Your Lab Cases in Dentrix — https://magazine.dentrix.com/manage-your-lab-cases-in-dentrix/
+- Open Dental — Lab Cases — https://www.opendental.com/manual/labcasemanage.html
+
+---
+
+## 3. Ação aplicada — Nível 1 (configuração, sem código)
+
+✅ **Aplicado no DEV em 23/jun/2026.** Função "Recepcionista" da CONSULTT CLINIC LTDA atualizada:
+
+```sql
+UPDATE funcoes
+   SET permissoes = '["agenda","pacientes","tratamentos","ortodontia","proteses","lancar-gto","orcamentos","contratos"]'
+ WHERE id = 'fnc_1780962382528_m28go';   -- UPDATE 1
+```
+
+Acréscimos: **`proteses`** (acompanhar a OS que ela lança) e **`orcamentos`** (case acceptance —
+coração do papel TC). Efeito imediato: a OS `pos_1782228267898_zgfzn` passa a aparecer para ela.
+
+> Escopo: alteração **só no DEV**. Não há mudança de código nem migração — é dado de configuração.
+> Para refletir em outras clínicas, ajustar o cargo equivalente de cada uma (ou rever o template
+> de cargos padrão, se existir).
+
+---
+
+## 3b. Causa raiz (investigação 23/jun) — `proteses` não é concedível pela UI
+
+A correção de dado acima trata o sintoma. A **causa raiz** é um bug de configuração de RBAC:
+
+- Cargos **não** têm seed no backend (signup não cria funções). São criados manualmente pelo
+  dono em Gestão de Equipe (`POST → INSERT INTO funcoes`, `server.js:806`), partindo de 4
+  templates do frontend (`GestaoEquipeView.tsx:96`).
+- **Nenhum** template inclui `proteses`: RECEPÇÃO (`dashboard,agenda,pacientes,leads,orcamentos`),
+  AUXILIAR (`...,ortodontia,tratamentos`), FINANCEIRO (`...,financeiro,relatorios,lancar-gto`),
+  GERENTE (`[...TODAS_PAGINAS]`).
+- **Raiz:** `proteses` **não está em `PAGINAS_RBAC`** (`GestaoEquipeView.tsx:57`), a lista mestre
+  de páginas atribuíveis. Como `TODAS_PAGINAS = PAGINAS_RBAC.flatMap(...)`, **nem o GERENTE /
+  "MARCAR TODAS"** concede prótese. ⇒ **É impossível um dono dar `proteses` a um funcionário
+  pela interface** — só via UPDATE direto no banco (o que foi feito na §3).
+- Também ausentes da lista atribuível, embora em uso: **`contratos`** (a função tinha — legado),
+  `comissoes`, `glosas`.
+
+**Resposta à pergunta "o cargo Recepcionista padrão nasce sem proteses?":** Sim — e mais,
+*nenhum* cargo consegue tê-la pela UI hoje.
+
+### Fix de raiz (código) — ✅ aplicado e validado no DEV (23/jun)
+Em `frontend/views/GestaoEquipeView.tsx`:
+- `PAGINAS_RBAC`, grupo `ATENDIMENTO`: + `{ key: 'proteses', label: 'PRÓTESES' }` e
+  `{ key: 'contratos', label: 'CONTRATOS' }` → agora concedíveis pela UI (e entram em
+  `TODAS_PAGINAS`/GERENTE/"MARCAR TODAS").
+- Templates: RECEPÇÃO ganhou `contratos, lancar-gto, proteses`; AUXILIAR ganhou `proteses`
+  (alinhado ao papel TC).
+
+**Validação:** `vite build` transformou 2382 módulos OK; container DEV rebuildado e no ar; o
+bundle servido pelo nginx DEV (`index-*.js`, alvo de `dev.scoreodonto.com`) contém
+`key:"proteses",label:"PRÓTESES"` e a string `proteses` nos 3 pontos editados. Cargos padrão
+passam a nascer coerentes — sem UPDATE manual por clínica.
+
+> ⚠️ Pendente de commit + deploy à produção (a mudança está só no DEV). Os fixes de **dado**
+> (§3, função da CONSULTT CLINIC) continuam sendo só-DEV e não se propagam por este fix de código.
+
+## 4. Recomendação — Nível 2 (estrutural, "Fase 3")
+
+Em vez de abas soltas (`tratamentos`, `proteses`, `ortodontia`), um **hub de Coordenação de
+Tratamentos por paciente**: pipeline único com o status de cada frente (clínico / prótese-lab /
+orto), espelhando o "lab case visível para toda a equipe" do Dentrix. View nova que **agrega o que
+já existe** (`tratamentos` + `protese_os` + ortodontia por paciente) — sem dado novo.
+
+## 5. Conexão com a Fase 2
+Dois lados do mesmo fluxo, unidos pela mesma `protese_os`:
+- **Fase 2** → casa do **protético** (quem produz; avança status na Bancada).
+- **Esta análise** → **recepção/TC** (quem encomenda e acompanha; lê o status no hub).
+O status que o lab avança é o mesmo que a recepção lê — o "Lab Case Manager" repartido entre os papéis.
+
+---
+
+## 6. Salas: acesso do funcionário corrigido + bloqueio de manutenção (23/jun)
+
+Gatilho: a mesma recepcionista aparecia com **MINHAS SALAS** e **ALUGAR SALAS** (gestão de
+locação, de titular) e deveria ter apenas a **agenda da sala** e o **bloqueio para manutenção**.
+
+### 6a. Bug — vazamento dos menus de locação ✅ corrigido (`Sidebar.tsx`)
+`MINHAS SALAS` (locador) e `ALUGAR SALAS` (locatário) eram empurrados a "todos menos
+superadmin" (`Sidebar.tsx:42`), vazando para **funcionário e paciente** — papéis que não são
+titulares de sala. Passaram a exibir apenas a `PAPEIS_LOCACAO`
+(`donosala/donoclinica/donoconsultorio/admin/dentista/biomedico/protetico`). O backend já era
+seguro por ownership; era vazamento só de UI.
+
+### 6b. Feature — acesso operacional + manutenção ✅ implementada e validada no DEV
+Não existia caminho para "funcionário vê só a agenda" nem "bloqueio para manutenção" — foram
+criados (modelos de mercado: *Dentrix/Open Dental Lab... não; aqui é gestão de espaço* — o
+padrão é **front desk opera a agenda da sala sem tocar no financeiro do locador**).
+
+- **Acesso operacional** (`server.js` `listarWorkspaces`): sala cuja `clinica_id` é uma clínica
+  onde o usuário tem vínculo (e ele **não** é o dono) entra como workspace `tipo='sala'` com
+  `papel_sala='operador'`. O `SalaHomeView` detecta o modo operador e **esconde recebíveis,
+  relatório e baixa** — mostra só a **agenda** + botão de bloqueio.
+- **Bloqueio de manutenção** (`POST /api/salas/:id/manutencao`): reserva `tipo='manutencao'`
+  (coluna nova, default `'locacao'`), `valor=0`, nasce `'confirmada'` (sem aprovação) e **não
+  gera recebível**. Acesso: dono **ou** membro com vínculo na clínica da sala. Reaproveita o
+  anti-conflito de horário (409) e o cancelamento por solicitante/unidade. A agenda renderiza
+  o bloqueio em **cinza** (legenda "Manutenção").
+
+**Validação ponta a ponta (DEV, JWT real da recepcionista, sala de teste vinculada à clínica):**
+| Caso | Resultado |
+|---|---|
+| Sala da clínica vira workspace operador dela | ✅ query retorna a sala |
+| POST bloqueio | ✅ `status:confirmada, tipo:manutencao` |
+| GET agenda mostra bloqueio + motivo | ✅ `valor:0, motivo:"Conserto do equipo"` |
+| Conflito de horário | ✅ HTTP 409 |
+| Não gera financeiro | ✅ 0 lançamentos |
+
+Commits: `fix(salas)` (menu) + `feat(salas)` (operador + manutenção). Backend e frontend no ar
+no DEV; dados de teste limpos.
+
+> ⚠️ Pendente de push + deploy (produção segue em v1.0.19).

doc/DEPLOY-PRODUCAO.md

@@ -1,117 +0,0 @@
-# Deploy & Versionamento — Runbook ScoreOdonto
-
-> Auditado contra o sistema em **17/jun/2026**. Cada item carrega seu **status real**.
->
-> **Legenda:** ✅ EM PRODUÇÃO · 🧪 EM DEV (não promovido) · 🎯 ALVO (não implementado).
->
-> **Produção AGORA:** `v1.0.16 · commit 471c2c2 · 2026-06-17` (`curl https://scoreodonto.com/api/version`).
-> Modelo **Build Once → Promote → Deploy** completo — Passo 5 validado em v1.0.16. Tudo abaixo ✅.
-
----
-
-## 1. O modelo  ✅
-
-> **Push** na `main` builda **uma vez** e publica por **commit**; a **tag `vX.Y.Z`** **re-tagueia** esse mesmo artefato (sem rebuild) e deploya. **Produção nunca builda — só executa imagens.**
-
-```
- PUSH main (commit C)                 TAG vX.Y.Z (no commit C)
-        │                                     │
-        ▼                                     ▼
-   CI: build (1x)                       CI: promote (SEM build) ✅
-   publica :C + :latest                 re-tag :C → :vX.Y.Z (MESMO digest) + deploy
-        ▼                                     ▼
-   registry                             VPS1: pull :vX.Y.Z + up --no-build
-                                        APP_VERSION=tag injetada em runtime
-```
-Prova (v1.0.16): `:v1.0.16` tem **digest idêntico** a `:471c2c2` — a tag é só um rótulo sobre a imagem já testada.
-
----
-
-## 2. Estado por componente (verificado)
-
-| Componente | Status | Detalhe |
-|---|---|---|
-| Infra VPS1/3/4 + Docker rootless | ✅ | Mapa na §3 |
-| Registry (`git.clube67.com/ruicesar/...`) | ✅ | Ver `REGISTRY.md` |
-| CI: job `build` publica por **commit** em push (sem `APP_VERSION`) | ✅ | `.gitea/workflows/build.yml` (runner `vps4-builder`) |
-| Job `promote` por tag: re-tag `:<commit>→:vX.Y.Z` (sem rebuild) + deploy | ✅ | validado em v1.0.16 (`:v1.0.16` == `:471c2c2`) |
-| Validação de integridade no promote (commit existe? digest igual? front+back mesmo commit) | ✅ | falha se o commit não foi pushado |
-| Produção não builda (`image:` + `pull` + `up --no-build`) | ✅ | `docker-compose.prod.yml` |
-| Banco DEV isolado em `pgdev`; prod no Postgres da VPS3 | ✅ | Ver `BANCO-DEV-ESTRATEGIA.md` |
-| Versão em runtime (`/api/version`) → Configurações + telas públicas | ✅ | `useAppVersion()`; sem `APP_VERSION` manual |
-| `APP_VERSION`/`APP_ENV` injetados no deploy em runtime | ✅ | `compose.prod` `environment` |
-| Versão **nasce da tag git** (`constants.ts`/`update-version.js` removidos) | ✅ | Passo 5 |
-
----
-
-## 3. Mapa de máquinas ✅
-
-| Onde | Host | Papel | Docker |
-|---|---|---|---|
-| VPS1 | `10.99.0.1` | **Produção** (Traefik + apps) | rootless |
-| VPS3 | `10.99.0.3` | Postgres (prod) + Gitea + registry | — |
-| VPS4 | `10.99.0.4` | **Dev + Builder** (código; runner CI; `pgdev`) | rootless |
-
-- Repo: `ssh://git@10.99.0.3/ruicesar/scoreodonto.com.git`. Project Compose: `scoreodontocom`.
-
----
-
-## 4. De onde vem a versão (`/api/version`)
-
-```json
-{ "name": "ScoreOdonto API", "version": "v1.0.16", "commit": "471c2c2",
-  "build": "2026-06-17 10:35 UTC", "environment": "PROD" }
-```
-- **commit / build** = carimbados no **build** (imutáveis — identidade do artefato).
-- **version / environment** = **injetados no deploy em runtime** (a partir da tag). A mesma imagem é promovida sob qualquer tag, sem rebuild.
-- **Frontend** lê tudo de `/api/version` (`useAppVersion()`); não embute versão. Fonte única = backend.
-
----
-
-## 5. Runbook — subir um release ✅
-
-> ⚠️ **Regra de ouro:** confirme **DEV ou PRODUÇÃO**. `dev.scoreodonto.com` = VPS4 (banco `pgdev`). `scoreodonto.com` = VPS1 (real). **Nunca** `git push --force` na `main`. Push/tag exigem autorização explícita.
-
-```bash
-# 1) VPS4: validar em DEV
-cd /home/deploy/stack/scoreodonto.com
-node --check backend/server.js
-docker compose build scoreodonto-backend scoreodonto-frontend
-docker compose up -d --force-recreate scoreodonto-backend scoreodonto-frontend   # https://dev.scoreodonto.com
-
-# 2) commit + push → CI builda 1x e publica :<commit> + :latest (NÃO deploya)
-git add -A && git commit -m "feat: <descrição>"
-git push origin main
-
-# 3) tag = "aprovado p/ produção" → job PROMOTE re-tagueia :<commit>→:vX.Y.Z (SEM rebuild) + deploya
-#    (o número da versão é livre — não precisa casar com nenhum arquivo)
-git tag -a vX.Y.Z -m "release vX.Y.Z" && git push origin vX.Y.Z
-
-# 4) verificar (sem SSH)
-curl -s https://scoreodonto.com/api/version     # → vX.Y.Z · <commit> · PROD
-```
-
-**Backup do banco de PRODUÇÃO antes de releases sensíveis** (via container, pois não há shell na VPS3):
-```bash
-docker run --rm -e PGPASSWORD=<senha> -v /home/deploy/backups:/b postgres:18 \
-  pg_dump -h 10.99.0.3 -U scoreodonto_user -d scoreodonto -Fc -f /b/scoreodonto_$(date +%Y%m%d_%H%M).dump
-```
-
----
-
-## 6. Rollback ✅
-
-Por imagem, **sem rebuild** — na VPS1:
-```bash
-/home/deploy/stack/scoreodonto.com/deploy-prod.sh <tag-ou-commit-anterior>   # pull + up --no-build
-```
-⚠️ A referência confiável é o **commit** (`:<sha>`). Tags `:vX.Y.Z` antigas (pré-Passo 5) podem ter sido republicadas com código diferente — a partir do Passo 5, `:vX.Y.Z` é sempre um alias imutável do commit. Migrações são aditivas (voltar o código é seguro). Dump em `/home/deploy/backups/` só em extremo.
-
----
-
-## 7. Follow-ups (não bloqueiam)  🎯
-- `GET /api/health` (monitoramento/diagnóstico).
-- **Política de retenção** do registry (uma imagem `:<commit>` por push acumula).
-- Reconciliar o repo na VPS1 (working tree sujo, não afeta o deploy por imagem).
-
-Racional do modelo em `deploy.md`; histórico em `project-cicd-tag-promove-nao-rebuilda` (memória).

doc/FASE2-IMPL-2.0-2.1.md

@@ -0,0 +1,217 @@
+# Fase 2 — Detalhamento de implementação: passos 2.0 e 2.1
+
+> ✅ **IMPLEMENTADO e validado em DEV (23/jun/2026).** Commits `feat(protese): Fase 2 backend`
+> + `frontend`. Validações: registro de protético nasce `laboratorio`; backfill preenche
+> `laboratorio_id`; bancada roteia por lab (fallback por pessoa); entrega gera **par espelhado**
+> DESPESA(clínica)+RECEITA(lab) R$600, idempotente (409 na re-entrega); menu do lab no bundle.
+>
+> ⚠️ **Bug pré-existente achado e corrigido junto:** o INSERT da DESPESA de prótese (Fase 1, já
+> em produção v1.0.20) usava `paciente_nome` — coluna inexistente em `financeiro` (é
+> `pacientenome`). A entrega de OS com `custo>0` **abortava** em produção. Corrigido no mesmo
+> commit de backend. **Recomenda-se priorizar o deploy** por causa disso.
+
+
+> Companheiro de `FASE2-PROTETICO-AREA.md` (o modelo). Aqui está o **como**, a nível de
+> arquivo/função, fiel ao código atual de `backend/server.js` e `frontend/`.
+> Decisões aplicadas: **1 lab por protético**, **só terceirizado**, **receita espelhada na 2.1**.
+> Disciplina herdada da Fase 1: migrações aditivas/idempotentes; blocos novos em `try/catch`
+> que nunca derrubam o fluxo principal; `protetico_id` sempre preservado (fallback).
+
+---
+
+# PASSO 2.0 — Dados invisíveis (backfill `laboratorio_id`)
+
+Nenhuma mudança de UI. Objetivo: todo protético tem um workspace `tipo='laboratorio'` e toda
+OS/produto carrega `laboratorio_id`. Validar 100% em DEV (`pgdev`) antes de seguir.
+
+## 2.0.a — Migrações (em `runMigrations()`, junto às da Fase 1, ~linha 5663)
+
+```js
+// ── FASE 2.0: Laboratório como workspace de 1ª classe ──────────────────────
+`ALTER TABLE protese_os       ADD COLUMN IF NOT EXISTS financeiro_lab_id TEXT`, // RECEITA espelhada (2.1)
+`ALTER TABLE protese_produtos ADD COLUMN IF NOT EXISTS laboratorio_id TEXT`,
+// laboratorio_id em protese_os JÁ EXISTE (coluna reservada na criação da tabela) — não recriar.
+
+// re-tag: o workspace pessoal do protético passa a ser 'laboratorio'
+`UPDATE clinicas SET tipo='laboratorio'
+   WHERE tipo='pessoal'
+     AND owner_id IN (SELECT id FROM usuarios WHERE role='protetico')`,
+
+// backfill: cada OS herda o laboratorio do workspace do seu protético
+`UPDATE protese_os o SET laboratorio_id = c.id
+   FROM clinicas c
+  WHERE o.laboratorio_id IS NULL AND c.tipo='laboratorio' AND c.owner_id = o.protetico_id`,
+
+// backfill: catálogo passa a ser do laboratório (mantém protetico_id p/ compat)
+`UPDATE protese_produtos p SET laboratorio_id = c.id
+   FROM clinicas c
+  WHERE p.laboratorio_id IS NULL AND c.tipo='laboratorio' AND c.owner_id = p.protetico_id`,
+
+// índice por lab (o de protetico_id já existe; adiciona o do lab)
+`CREATE INDEX IF NOT EXISTS idx_protese_os_labid ON protese_os (laboratorio_id, status)`,
+```
+> O `UPDATE especialidades … area='protese'` da Fase 1 já está logo acima — não duplicar.
+
+## 2.0.b — Helper: resolver o laboratório de um protético
+
+Novo helper perto de `proteseOsAccesso` (~linha 3772). 1 lab por protético ⇒ `LIMIT 1`.
+
+```js
+// O workspace 'laboratorio' do protético (1 por protético nesta fase).
+async function labDoProtetico(proteticoId) {
+    if (!proteticoId) return null;
+    const { rows } = await pool.query(
+        "SELECT id FROM clinicas WHERE owner_id=$1 AND tipo='laboratorio' AND COALESCE(deleted_at IS NULL, true) LIMIT 1",
+        [proteticoId]);
+    return rows[0]?.id || null;
+}
+```
+> Se `clinicas` não tiver `deleted_at`, usar só `WHERE owner_id=$1 AND tipo='laboratorio'`.
+
+## 2.0.c — Gravar `laboratorio_id` na CRIAÇÃO da OS (2 pontos)
+
+**(i) `POST /api/protese/os`** (~linha 3893): resolver o lab e incluí-lo no INSERT.
+```js
+const labId = await labDoProtetico(b.protetico_id);   // antes do INSERT
+// no INSERT: acrescentar a coluna laboratorio_id e o valor labId
+//   ... protetico_id, laboratorio_id, protetico_nome, ...
+//   VALUES ($1,$2,$3,$LAB,$4,...)
+```
+
+**(ii) Bloco GTO→protese_os (Fase 1)** em `PUT /api/gto-builder/:id/finalizar`
+(o INSERT em `protese_os` que você acabou de escrever): mesma adição.
+```js
+const labId = await labDoProtetico(it.protetico_id);  // dentro do for, antes do INSERT
+// incluir laboratorio_id = labId no INSERT da OS gerada por GTO
+```
+> Assim, OS novas já nascem com `laboratorio_id`; as antigas foram cobertas pelo backfill.
+
+## 2.0.d — Bancada roteia por laboratório (com fallback por pessoa)
+
+`GET /api/protese/bancada` (~linha 3926). Hoje: `WHERE protetico_id=$1`. Passa a aceitar OS
+do(s) laboratório(s) do usuário, mantendo fallback para OS ainda sem `laboratorio_id`:
+
+```js
+const uid = req.authUser.userId;
+const labId = await labDoProtetico(uid);              // o lab do protético logado
+const vals = [uid, labId];
+let where = `( (laboratorio_id IS NOT NULL AND laboratorio_id=$2)
+            OR (laboratorio_id IS NULL AND protetico_id=$1) ) AND deleted_at IS NULL`;
+if (req.query.status && PROTESE_STATUS.includes(req.query.status)) {
+    vals.push(req.query.status); where += ` AND status=$${vals.length}`;
+}
+// resto idêntico (ORDER BY / LIMIT / map)
+```
+> `proteseOsAccesso` **não muda na 2.0** (1 lab por protético ⇒ `protetico_id===uid` ainda
+> identifica o lab). O `OR por vínculo no lab` entra só na 2.3 (equipe/`tecnico_protese`).
+
+## 2.0.e — Novos protéticos já nascem com `tipo='laboratorio'`
+
+No `POST /api/register` (~linha 625), o INSERT do workspace usa `tipo='pessoal'` para todos.
+Diferenciar o protético:
+```js
+const wsTipo = userRole === 'protetico' ? 'laboratorio' : 'pessoal';
+`INSERT INTO clinicas (id, nome_fantasia, tipo, owner_id) VALUES ($1,$2,$3,$4)` // $3 = wsTipo
+```
+> O seed de catálogo (`seedProteseProdutos(userId)`) continua por `protetico_id` (owner) —
+> sem mudança. (O `laboratorio_id` do catálogo é resolvido pelo backfill / por leitura.)
+
+## ✅ Critérios de aceite 2.0 (validar em DEV)
+- `SELECT count(*) FROM protese_os WHERE laboratorio_id IS NULL` → **0** (após backfill).
+- Toda `clinicas` de protético tem `tipo='laboratorio'`.
+- Criar OS nova (via Nova OS **e** via finalizar GTO) → `laboratorio_id` preenchido.
+- Bancada continua mostrando exatamente as mesmas OS de antes (fallback cobre o legado).
+- **Zero** mudança visível na UI.
+
+---
+
+# PASSO 2.1 — Casa própria + receita espelhada
+
+Agora o protético entra numa **área de Laboratório** (menu próprio) e a entrega passa a
+lançar a receita no workspace do lab.
+
+## 2.1.a — BACKEND: receita espelhada na entrega
+
+Em `POST /api/protese/os/:id/status`, dentro do `if (novo === 'entregue') { ... }`, logo após
+o bloco que cria a **DESPESA** (`finId`). Mesma condição (`custo>0 && tipo_os≠'garantia'`):
+
+```js
+// Espelho: RECEITA no workspace do laboratório (clinica_id = laboratorio_id). Idempotente.
+let finLabId = os.financeiro_lab_id || null;
+try {
+    const labId = os.laboratorio_id || await labDoProtetico(os.protetico_id);
+    if (!finLabId && labId && Number(os.custo) > 0 && os.tipo_os !== 'garantia') {
+        finLabId = `fin_lab_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+        await pool.query(
+            `INSERT INTO financeiro (id, clinica_id, descricao, valor, tipo, status, datavencimento, data_competencia, paciente_id, paciente_nome, origem, centro_custo, sem_comissao)
+             VALUES ($1,$2,$3,$4,'RECEITA','Pendente',CURRENT_DATE,CURRENT_DATE,$5,$6,'protese','PRÓTESE',true)`,
+            [finLabId, labId, `PRÓTESE: ${os.tipo} (cliente ${clinicaNome || ''})`.trim(), Number(os.custo),
+             os.paciente_id || null, os.paciente_nome || null]);
+    }
+} catch (e) { console.error('[protese entrega→receita lab]', e.message); }
+```
+E no `UPDATE protese_os` da entrega, persistir o id:
+```js
+// ...financeiro_id=COALESCE($3,financeiro_id), financeiro_lab_id=COALESCE($N,financeiro_lab_id)...
+```
+> `clinicaNome` = nome da clínica de origem (1 query opcional, ou usar `os.clinica_id`).
+> **Estorno** (cancelar entrega) é tarefa à parte: reverter os dois `financeiro` — fica para
+> a sub-fase de cancelamento; por ora a entrega é terminal (já é hoje: 409 se `entregue`).
+
+## 2.1.b — FRONTEND: menu da área de Laboratório (`Sidebar.tsx`)
+
+**(i)** Acrescentar os itens ao array `menuItems` (~linha 53):
+```js
+{ id: 'lab-home',      label: 'PAINEL DO LAB', icon: LayoutDashboard },
+{ id: 'lab-bancada',   label: 'BANCADA',       icon: FlaskConical },
+```
+(catálogo/clientes/agenda/financeiro entram na 2.2/2.3 — não criar itens mortos agora.)
+
+**(ii)** Isolar o menu quando o workspace ativo é laboratório — **espelhar** o bloco que já
+existe para `tipo==='sala'` (~linha 98). Inserir antes dele:
+```js
+// Contexto de LABORATÓRIO: área própria do protético (não é clínica).
+if ((activeWorkspace as any)?.tipo === 'laboratorio')
+    return ['lab-home', 'lab-bancada', 'notificacoes', 'configuracoes'].includes(item.id);
+```
+> Como o protético tem **1** workspace e ele é `tipo='laboratorio'`, esse branch governa o
+> menu dele. O antigo filtro `currentRole==='protetico'` (linha ~131) deixa de ser alcançado
+> para o caso comum, mas **mantê-lo** como rede de segurança (protético sem workspace lab).
+
+## 2.1.c — FRONTEND: roteamento das telas novas (`App.tsx`)
+
+No switch/router de `view` do `App.tsx`, mapear:
+```jsx
+case 'lab-bancada': return <ProteseView />;   // já renderiza modo 'bancada' p/ role protetico
+case 'lab-home':    return <LabHomeView />;    // novo painel (abaixo)
+```
+> `ProteseView` já decide `modo='bancada'` por `getCurrentRole()==='protetico'` — reaproveita
+> 100%. Só muda o **id de menu** que a abre.
+
+## 2.1.d — FRONTEND: `LabHomeView` (painel mínimo)
+
+Nova view `frontend/views/LabHomeView.tsx`. Cards a partir de dados que já existem:
+- **Fila por status** e **atrasadas**: derivar de `getProteseBancada()` (já retorna `atrasada`).
+- **Faturamento do mês**: somar `financeiro` RECEITA `origem='protese'` do workspace lab
+  (rota de financeiro existente, escopada por `clinicaId` = id do lab).
+- **Prazo médio / entregues no mês**: agregação simples sobre a bancada.
+
+Sem rota nova obrigatória na 2.1 (reusa `bancada` + `financeiro`); se quiser um resumo de 1
+chamada, criar `GET /api/protese/lab/resumo` depois.
+
+## ✅ Critérios de aceite 2.1
+- Logado como protético, a Sidebar mostra **PAINEL DO LAB** + **BANCADA** (+ notificações/config).
+- A clínica continua com a tela PRÓTESES (modo `clinica`) **intacta**.
+- Entregar uma OS com `custo>0` (não-garantia) cria **2** lançamentos: DESPESA na clínica e
+  RECEITA no lab (mesmo valor `custo`); reentregar/reprocessar **não** duplica (`COALESCE`).
+- OS de garantia entregue → **nenhum** lançamento (nos dois lados).
+- `LabHomeView` mostra fila + faturamento do mês do laboratório.
+
+---
+
+# Ordem de execução e deploy
+1. Branch a partir da `main` (que já tem a Fase 1 não-commitada — **commitar a Fase 1 antes**).
+2. 2.0 (backend só) → subir em DEV (`dev.scoreodonto.com`/`pgdev`), rodar os SELECTs de aceite.
+3. 2.1 (backend receita + front) → validar aceite em DEV.
+4. Commit por sub-fase; push → CI builda por commit; `git tag vX.Y.Z` promove à produção.
+> Migrações aditivas ⇒ rollback de código é seguro (padrão já validado no projeto).

doc/FASE2-PROTETICO-AREA.md

@@ -0,0 +1,220 @@
+# Fase 2 — Área do Protético (Laboratório como workspace de 1ª classe)
+
+> Desenho de modelo. Continuação da **Fase 1 (GTO → Prótese)**, onde finalizar uma GTO
+> abre automaticamente uma OS na Bancada (`protese_os.gto_item_id`).
+> **Objetivo da Fase 2:** o protético deixa de ser "um papel que só vê a Bancada" e passa
+> a ter uma **área de gestão própria** — o Laboratório — equivalente ao que a Clínica é para
+> o dentista. Ele gere catálogo, equipe, clientes (clínicas), financeiro e agenda de entregas.
+
+---
+
+## 1. Onde estamos hoje (não reinventar)
+
+O alicerce já existe — a Fase 2 **promove**, não cria do zero:
+
+| Já existe | Onde |
+|---|---|
+| Role `protetico` (válido em `usuarios` e `vinculos`) | `server.js` VALID_ROLES / constraints |
+| Workspace pessoal "LABORATÓRIO DE …" criado no signup | `clinicas (tipo='pessoal')` + `vinculos (role='protetico')` |
+| Catálogo de produtos (preço fixo + garantia) | `protese_produtos (protetico_id)` |
+| Bancada (fila de OS do protético) | `GET /api/protese/bancada` (roteia por `protetico_id`) |
+| OS com eventos, fotos, status, garantia, financeiro | `protese_os`, `protese_os_evento`, `protese_os_foto` |
+| `ProteseView` com `modo: 'bancada' | 'clinica'` por role | `frontend/views/ProteseView.tsx` |
+| **`protese_os.laboratorio_id`** — reservado, hoje `null` | comentário: "workspace destino (futuro)" |
+| Menu filtrado por role (protético = subset) | `Sidebar.tsx` linha ~131 |
+
+**Lacuna que a Fase 2 fecha:** o Laboratório não é uma *entidade gerenciável*. O protético
+roteia OS por `protetico_id` (a pessoa), não por um laboratório (a empresa). Não há painel,
+equipe, visão de clientes, nem financeiro do lado do laboratório. A OS conhece a *pessoa*,
+não a *bancada/empresa*.
+
+---
+
+## 2. Decisão de modelo: Laboratório = workspace `tipo='laboratorio'`
+
+O sistema já trata **workspace** de forma polimórfica: `clinicas` é a tabela-base e `tipo`
+distingue (`clinica` | `pessoal` | `sala`). A Fase 2 introduz **`tipo='laboratorio'`** em vez
+de criar uma tabela nova. Isso reaproveita: vínculos, troca de workspace, RBAC por cargo,
+financeiro, notificações e o seletor de workspace da Sidebar.
+
+```
+            usuarios (role='protetico')
+                  │  vinculos (role='protetico' | 'tecnico_protese')
+                  ▼
+        clinicas  (tipo='laboratorio')   ◄── "LABORATÓRIO DE X" deixa de ser 'pessoal'
+                  │
+      ┌───────────┼─────────────────────────────┐
+      ▼           ▼                             ▼
+ protese_produtos  protese_os (laboratorio_id)   equipe (vinculos do lab)
+   (catálogo)        ▲  roteamento por LAB,
+                     │  não mais só por pessoa
+        clínicas-cliente enviam OS ──┘
+```
+
+### Migração do dado existente (aditiva, idempotente)
+```sql
+-- 1) re-tag do workspace pessoal do protético → laboratorio
+UPDATE clinicas SET tipo='laboratorio'
+ WHERE tipo='pessoal'
+   AND owner_id IN (SELECT id FROM usuarios WHERE role='protetico');
+
+-- 2) backfill: toda OS legada ganha o laboratorio_id do workspace do seu protetico
+UPDATE protese_os o SET laboratorio_id = c.id
+  FROM clinicas c
+ WHERE o.laboratorio_id IS NULL
+   AND c.tipo='laboratorio'
+   AND c.owner_id = o.protetico_id;
+
+-- 3) o catálogo passa a ser do laboratório (mantém protetico_id p/ compat)
+ALTER TABLE protese_produtos ADD COLUMN IF NOT EXISTS laboratorio_id TEXT;
+UPDATE protese_produtos p SET laboratorio_id = c.id
+  FROM clinicas c
+ WHERE p.laboratorio_id IS NULL AND c.tipo='laboratorio' AND c.owner_id = p.protetico_id;
+```
+> `protetico_id` **continua** populado em todas as tabelas (compatibilidade da Fase 1 e do
+> roteamento por pessoa). `laboratorio_id` passa a ser a **chave de escopo** da área.
+
+---
+
+## 3. A Área do Laboratório (navegação)
+
+Quando o `activeWorkspace.tipo === 'laboratorio'`, a Sidebar troca para um menu próprio
+(análogo ao `tipo==='sala'` que já isola o menu). Itens:
+
+| Item | Conteúdo | Reaproveita |
+|---|---|---|
+| `lab-home` | **Painel** do laboratório: OS por status, atrasadas, faturamento do mês, prazo médio | novo dashboard + agregações de `protese_os` |
+| `lab-bancada` | **Bancada** (fila de produção, kanban por status) | `ProteseView` modo bancada (já existe) |
+| `lab-catalogo` | **Catálogo** de produtos (preço/garantia) — vira tela, não modal | `ProdutosModal` → view |
+| `lab-clientes` | **Clínicas-cliente**: quem envia OS, volume, ticket, pendências | distinct de `protese_os.clinica_id` |
+| `lab-agenda` | **Agenda de entregas** por `prazo_entrega` | AgendaView adaptada / nova |
+| `lab-financeiro` | **A receber** das clínicas (a OS gera DESPESA na clínica = RECEITA no lab) | `protese_os.financeiro_id` (elo) |
+| `lab-equipe` | **Técnicos** do laboratório (RBAC por cargo já existe) | `vinculos` + permissões de workspace |
+| `notificacoes` / `configuracoes` | base | já existe |
+
+A tela "PRÓTESES" da **clínica** (modo `clinica`) não muda — ela continua **enviando** OS.
+O que muda é o **lado de quem recebe**, que ganha uma casa própria.
+
+### Roteamento de OS: pessoa → laboratório
+- Hoje: `bancada` filtra `WHERE protetico_id = me`.
+- Fase 2: `bancada` filtra `WHERE laboratorio_id = activeWorkspace.id` (com fallback
+  `OR (laboratorio_id IS NULL AND protetico_id = me)` durante a transição).
+- Ganho imediato: **mais de um técnico** pode atender a mesma bancada (equipe), e o protético
+  dono pode ter **mais de um laboratório**.
+
+---
+
+## 4. Modelo de dados — deltas da Fase 2
+
+Tudo aditivo (migrações no padrão `ALTER TABLE … IF NOT EXISTS`, como a Fase 1):
+
+```sql
+-- workspace
+clinicas.tipo                         -- novo valor possível: 'laboratorio'
+
+-- escopo por laboratório (a empresa), além de protetico_id (a pessoa)
+protese_os        ADD laboratorio_id TEXT    -- (já reservado; passa a ser populado/backfill)
+protese_os        ADD financeiro_lab_id TEXT -- RECEITA espelhada no lab (§9; idempotência)
+protese_produtos  ADD laboratorio_id TEXT
+
+-- equipe do laboratório: novo role de vínculo (técnico não-dono)
+vinculos.role  -- incluir 'tecnico_protese' no CHECK constraint
+
+-- relação clínica↔laboratório (opcional, p/ "meus laboratórios favoritos"/preços negociados)
+CREATE TABLE IF NOT EXISTS lab_clientes (
+    id TEXT PRIMARY KEY,
+    laboratorio_id TEXT NOT NULL,
+    clinica_id TEXT NOT NULL,
+    apelido TEXT,
+    desconto_pct NUMERIC DEFAULT 0,     -- preço negociado (futuro)
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    UNIQUE (laboratorio_id, clinica_id)
+);
+```
+
+Índices: `idx_protese_os_lab` passa a ser `(laboratorio_id, status)`.
+
+---
+
+## 5. Permissões (RBAC)
+
+Reaproveita o RBAC por cargo que já existe na Sidebar (`wsRole`/`wsPerms`):
+
+| Papel no laboratório | Pode |
+|---|---|
+| `protetico` (dono do lab) | tudo: catálogo, equipe, financeiro, status de qualquer OS |
+| `tecnico_protese` (membro) | bancada + avançar status + fotos; **sem** financeiro/equipe/catálogo |
+| clínica-cliente (`isClinic` em `proteseOsAccesso`) | criar OS, ver suas OS, entregar/cancelar, **sem** ver custo/bancada de outros |
+
+`proteseOsAccesso(os, userId)` ganha o caso "membro do laboratório dono da OS"
+(`vinculo em laboratorio_id`), além do dono atual.
+
+---
+
+## 6. Plano de implementação incremental
+
+Cada passo é deployável e reversível (migrações aditivas → rollback de código é seguro).
+
+- **2.0 — Dados (invisível):** migrações + backfill `laboratorio_id`; `bancada` lê por lab com
+  fallback por pessoa. Nada muda na UI. *Risco mínimo, valida o backfill em DEV (`pgdev`).*
+- **2.1 — Casa própria + receita espelhada:** `tipo='laboratorio'` re-tagueado; Sidebar com
+  menu do laboratório; `lab-home` (painel) + `lab-bancada`; **espelho de RECEITA na entrega**
+  (§9) — o financeiro mínimo do lab já nesta fase, conforme decisão 3.
+- **2.2 — Catálogo e clientes:** `ProdutosModal` vira `lab-catalogo`; tela `lab-clientes`.
+- **2.3 — Financeiro completo e equipe:** `lab-financeiro` (extrato/a-receber por cliente,
+  sobre as receitas já lançadas na 2.1) + `tecnico_protese` (convite de membro reusando o
+  fluxo de equipe existente).
+- **2.4 — Agenda de entregas + multi-laboratório** (expansão; modelo já suporta, sem migração).
+
+---
+
+## 7. O que **não** muda (contrato preservado)
+- O lado **clínica** de `ProteseView` (modo `clinica`) e o envio de OS.
+- A **Fase 1**: GTO finalizada continua abrindo OS (`gto_item_id`), agora já com
+  `laboratorio_id` preenchido na criação.
+- `protetico_id` permanece em todas as tabelas — roteamento por pessoa segue funcionando
+  como fallback; nenhuma OS legada fica órfã.
+
+---
+
+## 8. Decisões de produto (fechadas em 23/jun/2026)
+1. **Um laboratório por protético.** A UI assume 1 lab. O modelo de dados já suporta N
+   (`laboratorio_id` por OS/produto), então multi-lab é expansão futura **sem migração**.
+2. **Laboratório terceirizado** (empresa separada que cobra da clínica). A flag `interno`
+   de `getProteseLaboratorios` fica como gancho futuro, mas **não** é tratada agora —
+   todo lab gera receita/despesa cruzada entre tenants.
+3. **Financeiro espelhado já na 2.1.** A OS entregue, que hoje lança **DESPESA na clínica**
+   (`protese_os.financeiro_id`), passa a lançar simultaneamente uma **RECEITA no workspace
+   do laboratório**. Ver §9.
+
+---
+
+## 9. Financeiro espelhado (decisão 3) — DESPESA na clínica ↔ RECEITA no lab
+
+Hoje a entrega da OS gera um lançamento de **DESPESA** na clínica de origem
+(`protese_os.financeiro_id`), no valor de **`os.custo`** (o preço de catálogo do lab — o que a
+clínica paga ao laboratório; `os.valor` é o preço ao paciente, markup da clínica, e **não**
+entra aqui). Como o laboratório agora é um workspace de 1ª classe, o mesmo evento de entrega
+lança um **par espelhado**, ambos sobre `os.custo`:
+
+```
+  entrega da OS (status='entregue', custo>0, tipo_os≠'garantia')
+        │
+        ├─► financeiro (DESPESA)  clinica_id = os.clinica_id       valor = os.custo  [já existe]
+        └─► financeiro (RECEITA)  clinica_id = os.laboratorio_id   valor = os.custo  [novo]
+```
+
+- Mesma **condição** da despesa já existente: só lança se `custo > 0` e `tipo_os ≠ 'garantia'`
+  (OS de garantia refaz sem cobrar). Sai no mesmo `if (novo === 'entregue')`.
+- Idempotente, no padrão da Fase 1: novo `protese_os.financeiro_lab_id` guarda o id do
+  lançamento de receita; se já existe (`COALESCE`), não duplica.
+- Isolado em `try/catch` para **nunca** derrubar a transição de status (mesma disciplina do
+  bloco GTO→protese_os da Fase 1).
+- Estorno: cancelar/estornar a entrega deve reverter **os dois** lançamentos.
+
+Por isso o **passo 2.1 já inclui o financeiro mínimo** (apenas o espelho de receita na
+entrega); o item de menu `lab-financeiro` completo (extrato, a-receber por cliente) continua
+na 2.3.
+
+> ⚠️ Pré-requisito: `laboratorio_id` precisa estar populado **antes** de ligar o espelho
+> (senão a receita nasce sem destino). Por isso a ordem **2.0 (backfill) → 2.1** é obrigatória.

doc/MARKETPLACE-TRANSACIONAL-PROTESE.md

@@ -0,0 +1,58 @@
+# Marketplace transacional de Prótese
+
+> Desenho (24/jun/2026). O último grande item do backlog do Provedor de Prótese.
+> Princípio: **transformar o diretório (descoberta) em jornada de compra** — descobrir → ver
+> serviços/preços → solicitar → cotar → contratar → vira OS. Reaproveita ao máximo o que já existe.
+
+## O que já existe (não recriar)
+- **Descoberta:** `/api/profissionais/marketplace` (busca por proximidade/especialidade) **+ Nota
+  ScoreOdonto** no card (feito).
+- **Catálogo:** `protese_produtos` (nome, preço, garantia) + `GET /api/protese/laboratorios/:id/produtos`
+  — já acessível a quem está no **diretório** (`proteticoAcessivelPelaClinica` aceita `disponivel_diretorio`).
+- **Propostas:** `propostas_profissional` (clínica→profissional: mensagem, `pendente→aceita/recusada`).
+- **Contratação:** a clínica **já cria OS para qualquer protético do diretório** (Nova OS).
+- **Pós-venda:** OS completa (etapas, custódia, ocorrências), financeiro, score — tudo pronto.
+
+**Conclusão:** o "transacional" não exige nova fundação — falta **costurar a jornada** dentro do
+marketplace (hoje a clínica vê nome/nota/distância, mas não os serviços, e contrata por outra tela).
+
+## Fatias
+
+### ✅ Fatia 1 — Vitrine (catálogo no marketplace) — IMPLEMENTADA
+No card do protético no marketplace, **"Ver catálogo"** expande os produtos (nome, preço, garantia)
+via `getLaboratorioProdutos(id)` (reuso — zero endpoint novo). A clínica passa a **decidir vendo
+serviços + preço + garantia + ★nota** antes de contratar. Botão de contato vira **"Solicitar
+prótese"** (proposta com contexto de prótese).
+
+### ✅ Fatia 2 — Solicitação → OS direto — IMPLEMENTADA
+"Solicitar prótese" (card do protético) abre o `SolicitarProteseModal` — fluxo enxuto com o lab
+**pré-selecionado**: produto do catálogo (ou descrição livre) + paciente (busca) + dentista + dentes
++ prazo + observações → **cria a OS** via `createProteseOS` (que já aceita lab do diretório, sem
+vínculo prévio). Tela de confirmação com CTA para a Bancada. Optei por um modal próprio e auto-contido
+(reusa getLaboratorioProdutos/getDentistas/getPacientes/createProteseOS) em vez de extrair a Nova OS —
+menor risco. Validado em DEV: OS criada para lab do diretório (Coroa de Zircônia, status solicitado).
+
+### ✅ Fatia 3 — Cotação (RFQ) — IMPLEMENTADA
+Entidades novas `protese_rfq` + `protese_rfq_cotacao`. Fluxo: a clínica descreve o trabalho e
+**convida N labs** → cada lab **cota** (valor/prazo/obs) → a clínica **compara** (ordenado por preço)
+e **escolhe** → vira **OS** (custo = valor da cotação) e a RFQ fecha (demais cotações recusadas).
+Endpoints: `POST/GET /protese/rfq`, `GET /protese/rfq/recebidas`, `POST /protese/rfq/cotacao/:id`,
+`POST /protese/rfq/:id/escolher`. UI: lado lab = tela **Cotações** (`lab-cotacoes`, responde); lado
+clínica = botão **Cotações** na tela de Prótese (pedir multi-lab + comparar + escolher). Validado em
+DEV ponta a ponta (pedido → cotação R$420 → escolha → OS criada → RFQ fechada).
+
+### ✅ Fatia 4 — Reputação (avaliação + selo) — IMPLEMENTADA
+A clínica avalia o laboratório (1-5★ + comentário) **após a entrega** (`protese_avaliacao`, 1 por OS,
+reavaliável). A satisfação **entra na Nota ScoreOdonto**: `0.6·operacional + 0.4·(estrelas/5·10)` (sem
+avaliações = só operacional). **Selo "Verificado"** com ≥ 5 entregas. Exposto no marketplace (★nota ·
+nº avaliações · Verificado) e nos indicadores do lab (KPI Satisfação). Endpoint `POST
+/protese/os/:id/avaliar`. Validado em DEV: 6 entregas + avaliações 5★/3★ → nota **9.2**, satisfação 4★,
+verificado, em marketplace e indicadores.
+
+**Marketplace transacional concluído (Fatias 1-4).**
+
+## Decisões de modelagem
+- **Catálogo público = catálogo atual** (`protese_produtos`); a vitrine só o exibe — sem duplicar.
+- **Solicitação reusa a OS** (não cria entidade paralela): toda contratação termina em `protese_os`,
+  preservando rastreabilidade/financeiro/score.
+- **Cotação (Fatia 3)** é o único caso que precisa de entidade nova (pré-OS multi-lab).

doc/MODO1-LINK-SEGURO-PROTESE.md

@@ -0,0 +1,117 @@
+# Modo 1 — Provedor de Prótese SEM conta (link seguro `/p/TOKEN`)
+
+> Desenho (24/jun/2026). Evolução registrada como "fora de escopo" em `PROVEDOR-PROTESE-DECISAO.md`.
+> Princípio (decisão arquitetural): **a clínica opera 100% da OS; o protético não precisa ter conta.**
+> O link é a porta de entrada do ecossistema — acompanha hoje, vira conta amanhã.
+
+## Objetivo
+A clínica cria/gere a OS normalmente. O protético recebe um **link seguro** (WhatsApp/e-mail) e,
+**sem login**, acompanha e atua na OS dele. Com CTA para criar conta grátis (conversão).
+
+```
+Clínica cria OS ──► gera link /p/TOKEN ──► WhatsApp/e-mail ──► Protético abre (sem conta)
+                                                                  ├─ vê a OS (sem CPF/valores do paciente)
+                                                                  ├─ confirma recebimento/devolução
+                                                                  ├─ avança etapa / anexa foto
+                                                                  └─ responde ocorrência
+                                                          "Crie sua conta grátis" ──► cadastro (card Protético)
+```
+
+## 1. Escopo do token: **por OS** (não por protético)
+Escopo mínimo = menor superfície de risco. Um token dá acesso a **uma OS**. Vantagens: revogável
+individualmente, expira por trabalho, não expõe a carteira inteira do protético. (Evolução: um token
+"carteira" por protético-na-clínica que lista várias OS — fica para depois.)
+
+## 2. Modelo de dados (revogável e auditável)
+```sql
+CREATE TABLE IF NOT EXISTS protese_os_link (
+    token TEXT PRIMARY KEY,            -- aleatório longo (≥ 32 bytes base62), NÃO sequencial
+    os_id TEXT NOT NULL,
+    protetico_id TEXT,                 -- a quem se destina (rastreio)
+    created_by TEXT,                   -- quem na clínica gerou
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    expires_at TIMESTAMPTZ,            -- opcional (ex.: +30 dias); null = sem expirar
+    revoked_at TIMESTAMPTZ,            -- revogação manual
+    last_access_at TIMESTAMPTZ,
+    acessos INTEGER DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_protese_os_link_os ON protese_os_link (os_id);
+```
+> Preferir tabela a JWT puro: permite **revogar** e **auditar acessos**. O token nunca contém dados.
+
+## 3. Rotas públicas (sem `authGuard`; o token é a credencial)
+Todas resolvem `os_id` pelo token (valida não-revogado, não-expirado) e aplicam a **mesma blindagem
+do provedor**: sem `paciente_id`/CPF, sem valores do paciente (reusa a lógica `soLab`).
+
+| Rota | Ação |
+|---|---|
+| `GET /api/p/:token` | OS: nº, clínica, dentista, paciente (nome, conforme permissão), prazo, status, observações, fotos, componentes, ocorrências, custódia. **Sem CPF/valores do paciente.** |
+| `POST /api/p/:token/custodia` | confirmar recebimento / devolução (clínica↔lab) |
+| `POST /api/p/:token/status` | avançar a produção (recebido→…→finalizado) |
+| `POST /api/p/:token/foto` | anexar foto do trabalho (+ ocorrência) |
+| `POST /api/p/:token/ocorrencias/:id/resposta` | responder ocorrência (contraditório) |
+
+Cada ação registra no histórico da OS um **actor "Protético (link)"** com o `protetico_id` do token —
+mantendo a auditoria. Mesmas validações de status/foto já existentes.
+
+## 4. Geração e envio (lado clínica)
+Na OS (modal, aba Etapas ou Monitoramento): botão **"Enviar ao protético"** →
+`POST /api/protese/os/:id/link` gera/recupera o token e devolve a URL
+`https://scoreodonto.com/p/TOKEN`. Atalhos: **WhatsApp** (`https://wa.me/?text=…`) e **e-mail**
+(`mailto:`). Botão **"Revogar link"** para invalidar.
+
+## 5. Frontend público `/p/:token`
+Rota **fora do app autenticado** (sem Sidebar/login). Página enxuta que reusa as seções do
+`OSDetailModal` em modo "público/lab" (etapas, fotos, componentes, custódia, ocorrências — sem
+financeiro/clientes). Topo com a marca + rodapé fixo:
+
+> *"Gostou de acompanhar por aqui? Crie sua conta grátis e gerencie todos os seus laboratórios."*
+> → leva ao cadastro **já com o card Protético** (adicionado) e e-mail pré-preenchido.
+
+## 6. Segurança (checklist)
+- Token aleatório ≥ 32 bytes, base62, **não sequencial**; comparação em tempo constante.
+- Escopo de **1 OS**; expiração opcional; **revogável**; rate-limit por token/IP.
+- **Sem CPF e sem valores do paciente** (mesma blindagem `soLab` da Fase 1).
+- Ações registram actor no histórico (auditoria); `last_access_at`/`acessos` para detectar abuso.
+- OS `entregue`/`cancelado` → link vira **somente leitura**.
+
+## 7. Conversão (o "porquê de negócio")
+O link é aquisição: o protético experimenta o produto sem fricção e, ao criar conta, **herda o
+histórico** (as OS daquela clínica já estão ligadas ao `protetico_id` dele). Liga direto ao
+marketplace/score (Fase 5) — quanto mais clínicas o usam, mais OS e melhor o score do protético.
+
+## 8. Faseamento sugerido
+- **✅ 1a (núcleo) — IMPLEMENTADA 24/jun:** tabela `protese_os_link` (token aleatório 24 bytes
+  base64url, expira em 60 dias, revogável); `POST /api/protese/os/:id/link` (gera/recupera) +
+  `POST …/link/revogar`; `GET /api/p/:token` (leitura pública curada — sem CPF, sem valor do
+  paciente; conta acessos). Página pública `/p/:token` (`ProtesePublicView`, mobile-first 320px+,
+  interceptada no `index.tsx` antes do app autenticado); botão "Gerar link / WhatsApp / Copiar" na
+  aba Monitoramento (modo clínica). CTA "Criar conta grátis". Validado em DEV (leitura, blindagem,
+  token inválido→404, revogação→404).
+- **✅ 1b (ação) — IMPLEMENTADA 24/jun:** o protético, pelo link, **confirma recebimento/devolução**
+  (`POST /api/p/:token/custodia`), **avança a produção** (`/status`, só `recebido…finalizado` — nunca
+  entregue/cancelado, que são da clínica) e **anexa foto** (`/foto`). Tudo auditado como
+  `"<nome> (link)"`. Página pública ganha a seção "Atualizar status" (botões de custódia, etapa e foto)
+  enquanto a OS não está finalizada. Validado em DEV: recebimento, avanço, foto, e `entregue` pelo link
+  → 400 (bloqueado).
+- **✅ 1c (gestão) — IMPLEMENTADA 24/jun:** UI da clínica (aba Monitoramento) gere o link:
+  `GET /api/protese/os/:id/link/status` traz **link ativo, nº de acessos, último acesso e expiração**;
+  botões **Copiar / WhatsApp / Revogar**. Validado em DEV: acessos contados, expiração 60 dias,
+  revogação → status inativo + leitura pública 404.
+  > Conversão por herança: nativa — a OS já aponta para o `protetico_id` do destinatário, então ao
+  > entrar/criar conta ele já é dono do histórico. (Vincular um cadastro NOVO com e-mail diferente às
+  > OS é caso de borda — fica para evolução, evitando duplicar usuário.)
+
+**Modo 1 concluído (1a leitura + 1b ação + 1c gestão).**
+
+### ✅ Extras (24/jun)
+- **Carteira pela link** (`GET /api/p/:token/carteira`): botão "Meus trabalhos" na página pública →
+  trabalhos em andamento + finalizados + **mini financeiro mensal** (valores pagos ao protético).
+  Escopo = a relação clínica↔protético da OS do token (não vaza outras clínicas; sem dados do paciente).
+- **Protético INTERNO (sem conta)** (`POST /api/protese/proteticos-internos`): a clínica cadastra um
+  protético que não usa a plataforma — cria um usuário "mudo" (e-mail placeholder `..@interno.local`,
+  senha-fantasma; `usuarios.email` é NOT NULL/UNIQUE) + vínculo interno (fora do diretório). Botão
+  "Cadastrar protético interno" na Nova OS. A partir daí recebe OS e acompanha pelo link, sem conta.
+
+> Nenhuma refatoração: reusa OS/eventos/custódia/ocorrências/blindagem já existentes. Só adiciona a
+> camada de token público.

doc/PROVEDOR-PROTESE-DECISAO.md

@@ -0,0 +1,121 @@
+# Decisão arquitetural — Provedor de Prótese (módulo de Prótese)
+
+> Decisão de negócio/interface (24/jun/2026). Base: auditoria do código (`AUDITORIA-PROTESE.md`).
+> Princípio-guia: **a Clínica controla 100% do fluxo, mesmo que o Protético nunca crie conta.**
+> O login do Provedor é **alavanca de crescimento** (marketplace/ecossistema), não pré-requisito.
+
+## Conceito
+"**Provedor de Prótese**" é rótulo de **negócio/interface**. Internamente **NÃO se renomeia** o
+role `protetico` (aparece 87× no backend + 15 arquivos no front — refatorar = risco alto, ganho
+zero). As três formas são variações do **mesmo** workspace `tipo='laboratorio'`, diferenciadas por
+metadados (futuros `pessoa_tipo`, `tem_equipe`), não por novos roles:
+
+```
+PROVEDOR DE PRÓTESE  (role=protetico, workspace tipo='laboratorio')
+├── Profissional Individual (PF)
+├── Laboratório (PJ)
+└── Laboratório com Equipe (PJ + técnicos)
+```
+
+## Modos de operação
+- **Modo 1 — Protético SEM conta:** a Clínica opera tudo (OS, etapas, envio/recebimento/devolução,
+  pagamentos, componentes, ocorrências, encerramento). O Protético acompanha por **link seguro**
+  (`/p/TOKEN` via WhatsApp/e-mail), podendo confirmar recebimento/devolução, anexar fotos, responder
+  ocorrências. CTA: "crie sua conta ScoreOdonto".
+- **Modo 2 — Protético COM conta:** Dashboard, Ordens, Produção, Entregas, Clientes, Financeiro,
+  Catálogo, Notificações, Perfil.
+- **Modo 3 — Laboratório:** + Equipe, Relatórios, Marketplace, Configurações.
+
+## Cadastro/Login
+Card próprio **[ PROTÉTICO / LABORATÓRIO ]** com opção PF (Protético Individual) / PJ (Laboratório).
+Campos futuros (não obrigatórios no MVP): Nome, Nome Fantasia, CPF, CNPJ, CROT, Responsável Técnico,
+Cidade, Estado, Especialidades, Telefone, E-mail. (Campo `clinicas.documento` já existe para CPF/CNPJ.)
+
+## Rastreabilidade de componentes (modelo)
+Uma tabela (`protese_os_componente`) com eixo de direção/conferência, não duas:
+`enviado pela clínica → recebido pelo protético → devolvido pelo protético → conferido pela clínica`.
+A **ocorrência referencia o componente** (FK opcional).
+
+## Ocorrências + Contraditório
+Tabela própria. Categorias: não devolvido, danificado, incompatível, parafuso substituído/desgastado,
+peça incorreta, ajuste inadequado, falha de fabricação, retrabalho, outro. Campos: autor, data,
+categoria, descrição, fotos, evidências, anexos, responsável, status.
+**Fluxo com contraditório** (proteção dos dois lados): `Aberta → Respondida → Em análise → Resolvida`
+ou `Contestada`. **Só ocorrências resolvidas** alimentam indicadores — nunca automático.
+
+## Abas da OS (alvo)
+`Dados · Fotos · Componentes · Pagamentos · Custódia · Histórico · Ocorrências` (nova).
+
+## Indicadores (POR ÚLTIMO)
+Capturar primeiro (eventos, componentes, ocorrências, evidências, histórico); só depois derivar
+Score/ranking/marketplace. Não codar indicador antes de existir dado.
+
+---
+
+## Roadmap (5 fases)
+
+### ✅ FASE 1 — Origem da OS + LGPD (IMPLEMENTADA 24/jun)
+- **Clínica de origem** na bancada e no detalhe (`clinica_nome` via subquery) — visível ao protético
+  (badge na lista e no modal). Destrava o cenário multi-clínica.
+- **Blindagem de CPF:** confirmado que `pacientes.id` **É o CPF**. O protético (lab) deixa de receber
+  `paciente_id` (detalhe e bancada zeram), mantendo `paciente_nome`. A clínica continua vendo o CPF.
+- Validado em DEV: protético vê `clinica_nome` + `paciente_id:null`; clínica vê tudo.
+
+### ✅ FASE 2 — Rastreabilidade & Ocorrências (IMPLEMENTADA 24/jun)
+- **Componentes** ganham `direcao` (enviado/devolvido) e `status_conferencia` (pendente/ok/divergente/
+  ausente, com `conferido_nome/_em`). Endpoint `POST .../componentes/:id/conferir`.
+- **Ocorrências** (`protese_os_ocorrencia`): 10 categorias, descrição, responsável, autor, status.
+  Evidências via `protese_os_foto.ocorrencia_id` (reusa a infra de mídia).
+- **Contraditório**: `aberta → respondida → em_analise → resolvida | contestada`; `resolvida` é final
+  (409 ao remexer). Endpoints `/ocorrencias`, `/ocorrencias/:id/resposta`, `/ocorrencias/:id/status`.
+- **UI**: nova aba **Ocorrências** no modal (com contador) + conferência inline nos componentes.
+- Validado em DEV: componente `divergente`; ocorrência `parafuso_substituido` percorrendo todo o
+  contraditório até `resolvida`; resolvida final (409). Indicadores ficam para a Fase 5.
+
+### ✅ FASE 3 — Operação multi-clínica (IMPLEMENTADA 24/jun)
+- **Clientes** (tela `lab-clientes`): tabela das clínicas que enviam OS, com OS totais, ativas,
+  atrasadas, entregues, faturado e a-receber por cliente. Endpoint `GET /protese/lab/clientes`.
+- **Financeiro do lab** (tela `lab-financeiro`): KPIs (faturado/recebido/a-receber) + extrato de
+  recebimentos (pagamentos lado lab) com clínica/paciente/forma/data. Endpoint `GET /protese/lab/pagamentos`.
+  Regra: faturado = custo das OS entregues (exceto garantia); a-receber = faturado − recebido.
+- Menu do laboratório agora: Painel · Bancada · **Clientes** · **Financeiro** · Notificações · Config.
+- Histórico completo: a Bancada já lista entregues/cancelados com filtro de status (mantida).
+- Validado em DEV: agregação por clínica (faturado 600 / recebido 250 / a-receber 350) + extrato.
+
+### ✅ FASE 4 — Empresa de verdade (IMPLEMENTADA 24/jun)
+- **PF/PJ + documento**: `clinicas.pessoa_tipo` (PF=individual | PJ=laboratório); `documento` = CPF/CNPJ
+  (já existia, agora editável). Tela **Laboratório & Equipe** (`lab-equipe`): GET/PATCH `/protese/lab`.
+- **Equipe/Técnicos**: novo `vinculos.role='tecnico_protese'`. O dono convida por e-mail
+  (`ensureUsuarioPorEmail` → credencial temporária); endpoints `GET/POST/DELETE /protese/lab/equipe`.
+- **Acesso estendido**: `proteseOsAccesso` reconhece o técnico (vínculo no `laboratorio_id`); a bancada
+  usa `labDoUsuario` (dono **ou** técnico). Técnico opera a produção; **não** vê clientes/financeiro
+  (menu reduzido + endpoints retornam vazio/403). Gestão é exclusiva do dono.
+- Validado em DEV: dados PJ+CNPJ; técnico convidado acessa a bancada (vê clínica de origem), não vê
+  clientes (0) e leva 403 ao tentar gerenciar equipe.
+
+### ✅ FASE 5 — Indicadores & Score (IMPLEMENTADA 24/jun)
+- **Indicadores derivados** (`GET /protese/lab/indicadores`, só dono) calculados sobre a captura das
+  fases 2-4: entregues, tempo médio (solicitado→entregue), atraso %, retrabalho % (garantia),
+  ocorrências resolvidas %, componentes ausentes. Tela `lab-indicadores`.
+- **Nota ScoreOdonto** (0-10): `10 − (atraso%×3 + retrabalho%×4 + ocorrência%×3)`, só com **mínimo de
+  3 entregas** (senão "score em formação"). Só ocorrências **resolvidas** entram (contraditório respeitado).
+- **Ranking no marketplace**: `getProteseLaboratorios` passa a devolver a `nota` por protético e ordena
+  internos→maior nota→nome; a clínica vê `★ nota` no dropdown de Nova OS e do Lançar GTO.
+- Validado em DEV: 4 entregas (1 atrasada, 1 garantia) → atraso 25% / retrab 25% / **nota 8.3**; a
+  clínica vê a nota no dropdown; "score em formação" abaixo do mínimo.
+
+> Acoplamentos respeitados: PF/PJ veio com a equipe (Fase 4); Score só após a captura (Fases 2-4).
+
+### Pós-roadmap (entregue depois das Fases 1-5)
+- **✅ Modo 1** (protético sem conta via link `/p/TOKEN`) — completo (1a leitura, 1b ação, 1c gestão).
+  Ver `MODO1-LINK-SEGURO-PROTESE.md`.
+- **✅ Higiene** — menu legado do protético removido (Sidebar/App): o protético opera só no workspace
+  laboratório; fallback mínimo fora dele.
+- **✅ Score público no marketplace** — `GET /api/profissionais/marketplace` traz a `nota` ScoreOdonto
+  dos protéticos (helper `notasScorePorProtetico`, mesma fórmula da Fase 5), exibida como ★ no card.
+  Ordem mantida por proximidade; a nota é critério de comparação visível.
+
+### Ainda em aberto (futuro)
+Marketplace **transacional** (anúncio de serviços + solicitação/contratação/propostas dentro da
+plataforma); **agenda de produção/coleta**; **multi-unidade** do laboratório; envio automático do
+link (e-mail/WhatsApp API) e herança de cadastro novo com e-mail diferente.

doc/VERDADE-HOJE.md

@@ -1,6 +1,6 @@
 # Qual é a verdade hoje? — Auditoria de infra ScoreOdonto
 
-> Resposta direta às 6 perguntas essenciais, **verificada em 17/jun/2026**. Somente fatos do estado atual.
+> Resposta direta às 6 perguntas essenciais, **verificada em 23/jun/2026**. Somente fatos do estado atual.
 > **Documento principal: em caso de divergência entre docs, este prevalece.**
 > Como operar → `DEPLOY-PRODUCAO.md` (runbook). Para onde vamos → `deploy.md` (arquitetura-alvo).
 
@@ -9,7 +9,7 @@
 ### 1. Onde está o código?
 - **Fonte da verdade:** Gitea na **VPS3**, repo `ruicesar/scoreodonto.com`.
 - **Dev (trabalho):** VPS4 em `/home/deploy/stack/scoreodonto.com`.
-- **Produção:** VPS1 roda **imagens versionadas do registry** (não código-fonte). No ar: **v1.0.16 · commit `471c2c2`**.
+- **Produção:** VPS1 roda **imagens versionadas do registry** (não código-fonte). No ar: **v1.0.31 · commit `4673f3c`**.
 - **Documentação:** centralizada em `scoreodonto.com/doc/` (pasta única).
 
 ### 2. Onde está o banco?
@@ -28,7 +28,7 @@
 - ✅ **Build Once → Promote (Passo 5, validado em produção):** push builda 1× e publica por **commit** (`:<sha>`); a **tag re-tagueia** esse artefato como `:vX.Y.Z` (sem rebuild — digest idêntico) e deploya. Provado em v1.0.16 (`:v1.0.16` == `:471c2c2`, mesmo digest).
 
 ### 5. Como versiona?
-- A versão exibida vem do **backend em runtime**: `GET /api/version` (de `process.env`), mostrada em **Configurações → "Sobre o sistema"** e nas telas públicas (o frontend consome via `useAppVersion()`, não embute mais a versão). No ar: **v1.0.16 · `471c2c2` · PROD**.
+- A versão exibida vem do **backend em runtime**: `GET /api/version` (de `process.env`), mostrada em **Configurações → "Sobre o sistema"** e nas telas públicas (o frontend consome via `useAppVersion()`, não embute mais a versão). No ar: **v1.0.31 · `4673f3c` · PROD**.
 - A versão **nasce da tag git** e é **injetada no deploy em runtime** (`APP_VERSION`=tag, `APP_ENV=PROD`); `commit`/`build` vêm carimbados na imagem.
 - ✅ **`constants.ts`/`update-version.js` foram removidos** (Passo 5) — não há mais versão manual.
 
@@ -39,4 +39,4 @@
 ---
 
 ## Veredito de uma linha
-> O código vive no Gitea (VPS3); a **produção (VPS1) roda imagens versionadas do registry** (hoje **v1.0.16**), sem buildar; o **DEV está isolado no `pgdev`** (não toca o banco de produção). **CI/CD por tag ativo** no modelo **Build Once → Promote → Deploy** (push builda por commit; tag re-tagueia sem rebuild e deploya — validado em v1.0.16), com **versão visível em runtime** (`/api/version` → Configurações) nascendo da tag git.
+> O código vive no Gitea (VPS3); a **produção (VPS1) roda imagens versionadas do registry** (hoje **v1.0.31**), sem buildar; o **DEV está isolado no `pgdev`** (não toca o banco de produção). **CI/CD por tag ativo** no modelo **Build Once → Promote → Deploy** (push builda por commit; tag re-tagueia sem rebuild e deploya — validado em v1.0.16), com **versão visível em runtime** (`/api/version` → Configurações) nascendo da tag git.

docker-compose.dev.yml

@@ -1,11 +1,18 @@
-# ─── Dev override — NO docker compose build required ─────────────────────────
+# ─── Dev override — modo desenvolvimento com HMR ─────────────────────────────
 #
-# Usage:
-#   docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
+# Uso:
+#   docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
 #
-# What changes in dev:
-#   - Backend: Runs node server.js with direct hot mount of backend/
-#   - Frontend: Runs vite dev server on port 3013 with Hot Module Replacement (HMR)
+# O que muda em relação à produção:
+#   - Backend: monta ./backend ao vivo (node server.js), preservando o
+#     node_modules da imagem (node:20-slim) — código reflete sem rebuild.
+#   - Frontend: builda o stage `builder` (node:20-alpine, que TEM vite +
+#     node_modules no arch musl correto) e roda o vite dev server na 3013 com
+#     Hot Module Replacement. O nginx (default.conf) já faz proxy de / → :3013
+#     com headers de Upgrade, então o WS de HMR passa.
+#
+# ⚠️  Este box serve APENAS dev.scoreodonto.com. A produção (scoreodonto.com)
+#     roda em outro servidor — flipar esta stack para dev NÃO afeta produção.
 # ─────────────────────────────────────────────────────────────────────────────
 
 services:
@@ -15,13 +22,20 @@ services:
       - NODE_ENV=development
     volumes:
       - "/home/deploy/scoreodonto-sessions:/app/sessions"
-      - "./backend:/app"
+      - "/home/deploy/scoreodonto-media:/app/media"
+      - "./backend:/app"          # source ao vivo (server.js + newwhats/ do túnel)
+      - "/app/node_modules"       # preserva node_modules da imagem (arch correto)
+      - "./plugins:/app/plugins"
 
   scoreodonto-frontend:
+    build:
+      context: "."
+      dockerfile: frontend/Dockerfile
+      target: builder             # node:20-alpine com vite + node_modules (musl)
     command: ["npx", "vite", "--port", "3013", "--host", "0.0.0.0"]
     environment:
-      - PORT=3013
       - NODE_ENV=development
+      - DEV_PUBLIC_HOST=dev.scoreodonto.com   # libera host + roteia HMR por wss:443 (vite.config)
     volumes:
-      - "./frontend:/app"
-      - /app/node_modules
+      - "./frontend:/app/frontend"   # source ao vivo (HMR)
+      - "/app/frontend/node_modules" # preserva node_modules da imagem (musl)

docker-compose.yml

@@ -35,10 +35,14 @@ services:
       - "./backend/.env"
     environment:
       - BAILEYS_ENGINE=infinite
+      - TZ=America/Sao_Paulo
       - PORT=8018
       - NODE_ENV=production
-      - DATABASE_URL=postgresql://${SCOREO_DB_USER:-scoreodonto_user}:${SCOREO_DB_PASS:-clube67_scoreodonto_pass_9903}@${SCOREO_DB_HOST:-10.99.0.3}:5432/${SCOREO_DB_NAME:-scoreodonto}?schema=public
-      - DRAGONFLY_URL=redis://:clube67_dragonfly_pass_9903@10.99.0.3:6379/1
+      # Senha do banco vem do ambiente (.env raiz em DEV; provisionado fora do git em PROD).
+      # `:?` falha o `up` se a senha não estiver definida — evita subir com senha vazia/errada.
+      # Host/usuário/banco mantêm default (não são segredo); só a senha é obrigatória via env.
+      - DATABASE_URL=postgresql://${SCOREO_DB_USER:-scoreodonto_user}:${SCOREO_DB_PASS:?defina SCOREO_DB_PASS no .env}@${SCOREO_DB_HOST:-10.99.0.3}:5432/${SCOREO_DB_NAME:-scoreodonto}?schema=public
+      # DRAGONFLY_URL (com senha) vem do env_file backend/.env — não fica em texto no compose.
       - NATS_URL=nats://10.99.0.3:4222
       - TEMPORAL_ADDRESS=10.99.0.3:7233
       - BAILEYS_SESSIONS_PATH=/app/sessions

documentação/AUDITORIA-ESTRATEGICA-MODELAGEM.md

@@ -0,0 +1,157 @@
+# AUDITORIA ESTRATÉGICA DE MODELAGEM — ScoreOdonto
+
+> **Análise crítica da modelagem e da visão de negócio.** Não altera código, banco, documentação ou migrations.
+> Baseada exclusivamente em evidências reais: `backend/server.js`, schema real (tabelas), fluxos existentes e
+> `MAPA-FUNCIONAL-COMPLETO.md`. Estado verificado: produção `v1.0.18` · DEV `dev`. Data: 19/jun/2026.
+
+---
+
+## Evidências-âncora (o que o código realmente diz)
+
+| Camada | Evidência no código | Tabela/linha |
+|---|---|---|
+| **Identidade (Pessoa)** | `usuarios` é o ponto único de login; perfil multi-área (`usuario_areas`), capacidades por pessoa (`usuario_plugins`), `is_tutor` | `usuarios`, `me/areas`, `me/plugins` |
+| **Vínculo (join)** | `vinculos(usuario_id, clinica_id, role, setor_id, funcao_id)` + `CHECK role IN (paciente, dentista, biomedico, protetico, funcionario, donoclinica, donoconsultorio, donosala, admin)` | `server.js:4851` |
+| **Workspace** | `clinicas` ganhou `tipo ∈ {pessoal, consultorio, clinica}` + `owner_id`; comentário literal **"Clinicas → workspaces (Fase 1)"** | `server.js:4822-4824` |
+| **Workspace pessoal automático** | No registro, cria `clinicas(tipo='pessoal', owner_id=usuario)` — **toda pessoa nasce com um workspace** | `server.js:537,550` |
+| **Agregação** | `me/workspaces` → `listarWorkspaces(userId)` reúne clínicas (via vínculo) + salas | `server.js:5680` |
+| **Marketplace = pessoa** | `propostas_profissional.profissional_id` → `JOIN usuarios u` | `server.js:6307` |
+| **Legado clínica-cêntrico** | `pacientes` tem `clinica_id` e **não tem `usuario_id`**; `dentistas` é tabela à parte com `usuario_id` opcional; tudo passa por `tenantGuard`+`clinica_id` | `pacientes`, `dentistas:1542` |
+
+**Leitura imediata:** a *espinha de identidade e acesso* **já é** Pessoa → Vínculo → Workspace (e isso está em migração ativa, declarada como "Fase 1"). Os *dados clínicos/operacionais* **ainda são** Clínica → Pessoa. O sistema é **híbrido, com a direção já apontada pelo próprio código**.
+
+---
+
+## ANÁLISE 1 — Pessoa × Workspace
+
+1. **Centrado em clínica ou pessoa?** Híbrido. **Autenticação/autorização/workspaces:** centrado em **pessoa**. **Operação clínica e financeira:** centrado em **clínica** (`tenantGuard` + `clinica_id`).
+2. **A pessoa é entidade principal?** **Sim, há evidência forte:** `usuarios` é a âncora; áreas, plugins e tutor são da pessoa; o profissional do marketplace é a pessoa; e cada pessoa recebe um **workspace pessoal** ao se cadastrar.
+3. **A clínica é apenas um workspace?** **Sim, há evidência explícita:** `clinicas.tipo` pode ser `pessoal | consultorio | clinica`, com `owner_id`. A clínica é hoje **um tipo de workspace** dentro da própria tabela `clinicas` (que virou, de fato, a tabela de workspaces).
+4. **Módulos que favorecem Pessoa→Vínculo→Workspace:** login/identidade, `vinculos`+RBAC (`funcoes`/`setores`), `me/workspaces`, `usuario_plugins`, `usuario_areas`, Salas (workspace `tipo='sala'`), Marketplace de Profissionais, Tutoria.
+5. **Módulos que favorecem Clínica→Pessoa:** Pacientes, Dentistas (tabela-recurso), Agenda, Financeiro/Comissão/Repasse, Orçamentos/Contratos, Glosas — **toda a operação** ainda é escopada por `clinica_id`.
+6. **Mais sustentável em 5 anos:** **Pessoa → Vínculo → Workspace.** Justificativa técnica: a tabela `vinculos` é N:N (uma pessoa, vários workspaces, papéis distintos por workspace) — é o único modelo que comporta dentista em várias clínicas, locação de salas, tutoria e marketplace **sem duplicar a pessoa**. O modelo clínica-cêntrico exige duplicar o humano por clínica (é o que `dentistas` já faz, e é exatamente o gargalo).
+
+---
+
+## ANÁLISE 2 — Consultório
+
+**Hoje é simultaneamente (A) Papel e (C) Workspace:** existe a *role* `donoconsultorio` em `vinculos` **e** o `tipo='consultorio'` em `clinicas` (`server.js:590` decide o `tipoWs` a partir da role do dono).
+
+**Classificação ideal:** **(C) Workspace** — um `tipo` de workspace, sendo `donoconsultorio` apenas o *papel do dono* dentro dele. O sistema já está ~80% nesse modelo.
+
+**Impactos:** baixo do ponto de vista de dados (já existe `tipo='consultorio'`). O resíduo é **semântico**: a role codifica o tipo do workspace (acoplamento role↔tipo). Enquanto persistir, decisões de UI/permissão ramificam em dois lugares ("é consultório?" pode ser perguntado pela role *ou* pelo tipo), gerando divergência.
+
+---
+
+## ANÁLISE 3 — Protéticos
+
+**Hoje o protético é:** **Usuário/Profissional.** É `usuarios` com role `protetico` em `vinculos`, recebe workspace pessoal, e produz trabalho via `protese_os`/`protese_produtos`.
+
+**Existe conflito conceitual? Sim.** O protético-pessoa está modelado como **profissional do ecossistema**, mas o **laboratório** (onde o trabalho/custo realmente reside, `protese_laboratorios` + custo lab que abate comissão) é um **cadastro interno separado**. Ou seja, a faceta "fornecedor" está **descolada** da pessoa: a pessoa é profissional, o fornecedor é um cadastro à parte.
+
+**Modelo que faz mais sentido: (B) Protético = profissional do ecossistema** — e o **laboratório** é que ocupa o papel de *fornecedor*. Justificativa: o protético, como humano, se encaixa perfeitamente em Pessoa→Vínculo→Workspace (igual a dentista/biomédico); empurrá-lo para "fornecedor" o trataria como entidade não-humana e quebraria o login/marketplace/áreas que já funcionam para ele. A natureza "fornecimento" pertence ao **laboratório**, não ao indivíduo (ver Análise 4). (C) só seria verdade se um protético autônomo *fosse* o próprio laboratório — caso que o modelo atual não distingue.
+
+---
+
+## ANÁLISE 4 — Laboratórios
+
+**Hoje aparecem como:** **(A) Cadastro interno** — `protese_laboratorios` escopado por clínica, alimentando OS e custo lab. Não há identidade própria nem login; não cruzam clínicas.
+
+| Classificação | Vantagens | Desvantagens |
+|---|---|---|
+| **A) Cadastro auxiliar** (estado atual) | Simples; isolado por clínica; zero atrito | Cada clínica recadastra o mesmo laboratório; sem visão consolidada; sem relação direta com a pessoa protético |
+| **B) Participante do ecossistema** (entidade própria) | Laboratório único reaproveitável; liga custo lab à entidade real; base para reputação/histórico | Exige resolver identidade/duplicidade e governança de dados entre clínicas |
+| **C) Workspace independente** | Coerente com a linha Pessoa/Workspace; laboratório operaria como ator (recebe OS de várias clínicas) | Maior complexidade de tenancy; só se justifica se o laboratório for *operar dentro* da plataforma |
+
+**Análise (sem assumir locação):** hoje é **A**, e isso é consistente com o legado clínica-cêntrico. A tensão é que o laboratório é a **única entidade "fornecedor" real** do sistema e está modelada como simples lookup — o que limita qualquer evolução para histórico/qualidade/integração entre clínicas. **B** é o ponto de equilíbrio entre o estado atual e a direção arquitetural; **C** só se sustenta se o laboratório virar *operador* na plataforma.
+
+---
+
+## ANÁLISE 5 — Pacientes
+
+**Hoje o paciente pertence à CLÍNICA.** Evidências: `pacientes.clinica_id`, **ausência de `usuario_id`**, e até **dois variantes de INSERT** (um com `clinica_id`, outro sem — resíduo legado). Não há identidade de paciente no ecossistema; o mesmo CPF em duas clínicas vira **dois registros**.
+
+- **Compartilhamento entre clínicas:** inexistente (duplicação por clínica).
+- **Histórico:** preso à clínica; não há prontuário único da pessoa.
+- **Multiempresa:** o isolamento é forte (bom para tenancy), mas impede portabilidade.
+- **Privacidade/LGPD:** o modelo atual é, na verdade, **mais seguro por isolamento** (cada clínica é controladora dos seus dados). Um paciente "do ecossistema" exigiria base legal/consentimento para compartilhar histórico entre controladores distintos — não trivial.
+
+**Abordagem mais coerente com a arquitetura ATUAL:** **o paciente pertence à clínica.** É o que o código faz e o que o LGPD-por-isolamento favorece. **Porém** isso é a **maior contradição** com a direção Pessoa→Workspace: o paciente é a única "pessoa" do sistema que **não** é tratada como pessoa. É coerente com o presente e **incoerente com o futuro declarado**.
+
+---
+
+## ANÁLISE 6 — Marketplace
+
+| Módulo | Encaixa em | Evidência |
+|---|---|---|
+| Salas | **Modelo B** | workspace `tipo='sala'`, reservas cross-clínica |
+| Profissionais | **Modelo B** | `profissional_id` → `usuarios`; cruza clínicas |
+| Tutoria | **Modelo B** | candidatura/pagamento ligados à pessoa (`is_tutor`, MercadoPago) |
+| Próteses | **Modelo A** (hoje) | `protese_os` por `clinica_id` |
+| Laboratórios | **Modelo A** (hoje) | cadastro interno por clínica |
+
+**Conclusão:** o marketplace **só faz sentido no Modelo B (Pessoa→Vínculo→Workspace→Marketplace)**. Salas, Profissionais e Tutoria já estão lá porque dependem da **pessoa cruzando fronteiras de clínica** — algo que o Modelo A (Clínica→Tudo) torna impossível sem duplicação. Próteses/Laboratórios são os **retardatários** ainda presos ao Modelo A; são a fronteira onde os dois modelos colidem.
+
+---
+
+## ANÁLISE 7 — Escalabilidade (horizonte 5 anos)
+
+| Cenário | Suporta hoje? | Gargalo |
+|---|---|---|
+| Dentista em múltiplas clínicas | **Parcial** | `vinculos` suporta a identidade, mas `dentistas` **duplica a pessoa por clínica** (agenda/horários presos a `dentistas.id`); não há visão unificada do profissional |
+| Biomédico em vários locais | Parcial | mesma duplicação via tabela-recurso |
+| Profissionais temporários (Delivery) | **Não** | marketplace só tem proposta-mensagem; sem contrato/pagamento/vínculo temporário |
+| Locação de salas | **Sim (estrutura)** | falta captura de pagamento (fluxo financeiro aberto) |
+| Tutoria | **Sim** | escala de oferta de tutores |
+| Marketplace | Parcial | só Tutoria fatura |
+| Protéticos independentes | Parcial | pessoa ok, mas laboratório-fornecedor é cadastro preso à clínica |
+| Redes de clínicas | **Não** | **não existe entidade "rede/grupo" acima da clínica**; workspaces são planos, sem hierarquia |
+
+**O modelo escala?** A **camada de identidade sim**; a **camada operacional não**. Gargalos críticos: (1) **duplicação da pessoa** em `dentistas`/recursos; (2) **paciente não-portável**; (3) **ausência de hierarquia** (rede→clínica); (4) **tenancy de `clinica_id` único** impede consolidação cross-clínica (uma pessoa ver tudo o que é seu em todas as clínicas).
+
+---
+
+## ANÁLISE 8 — Contradições (por gravidade)
+
+| Gravidade | Contradição | Evidência |
+|---|---|---|
+| **ALTA** | `dentistas` é entidade paralela a `usuarios` (mesmo humano duplicado por clínica, com `usuario_id` *opcional*) → identidade fragmentada | `dentistas:1542`, `:328` |
+| **ALTA** | `pacientes` é entidade clínica-presa sem identidade de pessoa, com **dois INSERTs** (com/sem `clinica_id`) → ambiguidade legada + bloqueio de portabilidade | INSERTs de `pacientes` |
+| **MÉDIA** | O "workspace" está **dividido em duas tabelas**: `clinicas` (pessoal/consultorio/clinica) **e** `salas` — conceito único, dois lugares | `clinicas:4823`, `salas` |
+| **MÉDIA** | Acoplamento **role ↔ tipo de workspace** (`donoconsultorio`⇄`tipo='consultorio'`) | `server.js:590` |
+| **MÉDIA** | Estado de capacidades em **dois lugares**: `usuario_plugins` (servidor) vs `localStorage` (cliente) → divergência entre dispositivos | `pluginRegistry.ts`, `me/plugins` |
+| **BAIXA** | Protético-pessoa (profissional) × laboratório (fornecedor) descolados | `protese_laboratorios` |
+| **BAIXA** | `superadmin` fora de `vinculos` (é `usuarios.role`) → plano de auth separado (aceitável, mas assimétrico) | `me/workspaces:5682` |
+
+---
+
+## RESULTADO FINAL
+
+**1. Resumo executivo.** O ScoreOdonto é um ERP odontológico multiempresa em **transição arquitetural declarada no próprio código** ("Fase 1: Clinicas → workspaces"). A **identidade, o acesso e os workspaces já operam no modelo Pessoa→Vínculo→Workspace**; a **operação clínica/financeira permanece clínica-cêntrica**. As três frentes de marketplace já vivem no modelo novo; pacientes, dentistas-recurso e laboratórios são o legado que ainda não migrou. As contradições graves são todas de **identidade duplicada** (a mesma pessoa existindo como `usuarios` + `dentistas`, e o paciente sem identidade de pessoa).
+
+**2. Modelo que melhor representa o sistema HOJE:** **híbrido** — `Pessoa → Vínculo → Workspace` na espinha; `Clínica → Pacientes/Dentistas/Financeiro` na operação.
+
+**3. Modelo que melhor representa o sistema NO FUTURO:** `Pessoa → Vínculo → Workspace → Serviços → Marketplace → Financeiro` — e o código já está pavimentado para ele.
+
+**4. Entidades CORRETAMENTE classificadas:** `usuarios` (Pessoa), `vinculos` (Vínculo+RBAC), Clínica/Consultório/Sala como **workspaces**, Dentista/Biomédico/Protético/Tutor como **papéis da pessoa**, Profissional do marketplace e capacidades (`areas`/`plugins`) como atributos da pessoa.
+
+**5. Entidades MAL classificadas:**
+- **`dentistas`** — modelada como entidade própria; é, na verdade, uma **projeção da pessoa por workspace** (duplica o humano).
+- **`pacientes`** — entidade presa à clínica; é a única "pessoa" do sistema **não tratada como pessoa**.
+- **Laboratórios** — cadastro auxiliar; é o **único fornecedor real** e está subdimensionado.
+- **Consultório** — vive como role **e** tipo (redundância).
+
+**6. Riscos arquiteturais:** identidade fragmentada (dentistas); paciente não-portável e com resíduo de schema; conceito de workspace partido em duas tabelas; ausência de hierarquia "rede→clínica"; tenancy de `clinica_id` único barrando visão consolidada da pessoa; estado de plugins divergente cliente/servidor.
+
+**7. Oportunidades arquiteturais:** a "Fase 1" **já entregou o mais difícil** (identidade + vínculo + workspace + workspace pessoal automático). O ecossistema (marketplace, salas, tutoria) **só existe** porque essa base existe. Unificar as entidades-recurso (dentista) e a entidade-paciente sob a pessoa **destravaria de uma vez** multi-clínica, portabilidade de histórico, redes e o marketplace — sem reescrever o que já está certo.
+
+**8. Recomendação estratégica única:** **assumir e consolidar a PESSOA como âncora única do sistema, reconhecendo que a clínica já é — no código — apenas um tipo de workspace.** A decisão estratégica de fundo não é "se" migrar para Pessoa→Vínculo→Workspace (o sistema já escolheu isso na Fase 1), e sim **parar de manter o legado clínica-cêntrico em paralelo** nas duas entidades que ainda o sustentam (paciente e dentista-recurso) — pois é a coexistência dos dois modelos, não a escolha de um, que gera todas as contradições de gravidade ALTA.
+
+---
+
+> *Nota de método: tudo acima decorre de leitura de `backend/server.js`, do schema real (tabelas `usuarios`,
+> `vinculos`, `clinicas`, `pacientes`, `dentistas`, `salas`, `protese_*`, `propostas_profissional`) e do
+> `MAPA-FUNCIONAL-COMPLETO.md`. Onde o código tinha ambiguidade (ex.: dois INSERTs de `pacientes`, role↔tipo),
+> descreveu-se o fato observado, sem inferir intenção. Conforme solicitado, não há propostas de implementação,
+> migrations, código ou tarefas.*
+</content>

documentação/MAPA-FUNCIONAL-COMPLETO.md

@@ -0,0 +1,485 @@
+# MAPA FUNCIONAL COMPLETO — ScoreOdonto
+
+> **Auditoria funcional baseada SOMENTE em evidências do código.** Nada aqui foi assumido.
+> Fonte: `frontend/` (React 19 + Vite, roteador próprio em `App.tsx`) e `backend/server.js`
+> (Express monolítico, ~516 KB, **277 rotas**, ~70 tabelas Postgres acessadas por SQL direto).
+> Estado verificado: produção `v1.0.18` · DEV `dev` (banco isolado `pgdev`). Data: 19/jun/2026.
+
+---
+
+## Sumário executivo (o que o sistema É, na prática)
+
+O ScoreOdonto é um **ERP odontológico multiempresa** (SaaS) cujo núcleo é o ciclo
+**Lead → Paciente → Agenda → Procedimento → Financeiro → Comissão → Repasse**, com módulos
+clínicos (Ortodontia, Próteses/GTO, RX), administrativos (Equipe/RBAC, Planos, Procedimentos)
+e três frentes de marketplace (**Locação de Salas**, **Diretório/Propostas de Profissionais**,
+**Tutoria de Ortodontia** — esta última a única com cobrança automatizada via MercadoPago).
+
+A arquitetura é **multi-tenant real**: quase toda rota passa por `tenantGuard` e filtra por
+`clinica_id`. O "workspace" ativo (clínica **ou** sala) governa menu, permissões e dados visíveis.
+
+**Evidências estruturais:**
+- Frontend sem `react-router`: roteamento próprio (`ROUTE_MAP` / `VIEW_TO_ROUTE` em `App.tsx`).
+- 44 views (`frontend/views/*.tsx`), 16 componentes, 3 plugins.
+- Backend num único `server.js` (516 KB) — sem camada de serviços/controllers separada.
+- Prisma quase não usado (4 modelos legados de GTO); o banco real é SQL puro via `pg`.
+
+---
+
+# ETAPA 1 — INVENTÁRIO DE ROTAS
+
+Roteamento definido em `frontend/App.tsx` (`ROUTE_MAP`, `VIEW_TO_ROUTE`, `renderView`, `isViewAllowed`).
+**Papéis (roles):** `superadmin`, `admin`, `donoclinica`, `donoconsultorio`, `funcionario`,
+`dentista`, `biomedico`, `protetico`, `paciente`, `donosala`.
+**Tipos de workspace:** `clínica` (padrão) e `sala` (isola o contexto). **Plugins:** `rx-scoreodonto`,
+`locacao-salas` (sempre ON), `profissionais-marketplace`.
+
+| URL | View | Componente / Arquivo | Acesso (papéis) | Origem | Destino |
+|---|---|---|---|---|---|
+| `/` | landing | `LandingPage.tsx` | Público | — | login / área |
+| `/login` | login | `LoginView.tsx` | Público | landing | dashboard por papel |
+| `/contato` | public | `PublicContactForm.tsx` | Público | landing | cria interesse/lead |
+| `/dashboard` | dashboard | `Dashboard.tsx` | admin/donos/func/dentista/bio/prot | login, menu | agenda, pacientes |
+| `/leads` | leads | `LeadsView.tsx` | admin/donos/funcionário | menu | converter→paciente+agenda |
+| `/pacientes` | pacientes | `PatientsView.tsx` | admin/donos/funcionário | menu, dashboard | agenda, orçamento, procedimento, ortodontia, RX |
+| `/agenda` | agenda | `AgendaView.tsx` | quase todos os papéis clínicos | menu, dashboard | paciente, avaliação, procedimento |
+| `/ortodontia` | ortodontia | `OrthoView.tsx` | dentista (odonto) | menu, paciente | evolução, fotos, tutoria |
+| `/financeiro` | financeiro | `FinanceiroView.tsx` | admin/donos/funcionário | menu | comissão, glosa |
+| `/comissoes` | comissoes | `ComissoesView.tsx` | admin/donos | **menu apenas** ⚠️ | repasse |
+| `/glosas` | glosas | `GlosasView.tsx` | admin/donos/funcionário | **menu apenas** ⚠️ | recebíveis convênio |
+| `/proteses` | proteses | `ProteseView.tsx` | dentista/protético/func | menu | OS de laboratório, GTO |
+| `/orcamentos` | orcamentos | `OrcamentosView.tsx` | admin/donos/funcionário | menu, paciente | contrato |
+| `/contratos` | contratos | `ContratosView.tsx` | admin/donos/funcionário | menu, orçamento | cobrança/financeiro |
+| `/relatorios` | relatorios | `ReportsView.tsx` | admin/donos/funcionário | menu | — |
+| `/tratamentos` | tratamentos | `MeusTratamentos.tsx` | paciente + clínicos | menu | — |
+| `/lancar-gto` | lancar-gto | `LancarGTO.tsx` | biomédico/protético/func | menu | guias odontológicas |
+| `/notificacoes` | notificacoes | `NotificationsView.tsx` | todos | menu | — |
+| `/clinicas` | clinicas | `ClinicasView.tsx` | membros | menu, seletor de workspace | criar-clinica |
+| `/gestao-equipe` | gestao-equipe | `GestaoEquipeView.tsx` | admin/donos | menu | membros, cargos (RBAC) |
+| `/admin/dentistas` | dentistas | `AdminViews.tsx` | admin/donos | menu | horários |
+| `/admin/especialidades` | especialidades | `AdminViews.tsx` | admin/donos/biomédico | menu | procedimentos |
+| `/admin/procedimentos` | procedimentos | `AdminViews.tsx` | admin/donos/biomédico | menu | valores por plano |
+| `/admin/planos` | planos | `AdminViews.tsx` | admin/donos | menu | — |
+| `/admin/sync` | sync | `AdminViews.tsx` (`SyncView`) | **NINGUÉM (bloqueado)** ⚠️ | — | — |
+| `/plugins` | plugins | `PluginsView.tsx` | **superadmin apenas** | menu (superadmin) | ativa plugins |
+| `/rx-radiografias` | rx-radiografias | `plugins/RXPlugin.tsx` | dentista/donos/func (plugin RX) | menu | dispositivos RX |
+| `/rx-config` | rx-config | `RxConfigView.tsx` | admin/donos/superadmin | menu | dispositivos RX |
+| `/salas` `/minhas-salas` `/alugar-salas` | salas | `plugins/SalasPlugin.tsx` | todos (plugin `locacao-salas`, sempre ON) | menu | reservas |
+| `/sala-home` | sala-home | `SalaHomeView.tsx` | workspace tipo `sala` | seletor de workspace | reservas da sala |
+| `/marketplace-profissionais` | marketplace-profissionais | `plugins/ProfissionaisPlugin.tsx` | clínicos exceto paciente (plugin) | menu | propostas |
+| `/diretorio-profissionais` | diretorio-profissionais | `DiretorioProfissionaisView.tsx` (absorvido pelo plugin) | clínicos | menu | — |
+| `/candidatura-tutor` | candidatura-tutor | `TutorCandidaturaView.tsx` | dentista | menu | pagamento MercadoPago |
+| `/tutoria-painel` | tutoria-painel | `TutorPainelView.tsx` | **tutores aprovados** (`is_tutor`) | menu | solicitações |
+| `/admin-gestao-tutores` | admin-gestao-tutores | `AdminGestaoTutoresView.tsx` | **superadmin** | menu | confirma pagamentos/repasses |
+| `/criar-clinica` | criar-clinica | `CreateClinicView.tsx` | admin/donos sem workspace | pós-cadastro | dashboard |
+| `/cadastro-dentista` | cadastro-dentista | `DentistRegisterView.tsx` | standalone (magic-link) | **menu apenas** ⚠️ | aguardando-convite |
+| `/aguardando-convite` | aguardando-convite | `WaitingInviteView.tsx` | dentista/bio/prot sem vínculo | pós-cadastro | — |
+| `/superadmin/*` | superadmin-* | `SuperAdminView.tsx` (tabs) | **superadmin** | menu | usuários, clínicas, logs, financeiro, notificações |
+| `/update` | update | `UpdateDbView.tsx` | técnica (URL direta, sempre liberada) | **fora do menu** | migração de banco |
+
+**⚠️ Inconsistências de roteamento encontradas (evidência: `ROUTE_MAP` vs `VIEW_TO_ROUTE` em `App.tsx`):**
+- `/comissoes`, `/glosas` e `/cadastro-dentista` **existem em `VIEW_TO_ROUTE`** (a navegação por menu empurra a URL),
+  mas **NÃO existem em `ROUTE_MAP`**. Consequência: abrir essas URLs direto (deep-link / refresh) cai em `dashboard`.
+  **Deep-link quebrado** para 3 telas reais.
+- `/admin/sync` está mapeada, mas `isViewAllowed` retorna `false` **sempre** (substituída por "backup por clínica").
+  A tela e a rota existem, porém são **inacessíveis** (código morto navegável).
+
+---
+
+# ETAPA 2 — INVENTÁRIO DE TELAS
+
+(Resumo por tela — objetivo / usuário-alvo / valor / dependências / impacto. Apenas telas reais.)
+
+### Dashboard
+- **Objetivo:** visão consolidada (KPIs via `GET /api/dashboard/stats`). **Usuário:** gestores/clínicos.
+- **Valor:** ponto de entrada operacional. **Depende de:** agenda, pacientes, financeiro. **Impacta:** navegação.
+
+### Leads / Gestão de Leads
+- **Objetivo:** captar e **converter** interessados em pacientes. **Usuário:** funcionário/donos.
+- **Valor:** topo do funil comercial. **Depende de:** `interesses`/contato público. **Impacta:** Pacientes + Agenda
+  (a conversão cria ambos — `POST /api/leads/:id/converter`).
+
+### Pacientes
+- **Objetivo:** prontuário e cadastro (dados, família, score, faltas). **Usuário:** funcionário/donos.
+- **Valor:** entidade central do negócio. **Depende de:** clínica ativa. **Impacta:** Agenda, Orçamento,
+  Procedimento realizado, Ortodontia, RX, Receita/Exame. É o hub clínico (view de 92 KB).
+
+### Agenda
+- **Objetivo:** agendar/confirmar/remarcar; controle de presença e anti-overbooking. **Usuário:** todos clínicos.
+- **Valor:** coração operacional. **Depende de:** Pacientes, Dentistas+horários. **Impacta:** Avaliação,
+  Procedimento, Financeiro (presença libera lançamento).
+
+### Ortodontia
+- **Objetivo:** tratamento orto completo (triagem, diagnóstico, plano, evoluções, fotos, contenção). **Usuário:** dentista.
+- **Valor:** vertical clínica de alto valor recorrente. **Depende de:** Paciente. **Impacta:** Tutoria, fotos.
+
+### Próteses / GTO
+- **Objetivo:** OS de laboratório (`protese_os`), produtos, custo lab, entrega. **Usuário:** protético/dentista.
+- **Valor:** controle do laboratório e do custo que abate comissão. **Depende de:** Procedimentos, Laboratórios.
+  **Impacta:** Comissão (custo lab entra no cálculo).
+
+### Financeiro
+- **Objetivo:** contas a receber/pagar (`financeiro`: RECEITA/DESPESA), formas, centro de custo, fornecedor. **Usuário:** gestores.
+- **Valor:** caixa da clínica. **Depende de:** Procedimentos realizados, Contratos, Repasses. **Impacta:** Comissão, Glosa.
+
+### Comissões
+- **Objetivo:** definir % (padrão da clínica, por procedimento, override por profissional) e ver produção/comissão.
+- **Usuário:** donos. **Depende de:** Procedimentos realizados + Próteses (custo lab). **Impacta:** Repasses.
+
+### Glosas
+- **Objetivo:** registrar glosa sobre recebíveis (convênio), recorrer, recuperar. **Usuário:** gestores.
+- **Valor:** recupera receita negada por convênio. **Depende de:** Financeiro (recebíveis). **Impacta:** caixa.
+
+### Orçamentos → Contratos
+- **Objetivo:** propor tratamento (itens/valores) e formalizar em contrato (modelos com variáveis, assinatura, cobrança).
+- **Usuário:** funcionário/donos. **Depende de:** Paciente, Procedimentos. **Impacta:** Financeiro (`gerar-cobranca`).
+
+### Equipe / Usuários (RBAC)
+- **Objetivo:** membros, cargos (`funcoes`), setores e permissões por workspace. **Usuário:** donos.
+- **Valor:** governa quem vê o quê. **Impacta:** menu e `isViewAllowed` de todos os membros.
+
+### Salas (Locação) / Painel da Sala
+- **Objetivo:** cadastrar salas, publicar no marketplace, receber/aceitar reservas. **Usuário:** qualquer conta.
+- **Valor:** receita de locação P2P. **Depende de:** conta/sala. **Impacta:** `sala_reservas`.
+
+### Marketplace de Profissionais / Diretório
+- **Objetivo:** profissional publica perfil; clínica envia proposta (`propostas_profissional`). **Usuário:** clínicas e profissionais.
+- **Valor:** conexão oferta/demanda de mão de obra. **Impacta:** mensagens/propostas (sem cobrança hoje).
+
+### Tutoria de Ortodontia (Candidatura / Painel / Gestão)
+- **Objetivo:** dentista vira tutor (pagando inscrição via MercadoPago); resolve solicitações orto.
+- **Usuário:** dentistas + superadmin (gestão). **Valor:** **única receita de plataforma automatizada**.
+
+### SuperAdmin (overview/users/clínicas/logs/financeiro/notificações)
+- **Objetivo:** administração global da plataforma (preços/assinaturas, broadcast, auditoria de acesso).
+- **Usuário:** superadmin. **Valor:** operação do SaaS.
+
+### Configurações / Notificações / Minhas Clínicas
+- Conta, integrações (Google), backup por clínica; notificações; seletor/gestão de workspaces.
+
+---
+
+# ETAPA 3 — INVENTÁRIO DE BOTÕES (telas transacionais)
+
+Rótulos extraídos das views; ações mapeadas para as rotas/tabelas do backend.
+
+### Agenda (`AgendaView.tsx`)
+- **Novo Agendamento** → `POST /api/agendamentos` → tabela `agendamentos`. Fluxo: Paciente ↓ Procedimento ↓ Financeiro.
+- **Confirmar / Confirmar Presença** → `POST /api/agendamentos/:id/confirmar` + `/api/agenda/presenca` → `agendamentos`, `agenda_presenca`. **Libera lançamento financeiro.**
+- **Reagendar / Remarcar** → `POST /api/agendamentos/:id/remarcar` → `agendamentos`.
+- **Registrar Falta** → `POST /api/agendamentos/:id/falta` → `agendamentos` (impacta score do paciente).
+- **Solicitar Avaliação** → `POST /api/agendamentos/:id/solicitar-avaliacao` → `avaliacoes`.
+
+### Pacientes (`PatientsView.tsx`)
+- **Editar/Cadastrar Paciente** → `POST|PUT /api/pacientes` → `pacientes`.
+- **Agendar** → abre fluxo da Agenda. **Lançar Procedimento** (`LancarProcedimentoModal`) → `POST /api/procedimentos-realizados` → `procedimentos_realizados` (+ gera `financeiro`).
+- **Orçamento** (`OrcamentoModal`) → `orcamentos`. **Receita** (`ReceitaModal`) → `modelos_receita`/`items_receita`. **Pedido de Exame** (`PedidoExameModal`) → `pedidos_exame`.
+
+### Financeiro (`FinanceiroView.tsx`)
+- **Novo lançamento** (RECEITA/DESPESA, forma, vencimento, centro de custo, fornecedor) → `POST /api/financeiro` → `financeiro`.
+- **Marcar Pago / Alterar / Excluir** → `PUT|DELETE /api/financeiro/:id` → `financeiro`.
+
+### Comissões (`ComissoesView.tsx`)
+- **Salvar % padrão / por procedimento / override por profissional** → `PUT /api/comissoes/regras` → `comissao_regras`.
+- **Base de cálculo** (produção × recebido) e **Custo lab** abatido. Próximo fluxo: **Fechar repasse**.
+
+### Repasses (em Financeiro/Comissões)
+- **Fechar Repasse** → `POST /api/repasses/fechar` → `repasses` (status `fechado`).
+- **Pagar** → `POST /api/repasses/:id/pagar` → cria DESPESA em `financeiro` (origem `repasse`, centro de custo `COMISSÕES`).
+- **Anexar Comprovante** → `POST /api/repasses/:id/comprovante`. **Cancelar** → estorna a despesa.
+
+### Glosas (`GlosasView.tsx`)
+- **Registrar Glosa** (total/livre, motivo, valor) → `POST /api/glosas` → `glosas`.
+- **Recorrer** → `POST /api/glosas/:id/recorrer`. **Recuperar** → `POST /api/glosas/:id/recuperar`.
+
+### Orçamentos / Contratos
+- **Novo Orçamento** (itens, valor, entrada, parcelas) → `POST /api/orcamentos` → `orcamentos`/`orcamento_itens`.
+- **Gerar Contrato** (modelo + variáveis + prévia) → `POST /api/contratos/instancias` → `contratos`.
+- **Enviar / Assinar / Gerar Cobrança / Cancelar** → `POST /api/contratos/instancias/:id/{enviar,assinar,gerar-cobranca,cancelar}` → liga ao `financeiro`.
+
+### Próteses (`ProteseView.tsx`)
+- **Nova OS** (produto, dentes, material, custo lab, preço, prazo) → `POST /api/protese/os` → `protese_os`.
+- **Marcar Entregue / Mudar Status** → `POST /api/protese/os/:id/status` → `protese_os_evento`.
+
+### Leads (`LeadsView.tsx`)
+- **Cadastrar Lead** → `POST /api/leads` → `leads`.
+- **Cadastrar o Paciente / Converter** (com data, hora, dentista) → `POST /api/leads/:id/converter` → cria `pacientes` **+** `agendamentos` (anti-overbooking).
+
+---
+
+# ETAPA 4 — FLUXOS DE NEGÓCIO
+
+## Fluxo principal (núcleo do produto) — COMPLETO
+
+```
+Lead/Interesse ──converter──▶ Paciente ──▶ Agenda ──confirmar/presença──▶ Atendimento
+   (leads)                   (pacientes)  (agendamentos)                      │
+                                                                              ▼
+                                                            Procedimento Realizado
+                                                            (procedimentos_realizados)
+                                                                              │ valor>0
+                                                                              ▼
+                                                   Financeiro RECEITA (origem='procedimento')
+                                                            (financeiro, flag sem_comissao)
+                                                                              │
+                                          computeComissoes = (base − custo_lab) × %
+                                                                              ▼
+                                              Repasse FECHADO (repasses) ──pagar──▶
+                                              Financeiro DESPESA (origem='repasse',
+                                                       centro_custo='COMISSÕES')
+```
+
+- **Onde começa:** Lead/Interesse (ou cadastro direto de Paciente).
+- **Onde termina:** pagamento do repasse ao profissional (DESPESA conciliada no caixa) — ciclo fechado.
+- **Onde quebra / desvio:**
+  - **Geração de RECEITA é opcional** (`gerarLancamento !== false` e `valor>0`): um procedimento sem valor
+    **não** entra no financeiro — possível receita não registrada (depende do operador).
+  - **Glosa** é um ramo paralelo sobre recebíveis de convênio (recupera receita), não integrado ao repasse.
+  - **Garantia/Reabertura** marcam `sem_comissao` (regra: garantia sempre; reabertura só se mesmo profissional)
+    — corretamente excluídas do repasse.
+- **Duplicidade:** não há dupla geração de comissão — o repasse pago entra como DESPESA com `sem_comissao=true`
+  (evita recomissionar). Bom controle.
+
+## Fluxo comercial paralelo
+
+```
+Orçamento (orcamentos) ──▶ Contrato (contratos) ──gerar-cobranca──▶ Financeiro (a receber)
+```
+
+## Fluxos de marketplace (ver Etapas 7 e 8)
+
+```
+Sala (salas) ──publica──▶ Marketplace ──reserva──▶ sala_reservas (valor, status) [pagamento MANUAL]
+Profissional ──perfil──▶ Diretório ──proposta──▶ propostas_profissional (mensagem) [sem cobrança]
+Dentista ──candidatura──▶ MercadoPago (pago) ──webhook──▶ Tutor ativo ──▶ Solicitações de tutoria
+```
+
+---
+
+# ETAPA 5 — MATRIZ DE MÓDULOS
+
+| Módulo | Existe? | Acessível? | Funcional? | Completo? | Em uso? | Classificação |
+|---|---|---|---|---|---|---|
+| Autenticação / Workspaces / RBAC | Sim | Sim | Sim | Sim | Sim | **Maduro** |
+| Pacientes | Sim | Sim | Sim | Sim | Sim | **Maduro** |
+| Agenda (+presença/anti-overbooking) | Sim | Sim | Sim | Sim | Sim | **Maduro** |
+| Financeiro (receita/despesa) | Sim | Sim | Sim | Sim | Sim | **Maduro** |
+| Comissão + Repasse | Sim | Sim | Sim | Sim | Sim | **Operacional** |
+| Glosas | Sim | menu apenas (deep-link quebrado) | Sim | Parcial | Sim | **Operacional** |
+| Orçamentos → Contratos | Sim | Sim | Sim | Sim | Sim | **Operacional** |
+| Ortodontia | Sim | Sim | Sim | Sim | Sim | **Maduro** |
+| Próteses / GTO | Sim | Sim | Sim | Parcial | Sim | **Operacional** |
+| Leads | Sim | Sim | Sim | Sim | Sim | **Operacional** |
+| Plano/Procedimentos/Especialidades | Sim | Sim | Sim | Sim | Sim | **Operacional** |
+| RX / Radiografias (plugin) | Sim | por plugin/papel | Sim | Parcial | depende clínica | **Parcial** |
+| Locação de Salas (marketplace) | Sim | Sim (sempre ON) | Sim | Parcial (sem gateway) | baixo | **Parcial** |
+| Marketplace Profissionais | Sim | por plugin | Sim | Parcial (só mensagem) | baixo | **MVP** |
+| Tutoria de Ortodontia (MercadoPago) | Sim | Sim | Sim | Sim | baixo | **Operacional** |
+| SuperAdmin | Sim | superadmin | Sim | Sim | Sim | **Operacional** |
+| Sync Google/legado (global) | Sim | **bloqueado** | parcial | — | **não** | **Abandonado** |
+| Relatórios | Sim | Sim | Sim | Parcial | Sim | **Parcial** |
+
+---
+
+# ETAPA 6 — MULTIEMPRESA
+
+**Evidência:** quase todas as 277 rotas usam `tenantGuard` e filtram por `req.clinicaId`/`clinica_id`.
+O workspace ativo é resolvido por `GET /api/me/workspaces` (tabela `vinculos` = usuário↔clínica) + salas próprias.
+
+| Entidade | Como é modelada | Multiempresa respeitado? |
+|---|---|---|
+| Workspaces | `vinculos` (clínica) + `salas` (tipo `sala`); seletor no Sidebar | ✅ Sim |
+| Clínicas | `clinicas` + `clinica_id` em todas as tabelas operacionais | ✅ Sim |
+| Consultórios | papel `donoconsultorio` (variação de dono, mesmo modelo de clínica) | ✅ Sim |
+| Dentistas / Biomédicos / Protéticos | papéis distintos com menus próprios; vínculo por clínica | ✅ Sim |
+| Salas | `salas` + workspace `tipo='sala'` **isola** o contexto (menu reduzido) | ✅ Sim |
+| Laboratórios | `protese_laboratorios` por clínica | ✅ Sim |
+
+- **Acoplamento indevido:** **não** encontrado acoplamento a "clínica única" — o `clinica_id` é onipresente.
+- **Ponto de atenção:** o contexto é **cacheado no `localStorage`** (`SCOREODONTO_USER_DATA`, plugins) e
+  reconciliado via `hydrateMyPlugins()`. Plugins ativos vivem em `localStorage` (cliente), não só no servidor —
+  risco de divergência entre dispositivos (mitigado por `me/plugins`, mas é o elo mais frágil do multiempresa).
+- O **marketplace de salas é cross-tenant** por desenho (uma clínica aluga sala de outra) — acoplamento *intencional*.
+
+**Veredito:** conceito multiempresa **bem respeitado** no backend; a fragilidade é o estado de UI/plugins no cliente.
+
+---
+
+# ETAPA 7 — MARKETPLACE
+
+```
+Salas (salas) ─┬─ Locação (sala_reservas: valor, modelo, status pendente/aceita)
+               └─ Profissionais (perfil) ─ Propostas (propostas_profissional: mensagem)
+                                         └─ Protéticos/Laboratórios (protese_*)
+```
+
+| Frente | O que existe hoje | O que falta | Gera receita? | Pode gerar |
+|---|---|---|---|---|
+| **Locação de salas** | CRUD de salas, publicação no marketplace, reserva com `valor` e workflow de status (`pendente`→`aceita`), painel da sala | **Gateway de pagamento** e taxa da plataforma (hoje o `valor` é registrado, mas o pagamento é **manual/externo**) | **Não diretamente** | **Sim** — comissão sobre locação |
+| **Profissionais** | Perfil público + envio de proposta (mensagem) clínica→profissional | Negociação, contrato, e qualquer cobrança | **Não** | Sim — taxa de match/assinatura premium |
+| **Protéticos / Laboratórios** | OS, produtos, custo lab integrados ao financeiro/comissão | Marketplace aberto de laboratórios (hoje é interno por clínica) | Indireto (operacional) | Sim — rede de laboratórios |
+| **Tutoria de Ortodontia** | Candidatura **paga via MercadoPago** (`preferences` + `mp-webhook`), `comissao_pct`, solicitações/mensagens | Escala (oferta de tutores), avaliação | ✅ **Sim (a única automatizada)** | Já gera |
+
+**Conclusão:** a infraestrutura de marketplace existe, mas **só a Tutoria tem captura de pagamento real**.
+Salas é a frente mais próxima de monetizar (já tem `valor` e reservas) — falta o gateway + a taxa.
+
+---
+
+# ETAPA 8 — FINANCEIRO
+
+```
+ORIGEM DO DINHEIRO                  →  DESTINO                       →  RESPONSÁVEL
+Procedimento realizado (RECEITA)   →  financeiro (a receber)        →  Clínica
+Contrato (gerar-cobranca)          →  financeiro (a receber)        →  Clínica
+Convênio (recebíveis) − Glosa      →  financeiro / recupera         →  Clínica
+Comissão (base − custo lab × %)    →  repasses (fechado)            →  Profissional
+Repasse pago                       →  financeiro DESPESA (COMISSÕES) →  Clínica paga Profissional
+Locação de sala (valor reserva)    →  sala_reservas (status)        →  Locador  [pagamento manual]
+Tutoria (inscrição)                →  MercadoPago → ativa tutor     →  Plataforma (comissao_pct)
+```
+
+| Item | Tabela | Estado |
+|---|---|---|
+| Orçamentos | `orcamentos`/`orcamento_itens` | ✅ completo |
+| Contratos | `contratos`/`contrato_*` | ✅ completo (modelos, variáveis, assinatura, cobrança) |
+| Convênios/Planos | `planos`, `procedimentos_valores_planos` | ✅ |
+| Produção | `procedimentos_realizados` → `financeiro` | ✅ (RECEITA opcional por valor) |
+| Comissão | `comissao_regras` + `computeComissoes` | ✅ (3 níveis de regra; abate custo lab) |
+| Repasse | `repasses` (fechar/pagar/cancelar/comprovante) | ✅ ciclo fechado, com estorno |
+| Glosas | `glosas` (recorrer/recuperar) | ✅ funcional, isolado do repasse |
+| Locação | `sala_reservas.valor` | ⚠️ registra valor, **sem captura de pagamento** |
+
+**Pontos fortes:** rastreabilidade (cada DESPESA de repasse referencia o período/profissional; `audit_log` em tudo),
+e não-duplicação de comissão (`sem_comissao` propagado). **Lacuna:** receita de procedimento depende de ação manual.
+
+---
+
+# ETAPA 9 — MAPA DE CONEXÕES (Mermaid)
+
+```mermaid
+flowchart TD
+  U[Usuário] --> WS{Workspace ativo}
+  WS -->|clínica| CL[Clínica / RBAC]
+  WS -->|sala| SH[Painel da Sala]
+
+  CL --> LEAD[Leads]
+  LEAD -->|converter| PAC[Pacientes]
+  PAC --> AG[Agenda]
+  AG --> AV[Avaliação]
+  AG --> PR[Procedimento Realizado]
+  PAC --> ORTO[Ortodontia]
+  PAC --> RX[RX / Radiografias]
+  PAC --> ORC[Orçamento]
+  ORC --> CON[Contrato]
+  CON -->|gerar-cobranca| FIN[Financeiro]
+  PR -->|RECEITA| FIN
+  PR --> COM[Comissão]
+  PROT[Próteses / Custo Lab] --> COM
+  COM --> REP[Repasse]
+  REP -->|pagar DESPESA| FIN
+  FIN --> GLO[Glosas]
+  FIN --> REL[Relatórios]
+
+  SH --> RES[Reservas de Sala]
+  CL --> SAL[Salas Marketplace]
+  SAL --> RES
+  CL --> MKP[Marketplace Profissionais]
+  MKP --> PROP[Propostas]
+  ORTO --> TUT[Tutoria Orto]
+  TUT -->|MercadoPago| MP[(Pagamento)]
+
+  SUPER[SuperAdmin] --> CL
+  SUPER --> PLUG[Plugins]
+```
+
+```mermaid
+flowchart LR
+  subgraph Núcleo financeiro
+    PR[procedimentos_realizados] --> FINr[financeiro RECEITA]
+    FINr --> CR[comissao_regras]
+    CR --> RP[repasses]
+    RP --> FINd[financeiro DESPESA]
+    FINr --> GL[glosas]
+  end
+```
+
+---
+
+# ETAPA 10 — OPORTUNIDADES
+
+## Funcionalidades órfãs (existem no código, ninguém usa)
+- **`views/OrthoReports.tsx`** — não é roteada em `App.tsx` **nem** importada por nenhuma view. Órfã real
+  (importa `OrthoPhotoWorkspace`, mas nada importa `OrthoReports`). Relatórios de ortodontia prontos e desligados.
+- **`SyncView` (`/admin/sync`)** — tela e rota existem, mas `isViewAllowed` retorna `false` sempre. Código morto navegável.
+
+## Funcionalidades escondidas (existem mas não aparecem no menu)
+- **`/update` (`UpdateDbView`)** — migração de banco; acessível por URL direta, fora do menu (ferramenta técnica).
+- **`/cadastro-dentista`** — só alcançável por fluxo/magic-link; sem entrada no menu e com deep-link quebrado.
+- **Comissões deep-link** — visível no menu (admin/donos) mas `/comissoes` direto cai em dashboard.
+
+## Funcionalidades incompletas (começam mas não terminam o fluxo)
+- **Locação de salas** — reserva com `valor` e status, mas **sem captura de pagamento** (fluxo financeiro não fecha).
+- **Marketplace de profissionais** — proposta é só mensagem; **não** evolui para contratação/cobrança.
+- **RECEITA de procedimento opcional** — pode não gerar lançamento (receita potencialmente não registrada).
+- **Glosas isoladas** — recuperam receita, mas não reconciliam com o repasse correspondente.
+
+## Funcionalidades de alto potencial (podem gerar receita)
+1. **Gateway na Locação de Salas** (já existe `valor`+reserva): cobrança + taxa da plataforma → receita recorrente.
+2. **Assinatura/planos da plataforma** (`superadmin/pricing`, `assinaturas` já existem): monetizar o SaaS por clínica.
+3. **Marketplace de Profissionais premium**: taxa de match / destaque de perfil.
+4. **Tutoria de Ortodontia em escala** (único pago hoje): aumentar oferta de tutores e volume.
+
+---
+
+# RESULTADO FINAL
+
+## Notas (0–100) — com base nas evidências
+
+| Eixo | Nota | Justificativa (evidência) |
+|---|---:|---|
+| **Arquitetura funcional** | 72 | Roteamento+RBAC robustos, mas `server.js` monolítico (516 KB), roteador próprio e 3 deep-links quebrados. |
+| **Integração dos módulos** | 78 | Cadeia Lead→…→Repasse bem costurada, com auditoria e não-duplicação de comissão. |
+| **Fluxos de negócio** | 70 | Núcleo clínico+financeiro completo; ramos de marketplace incompletos; receita às vezes manual. |
+| **Multiempresa** | 82 | `tenantGuard`+`clinica_id` onipresentes; isolamento de sala; fragilidade no estado de plugins no cliente. |
+| **Marketplace** | 45 | Infra existe; só Tutoria captura pagamento; Salas e Profissionais sem fechar fluxo financeiro. |
+| **Financeiro** | 80 | Receita/despesa, comissão (3 níveis), repasse com estorno, glosas, contratos com cobrança. |
+| **Experiência do usuário** | 70 | Menus por papel, nav mobile, "visualizar como"; prejudicada por deep-links quebrados e estado em localStorage. |
+| **Potencial de monetização** | 65 | Tutoria já fatura; Salas e Assinatura SaaS são alavancas prontas e subutilizadas. |
+
+## 1. O que remover
+- `views/OrthoReports.tsx` (órfã) — ou religar ao menu de Ortodontia se desejado.
+- `SyncView` / rota `/admin/sync` e telas de sync global desativadas (já substituídas por backup por clínica).
+- `server.js.bak` e scripts de transformação legados (`transform.js`, `pg-convert.js`) do diretório de produção.
+
+## 2. O que corrigir
+- **Adicionar `/comissoes`, `/glosas`, `/cadastro-dentista` ao `ROUTE_MAP`** (deep-link/refresh quebrado).
+- Reconciliação de **plugins ativos**: tratar o servidor como fonte da verdade (reduzir dependência de `localStorage`).
+- Tornar a **geração de RECEITA do procedimento** o padrão claro (evitar receita não registrada).
+
+## 3. O que finalizar
+- **Locação de Salas**: captura de pagamento + taxa da plataforma (fecha o fluxo financeiro do marketplace).
+- **Marketplace de Profissionais**: evoluir proposta → contratação → cobrança.
+- **Relatórios**: consolidar (há `reports/productivity` + telas parciais).
+
+## 4. O que priorizar
+1. Corrigir deep-links e estado de plugins (baixo esforço, destrava UX e confiabilidade).
+2. Gateway de pagamento na Locação de Salas (alavanca de receita mais próxima).
+3. Cobrança por assinatura da plataforma (`superadmin/pricing`+`assinaturas` já existem).
+
+## 5. O que gera receita mais rapidamente
+- **Locação de Salas com pagamento** — o `valor` e o fluxo de reserva já existem; falta só a captura + taxa.
+- **Assinatura SaaS por clínica** — a base multiempresa e o `pricing` já estão prontos no superadmin.
+
+## 6. Próximo módulo mais estratégico
+- **Monetização da plataforma (Billing/Assinaturas + taxa de marketplace de salas).** É o que converte uma base
+  técnica madura (ERP odontológico multiempresa funcional) em **receita recorrente da plataforma** — hoje só a
+  Tutoria cobra. Tudo o mais já está construído; falta o módulo que **fatura**.
+
+---
+
+> **Nota de método:** este mapa reflete exclusivamente o que foi encontrado no código em 19/jun/2026
+> (`frontend/App.tsx`, `frontend/views/*`, `frontend/components/Sidebar.tsx`, `backend/server.js`).
+> Onde havia ambiguidade (ex.: receita opcional, pagamento manual de salas), o fato foi descrito como está,
+> sem inferir intenção. Nenhuma funcionalidade foi inventada.
+</content>
+</invoke>

documentação/STATUS-SEGURANCA-E-PRODUCAO.md

@@ -0,0 +1,129 @@
+# Status — Segurança & Produção (ScoreOdonto)
+
+> Resumo do que foi feito e do que falta. Atualizado em **22/jun/2026**.
+> Produção no ar: **v1.0.19** (`715b2dc`) — fila **A** concluída (push → CI → tag → deploy). **Commits
+> publicados (`git push` feito).** A rotação do `JWT_SECRET` segue aplicada e verificada em produção.
+
+---
+
+## ✅ O QUE JÁ FOI FEITO
+
+### 1. Segredos
+- **`JWT_SECRET` rotacionado em DEV e PRODUÇÃO** (recriado o backend na VPS1 na mesma tag, sem rebuild;
+  `/api/health` e `/api/version` validados). → **vetor de tomada de conta FECHADO** (o segredo vazado não
+  forja mais tokens). **Ação operacional na VPS1 — sem commit** (o segredo não é versionado).
+- **`backend/.env` fora do tracking do git** + `backend/.dockerignore` (o Dockerfile fazia `COPY . .` sem
+  `.dockerignore` → segredos iam para dentro da imagem) + `.env.example`. Commits `fcf2fb1`.
+- **Senhas hardcoded removidas do `docker-compose.yml`**: banco via `SCOREO_DB_PASS` (com `:?` fail-fast);
+  `DRAGONFLY_URL` (com senha) movido para `env_file`. Commit `3aa6a44`. Validado em DEV (pgdev/cache ok).
+
+### 2. Frontend
+- **`/update` (migração de banco) restrito a superadmin** (era acessível a qualquer um, até deslogado).
+- **Deep-links corrigidos** (`/comissoes`, `/glosas` faltavam no `ROUTE_MAP` → caíam em dashboard).
+- Commit `1559387`. (Build compila; validação visual de RBAC precisa de navegador.)
+
+### 3. RBAC intra-clínica no backend (99 rotas) — **NÚCLEO FECHADO**
+Antes: qualquer membro autenticado (até paciente) podia chamar ações privilegiadas direto na API
+(a UI escondia, o backend não barrava). Agora há autorização por **cargo**, espelhando o `isViewAllowed`
+do frontend, via 3 helpers: `requireCapability`, `requireCapabilityRow`, `requireCapabilityFromOrders`.
+
+| Grupo | Commit |
+|---|---|
+| Financeiro (comissões/repasses/financeiro/glosas) | `f4e7fe3` |
+| Gestão de equipe/clínica (membros/setores/funções/reset-senha/cor) | `9ad65c3` |
+| Cadastros administrativos (dentistas/especialidades/procedimentos/planos + reorder) | `116200c` + `0667456` |
+| Operação clínica (pacientes/agenda/leads) | `5b58a8a` |
+| Orçamentos/Contratos | `16c13ad` |
+| Sub-pass clínico (presença/pendências/horários/detalhes de paciente) | `0fc69bb` |
+
+- **Marketplace (salas/sala-reservas/propostas): auditado — já protegido por POSSE** nos handlers
+  (`owner_usuario_id`, profissional destinatário, dono/solicitante). Sem gap; sem mudança. Commit `0667456`.
+- Validado em DEV com tokens forjados: dono passa, dentista/paciente 403, isolamento cross-tenant intacto.
+
+### 4. Documentação & Skills
+- `documentação/MAPA-FUNCIONAL-COMPLETO.md` (inventário rotas/telas/botões/fluxos/módulos).
+- `documentação/AUDITORIA-ESTRATEGICA-MODELAGEM.md` (Pessoa→Vínculo→Workspace, débitos, riscos).
+- `ScoreOdonto_Skills_Enterprise/`: **62/62 skills preenchidas** com conteúdo real. Commits `5b99292`, `e83af04`, `f22e30e`.
+
+### 5. Pré-requisito de produção
+- **`SCOREO_DB_PASS` provisionado na VPS1** (`/home/deploy/stack/scoreodonto.com/.env`, 0600), valores
+  extraídos do container em execução, `.gitignore` da VPS1 ajustado, conexão validada (`SELECT 1` = ok).
+
+### 6. Fila A concluída — **PRODUÇÃO EM `v1.0.19`** (22/jun/2026)
+- **`git push` do lote** (RBAC 99 rotas + segredos fora do compose/imagem + correções de frontend).
+- **CI desbloqueada:** o build falhou na 1ª vez (`SCOREO_DB_PASS` com `:?` quebrava a interpolação do
+  compose no `docker compose build` do runner) → corrigido com placeholder runtime-only no `build.yml`
+  (commit `715b2dc`). Build verde → imagens `:715b2dc` (back+front, atômicas) publicadas no registry.
+- **Tag `v1.0.19` → `715b2dc`:** job `promote` re-tagueou `:715b2dc` → `:v1.0.19` **sem rebuild**
+  (digests idênticos conferidos) e rodou `deploy-prod.sh v1.0.19` na VPS1.
+- **Backup do banco antes do deploy:** `~/backups/scoreodonto_20260622_0005.dump` na VPS1 (PG18).
+- **Verificado em produção:** `/api/version` = `v1.0.19` (`715b2dc`, PROD); `/api/health` = ok
+  (DB ok, cache ok). DEV (8020) realinhado ao mesmo commit via `./dev-build.sh` (mostra `v1.0.19`).
+- **Rollback trivial:** `./deploy-prod.sh v1.0.18` (+ dump do banco, se necessário).
+
+---
+
+## ⏳ O QUE FALTA
+
+### A) Levar o trabalho a produção (fila) — ✅ CONCLUÍDA
+1. ~~**Imagem limpa `v1.0.19`**~~ → **FEITO** (ver "Fila A concluída" acima). Produção em `v1.0.19`/`715b2dc`.
+2. **Compose novo na VPS1 (opcional, passo 2b):** `deploy-prod.sh` **não faz `git pull`** → o
+   `docker-compose.yml` da VPS1 segue o antigo. Para tirar a senha hardcoded do compose local, copiar o
+   novo `docker-compose.yml` (scp) + recreate. O root `.env` já provisionado cobre isso. **Ainda pendente.**
+
+### B) Rotação dos demais segredos (ainda vivos no histórico/artefatos antigos)
+3. **Senha do banco** (`scoreodonto_user`) — contida ao scoreodonto; exige refactor já feito no compose +
+   `ALTER USER` + atualizar `.env`/`backend/.env` + recreate. Risco de outage → com cuidado/janela.
+4. **Senha do Dragonfly (cache)** — ⚠️ **compartilhada** entre apps (rx, newwhats, subdominio, mercado);
+   trocar derruba os outros → exige **janela coordenada**.
+5. **`OPENAI_API_KEY` / `GEMINI_API_KEY`** — **só você** rotaciona (painéis OpenAI/Google); depois colo os
+   novos valores no `.env` e recrio.
+6. **Histórico do git** — `backend/.env` (e um `backend/.env.bak`) estão no histórico. Após rotacionar tudo,
+   o *scrub* de histórico (force-push, destrutivo) vira **cosmético** — não recomendado às pressas.
+
+### C) Residual de qualidade (não-bloqueante; do MAPA / AUDITORIA)
+- RECEITA de procedimento é **opcional** (`gerarLancamento`/`valor>0`) → decidir se vira padrão (risco de caixa).
+- Estado de plugins divergente cliente/servidor (`localStorage` vs `usuario_plugins`).
+- Órfã `OrthoReports.tsx`; `SyncView` desativada; `server.js.bak`/scripts legados → limpeza.
+- Marketplace: **gateway de pagamento** (salas têm `valor`, sem captura) e **assinaturas SaaS** (manual).
+
+### D) Débitos de modelagem (estratégico; exige aprovação + janela)
+- `dentistas` como **projeção** da pessoa (hoje duplica a pessoa por clínica).
+- `pacientes` com **identidade de pessoa** (hoje preso à clínica, não-portável) — antes, decisão LGPD/jurídica.
+- Unificar workspace (`clinicas` + `salas`); entidade **"rede/grupo"** acima da clínica.
+> Recomendação estratégica única: assumir a **Pessoa como âncora** e parar de manter o legado clínica-cêntrico
+> em paralelo. Detalhe em `AUDITORIA-ESTRATEGICA-MODELAGEM.md`.
+
+---
+
+## Commits da sessão — **PUBLICADOS** (`git push` feito; produção em `v1.0.19`)
+> Todos empurrados para `origin/main`. Promovidos a produção via tag `v1.0.19` (commit `715b2dc`).
+> A rotação do `JWT_SECRET` **não** está nesta lista (foi ação operacional na VPS, sem commit).
+```
+715b2dc ci(build): desbloqueia build — SCOREO_DB_PASS placeholder na interpolação
+8a27f3b docs+infra: corrige status (JWT/contagem) + versão em DEV (dev-build.sh)
+6adf353 docs: status geral de segurança & produção (este documento)
+f22e30e docs(skills): completa as 62 skills
+e83af04 docs(skills): biblioteca operacional
+5b99292 docs: auditoria funcional + estratégica
+0667456 security(rbac): reorder + auditoria do marketplace
+0fc69bb security(rbac): sub-pass clínico
+16c13ad security(rbac): orçamentos e contratos
+5b58a8a security(rbac): operação clínica
+116200c security(rbac): cadastros administrativos
+9ad65c3 security(rbac): gestão de equipe/clínica
+f4e7fe3 security(rbac): rotas financeiras
+1559387 security/fix(front): /update + deep-links
+3aa6a44 security(infra): senhas fora do compose
+fcf2fb1 security(infra): .env fora do git + .dockerignore
+```
+
+## Como retomar
+- **Fila A:** ✅ concluída — produção em **`v1.0.19`** (`715b2dc`). Próximo release: `git push` → CI
+  builda `:<sha>` → `git tag vX.Y.Z` → job `promote` deploya na VPS1.
+- **Antes de abrir a usuários reais:** concluir **B** (rotações) — sobretudo as API keys (você) e a senha do banco.
+- **Pendência pontual:** passo **A.2** (compose novo na VPS1 via scp + recreate) para tirar a senha
+  hardcoded do compose local.
+- Código rodando em **DEV** (`dev.scoreodonto.com`) e **PROD** no mesmo commit `715b2dc`; rollback de
+  prod: `./deploy-prod.sh v1.0.18` (+ dump `~/backups/scoreodonto_20260622_0005.dump` se necessário).
+</content>

frontend/App.tsx

@@ -4,13 +4,19 @@ import { HybridBackend } from './services/backend.ts';
 import { Sidebar } from './components/Sidebar.tsx';
 import {
   Menu, LayoutDashboard, Users, Calendar as CalendarIcon,
-  DollarSign, Activity, ClipboardList, Bell, Settings, MoreHorizontal, Eye, X
+  DollarSign, Activity, ClipboardList, Bell, Settings, MoreHorizontal, Eye, X, PanelLeftOpen
 } from 'lucide-react';
 
 import { ToastContainer } from './components/Toast.tsx';
+import { useAppVersion } from './buildInfo.ts';
 
 import { Dashboard } from './views/Dashboard.tsx';
 import { LeadsView } from './views/LeadsView.tsx';
+import { WaInboxView } from './views/WaInboxView.tsx';
+import { SessionsView } from './views/newwhats/SessionsView.tsx';
+import { InboxView } from './views/newwhats/InboxView.tsx';
+import { SecretariaView } from './views/newwhats/SecretariaView.tsx';
+import { WaSecretariaView } from './views/WaSecretariaView.tsx';
 import { PublicContactForm } from './views/PublicContactForm.tsx';
 import { PatientsView } from './views/PatientsView.tsx';
 import { AgendaView } from './views/AgendaView.tsx';
@@ -30,6 +36,12 @@ import { ReportsView } from './views/ReportsView.tsx';
 import { ComissoesView } from './views/ComissoesView.tsx';
 import { GlosasView } from './views/GlosasView.tsx';
 import { SalaHomeView } from './views/SalaHomeView.tsx';
+import { LabHomeView } from './views/LabHomeView.tsx';
+import { LabAgendaView } from './views/LabAgendaView.tsx';
+import { LabClientesView } from './views/LabClientesView.tsx';
+import { LabCotacoesView } from './views/LabCotacoesView.tsx';
+import { LabEquipeView } from './views/LabEquipeView.tsx';
+import { LabIndicadoresView } from './views/LabIndicadoresView.tsx';
 import { ConfiguracoesView } from './views/ConfiguracoesView.tsx';
 import { OrcamentosView } from './views/OrcamentosView.tsx';
 import { ContratosView } from './views/ContratosView.tsx';
@@ -79,10 +91,21 @@ export type ViewKey =
   | 'contratos'
   | 'plugins'
   | 'rx-radiografias'
+  | 'wa-inbox'
+  | 'wa-sessions'
+  | 'wa-secretaria'
   | 'salas'
   | 'minhas-salas'
   | 'alugar-salas'
   | 'sala-home'
+  | 'lab-home'
+  | 'lab-bancada'
+  | 'lab-agenda'
+  | 'lab-clientes'
+  | 'lab-financeiro'
+  | 'lab-cotacoes'
+  | 'lab-equipe'
+  | 'lab-indicadores'
   | 'marketplace-profissionais'
   | 'criar-clinica'
   | 'rx-config'
@@ -98,6 +121,7 @@ export type ViewKey =
   | 'superadmin-logs'
   | 'superadmin-financeiro'
   | 'superadmin-notificacoes'
+  | 'superadmin-secretaria'
   | 'diretorio-profissionais';
 
 // ------- URL <-> VIEW mapping -------
@@ -129,10 +153,21 @@ const ROUTE_MAP: Record<string, ViewKey> = {
   '/contratos': 'contratos',
   '/plugins': 'plugins',
   '/rx-radiografias': 'rx-radiografias',
+  '/wa-inbox': 'wa-inbox',
+  '/wa-sessions': 'wa-sessions',
+  '/wa-secretaria': 'wa-secretaria',
   '/salas': 'salas',
   '/minhas-salas': 'minhas-salas',
   '/alugar-salas': 'alugar-salas',
   '/sala-home': 'sala-home',
+  '/lab-home': 'lab-home',
+  '/lab-bancada': 'lab-bancada',
+  '/lab-agenda': 'lab-agenda',
+  '/lab-clientes': 'lab-clientes',
+  '/lab-financeiro': 'lab-financeiro',
+  '/lab-cotacoes': 'lab-cotacoes',
+  '/lab-equipe': 'lab-equipe',
+  '/lab-indicadores': 'lab-indicadores',
   '/marketplace-profissionais': 'marketplace-profissionais',
   '/criar-clinica': 'criar-clinica',
   '/rx-config': 'rx-config',
@@ -147,9 +182,13 @@ const ROUTE_MAP: Record<string, ViewKey> = {
   '/superadmin/logs': 'superadmin-logs',
   '/superadmin/financeiro': 'superadmin-financeiro',
   '/superadmin/notificacoes': 'superadmin-notificacoes',
+  '/superadmin/secretaria': 'superadmin-secretaria',
   '/aguardando-convite': 'aguardando-convite',
   '/diretorio-profissionais': 'diretorio-profissionais',
   '/proteses': 'proteses',
+  // Corrige deep-link/refresh: existiam em VIEW_TO_ROUTE mas faltavam aqui (caíam em dashboard).
+  '/comissoes': 'comissoes',
+  '/glosas': 'glosas',
 };
 
 const VIEW_TO_ROUTE: Record<ViewKey, string> = {
@@ -181,10 +220,21 @@ const VIEW_TO_ROUTE: Record<ViewKey, string> = {
   contratos: '/contratos',
   plugins: '/plugins',
   'rx-radiografias': '/rx-radiografias',
+  'wa-inbox': '/wa-inbox',
+  'wa-sessions': '/wa-sessions',
+  'wa-secretaria': '/wa-secretaria',
   salas: '/salas',
   'minhas-salas': '/minhas-salas',
   'alugar-salas': '/alugar-salas',
   'sala-home': '/sala-home',
+  'lab-home': '/lab-home',
+  'lab-bancada': '/lab-bancada',
+  'lab-agenda': '/lab-agenda',
+  'lab-clientes': '/lab-clientes',
+  'lab-financeiro': '/lab-financeiro',
+  'lab-cotacoes': '/lab-cotacoes',
+  'lab-equipe': '/lab-equipe',
+  'lab-indicadores': '/lab-indicadores',
   'marketplace-profissionais': '/marketplace-profissionais',
   'criar-clinica': '/criar-clinica',
   'rx-config': '/rx-config',
@@ -200,6 +250,7 @@ const VIEW_TO_ROUTE: Record<ViewKey, string> = {
   'superadmin-logs': '/superadmin/logs',
   'superadmin-financeiro': '/superadmin/financeiro',
   'superadmin-notificacoes': '/superadmin/notificacoes',
+  'superadmin-secretaria': '/superadmin/secretaria',
   'diretorio-profissionais': '/diretorio-profissionais',
   proteses: '/proteses',
 };
@@ -265,22 +316,44 @@ const MobileBottomNav: React.FC<{
 
 // ------- App -------
 const App: React.FC = () => {
+  const ver = useAppVersion();
   const [isSidebarOpen, setSidebarOpen] = useState(false);
+  // Evita que a sidebar ANIME (slide-in) a cada reload no desktop: a transição só liga
+  // após o 1º paint, então no load ela já nasce posicionada; toggles do usuário animam.
+  const [uiMounted, setUiMounted] = useState(false);
+  useEffect(() => { setUiMounted(true); }, []);
+  // Gaveta de controles da Agenda no MOBILE (título/AGENDAR/ações) — comporta-se como
+  // a sidebar: some por padrão p/ dar o máximo de espaço ao calendário; abre pelo ⋯.
+  const [agendaControlsOpen, setAgendaControlsOpen] = useState(false);
+  // Recolher a sidebar no DESKTOP (persistente) — dá largura ao conteúdo (ex.: agenda).
+  const [isSidebarCollapsed, setSidebarCollapsed] = useState<boolean>(() => {
+    try { return localStorage.getItem('scoreodonto:sidebar-collapsed') === '1'; } catch { return false; }
+  });
+  const toggleSidebarCollapsed = (v: boolean) => {
+    setSidebarCollapsed(v);
+    try { localStorage.setItem('scoreodonto:sidebar-collapsed', v ? '1' : '0'); } catch { /* ignore */ }
+  };
   const [, forcePwRerender] = useState(0); // re-avalia o modal de troca obrigatória de senha
   const currentRole = HybridBackend.getCurrentRole();
   const activeWorkspace = HybridBackend.getActiveWorkspace();
   const clinColor = activeWorkspace?.cor || '#2563eb';
 
   const isViewAllowed = (view: ViewKey, role: string): boolean => {
-    if (['landing', 'login', 'public', 'update'].includes(view)) return true;
+    if (['landing', 'login', 'public'].includes(view)) return true;
+    // /update (migração de banco) é EXCLUSIVA do superadmin (liberado na linha seguinte).
     if (role === 'superadmin') return true;
     // Sync GLOBAL removido do app (substituído pelo backup por clínica em Configurações).
     if (view === 'sync') return false;
     // Locação de Salas: capability PESSOAL (add-on por conta), liberada a qualquer
     // usuário com o plugin ativo na conta — independe de ter clínica/cargo.
     if (view === 'salas' || view === 'minhas-salas' || view === 'alugar-salas') return isPluginActive('locacao-salas');
+    // NewWhats: Inbox e Secretária liberadas a qualquer usuário com o plugin ativo
+    // (a CONFIG do plugin é exclusiva do superadmin via view 'plugins').
+    if (view === 'wa-inbox' || view === 'wa-sessions' || view === 'wa-secretaria') return isPluginActive('newwhats');
     // Contexto de SALA: isola da clínica — só painel da sala/salas/conta/notificações.
     if ((HybridBackend.getActiveWorkspace() as any)?.tipo === 'sala') return ['sala-home', 'configuracoes', 'notificacoes', 'clinicas'].includes(view);
+    // Contexto de LABORATÓRIO: área do protético — painel do lab + bancada/conta/notificações.
+    if ((HybridBackend.getActiveWorkspace() as any)?.tipo === 'laboratorio') return ['lab-home', 'lab-bancada', 'lab-agenda', 'lab-clientes', 'lab-cotacoes', 'lab-financeiro', 'lab-equipe', 'lab-indicadores', 'marketplace-profissionais', 'diretorio-profissionais', 'configuracoes', 'notificacoes', 'clinicas'].includes(view);
     // Catálogo de PLUGINS: EXCLUSIVO do superadmin (já retorna true acima); ninguém mais.
     if (view === 'plugins') return false;
     // Admin/donos têm acesso amplo, MAS as telas de superadmin são exclusivas do superadmin.
@@ -299,7 +372,7 @@ const App: React.FC = () => {
       paciente: ['tratamentos', 'notificacoes', 'configuracoes'],
       dentista: ['dashboard', 'agenda', 'ortodontia', 'tratamentos', 'lancar-gto', 'proteses', 'notificacoes', 'clinicas', 'configuracoes', 'plugins', 'rx-radiografias', 'salas', 'marketplace-profissionais', 'candidatura-tutor', 'tutoria-painel', 'diretorio-profissionais'],
       biomedico: ['dashboard', 'agenda', 'tratamentos', 'lancar-gto', 'especialidades', 'procedimentos', 'notificacoes', 'clinicas', 'configuracoes', 'plugins', 'salas', 'marketplace-profissionais', 'diretorio-profissionais'],
-      protetico: ['dashboard', 'agenda', 'tratamentos', 'lancar-gto', 'proteses', 'notificacoes', 'clinicas', 'configuracoes', 'plugins', 'salas', 'marketplace-profissionais', 'diretorio-profissionais'],
+      protetico: ['lab-home', 'lab-bancada', 'lab-agenda', 'lab-clientes', 'lab-cotacoes', 'lab-financeiro', 'lab-equipe', 'lab-indicadores', 'notificacoes', 'clinicas', 'configuracoes', 'plugins', 'salas', 'marketplace-profissionais', 'diretorio-profissionais'],
       funcionario: ['dashboard', 'leads', 'pacientes', 'agenda', 'financeiro', 'tratamentos', 'lancar-gto', 'proteses', 'relatorios', 'notificacoes', 'clinicas', 'configuracoes', 'orcamentos', 'contratos', 'plugins', 'rx-radiografias', 'salas', 'marketplace-profissionais', 'candidatura-tutor', 'diretorio-profissionais'],
     };
 
@@ -310,6 +383,8 @@ const App: React.FC = () => {
     if (role === 'superadmin') return 'superadmin-overview';
     // Contexto de SALA (workspace tipo='sala') sempre cai no painel da sala.
     if ((HybridBackend.getActiveWorkspace() as any)?.tipo === 'sala') return 'sala-home';
+    // Contexto de LABORATÓRIO (workspace tipo='laboratorio') cai no painel do lab.
+    if ((HybridBackend.getActiveWorkspace() as any)?.tipo === 'laboratorio') return 'lab-home';
     if (role === 'paciente')   return 'tratamentos';
     if (role === 'donosala')   return 'minhas-salas';
     return 'dashboard';
@@ -443,7 +518,7 @@ const App: React.FC = () => {
       case 'leads': return <LeadsView />;
       case 'public': return <PublicContactForm />;
       case 'pacientes': return <PatientsView />;
-      case 'agenda': return <AgendaView onNavigate={handleNavigate} />;
+      case 'agenda': return <AgendaView onNavigate={handleNavigate} sidebarCollapsed={isSidebarCollapsed} onToggleSidebar={() => toggleSidebarCollapsed(!isSidebarCollapsed)} controlsOpen={agendaControlsOpen} onCloseControls={() => setAgendaControlsOpen(false)} />;
       case 'ortodontia': return <OrthoView />;
       case 'financeiro': return <FinanceiroView />;
       case 'dentistas': return <DentistasView />;
@@ -466,10 +541,21 @@ const App: React.FC = () => {
       case 'contratos': return <ContratosView />;
       case 'plugins': return <PluginsView />;
       case 'rx-radiografias': return <RXPlugin />;
+      case 'wa-inbox': return <InboxView onNavigate={handleNavigate} />;
+      case 'wa-sessions': return <SessionsView onNavigate={handleNavigate} />;
+      case 'wa-secretaria': return <SecretariaView onNavigate={handleNavigate} />;
       case 'salas': return <SalasPlugin />;
       case 'minhas-salas': return <SalasPlugin view="minhas" />;
       case 'alugar-salas': return <SalasPlugin view="alugar" />;
       case 'sala-home': return <SalaHomeView />;
+      case 'lab-home': return <LabHomeView />;
+      case 'lab-bancada': return <ProteseView />;
+      case 'lab-agenda': return <LabAgendaView />;
+      case 'lab-clientes': return <LabClientesView tab="clientes" />;
+      case 'lab-financeiro': return <LabClientesView tab="financeiro" />;
+      case 'lab-cotacoes': return <LabCotacoesView />;
+      case 'lab-equipe': return <LabEquipeView />;
+      case 'lab-indicadores': return <LabIndicadoresView />;
       case 'marketplace-profissionais': return <ProfissionaisPlugin />;
       case 'criar-clinica': return <CreateClinicView onCreated={() => { window.location.reload(); }} />;
       case 'rx-config': return <RxConfigView />;
@@ -485,6 +571,7 @@ const App: React.FC = () => {
       case 'superadmin-logs':         return <SuperAdminView tab="logs" />;
       case 'superadmin-financeiro':   return <SuperAdminView tab="financeiro" />;
       case 'superadmin-notificacoes': return <SuperAdminView tab="notificacoes" />;
+      case 'superadmin-secretaria':   return <SuperAdminView tab="secretaria" />;
       // Plugin Profissionais ativo absorve o diretório antigo (mesma rota, view nova).
       case 'diretorio-profissionais': return isPluginActive('profissionais-marketplace') ? <ProfissionaisPlugin /> : <DiretorioProfissionaisView />;
       case 'login':
@@ -493,7 +580,11 @@ const App: React.FC = () => {
     }
   };
 
-  const isStandaloneView = ['landing', 'login', 'public', 'update', 'cadastro-dentista', 'criar-clinica', 'aguardando-convite'].includes(currentView);
+  // Views do plugin NewWhats rodam em tela cheia (sem sidebar/barra do
+  // scoreodonto) — cada uma tem seu próprio "Voltar" (onNavigate) para sair.
+  // /wa-sessions (gestão de sessões WhatsApp) roda COM a sidebar do scoreodonto
+  // (é área de administração). wa-inbox/wa-secretaria seguem em tela cheia.
+  const isStandaloneView = ['landing', 'login', 'public', 'update', 'cadastro-dentista', 'criar-clinica', 'aguardando-convite', 'wa-inbox', 'wa-secretaria'].includes(currentView);
 
   return (
     <>
@@ -519,7 +610,7 @@ const App: React.FC = () => {
               ></div>
             )}
 
-            <div className={`fixed inset-y-0 left-0 z-30 transform transition-transform duration-300 md:relative md:translate-x-0 ${isSidebarOpen ? 'translate-x-0' : '-translate-x-full'}`}>
+            <div className={`fixed inset-y-0 left-0 z-30 transform ${uiMounted ? 'transition-transform duration-300' : ''} ${isSidebarCollapsed ? 'md:hidden' : 'md:relative md:translate-x-0'} ${isSidebarOpen ? 'translate-x-0' : '-translate-x-full'}`}>
               <Sidebar
                 activeTab={currentView}
                 setActiveTab={(t) => handleNavigate(t as ViewKey)}
@@ -528,6 +619,18 @@ const App: React.FC = () => {
           </>
         )}
 
+        {/* Botão flutuante para reexibir a sidebar (desktop, quando recolhida).
+            Na agenda NÃO aparece — ela já tem o próprio toggle ao lado do título. */}
+        {!isStandaloneView && isSidebarCollapsed && currentView !== 'agenda' && (
+          <button
+            onClick={() => toggleSidebarCollapsed(false)}
+            title="Mostrar menu"
+            className="hidden md:flex fixed top-3 left-3 z-40 items-center justify-center w-9 h-9 bg-white border border-gray-200 rounded-lg text-gray-500 hover:text-gray-800 hover:border-gray-300 shadow-sm transition-colors"
+          >
+            <PanelLeftOpen size={18} />
+          </button>
+        )}
+
         <main className={`flex-1 h-full relative flex flex-col min-w-0`}>
           {HybridBackend.isPreviewMode() && (
             <div className="bg-red-600 text-white px-4 py-2 flex items-center justify-between gap-3 shadow-md z-30">
@@ -560,7 +663,18 @@ const App: React.FC = () => {
                   </div>
                   <span className="font-bold text-gray-800 text-sm tracking-tight uppercase">SCOREODONTO</span>
                 </div>
-                <div className="w-8"></div>
+                {/* ⋯ controles da Agenda (só nesta view) — abre a gaveta; senão, espaçador */}
+                {currentView === 'agenda' ? (
+                  <button
+                    onClick={() => setAgendaControlsOpen(true)}
+                    className="p-2 text-gray-600 hover:bg-gray-100 rounded-lg transition-colors"
+                    title="Controles da agenda"
+                  >
+                    <MoreHorizontal size={24} />
+                  </button>
+                ) : (
+                  <div className="w-8"></div>
+                )}
               </div>
             </>
           )}
@@ -577,6 +691,10 @@ const App: React.FC = () => {
         </main>
       </div>
       <ToastContainer />
+      {/* Versão sempre visível no canto inferior direito (lê /api/version; não bloqueia cliques) */}
+      <div className="fixed bottom-1.5 right-2 z-40 pointer-events-none select-none text-[10px] font-mono text-gray-400/70">
+        {ver.version}
+      </div>
     </>
   );
 };