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

Плагин
Название	orders
Тип	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 отдела в таблице departments , внутри которого издан приказ
• ownerid - id персоны в таблице persons , подготовившей приказ
• signerid - id персоны в таблице persons , подписавшей приказ
• date - дата приказа (которой он пройдет по документам)
• signdate - дата подписания приказа в системе
• exdate - дата исполнения приказа в системе
• crondate - дата исполнения приказа по крону
• changedate - дата последнего изменения приказа
• status - список статусов указан в одноименном плагине рабочих процессов orders
• sdata - сериализованные данные приказа. Вынесены в отдельный справочник для хранения даных приказа
• 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 персоны в таблице persons , подготовившей приказ, по умолчанию null
• (int) $signerid - id персоны в таблице 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()

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

// Инициализируем работу с приказами
$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);
   }
}

Пример использования

В базовый класс плагина добавляется метод

   /**
    * Возвращает объект приказа
    *
    * @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;
       }
   }

Использование

       // Создаем экземпляр приказа напрямую
       // $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)

События

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

Перехватываемые события

Таблица событий, которые перехватывает этот плагин

Тип плагина	Код плагина	Код события	Доп. данные	Пояснение
Этот плагин не перехватывает никаких событий

Генерируемые события

Таблица событий, которые генерирует этот плагин

Тип плагина	Код плагина	Код события	Доп. данные	Пояснение
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.

Задания

Таблица заданий, которые выполняет этот плагин

Код задания	Дополнительный параметр	Пояснение
orders_on_orderdata	Необязателен	Находит все приказы, в которых хранятся данные в виде сериализованного объекта, после чего записывает эти данные в таблицу orderdata в виде скалярных значений.