إدارة الكود القديم والديون التقنية

واقع الكود القديم

كل قاعدة كود تعيش طويلاً تراكم ديونًا تقنية:

• أنماط واعتماديات قديمة
• اختبارات وتوثيق مفقود
• إصلاحات سريعة أصبحت دائمة
• فقدان المعرفة مع مغادرة المطورين

مساعدو الذكاء الاصطناعي قيّمون بشكل خاص هنا—يمكنهم تحليل كود غير مألوف بدون الإحباط الذي يختبره البشر.

فهم الكود القديم

توليد التوثيق من الكود

claude "هذا الملف ليس له توثيق. حلله وأنشئ:
1. نظرة عامة على الوحدة
2. تعليقات JSDoc لكل دالة
3. قائمة بالمشاكل أو المخاطر المحتملة"

الذكاء الاصطناعي ينتج توثيقًا:

/**
 * وحدة معالجة الطلبات
 *
 * تتعامل مع دورة حياة الطلب الكاملة من السلة إلى التنفيذ.
 * كُتبت أصلاً في 2019، تستخدم أنماط callback.
 *
 * المشاكل المعروفة:
 * - لا استرداد أخطاء لفشل الدفع
 * - المخزون غير محجوز حتى اكتمال الدفع (حالة سباق)
 * - معدلات ضريبة ثابتة في الكود (يجب استخدام TaxService)
 *
 * @module services/order
 * @deprecated فكر في الهجرة إلى OrderServiceV2
 */

/**
 * ينشئ طلبًا جديدًا من سلة المستخدم
 *
 * @param {string} userId - المستخدم الذي يضع الطلب
 * @param {Cart} cart - كائن السلة مع العناصر
 * @param {function} callback - يُستدعى مع (error, order)
 *
 * @warning لا يتحقق من عناصر السلة مقابل المخزون الحالي
 * @warning حساب الضريبة ثابت عند 8.5%
 */
function createOrder(userId, cart, callback) {
  // ... الكود الموجود
}

إنشاء نظرات عامة معمارية

claude "هذا monolith Rails عمره 10 سنوات. أنشئ وثيقة
هندسة معمارية عالية المستوى تُظهر:
1. المكونات الرئيسية ومسؤولياتها
2. تدفق البيانات بين المكونات
3. التكاملات الخارجية
4. مشاكل الهندسة المعمارية المعروفة"

تحديد الديون التقنية

اكتشاف الديون الآلي

claude "حلل قاعدة الكود هذه للديون التقنية. ابحث عن:
1. الاعتماديات المهجورة
2. كود منسوخ (انتهاكات DRY)
3. الدوال أكثر من 50 سطر
4. الملفات بدون تغطية اختبار
5. تعليقات TODO/FIXME/HACK
6. الاعتماديات الدائرية"

الذكاء الاصطناعي ينتج جرد الديون:

# جرد الديون التقنية

## حرج (يمنع النشر)
- [ ] lodash@3.10.1 لديه ثغرات معروفة (CVE-2021-23337)
- [ ] moment.js مهجور، وُجد 847 استخدام

## عالي (أصلح خلال السبرنت)
- [ ] 23 دالة تتجاوز 50 سطر (انظر الملحق)
- [ ] 12 ملف بتغطية اختبار 0% (منطق الأعمال الأساسي)
- [ ] اعتمادية دائرية: payment ↔ order ↔ inventory

## متوسط (خطط للربع القادم)
- [ ] 156 تعليق TODO، أقدمها من 2021
- [ ] 34 تعليق HACK تشير إلى حلول بديلة
- [ ] 89 حالة كود تحقق منسوخ

## منخفض (تتبع لكن لا تُعطِ أولوية)
- [ ] اتفاقيات تسمية غير متسقة (camelCase vs snake_case)
- [ ] 12 تصدير غير مستخدم
- [ ] تعليقات JSDoc قديمة (45 دالة)

## الديون حسب الدليل
- src/services/: 34% من إجمالي الديون
- src/legacy/: 28% من إجمالي الديون
- src/utils/: 18% من إجمالي الديون

تحديد أولويات سداد الديون

claude "بناءً على جرد الديون، أنشئ خطة
إعادة هيكلة مُرتبة حسب الأولوية. اعتبر:
- مخاطر كل عنصر
- الجهد المطلوب
- قيمة الأعمال
- الاعتماديات بين العناصر"

استراتيجيات إعادة الهيكلة الآمنة

نمط Strangler Fig

claude "ساعدني في تطبيق نمط Strangler Fig لاستبدال
OrderService القديم. أنشئ خطة تـ:
1. تحدد جميع مستهلكي OrderService
2. تنشئ واجهة OrderServiceV2 جديدة
3. تهاجر المستهلكين تدريجيًا
4. تحافظ على التوافق العكسي"

الذكاء الاصطناعي ينشئ خطة الهجرة:

# هجرة Strangler Fig لـ OrderService

