العمل دون اتصال

تستهدف Hogwarts المدارس التي يكون فيها التراجع إلى 2G/3G، والواي-فاي المتقطّع، والانقطاعات الكاملة هو القاعدة — تجارب السودان التجريبية، ومسارات النقل الريفية، وقاعات الامتحانات في الأقبية، والمتقدِّمون على بيانات الجوّال المدفوعة مسبقاً. هذه الصفحة هي الاستراتيجية على مستوى المنصّة لتقديم محرّك عمل دون اتصال بدرجة إنتاجية بأساس بلا تنازلات، ثم طبقات ميزات لكل دور على مراحل فوق هذا الأساس الصلب.

لا نُسلِّم أنصاف حلول. الأساس يُبنى مرّة واحدة ويُبنى بشكل صحيح؛ ميزات كل دور تُطبَّق فوقه على مراحل. لقيود تعدّد المستأجرين والمزامنة راجع تعدّد المستأجرين وقاعدة البيانات. لشكل الملحمة السابق الذي تتّبعه هذه الوثيقة راجع Document Intelligence. لاتفاقيات مفاتيح القاموس راجع الترجمة.

لماذا هذا مهم

تتعامل المنصّة اليوم مع فشل الشبكة بطرق متفرّقة خاصة بكل ميزة. تتراكم نقاط الألم في اللحظات الأكثر أهمية.

تخدم المنصّة اليوم ~12 ألف طالب عبر 8 مدارس نشطة؛ تستهدف تجارب السودان والمملكة دفع هذا الرقم إلى ~40 ألف خلال 12 شهراً. متوسّط شركات الجوّال في السودان 1.2 ميغابت/ثانية تنزيل مع انقطاعات متكرّرة؛ مدارس المملكة الداخلية ترى تشبّعاً في واي-فاي قاعة الامتحانات خلال الأسابيع الحرجة. محرّك عمل دون اتصال صلب هو ما يفتح الباب لكلا النشرين.

كيف يبدو النجاح

هذه هي المقاييس الرئيسية التي يلتزم بها الفريق عند "اجتياز بوّابة الأساس" + "تسليم كل ملاحم الأدوار".

1. صفر فقدان للحضور عند الانقطاع — يُسجَّل 100% من دفعات حضور المعلّمين خلال 60 ثانية من إعادة الاتصال.
2. صفر فقدان لتسليم الامتحان — تكتمل 100% من استدعاءات submitExamSession في النهاية، حتى بعد إعادة تشغيل المتصفّح.
3. تحميل دون اتصال أقل من ثانية للجدول الدراسي والإعلانات بعد الزيارة الأولى (عرض فوري من Dexie live query).
4. معدّل تثبيت PWA ≥ 35% على الهاتف للمعلّمين النشطين خلال 4 أسابيع من الإطلاق.
5. معدّل نجاح المزامنة ≥ 99.9% عبر جميع التعديلات المُطابورة (نافذة متدحرجة 7 أيام).
6. استخدام التخزين ≤ 25 ميغابايت لكل مستخدم نشط في المتوسّط (هامش حصّة Safari iOS).
7. زيادة حجم الحزمة — حزمة الأساس ≤ 35 كيلوبايت مضغوطة gzip؛ حزم كل ملحمة تُحمَّل بكسل.
8. ميزانية الخيط الرئيسي — تفريغ المزامنة لا يحجب الخيط الرئيسي > 16 مللي ثانية (العمل ينتقل إلى Web Worker).
9. إبطال الذاكرة المؤقتة من أوّل بايت — push WebSocket من الخادم يُبطل ذاكرة العميل خلال 200 مللي ثانية من الكتابة البعيدة.

مبادئ هندسية (بلا تنازلات)

هذه غير قابلة للتفاوض. كل مبدأ يُقود خيارات معمارية ملموسة.

