ultimatepos/PERSIAN_CALENDAR_SETUP.md

# 📅 راهنمای کامل شمسی‌سازی سیستم برای ایران

## ✅ تغییرات انجام شده

### 1. نصب پکیج تقویم شمسی
- افزودن `morilog/jalali` به `composer.json` برای تبدیل تاریخ میلادی به شمسی
- پکیج در دسترس برای استفاده در همه بخش‌های سیستم

### 2. به‌روزرسانی توابع تاریخ در PHP
#### فایل: `app/Utils/Util.php`
- تابع `format_date()`: تبدیل تاریخ میلادی به شمسی و نمایش با اعداد فارسی
- تابع `uf_date()`: تبدیل تاریخ شمسی ورودی کاربر به میلادی برای ذخیره در دیتابیس
- تابع `format_time()`: نمایش زمان با اعداد فارسی

### 3. به‌روزرسانی Blade Directives
#### فایل: `app/Providers/AppServiceProvider.php`
- `@format_date`: نمایش تاریخ شمسی در View ها
- `@format_time`: نمایش زمان با اعداد فارسی
- `@format_datetime`: نمایش تاریخ و زمان شمسی

### 4. به‌روزرسانی JavaScript
#### فایل: `resources/views/layouts/partials/javascripts.blade.php`
- افزودن کتابخانه `persian-datepicker` برای انتخاب تاریخ شمسی
- افزودن کتابخانه `moment-jalaali` برای کار با تاریخ شمسی در JavaScript
- تنظیم فرمت تاریخ پیش‌فرض برای فارسی: `Y/m/d` (1403/01/01)
- تنظیم فرمت moment برای فارسی: `jYYYY/jMM/jDD`

#### فایل: `public/js/common.js`
- به‌روزرسانی تنظیمات datepicker برای استفاده از تقویم شمسی
- به‌روزرسانی datetimepicker برای پشتیبانی از تقویم شمسی
- به‌روزرسانی date range picker برای استفاده از moment-jalaali

#### فایل: `public/js/app.js`
- به‌روزرسانی تمام date picker ها برای استفاده از Persian Date Picker
- پشتیبانی از `.start-date-picker`, `#user_dob`, `.dob-date-picker`

### 5. Helper Functions فارسی
#### فایل: `app/Http/persian_helpers.php`
توابع موجود:
- `persian_number()`: تبدیل اعداد انگلیسی به فارسی
- `english_number()`: تبدیل اعداد فارسی به انگلیسی
- `persian_date()`: تبدیل تاریخ میلادی به شمسی
- `persian_price()`: فرمت قیمت با اعداد فارسی
- `persian_month_name()`: نام ماه‌های شمسی
- `persian_day_name()`: نام روزهای هفته
- `persian_words()`: تبدیل عدد به حروف فارسی
- `is_persian_lang()`: بررسی فعال بودن زبان فارسی

## 🚀 نحوه نصب و راه‌اندازی

### مرحله 1: نصب پکیج‌ها
```bash
composer install
```

یا اگر قبلاً نصب شده:
```bash
composer update morilog/jalali
```

### مرحله 2: پاک‌سازی Cache
```bash
php artisan cache:clear
php artisan config:clear
php artisan view:clear
composer dump-autoload
```

### مرحله 3: تنظیم زبان پیش‌فرض
در فایل `.env`:
```env
APP_LOCALE=fa
APP_TIMEZONE=Asia/Tehran
```

### مرحله 4: تنظیم تاریخ پیش‌فرض کسب‌وکار
در تنظیمات کسب‌وکار، فرمت تاریخ را به `Y/m/d` تغییر دهید.

## 📋 نحوه استفاده

### در PHP (Backend)
```php
use App\Utils\Util;

$util = new Util();

// نمایش تاریخ شمسی
$date = $util->format_date('2024-01-01'); // 1402/10/11

// تبدیل تاریخ شمسی به میلادی برای ذخیره
$gregorian = $util->uf_date('1403/01/01'); // 2024-03-20

// استفاده از helper function
$persian_date = persian_date(now(), 'Y/m/d'); // 1403/01/01
```

