استاندارد زمان‌ها

• تمام زمان‌ها در دیتابیس به‌صورت UTC ذخیره می‌شوند (created، updated، deleted، startTime، endTime، …).
• روی wire، زمان‌ها همیشه به‌صورت ISO 8601 برمی‌گردند (مثل 2026-07-02T15:30:00.000Z).
• روی wire، ستون‌های created/updated در JSON همهٔ موجودیت‌ها با نام createdAt/updatedAt برمی‌گردند (مثل DeviceDto، موجودیت‌های pull در sync و پروفایل کاربر)؛ نامِ ستونی فقط سمت دیتابیس و Prisma است.
• فیلد version (مربوط به همگام‌سازی) چون BigInt است، روی wire همیشه به‌صورت string بازمی‌گردد.

ستون‌های زمانیِ یکسان

بیشتر مدل‌ها سه فیلدِ زمانیِ استاندارد دارند:

فیلد	نوع	معنی
created	DateTime	زمانِ ساختِ رکورد
updated	DateTime	زمانِ آخرین تغییر (توسط تریگر bump_record_version خودکار ست می‌شود)
deleted	DateTime?	زمانِ حذفِ نرم (NULL یعنی حذف‌نشده)

این سه‌تایی روی این مدل‌ها هست: User، Calendar، Event، Task، Reminder، CalendarShare، PersianHoliday.

استثناها:

• Device فقط created/updated دارد (deleted ندارد؛ حذفِ دستگاه فیزیکی است).
• SyncConflict فقط created دارد.

version و تریگرِ نسخه‌بندی

چهار موجودیتِ همگام‌شونده — Calendar، Event، Task، Reminder — یک ستونِ version BigInt دارند. این ستون توسط تریگرِ bump_record_version() روی هر INSERT/UPDATE از یک دنبالهٔ سراسری به‌نام record_version_seq پر می‌شود؛ همان تریگر updated را هم به now() ست می‌کند. پیش از اختصاصِ نسخه، تریگر یک advisory lock کاربر-محور می‌گیرد تا نوشتن‌های هم‌زمانِ یک کاربر نسخه‌های پشت‌سرهم نگیرند. (جزئیات ستون‌ها در پایگاه داده.)

معادلسازیِ کوئری (Prisma)

// رکوردهای اخیر
const recent = await prisma.calendar.findMany({
  where: { created: { gte: new Date(Date.now() - 7 * 86400_000) } },
});

// به‌روزرسانی‌های اخیر
const updated = await prisma.event.findMany({
  where: { updated: { gte: new Date(Date.now() - 86400_000) } },
});

// فقط فعال‌ها (حذف‌نشده)
const active = await prisma.event.findMany({ where: { deleted: null } });

// حذف‌شده‌ها
const trashed = await prisma.calendar.findMany({ where: { deleted: { not: null } } });

چرا این الگو؟

• یکسان‌سازی: همهٔ مدل‌ها از همان نام‌گذاری استفاده می‌کنند.
• حذفِ نرم: deleted اجازه می‌دهد رکورد را بدون حذفِ فیزیکی علامت بزنید — برای tombstone‌های همگام‌سازی لازم است.
• کارایی: ایندکس روی created/updated/deleted/version کوئری‌های رایج و همگام‌سازی را سریع نگه می‌دارد.