332 lines
8.3 KiB
Markdown
332 lines
8.3 KiB
Markdown
# 成就模块迁移指南
|
||
|
||
## 📝 迁移概述
|
||
|
||
成就相关功能已从 `usercenter` 模块迁移到独立的 `achievement` 模块。
|
||
|
||
### 迁移日期
|
||
2025-10-24
|
||
|
||
### 迁移原因
|
||
- ✅ **模块职责分离** - usercenter负责用户中心，achievement专注于成就系统
|
||
- ✅ **更好的可维护性** - 独立模块易于管理和扩展
|
||
- ✅ **清晰的依赖关系** - 减少模块间的耦合
|
||
- ✅ **可扩展性** - 便于添加新的成就类型和功能
|
||
|
||
## 🔄 包路径变更
|
||
|
||
### API接口变更
|
||
|
||
**旧路径（已删除）：**
|
||
```java
|
||
org.xyzh.api.usercenter.achievement.UserAchievementService
|
||
```
|
||
|
||
**新路径：**
|
||
```java
|
||
org.xyzh.api.achievement.AchievementService
|
||
```
|
||
|
||
### 服务实现变更
|
||
|
||
**旧路径（已删除）：**
|
||
```java
|
||
org.xyzh.usercenter.service.UCUserAchievementService
|
||
org.xyzh.usercenter.service.impl.UCUserAchievementServiceImpl
|
||
```
|
||
|
||
**新路径：**
|
||
```java
|
||
org.xyzh.api.achievement.AchievementService
|
||
org.xyzh.achievement.service.impl.ACHAchievementServiceImpl
|
||
```
|
||
|
||
### Mapper变更
|
||
|
||
**旧路径（已删除）：**
|
||
```java
|
||
org.xyzh.usercenter.mapper.AchievementMapper
|
||
org.xyzh.usercenter.mapper.UserAchievementMapper
|
||
```
|
||
|
||
**新路径：**
|
||
```java
|
||
org.xyzh.achievement.mapper.AchievementMapper
|
||
org.xyzh.achievement.mapper.UserAchievementMapper
|
||
org.xyzh.achievement.mapper.UserAchievementProgressMapper // 新增
|
||
```
|
||
|
||
### Controller变更
|
||
|
||
**旧路径（已删除）：**
|
||
```java
|
||
org.xyzh.usercenter.controller.UserAchievementController
|
||
```
|
||
|
||
**新路径：**
|
||
```java
|
||
org.xyzh.achievement.controller.AchievementController
|
||
```
|
||
|
||
## 📦 依赖变更
|
||
|
||
### 如果你的模块之前依赖了成就功能
|
||
|
||
#### 旧的依赖配置（需要删除）：
|
||
```xml
|
||
<dependency>
|
||
<groupId>org.xyzh</groupId>
|
||
<artifactId>api-usercenter</artifactId> <!-- 包含成就接口 -->
|
||
<version>1.0.0</version>
|
||
</dependency>
|
||
```
|
||
|
||
#### 新的依赖配置（需要添加）：
|
||
```xml
|
||
<!-- API接口依赖 -->
|
||
<dependency>
|
||
<groupId>org.xyzh</groupId>
|
||
<artifactId>api-achievement</artifactId>
|
||
<version>1.0.0</version>
|
||
</dependency>
|
||
|
||
<!-- 如果需要使用实现类（通常不需要，使用Dubbo远程调用） -->
|
||
<dependency>
|
||
<groupId>org.xyzh</groupId>
|
||
<artifactId>achievement</artifactId>
|
||
<version>1.0.0</version>
|
||
</dependency>
|
||
```
|
||
|
||
## 🔧 代码迁移步骤
|
||
|
||
### 1. 更新导入语句
|
||
|
||
**旧代码：**
|
||
```java
|
||
import org.xyzh.api.usercenter.achievement.UserAchievementService;
|
||
```
|
||
|
||
**新代码：**
|
||
```java
|
||
import org.xyzh.api.achievement.AchievementService;
|
||
```
|
||
|
||
### 2. 更新服务注入
|
||
|
||
**旧代码：**
|
||
```java
|
||
@Autowired
|
||
private UserAchievementService userAchievementService;
|
||
```
|
||
|
||
**新代码：**
|
||
```java
|
||
@Autowired
|
||
private AchievementService achievementService;
|
||
```
|
||
|
||
### 3. 更新方法调用
|
||
|
||
大部分方法签名保持不变，只需更新服务名称：
|
||
|
||
**旧代码：**
|
||
```java
|
||
ResultDomain<TbUserAchievement> result = userAchievementService.getUserAchievements(userID, type);
|
||
```
|
||
|
||
**新代码：**
|
||
```java
|
||
ResultDomain<TbUserAchievement> result = achievementService.getUserAchievements(userID, type);
|
||
```
|
||
|
||
### 4. 新增功能调用
|
||
|
||
新的成就系统增加了事件驱动机制：
|
||
|
||
```java
|
||
// 发布成就事件
|
||
AchievementEvent event = AchievementEvent.builder(userID, AchievementEventType.COURSE_COMPLETED)
|
||
.value(1)
|
||
.build();
|
||
|
||
// 方式1：使用Spring事件发布（推荐）
|
||
eventPublisher.publishEvent(event);
|
||
|
||
// 方式2：直接调用服务
|
||
achievementService.processAchievementEvent(event);
|
||
```
|
||
|
||
## 🗄️ 数据库变更
|
||
|
||
### 新增表
|
||
|
||
```sql
|
||
-- 用户成就进度表（新增）
|
||
CREATE TABLE tb_user_achievement_progress (
|
||
id VARCHAR(32) NOT NULL,
|
||
user_id VARCHAR(32) NOT NULL,
|
||
achievement_id VARCHAR(32) NOT NULL,
|
||
current_value INT DEFAULT 0,
|
||
target_value INT DEFAULT 0,
|
||
progress_percentage INT DEFAULT 0,
|
||
completed TINYINT(1) DEFAULT 0,
|
||
last_update_time DATETIME,
|
||
create_time DATETIME,
|
||
PRIMARY KEY (id),
|
||
UNIQUE KEY uk_user_achievement_progress (user_id, achievement_id)
|
||
);
|
||
```
|
||
|
||
### 已有表
|
||
|
||
`tb_achievement` 和 `tb_user_achievement` 表结构保持不变，无需迁移数据。
|
||
|
||
## 🌐 REST API变更
|
||
|
||
### 接口路径变更
|
||
|
||
**旧路径：**
|
||
```
|
||
/usercenter/achievement/*
|
||
```
|
||
|
||
**新路径：**
|
||
```
|
||
/achievement/*
|
||
```
|
||
|
||
### 具体接口映射
|
||
|
||
| 功能 | 旧接口 | 新接口 | 变化 |
|
||
|-----|-------|-------|-----|
|
||
| 获取所有成就 | GET /usercenter/achievement/list | GET /achievement/list | 路径变更 |
|
||
| 获取用户成就 | GET /usercenter/achievement/user/{userID} | GET /achievement/user/{userID} | 路径变更 |
|
||
| 获取我的成就 | - | GET /achievement/my | **新增** |
|
||
| 授予成就 | POST /usercenter/achievement/grant | POST /achievement/grant | 路径变更 |
|
||
| 检查条件 | GET /usercenter/achievement/condition/{userID}/{achievementID} | GET /achievement/condition/check/{userID}/{achievementID} | 路径变更 |
|
||
| 获取进度 | - | GET /achievement/progress/{userID} | **新增** |
|
||
| 处理事件 | - | POST /achievement/event/process | **新增** |
|
||
| 获取统计 | - | GET /achievement/statistics/{userID} | **新增** |
|
||
| 排行榜 | - | GET /achievement/ranking | **新增** |
|
||
|
||
## ✨ 新增功能
|
||
|
||
### 1. 事件驱动机制
|
||
```java
|
||
// 自动监听业务事件并触发成就检测
|
||
@Autowired
|
||
private ApplicationEventPublisher eventPublisher;
|
||
|
||
AchievementEvent event = AchievementEvent.builder(userID, eventType)
|
||
.value(value)
|
||
.build();
|
||
eventPublisher.publishEvent(event);
|
||
```
|
||
|
||
### 2. 成就进度追踪
|
||
```java
|
||
// 查询用户的成就进度
|
||
ResultDomain<TbUserAchievementProgress> result =
|
||
achievementService.getMyAchievementProgress(achievementID);
|
||
```
|
||
|
||
### 3. 策略模式检测器
|
||
- 可扩展的成就检测器
|
||
- 支持多种成就类型
|
||
- 易于添加新的成就类型
|
||
|
||
### 4. 统计和排行榜
|
||
```java
|
||
// 获取用户统计
|
||
ResultDomain<Map<String, Object>> stats =
|
||
achievementService.getUserAchievementStatistics(userID);
|
||
|
||
// 获取排行榜
|
||
ResultDomain<Map<String, Object>> ranking =
|
||
achievementService.getAchievementRanking(10);
|
||
```
|
||
|
||
## 🚨 注意事项
|
||
|
||
### 1. 破坏性变更
|
||
|
||
#### ❌ 已删除的类（不再可用）
|
||
- `org.xyzh.api.usercenter.achievement.UserAchievementService`
|
||
- `org.xyzh.usercenter.service.UCUserAchievementService`
|
||
- `org.xyzh.usercenter.mapper.AchievementMapper`
|
||
- `org.xyzh.usercenter.controller.UserAchievementController`
|
||
|
||
#### ✅ 对应的新类
|
||
- `org.xyzh.api.achievement.AchievementService`
|
||
- `org.xyzh.achievement.service.impl.ACHAchievementServiceImpl`
|
||
- `org.xyzh.achievement.mapper.AchievementMapper`
|
||
- `org.xyzh.achievement.controller.AchievementController`
|
||
|
||
### 2. 接口变化
|
||
|
||
新的 `AchievementService` 接口方法更多、更完善：
|
||
- ✅ 所有旧方法都有对应的新方法
|
||
- ✅ 新增了事件处理、进度查询、统计等功能
|
||
- ✅ 方法签名大部分保持兼容
|
||
|
||
### 3. 前端调用
|
||
|
||
如果你的前端代码调用了成就相关API，需要：
|
||
1. 更新API路径：`/usercenter/achievement/*` → `/achievement/*`
|
||
2. 检查返回数据格式（大部分保持兼容）
|
||
3. 利用新增的API（进度、统计、排行榜等）
|
||
|
||
## 📋 迁移检查清单
|
||
|
||
迁移时请检查以下项目：
|
||
|
||
- [ ] 更新 pom.xml 依赖
|
||
- [ ] 更新 import 语句
|
||
- [ ] 更新服务注入
|
||
- [ ] 更新方法调用
|
||
- [ ] 测试成就创建功能
|
||
- [ ] 测试成就授予功能
|
||
- [ ] 测试成就查询功能
|
||
- [ ] 测试事件触发功能（如有）
|
||
- [ ] 更新前端API路径（如有）
|
||
- [ ] 更新相关文档
|
||
- [ ] 执行集成测试
|
||
|
||
## 🆘 常见问题
|
||
|
||
### Q1: 编译报错找不到 UserAchievementService
|
||
**A:** 更新 import 语句为：
|
||
```java
|
||
import org.xyzh.api.achievement.AchievementService;
|
||
```
|
||
|
||
### Q2: 旧的成就数据会丢失吗？
|
||
**A:** 不会。数据库表结构保持不变，所有数据完整保留。
|
||
|
||
### Q3: 需要修改数据库吗？
|
||
**A:** 需要执行新表创建SQL（`tb_user_achievement_progress`），见 `.bin/mysql/sql/createTableAchievement.sql`。
|
||
|
||
### Q4: 如何使用新的事件驱动功能？
|
||
**A:** 参考 `README.md` 中的"使用方法"章节。
|
||
|
||
### Q5: admin模块已经自动配置好了吗？
|
||
**A:** 是的，admin模块的pom.xml已自动添加achievement依赖。
|
||
|
||
## 📚 相关文档
|
||
|
||
- [成就系统使用文档](../README.md)
|
||
- [数据库建表SQL](../../.bin/mysql/sql/createTableAchievement.sql)
|
||
|
||
## 👥 联系支持
|
||
|
||
如果在迁移过程中遇到问题，请联系：
|
||
- 开发者：yslg
|
||
- 创建Issue或PR
|
||
|
||
---
|
||
|
||
**迁移完成日期**: 2025-10-24
|
||
**版本**: 1.0.0
|
||
|