Arquitetura, ferramentas e técnicas

Visão de contêineres (C4 nível 2)

flowchart LR
    subgraph web ["apps/web · Next.js 14"]
      choose["Escolha de modo<br/>(Criar)"]
      s2d["Estúdio clássico<br/>Konva"]
      s3d["Editor 3D<br/>R3F + drei · import dinâmico"]
      wk["Web Worker<br/>deformação do preview"]
    end

    subgraph api ["apps/order-lifecycle · Fastify"]
      ed["Contexto Editor3D<br/>projetos, revisões"]
      cr["Contexto Créditos<br/>planos, lotes, livro-razão"]
      ai["Adaptador IA<br/>briefing → parâmetros"]
      rules["Validador de regras<br/>(zod + faixas)"]
      q["Fila BullMQ<br/>(Redis existente)"]
    end

    subgraph geo ["apps/geometry · Python (novo)"]
      gapi["FastAPI"]
      kern["trimesh + manifold3d<br/>numpy/scipy"]
    end

    llm[["Claude API"]]
    ip[["InfinitePay"]]
    vol[("Volume de arquivos<br/>(order-lifecycle)")]
    db[("PostgreSQL · Prisma")]

    choose --> s2d & s3d
    s3d <--> wk
    s3d -- "REST" --> ed
    s3d -- "REST" --> cr
    ed --> ai --> llm
    ai --> rules
    ed --> rules
    ed --> q --> gapi --> kern
    gapi --> vol
    cr <-->|"webhook verificado"| ip
    ed & cr --> db

Princípio central: um contrato, duas geometrias

O preview e a fabricação têm exigências opostas: velocidade no navegador, exatidão no servidor. A decisão D7 separa as duas, então a peça que mantém a coerência é o contrato de geometria:

packages/insole-contract/ com o JSON Schema dos parâmetros (schemaVersion, unidades, faixas por plano).
Gerado para TypeScript (zod via json-schema-to-zod) e Python (pydantic via datamodel-code-generator).
Cada revisão grava schemaVersion; o serviço Python sabe gerar todas as versões suportadas.
Testes de ouro: um conjunto de ~20 parâmetros de referência gera, nos dois lados, alturas em pontos de controle e contorno; o CI falha se a diferença passar de 0,5 mm (RNF-3D-05).

Frontend (preview)

Necessidade	Ferramenta	Por quê
Cena 3D	React Three Fiber + @react-three/drei (OrbitControls, Bounds, Environment)	Encaixa no React do `apps/web`; ecossistema maduro
Deformação em tempo real	Malha-base por numeração (GLB, ~10–20 mil triângulos) + deslocamento de vértices por região com pesos pré-calculados	Mover slider = recalcular deslocamentos, sem refazer topologia → 30 FPS no celular
Cálculo fora da thread principal	Web Worker (Comlink)	Interface não trava ao arrastar
Estado do editor	Zustand com middleware de histórico (desfazer/refazer)	Estado fora da árvore React evita re-render a cada quadro
Controles	Componentes do @moldape/ui (shadcn: Slider + Input numérico)	Acessibilidade e consistência; evita Leva/dat.gui na interface final
Mapa de espessura	Shader simples (cor por altura)	Leitura clínica rápida
Carregamento	`next/dynamic` sem SSR, só quando o modo 3D é escolhido	Não pesa no estúdio clássico (RNF-3D-02)
Perfil de desempenho	`r3f-perf`, Lighthouse, teste em aparelho real	Medir o alvo de FPS desde o spike

Backend (order-lifecycle)

Novos contextos na Clean Architecture: editor3d (Projeto3D, Revisão, PropostaIA) e creditos (Plano, Lote, Lançamento).
Créditos como livro-razão (ledger): lançamentos imutáveis COMPRA, RESERVA, CONSUMO, ESTORNO, EXPIRACAO, CONCESSAO. Saldo = soma. Reserva → confirmação garante que falha de geração não cobra.
Idempotência: chave por operação (exportacao:{revisaoId}:{formato}), restrição única no banco.
Direitos (entitlements): função pura direitosDoPlano(plano) → { parametros[], exportar, maxMembros, … } usada em todo endpoint; o frontend recebe o mesmo objeto para desenhar bloqueios.
Fila: BullMQ sobre o Redis que já existe para exportações e geração da malha de pedido; o worker chama o serviço Python por HTTP interno.
IA: adaptador com tool use e saída estruturada no schema do contrato; prompt com as regras clínicas da Moldapé; sem dados identificáveis do paciente; registro de modelo, versão do prompt, tokens e latência.

