docs(skills): completa as 62 skills (FASE 05/06/08/09/10)

Preenche as 25 restantes com conteúdo real baseado na auditoria + no RBAC:
- FASE_08 Auditoria: Permissoes (RBAC implementado), Entidades, Banco, APIs, Botoes, Performance
- FASE_09 Observabilidade: HealthChecks, VersionamentoRuntime, Logs, Diagnosticos
- FASE_06 Módulos: Agenda, CRM, Proteses, Prontuario, Radiologia, Tutoria, Documentos
- FASE_05 UI/UX: DesignSystem, Dashboard, Responsividade, Acessibilidade
- FASE_10 Roadmap: Monetizacao, Escalabilidade, Backlog, Priorizacao

Todas ancoradas em evidências reais (server.js, types.ts, documentos-unicos, relatórios).

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

ScoreOdonto_Skills_Enterprise/FASE_05_UIUX/SKILL_Acessibilidade.md

@@ -1,29 +1,25 @@
-# Skill Enterprise
+# SKILL — Acessibilidade
 
-## Objetivo
+> Base mínima de a11y, sem regredir a identidade visual. Pragmático para o estado atual.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## Estado atual (honesto)
-- Mapear impacto.
+O app prioriza densidade/visual; a11y é **básica**. Esta skill fixa o mínimo a manter/melhorar sem
-- Mapear dependências.
+quebrar o design.
-- Mapear entidades.
-- Mapear APIs.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Regras obrigatórias
-- Preservar cores.
+1. **Contraste**: texto sobre a cor de marca deve ser legível (a marca é escura → texto branco). Evitar
-- Preservar estilos.
+   cinza-claro sobre branco em informação essencial.
-- Preservar identidade visual.
+2. **Alvos de toque** no mobile ≥ ~40px (os botões do bottom nav/menu já respeitam).
-- Corrigir larguras excessivas.
+3. **Foco**: usar `focus:ring-brand` (já existe) em controles interativos; não remover outline sem substituto.
-- Aplicar max-width.
+4. **Semântica**: `<button>` para ação, `<a>` para navegação; ícone-só precisa de `aria-label`/título.
-- Evitar telas ultrawide desbalanceadas.
+5. **Estados**: feedback de loading/disabled (`disabled:opacity-60`) e toasts para resultado de ação.
 
-## Entregáveis
+## Como auditar
-- Relatório técnico.
+```bash
-- Relatório negócio.
+grep -rnE "onClick" frontend/views/<View>.tsx | grep -ivE "aria-label|title|>.*<"   # ícones-botão sem rótulo
-- Mermaid.
+```
-- Riscos.
+
-- Plano de execução.
+## 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_Dashboard.md

@@ -1,29 +1,22 @@
-# Skill Enterprise
+# SKILL — Dashboard
 
-## Objetivo
+> Tela inicial por papel. Herda de `SKILL_GridSystem.md` + `SKILL_DesktopWidth.md`.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## O que é
-- Mapear impacto.
+Visão consolidada (KPIs) de entrada. Dados via `GET /api/dashboard/stats`. View: `views/Dashboard.tsx`.
-- Mapear dependências.
+Cada papel tem seu ponto de entrada (`getDefaultViewForRole`): superadmin → overview; sala → painel da sala;
-- Mapear entidades.
+paciente → tratamentos; demais → dashboard.
-- Mapear APIs.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Padrão de layout (real)
-- Preservar cores.
+- KPIs em grid `grid-cols-2 md:grid-cols-4` (cards compactos), dentro do wrapper `max-w-7xl mx-auto`.
-- Preservar estilos.
+- Realce com a cor do workspace; números grandes + rótulo caixa-alta.
-- Preservar identidade visual.
-- Corrigir larguras excessivas.
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Regras obrigatórias
-- Relatório técnico.
+1. KPIs vêm do backend (`/api/dashboard/stats`) — não recalcular no cliente de forma divergente.
-- Relatório negócio.
+2. Respeitar o teto de largura (`max-w-7xl`) e o grid mobile-first (ver GridSystem).
-- Mermaid.
+3. Conteúdo do dashboard segue o papel/permissões (não mostrar KPI que o papel não pode ver).
-- Riscos.
+
-- Plano de execução.
+## 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

@@ -1,29 +1,29 @@
-# Skill Enterprise
+# SKILL — Design System (REGRA RÍGIDA)
 
-## Objetivo
+> Tokens e padrões visuais REAIS do app. **Preservar a identidade aprovada. Não inventar.**
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Herda de `SKILL_Containers.md`.
 
-## Checklist Obrigatório
+## Stack
-- Mapear impacto.
+React 19 + **Tailwind 4** + lucide-react (ícones). Sem biblioteca de componentes externa.
-- Mapear dependências.
-- Mapear entidades.
-- Mapear APIs.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Cor de marca (token oficial)
-- Preservar cores.
+- `--brand-color` ← `activeWorkspace.cor` (default `#2563eb`; superadmin `#dc2626`).
-- Preservar estilos.
+- Classes utilitárias: `bg-brand`, `text-brand`, `border-brand`, `hover:bg-brand`, `focus:ring-brand`.
-- Preservar identidade visual.
+- **Sempre** o token/classe — nunca um hex novo cravado.
-- Corrigir larguras excessivas.
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Tipografia & forma (observado)
-- Relatório técnico.
+- Rótulos/menus/badges: **caixa-alta**, peso forte (`font-bold`/`font-black uppercase`, `tracking`).
-- Relatório negócio.
+- Cantos arredondados (`rounded-xl`/`2xl`), bordas suaves (`border-gray-200`), sombra leve.
-- Mermaid.
+- Ícones lucide-react com tamanho consistente (`size={16..22}`).
-- Riscos.
+
-- Plano de execução.
+## 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_Responsividade.md

