DOF - Вклад участника [ru]

Разработка:Управление доступом

2024-04-25T10:29:27Z

Kuznetsova: /* Правила работы с правами доступа */

= Управление доступом =
На этой странице содержится вся основная информация по управлению доступом. "Электронный Деканат" имеет собственную систему полномочий, которая дополняет систему полномочий moodle, и позволяет реализовать более гибкое управление правами.

== Общая информация ==

=== Плагины необходимые для системы управления доступом ===

* [[Разработка:storages/acl | acl ]] - список полномочий. Хранит информацию о том в каком плагине какие полномочия существуют.
* [[Разработка:storages/aclwarrants | aclwarrants ]] - Мандаты и доверенности.
* [[Разработка:storages/aclwarrantagents | aclwarrantagents ]] - Применение доверенностей. Определяет, каким пользователям какие доверенности выданы.

=== Общие правила и требования ===
* Сторонние плагины могут зависеть от плагинов прав доступа, а плагины прав доступа не могут зависеть от остальных плагинов, и извлекать информацию из них (за исключением события установки/обновления плагина).
* Каждый плагин, предоставляющий права доступа должен описывать права в функции acldefault()
** Формат массива:
<pre>
array(
'view' => array('teacher', 'manager'),
'edit' => array('manager')
);
</pre>
В качестве ключей указывается то право, которое назначается, а значением служит массив ролей, которые получают это право. Список стандартных ролей можно посмотреть в плагине [[Разработка:storages/aclwarrants | aclwarrants ]]
* Все плагины, отвечающие за работу с полномочиями имеют префикс acl.
* Все функции в сторонних плагинах, которые управляют правами доступа должны иметь префикс acl
* В плагинах типа im и modlib следует для проверки стандартных прав доступа обращаться к плагинам storage.
* При построении прав на смену статуса объектов деканата имеет значение лишь то, в какой статус будет осуществлен перевод. Следовательно, необходимо реализовывать только права changestatus:to:СТАТУС.
** Право changestatus:from:СТАТУС следует устанавливать только для ограничения возможности вывода из спецстатусов.
** Право changestatus без модификаторов, дает право перевода из любого статуса в любой, кроме специальных (для которых объявлено право changestatus:from:Статус). Право changestatus:to:Статус дает право на перевод в целевой статус из любого другого, кроме специальных, для которых объявлено право changestatus:from:Статус.

=== Как происходит процесс установки прав ===
При установке, обновлении или удалении любого плагина, если он предоставляет права доступа - то в функциях upgrade(), delete(), и install() нужно вызывать функцию save_roles() плагина [[Разработка:storages/acl | acl ]].

== Правила работы с правами доступа ==