Serviço de geometria (Python)

Necessidade	Ferramenta
API	FastAPI + pydantic (modelos gerados do contrato)
Malha	trimesh (I/O, verificação estanque, medidas) + manifold3d (booleanos robustos para peças e copo)
Superfícies	numpy/scipy (interpolação por splines das alturas por região sobre o contorno)
Exportação	STL binário por pé; 3MF com volumes modificadores por zona (`lib3mf` ou escrita do XML)
Ficha técnica	Cortes e cotas em SVG → PDF (reaproveitar o padrão A4 dos PDFs atuais)
Testes	pytest + testes de ouro compartilhados com o frontend
Deploy	Novo serviço no Coolify (Nixpacks detecta Python), sem exposição pública

Modelo de domínio (proposta)

erDiagram
    USER ||--o{ DRAFT : cria
    DRAFT ||--o| PROJETO3D : "modo EDITOR_3D"
    PROJETO3D ||--|{ REVISAO : tem
    REVISAO }o--o| PROPOSTA_IA : "baseada em"
    REVISAO ||--o{ EXPORTACAO : gera
    ORGANIZACAO ||--o{ MEMBRO : tem
    USER ||--o{ MEMBRO : participa
    PLANO ||--o{ LOTE_CREDITO : origina
    LOTE_CREDITO ||--o{ LANCAMENTO : movimenta
    USER ||--o{ LOTE_CREDITO : "titular (individual)"
    ORGANIZACAO ||--o{ LOTE_CREDITO : "titular (clínica)"
    REVISAO {
      int numero
      string schemaVersion
      json parametrosEsq
      json parametrosDir
      json ajustesValidador
      string aprovadoPor
    }
    PROPOSTA_IA {
      json briefingAnonimo
      json parametros
      json justificativas
      string modelo
      string versaoPrompt
    }
    LOTE_CREDITO {
      int quantidade
      date expiraEm
      string pagamentoId
    }
    LANCAMENTO {
      enum tipo
      int valor
      string chaveIdempotencia
    }

Alternativas consideradas

Tema	Escolhida	Descartada	Motivo
Motor 3D web	R3F	Babylon.js, Three puro	R3F integra com React e o time já usa React
Geometria de fabricação	Python (trimesh/manifold3d)	Mesmo kernel TS/WASM nos dois lados	Decisão D7: ecossistema Python mais maduro para malha e verificação; custo é manter duas implementações (mitigado pelo contrato + testes de ouro)
CAD paramétrico	Malha + splines	CadQuery/OpenCascade	B-rep é excessivo para palmilha; pode entrar se a fábrica exigir STEP
Lattice	Zonas no 3MF (fatiador aplica)	Treliça gerada como malha	Arquivo menor, geração rápida; depende de validar fatiadores (spike)
Cobrança	Créditos + ledger	Assinatura	D3; sem recorrência na InfinitePay hoje
IA	Propõe + explica	Copiloto conversacional	Menor custo e risco no MVP; copiloto pode vir depois

Riscos específicos

ID	Risco	Prob.	Impacto	Mitigação
R3D-01	Preview diverge do STL	Média	Alto	Contrato único, testes de ouro no CI, revisão mostra “malha verificada”
R3D-02	IA propõe algo clinicamente inadequado	Média	Alto	Validador de faixas, justificativas visíveis, confirmação do profissional, auditoria, conjunto de avaliação
R3D-03	Webhook falso libera créditos	Alta se R-01 não for corrigido	Crítico	Corrigir R-01 antes de vender; conciliação manual na fase beta
R3D-04	FPS baixo em celulares	Média	Médio	Spike S-1 com aparelho real; malha-base com poucos triângulos; deformação em Worker
R3D-05	Contorno por medidas não serve a pés atípicos	Alta	Médio	Aviso “contorno estimado”; prioridade para importar plantigrafia
R3D-06	Enquadramento regulatório e responsabilidade de arquivos exportados	Desconhecida	Alto	Parecer antes do lançamento; termos de uso; exportação só para profissional com registro
R3D-07	Custo de tokens maior que o previsto	Baixa	Médio	Medir custo por proposta no beta; cache por briefing idêntico; modelo menor se o conjunto de avaliação permitir
R3D-08	Nova stack Python sem dono	Média	Médio	Serviço pequeno e sem estado, README, testes, dono definido na Nós Tecnologia

Desenvolvido e documentado por
Nós Tecnologia · Desenvolvimento Criativo