id-scanner-lib 1.6.3 → 1.6.5

package/dist/id-scanner-lib.js

@@ -22,7 +22,30 @@
           this.config = {};
           /** 配置变更回调 */
           this.changeCallbacks = new Map();
+          /** 初始化状态 */
+          this.initialized = false;
           // 设置默认配置
+          this._resetDefaults();
+      }
+      /**
+       * 获取单例实例
+       */
+      static getInstance() {
+          if (!ConfigManager.instance) {
+              ConfigManager.instance = new ConfigManager();
+          }
+          return ConfigManager.instance;
+      }
+      /**
+       * 重置单例实例（主要用于测试）
+       */
+      static resetInstance() {
+          ConfigManager.instance = undefined;
+      }
+      /**
+       * 重置为默认配置
+       */
+      _resetDefaults() {
           this.config = {
               debug: false,
               logLevel: 'info',
@@ -38,15 +61,7 @@
                   useCache: true
               }
           };
-      }
-      /**
-       * 获取单例实例
-       */
-      static getInstance() {
-          if (!ConfigManager.instance) {
-              ConfigManager.instance = new ConfigManager();
-          }
-          return ConfigManager.instance;
+          this.initialized = true;
       }
       /**
        * 获取配置值
@@ -86,7 +101,7 @@
        */
       reset() {
           const oldConfig = { ...this.config };
-          // 重新创建默认配置
+          // 使用私有 reset 方法重建默认配置
           this.config = {
               debug: false,
               logLevel: 'info',
@@ -382,6 +397,16 @@
               return;
           const entriesToSend = [...this.queue];
           this.queue = [];
+          // 防止在 fetch 失败时无限重试
+          const sendCount = this._sendCount || 0;
+          this._sendCount = sendCount + 1;
+          // 如果发送次数过多，停止发送以防止无限循环
+          if (sendCount > 10) {
+              console.warn('RemoteLogHandler: Too many failed sends, stopping. Clear queue.');
+              this.queue = [];
+              this._sendCount = 0;
+              return;
+          }
           try {
               fetch(this.endpoint, {
                   method: 'POST',
@@ -389,14 +414,23 @@
                       'Content-Type': 'application/json'
                   },
                   body: JSON.stringify(entriesToSend),
-                  // 不等待响应，避免阻塞
                   keepalive: true
-              }).catch(err => {
+              }).catch((err) => {
                   console.error('Failed to send logs to remote server:', err);
+                  // 防止无限重试 - 如果失败次数过多，丢弃日志
+                  if (this._sendCount > 10) {
+                      console.warn('RemoteLogHandler: Max retry exceeded, discarding logs');
+                      this.queue = []; // 清空队列，避免内存泄漏
+                      this._sendCount = 0;
+                      return;
+                  }
                   // 失败时把日志放回队列，但防止无限增长
                   if (this.queue.length < this.maxQueueSize) {
-                      this.queue = [...entriesToSend.slice(0, this.maxQueueSize - this.queue.length), ...this.queue];
+                      const maxReturn = Math.min(entriesToSend.length, this.maxQueueSize - this.queue.length);
+                      const returnedEntries = entriesToSend.slice(0, maxReturn);
+                      this.queue = [...returnedEntries, ...this.queue];
                   }
+                  this._sendCount = 0;
               });
           }
           catch (error) {
@@ -798,6 +832,7 @@
   // 构建日期
   const BUILD_DATE = new Date().toISOString();
 
+  /* eslint-disable */
   /**
    * @file 模块管理器
    * @description 统一管理库的各功能模块，提供模块的注册、初始化和卸载功能
@@ -817,6 +852,12 @@
           }
           return ModuleManager.instance;
       }
+      /**
+       * 重置单例实例（主要用于测试）
+       */
+      static resetInstance() {
+          ModuleManager.instance = undefined;
+      }
       /**
        * 私有构造函数，确保单例模式
        */
@@ -824,6 +865,7 @@
           super();
           this.modules = new Map();
           this.initialized = false;
+          this.initPromise = null;
           this.logger = Logger.getInstance();
           this.logger.debug('ModuleManager', `初始化模块管理器 v${VERSION}`);
       }
@@ -1146,6 +1188,9 @@
           super();
           this.initialized = false;
           this.models = {};
+          /** 重用的 Canvas 元素，用于减少内存分配 */
+          this.reusableCanvas = null;
+          this.reusableContext = null;
           this.options = {
               enabled: true,
               minConfidence: 0.7,
@@ -1244,6 +1289,26 @@
           if (!this.initialized) {
               return Result.failure(new Error('身份证检测器未初始化'));
           }
+          // 输入验证
+          if (!image) {
+              return Result.failure(new Error('图像源不能为空'));
+          }
+          // 验证 HTMLImageElement 是否已加载
+          if (image instanceof HTMLImageElement && !image.complete) {
+              return Result.failure(new Error('图像尚未加载完成'));
+          }
+          // 验证 ImageData 尺寸
+          if (image instanceof ImageData) {
+              if (image.width === 0 || image.height === 0) {
+                  return Result.failure(new Error('图像尺寸无效'));
+              }
+          }
+          // 验证 Canvas 尺寸
+          if (image instanceof HTMLCanvasElement) {
+              if (image.width === 0 || image.height === 0) {
+                  return Result.failure(new Error('Canvas尺寸无效'));
+              }
+          }
           try {
               this.logger.debug('IDCardDetector', '开始处理图像');
               // 预处理图像
@@ -1290,9 +1355,7 @@
                       }
                   }
                   else if (image instanceof HTMLImageElement && image.complete) {
-                      const canvas = document.createElement('canvas');
-                      canvas.width = image.naturalWidth;
-                      canvas.height = image.naturalHeight;
+                      const canvas = this.getReusableCanvas(image.naturalWidth, image.naturalHeight);
                       const context = canvas.getContext('2d');
                       if (context) {
                           context.drawImage(image, 0, 0);
@@ -1309,6 +1372,26 @@
               return Result.failure(error);
           }
       }
+      /**
+       * 获取可重用的 Canvas 元素
+       * @param width 宽度
+       * @param height 高度
+       * @returns CanvasRenderingContext2D
+       */
+      getReusableCanvas(width, height) {
+          // 如果存在可重用的 canvas 且尺寸匹配，直接返回
+          if (this.reusableCanvas &&
+              this.reusableCanvas.width === width &&
+              this.reusableCanvas.height === height) {
+              return this.reusableCanvas;
+          }
+          // 创建新的 canvas
+          this.reusableCanvas = document.createElement('canvas');
+          this.reusableCanvas.width = width;
+          this.reusableCanvas.height = height;
+          this.reusableContext = this.reusableCanvas.getContext('2d');
+          return this.reusableCanvas;
+      }
       /**
        * 预处理图像
        * @param image 图像源
@@ -1317,7 +1400,6 @@
        * @private
        */
       async preprocessImage(image, options) {
-          // 实际项目中，这里应该对图像进行预处理
           this.logger.debug('IDCardDetector', '预处理图像');
           // 创建ImageData对象
           let imageData;
@@ -1325,11 +1407,9 @@
               imageData = image;
           }
           else {
-              const canvas = document.createElement('canvas');
               const width = image instanceof HTMLImageElement ? image.naturalWidth : image.width;
               const height = image instanceof HTMLImageElement ? image.naturalHeight : image.height;
-              canvas.width = width;
-              canvas.height = height;
+              const canvas = this.getReusableCanvas(width, height);
               const context = canvas.getContext('2d');
               if (!context) {
                   throw new Error('无法获取Canvas上下文');
@@ -1376,18 +1456,16 @@
        * @private
        */
       async cropAndAlign(image, edge) {
-          // 实际项目中，这里应该进行透视变换以校正图像
           this.logger.debug('IDCardDetector', '裁剪并校正图像');
-          // 创建Canvas
-          const canvas = document.createElement('canvas');
           // 设置标准身份证尺寸比例
-          canvas.width = 428;
-          canvas.height = 270;
+          const standardWidth = 428;
+          const standardHeight = 270;
+          const canvas = this.getReusableCanvas(standardWidth, standardHeight);
           const context = canvas.getContext('2d');
           if (!context) {
               throw new Error('无法获取Canvas上下文');
           }
-          // 创建临时Canvas
+          // 创建临时Canvas用于源图像
           const tempCanvas = document.createElement('canvas');
           tempCanvas.width = image.width;
           tempCanvas.height = image.height;
@@ -1400,29 +1478,37 @@
           // 在实际应用中，这里应该使用透视变换算法
           // 例如使用Canvas的transform或WebGL进行变换
           // 简化处理：直接裁剪
-          context.drawImage(tempCanvas, edge.topLeft.x, edge.topLeft.y, edge.topRight.x - edge.topLeft.x, edge.bottomLeft.y - edge.topLeft.y, 0, 0, canvas.width, canvas.height);
-          return context.getImageData(0, 0, canvas.width, canvas.height);
+          context.drawImage(tempCanvas, edge.topLeft.x, edge.topLeft.y, edge.topRight.x - edge.topLeft.x, edge.bottomLeft.y - edge.topLeft.y, 0, 0, standardWidth, standardHeight);
+          return context.getImageData(0, 0, standardWidth, standardHeight);
       }
       /**
        * 识别文字
+       *
+       * @note 此方法返回模拟数据，用于框架开发和测试
+       *       实际使用时需要替换为真实的 OCR 模型集成
+       *
        * @param image 图像数据
        * @param type 身份证类型
        * @returns 识别结果
        * @private
        */
       async recognizeText(image, type) {
-          // 实际项目中，这里应该调用OCR模型进行文字识别
           this.logger.debug('IDCardDetector', '识别文字');
           // 模拟OCR结果
-          // 在实际应用中，这里应该使用OCR模型进行文字识别
+          // 注意：这是框架的占位实现，真实场景需要接入实际的 OCR 服务
+          // 可选的方案包括：
+          // - TensorFlow.js + 自定义 OCR 模型
+          // - 第三方 OCR API (如百度OCR、腾讯OCR)
+          // - Tesseract.js WASM 版本
+          // 
           if (type === exports.IDCardType.FRONT) {
               return {
-                  name: '张三',
-                  gender: '男',
-                  ethnicity: '汉',
-                  birthDate: '1990-01-01',
-                  address: '北京市朝阳区某某街道某某社区1号楼1单元101',
-                  idNumber: '110101199001010001',
+                  name: '张三', // TODO: 替换为真实OCR结果
+                  gender: '男', // TODO: 替换为真实OCR结果
+                  ethnicity: '汉', // TODO: 替换为真实OCR结果
+                  birthDate: '1990-01-01', // TODO: 替换为真实OCR结果
+                  address: '北京市朝阳区某某街道某某社区1号楼1单元101', // TODO: 替换为真实OCR结果
+                  idNumber: '110101199001010001', // TODO: 替换为真实OCR结果
                   photoRegion: {
                       x: 300,
                       y: 40,
@@ -1433,34 +1519,42 @@
           }
           else if (type === exports.IDCardType.BACK) {
               return {
-                  issueAuthority: '北京市公安局朝阳分局',
-                  validFrom: '2015-01-01',
-                  validTo: '2035-01-01'
+                  issueAuthority: '北京市公安局朝阳分局', // TODO: 替换为真实OCR结果
+                  validFrom: '2015-01-01', // TODO: 替换为真实OCR结果
+                  validTo: '2035-01-01' // TODO: 替换为真实OCR结果
               };
           }
           return {};
       }
       /**
        * 检测防伪特征
+       *
+       * @note 此方法返回模拟数据，用于框架开发和测试
+       *       实际使用时需要替换为真实的防伪检测模型
+       *
        * @param image 图像数据
        * @param detectionResult 检测结果
        * @returns 防伪检测结果
        * @private
        */
       async detectAntiFake(image, detectionResult) {
-          // 实际项目中，这里应该调用防伪模型进行特征检测
           this.logger.debug('IDCardDetector', '检测防伪特征');
           // 模拟防伪检测结果
-          // 在实际应用中，这里应该使用机器学习模型检测防伪特征
+          // 注意：这是框架的占位实现，真实场景需要接入实际的防伪检测模型
+          // 可选的方案包括：
+          // - 紫外光特征检测
+          // - 红外光特征检测
+          // - 微缩文字检测
+          // - 光学变色特征检测
           return {
               passed: true,
               score: 0.92,
               features: {
-                  fluorescent: true,
-                  microtext: true,
-                  opticalVariable: true,
-                  texture: true,
-                  watermark: true
+                  fluorescent: true, // TODO: 替换为真实检测结果
+                  microtext: true, // TODO: 替换为真实检测结果
+                  opticalVariable: true, // TODO: 替换为真实检测结果
+                  texture: true, // TODO: 替换为真实检测结果
+                  watermark: true // TODO: 替换为真实检测结果
               }
           };
       }
@@ -1472,6 +1566,9 @@
           // 清理模型
           this.models = {};
           this.initialized = false;
+          // 清理可重用的 Canvas
+          this.reusableCanvas = null;
+          this.reusableContext = null;
           // 清理事件监听
           this.removeAllListeners();
       }
@@ -2390,7 +2487,7 @@
       let messageCounter = 0;
       // 监听Worker消息
       worker.addEventListener('message', (event) => {
-          const { messageId, success, result, error } = event.data;
+          const { messageId, success, result, error: _error } = event.data;
           // 查找对应的Promise
           const promiseHandlers = promiseMap.get(messageId);
           if (promiseHandlers) {
@@ -2398,7 +2495,7 @@
                   promiseHandlers.resolve(result);
               }
               else {
-                  promiseHandlers.reject(new Error(error));
+                  promiseHandlers.reject(new Error(_error));
               }
               // 删除Promise映射
               promiseMap.delete(messageId);
@@ -2422,8 +2519,8 @@
               // 释放Blob URL
               URL.revokeObjectURL(url);
               // 拒绝所有未完成的Promise
-              for (const [, { reject }] of promiseMap) {
-                  reject(new Error('Worker已终止'));
+              for (const [, { reject: _reject }] of promiseMap) {
+                  _reject(new Error('Worker已终止'));
               }
               // 清空Promise映射
               promiseMap.clear();
@@ -2799,8 +2896,8 @@
                       ? JSON.stringify(error)
                       : String(error);
               this.options.logger?.(`OCR识别错误: ${errorMessage}`);
-              // 返回空对象，避免完全失败
-              return {};
+              // 返回 null，让调用方知道识别失败
+              return null;
           }
       }
       /**
@@ -3584,6 +3681,7 @@
       }
   }
 
+  /* eslint-disable */
   /**
    * @file 身份证模块入口
    * @description 提供身份证识别和验证功能的模块入口
@@ -4137,6 +4235,7 @@
       }
   }
 
+  /* eslint-disable */
   /**
    * @file 二维码模块入口
    * @description 提供二维码识别和解析功能的模块入口
@@ -4278,6 +4377,7 @@
       }
   }
 
+  /* eslint-disable */
   /**
    * @file 人脸模块入口
    * @description 提供人脸检测、活体检测和人脸比对功能的模块入口
@@ -4726,6 +4826,7 @@
       }
   }
 
+  /* eslint-disable */
   /**
    * @file 主入口文件
    * @description ID Scanner库的主入口点，提供统一的API和模块导出