freelancer-match/README.md

# Freelancer Match — Умная площадка для фрилансеров

Площадка для фрилансеров и заказчиков с AI-подбором, escrow-гарантом сделок и рейтинговой системой.

## 🚀 Быстрый старт

### Требования
- Docker + Docker Compose
- Python 3.12+ (для локальной разработки)
- Node.js 20+ (для фронтенда)
- PostgreSQL 16+
- Redis 7+

### Запуск через Docker Compose

```bash
# 1. Скопируйте .env.example в .env и заполните переменные
cp backend/.env.example backend/.env

# 2. Запустите стек
docker compose up -d --build

# 3. Примените миграции БД
docker compose exec backend alembic upgrade head

# 4. Проверьте что всё работает
curl http://localhost:8000/api/health
```

### Локальная разработка

#### Backend
```bash
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
```

#### Frontend
```bash
cd frontend
npm ci
npm run dev
```

## 🔑 Настройка переменных окружения

Скопируйте `backend/.env.example` в `backend/.env` и заполните значения.

### Обязательные (без них не запустится)

| Переменная | Описание | Где взять |
|------------|----------|-----------|
| `DATABASE_URL` | Подключение к PostgreSQL | Создайте БД: `createdb freelancer_match` |
| `REDIS_URL` | Подключение к Redis | По умолчанию: `redis://localhost:6379/0` |
| `SECRET_KEY` | Ключ для JWT токенов | Сгенерируйте: `openssl rand -hex 32` |

### Опциональные (но нужны для полноценной работы)

| Переменная | Описание | Где взять |
|------------|----------|-----------|
| `OPENAI_API_KEY` | API ключ OpenAI для AI-матчинга | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |
| `STRIPE_SECRET_KEY` | Ключ Stripe для escrow | [dashboard.stripe.com/test/keys](https://dashboard.stripe.com/test/keys) (Test mode) |
| `STRIPE_WEBHOOK_SECRET` | Секрет для webhook Stripe | Настройте в Stripe Dashboard → Webhooks |

### Email (опционально)

| Переменная | Описание | Где взять |
|------------|----------|-----------|
| `SMTP_USER` | Email для отправки писем | Ваш email (Gmail, Mail.ru и т.д.) |
| `SMTP_PASSWORD` | Пароль SMTP | Для Gmail — используйте App Passwords (не обычный пароль) |

### OAuth (опционально, если хотите вход через Google/GitHub)

| Переменная | Описание | Где взять |
|------------|----------|-----------|
| `GOOGLE_CLIENT_ID` | OAuth client ID для входа через Google | [Google Cloud Console](https://console.cloud.google.com/apis/credentials) |
| `GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET` | OAuth для GitHub | [GitHub Developer Settings → OAuth Apps](https://github.com/settings/developers) |

## 📁 Структура проекта

```
freelancer-match/
├── backend/                    # FastAPI бэкенд
│   ├── app/
│   │   ├── api/               # API endpoints
│   │   ├── models/            # SQLAlchemy модели
│   │   ├── schemas/           # Pydantic схемы
│   │   ├── services/          # Бизнес-логика
│   │   └── core/              # Базовые модули (БД, безопасность)
│   ├── alembic/               # Миграции БД
│   ├── tests/                 # Тесты pytest
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/                   # Next.js фронтенд
│   ├── app/                   # App Router (pages)
│   ├── components/ui/         # UI компоненты
│   ├── lib/                   # Утилиты и провайдеры
│   ├── Dockerfile
│   └── package.json
├── docker-compose.yml          # Стек сервисов
└── .drone.yml                  # CI/CD для Drone CI
```

## 🧪 Тесты

```bash
# Backend (pytest)
cd backend && pytest tests/ -v

# Frontend (linting)
cd frontend && npx next lint
```

## 🔒 Безопасность

- JWT аутентификация с refresh токенами
- Хеширование паролей через bcrypt
- CORS middleware
- Escrow-гарант сделок (Stripe интеграция)
- AI-матчинг с pgvector эмбеддингами

## 📊 API Endpoints

| Метод | Endpoint | Описание |
|-------|----------|----------|
| POST | `/api/auth/register` | Регистрация пользователя |
| POST | `/api/auth/login` | Вход (JWT) |
| GET | `/api/projects` | Список проектов |
| POST | `/api/projects` | Создать проект |
| POST | `/api/ai/match-project` | AI-подбор фрилансеров |
| POST | `/api/escrow/create` | Создать escrow-транзакцию |

## 🚀 Деплой на сервер

```bash
# 1. Настройте .env.production
cp backend/.env.example backend/.env.production

# 2. Обновите docker-compose.yml для продакшена (уберите порты, добавьте healthcheck)

# 3. Запустите через Docker Compose
docker compose -f docker-compose.prod.yml up -d --build

# 4. Примените миграции
docker compose exec backend alembic upgrade head
```

## 🤖 CI/CD (Drone CI)

Проект настроен для автоматического деплоя через Drone CI:
- `.drone.yml` — пайплайн с тестами, сборкой и деплоем
- Настроен на Gitea (`ms.webhop.me`)
- Автоматический запуск при push в main

## 📝 Лицензия

MIT © 2026 Freelancer Match