Архитектура системы

Рекомендации

Небольшой набор правил для обеспечения целостности интерфейса как для конечных пользователей, так и для разработчиков.

Конфигурация

Не надо плодить лишних параметров в .conf файлах. Давайте, по возможности, избегать path для внутренних целей. Если кто-то захочет поменять расположение какого-либо из файлов панели, он всегда может заменить его символической ссылкой.

XML

Все функции панели работают с XML документом, который используется для формирования ответа пользователю (этот XML — единственный источник данных для формирования ответа). При работе с XML следует соблюдать следующие правила:

• корневой элемент должен называться doc
• при обработке XML избегайте использования XPath начинающихся с "//" — вы можете найти больше узлов, чем вам было нужно.

Общие рекомендации

• Избегать ситуаций, ставящих пользователя в тупик; при возникновении ошибки он всегда должен точно знать, что делать, чтобы устранить ошибку. При возникновении ситуации, требующей дополнительных настроек, он всегда должен знать, где, как и какие настройки он должен произвести. В идеале, автоматом перенаправлять его на заполнение соответствующих настроек и потом автоматом возвращать обратно. При возникновении вопросов о поведении системы он должен быстро найти ответ в документации (по возможности в хинте)
• По возможности пытаться решать проблемы автоматически, не напрягая при этом пользователя. Например, если обнаружено несоответствие каких-то данных, и его можно однозначно устранить (rotate уже существует), то устраняем. Если отсутствует нужная нам дира или файл и мы знаем с какими правами они должны быть и знаем каким должно быть дефолтное содержимое файла, то автоматом создаем их. И т.д.
• В случае появления потенциально неправильных действий (warning) пишем сообщение не только в лог, но и отображаем их пользователю, посредством баннеров.
• Всегда разрешать переход с вышестоящих уровней даже на отключенные учетные записи.
• Все разделы в dashboard'е должны быть выстроены в ровные колонки и выглядеть органично.

• Весь код должен быть многопоточным
  1. Временные данные запроса должны храниться в XML сессии
• Изолировать функции панели
  1. Отдельный функционал должен быть оформлен в отдельный файл, а не размазан по всему коду
  2. Использовать неименованные namespace для сокрытия структуры данных модуля
• Функции, используемые для проверки значения (check в метаданных), должны пропускать пустое значение параметра
  1. Пустое значение можно запретить, указав атрибут required
  2. Значение может оказаться пустым в результате внутренних преобразований. В этом случае оно должно быть признано верным
• Все групповые операции (удаление, включение, выключение и т.д.) вызываются для каждого отдельного элемента, если операцию выполнить невозможно, обязательно генерируем эксепшен. На более высоком уровне он будет перехвачен, и продолжится выполнение операции для других элементов. В конечном итоге, в случае ошибок пользователь увидит список элементов, над которыми не удалось произвести операцию.
• Игнорировать попытки удаления несуществующих объектов (не генерировать исключения)
• Избегать дублирования кода
  1. Избегать случаев, когда несколько функций панели выполняют одни и те же действия. Такие действия следует объединять в отдельные функции и вызывать их посредством InternalCall, чтобы обеспечить возможность централизованно менять поведение. Есть возможность защитить такие функции от непосредственного вызова извне.
• Все функции создающие какие либо сущности, должны возвращать их идентификатор (по которому можно обратится к нему) в теге elid. если создаваемых объектов несколько, возвращается несколько тегов elid

Рекомендации по работе с формами

Подробную информацию о формате xml документа описывающего форму вы можете найти в статье Описание форм

