# ArchiMate 3.2 для md2gost — рабочий справочник

Как корректно генерировать диаграммы ArchiMate® 3.2 в PlantUML для отчётов md2gost. Версия языка — только **3.2**. ArchiMate® — товарный знак The Open Group; этот текст — учебная выжимка, не копия спецификации.

---

## 1. Как рисовать

Оградка ` ```uml-archimate ` или ` ```archimate `. В теле — **только макросы**: ни `@startuml`, ни `@enduml`, ни `!include` (их подставит схема).

~~~markdown
Слоистая архитектура портала приведена на @Рисунок:arch_layered.

%arch_layered Слоистая архитектура портала +landscape

```uml-archimate
LAYOUT_TOP_DOWN()

Business_Actor(student, "Студент")
Business_Process(enroll, "Подача заявки")
Application_Service(portalSvc, "Сервис приёма заявок")
Application_Component(portal, "Веб-портал")

Rel_Assignment(student, enroll)
Rel_Serving(portalSvc, enroll)
Rel_Realization(portal, portalSvc)
```
~~~

Широкие схемы (Layered, Application Cooperation) почти всегда с `+landscape`. Флаг `+listing` добавит исходник схемы отдельным Листингом.

Формат макроса: `Категория_Элемент(alias, "Подпись")`. Alias — латиница (`student`, `crm`); нельзя `end`, `start`, `group`. Подписи русские, в кавычках; длинные переносятся через `\n`.

---

## 2. Каркас языка

**Три core-слоя:**

| Слой | Что показывает |
|------|----------------|
| Business | бизнес-сервисы для клиентов, процессы и акторы, которые их реализуют |
| Application | прикладные сервисы и приложения, поддерживающие бизнес |
| Technology | обработка, хранение, сети, а также физический мир |

Плюс слой Strategy, слой Implementation & Migration и аспект Motivation.

**Четыре аспекта:**

| Аспект | Роль | Примеры |
|--------|------|---------|
| Active structure | кто действует | Actor, Role, Component, Node, Device |
| Behavior | что делается | Process, Function, Interaction, Service, Event |
| Passive structure | над чем работают | Business Object, Data Object, Artifact |
| Motivation | зачем | Stakeholder, Driver, Goal, Requirement |

**Каноническая цепочка внутри слоя:**

```text
Active structure  —Assignment→   internal behavior (Process / Function)
internal behavior —Realization→  Service (внешнее поведение)
Service           —Serving→      потребитель (Role / Process / Component)
behavior          —Access→       passive structure
```

**Два межслойных моста:** Serving (сервис предоставляет функциональность потребителю) и Realization (более конкретное реализует более абстрактное).

---

## 3. Элементы → макросы

### Motivation

| Элемент | Макрос | Определение |
|---------|--------|-------------|
| Stakeholder | `Motivation_Stakeholder` | роль лица или организации, заинтересованной в эффектах архитектуры |
| Driver | `Motivation_Driver` | условие, побуждающее ставить цели и вносить изменения |
| Assessment | `Motivation_Assessment` | результат анализа положения дел относительно driver |
| Goal | `Motivation_Goal` | высокоуровневое намерение, желаемое состояние |
| Outcome | `Motivation_Outcome` | конечный результат, эффект |
| Principle | `Motivation_Principle` | общее свойство, применимое к любой системе в контексте |
| Requirement | `Motivation_Requirement` | требуемое свойство конкретной системы |
| Constraint | `Motivation_Constraint` | ограничение на архитектуру или внедрение |
| Meaning | `Motivation_Meaning` | интерпретация концепта в контексте |
| Value | `Motivation_Value` | относительная ценность концепта |

### Strategy

| Элемент | Макрос | Определение |
|---------|--------|-------------|
| Resource | `Strategy_Resource` | актив, которым владеют или управляют |
| Capability | `Strategy_Capability` | способность активной структуры |
| Value Stream | `Strategy_ValueStream` | последовательность активностей, создающая результат для клиента |
| Course of Action | `Strategy_CourseOfAction` | план настройки capabilities и resources под цель |

### Business

