دليل البداية مع SoftJL Community: ربط المتطلبات وUML والاختبارات والوثائق باستعمال الذكاء الاصطناعي

شنو هو SoftJL Community

SoftJL Community هو منصّة هندسية للبرمجيات بالذكاء الاصطناعي، قابلة للنشر بشكل مستقل، وموجّهة لمشاريع التخرّج فمجال البرمجيات، ومشاريع المواد، وتمارين UML. كيربط تحليل المتطلبات، وتحليل الجدوى، ونمذجة UML، والتصميم، والاختبار، والوثائق الهندسية، وتتبع التغييرات، باش يعاونك تتحقق واش المتطلبات تطبقات فالتصميم والاختبارات، ويرتّب ليك أدلة قابلة للتتبع من أجل التعديلات والعروض والمناقشة.

نسخة المجتمع كتوفّر الكود المصدري كامل، ومرخّصة بموجب Apache License 2.0. مقارنة مع النسخة المستضافة فالموقع الرسمي، نسخة المجتمع كتحتاج منك تسيير الخدمات وقاعدة البيانات ومزوّد النماذج، ولكن كتحافظ على القدرات الرئيسية بحال استخراج قواعد المتطلبات، ونماذج المتطلبات والتصميم الكاملة، وتغطية الاختبارات، وتوليد الوثائق، وتتبع المصادر، وتسيير المشاريع، وربط النماذج بنظام BYOK.

سير العمل الرئيسي

المنصّة خدامة وفق سلسلة هندسية كتمتد من المتطلبات حتى التحقق: كتدخل المتطلبات وكتأكد القواعد، من بعد كتدير تحليل الجدوى، وكتولّد نموذج المتطلبات ونموذج التصميم، ثم كتولّد حالات الاختبار ومصفوفة التغطية، وفالأخير كتولّد وثائق هندسية قابلة للتحرير والتحميل.

• قواعد المتطلبات: استخراج القواعد من المتطلبات المكتوبة باللغة الطبيعية، وفحص الجودة، والمراجعة، والتأكيد اليدوي، وترتيب شروط القبول.
• تحليل الجدوى: توليد مخطط بيئة النظام، ومخططات سير العمل التجاري والنظامي، وتحليل حلول التنفيذ.
• نماذج UML: إنشاء نماذج للبنية الوظيفية، وحالات الاستخدام، والمفاهيم المجالّية، وواجهات النماذج الأولية، ومتطلبات النشر، والبنية العامة، وأصناف التصميم، وقاعدة البيانات وغيرها.
• الاختبار والتغطية: توليد حالات اختبار للسيناريوهات العادية والاستثنائية والحدّية، وتحديد الثغرات عبر مصفوفة التغطية ومصفوفة التتبع.
• الوثائق الهندسية: توليد تقرير دراسة الجدوى، ووثيقة مواصفات المتطلبات، ووثيقة تصميم البرمجيات، مع دعم إدارة الإصدارات وتحميل DOCX.
• تأثير التغييرات: عرض علاقات المصدر بين المتطلبات والتصميم والاختبارات والوثائق، وتحديد المنتجات اللي خاصها التحديث من بعد التعديل.
• ربط النماذج: إعداد خدمات نماذج متوافقة مع OpenAI واستعمال مزوّد النماذج ديالك.

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

التحضير للبيئة قبل التثبيت

فأول تشغيل، خاصك تحضّر البيئة التالية:

• Node.js 22
• npm 10
• Java 21
• Graphviz
• اختياري: Docker لتشغيل PostgreSQL وOnlyOffice

فأول استعمال لخدمة التصيير، ممكن النظام يحتاج اتصال بالإنترنت باش يحمّل خطوط PDF الصينية. Docker ماشي ضروري للتجربة المؤقتة ديال الخدمات الأساسية، ولكن الاستعمال الطويل كينصح بإعداد PostgreSQL دائم؛ وإذا بغيتي تحرّر ملفات DOCX عبر الإنترنت، خاصك حتى تفعّل OnlyOffice.

تشغيل الخدمات الأساسية بسرعة

1. جلب الكود المصدري وتثبيت الاعتماديات

git clone https://github.com/guolola/SoftJL.git
cd SoftJL
npm ci

2. تشغيل بيئة التطوير

npm run dev

