Проект: QRkot_spreadsheets

Приложение для Благотворительного фонда поддержки котиков QRKot. Фонд собирает пожертвования на различные целевые проекты: на медицинское обслуживание нуждающихся хвостатых, на обустройство кошачьей колонии в подвале, на корм оставшимся без попечения кошкам — на любые цели, связанные с поддержкой кошачьей популяции.

Оглавление

• Технологии
• Описание работы
• Установка и запуск
• Применение
• Удаление
• Автор

Технологии

Развернуть

Языки программирования, библиотеки и модули:

Фреймворк, расширения и библиотеки:

Базы данных и инструменты работы с БД:

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

CI/CD:

Облачные технологии:

⬆️Оглавление

Описание работы

• Проекты: В Фонде QRKot может быть открыто несколько целевых проектов. У каждого проекта есть название, описание и сумма, которую планируется собрать. После того, как нужная сумма собрана — проект закрывается. Пожертвования в проекты поступают по принципу First In, First Out: все пожертвования идут в проект, открытый раньше других; когда этот проект набирает необходимую сумму и закрывается — пожертвования начинают поступать в следующий проект.

• Отчеты в Google таблицах: В приложении есть возможность формирования отчёта в гугл-таблице. В таблице представлены закрытые проекты, отсортированные по скорости сбора средств — от тех, что закрылись быстрее всего, до тех, что долго собирали нужную сумму. Также реализован функционал по управлению отчетами (все методы реализованы в базовом классе GoogleBaseClient в пакете google_package), можно:

  • просмотреть все отчеты на Google диске
  • удалить определенный отчет с диска
  • полностью очистить диск - удаляются все отчеты с диска.

• Пожертвования: Каждый пользователь может сделать пожертвование и сопроводить его комментарием. Пожертвования не целевые: они вносятся в фонд, а не в конкретный проект. Каждое полученное пожертвование автоматически добавляется в первый открытый проект, который ещё не набрал нужную сумму. Если пожертвование больше нужной суммы или же в Фонде нет открытых проектов — оставшиеся деньги ждут открытия следующего проекта. При создании нового проекта все неинвестированные пожертвования автоматически вкладываются в новый проект.

• Пользователи: Целевые проекты создаются администраторами сайта. Зарегистрированные пользователи могут отправлять пожертвования и просматривать список своих пожертвований. Любой пользователь может видеть список всех проектов, включая требуемые и уже внесенные суммы. Это касается всех проектов — и открытых, и закрытых.

⬆️Оглавление

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

Удобно использовать принцип copy-paste - копировать команды из GitHub Readme и вставлять в командную строку Git Bash или IDE (например VSCode).

Предварительные условия:

Развернуть

Предполагается, что пользователь:

• создал сервисный аккаунт на платформе Google Cloud и получил JSON-файл с информацией о своем сервисном аккаунте, его приватный ключ, ID и ссылки для авторизации. Эти данные будет необходимо указать в файле переменных окружения.
• создал аккаунт DockerHub, если запуск будет производиться на удаленном сервере.
• установил Docker и Docker Compose на локальной машине или на удаленном сервере, где проект будет запускаться в контейнерах. Проверить наличие можно выполнив команды:

  docker --version && docker-compose --version

---

Локальный запуск

1. Клонируйте репозиторий с GitHub и введите данные для переменных окружения (значения даны для примера, но их можно оставить):

git clone https://github.com/alexpro2022/QRkot_spreadsheets-FastAPI.git && \
cd QRkot_spreadsheets-FastAPI && \
cp env_example .env && \
nano .env

сервер Uvicorn/SQLite3

2. Создайте и активируйте виртуальное окружение:

   • Если у вас Linux/macOS

    python -m venv venv && source venv/bin/activate

   • Если у вас Windows

    python -m venv venv && source venv/Scripts/activate

3. Установите в виртуальное окружение все необходимые зависимости из файла requirements.txt:

python -m pip install --upgrade pip && pip install -r requirements.txt

4. В проекте уже инициализирована система миграций Alembic с настроенной автогенерацией имен внешних ключей моделей и создан файл первой миграции. Чтобы ее применить, необходимо выполнить команду:

alembic upgrade head

Будут созданы все таблицы из файла миграций.

5. Запуск приложения - из корневой директории проекта выполните команду:

uvicorn app.main:app

Сервер Uvicorn запустит приложение по адресу http://127.0.0.1:8000. Администрирование приложения может быть осуществлено через Swagger доступный по адресу http://127.0.0.1:8000/docs (далее см. Применение).

6. Остановить Uvicorn можно комбинацией клавиш Ctl-C.

---

Docker Compose/PostgreSQL

2. Из корневой директории проекта выполните команду:

docker compose -f infra/local/docker-compose.yml up -d --build

Проект будет развернут в трех docker-контейнерах (db, web, nginx) по адресу http://localhost. Администрирование приложения может быть осуществлено через Swagger доступный по адресу http://localhost/docs (далее см. Применение).

3. Остановить docker и удалить контейнеры можно командой из корневой директории проекта:

docker compose -f infra/local/docker-compose.yml down

Если также необходимо удалить том базы данных:

docker compose -f infra/local/docker-compose.yml down -v

---

Запуск на удаленном сервере

1. Сделайте форк в свой репозиторий.

2. Создайте Actions.Secrets согласно списку ниже (значения указаны для примера) + переменные окружения из env_example файла:

PROJECT_NAME=qrkot_spreadsheets
SECRET_KEY

POSTGRES_PASSWORD
DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/postgres

CODECOV_TOKEN 

DOCKERHUB_USERNAME 
DOCKERHUB_PASSWORD 

# Данные удаленного сервера и ssh-подключения:
HOST 
USERNAME 
SSH_KEY     
PASSPHRASE 

# Учетные данные Телеграм-бота для получения сообщения о успешном завершении workflow
TELEGRAM_USER_ID 
TELEGRAM_BOT_TOKEN 

3. Запустите вручную workflow, чтобы автоматически развернуть проект в трех docker-контейнерах (db, web, nginx) на удаленном сервере.

---

При первом запуске будет создан суперюзер (пользователь с правами админа) с учетными данными из переменных окружения ADMIN_EMAIL и ADMIN_PASSWORD.

⬆️Оглавление

Применение:

Swagger позволяет осуществлять http-запросы к работающему сервису, тем самым можно управлять проектами, пожертвованиями и пользователями в рамках политики сервиса (указано в Swagger для каждого запроса). Для доступа к этим функциям необходимо авторизоваться в Swagger, используя credentials из .env-файла:

1. Нажмите:

   • на символ замка в строке любого эндпоинта или
   • на кнопку Authorize в верхней части Swagger. Появится окно для ввода логина и пароля.

2. Введите credentials в поля формы:

   • в поле username — значение переменной окружения ADMIN_EMAIL,
   • в поле password — значение переменной окружения ADMIN_PASSWORD. В выпадающем списке Client credentials location оставьте значение Authorization header, остальные два поля оставьте пустыми; нажмите кнопку Authorize. Если данные были введены правильно, и таблица в БД существует — появится окно с подтверждением авторизации, нажмите Close. Чтобы разлогиниться — перезагрузите страницу.

⬆️Оглавление

Удаление:

Для удаления проекта выполните команду:

cd .. && rm -fr QRkot_spreadsheets-FastAPI && deactivate

⬆️Оглавление

Автор

Aleksei Proskuriakov

• дополнительно к ТЗ проекта реализовал:
  • просмотр всех отчетов на Google диске
  • удаление определенного отчета
  • полную очистку диска
• нашел и исправил ошибки в оригинальных тестах (предоставлялись вместе с ТЗ проекта)
• написал несколько новых тестов повышающих codecov до 87%.

⬆️В начало