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* \-&nbsp; представляет собой схему в базе данных. Каждый модуль отображает таблицу (в некоторых случаях таблицы) из базы данных;
* *schemas* \- отвечает за валидирование данных на входе и на выходе;
* *templates* \- содержит в себе шаблоны frontend части;
* *views* \- отвечает за обработку пользовательских запросов.

h2. How It's Made

&nbsp;На момент последней версии (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}{*}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}