API для анализа данных ресторанов

Участники

Ревьюер - hitnes [Тимофей Кнутарев] Писал код у Iaroslav.Kharlov [Ярослав Харлов]

Совместный проект VibeCode - Командная разработка ПО с разделением ролей: Спецификация → Разработка → Ревью кода

📋 Обзор проекта

Этот проект реализует RESTful API для анализа данных ресторанов крупных индийских городов. Система предоставляет эндпоинты для поиска ресторанов с высоким рейтингом, анализа статистики по типам кухонь и выполнения анализа тональности на основе оценок клиентов.

Датасет

• Источник: Датасет ресторанов Swiggy
• Размер: 900+ ресторанов
• Охват: 8 крупных индийских городов (Бангалор, Мумбаи, Хайдарабад, Пуна, Калькутта, Ченнаи, Дели, Ахмадабад)
• Характеристики: Местоположение, рейтинги, цены, типы кухонь, метрики доставки

👥 Члены команды

Студент 1: Инженер по спецификации 🎯

Аккаунт GitVerse: @username1 (замените на реальный)

Роль: Создал комплексную спецификацию системы, включая:

• Определения эндпоинтов API
• Документацию структуры данных
• Функциональные требования
• Руководства по реализации

Вклад: Определил четкие требования в

Студент 2: Разработчик 💻

Аккаунт GitVerse: @username2 (замените на реальный)

Роль: Реализовал решение с использованием AI-ассистента:

• Разработал основные функции анализа данных
• Создал эндпоинты Django REST API
• Реализовал обработку ошибок и валидацию
• Создал модульные тесты

Процесс разработки:

• Используемый AI инструмент: GigaCode IDE 5.1+ / Cursor (укажите конкретный)
• Источник спецификации:
  spec/tasks.md
  загружен в контекст AI
• Работа по спецификации: @username1 (Студент 1)

Вклад: Полная реализация в папке

Студент 3: Ревьюер кода 🔍

Аккаунт GitVerse: @username3 (замените на реальный)

Роль: Провел ревью кода и контроль качества:

• Проверил соответствие спецификации
• Оценил качество и читаемость кода
• Выявил потенциальные улучшения
• Предоставил конструктивную обратную связь

Вклад: Комментарии к коду в Pull Request и артефакты в

🚀 Функциональность

Основные функции

1. get_top_restaurants(cuisine, location, min_reviews)
   • Возвращает рестораны с лучшим рейтингом, соответствующие критериям фильтра
   • Сортировка по рейтингу (по убыванию)
   • Фильтры по типу кухни, местоположению и минимальному количеству отзывов

2. get_cuisine_statistics(location)
   • Вычисляет средние рейтинги по типам кухонь
   • Определяет топ кухни в локации
   • Предоставляет общую статистику по локации
   • Включает анализ распределения тональности

3. get_review_sentiment_summary(restaurant_name)
   • Выполняет анализ тональности на основе рейтингов
   • Классифицирует отзывы как положительные/нейтральные/отрицательные
   • Возвращает оценку тональности и распределение

Эндпоинты REST API

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

team-work-ai-tx0/
├── spec/                      # Студент 1: Спецификации
│   ├── tasks.md              # Основная спецификация системы
│   ├── dataset.md            # Документация датасета
│   └── dataset.csv           # Данные ресторанов
├── dev/                       # Студент 2: Реализация
│   ├── solution.py           # Основные функции анализа
│   ├── api/                  # Django REST API
│   │   ├── views.py         # Представления API
│   │   ├── serializers.py   # Сериализаторы данных
│   │   └── urls.py          # Маршрутизация URL
│   └── tests/               # Модульные тесты
├── demo/                      # Студент 3: Артефакты ревью
│   ├── screenshots/         # Скриншоты тестирования API
│   ├── review.md           # Отчет о ревью кода
│   └── test_results.txt    # Результаты выполнения тестов
├── tasks/                    # Варианты заданий
│   └── task_variants.md
├── requirements.txt          # Зависимости Python
├── CONTRIBUTING.md           # Руководство по участию
└── README.md                # Этот файл

🛠️ Технологический стек

