# Роли

## Общее описание

`Роль` — административная единица для выдачи прав.

В роли выдаются гранты на привилегии.

Для выдачи дискретных привилегий на роли настраиваются дискретные правила, определяющие ограничения и передаваемые в них параметры.

Список ролей доступен по пути:
- `Администратор > Доступ > Роли`.

Система поддерживает следующие типы ролей:
- **Обычная роль** — стандартная роль с набором привилегий;
- **Мастер-роль** — специальная роль, позволяющая определять параметры дискретного доступа для подчинённых профилей.

Если для роли назначен параметр с типом `Определяется профилем`, роль должна иметь тип `Мастер-роль`.

## Интерфейс ролей

При открытии раздела `Роли` отображается окно, состоящее из двух частей:
- слева — дерево групп ролей;
- справа — список ролей, входящих в выбранную группу.

Если выбрать узел `Все роли`, в правой части отображается общий список всех ролей системы.

В списке ролей отображаются обзорные данные по роли:
- код роли;
- наименование;
- описание;
- признак `Не используется`;
- тип;
- изменивший пользователь;
- дата изменения.

В этом окне данные используются как обзорные. Основная настройка роли выполняется в карточке конкретной роли.

## Карточка роли

Карточка роли открывается при переходе к конкретной роли и используется для просмотра и изменения её параметров.

В карточке роли выполняется основная настройка прав, ограничений и дополнительных полномочий для выбранной роли.

В верхней части карточки отображаются:
- код;
- наименование;
- группа;
- тип;
- описание.

### Права роли

Во вкладке `Права роли` настраиваются права роли по административным объектам.

Вкладка `Права роли` является основной вкладкой карточки роли. В ней настраивается доступ роли к объектам системы, их атрибутам, операциям и переходам состояний.

Во вкладке отображается дерево администрируемых объектов со следующими уровнями:
- группа администрируемых объектов;
  - объект администрирования;
    - узел администрирования;
      - элемент администрируемого объекта.

```{tip}
По умолчанию отображаются только те администрируемые объекты, которые используются в роли. Чтобы отобразить все объекты, отключите флаг `Только объекты, на которые у роли имеются права` в панели фильтрации.
```

Для выбранного административного объекта или элемента во вкладке можно задать права роли. В зависимости от контекста здесь настраиваются:
- полный доступ;
- чтение;
- редактирование;
- добавление;
- удаление;
- интерактивные права;
- права на переходы состояний.

Основные типы прав во вкладке означают следующее:
- `Полный доступ`, `Чтение`, `Редактирование`, `Добавление`, `Удаление` — права на соответствующие действия с объектом и входящими в него нижестоящими элементами;
- `Интерактивные права` — права на выполнение операций в карточке и интерфейсе объекта;
- `Права на переходы состояний` — права на выполнение доступных переходов состояний.

Каждый тип элементарной привилегии отображается в отдельном столбце. Это позволяет массово выдавать права по типу для текущего уровня и всех вложенных.

**Расшифровка прав:**
- при выборе объекта администрирования отображается перечень типов элементарных привилегий и объектных привилегий;
- при выборе элемента администрируемого объекта отображается перечень элементарных привилегий для выбранной строки.

#### Выдача прав на объектные привилегии

1. Выберите нужный администрируемый объект.
2. В расшифровке прав отобразятся объектные привилегии.
3. Выдайте роли права на объектные привилегии.
4. Обновите индексы системных привилегий.

#### Выдача прав на тип элементарных привилегий

При выдаче права на тип элементарной привилегии доступ предоставляется ко всем элементарным привилегиям этого типа во всех элементах администрируемого объекта.

1. Выберите нужный администрируемый объект.
2. В расшифровке прав отобразятся типы элементарных привилегий.
3. Выдайте права на типы элементарных привилегий — в расшифровке прав или в дереве объектов.
4. Обновите индексы системных привилегий.

#### Выдача прав на элементарную привилегию

1. Выберите нужный элемент администрируемого объекта.
2. В расшифровке прав отобразятся элементарные привилегии.
3. Предоставьте доступ к нужным элементарным привилегиям.
4. Обновите индексы системных привилегий.

```{note} id="yaay5d"
Если установить признак `Запрещено`, пользователи с этой ролью не получат доступ к привилегии, даже если эта привилегия предоставлена другими ролями.
```

#### Перевод состояний

Раздел отображается при выборе объекта администрирования и позволяет настроить возможные переходы между состояниями.

Для настройки доступа к переходам состояний сначала необходимо определить возможные переходы для типа объекта. После этого на вкладке `Перевод состояний` выдаются права на доступные переходы.

#### Администрирование универсальных характеристик

