Система формирования отчетов WReport

Здеcь будут содержать все файлы для командного проекта по формирования отчетов компании между заказчиками

Для этого репозитория написано вики

Начало работы

Клонирование репозитория

1. Выполните клонирование репозитория через команду в нужную директорию:

git clone https://github.com/EmAksS/ReportCreator.git

2. Создадите и запустите виртуальную среду в директории reportcreator:

python -m venv venv
.\venv\Scripts\activate

3. Установите все зависимости через requirements.txt

pip install -r ../requirements.txt

4. Создадите и заполните .env-файл. Структура переменных описана в файле .env.dist
   • Значение MODE ставить на любое значение, кроме случаев загрузки сайта на продакшн - тут нужно ставить значение production.
   • Значение SECRET_KEY можно оставить пустым (при запуске будет подгружаться публичный ключ), однако при загрузке на продакшн тут должен быть СЕКРЕТНЫЙ ключ проекта.
5. Создайте новую ветку Git'a для работы.

Docker

Проект поддерживает запуск помощью Docker. Если вы впервые запускаете проект, сначала соберите контейнеры с помощью команды docker-compose build.

Запуск контейнеров оуществляется с помощью docker-compose up.

Миграции

Приложение содержит миграции - это специальные файлы для организации структуры базы данных. По умолчанию, миграции уже приготовлены и они располагаются в backend/migrations/. Перед первым запуском приложения, примените эти миграции для организации полей базы данных:

py .\manage.py migrate

После этого, будут организован файл базы данных в core/db.sqlite3.

Примечание: Если мы изменяете структуру базы данных (т.е. меняете файлы в папке <app_name>/models/<model_name>), вам нужно создать миграции командой:

py .\manage.py makemigrations

...и далее применить миграции командой migrate.

Запуск приложения

1. Введите команду:

python manage.py runserver

2. Перейдите по ссылке http://127.0.0.1:8000/ в браузере.

---

Документация по работе

ВАЖНО! Вы можете посмотреть все методы для работы по адресу http://127.0.0.1:8000/schema/swagger-ui/#/

Глосарий

• Исполнитель - компания, которая зарегистрирована как исполнитель услуг.
• Заказчик - внешняя компания, которая зарегистрирована как заказчик услуг исполнителя.
• Модель - таблица баз данных, куда сохраняются данные

Компании

Объявление моделей компаний указано в файле /backend/models/company.py

Абстрактная модель компании

Это базовая модель, где будут находиться общие поля для каждой компании (Исполнителя и Заказчика):

• ID (ключевое поле, автоинкрементирующий номер)
• Название компании (с сокращением и абревиатурами: ООО "Трайв Технолоджис")
• Полное название компании (с расшифровкой абревиатур: общество с ограниченной ответственностью «Трайв Технолоджис»)
• Название должности (директор или ген.директор)
• ФИО директора (полностью - Иванов Иван Иванович)

ID - это автоинкрементирующее поле, действие которое переходит в качестве Django и является ключевым полем для элемента. Тип данных - число.

Название компании (company_name) - обязательное поле. Принимает название компании с сокращениями и абревиатурами. Максимальная длина поля - 64 символа. Принимает только текстовые символы.

Полное название компании (company_fullName) - текстовое поле, которое содержит полное название компании с расшифровкой всех абревиатур. Максимальная длина 256 символов. Не может быть пустым. Если при создании элемента значение не задано, то принимает значение поля company_name.

Название должности руководителя (director_post) - именование должности руководителя, от чьего имени будут подписываться все документы от компании. Максимальная длина - 32 символа. Не может быть пустым. По умолчанию или если поле не было заполнено, принимает значение "Директор"

ФИО руководителя (director_name) - ФИО руководителя полностью, от чьего имени будут подписываться документы. Не может быть пустым. Максимальная длина - 64 символа.

Инициалы руководителя (director_shortName) - инициалы руководителя компании. Максимальная длина строки - 32 символа. Не может быть пустым. В дальнейшем оно будет автоматически создаваться из значений поля director_name.

Исполнитель

Модель наследует все поля из абстрактной модели компании.

Имеются ли дополнительные поля у исполнителя?

Заказчик

Модель компании-заказчика, который выполняет заказ у компании-исполнителя. Наследует все поля из абстрактной модели компании, а также добавляются дополнительные поля:

