# المسرد

المصطلحات المستخدمة في الكود والملاحظات الهندسية وملفات الأدلة، بكلمات بسيطة. الصفحات الموجهة للمستخدم تقول "عميل" و"خادمك"، والكود يقول `organization` و`installation`.

## الهرمية ومكان التشغيل

- **التثبيت (`installation`).** اسم خادمك في الكود: نسخة واحدة من صباربيز مع فهرسها وخدماتها وحالتها.
- **المنظمة (`organization`).** اسم العميل في الكود. تملك المشاريع، ولها أعضاء بأدوار.
- **المشروع.** تطبيق العميل. يجمع البيئات ولا يحمل بيانات خاصة به.
- **البيئة.** نسخة واحدة قابلة للنشر من المشروع، مثل الإنتاج أو التجربة، ولها قاعدة بياناتها وحسابات دخولها ومفاتيحها وAuth وREST. هي وحدة العزل والنقل والاستعادة.
- **معرّف التشغيل (`runtime`).** المعرّف الداخلي لخدمات البيئة العاملة، مثل `e_1f06...`. المسارات وملفات الحالة مفهرسة به.
- **مكان التشغيل (`placement`).** المكان الذي تعمل فيه خدمات البيئة فعلًا. يُخزَّن منفصلًا عن الملكية، فتنتقل البيئة دون أن يتغير مالكها.
- **المصدر والهدف.** في النقل أو الاستعادة، المصدر هو المحرك الذي جاءت منه البيئة، والهدف هو المحرك الجديد الذي تُستعاد إليه.
- **سجل التوجيه.** صف في الفهرس يحدد وجهة الطلبات لكل معرّف تشغيل، وهل البيئة في الصيانة، ورقم مراجعتها.
- **الصيانة.** علامة على سجل التوجيه. ما دامت مفعّلة، تجيب البوابة بـ`503` بدل تمرير الطلب.
- **المراجعة.** عدّاد على سجل التوجيه. كل تغيير يذكر رقم المراجعة الذي يتوقعه، فلا يستطيع طرف متأخر أن يكتب فوق قرار أحدث.
- **نطاق الإدارة.** نسخة Auth مخصصة يدخل إليها المشغّلون. لا تكون أبدًا Auth الخاصة ببيئة تطبيق.
- **الفهرس.** قاعدة SQLite المحلية التي تحفظ العملاء والمشاريع والبيئات والعضويات والمهام والتوجيه. لا تُخزَّن فيها بيانات التطبيقات أبدًا.
- **مشغّل التثبيت.** مالك أو مدير في العميل الذي أُنشئ عند الإعداد الأولي. وحده يرى الخادم، ويغيّر حصص البوابة، ويعيد ربط النسخ الاحتياطية، ويشغّل التحديثات؛ ويربط مالكو التثبيت Telegram أيضًا.
- **معرّف المشروع (ref).** اسم من 20 حرفًا تحمله البيئة في الواجهة المتوافقة مع Supabase (`/v1/projects/{ref}`)، حيث تُعدّ كل بيئة مشروعًا.
- **مدة الحفظ.** تحتفظ البيئة المحذوفة بقاعدة بياناتها وحاوياتها وملفاتها سبعة أيام، ويستطيع المالك خلالها استعادتها؛ ولا يزيلها مشغّل التثبيت نهائيًا إلا بعد ذلك.

## بيانات الاعتماد والوصول

