Концепт нового описания моей системы (v1)

[iurii-toropchin]

1. Предисловие

Я работаю системным аналитиком в ИТ-компании СберЗдоровье. В этой статье буду рассматривать вариант реорганизации документации для функционального и конструктивного описания системы. Остальные описания вне рамок текущей статьи.

Приложение: https://play.google.com/store/apps/details?id=com.docdoc.docdoc&hl=ru

2. Постановка задачи

Нам, как разработчикам, необходимо получать более полную информацию о системе за наименьшее количество времени. Для этого будем обращаться к описанию системы, которое будет выдавать информацию. Основные сценарии использования такого описания:

• Легкое получение информации о системе (в том числе о прошлых и будущих версиях). Конкретнее о типах информации:
  • Сценарии использования системы (по доменам ролей из предметной области)
  • Описание реализации сценариев использования
  • Проекты/design
• Легкий поиск информации о системе (в том числе о прошлых и будущих версиях).
• Легкое изменение информации о системе (в том числе о прошлых и будущих версиях)

3. Сценарий использования системы

Систему используют две роли “Врач” и “Пациент”, с ними будет взаимодействовать система. Сценарии будут описаны через Use Case, например так:

Название: Передача показаний давления. Домен пациента.

1. Система принимает показания давления от пациента
2. Система запоминает показания давления
3. Система показывает список последних показаний давления

Здесь не описывается внутреннее устройство системы. Система активна, а роли пассивны - можно наблюдать, что не пациент передает показатели давления в систему, а система принимает показатели давления.

Версионирование:

• Реализованные сценарии имеют “Дату релиза”
• Сценарии, которые вышли из эксплуатации имеют “Дата вывода из эксплуатации”
• Сценарии, которые еще не реализованы системой не имеют ни “Дату релиза”, ни “Дату вывода из эксплуатации”
• Сценарий можно связать с прошлой версией описания этого сценария (прошлая версия будет выведена из эксплуатации) и дополнительно указать комментариями изменения. При разработке прошлая версия будет отражать AS IS, а текущая версия будет отражать TO BE. Комментариями будут указаны изменения, работы, которые нужно будет сделать.

Внутри сценария указываются и “Желаемые характеристики системы”, которые можно измерить количественно, например так:

Желаемые характеристики системы (дополнение к сценариям использования):

1. Система принимает 500 показаний давления от Пациентов за 1 минуту
2. Система запоминает до 1000000 показаний давления за полгода

4. Описание реализации сценария

Каждый шаг из сценария детализируется до работы системы. Для нашего примера:

1. Система принимает показания давления от пациента
   1. Mobile-UI показывает экран ввода показаний давления пациенту (тут ссылка на описание экрана)
   2. Mobile-UI принимает показание верхнего давления (w) и показание нижнего давления (e) в соответствующие поля
   3. У Mobile-UI пациентом нажимается кнопка “Сохранить”
2. Система запоминает показания давления
   1. Mobile-UI отправляет POST /user/{userId}/observation с телом {“systolic”: (w), “diastolic”: (e)} на Backend-API (тут ссылка на описание API)
   2. Backend-API возвращает ответ в Mobile-UI
3. Система показывает список всех измерений
   1. Mobile-UI отравляет GET /user/{userId}/observation на Backend-API (тут ссылка на описание API)
   2. Backend-API возвращает ответ в Mobile-UI
   3. Mobile-UI показывает экран показаний давления пациенту (тут ссылка на описание экрана)

Описание реализации сценария включается в сам сценарий использования, при проектировании реализации используется:

• C2 схема из C4 Model для описания межсервисного взаимодействия

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

5. Проект

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

В предыдущем разделе уже были даны ссылки на некоторые проекты:

• UI-Frontend, описывается в figma на основании дизайн-системы
• Backend-API, описывается по спецификации OpenAPI, AsyncAPI
• Схема баз данных, описывается через dbdiagram.io
• …другие проекты…

Проекты имеют аналогичную логику по версионированию.

[anton-p]

Вы подробно рассказали о системе как о “прозрачном ящике” но системное мышление говорит что описание системы нужно начинать как “черный ящик” было бы интересно почитать описание вашего проекта с использованием типов мета-мета-модели из курсов. (Что есть целевая система, ваша система, создатели и т.д.)

[iurii-toropchin]

Сценарии использования это и есть описание системы как черного ящика. По крайней мере мной было так задумано.

[nedbailov375426]

В системном мышлении различают “концепцию использования” (которая уточняется до “сценариев использования”) и “концепцию системы”.
Это варианты методов описания системы. Но эти варианты используются(применяются), когда нет более точного описания. А точное описание этого когда, как минимум 5 рекомендуемых описаний.

@iurii-toropchin

Здесь не описывается внутреннее устройство системы. Система активна, а роли пассивны - можно наблюдать, что не пациент передает показатели давления в систему, а система принимает показатели давления.

Если системы принимает, то кто отправляет? И если мы говорим про концепцию использования, то рассматривать будет лучше от лица пользователя или как целевая система будет использована в над-системе, что получается за счет создания(улучшения) целевой системы?

[ailev]

Если use cases, то там всё правильно – что делает система важно, а не что делает пользователь. Что делает пользователь – это про другое (например, customer eXperience). В концепции использования, конечно, всё важно. Но автор-то пишет про use cases.

Смотрите свежий курс “Системная инженерия”, там про это четвёртый раздел, про use cases целый подраздел – уж больно тема горячая.

[natali-maximum]

@iurii-toropchin

Версионирование:

