レガシークライアント設定

HandyCafe は、古い V3 および V4 クライアントのインストールと並行して問題なく動作します。レガシークライアント設定ページでは、次の 2 つの独立した機能を管理します。

ランタイムプロトコル。 V3 / V4 クライアントが元のポートでこのサーバーに接続できるようにするネットワークリスナーを有効化します。
データベース移行。 古いローカルインストールから、メンバー、料金設定、商品、注文、取引、ログを新しい HandyCafe データベースへ任意で取り込みます。こちらは Windows 限定です。

この 2 つは独立しています。データ移行なしでランタイムサポートだけを有効にすることも、ランタイムサポートなしで移行だけ行うことも、両方を行うこともできます。

ランタイムプロトコルのセクション

レガシークライアントサポートを有効化

セクション上部にある全体トグルです。オンにすると、サーバーは 3 つのネットワークリスナーを起動します。

設定済みのマルチキャストグループを待ち受ける UDP リスナー。
UDP port + 2 で待ち受ける TCP コマンドリスナー。
UDP port + 7 で待ち受ける TCP ファイル転送リスナー。

トグルをオフにすると、3 つのリスナーはすべて原子的に停止します。無効化した状態でポート番号やエンコーディングを変更し、再度有効化して反映できます。

設定項目

項目	既定値	説明
認証キー	HANDYCAFE	共有の 10 文字キーです。受信・送信するすべてのフレームにこの文字列が含まれます。一致しないフレームは破棄されます。すべてのレガシークライアントで同じキーを使う必要があります。
UDP マルチキャスト IP	230.4.4.46	クライアント発見のビーコンと UDP ベースのコマンド配信に使うマルチキャストグループです。多くのレガシークライアントビルドでハードコードされています。
サーバー UDP ポート	710	サーバーがクライアントのビーコンとコマンドを受け付ける UDP ポートです。レガシークライアントはこのポートへ送信します。
クライアント UDP ポート	711	レガシークライアントが待ち受ける UDP ポートです。サーバーは検出済みクライアント IP に対し、このポートへユニキャストの管理コマンドを送ります。
エンコーディング	cp1254	ワイヤ形式の文字列フィールドに使う文字エンコーディングです。トルコ向けインストールでは cp1254、西欧向けでは cp1252 を使います。不明な値は cp1254 にフォールバックし、サーバーログに警告を残します。
サーバーバージョン	3.4.01	すべての UDP ビーコンでブロードキャストされるバージョン文字列です。レガシークライアントの中には、認識できないバージョンのフレームを拒否するものがあります。元のサーバーのバージョン文字列に合わせてください。
プロトコルバリアント	STE	使用するワイヤ形式を選びます。下のバリアント比較を参照してください。
無通信タイムアウト	10	秒単位の MAC ごとのウォッチドッグです。この時間内にクライアントから通信が来ないと、オフラインとして扱われます。2〜3 秒ごとにビーコンを送るレガシークライアントには 10 秒程度が適しています。

由来するポート

フォームの下には、由来する TCP ポートを示す読み取り専用の行が表示されます。

TCP Command Port: 712   File Transfer Port: 717

これらのポートは UDP サーバーポートから計算されます。個別には設定しません。Server UDP Port を別の値に変更すると、由来ポートも連動して変わります。

プロトコルバリアント

Protocol Variant フィールドでは、サーバーが使うワイヤ形式を選択します。レガシーサーバーがどのビルドで作られたかに合うバリアントを選んでください。

バリアント	使いどころ
STE（Smart/Turbo Edition）	現代のレガシーコードベースです。フレーム構造に 70 バイトの license-info プレフィックスを追加します。フレームサイズは 1337 バイトです。レガシー環境が Smart または Turbo Edition を使っていた場合に選びます。
Standard	標準のベースライン版レガシービルドです。license-info プレフィックスなしで、フレームサイズは 1267 バイトです。ライセンス登録のない Standard Edition だった場合にのみ選んでください。

誤ったバリアントを選ぶと、フレームが破棄されたり読み違えられたりします。症状としては、クライアントがオンラインに見えてもすべてのコマンドを無視する、またはコマンドデータが 70 バイトずれてしまう、などがあります。

モダンクライアントとの共存

レガシーポート（710、711、712、717）は、モダンな HandyCafe プロトコルポート（TCP 5001、5002、5003、UDP 5004）とは完全に分離されています。2 つのプロトコルスタックは同時に動作しても衝突しません。同じ LAN 上で古いクライアントと新しいクライアントを混在させ、同じ Admin Panel から管理できます。

変更の適用

ランタイムプロトコルセクション内のすべての項目は、ページ下部の共通 Save ボタンで保存されます。保存時、サーバーは次を行います。

