البنية التقنية
يعتمد النظام على إطار عمل .NET 10 (LTS) مع ASP.NET Core Web API وEntity Framework Core كبنية خلفية، وقاعدة بيانات Microsoft SQL Server، مع استخدام SQLite للتشغيل المحلي والاختبارات. تتكون المستودعة من ملف حل واحد (.sln) في الجذر يضم مشروع التطبيق الرئيسي ومشروع اختبارات xUnit الذي يشير إلى مشروع التطبيق، مع استهداف إطار net10.0. تُبنى الواجهات باستخدام ASP.NET Core MVC أو Razor Pages داخل مشروع التطبيق نفسه، دون مشروع واجهة منفصل، مع استخدام Bootstrap 5 للتصميم وjQuery وTypeScript لسكربتات الواجهة. يتبع كل وحدة في النظام اتفاقيات موحدة: تُعرّف الكيانات والواجهات وأنواع النتائج المشتركة في ملف docs/CONTRACT.md قبل كتابة أي كود، وتُستخدم التواقيع الدقيقة للمethods مع لاحقة Async وترتيب المعاملات كما هو محدد. يُسجَّل DbContext وجميع خدمات الواجهات في Program.cs باستخدام builder.Services.AddScoped، وينتهي الملف بـ public partial class Program { } لتمكين الاختبارات. تُسجَّل HtmlEncoder.Create(UnicodeRanges.All) كـ Singleton لضمان عرض النصوص العربية دون تحويلها إلى كيانات HTML. تُعالج الأخطاء بإرجاع 404 عند غياب السجل، ولا تُرمي استثناءات في عمليات البحث. تُهيأ المفاتيح والعلاقات والفهارس في OnModelCreating، وتُدار تغييرات المخطط عبر EF Core Migrations في مجلد Data/Migrations. تُحدد كل إجراءات المتحكمات بـ HTTP verb ومسار صريحين غير مكررين، وتُستخدم المصادقة عبر [Authorize(Roles = ...)] مع قراءة بيانات المستخدم من User وليس من الترويسات. تُعزل الأنظمة الخارجية (البريد، الدليل الوظيفي) خلف واجهات، مع تسجيل بديل محلي في بيئة التطوير. تُجرى الاختبارات ضد SQLite في الذاكرة عبر الواجهات، مع اختبار شامل يبدأ التطبيق عبر WebApplicationFactory<Program> ويتحقق من كل الصفحات والمسارات. تُوضع عارضات كل متحكم في Views/<اسم المتحكم>/، مع وجود Views/_ViewStart.cshtml وViews/_ViewImports.cshtml وViews/Shared/_Layout.cshtml، ومسار افتراضي HomeController.Index.
الوحدات البرمجية
- MOD-01وحدة الأساسيات والمخطط: تقع في مجلدات Data و Models و Common، وتُعرّف كائنات Entity Framework Core (Book, Copy, User, Loan, Reservation, Notification, EResource) مع ضبط المفاتيح والعلاقات والفهارس في OnModelCreating، وتوفر أدوات التوحيد الصوتي العربي (الهمزة، التاء المربوطة، الألف المقصورة) كدالة مشتركة، وتحتوي على واجهات الخدمات المشتركة (IEmailService, IDirectoryService) وسجل الأحداث AuditLog لتتبع هوية المنفذ والوقت.
- MOD-02وحدة الفهرس والبحث: تقع في مجلد Catalog، وتنفذ خدمة البحث في المقتنيات (ICatalogService) التي تستقبل معايير البحث (العنوان، المؤلف، الموضوع، رقم الإيداع) وتطبق دالة التوحيد الصوتي قبل الاستعلام، وتعرض حالة كل نسخة وموقعها، مع ضمان زمن استجابة أقل من ثانيتين عبر استخدام فهارس SQL Server المناسبة.
- MOD-03وحدة الإعارة والإرجاع: تقع في مجلد Circulation، وتنفذ خدمة تسجيل الإعارة (ILoanService) التي تحسب تاريخ الإرجاع آلياً وفق فئة المستفيد وترفض الطلبات المتجاوزة للحد أو التي تخص مستفيدين لديهم كتب متأخرة، وتنفيذ خدمة الإرجاع (IReturnService) التي تحدّث حالة النسخة إلى متاحة أو محجوزة خلال ثلاث ثوانٍ، مع تسجيل هوية المنفذ والوقت في سجل الأحداث.
- MOD-04وحدة الحجز وقائمة الانتظار: تقع في مجلد Reservation، وتنفذ خدمة إدارة الحجز (IReservationService) التي تتيح إضافة المستفيدين لقائمة انتظار مرتبة حسب الأسبقية، وتقوم بإشعار أول المنتظرين فورياً عند إرجاع النسخة المحجوزة، مع تحديث حالة النسخة في قاعدة البيانات.
- MOD-05وحدة الإشعارات: تقع في مجلد Notifications، وتنفذ خدمة إرسال الإشعارات (INotificationService) التي تولّد تذكيراً قبل موعد الإرجاع بيومين وإشعارات تأخير يومية، وتستخدم واجهة البريد الإلكتروني (IEmailService) لإرسال الرسائل، مع تسجيل حالة الإرسال والتاريخ في قاعدة البيانات، وتضمن عدم فشل العملية الرئيسية إذا تعذر إرسال الرسالة.
- MOD-06وحدة المصادر الإلكترونية: تقع في مجلد EResources، وتنفذ خدمة التحقق من الترخيص (IEResourceService) التي تقصر الوصول على المستفيدين المرخص لهم، وتراقب عدد النسخ المتزامنة المستخدمة مقابل الحد المسموح به في الترخيص، وترفض الطلبات التي تتجاوز هذا الحد مع تسجيل المحاولة.
- MOD-07وحدة التقارير: تقع في مجلد Reports، وتنفذ خدمة توليد التقارير (IReportService) التي تستخرج بيانات أكثر المقتنيات إعارة وطلبات الحجز غير الملباة شهرياً، وتتيح تصدير البيانات بصيغ قابلة للتصدير، مع تضمين تاريخ توليد التقرير وهوية المنفذ في المخرجات.