id-scanner-lib 1.6.3 → 1.6.5

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 agions
+Copyright (c) 2025-2026 agions
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/id-scanner-lib.esm.js

@@ -20,7 +20,30 @@ class ConfigManager {
         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',
@@ -36,15 +59,7 @@ class ConfigManager {
                 useCache: true
             }
         };
-    }
-    /**
-     * 获取单例实例
-     */
-    static getInstance() {
-        if (!ConfigManager.instance) {
-            ConfigManager.instance = new ConfigManager();
-        }
-        return ConfigManager.instance;
+        this.initialized = true;
     }
     /**
      * 获取配置值
@@ -84,7 +99,7 @@ class ConfigManager {
      */
     reset() {
         const oldConfig = { ...this.config };
-        // 重新创建默认配置
+        // 使用私有 reset 方法重建默认配置
         this.config = {
             debug: false,
             logLevel: 'info',
@@ -380,6 +395,16 @@ class RemoteLogHandler {
             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',
@@ -387,14 +412,23 @@ class RemoteLogHandler {
                     '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) {
@@ -796,6 +830,7 @@ const VERSION = '1.3.3';
 // 构建日期
 const BUILD_DATE = new Date().toISOString();
 
+/* eslint-disable */
 /**
  * @file 模块管理器
  * @description 统一管理库的各功能模块，提供模块的注册、初始化和卸载功能
@@ -815,6 +850,12 @@ class ModuleManager extends EventEmitter {
         }
         return ModuleManager.instance;
     }
+    /**
+     * 重置单例实例（主要用于测试）
+     */
+    static resetInstance() {
+        ModuleManager.instance = undefined;
+    }
     /**
      * 私有构造函数，确保单例模式
      */
@@ -822,6 +863,7 @@ class ModuleManager extends EventEmitter {
         super();
         this.modules = new Map();
         this.initialized = false;
+        this.initPromise = null;
         this.logger = Logger.getInstance();
         this.logger.debug('ModuleManager', `初始化模块管理器 v${VERSION}`);
     }
@@ -1144,6 +1186,9 @@ class IDCardDetector extends EventEmitter {
         super();
         this.initialized = false;
         this.models = {};
+        /** 重用的 Canvas 元素，用于减少内存分配 */
+        this.reusableCanvas = null;
+        this.reusableContext = null;
         this.options = {
             enabled: true,
             minConfidence: 0.7,
@@ -1242,6 +1287,26 @@ class IDCardDetector extends EventEmitter {
         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', '开始处理图像');
             // 预处理图像
@@ -1288,9 +1353,7 @@ class IDCardDetector extends EventEmitter {
                     }
                 }
                 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);
@@ -1307,6 +1370,26 @@ class IDCardDetector extends EventEmitter {
             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 图像源
@@ -1315,7 +1398,6 @@ class IDCardDetector extends EventEmitter {
      * @private
      */
     async preprocessImage(image, options) {
-        // 实际项目中，这里应该对图像进行预处理
         this.logger.debug('IDCardDetector', '预处理图像');
         // 创建ImageData对象
         let imageData;
@@ -1323,11 +1405,9 @@ class IDCardDetector extends EventEmitter {
             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上下文');
@@ -1374,18 +1454,16 @@ class IDCardDetector extends EventEmitter {
      * @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;
@@ -1398,29 +1476,37 @@ class IDCardDetector extends EventEmitter {
         // 在实际应用中，这里应该使用透视变换算法
         // 例如使用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 === 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,
@@ -1431,34 +1517,42 @@ class IDCardDetector extends EventEmitter {
         }
         else if (type === 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: 替换为真实检测结果
             }
         };
     }
@@ -1470,6 +1564,9 @@ class IDCardDetector extends EventEmitter {
         // 清理模型
         this.models = {};
         this.initialized = false;
+        // 清理可重用的 Canvas
+        this.reusableCanvas = null;
+        this.reusableContext = null;
         // 清理事件监听
         this.removeAllListeners();
     }
@@ -2388,7 +2485,7 @@ function createWorker(workerFunction) {
     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) {
@@ -2396,7 +2493,7 @@ function createWorker(workerFunction) {
                 promiseHandlers.resolve(result);
             }
             else {
-                promiseHandlers.reject(new Error(error));
+                promiseHandlers.reject(new Error(_error));
             }
             // 删除Promise映射
             promiseMap.delete(messageId);
@@ -2420,8 +2517,8 @@ function createWorker(workerFunction) {
             // 释放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();
@@ -2797,8 +2894,8 @@ class OCRProcessor {
                     ? JSON.stringify(error)
                     : String(error);
             this.options.logger?.(`OCR识别错误: ${errorMessage}`);
-            // 返回空对象，避免完全失败
-            return {};
+            // 返回 null，让调用方知道识别失败
+            return null;
         }
     }
     /**
@@ -3582,6 +3679,7 @@ class AntiFakeDetector {
     }
 }
 
+/* eslint-disable */
 /**
  * @file 身份证模块入口
  * @description 提供身份证识别和验证功能的模块入口
@@ -4135,6 +4233,7 @@ class QRCodeScanner extends EventEmitter {
     }
 }
 
+/* eslint-disable */
 /**
  * @file 二维码模块入口
  * @description 提供二维码识别和解析功能的模块入口
@@ -4276,6 +4375,7 @@ class QRCodeModule extends BaseModule {
     }
 }
 
+/* eslint-disable */
 /**
  * @file 人脸模块入口
  * @description 提供人脸检测、活体检测和人脸比对功能的模块入口
@@ -4724,6 +4824,7 @@ class NotSupportedError extends IDScannerError {
     }
 }
 
+/* eslint-disable */
 /**
  * @file 主入口文件
  * @description ID Scanner库的主入口点，提供统一的API和模块导出