الدرس 24 · الوحدة 10: إنشاء مستندات دقيقة للمواصفات الوظيفية والتقنية

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

كيف تجمع قرارات التصميم في مستند تقني دقيق يبدأ منه المطورون التنفيذ دون تخمين؟ ⏱ نحو 45 دقيقة.

بعد هذا الدرس ستستطيع أن:

تعدّد أقسام المستند التقني ومصدر كل قسم من مخرجات التصميم.
توصّف واجهة API بجدول وتقرأ صيغة OpenAPI.
تربط كل متطلب غير وظيفي بقرار تصميم وطريقة تحقق.
تتحقق من اكتمال التصميم بإحالة كل جزء إلى متطلب.

١من «ماذا» إلى «كيف»

المستند التقني (يسمى أيضًا مستند التصميم SDD أو المواصفات التقنية) يجيب: كيف سننفذ ما في SRS؟ قارئه الفريق التقني، وهدفه أن يبدأ المطورون العمل بالتوازي دون أن يخمّن أحدهم. من الخطة: «تحويل المواصفات الوظيفية بعد توثيقها وتحليلها إلى مواصفات تقنية تتضمن الأدوات واللغات وهيكلية البرمجيات بنسبة اكتمال لا تقل عن 95%».

القسم	محتواه	صنعناه في
1. نظرة عامة	ملخص النظام والإحالة إلى SRS بإصداره	الدرس 22
2. المعمارية	مخطط الحاويات، والنمط (MVC، متجانس)، وسجلات القرار ADR	الدروس 12–14
3. التقنيات	اللغات والأطر والإصدارات وأسباب اختيارها	الدرسان 11–12
4. نموذج البيانات	ERD والجداول والأعمدة والقيود	الدرسان 8–9
5. واجهة API	كل نقطة نهاية: المسار، والجسم، والاستجابات، والصلاحية	الدرس 10
6. الأمان والصلاحيات	مصفوفة الصلاحيات، والمصادقة، وسياسات الشروط، والتدقيق	الدروس 15–21
7. تحقيق غير الوظيفي	كيف يتحقق كل NFR في التصميم	الدرس 14
8. النشر والتشغيل	البيئات، والاستضافة، والنسخ الاحتياطي، والمراقبة	—

٢توصيف واجهة API

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

الطريقة والمسار	الصلاحية	الجسم	الاستجابات	المتطلب
`GET /api/courses`	عام	—	200	FR-01.1
`POST /api/enrollments`	`enrollment:create`	`{ courseId }`	201 · 400 · 403 · 409	FR-02.2
`PATCH /api/enrollments/:id/status`	`enrollment:approve`	`{ status, reason? }`	200 · 400 · 403 · 404 · 409	FR-03.2
`GET /api/reports/finance`	`report:finance`	—	200 · 403	FR-06.1

والمقابل بصيغة OpenAPI (جزء منه):

openapi.yaml

paths:  /api/enrollments:    post:      summary: إنشاء طلب تسجيل (FR-02.2)      security: [ bearerAuth: [] ]      # يتطلب enrollment:create      requestBody:        content:          application/json:            schema: { courseId: integer }      responses:        '201': { description: أُنشئ الطلب بحالة pending }        '400': { description: courseId ناقص }        '403': { description: الدور لا يملك enrollment:create }        '409': { description: الدورة مكتملة أو تعارض BR-01 }

٣كيف يتحقق كل متطلب غير وظيفي؟

المتطلبات غير الوظيفية في SRS وعود؛ المستند التقني يقول كيف نفي بها. قسم مستقل يربط كل NFR بقرار تصميم يمكن التحقق منه:

المتطلب	قرار التصميم	كيف نتحقق
NFR-01 300 مستخدم بزمن ≤ 3 ثوانٍ	فهارس على course_id و status، وتخزين مؤقت لقائمة الدورات 60 ثانية	اختبار حمل قبل الإطلاق
NFR-03 قفل بعد 5 محاولات	عدّاد محاولات لكل حساب، وقفل 15 دقيقة	حالة اختبار آلية
NFR-04 شاشات من 360px	تصميم متجاوب بـ Tailwind، واختبار على ثلاثة مقاسات	قائمة فحص قبل كل إصدار
NFR-06 البيانات داخل المملكة	خادم وقاعدة بيانات لدى مزود محلي، ونسخ احتياطي داخلي	عقد الاستضافة

٤قواعد كتابة المستند التقني