@@ -1,29 +1,23 @@
-# Skill Enterprise
+# SKILL — Responsividade (REGRA RÍGIDA)
 
-## Objetivo
+> Mobile-first, como o app já é. Herda de `SKILL_GridSystem.md`.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## Padrão real (não regredir)
-- Mapear impacto.
+- **Mobile-first**: estado base = mobile; cresce com `sm:`/`md:`/`lg:` (uso: `sm:`≈238, `md:`≈186, `lg:`≈100; `xl:` raro≈8).
-- Mapear dependências.
+- **Sidebar**: `w-64` fixa no desktop; off-canvas no mobile (drawer com overlay `bg-black/50 md:hidden`).
-- Mapear entidades.
+- **Bottom nav mobile** por papel (`BOTTOM_TABS` em `App.tsx`) com `+ Mais`.
-- Mapear APIs.
+- Padding de página `p-4 md:p-8`; safe-area no bottom nav (`env(safe-area-inset-bottom)`).
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Regras obrigatórias
-- Preservar cores.
+1. Toda tela nova **funciona no mobile** (coluna única, sem overflow horizontal) E no desktop.
-- Preservar estilos.
+2. Não depender de `xl:`/`2xl:` para o layout funcionar.
-- Preservar identidade visual.
+3. Sidebar drawer no mobile; conteúdo dentro de `max-w-7xl mx-auto`.
-- Corrigir larguras excessivas.
+4. Tabelas largas → `overflow-x-auto` (scroll interno), nunca estourar o container.
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Validação (obrigatória antes de entregar)
-- Relatório técnico.
+- Mobile (≤640): 1 coluna, sem scroll horizontal, bottom nav ok.
-- Relatório negócio.
+- Tablet (`md`), Desktop (`lg`), Ultrawide (centraliza, sem esticar).
-- Mermaid.
+
-- Riscos.
+## Anti-padrões
-- Plano de execução.
+- ❌ Testar só no desktop. ❌ Overflow horizontal no mobile. ❌ Layout que quebra sem `xl:`.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_06_MODULOS/SKILL_Agenda.md

@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Módulo Agenda
 
-## Objetivo
+> Coração operacional. RBAC: capability `'agenda'` (staff clínico, bloqueia paciente).
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## O que é
-- Mapear impacto.
+Agendar/confirmar/remarcar consultas, controle de presença, anti-overbooking e pendências de reagendamento.
-- Mapear dependências.
-- Mapear entidades.
-- Mapear APIs.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Entidades
-- Preservar cores.
+`agendamentos`, `agenda_presenca`, `agenda_pendencias`, `interesses_agenda`, `dentistas`+`dentistas_horarios`.
-- Preservar estilos.
-- Preservar identidade visual.
-- Corrigir larguras excessivas.
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Rotas principais
-- Relatório técnico.
+- `GET/POST /api/agendamentos`, `PUT/DELETE /api/agendamentos/:id`
-- Relatório negócio.
+- Ações `/:id`: `confirmar`, `falta`, `remarcar`, `restaurar`, `reencaminhar`, `solicitar-avaliacao`
-- Mermaid.
+- `GET/POST /api/agenda/presenca`, `GET /api/agenda/{pendencias,atividade}`, `POST /api/agenda/pendencias/:id/resolver`
-- Riscos.
+- `POST /api/agenda/importar-google`, horários: `GET /api/dentistas/:id/horarios`, `POST/DELETE /api/dentistas/horarios`
-- Plano de execução.
+
+## 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

@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Módulo CRM (Leads)
 
-## Objetivo
+> Topo do funil comercial. RBAC: capability `'leads'` (funcionário + dono).
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## O que é
-- Mapear impacto.
+Captar interessados e **converter** em paciente + agendamento (início do ciclo clínico).
-- Mapear dependências.
-- Mapear entidades.
-- Mapear APIs.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Entidades
-- Preservar cores.
+`leads` (status: Novo|Convertido|Arquivado), `interesses_agenda`, gera `pacientes` + `agendamentos`.
-- Preservar estilos.
-- Preservar identidade visual.
-- Corrigir larguras excessivas.
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Rotas
-- Relatório técnico.
+`GET/POST /api/leads`, `POST /api/leads/:id/converter`. Origem pública: `PublicContactForm`/`/api/interesses`.
-- Relatório negócio.
+
-- Mermaid.
+## Regra de negócio central (verificada)
-- Riscos.
+`POST /api/leads/:id/converter`:
-- Plano de execução.
+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

@@ -1,29 +1,25 @@
-# Skill Enterprise
+# SKILL — Módulo Documentos (Receitas, Exames, Contratos, Mídia)
 
-## Objetivo
+> Geração e guarda de documentos clínicos/jurídicos e mídia. Cruza Prontuário e Contratos.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## O que é
-- Mapear impacto.
+Receitas, pedidos de exame, contratos (com assinatura eletrônica) e arquivos (fotos, comprovantes, PDFs).
-- Mapear dependências.
-- Mapear entidades.
-- Mapear APIs.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Entidades
-- Preservar cores.
+`modelos_receita`/`items_receita`, `pedidos_exame`/`items_pedido_exame`,
-- Preservar estilos.
+`contratos`/`contrato_modelos`/`contrato_partes`/`contrato_assinaturas`, e fotos por entidade
-- Preservar identidade visual.
+(`*_foto`). PDFs no frontend via `jspdf`.
-- Corrigir larguras excessivas.
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Acesso à mídia (padrão real)
-- Relatório técnico.
+Arquivos são servidos por **URL assinada**: `/api/.../raw?t=signMedia(id)` — sem token de sessão.
-- Relatório negócio.
+A URL só é entregue a quem já passou pelo guard da listagem. **Não** gatear o `/raw` por capability
-- Mermaid.
+(quebraria a imagem); a proteção é o token assinado + a lista gateada.
-- Riscos.
+
-- Plano de execução.
+## 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