Город-месторасположение компании (contractor_city) - название города, где располагается компания-заказчик. Представляет собой строку, максимальная длина равна 64 символа. Не может быть пустым.

Пользователь системы

Модель пользователя системы, который выполняет работу с системой. Каждый пользователь связан с конкретной компанией-исполнителем. Пользователь может быть связан только с одной конкретной компанией.

Здесь представлена только информация с пользователем, как объектом системы.

Поля пользователя:

• username - имя пользователя в системе.
• last_name - фамилия пользователя.
• first_name - имя пользователя.
• patronymic - отчество пользователя.
• related_company - компания, которой принадлежит пользователь. Является полем таблицы companies.Executor.

API

Все действия с сервером будет происходить через API. Абсолютно вся работа API описана в директории api/. Для работы используется модуль django-rest-framework.

Принцип взаимодействия

Пока проект не загружен на продакшн, API будет доступно по адресу локалхоста с портом 8000.

ВАЖНО! Проект принимает только запроса от локалхоста с портом 3000 - React-проекта. Перед запуском проекта убедитесь, что фронтенд будет запускаться именно на этом порту!

Принцип работы действует согласно правилам API, предоставляя заголовки, коды ответов и само тело ответа.

Точки взаимодействия

Все точки взаимодействия API описаны относительно адреса https://127.0.0.1:8000

• /csrf/ - получить CSRF-токен текущей сессии - указан по ключу csrf_token
• /check_auth/ - проверить, является ли текущий пользовать авторизирован в системе. Статус аутентификации указан по ключу status: authenticated|not_authenticated. При аутентификации пользователя, также возвращает в ключе user информацию о пользователе.
• /login/ - POST-метод, аутентификация пользователя в системе. Обязан принять request-запрос в формате ключ-значение в формате ниже. При успехе возвращает ключ "status": "success" и информацию о пользователе в поле user. При неудаче, возвращает ошибку 400.

{
    "username": "логин_пользователя",
    "password": "пароль_пользователя"
}

• /logout - POST-метод, только для авторизированных пользователей. Выполняет выход пользователя из системы. При успехе возвращает поле "status": "success". Если пользователь не авторизирован, возвращает ошибку 403.
• register/company/ - POST-метод. Осуществляет регистрацию компании и его суперпользователя. Обязан модержать поля, указанные ниже. При успехе, возвращает код 201, а также поля "status": "success", информацию о сохранённой компании (company) и информацию о суперпользователе этой компании (user). При ошибке возвращает код 403.

{
    "company_name": "краткое_название_компании",
    "company_fullName": "полное_название_компании",
    "username": "логин_создаваемого_суперпользователя",
    "password": "пароль_создаваемого_суперпользователя",
    "last_name": "фамилия_суперпользователя",
    "first_name": "имя_суперпользователя",
    "surname": "НЕОБЯЗАТЕЛЬНО_отчество_суперпользователя"
}

• /register/user/ - POST-метод, только для авторизированного суперпользователя компании. Создаёт пользователя компании, в которой находится суперпользователь. Обязан содержать поля, указанные ниже. При успехе создания пользователя, возвращает код 201, "status": "success" и информацию о созданном пользователе user.

{
    "username": "логин_создаваемого_пользователя",
    "password": "пароль_создаваемого_пользователя",
    "last_name": "фамилия_пользователя",
    "first_name": "имя_пользователя",
    "surname": "НЕОБЯЗАТЕЛЬНО_отчество_пользователя"
}

• /company/ - только для авторизированных пользователей. Берёт компанию пользователя и информацию о компании company, а также информацию о всех пользователях-участниках этой компании users. Если пользователь не состоит в компании, возвращает код 400.

Поля

Поля (fields) - парадигма сохранения данных о пользователе, где содержится дополнительная информация о пользователях. Через API можно создать дополнительные кастомные поля, куда можно писать данные определённых типов. Все данные о полях описаны в backend/models/fields.py:

