Como Migrar de uma Instalação Legada

Este guia importa os dados existentes de uma instalação antiga do HandyCafe V3 ou V4 para um servidor HandyCafe moderno. A migração não altera nem apaga os arquivos de origem.

A migração de banco de dados roda apenas no Windows. O suporte em tempo de execução para clientes legados se conectarem pelo protocolo original funciona em todas as plataformas (consulte Configurações de Clientes Legados).

O que você vai precisar

• Uma máquina Windows com a instalação legada e o servidor moderno do HandyCafe no mesmo sistema, ou acesso ao arquivo de banco de dados legado.
• Acesso de administrador ao HandyCafe Server.
• O servidor legado parado. O banco de origem não deve receber gravações durante a migração.
• Espaço livre em disco pelo menos igual ao tamanho do banco legado (para a nova cópia do banco do HandyCafe).
• Entre 10 e 30 minutos de tempo sem interrupções. Migrações em bases grandes podem levar vários minutos. Não feche o HandyCafe durante o processo.

Passo 1: Pare o servidor legado

Abra o aplicativo do servidor antigo do HandyCafe. Encerre todas as sessões e feche o aplicativo. Se o servidor legado roda como serviço do Windows, pare o serviço em services.msc.

Resultado esperado: O processo do servidor legado não está mais em execução. O arquivo de banco não fica mais aberto.

Passo 2: Abra a página de configurações de clientes legados

1. Inicie o HandyCafe.
2. Abra Configurações na barra lateral.
3. Clique em Clientes Legados.
4. Role até a seção Migração de Banco de Dados.

Resultado esperado: Se o sistema detectar uma instalação legada, a página mostra o caminho da instalação, o caminho do banco de dados, a versão do servidor e a contagem de arquivos INI. Se nada for detectado, a página mostra "Nenhuma instalação legada detectada." Nesse caso, confirme que os arquivos antigos existem em um local padrão, como Program Files\HandyCafe ou C:\HandyCafe.

Passo 3: Revise a instalação detectada

Confirme se os valores detectados batem com a sua instalação legada conhecida:

Se algum campo estiver errado, feche o HandyCafe, corrija a instalação e abra novamente.

Passo 4: Verifique o campo de codificação

Antes de iniciar a migração, confirme se o campo Codificação na seção do Protocolo em Tempo de Execução está configurado corretamente para os seus dados de origem. Essa opção fica na mesma página de configurações, mais acima.

Se você alterar a codificação, clique em Salvar antes de continuar.

Resultado esperado: As strings da origem serão decodificadas corretamente durante a migração, evitando um resultado completed_with_warnings.

Passo 5: Inicie a migração

1. Clique em Iniciar Migração.
2. Uma janela de progresso é aberta. Ela mostra a fase atual e o número de linhas processadas até o momento.
3. Não feche o HandyCafe nem coloque o computador para dormir.
4. Aguarde a conclusão. Bases pequenas terminam em menos de um minuto. Bases maiores podem levar de 5 a 10 minutos.

Resultado esperado: A janela de progresso se fecha e o status muda para completed ou completed_with_warnings. Uma notificação aparece confirmando a execução.

Passo 6: Revise as contagens migradas

Após a conclusão, a página mostra as contagens dos registros migrados:

Clique no expansor Detalhes para ver o detalhamento completo. Confirme se as contagens fazem sentido em relação ao que você esperava.

Resultado esperado: As quatro categorias principais (membros, produtos, pedidos e transações) mostram contagens diferentes de zero se a origem tinha dados nessas tabelas.

Passo 7: Trate os avisos, se houver

Se o status for completed_with_warnings, expanda a lista de avisos e revise os registros ignorados.

Avisos comuns e suas correções:

Resultado esperado: Você aceita os avisos como perdas conhecidas e aceitáveis ou corrige o problema de origem e executa novamente.

Passo 8: Confira dados importados manualmente

Antes de desativar o servidor legado, verifique manualmente uma amostra de cada tipo de registro.

1. Abra Membros na barra lateral. Procure um membro que você conhece do sistema legado. Confirme nome, saldo e informações de contato.
2. Abra Configurações > Preços. Confirme se as tarifas por hora correspondem à agenda legada.
3. Abra Produtos. Confirme nomes e preços dos produtos.
4. Abra Relatório de Caixa em um dia histórico recente. Confirme se os totais batem com o que você espera do sistema legado.

Resultado esperado: As amostras escolhidas coincidem com a origem legada. Se um registro específico estiver errado, anote o problema. Pequenas diferenças de formatação são normais. Divergências grandes de valores sugerem um problema de codificação ou integridade de dados que vale investigar antes de entrar em produção.

Passo 9: Ative o suporte em tempo de execução para clientes legados (opcional)

Se você quiser que as máquinas V3 ou V4 existentes continuem conectando enquanto faz a transição, ative agora o protocolo em tempo de execução.

1. Role até o topo da página de configurações de Clientes Legados.
2. Ative Habilitar Suporte a Clientes Legados.
3. Confirme se as portas de escuta (UDP 710, TCP 712, transferência de arquivos 717) não conflitam com nada na sua rede.
4. Clique em Salvar.

Resultado esperado: Os clientes legados na LAN aparecem no Painel Administrativo em 5 a 10 segundos. Consulte Clientes Legados para ver como gerenciá-los pelo painel.

Como desfazer uma migração

Se a migração produzir resultados inesperados, você pode reverter tudo por completo. O banco legado original não é alterado.

1. Abra Configurações > Clientes Legados.
2. Role até a seção Migração de Banco de Dados.
3. Clique em Desfazer Migração.
4. Confirme na janela.

Todas as linhas migradas são excluídas do HandyCafe. O status volta para never. Em seguida, você pode corrigir o problema de origem (codificação, limpeza de dados, etc.) e executar Iniciar Migração novamente.

Como executar a migração novamente

Executar novamente substitui os dados migrados por dados novos da origem.

1. Abra Configurações > Clientes Legados.
2. Clique em Executar Novamente (o botão muda de Iniciar Migração depois da primeira execução concluída).
3. O fluxo é idêntico ao da primeira execução.

Executar novamente é seguro quantas vezes forem necessárias. Ele não duplica dados porque substitui a saída da migração existente.

Erros comuns para evitar

• Executar a migração enquanto o servidor legado está ativo. O banco de origem pode estar bloqueado ou conter gravações parciais. Sempre pare o servidor legado primeiro.
• Ignorar o campo Codificação. Executar com a codificação errada corrompe nomes de membros e mensagens de log. Corrigir depois exige Desfazer e Executar Novamente.
• Fechar o HandyCafe durante a migração. A execução é interrompida e dados parciais são gravados. A recuperação exige Desfazer. Sempre deixe a janela de progresso terminar.
• Pular a verificação manual. Confiar apenas nas contagens sem conferir exemplos de dados perde problemas sutis, como divergências de localidade ou arredondamento.
• Apagar a instalação legada cedo demais. Mantenha os arquivos de origem por pelo menos um ciclo completo de faturamento após a migração. Se surgir uma divergência em um relatório mensal, você ainda poderá consultar os registros originais.
• Migrar sem backup. Copie a pasta da instalação legada antes da primeira migração. Embora a origem não seja alterada pelo processo, problemas de disco ou acidentes podem acontecer. Um backup é um seguro barato.