# راهنمای پیاده‌سازی

این صفحه یک راهنمای عملی برای اضافه کردن تقویم شمسی به یک اپلیکیشن، وب‌سایت، کتابخونه یا دیتابیس واقعیه: اینکه چه تصمیم‌هایی باید بگیرید، تقویم کجای معماری نرم‌افزار قرار می‌گیره و در نهایت یک چک‌لیست کاربردی.

## گام ۱: مشخص کنید دقیقا چی لازم دارید

```
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 یا گزارش‌گیری بازه‌ای** هم دارید؟ اگر کتابخونهٔ خوب و تست‌شده‌ای برای زبانتون وجود داره ([بخش ۶](https://goudarzjafari.com/fa/persian-calendar/languages-and-libraries/)) از همون استفاده کنید؛ در غیر این صورت، کد آمادهٔ زبانتون رو از پوشهٔ [`implementations`](https://goudarzjafari.com/fa/persian-calendar/implementations/) همراه با فایل تستش بردارید و تست رو روی داده‌های [`data`](https://goudarzjafari.com/fa/persian-calendar/data/) اجرا کنید.

بیشتر پروژه‌ها فقط به نمایش تاریخ نیاز دارن؛ مثلا توی مرورگر یا Node.js همین یک خط کافیه:

```js
new Intl.DateTimeFormat('fa-IR', { dateStyle: 'long', timeZone: 'Asia/Tehran' }).format(new Date())
// → "۱ فروردین ۱۴۰۴"
```

## گام ۲: در دیتابیس و بک‌اند، همیشه تاریخ میلادی یا 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) در ایران به‌طور دائمی لغو شد.** \[[۱](https://rc.majlis.ir/fa/law/show/1745106)] پس از بازگشت ساعت در ۳۰ شهریور ۱۴۰۱، از ابتدای سال ۱۴۰۲ (مارس ۲۰۲۳) دیگر ساعت رسمی کشور جلو کشیده نمی‌شود. سرورها، پلتفرم‌ها و کتابخانه‌هایی که دیتابیس منطقهٔ زمانی آن‌ها قدیمی‌تر از نسخهٔ [`tzdata 2022b`](https://data.iana.org/time-zones/tzdb-2022b/NEWS) (منتشرشده در پایگاه [IANA Time Zone Database](https://www.iana.org/time-zones)) باشد، همچنان در ابتدای بهار ساعت را یک ساعت به جلو می‌برند (`+04:30`). این ناهماهنگی باعث بروز خطای یک‌ساعته در ثبت تراکنش‌ها، لاگ‌ها و تغییر نادرست تاریخ در حوالی نیمه‌شب می‌شود. حتما `tzdata`، ‏ICU، سیستم‌عامل، JDK و ایمیج‌های Docker خودتون رو آپدیت نگه دارید.

- **افغانستان**: شناسهٔ `Asia/Kabul` (با اختلاف `UTC+4:30`).

- هیچ‌وقت مقدار `+03:30` رو توی کد هاردکد نکنید؛ همیشه از نام استاندارد `Asia/Tehran` استفاده کنید، چون در سال‌های قبل از ۱۴۰۲ در شش ماه اول سال اختلاف ساعت `+04:30` بوده است.

```js
// 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 تبدیل نکنید، چون برای کاربرهایی که غرب [نصف‌النهار گرینویچ](https://fa.wikipedia.org/wiki/%D9%86%D8%B5%D9%81%E2%80%8C%D8%A7%D9%84%D9%86%D9%87%D8%A7%D8%B1_%D9%85%D8%A8%D8%AF%D8%A3) هستن، تاریخ یک روز عقب می‌افته!
- در جاوااسکریپت، `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`](https://goudarzjafari.com/fa/persian-calendar/implementations/postgresql/) توابع آمادهٔ PostgreSQL قرار دارن که از نوع `IMMUTABLE` هستن و می‌تونید مستقیم توی ایندکس‌ها و ستون‌های محاسباتی (Generated Columns) ازشون استفاده کنید.

## گام ۶: نمایش هفته و تقویم

- هفته در ایران و افغانستان از **شنبه** شروع می‌شه؛ پس ستون‌های تقویم باید از شنبه تا جمعه چیده بشن.
- برای **شمارهٔ هفته در سال** استاندارد رسمی واحدی وجود نداره، اما تعریف رایج اینه: «هفتهٔ اول سال، هفته‌ایه که ۱ فروردین توش قرار داره و هفته‌ها از شنبه شروع می‌شن.» حتما هر تعریفی رو که توی پروژه‌تون استفاده می‌کنید مستند کنید و حواستون باشه که شمارهٔ هفتهٔ استاندارد ISO 8601 (که از دوشنبه و سال میلادی حساب می‌شه) برای تقویم شمسی کاربردی نداره.
- تعطیل رسمی آخر هفته در ایران جمعه‌ست، و پنجشنبه‌ها هم در بسیاری از شرکت‌ها و اداره‌ها تعطیل یا نیمه‌تعطیله؛ پس روزهای تعطیل آخر هفته رو قابل تنظیم طراحی کنید.

## گام ۷: خواندن و پردازش ورودی کاربر (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` هم وجود نداره (چون مهر ۳۰ روزه‌ست).
- **نام ماه‌ها در متن**: اگر کاربر اسم ماه رو تایپ می‌کنه، اول حروف `ي`/`ك` عربی رو به `ی`/`ک` فارسی تبدیل کنید و تفاوت فاصله و نیم‌فاصله رو هم نادیده بگیرید ([بخش ۵: بومی‌سازی](https://goudarzjafari.com/fa/persian-calendar/localization/)).

```python
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` استفاده کنید تا ارقام فارسی و نام ماه‌ها به شکل استاندارد تولید بشن ([بومی‌سازی](https://goudarzjafari.com/fa/persian-calendar/localization/)).
- فرمت‌های پرکاربرد: `۱۴۰۴/۰۱/۰۱`، `۱ فروردین ۱۴۰۴` و `جمعه ۱ فروردین ۱۴۰۴` (و در رابط کاربری انگلیسی: `1 Farvardin 1404` یا `1404-01-01`).
- وقتی تاریخ در کنار متنی با جهت مخالف قرار می‌گیره (مثلا تاریخ فارسی وسط متن انگلیسی یا برعکس)، اون رو داخل تگ `<bdi>` یا ویژگی `dir="auto"` (یا کاراکترهای ایزولهٔ یونیکد U+2068…U+2069) بذارید تا ترتیب سال و ماه و روز به هم نریزه.
- نشون دادن تاریخ میلادی در کنار تاریخ شمسی (مثلا داخل یک Tooltip وقتی موس روی تاریخ می‌ره) به کاربرهایی که با شرکت‌ها و سرویس‌های بین‌المللی کار می‌کنن خیلی کمک می‌کنه.

## گام ۹: کامپوننت‌های رابط کاربری (Datepicker و تقویم)

یک Datepicker شمسی خوب باید این ویژگی‌ها رو داشته باشه:

- جدول هفته رو از **شنبه** شروع کنه، طول ماه‌های ۲۹، ۳۰ و ۳۱ روزه رو درست نشون بده و چیدمانش راست‌به‌چپ (RTL) باشه؛
- دکمه‌های «ماه قبل / ماه بعد» و «سال قبل / سال بعد» بر اساس ماه و سال شمسی حرکت کنن (نه میلادی)؛
- روز «امروز» رو بر اساس تایم‌زون کاربر مشخص کنه؛
- خروجی‌ای که به کد برنامه تحویل می‌ده، تاریخ استاندارد میلادی (ISO) یا Timestamp باشه (طبق گام ۲)؛
- تایپ مستقیم تاریخ با کیبورد رو طبق قواعد گام ۷ قبول کنه؛
- تعطیلات رو از روی فایل/سرویس داده بخونه ([بخش ۷: تعطیلات](https://goudarzjafari.com/fa/persian-calendar/holidays/))، نه اینکه داخل کد کامپوننت هاردکد شده باشه.

## گام ۱۰: تست کردن

کدتون رو حتما با داده‌های مرجع [`data/years.csv`](https://goudarzjafari.com/persian-calendar/files/data/years.csv) و [`data/test-vectors.csv`](https://goudarzjafari.com/persian-calendar/files/data/test-vectors.csv) تست کنید.
لیست کامل تست‌های ضروری رو در بخش [۹. تست](https://goudarzjafari.com/fa/persian-calendar/testing/) آوردیم، اما این ۴ مورد از همه مهم‌ترن:

1. کبیسه بودن سال‌های ۱۳۹۹، ۱۴۰۳ و **۱۴۰۸** (اولین فاصلهٔ ۵ ساله بعد از ۱۳۷۵) و کبیسه نبودن سال ۱۴۰۴.
2. تبدیل درست مرز سال کبیسه: ۳۰ اسفند ۱۴۰۳ = `2025-03-20` و ۱ فروردین ۱۴۰۴ = `2025-03-21`.
3. تبدیل دوطرفهٔ (شمسی ← میلادی ← شمسی) تک‌تک روزها در یک بازهٔ طولانی.
4. تست یک لحظهٔ زمانی نزدیک نیمه‌شب در تایم‌زون `Asia/Tehran` در مقایسه با `UTC`.

## چک‌لیست نهایی

- [ ] دادهٔ اصلی در دیتابیس و API به صورت میلادی/ISO/UTC ذخیره می‌شه و تبدیل به شمسی فقط در لایهٔ نمایش و ورودی انجام می‌شه.
- [ ] تشخیص سال کبیسه از الگوریتم درست استفاده می‌کنه (نه چرخهٔ ۲۸۲۰ ساله) و برای سال‌های ۱۴۰۳، ۱۴۰۴ و ۱۴۰۸ تست شده است.
- [ ] تایم‌زون روی `Asia/Tehran` تنظیم شده و دیتابیس تایم‌زون سیستم (`tzdata`) نسخهٔ `2022b` یا جدیدتر است.
- [ ] هفته از شنبه شروع می‌شه و روزهای تعطیل آخر هفته قابل تنظیم هستن.
- [ ] بخش دریافت ورودی، ارقام فارسی، عربی و انگلیسی رو قبول می‌کنه و تاریخ‌هایی مثل ۳۰ اسفند رو اعتبارسنجی می‌کنه.
- [ ] اضافه کردن ماه به تاریخ، شمارهٔ روز رو به حداکثر طول ماه مقصد محدود (Clamp) می‌کنه.
- [ ] کوئری‌های بازه‌ای در دیتابیس به شکل بازهٔ نیمه‌باز `[start, next_start)` و بر اساس شروع ماه شمسی نوشته شدن.
- [ ] نمایش تاریخ با Formatter استاندارد یا نام‌های CLDR انجام می‌شه، «سه‌شنبه» نیم‌فاصله داره و از `ی`/`ک` استاندارد فارسی استفاده شده است.
- [ ] تعطیلات به صورت دادهٔ قابل به‌روزرسانی (همراه با منبع) تعریف شدن، نه ثابت در کد.
- [ ] تست‌های خودکار روی فایل‌های پوشهٔ `data/` اجرا و پاس می‌شن.

---

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