Skip to content

GEMINI.md

Latest commit

 

History

History
94 lines (76 loc) · 8.93 KB

GEMINI.md

File metadata and controls

94 lines (76 loc) · 8.93 KB
Raw

FileFly — Project Knowledge Base & AI Agent Context

ملف إرشادات وسياق دائم للمساعد الذكي (Antigravity / Gemini Agent):
يُقرأ هذا الملف تلقائياً في بداية كل محادثة لضمان فهم كامل ومستمر لطبيعة مشروع FileFly، بنيته التقنية، وبيئات استخدامه، وملاحظات التطوير الهامة.

🚀 1. هوية وفكرة التطبيق (Project Overview)

  • الاسم: FileFly
  • الهدف الأساسي: تطبيق سريع، عصري، وآمن لنقل الملفات والنصوص عبر الشبكة المحلية (LAN / Wi-Fi) مباشرة بين مختلف الأجهزة وأنظمة التشغيل بدون الحاجة للإنترنت نهائياً (Zero Internet / Local Network Only).
  • الخصوصية والسرعة: نقل محلي 100% بأقصى سرعة يوفرها راوتر الواي فاي، بدون تخزين سحابي وبدون قيود على أحجام الملفات.
  • تجربة المستخدم: شبيهة بـ AirDrop ولكنها عابرة للأنظمة (Cross-Platform) مع رادار كشف للأجهزة المتصلة.

📱💻 2. أين وكيف يُستخدم التطبيق؟ (Target Environments)

1️⃣ أجهزة الكمبيوتر (Desktop / Laptop - Windows, Mac, Linux):

  • تطبيق مكتبي مخصص (Electron):
    • يعمل كبرنامج محمول (Portable .exe أو مثبت) بدون إطار خارجي (Frameless Dark UI) مع شريط عنوان مخصص، تصغير لشريط المهام، وإشعارات نظام حقيقية.
    • الأمر لبنائه كـ exe: npm run build:exe (ينتج في مجلد dist-app).
  • أو عبر المتصفح مباشرة:

2️⃣ الهواتف والأجهزة اللوحية (Mobile - Android, iPhone, iPad, Tablets):

  • بدون تثبيت أي تطبيقات إضافية (Zero-Install):
    • يفتح المستخدم كاميرا الهاتف ويمسح كود الـ QR Code المعروض على شاشة الكمبيوتر ليفتح الموقع مباشرة.
  • تطبيق ويب تقدمي (PWA - Progressive Web App):
    • يحتوي على manifest.json و sw.js (Service Worker).
    • يمكن للمستخدم تثبيته كأيقونة تطبيق مستقلة على الشاشة الرئيسية للهاتف ("Add to Home Screen").

🛠️ 3. البنية التقنية (Tech Stack)

الواجهة الأمامية (Frontend):

  • React 18 مع Vite 6
  • Tailwind CSS 3 (تصميم عصري Dark Mode زجاجي / Glassmorphism)
  • Lucide React (أيقونات الأنظمة والأجهزة)
  • State Management: src/context/FileFlyContext.jsx يدير اتصالات الـ WebSocket وحالات النقل والأجهزة النشطة.

السيرفر والباك إند (Backend):

  • Node.js (ES Modules)
  • Express 4: لخدمة الواجهة وواجهات الـ REST API واستقبال الملفات.
  • WebSockets (ws): مزامنة فورية ثنائية الاتجاه للرادار، طلبات الإرسال، القبول/الرفض، تقدم النقل، والرسائل النصية.
  • Multer & Streams: رفع الملفات وتقسيمها لتقليل استهلاك الذاكرة وتوفير سرعة نقل عالية.

الشبكة والاستكشاف (Networking & Discovery):

  • UDP Discovery (server/discovery.js): استكشاف تلقائي للأجهزة على الشبكة عبر البث (Port 53317).
  • Dynamic IP Detection (server/networkUtils.js): استخراج تلقائي لعنوان الـ IP الفعلي للراوتر وتحديث كود الـ QR عند تغير الشبكة.
  • mDNS Responder (server/mdnsResponder.js): دعم النطاق المحلي fly.local.

🌐 4. المنافذ وإعدادات الشبكة (Ports & Networking Rules)