### در Blade Template
```blade
{{-- نمایش تاریخ شمسی --}}
@format_date($transaction->transaction_date)

{{-- نمایش تاریخ و زمان شمسی --}}
@format_datetime($transaction->created_at)

{{-- نمایش زمان با اعداد فارسی --}}
@format_time($transaction->created_at)
```

### در JavaScript
```javascript
// استفاده از moment-jalaali
var today = moment.jDate(); // تاریخ امروز شمسی
var formatted = moment.jDate().format('jYYYY/jMM/jDD'); // 1403/01/01

// استفاده از Persian Date Picker
$('.date-picker').persianDatepicker({
    calendarType: 'persian',
    format: 'YYYY/MM/DD',
    autoClose: true
});
```

## ⚙️ تنظیمات پیش‌فرض برای ایران

### فرمت تاریخ
- **فرمت پیش‌فرض:** `Y/m/d` (1403/01/01)
- **فرمت کامل:** `Y/m/d H:i` (1403/01/01 14:30)

### منطقه زمانی
- **پیش‌فرض:** `Asia/Tehran`

### ارز (نیاز به تنظیم دستی)
برای تنظیم ریال ایران، در تنظیمات کسب‌وکار ارز را به "Iranian Rial (IRR)" تغییر دهید.

## 🔄 تبدیل تاریخ

### میلادی به شمسی
```php
$jalali = \Morilog\Jalali\Jalalian::fromCarbon(\Carbon\Carbon::now());
echo $jalali->format('Y/m/d'); // 1403/01/01
```

### شمسی به میلادی
```php
$jalali = \Morilog\Jalali\Jalalian::fromFormat('Y/m/d', '1403/01/01');
$carbon = $jalali->toCarbon();
echo $carbon->format('Y-m-d'); // 2024-03-20
```

## 📝 نکات مهم

1. **ذخیره‌سازی در دیتابیس:** همه تاریخ‌ها به صورت میلادی (Gregorian) در دیتابیس ذخیره می‌شوند.

2. **نمایش به کاربر:** تاریخ‌ها به صورت شمسی (Jalali) با اعداد فارسی نمایش داده می‌شوند.

3. **ورودی کاربر:** کاربر تاریخ را به صورت شمسی وارد می‌کند و سیستم آن را به میلادی تبدیل می‌کند.

4. **پشتیبانی چندزبانه:** سیستم هم از تاریخ میلادی و هم شمسی پشتیبانی می‌کند و بر اساس زبان فعال کاربر انتخاب می‌شود.

## 🐛 عیب‌یابی

### اگر تاریخ‌ها نمایش داده نمی‌شوند:
1. بررسی کنید که زبان سیستم روی `fa` تنظیم شده باشد
2. Cache را پاک کنید: `php artisan cache:clear`
3. بررسی کنید که پکیج `morilog/jalali` نصب شده باشد: `composer show morilog/jalali`

### اگر Date Picker کار نمی‌کند:
1. بررسی کنید که کتابخانه‌های JavaScript لود شده‌اند (در Developer Tools مرورگر)
2. بررسی کنید که متغیر `is_persian_lang` در JavaScript تعریف شده باشد
3. بررسی Console مرورگر برای خطاهای JavaScript

## ✅ چک‌لیست تست

- [ ] تاریخ‌های نمایش داده شده به صورت شمسی هستند
- [ ] اعداد تاریخ به فارسی نمایش داده می‌شوند (۰-۹)
- [ ] Date Picker تاریخ شمسی را نمایش می‌دهد
- [ ] ورود تاریخ شمسی از کاربر به درستی تبدیل می‌شود
- [ ] گزارش‌ها تاریخ شمسی را نمایش می‌دهند
- [ ] فاکتورها تاریخ شمسی را نمایش می‌دهند

## 📞 پشتیبانی

در صورت بروز مشکل، لطفاً موارد زیر را بررسی کنید:
1. نسخه PHP (حداقل 8.0)
2. نصب بودن تمام پکیج‌های Composer
3. پاک بودن Cache
4. تنظیمات زبان در `.env`

---

**نکته مهم:** پس از انجام تغییرات، حتماً Cache را پاک کرده و `composer dump-autoload` را اجرا کنید.