ابنِ موصلًا محدودًا وسجل أثره

حدد عمليات الموصل قبل بياناته

الموصل يترجم بين نظامين، لكنه لا يحتاج صلاحيات النظام كله. نبدأ بسؤال ما العمليات الضرورية للمشروع، ثم نحدد البيانات اللازمة لها.

في مدار نسمح read_request و create_draft و get_operation_status. لا يوجد delete_request ولا send_message في هذا الموصل التعليمي.

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

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

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

مثال محلول
المشروع يحتاج قراءة طلب، إنشاء مسودة، استعلام عملية. طالب اقترح delete_request.

الطلب
اكتب قائمة عمليات الموصل وقرار العملية المقترحة.

المخرج
مسموح:read_request/create_draft/get_operation_status. delete_request مرفوض:operation_not_allowed. لا توسيع صلاحية باقتراح النموذج.

لماذا؟
كل عملية لها احتياج.
الرفض قبل الاتصال الخارجي.
الموصل لا يقبل أسماء عمليات حرة.

حوّل الرد الخارجي لعقد داخلي ثابت

النظام الخارجي قد يسمي الحقول ticketNo و state، بينما تطبيقنا يستخدم request_id و status. الموصل يحولها بخريطة معلنة، ويتحقق من القيم.

الرد ticketNo=0017 و state=awaiting_review يتحول إلى request_id=0017 و status=pending_review حسب خريطة التدريب.

لو ظهر state جديد لا نعرفه، لا نحوله تلقائيًا إلى completed. نرجع unsupported_state ونحفظ القيمة الخام في سجل تقني محدود للمراجعة.

تحويل الحقول لا يسمح بتغيير المعنى. مثلًا closed قد تعني إغلاقًا إداريًا لا إتمام خدمة؛ لا تعتمد ترجمتها قبل مراجعة عقد المصدر.

اختبار العقد يتضمن قيمة معروفة وأخرى مجهولة. بهذا نكتشف تغييرات الطرف الآخر قبل أن تظهر كإجابات مضللة للطالب.

مثال محلول
خريطة معتمدة:awaiting_review→pending_review. الرد A:0017/awaiting_review؛ B:0018/archived_new.

الطلب
حوّل A وحدد سلوك B دون افتراض معنى جديد.

المخرج
A:{"request_id":"0017","status":"pending_review"}. B:unsupported_state؛ لا completed ولا حذف. تراجع خريطة الحالات قبل الاستكمال.

لماذا؟
التحويل له خريطة معلنة.
الحالة الجديدة لا يُخمن معناها.
رقم الطلب محفوظ.

افصل اعتماد القراءة عن الكتابة

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

قارئ الحالة يحتاج requests:read، والكاتب يحتاج drafts:create فقط. السر لا يظهر في Prompt ولا في مخرجات الطالب ولا في ملف المصدر.

ندير انتهاء الاعتماد وتغييره من إعدادات مخولة. إذا انتهى المفتاح تظهر حالة اتصال واضحة، ولا نخفض الحماية إلى الوصول المجهول كي تستمر التجربة.

البيئة التدريبية لها اعتماد مختلف عن الإنتاج، والنطاق يحدده إعداد موثوق. تغيير اسم البيئة في جسم طلب الطالب لا يختار مفتاح الإنتاج.

المثال يقدم أسماء رمزية فقط. عند تنفيذ موصل فعلي تحتاج صلاحيات مُنشأة ومختبرة؛ لا نزعم وجودها لمجرد كتابة التصميم.

مثال محلول
aliases:training_reader و training_writer. الأول read فقط؛ الثاني create_draft فقط.

الطلب
حدد أي اعتماد لكل عملية وموقف طلب تغيير environment=production.

المخرج
read_request→training_reader؛ create_draft→training_writer. البيئة من إعداد الخادم؛ تغيير body إلى production مرفوض. القيم السرية غير معروضة.

لماذا؟
فصل الصلاحيات حسب الحاجة.
لا المستخدم ولا المساعد يختار سر الإنتاج.
الأسماء الرمزية ليست اعتمادات حقيقية.

