الإضافات¶

يقوم متجر الإضافات (الإدارة ← الإضافات) بتثبيت إضافات موقّعة من المورّد تضيف قدرات خاصة بالعميل — محتوى إضافيًا للنموذج الفوقي، وتكاملات، ومهام خلفية، وحتى صفحات جديدة — دون تغيير نواة Turbo EA (مبدأ «clean core»).

يمكن تثبيت الإضافات بطريقتين: بنقرة واحدة من المتجر المدمج (إذا كان المثيل متصلاً بالإنترنت) أو عبر رفع الملفات مباشرةً — الإضافة حزمة .teax موقّعة، والترخيص ملف نصي موقّع، ويُرسَل كلاهما عادةً عبر البريد الإلكتروني. لا يتطلب المسار المعتمد على الملفات حساب متجر أو اتصالاً خارجيًا، لذا تعمل العملية بالكامل بالشكل نفسه على الأنظمة المعزولة عن الإنترنت (air-gapped).

تحتوي الصفحة على تبويبين: المتجر لتصفح كتالوج ملحقات المورّد مع تثبيت بنقرة واحدة، والمثبَّتة لإدارة الرخص والتثبيت من الملفات.

تُبنى الإضافات وتُوقَّع من قِبل Turbo EA — فهي ليست ذاتية البناء ولا مفتوحة لأطراف ثالثة. إذا كنت بحاجة إلى ميزة مُصمَّمة خصيصًا لمؤسستك، يمكننا بناؤها وترخيصها لك. راجع استشارات Turbo EA.

كيف تعمل الثقة¶

تحمي نظامك عمليتا تحقق مستقلتان:

المصدر (التوقيع). تحمل كل حزمة توقيع Ed25519 بمفتاح المورّد. يتحقق Turbo EA منه عند الرفع ومرة أخرى عند كل تشغيل للخادم الخلفي. تُرفض الحزم غير الموقّعة أو المعدّلة أو الصادرة عن طرف ثالث — فالإضافة المثبّتة مضمونة بأنها تمامًا ما بناه المورّد.
التفعيل (الترخيص). يسرد ملف الترخيص الموقّع استحقاقاتك — واحد لكل إضافة، ولكل منها تاريخ انتهاء خاص. لا تعمل الإضافة المثبّتة إلا ما دام هناك استحقاق صالح. الرخص مرتبطة بمعرّف مثيلك — تُرفض أي رخصة صادرة لمثيل آخر.

الإضافات المجانية¶

بعض الإضافات مجانية ولا تتطلب أي ترخيص على الإطلاق. تُثبَّت وتعمل فوراً — لا خطوة شراء ولا ملف ترخيص يُلصَق. تُميَّز الإضافات المجانية بشارة مجاني في علامتَي التبويب «المتجر» و«المثبَّتة»، ويُخفى إجراءا الشراء والتجديد لها. يبقى فحص التوقيع سارياً تماماً كما في الإضافات المدفوعة (فالإضافة المجانية موقَّعة من المورِّد أيضاً)، فتكون الأصالة مضمونة في الحالتين. ولأنها لا تحتاج إلى استحقاق، فإن الإضافات المجانية لا تنتهي صلاحيتها ولا تدخل فترة سماح أبداً.

معرّف المثيل الخاص بك¶

تولّد كل عملية تثبيت مرة واحدة معرّف مثيل فريدًا (TEA-XXXX-XXXX-XXXX) يظهر أعلى صفحة الإدارة ← الإضافات مع زر نسخ. إنه هويتك الترخيصية: اذكره عند الشراء (يرسله المتجر المدمج تلقائيًا؛ وتطلبه صفحة الدفع في المتجر الإلكتروني) بحيث تجتمع كل إضافة تُشترى لهذا المثيل — من أي مسؤول وبأي بريد إلكتروني — في رخصة واحدة موحّدة. وهو يعرّف مثيلك فحسب؛ وليس بيانات اعتماد أبدًا، لذا يمكن مشاركته مع المورّد بأمان.

ينتقل المعرّف مع نقل مساحة العمل، لذا يبقى الترخيص صالحًا عند الانتقال إلى مضيف جديد. بعد إعادة تثبيت كاملة يحصل المثيل على معرّف جديد — اطلب من المورّد إعادة إصدار الرخصة له (عملية «re-key» سريعة من جانبه).

تبويب المتجر¶

يعمل تبويب المتجر دون أي تكوين ويعرض الملحقات المنشورة من المورّد مع الوصف والسعر:

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

عندما يتضمن الكتالوج فئات، يعرض كل عنصر شارات صغيرة (free أو commercial، بالإضافة إلى مواضيع مثل integration) ويظهر شريط تصفية فوق القائمة — انقر على الشارات لتضييق النتائج (تتحد عدة شارات معًا)، ويعيد All ضبط العرض.

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

