انتقل إلى المحتوى

اصطلاح — قالب CRUD للبيانات المرجعية

ما هو

الوصفة القابلة للتكرار لإضافة ميزة CRUD التالية لإدارة البيانات المرجعية. أنضجت ManpowerIQ هذا القالب عبر سبعة كيانات بيانات مرجعية — ShiftTemplate، Holiday، DemandReason، NodeType، Terminal، Grade، Skill — عبر الجولات MIQ-131 وMIQ-132 وMIQ-133. اتّباعه يعني أن قائمة مرجعية جديدة تحصل على API متّسق بخمسة أفعال، وحذف ناعم، وحماية المفاتيح الأجنبية، وi18n ثنائي اللغة، وصلاحيات RBAC، وشاشة إدارة React مطابقة، دون مفاجآت.

متى تُستخدم

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

الوصفة

1. تدقيق تمهيدي (افعل هذا أولًا). قبل كتابة الشيفرة، أكّد الشكل (تقارير MIQ-131/132/133، أقسام "pre-flight"):

  • صنف الكيان الأساسي — TenantEntity (محصور بوحدة العمل) مقابل AuditableEntity (عام). أحفاد AuditableEntity يحتاجون HasQueryFilter(x => !x.IsDeleted) صريحًا في إعداد DbContext وإلّا تسرّبت الصفوف المحذوفة ناعمًا إلى القوائم؛ أحفاد TenantEntity يرثون المرشّح المركزي (قرار MIQ-132 رقم 46).
  • كل مفتاح أجنبي يشير إلى هذا الكيان — كلٌّ منه سطح "referenced" منفصل لعدّه لحجب الحذف (انظر الخطوة 3).
  • قابلية الاسم العربي للعدم — وهي لكل كيان، لا عامة (4 من 7 كيانات تتطلّب Name_2_Arabic؛ DemandReason يتركه اختياريًا). دقّقه مستقلًّا؛ لا تنسخ الكيان السابق نسخًا عامًا أبدًا (قرار MIQ-131 رقم 40؛ قرار MIQ-132 رقم 47).
  • يجب أن يحمل فهرس code الفريد WHERE is_deleted = false بحيث يمكن إعادة استخدام رمز بعد حذف ناعم (امتثال PB-043).

2. الواجهة الخلفية. اعكس شكل كيان قائم (Grade هو المثال القانوني بمفتاح أجنبي واحد):

  • Application/<Entity>s/ — I<Entity>Service (الأفعال الخمسة)، <Entity>Dtos (ListItem / Detail / CreateRequest / UpdateRequest — بلا حقل Code على UpdateRequest، الرمز غير قابل للتغيير)، ثوابت نوع-الحدث، و<Entity>ReferencedException إن أمكن حجب الحذف بمفتاح أجنبي.
  • Infrastructure/Services/<Entity>s/<Entity>Service — ينفّذ الواجهة؛ يحقن IAuditLogger، وICurrentTenantProvider، وIStringLocalizer<ErrorMessages> (تؤلّف الخدمة أجسام الرسائل المُوطَّنة — يبقى المتحكّم آليًا). يستدعي الحذف SoftDeleteExtensions.MarkDeleted(...).
  • API/Controllers/<Entity>sController — مسار /api/admin/<entity-plural>، خمسة أفعال كلٌّ [Authorize(Policy = "<entity>.view")] / ".config"، باستخدام المساعدات المشتركة (انظر كتالوج المساعدات).
  • API/Validation/<Entity>Validators — مُتحقِّقات FluentValidation للإنشاء/التحديث، مُسجَّلة تلقائيًا.
  • سجّل services.AddScoped<I<Entity>Service, <Entity>Service>() في Program.cs.

3. حماية الحذف. حارسان، بهذا الترتيب: ارفض إذا كان الصف IsSystem (صف نظام مزروع)، ثم عُدّ كل سطح مفتاح أجنبي وإن كان أيٌّ منها غير صفري، ارمِ <Entity>ReferencedException (409). انظر الاستثناءات.

4. مفاتيح i18n. أضف مفاتيح الكيان إلى كلٍّ من ErrorMessages.resx وErrorMessages.ar.resx بالتوازي، متّبعًا اصطلاح مفاتيح i18n للواجهة الخلفية: <Entity>.IsSystem.Body، <Entity>.Referenced.{Header, Intro, Surface.<Table>, Footer}، <Entity>.Validation.<Rule>.

5. الهجرة. ازرع الصلاحيتين (<entity>.view، <entity>.config) بـ category = "Reference Data"؛ أضف هجرة الفهرس الفريد الجزئي إن كان فهرس الرمز يفتقر إلى مرشّح is_deleted = false.

6. الواجهة الأمامية. api/<entity-plural>.ts (خمسة مُغلِّفات) → ملف hook يستهلك مصنع createLookupHooks → <Entity>Table + حوار → صفحة تستخدم DeleteConfirmDialog المشترك → مدخل مسار + SideNav تحت Reference Data → مفاتيح en.json/ar.json بتكافؤ. انظر كتالوج المساعدات للمصنع والحوار.

7. الاختبارات. اختبار عرض/صلاحية (ويب) يؤكّد تكافؤ مفاتيح en/ar؛ واختبار تكامل يستخدم نمط ملكية try/finally لحجب المفتاح الأجنبي (انظر أنماط الاختبار).

مزالق / قيود

  • code غير قابل للتغيير عند التحديث — مُنفَّذ بحذفه من UpdateRequest؛ تُعطِّل الواجهة الأمامية الإدخال كدعم بصري فقط.
  • تؤلّف الخدمة الجسم المُوطَّن، لا المتحكّم — يُحقَن IStringLocalizer<ErrorMessages> في مُنشئ الخدمة؛ يكتفي المتحكّم بربط الاستثناء المُلتقَط بـ 409 مع الرمز.
  • لا تربط فحوص المفتاح الأجنبي المسبقة بـ OR — عُدّ كل سطح على حدة بحيث تستطيع رسالة "referenced by" تسمية الجداول التي تحجب الحذف بالضبط.
  • قابلية العربي للعدم لكل كيان — أعد التدقيق في كل مرة؛ نسخ مُتحقِّق الكيان السابق هو الفخّ الكلاسيكي.
  • أشكال المصنع/الحوار مقفلة — إذا لم يلائم كيان جديد المصنع أو الحوار المشترك، أبقِ hooks/حوار ذلك الكيان مضمّنين بدلًا من ثني التجريد. هذا هو انضباط §G.

حالة البناء

Available — القالب حيّ عبر كل الكيانات السبعة للبيانات المرجعية (MIQ-131/132/133). إنه اصطلاح، لا إطار: لا يوجد مُولِّد، تعكس كيانًا قائمًا.

ذات صلة