واژه‌نامه

اگر حین خواندنِ این مستندات به یک اصطلاح برخوردید که معنایش دستتان نیامد، احتمالاً همین‌جاست. اصطلاحاتِ انگلیسیِ رایج در صنعت (مثل API، endpoint، JWT) عمداً ترجمه نشده‌اند — همان شکلی که در کد و مکالمهٔ روزمرهٔ تیم به کار می‌روند این‌جا هم تعریف شده‌اند.

API و وب

اصطلاح	تعریف
API (Application Programming Interface)	مجموعه‌ای از endpoint‌ها که کلاینت از طریق آن‌ها با سرور ارتباط برقرار می‌کند.
endpoint	یک URL مشخص (مثلاً POST /api/sync/push) که یک عملیاتِ واحد را نمایندگی می‌کند.
DTO (Data Transfer Object)	ساختار داده‌ای که روی شبکه منتقل می‌شود — شکلِ دقیقِ request یا response. در این پروژه با Zod تعریف می‌شود.
envelope	قالب استاندارد پاسخ API: { success, data?, error? }. تمام پاسخ‌ها از این قالب پیروی می‌کنند.
CORS (Cross-Origin Resource Sharing)	سازوکار مرورگری که مشخص می‌کند کدام دامنه‌ها مجاز به فراخوانی API هستند.

احراز هویت

اصطلاح	تعریف
JWT (JSON Web Token)	یک توکن امضا‌شده که هویت و نقش کاربر را در خود دارد؛ در هدر Authorization: Bearer <token> ارسال می‌شود.
Access token	توکن کوتاه‌عمر (۱۵ دقیقه) برای دسترسی به endpoint‌های محافظت‌شده.
Refresh token	توکن طولانی‌عمر (۹۰ روز) که فقط برای گرفتن access token جدید استفاده می‌شود و در هر بار چرخش (rotate) می‌کند.
Rotation (چرخش توکن)	صادرکردن یک refresh token جدید و باطل‌کردن قبلی، در هر بار استفاده.
OTP (One-Time Password)	کد یک‌بار‌مصرفِ ۶ رقمی که برای ورود پیامک می‌شود.
device-aware	مدلی که در آن هر دستگاه یک refresh token جداگانه و مستقل دارد.
Replay detection	تشخیصِ استفادهٔ مجدد از یک refresh token قدیمی (که قبلاً چرخش خورده) به‌عنوان نشانهٔ سوءاستفاده.
FCM (Firebase Cloud Messaging)	سرویس گوگل برای ارسال push notification به دستگاه‌های موبایل.

همگام‌سازی

اصطلاح	تعریف
uid	شناسهٔ یکتایِ هر رکورد که کلاینت آن را تولید می‌کند؛ مستقل از ID داخلی سرور و در همهٔ دستگاه‌ها یکسان.
version	یک عدد یکتا و تک‌رشته‌ای که سرور به هر تغییر اختصاص می‌دهد (INSERT، UPDATE و حذفِ نرم)؛ مبنای همگام‌سازی تفاضلی. روی wire همیشه string است (چون BigInt).
baseVersion	آخرین versionی که کلاینت هنگام ساختنِ تغییر از ردیف دیده؛ سرور با مقایسهٔ آن با version فعلی تشخیص می‌دهد نوشته clean است یا stale. null یعنی کلاینت ردیف را هرگز ندیده (سیگنالِ create).
cursor	یک token امضاشده (black-box) که کلاینت آن را ذخیره می‌کند و در هر pull به سرور می‌فرستد. سرور از روی آن می‌فهمد تا کجا خوانده‌ای — به‌ازای هر یک از چهار موجودیت.
watermark (واترمارک)	جای‌نمای مصرفِ به‌ازای هر موجودیت داخلِ cursor: «تا version چند از این نوع خوانده‌ام». چون دنباله سراسری است، می‌تواند از version هیچ رکوردی از آن نوع بزرگ‌تر باشد.
HMAC (Hash-based Message Authentication Code)	الگوریتم امضای رمزنگارانه که با یک کلید محرمانه (SYNC_CURSOR_SECRET) یک پیام را امضا می‌کند تا قابل جعل نباشد.
advisory lock	یک قفلِ سطح‌کاربرد در PostgreSQL (pg_advisory_xact_lock) که در این پروژه برای سریال‌کردنِ write‌ها و pull‌های یک کاربر به‌کار می‌رود، تا cursor هیچ رکوردی را از قلم نیندازد.
trigger (دیتابیس)	یک تابع SQL که به‌صورت خودکار هنگام INSERT یا UPDATE اجرا می‌شود؛ در این پروژه version و updated را برمی‌زند و advisory lock می‌گیرد.
tombstone	یک رکورد حذف‌شدهٔ نرم (soft delete) که فیلد deleted آن مقدار دارد. در pull به کلاینت فرستاده می‌شود تا کلاینت هم آن را حذف کند.
Push	ارسالِ تغییراتِ محلیِ ذخیره‌شده در outbox به سرور (POST /api/sync/push).
Pull	دریافتِ دلتای تغییراتِ سرور از cursor به بعد (GET /api/sync/changes).
outbox	صفِ محلیِ تغییراتِ هنوز-send‌نشده؛ هر نوشتنِ محلی یک ردیف در آن می‌گذارد و push بعدی آن را می‌فرستد.
local mutation	تراکنشِ اتمیکِ «به‌روزرسانیِ ردیف محلی + درج در outbox»؛ یا کامل انجام می‌شود یا هیچ.
bootstrap	اولین pull کامل: کلاینتِ بدون cursor با cursorReset: true کلِ snapshot را می‌گیرد و بعد outbox را می‌فرستد.
sync engine (موتور همگام‌سازی)	حلقهٔ سمتِ کلاینت که push و pull را اجرا و تعارض‌ها را به کاربر نشان می‌دهد؛ در اپ وب src/lib/sync/syncEngine.ts.
sync state	حالتِ کلاینت دربارهٔ همگام‌سازی: آخرین cursor، version هر ردیف و صفِ outbox.
conflict (تعارض)	وضعیتی که baseVersion کلاینت با version فعلیِ سرور نمی‌خواند؛ نتیجه‌اش per-item ‏status: "conflict" و یک ردیف SyncConflict است — نه شکستِ درخواست.
SyncConflict	جدولی که loser snapshot هر تعارض در آن ذخیره می‌شود تا کاربر بتواند آن را restore یا dismiss کند.
loser snapshot	وضعیتِ جای‌گذاشته‌شده در هر تعارض که برای تصمیمِ بعدیِ کاربر ذخیره می‌شود.
winner (برنده)	وضعیتی که پس از تعارض روی ردیف می‌ماند: در تعارضِ stale، نوشتهٔ جدید؛ در ویرایشِ بعد از حذف، tombstone.
LWW (Last-Writer-Wins)	در push، نوشتنِ تازه‌ترِ رسیده به سرور اعمال می‌شود و وضعیتِ جای‌گذاشته‌شدهٔ سرور به‌عنوان loser snapshot در SyncConflict ذخیره می‌شود (استثنا: ویرایشِ بعد از حذف — tombstone برنده است).