@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Módulo Prontuário (Paciente + Ortodontia)
 
-## Objetivo
+> O histórico clínico do paciente. Detalhes acessíveis a staff clínico (capability `'agenda'`).
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## O que é
-- Mapear impacto.
+Prontuário do paciente: dados, família, score, faltas, procedimentos realizados, receitas, pedidos de exame,
-- Mapear dependências.
+e o tratamento **ortodôntico** completo.
-- Mapear entidades.
-- Mapear APIs.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Entidades
-- Preservar cores.
+`pacientes`, `procedimentos_realizados`(+foto), `modelos_receita`/`items_receita`, `pedidos_exame`/`items_pedido_exame`,
-- Preservar estilos.
+`avaliacoes`/`avaliacao_foto`; **orto**: `ortho_tratamento`, `ortho_evolucao`, `ortho_photo`(+session/annotation).
-- Preservar identidade visual.
-- Corrigir larguras excessivas.
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Rotas
-- Relatório técnico.
+`GET/POST/PUT /api/pacientes[...]`, `GET /api/pacientes/:id/{score,faltas,familia}`,
-- Relatório negócio.
+`GET/POST /api/orto/tratamentos[/:id/{evolucoes,finalizar}]`, `/api/orto/{sessoes,fotos}`, `/api/avaliacoes`.
-- Mermaid.
+
-- Riscos.
+## Regras de negócio
-- Plano de execução.
+- **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

@@ -1,29 +1,25 @@
-# Skill Enterprise
+# SKILL — Módulo Próteses / GTO
 
-## Objetivo
+> Controle de laboratório. Liga-se à Comissão pelo **custo lab**. Ver `../FASE_03_PESSOAS/SKILL_Proteticos.md`.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## O que é
-- Mapear impacto.
+Ordens de Serviço de prótese (produto, dentes, material, custo lab, prazo, entrega) e GTO (guia de tratamento).
-- Mapear dependências.
-- Mapear entidades.
-- Mapear APIs.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Entidades
-- Preservar cores.
+`protese_os`, `protese_os_evento`, `protese_os_foto`, `protese_produtos`, `protese_laboratorios`;
-- Preservar estilos.
+GTO legado: `gto_builders`/`gto_items`, `guias_odontologicas`.
-- Preservar identidade visual.
-- Corrigir larguras excessivas.
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Rotas
-- Relatório técnico.
+`GET/POST /api/protese/os`, `GET /api/protese/os/:id`, `POST /api/protese/os/:id/{status,foto}`,
-- Relatório negócio.
+`GET/POST/PUT/DELETE /api/protese/produtos`, `GET /api/protese/laboratorios[/:id/produtos]`, `GET /api/protese/bancada`.
-- Mermaid.
+
-- Riscos.
+## Regra de negócio central
-- Plano de execução.
+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

@@ -1,29 +1,24 @@
-# Skill Enterprise
+# SKILL — Módulo Radiologia (RX)
 
-## Objetivo
+> Plugin `rx-scoreodonto`. Radiografias são ODONTOLÓGICAS (papéis odonto, não bio/protético).
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## O que é
-- Mapear impacto.
+Captura/gestão de radiografias e dos dispositivos (PCs/sensores) por clínica. Integra com o produto externo
-- Mapear dependências.
+**rx.scoreodonto.com** (server + client.exe) — ver `documentos-unicos/projetos/rx.scoreodonto.com*`.
-- Mapear entidades.
-- Mapear APIs.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Rotas
-- Preservar cores.
+`GET /api/rx/{config,devices,images,patients,health}`, `PUT /api/rx/config`, `POST /api/rx/devices`.
-- Preservar estilos.
+Views: `plugins/RXPlugin.tsx` (RX/Radiografias), `RxConfigView` (Dispositivos RX).
-- Preservar identidade visual.
-- Corrigir larguras excessivas.
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Permissões (do Sidebar real)
-- Relatório técnico.
+- **RX/Radiografias**: dentista + donos/funcionário (papéis odonto). **Biomédico e protético NÃO veem RX.**
-- Relatório negócio.
+- **Dispositivos RX**: admin/donos + superadmin.
-- Mermaid.
+- Requer o plugin `rx-scoreodonto` ativo na conta.
-- Riscos.
+
-- Plano de execução.
+## 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

@@ -1,29 +1,26 @@
-# Skill Enterprise
+# SKILL — Módulo Tutoria de Ortodontia
 
