id-scanner-lib 1.3.3 → 1.5.0

package/src/modules/id-card/types.ts

@@ -0,0 +1,178 @@
+/**
+ * @file 身份证模块类型定义
+ * @description 身份证模块相关的类型和接口定义
+ * @module modules/id-card/types
+ */
+
+/**
+ * 身份证类型枚举
+ */
+export enum IDCardType {
+  /** 第二代居民身份证正面 */
+  FRONT = 'front',
+  /** 第二代居民身份证背面 */
+  BACK = 'back',
+  /** 第一代居民身份证 */
+  FIRST_GENERATION = 'first_generation',
+  /** 临时身份证 */
+  TEMPORARY = 'temporary',
+  /** 外国人永久居留证 */
+  FOREIGN_PERMANENT = 'foreign_permanent',
+  /** 港澳台居民居住证 */
+  HMT_RESIDENT = 'hmt_resident',
+  /** 未知类型 */
+  UNKNOWN = 'unknown'
+}
+
+/**
+ * 证件边缘信息
+ */
+export interface IDCardEdge {
+  /** 左上角坐标 */
+  topLeft: { x: number; y: number };
+  /** 右上角坐标 */
+  topRight: { x: number; y: number };
+  /** 右下角坐标 */
+  bottomRight: { x: number; y: number };
+  /** 左下角坐标 */
+  bottomLeft: { x: number; y: number };
+}
+
+/**
+ * 身份证信息
+ */
+export interface IDCardInfo {
+  nationality?: string;
+  issuingAuthority?: string;
+  validPeriod?: string;
+  /** 身份证类型 */
+  type?: IDCardType;
+  /** 身份证边缘信息 */
+  edge?: IDCardEdge;
+  /** 姓名 */
+  name?: string;
+  /** 性别 */
+  gender?: string;
+  /** 民族 */
+  ethnicity?: string;
+  /** 出生日期，格式: YYYY-MM-DD */
+  birthDate?: string;
+  /** 地址 */
+  address?: string;
+  /** 身份证号码 */
+  idNumber?: string;
+  /** 签发机关 */
+  issueAuthority?: string;
+  /** 有效期起始日期，格式: YYYY-MM-DD */
+  validFrom?: string;
+  /** 有效期截止日期，格式: YYYY-MM-DD */
+  validTo?: string;
+  /** 相片区域坐标 */
+  photoRegion?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  /** 原始身份证图像 */
+  image?: ImageData;
+  /** 置信度 */
+  confidence?: number;
+  /** 防伪检测结果 */
+  antiFake?: {
+    /** 是否通过防伪检测 */
+    passed: boolean;
+    /** 防伪检测分数 */
+    score: number;
+    /** 防伪特征检测结果 */
+    features?: {
+      /** 荧光油墨 */
+      fluorescent?: boolean;
+      /** 微缩文字 */
+      microtext?: boolean;
+      /** 光变图案 */
+      opticalVariable?: boolean;
+      /** 纹理 */
+      texture?: boolean;
+      /** 暗记 */
+      watermark?: boolean;
+    };
+  };
+}
+
+/**
+ * 身份证模块配置选项
+ */
+export interface IDCardModuleOptions {
+  /** 是否启用模块 */
+  enabled?: boolean;
+  
+  /** 检测器配置 */
+  detector?: {
+    /** 最小置信度 */
+    minConfidence?: number;
+    /** 是否启用OCR识别 */
+    enableOCR?: boolean;
+    /** 是否启用防伪检测 */
+    enableAntiFake?: boolean;
+  };
+  
+  /** OCR处理器配置 */
+  ocr?: {
+    /** 是否使用Web Worker处理OCR */
+    useWorker?: boolean;
+    /** 最大图像尺寸 */
+    maxImageDimension?: number;
+    /** 亮度调整 */
+    brightness?: number;
+    /** 对比度调整 */
+    contrast?: number;
+  };
+  
+  /** 防伪检测配置 */
+  antiFake?: {
+    /** 防伪检测灵敏度 */
+    sensitivity?: number;
+    /** 最小置信度 */
+    minConfidence?: number;
+  };
+}
+
+/**
+ * 身份证验证结果
+ */
+export interface IDCardVerificationResult {
+  /** 是否验证通过 */
+  isValid: boolean;
+  /** 验证分数 */
+  score: number;
+  /** 失败原因 */
+  failureReason?: string;
+  /** 验证详情 */
+  details?: {
+    /** 身份证号码是否有效 */
+    idNumberValid?: boolean;
+    /** 签发日期是否有效 */
+    issueDateValid?: boolean;
+    /** 有效期是否过期 */
+    isExpired?: boolean;
+    /** 防伪检测是否通过 */
+    antiFakePassed?: boolean;
+  };
+}
+
+/**
+ * 图像处理配置选项
+ */
+export interface ImageProcessOptions {
+  /** 是否进行预处理 */
+  preprocess?: boolean;
+  /** 是否校正图像 */
+  correctPerspective?: boolean;
+  /** 是否增强图像 */
+  enhance?: boolean;
+  /** 是否去噪 */
+  denoise?: boolean;
+  /** 是否二值化 */
+  binarize?: boolean;
+} 

