瀑布流

docs/api/response.php

@@ -7,6 +7,13 @@
  * - MessagePack: 二进制格式，体积小30-50%，解析更快
  * - Gzip: 压缩JSON，减少传输大小
  * - CBOR: 二进制JSON，RFC 8949标准
+ * 
+ * @file      response.php
+ * @author    AI Assistant
+ * @date      2026-04-12
+ * @version   2.1.0
+ * @desc      API响应格式处理，包含评分格式化工具
+ * @lastUpdate 2026-04-12 新增评分格式化函数，处理边缘情况
  */
 
 class ApiResponse {
@@ -207,6 +214,103 @@ class ApiResponse {
             return $bytes . ' B';
         }
     }
+    
+    /**
+     * 格式化评分显示
+     * 处理边缘情况：暂无评分、评分数量少、评分异常
+     * 
+     * @param float $score 平均评分
+     * @param int $nums 评分次数
+     * @return array 格式化后的评分信息
+     */
+    public static function formatRating($score, $nums) {
+        $result = array(
+            'score' => 0.00,
+            'nums' => 0,
+            'display' => '暂无评分',
+            'status' => 'none',
+            'level' => '',
+            'star' => 0
+        );
+        
+        if ($nums <= 0) {
+            return $result;
+        }
+        
+        $score = (float) $score;
+        $nums = (int) $nums;
+        
+        if ($score < 0 || $score > 5) {
+            $result['status'] = 'abnormal';
+            $result['display'] = '评分异常';
+            return $result;
+        }
+        
+        $result['score'] = round($score, 2);
+        $result['nums'] = $nums;
+        $result['star'] = round($score);
+        
+        if ($nums < 3) {
+            $result['status'] = 'few';
+            $result['display'] = sprintf('%.1f分 (%d人评分，样本较少)', $score, $nums);
+        } elseif ($nums < 10) {
+            $result['status'] = 'normal';
+            $result['display'] = sprintf('%.1f分 (%d人评分)', $score, $nums);
+        } else {
+            $result['status'] = 'sufficient';
+            $result['display'] = sprintf('%.1f分 (%d人评分)', $score, $nums);
+        }
+        
+        if ($score >= 4.5) {
+            $result['level'] = '优秀';
+        } elseif ($score >= 4.0) {
+            $result['level'] = '推荐';
+        } elseif ($score >= 3.0) {
+            $result['level'] = '一般';
+        } elseif ($score >= 2.0) {
+            $result['level'] = '较差';
+        } else {
+            $result['level'] = '不推荐';
+        }
+        
+        return $result;
+    }
+    
+    /**
+     * 获取评分统计信息（用于列表显示）
+     * 
+     * @param float $score 平均评分
+     * @param int $nums 评分次数
+     * @return array 简化的评分信息
+     */
+    public static function getRatingSummary($score, $nums) {
+        if ($nums <= 0) {
+            return array(
+                'score' => 0.00,
+                'nums' => 0,
+                'display' => '暂无评分',
+                'star' => 0
+            );
+        }
+        
+        $score = (float) $score;
+        
+        if ($score < 0 || $score > 5) {
+            return array(
+                'score' => 0.00,
+                'nums' => $nums,
+                'display' => '评分异常',
+                'star' => 0
+            );
+        }
+        
+        return array(
+            'score' => round($score, 2),
+            'nums' => (int) $nums,
+            'display' => sprintf('%.1f分', $score),
+            'star' => (int) round($score)
+        );
+    }
 }
 
 if (php_sapi_name() === 'cli' && isset($argv[0]) && basename($argv[0]) === 'response.php') {