VibeCode Project - Climate Analysis API

Трёхэтапная совместная разработка

👥 Участники проекта

Student 1: Specification Engineer

• Gitverse: f1ntxsy-AI(https://gitverse.ru/f1ntxsy-AI)
• Роль: Создание системной спецификации, определение требований
• Задачи: codex.md, архитектурные решения, требования к валидации

Student 2: Developer

• Gitverse: AlexanderBokay(https://gitverse.ru/AlexanderBokay)
• Роль: Реализация на Python + FastAPI
• Задачи: solution.py, API endpoints, логирование, обработка ошибок

Student 3: Code Reviewer

• Gitverse: EgorIzialnov(https://gitverse.ru/EgorIzialnov)

• Роль: Контроль качества, анализ кода

• Задачи: Проверка спецификации, рекомендации по улучшению

• Выполнял роль Student 2 у EgorIzialnov

📋 Описание проекта

VibeCode - это образовательный проект, моделирующий реальный процесс совместной разработки в IT-команде. Проект демонстрирует:

• ✅ Specification Engineering - документирование требований в стиле OpenAI system prompt
• ✅ Backend Development - реализация REST API с pandas и FastAPI
• ✅ Code Review - оценка качества кода по профессиональным стандартам
• ✅ Agile Workflow - трёхэтапный процесс за 90 минут

Основная задача

Создать REST API для анализа глобальных климатических данных с поддержкой:

• Статистики по городам за год
• Сравнения климата между городами за месяц
• Поиска экстремальных погодных дней
• Валидации и обработки 50K+ строк климатических данных

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

Backend & Data Processing

• Python 3.10+ - основной язык программирования
• pandas 2.0+ - обработка и анализ табличных данных
• numpy 1.24+ - численные операции и векторизация
• FastAPI 0.104+ - REST API framework (асинхронный)
• Uvicorn 0.24+ - ASGI сервер для запуска FastAPI

Data Validation & API

• Pydantic 2.0+ - валидация данных и типизация
• python-dateutil 2.8+ - работа с датами и временем

Testing & Development

• pytest 7.4+ - unit testing framework
• pytest-cov 4.1+ - покрытие тестами

Инструменты разработки

• Git/GitHub - версионный контроль и совместная разработка
• VS Code / GigaCodeIde / Cursor - IDE для написания кода
• PowerShell / Bash - командная строка для управления

📁 Структура репозитория

team_task/
│
├── 📄 README.md                    ← Этот файл (описание проекта)
├── 🗂️ demo/
│    └──📄 codex.md                     ← Спецификация (Student 1
│
├── 🗂️ demo/                        ← АРТЕФАКТЫ РАБОТАЮЩЕГО ПРИЛОЖЕНИЯ
│   ├── 📸 api_health_check.txt      ← Результат /health endpoint
│   ├── 📸 api_stats_response.json   ← Результат /stats/{city} endpoint
│   ├── 📸 api_compare_response.json ← Результат /compare endpoint
│   ├── 📸 api_extremes_response.json← Результат /extremes endpoint
│   ├── 📸 swagger_ui_screenshot.png ← Скриншот Swagger документации
│   ├── 📸 console_output.txt        ← Вывод консоли при запуске
│   └── 📸 cli_example_output.txt    ← Примеры curl запросов
└── 🗂️ demo/
     └── 🐍 solution.py                  ← Реализация (Student 2) 

🚀 Как запустить проект

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

2. Запуск API сервера

3. Доступ к API

Swagger UI (автоматическая документация):

http://localhost:8000/docs

ReDoc (альтернативная документация):

http://localhost:8000/redoc

📌 API Endpoints

GET /health

Проверка статуса приложения

GET /stats/{city}?year=2024

Статистика по городу за год

GET /compare?cities=Moscow,Dubai&month=2024-01

Сравнение климата между городами

GET /extremes?parameter=temperature&limit=5&operation=top

Поиск экстремальных дней

GET /data-info

Информация о загруженном датасете

📚 Использование как библиотеки (без API)

🧪 Запуск тестов

📝 Описание основных модулей (solution.py)

1. WeatherDataLoader

Класс для загрузки и валидации CSV данных

Ключевые методы:

• load_weather_data(filepath, encoding='utf-8')
  - загрузка с валидацией

Что делает:

• ✅ Проверяет существование файла
• ✅ Валидирует структуру CSV (7 столбцов)
• ✅ Конвертирует типы данных (datetime, float)
• ✅ Исключает future dates
• ✅ Проверяет диапазоны (temperature -50...+60, humidity 0...100)
• ✅ Обрабатывает отрицательные значения (wind_speed, precipitation)
• ✅ Сохраняет UTF-8 кодировку для названий городов

Пример ошибки:

2. ClimateAnalyzer

Класс для анализа климатических данных

Ключевые методы:

a) get_city_statistics()

b) compare_cities()

c) find_extreme_days()

3. FastAPI Application

REST API endpoints с автодокументацией

Features:

• ✅ Асинхронные endpoints (async/await)
• ✅ CORS middleware для кроссдоменных запросов
• ✅ Автоматическое создание Swagger UI
• ✅ HTTP статус коды (200, 400, 503, 500)
• ✅ Пидантик валидация request/response

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

Метрики спецификации

Компетенции

• Python Programming: Advanced (9/10)
• API Design: Advanced (9/10)
• Data Processing: Advanced (10/10)
• Error Handling: Advanced (10/10)
• Code Quality: Advanced (9/10)

📊 Примеры использования в demo/

В папке

1. api_health_check.txt - результат GET /health
2. api_stats_response.json - полный response /stats/Moscow
3. api_compare_response.json - результат сравнения 3 городов
4. api_extremes_response.json - топ 5 самых горячих дней
5. swagger_ui_screenshot.png - скриншот автодокументации
6. console_output.txt - вывод при запуске сервера
7. cli_example_output.txt - примеры curl команд

🔧 Требования к окружению

Минимальные требования:

• Python 3.10+
• pip или conda для управления пакетами
• 500MB свободной памяти (для датасета 50K строк)
• 100MB свободного места на диске

Операционные системы:

• ✅ Windows 10/11
• ✅ macOS 10.15+
• ✅ Linux (Ubuntu 20.04+, CentOS 8+)

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

Основные файлы

• codex.md - полная спецификация с требованиями (Student 1)
• solution.py - полная реализация (Student 2)
• REVIEW.md - code review отчет (Student 3)
• README.md - этот файл

Дополнительные ресурсы

• FastAPI документация
• Pandas документация
• Pydantic документация

🎯 Git Workflow

Branch структура

Commit история

📄 Лицензия

MIT License - свободное использование в образовательных целях

🤝 Контрибьютинг

Проект предназначен для образовательных целей в рамках VibeCode курса.

Правила участия:

1. Fork репозитория
2. Создать feature branch (
   git checkout -b feature/your-feature
   )
3. Commit изменения (
   git commit -m 'Add some feature'
   )
4. Push в branch (
   git push origin feature/your-feature
   )
5. Открыть Pull Request

❓ FAQ

Q: Как изменить путь к CSV файлу?

Q: Как добавить новый endpoint?

Q: Как запустить без FastAPI (только как библиотека)?

Q: Где находятся логи?

logs/climate_api.log

📞 Поддержка

• Issues: Создавайте GitHub issues для bagы
• Discussions: Используйте Discussions для вопросов
• Email: Контактная информация студентов выше