أنماط التنقل في قاعدة الكود

مشكلة التنقل

في قواعد الكود الكبيرة، إيجاد الكود ذي الصلة هو نصف المعركة. مساعدو الذكاء الاصطناعي يحتاجون استراتيجيات فعالة لتحديد:

• أين يتم تنفيذ ميزة
• كيف تتدفق البيانات عبر النظام
• ما الذي يعتمد على ماذا
• أين يجب إجراء التغييرات

التنقل بالبحث أولاً

البحث الدلالي مع الذكاء الاصطناعي

claude "اعثر على مكان حدوث مصادقة المستخدم في قاعدة الكود هذه.
أحتاج فهم تدفق المصادقة الكامل."

الذكاء الاصطناعي ينفذ بحثًا ذكيًا:

جارٍ البحث عن أنماط المصادقة...

تم تحديد تدفق المصادقة:

1. نقطة الدخول: src/app/login/page.tsx
   - إرسال نموذج تسجيل الدخول
   - يستدعي /api/auth/login

2. مسار API: api/src/routes/auth.ts
   - POST /login - التحقق من بيانات الاعتماد
   - POST /register - إنشاء مستخدم جديد
   - POST /logout - إنهاء الجلسة

3. طبقة الخدمة: api/src/services/auth.ts
   - validateCredentials()
   - createSession()
   - hashPassword()

4. Middleware: api/src/middleware/auth.ts
   - authenticateRequest()
   - requireRole()

5. قاعدة البيانات: packages/database/schema.prisma
   - نموذج User
   - نموذج Session

هل تريد مني قراءة أي من هذه الملفات؟

البحث القائم على الأنماط

claude "اعثر على جميع نقاط نهاية API التي تتعامل مع المدفوعات.
ابحث عن تعريفات المسارات، ليس فقط 'payment' في النصوص."

# الذكاء الاصطناعي يستخدم أنماط grep ذكية
grep -r "router\.(get|post|put|delete).*payment" api/src/
grep -r "@(Get|Post|Put|Delete).*payment" api/src/  # Decorators
grep -r "app\.(get|post|put|delete).*pay" api/src/

تتبع تدفق البيانات

متابعة طلب

claude "تتبع ما يحدث عندما ينقر المستخدم 'إتمام الطلب':
1. معالج حدث الواجهة
2. طلب API
3. معالجة الخادم
4. عمليات قاعدة البيانات
5. معالجة الاستجابة"

الذكاء الاصطناعي ينتج مخطط تدفق:

المستخدم ينقر "إتمام الطلب"
         │
         ▼
┌─────────────────────────┐
│ OrderButton.tsx:45      │
│ onClick → placeOrder()  │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ useOrder.ts:23          │
│ mutation.mutate()       │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ POST /api/orders        │
│ routes/orders.ts:67     │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ OrderService.create()   │
│ services/order.ts:112   │
├─────────────────────────┤
│ 1. التحقق من عناصر السلة│
│ 2. فحص المخزون         │
│ 3. معالجة الدفع         │
│ 4. إنشاء سجل الطلب     │
│ 5. تحديث المخزون       │
│ 6. وضع التأكيد بالقائمة │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ prisma.order.create()   │
│ database/orders.ts:45   │
└─────────────────────────┘

تتبع الاعتماديات

claude "ما الذي يستدعي دالة sendEmail؟
تتبع جميع المستدعين حتى نقاط الدخول."

التسلسل الهرمي لاستدعاء sendEmail():

services/notification.ts:sendEmail()
├── مُستدعى بواسطة: services/notification.ts:sendOrderConfirmation()
│   └── مُستدعى بواسطة: services/order.ts:create()
│       └── مُستدعى بواسطة: routes/orders.ts:POST /orders
│           └── الدخول: OrderButton.tsx ← useOrder.ts
│
├── مُستدعى بواسطة: services/notification.ts:sendPasswordReset()
│   └── مُستدعى بواسطة: routes/auth.ts:POST /forgot-password
│       └── الدخول: ForgotPasswordForm.tsx
│
└── مُستدعى بواسطة: services/notification.ts:sendWelcome()
    └── مُستدعى بواسطة: services/auth.ts:register()
        └── مُستدعى بواسطة: routes/auth.ts:POST /register
            └── الدخول: RegisterForm.tsx

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

توليد خرائط الهندسة المعمارية

claude "أنشئ رسم اعتمادية لطبقة الخدمة لدينا.
أظهر أي خدمات تعتمد على أي."

