https://github.com/wizardjedi/a1s-plantuml-lib

Библиотека компонентов для диаграмм PlantUML с сфере телекома и мобильной связи
https://github.com/wizardjedi/a1s-plantuml-lib

diagram messenger mobile operators plantuml sprites telecom

Last synced: about 2 months ago
JSON representation

Библиотека компонентов для диаграмм PlantUML с сфере телекома и мобильной связи

• Host: GitHub
• URL: https://github.com/wizardjedi/a1s-plantuml-lib
• Owner: wizardjedi
• Created: 2024-02-19T08:03:06.000Z (about 1 year ago)
• Default Branch: master
• Last Pushed: 2024-02-23T13:04:35.000Z (about 1 year ago)
• Last Synced: 2025-01-21T01:42:39.383Z (4 months ago)
• Topics: diagram, messenger, mobile, operators, plantuml, sprites, telecom
• Homepage:
• Size: 1.9 MB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.adoc

Awesome Lists containing this project

README

        
= A1S PlantUML Lib

:toc:

:sectnums:

:sectnumlevels: 5

:outlinelevels: 5

:sectids:

Библиотека тем и спрайтов A1S.

WARNING: Отказ от ответственности: все права принадлежат их владельцам. Данные получены из открытых источников и сети Интернет. Данная библиотека предоставляется в режиме AS-IS. Автор не несёт ответственности в случае ущерба, понесённого в результате использования данной библиотеки.

TIP: В случае, если у вас есть более качественная версия логотипа или более точная версия цвета, то можете создать MR (fork + pull request/merge request).

В телекоме и в области мобильной связи часто возникает необходимость в диагрммах, например, диаграммах прохождения трафика или каких-то даиграммах последовательностей.

