Skip to content

GLOSSARY.md

Latest commit

 

History

History
182 lines (129 loc) · 10.1 KB

GLOSSARY.md

File metadata and controls

182 lines (129 loc) · 10.1 KB
Raw

المصطلحات والشخصيات

مرجع سريع لكل اسم / مصطلح / رمز يُستخدم في المشروع.

الشخصيات (Personas)

👨‍💼 صاحب المكتب — Operator

  • الدور: يستلم طلبات الطباعة، يطبعها، يسلّمها للطلاب، يستلم الدفع.
  • الجهاز: لابتوب Mac + راوتر + طابعة.
  • الوصول: تطبيق UOADrop Desktop + Dashboard كامل.
  • في الكود: role: 'librarian'.

👩‍🎓 طالب داخل المكتب — Offline/LAN

  • الدور: طالب داخل المكتب، يرفع ملفاته عبر الـ Wi-Fi المحلي.
  • الجهاز: أي موبايل (iOS/Android) أو لابتوب.
  • الاتصال: شبكة المكتب المحلية فقط، بدون إنترنت بالضرورة.
  • في التطبيق الحالي: يرفع الطلب عبر صفحة الرفع المحلية ويستلم ticket و pickupPin.

👨‍🎓 طالب أونلاين — Online

  • الدور: طالب يرفع طلبه عبر مسار Online من خارج شبكة المكتب.
  • الجهاز: أي جهاز متصل بالإنترنت.
  • الاتصال: https://uoadrop.vercel.app + Supabase.
  • في التطبيق الحالي: طلبه يظهر داخل Dashboard الديسكتوب بعد استيراده، ويمكن إشعاره عبر Email/Telegram.

الأيقونات والرموز

الرمز المعنى
📡 طلب Offline (من داخل المكتب)
🌐 طلب Online (من خارج المكتب أو عبر الرابط العام)
🔵 QR Offline (أزرق، مطبوع على الحائط)
🟢 QR Online (أخضر، مطبوع على الحائط)
✅ طلب مكتمل (done)
⏳ طلب في الانتظار (pending)
🖨️ طلب يُطبع حالياً (printing)
❌ طلب ملغى (canceled)

صيغة التذاكر (Ticket Format)

  • Offline: A-0001, A-0002, ... — counter محلي في SQLite، يبدأ من جديد كل سنة.
  • Online: B-0001, B-0002, ... — sequence في Postgres (Supabase)، مستمرة.
  • الـ prefix (A/B) يميّز المصدر بسرعة حتى لو الأيقونة ما ظهرت.

المصطلحات التقنية

mDNS (Multicast DNS)

بروتوكول يسمح للأجهزة على نفس الشبكة المحلية باكتشاف بعضها بأسماء .local (مثل drop.local) بدون الحاجة لـ DNS server. لم نستخدمه في المعمارية النهائية — اعتمدنا IP ثابت مباشرة.

Captive Portal

صفحة الترحيب اللي تفتح تلقائياً لما تتصل بشبكة Wi-Fi عامة (فنادق، مطارات). لم نستخدمها لأن الراوتر TL-WR940N ما يدعمها في الـ stock firmware. عوّضنا بمسح QR يدوي.

AP Isolation (Access Point Isolation)

ميزة على الراوتر تمنع الأجهزة المتصلة بنفس الـ Wi-Fi من رؤية بعضها. يجب أن تكون Disabled في UOADrop، وإلا موبايل الطالب ما يوصل لجهاز صاحب المكتب.

RLS (Row Level Security)

ميزة في Postgres تسمح بوضع شروط على مستوى الصف الواحد لتحديد من يقرأ/يكتب. نستخدمها في Supabase لحماية الطلبات من الوصول العام.

tus.io

بروتوكول رفع ملفات مفتوح يدعم resumable uploads — لو انقطع الاتصال في 80%، الرفع يستكمل من آخر chunk بدل البدء من الصفر. حرجة لاتصال Wi-Fi متذبذب.

غير مستخدم في التطبيق الحالي؛ مذكور فقط كخيار/خطة للنسخة online المستقبلية.

IP & MAC Binding

ميزة على الراوتر لحجز IP محدد لـ MAC address معيّن. نستخدمها لضمان أن جهاز صاحب المكتب دائماً يحصل على IP ثابت، مما يجعل الـ QR المحلي ثابتاً.

DHCP (Dynamic Host Configuration Protocol)

البروتوكول اللي يوزّع الـ IPs تلقائياً في الشبكة. الراوتر هو DHCP server في معماريتنا.

DHCP Reservation

مرادف لـ IP & MAC Binding — حجز IP ثابت لجهاز معيّن.

Runtime SQLite Migrations

أسلوب مستخدم حالياً داخل apps/desktop/src/main/db.ts لضمان إنشاء الجداول وإضافة الأعمدة المفقودة مثل pages و pickup_pin و options_json عند تشغيل التطبيق.

Supabase Realtime

ميزة في Supabase لبث تحديثات قاعدة البيانات للعملاء فوراً عبر WebSocket. نستخدمها لمسار الأونلاين ومزامنة الطلبات.

