scoreodonto.com/doc/PROVEDOR-PROTESE-DECISAO.md

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.