پایگاه داده

دیتابیس PostgreSQL است و از طریق Prisma دسترسی می‌شود. مرجع فیلدها apps/api/prisma/schema.prisma و مرجع قیود و triggerها apps/api/prisma/migrations است — هر دو معتبرند؛ خواندن فقط schema کافی نیست.

روابط اصلی:

User → Calendar → Event → Reminder
  ├─ Task → Reminder (والد یادآور: event XOR task)
  │    └─ والد زیروظیفه: Task دیگر
  ├─ Device
  ├─ SyncMutationReceipt
  └─ UserErrorLog

Task به Calendar و Event هم (به‌صورت اختیاری) وصل می‌شود. دو جدول CalendarShare و PersianHoliday در schema هستند؛ وجود جدول به معنی API فعال نیست.

migrationهای کلیدی

migration	رفتار ضروری
20260702030000_android_sync_phase1	ستون‌های uid/version چهار موجودیت، دنبالهٔ سراسری نسخه، قفل کاربر و triggerهای نسخه/updated؛ قید XOR یادآور
20260929100000_sync_mutation_receipts	جدول رسیدهای (userId, mutationId) با fingerprint و نتیجه؛ ایندکس یکتای مشروطِ «یک پیش‌فرض زنده» — اگر کاربری بیش از یک تقویم پیش‌فرض زنده داشته باشد، migration متوقف می‌شود
20261001090000_add_provider_id	ستون nullable از نوع BIGINT فقط برای Calendar/Event/Reminder؛ بدون backfill
20261001090100_add_user_error_logs	جدول گزارش خطای وابسته به کاربر؛ حذف کاربر، گزارش‌هایش را هم حذف می‌کند

نکات عملیاتی

• providerId روی wire عدد است؛ ورودی باید صحیح امن JSON باشد (-9007199254740991..9007199254740991). PostgreSQL آن را nullable BIGINT و کلاینت Kotlin آن را Long نگه می‌دارد. Task این ستون را ندارد.
• رسیدها سیاست retention ندارند. حذفشان تضمین بازتلاش sync را از بین می‌برد؛ قبل از هر پاک‌سازی، پیامدش را بپذیرید.
• SyncConflict فقط سوابق نسل قبل است. ستون‌های Event.syncStatus و User.lastSyncTime مبنای پروتکل ۲ نیستند.

db:push جایگزین migrate نیست: triggerها و قیود SQL در Prisma schema خلاصه نمی‌شوند. برای تغییر schema، migration بسازید. پس از بررسی DATABASE_URL محیط ایزوله، از ریشه:

corepack pnpm --filter taghvimam-backend run db:generate
corepack pnpm --filter taghvimam-backend run db:migrate

db:deploy فقط migrationهای موجود را اعمال می‌کند و اجرایش در محیط واقعی نیازمند فرایند مجاز انتشار است (استقرار). توجه: تست DB داده را پاک می‌کند — اول ایمنی محیط تست را بخوانید. گزارش‌های خطای کاربران: دستگاه‌ها.