id-scanner-lib 1.3.3 → 1.5.0

package/dist/types/core/base-module.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @file 基础模块
+ * @description 提供基础模块实现，作为所有功能模块的基类
+ * @module core/base-module
+ */
+import { EventEmitter } from './event-emitter';
+import { Logger } from './logger';
+import { Module } from './module-manager';
+/**
+ * 基础模块类
+ * 提供模块的基本功能和生命周期管理
+ */
+export declare abstract class BaseModule extends EventEmitter implements Module {
+    /** 模块名称 */
+    abstract readonly name: string;
+    /** 模块版本 */
+    readonly version: string;
+    /** 模块是否已初始化 */
+    protected _isInitialized: boolean;
+    /** 日志工具 */
+    protected logger: Logger;
+    /**
+     * 构造函数
+     */
+    constructor();
+    /**
+     * 获取模块是否已初始化
+     */
+    get isInitialized(): boolean;
+    /**
+     * 初始化模块
+     * 子类必须实现此方法
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * 释放模块资源
+     * 子类可以覆盖此方法以添加额外的资源释放逻辑
+     */
+    dispose(): Promise<void>;
+    /**
+     * 检查模块是否已初始化，如果未初始化则抛出错误
+     */
+    protected ensureInitialized(): void;
+}

package/dist/types/core/camera-manager.d.ts