• Функции редактирования/создания новых элементов, по возможности, должны возвращать новый идентификатор элемента в узле id и новое имя, если оно отличается от идентификатора, в узле name.
• Параметр confirm (подтверждение пароля) в коде нигде не обрабатывается, следовательно, при вызовах по API его можно не указывать.
• Если поле на форме подразумевает неограниченное значение, то оно должно иметь placeholder с сообщением "не ограничено" и обрабатывать пустое значение, выставляя большое значение самостоятельно.
• Если проверка доступа к элементу реализована в Get, её можно не делать в Set (Get всегда вызывается перед обработкой Set)
• Все проверки вводимых параметров должны быть объявлены в XML (@check и @checkargs). Значения полей с типами slider, checkbox и select проверяются автоматически, для чего во время set запросов выполняется соответствующий get запрос.
  • slider — целое число, лежащее в промежутке [min,max]. Если не указано — считается min.
  • checkbox — допустимые значения: on, off. Если не указано — считается off.
  • select — одно из значений в соответствующем slist. Если не указано — берется первое значение из списка slist после его сортировки
• Значения, возвращаемые в get запросах, должны удовлетворять условиям, заданным в XML.
  • Если разработчик в get запросе не вернул значения для полей с типами slider, checkbox или select, значение будет подставлено автоматически (см. предыдущий пункт).
  • Значения параметров, переданные в get запрос, заменят собой значения одноименных полей формы. Таким образом можно показать пользователю форму с заранее заполнеными полями.

• Значения для полей ввода в новых записях (запрос с пустым elid), заполняемые через setvalues, должны формироваться автоматически при Get запросе, если они небыли переданы в качестве параметров. Например, если вы заполняете некое поле Email после изменения поля Name, код может выглядеть следующим образом:

  if (ses.Has("Name") && !ses.Has("Email"))
    ses.NewNode("Email", ses.Param("Name") + "@host.com");

• Поля для ввода пароля при интеграции панели с внешними системами (другие панели: ip/dnsmanager, сервера баз данных и т.п.) должны иметь тип password. При этом, во время отображения формы (get запрос) должно отдаваться текущее значение запомненное в панели.

Рекомендации по оформлению списков

Подробную информацию о формате xml документа описывающего список вы можете найти в статье Описание списков

• Заголовок списка должен совпадать с именем списка в главном меню (если не использовалось сокращение)
• Использование подписи с prop'а только по согласованию с руководителем разработки.
• В статистике все цифры должны подытоживаться. Все индикаторы должны отображать обе цифры аля "3/40", а не "4/". По колонке с prop'ами итог должен подводиться по тому, чего меньше (если речь идёт о нескольких возможных состояниях объекта, аля "вкл/выкл").
• Не должно быть колонок, в которой нет ни одного значения.
• Если есть prop'ы в списке, то комментарии, примечания и т.п. должны быть хинтами к соответствующему изображению. Если prop'ов нет, то в отдельной колонке в виде текста.
• Если среди prop/xprop есть лампочка, она должна стоять первой
• Не должно быть больше 8 групп кнопок у списка.

• При описании колонки типа <col type="msg" ... /> содержащей состояние, обязательно указывается цвет текста.
  • red — ошибка
  • yellow — предупреждение
  • green — все хорошо

Рекомендации по расположению кнопок на toolbar

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

Кнопки везде располагаются в следующем порядке (разумеется, если у вас чего-то нет, пропускаем):

• Создать
• Изменить. При наличии этой кнопки default="yes" должен быть на ней. (Пользователи, которым такое поведение не удобно, могут изменить его в настройках таблицы)
• Удалить
• --разделитель--
• Включить
• Выключить
• --разделитель--
• любые другие кнопки не описанные ниже, по необходимости допускается ставить разделители между смысловыми группами кнопок
• --разделитель--
• кнопки отчетов
• --разделитель--
• кнопки фильтров
• --разделитель--
• кнопки переходов (на другой уровень, в другие панели и т.д.)

Рекомендации по работе с базами данных

