scoreodonto.com/doc/RX_ARQUITETURA_scoreodonto-rx-clientWindows-wasabi.md

Arquitetura RX — scoreodonto.com → rx.scoreodonto.com → clientWindows.exe → Wasabi

Documento de revisão / engenharia reversa (gerado em 2026-06-12, sem alterar código). Fonte da verdade: rx.scoreodonto.com/dental-server (servidor) lido linha a linha. O .exe do client Windows está em repo separado (Gitea) — aqui seu comportamento é descrito pelo protocolo que o servidor expõe/aceita (Socket.IO + machine_token).

---

1. Visão geral (quem é quem)

┌──────────────────────────┐         ┌───────────────────────────────────────────┐
│  CLÍNICA (PC com sensor)  │         │        rx.scoreodonto.com (dental-server)  │
│                          │         │        Node + Express + Socket.IO          │
│  clientWindows.exe       │  WSS    │                                            │
│  - captura RX do sensor  │────────▶│  io.on('send-image')                       │
│  - auth: machine_token   │ socket  │   → storage.saveImage()                    │
│  - emite 'send-image'    │  .io    │   → INSERT images (Postgres dental_images) │
└──────────────────────────┘         │                                            │
                                     │  HTTP API (/api/images, /api/admin/...)    │
┌──────────────────────────┐  HTTPS  │   - lista pacientes/imagens                │
│  scoreodonto.com (plugin)│────────▶│   - cria devices (/api/admin/clinics)      │
│  - superadmin: config     │  proxy  │                                            │
│    global (rx_url+token)  │ no nosso│            │ saveImage / getImageBuffer    │
│  - backend proxeia leitura│ backend │            ▼                              │
└──────────────────────────┘         │   ┌─────────────────────────────────────┐ │
                                     │   │ WASABI (S3) bucket                   │ │
                                     │   │ key: clinic/client/patient/file.png  │ │
                                     │   └─────────────────────────────────────┘ │
                                     │   (+ cache local em ./uploads como fallback)│
                                     └───────────────────────────────────────────┘

Quatro peças:

1. clientWindows.exe — instalado no PC da clínica; captura a radiografia e envia via Socket.IO.
2. rx.scoreodonto.com / dental-server — recebe, persiste metadados no Postgres e o binário no Wasabi; serve listagens e imagens.
3. Wasabi — storage S3-compatível (objeto = clinic/client/patient/arquivo).
4. scoreodonto.com (plugin RX) — administra/visualiza via API, com token global (nosso trabalho recente).

---

2. Banco de dados do RX (Postgres dental_images, em database.js)

Tabela	Campos-chave	Papel
clinics_devices	clinic_name, email (UNIQUE), password_hash, pc_name, machine_token (UUID UNIQUE), is_active, last_ip	1 linha por (clínica, PC). Credencial do client Windows. Criada por POST /api/admin/clinics.
images	image_guid, patient_name, client_name (=PC), clinic_name, filename, thumb_filename, doctor, remark, enabled, created_at	1 linha por radiografia. Filtros de leitura hoje: client_name e patient_name (e agora clinic_name, ver §7).
users	username, email, password_hash, is_admin	Usuários admin/web (painel).
api_tokens	name, token	Tokens estáticos de API (viram admin, não expiram).
system_config	key, value	Key-value. Guarda wasabi_config.
gtos / gto_images	gto_number, patient_name, …	Documentos GTO por paciente.

---

3. clientWindows.exe — como envia os RX (protocolo)

O envio NÃO é HTTP de upload; é Socket.IO (server.js):

1. Conexão / auth do socket (io.use(...), server.js:823):

   • O client conecta com handshake.auth.token = machine_token (UUID gerado no cadastro do device).
   • Regex confirma UUID → busca em clinics_devices → se is_active, autoriza.
   • Opcional: se email+password também vierem, são validados (compat).
   • Resultado: socket.user = { role:'client_device', clinicId, clinicName, pcName } vindos do registro do device (não do client). Atualiza last_ip.
   • Também aceita CLIENT_API_KEY (sensor legado) e JWT (painel web / app novo).

2. Envio da imagem — DIRECT UPLOAD pro Wasabi (fluxo REAL de produção): Confirmado pelos logs do client (🌐 Fazendo Direct Upload pro Wasabi (Bypass VPS)). O binário NÃO trafega pela VPS — vai direto pro Wasabi via URL pré-assinada:

   1. Client monitora C:\ProgramData\RF\Dental Sensor\Images (Chokidar) e gera thumb local.
   2. socket.emit('request-presigned-urls', { metadata:{guid}, patientData:{name,...} }) → servidor responde { originalUrl, thumbnailUrl, filename, thumbFilename } (storage.getUploadPresignedUrl, server.js:1218). A key do Wasabi já é fixada aqui.
   3. Client faz PUT direto no Wasabi (original + thumb) usando as presigned URLs.
   4. socket.emit('image-upload-direct', {...}) → servidor só grava os metadados em images (server.js:1258). Não recebe os bytes.
   • Em ambos (2 e 4) o eixo de clínica é o MESMO: clinicName = socket.user?.clinicName || clientInfo?.clinicName || 'Clínica não identificada' → vem do clinic_name do device (machine_token). clientName = PC; patientName = paciente.

