kwork-api/docs/HAR_ENDPOINTS_MAPPING.md

# HAR Endpoints Mapping

Сопоставление endpoints из `client.py` с реальными endpoints из HAR файла.

---

## 📊 Сопоставление endpoints

### ✅ Работающие endpoints (совпадают с HAR)

| client.py Endpoint | HAR Endpoint | Status | Notes |
|-------------------|--------------|--------|-------|
| `/projects` | `POST /projects` | ✅ 200 | GET в HAR, POST в client.py |
| `/api/validation/checktext` | N/A | ❓ | Нет в HAR - возможно не использовался |

---

### ❌ Неработающие endpoints (нужно исправить)

| client.py Endpoint | HAR Endpoint (реальный) | Status | Как исправить |
|-------------------|------------------------|--------|---------------|
| `/catalogMainv2` | `GET /categories/{slug}` | ❌ 404 | Использовать `GET /categories/{slug}` или найти JSON API |
| `/getKworkDetails` | `GET /projects/{id}/view` | ❌ 404 | Использовать `GET /projects/{id}/view` |
| `/userReviews` | `POST /user/get_reviews` | ❌ 404 | ✅ Исправить на `/user/get_reviews` |
| `/cities` | N/A | ❌ 404 | Нет в HAR - возможно через HTML страницу |
| `/countries` | N/A | ❌ 404 | Нет в HAR - возможно через HTML страницу |
| `/user` | `GET /user/{username}` | ❌ 404 | ✅ Исправить на `/user/{username}` |

---

## 🔍 Детальный анализ

### 1. Каталог кворков

**Текущий (не работает):**
```python
POST /catalogMainv2  # ❌ 404 Not Found
```

**Реальный из HAR:**
```
GET /categories/design  # ✅ 200 OK
GET /projects           # ✅ 200 OK
```

**Проблема:** HAR показывает HTML страницы, не JSON API.

**Решение:** Нужно найти JSON API endpoint или парсить HTML.

**Как найти:**
1. Открыть DevTools → Network → XHR/Fetch
2. Перейти на https://kwork.ru/categories/design
3. Искать JSON запросы с данными кворков
4. Или искать в HAR файлы с "kworks", "catalog", "list"

---

### 2. Детали кворка

**Текущий (не работает):**
```python
POST /getKworkDetails  # ❌ 404 Not Found
```

**Реальный из HAR:**
```
GET /projects/3127023/view  # ✅ 200 OK
```

**Проблема:** HAR показывает HTML страницу проекта.

**Решение:** Использовать `GET /projects/{id}/view` и парсить HTML.

**Как найти JSON API:**
1. Открыть DevTools → Network → XHR/Fetch
2. Перейти на https://kwork.ru/projects/{id}/view
3. Искать JSON запросы

---

### 3. Отзывы пользователя

**Текущий (не работает):**
```python
POST /userReviews  # ❌ 404 Not Found
```

**Реальный из HAR:**
```
POST /user/get_reviews  # ✅ 200 OK
Payload: {"userId":126921,"type":"positive"}
```

**Решение:** ✅ Исправить endpoint на `/user/get_reviews`

---

### 4. Информация о пользователе

**Текущий (не работает):**
```python
POST /user  # ❌ 404 Not Found
```

**Реальный из HAR:**
```
GET /user/jtjagomega         # ✅ 200 OK (HTML страница)
GET /user/alexey-liss        # ✅ 200 OK (HTML страница)
POST /api/user/checknotify   # ✅ 200 OK (JSON API, уведомления)
```

**Проблема:** Kwork **НЕ предоставляет JSON API** для user info!

**Решение:** 
- Для профиля: `GET /user/{username}` + парсинг HTML
- Для уведомлений: `POST /api/user/checknotify` (уже реализовано)

**В client.py сейчас:**
```python
# Временно используем checknotify как placeholder
return await self.client._request("POST", "/api/user/checknotify")
```

---

### 5. Справочные данные (города, страны)

**Текущие (не работают):**
```python
POST /cities    # ❌ 404 Not Found
POST /countries # ❌ 404 Not Found
```

**В HAR:** Нет таких endpoints.

**Проблема:** Возможно данные встроены в HTML или загружаются через JavaScript.

**Как найти:**
1. Открыть DevTools → Network
2. Перейти на страницу с формой (например, настройки)
3. Искать запросы с "cities", "countries", "regions"
4. Или искать в исходном коде страницы `<script>` с данными

**Альтернатива:** Парсить HTML страницу с формами.

---

## 🛠 План исправлений

### Приоритет 1 (есть в HAR):

1. ✅ `/userReviews` → `/user/get_reviews`
2. ✅ `/user` → `/user/{username}`

### Приоритет 2 (нужно искать):

3. 🔍 `/catalogMainv2` → искать JSON API или парсить HTML
4. 🔍 `/getKworkDetails` → использовать `/projects/{id}/view`
5. 🔍 `/cities`, `/countries` → искать в HTML или JavaScript

---

## 🔬 Как искать новые endpoints

### Метод 1: DevTools Network Tab

1. Открыть https://kwork.ru
2. DevTools (F12) → Network → XHR/Fetch
3. Выполнить действие (поиск, просмотр кворка и т.д.)
4. Искать JSON запросы

### Метод 2: Анализ HAR файла

```bash
cd /root
python3 << 'EOF'
import json
with open('kwork-dump.har') as f:
    har = json.load(f)

# Искать конкретные endpoints
for entry in har['log']['entries']:
    url = entry['request']['url']
    if 'catalog' in url or 'kwork' in url or 'review' in url:
        print(f"{entry['request']['method']} {url.split('?')[0]}")
EOF
```

### Метод 3: Поиск в JavaScript файлах

```bash
# Скачать все JS файлы и искать API endpoints
grep -r "api/" /path/to/js/files/ | grep -v ".map"
```

### Метод 4: Перехват трафика

Использовать mitmproxy для перехвата всех запросов:
```bash
mitmproxy --mode transparent --listen-port 8080
```

---

## 📝 Примечания

- **HAR файл** содержит только запросы которые были сделаны во время записи
- **Не все endpoints** попали в HAR (нужно дополнительно исследовать)
- **HTML vs JSON:** Kwork использует смешанный подход - некоторые данные в HTML, некоторые через JSON API
- **Динамические endpoints:** Некоторые endpoints могут требовать CSRF токены или другие заголовки

---

_Updated: 2026-03-29_