المنفذ (Port) الاستخدام ملاحظات هامة
53316 سيرفر الباك إند و WebSocket والـ API المنفذ الرئيسي للإنتاج ولاتصال الهواتف وكود الـ QR
5173 سيرفر تطوير الواجهة (Vite Dev Server) مخصص للتطوير محلياً مع التحديث الحي (HMR)
53317 منفذ UDP للاستكشاف (Peer Discovery) مستخدم لبث واستقبال رسائل التعرف بين الأجهزة
80 محجوز لنظام Windows (System / HTTP.sys) ⚠️ لا تستخدم المنفذ 80 نهائياً. الدخول دائماً يتطلب كتابة المنفذ (:53316 أو :5173)

⚠️ 5. ملاحظات وقواعد أساسية للمساعد الذكي أثناء التعديل (Critical Rules for AI)

  1. طريقة تشغيل المشروع في التطوير:
    • السيرفر يشغّل بالاختصار: npm run dev (يطلق concurrently كلاً من npm run dev:server و npm run dev:vite).
  2. ملفات الواجهة والإنتاج (dist):
    • سيرفر الباك إند server/index.js مهيأ لخدمة dist/index.html في الإنتاج، والتحويل التلقائي إلى منفذ 5173 في التطوير إذا لم يكن مجلد dist موجوداً. لا تعطل هذا السلوك.
  3. التجاوب مع الهواتف (Responsive UI):
    • أي تعديل في التصميم يجب أن يراعي شاشات الهواتف المحمولة عمودياً وشاشات الحواسيب أفقياً بشكل ممتاز، مع مراعاة وضع الـ PWA.
  4. جدار الحماية والشبكة:
    • عند تشغيل التطبيق على أي جهاز جديد، يجب تفعيل السماح في جدار حماية ويندوز (Windows Firewall) للشبكات الخاصة (Private Networks) لتتمكن الهواتف من الاتصال.
  5. سلامة بروتوكول النقل (File Transfer Protocol):
    • لا تغير هيكل رسائل الـ WebSocket (INIT_STATE, PEERS_UPDATE, TRANSFER_REQUEST, TRANSFER_ACCEPT, TRANSFER_PROGRESS, TRANSFER_COMPLETE, CLIPBOARD_SHARE) بدون مزامنة التغيير بين server/index.js و src/context/FileFlyContext.jsx.
  6. تنسيق التاريخ في سجل النقل (History Format):
    • يُعرض التاريخ والوقت كاملاً بصيغة: YYYY-M-D | 12:14 am (مثل 2026-5-2 | 12:14 am) مع تثبيت dir="ltr" لمنع تداخل الأرقام مع الواجهة العربية.
  7. خصوصية سجل النقل بين الأجهزة (Transfer History Privacy):
    • سجل النقل خاص ومنفصل تماماً لكل جهاز؛ لا يمكن لأي مستخدم معرفة ما نقله مستخدم آخر (خصوصية تامة بين الأجهزة).
    • يرى كل جهاز فقط العمليات التي شارك فيها هو بنفسه (إما كـ مُرسِل أو كـ مُستقبِل). لا تُشارك سجلات الأطراف الأخرى نهائياً سواء عبر الـ API أو في واجهة المستخدم أو التخزين المحلي.
  8. عرض وتصميم بطاقة السجل (Transfer History Card Layout):
    • تصميم بطاقة تنفيذي راقي ثنائي الطبقات (Two-Tier Executive Glass Card) يمنح كل معلومة موضعها الطبيعي:
      • الطبقة العلوية (File Profile & Metrics):
        • اليمين: أيقونة Squircle متدرجة ومتوهجة بنوع الملف مع شارة الامتداد الدقيقة المدمجة في الركن الداخلي (مثل JPEG أو PDF).
        • الوسط: اسم الملف بالخط العريض (font-bold truncate) وتحته اتجاه النقل وتصنيف الملف مع شارة الإتمام الزمردية (↙ مستلم • صورة • مكتمل ✓).
        • اليسار: كبسولة حجم الملف الزجاجية المدمجة (84.81 KB) مع زر الحذف الهادئ (Trash).
      • الطبقة السفلية (Route & Ledger Strip):
        • شريط سفلي أغمق مدمج ومفصول بحد علوي خفيف (bg-slate-950/60 border-t border-slate-800/60):
          • اليمين: مسار النقل بكبسولات الأجهزة الدقيقة [📱 iPhone-0C6A] ➔ [💻 PC].
          • اليسار: كبسولة التاريخ والوقت كاملاً [🕒 YYYY-M-D | 12:14 am].
      • رأس النافذة: زر "مسح الكل" لمسح السجل بضغطة واحدة.
      • متجاوب 100% بدون أي تداخل أو التفاف على كافة شاشات الهواتف والكمبيوتر.