schoolNews/schoolNewsServ/achievement/docs/MIGRATION.md

成就模块迁移指南

📝 迁移概述

成就相关功能已从 usercenter 模块迁移到独立的 achievement 模块。

迁移日期

2025-10-24

迁移原因

• ✅ 模块职责分离 - usercenter负责用户中心，achievement专注于成就系统
• ✅ 更好的可维护性 - 独立模块易于管理和扩展
• ✅ 清晰的依赖关系 - 减少模块间的耦合
• ✅ 可扩展性 - 便于添加新的成就类型和功能

🔄 包路径变更

API接口变更

旧路径（已删除）：

org.xyzh.api.usercenter.achievement.UserAchievementService

新路径：

org.xyzh.api.achievement.AchievementService

服务实现变更

旧路径（已删除）：

org.xyzh.usercenter.service.UCUserAchievementService
org.xyzh.usercenter.service.impl.UCUserAchievementServiceImpl

新路径：

org.xyzh.api.achievement.AchievementService
org.xyzh.achievement.service.impl.ACHAchievementServiceImpl

Mapper变更

旧路径（已删除）：

org.xyzh.usercenter.mapper.AchievementMapper
org.xyzh.usercenter.mapper.UserAchievementMapper

新路径：

org.xyzh.achievement.mapper.AchievementMapper
org.xyzh.achievement.mapper.UserAchievementMapper
org.xyzh.achievement.mapper.UserAchievementProgressMapper  // 新增

Controller变更

旧路径（已删除）：

org.xyzh.usercenter.controller.UserAchievementController

新路径：

org.xyzh.achievement.controller.AchievementController

📦 依赖变更

如果你的模块之前依赖了成就功能

旧的依赖配置（需要删除）：

<dependency>
    <groupId>org.xyzh</groupId>
    <artifactId>api-usercenter</artifactId>  <!-- 包含成就接口 -->
    <version>1.0.0</version>
</dependency>

新的依赖配置（需要添加）：

<!-- 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. 更新导入语句

旧代码：

import org.xyzh.api.usercenter.achievement.UserAchievementService;

新代码：

import org.xyzh.api.achievement.AchievementService;

2. 更新服务注入

旧代码：

@Autowired
private UserAchievementService userAchievementService;

新代码：

@Autowired
private AchievementService achievementService;

3. 更新方法调用

大部分方法签名保持不变，只需更新服务名称：

旧代码：

ResultDomain<TbUserAchievement> result = userAchievementService.getUserAchievements(userID, type);

新代码：

ResultDomain<TbUserAchievement> result = achievementService.getUserAchievements(userID, type);

4. 新增功能调用

新的成就系统增加了事件驱动机制：

// 发布成就事件
AchievementEvent event = AchievementEvent.builder(userID, AchievementEventType.COURSE_COMPLETED)
    .value(1)
    .build();
    
// 方式1：使用Spring事件发布（推荐）
eventPublisher.publishEvent(event);

// 方式2：直接调用服务
achievementService.processAchievementEvent(event);

🗄️ 数据库变更

新增表

-- 用户成就进度表（新增）
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. 事件驱动机制

// 自动监听业务事件并触发成就检测
@Autowired
private ApplicationEventPublisher eventPublisher;

AchievementEvent event = AchievementEvent.builder(userID, eventType)
    .value(value)
    .build();
eventPublisher.publishEvent(event);

2. 成就进度追踪

// 查询用户的成就进度
ResultDomain<TbUserAchievementProgress> result = 
    achievementService.getMyAchievementProgress(achievementID);

3. 策略模式检测器

• 可扩展的成就检测器
• 支持多种成就类型
• 易于添加新的成就类型

4. 统计和排行榜

// 获取用户统计
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 语句为：

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依赖。

📚 相关文档

• 成就系统使用文档
• 数据库建表SQL

👥 联系支持

如果在迁移过程中遇到问题，请联系：

• 开发者：yslg
• 创建Issue或PR

---

迁移完成日期: 2025-10-24
版本: 1.0.0