• key_name - английское название поле. Является ключевым полем (primary_key) и по нему идёт доступ в программе.
• name - русскоязычное название поле, понятное для человека.
• is_required - флаг, который обозначает, является ли переменная обязательной для заполнения или нет.
• related_item - название модели, куда относится данное поле. Заполняется программно (автоматически), при создании поля в зависимости от метода создания поля. Например, если создаётся поле пользователя, то related_item = "User". На данный момент (05.04.2025) поддерживает только значение "User".
• type - тип данных, который должен выступать как значение поля. Поддерживает значения, указанные в переменной FIELD_TYPES в файле модели. При программном создании (при формировании запроса в API) нужно использовать только первое значение кортежа. То есть, при кортеже ("TEXT", "Текстовое поле") нужно указать type = "TEXT". Обратите внимание, что несмотря на различные указания, все данные будут хранитьсся в текстовом формате.
• placeholder - необязательное поле - если его не указать, то принимает значение null. Указывает текст, который будет служить плейсхолдером при ожидании значения поля.
• validation_regex - необязательное поле - если его не указать, то принимает значение null. Указывает регулярное выражение, соглано которому нужно проверять значение поля. Стоит обратить внимание, что значение хранится в текстовом формате.
• secure_text - булевый флаг, отвечающий за то, является ли текст защищённым или нет. Если тект является защищённым, то предполагается, что его значение при вводе должно скрываться. Это обычно делается для паролей.
• error_text - текст, выводимый при ошибке ввода. Обычно это может быть ошибка при несоответствии ввода по регулярному выражению validation_regex. Может быть null - тогда вывод ошибки при несоответствии регулярному выражению остаётся на разработчике. Текст ошибки не предполагает иные ошибки (например, ошибки отказа доступа или другие из семейства 400). Текст ошибки не адаптируется соглано коду ошибки и не подвержен HTML-структуре.

Создание полей через API

Имеется точки взяимодействия с API для создания различных полей, но точки взаимодействия будут отличаться. Для каждого модуля (пользователи, документы, лица) программы будут свои точки взаимодействия с API для работы с полями (см. далее)

Поля пользователя

Поля пользователя имеют related_item = "User".

Изначальные поля

При запуске миграций (python manage.py migrate) создаются (если их нет) ключевые поля для пользователя. Проверить и изменить их можно в файле backend/migrations/initial_fields_0005.py. По факту это только ФИО пользователя, но там можно проверить пример создания полей, если вы хотите добавить другие поля для создания при старте сервера.

Работа с полями пользователя

Имеются два API-метода для работы с полями пользователя. Здесь и далее будут указаны URL отноительно адреса https://127.0.0.1:8000.

• user/fields/create/ - POST-метод. Доступен только для суперпользователей или если DEBUG=True (см. core/settings/) Создаёт поле для пользователя. Принимает значения, необходимые для создания полей (см. #Поля). При успехе возвращает код статуса 201, "status": "success" и созданное поле "field". При ошибке возвращает код статуса 400 и текст ошибки "error".
• user/fields/fields/ - GET-метод для всех пользователей. Возвращает все поля пользователя, которые находятся в базе данных в формате списка (массива) объектов. Возврат идёт в формате полей (см. #Поля).

Работа со значениями полей пользователя

Все значения кастомных полей хранятся в отдельной таблице базы данных UsersValues (/backend/models/users.py).

• user - пользователь, к которому относится данное поле. Является ссылкой на объект базы данных User.
• field - поле, чьё значение бло записано. Является ссылкой на объект базы данных Field.
• value - значение поля. Стоит обратить внимание, что оно всегда сохраняется как текст, вне зависимости от типа поля. При получении значения поля, стоит вручную позаботиться о его переводе в нужный формат.

API-методы

Существуют несколько методов, которые изменяют данные поля пользователя. Все методы будут работать только для аутентифицированных пользователей. Все методы будут возвращать поля только для того пользователя, от лица которого будет идти запрос.

• user/fields/ - POST-/GET-метод. Позволяет получить и изменить все значения полей для авторизированного пользователя. При получении данных возвращает данные в стандартном формате (см. #Работа со значениями полей пользователя). При успешной записи возвращает код статуса 201 и записанные данные. При ошибки в записи возвращает код статуса 400 и описание ошибки.
• user/fields/<int:pk>/ - GET-/PUT-/DELETE-метод. Позволяет получить и изменить данные о значении определённого поля для авторизированного пользователя. pk является ID значения поля в базе данных: его можно получить через user/fields/. Если поле pk не найдено, возвращает код ошибки 404 и "error": "Поле не найдено". При получении данных, возвращает код 200 и указанное значение поля. При успешном изменении поля, возвращает код 200 и изменённое поле. При ошибке во время изменения, возвращает ошибку в теле ответа и код 400. При успешном удалении поля возвращает только код выполнения 204.

Все другие вопросы спрашивайте на странице проекта в Трекере.