bearingsinfo/docs/it-infrastructure/API_DOCUMENTATION.md

# API документация - Справочник подшипников

## 📚 Обзор

Полнофункциональный RESTful API для поиска в справочнике подшипников с расширенными возможностями:
- ⚡ Автодополнение запросов
- 🔗 Рекомендации похожих документов
- 📊 История и аналитика поиска
- 💾 Экспорт результатов в JSON/CSV/XLSX

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

### Установка и запуск

```bash
# 1. Установка зависимостей
pip install -r requirements.txt

# 2. Построение индексов
python scripts/build_autocomplete_dict.py
python scripts/build_search_index.py

# 3. Запуск сервера
uvicorn api.app.api:app --reload

# Или используйте скрипт:
./start_api.sh
```

API будет доступно по адресу: `http://localhost:8000`

Документация Swagger: `http://localhost:8000/docs`

## 📋 Endpoints

### 1. Автодополнение

#### `GET /autocomplete`

Автодополнение поисковых запросов.

**Параметры:**
- `q` (обязательный) - префикс для поиска (минимум 1 символ)
- `limit` (опционально) - количество предложений (по умолчанию: 10, макс: 50)
- `types` (опционально) - типы результатов: `term`, `bearing_code`, `brand`, `series`

**Примеры:**

```bash
# Базовый запрос
curl "http://localhost:8000/autocomplete?q=под"

# С фильтром по типу
curl "http://localhost:8000/autocomplete?q=SK&types=brand"

# С ограничением количества
curl "http://localhost:8000/autocomplete?q=620&limit=5"
```

**Ответ:**

```json
{
  "query": "под",
  "suggestions": [
    {
      "value": "подшипник",
      "type": "term",
      "frequency": 1240,
      "highlight": "<b>под</b>шипник"
    }
  ],
  "count": 10
}
```

#### `GET /autocomplete/popular`

Получить самые популярные термины.

**Параметры:**
- `limit` (опционально) - количество результатов (по умолчанию: 10)

**Пример:**

```bash
curl "http://localhost:8000/autocomplete/popular?limit=5"
```

---

### 2. Поиск документов

#### `GET /search`

Полнотекстовый поиск документов.

**Параметры:**
- `q` (обязательный) - поисковый запрос
- `include_similar` (опционально) - включить похожие документы (по умолчанию: true)
- `limit` (опционально) - количество результатов (по умолчанию: 20, макс: 100)
- `user_id` (опционально) - ID пользователя для сохранения в истории
- `session_id` (опционально) - ID сессии

**Примеры:**

```bash
# Базовый поиск
curl "http://localhost:8000/search?q=подшипник"

# С похожими документами
curl "http://localhost:8000/search?q=6205&include_similar=true"

# С сохранением в историю
curl "http://localhost:8000/search?q=SKF&user_id=user123"
```

**Ответ:**

```json
{
  "query": "6205",
  "total": 45,
  "results": [
    {
      "id": "doc_123",
      "title": "Подшипник 6205",
      "path": "Подшипники/6205.md",
      "excerpt": "...",
      "relevance": 0.95,
      "similar_documents": [
        {
          "id": "doc_456",
          "title": "Подшипник 6206",
          "path": "Подшипники/6206.md",
          "similarity": 0.85
        }
      ]
    }
  ]
}
```

---

### 3. Похожие документы

#### `GET /similar/{document_id}`

Получить похожие документы для конкретного документа.

**Параметры:**
- `document_id` (в пути) - ID документа
- `limit` (опционально) - количество похожих документов (по умолчанию: 5, макс: 20)

**Пример:**

```bash
curl "http://localhost:8000/similar/doc_123?limit=5"
```

**Ответ:**

```json
{
  "document_id": "doc_123",
  "similar": [
    {
      "id": "doc_456",
      "title": "Подшипник 6206",
      "path": "Подшипники/6206.md",
      "similarity": 0.85
    }
  ],
  "count": 5
}
```

---

### 4. История поиска

#### `GET /history`

Получить историю поиска пользователя.

**Параметры:**
- `user_id` (обязательный) - ID пользователя
- `limit` (опционально) - количество записей (по умолчанию: 50, макс: 200)

**Пример:**

```bash
curl "http://localhost:8000/history?user_id=user123&limit=10"
```

**Ответ:**

```json
{
  "user_id": "user123",
  "history": [
    {
      "query": "подшипник 6205",
      "timestamp": "2026-01-19T12:00:00Z",
      "results_count": 45
    }
  ],
  "count": 10
}
```

#### `DELETE /history`

Очистить историю поиска пользователя.

**Параметры:**
- `user_id` (обязательный) - ID пользователя

**Пример:**

```bash
curl -X DELETE "http://localhost:8000/history?user_id=user123"
```

#### `GET /history/popular`

Получить популярные поисковые запросы.

**Параметры:**
- `limit` (опционально) - количество запросов (по умолчанию: 10, макс: 50)

**Пример:**

```bash
curl "http://localhost:8000/history/popular?limit=10"
```

