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

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

Список пользователей можно открыть из пункта меню:

- `Администратор \ Доступ > Пользователи`

### Ограничение имени пользователя
Имя пользователя имеет вид <локальная_часть>@<домен>, домен не является обязательной частью имени пользователя.

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

Общая длина имени пользователя не должна превышать 1024 байт (октет), включая символ @

Ограничения локальной части (До последнего символа @):

- Прописные и строчные буквы латинского алфавита: (A-Z), (a-z)
- Цифры: (0-9)
- Специальные символы: !#$%&"*+-/=?^_`{|}~
- Символ (.), если он не является первым или последним, а так же если они не идут друг за другом.
- Следующие специальные символы разрешены, только если локальная часть выделена в кавычки: пробел и "(),:;<>[\]

Ограничения домена (После последнего символа @):

- Прописные и строчные буквы латинского алфавита: (A-Z), (a-z)
- Цифры: (0-9)
- Специальный символ: -, если он не является первым или последним

Имя пользователя должно составляться по стандарту [RFC 822](https://www.w3.org/Protocols/rfc822/#z7)

Длина имени используется из стандарта [Active Directory](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-adls/63f5e067-d1b3-4e6e-9e53-a92953b6005b)

### Отключение администрирования
В случае, если у пользователя стоит признак `Супер-пользователь`, настройки администрирования 
не применяются, под таким пользователем можно совершать в системе любые действия. 
Данный признак удобно использовать для разработки и тестирования, так как это позволяет
отделить администрирование от разработки.

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

Администрируемый объект генерируется в момент установки или обновления системы по таким объектам как:
- Произвольная выборка
- Класс
  - Справочник
  - Настройка
  - Журнал
  - Документы
- Пакеты
- Приложения

Список административных объектов можно открыть из пункта меню:
- `Администратор \ Настройки > Администрируемые объекты`

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

- `Не распространяются настройки администрирования` \
  Если флаг установлен, на объекты представляющие состав административных объектов не 
  распространяются настройки администрирования
- `Не требуется настройка прав доступа на состояния` \
  Если флаг установлен, на документе данного административного объекта выключается контроль доступных переходов между состояниями.

### Узел администрирования
Группирует элементы администрируемого объекта для массовой раздачи прав, по умолчанию создается одна основная группа на каждый администрируемый объект. 

Узел администрирования зарезервирован на случай, если в системе потребуется настраивать права в зависимости от `типа объекта` или `состояния`


### Элементы администрируемого объекта
Элемент административного объекта создается на объекты которые требуют раздачи прав на `элементарные привилегии`.

#### Выборка
По умолчанию выборка со всеми отображениями регистрируется в один `элемент администрируемого объекта` с именем `{SelName}#Default`.
При этом на каждую операцию и атрибут в разрезе системного имени создается `элементарная привилегия`. 

Для переноса отображения в отдельный `элемент администрируемого объекта` существует аннотация:
```scala
@AcItemRep(name = "{Name}")
```
В таком случае `элемент администрируемого объекта` получит имя `{SelName}#{Name}`
Так же `элемент администрируемого объекта` можно задать в `avm.xml` через атрибут отображения `acItemRep`

```{note}
Изменения вступят в силу после обновления административного объекта (см. главу `Групповая настройка привилегий ролей`)
```

Для создания `элементов администрируемого объекта` по выборкам, не имеющим класса, в `avm` файле обязательно должен быть тег `<acObject/>`. 
Для выборок без класса формируется `администрируемый объект` и `элемент администрируемого объекта` с суффиксом `Avi` в имени. 

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

### Элементарные привилегии
`Элементарные привилегии` используются для разграничения действий пользователя и создаются следующим образом:
- по выборке на:
  - Операции \
    Создаются дискретные привилегии
  - Атрибуты
  - Сеттеры атрибута \
    Создаются дискретные привилегии

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

- Чтение \
  Содержит настройки видимости атрибутов.
- Редактирование \
  Содержит сеттеры атрибутов.
- Добавление \
  Содержит операции вставки и копирования.
- Удаление \
  Содержит операция удаления.
- Интерактивные права \
  Содержит остальные операции.


Для изменения типа привилегии, которой соответствует операция выборки, существует аннотация `@AcPrivilegeType`.
Пример:
```scala
@AcPrivilegeType(value = PrivilegeTypes.Read)
def myOperation(): Unit = {}
```

```{note}
Изменения вступят в силу после обновления административного объекта (см. главу `Групповая настройка привилегий ролей`)
```

### Объектные привилегии
`Объектные привилегии` позволяют раздавать права на бизнес логику.

#### Авто генерируемые объектные привилегии
- edit# \
  Создаются дискретные привилегии
- view# \
  Создаются дискретные привилегии
- viewReport# \
  Создаются дискретные привилегии

#### Привилегии на переход состояний

Привилегии на переход состояний ограничивают доступные переходы состояния. 
Ограничения на переходы реализовано в стандартном выпадающем списке для состояний `ru.bitec.app.btk.Btk_ClassStateAvi.Lookup_Class`

Имя привилегии формируется по правилу:

```scala
s"StateChange_OT:${idObjectType}_SS:${idStartState}_FS:$idFinishState"
```

Функция для определения возможности перехода: `ru.bitec.app.btk.Btk_AdminPkg#hasStateChangePriv`.

#### Ручное создание объектных привилегий
Для ручного создания объектных привилегий на классе(`odm.xml`) или пакете(`pkg.xml`) используются xml разметка, пример:
```xml
<admin>
    <privileges>
        <privilege name="SbtManage" caption="Управление решением"/>
    </privileges>
</admin>
```

```{note}
Изменения вступят в силу после обновления административного объекта (см. главу `Групповая настройка привилегий ролей`)
```

#### Приложение
Для администрирования приложений создается адм. объект `Приложения`(`Btk_ApplicationsListPkg`).
Объектные привилегии импортируются в него  из xml файлов `META-INF/applications.xml` всех подключенных модулей. 

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


### Дискретные ограничения
Дискретные ограничения позволяют задавать выражения для создания правил выдачи дискретных привилегий на конкретной роли. 
Подробности смотрите в главе `Дискретный доступ`
Принцип настройки дискретных ограничений:
1. Администратор определяет дискретные ограничения на административном объекте
2. Администратор определяет дискретные правила в роли \
   Каждое правило содержит дискретное ограничение и набор параметров
3. Администратор выдает грант на дискретную привилегию роли \
   При этом при синхронизации пользователей проходит расчет дискретных 
   привилегий данных пользователю по алгоритму объединения грантов

При проверки привилегии в бизнес логике, в функцию проверки передается перечень строк, для которых выполняется проверка.
При ограничении запроса по дискретной привилегии, каждое ограничение добавляется в where условие.

Алгоритм объединение грантов:
1. Пусть `g1` и `g2` гранты пользователю на объектную привилегию `p`
2. Если `g1` или `g2` с типом полный доступ, вернуть грант на `p` c полным доступом
3. Иначе вернуть грант на `p` объединив ограничения 

Алгоритм объединения ограничений:
1. Пусть `A` массив ограничений для грантов `g1` и `g2`
2. Пусть `S` пустое множество ограничений(параметры ограничения не в ходят в ключ множества)
3. Для каждой `g` из `A`
   1. Если `g` существует в `S`, добавить новые параметры к ограничению в `S`
   2. Иначе добавить `g` к `S`
4. Вернуть `S` 

#### Скрипт фильтрации
Используется в универсальной фильтрации для ограничения видимости по объектам.

#### Скрипт проверки объектного кэша
Используется в автономной бизнес логики для проверки возможности действия со строкой.

## Роль
`Роль` - административная единица для выдачи прав. 
Для раздачи дискретных привилегий на роли могут быть настроены дискретные правила, которые определяют 
дискретные ограничения и передаваемые в них на гранте параметры.

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

Список ролей можно открыть из пункта меню:
- `Администратор \ Доступ > Роли`

## Профиль пользователя
`Профили пользователя` используется для группировки ролей для более удобной раздачи их пользователю.

Список профилей можно открыть из пункта меню:
- `Администратор \ Доступ > Профили`

## Замещение прав

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

Список замещений можно открыть из пункта меню:
- `Администратор \ Доступ > Замещение прав`

## Индексация привилегий пользователей
Для быстрой проверки привилегий пользователя используются `индексы привилегий`.
Индексы привилегий необходимо пересчитывать после завершения редактирования ролей и их выдаче пользователю.

## Предустановленные профили

### Профиль "Отладчик"

`Профиль "Отладчик"` предназначен для пользователей, для которых нужно предоставить доступ к инструментам отладки.
Таким как:
- доступ к операциям управления решением (управление SBT)
- возможность открыть дебаггер
- выполнение jexl скриптов в дебагере
- доступ к инструментам меню Сервиса
- доступ к инструментам отладки клиента

### Профиль "Разработчик"

`Профиль "Разработчик"` предназначен для пользователей, которые являются разработчиками.
Включает в себя все права профиля "Отладчик". А также имеет доступ к следующим инструментам:
- доступ к редактированию справки