هاد الأمر كيبني أوتوماتيكياً الحزم المشتركة contracts وprompts، وكيشغّل بالتوازي خدمات Web وAPI والتصيير. غالباً Web كيتشغّل على http://localhost:3000، وAPI كيستعمل المنفذ 4101، وخدمة Render Service كتستعمل المنفذ 4002.

ملي يبان Ready فإخراج Web، تقدر تفتح http://localhost:3000. ومن الأحسن حتى تتحقق من الحالة الصحية:

http://localhost:3000/api/health
http://127.0.0.1:4002/health

خاص جوج واجهات التحقق الصحية يرجّعو نتيجة فيها status: "ok".

3. فهم وضع الذاكرة المؤقتة

التشغيل المباشر ديال npm run dev كيستعمل افتراضياً وضع الذاكرة المؤقتة. من بعد إعادة تشغيل الخدمات، الحسابات والمشاريع وإعدادات خدمات النماذج وسجل التشغيل غادي يضيعو؛ وملفات الوثائق المحفوظة بشكل منفصل فمجلد محلي ما كتعاوضش النسخ الاحتياطية ديال قاعدة البيانات. لذلك هاد الوضع مناسب للتجربة السريعة وماشي للحفاظ على المشاريع مدة طويلة.

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

استعمال PostgreSQL ديال التطوير

من بعد تثبيت Docker وتشغيله فالحاسوب، تقدر تستعمل الأوامر التالية لتشغيل قاعدة بيانات خاصة بالتطوير والخدمات الأساسية:

npm run dev:postgres

هاد الطريقة كتخزّن قاعدة البيانات فحجم Docker. بيانات الدخول الموجودة فالسكريبت مخصّصة غير للتطوير المحلي، وفبيئة الإنتاج خاصها تتبدل؛ وما تستعملش قاعدة بيانات كاملة موجودة من قبل مباشرة كقاعدة بيانات لنسخة المجتمع.

ربط PostgreSQL موجودة من قبل

إلا كانت PostgreSQL واجدة، نسخ ملف .env.example الموجود فالمجلد الجذر إلى .env، ومن بعد عيّن DATABASE_URL وUML_PROVIDER_CONFIG_SECRET اللي ولّدتيه بنفسك:

cp .env.example .env

من بعد ما تكمل الإعداد، عاود شغّل npm run dev. حافظ مزيان على مفتاح التشفير، حيث التبديل العشوائي ديال UML_PROVIDER_CONFIG_SECRET غادي يمنع فك تشفير بيانات اعتماد مزوّد النماذج المحفوظة. معلومات الاتصال بقاعدة البيانات والمفاتيح ما خاصهاش تدخل لـ Git.

تفعيل OnlyOffice

إلا بغيتي تحرّر الوثائق عبر الإنترنت، شغّل محرك Docker أولاً، ومن بعد نفّذ:

npm run dev:full

هاد السكريبت كيفحص OnlyOffice فـالمنفذ المحلي 8080؛ إلا ما كانتش الخدمة متاحة، غادي ينشئ أو يشغّل الحاوية المناسبة، وممكن أول تشغيل يحتاج تحميل الصورة. الخدمات الأساسية بوحدها تقدر تولّد وتحمل الوثائق، أما التحرير عبر الإنترنت كيحتاج إعداد OnlyOffice إضافي.

إعداد خدمة نماذج الذكاء الاصطناعي

1. شغّل خدمة Web ودخل للحساب.
2. دخل لإعدادات الحساب وزيد Provider متوافق مع OpenAI.
3. عمر HTTPS Base URL وAPI Key ديال مزوّد النماذج.
4. نفّذ اكتشاف النماذج واختبار الاتصال.
5. اختار نموذج متاح كنموذج افتراضي.

فبيئة النشر الذاتي، كتستعمل خدمة النماذج ديالك، ومصاريف الاستعمال كتتخلص للمزوّد المعني. فبيئة الإنتاج خاص استعمال قاعدة بيانات دائمة ومفتاح لتشفير بيانات الاعتماد، مع تعطيل زائر التطوير ومدخل التراجع legacy للنص الصريح.

إنجاز نمذجة لنظام حجز مقاعد المكتبة