⚙️ Existe também o caminho legado socket.on('send-image') (base64 pela VPS, server.js:1031) e POST /api/images/upload (upload manual). Mas o client Windows real usa o Direct Upload. Há ainda POST /api/client/login (JWT 2h client_device) para fluxos HTTP.

3.1. ⚠️ Estado real dos dados (2026-06-12, banco compartilhado dev+prod):

• 1 device: clinic_name="Consultt Clinic", pc="RX".
• images: 2552 imgs / 503 pacientes com clinic_name = NULL (subiram antes do clinic_name ser setado → Wasabi key desconhecido/RX/paciente/…) + 222 imgs / 37 pacientes sob "Consultt Clinic". → A maioria das radiografias está "órfã" de clínica.

---

4. Wasabi storage (storage.js) — a lógica que NÃO pode quebrar

Config: lida do banco em system_config.wasabi_config ({ wasabiAccessKey, wasabiSecretKey, wasabiBucket, wasabiRegion, wasabiEndpoint }), carregada por loadConfigFromDb() (server.js:1428, e ao salvar em routes/system.js). SDK: @aws-sdk/client-s3 com forcePathStyle:true, endpoint s3.wasabisys.com.

Chave do objeto (CRÍTICO):

key = sanitize(clinic_name) / sanitize(client_name) / sanitize(patient_name) / filename

sanitizePathSegment troca /\?#%*:"<>| por _. (storage.js:103, 120, 153, 220, 298, 340, 366, 414)

saveImage (storage.js:139):

1. grava local em ./uploads/<filename>;
2. se Wasabi ativo → Upload (lib-storage) para a key acima;
3. se subiu OK → apaga o local (Wasabi vira fonte). Se falhar → mantém local (fallback).

getImageBuffer (storage.js:190): local primeiro → senão Wasabi (key vinda dos args ou de um SELECT em images por filename/thumb_filename) → fallback key na raiz do bucket (arquivos legados) → cacheia local. getImageUrl/getDownloadPresignedUrl geram URL assinada (1h).

deleteImage: apaga local (uploads + processed) e a key no Wasabi (+ key raiz, redundância legada).

Wasabi é opcional: sem config, tudo funciona só em disco local. Por isso "desligar/errar" a config do Wasabi não derruba o servidor — só muda onde o binário vive.

---

5. Autenticação — matriz completa

Quem	Como autentica	Onde
client Windows (socket)	machine_token (UUID) — suficiente; email+senha opcionais	io.use server.js:823
client Windows (HTTP)	POST /api/client/login → JWT 2h role:client_device	client-auth.js
sensor legado	CLIENT_API_KEY (rf-dental-secure-key-2026 default)	io.use / x-api-key
admin / painel web	usuário+senha → JWT 7d (is_admin) OU api_token estático	auth.js authenticateToken
público	sem auth	só GET /api/images/:id/thumbnail

authenticateToken (auth.js:12): tenta JWT; se falhar, procura o token em api_tokens → se achar, injeta um admin mock (is_admin:true). É isso que o scoreodonto usa (token global) para chamar /api/admin/clinics e as listagens.

---

6. Integração scoreodonto.com (plugin RX) — estado atual

• Config GLOBAL (só superadmin) em settings.rx_config_global = { rx_url, api_token } no backend do scoreodonto. O api_token é um token de api_tokens do RX (admin, não expira).
• Criar PC (POST /api/rx/devices no nosso backend) → POST {rx_url}/api/admin/clinics com clinic_name = clinicaId (a clínica do scoreodonto) + pc_name + email/senha por PC. Devolve o machine_token que vai no client Windows.
• Ler (GET /api/rx/patients, /api/rx/images) → proxeia /api/images/patients e /api/images/by-patient com ?clinic=<clinicaId> + Bearer api_token. Isolamento por vínculo.
• Thumbnails: públicos, carregados direto de rx_url.

---

7. ⚠️ Pontos de atenção para NÃO quebrar o que já funciona

1. clinic_name é o eixo de tudo (Wasabi key + filtro de listagem). Os clients Windows já em produção sobem imagens com o clinic_name que foi gravado no cadastro do device deles (provavelmente o nome legível da clínica).

