# Конфигуратор

Системное приложение «Конфигуратор» предназначено для автоматизации и
ускорению выполнения рутинных задач по разработке проекта:

- Создание нового проекта
- Создание нового модуля
- Работа с классами 
  - Создание 
  - Редактирование
- Работа с выборками
  - Создание
  - Редактирование
- Управление разметкой выборок
  - Редактор карточки
  - Редактор фреймов.
- Управление подсистемой распространения изменений.
- Управление технической документацией сущностей и методов проекта.

Конфигуратор предназначен для работы на локальном компьютере
разработчика. 

Конфигуратор взаимодействует с IDE Intellij Idea через специальный плагин. 

Конфигуратор поддерживает систему контроля версий SVN.

## Запуск

Для запуска конфигуратора выполните следующие действия:

1.  Запустите сервер Global \
   Выполните скрипт `C:\Global3se\start.bat` или запустите
   отладку в IDE Intellij Idea
2. Откройте в браузере адрес `http://localhost:8080/`
3. Введите логин, пароль, базу данных
4. Разверните настройки подключения
5. Установите флажок "Конфигуратор"
6. Войдите в систему

## Первичная настройка

При первом запуске конфигуратор предлагает выбрать режим работы по
умолчанию: локально или через систему контроля версий. 
При работе через систему контроля версий необходимо далее указать:
- Логин svn
- Пароль svn
- Url svn 

Настройки сохраняются в поддиректорий конфигурации сервера Global:
`C:\Global3se\application\config\cfg`
- `vcs.dat` – Настройка SVN
- `project.dat` – Настройка проектов

При удалении этих файлов мастер настройки автоматически запустится 
заново.

## Создание нового проекта

Запустить мастер создания проектов: `Проекты > Новый проект` 

### Общие настройки

- *Системное имя проекта* \
  Внутреннее имя проекта, обычно совпадает с
  наименованием директории проекта (пример: `intern199`)
- *Локальный путь до проекта* \
  Корневая директория, в которой будет создан
  проект пример: `C:\SVN\ASSource\database\pgIntern\...`

### Настройки для локального режима

В локальном режиме работы требуется указать 
- *параметры соединения с БД*
- *шаблон проекта *
  - или путь к архиву с шаблоном проекта  
  - или каталог с существующим проектом
  -  
### Настройки для работы через svn
Для режима работы через систему контроля версий предусмотрена
расширенная конфигурация при которой надо задать параметры:  
- *Путь в репозитории*
  Каталог в SVN, в который будет сохранен проект  
  пример: `ASSource/database/pgIntern/...`

### Настройки Sbt-plugin 
Sbt-plugin является расширением к системе сборки  sbt (scala build tool). 
При настройке рекомендуется не использовать пункт "trunk-версия", 
а оставить предложенную версию, которая является максимальной 
на момент создания проекта.

### Настройки Базы данных
- *Url* \
  Указывается тип драйвера и параметры подключения  
  пример:` jdbc:postgresql://v39:5432/intern199`
- *Пользователь* \
  Имя пользователя для подключения к БД
- *Пароль*
  Пароль для подключения к БД
  ```{note}
  Параметры подключения к БД можно узнать у куратора проекта
  или системного администратора
  ``` 
### Подключаемые модули
В списке подключаемых модулей, будут подобраны основные модули, для
создания проекта. 
Их можно удалить или добавить новые. 
После выполнить операцию "Подобрать зависимости».

### Завершение создание проекта. 
1. По завершению конфигурации выполните операцию "Создать проект" \
   При этом:
   - В случае работы с svn, в репозитории системы контроля версий будет создана
      структура каталогов проекта (каталог хранения проекта приложения, 
      каталог хранения проектных модулей)
   - Отобразится диалог конфигурации сервера для запуска проекта 
2. Завершите конфигурацию сервера
3. Импортируйте проект в Intellij Idea

## Модули

Интерфейс для работы с модулями проекта расположен на панели
инструментов главного меню.

Позволяет выполнять настройку модулей, подключать существующие модули,
создавать новые.

## Создание модуля

Операция позволяет создать новый модуль и подключить его к проекту.

1.  На панели инструментов выполните операцию 
    `Подключить модули > Создать новый модуль`
2.  В открывшемся мастере введите:
    1.  *Системное имя* \
        Имя модуля в нижнем регистре
    2.  *Наименование модуля*
    3.  *Проектный модуль* (только для режима SVN) \
        Если установить этот
        признак, то модуль будет создан внутри каталога проекта в
        подкаталоге module, и не будет доступен к подключению в других
        проекта. Если признак не установить, то модуль будет создан в
        основном каталоге модулей (`ASSource/module`) и будет доступен к
        подключению в других проектах.
3. Подключите модули, от которых будет зависеть создаваемый модуль 

## Обозреватель проекта

Отображает дерево сущностей проекта с возможностью их редактирования и
просмотра документации. Сущности в обозревателе проекта:
- Классы
- Выборки
- Прикладная бизнес-логика (Api)
- Пакеты прикладной бизнес-логики (Pkg)

Для вызова используется операция панели инструментов главного меню
«Обозреватель проекта»

### Дерево сущностей

В дереве отображаются сущности, сгруппированные по каталогам. Для
классов отображаются в качестве потомков их базовая выборка и Api

Дерево отображается в двух режимах, которые переключаются флагами на
панели фильтров:

