وثيقة مواصفات التصميم

وثيقة مواصفات التصميم

يرسم التحليل صورة واضحة عن ما يجب أن يؤديه النظام، فيما يترجم التصميم تلك الصورة إلى مخطط يحدد كيف سيُبنى. والوثيقة التي تلتقط هذا المخطط وتوصله إلى الجميع هي وثيقة مواصفات التصميم — يُشار إليها أحياناً بـ SDS أو HLD. بصرف النظر عن تسميتها، فهي المرجع الوحيد الموثوق الذي يهتدي به كل مهندس ومدير قواعد بيانات ومختبر وجهة الإدارة من لحظة الاعتماد حتى التسليم.

يتناول هذا الدرس بنية وثيقة مواصفات التصميم، والجهات التي تقرأها وما يجب أن يقدمه لها كل قسم، والمستوى المناسب من التفصيل في كل طبقة.

لماذا نحتاج وثيقة تصميم منفصلة؟

يتساءل بعض الطلاب: "لقد كتبنا بالفعل مواصفة متطلبات النظام — لماذا نكتب وثيقة كبيرة أخرى؟" والجواب بسيط: مواصفة المتطلبات تجيب على سؤال ماذا، أما وثيقة التصميم فتجيب على سؤال كيف. كلتاهما تخدم قرّاء مختلفين وتُراجَع من قِبَل أصحاب مصلحة مختلفين. الفصل بينهما يحفظ إمكانية التتبع ويتيح إدارة النطاق دون الاضطرار لإعادة كتابة كلتا الوثيقتين في كل مرة يختار فيها المعماري إطار عمل مختلفاً.

الجهات المستهدفة واحتياجاتها

وثيقة مواصفات التصميم موجَّهة لجمهور متعدد. كتابتها بإتقان تعني معرفة ما يحتاجه كل قارئ وأين يجده.

• المعماريون والمهندسون الكبار يحتاجون النظرة المعمارية الشاملة: حدود المكونات، والخيارات التقنية، ونقاط التكامل، وقرارات التصميم الكبرى مع مبرراتها.
• المطورون يحتاجون مواصفات على مستوى الوحدات: الواجهات، وهياكل البيانات، والخوارزميات، وقواعد معالجة الأخطاء — بدقة تكفي للبرمجة مباشرةً.
• مديرو قواعد البيانات يحتاجون تصميم طبقة البيانات: المخطط، وإستراتيجية الفهرسة، والتقسيم، وخطة الترحيل المستمدة من مخطط الكيانات والعلاقات.
• مهندسو ضمان الجودة يحتاجون توكيدات تصميم قابلة للاختبار: المدخلات المتوقعة والمخرجات واستجابات الأخطاء وأهداف الأداء، ليبنوا حالات الاختبار قبل كتابة سطر واحد من الكود.
• مديرو المشاريع يحتاجون مؤشرات الجهد والمخاطر: أي المكونات معقدة، وأيها لها تبعيات خارجية، وأيها تقع على المسار الحرج.
• أصحاب المصلحة من الأعمال (العملاء، أصحاب المنتجات) يحتاجون الملخص التنفيذي وتصاميم المخرجات الظاهرة للمستخدم — تخطيطات الشاشات والتقارير وعقود الواجهات الخارجية — للتحقق من أن الحل لا يزال يطابق رؤيتهم.

البنية القياسية لوثيقة مواصفات التصميم

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

جولة عبر كل قسم

1. صفحة الغلاف وسجل المراجعات وجدول المحتويات

إداري في مظهره لكنه جوهري في قيمته. يسجّل سجل المراجعات من غيّر ماذا ولماذا — أمر لا غنى عنه حين تمر الوثيقة بخمس جولات مراجعة على مدى ستة أشهر. ويخبر حقل حالة الوثيقة (مسودة / قيد المراجعة / معتمدة / مستبدَلة) أي قارئ للوهلة الأولى ما إذا كان يطّلع على نسخة أساسية حية.

2. الملخص التنفيذي ونطاق العمل

صفحة إلى صفحتين. يحدد النظام المُصمَّم، والمشكلة التجارية التي يحلها، وحدود المشروع (ما هو داخل النطاق وما هو خارجه صراحةً)، والافتراضات التي بُني عليها التصميم. بالنسبة لنظام حجز العيادة، يؤكد هذا القسم مثلاً: "يغطي التصميم بوابة الويب الخاصة بالمريض وخدمة الجدولة الخلفية. تكامل الفوترة خارج نطاق الإصدار الأول."

3. النظرة المعمارية الشاملة

القسم التقني الأكثر رجوعاً إليه. يضم مخطط السياق (كيف يتصل النظام بالجهات الخارجية)، ومخطط المكونات عالي المستوى، والأهم — سجلات قرارات المعمارية (ADRs). يوثّق كل سجل قراراً تصميمياً رئيسياً: المشكلة، والخيارات المدروسة، والخيار المُختار ومبرره. المطورون المستقبليون الذين يتساءلون "لماذا هذه خدمة مصغّرة وليست وحدة؟" سيجدون الإجابة هنا، لا في ذاكرة أحد.

4. مواصفات الوحدات والمكونات

