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

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

Планирование по локациям и посещениям

Планировать маршруты можно несколькими способами:

  1. Если все посещения локации одинаковые, достаточно на листе locations указать список локаций и для каждой локации задать параметры:

    В этом случае лист visits в файле планирования не нужен.

  2. Если у локаций есть разные типы посещений, которые нужно выполнять в определенной последовательности, их нужно настроить на листе visits. Сервисное время, штраф за непосещение и дни посещения указываются для типов посещений на листе visits, а временные окна, количество и частота посещений – для локации в целом на листе locations.

  3. Можно сочетать 1 и 2 способы: указывать типы посещений только для некоторых локаций, а для остальных — только параметры локаций.

Пример 1

2 сотрудника посещают 20 локаций. Для них на листе locations заданы сервисное время service_duration_s, дни для посещения allowed_days, preferred_days, mandatory_days и denied_days, штрафы за пропуск посещения penalty.visit_count.per_visit и за пропуск всех посещений penalty.drop.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Пример 2

То же, что в примере 1, но для всех локаций заданы типы посещений на листе visits. Для каждого типа посещения указаны сервисное время service_duration_s, дни для посещения allowed_days, preferred_days и denied_days, штраф за пропуск посещения drop.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Пример 3

То же, что в примере 1, но для локаций 1 и 3 заданы типы посещений на листе visits. Для всех остальных локаций типы посещений не заданы, и их параметры указаны только на листе locations.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Приоритеты локаций и посещений

Вы можете задать приоритеты посещения локаций следующими способами:

  • с помощью штрафов за пропуск посещений;
  • с помощью тегов.

Приоритеты с помощью штрафов

Для установки приоритетов локаций и посещений можно использовать штрафы за непосещение локаций и за пропуск отдельных типов посещений. Чем выше штраф, тем выше вероятность, что локация или посещение будут запланированы.

Можно использовать следующие параметры:

  • для локаций — на листе locations:

    • penalty.drop — фиксированный штраф, если не было запланировано ни одного посещения локации;
    • penalty.visit_count.fixed — фиксированный штраф, если пропущено хотя бы одно посещение локации;
    • penalty.visit_count.per_visit — штраф за каждое пропущенное посещение локации.

  • для отдельных типов посещений — на листе visits укажите значение параметра drop (locations.visits.N.drop в запросе API). Оно заменит значение penalty.visit_count.per_visit для посещений этого типа.

Подробнее о параметрах, которые используются при планировании посещений, см. в разделах Количество и частота посещений локации и Типы посещений.

Пример 1

В планировании участвуют 2 сотрудника, которым нужно посетить 32 локации с одинаковым приоритетом. При этом у каждой локации указано жесткое временное окно, поэтому опоздание или ранее посещение локаций не предусмотрено. Штраф за непосещение локаций penalty.drop = 0.

В результате планирования сотрудники ни разу не посещают локацию 3, а также пропускают несколько посещений локаций 1 и 7.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Пример 2

То же, что в примере 1, но у локации 3 высокий приоритет, поэтому для нее задан штраф penalty.drop = 1 000 000.

В результате планирования сотрудники посещают локацию 3, а посещения локаций 25 и 29 остаются нераспределенными.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Пример 3

То же, что в примере 1, но на листе visits заданы штрафы drop за пропуски различных типов посещений локации 1 в порядке убывания их приоритета:

  • 1 000 000 — инвентаризация;
  • 500 000 — установка рекламы;
  • 100 000 — раскладка товаров.

В результате запланированы все локации и посещения, кроме двух посещений для раскладки товаров в локации 1.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Приоритеты с помощью тегов

Вы можете задать приоритет посещения локации с помощью опциональных тегов. Для этого на листе locations в поле optional_tags.0.tag задайте название тега, а в поле optional_tags.0.value — его вес (больше нуля). Чем больше вес тега, тем с большей вероятностью посещение этих локаций будет запланировано.

Пример

Двум сотрудникам нужно посетить 49 локаций. 8 локаций помечены опциональным тегом VIP с весом 3000.

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

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Посещение удаленно расположенных локаций

Одна или несколько локаций могут располагаться далеко от остальных. В этом случае стоимость посещения локации может оказаться выше, чем штраф за непосещение или пропуск одного из посещений. Локация окажется нераспределенной. Чтобы избежать этого, для удаленных локаций на листе locations можно назначать более высокие штрафы:

  • penalty.visit_count.per_visit — за пропуск одного посещения локации;
  • penalty.drop — за пропуск всех посещений.

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

Пример 1

