Глоссарий {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	Обогащение данных. Добавление к существующим гео-объектам дополнительных данных или метаданных из внешних или внутренних источников.
notification	Нотификации. Отправка технических или бизнес-уведомлений пользователям или во внешние системы. Не путать с бизнес-событиями (events).

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

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

Значение	Описание	Применимые домены
address	Адрес. Сущность, представляющая структурированный или неструктурированный адрес для прямого геокодирования.	geocoding
coordinates	Координаты. Сущность, представляющая географические координаты (широта, долгота) для обратного геокодирования.	geocoding
query	Запрос. Сущность, представляющая поисковый запрос в свободной форме.	geosuggest, geosearch
calculation	Задача на расчет. Детерминированная задача, имеющая однозначный результат на основе входных данных (например, построение изохроны, маршрута, определение пересечения с полигоном).	isochrone, routing, geospatial
job	Пакетная задача. "Тяжелая" или долго выполняющаяся задача по обработке большого объема данных, например, построение матрицы расстояний для 1000x1000 точек.	distancematrix
solution	Задача на оптимизацию. Сложная задача, требующая поиска оптимального решения из множества возможных вариантов (например, VRP).	vrp
route	Маршрут. Сущность, представляющая результат построения маршрута.	routing
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).	vrp.solution.solve, distancematrix.job.solve
solved	Событие	Задача успешно решена. Факт того, что оптимальное решение найдено.	vrp.solution.solved, distancematrix.job.solved
enrich	Команда	Запустить процесс обогащения сущности дополнительными данными.	enrichment.geodata.enrich
enriched	Событие	Факт того, что сущность была успешно обогащена.	enrichment.geodata.enriched
notify	Команда	Отправить уведомление.	notification.message.notify
notified	Событие	Факт того, что уведомление было успешно отправлено.	notification.message.notified
create	Команда	Создать новую долгоживущую сущность (например, метаданные для гео-объекта).	enrichment.metadata.create
created	Событие	Факт того, что сущность была успешно создана.	enrichment.metadata.created
update	Команда	Обновить существующую долгоживущую сущность.	system.configuration.update
updated	Событие	Факт того, что сущность была успешно обновлена.	system.configuration.updated
delete	Команда	Удалить долгоживущую сущность.	enrichment.metadata.delete
deleted	Событие	Факт того, что сущность была успешно удалена.	enrichment.metadata.deleted
accepted	Событие	Универсальное событие. Команда получена системой и принята в обработку. Отправляется как можно быстрее для асинхронного подтверждения.	vrp.solution.accepted, isochrone.calculation.accepted
failed	Событие	Универсальное событие. При обработке команды произошла невосстановимая ошибка. Содержит информацию о сбое.	vrp.solution.failed, isochrone.calculation.failed

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

Что дальше?

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