| External Testing Results (ETR) - приложение по отслеживанию посылок учеников на Codeforces API. В перспективе не только с Codeforces. |
| |
| Документация для работы с [API Codeforces|https://codeforces.com/apiHelp]. |
| |
| Исходники доступны по [ссылке|https://dl-gsu-by.jetbrains.space/p/main/repositories/etr/files/README.md]. |
| |
| h1. Инструкция новичку |
| |
| |
| h2. Что нужно знать |
| |
| Перед разработкой рекомендую почитать страницу про [новые проекты на Python для dl|http://confluence.newit.gsu.by/pages/viewpage.action?pageId=52264984]. |
| |
| Что такое git и как с ним работать. Про это можно почитать [здесь|https://git-scm.com/book/ru]. |
| |
| Python - основы программирования, такие, как ООП, уверено писать циклы и ифы. Материалов по этой теме много, достаточно в поиск написать "изучить python" если это вам необходимо. Можете почить [это|https://academy.yandex.ru/handbook/python/] для изучения. |
| |
| Flask - фреймворк, без которой мы бы здесь не собрались. Про flask очень много инфы и книг. Можно почитать [тут(англ)|https://flask.palletsprojects.com/en/]и [здесь|https://habr.com/ru/articles/193242/]. |
| |
| SQLAlchemy - это библиотека для работы с базами данных. Про эту библиотеку можете почитать на [сайте(англ)|https://www.sqlalchemy.org/], или [здесь|https://habr.com/ru/articles/470285/]. |
| |
| Так же, надо немного почитать про SQL базы данных - что это такое, как они работают и как с ними работать. Проект работает с MySQL, поэтому лучше искать материал близкий к MySQL. Но, в целом, они все очень похожи. Для погружения в вопрос могу посоветовать [этот|https://metanit.com/sql/mysql/] материал. |
| |
| Pydantic - отвечает за валидацию данных, тоесть проверку их корректности (email правильный и т.п.). Можно почитать [здесь(англ)|https://docs.pydantic.dev/latest/]. |
| |
| Также почитать про методологию git flow. Почитать поподробнее [здесь|https://www.atlassian.com/ru/git/tutorials/comparing-workflows/gitflow-workflow] и [здесь|https://habr.com/ru/articles/765264/]. |
| |
| Будет неплохо обладать навыками работы с pytest. Как писать и запускать тесты почитать [тут(англ)|https://docs.pytest.org/en/7.4.x/]. |
| |
| Также подойдут иные обучающие материалы по заданным технологиям. |
| |
| h2. Первоначальная настройка |
| |
| Первоначально необходимо получить исходники. Исходники etr можно найти, например, [здесь|https://dl-gsu-by.jetbrains.space/p/main/repositories/etr/files/README.md]. |
| |
| Для скачивания исходников необходимо установить git. |
| |
| Далее открываем консоль (на windows можно нажать Win+R и написать cmd либо powershell). В консоли пишем |
| {code} |
| git clone https://git.jetbrains.space/dl-gsu-by/main/etr.git |
| {code} |
| Также, исходники можно получить, например, через IDE. |
| |
| Далее скачиваем и устанавливаем (если еще этого не сделали) любую IDE для Python. Рекомендую присмотреться к [VS Code|https://code.visualstudio.com/] или [PyCharm|https://www.jetbrains.com/pycharm/]. В IDE открываем исходники. |
| |
| Ниже указаны инструкции по запуску проекта. |
| |
| Поздравляю\! Вы можете запустить проект и следить за другими\! |
| |
| h1. Стек технологий |
| |
| Приложение написано на Flask. Для валидирования данных используется Pydantic. В качестве базы данных используется MySQL. Для работы с БД используется библиотека SQLAlchemy. Для работы с API Codeforces используется библиотека requests. |
| |
| h1. Как запустить? |
| |
| Перед запуском необходимо проинициализировать файл *_.env{_}*. Пример находится в [README.md|https://dl-gsu-by.jetbrains.space/p/main/repositories/etr/files/README.md]. |
| |
| Для запуска достаточно прописать: |
| {code} |
| flask --app etr run |
| {code} |
| Более актуальная информация для запуска проекта может находится в [README.md|https://dl-gsu-by.jetbrains.space/p/main/repositories/etr/files/README.md]. |
| |
| Также, можно запустить в Docker образе. Все необходимы команды написаны в README.md. |
| |
| h2. Обзор параметров .env |
| |
| В README.md лежит пример файла .env. В этом разделе опишу поля, которые могут встретится в .env файле. |
| || параметр \\ || тип, значение \\ || пример \\ || |
| | URL_PREFIX | строка, обозначает префикс для всех url. Является необходимым на сервере, при локальной разработке может быть опущен. \\ | URL_PREFIX=/etr \\ | |
| | URL_DATABASE | строка, обозначает адрес до базы данных. Если не указана примет значение _"sqlite:///storage/users.db"_ \\ | URL_DATABASE=mysql+mysqlconnector://root:<password>@localhost:3306 \\ | |
| \\ |
| |
| h1. Структура проекта |
| |
| |
| h2. Общая информация |
| |
| В проекте есть несколько модулей: |
| * *models* \- представляет собой схему в базе данных. Каждый модуль отображает таблицу (в некоторых случаях таблицы) из базы данных; |
| * *schemas* \- отвечает за валидирование данных на входе и на выходе; |
| * *templates* \- содержит в себе шаблоны frontend части; |
| * *views* \- отвечает за обработку пользовательских запросов. |
| |
| h2. How It's Made |
| |
| На момент последней версии (v0.1.1) проект обрабатывает следующие запросы: |
| * GET /etr/user - возвращает html с таблицей всех пользователей в базе данных |
| * GET /etr/user/new - возвращает html форму для добавления нового пользователя |
| * POST /etr/user/new - принимает на вход handle с Codeforces и добавляет его в базу данных |
| * GET /etr/contest - возвращает html с таблицей всех отслеживаемых контестов |
| * GET /etr/contest/new - возвращает html форму для добавления нового контеста |
| * POST /etr/contest/new - ожидает id контеста и добавляет его в базу данных |
| * GET /etr/status - возвращает таблицу, содержащую все отправки отслеживаемых учеников (BBIWY) на отслеживаемые контесты |
| |
| h1. Как вносить свой вклад в развитие? |
| |
| Вы узнали немного о проекте, о его первоначальной настройке, о его возможностях и о том как его запускать. Настало время кодить. |
| |
| При разработке используется модель git flow. Про эту методологию можно почитать поподробнее [здесь|https://habr.com/ru/articles/765264/]и [здесь|https://www.atlassian.com/ru/git/tutorials/comparing-workflows/gitflow-workflow]. Вкратце можно выделить следующие этапы: |
| * переключаемся на ветку dev |
| * от ветки dev создаем свою ветку, называя ее hotfix/..., features/..., ... |
| * переключаемся на только что созданную ветку |
| * вносим в нее свои изменения, при этом в идеале пишем информативные коммиты |
| * после того, как внесли свои изменения документируем их и пишем на них тесты |
| * после этого, мержим с dev веткой |
| |
| h1. TODO проекта |
| |
| Здесь собраны всевозможные хотелки, которые реализуем, реализуются или будут реализовываться. |
| * возможно пригодится, давать возможность ученикам отправлять свои решения на etr для контестов; |
| * добавить возможность вставлять ссылку вместо id контеста; |
| * обработать ситуацию добавления одного и того же контеста 2 раза; |
| * локализация; |
| * {color:1f497d}{*}добавить показ информации о контесте за определенный период (от ... до ...)*{color} |
| * {color:1f497d}{*}рейтинги cf юзеров отобразить{*}{color} |
| * {color:1f497d}Фамилию Имя, Город и Учебное заведение брать, как и Класс, из списка{color} {color:1f497d}dl{color}{color:1f497d}/{color}{color:1f497d}codeforces{color} |
| | * {color:1f497d}{*}Предлагаю для тренировок сделать отдельный пункт меню «Тренировки» (там пункт «во время контеста» вообще убрать нужно)*{color} |
| | * {color:1f497d}{*}Предлагаю для тренировок сделать отдельный пункт меню «Тренировки» (там пункт «во время контеста» вообще убрать нужно)\*{color} |
| {color:1f497d}{*}Сейчас станет две тренировки{*}{color} |
| {color:1f497d}{*}104772 и 104730{*}{color} |
| * {color:1f497d}{*}Там, где у них нет даже посылок - не надо их отображать (их не было ни в официальном контесте, ни в дорешивании пока)*{color} |
| {color:1f497d}{*}это касается всех таблиц (речь о юзерах, которые в данном типе контеста не участвовали, но в целом решали контест)*{color} |
| * {color:1f497d}{*}надо сделать по умолчанию не "все", а контест{*}{color} |
| * {color:1f497d}{*}баллы и рейтинг за задачу не всегда обновляется (поставить в ночное?)*{color} |
| * {color:1f497d}*/etr/api/user/*{color} |
| {user_id}{color:1f497d}/problems не работает без verdict{color} |
| * {color:1f497d}{*}handle сделать недависимо от регистра{*}{color} |
| | * {color:1f497d}{*}предлагать ученику задачи взависимости от того, что он решал{*}{color} |