پرسش‌های مهم
آفلاین و همگام‌سازی
بدون اینترنت می‌توانم کار کنم؟ بعد از ورود و دریافت داده، ویرایش محلی ممکن است؛ ورود اولیه به API نیاز دارد. تغییر ذخیره‌شده در دستگاه لزوماً به سرور نرسیده است. sync اندروید درون process اجرا می‌شود؛ هنگام بسته‌بودن برنامه تضمین زمان اجرا ندارد. اندروید.
اگر برنامه وسط sync بسته شود یا پاسخ گم شود؟ intent پایدار می‌ماند. برای تکرار همان عملیات، mutationId و payload قبلی را حفظ کنید؛ سرور رسید اصلی را برمی‌گرداند، نه لزوماً تازه‌ترین وضعیت رکورد. برای دیدن تغییرات جدید همچنان pull لازم است. همگام‌سازی.
HTTP 200 یعنی همهٔ تغییرات ذخیره شدند؟ نه؛ نتیجهٔ هر آیتم را با mutationId بررسی کنید. applied پذیرش، stale اختلاف نسخه، و error نیاز به اصلاح است. حتی 5xx ممکن است پس از ثبت آیتم‌های قبلی رخ دهد؛ کل batch را شکستِ بدون نوشتن فرض نکنید.
اگر هنگام ارسال دوباره ویرایش کنم، تغییر دوم چه می‌شود؟ موتور باید نیت جدید را جدا حفظ و بعد از رسید اول بازپایه کند. canonical پاسخ را مستقیم روی draft جدید ننویسید. وب و اندروید مسیرهای آمادهٔ این کار را دارند؛ از آن‌ها استفاده کنید.
چرا اطلاعات بعد از یک pull کامل نیست؟ limit برای هر نوع است و hasMore ادامهٔ صفحه‌بندی را نشان می‌دهد. cursorReset یعنی بازخوانی از ابتدا، نه پاک‌کردن outbox. صفحه و cursor را در یک تراکنش ذخیره کنید.
تعارض، حذف و وابستگی
دو دستگاه یک رکورد را ویرایش کرده‌اند؛ کدام برنده است؟ تغییر با نسخهٔ قدیمی روی سرور اعمال نمی‌شود. کار محلی را نگه دارید؛ کاربر وضعیت سرور را می‌پذیرد یا تغییر خود را با نسخه و mutation تازه می‌فرستد. پروتکل ۲ LWW نیست؛ تعارض جدید در کلاینت نگه داشته می‌شود، نه در بانک تاریخی SyncConflict.
رکورد حذف شده را با upsert برگردانم؟ نه. برای tombstone، restore صریح با نسخهٔ همان tombstone لازم است؛ والدهای لازم هم باید زنده باشند. ردیف واقعاً غایب با upsert و baseVersion=null ساخته می‌شود. این دو تصمیم را یکی نکنید.
چرا حذف والد رد می‌شود؟ has_live_dependents یعنی فرزند زنده دا رد؛ نخست فرزندان را حذف یا جابه‌جا کنید. حذف تقویم پیش‌فرض زنده با default_calendar رد می‌شود؛ پیش از حذف، تقویم دیگری را پیش‌فرض کنید. تقویم‌ها.
چرا UID تقویم پیش‌فرض عوض شد؟ سرور ممکن است تقویم پیش‌فرض محلی را به هویت پیش‌فرض حساب وصل کند. در default_identity، effectiveUid را برای رکورد، ارجاع‌های فرزند و intentهای باقی‌مانده بپذیرید؛ تکرار UID قبلی راه‌حل نیست.
فرق فیلد غایب با null چیست؟ در patch، فیلد غایب تغییر نمی‌کند؛ null فیلد nullable را پاک می‌کند. برای پیوندها از UID رکورد همان حساب استفاده کنید، نه ID داخلی DB. والد باید پیش از فرزند ارسال شده باشد. کارها و یادآورها.
ورود و حفظ کار کاربر
توکن منقضی شده یا API قطع است؛ داده را پاک کنم؟ نه. درخواست 401 می‌تواند با refresh تکرار شود؛ قطع شبکه، timeout یا 5xx خروج حساب نیست. شکست قطعی احراز هویت هم مجوز دورریختن کار محلی نیست؛ دوباره وارد شوید یا آگاهانه خروجی/دورریز را انتخاب کنید. احراز هویت.
چطور از حساب خارج شوم یا حساب را عوض کنم؟ ابتدا تغییرات و تعارض‌ها را بررسی کنید: ارسال، خروجی یا دورریزِ صریح. در اندروید، drain فقط pending/in-flight را خالی می‌کند؛ وجود تعارض یا intent شکست‌خورده را «همهٔ کار ذخیره شد» حساب نکنید—پیش از پاک‌سازی حل یا export کنید. خروج اندروید و خروج وب.
حذف دادهٔ برنامه یا IndexedDB مشکل را حل می‌کند؟ ممکن است کار ارسال‌نشده را برای همیشه حذف کند. قبل از clear، uninstall یا تعویض حساب، خروجی بگیرید. فایل خروجی ممکن است اطلاعات شخصی داشته باشد؛ در گزارش عمومی یا error-log نفرستید.
قابلیت‌ها و عیب‌یابی
یادآور ذخیره شد؛ اعلان حتماً می‌رسد؟ ذخیره و sync یادآور اثبات اجرای زمان‌بندی یا تحویل اعلان نیست. یادآورها قرارداد داده را توضیح می‌دهد؛ FCM و مجوز/اجرای سیستم‌عامل را جدا بررسی کنید.
Google Calendar، تقویم دستگاه یا فایل ICS وصل است؟ فیلد منشأ/provider به‌تنهایی اتصال اجراشده نیست؛ وضعیت اتصال خارجی را ببینید. providerId هویت sync یا جایگزین uid نیست.
| نشانه | نخست چه بررسی کنم؟ |
|---|---|
426 در push | کلاینت به‌روز و سرصفحهٔ X-Sync-Protocol: 2؛ تب قدیمی را reload کنید، ذخیرهٔ محلی را پاک نکنید |
413 | حداکثر ۱۰۰۰ آیتم در هر آرایه و اندازهٔ body حداکثر ۱MB؛ batch را کوچک‌تر کنید |
400 | پاکت و mutationIdها؛ شکل DTO در مرجع API |
unknown_parent | مالکیت/زنده‌بودن والد، ترتیب ارسال و re-key تقویم پیش‌فرض |
| sync فقط در مرورگر cross-origin شکست می‌خورد | preflight؛ allowlist فعلی CORS و سرصفحهٔ پروتکل در استقرار |
| APK debug به سرور اشتباه وصل است | host override؛ debug پیش‌فرض تولید دارد |
| ساعت/روز نمایش اشتباه است | واحد زمان، منطقهٔ زمانی و all-day در زمان‌ها |
برای گزارش خطا: نوع موجودیت، مرحلهٔ عملیات، status/reason، نسخهٔ کلاینت و بازتولید بدون اطلاعات شخصی کافی‌اند؛ token، OTP و محتوای خصوصی را نفرستید. endpoint ثبت خطا موجود است؛ وجود آن به معنی ارسال خودکار از همهٔ کلاینت‌ها نیست.