schoolNews/schoolNewsServ/achievement/docs/MIGRATION.md

# 成就模块迁移指南

## 📝 迁移概述

成就相关功能已从 `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