## المرحلة 1: إنشاء Facade (الأسبوع 1)
1. أنشئ OrderServiceFacade يُغلف OrderService
2. أضف علم ميزة: USE_ORDER_V2
3. حدث جميع 34 مستهلك لاستخدام facade
4. انشر وتحقق من عدم تغير السلوك

## المرحلة 2: بناء الخدمة الجديدة (الأسبوع 2-3)
1. أنشئ OrderServiceV2 بأنماط حديثة
2. أضف مجموعة اختبارات شاملة
3. نفذ نفس واجهة facade

## المرحلة 3: الهجرة التدريجية (الأسبوع 4-6)
1. فعّل V2 للمستخدمين الداخليين (علم ميزة)
2. راقب الأخطاء، قارن المخرجات
3. فعّل لـ 10% ← 50% ← 100% من المستخدمين
4. احتفظ بـ V1 كاحتياطي

## المرحلة 4: التنظيف (الأسبوع 7)
1. أزل علم الميزة
2. أزل facade
3. احذف OrderService القديم
4. حدث التوثيق

## خطة التراجع
في أي مرحلة، عطّل علم USE_ORDER_V2 لـ
الرجوع فورًا للسلوك القديم.

اختبار التوصيف

claude "هذه الدالة القديمة ليس لها اختبارات. أنشئ اختبارات
توصيف تلتقط سلوكها الحالي حتى نتمكن من إعادة الهيكلة بأمان."

// الذكاء الاصطناعي يولد اختبارات توصيف
describe('createOrder (توصيف قديم)', () => {
  // هذه الاختبارات توثق السلوك الحالي، ليس السلوك المرغوب

  it('يُرجع طلب بـ ID مولد تلقائيًا', () => {
    const result = createOrder(user, cart);
    expect(result.id).toMatch(/^ORD-\d{8}$/);
  });

  it('يطبق معدل ضريبة ثابت 8.5%', () => {
    const cart = { items: [{ price: 100 }] };
    const result = createOrder(user, cart);
    expect(result.tax).toBe(8.5); // دين معروف: يجب استخدام TaxService
  });

  it('يتجاهل بصمت العناصر غير الصالحة بدلاً من الفشل', () => {
    const cart = { items: [{ price: -50 }] }; // غير صالح
    const result = createOrder(user, cart);
    expect(result.items).toEqual([]); // سلوك غريب يجب الحفاظ عليه
  });

  it('يستخدم نمط callback للعمليات غير المتزامنة', (done) => {
    createOrder(user, cart, (err, order) => {
      expect(err).toBeNull();
      expect(order).toBeDefined();
      done();
    });
  });
});

أنماط التحديث

هجرة TypeScript التدريجية

claude "ساعدني في إضافة TypeScript لملف JavaScript هذا.
أنشئ أنواع بناءً على:
1. كيف تُستدعى الدوال
2. ما ترجعه
3. استجابات API الخارجية
اجعله تدريجيًا—استخدم 'any' للأنواع غير المؤكدة."

تحديث الاعتماديات

claude "حدث اعتمادياتنا بأمان:
1. اذكر جميع الحزم القديمة
2. حدد التغييرات المعطلة بين الإصدارات
3. أنشئ خطة هجرة مع اختبارات
4. أشر للحزم التي تحتاج تغييرات كود"

# خطة تحديث الاعتماديات

## تحديثات آمنة (بدون تغييرات كود)
```bash
npm update axios lodash-es date-fns

تغييرات كود طفيفة مطلوبة

• react-query@3 ← @tanstack/react-query@5
  • 12 ملف تحتاج تحديث استيرادات
  • أسماء Hooks لم تتغير
  • الذكاء الاصطناعي يمكنه الإصلاح التلقائي

هجرة كبرى مطلوبة

• redux@4 ← zustand@4
  • إعادة كتابة كاملة للـ store
  • 45 مكون متصل
  • نوصي بهجرة مرحلية

## إنشاء مسار مستدام

### إنشاء إرشادات التحديث

```bash
claude "أنشئ قسم CONTRIBUTING.md عن الديون التقنية:
1. كيف تحدد الديون أثناء العمل
2. كيف توثق ديون جديدة
3. متى تكون الديون مقبولة
4. كيف تُعطى الديون أولوية للإصلاح"

تتبع التقدم

claude "قارن ديوننا التقنية من 3 أشهر مضت
إلى اليوم. أظهر:
- عناصر الديون المحلولة
- الديون الجديدة المُدخلة
- الصافي التغيير
- سرعة تخفيض الديون"

ملخص الوحدة

لقد تعلمت:

• إدارة السياق بفعالية في قواعد الكود الكبيرة
• التنقل وفهم الكود غير المألوف
• تحديد الديون التقنية وترتيب أولوياتها
• إعادة هيكلة الكود القديم بأمان بمساعدة الذكاء الاصطناعي

بعد ذلك، سنغطي تقنيات التصحيح وإعادة الهيكلة المتقدمة—استخدام الذكاء الاصطناعي لحل المشاكل المعقدة. :::