现场服务

业务场景

在新加坡, kStore 提供家庭设备安装维修服务。以下是四种不同产品的服务订单：

网络设备
电视
厨房（电器）
水管工（服务）

同时也有三种顾客类型：

重点客户
中小企业
个人

每一个员工（技术人员，工程人员）可以掌握多种技术，这会形成不同的技术组合，而且，员工可能需要同时满足多类顾客的需求。

服务订单会通过接口持续不断的上传到快盒调度平台，并被分配到合适工作人员，分配工作每天会进行一次。

本指南与其它指南的主要区别是，我们需要处理复杂的业务规则，像是"技术", "服务时间窗口", "服务持续时间"。而且，规划窗口时间轴可能会跨越数天。

本示例中所有代码都可在本仓库中找到: KDClient 。本示例所用主要程序/脚本为：

python demo
HTTP scripts

准备工作

您应该拥有一个快盒调度账户。如果没有，请前往快盒调度进行注册。
要运行示例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_

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

python ./src/sg_multi_days.py

程序运行结束后，您应该可以在用户界面查看到规划路径。

逐一运行示例程序所用API

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

创建一个团队

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

httppython

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": "sgmd", "name": "sgmd", 
    "geo_longitude": 103.8, 
    "geo_latitude": 1.3, 
    "planner_service": {"code": "single"}, 
    "flex_form_data": {
        "fixed_horizon_flag": "1", 
        "env_start_datetime": "2023-11-13T00:00:00",
        "horizon_start_datetime": "2023-11-13T08:01:01",
        "nbr_minutes_planning_windows_duration": 1440,

        "enable_skills": "1",
    }
}

这里 "enable_skills" 会启动技术检查功能，默认状态下，该功能关闭。

创建工作人员

我们可以调用此API，来创建两个拥有不同技术组合的工作人员。

http


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

{
    "code": "w1", "name": "w1",
    "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
}

然后您可以用以下内容替换上一个请求的JSON体，再次调用API来创建第二个员工。

json

{
    "code": "w2", "name": "w2",
    "flex_form_data": {
        "skills":"Kitchen"
    }
}

重置规划环境

在创建员工以后，建议重置规划窗口来初始化规划引擎。

http

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.

我们可以调用此API完成业务创建:

http


###
# @name create_job_1

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


{
    "code":"A1-0",
    "team": {"code": "{{team_code}}"} ,
    "job_type": "visit",
    "auto_planning": false,
    "is_active": true,
    "planning_status": "U",
    "geo_longitude": 103.833, 
    "geo_latitude": 1.301, 
    "requested_start_datetime": "2023-11-13T07:06:40",
    "requested_duration_minutes": 0.5,
    "flex_form_data": {
        "area_code": "A",
        "skills":"TV"
    }
}

然后您可以用以下内容替换上一个请求的JSON体，再次调用API来创建第二个业务。

json

{
    "code":"A2-0",
    "geo_longitude": 103.833, 
    "geo_latitude": 1.315, 
    "flex_form_data": {
        "skills":"Kitchen"
    }
}

执行批量规划

因为我们没有启动自动规划，所以业务创建后直到执行批量规划才会被分配。

创建所有业务以后，您可以调用此API完成批量规划。

http

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

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

查看规划结果

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

http

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

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

返回的结果应该包含以下信息:

json


{
  "w2": [
    {
      "code": "A2-0",
      "scheduled_start_datetime": "2023-11-13T08:03:00",
      "prev_travel": 0.0,
      "scheduled_duration_minutes": 0.0
    }
  ],
  "w1": [
    {
      "code": "A1-0",
      "scheduled_start_datetime": "2023-11-13T08:03:00",
      "prev_travel": 2.0,
      "scheduled_duration_minutes": 0.0
    }
  ]
}

结果是，业务 "A1-0" 被分配给工作人员 "W1" ，业务"A2-0" 被分配给工作人员 "W2"。这是由创建时的技术设定决定的。

在用户界面查看规划结果

规划结束后，您可以登录快盒调度平台。您应该能在看到已被规划的业务和工作人员。

现场服务 ​

业务场景 ​

准备工作 ​

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

逐一运行示例程序所用API ​

创建一个团队 ​

创建工作人员 ​

重置规划环境 ​

创建业务 ​

执行批量规划 ​

查看规划结果 ​

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

现场服务

业务场景

准备工作

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

逐一运行示例程序所用API

创建一个团队

创建工作人员

重置规划环境

创建业务

执行批量规划

查看规划结果

在用户界面查看规划结果