منصة مُيسّر (Muyassir)

مساعد بلدي ذكي للتحقق الاستباقي من مطابقة المحلات التجارية لاشتراطات البلدية.

منصة ويب تتيح لأصحاب المنشآت التجارية رفع صور منشآتهم، ليقوم الذكاء الاصطناعي بمطابقتها آلياً مع الاشتراطات البلدية المعتمدة للنشاط التجاري وإصدار "تقرير جاهزية" فوري بلغة المستفيد. كما تتضمن المنصة مساعداً تفاعلياً متعدد اللغات، ولوحة قياس أداء للجهات البلدية.

تنويه هام: قائمة الاشتراطات المتوفرة حالياً في مسار public/kb.js هي لأغراض تجريبية فقط. يجب استبدالها بالدليل الرسمي للاشتراطات من منصة "بلدي" قبل تفعيل المنصة في بيئة الإنتاج الفعلي.

للاطلاع على التوثيق التقني الشامل، يُرجى مراجعة ملف TECHNICAL.md.

---

التشغيل المحلي (بيئة التطوير)

مدة الإعداد المتوقعة: 5 دقائق. يتطلب تشغيل المنصة وجود بيئة Node.js (بإصدار 18 فما فوق)، ولا يتطلب تثبيت أي مكتبات خارجية إضافية.

cd muyassir-platform
cp .env.example .env          # يرجى إضافة المفتاح البرمجي الخاص بك في متغير ANTHROPIC_API_KEY
npm start                     # بعد التشغيل، يمكنك زيارة الرابط: http://localhost:3000

الوضع التجريبي (Demo Mode): في حال عدم توفر مفتاح برمجي (API Key)، يمكن تشغيل المنصة عبر الأمر: npm run demo. ستعمل المنصة بكامل خصائصها مع تقديم نتائج نموذجية تحمل وسم «وضع تجريبي». يُعد هذا الخيار مثالياً للاستخدام كخطة بديلة (Fallback) لضمان استمرارية العرض التقديمي للجنة التحكيم في حال انقطاع الاتصال بالإنترنت.

النشر السحابي (عبر منصة Vercel)

مدة الإعداد المتوقعة: 10 دقائق.

1. قم برفع مجلد muyassir-platform إلى مستودع خاص (Private Repository) على منصة GitHub.
2. انتقل إلى منصة Vercel، واختر إضافة مشروع جديد Add New → Project، ثم حدد المستودع الخاص بالمنصة.
3. من قسم المتغيرات البيئية Environment Variables، قم بإضافة القيم التالية:

• ANTHROPIC_API_KEY: المفتاح البرمجي الخاص بك المستخرج من console.anthropic.com.
• ADMIN_PIN: رمز الدخول المخصص لحماية لوحة بيانات الأمانة (على سبيل المثال: مكون من 4 أرقام).

4. اضغط على زر النشر Deploy، وسيتم تزويدك برابط حي للمنصة (مثل: muyassir.vercel.app).

التخزين الدائم لبيانات لوحة الأمانة (اختياري): نظراً لأن منصة Vercel تعيد تهيئة الخادم بشكل دوري، فقد تُفقد بيانات اللوحة مؤقتاً. لضمان التخزين الدائم للسجلات، يُنصح بإنشاء قاعدة بيانات مجانية من نوع Redis عبر منصة Upstash، ثم إضافة المتغيرين البيئيين UPSTASH_REDIS_REST_URL و UPSTASH_REDIS_REST_TOKEN إلى إعدادات مشروعك في Vercel.

الاختبار وضمان الجودة

npm test        # يُنفذ 23 اختباراً آلياً لمنطق الفحص وواجهات برمجة التطبيقات (API) ونصوص الواجهة (لا يتطلب مفتاحاً برمجياً أو اتصالاً بالإنترنت).
npm run eval    # يُجري اختباراً لقياس الدقة على صور حقيقية للمنشآت (يتطلب مفتاحاً برمجياً).

خطوات إجراء اختبار الدقة (Evaluation)

1. أضف صوراً حقيقية للمنشآت التجارية في المجلد eval/photos/. يُفضل توفير عينات تتراوح بين 6 إلى 10 منشآت متنوعة (مطابقة وغير مطابقة للاشتراطات).
2. قم بنسخ ملف eval/cases.example.json وتسميته eval/cases.json. بعد ذلك، حدد لكل منشأة تقييم الخبير البشري لكل بند من بنود الاشتراطات (باستخدام القيم pass أو fail).
3. نفّذ الأمر npm run eval. سيتم إصدار تقرير شامل في المسار eval/results/report.md يوضح نسبة دقة فحص النموذج، والذي يمكن مشاركته مع لجان التحكيم والتقييم.

هيكل المشروع ومحتوياته

ui/app.html         ملف مصدر الواجهة الأساسية (عند إجراء تعديلات، يُنفذ الأمر: node tools/build-ui.js)
public/index.html   واجهة المنصة النهائية (يتم إنشاؤها تلقائياً بالاعتماد على ui/app.html)
public/kb.js        قاعدة الاشتراطات البلدية (تُشارك بياناتها بين الواجهة والخادم)
public/i18n.js      نصوص الواجهة ومفاتيحها (تُنشأ تلقائياً: node tools/extract-i18n.js)
lib/core.js         المنطق البرمجي الخاص بعمليات الفحص، المساعد الذكي، والتخزين
lib/http.js         وحدة معالجة الطلبات الواردة (HTTP Requests)
api/                مسارات واجهات برمجة التطبيقات (analyze · ask · stats · health · i18n)
server.js           إعداد الخادم المحلي (Local Server)
tests/              مجلد اختبارات الوحدة (Unit Tests) واختبارات الـ API
eval/               مجلد أدوات وملفات اختبار قياس دقة النموذج

لغة الواجهة

الواجهة كلها تتغير مع اللغة اللي يختارها المستفيد، مو التقرير وحده.

• كل نص ظاهر مفتاحه نصه العربي نفسه. tools/extract-i18n.js يجمعها من ui/app.html وpublic/kb.js ويولّد public/i18n.js.
• أربع لغات جاهزة داخل الملف: العربية والإنجليزية والأردو والبنغالية. التبديل بينها فوري، بدون مفتاح وبدون إنترنت.
• بقية اللغات يترجمها /api/i18n مرة واحدة بالنموذج السريع، وتُحفظ في Upstash Redis وفي متصفح المستفيد. بدون مفتاح تظهر الإنجليزية.
• لإضافة لغة جاهزة: أنشئ tools/i18n-<code>.json بنفس المفاتيح، وشغّل المولّد.

بعد أي تعديل على نصوص الواجهة:

node tools/extract-i18n.js   # يحدّث قائمة المفاتيح وينبّه على الناقص من الإنجليزية
node tools/build-ui.js       # يعيد بناء public/index.html

الترجمات في tools/i18n-<code>.json، وتُحرَّر يدوياً. npm test يفشل إذا نقص نص في أي لغة جاهزة.

عمل وإشراف : • ريناس عبدالله • مرام الخيبري • لطيفه المتعب • جنا الحويطي