完善注释

package.json

@@ -26,7 +26,8 @@
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.1",
     "simple-git": "^3.28.0",
-    "ssh2": "^1.16.0"
+    "ssh2": "^1.16.0",
+    "ws": "^8.18.3"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.2.0",
@@ -40,6 +41,7 @@
     "@types/jest": "^29.5.14",
     "@types/node": "^22.16.4",
     "@types/supertest": "^6.0.2",
+    "@types/ws": "^8.18.1",
     "eslint": "^9.18.0",
     "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-prettier": "^5.2.2",

pnpm-lock.yaml

@@ -41,6 +41,9 @@ dependencies:
   ssh2:
     specifier: ^1.16.0
     version: 1.16.0
+  ws:
+    specifier: ^8.18.3
+    version: 8.18.3
 
 devDependencies:
   '@eslint/eslintrc':
@@ -76,6 +79,9 @@ devDependencies:
   '@types/supertest':
     specifier: ^6.0.2
     version: 6.0.3
+  '@types/ws':
+    specifier: ^8.18.1
+    version: 8.18.1
   eslint:
     specifier: ^9.18.0
     version: 9.31.0
@@ -2008,6 +2014,12 @@ packages:
       '@types/superagent': 8.1.9
     dev: true
 
+  /@types/ws@8.18.1:
+    resolution: {integrity: sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==}
+    dependencies:
+      '@types/node': 22.16.5
+    dev: true
+
   /@types/yargs-parser@21.0.3:
     resolution: {integrity: sha512-I4q9QU9MQv4oEOz4tAHJtNz1cwuLxn2F3xcc2iV5WdqLPpUnj30aUuxt1mAxYTG+oe8CZMV/+6rU4S4gRDzqtQ==}
     dev: true
@@ -6487,6 +6499,19 @@ packages:
       signal-exit: 3.0.7
     dev: true
 
+  /ws@8.18.3:
+    resolution: {integrity: sha512-PEIGCY5tSlUt50cqyMXfCzX+oOPqN0vuGqWzbcJ2xvnkzkq46oOpz7dQaTDBdfICb4N14+GARUDw2XV2N4tvzg==}
+    engines: {node: '>=10.0.0'}
+    peerDependencies:
+      bufferutil: ^4.0.1
+      utf-8-validate: '>=5.0.2'
+    peerDependenciesMeta:
+      bufferutil:
+        optional: true
+      utf-8-validate:
+        optional: true
+    dev: false
+
   /xtend@4.0.2:
     resolution: {integrity: sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==}
     engines: {node: '>=0.4'}

src/common/filters/all-exception.filter.ts

@@ -6,6 +6,9 @@ import {
   HttpStatus,
 } from '@nestjs/common';
 
