@nest-omni/core 4.1.3-2 → 4.1.3-20

package/validators/custom-validate.validator.js

@@ -28,6 +28,9 @@ let CustomValidateValidator = class CustomValidateValidator {
     constructor(moduleRef) {
         this.moduleRef = moduleRef;
     }
+    /**
+     * 验证入口
+     */
     validate(value, args) {
         return __awaiter(this, void 0, void 0, function* () {
             const [constraint, ...extraArgs] = args.constraints;
@@ -40,12 +43,15 @@ let CustomValidateValidator = class CustomValidateValidator {
                 args,
             };
             try {
+                // 1. 如果是函数，直接调用
                 if (typeof constraint === 'function') {
                     return yield this.callFunction(constraint, value, context, extraArgs);
                 }
+                // 2. 如果是字符串，调用 Entity 方法
                 if (typeof constraint === 'string') {
                     return yield this.callEntityMethod(args.object, constraint, value, context, extraArgs);
                 }
+                // 3. 如果是数组，调用 Service 方法
                 if (Array.isArray(constraint)) {
                     return yield this.callServiceMethod(constraint, value, context);
                 }
@@ -53,17 +59,24 @@ let CustomValidateValidator = class CustomValidateValidator {
                     `Expected: function, string, or array. Got: ${typeof constraint}`);
             }
             catch (error) {
+                // 验证函数执行出错，记录详细错误信息
                 console.error(`[@CustomValidate] Validation error for property "${args.property}":`, error);
                 throw error;
             }
         });
     }
+    /**
+     * 调用内联函数
+     */
     callFunction(fn, value, context, extraArgs) {
         return __awaiter(this, void 0, void 0, function* () {
             const result = fn(value, context, ...extraArgs);
             return result instanceof Promise ? yield result : result;
         });
     }
+    /**
+     * 调用 Entity 方法
+     */
     callEntityMethod(entity, methodName, value, context, extraArgs) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!entity || typeof entity[methodName] !== 'function') {
@@ -74,13 +87,18 @@ let CustomValidateValidator = class CustomValidateValidator {
             return result instanceof Promise ? yield result : result;
         });
     }
+    /**
+     * 调用 Service 方法
+     */
     callServiceMethod(constraint, value, context) {
         return __awaiter(this, void 0, void 0, function* () {
             let [serviceClass, methodName, ...extraArgs] = constraint;
+            // 验证参数
             if (!serviceClass || !methodName) {
                 throw new Error(`[@CustomValidate] Invalid service constraint format. ` +
                     `Expected: [ServiceClass, 'methodName'] or [() => ServiceClass, 'methodName']`);
             }
+            // 解析延迟引用（解决循环依赖）
             if (typeof serviceClass === 'function' && !serviceClass.prototype) {
                 serviceClass = serviceClass();
             }
@@ -89,6 +107,7 @@ let CustomValidateValidator = class CustomValidateValidator {
                     `This may be caused by circular dependencies. ` +
                     `Consider using lazy reference: [() => ServiceClass, 'methodName']`);
             }
+            // 通过依赖注入获取 service 实例
             let service;
             try {
                 service = this.moduleRef.get(serviceClass, { strict: false });
@@ -106,7 +125,11 @@ let CustomValidateValidator = class CustomValidateValidator {
             return result instanceof Promise ? yield result : result;
         });
     }
+    /**
+     * 默认错误消息
+     */
     defaultMessage(args) {
+        // 优先使用 i18n
         return (0, nestjs_i18n_1.i18nValidationMessage)('validation.CUSTOM_VALIDATE')(args);
     }
 };
@@ -116,6 +139,68 @@ exports.CustomValidateValidator = CustomValidateValidator = __decorate([
     (0, class_validator_1.ValidatorConstraint)({ name: 'customValidate', async: true }),
     __metadata("design:paramtypes", [core_1.ModuleRef])
 ], CustomValidateValidator);
