CatracaTopData

Aplicação Java para controlar catracas TopData (Fit 4 LC Bio) utilizando a biblioteca nativa EasyInner.dll, com API administrativa embutida.

Build com Maven

O projeto agora utiliza Maven e produz um JAR único autocontido:

mvn clean package

O artefato final fica em target/catraca-topdata.jar. O processo de build inclui automaticamente as dependências, EasyInner.dll, o conteúdo de web/, o config.json padrão e a JRE 32 bits de java832bits/ dentro do JAR.

Execução

Basta executar o JAR em qualquer JVM (32 ou 64 bits):

java -jar target/catraca-topdata.jar

O Launcher embutido fará o seguinte:

• Extrai para o diretório de trabalho (%CATRACA_HOME% ou ~/.catraca-topdata) os arquivos de configuração, web UI, EasyInner.dll e a JRE 32 bits.
• Mantém qualquer config.json que você já tenha personalizado (só cria um novo se não existir).
• Sobe a aplicação real (com.gramadoparks.Init) usando a JRE 32 bits embutida, garantindo compatibilidade com a DLL.

Se quiser alterar o local de extração, defina CATRACA_HOME antes de executar o JAR.

Scripts anteriores

O script build-package.ps1 continua disponível apenas como referência histórica, mas não é mais necessário para gerar os binários portáteis.

API HTTP embutida

Quando o processo principal (Init) é iniciado, o AdminServer sobe em http://localhost:5005 (porta configurável). Toda resposta JSON segue o mesmo envelope:

• success: booleano indicando se a operação foi aceita pelo servidor ou pelo hardware.
• message: código curto em snake_case para facilitar mapeamento no Next.js.
• data: objeto opcional com os dados solicitados.
• Para comandos do Inner, incluímos ainda code (retorno da DLL), name (descrição do código) e inner (número do equipamento). Quando o hardware retorna algo diferente de RET_COMANDO_OK, o HTTP continua 202 e success=false, preservando o código original para o frontend.

CORS e autenticação

Todas as rotas expõem Access-Control-Allow-* padrão para consumo direto do Next.js (dev server ou build). Ainda não há autenticação; quando for necessário ativá-la, padronize respostas 401 via sendApiResponse() (success=false, message="unauthorized"). Enquanto isso não acontece, endpoints ficam abertos na rede local.

Colaboradores e biometrias

Método	Caminho	Descrição
GET	/api/users	Lista colaboradores (data.items, data.total).
POST	/api/users	Cria colaborador (nome, matricula, ativo).
GET	/api/users/{id}	Busca colaborador.
PUT	/api/users/{id}	Atualiza campos informados.
DELETE	/api/users/{id}	Remove colaborador.
POST	/api/users/{id}/activate / inactivate	Alterna flag ativo.
GET	/api/users/{id}/biometry	Retorna biometria atrelada.
POST	/api/users/{id}/biometry	Salva template base64 (templateBase64, origem).
POST	/api/users/{id}/biometry/capture?inner=1	Captura direto do Inner e persiste.
DELETE	/api/users/{id}/biometry	Remove biometria.

Principais validações/exceções:

• 400 nome_matricula_obrigatorios, nome_invalido, matricula_invalida, payload_invalido.
• 404 colaborador_nao_encontrado, biometria_nao_encontrada.
• Violação de matricula duplicada gera 409 valor_duplicado.

Comandos do Inner

Os comandos expostos pelo antigo serviço C# foram espelhados em dois prefixos equivalentes: /inner/... e /api/inner/.... O parâmetro inner (query string) é opcional e assume 1 por padrão.

Método	Caminho	Ação	Observações
GET	/inner/ping	EasyInner.Ping	Verifica comunicação básica.
GET	/inner/ping-online	EasyInner.PingOnLine	Mantém equipamento online.
GET	/inner/bip	AcionarBipCurto	Bip curto.
GET	/inner/bip-longo (/biplongo)	AcionarBipLongo	Bip longo.
GET	/inner/liberar/entrada	LiberarCatracaEntrada	Demais modos: /saida, /entrada-invertida, /saida-invertida, /dois-sentidos.
GET	/inner/led/vermelho/ligar	LigarLedVermelho	/desligar usa DesligarLedVermelho.
GET	/inner/led/verde/ligar	LigarLedVerde	A DLL atual não expõe DesligarLedVerde; respondemos 501 led_verde_desligar_indisponivel.
GET	/inner/rele/{1|2}/acionar	AcionarRele{n}	/manter reutiliza o mesmo comando; /desligar usa DesabilitarRele{n}.
GET	/inner/receber-online	ReceberDadosOnLine	Retorna origem, complemento, cartão e timestamp do bilhete online.

Erros de validação retornam mensagens padronizadas (inner_invalido, modo_liberar_invalido, led_acao_invalida, rele_parametros_invalidos, etc.) sempre com success=false para facilitar o mapeamento do frontend. Em caso de exceção interna, respondemos 500 {acao}_falhou e anexamos data.erro com a mensagem raiz.

A partir desta etapa as rotas /inner/liberar/* (e o POST legado /api/turnstile/release) não falam mais com a DLL diretamente. O comando é enfileirado no Machine, que assume a sincronização com o polling e conclui a liberação no próximo ciclo do estado ESTADO_LIBERAR_CATRACA. As respostas HTTP continuam retornando code: 0, mas incluem queued: true para sinalizar que a operação foi aceita e será executada assíncronamente. Caso o processo Machine não esteja ativo, os endpoints fazem um fallback para o comportamento antigo (invocação direta do EasyInner). Além disso, o loop do Machine deixou de consultar a API externa de ingressos (/catraca/consulta-ticket/valida-ticket): qualquer validação de credencial ou fluxo de negócios associado deve ser feita pelo app Next antes de solicitar uma liberação.

Exemplo

curl "http://localhost:5005/inner/liberar/entrada?inner=2"
# {
#   "success": true,
#   "code": 0,
#   "name": "RET_COMANDO_OK",
#   "message": "liberar_entrada",
#   "inner": 2,
#   "mode": "entrada",
#   "queued": true
# }