//
//  KBHomeVM.h
//  keyBoard
//
//  Created by Mac on 2025/12/3.
//

#import <Foundation/Foundation.h>

NS_ASSUME_NONNULL_BEGIN

@class KBCharacter;
@class KBTag;

/// 首页排行榜回调
typedef void(^KBHomeRankCompletion)(NSArray<KBCharacter *> * _Nullable list,
                                    NSError * _Nullable error);

/// 首页标签回调
typedef void(^KBHomeTagCompletion)(NSArray<KBTag *> * _Nullable list,
                                   NSError * _Nullable error);

/// 添加用户人设回调
typedef void(^KBHomeAddUserCharacterCompletion)(BOOL success,
                                                NSError * _Nullable error);

@interface KBHomeVM : NSObject

/// 最近一次成功请求到的排行榜数据
@property (nonatomic, copy, readonly, nullable) NSArray<KBCharacter *> *rankList;

/// 最近一次成功请求到的标签数据
@property (nonatomic, copy, readonly, nullable) NSArray<KBTag *> *tagList;

/// 请求排行榜列表（GET /character/list）
/// - Parameters:
///   - params: 额外查询参数（可为空），例如分页、筛选 tag 等；
///   - needShow: 是否在请求期间显示加载 HUD；
///   - completion: 回调，list 为解析后的模型数组，error 非空表示失败。
- (void)fetchRankListWithParams:(nullable NSDictionary *)params
                       needShow:(BOOL)needShow
                     completion:(KBHomeRankCompletion)completion;

/// 根据 tagId 获取角色列表（GET /character/listByTag）
- (void)fetchRankListByTagId:(nullable NSString *)tagId
                    needShow:(BOOL)needShow
                  completion:(KBHomeRankCompletion)completion;

/// 请求排行榜标签列表（GET /tag/list）
/// - Parameters:
///   - params: 额外查询参数（可为空）；
///   - needShow: 是否在请求期间显示加载 HUD；
///   - completion: 回调，list 为解析后的标签数组，error 非空表示失败。
- (void)fetchTagListWithParams:(nullable NSDictionary *)params
                      needShow:(BOOL)needShow
                    completion:(KBHomeTagCompletion)completion;

/// 添加用户人设（例如在首页排行榜中点 “+”）
/// GET /character/addUserCharacter?id={characterId}
- (void)addUserCharacterWithId:(NSNumber *)characterId
                    completion:(KBHomeAddUserCharacterCompletion)completion;

@end

NS_ASSUME_NONNULL_END