# راهنمای توسعه‌دهنده (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`](../architecture/architecture.md) و [`module-boundaries.md`](../architecture/module-boundaries.md).

## ۳. راه‌اندازی با Docker
```bash
cp .env.example .env
docker compose up -d --build
```
سرویس‌ها: Core API روی `:8000`، Identity روی `:8001`، Frontend روی `:3000`،
Keycloak روی `:8080`. همه با `docker compose up -d --build` بالا می‌آیند.

## ۴. راه‌اندازی محلی — Backend
```bash
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
```bash
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)
```bash
cd backend/core-service
alembic revision --autogenerate -m "توضیح"
alembic upgrade head
```

## ۱۰. اجرای تست‌ها (Backend)
```bash
cd backend/core-service
pytest -q
```

## ۱۱. Celery
```bash
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`](coding-standards.md) و [`project-principles.md`](project-principles.md).
- منطق کسب‌وکار فقط در backend (`services/`).
- UI فقط در frontend.
- خطاها از `shared.exceptions` استفاده کنند.

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

## Related Documents

- [Architecture Overview](../architecture/architecture.md)
- [Testing Strategy](testing-strategy.md)
- [Deployment](../deployment/deployment.md)
- [Services Contracts](../reference/services-contracts.md)