اصطلاح — الاستثناءات وصيغة السلك `_PROTECTED` / `_REFERENCED`

ما هو

كيف تحوّل ManpowerIQ انتهاك قاعدة-نطاق (لا يمكنك حذف هذا — إنه مُشار إليه؛ لا يمكنك تحرير هذا — إنه صف نظام) إلى استجابة HTTP متّسقة: 409 Conflict RFC 7807 ProblemDetails يحمل code مُهيكلًا في امتداداته، مع جسم مُوطَّن مقروء للبشر. مُؤسَّس لكيانات CRUD البيانات المرجعية عبر MIQ-131/132/133.

متى تُستخدم

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

النمط

لا يوجد صنف أساسي DomainException في قاعدة الشيفرة هذه — ترث استثناءات النطاق مباشرةً من InvalidOperationException (تدقيق المرحلة Phase 1 لـ MIQ-133). يحمل شكلا استثناء مُسمّيان code مُهيكلًا:

Trigger	HTTP	`code`	Exception
حذف صف لا يزال مُشارًا إليه بمفاتيح أجنبية	409	`<ENTITY>_REFERENCED`	`<Entity>ReferencedException : InvalidOperationException`
تحديث/حذف صف نظام مزروع (`IsSystem = true`)	409	`<ENTITY>_PROTECTED`	`SystemRowProtectedException<T> : InvalidOperationException`
الإنشاء برمز مكرّر	409	—	`InvalidOperationException` عادي ("already exists")، مُلتقَط بمُسنِد `IsDuplicate()`
فشل التحقّق	400	—	FluentValidation، مربوط عبر `ToValidationProblem()`

<Entity>ReferencedException يحمل Id، وثابت Code ("<ENTITY>_REFERENCED")، وقاموس Referencers لعدّادات المفاتيح الأجنبية غير الصفرية. توجد أصناف فرعية لكل كيان: GradeReferencedException (مفتاح أجنبي واحد)، ShiftTemplateReferencedException (3)، SkillReferencedException (4)، TerminalReferencedException (8)، إلخ (Application/<Entity>s/<Entity>ReferencedException.cs).
SystemRowProtectedException<T> هو حارس صف-النظام العام المُستخرَج في MIQ-133 (Application/Common/SystemRowProtectedException.cs)؛ يحمل الكيان، وCode instance (مثلًا "GRADE_PROTECTED")، ورسالة مُوطَّنة مسبقًا. وُحِّدت رموز السلك إلى <ENTITY>_PROTECTED عبر كل الكيانات في المرحلة Phase 1 لـ MIQ-133 (أُعيد تركيب SYSTEM_REASON_PROTECTED التاريخي إلى DEMAND_REASON_PROTECTED).

الاستجابة. يلتقط المتحكّم الاستثناء ويستدعي المساعد المشترك ProblemWithCode(...) (انظر كتالوج المساعدات):

catch (SystemRowProtectedException<Grade> ex)
{
    return this.ProblemWithCode(
        StatusCodes.Status409Conflict,
        "System grade cannot be modified",
        ex.Message,                                   // pre-localized by the service
        new Dictionary<string, object?> { ["code"] = ex.Code });   // "GRADE_PROTECTED"
}

ينتج عنه:

{
  "status": 409,
  "title": "System grade cannot be modified",
  "detail": "This grade is a system row and cannot be modified or deleted.",
  "extensions": { "code": "GRADE_PROTECTED" }
}

يُؤلَّف الجسم في الخدمة، لا المتحكّم. تحقن الخدمة IStringLocalizer<ErrorMessages> وتبني جسم "referenced by" متعدّد الأسطر من هرمية مفاتيح resx (<Entity>.Referenced.{Header, Intro, Surface.<Table>, Footer})، مُصدِرةً فقط أسطح المفاتيح الأجنبية التي عدّادها غير صفري. يبقى المتحكّم آليًا. انظر مفاتيح i18n للواجهة الخلفية.

ترتيب الفحوص عند الحذف

حارس صف-النظام أولًا — إذا كان IsSystem، ارمِ SystemRowProtectedException<T> قبل لمس أي سطح مفتاح أجنبي. صفوف النظام غير قابلة للتغيير بغضّ النظر عن المراجع.
أسطح المفاتيح الأجنبية تاليًا — عُدّ كل جدول مُشير؛ إن كان أيٌّ منها غير صفري، ارمِ <Entity>ReferencedException مع الجسم المُؤلَّف.
وإلّا احذف ناعمًا.

مزالق / قيود

ألّف الأجسام متعدّدة الأسطر في الخدمة — لا في المتحكّم ولا في مُنشئ الاستثناء. يعيش IStringLocalizer في الخدمة.
أصدر فقط أسطر المفاتيح الأجنبية غير الصفرية — رسالة "referenced by" تسمّي بالضبط الجداول التي تحجب الحذف؛ تُحذَف الأسطح صفرية العدّ.
تقرأ الواجهة الأمامية detail، لا code — لا مستهلك أمامي يبوّب على سلسلة code، فإعادة تسمية صيغة السلك آمنة؛ code للمعالجة المُهيكلة/البرمجية.
يجب أن يضيف كيان جديد مفاتيح resx الخاصة به وإلّا رمت الخدمة خطأ مورد مفقود في وقت التشغيل عند تأليف الجسم.
Code ثابت على استثناءات Referenced، خاصية instance على SystemRowProtectedException<T> — اقرأ ex.Code للأخير.

حالة البناء

Available — حيّ عبر الكيانات السبعة للبيانات المرجعية وخدمات قواعد التخصيص (MIQ-131/132/133).

اصطلاح — الاستثناءات وصيغة السلك _PROTECTED / _REFERENCED