# خطاهای رایج

اینجا فهرست ۳۳ باگ واقعی رو می‌بینید که بارها توی پروژه‌ها و کتابخونه‌های مختلف تکرار شدن، همراه با نشونهٔ هر باگ و راه حلش. بیشتر این باگ‌ها رو موقع نوشتن همین راهنما و تست کردن کتابخونه‌ها از نزدیک دیدیم و بازتولید کردیم!

## ۱. محاسبات تقویم

| # | خطا / باگ                                                              | چطوری خودش رو نشون می‌ده؟                                                                                           | راه‌حل درست                                                                                                                                                            |
| - | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ۱ | **استفاده از الگوریتم چرخهٔ ۲۸۲۰ ساله** (بیرشک)                        | تمام تاریخ‌های بین ۲۰ مارس ۲۰۲۵ تا ۲۰ مارس ۲۰۲۶ (کل سال ۱۴۰۴) یک روز جابه‌جا می‌شن و ۳۰ اسفند ۱۴۰۳ اصلا وجود نداره! | استفاده از فرمول ۳۳ ساله + جدول اصلاح، یا یکی از کتابخونه‌های تیک‌خورده (✅) در [بخش ۶](https://goudarzjafari.com/fa/persian-calendar/languages-and-libraries/)         |
| ۲ | فرض کردن اینکه کبیسه‌ها همیشه ۴ سال یک‌بارن (`y % 4 == 3` و مشابه اون) | از سال ۱۴۰۸ به بعد به خطا می‌خوره (چون فاصلهٔ کبیسهٔ ۱۴۰۳ تا ۱۴۰۸ پنج ساله است)                                     | استفاده از فرمول استاندارد ۳۳ ساله + جدول اصلاح                                                                                                                        |
| ۳ | استفاده از تقسیم معمولی (`/` و `%`) روی اعداد منفی                     | برای سال‌های منفی یا مقادیر میانی منفی یک روز خطا می‌ده و پیدا کردنش خیلی سخته                                      | استفاده از تقسیم کف (Floor division) طبق [بخش ۳](https://goudarzjafari.com/fa/persian-calendar/algorithm/)                                                             |
| ۴ | اضافه کردن ماه از طریق تبدیل به میلادی                                 | «۱ مهر + ۱ ماه» به جای «۱ آبان» می‌شه یه روز دیگه!                                                                  | اضافه کردن ماه مستقیما روی سال و ماه شمسی و محدود کردن شمارهٔ روز                                                                                                      |
| ۵ | اضافه کردن ماه بدون محدود کردن (Clamp) شمارهٔ روز                      | «۳۱ شهریور + ۱ ماه» یا خطا پرتاب می‌کنه (مثل `shamsi_date`) یا سرریز می‌شه به ۱ آبان!                               | محدود کردن روز به حداکثر طول ماه مقصد (`days_in_month`)                                                                                                                |
| ۶ | فرض کردن اینکه ۲۹ اسفند همیشه آخرین روز ساله                           | روز ۳۰ اسفند در سال‌های کبیسه از گزارش‌ها و Datepickerها جا می‌افته                                                 | گرفتن طول اسفند از تابع `days_in_month(y, 12)`                                                                                                                         |
| ۷ | اشتباه وارد کردن طول ماه‌ها در کد (مثلا ۳۱ روزه گرفتن مهر)             | از اول پاییز به بعد تمام تاریخ‌ها یک روز جابه‌جا می‌شن                                                              | ۶ ماه اول ۳۱ روزه، ۵ ماه بعدی ۳۰ روزه، اسفند ۲۹ یا ۳۰ روزه                                                                                                             |
| ۸ | تبدیل تاریخ اسناد قدیمی (قبل از سال ۱۳۰۴) با فرمول امروزی              | تاریخ نامه‌ها و اسناد دورهٔ قاجار چند روز پس‌وپیش می‌شه                                                             | قبل از ۱۳۰۴ طول ماه‌ها برجی و متغیر بود؛ برای تاریخ‌های تاریخی از مبدل قدیمی در [persian-calendar/calendar](https://github.com/persian-calendar/calendar) استفاده کنید |
| ۹ | استفاده از کتابخونه‌ها خارج از بازهٔ پشتیبانی‌شون                      | پرتاب شدن خطا یا برگردوندن تاریخ غلط برای سال‌های دور (مثلا `jalaali-js` بعد از سال ۳۱۷۷ خطا می‌ده)                 | محدود کردن و اعتبارسنجی بازهٔ ورودی                                                                                                                                    |

## ۲. تایم‌زون (منطقهٔ زمانی)

| #  | خطا / باگ                                                                              | چطوری خودش رو نشون می‌ده؟                                                                             | راه‌حل درست                                                                                           |
| -- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| ۱۰ | تبدیل تاریخ بر اساس ساعت UTC یا ساعت سرور (به جای تایم‌زون کاربر)                      | بین ساعت ۱۲ شب تا ۳:۳۰ بامداد به وقت ایران، تاریخ «امروز» هنوز تاریخ دیروز رو نشون می‌ده!             | اول تاریخ رو در تایم‌زون `Asia/Tehran` (یا تایم‌زون کاربر) بگیرید و بعد به شمسی تبدیل کنید            |
| ۱۱ | **قدیمی بودن دیتابیس تایم‌زون سیستم** (قبل از `tzdata 2022b`)                          | از بهار ۱۴۰۲ به بعد، ساعت‌ها در بهار و تابستان ۱ ساعت جلو می‌رن و تاریخ‌ها حوالی نیمه‌شب اشتباه می‌شن | آپدیت کردن سیستم‌عامل، JDK، ‏ICU، ‏Node.js و پکیج `tzdata` (ایران از شهریور ۱۴۰۱ ساعت تابستانی نداره) |
| ۱۲ | هاردکد کردن `+03:30` در کد برنامه                                                      | ساعت تاریخ‌های ثبت‌شده در تابستان‌های قبل از ۱۴۰۲ یک ساعت اشتباه نشون داده می‌شه                      | استفاده از نام استاندارد IANA یعنی `Asia/Tehran`                                                      |
| ۱۳ | تبدیل داده‌های «فقط تاریخ» (مثل تاریخ تولد) به نیمه‌شب UTC و نمایش به وقت محلی         | برای کاربرهایی که در کشورهای غرب گرینویچ (اروپا/آمریکا) هستن، تاریخ تولد یک روز عقب می‌افته!          | نگه داشتن تاریخ به عنوان تاریخ بدون ساعت (`LocalDate`، `DateOnly`، `date`)                            |
| ۱۴ | خوندن Timestamp خروجی `parse` در یک تایم‌زون دیگه                                      | در PHP، خروجی `IntlDateFormatter::parse('1404/01/01')` اگر در UTC فرمت بشه، می‌شه `2025-03-20`!       | خوندن و فرمت کردن Timestamp در همون تایم‌زونی که `parse` شده است                                      |
| ۱۵ | تفاوت `new Date('2025-03-21')` (در UTC) با `new Date(2025, 2, 21)` (به وقت محلی) در JS | بسته به تایم‌زون سیستم کاربر، تاریخ یک روز جابه‌جا می‌شه                                              | مشخص کردن صریح تایم‌زون، یا استفاده از `PlainDate` در Temporal                                        |

## ۳. کتابخانه‌ها و لایسنس‌ها

| #  | خطا / باگ                                                                                    | چطوری خودش رو نشون می‌ده؟                                                                                                                                 | راه‌حل درست                                                                                |
| -- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| ۱۶ | استفاده از `dayjs` + پلاگین `jalaliday` (نسخهٔ 3.1.1)                                        | در تمام سال‌های کبیسهٔ میلادی، از ۱ ژانویه تا ۲۹ فوریه تبدیل میلادی به شمسی ۱ روز خطا داره (مثلا `2024-01-20` رو به جای `۱۴۰۲/۱۰/۳۰` می‌ده `۱۴۰۲/۱۱/۰۱`!) | تا زمان رفع باگ، از کتابخونهٔ دیگه‌ای استفاده کنید و با `data/test-vectors.csv` تستش کنید  |
| ۱۷ | استفاده از پکیج پایتونی `khayyam`                                                            | به خاطر چرخهٔ ۲۸۲۰ ساله، همین الان برای سال‌های ۱۴۰۳ و ۱۴۰۴ تاریخ اشتباه می‌ده                                                                            | مهاجرت به `persiantools` یا `jdatetime`                                                    |
| ۱۸ | استفاده از gem روبی `parsi-date` (نسخهٔ 0.5.1)                                               | در سال‌های کبیسه‌ای مثل ۱۴۰۸ (مارس ۲۰۲۹) تاریخ نامعتبر تولید می‌کنه                                                                                       | استفاده از پیاده‌سازی Ruby موجود در همین مخزن                                              |
| ۱۹ | نسخه‌های قدیمی ICU (نسخهٔ 76.1 و قبل‌تر) در مرورگرهای قدیمی، Node.js ≤ 23 و اندرویدهای قدیمی | تا سال ۱۵۰۲ کاملا درسته، اما از ۱۵۰۳ به بعد جدول اصلاح رو نداره                                                                                           | برای برنامه‌های امروزی هیچ مشکلی نداره (تا سال ۲۱۲۴ میلادی دقیقه)                          |
| ۲۰ | استفاده از کتابخونه‌های دارای مجوز GPL در پروژه‌های تجاری/بسته                               | نقض کپی‌رایت و الزام قانونی به متن‌باز کردن کل پروژه                                                                                                      | بررسی لایسنس کتابخونه‌ها قبل از نصب (مثلا `persian-calendar/calendar` مجوز GPL-2.0+‎ داره) |

## ۴. متن، فونت و رابط کاربری (UI)

| #  | خطا / باگ                                                 | چطوری خودش رو نشون می‌ده؟                                             | راه‌حل درست                                                                                                                            |
| -- | --------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| ۲۱ | حروف `ي` و `ك` عربی در نام ماه‌ها یا جست‌وجوی کاربر       | سرچ کار نمی‌کنه و مقایسهٔ رشته‌ها شکست می‌خوره (چون `"دي" !== "دی"`)  | یکسان‌سازی (Normalize) ورودی‌ها به `ی` (`U+06CC`) و `ک` (`U+06A9`) فارسی                                                               |
| ۲۲ | نمایش ارقام عربی (`٤٥٦`) به جای ارقام فارسی (`۴۵۶`)       | شکل اعداد ۴، ۵ و ۶ در رابط فارسی غریبه و ناهماهنگ به نظر می‌رسه       | استفاده از لوکیل `fa-IR` (سیستم عددنویسی `arabext`)                                                                                    |
| ۲۳ | پاس دادن مستقیم رشتهٔ فارسی به `parseInt('۱۴۰۴')`         | برگردوندن `NaN` در جاوااسکریپت                                        | تبدیل ارقام فارسی و عربی به انگلیسی (`0-9`) قبل از تبدیل به عدد                                                                        |
| ۲۴ | فرمت کردن عدد سال با Formatter معمولی اعداد               | نمایش سال به شکل «۱٬۴۰۴» (با ویرگول هزارگان!)                         | ست کردن `useGrouping: false` یا استفاده از Formatter تاریخ                                                                             |
| ۲۵ | نوشتن «سه شنبه» (با فاصله) یا «سهشنبه» (چسبیده)           | ظاهر نادرست و غیراستاندارد در رابط کاربری                             | نوشتن «سه‌شنبه» با نیم‌فاصله (`U+200C`) در خروجی، و قبول کردن هر سه شکل در ورودی                                                       |
| ۲۶ | شروع شدن جدول تقویم از یکشنبه یا دوشنبه                   | کاربرهای ایرانی موقع انتخاب روز هفته دچار اشتباه می‌شن                | شروع جدول هفته از **شنبه** و با چیدمان راست‌به‌چپ (RTL)                                                                                |
| ۲۷ | رها کردن رشتهٔ تاریخ وسط متن دوسویه (فارسی + انگلیسی)     | جابه‌جا شدن جای سال و روز در نمایش (`01/01/1404` به جای `1404/01/01`) | گذاشتن تاریخ داخل تگ `<bdi>` یا کاراکترهای ایزولهٔ `U+2068…U+2069`                                                                     |
| ۲۸ | استفاده از `dateStyle: 'full'` در `Intl` برای زبان فارسی  | خروجی نامأنوس «۱۴۰۴ فروردین ۱, جمعه»                                  | ساختن عبارت «جمعه ۱ فروردین ۱۴۰۴» با استفاده از `formatToParts` ([بخش ۵](https://goudarzjafari.com/fa/persian-calendar/localization/)) |
| ۲۹ | مرتب‌سازی (Sort) تاریخ‌ها به صورت رشتهٔ متنی بدون صفر اول | تاریخ `1404/1/9` بعد از `1404/1/10` قرار می‌گیره!                     | مرتب‌سازی بر اساس تاریخ میلادی/JDN، یا اضافه کردن صفر دو رقمی (`1404/01/09`)                                                           |

## ۵. دیتابیس و طراحی API

| #  | خطا / باگ                                                                    | چطوری خودش رو نشون می‌ده؟                                                                 | راه‌حل درست                                                                                                         |
| -- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| ۳۰ | ذخیره کردن تاریخ فقط به صورت رشتهٔ متنی شمسی در دیتابیس                      | کوئری زدن سخت می‌شه، توابع تاریخ دیتابیس از کار می‌افتن و مرتب‌سازی باگ می‌خوره           | ذخیره کردن به صورت تاریخ استاندارد میلادی (`date` / `timestamptz`) و تبدیل به شمسی در لایهٔ نمایش                   |
| ۳۱ | گذاشتن تاریخ شمسی داخل فیلد استاندارد ISO 8601 در API                        | کلاینت‌ها و کتابخونه‌ها رشتهٔ `1404-01-01` رو سال ۱۴۰۴ میلادی (قرن پانزدهم!) تفسیر می‌کنن | ارسال تاریخ میلادی در فیلد اصلی و گذاشتن تاریخ شمسی در فیلد جداگانه مثل `date_fa`                                   |
| ۳۲ | هاردکد کردن تعطیلات رسمی داخل کد برنامه                                      | با اولین تغییر قانون یا جابه‌جا شدن ماه‌های قمری، تعطیلات برنامه اشتباه می‌شه             | خوندن تعطیلات از روی فایل/سرویس دادهٔ قابل آپدیت                                                                    |
| ۳۳ | استفاده از تقویم‌های `islamic` یا `islamic-umalqura` برای تعطیلات قمری ایران | تعطیلاتی مثل عید فطر یا عاشورا در بعضی سال‌ها یک روز خطا دارن                             | استفاده از جدول شروع ماه‌های قمری ایران ([بخش ۷: تعطیلات](https://goudarzjafari.com/fa/persian-calendar/holidays/)) |

---

نشانی صفحه: https://goudarzjafari.com/fa/persian-calendar/pitfalls/
مجوز: متن CC BY 4.0، کد MIT، داده CC0 1.0. نسخهٔ 1.0.0 از https://github.com/Goudarz/PersianCalendar
