id-scanner-lib 1.6.7 → 1.7.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/modules/face/face-comparator.ts

@@ -0,0 +1,150 @@
+/**
+ * @file 人脸比对器
+ * @description 提供人脸特征向量比对功能
+ * @module modules/face/face-comparator
+ */
+
+import { FaceDetectionResult } from '../../interfaces/face-detection';
+import { Result } from '../../core/result';
+import { FaceComparisonError } from '../../core/errors';
+import { Logger } from '../../core/logger';
+
+/**
+ * 人脸比对结果
+ */
+export interface ComparisonResult {
+  /** 相似度 (0-1) */
+  similarity: number;
+  /** 是否匹配（基于阈值） */
+  isMatch: boolean;
+  /** 使用的阈值 */
+  threshold: number;
+}
+
+/**
+ * 人脸比对器配置
+ */
+export interface FaceComparatorConfig {
+  /** 人脸匹配阈值 (0-1) */
+  matchThreshold?: number;
+}
+
+/**
+ * 人脸比对器
+ *
+ * 负责计算两个人脸特征向量的相似度
+ */
+export class FaceComparator {
+  /** 日志记录器 */
+  private logger: Logger;
+
+  /** 匹配阈值 */
+  private matchThreshold: number;
+
+  /**
+   * 构造函数
+   * @param config 比对器配置
+   */
+  constructor(config: FaceComparatorConfig = {}) {
+    this.logger = Logger.getInstance();
+    this.matchThreshold = config.matchThreshold ?? 0.6;
+  }
+
+  /**
+   * 计算两个特征向量的余弦相似度
+   *
+   * @param v1 特征向量1
+   * @param v2 特征向量2
+   * @returns 相似度 (0-1)
+   */
+  computeSimilarity(v1: number[], v2: number[]): number {
+    if (v1.length !== v2.length) {
+      throw new Error('特征向量维度不匹配');
+    }
+
+    let dotProduct = 0;
+    let norm1 = 0;
+    let norm2 = 0;
+
+    for (let i = 0; i < v1.length; i++) {
+      dotProduct += v1[i] * v2[i];
+      norm1 += v1[i] * v1[i];
+      norm2 += v2[i] * v2[i];
+    }
+
+    // 确保长度非零
+    if (norm1 === 0 || norm2 === 0) {
+      return 0;
+    }
+
+    return dotProduct / (Math.sqrt(norm1) * Math.sqrt(norm2));
+  }
+
+  /**
+   * 比对两个人脸
+   *
+   * @param source 源人脸（特征向量或检测结果）
+   * @param target 目标人脸（特征向量或检测结果）
+   * @returns 比对结果
+   */
+  compare(
+    source: number[] | FaceDetectionResult,
+    target: number[] | FaceDetectionResult
+  ): Result<ComparisonResult> {
+    try {
+      // 提取特征向量
+      const sourceEmbedding = this.extractEmbedding(source);
+      const targetEmbedding = this.extractEmbedding(target);
+
+      if (!sourceEmbedding || !targetEmbedding) {
+        return Result.failure(new FaceComparisonError('无法获取特征向量'));
+      }
+
+      // 计算相似度
+      const similarity = this.computeSimilarity(sourceEmbedding, targetEmbedding);
+      const isMatch = similarity >= this.matchThreshold;
+
+      return Result.success({
+        similarity,
+        isMatch,
+        threshold: this.matchThreshold
+      });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error('FaceComparator', `人脸比对失败: ${errorMessage}`, error as Error);
+      return Result.failure(new FaceComparisonError(`人脸比对失败: ${errorMessage}`));
+    }
+  }
+
+  /**
+   * 从输入中提取特征向量
+   */
+  private extractEmbedding(input: number[] | FaceDetectionResult): number[] | null {
+    if (Array.isArray(input)) {
+      return input;
+    }
+
+    if (input.embedding?.vector) {
+      return input.embedding.vector;
+    }
+
+    return null;
+  }
+
+  /**
+   * 设置匹配阈值
+   */
+  setThreshold(threshold: number): void {
+    if (threshold < 0 || threshold > 1) {
+      throw new Error('阈值必须在 0-1 范围内');
+    }
+    this.matchThreshold = threshold;
+  }
+
+  /**
+   * 获取当前阈值
+   */
+  getThreshold(): number {
+    return this.matchThreshold;
+  }
+}

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

