<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "d0a02cb117e91a5b5f24178080068a3d",
  "translation_date": "2025-10-22T14:21:32+00:00",
  "source_file": "7-bank-project/3-data/assignment.md",
  "language_code": "ar"
}
-->
# إعادة هيكلة الكود وتوثيق المهمة

## أهداف التعلم

من خلال إكمال هذه المهمة، ستتمكن من ممارسة مهارات تطوير البرمجيات الأساسية التي يستخدمها المطورون المحترفون يوميًا. ستتعلم كيفية تنظيم الكود لتحسين قابليته للصيانة، تقليل التكرار من خلال التجريد، وتوثيق عملك للمطورين المستقبليين (بما فيهم أنت!).

الكود النظيف والمُوثق جيدًا ضروري لمشاريع تطوير الويب الواقعية حيث يتعاون العديد من المطورين وتتطور قواعد الكود بمرور الوقت.

## نظرة عامة على المهمة

ملف `app.js` الخاص بتطبيقك البنكي أصبح كبيرًا جدًا مع وظائف تسجيل الدخول، التسجيل، ولوحة التحكم. حان الوقت لإعادة هيكلة هذا الكود باستخدام ممارسات التطوير الاحترافية لتحسين قابلية القراءة والصيانة وتقليل التكرار.

## التعليمات

قم بتحويل الكود الحالي في ملف `app.js` الخاص بك من خلال تنفيذ هذه التقنيات الثلاثة الأساسية لإعادة الهيكلة:

### 1. استخراج الثوابت التكوينية

**المهمة**: قم بإنشاء قسم تكوين في أعلى الملف يحتوي على الثوابت القابلة لإعادة الاستخدام.

**إرشادات التنفيذ:**
- استخراج عنوان URL الأساسي لـ API الخاص بالخادم (الموجود حاليًا في عدة أماكن)
- إنشاء ثوابت لرسائل الخطأ التي تظهر في وظائف متعددة
- النظر في استخراج مسارات الروابط ومعرفات العناصر التي تُستخدم بشكل متكرر

**مثال على الهيكل:**
```javascript
// Configuration constants
const API_BASE_URL = 'http://localhost:5000/api';
const ROUTES = {
  LOGIN: '/login',
  DASHBOARD: '/dashboard'
};
```

### 2. إنشاء وظيفة طلب موحدة

**المهمة**: قم ببناء وظيفة `sendRequest()` قابلة لإعادة الاستخدام تُلغي الكود المكرر بين `createAccount()` و `getAccount()`.

**المتطلبات:**
- التعامل مع طلبات GET و POST
- تضمين معالجة الأخطاء بشكل صحيح
- دعم نقاط نهاية URL المختلفة
- قبول بيانات الجسم الاختيارية للطلب

**إرشادات توقيع الوظيفة:**
```javascript
async function sendRequest(endpoint, method = 'GET', data = null) {
  // Your implementation here
}
```

### 3. إضافة توثيق احترافي للكود

**المهمة**: قم بتوثيق الكود الخاص بك بتعليقات واضحة ومفيدة تشرح "لماذا" وراء منطقك.

**معايير التوثيق:**
- إضافة توثيق للوظائف يشرح الغرض، المعلمات، وقيم الإرجاع
- تضمين تعليقات داخلية للمنطق المعقد أو القواعد التجارية
- تجميع الوظائف ذات الصلة مع عناوين الأقسام
- شرح أي أنماط كود غير واضحة أو حلول خاصة بالمتصفح

**مثال على أسلوب التوثيق:**
```javascript
/**
 * Authenticates user and redirects to dashboard
 * @param {Event} event - Form submission event
 * @returns {Promise<void>} - Resolves when login process completes
 */
async function login(event) {
  // Prevent default form submission to handle with JavaScript
  event.preventDefault();
  
  // Your implementation...
}
```

## معايير النجاح

يجب أن يُظهر الكود المُعاد هيكلته هذه الممارسات الاحترافية للتطوير:

### تنفيذ مثالي
- ✅ **الثوابت**: تم استخراج جميع النصوص السحرية وعناوين URL إلى ثوابت ذات أسماء واضحة
- ✅ **مبدأ DRY**: تم تجميع منطق الطلب المشترك في وظيفة `sendRequest()` قابلة لإعادة الاستخدام
- ✅ **التوثيق**: تحتوي الوظائف على تعليقات JSDoc واضحة تشرح الغرض والمعلمات
- ✅ **التنظيم**: الكود مُجمع منطقيًا مع عناوين الأقسام وتنسيق متسق
- ✅ **معالجة الأخطاء**: تحسين معالجة الأخطاء باستخدام وظيفة الطلب الجديدة

### تنفيذ كافٍ
- ✅ **الثوابت**: تم استخراج معظم القيم المتكررة، مع بقاء بعض القيم الصلبة
- ✅ **التجميع**: تم إنشاء وظيفة `sendRequest()` أساسية ولكن قد لا تتعامل مع جميع الحالات
- ✅ **التعليقات**: تم توثيق الوظائف الرئيسية، رغم أن بعض التفسيرات يمكن أن تكون أكثر اكتمالاً
- ✅ **قابلية القراءة**: الكود منظم بشكل عام مع وجود بعض المجالات للتحسين

### بحاجة إلى تحسين
- ❌ **الثوابت**: لا تزال العديد من النصوص السحرية وعناوين URL موجودة في الكود
- ❌ **التكرار**: لا يزال هناك تكرار كبير في الكود بين الوظائف المتشابهة
- ❌ **التوثيق**: التعليقات مفقودة أو غير كافية ولا تشرح الغرض من الكود
- ❌ **التنظيم**: يفتقر الكود إلى هيكل واضح وتجميع منطقي

## اختبار الكود المُعاد هيكلته

بعد إعادة الهيكلة، تأكد من أن تطبيقك البنكي لا يزال يعمل بشكل صحيح:

1. **اختبر جميع تدفقات المستخدم**: التسجيل، تسجيل الدخول، عرض لوحة التحكم، ومعالجة الأخطاء
2. **تحقق من طلبات API**: تأكد من أن وظيفة `sendRequest()` تعمل لإنشاء الحساب واسترجاعه
3. **اختبر سيناريوهات الأخطاء**: جرب بيانات اعتماد غير صحيحة وأخطاء الشبكة
4. **راجع مخرجات وحدة التحكم**: تأكد من عدم ظهور أخطاء جديدة أثناء إعادة الهيكلة

## إرشادات التقديم

قم بتقديم ملف `app.js` المُعاد هيكلته مع:
- عناوين أقسام واضحة لتنظيم الوظائف المختلفة
- تنسيق وتباعد الكود بشكل متسق
- توثيق JSDoc كامل لجميع الوظائف
- تعليق موجز في الأعلى يشرح نهجك في إعادة الهيكلة

**تحدي إضافي**: قم بإنشاء ملف توثيق بسيط للكود (`CODE_STRUCTURE.md`) يشرح بنية التطبيق وكيفية عمل الوظائف المختلفة معًا.

## الاتصال بالعالم الواقعي

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

المهارات التي تمارسها هنا - استخراج الثوابت، القضاء على التكرار، وكتابة التوثيق الواضح - هي أساسيات تطوير البرمجيات الاحترافية.

---

**إخلاء المسؤولية**:  
تم ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى لتحقيق الدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الموثوق. للحصول على معلومات حاسمة، يُوصى بالترجمة البشرية الاحترافية. نحن غير مسؤولين عن أي سوء فهم أو تفسيرات خاطئة ناتجة عن استخدام هذه الترجمة.