-## Objetivo
+> **Única receita de plataforma automatizada hoje** (MercadoPago). Ver `../FASE_03_PESSOAS/SKILL_Tutores.md`.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## O que é
-- Mapear impacto.
+Dentista vira **tutor** (pagando inscrição) e atende solicitações de orto de outros dentistas; a plataforma
-- Mapear dependências.
+fica com uma comissão sobre a consultoria.
-- Mapear entidades.
-- Mapear APIs.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Entidades
-- Preservar cores.
+`ortho_tutor_config` (`comissao_pct` default 20, `taxa_inscricao`, chave PIX, credenciais MP),
-- Preservar estilos.
+`ortho_tutor_profile`, `ortho_tutor_candidatura`, `ortho_tutoring_request`/`message`/`photo_package`.
-- Preservar identidade visual.
-- Corrigir larguras excessivas.
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Rotas
-- Relatório técnico.
+`POST /api/tutoria/candidaturas[/:id/pagamento]`, `POST /api/tutoria/mp-webhook` (público),
-- Relatório negócio.
+`GET/POST /api/tutoria/solicitacoes[...]`, admin: `/api/admin/{candidaturas,repasses,tutor-config}`.
-- Mermaid.
+
-- Riscos.
+## Fluxo de receita (verificado)
-- Plano de execução.
+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_08_AUDITORIA/SKILL_APIs.md

@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Auditoria de APIs
 
-## Objetivo
+> Como mapear e evoluir a API sem quebrar consumidores. Complementa `SKILL_Rotas.md`.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## Realidade
-- Mapear impacto.
+- **~277 rotas** REST `/api/*` num único `backend/server.js` (Express monolítico, ~516 KB). Sem camada de
-- Mapear dependências.
+  controllers/services separada.
-- Mapear entidades.
+- Guards: `authGuard` (identidade), `tenantGuard` (tenant), `requireCapability*` (cargo), `superadminGuard`.
-- Mapear APIs.
+- Endpoints transversais: `GET /api/version`, `GET /api/health` (ver FASE_09); mídia por **URL assinada**
-- Mapear permissões.
+  (`/raw?t=signMedia(...)`).
-- Validar desktop.
+- Frontend consome via `services/backend.ts` (`HybridBackend`/`apiFetch`).
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Como auditar
-- Preservar cores.
+```bash
-- Preservar estilos.
+grep -oE "app\.(get|post|put|delete|patch)\('[^']+" backend/server.js | sort -u   # todas as rotas
-- Preservar identidade visual.
+grep -rn "API_URL}/<recurso>" frontend/services/backend.ts                         # consumidores
-- Corrigir larguras excessivas.
+```
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Regras obrigatórias
-- Relatório técnico.
+1. **Nunca** mudar o caminho/contrato de uma rota sem achar TODOS os consumidores (`services/backend.ts` + views).
-- Relatório negócio.
+2. Toda rota nova: definir guard correto (identidade vs tenant vs cargo) — ver `SKILL_Permissoes.md`.
-- Mermaid.
+3. Erros consistentes (`{ error }` / `{ success:false, message }` conforme o padrão vizinho).
-- Riscos.
+4. Rota que toca dado de clínica → `clinica_id` + `tenantGuard`.
-- Plano de execução.
+
+## 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

@@ -1,29 +1,27 @@
-# Skill Enterprise
+# SKILL — Auditoria de Banco
 
-## Objetivo
+> Como inspecionar e mexer no banco sem quebrar. Herda de `../FASE_07_INFRA/SKILL_PostgreSQL.md`.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## Realidade
-- Mapear impacto.
+- **PostgreSQL** (PostGIS) na VPS3 (`10.99.0.3`), banco `scoreodonto`. ~70 tabelas acessadas por **SQL direto**
-- Mapear dependências.
+  (`pg`), via helpers `buildInsert`/`buildUpdate`. **Prisma é vestigial** (4 modelos GTO legados).
-- Mapear entidades.
+- DEV isolado: container `pgdev` (banco `scoreodonto_dev`). Mexer aqui tem zero impacto em produção.
-- Mapear APIs.
+- **Migrações aditivas no boot**: blocos `CREATE TABLE IF NOT EXISTS` / `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Regras obrigatórias
-- Preservar cores.
+1. **Só aditivo** (add tabela/coluna). Nunca DROP/ALTER destrutivo → quebra rollback (ver Deploy Imutável).
-- Preservar estilos.
+2. **Toda query operacional filtra `clinica_id`** (tenancy).
-- Preservar identidade visual.
+3. Validar migração arriscada **no `pgdev`** antes; **backup `pg_dump -Fc`** antes de release sensível.
-- Corrigir larguras excessivas.
+4. Sem shell na VPS3 → operar por container (`pg_dump`/`pg_restore`/`psql`).
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Como auditar (via container, com creds do `.env`)
-- Relatório técnico.
+```bash
-- Relatório negócio.
+# tabelas e colunas
-- Mermaid.
+grep -niE "CREATE TABLE IF NOT EXISTS|ADD COLUMN IF NOT EXISTS" backend/server.js
-- Riscos.
+# índices declarados
-- Plano de execução.
+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

@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Auditoria de Botões
 
-## Objetivo
+> Como rastrear o que cada botão faz (rota → tabela → fluxo) antes de mexer. Base:
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> `documentação/MAPA-FUNCIONAL-COMPLETO.md` (Etapa 3).
 
-## Checklist Obrigatório
+## Método
-- Mapear impacto.
+Para cada botão: **rótulo → handler no front → método HTTP/rota → tabela impactada → fluxo a jusante**.
-- Mapear dependências.
-- Mapear entidades.
-- Mapear APIs.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Exemplos reais (verificados)
-- Preservar cores.
+| Botão (tela) | Rota | Tabela | Próximo fluxo |
-- Preservar estilos.
+|---|---|---|---|
-- Preservar identidade visual.
+| Novo Agendamento (Agenda) | `POST /api/agendamentos` | `agendamentos` | Procedimento → Financeiro |
-- Corrigir larguras excessivas.
+| Confirmar Presença (Agenda) | `POST /api/agenda/presenca` | `agenda_presenca` | libera lançamento |
-- Aplicar max-width.
+| Lançar Procedimento (Pacientes) | `POST /api/procedimentos-realizados` | `procedimentos_realizados` (+`financeiro`) | Comissão → Repasse |
-- Evitar telas ultrawide desbalanceadas.
+| 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 |
 
