sarex/iac
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Expand architecture documentation: update component counts, refine domain groupings, add new Archimate views, and enhance notation explanations.

Browse Source
This commit is contained in:
emelinda 2026-08-20 19:23:43 +03:00
parent 8357ccee8a
commit c6dff71420
1 changed files with 11 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/architecture/README.md
View File

@ -16,22 +16,25 @@
| `app-summaries.md` | короткие описания компонентов прикладного слоя (1–3 предложения) | вход для сборки; попадает в поле `Documentation` модели | | `app-summaries.md` | короткие описания компонентов прикладного слоя (1–3 предложения) | вход для сборки; попадает в поле `Documentation` модели |
| `app-docs.md` | развёрнутые описания тех же компонентов | справочник; в модель по умолчанию не идёт | | `app-docs.md` | развёрнутые описания тех же компонентов | справочник; в модель по умолчанию не идёт |
86 элементов, 331 отношение, 25 представлений. 91 элемент, 369 отношений, 40 представлений.
| Представление | Что показывает | | Представление | Что показывает |
|---|---| |---|---|
| L1 | Легенда нотации: что означает каждый тип элемента и каждый тип линии. Собрана из настоящих элементов модели — заодно разобранный пример |
| T1 | Кластер, ПО внутри него, внешние узлы, технологические сервисы. Без приложений — обзорная схема | | T1 | Кластер, ПО внутри него, внешние узлы, технологические сервисы. Без приложений — обзорная схема |
| T2 | Развёртывание по узлам: какая группа узлов какие компоненты несёт | | T2 | Развёртывание по узлам: какая группа узлов какие компоненты несёт |
| T3 | Внешние интеграции: чем контур связан с инфраструктурой заказчика — каталог предприятия, брокер идентификации, служба федерации, почтовый релей | | T3 | Внешние интеграции: чем контур связан с инфраструктурой заказчика — каталог предприятия, брокер идентификации, служба федерации, почтовый релей |
| T4–T13 | По одному представлению на технологический сервис: кто им пользуется |
| A0 | Карта прикладного слоя: все компоненты по смысловым группам, без связей |
| A1 | Ядро прикладного слоя: восемь самых связанных сервисов и вызовы между ними | | A1 | Ядро прикладного слоя: восемь самых связанных сервисов и вызовы между ними |
| A2–A12 | По представлению на сервис с тремя и более потребителями: кто от него зависит | | A2–A12 | По представлению на сервис с тремя и более потребителями: кто от него зависит |
| T16–T25 | По одному представлению на технологический сервис: кто им пользуется | | P1–P13 | Паспорт сервиса — зеркало к A2–A12: не «кто сломается без него», а «без чего не работает он сам» |
Направление связи — как принято в ArchiMate: стрелка идёт от вызываемого к вызывающему (serving). Читается как «кого лишишься — тот и сломается». Направление связи — как принято в ArchiMate: стрелка идёт от вызываемого к вызывающему (serving). Читается как «кого лишишься — тот и сломается». Тот же вопрос с другой стороны — представления P: что нужно самому сервису, чтобы работать.
Разбиение по сервисам сделано осознанно: 148 связей «технологический сервис → приложение» и 86 межсервисных вызовов на одной схеме нечитаемы. В модели они лежат одним набором, представления — это срезы. Разбиение по сервисам сделано осознанно: 148 связей «технологический сервис → приложение» и 86 межсервисных вызовов на одной схеме нечитаемы. В модели они лежат одним набором, представления — это срезы.
Метамодель намеренно урезана. Технологический слой: `Node`, `SystemSoftware`, `TechnologyService`, `Artifact`. Прикладной: `ApplicationComponent`. Отношения: `Composition`, `Realization`, `Serving`, `Assignment`. Не используются `Device`, `Path`, `CommunicationNetwork`, `TechnologyFunction` — они не несут информации на этом уровне. Метамодель намеренно урезана. Технологический слой: `Node`, `SystemSoftware`, `TechnologyService`, `Artifact`. Прикладной: `ApplicationComponent`. Смысловая группировка: `Grouping`. Отношения: `Composition`, `Aggregation`, `Realization`, `Serving`, `Assignment`. Не используются `Device`, `Path`, `CommunicationNetwork`, `TechnologyFunction` — они не несут информации на этом уровне.
## Как собрать модель для реального контура ## Как собрать модель для реального контура
@ -94,6 +97,8 @@
В представлении T3 показаны все четыре сразу — при сборке модели для конкретного контура лишние узлы из профиля убираются. Keycloak поставляется и чартом платформы (`infrastructure/keycloak`), поэтому брокер может стоять как у заказчика, так и внутри контура. В представлении T3 показаны все четыре сразу — при сборке модели для конкретного контура лишние узлы из профиля убираются. Keycloak поставляется и чартом платформы (`infrastructure/keycloak`), поэтому брокер может стоять как у заказчика, так и внутри контура.
**Группировка прикладного слоя по доменам — тоже не из манифестов.** В репозитории нет ничего, что относило бы приложение к «контролю качества» или «полевым данным»: это смысл, а не конфигурация. Группы заданы в профиле, блок `domains`, и сверены с доменной группировкой в [../apps/README.md](../apps/README.md). От контура к контуру они не меняются — в отличие от остального в профиле, это свойство продукта. Последняя группа с `"apps": "*"` собирает всё, что не попало в предыдущие: так новое приложение не исчезает с карты молча, а всплывает в группе «Не отнесено». Если группа пуста, в модель она не попадает.
Описания компонентов в `app-docs.md` и `app-summaries.md` выведены не из этого репозитория, а из исходного кода компонентных репозиториев, и потому проверяются иначе — чтением кода, а не грепом по манифестам. Там, где доказательств не хватило, это сказано в самом описании; такие места стоит подтверждать у команды платформы, а не считать фактом. Описания компонентов в `app-docs.md` и `app-summaries.md` выведены не из этого репозитория, а из исходного кода компонентных репозиториев, и потому проверяются иначе — чтением кода, а не грепом по манифестам. Там, где доказательств не хватило, это сказано в самом описании; такие места стоит подтверждать у команды платформы, а не считать фактом.
## Про формат файлов ## Про формат файлов
@ -102,6 +107,8 @@
Эталон для сверки — любая модель из [archimatetool/ArchiModels](https://github.com/archimatetool/ArchiModels), созданная самим Archi. Эталон для сверки — любая модель из [archimatetool/ArchiModels](https://github.com/archimatetool/ArchiModels), созданная самим Archi.
Пояснительные надписи на легенде — объекты `archimate:Note`: они принадлежат схеме, а не модели, поэтому в счёт элементов не идут и в других инструментах ничего не ломают. В обменном формате им соответствуют узлы `xsi:type="Label"`.
`example-technology.xml` проверен на соответствие официальной схеме `archimate3_Diagram.xsd`. Если сторонний инструмент не берёт нативный формат, используйте его. Отличие обменной версии: вложенность узлов развёрнута в плоский список с абсолютными координатами (в обменном формате трактовка координат вложенного узла неоднозначна между реализациями). Визуально раскладка та же, но компоненты внутри кластера не будут его дочерними элементами. `example-technology.xml` проверен на соответствие официальной схеме `archimate3_Diagram.xsd`. Если сторонний инструмент не берёт нативный формат, используйте его. Отличие обменной версии: вложенность узлов развёрнута в плоский список с абсолютными координатами (в обменном формате трактовка координат вложенного узла неоднозначна между реализациями). Визуально раскладка та же, но компоненты внутри кластера не будут его дочерними элементами.
## Скрипты ## Скрипты