AML/docs/KYC/Scanner_Integration.md

扫描仪集成分析

前端扫描仪架构

ViewerScanModalComponent (UI组件)
    ↓
PassportService (扫描服务层)
    ↓
PassportReader.js (扫描仪SDK/驱动 - 位于 assets/js/)
    ↓
WebSocket 连接 (ws://127.0.0.1:90)

PassportReader.js 实现分析

当前架构

前端                    WebSocket服务器 (127.0.0.1:90)     扫描仪硬件
  │                            │                            │
  │── connect() ──────────────>│                            │
  │<── onConnected() ──────────│                            │
  │                            │                            │
  │── setParameter(VIZ,true) ──>│                            │
  │── setParameter(RFID,true) ─>│                            │
  │                            │                            │
  │── triggerManualRead() ───>│                            │
  │<── onTextResult ───────────│<── 护照文字数据 ────────────  │
  │<── onImageResult ──────────│<── 护照图片 ──────────────  │

关键接口

方法 (Methods)

方法	说明
connect()	建立WebSocket连接
disconnect()	断开连接
setParameter(param, value)	设置参数 (VIZ/RFID/WantFieldSource)
getDeviceInfo(type)	获取设备状态
triggerManualRead()	触发读取
getOnLineStatus(callback)	检查设备在线状态
isConnected()	检查连接状态

回调 (Callbacks)

回调	触发时机
onConnected	WebSocket连接成功
onDisconnected	WebSocket断开
onError	连接或通信错误
onTextResult	收到文字识别结果
onImageResult	收到图片
onDeviceInfo	设备信息响应
onRealtimeMessage	实时消息

消息协议格式

// 请求格式
{ Type: "Request", Command: "Get/Set", Operand: "OnLineStatus", Param: "True/False" }
{ Type: "Notify", Command: "Trigger", Operand: "ManualRecog", Param: "2" }

// 响应格式
{ Type: "Notify", Operand: "CardContentText", Param: { ... } }  // 文字结果
{ Type: "Notify", Operand: "Images", Param: { ... } }              // 图片结果
{ Type: "Reply", Command: "Get", Operand: "OnLineStatus", Succeeded: "Y/N" }

替换扫描仪的影响分析

方案一：新SDK使用相同协议 (WebSocket + JSON)

改动范围: 仅 PassportReader.js

• 保持 PassportReader.js 接口不变
• 仅替换内部实现
• 上层代码 (passport.service.ts, viewer-scan-modal.component.ts) 无需修改
• 后端代码 无需修改

方案二：新SDK使用不同协议

改动范围:

文件	改动程度	说明
assets/js/PassportReader.js	完全重写	新SDK驱动
passport.service.ts	可能需要调整	适配新的调用方式
viewer-scan-modal.component.ts	大概率不变	UI逻辑不变
后端	大概率不变	只接收前端传来的数据

方案三：新SDK使用ActiveX/NPAPI等浏览器插件

需要考虑:

• 前端技术方案是否支持
• 浏览器兼容性
• 安全策略限制

建议方案

最理想情况是让新SDK适配现有的 PassportService 接口模式：

新SDK → 适配层 → PassportReader.js (现有接口不变) → PassportService → ViewerScanModalComponent

这样前端只需:

1. 替换 PassportReader.js (新SDK)
2. 重写适配逻辑，让它映射到现有回调接口
3. passport.service.ts 和 UI组件不用改

相关文件路径

前端

文件	说明
AML_Frontend/src/assets/js/PassportReader.js	扫描仪SDK (核心)
AML_Frontend/src/app/components/components-viewer/viewer-scan-modal/viewer-scan-modal.component.ts	扫描弹窗UI
AML_Frontend/src/app/components/components-viewer/viewer-scan-modal/services/passport.service.ts	扫描服务层
AML_Frontend/src/app/modules/configuration/components/set-scan/set-scan.component.ts	扫描设置组件

后端

后端不直接和扫描仪交互，接收的是前端传来的OCR结果和图片数据。

版本信息

文档版本: v1.0 创建日期: 2026-04-30