Одним из лучших, если не самым лучшим инстурментом для рисования диаграмм и схем (в парадигде `diagram as a code`) является PlantUML ( https://plantuml.com/ ).

Кроме того, у данного инструмента есть множество интеграций с другими системами:

 * Confluence https://marketplace.atlassian.com/apps/41025/plantuml-for-confluence?tab=overview&hosting=datacenter

 * Intellij Idea https://plugins.jetbrains.com/plugin/7017-plantuml-integration

 * MS VS Code https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml

Так как достаточно часто приходится рисовать диаграммы, то и появилась необходимость собрать часто используемые части/компоненты в виде библиотеки.

Например, очень не хватало логотипов операторов.

При использовании данной библиотеки можно строить диаграммы такого вида:

.Пример диаграммы с использованием библиотеки

image::_example/simple.png[]

В виде такого текстового описания:

.Пример текста для генерации диаграммы

[source,puml]

----

@startuml

title Схема прохождения трафика

!include https://raw.githubusercontent.com/wizardjedi/a1s-plantuml-lib/master/a1s-lib.puml

rectangle "<$megafon_s,scale=0.5,color=$CLR_MEGAFON_1>" as megafon

rectangle "<$mts_s,scale=0.5,color=$CLR_MTS_1>" as mts

rectangle "<$beeline_s,scale=0.5>" as beeline $CLR_BEELINE_1

rectangle "<$tele2_s,scale=0.5,color=$CLR_TELE2_1>" as tele2

rectangle "<$smstraffic_s,scale=0.5,color=$CLR_SMSTRAFFIC_1>\nSMS Traffic" as smstraffic

rectangle "<$devino_s,scale=0.5,color=$CLR_DEVINO_1>\nDevino Telecom" as devino

left to right direction

actor client

client --> smstraffic : smpp 50%

client --> devino : smpp 50%

smstraffic --> tele2

smstraffic --> mts $CLR_MTS_1

smstraffic --> megafon $CLR_MEGAFON_1

smstraffic --> beeline $CLR_BEELINE_1

devino --> tele2

devino --> mts $CLR_MTS_1

devino --> megafon $CLR_MEGAFON_1

devino --> beeline $CLR_BEELINE_1

@enduml

----

== Подключение

Для подключения библиотеки необходимо либо скачать библиотеку и использовать с локальной файловой системы или импортировать по URL.

.Пример подключения библиотеки по URL

[source,puml]

----

!include https://raw.githubusercontent.com/wizardjedi/a1s-plantuml-lib/master/a1s-lib.puml

----

WARNING: PlantUML имеет ограничения безопасности по импорту библиотек по URL. Настройки безопасности описаны на соответствующзей странице https://plantuml.com/security

=== Пример подключения для Confluence

Плагин PlantUML для Confluence может загружать файлы из приложений к страницам ( https://avono-support.atlassian.net/wiki/spaces/PUML/pages/9699367/Macro+plantuml ).

Для Confluence алгоритм подключения будет таким:

* Скачиваем файл с описанием библиотеки https://raw.githubusercontent.com/wizardjedi/a1s-plantuml-lib/master/a1s-lib.puml

* Для корневой (или какой-то другой страницы) добавляем файл `a1s-lib.puml` в приложения (attachment)

* В тексте диаграммы подключаем данный файл с помощью синтаксиса включения

+

----

^attachment.ext

pagetitle

pagetitle^attachment.ext

spacekey:pagetitle

spacekey:pagetitle^attachment.ext

----

Например, для пространства `superspace` и страницы `Space Home`.

[source,puml]

----

...

!include superspace:Space home^a1s-lib.puml

...

----

== Системные переменные

.Системные переменные

[%header]

|===

|Переменная|Описание

m|`$A1S_LIB_VERSION` |Текущая версия библиотеки (например, `1.0.0`)

|===

== Цвета

Для использования на диаграммах были выделены базовые цвета и дополнительно созданы оттенки данных базовых цветов для использования.

Для всех цветов дейсвтую следующие правила:

* Переменная цвета начинается с префикса `CLR_` (например, `CLR_BLUE` - синий цвет)

* Для оттенков используются суффиксы с насыщенностью от 100(светлый) до 900(тёмный) (базовый цвет имеет насущенность 500) (например, `CLR_ORANGE_100` - самый светлый из оранжевых оттенков)

.Базовые цвета

[%header]

|===

|Переменная|Значение|Описание

|`$CLR_RED`|`#d60f0f`|Красный

|`$CLR_BLUE`|`#1053b0`|Синий

|`$CLR_GREEN`|`#37750b`|Зелёный

|`$CLR_ORANGE`|`#fe6300`|Оранжевый

|`$CLR_YELLOW`|`#fffb16`|Жёлтый

|`$CLR_PURPLE`|`#7a0f91`|Фиолетовый

|`$CLR_BROWN`|`#4b1414`|Коричневый

|`$CLR_GRAY`|`#acacac`|Серый

|`$CLR_BLACK`|`#000000`|Чёрный

|`$CLR_WHITE`|`#FFFFFF`|Белый

|`$CLR_LIGHTBLUE`|`#67a7ff`|Голубой

|`$CLR_PINK`| `#fe59db`|Розовый

|===

.Палитра цветов

image::_images/img-color-palette.png[]

.Цвета в PlantUML

image::_example/colors.png[]

=== Специальные цвета

В диаграммах (особенно даиграммах последовталеьностей) часто используются альтернативные ветки исполнения. Например, успешны сценарий, ошибочный, некоторое количество алтернатив и исключения.

Для данных сценариев добавлены специальные переменные для указания цветов:

[%header]

|====

|Переменная|Описание

|`$CLR_SUCCESS`|Успешно

|`$CLR_ERROR`|Ошибка

|`$CLR_ALT`|Альтернатива

|`$CLR_EXCEPTION`|Исключение

|====

.Пример использования специальных цветов для веток исполнения

image::_example/special-colors.png[]

.Пример использования специальных цветов

[source,puml]

----

...

alt $CLR_SUCCESS Успешная отправка

    a1s --> viber : Отправка сообщения

else $CLR_ALT Альтернативный сценарий

    a1s --> whatsapp : Отправка сообщения

else $CLR_ERROR Ошибка отправки

    a1s --x viber : Ошибка отправки

    a1s --> whatsapp : Переотправка сообщения

else $CLR_EXCEPTION Режим аварии

    a1s --> telegram : Уведомление группы мониторинга

end

...

----

=== Корпоративные цвета

Для логотипов компаний и сервисов были выделены корпоративные или цвета бренда. Такие цвета записаны в переменных вида `$CLR__<НОМЕР>` (например, `$CLR_TELE2_1`).

[%header]

|===

|Переменная|Значение|Описание

m|$CLR_T2_1 m|#000000|Т2 РФ

m|$CLR_T2_2 m|#ffffff|Т2 РФ

m|$CLR_T2_3 m|#ff3495|Т2 РФ

m|$CLR_T2_4 m|#a7fc00|Т2 РФ

m|$CLR_T2_5 m|#0000ff|Т2 РФ

m|$CLR_T2_6 m|#00bfff|Т2 РФ

|`$CLR_MEGAFON_1`|`#00b956`|Мегафон РФ

|`$CLR_MEGAFON_2`|`#731982`|Мегафон РФ

|`$CLR_MTS_1`|`#cc061a`|МТС РФ

|`$CLR_BEELINE_1`|`#ffcc00`|Билайн(Вымпелком) РФ

|`$CLR_BEELINE_2`|`#13171b`|Билайн(Вымпелком) РФ

|`$CLR_YOTA_1`|`#00aeef`|Йота РФ

|`$CLR_MOTIV_1`|`#fa6600`|Мотив РФ/Екатеринбург-2000

|`$CLR_ROSTELECOM_1`|`#7700ff`|Ростелеком

|`$CLR_ROSTELECOM_2`|`#ff4f12`|Ростелеком

|`$CLR_DEVINO_1`|`#717fff`|Девино телеком

|`$CLR_SMSTRAFFIC_1`|`#004b93`|СМС Траффик

|`$CLR_EDNA_1`|`#00ea43`|ОСК/Эдна

|`$CLR_A1S_1`|`#dc220b`|А1 Системс

|`$CLR_A1S_2`|`#2c2f30`|А1 Системс

|`$CLR_PROTEY_1`|`#009cf7`|НТЦ Протей

|`$CLR_BERKUT_1`|`#2070FD`|Беркут

|`$CLR_VIBER_1`|`#7360f2`|Viber/Вайбер

|`$CLR_WHATSAPP_1`|`#075E54`|WhatsApp

|`$CLR_WHATSAPP_2`|`#25D366`|WhatsApp

|`$CLR_TELEGRAM_1`|`#24A1DE`|Telegram

|`$CLR_SKYPE_1`|`#00AFF0`|Skype

|`$CLR_ZOOM_1`|`#0B5CFF`|Zoom

|`$CLR_TELE2_1`|`#1f2229`|Теле2 РФ

|`$CLR_TELE2_2`|`#ff59a3`|Теле2 РФ

|`$CLR_TELE2_3`|`#00b4ee`|Теле2 РФ

|`$CLR_TELE2_4`|`#c882ff`|Теле2 РФ

|===

.Таблица корпоративных цветов для иллюстрации

image::_example/corporate-colors.png[]

WARNING: Цвета были получены из открытых источников. В частности с корпоративных сайтов с использованием инструмента CSS Overview из Chrome Developer Tools.

=== Градиенты

Библиотека содержит переменные с градиентами, которые начинаются с префикса `GRD_CLR_`.

[%header]

|===

|Переменная|Описание

|`$GRD_CLR_RED`|Красный градиент

|`$GRD_CLR_BLUE`|Синий градиент

|`$GRD_CLR_GREEN`|Зелёный градиент

|`$GRD_CLR_ORANGE`|Оранжевый градиент

|`$GRD_CLR_YELLOW`|Жёлтый градиент

|`$GRD_CLR_PURPLE`|Фиолетовый градиент

|`$GRD_CLR_BROWN`|Коричневый градиент

|`$GRD_CLR_GRAY`|Серый градиент

|`$GRD_CLR_LIGHTBLUE`|Голубой градиент

|`$GRD_CLR_PINK`|Розовый градиент

|`$GRD_CLR_DARK_RED`|Тёмный красный градиент

|`$GRD_CLR_DARK_BLUE`|Тёмный синий градиент

|`$GRD_CLR_DARK_GREEN`|Тёмный зелёный градиент

|`$GRD_CLR_DARK_ORANGE`|Тёмный оранжевый градиент

|`$GRD_CLR_DARK_YELLOW`|Тёмный жёлтый градиент

|`$GRD_CLR_DARK_PURPLE`|Тёмный фиолетовый градиент

|`$GRD_CLR_DARK_BROWN`|Тёмный коричневый градиент

|`$GRD_CLR_DARK_GRAY`|Тёмный серый градиент

|`$GRD_CLR_DARK_LIGHTBLUE`|Тёмный голубой градиент

|`$GRD_CLR_DARK_PINK`|Тёмный розовый градиент

|===

image::_example/gradients.png[]

Переменную `$GRD_CLR_BG_PRIMARY` пользователь может определить до включения библиотеки для переопределения фона по умолчанию для компонентов диаграмм.

== Спрайты

.Пример использования спрайтов

----

card "<$beeline>" as beeline

rectangle "<$megafon,scale=0.5,color=$CLR_MEGAFON_1>" as megafon $CLR_MEGAFON_2

----

* Спрайты разбиты на группы

** `messengers` - мессенджеры

** `mobile-operators` - логотипы мобильных операторов

** `sms-agregators` - логотипы СМС-агрегаторов

** `vendors` - вендоры

* Для спрайтов приняты следюущие размеры, которые оформляются в виде суффиксов к имени файла

** `_s` - маленький, только логотип, размер `128px x 128px` (пример, `<$megafon_s>`)

** `_l` - большой, логотип с названием, максимальный размер по ширине `300px` (пример, `<$motiv_l>`)

* Исходные изображения для спрайтов сохранены в директориях `src` соответствующей директории с категориями

=== Вендоры

[%header]

|===

|Спрайт|Изображение|Размеры

|`<$a1s_l>` a|image::vendors/a1s_l.png[] | 300x105

|`<$a1s_s>` a|image::vendors/a1s_s.png[] | 128x128

|`<$protey_l>` a|image::vendors/protey_l.png[] | 300x105

|`<$protey_s>` a|image::vendors/protey_s.png[] | 128x128

|`<$berkut_l>` a|image::vendors/berkut_l.png[] | 300x105

|`<$berkut_s>` a|image::vendors/berkut_s.png[] | 128x128

|===

=== Мобильный операторы РФ

[%header]

|===

|Спрайт|Изображение|Размеры

|`<$beeline_l>` a|image::mobile-operators/beeline_l.png[]| 300x63

|`<$beeline_s>` a|image::mobile-operators/beeline_s.png[]| 128x128

|`<$megafon_l>` a|image::mobile-operators/megafon_l.png[]| 300x54

|`<$megafon_s>` a|image::mobile-operators/megafon_s.png[]| 128x128

|`<$motiv_l>` a|image::mobile-operators/motiv_l.png[]| 300x56

|`<$motiv_s>` a|image::mobile-operators/motiv_s.png[]| 128x128

|`<$mts_l>` a|image::mobile-operators/mts_l.png[]| 300x300

|`<$mts_s>` a|image::mobile-operators/mts_s.png[]| 128x128

|`<$rostelecom_l>` a|image::mobile-operators/rostelecom_l.png[]| 300x77

|`<$rostelecom_s>` a|image::mobile-operators/rostelecom_s.png[]| 128x128

|`<$sbermobile_l>` a|image::mobile-operators/sbermobile_l.png[]| 300x39

|`<$sbermobile_s>` a|image::mobile-operators/sbermobile_s.png[]| 128x128

|`<$t2_l>` a|image::mobile-operators/t2_l.png[]| 300x300

|`<$t2_s>` a|image::mobile-operators/t2_s.png[]| 128x128

|`<$tinkoff_l>` a|image::mobile-operators/tinkoff_l.png[]| 300x92

|`<$tinkoff_s>` a|image::mobile-operators/tinkoff_s.png[]| 136x128

|`<$yota_l>` a|image::mobile-operators/yota_l.png[]| 300x95

|`<$yota_s>` a|image::mobile-operators/yota_s.png[]| 128x128

|===

.Старые версии логотипов

[%header]

|===

|Спрайт|Изображение|Размеры|Дата смены

|`<$tele2_l>` a|image::mobile-operators/tele2_l.png[]| 300x118 | 2024-12-31

|`<$tele2_s>` a|image::mobile-operators/tele2_s.png[]| 128x128 | 2024-12-31

|===

=== SMS-агрегаторы РФ

[%header]

|===

|Спрайт|Изображение|Размеры

|`<$devino_l>` a|image::sms-agregators/devino_l.png[] |300x115

|`<$devino_s>` a|image::sms-agregators/devino_s.png[] |128x128

|`<$edna_l>` a|image::sms-agregators/edna_l.png[] |300x93

|`<$edna_s>` a|image::sms-agregators/edna_s.png[] |128x128

|`<$rapporto_l>` a|image::sms-agregators/rapporto_l.png[] |300x77

|`<$rapporto_s>` a|image::sms-agregators/rapporto_s.png[] |128x128

|`<$smstraffic_l>` a|image::sms-agregators/smstraffic_l.png[] |300x50

|`<$smstraffic_s>` a|image::sms-agregators/smstraffic_s.png[] |128x128

|===

=== Instant Messengers

[%header]

|===

|Спрайт|Изображение|Размеры

|`<$skype_s>` a|image::messengers/skype_s.png[] | 128x128

|`<$telegram_s>` a|image::messengers/telegram_s.png[] | 128x128

|`<$viber_s>` a|image::messengers/viber_s.png[] | 128x128

|`<$whatsapp_s>` a|image::messengers/whatsapp_s.png[] | 128x128

|`<$zoom_s>` a|image::messengers/zoom_s.png[] | 128x128

|===

== Сборка

Базой для сборки библиотеки является метаописание компонентов в виде JSON объектов. Мета описание располагается в файле `meta.json`.

Для сборки используется PHP-скрипт, который собирает библиотеку из составных частей.

.Сборка из командной строки

[source,shell]

----

$ php build.php

----

.Сборка в Docker-контейнере

[source,shell]

----

$ docker run --rm -it ..... build.php

----

== Общий алгоритм к созданию спрайтов

. Находим необходимый спрайт, например, на сайте компании

. Копируем логотип и открываем в графикческом редакторе

.. Если логотип прозрачный, то добавляем слой с белым фоном и объединяем слои

. Переводим изображение в оттенки серого

. Переходим в настройку уровней (Levels)

. Переводим ползунок в крайнеправое положение для получения чёрного цвета

.. В случае, если логотип содержим какие-то переходы, то можно переводить ползунок цвета в такое положение, при котором сохраняются переходы

. Масштабируем изображение до размеров (`300` по ширине для длинных логотипов и `128x128` для иконок)

. Сохраняем изображение в соответствующий файл `.png`

. Используем команду для обработки спрайтов

+

[source,shell]

----

$ java -jar plantuml.jar -encodesprite 16z supersprite_l.png

sprite $supersprite_l [300x105/16z] {

...

}

----

. Полученный вывод (`sprite $supersprite ...`) добавляем в файл `.puml`

[appendix]

== Частые вопросы

[qanda]

Почему картинки чёрные?:: Это связано с ограничениями PlantUML. На текущий момент можно использовать только спрайты в виде монохромных изображений, переведённые в текстовое описание см. https://plantuml.com/sprite

+

Такое тектсовое описание позволяет встраивать изображения в текст диаграммы и не требует наличия доступных ресурсов во вне.

А если у меня есть доступные внешние ресурсы по ссылке?:: В случае, если есть доутпные по ссылке или в файловой системе ресурсы, то можно воспользоваться форматированием creole

+

[source,puml]

----

'Можно использовать  или  для использоания ВНЕШНИХ изображений

rectangle "" as r3

----

[appendix]

== Известные проблемы и ограничения