id-scanner-lib 1.3.3 → 1.6.2

package/src/core/logger.ts

@@ -0,0 +1,549 @@
+/**
+ * @file 日志系统
+ * @description 提供统一的日志记录与管理功能
+ * @module core/logger
+ */
+
+import { ConfigManager } from './config';
+
+/**
+ * 日志级别枚举
+ */
+export enum LogLevel {
+  DEBUG = 'debug',
+  INFO = 'info',
+  WARN = 'warn',
+  ERROR = 'error'
+}
+
+/**
+ * 日志条目接口
+ */
+export interface LogEntry {
+  /** 日志级别 */
+  level: LogLevel;
+  /** 日志标签 */
+  tag: string;
+  /** 日志消息 */
+  message: string;
+  /** 时间戳 */
+  timestamp: number;
+  /** 额外数据 */
+  data?: any;
+  /** 错误 */
+  error?: Error;
+}
+
+/**
+ * 日志处理器接口
+ */
+export interface LogHandler {
+  /**
+   * 处理日志条目
+   * @param entry 日志条目
+   */
+  handle(entry: LogEntry): void;
+}
+
+/**
+ * 控制台日志处理器
+ * 将日志输出到浏览器控制台
+ */
+export class ConsoleLogHandler implements LogHandler {
+  /**
+   * 处理日志条目
+   * @param entry 日志条目
+   */
+  handle(entry: LogEntry): void {
+    const timestamp = new Date(entry.timestamp).toISOString();
+    const prefix = `[${timestamp}] [${entry.level.toUpperCase()}] [${entry.tag}]`;
+    
+    switch (entry.level) {
+      case LogLevel.DEBUG:
+        console.debug(prefix, entry.message, entry.error || '');
+        break;
+      case LogLevel.INFO:
+        console.info(prefix, entry.message, entry.error || '');
+        break;
+      case LogLevel.WARN:
+        console.warn(prefix, entry.message, entry.error || '');
+        break;
+      case LogLevel.ERROR:
+        console.error(prefix, entry.message, entry.error || '');
+        break;
+      default:
+        // 输出什么也不做
+    }
+  }
+}
+
+/**
+ * 内存日志处理器
+ * 将日志保存在内存中，用于后续分析或显示
+ */
+export class MemoryLogHandler implements LogHandler {
+  /** 日志条目数组 */
+  private entries: LogEntry[] = [];
+  /** 最大日志条目数 */
+  private maxEntries: number;
+  
+  /**
+   * 构造函数
+   * @param maxEntries 最大日志条目数，默认为1000
+   */
+  constructor(maxEntries: number = 1000) {
+    this.maxEntries = maxEntries;
+  }
+  
+  /**
+   * 处理日志条目
+   * @param entry 日志条目
+   */
+  handle(entry: LogEntry): void {
+    this.entries.push(entry);
+    
+    // 如果超过最大条目数，移除最老的
+    if (this.entries.length > this.maxEntries) {
+      this.entries.shift();
+    }
+  }
+  
+  /**
+   * 获取所有日志条目
+   */
+  getEntries(): LogEntry[] {
+    return [...this.entries];
+  }
+  
+  /**
+   * 根据级别过滤日志条目
+   * @param level 日志级别
+   */
+  getEntriesByLevel(level: LogLevel): LogEntry[] {
+    return this.entries.filter(entry => entry.level === level);
+  }
+  
+  /**
+   * 根据标签过滤日志条目
+   * @param tag 日志标签
+   */
+  getEntriesByTag(tag: string): LogEntry[] {
+    return this.entries.filter(entry => entry.tag === tag);
+  }
+  
+  /**
+   * 清空日志
+   */
+  clear(): void {
+    this.entries = [];
+  }
+}
+
+/**
+ * 远程日志处理器
+ * 将日志发送到远程服务器
+ */
+export class RemoteLogHandler implements LogHandler {
+  /** 远程服务器URL */
+  private endpoint: string;
+  /** 批量发送的队列 */
+  private queue: LogEntry[] = [];
+  /** 最大队列长度 */
+  private maxQueueSize: number;
+  /** 发送间隔(毫秒) */
+  private flushInterval: number;
+  /** 定时发送的计时器ID */
+  private timerId: number | null = null;
+  
+  /**
+   * 构造函数
+   * @param endpoint 远程服务器URL
+   * @param maxQueueSize 最大队列长度，默认为100
+   * @param flushInterval 发送间隔(毫秒)，默认为5000
+   */
+  constructor(endpoint: string, maxQueueSize: number = 100, flushInterval: number = 5000) {
+    this.endpoint = endpoint;
+    this.maxQueueSize = maxQueueSize;
+    this.flushInterval = flushInterval;
+    
+    // 设置定时发送
+    this.startTimer();
+    
+    // 页面卸载前尝试发送剩余日志
+    window.addEventListener('beforeunload', () => {
+      this.flush();
+    });
+  }
+  
+  /**
+   * 处理日志条目
+   * @param entry 日志条目
+   */
+  handle(entry: LogEntry): void {
+    // 只处理INFO以上级别的日志
+    if (entry.level >= LogLevel.INFO) {
+      this.queue.push(entry);
+      
+      // 如果队列满了，立即发送
+      if (this.queue.length >= this.maxQueueSize) {
+        this.flush();
+      }
+    }
+  }
+  
+  /**
+   * 发送队列中的日志
+   */
+  flush(): void {
+    if (this.queue.length === 0) return;
+    
+    const entriesToSend = [...this.queue];
+    this.queue = [];
+    
+    try {
+      fetch(this.endpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(entriesToSend),
+        // 不等待响应，避免阻塞
+        keepalive: true
+      }).catch(err => {
+        console.error('Failed to send logs to remote server:', err);
+        // 失败时把日志放回队列，但防止无限增长
+        if (this.queue.length < this.maxQueueSize) {
+          this.queue = [...entriesToSend.slice(0, this.maxQueueSize - this.queue.length), ...this.queue];
+        }
+      });
+    } catch (error) {
+      console.error('Error sending logs:', error);
+    }
+  }
+  
+  /**
+   * 开始定时发送
+   */
+  startTimer(): void {
+    if (this.timerId !== null) return;
+    
+    this.timerId = window.setInterval(() => {
+      this.flush();
+    }, this.flushInterval);
+  }
+  
+  /**
+   * 停止定时发送
+   */
+  stopTimer(): void {
+    if (this.timerId !== null) {
+      window.clearInterval(this.timerId);
+      this.timerId = null;
+    }
+  }
+}
+
+/**
+ * 日志管理类
+ * 中央日志管理器，提供统一的日志记录接口
+ */
+export class Logger {
+  /** 单例实例 */
+  private static instance: Logger;
+  /** 配置管理器 */
+  private config: ConfigManager;
+  /** 日志处理器 */
+  private handlers: LogHandler[] = [];
+  /** 默认标签 */
+  private defaultTag: string = 'IDScanner';
+  /** 日志级别 */
+  private logLevel: LogLevel = LogLevel.INFO;
+  
+  /**
+   * 私有构造函数，防止直接实例化
+   */
+  private constructor() {
+    this.config = ConfigManager.getInstance();
+    
+    // 默认添加控制台处理器
+    this.addHandler(new ConsoleLogHandler());
+    
+    // 监听配置变化
+    this.config.onConfigChange('logLevel', (level: LogLevel) => {
+      this.debug('Logger', `Log level changed to ${level}`);
+    });
+  }
+  
+  /**
+   * 获取单例实例
+   */
+  public static getInstance(): Logger {
+    if (!Logger.instance) {
+      Logger.instance = new Logger();
+    }
+    return Logger.instance;
+  }
+  
+  /**
+   * 添加日志处理器
+   * @param handler 日志处理器
+   */
+  addHandler(handler: LogHandler): void {
+    this.handlers.push(handler);
+  }
+  
+  /**
+   * 移除日志处理器
+   * @param handler 要移除的处理器
+   */
+  removeHandler(handler: LogHandler): void {
+    const index = this.handlers.indexOf(handler);
+    if (index !== -1) {
+      this.handlers.splice(index, 1);
+    }
+  }
+  
+  /**
+   * 移除所有处理器
+   */
+  clearHandlers(): void {
+    this.handlers = [];
+  }
+  
+  /**
+   * 设置默认标签
+   * @param tag 默认标签
+   */
+  setDefaultTag(tag: string): void {
+    this.defaultTag = tag;
+  }
+  
+  /**
+   * 记录调试级别日志
+   * @param tag 标签
+   * @param message 消息
+   * @param error 错误
+   */
+  debug(tag: string, message: string, error?: Error): void {
+    this.log(LogLevel.DEBUG, tag, message, error);
+  }
+  
+  /**
+   * 记录信息级别日志
+   * @param tag 标签
+   * @param message 消息
+   * @param error 错误
+   */
+  info(tag: string, message: string, error?: Error): void {
+    this.log(LogLevel.INFO, tag, message, error);
+  }
+  
+  /**
+   * 记录警告级别日志
+   * @param tag 标签
+   * @param message 消息
+   * @param error 错误
+   */
+  warn(tag: string, message: string, error?: Error): void {
+    this.log(LogLevel.WARN, tag, message, error);
+  }
+  
+  /**
+   * 记录错误级别日志
+   * @param tag 标签
+   * @param message 消息
+   * @param error 错误
+   */
+  error(tag: string, message: string, error?: Error): void {
+    this.log(LogLevel.ERROR, tag, message, error);
+  }
+  
+  /**
+   * 创建标记了特定标签的日志记录器
+   * @param tag 标签
+   */
+  getTaggedLogger(tag: string): TaggedLogger {
+    return new TaggedLogger(this, tag);
+  }
+  
+  /**
+   * 记录日志
+   * @param level 日志级别
+   * @param tag 标签
+   * @param message 消息
+   * @param error 错误
+   */
+  private log(level: LogLevel, tag: string, message: string, error?: Error): void {
+    // 检查日志级别
+    const levelValue = this.getLevelValue(level);
+    const currentLevelValue = this.getLevelValue(this.logLevel);
+    
+    if (levelValue < currentLevelValue) {
+      return;
+    }
+    
+    // 创建日志条目
+    const entry: LogEntry = {
+      timestamp: Date.now(),
+      level: level,
+      tag: tag || this.defaultTag,
+      message,
+      error
+    };
+    
+    // 分发到所有处理程序
+    for (const handler of this.handlers) {
+      try {
+        handler.handle(entry);
+      } catch (handlerError) {
+        console.error(`[Logger] 处理程序错误:`, handlerError);
+      }
+    }
+    
+    // 如果没有处理程序，使用控制台
+    if (this.handlers.length === 0) {
+      this.consoleOutput(entry);
+    }
+  }
+
+  /**
+   * 控制台输出
+   * @param entry 日志条目
+   */
+  private consoleOutput(entry: LogEntry): void {
+    const timestamp = new Date(entry.timestamp).toISOString();
+    const prefix = `[${timestamp}] [${entry.level.toUpperCase()}] [${entry.tag}]`;
+    
+    switch (entry.level) {
+      case LogLevel.DEBUG:
+        console.debug(`${prefix} ${entry.message}`, entry.error || '');
+        break;
+      case LogLevel.INFO:
+        console.info(`${prefix} ${entry.message}`, entry.error || '');
+        break;
+      case LogLevel.WARN:
+        console.warn(`${prefix} ${entry.message}`, entry.error || '');
+        break;
+      case LogLevel.ERROR:
+        console.error(`${prefix} ${entry.message}`, entry.error || '');
+        break;
+    }
+  }
+
+  /**
+   * 获取日志级别值
+   * @param level 日志级别
+   */
+  private getLevelValue(level: LogLevel): number {
+    switch (level) {
+      case LogLevel.DEBUG:
+        return 0;
+      case LogLevel.INFO:
+        return 1;
+      case LogLevel.WARN:
+        return 2;
+      case LogLevel.ERROR:
+        return 3;
+      default:
+        return 1; // 默认INFO级别
+    }
+  }
+
+  /**
+   * 设置日志级别
+   * @param level 日志级别
+   */
+  public setLevel(level: LogLevel | string): void {
+    if (typeof level === 'string') {
+      switch (level) {
+        case 'debug':
+          this.logLevel = LogLevel.DEBUG;
+          break;
+        case 'info':
+          this.logLevel = LogLevel.INFO;
+          break;
+        case 'warn':
+          this.logLevel = LogLevel.WARN;
+          break;
+        case 'error':
+          this.logLevel = LogLevel.ERROR;
+          break;
+        default:
+          this.logLevel = LogLevel.INFO;
+      }
+    } else {
+      this.logLevel = level;
+    }
+    
+    this.debug('Logger', `日志级别已设置为 ${this.logLevel}`);
+  }
+
+  /**
+   * 获取当前日志级别
+   * @returns 当前日志级别
+   */
+  public getLevel(): LogLevel {
+    return this.logLevel;
+  }
+}
+
+/**
+ * 带标签的日志记录器
+ * 提供特定标签的简易日志接口
+ */
+export class TaggedLogger {
+  /** 所属的主日志记录器 */
+  private logger: Logger;
+  /** 标签 */
+  private tag: string;
+  
+  /**
+   * 构造函数
+   * @param logger 所属的主日志记录器
+   * @param tag 标签
+   */
+  constructor(logger: Logger, tag: string) {
+    this.logger = logger;
+    this.tag = tag;
+  }
+  
+  /**
+   * 记录调试级别日志
+   * @param message 消息
+   * @param error 错误
+   */
+  debug(message: string, error?: Error): void {
+    this.logger.debug(this.tag, message, error);
+  }
+  
+  /**
+   * 记录信息级别日志
+   * @param message 消息
+   * @param error 错误
+   */
+  info(message: string, error?: Error): void {
+    this.logger.info(this.tag, message, error);
+  }
+  
+  /**
+   * 记录警告级别日志
+   * @param message 消息
+   * @param error 错误
+   */
+  warn(message: string, error?: Error): void {
+    this.logger.warn(this.tag, message, error);
+  }
+  
+  /**
+   * 记录错误级别日志
+   * @param message 消息
+   * @param error 错误
+   */
+  error(message: string, error?: Error): void {
+    this.logger.error(this.tag, message, error);
+  }
+}
+
+/**
+ * 日志级别枚举
+ */

