> 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/2.x/ar/dlyl-almtwr/developer-guide/backend/resource-system.md).

# Resource System

نظام الموارد هو أحد أهم المفاهيم المعمارية في Chamilo 2.0. يوفر تجريداً موحداً لجميع محتويات الدورة — الوثائق، والتمارين، ومسارات التعلم، ومنشورات المنتدى، وغيرها.

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

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

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

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

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

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

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

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

تستخدم الشجرة استراتيجية **materialized path** الخاصة بـGedmo للاستعلامات الهرمية الفعالة.

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

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

| Field          | Type    | Description         |
| -------------- | ------- | ------------------- |
| `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 مزيج هذه الأنواع الثلاثة من السياقات ويحدد رؤية لهذا السياق الكامل:

| Field        | Type    | Description                    |
| ------------ | ------- | ------------------------------ |
| `course`     | Course  | الدورة التي ينتمي إليها المورد |
| `session`    | Session | الجلسة (null للدورة الأساسية)  |
| `group`      | CGroup  | المجموعة (null للدورة بأكملها) |
| `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. **التحكم في الرؤية** — إنشاء/تعديل ResourceLinks
5. **بناء الشجرات** — استخدام علاقة الأب-الابن في ResourceNode لهياكل المجلدات (مثل: مجلدات الوثائق)