هادي حالة بسيطة كمثال: الطالب كيدخل، وكيقلب على المقاعد الخاوية، وكيختار التاريخ والفترة الزمنية وكيقدّم الحجز؛ وما يمكنش لنفس الطالب يدير حجز مكرر فنفس الفترة؛ ومن بعد نجاح الحجز كيتبعث إشعار؛ والإداري يقدر يسيّر المقاعد، ويشوف سجل الحجوزات، ويتعامل مع الإلغاءات الاستثنائية.

الخطوة 1: إنشاء المشروع وتأكيد قواعد المتطلبات

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

الخطوة 2: إكمال تحليل الجدوى

كمّل التحليلات الثلاثة التالية وفق مسار المشروع:

• مخطط بيئة النظام: تحديد الحدود والتفاعلات بين الطالب والإداري وخدمة الإشعارات ونظام الحجز.
• مخطط سير العمل التجاري والنظامي: ترتيب مسار البحث عن المقاعد، وتقديم الحجز، وإرسال الإشعار، ومعالجة الإلغاء الاستثنائي.
• حل التنفيذ: مقارنة الحلول المرشحة وتسجيل التكاليف والمنافع والمخاطر.

من بعد إكمال التحليل، راجع أولاً واش حدود النظام وسير العمل منسجمين مع المتطلبات الأصلية، ومن بعد دوز لمرحلة توليد النماذج.

الخطوة 3: توليد نموذج المتطلبات ونموذج التصميم

المنصّة تقدر تولّد نموذج متطلبات كامل انطلاقاً من المتطلبات المؤكدة، وكيشمل البنية الوظيفية، وسير العمل التجاري العام، وحالات الاستخدام، والمفاهيم المجالّية، وعلاقات واجهات النماذج الأولية، ومتطلبات النشر. من بعد تأكيد نموذج المتطلبات، كتولّد نموذج التصميم حسب العلاقات القبلية، بحال البنية العامة، وتنفيذ حالات الاستخدام، وأصناف التصميم، والتنقل بين الصفحات، وقاعدة البيانات، وعلاقات المكوّنات، وتصميم النشر.

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

الخطوة 4: توليد الاختبارات ومصفوفة التغطية

بالنسبة لنظام الحجز، خاصك على الأقل تراجع السيناريوهات التالية:

• الطالب يقدر يقلب على المقاعد الخاوية فالتاريخ والفترة الزمنية المحددين.
• الطالب يقدر يقدّم حجز صحيح ويتوصل بالإشعار.
• إلا حاول نفس الطالب يحجز مرة أخرى فنفس الفترة، النظام يقدر يرفض الطلب.
• إلا ما كان حتى مقعد خاوي، أو كانت الفترة الزمنية غير صحيحة، أو كانت معلومات الحجز ناقصة، النظام يقدر يعالج الحالة الاستثنائية.
• الإداري يقدر يسيّر المقاعد، ويشوف سجل الحجوزات، ويتعامل مع الإلغاءات الاستثنائية.

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

الخطوة 5: توليد الوثائق الهندسية

من بعد إكمال تحليل الجدوى ونموذج المتطلبات ونموذج التصميم، تقدر تولّد ثلاثة أنواع ديال الوثائق الهندسية: تقرير دراسة الجدوى، ووثيقة مواصفات المتطلبات، ووثيقة تصميم البرمجيات. من بعد التوليد، راجع واش النصوص والرسومات منسجمة، وعدّل حسب قالب المؤسسة ومتطلبات التنسيق، ومن بعد دير إدارة الإصدارات وحمّل DOCX.

طريقة التعامل مع تغييرات المتطلبات

مثلاً، المشروع بدّل القاعدة من «نفس الطالب ما يقدرش يدير حجز مكرر فنفس الفترة» إلى «نفس الطالب يقدر يحجز جوج فترات كحد أقصى كل نهار». ما تبدلش غير جملة وحدة فالوثيقة، ولكن راجع عبر علاقات المصدر والاعتماد:

1. حفظ قاعدة المتطلبات الجديدة وأكّدها.
2. فتح علاقات المصدر وتأثير التغيير، وشوف المتطلبات وحالات الاستخدام والتصميم ومنتجات الاختبار المتأثرة.
3. حدّث نموذج المتطلبات ونموذج التصميم حسب ترتيب الاعتماد.
4. عاود راجع قيود قاعدة البيانات، وسير العمل التجاري، ومعالجة الحالات الاستثنائية.
5. حدّث حالات الاختبار ومصفوفة التغطية، ونفّذ اختبارات الانحدار فالنظام الحقيقي.
6. عاود ولّد أو راجع الوثائق المرتبطة، وخلي سجل الإصدارات محفوظ.

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

ربط Coding Agent خارجي

نسخة المجتمع تقدر، من طرف المسؤول على النشر، تفعّل ربط MCP للقراءة فقط، باش Coding Agent متوافق يقدر يقرا التصميم المحفوظ ضمن نطاق المشروع، وشروط القبول، والقيود الهندسية، ومعلومات الاختبار. مدخل التجربة المحلية ديال MCP موجود فالجانب فـ«المساعد البرمجي» أو فإعدادات المشروع تحت «ربط هاد المشروع»، وقبل الاستعمال خاص إكمال التثبيت والبناء.

npm run dev:mcp

هاد الربط كيوفّر الأدلة الهندسية للقراءة فقط، وما كيعوّضش مراجعة الكود، والتشغيل الفعلي، وقبول الاختبارات. وREADME كيوضح كذلك أن توافق عملاء Coding Agent الحقيقيين وقبول الكود المولّد ما زال كيتحسّن، لذلك خاص الرجوع إلى وثيقة ربط MCP أثناء الاستعمال.

أوامر التطوير الشائعة

• npm run build:packages: بناء الحزم المشتركة contracts وprompts.
• npm run build: بناء الحزم المشتركة وجميع التطبيقات.
• npm run dev:render: تشغيل خدمة تصيير PlantUML بشكل منفصل.
• npm run test:contracts: التحقق من العقود المشتركة.
• npm run test:api: تشغيل اختبارات API.
• npm run test:render: تشغيل اختبارات خدمة التصيير.
• npm run test:web: تشغيل اختبارات Web الكاملة.
• npm run typecheck:web: فحص أنواع Web.
• npm run lint:web: تنفيذ الفحص الساكن ديال Web.
• npm audit --audit-level=high: فحص التنبيهات الأمنية ديال الاعتماديات.

من بعد ما كتتبدل الحزم المشتركة، وقبل تشغيل تطبيق بشكل منفصل أو تشغيل الاختبارات، خاصك أولاً تنفّذ npm run build:packages. مخرجات البناء، وإعدادات البيئة، والمفاتيح الخاصة، والسجلات، وبيانات التشغيل المحلية خاصها تبقى ضمن نطاق الملفات المتجاهلة فـGit.

نظرة عامة على البنية

المشروع كيستعمل بنية متعددة التطبيقات وحزم مشتركة:

• apps/web: مساحة عمل وصفحات React وNext.js.
• apps/api: واجهة Fastify API، المصادقة، سلسلة التوليد، سجلات التشغيل وتجميع الوثائق.
• apps/render-service: عرض الرسومات ديال PlantUML.
• packages/contracts وpackages/prompts: العقود المشتركة وتعليمات التوليد.
• packages/harness-e2e وpackages/harness-eval: اختبارات القبول وتقييم الجودة.

ملاحظات على النشر والاستعمال

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

الخلاصة

SoftJL Community مناسبة للمطورين اللي باغين ينظمو مشروع التخرج ولا المشروع الدراسي ديالهم وفق منهجية هندسية. من بعد تثبيت البيئة وإعداد قاعدة البيانات والنماذج، تقدر تنطلق من قواعد المتطلبات وتولّد بالتدريج تحليل الجدوى، نماذج UML ديال المتطلبات والتصميم، تغطية الاختبارات ووثيقة المشروع، مع تتبع نطاق التأثير ملي كتتبدل المتطلبات.

كتعاون على التقليل من تشتت المواد وتكرار تنظيمها، ولكن ما كتعاوضش الحكم التصميمي البشري، تنفيذ الكود، الاختبارات الحقيقية والتحضير النهائي للمناقشة. من الأفضل اعتبار المحتوى اللي كتولدو المنصة مسودة هندسية قابلة للتتبع ومرجعاً للمراجعة، مع دمجو مع متطلبات المؤسسة ونتائج تشغيل النظام الفعلية باش يكتمل التسليم النهائي.