-## Entregáveis
+## Como auditar
-- Relatório técnico.
+```bash
-- Relatório negócio.
+grep -oE ">[A-ZÀ-Ú][a-zà-úA-ZÀ-Ú /]{3,28}<" frontend/views/<View>.tsx   # rótulos
-- Mermaid.
+# depois localize o onClick → método do HybridBackend → rota em services/backend.ts
-- Riscos.
+```
-- Plano de execução.
+
+## 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

@@ -1,29 +1,29 @@
-# Skill Enterprise
+# SKILL — Auditoria de Entidades
 
-## Objetivo
+> Como verificar se as entidades estão bem classificadas. Herda de
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> `../FASE_01_ARQUITETURA/SKILL_ModelagemMestra.md`. Detalhe em `documentação/AUDITORIA-ESTRATEGICA-MODELAGEM.md`.
 
-## Checklist Obrigatório
+## Entidades-âncora (corretas)
-- Mapear impacto.
+- `usuarios` (Pessoa) · `vinculos(usuario_id, clinica_id, role, setor_id, funcao_id)` (Vínculo+RBAC)
-- Mapear dependências.
+- `clinicas(tipo: pessoal|consultorio|clinica, owner_id)` + `salas(tipo='sala')` (Workspaces)
-- Mapear entidades.
+- `usuario_areas`, `usuario_plugins`, `funcoes` (capacidades/cargo)
-- Mapear APIs.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Débitos de modelagem (gravidade ALTA — vigiar)
-- Preservar cores.
+- **`dentistas`**: tabela paralela a `usuarios` (mesma pessoa duplicada por clínica, `usuario_id` opcional)
-- Preservar estilos.
+  → tratar como **projeção de agenda**, não identidade.
-- Preservar identidade visual.
+- **`pacientes`**: tem `clinica_id` e **não** `usuario_id` (preso à clínica, não-portável); há 2 variantes de
-- Corrigir larguras excessivas.
+  INSERT (com/sem `clinica_id`) — resíduo legado.
-- Aplicar max-width.
+- **MÉDIA**: workspace dividido em 2 tabelas (`clinicas` + `salas`); acoplamento role↔tipo (`donoconsultorio`).
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Como auditar
-- Relatório técnico.
+```bash
-- Relatório negócio.
+grep -niE "CREATE TABLE" backend/server.js | sort           # tabelas reais (banco é SQL puro, Prisma vestigial)
-- Mermaid.
+grep -oiE "(FROM|JOIN|INTO|UPDATE) [a-z_]+" backend/server.js | awk '{print $2}' | sort | uniq -c | sort -rn
-- Riscos.
+```
-- Plano de execução.
+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_Performance.md

@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Auditoria de Performance
 
-## Objetivo
+> Onde olhar antes de otimizar. Sem micro-otimização cega — medir primeiro.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## Pontos de atenção reais
-- Mapear impacto.
+- **`server.js` monolítico** (~516 KB): carga cognitiva alta, mas não é gargalo de runtime por si.
-- Mapear dependências.
+- **Guards fazem queries por request**: `tenantGuard` (1 SELECT em `vinculos`) + `requireCapability` (1–2
-- Mapear entidades.
+  SELECTs em `usuarios`/`vinculos`/`funcoes`). Aceitável; se virar gargalo, considerar cache curto do papel.
-- Mapear APIs.
+- **Catálogos/listas**: `GET /api/{procedimentos,especialidades,planos,dentistas,pacientes,agendamentos}` —
-- Mapear permissões.
+  garantir índices em `clinica_id` e filtros corretos.
-- Validar desktop.
+- **PostGIS**: busca por proximidade (salas) precisa de índice GIST em `geo`.
-- Validar mobile.
+- **Cache DragonflyDB** (`/1`): usado para acelerar; `/api/health` reporta latência de banco e cache.
-- Atualizar documentação.
 
-## UI Desktop
+## Como auditar
-- Preservar cores.
+```bash
-- Preservar estilos.
+grep -niE "CREATE INDEX" backend/server.js                 # índices existentes
-- Preservar identidade visual.
+grep -niE "SELECT .* FROM (pacientes|agendamentos)" backend/server.js | head   # queries quentes
-- Corrigir larguras excessivas.
+curl -s https://<projeto>/api/health   # latency_ms de database/cache
-- Aplicar max-width.
+```
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Regras obrigatórias
-- Relatório técnico.
+1. **Medir** (latências do `/api/health`, EXPLAIN) antes de otimizar.
-- Relatório negócio.
+2. Índice em toda coluna usada em filtro frequente (`clinica_id`, FKs, status).
-- Mermaid.
+3. Não introduzir N+1 em loop de query; preferir `IN`/JOIN.
-- Riscos.
+
-- Plano de execução.
+## 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

@@ -1,29 +1,36 @@
-# Skill Enterprise
+# SKILL — Auditoria de Permissões (RBAC)
 
-## Objetivo
+> Como o controle de acesso REAL funciona hoje e como auditá-lo. Herda de
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> `../FASE_01_ARQUITETURA/SKILL_RBAC.md`. Implementado no backend nesta stack.
 