Два сотрудника посещают 18 локаций. Одна из локаций (Location 2) — удаленная. Штраф за непосещение локации drop для всех локаций равен 1000, штраф за пропуск посещения penalty.visit_count.per_visit — 17. Стоимость выхода сотрудника на работу cost.fixed по умолчанию равна 3000 — это больше, чем суммарный штраф за непосещение локации. В результате удаленная локация оказалась нераспределенной.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Пример 2

То же, что в примере 1, но для удаленной локации штраф за пропуск посещения penalty.visit_count.per_visit увеличен до 3500 — больше стоимости выхода сотрудника на работу. В результате второй сотрудник выходит на работу в отдельные дни специально для посещения удаленной локации.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Планирование с учетом навыков сотрудников

Иногда для посещения локации требуются специальные навыки или оборудование. Чтобы запланировать маршруты с учетом этих требований, используйте теги локаций и сотрудников.

На листе locations в поле required_tags перечислите через запятую теги, определяющие обязательные требования для посещения локации. Желательные требования указываются в полях optional_tags.N.tag и optional_tags.N.value, подробнее см. в разделе Теги локаций.

Если сотрудник соответствует требованиям, заданным для локаций, то на листе employees в поле tags перечислите соответствующие теги. Если сотрудник не должен посещать локации с определенными тегами, укажите их в поле excluded_tags. Подробнее см. в разделе Теги сотрудника.

Пример

Для посещения некоторых локаций требуется спецодежда или наличие сумки-холодильника у сотрудника. У таких локаций в поле required_tags указаны теги uniform и fridge. Локации 7 и 12 желательно посещать сотрудникам с фармакологическим образованием, поэтому у них указан опциональный тег pharmacy. Сотрудник 1 не имеет соответствующего образования, поэтому для него тег pharmacy указан в поле excluded_tags.

В результате планирования локации со специальными требованиями распределены по сотрудникам с соответствующими тегами. Сотрудник 1 посещает локации, у которых нет опционального тега pharmacy.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Кучные маршруты

Чтобы сотрудники затрачивали меньше времени на перемещение между локациями, планируйте маршруты, в которых локации расположены как можно ближе друг к другу. Это можно сделать двумя способами:

  • с помощью параметров кучности global_proximity_factor и daily_proximity_factor;
  • с помощью ограничений на отрезки маршрута и использования коэффициентов для начальных и конечных отрезков.

Параметры кучности

Чтобы сотрудники посещали близко расположенные локации последовательно, используйте следующие параметры:

  • global_proximity_factor — параметр кучности для всего периода планирования;
  • daily_proximity_factor — параметр кучности в течение дня.

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

Параметры кучности могут принимать значение от 0 до 10, где 0 — отсутствие кучности, а 10 — максимальная кучность. Мы рекомендуем значения от 0 до 1 (по умолчанию 0).

Подробнее см. в разделе Кучность маршрутов.

Пример

Локации расположены преимущественно в центре, на севере и на юге города. Чтобы маршруты получились более кучными, заданы параметры global_proximity_factor = 0.2 и daily_proximity_factor = 0.5.

В результате маршруты сотрудников получились географически сгруппированными.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Ограничения на отрезки маршрута

Вы можете задать ограничения на расстояние между соседними локациями или время перемещения между ними на листе employees с помощью параметров max_edge_distance_m и max_edge_duration_s соответственно. Чтобы алгоритм учитывал начальные и конечные отрезки маршрута по особой стоимости, укажите для них положительные коэффициенты в полях first_edges_penalty_factor и last_edges_penalty_factor для пробега на первом и последнем отрезках маршрута соответственно.

Подробнее см. в разделах Ограничения на отрезки маршрута и Начальные и конечные отрезки маршрута.

Пример

Локации расположены преимущественно в центре, на севере и на юге города. Задано ограничение на максимальное расстояние между соседними локациями — 15 000 м. Также указаны повышающие коэффициенты first_edges_penalty_factor и last_edges_penalty_factor — 4.

В результате маршруты сотрудников получились географически сгруппированными.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Закрепление локации за сотрудником

Чтобы локацию всегда посещал определенный сотрудник, можно закрепить локацию за сотрудником одним из способов:

Закрепление локации с помощью тегов

Для сотрудника нужно задать уникальный тег на листе employees в поле tags. Для всех локаций, которые должны быть закреплены за данным сотрудником, этот тег нужно указать на листе locations в поле required_tags.

Пример

