مقدمة مشروع OpenStock

نظرة عامة على المشروع

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

الفكرة الأساسية: يجب أن تكون المعرفة مفتوحة ومجانية ومتاحة للجميع، ويجب أن تكون التكنولوجيا في متناول كل شخص.

الميزات الرئيسية

🔐 المصادقة

• نظام مصادقة عبر البريد الإلكتروني/كلمة المرور باستخدام Better Auth + MongoDB
• حماية المسارات عبر وسيط (Middleware) Next.js
• إدارة كاملة لجلسات المستخدمين

🔍 البحث العالمي

• وظيفة بحث سريعة عن الأسهم مدعومة بواسطة واجهة برمجة تطبيقات Finnhub
• عرض الأسهم الشائعة عند عدم النشاط، مع دعم استعلامات مضادة للارتداد (Debounced Queries)
• اختصار لوحة الأوامر Command + K

⭐ قائمة المراقبة (Watchlist)

• يتم تخزين قائمة المراقبة الخاصة بكل مستخدم في MongoDB
• رمز السهم فريد لكل مستخدم
• إمكانية إضافة/إزالة الأسهم بسهولة

📊 تفاصيل السهم

• معلومات رمز السهم من TradingView
• مخططات شمعدانية/متقدمة، مخططات خط أساس، ومؤشرات فنية
• ودجات ملف الشركة والبيانات المالية

📈 نظرة عامة على السوق

• خرائط حرارية، اقتباسات السوق، وأخبار رئيسية
• استخدام ودجات TradingView المضمنة
• تحديث بيانات السوق في الوقت الفعلي

🎯 عملية بدء استخدام مخصصة

• جمع معلومات عن الدولة التي ينتمي إليها المستخدم وأهدافه الاستثمارية
• تحمل المخاطر والقطاعات المفضلة
• تجربة مستخدم مخصصة

📧 البريد الإلكتروني والأتمتة

• بريد ترحيبي مخصص بواسطة الذكاء الاصطناعي (استدعاء Gemini عبر Inngest)
• بريد يومي ملخص للأخبار (مهمة مجدولة)
• محتوى مخصص بناءً على قائمة المراقبة الخاصة بالمستخدم

🎨 واجهة مستخدم أنيقة

• مكونات shadcn/ui + مكونات Radix UI الأساسية
• نظام تصميم Tailwind v4
• وضع داكن افتراضي
• تصميم متجاوب

المكدس التقني

التقنيات الأساسية

• Next.js 15 (App Router)
• React 19
• TypeScript
• Tailwind CSS v4 (عبر @tailwindcss/postcss)
• shadcn/ui + مكونات Radix UI الأساسية
• مكتبة أيقونات Lucide

المصادقة والبيانات

• Better Auth – مصادقة البريد الإلكتروني/كلمة المرور مع محول MongoDB
• MongoDB + Mongoose – استمرارية البيانات
• Finnhub API – رموز الأسهم، ملفات الشركات، وأخبار السوق
• TradingView – ودجات الرسوم البيانية القابلة للتضمين

الأتمتة والاتصالات

• Inngest – معالجة الأحداث، المهام المجدولة، واستنتاج الذكاء الاصطناعي (Gemini)
• Nodemailer – إرسال البريد الإلكتروني (من خلال Gmail)
• next-themes – تبديل السمات
• cmdk – لوحة الأوامر
• react-hook-form – معالجة النماذج

تكوين اللغات

• TypeScript (~93.4%)
• CSS (~6%)
• JavaScript (~0.6%)

هيكل المشروع

app/
├── (auth)/                    # صفحات المصادقة
│   ├── layout.tsx
│   ├── sign-in/page.tsx
│   └── sign-up/page.tsx
├── (root)/                    # صفحات التطبيق الرئيسية
│   ├── layout.tsx
│   ├── page.tsx
│   ├── help/page.tsx
│   └── stocks/[symbol]/page.tsx
├── api/inngest/route.ts       # نقطة نهاية Inngest API
├── globals.css
└── layout.tsx

