peikarband/docs/development/setup.md

# راهنمای راه‌اندازی محیط توسعه

## پیش‌نیازها

### نرم‌افزارهای مورد نیاز

| نرم‌افزار | نسخه مورد نیاز | لینک نصب |
|-----------|----------------|----------|
| Python | 3.11+ | [python.org](https://python.org) |
| PostgreSQL | 14+ | [postgresql.org](https://postgresql.org) |
| Redis | 7+ | [redis.io](https://redis.io) |
| Node.js | 18+ | [nodejs.org](https://nodejs.org) |
| Git | 2.x+ | [git-scm.com](https://git-scm.com) |

### بررسی نسخه‌ها

```bash
python --version  # باید 3.11 یا بالاتر
psql --version    # باید 14 یا بالاتر
redis-cli --version  # باید 7 یا بالاتر
node --version    # باید 18 یا بالاتر
git --version
```

## نصب

### 1. Clone Repository

```bash
git clone https://github.com/yourusername/peikarband.git
cd peikarband
```

### 2. Virtual Environment

```bash
# ایجاد virtual environment
python -m venv venv

# فعال‌سازی
# Linux/Mac:
source venv/bin/activate

# Windows:
venv\Scripts\activate
```

### 3. نصب Dependencies

```bash
# Core dependencies
pip install -r requirements.txt

# Development dependencies
pip install -r requirements-dev.txt

# تایید نصب
pip list
```

### 4. Pre-commit Hooks

```bash
# نصب pre-commit hooks
pre-commit install

# تست (اختیاری)
pre-commit run --all-files
```

## تنظیمات

### 1. Environment Variables

```bash
# کپی فایل example
cp .env.example .env

# ویرایش .env
nano .env
```

**متغیرهای ضروری**:

```env
# Database
DATABASE_URL=postgresql://username:password@localhost:5432/peikarband

# Redis
REDIS_URL=redis://localhost:6379/0

# Security
SECRET_KEY=generate-a-secure-random-key
JWT_SECRET_KEY=generate-another-secure-random-key

# Celery
CELERY_BROKER_URL=redis://localhost:6379/1
CELERY_RESULT_BACKEND=redis://localhost:6379/2
```

**تولید Secret Key**:
```bash
python -c "import secrets; print(secrets.token_urlsafe(32))"
```

### 2. PostgreSQL Setup

```bash
# ایجاد دیتابیس
createdb peikarband

# یا با psql
psql -U postgres
CREATE DATABASE peikarband;
CREATE USER peikarband_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE peikarband TO peikarband_user;
\q
```

### 3. Redis Setup

```bash
# شروع Redis
redis-server

# تست
redis-cli ping
# باید "PONG" برگرداند
```

### 4. Database Migrations

```bash
# اجرای migrations
alembic upgrade head

# بررسی
alembic current
```

### 5. Seed Database (اختیاری)

```bash
python scripts/seed_database.py
```

## اجرای پروژه

### Development Mode

```bash
# روش 1: با Reflex
python -m reflex run

# روش 2: با auto-reload
python -m reflex run --reload

# روش 3: با loglevel
python -m reflex run --loglevel debug
```

### Background Services

**Terminal 1**: Celery Worker
```bash
celery -A src.infrastructure.tasks.celery_app worker -l info
```

**Terminal 2**: Celery Beat (برای scheduled tasks)
```bash
celery -A src.infrastructure.tasks.celery_app beat -l info
```

**Terminal 3**: Flower (Celery monitoring)
```bash
celery -A src.infrastructure.tasks.celery_app flower
# دسترسی: http://localhost:5555
```

### دسترسی به Application

- **Frontend**: http://localhost:3000
- **Backend API**: http://localhost:8000
- **Flower (Celery)**: http://localhost:5555

## Development Workflow

### 1. Branch جدید

```bash
git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name
```

### 2. کدنویسی

```bash
# قبل از commit
black src/
isort src/
flake8 src/
mypy src/

# یا با pre-commit
pre-commit run --all-files
```

### 3. Testing

```bash
# همه تست‌ها
pytest

# با coverage
pytest --cov=src tests/

# تست‌های خاص
pytest tests/unit/
pytest tests/integration/

# تست یک فایل
pytest tests/unit/test_user.py

# تست یک function
pytest tests/unit/test_user.py::test_create_user
```

### 4. Commit

```bash
git add .
git commit -m "feat(scope): description"
git push origin feature/your-feature-name
```

### 5. Pull Request

1. Create PR از feature branch به develop
2. منتظر code review باشید
3. اصلاحات لازم را انجام دهید
4. Merge

## Troubleshooting

### مشکل: ModuleNotFoundError

```bash
# مطمئن شوید که در virtual environment هستید
which python
# باید به venv اشاره کند

# نصب مجدد
pip install -r requirements.txt
```

### مشکل: Database Connection

```bash
# بررسی PostgreSQL
sudo systemctl status postgresql

# شروع PostgreSQL
sudo systemctl start postgresql

# تست connection
psql -U username -d peikarband
```

### مشکل: Redis Connection

```bash
# بررسی Redis
redis-cli ping

# شروع Redis
redis-server

# بررسی port
netstat -an | grep 6379
```

### مشکل: Port Already in Use

```bash
# پیدا کردن process
lsof -i :3000
lsof -i :8000

# Kill process
kill -9 <PID>
```

## ابزارهای مفید

### IDE Setup

**VS Code Extensions**:
- Python
- Pylance
- Python Test Explorer
- GitLens
- Better Comments

**PyCharm**: تنظیمات پیشنهادی در `.idea/` موجود است.

### Database Tools

- **pgAdmin**: GUI برای PostgreSQL
- **DBeaver**: Multi-database tool
- **TablePlus**: Modern database GUI

### API Testing

- **httpie**: `pip install httpie`
- **Postman**: Desktop app
- **Insomnia**: Alternative to Postman

## بروزرسانی Dependencies

```bash
# بررسی dependencies قدیمی
pip list --outdated

# بروزرسانی یک package
pip install --upgrade package-name

# بروزرسانی همه (با دقت!)
pip install --upgrade -r requirements.txt

# ذخیره نسخه‌های جدید
pip freeze > requirements.txt
```

## مشکلات رایج

### Import Error

اطمینان حاصل کنید که:
- Virtual environment فعال است
- `PYTHONPATH` صحیح است
- همه `__init__.py` ها موجودند

### Alembic Migration Error

```bash
# Reset alembic
alembic downgrade base
alembic upgrade head

# ایجاد migration جدید
alembic revision --autogenerate -m "description"
```

### Test Failures

```bash
# پاک کردن cache
pytest --cache-clear

# اجرا با verbose
pytest -vv

# اجرا با output کامل
pytest -s
```

---

**نکته**: این راهنما همیشه به‌روز نگه داشته می‌شود. در صورت مشکل به team lead مراجعه کنید.