این راهنما گردش کار توسعه روزانه برای مشارکت در Bedrud را پوشش می‌دهد.

چیدمان مخزن

bedrud/
├── server/          # بک‌اند Go
├── apps/
│   ├── web/         # فرانت‌اند React (TanStack Start)
│   ├── android/     # برنامه Android
│   ├── ios/         # برنامه iOS
│   └── desktop/     # برنامه دسکتاپ (Rust + Slint)
├── agents/          # عوامل ربات Python
├── packages/        # تعاریف نوع TypeScript مشترک
├── tools/cli/       # CLI استقرار
├── docs/            # مستندات (MkDocs)
├── Cargo.toml       # روت فضای کار Rust
├── Makefile         # ارکستراسیون ساخت
└── Dockerfile       # ساخت کانتینر

پیش‌نیازها

تنظیم اولیه

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/ اگر پرس‌وجوهای DB جدید نیاز است ۳. ثبت مسیر در تنظیمات سرور (معمولاً در main.go یا فایل routes) ۴. افزودن middleware اگر نقطه پایانی به بررسی‌های auth یا admin نیاز دارد

تغییرات دیتابیس

ساختارهای مدل 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 پیروی می‌کند (مثلاً src/routes/settings.tsx). یک Route ایجاد شده با createFileRoute صادر کنید.

افزودن یک تابع کلاینت API

۱. تابع را در src/lib/api.ts با استفاده از authFetch اضافه کنید ۲. انواع TypeScript را به صورت درون‌خطی یا در فایل انواع مشترک تعریف کنید ۳. از تابع از مولفه مسیر خود استفاده کنید، معمولاً هوک useQuery TanStack Query

بررسی نوع

cd apps/web
bun run check    # اجرای lint Biome + بررسی نوع TypeScript

به معماری فرانت‌اند وب برای ساختار کامل و الگوهای فرانت‌اند ببینید.

توسعه Android

make dev-android    # باز در Android Studio

الگوهای کلیدی

• تمام صفحات توابع Composable هستند
• وابستگی‌ها از InstanceManager از طریق koinInject() می‌آیند
• از collectAsState().value ?: return برای مقادیر StateFlow قابل تهی استفاده کنید
• ناوبری در MainActivity.kt مدیریت می‌شود

ساخت

make build-android-debug    # Debug APK
make build-android          # Release APK (نیاز به keystore)
make release-android        # ساخت + نصب روی دستگاه

به معماری برنامه Android برای معماری دقیق برنامه موبایل ببینید.

توسعه iOS

make dev-ios    # باز در Xcode

الگوهای کلیدی

• Views ساختارهای SwiftUI هستند
• وابستگی‌ها از InstanceManager از طریق @EnvironmentObject می‌آیند
• از پیوند اختیاری برای ویژگی‌های published قابل تهی استفاده کنید
• ناوبری از پشته ناوبری بومی SwiftUI استفاده می‌کند

تولید پروژه

اگر project.yml را تغییر دهید، پروژه Xcode را دوباره تولید کنید:

cd apps/ios
xcodegen generate

ساخت

make build-ios          # بایگانی انتشار
make build-ios-sim      # ساخت شبیه‌ساز
make export-ios         # صدور 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           # باینری بهینه برای پلتفرم فعلی

الگوهای کلیدی

• تمام UI در فایل‌های .slint زیر apps/desktop/ui/ تعریف می‌شود؛ در زمان ساخت به Rust توسط build.rs کامپایل می‌شود
• apps/desktop/src/ui/bridge.rs تنها جایی است که پاسخ‌های Slint به منطق Rust متصل می‌شوند - منطق تجاری را از فایل‌های .slint دور نگه دارید
• از Weak<AppWindow> هنگام ایجاد وظایف پس‌زمینه که نیاز به به‌روزرسانی UI دارند استفاده کنید

به معماری برنامه دسکتاپ برای معماری دقیق برنامه دسکتاپ ببینید.

توسعه عامل ربات

عوامل در agents/ با یک دایرکتوری برای هر عامل هستند.

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

همه عوامل به یک سرور Bedrud در حال اجرا برای احراز هویت نیاز دارند.

CI/CD

GitHub Actions در هر push به main و در هر درخواست pull اجرا می‌شود:

ساخت‌های انتشار توسط تگ‌های نسخه (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   # ساخت و اجرای تست‌ها

مشاهده همچنین

• مرجع Makefile - تمام دستورات ساخت و توسعه
• نمای کلی معماری - نحوه تناسب اجزا