components/
├── ui/                        # مكونات shadcn/radix الأساسية
├── forms/                     # مكونات النماذج
├── Header.tsx
├── Footer.tsx
├── SearchCommand.tsx
└── WatchlistButton.tsx

database/
├── models/watchlist.model.ts
└── mongoose.ts

lib/
├── actions/                   # عمليات الخادم
│   ├── auth
│   ├── finnhub
│   ├── user
│   └── watchlist
├── better-auth/
├── inngest/                   # عميل Inngest والوظائف
├── nodemailer/               # إعدادات إرسال البريد الإلكتروني
├── constants.ts
└── utils.ts

scripts/
└── test-db.mjs               # اختبار اتصال قاعدة البيانات

types/
└── global.d.ts

public/assets/images/         # الشعارات واللقطات

البدء السريع

المتطلبات المسبقة

• Node.js 20+
• pnpm أو npm
• سلسلة اتصال MongoDB (MongoDB Atlas أو Docker محلي)
• مفتاح واجهة برمجة تطبيقات Finnhub
• حساب Gmail (لإرسال البريد الإلكتروني)
• اختياري: مفتاح واجهة برمجة تطبيقات Google Gemini (لمحتوى الذكاء الاصطناعي)

خطوات التثبيت

1. استنساخ المستودع

git clone https://github.com/Open-Dev-Society/OpenStock.git
cd OpenStock

2. تثبيت التبعيات

pnpm install
# أو
npm install

3. تهيئة متغيرات البيئة

أنشئ ملف .env:

# الإعدادات الأساسية
NODE_ENV=development

# قاعدة البيانات
MONGODB_URI=your_mongodb_connection_string

# Better Auth
BETTER_AUTH_SECRET=your_better_auth_secret
BETTER_AUTH_URL=http://localhost:3000

# Finnhub
FINNHUB_API_KEY=your_finnhub_key
NEXT_PUBLIC_FINNHUB_API_KEY=
FINNHUB_BASE_URL=https://finnhub.io/api/v1

# Inngest AI (Gemini)
GEMINI_API_KEY=your_gemini_api_key

# إعدادات البريد الإلكتروني
NODEMAILER_EMAIL=youraddress@gmail.com
NODEMAILER_PASSWORD=your_gmail_app_password

4. التحقق من اتصال قاعدة البيانات

pnpm test:db

5. تشغيل خادم التطوير

pnpm dev

6. تشغيل Inngest (لوظائف سير العمل والمهمات المجدولة)

npx inngest-cli@latest dev

7. فتح التطبيق

افتح المتصفح وانتقل إلى http://localhost:3000

النشر باستخدام Docker

يوفر المشروع تكوين Docker Compose لتشغيل التطبيق وMongoDB بسرعة:

# تشغيل MongoDB
docker compose up -d mongodb

# بناء وتشغيل التطبيق
docker compose up -d --build

عند استخدام Docker، يجب أن تكون سلسلة اتصال MongoDB كالتالي:

MONGODB_URI=mongodb://root:example@mongodb:27017/openstock?authSource=admin

البيانات والتكاملات

واجهة برمجة تطبيقات Finnhub

• توفر البحث عن الأسهم، ملفات الشركات، وأخبار السوق
• قد تُرجع النسخة المجانية أسعارًا مؤخرة
• يجب الانتباه إلى حدود معدل الطلبات

TradingView

• توفر ودجات قابلة للتضمين للرسوم البيانية، الخرائط الحرارية، واقتباسات السوق
• الصور الخارجية من i.ibb.co

Better Auth + MongoDB

• مصادقة البريد الإلكتروني/كلمة المرور
• محول MongoDB لتخزين الجلسات
• معظم المسارات محمية باستثناء صفحات تسجيل الدخول/التسجيل

سير عمل Inngest

• حدث إنشاء مستخدم → بريد ترحيبي مخصص بواسطة الذكاء الاصطناعي
• مهمة مجدولة (كل يوم عند الساعة 12 ظهرًا) → إرسال بريد ملخص الأخبار
• يستخدم في التطوير المحلي npx inngest-cli@latest dev

