Revert "Revert "使用通义灵码天假注释""

lib/apis/account.dart

@@ -2,76 +2,105 @@ part of apis;
 
 abstract class AccountAPI {
 
-  /// 1、登录
+    /// 登录功能
   ///
-  static Future <UserModel> login({
+  /// 参数：
+  /// - phone: 手机号码，必填。
+  /// - type: 登录类型，必填。'1'代表密码登录，'2'代表验证码登录。
+  /// - password: 登录密码，可选。仅在类型为'1'时需要。
+  /// - code: 验证码，可选。仅在类型为'2'时需要。
+  /// - uuid: 验证码的唯一标识，可选。仅在类型为'2'时需要。
+  ///
+  /// 返回值：
+  /// - UserModel: 登录成功时返回的用户模型实例。
+  /// - 如果登录失败或出现异常，可能返回空的UserModel实例。
+  static Future<UserModel> login({
     required String phone,
     required String type,
     String? password,
     String? code,
     String? uuid,
   }) async {
-    // assert((password != null && code == null) ||
-    //     (password == null && code != null),
-    // 'Provide either a password or a verification code, not both.');
-
-    Map<String,dynamic> params = {
-      'phone' : phone,
-      'type' : type,
+    Map<String, dynamic> params = {
+      'phone': phone,
+      'type': type,
     };
 
+    // 根据登录类型添加不同的登录参数
+    if (type == '1') {
       // 密码登录
-    if(type == '1'){
       params['password'] = password;
-    }
+    } else if (type == '2') {
       // 验证码登录
-    if(type == '2'){
       params['code'] = code;
       params['uuid'] = uuid;
     }
+
+    // 发起登录请求
     final result = await HttpService.to.post(
       '/v1/members/login/login',
       excludeToken: true,
       showLoading: true,
       params: params
     );
+
+    // 处理登录响应
     if (result.data is! Map) return UserModel();
     return UserModel.fromJson(result.data);
   }
 
-  /// 2、退出登录
+
+  /// 退出登录
   ///
+  /// 无参数。
+  /// 返回一个Future，如果退出登录成功，则返回true；否则返回false。
   static Future logout() async{
     final result = await HttpService.to.post(
       '/v1/members/login/logout',
       params: {}
     );
+    // 检查退出登录操作是否成功
     if (result.data is Map && result.data['is_success'] == 1){
       return true;
     }
     return false;
   }
 
-  /// 3、注销
+
+  /// 注销当前用户账号
+  ///
+  /// 本函数用于通过向服务器发送请求来注销当前用户的账号。
+  /// 注销成功时，返回值为true；注销失败时，返回值为false。
   ///
   static Future delete() async{
+    // 向服务器发送注销请求
     final result = await HttpService.to.post(
       '/v1/members/login/del',
       params: {}
     );
+    // 检查注销请求的响应结果
     if (result.data is Map && result.data['is_success'] == 1){
+      // 注销成功，返回true
       return true;
     }
+    // 注销失败，返回false
     return false;
   }
 
-  /// 4、发送验证码
+
+  /// 发送验证码
+  ///
+  /// 参数：
+  /// - phone: 需要发送验证码的手机号码，类型为 String，必需。
+  /// - type: 验证码的类型，例如注册、重置密码等，类型为 String，必需。
   ///
+  /// 返回值：
+  /// - Future<bool>: 若发送成功返回 true，否则返回 false。
   static Future sendCode({
     required String phone,
     required String type,
   }) async {
-
+    // 生成设备唯一标识符
     String uuid = '';
     final DeviceInfoPlugin device = DeviceInfoPlugin();
     if(Platform.isIOS){
@@ -82,9 +111,11 @@ abstract class AccountAPI {
       const androidIdPlugin = AndroidId();
       final AndroidDeviceInfo androidInfo = await device.androidInfo;
       uuid = await androidIdPlugin.getId()??'';
+      // 将设备ID与Android设备指纹组合以增加唯一性
       uuid = '$uuid${androidInfo.fingerprint}';
     }
 
+    // 调用HTTP服务发送验证码
     final result = await HttpService.to.post(
       '/v1/members/login/sendCode',
       params: {
@@ -92,23 +123,35 @@ abstract class AccountAPI {
         'types': type,
         'uuid':uuid
       },
-      excludeToken: true,
-      showLoading: true,
+      excludeToken: true, // 不包含令牌信息
+      showLoading: true, // 显示加载提示
     );
+    // 检查发送结果
     if (result.data is Map && result.data['is_success'] == 1){
-      return true;
+      return true; // 成功
     }
-    return false;
+    return false; // 失败
   }
 
-  /// 5、重置密码
+  /// 重置密码
+  ///
+  /// 使用该方法可以通过手机、验证码、新密码和确认新密码来重置用户的密码。
+  ///
+  /// 参数:
+  ///   - phone: 需要重置密码的用户的手机号码。
+  ///   - code: 验证码，发送到用户手机上的用于验证身份的代码。
+  ///   - password: 用户选择的新密码。
+  ///   - rePassword: 确认新密码，需要与新密码一致以确认输入无误。
   ///
+  /// 返回值:
+  ///   - 当密码重置成功时返回 true，否则返回 false。
   static Future resetPassword({
     required String phone,
     required String code,
     required String password,
     required String rePassword,
   }) async {
+    // 向服务器发送POST请求，提交手机、验证码、新密码和确认新密码以重置密码
     final result = await HttpService.to.post(
       '/v1/members/login/editPassword',
       params: {
@@ -117,20 +160,35 @@ abstract class AccountAPI {
         'password': password,
         'repassword': rePassword
       },
-      excludeToken: true,
-      showLoading: true,
+      excludeToken: true, // 不包含令牌信息，因为这是密码重置操作
+      showLoading: true, // 显示加载中的提示
     );
+
+    // 检查服务器返回的结果，如果操作成功，则返回true
     if (result.data is Map && result.data['is_success'] == 1){
       return true;
     }
+
+    // 如果操作失败或有错误，则返回false
     return false;
   }
 
-  /// 6、验证验证码
+  /// 验证验证码
+  ///
+  /// 通过手机号和验证码向服务器验证验证码的正确性。
+  ///
+  /// 参数：
+  /// - phone: 手机号，必填。
+  /// - code: 验证码，必填。
+  ///
+  /// 返回值：
+  /// - 若验证成功，返回true。
+  /// - 若验证失败，返回false。
   static Future checkCode({
     required String phone,
     required String code,
   }) async {
+    // 向服务器发送验证请求
     final result = await HttpService.to.post(
       '/v1/members/login/checkPhoneCode',
       params: {
@@ -140,6 +198,8 @@ abstract class AccountAPI {
       excludeToken: true,
       showLoading: true,
     );
+
+    // 检查验证结果
     if (result.data is Map && result.data['is_success'] == 1){
       return true;
     }
@@ -150,4 +210,5 @@ abstract class AccountAPI {
 
 
 
+
 }
\ No newline at end of file

lib/apis/course.dart

@@ -2,12 +2,19 @@ part of apis;
 
 abstract class CourseAPI {
 
-  /// 1、获取课程 内书籍列表
+  /// 获取课程内的书籍列表的异步方法。
   ///
+  /// 参数:
+  /// - page: 请求的页码，默认为1。
+  /// - limit: 每页的项数，默认为20。
+  ///
+  /// 返回值: 一个 Future 对象，解析为一个 CourseModel 类型的列表。
+  /// 如果请求失败或返回的数据不符合预期，则返回空列表。
   static Future <List<CourseModel>> list({
       int page = 1,
       int limit = 20,
     }) async {
+      // 向服务器发送 POST 请求，获取课程信息
       final result = await HttpService.to.post(
         '/v1/members/Information/myCourse',
         params: {
@@ -16,7 +23,11 @@ abstract class CourseAPI {
         },
         showLoading: true
       );
+
+      // 检查返回的数据是否符合预期格式
       if (result.data is! Map && result.data['list'] is! List) return [];
+
+      // 将返回的 JSON 数据转换为 CourseModel 对象列表
       return List.generate(result.data['list'].length, (index){
          return CourseModel.fromJson(result.data['list'][index]);
       });

lib/apis/shop.dart

@@ -2,45 +2,69 @@ part of apis;
 
 abstract class ShopAPI {
 
-  /// 1、加入书架
+  /// 加入书架
   ///
+  /// 参数：
+  ///   - bookId: 书籍的唯一标识符，必须提供。
+  ///
+  /// 返回值：
+  ///   布尔值，表示加入书架操作是否成功。成功返回true，失败返回false。
   static Future <bool> addCart({
     required String  bookId,
   }) async {
+    // 向服务器发送请求，将书籍添加到购物车
     final result = await HttpService.to.post(
       '/v1/orders/Orders/addCart',
       params: {
         'book_id':bookId,
       },
     );
+    // 检查服务器响应，判断添加操作是否成功
     if (result.data is Map && result.data['is_success'] == 1){
       return true;
     }
     return false;
   }
 
-  /// 2、删除书架
+
+  /// 删除书架
+  ///
+  /// 参数：
+  ///   - cartId: 购物车的唯一标识符，必须提供。
   ///
+  /// 返回值：
+  ///   布尔值，表示删除操作是否成功。成功返回true，失败返回false。
   static Future <bool> delCart({
     required String cartId,
   }) async {
+    // 向服务器发送删除购物车的请求
     final result = await HttpService.to.post(
       '/v1/orders/Orders/delCart',
       params: {
         'cart_id':cartId,
       },
     );
+    // 检查服务器返回的结果，判断删除是否成功
     if (result.data is Map && result.data['is_success'] == 1){
       return true;
     }
     return false;
   }
 
-  /// 3、书架列表
+
+  /// 获取购物车中的课程列表
+  ///
+  /// 参数:
+  ///   - page: 当前页码，默认为1
+  ///   - limit: 每页的数量，默认为10
+  ///
+  /// 返回值: 返回一个`Future`，这个`Future`解析为`List<CourseModel>`。
+  /// 如果请求成功，会返回课程列表的模型数组；如果请求失败或数据格式不正确，则返回空数组。
   static Future <List<CourseModel>> cart({
     int page = 1,
     int limit = 10,
   }) async {
+    // 向服务器发送POST请求，获取购物车列表数据
     final result = await HttpService.to.post(
       '/v1/orders/Orders/getCartListAll',
       params: {
@@ -48,18 +72,29 @@ abstract class ShopAPI {
         'page_size': limit,
       },
     );
+
+    // 检查返回的数据是否符合预期格式
     if (result.data is! Map && result.data['list'] is! List) return [];
+
+    // 将返回的JSON列表转换为`CourseModel`列表
     return List.generate(result.data['list'].length, (index){
       return CourseModel.fromJson(result.data['list'][index]);
     });
   }
 
-  /// 4、获取使用积分
+
+  /// 获取使用积分的函数
   ///
+  /// 参数：
+  /// - price: 商品价格，必填。
+  /// - couponRecId: 优惠券记录ID，必填。
+  ///
+  /// 返回值：一个 Future 对象，成功时返回 [CreditPointModel] 类的实例，失败时可能返回空实例。
   static Future <CreditPointModel> creditPoints({
     required String price,
     required String couponRecId,
   }) async {
+    // 向服务器发送 POST 请求，获取积分信息
     final result = await HttpService.to.post(
       '/v1/coupon/Coupon/getIntegral',
       params: {
@@ -67,37 +102,69 @@ abstract class ShopAPI {
         'coupon_rec_id': couponRecId
       },
     );
+
+    // 如果返回的数据不是 Map 类型，则返回一个空的 CreditPointModel 实例
     if (result.data is! Map ) return CreditPointModel();
+
+    // 将获取到的数据转换为 CreditPointModel 实例并返回
     return CreditPointModel.fromJson(result.data);
   }
 
-  /// 5、优惠券和积分是否展示
+
+  /// 查询优惠券和积分是否展示的设置
   ///
+  /// 该函数没有参数。
+  /// [返回值]
+  ///   - 返回一个`Future<ShowModel>`，表示异步获取的优惠券和积分展示设置的信息。
   static Future <ShowModel> show() async {
+    // 发起网络请求，获取优惠券和积分展示的设置信息
     final result = await HttpService.to.post(
       '/v1/orders/Orders/getSetting',
       params: {},
     );
+    // 如果返回的数据不是Map类型，则返回一个空的ShowModel实例
     if (result.data is! Map ) return ShowModel();
+    // 将获取到的数据转换为ShowModel对象并返回
     return ShowModel.fromJson(result.data);
   }
 
-  /// 6、 支付时选的优惠券列表
+
+  /// 获取支付时可选的优惠券列表
+  ///
+  /// 参数：
+  /// - page: 当前页码，默认为1
+  /// - limit: 每页数量，默认为10
+  /// - type: 优惠券类型，此次支付所适用的类型
+  /// - price: 支付金额，用于筛选适用的优惠券
+  ///
+  /// 返回值：一个 Future 对象，成功时返回 CouponListModel 类型的对象，表示优惠券列表信息。
   static Future<CouponListModel> coupon({
     int page = 1,
     int limit = 10,
     required String type,
     required String price
   }) async {
+    // 向服务器发送 POST 请求，获取优惠券列表数据
     final result = await HttpService.to.post(
       '/v1/coupon/Coupon/getCouponAll',
       params: {'page': page, 'page_size': limit, 'type': type,'price':price},
     );
+
+    // 如果请求结果不是 Map 类型，则返回一个空的 CouponListModel
     if (result.data is! Map ) return CouponListModel();
+
+    // 将请求结果转换为 CouponListModel 对象并返回
     return CouponListModel.fromJson(result.data);
   }
 
-  /// 7、获取优惠券可使用和不可使用数量
+
+  /// 获取优惠券可使用和不可使用数量
+  ///
+  /// 参数：
+  /// - price: 需要获取优惠券数量的商品价格，类型为String，必传。
+  ///
+  /// 返回值：
+  /// - CouponNumModel: 优惠券数量模型对象。如果请求成功，将返回包含可使用和不可使用优惠券数量的模型；如果请求失败或返回数据格式不符，将返回一个空的CouponNumModel实例。
   static Future<CouponNumModel> couponNum({
     required String price
   }) async {
@@ -107,20 +174,32 @@ abstract class ShopAPI {
         'price':price
       },
     );
+    // 判断返回的数据是否为Map类型
     if (result.data is! Map ) return CouponNumModel();
+    // 从返回的Map数据中构建CouponNumModel对象并返回
     return CouponNumModel.fromJson(result.data);
   }
 
-  /// 8、创建订单
+
+  /// 创建订单
+  ///
+  /// 参数：
+  /// - bookIdsList: 图书ID列表，表示用户购买的书籍ID集合。
+  /// - totalPrice: 总价格，表示购买所有书籍的总价。
+  /// - couponRecId: 优惠券记录ID，表示使用的优惠券的唯一标识。
+  /// - integral: 积分，表示使用了多少积分进行抵扣。
+  /// - type: 订单类型，标识是普通订单还是其他类型订单。
   ///
+  /// 返回值：返回一个Future，该Future解析为PayOrderModel类型，表示支付订单的模型。
   static Future <PayOrderModel> createOrder({
     required String bookIdsList,
     required String totalPrice,
     required String couponRecId,
     required String integral,
-    required String type
+    required String type,
 
   }) async {
+    // 向服务器发送POST请求，创建订单
     final result = await HttpService.to.post(
       '/v1/orders/Orders/createOrders',
       params: {
@@ -131,25 +210,45 @@ abstract class ShopAPI {
         'type':type,
       },
     );
+
+    // 如果返回的数据不是Map类型，则返回一个空的PayOrderModel实例
     if (result.data is! Map) return PayOrderModel();
+
+    // 将返回的数据解析为PayOrderModel类型并返回
     return PayOrderModel.fromJson(result.data);
   }
 
-  /// 9、获取订单状态
-  static Future <OrderStatusModel> orderStatus({
+
+  /// 获取订单状态
+  ///
+  /// 通过提供的订单号和收据信息，异步获取订单的当前状态。
+  ///
+  /// 参数:
+  /// - orderNumber: 订单号，必填。
+  /// - receipt: 收据信息，必填。
+  ///
+  /// 返回值:
+  /// - OrderStatusModel: 订单状态模型的实例，包含订单的详细状态信息。
+  static Future<OrderStatusModel> orderStatus({
     required String orderNumber,
-    required String receipt
+    required String receipt,
   }) async {
+    // 向服务器发送POST请求，获取订单状态
     final result = await HttpService.to.post(
       '/v1/orders/Orders/getOrdersStatus',
       params: {
-        'ordersnum':orderNumber,
-        'receipt':receipt
+        'ordersnum': orderNumber,
+        'receipt': receipt,
       },
     );
-    if (result.data is! Map ) return OrderStatusModel();
+
+    // 如果返回的数据不是Map类型，则返回一个空的订单状态模型实例
+    if (result.data is! Map) return OrderStatusModel();
+
+    // 将返回的JSON数据转换为OrderStatusModel实例并返回
     return OrderStatusModel.fromJson(result.data);
   }
 
 
+
 }
\ No newline at end of file