218 lines
6.5 KiB
Markdown
218 lines
6.5 KiB
Markdown
# KYC (Know Your Customer) 模块
|
||
|
||
## 概述
|
||
|
||
KYC 模块是 AML (Anti-Money Laundering) 系统的核心组成部分，用于对客户进行身份验证和合规检查。系统支持个人(Individual)和企业(Organization)两种实体类型。
|
||
|
||
## 目录结构
|
||
|
||
### 后端 (AML_Backend)
|
||
|
||
```
|
||
modules/iCON.Abp.AML/
|
||
├── src/
|
||
│ ├── iCON.Abp.AML.Application/
|
||
│ │ └── KYC/
|
||
│ │ ├── KYCService.cs # 核心KYC服务
|
||
│ │ ├── HandlerService.cs # 证件处理器服务
|
||
│ │ ├── XiangyunService.cs # 祥云OCR识别服务
|
||
│ │ ├── WebSearchService.cs # 失信人网络搜索
|
||
│ │ ├── CardInfoContentReader.cs # 卡片信息读取
|
||
│ │ ├── CertificateEntityValueFinder.cs
|
||
│ │ ├── ElasticResultJsonReader.cs
|
||
│ │ ├── TranslateMapper.cs
|
||
│ │ ├── MockKYCService.cs # KYC模拟服务(测试用)
|
||
│ │ └── MockHandlerService.cs # 处理器模拟服务
|
||
│ ├── iCON.Abp.AML.Application.Contracts/
|
||
│ │ └── KYCAppLayer/
|
||
│ │ ├── IKYCService.cs # KYC服务接口
|
||
│ │ ├── ScanCertificateDto.cs
|
||
│ │ ├── CertificateHandleDto.cs
|
||
│ │ └── ...
|
||
│ ├── iCON.Abp.AML.Domain/
|
||
│ │ └── KYC/
|
||
│ │ ├── KYCSetting.cs # KYC设置实体
|
||
│ │ ├── KYCCheckResultRecord.cs # KYC检查结果记录
|
||
│ │ ├── CertificateValidateRecord.cs
|
||
│ │ ├── ScanAndValidateSetting.cs
|
||
│ │ └── AttachmentFileSetting.cs
|
||
│ └── iCON.Abp.AML.HttpApi/
|
||
│ └── Controllers/
|
||
│ └── KYCController.cs # API控制器
|
||
└── test/
|
||
└── iCON.Abp.AML.Application.Tests/
|
||
└── TestKYCService_*.cs # KYC单元测试
|
||
```
|
||
|
||
### 前端 (AML_Frontend)
|
||
|
||
```
|
||
AML_Frontend/src/app/
|
||
├── services/
|
||
│ └── aml-kyc.service.ts # KYC服务
|
||
├── util/interfaces/
|
||
│ └── aml-kyc.ts # KYC接口定义
|
||
└── components/
|
||
└── components-viewer/
|
||
└── viewer-customer-info/
|
||
└── components/
|
||
└── kyc-section/ # KYC区域组件
|
||
└── components-form/
|
||
└── form-kyc-org-inv/ # 企业KYC表单
|
||
```
|
||
|
||
## 支持的证件类型
|
||
|
||
证件类型配置位于: `src/iCON.Abp.FX.HttpApi.Host/Data/AML/KYC/CertificateMappings/`
|
||
|
||
### 个人证件 (Individual)
|
||
| 证件类型 | 代码 | 说明 |
|
||
|---------|------|------|
|
||
| 中国居民身份证 | IDCard_CHN | 支持2012版 |
|
||
| 香港居民身份证 | IDCard_HKG | 支持2003/2018版 |
|
||
| 护照 | Passport_* | 支持多国护照 (USA, VNM, CHN, DEU, GBR, TWN等) |
|
||
| 旅行证 | Travel_Permit_* | 往来内地/港澳通行证等 |
|
||
|
||
### 企业证件 (Organization)
|
||
| 证件类型 | 代码 | 说明 |
|
||
|---------|------|------|
|
||
| 香港公司注册证书 | ORG_HKG | BR (Business Registration) |
|
||
| 香港公司CI | ORG_HKG_CI | 公司注册证明书 |
|
||
| 中国企业证件 | ORG_CHN | |
|
||
|
||
## API 接口
|
||
|
||
基础路径: `/api/aml/kyc`
|
||
|
||
### 证件扫描
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/ScanCertificate` | POST | 扫描证件 (v1) |
|
||
| `/ScanCertificateV2` | POST | 扫描证件 (v2) |
|
||
|
||
### 证件处理
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/CertificateHandle` | POST | 证件识别/验证/失信人检测 |
|
||
| `/ValidateCredit` | POST | 征信查询 |
|
||
| `/GetLastValidateCredit` | POST | 获取上次征信结果 |
|
||
|
||
### 设置管理
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/GetScanAndValidateSetting` | POST | 获取扫描/验证设置 |
|
||
| `/UpdateScanAndValidateSetting` | POST | 更新扫描/验证设置 |
|
||
| `/GetAttachmentFileSetting` | POST | 获取附件文件设置 |
|
||
| `/UpdateAttachmentFileSetting` | POST | 更新附件文件设置 |
|
||
|
||
### KYC 结果
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/GetKYCCheckResult` | POST | 获取KYC检查结果 |
|
||
| `/SaveKYCCheckResult` | POST | 保存KYC检查结果 |
|
||
| `/ReCheckKYCStatus` | POST | 重新检查KYC状态 |
|
||
| `/GetReportIndividualKYCCheckResult` | POST | 获取个人KYC报告 |
|
||
| `/GetReportOrganizationKYCCheckResult` | POST | 获取企业KYC报告 |
|
||
|
||
### 外部 API
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/openApi/kycCertificateVerify` | POST | 外部证件验证 |
|
||
| `/openApi/kycQueryCredit` | POST | 外部征信查询 |
|
||
|
||
## 核心流程
|
||
|
||
### 证件扫描 (ScanCertificateV2)
|
||
|
||
```
|
||
用户上传证件图片
|
||
↓
|
||
调用 OCR 服务识别证件内容
|
||
↓
|
||
提取证件信息 (姓名、证件号、有效期等)
|
||
↓
|
||
返回识别结果
|
||
```
|
||
|
||
### 证件处理 (CertificateHandle)
|
||
|
||
```
|
||
传入 EntityInfo + KYCCertificateCode + HandlerCodes
|
||
↓
|
||
根据 HandlerCodes 执行对应处理器:
|
||
- ValidateIDCard: 身份证验证
|
||
- ValidateBR: 商业登记证验证
|
||
- ValidateCredit: 失信人检测
|
||
- ScanCertificate: 证件扫描
|
||
↓
|
||
返回处理结果 (IsValidated, SourceResult 等)
|
||
```
|
||
|
||
### KYC 状态检查
|
||
|
||
```
|
||
获取实体 (Individual/Organization)
|
||
↓
|
||
检查所需证件是否齐全
|
||
↓
|
||
验证证件有效性
|
||
↓
|
||
检测失信人名单
|
||
↓
|
||
返回 KYC 状态评级 (RatingEnum)
|
||
```
|
||
|
||
## 关键服务
|
||
|
||
### KYCService
|
||
核心服务类，负责协调各子服务完成KYC流程。
|
||
|
||
### HandlerService
|
||
证件处理器，根据不同证件类型调用对应的验证服务。
|
||
|
||
### XiangyunService
|
||
调用祥云OCR服务进行证件识别。
|
||
|
||
### WebSearchService
|
||
执行网络搜索检测实体是否在失信人名单中。
|
||
|
||
## 数据模型
|
||
|
||
### KYCSetting
|
||
存储租户的KYC配置，包括：
|
||
- `AttachmentFileSetting`: 附件文件设置
|
||
- `ScanAndValidateSetting`: 扫描验证设置
|
||
|
||
### KYCCheckResultRecord
|
||
存储KYC检查结果记录，关联到具体实体。
|
||
|
||
### CertificateValidateRecord
|
||
存储证件验证记录，包含验证状态和来源结果。
|
||
|
||
## 前端集成
|
||
|
||
```typescript
|
||
import { AmlKycService } from '@/services/aml-kyc.service';
|
||
|
||
constructor(private kycService: AmlKycService) {}
|
||
|
||
// 扫描证件
|
||
this.kycService.scanCertificateV2(params);
|
||
|
||
// 获取KYC结果
|
||
this.kycService.getKYCCheckResult(entityId);
|
||
```
|
||
|
||
## 测试
|
||
|
||
测试文件位于: `modules/iCON.Abp.AML/test/iCON.Abp.AML.Application.Tests/`
|
||
|
||
- `TestKYCService_ScanCertificate*.cs`
|
||
- `TestKYCService_GetAttachmentFileSettingAsync.cs`
|
||
- `TestKYCService_GetScanAndValidateSettingAsync.cs`
|