動作中なら 3 つのレガシーリスナーを停止します。
認証キーを検証します（空であってはいけません）。
更新済みの値から新しいリスナー設定を構築します。
リスナーを同時に再起動します。
3 つすべてが再びオンラインになったら通知を出します。

ポートが別プロセスで既に使用中の場合は、サーバーがエラーを返し、トグルはオフに戻ります。netstat でファイアウォールと他のサービスを確認し、空いているポート範囲を選んでください。

データベース移行セクション（Windows のみ）

この機能は、HandyCafe が Windows 上で動作している場合にのみ利用できます。macOS と Linux では、「データベース移行は Windows でのみサポートされています。」という注意が表示されます。

検出

ページを開くと、サーバーはシステム上のレガシーインストールをスキャンします。検出対象は次のとおりです。

レジストリと、Program Files\HandyCafe や C:\HandyCafe のような一般的なインストール先。
インストール先にあるデータベースファイル。
インストールディレクトリ内の設定 INI ファイル。

検出に成功すると、ページには次が表示されます。

ラベル	意味
インストールパス	レガシーインストールがあるディスク上の場所です。
データベースパス	レガシーデータベースファイルのフルパスです。
サーバーバージョン	レガシー設定から解析された値です。
INI ファイル数	検出された設定ファイル数です。インストールが完全かどうかの確認に便利です。

インストールが見つからない場合は、「レガシーインストールは検出されませんでした。」と表示されます。それでもランタイムサポートは有効化できますが、移行機能には取り込むものがありません。

移行ステータス

ページでは移行履歴を次のように追跡します。

状態	意味
never	まだ移行を実行していません。
in_progress	現在移行中です。この状態の間はサーバーを閉じないでください。
completed	最新の移行が警告なしで完了しました。
completed_with_warnings	最新の移行は完了しましたが、一部のレコードはスキップされました（たとえば、エンコーディングエラーや不正な日付のため）。続行前に警告を確認してください。
undone	最新の移行がロールバックされました。

最初の成功後、Start Migration ボタンは Re-run Migration にラベル変更されます。

移行対象

テーブル	説明
Members	名前、連絡先、残高を持つ顧客レコードです。
Pricing	料金表と時間帯別のレートです。
Products	商品カタログのエントリです。
Orders	セッション参照付きの注文履歴です。
Transactions	タイムスタンプ、金額、支払い方法を持つ元帳エントリです。
Logs	レガシーデータベースからの監査ログと警告ログです。

「ファイルは安全」保証

ページには青い注意書きで、「元のデータベースファイルは削除されません。移行が確認できたあとで安全に削除できます。」と表示されます。移行はソースに対して読み取り専用です。何度移行を実行しても、元のレガシーデータベースは変更されません。これにより、取り込みを試し、件数を確認し、リスクなくロールバックできます。

Start / Re-run / Undo

Start Migration. 進行状況モーダルを開きます。インポート中は現在のフェーズと処理済み件数が表示されます。この間は HandyCafe を閉じないでください。
Re-run Migration. 完了後に利用できます。取り込みを最初からやり直します。新しい取り込み結果が、HandyCafe の以前のデータを置き換えます。
Undo Migration. 完了後に利用できます。確認ダイアログを開きます。確定すると、移行された行はすべて HandyCafe から削除されます。レガシー側の元データには触れません。Undo 後、状態は never に戻ります。

completed_with_warnings の場合

移行が completed_with_warnings で終わった場合は、黄色のバナーと Details リンクが表示されます。クリックすると、スキップされたレコードと理由の一覧を展開できます。よくある理由は次のとおりです。

エンコーディング不一致。 元データの行に、設定したエンコーディングでは正しくデコードできない文字が含まれています。エンコーディング（cp1254 または cp1252）を変更して再実行してください。
不正な日付。 一部のレガシーレコードには無効なタイムスタンプがあります。これらはスキップされますが、有効な行は引き続き取り込まれます。
重複キー。 同じ識別子のレコードが既に HandyCafe に存在します。移行は既存レコードを保持し、重複をスキップします。

ヒント

移行を始める前に、レガシーサーバーを停止してください。レガシー側がまだデータベースへ書き込んでいると、古いデータや途中のデータを読む可能性があります。
最初の移行の前に、エンコーディング項目をレガシーのロケールに合わせてください。取り込み後に変更しても、すでに壊れた名前は直りません。
必ず最初にテスト移行を行ってください。「Last Counts」の件数を確認し、メンバーや取引の行をいくつか目視で確認してから本運用へ進みましょう。
移行後の移行期間は、ランタイムサポートを有効にしてレガシークライアントを接続したままにしてください。新しいサーバーが旧サーバーと同じように動くことを確認してから、旧サーバーを廃止できます。
Server UDP Port を変更したら、由来するコマンドポートとファイル転送ポートも連動して変わることを忘れないでください。ファイアウォールルールもそれに合わせて更新が必要です。