bearingsinfo/docs/it-infrastructure/API_DOCUMENTATION.md

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

📚 Обзор

Полнофункциональный RESTful API для поиска в справочнике подшипников с расширенными возможностями:

• ⚡ Автодополнение запросов
• 🔗 Рекомендации похожих документов
• 📊 История и аналитика поиска
• 💾 Экспорт результатов в JSON/CSV/XLSX

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

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

# 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

Примеры:

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

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

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

Ответ:

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

GET /autocomplete/popular

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

Параметры:

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

Пример:

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

---

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

GET /search

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

Параметры:

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

Примеры:

# Базовый поиск
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"

Ответ:

{
  "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)

Пример:

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

Ответ:

{
  "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)

Пример:

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

Ответ:

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

DELETE /history

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

Параметры:

• user_id (обязательный) - ID пользователя

Пример:

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

GET /history/popular

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

Параметры:

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

Пример:

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

Ответ:

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

---

5. Аналитика

GET /analytics/search

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

Параметры:

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

Пример:

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

Ответ:

{
  "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)

Примеры:

# 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

Пример:

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

POST /export/batch

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

Параметры:

• format (опционально) - формат: json, xlsx (по умолчанию: xlsx)

Body (JSON):

["6205", "6305", "6405"]

Пример:

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

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

python api/examples/search_features.py

---

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

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

# Установка 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.

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

# Обновить словарь автодополнения
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. Изучите примеры использования
2. Проверьте тесты
3. Создайте Issue в репозитории