تقوم النسخة أيضًا بفحص الفهرس مرة واحدة يوميًا وتُبلغ عن التغييرات، حتى لا تنتظر إضافة جديدة — أو إصلاح أمني لإضافة تستخدمها بالفعل — أن يفتح أحدهم هذه الصفحة مصادفةً. يتلقى المسؤولون (كل من يمنحه دوره صلاحية admin.manage_extensions) إشعارًا في الجرس عند نشر إضافة جديدة في المتجر، وإشعارًا آخر عند توفر إصدار أحدث من إضافة مثبتة لديهم. ويُعلَن عن كل تغيير مرة واحدة، ويصل يوم الإصدارات المزدحم على هيئة إشعار واحد لكل نوع بدلًا من إشعار لكل إضافة. ولا يُنزَّل أو يُثبَّت أي شيء — الإشعار يقودك إلى هنا فحسب. ويمكن إيقاف الفحص اليومي تمامًا من الإدارة → الإعدادات → إشعارات التحديث.

الفترات التجريبية¶

تقدّم بعض الإضافات المدفوعة تجربة مجانية لمدة 30 يومًا — ابحث عن زر بدء تجربة 30 يومًا في تبويب المتجر (أو خيار التجربة على موقع المتجر). بدء التجربة يعمل مثل الشراء ولكن من دون دفع: لا حاجة إلى بطاقة ائتمان، ويتم تحديث ترخيصك تلقائيًا (تصل نسخة أيضًا عبر البريد الإلكتروني للتثبيتات المعزولة)، وتعمل الإضافة بكامل وظائفها لمدة 30 يومًا.

يمكن لكل مثيل Turbo EA تجربة إضافة معيّنة مرة واحدة فقط.
تنتهي التجربة في تاريخ انتهائها بالضبط — لا توجد فترة سماح. تتوقف الإضافة بعد ذلك عن العمل حتى تشترك؛ لا تُحذف بياناتك أبدًا، ويعود كل شيء فور تطبيق ترخيص اشتراك.
يعرض تبويب «المثبَّتة» استحقاقات التجربة على شكل تجربة حتى ….
تنتهي الفترات التجريبية من تلقاء نفسها — لا يوجد ما يلزم إلغاؤه ولا تُفرض أي رسوم أبدًا.

تثبيت إضافة¶

إن لم تكن قد فعلت ذلك بعد، طبّق ترخيصك أولًا (انظر أدناه).
افتح الإدارة ← الإضافات، واختر التثبيت من ملف… في تبويب المتجر، ثم ارفع ملف .teax الذي تلقيته.
يتحقق Turbo EA من التوقيع ويعرض معاينة: للإضافات الحاملة للمحتوى تكون تجربة جافة لكل نوع بطاقة ومجموعة وسوم وبطاقة وعلاقة ستنشئها الإضافة أو تحدّثها — لا يُكتب شيء بعد.
راجع المعاينة ثم اضغط تثبيت الإضافة.
إذا كانت الإضافة تحمل شيفرة خلفية، يطلب شريط تنبيه إعادة تشغيل حاوية الخادم الخلفي (docker compose restart backend). أما إضافات المحتوى والواجهة فتصبح فعّالة فورًا — يرى المستخدمون الواجهة الجديدة عند إعادة تحميل الصفحة.

رفع الحزمة نفسها مرة أخرى آمن — تعرض المعاينة كل شيء كـ«تم تخطيه» ولا يغيّر التطبيق شيئًا.

تحديث إضافة¶

عندما ينشر المتجر إصدارًا أحدث من إضافة مثبّتة، يعرض تبويب «المثبّتة» شارة التحديث إلى X بجوار الإصدار (ويتحول زر تبويب المتجر إلى تحديث). نقرة واحدة تنفّذ نفس التحقق من التوقيع والمعاينة والتطبيق كما في التثبيت الجديد. ينطبق إجراءان وقائيان:

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

التراخيص والتجديد¶

طبّق الترخيص عبر إدخال الترخيص… في تبويب المثبَّتة (الصق النص أو ارفع الملف) — يظهر الزر أيضًا على كل صف إضافة تحتاج إلى ترخيص. تعرض الصفحة بعدها اسم المرخَّص له وشارة لكل حق مع تاريخ انتهائه.

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

عندما يتجاوز استحقاقٌ تاريخ انتهائه يدخل فترة سماح (30 يومًا افتراضيًا): يستمر كل شيء في العمل ويرى المسؤولون شريط تحذير. بعد فترة السماح تُعطَّل الإضافة تعطيلًا ناعمًا — تختفي صفحاتها، وترفض واجهتها البرمجية الطلبات، وتتوقف مهامها الخلفية مؤقتًا. لا تُحذف أي بيانات أبدًا. يؤدي تطبيق ملف ترخيص مجدد إلى استعادة كل شيء فورًا دون إعادة تشغيل.

التراخيص المشتراة عبر المتجر تتجدد تلقائيًا على المثيلات المتصلة: بعد كل عملية دفع ناجحة يجلب مثيلك الترخيص الممدد تلقائيًا — لا حاجة للصق أي شيء. أما في نظام معزول فيكون التجديد: الصق ملف الترخيص المحدّث من رسالة التجديد (أو اطلبه من المورّد) — لا شيء آخر.

حالة التجديد التلقائي وإلغاء الاشتراك¶

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

