id-scanner-lib 1.6.7 → 2.0.0

package/src/core/config.ts

@@ -1,37 +1,23 @@
 /**
- * @file 配置管理器
- * @description 提供全局配置管理功能
+ * @file 配置管理器 + Scanner 配置
+ * @description 提供全局配置管理功能 + Scanner v2.0 配置接口
  * @module core/config
  */
 
-/**
- * 配置管理器
- * 负责存储和管理应用程序的配置
- */
+// ============================================================
+// 原有 ConfigManager（保持向后兼容）
+// ============================================================
+
 export class ConfigManager {
-  /** 单例实例 */
   private static instance: ConfigManager;
-  
-  /** 配置存储 */
   private config: Record<string, any> = {};
-  
-  /** 配置变更回调 */
   private changeCallbacks: Map<string, Array<(value: any, oldValue: any) => void>> = new Map();
-  
-  /** 初始化状态 */
   private initialized = false;
-  
-  /**
-   * 私有构造函数
-   */
+
   private constructor() {
-    // 设置默认配置
     this._resetDefaults();
   }
-  
-  /**
-   * 获取单例实例
-   */
+
   public static getInstance(): ConfigManager {
     if (!ConfigManager.instance) {
       ConfigManager.instance = new ConfigManager();
@@ -39,285 +25,145 @@ export class ConfigManager {
     return ConfigManager.instance;
   }
 
-  /**
-   * 重置单例实例（主要用于测试）
-   */
   public static resetInstance(): void {
     ConfigManager.instance = undefined as any;
   }
 
-  /**
-   * 重置为默认配置
-   */
   private _resetDefaults(): void {
     this.config = {
       debug: false,
       logLevel: 'info',
-      camera: {
-        resolution: {
-          width: 1280,
-          height: 720
-        },
-        frameRate: 30,
-        facingMode: 'environment'
+      modelPath: '/models',
+      maxRetries: 3,
+      retryDelay: 1000,
+      detectionInterval: 100,
+      face: {
+        enabled: true,
+        confidenceThreshold: 0.5,
+        maxFaces: 10,
+      },
+      idCard: {
+        enabled: false,
+      },
+      qr: {
+        enabled: false,
       },
-      performance: {
-        useCache: true
-      }
     };
     this.initialized = true;
   }
-  
-  /**
-   * 获取配置值
-   * @param key 配置键，支持点号分隔的路径
-   * @param defaultValue 默认值
-   */
-  get<T = any>(key: string, defaultValue?: T): T {
-    const value = this.getNestedValue(this.config, key);
-    return (value !== undefined) ? value : (defaultValue as T);
-  }
-  
-  /**
-   * 设置配置值
-   * @param key 配置键，支持点号分隔的路径
-   * @param value 配置值
-   */
-  set<T = any>(key: string, value: T): void {
-    const oldValue = this.get(key);
-    
-    // 如果值相同，不做任何事
-    if (oldValue === value) {
-      return;
+
+  public get<T = any>(key: string, defaultValue?: T): T {
+    const keys = key.split('.');
+    let value: any = this.config;
+    for (const k of keys) {
+      value = value?.[k];
     }
-    
-    this.setNestedValue(this.config, key, value);
-    
-    // 触发变更回调
-    this.triggerChangeCallbacks(key, value, oldValue);
+    return (value !== undefined ? value : defaultValue) as T;
   }
-  
-  /**
-   * 批量更新配置
-   * @param config 配置对象
-   */
-  updateConfig(config: Record<string, any>): void {
-    Object.entries(config).forEach(([key, value]) => {
-      this.set(key, value);
-    });
-  }
-  
-  /**
-   * 重置为默认配置
-   */
-  reset(): void {
-    const oldConfig = { ...this.config };
-    
-    // 使用私有 reset 方法重建默认配置
-    this.config = {
-      debug: false,
-      logLevel: 'info',
-      camera: {
-        resolution: {
-          width: 1280,
-          height: 720
-        },
-        frameRate: 30,
-        facingMode: 'environment'
-      },
-      performance: {
-        useCache: true
-      }
-    };
-    
-    // 触发所有回调
-    Object.keys(oldConfig).forEach(key => {
-      this.triggerChangeCallbacks(key, this.get(key), oldConfig[key]);
-    });
+
+  public set(key: string, value: any): void {
+    const keys = key.split('.');
+    let target: any = this.config;
+    for (let i = 0; i < keys.length - 1; i++) {
+      if (!target[keys[i]]) target[keys[i]] = {};
+      target = target[keys[i]];
+    }
+    const oldValue = target[keys[keys.length - 1]];
+    target[keys[keys.length - 1]] = value;
+    const callbacks = this.changeCallbacks.get(key);
+    if (callbacks) {
+      callbacks.forEach(cb => cb(value, oldValue));
+    }
   }
-  
-  /**
-   * 注册配置变更回调
-   * @param key 配置键
-   * @param callback 回调函数
-   */
-  onConfigChange<T = any>(key: string, callback: (value: T, oldValue: T) => void): void {
+
+  public onChange(key: string, callback: (value: any, oldValue: any) => void): void {
     if (!this.changeCallbacks.has(key)) {
       this.changeCallbacks.set(key, []);
     }
-    
     this.changeCallbacks.get(key)!.push(callback);
   }
-  
-  /**
-   * 移除配置变更回调
-   * @param key 配置键
-   * @param callback 特定回调函数，如不提供则移除所有
-   */
-  offConfigChange<T = any>(key: string, callback?: (value: T, oldValue: T) => void): void {
-    if (!this.changeCallbacks.has(key)) {
-      return;
-    }
-    
-    if (callback) {
-      // 移除特定回调
-      const callbacks = this.changeCallbacks.get(key)!;
-      const index = callbacks.indexOf(callback as any);
-      if (index !== -1) {
-        callbacks.splice(index, 1);
-      }
-      
-      // 如果没有回调，删除键
-      if (callbacks.length === 0) {
-        this.changeCallbacks.delete(key);
-      }
-    } else {
-      // 移除所有回调
-      this.changeCallbacks.delete(key);
-    }
-  }
-  
-  /**
-   * 获取嵌套值
-   * @param obj 对象
-   * @param path 路径
-   */
-  private getNestedValue(obj: Record<string, any>, path: string): any {
-    // 处理根路径
-    if (!path) {
-      return obj;
-    }
-    
-    // 处理嵌套路径
-    const parts = path.split('.');
-    let current = obj;
-    
-    for (const part of parts) {
-      if (current === undefined || current === null) {
-        return undefined;
-      }
-      
-      current = current[part];
-    }
-    
-    return current;
-  }
-  
-  /**
-   * 设置嵌套值
-   * @param obj 对象
-   * @param path 路径
-   * @param value 值
-   */
-  private setNestedValue(obj: Record<string, any>, path: string, value: any): void {
-    // 处理根路径
-    if (!path) {
-      return;
-    }
-    
-    // 处理嵌套路径
-    const parts = path.split('.');
-    let current = obj;
-    
-    // 遍历路径，直到倒数第二部分
-    for (let i = 0; i < parts.length - 1; i++) {
-      const part = parts[i];
-      
-      // 如果不存在，创建新对象
-      if (current[part] === undefined || current[part] === null || typeof current[part] !== 'object') {
-        current[part] = {};
-      }
-      
-      current = current[part];
-    }
-    
-    // 设置最终值
-    current[parts[parts.length - 1]] = value;
+
+  /** @deprecated Use onChange instead */
+  public onConfigChange<T = any>(key: string, callback: (value: T, oldValue: T) => void): void {
+    this.onChange(key, callback);
   }
-  
-  /**
-   * 触发变更回调
-   * @param key 配置键
-   * @param value 新值
-   * @param oldValue 旧值
-   */
-  private triggerChangeCallbacks(key: string, value: any, oldValue: any): void {
-    // 触发特定键的回调
-    if (this.changeCallbacks.has(key)) {
-      const callbacks = this.changeCallbacks.get(key)!;
-      callbacks.forEach(callback => {
-        try {
-          callback(value, oldValue);
-        } catch (error) {
-          console.error(`Error in config change callback for key ${key}:`, error);
-        }
-      });
-    }
-    
-    // 触发父路径的回调
-    const parts = key.split('.');
-    while (parts.length > 1) {
-      parts.pop();
-      const parentKey = parts.join('.');
-      
-      if (this.changeCallbacks.has(parentKey)) {
-        const parentValue = this.get(parentKey);
-        this.changeCallbacks.get(parentKey)!.forEach(callback => {
-          try {
-            callback(parentValue, parentValue);
-          } catch (error) {
-            console.error(`Error in config change callback for parent key ${parentKey}:`, error);
-          }
-        });
-      }
+
+  public removeChangeCallback(key: string, callback: (value: any, oldValue: any) => void): void {
+    const callbacks = this.changeCallbacks.get(key);
+    if (callbacks) {
+      const index = callbacks.indexOf(callback);
+      if (index > -1) callbacks.splice(index, 1);
     }
   }
 
-  /**
-   * 检查模块是否启用
-   * @param moduleName 模块名称
-   */
-  public isModuleEnabled(moduleName: string): boolean {
-    const key = `modules.${moduleName}.enabled`;
-    return this.get(key) ?? false;
+  public reset(): void {
+    this.config = {};
+    this._resetDefaults();
   }
 }
 
+// ============================================================
+// Scanner v2.0 配置接口
+// ============================================================
+
 /**
- * 全局配置接口
+ * Scanner configuration interface (v2.0)
  */
-export interface GlobalConfig {
-  /** 版本号 */
-  version: string;
-  /** 调试模式 */
-  debug: boolean;
-  /** 日志级别 */
-  logLevel: string;
-  /** 摄像头配置 */
-  camera: {
-    resolution: { width: number; height: number };
-    frameRate: number;
-    facingMode: string;
+export interface ScannerConfig {
+  debug?: boolean;
+  modules?: {
+    face?: boolean;
+    faceComparator?: boolean;
+    faceLiveness?: boolean;
+    idCard?: boolean;
+    qr?: boolean;
   };
-  /** 性能配置 */
-  performance: {
-    useCache: boolean;
+  performance?: {
+    maxCanvasWidth?: number;
+    useWorker?: boolean;
+    lazyLoad?: boolean;
   };
-  /** 模块配置 */
-  modules: {
-    face: { enabled: boolean };
-    idcard: { enabled: boolean };
-    qrcode: { enabled: boolean };
+}
+
+/**
+ * Scanner module interface
+ * All modules must implement this interface
+ */
+export interface ScannerModule {
+  initialize(): Promise<void>;
+  destroy(): Promise<void>;
+}
+
+/**
+ * Image source types
+ */
+export type ImageSource = HTMLVideoElement | HTMLCanvasElement | HTMLImageElement | ImageData | string;
+
+/**
+ * Face detection result
+ */
+export interface Face {
+  box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  confidence: number;
+  keypoints?: {
+    leftEye?: { x: number; y: number };
+    rightEye?: { x: number; y: number };
+    nose?: { x: number; y: number };
+    leftMouth?: { x: number; y: number };
+    rightMouth?: { x: number; y: number };
   };
-} 
+  embedding?: number[];
+}
 
 /**
- * 模块配置接口
- * 定义所有模块共享的基础配置属性
+ * Module configuration
  */
 export interface ModuleConfig {
-  /** 是否启用该模块 */
-  enabled: boolean;
-  /** 其他模块特定配置 */
+  enabled?: boolean;
   [key: string]: any;
-} 
+}

package/src/core/errors.ts

@@ -1,174 +1,125 @@
 /**
- * @file 错误处理模块
- * @description 定义ID-Scanner-Lib的错误类层次结构
+ * @file Scanner Errors
+ * @description Error classes for Scanner
  * @module core/errors
  */
 
 /**
- * ID-Scanner-Lib 基础错误类
- * 所有库特定错误的基类
+ * Scanner specific error
  */
-export class IDScannerError extends Error {
-  /** 错误代码 */
+export class ScannerError extends Error {
+  /**
+   * Error code
+   */
   public code: string;
-  /** 错误原因 */
-  public cause?: Error;
+  /**
+   * Module that threw the error
+   */
+  public module?: string;
 
   /**
-   * 构造函数
-   * @param message 错误消息
-   * @param options 错误选项
+   * Create a ScannerError
+   * @param message Error message
+   * @param code Error code
+   * @param module Module name
    */
-  constructor(message: string, options?: { code?: string; cause?: Error }) {
+  constructor(message: string, code: string, module?: string) {
     super(message);
-    
-    // 设置错误名称
-    this.name = this.constructor.name;
-    
-    // 设置错误代码
-    this.code = options?.code || 'UNKNOWN_ERROR';
-    
-    // 设置错误原因
-    this.cause = options?.cause;
-    
-    // 捕获堆栈 (Node.js专有，浏览器环境忽略)
-    if (typeof (Error as any).captureStackTrace === 'function') {
-      (Error as any).captureStackTrace(this, this.constructor);
-    }
+    this.name = 'ScannerError';
+    this.code = code;
+    this.module = module;
   }
 }
 
 /**
- * 初始化错误
- * 当库初始化失败时抛出
+ * Camera access error
  */
-export class InitializationError extends IDScannerError {
-  constructor(message: string, details?: string) {
-    super(`初始化失败: ${message}${details ? ` (${details})` : ''}`, { code: 'INIT_FAILED' });
-    this.name = 'InitializationError';
+export class CameraAccessError extends Error {
+  constructor(message = 'Camera access denied') {
+    super(message);
+    this.name = 'CameraAccessError';
   }
 }
 
 /**
- * 设备错误
- * 当访问硬件设备(如摄像头)失败时抛出
+ * Device error
  */
-export class DeviceError extends IDScannerError {
-  constructor(message: string) {
-    super(`设备错误: ${message}`, { code: 'DEVICE_ERROR' });
+export class DeviceError extends Error {
+  constructor(message = 'Device error') {
+    super(message);
     this.name = 'DeviceError';
   }
 }
 
 /**
- * 摄像头访问错误
- * 当无法访问或启动摄像头时抛出
+ * Resource load error
  */
-export class CameraAccessError extends IDScannerError {
-  constructor(message: string, options?: { code?: string; cause?: Error }) {
-    super(`摄像头访问失败: ${message}`, {
-      code: options?.code || 'CAMERA_ACCESS_FAILED',
-      cause: options?.cause
-    });
-    this.name = 'CameraAccessError';
+export class ResourceLoadError extends Error {
+  public readonly id?: string;
+  constructor(message = 'Failed to load resource', id?: string) {
+    super(message);
+    this.name = 'ResourceLoadError';
+    this.id = id;
   }
 }
 
 /**
- * 人脸检测错误
- * 当人脸检测过程失败时抛出
+ * Face detection error
  */
-export class FaceDetectionError extends IDScannerError {
-  constructor(message: string) {
-    super(`人脸检测失败: ${message}`, { code: 'FACE_DETECTION_FAILED' });
+export class FaceDetectionError extends Error {
+  constructor(message = 'Face detection failed') {
+    super(message);
     this.name = 'FaceDetectionError';
   }
 }
 
 /**
- * 人脸比对错误
- * 当人脸比对过程失败时抛出
+ * Face comparison error
  */
-export class FaceComparisonError extends IDScannerError {
-  constructor(message: string) {
-    super(`人脸比对失败: ${message}`, { code: 'FACE_COMPARISON_FAILED' });
+export class FaceComparisonError extends Error {
+  constructor(message = 'Face comparison failed') {
+    super(message);
     this.name = 'FaceComparisonError';
   }
 }
 
 /**
- * 活体检测错误
- * 当活体检测过程失败时抛出
- */
-export class LivenessDetectionError extends IDScannerError {
-  constructor(message: string) {
-    super(`活体检测失败: ${message}`, { code: 'LIVENESS_DETECTION_FAILED' });
-    this.name = 'LivenessDetectionError';
-  }
-}
-
-/**
- * OCR识别错误
- * 当OCR文字识别失败时抛出
+ * Initialization error
  */
-export class OCRProcessingError extends IDScannerError {
-  constructor(message: string) {
-    super(`OCR处理失败: ${message}`, { code: 'OCR_PROCESSING_FAILED' });
-    this.name = 'OCRProcessingError';
-  }
-}
-
-/**
- * 二维码扫描错误
- * 当二维码扫描失败时抛出
- */
-export class QRScanError extends IDScannerError {
-  constructor(message: string) {
-    super(`二维码扫描失败: ${message}`, { code: 'QR_SCAN_FAILED' });
-    this.name = 'QRScanError';
-  }
-}
-
-/**
- * 身份证检测错误
- * 当身份证检测失败时抛出
- */
-export class IDCardDetectionError extends IDScannerError {
-  constructor(message: string) {
-    super(`身份证检测失败: ${message}`, { code: 'ID_CARD_DETECTION_FAILED' });
-    this.name = 'IDCardDetectionError';
+export class InitializationError extends Error {
+  constructor(message = 'Initialization failed') {
+    super(message);
+    this.name = 'InitializationError';
   }
 }
 
 /**
- * 资源加载错误
- * 当无法加载必要资源(如模型)时抛出
+ * Liveness detection error
  */
-export class ResourceLoadError extends IDScannerError {
-  constructor(resource: string, reason: string) {
-    super(`无法加载资源 ${resource}: ${reason}`, { code: 'RESOURCE_LOAD_FAILED' });
-    this.name = 'ResourceLoadError';
+export class LivenessDetectionError extends Error {
+  constructor(message = 'Liveness detection failed') {
+    super(message);
+    this.name = 'LivenessDetectionError';
   }
 }
 
 /**
- * 参数错误
- * 当提供的参数无效时抛出
+ * Error codes for Scanner
  */
-export class InvalidArgumentError extends IDScannerError {
-  constructor(paramName: string, reason: string) {
-    super(`无效的参数 ${paramName}: ${reason}`, { code: 'INVALID_ARGUMENT' });
-    this.name = 'InvalidArgumentError';
-  }
-}
+export const ErrorCodes = {
+  /** Scanner not initialized */
+  NOT_INITIALIZED: 'SCANNER_001',
+  /** Module not found */
+  MODULE_NOT_FOUND: 'SCANNER_002',
+  /** Detection failed */
+  DETECTION_FAILED: 'SCANNER_003',
+  /** Camera access denied */
+  CAMERA_ACCESS_DENIED: 'CAMERA_001',
+  /** Camera not available */
+  CAMERA_NOT_AVAILABLE: 'CAMERA_002',
+} as const;
 
 /**
- * 不支持错误
- * 当尝试使用不支持的功能或当前环境无法使用的功能时抛出
+ * Type for error codes
  */
-export class NotSupportedError extends IDScannerError {
-  constructor(feature: string) {
-    super(`不支持的功能: ${feature}`, { code: 'NOT_SUPPORTED' });
-    this.name = 'NotSupportedError';
-  }
-} 
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];