Configurações de Clientes Legados
O HandyCafe funciona ao lado de instalações antigas de clientes V3 e V4 sem interromper o ambiente. A página Configurações de Clientes Legados controla dois recursos distintos:
- Protocolo em tempo de execução. Habilita os listeners de rede que permitem que clientes V3 e V4 se conectem a este servidor nas portas originais.
- Migração de banco de dados. Importa, de forma opcional, membros, preços, produtos, pedidos, transações e logs de uma instalação local antiga para o novo banco de dados do HandyCafe. Esse recurso funciona apenas no Windows.
Os dois recursos são independentes. Você pode habilitar o suporte em tempo de execução sem migrar dados, migrar dados sem habilitar o suporte em tempo de execução, ou fazer os dois.
Seção do protocolo em tempo de execução
Ativar suporte a clientes legados
Um alternador principal no topo da seção. Quando ativado, o servidor inicia três listeners de rede:
- Um listener UDP no grupo multicast configurado.
- Um listener TCP de comandos em
porta UDP + 2. - Um listener TCP de transferência de arquivos em
porta UDP + 7.
Desativar o alternador interrompe os três listeners de forma atômica. Você pode ajustar números de porta ou a codificação enquanto ele estiver desligado e depois reativar para aplicar as mudanças.
Campos de configuração
| Campo | Padrão | Descrição |
|---|---|---|
| Chave de autenticação | HANDYCAFE | Uma chave compartilhada de 10 caracteres. Cada quadro de entrada e saída carrega essa string. Quadros que não coincidirem são descartados. Todos os clientes legados devem usar a mesma chave. |
| IP multicast UDP | 230.4.4.46 | O grupo multicast usado para beacons de descoberta do cliente e para o despacho de comandos via UDP. Na maioria das compilações legadas, esse valor é fixo no código. |
| Porta UDP do servidor | 710 | Porta UDP na qual o servidor escuta beacons e comandos dos clientes. Os clientes legados enviam para esta porta. |
| Porta UDP do cliente | 711 | Porta UDP na qual os clientes legados escutam. O servidor envia comandos de gerenciamento unicast para esta porta no IP do cliente descoberto. |
| Codificação | cp1254 | Codificação de caracteres para os campos de string do formato de rede. Use cp1254 para instalações turcas e cp1252 para europeias ocidentais. Valores desconhecidos voltam para cp1254 com um aviso no log do servidor. |
| Versão do servidor | 3.4.01 | A string de versão transmitida em cada beacon UDP. Alguns clientes legados rejeitam quadros de versões que não reconhecem. Ajuste para corresponder à versão do seu servidor original. |
| Variante de protocolo | STE | Seleção do formato de rede. Veja a comparação de variantes abaixo. |
| Tempo limite de inatividade | 10 | Segundos. Um watchdog por MAC. Se nenhum tráfego chegar de um cliente dentro dessa janela, o cliente é marcado como offline. Uma folga de 10 segundos funciona bem para clientes legados que enviam beacons a cada 2 ou 3 segundos. |
Portas derivadas
Abaixo do formulário, a página mostra uma linha somente leitura com as portas TCP derivadas:
Porta TCP de comandos: 712 Porta de transferencia de arquivos: 717
Essas portas são calculadas a partir da porta UDP do servidor. Elas não são configuradas separadamente. Se você mudar a Porta UDP do Servidor para outro valor, as portas derivadas acompanham essa mudança.
Variante de protocolo
O campo Variante de protocolo seleciona o formato de rede usado pelo servidor. Escolha a variante que corresponde à forma como seu servidor legado foi construído.
| Variante | Quando usar |
|---|---|
| STE (Smart/Turbo Edition) | A base de código legada mais moderna. Adiciona um prefixo de informações de licença de 70 bytes à estrutura do quadro. O tamanho do quadro é 1337 bytes. Use esta opção se sua instalação legada era das edições Smart ou Turbo. |
| Standard | A compilação legada básica. O tamanho do quadro é 1267 bytes sem o prefixo de informações de licença. Use esta opção apenas se sua instalação legada era uma edição Standard sem registro de licença. |
Escolher a variante errada faz com que quadros sejam descartados ou lidos incorretamente. Os sintomas incluem clientes aparecendo online, mas ignorando todos os comandos, ou dados de comando deslocados pelo offset de 70 bytes.
Coexistência com clientes modernos
As portas legadas (710, 711, 712, 717) são completamente separadas das portas do protocolo moderno do HandyCafe (TCP 5001, 5002, 5003, UDP 5004). As duas pilhas de protocolo rodam ao mesmo tempo sem conflito. Você pode misturar clientes antigos e novos na mesma LAN e gerenciá-los pelo mesmo Painel Administrativo.
Aplicando as mudanças
Cada campo da seção Protocolo em tempo de execução é salvo com o botão global Salvar na parte inferior da página. Ao salvar, o servidor:
- Interrompe os três listeners legados se eles estiverem em execução.
- Valida a chave de autenticação (não pode estar vazia).
- Monta novas configurações de listener a partir dos campos atualizados.
- Reinicia os listeners em paralelo.
- Dispara uma notificação quando os três voltarem a ficar online.
Se uma porta já estiver em uso por outro processo, o servidor mostra um erro e o alternador volta para desligado. Verifique firewall e outros serviços com netstat e escolha uma faixa de portas livre.
Seção de migração de banco de dados (apenas Windows)
Esse recurso só está disponível quando o HandyCafe roda no Windows. No macOS e no Linux, a seção mostra o aviso: "A migração de banco de dados é suportada apenas no Windows."
Detecção
Ao abrir a página, o servidor procura uma instalação legada no sistema. A detecção verifica:
- O registro e caminhos de instalação comuns, como
Program Files\HandyCafeeC:\HandyCafe. - O arquivo de banco ao lado da instalação.
- Arquivos de configuração INI no diretório de instalação.
Quando a detecção funciona, a página mostra:
| Rótulo | Significado |
|---|---|
| Caminho da instalação | Onde a instalação legada fica no disco. |
| Caminho do banco | Caminho completo do arquivo de banco legado. |
| Versão do servidor | Valor interpretado a partir da configuração legada. |
| Contagem de arquivos INI | Número de arquivos de configuração detectados. Útil para conferir se a instalação está completa. |
Se nenhuma instalação for detectada, a página mostra "Nenhuma instalação legada detectada." Você ainda pode habilitar o suporte em tempo de execução; o recurso de migração simplesmente não terá nada para importar.
Status da migração
A página acompanha o histórico da migração:
| Status | Significado |
|---|---|
never |
Você ainda não executou uma migração. |
in_progress |
Uma migração está em andamento. Não feche o servidor durante esse estado. |
completed |
A migração mais recente terminou sem avisos. |
completed_with_warnings |
A migração mais recente terminou, mas alguns registros foram ignorados (por exemplo, por erros de codificação ou datas malformadas). Revise os avisos antes de prosseguir. |
undone |
A migração mais recente foi revertida. |
Depois da primeira execução bem-sucedida, o botão Iniciar Migração passa a ser rotulado como Executar Novamente.
O que é migrado
| Tabela | Descrição |
|---|---|
| Membros | Registros de clientes com nomes, contato e saldos de conta. |
| Preços | Tabelas de preços e tarifas por hora. |
| Produtos | Entradas do catálogo de produtos. |
| Pedidos | Histórico de pedidos com referências de sessão. |
| Transações | Lançamentos contabilizados com horários, valores e métodos de pagamento. |
| Logs | Entradas de auditoria e avisos do banco legado. |
A garantia de "arquivos seguros"
A página mostra um aviso em azul: "Os arquivos originais do banco de dados não são apagados. Você pode removê-los com segurança depois que a migração for confirmada." A migração é somente leitura na origem. Mesmo que você execute a migração várias vezes, o banco legado original permanece intocado. Isso permite testar a importação, revisar contagens e desfazer sem risco.
Iniciar, executar novamente e desfazer
- Iniciar Migração. Abre uma janela de progresso. A janela mostra a fase atual e as contagens de registros enquanto a importação acontece. Não feche o HandyCafe durante esse período.
- Executar Novamente. Disponível depois de uma execução concluída. Roda a importação do zero. A nova importação substitui os dados anteriores no HandyCafe.
- Desfazer Migração. Disponível depois de uma execução concluída. Abre uma janela de confirmação. Ao confirmar, cada linha migrada é excluída do HandyCafe. A origem legada não é tocada. Depois de desfazer, o status volta para
never.
Concluída com avisos
Se a migração terminar com completed_with_warnings, uma faixa amarela aparece com um link de Detalhes. Clique para expandir a lista de registros ignorados com o motivo. Motivos comuns:
- Desencontro de codificação. A linha de origem contém caracteres que não decodificam corretamente na codificação configurada. Altere o campo Codificação (cp1254 ou cp1252) e execute a migração novamente.
- Datas malformadas. Alguns registros legados possuem carimbos de hora inválidos. Eles são ignorados para que as linhas válidas ainda sejam importadas.
- Chaves duplicadas. Um registro com o mesmo identificador já existe no HandyCafe. A migração preserva o registro existente e ignora a duplicata.
Dicas
- Pare o servidor legado antes de executar uma migração. Se o sistema legado ainda estiver gravando no banco, a importação pode enxergar dados antigos ou parciais.
- Ajuste o campo Codificação para a localidade do seu legado antes da primeira migração. Alterar isso depois que os dados já foram importados não corrige nomes que já tenham sido corrompidos.
- Sempre rode primeiro uma migração de teste. Confira as contagens em "Contagens finais" e revise algumas linhas de membros e transações antes de liberar a equipe para o novo sistema.
- Habilite o suporte em tempo de execução e mantenha seus clientes legados conectados durante o período de transição. Isso permite verificar se o novo servidor os atende da mesma forma antes de aposentar o servidor antigo.
- Se você mudar a Porta UDP do Servidor, lembre-se de que as portas derivadas de comando e transferência de arquivos também mudam. As regras de firewall precisam ser atualizadas de acordo.