لعرض تاريخ التجديد، أو إلغاء التجديد التلقائي أو استعادته، أو تغيير طريقة الدفع، أو تنزيل الفواتير، استخدم زر إدارة الاشتراك بجوار اسم المرخَّص له (يظهر للتراخيص المشتراة من المتجر). يفتح الزر بوابة الفوترة الخاصة بك في تبويب جديد — دون الحاجة إلى حساب. على مثيل معزول لا يمكن للزر الوصول إلى المتجر؛ استخدم بدلاً منه رابط إدارة الاشتراك الموجود في كل بريد ترخيص (متصفحك فقط يحتاج إلى الإنترنت، وليس مثيل Turbo EA).

الإلغاء لا يوقف أي شيء فورًا: تستمر الإضافة في العمل حتى نهاية الفترة المدفوعة، ثم يسري المسار المعتاد لفترة السماح + التعطيل الناعم. بياناتك لا تُحذف أبدًا، وإعادة الاشتراك تستعيد كل شيء.

التفعيل والتعطيل والإزالة¶

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

الصلاحيات¶

الصفحة بأكملها وجميع مسارات API الخاصة بها محمية بالصلاحية المخصصة admin.manage_extensions (الممنوحة لدور المسؤول المدمج). يمكن للإضافات تعريف مفاتيح صلاحيات خاصة بها (ext.<الاسم>.…) تظهر في الإدارة ← المستخدمون والأدوار بعد تحميل الإضافة.

ميزات الحقول المتقدمة¶

تتيح بعض الإضافات طرقًا متقدمة لوصف بياناتك لا توفرها النواة بمفردها:

نص مساعدة الحقل — إرشاد قابل للطي يظهر أسفل الحقل أثناء إدخال البيانات، بحيث يشرح النموذج نفسه.
أنواع حقول مخصصة — أنواع جديدة تتجاوز المجموعة المدمجة (مثل تقييم قابل للتهيئة من ١ إلى ٥ أو من ٠ إلى ١٠).

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

أذونات الوصول إلى البيانات¶

تعمل معظم الامتدادات مع بياناتها الخاصة فقط. أما الامتداد الذي يتكامل مع بيانات النواة — مثل موصّل يزامن المهام (todos) مع أداة تتبع مهام خارجية مثل Jira أو MS Planner ‏(#921) — فيجب أن يعلن عن الأذونات (grants) في بيانه الموقّع:

core.todos.read / core.todos.write — قراءة المهام أو تعديلها عبر SDK الامتدادات. إذن الكتابة يتضمن القراءة. في مهام النظام (مثل طلبات التوقيع) لا يستطيع امتداد المزامنة سوى تعيين المرجع الخارجي الظاهر كشارة — ولا يمكنه أبدًا إكمالها أو تعديلها أو إعادة إسنادها أو حذفها، وتبقى مهام الامتدادات الأخرى خارج متناوله.
core.events.todo — استقبال أحداث تغيّر المهام، ليتفاعل الموصّل فورًا بدلًا من انتظار دورة الاستطلاع التالية.
core.users.read — الاطلاع على المستخدمين (الاسم والبريد الإلكتروني وحالة التفعيل فقط) ليتمكن الموصّل من مطابقة المكلّفين مع الحسابات في الأداة الخارجية. لا تُكشف أي بيانات عن الأدوار أو تسجيل الدخول أو التفضيلات، ولا يمكن للامتدادات أبدًا تعديل المستخدمين.
core.cards.read — قراءة البطاقات والعلاقات والنموذج الوصفي، مثلًا ليتمكن الموصّل من مطابقة تطبيقاتكم مع السجلات في نظام خارجي. تبقى البطاقات المؤرشفة خارج نطاق الرؤية.
core.cards.write — إنشاء البطاقات أو تحديثها أو أرشفتها وإضافة العلاقات، بنفس التحقق الذي يطبّقه محرر التطبيق تمامًا. تُدمج التحديثات قيم الحقول بدلًا من استبدالها، لذا لا يمكن لأي امتداد أبدًا محو بيانات لا يديرها، ولا يوجد حذف نهائي — الأرشفة، مع نافذة الاستعادة الخاصة بها، هي الإزالة الوحيدة المتاحة للامتداد.
core.events.card — استقبال أحداث تغيّر البطاقات والعلاقات، ليتفاعل الموصّل فورًا مع تغييرات الجرد بدلًا من انتظار دورة الاستطلاع التالية.

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

يظهر كل تغيير يجريه امتداد في الإدارة ← سجل التدقيق كدفعة ext:<key> مع فروقات حقلًا بحقل، ويمكن التراجع عنه من هناك مثل أي دفعة أخرى. يبقى القرار الأخير للمشغّلين: متغيّر البيئة EXTENSION_WRITES_ENABLED=false يوقف فورًا جميع كتابات الامتدادات (تستمر القراءات، دون إعادة تشغيل)، بينما يحدّ EXTENSION_MAX_WRITES_PER_BATCH / EXTENSION_MAX_BATCHES_PER_MINUTE من حجم ما يمكن لامتداد واحد تغييره في الدفعة الواحدة وفي الدقيقة.

أين تظهر صفحات الإضافات¶

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