From d3471331b1aee89f0863f109f2c9e7fb29c38779 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A1=D1=82=D0=B5=D0=BF=D0=B0=D0=BD=D0=B5=D0=BD=D0=BA?= =?UTF-8?q?=D0=BE=20=D0=9E=D0=BB=D1=8C=D0=B3=D0=B0?= Date: Thu, 15 Apr 2021 14:43:54 +0300 Subject: [PATCH] Add READme docs --- README.md | 189 ++++++++++++++++-------------- docs/source/code.rst | 2 +- docs/source/conf.py | 15 ++- docs/source/index.rst | 1 + docs/source/readme.rst | 4 + docs/source/spelling_wordlist.txt | 24 +++- main/extra_func.py | 4 +- main/models.py | 1 - 8 files changed, 136 insertions(+), 104 deletions(-) create mode 100644 docs/source/readme.rst diff --git a/README.md b/README.md index 14e3869..ffd6e42 100644 --- a/README.md +++ b/README.md @@ -1,126 +1,133 @@ -# ZenDesk Access Controller +************************* +ZenDesk Access Controller +************************* -## Управление правами доступа +****************************** +Управление правами доступа +****************************** -Идея - написать программу(Web приложение), которая будет выдавать права пользователям системы по запросу самого -пользователя. Например, из 12 человек 3 сейчас работают с правами админа, по окончании рабочей смены они сдают -свои права (освобождают места) и другие пользователи могут запросить эти права в свое пользование. +**Идея** - Web приложение, выдает права пользователям системы по запросу самого пользователя. Например, из 12 человек 3 +сейчас работают с правами админа, по окончании рабочей смены они сдают свои права (освобождают места) и другие +пользователи могут права запросить. -Оставшиеся 9 человек получают права легкого агента - без прав редактирования, а только чтение. +Оставшиеся 9 человек получают права легкого агента - без прав редактирования, только чтение. -Из технологий - программа должна взаимодействовать с api системы Zendesk(система обращений клиентов - жалобы), -проверять авторизованного пользователя на права(будет возможность менять права напрямую из Zendesk - нужна -синхронизация прав с приоритетом у Zendesk). +Технологически приложение взаимодействует с **api** системы **Zendesk** (система обращений клиентов - жалобы), +проверяет авторизованного пользователя на права с возможностью менять права напрямую из Zendesk (синхронизация +с приоритетом у Zendesk). -Если руками в самом Zendesk права у пользователя отобрали или наоборот -присвоили, то наша программа обновляет статус пользователя в соответствии с данными синхронизации -(например, раз в минуту). - -Так же в идеале должна быть проверка, что пользователь сайта существует на сайте Zendesk(по токену). - -Сэндбокс Zendesk нам предоставит моя компания, библиотеку для работы с api уже подсказали. -Сама программа (наша) будет обладать админскими правами и реализовывать контроль и выдачу прав другим пользователям. +Присутствует проверка, регистрации пользователя сайта на сайте Zendesk (по токену). *Итого:* 1. Реализовать авторизацию пользователей с проверкой по API на существование такого пользователя 2. Реализовать интерфейс со статистикой рабочих мест(занято, свободно, кто занимает) -3. Реализовать логирование действий(когда взял права, когда отдал - запись в файл и БД) -4. Реализовать передачу прав приложением по запросу от пользователя и замену прав пользователя - у которого права отбираются внутри Zendesk (на легкий агент) +3. Реализовать логгирование действий(когда взял права, когда отдал - запись в файл и БД) +4. Реализовать передачу прав приложением по запросу от пользователя и замену прав пользователя у которого права отбираются внутри Zendesk (на легкий агент) 5. Реализовать синхронизацию по API на проверку прав(не менялись ли в системе Zendesk) 6. Реализовать возможность добавить большее количество админских прав 7. Реализовать возможность добавления легких агентов(права только на просмотр) 8. Реализовать на общей странице текущую информацию о пользователе - текущие права, карточка пользователя - -## Технологический стек: +************************ +Технологический стек: +************************ - Python 3 - Django 3 +************** +Quickstart +************** +``sudo apt install make`` -## Quickstart -```bash -sudo apt install make -pip install --upgrade pip -pip install -r requirements.txt -./manage.py migrate -./manage.py loaddata data.json -./manage.py runserver -``` +``pip install --upgrade pip`` -##ZenDesk Access Controller instruction for eng +``pip install -r requirements.txt`` -##Перед запуском для тестирования: +``./manage.py migrate`` -Убедитесь, что вы зарегистрированы в песочнице ZenDesk, у вас назначена организация (SYSTEM) -Для админов ZenDesk дополнительно - создайте токен доступа в ZenDesk -При запуске в Docker убедитесь что папка, которая будет служить хранилищем для БД, открыта на запись и чтение +``./manage.py loaddata data.json`` + +``./manage.py runserver`` + +********************************** +Перед запуском для тестирования: +********************************** + +* убедитесь, что вы зарегистрированы в песочнице ZenDesk, у вас назначена организация (SYSTEM) +* для админов ZenDesk дополнительно - создайте токен доступа в ZenDesk +* при запуске в Docker убедитесь что папка, которая будет служить хранилищем для БД, открыта на запись и чтение + +***************************** +Запуск на локальной машине: +***************************** + +* скопировать репозиторий на локальную машину +* перейти в папку приложения +* активировать виртуальное окружение +* выполнить команду **pip install -r requirements.txt** +* в виртуальное окружение добавить следующие переменные: -##Запуск на локальной машине: - -скопировать репозиторий на локальную машину -перейти в папку приложения -активировать вирутальное окружение -выполнить команду pip install -r requirements.txt -в вирутальное окружение добавить следующие переменные : +| *ACCESS_CONTROLLER_API_EMAIL={EMAIL}* - почта админа в ZenDesk +| *ACCESS_CONTROLLER_API_PASSWORD={PASSWORD}* - пароль админа ZenDesk +| *ACCESS_CONTROLLER_API_TOKEN={API_TOKEN}* - API токен ZenDesk +| *ZD_DOMAIN={DOMAIN}* - домен ZenDesk +| *ENG_CROLE_ID={ENGINEER_CUSTOM_ROLE_ID}* - id роли инженера( custom_role_id сотрудника смены) +| *LA_CROLE_ID={LIGHT_AGENT_CUSTOM_ROLE_ID}* - id роли легкого агента (custom_role_id роли -легкий агент) +| *EMPL_GROUP={EMPLOYEE_GROUP_NAME}* - имя группы которой принадлежат сотрудники ССКС +| *BUF_GROUP={BUFFER_GROUP_NAME}* - имя буферной группы для передачи смен(через нее происходит управление тикетами) +| *ST_EMAIL={SOLVED_TICKETS_EMAIL}* - почта на которую будут переназначатся закрытые тикеты +| *LICENSE_NO={LICENSE_NO}* - количество лицензий, отображаемых как доступные в приложении +| *SHIFTH={SHIFT_HOURS}* - количество часов в рабочей смене (нужно для статистики, пока не реализовано но требует указания значения) -ACCESS_CONTROLLER_API_EMAIL={EMAIL} - почта админа в ZenDesk -ACCESS_CONTROLLER_API_PASSWORD={PASSWORD} - пароль админа ZenDesk -ACCESS_CONTROLLER_API_TOKEN={API_TOKEN} - API токен зендеск -ZD_DOMAIN={DOMAIN} - домен ZenDesk -ENG_CROLE_ID={ENGINEER_CUSTOM_ROLE_ID} - id роли инженера( custom_role_id сотрдника смены) -LA_CROLE_ID={LIGHT_AGENT_CUSTOM_ROLE_ID} - id роли легкого агента (custom_role_id роли -легкий агент) -EMPL_GROUP={EMPLOYEE_GROUP_NAME} - имя группы которой принадлежат сотрудники ССКС -BUF_GROUP={BUFFER_GROUP_NAME} - имя буферной группы для передачи смен(через нее происходит управление тикетами) -ST_EMAIL={SOLVED_TICKETS_EMAIL} - почта на которую будут переназначятся закрытые тикеты -LICENSE_NO={LICENSE_NO} - количество лицензий, отображаемых как доступные в приложении -SHIFTH={SHIFT_HOURS} - количество часов в рабочей смене (нужно для статистики, пока не реализовано но требует указания значения) +* выполнить команду **python manage.py makemigrations** +* выполнить команду **python manage.py migrate** +* запустить приложение командой **python manage.py runserver** (можно указать в параметрах для файла manage.py) +* перейти по ссылке в консоли (вероятнее всего откроется по адресу http://127.0.0.1:8000/) +****************** +Запуск в Docker: +****************** -выполнить команду python manage.py makemigrations -выполнить команду python manage.py migrate -запустить приложение командой python manage.py runserver (можно указать в параметрах для файла manage.py) -перейти по ссылке в консоли (вероятнее всего откроется по адресу http://127.0.0.1:8000/) +Требуется установленный и настроенный Docker +* скопировать репозиторий на локальную машину +* в командной строке перейти в папку проекта +* выполнить команду **docker build**. +* выполнить команду **docker images** (нам нужен id созданного образа) +* выполнить команду **docker run -d -p 8000:8000 -e ACCESS_CONTROLLER_API_EMAIL={EMAIL} -e ACCESS_CONTROLLER_API_PASSWORD={PASSWORD}**...(перечисляем все параметры виртуального окружения, разделяя их -e) -v {абсолютный путь к папке, в которой будет размещена база}:/zendesk-access-controller/db {id образа докера} +* открыть запущенный контейнер в браузере (можно перейти по ссылке http://localhost:8000/) -##Запуск в Docker: -Требуется установленный и настроеный Docker +***************************** +Запуск с тестовыми юзерами: +***************************** -скопировать репозиторий на локальную машину -в командной строке перейти в папку проекта -выполнить команду docker build . -выполнить команду docker images (нам нужен id созданного образа) -выполнить команду docker run -d -p 8000:8000 -e ACCESS_CONTROLLER_API_EMAIL={EMAIL} -e ACCESS_CONTROLLER_API_PASSWORD={PASSWORD} -...(перечисляем все параметры виртуального окружени разделяя их -e) -v {абсолютный путь к папке, в которой будет размещена база}:/zendesk-access-controller/db {id образа докера} -открываем запущеный контейнер в браузере (можно перейти по ссылке http://localhost:8000/) +| На локальной машине - перед запуском команды **python manage.py runserver** выполнить команду **python manage.py loaddata data.json**. +| Это создаст тестового админа и тестового пользователя в приложении для песочницы ZenDesk. +| **Админ - admin@gmail.com / zendeskadmin** , +| **пользователь - 123@test.ru / zendeskuser** . +| Не сработает если домен песочницы отличается от ngenix1612197338 (на другом домене нужно будет создать сначала пользователей в песочнице с правами админа и легкого агента +| с этими же почтами, назначить им организацию (SYSTEM)) +******************************* +Параметры тестовой песочницы: +******************************* -##Запуск с тестовыми юзерами: +| *ACCESS_CONTROLLER_API_EMAIL={EMAIL}* - почта админа в ZenDesk - взять у роководителя(если вы не админ) +| *ACCESS_CONTROLLER_API_PASSWORD={PASSWORD}* - пароль админа ZenDesk - взять у роководителя(если вы не админ) +| *ACCESS_CONTROLLER_API_TOKEN={API_TOKEN}* - API токен зендеск - взять у роководителя(если вы не админ) +| *ZD_DOMAIN* =ngenix1612197338 +| *ENG_CROLE_ID* =360005209000 +| *LA_CROLE_ID* =360005208980 +| *EMPL_GROUP* =Поддержка +| *BUF_GROUP* =Сменная группа +| *ST_EMAIL* =d.krikov@ngenix.net +| *LICENSE_NO* =3 +| *SHIFTH* =12 -На локальной машине - перед запуском команды python manage.py runserver выполнить команду python manage.py loaddata data.json -Это создаст тестового админа и тестового пользователя в приложении для песочницы ZenDesk. Админ - admin@gmail.com / zendeskadmin , пользователь - 123@test.ru / zendeskuser . -Не сработает если домен песочницы отличается от ngenix1612197338 (на другом домене нужно будет создать сначала пользователей в песочнице с правами админа и легкого агента -с этими же почтами, назначить им организацию (SYSTEM)) - - -##Параметры тестовой песочницы: - -ACCESS_CONTROLLER_API_EMAIL={EMAIL} - почта админа в ZenDesk - взять у роководителя(если вы не админ) -ACCESS_CONTROLLER_API_PASSWORD={PASSWORD} - пароль админа ZenDesk - взять у роководителя(если вы не админ) -ACCESS_CONTROLLER_API_TOKEN={API_TOKEN} - API токен зендеск - взять у роководителя(если вы не админ) -ZD_DOMAIN=ngenix1612197338 -ENG_CROLE_ID=360005209000 -LA_CROLE_ID=360005208980 -EMPL_GROUP=Поддержка -BUF_GROUP=Сменная группа -ST_EMAIL=d.krikov@ngenix.net - -LICENSE_NO=3 -SHIFTH=12 - - -## Read more +************ +Read more +************ - Zenpy: [http://docs.facetoe.com.au](http://docs.facetoe.com.au) - Zendesk API: [https://developer.zendesk.com/rest_api/docs/](https://developer.zendesk.com/rest_api/docs/) diff --git a/docs/source/code.rst b/docs/source/code.rst index 7479081..1f0bd15 100644 --- a/docs/source/code.rst +++ b/docs/source/code.rst @@ -6,7 +6,7 @@ Models ******* .. automodule:: main.models - :members: + :members: ****** diff --git a/docs/source/conf.py b/docs/source/conf.py index 993b68f..3330341 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -114,12 +114,15 @@ def skip_queryset(app, what, name, obj, skip, options): return True return skip +def fix_sig(app, what, name, obj, options, signature, return_annotation): + return ("", "") -# def setup(app): -# # Register the docstring processor with sphinx -# app.connect('autodoc-process-docstring', process_django_models) -# app.connect('autodoc-skip-member', skip_queryset) -# app.connect('autodoc-process-docstring', process_modules) +def setup(app): + # Register the docstring processor with sphinx + app.connect('autodoc-process-docstring', process_django_models) + app.connect('autodoc-skip-member', skip_queryset) + app.connect('autodoc-process-docstring', process_modules) + app.connect("autodoc-process-signature", fix_sig) @@ -181,7 +184,7 @@ intersphinx_mapping = { } autodoc_default_flags = ['members'] -autodoc_typehints = "none" +autodoc_typehints = "description" # spell checking spelling_lang = 'ru_RU' diff --git a/docs/source/index.rst b/docs/source/index.rst index 96f9c69..4de50ad 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,6 +12,7 @@ overview code + readme todo diff --git a/docs/source/readme.rst b/docs/source/readme.rst new file mode 100644 index 0000000..0cee3b2 --- /dev/null +++ b/docs/source/readme.rst @@ -0,0 +1,4 @@ +READ.me +================== + +.. include:: ../../README.md diff --git a/docs/source/spelling_wordlist.txt b/docs/source/spelling_wordlist.txt index bd64cf9..da91912 100644 --- a/docs/source/spelling_wordlist.txt +++ b/docs/source/spelling_wordlist.txt @@ -45,7 +45,9 @@ start end date Токен +токен токеном +токену аутентифицирован (datetime.time) datetime @@ -82,7 +84,23 @@ Serializer Serializers Сериализатор переадресации - - - +чекбоксов +админских +админские +Python +Docker +докер +докера +Докер +репозиторий +zendesk-access-controller/db +-e +-v +e +v +zendesk +db +юзерами +Read +Zenpy diff --git a/main/extra_func.py b/main/extra_func.py index e0aa110..70b57d3 100644 --- a/main/extra_func.py +++ b/main/extra_func.py @@ -570,7 +570,7 @@ class StatisticData: def post_engineer_logic(self, last_log): """ - Функция обрабатывает случай, когда нам изветсно что инженер работал и после диапазона + Функция обрабатывает случай, когда нам известно что инженер работал и после диапазона """ self.fill_daterange(last_log.change_time.date() + timedelta(days=1), self.end_date + timedelta(days=1)) if last_log.change_time.date() == timezone.now().date(): @@ -585,7 +585,7 @@ class StatisticData: def prev_engineer_logic(self, first_log): """ - Функция обрабатывает случай, когда нам изветсно что инженер начал работу до диапазона + Функция обрабатывает случай, когда нам известно что инженер начал работу до диапазона """ self.fill_daterange(max(User.objects.get(email=self.email).date_joined.date(), self.start_date), first_log.change_time.date()) diff --git a/main/models.py b/main/models.py index ac6f91c..c723806 100644 --- a/main/models.py +++ b/main/models.py @@ -49,7 +49,6 @@ class RoleChangeLogs(models.Model): """ Модель для логирования изменений ролей пользователя. """ - user = models.ForeignKey(to=User, on_delete=models.CASCADE, help_text='Пользователь, которому присвоили другую роль') old_role = models.IntegerField(default=0, help_text='Старая роль') new_role = models.IntegerField(default=0, help_text='Присвоенная роль')