@@ -0,0 +1,258 @@
+/**
+ * @file 摄像头管理器
+ * @description 提供摄像头控制和视频流管理功能
+ * @module core/camera-manager
+ */
+import { EventEmitter } from './event-emitter';
+import { Result } from './result';
+/**
+ * 摄像头设备信息
+ */
+export interface CameraDevice {
+    /** 设备ID */
+    deviceId: string;
+    /** 设备标签（名称） */
+    label: string;
+    /** 是否为前置摄像头 */
+    isFront: boolean;
+}
+/**
+ * 摄像头状态
+ */
+export declare enum CameraStatus {
+    /** 未初始化 */
+    NOT_INITIALIZED = "not_initialized",
+    /** 初始化中 */
+    INITIALIZING = "initializing",
+    /** 就绪 */
+    READY = "ready",
+    /** 活动中 */
+    ACTIVE = "active",
+    /** 暂停 */
+    PAUSED = "paused",
+    /** 已停止 */
+    STOPPED = "stopped",
+    /** 错误状态 */
+    ERROR = "error"
+}
+/**
+ * 摄像头事件
+ */
+export declare enum CameraEvent {
+    /** 摄像头初始化开始 */
+    INITIALIZING = "camera:initializing",
+    /** 摄像头初始化完成 */
+    READY = "camera:ready",
+    /** 摄像头开始 */
+    START = "camera:start",
+    /** 摄像头暂停 */
+    PAUSE = "camera:pause",
+    /** 摄像头恢复 */
+    RESUME = "camera:resume",
+    /** 摄像头停止 */
+    STOP = "camera:stop",
+    /** 摄像头错误 */
+    ERROR = "camera:error",
+    /** 摄像头切换 */
+    SWITCH = "camera:switch",
+    /** 媒体流轨道结束 */
+    TRACK_ENDED = "camera:track:ended",
+    /** 摄像头分辨率变化 */
+    RESOLUTION_CHANGE = "camera:resolution:change",
+    /** 摄像头帧处理 */
+    FRAME = "camera:frame"
+}
+/**
+ * 摄像头初始化选项
+ */
+export interface CameraOptions {
+    /** 目标视频元素 */
+    videoElement?: HTMLVideoElement;
+    /** 自动开始 */
+    autoStart?: boolean;
+    /** 宽度 */
+    width?: number;
+    /** 高度 */
+    height?: number;
+    /** 帧率 */
+    frameRate?: number;
+    /** 摄像头朝向 */
+    facingMode?: 'user' | 'environment';
+    /** 摄像头设备ID */
+    deviceId?: string;
+    /** 启用帧处理 */
+    enableFrameProcessing?: boolean;
+    /** 帧处理间隔(ms) */
+    frameProcessingInterval?: number;
+}
+/**
+ * 摄像头管理类
+ * 提供摄像头控制和视频流管理功能
+ */
+export declare class CameraManager extends EventEmitter {
+    /** 单例实例 */
+    private static instance;
+    /** 日志记录器 */
+    private readonly logger;
+    /** 配置管理器 */
+    private readonly config;
+    /** 视频元素 */
+    private videoElement;
+    /** 媒体流 */
+    private mediaStream;
+    /** 摄像头状态 */
+    private status;
+    /** 可用的摄像头设备列表 */
+    private devices;
+    /** 当前活动的摄像头设备 */
+    private activeDeviceId;
+    /** 帧处理计时器ID */
+    private frameProcessingTimerId;
+    /** 是否启用帧处理 */
+    private frameProcessingEnabled;
+    /** 帧处理间隔(ms) */
+    private frameProcessingInterval;
+    /** 视频准备就绪的Promise */
+    private videoReadyPromise;
+    /** 视频准备就绪的Promise解析函数 */
+    private videoReadyResolver;
+    /** Canvas元素，用于帧处理 */
+    private canvas;
+    /** Canvas 2D上下文 */
+    private canvasCtx;
+    /**
+     * 私有构造函数
+     */
+    private constructor();
+    /**
+     * 获取单例实例
+     */
+    static getInstance(): CameraManager;
+    /**
+     * 初始化摄像头
+     * @param options 初始化选项
+     */
+    init(options?: CameraOptions): Promise<Result<boolean>>;
+    /**
+     * 开始摄像头
+     * @param options 摄像头选项
+     */
+    start(options?: {
+        deviceId?: string;
+        width?: number;
+        height?: number;
+        frameRate?: number;
+        facingMode?: 'user' | 'environment';
+    }): Promise<Result<boolean>>;
+    /**
+     * 暂停摄像头
+     */
+    pause(): boolean;
+    /**
+     * 恢复摄像头
+     */
+    resume(): Promise<boolean>;
+    /**
+     * 停止摄像头
+     */
+    stop(): boolean;
+    /**
+     * 切换摄像头
+     */
+    switchCamera(): Promise<Result<boolean>>;
+    /**
+     * 加载可用的摄像头设备列表
+     */
+    loadDevices(): Promise<CameraDevice[]>;
+    /**
+     * 获取前置摄像头
+     */
+    getFrontCamera(): CameraDevice | undefined;
+    /**
+     * 获取后置摄像头
+     */
+    getBackCamera(): CameraDevice | undefined;
+    /**
+     * 获取所有摄像头设备
+     */
+    getDevices(): CameraDevice[];
+    /**
+     * 获取当前活动的设备ID
+     */
+    getActiveDeviceId(): string | null;
+    /**
+     * 获取当前活动的摄像头设备
+     */
+    getActiveDevice(): CameraDevice | undefined;
+    /**
+     * 获取当前媒体流
+     */
+    getMediaStream(): MediaStream | null;
+    /**
+     * 获取视频元素
+     */
+    getVideoElement(): HTMLVideoElement | null;
+    /**
+     * 设置视频元素
+     * @param element 视频元素
+     */
+    setVideoElement(element: HTMLVideoElement): void;
+    /**
+     * 创建视频元素
+     */
+    private createVideoElement;
+    /**
+     * 捕获当前画面
+     * @param format 图像格式
+     * @param quality 图像质量(0-1)
+     */
+    captureFrame(format?: 'image/png' | 'image/jpeg', quality?: number): string | null;
+    /**
+     * 捕获帧并返回ImageData
+     */
+    captureFrameData(): ImageData | null;
+    /**
+     * 获取当前状态
+     */
+    getStatus(): CameraStatus;
+    /**
+     * 检查摄像头是否活动
+     */
+    isActive(): boolean;
+    /**
+     * 初始化Canvas
+     */
+    private initCanvas;
+    /**
+     * 释放资源
+     */
+    dispose(): void;
+    /**
+     * 停止媒体流并释放轨道
+     */
+    private stopMediaStream;
+    /**
+     * 处理媒体流轨道结束事件
+     */
+    private handleTrackEnded;
+    /**
+     * 创建视频准备就绪的Promise
+     */
+    private createVideoReadyPromise;
+    /**
+     * 等待视频准备就绪
+     */
+    private waitForVideoReady;
+    /**
+     * 开始帧处理
+     */
+    private startFrameProcessing;
+    /**
+     * 停止帧处理
+     */
+    private stopFrameProcessing;
+    /**
+     * 处理当前帧
+     */
+    private processFrame;
+}

