ghost/admin/app/components/dashboard/charts/overview.js

@@ -1,43 +1,60 @@
-import Component from '@glimmer/component';
-import {action} from '@ember/object';
-import {formatNumber} from '../../../helpers/format-number';
-import {inject as service} from '@ember/service';
+// 导入必要的模块和依赖
+import Component from '@glimmer/component';        // Glimmer组件基类，用于创建Ember组件
+import {action} from '@ember/object';              // 动作装饰器，用于标记组件中的动作方法
+import {formatNumber} from '../../../helpers/format-number'; // 数字格式化工具函数
+import {inject as service} from '@ember/service';  // 服务注入装饰器，用于依赖注入
 
+// 定义仪表板总览组件类
 export default class Overview extends Component {
+    // 注入仪表板统计服务，提供会员数据和趋势数据
     @service dashboardStats;
 
+    // 组件动作：加载图表数据
+    // 当组件插入DOM时自动调用此方法
     @action
     loadCharts() {
+        // 调用统计服务的加载会员统计方法
         this.dashboardStats.loadMemberCountStats();
     }
 
+    // 计算属性：检查数据是否正在加载中
+    // 返回true表示数据尚未加载完成
     get loading() {
         return this.dashboardStats.memberCountStats === null;
     }
 
+    // 计算属性：获取总会员数量
+    // 使用可选链操作符(?.)和空值合并操作符(??)确保安全访问
     get totalMembers() {
         return this.dashboardStats.memberCounts?.total ?? 0;
     }
 
+    // 计算属性：检查总会员数是否大于零
+    // 用于控制总览区域的显示/隐藏
     get isTotalMembersMoreThanZero() {
         return this.dashboardStats.memberCounts && this.totalMembers > 0;
     }
 
+    // 计算属性：获取付费会员数量
     get paidMembers() {
         return this.dashboardStats.memberCounts?.paid ?? 0;
     }
 
+    // 计算属性：获取免费会员数量
     get freeMembers() {
         return this.dashboardStats.memberCounts?.free ?? 0;
     }
 
+    // 计算属性：获取格式化后的总会员数显示文本
+    // 数据未加载时返回"-"作为占位符
     get totalMembersFormatted() {
         if (this.dashboardStats.memberCounts === null) {
-            return '-';
+            return '-';  // 数据加载中的占位符
         }
-        return formatNumber(this.totalMembers);
+        return formatNumber(this.totalMembers);  // 调用格式化函数（如：1000 → "1,000"）
     }
 
+    // 计算属性：获取格式化后的付费会员数显示文本
     get paidMembersFormatted() {
         if (this.dashboardStats.memberCounts === null) {
             return '-';
@@ -45,6 +62,7 @@ export default class Overview extends Component {
         return formatNumber(this.paidMembers);
     }
 
+    // 计算属性：获取格式化后的免费会员数显示文本
     get freeMembersFormatted() {
         if (this.dashboardStats.memberCounts === null) {
             return '-';
@@ -52,6 +70,8 @@ export default class Overview extends Component {
         return formatNumber(this.freeMembers);
     }
 
+    // 计算属性：检查是否有可用的趋势数据
+    // 需要确保所有必需的数据都已加载完成
     get hasTrends() {
         return this.dashboardStats.memberCounts !== null 
             && this.dashboardStats.memberCountsTrend !== null
@@ -59,30 +79,43 @@ export default class Overview extends Component {
             && this.dashboardStats.currentMRRTrend !== null;
     }
 
+    // 计算属性：计算总会员数的趋势百分比
+    // 使用历史数据和当前数据进行对比计算
     get totalMembersTrend() {
         return this.calculatePercentage(this.dashboardStats.memberCountsTrend.total, this.dashboardStats.memberCounts.total);
     }
 
+    // 计算属性：计算付费会员数的趋势百分比
     get paidMembersTrend() {
         return this.calculatePercentage(this.dashboardStats.memberCountsTrend.paid, this.dashboardStats.memberCounts.paid);
     }
 
+    // 计算属性：计算免费会员数的趋势百分比
     get freeMembersTrend() {
         return this.calculatePercentage(this.dashboardStats.memberCountsTrend.free, this.dashboardStats.memberCounts.free);
     }
 
+    // 计算属性：检查网站是否设置了付费层级
+    // 用于控制付费相关功能的显示
     get hasPaidTiers() {
         return this.dashboardStats.siteStatus?.hasPaidTiers;
     }
 
+    // 私有方法：计算两个数值之间的百分比变化
+    // @param {number} from - 起始值（历史数据）
+    // @param {number} to - 结束值（当前数据）
+    // @returns {number} 百分比变化值，四舍五入到整数
     calculatePercentage(from, to) {
+        // 特殊处理：如果起始值为0
         if (from === 0) {
             if (to > 0) {
-                return 100;
+                return 100;  // 从0增长到任何正数都视为100%增长
             }
-            return 0;
+            return 0;        // 保持为0表示无变化
         }
 
+        // 标准百分比计算公式：(新值-旧值)/旧值 × 100
+        // 使用Math.round进行四舍五入
         return Math.round((to - from) / from * 100);
     }
-}
+}