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>
2026-06-19 19:58:50 +02:00
parent e83af044e0
commit f22e30e6aa
25 changed files with 564 additions and 625 deletions
@@ -1,29 +1,25 @@
-# Skill Enterprise
+# SKILL — Acessibilidade

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Base mínima de a11y, sem regredir a identidade visual. Pragmático para o estado atual.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## Estado atual (honesto)
+O app prioriza densidade/visual; a11y é **básica**. Esta skill fixa o mínimo a manter/melhorar sem
+quebrar o design.

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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.

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execuçã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>
@@ -1,29 +1,22 @@
-# Skill Enterprise
+# SKILL — Dashboard

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Tela inicial por papel. Herda de `SKILL_GridSystem.md` + `SKILL_DesktopWidth.md`.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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.

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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.

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,29 @@
-# Skill Enterprise
+# SKILL — Design System (REGRA RÍGIDA)

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Tokens e padrões visuais REAIS do app. **Preservar a identidade aprovada. Não inventar.**
+> Herda de `SKILL_Containers.md`.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## Stack
+React 19 + **Tailwind 4** + lucide-react (ícones). Sem biblioteca de componentes externa.

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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.

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,23 @@
-# Skill Enterprise
+# SKILL — Responsividade (REGRA RÍGIDA)

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Mobile-first, como o app já é. Herda de `SKILL_GridSystem.md`.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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)`).

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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.

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Módulo Agenda

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Coração operacional. RBAC: capability `'agenda'` (staff clínico, bloqueia paciente).

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## O que é
+Agendar/confirmar/remarcar consultas, controle de presença, anti-overbooking e pendências de reagendamento.

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## Entidades
+`agendamentos`, `agenda_presenca`, `agenda_pendencias`, `interesses_agenda`, `dentistas`+`dentistas_horarios`.

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Módulo CRM (Leads)

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Topo do funil comercial. RBAC: capability `'leads'` (funcionário + dono).

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## O que é
+Captar interessados e **converter** em paciente + agendamento (início do ciclo clínico).

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## Entidades
+`leads` (status: Novo|Convertido|Arquivado), `interesses_agenda`, gera `pacientes` + `agendamentos`.

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,25 @@
-# Skill Enterprise
+# SKILL — Módulo Documentos (Receitas, Exames, Contratos, Mídia)

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Geração e guarda de documentos clínicos/jurídicos e mídia. Cruza Prontuário e Contratos.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## O que é
+Receitas, pedidos de exame, contratos (com assinatura eletrônica) e arquivos (fotos, comprovantes, PDFs).

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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`.

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Módulo Prontuário (Paciente + Ortodontia)

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> O histórico clínico do paciente. Detalhes acessíveis a staff clínico (capability `'agenda'`).

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## O que é
+Prontuário do paciente: dados, família, score, faltas, procedimentos realizados, receitas, pedidos de exame,
+e o tratamento **ortodôntico** completo.

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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).

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,25 @@
-# Skill Enterprise
+# SKILL — Módulo Próteses / GTO

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Controle de laboratório. Liga-se à Comissão pelo **custo lab**. Ver `../FASE_03_PESSOAS/SKILL_Proteticos.md`.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## O que é
+Ordens de Serviço de prótese (produto, dentes, material, custo lab, prazo, entrega) e GTO (guia de tratamento).

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## Entidades
+`protese_os`, `protese_os_evento`, `protese_os_foto`, `protese_produtos`, `protese_laboratorios`;
+GTO legado: `gto_builders`/`gto_items`, `guias_odontologicas`.

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,24 @@
-# Skill Enterprise
+# SKILL — Módulo Radiologia (RX)

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Plugin `rx-scoreodonto`. Radiografias são ODONTOLÓGICAS (papéis odonto, não bio/protético).

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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*`.

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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).

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,26 @@
-# Skill Enterprise
+# SKILL — Módulo Tutoria de Ortodontia

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> **Única receita de plataforma automatizada hoje** (MercadoPago). Ver `../FASE_03_PESSOAS/SKILL_Tutores.md`.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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.

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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`.

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Auditoria de APIs

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Como mapear e evoluir a API sem quebrar consumidores. Complementa `SKILL_Rotas.md`.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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`).

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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
+```

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,27 @@
-# Skill Enterprise
+# SKILL — Auditoria de Banco

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Como inspecionar e mexer no banco sem quebrar. Herda de `../FASE_07_INFRA/SKILL_PostgreSQL.md`.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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`.

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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`).

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Auditoria de Botões

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Como rastrear o que cada botão faz (rota → tabela → fluxo) antes de mexer. Base:
+> `documentação/MAPA-FUNCIONAL-COMPLETO.md` (Etapa 3).

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## Método
+Para cada botão: **rótulo → handler no front → método HTTP/rota → tabela impactada → fluxo a jusante**.

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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 |

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,29 @@
-# Skill Enterprise
+# SKILL — Auditoria de Entidades

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> 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`.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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)

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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`).

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Auditoria de Performance

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Onde olhar antes de otimizar. Sem micro-otimização cega — medir primeiro.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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.

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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
+```

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,36 @@
-# Skill Enterprise
+# SKILL — Auditoria de Permissões (RBAC)

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> 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.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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).

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## `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).

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Diagnósticos (runbook de incidente)

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Passo a passo quando algo quebra. Combina Health, Logs, Deploy Imutável.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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?

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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]`.

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,26 @@
-# Skill Enterprise
+# SKILL — Health Checks

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Como saber se o app está vivo e saudável, sem SSH. Fonte: `documentos-unicos/deploy/versionamento.md`.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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.

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## Como usar
+```bash
+curl -s https://<projeto>/api/health        # produção
+curl -s https://dev.<projeto>/api/health    # dev
+```

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,28 @@
-# Skill Enterprise
+# SKILL — Logs & Auditoria

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Onde está o rastro do que aconteceu. Dois níveis: log de aplicação e trilha de auditoria persistida.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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).

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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).

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,26 @@
-# Skill Enterprise
+# SKILL — Versionamento em Runtime

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> De onde vem a versão exibida e por que ela é confiável. Herda de `../FASE_07_INFRA/SKILL_BuildOnce.md`.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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".

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## Como verificar
+```bash
+curl -s https://<projeto>/api/version   # → vX.Y.Z · <commit> · PROD
+```

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,26 @@
-# Skill Enterprise
+# SKILL — Backlog (Roadmap)

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Itens reais levantados nas auditorias e na sessão de hardening. Não inventar; manter atualizado.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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.

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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`).

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,24 @@
-# Skill Enterprise
+# SKILL — Escalabilidade (Roadmap)

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> O que o modelo suporta em 5 anos e onde estão os gargalos. Base: `AUDITORIA-ESTRATEGICA-MODELAGEM.md`.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## O que JÁ escala (base Pessoa→Vínculo→Workspace)
+- Pessoa em **múltiplos workspaces** (N `vinculos`), workspace pessoal automático, salas/tutoria/marketplace.

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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) |

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,25 @@
-# Skill Enterprise
+# SKILL — Monetização (Roadmap)

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> O que gera (ou pode gerar) receita. Base: `documentação/MAPA-FUNCIONAL-COMPLETO.md` + `AUDITORIA-ESTRATEGICA-MODELAGEM.md`.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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**.

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## 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).

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execução.
+## 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>
@@ -1,29 +1,22 @@
-# Skill Enterprise
+# SKILL — Priorização (Roadmap)

-## Objetivo
-Executar auditoria e evolução sem quebrar funcionalidades existentes.
+> Como decidir a ordem. Critérios concretos para esta stack.

-## Checklist Obrigatório
- Mapear impacto.
- Mapear dependências.
- Mapear entidades.
- Mapear APIs.
- Mapear permissões.
- Validar desktop.
- Validar mobile.
- Atualizar documentação.
+## 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).

-## UI Desktop
- Preservar cores.
- Preservar estilos.
- Preservar identidade visual.
- Corrigir larguras excessivas.
- Aplicar max-width.
- Evitar telas ultrawide desbalanceadas.
+## Fluxo obrigatório por item
+`Auditoria → Planejamento → Aprovação → Implementação (em DEV/`pgdev`) → Validação → Promoção`.

-## Entregáveis
- Relatório técnico.
- Relatório negócio.
- Mermaid.
- Riscos.
- Plano de execuçã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>