نحوه مهاجرت از نصب قدیمی
این راهنما دادههای موجود شما را از یک نصب قدیمی HandyCafe V3 یا V4 به یک سرور مدرن HandyCafe import میکند. مهاجرت برای منبع غیرمخرب است: فایلهای اصلی تغییر نمیکنند یا حذف نمیشوند.
مهاجرت پایگاهداده فقط روی ویندوز اجرا میشود. پشتیبانی زمان اجرا برای اینکه کلاینتهای قدیمی از طریق پروتکل اصلی وصل شوند روی همه پلتفرمها کار میکند (به تنظیمات کلاینتهای قدیمی نگاه کنید).
چیزهایی که نیاز دارید
- یک دستگاه ویندوز که هم نصب قدیمی و هم سرور مدرن HandyCafe روی همان سیستم باشد، یا دسترسی به فایل پایگاهداده قدیمی.
- دسترسی مدیریتی به HandyCafe Server.
- سرور قدیمی متوقف شده باشد. پایگاهداده منبع نباید هنگام مهاجرت در حال نوشتن فعال باشد.
- فضای خالی دیسک دستکم به اندازه پایگاهداده قدیمی (برای کپی جدید پایگاهداده HandyCafe).
- 10 تا 30 دقیقه زمان بدون وقفه. مهاجرت روی مجموعهدادههای بزرگ ممکن است چند دقیقه طول بکشد. HandyCafe را در طول اجرا نبندید.
مرحله 1: سرور قدیمی را متوقف کنید
برنامه سرور قدیمی HandyCafe را باز کنید. همه نشستها را متوقف کنید و از برنامه خارج شوید. اگر سرور قدیمی بهصورت Windows service اجرا میشود، سرویس را از services.msc متوقف کنید.
نتیجه مورد انتظار: فرایند سرور قدیمی دیگر در حال اجرا نیست. فایل پایگاهداده باز نگه داشته نشده است.
مرحله 2: صفحه تنظیمات کلاینتهای قدیمی را باز کنید
- HandyCafe را اجرا کنید.
- Settings را در نوار کناری باز کنید.
- روی Legacy Clients کلیک کنید.
- به بخش Database Migration بروید.
نتیجه مورد انتظار: اگر سیستم یک نصب قدیمی را تشخیص دهد، صفحه مسیر نصب، مسیر پایگاهداده، نسخه سرور و تعداد فایلهای INI را نشان میدهد. اگر چیزی تشخیص داده نشود، صفحه میگوید "No legacy installation detected." در آن صورت بررسی کنید فایلهای قدیمی در یک مسیر استاندارد مثل Program Files\HandyCafe یا C:\HandyCafe وجود داشته باشند.
مرحله 3: نصب شناساییشده را بررسی کنید
مقدارهای شناساییشده را با نصب قدیمی شناختهشده خود تطبیق دهید:
| فیلد | چه چیزی را بررسی کنید |
|---|---|
| Install Path | به پوشه درست HandyCafe اشاره میکند. |
| Database Path | به فایل پایگاهداده قدیمی در داخل پوشه نصب اشاره میکند. |
| Server Version | با نسخه سرور قدیمی شما مطابقت دارد (برای مثال 3.4.01 یا 4.0.10). |
| INI File Count | غیرصفر است. یک نصب سالم چند فایل INI برای پیکربندیهای مختلف دارد. |
اگر هر فیلدی اشتباه بود، HandyCafe را ببندید، نصب را اصلاح کنید و دوباره باز کنید.
مرحله 4: فیلد Encoding را بررسی کنید
قبل از اجرای migration، مطمئن شوید فیلد Encoding در بخش Runtime Protocol برای دادههای منبع شما درست تنظیم شده است. این فیلد در همان صفحه تنظیمات و در بخش بالاتر قرار دارد.
| Locale منبع | Encoding پیشنهادی |
|---|---|
| Turkish | cp1254 |
| Western European (English, French, German, Spanish, Italian, Portuguese) | cp1252 |
| Other | cp1254 (سرور این را بهعنوان fallback پیشفرض میپذیرد) |
اگر encoding را تغییر دادید، قبل از ادامه روی Save کلیک کنید.
نتیجه مورد انتظار: رشتههای منبع در هنگام مهاجرت بدون خطا decode میشوند و از نتیجه completed_with_warnings جلوگیری میشود.
مرحله 5: مهاجرت را شروع کنید
- روی Start Migration کلیک کنید.
- یک modal پیشرفت باز میشود. این modal phase فعلی و تعداد ردیفهای پردازششده تا آن لحظه را نشان میدهد.
- HandyCafe را نبندید و رایانه را به حالت sleep نبرید.
- منتظر پایان بمانید. مجموعهدادههای کوچک در کمتر از یک دقیقه تمام میشوند. مجموعهدادههای بزرگتر ممکن است 5 تا 10 دقیقه طول بکشند.
نتیجه مورد انتظار: modal پیشرفت بسته میشود و وضعیت به completed یا completed_with_warnings تغییر میکند. یک اعلان میآید و اجرای موفق را تأیید میکند.
مرحله 6: شمارشهای مهاجرتشده را بررسی کنید
بعد از پایان، صفحه شمارش رکوردهای مهاجرتشده را نشان میدهد:
| شمارش | معنی |
|---|---|
| Members | رکوردهای مشتری import شدهاند. |
| Pricing | جدولهای قیمتگذاری و ورودیهای برنامه import شدهاند. |
| Products | ورودیهای کاتالوگ محصول import شدهاند. |
| Orders | سفارشهای تاریخی import شدهاند. |
| Transactions | ورودیهای دفترکل import شدهاند. |
| Logs | لاگهای audit و هشدار import شدهاند. |
| Warnings | رکوردهایی که هنگام import رد شدهاند. فقط وقتی وضعیت completed_with_warnings باشد ظاهر میشود. |
روی expander Details کلیک کنید تا breakdown کامل را ببینید. بررسی کنید شمارشها با انتظار شما معقول باشند.
نتیجه مورد انتظار: اگر منبع شما در آن جدولها داده داشته باشد، هر چهار دسته (members، products، orders، transactions) شمارش غیرصفر نشان میدهند.
مرحله 7: هشدارها را رسیدگی کنید (اگر وجود دارد)
اگر وضعیت completed_with_warnings باشد، فهرست هشدارها را باز کنید و رکوردهای ردشده را بررسی کنید.
هشدارهای رایج و راهحلها:
| هشدار | علت | راهحل |
|---|---|---|
| Encoding decode error | متن منبع بایتهایی دارد که با encoding پیکربندیشده decode نمیشوند. | Undo را اجرا کنید، فیلد Encoding را با locale منبع هماهنگ کنید و migration را دوباره اجرا کنید. |
| Malformed date | یک رکورد قدیمی timestamp نامعتبر دارد (برای مثال 0000-00-00). |
این رکوردها بهصورت ایمن رد میشوند. نیازی به اقدام نیست. |
| Duplicate key | رکوردی با همان شناسه از قبل در HandyCafe وجود دارد. | اگر این یک مهاجرت دوم ناخواسته بوده، Undo و Re-run را اجرا کنید. اگر در حال ادغام پایگاهدادهها هستید، رد شدن را بپذیرید. |
نتیجه مورد انتظار: یا هشدارها را بهعنوان از دستدادنهای قابلقبول میپذیرید، یا مشکل اصلی را برطرف میکنید و دوباره اجرا میکنید.
مرحله 8: دادههای import شده را spot-check کنید
قبل از کنار گذاشتن سرور قدیمی، بهصورت دستی نمونهای از هر نوع رکورد را بررسی کنید.
- Members را در نوار کناری باز کنید. یک عضو شناختهشده از سیستم قدیمی را جستوجو کنید. نام، موجودی و اطلاعات تماس را تأیید کنید.
- Settings > Pricing را باز کنید. مطمئن شوید نرخهای ساعتی با برنامه قدیمی مطابقت دارند.
- Products را باز کنید. نامها و قیمتهای محصول را بررسی کنید.
- Cash Report را برای یک روز تاریخی اخیر باز کنید. مطمئن شوید جمعها با چیزی که از سیستم قدیمی انتظار دارید مطابقت دارند.
نتیجه مورد انتظار: نمونههای تصادفی با منبع قدیمی همخوانی دارند. اگر یک رکورد خاص اشتباه بود، آن را یادداشت کنید. تفاوتهای جزئی در قالببندی طبیعی است. اختلافهای بزرگ در مقدار، به مشکل encoding یا یکپارچگی داده اشاره میکنند که باید قبل از live شدن بررسی شود.
مرحله 9: پشتیبانی زمان اجرای کلاینت قدیمی را فعال کنید (اختیاری)
اگر میخواهید ماشینهای کلاینت V3 یا V4 فعلی شما در طول گذار همچنان وصل بمانند، حالا runtime protocol را فعال کنید.
- به بالای صفحه تنظیمات Legacy Clients بروید.
- Enable Legacy Client Support را روشن کنید.
- مطمئن شوید listener portها (UDP 710، TCP 712، file transfer 717) با چیز دیگری در شبکه شما تداخل ندارند.
- روی Save کلیک کنید.
نتیجه مورد انتظار: کلاینتهای قدیمی روی LAN ظرف 5 تا 10 ثانیه در Admin Panel ظاهر میشوند. برای مدیریت آنها از پنل، Legacy Clients را ببینید.
چگونه یک مهاجرت را Undo کنید
اگر مهاجرت نتیجهای غیرمنتظره داشت، میتوانید آن را کاملاً rollback کنید. پایگاهداده قدیمی اصلی دستنخورده میماند.
- Settings > Legacy Clients را باز کنید.
- به بخش Database Migration بروید.
- روی Undo Migration کلیک کنید.
- در دیالوگ تأیید کنید.
هر ردیف مهاجرتشده از HandyCafe حذف میشود. وضعیت به never برمیگردد. سپس میتوانید مشکل اصلی (encoding، پاکسازی داده منبع و غیره) را برطرف کنید و دوباره Start Migration را اجرا کنید.
چگونه یک مهاجرت را دوباره اجرا کنید
اجرای دوباره، داده مهاجرتشده را با داده تازه از منبع جایگزین میکند.
- Settings > Legacy Clients را باز کنید.
- روی Re-run Migration کلیک کنید (بعد از اولین اجرای کامل، برچسب دکمه از Start Migration عوض میشود).
- جریان کار دقیقاً مثل اجرای اولیه است.
Re-run هر چند بار که لازم باشد ایمن است. این کار داده را تکراری نمیکند، چون خروجی مهاجرت موجود را جایگزین میکند.
اشتباههای رایج که باید از آنها پرهیز کنید
- اجرای migration وقتی سرور قدیمی فعال است. پایگاهداده منبع ممکن است قفل باشد یا نوشتههای ناقص داشته باشد. همیشه اول سرور قدیمی را متوقف کنید.
- نادیده گرفتن فیلد Encoding. اجرای migration با encoding اشتباه، نام اعضا و پیامهای لاگ را خراب میکند. درستکردن این موضوع بعداً نیاز به Undo و Re-run دارد.
- بستن HandyCafe در حین migration. اجرا قطع میشود و داده ناقص نوشته میشود. بازیابی نیاز به Undo دارد. همیشه اجازه دهید modal پیشرفت کامل شود.
- رد کردن مرحله spot-check. اعتماد به شمارش رکوردها بدون بررسی داده نمونه، مشکلات ظریف مثل ناهماهنگی locale یا خطاهای گرد کردن را از قلم میاندازد.
- حذف زودهنگام نصب قدیمی. فایلهای منبع را دستکم تا پایان یک چرخه پرداخت کامل بعد از مهاجرت نگه دارید. اگر در گزارش ماهانه اختلافی ظاهر شد، میتوانید به رکوردهای اصلی مراجعه کنید.
- مهاجرت بدون backup. قبل از اولین مهاجرت، پوشه نصب قدیمی را کپی کنید. با اینکه منبع توسط migration تغییر نمیکند، خطاهای دیسک یا اتفاقات ناگهانی ممکن است رخ دهند. یک backup بیمهای ارزان است.