README.md

Решение вступительного задания направление «Go»

Задание 1. REST API

В качестве базовой функциональности сервиса необходимо реализовать 7 базовых методов.

Для всех методов в случае корректного ответа ожидается ответ HTTP 200 OK.

POST /couriers

Для загрузки списка курьеров в систему запланирован описанный ниже интерфейс.

Обработчик принимает на вход список в формате json с данными о курьерах и графиком их работы.

Курьеры работают только в заранее определенных районах, а также различаются по типу: пеший, велокурьер и курьер на автомобиле. От типа зависит объем заказов, которые перевозит курьер. Районы задаются целыми положительными числами. График работы задается списком строк формата HH:MM-HH:MM.

Request

{
  "couriers": [
    {
      "courier_type": "FOOT",
      "regions": [
        0
      ],
      "working_hours": [
        "string"
      ]
    }
  ]
}

GET /couriers/{courier_id}

Возвращает информацию о курьере.

GET /couriers

Возвращает информацию о всех курьерах.

У метода есть параметры offset и limit, чтобы обеспечить постраничную выдачу. Если:

• offset или limit не передаются, по умолчанию нужно считать, что offset = 0, limit = 1;
• офферов по заданным offset и limit не найдено, нужно возвращать пустой список couriers.

POST /orders

Принимает на вход список с данными о заказах в формате json. У заказа отображаются характеристики — вес, район, время доставки и цена. Время доставки - строка в формате HH:MM-HH:MM, где HH - часы (от 0 до 23) и MM - минуты (от 0 до 59). Примеры: “09:00-11:00”, “12:00-23:00”, “00:00-23:59”.

Request

{
  "orders": [
    {
      "weight": 0,
      "regions": 0,
      "delivery_hours": [
        "string"
      ],
      "cost": 0
    }
  ]
}

GET /orders/{order_id}

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

GET /orders

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

У метода есть параметры offset и limit, чтобы обеспечить постраничную выдачу. Если:

• offset или limit не передаются, по умолчанию нужно считать, что offset = 0, limit = 1;
• офферов по заданным offset и limit не найдено, нужно возвращать пустой список orders.

POST /orders/complete

Принимает массив объектов, состоящий из трех полей: id курьера, id заказа и время выполнения заказа, после отмечает, что заказ выполнен.

Если заказ:

• не найден, был назначен на другого курьера или не назначен совсем — следует вернуть ошибку HTTP 400 Bad Request.
• выполнен успешно — следует выводить HTTP 200 OK и идентификатор завершенного заказа.

Обработчик должен быть идемпотентным.

Request

{
    "complete_info": [
        {
            "courier_id": 0,
            "order_id": 0,
            "complete_time": "2023-05-08T21:09:11.838Z"
        }
    ]
}

Задание 2. Рейтинг курьеров

Команда сервиса решила начать учет заработной платы и рейтинго курьеров. Для этого необходимо реализовать новый метод GET /couriers/meta-info/{courier_id}.

Параметры метода:

• start_date - дата начала отсчета рейтинга
• end_date - дата конца отсчета рейтинга.

Примером значения параметров может быть 2023-01-20. В задании можно полагаться на то, что все заказы и даты для расчетов имеют одну и ту же фиксированную временную зону - UTC.

Метод должен возвращать заработанные курьером деньги за заказы и его рейтинг.

Заработок рассчитывается по формуле:

Заработок рассчитывается как сумма оплаты за каждый завершенный развоз в период с start_date (включая) до end_date (исключая):

sum = ∑(cost * C)

C — коэффициент, зависящий от типа курьера:

• пеший — 2
• велокурьер — 3
• авто — 4

Если курьер не завершил ни одного развоза, то рассчитывать и возвращать заработок не нужно.

Рейтинг рассчитывается по формуле:

Рейтинг рассчитывается следующим образом: ((число всех выполненных заказов с start_date по end_date) / (Количество часов между start_date и end_date)) * C C - коэффициент, зависящий от типа курьера:

• пеший = 3
• велокурьер = 2
• авто - 1

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

Response

{
  "courier_id": 0,
  "courier_type": "FOOT",
  "regions": [
    0
  ],
  "working_hours": [
    "string"
  ],
  "rating": 0,
  "earnings": 0
}

Задание 3. Rate limiter

Каждый большой сервис с API, открытым из интернета, должен ограничивать количество входящих запросов. Для этого используется rate limiter. Вам нужно реализовать такое решение для разрабатываемого сервиса.

Для решения задачи можно написать собственную реализацию или использовать известное готовое решение. Сервис должен ограничивать нагрузку в 10 RPS на каждый эндпоинт. Если допустимое количество запросов превышено, сервис должен отвечать кодом 429.

Задание 4. Распределение заказов

Сейчас сервис Яндекс Лавка для каждого курьера выбирает один заказ. Это приводит к том, что курьер может быть не загружен или будет доставлять заказ по удаленному адресу. Перед началом рабочей смены сервис распределяет заказы между курьерами для минимизации стоимости доставки.

Для этого нам понадобятся реализовать:

• метод распределения заказов POST /orders/assign. В общем виде он будет выглядеть так: перед началом рабочего дня берем список заказов и распределяем их по доступным курьерам
• метод получения уже распределенных заказов GET /couriers/assignments

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

• вес заказа
• регион доставки
• стоимость доставки

Вес заказов

У каждой из категорий курьеров есть ограничение по весу перевозимого заказа и количества заказов.

Тип курьера	Максимальный вес	Максимальное количество
пеший	10	2
велокурьер	20	4
авто	40	7

Регион доставки

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

Тип курьера	Количество регионов	Комментарий
пеший	1	Доставка осуществляется только в одном регионе
велокурьер	2	Доставка будет в двух регионах
авто	3	Можно выбрать 3 региона

Время доставки

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

Время посещения всех точек в одном регионе:

Тип курьера	1й заказ	Следующие заказы
пеший	25	10
велокурьер	12	8
авто	8	4

При доставке товара в другом регионе, время рассчитывается также:

Тип курьера	1й заказ	Следующие заказы
велокурьер	12	8
авто	8	4

Время доставки ограничено рабочим интервалов. Например, если курьер работает с 10-00 до 12-00 без использования транспорта, он может доставить 4 заказа без объединения:

Время	Номер заказа
10:25	1
10:50	2
11:15	3
11:40	4

И с объединением заказов, получится доставить больше заказов за то же время:

Время	Номер заказа
10:00	[1, 2]
10:35	[3, 4]
11:10	[5, 6]
11:45	[7, 8]

Стоимость доставки

Стоимость доставки при группировке заказов, расчитывается следующим образом:

Тип курьера	1й заказ	Следующие заказы
пеший	100%	80%
велокурьер	100%	80%
авто	100%	80%

Распределение заказов по курьерам

POST /orders/assign

Response

[
  {
    "date": "2023-05-17",
    "couriers": [
      {
        "courier_id": 0,
        "orders": [
          {
            "group_order_id": 0,
            "orders": [
              {
                "order_id": 0,
                "weight": 0,
                "regions": 0,
                "delivery_hours": [
                  "string"
                ],
                "cost": 0,
                "completed_time": "2023-05-17T22:47:14.562Z"
              }
            ]
          }
        ]
      }
    ]
  }
]

Список распределенных заказов

GET /couriers/assignments

Response

{
  "date": "2023-05-17",
  "couriers": [
    {
      "courier_id": 0,
      "orders": [
        {
          "group_order_id": 0,
          "orders": [
            {
              "order_id": 0,
              "weight": 0,
              "regions": 0,
              "delivery_hours": [
                "string"
              ],
              "cost": 0,
              "completed_time": "2023-05-17T22:52:42.299Z"
            }
          ]
        }
      ]
    }
  ]
}

Что можно улучшить

Использовать гуся в качестве инструмента миграций!