Documentação Técnica App + API REST - Parte 2

[Gilberto Júnior]

6. INTEGRAÇÕES EXTERNAS

6.1 Dispositivo QFace (Digicon/Suprema)

Item	Detalhe
Protocolo	TCP/IP proprietário (SDK C/C++)
DLL	QFM_SDK_DLL.dll (32-bit e 64-bit)
IP padrão	172.16.110.6
Porta padrão	12120
Modo	Binário (asciiMode = false)
Configuração	config/application.json → deviceIp, devicePort, asciiMode

Funções da DLL utilizadas:

Função C	Wrapper TypeScript	Descrição
QF_InitSocket	initSocket()	Conecta ao dispositivo
QF_CloseSocket	closeSocket()	Desconecta
QF_DeleteAll	deleteAllTemplates()	Remove todos os templates do device
QF_EnrollImage	enrollImage(userID, imageBuffer)	Envia imagem e gera template
QF_ReadTemplate	readTemplate(userID)	Lê template gerado
QF_ScanTemplate	scanTemplate()	Captura template via câmera do device
QF_GetFirmwareVersion	getDeviceInfo()	Lê versão de firmware
QF_GetSysParameter	getDeviceInfo()	Lê número de série e build

Pontos de atenção:

• A DLL não é thread-safe → usar sempre o mutex
• O dispositivo precisa estar na mesma rede local (IP acessível)
• Firewall do Windows pode bloquear a porta 12120

---

6.2 API Externa (Webhook de saída)

Descrição simplificada (Suporte):

O sistema pode enviar automaticamente os templates gerados para um sistema externo (ERP, controle de acesso, etc.) via HTTP.

Descrição técnica:

Item	Detalhe
Configuração	externalApiEnabled, externalApiUrl, externalApiUser, externalApiPassword
Formato de payload	Configurável via payloadTemplate (suporta variáveis: {{biometric_data}}, {{user_id}}, {{timestamp}})
Endpoints customizados	apiEndpoints (JSON com lista de endpoints)
Backup	Registros mantidos por backupRegistersDays dias (padrão: 7)

---

6.3 Windows Service Manager (NSSM)

Item	Detalhe
Ferramenta	NSSM v2.24 (Non-Sucking Service Manager)
Localização	nssm/win32/ e nssm/win64/
Uso	Registra insoft-qface-win-api.exe como serviço do Windows
Nome do serviço	insoft-qface-win-api (padrão)
Variáveis de ambiente	CONFIG_PATH, QFACE_DLL_PATH, SHARED_I18N_PATH configuradas no serviço

---

7. TRATAMENTO DE ERROS E EXCEÇÕES

Sistema de Logs

Aplicativo Electron (insoft-qface-app)

Aspecto	Detalhe
Biblioteca	electron-log
Arquivo de log	<cwd>/logs/AppLog.log
Níveis	info, warn, error, debug
Acesso	Dashboard → aba Logs → "Ver Logs"

API Windows (insoft-qface-win-api)

Aspecto	Detalhe
Arquivo de log	<exeDir>/logs/AppLog.log
Log de serviço	<exeDir>/logs/service.log
Log de erros	<exeDir>/logs/error.log
HTTP Requests	Morgan (combined format) no console

Proteção contra crashes

O sistema possui handlers globais para evitar que erros inesperados derrubem o aplicativo:

// No Electron (main.ts) e na API (start.ts / server/index.ts)
process.on('uncaughtException', (error) => {
  logger.error('Uncaught Exception:', error);
  // NÃO encerra o processo — mantém o app rodando
});

process.on('unhandledRejection', (reason) => {
  logger.error('Unhandled Rejection:', reason);
  // NÃO encerra o processo
});

Códigos de mensagem de erro

Todos os erros retornados pela API usam o sistema de mensagens codificadas (repp.message.X). A tabela completa está em shared/i18n/en-US.json e shared/i18n/pt-BR.json.

Erros mais comuns em produção:

Código	Constante	Mensagem (PT-BR)	Causa
repp.message.24	FAILED_CONNECT_DEVICE	Falha ao conectar no dispositivo	IP/porta errado ou dispositivo offline
repp.message.55	API_WINDOWS_SERVICE_NOT_INSTALLED	Serviço Windows não instalado	API não foi instalada como serviço
repp.message.31	CAPTURE_TIMEOUT	Timeout na captura	Usuário não posicionou rosto a tempo
repp.message.27	INVALID_IMAGE	Imagem inválida	Imagem não contém face detectável
repp.message.43	TEMPLATE_SCAN_FAILED	Falha na captura do template	Câmera do QFace com problema