Для разграничения доступа к универсальным характеристикам в динамически расширенных списках и карточках предусмотрены стандартные привилегии на чтение и изменение. Они именуются по системным именам УХ и имеют вид `UC_<системное имя УХ>`.

```{note} id="479l4r"
Если внутри элемента администрируемого объекта отсутствуют права на чтение и изменение уже наложенных универсальных характеристик, обновите администрируемый объект.
```

Также определены «общие» привилегии, предоставляющие доступ сразу ко всем универсальным характеристикам класса, шаблона или типа объекта. Для ссылочных атрибутов в имени привилегии используется постфикс `HL`, для значимых — без него.

**Список общих привилегий:**
- для расширенных списков:
  - чтение: `objAttrValue`, `objAttrValueHL`;
  - редактирование: `setobjAttrValue`, `setobjAttrValueHL`;
- для карточек объектных характеристик:
  - чтение: `sValue`, `sValueHL`;
  - редактирование: `setsValue`, `setsValueHL`.

Явные настройки на уровне конкретной характеристики имеют приоритет над общими:

| Сценарий | Глобальная привилегия | Настройка для конкретной УХ | Результат |
|---|---|---|---|
| Глобально редактирование разрешено, одна УХ запрещена | `[разрешено]` `setobjAttrValue` | `[запрещено]` `setUC_nNum` | Все УХ доступны для редактирования, **кроме** `nNum` |
| Глобально чтение запрещено, одна УХ разрешена | `[запрещено]` `sValueHL` | `[разрешено]` `UC_idDepOwner` | Чтение всех УХ запрещено, но `idDepOwner` доступна |

### Приложения, доступные для роли

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

Для каждого приложения в списке отображаются как минимум его наименование и системное имя.

Доступ к приложениям определяется привилегиями административного объекта `Приложения`. Выданные права на такую привилегию обеспечивают отображение приложения в меню выбора приложений.

В детализации приложения отображаются пункты меню, входящие в это приложение.

### Пункты динамического меню, доступные для роли

Во вкладке `Пункты динамического меню, доступные для роли` отображаются пункты динамического меню, доступные пользователям с данной ролью.

Если для элемента динамического меню установлен признак `Доступно`, этот признак автоматически устанавливается для всех предков, начиная с корневого элемента, и для всех потомков выбранного элемента. При снятии признака он снимается для всех потомков данного пункта меню.

### Профили роли

Во вкладке `Профили роли` для выбранной роли задаются профили, в состав которых должна входить эта роль.

Вкладка используется для настройки связи роли с профилями. На вкладке доступны операции включения роли в профили и удаления её из профилей.

### Пользователи роли

Во вкладке `Пользователи роли` отображаются пользователи, у которых назначена данная роль.

На этой вкладке роль пользователю не задаётся, а показывается, на каких пользователях она уже есть. Роли не назначаются пользователям напрямую: пользователь получает роль через профиль. Для каждого пользователя можно определить, от какого профиля он получил данную роль.

В списке и карточке `Роли` для этой вкладки доступна операция:
- `Пересчитать индексацию привилегий для текущего пользователя`.

### Дискретный доступ

Во вкладке `Дискретный доступ` задаются параметры дискретного доступа для выбранной роли.

В этой вкладке настраиваются значения параметров для ограничений, связанных с административными объектами и привилегиями. Если для объектной или элементарной привилегии указано ограничение дискретного доступа, оно проверяется в контексте объекта или строки выборки.

### Серверные полномочия

Во вкладке `Серверные полномочия` настраивается доступ роли к серверным возможностям JEXL.

Вкладка включает следующие разделы:
- `Доступ к API` — настройка доступа к вызову методов API из JEXL-скриптов;
- `Доступ к пакетам` — настройка доступа к пакетам (`Pkg`) из JEXL-скриптов;
- `Разрешения JEXL` — настройка разрешений на использование Java/Scala-пакетов и классов в JEXL-скриптах.

Подробности по настройке этих разрешений приведены в статье `Администрирование JEXL`.

#### Доступ к API

Чтобы настроить доступ к API:
1. Перейдите на закладку `Серверные полномочия > Доступ к API`.
2. Найдите нужный API.
3. В разделе `Права на вызов методов из JEXL` выберите методы и установите признак `Имеется право`.
4. Чтобы разрешить вызов всех методов API, установите флаг `Доступны все методы API через JEXL`.

#### Доступ к пакетам

Доступ к пакетам (`Pkg`) настраивается аналогично на закладке `Серверные полномочия > Доступ к пакетам`.

#### Разрешения JEXL

Во вкладке `Разрешения JEXL` настраивается использование Java/Scala-классов и пакетов в JEXL-скриптах.

