إنتقل إلى المحتوى الرئيسي

سياسة التوافق

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

تنطبق السياسة على 1.x. قد يراجعها خط 2.x مستقبلي؛ وإن حدث ذلك، فسيأتي دليل ترحيل مع ملاحظات إصدار 2.0.0.

ما المُغطّى​

مخطط قاعدة البيانات (ترحيلات Alembic)​

ضمن 1.x:

  • الترحيلات إضافية أو متوافقة-رجعيًا-عند-الترقية.
  • يمكن إضافة أعمدة جديدة في أي وقت.
  • لن تُحذف الأعمدة الموجودة دون المرور بدورة إلغاء دعم.
  • لن تُعاد تسمية الأعمدة الموجودة دون دورة إلغاء دعم (تُنفَّذ إعادة التسمية كـ إضافة-عمود-جديد ← تعبئة رجعية ← إلغاء-دعم-العمود-القديم ← حذف-في-الإصدار-الرئيسي-التالي).
  • تقتصر تغييرات النوع على التوسيع (مثل varchar(80) ← varchar(255))؛ أما تغييرات التضييق فتمرّ بإلغاء الدعم.
  • لن تصبح قيود المفتاح الخارجي أكثر صرامة (مثل ON DELETE SET NULL يصبح ON DELETE CASCADE) دون دورة إلغاء دعم.

يمكن للمشغّلين المضي قدمًا بثقة؛ والترحيل التلقائي عند بدء تشغيل الخلفية آمن لتشغيله على بيانات الإنتاج.

النموذج الفوقي المدمج​

ضمن 1.x، النموذج الفوقي الذي يأتي في backend/app/services/seed.py مستقر:

  • مفاتيح أنواع البطاقات المدمجة (Application، Initiative، BusinessCapability، إلخ) لن تُعاد تسميتها أو تُحذف.
  • مفاتيح الحقول المدمجة على تلك الأنواع لن تُحذف دون دورة إلغاء دعم.
  • مفاتيح أنواع العلاقات المدمجة لن تُعاد تسميتها أو تُحذف دون دورة إلغاء دعم.
  • الأنواع الفرعية الافتراضية التي تأتي مع الأنواع المدمجة مستقرة.

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

واجهة REST API (/api/v1/)​

ضمن 1.x:

  • نقاط النهاية تحت /api/v1/ لن تُحذف دون دورة إلغاء دعم.
  • أسماء حقول الطلب والاستجابة الموجودة لن تُعاد تسميتها دون دورة إلغاء دعم.
  • أنواع الحقول لن تتغيّر بشكل غير متوافق (مثل سلسلة نصية ← مصفوفة).
  • حقول الطلب الاختيارية الجديدة وحقول الاستجابة الجديدة غير كاسرة وقد تظهر في أي إصدار فرعي.
  • نقاط النهاية الجديدة غير كاسرة وقد تظهر في أي إصدار فرعي.
  • دلالات المصادقة (Bearer JWT، شكل حمولة /auth/login) مستقرة.
  • دلالات أكواد حالة HTTP مستقرة لمسارات النجاح والخطأ الموثّقة.

السلوك خارج السطح الموثّق (الترويسات غير الموثّقة، نص رسائل الخطأ الداخلية، الترتيب عند عدم تحديد sort_by) غير مشمول.

مفاتيح الأذونات​

مفاتيح الأذونات المعرّفة في backend/app/core/permissions.py مستقرة ضمن 1.x. يمكن إضافة مفاتيح جديدة؛ والمفاتيح الموجودة لن تُعاد تسميتها أو تُحذف دون دورة إلغاء دعم.

مجموعة الأذونات الممنوحة افتراضيًا للأدوار المزروعة (admin، bpm_admin، member، viewer) قد تتغيّر بين الإصدارات الفرعية، مع إشارة في CHANGELOG. المشغّلون الذين خصّصوا أذونات الأدوار في نشرهم غير متأثرين.

التهيئة (متغيرات البيئة)​

متغيرات البيئة الموجودة الموثّقة في CLAUDE.md وREADME.md مستقرة ضمن 1.x. يمكن إضافة متغيرات جديدة بقيم افتراضية معقولة. قد تتغيّر القيم الافتراضية مع إشارة في CHANGELOG عندما يكون التغيير ذا صلة بالمشغّل (مثل منفذ افتراضي جديد).

