docs(kyc): add scanner integration analysis and SDK replacement guidance
- Document frontend scanner architecture and PassportReader.js role - Detail key methods, callbacks, and message protocol formats - Analyze impact of replacing scanner SDK with three proposed solutions - Recommend ideal approach preserving PassportReader.js interface - List relevant frontend and backend file paths for integration - Provide version and creation date info for the documentation filemain
parent
07ad350566
commit
376cb3a15f
|
|
@ -0,0 +1,132 @@
|
||||||
|
# 扫描仪集成分析
|
||||||
|
|
||||||
|
## 前端扫描仪架构
|
||||||
|
|
||||||
|
```
|
||||||
|
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` | 实时消息 |
|
||||||
|
|
||||||
|
### 消息协议格式
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// 请求格式
|
||||||
|
{ 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
|
||||||
Loading…
Reference in New Issue