package/dist/types/core/config.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @file 配置管理器
+ * @description 提供全局配置管理功能
+ * @module core/config
+ */
+/**
+ * 配置管理器
+ * 负责存储和管理应用程序的配置
+ */
+export declare class ConfigManager {
+    /** 单例实例 */
+    private static instance;
+    /** 配置存储 */
+    private config;
+    /** 配置变更回调 */
+    private changeCallbacks;
+    /**
+     * 私有构造函数
+     */
+    private constructor();
+    /**
+     * 获取单例实例
+     */
+    static getInstance(): ConfigManager;
+    /**
+     * 获取配置值
+     * @param key 配置键，支持点号分隔的路径
+     * @param defaultValue 默认值
+     */
+    get<T = any>(key: string, defaultValue?: T): T;
+    /**
+     * 设置配置值
+     * @param key 配置键，支持点号分隔的路径
+     * @param value 配置值
+     */
+    set<T = any>(key: string, value: T): void;
+    /**
+     * 批量更新配置
+     * @param config 配置对象
+     */
+    updateConfig(config: Record<string, any>): void;
+    /**
+     * 重置为默认配置
+     */
+    reset(): void;
+    /**
+     * 注册配置变更回调
+     * @param key 配置键
+     * @param callback 回调函数
+     */
+    onConfigChange<T = any>(key: string, callback: (value: T, oldValue: T) => void): void;
+    /**
+     * 移除配置变更回调
+     * @param key 配置键
+     * @param callback 特定回调函数，如不提供则移除所有
+     */
+    offConfigChange<T = any>(key: string, callback?: (value: T, oldValue: T) => void): void;
+    /**
+     * 获取嵌套值
+     * @param obj 对象
+     * @param path 路径
+     */
+    private getNestedValue;
+    /**
+     * 设置嵌套值
+     * @param obj 对象
+     * @param path 路径
+     * @param value 值
+     */
+    private setNestedValue;
+    /**
+     * 触发变更回调
+     * @param key 配置键
+     * @param value 新值
+     * @param oldValue 旧值
+     */
+    private triggerChangeCallbacks;
+}
+/**
+ * 模块配置接口
+ * 定义所有模块共享的基础配置属性
+ */
+export interface ModuleConfig {
+    /** 是否启用该模块 */
+    enabled: boolean;
+    /** 其他模块特定配置 */
+    [key: string]: any;
+}