نفّذ الفحوص قبل الكتابة ثم سجل الإيصال

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

بعد السماح ينادي الموصل عملية محددة، ثم يفحص الرد ويحفظ operation_id والمرجع الخارجي والحالة والوقت. الرد 200 بلا مرجع متوقع قد يكون غير كافٍ وفق العقد.

الإيصال لا يخزن السر، ولا يعتبر نصًا حرًا يستطيع الطالب تزويره. سجل التنفيذ يأتي من المسار الموثوق ويرتبط بالطلب والمحاولة.

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

المثال يوضح شرط نجاح إنشاء مسودة:مرجع D17 مرتبط بالعملية والنسخة. إنشاء المسودة لا يعني إرسال عرض أو تنفيذ الخدمة.

مثال محلول
0017v3 معتمد؛ key ثابت؛ رد الموصل draft_id=D17 و status=created و operation_id=O17.

الطلب
اكتب إيصالًا على قدر دلالة الرد.

المخرج
O17؛ request0017؛ revision3؛ external_ref=D17؛ status=completed_for_draft_creation. لا ادعاء إرسال أو خدمة منفذة.

لماذا؟
المرجع يثبت نوع أثر محدد.
الإيصال مربوط بالنسخة والعملية.
لا يتجاوز الادعاء معنى created.

تعامل مع الأثر الخطأ بتعويض مقصود

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

في مدار المسودة D17 اتكتبت بفرع غلط. لا نحذف الطلب الأصلي أو نعدل قاعدة البيانات مباشرة؛ نراجع هل العقد يسمح بتعديل المسودة أو إلغائها.

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

بعض الآثار لا يمكن سحبها، مثل رسالة وصلت. وقتها المعالجة قد تكون رسالة تصحيح معتمدة أو تدخلًا بشريًا، وليست ادعاء rollback كامل.

المثال يتوقف عند اقتراح تعويض لأن موصلنا لا يدعم الإلغاء بعد. الصدق في حدود الأداة أفضل من زر يَعِد بإصلاح غير متاح.

مثال محلول
D17 للفرع الخطأ؛ الموصل الحالي يدعم إنشاء وقراءة فقط ولا يدعم الإلغاء.

الطلب
حدد خطة التعامل دون اختراع عملية حذف.

المخرج
أوقف أي أثر لاحق؛ سجل incident مرتبطًا D17؛ أحل المسألة للمسؤول ليصحح عبر إجراء مخول. لا تدّعِ rollback ولا تستدع delete غير موجود.

لماذا؟
حدود الموصل محفوظة.
الخطأ موثق لا مخفي.
التعويض يتطلب قدرة وصلاحية مناسبتين.

تحقق من العقد والعزل قبل التسليم

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

نضيف حالة مهلة بعد أثر وحالة رد لا يحتوي المرجع المطلوب. هذه الحالات تكشف الفرق بين اتصال يعمل وبين موصل يمكن الاعتماد عليه.

المراجعة تفحص أن السجلات لا تحتوي أسرارًا وأن عدد الآثار مطابق للمفاتيح. نحفظ أدلة مصغرة ببيانات صناعية بدل مشاركة سجل عملاء.

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

حزمة التسليم تحتوي العقد والاختبارات والقيود المعروفة والمسؤول عن الإعداد. بعدها نقدر نراقب التشغيل ونكتشف التغيرات بدل انتظار شكوى.

مثال محلول
اختبر:create_draft صحيح؛ delete غير مسموح؛ tenant خاطئ؛ state مجهول؛ مهلة بعد D17.

الطلب
اكتب نتائج مرجعية ودليلًا لكل نوع.

المخرج
الصحيح:إيصال مطابق. delete/tenant:رفض قبل الأثر. state:توقف لتحديث العقد. المهلة:استعلام يربط D17. الدليل يسمي بيئة التجربة ولا يدعي إنتاجًا.

لماذا؟
العزل جزء من الاختبار.
المهلة لها استعادة بلا مضاعفة.
حدود الدليل معلنة.