现场服务

场景简介

本平台适用于现场服务场景，支持多技术人员、多技能、多任务的智能调度。平台可灵活配置团队、技术人员、技能、任务等信息，并支持多种业务约束（如技能匹配、服务时间窗、优先级等），满足实际现场服务业务的复杂需求。通过 API 可实现团队创建、技术人员管理、任务下发、批量调度、结果查询等全流程操作。

准备工作

1. 注册获取平台账号。
2. 获取 API 访问地址、账号邮箱、密码、团队编码等信息。
3. 推荐使用 VSCode 并安装 rest-client 插件，便于直接运行 HTTP 脚本。

操作流程

1. 登录获取 Token

首先通过登录接口获取访问令牌（token），后续所有接口均需携带该 token。

@server_url=https://kd1.kuaihe.tech/api/v1
@email=
@password=
@team_code=field_service_demo
@jwtoken=

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

{
  "email": "{{email}}",
  "password": "{{password}}"
}

@jwtoken = {{login.response.body.data.jwtoken}}

登录成功后，返回的 token 用于后续接口的 Authorization 头部。

---

2. 创建团队

团队是调度的基本单位。创建团队时可配置地图中心点、调度约束、服务时间、技能匹配等参数。对于现场服务场景，需要开启技能约束。

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

{
    "code": "{{team_code}}", 
    "name": "现场服务团队", 
    "geo_longitude": 103.8, 
    "geo_latitude": 1.3, 
    "planner_service": {"code": "single_opti6"}, 
    "flex_form_data": {
        "fixed_horizon_flag": "1", 
        "env_start_datetime": "2025-06-04T00:00:00", 
        "nbr_minutes_planning_windows_duration": 1440,
        "timezone": "Asia/Singapore",
        "enable_skills": "1",
        "enable_time_window_constraint": 1
    }
}

• code：团队唯一标识 （必选）。
• name：团队名称。
• geo_longitude、geo_latitude：配置团队所在位置，地图中心点。
• fixed_horizon_flag：1 固定，0 不固定。
• env_start_datetime：调度窗口开始时间，格式为：YYYY-MM-DDTHH:MM:SS。
• nbr_minutes_planning_windows_duration：调度窗口时长，单位：分钟。
• timezone：配置时区。
• enable_skills：开启技能约束，1 开启。这对于根据技术人员技能匹配服务任务至关重要。
• enable_time_window_constraint：开启服务时间约束，0 关闭，1 开启。

---

3. 创建工作人员

工作人员即提供现场服务的技术人员。可为每位技术人员配置具备的技能、工作时间等。

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

{
    "code": "tech1", 
    "name": "技术员1-网络_电视",
    "team": {"code": "{{team_code}}"},
    "geo_longitude": 103.835,
    "geo_latitude": 1.303,
    "flex_form_data": {
        "skills": "Network;TV"
    },
    "business_hour": {
        "monday": [{"open": "0800", "close": "1800", "id": "a0", "isOpen": true}], 
        "tuesday": [{"open": "0800", "close": "1800", "id": "a1", "isOpen": true}], 
        "wednesday": [{"open": "0800", "close": "1800", "id": "a2", "isOpen": true}], 
        "thursday": [{"open": "0800", "close": "1800", "id": "a3", "isOpen": true}], 
        "friday": [{"open": "0800", "close": "1800", "id": "a4", "isOpen": true}], 
        "saturday": [{"open": "0000", "close": "0000", "id": "a5", "isOpen": false}], 
        "sunday": [{"open": "0000", "close": "0000", "id": "a6", "isOpen": false}]
    },
    "auto_planning": true,
    "is_active": true
}

• code：工作人员唯一标识 （必选）。
• name：工作人员名称。
• team：所属团队。
• geo_longitude、geo_latitude：配置工作人员起始位置。
• is_active：是否激活。
• auto_planning：是否允许被自动分配，true 允许 false 不允许。
• business_hour：配置工作时间。
• flex_form_data：配置扩展字段。
  • skills：配置工作人员具备的技能。多个技能用分号;分隔。

创建另一位掌握不同技能的技术员：

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

{
    "code": "tech2", 
    "name": "技术员2-厨房_水管",
    "team": {"code": "{{team_code}}"},
    "geo_longitude": 103.835,
    "geo_latitude": 1.303,
    "flex_form_data": {
        "skills": "Kitchen;Plumbing"
    },
    "business_hour": {
        "monday": [{"open": "0800", "close": "1800", "id": "a0", "isOpen": true}], 
        "tuesday": [{"open": "0800", "close": "1800", "id": "a1", "isOpen": true}], 
        "wednesday": [{"open": "0800", "close": "1800", "id": "a2", "isOpen": true}], 
        "thursday": [{"open": "0800", "close": "1800", "id": "a3", "isOpen": true}], 
        "friday": [{"open": "0800", "close": "1800", "id": "a4", "isOpen": true}], 
        "saturday": [{"open": "0000", "close": "0000", "id": "a5", "isOpen": false}], 
        "sunday": [{"open": "0000", "close": "0000", "id": "a6", "isOpen": false}]
    },
    "auto_planning": true,
    "is_active": true
}

