اصطلاح — كتالوج المساعدات

ما هو

المجموعة الصغيرة من أصناف المساعدة/الامتداد المشتركة المُستخرَجة أثناء عمل CRUD البيانات المرجعية (MIQ-131/132/133) التي ينبغي لمطوّر يبني الميزة التالية أن يعيد استخدامها بدلًا من إعادة تنفيذها. استُخرِج كلٌّ من ازدواجية ملحوظة، لا حاجة متوقَّعة — انظر انضباط §G — فالكتالوج قصير عمدًا.

متى يُستخدم

مدّ يدك إلى هذه عند بناء ميزة CRUD بيانات مرجعية (أو أي متحكّم يُرجِع ProblemDetails / أي خدمة تحذف ناعمًا). لا تمدّ أشكالها المقفلة؛ إن لم تلائم حالتك، أبقِ شيفرتك مضمّنة.

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

Helper	File	What it does
`SoftDeleteExtensions`	`Application/Common/SoftDeleteExtensions.cs`	`MarkDeleted(this AuditableEntity, string actor, DateTimeOffset now)` — يضبط `IsDeleted=true`، `DeletedAt`، `DeletedBy`، `IsActive=false` في استدعاء واحد. يستخدمه كل مسار حذف للبيانات المرجعية.
`ControllerProblemExtensions`	`API/Common/ControllerProblemExtensions.cs`	مصنع RFC 7807 ProblemDetails: `Problem400(detail)`، `ToValidationProblem(validationResult)`، و`ProblemWithCode(status, title, detail, extensions)` لاستجابات 409 ذات الـ `code` المُهيكل.
`ExceptionPredicates`	`API/Common/ExceptionPredicates.cs`	مُسنِدا `IsNotFound()` / `IsDuplicate()` على `InvalidOperationException`، لربط `catch (… ex) when (ex.IsDuplicate())` بالحالة الصحيحة.
`SystemRowProtectedException<T>`	`Application/Common/SystemRowProtectedException.cs`	حارس صف-النظام العام (MIQ-133 المرحلة Phase 1، استخراج قاعدة-الثلاثة PB-085): `(T entity, string code, string localizedMessage)`، يحمل `Entity` و`Code`. انظر الاستثناءات.

مساعدات الواجهة الأمامية

Helper	File	What it does
`createLookupHooks`	`web/src/lib/createLookupHooks.ts`	مصنع React Query: بإعطائه `{ resourceKey, api: { list, get, create, update, delete } }`، يُرجِع `{ keys, useList, useDetail, useCreate, useUpdate, useDelete }`. كل ملفات hooks البيانات المرجعية السبعة تستهلكه.
`DeleteConfirmDialog`	`web/src/components/common/DeleteConfirmDialog.tsx`	نافذة تأكيد حذف مشتركة. تأخذ مرجع hook طفرة-الحذف + `rowId` + `testIdPrefix`؛ تعرض أجسام 409 من الخادم بـ `whitespace-pre-line` بحيث تحفظ رسائل "referenced by" متعدّدة الأسطر فواصل أسطرها.
`extractErrorMessage`	`web/src/lib/apiError.ts`	يسحب بأمان الرسالة المُوجَّهة للمستخدم من خطأ Axios (`response.data.detail` ?? `message` ?? null). يستخدمه كل حوار.

كيف تتلاءم معًا

حذف بيانات مرجعية نموذجي: تعرض الصفحة DeleteConfirmDialog، مُمرِّرةً طفرة useDelete<Entity>() (من مصنع createLookupHooks) وtestIdPrefix. عند التأكيد، تستدعي الطفرة الـ API؛ يعود 409 من ProblemWithCode على الخادم؛ يُظهِر extractErrorMessage الـ detail المُوطَّن؛ يعرضه الحوار مع حفظ فواصل الأسطر.

مزالق / قيود

أشكال المصنع والحوار مقفلة (قرار MIQ-131 رقم 39). إذا احتاج كيان مستقبلي معاملًا سابعًا أو فعلًا مختلفًا، لا تمدّ المساعد — أبقِ hooks/حوار ذلك الكيان مضمّنين، أو قسّم التجريد. فرض معامل على الشكل المشترك هو فشل التجريد المتسرّب الذي يوجد انضباط §G لمنعه.
useSkillsAdmin يستخدم resourceKey: 'skills-admin' لتقسيم cache React Query الخاص به بعيدًا عن سطح المهارات الإنتاجي — مثال على نمط التعايش.
بلغ SystemRowProtectedException<T> الكتالوج عند ثلاثة مستهلكين حقيقيين، لا قبل — عتبة قاعدة-الثلاثة (MIQ-133، PB-085). بعض أنماط الأربعة-مستهلكين (StringBuilder الخاص بـ ComposeReferencedBody) لم تُستخرَج عمدًا لأن المضمّن لا يزال يُقرأ أنظف.

حالة البناء

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