داده و دیتابیس

اصطلاح	تعریف
Prisma	ORM TypeScript که با کد TypeScript با دیتابیس صحبت می‌کند؛ schema، migration و query را مدیریت می‌کند.
PostgreSQL	سیستم مدیریت دیتابیس رابطه‌ای (RDBMS) متن‌باز که بک‌اند از آن استفاده می‌کند.
schema	تعریف ساختار داده‌ها (جداول، ستون‌ها، روابط). در prisma/schema.prisma.
Migration	یک فایل SQL که ساختار دیتابیس را تغییر می‌دهد (مثل اضافه‌کردن ستون یا جدول). ترتیب migrations تضمین می‌کند دیتابیس همیشه همگام با کد است.
Zod	کتابخانه TypeScript برای تعریف schema‌های اعتبارسنجی؛ در packages/contracts برای تعریف تمام DTO‌ها و تولید OpenAPI به‌کار می‌رود.

رویداد و تقویم

اصطلاح	تعریف
RRULE	رشتهٔ استاندارد برای تعریف تکرارِ رویداد (مثلاً FREQ=WEEKLY;BYDAY=MO,WE,FR). مطابق RFC 5545.
iCal	فرمت استاندارد تقویم (RFC 5545) که هر رویداد به‌صورت یک VEVENT در آن توصیف می‌شود.
RFC 5545	استاندارد اینترنت برای تبادل دادهٔ تقویم (iCalendar).
source / sourceId	فیلدهایی که منشأ یک رویداد را مشخص می‌کنند (LOCAL, GOOGLE, ANDROID_PROVIDER, SERVER) و شناسهٔ خارجی آن را ذخیره می‌کنند.
ARGB	مدل رنگ (Alpha-Red-Green-Blue) که رنگ تقویم‌ها و رویدادها به‌صورت عدد صحیح در آن ذخیره می‌شود.
Jalali / Gregorian	نوع تقویم: جلالی (هجری شمسی) یا میلادی.

ابزارها و زیرساخت

اصطلاح	تعریف
Docker / Container	فناوری مجازی‌سازی سبک که هر سرویس را در یک محیط ایزوله اجرا می‌کند.
Docker Compose	ابزاری که چندین container را با یک فایل (docker-compose.yml) تعریف و مدیریت می‌کند.
Caddy	وب‌سرور و reverse proxy که TLS خودکار (Let's Encrypt) می‌گیرد و ترافیک را به container‌ها هدایت می‌کند.
Reverse proxy	سروری که درخواست‌های ورودی را بر اساس دامنه به سرویس پشتیبان (backend) مناسب هدایت می‌کند.
TLS (Transport Layer Security)	پروتکل رمزنگاری که ارتباط HTTPS را امن می‌کند.
OpenAPI	استانداردی برای توصیف API (مسیرها، schema‌ها، پارامترها). فایل openapi.json این پروژه از روی Zod تولید می‌شود.
Swagger UI	رابط تعاملی وب برای مرور و امتحانِ endpoint‌ها از روی specِ OpenAPI (/api-docs).
Redoc	رابط دیگر برای نمایش زیبا و خوانای specِ OpenAPI (در /api/).
Vite	ابزار build سریع برای فرانت‌اند که اپ وب از آن استفاده می‌کند.
TanStack Query	کتابخانه React برای fetch و cache از state سمت سرور (در اپ وب، عمدتاً برای auth).
monorepo	ساختاری که چند پروژه (API، وب، contracts) را در یک مخزن نگه می‌دارد.
workspace (npm)	قابلیت npm برای مدیریت پکیج‌های محلی در یک monorepo؛ packages/contracts با آن مدیریت می‌شود.
feature-sliced	الگوی معماری فرانت‌اند که هر دامنه (auth، events، …) را در یک slice مستقل با api/hooks/mappers خودش نگه می‌دارد.
env / .env	فایل پیکربندی محلی که متغیرهای محیطی (رمزها، URL‌ها، کلیدها) را نگه می‌دارد و در git track نمی‌شود.