-## Checklist Obrigatório
+## Três planos de autorização (backend)
-- Mapear impacto.
+1. **Identidade** — `authGuard`: valida o JWT (assinado com `JWT_SECRET`), popula `req.authUser.userId`.
-- Mapear dependências.
+2. **Tenant** — `tenantGuard`: valida que o usuário tem **vínculo** com a `clinica_id` pedida (ou é dono da
-- Mapear entidades.
+   sala); seta `req.clinicaId`. Sem vínculo → 403 `[TENANT VIOLATION]`.
-- Mapear APIs.
+3. **Cargo (capability)** — `requireCapability(cap)` / `requireCapabilityRow(cap, tabela)` /
-- Mapear permissões.
+   `requireCapabilityFromOrders(cap, tabela)`: exige a capability no workspace ativo. **Superadmin** → `superadminGuard` (checa `usuarios.role` no banco).
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## `capabilityCore` (espelha o `isViewAllowed` do frontend)
-- Preservar cores.
+- superadmin global → ok;
-- Preservar estilos.
+- dono (`donoclinica`/`donoconsultorio`/`admin`, `CAP_OWNER_ROLES`) → ok;
-- Preservar identidade visual.
+- cargo com `funcoes.permissoes` (JSONB) explícitas → ok se inclui a capability;
-- Corrigir larguras excessivas.
+- senão, **mapa padrão por papel** (`CAP_DEFAULTS`, cópia fiel do frontend).
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Cobertura (99 rotas gateadas)
-- Relatório técnico.
+financeiro (`'financeiro'`/`'comissoes'`/`'glosas'`), equipe (`'gestao-equipe'`), cadastros
-- Relatório negócio.
+(`'dentistas'`/`'especialidades'`/`'procedimentos'`/`'planos'`, incl. `/reorder`), operação clínica
-- Mermaid.
+(`'agenda'`/`'leads'`), orçamentos/contratos. Marketplace (salas/propostas) = autorização por **posse** no handler.
-- Riscos.
+
-- Plano de execução.
+## 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_09_OBSERVABILIDADE/SKILL_Diagnosticos.md

@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Diagnósticos (runbook de incidente)
 
-## Objetivo
+> Passo a passo quando algo quebra. Combina Health, Logs, Deploy Imutável.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## Triagem rápida
-- Mapear impacto.
+1. `GET /api/health` — `database down` (503)? `cache degraded`? `version` esperada?
-- Mapear dependências.
+2. `GET /api/version` — bate com a tag que deveria estar no ar?
-- Mapear entidades.
+3. `docker ps` (rootless) — container `Up`? reiniciando (`RestartCount`)?
-- Mapear APIs.
+4. `docker logs --tail 80 <container>` — erro no boot? `[PG]`/`[DRAGONFLY]` conectaram?
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Causas comuns (reais nesta stack)
-- Preservar cores.
+- **`env file .secrets/.env not found`** → falta o env_file no host (VPS1). Copiar manualmente (fora do git).
-- Preservar estilos.
+- **`database down`** → Postgres VPS3 inacessível (WireGuard) ou credencial errada.
-- Preservar identidade visual.
+- **`cache down`** → Dragonfly/`ping()` (degradável; não derruba).
-- Corrigir larguras excessivas.
+- **Migração** falhou no boot → ver log `[MIGRATION]`.
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Recuperação
-- Relatório técnico.
+- App quebrado pós-deploy → **rollback por imagem** (segundos): `deploy-prod.sh <ref-anterior>` (ver Deploy Imutável).
-- Relatório negócio.
+- Dado corrompido → restaurar `pg_dump` de `/home/deploy/backups/` (caso extremo).
-- Mermaid.
+
-- Riscos.
+## Regras obrigatórias
-- Plano de execução.
+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

@@ -1,29 +1,26 @@
-# Skill Enterprise
+# SKILL — Health Checks
 
-## Objetivo
+> Como saber se o app está vivo e saudável, sem SSH. Fonte: `documentos-unicos/deploy/versionamento.md`.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## Endpoint real
-- Mapear impacto.
+`GET /api/health` → `{ status, version, commit, environment, uptime_s, checks }`:
-- Mapear dependências.
+- **`database`** é crítico: se cair → `status: down` + **HTTP 503**.
-- Mapear entidades.
+- **`cache`** (DragonflyDB) é opcional: se cair → `status: degraded` (HTTP 200); `disabled` se desligado.
-- Mapear APIs.
+- Cada check traz `latency_ms` — útil para perceber lentidão de banco/cache.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Como usar
-- Preservar cores.
+```bash
-- Preservar estilos.
+curl -s https://<projeto>/api/health        # produção
-- Preservar identidade visual.
+curl -s https://dev.<projeto>/api/health    # dev
-- Corrigir larguras excessivas.
+```
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Regras obrigatórias
-- Relatório técnico.
+1. **Validar `/api/health` após todo deploy** (e na rotina de monitoramento).
-- Relatório negócio.
+2. `database down` (503) é incidente → investigar conexão VPS1→VPS3 / Postgres.
-- Mermaid.
+3. `cache down/degraded` não derruba o app, mas registre (ex.: pré-existente no RX — `redis.ping()`).
-- Riscos.
+4. Não remover/alterar o contrato do `/api/health` (monitor externo depende dele).
-- Plano de execução.
+
+## 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

@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Logs & Auditoria
 
