SoftJL Community کا عملی رہنما: AI کے ذریعے تقاضوں، UML، ٹیسٹنگ اور دستاویزات کو مربوط کریں

SoftJL Community کیا ہے

SoftJL Community سافٹ ویئر سے متعلق گریجویشن پروجیکٹس، کورس پروجیکٹس اور UML اسائنمنٹس کے لیے آزادانہ طور پر تعینات کیا جا سکنے والا AI سافٹ ویئر انجینئرنگ ورک بینچ ہے۔ یہ تقاضوں کے تجزیے، فزیبلٹی تجزیے، UML ماڈلنگ، ڈیزائن، ٹیسٹنگ، انجینئرنگ دستاویزات اور تبدیلیوں کی ٹریکنگ کو آپس میں مربوط کرتا ہے، تاکہ آپ جانچ سکیں کہ آیا تقاضے ڈیزائن اور ٹیسٹ تک درست طور پر پہنچے ہیں، اور ترامیم، پریزنٹیشن اور دفاع کے لیے قابلِ سراغ شواہد ترتیب دے سکیں۔

کمیونٹی ایڈیشن مکمل سورس کوڈ فراہم کرتا ہے اور Apache License 2.0 کے تحت لائسنس یافتہ ہے۔ سرکاری ہوسٹڈ ایڈیشن کے مقابلے میں، کمیونٹی ایڈیشن میں سروسز، ڈیٹا بیس اور ماڈل فراہم کنندگان کا انتظام خود کرنا ہوتا ہے، تاہم اس میں تقاضوں کے قواعد کا اخراج، مکمل تقاضہ اور ڈیزائن ماڈلز، ٹیسٹ کوریج، دستاویزات کی تیاری، ماخذ کی ٹریکنگ، پروجیکٹ مینجمنٹ اور BYOK ماڈل انضمام جیسی بنیادی صلاحیتیں برقرار رہتی ہیں۔

بنیادی ورک فلو

پلیٹ فارم تقاضوں سے توثیق تک ایک انجینئرنگ سلسلے کے گرد کام کرتا ہے: پہلے تقاضے درج کر کے قواعد کی تصدیق کی جاتی ہے، پھر فزیبلٹی تجزیہ کیا جاتا ہے، تقاضہ ماڈل اور ڈیزائن ماڈل تیار کیے جاتے ہیں، اس کے بعد ٹیسٹ کیسز اور کوریج میٹرکس بنائے جاتے ہیں، اور آخر میں قابلِ تدوین و ڈاؤن لوڈ انجینئرنگ دستاویزات تیار کی جاتی ہیں۔

• تقاضوں کے قواعد: قدرتی زبان میں موجود تقاضوں سے قواعد اخذ کریں، معیار کی جانچ، نظرثانی، انسانی تصدیق اور قبولیت کی شرائط مرتب کریں۔
• فزیبلٹی تجزیہ: سسٹم ماحول کا خاکہ، کاروباری اور سسٹم فلوچارٹس، اور نفاذ کی تجاویز کا تجزیہ تیار کریں۔
• UML ماڈلز: فنکشنل ساخت، یوز کیسز، ڈومین تصورات، پروٹوٹائپ انٹرفیس، تعیناتی تقاضے، مجموعی ساخت، ڈیزائن کلاسز اور ڈیٹا بیس سمیت مختلف ماڈلز بنائیں۔
• ٹیسٹنگ اور کوریج: معمول، غیر معمول اور سرحدی حالات کے ٹیسٹ کیسز تیار کریں، اور کوریج میٹرکس و ٹریس ایبلٹی میٹرکس کے ذریعے خلا تلاش کریں۔
• انجینئرنگ دستاویزات: فزیبلٹی اسٹڈی رپورٹ، تقاضوں کی وضاحتی دستاویز اور سافٹ ویئر ڈیزائن دستاویز تیار کریں، اور ورژن مینجمنٹ و DOCX ڈاؤن لوڈ کی سہولت استعمال کریں۔
• تبدیلی کا اثر: تقاضوں، ڈیزائن، ٹیسٹس اور دستاویزات کے درمیان ماخذی تعلقات دیکھیں، اور فیصلہ کریں کہ تبدیلی کے بعد کون سی مصنوعات اپ ڈیٹ کرنی ہیں۔
• ماڈل انضمام: OpenAI سے ہم آہنگ ماڈل سروسز کو ترتیب دیں اور اپنے ماڈل فراہم کنندہ کو استعمال کریں۔

تیار کردہ نتائج انجینئرنگ شواہد کی تلاش اور ترتیب میں مدد کے لیے ہیں۔ ماڈل کی پابندیوں، خاکوں کے مواد، دستاویزات کی کاروباری مطابقت کی انسانی جانچ اب بھی ضروری ہے، اور ٹیسٹس حقیقی سسٹم میں چلائے جانے چاہییں۔

تنصیب سے پہلے ماحول کی تیاری

پہلی بار چلانے کے لیے درج ذیل ماحول تیار کریں:

• Node.js 22
• npm 10
• Java 21
• Graphviz
• اختیاری: PostgreSQL اور OnlyOffice چلانے کے لیے Docker

رینڈرنگ سروس کو پہلی بار استعمال کرتے وقت سسٹم کو 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 پر چلتی ہے۔

Web کے آؤٹ پٹ میں Ready ظاہر ہونے کے بعد 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

یہ اسکرپٹ مقامی مشین کے 8080 پورٹ پر OnlyOffice کی جانچ کرے گا؛ اگر سروس دستیاب نہ ہو تو متعلقہ کنٹینر بنائے گا یا شروع کرے گا، اور پہلی بار چلنے پر امیج ڈاؤن لوڈ کرنے کی ضرورت پڑ سکتی ہے۔ بنیادی سروس اکیلے بھی دستاویزات تیار اور ڈاؤن لوڈ کر سکتی ہے؛ آن لائن تدوین کے لیے OnlyOffice کی اضافی ترتیب ضروری ہے۔

AI ماڈل سروس ترتیب دیں

1. Web سروس شروع کریں اور اکاؤنٹ میں لاگ ان کریں۔
2. اکاؤنٹ کی ترتیبات میں جائیں اور OpenAI سے ہم آہنگ Provider شامل کریں۔
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 ضروریات اور ڈیزائن ماڈلز، ٹیسٹ کوریج اور انجینئرنگ ہدایت نامہ مرحلہ وار تیار کر سکتے ہیں، اور ضروریات میں تبدیلی کے وقت اثرات کے دائرے کا سراغ رکھ سکتے ہیں۔

یہ مواد کے منتشر ہونے اور بار بار ترتیب دینے کی ضرورت کو کم کر سکتا ہے، لیکن انسانی ڈیزائن فیصلوں، کوڈ کے نفاذ، حقیقی ٹیسٹنگ اور حتمی دفاع کی تیاری کا متبادل نہیں ہے۔ تجویز ہے کہ پلیٹ فارم سے تیار کردہ مواد کو قابلِ سراغ انجینئرنگ مسودے اور جانچ کے معیار کے طور پر استعمال کریں، اور اسکول کی ضروریات اور حقیقی نظام کے آپریشنل نتائج کے ساتھ ملا کر حتمی ترسیل مکمل کریں۔