1. المزامنة لا تحجب الخيط الرئيسي أبداً. كل إعادة التشغيل، التشفير، الضغط، فحص التعارض يعمل في Web Worker مخصّص (sync-worker.ts). الخيط الرئيسي محجوز للواجهة.
2. الكتل الكبيرة تذهب إلى OPFS، ليس IDB. المرفقات، أوراق الامتحان، الصوت المُسجَّل، الصور كلّها تستخدم Origin Private File System. IDB يحفظ فقط الحمولات المُهيكَلة وmetadata الأجزاء.
3. كل تعديل دليل-عبث. كل envelope يحمل بصمة محتوى SHA-256. يُتحقَّق من الخادم عند الاستقبال؛ يُتحقَّق من العميل عند إعادة التشغيل.
4. إبطال ذاكرة في الوقت الحقيقي. WebSocket يدفع أحداث إبطال من الخادم لكل العملاء المتّصلين. لا قِدَم صامت؛ لا انتظار refetchOnReconnect.
5. تقسيم الكود لكل ملحمة. حزمة الأساس ≤ 35 كيلوبايت. كل ملحمة دور تُسلِّم حزمتها المحمَّلة بكسل. المدارس الجديدة تُنزّل فقط الأساس؛ كود كل ميزة يُحمَّل عند أوّل استخدام.
6. القياس عن بُعد من اليوم 1. كل انتقال حالة (enqueue، flush، conflict، error، retry) يُصدر حدثاً مُهيكَلاً إلى Sentry و OfflineSyncLog. لا إعادة تطبيق لاحقة.
7. علم الميزة يُتحكَّم في الميزات الجديدة، ليس الأساس. School.offlineMode يُبدّل الميزات؛ مكتبة الأساس مُحمَّلة دائماً للـPWA المُثبَّتة. الأساس لا يمكن تبنّيه جزئياً.
8. ميزانيات الأداء بوابات CI. size-limit، Lighthouse CI، ميزانيات Sentry مخصّصة. CI يفشل عند التراجع؛ لا "نُصلحه في متابعة".
9. حلّ التعارضات صريح دائماً للمستخدم. الكتابات الفوقية الصامتة ممنوعة. كل تعديل رفضه الخادم يُظهر واجهة تعارض مُهيكَلة مع البيانات على كلا الجانبين + خيار قرار.
10. مكتبة الأساس مُصدَّرة بإصدارات. ترحيلات المخطّط بين الإصدارات مُختبَرة. لا نكسر PWA قديمة في الحقل بدون مسار ترقية موثّق.
11. شروط الاستخدام قابلة للملاحظة. useNetworkStatus، useStorageEstimate، usePendingSyncCount خطّافات عامة. أي سطح ميزة يمكنه إظهار ما يحدث للمستخدم.
12. أمان متعدّد المستأجرين معماري، ليس إجرائياً. اسم IDB DB معزول بـschoolId؛ SW يقرأ المستأجر من كوكي الجلسة وقت الطلب، ليس من global؛ التسرّب عبر المستأجرين مستحيل بحكم البناء.

قرارات معمارية للأساس

كل تنازل اعتبرناه، ولماذا رفضناه.

ما شُحن في 2026-08-29/30 — صندوق الصادر، وسياسة

أول شريحة من هذه الخطة صارت حيّة، محصورةً في دروس لوموس: صندوق صادر (src/lib/offline/outbox.ts، IndexedDB) يصفّ موضعَ المشاهدة والإكمال وإجابات الاختبار ونصّ الواجب إلى POST /api/offline/sync الذي يعمل بلا تكرار لكلّ عنصر ويردّ بحكم لكلّ عنصر؛ والمرفوضات تُركن ظاهرةً في /offline مع إعادة المحاولة أو التجاهل — فصفّ «ظهور المزامنة المعلّقة» أعلاه صار ✓ للدروس وما يزال ✗ لبقية الإجراءات. شريحة «التنزيل للمشاهدة دون اتصال» (الفيديو والمواد على الجهاز) شُحنت في 08-29 وسُحبت في 08-30 بقرار المدرسة: الفيديوهات والمواد تُشاهَد داخل التطبيق ولا تُنسخ إلى جهاز، والإصدار 2 من IndexedDB يحذف أيّ وسائط خزّنها جهاز. عامل الخدمة (public/service-worker.js، الإصدار 2) يُثبَّت فعلًا الآن.

النطاق

10 ملاحم، ~42 قصة، 231 نقطة قصّة. EPIC-0 هو الأساس الذي تعتمد عليه كل ملحمة أخرى ويجب أن يجتاز بوّابة الأساس (انظر أدناه) قبل بدء أي عمل لكل دور.

السياق المعماري

تمدّ الخطّة سقالة المرونة القائمة بدلاً من استبدالها. تطبيقان معياريان ذهبيان موجودان بالفعل في الكود — خطّاف الحفظ التلقائي للامتحان، ومتعقّب GPS لـgeofence — وتعمّم ملحمة الأساس كليهما في مكتبة قابلة لإعادة الاستخدام بدرجة إنتاجية.

حقائق المخطّط

• كل نموذج تجاري لديه schoolId مع @@index([schoolId]). كل كتابة دون اتصال يجب أن تحفظ هذا.
• KioskLog.syncedToAttendance موجود بالفعل في prisma/models/attendance.prisma:404 — يُضبَط حالياً بشكل متزامن؛ سيُعاد استخدامه كعلم مزامنة مؤجَّلة.
• نماذج جديدة مطلوبة: OfflineMutation (طابور خادم دائم)، OfflineSyncLog (ذاكرة idempotency، TTL 30 يوماً)، CacheInvalidation (سجلّ بثّ موضوع، TTL 7 أيام).
• حقل تعدادي جديد School.offlineMode: disabled / limited / full. الافتراضي limited للمدارس الجديدة، full للنشر التجريبي.
• سلاسل الترجمة تعيش في src/components/internationalization/{school-en,school-ar}.json تحت dictionary.offline.*.