اعتماديات طبقة الخدمة:

OrderService
├── PaymentService (معالجة المدفوعات)
├── InventoryService (فحص/تحديث المخزون)
├── NotificationService (إرسال التأكيدات)
└── UserService (الحصول على تفاصيل العميل)

PaymentService
├── StripeService (معالجة الدفع)
└── OrderService (تحديث حالة الطلب) ⚠️ دائري!

InventoryService
├── ProductService (الحصول على معلومات المنتج)
└── WarehouseService (بيانات الموقع)

NotificationService
├── EmailService (إرسال البريد الإلكتروني)
├── SmsService (إرسال الرسائل النصية)
└── PushService (الإشعارات الفورية)

⚠️ تم اكتشاف اعتمادية دائرية:
OrderService ← PaymentService ← OrderService

حدود الوحدات

claude "حلل الحدود بين وحداتنا.
اعثر على حالات حيث الوحدات مرتبطة بشكل وثيق جدًا."

تحليل ارتباط الوحدات:

✅ وحدات محدودة بشكل جيد:
- auth ↔ user (واجهة نظيفة عبر UserService)
- notification ↔ * (إخراج نقي، بدون اعتماديات واردة)

⚠️ ارتباط مثير للقلق:
- order ↔ payment (دائري، 12 مرجع متقاطع)
- inventory ↔ product (15 استيراد مباشر، بدون واجهة)

❌ انتهاكات الحدود:
- routes/orders.ts يستورد مباشرة عميل prisma
  (يجب أن يمر عبر طبقة الخدمة)
- components/Cart.tsx يستورد من api/src/types
  (يجب استخدام packages/types)

التوصيات:
1. استخراج آلة حالة الدفع لكسر الاعتمادية الدائرية
2. إنشاء واجهة ProductRepository للمخزون
3. نقل استيرادات prisma لطبقة الخدمة فقط

أوامر التنقل السريع

البحث حسب المسؤولية

claude "أين نتعامل مع حجوزات المخزون؟"

claude "أي مكون يعرض الملف الشخصي للمستخدم؟"

claude "ما الذي يتحقق من أرقام بطاقات الائتمان؟"

البحث حسب النمط

claude "اعثر على جميع React hooks في هذا المشروع"

claude "أظهر لي جميع هجرات قاعدة البيانات"

claude "اذكر جميع متغيرات البيئة المستخدمة"

البحث حسب الاتفاقية

claude "بناءً على اتفاقيات التسمية لدينا، أين سيكون
منطق حساب الضريبة؟"

الذكاء الاصطناعي يستنتج من الأنماط:

بناءً على اتفاقيات مشروعك:

منطق الأعمال ← services/
الضريبة متعلقة بالمالية ← services/finance/ أو services/tax/

جارٍ التحقق...

وُجد: api/src/services/tax.ts
- calculateTax()
- getTaxRate()
- validateTaxId()

أيضًا ذو صلة:
- api/src/services/checkout.ts:applyTax() (يستخدم TaxService)
- packages/types/src/tax.ts (تعريفات الأنواع)

بناء النماذج الذهنية

طلب شروحات من الذكاء الاصطناعي

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

الذكاء الاصطناعي يقدم نظرة عامة مفاهيمية:

# هندسة التخزين المؤقت

## الاستراتيجية: القراءة عبر مع TTL

                    الطلب
                       │
                       ▼
              ┌────────────────┐
              │   مسار API    │
              └───────┬────────┘
                      │
                      ▼
              ┌────────────────┐
              │ CacheService   │
              │ cache.get(key) │
              └───────┬────────┘
                      │
           ┌──────────┴──────────┐
           │                     │
      إصابة Cache           فقدان Cache
           │                     │
           ▼                     ▼
      إرجاع البيانات      استعلام قاعدة البيانات
                                │
                                ▼
                          cache.set(key)
                                │
                                ▼
                          إرجاع البيانات

## طبقات Cache
1. في الذاكرة (LRU، 1000 عنصر) - lib/cache/memory.ts
2. Redis (موزع) - lib/cache/redis.ts

## استراتيجية TTL
- ملفات المستخدم الشخصية: 5 دقائق
- بيانات المنتج: ساعة واحدة
- المحتوى الثابت: 24 ساعة

## الإبطال
- عند الكتابة: إبطال فوري
- البث: Redis pub/sub لجميع النسخ

الخطوات التالية

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