6.1 Dispositivo QFace (Digicon/Suprema)

Funções da DLL utilizadas:

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:

6.3 Windows Service Manager (NSSM)

7. TRATAMENTO DE ERROS E EXCEÇÕES

Sistema de Logs

Aplicativo Electron (insoft-qface-app)

API Windows (insoft-qface-win-api)

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:

🧪 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

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

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