إرسال البريد الإلكتروني (Nodemailer)

• يستخدم Gmail كوسيط نقل
• يوفر قوالب للبريد الترحيبي وملخص الأخبار
• يُوصى باستخدام خدمة SMTP احترافية في بيئة الإنتاج

النصوص البرمجية المتاحة

• pnpm dev - تشغيل خادم التطوير (Turbopack)
• pnpm build - بناء للإنتاج
• pnpm start - تشغيل خادم الإنتاج
• pnpm lint - تشغيل ESLint
• pnpm test:db - التحقق من اتصال قاعدة البيانات

تجربة المطور

• TypeScript في الوضع الصارم
• Tailwind CSS v4 (بدون حاجة لملف تهيئة منفصل)
• مكتبة مكونات shadcn/ui
• لوحة أوامر cmdk
• تبديل السمات next-themes
• أيقونات lucide-react

بيان Open Dev Society

نحن نعيش في عالمٍ تُخفى فيه المعرفة خلف جدران الدفع، وتُغلَّف الأدوات داخل خدمات الاشتراك، وتُشوَّه المعلومات بالتحيّز، ويُقال للمبتدئين إنهم "ليسوا جيدين بما يكفي" للبناء.

معتقداتنا:

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

مهمتنا:

• بناء مشاريع مفتوحة المصدر مجانية ومفيدة حقًا
• أدوات يمكن للمحترفين والطلاب استخدامها دون عوائق
• منصات معرفة حيث يكون التعلم دائمًا مجانيًا
• مجتمعات توجّه المبتدئين ولا تحكم عليهم
• موارد تعمل على الثقة لا على الربح

تعهدنا:

• لن نغلق المعرفة أبدًا
• لن نفرض رسومًا على الوصول أبدًا
• لن نبيع ثقتكم مقابل المال أبدًا
• سنعمل على أساس الشفافية والتبرعات وقوة المجتمع

دليل المساهمة

نرحب بمساهمات الجميع! سواء كنت طالبًا، مطورًا ذاتي التعلم، أو مهندسًا متمرسًا.

• ناقش الأفكار والأخطاء عبر Issues
• ابحث عن المشكلات الموسومة بـ "good first issue" أو "help wanted"
• اجعل طلبات السحب (PR) مركزة، وأرفق لقطات شاشة لأي تغييرات في واجهة المستخدم
• تعامل بلطف، وجه المبتدئين، وارفض الحواجز — هذه هي طريقة ODS

الأمان

إذا اكتشفت ثغرة أمنية:

• لا تُبلّغ عنها علنًا عبر Issue
• أرسل بريدًا إلكترونيًا إلى: opendevsociety@cc.cc
• سنقوم بتنسيق الكشف المسؤول وإصلاح المشكلة بسرعة

الترخيص

يُرخّص OpenStock بموجب ترخيص AGPL-3.0. إذا قمت بتعديل المشروع أو إعادة توزيعه أو نشره (بما في ذلك كخدمة ويب)، فيجب عليك نشر شفرتك المصدرية تحت نفس الترخيص وذكر المؤلف الأصلي.

الشكر والتقدير

• Finnhub – لتوفير بيانات السوق بشكل متاح
• TradingView – لتوفير ودجات السوق القابلة للتضمين
• مجتمعات shadcn/ui, Radix UI, Tailwind CSS, Next.js
• Inngest – للمهام الخلفية وسير العمل الموثوق
• Better Auth – للمصادقة البسيطة والآمنة
• جميع المساهمين الذين يجعلون الأدوات مفتوحة المصدر ممكنة

شكر خاص لـ Adrian Hajdin (JavaScript Mastery)، فقد ساعدت دروسه الممتازة حول تطبيقات سوق الأسهم Open Dev Society بشكل كبير في بناء OpenStock.

مبني على الانفتاح، للجميع، مجاني إلى الأبد. — Open Dev Society

رابط المشروع: https://github.com/Open-Dev-Society/OpenStock