5.8 KiB
5.8 KiB
راهنمای پیاده‌سازی تقویم شمسی در Hesabix
✅ پیاده‌سازی کامل شده
🔧 Backend (FastAPI)
1. Jalali Date Converter (/hesabixAPI/app/core/calendar.py)
- تبدیل تاریخ میلادی به شمسی و بالعکس
- پشتیبانی از سال‌های کبیسه
- نام ماه‌ها و روزهای هفته به فارسی
- فرمت‌های مختلف تاریخ
2. Calendar Middleware (/hesabixAPI/app/core/calendar_middleware.py)
- تشخیص نوع تقویم از هدر
X-Calendar-Type - تنظیم پیش‌فرض بر اساس locale
3. Response Formatting (/hesabixAPI/app/core/responses.py)
- فرمت‌بندی خودکار تاریخ‌ها در پاسخ‌ها
- اضافه کردن فیلدهای
_rawبرای تاریخ اصلی
🎨 Frontend (Flutter)
1. Jalali Converter (/hesabixUI/hesabix_ui/lib/core/jalali_converter.dart)
- الگوریتم‌های دقیق تبدیل تاریخ
- پشتیبانی کامل از تقویم شمسی
- نام ماه‌ها و روزهای هفته فارسی
2. Jalali DatePicker (/hesabixUI/hesabix_ui/lib/widgets/jalali_date_picker.dart)
- DatePicker سفارشی برای تقویم شمسی
- UI کامل با نام ماه‌ها و روزهای فارسی
- ناوبری ماه و سال
3. Calendar Controller (/hesabixUI/hesabix_ui/lib/core/calendar_controller.dart)
- مدیریت حالت تقویم (شمسی/میلادی)
- ذخیره تنظیمات کاربر
- همگام‌سازی با API
4. Calendar Switcher (/hesabixUI/hesabix_ui/lib/widgets/calendar_switcher.dart)
- ویجت تعویض تقویم
- طراحی مشابه Language Switcher
- پشتیبانی چندزبانه
🚀 نحوه استفاده
در Frontend:
// نمایش Jalali DatePicker
final picked = await showJalaliDatePicker(
context: context,
initialDate: DateTime.now(),
firstDate: DateTime(2020),
lastDate: DateTime(2030),
helpText: 'تاریخ را انتخاب کنید',
);
// تبدیل تاریخ
final jalali = JalaliConverter.gregorianToJalali(DateTime.now());
print(jalali.formatFull()); // "شنبه ۱ فروردین ۱۴۰۳"
// استفاده از CalendarController
final controller = CalendarController();
await controller.load();
controller.setCalendarType(CalendarType.jalali);
در Backend:
# تبدیل تاریخ
jalali_data = CalendarConverter.to_jalali(datetime.now())
# {
# "year": 1403,
# "month": 1,
# "day": 1,
# "month_name": "فروردین",
# "weekday_name": "شنبه",
# "formatted": "1403/01/01 12:00:00"
# }
# فرمت‌بندی بر اساس تقویم
formatted_date = CalendarConverter.format_datetime(
datetime.now(),
CalendarType.jalali
)
📱 صفحات پیاده‌سازی شده
1. صفحه ورود (LoginPage)
- Calendar Switcher در AuthFooter
- هماهنگ با Language Switcher
2. داشبورد (HomePage)
- Calendar Switcher در AppBar
- دسترسی سریع به تعویض تقویم
3. صفحه بازاریابی (MarketingPage)
- DatePicker های شمسی و میلادی
- فیلتر تاریخ بر اساس تقویم انتخابی
4. پروفایل (ProfileShell)
- Calendar Switcher در AppBar
- دسترسی در تمام صفحات پروفایل
🔄 جریان کار
- کاربر تقویم را انتخاب می‌کند
- تنظیمات در SharedPreferences ذخیره می‌شود
- API Client هدر X-Calendar-Type را ارسال می‌کند
- Backend تاریخ‌ها را بر اساس تقویم انتخابی فرمت می‌کند
- Frontend DatePicker مناسب را نمایش می‌دهد
🎯 ویژگی‌های کلیدی
✅ بدون وابستگی خارجی
- پیاده‌سازی کامل با Flutter native
- الگوریتم‌های دقیق تبدیل تاریخ
- UI سفارشی برای تقویم شمسی
✅ پشتیبانی کامل
- سال‌های کبیسه شمسی
- نام ماه‌ها و روزهای فارسی
- فرمت‌های مختلف تاریخ
✅ یکپارچگی کامل
- هماهنگ با سیستم i18n موجود
- ذخیره تنظیمات کاربر
- همگام‌سازی Frontend و Backend
✅ UI/UX بهینه
- طراحی مشابه Language Switcher
- DatePicker های کاربرپسند
- پشتیبانی چندزبانه
🧪 تست
# تست Frontend
cd hesabixUI/hesabix_ui
flutter analyze
flutter build web
# تست Backend
cd hesabixAPI
python -m pytest tests/
📚 منابع
🔧 تنظیمات پیشرفته
تغییر نام ماه‌ها:
// در jalali_converter.dart
static const List<String> jalaliMonthNames = [
'فروردین', 'اردیبهشت', 'خرداد', // ...
];
تغییر فرمت تاریخ:
// فرمت سفارشی
String customFormat = jalali.format(separator: '-'); // 1403-01-01
اضافه کردن تقویم جدید:
// در calendar_controller.dart
enum CalendarType { gregorian, jalali, hijri } // اضافه کردن تقویم هجری
🎉 نتیجه
تقویم شمسی به صورت کامل و دقیق در پروژه Hesabix پیاده‌سازی شده است. کاربران می‌توانند بین تقویم میلادی و شمسی جابجا شوند و تمام تاریخ‌ها بر اساس تقویم انتخابی نمایش داده می‌شوند.