# Роль SMALUM — UML / Mermaid / SQL
<!-- smalum-role-version: 1.11.0 -->

Узкая шпаргалка нотации для внешней LLM (ENH-1624). Склейка: [role-core.md](https://docs.smalum.io/role-core.md) + этот файл.
Полный каталог: https://docs.smalum.io/role.md · страница: https://docs.smalum.io/ai · эталоны: https://docs.smalum.io/role-examples.md

Файл: https://docs.smalum.io/role-uml.md

# Часть C — UML и смежное (PlantUML / Mermaid / SQL)

Обёртка PlantUML почти всегда:

```
@startuml
title …
…
@enduml
```

Mermaid — без `@startuml`: первая строка `flowchart TD` / `sequenceDiagram` / … (C8). Когда какой формат — §0.2a.

`skinparam` и `#цвет` **не красят** use-case и activity на холсте Smalum — не опирайтесь на них. Не используйте устаревший activity `(*)`.

## C1. Use Case — акторы и сценарии

```
@startuml
left to right direction
title Интернет-магазин

actor "Клиент" as Client
actor "Оператор" as Operator

rectangle "Магазин" {
  usecase "Смотреть каталог" as UC1
  usecase "Оформить заказ" as UC2
  usecase "Оплатить" as UC3
}

Client --> UC1
Client --> UC2
UC2 ..> UC3 : <<include>>
Operator --> UC2
@enduml
```

| Конструкция | Смысл |
|-------------|--------|
| `actor` / `:Имя:` | актёр |
| `usecase "…" as Id` / `(Сценарий)` | прецедент |
| `rectangle "Система" { }` | граница; актёры снаружи |
| `-->` | ассоциация |
| `..> : <<include>>` / `<<extend>>` | включение / расширение |
| `--\|>` | обобщение |

## C2. Activity — алгоритм / workflow

Лейаут в Smalum **всегда сверху вниз** (`left to right direction` игнорируется).

```
@startuml
title Оформление заказа
start
:Открыть корзину;
if (Корзина пуста?) then (да)
  :Показать заглушку;
  stop
else (нет)
  :Ввести адрес;
endif
fork
  :Резерв на складе;
fork again
  :Списать бонусы;
end fork
:Создать заказ;
stop
@enduml
```

| Конструкция | Смысл |
|-------------|--------|
| `start` / `stop` / `end` | начало / конец |
| `:действие;` | шаг |
| `if / else / endif` | решение + слияние |
| `fork` / `fork again` / `end fork` | параллель |
| `\|Дорожка\|` | swimlane |
| `partition` / `group` | рамка |

## C3. State — жизненный цикл

```
@startuml
left to right direction
title Состояния заказа

[*] --> NEW
NEW --> PAID : pay()
PAID --> SHIPPED : ship()
state SHIPPED {
  [*] --> PACKING
  PACKING --> IN_TRANSIT : handed to carrier
  IN_TRANSIT --> DELIVERED : received
}
SHIPPED --> [*] : done
NEW --> CANCELLED : cancel()
CANCELLED --> [*]
@enduml
```

| Конструкция | Смысл |
|-------------|--------|
| `[*]` / `[]` | начальное / конечное |
| `state "…" as Alias` | состояние |
| `state Name { }` | составное |
| `A --> B : событие` | переход |
| `<<choice>>` / `<<fork>>` / `<<join>>` | псевдосостояния |
| `-u->` / `-d->` | явная сторона |

Одинаковые подписи с **разными alias** — разные блоки.

## C4. Class — типы и ER «классами»

```
@startuml
title Заказы

entity "Пользователь" as User {
  * id : UUID <<PK>>
  --
  email : String
  name : String
}

entity "Заказ" as Order {
  * id : UUID <<PK>>
  --
  user_id : UUID <<FK>>
  total : Decimal
}

User ||--o{ Order
@enduml
```

| Конструкция | Смысл |
|-------------|--------|
| `class` / `entity` / `enum` / `interface` / `object` | классификаторы |
| `package` / `namespace` | рамка |
| `--\|>` / `..\|>` | обобщение / реализация |
| `o--` / `*--` | агрегация / композиция |
| `"1" -- "0..*"` / crow’s foot | кратности |

Голые строки без операторов связи — **не** рёбра (будет warning). Для чистого DDL предпочитайте SQL (§C7).

## C5. C4 (архитектура)

В подписях Person/Container/… два и более пробела подряд = перенос строки (как `\n` / `"Name  [techn]  descr"`).

```
@startuml
!include <C4/C4_Container>

title Интернет-магазин — C4 Container

Person(customer, "Клиент", "Покупает товары")
System_Boundary(shop, "Интернет-магазин") {
  Container(web, "Web App", "React", "Витрина")
  Container(api, "API", "Node.js", "Логика")
  ContainerDb(db, "Database", "PostgreSQL", "Данные")
}
System_Ext(pay, "Платёжный шлюз", "Оплата")

Rel(customer, web, "Использует", "HTTPS")
Rel(web, api, "API", "HTTPS")
Rel(api, db, "Читает/пишет", "SQL")
Rel(api, pay, "Списывает", "HTTPS")
@enduml
```

Типично: `C4_Context`, `C4_Container`, `C4_Component`. Person / System / Container / ContainerDb / System_Ext / Boundary + `Rel(...)`.

**C4 — только два синтаксиса:** PlantUML `@startuml` + `!include <C4/…>` (как выше) или Mermaid `C4Context` / `C4Container` / `C4Component` (§C8). Заголовка `//smalum/c4/…` **нет** — не выдумывайте диалект (`person x = …`, `system y = …`, `a -- b`). Не смешивайте C4 с типами Infra (`camera`, `gateway`, `device`, `cloud`): камера или шлюз на контексте — `System_Ext(cam, "Камера ленты", "RTSP")`; схема оборудования — отдельный блок `//smalum/infra` (Часть I).

## C6. Component / deployment

```
@startuml
node "Application Server" as srv {
  artifact "app.war" as app
  [Web Module] as web
}
node "Database Server" as db {
  database "PostgreSQL" as pg
}
srv --> db
app --> web
@enduml
```

Поддерживаются `[Name]`, `()`, `database`, `node`, `artifact`, socket/lollipop в разумных пределах PlantUML component. `port` — только внутри element.

## C7. SQL → ERD

Без `@startuml`. Редактор строит ER из DDL:

```
-- Интернет-магазин
CREATE TABLE users (
  id UUID PRIMARY KEY,
  email VARCHAR(255) NOT NULL UNIQUE,
  name VARCHAR(120)
);

CREATE TABLE orders (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL REFERENCES users(id),
  total DECIMAL(12, 2) NOT NULL,
  status VARCHAR(32) NOT NULL DEFAULT 'NEW'
);
```

---

## C8. Mermaid (срез Smalum)

Smalum разбирает Mermaid **в UDM** (не mermaid.js). Оверлей — `%% SM:` (D1). Выбор vs PlantUML — §0.2a.

**Есть парсер:** `flowchart` / `graph` (TD, TB, LR, RL, BT), `sequenceDiagram`, `classDiagram`, `stateDiagram` / `stateDiagram-v2`, `C4Context` / `C4Container` / `C4Component`.

**Нет парсера (брак):** `erDiagram`, `mindmap`, `gantt`, `pie`, `gitGraph`, `journey`, `timeline`, `sankey`. Цепочки `A --> B --> C`, `A --> B & C`, пунктир `A -.- B` в flowchart — не пишите (по одному ребру на строку, сплошная стрелка `-->`).

Блок-схема (не BPMN):

```
flowchart TD
  start((Начало)) --> login[Ввести логин]
  login --> check{Верно?}
  check -->|да| ok(((Конец)))
  check -->|нет| login
```

`((подпись))` — круг, `(((подпись)))` — двойной круг, `{ }` — ромб, `[( )]` — цилиндр. Это **не** UML activity `start`/`stop`.

Sequence (если явно просили Mermaid; иначе PlantUML C — sequence через `@startuml`):

```
sequenceDiagram
  actor user as Покупатель
  participant api as API
  user->>api: Оформить заказ
  api-->>user: Подтверждение
```

Class:

```
classDiagram
  class Order {
    +id UUID
    +total Decimal
  }
  User "1" --> "*" Order
```

C4 Mermaid — макросы `Person(...)` / `Rel(...)` / `System_Boundary(...)`. Границы в `{ }` — ненадёжны; при сложной вложенности лучше PlantUML C4.

Не оборачивайте в ` ```mermaid `. Первая строка блока — заголовок типа.

---


# Часть M — DMN (таблица решений)

Канон: [Синтаксис-DMN.md](https://docs.smalum.io/) / RFC [v0.2](https://docs.smalum.io/rfc/dmn/v0.2). ADR-65.

## M1. Когда выбирать DMN

| Рассказ | Нотация |
|---------|---------|
| Правила «если … то …», hit policy, колонки входов/выходов | **`//smalum/dmn`** |
| Порядок работ, роли, шлюзы, события | BPMN |
| Потоки данных | DFD |

**DMN ≠ `xor`.** Шлюз — ветвление процесса; DMN — таблица решений (отдельный документ). Таблицу **не** класть внутрь `pool { }`.

## M2. Канон (выдавать только так)

```
//smalum/[каталог/]dmn Название

[input|вход] id [= Подпись]
[knowledge|знание] id [= Подпись]

[decision|решение] id [hit] [unique|any|first|collect <agg>] [= Подпись] {
  in id [= Подпись]
  out id [= Подпись]
  [rId](ячейки_in…) = ячейки_out…
  (*) = …
}

A - B
A -- B
```

- Default hit = **unique**. Слово `hit` только перед policy.
- **Нет** `priority` / `приоритет` (пишите `first`). Буква P в чужой таблице → `first`.
- **`any`** — декларация; не «проверяйте» равенство выходов.
- Catch-all: **`(*)`** (предпочтительно) или `(-, -)`…; `(-)` только при одном `in`.
- Без `|`, без `:`, без `rule when then`, без сигила `!`, без `of`.
- BPMN: `task id rule.<decisionId>` (точка).

## M3. Оверлей

Как у BPMN/DFD: `// SM:` в конце файла (Часть D). Ширины колонок таблицы в v0.2 не нормируйте.

## M4. Брак

- `priority {` / `discount priority {`
- `(-)` при двух+ `in` без `(*)` / полного списка `-`
- таблица внутри `pool`
- `task … rule of X`
- ASCII `| … | … |`