package/src/core/module-manager.ts

@@ -0,0 +1,163 @@
+/**
+ * @file 模块管理器
+ * @description 统一管理库的各功能模块，提供模块的注册、初始化和卸载功能
+ * @module core/module-manager
+ */
+
+import { Logger } from './logger';
+import { EventEmitter } from './event-emitter';
+import { VERSION } from '../version';
+
+/**
+ * 模块接口
+ * 所有功能模块必须实现此接口
+ */
+export interface Module {
+  /** 模块名称 */
+  name: string;
+  
+  /** 模块版本 */
+  version: string;
+  
+  /** 模块是否已初始化 */
+  isInitialized: boolean;
+  
+  /** 初始化模块 */
+  initialize(): Promise<void>;
+  
+  /** 释放模块资源 */
+  dispose(): Promise<void>;
+}
+
+/**
+ * 模块配置接口
+ */
+export interface ModuleOptions {
+  /** 是否启用该模块 */
+  enabled?: boolean;
+  
+  /** 模块特定配置 */
+  [key: string]: any;
+}
+
+/**
+ * 模块管理器类
+ * 负责管理所有功能模块的生命周期
+ */
+export class ModuleManager extends EventEmitter {
+  private static instance: ModuleManager;
+  private modules: Map<string, Module> = new Map();
+  private logger: Logger;
+  private initialized = false;
+  
+  /**
+   * 获取模块管理器单例
+   */
+  public static getInstance(): ModuleManager {
+    if (!ModuleManager.instance) {
+      ModuleManager.instance = new ModuleManager();
+    }
+    return ModuleManager.instance;
+  }
+  
+  /**
+   * 私有构造函数，确保单例模式
+   */
+  private constructor() {
+    super();
+    this.logger = Logger.getInstance();
+    this.logger.debug('ModuleManager', `初始化模块管理器 v${VERSION}`);
+  }
+  
+  /**
+   * 注册模块
+   * @param module 要注册的模块
+   * @returns 模块管理器实例，支持链式调用
+   */
+  public register(module: Module): ModuleManager {
+    if (this.modules.has(module.name)) {
+      this.logger.warn('ModuleManager', `模块 "${module.name}" 已经注册，将被覆盖`);
+    }
+    
+    this.modules.set(module.name, module);
+    this.logger.debug('ModuleManager', `注册模块: ${module.name} v${module.version}`);
+    this.emit('module:registered', { name: module.name });
+    
+    return this;
+  }
+  
+  /**
+   * 获取模块
+   * @param name 模块名称
+   * @returns 模块实例
+   */
+  public getModule<T extends Module>(name: string): T | undefined {
+    return this.modules.get(name) as T | undefined;
+  }
+  
+  /**
+   * 初始化所有注册的模块
+   */
+  public async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+    
+    this.logger.debug('ModuleManager', '开始初始化所有模块...');
+    
+    for (const [name, module] of this.modules.entries()) {
+      try {
+        this.logger.debug('ModuleManager', `初始化模块: ${name}`);
+        await module.initialize();
+        this.emit('module:initialized', { name });
+        this.logger.debug('ModuleManager', `模块 ${name} 初始化完成`);
+      } catch (error) {
+        this.logger.error('ModuleManager', `模块 ${name} 初始化失败`, error instanceof Error ? error : undefined);
+        this.emit('module:error', { name, error });
+        throw new Error(`模块 ${name} 初始化失败: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    
+    this.initialized = true;
+    this.logger.debug('ModuleManager', '所有模块初始化完成');
+    this.emit('modules:initialized');
+  }
+  
+  /**
+   * 卸载所有模块并释放资源
+   */
+  public async dispose(): Promise<void> {
+    this.logger.debug('ModuleManager', '开始释放所有模块资源...');
+    
+    for (const [name, module] of this.modules.entries()) {
+      try {
+        this.logger.debug('ModuleManager', `释放模块资源: ${name}`);
+        await module.dispose();
+        this.emit('module:disposed', { name });
+      } catch (error) {
+        this.logger.error('ModuleManager', `模块 ${name} 资源释放失败`, error instanceof Error ? error : undefined);
+        this.emit('module:error', { name, error });
+      }
+    }
+    
+    this.modules.clear();
+    this.initialized = false;
+    this.logger.debug('ModuleManager', '所有模块资源已释放');
+    this.emit('modules:disposed');
+  }
+  
+  /**
+   * 获取所有已注册的模块名称
+   */
+  public getRegisteredModules(): string[] {
+    return Array.from(this.modules.keys());
+  }
+  
+  /**
+   * 检查模块是否已注册
+   * @param name 模块名称
+   */
+  public hasModule(name: string): boolean {
+    return this.modules.has(name);
+  }
+}