سجلات القرارات المعمارية (Architecture Decision Records - ADRs)

سجلات القرارات المعمارية (ADRs) هي وثائق نصية خفيفة تُحفظ مباشرة داخل مستودع الكود (Git Repository) لتوثيق القرارات التقنية والهندسية، أسبابها، والنتائج المترتبة عليها.

أين تُحفظ ملفات الـ ADR بالضبط؟

تُوضع ملفات الـ ADR في مجلد مخصص داخل مشروع الكود، وغالباً ما يكون المسار docs/adr/ أو doc/architecture/decisions/. تسمية الملفات تبدأ برقم تسلسلي منظم لسهولة الترتيب الم Chronological.

سجلات القرارات المعمارية (ADRs) هي وثائق نصية خفيفة تُحفظ مباشرة داخل مستودع الكود (Git Repository) لتوثيق القرارات التقنية والهندسية، أسبابها، والنتائج المترتبة عليها.

أين تُحفظ ملفات الـ ADR بالضبط؟

تُوضع ملفات الـ ADR في مجلد مخصص داخل مشروع الكود، وغالباً ما يكون المسار docs/adr/ أو doc/architecture/decisions/. تسمية الملفات تبدأ برقم تسلسلي منظم لسهولة الترتيب الم Chronological.

Plaintext

📁 my-awesome-project/
├── 📁 src/
│   ├── 📁 controllers/
│   └── 📁 models/
├── 📁 docs/
│   └── 📁 adr/  <--- 🎯 هنا مكان ملفات الـ ADR بالضبط
│       ├── 📄 0001-record-architecture-decisions.md
│       ├── 📄 0002-use-postgresql-for-orders-database.md
│       └── 📄 0003-adopt-redis-for-caching.md
├── 📄 README.md
└── 📄 package.json

مثال عملي توضيحي (صيغة ملف Markdown)

هذا الشكل الفعلي لملف 0002-use-postgresql-for-orders-database.md:

📄 ADR 0002: استخدام PostgreSQL بدلاً من MongoDB لخدمة الطلبات

• 📅 التاريخ: 2026-08-16
  
  
• 👤 صاحب القرار: فريق الهندسة والـ Backend
  
  
• 📌 الحالة: ✅ مقبول (Accepted)
  
  

💡 السياق (Context)

مع زيادة حجم المبيعات في المتجر الإلكتروني، واجهنا مشاكل تضارب في المخزون أثناء الشراء المكثف في نفس اللحظة. قاعدة البيانات الحالية (MongoDB) لا توفر ضمانات ACID مطابقة لمتطلبات العمليات المالية المعقدة لدينا.

🎯 القرار (Decision)

سنقوم بنقل خدمة الطلبات (Orders Service) إلى قاعدة بيانات PostgreSQL.

⚖️ النتائج (Consequences)

🟢 المميزات (Pros)

• 🔒 ضمان سلامة البيانات: دعم كامل لـ ACID Transactions لمنع الأخطاء المالية.
  
  
• 📊 مرونة الاستعلامات: سهولة عمل استعلامات معقدة لتقارير المبيعات.
  
  

🔴 التنازلات والسلبيات (Cons)

• ⏳ وقت المهاجرة: يتطلب إعادة هيكلة البيانات (Data Migration) وتأهيل الفريق.
  
  
• 📐 Strict Schema: الانضباط بهيكل بيانات ثابت يتطلب حذر عند إجراء التحديثات.
  
  

دورة حياة ملف الـ ADR

Plaintext

[ 📝 مقترح (Proposed) ] ───► [ ✅ مقبول (Accepted) ]
                                    │
                                    ▼ (عند تغيير الظروف مستقبلاً)
                             [ 🔄 مُستبدل (Superseded) ]

• عدم التعديل: الملف المقبول لا يُعدل كوده أبدًا.
  
  
• التحديث: عند اتخاذ قرار جديد يرفض أو يغير القرار القديم، نُنشئ ملفاً جديداً (مثلاً 0015-migrate-to-dynamodb.md) ويشار فيه إلى أنه يحل محل 0002.