@@ -0,0 +1,104 @@
+/**
+ * @file 人脸检测选项工厂
+ * @description 创建 face-api 检测选项和处理选项
+ * @module modules/face/face-detector-options
+ */
+
+import * as faceapi from '@vladmandic/face-api';
+import { FaceDetectionOptions } from '../../interfaces/face-detection';
+import { FaceModelType, FaceDetectorConfig } from './face-detector';
+
+/**
+ * 人脸检测选项工厂
+ *
+ * 负责创建 face-api 兼容的检测选项和处理选项
+ */
+export class FaceDetectorOptionsFactory {
+  /**
+   * 创建 face-api 检测选项
+   * @param detectionModel 检测模型类型
+   * @param minConfidence 最小置信度
+   * @returns face-api 检测选项
+   */
+  static createFaceAPIOptions(
+    detectionModel: FaceModelType,
+    minConfidence: number
+  ): faceapi.SsdMobilenetv1Options | faceapi.TinyFaceDetectorOptions | faceapi.MtcnnOptions {
+    switch (detectionModel) {
+      case FaceModelType.SSD_MOBILENET:
+        return new faceapi.SsdMobilenetv1Options({ minConfidence });
+      case FaceModelType.TINY_FACE:
+        return new faceapi.TinyFaceDetectorOptions({ scoreThreshold: minConfidence });
+      case FaceModelType.MTCNN:
+        return new faceapi.MtcnnOptions({ minConfidence });
+      default:
+        return new faceapi.SsdMobilenetv1Options({ minConfidence });
+    }
+  }
+
+  /**
+   * 合并检测选项和配置
+   * @param config 人脸检测器配置
+   * @param options 用户提供的选项
+   * @returns 合并后的检测选项
+   */
+  static mergeOptions(
+    config: FaceDetectorConfig,
+    options: FaceDetectionOptions = {}
+  ): FaceDetectionOptions {
+    return {
+      minConfidence: config.minConfidence,
+      maxFaces: config.maxFaces,
+      withLandmarks: config.detectLandmarks,
+      withAttributes: config.detectExpressions || config.detectAgeGender,
+      withEmbedding: config.extractEmbeddings,
+      enableTracking: config.enableTracking,
+      ...options
+    };
+  }
+
+  /**
+   * 执行人脸检测
+   * @param input 输入图像/视频/画布
+   * @param faceapiOptions face-api 检测选项
+   * @param detectOptions 检测选项
+   * @param landmarksModel 关键点模型类型
+   * @returns face-api 检测结果
+   */
+  static async detect(
+    input: HTMLImageElement | HTMLCanvasElement | HTMLVideoElement,
+    faceapiOptions: faceapi.SsdMobilenetv1Options | faceapi.TinyFaceDetectorOptions | faceapi.MtcnnOptions,
+    detectOptions: FaceDetectionOptions,
+    landmarksModel: 'tiny' | '68_points'
+  ): Promise<any> {
+    const withLandmarks = detectOptions.withLandmarks;
+    const withAttributes = detectOptions.withAttributes;
+    const withEmbedding = detectOptions.withEmbedding;
+
+    // 根据选项组合选择检测方法链
+    if (withLandmarks && withAttributes && withEmbedding) {
+      // 全功能检测
+      return await faceapi
+        .detectAllFaces(input, faceapiOptions)
+        .withFaceLandmarks(landmarksModel === 'tiny')
+        .withFaceExpressions()
+        .withAgeAndGender()
+        .withFaceDescriptors();
+    } else if (withLandmarks && withAttributes) {
+      // 检测带关键点和属性
+      return await faceapi
+        .detectAllFaces(input, faceapiOptions)
+        .withFaceLandmarks(landmarksModel === 'tiny')
+        .withFaceExpressions()
+        .withAgeAndGender();
+    } else if (withLandmarks) {
+      // 检测带关键点
+      return await faceapi
+        .detectAllFaces(input, faceapiOptions)
+        .withFaceLandmarks(landmarksModel === 'tiny');
+    } else {
+      // 仅检测
+      return await faceapi.detectAllFaces(input, faceapiOptions);
+    }
+  }
+}