id-scanner-lib 1.6.7 → 2.0.0

package/src/core/logger.ts

@@ -62,19 +62,22 @@ export class ConsoleLogHandler implements LogHandler {
   handle(entry: LogEntry): void {
     const timestamp = new Date(entry.timestamp).toISOString();
     const prefix = `[${timestamp}] [${entry.level.toUpperCase()}] [${entry.tag}]`;
-    
+
+    // 优先使用 error，其次使用 data
+    const extra = entry.error || entry.data || '';
+
     switch (entry.level) {
       case LoggerLevel.DEBUG:
-        console.debug(prefix, entry.message, entry.error || '');
+        console.debug(prefix, entry.message, extra);
         break;
       case LoggerLevel.INFO:
-        console.info(prefix, entry.message, entry.error || '');
+        console.info(prefix, entry.message, extra);
         break;
       case LoggerLevel.WARN:
-        console.warn(prefix, entry.message, entry.error || '');
+        console.warn(prefix, entry.message, extra);
         break;
       case LoggerLevel.ERROR:
-        console.error(prefix, entry.message, entry.error || '');
+        console.error(prefix, entry.message, extra);
         break;
       default:
         // 输出什么也不做
@@ -158,10 +161,14 @@ export class RemoteLogHandler implements LogHandler {
   /** 发送间隔(毫秒) */
   private flushInterval: number;
   /** 定时发送的计时器ID */
-  private timerId: number | null = null;
+  private timerId: ReturnType<typeof setInterval> | null = null;
   /** 是否在浏览器环境 */
   private readonly isBrowser: boolean;
-  
+  /** 最大连续失败次数，超过则丢弃日志 */
+  private readonly maxConsecutiveFailures: number;
+  /** 当前连续失败计数 */
+  private consecutiveFailures: number = 0;
+
   /**
    * 构造函数
    * @param endpoint 远程服务器URL
@@ -173,10 +180,11 @@ export class RemoteLogHandler implements LogHandler {
     this.maxQueueSize = maxQueueSize;
     this.flushInterval = flushInterval;
     this.isBrowser = typeof window !== 'undefined' && typeof window.addEventListener === 'function';
-    
+    this.maxConsecutiveFailures = 10;
+
     // 设置定时发送
     this.startTimer();
-    
+
     // 页面卸载前尝试发送剩余日志
     if (this.isBrowser) {
       window.addEventListener('beforeunload', () => {
@@ -184,7 +192,7 @@ export class RemoteLogHandler implements LogHandler {
       });
     }
   }
-  
+
   /**
    * 处理日志条目
    * @param entry 日志条目
@@ -193,86 +201,96 @@ export class RemoteLogHandler implements LogHandler {
     // 只处理INFO以上级别的日志
     if (entry.level >= LoggerLevel.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 = [];
-    
-    // 防止在 fetch 失败时无限重试
-    const sendCount = (this as any)._sendCount || 0;
-    (this as any)._sendCount = sendCount + 1;
-    
-    // 如果发送次数过多，停止发送以防止无限循环
-    if (sendCount > 10) {
-      console.warn('RemoteLogHandler: Too many failed sends, stopping. Clear queue.');
+
+    // 如果连续失败次数过多，停止发送以防止无限循环
+    if (this.consecutiveFailures >= this.maxConsecutiveFailures) {
+      console.warn('RemoteLogHandler: Too many consecutive failures, stopping. Clear queue.');
       this.queue = [];
-      (this as any)._sendCount = 0;
+      this.consecutiveFailures = 0;
       return;
     }
-    
-    try {
-      fetch(this.endpoint, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json'
-        },
-        body: JSON.stringify(entriesToSend),
-        keepalive: true
-      }).catch((err: Error) => {
-        console.error('Failed to send logs to remote server:', err);
-        
-        // 防止无限重试 - 如果失败次数过多，丢弃日志
-        if ((this as any)._sendCount > 10) {
-          console.warn('RemoteLogHandler: Max retry exceeded, discarding logs');
-          this.queue = [];  // 清空队列，避免内存泄漏
-          (this as any)._sendCount = 0;
-          return;
-        }
-        
-        // 失败时把日志放回队列，但防止无限增长
-        if (this.queue.length < this.maxQueueSize) {
-          const maxReturn = Math.min(entriesToSend.length, this.maxQueueSize - this.queue.length);
-          const returnedEntries = entriesToSend.slice(0, maxReturn);
-          this.queue = [...returnedEntries, ...this.queue];
-        }
-        
-        (this as any)._sendCount = 0;
-      });
-    } catch (error) {
-      console.error('Error sending logs:', error);
-    }
+
+    const entriesToSend = [...this.queue];
+    this.queue = [];
+
+    this.sendLogEntries(entriesToSend);
   }
-  
+
+  /**
+   * 发送日志条目到远程服务器
+   * @param entries 日志条目数组
+   */
+  private sendLogEntries(entries: LogEntry[]): void {
+    if (entries.length === 0) return;
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 10000); // 10s 超时
+
+    fetch(this.endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(entries),
+      keepalive: true,
+      signal: controller.signal
+    }).then(() => {
+      clearTimeout(timeoutId);
+      this.consecutiveFailures = 0; // 发送成功，重置失败计数
+    }).catch((err: Error) => {
+      clearTimeout(timeoutId);
+      console.error('Failed to send logs to remote server:', err);
+
+      this.consecutiveFailures++;
+
+      // 如果失败次数过多，丢弃日志防止内存泄漏
+      if (this.consecutiveFailures >= this.maxConsecutiveFailures) {
+        console.warn('RemoteLogHandler: Max consecutive failures exceeded, discarding logs');
+        this.queue = [];
+        this.consecutiveFailures = 0;
+        return;
+      }
+
+      // 失败时把日志放回队列，但防止无限增长
+      const maxReturn = Math.min(entries.length, this.maxQueueSize - this.queue.length);
+      if (maxReturn > 0) {
+        const returnedEntries = entries.slice(0, maxReturn);
+        this.queue = [...returnedEntries, ...this.queue];
+      }
+    });
+  }
+
   /**
    * 开始定时发送
    */
   startTimer(): void {
     if (!this.isBrowser) return;
     if (this.timerId !== null) return;
-    
-    this.timerId = window.setInterval(() => {
+
+    this.timerId = setInterval(() => {
       this.flush();
     }, this.flushInterval);
   }
-  
+
   /**
    * 停止定时发送
    */
   stopTimer(): void {
     if (this.timerId !== null) {
-      window.clearInterval(this.timerId);
+      clearInterval(this.timerId);
       this.timerId = null;
     }
   }
@@ -364,40 +382,56 @@ export class Logger {
    * 记录调试级别日志
    * @param tag 标签
    * @param message 消息
-   * @param error 错误
+   * @param errorOrData 错误对象或结构化数据
    */
-  debug(tag: string, message: string, error?: Error): void {
-    this.log(LoggerLevel.DEBUG, tag, message, error);
+  debug(tag: string, message: string, errorOrData?: Error | object): void {
+    if (errorOrData instanceof Error) {
+      this.log(LoggerLevel.DEBUG, tag, message, errorOrData);
+    } else {
+      this.logWithData(LoggerLevel.DEBUG, tag, message, errorOrData);
+    }
   }
-  
+
   /**
    * 记录信息级别日志
    * @param tag 标签
    * @param message 消息
-   * @param error 错误
+   * @param errorOrData 错误对象或结构化数据
    */
-  info(tag: string, message: string, error?: Error): void {
-    this.log(LoggerLevel.INFO, tag, message, error);
+  info(tag: string, message: string, errorOrData?: Error | object): void {
+    if (errorOrData instanceof Error) {
+      this.log(LoggerLevel.INFO, tag, message, errorOrData);
+    } else {
+      this.logWithData(LoggerLevel.INFO, tag, message, errorOrData);
+    }
   }
-  
+
   /**
    * 记录警告级别日志
    * @param tag 标签
    * @param message 消息
-   * @param error 错误
+   * @param errorOrData 错误对象或结构化数据
    */
-  warn(tag: string, message: string, error?: Error): void {
-    this.log(LoggerLevel.WARN, tag, message, error);
+  warn(tag: string, message: string, errorOrData?: Error | object): void {
+    if (errorOrData instanceof Error) {
+      this.log(LoggerLevel.WARN, tag, message, errorOrData);
+    } else {
+      this.logWithData(LoggerLevel.WARN, tag, message, errorOrData);
+    }
   }
-  
+
   /**
    * 记录错误级别日志
    * @param tag 标签
    * @param message 消息
-   * @param error 错误
+   * @param errorOrData 错误对象或结构化数据
    */
-  error(tag: string, message: string, error?: Error): void {
-    this.log(LoggerLevel.ERROR, tag, message, error);
+  error(tag: string, message: string, errorOrData?: Error | object): void {
+    if (errorOrData instanceof Error) {
+      this.log(LoggerLevel.ERROR, tag, message, errorOrData);
+    } else {
+      this.logWithData(LoggerLevel.ERROR, tag, message, errorOrData);
+    }
   }
   
   /**
@@ -448,6 +482,46 @@ export class Logger {
     }
   }
 
+  /**
+   * 记录日志（支持结构化数据）
+   * @param level 日志级别
+   * @param tag 标签
+   * @param message 消息
+   * @param data 结构化数据
+   */
+  private logWithData(level: LoggerLevel, tag: string, message: string, data?: object): 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,
+      data
+    };
+
+    // 分发到所有处理程序
+    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 日志条目
@@ -455,19 +529,22 @@ export class Logger {
   private consoleOutput(entry: LogEntry): void {
     const timestamp = new Date(entry.timestamp).toISOString();
     const prefix = `[${timestamp}] [${entry.level.toUpperCase()}] [${entry.tag}]`;
-    
+
+    // 构造日志内容：错误对象或数据对象
+    const extra = entry.error || entry.data || '';
+
     switch (entry.level) {
       case LoggerLevel.DEBUG:
-        console.debug(`${prefix} ${entry.message}`, entry.error || '');
+        console.debug(`${prefix} ${entry.message}`, extra);
         break;
       case LoggerLevel.INFO:
-        console.info(`${prefix} ${entry.message}`, entry.error || '');
+        console.info(`${prefix} ${entry.message}`, extra);
         break;
       case LoggerLevel.WARN:
-        console.warn(`${prefix} ${entry.message}`, entry.error || '');
+        console.warn(`${prefix} ${entry.message}`, extra);
         break;
       case LoggerLevel.ERROR:
-        console.error(`${prefix} ${entry.message}`, entry.error || '');
+        console.error(`${prefix} ${entry.message}`, extra);
         break;
     }
   }

package/src/core/resource-manager.ts

@@ -10,6 +10,156 @@ import { ResourceLoadError } from './errors';
 import { EventEmitter } from './event-emitter';
 import { Result } from './result';
 
+/**
+ * 模型分片信息
+ */
+export interface ModelShard {
+  name: string;        // e.g. 'face-detector'
+  version: string;     // e.g. '1.0.0'
+  url: string;         // 完整 URL
+  size: number;        // bytes
+  hash?: string;       // 完整性校验
+}
+
+/**
+ * 模型缓存信息
+ */
+export interface ModelCacheInfo {
+  name: string;
+  version: string;
+  cachedAt: number;
+  size: number;
+}
+
+/**
+ * IndexedDB 模型缓存管理器
+ * 提供分片模型的持久化缓存功能
+ */
+export class ModelCacheManager {
+  private _dbName = 'id-scanner-lib-models';
+  private _storeName = 'model-cache';
+  private _db: IDBDatabase | null = null;
+
+  /**
+   * 初始化缓存管理器（打开 IndexedDB）
+   */
+  async init(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this._dbName, 1);
+      request.onerror = () => reject(new Error('Failed to open IndexedDB'));
+      request.onsuccess = () => {
+        this._db = request.result;
+        resolve();
+      };
+      request.onupgradeneeded = (event) => {
+        const db = (event.target as IDBOpenDBRequest).result;
+        if (!db.objectStoreNames.contains(this._storeName)) {
+          const store = db.createObjectStore(this._storeName, { keyPath: 'key' });
+          store.createIndex('name', 'name', { unique: false });
+          store.createIndex('version', 'version', { unique: false });
+        }
+      };
+    });
+  }
+
+  /**
+   * 生成缓存键
+   */
+  private _makeKey(model: ModelShard): string {
+    return `${model.name}@${model.version}`;
+  }
+
+  /**
+   * 检查模型是否已缓存
+   */
+  async has(model: ModelShard): Promise<boolean> {
+    if (!this._db) return false;
+    return new Promise((resolve, reject) => {
+      const tx = this._db!.transaction(this._storeName, 'readonly');
+      const store = tx.objectStore(this._storeName);
+      const req = store.get(this._makeKey(model));
+      req.onsuccess = () => resolve(!!req.result);
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  /**
+   * 存储模型数据
+   */
+  async store(model: ModelShard, data: ArrayBuffer): Promise<void> {
+    if (!this._db) throw new Error('ModelCacheManager not initialized');
+    return new Promise((resolve, reject) => {
+      const tx = this._db!.transaction(this._storeName, 'readwrite');
+      const store = tx.objectStore(this._storeName);
+      const record = {
+        key: this._makeKey(model),
+        name: model.name,
+        version: model.version,
+        url: model.url,
+        size: model.size,
+        data,
+        cachedAt: Date.now(),
+      };
+      const req = store.put(record);
+      req.onsuccess = () => resolve();
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  /**
+   * 加载模型数据
+   */
+  async load(model: ModelShard): Promise<ArrayBuffer | null> {
+    if (!this._db) throw new Error('ModelCacheManager not initialized');
+    return new Promise((resolve, reject) => {
+      const tx = this._db!.transaction(this._storeName, 'readonly');
+      const store = tx.objectStore(this._storeName);
+      const req = store.get(this._makeKey(model));
+      req.onsuccess = () => resolve(req.result ? req.result.data : null);
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  /**
+   * 清除所有缓存
+   */
+  async clear(): Promise<void> {
+    if (!this._db) return;
+    return new Promise((resolve, reject) => {
+      const tx = this._db!.transaction(this._storeName, 'readwrite');
+      const store = tx.objectStore(this._storeName);
+      const req = store.clear();
+      req.onsuccess = () => resolve();
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  /**
+   * 列出已缓存模型
+   */
+  async listCached(): Promise<ModelCacheInfo[]> {
+    if (!this._db) return [];
+    return new Promise((resolve, reject) => {
+      const tx = this._db!.transaction(this._storeName, 'readonly');
+      const store = tx.objectStore(this._storeName);
+      const req = store.getAll();
+      req.onsuccess = () => {
+        const results: ModelCacheInfo[] = req.result.map((r: any) => ({
+          name: r.name,
+          version: r.version,
+          cachedAt: r.cachedAt,
+          size: r.size,
+        }));
+        resolve(results);
+      };
+      req.onerror = () => reject(req.error);
+    });
+  }
+}
+
+/** 全局模型缓存管理器实例 */
+export const modelCache = new ModelCacheManager();
+
 /**
  * 资源类型枚举
  */

package/src/core/scanner.ts

@@ -0,0 +1,109 @@
+/**
+ * @file Scanner Core Class
+ * @description Main entry point for the Scanner library
+ * @module core/scanner
+ */
+
+import { ScannerConfig, ScannerModule, ImageSource, Face } from './config';
+import { ScannerError, ErrorCodes } from './errors';
+
+/**
+ * Scanner main class
+ * Provides unified interface for all scanning operations
+ */
+export class Scanner {
+  /**
+   * Internal configuration
+   */
+  private _config: Required<ScannerConfig>;
+  /**
+   * Loaded modules
+   */
+  private _modules: Map<string, ScannerModule>;
+  /**
+   * Initialization state
+   */
+  private _initialized: boolean = false;
+
+  /**
+   * Create a new Scanner instance
+   * @param config Scanner configuration
+   */
+  constructor(config: ScannerConfig = {}) {
+    this._config = this._normalizeConfig(config);
+    this._modules = new Map();
+  }
+
+  /**
+   * Check if scanner is initialized
+   */
+  get initialized(): boolean {
+    return this._initialized;
+  }
+
+  /**
+   * Normalize configuration with defaults
+   * @param config User provided config
+   * @returns Normalized config with defaults
+   */
+  private _normalizeConfig(config: ScannerConfig): Required<ScannerConfig> {
+    return {
+      debug: config.debug ?? false,
+      modules: {
+        face: config.modules?.face ?? true,
+        faceComparator: config.modules?.faceComparator ?? false,
+        faceLiveness: config.modules?.faceLiveness ?? false,
+        idCard: config.modules?.idCard ?? false,
+        qr: config.modules?.qr ?? false,
+      },
+      performance: {
+        maxCanvasWidth: config.performance?.maxCanvasWidth ?? 1280,
+        useWorker: config.performance?.useWorker ?? true,
+        lazyLoad: config.performance?.lazyLoad ?? true,
+      },
+    };
+  }
+
+  /**
+   * Initialize the scanner and load enabled modules
+   */
+  async initialize(): Promise<void> {
+    // Immediately load face core module
+    const { FaceDetector } = await import('../modules/face/detector');
+    const detector = new FaceDetector();
+    await detector.initialize();
+    this._modules.set('face-detector', detector);
+    this._initialized = true;
+  }
+
+  /**
+   * Detect faces in an image source
+   * @param input Image source (video, canvas, image, etc.)
+   * @returns Array of detected faces
+   */
+  async detectFace(input: ImageSource): Promise<Face[]> {
+    const detector = this._modules.get('face-detector');
+    if (!detector) {
+      throw new ScannerError(
+        'Scanner not initialized. Call initialize() first.',
+        ErrorCodes.NOT_INITIALIZED
+      );
+    }
+    return (detector as any).detect(input);
+  }
+
+  /**
+   * Destroy the scanner and release all resources
+   */
+  async destroy(): Promise<void> {
+    for (const module of this._modules.values()) {
+      await module.destroy();
+    }
+    this._modules.clear();
+    this._initialized = false;
+  }
+}
+
+// Re-export types
+export { ScannerConfig, ScannerModule, ImageSource, Face } from './config';
+export { ScannerError, ErrorCodes } from './errors';

package/src/core/utils/browser.ts

@@ -0,0 +1,7 @@
+/**
+ * @file Browser Utilities
+ * @description Browser environment utility functions
+ * @module core/utils/browser
+ */
+
+export {};