- **المفتاح العام.** مفتاح API يرسله التطبيق في ترويسة `apikey`. هو عام بطبيعته، ومنذ 0.5.0 يُحفظ لتعرضه لوحة الإدارة مرة أخرى.
- **المفتاح السري.** مفتاح API يعمل بصفة `service_role`، للخوادم والوكلاء فقط، ويُرفض من المتصفحات. لا يُحفظ منه إلا بصمته، ويظهر مرة واحدة ([مفاتيح API](https://base.sbarah.com/docs/guides/api-keys/)).
- **رمز الوصول.** رمز شخصي (`sbp_...`) يتيح لوكيل أو أداة العمل باسمك عبر نقطة MCP والواجهة المتوافقة مع Supabase، ضمن نطاق تختاره ([وكلاء الذكاء الاصطناعي](https://base.sbarah.com/docs/guides/agents/)).
- **نقطة MCP.** المسار `/mcp` على عنوان لوحة الإدارة، وفيه يعمل خادم MCP الرسمي من Supabase لوكيل يحمل رمز وصول، فوق واجهة `/v1` ([وكلاء الذكاء الاصطناعي](https://base.sbarah.com/docs/guides/agents/)).
- **حساب الدخول المحصور.** حساب دخول PostgreSQL يخص بيئة واحدة وخدمة واحدة (Auth أو REST أو Storage).
- **حساب المطوّر.** حساب دخول PostgreSQL لكل بيئة، للترحيلات والوصول المباشر والوكلاء وStudio. يعمل داخل قاعدة بياناته كما يعمل مستخدم `postgres` في مشروع Supabase، لكنه ليس مستخدمًا خارقًا ([الوصول إلى قاعدة البيانات](https://base.sbarah.com/docs/guides/database-access/)).
- **مخططات المنصة.** أسماء مخططات تنشئها المنصة بنفسها (`auth` و`storage` و`realtime` و`vault` و`cron`، وكل اسم يبدأ بـ`supabase` أو `sbarbase`، وغيرها). حارس لا يستطيع حساب المطوّر حذفه ولا تعطيله يرفض إنشاءها أو إعادة التسمية إليها.
- **الإضافة المرفوضة.** إضافة تصل إلى شبكة الخادم أو ترى كل البيئات، مثل `http` و`pg_net` و`dblink` و`pgroonga`. لا يستطيع حساب المطوّر إنشاءها.
- **Vault.** مخزن الأسرار المشفّر من Supabase، مثبّت في كل بيئة. مفتاحه الجذري واحد يخص الخادم، وتتشاركه كل بيئاته.
- **جلسة Studio.** نسخة Studio وpostgres-meta لبيئة واحدة، تبدأ عند الطلب على شبكة خاصة، وتُفتح بتذكرة دخول تصلح مرة واحدة، وتنتهي بعد ثماني ساعات دون استعمال أو سبعة أيام على الأكثر ([Studio](https://base.sbarah.com/docs/guides/studio/)).
- **الأدوار القياسية.** أدوار Supabase الثلاثة `anon` و`authenticated` و`service_role`. توجد مرة واحدة في كل محرك PostgreSQL، وتتشاركها البيئات بالاسم.
- **ملف HBA.** ملف المصادقة في PostgreSQL (`pg_hba.conf`): قواعد تحدد أي حساب يتصل بأي قاعدة ومن أين. صباربيز يكتب أزواجًا دقيقة من الحساب والقاعدة.
- **سلطة HBA.** البروتوكول الذي يحدد أي عملية يحق لها تعديل ملف HBA، فلا يكتب طرفان فوق بعضهما.
- **المستأجر.** البيئة كما تراها خدمة Storage المشتركة، بإعداداتها ومفاتيح توقيعها الخاصة.

## التجهيز والأمان عند الانهيار

- **المهمة والحجز والمحاولة.** المهمة عمل تجهيز في الطابور، والحجز استلام العامل لها، والمحاولة هي المرة المرقّمة. السجلات تذكر الثلاثة معًا، فلا تُخلط محاولة قديمة بأحدث منها.
- **قفل العامل.** قفل ملف حصري يمسكه العامل الوحيد المسموح له بالعمل.
- **قفل العملية.** قفل يرتّب عمليات دورة الحياة (التشغيل والإيقاف والتصدير والترحيل) واحدة بعد أخرى.
- **الأثر.** أي تغيير خارج الفهرس: حاوية، قاعدة بيانات، حساب دخول، قاعدة HBA.
- **إيصال الأثر.** ملف صغير دائم يُكتب قبل أن يبدأ الأثر، ويذكر حجز المهمة ورقم المحاولة بدقة. الإيصال المكتمل يُسوّى عند إعادة التشغيل، والإيصال المعلّق يمنع التشغيل وإعادة التنفيذ.
- **التسوية.** تسجيل النتيجة المعروفة للإيصال في الفهرس، ثم حذف الإيصال.
- **المراقب.** عملية تشرف على تنفيذ الأثر ضمن مهلة، وتنظّف مجموعة عملياته إذا توقف العامل.
- **الشاهد.** ملف دائم يكتبه المجهِّز عند الانتهاء، فإذا ضاع التأكيد أمكن استرجاعه دون إعادة العمل.
- **عقد الأثر.** قفل جديد يمسكه كل تشغيل للعامل طوال عمره، فلا يتصرف عامل بديل وأثر قديم ما زال يعمل.
- **الفحص المسبق.** الفحوصات التي تسبق أي تغيير خارجي. إذا ثبت أن الانقطاع وقع في الفحص المسبق، تعود المهمة إلى الطابور تلقائيًا.
- **بروتوكول المراحل.** علامات لكل عملية (الفحص المسبق، القاعدة، الخدمات، التخزين، النشر) تسجّل إلى أين وصل الأثر.
- **سجل العملية (`journal`).** سجل يُضاف إليه فقط أو يُستبدل دفعة واحدة، يحفظ نية العملية وتقدمها. يُكتب قبل التنفيذ، ويُستخدم للاستكمال أو المطابقة.
- **السياج.** حاجز يمنع طرفًا قديمًا أو متأخرًا من الكتابة. سياج المصدر يغلق القاعدة، وسياج عمليات SQL وسياج HBA يرفضان رمز عملية ملغى.
- **رمز العملية.** معرّف عشوائي مرتبط بعملية واحدة. الكتابات تحمله، وبعد إلغائه لا يكتب أبدًا.
- **شاهد الإلغاء.** السجل الدائم لإلغاء الرمز. لا يُحذف أبدًا، فلا تعود عملية ملغاة إلى العمل.
- **الجيل.** حاوية قاعدة بيانات مُدارة بعينها، تُعرف بمعرّف الحاوية وصورتها بدقة.
- **تثبيت الجيل.** الهوية المحفوظة للجيل الحالي. يرفض التشغيل إذا لم تطابقها الحاوية العاملة.
- **ترحيل الجيل.** الإجراء المسجّل والمختبر ضد الانهيار (`lab/migrate-generation.py`) الذي يستبدل حاوية القاعدة على وحدة التخزين نفسها.
- **المحفوظ.** الحاويات ووحدات التخزين والحالة التي نُبقيها بين التشغيلات عمدًا. لا نحذف البيانات المحفوظة ولا نعيد إنشاءها لتجاوز رفض.
- **التبنّي.** إدخال قاعدة محفوظة قديمة تحت سلطة HBA الحالية وتثبيت الجيل، صراحة ولمرة واحدة.
- **المطابقة.** خطوة صريحة يفحص فيها المشغّل الحالة الفعلية بعد انقطاع ويسجّل نتيجة آمنة.
- **النتيجة المجهولة.** أثر ربما حدث وربما لم يحدث. يمنع إعادة التنفيذ حتى يطابقه المشغّل.

## الموارد والحمل

- **فئة الموارد.** سياسة تعطي الحاوية وزن المعالج وحده الأقصى والذاكرة وحدود الإدخال والإخراج لكل جهاز.
- **القبول.** الفحوصات قبل تشغيل بيئة جديدة أو مكان تشغيل جديد: الذاكرة والقرص وعُقد الملفات والضغط وميزانية الاتصالات. الرفض لا يشغّل شيئًا.
- **القبول المشترك.** قبول تشغيل المصدر والهدف معًا، مع احتياطي للخادم.
- **الضغط.** معلومات تعطّل المهام في cgroup على Linux: كم انتظرت المهام المعالج أو القرص أو الذاكرة. الضغط المرتفع يرفض البيئات الجديدة.
- **ميزانية الاتصالات.** اتصالات PostgreSQL المحجوزة لكل حساب خدمة. يجب أن تتسع تحت حد المحرك مع هامش للمشغّلين.
- **قبول البوابة.** حد داخل العملية لعدد الطلبات المتزامنة لكل بيئة وللمجموع. لا طابور: الطلبات الزائدة تأخذ `429` أو `503`.
- **حصة البوابة.** عدد الطلبات المتزامنة المضمون لبيئة واحدة، و8 افتراضيًا. والبيئة المشغولة تستعير الخانات الفارغة حتى 24 من أصل 64 في البوابة.
- **التصريف.** انتظار انتهاء الطلبات التي قبلتها عملية البوابة.
- **عقد الإيقاف المؤقت.** مقبض داخل العملية يوقف بيئة واحدة مؤقتًا في عملية بوابة واحدة، ويستطيع انتظار تصريفها. يزول عند إعادة التشغيل.
- **المهلة.** حد زمني للطلب أو لتدفق الرد أو لجملة SQL، تفشل بعده بدل أن تبقى معلّقة.
- **الجار المزعج.** حمل بيئة يبطئ بيئة أخرى على المحرك أو الخادم المشترك.

## الاستعادة

- **التصدير.** حزمة مشفّرة لبيئة واحدة: تفريغ القاعدة وحسابات الدخول والصلاحيات والإعدادات والملفات ومفاتيح التوقيع.
- **السكون.** حالة لا تستطيع فيها أي جلسة عميل أو معاملة محضّرة أو مهمة خلفية تغيير البيانات أثناء تصديرها.
- **التحويل.** نقل حركة البيئة من المصدر إلى الهدف بعد التحقق من نجاح الاستعادة.
- **هدف الاستعادة.** محرك PostgreSQL جديد ومنفصل تُستعاد إليه البيئة.

## سير العمل في المشروع

- **تثبيت الإصدار وملف القفل.** وسم صورة وبصمتها الدقيقة، مسجّلان في `lab/*.lock.json`.
- **الأدلة.** ملف JSON في `docs/evidence/` يكتبه فحص حي، ويسجّل كل فحص ونتيجته.
- **الفحص الحي والبيئات الثابتة.** سكربت اختبار حي (`lab/*-check.*`) وبيئات الاختبار المحفوظة التي يعمل عليها.
- **نقطة التحقق.** مدخل مؤرخ في الملاحظات الهندسية يسجّل ما ثبت في ذلك الوقت.
- **قناة التحديث.** إصدارات موقّعة يبحث عنها الخادم ويثبّتها من لوحة الإدارة، أو وحده في نافذة الصيانة ([الترقيات](https://base.sbarah.com/docs/guides/upgrades/)).
- **فئة الإصدار.** طريقة تثبيت الإصدار: `safe`، أو `attended` (يحتاج إقرار المشغّل، مثلًا لتغييرات مخطط Auth أو Storage)، أو `rebuild`، أو `manual`.
- **التعليق.** ما دام إصدار جديد ينتظر فحوص سلامته، تجيب مسارات التطبيقات بـ`503` وتتوقف أغلب تغييرات الإدارة.
- **حارس البدء.** سكربت صغير يجريه كل تشغيل قبل أي كود من الإصدار الموجود في نسخة المستودع، منسوخ من الإصدار الذي تركته آخر ترقية، فلا يستطيع إصدار معطوب أن يقطع طريق العودة. وما دامت الترقية تنتظر فحوص سلامتها، يعيد الحارس نسخة المستودع إلى سابقها إن فشل التشغيل ([الترقيات](https://base.sbarah.com/en/docs/guides/upgrades/#the-start-guard)).