وصف الخصائص الوظيفية لبرنامج CShark

تحديد المثيل المقدم

1. الغرض

CShark هو برنامج خادم لإدارة أماكن وقوف السيارات وأجهزة المنشأة والأحداث والحوادث وأدوات المعلومات. تم تصميم النظام للنشر المحلي على البنية التحتية للمالك ويوفر واجهة ويب واحدة للمشغلين والمسؤولين والموظفين الفنيين والمحللين.

تصف الوثيقة وظائف المثيل المقدم في المتغير demo. بعد التثبيت، يتم إنشاء كائن وهمي Demo Parking "North" بدون عنوان حقيقي وتفاصيل كيان قانوني: مستوى واحد ومنطقتان و50 مكانًا. يتضمن التسليم بوابة الجهاز وAPS الوهمي والمحاكيات الضرورية.

2. تكوين البرمجيات

يتم تسليم المكونات كصور حاوية محلية وتشغيلها عبر Docker Compose. لا تتطلب الخدمات الداخلية الاتصال بسجل حاوية خارجي.

3. المستخدمين والتحكم في الوصول

يدعم النظام المصادقة ونمذجة الأدوار والتحقق من الأذونات لإجراءات المستخدم. يتم تحديد تكوين الأقسام والعمليات المتاحة من خلال الأدوار المعينة.

الخطوط العريضة المخصصة الأساسية:

• المشغل: مخطط المنشأة وحالات الموقع والحوادث والسجل؛
• المسؤول: الهيكل والمستخدمون والأدوار والإعدادات وعمليات التكامل؛
• الفني: الأجهزة وحالة الاتصال والأوامر؛
• محلل أو مالك: مؤشرات وديناميكيات التوظيف؛
• شاشة المعلومات: وصول محدود للآلة إلى العرض المخصص.

يتم تسجيل الإجراءات الإدارية والمشغلة الهامة في مسار التدقيق، مما يحدد المستخدم والوقت والهدف من الإجراء.

4. طوبولوجيا الكائن

يقوم المسؤول بتشكيل الهيكل الرقمي لمرفق وقوف السيارات:

1. كائن؛
2. المستويات؛
3. مناطق ومقصورات النار.
4. أماكن وقوف السيارات؛
5. مجموعات من الأماكن؛
6. الأجهزة واتصالاتها.

الأنواع المدعومة للأماكن هي: قياسي (standard)، للأشخاص ذوي القدرة المحدودة على الحركة (mgn)، دراجة نارية (moto)، الخدمة (service) والمختار (vip). يتم تحديد القدرة على شحن السيارة الكهربائية بواسطة سمة منفصلة ev_charging. تحتوي المناطق على الأوضاع التالية: قياسي (normal)، النار (fire)، المأوى (shelter) والخدمة (service). يتم استخدام هندسة المكان وخلفية المستوى عند عرض الرسم التخطيطي.

في الخيار demo seed 2026.07.2 إنشاء مستوى واحد، مناطق القطاع الأزرق والقطاع الأخضر، بالإضافة إلى 50 مكانًا برموز DEMO-01–DEMO-50. من بينها هناك أماكن MGN، EV، الدراجات النارية والخدمة. لا توجد عناوين حقيقية وتفاصيل عن المنظمات ولقطات الكاميرا في النسخة التجريبية الأساسية.

5. دائرة المشغل

تم تصميم قسم الرسم البياني لمراقبة الحالة الحالية للكائن. وهو يوفر:

• اختيار الكائن والمستوى؛
• نظرة عامة على المستوى والانتقال إلى القطاعات؛
• عرض الأماكن المحتلة والحرة وغير المتاحة وغير المعروفة؛
• البحث عن الموقع؛
• تصفية والتحكم في رؤية الطبقات الإضافية؛
• عرض بطاقة المكان وتاريخ أحواله؛
• عرض الحوادث النشطة ذات الصلة؛
• نقل مكان أو أكثر إلى حالة خارج الخدمة مع الحصول على الإذن المناسب.

يتم تخزين سياق الكائن والمستوى في عنوان URL ويتم استخدامه بواسطة طرق العرض التحليلية المرتبطة.

6. استقبال المناسبات وحالة الأماكن

تستقبل بوابة الجهاز الأحداث من الكاميرات والأجهزة الأخرى، وتقوم بتطبيعها ونقلها إلى Core عبر ناقل الأحداث. تدعم الكاميرات التسجيل وحالة الاتصال ونبضات القلب ومراقبة المنطقة والموقع وقناة الأوامر.

إذا كان NATS غير متاح مؤقتًا، فسيتم تخزين الأحداث التي تستقبلها البوابة في قائمة انتظار محلية مستمرة ويتم إرسالها عند استعادة الاتصال. يجب ألا تؤدي إعادة التسليم إلى إنشاء أحداث عمل مكررة.

يقوم النظام بتخزين سجل التغييرات في حالة الأماكن ويستخدم لقطات الإشغال للتحليلات.

7. الحوادث

يوفر النظام الفرعي للحوادث:

• إنشاء حادث يدويًا أو حسب الحدث؛
• قائمة الحوادث النشطة والمكتملة؛
• قبول الحادث؛
• التجاهل بقرار؛
• الانتهاء من الحادث؛
• عرض المكان والمنطقة والوقت والمواد؛
• تحديث الواجهة عندما تتغير الحالة؛
• السيطرة على وقت المعالجة والتصعيد.

يتم تسجيل إجراءات المشغل في سجل الحوادث وسجل التدقيق.

8. سجل الزيارة

يوفر السجل قائمة بالزيارات المسجلة وأحداث المرور المرتبطة بها. يمكن للمستخدم عرض الإدخالات وتطبيق المرشحات المتاحة. الوصول إلى معرفات ومواد المركبات مقيد بالحقوق ويخضع للتدقيق.