• Язык: Python 3.8+
• Фреймворк: Django + Django REST Framework
• Обработка данных: Pandas, NumPy
• Тестирование API: Postman / cURL
• Контроль версий: Git (GitVerse)

⚙️ Установка и настройка

Предварительные требования

Клонирование репозитория

Создание виртуального окружения

Установка зависимостей

Запуск сервера разработки

API будет доступен по адресу:

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

1. Получить топ ресторанов

Ответ:

2. Получить статистику по кухням

3. Получить анализ тональности

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

Запуск модульных тестов:

Ожидаемый результат: Все тесты пройдены ✅

📊 Процесс разработки

Временная шкала (90 минут)

1. Фаза спецификации (25-30 мин) - Студент 1

   • Создан
     spec/tasks.md
     с требованиями к системе
   • Документирована структура датасета в
     spec/dataset.md
   • Определены эндпоинты API и форматы ответов

2. Фаза разработки (35-40 мин) - Студент 2

   • Загружена спецификация в контекст AI-ассистента
   • Реализованы основные функции в
     dev/solution.py
   • Созданы эндпоинты Django REST API
   • Созданы сериализаторы и представления
   • Написаны модульные тесты

3. Фаза ревью (15-20 мин) - Студент 3

   • Проверен код на соответствие спецификации
   • Протестирована функциональность эндпоинтов API
   • Документированы результаты в
     demo/review.md
   • Созданы комментарии в Pull Request

Подход разработки с использованием AI

Студент 2 использовал AI-ассистента для кодирования следующим образом:

1. Загрузка
   spec/tasks.md
   в контекст AI
2. Запрос реализации каждой функции
3. Итеративное улучшение кода на основе спецификации
4. Генерация модульных тестов для валидации
5. Создание эндпоинтов API с корректной обработкой ошибок

Этот подход демонстрирует эффективное сотрудничество с AI-LLM, где:

• ✅ Четкие спецификации обеспечивают точную генерацию кода AI
• ✅ Разработчик сохраняет контроль и понимание
• ✅ AI обрабатывает шаблонный и повторяющийся код
• ✅ Человек проверяет и валидирует результаты

🎯 Ключевые результаты обучения

Студент 1 (Инженер по спецификации)

• Написание четких технических спецификаций
• Определение контрактов API и структур данных
• Документирование требований для разработчиков

Студент 2 (Разработчик)

• Эффективное использование AI-ассистентов для генерации кода
• Реализация согласно требованиям спецификации
• Написание тестируемого, поддерживаемого кода
• Разработка API с Django REST Framework

Студент 3 (Ревьюер кода)

• Навыки критического анализа кода
• Проверка соответствия спецификациям
• Выявление проблем качества кода
• Предоставление конструктивной обратной связи

🔍 Качество кода

Соответствие спецификации

• ✅ Все требуемые функции реализованы
• ✅ Эндпоинты API соответствуют спецификации
• ✅ Форматы ответов корректны
• ✅ Включена обработка ошибок

Метрики качества кода

• Читаемость: Высокая (понятные имена переменных, комментарии)
• Модульность: Хорошая (отдельные представления, сериализаторы, утилиты)
• Обработка ошибок: Комплексная (валидация ввода, граничные случаи)
• Тестирование: Модульные тесты для основной функциональности

📝 Примечания

• Источник датасета: данные ресторанов Swiggy (публичный датасет)
• Анализ тональности основан на рейтингах (упрощенный подход)
• API включает пагинацию для больших наборов результатов
• CORS включен для интеграции с фронтендом
• Ограничение запросов: 100 запросов/час на IP

📚 Документация

• Спецификация: См.
  spec/tasks.md
• Информация о датасете: См.
  spec/dataset.md
• Справочник по API: Доступен через браузерный API Django REST Framework
• Ревью кода: См.
  demo/review.md

🤝 Участие в проекте

Это образовательный проект, следующий методологии VibeCode. См.

📄 Лицензия

Образовательный проект для курсовой работы СибФУ.

Вариант проекта: #10
Учебный год: 2024-2025
Курс: Совместная разработка программного обеспечения