@vlian/infrastructure 0.9.10

package/dist/esm/managers/DictionaryManager/DictionaryManager.js

@@ -0,0 +1,718 @@
+/**
+ * DictionaryManager - 字典管理器
+ * 
+ * 提供字典数据管理能力
+ * 完全泛型化，字典项类型由用户定义
+ * 基于 @vlian/framework 的 Storage、StateManager 和 AppEventBus
+ */ function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+import { DictionaryError, DictionaryErrorCode, DictionaryEventType } from "./types";
+import { DEFAULT_OPTIONS, PRODUCTION_OVERRIDES } from "./constants";
+// 导入 Core 层
+import { CacheManager, ConcurrencyController, IndexManager, DiffCalculator, DictionaryValidator, StateManagerWrapper, DictionaryDataManager } from "./core";
+// 导入 Runtime 层
+import { DictionaryFormatter } from "./runtime/DictionaryFormatter";
+import { DictionaryBatchProcessor } from "./runtime/DictionaryBatchProcessor";
+// 导入 Observability 层
+import { EventManager, PerformanceMonitor, LoggingManager, MonitoringManager } from "./observability";
+// 导入公共模块
+import { StorageManager, EnvironmentDetector, ErrorHandler } from "./modules";
+/**
+ * DictionaryManager 类
+ */ export class DictionaryManager {
+    /**
+   * 初始化所有模块
+   */ initializeModules() {
+        // 初始化公共模块
+        if (this.options.storage || this.options.enablePersistentCache) {
+            this.storageManager = new StorageManager({
+                storage: this.options.storage || {
+                    strategy: 'local'
+                },
+                environment: this.environment,
+                logger: this.options.logger
+            });
+        }
+        this.errorHandler = new ErrorHandler({
+            logger: this.options.logger,
+            monitoring: this.options.monitoring,
+            sanitizeErrors: this.isProduction
+        });
+        // 初始化 Observability 层
+        this.loggingManager = new LoggingManager({
+            logger: this.options.logger,
+            enableLogging: this.options.enableLogging,
+            context: {
+                instanceId: this.instanceId
+            }
+        });
+        this.monitoringManager = new MonitoringManager({
+            monitoring: this.options.monitoring,
+            enableMonitoring: this.options.enableMonitoring
+        });
+        this.performanceMonitor = new PerformanceMonitor({
+            monitoring: this.options.monitoring,
+            enableDetailedMetrics: this.options.enableDetailedMetrics
+        });
+        this.eventManager = new EventManager({
+            eventBus: this.options.eventBus,
+            eventNamespace: this.options.eventNamespace,
+            enableEvents: this.options.enableEvents,
+            logger: this.options.enableLogging ? {
+                debug: (...args)=>this.loggingManager.debug(...args),
+                error: (...args)=>this.loggingManager.error(...args)
+            } : undefined,
+            monitoring: this.options.enableMonitoring ? {
+                trackEvent: (name, props)=>this.monitoringManager.trackEvent(name, props),
+                captureError: (error, ctx)=>this.monitoringManager.captureError(error, ctx)
+            } : undefined
+        });
+        // 初始化 Core 层
+        this.stateManager = this.options.stateManager ? new StateManagerWrapper({
+            stateManager: this.options.stateManager,
+            logger: this.options.logger
+        }) : undefined;
+        this.cacheManager = new CacheManager({
+            defaultTTL: this.options.cacheExpiry
+        });
+        this.concurrencyController = new ConcurrencyController({
+            strategy: this.options.concurrencyStrategy,
+            maxQueueSize: this.options.maxQueueSize,
+            operationTimeout: this.options.operationTimeout
+        });
+        this.indexManager = new IndexManager({
+            indexKeyField: this.options.indexKeyField,
+            keyField: this.options.keyField,
+            enableIndex: this.options.enableIndex
+        });
+        this.diffCalculator = new DiffCalculator({
+            itemComparator: this.options.itemComparator,
+            itemChangeDetector: this.options.itemChangeDetector,
+            indexKeyField: this.options.indexKeyField || this.options.keyField
+        });
+        this.validator = new DictionaryValidator({
+            validator: this.options.dictionaryValidator
+        });
+        this.dataManager = new DictionaryDataManager({
+            cacheManager: this.cacheManager,
+            stateManager: this.stateManager,
+            storageManager: this.storageManager,
+            indexManager: this.indexManager,
+            validator: this.validator,
+            dictionaryFetcher: this.options.dictionaryFetcher,
+            dictionariesFetcher: this.options.dictionariesFetcher,
+            dictionaryConfig: this.options.dictionaryConfig,
+            enableCache: this.options.enableCache,
+            enablePersistentCache: this.options.enablePersistentCache,
+            cacheExpiry: this.options.cacheExpiry,
+            dictionaryKeyPrefix: this.options.dictionaryKeyPrefix
+        });
+        // 初始化 Runtime 层
+        this.formatter = new DictionaryFormatter({
+            formatter: this.options.formatter,
+            keyField: this.options.keyField,
+            labelField: this.options.labelField
+        });
+    }
+    /**
+   * 初始化时自动预加载
+   */ async initializeAutoPreload() {
+        if (this.options.preloadDictionaries && this.options.preloadDictionaries.length > 0) {
+            // 异步预加载，不阻塞初始化
+            this.preloadDictionaries(this.options.preloadDictionaries).catch((error)=>{
+                this.errorHandler.handleError(error, {
+                    operation: 'autoPreload'
+                });
+            });
+        }
+    }
+    /**
+   * 配置验证
+   */ validateConfig(options) {
+        const errors = [];
+        const warnings = [];
+        // 验证数据来源
+        if (!options.dictionaryFetcher && !options.dictionariesFetcher && !options.dictionaryConfig) {
+            warnings.push('No dictionary data source provided. DictionaryManager will return empty arrays.');
+        }
+        // 验证索引配置
+        if (options.enableIndex && !options.indexKeyField && !options.keyField) {
+            errors.push('keyField is required when enableIndex is true');
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    /**
+   * 获取字典数据（异步）
+   */ async getDictionary(code, options) {
+        const startTime = Date.now();
+        const operationType = 'getDictionary';
+        return this.concurrencyController.execute(async ()=>{
+            try {
+                const items = await this.dataManager.getDictionary(code, {
+                    force: options?.force,
+                    usePersistentCache: options?.usePersistentCache
+                });
+                // 记录性能指标
+                const duration = Date.now() - startTime;
+                this.performanceMonitor.recordMetric(operationType, duration, {
+                    code
+                });
+                // 触发事件
+                this.eventManager.emitEvent(DictionaryEventType.DICTIONARY_LOADED, {
+                    code,
+                    items,
+                    timestamp: Date.now()
+                });
+                return items;
+            } catch (error) {
+                const duration = Date.now() - startTime;
+                this.performanceMonitor.recordMetric(operationType, duration, {
+                    code,
+                    error: true
+                });
+                throw this.errorHandler.handleError(error, {
+                    operation: operationType,
+                    code
+                });
+            }
+        }, operationType);
+    }
+    /**
+   * 获取字典数据（同步，仅读取缓存）
+   */ getDictionarySync(code, _options) {
+        const items = this.dataManager.getDictionarySync(code);
+        return items || [];
+    }
+    /**
+   * 获取字典值（异步）
+   */ async getDictionaryValue(code, key, options) {
+        const items = await this.getDictionary(code, options);
+        const item = items.find((item)=>{
+            const itemKey = item[this.options.keyField];
+            return String(itemKey) === String(key);
+        });
+        if (!item) {
+            return null;
+        }
+        return this.formatter.getLabel(item);
+    }
+    /**
+   * 获取字典值（同步，仅读取缓存）
+   */ getDictionaryValueSync(code, key, _options) {
+        const items = this.getDictionarySync(code);
+        const item = items.find((item)=>{
+            const itemKey = item[this.options.keyField];
+            return String(itemKey) === String(key);
+        });
+        if (!item) {
+            return null;
+        }
+        return this.formatter.getLabel(item);
+    }
+    /**
+   * 格式化字典值
+   */ async formatDictionary(code, value, options) {
+        const items = await this.getDictionary(code);
+        const item = items.find((item)=>{
+            const itemKey = item[this.options.keyField];
+            return String(itemKey) === String(value);
+        });
+        return this.formatter.format(item || null, value, options?.defaultValue);
+    }
+    /**
+   * 批量获取字典数据（异步）
+   */ async getDictionaries(codes, options) {
+        const startTime = Date.now();
+        const operationType = 'batch';
+        return this.concurrencyController.execute(async ()=>{
+            try {
+                const dictionaries = await this.dataManager.getDictionaries(codes, {
+                    force: options?.force,
+                    usePersistentCache: options?.usePersistentCache
+                });
+                const duration = Date.now() - startTime;
+                this.performanceMonitor.recordMetric(operationType, duration, {
+                    count: codes.length
+                });
+                return dictionaries;
+            } catch (error) {
+                const duration = Date.now() - startTime;
+                this.performanceMonitor.recordMetric(operationType, duration, {
+                    count: codes.length,
+                    error: true
+                });
+                throw this.errorHandler.handleError(error, {
+                    operation: operationType,
+                    codes
+                });
+            }
+        }, operationType);
+    }
+    /**
+   * 批量获取字典数据（同步，仅读取缓存）
+   */ getDictionariesSync(codes, _options) {
+        return this.dataManager.getDictionariesSync(codes);
+    }
+    /**
+   * 批量获取字典值（异步）
+   */ async getDictionaryValues(queries, options) {
+        return DictionaryBatchProcessor.getDictionaryValues(queries, async (code, key)=>{
+            const items = await this.getDictionary(code, options);
+            return items.find((item)=>{
+                const itemKey = item[this.options.keyField];
+                return String(itemKey) === String(key);
+            }) || null;
+        }, (item)=>this.formatter.getLabel(item));
+    }
+    /**
+   * 批量获取字典值（同步，仅读取缓存）
+   */ getDictionaryValuesSync(queries, _options) {
+        return DictionaryBatchProcessor.getDictionaryValuesSync(queries, (code, key)=>{
+            const items = this.getDictionarySync(code);
+            return items.find((item)=>{
+                const itemKey = item[this.options.keyField];
+                return String(itemKey) === String(key);
+            }) || null;
+        }, (item)=>this.formatter.getLabel(item));
+    }
+    /**
+   * 获取可用字典列表
+   */ async getAvailableDictionaries() {
+        const codes = [];
+        // 从缓存获取
+        codes.push(...this.dataManager.getAvailableDictionariesSync());
+        // 从配置获取
+        if (this.options.dictionaryConfig) {
+            for (const code of Object.keys(this.options.dictionaryConfig)){
+                if (!codes.includes(code)) {
+                    codes.push(code);
+                }
+            }
+        }
+        return codes;
+    }
+    /**
+   * 获取可用字典列表（同步，仅读取缓存）
+   */ getAvailableDictionariesSync() {
+        return this.dataManager.getAvailableDictionariesSync();
+    }
+    /**
+   * 刷新字典数据
+   */ async refreshDictionary(code, force = true) {
+        const startTime = Date.now();
+        const operationType = 'refresh';
+        return this.concurrencyController.execute(async ()=>{
+            try {
+                if (code) {
+                    await this.dataManager.getDictionary(code, {
+                        force,
+                        usePersistentCache: false
+                    });
+                } else {
+                    // 刷新所有字典
+                    const codes = await this.getAvailableDictionaries();
+                    await this.dataManager.getDictionaries(codes, {
+                        force,
+                        usePersistentCache: false
+                    });
+                }
+                const duration = Date.now() - startTime;
+                this.performanceMonitor.recordMetric(operationType, duration, {
+                    code: code || 'all'
+                });
+                this.eventManager.emitEvent(DictionaryEventType.DICTIONARY_REFRESHED, {
+                    code: code || 'all',
+                    timestamp: Date.now()
+                });
+            } catch (error) {
+                const duration = Date.now() - startTime;
+                this.performanceMonitor.recordMetric(operationType, duration, {
+                    code: code || 'all',
+                    error: true
+                });
+                throw this.errorHandler.handleError(error, {
+                    operation: operationType,
+                    code
+                });
+            }
+        }, operationType);
+    }
+    /**
+   * 刷新多个字典数据
+   */ async refreshDictionaries(codes, force = true) {
+        await this.dataManager.getDictionaries(codes, {
+            force,
+            usePersistentCache: false
+        });
+        this.eventManager.emitEvent(DictionaryEventType.DICTIONARY_REFRESHED, {
+            codes,
+            timestamp: Date.now()
+        });
+    }
+    /**
+   * 清除字典缓存
+   */ async clearCache(code) {
+        await this.dataManager.clearCache(code);
+        this.eventManager.emitEvent(DictionaryEventType.DICTIONARY_CACHE_CLEARED, {
+            code: code || 'all',
+            timestamp: Date.now()
+        });
+    }
+    /**
+   * 预加载字典数据
+   */ async preloadDictionaries(codes) {
+        const startTime = Date.now();
+        const operationType = 'preload';
+        return this.concurrencyController.execute(async ()=>{
+            try {
+                // 更新预加载状态
+                for (const code of codes){
+                    this.preloadStatus.set(code, {
+                        code,
+                        status: 'loading'
+                    });
+                }
+                await this.dataManager.getDictionaries(codes, {
+                    force: false,
+                    usePersistentCache: this.options.enablePersistentCache
+                });
+                // 更新预加载状态
+                for (const code of codes){
+                    this.preloadStatus.set(code, {
+                        code,
+                        status: 'loaded'
+                    });
+                }
+                const duration = Date.now() - startTime;
+                this.performanceMonitor.recordMetric(operationType, duration, {
+                    count: codes.length
+                });
+                this.eventManager.emitEvent(DictionaryEventType.DICTIONARY_PRELOADED, {
+                    codes,
+                    timestamp: Date.now()
+                });
+            } catch (error) {
+                // 更新预加载状态
+                for (const code of codes){
+                    this.preloadStatus.set(code, {
+                        code,
+                        status: 'error',
+                        error: error instanceof Error ? error : new Error(String(error))
+                    });
+                }
+                const duration = Date.now() - startTime;
+                this.performanceMonitor.recordMetric(operationType, duration, {
+                    count: codes.length,
+                    error: true
+                });
+                throw this.errorHandler.handleError(error, {
+                    operation: operationType,
+                    codes
+                });
+            }
+        }, operationType);
+    }
+    /**
+   * 获取预加载状态
+   */ async getPreloadStatus(code) {
+        if (code) {
+            return this.preloadStatus.get(code) || {
+                code,
+                status: 'pending'
+            };
+        }
+        return Object.fromEntries(this.preloadStatus);
+    }
+    /**
+   * 获取字典项索引（通过索引键）
+   */ async getDictionaryItemByIndex(code, indexKey, options) {
+        await this.dataManager.getDictionary(code, options);
+        const dictionaryData = this.dataManager.getDictionaryData(code);
+        if (!dictionaryData || !dictionaryData.index) {
+            return null;
+        }
+        return this.indexManager.getItemByIndex(dictionaryData.index, indexKey);
+    }
+    /**
+   * 获取字典项索引（同步，仅读取缓存）
+   */ getDictionaryItemByIndexSync(code, indexKey, _options) {
+        const dictionaryData = this.dataManager.getDictionaryData(code);
+        if (!dictionaryData || !dictionaryData.index) {
+            return null;
+        }
+        return this.indexManager.getItemByIndex(dictionaryData.index, indexKey);
+    }
+    /**
+   * 获取字典索引 Map
+   */ async getDictionaryIndex(code, options) {
+        await this.getDictionary(code, options);
+        const dictionaryData = this.dataManager.getDictionaryData(code);
+        return dictionaryData?.index || new Map();
+    }
+    /**
+   * 获取字典索引 Map（同步，仅读取缓存）
+   */ getDictionaryIndexSync(code, _options) {
+        const dictionaryData = this.dataManager.getDictionaryData(code);
+        return dictionaryData?.index || new Map();
+    }
+    /**
+   * 计算字典差异
+   */ async calculateDictionaryDiff(code, newItems, oldItems) {
+        const old = oldItems || this.dataManager.getDictionarySync(code) || [];
+        return this.diffCalculator.calculateDiff(newItems, old);
+    }
+    /**
+   * 应用字典差异（Patch）
+   */ async applyDictionaryPatch(code, diff) {
+        const currentItems = this.dataManager.getDictionarySync(code) || [];
+        // 应用差异
+        const newItems = [
+            ...currentItems
+        ];
+        // 移除删除的项
+        for (const removed of diff.removed){
+            const index = newItems.findIndex((item)=>{
+                const itemKey = item[this.options.keyField];
+                const removedKey = removed[this.options.keyField];
+                return String(itemKey) === String(removedKey);
+            });
+            if (index !== -1) {
+                newItems.splice(index, 1);
+            }
+        }
+        // 添加新增的项
+        newItems.push(...diff.added);
+        // 更新变更的项
+        for (const { before, after } of diff.changed){
+            const index = newItems.findIndex((item)=>{
+                const itemKey = item[this.options.keyField];
+                const beforeKey = before[this.options.keyField];
+                return String(itemKey) === String(beforeKey);
+            });
+            if (index !== -1) {
+                newItems[index] = after;
+            }
+        }
+        // 保存新数据
+        const { oldItems } = await this.dataManager.setDictionary(code, newItems, this.options.enablePersistentCache);
+        // 触发更新事件（包含 Diff 信息）
+        this.eventManager.emitEvent(DictionaryEventType.DICTIONARY_UPDATED, {
+            code,
+            items: newItems,
+            previousItems: oldItems,
+            diff,
+            timestamp: Date.now()
+        });
+    }
+    /**
+   * 订阅事件
+   */ on(event, listener, options) {
+        return this.eventManager.on(event, listener, options);
+    }
+    /**
+   * 取消订阅
+   */ off(event, listener) {
+        this.eventManager.off(event, listener);
+    }
+    /**
+   * 一次性订阅
+   */ once(event, listener) {
+        return this.eventManager.once(event, listener);
+    }
+    /**
+   * 健康检查
+   */ async healthCheck() {
+        const checks = {};
+        // 检查存储
+        if (this.storageManager) {
+            try {
+                await this.storageManager.get('__health_check__');
+                checks.storage = {
+                    healthy: true
+                };
+            } catch (error) {
+                checks.storage = {
+                    healthy: false,
+                    error: error instanceof Error ? error.message : String(error)
+                };
+            }
+        }
+        // 检查状态管理
+        if (this.stateManager) {
+            try {
+                this.stateManager.get('__health_check__');
+                checks.stateManager = {
+                    healthy: true
+                };
+            } catch (error) {
+                checks.stateManager = {
+                    healthy: false,
+                    error: error instanceof Error ? error.message : String(error)
+                };
+            }
+        }
+        // 检查事件总线
+        if (this.options.enableEvents) {
+            try {
+                this.eventManager.emitEvent(DictionaryEventType.DICTIONARY_LOADED, {
+                    code: '__health_check__',
+                    items: [],
+                    timestamp: Date.now()
+                });
+                checks.eventBus = {
+                    healthy: true
+                };
+            } catch (error) {
+                checks.eventBus = {
+                    healthy: false,
+                    error: error instanceof Error ? error.message : String(error)
+                };
+            }
+        }
+        const healthy = Object.values(checks).every((check)=>check?.healthy !== false);
+        return {
+            healthy,
+            checks
+        };
+    }
+    /**
+   * 获取性能指标
+   */ getPerformanceMetrics() {
+        return this.performanceMonitor.getMetrics();
+    }
+    /**
+   * 清除性能指标
+   */ clearPerformanceMetrics() {
+        this.performanceMonitor.clearMetrics();
+    }
+    /**
+   * 获取缓存统计信息
+   */ getCacheStatistics() {
+        const stats = this.cacheManager.getStatistics();
+        return {
+            size: stats.size,
+            hits: stats.hits,
+            misses: stats.misses,
+            hitRate: stats.hitRate,
+            keys: stats.keys
+        };
+    }
+    /**
+   * 重置缓存统计信息
+   */ resetCacheStatistics() {
+        this.cacheManager.resetStatistics();
+    }
+    /**
+   * 销毁实例（清理资源）
+   */ destroy() {
+        // 清理事件订阅
+        this.eventManager.cleanup();
+        // 清理缓存
+        this.cacheManager.clear();
+        // 清理预加载状态
+        this.preloadStatus.clear();
+        // 清理并发控制器
+        this.concurrencyController.clear();
+    }
+    /**
+   * 构造函数
+   */ constructor(options){
+        _define_property(this, "options", void 0);
+        _define_property(this, "environment", void 0);
+        _define_property(this, "isProduction", void 0);
+        _define_property(this, "instanceId", void 0);
+        // 模块实例
+        _define_property(this, "storageManager", void 0);
+        _define_property(this, "stateManager", void 0);
+        _define_property(this, "errorHandler", void 0);
+        // Core 层
+        _define_property(this, "cacheManager", void 0);
+        _define_property(this, "concurrencyController", void 0);
+        _define_property(this, "indexManager", void 0);
+        _define_property(this, "diffCalculator", void 0);
+        _define_property(this, "validator", void 0);
+        _define_property(this, "dataManager", void 0);
+        // Runtime 层
+        _define_property(this, "formatter", void 0);
+        // Observability 层
+        _define_property(this, "loggingManager", void 0);
+        _define_property(this, "monitoringManager", void 0);
+        _define_property(this, "performanceMonitor", void 0);
+        _define_property(this, "eventManager", void 0);
+        // 预加载状态
+        _define_property(this, "preloadStatus", new Map());
+        // 检测环境
+        this.environment = EnvironmentDetector.detectEnvironment();
+        this.isProduction = EnvironmentDetector.checkIsProduction();
+        this.instanceId = options.instanceId || `dict_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        // 合并默认配置
+        this.options = {
+            ...DEFAULT_OPTIONS,
+            ...options,
+            storage: options.storage,
+            stateManager: options.stateManager,
+            eventBus: options.eventBus,
+            logger: options.logger,
+            monitoring: options.monitoring,
+            dictionaryFetcher: options.dictionaryFetcher,
+            dictionariesFetcher: options.dictionariesFetcher,
+            dictionaryConfig: options.dictionaryConfig,
+            dictionaryValidator: options.dictionaryValidator,
+            formatter: options.formatter,
+            instanceId: this.instanceId
+        };
+        // 应用生产环境覆盖
+        if (this.isProduction) {
+            this.options = {
+                ...this.options,
+                ...PRODUCTION_OVERRIDES
+            };
+        }
+        // 配置验证
+        if (this.options.validateConfig !== false) {
+            const validation = this.validateConfig(this.options);
+            if (!validation.valid) {
+                const errorMsg = `Configuration validation failed: ${validation.errors.join(', ')}`;
+                if (this.options.devMode) {
+                    throw new DictionaryError(`${errorMsg}\nWarnings: ${validation.warnings.join(', ')}`, DictionaryErrorCode.CONFIG_ERROR);
+                } else {
+                    throw new DictionaryError(errorMsg, DictionaryErrorCode.CONFIG_ERROR);
+                }
+            }
+            if (validation.warnings.length > 0 && this.options.devMode) {
+                validation.warnings.forEach((warning)=>{
+                    this.options.logger?.warn(`Config warning: ${warning}`);
+                });
+            }
+        }
+        // 初始化模块
+        this.initializeModules();
+        // 开发模式日志
+        if (this.options.devMode && this.options.enableLogging) {
+            this.loggingManager?.debug('DictionaryManager initialized', {
+                environment: this.environment,
+                isProduction: this.isProduction,
+                instanceId: this.instanceId
+            });
+        }
+        // 初始化时自动预加载
+        this.initializeAutoPreload();
+    }
+}
+
+//# sourceMappingURL=DictionaryManager.js.map