送餐

业务场景

假定“快跑腿”是在深圳,提供线上订餐送餐服务的公司。每个跑腿订单(order)都包括两个任务(job)，一是从餐厅取餐(pick)，二是给顾客送餐(drop)。这些订单会通过接口发送到快盒调度平台，快盒调度负责实时，自动分配给合适的骑手(worker)。

本指南和其它指南的主要区别是，我们使用了订单的概念，一个订单包含了取和送两部分工作。同一个订单的取送应当由同一位工作人员完成，并且取餐应当在送餐之前。

本示例中所有代码都可在Gitee仓库中免费下载: Gitee - KDClient 。本示例所用主要程序/脚本为：

• python demo
• HTTP scripts

准备工作

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_

我们提供了一个名为_sample.env_的模板文件，您可以将该文件另存为sg.env并进行配置。该文件中的环境变量将会正确被shenzhen_pickdrop.py示例程序读取。

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

python ./src/shenzhen_pickdrop.py

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

逐一运行示例程序所用API

之前的Python程序包含了所有的API并将他们一次性全部执行。如果您想逐一学习和测试这些API，您可以按照本节中的步骤进行操作。本节逐一使用API的顺序也是之前Python程序使用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"}, 
    )

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

http

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

{
    "code": "sz1", "name": "sz1", 
    "geo_longitude": 113.9618, 
    "geo_latitude": 22.5583, 
    "planner_service": {"code": "pickdrop"}, 
    "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
    }
}

为了完成同一订单的取送工作，我们应将"Planner Code"设置为"pickdrop"来指定取送的算法引擎。我们依然会设置参数"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": 103.835, 
    "geo_latitude": 1.303, 
    "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=true 。

我们可以通过调用此API来逐个创建订单：

@order_code2=ord2

###
# @name create_order_2

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

{
    "code": "{{order_code2}}", 
    "flex_form_data": {"area_code": "A"},  
    "order_type": "pickdrop", 
    "auto_planning": true, 
    "auto_commit": true, 
    "team": {"code": "{{team_code}}"} ,
    "job_list": [
        {
            "code": "{{order_code2}}-p", 
            "geo_longitude":103.8601, "geo_latitude": 1.30598, 
            "job_type": "visit", 
            "planning_status": "U", 
            "auto_planning": true, 
            "flex_form_data": {"area_code": "A"}, 
            "requested_start_datetime": "2024-02-14T02:03:00", 
            "requested_duration_minutes": 0.5,
            "order_code": "{{order_code2}}", 
            "team": {"code": "{{team_code}}"}  
        }, 
        {
            "code": "{{order_code2}}-d", 
            "geo_longitude": 103.88465, "geo_latitude": 1.313883,
            "job_type": "visit", 
            "planning_status": "U", 
            "auto_planning": true, 
            "flex_form_data": {"area_code": "A"}, 
            "requested_start_datetime": "2024-02-14T03:03:00", 
            "requested_duration_minutes": 0.5,
            "order_code": "{{order_code2}}", 
            "team": {"code": "{{team_code}}"}  
        }
    ]
}

因为我们设置了 "auto_planning"=true ,所以订单创建以后会被自动规划。如果规划成功，您应该能看到状态码显示为"COMMITTED"的结果。

查看规划结果

您可以调用此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
}

在用户界面中查看规划结果

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

更多高级配置

完成这个基本配置后，你能做简单的订单自动调度。如果需要了解更详细的规则配置能力，请访问 取送业务配置参数