Новая документация (#85)

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/)
+

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