如何从旧版安装迁移
本指南会将您现有的 HandyCafe V3 或 V4 旧安装数据导入现代 HandyCafe 服务端。迁移过程对源数据是非破坏性的：原始文件不会被修改或删除。
数据库迁移仅在 Windows 上运行。旧版客户端按原始协议连接的运行时支持则可在所有平台上使用（参见旧版客户端设置）。
您需要准备什么
- 一台 Windows 机器，旧版安装和现代 HandyCafe 服务端都位于同一系统上，或者可以访问旧版数据库文件。
- HandyCafe Server 的管理员访问权限。
- 已停止运行的旧版服务端。迁移时，源数据库不应处于写入状态。
- 至少与旧版数据库大小相当的可用磁盘空间（用于新的 HandyCafe 数据库副本）。
- 10 到 30 分钟不中断的时间。大数据集的迁移可能需要几分钟。运行期间请勿关闭 HandyCafe。
第 1 步：停止旧版服务端
打开旧版 HandyCafe 服务端应用。停止所有时段并退出程序。如果旧版服务端是以 Windows 服务运行，请在 services.msc 中停止该服务。
预期结果： 旧版服务端进程已经不再运行，数据库文件也没有被占用。
第 2 步：打开旧版客户端设置页
- 启动 HandyCafe。
- 在侧边栏中打开 设置。
- 点击 旧版客户端。
- 滚动到 数据库迁移 区域。
预期结果： 如果系统检测到旧版安装，页面会显示安装路径、数据库路径、服务端版本和 INI 文件数量。如果没有检测到，页面会显示“未检测到旧版安装”。此时请确认旧版文件确实位于诸如 Program Files\HandyCafe 或 C:\HandyCafe 这样的标准位置。
第 3 步：检查检测到的安装
确认检测出的值与您已知的旧版安装相符：
| 字段 | 检查内容 |
|---|---|
| 安装路径 | 指向正确的 HandyCafe 文件夹。 |
| 数据库路径 | 指向安装目录中的旧版数据库文件。 |
| 服务端版本 | 与您的旧版服务端版本一致（例如 3.4.01 或 4.0.10）。 |
| INI 文件数量 | 非零。正常安装通常会有多个用于不同配置的 INI 文件。 |
如果任何字段不正确，请关闭 HandyCafe、修复安装，然后重新打开。
第 4 步：检查编码字段
在运行迁移之前，请确认运行时协议区域中的 编码 字段已针对源数据设置正确。这个字段就在同一设置页的上方。
| 源地区 | 推荐编码 |
|---|---|
| 土耳其 | cp1254 |
| 西欧（英语、法语、德语、西班牙语、意大利语、葡萄牙语） | cp1252 |
| 其他 | cp1254（服务端会把它作为默认回退值） |
如果您更改了编码，请先保存再继续。
预期结果： 源字符串在迁移期间会被正确解码，从而避免出现 completed_with_warnings 结果。
第 5 步：开始迁移
- 点击 开始迁移。
- 会打开一个进度弹窗，显示当前阶段和已处理的行数。
- 不要关闭 HandyCafe，也不要让电脑进入睡眠。
- 等待完成。小数据集通常不到一分钟即可完成。较大的数据集可能需要 5 到 10 分钟。
预期结果： 进度弹窗关闭，状态变为 completed 或 completed_with_warnings。系统会弹出通知，确认这次运行已经完成。
第 6 步：查看已迁移计数
完成后，页面会显示已迁移记录数：
| 计数 | 含义 |
|---|---|
| 会员 | 已导入的顾客记录。 |
| 定价 | 已导入的价格表和排期条目。 |
| 商品 | 已导入的商品目录条目。 |
| 订单 | 已导入的历史订单。 |
| 交易 | 已导入的账本条目。 |
| 日志 | 已导入的审计与警告日志。 |
| 警告 | 导入过程中被跳过的记录。仅在状态为 completed_with_warnings 时显示。 |
点击“详情”展开项可以查看完整明细。请根据您的预期检查这些计数是否合理。
预期结果： 如果源数据中这些表都有内容，那么会员、商品、订单和交易四类至少应当显示非零计数。
第 7 步：处理警告（如有）
如果状态为 completed_with_warnings，请展开警告列表并查看被跳过的记录。
常见警告及其处理方式如下：
| 警告 | 原因 | 处理方法 |
|---|---|---|
| 编码解码错误 | 源文本包含无法使用当前编码解码的字节。 | 运行撤销迁移，修改编码字段以匹配源地区，然后重新运行迁移。 |
| 日期格式错误 | 某条旧版记录包含无效时间戳（例如 0000-00-00）。 |
这些会被安全跳过，无需处理。 |
| 重复键 | 某条记录的标识符已经存在于 HandyCafe 中。 | 如果这是一次无意的重复迁移，请先撤销迁移，然后重新运行迁移；如果您是在合并数据库，则可以接受该跳过。 |
预期结果： 您要么接受这些可知的警告损失，要么修复底层问题后重新运行。
第 8 步：抽查导入数据
在退役旧版服务端之前，请手动验证每种记录类型的样本。
- 在侧边栏打开 会员。搜索一位您在旧系统中认识的会员，确认姓名、余额和联系信息。
- 打开 设置 > 定价。确认小时费率与旧版排期一致。
- 打开 商品。确认商品名称和价格。
- 打开最近某一天的 财务报表。确认总计与旧系统中的预期一致。
预期结果： 随机抽查的样本与旧版源数据一致。如果某条记录有误，请记录下来。轻微的格式差异是正常的。若出现明显数值不一致，则很可能是编码或数据完整性问题，值得在正式上线前进一步排查。
第 9 步：启用旧版客户端运行时支持（可选）
如果您希望现有的 V3 或 V4 客户端机器在过渡期间继续接入，可以现在启用运行时协议。
- 滚动回旧版客户端设置页顶部。
- 打开 启用旧版客户端支持。
- 确认侦听端口（UDP 710、TCP 712、文件传输 717）不会与网络中的其他服务冲突。
- 点击保存。
预期结果： 局域网中的旧版客户端会在 5 到 10 秒内出现在管理面板中。有关如何在面板中管理它们，请参阅旧版客户端。
如何撤销迁移
如果迁移结果不符合预期，您可以将其完全回滚。原始旧版数据库不会被修改。
- 打开 设置 > 旧版客户端。
- 滚动到数据库迁移区域。
- 点击 撤销迁移。
- 在对话框中确认。
所有已迁移的行都会从 HandyCafe 中删除。状态会回到 never。之后您可以修正底层问题（编码、源数据清理等），再运行“开始迁移”。
如何重新运行迁移
重新运行会使用源数据中的最新内容替换已迁移的数据。
- 打开 设置 > 旧版客户端。
- 点击 重新运行迁移（在第一次完成运行后，该按钮会从“开始迁移”改名）。
- 流程与初次运行完全相同。
只要需要，您可以安全地多次重新运行。它不会重复写入数据，因为它会替换已有的迁移输出。
应避免的常见错误
- 在旧版服务端仍在运行时执行迁移。 源数据库可能被锁定，或者包含部分写入。请始终先停止旧版服务端。
- 忽略编码字段。 使用错误编码会损坏会员姓名和日志消息。事后修复必须先撤销迁移，再重新运行迁移。
- 在迁移过程中关闭 HandyCafe。 运行会被中断，并且只写入部分数据。恢复通常需要撤销迁移。请务必让进度弹窗完成。
- 跳过抽查步骤。 只看记录数而不验证样本数据，很容易忽略地区编码或四舍五入错误之类的细微问题。
- 过早删除旧版安装。 在迁移后至少保留源文件一个完整结算周期。如果月报中出现差异，您还能参考原始记录。
- 没有备份就开始迁移。 在第一次迁移前，请先复制旧版安装文件夹。虽然迁移不会修改源数据，但磁盘问题或意外仍有可能发生。备份是便宜而有效的保险。