-## Objetivo
+> Onde está o rastro do que aconteceu. Dois níveis: log de aplicação e trilha de auditoria persistida.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## Auditoria de negócio (persistida)
-- Mapear impacto.
+- Tabela **`audit_log`** (`clinica_id, entidade, entidade_id, acao, actor_id, actor_nome, detalhes, at`),
-- Mapear dependências.
+  gravada por `registrarAudit(...)` em mutações sensíveis (procedimento, repasse, comissão, contrato, equipe…).
-- Mapear entidades.
+- **Imutável** — é o rastro de quem fez o quê. Mutações financeiras/RBAC devem registrar.
-- Mapear APIs.
+- `login_log` registra acessos (visível em SuperAdmin → Acessos).
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Log de aplicação (runtime)
-- Preservar cores.
+- `console.*` no `server.js` (boot, `[PG] Connected`, `[DRAGONFLY] Connected`, `[WS] broadcast`,
-- Preservar estilos.
+  `[TENANT VIOLATION]`, `[CLINICA] Created`…). Visível em `docker logs <container>` (rootless).
-- Preservar identidade visual.
-- Corrigir larguras excessivas.
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Como usar
-- Relatório técnico.
+```bash
-- Relatório negócio.
+DOCKER_HOST=unix:///run/user/1000/docker.sock docker logs --tail 50 <container>
-- Mermaid.
+grep -n "registrarAudit" backend/server.js   # pontos auditados
-- Riscos.
+```
-- Plano de execução.
+
+## 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

@@ -1,29 +1,26 @@
-# Skill Enterprise
+# SKILL — Versionamento em Runtime
 
-## Objetivo
+> De onde vem a versão exibida e por que ela é confiável. Herda de `../FASE_07_INFRA/SKILL_BuildOnce.md`.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## Como funciona (real)
-- Mapear impacto.
+- A versão **nasce da tag git** (`vX.Y.Z`) e é **injetada no deploy em runtime** (`APP_VERSION`), não escrita à
-- Mapear dependências.
+  mão (não existe mais `constants.ts`/`update-version.js`).
-- Mapear entidades.
+- `commit` e `build` são **carimbados na imagem** (imutáveis, propriedade do artefato).
-- Mapear APIs.
+- Em **DEV** aparece `dev`; o número só existe em produção.
-- Mapear permissões.
+- Exposição: `GET /api/version` → `{ name, version, commit, build, environment }`. O frontend **não embute**
-- Validar desktop.
+  versão — lê de `/api/version` (fonte única = backend). Mostrada no rodapé (canto inf. direito) e em
-- Validar mobile.
+  Configurações → "Sobre o sistema".
-- Atualizar documentação.
 
-## UI Desktop
+## Como verificar
-- Preservar cores.
+```bash
-- Preservar estilos.
+curl -s https://<projeto>/api/version   # → vX.Y.Z · <commit> · PROD
-- Preservar identidade visual.
+```
-- Corrigir larguras excessivas.
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Regras obrigatórias
-- Relatório técnico.
+1. **Não** hardcodar versão em arquivo — só a tag define.
-- Relatório negócio.
+2. A MESMA imagem promovida sob a tag = `commit`/`build` imutáveis + `version`/`environment` em runtime.
-- Mermaid.
+3. Conferir `/api/version` após deploy (bate com a tag promovida?).
-- Riscos.
+
-- Plano de execução.
+## 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

@@ -1,29 +1,26 @@
-# Skill Enterprise
+# SKILL — Backlog (Roadmap)
 
-## Objetivo
+> Itens reais levantados nas auditorias e na sessão de hardening. Não inventar; manter atualizado.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## Segurança / produção (parcialmente feito em DEV)
-- Mapear impacto.
+- ✅ JWT rotacionado (dev+prod); `.env` fora do git; `.dockerignore`; senhas fora do compose; RBAC por cargo (99 rotas).
-- Mapear dependências.
+- ⬜ Provisionar `SCOREO_DB_PASS` na VPS1; push imagem limpa `v1.0.19`; rotacionar DB/cache/API keys.
-- Mapear entidades.
-- Mapear APIs.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Correções (do MAPA-FUNCIONAL)
-- Preservar cores.
+- ⬜ Deep-links residuais já tratados (`/comissoes`, `/glosas`); revisar outros se surgirem.
-- Preservar estilos.
+- ⬜ RECEITA de procedimento opcional → decidir se vira padrão (risco de caixa).
-- Preservar identidade visual.
+- ⬜ Estado de plugins divergente cliente/servidor (`localStorage` vs `usuario_plugins`).
-- Corrigir larguras excessivas.
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Modelagem (do AUDITORIA-ESTRATEGICA)
-- Relatório técnico.
+- ⬜ `dentistas` como projeção da pessoa; `pacientes` com identidade (LGPD/jurídico antes).
-- Relatório negócio.
+- ⬜ Unificar workspace (`clinicas`+`salas`); entidade "rede" acima da clínica.
-- Mermaid.
+
-- Riscos.
+## Receita (do SKILL_Monetizacao)
-- Plano de execução.
+- ⬜ 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

@@ -1,29 +1,24 @@
-# Skill Enterprise
+# SKILL — Escalabilidade (Roadmap)
 
