ййй

_process/01. Process.md

@@ -0,0 +1,126 @@
+# Процессы работы с документацией (AS IS / TO BE)
+
+
+## Основные артефакты системной аналитики
+Системные аналитики работают с 3 артефактами:
+
+- бизнес-требованиями
+- системной аналитикой
+- технической документацией
+
+
+### Бизнес требования
+Описывает бизнес и пользовательские требования, пользователькие use case, макеты экранов.
+Сейчас не всегда оформляется как отдельный документ, часто этот шаг пропускается и требования фиксируются сразу в документе системной аналитики.
+
+
+### Системная аналитика
+Документ описыватет изменения в автоматизированной системе. Пишется системными аналитиками для разработчиков и тестировщиков. Так же этот документ проходит согласование с экспертами по архитектуре, безопасности, сопровождению. 
+
+Может описывать как целиком процесс (в случае реализации с нуля), так и инкремент, который вносит небольшие изменения в существующие процессы.
+
+В данном документе содкржится вся информация по сути вносимых изменений, но отсутствует контекст о текущей реализации системы.
+
+Состоит из разделов:
+- Цели - короткое описание какую проблему и для кого решаем.
+- Процесс AS IS и TO BE - фокус на изменения с точки зрения бизнес функций, без технической детализации.
+- Ограничения - ограничения и допущения в реализации.
+- Архитектура - описывает схему уровня контейнеров, основной фокус на интеграции между контейнерами и интеграционные сценарии.
+- Функциональные требования - описывают изменения в системе.
+- Нефункциональные требования - требования к аудиту, мониторингу, фичетоглам, пользовтелькой аналитике.
+
+
+### Техническая документация
+Техническая документация описывает реализацию системы. Эта информация используется командой разработки при проектировании и реализации новых фичей, понимании как работает система. Артефакт живет чуть впереди кода
+Представялет из себя иерархическую модель документов, сейчас реализованную в конфлюенсе.
+
+Есть несколько типов страниц, каждая из которы описывает определенный тип функциональности
+
+- UI страницы
+- API методы
+- БД
+- Логические блоки
+
+#### UI страницы
+Описывают экран на UI. 
+**Декомпозиция**
+Как правило на страницу с описанием выносится целый макет/страница фронтального приложения, с одной основной интеграцией и опционально вспомогательными интеграциями. 
+Например - форма создания сущности. Есть вспомогательгные методы для полученяи правочников, использующихся при заполнении полей на форме, и вызов оснвного метода создания сущности.
+
+Таким образом приложение декомпозируется на отдельные экраны, коотры свызываются между собой последовательно, но сами по себе являются независимыми
+
+**Состав описания**
+Все разделы обязательны.
+Страница с описанием содержит:
+ - Краткое описание
+ - Технический use case
+ - Описание макета с декомпозицией на компоненты + их поведение 
+ - Функциональные требования - описание интеграций и логики, специфичной для этой формы UI
+ - Нефункциональные требования - фичетоглы и события пользовательской аналитики
+
+
+#### API методы
+**Декомпозиция**
+На каждый метод API заводится отдельная страница.
+**Состав описания**
+Все разделы обязательны.
+Страница с описанием содержит:
+ - Краткое описание
+ - Технический use case
+ - Функциональные требования - описание интеграций и логики, специфичной для этой формы UI
+ - Нефункциональные требования - фичетоглы и события пользовательской аналитики
+ - Контракт метода - описание запроса и ответа. Для ответа так же приводится описание как заполнять поля.
+
+#### БД
+**Декомпозиция**
+Сейсас это только странциа с описанием таблица. На каждую таблицу заводится отдельная страница.
+**Состав описания**
+Все разделы обязательны.
+Страница с описанием содержит:
+ - Краткое описание
+ - Таблица с офисанием физической модели данных
+
+#### Логические блоки
+**Декомпозиция**
+На отдельную страницу может быть вынесен общий переиспользуемый блок логики. Это позволяет не дублировать его на страницах документации. Как правило соответствует реализации общего компонента в коде.
+**Состав описания**
+Часть разделов в описании может отсутствовать.
+ - Краткое описание
+ - Технический use case
+ - Функциональные требования - описание интеграций и логики, специфичной для этой формы UI
+ - Нефункциональные требования - фичетоглы и события пользовательской аналитики
+
+#### Прочие особенности процесса
+##### Описание технических use cases
+Сценарий описывает основные шаги процесса в разрезе участников, все технические детали, если их нельзя описать одним предложением, выносятся в разделы функциональных требований, нефункциональных требований, или даются ссылки на другие страницы (как правило это страницы с логическими блоками).
+
+В технических use cases приводятся ссылки на страницы с описнаием вызываемых методов API. Особенно это актуально для страниц фронта, т.к. он использует наши методы API, которые есть в документации. Для интеграций с другими АС как правило приводистя ссылка на описание конфлюенса.
+
+
+
+## AS IS
+Сейчас все артефакты ведутся в конфлюенс. Одна страница содержит описанием одного аретфакта (бизнес требования, системная аналитика, страница документации), страницы организованы иерархически, используюстя ссылки для обозначения связей.
+
+Проблемы:
+- документация со временем теряет актуальность
+- отсутствие автоматизации
+- ручное ведение
+---
+
+## TO BE
+
+Целевое состояние:
+- аналитик продолжает писать артефакты бизнес-требований и системной аналитики
+- агент генерирует и обновляет документацию по странице системной аналитики
+- документация становится инженерным артефактом, который ведется в GIT
+
+### Форматы
+- Markdown
+- OpenAPI
+- Mermaid / PlantUML
+
+### Роль агента
+- использование документации как базы знаний - как для ответов на вопросы, так и для проектирования изменений в системе.
+- внесение изменений в документацию по артефактам системной аналитики
+- генерация из документации спецификаций OPENAPI и JSON-schema
+