Explicação simplificada (Suporte):

O usuário altera as configurações (ex: intervalo de leitura para 500ms, prefixo "ID:"). Ao salvar, as mudanças são aplicadas imediatamente sem reiniciar o sistema.

Explicação técnica (Dev):

[Frontend] SettingsForm.onSubmit(data)
  │
  ├─► PUT /settings/reader (axios)
  │     │
  │     CardService.updateReaderSettings(payload)
  │       ├─ ReaderSettingsStore.update(payload) → normaliza → grava JSON em disco
  │       └─ DeviceManager.applyReaderSettings(updated)
  │             └─ DigiconDG710Reader.applySettings(settings)
  │                   ├─ pollingMs = settings.intervalMs
  │                   ├─ continuousRead = settings.continuousRead
  │                   └─ reinicia loop de polling (clearTimeout + scheduleNextPoll)
  │
  └─► window.readerApi.syncRuntimeSettings(updated)  [IPC]
        └─ ipcMain: "reader-runtime-settings:update-cache"
              └─ runtimeSettingsCache = { ...cache, ...payload }
                    (usado pelo auto-paste: appendNewLine)

Fluxo 4: Reconexão de Leitores

Explicação simplificada (Suporte):

Se o leitor parar de responder, o usuário pode clicar em "Reconectar leitores" no menu da bandeja. O sistema faz disconnect e connect novamente automaticamente.

Explicação técnica (Dev):

[Tray menu: "Reconectar leitores"]
  │  ou [Frontend: botão Reconectar]
  ▼
performReconnectReaders()
  │
  ├─► GET /readers → lista todos os leitores
  │
  └─► Para cada reader (em paralelo):
        POST /readers/disconnect { key }
        POST /readers/connect    { key }
        POST /readers/start      { key }

Fluxo 5: Manutenção Automática de Leitores

Explicação simplificada (Suporte):

A cada 1,5 segundos, o sistema verifica se o leitor está conectado e escutando. Se estiver desconectado, tenta reconectar sozinho.

Explicação técnica (Dev):

setInterval(service.maintainReaders, 1500ms)
  │
  └─► CardService.maintainReaders()
        Para cada readerKey:
          reader.getStatus()
          ├─ !connected → reader.connect()
          └─ connected + !listening → reader.startListening()
        Erros → logger.debug (não interrompem)

️ 5. ROTINAS E MÉTODOS IMPORTANTES

bootstrap() — server.ts

Descrição simplificada:

Inicializa toda a API: verifica instância única, cria componentes, monta rotas e inicia o servidor.

Descrição técnica:

• Localização: insoft-readers-api/src/server.ts
• Fluxo: ensureSingleApiInstance() → instância de todos os serviços → monta Express → escuta na porta
• Parâmetros: nenhum (usa variáveis de ambiente)
• Retorno: Promise<void>
• Possíveis saídas de emergência: process.exit(0) (duplicata), process.exit(1) (falha crítica)

runPollingTick() — DigiconDG710Reader.ts

Descrição simplificada:

O loop que "pergunta" ao hardware a cada N milissegundos se há um cartão presente.

Descrição técnica:

• Localização: DigiconDG710Reader (método privado)
• Usa setTimeout recursivo (não setInterval), garantindo que o próximo tick só ocorre após o atual terminar
• Gerencia estado wasCardPresent para evitar eventos duplicados no modo não-contínuo
• Em caso de erro: registra em lastError e continua o polling no próximo tick
• Parada: stopListening() define pollingActive = false; o finally do tick detecta isso e não agenda o próximo

readMifareCard() — DigiconFacade.ts

Descrição simplificada:

Lê os bytes do cartão físico e os converte para um número decimal (o "código do cartão").

Descrição técnica:

• Localização: DigiconFacade
• Parâmetros: handle: number → identificador do canal conectado
• Retorno: { cardId: string; rawHex: string } | null
• Algoritmo: buffer de 4 bytes → leitura em ordem decrescente de índice (big-endian) → hex string → BigInt(0x${rawHex}).toString(10)
• Exemplo: bytes [0x4E, 0x61, 0xBC, 0x00] → rawHex "00BC614E" → cardId "12345678"
• Em mock mode: retorna número aleatório de 8 dígitos

applyRuntimeSettingsToEvent() — CardService.ts

Descrição simplificada:

Adiciona o prefixo e o sufixo configurados ao código do cartão antes de distribuí-lo.

Descrição técnica:

• Localização: CardService (método privado)
• Parâmetros: event: CardReadEvent
• Retorno: novo CardReadEvent com cardId = prefix + originalCardId + suffix
• Não modifica o evento original (imutabilidade via spread {...event})
• Exemplo: prefixo "ID:", sufixo "", cardId "12345678" → "ID:12345678"

ensureApiRunning() — ApiProcessManager.ts

Descrição simplificada:

Garante que a API está disponível antes de abrir a janela. Tenta todas as formas de iniciá-la.

