# Процессы работы с документацией (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