9. التحليلات

يعرض القسم التحليلي:

• مؤشرات موجزة للكائن المحدد؛
• عدد ونسبة الأماكن المحتلة؛
• ديناميات التوظيف؛
• لقطات تاريخية للحالة؛
• مؤشرات للنطاق الزمني المتاح.

يجب تحديد منطقة البيانات بشكل صريح: مستوى أو كائن أو مجموعة كائنات محددة.

10. المعدات

يتم استخدام سجل المعدات للكاميرات والبوابات ومداخل الحريق والأجهزة المقلدة. متاح:

• تسجيل وتحرير الجهاز؛
• عرض الطبقة والسائق ومعلمات الاتصال؛
• حالة الاتصال أو عدم الاتصال بالإنترنت ووقت الحدث الأخير؛
• التاريخ التشخيصي
• إرسال أمر مدعوم مع التأكيد؛
• الكشف عن الكاميرات غير المسجلة.
• ربط الجهاز بعناصر الطوبولوجيا.

يتضمن التسليم برامج محاكاة تسمح لك بالتحقق من دائرة الأحداث بدون معدات مادية.

11. لوحة النتائج وشاشات المعلومات

يوفر النظام الفرعي للمعلومات:

• الاحتفاظ بسجل للوحات النتائج؛
• إنشاء وتحرير القوالب؛
• معاينة القالب؛
• تعيين قالب للوحة نتائج محددة؛
• عرض عدادات المقاعد المتاحة والرسائل النصية.
• رسالة الطوارئ ذات الأولوية؛
• رمز وصول محدود لعميل الشاشة؛
• تحديث حالة الشاشة المخصصة.

يتم تخزين القوالب والمهام على الخادم ولا تعتمد على الجلسة التفاعلية للمشغل. ترتبط الإدارة الكاملة لقوالب الورديات ونسخ التخطيطات الشخصية بين المشغلين بمزيد من التطوير ولم يتم ذكرها كوظيفة للمثيل الحالي.

12. الإدارة

الدائرة الإدارية وتضم:

• المستخدمون والأدوار والأذونات؛
• معلمات النظام
• الطوبولوجيا والهندسة.
• تسجيل الجهاز ومفاتيح التكامل؛
• القواعد واشتراكات Webhook؛
• الرسم البياني للملاحة وإصداراته؛
• سجل التدقيق.

عمليات التغيير محمية عن طريق فحص الأذونات. لا يتم عرض أسرار الخدمة بنص واضح في واجهة المستخدم.

13. قدرات التكامل

يوفر Core واجهة برمجة تطبيقات HTTP استنادًا إلى مخطط OpenAPI المنشور. تدعم بوابة الجهاز عقود الأحداث وأوامر الأجهزة. بالنسبة للأنظمة الخارجية، يتم توفير مفاتيح API وتسليم Webhook وإعادة تسليم الرسائل غير الناجحة.

الأنواع الرئيسية لبيانات التكامل:

• حالة أماكن وقوف السيارات
• مراقبة المركبات؛
• حالة الكاميرا والبوابة ومدخل النار؛
• تغيير الحادث؛
• تغيير وضع المنطقة.
• الأمر إلى الجهاز أو الشاشة.

14. إمكانية الملاحظة والتشخيص

يوفر النظام:

• نقطة نهاية الاستعداد /api/health;
• حالات الحاوية؛
• بروميثيوس المقاييس الفنية.
• لوحات معلومات جرافانا؛
• وسجلات Loki المركزية؛
• آثار الإيقاع الموزعة.
• عدادات التسليم ومعالجة الأحداث.

تهدف إمكانية الملاحظة إلى الأغراض التشخيصية وليست بديلاً عن النسخ الاحتياطي لبيانات العمل.

15. الحماية والاستقرار

يقوم المثيل بتنفيذ التدابير التالية:

• التحكم في الوصول على أساس الدور؛
• أدوار قاعدة البيانات الفردية؛
• أسرار فريدة من نوعها؛
• حقوق محدودة لملفات التكوين؛
• إجراءات التسجيل؛
• التحقق من مخطط قاعدة البيانات قبل تشغيل Core؛
• قائمة الانتظار الدائمة للبوابة؛
• تيار مستمر من الأحداث.
• المجاميع الاختبارية للمجموعة والصور المحلية؛
• النسخ الاحتياطي لقاعدة البيانات والوسائط.

16. حدود المثيل الحالي

المجموعة الحالية:

• مصمم لـ Ubuntu Server 24.04 LTS AMD64؛
• لا يدعم ARM64؛
• مثبتة في دائرة حاوية محلية؛
• في الخيار demo إنشاء ساحة انتظار وهمية فقط بدون عنوان حقيقي وتفاصيل عن كيان قانوني؛ الخيار clean لا يتم إنشاء مواقف سيارات توضيحية؛
• لا يشمل التكامل الصناعي مع معدات محددة دون تكوينها؛
• لا ينص على التحديث التلقائي من واجهة المستخدم؛
• لا تطالب بإدارة محطة الفوترة أو الشحن كميزة للمثيل المقدم.

17. التحكم الوظيفي في إمكانية الوصول

بعد التثبيت تأكد من:

• تسجيل دخول المستخدم؛
• توافر الأقسام حسب الدور؛
• إنشاء طوبولوجيا أساسية؛
• تلقي حدث من المحاكي؛
• تغير في حالة المكان
• إنشاء ومعالجة الحادث؛
• سجل الزيارة؛
• ملخص تحليلي؛
• حالة الجهاز
• إنشاء وتعيين قالب لوحة النتائج؛
• مسار التدقيق؛
• المقاييس وسجلات النظام.