TorbatYar/docs/development/developer-guide.md

راهنمای توسعه‌دهنده (Developer Guide)

۱. پیش‌نیازها

• Python 3.11+ (backend)
• Node.js 18+ (frontend)
• Docker و Docker Compose (برای اجرای کامل)
• PostgreSQL 15+ و Redis (در صورت اجرای بدون Docker)

۲. قانون جداسازی Frontend/Backend (اجباری)

• تمام کد backend فقط در backend/ قرار دارد.
• تمام کد frontend فقط در frontend/ قرار دارد.
• ارتباط فقط از طریق REST API نسخه‌دار (lib/api-client.ts در frontend).
• جزئیات در architecture.md و module-boundaries.md.

۳. راه‌اندازی با Docker

cp .env.example .env
docker compose up -d --build

سرویس‌ها: Core API روی :8000، Identity روی :8001، Accounting روی :8002، CRM روی :8003، Loyalty روی :8004، Communication روی :8005، Sports Center روی :8006، Frontend روی :3000، Keycloak روی :8080. همه با docker compose up -d --build بالا می‌آیند.

۴. راه‌اندازی محلی — Backend

cd backend/core-service
python -m venv .venv
# Windows: .venv\Scripts\Activate.ps1  |  Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload

۵. راه‌اندازی محلی — Frontend

cd frontend
npm install
npm run dev

Frontend: http://localhost:3000

۶. متغیرهای محیطی

همه تنظیمات در .env هستند (نمونه: .env.example). هیچ مقداری در کد hardcode نمی‌شود.

Backend: DATABASE_URL, DATABASE_URL_SYNC, REDIS_URL, CELERY_BROKER_URL, KEYCLOAK_*, INTERNAL_TOKEN_SECRET, PLATFORM_*.

Frontend: NEXT_PUBLIC_API_BASE_URL (پیش‌فرض: http://localhost:8000).

۷. ساختار backend

backend/
├── core-service/app/
│   ├── api/v1/        # routerها
│   ├── core/          # config, database, cache, security, logging
│   ├── models/        # مدل‌های SQLAlchemy
│   ├── schemas/       # اسکیماهای Pydantic
│   ├── services/      # منطق کسب‌وکار
│   ├── repositories/  # دسترسی به داده
│   ├── middlewares/   # تشخیص tenant
│   ├── workers/       # Celery
│   └── tests/         # تست‌ها
├── shared-lib/        # کتابخانه مشترک backend
└── services/          # placeholder سرویس‌های آینده

۸. ساختار frontend

frontend/
├── app/          # صفحات Next.js (App Router)
├── components/   # کامپوننت‌های UI
├── hooks/        # React hooks
├── lib/          # API client، theme
├── styles/       # CSS global
└── public/       # فایل‌های استاتیک

۹. Migrations (Alembic)

cd backend/core-service
alembic revision --autogenerate -m "توضیح"
alembic upgrade head

۱۰. اجرای تست‌ها (Backend)

cd backend/core-service
pytest -q

۱۱. Celery

cd backend/core-service
celery -A app.workers.celery_app.celery_app worker -Q default,core_events,notifications,webhooks
celery -A app.workers.celery_app.celery_app beat

۱۲. الگوهای کدنویسی

• کامل در coding-standards.md و project-principles.md.
• منطق کسب‌وکار فقط در backend (services/).
• UI فقط در frontend.
• خطاها از shared.exceptions استفاده کنند.

۱۳. افزودن سرویس جدید (فازهای بعدی)

1. پوشه سرویس را در backend/services/ توسعه دهید.
2. دیتابیس مستقل با tenant_id بسازید.
3. قابلیت‌ها را در Core ثبت کنید و module-registry.md را به‌روز کنید.
4. UI مربوطه را در frontend/ بسازید (فقط از API استفاده کند).
5. ارتباط را فقط از طریق API/Event برقرار کنید.
6. مستندات architecture/reference/phase را همزمان به‌روز کنید — docs/README.md.

Related Documents

• Architecture Overview
• Testing Strategy
• Deployment
• Services Contracts