نظام إدارة تصاريح دخول الزوار

يعتمد نظام إدارة تصاريح دخول الزوار على بنية تقنية موحدة مبنية على لغة C# وبيئة .NET 10 (LTS)، حيث يتم تطوير الخادم باستخدام إطار عمل ASP.NET Core Web API مع تطبيق نمط التحكم (Controllers) لإدارة الطلبات، بينما تعتمد واجهة المستخدم على صفحات Razor أو عرض MVC مدمجاً داخل مشروع .NET نفسه دون الحاجة إلى مشروع واجهة منفصل، مما يضمن اتساق الأداء وسهولة الصيانة. يتم إدارة البيانات عبر Entity Framework Core مع قاعدة بيانات Microsoft SQL Server في بيئة الإنتاج، مع إمكانية استخدام SQLite للتشغيل المحلي والاختبارات، وتُدار التغييرات في مخطط قاعدة البيانات عبر هجرات EF Core (Migrations) لضمان التتبع الدقيق للتحديثات. يتكون مستودع الكود من ملف حل واحد (sln) في الجذر يحتوي على مشروع التطبيق الرئيسي ومشروع اختبارات xUnit الذي يشير إلى مشروع التطبيق، مع تحديد إطار العمل المستهدف net10.0. تُنظم الملفات في مجلدات رئيسية: مجلد Controllers للتحكم في الطلبات، مجلد Views لعرض الواجهات مع بنية فرعية لكل متحكم، مجلد Data لمخرجات قاعدة البيانات والهجرات، مجلد Services لتعريف وتنفيذ الخدمات، ومجلد Infrastructure لدعم المصادقة والتطوير. قبل كتابة أي كود، يتم توثيق العقد المشترك في ملف docs/CONTRACT.md الذي يحدد أسماء الكيانات، التعدادات، أنواع النتائج المشتركة، وواجهات الخدمات مع توقيعات دوالها الدقيقة، بما في ذلك لاحقة Async وترتيب المعاملات، لضمان التوحيد في جميع الوحدات. يتبع كل وحدة قواعد صارمة: يتم تسجيل DbContext وجميع الخدمات في Program.cs باستخدام نمط AddScoped، مع إنهاء الملف بـ public partial class Program { } لتمكن الاختبارات من بدء التطبيق. يتم تسجيل HtmlEncoder مع UnicodeRanges.All لضمان عرض النصوص العربية بشكل صحيح دون ترميز. عند البحث عن سجل بمعرّف غير موجود، تعيد الدالة قيمة null ولا ترمي استثناءً، بينما تعالج الصفحات أو نقاط النهاية غير الموجودة برد 404 أو إعادة توجيه برسالة، وتجنب أخطاء الخادم. تُضبط المفاتيح والعلاقات والفهارس في OnModelCreating، وتُحدد مزود قاعدة البيانات من الإعدادات (Database:Provider) لاختيار بين SQLite وSQL Server. في بيئة التطوير والاختبارات، تُستخدم SQLite دون الحاجة إلى خادم خارجي، وتُستخدم بيانات اختبار تفي بمفاتيح الأجنبيات. تُستخدم ASP.NET Core Authentication للمصادقة، مع حماية الصفحات باستخدام [Authorize(Roles = ...)]، وقراءة بيانات المستخدم من User وليس من الترويسات. في بيئة التطوير، يُستخدم DevelopmentSignIn.cs للمصادقة عبر ترويسات X-Dev-User وX-Dev-Roles، بينما تُستخدم المصادقة الفعلية في الإنتاج. يُعامل معرّف المستخدم كنص (string) وليس رقماً، وتُستخدم await HttpContext.SignOutAsync() دون تحديد مخطط. تُعزل الأنظمة الخارجية (البريد، الرسائل) خلف واجهات، مع تسجيل الرسائل غير المرسلة في السجل دون فشل العملية. تُختبر الخدمات عبر SQLite في الذاكرة، وتُختبر الصفحات عبر WebApplicationFactory<Program> مع تسجيل الدخول بدور مسموح، مع التركيز على التحقق من فتح الصفحات وحفظ النماذج، دون اختبار الوصول أو الترميز أو الأنظمة الخارجية.