Текущая версия на 11:02, 17 октября 2022

Внимание все службы должны жить в репозитории ibis_server Этот файл отстает в соответствующего документа по КИС. см Службы_KIS._Разработка

Общие требования

Структура файлов

• каждая служба живет в своем каталоге
• имена каталогов в ВЕРХНЕМ регистре
• все имена файлов в нижнем регистре
• имя исполняемого файла службы должно заканчиваться на _srv.
• имя службы должно быть в нижнем регистре и начинаться с ibis без "_srv" в конце. Например "ibis_sertificate"
• имя исполняемого файла по управлению службой должно заканчиваться на _ctl
• настройки службы должны храниться в ini файле рядом с исполнимыми файлами.
• настройки подключения берутся из файла ibis.ini

Пример расположения служб

IBIS_SRV
 ├─IBIS_SERTIFIATE
 │  ├──ibis_sertificate_srv.exe
 │  ├──ibis_sertificate_ctl.exe
 │  ├──ibis_sertificate.ini
 │  ├──ibis_sertificate.ini.example
 │  ├──ibis_sertificate_install.bat
 │  ├──ibis_sertificate_uninstall.bat
 │  ├──ibis_sertificate_update.bat
 │  ├──ibis.ini
 │  ├──readme.md
 │  └──LOG - Папка с логами
 └─IBIS_SPARM
    ├──ibis_sparm_srv.exe
    ├──ibis_sparm_ctl.exe
    ├──ibis.ini
    ├──ibis_sparm.ini
    ├──ibis_sparm.ini.example
    ├──ibis_sparm_install.bat
    ├──ibis_sparm_unistall.bat
    ├──ibis_sparm_update.bat
    ├──readme.md
    └──LOG

Именования файлов

• _srv.exe сервис
• _ctl.exe управляющая программ
• _app.exe в виде отдельного приложения (на этапе разработки)
• _install.bat скрипт для уснановки службы, как правило, содержит вызов _srv.exe с праметром /install
• _uninstall.bat скрипт для удаления службы, как правило, содержит вызов _srv.exe с праметром /uninstall
• _update.bat содержит параметры, неопходимые updater_console.exe, для обновления сервисов.

Все исполняемые файлы (*.exe) должны содержать актуальную информацию о версии (номер версии должен совпадать с номером ревизии SVN на котором этот exe собран)

Взаимодействие с postgresql

Аутентификация в БД

• каждая служба должна работать под своим уникальным пользователем (для того чтобы можно было мониторить работу службы со стороны БД)
• имя пользователя должно быть
  • большими буквами
  • совпадать с именем службы
  • начинаться на SRV (тут разница с KIS)

логин пароль храним в открытом виде в файле ini (<имя службы>.ini)

• [Postgresql]
  • user
  • password
  • password_crypt

Требования к работоспособности при потере соединения

• Служба должна корректно отрабатывать ошибки, связанные с потерей соединения с БД и пытаться восстановить соединение самостоятельность.

application_name в сессии postgresql

Любая сессия должна себя идентифицировать установив application_name в формате <имя файла> (версия). Например:

 ibis_mqtt.exe (1.0.0.1)

Ниже пример кода:

procedure TdmMain.conAfterConnect(Sender: TObject);
var
  S : String;
begin
  S := ExtractFileName(FSrvInfo.AppExe);
  S :=  S+  ' (' + FSrvInfo.FileVer + ')';
  con.ExecSQL('SET  application_name =  + S + '); // устанваливаем переменную application_name (pg_stat_activity)
end;

Размер work_mem

для сессии которая слушает pg_listen (и только для нее) нужно проставить

set session work_mem='64kB'

Зависимость от другого ПО

• служба не должна зависеть от стороннего ПО, такого как
  • вебсерверы (IIS, Apache)
  • Net framework
  • клиент БД

Диагностика работы службы

• служба должна писать информацию о событиях, в файл лога. Рекомендуется использовать QuickLogger https://github.com/exilon/QuickLogger или SynLog из библиотеки Synopse mORMot framework
• файлы логов должны быть легко просматриваемы сторонними программами.
• логов НЕ должно быть много. Т.е. НЕ должны забивать свободное место (должен происходить Rotate) и не должны сильно влиять на производительность дисковой подсистемы

WEB API

• checkstatus - возвращает 1 в теле ответа, если сервис работает правильно
• info - возвращает json, в котором есть настройки, текущий статус сервера (есть подключение к БД и т.п.)
• stat - возвращает json со статистикой работы
• showlog - показывает лог работы программы
• admin - возвращает html страницу с настройками

Документация

Файл readme.md

В каталоге обязательно должен быть файл readme.md в формате markdown (для редактирования можно использовать Typora). Кодировка UTF-8. В нем должны быть следующие разделы:

• Назначение
• Описание работы
• Состав (список файлов с описанием)
• Установка
• Настройка (что можно настроить в ini файлах, что можно настроить в adj)
• Обновление
• Мониторинг (проверка работоспособности, где и какие логи ведутся, как посмотреть какие ошибки возникали)

По правильному, содержимое файла markodown нужно продублировать на wiki (в typora есть экспорт)

Файлы-примеры конфигурационных файлов (ini.example)

Для каждого из возможных ini файлов должен лежать файл пример с расширением ini.example со всеми значениями по умолчанию и комментариями. Например для kis_mqtt.ini должен быть файл kis_mqtt.ini.example

Документация разработчика (readme_dev.md)

В исходных кодах в каталоге DOC должен быть файл readme_dev.md в формате markdown Что можно писать

• структуры данных
• особенности сборки
• структура приложения (сервиса)

Публикация и распространение

на WEBDAV в папку LASTSRVFILES/<имя-службы_большими буквами> необходимо выложить два файла:

• <имяслужбымаленькими>.7z
• ver.ini

Состав файла 7z

1. все необходимые для работы файлы
2. ini-файлы с настройками по умолчанию (как правило это два файла)
3. файл readme.md (см пункт "Документация")

Содержимое файла ver.ini

[Ver]

srv_ver=1.0.0.13

Автоматизация публикации

В папке CI (Continuous Integration) необходимо создать два файла:

• 01_pack.bat - создает архив 7z
• 02_webdav.bat публикует архив в папке на WEBDAV с помощью утилиты curl

Примеры скриптов можно брать из kisservices\trunk\kispg_rest\CI

Алгоритм публикации

1. Изменяем в проекте номер версии, успешно компилим
2. Правим файл ver.ini в папке bin
3. Последовательно запускаем скрипты 01_pack.bat, 02_webdav.bat (смотрим в логи что все успешно)

Список сервисов

• KIS MQTT_connector брать пример отсюда
• Учет смертности и рождаемости ХМАО
• Across
• ХОСТ (портал пациента)
• Интеграция с ЛИНС Махаон
• Интеграция с СПАРМ
• Интеграция с ИСАР
• ЛИС результаты анализаторов - больше не используется