package/dist/types/core/errors.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @file 错误处理模块
+ * @description 定义ID-Scanner-Lib的错误类层次结构
+ * @module core/errors
+ */
+/**
+ * ID-Scanner-Lib 基础错误类
+ * 所有库特定错误的基类
+ */
+export declare class IDScannerError extends Error {
+    /** 错误代码 */
+    code: string;
+    /** 错误原因 */
+    cause?: Error;
+    /**
+     * 构造函数
+     * @param message 错误消息
+     * @param options 错误选项
+     */
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: Error;
+    });
+}
+/**
+ * 初始化错误
+ * 当库初始化失败时抛出
+ */
+export declare class InitializationError extends IDScannerError {
+    constructor(message: string, details?: string);
+}
+/**
+ * 设备错误
+ * 当访问硬件设备(如摄像头)失败时抛出
+ */
+export declare class DeviceError extends IDScannerError {
+    constructor(message: string);
+}
+/**
+ * 摄像头访问错误
+ * 当无法访问或启动摄像头时抛出
+ */
+export declare class CameraAccessError extends IDScannerError {
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: Error;
+    });
+}
+/**
+ * 人脸检测错误
+ * 当人脸检测过程失败时抛出
+ */
+export declare class FaceDetectionError extends IDScannerError {
+    constructor(message: string);
+}
+/**
+ * 人脸比对错误
+ * 当人脸比对过程失败时抛出
+ */
+export declare class FaceComparisonError extends IDScannerError {
+    constructor(message: string);
+}
+/**
+ * 活体检测错误
+ * 当活体检测过程失败时抛出
+ */
+export declare class LivenessDetectionError extends IDScannerError {
+    constructor(message: string);
+}
+/**
+ * OCR识别错误
+ * 当OCR文字识别失败时抛出
+ */
+export declare class OCRProcessingError extends IDScannerError {
+    constructor(message: string);
+}
+/**
+ * 二维码扫描错误
+ * 当二维码扫描失败时抛出
+ */
+export declare class QRScanError extends IDScannerError {
+    constructor(message: string);
+}
+/**
+ * 身份证检测错误
+ * 当身份证检测失败时抛出
+ */
+export declare class IDCardDetectionError extends IDScannerError {
+    constructor(message: string);
+}
+/**
+ * 资源加载错误
+ * 当无法加载必要资源(如模型)时抛出
+ */
+export declare class ResourceLoadError extends IDScannerError {
+    constructor(resource: string, reason: string);
+}
+/**
+ * 参数错误
+ * 当提供的参数无效时抛出
+ */
+export declare class InvalidArgumentError extends IDScannerError {
+    constructor(paramName: string, reason: string);
+}
+/**
+ * 不支持错误
+ * 当尝试使用不支持的功能或当前环境无法使用的功能时抛出
+ */
+export declare class NotSupportedError extends IDScannerError {
+    constructor(feature: string);
+}

package/dist/types/core/event-emitter.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @file 事件发射器
+ * @description 提供基础的事件发射和订阅功能
+ * @module core/event-emitter
+ */
+/**
+ * 事件处理器类型
+ */
+type EventHandler = (data?: any) => void;
+/**
+ * 事件发射器基类
+ * 提供基础的事件发射和订阅功能
+ */
+export declare class EventEmitter {
+    /** 事件处理器映射 */
+    private eventHandlers;
+    /**
+     * 订阅事件
+     * @param eventName 事件名称
+     * @param handler 事件处理器
+     */
+    on(eventName: string, handler: EventHandler): void;
+    /**
+     * 取消订阅事件
+     * @param eventName 事件名称
+     * @param handler 事件处理器，如果不提供则移除该事件的所有处理器
+     */
+    off(eventName: string, handler?: EventHandler): void;
+    /**
+     * 订阅事件，但只触发一次
+     * @param eventName 事件名称
+     * @param handler 事件处理器
+     */
+    once(eventName: string, handler: EventHandler): void;
+    /**
+     * 发射事件
+     * @param eventName 事件名称
+     * @param data 事件数据
+     */
+    emit(eventName: string, data?: any): void;
+    /**
+     * 获取某个事件的处理器数量
+     * @param eventName 事件名称
+     */
+    listenerCount(eventName: string): number;
+    /**
+     * 移除所有事件处理器
+     */
+    removeAllListeners(): void;
+    /**
+     * 获取所有事件名称
+     */
+    eventNames(): string[];
+}
+export {};