يغطي هذا الدليل سير عمل التطوير اليومي للمساهمة في Bedrud.

هيكل المستودع

bedrud/
├── server/          # Go backend
├── apps/
│   ├── web/         # React frontend (TanStack Start)
│   ├── android/     # Android app
│   ├── ios/         # iOS app
│   └── desktop/     # Desktop app (Rust + Slint)
├── agents/          # Python bot agents
├── packages/        # Shared TypeScript types
├── tools/cli/       # Deployment CLI
├── docs/            # Documentation (MkDocs)
├── Cargo.toml       # Rust workspace root
├── Makefile         # Build orchestration
└── Dockerfile       # Container build

المتطلبات الأساسية

الإعداد الأولي

git clone https://github.com/bedrud-ir/bedrud.git
cd bedrud
make init

التطوير الكامل

لتشغيل الحزمة بالكامل محليًا:

make dev

يُشغّل هذا LiveKit وخادم Go وخادم تطوير React بشكل متزامن. اضغط Ctrl+C لإيقاف جميع العمليات.

تشغيل الخدمات بشكل فردي

make dev-web

make dev-server

make dev-livekit

تطوير الخادم

نقطة الدخول لخادم Go هي server/cmd/server/main.go.

إضافة نقطة نهاية API

١. عرّف المعالج في server/internal/handlers/ ٢. أضف دوال المستودع في server/internal/repository/ إذا كانت هناك حاجة لاستعلامات جديدة في قاعدة البيانات ٣. سجّل المسار في إعداد الخادم (عادة في main.go أو ملف المسارات) ٤. أضف الوسيطة إذا كانت نقطة النهاية تحتاج مصادقة أو فحص صلاحيات المسؤول

تغييرات قاعدة البيانات

أضف أو عدّل هياكل نماذج GORM في server/internal/models/. يقوم GORM بالترحيل التلقائي عند البدء.

توثيق Swagger

تستخدم تعليقات توثيق API تنسيق swaggo. بعد التعديل، أعد التوليد:

cd server
swag init -g cmd/server/main.go

راجع بنية الخادم للاطلاع على هيكل الدليل الكامل والتصميم الطبقي.

تطوير واجهة الويب

توجد الواجهة في apps/web/ وتستخدم React 19 مع TanStack Start.

إضافة صفحة

أنشئ ملفًا جديدًا ضمن src/routes/ باتّباع اصطلاح التوجيه القائم على الملفات في TanStack Router (مثال: src/routes/settings.tsx). صدِّر Route مُنشأ باستخدام createFileRoute.

إضافة دالة عميل API

١. أضف الدالة في src/lib/api.ts باستخدام authFetch ٢. عرّف أنواع TypeScript مضمنة أو في ملف أنواع مشترك ٣. استخدم الدالة من مكوّن المسار، عادةً عبر خطاف useQuery من TanStack Query

فحص الأنواع

cd apps/web
bun run check    # runs Biome lint + TypeScript type check

راجع بنية واجهة الويب للاطلاع على الهيكل الكامل والأنماط.

تطوير Android

make dev-android    # Opens in Android Studio

الأنماط الأساسية

• جميع الشاشات دوال Composable
• التبعيات تأتي من InstanceManager عبر koinInject()
• استخدم collectAsState().value ?: return لقيم StateFlow القابلة للقيمة الفارغة
• التنقل مُدار في MainActivity.kt

البناء

make build-android-debug    # Debug APK
make build-android          # Release APK (needs keystore)
make release-android        # Build + install on device

راجع بنية تطبيق Android للاطلاع على بنية التطبيق المحمول بالتفصيل.

تطوير iOS

make dev-ios    # Opens in Xcode

الأنماط الأساسية

• العروض هي هياكل SwiftUI
• التبعيات تأتي من InstanceManager عبر @EnvironmentObject
• استخدم الربط الاختياري للخصائص المنشورة القابلة للقيمة الفارغة
• التنقل يستخدم حزمة التنقل الأصلية في SwiftUI

توليد المشروع

إذا عدّلت project.yml، أعد توليد مشروع Xcode:

cd apps/ios
xcodegen generate

البناء

make build-ios          # Release archive
make build-ios-sim      # Simulator build
make export-ios         # Export IPA

راجع بنية تطبيق iOS للاطلاع على بنية التطبيق المحمول بالتفصيل.

تطوير سطح المكتب

تطبيق سطح المكتب موجود في apps/desktop/ وهو حزمة Rust في مساحة العمل.

المتطلبات الأساسية (Linux)

sudo apt-get install -y \
  libfontconfig1-dev libxkbcommon-dev libxkbcommon-x11-dev \
  libwayland-dev libgles2-mesa-dev libegl1-mesa-dev \
  libdbus-1-dev libsecret-1-dev \
  libasound2-dev

يتطلب Windows أداة Visual Studio Build Tools مع عبء عمل C++ (MSVC).

التشغيل

make dev-desktop    # cargo run -p bedrud-desktop

البناء

make build-desktop           # optimised binary for the current platform

الأنماط الأساسية

• جميع عناصر الواجهة مُعرَّفة في ملفات .slint ضمن apps/desktop/ui/؛ تُترجم إلى Rust وقت البناء بواسطة build.rs
• apps/desktop/src/ui/bridge.rs هو المكان الوحيد الذي تُربط فيه استدعيات Slint بمنطق Rust - أبقِ منطق الأعمال خارج ملفات .slint
• استخدم Weak<AppWindow> عند تشغيل مهام خلفية تحتاج لتحديث الواجهة

راجع بنية تطبيق سطح المكتب للاطلاع على بنية تطبيق سطح المكتب بالتفصيل.

تطوير وكلاء البوت

الوكلاء موجودون في agents/ بمجلد واحد لكل وكيل.

cd agents/music_agent
pip install -r requirements.txt
python agent.py "http://localhost:8090/m/test-room"

جميع الوكلاء يحتاجون خادم Bedrud قيد التشغيل للمصادقة ضده.

CI/CD

يعمل GitHub Actions عند كل دفع إلى main وعند طلبات السحب:

يُفعَّل البناء للإصدار بواسطة وسوم الإصدارات (v*).

نمط الكود

• Go: التنسيق القياسي gofmt
• TypeScript/React: Biome (مُكوَّن في apps/web/biome.json)
• Kotlin: التنسيق الافتراضي في Android Studio
• Swift: التنسيق الافتراضي في Xcode

الاختبار

cd server
go test ./...

cd apps/web
bun run check

cd apps/android
./gradlew test

make build-ios-sim   # Builds and runs tests

انظر أيضًا

• مرجع Makefile - جميع أوامر البناء والتطوير
• نظرة عامة على البنية - كيف تتلاءم المكونات معًا