• Не использовать Зарезервированные_слова_СУБД в качестве имен таблиц и полей
• Ключевые слова языка SQL должны быть в верхнем регистре (ну проще так запросы читать)
• Разделение слов внутри имени символом '_'
• Таблицы
  • Имена функций выводящих содержимое списков должны соответствовать именам таблиц (если это возможно)
  • Имена таблиц и полей маленькими буквами
  • Имена таблиц писать в единственном числе (Например: server, а не servers). Иначе внешние ссылки будут некрасиво выглядеть (см. выше)
  • Таблица со списком пользователей — users (user — зарезервированное слово в некоторых СУБД)
  • many2many Таблицы именуем через двойку в единственном числе слева и справа от двойки
• Поля
  • Префиксы имен полей (обозначающие тип, размер и прочее) не использовать.
  • Тип boolean — StringField длины 3. Значения on/off (для совместимости с checkbox). Class_mgr_db::BoolField
  • Не использовать autoincrement поля (из-за проблем с репликацией данных MySQL). Используем Class_mgr_db::AutoIncrement
  • Поле, ссылающееся на другую таблицу, должно иметь такое же имя, как и таблица, на которую оно ссылается (если ссылок много, то имя таблицы следует использовать в качестве префикса)
  • Поле, содержащее уникальный идентификатор записи, должно иметь имя id Class_mgr_db::AutoIncrement
  • Поле, содержащее уникальное имя записи, должно иметь имя name
  • Поле, содержащее состояние объекта типа: включено/выключено, должно иметь имя active с возможными значениями on/off. Class_mgr_db::BoolField
  • Поле, содержащее уровень доступа, должно называться level быть целочисленным и принимать значения согласно Namespace_mgr_access
  • Поля, содержащие пароли, должны иметь тип Class_mgr_db::CryptedField. Это позволяет увеличить защиту данных (в частности от SQL инъекций)

SQLite

• Базы храним в каталоге etc
• Имя файла базы данных должно иметь расширение .db

Рекомендации по расположению разделов меню

Разделы меню во всех панелях располагаются в следующем порядке:

• Разделы продукта
• Состояние системы
• Интеграция
• Настройки
• Справка. При этом сам модуль "Справка" должен занимать самую верхнюю позицию раздела "Справка"

Рекомендации по содержанию текстовых сообщений

Будет пополняться прецедентно.

• Придерживаться единого стиля при написании сообщений
  1. Хинты писать с большой буквы и без точки в конце
  2. Для подписей к кнопкам и имен полей стараться использовать сообщения из секции common
• Id — писать так.
• Краткие подписи под кнопками. В идеале, подписи должны вмещаться в ширину кнопки. Максимум в 1.5 ширины кнопки. В особо трудных случаях допускается сокращать слова точкой. Развёрнутая информация о предназначении кнопки должна быть в подсказке(hint) к ней.
• IP и другие адреса следует писать так: "IP-адрес" "MAC-адрес". Аббревиатура большими буквами через дефис.
• Наименования модулей. Текст должен быть такой длины, чтобы вмещался в одну строчку в главном (боковом) меню. Максимальная длина названия также зависит от ширины тулбара, т.е. название и тулбар должны вмещаться на экране шириной 1280px
• Хинт должен раскрывать суть, а не констатировать то, что и так указано в подписи поля. Например, если на форме есть чекбокс "Включить Spamassassin для домена" — то в хинте должно быть примерно следующее содержание "Разрешать ли фильтрацию спама с помощью Spamassassin для данного домена". Человек, которому понятие не знакомо, может сразу вникнуть о чём идёт речь. Если сообщение очевидно и пояснения не требуются, то нужно написать, где и для чего используется данное поле или перефразировать его название другими словами.
• Если все что хочется написать в хинте не вмещается в 5 строк, то пишем техническую статью (даже если в ней всего будет пара абзацев) и добавляем на нее ссылку в "Полезные ссылки"

Рекомендации по обработке лимитов на различные ресурсы

• В качестве безлимита использовать пустое значение. Ноль — это ноль (запрет на использование ресурса), а не анлим. Для того, чтобы клиенту было понятно, что пусто — это безлимит, используем placeholder. Пример использования:

   <field name="domainlimit">
       <input type="text" name="domainlimit" check="int" unlimit="" checkargs="0,"/>
   </field>
   ...
   <msg name="placeholder_domainlimit">не ограничено</msg>

