Перейти к основному содержимому

Спецификации UseCase-ов

Спецификация UseCase-а формируется на основе потока данных.

Поток данных задает последовательность шагов, участников, интеграционные вызовы, запросы, ответы, альтернативные ветки, параллельные ветки и дополнительные свойства. Документационное представление собирает эти данные в читаемый сценарий.

Когда использовать спецификацию​

Спецификация UseCase-а полезна, когда нужно:

  • описать бизнес-сценарий;
  • согласовать порядок взаимодействия систем;
  • показать, какие интерфейсы участвуют в сценарии;
  • связать бизнес-описание с архитектурной диаграммой;
  • передать описание разработчикам или аналитикам;
  • подготовить материалы для архитектурного ревью;
  • экспортировать описание в статический HTML;
  • дать read-only доступ по share-ссылке;
  • попросить AI улучшить текст или найти недостающие вопросы.

Как открыть спецификацию​

Спецификацию можно открыть несколькими способами.

Через вкладку «Потоки данных»:

  1. Откройте главный экран.
  2. В левом меню перейдите в «Потоки данных».
  3. Найдите нужный поток.
  4. В контекстном меню выберите «Документация».

Через редактор диаграммы:

  1. Откройте диаграмму.
  2. Откройте меню «Отчеты».
  3. Выберите отчет по потокам, если он доступен.

Через share-ссылку:

  1. Откройте ссылку доступа.
  2. Убедитесь, что для ссылки включены «Потоки данных» и «Документация».
  3. Перейдите к документации из меню или разрешенного маршрута.
Загрузка изображения...
Документационное представление показывает Data Flow, Sequence, шаги сценария, endpoint, запрос и ответ.

Меню документации​

В документационном представлении доступны:

  • меню «Диаграмма»;
  • настройка типа линий: Ortho, Poly, Default;
  • меню «Поток данных» с выбором потока;
  • кнопка Скачать одним HTML-файлом;
  • кнопка Настройки документации;
  • кнопка Открыть диаграмму;
  • кнопка Полный экран.
  • значки глаза у альтернативных последовательностей для персонального включения и исключения веток.

Если документация открыта по share-ссылке, доступность определяется настройками шаринга. Если документация запрещена через Lock, кнопки могут быть скрыты или заблокированы.

Что отображается в спецификации​

В спецификации отображаются:

  • название диаграммы;
  • название потока данных;
  • описание потока;
  • шаги сценария;
  • вложенные альтернативные и параллельные шаги;
  • источник и цель интеграционных шагов;
  • привязанные интерфейсы;
  • URL, запросы, ответы и описания интерфейсов;
  • изображения и вложения;
  • дополнительные свойства шагов;
  • связи с элементами модели.

Как подготовить качественную спецификацию​

  1. Создайте диаграмму, которая показывает участников сценария.
  2. Создайте поток данных.
  3. Добавьте шаги в правильном порядке.
  4. Для каждого интеграционного шага укажите источник и цель.
  5. Создайте или импортируйте интерфейсы у целевого элемента.
  6. Привяжите интеграционные шаги к интерфейсам.
  7. Добавьте запросы, ответы, описания и вложения.
  8. Проверьте сценарий в режиме Data flow и Sequence.
  9. Откройте спецификацию и проверьте текст.
  10. Используйте AI, чтобы найти пробелы и подготовить вопросы для владельцев.

Настройки документации​

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

Например, можно настроить отображение:

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

Для Sequence-диаграмм можно включить настройку «Скрывать описания элементов на Sequence-диаграммах». Она убирает поле description из подписей участников, но оставляет названия элементов и сообщения между ними. Это делает широкие диаграммы компактнее и позволяет показать их крупнее.

После включения настройки появляется список UseCase с множественным выбором. Отметьте только те UseCase, для которых нужны компактные Sequence-диаграммы. Если список оставить пустым, описания будут скрыты для всех UseCase в текущей документации. Изменение применяется сразу и сохраняется в выбранном профиле документации.

Загрузка изображения...
Панель управляет составом документа, диаграммами, спецификациями шагов и компактным отображением Sequence.

Скрытие альтернативных последовательностей​

В правом верхнем углу каждой альтернативной последовательности отображается значок глаза. Он позволяет временно исключить ветку из текущей спецификации и сосредоточить документ на нужном варианте сценария.

  1. Найдите альтернативную последовательность в спецификации.
  2. Нажмите значок глаза рядом с ее заголовком.
  3. Значок станет перечеркнутым, а ветка и все вложенные в нее шаги исчезнут из документационного представления.
  4. Повторно нажмите значок, чтобы вернуть ветку.

Переключатель использует ту же персональную настройку, что и панель потока на диаграмме. Поэтому скрытая в документации ветка одновременно перестает отображаться на Data flow/Sequence-диаграмме и участвовать в пошаговом проигрывании.

Настройка относится только к текущему пользователю. У остальных пользователей все альтернативы по-прежнему отображаются, пока они сами их не скроют. Скрытие не редактирует UseCase, не удаляет шаги и не требует изменения общей модели.

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

AI и улучшение спецификаций​

AI можно использовать для доработки UseCase-документации.

Примеры запросов:

  • Проверь этот UseCase и перечисли, чего не хватает для разработки.
  • Сгенерируй текстовое описание сценария для бизнес-заказчика.
  • Выдели альтернативные сценарии, которые не описаны.
  • Какие интерфейсы нужно уточнить перед ревью?
  • Сделай краткое резюме UseCase-а для release notes.

Если AI задает уточняющие вопросы, ответьте на них и затем обновите поток данных или свойства шагов.

Экспорт UseCase-спецификации​

Спецификацию можно выгрузить в статический HTML. Общая страница по экспорту находится в разделе «Экспорт спецификаций UseCase-ов».

При выгрузке одним HTML-файлом скрытые текущим пользователем альтернативные последовательности не включаются в документ. Перед скачиванием проверьте значки глаза: экспорт фиксирует видимое для вас состояние спецификации на этот момент.

Такой экспорт полезен, когда нужно:

  • отправить документацию внешним участникам;
  • сохранить состояние описания на момент согласования;
  • приложить спецификацию к задаче или заявке;
  • опубликовать материалы вне ArchiVision.

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

Краевые случаи​

Документация не открывается из share-ссылки​

Проверьте настройки ссылки:

  • Потоки данных;
  • Документация.

Если включена только визуальная часть диаграммы, UseCase-спецификация недоступна.

В спецификации нет шагов​

Проверьте:

  • выбран правильный поток;
  • у потока есть шаги;
  • поток связан с текущей диаграммой;
  • получателю share-ссылки разрешен просмотр потоков данных.

Нет запросов и ответов​

Проверьте:

  • описаны ли интерфейсы у целевого элемента;
  • привязан ли шаг к интерфейсу;
  • импортирована ли API-документация;
  • разрешен ли просмотр интерфейсов в share-ссылке.

Кнопка экспорта HTML недоступна​

Проверьте:

  • включена ли документация;
  • не открыт ли режим, который запрещает экспорт;
  • выбран ли поток данных, если экспорт строится по UseCase-у;
  • не запрещены ли документация или экспорт через Lock.

Связанные разделы​