---
title: "بنك الأسئلة وخط الاستيراد"
url: https://docs.growamal.com/ar/guides/item-bank-and-import-pipeline/
language: ar
---

# بنك الأسئلة وخط الاستيراد

يُعدّ بنك الأسئلة (`modules/items`، WP-01) المصدرَ الوحيد للحقيقة لجميع المحتوى في
أمل. تُؤلَّف الأسئلة وتُتحقَّق منها **دون اتصال بالشبكة**، ثم تُستورَد عبر خط معتمَد
ومُدقَّق. لا تُولِّد المنصة محتوى الأسئلة ولا تُركِّبه ولا تُحوِّله في وقت التشغيل.

جميع مسارات هذه الوحدة محمية بصلاحية `RUN_BACKOFFICE`. يتلقّى الطلاب الأسئلة فقط عبر
خدمة [تسليم المهام](https://docs.growamal.com/ar/guides/task-delivery/)، التي تعمل بنقطة نهاية ذات نطاق خاص.

## دورة حياة السؤال

ينتقل كل سؤال عبر دورة حياة ذات أربع حالات. تُتحقَّق انتقالات الحالة وتُسجَّل؛
أي تصحيح على سؤال عملياتي يُضاف دائمًا كصف جديد ولا يُعدَّل في مكانه (قاعدة
الإلحاق فقط، V-6).

```
draft → pilot → operational
                    ↓
                 retired
```

| الحالة | المعنى |
|---|---|
| `draft` | مستورَد حديثًا؛ في انتظار مراجعة خبير المادة |
| `pilot` | معتمَد للاستخدام التجريبي المحدود؛ يجمع بيانات استجابة حقيقية |
| `operational` | معتمَد بالكامل؛ متاح لتسليم الجلسات المباشرة |
| `retired` | مُستبعَد من الاختيار النشط؛ يُحفَظ الصف لأغراض التدقيق |

> **تنبيه:** الأسئلة الاصطناعية (ذات `source=synthetic`) مُستبعَدة نهائيًا من القراءات خارج الخلفية
> الإدارية. لا يمكن ترقيتها إلى حالة `operational`. تتضمّن الاستجابة `409` على نقطة نهاية
> الترقية سببًا صريحًا للرفض.

## دفعة الاستيراد

`POST /api/items/import` هو مسار الكتابة الوحيد المدقَّق لجميع الأسئلة الجديدة. يحمل
جسم الطلب بيانات تعريف الدفعة (المصدر، واللغة، واللهجة، وتسمية الدفعة). تُرسَل صفوف
الأسئلة الفعلية كحمولة JSON منظَّمة يتحقّق منها الخادم قبل كتابة أي شيء.

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

| خطوة التحقق | ما تفحصه |
|---|---|
| المخطط | الحقول المطلوبة، والأنواع، وقيم التعداد |
| قواعد بنية نوع السؤال | عدد المُشتِّتات، وعدد الخيارات، وقواعد التنسيق للـ `item_type` المُعلَن |
| توافق المُشتِّت | يجب أن يكون `distractorType` المُعلَن مقبولًا لنوع السؤال (مصفوفة التوافق في `GET /api/item-types/{code}/distractor-compat`) |
| سلامة اللغة | يُفحَص محتوى السؤال مقابل مجموعة قواعد سلامة اللغة؛ أي تطابق لجزء نصي يتسبّب في رفض الصف |
| التوافق النحوي العربي | التوافق في الجنس والعدد والإعراب بين الجذع والخيارات والمُشتِّتات (فحص معالجة لغة طبيعية دون اتصال عبر المُتحقِّق العربي) |
| حساب `delta_prior` | تُحسَب قيمة الصعوبة المسبقة المكوَّنة من خمسة عناصر وتُخزَّن؛ الصفوف التي لا تتوفّر لها بيانات مستوى SAMER تحصل على علامة تجاوز `samer_unavailable` ويمكن استيرادها بمستوى ثقة أقل |

الدفعة آمنة التكرار على `fileHash`. إعادة إرسال الملف نفسه تُعيد تقرير الدفعة الموجود
دون كتابة صفوف مكرَّرة.

### `delta_prior`: العناصر الخمسة

قيمة الصعوبة المسبقة هي مجموع موزون لخمس إشارات من المحتوى. تأتي الأوزان من صف
`expected_difficulty_weights` النشط في قاعدة البيانات (مُعيَّر بالإصدار؛ والإصدار مُثبَّت
على كل صف سؤال لإعادة تشغيل V-6).

| العنصر | الحقل المصدر | ما يقيسه |
|---|---|---|
| **TR** (سهولة قراءة النص) | `samerTextLevel` (المقطع)؛ يرجع إلى `samerAvgLevel` (مستوى السؤال) | صعوبة المقطع على مقياس SAMER |
| **TW** (الكلمة المستهدفة) | `targetWordSamerLevel` | متوسط مستوى SAMER للكلمة أو الكلمات المستهدفة |
| **CD** (المطلب المعرفي) | `dokLevel`؛ يتجاوزه `pirlsProcess` عند توفّره | عمق المعرفة وعبء عملية الاستيعاب |
| **SC** (تعقيد الجملة) | `avgSentenceLength`، `cliticDensity` | التعقيد الصرفي والنحوي |
| **AF** (تنسيق الإجابة) | `itemType`، `distractorSimilarity`، `requiresMultipleSelection`، `optionCount` | مدى الصعوبة التي يُضيفها تنسيق الإجابة على السؤال |

توزيع الأوزان الافتراضي (صف الأوزان النشط كما يُشحَن): TR 0.35، TW 0.25، CD 0.20،
SC 0.10، AF 0.10. الأوزان قابلة للضبط في قاعدة البيانات ولا تستلزم تغيير الكود.

تُخزَّن `delta_prior` المحسوبة كـ `Decimal(7,4)` (نفس دقة θ) حتى تعيش الصعوبة والقدرة
على مقياس مقارَن وتكون إعادة تشغيل V-6 مطابقة بايت لبايت.

## أنواع الأسئلة

`GET /api/item-types` يُعيد الفهرس الكامل: 15 نوعًا نشطًا و3 رموز محجوزة.
لكل نوع:

- مجموعة قواعد بنيوية (الحقول المطلوبة، وعدد الخيارات الصحيح، وغيرها)
- قيمة `afBase` تُستخدَم أساسًا لعنصر AF في `delta_prior`
- مجموعة توافق المُشتِّتات، متاحة في `GET /api/item-types/{code}/distractor-compat`

يُهيَّأ الفهرس عند الإقلاع من `catalog-seed.ts` ولا يتغيّر في وقت التشغيل.

## الموافقة والترقية

بعد الاستيراد تهبط الأسئلة بحالة `draft`. يوجد مساران مستقلان للموافقة.

**موافقة الدفعة** (`POST /api/items/import/{batchId}/approve`) هو المسار المعتاد. يراجع
مستخدم الخلفية الإدارية المُخوَّل تقرير الدفعة وإن اقتنع بها وافق عليها. تُرقَّى جميع
الصفوف المقبولة (`accepted`) في الدفعة إلى `operational` في معاملة واحدة. تُستثنى الصفوف
ذات أسباب الرفض الفردية. نقطة النهاية آمنة التكرار: إعادة الموافقة على دفعة سبق
اعتمادها تُعيد `409`.

**موافقة خبير المادة الفردية** (`POST /api/items/{id}/sme-approve`) تُطبَّق على الأسئلة
ذات `source=sme_authored`. تُعلِّم السؤال الفردي بأنه خضع لمراجعة خبير المادة دون التأثير
في بقية دفعته.

**الترقية** (`POST /api/items/{id}/promote`) تُقدِّم سؤالًا واحدًا خطوة واحدة في دورة
الحياة (`draft → pilot → operational`). تُطبِّق نقطة النهاية بوّابة خبير المادة: لا يمكن
لسؤال `draft` تخطّي المرحلة الوسيطة والوصول إلى `operational` مباشرة دون ختم موافقة
خبير المادة.

## سحب سؤال

`POST /api/items/{id}/retire` يضبط الحالة إلى `retired`. لا يُحذَف صف السؤال أبدًا. يُستبعَد
من جميع استعلامات اختيار التسليم لكنه يظل مرئيًا في قائمة الخلفية الإدارية
(`GET /api/items`) وفي سجل `delta_prior`. يُحفَظ بهذا سجل التدقيق لأي جلسات قدَّمت
السؤال حين كان `operational`.

## سجل `delta_prior`

`GET /api/expected-difficulty/log?itemBankId=<id>` يُعيد تاريخ الحساب الكامل لسؤال واحد:
كل إعادة حساب لـ `delta_prior`، وإصدار الأوزان المستخدَم، وقيم العناصر الخمسة، والـ
`difficultyBand` الناتج. هذا هو مسار تدقيق V-6 لتغييرات قيمة الصعوبة المسبقة. استخدمه
عند التحقيق في سبب تغيّر نطاق سؤال بعد تحديث أوزان أو إعادة استيراد.

## مرجع واجهة برمجة التطبيقات

جميع المسارات تستلزم `RUN_BACKOFFICE`.

| الطريقة | المسار | ملاحظات |
|---|---|---|
| `GET` | `/api/items` | قائمة الأسئلة (مُصفَّاة، بنطاق المستأجر؛ الاصطناعية مُستثناة) |
| `GET` | `/api/items/{id}` | سؤال واحد؛ أضف `?view=authoring` للصف الكامل |
| `GET` | `/api/item-types` | الفهرس الكامل للأنواع (15 نشطًا + 3 محجوزة) |
| `GET` | `/api/item-types/{code}/distractor-compat` | مصفوفة توافق المُشتِّتات لنوع واحد |
| `POST` | `/api/items/import` | استيراد دفعة؛ آمن التكرار على `fileHash` |
| `GET` | `/api/items/import` | تاريخ الدفعات |
| `GET` | `/api/items/import/{batchId}` | تقرير التحقق لدفعة واحدة (الأعداد والنتائج لكل صف) |
| `POST` | `/api/items/import/{batchId}/approve` | موافقة دفعة خبير المادة؛ ترقّي جميع الصفوف المقبولة |
| `POST` | `/api/items/{id}/sme-approve` | موافقة خبير المادة على سؤال فردي (للأسئلة `sme_authored`) |
| `POST` | `/api/items/{id}/promote` | ترقية حالة بخطوة واحدة (`draft → pilot → operational`) |
| `POST` | `/api/items/{id}/retire` | ضبط الحالة إلى `retired` (لا يُحذَف الصف أبدًا) |
| `GET` | `/api/expected-difficulty/log` | تاريخ حساب `delta_prior` لسؤال واحد |

## ما لا يفعله خط الاستيراد

- لا يُولِّد أسئلة أو محتوى في وقت التشغيل.
- لا يستدعي نموذجًا لغويًا في أي نقطة (V-5).
- لا يقبل صامتًا الصفوف التي تفشل في التوافق النحوي العربي؛ تُرفَض مع ذكر سبب لكل صف.
- لا يسمح للأسئلة الاصطناعية بالوصول إلى حالة `operational`.

## ذات صلة

- [تسليم المهام](https://docs.growamal.com/ar/guides/task-delivery/): كيف تُختار الأسئلة العملياتية المعتمدة وتُقدَّم
- [سلامة اللغة](https://docs.growamal.com/ar/guides/language-safety/): فلتر الجزء النصي المطبَّق أثناء الاستيراد
- [دليل المعايرة](https://docs.growamal.com/ar/guides/calibration-runbook/): كيف تُنقَّح قيم `delta_prior` لاحقًا ببيانات الاستجابة الحقيقية
- [تصنيف المهارات](https://docs.growamal.com/ar/guides/skills-taxonomy/): معرِّفات المهارات الفرعية التي تُوسَم بها الأسئلة