# Guia de Exemplos de Uso - SecWinDev BioFinger v12

**Data:** 07 de Outubro de 2025
**Versão:** 12.0 (Binding Dinâmico REST/DLL via JSON)
**Documento:** Exemplos Práticos de Utilização

---

## Índice

1. [Inicialização Básica](#1-inicialização-básica)
2. [Cadastro de Digitais](#2-cadastro-de-digitais)
3. [Verificação 1:1](#3-verificação-11)
4. [Identificação 1:N](#4-identificação-1n)
5. [Busca por Imagem](#5-busca-por-imagem)
6. [Busca e Consultas](#6-busca-e-consultas)
7. [Atualização de Digitais](#7-atualização-de-digitais)
8. [Matcher Combinado](#8-matcher-combinado)
9. [Exclusão de Dados](#9-exclusão-de-dados)
10. [Estatísticas](#10-estatísticas)
11. [Tratamento de Erros](#11-tratamento-de-erros)
12. [Provider MOCK (Testes)](#12-provider-mock-testes)
13. [Integração com Interface](#13-integração-com-interface)

---

## 1. Inicialização Básica

### 1.1. Inicialização Simples

```wlanguage
PROCEDURE InicializarSistema()
LOCAL oBio IS clsBioFinger
LOCAL stResult IS STBioResult

// Criar instância da classe
oBio = NEW clsBioFinger

// Inicializar com arquivo de configuração e banco de dados
stResult = oBio.Initialize(".\cfg\secwin_biofinger.config.json",
"DSN=PostgreSQL;UID=postgres;PWD=senha123")

IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("Sistema inicializado com sucesso!")
Trace("Provider: " + oBio.GetConfig().GetProviderName())
ELSE
Error("Falha na inicialização: " + stResult.message)
RETURN False
END

RETURN True
END
```

### 1.2. Inicialização com Diferentes Providers

```wlanguage
// Provider MOCK (simulação para testes)
stResult = oBio.Initialize(".\cfg\cfg_mock.json", sConnectionString)

// Provider SecuGen
stResult = oBio.Initialize(".\cfg\cfg_secugen.json", sConnectionString)

// Provider HID DigitalPersona
stResult = oBio.Initialize(".\cfg\cfg_hid.json", sConnectionString)

// Provider Control iD (REST com TLS)
stResult = oBio.Initialize(".\cfg\cfg_controlid.json", sConnectionString)

// Provider ZKTeco
stResult = oBio.Initialize(".\cfg\cfg_zkteco.json", sConnectionString)
```

### 1.3. Verificar Status do Dispositivo

```wlanguage
PROCEDURE VerificarDispositivo(oBio IS clsBioFinger)
LOCAL stDeviceInfo IS STBioDeviceInfo
LOCAL stResult IS STBioResult

// Obter informações do dispositivo
stDeviceInfo = oBio.GetDeviceInfo()

Trace("=== Informações do Dispositivo ===")
Trace("Provider: " + stDeviceInfo.provider_name)
Trace("Dispositivo: " + stDeviceInfo.device_name)
Trace("Serial: " + stDeviceInfo.device_serial)
Trace("Firmware: " + stDeviceInfo.firmware_version)
Trace("Conectado: " + (stDeviceInfo.is_connected ? "Sim" : "Não"))

// Verificar status atual
stResult = oBio.GetDeviceStatus()
IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("Dispositivo operacional")
ELSE
Warning("Problema no dispositivo: " + stResult.message)
END
END
```

### 1.4. Finalização

```wlanguage
PROCEDURE FinalizarSistema(oBio IS clsBioFinger)
LOCAL stResult IS STBioResult

stResult = oBio.Disconnect()

IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("Sistema desconectado com sucesso!")
ELSE
Warning("Erro ao desconectar: " + stResult.message)
END
END
```

---

## 2. Cadastro de Digitais

### 2.1. Cadastro Básico

```wlanguage
PROCEDURE CadastrarDigital(oBio IS clsBioFinger, sLogin IS STRING)
LOCAL stResult IS STBioResult

Info("Coloque o polegar direito no leitor...")

// Cadastrar com captura de imagem
stResult = oBio.EnrollFinger(sLogin, BIO_FINGER_RIGHT_THUMB, True)

IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("Digital cadastrada com sucesso!")
Info("Qualidade: " + stResult.quality + "%")
ELSE IF stResult.status = BIO_STATUS_INVALID_QUALITY THEN
Warning("Qualidade insuficiente. Tente novamente.")
ELSE IF stResult.status = BIO_STATUS_EXISTS THEN
Info("Esta digital já está cadastrada.")
ELSE
Error("Erro no cadastro: " + stResult.message)
END
END
```

### 2.2. Cadastro de Múltiplos Dedos

```wlanguage
PROCEDURE CadastrarMultiplosDedos(oBio IS clsBioFinger, sLogin IS STRING)
LOCAL stResult IS STBioResult
LOCAL arrDedos IS ARRAY OF INT
LOCAL nDedo IS INT

// Definir dedos a cadastrar
arrDedos = [BIO_FINGER_RIGHT_THUMB,
BIO_FINGER_RIGHT_INDEX,
BIO_FINGER_LEFT_THUMB]

FOR EACH nDedo OF arrDedos
Info("Coloque o " + BioGetFingerName(nDedo) + " no leitor...")

stResult = oBio.EnrollFinger(sLogin, nDedo, True)

IF stResult.status = BIO_STATUS_SUCCESS THEN
Trace(BioGetFingerName(nDedo) + " cadastrado! Qualidade: " + stResult.quality)
ELSE IF stResult.status = BIO_STATUS_RETRY THEN
Warning("Tente novamente...")
// Repetir tentativa
stResult = oBio.EnrollFinger(sLogin, nDedo, True)
ELSE
Error("Erro ao cadastrar " + BioGetFingerName(nDedo) + ": " + stResult.message)
BREAK
END
END

Info("Cadastro concluído!")
END
```

### 2.3. Cadastro com Validação de Qualidade

```wlanguage
PROCEDURE CadastrarComQualidade(oBio IS clsBioFinger, sLogin IS STRING, nMinQuality IS INT = 70)
LOCAL stResult IS STBioResult
LOCAL nTentativas IS INT = 0
LOCAL nMaxTentativas IS INT = 3

LOOP
nTentativas++

Info("Tentativa " + nTentativas + " de " + nMaxTentativas)
Info("Coloque o dedo no leitor...")

stResult = oBio.EnrollFinger(sLogin, BIO_FINGER_RIGHT_INDEX, True)

IF stResult.status = BIO_STATUS_SUCCESS THEN
IF stResult.quality >= nMinQuality THEN
Info("Digital cadastrada! Qualidade excelente: " + stResult.quality + "%")
BREAK
ELSE
Warning("Qualidade baixa (" + stResult.quality + "%). Tente novamente.")
// Remover cadastro de baixa qualidade
oBio.DeleteFinger(sLogin, BIO_FINGER_RIGHT_INDEX)
END
ELSE
Warning(stResult.message)
END

IF nTentativas >= nMaxTentativas THEN
Error("Número máximo de tentativas excedido.")
BREAK
END
END
END
```

### 2.4. Cadastro a partir de Template Existente

```wlanguage
PROCEDURE CadastrarDeTemplate(oBio IS clsBioFinger,
sLogin IS STRING,
bufTemplate IS BUFFER,
bufImage IS BUFFER = Null)
LOCAL stResult IS STBioResult

// Cadastrar a partir de template já existente (importação)
stResult = oBio.EnrollFingerFromTemplate(sLogin,
BIO_FINGER_RIGHT_THUMB,
bufTemplate,
bufImage,
85) // qualidade estimada

IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("Template importado com sucesso!")
ELSE
Error("Erro ao importar template: " + stResult.message)
END
END
```

---

## 3. Verificação 1:1

### 3.1. Verificação Simples

```wlanguage
PROCEDURE VerificarUsuario(oBio IS clsBioFinger, sLogin IS STRING)
LOCAL stResult IS STBioResult

Info("Coloque o polegar direito no leitor...")

// Verificar se o dedo capturado corresponde ao cadastrado
stResult = oBio.VerifyFinger(sLogin, BIO_FINGER_RIGHT_THUMB)

IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("? Verificação bem-sucedida!")
Info("Score de correspondência: " + stResult.score + "%")
// Permitir acesso
PermitirAcesso(sLogin)
ELSE IF stResult.status = BIO_STATUS_NOT_FOUND THEN
Warning("? Digital não corresponde!")
Info("Score: " + stResult.score + "%")
// Negar acesso
NegarAcesso()
ELSE
Error("Erro na verificação: " + stResult.message)
END
END
```

### 3.2. Verificação com Threshold Customizado

```wlanguage
PROCEDURE VerificarComThreshold(oBio IS clsBioFinger,
sLogin IS STRING,
nThreshold IS INT = 70)
LOCAL stResult IS STBioResult

stResult = oBio.VerifyFinger(sLogin, BIO_FINGER_RIGHT_INDEX)

IF stResult.status = BIO_STATUS_SUCCESS AND stResult.score >= nThreshold THEN
Info("Acesso autorizado! Score: " + stResult.score)
RETURN True
ELSE
Warning("Acesso negado. Score: " + stResult.score + " (mínimo: " + nThreshold + ")")
RETURN False
END
END
```

### 3.3. Verificação com Múltiplas Tentativas

```wlanguage
PROCEDURE VerificarComTentativas(oBio IS clsBioFinger, sLogin IS STRING)
LOCAL stResult IS STBioResult
LOCAL nTentativa IS INT
LOCAL nMaxTentativas IS INT = 3

FOR nTentativa = 1 TO nMaxTentativas
Info("Tentativa " + nTentativa + " de " + nMaxTentativas)
Info("Coloque o dedo no leitor...")

stResult = oBio.VerifyFinger(sLogin, BIO_FINGER_RIGHT_THUMB)

IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("? Acesso autorizado!")
RETURN True
ELSE IF stResult.status = BIO_STATUS_NOT_FOUND THEN
IF nTentativa < nMaxTentativas THEN
Warning("Digital não corresponde. Tente novamente.")
END
ELSE
Error("Erro: " + stResult.message)
BREAK
END
END

Error("? Acesso negado após " + nMaxTentativas + " tentativas.")
RETURN False
END
```

### 3.4. Verificação de Qualquer Dedo Cadastrado

```wlanguage
PROCEDURE VerificarQualquerDedo(oBio IS clsBioFinger, sLogin IS STRING)
LOCAL stResult IS STBioResult
LOCAL arrDedos IS ARRAY OF STBioFingerData
LOCAL stDedo IS STBioFingerData
LOCAL bVerificado IS BOOLEAN = False

// Obter todos os dedos cadastrados do usuário
arrDedos = oBio.GetFingersByLogin(sLogin)

IF ArrayCount(arrDedos) = 0 THEN
Error("Usuário não possui digitais cadastradas.")
RETURN False
END

Info("Coloque qualquer dedo cadastrado no leitor...")

// Tentar verificar com cada dedo cadastrado
FOR EACH stDedo OF arrDedos
stResult = oBio.VerifyFinger(sLogin, stDedo.finger_code)

IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("? Verificado com " + BioGetFingerName(stDedo.finger_code))
bVerificado = True
BREAK
END
END

IF NOT bVerificado THEN
Warning("? Nenhum dedo correspondeu.")
END

RETURN bVerificado
END
```

---

## 4. Identificação 1:N

### 4.1. Identificação Básica

```wlanguage
PROCEDURE IdentificarUsuario(oBio IS clsBioFinger)
LOCAL arrMatches IS ARRAY OF STBioMatchResult
LOCAL stMatch IS STBioMatchResult

Info("Coloque qualquer dedo cadastrado no leitor...")

// Identificar entre todos os usuários cadastrados
arrMatches = oBio.IdentifyFinger(Null, 5) // Top 5 resultados

IF ArrayCount(arrMatches) > 0 THEN
// Melhor correspondência
stMatch = arrMatches[1]

Info("? Usuário identificado: " + stMatch.login)
Info("Dedo: " + BioGetFingerName(stMatch.finger_code))
Info("Score: " + stMatch.score + "%")

// Exibir outros candidatos
IF ArrayCount(arrMatches) > 1 THEN
Trace("Outros candidatos:")
FOR i = 2 TO ArrayCount(arrMatches)
Trace(" " + i + ". " + arrMatches[i].login + " (Score: " + arrMatches[i].score + ")")
END
END

RETURN stMatch.login
ELSE
Warning("? Nenhum usuário identificado.")
RETURN ""
END
END
```

### 4.2. Identificação com Threshold

```wlanguage
PROCEDURE IdentificarComThreshold(oBio IS clsBioFinger, nMinScore IS INT = 75)
LOCAL arrMatches IS ARRAY OF STBioMatchResult

arrMatches = oBio.IdentifyFinger(Null, 10)

IF ArrayCount(arrMatches) > 0 AND arrMatches[1].score >= nMinScore THEN
Info("Identificado: " + arrMatches[1].login + " (Score: " + arrMatches[1].score + ")")
RETURN arrMatches[1].login
ELSE
IF ArrayCount(arrMatches) > 0 THEN
Warning("Melhor correspondência abaixo do threshold: " + arrMatches[1].score + " < " + nMinScore)
ELSE
Warning("Nenhuma correspondência encontrada.")
END
RETURN ""
END
END
```

### 4.3. Identificação com Ranking Completo

```wlanguage
PROCEDURE ExibirRankingIdentificacao(oBio IS clsBioFinger)
LOCAL arrMatches IS ARRAY OF STBioMatchResult
LOCAL stMatch IS STBioMatchResult
LOCAL i IS INT

Info("Coloque o dedo no leitor...")

arrMatches = oBio.IdentifyFinger(Null, 10)

IF ArrayCount(arrMatches) = 0 THEN
Info("Nenhuma correspondência encontrada.")
RETURN
END

Info("=== Ranking de Identificação ===")

FOR i = 1 TO ArrayCount(arrMatches)
stMatch = arrMatches[i]

Trace(StringBuild("Rank %1: %2", i, stMatch.login))
Trace(" Dedo: " + BioGetFingerName(stMatch.finger_code))
Trace(" Score: " + stMatch.score + "%")
Trace(" " + BarraProgresso(stMatch.score))
Trace("")
END
END

// Função auxiliar para exibir barra de progresso
FUNCTION BarraProgresso(nScore IS INT) : STRING
LOCAL sBarra IS STRING = "["
LOCAL nBlocos IS INT = Round(nScore / 5, 0) // 20 blocos para 100%

FOR i = 1 TO 20
IF i <= nBlocos THEN
sBarra += "¦"
ELSE
sBarra += "¦"
END
END

sBarra += "]"
RETURN sBarra
END
```

### 4.4. Identificação em Grupo Específico

```wlanguage
PROCEDURE IdentificarEmGrupo(oBio IS clsBioFinger, arrLoginsPermitidos IS ARRAY OF STRING)
LOCAL arrMatches IS ARRAY OF STBioMatchResult
LOCAL stMatch IS STBioMatchResult
LOCAL bEncontrado IS BOOLEAN = False

arrMatches = oBio.IdentifyFinger(Null, 20)

// Verificar se algum dos matches está no grupo permitido
FOR EACH stMatch OF arrMatches
IF ArraySeek(arrLoginsPermitidos, stMatch.login) > 0 THEN
Info("? Identificado: " + stMatch.login + " (autorizado)")
bEncontrado = True
BREAK
END
END

IF NOT bEncontrado THEN
Warning("? Usuário não autorizado ou não identificado.")
END

RETURN bEncontrado
END
```

---

## 5. Busca por Imagem

### 5.1. Busca por Similaridade

```wlanguage
PROCEDURE BuscarImagensSimilares(oBio IS clsBioFinger)
LOCAL arrSimilar IS ARRAY OF STBioImageCompareResult
LOCAL stSimilar IS STBioImageCompareResult
LOCAL i IS INT

Info("Coloque o dedo no leitor para busca por imagem...")

// Buscar imagens com similaridade >= 70%
arrSimilar = oBio.SearchByImage(Null, 5, 0.7)

IF ArrayCount(arrSimilar) > 0 THEN
Info("Imagens similares encontradas:")

FOR i = 1 TO ArrayCount(arrSimilar)
stSimilar = arrSimilar[i]

Trace(StringBuild("%1. %2 - %3",
i,
stSimilar.login,
BioGetFingerName(stSimilar.finger_code)))
Trace(" Similaridade: " + Round(stSimilar.similarity * 100, 2) + "%")
END
ELSE
Info("Nenhuma imagem similar encontrada.")
END
END
```

### 5.2. Busca de Duplicatas

```wlanguage
PROCEDURE DetectarDuplicatas(oBio IS clsBioFinger, sLoginNovo IS STRING)
LOCAL arrSimilar IS ARRAY OF STBioImageCompareResult
LOCAL stSimilar IS STBioImageCompareResult
LOCAL arrDedosNovos IS ARRAY OF STBioFingerData
LOCAL stDedo IS STBioFingerData

// Obter digitais do novo usuário
arrDedosNovos = oBio.GetFingersByLogin(sLoginNovo)

FOR EACH stDedo OF arrDedosNovos
// Buscar imagens muito similares (>= 95%)
arrSimilar = oBio.SearchByImage(stDedo.image, 3, 0.95)

FOR EACH stSimilar OF arrSimilar
// Ignorar o próprio usuário
IF stSimilar.login <> sLoginNovo THEN
Warning("? Possível duplicata detectada!")
Warning(" Novo: " + sLoginNovo + " - " + BioGetFingerName(stDedo.finger_code))
Warning(" Similar: " + stSimilar.login + " - " + BioGetFingerName(stSimilar.finger_code))
Warning(" Similaridade: " + Round(stSimilar.similarity * 100, 2) + "%")
END
END
END
END
```

---

## 6. Busca e Consultas

### 6.1. Buscar Digital Específica

```wlanguage
PROCEDURE ConsultarDigital(oBio IS clsBioFinger, sLogin IS STRING, nFingerCode IS INT)
LOCAL stFinger IS STBioFingerData

stFinger = oBio.GetFinger(sLogin, nFingerCode)

IF stFinger.login <> "" THEN
Info("=== Informações da Digital ===")
Trace("Usuário: " + stFinger.login)
Trace("Dedo: " + BioGetFingerName(stFinger.finger_code))
Trace("Qualidade: " + stFinger.quality_score + "%")
Trace("Formato: " + stFinger.tpl_fmt)
Trace("Tamanho template: " + Length(stFinger.tpl) + " bytes")
Trace("Possui imagem: " + (Length(stFinger.image) > 0 ? "Sim" : "Não"))
Trace("Atualizado em: " + DateTimeToString(stFinger.updated_at, "DD/MM/YYYY HH:MM:SS"))
Trace("Dispositivo: " + stFinger.device_info)
ELSE
Info("Digital não encontrada.")
END
END
```

### 6.2. Listar Digitais de um Usuário

```wlanguage
PROCEDURE ListarDigitaisUsuario(oBio IS clsBioFinger, sLogin IS STRING)
LOCAL arrDedos IS ARRAY OF STBioFingerData
LOCAL stDedo IS STBioFingerData

arrDedos = oBio.GetFingersByLogin(sLogin)

IF ArrayCount(arrDedos) = 0 THEN
Info("Usuário não possui digitais cadastradas.")
RETURN
END

Info("=== Digitais de " + sLogin + " ===")
Info("Total: " + ArrayCount(arrDedos) + " digital(is)")
Trace("")

FOR EACH stDedo OF arrDedos
Trace("• " + BioGetFingerName(stDedo.finger_code))
Trace(" Qualidade: " + stDedo.quality_score + "%")
Trace(" Atualizado: " + DateTimeToString(stDedo.updated_at, "DD/MM/YYYY"))
Trace("")
END
END
```

### 6.3. Busca Composta com Filtros

```wlanguage
PROCEDURE BuscarDigitaisAvancada()
LOCAL oBio IS clsBioFinger
LOCAL stCriteria IS STBioSearchCriteria
LOCAL arrResults IS ARRAY OF STBioFingerData
LOCAL stFinger IS STBioFingerData

// Configurar critérios de busca
stCriteria.min_quality = 80 // Qualidade mínima 80%
stCriteria.date_from = DateSys() - 30 // Últimos 30 dias
stCriteria.order_by = "quality_score" // Ordenar por qualidade
stCriteria.order_desc = True // Ordem descendente
stCriteria.limit = 20 // Máximo 20 resultados

arrResults = oBio.SearchFingers(stCriteria)

Info("Encontradas " + ArrayCount(arrResults) + " digitais de alta qualidade")

FOR EACH stFinger OF arrResults
Trace(StringBuild("%1 - %2: %3%",
stFinger.login,
BioGetFingerName(stFinger.finger_code),
stFinger.quality_score))
END
END
```

### 6.4. Busca por Período

```wlanguage
PROCEDURE BuscarPorPeriodo(oBio IS clsBioFinger, dtInicio IS DATETIME, dtFim IS DATETIME)
LOCAL stCriteria IS STBioSearchCriteria
LOCAL arrResults IS ARRAY OF STBioFingerData

stCriteria.date_from = dtInicio
stCriteria.date_to = dtFim
stCriteria.order_by = "updated_at"
stCriteria.order_desc = True

arrResults = oBio.SearchFingers(stCriteria)

Info(StringBuild("Digitais cadastradas/atualizadas entre %1 e %2: %3",
DateToString(dtInicio, "DD/MM/YYYY"),
DateToString(dtFim, "DD/MM/YYYY"),
ArrayCount(arrResults)))

RETURN arrResults
END
```

---

## 7. Atualização de Digitais

### 7.1. Atualizar com Nova Captura

```wlanguage
PROCEDURE AtualizarDigital(oBio IS clsBioFinger, sLogin IS STRING, nFingerCode IS INT)
LOCAL stResult IS STBioResult

Info("Coloque o " + BioGetFingerName(nFingerCode) + " no leitor para atualização...")

stResult = oBio.UpdateFingerFromCapture(sLogin, nFingerCode, True)

IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("? Digital atualizada com sucesso!")
Info("Nova qualidade: " + stResult.quality + "%")
ELSE
Error("Erro na atualização: " + stResult.message)
END
END
```

### 7.2. Melhorar Qualidade de Digitais

```wlanguage
PROCEDURE MelhorarQualidade(oBio IS clsBioFinger, sLogin IS STRING)
LOCAL arrDedos IS ARRAY OF STBioFingerData
LOCAL stDedo IS STBioFingerData
LOCAL stResult IS STBioResult
LOCAL nMelhorados IS INT = 0

arrDedos = oBio.GetFingersByLogin(sLogin)

Info("Verificando digitais de " + sLogin + "...")

FOR EACH stDedo OF arrDedos
IF stDedo.quality_score < 70 THEN
Info("Qualidade baixa detectada em " + BioGetFingerName(stDedo.finger_code))
Info("Coloque o dedo no leitor para melhorar...")

stResult = oBio.UpdateFingerFromCapture(sLogin, stDedo.finger_code, True)

IF stResult.status = BIO_STATUS_SUCCESS AND stResult.quality > stDedo.quality_score THEN
Info("? Qualidade melhorada: " + stDedo.quality_score + "% ? " + stResult.quality + "%")
nMelhorados++
END
END
END

Info(StringBuild("Processo concluído. %1 digital(is) melhorada(s).", nMelhorados))
END
```

---

## 8. Matcher Combinado

### 8.1. Obter Matcher Combinado

```wlanguage
PROCEDURE ConsultarMatcherCombinado(oBio IS clsBioFinger, sLogin IS STRING)
LOCAL stCombined IS STBioCombinedMatcher
LOCAL nDedo IS INT

stCombined = oBio.GetCombinedMatcher(sLogin)

IF stCombined.login <> "" THEN
Info("=== Matcher Combinado de " + sLogin + " ===")
Trace("Quantidade de dedos: " + stCombined.tpl_count)
Trace("Tamanho do template combinado: " + Length(stCombined.combined_tpl) + " bytes")
Trace("Criado em: " + DateTimeToString(stCombined.created_at, "DD/MM/YYYY HH:MM:SS"))

Trace("Dedos incluídos:")
FOR EACH nDedo OF stCombined.finger_codes
Trace(" • " + BioGetFingerName(nDedo))
END
ELSE
Info("Matcher combinado não encontrado.")
END
END
```

### 8.2. Atualizar Matcher Combinado

```wlanguage
PROCEDURE AtualizarMatcherCombinado(oBio IS clsBioFinger, sLogin IS STRING)
LOCAL stResult IS STBioResult

Info("Atualizando matcher combinado de " + sLogin + "...")

stResult = oBio.UpdateCombinedMatcher(sLogin)

IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("? Matcher combinado atualizado com sucesso!")
ELSE
Error("Erro ao atualizar matcher: " + stResult.message)
END
END
```

---

## 9. Exclusão de Dados

### 9.1. Excluir Digital Específica

```wlanguage
PROCEDURE ExcluirDigital(oBio IS clsBioFinger, sLogin IS STRING, nFingerCode IS INT)
LOCAL stResult IS STBioResult

IF YesNo("Confirma a exclusão do " + BioGetFingerName(nFingerCode) + " de " + sLogin + "?") = Yes THEN
stResult = oBio.DeleteFinger(sLogin, nFingerCode)

IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("? Digital excluída com sucesso!")
ELSE
Error("Erro na exclusão: " + stResult.message)
END
END
END
```

### 9.2. Excluir Todas as Digitais de um Usuário

```wlanguage
PROCEDURE ExcluirUsuario(oBio IS clsBioFinger, sLogin IS STRING)
LOCAL stResult IS STBioResult
LOCAL nQuantidade IS INT

// Verificar quantas digitais serão excluídas
nQuantidade = ArrayCount(oBio.GetFingersByLogin(sLogin))

IF nQuantidade = 0 THEN
Info("Usuário não possui digitais cadastradas.")
RETURN
END

IF YesNo(StringBuild("Confirma a exclusão de %1 digital(is) de %2?", nQuantidade, sLogin)) = Yes THEN
stResult = oBio.DeleteFingersByLogin(sLogin)

IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("? " + stResult.message)
ELSE
Error("Erro: " + stResult.message)
END
END
END
```

### 9.3. Limpeza Total (Cuidado!)

```wlanguage
PROCEDURE LimparTodosBancoDados(oBio IS clsBioFinger)
LOCAL stResult IS STBioResult

Warning("? ATENÇÃO: Esta operação irá excluir TODAS as digitais do sistema!")

IF YesNo("Tem certeza que deseja continuar?") = No THEN
RETURN
END

IF YesNo("ÚLTIMA CONFIRMAÇÃO: Excluir TODOS os dados?") = Yes THEN
stResult = oBio.WipeAll(True)

IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("? Todos os dados foram excluídos.")
ELSE
Error("Erro: " + stResult.message)
END
ELSE
Info("Operação cancelada.")
END
END
```

---

## 10. Estatísticas

### 10.1. Obter Estatísticas do Sistema

```wlanguage
PROCEDURE ExibirEstatisticas(oBio IS clsBioFinger)
LOCAL stStats IS STBioStatistics

stStats = oBio.GetStatistics()

Info("=== Estatísticas do Sistema ===")
Trace("Total de usuários: " + stStats.total_users)
Trace("Total de digitais: " + stStats.total_fingers)
Trace("Qualidade média: " + Round(stStats.avg_quality, 2) + "%")
Trace("Total de verificações: " + stStats.total_verifications)
Trace("Total de identificações: " + stStats.total_identifications)
Trace("Último cadastro: " + DateTimeToString(stStats.last_enrollment, "DD/MM/YYYY HH:MM"))
Trace("Última verificação: " + DateTimeToString(stStats.last_verification, "DD/MM/YYYY HH:MM"))
END
```

---

## 11. Tratamento de Erros

### 11.1. Tratamento Robusto

```wlanguage
PROCEDURE OperacaoSegura(oBio IS clsBioFinger, sLogin IS STRING)
LOCAL stResult IS STBioResult

TRY
// Validar parâmetros
IF sLogin = "" THEN
Error("Login não pode ser vazio")
RETURN
END

// Verificar inicialização
IF NOT oBio.IsInitialized() THEN
Error("Sistema não inicializado")
RETURN
END

// Executar operação
stResult = oBio.EnrollFinger(sLogin, BIO_FINGER_RIGHT_THUMB, True)

// Tratar resultado
SWITCH stResult.status
CASE BIO_STATUS_SUCCESS
Info("? Operação bem-sucedida!")

CASE BIO_STATUS_NOT_FOUND
Warning("Digital não encontrada")

CASE BIO_STATUS_RETRY
Warning("Tente novamente")

CASE BIO_STATUS_ERROR
Error("Erro genérico: " + stResult.message)

CASE BIO_STATUS_EXISTS
Info("Digital já cadastrada")

CASE BIO_STATUS_TIMEOUT
Warning("Timeout - operação demorou muito")

CASE BIO_STATUS_INVALID_QUALITY
Warning("Qualidade insuficiente: " + stResult.quality + "%")

CASE BIO_STATUS_DEVICE_ERROR
Error("Erro no dispositivo: " + stResult.message)

CASE BIO_STATUS_DB_ERROR
Error("Erro no banco de dados: " + stResult.message)

CASE BIO_STATUS_INVALID_PARAM
Error("Parâmetro inválido: " + stResult.message)

CASE BIO_STATUS_NOT_INITIALIZED
Error("Sistema não inicializado")

OTHER CASE
Error("Status desconhecido: " + stResult.status)
END

EXCEPTION
Error("Exceção capturada: " + ExceptionInfo())
Trace("Último erro: " + oBio.GetLastError())
END
END
```

---

## 12. Provider MOCK (Testes)

### 12.1. Usar MOCK para Desenvolvimento

```wlanguage
PROCEDURE TestarSemHardware()
LOCAL oBio IS clsBioFinger
LOCAL stResult IS STBioResult

// Inicializar com provider MOCK
oBio = NEW clsBioFinger
stResult = oBio.Initialize(".\cfg\cfg_mock.json", "DSN=PostgreSQL")

IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("? Provider MOCK inicializado - ideal para testes!")

// Todas as operações funcionam normalmente com dados simulados
stResult = oBio.EnrollFinger("teste01", BIO_FINGER_RIGHT_THUMB, True)
Info("Cadastro simulado: " + stResult.message + " (Qualidade: " + stResult.quality + "%)")

stResult = oBio.VerifyFinger("teste01", BIO_FINGER_RIGHT_THUMB)
Info("Verificação simulada: Score = " + stResult.score + "%")

LOCAL arrMatches IS ARRAY OF STBioMatchResult
arrMatches = oBio.IdentifyFinger(Null, 5)
Info("Identificação simulada: " + ArrayCount(arrMatches) + " resultado(s)")
END
END
```

---

## 13. Integração com Interface

### 13.1. Janela de Cadastro

```wlanguage
// Código do botão "Cadastrar Digital"
PROCEDURE BTN_CadastrarDigital_Click()
GLOBAL g_oBio IS clsBioFinger
LOCAL stResult IS STBioResult
LOCAL sLogin IS STRING
LOCAL nDedo IS INT

// Obter dados da interface
sLogin = EDT_Login
nDedo = COMBO_Dedo[COMBO_Dedo] // Valor selecionado

// Validar
IF sLogin = "" THEN
Error("Informe o login do usuário")
RETURN
END

// Verificar se já existe
IF g_oBio.FingerExists(sLogin, nDedo) THEN
IF YesNo("Esta digital já está cadastrada. Deseja atualizar?") = Yes THEN
stResult = g_oBio.UpdateFingerFromCapture(sLogin, nDedo, True)
ELSE
RETURN
END
ELSE
// Cadastrar nova digital
Info("Coloque o " + BioGetFingerName(nDedo) + " no leitor...")
stResult = g_oBio.EnrollFinger(sLogin, nDedo, True)
END

// Exibir resultado
IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("Digital cadastrada com sucesso!")
PROG_Qualidade = stResult.quality
STC_Qualidade = stResult.quality + "%"

// Atualizar lista
AtualizarListaDigitais(sLogin)
ELSE
Error(stResult.message)
END
END
```

### 13.2. Janela de Verificação

```wlanguage
// Código do botão "Verificar Acesso"
PROCEDURE BTN_VerificarAcesso_Click()
GLOBAL g_oBio IS clsBioFinger
LOCAL stResult IS STBioResult
LOCAL sLogin IS STRING

sLogin = EDT_Login

IF sLogin = "" THEN
Error("Informe o login")
RETURN
END

// Exibir mensagem na interface
STC_Status = "Aguardando digital..."
STC_Status..Color = OrangeLight

// Verificar
stResult = g_oBio.VerifyFinger(sLogin, BIO_FINGER_RIGHT_THUMB)

IF stResult.status = BIO_STATUS_SUCCESS THEN
STC_Status = "? ACESSO AUTORIZADO"
STC_Status..Color = GreenLight
IMG_Status = "ok.png"

// Registrar acesso
RegistrarAcesso(sLogin, True, stResult.score)
ELSE
STC_Status = "? ACESSO NEGADO"
STC_Status..Color = RedLight
IMG_Status = "error.png"

RegistrarAcesso(sLogin, False, stResult.score)
END

PROG_Score = stResult.score
STC_Score = "Score: " + stResult.score + "%"
END
```

### 13.3. Janela de Identificação

```wlanguage
// Código do botão "Identificar"
PROCEDURE BTN_Identificar_Click()
GLOBAL g_oBio IS clsBioFinger
LOCAL arrMatches IS ARRAY OF STBioMatchResult
LOCAL stMatch IS STBioMatchResult

STC_Status = "Coloque qualquer dedo no leitor..."

arrMatches = g_oBio.IdentifyFinger(Null, 10)

// Limpar tabela
TableDeleteAll(TABLE_Resultados)

IF ArrayCount(arrMatches) > 0 THEN
// Melhor match
stMatch = arrMatches[1]

STC_Status = "? Identificado: " + stMatch.login
STC_Status..Color = GreenLight
EDT_LoginIdentificado = stMatch.login

// Preencher tabela com ranking
FOR EACH stMatch OF arrMatches
TableAddLine(TABLE_Resultados,
stMatch.rank,
stMatch.login,
BioGetFingerName(stMatch.finger_code),
stMatch.score)
END

// Selecionar primeira linha
TABLE_Resultados = 1
ELSE
STC_Status = "? Nenhum usuário identificado"
STC_Status..Color = RedLight
EDT_LoginIdentificado = ""
END
END
```

---

## Conclusão

Este guia apresenta exemplos práticos de utilização do sistema **SecWinDev BioFinger v12** cobrindo todas as funcionalidades principais. Os exemplos podem ser adaptados conforme as necessidades específicas de cada aplicação.

### Recursos Adicionais

**Arquivos de Exemplo no Projeto:**
- `examples/exemplo_uso_completo.wl` - Exemplo completo com todas as funcionalidades
- `examples/testes_unitarios.wl` - Suite de testes unitários
- `examples/BioFinger_Tests_v11.wl` - Testes básicos
- `examples/WIN_BioFinger_UX_v11.wl` - Exemplo de interface de usuário

**Documentação:**
- `docs/API_Reference_v11.md` - Referência completa da API
- `docs/README_Manual_Operacional.md` - Manual operacional
- `GUIA_IMPLEMENTACAO.md` - Guia de implementação detalhado

---

**Documento gerado em:** 07 de Outubro de 2025
**Versão do Sistema:** SecWinDev BioFinger v12
**Autor:** Análise Manus AI

# Organograma Completo do Projeto SecWinDev BioFinger v12

**Data:** 07 de Outubro de 2025
**Versão:** 12.0 (Binding Dinâmico REST/DLL via JSON)
**Documento:** Estrutura Organizacional e Arquitetura do Sistema

---

## 1. Visão Geral do Projeto

O projeto **SecWinDev BioFinger v12** é um sistema completo de gerenciamento biométrico desenvolvido em WLanguage para a plataforma WinDev. O sistema oferece suporte a múltiplos fabricantes de leitores biométricos através de uma arquitetura modular baseada em providers configuráveis.

### Estatísticas do Projeto

| Métrica | Valor |
|---------|-------|
| **Total de Linhas de Código** | 3.060 linhas |
| **Classes Principais** | 2 classes |
| **Estruturas de Dados** | 8 estruturas |
| **Constantes Definidas** | 28 constantes |
| **Métodos Públicos** | 25 métodos |
| **Métodos Privados** | 32 métodos |
| **Providers Suportados** | 7 tipos |
| **Fabricantes Configurados** | 17 configurações |
| **Tabelas de Banco** | 4 tabelas |
| **Arquivos de Configuração** | 18 arquivos JSON |

---

## 2. Estrutura de Diretórios

### 2.1. Estrutura Principal

```
SecWinDev_BioFinger_v12_CONSOLIDADO/
¦
+-- src/ # Código-fonte WLanguage
¦ +-- clsBioFinger_v12_completed.wl (2.394 linhas)
¦ +-- clsSecwinConfig.wl (387 linhas)
¦ +-- clsBioFinger_v11_full.wl (versão anterior)
¦ +-- BioFingerStructures.wl (279 linhas - em biofinger_analysis)
¦
+-- cfg/ # Configurações JSON
¦ +-- secwin_biofinger.config.json (configuração principal)
¦ +-- cfg_mock.json (provider simulado)
¦ +-- cfg_dll_binding.json (DLL genérica)
¦ +-- cfg_rest_binding.json (REST genérico)
¦ +-- cfg_secugen.json (SecuGen)
¦ +-- cfg_suprema.json (Suprema)
¦ +-- cfg_hid.json (HID DigitalPersona)
¦ +-- cfg_aratek_a400.json (Aratek)
¦ +-- cfg_dermalog.json (Dermalog)
¦ +-- cfg_futronic_fs80.json (Futronic)
¦ +-- cfg_idemia_morpho.json (IDEMIA/Morpho)
¦ +-- cfg_mantra_mfs100.json (Mantra)
¦ +-- cfg_nitgen_nbionbsp.json (Nitgen)
¦ +-- cfg_controlid.json (Control iD)
¦ +-- cfg_henry.json (Henry)
¦ +-- cfg_anviz_crosschex.json (Anviz)
¦ +-- cfg_realand.json (Realand)
¦ +-- cfg_zkteco.json (ZKTeco)
¦
+-- sql/ # Scripts de Banco de Dados
¦ +-- secwin_biometrics.sql (schema básico)
¦ +-- secwin_biometrics_complete.sql (schema completo com auditoria)
¦
+-- dll/ # Bibliotecas DLL dos Fabricantes
¦ +-- README_DLLS.txt (instruções)
¦
+-- ssl/ # Certificados SSL/TLS
¦ +-- README_SSL.txt (instruções)
¦
+-- sounds/ # Arquivos de Áudio para Feedback
¦ +-- ok.wav (operação bem-sucedida)
¦ +-- error.wav (erro)
¦ +-- enroll_ok.wav (cadastro OK)
¦ +-- enroll_fail.wav (cadastro falhou)
¦ +-- found.wav (digital encontrada)
¦ +-- not_found.wav (digital não encontrada)
¦
+-- docs/ # Documentação
¦ +-- README_v12_completed.md
¦ +-- API_Reference_v11.md
¦ +-- BUILD_CHECKLIST_v11.md
¦ +-- CHANGELOG.md
¦ +-- LICENSE.txt
¦ +-- README_Manual_Operacional.md
¦ +-- SOUNDS_README.md
¦ +-- branding/
¦ +-- logo_wx.svg
¦
+-- examples/ # Exemplos de Uso
¦ +-- BioFinger_Tests_v11.wl (testes básicos)
¦ +-- WIN_BioFinger_UX_v11.wl (interface de usuário)
¦ +-- exemplo_uso_completo.wl (exemplo completo)
¦ +-- testes_unitarios.wl (testes unitários)
¦
+-- biofinger_analysis/ # Análise e Documentação Detalhada
¦ +-- ANALISE_ESTRUTURA.md
¦ +-- VERIFICACAO_COMPLETUDE.md
¦ +-- VALIDACAO_REQUISITOS.md
¦ +-- RELATORIO_EXECUTIVO.md
¦ +-- README_IMPLEMENTACAO.md
¦ +-- GUIA_IMPLEMENTACAO.md
¦ +-- RESOLUCAO_LACUNAS.md
¦ +-- [mesma estrutura de src/, cfg/, sql/, etc.]
¦
+-- MANIFEST.csv # Manifesto de Arquivos
+-- README.txt # Leia-me Principal
+-- SecWinDev_BioFinger_Manual_v12.pdf # Manual do Sistema
+-- SecWinDev_BioFinger_Site_v12.zip # Site de Documentação
```

---

## 3. Arquitetura de Classes

### 3.1. Classe Principal: clsBioFinger

A classe **clsBioFinger** é o núcleo do sistema, implementando toda a lógica de gerenciamento biométrico.

#### Membros Privados

| Membro | Tipo | Descrição |
|--------|------|-----------|
| `m_oConfig` | clsSecwinConfig | Objeto de configuração |
| `m_bInitialized` | BOOLEAN | Status de inicialização |
| `m_sLastError` | STRING | Última mensagem de erro |
| `m_nProvider` | INT | Provider atual (0-6) |
| `m_oDeviceInfo` | STBioDeviceInfo | Informações do dispositivo |
| `m_hDLL` | INT | Handle da DLL carregada |
| `m_oConnection` | Connection | Conexão de banco de dados |
| `m_bDBConnected` | BOOLEAN | Status de conexão DB |
| `m_sConnectionString` | STRING | String de conexão |
| `m_oStats` | STBioStatistics | Estatísticas do sistema |
| `m_arrTemplateCache` | ARRAY | Cache de templates para 1:N |
| `m_bCacheValid` | BOOLEAN | Validade do cache |

#### Métodos Públicos (25 métodos)

**A) Inicialização (5 métodos)**
- `Initialize(sConfigPath, sDBConnectionString)` - Inicializa o sistema
- `Disconnect()` - Desconecta do dispositivo
- `GetDeviceInfo()` - Retorna informações do dispositivo
- `GetDeviceStatus()` - Verifica status do dispositivo
- `IsInitialized()` - Verifica se está inicializado

**B) Cadastro de Digitais (2 métodos)**
- `EnrollFinger(sLogin, nFingerCode, bCaptureImage)` - Cadastra digital com captura
- `EnrollFingerFromTemplate(sLogin, nFingerCode, bufTemplate, bufImage, nQuality)` - Cadastra a partir de template

**C) Matching e Combinação (4 métodos)**
- `UpdateCombinedMatcher(sLogin)` - Atualiza matcher combinado
- `GetCombinedMatcher(sLogin)` - Obtém matcher combinado
- `VerifyFinger(sLogin, nFingerCode, bufTemplate)` - Verificação 1:1
- `IdentifyFinger(bufTemplate, nMaxResults)` - Identificação 1:N

**D) Busca por Imagem (1 método)**
- `SearchByImage(bufImage, nMaxResults, rMinSimilarity)` - Busca por similaridade de imagem

**E) Atualização (2 métodos)**
- `UpdateFinger(sLogin, nFingerCode, bufTemplate, bufImage, nQuality)` - Atualiza digital
- `UpdateFingerFromCapture(sLogin, nFingerCode, bCaptureImage)` - Atualiza com captura

**F) CRUD e Consultas (6 métodos)**
- `GetFinger(sLogin, nFingerCode)` - Obtém uma digital específica
- `GetFingersByLogin(sLogin)` - Obtém todas as digitais de um usuário
- `FingerExists(sLogin, nFingerCode)` - Verifica existência
- `SearchFingers(stCriteria)` - Busca composta com filtros
- `DeleteFinger(sLogin, nFingerCode)` - Remove digital
- `DeleteFingersByLogin(sLogin)` - Remove todas as digitais de um usuário
- `WipeAll(bConfirm)` - Remove todas as digitais do sistema

**G) Utilitários (5 métodos)**
- `GetLastError()` - Retorna último erro
- `GetConfig()` - Retorna objeto de configuração
- `NotifyStatus(nStatus, sMessage)` - Notifica status
- `GetStatistics()` - Retorna estatísticas do sistema
- `PlaySound(nSoundType)` - Toca som de feedback

#### Métodos Privados (32 métodos)

**Inicialização por Provider**
- `InitializeMock()` - Inicializa provider MOCK
- `InitializeDLL()` - Inicializa provider DLL
- `InitializeREST()` - Inicializa provider REST

**Captura de Imagem**
- `CaptureImage(bufImage, nQuality)` - Captura genérica
- `CaptureMock(bufImage, nQuality)` - Captura simulada
- `CaptureDLL(bufImage, nQuality)` - Captura via DLL
- `CaptureREST(bufImage, nQuality)` - Captura via REST

**Criação de Template**
- `CreateTemplate(bufImage, bufTemplate)` - Criação genérica
- `CreateTemplateMock(bufImage, bufTemplate)` - Template simulado
- `CreateTemplateDLL(bufImage, bufTemplate)` - Template via DLL
- `CreateTemplateREST(bufImage, bufTemplate)` - Template via REST

**Matching 1:1**
- `Match11(bufTemplate1, bufTemplate2, nScore)` - Match genérico
- `Match11Mock(bufTemplate1, bufTemplate2, nScore)` - Match simulado
- `Match11DLL(bufTemplate1, bufTemplate2, nScore)` - Match via DLL
- `Match11REST(bufTemplate1, bufTemplate2, nScore)` - Match via REST

**Processamento de Imagens**
- `CompareImages(bufImage1, bufImage2)` - Compara duas imagens
- `DecomposeCombinedMatcher(stCombined)` - Decompõe matcher combinado

**Banco de Dados**
- `ConnectDB()` - Conecta ao banco
- `DisconnectDB()` - Desconecta do banco
- `InsertFingerDB(stFingerData)` - Insere digital no banco
- `SaveCombinedMatcherDB(stCombined)` - Salva matcher combinado
- `DeleteCombinedMatcher(sLogin)` - Remove matcher combinado
- `LoadTemplateCache()` - Carrega cache de templates
- `GetAllFingersWithImage()` - Obtém todas as digitais com imagem
- `CountFingersByLogin(sLogin)` - Conta digitais por usuário
- `CountAllFingers()` - Conta total de digitais

**Utilitários Internos**
- `LogEvent(sMessage)` - Registra evento em log

---

### 3.2. Classe de Configuração: clsSecwinConfig

A classe **clsSecwinConfig** gerencia o carregamento e validação de arquivos de configuração JSON.

#### Responsabilidades

A classe clsSecwinConfig é responsável por carregar e validar arquivos de configuração JSON que definem os parâmetros de conexão com diferentes providers de dispositivos biométricos. Ela abstrai a complexidade do parsing JSON e fornece uma interface limpa para acesso aos dados de configuração.

#### Funcionalidades Principais

**Carregamento de Configuração**
- Leitura de arquivos JSON do sistema de arquivos
- Parsing e validação de estrutura JSON
- Tratamento de erros de formato e sintaxe

**Validação de Providers**
- Verificação de campos obrigatórios por tipo de provider
- Validação de URLs e caminhos de arquivo
- Checagem de valores válidos para enumerações

**Acesso a Dados**
- Propriedades tipadas para cada campo de configuração
- Métodos auxiliares para obter nomes de providers
- Informações de diagnóstico e debugging

---

## 4. Estruturas de Dados

O sistema define **8 estruturas principais** para organização dos dados:

### 4.1. STBioResult

Estrutura padrão de retorno para todas as operações.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `status` | INT | Código de status (0-10) |
| `message` | STRING | Mensagem descritiva |
| `score` | INT | Score de matching (0-100) |
| `quality` | INT | Score de qualidade (0-100) |
| `data` | VARIANT | Dados adicionais |
| `timestamp` | DATETIME | Timestamp da operação |

### 4.2. STBioFingerData

Dados completos de uma digital cadastrada.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `login` | STRING | Login do usuário |
| `finger_code` | INT | Código do dedo (1-10) |
| `tpl_fmt` | INT | Formato do template |
| `tpl` | BUFFER | Template biométrico |
| `image` | BUFFER | Imagem da digital (opcional) |
| `quality_score` | INT | Score de qualidade |
| `updated_at` | DATETIME | Data de atualização |
| `device_info` | STRING | Informações do dispositivo |

### 4.3. STBioSearchCriteria

Critérios para busca composta de digitais.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `login` | STRING | Filtrar por login |
| `finger_code` | INT | Filtrar por dedo |
| `min_quality` | INT | Qualidade mínima |
| `date_from` | DATETIME | Data inicial |
| `date_to` | DATETIME | Data final |
| `order_by` | STRING | Campo de ordenação |
| `order_desc` | BOOLEAN | Ordem descendente |
| `limit` | INT | Limite de registros |
| `offset` | INT | Offset para paginação |

### 4.4. STBioMatchResult

Resultado de operação de matching 1:N.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `login` | STRING | Login identificado |
| `finger_code` | INT | Código do dedo |
| `score` | INT | Score de matching |
| `rank` | INT | Posição no ranking |

### 4.5. STBioDeviceInfo

Informações sobre o dispositivo biométrico conectado.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `provider` | INT | ID do provider |
| `provider_name` | STRING | Nome do provider |
| `device_name` | STRING | Nome do dispositivo |
| `device_serial` | STRING | Número de série |
| `firmware_version` | STRING | Versão do firmware |
| `sdk_version` | STRING | Versão do SDK |
| `is_connected` | BOOLEAN | Status de conexão |
| `last_error` | STRING | Último erro |

### 4.6. STBioCombinedMatcher

Matcher combinado de múltiplos dedos de um usuário.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `login` | STRING | Login do usuário |
| `finger_codes` | ARRAY OF INT | Códigos dos dedos incluídos |
| `combined_tpl` | BUFFER | Template combinado |
| `individual_tpls` | ARRAY OF BUFFER | Templates individuais |
| `created_at` | DATETIME | Data de criação |
| `tpl_count` | INT | Quantidade de templates |

### 4.7. STBioImageCompareResult

Resultado de comparação de imagens.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `login` | STRING | Login do usuário |
| `finger_code` | INT | Código do dedo |
| `similarity` | REAL | Similaridade (0.0-1.0) |
| `rank` | INT | Posição no ranking |

### 4.8. STBioStatistics

Estatísticas gerais do sistema.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `total_users` | INT | Total de usuários |
| `total_fingers` | INT | Total de digitais |
| `avg_quality` | REAL | Qualidade média |
| `last_enrollment` | DATETIME | Último cadastro |
| `last_verification` | DATETIME | Última verificação |

---

## 5. Constantes do Sistema

### 5.1. Status de Operação (11 constantes)

| Constante | Valor | Descrição |
|-----------|-------|-----------|
| `BIO_STATUS_SUCCESS` | 0 | Operação bem-sucedida |
| `BIO_STATUS_NOT_FOUND` | 1 | Não encontrado |
| `BIO_STATUS_RETRY` | 2 | Tentar novamente |
| `BIO_STATUS_ERROR` | 3 | Erro genérico |
| `BIO_STATUS_EXISTS` | 4 | Já existe |
| `BIO_STATUS_TIMEOUT` | 5 | Timeout |
| `BIO_STATUS_INVALID_QUALITY` | 6 | Qualidade insuficiente |
| `BIO_STATUS_DEVICE_ERROR` | 7 | Erro no dispositivo |
| `BIO_STATUS_DB_ERROR` | 8 | Erro no banco de dados |
| `BIO_STATUS_INVALID_PARAM` | 9 | Parâmetro inválido |
| `BIO_STATUS_NOT_INITIALIZED` | 10 | Não inicializado |

### 5.2. Providers (7 constantes)

| Constante | Valor | Descrição |
|-----------|-------|-----------|
| `BIO_PROVIDER_MOCK` | 0 | Simulação |
| `BIO_PROVIDER_DLL` | 1 | DLL genérica |
| `BIO_PROVIDER_HID` | 2 | HID DigitalPersona |
| `BIO_PROVIDER_SUPREMA` | 3 | Suprema BioMini |
| `BIO_PROVIDER_REST` | 4 | REST genérico |
| `BIO_PROVIDER_REST_TLS` | 5 | REST com TLS |
| `BIO_PROVIDER_HENRY` | 6 | Henry |

### 5.3. Códigos de Dedos (10 constantes)

| Constante | Valor | Descrição |
|-----------|-------|-----------|
| `BIO_FINGER_RIGHT_THUMB` | 1 | Polegar direito |
| `BIO_FINGER_RIGHT_INDEX` | 2 | Indicador direito |
| `BIO_FINGER_RIGHT_MIDDLE` | 3 | Médio direito |
| `BIO_FINGER_RIGHT_RING` | 4 | Anelar direito |
| `BIO_FINGER_RIGHT_LITTLE` | 5 | Mínimo direito |
| `BIO_FINGER_LEFT_THUMB` | 6 | Polegar esquerdo |
| `BIO_FINGER_LEFT_INDEX` | 7 | Indicador esquerdo |
| `BIO_FINGER_LEFT_MIDDLE` | 8 | Médio esquerdo |
| `BIO_FINGER_LEFT_RING` | 9 | Anelar esquerdo |
| `BIO_FINGER_LEFT_LITTLE` | 10 | Mínimo esquerdo |

### 5.4. Tipos de Som (6 constantes)

| Constante | Valor | Descrição |
|-----------|-------|-----------|
| `BIO_SOUND_OK` | 1 | Som de sucesso |
| `BIO_SOUND_ERROR` | 2 | Som de erro |
| `BIO_SOUND_ENROLL_OK` | 3 | Som de cadastro OK |
| `BIO_SOUND_ENROLL_FAIL` | 4 | Som de cadastro falhou |
| `BIO_SOUND_FOUND` | 5 | Som de encontrado |
| `BIO_SOUND_NOT_FOUND` | 6 | Som de não encontrado |

---

## 6. Arquitetura de Banco de Dados

### 6.1. Tabelas Principais

O sistema utiliza **4 tabelas** no PostgreSQL:

#### Tabela: secwin_biometrics

Armazena as digitais individuais cadastradas.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `login` | VARCHAR(100) | Login do usuário (PK) |
| `finger_code` | INT | Código do dedo (PK) |
| `tpl_fmt` | INT | Formato do template |
| `tpl` | BYTEA | Template biométrico |
| `sha256` | VARCHAR(64) | Hash SHA256 do template |
| `image` | BYTEA | Imagem da digital (opcional) |
| `quality_score` | INT | Score de qualidade (0-100) |
| `device_info` | TEXT | Informações do dispositivo |
| `created_at` | TIMESTAMP | Data de criação |
| `updated_at` | TIMESTAMP | Data de atualização |

**Índices:**
- PRIMARY KEY (login, finger_code)
- INDEX idx_sha256 (sha256)
- INDEX idx_quality (quality_score)
- INDEX idx_updated (updated_at)

#### Tabela: secwin_biometrics_combined

Armazena matchers combinados por usuário.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `login` | VARCHAR(100) | Login do usuário (PK) |
| `combined_tpl` | BYTEA | Template combinado |
| `finger_codes` | INT[] | Array de códigos de dedos |
| `tpl_count` | INT | Quantidade de templates |
| `created_at` | TIMESTAMP | Data de criação |
| `updated_at` | TIMESTAMP | Data de atualização |

**Índices:**
- PRIMARY KEY (login)
- INDEX idx_tpl_count (tpl_count)

#### Tabela: secwin_biometrics_history

Auditoria de todas as operações.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `id` | SERIAL | ID sequencial (PK) |
| `login` | VARCHAR(100) | Login do usuário |
| `finger_code` | INT | Código do dedo |
| `operation` | VARCHAR(20) | Operação (INSERT/UPDATE/DELETE) |
| `old_data` | JSONB | Dados antigos |
| `new_data` | JSONB | Dados novos |
| `timestamp` | TIMESTAMP | Data/hora da operação |

**Índices:**
- PRIMARY KEY (id)
- INDEX idx_login_history (login)
- INDEX idx_timestamp_history (timestamp)

#### Tabela: secwin_biometrics_log

Log de eventos do sistema.

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `id` | SERIAL | ID sequencial (PK) |
| `event_type` | VARCHAR(50) | Tipo de evento |
| `message` | TEXT | Mensagem do evento |
| `login` | VARCHAR(100) | Login relacionado (opcional) |
| `status` | INT | Status da operação |
| `timestamp` | TIMESTAMP | Data/hora do evento |

**Índices:**
- PRIMARY KEY (id)
- INDEX idx_event_type (event_type)
- INDEX idx_timestamp_log (timestamp)

### 6.2. Triggers e Views

**Triggers Automáticos:**
- `trg_update_timestamp` - Atualiza automaticamente o campo `updated_at`
- `trg_audit_insert` - Registra INSERTs na tabela de auditoria
- `trg_audit_update` - Registra UPDATEs na tabela de auditoria
- `trg_audit_delete` - Registra DELETEs na tabela de auditoria

**Views de Relatórios:**
- `vw_finger_statistics` - Estatísticas por usuário
- `vw_quality_report` - Relatório de qualidade
- `vw_recent_activity` - Atividades recentes

**Funções PostgreSQL:**
- `fn_cleanup_old_logs(days INT)` - Limpa logs antigos
- `fn_rebuild_combined_matcher(login VARCHAR)` - Reconstrói matcher combinado

---

## 7. Providers e Configurações

### 7.1. Tipos de Providers

O sistema suporta **7 tipos de providers** diferentes:

| ID | Provider | Tipo de Comunicação | Configuração |
|----|----------|---------------------|--------------|
| 0 | MOCK | Simulação em memória | cfg_mock.json |
| 1 | DLL | Binding DLL genérico | cfg_dll_binding.json |
| 2 | HID | DLL específica HID | cfg_hid.json |
| 3 | SUPREMA | DLL específica Suprema | cfg_suprema.json |
| 4 | REST | API REST HTTP | cfg_rest_binding.json |
| 5 | REST_TLS | API REST HTTPS | cfg_rest_binding.json |
| 6 | HENRY | REST customizado | cfg_henry.json |

### 7.2. Fabricantes Configurados (17 configurações)

**Comunicação via DLL (8 fabricantes):**
1. Aratek A400 - `cfg_aratek_a400.json`
2. Dermalog - `cfg_dermalog.json`
3. Futronic FS80 - `cfg_futronic_fs80.json`
4. HID DigitalPersona - `cfg_hid.json`
5. IDEMIA (Morpho) - `cfg_idemia_morpho.json`
6. Mantra MFS100 - `cfg_mantra_mfs100.json`
7. Nitgen NBioBSP - `cfg_nitgen_nbionbsp.json`
8. SecuGen - `cfg_secugen.json`
9. Suprema BioMini - `cfg_suprema.json`

**Comunicação via REST (5 fabricantes):**
10. Anviz CrossChex - `cfg_anviz_crosschex.json`
11. Control iD - `cfg_controlid.json`
12. Henry - `cfg_henry.json`
13. Realand - `cfg_realand.json`
14. ZKTeco - `cfg_zkteco.json`

**Configurações Genéricas (3 configurações):**
15. DLL Binding Genérico - `cfg_dll_binding.json`
16. REST Binding Genérico - `cfg_rest_binding.json`
17. MOCK (Simulação) - `cfg_mock.json`

---

## 8. Fluxo de Operações

### 8.1. Fluxo de Inicialização

```
1. Aplicação chama Initialize(configPath, dbConnection)
?
2. clsBioFinger carrega configuração via clsSecwinConfig
?
3. Valida provider e parâmetros obrigatórios
?
4. Conecta ao banco de dados (se fornecido)
?
5. Inicializa provider específico:
- MOCK: Cria estruturas em memória
- DLL: Carrega DLL e resolve funções
- REST: Valida conectividade e autenticação
?
6. Atualiza m_bInitialized = True
?
7. Retorna STBioResult com status SUCCESS
```

### 8.2. Fluxo de Cadastro (Enroll)

```
1. Aplicação chama EnrollFinger(login, fingerCode, captureImage)
?
2. Valida se sistema está inicializado
?
3. Verifica se digital já existe
?
4. Captura imagem do dispositivo:
- CaptureMock() ou CaptureDLL() ou CaptureREST()
?
5. Cria template biométrico:
- CreateTemplateMock() ou CreateTemplateDLL() ou CreateTemplateREST()
?
6. Calcula SHA256 do template
?
7. Insere no banco de dados (InsertFingerDB)
?
8. Atualiza matcher combinado (UpdateCombinedMatcher)
?
9. Invalida cache de templates
?
10. Toca som de feedback (PlaySound)
?
11. Registra log de evento (LogEvent)
?
12. Retorna STBioResult com status e qualidade
```

### 8.3. Fluxo de Verificação 1:1

```
1. Aplicação chama VerifyFinger(login, fingerCode, template)
?
2. Valida parâmetros
?
3. Se template não fornecido:
- Captura nova imagem
- Cria template
?
4. Busca template cadastrado no banco
?
5. Executa matching 1:1:
- Match11Mock() ou Match11DLL() ou Match11REST()
?
6. Compara score com threshold
?
7. Toca som de feedback (FOUND ou NOT_FOUND)
?
8. Registra log de evento
?
9. Retorna STBioResult com score de matching
```

### 8.4. Fluxo de Identificação 1:N

```
1. Aplicação chama IdentifyFinger(template, maxResults)
?
2. Valida parâmetros
?
3. Se template não fornecido:
- Captura nova imagem
- Cria template
?
4. Carrega cache de templates (LoadTemplateCache)
?
5. Para cada template no cache:
- Executa Match11()
- Armazena score se > threshold
?
6. Ordena resultados por score (descendente)
?
7. Limita a maxResults
?
8. Toca som de feedback
?
9. Registra log de evento
?
10. Retorna ARRAY OF STBioMatchResult
```

---

## 9. Dependências e Integrações

### 9.1. Dependências Externas

**Banco de Dados:**
- PostgreSQL 12+ (recomendado)
- Ou qualquer banco SQL via ODBC/HFSQL

**DLLs de Fabricantes:**
- Cada fabricante fornece sua própria DLL
- Devem ser colocadas no diretório `dll/`
- Drivers do dispositivo devem estar instalados

**Certificados SSL:**
- Para providers REST_TLS
- Certificados CA devem estar no diretório `ssl/`

**Arquivos de Som:**
- Formato WAV
- Localizados no diretório `sounds/`

### 9.2. Integrações com Aplicação

A aplicação WinDev integra-se com o sistema através de:

**1. Instanciação da Classe:**
```wlanguage
oBio IS clsBioFinger = NEW clsBioFinger
```

**2. Inicialização:**
```wlanguage
stResult = oBio.Initialize("cfg/secwin_biofinger.config.json", "DSN=PostgreSQL")
```

**3. Operações Biométricas:**
```wlanguage
// Cadastro
stResult = oBio.EnrollFinger("user01", BIO_FINGER_RIGHT_INDEX, True)

// Verificação
stResult = oBio.VerifyFinger("user01", BIO_FINGER_RIGHT_INDEX)

// Identificação
arrMatches = oBio.IdentifyFinger(Null, 10)
```

**4. Tratamento de Resultados:**
```wlanguage
IF stResult.status = BIO_STATUS_SUCCESS THEN
Info("Operação bem-sucedida! Score: " + stResult.score)
ELSE
Error(stResult.message)
END
```

---

## 10. Boas Práticas Implementadas

O projeto segue rigorosamente as melhores práticas de desenvolvimento WLanguage:

### 10.1. Programação Orientada a Objetos

**Encapsulamento:**
- Membros privados protegidos com palavra-chave `PRIVATE`
- Acesso controlado através de métodos públicos
- Validação de estado em todos os métodos públicos

**Validação de Objetos Dinâmicos:**
- Verificação `IF objeto <> Null` antes de uso
- Tratamento adequado de objetos não alocados

**Tratamento de Erros:**
- Blocos `TRY/EXCEPTION` em operações críticas
- Retorno estruturado com `STBioResult`
- Mensagens de erro descritivas

**Gerenciamento de Memória:**
- Liberação de recursos no destructor
- Limpeza de handles de DLL
- Desconexão de banco de dados

### 10.2. Qualidade de Código

**Nomenclatura:**
- Prefixos consistentes (m_ para membros, st para estruturas)
- Nomes descritivos e auto-explicativos
- Constantes em MAIÚSCULAS com prefixo BIO_

**Documentação:**
- Comentários de cabeçalho em todos os métodos
- Descrição de parâmetros e retornos
- Separação visual de seções

**Modularização:**
- Métodos pequenos e focados
- Separação de responsabilidades
- Reutilização de código

**Validação:**
- Verificação de parâmetros em métodos públicos
- Validação de estado antes de operações
- Confirmação em operações destrutivas

---

## 11. Conclusão

O projeto **SecWinDev BioFinger v12** apresenta uma arquitetura robusta, modular e bem organizada. A estrutura do projeto facilita a manutenção, extensão e integração com diferentes dispositivos biométricos.

### Pontos Fortes

**Arquitetura Modular:** A separação em providers permite fácil adição de novos dispositivos sem alteração no código principal.

**Código Limpo:** Seguindo as melhores práticas de OOP em WLanguage, o código é legível, manutenível e testável.

**Documentação Completa:** O projeto inclui documentação extensa em múltiplos níveis (código, arquivos MD, exemplos).

**Flexibilidade:** Suporte a múltiplos fabricantes, tipos de comunicação e configurações.

**Robustez:** Tratamento abrangente de erros, validações e logging.

**Escalabilidade:** Arquitetura preparada para grandes volumes através de cache, índices e otimizações.

### Estrutura de Arquivos

O projeto está organizado de forma lógica, com separação clara entre código-fonte, configurações, documentação e recursos. A duplicação da estrutura em `biofinger_analysis/` serve como backup e documentação detalhada da implementação.

---

**Documento gerado em:** 07 de Outubro de 2025
**Versão do Sistema:** SecWinDev BioFinger v12
**Autor:** Análise Manus AI

Marcas e Modelos com Suporte no SecWinDev BioFinger v12
O projeto SecWinDev BioFinger v12 oferece suporte abrangente a 17 configurações diferentes de dispositivos biométricos, cobrindo as principais marcas do mercado global através de uma arquitetura flexível baseada em providers configuráveis.

Resumo das Marcas Suportadas
O sistema suporta as seguintes marcas e modelos de leitores biométricos:

Comunicação via DLL (8 marcas):

1. Aratek - Modelo A400 e família A-Series
2. Dermalog - Linha profissional e forense
3. Futronic - Modelos FS80, FS88, FS90
4. IDEMIA (Morpho) - MorphoSmart série MSO
5. Mantra - MFS100 (padrão ISO)
6. Nitgen - Hamster série (DX, Pro, Plus, eNBSP)
7. SecuGen - Hamster série (Pro 20, Plus, Duo), iD-USB
8. HID DigitalPersona - U.are.U 4500, 5160 e linha completa

Comunicação via REST API (5 marcas):
9. Anviz - Linha CrossChex (terminais de ponto)
10. Control iD - iDClass, iDFlex, iDAccess (com TLS/SSL)
11. Henry - Terminais de controle de acesso
12. Realand - Terminais de ponto e acesso
13. ZKTeco - Série iClock e série F (protocolo iClock)

Configurações Genéricas:
14. Binding DLL Genérico - Para qualquer fabricante com SDK DLL
15. Binding REST Genérico - Para APIs REST customizadas
16. Suprema - BioMini série (Plus, Slim, Combo), RealScan
17. MOCK - Provider simulado para testes sem hardware

Marcas Populares por Região
Brasil: Control iD, Henry, Nitgen, SecuGen, SupremaAmérica do Norte: HID DigitalPersona, SecuGen, SupremaEuropa: Dermalog, IDEMIA (Morpho), SecuGenÁsia: Anviz, Futronic, Mantra, Realand, ZKTecoGlobal: SecuGen, Suprema, HID DigitalPersona

Arquitetura de Providers
O sistema utiliza 7 tipos de providers diferentes para comunicação com dispositivos, permitindo flexibilidade total na escolha do hardware e facilitando a migração entre fabricantes sem alteração no código-fonte principal.