• Если цифра 0 в лимите бессмысленна, делайте проверку в валидатор, на минимальное значение 1, поможет пользователям избежать недопонимания.
• Уменьшение лимитов. Если у пользователя использовано ресурсов больше, чем вы хотите задать (уменьшить) лимит. Значит отказываем в этой операции, генерим ошибку.
• Оверселинг по умолчанию у нас разрешен. Т.е. реселлер может в сумме раздать своим пользователям больше лимитов, чем его собственный лимит. При этом при выделении какого либо ресурса пользователю нужно проверять оба лимита, лимит пользователя и лимит реселлера (сложив использование ресурса всеми его пользователями)
• Если лимит не задан явно — доступ к ресурсу должен быть закрыт

Новые возможности COREmanager, которые нужно использовать в панелях

• Notify bar (уведомления теперь отображаются в панели оповещений в левом верхнем углу).
• Навигация из списков (nestedlist). Возможность связывания списков. Можно задать в какой список и с каким фильтром следует перейти при нажатии на отдельные значения таблицы.
• Перегрузка веб-интерфейса при изменениях в меню.
• Кнопки New в дашборде
• Подсказки для кнопок при первой авторизации пользователя. Нужны для того, чтобы сориентировать пользователя как пользоваться панелью.

Загрузка системы

• создание обработчиков базовых функций
• загрузка дополнительной библиотеки <имя панели>.so / <имя панели>.dll Во время загрузки библиотека должна зарегистрировать в системе все необходимые ей компоненты . Кроме того, она может подгружать дополнительные библиотеки. Если загрузка какой-либо библиотеки завершается с ошибкой, все зарегистрированные ей компоненты автоматически удаляются из системы.

Обработка запросов

На каждом этапе обработки запроса вы можете добавлять собственные обработчики.

1. получение запроса, чтение и разбор параметров запроса Обрабатываются данные GET и POST, формируются внутреннее представление данных для удобного и быстрого доступа
2. аутентификация пользователя (попытка определить имя и уровень доступа пользователя отправившего запрос)
3. поиск функции по имени (имя функции берется из параметра func, если параметр отсутствует, предполагается, что он равен desktop )
4. авторизация пользователя
5. создание Xml для сессии (lang, func, binary, host)
6. вызов глобальных обработчиков событий (тех, что висят на действии "*" ) before="yes"
7. вызов обработчиков событий для выбранной функции before="yes"
8. вызов обработчика функции
9. вызов обработчиков событий для выбранной функции after="yes"
10. вызов глобальных обработчиков событий (тех, что висят на действии "*" ) after="yes"
11. завершение транзакций (запись файлов, удаление временных данных, вызов commit для баз данных)
12. формирование ответа в требуемом формате (формат задается через параметр запроса out)

Аутентификация пользователя

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

1. проверка COOKIE (<имя панели> + "5") COOKIE должен содержать следующие поля разделенные двоеточием: имя темы, аббревиатуру языка, код сессии .
   • загрузка сохраненных сессий из файла var/<имя панели>.ses (если он еще не был загружен) Этот файл записывается каждый раз, когда создается код сессии , на случай непредвиденного завершения работы панели.
   • проверка пользователя (вызов authenticate.<имя метода авторизации> )
2. авторизация пользователя исходя из данных полученных от клиента (вызов authenticate )
3. авторизация по IP В данном, случае имя пользователя нам уже известно (задано в конфиге), но все равно необходим вызов authenticate , чтобы определить дополнительные параметры.
4. авторизация пользователей пришедших с доверенного источника соединений Все аналогично предыдущему пункту, только имя пользователя — это имя локального администратора .

Если ни одна из предпринятых попыток не завершилась успешно, сессии присваивается нулевой уровень доступа.