**Ответ:**

```json
{
  "popular": [
    {
      "query": "подшипник 6205",
      "count": 150
    }
  ],
  "count": 10
}
```

---

### 5. Аналитика

#### `GET /analytics/search`

Получить аналитику поисковых запросов.

**Параметры:**
- `period` (опционально) - период: `1d`, `7d`, `30d` (по умолчанию: `7d`)

**Пример:**

```bash
curl "http://localhost:8000/analytics/search?period=7d"
```

**Ответ:**

```json
{
  "period": "7d",
  "total_searches": 1240,
  "unique_queries": 456,
  "top_queries": [
    {"query": "6205", "count": 120}
  ],
  "zero_results_queries": [],
  "avg_results_per_query": 12.5
}
```

---

### 6. Экспорт результатов

#### `GET /search/export`

Экспорт результатов поиска в различных форматах.

**Параметры:**
- `q` (обязательный) - поисковый запрос
- `format` (обязательный) - формат: `json`, `csv`, `xlsx`
- `limit` (опционально) - количество результатов (по умолчанию: 100, макс: 1000)

**Примеры:**

```bash
# JSON
curl "http://localhost:8000/search/export?q=6205&format=json" > results.json

# CSV
curl "http://localhost:8000/search/export?q=6205&format=csv" > results.csv

# Excel
curl "http://localhost:8000/search/export?q=6205&format=xlsx" > results.xlsx
```

#### `GET /analogs/{bearing_code}/export`

Экспорт списка аналогов подшипника.

**Параметры:**
- `bearing_code` (в пути) - код подшипника
- `format` (обязательный) - формат: `json`, `csv`, `xlsx`

**Пример:**

```bash
curl "http://localhost:8000/analogs/6205/export?format=xlsx" > analogs_6205.xlsx
```

#### `POST /export/batch`

Массовый экспорт результатов для списка запросов.

**Параметры:**
- `format` (опционально) - формат: `json`, `xlsx` (по умолчанию: `xlsx`)

**Body (JSON):**
```json
["6205", "6305", "6405"]
```

**Пример:**

```bash
curl -X POST "http://localhost:8000/export/batch?format=xlsx" \
  -H "Content-Type: application/json" \
  -d '["6205", "6305", "6405"]' \
  > batch_export.xlsx
```

---

## 🔧 Примеры использования

Полные примеры использования API находятся в файле: [`api/examples/search_features.py`](../api/examples/search_features.py)

Запуск примеров:

```bash
python api/examples/search_features.py
```

---

## 🧪 Тестирование

Для запуска тестов:

```bash
# Установка pytest
pip install pytest pytest-cov

# Запуск всех тестов
pytest api/tests/ -v

# Запуск конкретного теста
pytest api/tests/test_autocomplete.py -v

# С покрытием кода
pytest api/tests/ --cov=api/app --cov-report=html
```

---

## 📊 Архитектура

### Компоненты системы

```
api/
├── app/
│   ├── api.py              # FastAPI приложение, endpoints
│   ├── logic.py            # Бизнес-логика (автодополнение, поиск)
│   └── export_utils.py     # Утилиты экспорта
├── tests/                  # Тесты
└── examples/               # Примеры использования

scripts/
├── build_autocomplete_dict.py   # Построение словаря автодополнения
└── build_search_index.py        # Построение индекса документов

data/
├── autocomplete_dict.json       # Словарь для автодополнения
├── document_index.json          # Индекс документов
└── similarity_matrix.json       # Матрица схожести документов
```

### Технологии

- **FastAPI** - современный веб-фреймворк
- **scikit-learn** - TF-IDF и косинусное расстояние
- **pandas + openpyxl** - экспорт в Excel
- **pytest** - тестирование

---

## 🔄 Обновление индексов

Индексы обновляются автоматически каждое воскресенье в 2:00 UTC через GitHub Actions.

Для ручного обновления:

```bash
# Обновить словарь автодополнения
python scripts/build_autocomplete_dict.py

# Обновить индекс документов и матрицу схожести
python scripts/build_search_index.py
```

---

## 🐛 Решение проблем

### API не запускается

1. Проверьте, что установлены все зависимости: `pip install -r requirements.txt`
2. Проверьте версию Python (требуется 3.8+): `python --version`
3. Убедитесь, что порт 8000 свободен

### Нет результатов автодополнения

1. Убедитесь, что построен словарь: `data/autocomplete_dict.json`
2. Если нет, запустите: `python scripts/build_autocomplete_dict.py`

### Ошибки при экспорте в Excel

1. Убедитесь, что установлены библиотеки: `pip install pandas openpyxl`
2. Проверьте права на запись в директорию

---

## 📝 Лицензия

Открытый исходный код для образовательных целей.

---

## 🤝 Поддержка

Если у вас возникли вопросы или проблемы:

1. Изучите [примеры использования](../api/examples/search_features.py)
2. Проверьте [тесты](../api/tests/)
3. Создайте [Issue](https://github.com/ArtemFilin1990/Mar/issues) в репозитории