Глоссарий {domain}.{entity}.{action}

1. Общие принципы формирования словаря

Общие принципы для каждого компонента:

• {domain} (Домен): Определяет широкую бизнес-область или функциональный сервис системы. Соответствует одному из ключевых сервисов, предоставляемых платформой.
• {entity} (Сущность): Определяет основной объект, над которым выполняется действие внутри домена. Сущность должна быть существительным.
• {action} (Действие): Определяет, что происходит с сущностью.
  • Для команд (commands) используется инфинитив или повелительное наклонение (например, calculate, solve, process), так как команда является приказом к выполнению действия.
  • Для событий (events) используется глагол в прошедшем времени (например, calculated, solved, processed, failed), так как событие сообщает о факте, который уже произошел.

2. Домены ({domain})

Домен определяет высокоуровневую бизнес-область или функциональную возможность системы.

Значение	Описание
system	Системный домен. Связан с жизненным циклом, мониторингом и конфигурацией самой системы, а не с бизнес-логикой.
geocoding	Геокодирование. Преобразование текстовых адресов в географические координаты (прямое) и наоборот (обратное).
geosearch	Геопоиск. Поиск географических объектов, организаций, топонимов по текстовому запросу или координатам. В отличие от геокодинга, ориентирован на поиск, а не на точное преобразование.
geosuggest	Поисковые подсказки. Предоставление вариантов завершения адреса или названия объекта по мере ввода пользователем.
geospatial	Пространственные вычисления. Выполнение операций с геоданными, таких как проверка пересечения координат с полигонами, определение нахождения точки в зоне и т.п.
isochrone	Изохроны. Построение областей достижимости из заданной точки за определенное время или расстояние.
distancematrix	Матрицы расстояний. Расчет матриц времени и расстояний между множеством точек. Обычно это "тяжелые", ресурсоемкие задачи.
routing	Простая маршрутизация. Построение оптимального маршрута между двумя точками (A -> B).
vrp	Планирование маршрутов (VRP). Решение оптимизационной задачи маршрутизации для группы выездных сотрудников (Vehicle Routing Problem).
enrichment	Обогащение данных. Добавление к существующим гео-объектам дополнительных данных или метаданных из внешних или внутренних источников.
mapdata	Управление картографическими данными. Создание, редактирование и управление геослоями и другими картографическими элементами (например, базовыми картами, стилями).
notification	Нотификации. Отправка технических или бизнес-уведомлений пользователям или во внешние системы. Не путать с бизнес-событиями (events).

3. Сущности ({entity})

Сущность — это основной объект, над которым выполняется действие в рамках домена. Сущность не должна дублировать домен.

Значение	Описание	Применимые домены
address	Адрес. Сущность, представляющая структурированный или неструктурированный адрес для прямого геокодирования.	geocoding
coordinates	Координаты. Сущность, представляющая географические координаты (широта, долгота) для обратного геокодирования.	geocoding
query	Запрос. Сущность, представляющая поисковый запрос в свободной форме.	geosuggest, geosearch
calculation	Задача на расчет. Детерминированная задача, имеющая однозначный результат на основе входных данных (например, построение изохроны, маршрута, определение пересечения с полигоном).	isochrone, routing, geospatial
job	Пакетная задача. "Тяжелая" или долго выполняющаяся задача по обработке большого объема данных, например, построение матрицы расстояний для 1000x1000 точек.	distancematrix
solution	Задача на оптимизацию. Сложная задача, требующая поиска оптимального решения из множества возможных вариантов (например, VRP).	vrp
route	Маршрут. Сущность, представляющая результат построения маршрута.	routing
geolayer	Геослой. Сущность, представляющая собой набор сгруппированных географических объектов (точек, линий, полигонов), управляемых как единое целое.	mapdata
grid	Опорная сетка. Сущность, представляющая собой набор предварительно рассчитанных точек, используемых для оптимизации, анализа или индексации в других сервисах (например, в VRP).	mapdata
geodata	Геоданные. Обобщенная сущность для геоданных (объект, полигон, точка), когда требуется обогащение или CRUD-операции.	enrichment
metadata	Метаданные. Сущность для управления мета-информацией, привязанной к гео-объектам.	enrichment
message	Сообщение. Сущность, представляющая сообщение для отправки (email, SMS, push).	notification
configuration	Конфигурация. Параметры конфигурации сервиса или системы в целом.	system