2. Descompasso scoreodonto × RX: o plugin novo cria device com clinic_name = clinicaId (ID opaco do scoreodonto). Logo:

   • Imagens antigas estão sob clinic_name = <nome legível> no Wasabi e no images.
   • Imagens novas (via plugin) ficariam sob clinic_name = <clinicaId>.
   • Filtrar por ?clinic=<clinicaId> não acha as antigas (clinic_name diferente) — mas não quebra o envio existente (cada client continua com o seu clinic_name).
   • → Para enxergar clínicas já ativas, é preciso um mapeamento clinicaId ↔ clinic_name atual (tabela/coluna de-para), NÃO renomear objetos no Wasabi (arriscado e custoso).

3. Hierarquia desejada (4 níveis) × Wasabi (3 níveis):

   • Desejado: scoreodonto / consulttclinic@gmail.com / clinicaID / paciente.
   • Wasabi real: clinic_name / client_name / paciente / arquivo (3 níveis, sem o nível "conta").
   • A "conta-mestre" (email) é identidade de auth (api_token/users.email), não faz parte da key.
   • Realizar 4 níveis exigiria mudar o esquema de key — risco alto para objetos já gravados. Caminho seguro: manter 3 níveis e usar clinic_name = clinicaId só para o que for novo, com de-para para o legado.

4. npm run dev do RX = node server.js (sem nodemon) → mudanças no dental-server exigem docker restart rx_dev_api. (Em prod o deploy é via deploy-prod.sh / webhook.)

5. Não tocar: io.on('send-image'), storage.saveImage/getImageBuffer, o esquema da key, nem o cadastro de clinics_devices dos PCs que já enviam. Toda evolução deve ser aditiva (novos endpoints/colunas), preservando o caminho do client Windows.

---

8. Endpoints-chave (referência rápida)

Endpoint	Auth	Uso
WSS send-image	machine_token	client Windows envia RX
POST /api/admin/clinics	admin/api_token	cria device (clinic_name, email, pc_name) → machine_token
GET /api/admin/clinics	admin/api_token	lista devices
GET /api/images?clinic=&client=&search=	admin	lista imagens (filtros)
GET /api/images/patients?clinic=&search=&page=	admin	pacientes agrupados
GET /api/images/by-patient?name=&clinic=	admin	imagens de um paciente
GET /api/images/:id/thumbnail	público	miniatura
GET /api/version · /download-client	público	versão / instalador do client
POST /api/auth/login → JWT · POST /api/auth/tokens → api_token	admin	obter credenciais de API

---

9. Multi-tenant 2 níveis: tenant_id / clinica_id (implementado 2026-06-12, DEV)

Hierarquia (espelha o scoreodonto, que tem conta multi-clínica no plano): tenant_id (conta/dono = usuarios.id "u_…") / clinica_id (clinicas.id "c_…") / pc / paciente / arquivo. O tenant_id é resolvido pelo vínculo dono* da clínica (owner_id está vazio hoje). Para a Consultt: tenant_id=u_1780870994865_3876n (Rui Cesar) / clinica_id=c_1780871001549_koqa3o.

• Colunas tenant_id e clinica_id em clinics_devices e images (+índices); clinic_name vira rótulo. Backfill: device + 2776 imgs → tenant+clínica da Consultt.
• Verificado: ?tenant_id= (conta) e ?clinica_id= (clínica) isolam; tenant/clínica inexistente → 0.
• scoreodonto: cadastro de device resolve+envia tenant_id; proxy de leitura libera conta (tenant_id = própria conta do dono) ou clínica (clinica_id com vínculo).

(Resto desta seção descreve a base por clinica_id.)

• Schema RX: coluna clinica_id em clinics_devices e images (+ índices). clinic_name vira só rótulo legível. Backfill: device + 2776 imgs existentes → c_1780871001549_koqa3o.
• Fluxo: POST /api/admin/clinics grava clinica_id; o socket (machine_token) resolve socket.user.clinicaId do device; image-upload-direct (e o legado send-image) gravam images.clinica_id. Wasabi key ainda é clinic_name/… (mudança física = fase de reconciliação, pendente da resposta sobre os PNGs de origem).
• Isolamento: listagens (/api/images, /patients, /by-patient, /unique-clinics) filtram por ?clinica_id=. Verificado: tenant real retorna dados, tenant inexistente → 0.
• scoreodonto: /api/rx/* envia/filtra por clinica_id (e clinic_name=nome_fantasia no cadastro); proxy de leitura valida vínculo (_rxClinicScopeOk) → 403 fora do tenant.
• Pendente: reconciliação física no Wasabi (clinica_id/…) + remoção do send-image legado (após confirmar que nenhum .exe em campo usa versão pré-Direct-Upload).

TL;DR

O client Windows manda RX por Socket.IO autenticado por machine_token; o servidor grava metadados no Postgres e o arquivo no Wasabi sob clinic_name/client_name/patient_name/arquivo. O scoreodonto administra isso com um token de API global, filtrando por clinic_name = clinicaId. O risco de integração está em clinic_name: alinhar o ID do scoreodonto com o clinic_name que os PCs já usam, sem renomear nada no Wasabi nem mexer no caminho de envio.