Descrição técnica:

• Localização: insoft-readers-app/electron/main/services/ApiProcessManager.ts
• Retorno: Promise<void>
• Lança Error apenas se todas as tentativas falharem
• Em dev: spawna npm run dev:once; em prod: executa o .exe da pasta resources

handleCardRead() — main.ts

Descrição simplificada:

Decide o que fazer quando um cartão é lido: mostrar na UI ou colar no aplicativo ativo.

Descrição técnica:

• Localização: insoft-readers-app/electron/main/main.ts
• Se janela em foco: mainWindow.webContents.send("card:read", event)
• Se janela em background: pasteToExternalFocusedApp(cardId, appendNewLine)
• Também envia app:notification quando em background (aparece como toast)

pasteToExternalFocusedApp() — main.ts

Descrição simplificada:

Cola o código do cartão no campo de texto ativo usando a área de transferência do Windows.

Descrição técnica:

• Localização: insoft-readers-app/electron/main/main.ts
• Usa clipboard.writeText(cardId) do Electron
• Executa VBScript pré-criado em %TEMP% (criado na inicialização para evitar latência)
  • insoft_paste.vbs: SendKeys "^v" (Ctrl+V)
  • insoft_paste_nl.vbs: SendKeys "^v{ENTER}" (Ctrl+V + Enter)
• wscript.exe //B suprime diálogos; latência ~50ms vs ~1.500ms do PowerShell
• Apenas funciona em win32

6. INTEGRAÇÕES EXTERNAS

DLL Nativa — DG710Facade.dll

Pontos de atenção:

• A DLL deve estar acessível no mesmo diretório do executável ou em caminho absoluto
• O processo deve ser x64 para carregar a DLL x64
• A DLL pode requerer drivers do fabricante instalados no Windows

NSSM — Non-Sucking Service Manager

VBScript / wscript.exe

7. TRATAMENTO DE ERROS E EXCEÇÕES

Estratégia Geral

Logs Importantes

O backend usa pino com logs estruturados JSON. Nível padrão: info.

Variáveis de Ambiente para Diagnóstico

🧪 8. CENÁRIOS COMUNS DE SUPORTE

Cenário 1: O cartão não está sendo lido

Cenário 2: O código do cartão está errado (com caracteres extras)

Cenário 3: O cartão está sendo lido mas não é colado no aplicativo

Cenário 4: A interface abre mas mostra erro de conexão

Cenário 5: Erro "Arquitetura incompatível" no log

Cenário 6: Porta 3791 já está em uso

Cenário 7: Leitor conecta mas para de responder após um tempo

9. BOAS PRÁTICAS E OBSERVAÇÕES

Adicionando Suporte a Novo Modelo de Leitor

Para adicionar um novo leitor (ex: fabricante X, modelo Y):

1. Criar pasta: insoft-readers-api/src/devices/fabricante-x/
2. Implementar a interface ICardReader em uma nova classe
3. Registrar em server.ts:

   registry.register("fabricante-x-modelY", () => new FabricanteXReaderY());
   

4. Se usar DLL nativa: criar uma Facade similar ao DigiconFacade.ts

Pontos Sensíveis ao Modificar

Configuração de Runtime em Produção

O arquivo reader-runtime-settings.json é persistido no diretório de trabalho (cwd) da API. Em produção, isso é o diretório do executável. Ao atualizar a API, preserve esse arquivo para não perder configurações.

Modo de Desenvolvimento

Para rodar o projeto em modo desenvolvimento:

# Na raiz do monorepo — inicia todos os serviços simultaneamente:
npm run dev

# Separado:
npm run dev:frontend   # Vite na porta 5173
npm run dev:electron   # Electron + TypeScript watch
# A API é iniciada automaticamente pelo Electron via ApiProcessManager

Compilação para Produção

# Gera instalador NSIS para Windows x64:
npm run dist

# Resultado em:
# insoft-readers-app/electron/release/
#   Insoft-Readers-1.0.0-Setup-x64.exe

O instalador empacota:

• resources/api/insoft-reader-api.exe — API compilada com pkg
• resources/frontend/ — Build estático do React
• resources/ — Preload, assets

Diagrama de Dependências dos Pacotes

@insoft/backend (API)
  ├── express          ← servidor HTTP
  ├── koffi            ← FFI para DLL nativa
  ├── pino             ← logging
  ├── zod              ← validação
  └── dotenv           ← variáveis de ambiente

@insoft/electron
  └── electron         ← framework desktop

@insoft/frontend
  ├── react            ← UI
  ├── zustand          ← estado global
  ├── axios            ← cliente HTTP
  ├── react-hook-form  ← formulários
  ├── zod              ← validação de forms
  ├── flowbite-react   ← componentes UI
  └── tailwindcss      ← estilos

Documentação gerada a partir do código-fonte do projeto. Para atualizações, reanalise os arquivos correspondentes após mudanças significativas na arquitetura e atualize essa documentação.