peikarband/docs/development/setup.md

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

پیش‌نیازها

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

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

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

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

نصب

1. Clone Repository

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

2. Virtual Environment

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

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

# Windows:
venv\Scripts\activate

3. نصب Dependencies

# Core dependencies
pip install -r requirements.txt

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

# تایید نصب
pip list

4. Pre-commit Hooks

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

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

تنظیمات

1. Environment Variables

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

# ویرایش .env
nano .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:

python -c "import secrets; print(secrets.token_urlsafe(32))"

2. PostgreSQL Setup

# ایجاد دیتابیس
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

# شروع Redis
redis-server

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

4. Database Migrations

# اجرای migrations
alembic upgrade head

# بررسی
alembic current

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

python scripts/seed_database.py

اجرای پروژه

Development Mode

# روش 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

celery -A src.infrastructure.tasks.celery_app worker -l info

Terminal 2: Celery Beat (برای scheduled tasks)

celery -A src.infrastructure.tasks.celery_app beat -l info

Terminal 3: Flower (Celery monitoring)

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 جدید

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

2. کدنویسی

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

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

3. Testing

# همه تست‌ها
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

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

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

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

مشکل: Database Connection

# بررسی PostgreSQL
sudo systemctl status postgresql

# شروع PostgreSQL
sudo systemctl start postgresql

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

مشکل: Redis Connection

# بررسی Redis
redis-cli ping

# شروع Redis
redis-server

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

مشکل: Port Already in Use

# پیدا کردن 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

# بررسی 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

# Reset alembic
alembic downgrade base
alembic upgrade head

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

Test Failures

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

# اجرا با verbose
pytest -vv

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

---

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