# AI虚拟形象管理

相关源文件

- [AiAvatarController.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarController.java)
- [UserAiAvatarController.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java)
- [DeleteRequest.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/dto/DeleteRequest.java)
- [AiAvatar.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/entity/AiAvatar.java)
- [AiAvatarChatHistory.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/entity/AiAvatarChatHistory.java)
- [UserAiAvatar.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/entity/UserAiAvatar.java)
- [AchievementVO.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/vo/AchievementVO.java)
- [AiAvatarVO.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/vo/AiAvatarVO.java)
- [AnnouncementVO.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/vo/AnnouncementVO.java)
- [AiAvatarService.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/AiAvatarService.java)
- [AiAvatarServiceImpl.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/AiAvatarServiceImpl.java)
- [UserAiAvatarServiceImpl.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/UserAiAvatarServiceImpl.java)

## 目的和范围

本文档解释了SmartClass后端的AI虚拟形象管理子系统，重点介绍AI虚拟形象的创建、配置和管理。它涵盖了与AI虚拟形象相关的核心实体、操作和用户交互。有关这些虚拟形象的聊天功能详情，请参见[聊天会话管理](https://deepwiki.com/Ubanillx/smartclass-backend/2.2-chat-session-management)，关于底层AI集成的信息，请参见[Dify集成](https://deepwiki.com/Ubanillx/smartclass-backend/2.1-dify-integration)。

## 概述

AI虚拟形象管理系统允许创建和管理用户可以互动的AI角色。每个虚拟形象都有不同的特征，包括个性特征、专业能力和视觉表现。该系统支持虚拟形象创建和管理的管理操作，以及用户特定的交互，如收藏、评分和使用跟踪。

**图示：AI虚拟形象管理系统概览**

来源：[src/main/java/com/ubanillx/smartclass/controller/AiAvatarController.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarController.java) [src/main/java/com/ubanillx/smartclass/service/impl/AiAvatarServiceImpl.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/AiAvatarServiceImpl.java) [src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java) [src/main/java/com/ubanillx/smartclass/service/impl/UserAiAvatarServiceImpl.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/UserAiAvatarServiceImpl.java)

## 核心实体

AI虚拟形象管理系统围绕以下主要实体构建：

### AiAvatar

代表具有其特征和能力的AI人格的核心实体。

关键属性：

- **基本信息**：名称、描述、头像图片URL
- **性格**：性格特征、能力和标签
- **配置**：API请求的基础URL、认证
- **状态**：公开/私有设置、启用/禁用状态
- **统计数据**：使用次数、评分、排序优先级

### UserAiAvatar

表示用户和AI虚拟形象之间的关系及互动。

关键属性：

- **用户-虚拟形象关联**：链接用户到虚拟形象
- **互动数据**：收藏状态、使用次数、上次使用时间戳
- **反馈**：用户评分（1-5分制）、反馈评论
- **自定义**：特定于用户偏好的自定义设置

**图示：AI虚拟形象实体关系**

来源：[src/main/java/com/ubanillx/smartclass/model/entity/AiAvatar.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/entity/AiAvatar.java) [src/main/java/com/ubanillx/smartclass/model/entity/UserAiAvatar.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/entity/UserAiAvatar.java) [src/main/java/com/ubanillx/smartclass/model/entity/AiAvatarChatHistory.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/entity/AiAvatarChatHistory.java)

## 虚拟形象管理操作

### 创建虚拟形象

管理员和授权用户可以通过系统创建新的AI虚拟形象。创建过程需要：

- 基本资料信息（名称、描述、图像）
- 性格特征和能力定义
- 配置设置（API端点、身份验证）
- 可见性和状态设置

`AiAvatarController.addAiAvatar()` 方法 [src/main/java/com/ubanillx/smartclass/controller/AiAvatarController.java49-64](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarController.java#L49-L64) 处理虚拟形象创建请求，需要身份验证和权限验证。

### 更新虚拟形象

虚拟形象可以更新以修改其特征、外观或行为。系统支持增量更新，允许部分修改而不影响未更改的属性。这由 `AiAvatarController.updateAiAvatar()` [src/main/java/com/ubanillx/smartclass/controller/AiAvatarController.java100-173](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarController.java#L100-L173) 处理。

可更新的字段包括：

- 名称、描述和视觉外观
- 性格特征和能力
- API端点和身份验证
- 标签和分类
- 可见性和状态设置
- 排序优先级用于显示顺序

### 列出和检索虚拟形象

系统提供多种方法来列出和检索虚拟形象：

1. **获取单个虚拟形象**：通过ID检索特定虚拟形象
2. **列出所有虚拟形象**：获取完整列表（仅限管理员）
3. **分页列出**：带分页支持获取虚拟形象
4. **简要列出**：获取所有可用虚拟形象的简要信息

用户浏览可用虚拟形象的主要方法是 `AiAvatarService.listAllAiAvatarBrief()` [src/main/java/com/ubanillx/smartclass/service/impl/AiAvatarServiceImpl.java24-39](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/AiAvatarServiceImpl.java#L24-L39) 它只返回已启用虚拟形象的基本信息，按优先级排序。

### 删除虚拟形象

虚拟形象可以由其创建者或管理员删除，使用 `AiAvatarController.deleteAiAvatar()` [src/main/java/com/ubanillx/smartclass/controller/AiAvatarController.java73-91](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarController.java#L73-L91)

数据库UserServiceAiAvatarServiceAiAvatarController客户端数据库UserServiceAiAvatarServiceAiAvatarController客户端虚拟形象创建虚拟形象更新POST /ai_avatar/addgetLoginUser()用户对象验证权限save(aiAvatar)插入新记录成功/失败操作结果虚拟形象ID或错误POST /ai_avatar/updategetLoginUser()用户对象getById(id)选择记录虚拟形象数据虚拟形象对象验证所有权/权限应用增量更新updateById(aiAvatar)更新记录成功/失败操作结果成功/失败响应

**图示：虚拟形象管理操作**

来源：[src/main/java/com/ubanillx/smartclass/controller/AiAvatarController.java49-173](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarController.java#L49-L173)

# 用户-虚拟形象互动

用户可以通过多种方式与AI虚拟形象互动，不仅仅是聊天。系统会跟踪这些互动，并提供增强用户体验的功能。

### 收藏虚拟形象

用户可以将虚拟形象标记为收藏以便快速访问。该功能在以下文件中实现：

- `UserAiAvatarController.favoriteAiAvatar()` [src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java213-224](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java#L213-L224)
- `UserAiAvatarService.favoriteAiAvatar()` [src/main/java/com/ubanillx/smartclass/service/impl/UserAiAvatarServiceImpl.java44-67](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/UserAiAvatarServiceImpl.java#L44-L67)

系统要么创建新的用户-虚拟形象关系，要么用收藏状态更新现有的关系。

### 使用跟踪

每当用户与虚拟形象互动时，系统都会记录这种使用情况：

- `UserAiAvatarController.useAiAvatar()` [src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java232-241](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java#L232-L241)
- `UserAiAvatarService.useAiAvatar()` [src/main/java/com/ubanillx/smartclass/service/impl/UserAiAvatarServiceImpl.java69-104](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/UserAiAvatarServiceImpl.java#L69-L104)

跟踪包括：

- 增加用户的个人使用次数
- 更新虚拟形象的总体使用统计数据
- 记录最后使用时间戳

### 评分和反馈

用户可以为虚拟形象提供评分（1-5分制）和文本反馈：

- `UserAiAvatarController.rateAiAvatar()` [src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java252-264](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java#L252-L264)
- `UserAiAvatarService.rateAiAvatar()` [src/main/java/com/ubanillx/smartclass/service/impl/UserAiAvatarServiceImpl.java106-152](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/UserAiAvatarServiceImpl.java#L106-L152)

评分系统：

- 记录单个用户的评分
- 重新计算虚拟形象的平均评分
- 跟踪评分总数
- 存储可选的文本反馈

### 查看用户-虚拟形象关系

用户可以通过以下方法查看他们与虚拟形象的互动：

- `UserAiAvatarController.listMyUserAiAvatars()` [src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java171-176](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java#L171-L176)
- `UserAiAvatarController.listFavoriteAiAvatars()` [src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java272-277](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java#L272-L277)
- `UserAiAvatarService.getUserAiAvatarPage()` [src/main/java/com/ubanillx/smartclass/service/impl/UserAiAvatarServiceImpl.java154-191](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/UserAiAvatarServiceImpl.java#L154-L191)

数据库UserServiceUserAiAvatarServiceUserAiAvatarController用户客户端数据库UserServiceUserAiAvatarServiceUserAiAvatarController用户客户端收藏一个虚拟形象alt[关系存在][没有关系]给虚拟形象评分alt[关系存在][没有关系]POST /user_ai_avatar/favoritegetLoginUser()用户对象favoriteAiAvatar(userId, aiAvatarId, isFavorite)检查现有关系关系数据 (或null)更新收藏状态创建新关系操作结果成功/失败响应POST /user_ai_avatar/rategetLoginUser()用户对象rateAiAvatar(userId, aiAvatarId, rating, feedback)检查现有关系关系数据 (或null)更新用户评分和反馈useAiAvatar() 创建关系rateAiAvatar() 递归调用重新计算虚拟形象平均评分操作结果成功/失败响应

**图示：用户-虚拟形象互动流程**

来源：[src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java213-277](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java#L213-L277) [src/main/java/com/ubanillx/smartclass/service/impl/UserAiAvatarServiceImpl.java44-152](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/UserAiAvatarServiceImpl.java#L44-L152)

## API端点参考

AI虚拟形象管理系统暴露了以下关键API端点：

### 虚拟形象管理API

| 端点 | 方法 | 描述 | 认证 | 参考 |
|---|---|---|---|---|
| `/ai_avatar/add` | POST | 创建一个新的AI虚拟形象 | 需要(创建者) | [AiAvatarController.java49-64](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/AiAvatarController.java#L49-L64) |
| `/ai_avatar/update` | POST | 更新一个已有的虚拟形象 | 需要(所有者/管理员) | [AiAvatarController.java100-173](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/AiAvatarController.java#L100-L173) |
| `/ai_avatar/delete` | POST | 删除一个虚拟形象 | 需要(所有者/管理员) | [AiAvatarController.java73-91](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/AiAvatarController.java#L73-L91) |
| `/ai_avatar/get` | GET | 通过ID获取虚拟形象详情 | 公共 | [AiAvatarController.java181-193](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/AiAvatarController.java#L181-L193) |
| `/ai_avatar/list/all` | GET | 列出所有活动的虚拟形象（简要信息） | 公共 | [AiAvatarController.java264-268](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/AiAvatarController.java#L264-L268) |
| `/ai_avatar/list` | GET | 列出所有虚拟形象（管理员） | 需要(管理员) | [AiAvatarController.java202-218](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/AiAvatarController.java#L202-L218) |
| `/ai_avatar/list/page` | GET | 分页列出虚拟形象 | 公共 | [AiAvatarController.java227-257](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/AiAvatarController.java#L227-L257) |

### 用户-虚拟形象互动API

| 端点 | 方法 | 描述 | 认证 | 参考 |
|---|---|---|---|---|
| `/user_ai_avatar/favorite` | POST | 收藏或取消收藏虚拟形象 | 需要 | [UserAiAvatarController.java213-224](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/UserAiAvatarController.java#L213-L224) |
| `/user_ai_avatar/use` | POST | 记录虚拟形象使用情况 | 需要 | [UserAiAvatarController.java232-241](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/UserAiAvatarController.java#L232-L241) |
| `/user_ai_avatar/rate` | POST | 评分和提供反馈 | 需要 | [UserAiAvatarController.java252-264](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/UserAiAvatarController.java#L252-L264) |
| `/user_ai_avatar/my/list` | GET | 列出用户的虚拟形象互动 | 需要 | [UserAiAvatarController.java171-176](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/UserAiAvatarController.java#L171-L176) |
| `/user_ai_avatar/favorite/list` | GET | 列出用户的收藏虚拟形象 | 需要 | [UserAiAvatarController.java272-277](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/UserAiAvatarController.java#L272-L277) |
| `/user_ai_avatar/my/list/page` | GET | 分页列出互动 | 需要 | [UserAiAvatarController.java185-203](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/UserAiAvatarController.java#L185-L203) |

来源：[src/main/java/com/ubanillx/smartclass/controller/AiAvatarController.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarController.java) [src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/UserAiAvatarController.java)

# 实现细节

### 虚拟形象实体结构

核心实体`AiAvatar`包含了定义虚拟形象特性和集成细节的字段：

```
AiAvatar {
    id               - 唯一标识符
    name             - 显示名称
    baseUrl          - 虚拟形象API端点
    description      - 详细描述
    avatarImgUrl     - 视觉表示图片URL
    avatarAuth       - 认证令牌
    tags             - 分类标签（JSON数组）
    personality      - 性格描述
    abilities        - 功能能力描述
    isPublic         - 可见性标志（0=私有，1=公开）
    status           - 状态标志（0=禁用，1=启用）
    usageCount       - 使用统计
    rating           - 用户平均评分
    ratingCount      - 收到的评分数量
    creatorId        - 创建者用户ID
    sort             - 显示优先级排序
}
```

来源：[src/main/java/com/ubanillx/smartclass/model/entity/AiAvatar.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/entity/AiAvatar.java)

### 用户-虚拟形象关系结构

`UserAiAvatar`实体跟踪用户与虚拟形象的关系：

```
UserAiAvatar {
    id               - 唯一标识符
    userId           - 用户引用
    aiAvatarId       - 虚拟形象引用
    isFavorite       - 收藏状态（0=否，1=是）
    lastUseTime      - 最后互动时间戳
    useCount         - 用户个人使用次数
    userRating       - 用户评分（1-5分）
    userFeedback     - 用户反馈文本
    customSettings   - 用户特定设置（JSON格式）
}
```

来源：[src/main/java/com/ubanillx/smartclass/model/entity/UserAiAvatar.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/entity/UserAiAvatar.java)

## 最佳实践和注意事项

1. **虚拟形象创建**：
    
    - 提供描述性的性格和功能来创建独特的虚拟形象
    - 使用高质量图片以提高用户参与度
    - 为每种虚拟形象类型配置适当的API端点
    
2. **用户体验**：
    
    - 使用`sort`字段按受欢迎程度或相关性对虚拟形象排序
    - 推广高评分虚拟形象以改善用户发现
    - 跟踪用户收藏和使用模式以推荐虚拟形象
    
3. **性能**：
    
    - 在初始界面使用简要虚拟形象列表以减少数据负载
    - 对大量虚拟形象集合实现分页
    - 考虑缓存热门虚拟形象数据
    
4. **安全**：
    
    - 对虚拟形象管理操作执行适当的访问控制
    - 保护虚拟形象认证令牌
    - 验证用户输入，特别是评分和反馈

来源：[src/main/java/com/ubanillx/smartclass/service/impl/AiAvatarServiceImpl.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/AiAvatarServiceImpl.java) [src/main/java/com/ubanillx/smartclass/service/impl/UserAiAvatarServiceImpl.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/UserAiAvatarServiceImpl.java)