id-scanner-lib 1.5.0 → 1.6.2

package/src/core/loading-state.ts

@@ -0,0 +1,156 @@
+/**
+ * @file 加载状态管理
+ * @description 提供模块加载状态跟踪功能
+ * @module core/loading-state
+ */
+
+import { EventEmitter } from './event-emitter';
+
+/**
+ * 加载状态类型
+ */
+export enum LoadingState {
+  /** 空闲 */
+  IDLE = 'idle',
+  /** 加载中 */
+  LOADING = 'loading',
+  /** 就绪 */
+  READY = 'ready',
+  /** 错误 */
+  ERROR = 'error',
+  /** 已释放 */
+  DISPOSED = 'disposed'
+}
+
+/**
+ * 加载进度信息
+ */
+export interface LoadingProgress {
+  /** 当前状态 */
+  state: LoadingState;
+  /** 已加载的模型 */
+  loadedModels: string[];
+  /** 正在加载的模型 */
+  loadingModel?: string;
+  /** 进度百分比 (0-100) */
+  progress: number;
+  /** 错误信息 */
+  error?: string;
+}
+
+/**
+ * 加载状态管理器
+ * 用于跟踪和管理模块的加载状态
+ */
+export class LoadingStateManager extends EventEmitter {
+  private state: LoadingState = LoadingState.IDLE;
+  private loadedModels: Set<string> = new Set();
+  private loadingModel?: string;
+  private totalModels: number = 0;
+  private error?: string;
+
+  /**
+   * 开始加载
+   * @param totalModels 总模型数
+   */
+  startLoading(totalModels: number): void {
+    this.totalModels = totalModels;
+    this.state = LoadingState.LOADING;
+    this.error = undefined;
+    this.emit('stateChange', this.getProgress());
+  }
+
+  /**
+   * 模型开始加载
+   * @param modelName 模型名称
+   */
+  startModelLoading(modelName: string): void {
+    this.loadingModel = modelName;
+    this.emit('progress', this.getProgress());
+  }
+
+  /**
+   * 模型加载完成
+   * @param modelName 模型名称
+   */
+  completeModelLoading(modelName: string): void {
+    this.loadedModels.add(modelName);
+    this.loadingModel = undefined;
+    this.emit('progress', this.getProgress());
+  }
+
+  /**
+   * 加载完成
+   */
+  complete(): void {
+    this.state = LoadingState.READY;
+    this.totalModels = 0;
+    this.emit('stateChange', this.getProgress());
+  }
+
+  /**
+   * 加载失败
+   * @param error 错误信息
+   */
+  fail(error: string): void {
+    this.state = LoadingState.ERROR;
+    this.error = error;
+    this.emit('error', { error, progress: this.getProgress() });
+  }
+
+  /**
+   * 释放
+   */
+  dispose(): void {
+    this.state = LoadingState.DISPOSED;
+    this.loadedModels.clear();
+    this.totalModels = 0;
+    this.error = undefined;
+    this.emit('stateChange', this.getProgress());
+  }
+
+  /**
+   * 获取当前进度
+   */
+  getProgress(): LoadingProgress {
+    const progress = this.totalModels > 0 
+      ? Math.round((this.loadedModels.size / this.totalModels) * 100) 
+      : 0;
+
+    return {
+      state: this.state,
+      loadedModels: Array.from(this.loadedModels),
+      loadingModel: this.loadingModel,
+      progress,
+      error: this.error
+    };
+  }
+
+  /**
+   * 获取当前状态
+   */
+  getState(): LoadingState {
+    return this.state;
+  }
+
+  /**
+   * 是否已就绪
+   */
+  isReady(): boolean {
+    return this.state === LoadingState.READY;
+  }
+
+  /**
+   * 是否有错误
+   */
+  hasError(): boolean {
+    return this.state === LoadingState.ERROR;
+  }
+}
+
+/**
+ * 创建加载状态管理器
+ */
+export function createLoadingStateManager(): LoadingStateManager {
+  return new LoadingStateManager();
+}

package/src/core/logger.test.ts