Посещения 50 локаций могут быть распланированы на 5 сотрудников. У локаций 40 и 50 в поле required_tags указан уникальный тег сотрудника employee3, этот же тег указан у сотрудника 3 в поле tags. В результате посещения локаций 40 и 50 запланированы этому сотруднику.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Закрепление локации с помощью геозон

Если за сотрудником нужно закрепить все локации, расположенные в определенном районе города, можно использовать разрешенные и запрещенные геозоны.

Чтобы посещать локации в геозоне мог только определенный сотрудник, на листе employees укажите название геозоны:

  • для выбранного сотруднка – в поле allowed_zones;
  • для остальных сотрудников – в поле forbidden_zones.

Добавлять новые геозоны можно через интерфейс и API.

Пример

Посещения 50 локаций могут быть распланированы на 5 сотрудников. Геозона North включает локации, расположенные на севере Москвы. Эта геозона указана для сотрудника 2 в поле allowed_zones, а для остальных сотрудников — в поле forbidden_zones. В результате посещения всех локаций, расположенных внутри геозоны North, запланированы сотруднику 2.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Балансировка нагрузки

При планировании распределение локаций между сотрудниками не всегда происходит равномерно. Чтобы распределить нагрузку поровну между сотрудниками, используйте параметры балансировки:

  1. Добавьте на лист locations поле shipment_size.units – оценка трудозатрат на одно посещение локации. Трудозатраты оцениваются в условных единицах – юнитах.

    Примечание

    Если время обслуживания service_duration_s для разных локаций различается, то оценка трудозатрат shipment_size.units должна быть пропорциональна service_duration_s. Например, если для локации service_duration_s = 1800 и shipment_size.units = 10, то для service_duration_s = 3600 значение shipment_size.units должно составлять 20.

  2. Для каждой локации умножьте shipment_size.units на visit_count. Вы получите оценку трудозатрат на все посещения локации в периоде планирования.

  3. Просуммируйте значения для всех локаций. Сумму поделите на количество дней в периоде планирования (лист options, поле planning_days). Получится оценка трудозатрат на все посещения локаций в день.

  4. Общую дневную оценку трудозатрат разделите на количество сотрудников. Это будет средняя нагрузка на сотрудника в день.

  5. Полученную среднюю нагрузку округлите в бо́льшую сторону с запасом, прибавив еще 5-10 юнитов. Например, если вы получили значение 19,35, округлите его до 20 и добавьте запас в 10 юнитов. Итого – 30 юнитов. Добавьте на лист employees поле capacity.units и для всех сотрудников укажите рассчитанное значение.

  6. На листе employees для каждого сотрудника укажите стоимость дня простоя – cost.empty_run, чтобы алгоритм при планировании задействовал всех сотрудников. Например, cost.empty_run = 100 000.

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

Пример 1

Посещения 20 локаций должны быть распланированы на 3 сотрудников. Параметры балансировки не задаются. В результате посещения всех локаций распределяются на сотрудника 2. Сотрудники 1 и 3 остаются незадействованными.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Пример 2

Тот же, что в примере 1, но задаются параметры балансировки.

Трудозатраты для одного посещения локации оценены в 10 юнитов, это значение указано на листе locations в поле shipment_size.units. Для каждой локации планируется по 2 посещения, visit_count = 2.

Общая оценка трудозатрат для всех 20 локаций составляет (10 * 2) * 20 = 400. Эта оценка делится на количество дней в периоде планирования: 400 : 7 = 57,14.

Дневная нагрузка распределяется на 3 сотрудников: 57,14 : 3 = 19,05. Значение округлено и увеличено на 10 – до 30 юнитов. Эта оценка указана для каждого сотрудника на листе employees в поле capacity.units. Также для каждого сотрудника задана стоимость дня простоя cost.empty_run = 10 000.

В результате посещения всех локаций распределены равномерно между тремя сотрудниками.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Допланирование

Допланирование — это добавление локаций и посещений в спланированный ранее маршрут. Необходимость в допланировании возникает, например, в следующих случаях:

  • сотрудникам были заранее запланированы маршруты и период планирования уже начался, но позднее возникла необходимость распределить дополнительные локации и посещения;
  • у сотрудников есть постоянные маршруты на неполный рабочий день, и к ним могут добавляться дополнительные локации и посещения.

Примечание

Допланирование выполняется только с помощью запросов API, при работе с файлами Excel допланирование не поддерживается.

Как реализовать сценарий:

На первой итерации выполняется планирование маршрутов для начального набора локаций. В ответе API для каждого сотрудника возвращается объект route с запланированным маршрутом на день.