| Элемент | Макрос | Аспект | Определение |
|---------|--------|--------|-------------|
| Business Actor | `Business_Actor` | active | сущность, способная выполнять поведение |
| Business Role | `Business_Role` | active | ответственность за поведение |
| Business Collaboration | `Business_Collaboration` | active | агрегат двух и более активных структур |
| Business Interface | `Business_Interface` | active | точка доступа к бизнес-сервису |
| Business Process | `Business_Process` | behavior | последовательность поведения к результату |
| Business Function | `Business_Function` | behavior | набор поведения по компетенциям и ресурсам |
| Business Interaction | `Business_Interaction` | behavior | коллективное поведение участников |
| Business Event | `Business_Event` | behavior | изменение состояния на бизнес-уровне |
| Business Service | `Business_Service` | behavior | явно определённое поведение, доступное среде |
| Business Object | `Business_Object` | passive | концепт предметной области |
| Contract | `Business_Contract` | passive | соглашение провайдера и потребителя |
| Representation | `Business_Representation` | passive | форма представления информации объекта |
| Product | `Business_Product` | composite | набор сервисов и объектов вместе с контрактом |

### Application

| Элемент | Макрос | Аспект | Определение |
|---------|--------|--------|-------------|
| Application Component | `Application_Component` | active | модульная инкапсуляция прикладной функциональности |
| Application Collaboration | `Application_Collaboration` | active | агрегат прикладных активных структур |
| Application Interface | `Application_Interface` | active | точка доступа к прикладным сервисам |
| Application Function | `Application_Function` | behavior | автоматизированное поведение компонента |
| Application Interaction | `Application_Interaction` | behavior | коллективное поведение компонентов |
| Application Process | `Application_Process` | behavior | последовательность прикладного поведения |
| Application Event | `Application_Event` | behavior | изменение состояния приложения |
| Application Service | `Application_Service` | behavior | внешне видимое прикладное поведение |
| Data Object | `Application_DataObject` | passive | данные, структурированные для обработки |

### Technology и Physical

| Элемент | Макрос | Определение |
|---------|--------|-------------|
| Node | `Technology_Node` | вычислительный или физический ресурс, хостящий другие |
| Device | `Technology_Device` | физический ИТ-ресурс |
| System Software | `Technology_SystemSoftware` | ПО среды исполнения или хранения |
| Technology Collaboration | `Technology_Collaboration` | агрегат технологических активных структур |
| Technology Interface | `Technology_Interface` | точка доступа к технологическим сервисам |
| Path | `Technology_Path` | связь между технологическими структурами для обмена |
| Communication Network | `Technology_CommunicationNetwork` | структуры передачи данных |
| Technology Function | `Technology_Function` | набор технологического поведения |
| Technology Process | `Technology_Process` | последовательность технологического поведения |
| Technology Interaction | `Technology_Interaction` | коллективное технологическое поведение |
| Technology Event | `Technology_Event` | изменение технологического состояния |
| Technology Service | `Technology_Service` | внешне видимое технологическое поведение |
| Artifact | `Technology_Artifact` | данные или файл, используемый при разработке и эксплуатации |
| Equipment | `Physical_Equipment` | физические машины и инструменты |
| Facility | `Physical_Facility` | физическая структура или окружение |
| Distribution Network | `Physical_DistributionNetwork` | сеть транспортировки материи или энергии |
| Material | `Physical_Material` | осязаемая материя или энергия |

В 3.2 Device, System Software, Facility и Equipment — **не** подтипы Node, а технологические активные структуры, связанные с Node композицией или агрегацией.

### Implementation & Migration

| Элемент | Макрос | Определение |
|---------|--------|-------------|
| Work Package | `Implementation_WorkPackage` | серия действий с результатом в сроках и ресурсах |
| Deliverable | `Implementation_Deliverable` | определённый результат work package |
| Implementation Event | `Implementation_Event` | изменение состояния при внедрении |
| Plateau | `Implementation_Plateau` | стабильное состояние архитектуры на период |
| Gap | `Implementation_Gap` | различие между двумя plateau |

### Composite и Junction

| Элемент | Макрос |
|---------|--------|
| Grouping | `Grouping` / `Other_Grouping` / `Group` |
| Location | `Other_Location` / `Business_Location` |
| And Junction | `Junction_And` |
| Or Junction | `Junction_Or` |

Grouping и Junction допустимы в любом viewpoint.

### Какой элемент поведения выбрать

| Нужно показать | Берётся |
|----------------|---------|
| последовательность шагов к результату | `*_Process` |
| группу поведения по компетенциям и ресурсам | `*_Function` |
| поведение двух и более участников | `*_Interaction` |
| внешне видимое поведение, чёрный ящик | `*_Service` |
| момент или смену состояния | `*_Event` |

Слой задаётся типом элемента, а не подписью: `Business_Process` ≠ `Application_Process` ≠ `Technology_Process`.

---

## 4. Связи

