Версия 10:41, 17 октября 2022

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

Содержание

1 Общие требования
- 1.1 Структура файлов
2 Взаимодействие с postgresql
3 Зависимость от другого ПО
4 Диагностика работы службы
5 WEB API
6 Документация
7 Публикация и распространение

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

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

каждая служба живет в своем каталоге
имена каталогов в ВЕРХНЕМ регистре
все имена файлов в нижнем регистре
имя исполняемого файла службы должно заканчиваться на _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.ini
 │  ├──readme.md
 │  └──LOG - Папка с логами
 └─IBIS_SPARM
    ├──ibis_sparm_srv.exe
    ├──ibis_sparm_ctl.exe
    ├──ibis.ini
    ├──ibis_sparm.ini
    ├──ibis_sparm.ini.example
    ├──readme.md
    └──LOG

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

_srv.exe сервис
_ctl.exe управляющая программ
_app.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

все необходимые для работы файлы
ini-файлы с настройками по умолчанию (как правило это два файла)
файл 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

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

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

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

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

Службы MIS3. Разработка — различия между версиями