=== Полномочия (acl) ===
* Полномочия не имеют статусов, поэтому при удалении плагина все полномочия, принадлежащие ему также физически удаляются из таблицы
* Для хранилищ и рабочих процессов существуют [[ Разработка:storages/acl#.D0.A1.D1.82.D0.B0.D0.BD.D0.B4.D0.B0.D1.80.D1.82.D0.BD.D1.8B.D0.B5_.D0.BF.D0.BE.D0.BB.D0.BD.D0.BE.D0.BC.D0.BE.D1.87.D0.B8.D1.8F_.D0.B4.D0.BB.D1.8F_.D1.85.D1.80.D0.B0.D0.BD.D0.B8.D0.BB.D0.B8.D1.89_.D0.B8_.D1.80.D0.B0.D0.B1.D0.BE.D1.87.D0.B8.D1.85_.D0.BF.D1.80.D0.BE.D1.86.D0.B5.D1.81.D1.81.D0.BE.D0.B2 | стандартные полномочия ]]
* Полномочия проверяются только тем плагином, в котором они содержатся. То есть - из im/persons можно проверять только права im/persons, из storage/persons только права storage/persons. Нельзя проверять из одного плагина права другого плагина.

=== Мандаты и доверенности (warrants) ===
* Действия при удалении мандата или доверенности
** Основным способом удаления мандата следует считать перевод записи в статус "archive"
** Все дочерние доверенности и мандаты также перестают действовать
** Прекращают действия все применения полномочий ([[Разработка:storages/aclwarrantagents | aclwarrantagents ]]) которые были назначены указанным мандатом.
* При установке прав новым плагином все новые права добавляются к стандартным доверенностям
* Плагины не могут добавлять свои доверенности при установке
* Стандартные доверенности не могут быть назначены пользователям
* Если запрещается наследование для доверенности, которую раньше можно было наследовать - то старые дочерние доверенности продолжают свое действие, но новые создать нельзя

==== Синхронизация ====
Здесь описаны плагины, которые должны синхронизироваться с таблицей доверенностей.
* [[Разработка:storages/positions | storage/positions]]

=== Применение полномочий (warrantagents) ===
* При прекращении действия доверенности, применение полномочия прекращает действовать (переводится в статус archive)
* При истечении срока действия применение полномочия переводится в статус archive

==== Синхронизация ====
Здесь описаны плагины, которые должны синхронизироваться с таблицей применения полномочий.
* [[Разработка:storages/appointments | storages/appointments ]]

=== Опасные действия и режим работы в обход стандартной логики (datamanager) ===

Режим datamanager позволяет админам действовать в обход стандартной логики на свой страх и риск. Такие действия могут понадобиться, например, в случае выполнения ошибочных действий сотрудниками, однако не должны быть доступны обычным пользователям во избежание потери данных или консистентности данных. Чтобы для выполнения этих действий не требовалась модификация напрямую через СУБД, реализован опасный режим.

Для перехода в опасный режим персона должна иметь соответствующее право и подтвердить свое согласие с переходом в опасный режим через интерфейс системы.

Проверка опасного режима должна осуществляться через реализованный метод is_datamanager(), который проверит и право и согласие. Проверка режима через инструменты прав доступа в настоящий момент является устаревшей и должна быть заменена на использование выше указанного метода.

==== Принципы реализации проверок для режима datamanager ====

* В обычном режиме пользователю должны быть заблокированы любые изменения, которые могут привести к неочевидному (или не очень очевидному) безвозвратному уничтожению или порче данных.
Также могут быть заблокированы изменения, которые способны нарушить консистентность и корректность данных.
* По возможности необходимо реализовать более полные и глубокие проверки, например, запрещать не любое изменение даты, а только опасное, вызывающее противоречие и могущее повлечь порчу данных (например, дата старта обучения должна быть не позже даты первого результата обучения, оценки, подписки на элемент учебного плана и т.п.). При недостатке ресурсов предпочитаем полное блокирование изменения поля и полагаемся на режим datamanager, где пользователь может выполнить изменения полностью на свой страх и риск, самостоятельно проверив непротиворечивость данных.
* Режим datamanager разрешает любое редактирование. Опасные ситуации, которые могут привести к порче данных, должны быть доступны только в этом режиме и описаны.
* datamanage - это право, предназначенное только для игнорирования некоторых (добавленных с целью сохранения консистентности) валидаций данных, она не добавляет и не убирает никаких прав, если их нет, для выполнения опасного действия помимо собственно нужно иметь право для исполнения этого действия и подтвержденное согласие работы в опасном режиме

При принятии технических решений полная блокировка потенциально опасного действия предпочтительна непредсказуемому каскадному обновлению данных после этого действия. Например, если изменение даты начала подписки на программу может привести к пересчету истории обучения и ее порче, предпочитаем заблокировать такое изменение (пока пользователь руками не поправит все объекты, вступающие в противоречие с изменением), а не выполнять в фоне опасное каскадное действие.

[[Категория:Разработка]]
[[Категория:Управление доступом]]

Разработка:storages/orders

2022-03-28T10:10:25Z

Kuznetsova: исправление орфографической ошибки в тексте

{{Infobox_Plugin
| name = orders
| type = storages
}}

= Принцип работы =
Приказы - единоличные, законченные, единовременные распоряжения пользователей системы, на выполнение значимых действий с данными в системе. Реализуют протоколирование и исполнение как обычных приказов (приказ о зачислении, приказ о переводе), так и подразумеваемые приказы (выставление оценки, изменение статуса объекты).
Не обязательно все действия в системе должны выполняться через приказы, однако нужно стремится реализовать как приказы все действия, которые необходимо протоколировать и для работы с которыми в будущем предполагается использовать индивидуальную цифровую подпись. При последующей реализации индивидуальной цифровой подписи, ею можно будет заверять только действия, оформленные в качестве приказов. Сейчас при обработки приказов вычисляются контрольные суммы данных (сигнатуры sha1), для затруднения несанкционированного изменения данных (требуется ключ, сохраненный в конфигурационном файле).

С программной точки зрения работа с приказами построена следующим образом:
* Плагин, "желающий" реализовать собственный приказ наследует родительский класс приказа (dof_storage_orders_baseorder), объявленный в справочнике "приказ". Базовый класс содержит методы для наполнения приказа данными, исполнения приказа, получение из БД данных о ранее исполненном приказе. В дочернем классе эти методы переопределяются, в соответствии с логикой работы данного приказа.
* Для унификации, плагин, использующий приказы, должен реализовать метод order($code,$id=null), который возвращает объект нового или существующего приказа.
* При сохранении приказа, данные сохраняются в справочник orders в сериализованном виде, или в другие справочники (для этого можно использовать методы load_data() и save_data() либо в классе приказа переопределяются методы load() и save(), которые сохраняют/читают часть данных в других справочниках и убирают/добавляют их в поле data). При сохранении указывается ответственный сотрудник (подготовивший приказ) и отдел, к которому приказ относится.
* До исполнения приказа его необходимо подписать с помощью метода sign(), при этом формируется хешь от всех данных приказа (включая отсутствующие в sdata) и записывается в поле signature. Подпись приказа рассчитывается с учетом id подписанта. Если данные из других справочников будут возвращены в другой последовательности, либо данные будут измененыв в других справочниках в обход приказа, цифровая подпись станет недействительной.
* Подписанный приказ можно один раз исполнить методом execute(). При этом выполняются все действия, сопутствующие исполнению приказа. При необходимости, часть данных из sdata в другие справочники может переноситься именно на этом этапе, тогда переопределенная функция load() должна уметь их получить. Исполненный приказ помечается как исполненный. Это конечное состояние, удалить исполненный приказ нельзя, его действие можно отменить только другим, противоположным по эффекту приказом (если такой предусмотрен). Повторно исполнить приказ нельзя.
* Справочник "приказы" содержит метод, для получения записанного в БД приказа, при этом на основании информации из БД инициализируется соотествующий объект, который загружает собственные данные любым способом. Для этого используются методы order() в плагинах, реализовавших соответствующие типы приказов.

Данные приказа представляют собой сложно-структурированный объект (тип object), элементами которого могут быть скалярные значение, другие объекты и массивы. После исполнения приказа эти данные могут протоколироваться как в сериализованном виде, так и в реляционном, в виде составных частей записей в БД. Следует стремится к тому, чтобы формат этого объекта соответствовал формату входных данных для шаблона, отображающего приказ в виде документа ODF и в других форматах. Для этого формат объекта планируется совместимым с шаблонизатором [[Разработка:modlibs/templater]], с тем, чтобы приказы можно было распечатывать без дополнительной обработки.

=Таблица в базе данных=
''orders'' - список зарегистрированных и исполненных приказов, с информацией о плагине, реализующем объект приказа, исполнителе, дате исполнения.

===Подробный формат полей в таблице:===
* plugintype - тип плагина, в котором реализован приказ
* plugincode - код плагина, в котором реализован приказ
* pluginversion - версия плагина, в котором реализован приказ
* code - код типа приказа (уникален внутри одного плагина)
* departmentid - id отдела в таблице [[Разработка:storages/departments | departments ]], внутри которого издан приказ
* ownerid - id персоны в таблице [[Разработка:storages/persons | persons ]], подготовившей приказ
* signerid - id персоны в таблице [[Разработка:storages/persons | persons ]], подписавшей приказ
* date - дата приказа (которой он пройдет по документам)
* signdate - дата подписания приказа в системе
* exdate - дата исполнения приказа в системе
* crondate - дата исполнения приказа по крону
* changedate - дата последнего изменения приказа
* status - список статусов указан в одноименном плагине рабочих процессов [[Разработка:workflows/orders | orders ]]
* sdata - сериализованные данные приказа. Вынесены в отдельный справочник для хранения [[Разработка:storages/orderdata | даных приказа ]]
* signature - сигнатура приказа (sha от signerid, ключевого слова из конфига,signdate,date и сериализованной data)
* notes - заметки

=Дополнительные методы:=

===='''get_list_by_code($plugintype,$plogincode,$code,$departmentid=null,$ownerid=null,$signerid=null,$status=null,$limitfrom="",$limitnum="")'''====

Выдает список приказов по параметрам

''Аргументы:''
* (str) $plugintype - тип плагина, в котором реализован приказ
* (str) $plogincode - код плагина, в котором реализован приказ
* (str) $code - код типа приказа (уникален внутри одного плагина)
* (int) $departmentid - id отдела в таблице departments , внутри которого издан приказ, по умолчанию null
* (int) $ownerid - id персоны в таблице [[Разработка:storages/persons | persons ]], подготовившей приказ, по умолчанию null
* (int) $signerid - id персоны в таблице [[Разработка:storages/persons | persons ]], подписавшей приказ, по умолчанию null
* (str) $status - статус приказа, по умолчанию null
* (int) $limitfrom - id, начиная с которого надо искать, по умолчанию пусто
* (int) $limitnum максимальное количество записей, которое надо вернуть, по умолчанию пусто
''Возвращает значение:''
* (mixed) массив объектов если что-то нашлось или false

== API ==
=== dof_storage_orders_baseorder ===
Класс является базовым классом для типов приказов, объявляемых в плагинах. Дочерние классы должны именоваться по шаблону dof_типплагина_кодплагина_order_кодприказа и располагаться в папке orders/кодприказа/init.php внутри объявляющего их плагина.
* plugintype(),plugincode(),code() - получить идентификационную информацию о типе документа (должны быть объявлены в дочерних классах и возвращать строки).
* baseptype(), basepcode() - идентификация плагина storages/orders, если объекту понадобиться обратиться к справочнику orders.
* get_id() - получить id текущего объекта
* set_id() - установить id. Не может вызываться напрямую, только через методы save() и load()
* load($id,$withoutdata=false) - проверить наличие объекта совместимого типа в БД и сопоставиться с ним. Если требуется - собрать и вернуть данные объекта. Возвращается объект из справочника orders, с убранными полями sdata, plugintype, plugincode, code и добавленным полем data, куда помещены десериализованные данные из sdata, если они были запрошены. Если данные необходимо сохранять в других справочниках, в дочернем классе переопределяется метод load_date() либо сам метод load(), а родительский метод вызывается через parent::. При загрузке к объекту в поле $order->data добавляются копии служебных полей, с префиксом из символа подчеркивания, чтобы эти данные сразу можно было использовать в шаблонах.
* save(object $data) - сохранить данные приказа в БД. Перед сохранением убираются поля, которые нельзя изменять напрямую (plugintype, plugincode, code, exdate, changedate, status, sdata, signerid, signature, signdate, data). Данные из data сериализуются в sdata. Если часть данных после сохранения или исполнения хранится в других справочниках, можно переопределить метод save_data(), либо сам метод save() должен быть переопределен, а родительский вызывать через parent::. При этом, для корректности цифровой подписи необходимо обеспечить получение полей в той же последовательности, в которой они были сохранены. Кроме того, при сохранении удаляются копии служебных полей из поля $order->data, чтобы избежать дублирования при сохранении.
* execute() - исполнить текущий приказ и пометить его как исполненный, если он был корректно подписан. Как правило переопределять не требуется, так как все сопутсвующие действия можно поместить в execute_actions().
* execute_actions() - исполнить действия, сопутствующие выполнению приказа (вызывается после проверки подписи в execute()). Если данные переписываются в другие справочники, они должны быть записаны так, чтобы функция load() прочитала все поля в точности в той же последовательности, как они были в сериализованном виде, иначе подпись не сойдется.
* notes() - сохранить заметки о приказе (не считается изменением приказа и не влияет на подпись)
* sign() - подписать объект по id
* is_signed() - проверить подпись по id
* make_sign() - сфоормировать строку подпись по объекту, возвращенному load(), при этом подпись зависит от порядка полей и чувствительна к любым изменениям данных. Несущественные и часто-меняющиеся данные необходимо выносить за пределы приказа и подгружать уже непосредственно перед их использованием.
* check_signature() - проверить корректность подписи по объекту, возвращенному load()

=== Пример объявления нового приказа ===

<code php>

// Инициализируем работу с приказами
$DOF->storage('orders');
// Объявляем класс
class dof_im_exampleim_order_delete extends dof_storage_orders_baseorder
{
/**
* Тип плагина, объявившего тип приказа
*/
public function plugintype()
{
return 'im';
}
/**
* Код плагина, объявившего тип приказа
*/
public function plugincode()
{
return 'exampleim';
}
/**
* Код типа приказа
*/
public function code()
{
return 'delete';
}
/**
* Исполнить действия, сопутствующие исполнению приказа
*
* @param object $order
* @return bool
*/
protected function execute_actions($order)
{
// Удаляем объект, который потребовали удалить в приказе
return $this->dof->storage('examplest')->delete($order->data->id);
}
}
</code>

=== Пример использования ===
В базовый класс плагина добавляется метод
<code php>
/**
* Возвращает объект приказа
*
* @param string $code
* @param integer $id
* @return dof_storage_orders_baseorder
*/
public function order($code,$id=NULL)
{
switch ($code)
{
case 'delete':
// Хорошей мыслью будет сделать сдесь кеширование
$order = new dof_im_exampleim_order_delete($this->dof);
if (!is_null($id))
{
if (!$order->load($id))
{
// Не найден
return false;
}
}
// Возвращаем объект
return $order;
break;
default:
// Ошибка
return false;
break;
}
}
</code>

Использование
<code php>
// Создаем экземпляр приказа напрямую
// $order = new dof_im_exampleim_order_delete($DOF);
// Или через плагин
$order = $DOF->im('exampleim')->order('delete');
// Вводим данные (id, отдел, ответственный, время в приказе)
$orderobj = new object();
$orderobj->departmentid = 1;
$orderobj->ownerid = 2;
$orderobj->date = time();
$orderobj->data->id = $id;
// Сохраняем приказ в БД и привязываем экземпляр приказа к id
$order->save($orderobj);
// Подписываем от имени персоны 2
$order->sign(3)
</code>

=События=
В этом разделе описан список всех событий, которые генерируются, перехватываются и обрабатываются этим плагином.
====Перехватываемые события====
{| border="1"
|+ Таблица событий, которые перехватывает этот плагин
! Тип плагина
! Код плагина
! Код события
! Доп. данные
! Пояснение
|-
|colspan=5 align=center | ''Этот плагин не перехватывает никаких событий''
|}
====Генерируемые события====
{| border="1"
|+ Таблица событий, которые генерирует этот плагин
! Тип плагина
! Код плагина
! Код события
! Доп. данные
! Пояснение
|-
|storage
|orders
|insert
|Массив, содержащий в поле "new" объект с данными для вставки в таблицу.
''Пример:'' array('new' => $dataobject)
|Генерируется каждый раз при вставке новой записи в таблицу orders.
|-
|storage
|orders
|update
|Массив, содержащий в поле "new" обновленный объект, и в поле "old" объект со старыми данными, до обновления записи.
''Пример:'' array('old' => $dataobject_old, 'new' => $dataobject_new)
|Генерируется каждый раз при обновлении записи в таблице orders.
|-
|storage
|orders
|delete
|Массив, содержащий в поле "old" объект с данными, которые удаляются из таблицы
''Пример:'' array('old' => $dataobject)
|Генерируется каждый раз при удалении записи из таблицы orders.
|}

=Задания=

{| border="1"
|+ Таблица заданий, которые выполняет этот плагин
! Код задания
! Дополнительный параметр
! Пояснение
|-
|orders_on_orderdata
|Необязателен
|Находит все приказы, в которых хранятся данные в виде сериализованного объекта, после чего записывает эти данные в таблицу [[Разработка:storages/orderdata | orderdata ]] в виде скалярных значений.
|}

[[Категория:Плагины обработки todo | storages/orders]]