| Тип | Класс | Смысл | Макрос | Нотация |
|-----|-------|-------|--------|---------|
| Composition | structural | целое состоит из частей, часть не живёт отдельно | `Rel_Composition` | `*--` |
| Aggregation | structural | целое объединяет части, части живут отдельно | `Rel_Aggregation` | `o--` |
| Assignment | structural | ответственность, исполнение, размещение | `Rel_Assignment` | `@-->>` |
| Realization | structural | конкретное реализует абстрактное | `Rel_Realization` | `~~\|>` |
| Serving | dependency | предоставляет функциональность другому | `Rel_Serving` | `-->` |
| Access | dependency | поведение работает с пассивным элементом | `Rel_Access`, `_r`, `_w`, `_rw` | `~~` |
| Influence | dependency | влияет на достижение motivation-элемента | `Rel_Influence` | `..>` |
| Triggering | dynamic | временная или причинная активация | `Rel_Triggering` | `-->>` |
| Flow | dynamic | передача чего-либо | `Rel_Flow` | `..>>` |
| Specialization | other | является разновидностью | `Rel_Specialization` | `--\|>` |
| Association | other | неспецифичная связь | `Rel_Association` | `--` |

Направление раскладки: суффиксы `_Up`, `_Down`, `_Left`, `_Right` — например `Rel_Serving_Up(svc, proc)`.

### Направления связей — где чаще всего ошибаются

| Связь | Откуда → куда |
|-------|---------------|
| Serving | поставщик (обычно Service) → **потребитель** |
| Realization | более конкретное → более абстрактное |
| Composition, Aggregation | целое → часть |
| Assignment | активная структура → поведение |
| Access | поведение → **пассивный** элемент, вид read / write / read-write |
| Triggering | предшественник → следующий |
| Flow | источник → приёмник |
| Influence | влияющий → motivation-элемент, сила в подписи (`++`, `+`, `0`, `-`, `--`) |
| Specialization | специализация → общий тип |

### Правила метамодели

- Элемент может композировать или агрегировать элементы того же класса.
- Внутренние поведения одного слоя могут агрегировать друг друга (Function агрегирует Process).
- Collaboration ведёт себя как соответствующая внутренняя активная структура.
- Stakeholder связывается Association с любым элементом; остальные motivation-элементы влияют друг на друга через Influence.
- Association формально возможна между любыми классами, но применяется только когда нет более точного типа.

---

## 5. Канонические цепочки

```text
# Внутри слоя Business
Business_Actor / Business_Role   Rel_Assignment    Business_Process / Function
Business_Process                 Rel_Realization   Business_Service
Business_Process                 Rel_Access_*      Business_Object
Business_Event                   Rel_Triggering    Business_Process

# Внутри слоя Application
Application_Component            Rel_Assignment    Application_Function / Process
Application_Function             Rel_Realization   Application_Service
Application_Service              Rel_Serving       Business_Process / Business_Role
Application_Component            Rel_Access_*      Application_DataObject
Application_Component            Rel_Composition   Application_Component

# Технологии и данные
Technology_Node                  Rel_Composition   Technology_Device / SystemSoftware
Technology_*                     Rel_Assignment    Technology_Function / Process
Technology_Function              Rel_Realization   Technology_Service
Technology_Service               Rel_Serving       Application_Component
Technology_Artifact              Rel_Realization   Application_DataObject
Application_DataObject           Rel_Realization   Business_Object

# Стратегия и мотивация
Business_Process / App_Service   Rel_Realization   Strategy_Capability
Application_Service / Component  Rel_Realization   Motivation_Requirement
Motivation_Driver                Rel_Association   Motivation_Stakeholder
Motivation_Assessment            Rel_Association   Motivation_Driver
Motivation_Goal                  Rel_Realization   Motivation_Outcome

# Внедрение и миграция
Implementation_WorkPackage       Rel_Realization   Implementation_Deliverable
Implementation_Plateau           Rel_Aggregation   элементы core-слоёв
Implementation_Gap               Rel_Association   между двумя plateau
```

### Запреты

1. Не `Rel_Assignment` от Data Object или Business Object к процессу.
2. Не `Rel_Realization` от Component сразу к Process: нужен внутренний Function или Process, затем Realization к Service.
3. Не `Rel_Serving` в направлении «потребитель → сервис».
4. Не подменять Access потоком Flow только потому, что речь о данных.
5. Не ставить `Business_Process` там, где исполнитель — приложение.
6. Не ставить Association на все рёбра «на всякий случай».
7. Не считать Device подтипом Node без композиции или агрегации.

---

## 6. Viewpoints

**Один рисунок = один viewpoint.** Не сваливать мотивацию, бизнес, приложения и инфраструктуру на один холст (Layered — исключение, но и там ограничивай число элементов).