package/src/modules/qrcode/index.ts

@@ -0,0 +1,175 @@
+/**
+ * @file 二维码模块入口
+ * @description 提供二维码识别和解析功能的模块入口
+ * @module modules/qrcode
+ */
+
+import { BaseModule } from '../../core/base-module';
+import { QRCodeResult, QRCodeModuleOptions } from './types';
+import { QRCodeScanner } from './qr-code-scanner';
+
+/**
+ * 二维码模块
+ * 提供二维码检测和解析功能
+ */
+export class QRCodeModule extends BaseModule {
+  /** 模块名称 */
+  public readonly name: string = 'qrcode';
+  
+  /** 模块配置 */
+  private options: QRCodeModuleOptions;
+  
+  /** 二维码扫描器 */
+  private scanner: QRCodeScanner;
+  
+  /** 最后一次扫描结果 */
+  private lastScanResult?: QRCodeResult;
+  
+  /**
+   * 构造函数
+   * @param options 模块配置选项
+   */
+  constructor(options: QRCodeModuleOptions = {}) {
+    super();
+    
+    this.options = {
+      enabled: true,
+      scanner: {
+        minConfidence: 0.6,
+        tryMultipleScan: true,
+        returnImage: false,
+        ...options.scanner
+      },
+      imageProcess: {
+        preprocess: true,
+        enhanceContrast: true,
+        threshold: 128,
+        ...options.imageProcess
+      },
+      ...options
+    };
+    
+    // 创建扫描器
+    this.scanner = new QRCodeScanner({
+      minConfidence: this.options.scanner?.minConfidence,
+      returnImage: this.options.scanner?.returnImage,
+      imageProcess: this.options.imageProcess
+    });
+  }
+  
+  /**
+   * 初始化模块
+   */
+  public async initialize(): Promise<void> {
+    if (this._isInitialized) {
+      return;
+    }
+    
+    this.logger.debug(this.name, '初始化二维码模块');
+    
+    try {
+      // 初始化扫描器
+      await this.scanner.initialize();
+      
+      this._isInitialized = true;
+      this.emit('initialized');
+      this.logger.debug(this.name, '二维码模块初始化完成');
+    } catch (error) {
+      this.logger.error(this.name, '二维码模块初始化失败', error as Error);
+      throw new Error(`二维码模块初始化失败: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  
+  /**
+   * 扫描图像中的二维码
+   * @param image 图像源
+   * @returns 二维码扫描结果
+   */
+  public async scan(
+    image: ImageData | HTMLImageElement | HTMLCanvasElement
+  ): Promise<QRCodeResult | undefined> {
+    this.ensureInitialized();
+    
+    try {
+      // 扫描二维码
+      const scanResult = await this.scanner.scan(image);
+      
+      if (scanResult) {
+        // 保存最后一次扫描结果
+        this.lastScanResult = scanResult;
+        
+        // 触发事件
+        this.emit('qrcode:scanned', { result: scanResult });
+      }
+      
+      return scanResult;
+    } catch (error) {
+      this.logger.error(this.name, '二维码扫描失败', error as Error);
+      throw new Error(`二维码扫描失败: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  
+  /**
+   * 获取最后一次扫描结果
+   */
+  public getLastScanResult(): QRCodeResult | undefined {
+    return this.lastScanResult;
+  }
+  
+  /**
+   * 解析二维码数据
+   * @param data 二维码数据
+   * @returns 解析后的数据对象
+   */
+  public parseQRCodeData(data: string): Record<string, any> | string {
+    try {
+      // 尝试解析为JSON
+      return JSON.parse(data);
+    } catch {
+      // 不是JSON，尝试解析为URL参数
+      if (data.includes('=')) {
+        try {
+          const params: Record<string, string> = {};
+          const urlParams = new URLSearchParams(data.includes('?') ? data.split('?')[1] : data);
+          
+          urlParams.forEach((value, key) => {
+            params[key] = value;
+          });
+          
+          return params;
+        } catch {
+          // 解析URL参数失败，返回原始字符串
+          return data;
+        }
+      }
+      
+      // 返回原始字符串
+      return data;
+    }
+  }
+  
+  /**
+   * 释放模块资源
+   */
+  public async dispose(): Promise<void> {
+    if (!this._isInitialized) {
+      return;
+    }
+    
+    this.logger.debug(this.name, '释放二维码模块资源');
+    
+    try {
+      // 释放扫描器资源
+      await this.scanner.dispose();
+      
+      // 调用基类的dispose方法
+      await super.dispose();
+    } catch (error) {
+      this.logger.error(this.name, '二维码模块资源释放失败', error as Error);
+      throw new Error(`二维码模块资源释放失败: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}
+
+// 导出类型
+export * from './types'; 

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

@@ -0,0 +1,230 @@
+/**
+ * @file 二维码扫描器
+ * @description 提供二维码检测和解析功能
+ * @module modules/qrcode/qr-code-scanner
+ */
+
+import { EventEmitter } from '../../core/event-emitter';
+import { Logger } from '../../core/logger';
+import { QRCodeResult } from './types';
+import jsQR from 'jsqr';
+
+/**
+ * 二维码扫描器配置选项
+ */
+export interface QRCodeScannerOptions {
+  /** 最小置信度 */
+  minConfidence?: number;
+  /** 是否返回原始图像 */
+  returnImage?: boolean;
+  /** 图像处理配置 */
+  imageProcess?: {
+    /** 是否进行预处理 */
+    preprocess?: boolean;
+    /** 是否增强对比度 */
+    enhanceContrast?: boolean;
+    /** 二值化阈值 */
+    threshold?: number;
+  };
+}
+
+/**
+ * 二维码扫描器类
+ */
+export class QRCodeScanner extends EventEmitter {
+  private options: QRCodeScannerOptions;
+  private logger: Logger;
+  private initialized: boolean = false;
+
+  /**
+   * 构造函数
+   * @param options 配置选项
+   */
+  constructor(options: QRCodeScannerOptions = {}) {
+    super();
+    this.options = {
+      minConfidence: 0.6,
+      returnImage: false,
+      imageProcess: {
+        preprocess: true,
+        enhanceContrast: true,
+        threshold: 128,
+        ...options.imageProcess
+      },
+      ...options
+    };
+    this.logger = Logger.getInstance();
+  }
+
+  /**
+   * 初始化扫描器
+   */
+  public async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    this.logger.debug('QRCodeScanner', '初始化二维码扫描器');
+    
+    // 验证jsQR是否可用
+    if (typeof jsQR !== 'function') {
+      throw new Error('jsQR库未加载，请确保已安装jsqr依赖');
+    }
+
+    this.initialized = true;
+    this.logger.debug('QRCodeScanner', '二维码扫描器初始化完成');
+  }
+
+  /**
+   * 扫描图像中的二维码
+   * @param image 图像源
+   * @returns 二维码扫描结果
+   */
+  public async scan(
+    image: ImageData | HTMLImageElement | HTMLCanvasElement
+  ): Promise<QRCodeResult | undefined> {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+
+    // 将输入转换为ImageData
+    const imageData = this.getImageData(image);
+    
+    // 图像预处理
+    const processedImage = this.options.imageProcess?.preprocess
+      ? this.preprocessImage(imageData)
+      : imageData;
+
+    // 使用jsQR进行扫描
+    const code = jsQR(
+      processedImage.data,
+      processedImage.width,
+      processedImage.height,
+      {
+        inversionAttempts: 'dontInvert'
+      }
+    );
+
+    if (!code) {
+      return undefined;
+    }
+
+    // 构建结果
+    const result: QRCodeResult = {
+      data: code.data,
+      boundingBox: {
+        topLeft: code.location.topLeftCorner,
+        topRight: code.location.topRightCorner,
+        bottomRight: code.location.bottomRightCorner,
+        bottomLeft: code.location.bottomLeftCorner
+      },
+      center: {
+        x: Math.round((code.location.topLeftCorner.x + code.location.bottomRightCorner.x) / 2),
+        y: Math.round((code.location.topLeftCorner.y + code.location.bottomRightCorner.y) / 2)
+      },
+      confidence: 1.0 // jsQR不提供置信度，默认为1.0
+    };
+
+    // 如果需要返回原始图像
+    if (this.options.returnImage) {
+      result.image = imageData;
+    }
+
+    this.logger.debug('QRCodeScanner', `扫描到二维码: ${result.data.substring(0, 20)}${result.data.length > 20 ? '...' : ''}`);
+    
+    return result;
+  }
+
+  /**
+   * 将各种图像源转换为ImageData
+   * @param image 图像源
+   * @returns ImageData
+   */
+  private getImageData(
+    image: ImageData | HTMLImageElement | HTMLCanvasElement
+  ): ImageData {
+    // 如果已经是ImageData，直接返回
+    if (image instanceof ImageData) {
+      return image;
+    }
+
+    // 创建canvas并获取2D上下文
+    const canvas = document.createElement('canvas');
+    const ctx = canvas.getContext('2d');
+
+    if (!ctx) {
+      throw new Error('无法创建Canvas上下文');
+    }
+
+    // 设置canvas尺寸
+    canvas.width = image.width;
+    canvas.height = image.height;
+
+    // 绘制图像
+    ctx.drawImage(image, 0, 0);
+
+    // 获取ImageData
+    return ctx.getImageData(0, 0, canvas.width, canvas.height);
+  }
+
+  /**
+   * 图像预处理
+   * @param imageData 原始图像数据
+   * @returns 处理后的图像数据
+   */
+  private preprocessImage(imageData: ImageData): ImageData {
+    // 创建canvas并获取2D上下文
+    const canvas = document.createElement('canvas');
+    const ctx = canvas.getContext('2d');
+
+    if (!ctx) {
+      return imageData;
+    }
+
+    // 设置canvas尺寸
+    canvas.width = imageData.width;
+    canvas.height = imageData.height;
+
+    // 绘制原始图像
+    ctx.putImageData(imageData, 0, 0);
+
+    // 增强对比度
+    if (this.options.imageProcess?.enhanceContrast) {
+      ctx.filter = 'contrast(150%)';
+      ctx.drawImage(canvas, 0, 0);
+      ctx.filter = 'none';
+    }
+
+    // 应用二值化
+    const threshold = this.options.imageProcess?.threshold || 128;
+    const processedData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+    const data = processedData.data;
+
+    for (let i = 0; i < data.length; i += 4) {
+      // 计算灰度值
+      const gray = 0.299 * data[i] + 0.587 * data[i + 1] + 0.114 * data[i + 2];
+      // 二值化
+      const value = gray < threshold ? 0 : 255;
+      data[i] = data[i + 1] = data[i + 2] = value;
+    }
+
+    return processedData;
+  }
+
+  /**
+   * 释放资源
+   */
+  public async dispose(): Promise<void> {
+    if (!this.initialized) {
+      return;
+    }
+
+    this.logger.debug('QRCodeScanner', '释放二维码扫描器资源');
+    
+    // 移除所有事件监听器
+    this.removeAllListeners();
+    
+    this.initialized = false;
+    this.logger.debug('QRCodeScanner', '二维码扫描器资源已释放');
+  }
+} 

package/src/modules/qrcode/types.ts

@@ -0,0 +1,65 @@
+/**
+ * @file 二维码模块类型定义
+ * @description 二维码模块相关的类型和接口定义
+ * @module modules/qrcode/types
+ */
+
+/**
+ * 二维码检测结果
+ */
+export interface QRCodeResult {
+  /** 二维码内容 */
+  data: string;
+  
+  /** 二维码类型 */
+  type?: string;
+  
+  /** 二维码边界框 */
+  boundingBox: {
+    topLeft: { x: number; y: number };
+    topRight: { x: number; y: number };
+    bottomRight: { x: number; y: number };
+    bottomLeft: { x: number; y: number };
+  };
+  
+  /** 二维码中心点 */
+  center: { x: number; y: number };
+  
+  /** 原始图像 */
+  image?: ImageData;
+  
+  /** 置信度 */
+  confidence?: number;
+}
+
+/**
+ * 二维码模块选项
+ */
+export interface QRCodeModuleOptions {
+  /** 是否启用模块 */
+  enabled?: boolean;
+  
+  /** 二维码扫描配置 */
+  scanner?: {
+    /** 最小置信度 */
+    minConfidence?: number;
+    
+    /** 是否尝试多次扫描 */
+    tryMultipleScan?: boolean;
+    
+    /** 是否返回原始图像 */
+    returnImage?: boolean;
+  };
+  
+  /** 图像处理配置 */
+  imageProcess?: {
+    /** 是否进行预处理 */
+    preprocess?: boolean;
+    
+    /** 是否增强对比度 */
+    enhanceContrast?: boolean;
+    
+    /** 二值化阈值 */
+    threshold?: number;
+  };
+}