---

🧪 8. CENÁRIOS COMUNS DE SUPORTE

Problema 1: "API não está rodando" / Dashboard mostra serviço parado

Sintoma: Status da API aparece como "Parado" ou "Não instalado" na tela do Dashboard.

Possíveis causas:

• O serviço insoft-qface-win-api não está instalado
• O serviço foi interrompido manualmente
• Alguma atualização removeu o serviço

Como investigar:

1. Abrir o Gerenciador de Serviços do Windows (services.msc)
2. Procurar por Insoft QFace Win API
3. Verificar logs: <pasta_instalação>\logs\service.log

Como resolver:

• Se o serviço não existe: usar o botão "Instalar Serviço" no Dashboard
• Se o serviço existe mas está parado: clicar em "Iniciar" no Dashboard ou no services.msc
• Se há erro: verificar error.log para detalhes

---

Problema 2: Falha ao conectar no dispositivo QFace

Sintoma: Erros de conversão com mensagem repp.message.24 ou "Falha ao conectar no dispositivo".

Possíveis causas:

• Dispositivo QFace desligado ou sem energia
• IP ou porta errada na configuração
• Firewall bloqueando a porta 12120
• Dispositivo em outra sub-rede

Como investigar:

1. Verificar se o dispositivo está ligado (LEDs acesos)
2. Testar ping para o IP configurado: ping 172.16.110.6
3. Verificar config/application.json → campos deviceIp e devicePort
4. Verificar log: procurar por [QFace SDK] ou QF_ERR_CANNOT_CONNECT_SOCKET

Como resolver:

• Corrigir IP/porta nas Configurações do aplicativo
• Verificar regras do Firewall do Windows para porta 12120
• Confirmar que o dispositivo e o PC estão na mesma rede

---

Problema 3: Imagens não geram template (qualidade ruim)

Sintoma: Retorno com error: repp.message.27 (imagem inválida) ou qualidade muito baixa.

Possíveis causas:

• Imagem não contém rosto humano reconhecível
• Resolução da imagem muito baixa
• Imagem com iluminação inadequada (muito escura, muito clara, contra-luz)
• Formato de imagem incompatível

Como investigar:

1. Verificar o campo quality no retorno (valores abaixo de 40 indicam baixa qualidade)
2. Revisar logs da API: [biometricTemplateController] → enrollImage result

Como resolver:

• Garantir imagens com rosto frontal, bem iluminado, mínimo 200x200 pixels
• Verificar que o formato é JPEG ou PNG

---

Problema 4: Câmera não funciona para captura ao vivo

Sintoma: Tela de captura abre mas câmera não inicializa ou mostra tela preta.

Possíveis causas:

• Permissão de câmera negada no Windows
• Driver da câmera do QFace não instalado
• Outro aplicativo está usando a câmera

Como investigar:

1. Verificar Configurações do Windows → Privacidade → Câmera
2. O aplicativo possui botão "Abrir Configurações de Câmera" nas Configurações
3. Verificar log: [useCamera] ou [QFace SDK]

Como resolver:

• Ativar permissão de câmera para o aplicativo
• Reinstalar drivers do dispositivo QFace
• Fechar outros aplicativos que possam estar usando a câmera

---

Problema 5: WebSocket desconectado — eventos não chegam à interface

Sintoma: A tela de conversão não atualiza, ou a captura não é iniciada apesar da requisição ter chegado à API.

Possíveis causas:

• API rodando mas porta 3133 bloqueada por firewall
• API reiniciou mas WebSocket do Electron ainda não reconectou

Como investigar:

1. Verificar log do Electron: procurar por [WebSocket]
2. Verificar se o serviço da API está rodando (porta 3133)

Como resolver:

• Reiniciar a API pelo Dashboard (botão "Reiniciar API")
• O WebSocket reconecta automaticamente em até 5 segundos

---

Problema 6: Erro de permissão / instalação de serviço falha

Sintoma: Botão "Instalar Serviço" retorna erro de permissão.

Possíveis causas:

• Aplicativo não está rodando como Administrador
• Antivírus bloqueando criação de serviço

Como resolver:

• Fechar e reabrir o aplicativo com "Executar como Administrador" (o instalador já solicita isso automaticamente)
• Adicionar exceção no antivírus para nssm.exe e insoft-qface-win-api.exe

---

9. BOAS PRÁTICAS E OBSERVAÇÕES

Padrões utilizados no código

Padrão	Onde é usado	Motivo
Mutex assíncrono	QFaceMutex na API	DLL não é thread-safe
IPC com Context Bridge	preload.ts	Segurança Electron: isola renderer do Node.js
Mensagens codificadas	Todo o sistema (MSG.XXX)	Internacionalização e rastreabilidade
Polling de saúde	startApiServer()	Garante que a API está realmente respondendo antes de sinalizar como ready
Fila de eventos	EventQueue	Evita perda de eventos se Electron conectar depois da API emitir
Context API React	ConfigContext, ThemeContext	Evita prop drilling e centraliza estado global
Reconexão WebSocket	reconnectionAttempts: Infinity	Alta disponibilidade da comunicação em tempo real

Cuidados ao modificar o sistema

️ DLL nativa (QFM_SDK_DLL.dll)

• NUNCA fazer chamadas concorrentes à DLL sem usar o qfaceMutex
• A DLL é 32-bit em alguns ambientes — verificar compatibilidade do processo
• Alterações nas assinaturas de função precisam ser sincronizadas com qface-sdk.ts

️ Arquivo application.json

• É o único ponto de configuração compartilhado entre Electron e API
• Tanto o Electron (main.ts) quanto a API (configManager.ts) leem este arquivo
• Ao salvar configurações pela UI, o Electron atualiza o arquivo e notifica a API via HTTP (/internal/config/update)
• Em produção, o arquivo fica na pasta do instalador, NÃO dentro do ASAR

️ Mensagens i18n

• Nunca usar strings literais de erro — sempre usar MSG.NOME_DA_CONSTANTE
• Ao adicionar nova mensagem: adicionar em message-codes.json, en-US.json E pt-BR.json
• Executar npm run validate:i18n para verificar consistência

️ Gerenciamento de janela

• A função bringWindowToFront() usa sequência específica para garantir que a janela apareça acima de outros aplicativos no Windows
• O setTimeout(180ms) é intencional para estabilizar o foco após setAlwaysOnTop

️ Build e empacotamento

• O electron-builder.json define que o instalador exige privilégios de Administrador (requireAdministrator)
• A API .exe é copiada para build-api/ antes do build do Electron
• O NSSM é incluído para ambas as arquiteturas (win32/win64) e selecionado automaticamente

Portas utilizadas pelo sistema

Porta	Protocolo	Serviço	Configurável?
3333	HTTP	API REST principal	Sim (serverPort no config)
3133	HTTP/WebSocket	Socket.IO (eventos em tempo real)	Não (fixo no código)
12120	TCP	Dispositivo QFace	Sim (devicePort no config)
4443	HTTPS	API REST (modo SSL)	Não (fixo, fallback)

Estrutura do application.json (referência completa)

{
  "deviceIp": "172.16.110.6",       // IP do dispositivo QFace
  "devicePort": 12120,               // Porta TCP do dispositivo
  "asciiMode": false,                // Protocolo binário (false) ou ASCII (true)
  "apiKey": "<uuid>",                // Chave de autenticação da API REST
  "useSsl": false,                   // Habilitar HTTPS na API
  "certFiles": null,                 // Caminho dos arquivos de certificado SSL
  "useCertificate": false,           // Usar certificado SSL customizado
  "backgroundMode": true,            // API roda em segundo plano
  "saveTemplates": true,             // Salvar templates em disco
  "saveImages": true,                // Salvar imagens em disco
  "serverIp": "localhost",           // IP de escuta da API REST
  "serverPort": 3333,                // Porta HTTP da API REST
  "theme": "dark",                   // Tema da UI: "dark" | "light"
  "qfaceCapture": true,              // Habilitar captura via câmera QFace
  "externalApiEnabled": false,       // Enviar templates para API externa
  "externalApiUrl": "",              // URL da API externa
  "externalApiUser": "",             // Usuário da API externa
  "externalApiPassword": "",         // Senha da API externa
  "apiEndpoints": "[]",              // Endpoints customizados (JSON)
  "payloadTemplate": "...",          // Template do payload de saída
  "backupRegistersDays": 7           // Dias de retenção de registros
}

---

Documentação gerada em Abril de 2026 — Insoft4 Informática LTDA