4. Действия ({action})

{action} — это:

1. Для команд (commands): используется глагол в повелительном наклонении. Команда — это приказ.
2. Для событий (events): используется причастие прошедшего времени (Past Participle). Событие — это свершившийся факт.

Значение	Тип	Принцип выбора	Описание	Примеры использования ({domain}.{entity}.{action})
process	Команда	Преобразование	Запустить стандартизированный процесс преобразования данных из одного формата в другой (например, геокодирование).	geocoding.address.process, geosearch.query.process
processed	Событие		Факт того, что данные были успешно преобразованы.	geocoding.address.processed, geosearch.query.processed
calculate	Команда	Детерминированный расчет	Запустить детерминированный расчет, который всегда дает одинаковый результат для одинаковых входных данных (построить изохрону, матрицу, маршрут).	isochrone.calculation.calculate, routing.calculation.calculate
calculated	Событие		Факт того, что результат успешно вычислен.	isochrone.calculation.calculated, routing.calculation.calculated
solve	Команда	Оптимизация / Пакетная задача	Запустить решение сложной оптимизационной или ресурсоемкой пакетной задачи, которая может иметь несколько вариантов решения или требовать итеративного подхода.	vrp.solution.solve, distancematrix.job.solve
solved	Событие		Факт того, что задача успешно решена.	vrp.solution.solved, distancematrix.job.solved
enrich	Команда	Обогащение	Запустить процесс обогащения сущности дополнительными данными.	enrichment.geodata.enrich
enriched	Событие		Факт того, что сущность была успешно обогащена.	enrichment.geodata.enriched
notify	Команда	Внешнее уведомление	Отправить уведомление по внешнему каналу: email, push, telegram и т.д. (не по Kafka).	notification.message.notify
notified	Событие		Факт того, что уведомление было успешно отправлено.	notification.message.notified
create	Команда	CRUD: Создание	Создать новую долгоживущую сущность (например, метаданные для гео-объекта).	enrichment.metadata.create, mapdata.geolayer.create
created	Событие		Факт того, что сущность была успешно создана.	enrichment.metadata.created, mapdata.geolayer.created
update	Команда	CRUD: Изменение	Обновить существующую долгоживущую сущность.	system.configuration.update, mapdata.geolayer.update
updated	Событие		Факт того, что сущность была успешно обновлена.	system.configuration.updated, mapdata.geolayer.updated
delete	Команда	CRUD: Удаление	Удалить долгоживущую сущность.	enrichment.metadata.delete, mapdata.geolayer.delete
deleted	Событие		Факт того, что сущность была успешно удалена.	enrichment.metadata.deleted, mapdata.geolayer.deleted
add	Команда	Добавление в коллекцию	Добавить новые элементы к существующей сущности-коллекции, не изменяя существующие.	mapdata.grid.add
added	Событие		Факт того, что новые элементы были успешно добавлены.	mapdata.grid.added
publish	Команда	Публикация	Опубликовать сущность, сделав ее доступной для использования.	mapdata.geolayer.publish
published	Событие		Факт того, что сущность была успешно опубликована.	mapdata.geolayer.published
changed	Событие	Консолидация событий	Универсальное событие. Факт того, что состояние сущности изменилось. Используется для консолидации событий жизненного цикла (created, updated, deleted) в один топик.	mapdata.geolayer.changed
accepted	Событие	Быстрое подтверждение	Универсальное событие. Команда получена системой и принята в обработку. Отправляется как можно быстрее для асинхронного подтверждения.	vrp.solution.accepted, isochrone.calculation.accepted
failed	Событие	Невосстановимая ошибка	Универсальное событие. При обработке команды произошла невосстановимая ошибка.	vrp.solution.failed, isochrone.calculation.failed

Примечание: plan/planned можно считать синонимами calculate/calculated для домена routing. Для простоты лучше использовать один унифицированный глагол (calculate), если бизнес-логика не требует их разделения.

Что дальше?

1. Нашли эту статью полезной? Поделитесь ею и помогите распространить знания!
2. Нашли ошибку или есть идеи 💡 о том, что и как я могу улучшить? Напишите мне в Telegram.
3. Хотите узнать обо мне больше? Читайте здесь.