v0.5.3

- Мелкие исправления увеличивающие работу конвертера

ai/context/archimate.md

@@ -0,0 +1,514 @@
+# 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` на одной схеме нельзя.