قسم فرعي لكل مكون أو خدمة رئيسية. يغطي عادةً: المسؤوليات، والواجهة العامة، والتبعيات، والحالة الداخلية (إن وجدت)، ومعالجة الأخطاء، وخصائص الأداء. في المتجر الإلكتروني، تحدد مواصفة مكوّن خدمة الطلبات سطح واجهته البرمجية، والحالات التي يمكن أن يكون عليها الطلب، وكيفية التعامل مع انتهاء مهلة بوابة الدفع.

5. مواصفة الواجهات والواجهات البرمجية

مفصّلة بما يكفي لتمكين المطور من تنفيذ الواجهة أو استخدامها دون الحاجة للسؤال. تتضمن نقاط نهاية REST: طريقة HTTP، والمسار، ومخطط الطلب والاستجابة، والمصادقة، ورموز الأخطاء. كثيراً ما يُحال هذا القسم إلى ملف OpenAPI/Swagger بدلاً من تكرار المحتوى.

6. تصميم طبقة البيانات

مشتق مباشرةً من مخطط الكيانات والعلاقات (الدرس 5 من هذا الدليل). يضم المخطط المادي: أسماء الجداول، وأنواع الأعمدة، وقيود القيم الخالية، والفهارس، وعلاقات المفاتيح الخارجية، وأي إستراتيجية تقسيم أو أرشفة. في مثال شركة الخدمات اللوجستية، يوثّق هذا القسم كيفية تقسيم جدول shipments بحسب السنة وكيفية فهرسة جدول claims على status وcreated_at لاستعلامات لوحة المعلومات.

7. تصميم المدخلات والمخرجات

مخططات سلكية مشروحة لكل شاشة مهمة، إضافةً إلى مواصفات لكل تقرير وتصدير وإشعار. تحدد كل مخطط حقوله وقواعد التحقق من صحتها والإجراءات التي تطلقها. هذا يمنح أصحاب المصلحة من الأعمال شيئاً ملموساً ليراجعوه ويوقّعوا عليه قبل برمجة بكسل واحد.

8. التصميم غير الوظيفي

يترجم المتطلبات غير الوظيفية إلى قرارات تصميمية: معايير التشفير، وآليات المصادقة، وتحديد معدل الطلبات، وإستراتيجية التخزين المؤقت، وتكرار النسخ الاحتياطية، وطوبولوجيا النشر، وخطة المراقبة. بدون هذا القسم تبقى المتطلبات غير الوظيفية مجرد تمنيات في مواصفة المتطلبات بدلاً من توجيهات قابلة للتنفيذ.

9. مصفوفة التتبع والملاحق

تربط مصفوفة التتبع كل متطلب من مواصفة المتطلبات بالقسم (أو الأقسام) التصميمية التي تحقق متطلبه. وهي الأداة الرئيسية لفريق ضمان الجودة للتحقق من أنه لم يُفَوَّت شيء. تحتوي الملاحق على المادة الداعمة: المسرد، والمعايير المرجعية، وتراخيص المكتبات الخارجية، وسجل الأسئلة المفتوحة.

مستوى التفصيل: إيجاد العمق المناسب

من أكثر الأخطاء شيوعاً كتابة وثيقة تصميم إما شحيحة جداً (ملخص شرائح يترك المطورين في حيرة) أو ضخمة جداً (دليل من ألف صفحة لا يقرأه ولا يصونه أحد). المستوى الصحيح من التفصيل هو ما يكفي لإزالة الغموض عن القرار الذي يحتاج إلى اتخاذ.

كدليل عملي، استخدم ثلاث طبقات من التفصيل:

• عالي المستوى (معماري): أسماء المكونات، مسؤولياتها، وكيفية تواصلها. الجمهور: المعماريون. فقرة إلى فقرتين ومخطط لكل مجموعة مكونات.
• متوسط المستوى (الوحدة): عقود الواجهات، وهياكل البيانات المتبادلة بين الوحدات، وحالات الأخطاء، وانتقالات الحالة. الجمهور: المطورون. جدول نقاط نهاية واجهة برمجية أو واجهة صنف لكل وحدة.
• منخفض المستوى (خوارزمية / استعلام): فقط حين تكون الخوارزمية أو الاستعلام غير بديهيَّين — صيغة تصنيف بحثي معقدة، أو آلية تحكم في التزامن، أو إجراء ترحيل قاعدة بيانات متعدد الخطوات. في كل مكان آخر، ثِق بالمطورين.

إبقاء الوثيقة حيّة

وثيقة التصميم التي تُكتب مرة واحدة ولا تُحدَّث أبداً أسوأ من غيابها التام — فهي تضلّل المطورين الذين يثقون بها بصمت. كل تغيير تصميمي جوهري خلال مرحلة البناء يجب أن ينعكس في الوثيقة مع تحديث سجل المراجعات. تعتمد كثير من الفرق نهج الوثيقة الحية في ويكي أو مستودع Markdown بإدارة الإصدارات، بحيث تُراجَع التغييرات عبر طلب دمج بدلاً من تبادل ملفات Word عبر البريد الإلكتروني.

هيكل قالب عملي

إليك المحتوى التنظيمي الأعلى مستوى الذي تتبعه وثيقة التصميم المنظمة بشكل جيد. تُوسِّع كل بند إلى قسم مرقّم مستقل مع أقسام فرعية مناسبة:

بفهم بنية كل قسم والغرض منه، تستطيع — بوصفك محللاً ومصمماً — إنتاج وثيقة تقود فعلاً عملية البناء، بدلاً من أن تُكتب لاستيفاء متطلب إجرائي شكلي ثم لا يفتحها أحد بعد ذلك.