777

.docker/prometheus/prometheus.yml

@@ -1,26 +1,39 @@
+# 全局配置部分
 global:
-  scrape_interval:     15s # By default, scrape targets every 15 seconds.
+  # 默认情况下，每15秒抓取一次目标数据
+  scrape_interval:     15s 
 
-# A scrape configuration containing exactly one endpoint to scrape:
+# 抓取配置部分，包含所有需要抓取的端点配置
-# Here it's Prometheus itself.
+# 这里首先配置了Prometheus自身的监控
 scrape_configs:
-  # The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
+  # 作业名称会作为标签`job=<job_name>`添加到从该配置抓取的所有时间序列中
   - job_name: 'prometheus'
 
-    # Override the global default and scrape targets from this job every 5 seconds.
+    # 覆盖全局默认配置，从该作业抓取目标的间隔为5秒
     scrape_interval: 5s
 
+    # 静态配置的目标列表（不需要服务发现）
     static_configs:
+      # 监控Prometheus自身，默认运行在localhost:9090
       - targets: ['localhost:9090']
 
+  # 配置Pushgateway的监控抓取
   - job_name: 'pushgateway'
 
+    # 抓取间隔设置为1秒（更频繁地获取推送的数据）
     scrape_interval: 1s
 
+    # Pushgateway的静态目标配置
     static_configs:
+      # Pushgateway服务地址（假设通过容器网络访问，服务名为pushgateway，端口9091）
       - targets: ['pushgateway:9091']
 
+    # 保留被推送数据中原有的标签（不覆盖job等标签）
+    # 对于Pushgateway尤为重要，因为它需要保留推送数据的原始标签信息
     honor_labels: true
 
+# 远程写入配置（将Prometheus收集的数据推送到其他服务）
 remote_write:
+  # 配置推送到Grafana的Prometheus兼容端点
+  # 假设Grafana服务通过容器网络访问，服务名为grafana，端口3000
   - url: http://grafana:3000/api/prom/push

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -1,6 +1,8 @@
+# 定义一个Bug报告的表单模板
 name: 🐛 Bug report
-description: Report reproducible software issues so we can improve
+description: Report reproducible software issues so we can improve  # 模板用途：报告可复现的软件问题以帮助改进
 body:
+  #  markdown类型的说明文本，用于展示欢迎信息
   - type: markdown
     attributes:
       value: |
@@ -8,69 +10,87 @@ body:
         Thank you for taking the time to fill out a bug report 🙂
 
         We'll respond as quickly as we can. The more information you provide the easier & quicker it is for us to diagnose the problem.
+
+  # 文本区域：用于简要描述问题
   - type: textarea
-    id: summary
+    id: summary  # 字段唯一标识
     attributes:
-      label: Issue Summary
+      label: Issue Summary  # 字段标签：问题概要
-      description: Explain roughly what's wrong
+      description: Explain roughly what's wrong  # 描述：简要说明哪里出了问题
     validations:
-      required: true
+      required: true  # 此字段为必填项
+
+  # 文本区域：用于描述复现步骤和预期结果
   - type: textarea
-    id: reproduction
+    id: reproduction  # 字段唯一标识
     attributes:
-      label: Steps to Reproduce
+      label: Steps to Reproduce  # 字段标签：复现步骤
-      description: Also tell us, what did you expect to happen?
+      description: Also tell us, what did you expect to happen?  # 描述：同时说明你预期的结果
-      placeholder: |
+      placeholder: |  # 输入示例
         1. This is the first step...
         2. This is the second step, etc.
     validations:
-      required: true
+      required: true  # 此字段为必填项
+
+  # 输入框：用于填写Ghost版本号
   - type: input
-    id: version
+    id: version  # 字段唯一标识
     attributes:
-      label: Ghost Version
+      label: Ghost Version  # 字段标签：Ghost版本
     validations:
-      required: true
+      required: true  # 此字段为必填项
+
+  # 输入框：用于填写Node.js版本号
   - type: input
-    id: node
+    id: node  # 字段唯一标识
     attributes:
-      label: Node.js Version
+      label: Node.js Version  # 字段标签：Node.js版本
     validations:
-      required: true
+      required: true  # 此字段为必填项
+
+  # 输入框：用于描述安装方式
   - type: input
-    id: install
+    id: install  # 字段唯一标识
     attributes:
-      label: How did you install Ghost?
+      label: How did you install Ghost?  # 字段标签：如何安装的Ghost？
-      description: Provide details of your host & operating system
+      description: Provide details of your host & operating system  # 描述：提供主机和操作系统的详细信息
     validations:
-      required: true
+      required: true  # 此字段为必填项
+
+  # 下拉选择框：用于选择数据库类型
   - type: dropdown
-    id: database
+    id: database  # 字段唯一标识
     attributes:
-      label: Database type
+      label: Database type  # 字段标签：数据库类型
-      options:
+      options:  # 可选值列表
          - MySQL 5.7
          - MySQL 8
          - SQLite3
          - Other
     validations:
-      required: true
+      required: true  # 此字段为必填项
+
+  # 输入框：用于填写浏览器和操作系统版本（前端问题必填）
   - type: input
-    id: browsers
+    id: browsers  # 字段唯一标识
     attributes:
-      label: Browser & OS version
+      label: Browser & OS version  # 字段标签：浏览器和操作系统版本
-      description: Include this for frontend bugs
+      description: Include this for frontend bugs  # 描述：前端问题需要填写此项
+
+  # 文本区域：用于展示相关日志或错误输出
   - type: textarea
-    id: logs
+    id: logs  # 字段唯一标识
     attributes:
-      label: Relevant log / error output
+      label: Relevant log / error output  # 字段标签：相关日志/错误输出
-      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.  # 描述：请复制粘贴相关日志，会自动格式化为代码块，无需手动添加反引号
-      render: shell
+      render: shell  # 渲染为shell代码块格式
+
+  # 复选框：用于确认是否同意行为准则
   - type: checkboxes
-    id: terms
+    id: terms  # 字段唯一标识
     attributes:
-      label: Code of Conduct
+      label: Code of Conduct  # 字段标签：行为准则
-      description: By submitting this issue, you agree to follow our [Code of Conduct](https://ghost.org/conduct)
+      description: By submitting this issue, you agree to follow our [Code of Conduct](https://ghost.org/conduct)  # 描述：提交此问题即表示同意遵守我们的行为准则
       options:
-        - label: I agree to be friendly and polite to people in this repository
+        - label: I agree to be friendly and polite to people in this repository  # 同意在仓库中友好礼貌地对待他人
-          required: true
+          required: true  # 此字段为必填项（必须勾选）

.github/ISSUE_TEMPLATE/config.yml

@@ -1,11 +1,20 @@
+# 是否允许创建空白问题（不使用预设模板的问题）
+# 设置为true表示用户可以直接提交自定义内容的问题
 blank_issues_enabled: true
+
+# 联系链接配置：提供额外的支持和资源入口
 contact_links:
-  - name: 🚑 Help & Support
+  # 第一个链接：帮助与支持
-    url: https://forum.ghost.org
+  - name: 🚑 Help & Support  # 链接名称，带救护车图标表示紧急支持
-    about: Please use the community forum for questions
+    url: https://forum.ghost.org  # 链接地址（Ghost社区论坛）
-  - name: 💡 Features & Ideas
+    about: Please use the community forum for questions  # 说明：请在社区论坛提问
-    url: https://forum.ghost.org/c/Ideas
+
-    about: Please vote for & post new ideas in the the forum
+  # 第二个链接：功能与想法建议
-  - name: 📖 Documentation
+  - name: 💡 Features & Ideas  # 链接名称，带灯泡图标表示创意建议
-    url: https://ghost.org/docs/
+    url: https://forum.ghost.org/c/Ideas  # 链接地址（论坛的Ideas分类）
-    about: Tutorials & reference guides for themes, the API and more
+    about: Please vote for & post new ideas in the forum  # 说明：请在论坛投票或发布新想法
+
+  # 第三个链接：文档资源
+  - name: 📖 Documentation  # 链接名称，带书本图标表示文档
+    url: https://ghost.org/docs/  # 链接地址（官方文档中心）
+    about: Tutorials & reference guides for themes, the API and more  # 说明：包含主题、API等的教程和参考指南

.github/scripts/bump-version.js

@@ -1,38 +1,54 @@
+// 引入所需模块：文件系统（Promise版）、子进程exec（Promise化）、路径处理
 const fs = require('fs/promises');
 const exec = require('util').promisify(require('child_process').exec);
 const path = require('path');
 
+// 引入GitHub Actions核心模块（用于设置输出）和语义化版本处理工具
 const core = require('@actions/core');
 const semver = require('semver');
 
+// 异步自执行函数：处理版本号更新逻辑
 (async () => {
+    // 1. 定位并读取core模块的package.json文件
     const corePackageJsonPath = path.join(__dirname, '../../ghost/core/package.json');
     const corePackageJson = require(corePackageJsonPath);
 
+    // 2. 获取当前版本号并打印
     const current_version = corePackageJson.version;
     console.log(`Current version: ${current_version}`);
 
+    // 3. 获取命令行传入的第一个参数（用于判断版本类型）
     const firstArg = process.argv[2];
     console.log('firstArg', firstArg);
 
-    const buildString = await exec('git rev-parse --short HEAD').then(({stdout}) => stdout.trim());
+    // 4. 获取当前Git提交的短哈希值（用于构建版本号）
+    const buildString = await exec('git rev-parse --short HEAD')
+        .then(({stdout}) => stdout.trim()); // 去除输出中的换行符
 
-    let newVersion;
+    let newVersion; // 声明新版本号变量
 
+    // 5. 根据命令行参数生成不同类型的新版本号
     if (firstArg === 'canary' || firstArg === 'six') {
-        const bumpedVersion = semver.inc(current_version, 'minor');
+        // 对于canary或six类型：升级minor版本并添加预发布标签（包含Git哈希）
-        newVersion = `${bumpedVersion}-pre-g${buildString}`;
+        const bumpedVersion = semver.inc(current_version, 'minor'); // 升级次要版本（如1.2.3 → 1.3.0）
+        newVersion = `${bumpedVersion}-pre-g${buildString}`; // 格式：1.3.0-pre-gabc123
     } else {
-        const gitVersion = await exec('git describe --long HEAD').then(({stdout}) => stdout.trim().replace(/^v/, ''));
+        // 其他情况：使用git describe生成版本号（基于最近的标签）
+        // git describe --long会输出类似"v1.2.3-4-gabc123"，这里去除前缀v
+        const gitVersion = await exec('git describe --long HEAD')
+            .then(({stdout}) => stdout.trim().replace(/^v/, ''));
         newVersion = gitVersion;
     }
 
+    // 6. 统一添加+moya后缀（可能用于标识自定义构建）
     newVersion += '+moya';
     console.log('newVersion', newVersion);
 
+    // 7. 更新core模块的package.json版本号并写入文件
     corePackageJson.version = newVersion;
-    await fs.writeFile(corePackageJsonPath, JSON.stringify(corePackageJson, null, 2));
+    await fs.writeFile(corePackageJsonPath, JSON.stringify(corePackageJson, null, 2)); // 保留2空格缩进
 
+    // 8. 同步更新admin模块的package.json版本号
     const adminPackageJsonPath = path.join(__dirname, '../../ghost/admin/package.json');
     const adminPackageJson = require(adminPackageJsonPath);
     adminPackageJson.version = newVersion;
@@ -40,6 +56,7 @@ const semver = require('semver');
 
     console.log('Version bumped to', newVersion);
 
-    core.setOutput('BUILD_VERSION', newVersion);
+    // 9. 设置GitHub Actions输出变量（供后续步骤使用）
-    core.setOutput('GIT_COMMIT_HASH', buildString)
+    core.setOutput('BUILD_VERSION', newVersion); // 输出构建版本号
-})();
+    core.setOutput('GIT_COMMIT_HASH', buildString) // 输出Git提交哈希
+})();

.github/scripts/clean.js

@@ -1,30 +1,44 @@
-// NOTE: this file can't use any NPM dependencies because it needs to run even if dependencies aren't installed yet or are corrupted
+// 注意：此文件不能使用任何NPM依赖，因为它需要在依赖未安装或已损坏的情况下仍能运行
+// 引入Node.js内置的子进程同步执行模块
 const {execSync} = require('child_process');
 
-cleanYarnCache();
+// 执行一系列清理操作
-resetNxCache();
+cleanYarnCache();       // 清理Yarn缓存
-deleteNodeModules();
+resetNxCache();         // 重置NX构建缓存
-deleteBuildArtifacts();
+deleteNodeModules();    // 删除所有node_modules目录
-console.log('Cleanup complete!');
+deleteBuildArtifacts(); // 删除构建产物
+console.log('Cleanup complete!'); // 清理完成提示
 
+/**
+ * 删除项目中的构建产物
+ * 包括ghost目录下所有名为build的文件夹和tsconfig.tsbuildinfo文件
+ */
 function deleteBuildArtifacts() {
     console.log('Deleting all build artifacts...');
     try {
+        // 查找ghost目录下所有名为build的目录并递归删除
         execSync('find ./ghost -type d -name "build" -exec rm -rf \'{}\' +', {
-            stdio: 'inherit'
+            stdio: 'inherit' // 子进程的输入输出继承自当前进程（显示执行过程）
         });
+        // 查找ghost目录下所有tsconfig.tsbuildinfo文件并删除
         execSync('find ./ghost -type f -name "tsconfig.tsbuildinfo" -delete', {
             stdio: 'inherit'
         });
     } catch (error) {
         console.error('Failed to delete build artifacts:', error);
-        process.exit(1);
+        process.exit(1); // 执行失败时退出进程，状态码1表示错误
     }
 }
 
+/**
+ * 删除项目中所有node_modules目录
+ * 用于彻底清理已安装的依赖包
+ */
 function deleteNodeModules() {
     console.log('Deleting all node_modules directories...');
     try {
+        // 从当前目录开始查找所有node_modules目录并递归删除
+        // -prune确保不会进入已找到的node_modules目录内部继续查找
         execSync('find . -name "node_modules" -type d -prune -exec rm -rf \'{}\' +', {
             stdio: 'inherit'
         });
@@ -34,9 +48,14 @@ function deleteNodeModules() {
     }
 }
 
+/**
+ * 重置NX构建工具的缓存
+ * NX是用于 monorepo 项目的构建系统，缓存可能影响构建结果
+ */
 function resetNxCache() {
     console.log('Resetting NX cache...');
     try {
+        // 删除NX的缓存目录
         execSync('rm -rf .nxcache .nx');
     } catch (error) {
         console.error('Failed to reset NX cache:', error);
@@ -44,12 +63,17 @@ function resetNxCache() {
     }
 }
 
+/**
+ * 清理Yarn包管理器的缓存
+ * 移除缓存的依赖包副本，避免旧版本缓存影响安装
+ */
 function cleanYarnCache() {
     console.log('Cleaning yarn cache...');
     try {
+        // 删除Yarn缓存目录下的所有内容
         execSync('rm -rf .yarncache/* .yarncachecopy/*');
     } catch (error) {
         console.error('Failed to clean yarn cache:', error);
         process.exit(1);
     }
-}
+}

.github/scripts/release-apps.js

@@ -3,9 +3,9 @@ const fs = require('fs/promises');
 const exec = require('util').promisify(require('child_process').exec);
 const readline = require('readline/promises');
 
-const semver = require('semver');
+const semver = require('semver'); // 用于语义化版本号处理
 
-// Maps a package name to the config key in defaults.json
+// 映射包名到defaults.json中的配置键名（用于版本同步）
 const CONFIG_KEYS = {
     '@tryghost/portal': 'portal',
     '@tryghost/sodo-search': 'sodoSearch',
@@ -14,14 +14,20 @@ const CONFIG_KEYS = {
     '@tryghost/signup-form': 'signupForm'
 };
 
-const CURRENT_DIR = process.cwd();
+const CURRENT_DIR = process.cwd(); // 当前工作目录
 
+// 读取当前项目的package.json路径和内容
 const packageJsonPath = path.join(CURRENT_DIR, 'package.json');
 const packageJson = require(packageJsonPath);
 
+// 从package.json中提取应用名称和当前版本
 const APP_NAME = packageJson.name;
 const APP_VERSION = packageJson.version;
 
+/**
+ * 安全执行命令的工具函数
+ * 捕获错误并返回包含stdout和stderr的对象（避免进程直接崩溃）
+ */
 async function safeExec(command) {
     try {
         return await exec(command);
@@ -33,106 +39,143 @@ async function safeExec(command) {
     }
 }
 
+/**
+ * 确保当前应用在允许发布的列表中
+ * 检查APP_NAME是否存在于CONFIG_KEYS的键名中
+ */
 async function ensureEnabledApp() {
     const ENABLED_APPS = Object.keys(CONFIG_KEYS);
     if (!ENABLED_APPS.includes(APP_NAME)) {
         console.error(`${APP_NAME} is not enabled, please modify ${__filename}`);
-        process.exit(1);
+        process.exit(1); // 非允许的应用，退出进程
     }
 }
 
+/**
+ * 确保不在main分支上执行发布
+ * 防止直接在主分支上修改代码
+ */
 async function ensureNotOnMain() {
     const currentGitBranch = await safeExec(`git branch --show-current`);
     if (currentGitBranch.stderr) {
         console.error(`There was an error checking the current git branch`)
         console.error(`${currentGitBranch.stderr}`);
-        process.exit(1);
+        process.exit(1); // 分支检查失败，退出进程
     }
 
     if (currentGitBranch.stdout.trim() === 'main') {
         console.error(`The release can not be done on the "main" branch`)
-        process.exit(1);
+        process.exit(1); // 在main分支上，退出进程
     }
 }
 
+/**
+ * 确保当前git工作区干净（无未提交的更改）
+ * 避免发布时包含未跟踪的修改
+ */
 async function ensureCleanGit() {
     const localGitChanges = await safeExec(`git status --porcelain`);
     if (localGitChanges.stderr) {
         console.error(`There was an error checking the local git status`)
         console.error(`${localGitChanges.stderr}`);
-        process.exit(1);
+        process.exit(1); // 状态检查失败，退出进程
     }
 
     if (localGitChanges.stdout) {
         console.error(`You have local git changes - are you sure you're ready to release?`)
         console.error(`${localGitChanges.stdout}`);
-        process.exit(1);
+        process.exit(1); // 有未提交的更改，退出进程
     }
 }
 
+/**
+ * 获取用户输入的版本更新类型（patch/minor/major）并计算新版本号
+ * 默认使用patch更新
+ */
 async function getNewVersion() {
     const rl = readline.createInterface({input: process.stdin, output: process.stdout});
     const bumpTypeInput = await rl.question('Is this a patch, minor or major (patch)? ');
     rl.close();
+    
     const bumpType = bumpTypeInput.trim().toLowerCase() || 'patch';
     if (!['patch', 'minor', 'major'].includes(bumpType)) {
         console.error(`Unknown bump type ${bumpTypeInput} - expected one of "patch", "minor, "major"`)
-        process.exit(1);
+        process.exit(1); // 无效的更新类型，退出进程
     }
-    return semver.inc(APP_VERSION, bumpType);
+    
+    return semver.inc(APP_VERSION, bumpType); // 使用semver计算新版本号
 }
 
+/**
+ * 更新全局配置文件中的应用版本
+ * 只保留主版本号和次版本号（如1.2.3 → 1.2）
+ */
 async function updateConfig(newVersion) {
+    // 定位全局配置文件defaults.json
     const defaultConfigPath = path.resolve(__dirname, '../../ghost/core/core/shared/config/defaults.json');
     const defaultConfig = require(defaultConfigPath);
 
+    // 获取当前应用在配置文件中的键名
     const configKey = CONFIG_KEYS[APP_NAME];
 
+    // 更新配置中的版本（只保留major和minor）
     defaultConfig[configKey].version = `${semver.major(newVersion)}.${semver.minor(newVersion)}`;
 
+    // 写回配置文件（保留4空格缩进）
     await fs.writeFile(defaultConfigPath, JSON.stringify(defaultConfig, null, 4) + '\n');
 }
 
+/**
+ * 更新当前应用的package.json版本号
+ */
 async function updatePackageJson(newVersion) {
     const newPackageJson = Object.assign({}, packageJson, {
         version: newVersion
     });
 
+    // 写回package.json（保留2空格缩进）
     await fs.writeFile(packageJsonPath, JSON.stringify(newPackageJson, null, 2) + '\n');
 }
 
+/**
+ * 生成更新日志（Changelog）
+ * 包含i18n更新信息和相关的提交记录
+ */
 async function getChangelog(newVersion) {
     const rl = readline.createInterface({input: process.stdin, output: process.stdout});
     const i18nChangesInput = await rl.question('Does this release contain i18n updates (Y/n)? ');
     rl.close();
 
+    // 判断是否包含国际化更新
     const i18nChanges = i18nChangesInput.trim().toLowerCase() !== 'n';
 
     let changelogItems = [];
 
+    // 如果有i18n更新，添加到更新日志
     if (i18nChanges) {
         changelogItems.push('Updated i18n translations');
     }
 
-    // Restrict git log to only the current directory (the specific app)
+    // 获取当前应用目录下最近50条提交记录（限制在当前目录）
     const lastFiftyCommits = await safeExec(`git log -n 50 --oneline -- .`);
 
     if (lastFiftyCommits.stderr) {
         console.error(`There was an error getting the last 50 commits`);
-        process.exit(1);
+        process.exit(1); // 获取提交记录失败，退出进程
     }
 
+    // 解析提交记录，查找上一次发布的提交
     const lastFiftyCommitsList = lastFiftyCommits.stdout.split('\n');
     const releaseRegex = new RegExp(`Released ${APP_NAME} v${APP_VERSION}`);
     const indexOfLastRelease = lastFiftyCommitsList.findIndex((commitLine) => {
-        const commitMessage = commitLine.slice(11); // Take the hash off the front
+        const commitMessage = commitLine.slice(11); // 移除哈希前缀
         return releaseRegex.test(commitMessage);
     });
 
     if (indexOfLastRelease === -1) {
+        // 未找到上一次发布记录，使用最近20条相关提交作为 fallback
         console.warn(`Could not find commit for previous release. Will include recent commits affecting this app.`);
 
-        // Fallback: get recent commits for this app (last 20)
         const recentCommits = await safeExec(`git log -n 20 --pretty=format:"%h%n%B__SPLIT__" -- .`);
         if (recentCommits.stderr) {
             console.error(`There was an error getting recent commits`);
@@ -141,25 +184,28 @@ async function getChangelog(newVersion) {
 
         const recentCommitsList = recentCommits.stdout.split('__SPLIT__');
 
+        // 筛选包含Linear链接的提交（通常是已处理的任务）
         const recentCommitsWhichMentionLinear = recentCommitsList.filter((commitBlock) => {
             return commitBlock.includes('https://linear.app/ghost');
         });
 
+        // 生成提交记录的GitHub链接
         const commitChangelogItems = recentCommitsWhichMentionLinear.map((commitBlock) => {
             const lines = commitBlock.split('\n');
             if (!lines.length || !lines[0].trim()) {
-                return null; // Skip entries with no hash
+                return null; // 跳过无效条目
             }
             const hash = lines[0].trim();
             return `https://github.com/TryGhost/Ghost/commit/${hash}`;
-        }).filter(Boolean); // Filter out any null entries
+        }).filter(Boolean); // 过滤空值
 
         changelogItems.push(...commitChangelogItems);
     } else {
+        // 找到上一次发布记录，获取两次发布之间的提交
         const lastReleaseCommit = lastFiftyCommitsList[indexOfLastRelease];
-        const lastReleaseCommitHash = lastReleaseCommit.slice(0, 10);
+        const lastReleaseCommitHash = lastReleaseCommit.slice(0, 10); // 提取提交哈希
 
-        // Also restrict this git log to only the current directory (the specific app)
+        // 获取从上次发布到现在的提交（限制在当前目录）
         const commitsSinceLastRelease = await safeExec(`git log ${lastReleaseCommitHash}..HEAD --pretty=format:"%h%n%B__SPLIT__" -- .`);
         if (commitsSinceLastRelease.stderr) {
             console.error(`There was an error getting commits since the last release`);
@@ -167,49 +213,63 @@ async function getChangelog(newVersion) {
         }
         const commitsSinceLastReleaseList = commitsSinceLastRelease.stdout.split('__SPLIT__');
 
+        // 筛选包含Linear链接的提交
         const commitsSinceLastReleaseWhichMentionLinear = commitsSinceLastReleaseList.filter((commitBlock) => {
             return commitBlock.includes('https://linear.app/ghost');
         });
 
+        // 生成提交记录的GitHub链接
         const commitChangelogItems = commitsSinceLastReleaseWhichMentionLinear.map((commitBlock) => {
             const lines = commitBlock.split('\n');
             if (!lines.length || !lines[0].trim()) {
-                return null; // Skip entries with no hash
+                return null; // 跳过无效条目
             }
             const hash = lines[0].trim();
             return `https://github.com/TryGhost/Ghost/commit/${hash}`;
-        }).filter(Boolean); // Filter out any null entries
+        }).filter(Boolean); // 过滤空值
 
         changelogItems.push(...commitChangelogItems);
     }
 
+    // 格式化更新日志列表
     const changelogList = changelogItems.map(item => `  - ${item}`).join('\n');
     return `Changelog for v${APP_VERSION} -> ${newVersion}: \n${changelogList}`;
 }
 
+/**
+ * 主函数：执行发布流程
+ */
 async function main() {
-    await ensureEnabledApp();
+    // 前置检查
-    await ensureNotOnMain();
+    await ensureEnabledApp();      // 检查应用是否允许发布
-    await ensureCleanGit();
+    await ensureNotOnMain();       // 检查是否不在main分支
+    await ensureCleanGit();        // 检查工作区是否干净
 
     console.log(`Running release for ${APP_NAME}`);
     console.log(`Current version is ${APP_VERSION}`);
 
+    // 获取新版本号
     const newVersion = await getNewVersion();
 
     console.log(`Bumping to version ${newVersion}`);
 
+    // 生成更新日志
     const changelog = await getChangelog(newVersion);
 
+    // 更新package.json并提交
     await updatePackageJson(newVersion);
     await exec(`git add package.json`);
 
+    // 更新全局配置并提交
     await updateConfig(newVersion);
     await exec(`git add ../../ghost/core/core/shared/config/defaults.json`);
 
+    // 创建发布提交
     await exec(`git commit -m 'Released ${APP_NAME} v${newVersion}\n\n${changelog}'`);
 
+    // 提示用户检查并提交PR
     console.log(`Release commit created - please double check it and use "git commit --amend" to make any changes before opening a PR to merge into main`)
 }
 
-main();
+// 执行主函数
+main();

.github/workflows/label-actions.yml

@@ -1,21 +1,25 @@
+# 工作流名称：为 Issues 添加标签
 name: 'Label Issues'
 
+# 触发条件：定义工作流在哪些事件发生时运行
 on:
-  workflow_dispatch:
+  workflow_dispatch:  # 允许手动触发工作流
   issues:
-    types: [opened, closed, labeled]
+    types: [opened, closed, labeled]  # 当 issues 被打开、关闭或添加标签时触发
   pull_request_target:
-    types: [closed, labeled]
+    types: [closed, labeled]  # 当 PR 被关闭或添加标签时触发（使用 target 分支上下文）
   schedule:
-    - cron:  '0 * * * *'
+    - cron:  '0 * * * *'  # 定时触发，每小时执行一次（分钟 小时 日 月 周）
 
+# 权限设置：工作流运行时拥有的权限
 permissions:
-  issues: write
+  issues: write  # 允许对 issues 执行写操作（如添加标签）
-  pull-requests: write
+  pull-requests: write  # 允许对 PR 执行写操作（如添加标签）
 
 jobs:
-  action:
+  action:  # 定义一个名为 action 的任务
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-latest  # 任务运行在最新版 Ubuntu 系统上
-    if: github.repository_owner == 'TryGhost'
+    if: github.repository_owner == 'TryGhost'  # 仅当仓库所有者为 TryGhost 时才执行
     steps:
-      - uses: tryghost/actions/actions/label-actions@main
+      # 步骤：使用自定义动作处理标签操作
+      - uses: tryghost/actions/actions/label-actions@main  # 引用 TryGhost 组织下的 label-actions 动作（main 分支）

.github/workflows/migration-review.yml

@@ -1,30 +1,38 @@
+# 工作流名称：迁移审查
 name: Migration Review
+
+# 触发条件：当目标分支的PR被打开，且修改了特定迁移相关路径时触发
 on:
   pull_request_target:
-    types: [opened]
+    types: [opened]  # 仅在PR被打开时触发
     paths:
-      - 'ghost/core/core/server/data/schema/**'
+      - 'ghost/core/core/server/data/schema/**'  # 监控schema目录下的所有文件变更
-      - 'ghost/core/core/server/data/migrations/versions/**'
+      - 'ghost/core/core/server/data/migrations/versions/**'  # 监控迁移版本目录下的所有文件变更
+
 jobs:
-  createComment:
+  createComment:  # 定义一个名为createComment的任务
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-latest  # 任务运行在最新版Ubuntu系统上
-    if: github.repository_owner == 'TryGhost'
+    if: github.repository_owner == 'TryGhost'  # 仅当仓库所有者为TryGhost时执行
-    name: Add migration review requirements
+    name: Add migration review requirements  # 任务名称：添加迁移审查要求
+
     steps:
-      - uses: actions/github-script@v7
+      # 步骤1：为PR添加"migration"标签
+      - uses: actions/github-script@v7  # 使用GitHub官方脚本动作
         with:
           script: |
+            # 调用GitHub API为当前PR添加标签
             github.rest.issues.addLabels({
-              issue_number: context.issue.number,
+              issue_number: context.issue.number,  # 获取当前PR的编号
-              owner: context.repo.owner,
+              owner: context.repo.owner,  # 仓库所有者（从上下文获取）
-              repo: context.repo.repo,
+              repo: context.repo.repo,  # 仓库名称（从上下文获取）
-              labels: ["migration"]
+              labels: ["migration"]  # 要添加的标签
             })
 
+      # 步骤2：在PR中添加迁移审查清单评论
       - uses: peter-evans/create-or-update-comment@ac8e6509d7545ebc2e5e7c35eaa12195c2f77adc
         with:
-          issue-number: ${{ github.event.pull_request.number }}
+          issue-number: ${{ github.event.pull_request.number }}  # 指定要评论的PR编号
-          body: |
+          body: |  # 评论内容（迁移审查清单）
             It looks like this PR contains a migration 👀
             Here's the checklist for reviewing migrations:
 
@@ -54,4 +62,4 @@ jobs:
             - [ ]  Mass updates/inserts are batched appropriately
             - [ ]  Does not loop over large tables/datasets
             - [ ]  Defends against missing or invalid data
-            - [ ]  For settings updates: follows the appropriate guidelines
+            - [ ]  For settings updates: follows the appropriate guidelines

.github/workflows/stale-i18n.yml

@@ -1,15 +1,21 @@
+# 工作流名称：关闭过时的国际化（i18n）相关PR
 name: 'Close stale i18n PRs'
+
+# 触发条件
 on:
-  workflow_dispatch:
+  workflow_dispatch:  # 允许手动触发工作流
   schedule:
-    - cron: '0 6 * * *'
+    - cron: '0 6 * * *'  # 定时触发，每天早上6点执行（UTC时间）
+
 jobs:
-  stale:
+  stale:  # 定义名为stale的任务（处理过时PR）
-    if: github.repository_owner == 'TryGhost'
+    if: github.repository_owner == 'TryGhost'  # 仅当仓库所有者为TryGhost时执行
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-latest  # 任务运行在最新版Ubuntu系统上
     steps:
+      # 使用官方的stale动作处理过时PR
       - uses: actions/stale@v9
         with:
+          # 标记PR为过时的提示消息
           stale-pr-message: |
             Thanks for contributing to Ghost's i18n :)
 
@@ -17,10 +23,12 @@ jobs:
             I18n PRs tend to get out of date quickly, so we're closing them to keep the PR list clean.
 
             If you're still interested in working on this PR, please let us know. Otherwise this PR will be closed shortly, but can always be reopened later. Thank you for understanding 🙂
-          only-labels: 'affects:i18n'
+          
-          days-before-pr-stale: 21
+          only-labels: 'affects:i18n'  # 仅对带有affects:i18n标签的PR生效
-          days-before-pr-close: 7
+          days-before-pr-stale: 21  # PR闲置21天（3周）后标记为过时
-          exempt-pr-labels: 'feature,pinned,needs:triage'
+          days-before-pr-close: 7   # 标记为过时后7天自动关闭
-          stale-pr-label: 'stale'
+          exempt-pr-labels: 'feature,pinned,needs:triage'  # 这些标签的PR不会被标记为过时
+          stale-pr-label: 'stale'  # 标记过时PR时添加的标签
+          # 关闭PR时的提示消息
           close-pr-message: |
-            This PR has been automatically closed due to inactivity. If you'd like to continue working on it, feel free to open a new PR.
+            This PR has been automatically closed due to inactivity. If you'd like to continue working on it, feel free to open a new PR.

.github/workflows/stale.yml

@@ -1,29 +1,43 @@
+# 工作流名称：关闭过时的issues和PRs
 name: 'Close stale issues and PRs'
+
+# 触发条件
 on:
-  workflow_dispatch:
+  workflow_dispatch:  # 允许手动触发工作流
   schedule:
-    - cron: '0 6 * * *'
+    - cron: '0 6 * * *'  # 定时触发，每天早上6点执行（UTC时间）
+
 jobs:
-  stale:
+  stale:  # 定义名为stale的任务（处理过时的issues和PRs）
-    if: github.repository_owner == 'TryGhost'
+    if: github.repository_owner == 'TryGhost'  # 仅当仓库所有者为TryGhost时执行
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-latest  # 任务运行在最新版Ubuntu系统上
     steps:
+      # 使用官方的stale动作处理过时内容
       - uses: actions/stale@v9
         with:
+          # 标记issue为过时的提示消息
           stale-issue-message: |
             Our bot has automatically marked this issue as stale because there has not been any activity here in some time.
 
             The issue will be closed soon if there are no further updates, however we ask that you do not post comments to keep the issue open if you are not actively working on a PR.
 
             We keep the issue list minimal so we can keep focus on the most pressing issues. Closed issues can always be reopened if a new contributor is found. Thank you for understanding 🙂
+          
+          # 标记PR为过时的提示消息
           stale-pr-message: |
             Our bot has automatically marked this PR as stale because there has not been any activity here in some time.
 
             If we’ve missed reviewing your PR & you’re still interested in working on it, please let us know. Otherwise this PR will be closed shortly, but can always be reopened later. Thank you for understanding 🙂
+          
+          # 免于标记为过时的issue标签（这些标签的issue不会被处理）
           exempt-issue-labels: 'feature,pinned,needs:triage'
+          # 免于标记为过时的PR标签（这些标签的PR不会被处理）
           exempt-pr-labels: 'feature,pinned,needs:triage'
-          days-before-stale: 113
+          
-          days-before-pr-stale: 358
+          days-before-stale: 113  # issue闲置113天后标记为过时
-          stale-issue-label: 'stale'
+          days-before-pr-stale: 358  # PR闲置358天后标记为过时
-          stale-pr-label: 'stale'
+          
-          close-issue-reason: 'not_planned'
+          stale-issue-label: 'stale'  # 标记过时issue时添加的标签
+          stale-pr-label: 'stale'  # 标记过时PR时添加的标签
+          
+          close-issue-reason: 'not_planned'  # 关闭issue时的原因（GitHub内置选项）

.vscode/settings.json

@@ -1,26 +1,37 @@
 {
+  // 编辑器快速建议配置
   "editor.quickSuggestions": {
-    "strings": true
+    "strings": true  // 在字符串中启用自动补全建议（例如输入HTML/CSS类名时）
   },
+
+  // ESLint工作目录配置
   "eslint.workingDirectories": [
     {
-      "pattern": "./apps/*/"
+      "pattern": "./apps/*/"  // 对apps目录下的所有子目录启用ESLint检查
     },
     {
-      "pattern": "./ghost/*/"
+      "pattern": "./ghost/*/"  // 对ghost目录下的所有子目录启用ESLint检查
     }
   ],
+
+  // 搜索排除配置（这些路径不会出现在搜索结果中）
   "search.exclude": {
-    "**/.git": true,
+    "**/.git": true,  // 排除git版本控制目录
-    "**/build/*": true,
+    "**/build/*": true,  // 排除构建输出目录
-    "**/coverage/**": true,
+    "**/coverage/**": true,  // 排除测试覆盖率报告目录
-    "**/dist/**": true,
+    "**/dist/**": true,  // 排除打包输出目录
-    "**/ghost.map": true,
+    "**/ghost.map": true,  // 排除ghost.map文件
-    "**/node_modules": true,
+    "**/node_modules": true,  // 排除依赖包目录
-    "ghost/core/core/built/**": true
+    "ghost/core/core/built/**": true  // 排除特定的构建产物目录
   },
+
+  // Tailwind CSS配置
   "tailwindCSS.experimental.classRegex": [
+    // 配置识别clsx语法中的Tailwind类（用于自动补全）
+    // 例如匹配 clsx('text-red-500', 'bg-white') 中的类名
     ["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
   ],
-  "git.detectSubmodules": false
+
-}
+  // Git配置
+  "git.detectSubmodules": false  // 禁用Git子模块检测（可能用于加速或避免误检测）
+}

README.md

@@ -99,6 +99,6 @@ To stay up to date with all the latest news and product updates, make sure you [
  
 
 # Copyright & license
-
++ MIT
 Copyright (c) 2013-2025 Ghost Foundation - Released under the [MIT license](LICENSE).
 Ghost and the Ghost Logo are trademarks of Ghost Foundation Ltd. Please see our [trademark policy](https://ghost.org/trademark/) for info on acceptable usage.

apps/admin-x-activitypub/src/components/global/FollowButton.tsx

@@ -1,82 +1,102 @@
-import clsx from 'clsx';
+import clsx from 'clsx'; // 用于条件性组合CSS类名的库
-import {Button} from '@tryghost/shade';
+import { Button } from '@tryghost/shade'; // 引入UI组件库中的Button组件
-import {useEffect, useState} from 'react';
+import { useEffect, useState } from 'react'; // 引入React的钩子函数
-import {useFollowMutationForUser, useUnfollowMutationForUser} from '@hooks/use-activity-pub-queries';
+// 引入用于关注和取消关注的自定义钩子
+import { useFollowMutationForUser, useUnfollowMutationForUser } from '@hooks/use-activity-pub-queries';
 
+// 定义FollowButton组件的属性接口
 interface FollowButtonProps {
-    className?: string;
+    className?: string; // 可选的CSS类名
-    following: boolean;
+    following: boolean; // 表示当前是否已关注的状态
-    handle: string;
+    handle: string; // 被关注用户的唯一标识（如用户名）
-    type?: 'primary' | 'secondary';
+    type?: 'primary' | 'secondary'; // 按钮类型（未在组件中使用，预留扩展）
-    onFollow?: () => void;
+    onFollow?: () => void; // 关注操作完成后的回调函数
-    onUnfollow?: () => void;
+    onUnfollow?: () => void; // 取消关注操作完成后的回调函数
-    'data-testid'?: string;
+    'data-testid'?: string; // 用于测试的标识属性
 }
 
+// 空函数，作为回调函数的默认值
 const noop = () => {};
 
+// 关注/取消关注按钮组件
 const FollowButton: React.FC<FollowButtonProps> = ({
     className,
     following,
     handle,
-    onFollow = noop,
+    onFollow = noop, // 默认使用空函数
-    onUnfollow = noop,
+    onUnfollow = noop, // 默认使用空函数
     'data-testid': testId
 }) => {
+    // 本地状态管理当前是否关注，初始值由props传入
     const [isFollowing, setIsFollowing] = useState(following);
 
-    const unfollowMutation = useUnfollowMutationForUser('index',
+    // 初始化取消关注的mutation hook
+    const unfollowMutation = useUnfollowMutationForUser(
+        'index', // 缓存键名
         () => {
-            // Success handled by cache updates
+            // 成功回调 - 由缓存更新处理，这里不需要额外操作
         },
         () => {
+            // 失败回调 - 恢复关注状态
             setIsFollowing(true);
         }
     );
 
-    const followMutation = useFollowMutationForUser('index',
+    // 初始关注的mutation hook
+    const followMutation = useFollowMutationForUser(
+        'index', // 缓存键名
         () => {
-            // Success handled by cache updates
+            // 成功回调 - 由缓存更新处理，这里不需要额外操作
         },
         () => {
+            // 失败回调 - 恢复未关注状态
             setIsFollowing(false);
         }
     );
 
+    // 处理按钮点击事件
     const handleClick = async () => {
         if (isFollowing) {
-            setIsFollowing(false);
+            // 当前已关注，执行取消关注流程
-            onUnfollow();
+            setIsFollowing(false); // 先更新UI状态
-            unfollowMutation.mutate(handle);
+            onUnfollow(); // 触发取消关注回调
+            unfollowMutation.mutate(handle); // 调用取消关注API
         } else {
-            setIsFollowing(true);
+            // 当前未关注，执行关注流程
-            onFollow();
+            setIsFollowing(true); // 先更新UI状态
-            followMutation.mutate(handle);
+            onFollow(); // 触发关注回调
+            followMutation.mutate(handle); // 调用关注API
         }
     };
 
+    // 当props中的following变化时，同步更新本地状态
     useEffect(() => {
         setIsFollowing(following);
     }, [following]);
 
     return (
         <Button
+            // 组合CSS类名，确保最小宽度为90px
             className={clsx(
                 'min-w-[90px]',
                 className
             )}
-            data-testid={testId}
+            data-testid={testId} // 测试标识
+            // 已关注状态时显示提示文本
             title={isFollowing ? 'Click to unfollow' : ''}
+            // 根据关注状态切换按钮样式（默认/轮廓）
             variant={!isFollowing ? 'default' : 'outline'}
+            // 点击事件处理，阻止默认行为和事件冒泡
             onClick={(event) => {
                 event?.preventDefault();
                 event?.stopPropagation();
                 handleClick();
             }}
         >
+            {/* 根据关注状态显示不同文本 */}
             {isFollowing ? 'Following' : 'Follow'}
         </Button>
     );
 };
 
-export default FollowButton;
+export default FollowButton;

apps/admin-x-activitypub/src/components/global/ImageLightbox.tsx

@@ -1,52 +1,72 @@
-import React, {useCallback, useEffect, useState} from 'react';
+import React, { useCallback, useEffect, useState } from 'react';
-import {Button, Dialog, DialogClose, DialogContent, LucideIcon} from '@tryghost/shade';
+// 导入UI组件：按钮、对话框及内容容器、Lucide图标库
-import {ObjectProperties} from '@tryghost/admin-x-framework/api/activitypub';
+import { Button, Dialog, DialogClose, DialogContent, LucideIcon } from '@tryghost/shade';
-import {getAttachment} from '@components/feed/FeedItem';
+// 导入活动发布对象的类型定义
+import { ObjectProperties } from '@tryghost/admin-x-framework/api/activitypub';
+// 导入获取附件的工具函数
+import { getAttachment } from '@components/feed/FeedItem';
 
+// 定义灯箱中图片的类型接口
 export interface LightboxImage {
-    url: string;
+    url: string;  // 图片URL
-    alt: string;
+    alt: string;  // 图片替代文本
 }
 
+// 定义灯箱状态的类型接口
 export interface LightboxState {
-    images: LightboxImage[];
+    images: LightboxImage[];  // 所有图片列表
-    currentIndex: number;
+    currentIndex: number;     // 当前显示图片的索引
-    isOpen: boolean;
+    isOpen: boolean;          // 灯箱是否打开
 }
 
+/**
+ * 自定义Hook：管理图片灯箱的状态和操作
+ * @param object - 包含图片的活动发布对象
+ * @returns 灯箱状态及相关操作方法
+ */
 export function useLightboxImages(object: ObjectProperties | null) {
+    // 初始化灯箱状态
     const [lightboxState, setLightboxState] = useState<LightboxState>({
         images: [],
         currentIndex: 0,
         isOpen: false
     });
 
+    /**
+     * 从对象中提取所有图片
+     * @param obj - 活动发布对象
+     * @returns 提取出的图片数组
+     */
     const getAllImagesFromAttachment = (obj: ObjectProperties): LightboxImage[] => {
+        // 获取对象的附件
         const attachment = getAttachment(obj);
         if (!attachment) {
             return [];
         }
 
+        // 处理附件为数组的情况
         if (Array.isArray(attachment)) {
             return attachment.map((item, index) => ({
                 url: item.url,
-                alt: item.name || `Image-${index}`
+                alt: item.name || `Image-${index}`  // 用索引作为默认alt文本
             }));
         }
 
+        // 处理单个图片附件
         if (attachment.mediaType?.startsWith('image/') || attachment.type === 'Image') {
             return [{
                 url: attachment.url,
-                alt: attachment.name || 'Image'
+                alt: attachment.name || 'Image'  // 用默认文本作为fallback
             }];
         }
 
+        // 处理对象中直接包含image字段的情况
         if (obj.image) {
             let imageUrl;
             if (typeof obj.image === 'string') {
-                imageUrl = obj.image;
+                imageUrl = obj.image;  // 图片URL直接是字符串
             } else {
-                imageUrl = obj.image?.url;
+                imageUrl = obj.image?.url;  // 图片是对象，取其url属性
             }
 
             if (imageUrl) {
@@ -57,17 +77,23 @@ export function useLightboxImages(object: ObjectProperties | null) {
             }
         }
 
-        return [];
+        return [];  // 没有找到图片时返回空数组
     };
 
+    /**
+     * 打开灯箱并显示指定图片
+     * @param clickedUrl - 被点击图片的URL
+     */
     const openLightbox = (clickedUrl: string) => {
         if (!object) {
-            return;
+            return;  // 对象为空时不执行操作
         }
 
+        // 获取所有图片并找到被点击图片的索引
         const images = getAllImagesFromAttachment(object);
         const clickedIndex = images.findIndex(img => img.url === clickedUrl);
 
+        // 找到对应图片时更新灯箱状态
         if (clickedIndex !== -1) {
             setLightboxState({
                 images,
@@ -77,6 +103,9 @@ export function useLightboxImages(object: ObjectProperties | null) {
         }
     };
 
+    /**
+     * 关闭灯箱
+     */
     const closeLightbox = () => {
         setLightboxState(prev => ({
             ...prev,
@@ -84,6 +113,10 @@ export function useLightboxImages(object: ObjectProperties | null) {
         }));
     };
 
+    /**
+     * 导航到指定索引的图片
+     * @param newIndex - 目标图片索引
+     */
     const navigateToIndex = (newIndex: number) => {
         setLightboxState(prev => ({
             ...prev,
@@ -99,14 +132,18 @@ export function useLightboxImages(object: ObjectProperties | null) {
     };
 }
 
+// 图片灯箱组件的属性接口
 interface ImageLightboxProps {
-    images: LightboxImage[];
+    images: LightboxImage[];       // 图片列表
-    currentIndex: number;
+    currentIndex: number;          // 当前显示图片索引
-    isOpen: boolean;
+    isOpen: boolean;               // 是否打开
-    onClose: () => void;
+    onClose: () => void;           // 关闭回调
-    onNavigate: (newIndex: number) => void;
+    onNavigate: (newIndex: number) => void;  // 导航回调
 }
 
+/**
+ * 图片灯箱组件：用于放大查看图片，支持左右导航和键盘控制
+ */
 const ImageLightbox: React.FC<ImageLightboxProps> = ({
     images,
     currentIndex,
@@ -114,44 +151,65 @@ const ImageLightbox: React.FC<ImageLightboxProps> = ({
     onClose,
     onNavigate
 }) => {
+    // 判断是否是第一张/最后一张图片
     const isFirstImage = currentIndex === 0;
     const isLastImage = currentIndex === images.length - 1;
 
+    /**
+     * 导航到下一张图片
+     * 使用useCallback缓存函数，避免不必要的重渲染
+     */
     const goToNext = useCallback(() => {
+        // 只有一张图片或已经是最后一张时不执行
         if (images.length <= 1 || isLastImage) {
             return;
         }
+        // 计算下一张索引（循环导航）
         const nextIndex = (currentIndex + 1) % images.length;
         onNavigate(nextIndex);
     }, [images.length, isLastImage, currentIndex, onNavigate]);
 
+    /**
+     * 导航到上一张图片
+     * 使用useCallback缓存函数
+     */
     const goToPrev = useCallback(() => {
+        // 只有一张图片或已经是第一张时不执行
         if (images.length <= 1 || isFirstImage) {
             return;
         }
+        // 计算上一张索引（循环导航）
         const prevIndex = (currentIndex - 1 + images.length) % images.length;
         onNavigate(prevIndex);
     }, [images.length, isFirstImage, currentIndex, onNavigate]);
 
+    /**
+     * 监听键盘事件，支持左右箭头导航
+     */
     useEffect(() => {
         const handleKeyDown = (e: KeyboardEvent) => {
             if (!isOpen) {
-                return;
+                return;  // 灯箱关闭时不处理
             }
 
+            // 右箭头导航到下一张（非最后一张时）
             if (e.key === 'ArrowRight' && !isLastImage) {
                 goToNext();
-            } else if (e.key === 'ArrowLeft' && !isFirstImage) {
+            }
+            // 左箭头导航到上一张（非第一张时）
+            else if (e.key === 'ArrowLeft' && !isFirstImage) {
                 goToPrev();
             }
         };
 
         window.addEventListener('keydown', handleKeyDown);
+        // 组件卸载时移除事件监听
         return () => {
             window.removeEventListener('keydown', handleKeyDown);
         };
     }, [isOpen, currentIndex, images.length, goToNext, goToPrev, isLastImage, isFirstImage]);
 
+    // 灯箱未打开或没有图片时不渲染
     if (!isOpen || images.length === 0) {
         return null;
     }
@@ -159,37 +217,46 @@ const ImageLightbox: React.FC<ImageLightboxProps> = ({
     return (
         <Dialog
             open={isOpen}
+            // 监听对话框状态变化，关闭时触发回调
             onOpenChange={(open) => {
                 if (!open) {
                     onClose();
                 }
             }}
         >
-            <DialogContent className="top-[50%] h-[100vh] max-h-[100vh] w-[100vw] max-w-[100vw] translate-y-[-50%] items-center border-none bg-transparent p-0 shadow-none data-[state=closed]:zoom-out-100 data-[state=open]:zoom-in-100 data-[state=closed]:slide-out-to-top-[50%] data-[state=open]:slide-in-from-top-[50%]" onClick={() => onClose()}>
+            {/* 灯箱内容容器，全屏显示且居中 */}
+            <DialogContent 
+                className="top-[50%] h-[100vh] max-h-[100vh] w-[100vw] max-w-[100vw] translate-y-[-50%] items-center border-none bg-transparent p-0 shadow-none data-[state=closed]:zoom-out-100 data-[state=open]:zoom-in-100 data-[state=closed]:slide-out-to-top-[50%] data-[state=open]:slide-in-from-top-[50%]" 
+                onClick={() => onClose()}  // 点击空白区域关闭
+            >
+                {/* 当前显示的图片 */}
                 <img
                     alt={images[currentIndex].alt}
-                    className="mx-auto max-h-[90vh] max-w-[90vw] object-contain"
+                    className="mx-auto max-h-[90vh] max-w-[90vw] object-contain"  // 保持比例，限制最大尺寸
                     src={images[currentIndex].url}
-                    onClick={e => e.stopPropagation()}
+                    onClick={e => e.stopPropagation()}  // 点击图片本身不关闭灯箱
                 />
 
+                {/* 多张图片时显示导航按钮 */}
                 {images.length > 1 && (
                     <>
+                        {/* 上一张按钮 */}
                         <Button
                             className="absolute left-5 top-1/2 size-11 -translate-y-1/2 rounded-full bg-black/50 p-0 pr-0.5 hover:bg-black/70"
-                            disabled={isFirstImage}
+                            disabled={isFirstImage}  // 第一张时禁用
                             onClick={(e) => {
-                                e.stopPropagation();
+                                e.stopPropagation();  // 阻止事件冒泡（避免关闭灯箱）
                                 goToPrev();
                             }}
                         >
                             <LucideIcon.ChevronLeft className="!size-6" />
-                            <span className="sr-only">Previous image</span>
+                            <span className="sr-only">Previous image</span>  // 屏幕阅读器文本
                         </Button>
 
+                        {/* 下一张按钮 */}
                         <Button
                             className="absolute right-5 top-1/2 size-11 -translate-y-1/2 rounded-full bg-black/50 p-0 pl-0.5 hover:bg-black/70"
-                            disabled={isLastImage}
+                            disabled={isLastImage}  // 最后一张时禁用
                             onClick={(e) => {
                                 e.stopPropagation();
                                 goToNext();
@@ -200,6 +267,8 @@ const ImageLightbox: React.FC<ImageLightboxProps> = ({
                         </Button>
                     </>
                 )}
+
+                {/* 关闭按钮 */}
                 <DialogClose asChild>
                     <Button className="absolute right-5 top-5 size-11 rounded-full bg-black/50 p-0 hover:bg-black/70">
                         <LucideIcon.X className="!size-5" />
@@ -211,4 +280,4 @@ const ImageLightbox: React.FC<ImageLightboxProps> = ({
     );
 };
 
-export default ImageLightbox;
+export default ImageLightbox;

apps/admin-x-activitypub/src/components/global/ShowRepliesButton.tsx

@@ -1,39 +1,65 @@
-import React, {useRef} from 'react';
+import React, { useRef } from 'react';
-import {Button, LoadingIndicator} from '@tryghost/shade';
+// 导入UI组件：按钮组件和加载指示器组件
+import { Button, LoadingIndicator } from '@tryghost/shade';
 
+// 定义显示回复按钮的属性接口
 interface ShowRepliesButtonProps {
-    count?: number;
+    count?: number; // 可选，回复的数量
-    onClick: () => void;
+    onClick: () => void; // 点击按钮时触发的回调函数
-    variant?: 'default' | 'expand' | 'loadMore';
+    variant?: 'default' | 'expand' | 'loadMore'; // 可选，按钮文本变体
-    preserveScroll?: boolean;
+    preserveScroll?: boolean; // 可选，是否在点击后保持滚动位置，默认true
-    loading?: boolean;
+    loading?: boolean; // 可选，是否处于加载状态，默认false
 }
 
-const ShowRepliesButton: React.FC<ShowRepliesButtonProps> = ({count, onClick, variant = 'default', preserveScroll = true, loading = false}) => {
+/**
+ * 显示回复按钮组件
+ * 用于触发展示更多回复的操作，支持不同文本样式和加载状态
+ */
+const ShowRepliesButton: React.FC<ShowRepliesButtonProps> = ({
+    count,
+    onClick,
+    variant = 'default', // 默认使用'default'文本变体
+    preserveScroll = true, // 默认保持滚动位置
+    loading = false // 默认不显示加载状态
+}) => {
+    // 用于获取按钮容器DOM元素的引用
     const buttonRef = useRef<HTMLDivElement>(null);
 
+    /**
+     * 根据回复数量和按钮变体生成按钮显示文本
+     * @returns 按钮文本内容
+     */
     const getButtonText = () => {
+        // 当有明确的回复数量且数量大于0时，显示包含数量的文本
         if (count && count > 0) {
             return `Show ${count} more ${count === 1 ? 'reply' : 'replies'}`;
         }
 
+        // 根据不同的按钮变体返回对应文本
         switch (variant) {
-        case 'expand':
+            case 'expand':
-            return 'Show replies';
+                return 'Show replies';
-        case 'loadMore':
+            case 'loadMore':
-            return 'Show more replies';
+                return 'Show more replies';
-        default:
+            default:
-            return 'Show replies';
+                return 'Show replies';
         }
     };
 
+    /**
+     * 处理按钮点击事件
+     * 支持保持滚动位置的功能，避免点击后页面滚动位置跳动
+     */
     const handleClick = () => {
         if (preserveScroll) {
+            // 查找自定义滚动容器（优先）或使用window作为滚动容器
             const container = document.querySelector('[data-scrollable-container]') as HTMLElement;
             const scrollTop = container ? container.scrollTop : window.scrollY;
 
+            // 执行点击回调（如加载更多回复）
             onClick();
 
+            // 在下一次DOM更新周期中恢复滚动位置
             setTimeout(() => {
                 if (container) {
                     container.scrollTop = scrollTop;
@@ -42,30 +68,36 @@ const ShowRepliesButton: React.FC<ShowRepliesButtonProps> = ({count, onClick, va
                 }
             }, 0);
         } else {
+            // 不需要保持滚动位置时，直接执行回调
             onClick();
         }
     };
 
     return (
+        // 按钮容器，包含装饰线和按钮本身
         <div ref={buttonRef} className='mt-[-7px] flex items-center pb-3'>
+            {/* 左侧装饰元素：三条垂直短横线 */}
             <div className='flex w-10 flex-col items-center justify-center gap-1'>
                 <div className='size-0.5 rounded-sm bg-gray-300'></div>
                 <div className='size-0.5 rounded-sm bg-gray-300'></div>
                 <div className='size-0.5 rounded-sm bg-gray-300'></div>
             </div>
+
+            {/* 主按钮组件 */}
             <Button
                 className='hover:text-blue-800 text-sm font-medium text-blue-600'
-                variant="ghost"
+                variant="ghost" // 幽灵按钮样式（无背景色，仅文字交互）
                 onClick={(e: React.MouseEvent<HTMLElement>) => {
-                    e.preventDefault();
+                    e.preventDefault(); // 阻止默认事件
-                    e.stopPropagation();
+                    e.stopPropagation(); // 阻止事件冒泡
-                    (e.target as HTMLElement).blur();
+                    (e.target as HTMLElement).blur(); // 移除按钮焦点状态
-                    handleClick();
+                    handleClick(); // 执行点击处理逻辑
                 }}
             >
+                {/* 加载状态显示加载指示器和文本，否则显示按钮文本 */}
                 {loading ? (
                     <div className='flex items-center gap-2'>
-                        <LoadingIndicator size='sm' />
+                        <LoadingIndicator size='sm' /> {/* 小型加载指示器 */}
                         <span>Loading...</span>
                     </div>
                 ) : (
@@ -76,4 +108,4 @@ const ShowRepliesButton: React.FC<ShowRepliesButtonProps> = ({count, onClick, va
     );
 };
 
-export default ShowRepliesButton;
+export default ShowRepliesButton;

apps/admin-x-activitypub/src/components/global/SuggestedProfiles.tsx

@@ -1,88 +1,117 @@
-import APAvatar from './APAvatar';
+import APAvatar from './APAvatar'; // 头像组件，用于显示用户头像及相关信息
-import ActivityItem from '../activities/ActivityItem';
+import ActivityItem from '../activities/ActivityItem'; // 活动项容器组件
-import FollowButton from './FollowButton';
+import FollowButton from './FollowButton'; // 关注/取消关注按钮组件
 import React from 'react';
-import {type Account} from '../../api/activitypub';
+import { type Account } from '../../api/activitypub'; // 导入Account类型定义，描述用户账号信息
-import {Skeleton} from '@tryghost/shade';
+import { Skeleton } from '@tryghost/shade'; // 骨架屏组件，用于加载状态显示
-import {useNavigate} from '@tryghost/admin-x-framework';
+import { useNavigate } from '@tryghost/admin-x-framework'; // 路由导航钩子
-import {useSuggestedProfilesForUser} from '@hooks/use-activity-pub-queries';
+import { useSuggestedProfilesForUser } from '@hooks/use-activity-pub-queries'; // 获取推荐用户列表的自定义钩子
 
+// 推荐用户项组件的属性接口
 interface SuggestedProfileProps {
-    profile: Account;
+    profile: Account; // 用户账号信息
-    update: (id: string, updated: Partial<Account>) => void;
+    update: (id: string, updated: Partial<Account>) => void; // 更新用户信息的回调函数
-    isLoading: boolean;
+    isLoading: boolean; // 是否处于加载状态
 }
 
+/**
+ * 推荐用户项组件
+ * 展示单个推荐用户的信息，包括头像、名称、账号和关注按钮
+ */
 export const SuggestedProfile: React.FC<SuggestedProfileProps & {
-    onOpenChange?: (open: boolean) => void;
+    onOpenChange?: (open: boolean) => void; // 控制父组件弹窗/面板显示状态的回调
-}> = ({profile, update, isLoading, onOpenChange}) => {
+}> = ({ profile, update, isLoading, onOpenChange }) => {
+    // 处理关注操作的回调
     const onFollow = () => {
         update(profile.id, {
-            followedByMe: true,
+            followedByMe: true, // 更新为已关注状态
-            followerCount: profile.followerCount + 1
+            followerCount: profile.followerCount + 1 // 粉丝数+1
         });
     };
 
+    // 处理取消关注操作的回调
     const onUnfollow = () => {
         update(profile.id, {
-            followedByMe: false,
+            followedByMe: false, // 更新为未关注状态
-            followerCount: profile.followerCount - 1
+            followerCount: profile.followerCount - 1 // 粉丝数-1
         });
     };
 
-    const navigate = useNavigate();
+    const navigate = useNavigate(); // 路由导航实例
 
     return (
         <ActivityItem
             key={profile.id}
+            // 点击用户项导航到用户主页，并关闭可能的父级弹窗
             onClick={() => {
                 onOpenChange?.(false);
                 navigate(`/profile/${profile.handle}`);
             }}
         >
-            <APAvatar author={
+            {/* 用户头像组件 */}
-                {
+            <APAvatar
-                    icon: {
+                author={{
-                        url: profile.avatarUrl
+                    icon: { url: profile.avatarUrl },
-                    },
                     name: profile.name,
                     handle: profile.handle
-                }
+                }}
-            } onClick={() => onOpenChange?.(false)} />
+                onClick={() => onOpenChange?.(false)} // 点击头像关闭父级弹窗
+            />
+            
+            {/* 用户信息区域 */}
             <div className='flex grow flex-col break-anywhere'>
-                <span className='line-clamp-1 font-semibold text-black dark:text-white'>{!isLoading ? profile.name : <Skeleton className='w-full max-w-64' />}</span>
+                {/* 用户名 - 加载状态显示骨架屏 */}
-                <span className='line-clamp-1 text-sm text-gray-700 dark:text-gray-600'>{!isLoading ? profile.handle : <Skeleton className='w-24' />}</span>
+                <span className='line-clamp-1 font-semibold text-black dark:text-white'>
+                    {!isLoading ? profile.name : <Skeleton className='w-full max-w-64' />}
+                </span>
+                {/* 用户账号（handle） - 加载状态显示骨架屏 */}
+                <span className='line-clamp-1 text-sm text-gray-700 dark:text-gray-600'>
+                    {!isLoading ? profile.handle : <Skeleton className='w-24' />}
+                </span>
             </div>
-            {!isLoading ?
+            
+            {/* 关注按钮 - 加载状态显示骨架屏 */}
+            {!isLoading ? (
                 <FollowButton
                     className='ml-auto'
-                    following={profile.followedByMe}
+                    following={profile.followedByMe} // 当前关注状态
-                    handle={profile.handle}
+                    handle={profile.handle} // 用户账号标识
                     type='secondary'
-                    onFollow={onFollow}
+                    onFollow={onFollow} // 关注回调
-                    onUnfollow={onUnfollow}
+                    onUnfollow={onUnfollow} // 取消关注回调
-                /> :
+                />
+            ) : (
                 <div className='inline-flex items-center'>
                     <Skeleton className='w-12' />
                 </div>
-            }
+            )}
         </ActivityItem>
     );
 };
 
+/**
+ * 推荐用户列表组件
+ * 展示多个推荐用户，支持加载状态显示
+ */
 export const SuggestedProfiles: React.FC<{
-    onOpenChange?: (open: boolean) => void;
+    onOpenChange?: (open: boolean) => void; // 控制父组件弹窗/面板显示状态的回调
-}> = ({onOpenChange}) => {
+}> = ({ onOpenChange }) => {
-    const {suggestedProfilesQuery, updateSuggestedProfile} = useSuggestedProfilesForUser('index', 5);
+    // 获取推荐用户列表及更新方法（最多5个用户）
-    const {data: suggestedProfilesData = [], isLoading: isLoadingSuggestedProfiles} = suggestedProfilesQuery;
+    const { suggestedProfilesQuery, updateSuggestedProfile } = useSuggestedProfilesForUser('index', 5);
+    const {
+        data: suggestedProfilesData = [], // 推荐用户数据，默认空数组
+        isLoading: isLoadingSuggestedProfiles // 是否正在加载
+    } = suggestedProfilesQuery;
 
     return (
         <div className='mb-[-15px] flex flex-col gap-3 pt-2'>
             <div className='flex flex-col'>
+                {/* 加载状态时显示5个骨架项，否则显示实际推荐用户 */}
                 {(isLoadingSuggestedProfiles ? Array(5).fill(null) : (suggestedProfilesData || [])).map((profile, index) => (
                     <React.Fragment key={profile?.id || `loading-${index}`}>
                         <SuggestedProfile
                             isLoading={isLoadingSuggestedProfiles}
+                            // 加载状态时传入默认空对象，避免报错
                             profile={profile || {
                                 id: '',
                                 name: '',
@@ -93,7 +122,7 @@ export const SuggestedProfiles: React.FC<{
                                 followingCount: 0,
                                 followedByMe: false
                             }}
-                            update={updateSuggestedProfile}
+                            update={updateSuggestedProfile} // 传递更新方法
                             onOpenChange={onOpenChange}
                         />
                     </React.Fragment>
@@ -101,4 +130,4 @@ export const SuggestedProfiles: React.FC<{
             </div>
         </div>
     );
-};
+};

apps/admin-x-activitypub/src/components/layout/Sidebar/Sidebar.tsx

@@ -1,37 +1,66 @@
 import * as React from 'react';
+// 导入反馈框组件
 import FeedbackBox from './FeedbackBox';
+// 导入新建笔记模态框组件
 import NewNoteModal from '@src/components/modals/NewNoteModal';
+// 导入推荐内容组件
 import Recommendations from './Recommendations';
+// 导入搜索相关组件
 import Search from '@src/components/modals/Search';
 import SearchInput from '../Header/SearchInput';
+// 导入侧边栏菜单链接组件
 import SidebarMenuLink from './SidebarMenuLink';
-import {Button, Dialog, DialogContent, DialogTrigger, LucideIcon} from '@tryghost/shade';
+// 导入UI组件：按钮、对话框及相关组件、Lucide图标库
-import {useCurrentUser} from '@tryghost/admin-x-framework/api/currentUser';
+import { Button, Dialog, DialogContent, DialogTrigger, LucideIcon } from '@tryghost/shade';
-import {useFeatureFlags} from '@src/lib/feature-flags';
+// 导入获取当前用户信息的钩子
-import {useLocation} from '@tryghost/admin-x-framework';
+import { useCurrentUser } from '@tryghost/admin-x-framework/api/currentUser';
-import {useNotificationsCountForUser, useResetNotificationsCountForUser} from '@src/hooks/use-activity-pub-queries';
+// 导入特性标志相关钩子
+import { useFeatureFlags } from '@src/lib/feature-flags';
+// 导入路由位置钩子
+import { useLocation } from '@tryghost/admin-x-framework';
+// 导入通知计数相关钩子
+import { useNotificationsCountForUser, useResetNotificationsCountForUser } from '@src/hooks/use-activity-pub-queries';
 
+// 侧边栏组件属性接口
 interface SidebarProps {
-    isMobileSidebarOpen: boolean;
+    isMobileSidebarOpen: boolean; // 移动端侧边栏是否打开
-    onCloseMobileSidebar: () => void;
+    onCloseMobileSidebar: () => void; // 关闭移动端侧边栏的回调（注：组件内未使用，可能为预留）
 }
 
-const Sidebar: React.FC<SidebarProps> = ({isMobileSidebarOpen}) => {
+/**
-    const {allFlags, flags} = useFeatureFlags();
+ * 侧边栏组件
-    const [isSearchOpen, setIsSearchOpen] = React.useState(false);
+ * 展示导航菜单、搜索框、新建笔记按钮、推荐内容等，适配移动端和桌面端
-    const [searchQuery, setSearchQuery] = React.useState('');
+ */
-    const {data: currentUser} = useCurrentUser();
+const Sidebar: React.FC<SidebarProps> = ({ isMobileSidebarOpen }) => {
+    // 获取特性标志（用于功能开关控制）
+    const { allFlags, flags } = useFeatureFlags();
+    // 搜索相关状态
+    const [isSearchOpen, setIsSearchOpen] = React.useState(false); // 搜索对话框是否打开
+    const [searchQuery, setSearchQuery] = React.useState(''); // 搜索关键词
+    // 获取当前用户信息
+    const { data: currentUser } = useCurrentUser();
+    // 获取当前路由位置
     const location = useLocation();
-    const {data: notificationsCount} = useNotificationsCountForUser(currentUser?.slug || '');
+    // 获取通知计数
+    const { data: notificationsCount } = useNotificationsCountForUser(currentUser?.slug || '');
+    // 重置通知计数的方法
     const resetNotificationsCount = useResetNotificationsCountForUser(currentUser?.slug || '');
 
-    // Reset count when on notifications page
+    /**
+     * 当路由切换到通知页面时，重置通知计数
+     * 依赖项变化时触发（路由路径、通知计数、重置方法）
+     */
     React.useEffect(() => {
         if (location.pathname === '/notifications' && notificationsCount && notificationsCount > 0) {
             resetNotificationsCount.mutate();
         }
     }, [location.pathname, notificationsCount, resetNotificationsCount]);
 
+    /**
+     * 处理通知按钮点击事件
+     * 点击时重置通知计数（如果有未读通知）
+     * 使用useCallback缓存函数，避免不必要的重渲染
+     */
     const handleNotificationsClick = React.useCallback(() => {
         if (notificationsCount && notificationsCount > 0) {
             resetNotificationsCount.mutate();
@@ -39,21 +68,29 @@ const Sidebar: React.FC<SidebarProps> = ({isMobileSidebarOpen}) => {
     }, [notificationsCount, resetNotificationsCount]);
 
     return (
-        <div className={`sticky top-0 flex min-h-screen w-[320px] flex-col border-l border-gray-200 pr-8 transition-transform duration-300 ease-in-out max-lg:fixed max-lg:inset-y-0 max-lg:right-0 max-lg:z-50 max-lg:border-0 max-lg:bg-white max-lg:shadow-xl max-md:bottom-[72px] max-md:min-h-[auto] max-md:overflow-y-scroll dark:border-gray-950 max-lg:dark:bg-black ${
+        // 侧边栏容器，根据设备尺寸适配样式
-            isMobileSidebarOpen ? 'max-lg:translate-x-0' : 'max-lg:translate-x-full'
+        <div className={`sticky top-0 flex min-h-screen w-[320px] flex-col border-l border-gray-200 pr-8 transition-transform duration-300 ease-in-out 
-        }`}>
+            max-lg:fixed max-lg:inset-y-0 max-lg:right-0 max-lg:z-50 max-lg:border-0 max-lg:bg-white max-lg:shadow-xl 
+            max-md:bottom-[72px] max-md:min-h-[auto] max-md:overflow-y-scroll 
+            dark:border-gray-950 max-lg:dark:bg-black 
+            ${isMobileSidebarOpen ? 'max-lg:translate-x-0' : 'max-lg:translate-x-full'}`}>
             <div className='flex grow flex-col justify-between'>
+                {/* 侧边栏主要内容区域 */}
                 <div className='isolate flex w-full flex-col items-start gap-6 pl-6 pt-6'>
+                    {/* 搜索框区域 */}
                     <div className='flex h-[52px] w-full items-center'>
                         <Dialog open={isSearchOpen} onOpenChange={setIsSearchOpen}>
                             <DialogTrigger className='w-full'>
-                                <SearchInput />
+                                <SearchInput /> {/* 搜索输入框 */}
                             </DialogTrigger>
                             <DialogContent>
+                                {/* 搜索结果展示组件 */}
                                 <Search query={searchQuery} setQuery={setSearchQuery} onOpenChange={setIsSearchOpen} />
                             </DialogContent>
                         </Dialog>
                     </div>
+
+                    {/* 导航菜单链接列表 */}
                     <div className='flex w-full flex-col gap-px'>
                         <SidebarMenuLink to='/reader'>
                             <LucideIcon.BookOpen size={18} strokeWidth={1.5} />
@@ -64,7 +101,7 @@ const Sidebar: React.FC<SidebarProps> = ({isMobileSidebarOpen}) => {
                             Notes
                         </SidebarMenuLink>
                         <SidebarMenuLink
-                            count={location.pathname !== '/notifications' ? notificationsCount : undefined}
+                            count={location.pathname !== '/notifications' ? notificationsCount : undefined} // 非通知页显示未读计数
                             to='/notifications'
                             onClick={handleNotificationsClick}
                         >
@@ -84,6 +121,8 @@ const Sidebar: React.FC<SidebarProps> = ({isMobileSidebarOpen}) => {
                             Preferences
                         </SidebarMenuLink>
                     </div>
+
+                    {/* 新建笔记按钮（包裹在模态框组件中） */}
                     <NewNoteModal>
                         <Button className='h-9 rounded-full bg-purple-500 px-3 text-md text-white hover:bg-purple-600 dark:hover:bg-purple-600'>
                             <LucideIcon.FilePen />
@@ -91,8 +130,10 @@ const Sidebar: React.FC<SidebarProps> = ({isMobileSidebarOpen}) => {
                         </Button>
                     </NewNoteModal>
 
+                    {/* 推荐内容区域 */}
                     <Recommendations />
 
+                    {/* 特性标志展示（仅显示开启的标志，用于开发/调试） */}
                     {allFlags.map((flag) => {
                         if (flags[flag]) {
                             return (
@@ -104,9 +145,11 @@ const Sidebar: React.FC<SidebarProps> = ({isMobileSidebarOpen}) => {
                                 </div>
                             );
                         }
-                        return (<></>);
+                        return null;
                     })}
                 </div>
+
+                {/* 底部反馈框 */}
                 <div className='sticky bottom-0 flex items-center gap-2 bg-white pb-4 pl-4 dark:bg-black'>
                     <FeedbackBox />
                 </div>
@@ -115,6 +158,7 @@ const Sidebar: React.FC<SidebarProps> = ({isMobileSidebarOpen}) => {
     );
 };
 
+// 设置组件显示名称（便于调试）
 Sidebar.displayName = 'Sidebar';
 
-export default Sidebar;
+export default Sidebar;

apps/admin-x-activitypub/src/components/layout/Sidebar/SidebarMenuLink.tsx

@@ -1,52 +1,68 @@
 import * as React from 'react';
-import {Button, ButtonProps, cn, formatNumber} from '@tryghost/shade';
+// 导入UI组件及工具函数：按钮组件、按钮属性类型、类名组合函数、数字格式化函数
-import {Link, resetScrollPosition, useLocation, useNavigationStack} from '@tryghost/admin-x-framework';
+import { Button, ButtonProps, cn, formatNumber } from '@tryghost/shade';
+// 导入路由相关工具：链接组件、滚动位置重置函数、路由位置钩子、导航栈钩子
+import { Link, resetScrollPosition, useLocation, useNavigationStack } from '@tryghost/admin-x-framework';
 
+// 侧边栏菜单链接组件的属性接口，继承按钮属性并扩展路由和计数相关属性
 interface SidebarButtonProps extends ButtonProps {
-    to?: string;
+    to?: string; // 路由路径（可选，用于导航链接）
-    children: React.ReactNode;
+    children: React.ReactNode; // 子元素（图标和文本）
-    count?: number;
+    count?: number; // 数量标记（可选，如未读通知数）
 }
 
+/**
+ * 侧边栏菜单链接组件
+ * 用于侧边栏导航，支持路由跳转、当前页面高亮、数量标记显示
+ */
 const SidebarMenuLink = React.forwardRef<HTMLButtonElement, SidebarButtonProps>(
-    ({to, children, count, ...props}, ref) => {
+    ({ to, children, count, ...props }, ref) => {
-        const location = useLocation();
+        const location = useLocation(); // 获取当前路由位置
-        const {resetStack} = useNavigationStack();
+        const { resetStack } = useNavigationStack(); // 获取重置导航栈的方法
 
+        // 组合链接的CSS类名
         const linkClass = cn(
+            // 基础样式：左对齐、中等文本大小、中等字重、默认文本色、悬停背景（深色模式）
             'justify-start text-md font-medium text-gray-800 dark:hover:bg-gray-925/70 dark:text-gray-500 h-9 [&_svg]:size-[18px]',
+            // 当前页面高亮样式：背景色、文本色加深（深色模式适配）
             (to && location.pathname === to) && 'bg-gray-100 dark:bg-gray-925/70 dark:text-white text-black font-semibold'
         );
 
+        // 数量标记徽章（当有数量且大于0时显示）
         const badge = count && count > 0 ? (
             <span className={cn(
                 'ml-auto bg-purple-500 text-white text-xs font-semibold py-1 px-1.5 rounded-full min-w-[20px] h-5 flex items-center justify-center'
             )}>
-                {formatNumber(count)}
+                {formatNumber(count)} {/* 格式化数字显示（如1000→1k） */}
             </span>
         ) : null;
 
+        // 当提供路由路径时，渲染为链接组件
         if (to) {
             return (
                 <Button className={linkClass} variant='ghost' asChild>
-                    <Link to={to} onClick={() => {
+                    <Link 
-                        resetStack();
+                        to={to} 
-                        resetScrollPosition(to);
+                        onClick={() => {
-                    }}>
+                            resetStack(); // 重置导航栈（清除历史记录）
-                        {children}
+                            resetScrollPosition(to); // 跳转到目标路由时重置滚动位置
-                        {badge}
+                        }}
+                    >
+                        {children} {/* 显示图标和文本 */}
+                        {badge} {/* 显示数量徽章（如有） */}
                     </Link>
                 </Button>
             );
         }
 
+        // 未提供路由路径时，渲染为普通按钮
         return (
             <Button
-                ref={ref}
+                ref={ref} // 转发ref到按钮元素
                 className={linkClass}
                 variant='ghost'
-                onClick={props.onClick}
+                onClick={props.onClick} // 传递点击事件
-                {...props}
+                {...props} // 传递其他按钮属性
             >
                 {children}
                 {badge}
@@ -55,6 +71,7 @@ const SidebarMenuLink = React.forwardRef<HTMLButtonElement, SidebarButtonProps>(
     }
 );
 
+// 设置组件显示名称（便于React DevTools识别）
 SidebarMenuLink.displayName = 'SidebarMenuLink';
 
-export default SidebarMenuLink;
+export default SidebarMenuLink;

apps/admin-x-framework/src/api/referrers.ts

@@ -1,5 +1,11 @@
 import {createQuery} from '../utils/api/hooks';
 
+// ReferrerHistoryItem：表示单条来源历史记录的结构
+// - date: 日期字符串（通常为 ISO 格式）
+// - signups: 该日期来自该来源的注册数
+// - source: 来源名称，若未知则为 null
+// - paid_conversions: 付费转化次数（例如成功订阅）
+// - mrr: 该来源在该日期贡献的月度经常性收入（Monthly Recurring Revenue）
 export type ReferrerHistoryItem = {
     date: string,
     signups: number,
@@ -8,17 +14,26 @@ export type ReferrerHistoryItem = {
     mrr: number
 };
 
+// ReferrerHistoryResponseType：后端返回的历史数据响应结构，包含 stats 数组
 export interface ReferrerHistoryResponseType {
     stats: ReferrerHistoryItem[];
 }
 
+// dataType：用于 createQuery 的标识字符串（用于缓存/调试/metrics 等）
 const dataType = 'ReferrerHistoryResponseType';
 
+// useReferrerHistory：Hook / 查询，获取来源历史时间序列数据
+// - 请求路径：GET /stats/referrers/
+// - 返回类型：ReferrerHistoryResponseType
+// 使用场景：给增长图表、来源折线图或列表提供数据
 export const useReferrerHistory = createQuery<ReferrerHistoryResponseType>({
     dataType,
     path: '/stats/referrers/'
 });
 
+// useTopSourcesGrowth：查询“Top sources growth”数据（来源增长趋势）
+// - 请求路径：GET /stats/top-sources-growth
+// - 注意：dataType 字符串与上面不同，以便区分缓存条目或响应处理
 export const useTopSourcesGrowth = createQuery<ReferrerHistoryResponseType>({
     dataType: 'TopSourcesGrowthResponseType',
     path: '/stats/top-sources-growth'

apps/admin-x-framework/src/api/stats.ts

@@ -1,22 +1,31 @@
 import {Meta, createQuery, createQueryWithId} from '../utils/api/hooks';
 
-// Types
+/*
+  文件说明：
+  - 本文件定义了与统计/分析相关的 TypeScript 类型（Types）以及用于向后端请求统计数据的 Hook（createQuery/createQueryWithId 封装）。
+  - 这些 Hook 会请求后端的 /stats/* 接口，返回结构化的数据，供前端可视化组件（图表/列表）使用。
+*/
 
+/* ----------------------------- Types ----------------------------- */
+
+/* TopContentItem：热门内容条目的结构（用于 Top content 列表） */
 export type TopContentItem = {
-    pathname: string;
+    pathname: string;       // 内容路径（如 /post/slug）
-    visits: number;
+    visits: number;         // 访问次数
-    title?: string;
+    title?: string;         // 标题（可选，若爬取或关联到文章）
-    post_uuid?: string;
+    post_uuid?: string;     // 文章 UUID（可选）
-    post_id?: string;
+    post_id?: string;       // 文章 ID（可选）
-    post_type?: string;
+    post_type?: string;     // 内容类型（post/page 等，可选）
-    url_exists?: boolean;
+    url_exists?: boolean;   // 链接是否有效（可选）
 }
 
+/* TopContentResponseType：热门内容接口的返回类型，包含 stats 数组与分页元信息 */
 export type TopContentResponseType = {
     stats: TopContentItem[];
     meta: Meta;
 }
 
+/* MemberStatusItem：会员统计按日期的结构（用于会员数量历史） */
 export type MemberStatusItem = {
     date: string;
     paid: number;
@@ -26,6 +35,7 @@ export type MemberStatusItem = {
     paid_canceled: number;
 }
 
+/* MemberCountHistoryResponseType：会员数量历史接口返回类型，包含统计数组和 totals */
 export type MemberCountHistoryResponseType = {
     stats: MemberStatusItem[];
     meta: {
@@ -37,6 +47,7 @@ export type MemberCountHistoryResponseType = {
     };
 }
 
+/* TopPostStatItem：热门文章统计项，含成员/收益等指标 */
 export type TopPostStatItem = {
     post_id: string;
     attribution_url: string;
@@ -50,11 +61,13 @@ export type TopPostStatItem = {
     url_exists?: boolean;
 };
 
+/* TopPostsStatsResponseType：热门文章统计接口返回类型 */
 export type TopPostsStatsResponseType = {
     stats: TopPostStatItem[];
     meta: Meta;
 };
 
+/* PostReferrerStatItem：单篇文章的来源统计项（来源名称及贡献的成员/收益） */
 export type PostReferrerStatItem = {
     source: string;
     referrer_url?: string;
@@ -68,6 +81,7 @@ export type PostReferrersResponseType = {
     meta: Meta;
 };
 
+/* PostGrowthStatItem：单篇文章按日期的增长统计项（成员增长/付费等） */
 export type PostGrowthStatItem = {
     post_id: string;
     free_members: number;
@@ -80,6 +94,7 @@ export type PostGrowthStatsResponseType = {
     meta: Meta;
 };
 
+/* MRR（经常性收入）相关类型：历史项与总计结构 */
 export type MrrHistoryItem = {
     date: string;
     mrr: number;
@@ -101,6 +116,7 @@ export type MrrHistoryResponseType = {
     };
 };
 
+/* Newsletter / 邮件简报相关类型（用于统计打开/点击/发送量等） */
 export type NewsletterStatItem = {
     post_id: string;
     post_title: string;
@@ -117,9 +133,10 @@ export type NewsletterStatsResponseType = {
     meta: Meta;
 };
 
+/* NewsletterSubscriberStats：按日期累计订阅数结构 */
 export type NewsletterSubscriberValue = {
     date: string;
-    value: number; // Cumulative subscriber count for this date
+    value: number; // 该日期的累计订阅者数量
 };
 
 export type NewsletterSubscriberStats = {
@@ -131,6 +148,7 @@ export type NewsletterSubscriberStatsResponseType = {
     stats: NewsletterSubscriberStats[];
 };
 
+/* PostStats：文章在不同维度（打开、访客、成员变动等）的统计结构 */
 export interface PostStats {
     id: string;
     recipient_count: number | null;
@@ -146,6 +164,7 @@ export type PostStatsResponseType = {
     stats: PostStats[];
 };
 
+/* TopPostViewsStats：热门文章浏览量详情类型 */
 export type TopPostViewsStats = {
     post_id: string;
     title: string;
@@ -168,7 +187,7 @@ export type TopPostViewsResponseType = {
     stats: TopPostViewsStats[];
 };
 
-// Types for subscription stats
+/* Subscription stats：订阅相关按日期统计类型（用于订阅/取消/计数等） */
 export type SubscriptionStatItem = {
     date: string;
     tier: string;
@@ -193,8 +212,12 @@ export type SubscriptionStatsResponseType = {
     };
 };
 
-// Requests
+/* ----------------------------- Requests (Hooks) ----------------------------- */
 
+/*
+  dataType 常量：用于 createQuery 的标识，一般用于缓存键、调试输出或网络请求追踪。
+  每个 hook 对应后端的一个 /stats/* 路由，返回与上述类型匹配的数据结构。
+*/
 const dataType = 'TopContentResponseType';
 const memberCountHistoryDataType = 'MemberCountHistoryResponseType';
 const topPostsStatsDataType = 'TopPostsStatsResponseType';
@@ -207,50 +230,63 @@ const mrrHistoryDataType = 'MrrHistoryResponseType';
 const topPostViewsDataType = 'TopPostViewsResponseType';
 const subscriptionStatsDataType = 'SubscriptionStatsResponseType';
 
+/* useTopContent：获取热门内容列表（GET /stats/top-content/），返回 TopContentResponseType */
 export const useTopContent = createQuery<TopContentResponseType>({
     dataType,
     path: '/stats/top-content/'
 });
 
+/* useMemberCountHistory：获取会员数量历史（GET /stats/member_count/） */
 export const useMemberCountHistory = createQuery<MemberCountHistoryResponseType>({
     dataType: memberCountHistoryDataType,
     path: '/stats/member_count/'
 });
 
+/* useTopPostsStats：获取热门文章相关统计（GET /stats/top-posts/） */
 export const useTopPostsStats = createQuery<TopPostsStatsResponseType>({
     dataType: topPostsStatsDataType,
     path: '/stats/top-posts/'
 });
 
+/* usePostReferrers：按文章 ID 获取该文章的来源统计（GET /stats/posts/:id/top-referrers） */
 export const usePostReferrers = createQueryWithId<PostReferrersResponseType>({
     dataType: postReferrersDataType,
     path: id => `/stats/posts/${id}/top-referrers`
 });
 
+/* usePostGrowthStats：按文章 ID 获取该文章的增长时间序列（GET /stats/posts/:id/growth） */
 export const usePostGrowthStats = createQueryWithId<PostGrowthStatsResponseType>({
     dataType: postGrowthStatsDataType,
     path: id => `/stats/posts/${id}/growth`
 });
+
+/* useMrrHistory：获取 MRR 历史（GET /stats/mrr/） */
 export const useMrrHistory = createQuery<MrrHistoryResponseType>({
     dataType: mrrHistoryDataType,
     path: '/stats/mrr/'
 });
 
+/* useSubscriptionStats：获取订阅统计（GET /stats/subscriptions/） */
 export const useSubscriptionStats = createQuery<SubscriptionStatsResponseType>({
     dataType: subscriptionStatsDataType,
     path: '/stats/subscriptions/'
 });
 
+/* usePostStats：按文章 ID 获取多维度文章统计（GET /stats/posts/:id/stats/） */
 export const usePostStats = createQueryWithId<PostStatsResponseType>({
     dataType: 'PostStatsResponseType',
     path: id => `/stats/posts/${id}/stats/`
 });
 
+/* useTopPostsViews：获取按浏览量排序的文章列表（GET /stats/top-posts-views/） */
 export const useTopPostsViews = createQuery<TopPostViewsResponseType>({
     dataType: topPostViewsDataType,
     path: '/stats/top-posts-views/'
 });
 
+/* ----------------------------- Newsletter hooks ----------------------------- */
+
+/* 支持基于参数查询的 newsletter hooks（包含包装函数以接收 newsletterId 等参数） */
 export interface NewsletterStatsSearchParams {
     newsletterId?: string;
     date_from?: string;
@@ -269,7 +305,7 @@ export const useNewsletterStats = createQuery<NewsletterStatsResponseType>({
     dataType: newsletterStatsDataType,
     path: '/stats/newsletter-stats/',
     defaultSearchParams: {
-        // Empty default params, will be filled by the hook
+        // 空的默认参数，会在调用时由 hook 填充
     }
 });
 
@@ -277,7 +313,7 @@ export const useNewsletterBasicStats = createQuery<NewsletterStatsResponseType>(
     dataType: newsletterStatsDataType,
     path: '/stats/newsletter-basic-stats/',
     defaultSearchParams: {
-        // Empty default params, will be filled by the hook
+        // 空的默认参数，会在调用时由 hook 填充
     }
 });
 
@@ -285,11 +321,11 @@ export const useNewsletterClickStats = createQuery<NewsletterStatsResponseType>(
     dataType: newsletterStatsDataType,
     path: '/stats/newsletter-click-stats/',
     defaultSearchParams: {
-        // Empty default params, will be filled by the hook
+        // 空的默认参数，会在调用时由 hook 填充
     }
 });
 
-// Hook wrapper to accept a newsletterId parameter
+/* useNewsletterStatsByNewsletterId：包装器，接受 newsletterId 与额外选项并构建搜索参数 */
 export const useNewsletterStatsByNewsletterId = (newsletterId?: string, options: Partial<NewsletterStatsSearchParams> = {}, queryOptions: {enabled?: boolean} = {}) => {
     const searchParams: Record<string, string> = {};
 
@@ -297,7 +333,7 @@ export const useNewsletterStatsByNewsletterId = (newsletterId?: string, options:
         searchParams.newsletter_id = newsletterId;
     }
 
-    // Add any additional search params
+    // 添加其它可选参数（日期范围、排序、限制等）
     if (options.date_from) {
         searchParams.date_from = options.date_from;
     }
@@ -318,11 +354,11 @@ export const useSubscriberCount = createQuery<NewsletterSubscriberStatsResponseT
     dataType: newsletterSubscriberStatsDataType,
     path: '/stats/subscriber-count/',
     defaultSearchParams: {
-        // Empty default params, will be filled by the hook
+        // 空的默认参数，会在调用时由 hook 填充
     }
 });
 
-// Hook wrapper to accept a newsletterId parameter
+/* useSubscriberCountByNewsletterId：包装器，构建 newsletter_id 与日期参数后调用 useSubscriberCount */
 export const useSubscriberCountByNewsletterId = (newsletterId?: string, options: Partial<SubscriberCountSearchParams> = {}) => {
     const searchParams: Record<string, string> = {};
 
@@ -330,7 +366,7 @@ export const useSubscriberCountByNewsletterId = (newsletterId?: string, options:
         searchParams.newsletter_id = newsletterId;
     }
 
-    // Add any additional search params
+    // 可选的日期范围参数
     if (options.date_from) {
         searchParams.date_from = options.date_from;
     }

apps/admin-x-framework/src/utils/post-helpers.ts

@@ -1,46 +1,66 @@
 import {Post} from '../api/posts';
 
 /**
- * Determines if a post is email-only (newsletter only, not published to the web)
+ * 判断文章是否为仅邮件（只通过邮件发送，不在网站发布）
+ * - 返回 true 当 post.email_only 为真且状态为 'sent'
  */
 export function isEmailOnly(post: Post): boolean {
     return Boolean(post.email_only) && post.status === 'sent';
 }
 
 /**
- * Determines if a post is published-only (web only, no email sent)
+ * 判断文章是否为仅发布到网站（已发布但未作为邮件发送）
+ * - 返回 true 当状态为 'published' 且未发送过邮件
  */
 export function isPublishedOnly(post: Post): boolean {
     return post.status === 'published' && !hasBeenEmailed(post);
 }
 
 /**
- * Determines if a post is both published and emailed
+ * 判断文章是否既发布到网站又发送为邮件
+ * - 返回 true 当状态为 'published' 且已发送邮件
  */
 export function isPublishedAndEmailed(post: Post): boolean {
     return post.status === 'published' && hasBeenEmailed(post);
 }
 
 /**
- * Determines if a post has been sent as an email
+ * 判断文章是否被发送过邮件（内部辅助函数）
- * Based on the logic from admin-x-framework/src/utils/post-utils.ts
+ * 逻辑说明：
+ * - 认为已发送邮件的条件为：状态为 sent 或 published，并且存在 email 对象
+ * - 同时要求 email 未标记为失败（status !== 'failed'）或有有效的 email_count（>0）
+ *
+ * 该函数用于区分“已发送邮件”和“未发送邮件”的边界情况（例如发送失败但有记录等）。
  */
 function hasBeenEmailed(post: Post): boolean {
     const isPublished = post.status === 'published';
     const isSent = post.status === 'sent';
     const hasEmail = Boolean(post.email);
-    const validEmailStatus = post.email?.status !== 'failed';
+    const validEmailStatus = post.email?.status !== 'failed'; // 邮件状态不为 failed 则视为有效
-    const hasEmailCount = typeof post.email?.email_count === 'number' && post.email.email_count > 0;
+    const hasEmailCount = typeof post.email?.email_count === 'number' && post.email.email_count > 0; // 有发送计数
-    
+
+    // 只有在已发送或已发布且存在 email 信息，且 email 状态有效或有发送次数时，
+    // 才认为文章“已被邮件发送/记录为邮件发送过”
     return (isSent || isPublished)
         && hasEmail 
         && (validEmailStatus || hasEmailCount);
 }
 
 /**
- * Gets the appropriate metrics to display based on post type and settings
+ * 根据文章类型和站点设置决定在分析界面应展示哪些指标
+ * 返回对象包含：
+ * - showEmailMetrics: 是否显示邮件相关指标（opens/clicks 等）
+ * - showWebMetrics: 是否显示网站相关指标（views/visitors 等）
+ * - showMemberGrowth: 是否显示会员增长/来源相关指标（取决于站点设置 membersTrackSources）
+ *
+ * 逻辑：
+ * - 仅邮件文章 (isEmailOnly) -> 只显示邮件指标
+ * - 仅发布文章 (isPublishedOnly) -> 只显示网站指标
+ * - 两者都有 (isPublishedAndEmailed) -> 两者都显示
+ * - 默认兜底：显示网站指标
  */
 export function getPostMetricsToDisplay(post: Post, settings?: {membersTrackSources?: boolean}) {
+    // settings.membersTrackSources 如果未配置，默认取 true（显示会员增长来源）
     const showMemberGrowth = settings?.membersTrackSources ?? true;
     
     if (isEmailOnly(post)) {
@@ -67,7 +87,7 @@ export function getPostMetricsToDisplay(post: Post, settings?: {membersTrackSour
         };
     }
     
-    // Default fallback
+    // 默认回退：显示网站指标并隐藏邮件指标
     return {
         showEmailMetrics: false,
         showWebMetrics: true,
@@ -76,6 +96,8 @@ export function getPostMetricsToDisplay(post: Post, settings?: {membersTrackSour
 }
 
 /**
- * Post type information with computed properties
+ * 后续可在此处添加与文章指标相关的辅助方法，例如：
+ * - formatPostUrl(post)
+ * - shouldShowTopSources(post, settings)
+ * - deriveDefaultTimeRange(post)
  */
- 

apps/admin-x-framework/src/utils/source-utils.ts

@@ -1,4 +1,8 @@
-// Source domain mapping for favicons
+/**
+ * Source domain mapping for favicons
+ * - 用于将显示名或来源标识映射到用于抓取 favicon 的域名。
+ * - 优先用于已知来源（例如 Reddit -> reddit.com），便于生成图标 URL 或外链。
+ */
 export const SOURCE_DOMAIN_MAP: Record<string, string> = {
     Reddit: 'reddit.com',
     'www.reddit.com': 'reddit.com',
@@ -39,7 +43,11 @@ export const SOURCE_DOMAIN_MAP: Record<string, string> = {
     newsletter: 'static.ghost.org'
 };
 
-// Comprehensive source normalization mapping
+/**
+ * SOURCE_NORMALIZATION_MAP
+ * - 用于规范化来源字符串到统一的展示名称（大小写/别名归一）。
+ * - 在处理 referrer 数据时先做归一化，便于汇总相同来源（如 facebook 与 www.facebook.com）。
+ */
 export const SOURCE_NORMALIZATION_MAP = new Map<string, string>([
     // Social Media Consolidation
     ['facebook', 'Facebook'],
@@ -141,9 +149,10 @@ export const SOURCE_NORMALIZATION_MAP = new Map<string, string>([
 ]);
 
 /**
- * Normalize source names to consistent display names
+ * normalizeSource
- * @param source - Raw source string from referrer data
+ * - 将原始的 source 字符串规范化为展示名称。
- * @returns Normalized source name or 'Direct' for empty/null sources
+ * - 若 source 为空或 null，返回 'Direct' 表示直接访问。
+ * - 使用小写匹配 SOURCE_NORMALIZATION_MAP 做归一化；若未命中则原样返回。
  */
 export function normalizeSource(source: string | null): string {
     if (!source || source === '') {
@@ -155,7 +164,11 @@ export function normalizeSource(source: string | null): string {
     return SOURCE_NORMALIZATION_MAP.get(lowerSource) || source;
 }
 
-// Helper function to extract domain from URL
+/**
+ * extractDomain
+ * - 从给定 URL 或域名字符串中提取主机名并移除 www. 前缀。
+ * - 对无效 URL 返回 null（安全解析）。
+ */
 export const extractDomain = (url: string): string | null => {
     try {
         const domain = new URL(url.startsWith('http') ? url : `https://${url}`).hostname;
@@ -171,6 +184,11 @@ export interface ExtendSourcesOptions {
     mode: 'visits' | 'growth';
 }
 
+/**
+ * extendSourcesWithPercentages
+ * - 在 mode 为 'visits' 时为每个已处理的来源项计算访问百分比 (visits / totalVisitors)。
+ * - 在 growth 模式下不计算百分比（growth 关注成员/收入等指标）。
+ */
 export function extendSourcesWithPercentages({
     processedData,
     totalVisitors,
@@ -186,7 +204,11 @@ export function extendSourcesWithPercentages({
     }));
 };
 
-// Helper function to check if a domain is the same or a subdomain
+/**
+ * isDomainOrSubdomain
+ * - 判断 sourceDomain 是否等于 siteDomain 或为其子域（例如 blog.example.com 属于 example.com）。
+ * - 用于将站点自身来源识别为“Direct”类型流量。
+ */
 export const isDomainOrSubdomain = (sourceDomain: string, siteDomain: string): boolean => {
     // Exact match
     if (sourceDomain === siteDomain) {
@@ -197,7 +219,20 @@ export const isDomainOrSubdomain = (sourceDomain: string, siteDomain: string): b
     return sourceDomain.endsWith(`.${siteDomain}`);
 };
 
-// Helper function to get favicon domain and determine if it's direct traffic
+/**
+ * getFaviconDomain
+ * - 输入：source（可能为来源名/域名/URL）、siteUrl（站点地址）
+ * - 输出：{domain, isDirectTraffic}
+ * - 逻辑：
+ *   1. 若 source 为空或非字符串 -> 返回 null domain，isDirectTraffic = false
+ *   2. 若 source 字符串为 'Direct' -> 标识为直接流量（isDirectTraffic = true）
+ *   3. 用 siteUrl 提取站点域名，若 source 与站点域名相同或为子域 -> 视为直接流量
+ *   4. 在 SOURCE_DOMAIN_MAP 中查找已知来源对应的域名 -> 返回该域名（用于 favicon/链接）
+ *   5. 否则判断 source 本身是否已是域名，若是则清理后返回
+ *   6. 否则无法解析，返回 null domain
+ *
+ * - 返回的 domain 用于生成 favicon 抓取 URL 或外链（例如 https://<domain>）。
+ */
 export const getFaviconDomain = (source: string | number | undefined, siteUrl?: string): {domain: string | null, isDirectTraffic: boolean} => {
     if (!source || typeof source !== 'string') {
         return {domain: null, isDirectTraffic: false};
@@ -230,7 +265,7 @@ export const getFaviconDomain = (source: string | number | undefined, siteUrl?:
         return {domain: mappedDomain, isDirectTraffic: false};
     }
 
-    // If not in mapping, check if it's already a domain
+    // If not in mapping, check if it's already a domain (basic domain regex)
     const isDomain = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/.test(source);
     if (isDomain) {
         // Clean up the domain by removing www. prefix
@@ -242,7 +277,12 @@ export const getFaviconDomain = (source: string | number | undefined, siteUrl?:
     return {domain: null, isDirectTraffic: false};
 };
 
-// Base interface for all source data types
+/* ----------------------------- Data Structures ----------------------------- */
+
+/**
+ * BaseSourceData
+ * - 接口表示后端返回的原始来源数据项（可能含不同字段，用于 visits/growth 模式）
+ */
 export interface BaseSourceData {
     source?: string | number;
     visits?: number;
@@ -252,7 +292,11 @@ export interface BaseSourceData {
     [key: string]: unknown;
 }
 
-// Processed source data with pre-computed display values
+/**
+ * ProcessedSourceData
+ * - 处理后用于前端展示的来源数据结构
+ * - 包括已解析的 displayName、图标地址(iconSrc)、是否为直接流量、以及增长相关字段
+ */
 export interface ProcessedSourceData {
     source: string;
     visits: number;
@@ -275,6 +319,21 @@ export interface ProcessSourcesOptions {
     defaultSourceIconUrl: string;
 }
 
+/**
+ * processSources
+ * - 将后端返回的原始来源数组（data）处理成前端展示数组：
+ *   - 归并相同来源（累加 visits / growth 字段）
+ *   - 将站点自身或子域标记为 Direct，并合并为一项
+ *   - 为非 Direct 来源构建 favicon URL 和外链
+ *   - 根据 mode (visits | growth) 做不同的排序与字段处理
+ *
+ * 参数说明：
+ * - data: 后端原始来源数组（可能为 null）
+ * - mode: 'visits' 表示按访问数处理；'growth' 表示按成员/收益增长处理
+ * - siteUrl: 站点地址（用于识别 direct traffic）
+ * - siteIcon: 站点图标 URL（用于 Direct 图标显示）
+ * - defaultSourceIconUrl: 当无法解析 faviconDomain 时使用的默认图标
+ */
 export function processSources({
     data,
     mode,
@@ -311,12 +370,14 @@ export function processSources({
         } else {
             // Keep other sources as-is
             const sourceKey = String(item.source);
+            // 若有 faviconDomain 则使用 favicon 服务拼接图标地址，否则使用默认图标
             const iconSrc = faviconDomain
                 ? `https://www.faviconextractor.com/favicon/${faviconDomain}?larger=true`
                 : defaultSourceIconUrl;
             const linkUrl = faviconDomain ? `https://${faviconDomain}` : undefined;
 
             if (sourceMap.has(sourceKey)) {
+                // 已存在则累加数值（用于合并相同来源）
                 const existing = sourceMap.get(sourceKey)!;
                 existing.visits += visits;
                 if (mode === 'growth') {
@@ -325,6 +386,7 @@ export function processSources({
                     existing.mrr = (existing.mrr || 0) + (item.mrr || 0);
                 }
             } else {
+                // 新建处理项
                 const processedItem: ProcessedSourceData = {
                     source: sourceKey,
                     visits,
@@ -380,7 +442,7 @@ export function processSources({
             return bScore - aScore;
         });
     } else {
-        // Sort by visits
+        // Sort by visits（降序）
         return result.sort((a, b) => b.visits - a.visits);
     }
 }

apps/admin-x-framework/test/unit/utils/post-helpers.test.ts

@@ -1,9 +1,16 @@
+/**
+ * 单元测试：utils/post-helpers
+ * 说明：验证 isEmailOnly / isPublishedOnly / isPublishedAndEmailed / getPostMetricsToDisplay
+ *      这些辅助函数在不同文章状态和 email 信息组合下的行为是否正确。
+ */
+
 import {isEmailOnly, isPublishedOnly, isPublishedAndEmailed, getPostMetricsToDisplay} from '../../../src/utils/post-helpers';
 import {Post} from '../../../src/api/posts';
 
 describe('post-helpers', () => {
     describe('isEmailOnly', () => {
         it('returns true for email-only posts with sent status', () => {
+            // email_only 且 status 为 sent -> 认为是仅邮件发送的文章
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -17,6 +24,7 @@ describe('post-helpers', () => {
         });
 
         it('returns false for email-only posts with published status', () => {
+            // 即便 email_only 为 true，但 status 为 published -> 不是仅邮件（已发布也在线）
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -30,6 +38,7 @@ describe('post-helpers', () => {
         });
 
         it('returns false for non-email-only posts with sent status', () => {
+            // status 为 sent 但 email_only 为 false -> 不是仅邮件
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -43,6 +52,7 @@ describe('post-helpers', () => {
         });
 
         it('returns false when email_only is undefined', () => {
+            // 未设置 email_only -> 默认为 false
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -55,6 +65,7 @@ describe('post-helpers', () => {
         });
 
         it('returns false for draft posts even with email_only true', () => {
+            // 草稿状态即使标记为 email_only 也不认为是已发送的仅邮件文章
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -70,6 +81,7 @@ describe('post-helpers', () => {
 
     describe('isPublishedOnly', () => {
         it('returns true for published posts without email', () => {
+            // 已发布且没有 email 信息 -> 仅在网站发布
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -82,6 +94,7 @@ describe('post-helpers', () => {
         });
 
         it('returns false for published posts with email', () => {
+            // 已发布且包含有效 email 信息 -> 既发布又发邮件，不是仅发布
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -99,6 +112,7 @@ describe('post-helpers', () => {
         });
 
         it('returns true for published posts with failed email', () => {
+            // 已发布但 email 状态为 failed 且无发送记录 -> 仍视为仅发布（邮件失败不计）
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -116,6 +130,7 @@ describe('post-helpers', () => {
         });
 
         it('returns false for draft posts', () => {
+            // 草稿不属于已发布
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -128,6 +143,7 @@ describe('post-helpers', () => {
         });
 
         it('returns false for sent posts', () => {
+            // sent 状态表示仅邮件或已发送邮件，不视为仅发布
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -142,6 +158,7 @@ describe('post-helpers', () => {
 
     describe('isPublishedAndEmailed', () => {
         it('returns true for published posts with valid email', () => {
+            // 已发布且有有效 email（非 failed 或有发送量） -> 同时为发布与发邮件
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -159,6 +176,7 @@ describe('post-helpers', () => {
         });
 
         it('returns false for published posts without email', () => {
+            // 已发布但没有 email 信息 -> 不是同时发布与发邮件
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -171,6 +189,7 @@ describe('post-helpers', () => {
         });
 
         it('returns false for sent posts with email', () => {
+            // sent 状态不是 published，即便有 email 也不满足 publishedAndEmailed
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -188,6 +207,7 @@ describe('post-helpers', () => {
         });
 
         it('returns false for published posts with failed email', () => {
+            // 已发布但 email 状态为 failed 且无发送量 -> 不认为已成功发邮件
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -205,6 +225,7 @@ describe('post-helpers', () => {
         });
 
         it('returns true for published posts with failed status but positive email_count', () => {
+            // 虽然 email.status 为 failed，但如果有正的 email_count（历史发送记录），仍视为已发邮件
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -224,6 +245,7 @@ describe('post-helpers', () => {
 
     describe('getPostMetricsToDisplay', () => {
         it('returns correct metrics for email-only posts', () => {
+            // email-only 且 sent -> 只显示邮件相关指标（showEmailMetrics）
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -241,6 +263,7 @@ describe('post-helpers', () => {
         });
 
         it('returns correct metrics for published-only posts', () => {
+            // 仅发布（无 email） -> 只显示网站相关指标
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -257,6 +280,7 @@ describe('post-helpers', () => {
         });
 
         it('returns correct metrics for published and emailed posts', () => {
+            // 同时发布并成功发邮件 -> 显示邮件与网站指标
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -278,6 +302,7 @@ describe('post-helpers', () => {
         });
 
         it('returns default metrics for draft posts', () => {
+            // 草稿或未定义状态 -> 默认显示网站指标（邮件指标为 false）
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -294,6 +319,7 @@ describe('post-helpers', () => {
         });
 
         it('returns default metrics for scheduled posts', () => {
+            // scheduled 与 draft 类似，使用默认策略
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -310,6 +336,7 @@ describe('post-helpers', () => {
         });
 
         it('returns default metrics for sent posts without email_only flag', () => {
+            // sent 状态但未标记为 email_only -> 仍显示网站指标（兼容历史/未标记场景）
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',
@@ -327,6 +354,7 @@ describe('post-helpers', () => {
         });
 
         it('returns default metrics for undefined status', () => {
+            // 未定义 status -> 使用函数默认返回值（兼容缺省字段）
             const post: Post = {
                 id: '1',
                 url: 'http://example.com/post',

apps/admin-x-settings/src/components/settings/growth/Recommendations.tsx

@@ -8,13 +8,27 @@ import {useBrowseIncomingRecommendations, useBrowseRecommendations} from '@trygh
 import {useReferrerHistory} from '@tryghost/admin-x-framework/api/referrers';
 import {useRouting} from '@tryghost/admin-x-framework/routing';
 
+/**
+ * Recommendations 组件
+ * - 显示 Growth -> Recommendations 分组，包含两个 Tab：
+ *   1) Your recommendations：当前发布方推荐的条目（可分页）
+ *   2) Recommending you：外部推荐你的条目（含来源/统计数据）
+ *
+ * 关键点：
+ * - 使用 useBrowseRecommendations / useBrowseIncomingRecommendations 获取分页数据
+ * - useReferrerHistory 提供统计（用于 IncomingRecommendationList 渲染）
+ * - 提供 "Add recommendation" 跳转到新增 modal 的路由方法
+ * - 支持分页加载（showMore 对象）并在列表组件中传入 isLoading / stats 数据
+ */
 const Recommendations: React.FC<{ keywords: string[] }> = ({keywords}) => {
+    // Setting group 保存/提交控制（TopLevelGroup 提供的上下文）
     const {
         saveState,
         handleSave
     } = useSettingGroup();
 
-    // Fetch "Your recommendations"
+    /* ---------------- Fetch "Your recommendations" ---------------- */
+    // 分页获取当前站点的 recommendations（带 counts 的简要信息）
     const {data: {meta: recommendationsMeta, recommendations} = {}, isLoading: areRecommendationsLoading, hasNextPage, fetchNextPage} = useBrowseRecommendations({
         searchParams: {
             include: 'count.clicks,count.subscribers',
@@ -22,7 +36,7 @@ const Recommendations: React.FC<{ keywords: string[] }> = ({keywords}) => {
             limit: '5'
         },
 
-        // We first load 5, then load 100 at a time (= show all, but without using the dangerous 'all' limit)
+        // 翻页策略：先加载 5，然后以 100 为步长加载全部（避免使用危险的 'all'）
         getNextPageParams: (lastPage, otherParams) => {
             if (!lastPage.meta) {
                 return;
@@ -43,19 +57,21 @@ const Recommendations: React.FC<{ keywords: string[] }> = ({keywords}) => {
         keepPreviousData: true
     });
 
+    // 为 RecommendationList 提供的 showMore 对象（分页展示/加载）
     const showMoreRecommendations: ShowMoreData = {
         hasMore: !!hasNextPage,
         loadMore: fetchNextPage
     };
 
-    // Fetch "Recommending you", including stats
+    /* ---------------- Fetch "Recommending you" ---------------- */
+    // 获取推荐你到其它站点/来源的条目
     const {data: {recommendations: incomingRecommendations, meta: incomingRecommendationsMeta} = {}, isLoading: areIncomingRecommendationsLoading, hasNextPage: hasIncomingRecommendationsNextPage, fetchNextPage: fetchIncomingRecommendationsNextPage} = useBrowseIncomingRecommendations({
         searchParams: {
             limit: '5',
             order: 'created_at desc'
         },
 
-        // We first load 5, then load 100 at a time (= show all, but without using the dangerous 'all' limit)
+        // 同上：分页策略，先 5 后 100
         getNextPageParams: (lastPage, otherParams) => {
             if (!lastPage.meta) {
                 return;
@@ -76,6 +92,7 @@ const Recommendations: React.FC<{ keywords: string[] }> = ({keywords}) => {
         keepPreviousData: true
     });
 
+    // 从 referrers API 获取来源历史/统计，用于在 IncomingRecommendationList 中展示来源信息
     const {data: {stats} = {}, isLoading: areStatsLoading} = useReferrerHistory({});
 
     const showMoreMentions: ShowMoreData = {
@@ -83,9 +100,10 @@ const Recommendations: React.FC<{ keywords: string[] }> = ({keywords}) => {
         loadMore: fetchIncomingRecommendationsNextPage
     };
 
-    // Select "Your recommendations" by default
+    // 默认选中 "Your recommendations" Tab
     const [selectedTab, setSelectedTab] = useState('your-recommendations');
 
+    // Tab 配置：包含计数、加载状态以及传入子组件的 props
     const tabs = [
         {
             id: 'your-recommendations',
@@ -102,38 +120,45 @@ const Recommendations: React.FC<{ keywords: string[] }> = ({keywords}) => {
     ];
 
     const groupDescription = (
+        // 分组说明（显示在 TopLevelGroup 中）
         <>Recommend any publication that your audience will find valuable, and find out when others are recommending you.</>
     );
 
-    // Add a new recommendation
+    /* ---------------- Add new recommendation 操作 ---------------- */
     const {updateRoute} = useRouting();
     const openAddNewRecommendationModal = () => {
+        // 跳转到新增推荐的路由（由路由处理打开 modal/页面）
         updateRoute('recommendations/add');
     };
 
+    // 顶部按钮（大屏显示）
     const buttons = (
         <Button className='mt-[-5px] hidden md:!visible md:!block' color='clear' label='Add recommendation' size='sm' onClick={() => {
             openAddNewRecommendationModal();
         }} />
     );
 
+    /* ---------------- Render ---------------- */
     return (
         <TopLevelGroup
-            beta={true}
+            beta={true}                    // 标记为 beta 功能
-            customButtons={buttons}
+            customButtons={buttons}        // 自定义右上按钮
-            description={groupDescription}
+            description={groupDescription} // 分组描述
-            keywords={keywords}
+            keywords={keywords}            // 搜索关键词（来自父级配置）
-            navid='recommendations'
+            navid='recommendations'       // 导航 id（用于侧边栏高亮/跳转）
-            saveState={saveState}
+            saveState={saveState}          // 保存状态（来自 useSettingGroup）
-            testId='recommendations'
+            testId='recommendations'       // 用于 e2e 测试定位
             title="Recommendations"
-            onSave={handleSave}
+            onSave={handleSave}            // 点击保存时的回调
         >
+            {/* 小屏时显示的添加按钮（在 TopLevelGroup 内部隐藏） */}
             <div className='flex justify-center rounded border border-green px-4 py-2 md:hidden'>
                 <Button color='light-grey' label='Add recommendation' link onClick={() => {
                     openAddNewRecommendationModal();
                 }} />
             </div>
+
+            {/* Tab 视图：切换 Your recommendations / Recommending you */}
             <TabView selectedTab={selectedTab} tabs={tabs} onTabChange={setSelectedTab} />
         </TopLevelGroup>
     );

apps/admin-x-settings/src/components/settings/site/ThemeModal.tsx

@@ -80,11 +80,12 @@ const ThemeToolbar: React.FC<ThemeToolbarProps> = ({
     const onClose = () => {
         updateRoute('/');
     };
-
+    
+    //主题上传预处理函数
     const onThemeUpload = async (file: File) => {
         const themeFileName = file?.name.replace(/\.zip$/, '');
         const existingThemeNames = themes.map(t => t.name);
-        if (isDefaultOrLegacyTheme({name: themeFileName})) {
+        if (isDefaultOrLegacyTheme({name: themeFileName})) {//防止覆盖默认主题
             NiceModal.show(ConfirmationModal, {
                 title: 'Upload failed',
                 cancelLabel: 'Cancel',
@@ -99,7 +100,7 @@ const ThemeToolbar: React.FC<ThemeToolbarProps> = ({
                     confirmModal?.remove();
                 }
             });
-        } else if (existingThemeNames.includes(themeFileName)) {
+        } else if (existingThemeNames.includes(themeFileName)) {//处理主题覆盖确认
             NiceModal.show(ConfirmationModal, {
                 title: 'Overwrite theme',
                 prompt: (
@@ -114,19 +115,17 @@ const ThemeToolbar: React.FC<ThemeToolbarProps> = ({
                 okColor: 'red',
                 onOk: async (confirmModal) => {
                     setUploading(true);
-
                     // this is to avoid the themes array from returning the overwritten theme.
                     // find index of themeFileName in existingThemeNames and remove from the array
                     const index = existingThemeNames.indexOf(themeFileName);
                     themes.splice(index, 1);
-
                     await handleThemeUpload({file, onActivate: onClose});
                     setUploading(false);
                     setCurrentTab('installed');
                     confirmModal?.remove();
                 }
             });
-        } else {
+        } else {//正常的主题
             setCurrentTab('installed');
             handleThemeUpload({file, onActivate: onClose});
         }
@@ -275,7 +274,7 @@ const ThemeToolbar: React.FC<ThemeToolbarProps> = ({
         </div>
     </>);
 };
-
+//负责界面渲染
 const ThemeModalContent: React.FC<ThemeModalContentProps> = ({
     currentTab,
     onSelectTheme,
@@ -448,7 +447,6 @@ const ChangeThemeModal: React.FC<ChangeThemeModalProps> = ({source, themeRef}) =
         const performInstallation = async () => {
             let title = 'Success';
             let prompt = <></>;
-
             // default theme can't be installed, only activated
             if (isDefaultOrLegacyTheme(selectedTheme)) {
                 title = 'Activate theme';
@@ -463,33 +461,26 @@ const ChangeThemeModal: React.FC<ChangeThemeModalProps> = ({source, themeRef}) =
                 } finally {
                     setInstalling(false);
                 }
-
                 if (!data) {
                     return;
                 }
-
                 const newlyInstalledTheme = data.themes[0];
-
                 title = 'Success';
                 prompt = <>
                     <strong>{newlyInstalledTheme.name}</strong> has been successfully installed.
                 </>;
-
                 if (!newlyInstalledTheme.active) {
                     prompt = <>
                         {prompt}{' '}
         Do you want to activate it now?
                     </>;
                 }
-
                 if (newlyInstalledTheme.gscan_errors?.length || newlyInstalledTheme.warnings?.length) {
                     const hasErrors = newlyInstalledTheme.gscan_errors?.length;
-
                     title = `Installed with ${hasErrors ? 'errors' : 'warnings'}`;
                     prompt = <>
         The theme <strong>&quot;{newlyInstalledTheme.name}&quot;</strong> was installed successfully but we detected some {hasErrors ? 'errors' : 'warnings'}.
                     </>;
-
                     if (!newlyInstalledTheme.active) {
                         prompt = <>
                             {prompt}

apps/posts/src/views/Tags/Tags.tsx

@@ -1,39 +1,64 @@
+/**
+ * Admin Tags Page
+ *
+ * Responsibilities:
+ * - Fetch tags using useBrowseTags and the current visibility filter (public/internal)
+ * - Render loading, error, empty and list states
+ * - Wire list pagination (infinite) into TagsList
+ *
+ * 中文说明：
+ * 本页面是后台标签管理的入口页面。页面通过 `useBrowseTags` 调用后台的 tags API 获取数据，
+ * 并根据 URL 查询字符串的 `type` 参数（public/internal）决定请求哪个可见性类型的标签。
+ * 页面负责协调：请求数据、处理加载/错误/空状态、以及把分页/加载更多的能力传递给 `TagsList` 组件。
+ */
 import React from 'react';
 import TagsContent from './components/TagsContent';
 import TagsHeader from './components/TagsHeader';
 import TagsLayout from './components/TagsLayout';
 import TagsList from './components/TagsList';
-import {Button, LoadingIndicator, LucideIcon} from '@tryghost/shade';
+import { Button, LoadingIndicator, LucideIcon } from '@tryghost/shade';
-import {useBrowseTags} from '@tryghost/admin-x-framework/api/tags';
+import { useBrowseTags } from '@tryghost/admin-x-framework/api/tags';
-import {useLocation} from '@tryghost/admin-x-framework';
+import { useLocation } from '@tryghost/admin-x-framework';
 
+/**
+ * 标签管理页面组件
+ * 负责展示、加载和管理标签列表，支持不同可见性类型的标签筛选
+ */
 const Tags: React.FC = () => {
-    const {search} = useLocation();
+    // 获取当前URL的查询参数，用于确定标签筛选类型
+    const { search } = useLocation();
     const qs = new URLSearchParams(search);
+    // 从查询参数中获取标签类型（默认为'public'公开标签）
     const type = qs.get('type') ?? 'public';
 
+    // 调用标签浏览API，根据可见性类型筛选标签
     const {
-        data,
+        data,           // 接口返回的标签数据
-        isError,
+        isError,        // 接口请求是否出错
-        isLoading,
+        isLoading,      // 接口是否正在加载（首次）
-        isFetchingNextPage,
+        isFetchingNextPage, // 是否正在加载下一页数据
-        fetchNextPage,
+        fetchNextPage,  // 加载下一页数据的函数
-        hasNextPage
+        hasNextPage     // 是否有下一页数据
     } = useBrowseTags({
         filter: {
-            visibility: type
+            visibility: type // 筛选条件：按可见性类型
         }
     });
 
     return (
         <TagsLayout>
+            {/* 标签页面头部，显示当前选中的标签类型标签 */}
             <TagsHeader currentTab={type} />
+            
+            {/* 标签内容区域 */}
             <TagsContent>
+                {/* 加载状态：显示加载指示器 */}
                 {isLoading ? (
                     <div className="flex h-full items-center justify-center"> 
                         <LoadingIndicator size="lg" />
                     </div>
                 ) : isError ? (
+                    {/* 错误状态：显示错误信息和重试按钮 */}
                     <div className="mb-16 flex h-full flex-col items-center justify-center">
                         <h2 className="mb-2 text-xl font-medium">
                             Error loading tags
@@ -46,6 +71,7 @@ const Tags: React.FC = () => {
                         </Button>
                     </div>
                 ) : !data?.tags.length ? (
+                    {/* 空状态：当没有标签时显示引导创建标签 */}
                     <div className="mb-16 flex h-full flex-col items-center justify-center gap-8">
                         <LucideIcon.Tags className="-mb-4 size-16 text-muted-foreground" strokeWidth={1} />
                         <h2 className="text-xl font-medium">
@@ -56,12 +82,13 @@ const Tags: React.FC = () => {
                         </Button>
                     </div>
                 ) : (
+                    {/* 列表状态：显示标签列表，支持分页加载 */}
                     <TagsList
-                        fetchNextPage={fetchNextPage}
+                        fetchNextPage={fetchNextPage}       // 加载下一页的回调
-                        hasNextPage={hasNextPage}
+                        hasNextPage={hasNextPage}           // 是否有更多数据
-                        isFetchingNextPage={isFetchingNextPage}
+                        isFetchingNextPage={isFetchingNextPage} // 是否正在加载下一页
-                        items={data?.tags ?? []}
+                        items={data?.tags ?? []}            // 标签数据列表
-                        totalItems={data?.meta?.pagination?.total ?? 0}
+                        totalItems={data?.meta?.pagination?.total ?? 0} // 总标签数量
                     />
                 )}
             </TagsContent>
@@ -69,4 +96,4 @@ const Tags: React.FC = () => {
     );
 };
 
-export default Tags;
+export default Tags;

apps/posts/src/views/Tags/components/TagsHeader.tsx

@@ -1,3 +1,5 @@
+// TagsHeader: top navigation for the tags admin page
+// - shows public/internal tab selection and New tag action
 import React from 'react';
 import {Button, Header, PageMenu, PageMenuItem} from '@tryghost/shade';
 import {Link} from '@tryghost/admin-x-framework';

apps/posts/src/views/Tags/components/TagsList.tsx

@@ -1,3 +1,11 @@
+/**
+ * TagsList component
+ *
+ * Responsibilities:
+ * - Render a virtualized/infinite-scrolling table of tags
++ * - Show placeholders while items are being fetched
++ * - Render each tag row with name, slug, post count and edit action
++ */
 import {
     Button,
     LucideIcon,
@@ -9,16 +17,26 @@ import {
     TableRow,
     formatNumber
 } from '@tryghost/shade';
-import {Tag} from '@tryghost/admin-x-framework/api/tags';
+import { Tag } from '@tryghost/admin-x-framework/api/tags';
-import {forwardRef, useRef} from 'react';
+import { forwardRef, useRef } from 'react';
-import {useInfiniteVirtualScroll} from './VirtualTable/useInfiniteVirtualScroll';
+import { useInfiniteVirtualScroll } from './VirtualTable/useInfiniteVirtualScroll';
 
-const SpacerRow = ({height}: { height: number }) => (
+/**
+ * 用于在虚拟滚动中填充空白空间的间隔行组件
+ * @param {Object} props - 组件属性
+ * @param {number} props.height - 间隔行高度
+ * @returns {JSX.Element} 间隔行元素
+ */
+const SpacerRow = ({ height }: { height: number }) => (
     <tr className="flex lg:table-row">
-        <td className="flex lg:table-cell" style={{height}} />
+        <td className="flex lg:table-cell" style={{ height }} />
     </tr>
 );
 
+/**
+ * 加载状态下的占位行组件（骨架屏）
+ * TODO: 升级到React 19后可移除forwardRef
+ */
 // TODO: Remove forwardRef once we have upgraded to React 19
 const PlaceholderRow = forwardRef<HTMLTableRowElement>(function PlaceholderRow(
     props,
@@ -37,6 +55,16 @@ const PlaceholderRow = forwardRef<HTMLTableRowElement>(function PlaceholderRow(
     );
 });
 
+/**
+ * 标签列表组件，支持虚拟滚动和无限加载
+ * @param {Object} props - 组件属性
+ * @param {Tag[]} props.items - 标签数据数组
+ * @param {number} props.totalItems - 标签总数量
+ * @param {boolean} [props.hasNextPage] - 是否有下一页数据
+ * @param {boolean} [props.isFetchingNextPage] - 是否正在加载下一页
+ * @param {() => void} props.fetchNextPage - 加载下一页数据的函数
+ * @returns {JSX.Element} 标签列表组件
+ */
 function TagsList({
     items,
     totalItems,
@@ -50,8 +78,11 @@ function TagsList({
     isFetchingNextPage?: boolean;
     fetchNextPage: () => void;
 }) {
+    // 父容器引用，用于计算虚拟滚动区域
     const parentRef = useRef<HTMLDivElement>(null);
-    const {visibleItems, spaceBefore, spaceAfter} = useInfiniteVirtualScroll({
+    
+    // 调用虚拟滚动钩子，获取可见项和间隔高度
+    const { visibleItems, spaceBefore, spaceAfter } = useInfiniteVirtualScroll({
         items,
         totalItems,
         hasNextPage,
@@ -63,6 +94,7 @@ function TagsList({
     return (
         <div ref={parentRef}>
             <Table className="flex table-fixed flex-col lg:table">
+                {/* 桌面端表头 */}
                 <TableHeader className="hidden lg:!visible lg:!table-header-group">
                     <TableRow>
                         <TableHead className="w-auto px-4">
@@ -75,9 +107,15 @@ function TagsList({
                         <TableHead className="w-20 px-4"></TableHead>
                     </TableRow>
                 </TableHeader>
+                
+                {/* 表格内容区域 */}
                 <TableBody className="flex flex-col lg:table-row-group">
+                    {/* 顶部空白间隔（用于虚拟滚动定位） */}
                     <SpacerRow height={spaceBefore} />
-                    {visibleItems.map(({key, virtualItem, item, props}) => {
+                    
+                    {/* 渲染可见的标签行 */}
+                    {visibleItems.map(({ key, virtualItem, item, props }) => {
+                        // 判断是否需要渲染占位行（数据尚未加载时）
                         const shouldRenderPlaceholder =
                             virtualItem.index > items.length - 1;
 
@@ -85,12 +123,14 @@ function TagsList({
                             return <PlaceholderRow key={key} {...props} />;
                         }
 
+                        // 渲染实际标签行（响应式布局）
                         return (
                             <TableRow
                                 key={key}
                                 {...props}
                                 className="relative grid w-full grid-cols-[1fr_5rem] items-center gap-x-4 p-2 md:grid-cols-[1fr_auto_5rem] lg:table-row lg:p-0"
                             >
+                                {/* 标签名称和描述（移动端占满一行，桌面端占多列） */}
                                 <TableCell className="static col-start-1 col-end-1 row-start-1 row-end-1 flex min-w-0 flex-col p-0 lg:table-cell lg:w-1/2 lg:p-4 xl:w-3/5">
                                     <a
                                         className="block truncate pb-1 text-lg font-medium before:absolute before:inset-0 before:z-10"
@@ -102,11 +142,15 @@ function TagsList({
                                         {item.description}
                                     </span>
                                 </TableCell>
+                                
+                                {/* 标签Slug（移动端第二行） */}
                                 <TableCell className="col-start-1 col-end-1 row-start-2 row-end-2 flex p-0 lg:table-cell lg:p-4">
                                     <span className="block truncate">
                                         {item.slug}
                                     </span>
                                 </TableCell>
+                                
+                                {/* 关联文章数量（移动端第三行，桌面端单独列） */}
                                 <TableCell className="col-start-1 col-end-1 row-start-3 row-end-3 flex p-0 md:col-start-2 md:col-end-2 md:row-start-1 md:row-end-3 lg:table-cell lg:p-4">
                                     {item.count?.posts ? (
                                         <a
@@ -121,6 +165,8 @@ function TagsList({
                                         </span>
                                     )}
                                 </TableCell>
+                                
+                                {/* 编辑按钮（移动端右上角，桌面端最后一列） */}
                                 <TableCell className="col-start-2 col-end-2 row-start-1 row-end-3 p-0 md:col-start-3 md:col-end-3 lg:table-cell lg:p-4">
                                     <Button
                                         aria-hidden="true"
@@ -135,6 +181,8 @@ function TagsList({
                             </TableRow>
                         );
                     })}
+                    
+                    {/* 底部空白间隔（用于虚拟滚动定位） */}
                     <SpacerRow height={spaceAfter} />
                 </TableBody>
             </Table>
@@ -142,4 +190,4 @@ function TagsList({
     );
 }
 
-export default TagsList;
+export default TagsList;

apps/sodo-search/src/App.js

@@ -5,54 +5,74 @@ import PopupModal from './components/PopupModal';
 import SearchIndex from './search-index.js';
 import i18nLib from '@tryghost/i18n';
 
+/**
+ * 搜索应用的主组件 - 负责管理整个搜索功能的布局和状态
+ */
 export default class App extends React.Component {
     constructor(props) {
         super(props);
 
+        // ==================== 国际化设置 ====================
+        // 设置语言环境，默认为英语
         const i18nLanguage = this.props.locale || 'en';
         const i18n = i18nLib(i18nLanguage, 'search');
-        const dir = i18n.dir() || 'ltr';
+        const dir = i18n.dir() || 'ltr'; // 文字方向（左到右或右到左）
 
+        // ==================== 搜索索引初始化 ====================
+        // 创建搜索索引实例，用于处理搜索逻辑
         const searchIndex = new SearchIndex({
-            adminUrl: props.adminUrl,
+            adminUrl: props.adminUrl,    // 管理后台URL
-            apiKey: props.apiKey,
+            apiKey: props.apiKey,        // API密钥
-            dir: dir
+            dir: dir                     // 文字方向
         });
 
+        // ==================== 组件状态初始化 ====================
         this.state = {
-            searchIndex,
+            searchIndex,      // 搜索索引实例
-            showPopup: false,
+            showPopup: false, // 是否显示搜索弹窗
-            indexStarted: false,
+            indexStarted: false, // 是否开始构建索引
-            indexComplete: false,
+            indexComplete: false, // 索引构建是否完成
-            t: i18n.t,
+            t: i18n.t,        // 国际化翻译函数
-            dir: dir,
+            dir: dir,         // 文字方向
-            scrollbarWidth: 0
+            scrollbarWidth: 0 // 滚动条宽度（用于防止布局偏移）
         };
 
+        // 创建输入框的引用，用于直接操作DOM元素
         this.inputRef = React.createRef();
     }
 
+    /**
+     * 组件挂载后立即执行
+     */
     componentDidMount() {
+        // 计算并保存滚动条宽度
         const scrollbarWidth = this.getScrollbarWidth();
         this.setState({scrollbarWidth});
 
+        // 初始化搜索设置
         this.initSetup();
     }
 
+    /**
+     * 组件更新时执行，主要用于处理弹窗显示/隐藏时的滚动条逻辑
+     */
     componentDidUpdate(_prevProps, prevState) {
+        // ==================== 弹窗显示状态变化处理 ====================
         if (prevState.showPopup !== this.state.showPopup) {
-            /** Remove background scroll when popup is opened */
+            /** 当弹窗打开时移除背景滚动，防止页面抖动 */
             try {
                 if (this.state.showPopup) {
-                    /** When modal is opened, store current overflow and set as hidden */
+                    /** 当弹窗打开时，保存当前的overflow状态并设置为hidden */
                     this.bodyScroll = window.document?.body?.style?.overflow;
                     this.bodyMargin = window.getComputedStyle(document.body).getPropertyValue('margin-right');
                     window.document.body.style.overflow = 'hidden';
+                    
+                    // 如果有滚动条且内容高度超过视口，调整右边距防止布局偏移
                     if (this.state.scrollbarWidth && document.body.scrollHeight > window.innerHeight) {
                         window.document.body.style.marginRight = `calc(${this.bodyMargin} + ${this.state.scrollbarWidth}px)`;
                     }
                 } else {
-                    /** When the modal is hidden, reset overflow property for body */
+                    /** 当弹窗隐藏时，恢复body的overflow属性 */
                     window.document.body.style.overflow = this.bodyScroll || '';
                     if (!this.bodyMargin || this.bodyMargin === '0px') {
                         window.document.body.style.marginRight = '';
@@ -61,74 +81,93 @@ export default class App extends React.Component {
                     }
                 }
             } catch (e) {
-                /** Ignore any errors for scroll handling */
+                /** 忽略滚动处理中的任何错误 */
             }
         }
 
+        // ==================== 弹窗关闭时清空搜索值 ====================
         if (this.state.showPopup !== prevState?.showPopup && !this.state.showPopup) {
             this.setState({
                 searchValue: ''
             });
         }
 
+        // ==================== 弹窗打开时初始化搜索索引 ====================
         if (this.state.showPopup && !this.state.indexStarted) {
             this.setupSearchIndex();
         }
     }
 
+    /**
+     * 设置搜索索引 - 异步初始化搜索功能
+     */
     async setupSearchIndex() {
         this.setState({
-            indexStarted: true
+            indexStarted: true  // 标记索引构建开始
         });
-        await this.state.searchIndex.init();
+        await this.state.searchIndex.init(); // 等待索引初始化完成
         this.setState({
-            indexComplete: true
+            indexComplete: true // 标记索引构建完成
         });
     }
 
+    /**
+     * 组件卸载前的清理工作
+     */
     componentWillUnmount() {
-        /**Clear timeouts and event listeners on unmount */
+        /** 清除超时和事件监听器 */
         window.removeEventListener('hashchange', this.hashHandler, false);
         window.removeEventListener('keydown', this.handleKeyDown, false);
     }
 
+    /**
+     * 初始化搜索设置
+     */
     initSetup() {
-        // Listen to preview mode changes
+        // 监听预览模式变化
         this.handleSearchUrl();
         this.addKeyboardShortcuts();
         this.setupCustomTriggerButton();
+        
+        // 哈希变化处理器（用于URL路由）
         this.hashHandler = () => {
             this.handleSearchUrl();
         };
         window.addEventListener('hashchange', this.hashHandler, false);
     }
 
-    // User for adding trailing margin to prevent layout shift when popup appears
+    /**
+     * 计算滚动条宽度 - 用于防止弹窗出现时的布局偏移
+     */
     getScrollbarWidth() {
-        // Create a temporary div
+        // 创建临时div元素
         const div = document.createElement('div');
         div.style.visibility = 'hidden';
-        div.style.overflow = 'scroll'; // forcing scrollbar to appear
+        div.style.overflow = 'scroll'; // 强制显示滚动条
         document.body.appendChild(div);
 
-        // Calculate the width difference
+        // 计算宽度差异（这就是滚动条的宽度）
         const scrollbarWidth = div.offsetWidth - div.clientWidth;
 
-        // Clean up
+        // 清理临时元素
         document.body.removeChild(div);
 
         return scrollbarWidth;
     }
 
-    /** Setup custom trigger buttons handling on page */
+    /**
+     * 设置页面上的自定义触发按钮处理
+     */
     setupCustomTriggerButton() {
-        // Handler for custom buttons
+        // 自定义按钮的点击处理器
         this.clickHandler = (event) => {
             event.preventDefault();
             this.setState({
-                showPopup: true
+                showPopup: true  // 显示搜索弹窗
             });
 
+            // ==================== 焦点管理技巧 ====================
+            // 创建临时输入元素来解决焦点问题
             const tmpElement = document.createElement('input');
             tmpElement.style.opacity = '0';
             tmpElement.style.position = 'fixed';
@@ -136,12 +175,14 @@ export default class App extends React.Component {
             document.body.appendChild(tmpElement);
             tmpElement.focus();
 
+            // 延迟后将焦点转移到真正的搜索输入框
             setTimeout(() => {
                 this.inputRef.current.focus();
                 document.body.removeChild(tmpElement);
             }, 150);
         };
 
+        // 获取所有自定义触发按钮并添加点击事件
         this.customTriggerButtons = this.getCustomTriggerButtons();
         this.customTriggerButtons.forEach((customTriggerButton) => {
             customTriggerButton.removeEventListener('click', this.clickHandler);
@@ -149,27 +190,39 @@ export default class App extends React.Component {
         });
     }
 
+    /**
+     * 获取页面上的自定义触发按钮
+     */
     getCustomTriggerButtons() {
-        const customTriggerSelector = '[data-ghost-search]';
+        const customTriggerSelector = '[data-ghost-search]'; // 通过data属性选择按钮
         return document.querySelectorAll(customTriggerSelector) || [];
     }
 
+    /**
+     * 处理搜索URL - 当URL哈希为/#search时自动打开搜索弹窗
+     */
     handleSearchUrl() {
         const [path] = window.location.hash.substr(1).split('?');
         if (path === '/search' || path === '/search/') {
             this.setState({
                 showPopup: true
             });
+            // 替换历史状态，移除哈希部分
             window.history.replaceState('', document.title, window.location.pathname);
         }
     }
 
+    /**
+     * 添加快捷键支持 - Cmd+K 打开搜索
+     */
     addKeyboardShortcuts() {
         const customTriggerButtons = this.getCustomTriggerButtons();
         if (!customTriggerButtons?.length) {
             return;
         }
+        
         this.handleKeyDown = (e) => {
+            // 检测 Cmd+K (Mac) 或 Ctrl+K (Windows)
             if (e.key === 'k' && e.metaKey) {
                 this.setState({
                     showPopup: true
@@ -182,19 +235,26 @@ export default class App extends React.Component {
         document.addEventListener('keydown', this.handleKeyDown);
     }
 
+    /**
+     * 渲染组件 - 这里是整个搜索应用的布局入口
+     */
     render() {
         return (
+            /**
+             * 使用Context API提供全局状态给所有子组件
+             * 这是React中管理全局状态的常用模式
+             */
             <AppContext.Provider value={{
-                page: 'search',
+                page: 'search',                    // 当前页面标识
-                showPopup: this.state.showPopup,
+                showPopup: this.state.showPopup,   // 弹窗显示状态
-                adminUrl: this.props.adminUrl,
+                adminUrl: this.props.adminUrl,     // 管理后台URL
-                stylesUrl: this.props.stylesUrl,
+                stylesUrl: this.props.stylesUrl,   // 样式文件URL
-                searchIndex: this.state.searchIndex,
+                searchIndex: this.state.searchIndex, // 搜索索引实例
-                indexComplete: this.state.indexComplete,
+                indexComplete: this.state.indexComplete, // 索引完成状态
-                searchValue: this.state.searchValue,
+                searchValue: this.state.searchValue, // 搜索关键词
-                inputRef: this.inputRef,
+                inputRef: this.inputRef,           // 输入框引用
-                onAction: () => {},
+                onAction: () => {},                // 动作处理器
-                dispatch: (action, data) => {
+                dispatch: (action, data) => {      // 状态更新函数
                     if (action === 'update') {
                         this.setState({
                             ...this.state,
@@ -202,11 +262,12 @@ export default class App extends React.Component {
                         });
                     }
                 },
-                t: this.state.t,
+                t: this.state.t,                   // 翻译函数
-                dir: this.state.dir
+                dir: this.state.dir                // 文字方向
             }}>
+                {/* 渲染搜索弹窗组件 - 这是主要的UI组件 */}
                 <PopupModal />
             </AppContext.Provider>
         );
     }
-}
+}

apps/sodo-search/src/AppContext.js

@@ -1,3 +1,11 @@
+/*
+ * 全局应用上下文（AppContext）
+ *
+ * 中文说明：
+ * - 为 sodo-search 提供共享状态，包括已加载的 posts/authors/tags 索引、搜索关键字、
+ *   以及 dispatch 方法用于触发 UI 状态改变（比如打开/关闭弹窗）。
+ * - tags 列表会在 SearchIndex 初始化时被填充并用于弹窗内的 tag 搜索结果展示。
+ */
 // Ref: https://reactjs.org/docs/context.html
 import React from 'react';
 

apps/sodo-search/src/components/PopupModal.js

@@ -1,3 +1,12 @@
+/*
+ * 搜索弹窗（PopupModal）组件
+ *
+ * 中文说明：
+ * - 该文件实现站内搜索弹窗 UI，用于搜索 posts、tags、authors 等内容并展示结果。
+ * - 当用户输入关键字时会使用内部的 SearchIndex（由 `apps/sodo-search/src/search-index.js` 提供）
+ *   来检索本地索引（在初始化时会向 Ghost 内容 API 拉取 posts/authors/tags 并建立索引）。
+ * - 在结果中，tags 的条目会被渲染为可点击项（`TagListItem`），点击会跳转到 tag.url。
+ */
 import Frame from './Frame';
 import AppContext from '../AppContext';
 import {ReactComponent as SearchIcon} from '../icons/search.svg';

apps/sodo-search/src/search-index.js

@@ -1,3 +1,12 @@
+/*
+ * 搜索索引（SearchIndex）
+ *
+ * 中文说明：
+ * - 使用 FlexSearch 在浏览器端建立 posts、authors、tags 的索引，以便快速检索。
+ * - 在初始化时会向 Ghost 内容 API 拉取 posts/authors/tags（使用 admin/content search-index endpoints），
+ *   并把返回的数据加入对应的索引文档（postsIndex/authorsIndex/tagsIndex）。
+ * - tags 的索引托管在 `tagsIndex`，其文档字段只索引 `name`，并且使用自定义编码器以支持 CJK 分词。
+ */
 import Flexsearch, {Charset} from 'flexsearch';
 
 const cjkEncoderPresetCodepoint = {

apps/stats/src/hooks/useGrowthStats.ts

@@ -4,10 +4,40 @@ import {formatNumber, formatPercentage, formatQueryDate, getRangeDates} from '@t
 import {getSymbol} from '@tryghost/admin-x-framework';
 import {useMemo} from 'react';
 
-// Type for direction values
+/**
+ * DiffDirection
+ * - 用于表示数值变化方向：上升（up）、下降（down）、相同（same）
+ */
 export type DiffDirection = 'up' | 'down' | 'same';
 
-// Calculate totals from member data
+/**
+ * calculateTotals
+ * - 从 memberData 和 mrrData 计算摘要指标（总会员数、免费/付费会员、MRR）以及百分比变化与方向。
+ * - 参数：
+ *   - memberData: 按日期的会员状态数组（每项包含 free/paid/comped 等）
+ *   - mrrData: 按日期的 MRR 历史数组（每项包含 date/mrr/currency）
+ *   - dateFrom: 选择范围的起始日期（YYYY-MM-DD 格式）
+ *   - memberCountTotals: 可选的当前汇总 totals（如来自 meta，用于优先显示最新汇总）
+ *
+ * 逻辑要点：
+ * - 若没有数据，返回一组默认的 0/同向(same) 值，避免上层处理空值判断。
+ * - totalMembers 使用 memberCountTotals（如果可用）或 memberData 最后一个来计算。
+ * - percentChanges: 只有当时间序列包含 >1 个点时才计算与第一个点的百分比变化。
+ * - 对 MRR 的变化判断有特殊策略：
+ *   - 识别 "from beginning" 范围（例如年初开始或更早），在该场景下若首点不在范围起始，默认首点为 0（YTD 语义）。
+ *   - 对于最近范围（非 from-beginning），若缺少起点，使用范围前最近的 MRR 值（视为平滑承接）。
+ *   - 若首点为 0 且当前 MRR>0，按业务逻辑显示 100% 增长。
+ *
+ * 返回值（示例）：
+ * {
+ *   totalMembers: number,
+ *   freeMembers: number,
+ *   paidMembers: number,
+ *   mrr: number,
+ *   percentChanges: { total, free, paid, mrr },
+ *   directions: { total, free, paid, mrr }
+ * }
+ */
 const calculateTotals = (memberData: MemberStatusItem[], mrrData: MrrHistoryItem[], dateFrom: string, memberCountTotals?: {paid: number; free: number; comped: number}) => {
     if (!memberData.length) {
         return {
@@ -30,18 +60,18 @@ const calculateTotals = (memberData: MemberStatusItem[], mrrData: MrrHistoryItem
         };
     }
 
-    // Use current totals from API meta if available (like Ember), otherwise use latest time series data
+    // 使用后端 meta 的 totals（如果存在），否则从时间序列取最后一个点作为当前值
     const currentTotals = memberCountTotals || memberData[memberData.length - 1];
     const latest = memberData.length > 0 ? memberData[memberData.length - 1] : {free: 0, paid: 0, comped: 0};
 
     const latestMrr = mrrData.length > 0 ? mrrData[mrrData.length - 1] : {mrr: 0};
 
-    // Calculate total members using current totals (like Ember dashboard)
+    // 计算总会员数（免费 + 付费 + comped）
     const totalMembers = currentTotals.free + currentTotals.paid + currentTotals.comped;
 
     const totalMrr = latestMrr.mrr;
 
-    // Calculate percentage changes if we have enough data
+    // 默认百分比与方向
     const percentChanges = {
         total: '0%',
         free: '0%',
@@ -56,8 +86,8 @@ const calculateTotals = (memberData: MemberStatusItem[], mrrData: MrrHistoryItem
         mrr: 'same' as DiffDirection
     };
 
+    // 只有在成员时间序列存在 >=2 个点时，才计算与第一天的百分比变化
     if (memberData.length > 1) {
-        // Get first day in range
         const first = memberData[0];
         const firstTotal = first.free + first.paid + first.comped;
 
@@ -83,43 +113,43 @@ const calculateTotals = (memberData: MemberStatusItem[], mrrData: MrrHistoryItem
         }
     }
 
+    // MRR 的百分比变化需要更复杂的边界处理，考虑到 YTD 或缺失数据点情况
     if (mrrData.length > 1) {
-        // Find the first ACTUAL data point within the selected date range (not synthetic boundary points)
+        // 选择范围内第一个真正的点（实际数据点，而非人为添加的边界点）
         const actualStartDate = moment(dateFrom).format('YYYY-MM-DD');
         const firstActualPoint = mrrData.find(point => moment(point.date).isSameOrAfter(actualStartDate));
 
-        // Check if this is a "from beginning" range (like YTD) vs a recent range
+        // 判断是否为从“起始/年初”开始的范围（例如 YTD），这会将缺失起点视作 0
         const isFromBeginningRange = moment(dateFrom).isSame(moment().startOf('year'), 'day') ||
                                     moment(dateFrom).year() < moment().year();
 
         let firstMrr = 0;
 
         if (firstActualPoint) {
-            // Check if the first actual point is exactly at the start date
             if (moment(firstActualPoint.date).isSame(actualStartDate, 'day')) {
+                // 起点恰好落在范围开始
                 firstMrr = firstActualPoint.mrr;
             } else {
-                // First actual point is later than start date
+                // 起点在范围之后
                 if (isFromBeginningRange) {
-                    // For YTD/beginning ranges, assume started from 0
+                    // 对于 YTD 等从年初/更早开始的范围，假设从 0 开始增长
                     firstMrr = 0;
                 } else {
-                    // For recent ranges, use the most recent MRR before the range
+                    // 对于近期范围，采用范围外最近的 MRR 值（平滑承接）
-                    // This should be the same as current MRR (flat line scenario)
                     firstMrr = totalMrr;
                 }
             }
         } else if (isFromBeginningRange) {
-            // No data points in range, and it's a from-beginning range
+            // 范围内无数据且属于从起始范围 -> 起点为 0
             firstMrr = 0;
         } else {
-            // No data points in recent range, carry forward current MRR
+            // 范围内无数据且为近期范围 -> 使用当前 MRR（没有变化）
             firstMrr = totalMrr;
         }
 
-        if (firstMrr >= 0) { // Allow 0 as a valid starting point
+        if (firstMrr >= 0) { // 允许 0 作为有效起点
             const mrrChange = firstMrr === 0
-                ? (totalMrr > 0 ? 100 : 0) // If starting from 0, any positive value is 100% increase
+                ? (totalMrr > 0 ? 100 : 0) // 起点0且有增长 -> 视作 100% 增长
                 : ((totalMrr - firstMrr) / firstMrr) * 100;
 
             percentChanges.mrr = formatPercentage(mrrChange / 100);
@@ -137,15 +167,25 @@ const calculateTotals = (memberData: MemberStatusItem[], mrrData: MrrHistoryItem
     };
 };
 
-// Format chart data
+/**
+ * formatChartData
+ * - 将 memberData 与 mrrData 合并成用于曲线图的日期序列：
+ *   - 合并所有出现过的日期（member 与 mrr 的并集）
+ *   - 对缺失日期使用最近已知值向前填充（last-known 值），以保证图表线连续
+ *   - 输出每个日期的 value(总会员)、free、paid、comped、mrr、formattedValue、label 等字段
+ *
+ * 说明：
+ * - 输入数据会先按日期升序排序，返回的数组也按升序排列（便于前端直接用于图表）
+ */
 const formatChartData = (memberData: MemberStatusItem[], mrrData: MrrHistoryItem[]) => {
-    // Ensure data is sorted by date
+    // 确保时间序列按日期升序
     const sortedMemberData = [...memberData].sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
     const sortedMrrData = [...mrrData].sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
 
     const memberDates = sortedMemberData.map(item => item.date);
     const mrrDates = sortedMrrData.map(item => item.date);
 
+    // 合并去重后的所有日期并按时间排序
     const allDates = [...new Set([...memberDates, ...mrrDates])].sort((a, b) => new Date(a).getTime() - new Date(b).getTime());
 
     let lastMemberItem: MemberStatusItem | null = null;
@@ -155,6 +195,7 @@ const formatChartData = (memberData: MemberStatusItem[], mrrData: MrrHistoryItem
     const mrrMap = new Map(sortedMrrData.map(item => [item.date, item]));
 
     return allDates.map((date) => {
+        // 若该日期存在 member/mrr 项，则更新 last-known
         const currentMemberItem = memberMap.get(date);
         if (currentMemberItem) {
             lastMemberItem = currentMemberItem;
@@ -165,6 +206,7 @@ const formatChartData = (memberData: MemberStatusItem[], mrrData: MrrHistoryItem
             lastMrrItem = currentMrrItem;
         }
 
+        // 使用最近已知的值向前填充缺失数据
         const free = lastMemberItem?.free ?? 0;
         const paid = lastMemberItem?.paid ?? 0;
         const comped = lastMemberItem?.comped ?? 0;
@@ -184,18 +226,40 @@ const formatChartData = (memberData: MemberStatusItem[], mrrData: MrrHistoryItem
             paid_subscribed: paidSubscribed,
             paid_canceled: paidCanceled,
             formattedValue: formatNumber(value),
-            label: 'Total members' // Consider if label needs update based on data type?
+            label: 'Total members' // 注意：如需根据视图切换 label，可在上层处理
         };
     });
 };
 
+/**
+ * useGrowthStats(range)
+ * - 入口 Hook：接受一个 range（天数，例如 1, 7, 30 等）
+ * - 返回：
+ *   - isLoading: 是否仍在加载底层 API
+ *   - memberData: 处理后的 member 时间序列（对单日范围做了特殊处理保证至少 2 个点）
+ *   - mrrData: 选择货币后的 MRR 时间序列（已填补起/终点）
+ *   - dateFrom / endDate: 查询使用的范围日期字符串
+ *   - totals: calculateTotals 的结果（汇总数字 + 百分比 + 方向）
+ *   - chartData: formatChartData 的结果，直接可用于图表
+ *   - subscriptionData: 合并后的订阅事件时间序列（signups/cancellations）
+ *   - selectedCurrency / currencySymbol: 货币选择与符号
+ *
+ * 关键实现细节：
+ * - 使用 getRangeDates(range) 获得时区感知的 startDate / endDate
+ * - 对于 range===1（今日）：
+ *   - member 数据请求需包含昨天的数据（以便构造两点：昨日->今日），从而在图表上显示变化斜率
+ * - mrrData 的处理：
+ *   - 从 meta.totals 选择 MRR 最大的 currency，然后只保留该币种的数据
+ *   - 确保时间序列在 dateFrom 与 dateTo 有边界点：若缺失则从范围外取最近值或复制最后值到范围结束
+ * - subscriptionData：
+ *   - 合并按日期的 signups/cancellations（reduce 合并），并过滤到请求范围内
+ */
 export const useGrowthStats = (range: number) => {
-    // Calculate date range using Shade's timezone-aware getRangeDates
+    // 使用 Shade 提供的时区感知工具计算起止日期
     const {startDate, endDate} = useMemo(() => getRangeDates(range), [range]);
     const dateFrom = formatQueryDate(startDate);
 
-    // Fetch member count history from API
+    // memberData 请求：对于单日需要从昨天开始以便生成两个点
-    // For single day ranges, we need at least 2 days of data to show a proper delta
     const memberDataStartDate = range === 1 ? moment(dateFrom).subtract(1, 'day').format('YYYY-MM-DD') : dateFrom;
     
     const {data: memberCountResponse, isLoading: isMemberCountLoading} = useMemberCountHistory({
@@ -204,35 +268,35 @@ export const useGrowthStats = (range: number) => {
         }
     });
 
+    // MRR 历史（全币种）——后续会基于 meta 选择最佳币种
     const {data: mrrHistoryResponse, isLoading: isMrrLoading} = useMrrHistory();
 
-    // Fetch subscription stats for real subscription events
+    // 订阅事件（用于真实的 signups / cancellations）
     const {data: subscriptionStatsResponse, isLoading: isSubscriptionLoading} = useSubscriptionStats();
 
-    // Process member data with stable reference
+    /**
+     * memberData memo：
+     * - 兼容后端返回 stats 在 response.stats 或直接返回数组的情况
+     * - 对 range===1 执行特殊转换：把昨天的 EOD 视作 startOfToday，今天的 EOD 视作 startOfTomorrow，
+     *   从而在图表上形成两个点（便于展示今日变化）
+     */
     const memberData = useMemo(() => {
         let rawData: MemberStatusItem[] = [];
         
-        // Check the structure of the response and extract data
         if (memberCountResponse?.stats) {
             rawData = memberCountResponse.stats;
         } else if (Array.isArray(memberCountResponse)) {
-            // If response is directly an array
             rawData = memberCountResponse;
         }
         
-        // For single day (Today), ensure we have two data points for a proper line
         if (range === 1 && rawData.length >= 2) {
-            // We should have yesterday's data and today's data
+            const yesterdayData = rawData[rawData.length - 2]; // 昨日 EOD
-            const yesterdayData = rawData[rawData.length - 2]; // Yesterday's EOD counts
+            const todayData = rawData[rawData.length - 1]; // 今日 EOD
-            const todayData = rawData[rawData.length - 1]; // Today's EOD counts
             
-            const startOfToday = moment(dateFrom).format('YYYY-MM-DD'); // 6/26
+            const startOfToday = moment(dateFrom).format('YYYY-MM-DD');
-            const startOfTomorrow = moment(dateFrom).add(1, 'day').format('YYYY-MM-DD'); // 6/27
+            const startOfTomorrow = moment(dateFrom).add(1, 'day').format('YYYY-MM-DD');
             
-            // Create two data points:
+            // 构造两个点：昨天的数据点标记为 startOfToday，今天的数据点标记为 startOfTomorrow
-            // 1. Yesterday's EOD count attributed to start of today (6/26)
-            // 2. Today's EOD count attributed to start of tomorrow (6/27)
             const startPoint = {
                 ...yesterdayData,
                 date: startOfToday
@@ -249,13 +313,21 @@ export const useGrowthStats = (range: number) => {
         return rawData;
     }, [memberCountResponse, range, dateFrom]);
 
+    /**
+     * mrrData memo：
+     * - 选择 meta.totals 中总量最大的 currency，过滤出该 currency 的数据
+     * - 过滤到 dateFrom 之后的点，并确保在范围开始（dateFrom）和结束（endDate/endOfDay）有边界点：
+     *   - 若起点缺失：尝试从范围外取最近的点并把它的值设在 dateFrom
+     *   - 若终点缺失：把最近的值复制到范围结束，保证图表不会在末尾断开
+     * - 对单日 range 使用 end-of-today 的处理以保证时间一致性
+     */
     const {mrrData, selectedCurrency} = useMemo(() => {
         const dateFromMoment = moment(dateFrom);
-        // For "Today" range (1 day), use end of today to match visitor data behavior
+        // 单日范围时，使用当日结束时间作为检查边界
         const dateToMoment = range === 1 ? moment().endOf('day') : moment().startOf('day');
 
         if (mrrHistoryResponse?.stats && mrrHistoryResponse?.meta?.totals) {
-            // Select the currency with the highest total MRR value (same logic as Dashboard)
+            // 从 meta.totals 中选取 mrr 最大的 currency（与 Dashboard 一致的选择逻辑）
             const totals = mrrHistoryResponse.meta.totals;
             let currentMax = totals[0];
             if (!currentMax) {
@@ -270,17 +342,19 @@ export const useGrowthStats = (range: number) => {
 
             const useCurrency = currentMax.currency;
 
-            // Filter MRR data to only include the selected currency
+            // 筛选出所选货币的数据
             const currencyFilteredData = mrrHistoryResponse.stats.filter(d => d.currency === useCurrency);
 
+            // 只保留在 dateFrom 及之后的点（范围内部数据）
             const filteredData = currencyFilteredData.filter((item) => {
                 return moment(item.date).isSameOrAfter(dateFromMoment);
             });
 
+            // allData 用于查找范围外最近的点（向前回填）
             const allData = [...currencyFilteredData].sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
             const result = [...filteredData];
 
-            // Always ensure we have a data point at the start of the range
+            // 确保起点存在：若缺失则尝试取范围外最近的点并把它插入为 dateFrom
             const hasStartPoint = result.some(item => moment(item.date).isSame(dateFromMoment, 'day'));
             if (!hasStartPoint) {
                 const mostRecentBeforeRange = allData.find((item) => {
@@ -295,11 +369,10 @@ export const useGrowthStats = (range: number) => {
                 }
             }
 
-            // Always ensure we have a data point at the end of the range
+            // 确保终点存在：若缺失则把当前 result 中最近的值复制为结束点
             const endDateToCheck = range === 1 ? moment().startOf('day') : dateToMoment;
             const hasEndPoint = result.some(item => moment(item.date).isSame(endDateToCheck, 'day'));
             if (!hasEndPoint && result.length > 0) {
-                // Use the most recent value in our result set
                 const sortedResult = [...result].sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
                 const mostRecentValue = sortedResult[0];
 
@@ -309,6 +382,7 @@ export const useGrowthStats = (range: number) => {
                 });
             }
 
+            // 最终按时间升序返回
             const finalResult = result.sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
 
             return {mrrData: finalResult, selectedCurrency: useCurrency};
@@ -316,26 +390,32 @@ export const useGrowthStats = (range: number) => {
         return {mrrData: [], selectedCurrency: 'usd'};
     }, [mrrHistoryResponse, dateFrom, range]);
 
-    // Calculate totals
+    // totalsData：计算摘要数字（使用 calculateTotals）
     const totalsData = useMemo(() => calculateTotals(memberData, mrrData, dateFrom, memberCountResponse?.meta?.totals), [memberData, mrrData, dateFrom, memberCountResponse?.meta?.totals]);
 
-    // Format chart data
+    // chartData：将时间序列格式化为图表友好的连续数据（formatChartData）
     const chartData = useMemo(() => formatChartData(memberData, mrrData), [memberData, mrrData]);
 
-    // Get currency symbol
+    // 货币符号（用于显示 MRR 时的单位）
     const currencySymbol = useMemo(() => {
         return getSymbol(selectedCurrency);
     }, [selectedCurrency]);
 
+    // 综合加载状态（任一基础请求在加载则返回 true）
     const isLoading = useMemo(() => isMemberCountLoading || isMrrLoading || isSubscriptionLoading, [isMemberCountLoading, isMrrLoading, isSubscriptionLoading]);
 
-    // Process subscription data for real subscription events (like Ember dashboard)
+    /**
+     * subscriptionData：
+     * - 将 subscriptionStatsResponse.stats 按日期合并（累加 signups 与 cancellations）
+     * - 结果按时间升序排序，并过滤到请求范围 [dateFrom, endDate]
+     * - 主要用于显示真实的订阅事件（区别于累积会员数）
+     */
     const subscriptionData = useMemo(() => {
         if (!subscriptionStatsResponse?.stats) {
             return [];
         }
 
-        // Merge subscription stats by date (like Ember's mergeStatsByDate)
+        // 按日期合并（merge by date）
         const mergedByDate = subscriptionStatsResponse.stats.reduce((acc, current) => {
             const dateKey = current.date;
             
@@ -353,11 +433,11 @@ export const useGrowthStats = (range: number) => {
             return acc;
         }, {} as Record<string, {date: string; signups: number; cancellations: number}>);
 
-        // Convert to array and sort by date
+        // 转数组并按日期排序
         const subscriptionArray = Object.values(mergedByDate).sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime()
         );
 
-        // Filter to requested date range
+        // 过滤到请求范围
         const dateFromMoment = moment(dateFrom);
         const dateToMoment = moment(endDate);
         return subscriptionArray.filter((item) => {
@@ -366,6 +446,7 @@ export const useGrowthStats = (range: number) => {
         });
     }, [subscriptionStatsResponse, dateFrom, endDate]);
 
+    // 最终返回：供组件/页面直接消费的所有字段
     return {
         isLoading,
         memberData,

apps/stats/src/views/Stats/Overview/Overview.tsx

@@ -77,8 +77,14 @@ const Overview: React.FC = () => {
         }
     });
 
-    /* Get visitors
+    /* 获取访客（visitors）数据
-    /* ---------------------------------------------------------------------- */
+    ----------------------------------------------------------------------
+    说明：
+    - 该部分通过 `useTinybirdQuery` 向 Tinybird（或 stats 后端）发起查询，获取按日期聚合的访问量数据。
+    - 接着使用 `sanitizeChartData` 对数据做日期范围内的聚合/缺失点填充/离群值检测（由 range 决定日/周/月聚合策略）。
+    - 最终把数据映射为 `GhAreaChart` 可识别的格式（date, value, formattedValue, label），并传入展示组件。
+    - 这里的 visitorsChartData 是概览页中显示“访客曲线”的数据源。
+    */
     const visitorsParams = {
         site_uuid: statsConfig?.id || '',
         date_from: formatQueryDate(startDate),
@@ -94,7 +100,11 @@ const Overview: React.FC = () => {
     });
 
     const visitorsChartData = useMemo(() => {
-        return sanitizeChartData<WebKpiDataItem>(visitorsData as WebKpiDataItem[] || [], range, 'visits' as keyof WebKpiDataItem, 'sum')?.map((item: WebKpiDataItem) => {
+        // 先对原始数据进行清洗和聚合（按 range: day/week/month）
+        const sanitized = sanitizeChartData<WebKpiDataItem>(visitorsData as WebKpiDataItem[] || [], range, 'visits' as keyof WebKpiDataItem, 'sum') || [];
+
+        // 将每项转换为 GhAreaChart 所需的字段格式
+        return sanitized.map((item: WebKpiDataItem) => {
             const value = Number(item.visits);
             const safeValue = isNaN(value) ? 0 : value;
             return {

apps/stats/src/views/Stats/Overview/components/TopPosts.tsx

@@ -7,6 +7,20 @@ import {getPostStatusText} from '@tryghost/admin-x-framework/utils/post-utils';
 import {useAppContext, useNavigate} from '@tryghost/admin-x-framework';
 import {useGlobalData} from '@src/providers/GlobalDataProvider';
 
+/**
+ * TopPosts.tsx
+ * 说明：
+ * - 本文件渲染概览页面中的 "Top posts" 卡片，展示在选定时间范围内按浏览量排序的文章摘要。
+ * - 每一行显示文章标题、作者、发布日期、状态及若干关键指标（Web visitors / Newsletter / New members）。
+ * - 支持点击文章跳转到该文章的 analytics 详情页（跨应用路由）。
+ *
+ * 主要职责：
+ * - 根据 appSettings 决定显示哪些指标（web analytics、email opens/clicks、members tracking 等）
+ * - 为每个指标提供 tooltip（展示更详细的数值）
+ * - 在加载中显示骨架表格，在无数据时显示 EmptyIndicator
+ */
+
+/* Tooltip 组件：鼠标悬停时显示每个帖子的多个指标（例如 unique visitors / opens / clicks / new members） */
 interface PostlistTooptipProps {
     title?: string;
     metrics?: Array<{
@@ -24,6 +38,11 @@ const PostListTooltip:React.FC<PostlistTooptipProps> = ({
 }) => {
     return (
         <>
+            {/* 
+                Tooltip 容器
+                - 使用 group-hover/tooltip 来控制显示/隐藏（基于父元素 hover）
+                - 绝对定位在指标按钮上方，包含标题行与指标列表
+            */}
             <div className={
                 cn('pointer-events-none absolute bottom-[calc(100%+2px)] left-1/2 z-50 min-w-[160px] -translate-x-1/2 rounded-md bg-background p-3 text-sm opacity-0 shadow-md transition-all group-hover/tooltip:bottom-[calc(100%+12px)] group-hover/tooltip:opacity-100', className)
             }>
@@ -44,6 +63,7 @@ const PostListTooltip:React.FC<PostlistTooptipProps> = ({
     );
 };
 
+/* 类型定义：Top posts 卡片接收的数据结构 */
 interface TopPostsData {
     stats?: TopPostViewsStats[];
 }
@@ -53,24 +73,31 @@ interface TopPostsProps {
     isLoading: boolean;
 }
 
+/**
+ * TopPosts 组件
+ * - topPostsData.stats: 每一项包含 TopPostViewsStats（由后端提供：views, members, sent_count, opened_count 等）
+ * - isLoading: 数据获取中则展示 SkeletonTable
+ */
 const TopPosts: React.FC<TopPostsProps> = ({
     topPostsData,
     isLoading
 }) => {
     const navigate = useNavigate();
-    const {range} = useGlobalData();
+    const {range} = useGlobalData();         // 全局时间范围（用于标题 "Top posts (Last 7 days)"）
-    const {appSettings} = useAppContext();
+    const {appSettings} = useAppContext();   // 全局应用设置，用于决定显示哪些指标
 
-    // Show open rate if newsletters are enabled and email tracking is enabled
+    // 根据设置决定是否展示对应指标
-    const showWebAnalytics = appSettings?.analytics.webAnalytics;
+    const showWebAnalytics = appSettings?.analytics.webAnalytics;           // 是否显示 Unique visitors
-    const showClickTracking = appSettings?.analytics.emailTrackClicks;
+    const showClickTracking = appSettings?.analytics.emailTrackClicks;      // 是否显示点击率（clicks）
-    const showOpenTracking = appSettings?.analytics.emailTrackOpens;
+    const showOpenTracking = appSettings?.analytics.emailTrackOpens;       // 是否显示打开率（opens）
 
+    // metricClass：共享的样式类，用于右侧每个指标的显示（图标 + 值）
     const metricClass = 'flex items-center justify-end gap-1 rounded-md px-2 py-1 font-mono text-gray-800 hover:bg-muted-foreground/10 group-hover:text-foreground';
 
     return (
         <Card className='group/card w-full lg:col-span-2' data-testid='top-posts-card'>
             <CardHeader>
+                {/* 标题：包含时间范围描述（getPeriodText 会基于 range 返回如 "this week"） */}
                 <CardTitle className='flex items-baseline justify-between font-medium  leading-snug text-muted-foreground'>
                     Top posts {getPeriodText(range)}
                 </CardTitle>
@@ -78,39 +105,52 @@ const TopPosts: React.FC<TopPostsProps> = ({
             </CardHeader>
             <CardContent>
                 {isLoading ?
+                    /* 加载中展示骨架表格，替代真实条目 */
                     <SkeletonTable className='mt-6' />
                     :
                     <>
                         {
+                            /* 列表渲染：遍历 topPostsData.stats，每一项渲染为一行 */
                             topPostsData?.stats?.map((post: TopPostViewsStats) => {
                                 return (
                                     <div key={post.post_id} className='group relative flex w-full items-start justify-between gap-5 border-t border-border/50 py-4 before:absolute before:-inset-x-4 before:inset-y-0 before:z-0 before:hidden before:rounded-md before:bg-accent before:opacity-80 before:content-[""] first:!border-border hover:cursor-pointer hover:border-transparent hover:before:block md:items-center dark:before:bg-accent/50 [&+div]:hover:border-transparent'>
+                                        {/* 左侧：封面缩略 + 标题/作者/发布日期/状态，点击整块跳转到文章 Analytics 概览 */}
                                         <div className='z-10 flex min-w-[160px] grow items-start gap-4 md:items-center lg:min-w-[320px]' onClick={() => {
+                                            // 跨应用导航到文章分析主页面（Overview）
                                             navigate(`/posts/analytics/${post.post_id}`, {crossApp: true});
                                         }}>
                                             {post.feature_image ?
+                                                /* 若存在 feature_image，使用背景图展示缩略 */
                                                 <div className='hidden aspect-[16/10] w-[80px] shrink-0 rounded-sm bg-cover bg-center sm:!visible sm:!block lg:w-[100px]' style={{
                                                     backgroundImage: `url(${post.feature_image})`
                                                 }}></div>
                                                 :
+                                                /* 否则使用占位组件 */
                                                 <FeatureImagePlaceholder className='hidden aspect-[16/10] w-[80px] shrink-0 group-hover:bg-muted-foreground/10 sm:!visible sm:!flex lg:w-[100px]' />
                                             }
                                             <div className='flex flex-col'>
+                                                {/* 标题（最多两行） */}
                                                 <span className='line-clamp-2 text-lg font-semibold leading-[1.35em]'>{post.title}</span>
+                                                {/* 作者与发布时间 */}
                                                 <span className='text-sm text-muted-foreground'>
                                                     By {post.authors} &ndash; {formatDisplayDate(post.published_at)}
                                                 </span>
+                                                {/* 文章状态（例如 Draft / Published / Scheduled） */}
                                                 <span className='text-sm text-muted-foreground'>
                                                     {getPostStatusText(post)}
                                                 </span>
                                             </div>
                                         </div>
+
+                                        {/* 右侧：各指标列（按设置显示不同列），每个指标区域支持点击跳转并包含 Tooltip */}
                                         <div className='z-10 flex flex-col items-end justify-center gap-0.5 text-sm md:flex-row md:items-center md:justify-end md:gap-3'>
+                                            {/* Web analytics 列：Unique visitors */}
                                             {showWebAnalytics &&
                                                 <div className='group/tooltip relative flex w-[66px] lg:w-[92px]' data-testid='statistics-visitors' onClick={(e) => {
-                                                    e.stopPropagation();
+                                                    e.stopPropagation(); // 阻止外层行点击，避免同时触发导航
                                                     navigate(`/posts/analytics/${post.post_id}/web`, {crossApp: true});
                                                 }}>
+                                                    {/* Tooltip：展示 Unique visitors 的详细数值 */}
                                                     <PostListTooltip
                                                         metrics={[
                                                             {
@@ -127,27 +167,29 @@ const TopPosts: React.FC<TopPostsProps> = ({
                                                     </div>
                                                 </div>
                                             }
+
+                                            {/* Newsletter 列：如果有 sent_count 字段，展示邮件相关指标（sent / opens / clicks） */}
                                             {post.sent_count !== null &&
                                                 <div className='group/tooltip relative flex w-[66px] lg:w-[92px]' onClick={(e) => {
                                                     e.stopPropagation();
                                                     navigate(`/posts/analytics/${post.post_id}/newsletter`, {crossApp: true});
                                                 }}>
+                                                    {/* Tooltip：根据 appSettings 显示 sent / opens / clicks */}
                                                     <PostListTooltip
                                                         className={`${!appSettings?.analytics.membersTrackSources ? 'left-auto right-0 translate-x-0' : ''}`}
                                                         metrics={[
-                                                            // Always show sent
                                                             {
                                                                 icon: <LucideIcon.Send className='shrink-0 text-muted-foreground' size={16} strokeWidth={1.5} />,
                                                                 label: 'Sent',
                                                                 metric: formatNumber(post.sent_count || 0)
                                                             },
-                                                            // Only show opens if open tracking is enabled
+                                                            // 仅在启用 open tracking 时展示 Open 数
                                                             ...(showOpenTracking ? [{
                                                                 icon: <LucideIcon.MailOpen className='shrink-0 text-muted-foreground' size={16} strokeWidth={1.5} />,
                                                                 label: 'Opens',
                                                                 metric: formatNumber(post.opened_count || 0)
                                                             }] : []),
-                                                            // Only show clicks if click tracking is enabled
+                                                            // 仅在启用 click tracking 时展示 Click 数
                                                             ...(showClickTracking ? [{
                                                                 icon: <LucideIcon.MousePointer className='shrink-0 text-muted-foreground' size={16} strokeWidth={1.5} />,
                                                                 label: 'Clicks',
@@ -158,8 +200,10 @@ const TopPosts: React.FC<TopPostsProps> = ({
                                                     />
                                                     <div className={metricClass}>
                                                         {(() => {
-                                                            // If clicks and opens are enabled, show open rate %
+                                                            // 在展示区域根据追踪设置选择显示内容：
-                                                            // If clicks are disabled but opens enabled, show open rate %
+                                                            // - 优先显示 open rate（若启用）
+                                                            // - 否则若启用 click tracking 则显示 click rate
+                                                            // - 否则回退显示已发送数（sent）
                                                             if (showOpenTracking) {
                                                                 return (
                                                                     <>
@@ -168,7 +212,6 @@ const TopPosts: React.FC<TopPostsProps> = ({
                                                                     </>
                                                                 );
                                                             } else if (showClickTracking) {
-                                                                // If open rate is disabled but clicks enabled, show click rate %
                                                                 return (
                                                                     <>
                                                                         <LucideIcon.MousePointer className='text-muted-foreground group-hover:text-foreground' size={16} strokeWidth={1.5} />
@@ -176,7 +219,6 @@ const TopPosts: React.FC<TopPostsProps> = ({
                                                                     </>
                                                                 );
                                                             } else {
-                                                                // If both are disabled, show sent count
                                                                 return (
                                                                     <>
                                                                         <LucideIcon.Send className='text-muted-foreground group-hover:text-foreground' size={16} strokeWidth={1.5} />
@@ -188,11 +230,14 @@ const TopPosts: React.FC<TopPostsProps> = ({
                                                     </div>
                                                 </div>
                                             }
+
+                                            {/* Members 列：若启用 membersTrackSources，则展示新增会员数（free / paid） */}
                                             {appSettings?.analytics.membersTrackSources &&
                                                 <div className='group/tooltip relative flex w-[66px] lg:w-[92px]' data-testid='statistics-members' onClick={(e) => {
                                                     e.stopPropagation();
                                                     navigate(`/posts/analytics/${post.post_id}/growth`, {crossApp: true});
                                                 }}>
+                                                    {/* Tooltip：展示 Free / Paid 新增会员（Paid 仅在站点启用付费会员时显示） */}
                                                     <PostListTooltip
                                                         className='left-auto right-0 translate-x-0'
                                                         metrics={[
@@ -201,7 +246,6 @@ const TopPosts: React.FC<TopPostsProps> = ({
                                                                 label: 'Free',
                                                                 metric: post.free_members > 0 ? `+${formatNumber(post.free_members)}` : '0'
                                                             },
-                                                            // Only show paid members if paid members are enabled
                                                             ...(appSettings?.paidMembersEnabled ? [{
                                                                 icon: <LucideIcon.CreditCard className='shrink-0 text-muted-foreground' size={16} strokeWidth={1.5} />,
                                                                 label: 'Paid',
@@ -221,6 +265,7 @@ const TopPosts: React.FC<TopPostsProps> = ({
                                 );
                             })
                         }
+                        {/* 无数据状态：若 stats 为空则展示 EmptyIndicator 提示 */}
                         {(!topPostsData?.stats || topPostsData.stats.length === 0) && (
                             <EmptyIndicator
                                 className='w-full pb-10'

e2e/helpers/pages/admin/analytics/AnalyticsWebTrafficPage.ts

@@ -1,51 +1,97 @@
-import {Locator, Page} from '@playwright/test';
+import { Locator, Page } from '@playwright/test';
-import {AdminPage} from '../AdminPage';
+// 导入父类AdminPage，该类继承了管理员页面的通用属性和方法（如页面导航、通用元素等）
+import { AdminPage } from '../AdminPage';
 
+/**
+ * 博客后台"网站流量分析"页面的页面对象模型
+ * 封装了该页面的所有元素定位和交互方法，用于自动化测试
+ */
 export class AnalyticsWebTrafficPage extends AdminPage {
+    // 总浏览量标签页的定位器（用于切换到总浏览量视图）
     readonly totalViewsTab: Locator;
+    // 唯一访客数标签页的定位器（用于切换到唯一访客视图）
     readonly totalUniqueVisitorsTab: Locator;
+    // 页面中流量图表（折线图/柱状图）的容器定位器
+    // 私有属性，仅在类内部使用（通过方法暴露交互能力）
     private readonly webGraph: Locator;
 
+    // "热门内容"统计卡片的定位器（包含内容访问量排名）
     readonly topContentCard: Locator;
+    // "热门内容"卡片中的"文章和页面"标签按钮（切换显示所有内容类型）
     readonly postsAndPagesButton: Locator;
+    // "热门内容"卡片中的"文章"标签按钮（仅显示文章的访问排名，exact确保精确匹配文本）
     readonly postsButton: Locator;
+    // "热门内容"卡片中的"页面"标签按钮（仅显示页面的访问排名）
     readonly pagesButton: Locator;
 
+    // "热门来源"统计卡片的定位器（显示流量来源渠道排名，如搜索引擎、外部链接等）
     public readonly topSourcesCard: Locator;
 
+    /**
+     * 构造函数，初始化页面元素定位器
+     * @param page Playwright的Page对象，代表当前浏览器页面
+     */
     constructor(page: Page) {
+        // 调用父类构造函数，传递page对象
         super(page);
+        // 当前页面的URL路径，用于页面导航或验证是否在目标页面
         this.pageUrl = '/ghost/#/analytics/web';
 
-        this.totalViewsTab = page.getByRole('tab', {name: 'Total views'});
+        // 初始化标签页定位器：使用角色定位（role="tab"），更符合页面语义和可访问性
-        this.totalUniqueVisitorsTab = page.getByRole('tab', {name: 'Unique visitors'});
+        this.totalViewsTab = page.getByRole('tab', { name: 'Total views' });
+        this.totalUniqueVisitorsTab = page.getByRole('tab', { name: 'Unique visitors' });
 
+        // 初始化图表定位器：使用data-testid属性（开发者为测试预留的标识），定位更稳定
         this.webGraph = page.getByTestId('web-graph');
 
+        // 初始化热门内容卡片及内部标签：通过卡片容器定位子元素，缩小查找范围提高效率
         this.topContentCard = page.getByTestId('top-content-card');
-        this.postsAndPagesButton = this.topContentCard.getByRole('tab', {name: 'Posts & pages'});
+        this.postsAndPagesButton = this.topContentCard.getByRole('tab', { name: 'Posts & pages' });
-        this.postsButton = this.topContentCard.getByRole('tab', {name: 'Posts', exact: true});
+        this.postsButton = this.topContentCard.getByRole('tab', { name: 'Posts', exact: true });
-        this.pagesButton = this.topContentCard.getByRole('tab', {name: 'Pages', exact: true});
+        this.pagesButton = this.topContentCard.getByRole('tab', { name: 'Pages', exact: true });
 
+        // 初始化热门来源卡片定位器
         this.topSourcesCard = page.getByTestId('top-sources-card');
     }
 
+    /**
+     * 获取总浏览量图表区域的文本内容
+     * 通常用于断言图表显示的统计数据（如总浏览量数值、时间范围提示等）
+     * @returns 图表区域的文本内容（字符串或null）
+     */
     async totalViewsContent() {
         return await this.webGraph.textContent();
     }
 
+    /**
+     * 获取"唯一访客"标签页的文本内容
+     * 可用于验证标签显示的文本或数字（如标签上的小红点数字提示）
+     * @returns 标签页的文本内容（字符串或null）
+     */
     async totalUniqueVisitorsContent() {
         return await this.totalUniqueVisitorsTab.textContent();
     }
 
+    /**
+     * 点击"总浏览量"标签页，切换到总浏览量统计视图
+     * 模拟用户操作，切换后图表会显示总浏览量相关数据
+     */
     async viewTotalViews() {
         await this.totalViewsTab.click();
     }
 
+    /**
+     * 点击"唯一访客"标签页，切换到唯一访客统计视图
+     * 模拟用户操作，切换后图表会显示唯一访客相关数据
+     */
     async viewTotalUniqueVisitors() {
         await this.totalUniqueVisitorsTab.click();
-    }
+    }0 vcf
 
+    /**
+     * 读取流量图表的文本内容（与totalViewsContent功能类似，可能用于分步操作中获取内容）
+     * 注意：当前实现未返回内容，若需使用需修改为return语句
+     */
     async viewWebGraphContent() {
         await this.webGraph.textContent();
     }

e2e/helpers/pages/admin/analytics/post-analytics/PostAnalyticsGrowthPage.ts

@@ -1,17 +1,42 @@
-import {Locator, Page} from '@playwright/test';
+import { Locator, Page } from '@playwright/test';
-import {AdminPage} from '../../AdminPage';
+// 导入管理员页面基类，继承通用的管理员页面属性和方法（如页面导航、基础元素操作）
+import { AdminPage } from '../../AdminPage';
 
+/**
+ * PostAnalyticsGrowthPage（文章分析增长页面）
+ * 作用：封装文章分析模块中“Growth（增长）”视图的所有元素定位器和基础交互方法
+ * 适用场景：在端到端（e2e）测试中，用于操作和验证与文章增长相关的数据展示（如成员数据、流量来源）
+ */
 export class PostAnalyticsGrowthPage extends AdminPage {
+    // 成员统计卡片的容器定位器
+    // 说明：通过data-testid定位，这是开发者为测试预留的标识，定位稳定性高，不易受UI变动影响
+    // 用途：用于获取成员相关统计信息（如免费成员数、付费成员数等）的容器元素
     readonly membersCard: Locator;
+
+    // 成员卡片内的“View member”按钮定位器
+    // 说明：在membersCard容器内通过角色（button）和名称（View member）定位，确保按钮唯一
+    // 用途：点击后跳转到成员管理页面，查看该文章相关的成员详情
     readonly viewMemberButton: Locator;
+
+    // 流量来源（Top sources）卡片的容器定位器
+    // 说明：通过data-testid定位，用于获取访问来源相关数据（如直接访问、搜索引擎、外部链接等）
     readonly topSourcesCard: Locator;
 
+    /**
+     * 构造函数：初始化页面元素定位器
+     * @param page Playwright的Page对象，代表当前浏览器页面实例，所有元素操作基于此对象
+     */
     constructor(page: Page) {
+        // 调用父类AdminPage的构造函数，传入page对象以继承基础功能
         super(page);
 
+        // 初始化成员卡片定位器：匹配data-testid="members-card"的元素
         this.membersCard = this.page.getByTestId('members-card');
-        this.viewMemberButton = this.membersCard.getByRole('button', {name: 'View member'});
 
+        // 初始化“View member”按钮定位器：在成员卡片内查找角色为button、名称为View member的元素
+        this.viewMemberButton = this.membersCard.getByRole('button', { name: 'View member' });
+
+        // 初始化流量来源卡片定位器：匹配data-testid="top-sources-card"的元素
         this.topSourcesCard = this.page.getByTestId('top-sources-card');
     }
-}
+}

e2e/helpers/pages/admin/analytics/post-analytics/PostAnalyticsPage.ts

@@ -1,54 +1,102 @@
-import {Locator, Page} from '@playwright/test';
+import { Locator, Page } from '@playwright/test';
-import {AdminPage} from '../../AdminPage';
+// 导入管理员页面基类，所有管理后台页面均继承此类，可复用通用属性和方法（如页面导航）
+import { AdminPage } from '../../AdminPage';
 
+/**
+ * GrowthSection（增长区块）
+ * 作用：封装文章分析页面中“Growth（增长）”子区块的所有元素和交互逻辑
+ * 说明：该区块主要展示与用户增长相关的摘要数据，提供“View more”按钮查看详情
+ */
 class GrowthSection extends AdminPage {
+    // Growth区块的容器定位器（最外层元素），通过data-testid定位，稳定性高
     readonly card: Locator;
+    // Growth区块内的“View more”按钮定位器，用于点击查看更详细的增长数据
     readonly viewMoreButton: Locator;
 
+    /**
+     * 构造函数：初始化Growth区块的元素定位器
+     * @param page Playwright的Page对象，代表当前浏览器页面
+     */
     constructor(page: Page) {
-        super(page);
+        super(page); // 调用父类构造函数，继承页面上下文
 
+        // 通过data-testid="growth"定位区块容器（开发预留的测试标识，不易变更）
         this.card = this.page.getByTestId('growth');
-        this.viewMoreButton = this.card.getByRole('button', {name: 'View more'});
+        // 在容器内定位“View more”按钮（按角色+名称定位，符合页面语义）
+        this.viewMoreButton = this.card.getByRole('button', { name: 'View more' });
     }
 }
 
+/**
+ * WebPerformanceSection（网站表现区块）
+ * 作用：封装文章分析页面中“Web performance（网站表现）”子区块的元素和交互
+ * 说明：该区块主要展示网站性能相关数据（如唯一访客数），提供详情查看入口
+ */
 class WebPerformanceSection extends AdminPage {
+    // Web performance区块的容器定位器
     readonly card: Locator;
+    // 区块内显示“唯一访客数”的元素定位器（核心数据展示元素）
     readonly uniqueVisitors: Locator;
+    // 区块内的“View more”按钮定位器，用于查看更详细的网站表现数据
     readonly viewMoreButton: Locator;
 
+    /**
+     * 构造函数：初始化Web performance区块的元素定位器
+     * @param page Playwright的Page对象，代表当前浏览器页面
+     */
     constructor(page: Page) {
-        super(page);
+        super(page); // 调用父类构造函数
 
+        // 通过data-testid="web-performance"定位区块容器
         this.card = this.page.getByTestId('web-performance');
+        // 在容器内通过data-testid定位唯一访客数元素（精确指向数据展示区域）
         this.uniqueVisitors = this.card.getByTestId('unique-visitors');
-        this.viewMoreButton = this.card.getByRole('button', {name: 'View more'});
+        // 在容器内定位“View more”按钮
+        this.viewMoreButton = this.card.getByRole('button', { name: 'View more' });
     }
 }
 
+/**
+ * PostAnalyticsPage（文章分析页面）
+ * 作用：文章分析主页面的页面对象，聚合所有子区块和顶部导航按钮，提供整体页面操作
+ * 包含的核心功能：视图切换（Overview/Web traffic/Growth）、子区块访问、页面加载等待
+ */
 export class PostAnalyticsPage extends AdminPage {
-    readonly overviewButton: Locator;
+    // 顶部视图切换按钮：用于在不同分析视图间切换
-    readonly webTrafficButton: Locator;
+    readonly overviewButton: Locator; // “概览”视图按钮
-    readonly growthButton: Locator;
+    readonly webTrafficButton: Locator; // “网站流量”视图按钮
+    readonly growthButton: Locator; // “增长”视图按钮
 
-    readonly growthSection: GrowthSection;
+    // 子区块实例：通过组合子区块类，实现对页面各部分的精细化操作
-    readonly webPerformanceSection: WebPerformanceSection;
+    readonly growthSection: GrowthSection; // 增长区块实例
+    readonly webPerformanceSection: WebPerformanceSection; // 网站表现区块实例
 
+    /**
+     * 构造函数：初始化文章分析页面的导航按钮和子区块
+     * @param page Playwright的Page对象，代表当前浏览器页面
+     */
     constructor(page: Page) {
-        super(page);
+        super(page); // 调用父类构造函数
+        // 当前页面的路由地址（用于页面导航或验证是否在目标页面）
         this.pageUrl = '/ghost/#/analytics';
 
-        this.overviewButton = this.page.getByRole('button', {name: 'Overview'});
+        // 初始化顶部视图切换按钮（按角色+名称定位，确保点击目标准确）
-        this.webTrafficButton = this.page.getByRole('button', {name: 'Web traffic'});
+        this.overviewButton = this.page.getByRole('button', { name: 'Overview' });
-        this.growthButton = this.page.getByRole('button', {name: 'Growth'});
+        this.webTrafficButton = this.page.getByRole('button', { name: 'Web traffic' });
+        this.growthButton = this.page.getByRole('button', { name: 'Growth' });
 
+        // 实例化子区块对象，传入当前page实例以共享页面上下文
         this.growthSection = new GrowthSection(page);
         this.webPerformanceSection = new WebPerformanceSection(page);
     }
 
+    /**
+     * 等待页面加载完成的方法
+     * 逻辑：通过等待webPerformanceSection区块可见，判断页面核心内容已加载
+     * 用途：在测试中调用，确保页面元素渲染完成后再执行后续操作（如点击、断言），避免异步加载导致的错误
+     */
     async waitForPageLoad() {
-        await this.webPerformanceSection.card.waitFor({state: 'visible'});
+        // 等待网站表现区块容器处于可见状态（{state: 'visible'}为可见性检查）
+        await this.webPerformanceSection.card.waitFor({ state: 'visible' });
     }
-}
+}
-

e2e/helpers/pages/admin/analytics/post-analytics/PostAnalyticsWebTrafficPage.ts

@@ -1,8 +1,60 @@
-import {Page} from '@playwright/test';
+import { Page } from '@playwright/test';
-import {AdminPage} from '../../AdminPage';
+// 导入管理员页面基类，继承管理员页面的通用属性和方法（如页面导航、基础元素等）
+import { AdminPage } from '../../AdminPage';
 
+/**
+ * 文章级别“网站流量”分析页面的页面对象模型（POM）
+ * 
+ * 核心作用：
+ * - 封装文章详情页中与“Web Traffic”（网站流量）相关的所有元素定位器和交互方法
+ * - 为端到端（e2e）测试提供统一的操作接口，避免测试用例中硬编码元素定位逻辑
+ * 
+ * 适用场景：
+ * 当需要测试单篇文章的流量数据（如浏览量、访问来源、访问趋势等）时，通过此类操作页面元素
+ */
 export class PostAnalyticsWebTrafficPage extends AdminPage {
+    /**
+     * 构造函数：初始化页面实例并准备元素定位器
+     * @param page Playwright的Page对象，代表当前浏览器页面实例，用于操作页面元素
+     */
     constructor(page: Page) {
+        // 调用父类AdminPage的构造函数，传递page对象以继承基础功能
         super(page);
+        
+        // TODO：当前为占位说明，实际使用时需补充以下内容：
+        // 1. 页面URL（如有固定路由，用于验证是否在目标页面或直接导航）
+        //    示例：this.pageUrl = '/ghost/#/analytics/post/123'; // 假设123为文章ID
+        //
+        // 2. 元素定位器（根据页面实际DOM结构补充）：
+        //    - 流量图表容器（如折线图/柱状图）
+        //    - 总浏览量/唯一访客数等统计数据元素
+        //    - 流量来源（Top sources）卡片及内部元素
+        //    - 热门内容（Top content）相关元素
+        //    - 时间范围切换控件（如7天/30天/90天）
+        //
+        // 示例定位器（仅为参考，需根据实际测试ID或属性调整）：
+        // this.trafficGraph = page.getByTestId('post-traffic-graph'); // 文章流量图表
+        // this.totalViewsStat = page.getByTestId('post-total-views'); // 总浏览量统计
+        // this.timeRangeSelector = page.getByRole('combobox', { name: 'Time range' }); // 时间范围选择器
+        // this.topSourcesList = page.getByTestId('post-top-sources-list'); // 流量来源列表
     }
-}
+
+    /**
+     * （预留说明）建议添加的常用方法示例：
+     * 
+     * 1. 获取图表显示的总浏览量
+     * async getTotalViews(): Promise<string | null> {
+     *   return await this.totalViewsStat.textContent();
+     * }
+     * 
+     * 2. 切换时间范围（如切换到30天数据）
+     * async setTimeRange(range: '7d' | '30d' | '90d'): Promise<void> {
+     *   await this.timeRangeSelector.selectOption(range);
+     * }
+     * 
+     * 3. 验证流量来源列表是否包含指定来源
+     * async hasSource(sourceName: string): Promise<boolean> {
+     *   return await this.topSourcesList.getByText(sourceName).isVisible();
+     * }
+     */
+}

e2e/tests/admin/analytics/post-analytics/growth.test.ts

@@ -1,42 +1,68 @@
-import {test, expect} from '../../../../helpers/playwright';
+// 导入Playwright测试工具（test用于定义测试用例结构，expect用于结果断言验证）
+// 从项目自定义helpers中导入playwright工具包（可能包含项目特有的配置或辅助函数）
+import { test, expect } from '../../../../helpers/playwright';
+// 导入所需的页面对象类（每个类对应管理后台的一个页面/功能模块）
 import {
-    AnalyticsOverviewPage,
+    AnalyticsOverviewPage,       // 分析概览页面（展示所有内容的分析入口）
-    PostAnalyticsPage,
+    PostAnalyticsPage,          // 文章分析主页面（包含概览、流量、增长等多个视图切换）
-    PostAnalyticsGrowthPage,
+    PostAnalyticsGrowthPage,    // 文章分析的“增长”子页面（专注于用户增长和流量来源数据）
-    MembersPage
+    MembersPage                 // 成员管理页面（展示所有用户成员信息）
 } from '../../../../helpers/pages/admin';
 
+// 定义测试套件：对Ghost管理后台中“文章分析-增长”页面的测试集合
+// test.describe用于将相关测试用例分组，增强代码可读性和维护性
 test.describe('Ghost Admin - Post Analytics - Growth', () => {
-    test.beforeEach(async ({page}) => {
+    // 前置钩子函数：每个测试用例执行前自动运行
+    // 作用：创建统一的测试前置条件，确保所有用例从相同初始状态开始
+    test.beforeEach(async ({ page }) => {
+        // 1. 实例化分析概览页面对象（获取该页面的元素操作能力）
         const analyticsOverviewPage = new AnalyticsOverviewPage(page);
+        // 2. 导航到分析概览页面（内部封装了页面跳转和加载完成的验证）
         await analyticsOverviewPage.goto();
+
+        // 3. 在概览页面中，点击最新文章的“analytics”按钮
+        //    （latestPost是AnalyticsOverviewPage中定义的“最新文章”元素对象，包含其专属的analyticsButton）
         await analyticsOverviewPage.latestPost.analyticsButton.click();
 
-        // TODO: check post analytics component, we shouldn't need to wait on page load to be able to click growth link
+        // TODO：优化提示——未来可调整为无需等待页面完全加载即可点击growth链接（提升测试效率）
+        // 4. 实例化文章分析主页面对象（当前处于文章分析的概览视图）
         const postAnalyticsPage = new PostAnalyticsPage(page);
+        // 5. 等待文章分析页面加载完成（内部通过等待关键元素出现来确认页面就绪，避免操作过早导致失败）
         await postAnalyticsPage.waitForPageLoad();
+        // 6. 点击“Growth”按钮，切换到增长数据视图（进入当前测试套件的目标页面）
         await postAnalyticsPage.growthButton.click();
     });
 
-    test('empty members card', async ({page}) => {
+    // 测试用例1：验证空数据时成员卡片的显示内容
+    test('empty members card', async ({ page }) => {
+        // 实例化文章分析的增长页面对象（获取当前页面的元素操作能力）
         const postAnalyticsPageGrowthPage = new PostAnalyticsGrowthPage(page);
 
+        // 断言1：成员卡片应包含“Free members”文本（验证标签显示正确）
         await expect(postAnalyticsPageGrowthPage.membersCard).toContainText('Free members');
+        // 断言2：成员卡片应包含“0”（验证空数据场景下数量显示正确）
         await expect(postAnalyticsPageGrowthPage.membersCard).toContainText('0');
     });
 
-    test('empty members card - view member', async ({page}) => {
+    // 测试用例2：验证空成员场景下点击“查看成员”的跳转结果
+    test('empty members card - view member', async ({ page }) => {
+        // 实例化增长页面对象
         const postAnalyticsPageGrowthPage = new PostAnalyticsGrowthPage(page);
+        // 点击增长页面上的“查看成员”按钮（模拟用户查看详情的操作）
         await postAnalyticsPageGrowthPage.viewMemberButton.click();
 
+        // 实例化成员管理页面对象（跳转后的目标页面）
         const membersPage = new MembersPage(page);
+        // 断言：成员页面应显示“无成员匹配”的提示文本（验证空数据跳转后的状态正确）
         await expect(membersPage.body).toContainText('No members match');
     });
 
-    test('empty top sources card', async ({page}) => {
+    // 测试用例3：验证Top sources卡片在无数据时的提示文本
+    test('empty top sources card', async ({ page }) => {
+        // 实例化增长页面对象
         const postAnalyticsPageGrowthPage = new PostAnalyticsGrowthPage(page);
 
+        // 断言：顶部来源卡片应包含“No sources data available”（验证无数据提示正确）
         await expect(postAnalyticsPageGrowthPage.topSourcesCard).toContainText('No sources data available');
     });
-});
+});
-

e2e/tests/admin/analytics/post-analytics/overview.test.ts

@@ -1,48 +1,80 @@
-import {test, expect} from '../../../../helpers/playwright';
+// 导入Playwright测试核心工具：test用于定义测试用例，expect用于用于断言验证结果
+// 从项目helpers目录导入导入playwright工具包（封装含项目自定义的测试配置或工具函数）
+import { test, expect } from '../../../../helpers/playwright';
+// 导入所需的页面对象类（对应管理后台的不同页面/组件）
 import {
-    AnalyticsOverviewPage,
+    AnalyticsOverviewPage,          // 分析概览页面（入口页面）
-    PostAnalyticsPage,
+    PostAnalyticsPage,             // 文章分析主页面（Overview视图）
-    PostAnalyticsGrowthPage,
+    PostAnalyticsGrowthPage,       // 文章分析的Growth详情页面
-    PostAnalyticsWebTrafficPage
+    PostAnalyticsWebTrafficPage    // 文章分析的Web Traffic详情页面
 } from '../../../../helpers/pages/admin';
 
+/**
+ * 文件说明：
+ * 这个测试文件包含文章级别 Analytics 的 Overview 视图相关的 e2e 测试。
+ * 场景主要验证在“空数据”情况下，各个卡片/选项卡的可见性和提示文本。
+ */
+
+// 定义测试套件：Ghost管理后台 - 文章分析 - Overview（概览）视图的测试
+// 所有相关测试用例都归类在此套件下，便于管理和理解测试范围
 test.describe('Ghost Admin - Post Analytics - Overview', () => {
-    test.beforeEach(async ({page}) => {
+    // 前置操作：每个测试用例执行前都会运行的代码（初始化测试环境）
+    test.beforeEach(async ({ page }) => {
+        // 1. 实例化分析概览页面对象（进入分析模块的入口页面）
         const analyticsOverviewPage = new AnalyticsOverviewPage(page);
+        // 2. 导航到分析概览页面（内部实现页面跳转和加载验证）
         await analyticsOverviewPage.goto();
-
+        // 3. 在概览页面中，点击“最新文章”的analytics按钮，进入该文章的分析面板
+        //    （模拟用户从概览页查看单篇文章详情分析的操作流程）
         await analyticsOverviewPage.latestPost.analyticsButton.click();
     });
 
-    test('empty page with all tabs', async ({page}) => {
+    // 测试用例1：验证概览页面存在三个主要选项卡（确保页面结构完整性）
+    test('empty page with all tabs', async ({ page }) => {
+        // 实例化文章分析主页面对象（当前处于Overview视图）
         const postAnalyticsPage = new PostAnalyticsPage(page);
 
+        // 断言：三个视图切换按钮（Overview/Web traffic/Growth）都应可见
+        // 验证页面基本结构完整，用户可正常切换不同分析视图
         await expect(postAnalyticsPage.overviewButton).toBeVisible();
         await expect(postAnalyticsPage.webTrafficButton).toBeVisible();
         await expect(postAnalyticsPage.growthButton).toBeVisible();
     });
 
-    test('empty page - overview - web performance - view more', async ({page}) => {
+    // 测试用例2：验证从Overview的Web performance区块点击"View more"的跳转和空数据提示
+    test('empty page - overview - web performance - view more', async ({ page }) => {
+        // 实例化文章分析主页面对象
         const postAnalyticsPage = new PostAnalyticsPage(page);
+        // 点击Web performance区块的“View more”按钮（预期跳转到Web traffic详情页）
         await postAnalyticsPage.webPerformanceSection.viewMoreButton.click();
 
+        // 实例化Web traffic详情页面对象（跳转后的目标页面）
         const postAnalyticsWebTrafficPage = new PostAnalyticsWebTrafficPage(page);
+        // 断言：空数据场景下，Web traffic页面应显示指定提示文本（验证空状态展示正确）
         await expect(postAnalyticsWebTrafficPage.body).toContainText('No visitors in the last 30 days');
     });
 
-    test('empty page - overview - growth', async ({page}) => {
+    // 测试用例3：验证Overview视图中Growth区块的空数据展示（成员数相关）
+    test('empty page - overview - growth', async ({ page }) => {
+        // 实例化文章分析主页面对象
         const postAnalyticsPage = new PostAnalyticsPage(page);
 
+        // 断言1：Growth区块应包含“Free members”标签（验证成员类型标签正确）
         await expect(postAnalyticsPage.growthSection.card).toContainText('Free members');
+        // 断言2：Growth区块应显示成员数量为0（验证空数据时数量展示正确）
         await expect(postAnalyticsPage.growthSection.card).toContainText('0');
     });
 
-    test('empty page - overview - growth - view more', async ({page}) => {
+    // 测试用例4：验证从Overview的Growth区块点击"View more"的跳转和空数据提示
+    test('empty page - overview - growth - view more', async ({ page }) => {
+        // 实例化文章分析主页面对象
         const postAnalyticsPage = new PostAnalyticsPage(page);
+        // 点击Growth区块的“View more”按钮（预期跳转到Growth详情页）
         await postAnalyticsPage.growthSection.viewMoreButton.click();
 
+        // 实例化Growth详情页面对象（跳转后的目标页面）
         const postAnalyticsGrowthPage = new PostAnalyticsGrowthPage(page);
+        // 断言：空数据场景下，Top sources卡片应显示指定提示文本（验证空状态展示正确）
         await expect(postAnalyticsGrowthPage.topSourcesCard).toContainText('No sources data available');
     });
-});
+});
-

ghost/admin/app/adapters/label.js

@@ -1,10 +1,27 @@
 import ApplicationAdapter from 'ghost-admin/adapters/application';
 import SlugUrl from 'ghost-admin/utils/slug-url';
 
+/**
+ * Label 适配器
+ * 继承自应用程序基础适配器，用于处理标签(Label)模型与后端API的交互
+ * 主要扩展了URL构建逻辑，支持基于slug参数生成URL
+ */
 export default class Label extends ApplicationAdapter {
+    /**
+     * 重写基础适配器的URL构建方法
+     * 用于生成与标签相关的API请求URL，并支持通过query参数中的slug生成友好URL
+     * @param {string} _modelName - 模型名称（此处未使用，保留参数位置）
+     * @param {string|number} _id - 模型ID（此处未使用，保留参数位置）
+     * @param {Object} _snapshot - 模型快照（此处未使用，保留参数位置）
+     * @param {string} _requestType - 请求类型（如find、create等，此处未使用）
+     * @param {Object} query - 查询参数对象，可能包含slug等信息
+     * @returns {string} 构建后的API请求URL
+     */
     buildURL(_modelName, _id, _snapshot, _requestType, query) {
+        // 调用父类的buildURL方法生成基础URL
         let url = super.buildURL(...arguments);
 
+        // 使用SlugUrl工具处理URL，结合query参数（如slug）生成最终URL
         return SlugUrl(url, query);
     }
-}
+}

ghost/admin/app/adapters/snippet.js

@@ -1,20 +1,36 @@
 import ApplicationAdapter from 'ghost-admin/adapters/application';
 
+/**
+ * 代码片段（Snippet）适配器
+ * 继承自应用程序基础适配器，用于处理代码片段模型与后端API的交互
+ * 核心功能是自动为API请求添加数据格式参数，确保后端返回指定格式的内容
+ */
 export default class Snippet extends ApplicationAdapter {
+    /**
+     * 重写URL构建方法，自动添加格式参数
+     * 确保所有代码片段相关请求都包含formats=mobiledoc,lexical
+     * @param {...any} args - 传递给父类的参数（模型名、ID等）
+     * @returns {string} 处理后的API请求URL
+     */
     buildURL() {
+        // 调用父类方法生成基础URL（包含基础路径、模型路由等）
         const url = super.buildURL(...arguments);
 
         try {
+            // 解析URL以操作查询参数
             const parsedUrl = new URL(url);
+            
+            // 检查是否已包含formats参数，若没有则添加
             if (!parsedUrl.searchParams.get('formats')) {
                 parsedUrl.searchParams.set('formats', 'mobiledoc,lexical');
-                return parsedUrl.href;
+                return parsedUrl.href; // 返回更新后的URL
             }
         } catch (e) {
-            // noop, just use the original url
+            // URL解析失败时，使用原始URL并记录错误
             console.error('Couldn\'t parse URL', e); // eslint-disable-line
         }
 
+        // 若已包含formats参数或解析失败，返回原始URL
         return url;
     }
-}
+}

ghost/admin/app/adapters/tag.js

@@ -1,10 +1,27 @@
 import ApplicationAdapter from 'ghost-admin/adapters/application';
 import SlugUrl from 'ghost-admin/utils/slug-url';
 
+/**
+ * 标签（Tag）适配器
+ * 继承自应用程序基础适配器，用于处理标签模型与后端API的交互
+ * 主要扩展了URL构建逻辑，支持基于slug参数生成友好URL
+ */
 export default class Tag extends ApplicationAdapter {
+    /**
+     * 重写基础适配器的URL构建方法
+     * 用于生成与标签相关的API请求URL，并支持通过query参数中的slug生成语义化URL
+     * @param {string} _modelName - 模型名称（此处未使用，保留参数位置）
+     * @param {string|number} _id - 模型ID（此处未使用，保留参数位置）
+     * @param {Object} _snapshot - 模型快照（此处未使用，保留参数位置）
+     * @param {string} _requestType - 请求类型（如find、create等，此处未使用）
+     * @param {Object} query - 查询参数对象，可能包含slug等信息
+     * @returns {string} 构建后的API请求URL
+     */
     buildURL(_modelName, _id, _snapshot, _requestType, query) {
+        // 调用父类的buildURL方法生成基础URL
         let url = super.buildURL(...arguments);
 
+        // 使用SlugUrl工具处理URL，结合query参数（如slug）生成最终的语义化URL
         return SlugUrl(url, query);
     }
-}
+}

ghost/admin/app/components/admin-x/activitypub.js

@@ -1,13 +1,20 @@
 import AdminXComponent from './admin-x-component';
 import {inject as service} from '@ember/service';
 
+// AdminXActivityPub 继承自 AdminXComponent，提供与 ActivityPub（社交网络功能）相关的绑定和属性。
 export default class AdminXActivityPub extends AdminXComponent {
+    // 注入 upgradeStatus 服务，用于查询或响应系统升级状态（保留以备使用或观察）。
     @service upgradeStatus;
+    // 注入 settings 服务，包含站点设置（例如 socialWebEnabled 标志）。
     @service settings;
 
+    // 指定该组件所属的 NPM 包名，供框架或调试时识别来源。
     static packageName = '@tryghost/admin-x-activitypub';
 
+    // additionalProps 返回一个对象，这些属性会传递给子组件或渲染模板。
+    // 这里我们暴露了 activityPubEnabled，基于 settings 服务中的 socialWebEnabled 标志。
     additionalProps = () => ({
+        // activityPubEnabled: 布尔值，指示是否启用了社交网络（ActivityPub）功能。
         activityPubEnabled: this.settings.socialWebEnabled
     });
 }

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

@@ -1,43 +1,60 @@
-import Component from '@glimmer/component';
+// 导入必要的模块和依赖
-import {action} from '@ember/object';
+import Component from '@glimmer/component';        // Glimmer组件基类，用于创建Ember组件
-import {formatNumber} from '../../../helpers/format-number';
+import {action} from '@ember/object';              // 动作装饰器，用于标记组件中的动作方法
-import {inject as service} from '@ember/service';
+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);
     }
-}
+}

ghost/admin/app/controllers/tag.js

@@ -1,28 +1,55 @@
 import Controller from '@ember/controller';
+// 导入删除标签模态框组件
 import DeleteTagModal from '../components/tags/delete-tag-modal';
-import {action} from '@ember/object';
+// 导入Ember动作装饰器
-import {inject} from 'ghost-admin/decorators/inject';
+import { action } from '@ember/object';
-import {inject as service} from '@ember/service';
+// 导入注入装饰器（用于注入配置）
-import {task} from 'ember-concurrency';
+import { inject } from 'ghost-admin/decorators/inject';
+// 导入服务注入工具
+import { inject as service } from '@ember/service';
+// 导入Ember并发任务工具（用于处理异步操作）
+import { task } from 'ember-concurrency';
 
+/**
+ * 标签控制器（TagController）
+ * 处理标签编辑/新建页面的交互逻辑，包括保存、删除等操作
+ */
 export default class TagController extends Controller {
+    // 注入模态框服务（用于打开删除确认弹窗）
     @service modals;
+    // 注入通知服务（用于显示操作结果提示）
     @service notifications;
+    // 注入路由服务（用于路由跳转）
     @service router;
+    // 注入标签管理服务（用于管理标签列表数据）
     @service tagsManager;
 
+    // 注入应用配置（用于获取博客基础URL等信息）
     @inject config;
 
+    /**
+     * 获取当前标签模型
+     * 简化模板中对模型的访问（this.tag 等价于 this.model）
+     * @returns {Model} 标签模型实例
+     */
     get tag() {
         return this.model;
     }
 
+    /**
+     * 计算标签的访问URL
+     * 优先使用标签的canonicalUrl，否则通过博客URL和标签slug拼接
+     * 确保URL以斜杠结尾
+     * @returns {string} 标签的完整访问URL
+     */
     get tagURL() {
-        const blogUrl = this.config.blogUrl;
+        const blogUrl = this.config.blogUrl; // 从配置中获取博客基础URL
-        const tagSlug = this.tag?.slug || '';
+        const tagSlug = this.tag?.slug || ''; // 获取标签的slug（URL别名）
 
+        // 构建标签URL：优先使用规范URL，否则拼接基础URL和slug
         let tagURL = this.tag?.canonicalUrl || `${blogUrl}/tag/${tagSlug}`;
 
+        // 确保URL以斜杠结尾（标准化URL格式）
         if (!tagURL.endsWith('/')) {
             tagURL += '/';
         }
@@ -30,35 +57,51 @@ export default class TagController extends Controller {
         return tagURL;
     }
 
+    /**
+     * 打开删除标签确认弹窗的动作
+     * 点击"删除标签"按钮时触发，显示确认弹窗并传入当前标签数据
+     */
     @action
     confirmDeleteTag() {
         return this.modals.open(DeleteTagModal, {
-            tag: this.model
+            tag: this.model // 向弹窗组件传递当前标签模型
         });
     }
 
-    @task({drop: true})
+    /**
+     * 保存标签的并发任务
+     * 处理标签的新建或编辑保存逻辑，包含错误处理和成功后的路由跳转
+     * 使用drop策略：新任务触发时，若当前任务正在运行则忽略新任务
+     */
+    @task({ drop: true })
     *saveTask() {
-        let {tag} = this;
+        let { tag } = this;
 
         try {
+            // 若标签模型存在验证错误，不执行保存操作
             if (tag.get('errors').length !== 0) {
                 return;
             }
+
+            // 记录标签是否为新建状态（用于后续逻辑区分）
             const wasNew = tag.isNew;
+            // 执行保存操作（Ember Data的save方法，返回Promise）
             yield tag.save();
 
+            // 若为新建标签，将其添加到标签列表数据中（更新缓存）
             if (wasNew) {
                 this.tagsManager.tagsScreenInfinityModel?.pushObjects([tag]);
             }
-            // replace 'new' route with 'tag' route
+
+            // 保存成功后，将"新建标签"路由替换为"标签详情"路由（避免回退到新建页）
             this.replaceRoute('tag', tag);
 
-            return tag;
+            return tag; // 返回保存后的标签模型
         } catch (error) {
+            // 保存失败时，显示API错误通知（指定key避免重复显示相同错误）
             if (error) {
-                this.notifications.showAPIError(error, {key: 'tag.save'});
+                this.notifications.showAPIError(error, { key: 'tag.save' });
             }
         }
     }
-}
+}

ghost/admin/app/controllers/tags.js

@@ -1,51 +1,93 @@
 import Controller from '@ember/controller';
-import {action} from '@ember/object';
+import { action } from '@ember/object';
-import {inject as service} from '@ember/service';
+import { inject as service } from '@ember/service';
-import {tracked} from '@glimmer/tracking';
+import { tracked } from '@glimmer/tracking';
 
+/**
+ * 标签列表控制器（TagsController）
+ * 处理标签列表页面的逻辑，包括筛选、排序、加载更多、新建标签等交互
+ */
 export default class TagsController extends Controller {
+    // 注入无限滚动服务（用于处理列表分页加载）
     @service infinity;
+    // 注入路由服务（用于页面跳转）
     @service router;
+    // 注入标签管理服务（用于标签排序等共享逻辑）
     @service tagsManager;
 
+    // 路由参数配置：将"type"作为查询参数（控制标签筛选类型）
     queryParams = ['type'];
+    // 跟踪标签筛选类型（默认筛选"公开标签"）
     @tracked type = 'public';
 
+    /**
+     * 获取标签列表数据源
+     * 简化模板中对模型的访问（this.tags 等价于 this.model）
+     * @returns {Array} 标签模型数组
+     */
     get tags() {
         return this.model;
     }
 
+    /**
+     * 获取筛选后的标签列表
+     * 1. 去重：避免新标签在分页请求后重复显示
+     * 2. 过滤：仅保留非新建、非删除状态，且符合当前筛选类型的标签
+     * @returns {Array} 去重并筛选后的标签数组
+     */
     get filteredTags() {
-        // new tags are preemptively added to the client-side tagsScreenInfinityModel,
+        // 用Map去重：以标签ID为键，确保每个标签只出现一次
-        // but if the new tag is included in a later pagination request it will end up duplicated
-        // this makes sure each tag only shows up once
         const tagMap = new Map();
         
         this.tags.forEach((tag) => {
+            // 过滤条件：
+            // - 非新建标签（!tag.isNew）
+            // - 非销毁中/已销毁状态（!tag.isDestroyed && !tag.isDestroying）
+            // - 非已删除状态（!tag.isDeleted）
+            // - 符合当前筛选类型（无筛选类型时显示全部，否则匹配visibility）
             if (!tag.isNew && !tag.isDestroyed && !tag.isDestroying && !tag.isDeleted && (!this.type || tag.visibility === this.type)) {
                 tagMap.set(tag.id, tag);
             }
         });
         
+        // 将Map的值转为数组返回（去重后的结果）
         return [...tagMap.values()];
     }
 
+    /**
+     * 获取排序后的标签列表
+     * 调用标签管理服务的排序方法，对筛选后的标签进行排序
+     * @returns {Array} 排序后的标签数组
+     */
     get sortedTags() {
         return this.tagsManager.sortTags(this.filteredTags);
     }
 
+    /**
+     * 切换标签筛选类型的动作
+     * 点击"公开标签/内部标签"按钮时触发，更新筛选类型
+     * @param {string} type - 筛选类型（"public" 或 "internal"）
+     */
     @action
     changeType(type) {
         this.type = type;
     }
 
+    /**
+     * 跳转到新建标签页面的动作
+     * 点击"New tag"按钮或按快捷键"c"时触发
+     */
     @action
     newTag() {
         this.router.transitionTo('tag.new');
     }
 
+    /**
+     * 加载更多标签的动作
+     * 滚动到列表底部时触发，通过无限滚动服务加载下一页标签
+     */
     @action
     loadMoreTags() {
         this.infinity.infinityLoad(this.model);
     }
-}
+}

ghost/admin/app/models/tag.js

@@ -1,62 +1,108 @@
-import Model, {attr} from '@ember-data/model';
+import Model, { attr } from '@ember-data/model';
+// 导入验证混入，用于为模型添加验证能力
 import ValidationEngine from 'ghost-admin/mixins/validation-engine';
-import {equal} from '@ember/object/computed';
+// 导入Ember计算属性工具，用于定义等值判断计算属性
-import {inject as service} from '@ember/service';
+import { equal } from '@ember/object/computed';
+// 导入Ember服务注入工具，用于注入依赖服务
+import { inject as service } from '@ember/service';
 
+/**
+ * 标签（Tag）模型
+ * 继承自Ember Data的基础Model，集成验证能力，用于描述标签的属性和行为
+ * 对应后端标签数据，支持属性管理、可见性控制、搜索缓存更新等功能
+ */
 export default Model.extend(ValidationEngine, {
+    // 注入搜索服务，用于操作搜索缓存
     search: service(),
+    // 注入特性服务，用于特性开关控制（当前未在方法中使用，预留扩展）
+    feature: service(),
 
+    // 指定验证规则类型，对应后端/前端的"tag"验证配置
     validationType: 'tag',
 
-    name: attr('string'),
+    // ------------------------------
-    slug: attr('string'),
+    // 标签核心属性（与后端字段对应）
-    url: attr('string'),
+    // ------------------------------
-    description: attr('string'),
+    name: attr('string'), // 标签名称（必填，如"技术"）
-    metaTitle: attr('string'),
+    slug: attr('string'), // 标签URL别名（如"tech"，用于生成友好URL）
-    metaDescription: attr('string'),
+    url: attr('string'), // 标签完整URL（如"https://xxx.com/tag/tech"）
-    twitterImage: attr('string'),
+    description: attr('string'), // 标签描述（可选）
-    twitterTitle: attr('string'),
+    metaTitle: attr('string'), // 标签SEO标题（可选，用于页面<head>的title标签）
-    twitterDescription: attr('string'),
+    metaDescription: attr('string'), // 标签SEO描述（可选，用于页面<head>的meta description）
-    ogImage: attr('string'),
+    // 社交媒体（Twitter）相关属性
-    ogTitle: attr('string'),
+    twitterImage: attr('string'), // Twitter分享时的封面图URL
-    ogDescription: attr('string'),
+    twitterTitle: attr('string'), // Twitter分享标题
-    codeinjectionHead: attr('string'),
+    twitterDescription: attr('string'), // Twitter分享描述
-    codeinjectionFoot: attr('string'),
+    // 社交媒体（Open Graph）相关属性
-    canonicalUrl: attr('string'),
+    ogImage: attr('string'), // OG分享时的封面图URL
-    accentColor: attr('string'),
+    ogTitle: attr('string'), // OG分享标题
-    featureImage: attr('string'),
+    ogDescription: attr('string'), // OG分享描述
-    visibility: attr('string', {defaultValue: 'public'}),
+    // 代码注入相关属性（用于在标签页注入自定义脚本/样式）
-    createdAtUTC: attr('moment-utc'),
+    codeinjectionHead: attr('string'), // 注入到<head>的代码
-    updatedAtUTC: attr('moment-utc'),
+    codeinjectionFoot: attr('string'), // 注入到</body>前的代码
-    count: attr('raw'),
+    canonicalUrl: attr('string'), // 标签页规范URL（用于SEO，避免重复内容）
+    accentColor: attr('string'), // 标签强调色（用于前端样式渲染）
+    featureImage: attr('string'), // 标签封面图URL
+    // 标签可见性（默认"public"公开，可选"internal"内部）
+    visibility: attr('string', { defaultValue: 'public' }),
+    createdAtUTC: attr('moment-utc'), // 标签创建时间（UTC时区，moment对象）
+    updatedAtUTC: attr('moment-utc'), // 标签更新时间（UTC时区，moment对象）
+    count: attr('raw'), // 标签关联内容数量（原始数据，如{posts: 10}表示关联10篇文章）
 
+    // ------------------------------
+    // 计算属性（基于基础属性派生）
+    // ------------------------------
+    // 判断标签是否为"内部可见"（visibility === 'internal'）
     isInternal: equal('visibility', 'internal'),
+    // 判断标签是否为"公开可见"（visibility === 'public'）
     isPublic: equal('visibility', 'public'),
 
-    feature: service(),
+    // ------------------------------
-
+    // 标签行为方法
+    // ------------------------------
+    /**
+     * 更新标签可见性
+     * 根据标签名称是否以"#"开头，自动设置可见性：
+     * - 以"#"开头 → "internal"（内部标签，仅管理员可见）
+     * - 其他情况 → "public"（公开标签，前端可展示）
+     */
     updateVisibility() {
+        // 正则表达式：匹配以"#"开头的名称（支持"#"后紧跟其他字符，如"#内部标签"）
         let internalRegex = /^#.?/;
         this.set('visibility', internalRegex.test(this.name) ? 'internal' : 'public');
     },
 
+    /**
+     * 重写模型默认save方法
+     * 扩展功能：
+     * 1. 名称变更时自动更新可见性
+     * 2. 名称/URL变更或标签删除时，清理搜索缓存
+     * @returns {Promise<Model>} 保存成功后的模型实例
+     */
     save() {
+        // 判断标签名称是否有变更（changedAttributes()返回变更的属性键值对）
         const nameChanged = !!this.changedAttributes().name;
 
+        // 若名称变更且标签未被删除，更新可见性
         if (nameChanged && !this.isDeleted) {
             this.updateVisibility();
         }
 
-        const {url} = this;
+        // 保存当前URL（用于后续判断URL是否变更）
+        const { url } = this;
 
+        // 调用父类save方法执行实际保存，返回Promise
         return this._super(...arguments).then((savedModel) => {
+            // 判断保存后URL是否变更（与保存前对比）
             const urlChanged = url !== savedModel.url;
 
+            // 若名称变更、URL变更或标签被删除，清理搜索服务的内容缓存
             if (nameChanged || urlChanged || this.isDeleted) {
                 this.search.expireContent();
             }
 
+            // 返回保存后的模型实例
             return savedModel;
         });
     }
-});
+});

ghost/admin/app/routes/tag.js

@@ -1,18 +1,30 @@
-import * as Sentry from '@sentry/ember';
+import * as Sentry from '@sentry/ember'; // Sentry错误跟踪工具
-import AuthenticatedRoute from 'ghost-admin/routes/authenticated';
+import AuthenticatedRoute from 'ghost-admin/routes/authenticated'; // 已认证路由基类（需要登录）
-import ConfirmUnsavedChangesModal from '../components/modals/confirm-unsaved-changes';
+import ConfirmUnsavedChangesModal from '../components/modals/confirm-unsaved-changes'; // 未保存更改确认弹窗
-import {action} from '@ember/object';
+import { action } from '@ember/object'; // Ember动作装饰器
-import {inject as service} from '@ember/service';
+import { inject as service } from '@ember/service'; // 服务注入工具
-
+
+/**
+ * 标签路由（TagRoute）
+ * 处理标签的查看、编辑和新建功能，继承自需要登录的路由基类
+ * 包含权限控制、数据加载、未保存更改确认等逻辑
+ */
 export default class TagRoute extends AuthenticatedRoute {
+    // 注入模态框服务（用于打开确认弹窗）
     @service modals;
+    // 注入路由服务（用于路由跳转）
     @service router;
+    // 注入会话服务（用于获取当前用户信息）
     @service session;
 
-    // ensures if a tag model is passed in directly we show it immediately
+    // 标记是否需要在后台刷新数据（用于直接传入标签模型时的场景）
-    // and refresh in the background
     _requiresBackgroundRefresh = true;
 
+    /**
+     * 路由进入前的钩子
+     * 先执行父类的beforeModel逻辑（验证登录状态等）
+     * 然后检查用户权限：如果是作者或贡献者，不允许访问标签管理，跳转到首页
+     */
     beforeModel() {
         super.beforeModel(...arguments);
 
@@ -21,73 +33,114 @@ export default class TagRoute extends AuthenticatedRoute {
         }
     }
 
+    /**
+     * 加载路由模型数据
+     * @param {Object} params - 路由参数
+     * @returns {Promise} 标签模型实例
+     */
     model(params) {
-        this._requiresBackgroundRefresh = false;
+        this._requiresBackgroundRefresh = false; // 重置后台刷新标记
 
         if (params.tag_slug) {
-            return this.store.queryRecord('tag', {slug: params.tag_slug});
+            // 如果有标签slug参数，查询对应的标签记录
+            return this.store.queryRecord('tag', { slug: params.tag_slug });
         } else {
+            // 没有slug参数，创建一个新的标签记录（用于新建标签）
             return this.store.createRecord('tag');
         }
     }
 
+    /**
+     * 序列化模型数据为路由参数
+     * 用于生成带标签slug的URL
+     * @param {Model} tag - 标签模型实例
+     * @returns {Object} 路由参数对象
+     */
     serialize(tag) {
-        return {tag_slug: tag.get('slug')};
+        return { tag_slug: tag.get('slug') };
     }
 
+    /**
+     * 设置控制器数据
+     * 在控制器中准备好模型数据，供模板使用
+     * @param {Controller} controller - 对应的控制器实例
+     * @param {Model} tag - 标签模型实例
+     */
     setupController(controller, tag) {
         super.setupController(...arguments);
 
+        // 如果需要后台刷新，重新加载标签数据（用于直接传入模型时的场景）
         if (this._requiresBackgroundRefresh) {
             tag.reload();
         }
     }
 
+    /**
+     * 路由离开时的钩子
+     * 重置相关状态，清理确认弹窗引用
+     */
     deactivate() {
-        this._requiresBackgroundRefresh = true;
+        this._requiresBackgroundRefresh = true; // 恢复后台刷新标记
 
-        this.confirmModal = null;
+        this.confirmModal = null; // 清空弹窗引用
-        this.hasConfirmed = false;
+        this.hasConfirmed = false; // 重置确认状态
     }
 
+    /**
+     * 路由切换前的动作（Ember动作）
+     * 处理未保存更改的确认逻辑，防止用户意外丢失数据
+     * @param {Transition} transition - 路由切换对象
+     */
     @action
     async willTransition(transition) {
+        // 如果已经确认离开，直接允许切换
         if (this.hasConfirmed) {
             return true;
         }
 
+        // 先中断当前切换
         transition.abort();
 
-        // wait for any existing confirm modal to be closed before allowing transition
+        // 如果已有确认弹窗打开，等待其关闭后再处理
         if (this.confirmModal) {
             return;
         }
 
+        // 如果正在保存标签，等待保存完成
         if (this.controller.saveTask?.isRunning) {
             await this.controller.saveTask.last;
         }
 
+        // 确认是否允许离开（检查是否有未保存的更改）
         const shouldLeave = await this.confirmUnsavedChanges();
 
         if (shouldLeave) {
+            // 放弃未保存的更改，标记已确认，重试路由切换
             this.controller.model.rollbackAttributes();
             this.hasConfirmed = true;
             return transition.retry();
         }
     }
 
+    /**
+     * 确认未保存的更改
+     * 如果模型有未保存的属性，显示确认弹窗；否则直接允许离开
+     * @returns {Promise<boolean>} 是否允许离开的Promise
+     */
     async confirmUnsavedChanges() {
         if (this.controller.model?.hasDirtyAttributes) {
+            // 有未保存的更改，记录Sentry日志并打开确认弹窗
             Sentry.captureMessage('showing unsaved changes modal for tags route');
             this.confirmModal = this.modals
                 .open(ConfirmUnsavedChangesModal)
                 .finally(() => {
-                    this.confirmModal = null;
+                    this.confirmModal = null; // 弹窗关闭后清空引用
                 });
 
-            return this.confirmModal;
+            return this.confirmModal; // 返回弹窗的结果（用户是否确认离开）
         }
 
+        // 没有未保存的更改，直接允许离开
         return true;
     }
-}
+}

ghost/admin/app/routes/tag/new.js

@@ -1,6 +1,12 @@
 import TagRoute from '../tag';
 
+/**
+ * 新建标签路由（NewRoute）
+ * 继承自标签路由（TagRoute），用于处理新建标签的页面逻辑
+ * 复用标签路由的控制器和模板，简化新建标签功能的实现
+ */
 export default class NewRoute extends TagRoute {
+    // 指定使用的控制器名称为'tag'，复用标签控制器的逻辑
     controllerName = 'tag';
-    templateName = 'tag';
+    // 指定使用的模板名称为'tag'，复用标签页面的模板
-}
+}

ghost/admin/app/routes/tags.js

@@ -1,17 +1,35 @@
 import AuthenticatedRoute from 'ghost-admin/routes/authenticated';
-import {inject as service} from '@ember/service';
+import { inject as service } from '@ember/service';
 
-const CACHE_TIME = 1000 * 60 * 5; // 5 minutes
+// 数据缓存时间：5分钟（用于控制无限滚动数据的缓存有效期）
+const CACHE_TIME = 1000 * 60 * 5;
 
+/**
+ * 标签列表路由（TagsRoute）
+ * 继承自已认证路由基类，用于处理标签列表页面的逻辑
+ * 支持权限控制、数据分页加载、特性开关适配等功能
+ */
 export default class TagsRoute extends AuthenticatedRoute {
+    // 注入无限滚动服务（用于实现标签列表的分页加载）
     @service infinity;
+    // 注入标签管理服务（用于存储和共享标签列表数据）
     @service tagsManager;
+    // 注入特性开关服务（用于控制新旧标签页面的切换）
     @service feature;
 
+    /**
+     * 动态指定模板名称
+     * 根据特性开关"tagsX"决定使用新模板（tags-x）还是旧模板（tags）
+     * @returns {string} 模板名称
+     */
     get templateName() {
         return this.feature.tagsX ? 'tags-x' : 'tags';
     }
 
+    /**
+     * 路由参数配置
+     * 当"type"参数变化时，刷新模型数据，并替换历史记录（避免回退时重复显示）
+     */
     queryParams = {
         type: {
             refreshModel: true,
@@ -19,7 +37,11 @@ export default class TagsRoute extends AuthenticatedRoute {
         }
     };
 
-    // authors aren't allowed to manage tags
+    /**
+     * 路由进入前的钩子
+     * 先执行父类的权限验证（确保用户已登录）
+     * 然后检查用户权限：作者或贡献者不允许访问标签管理，自动跳转到首页
+     */
     beforeModel() {
         super.beforeModel(...arguments);
 
@@ -28,41 +50,62 @@ export default class TagsRoute extends AuthenticatedRoute {
         }
     }
 
+    /**
+     * 加载路由模型数据
+     * @param {Object} params - 路由参数（包含type筛选条件）
+     * @returns {Promise} 标签列表数据（无限滚动模型）
+     */
     model(params) {
+        // 如果启用新标签页面特性，暂时返回null（由新页面自行处理数据加载）
         if (this.feature.tagsX) {
             return null;
         }
         
+        // 构建筛选参数（根据type参数筛选标签可见性）
         const filterParams = {
             visibility: params.type
         };
 
+        // 构建分页参数
         const paginationParams = {
-            perPage: 100,
+            perPage: 100, // 每页加载100条标签
-            perPageParam: 'limit',
+            perPageParam: 'limit', // 后端接收的每页数量参数名
-            totalPagesParam: 'meta.pagination.pages',
+            totalPagesParam: 'meta.pagination.pages', // 后端返回的总页数字段路径
-            order: 'name asc',
+            order: 'name asc', // 按名称升序排序
-            include: 'count.posts'
+            include: 'count.posts' // 关联加载标签下的文章数量
         };
 
+        // 使用无限滚动服务加载标签数据，并缓存到标签管理服务中
         this.tagsManager.tagsScreenInfinityModel = this.infinity.model('tag', {
             ...paginationParams,
-            filter: this._filterString({...filterParams}),
+            filter: this._filterString({...filterParams}), // 转换筛选参数为后端需要的格式
-            infinityCache: CACHE_TIME
+            infinityCache: CACHE_TIME // 设置数据缓存时间
         });
 
+        // 返回加载的标签列表数据
         return this.tagsManager.tagsScreenInfinityModel;
     }
 
+    /**
+     * 构建路由信息元数据
+     * 用于设置页面标题等信息
+     * @returns {Object} 包含标题令牌的元数据
+     */
     buildRouteInfoMetadata() {
         return {
-            titleToken: 'Tags'
+            titleToken: 'Tags' // 页面标题为"Tags"
         };
     }
 
+    /**
+     * 将筛选参数转换为后端API需要的字符串格式
+     * 例如：{visibility: 'public'} → "visibility:public"
+     * @param {Object} filter - 筛选参数对象
+     * @returns {string} 格式化后的筛选字符串
+     */
     _filterString(filter) {
-        return Object.entries(filter).map(([key, value]) => {
+        return Object.entries(filter)
-            return `${key}:${value}`;
+            .map(([key, value]) => `${key}:${value}`) // 键值对转换为"key:value"格式
-        }).join(',');
+            .join(','); // 多个筛选条件用逗号分隔
     }
-}
+}

ghost/admin/app/serializers/label.js

@@ -1,34 +1,64 @@
 /* eslint-disable camelcase */
-import ApplicationSerializer from './application';
+import ApplicationSerializer from './application'; // 导入应用程序基础序列化器
-import {pluralize} from 'ember-inflector';
+import { pluralize } from 'ember-inflector'; // 导入单复数转换工具函数
 
+/**
+ * 标签（Label）序列化器
+ * 继承自应用程序基础序列化器，用于处理Label模型与后端API数据的序列化/反序列化
+ * 负责在前端模型和后端数据格式之间进行转换，确保数据交互的一致性
+ */
 export default class LabelSerializer extends ApplicationSerializer {
+    /**
+     * 属性映射配置
+     * 定义前端模型属性与后端API字段的对应关系
+     */
     attrs = {
-        createdAtUTC: {key: 'created_at'},
+        createdAtUTC: { key: 'created_at' }, // 前端createdAtUTC属性对应后端created_at字段
-        updatedAtUTC: {key: 'updated_at'}
+        updatedAtUTC: { key: 'updated_at' }  // 前端updatedAtUTC属性对应后端updated_at字段
     };
 
+    /**
+     * 序列化方法
+     * 将前端Label模型实例转换为后端API可接受的JSON格式
+     * @param {Snapshot} snapshot - 模型快照（包含模型当前属性数据）
+     * @param {Object} options - 序列化选项（可选）
+     * @returns {Object} 处理后的JSON数据
+     */
     serialize(/*snapshot, options*/) {
+        // 调用父类的序列化方法获取基础JSON数据
         let json = super.serialize(...arguments);
 
-        // Properties that exist on the model but we don't want sent in the payload
+        // 移除不需要发送到后端的属性：
+        // count属性由后端计算，前端无需提交
         delete json.count;
 
         return json;
     }
 
-    // if we use `queryRecord` ensure we grab the first record to avoid
+    /**
-    // DS.SERIALIZER.REST.QUERYRECORD-ARRAY-RESPONSE deprecations
+     * 反序列化响应数据
+     * 将后端API返回的原始数据转换为前端模型可识别的格式
+     * @param {Store} store - 数据存储实例
+     * @param {Model} primaryModelClass - 主模型类（此处为Label）
+     * @param {Object} payload - 后端返回的原始数据
+     * @param {string} id - 模型ID
+     * @param {string} requestType - 请求类型（如find、queryRecord等）
+     * @returns {Object} 标准化后的数据（供前端模型使用）
+     */
     normalizeResponse(store, primaryModelClass, payload, id, requestType) {
+        // 处理queryRecord请求（查询单条记录）的响应格式
         if (requestType === 'queryRecord') {
-            let singular = primaryModelClass.modelName;
+            const singular = primaryModelClass.modelName; // 模型单数名称（如"label"）
-            let plural = pluralize(singular);
+            const plural = pluralize(singular); // 模型复数名称（如"labels"）
 
+            // 后端可能返回复数形式的数组（如{labels: [{...}]}），需转换为单数形式
             if (payload[plural]) {
-                payload[singular] = payload[plural][0];
+                payload[singular] = payload[plural][0]; // 取数组第一个元素作为单条记录
-                delete payload[plural];
+                delete payload[plural]; // 移除复数字段，避免序列化警告
             }
         }
+
+        // 调用父类方法完成最终的标准化处理
         return super.normalizeResponse(...arguments);
     }
-}
+}

ghost/admin/app/serializers/tag.js

@@ -1,35 +1,66 @@
 /* eslint-disable camelcase */
 import ApplicationSerializer from 'ghost-admin/serializers/application';
-import {pluralize} from 'ember-inflector';
+import { pluralize } from 'ember-inflector'; // 用于模型名称单复数转换的工具
 
+/**
+ * 标签序列化器（TagSerializer）
+ * 继承自应用程序基础序列化器，用于处理标签(Tag)模型与API数据的序列化/反序列化
+ * 负责在前端模型与后端API数据格式之间进行转换
+ */
 export default class TagSerializer extends ApplicationSerializer {
+    /**
+     * 属性映射配置
+     * 定义前端模型属性与后端API字段的对应关系
+     */
     attrs = {
-        createdAtUTC: {key: 'created_at'},
+        createdAtUTC: { key: 'created_at' }, // 前端createdAtUTC属性对应后端created_at字段
-        updatedAtUTC: {key: 'updated_at'}
+        updatedAtUTC: { key: 'updated_at' }  // 前端updatedAtUTC属性对应后端updated_at字段
     };
 
+    /**
+     * 序列化方法
+     * 将前端标签模型转换为后端API所需的JSON格式
+     * @param {Snapshot} snapshot - 模型快照（包含模型当前属性数据）
+     * @param {Object} options - 序列化选项（可选）
+     * @returns {Object} 处理后的JSON数据
+     */
     serialize(/*snapshot, options*/) {
+        // 调用父类序列化方法获取基础JSON数据
         let json = super.serialize(...arguments);
 
-        // Properties that exist on the model but we don't want sent in the payload
+        // 移除不需要发送到后端的属性：
+        // - count：标签关联内容数量（由后端计算，前端无需提交）
+        // - url：标签URL（由后端生成，前端无需提交）
         delete json.count;
         delete json.url;
 
         return json;
     }
 
-    // if we use `queryRecord` ensure we grab the first record to avoid
+    /**
-    // DS.SERIALIZER.REST.QUERYRECORD-ARRAY-RESPONSE deprecations
+     * 反序列化响应数据
+     * 将后端API返回的JSON转换为前端模型可识别的格式
+     * @param {Store} store - 数据存储实例
+     * @param {Model} primaryModelClass - 主模型类（此处为Tag）
+     * @param {Object} payload - 后端返回的原始数据
+     * @param {string} id - 模型ID
+     * @param {string} requestType - 请求类型（如find、queryRecord等）
+     * @returns {Object} 标准化后的数据（供前端模型使用）
+     */
     normalizeResponse(store, primaryModelClass, payload, id, requestType) {
+        // 处理queryRecord请求（根据条件查询单条记录）的响应
         if (requestType === 'queryRecord') {
-            let singular = primaryModelClass.modelName;
+            const singular = primaryModelClass.modelName; // 模型单数名称（如"tag"）
-            let plural = pluralize(singular);
+            const plural = pluralize(singular); // 模型复数名称（如"tags"）
 
+            // 后端可能返回复数形式的数组（如{tags: [{...}]}），需转换为单数形式
             if (payload[plural]) {
-                payload[singular] = payload[plural][0];
+                payload[singular] = payload[plural][0]; // 取数组第一个元素作为单条记录
-                delete payload[plural];
+                delete payload[plural]; // 移除复数字段，避免序列化警告
             }
         }
+
+        // 调用父类方法完成最终的标准化处理
         return super.normalizeResponse(...arguments);
     }
-}
+}

ghost/admin/app/templates/tag.hbs

@@ -1,38 +1,100 @@
+{{! 标签编辑/新建页面的主模板，同时支持新建标签和编辑已有标签的功能 }}
+{{! section标签：语义化HTML元素，用于划分页面独立区域 }}
+{{! gh-canvas：Ghost CMS的核心样式类，定义页面基础布局（宽度、边距等），保证后台界面风格统一 }}
 <section class="gh-canvas">
+    {{! form标签：语义化表单容器，虽未绑定提交事件，但用于包裹所有表单元素，便于后续扩展验证逻辑 }}
+    {{! mb15：自定义样式类，设置margin-bottom:15px，与下方删除按钮保持间距 }}
     <form class="mb15">
+        {{! 页面头部区域：包含面包屑导航、页面标题和操作按钮 }}
+        {{! GhCanvasHeader：Ghost的通用头部组件，封装了后台页面的标准化头部布局 }}
+        {{! gh-canvas-header：为头部组件添加的样式类，控制内边距和边框等细节 }}
         <GhCanvasHeader class="gh-canvas-header">
             <div class="flex flex-column">
+                {{! 面包屑导航：显示用户当前位置，提供返回上级页面的入口 }}
+                {{! gh-canvas-breadcrumb：面包屑导航样式类，控制文字大小、间距和颜色 }}
                 <div class="gh-canvas-breadcrumb">
+                    {{! LinkTo：Ember框架的路由链接组件，用于页面间跳转 }}
+                    {{! @route="tags"：指定跳转的路由为标签列表页 }}
+                    {{! data-test-link="tags-back"：测试标识，供自动化测试工具定位该元素 }}
                     <LinkTo @route="tags" data-test-link="tags-back">
                         Tags
                     </LinkTo>
-                    {{svg-jar "arrow-right-small"}} {{if this.tag.isNew "New tag" "Edit tag"}}
+                    {{! svg-jar：引入SVG图标组件，"arrow-right-small"是图标名称 }}
+                    {{! 作用：作为面包屑导航的分隔符，增强视觉层级 }}
+                    {{svg-jar "arrow-right-small"}} {{! 箭头图标，分隔面包屑导航项 }}
+                    {{! if条件渲染：根据标签状态动态显示文本 }}
+                    {{! this.tag.isNew：组件逻辑中的属性，判断标签是否为新创建（未保存） }}
+                    {{! 新建标签时显示"New tag"，编辑时显示"Edit tag" }}
+                    {{if this.tag.isNew "New tag" "Edit tag"}}
                 </div>
+                
+                {{! 页面标题：明确当前页面的核心内容 }}
+                {{! gh-canvas-title：标题样式类，通常为大字号、粗体，突出显示页面主题 }}
+                {{! data-test-screen-title：测试标识，用于验证页面标题是否正确渲染 }}
                 <h2 class="gh-canvas-title" data-test-screen-title>
+                    {{! 动态标题：新建时显示"New tag"，编辑时显示标签名称 }}
                     {{if this.tag.isNew "New tag" this.tag.name}}
                 </h2>
             </div>
 
+            {{! 操作按钮区域：集中展示页面的核心功能按钮 }}
+            {{! view-actions：Ghost的操作按钮容器样式类，通常位于页面右上角 }}
             <section class="view-actions">
+                {{! view-actions-bottom-row：控制按钮行的布局（水平排列、间距等） }}
                 <div class="view-actions-bottom-row">
-                    <a href={{this.tagURL}} target="_blank" rel="noopener noreferrer" class="gh-btn gh-btn-icon-right gh-btn-action-icon"><span>View{{svg-jar "arrow-top-right"}}</span></a>
+                    {{! 查看标签按钮：在新窗口打开标签的前端页面，方便预览效果 }}
+                    {{! href={{this.tagURL}}：this.tagURL是组件逻辑计算的标签访问URL }}
+                    {{! target="_blank"：在新窗口打开链接 }}
+                    {{! rel="noopener noreferrer"：安全属性，防止新窗口劫持原页面 }}
+                    {{! gh-btn：基础按钮样式；gh-btn-icon-right：图标在文字右侧的样式；gh-btn-action-icon：辅助操作按钮样式（灰色） }}
+                    <a 
+                        href={{this.tagURL}} 
+                        target="_blank" 
+                        rel="noopener noreferrer" 
+                        class="gh-btn gh-btn-icon-right gh-btn-action-icon"
+                    >
+                        {{! 按钮文本+图标："View"提示功能，箭头图标表示外部链接 }}
+                        <span>View{{svg-jar "arrow-top-right"}}</span> {{! 包含"View"文本和外部链接图标 }}
+                    </a>
+                    
+                    {{! 保存按钮：用于提交标签数据（新建或更新） }}
+                    {{! GhTaskButton：Ghost的任务按钮组件，专门绑定异步任务，支持加载状态显示 }}
+                    {{! @task={{this.saveTask}}：绑定组件中的saveTask异步任务（负责保存标签数据到服务器） }}
+                    {{! @type="button"：指定按钮类型为button，避免触发表单默认提交 }}
+                    {{! gh-btn-primary：主要操作按钮样式（通常为蓝色），突出显示核心功能 }}
+                    {{! @data-test-button="save"：测试标识，用于验证保存按钮功能 }}
+                    {{! on-key "cmd+s"：绑定快捷键，按下Command+S（Mac）或Ctrl+S（Windows）触发保存 }}
                     <GhTaskButton
                         @task={{this.saveTask}}
                         @type="button"
                         @class="gh-btn gh-btn-primary gh-btn-icon"
                         @data-test-button="save"
-                        {{on-key "cmd+s"}}
+                        {{on-key "cmd+s"}} {{! 绑定快捷键：Command+S保存 }}
                     />
                 </div>
             </section>
         </GhCanvasHeader>
 
+        {{! 标签表单组件：负责渲染标签的具体编辑字段（名称、颜色、描述等） }}
+        {{! Tags::TagForm：自定义组件，路径为app/components/tags/tag-form }}
+        {{! @tag={{this.model}}：通过参数传递标签数据模型（Ember Data对象），表单基于此渲染和更新数据 }}
         <Tags::TagForm @tag={{this.model}} />
     </form>
 
+    {{! 删除按钮：仅在编辑现有标签时显示（新建标签无删除意义） }}
+    {{! unless条件渲染：等同于"如果不满足条件则渲染"，this.tag.isNew为false时显示（即编辑状态） }}
     {{#unless this.tag.isNew}}
         <div>
-            <button type="button" class="gh-btn gh-btn-red gh-btn-icon" {{on "click" this.confirmDeleteTag}} data-test-button="delete-tag">
+            {{! 按钮类型为button，避免触发表单提交 }}
+            {{! gh-btn-red：红色按钮样式，视觉警示用户这是危险操作（删除不可恢复） }}
+            {{! on "click" this.confirmDeleteTag：点击事件绑定，触发删除确认流程（通常弹出模态框） }}
+            {{! data-test-button="delete-tag"：测试标识，用于验证删除按钮功能 }}
+            <button 
+                type="button" 
+                class="gh-btn gh-btn-red gh-btn-icon" 
+                {{on "click" this.confirmDeleteTag}} {{! 点击触发删除确认流程 }}
+                data-test-button="delete-tag"
+            >
                 <span>Delete tag</span>
             </button>
         </div>

ghost/admin/app/templates/tags-loading.hbs

@@ -1,12 +1,25 @@
+{{! 标签列表页面模板 }}
 <section class="gh-canvas">
+    {{! 页面头部区域：包含标题和操作按钮，设置为粘性定位（滚动时保持在顶部） }}
     <GhCanvasHeader class="gh-canvas-header sticky">
+        {{! 页面标题：显示"Tags"，用于测试标识 }}
         <h2 class="gh-canvas-title" data-test-screen-title>Tags</h2>
+        
+        {{! 操作按钮区域 }}
         <section class="view-actions">
-            <LinkTo @route="tag.new" class="gh-btn gh-btn-primary" data-test-button="new-tag"><span>New tag</span></LinkTo>
+            {{! 新建标签按钮：链接到标签新建路由，包含测试标识 }}
+            <LinkTo 
+                @route="tag.new" 
+                class="gh-btn gh-btn-primary" 
+                data-test-button="new-tag"
+            >
+                <span>New tag</span>
+            </LinkTo>
         </section>
     </GhCanvasHeader>
 
+    {{! 内容区域：显示加载状态指示器 }}
     <div class="gh-content">
-        <GhLoadingSpinner />
+        <GhLoadingSpinner /> {{! 加载动画组件，数据加载完成前显示 }}
     </div>
-</section>
+</section>

ghost/admin/app/templates/tags-x.hbs

@@ -1 +1,3 @@
+{{! AdminX 后台的文章管理组件入口 }}
+{{! 用于在 AdminX 界面中嵌入完整的文章管理功能模块 }}
 <AdminX::Posts />

ghost/admin/app/templates/tags.hbs

@@ -1,42 +1,84 @@
+{{! 标签列表页面（带筛选功能）模板 }}
+{{! 绑定快捷键 "c"，触发新建标签操作 }}
 <section class="gh-canvas" {{on-key "c" this.newTag}}>
+    {{! 页面头部（粘性定位，滚动时保持在顶部） }}
     <GhCanvasHeader class="gh-canvas-header sticky">
+        {{! 页面标题：显示"Tags"，用于自动化测试标识 }}
         <h2 class="gh-canvas-title" data-test-screen-title>Tags</h2>
+        
+        {{! 操作按钮与筛选区域 }}
         <section class="view-actions">
+            {{! 标签类型筛选按钮组：切换显示"公开标签"和"内部标签" }}
             <div class="gh-contentfilter gh-btn-group">
-                <button class="gh-btn {{if (eq this.type "public") "gh-btn-group-selected"}}" type="button" {{action "changeType" "public"}} data-test-tags-nav="public" data-test-active={{eq this.type "public"}}><span>Public tags</span></button>
+                {{! 公开标签筛选按钮：点击切换到公开标签列表，选中时显示高亮样式 }}
-                <button class="gh-btn {{if (eq this.type "internal") "gh-btn-group-selected"}}" type="button" {{action "changeType" "internal"}} data-test-tags-nav="internal" data-test-active={{eq this.type "internal"}}><span>Internal tags</span></button>
+                <button 
+                    class="gh-btn {{if (eq this.type "public") "gh-btn-group-selected"}}" 
+                    type="button" 
+                    {{action "changeType" "public"}} 
+                    data-test-tags-nav="public" 
+                    data-test-active={{eq this.type "public"}}
+                >
+                    <span>Public tags</span>
+                </button>
+                {{! 内部标签筛选按钮：点击切换到内部标签列表，选中时显示高亮样式 }}
+                <button 
+                    class="gh-btn {{if (eq this.type "internal") "gh-btn-group-selected"}}" 
+                    type="button" 
+                    {{action "changeType" "internal"}} 
+                    data-test-tags-nav="internal" 
+                    data-test-active={{eq this.type "internal"}}
+                >
+                    <span>Internal tags</span>
+                </button>
             </div>
-            <LinkTo @route="tag.new" class="gh-btn gh-btn-primary" data-test-button="new-tag"><span>New tag</span></LinkTo>
+
+            {{! 新建标签按钮：点击跳转到标签新建路由 }}
+            <LinkTo 
+                @route="tag.new" 
+                class="gh-btn gh-btn-primary" 
+                data-test-button="new-tag"
+            >
+                <span>New tag</span>
+            </LinkTo>
         </section>
     </GhCanvasHeader>
 
+    {{! 标签列表内容容器 }}
     <section class="view-container content-list">
         <ol class="tags-list gh-list {{unless this.sortedTags "no-posts"}}">
+            {{! 有标签数据时，渲染列表头部和标签项 }}
             {{#if this.sortedTags}}
+                {{! 列表头部：定义列标题和宽度占比 }}
                 <li class="gh-list-row header">
-                    <div class="gh-list-header gh-list-cellwidth-70">Tag</div>
+                    <div class="gh-list-header gh-list-cellwidth-70">Tag</div> {{! 标签名称列（占70%宽度） }}
-                    <div class="gh-list-header gh-list-cellwidth-10">Slug</div>
+                    <div class="gh-list-header gh-list-cellwidth-10">Slug</div> {{! 标签别名列（占10%宽度） }}
-                    <div class="gh-list-header gh-list-cellwidth-10">No. of posts</div>
+                    <div class="gh-list-header gh-list-cellwidth-10">No. of posts</div> {{! 关联文章数列（占10%宽度） }}
-                    <div class="gh-list-header gh-list-cellwidth-10"></div>
+                    <div class="gh-list-header gh-list-cellwidth-10"></div> {{! 空列（预留操作区域，占10%宽度） }}
                 </li>
+
+                {{! 虚拟滚动列表组件：高效渲染大量标签，支持滚动加载更多 }}
                 <VerticalCollection
-                    @items={{this.sortedTags}}
+                    @items={{this.sortedTags}} {{! 数据源：已排序的标签列表 }}
-                    @key="id"
+                    @key="id" {{! 每个标签的唯一标识字段 }}
-                    @containerSelector=".gh-main"
+                    @containerSelector=".gh-main" {{! 滚动容器选择器 }}
-                    @estimateHeight={{60}}
+                    @estimateHeight={{60}} {{! 每个列表项的预估高度（用于虚拟滚动计算） }}
-                    @bufferSize={{20}}
+                    @bufferSize={{20}} {{! 滚动时预加载的列表项数量 }}
-                    @lastReached={{this.loadMoreTags}}
+                    @lastReached={{this.loadMoreTags}} {{! 滚动到底部时触发的"加载更多"方法 }}
                 as |tag|>
+                    {{! 单个标签列表项组件：传入当前标签数据 }}
                     <Tags::ListItem @tag={{tag}} data-test-tag={{tag.id}} />
                 </VerticalCollection>
+            
+            {{! 无标签数据时，显示空状态提示 }}
             {{else}}
                 <li class="no-posts-box">
                     <div class="no-posts">
-                            {{svg-jar "tags-placeholder" class="gh-tags-placeholder"}}
+                        {{svg-jar "tags-placeholder" class="gh-tags-placeholder"}} {{! 标签占位图标 }}
-                            <h4>Start organizing your content.</h4>
+                        <h4>Start organizing your content.</h4> {{! 空状态提示文本 }}
-                            <LinkTo @route="tag.new" class="gh-btn gh-btn-green">
+                        {{! 新建标签按钮：引导用户创建第一个标签 }}
-                                <span>Create a new tag</span>
+                        <LinkTo @route="tag.new" class="gh-btn gh-btn-green">
-                            </LinkTo>
+                            <span>Create a new tag</span>
+                        </LinkTo>
                     </div>
                 </li>
             {{/if}}
@@ -44,4 +86,5 @@
     </section>
 </section>
 
+{{! 路由出口：用于渲染子路由内容（如标签详情、新建标签等，当前模板为父路由时生效） }}
 {{outlet}}

ghost/admin/config/targets.js

@@ -1,12 +1,18 @@
 /* eslint-env node */
 
+/**
+ * 浏览器兼容性配置
+ * 用于指定项目需要支持的浏览器版本范围
+ * 通常被Babel、Autoprefixer等工具使用，以生成兼容的代码
+ */
 const browsers = [
-    'last 2 Chrome versions',
+    'last 2 Chrome versions', // 支持Chrome最新的2个版本
-    'last 2 Firefox versions',
+    'last 2 Firefox versions', // 支持Firefox最新的2个版本
-    'last 3 Safari versions',
+    'last 3 Safari versions', // 支持Safari最新的3个版本
-    'last 2 Edge versions'
+    'last 2 Edge versions' // 支持Edge最新的2个版本
 ];
 
+// 导出浏览器配置，供工具链使用
 module.exports = {
     browsers
-};
+};

ghost/admin/mirage/config/labels.js

@@ -1,22 +1,55 @@
-import {paginatedResponse} from '../utils';
+import { paginatedResponse } from '../utils'; // 导入分页响应处理工具函数
 
+/**
+ * 模拟标签（Labels）相关的API接口
+ * 用于前端开发时的本地数据模拟，提供标签的CRUD操作接口
+ * @param {Object} server - Mirage JS服务器实例
+ */
 export default function mockLabels(server) {
+    /**
+     * 模拟创建标签的POST请求
+     * 路径：/labels/
+     * 功能：使用Mirage默认逻辑处理标签创建，接收请求数据并返回新创建的标签
+     */
     server.post('/labels/');
+
+    /**
+     * 模拟查询标签列表的GET请求
+     * 路径：/labels/
+     * 功能：使用分页工具函数处理响应，返回分页格式的标签列表
+     * （自动处理page、limit等查询参数，返回包含数据和分页元信息的响应）
+     */
     server.get('/labels/', paginatedResponse('labels'));
 
-    server.get('/labels/:id/', function ({labels}, {params}) {
+    /**
-        let {id} = params;
+     * 模拟查询单个标签的GET请求（按ID）
-        let label = labels.find(id);
+     * 路径：/labels/:id/
+     * 功能：根据ID查询标签，若不存在则返回404错误
+     */
+    server.get('/labels/:id/', function ({ labels }, { params }) {
+        const { id } = params;
+        const label = labels.find(id); // 从模拟数据库中查找标签
 
+        // 若标签存在则返回，否则返回404错误响应
         return label || new Response(404, {}, {
             errors: [{
                 type: 'NotFoundError',
-                message: 'Label not found.'
+                message: 'Label not found.' // 错误信息：标签未找到
             }]
         });
     });
 
+    /**
+     * 模拟更新标签的PUT请求
+     * 路径：/labels/:id/
+     * 功能：使用Mirage默认逻辑处理标签更新，根据ID更新标签属性并返回更新后的结果
+     */
     server.put('/labels/:id/');
 
+    /**
+     * 模拟删除标签的DELETE请求
+     * 路径：/labels/:id/
+     * 功能：使用Mirage默认逻辑处理标签删除，根据ID删除标签并返回相应状态
+     */
     server.del('/labels/:id/');
-}
+}

ghost/admin/mirage/config/tags.js

@@ -1,37 +1,93 @@
-import {dasherize} from '@ember/string';
+import { dasherize } from '@ember/string'; // 字符串处理工具：转换为连字符格式（如"Hello World"→"hello-world"）
-import {extractFilterParam, paginateModelCollection} from '../utils';
+import { extractFilterParam, paginateModelCollection } from '../utils'; // 工具函数：提取筛选参数、分页处理
-import {isBlank} from '@ember/utils';
+import { isBlank } from '@ember/utils'; // 工具函数：判断值是否为空（null/undefined/空字符串等）
 
+/**
+ * 模拟标签（Tags）相关的API接口
+ * 用于前端开发时的本地数据模拟，无需依赖真实后端服务
+ * @param {Object} server - Mirage JS服务器实例
+ */
+/*
+ * Mirage tags API config
+ *
+ * 中文说明：
+ * - 本模块在 Mirage 配置中定义了与标签相关的 REST 路由（GET /tags、POST /tags 等）以及
+ *   对应的处理逻辑，目的是在开发或集成测试环境中模拟后端行为。
+ * - 这些路由会调用 Mirage 的模型/工厂来创建、查询、更新或删除标签数据，从而让前端组件
+ *   在没有真实后端时也能执行完整的交互流程。
+ */
 export default function mockTags(server) {
-    server.post('/tags/', function ({tags}) {
+    /**
+     * 模拟创建标签的POST请求
+     * 路径：/tags/
+     * 功能：接收标签数据，自动生成slug（若未提供），创建新标签并返回
+     */
+    server.post('/tags/', function ({ tags }) {
+        // 获取请求中的标签属性（已标准化处理）
         let attrs = this.normalizedRequestAttrs();
 
+        // 若未提供slug但提供了name，自动将name转换为slug（连字符格式）
         if (isBlank(attrs.slug) && !isBlank(attrs.name)) {
             attrs.slug = dasherize(attrs.name);
         }
 
-        // NOTE: this does not use the tag factory to fill in blank fields
+        // 创建并返回新标签（注意：此处未使用标签工厂填充默认字段，需手动确保必要字段存在）
         return tags.create(attrs);
     });
 
-    server.get('/tags/slug/:slug/', function ({tags}, {params: {slug}}) {
+    /**
-        // TODO: remove post_count unless requested?
+     * 模拟通过slug查询标签的GET请求
-        return tags.findBy({slug});
+     * 路径：/tags/slug/:slug/
+     * 功能：根据slug查询标签并返回（TODO：优化：按需返回post_count字段）
+     */
+    server.get('/tags/slug/:slug/', function ({ tags }, { params: { slug } }) {
+        // 通过slug查找标签并返回
+        return tags.findBy({ slug });
     });
 
-    server.get('/tags/', function ({tags}, {queryParams}) {
+    /**
-        const {filter, page = 1, limit = 15} = queryParams;
+     * 模拟查询标签列表的GET请求
+     * 路径：/tags/
+     * 功能：支持筛选（按名称）、分页，返回符合条件的标签列表
+     */
+    server.get('/tags/', function ({ tags }, { queryParams }) {
+        // 解析查询参数：筛选条件、页码、每页数量（默认第1页，每页15条）
+        const { filter, page = 1, limit = 15 } = queryParams;
+        // 从筛选条件中提取标签名称的筛选值（如filter=tags.name:test → 提取"test"）
         const tagsName = extractFilterParam('tags.name', filter);
 
+        // 获取所有标签
         let collection = tags.all();
 
+        // 若有名称筛选条件，过滤出名称包含筛选值的标签（不区分大小写）
         if (tagsName) {
-            collection = collection.filter(tag => tag.name.toLowerCase().includes(tagsName.toLowerCase()));
+            collection = collection.filter(tag => 
+                tag.name.toLowerCase().includes(tagsName.toLowerCase())
+            );
         }
 
+        // 对筛选后的标签列表进行分页处理，并返回标准化的分页响应格式
         return paginateModelCollection('tags', collection, page, limit);
     });
+
+    /**
+     * 模拟查询单个标签的GET请求（按ID）
+     * 路径：/tags/:id/
+     * 功能：使用Mirage的默认处理逻辑（根据ID查询标签）
+     */
     server.get('/tags/:id/');
+
+    /**
+     * 模拟更新标签的PUT请求
+     * 路径：/tags/:id/
+     * 功能：使用Mirage的默认处理逻辑（根据ID更新标签属性）
+     */
     server.put('/tags/:id/');
+
+    /**
+     * 模拟删除标签的DELETE请求
+     * 路径：/tags/:id/
+     * 功能：使用Mirage的默认处理逻辑（根据ID删除标签）
+     */
     server.del('/tags/:id/');
-}
+}

ghost/admin/mirage/factories/label.js

@@ -1,13 +1,57 @@
-import moment from 'moment-timezone';
+import moment from 'moment-timezone'; // 导入moment时间处理库（带时区支持）
-import {Factory} from 'miragejs';
+import { Factory } from 'miragejs'; // 导入Mirage JS的Factory类，用于创建模拟数据工厂
 
+/**
+ * 标签（Label）数据工厂
+ * 用于生成标准化的标签模拟数据，供Mirage JS服务器使用
+ * 支持动态生成带索引的属性值，模拟真实业务场景中的标签数据
+ */
 export default Factory.extend({
-    createdAt() { return moment.utc().toISOString(); },
+    /**
-    name(i) { return `Label ${i}`; },
+     * 标签创建时间
-    slug(i) { return `label-${i}`; },
+     * 动态生成：当前UTC时间的ISO格式字符串（如"2024-05-20T12:34:56.789Z"）
-    updatedAt() { return moment.utc().toISOString(); },
+     * @returns {string} ISO格式的UTC时间字符串
+     */
+    createdAt() {
+        return moment.utc().toISOString();
+    },
+
+    /**
+     * 标签名称
+     * 动态生成：包含当前标签索引（i），如"Label 1"
+     * @param {number} i - 标签在工厂序列中的索引（从1开始）
+     * @returns {string} 带索引的标签名称
+     */
+    name(i) {
+        return `Label ${i}`;
+    },
+
+    /**
+     * 标签URL别名（slug）
+     * 动态生成：包含当前标签索引（i），如"label-1"
+     * @param {number} i - 标签在工厂序列中的索引
+     * @returns {string} 带索引的slug
+     */
+    slug(i) {
+        return `label-${i}`;
+    },
+
+    /**
+     * 标签更新时间
+     * 动态生成：当前UTC时间的ISO格式字符串（与创建时间一致，模拟刚创建未更新的状态）
+     * @returns {string} ISO格式的UTC时间字符串
+     */
+    updatedAt() {
+        return moment.utc().toISOString();
+    },
+
+    /**
+     * 标签关联成员数量
+     * 默认为{members: 0}（关联0个成员）
+     * 注：实际使用中会被标签序列化器自动更新
+     * @returns {Object} 包含关联成员数量的对象
+     */
     count() {
-        // this gets updated automatically by the label serializer
+        return { members: 0 };
-        return {members: 0};
     }
-});
+});

ghost/admin/mirage/factories/tag.js

@@ -1,18 +1,106 @@
-import {Factory} from 'miragejs';
+import { Factory } from 'miragejs'; // 引入Mirage JS的Factory类，用于创建模拟数据工厂
 
+/*
+ * Mirage Tag Factory
+ *
+ * 中文说明：
+ * - 本工厂用于在开发模式或前端集成测试中生成标签（Tag）模拟数据。
+ * - Mirage 会使用此工厂在内存数据库中创建标签记录，以模拟后端返回的 API 数据。
+ * - 这里生成的字段（name、slug、featureImage、metaTitle、metaDescription 等）
+ *   用于保证前端组件与交互在没有真实后端的情况下也能正常工作与测试。
+ */
 export default Factory.extend({
+    /**
+     * 标签创建时间
+     * 默认为固定时间（2015-09-11T09:44:29.871Z）
+     */
     createdAt: '2015-09-11T09:44:29.871Z',
-    description(i) { return `Description for tag ${i}.`; },
+
+    /**
+     * 标签描述
+     * 动态生成：包含当前标签索引（i），如"Description for tag 1."
+     * @param {number} i - 标签在工厂序列中的索引（从1开始）
+     * @returns {string} 带索引的描述文本
+     */
+    description(i) {
+        return `Description for tag ${i}.`;
+    },
+
+    /**
+     * 标签可见性
+     * 默认为"public"（公开）
+     */
     visibility: 'public',
-    featureImage(i) { return `/content/images/2015/10/tag-${i}.jpg`; },
+
-    metaDescription(i) { return `Meta description for tag ${i}.`; },
+    /**
-    metaTitle(i) { return `Meta Title for tag ${i}`; },
+     * 标签封面图URL
-    name(i) { return `Tag ${i}`; },
+     * 动态生成：包含当前标签索引（i），如"/content/images/2015/10/tag-1.jpg"
+     * @param {number} i - 标签在工厂序列中的索引
+     * @returns {string} 带索引的图片URL
+     */
+    featureImage(i) {
+        return `/content/images/2015/10/tag-${i}.jpg`;
+    },
+
+    /**
+     * 标签SEO描述（meta description）
+     * 动态生成：包含当前标签索引（i），如"Meta description for tag 1."
+     * @param {number} i - 标签在工厂序列中的索引
+     * @returns {string} 带索引的SEO描述文本
+     */
+    metaDescription(i) {
+        return `Meta description for tag ${i}.`;
+    },
+
+    /**
+     * 标签SEO标题（meta title）
+     * 动态生成：包含当前标签索引（i），如"Meta Title for tag 1"
+     * @param {number} i - 标签在工厂序列中的索引
+     * @returns {string} 带索引的SEO标题文本
+     */
+    metaTitle(i) {
+        return `Meta Title for tag ${i}`;
+    },
+
+    /**
+     * 标签名称
+     * 动态生成：包含当前标签索引（i），如"Tag 1"
+     * @param {number} i - 标签在工厂序列中的索引
+     * @returns {string} 带索引的标签名称
+     */
+    name(i) {
+        return `Tag ${i}`;
+    },
+
+    /**
+     * 父标签
+     * 默认为null（无父标签）
+     */
     parent: null,
-    slug(i) { return `tag-${i}`; },
+
+    /**
+     * 标签URL别名（slug）
+     * 动态生成：包含当前标签索引（i），如"tag-1"
+     * @param {number} i - 标签在工厂序列中的索引
+     * @returns {string} 带索引的slug
+     */
+    slug(i) {
+        return `tag-${i}`;
+    },
+
+    /**
+     * 标签更新时间
+     * 默认为固定时间（2015-10-19T16:25:07.756Z）
+     */
     updatedAt: '2015-10-19T16:25:07.756Z',
+
+    /**
+     * 标签关联内容数量
+     * 默认为{posts: 0}（关联0篇文章）
+     * 注：实际使用中会被标签序列化器自动更新
+     * @returns {Object} 包含关联文章数量的对象
+     */
     count() {
-        // this gets updated automatically by the tag serializer
+        return { posts: 0 };
-        return {posts: 0};
     }
-});
+});

ghost/admin/mirage/models/label.js

@@ -1,5 +1,19 @@
-import {Model, hasMany} from 'miragejs';
+import { Model, hasMany } from 'miragejs'; // 导入Mirage JS的模型基础类和关联关系工具
 
+/**
+ * 标签（Label）模型
+ * 定义标签与其他模型的关联关系，用于Mirage JS模拟数据的关系管理
+ */
 export default Model.extend({
+    /**
+     * 定义标签与成员（members）的一对多关联关系
+     * 表示一个标签可以关联多个成员
+     * 
+     * 关联说明：
+     * - 采用hasMany关系：当前标签（Label）拥有多个成员（members）
+     * - Mirage JS会自动管理关联数据的CRUD操作，例如：
+     *   - 当查询标签时，可以通过`label.members`获取关联的所有成员
+     *   - 当创建成员并关联标签时，标签的成员列表会自动更新
+     */
     members: hasMany()
-});
+});

ghost/admin/mirage/models/tag.js

@@ -1,5 +1,28 @@
-import {Model, hasMany} from 'miragejs';
+/*
+ * Mirage Tag Model
+ *
+ * 中文说明：
+ * - Mirage 中的 Tag 模型用于在前端开发与测试时模拟后端的标签数据模型。
+ * - 通过 `hasMany('post')` 定义与文章（posts）的多对多/一对多关系，方便在测试中通过 `tag.posts` 访问关联文章。
+ * - Mirage 会自动维护关联数据（如创建/删除时的引用更新），因此测试可以更接近真实后端行为。
+ */
+import { Model, hasMany } from 'miragejs'; // 导入Mirage JS的模型基础类和关联关系工具
 
+/**
+ * 标签（Tag）模型
+ * 定义标签与文章（posts）的关联关系，用于Mirage JS模拟数据的关系管理
+ */
 export default Model.extend({
+    /**
+     * 定义标签与文章的一对多关联关系
+     * 表示一个标签可以关联多篇文章
+     * 
+     * 关联说明：
+     * - 采用hasMany关系：当前标签（Tag）拥有多篇文章（posts）
+     * - Mirage JS会自动维护关联数据，例如：
+     *   - 查询标签时，可通过`tag.posts`获取该标签关联的所有文章
+     *   - 创建文章并关联标签时，标签的文章列表会自动更新
+     *   - 删除标签时，可配置是否级联删除关联的文章（默认不删除）
+     */
     posts: hasMany()
-});
+});

ghost/admin/mirage/serializers/label.js

@@ -1,18 +1,36 @@
-import BaseSerializer from './application';
+import BaseSerializer from './application'; // 导入应用程序基础序列化器
 
+/**
+ * 标签（Label）序列化器
+ * 继承自基础序列化器，扩展了标签关联成员数量的动态计算逻辑
+ */
 export default BaseSerializer.extend({
-    // make the label.count.members value dynamic
+    /**
+     * 序列化标签模型或模型集合
+     * 动态更新标签的成员数量（count.members），确保与实际关联的成员数量一致
+     * @param {Model|Collection} labelModelOrCollection - 单个标签模型或标签集合
+     * @param {Object} request - 请求对象（包含请求信息）
+     * @returns {Object} 序列化后的标签数据（符合API响应格式）
+     */
     serialize(labelModelOrCollection, request) {
+        /**
+         * 更新单个标签的成员数量
+         * 将标签关联的成员ID数组长度作为实际成员数量，更新到count.members字段
+         * @param {Model} label - 标签模型实例
+         */
         let updateMemberCount = (label) => {
-            label.update('count', {members: label.memberIds.length});
+            label.update('count', { members: label.memberIds.length });
         };
 
+        // 若为单个标签模型，直接更新其成员数量
         if (this.isModel(labelModelOrCollection)) {
             updateMemberCount(labelModelOrCollection);
         } else {
+            // 若为标签集合，遍历每个标签并更新成员数量
             labelModelOrCollection.models.forEach(updateMemberCount);
         }
 
+        // 调用父类的序列化方法，返回标准化的响应数据
         return BaseSerializer.prototype.serialize.call(this, labelModelOrCollection, request);
     }
-});
+});

ghost/admin/mirage/serializers/tag.js

@@ -1,19 +1,45 @@
 import BaseSerializer from './application';
 
+/*
+ * Mirage Tag Serializer
+ *
+ * 中文说明：
+ * - 为 Mirage 中的 Tag 模型提供序列化逻辑，在序列化阶段计算并注入关联文章数量（count.posts）
+ *   和访问 URL（url 字段），使前端在渲染列表或详情时能正确显示关联计数与跳转链接。
+ * - serialize 方法会支持传入单个模型或模型集合，并为每个模型更新动态字段后再调用基类序列化。
+ */
 export default BaseSerializer.extend({
-    // make the tag.count.posts and url values dynamic
+    /**
+     * 序列化标签模型或模型集合
+     * 会在序列化前动态更新标签的关联文章数量和访问URL
+     * @param {Model|Collection} tagModelOrCollection - 单个标签模型或标签集合
+     * @param {Object} request - 请求对象，包含请求相关信息
+     * @returns {Object} 序列化后的标签数据，符合API响应格式
+     */
     serialize(tagModelOrCollection, request) {
+        /**
+         * 更新单个标签的动态属性
+         * 1. 计算关联文章数量：根据标签关联的文章ID数组长度
+         * 2. 生成访问URL：结合本地开发服务器地址和标签的slug
+         * @param {Model} tag - 单个标签模型实例
+         */
         let updatePost = (tag) => {
+            // 更新关联文章数量：postIds是Mirage自动维护的关联文章ID数组
             tag.update('count', {posts: tag.postIds.length});
+            // 生成标签的访问URL，基于本地开发环境地址
             tag.update('url', `http://localhost:4200/tag/${tag.slug}/`);
         };
 
+        // 判断传入的是单个模型还是模型集合
         if (this.isModel(tagModelOrCollection)) {
+            // 若为单个模型，直接更新其动态属性
             updatePost(tagModelOrCollection);
         } else {
+            // 若为模型集合，遍历每个模型并更新动态属性
             tagModelOrCollection.models.forEach(updatePost);
         }
 
+        // 调用父类的serialize方法，完成最终的序列化并返回结果
         return BaseSerializer.prototype.serialize.call(this, tagModelOrCollection, request);
     }
-});
+});

ghost/admin/tests/acceptance/tags-test.js

@@ -1,361 +1,469 @@
-import {Response} from 'miragejs';
+import { Response } from 'miragejs';
-import {authenticateSession, invalidateSession} from 'ember-simple-auth/test-support';
+// 导入Ember Simple Auth的测试支持工具：用于认证和失效会话
-import {beforeEach, describe, it} from 'mocha';
+import { authenticateSession, invalidateSession } from 'ember-simple-auth/test-support';
-import {click, currentRouteName, currentURL, fillIn, find, findAll} from '@ember/test-helpers';
+// 导入Mocha测试框架的钩子和断言方法
-import {expect} from 'chai';
+import { beforeEach, describe, it } from 'mocha';
-import {setupApplicationTest} from 'ember-mocha';
+// 导入Ember测试辅助函数：用于模拟用户交互和获取DOM元素
-import {setupMirage} from 'ember-cli-mirage/test-support';
+import { click, currentRouteName, currentURL, fillIn, find, findAll } from '@ember/test-helpers';
-import {visit} from '../helpers/visit';
+// 导入Chai断言库
-
+import { expect } from 'chai';
+// 导入Ember应用测试设置工具
+import { setupApplicationTest } from 'ember-mocha';
+// 导入Mirage JS的测试支持工具
+import { setupMirage } from 'ember-cli-mirage/test-support';
+// 导入自定义的访问页面辅助函数
+import { visit } from '../helpers/visit';
+
+// 描述"标签（Tags）"验收测试套件
 describe('Acceptance: Tags', function () {
+    // 设置应用测试钩子和Mirage模拟服务器
     let hooks = setupApplicationTest();
     setupMirage(hooks);
 
+    // 测试用例：未认证用户访问标签页时重定向到登录页
     it('redirects to signin when not authenticated', async function () {
+        // 使当前会话失效（模拟未登录状态）
         await invalidateSession();
+        // 访问标签页面
         await visit('/tags');
 
+        // 断言当前URL为登录页
         expect(currentURL()).to.equal('/signin');
     });
 
+    // 测试用例：贡献者（Contributor）角色用户访问标签页时重定向到文章页
     it('redirects to posts page when authenticated as contributor', async function () {
-        let role = this.server.create('role', {name: 'Contributor'});
+        // 创建"Contributor"角色
-        this.server.create('user', {roles: [role], slug: 'test-user'});
+        let role = this.server.create('role', { name: 'Contributor' });
+        // 创建具有该角色的用户
+        this.server.create('user', { roles: [role], slug: 'test-user' });
 
+        // 认证当前会话（模拟登录）
         await authenticateSession();
+        // 访问标签页面
         await visit('/tags');
 
+        // 断言当前URL为文章页
         expect(currentURL(), 'currentURL').to.equal('/posts');
     });
 
+    // 测试用例：作者（Author）角色用户访问标签页时重定向到站点设置页
     it('redirects to site page when authenticated as author', async function () {
-        let role = this.server.create('role', {name: 'Author'});
+        // 创建"Author"角色
-        this.server.create('user', {roles: [role], slug: 'test-user'});
+        let role = this.server.create('role', { name: 'Author' });
+        // 创建具有该角色的用户
+        this.server.create('user', { roles: [role], slug: 'test-user' });
 
+        // 认证当前会话
         await authenticateSession();
+        // 访问标签页面
         await visit('/tags');
 
+        // 断言当前URL为站点设置页
         expect(currentURL(), 'currentURL').to.equal('/site');
     });
 
+    // 描述"以管理员（Administrator）身份登录"的测试场景
     describe('when logged in as administrator', function () {
+        // 每个测试用例执行前的准备工作
         beforeEach(async function () {
-            let role = this.server.create('role', {name: 'Administrator'});
+            // 创建"Administrator"角色
-            this.server.create('user', {roles: [role]});
+            let role = this.server.create('role', { name: 'Administrator' });
+            // 创建具有该角色的用户
+            this.server.create('user', { roles: [role] });
 
+            // 认证当前会话
             await authenticateSession();
         });
 
+        // 测试用例：分别列出公开标签和内部标签
         it('lists public and internal tags separately', async function () {
-            this.server.create('tag', {name: 'B - Third', slug: 'third'});
+            // 创建4个公开标签
-            this.server.create('tag', {name: 'Z - Last', slug: 'last'});
+            this.server.create('tag', { name: 'B - Third', slug: 'third' });
-            this.server.create('tag', {name: '!A - Second', slug: 'second'});
+            this.server.create('tag', { name: 'Z - Last', slug: 'last' });
-            this.server.create('tag', {name: 'A - First', slug: 'first'});
+            this.server.create('tag', { name: '!A - Second', slug: 'second' });
-            this.server.create('tag', {name: '#one', slug: 'hash-one', visibility: 'internal'});
+            this.server.create('tag', { name: 'A - First', slug: 'first' });
-            this.server.create('tag', {name: '#two', slug: 'hash-two', visibility: 'internal'});
+            // 创建2个内部标签
-
+            this.server.create('tag', { name: '#one', slug: 'hash-one', visibility: 'internal' });
+            this.server.create('tag', { name: '#two', slug: 'hash-two', visibility: 'internal' });
+
+            // 访问标签页面
             await visit('tags');
 
-            // it loads tags list
+            // 断言页面成功加载（当前URL为标签页）
             expect(currentURL(), 'currentURL').to.equal('tags');
 
-            // it highlights nav menu
+            // 断言导航菜单中"标签"项处于激活状态
             expect(find('[data-test-nav="tags"]'), 'highlights nav menu item')
                 .to.have.class('active');
 
-            // it defaults to public tags
+            // 断言默认显示公开标签（公开标签按钮处于激活状态）
             expect(find('[data-test-tags-nav="public"]')).to.have.attr('data-test-active');
             expect(find('[data-test-tags-nav="internal"]')).to.not.have.attr('data-test-active');
 
-            // it lists all public tags
+            // 断言公开标签列表数量为4
             expect(findAll('[data-test-tag]'), 'public tag list count')
                 .to.have.length(4);
 
-            // tags are in correct order
+            // 断言标签按正确顺序排序（按名称排序）
             let tags = findAll('[data-test-tag]');
-
             expect(tags[0].querySelector('[data-test-tag-name]')).to.have.trimmed.text('A - First');
             expect(tags[1].querySelector('[data-test-tag-name]')).to.have.trimmed.text('!A - Second');
             expect(tags[2].querySelector('[data-test-tag-name]')).to.have.trimmed.text('B - Third');
             expect(tags[3].querySelector('[data-test-tag-name]')).to.have.trimmed.text('Z - Last');
 
-            // can switch to internal tags
+            // 切换到内部标签视图
             await click('[data-test-tags-nav="internal"]');
 
+            // 断言内部标签列表数量为2
             expect(findAll('[data-test-tag]'), 'internal tag list count').to.have.length(2);
         });
 
+        // 测试用例：可以添加标签
         it('can add tags', async function () {
+            // 访问标签页面
             await visit('tags');
+            // 断言初始时没有标签
             expect(findAll('[data-test-tag]')).to.have.length(0);
 
+            // 点击"新建标签"按钮
             await click('[data-test-button="new-tag"]');
 
+            // 断言跳转到新建标签页面
             expect(currentURL()).to.equal('/tags/new');
 
+            // 填写标签名称和slug
             await fillIn('[data-test-input="tag-name"]', 'New tag name');
             await fillIn('[data-test-input="tag-slug"]', 'new-tag-slug');
+            // 点击保存按钮
             await click('[data-test-button="save"]');
+            // 点击返回标签列表链接
             await click('[data-test-link="tags-back"]');
 
+            // 断言标签列表中新增了一个标签
             expect(findAll('[data-test-tag]')).to.have.length(1);
+            // 断言标签名称正确
             expect(find('[data-test-tag] [data-test-tag-name]')).to.have.trimmed.text('New tag name');
+            // 断言标签slug正确
             expect(find('[data-test-tag] [data-test-tag-slug]')).to.have.trimmed.text('new-tag-slug');
+            // 断言关联文章数量为0
             expect(find('[data-test-tag] [data-test-tag-count]')).to.have.trimmed.text('0 posts');
         });
         
+        // 测试用例：可以编辑标签
         it('can edit tags', async function () {
-            const tag = this.server.create('tag', {name: 'To be edited', slug: 'to-be-edited'});
+            // 创建一个待编辑的标签
+            const tag = this.server.create('tag', { name: 'To be edited', slug: 'to-be-edited' });
 
+            // 访问标签页面
             await visit('tags');
+            // 点击标签名称进入编辑页
             await click(`[data-test-tag="${tag.id}"] [data-test-tag-name]`);
 
-            // it maintains active state in nav menu
+            // 断言导航菜单中"标签"项仍处于激活状态
             expect(find('[data-test-nav="tags"]'), 'highlights nav menu item')
                 .to.have.class('active');
 
+            // 断言当前URL为标签编辑页
             expect(currentURL()).to.equal('/tags/to-be-edited');
 
+            // 断言表单中初始值正确
             expect(find('[data-test-input="tag-name"]')).to.have.value('To be edited');
             expect(find('[data-test-input="tag-slug"]')).to.have.value('to-be-edited');
 
+            // 修改标签名称和slug
             await fillIn('[data-test-input="tag-name"]', 'New tag name');
             await fillIn('[data-test-input="tag-slug"]', 'new-tag-slug');
+            // 点击保存按钮
             await click('[data-test-button="save"]');
 
+            // 从数据库中获取保存后的标签，断言数据已更新
             const savedTag = this.server.db.tags.find(tag.id);
             expect(savedTag.name, 'saved tag name').to.equal('New tag name');
             expect(savedTag.slug, 'saved tag slug').to.equal('new-tag-slug');
 
+            // 点击返回标签列表链接
             await click('[data-test-link="tags-back"]');
 
+            // 断言标签列表中显示更新后的标签信息
             const tagListItem = find('[data-test-tag]');
             expect(tagListItem.querySelector('[data-test-tag-name]')).to.have.trimmed.text('New tag name');
             expect(tagListItem.querySelector('[data-test-tag-slug]')).to.have.trimmed.text('new-tag-slug');
         });
 
+        // 测试用例：编辑标签时不会创建重复项
         it('does not create duplicates when editing a tag', async function () {
-            const tag = this.server.create('tag', {name: 'To be edited', slug: 'to-be-edited'});
+            // 创建一个待编辑的标签
+            const tag = this.server.create('tag', { name: 'To be edited', slug: 'to-be-edited' });
 
+            // 访问标签页面
             await visit('tags');
             
-            // Verify we start with one tag
+            // 断言初始时只有一个标签
             expect(findAll('[data-test-tag]')).to.have.length(1);
 
+            // 点击标签名称进入编辑页
             await click(`[data-test-tag="${tag.id}"] [data-test-tag-name]`);
+            // 修改标签名称
             await fillIn('[data-test-input="tag-name"]', 'Edited Tag Name');
+            // 点击保存按钮
             await click('[data-test-button="save"]');
+            // 点击返回标签列表链接
             await click('[data-test-link="tags-back"]');
 
-            // Verify we still have only one tag after editing (no duplicates)
+            // 断言编辑后仍只有一个标签（无重复）
             expect(findAll('[data-test-tag]')).to.have.length(1);
+            // 断言标签名称已更新
             expect(find('[data-test-tag] [data-test-tag-name]')).to.have.trimmed.text('Edited Tag Name');
         });
 
+        // 测试用例：可以删除标签
         it('can delete tags', async function () {
-            const tag = this.server.create('tag', {name: 'To be edited', slug: 'to-be-edited'});
+            // 创建一个待删除的标签
-            this.server.create('post', {tags: [tag]});
+            const tag = this.server.create('tag', { name: 'To be edited', slug: 'to-be-edited' });
+            // 创建一篇关联该标签的文章
+            this.server.create('post', { tags: [tag] });
 
+            // 访问标签页面
             await visit('tags');
+            // 点击标签名称进入编辑页
             await click(`[data-test-tag="${tag.id}"] [data-test-tag-name]`);
 
+            // 点击删除标签按钮
             await click('[data-test-button="delete-tag"]');
 
+            // 定义删除确认弹窗选择器
             const tagModal = '[data-test-modal="confirm-delete-tag"]';
 
+            // 断言弹窗已显示
             expect(find(tagModal)).to.exist;
+            // 断言弹窗中显示正确的关联文章数量
             expect(find(`${tagModal} [data-test-text="posts-count"]`))
                 .to.have.trimmed.text('1 post');
 
+            // 点击确认删除按钮
             await click(`${tagModal} [data-test-button="confirm"]`);
 
+            // 断言弹窗已关闭
             expect(find(tagModal)).to.not.exist;
+            // 断言返回标签列表页
             expect(currentURL()).to.equal('/tags');
+            // 断言标签已被删除（列表为空）
             expect(findAll('[data-test-tag]')).to.have.length(0);
         });
 
+        // 测试用例：可以通过URL中的slug访问标签
         it('can load tag via slug in url', async function () {
-            this.server.create('tag', {name: 'To be edited', slug: 'to-be-edited'});
+            // 创建一个标签
+            this.server.create('tag', { name: 'To be edited', slug: 'to-be-edited' });
 
+            // 直接通过slug访问标签编辑页
             await visit('tags/to-be-edited');
+            // 断言当前URL正确
             expect(currentURL()).to.equal('tags/to-be-edited');
 
+            // 断言表单中显示正确的标签信息
             expect(find('[data-test-input="tag-name"]')).to.have.value('To be edited');
             expect(find('[data-test-input="tag-slug"]')).to.have.value('to-be-edited');
         });
 
+        // 测试用例：访问不存在的标签时重定向到404页面
         it('redirects to 404 when tag does not exist', async function () {
+            // 模拟请求不存在的标签时返回404错误
             this.server.get('/tags/slug/unknown/', function () {
-                return new Response(404, {'Content-Type': 'application/json'}, {errors: [{message: 'Tag not found.', type: 'NotFoundError'}]});
+                return new Response(404, { 'Content-Type': 'application/json' }, { 
+                    errors: [{ message: 'Tag not found.', type: 'NotFoundError' }] 
+                });
             });
 
+            // 访问不存在的标签页面
             await visit('tags/unknown');
 
+            // 断言当前路由为404错误页
             expect(currentRouteName()).to.equal('error404');
+            // 断言URL保持不变（显示错误的URL）
             expect(currentURL()).to.equal('/tags/unknown');
         });
 
+        // 测试用例：创建新标签时导航菜单中"标签"项保持激活状态
         it('maintains active state in nav menu when creating a new tag', async function () {
+            // 访问新建标签页面
             await visit('tags/new');
+            // 断言当前URL正确
             expect(currentURL()).to.equal('tags/new');
+            // 断言导航菜单中"标签"项处于激活状态
             expect(find('[data-test-nav="tags"]'), 'highlights nav menu item')
                 .to.have.class('active');
         });
     });
+
+    // 描述"以编辑者（Editor）身份登录"的测试场景
     describe('as an editor', function () {
+        // 每个测试用例执行前的准备工作
         beforeEach(async function () {
-            let role = this.server.create('role', {name: 'Editor'});
+            // 创建"Editor"角色
-            this.server.create('user', {roles: [role]});
+            let role = this.server.create('role', { name: 'Editor' });
+            // 创建具有该角色的用户
+            this.server.create('user', { roles: [role] });
 
+            // 认证当前会话
             await authenticateSession();
         });
-        it('lists public and internal tags separately', async function () {
-            this.server.create('tag', {name: 'B - Third', slug: 'third'});
-            this.server.create('tag', {name: 'Z - Last', slug: 'last'});
-            this.server.create('tag', {name: '!A - Second', slug: 'second'});
-            this.server.create('tag', {name: 'A - First', slug: 'first'});
-            this.server.create('tag', {name: '#one', slug: 'hash-one', visibility: 'internal'});
-            this.server.create('tag', {name: '#two', slug: 'hash-two', visibility: 'internal'});
 
+        // 测试用例：分别列出公开标签和内部标签（与管理员权限一致）
+        it('lists public and internal tags separately', async function () {
+            // 创建4个公开标签和2个内部标签（同管理员测试用例）
+            this.server.create('tag', { name: 'B - Third', slug: 'third' });
+            this.server.create('tag', { name: 'Z - Last', slug: 'last' });
+            this.server.create('tag', { name: '!A - Second', slug: 'second' });
+            this.server.create('tag', { name: 'A - First', slug: 'first' });
+            this.server.create('tag', { name: '#one', slug: 'hash-one', visibility: 'internal' });
+            this.server.create('tag', { name: '#two', slug: 'hash-two', visibility: 'internal' });
+
+            // 访问标签页面
             await visit('tags');
 
-            // it loads tags list
+            // 断言页面成功加载
             expect(currentURL(), 'currentURL').to.equal('tags');
-
+            // 断言导航菜单激活状态
-            // it highlights nav menu
             expect(find('[data-test-nav="tags"]'), 'highlights nav menu item')
                 .to.have.class('active');
-
+            // 断言默认显示公开标签
-            // it defaults to public tags
             expect(find('[data-test-tags-nav="public"]')).to.have.attr('data-test-active');
             expect(find('[data-test-tags-nav="internal"]')).to.not.have.attr('data-test-active');
-
+            // 断言公开标签数量
-            // it lists all public tags
             expect(findAll('[data-test-tag]'), 'public tag list count')
                 .to.have.length(4);
-
+            // 断言标签排序正确
-            // tags are in correct order
             let tags = findAll('[data-test-tag]');
-
             expect(tags[0].querySelector('[data-test-tag-name]')).to.have.trimmed.text('A - First');
             expect(tags[1].querySelector('[data-test-tag-name]')).to.have.trimmed.text('!A - Second');
             expect(tags[2].querySelector('[data-test-tag-name]')).to.have.trimmed.text('B - Third');
             expect(tags[3].querySelector('[data-test-tag-name]')).to.have.trimmed.text('Z - Last');
-
+            // 切换到内部标签
-            // can switch to internal tags
             await click('[data-test-tags-nav="internal"]');
-
+            // 断言内部标签数量
             expect(findAll('[data-test-tag]'), 'internal tag list count').to.have.length(2);
         });
+
+        // 测试用例：可以编辑标签（与管理员权限一致）
         it('can edit tags', async function () {
-            const tag = this.server.create('tag', {name: 'To be edited', slug: 'to-be-edited'});
+            // 创建待编辑标签
+            const tag = this.server.create('tag', { name: 'To be edited', slug: 'to-be-edited' });
 
+            // 访问标签页面并进入编辑页
             await visit('tags');
             await click(`[data-test-tag="${tag.id}"] [data-test-tag-name]`);
 
-            // it maintains active state in nav menu
+            // 断言导航菜单激活状态
             expect(find('[data-test-nav="tags"]'), 'highlights nav menu item')
                 .to.have.class('active');
-
+            // 断言当前URL
             expect(currentURL()).to.equal('/tags/to-be-edited');
-
+            // 断言初始表单值
             expect(find('[data-test-input="tag-name"]')).to.have.value('To be edited');
             expect(find('[data-test-input="tag-slug"]')).to.have.value('to-be-edited');
 
+            // 修改并保存标签
             await fillIn('[data-test-input="tag-name"]', 'New tag name');
             await fillIn('[data-test-input="tag-slug"]', 'new-tag-slug');
             await click('[data-test-button="save"]');
 
+            // 断言数据已更新
             const savedTag = this.server.db.tags.find(tag.id);
             expect(savedTag.name, 'saved tag name').to.equal('New tag name');
             expect(savedTag.slug, 'saved tag slug').to.equal('new-tag-slug');
 
+            // 返回列表页并断言显示正确
             await click('[data-test-link="tags-back"]');
-
             const tagListItem = find('[data-test-tag]');
             expect(tagListItem.querySelector('[data-test-tag-name]')).to.have.trimmed.text('New tag name');
             expect(tagListItem.querySelector('[data-test-tag-slug]')).to.have.trimmed.text('new-tag-slug');
         });
 
+        // 测试用例：可以删除标签（与管理员权限一致）
         it('can delete tags', async function () {
-            const tag = this.server.create('tag', {name: 'To be edited', slug: 'to-be-edited'});
+            // 创建待删除标签及关联文章
-            this.server.create('post', {tags: [tag]});
+            const tag = this.server.create('tag', { name: 'To be edited', slug: 'to-be-edited' });
+            this.server.create('post', { tags: [tag] });
 
+            // 访问标签页面并进入编辑页
             await visit('tags');
             await click(`[data-test-tag="${tag.id}"] [data-test-tag-name]`);
 
+            // 点击删除按钮
             await click('[data-test-button="delete-tag"]');
-
             const tagModal = '[data-test-modal="confirm-delete-tag"]';
 
+            // 断言弹窗显示及内容正确
             expect(find(tagModal)).to.exist;
             expect(find(`${tagModal} [data-test-text="posts-count"]`))
                 .to.have.trimmed.text('1 post');
 
+            // 确认删除
             await click(`${tagModal} [data-test-button="confirm"]`);
 
+            // 断言标签已删除
             expect(find(tagModal)).to.not.exist;
             expect(currentURL()).to.equal('/tags');
             expect(findAll('[data-test-tag]')).to.have.length(0);
         });
     });
+
+    // 描述"以超级编辑者（Super Editor）身份登录"的测试场景
     describe('as a super editor', function () {
+        // 每个测试用例执行前的准备工作
         beforeEach(async function () {
-            let role = this.server.create('role', {name: 'Super Editor'});
+            // 创建"Super Editor"角色
-            this.server.create('user', {roles: [role]});
+            let role = this.server.create('role', { name: 'Super Editor' });
+            // 创建具有该角色的用户
+            this.server.create('user', { roles: [role] });
 
+            // 认证当前会话
             await authenticateSession();
         });
-        it('lists public and internal tags separately', async function () {
-            this.server.create('tag', {name: 'B - Third', slug: 'third'});
-            this.server.create('tag', {name: 'Z - Last', slug: 'last'});
-            this.server.create('tag', {name: '!A - Second', slug: 'second'});
-            this.server.create('tag', {name: 'A - First', slug: 'first'});
-            this.server.create('tag', {name: '#one', slug: 'hash-one', visibility: 'internal'});
-            this.server.create('tag', {name: '#two', slug: 'hash-two', visibility: 'internal'});
 
+        // 测试用例：分别列出公开标签和内部标签（与管理员权限一致）
+        it('lists public and internal tags separately', async function () {
+            // 创建4个公开标签和2个内部标签（同管理员测试用例）
+            this.server.create('tag', { name: 'B - Third', slug: 'third' });
+            this.server.create('tag', { name: 'Z - Last', slug: 'last' });
+            this.server.create('tag', { name: '!A - Second', slug: 'second' });
+            this.server.create('tag', { name: 'A - First', slug: 'first' });
+            this.server.create('tag', { name: '#one', slug: 'hash-one', visibility: 'internal' });
+            this.server.create('tag', { name: '#two', slug: 'hash-two', visibility: 'internal' });
+
+            // 访问标签页面
             await visit('tags');
 
-            // it loads tags list
+            // 断言页面加载及标签展示正确（与管理员测试用例一致）
             expect(currentURL(), 'currentURL').to.equal('tags');
-
-            // it highlights nav menu
             expect(find('[data-test-nav="tags"]'), 'highlights nav menu item')
                 .to.have.class('active');
-
-            // it defaults to public tags
             expect(find('[data-test-tags-nav="public"]')).to.have.attr('data-test-active');
             expect(find('[data-test-tags-nav="internal"]')).to.not.have.attr('data-test-active');
-
-            // it lists all public tags
             expect(findAll('[data-test-tag]'), 'public tag list count')
                 .to.have.length(4);
-
-            // tags are in correct order
             let tags = findAll('[data-test-tag]');
-
             expect(tags[0].querySelector('[data-test-tag-name]')).to.have.trimmed.text('A - First');
             expect(tags[1].querySelector('[data-test-tag-name]')).to.have.trimmed.text('!A - Second');
             expect(tags[2].querySelector('[data-test-tag-name]')).to.have.trimmed.text('B - Third');
             expect(tags[3].querySelector('[data-test-tag-name]')).to.have.trimmed.text('Z - Last');
-
-            // can switch to internal tags
             await click('[data-test-tags-nav="internal"]');
-
             expect(findAll('[data-test-tag]'), 'internal tag list count').to.have.length(2);
         });
+
+        // 测试用例：可以编辑标签（与管理员权限一致）
         it('can edit tags', async function () {
-            const tag = this.server.create('tag', {name: 'To be edited', slug: 'to-be-edited'});
+            // 创建待编辑标签（测试步骤与管理员测试用例一致）
+            const tag = this.server.create('tag', { name: 'To be edited', slug: 'to-be-edited' });
 
             await visit('tags');
             await click(`[data-test-tag="${tag.id}"] [data-test-tag-name]`);
 
-            // it maintains active state in nav menu
             expect(find('[data-test-nav="tags"]'), 'highlights nav menu item')
                 .to.have.class('active');
-
             expect(currentURL()).to.equal('/tags/to-be-edited');
-
             expect(find('[data-test-input="tag-name"]')).to.have.value('To be edited');
             expect(find('[data-test-input="tag-slug"]')).to.have.value('to-be-edited');
 
@@ -368,21 +476,21 @@ describe('Acceptance: Tags', function () {
             expect(savedTag.slug, 'saved tag slug').to.equal('new-tag-slug');
 
             await click('[data-test-link="tags-back"]');
-
             const tagListItem = find('[data-test-tag]');
             expect(tagListItem.querySelector('[data-test-tag-name]')).to.have.trimmed.text('New tag name');
             expect(tagListItem.querySelector('[data-test-tag-slug]')).to.have.trimmed.text('new-tag-slug');
         });
 
+        // 测试用例：可以删除标签（与管理员权限一致）
         it('can delete tags', async function () {
-            const tag = this.server.create('tag', {name: 'To be edited', slug: 'to-be-edited'});
+            // 创建待删除标签及关联文章（测试步骤与管理员测试用例一致）
-            this.server.create('post', {tags: [tag]});
+            const tag = this.server.create('tag', { name: 'To be edited', slug: 'to-be-edited' });
+            this.server.create('post', { tags: [tag] });
 
             await visit('tags');
             await click(`[data-test-tag="${tag.id}"] [data-test-tag-name]`);
 
             await click('[data-test-button="delete-tag"]');
-
             const tagModal = '[data-test-modal="confirm-delete-tag"]';
 
             expect(find(tagModal)).to.exist;
@@ -396,4 +504,4 @@ describe('Acceptance: Tags', function () {
             expect(findAll('[data-test-tag]')).to.have.length(0);
         });
     });
-});
+});

ghost/admin/tests/helpers/labs-flag.js

@@ -1,37 +1,63 @@
+/**
+ * 启用指定的实验室功能标志（Labs Flag）
+ * 用于在测试环境中开启特定的实验性功能
+ * @param {Object} server - Mirage JS服务器实例
+ * @param {string} flag - 要启用的实验室功能标志名称
+ */
 export function enableLabsFlag(server, flag) {
+    // 若配置表为空，加载配置 fixtures 数据
     if (!server.schema.configs.all().length) {
         server.loadFixtures('configs');
     }
 
+    // 若设置表为空，加载设置 fixtures 数据
     if (!server.schema.settings.all().length) {
         server.loadFixtures('settings');
     }
 
+    // 获取第一个配置项，开启开发者实验功能总开关
     const config = server.schema.configs.first();
-    config.update({enableDeveloperExperiments: true});
+    config.update({ enableDeveloperExperiments: true });
 
-    const existingSetting = server.db.settings.findBy({key: 'labs'}).value;
+    // 获取现有的实验室功能设置（JSON字符串）
+    const existingSetting = server.db.settings.findBy({ key: 'labs' }).value;
+    // 解析为对象（若不存在则初始化为空对象）
     const labsSetting = existingSetting ? JSON.parse(existingSetting) : {};
+    // 启用目标功能标志
     labsSetting[flag] = true;
 
-    server.db.settings.update({key: 'labs'}, {value: JSON.stringify(labsSetting)});
+    // 更新数据库中的实验室设置（转换为JSON字符串存储）
+    server.db.settings.update({ key: 'labs' }, { value: JSON.stringify(labsSetting) });
 }
 
+/**
+ * 禁用指定的实验室功能标志（Labs Flag）
+ * 用于在测试环境中关闭特定的实验性功能
+ * @param {Object} server - Mirage JS服务器实例
+ * @param {string} flag - 要禁用的实验室功能标志名称
+ */
 export function disableLabsFlag(server, flag) {
+    // 若配置表为空，加载配置 fixtures 数据
     if (!server.schema.configs.all().length) {
         server.loadFixtures('configs');
     }
 
+    // 若设置表为空，加载设置 fixtures 数据
     if (!server.schema.settings.all().length) {
         server.loadFixtures('settings');
     }
 
+    // 获取第一个配置项，确保开发者实验功能总开关开启（避免功能被全局禁用）
     const config = server.schema.configs.first();
-    config.update({enableDeveloperExperiments: true});
+    config.update({ enableDeveloperExperiments: true });
 
-    const existingSetting = server.db.settings.findBy({key: 'labs'}).value;
+    // 获取现有的实验室功能设置（JSON字符串）
+    const existingSetting = server.db.settings.findBy({ key: 'labs' }).value;
+    // 解析为对象（若不存在则初始化为空对象）
     const labsSetting = existingSetting ? JSON.parse(existingSetting) : {};
+    // 禁用目标功能标志
     labsSetting[flag] = false;
 
-    server.db.settings.update({key: 'labs'}, {value: JSON.stringify(labsSetting)});
+    // 更新数据库中的实验室设置（转换为JSON字符串存储）
-}
+    server.db.settings.update({ key: 'labs' }, { value: JSON.stringify(labsSetting) });
+}

ghost/admin/tests/integration/adapters/tag-test.js

@@ -1,60 +1,92 @@
-import Pretender from 'pretender';
+import Pretender from 'pretender'; // 导入Pretender库，用于模拟HTTP请求
-import ghostPaths from 'ghost-admin/utils/ghost-paths';
+import ghostPaths from 'ghost-admin/utils/ghost-paths'; // 导入Ghost路径工具，用于获取API根路径
-import {describe, it} from 'mocha';
+import { describe, it } from 'mocha'; // 导入Mocha测试框架的描述和测试用例函数
-import {expect} from 'chai';
+import { expect } from 'chai'; // 导入Chai断言库
-import {setupTest} from 'ember-mocha';
+import { setupTest } from 'ember-mocha'; // 导入Ember测试设置工具
 
+// 描述"标签适配器（Adapter: tag）"的集成测试套件
 describe('Integration: Adapter: tag', function () {
+    // 设置测试环境（初始化Ember测试容器）
     setupTest();
 
+    // 声明变量：模拟服务器和数据存储服务
     let server, store;
 
+    // 每个测试用例执行前的准备工作
     beforeEach(function () {
+        // 获取Ember的数据存储服务（store）
         store = this.owner.lookup('service:store');
+        // 创建Pretender模拟服务器实例，用于拦截和模拟API请求
         server = new Pretender();
     });
 
+    // 每个测试用例执行后的清理工作
     afterEach(function () {
+        // 关闭模拟服务器，避免影响其他测试
         server.shutdown();
     });
 
+    // 测试用例：获取所有标签时，从常规API端点加载数据
     it('loads tags from regular endpoint when all are fetched', function (done) {
+        // 模拟GET请求：当请求标签列表API时，返回预设的标签数据
         server.get(`${ghostPaths().apiRoot}/tags/`, function () {
-            return [200, {'Content-Type': 'application/json'}, JSON.stringify({tags: [
+            return [
-                {
+                200, // HTTP状态码：成功
-                    id: 1,
+                { 'Content-Type': 'application/json' }, // 响应头：JSON格式
-                    name: 'Tag 1',
+                JSON.stringify({ // 响应体：包含两个标签的数组
-                    slug: 'tag-1'
+                    tags: [
-                }, {
+                        {
-                    id: 2,
+                            id: 1,
-                    name: 'Tag 2',
+                            name: 'Tag 1',
-                    slug: 'tag-2'
+                            slug: 'tag-1'
-                }
+                        }, {
-            ]})];
+                            id: 2,
+                            name: 'Tag 2',
+                            slug: 'tag-2'
+                        }
+                    ]
+                })
+            ];
         });
 
-        store.findAll('tag', {reload: true}).then((tags) => {
+        // 使用store查询所有标签（强制重新加载）
+        store.findAll('tag', { reload: true }).then((tags) => {
+            // 断言：查询结果存在
             expect(tags).to.be.ok;
+            // 断言：第一个标签的名称正确
             expect(tags.objectAtContent(0).get('name')).to.equal('Tag 1');
+            // 标记测试完成
             done();
         });
     });
 
+    // 测试用例：查询单个标签且传入slug时，从slug专属API端点加载数据
     it('loads tag from slug endpoint when single tag is queried and slug is passed in', function (done) {
+        // 模拟GET请求：当请求特定slug的标签API时，返回预设的标签数据
         server.get(`${ghostPaths().apiRoot}/tags/slug/tag-1/`, function () {
-            return [200, {'Content-Type': 'application/json'}, JSON.stringify({tags: [
+            return [
-                {
+                200, // HTTP状态码：成功
-                    id: 1,
+                { 'Content-Type': 'application/json' }, // 响应头：JSON格式
-                    slug: 'tag-1',
+                JSON.stringify({ // 响应体：包含指定slug的标签
-                    name: 'Tag 1'
+                    tags: [
-                }
+                        {
-            ]})];
+                            id: 1,
+                            slug: 'tag-1',
+                            name: 'Tag 1'
+                        }
+                    ]
+                })
+            ];
         });
 
-        store.queryRecord('tag', {slug: 'tag-1'}).then((tag) => {
+        // 使用store按slug查询单个标签
+        store.queryRecord('tag', { slug: 'tag-1' }).then((tag) => {
+            // 断言：查询结果存在
             expect(tag).to.be.ok;
+            // 断言：标签名称正确
             expect(tag.get('name')).to.equal('Tag 1');
+            // 标记测试完成
             done();
         });
     });
-});
+});

ghost/admin/tests/integration/components/gh-psm-tags-input-test.js

@@ -1,253 +1,358 @@
 import hbs from 'htmlbars-inline-precompile';
 import mockPosts from '../../../mirage/config/posts';
 import mockTags from '../../../mirage/config/themes';
-import {click, find, findAll, render, settled, waitUntil} from '@ember/test-helpers';
+import { click, find, findAll, render, settled, waitUntil } from '@ember/test-helpers';
-import {clickTrigger, selectChoose, typeInSearch} from 'ember-power-select/test-support/helpers';
+import { clickTrigger, selectChoose, typeInSearch } from 'ember-power-select/test-support/helpers';
-import {describe, it} from 'mocha';
+import { describe, it } from 'mocha';
-import {expect} from 'chai';
+import { expect } from 'chai';
-import {setupRenderingTest} from 'ember-mocha';
+import { setupRenderingTest } from 'ember-mocha';
-import {startMirage} from 'ghost-admin/initializers/ember-cli-mirage';
+import { startMirage } from 'ghost-admin/initializers/ember-cli-mirage';
-import {timeout} from 'ember-concurrency';
+import { timeout } from 'ember-concurrency';
-
+
-// NOTE: although Mirage has posts<->tags relationship and can respond
+// 注意：尽管Mirage中存在文章与标签的关联关系，且能响应带include=tags的请求
-// to :post-id/?include=tags all ordering information is lost so we
+//
-// need to build the tags array manually
+// 中文说明：
+// - 本集成测试依赖 Mirage 提供的 tags mock 数据及 API 路由，用于验证标签输入组件（GhPsmTagsInput）
+//   在不同场景下（渲染已选标签、本地/服务端搜索、创建/删除标签等）的行为是否正确。
+// - Mirage 在模拟时可能丢失后端在排序/pagination 上的一些真实细节（例如特定排序字段），
+//   因此测试中在需要断言顺序或构建复杂关联时，会手动调整或重建标签数组以保证一致性。
+// - 当修改 Mirage 工厂/序列化器或标签相关 API 时，请同时更新此测试以保持兼容性。
 const assignPostWithTags = async function postWithTags(context, ...slugs) {
+    // 获取ID为1的文章
     let post = await context.store.findRecord('post', 1);
+    // 获取所有标签
     let tags = await context.store.findAll('tag');
 
+    // 为文章添加指定slug的标签
     slugs.forEach((slug) => {
         post.get('tags').pushObject(tags.findBy('slug', slug));
     });
 
+    // 将文章设置到测试上下文并等待异步操作完成
     context.set('post', post);
     await settled();
 };
 
+// 描述"标签输入组件（GhPsmTagsInput）"的集成测试套件
 describe('Integration: Component: gh-psm-tags-input', function () {
+    // 设置渲染测试环境
     setupRenderingTest();
 
+    // 声明模拟服务器变量
     let server;
 
+    // 每个测试用例执行前的准备工作
     beforeEach(function () {
+        // 启动Mirage模拟服务器
         server = startMirage();
+        // 创建作者用户
         let author = server.create('user');
 
+        // 加载文章和标签的模拟数据配置
         mockPosts(server);
         mockTags(server);
 
-        server.create('post', {authors: [author]});
+        // 创建关联作者的文章
-        server.create('tag', {name: 'Tag 1', slug: 'one'});
+        server.create('post', { authors: [author] });
-        server.create('tag', {name: '#Tag 2', visibility: 'internal', slug: 'two'});
+        // 创建测试标签
-        server.create('tag', {name: 'Tag 3', slug: 'three'});
+        server.create('tag', { name: 'Tag 1', slug: 'one' });
-        server.create('tag', {name: 'Tag 4', slug: 'four'});
+        server.create('tag', { name: '#Tag 2', visibility: 'internal', slug: 'two' });
+        server.create('tag', { name: 'Tag 3', slug: 'three' });
+        server.create('tag', { name: 'Tag 4', slug: 'four' });
 
+        // 将数据存储服务设置到测试上下文
         this.set('store', this.owner.lookup('service:store'));
     });
 
+    // 每个测试用例执行后的清理工作
     afterEach(function () {
+        // 关闭模拟服务器
         server.shutdown();
     });
 
+    // 测试用例：渲染时显示已选择的标签
     it('shows selected tags on render', async function () {
+        // 为文章分配标签"one"和"three"
         await assignPostWithTags(this, 'one', 'three');
+        // 渲染标签输入组件
         await render(hbs`<GhPsmTagsInput @post={{post}} />`);
 
+        // 获取所有已选择的标签令牌
         let selected = findAll('.tag-token');
+        // 断言：显示2个已选择的标签
         expect(selected.length).to.equal(2);
+        // 断言：标签文本正确
         expect(selected[0]).to.contain.text('Tag 1');
         expect(selected[1]).to.contain.text('Tag 3');
     });
 
-    // skipped because FF 85 on Linux (CI) is failing. FF 85 on mac is fine.
+    // 测试用例：以字母顺序显示所有标签选项（因浏览器兼容性问题暂时跳过）
-    // possible difference in `localeCompare()` across systems
+    // 跳过原因：Linux上的FF 85（CI环境）失败，mac上的FF 85正常
+    // 可能是不同系统上`localeCompare()`的实现差异导致
     it.skip('exposes all tags as options sorted alphabetically', async function () {
+        // 获取ID为1的文章并设置到测试上下文
         this.set('post', this.store.findRecord('post', 1));
         await settled();
 
+        // 渲染标签输入组件
         await render(hbs`<GhPsmTagsInput @post={{post}} />`);
+        // 点击触发下拉选项
         await clickTrigger();
         await settled();
-        // unsure why settled() is sometimes not catching the update
+        // 不确定为什么settled()有时无法捕获更新，添加短暂延迟
         await timeout(100);
 
+        // 获取所有选项
         let options = findAll('.ember-power-select-option');
+        // 断言：显示4个标签选项
         expect(options.length).to.equal(4);
+        // 断言：选项按字母顺序排列
         expect(options[0]).to.contain.text('Tag 1');
         expect(options[1]).to.contain.text('#Tag 2');
         expect(options[2]).to.contain.text('Tag 3');
         expect(options[3]).to.contain.text('Tag 4');
     });
 
+    // 测试用例：如果第一页已加载所有标签，则使用本地搜索
     it('uses local search if all tags have been loaded in first page', async function () {
+        // 获取ID为1的文章并设置到测试上下文
         this.set('post', this.store.findRecord('post', 1));
         await settled();
 
+        // 渲染标签输入组件
         await render(hbs`<GhPsmTagsInput @post={{post}} />`);
+        // 点击触发下拉选项
         await clickTrigger();
         await settled();
 
+        // 记录当前请求次数
         const requestCount = server.pretender.handledRequests.length;
+        // 等待选项加载完成
         await waitUntil(() => findAll('.ember-power-select-option').length >= 4);
 
+        // 输入搜索关键词
         await typeInSearch('2');
         await settled();
 
+        // 断言：搜索未触发新的请求（使用本地搜索）
         expect(server.pretender.handledRequests.length).to.equal(requestCount);
     });
 
+    // 测试用例：如果通过滚动加载了所有标签，则使用本地搜索
     it('uses local search if all tags have been loaded by scrolling', async function () {
-        // create > 1 page of tags. Left-pad the names to ensure they're sorted alphabetically
+        // 创建超过1页的标签（150个）。左填充名称以确保按字母顺序排序
-        server.db.tags.remove(); // clear existing tags that will mess with alphabetical sorting
+        server.db.tags.remove(); // 清除可能干扰字母排序的现有标签
-        server.createList('tag', 150, {name: i => `Tag ${i.toString().padStart(3, '0')}`});
+        server.createList('tag', 150, { name: i => `Tag ${i.toString().padStart(3, '0')}` });
 
+        // 获取ID为1的文章并设置到测试上下文
         this.set('post', this.store.findRecord('post', 1));
         await settled();
 
+        // 渲染标签输入组件
         await render(hbs`<GhPsmTagsInput @post={{post}} />`);
+        // 点击触发下拉选项
         await clickTrigger();
-        // although we load 100 per page, we'll never have more 50 options rendered
+        // 尽管每页加载100个，但由于使用vertical-collection回收DOM元素，最多显示50个选项
-        // because we use vertical-collection to recycle dom elements on scroll
+        await waitUntil(
-        await waitUntil(() => findAll('.ember-power-select-option').length >= 50, {timeoutMessage: 'Timed out waiting for first page loaded state'});
+            () => findAll('.ember-power-select-option').length >= 50,
+            { timeoutMessage: '等待第一页加载超时' }
+        );
 
-        // scroll to the bottom of the options to load the next page
+        // 滚动到选项底部以加载下一页
         const optionsContent = find('.ember-power-select-options');
-        optionsContent.scrollTo({top: optionsContent.scrollHeight});
+        optionsContent.scrollTo({ top: optionsContent.scrollHeight });
         await settled();
 
-        // wait for second page to be loaded
+        // 等待第二页加载完成
-        await waitUntil(() => server.pretender.handledRequests.some(r => r.queryParams.page === '2'));
+        await waitUntil(
-        optionsContent.scrollTo({top: optionsContent.scrollHeight});
+            () => server.pretender.handledRequests.some(r => r.queryParams.page === '2')
-        await waitUntil(() => findAll('.ember-power-select-option').some(o => o.textContent.includes('Tag 105')), {timeoutMessage: 'Timed out waiting for second page loaded state'});
+        );
-
+        optionsContent.scrollTo({ top: optionsContent.scrollHeight });
-        // capture current request count - we test that it doesn't change to indicate a client-side filter
+        await waitUntil(
+            () => findAll('.ember-power-select-option').some(o => o.textContent.includes('Tag 105')),
+            { timeoutMessage: '等待第二页加载超时' }
+        );
+
+        // 记录当前请求次数 - 测试是否未发送新请求（表明使用客户端过滤）
         const requestCount = server.pretender.handledRequests.length;
+        // 输入搜索关键词
         await typeInSearch('21');
         await settled();
 
-        // wait until we're sure we've filtered
+        // 等待过滤完成
-        await waitUntil(() => findAll('.ember-power-select-option').length <= 5, {timeoutMessage: 'Timed out waiting for filtered state'});
+        await waitUntil(
+            () => findAll('.ember-power-select-option').length <= 5,
+            { timeoutMessage: '等待过滤状态超时' }
+        );
 
-        // request count should not increase if we've used client-side filtering
+        // 断言：请求次数未增加（使用客户端过滤）
         expect(server.pretender.handledRequests.length).to.equal(requestCount);
     });
 
+    // 描述"客户端搜索"的测试场景
     describe('client-side search', function () {
+        // 测试用例：匹配小写标签名称的选项
         it('matches options on lowercase tag names', async function () {
+            // 获取ID为1的文章并设置到测试上下文
             this.set('post', this.store.findRecord('post', 1));
             await settled();
 
+            // 渲染标签输入组件
             await render(hbs`<GhPsmTagsInput @post={{post}} />`);
+            // 点击触发下拉选项并输入搜索关键词
             await clickTrigger();
             await typeInSearch('2');
             await settled();
-            // unsure why settled() is sometimes not catching the update
+            // 不确定为什么settled()有时无法捕获更新，添加短暂延迟
             await timeout(100);
 
+            // 获取所有选项
             let options = findAll('.ember-power-select-option');
+            // 断言：显示2个匹配选项
             expect(options.length).to.equal(2);
+            // 断言：选项包含"Add "2"..."和"Tag 2"
             expect(options[0]).to.contain.text('Add "2"...');
             expect(options[1]).to.contain.text('Tag 2');
         });
 
+        // 测试用例：精确匹配时隐藏创建选项
         it('hides create option on exact matches', async function () {
+            // 获取ID为1的文章并设置到测试上下文
             this.set('post', this.store.findRecord('post', 1));
             await settled();
 
+            // 渲染标签输入组件
             await render(hbs`<GhPsmTagsInput @post={{post}} />`);
+            // 点击触发下拉选项并输入精确匹配的关键词
             await clickTrigger();
             await typeInSearch('#Tag 2');
             await settled();
-            // unsure why settled() is sometimes not catching the update
+            // 不确定为什么settled()有时无法捕获更新，添加短暂延迟
             await timeout(100);
 
+            // 获取所有选项
             let options = findAll('.ember-power-select-option');
+            // 断言：只显示1个精确匹配的选项
             expect(options.length).to.equal(1);
             expect(options[0]).to.contain.text('#Tag 2');
         });
 
+        // 测试用例：可以搜索包含单引号的标签
         it('can search for tags with single quotes', async function () {
-            server.create('tag', {name: 'O\'Nolan', slug: 'quote-test'});
+            // 创建包含单引号的标签
+            server.create('tag', { name: 'O\'Nolan', slug: 'quote-test' });
 
+            // 获取ID为1的文章并设置到测试上下文
             this.set('post', this.store.findRecord('post', 1));
             await settled();
 
+            // 渲染标签输入组件
             await render(hbs`<GhPsmTagsInput @post={{post}} />`);
+            // 点击触发下拉选项并输入包含单引号的搜索关键词
             await clickTrigger();
             await typeInSearch(`O'`);
             await settled();
 
+            // 获取所有选项
             let options = findAll('.ember-power-select-option');
+            // 断言：显示2个匹配选项
             expect(options.length).to.equal(2);
             expect(options[0]).to.contain.text(`Add "O'"...`);
             expect(options[1]).to.contain.text(`O'Nolan`);
         });
     });
 
+    // 描述"服务器端搜索"的测试场景（暂未实现测试用例）
     describe('server-side search', function () {
 
     });
 
+    // 测试用例：高亮显示内部标签
     it('highlights internal tags', async function () {
+        // 为文章分配标签"two"（内部标签）和"three"
         await assignPostWithTags(this, 'two', 'three');
+        // 渲染标签输入组件
         await render(hbs`<GhPsmTagsInput @post={{post}} />`);
 
+        // 获取所有已选择的标签令牌
         let selected = findAll('.tag-token');
+        // 断言：显示2个已选择的标签
         expect(selected.length).to.equal(2);
+        // 断言：内部标签有特殊样式类，普通标签没有
         expect(selected[0]).to.have.class('tag-token--internal');
         expect(selected[1]).to.not.have.class('tag-token--internal');
     });
 
+    // 描述"更新标签（updateTags）"的测试场景
     describe('updateTags', function () {
+        // 测试用例：修改文章的标签列表
         it('modifies post.tags', async function () {
+            // 为文章分配标签"two"和"three"
             await assignPostWithTags(this, 'two', 'three');
+            // 渲染标签输入组件
             await render(hbs`<GhPsmTagsInput @post={{post}} />`);
+            // 选择"Tag 1"标签
             await selectChoose('.ember-power-select-trigger', 'Tag 1');
 
+            // 断言：文章的标签列表已更新
             expect(
                 this.post.tags.mapBy('name').join(',')
             ).to.equal('#Tag 2,Tag 3,Tag 1');
         });
 
-        // TODO: skipped due to consistently random failures on Travis
+        // 测试用例：未选中时销毁新标签记录（因Travis上持续随机失败暂时跳过）
-        // '#ember-basic-dropdown-content-ember17494 Add "New"...' is not a valid selector
+        // 失败原因：选择器无效 '#ember-basic-dropdown-content-ember17494 Add "New"...'
-        // https://github.com/TryGhost/Ghost/issues/10308
+        // 相关Issue：https://github.com/TryGhost/Ghost/issues/10308
         it.skip('destroys new tag records when not selected', async function () {
+            // 为文章分配标签"two"和"three"
             await assignPostWithTags(this, 'two', 'three');
+            // 渲染标签输入组件
             await render(hbs`<GhPsmTagsInput @post={{post}} />`);
+            // 点击触发下拉选项，输入新标签名称并选择创建选项
             await clickTrigger();
             await typeInSearch('New');
             await settled();
             await selectChoose('.ember-power-select-trigger', 'Add "New"...');
 
+            // 断言：标签数量增加到5（原有4个+新增1个）
             let tags = await this.store.peekAll('tag');
             expect(tags.length).to.equal(5);
 
+            // 点击移除最后一个标签（新创建的标签）
             let removeBtns = findAll('.ember-power-select-multiple-remove-btn');
             await click(removeBtns[removeBtns.length - 1]);
 
+            // 断言：新标签记录已被销毁（标签数量回到4）
             tags = await this.store.peekAll('tag');
             expect(tags.length).to.equal(4);
         });
     });
 
+    // 描述"创建标签（createTag）"的测试场景
     describe('createTag', function () {
+        // 测试用例：创建新的标签记录
         it('creates new records', async function () {
+            // 为文章分配标签"two"和"three"
             await assignPostWithTags(this, 'two', 'three');
+            // 渲染标签输入组件
             await render(hbs`<GhPsmTagsInput @post={{post}} />`);
+            // 点击触发下拉选项，输入第一个新标签名称并选择创建选项
             await clickTrigger();
             await typeInSearch('New One');
             await settled();
             await selectChoose('.ember-power-select-trigger', '.ember-power-select-option', 0);
+            // 输入第二个新标签名称并选择创建选项
             await typeInSearch('New Two');
             await settled();
             await selectChoose('.ember-power-select-trigger', '.ember-power-select-option', 0);
 
+            // 断言：标签数量增加到6（原有4个+新增2个）
             let tags = await this.store.peekAll('tag');
             expect(tags.length).to.equal(6);
 
+            // 断言：新创建的标签记录处于isNew状态（未保存到服务器）
             expect(tags.findBy('name', 'New One').isNew).to.be.true;
             expect(tags.findBy('name', 'New Two').isNew).to.be.true;
         });
     });
-});
+});

ghost/admin/tests/integration/components/tabs/tabs-test.js

@@ -1,13 +1,23 @@
-import {click, findAll, render, triggerKeyEvent} from '@ember/test-helpers';
+import { click, findAll, render, triggerKeyEvent } from '@ember/test-helpers';
-import {describe, it} from 'mocha';
+import { describe, it } from 'mocha';
-import {expect} from 'chai';
+import { expect } from 'chai';
-import {hbs} from 'ember-cli-htmlbars';
+import { hbs } from 'ember-cli-htmlbars';
-import {setupRenderingTest} from 'ember-mocha';
+import { setupRenderingTest } from 'ember-mocha';
-
+
+/**
+ * 标签页组件（Tabs::Tabs）的集成测试
+ * 验证组件的渲染效果、交互行为及特殊配置的功能
+ */
 describe('Integration: Component: tabs/tabs', function () {
+    // 设置渲染测试环境
     setupRenderingTest();
 
+    /**
+     * 测试组件基础渲染效果
+     * 验证初始状态下标签按钮、面板的数量、选中状态及内容
+     */
     it('renders', async function () {
+        // 渲染标签页组件，包含2个标签和对应的面板
         await render(hbs`
             <Tabs::Tabs class="test-tab" as |tabs|>
                 <tabs.tab>Tab 1</tabs.tab>
@@ -17,27 +27,37 @@ describe('Integration: Component: tabs/tabs', function () {
                 <tabs.tabPanel>Content 2</tabs.tabPanel>
             </Tabs::Tabs>`);
 
+        // 获取标签按钮和面板元素
         const tabButtons = findAll('.tab');
         const tabPanels = findAll('.tab-panel');
 
-        expect(findAll('.test-tab').length).to.equal(1);
+        // 验证组件容器和列表结构
-        expect(findAll('.tab-list').length).to.equal(1);
+        expect(findAll('.test-tab').length).to.equal(1); // 组件容器存在
-        expect(tabPanels.length).to.equal(2);
+        expect(findAll('.tab-list').length).to.equal(1); // 标签列表容器存在
-        expect(tabButtons.length).to.equal(2);
+        expect(tabPanels.length).to.equal(2); // 面板数量正确
+        expect(tabButtons.length).to.equal(2); // 标签按钮数量正确
 
-        expect(findAll('.tab-selected').length).to.equal(1);
+        // 验证初始选中状态
-        expect(findAll('.tab-panel-selected').length).to.equal(1);
+        expect(findAll('.tab-selected').length).to.equal(1); // 只有一个选中的标签
-        expect(tabButtons[0]).to.have.class('tab-selected');
+        expect(findAll('.tab-panel-selected').length).to.equal(1); // 只有一个选中的面板
-        expect(tabPanels[0]).to.have.class('tab-panel-selected');
+        expect(tabButtons[0]).to.have.class('tab-selected'); // 第一个标签默认选中
+        expect(tabPanels[0]).to.have.class('tab-panel-selected'); // 第一个面板默认选中
 
+        // 验证标签按钮文本
         expect(tabButtons[0]).to.have.trimmed.text('Tab 1');
         expect(tabButtons[1]).to.have.trimmed.text('Tab 2');
 
+        // 验证面板内容（未选中的面板内容为空）
         expect(tabPanels[0]).to.have.trimmed.text('Content 1');
         expect(tabPanels[1]).to.have.trimmed.text('');
     });
 
+    /**
+     * 测试点击标签时的交互效果
+     * 验证点击后标签和面板的选中状态及内容切换
+     */
     it('renders expected content on click', async function () {
+        // 渲染标签页组件
         await render(hbs`
             <Tabs::Tabs class="test-tab" as |tabs|>
                 <tabs.tab>Tab 1</tabs.tab>
@@ -50,18 +70,26 @@ describe('Integration: Component: tabs/tabs', function () {
         const tabButtons = findAll('.tab');
         const tabPanels = findAll('.tab-panel');
 
+        // 点击第二个标签
         await click(tabButtons[1]);
 
+        // 验证选中状态切换
         expect(findAll('.tab-selected').length).to.equal(1);
         expect(findAll('.tab-panel-selected').length).to.equal(1);
-        expect(tabButtons[1]).to.have.class('tab-selected');
+        expect(tabButtons[1]).to.have.class('tab-selected'); // 第二个标签被选中
-        expect(tabPanels[1]).to.have.class('tab-panel-selected');
+        expect(tabPanels[1]).to.have.class('tab-panel-selected'); // 第二个面板被选中
 
+        // 验证面板内容切换（未选中的面板内容为空）
         expect(tabPanels[0]).to.have.trimmed.text('');
         expect(tabPanels[1]).to.have.trimmed.text('Content 2');
     });
 
+    /**
+     * 测试键盘事件对标签的控制
+     * 验证方向键、Home、End键的导航功能
+     */
     it('renders expected content on keyup event', async function () {
+        // 渲染包含3个标签的组件
         await render(hbs`
             <Tabs::Tabs class="test-tab" as |tabs|>
                 <tabs.tab>Tab 0</tabs.tab>
@@ -76,34 +104,45 @@ describe('Integration: Component: tabs/tabs', function () {
         const tabButtons = findAll('.tab');
         const tabPanels = findAll('.tab-panel');
 
+        // 辅助函数：验证指定索引的标签和面板处于选中状态且内容正确
         const isTabRenders = (num) => {
             expect(tabButtons[num]).to.have.class('tab-selected');
             expect(tabPanels[num]).to.have.class('tab-panel-selected');
-
             expect(tabPanels[num]).to.have.trimmed.text(`Content ${num}`);
         };
 
+        // 右方向键导航：从0→1→2
         await triggerKeyEvent(tabButtons[0], 'keyup', 'ArrowRight');
         await triggerKeyEvent(tabButtons[1], 'keyup', 'ArrowRight');
         isTabRenders(2);
 
+        // 右方向键循环：从2→0
         await triggerKeyEvent(tabButtons[2], 'keyup', 'ArrowRight');
         isTabRenders(0);
 
+        // 左方向键导航：从0→2
         await triggerKeyEvent(tabButtons[0], 'keyup', 'ArrowLeft');
         isTabRenders(2);
 
+        // 左方向键导航：从2→1
         await triggerKeyEvent(tabButtons[2], 'keyup', 'ArrowLeft');
         isTabRenders(1);
 
+        // Home键：跳转到第一个标签
         await triggerKeyEvent(tabButtons[0], 'keyup', 'Home');
         isTabRenders(0);
 
+        // End键：跳转到最后一个标签
         await triggerKeyEvent(tabButtons[0], 'keyup', 'End');
         isTabRenders(2);
     });
 
+    /**
+     * 测试forceRender参数的效果
+     * 验证开启后所有面板内容始终渲染（不随选中状态隐藏）
+     */
     it('renders content for all tabs with forceRender option', async function () {
+        // 渲染开启forceRender的标签页组件
         await render(hbs`
             <Tabs::Tabs class="test-tab" @forceRender={{true}} as |tabs|>
                 <tabs.tab>Tab 1</tabs.tab>
@@ -116,17 +155,21 @@ describe('Integration: Component: tabs/tabs', function () {
         const tabButtons = findAll('.tab');
         const tabPanels = findAll('.tab-panel');
 
+        // 初始状态：所有面板内容都渲染
         expect(tabPanels[0]).to.have.trimmed.text('Content 1');
         expect(tabPanels[1]).to.have.trimmed.text('Content 2');
 
+        // 点击第二个标签
         await click(tabButtons[1]);
 
+        // 选中状态正常切换
         expect(findAll('.tab-selected').length).to.equal(1);
         expect(findAll('.tab-panel-selected').length).to.equal(1);
         expect(tabButtons[1]).to.have.class('tab-selected');
         expect(tabPanels[1]).to.have.class('tab-panel-selected');
 
+        // 所有面板内容仍保持渲染（forceRender生效）
         expect(tabPanels[0]).to.have.trimmed.text('Content 1');
         expect(tabPanels[1]).to.have.trimmed.text('Content 2');
     });
-});
+});

ghost/admin/tests/integration/components/tags/tag-form-test.js

@@ -1,29 +1,36 @@
-// TODO: remove usage of Ember Data's private `Errors` class when refactoring validations
+// TODO: 重构验证逻辑时，移除对Ember Data私有类`Errors`的使用
 // eslint-disable-next-line
 import DS from 'ember-data';
 import EmberObject from '@ember/object';
 import Service from '@ember/service';
 import hbs from 'htmlbars-inline-precompile';
-import {blur, click, fillIn, find, findAll, render} from '@ember/test-helpers';
+import { blur, click, fillIn, find, findAll, render } from '@ember/test-helpers';
-import {describe, it} from 'mocha';
+import { describe, it } from 'mocha';
-import {expect} from 'chai';
+import { expect } from 'chai';
-import {setupRenderingTest} from 'ember-mocha';
+import { setupRenderingTest } from 'ember-mocha';
 
-const {Errors} = DS;
+// 从Ember Data中获取私有Errors类（用于模拟验证错误）
+const { Errors } = DS;
 
+// 配置服务桩：提供博客URL
 let configStub = Service.extend({
     blogUrl: 'http://localhost:2368'
 });
 
+// 媒体查询服务桩：控制移动端视图模拟
 let mediaQueriesStub = Service.extend({
-    maxWidth600: false
+    maxWidth600: false // 默认模拟非移动端
 });
 
+// 描述"标签表单组件（Tags::TagForm）"的集成测试套件（当前跳过测试）
 describe.skip('Integration: Component: tags/tag-form', function () {
+    // 设置渲染测试环境
     setupRenderingTest();
 
+    // 每个测试用例执行前的准备工作
     beforeEach(function () {
         /* eslint-disable camelcase */
+        // 创建模拟标签对象，包含基础属性和验证相关字段
         let tag = EmberObject.create({
             id: 1,
             name: 'Test',
@@ -31,38 +38,48 @@ describe.skip('Integration: Component: tags/tag-form', function () {
             description: 'Description.',
             metaTitle: 'Meta Title',
             metaDescription: 'Meta description',
-            errors: Errors.create(),
+            errors: Errors.create(), // 用于存储验证错误
-            hasValidated: []
+            hasValidated: [] // 用于记录已验证的字段
         });
         /* eslint-enable camelcase */
 
+        // 将标签对象和属性设置方法存入测试上下文
         this.set('tag', tag);
         this.set('setProperty', function (property, value) {
-            // this should be overridden if a call is expected
+            // 若未被覆盖，调用时会打印错误（用于捕获意外调用）
             // eslint-disable-next-line no-console
             console.error(`setProperty called '${property}: ${value}'`);
         });
 
+        // 注册服务桩，替换真实服务
         this.owner.register('service:config', configStub);
         this.owner.register('service:media-queries', mediaQueriesStub);
     });
 
+    // 测试用例：表单标题显示正确
     it('has the correct title', async function () {
+        // 渲染标签表单组件
         await render(hbs`
             <Tags::TagForm @tag={{this.tag}} @setProperty={{this.setProperty}} />
         `);
+        // 断言：现有标签的标题为"Tag settings"
         expect(find('.tag-settings-pane h4').textContent, 'existing tag title').to.equal('Tag settings');
 
+        // 切换为新标签（设置isNew属性）
         this.set('tag.isNew', true);
+        // 断言：新标签的标题为"New tag"
         expect(find('.tag-settings-pane h4').textContent, 'new tag title').to.equal('New tag');
     });
 
+    // 测试用例：正确渲染主要设置项
     it('renders main settings', async function () {
         await render(hbs`
             <Tags::TagForm @tag={{this.tag}} @setProperty={{this.setProperty}} />
         `);
 
+        // 断言：显示图片上传器
         expect(findAll('.gh-image-uploader').length, 'displays image uploader').to.equal(1);
+        // 断言：各字段值正确显示
         expect(find('input[name="name"]').value, 'name field value').to.equal('Test');
         expect(find('input[name="slug"]').value, 'slug field value').to.equal('test');
         expect(find('textarea[name="description"]').value, 'description field value').to.equal('Description.');
@@ -70,40 +87,48 @@ describe.skip('Integration: Component: tags/tag-form', function () {
         expect(find('textarea[name="metaDescription"]').value, 'metaDescription field value').to.equal('Meta description');
     });
 
+    // 测试用例：可在主要设置和元数据设置之间切换
     it('can switch between main/meta settings', async function () {
         await render(hbs`
             <Tags::TagForm @tag={{this.tag}} @setProperty={{this.setProperty}} />
         `);
 
+        // 断言：初始状态显示主要设置，隐藏元数据设置
         expect(find('.tag-settings-pane').classList.contains('settings-menu-pane-in'), 'main settings are displayed by default').to.be.true;
         expect(find('.tag-meta-settings-pane').classList.contains('settings-menu-pane-out-right'), 'meta settings are hidden by default').to.be.true;
 
+        // 点击"Meta Data"按钮切换到元数据设置
         await click('.meta-data-button');
 
+        // 断言：切换后隐藏主要设置，显示元数据设置
         expect(find('.tag-settings-pane').classList.contains('settings-menu-pane-out-left'), 'main settings are hidden after clicking Meta Data button').to.be.true;
         expect(find('.tag-meta-settings-pane').classList.contains('settings-menu-pane-in'), 'meta settings are displayed after clicking Meta Data button').to.be.true;
 
+        // 点击"back"按钮返回主要设置
         await click('.back');
 
+        // 断言：返回后显示主要设置，隐藏元数据设置
         expect(find('.tag-settings-pane').classList.contains('settings-menu-pane-in'), 'main settings are displayed after clicking "back"').to.be.true;
         expect(find('.tag-meta-settings-pane').classList.contains('settings-menu-pane-out-right'), 'meta settings are hidden after clicking "back"').to.be.true;
     });
 
+    // 测试用例：属性采用单向绑定（输入框值变化不直接修改源数据）
     it('has one-way binding for properties', async function () {
-        this.set('setProperty', function () {
+        // 覆盖setProperty为无操作（避免干扰测试）
-            // noop
+        this.set('setProperty', function () {});
-        });
 
         await render(hbs`
             <Tags::TagForm @tag={{this.tag}} @setProperty={{this.setProperty}} />
         `);
 
+        // 修改各输入框的值
         await fillIn('input[name="name"]', 'New name');
         await fillIn('input[name="slug"]', 'new-slug');
         await fillIn('textarea[name="description"]', 'New description');
         await fillIn('input[name="metaTitle"]', 'New metaTitle');
         await fillIn('textarea[name="metaDescription"]', 'New metaDescription');
 
+        // 断言：源标签对象的属性未被修改（单向绑定生效）
         expect(this.get('tag.name'), 'tag name').to.equal('Test');
         expect(this.get('tag.slug'), 'tag slug').to.equal('test');
         expect(this.get('tag.description'), 'tag description').to.equal('Description.');
@@ -111,19 +136,23 @@ describe.skip('Integration: Component: tags/tag-form', function () {
         expect(this.get('tag.metaDescription'), 'tag metaDescription').to.equal('Meta description');
     });
 
+    // 测试用例：所有字段失焦时触发setProperty动作
     it('triggers setProperty action on blur of all fields', async function () {
         let lastSeenProperty = '';
         let lastSeenValue = '';
 
+        // 覆盖setProperty记录最后一次调用的属性和值
         this.set('setProperty', function (property, value) {
             lastSeenProperty = property;
             lastSeenValue = value;
         });
 
+        // 辅助函数：测试字段失焦时是否正确触发setProperty
         let testSetProperty = async (selector, expectedProperty, expectedValue) => {
-            await click(selector);
+            await click(selector); // 聚焦字段
-            await fillIn(selector, expectedValue);
+            await fillIn(selector, expectedValue); // 输入值
-            await blur(selector);
+            await blur(selector); // 失焦
+            // 断言：触发的属性和值正确
             expect(lastSeenProperty, 'property').to.equal(expectedProperty);
             expect(lastSeenValue, 'value').to.equal(expectedValue);
         };
@@ -132,6 +161,7 @@ describe.skip('Integration: Component: tags/tag-form', function () {
             <Tags::TagForm @tag={{this.tag}} @setProperty={{this.setProperty}} />
         `);
 
+        // 测试所有字段
         await testSetProperty('input[name="name"]', 'name', 'New name');
         await testSetProperty('input[name="slug"]', 'slug', 'new-slug');
         await testSetProperty('textarea[name="description"]', 'description', 'New description');
@@ -139,10 +169,12 @@ describe.skip('Integration: Component: tags/tag-form', function () {
         await testSetProperty('textarea[name="metaDescription"]', 'metaDescription', 'New metaDescription');
     });
 
+    // 测试用例：显示已验证字段的错误信息
     it('displays error messages for validated fields', async function () {
         let errors = this.get('tag.errors');
         let hasValidated = this.get('tag.hasValidated');
 
+        // 为各字段添加验证错误并标记为已验证
         errors.add('name', 'must be present');
         hasValidated.push('name');
 
@@ -162,91 +194,121 @@ describe.skip('Integration: Component: tags/tag-form', function () {
             <Tags::TagForm @tag={{this.tag}} @setProperty={{this.setProperty}} />
         `);
 
+        // 验证name字段错误状态
         let nameFormGroup = find('input[name="name"]').closest('.form-group');
         expect(nameFormGroup, 'name form group has error state').to.have.class('error');
         expect(nameFormGroup.querySelector('.response'), 'name form group has error message').to.exist;
 
+        // 验证slug字段错误状态
         let slugFormGroup = find('input[name="slug"]').closest('.form-group');
         expect(slugFormGroup, 'slug form group has error state').to.have.class('error');
         expect(slugFormGroup.querySelector('.response'), 'slug form group has error message').to.exist;
 
+        // 验证description字段错误状态
         let descriptionFormGroup = find('textarea[name="description"]').closest('.form-group');
         expect(descriptionFormGroup, 'description form group has error state').to.have.class('error');
 
+        // 验证metaTitle字段错误状态
         let metaTitleFormGroup = find('input[name="metaTitle"]').closest('.form-group');
         expect(metaTitleFormGroup, 'metaTitle form group has error state').to.have.class('error');
         expect(metaTitleFormGroup.querySelector('.response'), 'metaTitle form group has error message').to.exist;
 
+        // 验证metaDescription字段错误状态
         let metaDescriptionFormGroup = find('textarea[name="metaDescription"]').closest('.form-group');
         expect(metaDescriptionFormGroup, 'metaDescription form group has error state').to.have.class('error');
         expect(metaDescriptionFormGroup.querySelector('.response'), 'metaDescription form group has error message').to.exist;
     });
 
+    // 测试用例：显示文本字段的字符计数
     it('displays char count for text fields', async function () {
         await render(hbs`
             <Tags::TagForm @tag={{this.tag}} @setProperty={{this.setProperty}} />
         `);
 
+        // 验证描述字段的字符计数（"Description." 共12个字符）
         let descriptionFormGroup = find('textarea[name="description"]').closest('.form-group');
         expect(descriptionFormGroup.querySelector('.word-count'), 'description char count').to.have.trimmed.text('12');
 
+        // 验证元描述字段的字符计数（"Meta description" 共16个字符）
         let metaDescriptionFormGroup = find('textarea[name="metaDescription"]').closest('.form-group');
         expect(metaDescriptionFormGroup.querySelector('.word-count'), 'description char count').to.have.trimmed.text('16');
     });
 
+    // 测试用例：正确渲染SEO标题预览
     it('renders SEO title preview', async function () {
         await render(hbs`
             <Tags::TagForm @tag={{this.tag}} @setProperty={{this.setProperty}} />
         `);
+        // 断言：存在metaTitle时显示metaTitle
         expect(find('.seo-preview-title').textContent, 'displays meta title if present').to.equal('Meta Title');
 
+        // 移除metaTitle
         this.set('tag.metaTitle', '');
+        // 断言：无metaTitle时回退到标签名称
         expect(find('.seo-preview-title').textContent, 'falls back to tag name without metaTitle').to.equal('Test');
 
+        // 设置超长名称（150个x）
         this.set('tag.name', (new Array(151).join('x')));
+        // 断言：标题被截断为70字符+省略号
         let expectedLength = 70 + '…'.length;
         expect(find('.seo-preview-title').textContent.length, 'cuts title to max 70 chars').to.equal(expectedLength);
     });
 
+    // 测试用例：正确渲染SEO URL预览
     it('renders SEO URL preview', async function () {
         await render(hbs`
             <Tags::TagForm @tag={{this.tag}} @setProperty={{this.setProperty}} />
         `);
+        // 断言：URL预览包含博客地址、标签路径和slug
         expect(find('.seo-preview-link').textContent, 'adds url and tag prefix').to.equal('http://localhost:2368/tag/test/');
 
+        // 设置超长slug（150个x）
         this.set('tag.slug', (new Array(151).join('x')));
+        // 断言：slug被截断为70字符+省略号
         let expectedLength = 70 + '…'.length;
         expect(find('.seo-preview-link').textContent.length, 'cuts slug to max 70 chars').to.equal(expectedLength);
     });
 
+    // 测试用例：正确渲染SEO描述预览
     it('renders SEO description preview', async function () {
         await render(hbs`
             <Tags::TagForm @tag={{this.tag}} @setProperty={{this.setProperty}} />
         `);
+        // 断言：存在metaDescription时显示metaDescription
         expect(find('.seo-preview-description').textContent, 'displays meta description if present').to.equal('Meta description');
 
+        // 移除metaDescription
         this.set('tag.metaDescription', '');
+        // 断言：无metaDescription时回退到描述
         expect(find('.seo-preview-description').textContent, 'falls back to tag description without metaDescription').to.equal('Description.');
 
+        // 设置超长描述（499个x）
         this.set('tag.description', (new Array(500).join('x')));
+        // 断言：描述被截断为156字符+省略号
         let expectedLength = 156 + '…'.length;
         expect(find('.seo-preview-description').textContent.length, 'cuts description to max 156 chars').to.equal(expectedLength);
     });
 
+    // 测试用例：接收新标签时重置表单状态
     it('resets if a new tag is received', async function () {
         await render(hbs`
             <Tags::TagForm @tag={{this.tag}} @setProperty={{this.setProperty}} />
         `);
+        // 切换到元数据设置面板
         await click('.meta-data-button');
         expect(find('.tag-meta-settings-pane').classList.contains('settings-menu-pane-in'), 'meta data pane is shown').to.be.true;
 
-        this.set('tag', EmberObject.create({id: '2'}));
+        // 设置新的标签对象
+        this.set('tag', EmberObject.create({ id: '2' }));
+        // 断言：表单重置为显示主要设置
         expect(find('.tag-settings-pane').classList.contains('settings-menu-pane-in'), 'resets to main settings').to.be.true;
     });
 
+    // 测试用例：点击删除按钮时触发删除模态框
     it('triggers delete tag modal on delete click', async function () {
         let openModalFired = false;
 
+        // 覆盖openModal方法标记为已触发
         this.set('openModal', () => {
             openModalFired = true;
         });
@@ -254,12 +316,16 @@ describe.skip('Integration: Component: tags/tag-form', function () {
         await render(hbs`
             <Tags::TagForm @tag={{this.tag}} @setProperty={{this.setProperty}} @showDeleteTagModal={{this.openModal}} />
         `);
+        // 点击删除按钮
         await click('.settings-menu-delete-button');
 
+        // 断言：删除模态框触发方法被调用
         expect(openModalFired).to.be.true;
     });
 
+    // 测试用例：移动端显示标签返回箭头链接
     it('shows tags arrow link on mobile', async function () {
+        // 获取媒体查询服务并设置为移动端（宽度≤600px）
         let mediaQueries = this.owner.lookup('service:media-queries');
         mediaQueries.set('maxWidth600', true);
 
@@ -267,6 +333,7 @@ describe.skip('Integration: Component: tags/tag-form', function () {
             <Tags::TagForm @tag={{this.tag}} @setProperty={{this.setProperty}} />
         `);
 
+        // 断言：移动端显示标签返回链接
         expect(findAll('.tag-settings-pane .settings-menu-header .settings-menu-header-action').length, 'tags link is shown').to.equal(1);
     });
-});
+});

ghost/admin/tests/integration/models/tag-test.js

@@ -1,71 +1,111 @@
-import {describe, it} from 'mocha';
+import { describe, it } from 'mocha';
-import {expect} from 'chai';
+import { expect } from 'chai';
-import {setupMirage} from 'ember-cli-mirage/test-support';
+import { setupMirage } from 'ember-cli-mirage/test-support';
-import {setupTest} from 'ember-mocha';
+import { setupTest } from 'ember-mocha';
-
+
+/**
+ * 标签模型（Model: tag）的集成测试
+ * 验证标签模型在各种操作下对搜索内容过期状态的影响
+ */
 describe('Integration: Model: tag', function () {
+    // 设置测试环境和Mirage模拟服务器
     const hooks = setupTest();
     setupMirage(hooks);
 
+    // 声明数据存储服务变量
     let store;
 
+    // 每个测试用例执行前的准备工作
     beforeEach(function () {
+        // 获取Ember的数据存储服务（store）
         store = this.owner.lookup('service:store');
     });
 
+    // 描述"搜索过期（search expiry）"的测试场景
     describe('search expiry', function () {
+        // 声明搜索服务变量
         let search;
 
+        // 每个子测试用例执行前的准备工作
         beforeEach(function () {
+            // 获取搜索服务
             search = this.owner.lookup('service:search');
+            // 初始设置搜索内容为未过期状态
             search.isContentStale = false;
         });
 
+        // 测试用例：创建标签时使搜索内容过期
         it('expires on create', async function () {
+            // 创建新标签记录
             const tagModel = await store.createRecord('tag');
             tagModel.name = 'Test tag';
+            // 保存标签到服务器
             await tagModel.save();
 
+            // 断言：搜索内容过期标志为true（创建操作触发过期）
             expect(search.isContentStale, 'stale flag after save').to.be.true;
         });
 
+        // 测试用例：删除标签时使搜索内容过期
         it('expires on delete', async function () {
+            // 在服务器端创建标签
             const serverTag = this.server.create('tag');
 
+            // 从数据存储中获取该标签
             const tagModel = await store.find('tag', serverTag.id);
+            // 删除标签
             await tagModel.destroyRecord();
 
+            // 断言：搜索内容过期标志为true（删除操作触发过期）
             expect(search.isContentStale, 'stale flag after delete').to.be.true;
         });
 
+        // 测试用例：修改标签名称时使搜索内容过期
         it('expires when name changed', async function () {
+            // 在服务器端创建标签
             const serverTag = this.server.create('tag');
 
+            // 从数据存储中获取该标签
             const tagModel = await store.find('tag', serverTag.id);
+            // 修改标签名称
             tagModel.name = 'New name';
+            // 保存修改
             await tagModel.save();
 
+            // 断言：搜索内容过期标志为true（名称修改触发过期）
             expect(search.isContentStale, 'stale flag after save').to.be.true;
         });
 
+        // 测试用例：修改标签URL（slug）时使搜索内容过期
         it('expires when url changed', async function () {
+            // 在服务器端创建标签
             const serverTag = this.server.create('tag');
 
+            // 从数据存储中获取该标签
             const tagModel = await store.find('tag', serverTag.id);
+            // 修改标签slug（URL的一部分）
             tagModel.slug = 'new-slug';
+            // 保存修改
             await tagModel.save();
 
+            // 断言：搜索内容过期标志为true（URL修改触发过期）
             expect(search.isContentStale, 'stale flag after save').to.be.true;
         });
 
+        // 测试用例：修改非名称字段时不使搜索内容过期
         it('does not expire on non-name change', async function () {
+            // 在服务器端创建标签
             const serverTag = this.server.create('tag');
 
+            // 从数据存储中获取该标签
             const tagModel = await store.find('tag', serverTag.id);
+            // 修改标签描述（非名称相关字段）
             tagModel.description = 'New description';
+            // 保存修改
             await tagModel.save();
 
+            // 断言：搜索内容过期标志为false（非名称修改不触发过期）
             expect(search.isContentStale, 'stale flag after save').to.be.false;
         });
     });
-});
+});

ghost/admin/tests/unit/models/tag-test.js

@@ -1,13 +1,24 @@
-import {describe, it} from 'mocha';
+import { describe, it } from 'mocha';
-import {expect} from 'chai';
+import { expect } from 'chai';
-import {setupTest} from 'ember-mocha';
+import { setupTest } from 'ember-mocha';
 
+/**
+ * 标签模型（Model: tag）的单元测试
+ * 验证模型的基础属性和行为
+ */
 describe('Unit: Model: tag', function () {
+    // 设置单元测试环境
     setupTest();
 
+    /**
+     * 测试用例：标签模型的验证类型（validationType）为"tag"
+     * 验证模型在验证逻辑中使用正确的类型标识
+     */
     it('has a validation type of "tag"', function () {
+        // 从数据存储服务创建一个标签模型实例
         let model = this.owner.lookup('service:store').createRecord('tag');
 
+        // 断言：模型的validationType属性值为"tag"
         expect(model.get('validationType')).to.equal('tag');
     });
-});
+});

ghost/core/core/frontend/helpers/tags.js

@@ -1,50 +1,106 @@
 // # Tags Helper
-// Usage: `{{tags}}`, `{{tags separator=' - '}}`
+// 用法: `{{tags}}`, `{{tags separator=' - '}}`
 //
-// Returns a string of the tags on the post.
+// 返回文章标签的字符串形式
-// By default, tags are separated by commas.
+// 默认情况下，标签之间用逗号分隔
 //
-// Note that the standard {{#each tags}} implementation is unaffected by this helper
+// 中文说明：
-const {urlService} = require('../services/proxy');
+// - 该 helper 在主题模板中用于渲染单个文章/页面的标签列表。
-const {SafeString, escapeExpression, templates} = require('../services/handlebars');
+// - 支持的参数说明：
+//   - autolink (boolean|string): 是否将标签渲染为链接（默认 true）。传入字符串 'false' 可关闭。
+//   - separator (string): 标签之间的分隔符，默认使用 ", ".
+//   - prefix / suffix (string): 输出的前缀与后缀，默认空字符串。
+//   - limit / from / to (number): 用于对标签进行切片（注意 from 是 1-based 索引）；
+//       如果同时指定 limit 与 from，会使用 limit+from 计算默认的 to 值。
+//   - visibility (string): 通过 helpers 的 visibility 工具进行过滤（public/internal）。
+//
+// 实现细节：
+// - 先通过 visibility.filter 对传入的 tags 进行可见性过滤并对每一项应用 processTag，
+//   processTag 根据 autolink 决定生成带 <a> 链接的 HTML 或纯文本（已转义）。
+// - 对结果数组应用 from/to/limit 的裁切逻辑（将 from 转为 0-based），然后用 separator 拼接。
+// - 最终使用 SafeString 返回，保证已生成的 HTML（例如标签链接）不会被 Handlebars 再次转义。
+//
+// 注意：此 helper 仅负责渲染表现层，标签的 URL 生成依赖于 `urlService.getUrlByResourceId`，
+// 如果修改了 URL 规则或可见性规则，应同步更新此 helper 的实现。
+const { urlService } = require('../services/proxy');
+const { SafeString, escapeExpression, templates } = require('../services/handlebars');
 
 const isString = require('lodash/isString');
 const ghostHelperUtils = require('@tryghost/helpers').utils;
 
 module.exports = function tags(options) {
+    // 处理可选参数，确保参数对象存在
     options = options || {};
     options.hash = options.hash || {};
 
+    // 解析参数：自动链接（默认开启）
+    // 如果autolink参数是字符串且值为'false'，则关闭自动链接
     const autolink = !(isString(options.hash.autolink) && options.hash.autolink === 'false');
+    
+    // 解析参数：分隔符（默认逗号加空格）
     const separator = isString(options.hash.separator) ? options.hash.separator : ', ';
+    
+    // 解析参数：前缀（默认空）
     const prefix = isString(options.hash.prefix) ? options.hash.prefix : '';
+    
+    // 解析参数：后缀（默认空）
     const suffix = isString(options.hash.suffix) ? options.hash.suffix : '';
+    
+    // 解析参数：限制数量（默认无限制）
     const limit = options.hash.limit ? parseInt(options.hash.limit, 10) : undefined;
+    
+    // 初始化输出字符串
     let output = '';
+    
+    // 解析参数：起始位置（默认1，1-based索引）
     let from = options.hash.from ? parseInt(options.hash.from, 10) : 1;
+    
+    // 解析参数：结束位置（默认无）
     let to = options.hash.to ? parseInt(options.hash.to, 10) : undefined;
 
+    /**
+     * 创建标签列表数组
+     * @param {Array} tagsList - 标签数组
+     * @returns {Array} 处理后的标签字符串数组
+     */
     function createTagList(tagsList) {
+        /**
+         * 处理单个标签
+         * @param {Object} tag - 标签对象
+         * @returns {string} 处理后的标签字符串（带链接或纯文本）
+         */
         function processTag(tag) {
+            // 如果开启自动链接，返回带链接的标签；否则返回纯文本标签
             return autolink ? templates.link({
-                url: urlService.getUrlByResourceId(tag.id, {withSubdirectory: true}),
+                url: urlService.getUrlByResourceId(tag.id, { withSubdirectory: true }), // 获取标签的URL
-                text: escapeExpression(tag.name)
+                text: escapeExpression(tag.name) // 转义标签名称，防止XSS
             }) : escapeExpression(tag.name);
         }
 
+        // 根据可见性筛选标签，并应用processTag处理
         return ghostHelperUtils.visibility.filter(tagsList, options.hash.visibility, processTag);
     }
 
+    // 如果存在标签且标签数组不为空
     if (this.tags && this.tags.length) {
+        // 生成处理后的标签列表数组
         output = createTagList(this.tags);
-        from -= 1; // From uses 1-indexed, but array uses 0-indexed.
+        
+        // 转换起始位置为0-based索引（因为from参数是1-based）
+        from -= 1;
+        
+        // 计算结束位置：如果指定了to则用to，否则用limit+from，否则用数组长度
         to = to || limit + from || output.length;
+        
+        // 截取指定范围的标签，并使用分隔符拼接
         output = output.slice(from, to).join(separator);
     }
 
+    // 如果有输出内容，添加前缀和后缀
     if (output) {
         output = prefix + output + suffix;
     }
 
+    // 返回安全字符串（防止Handlebars自动转义HTML）
     return new SafeString(output);
-};
+};

ghost/core/core/server/api/endpoints/posts.js

@@ -1,7 +1,7 @@
 const urlUtils = require('../../../shared/url-utils');
 const models = require('../../models');
 const getPostServiceInstance = require('../../services/posts/posts-service');
-const allowedIncludes = [
+const allowedIncludes = [ //允许包含的关联数据
     'tags',
     'authors',
     'authors.roles',
@@ -18,12 +18,13 @@ const allowedIncludes = [
     'post_revisions',
     'post_revisions.author'
 ];
-const unsafeAttrs = ['status', 'authors', 'visibility'];
+const unsafeAttrs = ['status', 'authors', 'visibility'];  //不安全属性列表
 
-const postsService = getPostServiceInstance();
+const postsService = getPostServiceInstance(); //文章服务实例
 
 /**
  * @param {string} event
+ * 根据文章状态变更事件生成缓存失效头信息
  */
 function getCacheHeaderFromEventString(event, dto) {
     if (event === 'published_updated' || event === 'unpublished') {
@@ -44,76 +45,98 @@ function getCacheHeaderFromEventString(event, dto) {
     }
 }
 
-/** @type {import('@tryghost/api-framework').Controller} */
+/**
+ * Ghost CMS 文章 API 控制器
+ * 提供对文章的各种操作的api 控制器
+ * 这个控制器实现了完整的文章 CRUD（创建、读取、更新、删除）操作，
+ * 以及批量操作、数据导出等高级功能。它遵循 Ghost API 框架规范，
+ * 每个端点都包含完整的配置：权限控制、参数验证、缓存管理等。
+ * 
+ * @type {import('@tryghost/api-framework').Controller}
+ */
 const controller = {
+    // 控制器文档名称，用于 API 文档生成
     docName: 'posts',
+    
+    /**
+     * 获取文章列表端点
+     * 支持分页、过滤、排序、字段选择等高级查询功能
+     */
     browse: {
         headers: {
-            cacheInvalidate: false
+            cacheInvalidate: false  // 列表查询不缓存失效
         },
         options: [
-            'include',
+            'include',      // 包含关联数据（标签、作者等）
-            'filter',
+            'filter',       // 过滤条件
-            'fields',
+            'fields',       // 选择返回字段
-            'collection',
+            'collection',   // 集合过滤
-            'formats',
+            'formats',      // 内容格式
-            'limit',
+            'limit',        // 分页大小
-            'order',
+            'order',        // 排序方式
-            'page',
+            'page',         // 页码
-            'debug',
+            'debug',        // 调试模式
-            'absolute_urls'
+            'absolute_urls' // 绝对URL
         ],
         validation: {
             options: {
                 include: {
-                    values: allowedIncludes
+                    values: allowedIncludes  // 只允许预定义的关联数据
                 },
                 formats: {
-                    values: models.Post.allowedFormats
+                    values: models.Post.allowedFormats  // 只允许支持的格式
                 }
             }
         },
         permissions: {
-            unsafeAttrs: unsafeAttrs
+            unsafeAttrs: unsafeAttrs  // 限制不安全属性修改
         },
         query(frame) {
-            return postsService.browsePosts(frame.options);
+            return postsService.browsePosts(frame.options);  // 调用服务层
         }
     },
 
+    /**
+     * 导出文章分析数据为 CSV 格式
+     * 用于数据分析和报表生成
+     */
     exportCSV: {
         options: [
-            'limit',
+            'limit',    // 导出数量限制
-            'filter',
+            'filter',   // 过滤条件
-            'order'
+            'order'     // 排序方式
         ],
         headers: {
             disposition: {
-                type: 'csv',
+                type: 'csv',  // 文件类型
                 value() {
                     const datetime = (new Date()).toJSON().substring(0, 10);
-                    return `post-analytics.${datetime}.csv`;
+                    return `post-analytics.${datetime}.csv`;  // 带时间戳的文件名
                 }
             },
-            cacheInvalidate: false
+            cacheInvalidate: false  // 导出操作不缓存失效
         },
         response: {
-            format: 'plain'
+            format: 'plain'  // 纯文本响应格式
         },
         permissions: {
-            method: 'browse'
+            method: 'browse'  // 复用浏览权限
         },
         validation: {},
         async query(frame) {
             return {
-                data: await postsService.export(frame)
+                data: await postsService.export(frame)  // 调用导出服务
             };
         }
     },
 
+    /**
+     * 获取单篇文章详情
+     * 支持通过 ID、slug 或 UUID 查询
+     */
     read: {
         headers: {
-            cacheInvalidate: false
+            cacheInvalidate: false  // 单篇文章查询不缓存失效
         },
         options: [
             'include',
@@ -121,14 +144,14 @@ const controller = {
             'formats',
             'debug',
             'absolute_urls',
-            // NOTE: only for internal context
+            // 内部上下文专用选项
-            'forUpdate',
+            'forUpdate',    // 用于更新操作
-            'transacting'
+            'transacting'    // 事务处理
         ],
         data: [
-            'id',
+            'id',    // 文章ID
-            'slug',
+            'slug',  // 文章别名
-            'uuid'
+            'uuid'   // 全局唯一标识
         ],
         validation: {
             options: {
@@ -144,19 +167,23 @@ const controller = {
             unsafeAttrs: unsafeAttrs
         },
         query(frame) {
-            return postsService.readPost(frame);
+            return postsService.readPost(frame);  // 调用读取服务
         }
     },
 
+    /**
+     * 创建新文章
+     * 状态码 201 表示创建成功
+     */
     add: {
-        statusCode: 201,
+        statusCode: 201,  // 创建成功状态码
         headers: {
-            cacheInvalidate: false
+            cacheInvalidate: false  // 默认不缓存失效
         },
         options: [
             'include',
             'formats',
-            'source'
+            'source'  // 内容来源（HTML）
         ],
         validation: {
             options: {
@@ -164,7 +191,7 @@ const controller = {
                     values: allowedIncludes
                 },
                 source: {
-                    values: ['html']
+                    values: ['html']  // 只支持HTML源
                 }
             }
         },
@@ -173,6 +200,7 @@ const controller = {
         },
         async query(frame) {
             const model = await models.Post.add(frame.data.posts[0], frame.options);
+            // 如果文章状态为已发布，则失效所有缓存
             if (model.get('status') === 'published') {
                 frame.setHeader('X-Cache-Invalidate', '/*');
             }
@@ -181,22 +209,26 @@ const controller = {
         }
     },
 
+    /**
+     * 编辑文章
+     * 支持智能缓存失效和事件处理
+     */
     edit: {
         headers: {
             /** @type {boolean | {value: string}} */
-            cacheInvalidate: false
+            cacheInvalidate: false  // 初始不缓存失效
         },
         options: [
             'include',
-            'id',
+            'id',                    // 必须提供文章ID
             'formats',
             'source',
-            'email_segment',
+            'email_segment',         // 邮件分段
-            'newsletter',
+            'newsletter',            // 新闻稿设置
-            'force_rerender',
+            'force_rerender',        // 强制重新渲染
-            'save_revision',
+            'save_revision',         // 保存修订版本
-            'convert_to_lexical',
+            'convert_to_lexical',    // 转换为Lexical格式
-            // NOTE: only for internal context
+            // 内部上下文专用选项
             'forUpdate',
             'transacting'
         ],
@@ -206,7 +238,7 @@ const controller = {
                     values: allowedIncludes
                 },
                 id: {
-                    required: true
+                    required: true  // ID为必填项
                 },
                 source: {
                     values: ['html']
@@ -218,12 +250,12 @@ const controller = {
         },
         async query(frame) {
             let model = await postsService.editPost(frame, {
-                eventHandler: (event, dto) => {
+                eventHandler: (event, dto) => {                // 事件处理器，根据文章状态变更智能处理缓存
                     const cacheInvalidate = getCacheHeaderFromEventString(event, dto);
                     if (cacheInvalidate === true) {
-                        frame.setHeader('X-Cache-Invalidate', '/*');
+                        frame.setHeader('X-Cache-Invalidate', '/*');  // 失效所有缓存
                     } else if (cacheInvalidate?.value) {
-                        frame.setHeader('X-Cache-Invalidate', cacheInvalidate.value);
+                        frame.setHeader('X-Cache-Invalidate', cacheInvalidate.value);  // 失效特定URL缓存
                     }
                 }
             });
@@ -232,62 +264,74 @@ const controller = {
         }
     },
 
+    /**
+     * 批量编辑文章
+     * 基于过滤条件对多篇文章执行相同操作
+     */
     bulkEdit: {
-        statusCode: 200,
+        statusCode: 200,  // 操作成功状态码
         headers: {
-            cacheInvalidate: true
+            cacheInvalidate: true  // 批量操作需要缓存失效
         },
         options: [
-            'filter'
+            'filter'  // 必须提供过滤条件
         ],
         data: [
-            'action',
+            'action',  // 操作类型（必填）
-            'meta'
+            'meta'     // 操作元数据
         ],
         validation: {
             data: {
                 action: {
-                    required: true
+                    required: true  // 操作类型为必填项
                 }
             },
             options: {
                 filter: {
-                    required: true
+                    required: true  // 过滤条件为必填项
                 }
             }
         },
         permissions: {
-            method: 'edit'
+            method: 'edit'  // 复用编辑权限
         },
         async query(frame) {
             return await postsService.bulkEdit(frame.data.bulk, frame.options);
         }
     },
 
+    /**
+     * 批量删除文章
+     * 基于过滤条件删除多篇文章
+     */
     bulkDestroy: {
         statusCode: 200,
         headers: {
-            cacheInvalidate: true
+            cacheInvalidate: true  // 删除操作需要缓存失效
         },
         options: [
-            'filter'
+            'filter'  // 必须提供过滤条件
         ],
         permissions: {
-            method: 'destroy'
+            method: 'destroy'  // 复用删除权限
         },
         async query(frame) {
             return await postsService.bulkDestroy(frame.options);
         }
     },
 
+    /**
+     * 删除单篇文章
+     * 状态码 204 表示无内容返回（删除成功）
+     */
     destroy: {
-        statusCode: 204,
+        statusCode: 204,  // 删除成功状态码（无内容）
         headers: {
-            cacheInvalidate: true
+            cacheInvalidate: true  // 删除操作需要缓存失效
         },
         options: [
             'include',
-            'id'
+            'id'  // 必须提供文章ID
         ],
         validation: {
             options: {
@@ -295,7 +339,7 @@ const controller = {
                     values: allowedIncludes
                 },
                 id: {
-                    required: true
+                    required: true  // ID为必填项
                 }
             }
         },
@@ -303,34 +347,39 @@ const controller = {
             unsafeAttrs: unsafeAttrs
         },
         query(frame) {
-            return models.Post.destroy({...frame.options, require: true});
+            return models.Post.destroy({...frame.options, require: true});  // 直接调用模型层
         }
     },
 
+    /**
+     * 复制文章
+     * 创建文章的副本，保留原文章内容但生成新的标识
+     */
     copy: {
-        statusCode: 201,
+        statusCode: 201,  // 创建成功状态码
         headers: {
             location: {
+                // 生成复制后文章的位置URL
                 resolve: postsService.generateCopiedPostLocationFromUrl
             },
-            cacheInvalidate: false
+            cacheInvalidate: false  // 复制操作不缓存失效
         },
         options: [
-            'id',
+            'id',       // 必须提供原文章ID
-            'formats'
+            'formats'   // 内容格式
         ],
         validation: {
             id: {
-                required: true
+                required: true  // ID为必填项
             }
         },
         permissions: {
-            method: 'add'
+            method: 'add'  // 复用添加权限
         },
         async query(frame) {
-            return postsService.copyPost(frame);
+            return postsService.copyPost(frame);  // 调用复制服务
         }
     }
 };
 
-module.exports = controller;
+module.exports = controller;

ghost/core/core/server/api/endpoints/tags-public.js

@@ -1,10 +1,36 @@
+/*
+ * Public Tags API controller
+ *
+ * Responsibilities:
+ * - Provide public endpoints for browsing and reading tags
+ * - Use models.TagPublic for public-safe queries/serialization
+ * - Validate allowed include parameters (e.g. count.posts)
+ * - Integrate cache provided by tagsPublicService when available
+ *
+ * Note: this controller is intentionally separate from the admin
+ * endpoints to ensure public/unauthenticated access uses the
+ * appropriate models/serialization and caching layers.
+ *
+ * 中文说明：
+ * 本文件为公开（无需管理员权限）标签相关 API 的控制器实现。
+ * - browse / read 两个方法暴露给前端或第三方在公共场景下读取标签数据。
+ * - 为了保证公开接口的安全性与性能，使用 `models.TagPublic`（只包含可公开的字段与序列化规则）。
+ * - 在允许的 include 参数上会进行验证（目前仅允许 `count.posts`），以避免不安全或昂贵的嵌入查询。
+ * - 若存在 `tagsPublicService.api.cache`，browse 方法会使用它来启用缓存以提高性能；但 cacheInvalidate header 默认为 false，控制器本身不负责主动失效缓存。
+ *
+ * 注意事项：
+ * - 管理端（admin）和公开端分离是刻意的设计，避免权限混淆与敏感字段外泄。
+ * - 若修改了可公开的字段集合或序列化逻辑，请同时更新对应的 models 与本处允许的 include 列表。
+ */
 const tpl = require('@tryghost/tpl');
 const errors = require('@tryghost/errors');
 const models = require('../../models');
 const tagsPublicService = require('../../services/tags-public');
 
+// 允许通过 include 参数包含的关联计数（仅允许对外公开的项）
 const ALLOWED_INCLUDES = ['count.posts'];
 
+// 本地化/模板消息（可以用于抛出用户友好的错误信息）
 const messages = {
     tagNotFound: 'Tag not found.'
 };

ghost/core/core/server/api/endpoints/tags.js

@@ -1,3 +1,24 @@
+/*
+ * Admin Tags API controller
+ *
+ * Responsibilities:
+ * - Provide admin endpoints for managing tags (browse/read/add/edit/destroy)
+ * - Enforce permission checks for admin operations
+ * - Validate allowed include parameters (e.g. count.posts)
+ * - Delegate core data operations to models.Tag
+ * - Trigger cache invalidation headers on changes
+ */
+/*
+ * 中文说明：
+ * 本文件为管理端（admin）标签相关 API 控制器，提供对标签的增删改查接口：
+ * - browse / read: 管理后台读取标签列表或单一标签（可包含 count.posts 等允许的 include）。
+ * - add / edit / destroy: 管理员权限下的写操作，会调用 `models.Tag` 执行数据变更。
+ *
+ * 关键注意事项：
+ * - 写操作会在必要时设置 `X-Cache-Invalidate` 以通知 CDN/缓存层清理缓存；read/browse 默认不主动失效缓存。
+ * - 本控制器启用了权限检查（permissions: true），只有具备管理员权限的请求才能执行写操作。
+ * - 如果修改了可包含的 include 列表或序列化规则，请同步更新 `ALLOWED_INCLUDES` 常量与模型/序列化逻辑。
+ */
 const tpl = require('@tryghost/tpl');
 const errors = require('@tryghost/errors');
 const models = require('../../models');

ghost/core/core/server/api/endpoints/themes.js

@@ -180,4 +180,4 @@ const controller = {
     }
 };
 
-module.exports = controller;
+module.exports = controller;

ghost/core/core/server/data/db/DatabaseStateManager.js

@@ -5,14 +5,14 @@ const metrics = require('@tryghost/metrics');
 
 const sentry = require('../../../shared/sentry');
 
-const states = {
+const states = { //定义数据库状态
     READY: 0,
     NEEDS_INITIALISATION: 1,
     NEEDS_MIGRATION: 2,
     ERROR: 3
 };
 
-const printState = ({state}) => {
+const printState = ({state}) => {  //打印当前数据库状态
     if (state === states.READY) {
         logging.info('Database is in a ready state.');
     }
@@ -37,12 +37,12 @@ class DatabaseStateManager {
         });
     }
 
-    async getState() {
+    async getState() {  //获得当前数据库状态
         let state = states.READY;
         try {
-            await this.knexMigrator.isDatabaseOK();
+            await this.knexMigrator.isDatabaseOK(); //await 起等待作用，如果有问题，它会率先等异步操作结束在进行
             return state;
-        } catch (error) {
+        } catch (error) {  //对错误状态进行处理
             // CASE: database has not yet been initialized
             if (error.code === 'DB_NOT_INITIALISED') {
                 state = states.NEEDS_INITIALISATION;
@@ -71,12 +71,12 @@ class DatabaseStateManager {
                 });
             }
 
-            sentry.captureException(errorToThrow);
+            sentry.captureException(errorToThrow);//记录错误信息
             throw errorToThrow;
         }
     }
 
-    async makeReady() {
+    async makeReady() { //将数据库状态设置为READY
         try {
             let state = await this.getState();
 
@@ -111,7 +111,7 @@ class DatabaseStateManager {
             state = await this.getState();
 
             printState({state});
-        } catch (error) {
+        } catch (error) { //对错误状态进行处理 
             let errorToThrow = error;
             if (!errors.utils.isGhostError(error)) {
                 errorToThrow = new errors.InternalServerError({

ghost/core/core/server/data/db/backup.js

@@ -12,6 +12,7 @@ const exporter = require('../exporter');
  * @param {object} exportResult
  * @param {string} exportResult.filename
  * @param {object} exportResult.data
+ * 文件写入功能
  */
 const writeExportFile = async (exportResult) => {
     const filename = path.resolve(urlUtils.urlJoin(config.get('paths').contentPath, 'data', exportResult.filename));
@@ -21,7 +22,8 @@ const writeExportFile = async (exportResult) => {
 };
 
 /**
- * @param {string} filename
+ * @param {string} fileName
+ * 文件读取功能
  */
 const readBackup = async (filename) => {
     const parsedFileName = path.parse(filename);
@@ -43,10 +45,11 @@ const readBackup = async (filename) => {
  *
  * @param {Object} options
  * @returns {Promise<String> | null}
+ * 数据库备份功能
  */
 const backup = async function backup(options = {}) {
     // do not create backup if disabled in config (this is intended for large customers who will OOM node)
-    if (config.get('disableJSBackups')) {
+    if (config.get('disableJSBackups')) {  //检查是否禁用了备份功能
         logging.info('Database backup is disabled in Ghost config');
         return null;
     }

ghost/core/core/server/data/db/connection.js

@@ -8,17 +8,17 @@ const config = require('../../../shared/config');
 const errors = require('@tryghost/errors');
 
 /** @type {knex.Knex} */
-let knexInstance;
+let knexInstance;  //执行的时候才会被赋予一个Knex实例
 
 // @TODO:
 // - if you require this file before config file was loaded,
 // - then this file is cached and you have no chance to connect to the db anymore
 // - bring dynamic into this file (db.connect())
 function configure(dbConfig) {
-    const client = dbConfig.client;
+    const client = dbConfig.client;  //获取但概念的客户端
 
-    if (client === 'sqlite3') {
+    if (client === 'sqlite3') {  //向后兼容性，如果使用的是sqlite3客户端
-        // Backwards compatibility with old knex behaviour
+        // Backwards compatibility with old knex behaviour  
         dbConfig.useNullAsDefault = Object.prototype.hasOwnProperty.call(dbConfig, 'useNullAsDefault') ? dbConfig.useNullAsDefault : true;
 
         // Enables foreign key checks and delete on cascade
@@ -38,6 +38,7 @@ function configure(dbConfig) {
         // In the default SQLite test config we set the path to /tmp/ghost-test.db,
         // but this won't work on Windows, so we need to replace the /tmp bit with
         // the Windows temp folder
+        // 在windows系统下的兼容性处理
         const filename = dbConfig.connection.filename;
         if (process.platform === 'win32' && _.isString(filename) && filename.match(/^\/tmp/)) {
             dbConfig.connection.filename = filename.replace(/^\/tmp/, os.tmpdir());
@@ -47,18 +48,19 @@ function configure(dbConfig) {
 
     if (client === 'mysql2') {
         dbConfig.connection.timezone = 'Z';
-        dbConfig.connection.charset = 'utf8mb4';
+        dbConfig.connection.charset = 'utf8mb4';   //编码方式的设置
-        dbConfig.connection.decimalNumbers = true;
+        dbConfig.connection.decimalNumbers = true; //是否将MySQL的DECIMAL类型转换为JavaScript的Number类型
 
-        if (process.env.REQUIRE_INFILE_STREAM) {
+        if (process.env.REQUIRE_INFILE_STREAM) {  //是否要求启用infile流
-            if (process.env.NODE_ENV === 'development' || process.env.ALLOW_INFILE_STREAM) {
+            if (process.env.NODE_ENV === 'development' || process.env.ALLOW_INFILE_STREAM) { //如果是在开发环境下，或者允许启用infile流
                 dbConfig.connection.infileStreamFactory = path => fs.createReadStream(path);
-            } else {
+            } else {//如果不是在开发环境下，并且不允许启用infile流
                 throw new errors.InternalServerError({message: 'MySQL infile streaming is required to run the current process, but is not allowed. Run the script in development mode or set ALLOW_INFILE_STREAM=1.'});
             }
         }
     }
-
+    //如果前两个if都没成功的话，就会返回原始的dbConfig对象
+    //返回数据库配置对象
     return dbConfig;
 }
 

ghost/core/core/server/data/exporter/export-filename.js

@@ -1,32 +1,70 @@
+/**
+ * 数据库导出文件名生成模块
+ * 
+ * 负责为 Ghost 数据库备份文件生成智能、安全的文件名
+ * 文件名格式：{站点标题}.ghost.{时间戳}.json
+ * 
+ * @module exporter/export-filename
+ */
+
 const _ = require('lodash');
 const logging = require('@tryghost/logging');
 const errors = require('@tryghost/errors');
 const security = require('@tryghost/security');
 const models = require('../../models');
 
+/**
+ * 数据库模型查询选项配置
+ * 使用内部上下文权限访问设置数据
+ */
 const modelOptions = {context: {internal: true}};
 
+/**
+ * 生成数据库导出文件的文件名
+ * 
+ * 文件名生成规则：
+ * 1. 如果提供了自定义文件名，直接使用
+ * 2. 否则生成格式：{站点标题}.ghost.{年-月-日-时-分-秒}.json
+ * 3. 包含安全过滤和错误处理机制
+ * 
+ * @param {Object} [options] - 配置选项
+ * @param {string} [options.filename] - 自定义文件名（不含后缀）
+ * @param {Object} [options.transacting] - 事务对象
+ * @returns {Promise<string>} 生成的完整文件名（包含 .json 后缀）
+ *  
+ */
 const exportFileName = async function exportFileName(options) {
+    // 生成当前时间戳，格式：年-月-日-时-分-秒
     const datetime = require('moment')().format('YYYY-MM-DD-HH-mm-ss');
-    let title = '';
+    let title = ''; // 站点标题部分，默认为空
 
+    // 确保 options 参数不为空
     options = options || {};
-
+ 
-    // custom filename
+    if (options.filename) {   //对文件名进行处理
-    if (options.filename) {
         return options.filename + '.json';
     }
 
     try {
-        const settingsTitle = await models.Settings.findOne({key: 'title'}, _.merge({}, modelOptions, _.pick(options, 'transacting')));
+        /**
+         * 从数据库查询站点标题设置
+         * 使用内部权限上下文，支持事务传递
+         */
+        const settingsTitle = await models.Settings.findOne(
+            {key: 'title'}, 
+            _.merge({}, modelOptions, _.pick(options, 'transacting'))
+        );
 
-        if (settingsTitle) {
+        // 如果成功获取到站点标题，进行安全过滤处理
-            title = security.string.safe(settingsTitle.get('value')) + '.';
+        if (settingsTitle) { 
+            title = security.string.safe(settingsTitle.get('value')) + '.';  //对站点标题进行安全性过滤，移除一些可能会出问题的字符
         }
 
-        return title + 'ghost.' + datetime + '.json';
+        return title + 'ghost.' + datetime + '.json';   //返回完整的文件名格式
-    } catch (err) {
+    } catch (err) { 
-        logging.error(new errors.InternalServerError({err: err}));
+        logging.error(new errors.InternalServerError({err: err}));  //错误处理机制，记录错误日志
+        
+        // 错误情况下返回默认文件名：ghost.{时间戳}.json
         return 'ghost.' + datetime + '.json';
     }
 };

ghost/core/core/server/data/exporter/exporter.js

@@ -9,12 +9,12 @@ const {sequence} = require('@tryghost/promise');
 const messages = {
     errorExportingData: 'Error exporting data'
 };
-
+//负责将数据库内容到处为可移植的json格式
 const {
     TABLES_ALLOWLIST,
     SETTING_KEYS_BLOCKLIST
 } = require('./table-lists');
-
+//单表导出函数 会在后面被调用
 const exportTable = function exportTable(tableName, options) {
     if (TABLES_ALLOWLIST.includes(tableName) ||
         (options.include && _.isArray(options.include) && options.include.indexOf(tableName) !== -1)) {
@@ -23,25 +23,25 @@ const exportTable = function exportTable(tableName, options) {
         return query.select();
     }
 };
-
+//数据过滤函数，移除黑名单中的设置项
-const getSettingsTableData = function getSettingsTableData(settingsData) {
+const getSettingsTableData = function getSettingsTableData(settingsData) { 
     return settingsData && settingsData.filter((setting) => {
         return !SETTING_KEYS_BLOCKLIST.includes(setting.key);
     });
 };
 
-const doExport = async function doExport(options) {
+const doExport = async function doExport(options) {//导出主函数
-    options = options || {include: []};
+    options = options || {include: []};//默认选项，包含所有表
 
     try {
         const tables = await commands.getTables(options.transacting);
-
+        //并行导出所有表的数据
         const tableData = await sequence(tables.map(tableName => async () => {
             return exportTable(tableName, options);
         }));
 
         const exportData = {
-            meta: {
+            meta: { //导出元数据，包含导出时间和Ghost版本
                 exported_on: new Date().getTime(),
                 version: ghostVersion.full
             },
@@ -50,7 +50,7 @@ const doExport = async function doExport(options) {
             }
         };
 
-        tables.forEach((name, i) => {
+        tables.forEach((name, i) => {//导出数据到导出的结构之中，设置信息，普通的表格信息
             if (name === 'settings') {
                 exportData.data[name] = getSettingsTableData(tableData[i]);
             } else {

ghost/core/core/server/data/exporter/table-lists.js

@@ -1,4 +1,5 @@
 // NOTE: these tables can be optionally included to have full db-like export
+//比较重要的表，需要导出进行操作
 const BACKUP_TABLES = [
     'actions',
     'api_keys',

ghost/core/core/server/data/importer/handlers/image.js

@@ -4,7 +4,7 @@ const config = require('../../../../shared/config');
 const urlUtils = require('../../../../shared/url-utils');
 const storage = require('../../../adapters/storage');
 let ImageHandler;
-
+//各种类型文本的导入处理程序
 ImageHandler = {
     type: 'images',
     extensions: config.get('uploads').images.extensions,
@@ -12,29 +12,32 @@ ImageHandler = {
     directories: ['images', 'content'],
 
     loadFile: function (files, baseDir) {
-        const store = storage.getStorage('images');
+        const store = storage.getStorage('images');  // 获取图像存储适配器
         const baseDirRegex = baseDir ? new RegExp('^' + baseDir + '/') : new RegExp('');
-
+        
+        // 创建Ghost静态文件URL前缀的正则表达式
         const imageFolderRegexes = _.map(store.staticFileURLPrefix.split('/'), function (dir) {
             return new RegExp('^' + dir + '/');
         });
 
         // normalize the directory structure
         files = _.map(files, function (file) {
-            const noBaseDir = file.name.replace(baseDirRegex, '');
+            const noBaseDir = file.name.replace(baseDirRegex, '');  // 移除基础目录
             let noGhostDirs = noBaseDir;
-
+        
+            // 移除Ghost特定的目录前缀
             _.each(imageFolderRegexes, function (regex) {
                 noGhostDirs = noGhostDirs.replace(regex, '');
             });
-
+        
-            file.originalPath = noBaseDir;
+            file.originalPath = noBaseDir;  // 保存原始路径（不含基础目录）
-            file.name = noGhostDirs;
+            file.name = noGhostDirs;       // 标准化后的文件名
             file.targetDir = path.join(config.getContentPath('images'), path.dirname(noGhostDirs));
             return file;
         });
 
         return Promise.all(files.map(function (image) {
+            //构建新的url路径
             return store.getUniqueFileName(image, image.targetDir).then(function (targetFilename) {
                 image.newPath = urlUtils.urlJoin('/', urlUtils.getSubdir(), store.staticFileURLPrefix,
                     path.relative(config.getContentPath('images'), targetFilename));
@@ -45,4 +48,4 @@ ImageHandler = {
     }
 };
 
-module.exports = ImageHandler;
+module.exports = ImageHandler;

ghost/core/core/server/data/importer/handlers/markdown.js

@@ -1,108 +1,155 @@
 const _ = require('lodash');
 const fs = require('fs-extra');
 const moment = require('moment');
-const featuredImageRegex = /^(!\[]\(([^)]*?)\)\s+)(?=#)/;
+
-const titleRegex = /^#\s?([\w\W]*?)(?=\n)/;
+// 正则表达式用于匹配Markdown文件中的不同部分
-const statusRegex = /(published||draft)-/;
+const featuredImageRegex = /^(!\[]\(([^)]*?)\)\s+)(?=#)/; // 匹配特色图片：以 ![alt](url) 格式开头，后面跟着 #
-const dateRegex = /(\d{4}-\d{2}-\d{2})-/;
+const titleRegex = /^#\s?([\w\W]*?)(?=\n)/; // 匹配标题：以 # 开头，直到换行符
+const statusRegex = /(published|draft)-/; // 匹配状态：published- 或 draft-
+const dateRegex = /(\d{4}-\d{2}-\d{2})-/; // 匹配日期：YYYY-MM-DD 格式
+
 let processDateTime;
 let processFileName;
 let processMarkdownFile;
 let MarkdownHandler;
 
-// Takes a date from the filename in y-m-d-h-m form, and converts it into a Date ready to import
+/**
+ * 处理日期时间，将文件名中的日期时间转换为可导入的Date对象
+ * @param {Object} post - 文章对象
+ * @param {string} datetime - 日期时间字符串 (格式: YYYY-MM-DD-HH-mm)
+ * @returns {Object} 更新后的文章对象
+ */
 processDateTime = function (post, datetime) {
     const format = 'YYYY-MM-DD-HH-mm';
+    // 将日期时间字符串转换为时间戳（UTC时间）
     datetime = moment.utc(datetime, format).valueOf();
 
+    // 根据文章状态设置发布时间或创建时间
     if (post.status && post.status === 'published') {
-        post.published_at = datetime;
+        post.published_at = datetime; // 已发布文章设置发布时间
     } else {
-        post.created_at = datetime;
+        post.created_at = datetime; // 草稿文章设置创建时间
     }
 
     return post;
 };
 
+/**
+ * 处理文件名，从中提取文章状态、日期和slug信息
+ * @param {string} filename - 文件名（不含扩展名）
+ * @returns {Object} 包含文章基本信息的对象
+ */
 processFileName = function (filename) {
     let post = {};
-    let name = filename.split('.')[0];
+    let name = filename.split('.')[0]; // 移除文件扩展名
     let match;
 
-    // Parse out the status
+    // 解析文章状态（published 或 draft）
     match = name.match(statusRegex);
     if (match) {
-        post.status = match[1];
+        post.status = match[1]; // 提取状态
-        name = name.replace(match[0], '');
+        name = name.replace(match[0], ''); // 从文件名中移除状态部分
     }
 
-    // Parse out the date
+    // 解析日期
     match = name.match(dateRegex);
     if (match) {
-        name = name.replace(match[0], '');
+        name = name.replace(match[0], ''); // 从文件名中移除日期部分
-        // Default to middle of the day
+        // 默认设置为中午12点，并处理日期时间
         post = processDateTime(post, match[1] + '-12-00');
     }
 
+    // 设置slug和默认标题（使用处理后的文件名）
     post.slug = name;
     post.title = name;
 
     return post;
 };
 
+/**
+ * 处理Markdown文件内容，提取特色图片、标题和正文
+ * @param {string} filename - 文件名
+ * @param {string} content - 文件内容
+ * @returns {Object} 完整的文章对象
+ */
 processMarkdownFile = function (filename, content) {
+    // 首先从文件名中提取基本信息
     const post = processFileName(filename);
     let match;
 
+    // 统一换行符为Unix风格
     content = content.replace(/\r\n/gm, '\n');
 
-    // parse out any image which appears before the title
+    // 解析标题前的特色图片
     match = content.match(featuredImageRegex);
     if (match) {
-        content = content.replace(match[1], '');
+        content = content.replace(match[1], ''); // 从内容中移除图片标记
-        post.image = match[2];
+        post.image = match[2]; // 保存图片URL
     }
 
-    // try to parse out a heading 1 for the title
+    // 解析一级标题作为文章标题
     match = content.match(titleRegex);
     if (match) {
-        content = content.replace(titleRegex, '');
+        content = content.replace(titleRegex, ''); // 从内容中移除标题标记
-        post.title = match[1];
+        post.title = match[1]; // 保存标题内容
     }
 
+    // 移除开头多余的换行符
     content = content.replace(/^\n+/, '');
 
+    // 保存处理后的Markdown正文
     post.markdown = content;
 
     return post;
 };
 
+/**
+ * Markdown处理器 - 主要模块
+ * 用于处理Markdown文件的导入和解析
+ */
 MarkdownHandler = {
-    type: 'data',
+    type: 'data', // 处理器类型
-    extensions: ['.md', '.markdown'],
+    extensions: ['.md', '.markdown'], // 支持的文件扩展名
-    contentTypes: ['application/octet-stream', 'text/plain'],
+    contentTypes: ['application/octet-stream', 'text/plain'], // 支持的内容类型
-    directories: [],
+    directories: [], // 处理的目录
-
+
+    /**
+     * 加载并处理多个Markdown文件
+     * @param {Array} files - 文件对象数组
+     * @param {string} startDir - 起始目录（用于路径处理）
+     * @returns {Promise} 返回包含处理结果的Promise
+     */
     loadFile: function (files, startDir) {
+        // 创建正则表达式用于移除起始目录前缀
         const startDirRegex = startDir ? new RegExp('^' + startDir + '/') : new RegExp('');
-        const posts = [];
+        const posts = []; // 存储处理后的文章
-        const ops = [];
+        const ops = []; // 存储文件读取操作
 
+        // 遍历所有文件
         _.each(files, function (file) {
+            // 对每个文件创建读取和处理操作
             ops.push(fs.readFile(file.path).then(function (content) {
-                // normalize the file name
+                // 规范化文件名（移除起始目录前缀）
                 file.name = file.name.replace(startDirRegex, '');
-                // don't include deleted posts
+                
+                // 跳过已删除的文章（文件名以"deleted"开头）
                 if (!/^deleted/.test(file.name)) {
+                    // 处理Markdown文件并添加到文章列表
                     posts.push(processMarkdownFile(file.name, content.toString()));
                 }
             }));
         });
 
+        // 等待所有文件处理完成
         return Promise.all(ops).then(function () {
-            return {meta: {}, data: {posts: posts}};
+            // 返回标准格式的数据
+            return {
+                meta: {}, // 元数据（当前为空）
+                data: {posts: posts} // 文章数据
+            };
         });
     }
 };
 
-module.exports = MarkdownHandler;
+// 导出Markdown处理器模块
+module.exports = MarkdownHandler;

ghost/core/core/server/data/importer/import-manager.js

@@ -52,10 +52,12 @@ let defaults = {
     contentTypes: ['application/zip', 'application/x-zip-compressed'],
     directories: []
 };
-
+/* 导入管理类，负责处理从各种格式的文件导入数据到Ghost系统的完整流程。
+ * 负责导入图片、媒体文件、内容文件、Revue数据、JSON数据、Markdown数据等。
+*/
 class ImportManager {
     constructor() {
-        const mediaHandler = new ImporterContentFileHandler({
+        const mediaHandler = new ImporterContentFileHandler({//媒体文件导入处理程序
             type: 'media',
             // @NOTE: making the second parameter strict folder "content/media" brakes the glob pattern
             //        in the importer, so we need to keep it as general "content" unless
@@ -69,7 +71,7 @@ class ImportManager {
             storage: mediaStorage
         });
 
-        const filesHandler = new ImporterContentFileHandler({
+        const filesHandler = new ImporterContentFileHandler({//文件导入处理程序
             type: 'files',
             // @NOTE: making the second parameter strict folder "content/files" brakes the glob pattern
             //        in the importer, so we need to keep it as general "content" unless
@@ -82,12 +84,12 @@ class ImportManager {
             urlUtils: urlUtils,
             storage: fileStorage
         });
-
+        //导入器初始化
-        const imageImporter = new ContentFileImporter({
+        const imageImporter = new ContentFileImporter({ 
             type: 'images',
             store: imageStorage
         });
-        const mediaImporter = new ContentFileImporter({
+        const mediaImporter = new ContentFileImporter({ 
             type: 'media',
             store: mediaStorage
         });
@@ -98,25 +100,25 @@ class ImportManager {
         });
 
         /**
-         * @type {Importer[]} importers
+         * @type {Importer[]} importers 导入器数组，包含图片导入器、媒体文件导入器、内容文件导入器、Revue导入器和数据导入器。
          */
         this.importers = [imageImporter, mediaImporter, contentFilesImporter, RevueImporter, DataImporter];
 
         /**
-         * @type {Handler[]}
+         * @type {Handler[]} handlers 处理程序数组，包含图片处理程序、媒体文件处理程序、文件处理程序、Revue处理程序和JSON处理程序。
          */
         this.handlers = [ImageHandler, mediaHandler, filesHandler, RevueHandler, JSONHandler, MarkdownHandler];
 
         // Keep track of file to cleanup at the end
         /**
-         * @type {?string}
+         * @type {?string} fileToDelete 待删除的文件路径，初始值为null。
          */
         this.fileToDelete = null;
     }
 
     /**
      * Get an array of all the file extensions for which we have handlers
-     * @returns {string[]}
+     * @returns {string[]} extensions 所有支持的文件扩展名数组。
      */
     getExtensions() {
         return _.union(_.flatMap(this.handlers, 'extensions'), defaults.extensions);
@@ -124,7 +126,8 @@ class ImportManager {
 
     /**
      * Get an array of all the mime types for which we have handlers
-     * @returns {string[]}
+     * @returns {string[]} contentTypes 所有支持的文件MIME类型数组。
+     * 获取导入管理器的所有支持类型
      */
     getContentTypes() {
         return _.union(_.flatMap(this.handlers, 'contentTypes'), defaults.contentTypes);
@@ -132,7 +135,7 @@ class ImportManager {
 
     /**
      * Get an array of directories for which we have handlers
-     * @returns {string[]}
+     * @returns {string[]} directories 所有支持的文件目录数组。
      */
     getDirectories() {
         return _.union(_.flatMap(this.handlers, 'directories'), defaults.directories);
@@ -140,8 +143,8 @@ class ImportManager {
 
     /**
      * Convert items into a glob string
-     * @param {String[]} items
+     * @param {String[]} items 要转换的文件扩展名数组。
-     * @returns {String}
+     * @returns {String} globPattern 转换后的文件扩展名glob模式字符串。
      */
     getGlobPattern(items) {
         return '+(' + _.reduce(items, function (memo, ext) {
@@ -150,9 +153,9 @@ class ImportManager {
     }
 
     /**
-     * @param {String[]} extensions
+     * @param {String[]} extensions 要匹配的文件扩展名数组。
-     * @param {Number} [level]
+     * @param {Number} [level=ROOT_OR_SINGLE_DIR] 匹配级别，默认值为ROOT_OR_SINGLE_DIR。
-     * @returns {String}
+     * @returns {String} globPattern 转换后的文件扩展名glob模式字符串。
      */
     getExtensionGlob(extensions, level) {
         const prefix = level === ALL_DIRS ? '**/*' :
@@ -163,9 +166,9 @@ class ImportManager {
 
     /**
      *
-     * @param {String[]} directories
+     * @param {String[]} directories 要匹配的文件目录数组。
-     * @param {Number} [level]
+     * @param {Number} [level=ROOT_OR_SINGLE_DIR] 匹配级别，默认值为ROOT_OR_SINGLE_DIR。
-     * @returns {String}
+     * @returns {String} globPattern 转换后的文件目录glob模式字符串。
      */
     getDirectoryGlob(directories, level) {
         const prefix = level === ALL_DIRS ? '**/' :
@@ -617,4 +620,4 @@ class ImportManager {
 /**
  * @typedef {Object} ImportResult
  */
-module.exports = new ImportManager();
+module.exports = new ImportManager();

ghost/core/core/server/data/schema/commands.js

@@ -1,73 +1,102 @@
-const _ = require('lodash');
+//这里是基本的外部链接，让之后的一些操作可以直接进行使用
-const logging = require('@tryghost/logging');
+const _ = require('lodash');    // 工具库
-const errors = require('@tryghost/errors');
+const logging = require('@tryghost/logging'); // 日志
-const tpl = require('@tryghost/tpl');
+const errors = require('@tryghost/errors'); // 错误处理
-const db = require('../db');
+const tpl = require('@tryghost/tpl'); // 模板
-const DatabaseInfo = require('@tryghost/database-info');
+const db = require('../db');  // 数据库连接
-const schema = require('./schema');
+const DatabaseInfo = require('@tryghost/database-info'); // 数据库信息
-
+const schema = require('./schema');  // 数据库模型里面各种表的定义
-const messages = {
+
+const messages = {   //相关的错误提示
     hasPrimaryKeySQLiteError: 'Must use hasPrimaryKeySQLite on an SQLite3 database',
     hasForeignSQLite3: 'Must use hasForeignSQLite3 on an SQLite3 database',
     noSupportForDatabase: 'No support for database client {client}'
 };
+//这个地方都是实现sql语句功能的函数
 
 /**
- * @param {string} tableName
+ * 根据schema.js中的定义来创建数据库中的表
- * @param {import('knex').knex.TableBuilder} tableBuilder
+ * 
- * @param {string} columnName
+ * @param {string} tableName - 表名，用于从 schema.js 中获取字段定义
- * @param {object} [columnSpec]
+ * @param {Object} tableBuilder - Knex.js 的表构建器对象，用于创建字段
+ * @param {string} columnName - 字段名
+ * @param {Object} [columnSpec] - 字段定义对象，如果未提供则从 schema.js 中获取
+ * @returns {void}
  */
 function addTableColumn(tableName, tableBuilder, columnName, columnSpec = schema[tableName][columnName]) {
-    let column;
+    let column;  // Knex.js 字段构建器对象，用于链式调用字段约束方法
 
-    // creation distinguishes between text with fieldtype, string with maxlength and all others
+    // 字段类型处理：区分 text（带 fieldtype）、string（带 maxlength）和其他基本类型
     if (columnSpec.type === 'text' && Object.prototype.hasOwnProperty.call(columnSpec, 'fieldtype')) {
+        // 处理 text 类型，支持指定 fieldtype（如 'text', 'longtext' 等）
         column = tableBuilder[columnSpec.type](columnName, columnSpec.fieldtype);
     } else if (columnSpec.type === 'string') {
+        // 处理 string 类型，支持指定最大长度
         if (Object.prototype.hasOwnProperty.call(columnSpec, 'maxlength')) {
             column = tableBuilder[columnSpec.type](columnName, columnSpec.maxlength);
         } else {
+            // 默认使用 191 作为字符串长度（兼容 MySQL 的索引限制）
             column = tableBuilder[columnSpec.type](columnName, 191);
         }
     } else {
+        // 处理其他基本类型（integer, boolean, dateTime 等）
         column = tableBuilder[columnSpec.type](columnName);
     }
 
+    // === 字段约束处理 ===
+
+    // 空值约束：控制字段是否允许 NULL 值
     if (Object.prototype.hasOwnProperty.call(columnSpec, 'nullable') && columnSpec.nullable === true) {
-        column.nullable();
+        column.nullable();        // 允许 NULL 值
     } else {
-        column.nullable(false);
+        column.nullable(false);   // 不允许 NULL 值（默认）
     }
+
+    // 主键约束：将字段设置为主键
     if (Object.prototype.hasOwnProperty.call(columnSpec, 'primary') && columnSpec.primary === true) {
         column.primary();
     }
+
+    // 唯一约束：确保字段值在表中唯一
     if (Object.prototype.hasOwnProperty.call(columnSpec, 'unique') && columnSpec.unique) {
         column.unique();
     }
+
+    // 无符号约束：适用于整数类型，确保值为非负数
     if (Object.prototype.hasOwnProperty.call(columnSpec, 'unsigned') && columnSpec.unsigned) {
         column.unsigned();
     }
+
+    // 外键引用：建立字段与其他表的关联
     if (Object.prototype.hasOwnProperty.call(columnSpec, 'references')) {
-        // check if table exists?
+        // 注意：这里没有检查被引用的表是否存在，需要在调用前确保
         column.references(columnSpec.references);
     }
+
+    // 外键约束名：为外键约束指定名称
     if (Object.prototype.hasOwnProperty.call(columnSpec, 'constraintName')) {
         column.withKeyName(columnSpec.constraintName);
     }
 
+    // 级联删除策略：控制关联记录删除时的行为
     if (Object.prototype.hasOwnProperty.call(columnSpec, 'cascadeDelete') && columnSpec.cascadeDelete === true) {
-        column.onDelete('CASCADE');
+        column.onDelete('CASCADE');    // 级联删除：删除主记录时自动删除关联记录
     } else if (Object.prototype.hasOwnProperty.call(columnSpec, 'setNullDelete') && columnSpec.setNullDelete === true) {
-        column.onDelete('SET NULL');
+        column.onDelete('SET NULL');   // 设为 NULL：删除主记录时将外键设为 NULL
     }
+
+    // 默认值：为字段设置默认值
     if (Object.prototype.hasOwnProperty.call(columnSpec, 'defaultTo')) {
         column.defaultTo(columnSpec.defaultTo);
     }
+
+    // 索引：为字段创建索引以提高查询性能
     if (Object.prototype.hasOwnProperty.call(columnSpec, 'index') && columnSpec.index === true) {
         column.index();
     }
-}
+} 
+
+//用函数将sql语句的功能进行封装，方便之后使用
 
 /**
  * @param {string} tableName
@@ -285,7 +314,7 @@ async function dropUnique(tableName, columns, transaction = db.knex) {
 
 /**
  * Checks if a foreign key exists in a table over the given columns.
- *
+*
  * @param {Object} configuration - contains all configuration for this function
  * @param {string} configuration.fromTable - name of the table to add the foreign key to
  * @param {string} configuration.fromColumn - column of the table to add the foreign key to
@@ -376,7 +405,7 @@ async function addForeign({fromTable, fromColumn, toTable, toColumn, constraintN
  * @param {Object} configuration - contains all configuration for this function
  * @param {string} configuration.fromTable - name of the table to add the foreign key to
  * @param {string} configuration.fromColumn - column of the table to add the foreign key to
- * @param {string} configuration.toTable - name of the table to point the foreign key to
+ * @param {string} configuration.toTable - name of the table to point the foreign key to 
  * @param {string} configuration.toColumn - column of the table to point the foreign key to
  * @param {string} [configuration.constraintName] - name of the FK to delete
  * @param {import('knex').Knex} [configuration.transaction] - connection object containing knex reference
@@ -553,8 +582,28 @@ async function getColumns(table, transaction = db.knex) {
     return Promise.reject(tpl(messages.noSupportForDatabase, {client: client}));
 }
 
+/**
+ * 创建字段迁移脚本的高阶函数
+ * 
+ * 这是一个高级的数据库迁移工具函数，用于创建幂等的字段迁移脚本。
+ * 通过检查数据库当前状态，确保迁移操作只在必要时执行，避免重复操作。
+ * 
+ */
 function createColumnMigration(...migrations) {
+    /**
+     * 执行单个迁移操作的内部函数
+     * 
+     * @param {import('knex').Knex} conn - 数据库连接对象
+     * @param {Object} migration - 迁移配置对象
+     * @param {string} migration.table - 表名
+     * @param {string} migration.column - 字段名
+     * @param {Function} migration.dbIsInCorrectState - 状态检查函数，返回布尔值
+     * @param {Function} migration.operation - 要执行的操作函数（如 addColumn、dropColumn）
+     * @param {string} migration.operationVerb - 操作动词（用于日志记录）
+     * @param {Object} [migration.columnDefinition] - 字段定义（仅用于添加字段操作）
+     */
     async function runColumnMigration(conn, migration) {
+        // 解构迁移配置参数
         const {
             table,
             column,
@@ -564,44 +613,70 @@ function createColumnMigration(...migrations) {
             columnDefinition
         } = migration;
 
+        // 检查字段是否存在
         const hasColumn = await conn.schema.hasColumn(table, column);
+        // 根据状态检查函数判断是否需要执行操作
         const isInCorrectState = dbIsInCorrectState(hasColumn);
 
         if (isInCorrectState) {
+            // 如果数据库已处于正确状态，跳过操作并记录警告日志
             logging.warn(`${operationVerb} ${table}.${column} column - skipping as table is correct`);
         } else {
+            // 如果数据库需要更新，执行操作并记录信息日志
             logging.info(`${operationVerb} ${table}.${column} column`);
             await operation(table, column, conn, columnDefinition);
         }
     }
 
+    /**
+     * 返回的迁移执行函数
+     * 
+     * @param {import('knex').Knex} conn - 数据库连接对象
+     * @returns {Promise} 异步执行所有迁移操作
+     */
     return async function columnMigration(conn) {
+        // 按顺序执行所有迁移配置
         for (const migration of migrations) {
             await runColumnMigration(conn, migration);
         }
     };
 }
 
+/**
+ * 数据库模式操作命令模块导出
+ * 这个地方是对上面封装sql语句的函数进行一个成列 
+ */
 module.exports = {
-    createTable,
+    // 表操作命令
-    deleteTable,
+    createTable,      // 创建表：根据 schema.js 定义创建新表
-    getTables,
+    deleteTable,      // 删除表：删除指定的表
-    getIndexes,
+    
-    addUnique,
+    // 元数据查询命令
-    dropUnique,
+    getTables,        // 获取表列表：查询数据库中所有表名
-    addIndex,
+    getIndexes,       // 获取索引：查询指定表的所有索引
-    dropIndex,
+    getColumns,       // 获取字段：查询指定表的所有字段名
-    addPrimaryKey,
+    
-    addForeign,
+    // 约束操作命令
-    dropForeign,
+    addUnique,        // 添加唯一约束：为字段添加唯一性约束
-    addColumn,
+    dropUnique,       // 删除唯一约束：移除字段的唯一性约束
-    renameColumn,
+    addIndex,         // 添加索引：为字段创建索引以提高查询性能
-    dropColumn,
+    dropIndex,        // 删除索引：移除字段的索引
-    setNullable,
+    addPrimaryKey,    // 添加主键：将字段设置为主键
-    dropNullable,
+    addForeign,       // 添加外键：建立表之间的关联关系
-    getColumns,
+    dropForeign,      // 删除外键：移除表之间的关联关系
-    createColumnMigration,
+    
+    // 字段操作命令
+    addColumn,        // 添加字段：向表中添加新字段
+    renameColumn,     // 重命名字段：修改字段名称
+    dropColumn,       // 删除字段：从表中移除字段
+    setNullable,      // 设为可空：允许字段为 NULL 值
+    dropNullable,     // 设为非空：不允许字段为 NULL 值
+    
+    // 高级功能
+    createColumnMigration,  // 创建字段迁移：生成字段变更的迁移脚本
+    
+    // 测试专用函数（仅供内部测试使用）
     // NOTE: below are exposed for testing purposes only
-    _hasForeignSQLite: hasForeignSQLite,
+    _hasForeignSQLite: hasForeignSQLite,        // 检查 SQLite 外键存在性（测试用）
-    _hasPrimaryKeySQLite: hasPrimaryKeySQLite
+    _hasPrimaryKeySQLite: hasPrimaryKeySQLite  // 检查 SQLite 主键存在性（测试用）
-};
+};

ghost/core/core/server/data/schema/default-settings/index.js

@@ -4,3 +4,4 @@ const defaultSettingsPath = config.get('paths').defaultSettings;
 const defaultSettings = require(defaultSettingsPath);
 
 module.exports = defaultSettings;
+//一些默认配置文件

ghost/core/core/server/data/schema/fixtures/FixtureManager.js

@@ -1,13 +1,13 @@
-const _ = require('lodash');
+const _ = require('lodash');  //引入lodash库，用于处理数组、对象等数据结构
 const logging = require('@tryghost/logging');
 const {sequence} = require('@tryghost/promise');
 
 const models = require('../../../models');
 const baseUtils = require('../../../models/base/utils');
 
-const moment = require('moment');
+const moment = require('moment'); 
-
+//把写在 JSON/JS 里的“蓝图”变成真正的数据库记录，并建立好它们之间的关联。
-class FixtureManager {
+class FixtureManager { 
     /**
      * Create a new FixtureManager instance
      *
@@ -194,22 +194,23 @@ class FixtureManager {
      * @param {String} objName
      * @returns {Object} fixture relation
      */
+    /**
+     * 查找特定对象的权限关系
+     * 
+     * 用于设置角色权限，如：管理员对文章有所有权限
+     */
     findPermissionRelationsForObject(objName, role) {
-        // Make a copy and delete any entries we don't want
+        const foundRelation = this.findRelationFixture('Role', 'Permission');
-        const foundRelation = _.cloneDeep(this.findRelationFixture('Role', 'Permission'));
+        
-
+        // 过滤只保留指定对象的权限
         _.each(foundRelation.entries, (entry, key) => {
             _.each(entry, (perm, obj) => {
                 if (obj !== objName) {
-                    delete entry[obj];
+                    delete entry[obj];  // 移除其他对象权限
                 }
             });
-
-            if (_.isEmpty(entry) || (role && role !== key)) {
-                delete foundRelation.entries[key];
-            }
         });
-
+        
         return foundRelation;
     }
 
@@ -382,52 +383,49 @@ class FixtureManager {
      * @param {{from, to, entries}} relationFixture
      * @returns {Promise<any>}
      */
+    /**
+     * 创建模型之间的关联关系
+     * 
+     * 处理多对多、一对多等复杂关系
+     * 避免重复关联：检查是否已存在相同关系
+     * 
+     * @param {{from, to, entries}} relationFixture - 关系配置
+     */
     async addFixturesForRelation(relationFixture, options) {
-        const ops = [];
+        // 获取关联双方的现有数据
-        let max = 0;
-
         const data = await this.fetchRelationData(relationFixture, options);
-
+        
         _.each(relationFixture.entries, (entry, key) => {
-            const fromItem = data.from.find(FixtureManager.matchFunc(relationFixture.from.match, key));
+            // 查找源模型
-
+            const fromItem = data.from.find(
-            // CASE: You add new fixtures e.g. a new role in a new release.
+                FixtureManager.matchFunc(relationFixture.from.match, key)
-            // As soon as an **older** migration script wants to add permissions for any resource, it iterates over the
+            );
-            // permissions for each role. But if the role does not exist yet, it won't find the matching db entry and breaks.
+            
-            if (!fromItem) {
-                logging.warn('Skip: Target database entry not found for key: ' + key);
-                return Promise.resolve();
-            }
-
             _.each(entry, (value, entryKey) => {
-                let toItems = data.to.filter(FixtureManager.matchFunc(relationFixture.to.match, entryKey, value));
+                // 查找目标模型
-                max += toItems.length;
+                let toItems = data.to.filter(
-
+                    FixtureManager.matchFunc(relationFixture.to.match, entryKey, value)
-                // Remove any duplicates that already exist in the collection
+                );
+                
+                // 移除已存在的关联（避免重复）
                 toItems = _.reject(toItems, (item) => {
-                    return fromItem
+                    return fromItem.related(relationFixture.from.relation)
-                        .related(relationFixture.from.relation)
+                        .find((model) => /* 检查是否已关联 */);
-                        .find((model) => {
-                            const objectToMatch = FixtureManager.matchObj(relationFixture.to.match, item);
-                            return Object.keys(objectToMatch).every((keyToCheck) => {
-                                return model.get(keyToCheck) === objectToMatch[keyToCheck];
-                            });
-                        });
                 });
-
+                
-                if (toItems && toItems.length > 0) {
+                // 创建新关联
-                    ops.push(function addRelationItems() {
+                if (toItems.length > 0) {
-                        return baseUtils.attach(
+                    ops.push(() => baseUtils.attach(
-                            models[relationFixture.from.Model || relationFixture.from.model],
+                        models[relationFixture.from.model],
-                            fromItem.id,
+                        fromItem.id,
-                            relationFixture.from.relation,
+                        relationFixture.from.relation,
-                            toItems,
+                        toItems,
-                            options
+                        options
-                        );
+                    ));
-                    });
                 }
             });
         });
+    }
 
         const result = await sequence(ops);
         return {expected: max, done: _(result).map('length').sum()};
@@ -472,4 +470,4 @@ class FixtureManager {
     }
 }
 
-module.exports = FixtureManager;
+module.exports = FixtureManager;

ghost/core/core/server/data/schema/schema.js

@@ -8,140 +8,153 @@
  * Text = length 65535 (64 KiB)
  * Long text = length 1,000,000,000
  */
+/* 数据库模型里面各种表的定义
+    * primary 主键
+    * unique 唯一
+    * defaultTo 默认值
+    * nullable 是否为空
+    * validations 验证规则
+    * isIn 枚举值，defaultTo为当前枚举值中的一个
+    * isUUID 是否为UUID
+    * validations 验证规则，看当前字段是否符合规则，不符合就拒写
+    * visibility 可见性验证，仅给定人员可见
+    * slug:url 别名  type:内容类型（post,page)
+*/
 module.exports = {
-    newsletters: {
+    newsletters: { // 邮件通讯表 - 存储邮件通讯相关的配置信息
-        id: {type: 'string', maxlength: 24, nullable: false, primary: true},
+        id: {type: 'string', maxlength: 24, nullable: false, primary: true},         // 内部主键（对外不可见） 
-        uuid: {type: 'string', maxlength: 36, nullable: false, unique: true, validations: {isUUID: true}},
+        uuid: {type: 'string', maxlength: 36, nullable: false, unique: true, validations: {isUUID: true}}, // 外部唯一标志，即使被泄露还有id保护，无法被外部人员窃取相关数据
-        name: {type: 'string', maxlength: 191, nullable: false, unique: true},
+        name: {type: 'string', maxlength: 191, nullable: false, unique: true}, // 邮件通讯名称，必须唯一
-        description: {type: 'string', maxlength: 2000, nullable: true},
+        description: {type: 'string', maxlength: 2000, nullable: true}, // 邮件通讯描述，可为空
-        feedback_enabled: {type: 'boolean', nullable: false, defaultTo: false},
+        feedback_enabled: {type: 'boolean', nullable: false, defaultTo: false}, // 是否启用反馈功能，默认关闭
-        slug: {type: 'string', maxlength: 191, nullable: false, unique: true},
+        slug: {type: 'string', maxlength: 191, nullable: false, unique: true}, // URL友好的标识符，必须唯一
-        sender_name: {type: 'string', maxlength: 191, nullable: true},
+        sender_name: {type: 'string', maxlength: 191, nullable: true}, // 发件人名称，可为空
-        sender_email: {type: 'string', maxlength: 191, nullable: true},
+        sender_email: {type: 'string', maxlength: 191, nullable: true}, // 发件人邮箱地址，可为空
-        sender_reply_to: {type: 'string', maxlength: 191, nullable: false, defaultTo: 'newsletter'},
+        sender_reply_to: {type: 'string', maxlength: 191, nullable: false, defaultTo: 'newsletter'}, // 回复地址，默认为'newsletter'
-        status: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'active', validations: {isIn: [['active', 'archived']]}},
+        status: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'active', validations: {isIn: [['active', 'archived']]}}, // 状态：活跃或已归档
         visibility: {
             type: 'string',
             maxlength: 50,
             nullable: false,
-            defaultTo: 'members'
+            defaultTo: 'members'//设置可见性，仅会员可见
         },
-        subscribe_on_signup: {type: 'boolean', nullable: false, defaultTo: true},
+        subscribe_on_signup: {type: 'boolean', nullable: false, defaultTo: true}, // 用户注册时是否自动订阅邮件通讯，默认为true（自动订阅）
-        sort_order: {type: 'integer', nullable: false, unsigned: true, defaultTo: 0},
+        sort_order: {type: 'integer', nullable: false, unsigned: true, defaultTo: 0}, // 排序顺序，用于控制显示顺序
-        header_image: {type: 'string', maxlength: 2000, nullable: true},
+        header_image: {type: 'string', maxlength: 2000, nullable: true}, // 头部图片URL，可为空
-        show_header_icon: {type: 'boolean', nullable: false, defaultTo: true},
+        show_header_icon: {type: 'boolean', nullable: false, defaultTo: true}, // 是否显示头部图标，默认显示
-        show_header_title: {type: 'boolean', nullable: false, defaultTo: true},
+        show_header_title: {type: 'boolean', nullable: false, defaultTo: true}, // 是否显示头部标题，默认显示
-        show_excerpt: {type: 'boolean', nullable: false, defaultTo: false},
+        show_excerpt: {type: 'boolean', nullable: false, defaultTo: false}, // 是否显示摘要，默认不显示
-        title_font_category: {type: 'string', maxlength: 191, nullable: false, defaultTo: 'sans_serif', validations: {isIn: [['serif', 'sans_serif']]}},
+        title_font_category: {type: 'string', maxlength: 191, nullable: false, defaultTo: 'sans_serif', validations: {isIn: [['serif', 'sans_serif']]}}, // 标题字体类别：衬线体或无衬线体
-        title_alignment: {type: 'string', maxlength: 191, nullable: false, defaultTo: 'center', validations: {isIn: [['center', 'left']]}},
+        title_alignment: {type: 'string', maxlength: 191, nullable: false, defaultTo: 'center', validations: {isIn: [['center', 'left']]}}, // 标题对齐方式：居中或左对齐
-        show_feature_image: {type: 'boolean', nullable: false, defaultTo: true},
+        show_feature_image: {type: 'boolean', nullable: false, defaultTo: true}, // 是否显示特色图片，默认显示
-        body_font_category: {type: 'string', maxlength: 191, nullable: false, defaultTo: 'sans_serif', validations: {isIn: [['serif', 'sans_serif']]}},
+        body_font_category: {type: 'string', maxlength: 191, nullable: false, defaultTo: 'sans_serif', validations: {isIn: [['serif', 'sans_serif']]}}, // 正文字体类别：衬线体或无衬线体
-        footer_content: {type: 'text', maxlength: 1000000000, nullable: true},
+        footer_content: {type: 'text', maxlength: 1000000000, nullable: true}, // 页脚内容，支持长文本
-        show_badge: {type: 'boolean', nullable: false, defaultTo: true},
+        show_badge: {type: 'boolean', nullable: false, defaultTo: true}, // 是否显示徽章，默认显示
-        show_header_name: {type: 'boolean', nullable: false, defaultTo: true},
+        show_header_name: {type: 'boolean', nullable: false, defaultTo: true}, // 是否显示头部名称，默认显示
-        show_post_title_section: {type: 'boolean', nullable: false, defaultTo: true},
+        show_post_title_section: {type: 'boolean', nullable: false, defaultTo: true}, // 是否显示文章标题区域，默认显示
-        show_comment_cta: {type: 'boolean', nullable: false, defaultTo: true},
+        show_comment_cta: {type: 'boolean', nullable: false, defaultTo: true}, // 是否显示评论行动号召，默认显示
-        show_subscription_details: {type: 'boolean', nullable: false, defaultTo: false},
+        show_subscription_details: {type: 'boolean', nullable: false, defaultTo: false}, // 是否显示订阅详情，默认不显示
-        show_latest_posts: {type: 'boolean', nullable: false, defaultTo: false},
+        show_latest_posts: {type: 'boolean', nullable: false, defaultTo: false}, // 是否显示最新文章，默认不显示
-        background_color: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'light'},
+        background_color: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'light'}, // 背景颜色，默认为浅色
-        post_title_color: {type: 'string', maxlength: 50, nullable: true},
+        post_title_color: {type: 'string', maxlength: 50, nullable: true}, // 文章标题颜色，可为空
-        created_at: {type: 'dateTime', nullable: false},
+        created_at: {type: 'dateTime', nullable: false}, // 创建时间，不能为空
-        updated_at: {type: 'dateTime', nullable: true},
+        updated_at: {type: 'dateTime', nullable: true}, // 更新时间，可为空
-        button_corners: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'rounded', validations: {isIn: [['square', 'rounded', 'pill']]}},
+        button_corners: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'rounded', validations: {isIn: [['square', 'rounded', 'pill']]}}, // 按钮圆角样式：方形、圆角或药丸形
-        button_style: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'fill', validations: {isIn: [['fill', 'outline']]}},
+        button_style: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'fill', validations: {isIn: [['fill', 'outline']]}}, // 按钮样式：填充或轮廓
-        title_font_weight: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'bold', validations: {isIn: [['normal', 'medium', 'semibold', 'bold']]}},
+        title_font_weight: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'bold', validations: {isIn: [['normal', 'medium', 'semibold', 'bold']]}}, // 标题字体粗细：正常、中等、半粗体、粗体
-        link_style: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'underline', validations: {isIn: [['underline', 'regular', 'bold']]}},
+        link_style: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'underline', validations: {isIn: [['underline', 'regular', 'bold']]}}, // 链接样式：下划线、常规、粗体
-        image_corners: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'square', validations: {isIn: [['square', 'rounded']]}},
+        image_corners: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'square', validations: {isIn: [['square', 'rounded']]}}, // 图片圆角样式：方形或圆角
-        header_background_color: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'transparent'},
+        header_background_color: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'transparent'}, // 头部背景颜色，默认为透明
-        section_title_color: {type: 'string', maxlength: 50, nullable: true},
+        section_title_color: {type: 'string', maxlength: 50, nullable: true}, // 区域标题颜色，可为空
-        divider_color: {type: 'string', maxlength: 50, nullable: true},
+        divider_color: {type: 'string', maxlength: 50, nullable: true}, // 分隔线颜色，可为空
-        button_color: {type: 'string', maxlength: 50, nullable: true, defaultTo: 'accent'},
+        button_color: {type: 'string', maxlength: 50, nullable: true, defaultTo: 'accent'}, // 按钮颜色，默认为强调色
-        link_color: {type: 'string', maxlength: 50, nullable: true, defaultTo: 'accent'}
+        link_color: {type: 'string', maxlength: 50, nullable: true, defaultTo: 'accent'} // 链接颜色，默认为强调色
-    },
+    },
+    // 内容管理器，对内容的各种信息进行存储管理
     posts: {
-        id: {type: 'string', maxlength: 24, nullable: false, primary: true},
+        id: {type: 'string', maxlength: 24, nullable: false, primary: true}, // 主键ID，唯一标识文章
-        uuid: {type: 'string', maxlength: 36, nullable: false, index: true, validations: {isUUID: true}},
+        uuid: {type: 'string', maxlength: 36, nullable: false, index: true, validations: {isUUID: true}}, // 全局唯一标识符，用于外部引用
-        title: {type: 'string', maxlength: 2000, nullable: false, validations: {isLength: {max: 255}}},
+        title: {type: 'string', maxlength: 2000, nullable: false, validations: {isLength: {max: 255}}}, // 文章标题，最大长度255字符
-        slug: {type: 'string', maxlength: 191, nullable: false},
+        slug: {type: 'string', maxlength: 191, nullable: false, unique: true}, // URL别名，用于在URL中标识文章
-        mobiledoc: {type: 'text', maxlength: 1000000000, fieldtype: 'long', nullable: true},
+        mobiledoc: {type: 'text', maxlength: 1000000000, fieldtype: 'long', nullable: true}, // 旧编辑器JSON格式内容
-        lexical: {type: 'text', maxlength: 1000000000, fieldtype: 'long', nullable: true},
+        lexical: {type: 'text', maxlength: 1000000000, fieldtype: 'long', nullable: true}, // 新编辑器JSON格式内容
-        html: {type: 'text', maxlength: 1000000000, fieldtype: 'long', nullable: true},
+        html: {type: 'text', maxlength: 1000000000, fieldtype: 'long', nullable: true}, // 编译之后的HTML内容
-        comment_id: {type: 'string', maxlength: 50, nullable: true},
+        comment_id: {type: 'string', maxlength: 50, nullable: true}, // 评论ID，用于外部评论系统集成
-        plaintext: {type: 'text', maxlength: 1000000000, fieldtype: 'long', nullable: true},
+        plaintext: {type: 'text', maxlength: 1000000000, fieldtype: 'long', nullable: true}, // 纯文本摘要，用于搜索和预览
-        feature_image: {type: 'string', maxlength: 2000, nullable: true},
+        feature_image: {type: 'string', maxlength: 2000, nullable: true}, // 封面图地址
-        featured: {type: 'boolean', nullable: false, defaultTo: false},
+        featured: {type: 'boolean', nullable: false, defaultTo: false}, // 是否置顶，默认为否，需要手动设置
-        type: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'post', validations: {isIn: [['post', 'page']]}},
+        type: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'post', validations: {isIn: [['post', 'page']]}}, // 内容类型，post为文章，page为页面
-        status: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'draft', validations: {isIn: [['published', 'draft', 'scheduled', 'sent']]}},
+        status: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'draft', validations: {isIn: [['published', 'draft', 'scheduled', 'sent']]}}, // 文章状态：已发布、草稿、定时发布、已发送
         // NOTE: unused at the moment and reserved for future features
-        locale: {type: 'string', maxlength: 6, nullable: true},
+        locale: {type: 'string', maxlength: 6, nullable: true}, // 语言区域设置，预留字段
         visibility: {
             type: 'string',
             maxlength: 50,
             nullable: false,
-            defaultTo: 'public'
+            defaultTo: 'public' // 可见性设置，默认为公开
         },
         email_recipient_filter: {
             type: 'text',
             maxlength: 1000000000,
-            nullable: false
+            nullable: false // 邮件接收者筛选条件
         },
-        created_at: {type: 'dateTime', nullable: false},
+        created_at: {type: 'dateTime', nullable: false}, // 创建时间
-        updated_at: {type: 'dateTime', nullable: true, index: true},
+        updated_at: {type: 'dateTime', nullable: true, index: true}, // 更新时间，有索引便于排序
-        published_at: {type: 'dateTime', nullable: true, index: true},
+        published_at: {type: 'dateTime', nullable: true, index: true}, // 发布时间，有索引便于排序
-        published_by: {type: 'string', maxlength: 24, nullable: true},
+        published_by: {type: 'string', maxlength: 24, nullable: true}, // 发布者ID
-        custom_excerpt: {type: 'string', maxlength: 2000, nullable: true, validations: {isLength: {max: 300}}},
+        custom_excerpt: {type: 'string', maxlength: 2000, nullable: true, validations: {isLength: {max: 300}}}, // 自定义摘要，最大300字符
-        codeinjection_head: {type: 'text', maxlength: 65535, nullable: true},
+        codeinjection_head: {type: 'text', maxlength: 65535, nullable: true}, // 头部代码注入，用于在<head>标签中添加自定义代码
-        codeinjection_foot: {type: 'text', maxlength: 65535, nullable: true},
+        codeinjection_foot: {type: 'text', maxlength: 65535, nullable: true}, // 底部代码注入，用于在<body>结束前添加自定义代码
-        custom_template: {type: 'string', maxlength: 100, nullable: true},
+        custom_template: {type: 'string', maxlength: 100, nullable: true}, // 自定义模板名称
-        canonical_url: {type: 'text', maxlength: 2000, nullable: true},
+        canonical_url: {type: 'text', maxlength: 2000, nullable: true}, // 规范URL，用于SEO避免重复内容
-        newsletter_id: {type: 'string', maxlength: 24, nullable: true, references: 'newsletters.id'},
+        newsletter_id: {type: 'string', maxlength: 24, nullable: true, references: 'newsletters.id'}, // 关联的邮件通讯ID
-        show_title_and_feature_image: {type: 'boolean', nullable: false, defaultTo: true},
+        show_title_and_feature_image: {type: 'boolean', nullable: false, defaultTo: true}, // 是否显示标题和封面图，默认为是
         '@@INDEXES@@': [
-            ['type','status','updated_at']
+            ['type','status','updated_at'] // 复合索引：按类型、状态、更新时间排序，提高查询性能
         ],
         '@@UNIQUE_CONSTRAINTS@@': [
-            ['slug', 'type']
+            ['slug', 'type'] // 唯一约束：同一类型的文章不能有相同的slug
         ]
     },
-    posts_meta: {
+    posts_meta: {  //用于存储文章的额外元数据
-        id: {type: 'string', maxlength: 24, nullable: false, primary: true},
+        id: {type: 'string', maxlength: 24, nullable: false, primary: true},//主键ID，唯一标识文章元数据
-        post_id: {type: 'string', maxlength: 24, nullable: false, references: 'posts.id', unique: true},
+        post_id: {type: 'string', maxlength: 24, nullable: false, references: 'posts.id', unique: true}, // 关联的文章ID，唯一标识
-        og_image: {type: 'string', maxlength: 2000, nullable: true},
+        og_image: {type: 'string', maxlength: 2000, nullable: true}, // Open Graph 图片URL
-        og_title: {type: 'string', maxlength: 300, nullable: true},
+        og_title: {type: 'string', maxlength: 300, nullable: true}, // Open Graph 标题，最大300字符
-        og_description: {type: 'string', maxlength: 500, nullable: true},
+        og_description: {type: 'string', maxlength: 500, nullable: true}, // Open Graph 描述，最大500字符
-        twitter_image: {type: 'string', maxlength: 2000, nullable: true},
+        twitter_image: {type: 'string', maxlength: 2000, nullable: true}, // Twitter 图片URL
-        twitter_title: {type: 'string', maxlength: 300, nullable: true},
+        twitter_title: {type: 'string', maxlength: 300, nullable: true}, // Twitter 标题，最大300字符
-        twitter_description: {type: 'string', maxlength: 500, nullable: true},
+        twitter_description: {type: 'string', maxlength: 500, nullable: true}, // Twitter 描述，最大500字符
-        meta_title: {type: 'string', maxlength: 2000, nullable: true, validations: {isLength: {max: 300}}},
+        meta_title: {type: 'string', maxlength: 2000, nullable: true, validations: {isLength: {max: 300}}},// SEO 标题，最大300字符
-        meta_description: {type: 'string', maxlength: 2000, nullable: true, validations: {isLength: {max: 500}}},
+        meta_description: {type: 'string', maxlength: 2000, nullable: true, validations: {isLength: {max: 500}}},// SEO 描述，最大500字符
-        email_subject: {type: 'string', maxlength: 300, nullable: true},
+        email_subject: {type: 'string', maxlength: 300, nullable: true},// 邮件主题，最大300字符
-        frontmatter: {type: 'text', maxlength: 65535, nullable: true},
+        frontmatter: {type: 'text', maxlength: 65535, nullable: true},// 文章的Frontmatter内容，用于自定义元数据
-        feature_image_alt: {type: 'string', maxlength: 2000, nullable: true, validations: {isLength: {max: 191}}},
+        feature_image_alt: {type: 'string', maxlength: 2000, nullable: true, validations: {isLength: {max: 191}}},// 封面图替代文本，最大191字符
-        feature_image_caption: {type: 'text', maxlength: 65535, nullable: true},
+        feature_image_caption: {type: 'text', maxlength: 65535, nullable: true},// 封面图标题，用于图片描述
-        email_only: {type: 'boolean', nullable: false, defaultTo: false}
+        email_only: {type: 'boolean', nullable: false, defaultTo: false}, // 是否仅通过邮件发送，默认为否
     },
     // NOTE: this is the staff table
     users: {
-        id: {type: 'string', maxlength: 24, nullable: false, primary: true},
+        id: {type: 'string', maxlength: 24, nullable: false, primary: true},//主键ID，唯一标识用户
-        name: {type: 'string', maxlength: 191, nullable: false},
+        name: {type: 'string', maxlength: 191, nullable: false}, // 用户名
-        slug: {type: 'string', maxlength: 191, nullable: false, unique: true},
+        slug: {type: 'string', maxlength: 191, nullable: false, unique: true},//用户slug，唯一标识
-        password: {type: 'string', maxlength: 60, nullable: false},
+        password: {type: 'string', maxlength: 60, nullable: false},//用户密码 
-        email: {type: 'string', maxlength: 191, nullable: false, unique: true, validations: {isEmail: true}},
+        email: {type: 'string', maxlength: 191, nullable: false, unique: true, validations: {isEmail: true}},//用户邮箱，唯一标识
-        profile_image: {type: 'string', maxlength: 2000, nullable: true},
+        profile_image: {type: 'string', maxlength: 2000, nullable: true},// 用户头像URL
-        cover_image: {type: 'string', maxlength: 2000, nullable: true},
+        cover_image: {type: 'string', maxlength: 2000, nullable: true},//用户封面图URL 
-        bio: {type: 'text', maxlength: 65535, nullable: true, validations: {isLength: {max: 250}}},
+        bio: {type: 'text', maxlength: 65535, nullable: true, validations: {isLength: {max: 250}}},//用户简介，最大250字符
-        website: {type: 'string', maxlength: 2000, nullable: true, validations: {isEmptyOrURL: true}},
+        website: {type: 'string', maxlength: 2000, nullable: true, validations: {isEmptyOrURL: true}},//用户网站URL
-        location: {type: 'text', maxlength: 65535, nullable: true, validations: {isLength: {max: 150}}},
+        location: {type: 'text', maxlength: 65535, nullable: true, validations: {isLength: {max: 150}}},//用户位置，最大150字符
-        facebook: {type: 'string', maxlength: 2000, nullable: true},
+        facebook: {type: 'string', maxlength: 2000, nullable: true},//用户Facebook链接
         twitter: {type: 'string', maxlength: 2000, nullable: true},
-        threads: {type: 'string', maxlength: 191, nullable: true},
+        threads: {type: 'string', maxlength: 191, nullable: true},//用户Threads链接
-        bluesky: {type: 'string', maxlength: 191, nullable: true},
+        bluesky: {type: 'string', maxlength: 191, nullable: true},//用户Bluesky链接
-        mastodon: {type: 'string', maxlength: 191, nullable: true},
+        mastodon: {type: 'string', maxlength: 191, nullable: true},//用户Mastodon链接
-        tiktok: {type: 'string', maxlength: 191, nullable: true},
+        tiktok: {type: 'string', maxlength: 191, nullable: true},//用户TikTok链接
-        youtube: {type: 'string', maxlength: 191, nullable: true},
+        youtube: {type: 'string', maxlength: 191, nullable: true},    //用户YouTube链接
-        instagram: {type: 'string', maxlength: 191, nullable: true},
+        instagram: {type: 'string', maxlength: 191, nullable: true},//用户Instagram链接
-        linkedin: {type: 'string', maxlength: 191, nullable: true},
+        linkedin: {type: 'string', maxlength: 191, nullable: true},//用户LinkedIn链接
-        accessibility: {type: 'text', maxlength: 65535, nullable: true},
+        accessibility: {type: 'text', maxlength: 65535, nullable: true},//用户可访问性设置
         status: {
             type: 'string',
             maxlength: 50,
@@ -160,7 +173,7 @@ module.exports = {
             }
         },
         // NOTE: unused at the moment and reserved for future features
-        locale: {type: 'string', maxlength: 6, nullable: true},
+        locale: {type: 'string', maxlength: 6, nullable: true},//用户语言设置
         visibility: {
             type: 'string',
             maxlength: 50,
@@ -184,25 +197,25 @@ module.exports = {
         created_at: {type: 'dateTime', nullable: false},
         updated_at: {type: 'dateTime', nullable: true}
     },
-    posts_authors: {
+    posts_authors: { // 文章作者关联表
         id: {type: 'string', maxlength: 24, nullable: false, primary: true},
         post_id: {type: 'string', maxlength: 24, nullable: false, references: 'posts.id'},
         author_id: {type: 'string', maxlength: 24, nullable: false, references: 'users.id'},
         sort_order: {type: 'integer', nullable: false, unsigned: true, defaultTo: 0}
     },
-    roles: {
+    roles: {// 角色
         id: {type: 'string', maxlength: 24, nullable: false, primary: true},
         name: {type: 'string', maxlength: 50, nullable: false, unique: true},
         description: {type: 'string', maxlength: 2000, nullable: true},
         created_at: {type: 'dateTime', nullable: false},
         updated_at: {type: 'dateTime', nullable: true}
     },
-    roles_users: {
+    roles_users: { // 角色用户关联表
         id: {type: 'string', maxlength: 24, nullable: false, primary: true},
         role_id: {type: 'string', maxlength: 24, nullable: false},
         user_id: {type: 'string', maxlength: 24, nullable: false}
     },
-    permissions: {
+    permissions: {// 权限
         id: {type: 'string', maxlength: 24, nullable: false, primary: true},
         name: {type: 'string', maxlength: 50, nullable: false, unique: true},
         object_type: {type: 'string', maxlength: 50, nullable: false},
@@ -211,17 +224,17 @@ module.exports = {
         created_at: {type: 'dateTime', nullable: false},
         updated_at: {type: 'dateTime', nullable: true}
     },
-    permissions_users: {
+    permissions_users: {// 权限用户关联表 
         id: {type: 'string', maxlength: 24, nullable: false, primary: true},
         user_id: {type: 'string', maxlength: 24, nullable: false},
         permission_id: {type: 'string', maxlength: 24, nullable: false}
     },
-    permissions_roles: {
+    permissions_roles: {// 权限角色关联表 
         id: {type: 'string', maxlength: 24, nullable: false, primary: true},
         role_id: {type: 'string', maxlength: 24, nullable: false},
         permission_id: {type: 'string', maxlength: 24, nullable: false}
     },
-    settings: {
+    settings: {// 设置
         id: {type: 'string', maxlength: 24, nullable: false, primary: true},
         group: {
             type: 'string',
@@ -265,7 +278,7 @@ module.exports = {
         created_at: {type: 'dateTime', nullable: false},
         updated_at: {type: 'dateTime', nullable: true}
     },
-    tags: {
+    tags: {// 标签
         id: {type: 'string', maxlength: 24, nullable: false, primary: true},
         name: {type: 'string', maxlength: 191, nullable: false, validations: {matches: /^([^,]|$)/}},
         slug: {type: 'string', maxlength: 191, nullable: false, unique: true},
@@ -294,7 +307,7 @@ module.exports = {
         created_at: {type: 'dateTime', nullable: false},
         updated_at: {type: 'dateTime', nullable: true}
     },
-    posts_tags: {
+    posts_tags: {// 文章标签关联表
         id: {type: 'string', maxlength: 24, nullable: false, primary: true},
         post_id: {type: 'string', maxlength: 24, nullable: false, references: 'posts.id'},
         tag_id: {type: 'string', maxlength: 24, nullable: false, references: 'tags.id'},
@@ -303,7 +316,7 @@ module.exports = {
             ['post_id','tag_id']
         ]
     },
-    invites: {
+    invites: {  // 邀请
         id: {type: 'string', maxlength: 24, nullable: false, primary: true},
         role_id: {type: 'string', maxlength: 24, nullable: false},
         status: {
@@ -319,14 +332,14 @@ module.exports = {
         created_at: {type: 'dateTime', nullable: false},
         updated_at: {type: 'dateTime', nullable: true}
     },
-    brute: {
+    brute: {// 暴力破解
         key: {type: 'string', maxlength: 191, primary: true},
         firstRequest: {type: 'bigInteger'},
         lastRequest: {type: 'bigInteger'},
         lifetime: {type: 'bigInteger'},
         count: {type: 'integer'}
     },
-    sessions: {
+    sessions: {// 会话
         id: {type: 'string', maxlength: 24, nullable: false, primary: true},
         session_id: {type: 'string', maxlength: 32, nullable: false, unique: true},
         user_id: {type: 'string', maxlength: 24, nullable: false},
@@ -334,7 +347,7 @@ module.exports = {
         created_at: {type: 'dateTime', nullable: false},
         updated_at: {type: 'dateTime', nullable: true}
     },
-    integrations: {
+    integrations: {// 集成
         id: {type: 'string', maxlength: 24, nullable: false, primary: true},
         type: {
             type: 'string',
@@ -350,12 +363,12 @@ module.exports = {
         created_at: {type: 'dateTime', nullable: false},
         updated_at: {type: 'dateTime', nullable: true}
     },
-    webhooks: {
+    webhooks: {//用于实现事件驱动的外部系统集成，当系统中发生特定时间的时候，会自动向配置的外部url发送http通知
         id: {type: 'string', maxlength: 24, nullable: false, primary: true},
-        event: {type: 'string', maxlength: 50, nullable: false, validations: {isLowercase: true}},
+        event: {type: 'string', maxlength: 50, nullable: false, validations: {isLowercase: true}},// 事件类型
-        target_url: {type: 'string', maxlength: 2000, nullable: false},
+        target_url: {type: 'string', maxlength: 2000, nullable: false},// 目标url
-        name: {type: 'string', maxlength: 191, nullable: true},
+        name: {type: 'string', maxlength: 191, nullable: true},// 名称
-        secret: {type: 'string', maxlength: 191, nullable: true},
+        secret: {type: 'string', maxlength: 191, nullable: true},// 密钥
         // @NOTE: the defaultTo does not make sense to set on DB layer as it leads to unnecessary maintenance every major release
         //       would be ideal if we can remove the default and instead have "isIn" validation checking if it's a valid version e.g: 'v3', 'v4', 'canary'
         api_version: {type: 'string', maxlength: 50, nullable: false, defaultTo: 'v2'},
@@ -376,14 +389,14 @@ module.exports = {
             nullable: false,
             validations: {isIn: [['content', 'admin']]}
         },
-        secret: {
+        secret: {  //密钥字符串
             type: 'string',
             maxlength: 191,
             nullable: false,
-            unique: true,
+            unique: true,//防止出现重复
             validations: {isLength: {min: 26, max: 128}}
         },
-        role_id: {type: 'string', maxlength: 24, nullable: true},
+        role_id: {type: 'string', maxlength: 24, nullable: true},   // 角色ID：关联到roles表，定义密钥的权限级别
         // integration_id is nullable to allow "internal" API keys that don't show in the UI
         integration_id: {type: 'string', maxlength: 24, nullable: true},
         user_id: {type: 'string', maxlength: 24, nullable: true},
@@ -414,7 +427,7 @@ module.exports = {
         feature_image_caption: {type: 'text', maxlength: 65535, nullable: true},
         custom_excerpt: {type: 'string', maxlength: 2000, nullable: true, validations: {isLength: {max: 300}}}
     },
-    members: {
+    members: {// 会员
         id: {type: 'string', maxlength: 24, nullable: false, primary: true},
         uuid: {type: 'string', maxlength: 36, nullable: false, unique: true, validations: {isUUID: true}},
         transient_id: {type: 'string', maxlength: 191, nullable: false, unique: true},
@@ -437,7 +450,7 @@ module.exports = {
         last_commented_at: {type: 'dateTime', nullable: true},
         created_at: {type: 'dateTime', nullable: false},
         updated_at: {type: 'dateTime', nullable: true},
-        '@@INDEXES@@': [
+        '@@INDEXES@@': [  // 索引
             ['email_disabled']
         ]
     },
@@ -1090,4 +1103,4 @@ module.exports = {
         member_id: {type: 'string', maxlength: 24, nullable: true, references: 'members.id', unique: false, setNullDelete: true},
         created_at: {type: 'dateTime', nullable: false}
     }
-};
+};

ghost/core/core/server/data/schema/validator.js

@@ -25,28 +25,38 @@ const messages = {
  *
  * ## on model add
  * - validate everything to catch required fields
+ */ 
+/**
+ * 数据库模式验证函数 - 根据schema定义验证模型数据的完整性
+ * 
+ * 这个函数负责验证传入的模型数据是否符合数据库表的schema定义，
+ * 包括数据类型、长度限制、必填字段等约束条件，如果不通过就统一抛错误，防止数据污染
  */
-function validateSchema(tableName, model, options) {
+function validateSchema(tableName, model, options) {  
     options = options || {};
 
-    const columns = _.keys(schema[tableName]);
+    const columns = _.keys(schema[tableName]);  // 获取表中所有列名
-    let validationErrors = [];
+    let validationErrors = [];  // 存储验证错误
 
-    _.each(columns, function each(columnKey) {
+    _.each(columns, function each(columnKey) {    // 遍历表中的每一列进行验证
         let message = ''; // KEEP: Validator.js only validates strings.
+        
+        // 将字段值转换为字符串进行验证（Validator.js只验证字符串）
         const strVal = _.toString(model.get(columnKey));
 
+        // 如果是更新操作且字段未改变，则跳过验证（优化性能）
         if (options.method !== 'insert' && !_.has(model.changed, columnKey)) {
             return;
-        }
+        } 
-
+        // ==================== 必填字段验证 ====================
-        // check nullable
+        // 检查非空约束：字段不可为空、不是text类型、没有默认值
         if (Object.prototype.hasOwnProperty.call(schema[tableName][columnKey], 'nullable') &&
-            schema[tableName][columnKey].nullable !== true &&
+            schema[tableName][columnKey].nullable !== true &&  // 字段不可为空
             Object.prototype.hasOwnProperty.call(schema[tableName][columnKey], 'type') &&
-            schema[tableName][columnKey].type !== 'text' &&
+            schema[tableName][columnKey].type !== 'text' &&     // 排除text类型（允许空字符串）
-            !Object.prototype.hasOwnProperty.call(schema[tableName][columnKey], 'defaultTo')
+            !Object.prototype.hasOwnProperty.call(schema[tableName][columnKey], 'defaultTo')  // 没有默认值
         ) {
+            // 检查字段值是否为空
             if (validator.isEmpty(strVal)) {
                 message = tpl(messages.valueCannotBeBlank, {
                     tableName: tableName,
@@ -54,14 +64,16 @@ function validateSchema(tableName, model, options) {
                 });
                 validationErrors.push(new errors.ValidationError({
                     message: message,
-                    context: tableName + '.' + columnKey
+                    context: tableName + '.' + columnKey  // 错误上下文：表名.字段名
                 }));
             }
-        }
+        } 
-
+        // ==================== 布尔字段验证 ====================
-        // validate boolean columns
+        // 验证布尔类型字段
         if (Object.prototype.hasOwnProperty.call(schema[tableName][columnKey], 'type')
             && schema[tableName][columnKey].type === 'boolean') {
+            
+            // 检查值是否为有效的布尔值或空值
             if (!(validator.isBoolean(strVal) || validator.isEmpty(strVal))) {
                 message = tpl(messages.valueMustBeBoolean, {
                     tableName: tableName,
@@ -73,15 +85,18 @@ function validateSchema(tableName, model, options) {
                 }));
             }
 
-            // CASE: ensure we transform 0|1 to false|true
+            // CASE: 确保将0|1转换为false|true（数据标准化）
             if (!validator.isEmpty(strVal)) {
-                model.set(columnKey, !!model.get(columnKey));
+                model.set(columnKey, !!model.get(columnKey));  // 强制转换为布尔值
             }
         }
 
-        // TODO: check if mandatory values should be enforced
+        // TODO: 检查是否应该强制执行必填值
+        // 当字段值不为null或undefined时进行进一步验证
         if (model.get(columnKey) !== null && model.get(columnKey) !== undefined) {
-            // check length
+            
+            // ==================== 长度限制验证 ====================
+            // 检查字段最大长度限制
             if (Object.prototype.hasOwnProperty.call(schema[tableName][columnKey], 'maxlength')) {
                 if (!validator.isLength(strVal, 0, schema[tableName][columnKey].maxlength)) {
                     message = tpl(messages.valueExceedsMaxLength,
@@ -97,12 +112,16 @@ function validateSchema(tableName, model, options) {
                 }
             }
 
-            // check validations objects
+            // ==================== 自定义验证规则 ====================
+            // 执行schema中定义的自定义验证规则
             if (Object.prototype.hasOwnProperty.call(schema[tableName][columnKey], 'validations')) {
-                validationErrors = validationErrors.concat(validator.validate(strVal, columnKey, schema[tableName][columnKey].validations, tableName));
+                validationErrors = validationErrors.concat(
+                    validator.validate(strVal, columnKey, schema[tableName][columnKey].validations, tableName)
+                );
             }
 
-            // check type
+            // ==================== 数据类型验证 ====================
+            // 检查整数类型字段
             if (Object.prototype.hasOwnProperty.call(schema[tableName][columnKey], 'type')) {
                 if (schema[tableName][columnKey].type === 'integer' && !validator.isInt(strVal)) {
                     message = tpl(messages.valueIsNotInteger, {
@@ -118,10 +137,13 @@ function validateSchema(tableName, model, options) {
         }
     });
 
+    // ==================== 验证结果处理 ====================
+    // 如果有验证错误，使用Promise.reject返回错误数组
     if (validationErrors.length !== 0) {
         return Promise.reject(validationErrors);
     }
 
+    // 验证通过，返回成功的Promise
     return Promise.resolve();
 }
-module.exports = validateSchema;
+module.exports = validateSchema;

ghost/core/core/server/models/label.js

@@ -1,88 +1,144 @@
+// 导入基础模块
 const ghostBookshelf = require('./base');
 const tpl = require('@tryghost/tpl');
 const errors = require('@tryghost/errors');
 
+// 定义错误消息
 const messages = {
     labelNotFound: 'Label not found.'
 };
 
+// 定义变量
 let Label;
 let Labels;
 
+/**
+ * Label 模型 - 标签数据模型
+ * 用于管理系统中的标签功能
+ */
 Label = ghostBookshelf.Model.extend({
-
+    // 数据库表名
     tableName: 'labels',
 
+    // 动作收集配置（用于记录CRUD操作）
     actionsCollectCRUD: true,
     actionsResourceType: 'label',
 
+    /**
+     * 触发变更事件
+     * @param {string} event - 事件类型
+     * @param {Object} options - 选项参数
+     */
     emitChange: function emitChange(event, options) {
         const eventToTrigger = 'label' + '.' + event;
         ghostBookshelf.Model.prototype.emitChange.bind(this)(this, eventToTrigger, options);
     },
 
+    /**
+     * 创建后钩子函数
+     */
     onCreated: function onCreated(model, options) {
         ghostBookshelf.Model.prototype.onCreated.apply(this, arguments);
-
+        // 触发添加事件
         model.emitChange('added', options);
     },
 
+    /**
+     * 更新后钩子函数
+     */
     onUpdated: function onUpdated(model, options) {
         ghostBookshelf.Model.prototype.onUpdated.apply(this, arguments);
-
+        // 触发编辑事件
         model.emitChange('edited', options);
     },
 
+    /**
+     * 删除后钩子函数
+     */
     onDestroyed: function onDestroyed(model, options) {
         ghostBookshelf.Model.prototype.onDestroyed.apply(this, arguments);
-
+        // 触发删除事件
         model.emitChange('deleted', options);
     },
 
+    /**
+     * 保存前钩子函数 - 在保存到数据库前执行
+     */
     onSaving: function onSaving(newLabel, attr, options) {
         const self = this;
 
+        // 调用父类的onSaving方法
         ghostBookshelf.Model.prototype.onSaving.apply(this, arguments);
-        // Make sure name is trimmed of extra spaces
+        
+        // 确保名称被修剪（去除前后空格）
         let name = this.get('name') && this.get('name').trim();
         this.set('name', name);
+        
+        // 如果slug发生变化，或者没有slug但有名称时，生成新的slug
         if (this.hasChanged('slug') || (!this.get('slug') && this.get('name'))) {
-            // Pass the new slug through the generator to strip illegal characters, detect duplicates
+            // 通过生成器传递新的slug，去除非法字符，检测重复
-            return ghostBookshelf.Model.generateSlug(Label, this.get('slug') || this.get('name'),
+            return ghostBookshelf.Model.generateSlug(
-                {transacting: options.transacting})
+                Label, 
-                .then(function then(slug) {
+                this.get('slug') || this.get('name'),
-                    self.set({slug: slug});
+                {transacting: options.transacting}
-                });
+            ).then(function then(slug) {
+                self.set({slug: slug});
+            });
         }
     },
 
+    /**
+     * 定义与 Member 模型的多对多关联
+     * 一个标签可以关联多个会员，一个会员可以有多个标签
+     * 通过 members_labels 中间表关联
+     */
     members: function members() {
-        return this.belongsToMany('Member', 'members_labels', 'label_id', 'member_id');
+        return this.belongsToMany(
+            'Member', 
+            'members_labels', 
+            'label_id', 
+            'member_id'
+        );
     },
 
+    /**
+     * 转换为JSON格式
+     * @param {Object} unfilteredOptions - 过滤选项
+     * @returns {Object} JSON数据
+     */
     toJSON: function toJSON(unfilteredOptions) {
         const attrs = ghostBookshelf.Model.prototype.toJSON.call(this, unfilteredOptions);
         return attrs;
     }
 }, {
+    // 静态方法和属性
+    
+    /**
+     * 默认排序选项
+     */
     orderDefaultOptions: function orderDefaultOptions() {
         return {
-            name: 'ASC',
+            name: 'ASC',        // 按名称升序
-            created_at: 'DESC'
+            created_at: 'DESC'  // 按创建时间降序
         };
     },
 
+    /**
+     * 允许的查询选项
+     * @param {string} methodName - 方法名称
+     * @returns {Array} 允许的选项数组
+     */
     permittedOptions: function permittedOptions(methodName) {
         let options = ghostBookshelf.Model.permittedOptions.call(this, methodName);
 
-        // allowlists for the `options` hash argument on methods, by method name.
+        // 按方法名称定义允许的选项白名单
-        // these are the only options that can be passed to Bookshelf / Knex.
         const validOptions = {
-            findAll: ['columns'],
+            findAll: ['columns'],   // 查找所有时允许columns选项
-            findOne: ['columns'],
+            findOne: ['columns'],   // 查找单个时允许columns选项
-            destroy: ['destroyAll']
+            destroy: ['destroyAll'] // 删除时允许destroyAll选项
         };
 
+        // 添加特定方法的允许选项
         if (validOptions[methodName]) {
             options = options.concat(validOptions[methodName]);
         }
@@ -90,47 +146,67 @@ Label = ghostBookshelf.Model.extend({
         return options;
     },
 
+    /**
+     * 定义关联计数
+     * 用于在查询时包含关联对象的计数
+     */
     countRelations() {
         return {
+            // 计算每个标签关联的会员数量
             members(modelOrCollection) {
                 modelOrCollection.query('columns', 'labels.*', (qb) => {
                     qb.count('members.id')
                         .from('members')
                         .leftOuterJoin('members_labels', 'members.id', 'members_labels.member_id')
                         .whereRaw('members_labels.label_id = labels.id')
-                        .as('count__members');
+                        .as('count__members');  // 别名为 count__members
                 });
             }
         };
     },
 
+    /**
+     * 重写销毁方法 - 删除标签及其关联关系
+     * @param {Object} unfilteredOptions - 未过滤的选项
+     * @returns {Promise} 删除操作的Promise
+     */
     destroy: function destroy(unfilteredOptions) {
+        // 过滤选项，只允许特定的额外属性
         const options = this.filterOptions(unfilteredOptions, 'destroy', {extraAllowedProperties: ['id']});
+        // 包含关联的会员数据
         options.withRelated = ['members'];
 
+        // 根据ID查找标签
         return this.forge({id: options.id})
             .fetch(options)
             .then(function destroyLabelsAndMember(label) {
+                // 如果标签不存在，抛出404错误
                 if (!label) {
                     return Promise.reject(new errors.NotFoundError({
                         message: tpl(messages.labelNotFound)
                     }));
                 }
 
+                // 先解除标签与会员的关联关系
                 return label.related('members')
                     .detach(null, options)
                     .then(function destroyLabels() {
+                        // 然后删除标签本身
                         return label.destroy(options);
                     });
             });
     }
 });
 
+/**
+ * Labels 集合 - 标签集合类
+ */
 Labels = ghostBookshelf.Collection.extend({
     model: Label
 });
 
+// 导出模型和集合
 module.exports = {
     Label: ghostBookshelf.model('Label', Label),
     Labels: ghostBookshelf.collection('Labels', Labels)
-};
+};

ghost/core/core/server/models/permission.js

@@ -1,25 +1,36 @@
+// 导入基础的Bookshelf模型
 const ghostBookshelf = require('./base');
 
+// 定义变量
 let Permission;
 let Permissions;
 
+/**
+ * Permission 模型 - 权限数据模型
+ * 用于处理系统中的权限数据
+ */
 Permission = ghostBookshelf.Model.extend({
-
+    // 数据库表名
     tableName: 'permissions',
 
+    // 定义模型关联关系
     relationships: ['roles'],
     relationshipBelongsTo: {
-        roles: 'roles'
+        roles: 'roles'  // 权限属于角色
     },
 
     /**
-     * The base model keeps only the columns, which are defined in the schema.
+     * 重写 permittedAttributes 方法
-     * We have to add the relations on top, otherwise bookshelf-relations
+     * 基础模型只保留模式中定义的列，我们需要添加关联关系
-     * has no access to the nested relations, which should be updated.
+     * 这样 bookshelf-relations 才能访问到需要更新的嵌套关系
+     * 
+     * @returns {Array} 包含所有允许属性的数组
      */
     permittedAttributes: function permittedAttributes() {
+        // 首先调用父类方法获取基础列
         let filteredKeys = ghostBookshelf.Model.prototype.permittedAttributes.apply(this, arguments);
 
+        // 添加关联关系到允许的属性列表中
         this.relationships.forEach((key) => {
             filteredKeys.push(key);
         });
@@ -27,20 +38,46 @@ Permission = ghostBookshelf.Model.extend({
         return filteredKeys;
     },
 
+    /**
+     * 定义与 Role 模型的多对多关联
+     * 一个权限可以属于多个角色，一个角色可以有多个权限
+     * 通过 permissions_roles 中间表进行关联
+     * 
+     * @returns {Bookshelf.Relation} 多对多关联关系
+     */
     roles: function roles() {
-        return this.belongsToMany('Role', 'permissions_roles', 'permission_id', 'role_id');
+        return this.belongsToMany(
+            'Role',                   // 关联的模型名称
+            'permissions_roles',      // 中间表名
+            'permission_id',          // 当前模型在中间表中的外键
+            'role_id'                 // 关联模型在中间表中的外键
+        );
     },
 
+    /**
+     * 定义与 User 模型的多对多关联
+     * 一个权限可以直接关联多个用户（如果需要的话）
+     * 
+     * @returns {Bookshelf.Relation} 多对多关联关系
+     */
     users: function users() {
         return this.belongsToMany('User');
     }
 });
 
+/**
+ * Permissions 集合 - 权限集合类
+ * 用于处理多个权限对象的集合操作
+ */
 Permissions = ghostBookshelf.Collection.extend({
+    // 指定集合中模型的类型
     model: Permission
 });
 
+// 导出模型和集合
 module.exports = {
+    // 注册 Permission 模型到 Bookshelf
     Permission: ghostBookshelf.model('Permission', Permission),
+    // 注册 Permissions 集合到 Bookshelf
     Permissions: ghostBookshelf.collection('Permissions', Permissions)
-};
+};

ghost/core/core/server/models/post.js

@@ -530,7 +530,7 @@ Post = ghostBookshelf.Model.extend({
             author.emitChange('attached', options);
         });
     },
-
+//1030   max
     onSaving: async function onSaving(model, attrs, options) {
         options = options || {};
 
@@ -577,7 +577,7 @@ Post = ghostBookshelf.Model.extend({
         }
 
         // CASE: both page and post can get scheduled
-        if (newStatus === 'scheduled') {
+        if (newStatus === 'scheduled') {  //定时发布状态检查
             if (!publishedAt) {
                 return Promise.reject(new errors.ValidationError({
                     message: tpl(messages.valueCannotBeBlank, {key: 'published_at'})
@@ -604,6 +604,7 @@ Post = ghostBookshelf.Model.extend({
         // CASE: Force a change for scheduled posts within 2 minutes of
         // publishing. This ensures the scheduler can detect last-minute
         // touches to the post
+        //通过多种判断来防漏发布
         const isScheduled = newStatus === 'scheduled';
         const isUpdate = options.method === 'update';
         const isWithin2Minutes = publishedAt && moment(publishedAt).diff(moment(), 'minutes') <= 2;

ghost/core/core/server/models/role.js

@@ -41,7 +41,6 @@ Role = ghostBookshelf.Model.extend({
      */
     permittedOptions: function permittedOptions(methodName) {
         let options = ghostBookshelf.Model.permittedOptions.call(this, methodName);
-
         // allowlists for the `options` hash argument on methods, by method name.
         // these are the only options that can be passed to Bookshelf / Knex.
         const validOptions = {
@@ -55,7 +54,7 @@ Role = ghostBookshelf.Model.extend({
 
         return options;
     },
-
+    //检查用户是否有权执行某个操作 权限检查核心方法
     permissible: function permissible(roleModelOrId, action, context, unsafeAttrs, loadedPermissions, hasUserPermission, hasApiKeyPermission) {
         // If we passed in an id instead of a model, get the model
         // then check the permissions
@@ -67,17 +66,15 @@ Role = ghostBookshelf.Model.extend({
                         throw new errors.NotFoundError({
                             message: tpl(messages.roleNotFound)
                         });
-                    }
+                    } 
-
                     // Grab the original args without the first one
                     const origArgs = _.toArray(arguments).slice(1);
 
                     return this.permissible(foundRoleModel, ...origArgs);
                 });
-        }
+        } 
-
+        const roleModel = roleModelOrId; 
-        const roleModel = roleModelOrId;
+        // 检查用户是否有赋值权限
-
         if (action === 'assign' && loadedPermissions.user) {
             const {isOwner, isAdmin, isEitherEditor} = setIsRoles(loadedPermissions);
             let checkAgainst;
@@ -87,12 +84,11 @@ Role = ghostBookshelf.Model.extend({
                 checkAgainst = ['Administrator', 'Super Editor', 'Editor', 'Author', 'Contributor'];
             } else if (isEitherEditor) {
                 checkAgainst = ['Author', 'Contributor'];
-            }
+            } 
-
             // Role in the list of permissible roles
             hasUserPermission = roleModelOrId && _.includes(checkAgainst, roleModel.get('name'));
         }
-
+        // 检查apiKey是否有赋值权限
         if (action === 'assign' && loadedPermissions.apiKey) {
             // apiKey cannot 'assign' the 'Owner' role
             if (roleModel.get('name') === 'Owner') {
@@ -103,7 +99,7 @@ Role = ghostBookshelf.Model.extend({
         }
 
         if (hasUserPermission && hasApiKeyPermission) {
-            return Promise.resolve();
+            return Promise.resolve();   // 同时有用户权限和apiKey权限，返回成功
         }
 
         return Promise.reject(new errors.NoPermissionError({message: tpl(messages.notEnoughPermission)}));

ghost/core/core/server/models/tag.js

@@ -1,3 +1,30 @@
+/*
+ * Tag model
+ *
+ * Responsibilities:
+ * - Represent the 'tags' table via Bookshelf/ghostBookshelf
+ * - Handle slug generation and normalization on save
+ * - Provide relations to posts (belongsToMany)
+ * - Convert transform-ready urls to absolute on parse, and prepare urls on write
+ * - Emit tag.* events on create/update/delete for webhooks and internals
+ * - Provide a custom destroy which detaches post relations before deleting
+ *
+ * Notes:
+ * - Many services call into models.Tag (e.g. PostsService) to create or link tags.
+ * - countRelations defines how to include posts counts when requested via include=count.posts
+ */
+/*
+ * 中文说明：
+ * 本模型封装了 tags 表的数据库映射与行为，提供给服务层与 API 层使用：
+ * - 在保存时处理 slug 的生成与规范化（onSaving），并根据 name 前缀处理 visibility（例如以 `#` 开头视为内部标签）。
+ * - 对 URL 字段在读取/写入时进行转换（parse / formatOnWrite），以便模板/序列化使用绝对/transform-ready 的 URL。
+ * - 定义与 posts 的多对多关系（posts），并在删除标签前负责解除与所有帖子的关联（自定义 destroy 实现），以防止孤立的关联数据。
+ * - 触发生命周期事件（tag.added / tag.edited / tag.deleted），供 webhook、事件系统或其他内部服务订阅。
+ *
+ * 注意：
+ * - 许多业务逻辑（例如 PostsService）会调用此模型创建或关联标签，修改模型的行为可能影响这些调用点。
+ * - 当需要在公开 API 中返回统计信息（include=count.posts）时，countRelations 提供了构造查询的方法，注意在公共上下文中对帖子的过滤（published,type=post）。
+ */
 const ghostBookshelf = require('./base');
 const tpl = require('@tryghost/tpl');
 const errors = require('@tryghost/errors');
@@ -98,6 +125,11 @@ Tag = ghostBookshelf.Model.extend({
         model.emitChange('deleted', options);
     },
 
+    // onSaving hook runs before persisting a tag.
+    // Responsibilities:
+    // - Ensure a name exists when only slug is supplied (e.g. nested creation)
+    // - Detect internal tags (name starts with '#') and set visibility
+    // - Generate a unique slug when necessary using the shared generator
     onSaving: function onSaving(newTag, attr, options) {
         const self = this;
 
@@ -126,10 +158,12 @@ Tag = ghostBookshelf.Model.extend({
         }
     },
 
+    // Relationship: tags <-> posts (many-to-many)
     posts: function posts() {
         return this.belongsToMany('Post');
     },
 
+    // toJSON: normalize attributes when serializing model instances
     toJSON: function toJSON(unfilteredOptions) {
         const attrs = ghostBookshelf.Model.prototype.toJSON.call(this, unfilteredOptions);
 
@@ -141,6 +175,7 @@ Tag = ghostBookshelf.Model.extend({
     },
 
     defaultColumnsToFetch() {
+        // By default, fetching minimal columns for lightweight queries
         return ['id'];
     }
 }, {
@@ -166,6 +201,7 @@ Tag = ghostBookshelf.Model.extend({
         return options;
     },
 
+    // Configure how to compute relation counts when include=count.posts is requested
     countRelations() {
         return {
             posts(modelOrCollection, options) {
@@ -186,6 +222,11 @@ Tag = ghostBookshelf.Model.extend({
         };
     },
 
+    // Custom destroy implementation which:
+    // - Fetches the tag with related posts
+    // - Detaches all posts from the tag (posts_tags entries)
+    // - Deletes the tag row
+    // This prevents orphaned relations and mirrors expected semantics when deleting a tag.
     destroy: function destroy(unfilteredOptions) {
         const options = this.filterOptions(unfilteredOptions, 'destroy', {extraAllowedProperties: ['id']});
         options.withRelated = ['posts'];