---

4. 创建服务任务

任务可配置所需的技能、服务时间窗、服务时长等参数。

创建需要特定技能的任务

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

{
    "code":"JOB-TV-1",
    "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": "2025-06-04T09:00:00",
    "requested_duration_minutes": 60,
    "flex_form_data": {
        "skills": "TV"
    }
}

• code：任务唯一标识 （必选）。
• team：任务所属团队。
• job_type：任务类型，visit[上门服务]、pickup[取件]。
• auto_planning：是否立刻分配 true 允许 false 不允许。
• is_active：是否激活任务。
• planning_status：任务状态，U[未规划]、I[已规划]。
• geo_longitude、geo_latitude：配置任务所在位置。
• requested_start_datetime 请求开始时间，格式为：YYYY-MM-DDTHH:MM:SS。
• requested_duration_minutes 服务时长，单位：分钟。
• flex_form_data 扩展字段。
  • skills 所需技能。调度时会匹配技术人员拥有的技能。
  • service_window 服务时间窗，格式为：YYYYMMDDHHMM:YYYYMMDDHHMM。

创建需要多种技能的任务

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

{
    "code":"JOB-KP-1",
    "team": {"code": "{{team_code}}"},
    "job_type": "visit",
    "auto_planning": false,
    "is_active": true,
    "planning_status": "U",
    "geo_longitude": 103.833,
    "geo_latitude": 1.315,
    "requested_start_datetime": "2025-06-04T10:30:00",
    "requested_duration_minutes": 90,
    "flex_form_data": {
        "skills": "Kitchen;Plumbing"
    }
}

创建带服务时间窗的任务

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

{
    "code":"JOB-NW-1",
    "team": {"code": "{{team_code}}"},
    "job_type": "visit",
    "auto_planning": false,
    "is_active": true,
    "planning_status": "U",
    "geo_longitude": 103.824,
    "geo_latitude": 1.312,
    "requested_start_datetime": "2025-06-04T14:00:00",
    "requested_duration_minutes": 45,
    "flex_form_data": {
        "skills": "Network",
        "service_window": "202506041400:202506041600"
    }
}

---

5. 重置调度环境

在添加或修改团队配置、工作人员（排班）、任务后建议重置调度窗口以刷新调度环境。

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

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

---

6. 执行批量调度

所有任务创建完成后，调用批量调度接口进行自动分配。

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

{
    "team_code": "{{team_code}}",
    "worker_codes": "tech1;tech2",
    "job_codes": "JOB-TV-1;JOB-KP-1;JOB-NW-1"
}

• team_code 团队编码
• worker_codes 可选，限定只分配给固定的工作人员，不传入则分配给所有工作人员。
• job_codes 可选，限定只分配固定的任务 ，不传入则分配所有任务。

---

7. 查询调度结果

可按工作人员查询任务分配结果。

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

{
    "team_code": "{{team_code}}", 
    "worker_codes": "tech1;tech2",
    "reset_start_datetime": false,
    "active_only": false
}

返回示例： 由于 JOB-TV-1 和 JOB-NW-1 需要 TV 或 Network 技能，它们被分配给了 tech1。JOB-KP-1 需要 Kitchen 和 Plumbing 技能，被分配给了 tech2。

{
  "tech1": [
    {
      "code": "JOB-TV-1",
      "scheduled_start_datetime": "2025-06-04T09:00:00",
      "prev_travel": 2.0,
      "scheduled_duration_minutes": 60.0
    },
    {
      "code": "JOB-NW-1",
      "scheduled_start_datetime": "2025-06-04T14:00:00",
      "prev_travel": 15.0,
      "scheduled_duration_minutes": 45.0
    }
  ],
  "tech2": [
    {
      "code": "JOB-KP-1",
      "scheduled_start_datetime": "2025-06-04T10:30:00",
      "prev_travel": 0.0,
      "scheduled_duration_minutes": 90.0
    }
  ]
}

• tech1: worker code
  • code: job code
  • scheduled_start_datetime: 调度开始时间

结果查看

规划结束后，您可以登录快盒调度平台。 或者在Map组件上 该能在看到已被规划的业务和工作人员及执行路径。

调试用接口

批量删除任务

可以删除指定任务，用于测试。

DELETE {{server_url}}/jobs/utils/batch_delete
Authorization: Bearer {{jwtoken}}
Content-Type: application/json

{
    "team_code": "{{team_code}}",
    "job_codes": ["JOB-TV-1", "JOB-KP-1"]
}

• team_code 团队编码
• job_codes 可选，限定只删除固定的任务 ，不传入则删除所有任务。

删除团队

可以删除团队及团队下所有任务、工作人员，用于测试。

DELETE {{server_url}}/teams/utils/batch_delete
Authorization: Bearer {{jwtoken}}
Content-Type: application/json

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