القاعدة	لماذا؟
اذكر الإصدارات: Laravel 11، MySQL 8	سلوك الأطر يختلف بين الإصدارات
المخططات نصية `(Mermaid)` داخل المستودع	تتحدث مع الكود، وتُراجع تغييراتها كأي ملف
كل قرار مهم في ADR يُحال إليه	المستند يبقى مختصرًا، والأسباب محفوظة
أمثلة طلبات واستجابات حقيقية	تزيل الغموض أسرع من أي وصف
اتفاقيات التسمية (جداول بالجمع، و snake_case للأعمدة)	يكتب الجميع بالطريقة نفسها

توقّع وتحقّق

من القارئ الأساسي للمستند التقني؟

ما ميزة OpenAPI على الجدول؟

نقطة نهاية لا يقابلها أي متطلب. ماذا يعني ذلك؟

لماذا نذكر إصدار الإطار في المستند؟

الخلاصة

المستند التقني: نظرة عامة، ومعمارية، وتقنيات، وبيانات، و API، وأمان، وتحقيق NFR، ونشر.
API: الطريقة والمسار، والصلاحية، والجسم، وكل رموز الاستجابة، والمتطلب المرتبط.
OpenAPI صيغة معيارية تقرؤها الأدوات.
كل NFR يقابله قرار تصميم وطريقة تحقق.
الإحالة المتبادلة بين SRS والمستند التقني تكشف الزائد والناقص.

تحدٍّ تصميمي: مقاطع من المستند التقني

متقدم

اكتب ثلاثة مقاطع من المستند التقني لنظام «دورات»: نقاط نهاية API للتسجيل والاعتماد والاسترداد، وجداول نموذج البيانات، وربط ثلاثة متطلبات غير وظيفية بقرارات التصميم.

المطلوب:

ثلاث نقاط نهاية على الأقل، كل منها في سطر: الطريقة والمسار، ثم الصلاحية بصيغة مورد:فعل، ثم رمزا استجابة على الأقل.
ثلاثة جداول على الأقل، كل منها في سطر: اسم الجدول ثم «:» ثم أعمدته، ومنها مفتاح أجنبي ينتهي بـ _id.
ثلاثة متطلبات غير وظيفية بمعرّفاتها، كل منها مع قرار التصميم الذي يحققه.

✓ التحقق الآلي: يفحص المختبر بنية مستندك وصياغته (لا يحكم على جودة الفكرة؛ هذا دور معلمك)

ثلاث نقاط نهاية على الأقل
كل نقطة تبدأ بطريقة HTTP ومسار /api
كل نقطة معها صلاحية مورد:فعل
كل نقطة معها رمزا استجابة على الأقل
ثلاثة جداول على الأقل
كل جدول: الاسم ثم «:» ثم الأعمدة
مفتاح أجنبي ينتهي بـ _id
ثلاثة متطلبات غير وظيفية على الأقل
كل سطر يبدأ بمعرّف NFR
كل متطلب مع قرار تصميمه

💡 تلميح 1

ارجع إلى ERD في الدرس 9 ومصفوفة الصلاحيات في الدرس 16، ومواصفة نقطة النهاية في الدرس 10.

💡 تلميح 2

اكتب الأعمدة بالإنجليزية بصيغة snake_case: trainee_id، course_id.

💡 تلميح 3

لكل NFR اسأل: ما الذي سأبنيه أو أضبطه ليتحقق؟

نموذج واحد من إجابات كثيرة صحيحة.

نقاط النهاية (سطر لكل نقطة): POST /api/enrollments | enrollment:create | 201, 400, 409
PATCH /api/enrollments/:id/status | enrollment:approve | 200, 400, 403, 404
POST /api/enrollments/:id/refund | refund:small أو refund:any | 200, 403, 404
نموذج البيانات (سطر لكل جدول): courses: id, title, capacity, fee, trainer_id
enrollments: id, trainee_id, course_id, status, approved_by
payments: id, enrollment_id, amount, paid_at
تحقيق المتطلبات غير الوظيفية: NFR-01 ← فهارس على course_id و status وتخزين مؤقت لقائمة الدورات
NFR-03 ← عداد محاولات وقفل الحساب 15 دقيقة
NFR-06 ← استضافة الخادم وقاعدة البيانات لدى مزود محلي

انتقل إلى تقييم الدرساختيار من متعدد، وصح وخطأ، وأكمل الفراغ، وتتبّع الناتج.ابدأ التقييم ←

📝 معلم؟ أرسل ملاحظة للمؤلف عن هذا الدرس