التجميع الذكي
يُجيب التجميع الذكي على سؤال تعليمي عملي: أي الطلاب في هذا الفصل يمكن تدريسهم
معًا الآن؟ تُجمِّع وحدة modules/cluster الطلابَ القابلين للتفعيل في الفصل
في مجموعات استنادًا إلى تطابق 5 مفاتيح، وتستثني استثناءً صارمًا قسمَين
لأغراض السلامة، وتتيح للمعلم تفعيل مجموعة كاملة بخطوة تأكيد واحدة.
التقسيم: ثلاث مجموعات، تمريرة واحدة
كل إعادة احتساب تقوم بتمريرة حتمية واحدة على قائمة الفصل. كل طالب يقع في واحدة بالضبط من ثلاث مجموعات، بدون تداخل:
| المجموعة | المُحفِّز | ما يحدث |
|---|---|---|
individualReview | الطالب لديه تنبيه acute_regression مفتوح (SCS_03) | لا يُجمَّع أبدًا، لا يُفعَّل جماعيًا أبدًا |
moreDataNeeded | الطالب في حالة DATA_INCOMPLETE أو do_not_decide_yet أو بلا توصية (SCS_02) | لا يُجمَّع أبدًا، لا يُفعَّل جماعيًا أبدًا |
| قابل للتجميع | الباقون جميعًا | يُجمَّعون وفق تطابق الـ 5 مفاتيح |
القسمان المستثنيان (acute_regression وDATA_INCOMPLETE)
هما استثناءان صارمان بلا تجاوز. طلب تفعيل جماعي يُسمِّي طالبًا مستثنى
يُعيد 422 EXCLUDED_MEMBER ولا يُنشئ أي تعيينات (كل شيء أو لا شيء).
هذا تصميم سلامة مقصود: هؤلاء الطلاب يحتاجون انتباهًا فرديًا، لا تعيينًا جماعيًا.
هوية المجموعة: المفاتيح الـ 5
يُجمَّع الطلاب القابلون للتجميع في مجموعات هويتها سلسلة clusterKey كانونية
تتشكَّل من خمسة أبعاد:
bundle_id: الحزمة الموصى بهاanchor_skill_group: مجموعة مهارة المحور الأساسية ضمن تلك الحزمةscaffold_tier: مستوى السقالة المُحلَّل (مع دمجMERGE_L1_L2الاختياري لأوضاع التسليم بقيادة المعلم، وفق SCS_04)compatible_delivery_mode: وضع التسليم المشترك بين أعضاء المجموعةsufficient_data: ما إذا كان لدى جميع الأعضاء أدلة كافية (طلاب DATA_INCOMPLETE مستثنَون مسبقًا، لذا هذا صحيح دائمًا للصفوف القابلة للتجميع)
نفس قيم الـ 5 مفاتيح + نفس إصدار smart_cluster_rule_set المثبَّت = عضوية
متطابقة في كل مرة. هذه الحتمية (V-6) هي ما يجعل إعادة الاحتساب متكافئة:
تشغيلها مرتين على التوالي يُنتج نفس المجموعات.
المجموعة تُعنوَن بـ clusterKey. المفتاح الأساسي الغامض في قاعدة البيانات
لا يُستخدم في عمليات التفعيل الجماعي أو المعاينة.
بوابة الحجم الأدنى
مجموعة بأعضاء أقل من الحجم الأدنى (الافتراضي: 2؛ قابل للتكوين لكل مدرسة
بين 3-5) تُسقَط ولا تظهر كمجموعة من عضو واحد. الطلاب الذين تقع
حزمة/مستوى السقالة الخاصة بهم دون الحجم الأدنى يُسقَطون بصمت من مخرجات التجميع
ولا يظهرون في moreDataNeeded أو individualReview. يمكن للمعلم تفعيلهم
فرديًا عبر مسار تفعيل الحزمة القياسي.
التفعيل الجماعي
عندما يؤكد المعلم مجموعة، يُنشئ POST /api/cluster/bulk-activate تعيين
bundle_assignment واحد لكل عضو مؤكَّد. التنفيذ يُعيد استخدام **نفس مسار
الكتابة الفردي كتفعيل الحزمة الفردي. لم يُنشأ كاتب ثانٍ للمجموعات.
يتحقق فحص CI lint:bundle-assignment-single-write-path من هذا في كل بناء.
يتطلب جسم الطلب confirmedMemberStudentIds. يجب على المعلم ذكر معرِّفات
الطلاب الذين ينوي تفعيلهم صراحةً. هذا هو مبدأ V-12 “المعلم يقرر” مُشفَّرًا
على مستوى API.
حارس التقادم
بين لحظة معاينة المعلم للمجموعة ولحظة إرسال التفعيل الجماعي، قد تكون
المجموعة تبدَّلت (حصل طالب على توصية جديدة، فُتح تنبيه انحدار حاد، إلخ).
يُعيد التفعيل الجماعي التحقق من العضوية في مقابل احتساب جديد داخل
معاملة التفعيل. أي تعارض في أي اتجاه يُعيد 409 CLUSTER_STALE ولا تُنشأ
تعيينات. يُعاد إرجاع 409 أيضًا إذا تغيَّر وضع التسليم الخاص بالمجموعة منذ
المعاينة (على سبيل المثال، عند تغيُّر القائمة الدراسية أو قواعد أولويات التسليم).
يُعيد المعلم إجراء الاحتساب للحصول على معاينة جديدة ثم يؤكد من جديد.
تعديلات لكل عضو عند التفعيل
حقل memberAdjustments مقبول في مخطط الطلب لكنه غير مُطبَّق بعد؛
إرسال أي قائمة غير فارغة يُعيد 422 MEMBER_ADJUSTMENTS_NOT_SUPPORTED.
لتطبيق تجاوزات لكل عضو (مستوى السقالة، التسليم، الجدول)، فعِّل الطالب
فرديًا عبر سير عمل تفعيل المعلم بعد التفعيل الجماعي.
إعادة الاحتساب: عند الطلب والليلية
POST /api/cluster/recompute/{classId} هي الدالة المتكافئة التي تحتسب أو
تُحدِّث المجموعات لفصل. يمكن استدعاؤها عند الطلب من قبل معلم (يحتاج
VIEW_OWN_CLASSES) أو مشرف (يحتاج RUN_BACKOFFICE)، وهي نفس الدالة
التي يستدعيها جدولة ليلية لكل فصل نشط. تشغيلها مرات متعددة يُنتج
نفس النتيجة للمدخلات نفسها.
كل إعادة احتساب تكتب جيلًا جديدًا (إضافة فقط)، والأجيال السابقة
لا تُعدَّل أبدًا. تنتهي صلاحيتها عند createdAt + 60 يومًا.
معاينة توزيع السقالة
GET /api/cluster/student/{id}/preview يُعيد معاينة توزيع السقالة
لطالب محدد: تعيين مجموعته الحالية بالإضافة إلى تفصيل المستوى لكل
مهارة × نوع مهمة عبر جميع الحزم. هذا هو مصدر البيانات للوحة توزيع
السقالة الموجَّهة للمعلم.
توزيع المستوى (أعداد Level_1/2/3) للمعلم/المشرف فقط. لا ترى
الواجهة الموجَّهة للطالب ملصقات المستوى أو هوية المجموعة أبدًا.
نقاط النهاية الرئيسية
| نقطة النهاية | الطريقة | الصلاحية | الغرض |
|---|---|---|---|
/api/cluster/recompute/{classId} | POST | معلم / مشرف | إعادة الاحتساب عند الطلب؛ يُعيد المجموعات وقائمتَي الاستثناء |
/api/cluster/student/{id}/preview | GET | معلم / مشرف | معاينة توزيع السقالة لطالب واحد |
/api/cluster/bulk-activate | POST | معلم | تفعيل جماعي لمجموعة مؤكَّدة |
الارتباطات
- المدخل: حزم التدخل: صف
bundle_recommendationومستوى السقالة لكل طالب هما مدخلا تجميع المجموعات. - السلامة: مراقبة التقدم: دورة حياة
تنبيه الانحدار الحاد التي تُنتجها مراقبة التقدم هي ما يُغذِّي قائمة
استثناء
individualReview. - سير العمل: سير عمل تفعيل المعلم: خطوتا لوحة التجميع الذكي وتأكيد التفعيل الجماعي في سير العمل المكوَّن من 17 خطوة تتوافقان مع نقطتَي نهاية إعادة الاحتساب والتفعيل الجماعي.
- المفاهيم: تصميم التدخل: كيف تتناسب الحزم ومستويات السقالة والمجموعات الذكية مع نموذج تصميم التدخل الأشمل.