فصل ۴ از ۱۰
راهنمای پیادهسازی
۱۱ دقیقه مطالعهبهروزرسانی
این صفحه یک راهنمای عملی برای اضافه کردن تقویم شمسی به یک اپلیکیشن، وبسایت، کتابخونه یا دیتابیس واقعیه: اینکه چه تصمیمهایی باید بگیرید، تقویم کجای معماری نرمافزار قرار میگیره و در نهایت یک چکلیست کاربردی.
گام ۱: مشخص کنید دقیقا چی لازم دارید
پیوند به بخش گام ۱: مشخص کنید دقیقا چی لازم داریدDo you only DISPLAY dates in the Persian calendar?
├─ yes → use the platform's formatter (Intl / ICU / .NET culture / Foundation). No library, no algorithm.
└─ no, you also parse input, do date arithmetic, build a calendar UI, or compute ranges
├─ is there a well-tested library for your language? (see page 6)
│ └─ yes → use it
└─ no / you need zero dependencies / SQL / embedded
└─ copy the implementation for your language from /implementations
and its test, then run the test against /data- فقط میخواید تاریخ رو به شمسی نمایش بدید؟ از همون ابزار قالببندی (Formatter) خود پلتفرم استفاده کنید (
Intlدر جاوااسکریپت، ICU، فرهنگfa-IRدر .NET، یاFoundationدر اپل). در این حالت نه به کتابخونهٔ خارجی نیاز دارید و نه به الگوریتم. - علاوه بر نمایش، خواندن ورودی کاربر، محاسبه با تاریخ، ساختن Datepicker یا گزارشگیری بازهای هم دارید؟ اگر کتابخونهٔ خوب و تستشدهای برای زبانتون وجود داره (بخش ۶) از همون استفاده کنید؛ در غیر این صورت، کد آمادهٔ زبانتون رو از پوشهٔ
implementationsهمراه با فایل تستش بردارید و تست رو روی دادههایdataاجرا کنید.
بیشتر پروژهها فقط به نمایش تاریخ نیاز دارن؛ مثلا توی مرورگر یا Node.js همین یک خط کافیه:
new Intl.DateTimeFormat('fa-IR', { dateStyle: 'long', timeZone: 'Asia/Tehran' }).format(new Date())
// → "۱ فروردین ۱۴۰۴"گام ۲: در دیتابیس و بکاند، همیشه تاریخ میلادی یا Timestamp ذخیره کنید
پیوند به بخش گام ۲: در دیتابیس و بکاند، همیشه تاریخ میلادی یا Timestamp ذخیره کنیدهیچوقت رشتهٔ تاریخ شمسی رو به عنوان دادهٔ اصلی ذخیره نکنید. به جاش:
- لحظههای زمانی (مثل زمان ثبت سفارش یا لاگ) رو به صورت Timestamp بر مبنای UTC ذخیره کنید (
timestamptz،Instant،DateTimeOffsetیا Unix timestamp)؛ - تاریخهای تقویمی بدون ساعت (مثل تاریخ تولد یا تاریخ سررسید) رو به شکل تاریخ استاندارد میلادی/ISO ذخیره کنید (
date،LocalDate،DateOnlyیاYYYY-MM-DD).
تبدیل به تاریخ شمسی رو فقط در لبههای سیستم (لایهٔ نمایش و دریافت ورودی) انجام بدید:
user input "۱۴۰۴/۰۱/۰۱" ─parse→ 2025-03-21 ─store→ DB (date)
DB 2025-03-21 ─format→ "۱ فروردین ۱۴۰۴" ─display→ userچرا این کار بهترین روشه؟
- تمام دیتابیسها، APIها، ایندکسها، مرتبسازیها و توابع تاریخ به صورت پیشفرض با تاریخ میلادی/ISO کار میکنن.
- همون داده رو میتونید به راحتی برای کاربرهای دیگه به میلادی یا هر تقویم و زبان دیگهای نشون بدید.
- چون تبدیل بین میلادی و شمسی کاملا یکبهیک و قطعیه، هیچ اطلاعاتی در این بین از دست نمیره.
چه زمانی لازمه خود تاریخ شمسی رو هم ذخیره کنیم؟ وقتی در اسناد حقوقی یا مالی، خود عبارت شمسی بخشی از متن سنده (مثلا قراردادی «مورخ ۱۴۰۴/۰۱/۱۵»). در این حالت هم تاریخ شمسی رو در کنار تاریخ میلادی ذخیره کنید، نه به جای اون.
اگر به هر دلیلی مجبور شدید روی تاریخ شمسی مرتبسازی یا ایندکسگذاری کنید، اون رو به صورت عدد صحیح yyyymmdd (مثلا 14040115) نگه دارید تا ترتیبش درست بمونه؛ رشتههای متنی (مخصوصا اگر صفر اول ماه و روز رو نداشته باشن یا با اعداد فارسی نوشته بشن) توی مرتبسازی به هم میریزن.
توی APIها: تاریخها رو همیشه با فرمت استاندارد ISO 8601 (میلادی) ردوبدل کنید. اگر کلاینت به رشتهٔ آمادهٔ شمسی هم نیاز داره، اون رو توی یک فیلد جداگانه با اسم مشخص بفرستید (مثلا "date_fa": "1404/01/01"). هیچوقت تاریخ شمسی رو داخل فیلدی که قراره ISO 8601 باشه نذارید!
گام ۳: حواستون به تایمزون (منطقهٔ زمانی) باشه
پیوند به بخش گام ۳: حواستون به تایمزون (منطقهٔ زمانی) باشهتاریخ شمسی هر لحظه از زمان، درست مثل تاریخ میلادی، به تایمزون بستگی داره.
-
ایران: شناسهٔ استاندارد IANA برابر با
Asia/Tehran(با اختلاف ثابتUTC+3:30) است. نکتهٔ حیاتی: با تصویب قانون نسخ قانون تغییر ساعت رسمی کشور، تغییر ساعت تابستانی (DST) در ایران بهطور دائمی لغو شد. [۱] پس از بازگشت ساعت در ۳۰ شهریور ۱۴۰۱، از ابتدای سال ۱۴۰۲ (مارس ۲۰۲۳) دیگر ساعت رسمی کشور جلو کشیده نمیشود. سرورها، پلتفرمها و کتابخانههایی که دیتابیس منطقهٔ زمانی آنها قدیمیتر از نسخهٔtzdata 2022b(منتشرشده در پایگاه IANA Time Zone Database) باشد، همچنان در ابتدای بهار ساعت را یک ساعت به جلو میبرند (+04:30). این ناهماهنگی باعث بروز خطای یکساعته در ثبت تراکنشها، لاگها و تغییر نادرست تاریخ در حوالی نیمهشب میشود. حتماtzdata، ICU، سیستمعامل، JDK و ایمیجهای Docker خودتون رو آپدیت نگه دارید. -
افغانستان: شناسهٔ
Asia/Kabul(با اختلافUTC+4:30). -
هیچوقت مقدار
+03:30رو توی کد هاردکد نکنید؛ همیشه از نام استانداردAsia/Tehranاستفاده کنید، چون در سالهای قبل از ۱۴۰۲ در شش ماه اول سال اختلاف ساعت+04:30بوده است.
// The same instant, two different Persian dates:
const t = new Date('2025-03-20T21:00:00Z')
fmt('Asia/Tehran') // 1 Farvardin 1404 (00:30 local time)
fmt('UTC') // 30 Esfand 1403چند قانون طلایی:
- «امروز» یعنی تاریخ امروز در تایمزون کاربر؛ اول تاریخ رو در تایمزون کاربر بگیرید و بعد به شمسی تبدیل کنید.
- دادههایی که «فقط تاریخ» هستن (مثل تاریخ تولد:
dateیاLocalDate) اصلا تایمزون ندارن؛ اونها رو مستقیم تبدیل کنید. هیچوقت یک تاریخ ساده رو به نیمهشب UTC تبدیل نکنید، چون برای کاربرهایی که غرب نصفالنهار گرینویچ هستن، تاریخ یک روز عقب میافته! - در جاوااسکریپت،
new Date(2025, 2, 21)نیمهشب به وقت محلی سیستم است، ولیnew Date('2025-03-21')نیمهشب به وقت UTC است. قاطی کردن این دو تا یکی از رایجترین دلایل باگهای یکروزهست.
گام ۴: محاسبات روی تاریخ (اضافه کردن روز، ماه و سال)
پیوند به بخش گام ۴: محاسبات روی تاریخ (اضافه کردن روز، ماه و سال)اضافه و کم کردن «روز» خیلی سادهست: تاریخ رو به شمارهٔ روز (JDN) تبدیل کنید، تعداد روز رو جمع بزنید و برگردونید. اما برای اضافه کردن «ماه» یا «سال»، باید تکلیف روزهای آخر ماه رو مشخص کنید (چون طول ماهها فرق داره):
| عملیات | نتیجهٔ درست | قانون |
|---|---|---|
| ۳۱ شهریور ۱۴۰۴ + ۱ ماه | ۳۰ مهر ۱۴۰۴ | اگر روز از طول ماه مقصد بیشتر بود، به آخرین روز ماه محدودش کنید (Clamp) |
| ۳۰ اسفند ۱۴۰۳ + ۱ سال | ۲۹ اسفند ۱۴۰۴ | محدود کردن به طول اسفند ۱۴۰۴ (چون ۱۴۰۴ کبیسه نیست) |
| ۳۱ فروردین + ۶ ماه | ۳۰ مهر | محدود کردن به ۳۰ روز |
| ۱ فروردین ۱۴۰۴ − ۱ روز | ۳۰ اسفند ۱۴۰۳ | تفریق روزانه از طریق JDN؛ نیازی به قانون خاص نداره |
ابزارهای استانداردی مثل ICU، Temporal (با تنظیم پیشفرض overflow: 'constrain') و متد PersianCalendar.AddMonths در .NET هم دقیقا به همین شکل عمل میکنن.
function add_months(y, m, d, n):
total = (y * 12 + (m - 1)) + n
y2 = floor_div(total, 12); m2 = floor_mod(total, 12) + 1
return (y2, m2, min(d, days_in_month(y2, m2)))هیچوقت برای اضافه کردن یک ماه شمسی، تاریخ رو به میلادی تبدیل نکنید که یک ماه میلادی بهش اضافه کنید و برگردونید! چون طول ماههای میلادی و شمسی با هم فرق داره و نتیجه روی روز دیگهای میافته.
گام ۵: بازههای زمانی، گزارشگیری و کوئریهای دیتابیس
پیوند به بخش گام ۵: بازههای زمانی، گزارشگیری و کوئریهای دیتابیسفرض کنید میخواید «همهٔ سفارشهای مهر ۱۴۰۴» رو از دیتابیس بگیرید. راه درست اینه که ابتدا و انتهای بازهٔ شمسی رو به میلادی تبدیل کنید و بعد روی ستون میلادی ایندکسشده کوئری بزنید:
start = to_gregorian(1404, 7, 1) # 2025-09-23
end = to_gregorian(1404, 8, 1) # 2025-10-23 (exclusive)
SELECT … WHERE created_at >= start AND created_at < end -- in the user's time zone!- همیشه از بازهٔ نیمهباز
[start, next_start)(یعنی از اول این ماه تا قبل از اول ماه بعد) استفاده کنید تا اصلا درگیر این نشید که ماه ۲۹، ۳۰ یا ۳۱ روزه است. - فصلهای شمسی دقیقا منطبق بر ماهها هستن: بهار (۱ تا ۳)، تابستان (۴ تا ۶)، پاییز (۷ تا ۹) و زمستان (۱۰ تا ۱۲).
- سال مالی در ایران از ۱ فروردین شروع میشه و با سال تقویمی شمسی یکیه.
- اگر گزارشهای تحلیلی و BI سنگین دارید، ساختن یک جدول بعد تاریخ (Date Dimension Table) که به ازای هر روز یک سطر شامل سال، ماه، روز شمسی، روز هفته و وضعیت تعطیلی داره، کارتون رو خیلی راحت میکنه. میتونید این جدول رو یکبار با هرکدوم از کدهای این مخزن بسازید و پر کنید. همچنین در پوشهٔ
implementations/sqlتوابع آمادهٔ PostgreSQL قرار دارن که از نوعIMMUTABLEهستن و میتونید مستقیم توی ایندکسها و ستونهای محاسباتی (Generated Columns) ازشون استفاده کنید.
گام ۶: نمایش هفته و تقویم
پیوند به بخش گام ۶: نمایش هفته و تقویم- هفته در ایران و افغانستان از شنبه شروع میشه؛ پس ستونهای تقویم باید از شنبه تا جمعه چیده بشن.
- برای شمارهٔ هفته در سال استاندارد رسمی واحدی وجود نداره، اما تعریف رایج اینه: «هفتهٔ اول سال، هفتهایه که ۱ فروردین توش قرار داره و هفتهها از شنبه شروع میشن.» حتما هر تعریفی رو که توی پروژهتون استفاده میکنید مستند کنید و حواستون باشه که شمارهٔ هفتهٔ استاندارد ISO 8601 (که از دوشنبه و سال میلادی حساب میشه) برای تقویم شمسی کاربردی نداره.
- تعطیل رسمی آخر هفته در ایران جمعهست، و پنجشنبهها هم در بسیاری از شرکتها و ادارهها تعطیل یا نیمهتعطیله؛ پس روزهای تعطیل آخر هفته رو قابل تنظیم طراحی کنید.
گام ۷: خواندن و پردازش ورودی کاربر (Parsing)
پیوند به بخش گام ۷: خواندن و پردازش ورودی کاربر (Parsing)کاربرها به شکلهای مختلفی تاریخ رو تایپ میکنن؛ کد شما باید با همهٔ این حالتها راه بیاد:
- ارقام: اعداد فارسی (
۰–۹با کد U+06F0 تا U+06F9)، اعداد عربی (٠–٩با کد U+0660 تا U+0669) و اعداد انگلیسی (0–9). قبل از هر کاری همه رو به اعداد انگلیسی تبدیل کنید. - جداکنندهها: اسلش (
/)، خط تیره (-)، نقطه (.) و فاصله رو قبول کنید. - ترتیب اجزا: کاربر فارسیزبان همیشه تاریخ رو به ترتیب سال/ماه/روز وارد میکنه (مثلا
۱۴۰۴/۰۱/۱۵). - سالهای دو رقمی (مثل
04/01/15): چون ممکنه ابهام ایجاد کنن، یا ردشون کنید یا صریحا به سال چهار رقمی (04←1404) تبدیلشون کنید. - اعتبارسنجی منطقی: حتما تاریخ رو با تابع
is_valid(y, m, d)چک کنید؛ مثلا1404/12/30نامعتبره (چون ۱۴۰۴ کبیسه نیست) و1404/07/31هم وجود نداره (چون مهر ۳۰ روزهست). - نام ماهها در متن: اگر کاربر اسم ماه رو تایپ میکنه، اول حروف
ي/كعربی رو بهی/کفارسی تبدیل کنید و تفاوت فاصله و نیمفاصله رو هم نادیده بگیرید (بخش ۵: بومیسازی).
PERSIAN = str.maketrans('۰۱۲۳۴۵۶۷۸۹٠١٢٣٤٥٦٧٨٩', '01234567890123456789')
def parse_persian_date(text):
parts = re.split(r'[/\-.\s]+', text.strip().translate(PERSIAN))
y, m, d = (int(p) for p in parts)
if not is_valid_date(y, m, d):
raise ValueError('invalid date')
return y, m, dگام ۸: قالببندی و نمایش تاریخ
پیوند به بخش گام ۸: قالببندی و نمایش تاریخ- تا جای ممکن از Formatter استاندارد خود پلتفرم با
fa-IRاستفاده کنید تا ارقام فارسی و نام ماهها به شکل استاندارد تولید بشن (بومیسازی). - فرمتهای پرکاربرد:
۱۴۰۴/۰۱/۰۱،۱ فروردین ۱۴۰۴وجمعه ۱ فروردین ۱۴۰۴(و در رابط کاربری انگلیسی:1 Farvardin 1404یا1404-01-01). - وقتی تاریخ در کنار متنی با جهت مخالف قرار میگیره (مثلا تاریخ فارسی وسط متن انگلیسی یا برعکس)، اون رو داخل تگ
<bdi>یا ویژگیdir="auto"(یا کاراکترهای ایزولهٔ یونیکد U+2068…U+2069) بذارید تا ترتیب سال و ماه و روز به هم نریزه. - نشون دادن تاریخ میلادی در کنار تاریخ شمسی (مثلا داخل یک Tooltip وقتی موس روی تاریخ میره) به کاربرهایی که با شرکتها و سرویسهای بینالمللی کار میکنن خیلی کمک میکنه.
گام ۹: کامپوننتهای رابط کاربری (Datepicker و تقویم)
پیوند به بخش گام ۹: کامپوننتهای رابط کاربری (Datepicker و تقویم)یک Datepicker شمسی خوب باید این ویژگیها رو داشته باشه:
- جدول هفته رو از شنبه شروع کنه، طول ماههای ۲۹، ۳۰ و ۳۱ روزه رو درست نشون بده و چیدمانش راستبهچپ (RTL) باشه؛
- دکمههای «ماه قبل / ماه بعد» و «سال قبل / سال بعد» بر اساس ماه و سال شمسی حرکت کنن (نه میلادی)؛
- روز «امروز» رو بر اساس تایمزون کاربر مشخص کنه؛
- خروجیای که به کد برنامه تحویل میده، تاریخ استاندارد میلادی (ISO) یا Timestamp باشه (طبق گام ۲)؛
- تایپ مستقیم تاریخ با کیبورد رو طبق قواعد گام ۷ قبول کنه؛
- تعطیلات رو از روی فایل/سرویس داده بخونه (بخش ۷: تعطیلات)، نه اینکه داخل کد کامپوننت هاردکد شده باشه.
گام ۱۰: تست کردن
پیوند به بخش گام ۱۰: تست کردنکدتون رو حتما با دادههای مرجع data/years.csv و data/test-vectors.csv تست کنید.
لیست کامل تستهای ضروری رو در بخش ۹. تست آوردیم، اما این ۴ مورد از همه مهمترن:
- کبیسه بودن سالهای ۱۳۹۹، ۱۴۰۳ و ۱۴۰۸ (اولین فاصلهٔ ۵ ساله بعد از ۱۳۷۵) و کبیسه نبودن سال ۱۴۰۴.
- تبدیل درست مرز سال کبیسه: ۳۰ اسفند ۱۴۰۳ =
2025-03-20و ۱ فروردین ۱۴۰۴ =2025-03-21. - تبدیل دوطرفهٔ (شمسی ← میلادی ← شمسی) تکتک روزها در یک بازهٔ طولانی.
- تست یک لحظهٔ زمانی نزدیک نیمهشب در تایمزون
Asia/Tehranدر مقایسه باUTC.
چکلیست نهایی
پیوند به بخش چکلیست نهایی- دادهٔ اصلی در دیتابیس و API به صورت میلادی/ISO/UTC ذخیره میشه و تبدیل به شمسی فقط در لایهٔ نمایش و ورودی انجام میشه.
- تشخیص سال کبیسه از الگوریتم درست استفاده میکنه (نه چرخهٔ ۲۸۲۰ ساله) و برای سالهای ۱۴۰۳، ۱۴۰۴ و ۱۴۰۸ تست شده است.
- تایمزون روی
Asia/Tehranتنظیم شده و دیتابیس تایمزون سیستم (tzdata) نسخهٔ2022bیا جدیدتر است. - هفته از شنبه شروع میشه و روزهای تعطیل آخر هفته قابل تنظیم هستن.
- بخش دریافت ورودی، ارقام فارسی، عربی و انگلیسی رو قبول میکنه و تاریخهایی مثل ۳۰ اسفند رو اعتبارسنجی میکنه.
- اضافه کردن ماه به تاریخ، شمارهٔ روز رو به حداکثر طول ماه مقصد محدود (Clamp) میکنه.
- کوئریهای بازهای در دیتابیس به شکل بازهٔ نیمهباز
[start, next_start)و بر اساس شروع ماه شمسی نوشته شدن. - نمایش تاریخ با Formatter استاندارد یا نامهای CLDR انجام میشه، «سهشنبه» نیمفاصله داره و از
ی/کاستاندارد فارسی استفاده شده است. - تعطیلات به صورت دادهٔ قابل بهروزرسانی (همراه با منبع) تعریف شدن، نه ثابت در کد.
- تستهای خودکار روی فایلهای پوشهٔ
data/اجرا و پاس میشن.