# Smart Schedule Agent

**Repository Path**: java_36/smart-schedule-agent

## Basic Information

- **Project Name**: Smart Schedule Agent
- **Description**: Smart Schedule Agent - 智能 K-12 学校排课 AI Agent
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-14
- **Last Updated**: 2026-05-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Smart Schedule Agent - 智能 K-12 学校排课 AI Agent

## 项目概述

这是一个面向 K-12 教育的智能排课系统，结合了约束求解 (Timefold Solver) 和 AI Agent (LangChain4j + 通义千问) 技术。项目采用前后端分离架构，后端基于 Spring Boot 3.2 多模块设计，前端使用 Vue 3 + TypeScript + Element Plus。

### 核心技术栈

- **后端**: Java 17, Spring Boot 3.2.4
- **持久层**: MyBatis-Plus 3.5.5
- **数据库**: MySQL 8.0
- **约束求解**: Timefold Solver 1.16.0 (排课核心引擎)
- **AI Agent**: LangChain4j 1.0.0-beta3 + 通义千问 (DashScope)
- **安全认证**: JWT (jjwt)
- **前端**: Vue 3, TypeScript, Vite, Element Plus
- **工具库**: Hutool, Lombok

### 项目定位

本项目属于 AI Agent 学习路径中的**阶段三：进阶实战**，对应"项目 7: 企业级 Agent 平台"和"项目 8: AI 原生应用"的综合实践。

## 模块结构

```
smart-schedule-agent/
├── schedule-common        # 公共模块：工具类、异常处理、通用模型、JWT
├── schedule-data          # 数据层模块：实体类、Mapper、多租户支持、MyBatis 配置
├── schedule-engine        # 排课引擎：Timefold 约束求解器、领域模型、约束规则
├── schedule-agent         # AI Agent 模块：LangChain4j 集成、智能对话 (开发中)
├── schedule-service       # 业务服务层：学校数据服务、用户认证服务
├── schedule-web           # Web 层：Spring Boot 启动类、Controller、过滤器、Swagger
├── docker-compose.yml     # Docker 编排 (MySQL + 后端)
├── Dockerfile             # 后端镜像构建
└── pom.xml                # Maven 父 POM
```

> **注意**: 前端项目已独立为 `smart-schedule-frontend`，位于同级目录下。

### 模块依赖关系

```
schedule-web
  └── schedule-service
        ├── schedule-data
        └── schedule-common

schedule-agent
  └── schedule-common

schedule-engine
  ├── schedule-data
  └── schedule-common
```

## 构建与运行

### 前置条件

- JDK 17+
- Maven 3.8+
- Node.js 18+ (前端开发)
- Docker & Docker Compose (可选，容器化部署)

### 后端构建与运行

```bash
# 1. 编译打包 (跳过测试)
mvn clean package -DskipTests

# 2. 运行应用 (需先启动 MySQL)
java -jar schedule-web/target/*.jar

# 3. 或使用 Maven 插件直接运行
mvn spring-boot:run -pl schedule-web
```

### 使用 Docker Compose 一键启动

```bash
# 设置环境变量 (通义千问 API Key)
export DASHSCOPE_API_KEY=your-api-key-here

# 启动 MySQL + 后端服务
docker-compose up -d
```

### 前端开发

前端项目已独立，请前往 `smart-schedule-frontend` 目录进行开发。

### 开发环境变量

项目使用环境变量配置，关键变量如下：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `DB_PASSWORD` | 数据库密码 | `root` |
| `JWT_SECRET` | JWT 密钥 | 内置默认值 |
| `DASHSCOPE_API_KEY` | 通义千问 API Key | `your-api-key` |

### API 文档

启动后可访问 Swagger UI:
- URL: `http://localhost:8080/swagger-ui.html`

## 架构设计要点

### 1. 多租户支持

- `schedule-data` 模块实现了基于 MyBatis-Plus 的多租户拦截器
- 租户上下文: `TenantContext`
- 忽略表: `t_school`, `t_user` (全局共享)
- Web 层通过 `TenantFilter` 设置租户上下文

### 2. 排课引擎 (schedule-engine)

使用 Timefold Solver 实现约束求解排课：

- **领域模型**: `TimetableSolution`, `LessonAssignment`, `Timeslot`, `RoomAssignment`, `TeacherUnavailability`
- **约束规则**: `ScheduleConstraintProvider`
- **求解服务**: `ScheduleSolverService`
- **配置**: `TimefoldConfig`, `solverConfig.xml`

### 3. AI Agent 集成 (schedule-agent)

