Seyyed_arc/extraScripts/arcwoc/INSTALLATION.md

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

## 📋 پیش‌نیازها

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

- ✅ وردپرس نسخه 5.8 یا بالاتر
- ✅ ووکامرس نسخه 6.0 یا بالاتر
- ✅ PHP نسخه 7.4 یا بالاتر
- ✅ حساب کاربری فعال در [hesabix.ir](https://hesabix.ir)
- ✅ حداقل یک کسب‌وکار ایجاد شده در حسابیکس

---

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

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

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

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

```bash
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

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

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

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

```php
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 ثانیه برای هر مشتری

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

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

```sql
-- اجرا در 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 وردپرس

```bash
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 و بررسی لاگ‌ها

```php
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

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

### پاک کردن کش

```php
// 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. تست کنید

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

```php
// 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](https://hesabix.ir/support)
- 📧 ایمیل: support@hesabix.ir
- 📱 تلگرام: @HesabixSupport

---

## 📚 منابع اضافی

- [مستندات API](https://api.hesabix.ir/docs)
- [ویدیوهای آموزشی](https://hesabix.ir/videos)
- [پرسش‌های متداول](https://hesabix.ir/faq)
- [وبلاگ](https://hesabix.ir/blog)

---

## ✅ Checklist نصب

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

---

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