@@ -0,0 +1,49 @@
+/**
+ * @file Logger 测试
+ * @description 测试日志系统
+ */
+
+import { Logger, LogLevel } from './logger';
+
+describe('Logger', () => {
+  let logger: Logger;
+
+  beforeEach(() => {
+    logger = Logger.getInstance();
+  });
+
+  it('should get singleton instance', () => {
+    const logger2 = Logger.getInstance();
+    expect(logger).toBe(logger2);
+  });
+
+  it('should log debug message', () => {
+    expect(() => {
+      logger.debug('Test', 'Debug message');
+    }).not.toThrow();
+  });
+
+  it('should log info message', () => {
+    expect(() => {
+      logger.info('Test', 'Info message');
+    }).not.toThrow();
+  });
+
+  it('should log warn message', () => {
+    expect(() => {
+      logger.warn('Test', 'Warning message');
+    }).not.toThrow();
+  });
+
+  it('should log error message', () => {
+    expect(() => {
+      logger.error('Test', 'Error message', new Error('test error'));
+    }).not.toThrow();
+  });
+
+  it('should set log level', () => {
+    expect(() => {
+      logger.setLevel(LogLevel.WARN);
+    }).not.toThrow();
+  });
+});

package/src/core/module-manager.ts

@@ -112,8 +112,7 @@ export class ModuleManager extends EventEmitter {
         this.emit('module:initialized', { name });
         this.logger.debug('ModuleManager', `模块 ${name} 初始化完成`);
       } catch (error) {
-        const errorObj = error instanceof Error ? error : new Error(String(error));
-        this.logger.error('ModuleManager', `模块 ${name} 初始化失败`, errorObj);
+        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)}`);
       }
@@ -136,8 +135,7 @@ export class ModuleManager extends EventEmitter {
         await module.dispose();
         this.emit('module:disposed', { name });
       } catch (error) {
-        const errorObj = error instanceof Error ? error : new Error(String(error));
-        this.logger.error('ModuleManager', `模块 ${name} 资源释放失败`, errorObj);
+        this.logger.error('ModuleManager', `模块 ${name} 资源释放失败`, error instanceof Error ? error : undefined);
         this.emit('module:error', { name, error });
       }
     }

package/src/core/scanner-factory.ts

@@ -4,19 +4,18 @@
  * @module core/scanner-factory
  */
 
-import { ConfigManager } from './config';
+import { ConfigManager, GlobalConfig } from './config';
 import { Logger } from './logger';
 import { ResourceManager } from './resource-manager';
 import { EventEmitter } from './event-emitter';
 import { InitializationError } from './errors';
-import { VERSION } from '../version';
 
 /**
  * 扫描器初始化选项
  */
 export interface ScannerFactoryOptions {
   /** 配置选项 */
-  config?: Record<string, any>;
+  config?: Partial<GlobalConfig>;
   /** 资源基础路径 */
   resourceBasePath?: string;
   /** 调试模式 */
@@ -102,7 +101,7 @@ export class ScannerFactory extends EventEmitter {
       }
       
       // 记录初始化日志
-      this.logger.info('ScannerFactory', `Initializing ID Scanner Library v${VERSION}`);
+      this.logger.info('ScannerFactory', `Initializing ID Scanner Library v1.4.0, debug: ${this.config.get('debug', false)}`);
       
       // 如果启用了自动初始化模块，则加载相应模块
       if (autoInitModules) {
@@ -120,7 +119,7 @@ export class ScannerFactory extends EventEmitter {
       this.initializing = false;
       
       const errorMessage = error instanceof Error ? error.message : String(error);
-      this.logger.error('ScannerFactory', `Initialization failed: ${errorMessage}`, error instanceof Error ? error : new Error(errorMessage));
+      this.logger.error('ScannerFactory', `Initialization failed: ${errorMessage}`, error instanceof Error ? error : undefined);
       
       this.emit('initialized', { success: false, error });
       
@@ -138,19 +137,19 @@ export class ScannerFactory extends EventEmitter {
     const enabledModules = [];
     
     // 检查每个模块的启用状态
-    if (this.config.get('modules.face.enabled', false)) {
+    if (this.config.isModuleEnabled('face')) {
       enabledModules.push(this.initFaceModule());
     }
     
-    if (this.config.get('modules.qr.enabled', false)) {
+    if (this.config.isModuleEnabled('qr')) {
       enabledModules.push(this.initQRModule());
     }
     
-    if (this.config.get('modules.idcard.enabled', false)) {
+    if (this.config.isModuleEnabled('idcard')) {
       enabledModules.push(this.initIDCardModule());
     }
     
-    if (this.config.get('modules.ocr.enabled', false)) {
+    if (this.config.isModuleEnabled('ocr')) {
       enabledModules.push(this.initOCRModule());
     }
     

package/src/index.ts

@@ -130,7 +130,7 @@ export class IDScanner {
   public async dispose(): Promise<void> {
     if (!this.initialized) {
       return;
-        }
+    }
     
     this.logger.info('IDScanner', '释放IDScanner资源');
     
@@ -147,6 +147,7 @@ export class IDScanner {
 }
 
 // 导出核心模块
+export * from './core/loading-state';
 export * from './core/module-manager';
 export * from './core/logger';
 export * from './core/errors';
@@ -159,7 +160,7 @@ export { FaceModule } from './modules/face';
 // 导出类型
 export * from './utils/types';
 export { IDCardModuleOptions, IDCardInfo, IDCardType, IDCardVerificationResult } from './modules/id-card/types';
-export { QRCodeModuleOptions, QRCodeResult } from './modules/qrcode/types';
+export { QRCodeModuleOptions, QRCodeResult, BarcodeFormat, DEFAULT_FORMATS } from './modules/qrcode/types';
 export { FaceModuleOptions, FaceDetectionResult, FaceComparisonResult } from './modules/face/types';
 
 // 默认导出IDScanner类

package/src/modules/face/face-detector.ts

@@ -31,6 +31,21 @@ export enum FaceModelType {
   BLAZE_FACE = 'blazeface'
 }
 
+/**
+ * 68点人脸关键点索引 (face-api 68-point model)
+ * 参考: https://github.com/justadudewhohacks/face-api.js/issues/175
+ */
+const FaceLandmarkIndex = {
+  LEFT_EYE: 36,
+  RIGHT_EYE: 45,
+  NOSE: 30,
+  MOUTH: 48,  // 上唇中心
+  LEFT_EYE_CORNER: 36,
+  RIGHT_EYE_CORNER: 45,
+  NOSE_TIP: 30,
+  MOUTH_CENTER: 57,
+} as const;
+
 /**
  * 人脸检测模块配置
  */
@@ -92,6 +107,7 @@ export class FaceDetector extends BaseScannerModule {
   
   /** 模型加载状态 */
   private modelsLoaded: boolean = false;
+  private loadedModels: Set<string> = new Set();
   
   /** 处理计时器ID */
   private processingTimerId: number | null = null;
@@ -236,59 +252,97 @@ export class FaceDetector extends BaseScannerModule {
   }
   
   /**
-   * 加载人脸检测模型
+   * 懒加载模型 - 仅在需要时加载特定模型
+   * @param modelType 模型类型
    * @param modelPath 模型路径
    */
-  private async loadModels(modelPath: string): Promise<void> {
+  private async lazyLoadModel(modelType: string, modelPath: string): Promise<void> {
+    // 检查模型是否已加载
+    const loadedModels = this.loadedModels || new Set();
+    if (loadedModels.has(modelType)) {
+      return;
+    }
+
+    this.logger.info('FaceDetector', `懒加载模型: ${modelType}`);
+
     try {
-      // 设置模型路径
-      faceapi.nets.ssdMobilenetv1.isLoaded && faceapi.nets.ssdMobilenetv1.dispose();
-      
-      // 根据配置加载检测模型
-      switch (this.config.detectionModel) {
-        case FaceModelType.SSD_MOBILENET:
+      switch (modelType) {
+        case 'ssdMobilenetv1':
           await faceapi.nets.ssdMobilenetv1.loadFromUri(modelPath);
           break;
-        case FaceModelType.TINY_FACE:
+        case 'tinyFaceDetector':
           await faceapi.nets.tinyFaceDetector.loadFromUri(modelPath);
           break;
-        case FaceModelType.MTCNN:
-          await faceapi.nets.mtcnn.loadFromUri(modelPath);
-          break;
-        default:
-          await faceapi.nets.ssdMobilenetv1.loadFromUri(modelPath);
-      }
-      
-      // 加载关键点检测模型
-      if (this.config.detectLandmarks) {
-        if (this.config.landmarksModel === '68_points') {
+        case 'faceLandmark68Net':
           await faceapi.nets.faceLandmark68Net.loadFromUri(modelPath);
-        } else {
+          break;
+        case 'faceLandmark68TinyNet':
           await faceapi.nets.faceLandmark68TinyNet.loadFromUri(modelPath);
-        }
-      }
-      
-      // 加载表情识别模型
-      if (this.config.detectExpressions) {
-        await faceapi.nets.faceExpressionNet.loadFromUri(modelPath);
-      }
-      
-      // 加载年龄性别识别模型
-      if (this.config.detectAgeGender) {
-        await faceapi.nets.ageGenderNet.loadFromUri(modelPath);
-      }
-      
-      // 加载人脸识别模型
-      if (this.config.extractEmbeddings) {
-        await faceapi.nets.faceRecognitionNet.loadFromUri(modelPath);
+          break;
+        case 'faceExpressionNet':
+          await faceapi.nets.faceExpressionNet.loadFromUri(modelPath);
+          break;
+        case 'ageGenderNet':
+          await faceapi.nets.ageGenderNet.loadFromUri(modelPath);
+          break;
+        case 'faceRecognitionNet':
+          await faceapi.nets.faceRecognitionNet.loadFromUri(modelPath);
+          break;
+        default:
+          this.logger.warn('FaceDetector', `未知模型类型: ${modelType}`);
+          return;
       }
-      
-      this.modelsLoaded = true;
-      this.logger.info('FaceDetector', '所有人脸检测模型加载完成');
+
+      loadedModels.add(modelType);
+      this.loadedModels = loadedModels;
+      this.logger.info('FaceDetector', `模型加载完成: ${modelType}`);
     } catch (error) {
-      this.logger.error('FaceDetector', `模型加载失败: ${error}`);
-      throw new ResourceLoadError('face-api-models', `模型加载失败: ${error}`);
+      this.logger.error('FaceDetector', `模型加载失败: ${modelType}`, error instanceof Error ? error : undefined);
+      throw new ResourceLoadError(modelType, `模型加载失败: ${error}`);
+    }
+  }
+
+  /**
+   * 根据需求加载模型
+   * @param options 检测选项
+   * @param modelPath 模型路径
+   */
+  private async loadModelsOnDemand(options: FaceDetectionOptions, modelPath: string): Promise<void> {
+    // 基础检测模型
+    await this.lazyLoadModel(this.config.detectionModel, modelPath);
+
+    // 关键点模型
+    if (options.withLandmarks || this.config.detectLandmarks) {
+      await this.lazyLoadModel(
+        this.config.landmarksModel === '68_points' ? 'faceLandmark68Net' : 'faceLandmark68TinyNet',
+        modelPath
+      );
+    }
+
+    // 表情模型
+    if (options.withExpressions || this.config.detectExpressions) {
+      await this.lazyLoadModel('faceExpressionNet', modelPath);
+    }
+
+    // 年龄性别模型
+    if (options.withAgeAndGender || this.config.detectAgeGender) {
+      await this.lazyLoadModel('ageGenderNet', modelPath);
+    }
+
+    // 人脸识别模型
+    if (options.withEmbedding || this.config.extractEmbeddings) {
+      await this.lazyLoadModel('faceRecognitionNet', modelPath);
     }
+
+    this.modelsLoaded = true;
+  }
+
+  /**
+   * 加载人脸检测模型 (旧版 - 保留兼容性)
+   * @param modelPath 模型路径
+   */
+  private async loadModels(modelPath: string): Promise<void> {
+    await this.loadModelsOnDemand({}, modelPath);
   }
   
   /**
@@ -308,8 +362,12 @@ export class FaceDetector extends BaseScannerModule {
     
     this.setStatus(ModuleStatus.PROCESSING);
     this.emit(ModuleEvent.PROCESS_START);
-    
+
     try {
+      // 懒加载所需的模型
+      const modelPath = this.config.modelPath || '/models';
+      await this.loadModelsOnDemand(options, modelPath);
+      
       // 合并选项和配置
       const processOptions: FaceDetectionOptions = {
         minConfidence: this.config.minConfidence,
@@ -638,15 +696,16 @@ export class FaceDetector extends BaseScannerModule {
       
       // 限制检测数量
       const maxFaces = detectOptions.maxFaces || this.config.maxFaces;
-      if ((detections as any).length > maxFaces) {
-        detections = (detections as any).slice(0, maxFaces);
+      const detectionsArray: any[] = Array.isArray(detections) ? detections : [detections];
+      if (detectionsArray.length > maxFaces) {
+        detectionsArray.length = maxFaces;
       }
       
       // 将结果转换为标准格式
       const results: FaceDetectionResult[] = [];
       const processingTime = Date.now() - startTime;
       
-      for (const detection of detections) {
+      for (const detection of detectionsArray) {
         const boundingBox: Rect = {
           x: detection.detection?.box.x || 0,
           y: detection.detection?.box.y || 0,
@@ -667,27 +726,23 @@ export class FaceDetector extends BaseScannerModule {
         // 添加关键点
         if (detection.landmarks) {
           const positions = detection.landmarks.positions;
-          const leftEyeIdx = 36; // 面部68点模型中左眼的索引
-          const rightEyeIdx = 45; // 面部68点模型中右眼的索引
-          const noseIdx = 30; // 鼻尖
-          const mouthIdx = 57; // 嘴巴中心
           
           result.landmarks = {
             leftEye: {
-              x: positions[leftEyeIdx].x,
-              y: positions[leftEyeIdx].y
+              x: positions[FaceLandmarkIndex.LEFT_EYE].x,
+              y: positions[FaceLandmarkIndex.LEFT_EYE].y
             },
             rightEye: {
-              x: positions[rightEyeIdx].x,
-              y: positions[rightEyeIdx].y
+              x: positions[FaceLandmarkIndex.RIGHT_EYE].x,
+              y: positions[FaceLandmarkIndex.RIGHT_EYE].y
             },
             nose: {
-              x: positions[noseIdx].x,
-              y: positions[noseIdx].y
+              x: positions[FaceLandmarkIndex.NOSE].x,
+              y: positions[FaceLandmarkIndex.NOSE].y
             },
             mouth: {
-              x: positions[mouthIdx].x,
-              y: positions[mouthIdx].y
+              x: positions[FaceLandmarkIndex.MOUTH_CENTER].x,
+              y: positions[FaceLandmarkIndex.MOUTH_CENTER].y
             },
             points: positions.map((p: { x: any; y: any; }) => ({ x: p.x, y: p.y }))
           };
@@ -695,16 +750,18 @@ export class FaceDetector extends BaseScannerModule {
         
         // 添加表情属性
         if (detection.expressions) {
+          const emotion = {
+            angry: detection.expressions.angry,
+            disgust: detection.expressions.disgusted,
+            fear: detection.expressions.fearful,
+            happy: detection.expressions.happy,
+            neutral: detection.expressions.neutral,
+            sad: detection.expressions.sad,
+            surprise: detection.expressions.surprised
+          };
           result.attributes = {
-            emotion: {
-              angry: detection.expressions.angry,
-              disgust: detection.expressions.disgusted,
-              fear: detection.expressions.fearful,
-              happy: detection.expressions.happy,
-              neutral: detection.expressions.neutral,
-              sad: detection.expressions.sad,
-              surprise: detection.expressions.surprised
-            }
+            ...result.attributes,
+            emotion
           };
         }
         

package/src/modules/id-card/anti-fake-detector.ts

@@ -136,7 +136,7 @@ export class AntiFakeDetector implements Disposable {
       detectedFeatures.length >= 2
 
     // 生成结果消息
-    let message = isAuthentic
+    const message = isAuthentic
       ? `身份证真实，检测到${detectedFeatures.length}个防伪特征`
       : detectedFeatures.length > 0
       ? `可疑身份证，仅检测到${detectedFeatures.length}个防伪特征，置信度不足`
@@ -456,7 +456,7 @@ export class AntiFakeDetector implements Disposable {
   } {
     const { data, width, height } = edgeData
     let edgeCount = 0
-    let totalPixels = width * height
+    const totalPixels = width * height
 
     // 计算边缘像素的数量
     for (let i = 0; i < data.length; i += 4) {

package/src/modules/id-card/ocr-worker.ts

@@ -149,7 +149,7 @@ function parseIDCardText(text: string): IDCardInfo {
   const birthDateRegex2 = /出生[\s\:]*(\d{4})[-\/\.](\d{1,2})[-\/\.](\d{1,2})/;
   const birthDateRegex3 = /出生日期[\s\:]*(\d{4})[-\/\.\u5e74](\d{1,2})[-\/\.\u6708](\d{1,2})[日号]?/;
 
-  let birthDateMatch =
+  const birthDateMatch =
     processedText.match(birthDateRegex1) ||
     processedText.match(birthDateRegex2) ||
     processedText.match(birthDateRegex3);

package/src/modules/qrcode/qr-code-scanner.ts

@@ -6,7 +6,7 @@
 
 import { EventEmitter } from '../../core/event-emitter';
 import { Logger } from '../../core/logger';
-import { QRCodeResult } from './types';
+import { QRCodeResult, BarcodeFormat } from './types';
 import jsQR from 'jsqr';
 
 /**
@@ -112,6 +112,7 @@ export class QRCodeScanner extends EventEmitter {
     // 构建结果
     const result: QRCodeResult = {
       data: code.data,
+      barcodeFormat: BarcodeFormat.QR_CODE,
       boundingBox: {
         topLeft: code.location.topLeftCorner,
         topRight: code.location.topRightCorner,