id-scanner-lib 1.5.0 → 1.6.2

package/src/modules/qrcode/types.ts

@@ -5,16 +5,65 @@
  */
 
 /**
- * 二维码检测结果
+ * 支持的条码格式
+ */
+export enum BarcodeFormat {
+  /** QR码 */
+  QR_CODE = 'qrcode',
+  /** Code 128 */
+  CODE_128 = 'code_128',
+  /** Code 39 */
+  CODE_39 = 'code_39',
+  /** Code 93 */
+  CODE_93 = 'code_93',
+  /** EAN-13 */
+  EAN_13 = 'ean_13',
+  /** EAN-8 */
+  EAN_8 = 'ean_8',
+  /** UPC-A */
+  UPC_A = 'upc_a',
+  /** UPC-E */
+  UPC_E = 'upc_e',
+  /** ITF */
+  ITF = 'itf',
+  /** PDF417 */
+  PDF_417 = 'pdf_417',
+  /** DataMatrix */
+  DATA_MATRIX = 'data_matrix',
+  /** Aztec */
+  AZTEC = 'aztec',
+  /** Codabar */
+  CODABAR = 'codabar',
+  /** Industrial 2 of 5 */
+  INDUSTRIAL_2_OF_5 = 'industrial_2_of_5',
+  /** QR Code Micro */
+  QR_CODE_MICRO = 'qr_code_micro'
+}
+
+/**
+ * 默认支持的格式
+ */
+export const DEFAULT_FORMATS = [
+  BarcodeFormat.QR_CODE,
+  BarcodeFormat.CODE_128,
+  BarcodeFormat.CODE_39,
+  BarcodeFormat.EAN_13
+];
+
+/**
+ * 二维码/条码检测结果
  */
 export interface QRCodeResult {
-  /** 二维码内容 */
+  /** 条码内容 */
   data: string;
   
-  /** 二维码类型 */
+  /** 条码格式 */
+  barcodeFormat: BarcodeFormat;
+  
+  /** 条码类型 (兼容旧版) */
   type?: string;
   
-  /** 二维码边界框 */
+  /** 条码边界框 */
   boundingBox: {
     topLeft: { x: number; y: number };
     topRight: { x: number; y: number };
@@ -22,7 +71,7 @@ export interface QRCodeResult {
     bottomLeft: { x: number; y: number };
   };
   
-  /** 二维码中心点 */
+  /** 条码中心点 */
   center: { x: number; y: number };
   
   /** 原始图像 */
@@ -30,6 +79,12 @@ export interface QRCodeResult {
   
   /** 置信度 */
   confidence?: number;
+  
+  /** 原始数据 (解码后的字节) */
+  rawBytes?: Uint8Array;
+  
+  /** 错误校正级别 (QR码) */
+  errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H';
 }
 
 /**
@@ -39,7 +94,7 @@ export interface QRCodeModuleOptions {
   /** 是否启用模块 */
   enabled?: boolean;
   
-  /** 二维码扫描配置 */
+  /** 扫描配置 */
   scanner?: {
     /** 最小置信度 */
     minConfidence?: number;
@@ -49,6 +104,12 @@ export interface QRCodeModuleOptions {
     
     /** 是否返回原始图像 */
     returnImage?: boolean;
+    
+    /** 扫描频率 (ms) */
+    scanFrequency?: number;
+    
+    /** 启用扫描的格式 */
+    formats?: BarcodeFormat[];
   };
   
   /** 图像处理配置 */
@@ -61,5 +122,48 @@ export interface QRCodeModuleOptions {
     
     /** 二值化阈值 */
     threshold?: number;
+    
+    /** 是否进行降噪 */
+    denoise?: boolean;
   };
-} 
+}
+
+/**
+ * 实时扫描选项
+ */
+export interface RealtimeScanOptions {
+  /** 视频元素 */
+  video: HTMLVideoElement;
+  
+  /** 扫描回调 */
+  onResult: (result: QRCodeResult) => void;
+  
+  /** 错误回调 */
+  onError?: (error: Error) => void;
+  
+  /** 扫描频率 (ms) */
+  frequency?: number;
+  
+  /** 是否连续扫描 */
+  continuous?: boolean;
+}
+
+/**
+ * 扫描统计信息
+ */
+export interface ScanStats {
+  /** 总扫描次数 */
+  totalScans: number;
+  
+  /** 成功次数 */
+  successfulScans: number;
+  
+  /** 失败次数 */
+  failedScans: number;
+  
+  /** 平均处理时间 (ms) */
+  avgProcessingTime: number;
+  
+  /** 成功率 */
+  successRate: number;
+}

package/src/types/common.test.ts

@@ -0,0 +1,99 @@
+/**
+ * @file 通用类型测试
+ * @description 测试通用类型
+ */
+
+import {
+  Rectangle,
+  Point,
+  Size,
+  ImageSource,
+  ModuleState,
+  CancellablePromise,
+  KeyValuePair
+} from './common';
+
+describe('Common Types', () => {
+  describe('Rectangle', () => {
+    it('should create rectangle', () => {
+      const rect: Rectangle = {
+        x: 10,
+        y: 20,
+        width: 100,
+        height: 50
+      };
+
+      expect(rect.x).toBe(10);
+      expect(rect.y).toBe(20);
+      expect(rect.width).toBe(100);
+      expect(rect.height).toBe(50);
+    });
+  });
+
+  describe('Point', () => {
+    it('should create point', () => {
+      const point: Point = {
+        x: 50,
+        y: 100
+      };
+
+      expect(point.x).toBe(50);
+      expect(point.y).toBe(100);
+    });
+  });
+
+  describe('Size', () => {
+    it('should create size', () => {
+      const size: Size = {
+        width: 1920,
+        height: 1080
+      };
+
+      expect(size.width).toBe(1920);
+      expect(size.height).toBe(1080);
+    });
+  });
+
+  describe('ModuleState', () => {
+    it('should have correct states', () => {
+      expect(ModuleState.UNINITIALIZED).toBe('uninitialized');
+      expect(ModuleState.INITIALIZING).toBe('initializing');
+      expect(ModuleState.INITIALIZED).toBe('initialized');
+      expect(ModuleState.RUNNING).toBe('running');
+      expect(ModuleState.PAUSED).toBe('paused');
+      expect(ModuleState.STOPPED).toBe('stopped');
+      expect(ModuleState.ERROR).toBe('error');
+      expect(ModuleState.DESTROYED).toBe('destroyed');
+    });
+  });
+
+  describe('CancellablePromise', () => {
+    it('should create cancellable promise', () => {
+      let cancelled = false;
+      
+      const cp: CancellablePromise<string> = {
+        promise: new Promise((resolve) => {
+          setTimeout(() => resolve('done'), 100);
+        }),
+        cancel: () => {
+          cancelled = true;
+        }
+      };
+
+      expect(cp.promise).toBeInstanceOf(Promise);
+      expect(typeof cp.cancel).toBe('function');
+    });
+  });
+
+  describe('KeyValuePair', () => {
+    it('should create key value pair', () => {
+      const pair: KeyValuePair<string, number> = {
+        key: 'age',
+        value: 25
+      };
+
+      expect(pair.key).toBe('age');
+      expect(pair.value).toBe(25);
+    });
+  });
+});

package/src/types/common.ts

@@ -0,0 +1,166 @@
+/**
+ * @file 通用类型定义
+ * @description 提供项目通用的类型定义
+ * @module types/common
+ */
+
+/**
+ * 基础结果接口
+ */
+export interface BaseResult<T = unknown> {
+  /** 是否成功 */
+  success: boolean;
+  /** 结果数据 */
+  data?: T;
+  /** 错误信息 */
+  error?: string;
+  /** 错误码 */
+  code?: string;
+}
+
+/**
+ * 分页结果接口
+ */
+export interface PaginatedResult<T> {
+  /** 数据列表 */
+  items: T[];
+  /** 总数 */
+  total: number;
+  /** 当前页码 */
+  page: number;
+  /** 每页大小 */
+  pageSize: number;
+  /** 是否有下一页 */
+  hasMore: boolean;
+}
+
+/**
+ * 通用配置接口
+ */
+export interface GenericConfig {
+  /** 启用状态 */
+  enabled?: boolean;
+  /** 调试模式 */
+  debug?: boolean;
+  /** 超时时间(ms) */
+  timeout?: number;
+  /** 重试次数 */
+  retries?: number;
+}
+
+/**
+ * 回调函数类型
+ */
+export type Callback<T = unknown> = (error?: Error, result?: T) => void;
+
+/**
+ * 异步回调函数类型
+ */
+export type AsyncCallback<T = unknown> = (error?: Error, result?: T) => Promise<void>;
+
+/**
+ * 可取消的 Promise
+ */
+export interface CancellablePromise<T> {
+  /** Promise 对象 */
+  promise: Promise<T>;
+  /** 取消函数 */
+  cancel: () => void;
+}
+
+/**
+ * 事件监听器类型
+ */
+export type EventListener<T = unknown> = (event: T) => void;
+
+/**
+ * 生命周期钩子
+ */
+export interface LifecycleHooks {
+  /** 初始化前 */
+  onBeforeInit?: () => void | Promise<void>;
+  /** 初始化后 */
+  onAfterInit?: () => void | Promise<void>;
+  /** 销毁前 */
+  onBeforeDestroy?: () => void | Promise<void>;
+  /** 销毁后 */
+  onAfterDestroy?: () => void | Promise<void>;
+}
+
+/**
+ * 模块状态
+ */
+export enum ModuleState {
+  /** 未初始化 */
+  UNINITIALIZED = 'uninitialized',
+  /** 初始化中 */
+  INITIALIZING = 'initializing',
+  /** 已初始化 */
+  INITIALIZED = 'initialized',
+  /** 运行中 */
+  RUNNING = 'running',
+  /** 已暂停 */
+  PAUSED = 'paused',
+  /** 已停止 */
+  STOPPED = 'stopped',
+  /** 错误 */
+  ERROR = 'error',
+  /** 已销毁 */
+  DESTROYED = 'destroyed'
+}
+
+/**
+ * 检测结果基类
+ */
+export interface DetectionResultBase {
+  /** 置信度 (0-1) */
+  confidence: number;
+  /** 边界框 */
+  boundingBox?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  /** 时间戳 */
+  timestamp: number;
+}
+
+/**
+ * 图像源类型
+ */
+export type ImageSource = string | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | ImageData | Blob;
+
+/**
+ * 矩形区域
+ */
+export interface Rectangle {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * 点
+ */
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/**
+ * 尺寸
+ */
+export interface Size {
+  width: number;
+  height: number;
+}
+
+/**
+ * 键值对
+ */
+export interface KeyValuePair<K = string, V = unknown> {
+  key: K;
+  value: V;
+}

package/src/utils/camera.test.ts

@@ -0,0 +1,30 @@
+/**
+ * @file 摄像头工具测试
+ * @description 测试摄像头相关工具
+ */
+
+import { getMediaConstraints } from './index';
+
+describe('Camera Utils', () => {
+  describe('getMediaConstraints', () => {
+    it('should return default constraints', () => {
+      const constraints = getMediaConstraints();
+      
+      expect(constraints).toBeDefined();
+      expect(constraints.audio).toBe(false);
+      expect(constraints.video).toBeDefined();
+    });
+
+    it('should accept custom parameters', () => {
+      const constraints = getMediaConstraints(1920, 1080, 'user', 60);
+      
+      expect(constraints.video).toBeDefined();
+    });
+
+    it('should handle partial parameters', () => {
+      const constraints = getMediaConstraints(640);
+      
+      expect(constraints.video).toBeDefined();
+    });
+  });
+});

package/src/utils/camera.ts

@@ -4,6 +4,8 @@
  * @module Camera
  */
 
+import { Logger } from '../core/logger';
+
 /**
  * 相机配置选项接口
  * 
@@ -113,7 +115,8 @@ export class Camera {
         });
       }
     } catch (error) {
-      console.error('无法访问摄像头:', error);
+      const logger = Logger.getInstance();
+      logger.error('Camera', '无法访问摄像头', error instanceof Error ? error : undefined);
       throw new Error('无法访问摄像头。请确保已授予摄像头访问权限，并且摄像头未被其他应用程序占用。');
     }
   }

package/src/utils/error-handler.test.ts

@@ -0,0 +1,137 @@
+/**
+ * @file 错误处理工具测试
+ * @description 测试 ErrorHandler
+ */
+
+import { ErrorHandler, ErrorSeverity } from './error-handler';
+
+describe('ErrorHandler', () => {
+  // Mock Logger
+  const mockLogger = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn()
+  };
+
+  beforeAll(() => {
+    // Replace logger with mock
+    (ErrorHandler as any).logger = mockLogger;
+  });
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should handle error with ERROR severity', () => {
+    ErrorHandler.handle('TestModule', 'Test error', new Error('test error'));
+    
+    expect(mockLogger.error).toHaveBeenCalledWith(
+      'TestModule',
+      'Test error',
+      expect.any(Error)
+    );
+  });
+
+  it('should handle error with WARN severity', () => {
+    ErrorHandler.handle('TestModule', 'Warning message', null, ErrorSeverity.WARN);
+    
+    expect(mockLogger.warn).toHaveBeenCalledWith(
+      'TestModule',
+      'Warning message',
+      undefined
+    );
+  });
+
+  it('should handle error with INFO severity', () => {
+    ErrorHandler.handle('TestModule', 'Info message', null, ErrorSeverity.INFO);
+    
+    expect(mockLogger.info).toHaveBeenCalledWith(
+      'TestModule',
+      'Info message',
+      undefined
+    );
+  });
+
+  it('should handle error with DEBUG severity', () => {
+    ErrorHandler.handle('TestModule', 'Debug message', null, ErrorSeverity.DEBUG);
+    
+    expect(mockLogger.debug).toHaveBeenCalledWith(
+      'TestModule',
+      'Debug message',
+      undefined
+    );
+  });
+
+  it('should convert string error to Error object', () => {
+    ErrorHandler.handle('TestModule', 'Test error', 'string error');
+    
+    expect(mockLogger.error).toHaveBeenCalledWith(
+      'TestModule',
+      'Test error',
+      expect.any(Error)
+    );
+  });
+
+  it('should convert unknown error to Error object', () => {
+    ErrorHandler.handle('TestModule', 'Test error', { code: 123 });
+    
+    expect(mockLogger.error).toHaveBeenCalledWith(
+      'TestModule',
+      'Test error',
+      expect.any(Error)
+    );
+  });
+
+  describe('asyncHandler', () => {
+    it('should create error handler function', () => {
+      const handler = ErrorHandler.asyncHandler('TestModule', 'Operation failed');
+      
+      handler(new Error('test'));
+      
+      expect(mockLogger.error).toHaveBeenCalledWith(
+        'TestModule',
+        'Operation failed',
+        expect.any(Error)
+      );
+    });
+  });
+
+  describe('safeExecute', () => {
+    it('should return result on success', async () => {
+      const fn = async () => 'success';
+      const result = await ErrorHandler.safeExecute(fn, 'TestModule', 'fallback');
+      
+      expect(result).toBe('success');
+    });
+
+    it('should return fallback on error', async () => {
+      const fn = async () => {
+        throw new Error('error');
+      };
+      const result = await ErrorHandler.safeExecute(fn, 'TestModule', 'fallback');
+      
+      expect(result).toBe('fallback');
+      expect(mockLogger.error).toHaveBeenCalled();
+    });
+  });
+
+  describe('safeExecuteSync', () => {
+    it('should return result on success', () => {
+      const fn = () => 'success';
+      const result = ErrorHandler.safeExecuteSync(fn, 'TestModule', 'fallback');
+      
+      expect(result).toBe('success');
+    });
+
+    it('should return fallback on error', () => {
+      const fn = () => {
+        throw new Error('error');
+      };
+      const result = ErrorHandler.safeExecuteSync(fn, 'TestModule', 'fallback');
+      
+      expect(result).toBe('fallback');
+      expect(mockLogger.error).toHaveBeenCalled();
+    });
+  });
+});