+/**
+ * @CustomValidate 装饰器
+ *
+ * 支持多种验证方式的灵活验证装饰器
+ *
+ * @example
+ *
+ * // 1. 内联函数（同步）
+ * @CustomValidate(
+ *   (value) => value > 0,
+ *   { message: '价格必须大于0' }
+ * )
+ * price: number;
+ *
+ * @example
+ * // 2. 内联函数（异步）
+ * @CustomValidate(
+ *   async (value, context) => {
+ *     const response = await fetch(`/api/check/${value}`);
+ *     return response.ok;
+ *   }
+ * )
+ * username: string;
+ *
+ * @example
+ * // 3. Entity 方法
+ * @CustomValidate('validateVersion')
+ * version: string;
+ *
+ * validateVersion(value: string): boolean {
+ *   return /^\d+\.\d+\.\d+$/.test(value);
+ * }
+ *
+ * @example
+ * // 4. Service 方法
+ * @CustomValidate([UserValidationService, 'checkUsername'])
+ * username: string;
+ *
+ * @example
+ * // 5. 延迟引用（解决循环依赖）
+ * @CustomValidate([() => UserValidationService, 'checkUsername'])
+ * username: string;
+ *
+ * @example
+ * // 6. 带额外参数
+ * @CustomValidate(
+ *   [ValidationService, 'checkRange', 0, 100],
+ *   { message: '价格必须在 0-100 之间' }
+ * )
+ * price: number;
+ *
+ * @example
+ * // 7. 使用 i18n
+ * @CustomValidate(
+ *   (value) => value.length >= 6,
+ *   { message: 'validation.PASSWORD_TOO_SHORT' }
+ * )
+ * password: string;
+ *
+ * @param constraint 验证约束（函数、方法名、或 [Service, 方法名]）
+ * @param validationOptions 验证选项
+ */
 function CustomValidate(constraint, validationOptions) {
     return (object, propertyName) => {
         (0, class_validator_1.registerDecorator)({

package/validators/file-mimetype.validator.d.ts

@@ -5,8 +5,6 @@ export type FileMimetypeValidatorOptions = {
     message?: string;
 };
 export declare class FileMimetypeValidator extends FileValidator<FileMimetypeValidatorOptions, IFile> {
-    private allowedMimetypes;
-    private message;
     constructor(options: FileMimetypeValidatorOptions);
     buildErrorMessage(): string;
     isValid(file?: IFile): boolean;

package/validators/file-mimetype.validator.js

@@ -5,17 +5,15 @@ const file_validator_interface_1 = require("@nestjs/common/pipes/file/file-valid
 class FileMimetypeValidator extends file_validator_interface_1.FileValidator {
     constructor(options) {
         super(options);
-        this.allowedMimetypes = options.allowedMimetypes;
-        this.message = options.message;
     }
     buildErrorMessage() {
-        if (this.message) {
-            return this.message;
+        if (this.validationOptions.message) {
+            return this.validationOptions.message;
         }
-        return `Invalid file type. Only ${this.allowedMimetypes.join(', ')} are allowed.`;
+        return `Invalid file type. Only ${this.validationOptions.allowedMimetypes.join(', ')} are allowed.`;
     }
     isValid(file) {
-        return this.allowedMimetypes.includes(file.mimetype);
+        return this.validationOptions.allowedMimetypes.includes(file.mimetype);
     }
 }
 exports.FileMimetypeValidator = FileMimetypeValidator;

package/validators/index.d.ts

@@ -5,3 +5,4 @@ export * from './is-exists.validator';
 export * from './is-unique.validator';
 export * from './same-as.validator';
 export * from './custom-validate.validator';
+export * from './common-validators';

package/validators/index.js

@@ -21,3 +21,4 @@ __exportStar(require("./is-exists.validator"), exports);
 __exportStar(require("./is-unique.validator"), exports);
 __exportStar(require("./same-as.validator"), exports);
 __exportStar(require("./custom-validate.validator"), exports);
+__exportStar(require("./common-validators"), exports);

package/validators/is-exists.validator.d.ts

@@ -1,18 +1,38 @@
 import type { ValidationArguments, ValidationOptions, ValidatorConstraintInterface } from 'class-validator';
 import type { EntitySchema, FindOptionsWhere, ObjectType } from 'typeorm';
-import { TransactionHost } from '@nestjs-cls/transactional';
-import { TransactionalAdapterTypeOrm } from '@nestjs-cls/transactional-adapter-typeorm';
 export declare class IsExistsValidator implements ValidatorConstraintInterface {
-    private readonly transactionHost;
-    constructor(transactionHost: TransactionHost<TransactionalAdapterTypeOrm>);
+    constructor();
+    /**
+     * 解析 Entity 引用，支持多种形式：
+     * 1. Entity 类直接引用
+     * 2. 延迟函数 () => Entity
+     * 3. 字符串名称 "EntityName"
+     * 4. undefined (从属性名自动推断)
+     */
     private resolveEntity;
+    /**
+     * 从属性名推断 Entity 名称
+     * 例如：appId -> App, userId -> User
+     */
     private inferEntityNameFromProperty;
     validate<E>(value: string, args: IExistsValidationArguments<E>): Promise<boolean>;
     defaultMessage(args: ValidationArguments): string;
 }
+/**
+ * IsExists 配置选项
+ */
+export interface IsExistsOptions {
+    /**
+     * 数据源名称或 DataSource 实例
+     * 用于多数据源场景，指定使用哪个数据源进行验证
+     * 例如：'readonly', 'report', 或直接传入 DataSource 实例
+     */
+    dataSource?: string;
+}
 type ExistsValidationConstraints<E> = [
-    ObjectType<E> | EntitySchema<E> | string | (() => ObjectType<E> | EntitySchema<E> | string),
-    (validationArguments: ValidationArguments) => FindOptionsWhere<E>
+    (ObjectType<E> | EntitySchema<E> | string | (() => ObjectType<E> | EntitySchema<E> | string)),
+    (validationArguments: ValidationArguments) => FindOptionsWhere<E>,
+    IsExistsOptions?
 ];
 interface IExistsValidationArguments<E> extends ValidationArguments {
     constraints: ExistsValidationConstraints<E>;

package/validators/is-exists.validator.js

@@ -23,31 +23,44 @@ exports.IsExists = IsExists;
 const class_validator_1 = require("class-validator");
 const nestjs_i18n_1 = require("nestjs-i18n");
 const common_1 = require("@nestjs/common");
-const transactional_1 = require("@nestjs-cls/transactional");
+const transaction_1 = require("@nest-omni/transaction");
 let IsExistsValidator = class IsExistsValidator {
-    constructor(transactionHost) {
-        this.transactionHost = transactionHost;
-    }
+    constructor() { }
+    /**
+     * 解析 Entity 引用，支持多种形式：
+     * 1. Entity 类直接引用
+     * 2. 延迟函数 () => Entity
+     * 3. 字符串名称 "EntityName"
+     * 4. undefined (从属性名自动推断)
+     */
     resolveEntity(entityRef, propertyName, object) {
+        // 1. 如果是字符串，直接返回（TypeORM 支持字符串）
         if (typeof entityRef === 'string') {
             return entityRef;
         }
+        // 2. 如果是函数，需要区分延迟函数和 Entity 类
         if (typeof entityRef === 'function') {
+            // 2.1 箭头函数没有 prototype，是延迟函数
             if (!entityRef.prototype) {
                 const resolved = entityRef();
                 if (resolved)
                     return resolved;
             }
             else {
+                // 2.2 有 prototype，是 Entity 类或普通构造函数
+                // 直接返回
                 return entityRef;
             }
         }
+        // 3. 如果是 undefined，尝试从属性名推断 Entity
+        // 例如：appId -> AppEntity, userId -> UserEntity
         if (!entityRef) {
             const inferredEntityName = this.inferEntityNameFromProperty(propertyName);
             if (inferredEntityName) {
                 console.warn(`[IsExists] Entity reference is undefined for property "${propertyName}". ` +
                     `This may be caused by circular dependencies. ` +
                     `Consider using lazy reference: () => ${inferredEntityName}`);
+                // 返回字符串形式的 Entity 名称
                 return inferredEntityName;
             }
         }
@@ -58,18 +71,28 @@ let IsExistsValidator = class IsExistsValidator {
             `2. String reference: @IsExists(["EntityName", ...])\n` +
             `3. Break the circular dependency`);
     }
+    /**
+     * 从属性名推断 Entity 名称
+     * 例如：appId -> App, userId -> User
+     */
     inferEntityNameFromProperty(propertyName) {
+        // 移除常见后缀：Id, Ids, Key, Code
         const name = propertyName.replace(/(Id|Ids|Key|Code)$/, '');
         if (!name)
             return null;
+        // 转换为 PascalCase 并添加 Entity 后缀
         const entityName = name.charAt(0).toUpperCase() + name.slice(1) + 'Entity';
         return entityName;
     }
     validate(value, args) {
         return __awaiter(this, void 0, void 0, function* () {
-            const [entityRef, findCondition] = args.constraints;
+            const [entityRef, findCondition, options] = args.constraints;
+            // 解析 Entity 引用
             const entityClass = this.resolveEntity(entityRef, args.property, args.object);
-            const repository = this.transactionHost.tx.getRepository(entityClass);
+            // 获取数据源（支持多数据源）
+            const dataSourceName = (options === null || options === void 0 ? void 0 : options.dataSource) || 'default';
+            const dataSource = (0, transaction_1.getDataSource)(dataSourceName);
+            const repository = dataSource.getRepository(entityClass);
             args.value = value;
             return ((yield repository.count({
                 where: findCondition(args),
@@ -84,7 +107,7 @@ exports.IsExistsValidator = IsExistsValidator;
 exports.IsExistsValidator = IsExistsValidator = __decorate([
     (0, common_1.Injectable)(),
     (0, class_validator_1.ValidatorConstraint)({ name: 'isExists', async: true }),
-    __metadata("design:paramtypes", [transactional_1.TransactionHost])
+    __metadata("design:paramtypes", [])
 ], IsExistsValidator);
 function IsExists(constraints, validationOptions) {
     return (object, propertyName) => {

package/validators/is-unique.validator.d.ts

@@ -1,18 +1,44 @@
 import type { ValidationArguments, ValidationOptions, ValidatorConstraintInterface } from 'class-validator';
-import { EntitySchema, FindOptionsWhere, ObjectType } from 'typeorm';
-import { TransactionHost } from '@nestjs-cls/transactional';
-import { TransactionalAdapterTypeOrm } from '@nestjs-cls/transactional-adapter-typeorm';
+import type { EntitySchema, FindOptionsWhere, ObjectType } from 'typeorm';
 export declare class IsUniqueValidator implements ValidatorConstraintInterface {
-    private readonly transactionHost;
-    constructor(transactionHost: TransactionHost<TransactionalAdapterTypeOrm>);
+    constructor();
+    /**
+     * 解析 Entity 引用，支持多种形式：
+     * 1. Entity 类直接引用
+     * 2. 延迟函数 () => Entity
+     * 3. 字符串名称 "EntityName"
+     * 4. undefined (从属性名自动推断)
+     */
     private resolveEntity;
+    /**
+     * 从属性名推断 Entity 名称
+     * 例如：appId -> App, userId -> User
+     */
     private inferEntityNameFromProperty;
     validate<E>(value: string, args: IUniqueValidationArguments<E>): Promise<boolean>;
     defaultMessage(args: ValidationArguments): string;
 }
+/**
+ * IsUnique 配置选项
+ */
+export interface IsUniqueOptions {
+    /**
+     * 手动指定用于判断是否为新建的字段名
+     * 适用于视图（View）等没有主键的场景
+     * 例如：uniqueKeys: ['id'] 或 uniqueKeys: ['id', 'version']
+     */
+    uniqueKeys?: string[];
+    /**
+     * 数据源名称或 DataSource 实例
+     * 用于多数据源场景，指定使用哪个数据源进行验证
+     * 例如：'readonly', 'report', 或直接传入 DataSource 实例
+     */
+    dataSource?: string;
+}
 type UniqueValidationConstraints<E> = [
-    ObjectType<E> | EntitySchema<E> | string | (() => ObjectType<E> | EntitySchema<E> | string),
-    (validationArguments: ValidationArguments) => FindOptionsWhere<E>
+    (ObjectType<E> | EntitySchema<E> | string | (() => ObjectType<E> | EntitySchema<E> | string)),
+    (validationArguments: ValidationArguments) => FindOptionsWhere<E>,
+    IsUniqueOptions?
 ];
 interface IUniqueValidationArguments<E> extends ValidationArguments {
     constraints: UniqueValidationConstraints<E>;

package/validators/is-unique.validator.js

@@ -23,25 +23,36 @@ exports.IsUnique = IsUnique;
 const class_validator_1 = require("class-validator");
 const nestjs_i18n_1 = require("nestjs-i18n");
 const common_1 = require("@nestjs/common");
-const transactional_1 = require("@nestjs-cls/transactional");
+const transaction_1 = require("@nest-omni/transaction");
 let IsUniqueValidator = class IsUniqueValidator {
-    constructor(transactionHost) {
-        this.transactionHost = transactionHost;
-    }
+    constructor() { }
+    /**
+     * 解析 Entity 引用，支持多种形式：
+     * 1. Entity 类直接引用
+     * 2. 延迟函数 () => Entity
+     * 3. 字符串名称 "EntityName"
+     * 4. undefined (从属性名自动推断)
+     */
     resolveEntity(entityRef, propertyName, object) {
+        // 1. 如果是字符串，直接返回（TypeORM 支持字符串）
         if (typeof entityRef === 'string') {
             return entityRef;
         }
+        // 2. 如果是函数，需要区分延迟函数和 Entity 类
         if (typeof entityRef === 'function') {
+            // 2.1 箭头函数没有 prototype，是延迟函数
             if (!entityRef.prototype) {
                 const resolved = entityRef();
                 if (resolved)
                     return resolved;
             }
             else {
+                // 2.2 有 prototype，是 Entity 类或普通构造函数
+                // 直接返回
                 return entityRef;
             }
         }
+        // 3. 如果是 undefined，尝试从属性名推断 Entity
         if (!entityRef) {
             const inferredEntityName = this.inferEntityNameFromProperty(propertyName);
             if (inferredEntityName) {
@@ -58,6 +69,10 @@ let IsUniqueValidator = class IsUniqueValidator {
             `2. String reference: @IsUnique(["EntityName", ...])\n` +
             `3. Break the circular dependency`);
     }
+    /**
+     * 从属性名推断 Entity 名称
+     * 例如：appId -> App, userId -> User
+     */
     inferEntityNameFromProperty(propertyName) {
         const name = propertyName.replace(/(Id|Ids|Key|Code)$/, '');
         if (!name)
@@ -67,39 +82,66 @@ let IsUniqueValidator = class IsUniqueValidator {
     }
     validate(value, args) {
         return __awaiter(this, void 0, void 0, function* () {
-            const [entityRef, findCondition] = args.constraints;
+            const [entityRef, findCondition, options] = args.constraints;
+            // 解析 Entity 引用
             const entityClass = this.resolveEntity(entityRef, args.property, args.object);
-            const repository = this.transactionHost.tx.getRepository(entityClass);
+            // 获取数据源（支持多数据源）
+            const dataSourceName = (options === null || options === void 0 ? void 0 : options.dataSource) || 'default';
+            const dataSource = (0, transaction_1.getDataSource)(dataSourceName);
+            const repository = dataSource.getRepository(entityClass);
             args.value = value;
             let exists;
             const defCon = findCondition(args);
-            const pkCols = repository.metadata
-                .primaryColumns.map((column) => column.propertyName);
-            const isNew = pkCols.some((pk) => args.object[pk]);
-            if (!isNew) {
-                exists =
-                    (yield repository
-                        .count({ where: defCon })) < 1;
+            // 获取用于判断是否为新建的字段
+            // 优先级：手动配置的 uniqueKeys > 实体主键
+            let pkCols;
+            if ((options === null || options === void 0 ? void 0 : options.uniqueKeys) && options.uniqueKeys.length > 0) {
+                // 1. 使用手动指定的字段
+                pkCols = options.uniqueKeys;
+            }
+            else {
+                // 2. 使用实体的主键
+                pkCols = repository.metadata.primaryColumns.map((column) => column.propertyName);
+            }
+            // 如果没有主键也没有 uniqueKeys，使用简化逻辑
+            // 查询条件本身表示唯一性，只要存在记录就不允许
+            if (pkCols.length === 0) {
+                const count = yield repository.count({ where: defCon });
+                exists = count < 1;
+                return exists;
+            }
+            // 修复：检查是否为新建记录
+            // 如果所有 uniqueKeys/主键都没有值（null/undefined），则为新建
+            const isNew = !pkCols.some((pk) => {
+                const pkValue = args.object[pk];
+                return pkValue !== null && pkValue !== undefined && pkValue !== '';
+            });
+            if (isNew) {
+                // 新建场景：简单检查是否存在相同值的记录
+                exists = (yield repository.count({ where: defCon })) < 1;
             }
             else {
+                // 更新场景：需要排除当前记录（通过主键对比）
                 const entities = yield repository
                     .createQueryBuilder()
                     .where(defCon)
-                    .select(pkCols)
                     .limit(2)
-                    .execute();
+                    .getMany();
                 const entityCount = entities.length;
                 if (entityCount === 1) {
+                    // 只有一条记录，检查是否是当前记录本身
                     const entity = entities[0];
                     const oldPk = {};
                     const newPk = {};
-                    pkCols.map((pk) => {
+                    pkCols.forEach((pk) => {
                         oldPk[pk] = entity[pk];
                         newPk[pk] = args.object[pk];
                     });
+                    // 如果主键相同，说明是自己，允许（唯一）
                     exists = JSON.stringify(oldPk) === JSON.stringify(newPk);
                 }
                 else {
+                    // 0条或多条记录
                     exists = entityCount < 1;
                 }
             }
@@ -114,7 +156,7 @@ exports.IsUniqueValidator = IsUniqueValidator;
 exports.IsUniqueValidator = IsUniqueValidator = __decorate([
     (0, common_1.Injectable)(),
     (0, class_validator_1.ValidatorConstraint)({ name: 'isUnique', async: true }),
-    __metadata("design:paramtypes", [transactional_1.TransactionHost])
+    __metadata("design:paramtypes", [])
 ], IsUniqueValidator);
 function IsUnique(constraints, validationOptions) {
     return function (object, propertyName) {

package/validators/skip-empty.validator.d.ts

@@ -1 +1,6 @@
+/**
+ * When the value is emtpy, validation is skipped
+ * @param field
+ * @constructor
+ */
 export declare function SkipEmpty(field?: string): <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/validators/skip-empty.validator.js

@@ -5,6 +5,11 @@ const common_1 = require("@nestjs/common");
 const swagger_1 = require("@nestjs/swagger");
 const class_validator_1 = require("class-validator");
 const lodash_1 = require("lodash");
+/**
+ * When the value is emtpy, validation is skipped
+ * @param field
+ * @constructor
+ */
 function SkipEmpty(field) {
     return (0, common_1.applyDecorators)((0, swagger_1.ApiProperty)({ required: false }), (0, class_validator_1.ValidateIf)((obj, value) => {
         if (field) {

package/vault/interfaces/vault-options.interface.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Vault 认证选项
+ */
 export interface VaultAuthOptions {
     token?: string;
     roleId?: string;
@@ -5,6 +8,9 @@ export interface VaultAuthOptions {
     k8sRole?: string;
     k8sServiceAccountToken?: string;
 }
+/**
+ * Vault 配置选项
+ */
 export interface VaultOptions {
     endpoint: string;
     auth: VaultAuthOptions;
@@ -16,6 +22,9 @@ export interface VaultOptions {
     hotReloadInterval?: number;
     failOnError?: boolean;
 }
+/**
+ * Vault 配置
+ */
 export interface VaultConfig {
     enabled: boolean;
     options?: VaultOptions;

package/vault/vault-config.loader.d.ts

@@ -1,13 +1,43 @@
+/**
+ * Vault 配置加载器
+ * 负责在应用启动时从 Vault 加载配置并注入到 process.env
+ * 配置优先级: base.env < 环境.env < Vault
+ */
 export declare class VaultConfigLoader {
     private static readonly logger;
     private static vaultClient;
     private static hotReloadTimer;
+    /**
+     * 从环境变量构建 Vault 配置
+     */
     private static buildVaultOptions;
+    /**
+     * 初始化 Vault 客户端并进行认证
+     */
     private static initializeVaultClient;
+    /**
+     * 从 Vault 读取指定路径的配置
+     */
     private static readSecrets;
+    /**
+     * 加载 Vault 配置并注入到 process.env
+     * 配置优先级: base.env < 环境.env < Vault（Vault 会覆盖之前的配置）
+     */
     static loadVaultConfig(): Promise<void>;
+    /**
+     * 启动配置热更新
+     */
     private static startHotReload;
+    /**
+     * 停止热更新
+     */
     static stopHotReload(): void;
+    /**
+     * 获取 Vault 客户端（用于运行时动态读取）
+     */
     static getVaultClient(): any;
+    /**
+     * 检查 Vault 是否已连接
+     */
     static isConnected(): boolean;
 }