+/**
+ * 异常类
+ */
 @Catch()
 export class AllExceptionsFilter implements ExceptionFilter {
   catch(exception: unknown, host: ArgumentsHost) {

src/common/interceptors/response.interceptor.ts

@@ -7,6 +7,9 @@ import {
 import { Observable, map } from 'rxjs';
 import { ApiResponse } from '../response-format';
 
+/**
+ * 规范返回格式
+ */
 @Injectable()
 export class ResponseInterceptor<T>
   implements NestInterceptor<T, ApiResponse<T>>

src/config/config.service.ts

@@ -14,6 +14,11 @@ export class AppConfigService implements OnModuleInit {
     this.checkRequiredVariables();
   }
 
+  /**
+   * 获取环境变量
+   * @param key 键值
+   * @param defaultValue 默认
+   */
   get<T = string>(key: string, defaultValue?: T): T | undefined {
     const value = this.nestConfigService.get<T>(key);
     if (value === undefined || value === null) {

src/core/auto-update/auto-update.service.ts

@@ -22,7 +22,7 @@ export class AutoUpdateService {
   }
 
   /**
-   * 检查是否有远程更新
+   * 检查远程更新
    */
   async checkForUpdates(): Promise<boolean> {
     try {

src/core/persistence/persistence.service.ts

@@ -28,6 +28,12 @@ export class PersistenceService {
     }
   }
 
+  /**
+   * 将数据保存到本地 带格式化
+   * @param dataName 数据名 -> 文件夹名
+   * @param data 内容
+   * @param fileName 文件名
+   */
   public async writeDataLocal<T>(
     dataName: string,
     data: T,
@@ -44,6 +50,11 @@ export class PersistenceService {
     }
   }
 
+  /**
+   * 从本地读取数据 带解析
+   * @param dataName 数据名 -> 文件夹名
+   * @param fileName 文件名
+   */
   public async readDataLocal<T>(
     dataName: string,
     fileName: string,

src/core/redis/redis.service.ts

@@ -63,7 +63,7 @@ export class RedisService implements OnModuleInit {
 
     this.client.on('ready', () => {
       this.isConnected = true;
-      this.logger.debug('Redis连接就绪!');
+      this.logger.log('Redis连接就绪!');
     });
 
     this.client.on('reconnecting', () => {
@@ -71,6 +71,9 @@ export class RedisService implements OnModuleInit {
     });
   }
 
+  /**
+   * 等待redis就绪
+   */
   public async waitUntilReady(): Promise<void> {
     if (this.isConnected) return;
     return new Promise((resolve) => {
@@ -80,6 +83,9 @@ export class RedisService implements OnModuleInit {
     });
   }
 
+  /**
+   * 获取单一redis实例
+   */
   public getClient(): Redis {
     if (!this.isConnected) {
       this.logger.error('Redis未连接');
@@ -87,11 +93,20 @@ export class RedisService implements OnModuleInit {
     return this.client;
   }
 
+  /**
+   * 断开连接
+   */
   public async disconnect(): Promise<void> {
     await this.client.quit();
     this.isConnected = false;
   }
 
+  /**
+   * 储存对象
+   * @param key 键
+   * @param value 键值
+   * @param ttl 缓存时间
+   */
   public async setObject<T>(
     key: string,
     value: T,
@@ -104,6 +119,10 @@ export class RedisService implements OnModuleInit {
     }
   }
 
+  /**
+   * 从redis中获取对象
+   * @param key 键
+   */
   public async getObject<T>(key: string): Promise<T | undefined> {
     const serialized = await this.client.get(key);
     if (!serialized) return undefined;
@@ -111,6 +130,11 @@ export class RedisService implements OnModuleInit {
     return RedisUtils.reviveDates(deserialized);
   }
 
+  /**
+   * 更新redis中的呃对象
+   * @param key
+   * @param updates
+   */
   public async update<T>(key: string, updates: T): Promise<T> {
     const existing = await this.getObject<T>(key);
     if (!existing) {
@@ -121,6 +145,11 @@ export class RedisService implements OnModuleInit {
     return updated;
   }
 
+  /**
+   * 从本地或redis获取对象
+   * @param key 键 / 文件夹名
+   * @param fileName 文件名
+   */
   public async fetch<T>(key: string, fileName: string): Promise<T | undefined> {
     const data = await this.getObject<T>(key);
     if (data) return data;
@@ -134,6 +163,12 @@ export class RedisService implements OnModuleInit {
     this.logger.error(`数据${key}不存在`);
   }
 
+  /**
+   * 保存对象
+   * @param key 键
+   * @param data 内容
+   * @param fileName 文件名
+   */
   public async persistData<T>(
     key: string,
     data: T,

src/core/system/system.service.ts

@@ -56,6 +56,9 @@ export class SystemService {
     process.exit(0);
   }
 
+  /**
+   * 检查更新
+   */
   async checkUpdate(): Promise<void> {
     const updated = await this.autoUpdateService.checkForUpdates();
     if (updated) {

src/types/ws.ts

@@ -0,0 +1,18 @@
+import WebSocket from 'ws';
+
+export interface AuthenticatedSocket extends WebSocket {
+  isAuthed?: boolean;
+  clientId?: string;
+  heartbeat?: NodeJS.Timeout;
+}
+
+export interface WSMessage {
+  type: string;
+  [key: string]: unknown;
+}
+
+export interface AuthMessage extends WSMessage {
+  type: 'auth';
+  secret: string;
+  clientId: string;
+}