此仓库包含 Timefold Solver 的快速入门示例，它是一款适用于 Java 和 Kotlin 的 AI 约束求解器。这些示例展示了不同的用例和基础实现，帮助您开启规划 AI 之旅。

概述

用例	显著的求解器概念
🚚 车辆路径规划	链式时间约束、影子变量
🧑‍💼 员工排班	负载均衡
🛠️ 维护调度	时间粒度、影子变量、变量监听器
📦 食品包装	混合模型、影子变量、固定
🛒 订单拣选	链式规划变量、影子变量
🏫 学校课表编排	时间槽
🏭 设施选址问题	影子变量
🎤 会议安排	时间槽、理由说明
🛏️ 床位分配调度	允许未分配
🛫 飞行机组排班
👥 会议安排	时间粒度
✅ 任务分配	可调整评分、链式时间约束、允许未分配
📆 项目作业调度	影子变量、变量监听器、强度比较器
🏆 体育联赛赛程安排	连续序列
🏅 锦标赛赛程安排	固定、负载均衡

[!注意] 此仓库中的实现仅作为起点和/或灵感，用于构建您自己的应用程序。 Timefold Solver 是一个库，不包含用户界面。为了展示这些用例，这些快速入门示例中附带了一个基础 UI。

用例

🚚 车辆路径规划

在考虑车辆容量和访问时间窗口的情况下，为车辆找到到达各访问点的最高效路线。有时也称为“CVRPTW”。

• 运行 quarkus-vehicle-routing (Java, Maven, Quarkus)

[!提示] 查看我们现成的现场服务路由模型。该模型超越了基本的车辆路径规划，支持优先级、技能、公平性等额外约束。

---

🧑‍💼 员工排班

根据员工的可用性和班次技能要求，为员工安排班次。

• 运行 quarkus-employee-scheduling (Java, Maven, Quarkus)

[!提示] 查看我们现成的员工轮班排班模型。该模型支持许多额外的约束，如技能、员工配对、公平性等。

---

🛠️ 维护调度

将维护任务按时间顺序分配给维护团队，以减少过早和逾期维护的情况。

• 运行 quarkus-maintenance-scheduling (Java, Maven, Quarkus)

---

📦 食品包装

将食品包装订单安排到生产线，以最大限度地减少停机时间并按时完成所有订单。

• 运行 quarkus-food-packaging (Java, Maven, Quarkus)

---

🛒 订单拣选

为完成一组订单生成最优的拣选计划。

• 运行 quarkus-order-picking (Java, Maven, Quarkus)

---

🏫 学校课表编排

将课程分配到时间槽和教室，以制定更合理的教师和学生课表。

• 运行 quarkus-school-timetabling (Java, Maven 或 Gradle, Quarkus)
• 运行 spring-boot-school-timetabling (Java, Maven 或 Gradle, Spring Boot)
• 运行 kotlin-quarkus-school-timetabling (Kotlin, Maven, Quarkus)

无 UI 版本：

• 运行 hello-world-school-timetabling (Java, Maven 或 Gradle)

---

🏭 设施选址问题

为新门店、配送中心、新冠检测中心或通信基站选择最佳地理位置。

• 运行 quarkus-facility-location (Java, Maven, Quarkus)

---

🎤 会议安排

将会议演讲分配到时间槽和会议室，以制定更合理的演讲者日程。

• 运行 quarkus-conference-scheduling (Java, Maven, Quarkus)

---

🛏️ 床位分配调度

为患者的住院安排床位，以生成更优的医院排班计划。

• 运行 quarkus-bed-allocation-scheduling（Java、Maven、Quarkus）

---

🛫 航空机组调度

为航班分配机组人员，以生成更优的机组排班计划。

• 运行 quarkus-flight-crew-scheduling（Java、Maven、Quarkus）

---

👥 会议调度

为会议分配时间段和会议室，以生成更优的会议日程安排。

• 运行 quarkus-meeting-scheduling（Java、Maven、Quarkus）

---

✅ 任务分配

将员工分配到各项任务中，以生成更优的任务分配方案。

• 运行 quarkus-task-assigning（Java、Maven、Quarkus）

---

📆 项目作业调度

为执行任务分配作业，以生成更优的项目作业排程。

• 运行 quarkus-project-job-scheduling（Java、Maven、Quarkus）