• Реализованные сценарии имеют “Дату релиза”
• Сценарии, которые вышли из эксплуатации имеют “Дата вывода из эксплуатации”
• Сценарии, которые еще не реализованы системой не имеют ни “Дату релиза”, ни “Дату вывода из эксплуатации”
• Сценарий можно связать с прошлой версией описания этого сценария (прошлая версия будет выведена из эксплуатации) и дополнительно указать комментариями изменения. При разработке прошлая версия будет отражать AS IS, а текущая версия будет отражать TO BE. Комментариями будут указаны изменения, работы, которые нужно будет сделать.

Немного странно выглядит реализация версионирования.

Версионирование само по себе обычно подразумевает, что сущность (у вас это сценарий использования) имеет версию. И версия всегда растёт, каждый выпуск новой версии её увеличивает. Это можно разными способами делать, цифрами или как в курсах ШСМ датой выпуска. Но суть остаётся той же, у нас появляется набор сущностей и они связаны порядком их появления. Прямые ссылки из одной версии на другую обычно не делаются, но может и можно сделать.

Второй момент, у вас сценарий использования имеет несколько состояний (версия сценария использования). И вы для реализации этих разных состояний, делаете разные атрибуты. У меня СА тоже постоянно так делает. И это неэффективно. Потому что приходится состояние вычислить по нескольким атрибутам, когда его можно было бы задать явно один полем. Вот смотрите.

Сценарий, который не реализован, это что? Это черновик::состояние.
Актуальная версия судя по вашему описанию у нас всегда одна. Выпущенный в релиз сценарий с наибольшей версией это актуальная_версия::состояние.
Ввод из эксплуатации не то, чтобы имеет какой-то логический смысл. Потому что все версии ниже актуальной являются устаревшими. При этом это не значит, что мы их прямо таки выбросили. Вы например можете без проблем посмотреть прошлые версии курсов ШСМ (и там даже домашка ваша сохранится). А дата выхода из эксплуатации это же дата выпуска очередной версии, зачем она нужна?

Я бы оставила версию, дату выпуска и состояние:
Version
Released_at datetime
State Draft/Actual/Expired

@iurii-toropchin

Внутри сценария указываются и “Желаемые характеристики системы”, которые можно измерить количественно, например так:

Желаемые характеристики системы (дополнение к сценариям использования):

1. Система принимает 500 показаний давления от Пациентов за 1 минуту
2. Система запоминает до 1000000 показаний давления за полгода

А сможете назвать на какие характеристики вы указали желаемые метрики?
Метрика 1 - это характеристика “название характеристики”. И т.д.

[iurii-toropchin]

Спасибо за ваш ответ.

Версионирование само по себе обычно подразумевает, что сущность (у вас это сценарий использования) имеет версию. И версия всегда растёт, каждый выпуск новой версии её увеличивает. Это можно разными способами делать, цифрами или как в курсах ШСМ датой выпуска. Но суть остаётся той же, у нас появляется набор сущностей и они связаны порядком их появления. Прямые ссылки из одной версии на другую обычно не делаются, но может и можно сделать.

Все верно в части системы, версии системы будут увеличиваться, но версии фич могут не увеличиваться. По моей идеи описание фичи будет описывать фичу определенной версии сразу в нескольких системах, а осложняется все тем, что существуют несколько экземпляров версий (все они в эксплуатации, on-remise решения), например

• Система v1, эзкемпляр #2, Фича v1, Дата релиза 12.02.25
• Система v1, эзкемпляр #3, Фича v1, Дата релиза 21.03.25
• Система v2, экемпляр #4, Фича v1, Дата релиза 05.04.25

Описание фичи будет одно, где Дата релиза фичи: 01.03.25, а значит все версии и экземпляры будущих систем будут соответствовать этому описанию. Тут уже вижу проблему, что могут сделать специальную сборку и туда накидать фич, как в солянку - тут такое не подойдет.

Второй момент, у вас сценарий использования имеет несколько состояний (версия сценария использования). И вы для реализации этих разных состояний, делаете разные атрибуты. У меня СА тоже постоянно так делает. И это неэффективно. Потому что приходится состояние вычислить по нескольким атрибутам, когда его можно было бы задать явно один полем. Вот смотрите.

Сценарий, который не реализован, это что? Это черновик::состояние.
Актуальная версия судя по вашему описанию у нас всегда одна. Выпущенный в релиз сценарий с наибольшей версией это актуальная_версия::состояние.
Ввод из эксплуатации не то, чтобы имеет какой-то логический смысл. Потому что все версии ниже актуальной являются устаревшими. При этом это не значит, что мы их прямо таки выбросили. Вы например можете без проблем посмотреть прошлые версии курсов ШСМ (и там даже домашка ваша сохранится). А дата выхода из эксплуатации это же дата выпуска очередной версии, зачем она нужна?

Я бы оставила версию, дату выпуска и состояние:
Version
Released_at datetime
State Draft/Actual/Expired

Ваша структура сложнее, но не понятна выгода. Я свои потребности двумя атрибутыми закрываю и не нужно описывать значение состояний.

С вамиши атрибутами есть еще проблема, что я по ним не смогу сказать к каким версиям системы подходят описания (посмотрите выше примеры - у меня несколько экземпляров в эксплуатации). В целом я согласен, что можно и ваш вариант использовать, если подкрутить, но это все будет примерно одно и тоже))

А сможете назвать на какие характеристики вы указали желаемые метрики?
Метрика 1 - это характеристика “название характеристики”. И т.д.

Я предпочитаю не называть, потому что это пораждает споры о терминах)), но я бы мог сказать, что обе метрики относятся к performance.capacity