serv-成就模块初始
This commit is contained in:
331
schoolNewsServ/achievement/docs/MIGRATION.md
Normal file
331
schoolNewsServ/achievement/docs/MIGRATION.md
Normal file
@@ -0,0 +1,331 @@
|
||||
# 成就模块迁移指南
|
||||
|
||||
## 📝 迁移概述
|
||||
|
||||
成就相关功能已从 `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>${school-news.version}</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
#### 新的依赖配置（需要添加）：
|
||||
```xml
|
||||
<!-- API接口依赖 -->
|
||||
<dependency>
|
||||
<groupId>org.xyzh</groupId>
|
||||
<artifactId>api-achievement</artifactId>
|
||||
<version>${school-news.version}</version>
|
||||
</dependency>
|
||||
|
||||
<!-- 如果需要使用实现类（通常不需要，使用Dubbo远程调用） -->
|
||||
<dependency>
|
||||
<groupId>org.xyzh</groupId>
|
||||
<artifactId>achievement</artifactId>
|
||||
<version>${school-news.version}</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
|
||||
|
||||
Reference in New Issue
Block a user