# 系统架构

相关源文件

- [.gitignore](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/.gitignore)
- [README.md](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/README.md)
- [DifyAPI.md](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/doc/DifyAPI.md)
- [create_table.sql](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/sql/create_table.sql)
- [DifyConfig.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/config/DifyConfig.java)
- [MyBatisPlusConfig.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/config/MyBatisPlusConfig.java)
- [CodeGenerator.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/generate/CodeGenerator.java)
- [DifyStreamChunk.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/dto/dify/DifyStreamChunk.java)
- [application-prod.yml](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application-prod.yml)
- [application-test.yml](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application-test.yml)
- [application.yml](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml)
- [PostFavourMapper.xml](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/mapper/PostFavourMapper.xml)
- [PostMapper.xml](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/mapper/PostMapper.xml)
- [PostThumbMapper.xml](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/mapper/PostThumbMapper.xml)
- [UserMapper.xml](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/mapper/UserMapper.xml)

## 目的与范围

本文档描述了 SmartClass 后端系统的整体架构，包括其主要组件、它们之间的关系以及交互方式。它提供了对系统结构的技术理解，帮助开发人员浏览和扩展代码库。有关使用的关键技术信息，请参阅 [关键技术](https://deepwiki.com/Ubanillx/smartclass-backend/1.2-key-technologies)。

## 概览

SmartClass 后端是一个基于 Java 的教育平台，利用 AI 技术提供个性化的学习体验。该系统集成了 Dify AI 以实现智能对话，支持课程管理、每日学习内容和用户进度跟踪。

参考资料：[README.md 第1-37行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/README.md#L1-L37)、[application.yml 第1-125行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L1-L125)

## 核心组件

系统采用分层架构，具有清晰的关注点分离：

### API 层

API 层由处理 HTTP 请求和响应的 RESTful 控制器组成。这些控制器验证输入，将业务逻辑委托给服务层，并返回适当的响应。

### 服务层

服务层包含应用程序的核心业务逻辑。它通过协调数据访问和外部服务集成来实现用例。服务层负责：

- 业务规则执行
- 事务管理
- 外部服务集成
- 复杂操作的编排

### 数据访问层

数据访问层使用 MyBatis Plus 与 MySQL 数据库进行交互。它由以下部分组成：

- 实体定义（POJO）
- Mapper 接口
- 定义 SQL 查询的 XML 映射文件

参考资料：[MyBatisPlusConfig.java 第1-28行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/config/MyBatisPlusConfig.java#L1-L28)、[UserMapper.xml 第1-36行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/mapper/UserMapper.xml#L1-L36)、[PostMapper.xml 第1-33行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/mapper/PostMapper.xml#L1-L33)

### 外部服务集成

系统集成了多个外部服务：

1. **Dify AI API** - 提供智能对话和 AI 强化功能  
2. **微信平台** - 用于用户认证和社会化功能  
3. **云对象存储** - 用于存储和提供文件  

参考资料：[DifyConfig.java 第1-34行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/config/DifyConfig.java#L1-L34)、[application.yml 第63-102行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L63-L102)

## 数据库模型

系统使用 MySQL 进行持久化存储。数据库模式包括以下主要实体组：

### 核心实体关系

参考资料：[create_table.sql 第10-645行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/sql/create_table.sql#L10-L645)

### 关键表

| 实体组             | 主要表                                                                 | 功能说明                           |
|--------------------|------------------------------------------------------------------------|------------------------------------|
| 用户系统           | `user`, `user_learning_stats`                                         | 管理用户账户和学习进度             |
| AI 虚拟头像系统    | `ai_avatar`, `ai_avatar_chat_history`, `user_ai_avatar`                | 处理 AI 对话                       |
| 日常学习系统       | `daily_article`, `daily_word`, `user_daily_article`, `user_daily_word` | 提供每日学习内容                   |
| 课程系统           | `course`, `course_chapter`, `course_section`, `user_course`, `user_course_progress` | 管理教育课程                     |
| 成就系统           | `achievement`, `user_achievement`, `achievement_milestone`             | 实现游戏化功能                     |

参考资料：[create_table.sql 第10-140行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/sql/create_table.sql#L10-L140)、[create_table.sql 第266-400行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/sql/create_table.sql#L266-L400)、[create_table.sql 第437-544行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/sql/create_table.sql#L437-L544)

## 关键业务领域

### AI 虚拟头像聊天系统

AI 虚拟头像聊天系统是核心功能之一，允许用户与 AI 驱动的虚拟头像进行互动学习。它集成了 Dify API 以提供智能响应。

```
"Database" --> "AiAvatarChatHistoryService"
"AiAvatarChatHistoryService" --> "DifyService" : "Dify API"
"DifyService" --> "AiAvatarChatService"
"AiAvatarChatService" --> "AiAvatarChatController"
"AiAvatarChatController" --> "User"

loop [对于每个 chunk]
  alt [流式响应] [阻塞响应]
    "User" ->> "AiAvatarChatController": 发送消息
    "AiAvatarChatController" ->> "AiAvatarChatService": 处理消息
    "AiAvatarChatService" ->> "AiAvatarChatHistoryService": 保存用户消息
    "AiAvatarChatHistoryService" ->> "DifyService": 存储消息并发送给 AI
    "DifyService" ->> "Dify API": 调用 Dify API
    "Dify API" ->> "DifyService": 流式返回响应分块
    "DifyService" ->> "AiAvatarChatService": 转发分块
    "AiAvatarChatService" ->> "AiAvatarChatController": 发送分块
    "AiAvatarChatController" ->> "User": 返回响应分块
  end
end

"Dify API" --> "DifyService": 完整响应
"DifyService" --> "AiAvatarChatService": 返回完整响应
"AiAvatarChatService" --> "AiAvatarChatHistoryService": 处理响应
"AiAvatarChatHistoryService" --> "Database": 保存 AI 响应
```

参考资料：[DifyStreamChunk.java 第1-44行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/dto/dify/DifyStreamChunk.java#L1-L44)、[DifyAPI.md 第1-30行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/doc/DifyAPI.md#L1-L30)
### 日常学习系统

日常学习系统为用户提供每日学习内容，包括文章和词汇。它跟踪用户与内容的互动情况。

参考资料：[create_table.sql 第116-157行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/sql/create_table.sql#L116-L157)、[README.md 第45-52行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/README.md#L45-L52)

### 课程系统

课程系统管理教育课程，包括其结构（章节和小节）、用户注册以及学习进度跟踪。

参考资料：[create_table.sql 第437-638行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/sql/create_table.sql#L437-L638)

## 配置与部署

系统使用 Spring Boot 的配置机制，并支持环境相关的配置文件：

- `application.yml` - 基础配置
- `application-dev.yml` - 开发环境配置
- `application-prod.yml` - 生产环境配置
- `application-test.yml` - 测试环境配置

关键配置项包括：

1. 数据库连接
2. Redis 缓存
3. 服务器端口和上下文路径
4. MyBatis Plus 设置
5. 微信集成
6. 对象存储（COS）
7. Dify API 配置

参考资料：[application.yml 第1-125行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L1-L125)、[application-prod.yml 第1-36行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application-prod.yml#L1-L36)、[application-test.yml 第1-25行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application-test.yml#L1-L25)、[README.md 第119-128行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/README.md#L119-L128)

## 系统集成点

### Dify AI 集成

系统通过 Dify AI API 提供智能虚拟头像对话功能。该集成为 AI 虚拟头像聊天系统所使用，主要在 `DifyConfig.java` 中进行配置。

关键集成点：

- 调用 Dify 的 chat-messages 接口
- 支持流式和阻塞两种响应模式
- 消息历史管理

参考资料：[DifyConfig.java 第1-34行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/config/DifyConfig.java#L1-L34)、[DifyAPI.md 第1-30行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/doc/DifyAPI.md#L1-L30)

### 微信集成

系统通过微信进行用户认证和消息传递。集成配置位于 `application.yml` 文件中的 `wx` 配置部分。

关键集成点：

- 微信公众平台（MP）用于公众号交互
- 微信开放平台用于更广泛的生态系统集成
- 使用微信凭证进行用户认证

参考资料：[application.yml 第63-83行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L63-L83)

### 对象存储集成

系统使用云对象存储来管理文件。集成配置位于 `application.yml` 文件中的 `cos` 配置部分。

关键集成点：

- 用户头像存储
- 课程资料和资源
- 媒体附件

参考资料：[application.yml 第84-102行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L84-L102)

## 数据流架构

系统通过几个关键的数据流实现核心功能：

### 用户认证流程

```
"Database" --> "WeChatUserService" : "AuthController"
"AuthController" --> "User"
"Database" --> "WeChatUserService" : "AuthController"
"AuthController" --> "User"

alt [标准登录] [微信登录]
    "User" ->> "AuthController": 使用用户名/密码登录
    "AuthController" ->> "WeChatUserService": 认证
    "WeChatUserService" ->> "Database": 验证凭证
    "Database" ->> "AuthController": 用户信息
    "AuthController" ->> "User": 返回认证结果
    "User" ->> "Session token": 存储会话令牌
end

alt [微信登录]
    "User" ->> "AuthController": 使用微信登录
    "AuthController" ->> "WeChatUserService": 认证微信凭证
    "WeChatUserService" ->> "Database": 处理微信认证
    "Database" ->> "AuthController": 查找或创建用户
    "AuthController" ->> "User": 返回认证结果
    "User" ->> "Session token": 存储会话令牌
end
```

参考资料：[create_table.sql 第10-34行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/sql/create_table.sql#L10-L34)、[application.yml 第63-83行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/resources/application.yml#L63-L83)

### 学习进度跟踪

```
"Database" --> "AchievementService" : "StatsService"
"StatsService" --> "LearningService" : "Controller"
"Controller" --> "User"
"Database" --> "AchievementService" : "StatsService"
"StatsService" --> "LearningService" : "Controller"
"Controller" --> "User"

alt [成就解锁]
    "User" ->> "Controller": 完成学习活动
    "Controller" ->> "LearningService": 记录活动
    "LearningService" ->> "StatsService": 保存活动记录
    "StatsService" ->> "Database": 更新用户统计
    "Database" ->> "AchievementService": 更新学习统计数据
    "AchievementService" ->> "Controller": 检查成就条件
    "Controller" ->> "User": 解锁成就并通知用户
    "User" ->> "Updated stats": 显示进度
end
```

参考资料：[create_table.sql 第93-262行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/sql/create_table.sql#L93-L262)、[create_table.sql 第266-335行](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/sql/create_table.sql#L266-L335)

## 结论

SmartClass 后端采用结构良好的分层架构，实现了关注点分离，提高了可维护性。与 Dify AI 等外部服务的集成提供了强大的智能学习能力，而全面的数据模型支持广泛的教学功能。

系统的架构设计具有可扩展性和可伸缩性，能够支持未来功能和用户群的增长。模块化设计使得不同组件可以独立开发和测试。