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