レガシーインストールからの移行方法

このガイドでは、古いHandyCafe V3またはV4のインストールから最新のHandyCafeサーバーに既存のデータをインポートします。移行はソースに対して非破壊的であり、元のファイルは変更または削除されません。

データベースの移行はWindowsでのみ実行されます。レガシークライアントが元のプロトコルで接続するためのランタイムサポートはすべてのプラットフォームで動作します（レガシークライアント設定を参照）。

必要なもの

• レガシーインストールと最新のHandyCafeサーバーが同じシステム上にあるWindowsマシン、またはレガシーデータベースファイルへのアクセス。
• HandyCafeサーバーへの管理者アクセス。
• レガシーサーバーが停止していること。移行中にソースデータベースがアクティブに書き込まれていないこと。
• レガシーデータベースのサイズと同等の空きディスクスペース（新しいHandyCafeデータベースコピー用）。
• 10〜30分の中断のない時間。大規模なデータセットの移行には数分かかることがあります。実行中にHandyCafeを閉じないでください。

ステップ1: レガシーサーバーを停止する

レガシーHandyCafeサーバーアプリケーションを開きます。すべてのセッションを停止し、アプリケーションを終了します。レガシーサーバーがWindowsサービスとして実行されている場合は、services.mscからサービスを停止します。

期待される結果: レガシーサーバープロセスが実行されていない。データベースファイルが開かれていない。

ステップ2: レガシークライアント設定ページを開く

1. HandyCafeを起動します。
2. サイドバーの設定を開きます。
3. レガシークライアントをクリックします。
4. データベース移行セクションまでスクロールします。

期待される結果: システムがレガシーインストールを検出すると、インストールパス、データベースパス、サーバーバージョン、INIファイル数が表示されます。何も検出されない場合は、「レガシーインストールが検出されません」と表示されます。その場合、レガシーファイルがProgram Files\HandyCafeやC:\HandyCafeなどの標準的な場所に存在することを確認してください。

ステップ3: 検出されたインストールを確認する

検出された値が既知のレガシーインストールと一致することを確認します:

どのフィールドも間違っている場合は、HandyCafeを閉じてインストールを修正し、再度開きます。

ステップ4: エンコーディングフィールドを確認する

移行を実行する前に、ランタイムプロトコルセクションのエンコーディングフィールドがソースデータに対して正しく設定されていることを確認します。同じ設定ページの上部にあります。

エンコーディングを変更した場合は、続行する前に保存をクリックしてください。

期待される結果: 移行中にソース文字列が正しくデコードされ、completed_with_warningsの結果を回避します。

ステップ5: 移行を開始する

1. 移行を開始をクリックします。
2. 進行状況モーダルが開きます。現在のフェーズとこれまでに処理された行数が表示されます。
3. HandyCafeを閉じたり、コンピュータをスリープ状態にしないでください。
4. 完了を待ちます。小さなデータセットは1分以内に終了します。大きなデータセットは5〜10分かかることがあります。

期待される結果: 進行状況モーダルが閉じ、ステータスがcompletedまたはcompleted_with_warningsに変わります。実行を確認する通知が表示されます。

ステップ6: 移行されたカウントを確認する

完了後、ページに移行されたレコードのカウントが表示されます:

詳細エクスパンダーをクリックして、完全な内訳を確認します。カウントが期待に対して妥当であることを確認してください。

期待される結果: ソースにデータがあった場合、すべてのカテゴリ（メンバー、商品、注文、取引）がゼロでないカウントを示します。

ステップ7: 警告の処理（ある場合）

ステータスがcompleted_with_warningsの場合、警告リストを展開してスキップされたレコードを確認します。

一般的な警告とその修正:

期待される結果: 警告を既知の許容可能な損失として受け入れるか、根本的な問題を修正して再実行します。

ステップ8: インポートされたデータをスポットチェックする

レガシーサーバーを退役させる前に、各レコードタイプのサンプルを手動で確認します。

1. サイドバーのメンバーを開きます。レガシーシステムから知っているメンバーを検索し、名前、残高、連絡先情報を確認します。
2. 設定 > 価格設定を開きます。時間料金がレガシースケジュールと一致していることを確認します。
3. 商品を開きます。商品名と価格を確認します。
4. 最近の履歴日付のキャッシュレポートを開きます。合計がレガシーシステムから期待するものと一致していることを確認します。

期待される結果: ランダムサンプルがレガシーソースと一致します。特定のレコードが間違っている場合は、問題を記録します。小さなフォーマットの違いは通常です。大きな値の不一致は、エンコーディングやデータの整合性の問題を示唆しており、本番稼働前に調査する価値があります。

ステップ9: レガシークライアントランタイムサポートを有効にする（オプション）

既存のV3またはV4クライアントマシンを移行中に接続し続けたい場合は、今すぐランタイムプロトコルを有効にします。

1. レガシークライアント設定ページの上部までスクロールします。
2. レガシークライアントサポートを有効にするをオンに切り替えます。
3. リスナーポート（UDP 710、TCP 712、ファイル転送717）がネットワーク上の他のものと競合していないことを確認します。
4. 保存をクリックします。

期待される結果: LAN上のレガシークライアントが5〜10秒以内に管理パネルに表示されます。パネルからの管理方法についてはレガシークライアントを参照してください。

移行を元に戻す方法

移行が予期しない結果をもたらした場合、完全に元に戻すことができます。元のレガシーデータベースは変更されません。

1. 設定 > レガシークライアントを開きます。
2. データベース移行セクションまでスクロールします。
3. 移行を元に戻すをクリックします。
4. ダイアログで確認します。

移行されたすべての行がHandyCafeから削除されます。ステータスはneverに戻ります。その後、根本的な問題（エンコーディング、ソースデータのクリーンアップなど）を修正し、再度移行を開始できます。

移行を再実行する方法

再実行すると、移行されたデータがソースからの新しいデータで置き換えられます。

1. 設定 > レガシークライアントを開きます。
2. 移行を再実行をクリックします（最初の完了した実行後、ボタンは移行を開始からラベルが変わります）。
3. フローは最初の実行と同じです。

再実行は必要なだけ安全に使用できます。既存の移行出力を置き換えるため、データが重複することはありません。

避けるべき一般的なミス

• レガシーサーバーがアクティブな状態で移行を実行する。 ソースデータベースがロックされるか、部分的な書き込みが含まれる可能性があります。必ず最初にレガシーサーバーを停止してください。
• エンコーディングフィールドを無視する。 間違ったエンコーディングで実行すると、メンバー名やログメッセージが破損します。これを後で修正するには、アンドゥと再実行が必要です。
• 移行中にHandyCafeを閉じる。 実行が中断され、部分的なデータが書き込まれます。復旧にはアンドゥが必要です。進行状況モーダルが完了するまで待ちます。
• スポットチェックステップをスキップする。 レコードカウントを信頼してサンプルデータを確認しないと、ロケールの不一致や丸め誤差などの微妙な問題を見逃します。
• レガシーインストールを早すぎて削除する。 移行後、少なくとも1つの完全な支払いサイクルの間、ソースファイルを保持してください。月次レポートで不一致が発生した場合、元のレコードを参照できます。
• バックアップなしで移行する。 最初の移行前にレガシーインストールフォルダをコピーします。移行によってソースが変更されることはありませんが、ディスクの問題や事故が発生する可能性があります。バックアップは安価な保険です。