# Use-case диаграмма по правилам UML

> Актёры, граница системы, include, extend, generalization — направления стрелок, PlantUML и четыре типичные ошибки

_Источник: https://sii.sergeivolchkov.ru/materials/use-cases/uml_







Диаграмма не заменяет [текстовые UC](/materials/use-cases/writing) — она
отвечает на другой вопрос: **кто вообще пользуется системой и что у неё
внутри границы**. Один взгляд, вся картина; детали живут в текстах.

Рисуем в PlantUML и коммитим `.puml` рядом с `.svg` — [as-code, как и
всё остальное](/materials/architecture/c4-levels).

## Образец [#образец]

<img alt="Use-case диаграмма по правилам" src="__img0" />

Что здесь сделано правильно:

* **Граница системы** — прямоугольник с названием продукта. Внутри — то,
  что вы строите; актёры всегда снаружи.
* **Актёры — роли, а не люди и не должности.** Один человек может быть и
  студентом, и преподавателем: это две роли, два актёра.
* **Внешняя система тоже актёр.** LLM-провайдер стоит справа: он не
  инициирует сценарий, но участвует в нём (вторичный актёр).
* **Кейсы — цели**, сформулированные глаголом с объектом, а не экранами и
  не CRUD-операциями.

## Три вида связей — и куда смотрит стрелка [#три-вида-связей--и-куда-смотрит-стрелка]

Это место, где ошибаются чаще всего, поэтому запомни направления
буквально:

| Связь          | Смысл                                                 | Направление стрелки                                  |
| -------------- | ----------------------------------------------------- | ---------------------------------------------------- |
| `<<include>>`  | Обязательная часть, вынесенная ради переиспользования | От **базового** кейса к включаемому                  |
| `<<extend>>`   | Необязательное поведение, срабатывающее по условию    | От **расширяющего** кейса к базовому                 |
| generalization | «Является частным случаем» (is-a)                     | От частного к общему, сплошная линия с треугольником |

Мнемоника: `include` — «база не может без этого»; `extend` — «база
прекрасно живёт и без этого». Отсюда и стрелки: зависимая сторона всегда
указывает на ту, без которой не существует.

**Точка расширения** (`extension point`) — именованное место в базовом
кейсе, куда встраивается расширение: «вопрос вызвал сомнение». Без неё
`extend` превращается в «где-то тут иногда бывает ещё вот это».

**Generalization используй осторожно.** Он корректен, только если частный
кейс выполняет *все* шаги общего и лишь уточняет их. Нужно пропустить или
переопределить шаг — это не наследование, это `include` или `extend`.

## PlantUML: исходник образца [#plantuml-исходник-образца]

```text title="docs/diagrams/use-cases.puml"
@startuml
left to right direction

actor "Студент" as student
actor "Преподаватель" as teacher
actor "LLM-провайдер" as llm <<внешняя система>>

rectangle "Тренажёр к экзамену" {
  usecase "Загрузить материалы курса" as UC1
  usecase "Получить набор вопросов по теме" as UC2
  usecase "Пройти тренировку\n--\nточка расширения:\nвопрос вызвал сомнение" as UC3
  usecase "Оценить ответ студента" as UC4
  usecase "Пожаловаться на некорректный вопрос" as UC5
}

student --> UC1
student --> UC2
student --> UC3
teacher --> UC5

UC3 ..> UC4 : <<include>>
UC5 ..> UC3 : <<extend>>

UC2 --> llm
UC4 --> llm
@enduml
```

Рендер: `plantuml -tsvg docs/diagrams/use-cases.puml`.

## Четыре ошибки на одной картинке [#четыре-ошибки-на-одной-картинке]

<img alt="Типичные ошибки use-case диаграммы" src="__img1" />

1. **UI вместо цели.** «Нажать кнопку» и «Открыть модальное окно» — это
   интерфейс. Он переживёт максимум один редизайн, цель актёра — весь
   продукт.
2. **Нет границы системы.** Без прямоугольника непонятно, где кончается
   ваша ответственность и начинается чужая.
3. **«Система делает».** Use case описывает, чего добивается актёр.
   «Система отправляет запрос в API модели» — это уже реализация, ей
   место в [container-диаграмме](/materials/architecture/c4-levels).
4. **Поток вместо кейсов.** Цепочка стрелок «потом, потом, потом» превращает
   диаграмму в блок-схему. Порядок шагов живёт в текстовом сценарии;
   на use-case диаграмме связи означают только «кто участвует» и
   include/extend.

Пятая ошибка не помещается на картинку: **декомпозиция до операций**.
«Создать вопрос», «Прочитать вопрос», «Обновить вопрос», «Удалить
вопрос» — это таблица в базе, а не цели человека.

## Чек-лист перед сдачей [#чек-лист-перед-сдачей]

* [ ] Есть прямоугольник границы с названием продукта.
* [ ] Каждый актёр — роль; внешние системы вынесены отдельно.
* [ ] Каждый кейс — цель актёра, глагол + объект, без слов «система» и
  названий экранов.
* [ ] Стрелки `include`/`extend` направлены по таблице выше, у `extend`
  названа точка расширения.
* [ ] Между кейсами нет стрелок «потом».
* [ ] Кейсов на диаграмме столько же, сколько текстовых UC в
  `docs/use-cases/` — и имена совпадают дословно.
* [ ] `.puml` и `.svg` закоммичены.

Последний пункт — не формальность: расхождение имён на диаграмме и в
текстах ломает и проверку, и агента, который читает оба артефакта.