feat: 添加3D文档聚类散点图功能

- 引入echarts-gl依赖以支持3D图表渲染
- 新增ClusterScatter数据结构定义
- 实现2D/3D视图切换功能
- 添加WebGL兼容性检测机制
- 重构聚类页面UI布局和交互逻辑
- 更新路由配置以支持.html扩展名访问

Author: 0xcaffebabe

package-lock.json

@@ -17,6 +17,7 @@
     "@element-plus/icons-vue": "2.3.2",
     "algoliasearch": "4.26.0",
     "echarts": "6.0.0",
+    "echarts-gl": "^2.1.0",
     "element-plus": "2.13.2",
     "js-yaml": "4.1.1",
     "jsmind": "0.9.1",

package.json

@@ -11,6 +11,7 @@ import UrlConst from '@/const/UrlConst'
 import CommitInfo from '@/dto/CommitInfo'
 import Category from '@/dto/Category'
 import ClusterNode from '@/dto/ClusterNode'
+import ClusterScatter from '@/dto/ClusterScatterPoint'
 import DocQuality from '@/dto/doc/DocQuality'
 import KnowledgeRichnessNode from '@/dto/KnowledgeRichnessNode'
 // import DocService from '@/service/DocService'
@@ -83,6 +84,11 @@ class Api implements Cacheable{
     return http(UrlUtils.concatUrl(baseUrl(), UrlConst.docClusterJson)).then(r => r.json())
   }
 
+  @cache
+  public async getDocClusterScatter(): Promise<ClusterScatter> {
+    return http(UrlUtils.concatUrl(baseUrl(), UrlConst.docClusterScatterJson)).then(r => r.json())
+  }
+
   @cache
   public async getKnowledgeRichness(): Promise<KnowledgeRichnessNode[]> {
     return http(UrlUtils.concatUrl(baseUrl(), UrlConst.knowledgeRichnessJson)).then(r => r.json())

src/api/index.ts

@@ -14,6 +14,7 @@ import Cacheable from "@/decorator/Cacheable";
 import ArrayUtils from "../util/ArrayUtils";
 import CommitInfo from "@/dto/CommitInfo";
 import ClusterNode from "@/dto/ClusterNode";
+import ClusterScatter from "@/dto/ClusterScatterPoint";
 import DocQuality from "../dto/doc/DocQuality";
 import Cache from "../decorator/Cache";
 import generateDocCluster from '../scripts/generateDocCluster'
@@ -191,6 +192,11 @@ class DocService extends BaseService implements Cacheable {
     return generateDocCluster.main(true)
   }
 
+  @cache
+  public async getDocClusterScatter(): Promise<ClusterScatter> {
+    return generateDocCluster.generateClusterScatter()
+  }
+
   public async getDocTagPrediction() {
     return (await generateDocCluster.generateDocTagPrediction())
   }

src/build/DocService.ts

@@ -102,7 +102,7 @@ export default defineComponent({
       navList: [
         { name: '首页', path: '/home.html', match: '/home' },
         { name: '标签', path: '/tag.html', match: '/tag' },
-        { name: '聚类', path: '/cluster', match: '/cluster' },
+        { name: '聚类', path: '/cluster.html', match: '/cluster' },
       ],
     };
   },

src/components/header/Header.vue

@@ -12,6 +12,7 @@ export default {
   tagMappingJson: '/tagMapping.json',
   wordcloudJson: '/wordcloud.json',
   docClusterJson: '/docCluster.json',
+  docClusterScatterJson: '/docClusterScatter.json',
   docTagPrediction: '/docTagPrediction.json',
   docQualityJson: '/docQuality.json',
   textSimilarJson: '/textSimilar.json',

src/const/UrlConst.ts

@@ -0,0 +1,27 @@
+// 散点聚类图的单个文档点
+export interface ClusterScatterPoint {
+  id: string          // docUrl2Id 后的文档 id, 供跳转
+  name: string        // 原始文件路径(前端 displayName 截取文件名)
+  x: number           // 2D MDS 投影坐标
+  y: number
+  x3: number          // 3D MDS 投影坐标
+  y3: number
+  z3: number
+  cluster: number     // K-means 簇标签
+  tags: string[]      // frontmatter tags, 供 tooltip
+  size: number        // 点径编码(正文长度归一)
+}
+
+// 簇元信息, 供图例
+export interface ClusterMeta {
+  id: number
+  label: string       // 簇主 tag(自动命名), 无则 "簇 N"
+  size: number        // 成员数
+}
+
+export interface ClusterScatter {
+  points: ClusterScatterPoint[]
+  clusters: ClusterMeta[]
+}
+
+export default ClusterScatter

src/dto/ClusterScatterPoint.ts

@@ -3,4 +3,12 @@ declare module '@vue/runtime-core' {
   interface ComponentCustomProperties {
     $isMobile: () => boolean
   }
+}
+
+// echarts-gl 未随包提供类型声明, 这里给出最小模块声明(install 形态, 供 echarts.use)
+declare module 'echarts-gl/charts' {
+  export const Scatter3DChart: any
+}
+declare module 'echarts-gl/components' {
+  export const Grid3DComponent: any
 }