الأنماط

كل ملحمة تتّبع نفس الاتفاقيات.

• Dexie DB لكل مستأجر. قاعدة Dexie واحدة لكل أصل تُسمّى hogwarts-${schoolId} مع مخطّط بإصدارات. live queries عبر useLiveQuery. الترحيلات مُختبَرة في CI.
• كتل OPFS. الملفّات > 100 KB تذهب إلى OPFS. IDB يحفظ { opfsPath, size, sha256, mimeType } فقط.
• عامل المزامنة. sync-worker.ts يُشغّل استعلامات Dexie، ضغط الحمولة، التحقّق من بصمة المحتوى، إعادة تشغيل HTTP. الخيط الرئيسي يُرسل رسائل إليه؛ العامل يبثّ التقدّم.
• مظروف تعديل من نوع discriminated. { id, schoolId, userId, action, payload, idempotencyKey, contentHash, attempts, lastError, state, createdAt } حيث action هو سلسلة حرفية تُحلّ عبر actionRegistry وقت التفريغ.
• مفاتيح idempotency. cuid v2 مولَّد من جانب العميل؛ يبقى في الحمولة؛ يفحص الخادم OfflineSyncLog قبل إعادة التطبيق.
• شظايا مزامنة لكل مجال. /api/offline/sync/{attendance|exam|transport|messaging|application} للمعالجة المتوازية. كل نقطة نهاية تُرسل إلى معالجات الإجراءات لمجالها.
• إبطال WebSocket. الخادم يبثّ رسائل cache-invalidate على الكتابات. العميل يُطابق ضدّ جداول Dexie النشطة ويُطلق تحديث live-query.
• خطّافات react رقيقة. كود الميزة يستخدم useOfflineMutation / useLiveQuery / useNetworkStatus / usePendingSyncCount / useStorageEstimate. لا يستورد dexie أو @tanstack/* مباشرة أبداً.
• التعريب أوّلاً. كل سلسلة دون اتصال تعيش في dictionary.offline.*. لا إنجليزية مدمجة في JSX أو toasts أو إرجاعات الأخطاء.
• تقسيم الكود لكل ملحمة. كود عدم الاتصال لكل ميزة يعيش في حزم بكسل. حدود import("./feature/offline.ts").

الحالة الحالية مقابل الحالة المستهدفة

سياسة حلّ التعارضات لكل إجراء

الافتراضي هو الخادم-هو-المرجع مع واجهة دمج مُهيكَلة. التجاوزات لكل إجراء أدناه.

مصفوفة توافق المتصفحات

تستهدف الاستراتيجية المتصفحات التي تستخدمها المدارس فعلياً. كشف القدرات في وقت التشغيل في useNetworkStatus و useOPFSSupport.

حيث OPFS مفقود، طبقة التخزين ترجع إلى حقول blob في IDB مع تحذير حصّة. حيث Background Sync مفقود، المزامنة تعمل على حدث online + تغيّر visibility أثناء فتح التبويب؛ عند إعادة فتح PWA، العامل يُفرّغ فوراً.

ميزانية التخزين لكل دور

مراقب navigator.storage.estimate() يُحذّر عند 80% من الاستخدام. OPFS مُضمَّن في نفس حصّة الأصل؛ نُقسِّم عمداً.

ميزانيات الأداء

هذه هي الميزانيات التي يفرضها CI.

المرحلة التمهيدية (الأسبوع 0): استكشافات وأبحاث

عشرة استكشافات تُسلَّم قبل بدء EPIC-0. كل واحد محدّد بـ0.5-1 يوم وينتج Decision Record. كلّها يجب أن تُدمَج قبل بدء EPIC-0.

القصص لكل ملحمة

الملحمة-0 — الأساس: محرّك عمل دون اتصال بدرجة إنتاجية (62 نقطة)

الأساس يُبنى مرّة، يُبنى بشكل صحيح، ويُسلَّم قبل بدء أي عمل لكل دور. خمس ملاحم فرعية، كلّها مُدمَجة قبل بوّابة الأساس (انظر أدناه).

0.A — طبقة التخزين (18 نقطة)

0.B — عامل المزامنة (18 نقطة)

0.C — أوّليات الشبكة والتعارض (12 نقطة)

0.D — service worker كمنسّق (8 نقاط)

0.E — القياس عن بُعد + devtools (6 نقاط)

تُسلِّم ملحمة الأساس محرّك العمل دون اتصال بدرجة إنتاجية الذي تستهلكه كل ملحمة دور. ملفّات جديدة تهبط تحت src/lib/offline/{db,opfs,registry,types,state-machine,compression,integrity}.ts، عامل sync-worker.ts، و src/components/offline/{hooks,provider,devtools}/. يحجب كل ملحمة أخرى حتى تمرير بوّابة الأساس.

الملحمة-1 — قابلية تثبيت PWA + تخزين هيكل التطبيق مسبقاً (15 نقطة)

تُرقّي manifest القابل للتثبيت الحالي إلى PWA حقيقي. اسم الذاكرة المؤقتة يستخدم __BUILD_ID__ للإبطال عند النشر. شريط التثبيت يظهر في الزيارة الثالثة للوحة التحكّم، التجاهل محفوظ في Dexie. تدفّق التحديث يستمع لـcontrollerchange ويطلب من المستخدم إعادة التحميل. الإطلاق المرحلي يُمكّن تحديثات SW لـ10% → 50% → 100% من الأجهزة عبر 48 ساعة.

الملحمة-2 — ذاكرة قراءة ذكية (24 نقطة)

تُعرَض الأسطح غالباً-للقراءة فورياً دون اتصال من Dexie live queries. مفاتيح الذاكرة تتّبع [schoolId, resource, id]. staleTime المُدرك للشبكة يُشتقّ من عتبات performance-optimization.ts — 5min على 4G، 30min على slow-2g. WebSocket يُبطل المُدخلات المخزّنة خلال 200 مللي ثانية من الكتابات البعيدة.

الملحمة-3 — المعلّم دون اتصال (الحضور + QR + التصحيح) (32 نقطة)

تُغلّف bulkUploadAttendance في src/components/school-dashboard/attendance/actions/bulk.ts:33 كإجراء مسجَّل. التخزين المسبق يملأ Dexie + OPFS (صور الطلاب) عندما يفتح المعلّم فصلاً. طابور QR يستبدل toast بمحاولة واحدة في qr-scanner.tsx:209. التصحيح بالسحب يُدفِّع 25 سحبة في تعديل واحد.

الملحمة-4 — الطالب دون اتصال (تسليم الامتحان + سجلّ المراقَبة) (22 نقطة)

يُغلق الفجوة الحرجة: اليوم الحفظ التلقائي يصمد لكن submitExamSession النهائي في src/components/school-dashboard/exams/take/actions.ts:369 لا يفعل. مفتاح idempotency = sessionId. الخادم يرفض التسليم عند عدم تطابق paperVersion مع واجهة تعارض مُهيكَلة. الترحيل يُسقط حوالي 120 سطراً من إعادة المحاولة/backoff المخصّصين.

الملحمة-5 — السائق دون اتصال (صعود الرحلة) (15 نقطة)

يحاكي نمط geofence المعياري الذهبي في تجربة السائق داخل التطبيق. recordBoardingFromGeofenceInternal هو بالفعل idempotent على (schoolId, tripId, studentId). التخزين المسبق يملأ Dexie + OPFS عند بدء الرحلة. القصة 5.4 تتقاعد عن صنف LocationQueue في geo-tracker.tsx:59.

الملحمة-6 — المتقدِّم دون اتصال (مرفقات قابلة للاستئناف + تسليم) (18 نقطة)

المتقدِّمون على 3G ضعيف يمكنهم استئناف رفع نسخة دراسية 5 ميغابايت — الأجزاء تعيش في OPFS. نقطة نهاية جديدة /api/uploads/resumable/[uploadId]/[partNumber] تتعقّب الأجزاء المكتملة. سياق الطلب في application-context.tsx:412 يترقّى من localStorage إلى Dexie.

الملحمة-7 — طابور المراسلة الصادرة (16 نقطة)

تُغلق فجوة المراسلة. حالات الفقاعة تتطابق مع دورة حياة XState من EPIC-0. الجسر يستقبل clientMessageId لمنع التكرار-على-الإعادة.

الملحمة-8 — قابلية المراقبة + تحليلات عدم الاتصال (14 نقطة)

تُجيب "هل يساعد عدم الاتصال المستخدمين" بأرقام صلبة. مقاييس لكل مدرسة تظهر في لوحة SaaS. لوحة SLI مكشوفة لدور ADMIN ليتمكّن كل مدرسة من المراقبة الذاتية.

الملحمة-9 — الوثائق والتعريب وإعداد المسؤول (13 نقطة)

ملحمة تسليم قائمة بذاتها. القصة 9.4 تغطّي مسارات الأدوار الأربعة عبر context.setOffline(true). مفاتيح القاموس: online، offline، slowConnection، backOnline، syncing، pendingCount، pendingDrawerTitle، retry، discard، discardConfirm، lastSynced، cached، submissionQueued، submissionInFlight، conflictTitle، conflictBody، conflictResolveKeep، conflictResolveDiscard، conflictResolveMerge، installAvailable، installCta، updateAvailable، updateCta، offlinePageTitle، offlinePageBody، dataSaver، featureUnavailableOffline، storageNearFull، storageFullError، paperVersionConflict، gradingConflict.

استراتيجية الانتقال

الانتقال من حالة اليوم إلى عمل دون اتصال بدرجة إنتاجية يحدث على ثلاث مراحل لكل ميزة. لا تبديل مفاجئ.

1. مرحلة الكتابة المزدوجة. تكتب الميزة عبر الإنترنت مباشرة وتُطابور أيضاً لإعادة التشغيل عبر الأساس الجديد. OfflineSyncLog يُزيل التكرار عبر مفتاح idempotency. اكتشف الاختلاف في القياس عن بُعد؛ نبّه على أي.
2. التحويل. بدّل الميزة إلى الطابور-أولاً. التفريغ عبر الإنترنت تلقائي وفوري. علم School.offlineMode='full' يُمكّن مسار الطابور؛ limited يبقي عبر الإنترنت فقط.
3. التنظيف. أزل إعادة المحاولة/localStorage/طابور الذاكرة المخصّص. احذف الكود الميت في use-auto-save.ts، useOfflineQueue (attendance/shared/hooks.ts:541)، LocationQueue (geo-tracker.tsx:59).

ترتيب التحويل: الحضور → تسليم الامتحان → صعود السائق → مرفقات الطلب → المراسلة. كل تحويل يعيش خلف علم الميزة ويُسلَّم بشكل مستقلّ.

متعدّد الجوانب

إضافات المخطّط

طبّق عبر بروتوكول Neon branch-before-touch.

• OfflineMutation — طابور خادم دائم: id، schoolId @@index، userId @@index، action، idempotencyKey @unique، contentHash، payload Json، status enum(PENDING|SUCCESS|FAILED|CONFLICT)، attempts، lastError، createdAt، syncedAt.
• OfflineSyncLog — ذاكرة idempotency: idempotencyKey @id، schoolId @@index، userId، action، responseJson Json، replayedAt. وظيفة TTL 30 يوماً.
• CacheInvalidation — سجلّ بثّ موضوع: id، schoolId @@index، topic، keyHash، emittedAt، propagatedAt. وظيفة TTL 7 أيام.
• School.offlineMode — حقل تعدادي disabled / limited / full. الافتراضي limited.
• KioskLog.syncedToAttendance — موجود بالفعل. أعد الاستخدام، لا تكرّر.

التحكّم في الوصول حسب الدور

• درج المزامنة المعلّقة: مرئي لجميع الأدوار المُصادَق عليها.
• إعادة المحاولة / التجاهل: محدّد لدور المالك لكل ميزة.
• بلاطة لوحة المطوّر: تجميع عبر المدارس.
• لوحة SLI لكل مدرسة: دور ADMIN.
• تبديل وضع عدم الاتصال للمسؤول: دور ADMIN فقط.
• لوحة <OfflineDevtools>: دور DEVELOPER فقط (محمي بفحص جلسة).

التعريب

30 مفتاح قاموس جديد تحت dictionary.offline.*. صفر سلاسل مدمجة في كود واجهة عدم الاتصال. السلاسل العربية يراجعها متحدّث أصلي قبل الإطلاق التجريبي.

استراتيجية الاختبار

القياس عن بُعد والمقاييس

كل انتقال حالة يُصدر حدثاً مُهيكَلاً. أسماء الأحداث تستخدم namespace offline.*.

الإطلاق التدريجي (علم الميزة)

المدارس التجريبية (السودان، الملك فهد) تختار full. SaaS Marketing يبقى على الافتراضي.

إعداد المطوّر

يضيف مساهم جديد دعم عدم الاتصال لميزته في خمس خطوات.

1. سجّل معالج إجراء جديد في src/lib/offline/registry.ts مع مخطّط حمولة Zod وسياسة تعارض.
2. استدعِ useOfflineMutation("yourFeature.actionName", payload) من العميل؛ للقراءات استخدم useLiveQuery(() => db.yourFeature.where(...).toArray()).
3. أضف دخول Storybook لواجهة التعارض إن كانت التعارضات محتملة.
4. أضف اختبار Playwright في playwright/tests/offline.spec.ts.
5. أضف مفاتيح قاموس لأي سلاسل عدم اتصال جديدة تحت dictionary.offline.<feature>.*.

مثال عمل كامل يعيش في src/components/school-dashboard/attendance/ بعد تسليم EPIC-3.

بوّابة الأساس

EPIC-0 يجب أن يجتاز كل ما يلي قبل بدء أي ملحمة دور. عمل الأساس ليس تسليماً جزئياً.

• مصنع DB Dexie لكل مستأجر + إصدارات المخطّط + اختبارات الترحيل مُدمَجة
• تجريد OPFS مع فولباك IDB مُدمَج + اختبار Safari iOS 16.4 اليدوي ناجح
• sync-worker.ts يُشغّل كل إعادة تشغيل التعديلات؛ مراقب long-task للخيط الرئيسي يُبلِّغ عن صفر حجب > 16 مللي ثانية أثناء المزامنة
• actionRegistry + دورة حياة XState مُدمَجة بتغطية ≥ 95% اختبارات وحدة
• ضغط LZ4 + MessagePack مقيس بنسبة ≥ 3× على الحمولات النموذجية
• بصمة محتوى SHA-256 تتحقّق في كل إعادة تشغيل؛ اختبار العبث يفشل مغلقاً
• كمون cache-invalidate عبر WebSocket من طرف إلى طرف ≤ 200 مللي ثانية في staging
• service worker يُفرّغ الطابور على حدث Background Sync (Chrome) وعلى إعادة فتح التبويب (iOS)
• ذرّة <ConflictResolver> مُسلَّمة مع تغطية Storybook لكل سياسة تعارض
• OfflineSyncLog يكتب من كل انتقال؛ breadcrumbs في Sentry مرئية في اللوحة
• لوحة <OfflineDevtools> تُعرَض لدور DEVELOPER وتُظهر حالة الطابور الحيّة
• حجم حزمة الأساس ≤ 35 KB مضغوطة gzip (بوّابة CI size-limit)
• اختبار Playwright لتسرّب المستأجر أخضر (طابور على school-a → تبديل إلى school-b → الطابور غير مرئي)

عمل الأساس يستمرّ حتى تُحدَّد كل المربّعات. لا ملحمة دور تبدأ قبل ذلك.

المخاطر والمقايضات

1. حصص IndexedDB + OPFS. Safari iOS يُحدّد حوالي 50 ميغابايت؛ Chrome Android يسمح حتى 60% من القرص. التخفيف: OPFS للكتل؛ حمولات فقط في IDB؛ مراقب navigator.storage.estimate() يُحذّر عند 80%؛ يُجلي ذاكرات القراءة قبل الكتابات المُطابورة.
2. تسرّب عبر المستأجرين عند تبديل النطاق الفرعي. التخفيف: اسم DB معزول بـschoolId؛ SW يقرأ schoolId من كوكي الجلسة لكل طلب؛ اختبار Playwright في بوّابة الأساس.
3. أسئلة امتحان بائتة مقابل النزاهة. التخفيف: التخزين المسبق يحفظ paperVersion؛ الخادم يرفض التسليم عند عدم التطابق مع <PaperVersionConflict> مُهيكَل.
4. تكرارات جسر واتساب. التخفيف: clientMessageId يُمرَّر إلى الجسر كمفتاح idempotency.
5. نطاق SW متعدّد النطاقات الفرعية. كل school-X.databayt.org يحصل على نطاق SW خاص (صحيح).
6. غياب Background Sync في Safari iOS. التخفيف: حدث online + مستمع visibility-change في التبويب؛ عند إعادة فتح PWA، عامل المزامنة يُفرّغ الطابور فوراً.
7. OPFS غير متاح على Safari قديم / متصفّحات داخل التطبيق. التخفيف: طبقة التخزين تكتشف القدرة عند التهيئة؛ ترجع إلى حقول blob في IDB مع تحذير تخزين.
8. صفحة عدم اتصال باردة. التخفيف: تخزين مسبق عدواني للهيكل عند التثبيت؛ صفحة عدم الاتصال مفيدة حتى في أوّل زيارة (تُظهر CTA التثبيت).
9. تقييد Background Sync. التخفيف: التفريغ الأمامي هو المسار الأساسي؛ المزامنة الخلفية بذل أفضل.
10. انحراف الوقت على التعديلات المحفوظة. التخفيف: الخادم يسجّل serverAcceptedAt كمرجع؛ markedAt العميل يبقى كـmetadata مراجعة فقط.
11. حدود اتصال WebSocket لكل أصل. التخفيف: socket واحد لكل تبويب؛ تنسيق بنمط SharedWorker عبر التبويبات لنفس الأصل.
12. إجلاء التخزين على مستوى نظام التشغيل. التخفيف: تثبيت PWA يُرقّي إلى "تخزين مُدار" بضمانات إجلاء؛ المستخدمون غير المُثبَّتين يرون toast تحذير.

الجدول الزمني التفصيلي (14 أسبوعاً، أسبوع-بأسبوع)

مطوّران، مراحل مُنسَّقة. أرقام الأسابيع تقويمية بدءاً من انطلاق المشروع.

احتياطي: أسبوع واحد محجوز لـsoak في staging قبل تمكين التجريبي.

P0 — EPIC-0، 1، 3، 4 (الأساس + المعلّم اليومي + الطالب عالي المخاطر). P1 — EPIC-2، 5، 6، 9 (ذاكرة قراءة، سائق، متقدِّم، وثائق). P2 — EPIC-7، 8 (طابور المراسلة + تحليلات).

دليل الإطلاق التجريبي

تمكين School.offlineMode='full' لمدرسة تجريبية تغيير مدروس وقابل للملاحظة. خمس خطوات.

1. ما قبل الإطلاق (T-7 أيام). تأكّد أن المدرسة على أحدث إصدار؛ فحص مسارات الإنترنت؛ خط أساس لمعدّل فشل الاتصال؛ إحاطة المسؤول.
2. تمكين ناعم (T-0). يُبدّل ADMIN offlineMode='full' في إعدادات المدرسة. service worker يُسجَّل في الزيارة التالية.
3. مراقبة اليوم 1. راقب OfflineSyncLog لأول ~50 تعديل مُطابور؛ تحقّق من نجاح كل تفريغ؛ افحص Sentry.
4. مراجعة اليوم 7. قارن المقاييس الرئيسية. إذا أي شيء تحت 95%، جذر المشكلة أو ارجع إلى limited.
5. استرجاع اليوم 30. قرّر: الإبقاء على full، الترقية إلى الافتراضي، أو التحسين.

الرجوع فوري: يضبط ADMIN offlineMode='limited'.

قائمة اختبار التحقّق السريع

فحوصات يدوية قبل إعلان "ميزة منجَزة دون اتصال". شغّل على Safari iOS 16.4، Chrome Android 110، Chrome Desktop 110 كلّ منها.

• service worker مُسجَّل (chrome://serviceworker-internals يُظهره نشطاً)
• manifest قابل للتثبيت
• هيكل التطبيق يُحمَّل مع Network: Offline بعد زيارة سابقة عبر الإنترنت
• صفحة عدم الاتصال تُعرَض مع وقت آخر مزامنة + عدد التعديلات المعلّقة + واجهة تخزين
• حضور المعلّم بالجملة: حدّد 20 طالباً دون اتصال → أعد التحميل → كلّهم مرئيون كمعلّقين → أعد الاتصال → كلّهم مُفرَّغون → لا تكرارات
• امتحان الطالب: أدخل الإجابات دون اتصال → سلّم دون اتصال → شاشة كاملة "التسليم مُطابور" → أعد الاتصال → مُسلَّم
• صعود السائق: امسح 5 طلاب في عدم اتصال محاكٍ للنفق → أعد الاتصال → كلّ الخمسة مُسجَّلون
• المتقدِّم: ارفع مرفق 5 ميغابايت، اقتل الاتصال منتصف الرفع → أعد الاتصال → الرفع يستأنف من الأجزاء المكتملة في OPFS
• المراسلة: أرسل 3 رسائل دون اتصال → الفقاعة تُظهر queued → أعد الاتصال → كلّها تُظهر sent
• تبديل النطاق الفرعي: عناصر طابور على school-a → انتقل إلى school-b → الطابور غير مرئي → عُد إلى school-a → الطابور سليم
• نافذة تثبيت PWA: زر لوحة التحكّم 3 مرّات → يظهر الشريط → قبول → يطلق كـstandalone
• تحديث SW: انشر SW جديد → يظهر toast → إعادة التحميل تكتمل
• كل الواجهة بالعربية عند ?lang=ar → السلاسل تُعرَض من اليمين إلى اليسار
• الدرج المعلّق: زرّ إعادة المحاولة يعمل؛ زرّ التجاهل يعمل؛ كلاهما يؤكّد قبل الإتلاف
• التخزين شبه ممتلئ: املأ IDB+OPFS إلى 80% → يظهر toast تحذير
• offlineMode='disabled' → لا SW مُسجَّل
• إبطال WebSocket: اكتب من جهاز أ → live query لجهاز ب يُحدَّث خلال ثانية واحدة
• واجهة التعارض: حاكِ تعارض نسخة → <ConflictResolver> يُظهر كلا الجانبين → المستخدم يختار احتفاظ/تجاهل
• مُحلّل الخيط الرئيسي لا يُظهر مهام طويلة > 16 مللي ثانية أثناء تفريغ مزامنة 50 عنصراً

معايير القبول — "عمل دون اتصال بدرجة إنتاجية مُسلَّم"

1. مع School.offlineMode='full'، معلّم على chrome://devtools network: Offline يُسجّل الحضور، يُعيد التحميل، يُغلق التبويب، يعيد الفتح — كل العلامات معلّقة؛ إعادة الاتصال تُعيد التشغيل بصفر تكرار وصفر حجب للخيط الرئيسي.
2. طالب يفقد الاتصال لـ10+ دقائق منتصف الامتحان، يستمرّ في الإجابة، يضغط تسليم، يرى "التسليم مُطابور"؛ إعادة الاتصال تكتمل خلال 30 ثانية بصفر فقدان بيانات.
3. حدث SW sync-forms يطلق عند إعادة الاتصال؛ يُفرّغ طابور Dexie دون أن تكون الصفحة مفتوحة.
4. إغلاق/إعادة فتح المتصفّح تحافظ على الطابور (Dexie، ليس في الذاكرة).
5. تبديل النطاق الفرعي school-a → school-b لا يُعيد تشغيل طابور school-a ضدّ school-b.
6. Playwright tests/offline.spec.ts أخضر عبر مسارات الأدوار الأربعة + أمان المستأجر + حلّ التعارضات.
7. كل سلاسل واجهة عدم الاتصال تُعرَض في en و ar من مفاتيح القاموس؛ صفر إنجليزية مدمجة في grep.
8. offlineMode='disabled' يُعطّل تسجيل SW كلّياً.
9. حزمة الأساس ≤ 35 KB مضغوطة gzip (بوّابة CI). حزم كل ملحمة ≤ 15 KB لكلٍّ منها.
10. القياس في Sentry يُظهر ≥ 99.9% معدّل نجاح مزامنة على نافذة متدحرجة 7 أيام عبر كل مدارس full.
11. مراقب long-task للخيط الرئيسي يُظهر صفر حجب > 16 مللي ثانية أثناء تفريغ المزامنة في قياسات p99.
12. كمون إبطال ذاكرة WebSocket p95 ≤ 200 مللي ثانية في الإنتاج.
13. استئناف مرفقات OPFS يعمل بعد قتل الرفع منتصف الطيران على iOS 16.4.

الملفّات الرئيسية

المسرد

• معالج إجراء (Action handler). إجراء خادم مسجَّل في actionRegistry بسلسلة اسم. نفس الدالة المُستدعاة عبر الإنترنت أو عبر إعادة تشغيل دون اتصال.
• هيكل التطبيق (App shell). الحدّ الأدنى من HTML و CSS و JS اللازمة لعرض كروم التنقّل. يُخزَّن مسبقاً وقت التثبيت.
• Background Sync. واجهة برمجة متصفّح تطلق حدث sync عندما يكون الجهاز متّصلاً. دعم متصفّح محدود.
• Comlink. مكتبة لـRPC مريح مع Web Worker.
• حلّ التعارض. سياسة تُطبَّق عندما لا يمكن تطبيق تعديل مُطابور بنظافة. الافتراضي خادم-مرجع مع واجهة دمج مُهيكَلة.
• بصمة محتوى (Content hash). SHA-256 لحمولة التعديل، محفوظة على envelope. يُتحقَّق منها عند الاستقبال وإعادة التشغيل. دليل عبث.
• Dexie. مكتبة غلاف فوق IndexedDB مع دلالات استعلام غنية، معاملات، live queries، إصدارات مخطّط.
• مفتاح idempotency. cuid v2 مولَّد من جانب العميل مرفق بكل تعديل. الخادم يستخدم OfflineSyncLog لإزالة التكرار.
• IDB. IndexedDB، متجر مفتاح-قيمة مفهرس أصلي للمتصفّح.
• LZ4. خوارزمية ضغط سريعة؛ مستخدمة هنا عبر WASM لضغط الحمولة > 1 KB.
• MessagePack. صيغة تسلسل ثنائية. أكثر إحكاماً من JSON لترميز envelope.
• مظروف التعديل. الغلاف المكتوب حول كتابة مُطابورة. يحمل metadata لإعادة التشغيل بما في ذلك مفتاح idempotency وبصمة المحتوى.
• Network Information API. navigator.connection.effectiveType / saveData / rtt. مستخدم لتكييف الواجهة مع جودة الاتصال.
• OPFS. Origin Private File System. نظام ملفّات أصلي للمتصفّح محدود بالأصل؛ أفضل من IDB للكتل الكبيرة.
• PWA. تطبيق ويب تقدّمي. تطبيق ويب قابل للتثبيت مع قدرة دون اتصال.
• التخزين المسبق. تخزين الأصول أو البيانات قبل أن يحتاج إليها المستخدم دون اتصال.
• استقبال المزامنة. POST /api/offline/sync/{domain}، نقاط النهاية لكل مجال التي تستقبل التعديلات المُطابورة.
• عامل المزامنة. sync-worker.ts، Web Worker الذي يُعالج كل إعادة تشغيل دون اتصال خارج الخيط الرئيسي.
• معزول لكل مستأجر. تخزين مفهرس بـschoolId بحيث لا تتسرّب البيانات عبر المدارس.
• XState. مكتبة لنمذجة آلة الحالة المنتهية. مستخدمة لدورة حياة التعديل.

انظر أيضاً

• تعدّد المستأجرين — قواعد تحديد نطاق schoolId التي يجب أن تحترمها كل كتابة دون اتصال
• قاعدة البيانات — بروتوكول أمان Prisma + Neon للجداول الجديدة
• Notifications — أنماط ذاكرة جانب القراءة تشارك البنية التحتية
• الترجمة — اتفاقيات مفاتيح القاموس لسلاسل عدم الاتصال
• Document Intelligence — قالب وثيقة الملحمة السابق الذي تتّبعه هذه الوثيقة
• البنية المعمارية — نمط المرآة وحلّ سياق المستأجر
• MVP — اتفاقيات شارات النضج لتتبّع تقدّم الملحمة
• خارطة الطريق — نظرة ربعية لإطلاق عدم الاتصال