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

pessoa_tipo PF/PJ, CNPJ (expor documento), Equipe/Técnicos (estende proteseOsAccesso por vínculo).

FASE 5 — Ecossistema

Marketplace transacional, Score, indicadores, ranking (sobre os dados das fases 2-4).

Acoplamentos: PF/PJ só com a Fase 4 (equipe), senão é campo morto. Score só na Fase 5 (precisa volume).