---
title: 'قاعدة البيانات ولوحة الإدارة'
description: 'احفظ مجموعة التوثيق في قاعدة بيانات تطبيقك، خلف ذاكرة مؤقتة دائمة في كل الأحوال، مع مراجعة (revision) لكل تغيير ولوحة إدارة تديرها منها.'
url: 'https://larecipe.saleem.dev/ar/3.x/sources/database'
version: 3.x
locale: ar
last_updated: '2026-10-18'
---

> Docs index: https://larecipe.saleem.dev/3.x/llms.txt · MCP: https://larecipe.saleem.dev/mcp · Skill: https://larecipe.saleem.dev/skill.md

# قاعدة البيانات ولوحة الإدارة

يحفظ مصدر قاعدة البيانات صفحات مجموعة التوثيق وتنقّلها وملف تعريفها في قاعدة بيانات تطبيقك بدلًا من الملفات. اختره حين يدير التوثيقَ من لوحة إدارة أشخاصٌ لا يعملون في المستودع، أو حين تولّد الصفحات من بيانات، أو حين يجب أن يبقى محتوى التوثيق خارج المستودع. تبدأ معظم الفرق بـ [مصدر المستودع](https://larecipe.saleem.dev/ar/3.x/sources/repository.md)، ويمكنك [التبديل](https://larecipe.saleem.dev/ar/3.x/sources/switching.md) في أي وقت: فكلاهما يحتفظ بالصيغة نفسها.

وجّه مصدر المجموعة إلى قاعدة البيانات:

```php title="config/larecipe.php"
'sets' => [
    'handbook' => [
        'route' => ['prefix' => 'handbook'],
        'source' => [
            'driver' => 'database',
            'cache' => 'redis',
        ],
        'access' => ['mode' => 'auth'],
    ],
],
```

ثم أنشئ الجداول، وامنح المجموعة مخزن ذاكرة مؤقتة دائمًا (`redis` أو `database` أو `file` أو `memcached`):

```bash
php artisan migrate
```

املأها [بنقل مجموعة موجودة](https://larecipe.saleem.dev/ar/3.x/sources/switching.md)، أو من [لوحة الإدارة](https://larecipe.saleem.dev/ar/3.x/sources/database#the-admin-ui)، أو بأن تدع وكيل البرمجة يكتب الصفحات عبر أدوات التأليف في خادم MCP المحلي. ويستطيع تطبيق جديد أن يبدأ من هنا بالأمر `php artisan larecipe:install --driver=database`، الذي يكتب أيضًا [ترحيل توثيق](https://larecipe.saleem.dev/ar/3.x/sources/docs-migrations.md) أوليًا فيه صفحة مقدمة.

**كل مفاتيح المصدر**

| المفتاح | يتحكّم في |
| --- | --- |
| `source.connection` | اتصال قاعدة البيانات. القيمة `null` تستخدم الاتصال الافتراضي. |
| `source.cache` | مخزن الذاكرة المؤقتة الذي تعمل المجموعة خلفه. ومن دونه يُستخدم `larecipe.cache.store`، ثم المخزن الافتراضي لديك. |
| `source.disk` | قرص نظام الملفات للملفات المرفقة. القيمة `null` تستخدم القرص الافتراضي. |

حين تستخدم أي مجموعة مشغّل قاعدة البيانات، يحمّل LaRecipe ترحيل جداوله من الحزمة، مع مجلد ترحيلات التوثيق. ولتغيّر الجداول، انشر الترحيل أولًا بالأمر `php artisan vendor:publish --tag=larecipe-migrations`؛ فما إن يوجد ملف `*_create_larecipe_tables.php` في `database/migrations` حتى تتوقف نسخة الحزمة عن التحميل.

## كيف تصبح التغييرات حية

كل تغيير في مجموعة قاعدة البيانات مراجعة (revision)، مع من أجراه ومن أين جاء. وكونه يصبح حيًا فورًا أم لا يعتمد على مصدره:

| جاء التغيير من | يصبح حيًا |
| --- | --- |
| ترحيل توثيق، يطبّقه `php artisan migrate` عند النشر | فورًا: فالـ pull request كان هو المراجعة. |
| جلسة MCP المحلية لوكيل البرمجة | فورًا في قاعدة بياناتك المحلية، ويُكتب في [ترحيل التوثيق](https://larecipe.saleem.dev/ar/3.x/sources/docs-migrations.md) الخاص بالفرع. |
| شخص في لوحة الإدارة | فورًا، ما لم يحفظه مسودة. |
| وكيل عبر أدوات التأليف في MCP على الويب، خارج أي pull request | مسودةً مع `review: required`، وفورًا مع `review: auto`. |

يُتحقق مما يكتبه كل كاتب (الصفحة التي فيها أخطاء تُرفض، ولا يُكتب شيء)، ولا يستطيع أي كاتب أبدًا أن يكتب بصمت فوق تعديل أحدث. ولا يضيع شيء: التراجع يستعيد مراجعة سابقة بوصفها مراجعة جديدة، والصفحة المحذوفة يمكن استعادتها. راجع [أوضاع المراجعة](https://larecipe.saleem.dev/ar/3.x/keeping-current/review-modes.md).

**المراجعات والتعارضات والأحداث**

يستطيع الكاتب أن يذكر نسخة الصفحة التي قرأها (بصمة محتواها). فإن تغيّرت الصفحة منذ ذلك الحين، تُرفض الكتابة ويُطلب من الكاتب أن يقرأها من جديد. أما ترحيل التوثيق فيحتفظ بنسخته مسودةَ `conflict` بدلًا من ذلك؛ راجع [ترحيلات التوثيق](https://larecipe.saleem.dev/ar/3.x/sources/docs-migrations.md).

حالة المراجعة إحدى: `draft` أو `published` أو `superseded` أو `rejected` أو `reverted` أو `conflict`. ولا تكون أكثر من مراجعة واحدة لكل صفحة أو تنقل أو ملف تعريف بحالة `published` في الوقت نفسه. ونشر مسودة يجعل المراجعة السابقة `superseded`. والتراجع يجعل المراجعة التي استبدلها `reverted`، فيمكن التراجع عن التراجع نفسه.

كل خطوة تطلق حدثًا لأدواتك الخاصة: `PageWritten` و `DraftCreated` و `DraftPublished` و `DraftRejected` و `ContentChanged`. راجع [مرجع الأحداث](https://larecipe.saleem.dev/ar/3.x/reference/events.md).

## دائمًا خلف ذاكرة مؤقتة

لا تقرأ مجموعة قاعدة البيانات قاعدةَ البيانات أبدًا لتقدّم صفحة مخزّنة. فكل مجموعة قاعدة بيانات تعمل خلف طبقة ذاكرة مؤقتة لا يمكن إيقافها، ويجب أن يحتفظ المخزن بالبيانات: المخزنان `array` و `null` مرفوضان خارج الاختبارات، ويبلّغ عنهما `larecipe:validate` تحت `cache.store`، ويشير إليهما `larecipe:doctor`.

حين يتغيّر المحتوى الحي، يجهّز LaRecipe الذاكرة المؤقتة للمجموعة عبر الطابور لديك، فشغّل عامل طوابير. وعند النشر، شغّل `php artisan larecipe:cache:warm` بعد `migrate`؛ وتجد السكربت الكامل في صفحة [النشر](https://larecipe.saleem.dev/ar/3.x/operate/deployment.md).

**كيف تعمل الذاكرة المؤقتة**

- **بصمة واحدة لكل مجموعة.** تأتي من أعلى مراجعة منشورة، وعدد مرات النشر، وحالة جدول الملفات المرفقة، وتعيش في مخزن الذاكرة المؤقتة. وكل كتابة ونشر ورفض وتراجع يعيد قراءتها من قاعدة البيانات.
- **كل ما عداها يُخزَّن تحتها، بلا انتهاء صلاحية:** ملف التعريف، وقوائم الصفحات، وكل صفحة، والتنقل، والملفات المرفقة حتى 1 MB. والبصمة الجديدة تجعل كل المدخلات القديمة غير قابلة للوصول دفعة واحدة، فلا يُفرَّغ شيء يدويًا أبدًا. أما الملفات المرفقة الأكبر فتُقرأ من قرصها.
- **بيانات المراجعة لا تُخزَّن مؤقتًا أبدًا.** المسودات وسجل المراجعات لا تُقرأ إلا لمراجعتها، ويجب أن تكون حالية دائمًا.
- **التجهيز.** حين يتغيّر المحتوى الحي (نشر، أو تراجع، أو ترحيل توثيق، أو نقل مصدر)، يطلق LaRecipe الحدث `ContentChanged`. ويجهّز المستمع الخاص به، الذي يعمل عبر الطابور، المجموعة بعد أن تُثبَّت معاملة قاعدة البيانات. ويقرأ `larecipe:cache:warm` البصمة من قاعدة البيانات، ثم يخزّن ملف التعريف، ولكل إصدار ولغة: قائمة الصفحات وكل صفحة والتنقل. ومن دون `--set`، يجهّز كل مجموعات قاعدة البيانات.

**Event** `LaRecipe\Domains\Sources\Events\ContentChanged`

Payload:

| Property | Type |
| --- | --- |
| `set` | string |
| `pages` | array |

Listeners:

| Listener | Runs |
| --- | --- |
| `LaRecipe\Domains\Sources\Listeners\WarmChangedSet` | queued |

## قواعد أشد للمحتوى

من يحرّرون مجموعة قاعدة البيانات في لوحة الإدارة أو عبر MCP قد يكونون أقل موثوقية من قاعدة الكود لديك، لذا تُخضع مجموعة قاعدة البيانات صفحاتها لقواعد أشد من مجموعة المستودع:

- **يُهرَّب HTML الخام دائمًا**، وكل صفحة تُصيّرها المجموعة تمر أيضًا عبر منقّي HTML. ولا أثر للإعداد `html_input`. راجع [Markdown](https://larecipe.saleem.dev/ar/3.x/writing/markdown.md#raw-html).
- **لا يحتفظ كل مكوّن إلا بالخصائص (props) التي يعلن عنها**، بما فيها مكوّناتك الخاصة.
- **تأتي التحليلات من `config/larecipe.php` فقط** (`sets.{key}.integrations.analytics`). وتُتجاهل التكاملات الموجودة في `larecipe.json` الخاص بالمجموعة. راجع [التحليلات](https://larecipe.saleem.dev/ar/3.x/operate/analytics.md).
- **الروابط في التنقل وفي `larecipe.json`** يجب أن تكون عناوين `http` أو `https` أو `mailto`، أو مسارات في موقعك. والكتابة التي فيها أي رابط آخر تُرفض.
- **تضمينات المقتطفات** (`<<< @/...`) لا تُحَل في أي مكان حتى تمنح المجموعة مجلدًا خاصًا بها في `sets.{key}.snippets.root`.

## لوحة الإدارة

تحصل كل مجموعة توثيق على منطقة إدارة على `/{prefix}/_admin`: فللمجموعة على `/handbook` تكون `/handbook/_admin`. وتحصل مجموعة قاعدة البيانات على المحرّر الكامل. أما مجموعة المستودع فتحصل على نظرة عامة للقراءة فقط (تقرير التحقق، وجاهزية الوكلاء، والصفحات القديمة)، لأن صفحاتها تُحرَّر في git.

تقرّر البوابة (gate) `manageLarecipe` من يدخل، ومفتاح المجموعة وسيطها. وكل من عداهم يحصل على 403. وإلى أن تعرّف البوابة، لا يمرّ إلا المستخدمون المسجّلو الدخول في بيئة محلية، فعرّفها للإنتاج:

```php title="app/Providers/AppServiceProvider.php"
Gate::define('manageLarecipe', fn (User $user, string $set) => $user->is_admin);
```

كل تغيير يُجرى في لوحة الإدارة يُتحقق منه، ويُحفظ مراجعةً، ويُنسب إلى الشخص المسجّل الدخول.

### قائمة المراجعة (The pass)

قائمة المراجعة هي المكان الذي تنتظر فيه التغييرات شخصًا يراجعها، واسمها الإنجليزي (The pass) مأخوذ من منضدة التسليم في مطبخ المطعم حيث يُفحص كل طبق قبل أن يخرج. تأتي تعارضات ترحيلات التوثيق أولًا، ثم المسودات. انشر التغيير، أو ارفضه مع ذكر السبب، أو حرّره وانشر نسختك.

**التعارضات والمسودات في قائمة المراجعة**

كل تغيير ينتظر هناك تذكرة، ويعرض الشريط الجانبي عدد ما ينتظر.

التعارض تغيير من عملية نشر أُوقف لأن الإنتاج تغيّر بعد أن كُتب الترحيل. يعرض الجانبين، مُصيَّرين على الخادم أو بصيغة المصدر، مع ثلاث طرق لحلّه: الإبقاء على الإنتاج، أو أخذ الترحيل، أو تحرير دمج بينهما.

المسودات تغييرات من وكلاء عملوا خارج أي pull request، ومسودات حفظها أشخاص. تعرض كل منها بيانات التحديث (provenance) الخاصة بها (من أو أي وكيل، وملخّصه)، وفروقًا مُصيَّرة، وفروقًا في المصدر. وسبب الرفض يستطيع الوكيل الذي كتب المسودة أن يقرأه. ومع `review: auto` ينشر الوكلاء بأنفسهم، فتعرض قائمة المراجعة أيضًا ما نشروه مؤخرًا، وكل منه على بعد نقرة واحدة من التراجع.

### السجل والنشاط

لكل صفحة، ولتنقل كل إصدار، وللإعدادات، سجلٌّ تستطيع الاستعادة منه. وتعرض شاشة النشاط (Activity) كل تغيير في المجموعة، وفيها تصدّر تعديلات لوحة الإدارة بوصفها ترحيل توثيق تضيفه في commit مع pull request.

**الاستعادة، وإعادة تعديلات لوحة الإدارة إلى git**

يعرض السجل كل المراجعات، الأحدث أولًا، ولكل منها فروق مقارنةً بالمراجعة التي استبدلتها، بما فيها المراجعات التي أنشأها كل ترحيل توثيق. والمراجعة التي رآها القرّاء يومًا يمكن استعادتها. والاستعادة مراجعة جديدة، فيمكن التراجع عنها أيضًا.

التعديلات في لوحة الإدارة تغييرات مباشرة في قاعدة البيانات، تُحفظ مراجعات. ولا تنشئ ملفات ترحيل من تلقاء نفسها. ولتنقل تغييرات تختارها إلى كل البيئات عبر pull request، اخترها في شاشة النشاط وصدّرها ترحيلَ توثيق واحدًا: تعرض لوحة الإدارة الملف لتنسخه أو تنزّله، ثم تضيفه أنت في commit. وحيث تكون تلك التغييرات حية أصلًا، لا تفعل أي من عملياته شيئًا؛ وحيث انحرف المحتوى، تصبح تعارضًا في قائمة المراجعة بدلًا من الكتابة فوقه.

ولتنقل المجموعة كلها إلى git، يكتبها `php artisan larecipe:source:export` ملفاتٍ، وينقلها `larecipe:source:move database repository` إلى المستودع نهائيًا. راجع [التبديل بين المصادر](https://larecipe.saleem.dev/ar/3.x/sources/switching.md).

### شاشات أخرى

**نظرة عامة (Overview)**

عدد الصفحات، والتعارضات والمسودات التي تنتظر المراجعة، ووضع المراجعة، والإصدار. وتحت ذلك تقرير التحقق، وهو نفسه الذي يطبعه `larecipe:validate`، وبطاقة جاهزية الوكلاء: تقرير [`larecipe:doctor`](https://larecipe.saleem.dev/ar/3.x/operate/validation.md#larecipedoctor)، مع درجة، وإصلاح لكل ملاحظة. ولا لوحات بيانات لحركة الزيارات: فالتحليلات تذهب إلى أدواتك الخاصة.

**الصفحات والتنقل**

شجرة الصفحات هي تنقل الإصدار، للغة واحدة في كل مرة. اسحب الصفحات والمجموعات لتعيد ترتيبها أو لتنقل صفحة إلى مجموعة أخرى، أو ضع التركيز على مقبض السحب واضغط Alt مع مفاتيح الأسهم. أنشئ صفحات ومجموعات، وأعد تسمية مجموعة أو أزلها (تبقى صفحاتها)، وأخرج صفحة من التنقل، أو احذفها. والصفحات التي لا يذكرها التنقل تنتظر تحت الشجرة، جاهزة لتُضاف، والصفحات الجديدة المقترحة مسوداتٍ ترتبط بمراجعتها. وتحرّر طريقة عرض JSON التنقلَ نفسه على شكل `navigation.json` خام.

الإصدار الذي لا `navigation.json` له يبدأ من الشجرة التي تقتضيها صفحاته. وهناك، إخفاء صفحة يضبط `hidden: true` في ترويستها، وحفظ ترتيب جديد يكتب الشجرة بوصفها `navigation.json` للإصدار.

**المحرّر**

تُفتح الصفحات في محرّر Markdown (CodeMirror) مع معاينة حية تُصيّرها أداة التصيير في خادم LaRecipe نفسها، فتكون المعاينة تمامًا ما سيراه القرّاء، بما فيه المكوّنات. وتعرض لوحة المكوّنات كل مكوّن يستطيع الخادم تصييره (المدمجة، والمراجع الحية، وكتل الصلاحيات، ومكوّناتك الخاصة)، وتُدرج أحدها عند المؤشّر مع خصائصه معبّأة. وتظهر مشكلات التحقق أثناء الكتابة، معلَّمة على السطر الذي تشير إليه ومذكورة تحت المحرّر. ولترويسة الصفحة نموذج مولَّد من مخطط JSON Schema الخاص بها، مع مفتاح للتبديل إلى تحرير YAML الخام.

الحفظ ينشر فورًا، أو يحفظ مسودة للمراجعة بدلًا من ذلك. والاختصار Cmd+S أو Ctrl+S ينشر. وكل حفظ يُكتب بناءً على نسخة الصفحة التي حمّلها المحرّر. فإن غيّر أحدٌ الصفحة في الأثناء، لا يُكتب فوق شيء: يعرض المحرّر نسخته مقابل نسختك، فتحمّل نسخته أو تبقي نسختك. ويمكن أيضًا نقل الصفحة إلى مسار جديد أو حذفها، وتبقى الصفحة المحذوفة في سجلها.

**الملفات المرفقة (Assets)**

أفلت الصور والملفات على شاشة الملفات المرفقة لترفعها إلى قرص المجموعة، تحت `larecipe/{set}/{version}/`. ويعرض كل ملف المسار الذي تلصقه في Markdown والصفحات التي تستخدمه. وحذف ملف ما زالت صفحة تستخدمه يطلب منك التأكيد، ويسمّي تلك الصفحات.

لا مراجعات للملفات المرفقة؛ بل للصفحات التي تستخدمها. ولا تحمل ترحيلات التوثيق ملفات مرفقة: ارفعها هنا، أو أشر إلى الصور بعناوين URL. ونقل المصدر أو استيراد حزمة ينسخها.

**الإعدادات (Settings)**

تحرّر شاشة الإعدادات ملف `larecipe.json` الخاص بالمجموعة: نموذج مولَّد من مخطط JSON Schema الخاص به للاسم والشعار ورموز المظهر والإصدارات واللغات وروابط شريط التنقل العلوي وعمليات إعادة التوجيه والوصف الذي يقرؤه الوكلاء، مع مفتاح للتبديل إلى JSON الخام لما تبقى. وتعرض معاينة حية للمظهر رموزك على مكوّنات LaRecipe نفسها أثناء تغييرها. وتبقى البنية التحتية في `config/larecipe.php`: المسارات، والمصدر، والذاكرة المؤقتة، والذكاء الاصطناعي، والتحليلات. وللإعدادات سجلّ أيضًا.

**عن تطبيق لوحة الإدارة**

لوحة الإدارة تطبيق صغير قائم بذاته، مبني من نظام التصميم نفسه الذي بُنيت منه واجهة القراءة، بالوضع الفاتح أو الداكن. وتحتاج إلى JavaScript؛ أما التوثيق نفسه فلا. ومحدِّدا الإصدار واللغة في الشريط العلوي يضبطان نطاق كل شاشة. وتمر التغييرات عبر مسار الكتابة نفسه الذي تمر فيه تغييرات الوكيل. ولا يُحمَّل كودها إلا هناك، ولا يُحمَّل أبدًا في صفحات القرّاء، ولا تُخزَّن صفحاتها مؤقتًا ولا تُفهرس أبدًا. ولوحة الإدارة أداة وليست محتوى، لذا يحصل المستخدم المرفوض على 403 لا 404. والبوابة نفسها `manageLarecipe` تقرّر من يحق له استخدام أدوات التأليف في MCP على الويب و `validate_docs` على الويب. وتُسجَّل تغييرات لوحة الإدارة مع القناة `admin_ui`.

## تفاصيل

**الجداول**

كل صف يحمل مفتاح مجموعته، فيستطيع اتصال واحد أن يضم مجموعات توثيق كثيرة.

| الجدول | يحوي |
| --- | --- |
| `larecipe_pages` | الصفحات الحية: المجموعة، والإصدار، واللغة، والمسار، والعنوان، والوصف، وترويسة الصفحة، والمتن، وبصمة المحتوى، والمراجعة الحية. والصفحة المحذوفة تحتفظ بصفّها، مع ضبط `deleted_at`. |
| `larecipe_navigation` | شجرة تنقل واحدة لكل مجموعة وإصدار ولغة. |
| `larecipe_manifest` | ملف `larecipe.json` واحد لكل مجموعة. |
| `larecipe_revisions` | كل تغيير، حيًا كان أم لا: العملية، والمحتوى الكامل، وبصمته والبصمة التي بُني عليها، والحالة، ومن أجراه (شخص أو وكيل أو ترحيل، مع اسم ومرجع)، ومن أين جاء، وملخّص، ومن راجعه. |
| `larecipe_assets` | مسار كل ملف مرفق، وقرصه، ومساره على القرص، ونوعه، وحجمه، وبصمته. |
| `larecipe_docs_migrations` | ما غيّره كل ترحيل توثيق، ليستطيع التراجع (rollback) أن يعيده. |

**نماذجك الخاصة**

يقرأ LaRecipe هذه الجداول ويكتب فيها عبر نماذج Eloquent تستطيع استبدالها، كما يسمح Sanctum و Cashier. وسّع نموذجًا ووجّه مفتاحه إلى صنفك، لتضيف نطاقات عامة (global scopes) أو تعدد المستأجرين (tenancy) أو مراقبين (observers):

```php title="config/larecipe.php"
'models' => [
    'page' => App\Models\DocsPage::class,
],
```

```php title="app/Models/DocsPage.php"
namespace App\Models;

use App\Observers\DocsPageObserver;
use Illuminate\Database\Eloquent\Attributes\ObservedBy;
use LaRecipe\Domains\Sources\Models\Page;

#[ObservedBy(DocsPageObserver::class)]
class DocsPage extends Page
{
}
```

المفاتيح هي `page` و `navigation` و `manifest` و `revision` و `asset` و `docs_migration`. وسّع نموذج LaRecipe نفسه بدلًا من كتابة نموذج جديد، ليبقى الجدول والتحويلات (casts) كما هي.

## التالي

- [ترحيلات التوثيق](https://larecipe.saleem.dev/ar/3.x/sources/docs-migrations.md): كيف تصل التغييرات التي تُجرى في pull request إلى مجموعة قاعدة البيانات.
- [التبديل بين المصادر](https://larecipe.saleem.dev/ar/3.x/sources/switching.md): الانتقال بين المستودع وقاعدة البيانات.
- [أوضاع المراجعة](https://larecipe.saleem.dev/ar/3.x/keeping-current/review-modes.md): `required` و `auto`.