Для выдачи прав на пакет:
- укажите тип привилегии `package`;
- в поле имени укажите полное имя пакета.

Для выдачи прав на класс:
- укажите тип привилегии `class`;
- в поле имени укажите полное имя класса.

Чтобы разрешить только отдельные методы класса, перечислите их в поле `Методы` в виде JSON-массива.

Если нужно разрешить все методы, кроме указанных, установите флаг `Указанные методы исключающие`.

### Доступ к таблицам в SQL-запросах

Во вкладке `Доступ к таблицам в SQL-запросах` настраиваются права роли на использование таблиц в SQL-запросах из JEXL.

Подробности по этой настройке также приведены в статье `Администрирование JEXL`.

Чтобы настроить доступ:
1. Перейдите на вкладку `Доступ к таблицам в SQL-запросах`.
2. Найдите нужную таблицу.
3. Установите права с помощью чекбоксов:
   - `Select` — чтение;
   - `Update` — изменение;
   - `Delete` — удаление;
   - `Insert` — вставка.

Права на `Insert` можно выдать только для таблиц в схемах:
- `public`;
- `aud`;
- `global_dev`;
- `global_system`.

```{note} id="ch7wax"
Права на `Select` могут быть получены при наличии любой не запрещающей привилегии на администрируемом объекте, соответствующем данной таблице.
```

### Право подписи

Во вкладке `Право подписи` отображаются настройки, связанные с правом подписи для роли.

### Доступ к складам

Во вкладке `Доступ к складам` отображаются склады, доступ к которым предоставлен для роли.

### Доступ к операциям по заказам

Во вкладке `Доступ к операциям по заказам` отображаются операции по заказам, доступные для роли.

### Доступ к проводкам по счетам

Во вкладке `Доступ к проводкам по счетам` отображаются проводки по счетам, доступные для роли.

## Групповая настройка привилегий ролей

Выборка `Групповая настройка привилегий ролей` предназначена для массовой выдачи привилегий ролям от администрируемого объекта.

Выборка доступна по пути:
- `Администратор > Доступ > Групповая настройка привилегий ролей`.

**Принцип работы:**
1. Выберите нужный администрируемый объект.
2. Выберите нужные роли — в панели фильтрации откройте список подбора для поля `Перечень ролей`.
3. Проставьте гранты на нужных привилегиях.
4. Пересчитайте индексы привилегий — выполните операцию `Пересчитать индексацию привилегий` в интерфейсе `Перечень ролей`.

### Дерево администрируемых объектов

Уровни дерева:
- группа администрируемых объектов;
  - объект администрирования;
    - узел администрирования;
      - элемент администрируемого объекта.

Объекты администрирования могут не входить в группу. В этом случае они считаются корневыми.

**Операции дерева:**
- `Обновить выбранный объект` — обновляет выделенный объект или элемент. При обновлении сканируется исходный код, добавляются недостающие привилегии и элементы;
- `Обновить администрируемый объект по имени` — обновляет объект по указанному имени;
- `Обновить администрируемые объекты модуля` — обновляет все администрируемые объекты модуля.

```{note} id="vlx2yt"
Классы-коллекции не имеют собственных объектов администрирования и входят в объект мастера. Для обновления настроек коллекций обновляйте администрируемый объект по имени класса-мастера.
```

### Настройка прав

На закладке отображается настройка прав для ролей в зависимости от выделенной записи в дереве:
- для администрируемого объекта — объектные привилегии;
- для элемента администрирования — типы элементарных привилегий и элементарные привилегии.

Колонки ролей формируются динамически по ролям, выбранным в фильтре.

**Операции настройки прав:**
- `Подобрать роли` — подбирает в фильтр роли, для которых уже есть права на текущий объект или элемент.

### Пользователи и профили

В активной ячейке отображаются пользователи и профили, связанные с выбранной ролью.

## Технические сведения

Для работы системы администрирования в отображении объявлены следующие функции:
- `onLoadAdminMeta` — применяет настройки администрирования;
- `acObject` — возвращает имя администрируемого объекта;
- `acObjectBundle` — возвращает имя узла администрирования;
- `acObjectItem` — возвращает имя элемента администрирования;
- `isAdministraded` — определяет признак администрирования выборки.

Для проверки привилегий и ролей используются функции:
- `ru.bitec.app.btk.Btk_AdminPkg#hasObjPriv` — проверяет наличие объектной привилегии у пользователя;
- `ru.bitec.app.btk.Btk_AdminPkg#hasStateChangePriv` — проверяет привилегию на переход состояния;
- `ru.bitec.app.btk.Btk_AdminPkg#hasRole` — проверяет наличие роли у пользователя.
```