2

keyBoard/Class/Home/M/KBCharacter.h

@@ -0,0 +1,50 @@
+//
+//  KBCharacter.h
+//  首页 - 排行榜角色模型（MJExtension 解析）
+//
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// 排行榜角色/角色卡片模型
+/// 对应后端返回字段：
+/// {
+///   "id": 0,
+///   "title": "",
+///   "characterBackground": "",
+///   "avatarUrl": "",
+///   "download": "",
+///   "tag": 0,
+///   "rank": 0
+/// }
+@interface KBCharacter : NSObject
+
+/// 唯一标识，对应后端的 id
+@property (nonatomic, copy, nullable) NSString *characterId;
+
+/// 标题/名称
+@property (nonatomic, copy, nullable) NSString *title;
+
+/// 角色背景（颜色值、图片地址或后端定义的 key）
+@property (nonatomic, copy, nullable) NSString *characterBackground;
+
+/// 头像地址
+@property (nonatomic, copy, nullable) NSString *avatarUrl;
+
+/// 下载量文案或数值（后端返回字符串）
+@property (nonatomic, copy, nullable) NSString *download;
+
+/// 标签（例如分类、类型）原样保存
+@property (nonatomic, assign) NSInteger tag;
+
+/// 排名序号（1、2、3...）
+@property (nonatomic, assign) NSInteger rank;
+
+/// 本地字段：是否已添加到键盘（仅客户端使用）
+@property (nonatomic, assign) BOOL added;
+
+@end
+
+NS_ASSUME_NONNULL_END
+

keyBoard/Class/Home/M/KBCharacter.m

@@ -0,0 +1,18 @@
+//
+//  KBCharacter.m
+//
+
+#import "KBCharacter.h"
+#import <MJExtension/MJExtension.h>
+
+@implementation KBCharacter
+
++ (NSDictionary *)mj_replacedKeyFromPropertyName {
+    // 后端字段 id -> characterId
+    return @{
+        @"characterId": @"id"
+    };
+}
+
+@end
+

keyBoard/Class/Home/VM/KBHomeVM.h

@@ -0,0 +1,34 @@
+//
+//  KBHomeVM.h
+//  keyBoard
+//
+//  Created by Mac on 2025/12/3.
+//
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@class KBCharacter;
+
+/// 首页排行榜回调
+typedef void(^KBHomeRankCompletion)(NSArray<KBCharacter *> * _Nullable list,
+                                    NSError * _Nullable error);
+
+@interface KBHomeVM : NSObject
+
+/// 最近一次成功请求到的排行榜数据
+@property (nonatomic, copy, readonly, nullable) NSArray<KBCharacter *> *rankList;
+
+/// 请求排行榜列表（GET /character/list）
+/// - Parameters:
+///   - params: 额外查询参数（可为空），例如分页、筛选 tag 等；
+///   - needShow: 是否在请求期间显示加载 HUD；
+///   - completion: 回调，list 为解析后的模型数组，error 非空表示失败。
+- (void)fetchRankListWithParams:(nullable NSDictionary *)params
+                       needShow:(BOOL)needShow
+                     completion:(KBHomeRankCompletion)completion;
+
+@end
+
+NS_ASSUME_NONNULL_END

keyBoard/Class/Home/VM/KBHomeVM.m

@@ -0,0 +1,68 @@
+//
+//  KBHomeVM.m
+//  keyBoard
+//
+//  Created by Mac on 2025/12/3.
+//
+
+#import "KBHomeVM.h"
+#import "KBCharacter.h"
+#import "KBNetworkManager.h"
+#import "KBHUD.h"
+#import "KBBizCode.h"
+
+@interface KBHomeVM ()
+@property (nonatomic, copy, readwrite, nullable) NSArray<KBCharacter *> *rankList;
+@end
+
+@implementation KBHomeVM
+
+- (void)fetchRankListWithParams:(nullable NSDictionary *)params
+                       needShow:(BOOL)needShow
+                     completion:(KBHomeRankCompletion)completion {
+    if (needShow) {
+        [KBHUD show];
+    }
+
+    [[KBNetworkManager shared] GET:KB_API_CHARACTER_LIST
+                        parameters:params
+                           headers:nil
+              autoShowBusinessError:NO
+                        completion:^(NSDictionary * _Nullable json, NSURLResponse * _Nullable response, NSError * _Nullable error) {
+        if (needShow) {
+            [KBHUD dismiss];
+        }
+
+        if (error) {
+            // 若是业务错误，优先展示服务端 message
+            NSString *msg = KBBizMessageFromJSONObject(json) ?: error.localizedDescription ?: KBLocalized(@"Network error");
+            [KBHUD showInfo:msg];
+            if (completion) {
+                completion(nil, error);
+            }
+            return;
+        }
+
+        id dataObj = json[KBData] ?: json[@"data"];
+        if (![dataObj isKindOfClass:[NSArray class]]) {
+            NSError *e = [NSError errorWithDomain:KBNetworkErrorDomain
+                                             code:KBNetworkErrorInvalidResponse
+                                         userInfo:@{NSLocalizedDescriptionKey: KBLocalized(@"Invalid response")}];
+            [KBHUD showInfo:e.localizedDescription];
+            if (completion) {
+                completion(nil, e);
+            }
+            return;
+        }
+
+        // 使用 MJExtension 将数组字典解析为模型数组
+        NSArray<KBCharacter *> *list = [KBCharacter mj_objectArrayWithKeyValuesArray:(NSArray *)dataObj];
+        self.rankList = list;
+
+        if (completion) {
+            completion(list, nil);
+        }
+    }];
+}
+
+@end