> For the complete documentation index, see [llms.txt](https://docs.chamilo.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chamilo.org/3.x/ar/dlyl-almtw-r/developer-guide/backend/resource-system.md).

# نظام الموارد

يُعد نظام الموارد أحد أهم المفاهيم المعمارية في Chamilo 3.0. فهو يوفّر تجريدًا موحّدًا لكل محتوى المقرر — المستندات، والتمارين، ومسارات التعلّم، ومنشورات المنتدى، وغيرها.

## المفهوم الأساسي

تُمثَّل كل قطعة من محتوى المقرر بواسطة **ResourceNode**. وهذا يمنح جميع أنواع المحتوى مجموعة مشتركة من القدرات:

* **التحكم في الظهور** — إظهار/إخفاء المحتوى عن المتعلمين
* **التحكم في الوصول** — تتحقق مُقيِّمات الأمان من الصلاحيات عبر ResourceNode
* **تخزين الملفات** — تُخزَّن الملفات المرفقة عبر ResourceFile
* **البنية الشجرية** — تشكّل كيانات ResourceNode شجرة (علاقات أب-ابن)
* **سجل التدقيق** — المنشئ، وتاريخ الإنشاء، وتتبع التعديلات

## الكيانات الرئيسية

### ResourceNode (`src/CoreBundle/Entity/ResourceNode.php`)

الكيان المركزي. لكل كيان محتوى علاقة واحد-إلى-واحد مع ResourceNode.

الحقول الرئيسية:

| الحقل           | النوع        | الوصف                                 |
| --------------- | ------------ | ------------------------------------- |
| `id`            | integer      | المفتاح الأساسي                       |
| `uuid`          | UUID v4      | معرّف فريد للاستخدام في واجهة البرمجة |
| `title`         | string       | عنوان العرض                           |
| `creator`       | User         | المستخدم الذي أنشأ هذا المورد         |
| `resourceFile`  | ResourceFile | الملف المرفق (إن وُجد)                |
| `resourceType`  | ResourceType | نوع المورد (مستند، اختبار، إلخ)       |
| `parent`        | ResourceNode | الأب في شجرة الموارد                  |
| `children`      | Collection   | كيانات ResourceNode الفرعية           |
| `resourceLinks` | Collection   | روابط الظهور والوصول                  |

تستخدم الشجرة استراتيجية **المسار المادي** (materialized path) من Gedmo للاستعلامات الهرمية الفعّالة.

### ResourceFile (`src/CoreBundle/Entity/ResourceFile.php`)

يخزّن بيانات الملف الفعلية للمورد:

| الحقل          | النوع   | الوصف               |
| -------------- | ------- | ------------------- |
| `id`           | integer | المفتاح الأساسي     |
| `title`        | string  | اسم الملف الأصلي    |
| `mimeType`     | string  | نوع MIME            |
| `originalName` | string  | اسم الرفع الأصلي    |
| `size`         | integer | حجم الملف بالبايت   |
| `crop`         | string  | بيانات القص (للصور) |

يُدار تخزين الملفات بواسطة Flysystem، لذا يمكن أن تكون الملفات على القرص المحلي، أو S3، أو Azure، أو GCS حسب الإعدادات.

### ResourceLink

يتحكم في الظهور والوصول حسب السياق. هناك 3 أنواع سياقات رئيسية:

1. المقرر (Course)
2. الجلسة (Session)
3. المجموعة (Group) (ضمن مقرر)

لذا يعكس كيان ResourceLink تركيبة أنواع السياقات الثلاثة هذه ويحدّد ظهورًا لذلك السياق الكامل:

| الحقل        | النوع   | الوصف                               |
| ------------ | ------- | ----------------------------------- |
| `course`     | Course  | المقرر الذي ينتمي إليه المورد       |
| `session`    | Session | الجلسة (قيمة فارغة للمقرر الأساسي)  |
| `group`      | CGroup  | المجموعة (قيمة فارغة للمقرر بأكمله) |
| `visibility` | integer | ظاهر، أو مخفي، أو محذوف             |

يتيح ذلك أن يكون لنفس ResourceNode ظهور مختلف في سياقات مختلفة (مثلًا ظاهر في جلسة ومخفي في أخرى).

يُضبط هذا تلقائيًا عند استخدام الواجهة واتخاذ قرار، على سبيل المثال، بأن المورد خاص بجلسة معيّنة سيكون ظاهرًا لجميع المجموعات في مقرر معيّن في جلسة معيّنة، لكنه مخفي في المقرر الأساسي أو في جلسة أخرى.

افتراضيًا، تكون الموارد الظاهرة في المقرر الأساسي ظاهرة أيضًا في جميع جلسات ذلك المقرر، لكن يمكن لمدرّس المقرر أن يقرر إخفاء مورد من جلسة معيّنة. في هذه الحالة، نسترجع الظهور الخاص بهذا المورد في هذه الجلسة ونرى أن قيمته 0، فلا يظهر العنصر للمتعلمين في هذه الجلسة، بينما غياب ظهور خاص بالجلسة في الجلسات الأخرى يجعل المورد يستخدم ظهور المقرر الأساسي (فيظهر المورد للمتعلمين).

## التكامل مع API Platform

يُعرَض ResourceNode كمورد في API Platform مع الأمان:

```php
#[ApiResource(
    operations: [
        new Get(security: "is_granted('VIEW', object)"),
        new Put(security: "is_granted('EDIT', object)"),
        new Delete(security: "is_granted('DELETE', object)"),
        new GetCollection(security: "is_granted('ROLE_USER')"),
    ]
)]
```

## كيف ترتبط كيانات المحتوى

كيانات محتوى المقرر (CDocument، CQuiz، CLp، إلخ) توسّع `AbstractResource` أو تنفّذ `ResourceInterface`، مما يمنحها علاقة `resourceNode`:

```php
// In CDocument entity:
#[ORM\OneToOne(targetEntity: ResourceNode::class)]
private ResourceNode $resourceNode;
```

عند إنشاء CDocument، يُنشأ ResourceNode تلقائيًا معه، مما يوفّر إدارة موحّدة للموارد.

## الآثار العملية

عند العمل مع محتوى المقرر:

1. **إنشاء المحتوى** — أنشئ كيان المحتوى وResourceNode الخاص به معًا
2. **التحقق من الصلاحيات** — استخدم مُقيِّمات الأمان الخاصة بـ ResourceNode
3. **إدارة الملفات** — أرفق الملفات عبر ResourceFile
4. **التحكم في الظهور** — أنشئ/عدّل كيانات ResourceLink
5. **بناء الأشجار** — استخدم علاقة الأب-الابن على ResourceNode لهياكل المجلدات (مثل مجلدات المستندات)