- 基于 LangChain4j 框架，采用 `AiServices` + `Function Calling` 架构
- 使用通义千问 (qwen-plus) 作为 LLM 后端
- 通过 OpenAI 兼容模式调用 DashScope API
- **核心能力**:
  - [x] 智能对话与多轮上下文记忆 (`DbChatMemory`)
  - [x] 流式输出 (SSE 打字机效果)
  - [x] 自动身份识别 (`@ToolMemoryId` 复合键路由)
  - [x] 排课工具集 (查询、交换 `swapLessons`、移动 `moveLesson`)
  - [x] 自动冲突检测与调课失败反馈
  - [x] 系统提示词动态注入 (用户身份、学校数据)

### 4. 安全认证

- JWT 认证机制 (`JwtAuthenticationFilter`)
- Spring Security 配置 (`SecurityConfig`)
- 基于角色的访问控制 (RBAC): `ADMIN`, `TEACHER`
- 认证服务: `AuthService`

### 5. 数据库迁移

- 使用 Flyway 进行数据库版本管理
- 迁移脚本位置: `classpath:db/migration`

## 开发约定

### 包命名

- 基础包名: `com.schedule`
- 数据层: `com.schedule.data.*` (mapper, entity, config)
- 引擎层: `com.schedule.engine.*` (domain, solver, constraint)
- 服务层: `com.schedule.service.*` (school, user)
- Web 层: `com.schedule.web.*` (controller, filter, config)
- 公共层: `com.schedule.common.*` (util, exception, model, constant)

### 编码风格

- 使用 Lombok 简化代码 (`@Data`, `@RequiredArgsConstructor` 等)
- 使用 MyBatis-Plus 的 `LambdaQueryWrapper` 进行类型安全查询
- Controller 返回统一响应模型 `ApiResponse<T>`
- OpenAPI 注解标注接口文档 (`@Tag`, `@Operation`)

### 异常处理

- 业务异常: `BusinessException`
- 全局异常处理: `GlobalExceptionHandler`

## 数据模型概览

核心实体 (位于 `schedule-data` 模块):

| 实体 | 说明 |
|------|------|
| `School` | 学校信息 |
| `SchoolClass` | 班级 |
| `Teacher` | 教师 |
| `Subject` | 科目 |
| `SubjectTeacher` | 科目-教师关联 |
| `Room` | 教室 |
| `TimeSlot` | 时间段 |
| `Schedule` | 排课方案 |
| `ScheduleItem` | 排课项 |
| `Conversation` | 对话会话 (AI Agent) |
| `Message` | 对话消息 (AI Agent) |
| `CustomConstraint` | 自定义约束规则 |
| `User` | 系统用户 |

## 当前状态与待开发

### 已完成

- [x] 项目结构与模块划分
- [x] 数据库实体与 Mapper 层
- [x] 多租户支持 (MyBatis-Plus 租户拦截器)
- [x] JWT 认证与用户登录
- [x] 学校数据管理 API
- [x] Timefold 排课引擎集成
- [x] 前端基础页面 (登录、仪表盘、数据管理)
- [x] AI Agent 对话功能 (LangChain4j AiServices + Function Calling)
- [x] AI 流式输出 (SSE 打字机效果 + Markdown 渲染)
- [x] 排课工具集 (查询、交换 `swapLessons`、移动 `moveLesson`)
- [x] 自动身份识别 (`@ToolMemoryId` 复合键路由机制)
- [x] 教师角色与权限隔离 (RBAC)
- [x] 教师个人课表视图 (带背景信息高亮显示)
- [x] 会话标题自动总结与手动编辑功能
- [x] 数据库迁移脚本 (V1~V5)

### 待开发

- [ ] Timefold 排课求解器完整集成 (当前 `startScheduleSolving` 仅更新状态)
- [ ] 自定义约束规则管理界面
- [ ] 排课结果可视化展示 (课表矩阵视图)
- [ ] 教师调课申请与审批流
- [ ] 学生/家长端课表查看功能
- [ ] 监控告警体系 (Prometheus + Grafana)
- [ ] 配置中心集成 (Nacos/Apollo)

## 版本控制

项目使用 Git 进行版本控制。

### 常用命令

```bash
# 查看状态
git status

# 添加并提交
git add .
git commit -m "feat: 功能描述"

# 查看日志
git log --oneline
```

### 提交信息规范

使用 Conventional Commits 格式: `type: description`

| type | 说明 |
|------|------|
| `feat` | 新功能 |
| `fix` | Bug 修复 |
| `docs` | 文档更新 |
| `refactor` | 重构 |
| `chore` | 构建/工具变更 |

## 学习路径映射

本项目对应 AI Agent 学习路径中的以下阶段：

| 阶段 | 关联项目 | 说明 |
|------|----------|------|
| 阶段三: 项目 7 | 企业级 Agent 平台 | Spring Boot 架构、插件化设计、可观测性 |
| 阶段三: 项目 8 | AI 原生应用 | 前后端 AI 集成、流式输出、错误恢复 |