---

🏆 体育联赛调度

为比赛分配轮次，以生成更优的联赛赛程。

• 运行 quarkus-sports-league-scheduling（Java、Maven、Quarkus）

---

🏅 锦标赛调度

锦标赛调度服务，用于将球队分配到锦标赛比赛中。

• 运行 quarkus-tournament-scheduling（Java、Maven、Quarkus）

---

法律声明

Timefold Quickstarts 于 2023 年 4 月 20 日从 OptaPlanner Quickstarts 分支而来。OptaPlanner Quickstarts 完全采用 Apache-2.0 许可证（一种宽松的开源许可证）。

Timefold Quickstarts 是 OptaPlanner Quickstarts 的衍生作品，其中包含原始创建者 Red Hat Inc.、其关联公司及贡献者的版权，这些版权均完全受 Apache-2.0 许可证保护。所有源代码文件均已修改。

Timefold Quickstarts 快速上手指南

Timefold Quickstarts 是 Timefold Solver 的示例集合，这是一个用于 Java 和 Kotlin 的 AI 约束求解器。本指南将帮助你快速运行这些示例，了解如何解决车辆路径、员工排班、课程表等规划问题。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows
• JDK: Java 17 或更高版本 (推荐 OpenJDK 17/21)
  • 国内加速: 建议从 华为开源镜像站 或 阿里巴巴开源镜像站 下载。
• 构建工具: Maven 3.8+ 或 Gradle 8+
  • 国内加速: 配置 settings.xml (Maven) 或 init.gradle (Gradle) 使用阿里云镜像源以加快依赖下载速度。
  • Maven 阿里云配置示例 (~/.m2/settings.xml):

  <mirrors>
    <mirror>
      <id>aliyunmaven</id>
      <mirrorOf>*</mirrorOf>
      <name>Aliyun Public</name>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
  </mirrors>
  

• IDE (可选): IntelliJ IDEA, Eclipse 或 VS Code (安装 Java 扩展包)。

安装步骤

由于这是一个包含多个独立示例的仓库，你不需要全局安装工具，只需克隆仓库并进入具体示例目录即可。

1. 克隆仓库

   git clone https://github.com/TimefoldAI/timefold-quickstarts.git
   cd timefold-quickstarts
   

2. 选择并进入示例目录 根据你的需求选择一个场景。例如，运行最经典的“学校课程表”示例（Java + Quarkus）：

   cd java/school-timetabling
   

   其他常见示例路径:

   • 车辆路径: cd java/vehicle-routing
   • 员工排班: cd java/employee-scheduling
   • Kotlin 版本: cd kotlin/school-timetabling

3. 编译项目 在项目根目录下执行以下命令（以 Maven 为例）：

   mvn clean compile
   

   如果是 Gradle 项目，请使用 ./gradlew build。

基本使用

大多数 Quickstart 示例都内置了一个简易的 Web UI，方便直观地查看求解过程和结果。以下以 学校课程表 (School Timetabling) 为例演示如何运行。

1. 启动应用

在示例目录（如 java/school-timetabling）下运行：

mvn quarkus:dev

注：如果是 Spring Boot 版本的示例，请使用 mvn spring-boot:run。

2. 访问界面

当控制台显示 Quarkus ... started in x.xxx s 时，打开浏览器访问：

http://localhost:8080

3. 操作求解器

1. 加载数据: 页面加载后会自动生成示例数据（课程、教室、时间段、老师等）。
2. 开始求解: 点击界面上的 "Solve" 按钮。
3. 观察过程: 你将看到 AI 求解器实时调整课程安排，分数（Score）会随着约束条件的满足而逐渐优化（负分减少趋向于 0 或正分）。
4. 停止求解: 点击 "Stop solving" 查看最终结果，或让其在后台持续优化。

代码结构简析

如果你想基于此开发自己的应用，重点关注以下文件：

• src/main/java/.../domain/*.java: 定义规划实体（如 Lesson）和规划变量（@PlanningVariable）。
• src/main/java/.../constraint/...ConstraintProvider.java: 定义业务约束规则（硬约束和软约束）。
• src/main/resources/application.properties: 配置求解器超时时间、线程数等参数。

现在，你可以尝试切换到其他目录（如 vehicle-routing），重复上述步骤来体验不同的 AI 规划场景。