На следующей итерации планирования в запросе API в объекте locations передается дополненный список локаций (локации с предыдущей итерации планирования и новые). В массиве initial_routes для каждого сотрудника передаются запланированные ранее маршруты на день — route из ответа на предыдущий запрос API.

В запланированном маршруте обязательно должны быть указаны поля route, employee_id и day (в поле day указывается номер дня, в который совершается маршрут; дни нумерются с 0). В описании точки node необходимо указать поле id, тип точки можно не указывать.

Пример initial_routes с минимальным набором параметров
"initial_routes": [
    {
        "route": [
            {
                "node": {
                    "value": {
                        "id": "location1"
                    }
                }
            },
            {
                "node": {
                    "value": {
                        "id": "location2"
                    }
                }
            },
            ...
        ],
        "employee_id": "employee",
        "day": 0
    }
]

Фиксация маршрутов

При допланировании прежние маршруты могут быть перестроены — в них могут быть добавлены новые локации, изменены посещения локаций, локации могут быть перенесены в нераспределенные. Если нужно сохранить прежние маршруты без изменений, при допланировании их можно фиксировать.

  • Чтобы зафиксировать решение целиком, установите значение true для параметра options.fixed. В этом случае в новом решении ни один из запланированных ранее маршрутов не будет изменен, добавленные локации и посещения будут помещены в новые маршруты.

  • Чтобы зафиксировать маршрут сотрудника, установите значение true в параметре initial_routes.N.fixed для этого маршрута. Маршрут можно зафиксировать только целиком — запланированные ранее посещения и их последовательность. При допланировании новые посещения не будут добавляться в маршрут.

    Фиксированные маршруты должны стоять подряд в начале массива initial_routes. Если между этими маршрутами есть пропущенные пустые дни, в которые сотрудник не совершает поездок, они тоже будут зафиксированы, и останутся неиспользованными в итоговом решении.

  • Чтобы зафиксировать отдельные посещения, можно установить значение true для параметров:

    • initial_routes.route.node.value.fixed_employee — посещение закрепляется за сотрудником, но может быть перенесено на другой день или стать нераспределенным. Все посещения локации можно закреплять только за одним сотрудником.
    • initial_routes.route.node.value.fixed_day — посещение не может быть перенесено на другой день, но может быть передано другому сотруднику или стать нераспределенным.
    • initial_routes.route.node.value.undropable — посещение не может быть перенесено в нераспределенные, но может быть передано другому сотруднику или перенесено на другой день.

    Перечисленные выше параметры можно комбинировать. Последовательность посещений зафиксировать с помощью этих параметров нельзя.

Пример для запроса API

На предыдущей итерации были запланированы маршруты на 8 дней. Маршруты в дни с 0 по 5 необходимо зафиксировать. При этом дни 0, 1, 3 и 4 останутся неиспользованными, так как находятся между зафиксированными маршрутами. Маршруты в последующие дни могут быть изменены.

"initial_routes": [
    {
        "route": [
			...
        ],
        "employee_id": "employee",
        "day": 2,
        "fixed": true
    },
    {
        "route": [
			...
        ],
        "employee_id": "employee",
        "day": 5,
        "fixed": true
    },
    {
        "route": [
			...
        ],
        "employee_id": "employee",
        "day": 7
    },
    ...
]

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

Для локаций можно задать обязательное время посещения в полях actual_arrival_time_s, actual_service_start_time_s и actual_departure_time_s. Эти посещения будут обязательно запланированы. При невозможности составить такие маршруты решение не будет создано, запрос вернет ошибку.

Обязательное время посещения можно указывать только для локаций в зафиксированных маршрутах. При этом если обязательное время посещения указано для одной локации в маршруте, оно должно быть указано и для остальных локаций в этом маршруте. Маршруты, в которых указано обязательное время посещения локаций, должны стоять подряд в начале массива initial_routes.

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

Также для локаций можно задать рекомендуемое время для посещения в полях arrival_time_s и departure_time_s. Эти условия будут выполнены по возможности.

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

Пример для запроса API
"initial_routes": [
    {
        "route": [
            {
            	"arrival_time_s": 25000,
                "departure_time_s": 26000,
                "actual_arrival_time_s": 26000,
                "actual_service_start_time_s": 26500,
                "actual_departure_time_s": 27000,
                "node": {
                    "value": {
                        "id": "location1"
                    }
                }
            }
        ],
        "employee_id": "employee",
        "day": 0
    }
]
Написать в службу поддержки
Предыдущая
Обработка ошибок
Следующая
Как учитываются пробки на дорогах
В этой статье: