arc/extraScripts/arcwoc/INSTALLATION.md

📘 راهنمای نصب و راه‌اندازی Hesabix V2

📋 پیش‌نیازها

قبل از نصب، مطمئن شوید که موارد زیر را دارید:

• ✅ وردپرس نسخه 5.8 یا بالاتر
• ✅ ووکامرس نسخه 6.0 یا بالاتر
• ✅ PHP نسخه 7.4 یا بالاتر
• ✅ حساب کاربری فعال در hesabix.ir
• ✅ حداقل یک کسب‌وکار ایجاد شده در حسابیکس

---

🚀 مرحله 1: نصب افزونه

روش 1: آپلود از طریق وردپرس

1. پوشه hesabixwcplugin-v2 را به صورت ZIP فشرده کنید
2. وارد پنل مدیریت وردپرس شوید
3. به افزونه‌ها > افزودن بروید
4. روی آپلود افزونه کلیک کنید
5. فایل ZIP را انتخاب و آپلود کنید
6. روی فعال‌سازی کلیک کنید

روش 2: کپی مستقیم

cd /var/www/your-site/wp-content/plugins/
cp -r /path/to/hesabixwcplugin-v2 .
chown -R www-data:www-data hesabixwcplugin-v2

سپس از پنل مدیریت وردپرس، افزونه را فعال کنید.

---

⚙️ مرحله 2: راه‌اندازی اولیه (Setup Wizard)

پس از فعال‌سازی، به طور خودکار به Setup Wizard هدایت می‌شوید.

قدم 1: ورود به حساب حسابیکس

📧 ایمیل: your-email@example.com
🔒 رمز عبور: ••••••••

نکته مهم: این ایمیل و رمز عبور، اطلاعات حساب کاربری شما در hesabix.ir است.

قدم 2: انتخاب کسب‌وکار

لیست کسب‌وکارهای شما نمایش داده می‌شود:

📊 شرکت ABC
   📅 سال مالی: 1403
   
📊 فروشگاه XYZ  
   📅 سال مالی: 1403

کسب‌وکار و سال مالی مورد نظر را انتخاب کنید.

قدم 3: ایجاد API Key

سیستم به طور خودکار یک Personal API Key با مشخصات زیر ایجاد می‌کند:

📝 نام: WooCommerce Plugin - Your-Site.com
🔑 Prefix: hsx_
🔐 Scopes: products:read,products:write,persons:read,persons:write,invoices:read,invoices:write
⏰ Expires: هرگز (ندارد)
🌐 IP Whitelist: ندارد (می‌توانید بعداً اضافه کنید)

⚠️ مهم: API Key فقط یک بار نمایش داده می‌شود! (ولی نگران نباشید، در دیتابیس ذخیره می‌شود)

قدم 4: تنظیمات همگام‌سازی

انتخاب کنید چه مواردی به طور خودکار همگام‌سازی شوند:

• ☑️ محصولات جدید
• ☑️ ویرایش محصولات
• ☑️ مشتریان جدید
• ☑️ سفارشات جدید
• ☑️ ایجاد فاکتور خودکار

قدم 5: اتمام

✅ راه‌اندازی تکمیل شد! می‌توانید به داشبورد بروید.

---

🔧 مرحله 3: پیکربندی دستی (اختیاری)

اگر Setup Wizard را رد کردید، می‌توانید به صورت دستی تنظیم کنید:

1. دریافت API Key

// روش 1: از طریق Setup Wizard (توصیه می‌شود)
// روش 2: دستی از پنل حسابیکس

// ورود به hesabix.ir
// Settings → API Keys → Create New Key

2. ذخیره تنظیمات در دیتابیس

update_option('hesabix_v2_api_key', 'hsx_your_api_key_here');
update_option('hesabix_v2_business_id', 123);
update_option('hesabix_v2_fiscal_year_id', 10);
update_option('hesabix_v2_enabled', true);

3. تست اتصال

به حسابیکس V2 > داشبورد بروید و روی تست اتصال کلیک کنید.

---

📊 مرحله 4: همگام‌سازی اولیه

همگام‌سازی محصولات

حسابیکس V2 > همگام‌سازی > همگام‌سازی همه محصولات

این عملیات:

• ✅ تمام محصولات ساده را ارسال می‌کند
• ✅ تمام variations را ارسال می‌کند
• ✅ Mapping ها را ذخیره می‌کند
• ✅ لاگ کامل ایجاد می‌کند

زمان تخمینی: ~1 ثانیه برای هر محصول

همگام‌سازی مشتریان

حسابیکس V2 > همگام‌سازی > همگام‌سازی همه مشتریان

زمان تخمینی: ~1 ثانیه برای هر مشتری

همگام‌سازی سفارشات

سفارشات به طور خودکار همگام می‌شوند. برای سفارشات قدیمی:

-- اجرا در phpMyAdmin یا wp-cli
-- این یک نمونه است، از طریق افزونه قابل انجام است

---

🔍 بررسی وضعیت

داشبورد

حسابیکس V2 > داشبورد

نمایش می‌دهد:

• 📊 تعداد محصولات همگام شده
• 👥 تعداد مشتریان همگام شده
• 🧾 تعداد سفارشات همگام شده
• 🔌 وضعیت اتصال

لاگ‌ها

حسابیکس V2 > لاگ‌ها

نمایش می‌دهد:

• 📝 تمام عملیات
• ⚠️ خطاها
• ℹ️ اطلاعات
• 🐛 Debug logs (در صورت فعال بودن)

---

⚡ استفاده روزمره

هنگام اضافه کردن محصول جدید

1. محصول را در ووکامرس ایجاد کنید
2. خودکار: محصول در حسابیکس ایجاد می‌شود
3. در صفحه ویرایش محصول، کد حسابیکس نمایش داده می‌شود

هنگام ثبت سفارش جدید

1. مشتری سفارش ثبت می‌کند
2. خودکار:
   • مشتری در حسابیکس ایجاد می‌شود (اگر وجود نداشته باشد)
   • فاکتور فروش در حسابیکس ایجاد می‌شود
3. شماره فاکتور به سفارش اضافه می‌شود

مشاهده فاکتور در حسابیکس

وردپرس: سفارش #1234
         ↓
حسابیکس: فاکتور فروش #5678

در صفحه سفارش، یادداشتی اضافه می‌شود:

فاکتور در حسابیکس ایجاد شد. شناسه: 5678

---

🔄 مایگریشن از نسخه قدیمی

اگر نسخه قدیمی (hesabixwcplugin) نصب دارید:

مرحله 1: نصب نسخه جدید

• نسخه قدیمی را غیرفعال نکنید
• نسخه جدید را نصب و فعال کنید

مرحله 2: اجرای ابزار مایگریشن

حسابیکس V2 > مایگریشن > شروع مایگریشن

این ابزار:

• ✅ داده‌های mapping قدیمی را می‌خواند
• ✅ به فرمت جدید تبدیل می‌کند
• ✅ در جداول جدید ذخیره می‌کند
• ✅ هیچ تغییری در نسخه قدیمی ایجاد نمی‌کند

مرحله 3: تست

• چند محصول را ویرایش کنید
• چند سفارش تست ثبت کنید
• بررسی کنید که در حسابیکس درست ثبت می‌شوند

مرحله 4: غیرفعال‌سازی نسخه قدیمی

وقتی مطمئن شدید همه چیز درست کار می‌کند:

افزونه‌ها > Hesabix: WooCommerce (قدیمی) > غیرفعال

⚠️ توجه: نسخه قدیمی را حذف نکنید! فقط غیرفعال کنید.

---

🛠️ عیب‌یابی

مشکل: افزونه فعال نمی‌شود

راه‌حل:

1. بررسی نسخه PHP (حداقل 7.4)
2. بررسی نصب بودن ووکامرس
3. بررسی error logs وردپرس

tail -f /var/www/your-site/wp-content/debug.log

مشکل: خطا در تست اتصال

راه‌حل:

1. بررسی صحت API Key
2. بررسی Business ID و Fiscal Year ID
3. بررسی دسترسی سرور به api.hesabix.ir
4. فعال کردن Debug Mode و بررسی لاگ‌ها

update_option('hesabix_v2_debug_mode', true);

مشکل: محصولات همگام نمی‌شوند

راه‌حل:

1. بررسی فعال بودن همگام‌سازی خودکار
2. مشاهده لاگ‌ها برای پیام خطا
3. تست همگام‌سازی دستی یک محصول
4. بررسی permissions API Key

مشکل: API Key منقضی شده

راه‌حل:

1. به Setup Wizard بروید
2. مجدداً login کنید
3. API Key جدید ایجاد کنید

---

📊 مدیریت داده‌ها

مشاهده Mappings

SELECT * FROM wp_hesabix_v2 
WHERE entity_type = 'product' 
LIMIT 10;

پاک کردن کش

// Clear all mappings (احتیاط!)
global $wpdb;
$wpdb->query("TRUNCATE TABLE {$wpdb->prefix}hesabix_v2");

Export لاگ‌ها

حسابیکس V2 > لاگ‌ها > دانلود لاگ امروز

---

🔐 امنیت

محافظت از API Key

API Key در دیتابیس وردپرس ذخیره می‌شود:

wp_options.option_name = 'hesabix_v2_api_key'

توصیه‌های امنیتی:

1. ✅ دسترسی به دیتابیس را محدود کنید
2. ✅ از SSL استفاده کنید
3. ✅ Backup منظم بگیرید
4. ✅ IP Whitelist تنظیم کنید (در حسابیکس)

محافظت از لاگ‌ها

لاگ‌ها در مسیر زیر ذخیره می‌شوند:

wp-content/uploads/hesabix-v2-logs/

این پوشه با .htaccess محافظت شده و قابل دسترسی مستقیم نیست.

---

🔄 به‌روزرسانی

به‌روزرسانی افزونه

1. پشتیبان کامل بگیرید
2. افزونه را غیرفعال کنید
3. فایل‌های جدید را جایگزین کنید
4. افزونه را فعال کنید
5. تست کنید

به‌روزرسانی دیتابیس

// Activator به طور خودکار دیتابیس را به‌روزرسانی می‌کند
// در صورت نیاز، دستی:
Hesabix_V2_Activator::activate();

---

📞 پشتیبانی

مشکلات رایج

1. خطای 401 Unauthorized

   • API Key نامعتبر است
   • API Key منقضی شده
   • راه‌حل: ایجاد مجدد API Key

2. خطای 403 Forbidden

   • دسترسی کافی ندارید
   • Business ID اشتباه است
   • راه‌حل: بررسی permissions

3. خطای 404 Not Found

   • Endpoint اشتباه است
   • Business/Product وجود ندارد
   • راه‌حل: بررسی لاگ‌ها

تماس با پشتیبانی

• 🌐 وب‌سایت: hesabix.ir/support
• 📧 ایمیل: support@hesabix.ir
• 📱 تلگرام: @HesabixSupport

---

📚 منابع اضافی

• مستندات API
• ویدیوهای آموزشی
• پرسش‌های متداول
• وبلاگ

---

✅ Checklist نصب

• افزونه نصب و فعال شد
• Setup Wizard اجرا شد
• اتصال تست شد (موفق بود)
• یک محصول تست همگام شد
• یک سفارش تست ثبت شد
• فاکتور در حسابیکس ایجاد شد
• لاگ‌ها بررسی شدند
• تنظیمات همگام‌سازی خودکار فعال شد

---

آخرین به‌روزرسانی: 2024-12-05
نسخه: 2.0.0