الأسرار المشفّرة عند الراحة​

علامة البادئة enc: والمفتاح المشتق بـ Fernet في backend/app/core/encryption.py مستقران ضمن 1.x. لا يحتاج المشغّلون إلى إعادة تشفير الأسرار عبر الترقيات الفرعية.

دورة إلغاء الدعم​

عندما يحتاج شيء مشمول بهذه السياسة إلى الحذف:

  1. التعليم بإلغاء الدعم في الإصدار الفرعي N. يتضمّن إدخال CHANGELOG قسم Deprecated يشير إلى التغيير. بالنسبة لنقاط نهاية API، يبعث المسار المُلغى دعمه ترويسة استجابة Deprecation: true (RFC 8594) وترويسة Sunset تشير إلى أقرب هدف للحذف.
  2. الاستمرار في الدعم في الإصدار الفرعي N+1. لا يمكن أن يحدث الحذف في الإصدار الفرعي نفسه الذي حدث فيه إلغاء الدعم. يستمر الشكل المُلغى دعمه في العمل.
  3. أقرب حذف في الإصدار الفرعي N+2 أو في 2.0 (أيهما يأتي أولًا). يأتي الحذف مع قسم Removed في CHANGELOG وملاحظة ترحيل.

بالنسبة لتغييرات شكل البيانات (ترحيلات Alembic)، ينطبق إيقاع N ← N+1 نفسه، مُعبَّرًا عنه كـ إضافة-جديد ← تعبئة رجعية ← حذف-قديم.

ما غير المُغطّى​

هذه خارج النطاق صراحةً وقد تتغيّر في أي وقت:

  • تخطيط وحدات Python الداخلية تحت backend/app/. عمليات استيراد app.models وapp.services وغيرها ليست جزءًا من واجهة API العامة. ينبغي للإضافات أو السكربتات التي تعتمد على عمليات الاستيراد الداخلية أن تثبّت إصدار Turbo EA محدّدًا.
  • بنية كتل JSONB المخزّنة على الجداول المدمجة (fields_schema، section_config، attributes، lifecycle) بما يتجاوز ما تقرؤه واجهة REST API الموثّقة. قد يتطوّر شكل JSON على القرص لدعم ميزات جديدة.
  • داخليات الواجهة الأمامية: مسارات ملفات المكوّنات، وتواقيع خصائص المكوّنات في frontend/src/، ومحتويات frontend/src/types/index.ts، وتنسيق مكوّنات MUI. المشغّلون الذين يستخدمون الواجهة الأمامية المرفقة محميون؛ ومن يضمّن مكوّنات من شجرة المصدر فهو مسؤول عن نفسه.
  • تخصيصات النموذج الفوقي التي يُدخلها المشغّل. إذا أضفت نوع بطاقة أو حقلًا مخصصًا عبر واجهة الإدارة، فأنت تملك قصة الترحيل عند تغييره.
  • بيانات العرض والزرع (SEED_DEMO=true). يُسمح لمجموعة بيانات العرض بالتطوّر بحرية بين الإصدارات.
  • خدمات الطرف الثالث المرفقة: إصدار DrawIO، صورة Ollama المرفقة، إصدار swagger-ui-dist المضمَّن. قد تُرقّى في أي وقت.
  • السلوك مع التهيئات غير الافتراضية المُعلَّمة صراحةً كتجريبية في إدخالات CHANGELOG.

ما الذي يغيّره "1.0.0" فعلًا​

مقارنة بسلسلة 0.x، فإن 1.0.0 نفسه ليس إصدار ميزات — إنه النقطة التي تبدأ عندها الالتزامات أعلاه بالتطبيق. الشيفرة المشحونة في 1.0.0 هي نفس الشيفرة التي شُحِنت في 0.71.0، بالإضافة إلى تصليب سلسلة التوريد وتغييرات تدفق المساهمين الموثّقة في إدخال CHANGELOG لـ 1.0.0.

لم تكن إصدارات ما قبل 1.0 مشمولة بهذه السياسة. كان بإمكان عمليات الترحيل بين إصدارات 0.x أن تتضمّن — وقد تضمّنت — حذف مخططات وإعادة تسمية وتغييرات كاسرة للنموذج الفوقي. من 1.0.0 فصاعدًا، تمرّ تلك بدورة إلغاء الدعم.