简单超市配送

业务场景

以下是演示快盒调度工作原理的一个最简单的业务场景。

在淄博，某商店提供线上购物平台。所有线上订单都从一个中央配送中心发货。这个商店有2名员工，每天有8个订单。

该商店在平台上创建自己的员工和订单后，平台可以将8个订单以最优次序分配给2个员工，以最小化订单配送的总行驶距离。

本示例中的所有代码都可以在该仓库中找到: KDClient .

准备工作

1. 您应该拥有一个快盒调度账户。如果没有，请前往 快盒调度 进行注册。
2. 要运行示例Python程序，您需要在您的环境中安装Python。我们将通过Python和RESTful API构建客户端示例。VSCode是我们的首选IDE。我们准备的HTTP脚本是使用rest-client 扩展在VSCode中编写的。

运行示例Python程序以一次性完成所有步骤

第一步是将该仓库克隆到您的本地计算机上：

git clone https://gitee.com/CrazyClue/kdclient.git

然后，将所需的包安装到您的Python环境中：

cd kdclient
pip install -r requirements.txt

接下来用您在快盒调度的注册信息配置所需环境变量:

# export server_url=http://_server_url_/kd/api/v1
# export email=_email_@email.com
# export password=_pass_
# export team_code=_team_

您可以在dev.env文件中进行环境变量的配置。该文件中的环境变量将会正确被程序读取。

然后您可以通过以下方式运行zibo.py示例程序:

python ./src/zibo.py

程序运行完毕后，您可以回到用户界面中，此时您应该可以在"Live Map"（实时地图）中查看规划好的路线。

逐一运行示例程序所用API

之前的Python程序包含了所有的API并将他们一次性全部执行。如果您想逐一学习和测试这些API，您可以按照本节中的步骤进行操作。本节逐一使用API的顺序也是之前Python程序使用API的顺序。如果您使用的是Vscode IDE并且安装了rest-client扩展，您可以直接打开位于http文件夹下的london_sample.http文件，通过Send Requst逐一调用API。

创建一个团队

要使用restful APIs，您首先应该使用登录 API 来获取一个令牌，以便在后续的每个API调用中使用。

http

POST {{hostUrl}}/auth/login
Content-Type: application/json

{"email": "{{user}}", "password": "{{pass}}"}

python

    url = f"{self.service_url}/auth/login"
    login_info = {"email": username, "password": password}

    response = self.requests.post(
        url, json=login_info, headers={"Content-Type": "application/json"}, 
    )

有了这个令牌, 我们就可以通过调用这个API来创建一个在英国的团队:

POST {{server_url}}/teams/
Authorization: Bearer {{jwtoken}}
Content-Type: application/json

{
    "code": "london", "name": "london", 
    "geo_longitude": -0.193837, 
    "geo_latitude": 51.49161, 
    "planner_service": {"code": "single_area_code_cvrp"}, 
    "flex_form_data": {
        "fixed_horizon_flag": "1", 
        "env_start_datetime": "2024-02-14T00:00:00", 
        "horizon_start_datetime": "2024-02-14T08:01:01", 
        "nbr_minutes_planning_windows_duration": 2880
    }
}

本指南与[快速开始]指南之间的主要区别在于，我们通过设置参数“fixed_horizon_flag”为1来固定规划窗口（设置为一个固定的时间段），以完成测试目的。但在生产系统中，我们应该保持其在线状态，动态使用当前时间，而不是固定的，即“fixed_horizon_flag”应为0。参数“horizon_start_datetime”仅在“fixed_horizon_flag”等于1时有效。

创建工作人员

现在我们可以通过调用此API来完成工作人员的逐个创建。

POST {{server_url}}/workers/   HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{jwtoken}}

{
    "code": "w1", 
    "name": "w0",
    "team": {"code": "{{team_code}}"}, 
    "geo_longitude": -0.1938377, 
    "geo_latitude": 51.49161,
    "flex_form_data": {"area_code": "A", "capacity_volume": 0, "max_nbr_order": 0}, 
    "business_hour": {
        "monday": [{"open": "0005", "close": "2330", "id": "a0", "isOpen": true}], 
        "tuesday": [{"open": "0005", "close": "2330", "id": "a1", "isOpen": true}], 
        "wednesday": [{"open": "0005", "close": "2330", "id": "a2", "isOpen": true}], 
        "thursday": [{"open": "0005", "close": "2330", "id": "a3", "isOpen": true}], 
        "friday": [{"open": "0005", "close": "2330", "id": "a4", "isOpen": true}], 
        "saturday": [{"open": "0005", "close": "2330", "id": "a5", "isOpen": true}], 
        "sunday": [{"open": "0005", "close": "2330", "id": "a6", "isOpen": true}]
        }, 
    "auto_planning": true,
    "is_active": true
}

建议在创建工作人员以后重置规划环境。

POST {{server_url}}/planner_service/reset_planning_window/   HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{jwtoken}}

{"team_code":  "{{team_code}}"}

创建订单

现在我们可以向这个团队添加订单了。在本指南中，我们会运行批量规划，自动规划不会启用。这意味着我们将设置 auto_planning=false。

在已创建令牌和团队的情况下，我们可以通过调用此接口完成业务的逐步创建。

POST {{server_url}}/jobs/  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{jwtoken}}

{
    "code":"A5-0",
    "team": {"code": "{{team_code}}"} ,
    "job_type": "visit",
    "auto_planning": false,
    "is_active": true,
    "planning_status": "U",
    "geo_longitude": -0.168417,
    "geo_latitude": 51.461233,
    "requested_start_datetime": "2024-02-14T07:06:40",
    "requested_duration_minutes": 0.5,
    "flex_form_data": {
        "area_code": "A"
    }
}

执行批量规划

创建完所有任务后，您可以通过调用此API执行规划操作。

POST {{server_url}}/planner_service/run_batch_optimizer/   HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{jwtoken}}

{
    "team_code": "{{team_code}}", 
    "area_codes": "A"
}

查看规划结果

您可以调用此API来获取任何工作人员的已规划任务。

POST {{server_url}}/planner_service/get_env_jobs/  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{jwtoken}}

{
    "team_code": "{{team_code}}", 
    "worker_codes": "w0",
    "reset_start_datetime": false,
    "active_only":false
}

在用户界面查看规划结果

在规划完成后，您可以登录快盒调度平台。您此时应当能看到伦敦中心的地图，已规划的业务和工作人员应当在地图上显示。