| Viewpoint | Фокус | Типичные элементы |
|-----------|-------|-------------------|
| Organization | структура организационных единиц | Actor, Role, Collaboration, Location |
| Application Structure | внутренняя структура приложений | Component, Interface, Data Object |
| Information Structure | данные и информация | Business Object, Representation, Data Object, Artifact |
| Technology | инфраструктура | Node, Device, System Software, Network, Path |
| Layered | обзор слоёв | Business + Application + Technology, Serving и Realization |
| Physical | физический мир | Equipment, Facility, Distribution Network, Material |
| Product | ценность продукта | Product, Contract, Service, Interface |
| Application Usage | приложения в бизнес-контексте | бизнес-процессы + прикладные сервисы |
| Technology Usage | технологии для приложений | Application + Technology services и nodes |
| Business Process Cooperation | связь процессов | Process, Event, Service, Role |
| Application Cooperation | связь приложений | Component, Service, Interface, Data, Flow |
| Service Realization | как реализованы сервисы | Service ← Process / Function ← активная структура |
| Implementation and Deployment | развёртывание | Application + Artifact + Node / Device |
| Stakeholder, Goal Realization, Requirements Realization, Motivation | мотивация | Driver, Goal, Outcome, Requirement, Constraint |
| Strategy, Capability Map, Value Stream, Resource Map | стратегия | Capability, Resource, Value Stream, Course of Action |
| Project, Migration, Implementation and Migration | внедрение | Work Package, Deliverable, Plateau, Gap |

### Макет

- Структурные схемы: `LAYOUT_TOP_DOWN()` или вложенность через `{ }`.
- Процессы слева направо: `LAYOUT_LEFT_RIGHT()` и `Rel_*_Right`.
- Layered: бизнес сверху, технологии снизу; Serving и Realization направлены вверх (`Rel_Serving_Up`).
- Выравнивание скрытыми связями: `Lay_U`, `Lay_D`, `Lay_L`, `Lay_R`.
- Вложение элементов:

```text
Business_Product(prod, "Тариф") {
  Business_Service(s1, "Подключение")
  Business_Contract(c1, "Оферта")
}
```

Для Service, Actor, Value и ValueStream при вложении добавляется `$nest=%true()`.

---

## 7. Готовые шаблоны

Тела для ` ```uml-archimate ` без обёртки.

### Organization

```text
LAYOUT_TOP_DOWN()
Business_Actor(uni, "Университет") {
  Business_Actor(dean, "Деканат")
  Business_Actor(it, "Управление ИТ")
}
Business_Role(student, "Студент")
Business_Role(clerk, "Методист")
Rel_Assignment(dean, clerk)
Rel_Assignment(uni, student)
```

### Service Realization

```text
LAYOUT_TOP_DOWN()
Business_Role(applicant, "Абитуриент")
Business_Process(apply, "Подача заявления")
Business_Service(applySvc, "Приём заявлений")
Application_Service(webSvc, "Веб-приёмная")
Application_Component(lk, "Личный кабинет")
Application_Function(submitFn, "Отправка формы")

Rel_Assignment(applicant, apply)
Rel_Realization(apply, applySvc)
Rel_Serving(webSvc, apply)
Rel_Assignment(lk, submitFn)
Rel_Realization(submitFn, webSvc)
```

### Application Cooperation

```text
LAYOUT_LEFT_RIGHT()
Application_Component(crm, "CRM")
Application_Component(billing, "Биллинг")
Application_Service(crmApi, "API клиентов")
Application_DataObject(client, "Карточка клиента")

Rel_Realization(crm, crmApi)
Rel_Serving(crmApi, billing)
Rel_Access_rw(crm, client)
Rel_Access_r(billing, client)
Rel_Flow(crm, billing, "событие оплаты")
```

### Layered

```text
LAYOUT_TOP_DOWN()
Business_Process(sale, "Оформление заказа")
Business_Object(order, "Заказ")
Application_Service(shopSvc, "Интернет-магазин")
Application_Component(shop, "ShopApp")
Technology_Service(dbSvc, "СУБД")
Technology_Node(dbHost, "Сервер БД")
Technology_SystemSoftware(pg, "PostgreSQL")

Rel_Access_w(sale, order)
Rel_Serving_Up(shopSvc, sale)
Rel_Realization(shop, shopSvc)
Rel_Serving_Up(dbSvc, shop)
Rel_Assignment(dbHost, dbSvc)
Rel_Composition(dbHost, pg)
```

### Requirements Realization

```text
LAYOUT_TOP_DOWN()
Motivation_Stakeholder(rector, "Ректор")
Motivation_Driver(comp, "Конкуренция вузов")
Motivation_Goal(digital, "Цифровизация приёма")
Motivation_Requirement(online, "Заявление онлайн круглосуточно")
Motivation_Constraint(fz152, "152-ФЗ")
Application_Service(portal, "Портал абитуриента")

Rel_Association(rector, comp)
Rel_Association(comp, digital)
Rel_Realization(online, digital)
Rel_Influence(fz152, online, "-")
Rel_Realization(portal, online)
```

### Implementation & Migration

```text
LAYOUT_LEFT_RIGHT()
Implementation_Plateau(asIs, "AS-IS 2025")
Implementation_Plateau(toBe, "TO-BE 2026")
Implementation_Gap(gap1, "Нет единого личного кабинета")
Implementation_WorkPackage(wp, "Проект «Единый ЛК»")
Implementation_Deliverable(d1, "Релиз 1.0")
Implementation_Event(goLive, "Ввод в эксплуатацию")

Rel_Association(gap1, asIs)
Rel_Association(gap1, toBe)
Rel_Realization(wp, d1)
Rel_Triggering(d1, goLive)
Rel_Triggering(goLive, toBe)
```

### Technology Usage

```text
LAYOUT_TOP_DOWN()
Application_Component(api, "API Gateway")
Technology_Node(k8s, "Кластер Kubernetes")
Technology_Device(node1, "Рабочий узел")
Technology_SystemSoftware(os, "Linux")
Technology_CommunicationNetwork(net, "Сеть кластера")
Technology_Artifact(image, "api:1.2")

Rel_Serving_Up(k8s, api)
Rel_Composition(k8s, node1)
Rel_Composition(node1, os)
Rel_Association(node1, net)
Rel_Assignment(node1, image)
```

### Процесс с Junction

```text
LAYOUT_LEFT_RIGHT()
Business_Event(incident, "Инцидент")
Business_Process(triage, "Первичная оценка")
Junction_Or(j1, "")
Business_Process(restore, "Восстановление сервиса")
Business_Process(investigate, "Расследование")
Business_Process(close, "Закрытие инцидента")

Rel_Triggering(incident, triage)
Rel_Triggering(triage, j1)
Rel_Triggering(j1, restore)
Rel_Triggering(j1, investigate)
Rel_Triggering(restore, close)
Rel_Triggering(investigate, close)
```

---

## 8. Антипаттерны

| Плохо | Почему | Как надо |
|-------|--------|----------|
| все связи `Rel_Association` | теряется семантика | Serving, Realization, Assignment, Access |
| `Application_Component` вместо `Business_Actor` | разные аспекты и слои | Actor и Role для людей и подразделений |
| Business Process «внутри» компонента без Assignment | слои смешаны | процесс на бизнес-слое, Serving от прикладного сервиса |
| Serving от Role к Service | направление наоборот | Service → Role или Process |
| Realization Component → Process | пропущено внутреннее поведение | Component → Function → Service |
| Flow вместо Access к Data Object | Flow — передача, Access — работа с объектом | `Rel_Access_r/w/rw` |
| один Layered на 40 элементов | нечитаемо | несколько viewpoint'ов |
| C4 `Person` или UML-класс в блоке archimate | другой язык | только макросы ArchiMate |
| `Process` без указания слоя | в 3.2 слой обязателен | `Business_Process`, `Application_Process`, `Technology_Process` |

---

## 9. Чеклист генерации

1. Версия языка 3.2, макросы с указанием слоя.
2. Оградка ` ```uml-archimate `, без `@startuml` и `!include`.
3. Выбран **один** viewpoint; 8–18 элементов на рисунок.
4. Сначала объявлены все элементы, затем все `Rel_*`.
5. Alias латиницей, подписи по-русски в кавычках.
6. Serving — от сервиса к потребителю; Realization — от конкретного к абстрактному.
7. Поведение того же слоя, что и его исполнитель по Assignment.
8. Нет C4, UML-классов, BPMN-развилок и Association «по умолчанию».
9. Перед блоком стоит `%id Название`, при широкой схеме — `+landscape`.
10. В тексте есть ссылка `@Рисунок:id`.

---

## 10. Запасной вариант без stdlib

Если библиотека ArchiMate недоступна, схему можно нарисовать в ` ```uml ` низкоуровневым ключевым словом:

~~~markdown
%arch_fallback Фрагмент архитектуры

```uml
@startuml
archimate #Business "Подача заявки" as p <<business-process>>
archimate #Application "Портал" as c <<application-component>>
c --> p
@enduml
```
~~~

Смешивать макросы и низкоуровневый `archimate` на одной схеме нельзя.