package org.xyzh.api.achievement;

import org.xyzh.common.core.domain.ResultDomain;
import org.xyzh.common.core.event.AchievementEvent;
import org.xyzh.common.core.page.PageDomain;
import org.xyzh.common.core.page.PageParam;
import org.xyzh.common.dto.usercenter.TbAchievement;
import org.xyzh.common.dto.usercenter.TbUserAchievement;
import org.xyzh.common.dto.usercenter.TbUserAchievementProgress;

import java.util.List;
import java.util.Map;

/**
 * @description 成就服务接口
 * @filename AchievementService.java
 * @author yslg
 * @copyright xyzh
 * @since 2025-10-24
 */
public interface AchievementService {

    // ==================== 成就定义管理 ====================
    
    /**
     * @description 创建成就
     * @param achievement 成就信息
     * @return ResultDomain<TbAchievement> 创建结果
     */
    ResultDomain<TbAchievement> createAchievement(TbAchievement achievement);
    
    /**
     * @description 更新成就
     * @param achievement 成就信息
     * @return ResultDomain<TbAchievement> 更新结果
     */
    ResultDomain<TbAchievement> updateAchievement(TbAchievement achievement);
    
    /**
     * @description 删除成就
     * @param achievementID 成就ID
     * @return ResultDomain<Void> 删除结果
     */
    ResultDomain<Void> deleteAchievement(String achievementID);
    
    /**
     * @description 获取所有成就列表
     * @param type 成就类型（可选）
     * @param level 成就等级（可选）
     * @return ResultDomain<TbAchievement> 成就列表
     */
    ResultDomain<TbAchievement> getAllAchievements(Integer type, Integer level);
    
    /**
     * @description 分页查询成就
     * @param filter 过滤条件
     * @param pageParam 分页参数
     * @return ResultDomain<TbAchievement> 成就分页数据
     */
    ResultDomain<TbAchievement> getAchievementPage(TbAchievement filter, PageParam pageParam);
    
    /**
     * @description 获取成就详情
     * @param achievementID 成就ID
     * @return ResultDomain<TbAchievement> 成就详情
     */
    ResultDomain<TbAchievement> getAchievementDetail(String achievementID);
    
    // ==================== 用户成就管理 ====================
    
    /**
     * @description 获取用户已获得的成就
     * @param userID 用户ID
     * @param type 成就类型（可选）
     * @return ResultDomain<TbUserAchievement> 用户成就列表
     */
    ResultDomain<TbUserAchievement> getUserAchievements(String userID, Integer type);
    
    /**
     * @description 获取当前用户的成就列表
     * @param type 成就类型（可选）
     * @return ResultDomain<TbUserAchievement> 用户成就列表
     */
    ResultDomain<TbUserAchievement> getMyAchievements(Integer type);
    
    /**
     * @description 检查用户是否已获得成就
     * @param userID 用户ID
     * @param achievementID 成就ID
     * @return ResultDomain<Boolean> 是否已获得
     */
    ResultDomain<Boolean> hasAchievement(String userID, String achievementID);
    
    /**
     * @description 手动授予用户成就（管理员功能）
     * @param userID 用户ID
     * @param achievementID 成就ID
     * @return ResultDomain<TbUserAchievement> 授予结果
     */
    ResultDomain<TbUserAchievement> grantAchievement(String userID, String achievementID);
    
    /**
     * @description 撤销用户成就（管理员功能）
     * @param userID 用户ID
     * @param achievementID 成就ID
     * @return ResultDomain<Void> 撤销结果
     */
    ResultDomain<Void> revokeAchievement(String userID, String achievementID);
    
    // ==================== 成就进度管理 ====================
    
    /**
     * @description 获取用户成就进度
     * @param userID 用户ID
     * @param achievementID 成就ID（可选，为空则获取所有进度）
     * @return ResultDomain<TbUserAchievementProgress> 成就进度列表
     */
    ResultDomain<TbUserAchievementProgress> getUserAchievementProgress(String userID, String achievementID);
    
    /**
     * @description 获取当前用户的成就进度
     * @param achievementID 成就ID（可选）
     * @return ResultDomain<TbUserAchievementProgress> 成就进度列表
     */
    ResultDomain<TbUserAchievementProgress> getMyAchievementProgress(String achievementID);
    
    /**
     * @description 更新用户成就进度
     * @param userID 用户ID
     * @param achievementID 成就ID
     * @param incrementValue 增量值
     * @return ResultDomain<TbUserAchievementProgress> 更新后的进度
     */
    ResultDomain<TbUserAchievementProgress> updateProgress(String userID, String achievementID, Integer incrementValue);
    
    // ==================== 成就检测与触发 ====================
    
    /**
     * @description 处理成就事件（核心方法）
     * @param event 成就事件
     * @return ResultDomain<List<TbUserAchievement>> 本次触发的成就列表
     */
    ResultDomain<List<TbUserAchievement>> processAchievementEvent(AchievementEvent event);
    
    /**
     * @description 检查用户是否满足成就条件
     * @param userID 用户ID
     * @param achievementID 成就ID
     * @return ResultDomain<Boolean> 是否满足条件
     */
    ResultDomain<Boolean> checkAchievementCondition(String userID, String achievementID);
    
    /**
     * @description 批量检查用户可获得的成就
     * @param userID 用户ID
     * @return ResultDomain<List<TbAchievement>> 可获得的成就列表
     */
    ResultDomain<List<TbAchievement>> checkAvailableAchievements(String userID);
    
    // ==================== 成就统计 ====================
    
    /**
     * @description 获取用户成就统计
     * @param userID 用户ID
     * @return ResultDomain<Map<String, Object>> 统计信息
     */
    ResultDomain<Map<String, Object>> getUserAchievementStatistics(String userID);
    
    /**
     * @description 获取成就排行榜
     * @param limit 排行榜条数
     * @return ResultDomain<Map<String, Object>> 排行榜数据
     */
    ResultDomain<Map<String, Object>> getAchievementRanking(Integer limit);
    
    /**
     * @description 获取最近获得成就的用户
     * @param achievementID 成就ID
     * @param limit 查询条数
     * @return ResultDomain<List<TbUserAchievement>> 用户成就列表
     */
    ResultDomain<List<TbUserAchievement>> getRecentAchievers(String achievementID, Integer limit);
}