Edge Function

دالة serverless تشتغل على CDN edge. ذُكرت في التصاميم الأولى؛ التنفيذ الحالي للإشعارات يعتمد غالباً على Next.js API routes في apps/web.

SMTP / Nodemailer

المسار الحالي لإرسال Email من apps/web عبر SMTP. الإعداد الافتراضي يستخدم Brevo SMTP، ويمكن تغييره عبر متغيرات EMAIL_HOST, EMAIL_PORT, EMAIL_USER, EMAIL_PASS, EMAIL_FROM.

Telegram Bot API

API رسمي من تيليجرام لإنشاء بوتات. مجاني بالكامل. نستخدمه لإرسال إشعارات الطباعة لطلاب الأونلاين عبر بوت UOADrop.

Webhook

آلية حيث خدمة خارجية (مثل Telegram) ترسل HTTP POST إلى endpoint عندنا عند وقوع حدث (مثل رسالة جديدة من مستخدم). أسرع وأكفأ من polling.

Chat ID

رقم عددي فريد يحدّد محادثة في Telegram. كل مستخدم عنده chat_id خاص مع كل بوت. نحفظه لنرسل الإشعارات مباشرة بدل الاعتماد على @username (اللي ممكن يتغير).

Opt-in / Opt-out

  • Opt-in: المستخدم يختار الاشتراك صراحة (مثلاً بإرسال /start للبوت).
  • Opt-out: المستخدم يلغي الاشتراك (مثلاً /stop للبوت).
  • نحترم الاثنين: لا نرسل إشعارات لأحد لم يطلبها.

Electron

إطار لبناء تطبيقات Desktop بـ web technologies (JS/HTML/CSS). تطبيق المكتب مبني عليه.

Fastify

إطار HTTP server لـ Node.js، أسرع من Express. يشتغل داخل Electron main process.

better-sqlite3

مكتبة Node.js للتعامل مع SQLite بشكل synchronous — الأسرع في الـ ecosystem.

Monorepo

نمط تنظيم الكود حيث كل الحزم (packages + apps) في مستودع git واحد. نستخدم pnpm workspaces + Turborepo.

PWA (Progressive Web App)

تطبيق ويب يقدر يُثبّت على الشاشة الرئيسية ويعمل offline. صفحة الرفع المحلية تعمل كصفحة standalone، والويب الأونلاين موجود داخل apps/web.

Zod

مكتبة TypeScript لـ schema validation. نستخدمها لـ form validation في كل من الـ client والـ server.

Service Worker

script يشتغل في الخلفية في المتصفح، يدعم offline caching. يساعد صفحة الرفع لتفتح حتى لو الشبكة متذبذبة.

WAL Mode (Write-Ahead Logging)

وضع في SQLite يحسّن الأداء والاعتمادية بفصل الكتابة عن القراءة. نفعّله افتراضياً.

الملفات والمجلدات الرئيسية

الاسم الموقع الغرض
apps/web جذر المشروع Next.js online upload + notification APIs
apps/desktop جذر المشروع Electron + Fastify + SQLite + React dashboard
packages/shared جذر المشروع types + constants + validation helpers
supabase/functions جذر المشروع مساحة اختيارية/قديمة لـ Edge Functions إن أضيفت لاحقاً
~/Library/Application Support/UOADrop Mac بيانات تطبيق المكتب (SQLite + ملفات)
%APPDATA%/UOADrop Windows نفس الشي لـ Windows

URLs والعناوين

العنوان الغرض
http://192.168.0.100:3737/ صفحة الرفع المحلية للطالب
http://<LAN-IP>:3737/ نفس صفحة الرفع إذا تغيّر عنوان الجهاز داخل الشبكة
https://uoadrop.vercel.app صفحة رفع Online العامة
Dashboard داخل Electron الواجهة الإدارية الحالية، وليست صفحة ويب منفصلة
http://192.168.0.1 واجهة إدارة الراوتر
https://<project>.supabase.co Supabase project dashboard

مستويات حالة الطلب (Status)

Status معناها من يقدر يغيّرها
pending الطلب وصل وينتظر التنفيذ صاحب المكتب
printing بدأ التنفيذ أو الطباعة صاحب المكتب
ready جاهز للاستلام صاحب المكتب
done تم التسليم صاحب المكتب
canceled ألغي قبل الإكمال صاحب المكتب
blocked موقوف أو يحتاج مراجعة صاحب المكتب

مصطلحات التشغيل اليومي

  • الطابور: قائمة الطلبات pending مرتبة حسب الوقت.
  • التذكرة: رقم فريد للطلب مخزن في الحقل ticket.
  • النموذج: صفحة الرفع اللي يعبيها الطالب.
  • اللوحة: Dashboard صاحب المكتب.
  • رمز الاستلام: رقم/رمز يظهر للطالب في صفحة النجاح ويظهر أيضاً داخل الدشبورد.
  • إعدادات الملف: خيارات الطباعة المخزنة على مستوى كل ملف داخل request_files.options_json.