Добавил описание

Author: 240596448

README.md

@@ -1,3 +1,129 @@
 # Версионирование правил КД2
 
-Разбор для версионирования в гит правил конвертации, правил регистрации в удобочитаемом виде.
+Разбор правил конвертации, правил регистрации в читаемом и удобном для анализа виде для хранения и версионирования в GIT.
+
+
+## Как пользоваться
+
+1. Ручной разбор правил (команда `rulexport export`)
+2. Автоматический разбор в гит-репозитории (команда `rulexport install`)
+
+### Ручной разбор правил:
+Выполняет разбор произвольного файла командой  
+```
+rulexport export  
+	--schema=ИмяФайлаСхемы.json  
+	--path=ПапкаРазбора  
+	ИМЯ_ФАЙЛА_ПРАВИЛ.xml
+```
+
+### Автоматический разбор правил:
+Выполняет разбор с помощью хука `pre-commit` всех файлов КД2 добавленных индекс гит-репозитория.  
+Хук устанавливается в репозиторий командой:
+```
+rulexport install  
+	--schema=ИмяФайлаСхемы.json  
+	--src=ПапкаРазбора  
+	ПУТЬ_К_РЕПОЗИТОРИЮ
+```
+
+*Особенности работы хука:*  
+- Выполняет разбор только тех файлов, которые являются файлами КД2, которые добавлены в индекс.  
+- Если файл добавлен в индекс и имеет изменения вне индекса, то будет выдано исключение.  
+- Вне индекса файлы не обрабатываются.  
+- Если файл правил удаляется или переименовывается, то соотвествующая ему папка с разобранными правилами удаляется.
+
+## Что такое СХЕМА и как это работает?
+
+Алгоритм выполняет обработку правил согласно схемы.  
+По задумке модификацию разбора правил, добавления обработки дополнительных узлов можно производить только изменяя файл схемы `schema.json` не модифицируя код алгоритма.  
+
+Алгоритм рекурсивно обходит структуру схемы и выполняет действия каждого "узла".
+
+*Узел схемы влючает в себя следующие поля:*
+- `Область` - произвольное описание действия (не используется в алгоритмах)
+- `ИмяПапки` - создает папку, в которую помещает результат обработки узла
+- `Совпадения` - поиск совпадений Regex (коллекция) в тексте итерации. 
+- `ИменованныеГруппы` - имена именованных групп `Совпадения`, которые будут использованы для автозамены в полях `ЗаменитьНа` и `ИмяФайла` текста "<ИмяГруппы>" за значение из найденного совпадения
+- `ЗаменитьНа` - выражение для замены совпадения (использует автоподставновку именованных групп) 
+- `ИмяФайла` - имя файла, в который будет сохранен каждый элемент коллекции совпадений (использует автоподставновку именованных групп)
+- `ИмяПапкиПодчиненных` - создает папку для каждого элемента `Совпадения` (использует автоподставновку именованных групп текущего узла). Дополняет путь `ИмяПапки`, может использоваться как вместо, так и вместе с `ИмяПапки`. Пример, когда может понадобиться данное поле - создание папок для каждого ПКО с вложенными файлами свойств и т.п.
+- `ПодчиненныеЭлементы` - массив подчиненных узлов
+ 
+ В текущей реализации схема копируется в репозиторий. Для каждого репозитория можно использовать свою схему.
+## Почему не другие готовые решения?
+
+Целью решения было нахождение баланса между "версионируем файл целиком" и "версионируем каждый узел как отдельный файл".  
+Оба варианта имеют недостатки.  
+В первом случае проблемой является изменение порядка узлов.  
+Во втором - слишком большое количество мелких файлов, глубина иерархии, длинные пути
+
+Предлагаемый способ хранения (согласно дефолтной схеме) в виде дерева:
+```
+│   НашиПравилаКонвертации.xml
+├───Алгоритмы
+│   │   Алгоритмы.xml
+│   └───Алгоритмы
+│           Алгоритм-ВыгрузитьОстаткиМатериалов.xml
+│           Алгоритм-ВыгрузитьОстаткиНоменклатурыПоСчету.xml
+│           Алгоритм-ВыгрузитьОстаткиТМЦвЭксплуатации.xml
+│           Алгоритм-ВыгрузитьОстаткиТоваров.xml
+├───Запросы
+│   │   Запросы.xml
+│   └───Запросы
+│           Запрос-ОстаткиМатериалов.xml
+│           Запрос-ОстаткиОС.xml
+├───Общее
+│       ПередВыгрузкойДанных.xml
+│       ПередЗагрузкойДанных.xml
+│       ПередКонвертациейОбъекта.xml
+│       ПослеЗагрузкиДанных.xml
+│       ПослеЗагрузкиПараметров.xml
+│       ПослеЗагрузкиПравилОбмена.xml
+├───Параметры
+│       Параметры.xml
+├───ПравилаВыгрузкиДанных
+│       ПВД-Банки.xml
+│       ПВД-БанковскиеСчета.xml
+│       ПВД-Валюты.xml
+└───ПравилаКонвертацииОбъектов
+    │   ПравилаКонвертацииОбъектов.xml
+    └───Правила
+            ПКО-АвансовыйОтчет.xml
+            ПКО-Банки.xml
+            ПКО-Валюты.xml
+            ПКО-ВводОстатков.xml
+```
+Основной принцип:  
+в исходном тексте удаляются (заменяются) `Совпадения` и сохраняются в файл `ИмяФайла`.  
+Получаем на верхних уровнях файлы-оглавления, в которых версионируем иерархию в группах, порядок, состав подчиненных элементов.
+
+Пример файла "Алгоритмы.xml"
+```
+<Алгоритмы>
+		<Группа Имя="Выгрузка">
+			<Алгоритм Имя="ВыгрузитьОстаткиМатериалов"></Алгоритм>
+			<Алгоритм Имя="ВыгрузитьОстаткиНоменклатурыПоСчету"></Алгоритм>
+			<Алгоритм Имя="ВыгрузитьОстаткиТМЦвЭксплуатации"></Алгоритм>
+			<Алгоритм Имя="ВыгрузитьОстаткиТоваров"></Алгоритм>
+		</Группа>
+		<Группа Имя="Загрузка">
+			<Группа Имя=".....">
+				<Алгоритм Имя="....."></Алгоритм>
+				<Алгоритм Имя="....."></Алгоритм>
+				<Алгоритм Имя="....."></Алгоритм>
+			</Группа>
+			<Алгоритм Имя="....."></Алгоритм>
+			<Алгоритм Имя="....."></Алгоритм>
+			<Алгоритм Имя="....."></Алгоритм>
+		</Группа>
+	</Алгоритмы>
+```
+
+*А где отдельные свойства ПКО, а отдельные алгоритмы обработчиков свойств?*
+Это несложно добавить в схему самостоятельно.
+Проба разбора свойств ПКО в отдельные файлы (в подпапку ПКО-ХХХ) превратила разобранные файлы в плохо анализируемый винегрет. Поэтому в дефолтной схеме детализация до ПКО.
+
+## Где сборка правил?
+
+С учетом того, что исходный файл правил тоже хранится в репозитории (разбор выполняется только для файлов в индексе), то обратная сборка в текущий момент не целесообразна. Но ее можно сделать гарантируя соблюдение струтуры и порядка исходного файла правил. По идее для этого можно будет использовать схему, которая хранится в репозитории. Но пока сборка не планируется.