- *Логическая структура* \ 
  Каталоги для сущностей определяются так: если в
  метаданных класса, выборки или пакета указан тег `logicFolder`, то
  каталогом этой сущности будет указанное значение, иначе физический
  каталог. Пример значения: `logicFolder = "audit.test"`
- *Физическая структура* \
  Каталоги для сущностей определяются их
  расположением внутри проекта. Например для scala-пакета
  `ru.bitec.app.btk.audit.test` каталогом будет `audit.test`

Основная закладка для всех сущностей — это "Описание", которое
формируется на основе документации, которая хранится в исходном коде.
Подробнее см. главу "Документирование"

### Создание новых сущностей

Реализовано создание основных сущностей:

- *Класс* \
  Создает odm-файл
- *Выборка* \
  Создает avi и avm файлы
- *Пакет* \
  Создает Pkg и pkg.xml файлы
- *Описание каталога* 
  Создает package-info.java в указанном каталоге.

### Тегирование

Позволяет для сущностей повесить разнообразные теги. Которые будут
отображены в дереве обозревателя.

Настройка доступных тегов осуществляется в гл. меню 
`Настройка > Теги обозревателя проекта`

Для установки тегов сущности используется операция 
`Дополнительно > Редактировать теги`

### Документирование

Для сущностей на закладке "Описание" собирается их документация,
хранящаяся в исходном коде.

Документация пишется в mark down.

Формирование описания по типам сущностей:

#### Класс
Документация для класса хранится в odm файле. 
В теге `documentation`, который доступен для:
- класса
- Атрибута 

#### Выборка 
Документация для выборки хранится в Avm файле. 
В тег `documentation`, который доступен для:
- Выборки
- Отображения 
- Атрибута 

#### Api 
Документация хранится в scala doc в файле Api-класса

#### Pkg 
Документация хранится в: 
- теге `documentation` файла pkg.xml
- scala doc Pkg-класса
- 
#### Каталог 
Документация хранится в package-info.java, расположенном в каталоге на
диске в scala-ветке. Документация в нем так же пишется в mark down.

#### Модуль 
Документация хранится в `package-info.java`, расположенном корневом каталоге
scala-ветки

### Интеграция с IntelliJ IDEA

Интеграция осуществляется через плагин для IDEA

Позволяет открывать файлы в IDEA, которые соответствуют записям в дереве
обозревателя. Для некоторых сущностей есть возможность открывать
дополнительные файлы. Если не открыт текущий проект в IDEA, то будет
выдано сообщение, что проект не найден.

При открытии проекта в IDEA запускается json-rpc сервер, который
получает порт для прослушивания, и сохраняет в структуре проекта файл
`.idea/ideasocket/<номер порта>.lock`, при этом блокируя файл.
Конфигуратор при отправлении команды на открытие файла сканирует эту
директорию на наличие заблокированных файлов, и получает порт, в который
требуется отправлять данные.

Для открытия файла в IDE используется операция "Открыть в IDE"

Открываемые файлы по типам сущностей:
- *Класс* \
  Открывает odm-файл
- *Выборка* \
  Открывает Avi-файл. \
  Дополнительная подоперация позволяет открыть avm
- *Api* \
  Открывает Api-файл
- *Pkg* \
  Открывает Pkg.scala \
  Дополнительная подоперация позволяет открыть pkg.xml


## Разработка конфигуратора

Код конфигуратора содержится в отдельном модуле.
Для разработки этого модуля необходимо его настроить в режим разработки. 

Конфигурация модуля происходит в файле `global3.config.xml` через тэги:
- `database` \
  Конфигурация базы данных с именем "{DB_ALIAS}.CFG", где  DB_ALIAS
  имя базы к которой идет подключение. 
- `sbt`
  Настройка модуля содержащего исходный код конфигуратора.

### Конфигурация базы данных 

Если конфигурация  отсутствует она создаются автоматически по алгоритму:
1. Скопировать конфигурацию "{DB_ALIAS}" в "{DB_ALIAS}.CFG"
2. Заменить имя sbt на значения `cfg`
   ```XML
   <metaManager sbtName="cfg"/>
   ```

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

Если конфигурация sbt отсутствует, формируется конфигурация по умолчанию.

Шаблон конфигурации:
```xml
<sbt name="cfg"
     jarFolder="%GLOBAL3_HOME%\server\configurator\applib\\"
     binaryFolder="%GLOBAL3_HOME%\server\configurator\appbin\\"
     sourceMode="Jar"
     lazyLoad="true">
</sbt>
```
где:
- `GLOBAL3_HOME` \
  Переменная окружения указывающая на расположения дистрибутива.\
  Данная переменная задается автоматически при старте сервера 

#### Конфигурация sbt для разработчика
Для разработки необходимо переопределить конфигурацию sbt по шаблону: 
```xml
<sbt name="cfg"
     source="{PATH_TO_CFG}\configurator\application\"
     sourceMode="Dev"
     lazyLoad="true">
</sbt>
```

#### Алгоритм формирования для режима системной разработки
Для перехода в режим разработки:
- Задайте переменную окружения  `G3_ISDEV` = `1`
- Задайте переменную окружения `G3_SHARE` = "путь к jar архивам конфигуратора"

Шаблон генерации конфигурации в режиме системной разработки:
```xml
<sbt name="cfg"
    jarFolder="%G3_SHARE%\cfgapplib"
    binaryFolder="%G3_SHARE%\cfgappbin"
    sourceMode="Jar"
    lazyLoad="true">
</sbt>
```