From 47b708a231b8d48b6839f1850842675217c5c3c1 Mon Sep 17 00:00:00 2001 From: Grigoriev Semyon <33061489+grigoriev-semyon@users.noreply.github.com> Date: Wed, 24 Jul 2024 22:04:41 +0300 Subject: [PATCH] =?UTF-8?q?=D0=9D=D0=BE=D0=B2=D0=B0=D1=8F=20=D0=B4=D0=BE?= =?UTF-8?q?=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82=D0=B0=D1=86=D0=B8=D1=8F=20?= =?UTF-8?q?(#85)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 29 ++++++++++++++ README.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..147356d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,29 @@ +## Что нужно для запуска + +1. python3.11. Установка описана [тут](https://www.python.org/downloads/) + +2. Docker. Как установить docker описано [тут](https://docs.docker.com/engine/install/) + +3. PostgreSQL. Запустить команду + ```bash + docker run -d -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust --name db-print_service postgres:15 + ``` + +4. Опционально Redis (если хотите дергать ручку `/qr` или подключаться по вебсокету) + ```bash + docker run -d -p 6379:6379 --name redis-print_service redis + ``` + +## Какие переменные нужны для запуска +- `DB_DSN=postgresql://postgres@localhost:5432/postgres` + +### Опционально, если хотите дергать ручку `/qr` или подключаться по вебсокету +- `REDIS_DSN=redis://localhost:6379/0` + + +## Codestyle + +- Black. Как пользоваться описано [тут](https://black.readthedocs.io/en/stable/) + +- Также применяем [isort](https://pycqa.github.io/isort/) + diff --git a/README.md b/README.md index a37fbf8..0eda7d2 100644 --- a/README.md +++ b/README.md @@ -50,3 +50,107 @@ - `DB_DSN=postgresql://postgres@localhost:5432/postgres` – Данные для подключения к БД - `STATIC_PATH` - путь до папки, в которой лежит статика. +- `REDIS_DSN` - Данные для подключения к Redis +- `CONTENT_TYPES` - типы принимаемого контента для печати +- `MAX_SIZE` - Максимальный размер файла в байтах +- `MAX_PAGE_COUNT` - Максимальное количество страниц для печати +- `STORAGE_TIME` - Время хранения файла в часах +- `ALLOW_STUDENT_NUMBER` - разрешить ли номер студенческого для печати +- `PIN_SYMBOLS` - символы из которых состоит ПИН-код +- `PIN_LENGTH` - длина пин-кода +- `QR_TOKEN_PREFIX` - префикс QR кода +- `QR_TOKEN_SYMBOLS` - символы из которых состоит QR-код +- `QR_TOKEN_LENGTH` - Длина QR-кода +- `QR_TOKEN_TTL` - время жизни QR-кода (время показа) +- `QR_TOKEN_DELAY` - как долго QR-код будет валидным после того, как прошел TTL (исчез с экрана) +- Остальные общие для всех АПИ параметры описаны [тут](https://docs.profcomff.com/tvoy-ff/backend/settings.html) + +## Основные абстракции +- `Пользователь` - сущность, у которой есть номер студенческого и профсоюзного билета, а также фамилию +- `Файл` - сущность, отвечающая за загруженный пользователем файл. Имеет пин-код для скачивания, ссылку на реальный файл (который лежит в static хранилище), а также опции печати и ссылку на пользователья, который его загрузил +- `Факт печати` - сущность для статистики печати. Каждый раз, когда кто-то печатает файл, создается эта сущность со ссылкой на файл и его владельца, а также количеством использованных страниц + +## Сценарий использования +1. Обновить список пользователей. + + Дернуть ручку `POST /print/is_union_member`, передать json со списком новых пользователей: + ```json + { + "users": [ + { + "username": "string", + "union_number": "string", + "student_number": "string" + } + ] + } + ``` + Если пользователь с таким студенческим _или_ профсоюзным уже существует, то вся остальная информация будет заменена. Иначе, создается новый пользователь. + +2. Проверить, что пользователь существует в системе + Дернуть ручку `GET /print/is_union_member?surname=...&number=...`, передать в query параметрах фамилию и номер профсоюзного билета. + Вернет ответ, найден ли пользователь. +3. Загрузить файл + + Дернуть ручку `POST /print/file`, передать туда json: + ```json + { + "surname": "Иванов", + "number": "1015000", + "filename": "filename.pdf", + "source": "string", + "options": { + "pages": "", // "" если распечатать надо все страницы, иначе формат такой: "10-13,16,18,20,21,24,25,27,28,30", можно не сортировать + "copies": 1, + "two_sided": false + } + } + ``` + Передается пользователь с его проф. билетом. + Ручка вернет pin в таком формате: + ```json + { + "pin": "OF72I1", + "options": { + "pages": "", + "copies": 1, + "two_sided": false + } + } + ``` + Его надо сохранить и отправить еще один запрос на загрузку самого файла: + Дернуть ручку `POST /print/file/{pin}`, передать файл в бинарном виде + Ручка вернет тот же json, что и предыдущая в случае успеха + + После этого файл готов к печати + +4. Получить файл + Дернуть ручку `GET /print/file/{pin}` + Вернет json: + ```json + { + "filename": "2021-11-02-ZMNF5V...9.pdf", + "options": { + "pages": "", + "copies": 1, + "two_sided": false + } + } + ``` + По ссылке можно скачать файл из static хранилища, options помогают распечтать файл, если запрос идет от принтера + +5. Как работает QR + Пользователь приходит к терминалу, считывает QR-код, после этого с его устройства идет запрос на `POST /qr`, в котором передается отсканированный QR-код и пин для печати + + Терминал подключен к бэкенду через вебсокет. Бэкенд после получения запроса от пользователя в течение некоторого времени отправляет хапрос на печать файла. + +6. Ручное обновление и перезагрузка + Делается с админским токеном + Ручки, соответственно: `POST /admin/update` и `POST /admin/reboot` + Спецификация доступна в Swagger UI + +## Contributing + +- Основная [информация](https://docs.profcomff.com/tvoy-ff/backend/index.html) по разработке наших приложений + +- [Ссылка](https://github.com/profcomff/print-api/blob/main/CONTRIBUTING.md) на страницу с информацией по разработке userdata-api