-## Objetivo
+> O que o modelo suporta em 5 anos e onde estão os gargalos. Base: `AUDITORIA-ESTRATEGICA-MODELAGEM.md`.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## O que JÁ escala (base Pessoa→Vínculo→Workspace)
-- Mapear impacto.
+- Pessoa em **múltiplos workspaces** (N `vinculos`), workspace pessoal automático, salas/tutoria/marketplace.
-- Mapear dependências.
-- Mapear entidades.
-- Mapear APIs.
-- Mapear permissões.
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Gargalos conhecidos
-- Preservar cores.
+| Cenário | Suporta? | Gargalo |
-- Preservar estilos.
+|---|---|---|
-- Preservar identidade visual.
+| Dentista em várias clínicas | parcial | `dentistas` **duplica a pessoa** por clínica (agenda/horários presos ao `dentistas.id`) |
-- Corrigir larguras excessivas.
+| Paciente entre clínicas | não | `pacientes` preso à clínica, sem identidade de pessoa (não-portável) |
-- Aplicar max-width.
+| Redes de clínicas | não | **não existe entidade "rede/grupo"** acima da clínica (workspaces são planos) |
-- Evitar telas ultrawide desbalanceadas.
+| 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) |
 
-## Entregáveis
+## Direção (sem propor implementação)
-- Relatório técnico.
+Consolidar a **Pessoa** como âncora única (unificar `dentistas`→projeção; paciente→identidade) destrava
-- Relatório negócio.
+multi-clínica, redes e portabilidade. Coexistir os 2 modelos é o que gera as contradições de gravidade ALTA.
-- Mermaid.
+
-- Riscos.
+## Anti-padrões
-- Plano de execução.
+- ❌ 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

@@ -1,29 +1,25 @@
-# Skill Enterprise
+# SKILL — Monetização (Roadmap)
 
-## Objetivo
+> O que gera (ou pode gerar) receita. Base: `documentação/MAPA-FUNCIONAL-COMPLETO.md` + `AUDITORIA-ESTRATEGICA-MODELAGEM.md`.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## Três camadas de receita (estado real)
-- Mapear impacto.
+1. **Receita da clínica** (operacional): produção, contratos/cobrança, recuperação de glosas.
-- Mapear dependências.
+2. **Receita do profissional** (repasse de comissão).
-- Mapear entidades.
+3. **Receita da PLATAFORMA**:
-- Mapear APIs.
+   - **Tutoria** — MercadoPago + `comissao_pct`: **única automatizada hoje**. ✅
-- Mapear permissões.
+   - **Assinaturas SaaS** (`assinaturas`/`superadmin/pricing`): existe, mas **manual** (sem gateway/recorrência).
-- Validar desktop.
+   - **Locação de salas** (`sala_reservas.valor`): registra valor, **sem captura de pagamento**.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Alavancas (ordem de retorno mais rápido)
-- Preservar cores.
+1. **Gateway na Locação de Salas** — reserva + `valor` já existem; falta cobrança + taxa da plataforma.
-- Preservar estilos.
+2. **Recorrência das Assinaturas SaaS** — base multiempresa + pricing prontos; falta gateway/automação.
-- Preservar identidade visual.
+3. **Marketplace de Profissionais premium** — taxa de match/destaque (hoje só mensagem).
-- Corrigir larguras excessivas.
+4. **Escalar Tutoria** (já fatura).
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Regras
-- Relatório técnico.
+- Toda lacuna de captura deve ser **sinalizada, não presumida como paga**.
-- Relatório negócio.
+- Não misturar as 3 camadas (clínica ≠ profissional ≠ plataforma).
-- Mermaid.
+
-- Riscos.
+## Anti-padrões
-- Plano de execução.
+- ❌ Assumir que reserva/assinatura foi paga. ❌ Construir cobrança fora do modelo Pessoa→Workspace.
+</content>

ScoreOdonto_Skills_Enterprise/FASE_10_ROADMAP/SKILL_Priorizacao.md

@@ -1,29 +1,22 @@
-# Skill Enterprise
+# SKILL — Priorização (Roadmap)
 
-## Objetivo
+> Como decidir a ordem. Critérios concretos para esta stack.
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
 
-## Checklist Obrigatório
+## Critérios (em ordem)
-- Mapear impacto.
+1. **Não quebrar o que funciona** (REGRA Nº 1) — auditar impacto antes.
-- Mapear dependências.
+2. **Segurança / pré-produção** primeiro (abrir a usuários reais exige base segura) — ver `SKILL_Backlog`.
-- Mapear entidades.
+3. **Receita mais rápida com menor esforço** — alavanca onde a infra já existe (ex.: gateway de salas).
-- Mapear APIs.
+4. **Destravar arquitetura** (unificar Pessoa) — alto valor, maior esforço/risco → deliberado, não no susto.
-- Mapear permissões.
+5. **Esforço × risco × reversibilidade** — preferir mudanças aditivas e reversíveis (build-once/rollback).
-- Validar desktop.
-- Validar mobile.
-- Atualizar documentação.
 
-## UI Desktop
+## Fluxo obrigatório por item
-- Preservar cores.
+`Auditoria → Planejamento → Aprovação → Implementação (em DEV/`pgdev`) → Validação → Promoção`.
-- Preservar estilos.
-- Preservar identidade visual.
-- Corrigir larguras excessivas.
-- Aplicar max-width.
-- Evitar telas ultrawide desbalanceadas.
 
-## Entregáveis
+## Recomendação estratégica única (da auditoria)
-- Relatório técnico.
+Assumir a **Pessoa como âncora** e **parar de manter o legado clínica-cêntrico em paralelo** — é a coexistência
-- Relatório negócio.
+dos dois modelos que gera as contradições graves. Mas: só após segurança/produção estável e com aprovação.
-- Mermaid.
+
-- Riscos.
+## Anti-padrões
-- Plano de execução.
+- ❌ Implementar sem auditoria/aprovação. ❌ Priorizar features novas sobre segurança pré-lançamento.
+- ❌ Refator arquitetural grande sem janela e rollback.
+</content>