312 lines
9.1 KiB
Markdown
312 lines
9.1 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
|
||
│ │ ├── JsonContentReader.cs # JSON内容读取器
|
||
│ │ ├── RealHttpClient.cs # HTTP客户端实现
|
||
│ │ ├── XiangyunCartTypeCodeConverter.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表单
|
||
```
|
||
|
||
## 支持的证件类型
|
||
|
||
证件类型配置位于: `AML_Backend/src/iCON.Abp.FX.HttpApi.Host/appsettings.json` 的 `CertificateMappings` 节点
|
||
|
||
### 配置结构示例
|
||
|
||
```json
|
||
{
|
||
"AMLConfig": {
|
||
"CertificateMappings": [
|
||
{
|
||
"CertificateCode": "IDCard_CHN",
|
||
"EntityType": "Individual",
|
||
"Description": "中国居民身份证"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 个人证件 (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报告 |
|
||
|
||
### 证件记录管理
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/GetValidateCertificateRecords` | POST | 获取证件验证记录 |
|
||
| `/BindValidateCertificateRecords` | POST | 绑定证件验证记录 |
|
||
|
||
### 证件类型查询
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/GetIndividualSupportCertificate` | POST | 获取个人支持的证件类型 |
|
||
| `/GetOrganizationSupportCertificate` | POST | 获取企业支持的证件类型 |
|
||
|
||
### 附件验证
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/ValidateAttachment` | POST | 验证附件 |
|
||
|
||
### 外部 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
|
||
执行网络搜索检测实体是否在失信人名单中。
|
||
|
||
### JsonContentReader
|
||
JSON内容读取器，用于解析各种JSON格式的响应数据。
|
||
|
||
### RealHttpClient
|
||
HTTP客户端实现，用于与外部服务进行通信。
|
||
|
||
### XiangyunCartTypeCodeConverter
|
||
祥云证件类型转换器，用于转换祥云OCR服务的证件类型代码。
|
||
|
||
## 证件映射实现
|
||
|
||
证件类型映射通过 `CertificateMappings.cs` 类实现，该类定义了系统支持的所有证件类型及其属性：
|
||
|
||
- **CertificateCode**: 证件类型代码
|
||
- **EntityType**: 实体类型 (Individual/Organization)
|
||
- **Description**: 证件描述
|
||
- **SupportedCountries**: 支持的国家/地区
|
||
- **ValidationRules**: 验证规则
|
||
|
||
## 数据模型
|
||
|
||
### 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);
|
||
```
|
||
|
||
## 版本信息
|
||
|
||
**文档版本**: v1.1
|
||
**最后更新**: 2026-04-30
|
||
**适用系统版本**: AML Backend v2.x
|
||
|
||
## 更新日志
|
||
|
||
### v1.1 (2026-04-30)
|
||
- 修正证件映射配置文件路径
|
||
- 补充完整的KYC服务文件列表
|
||
- 添加证件映射实现说明
|
||
- 完善API接口分类
|
||
- 更新测试文件列表
|
||
- 添加配置结构示例
|
||
|
||
### v1.0 (初始版本)
|
||
- 基础KYC模块文档
|
||
- 核心功能说明
|
||
- API接口定义
|
||
- 数据模型描述
|
||
|
||
## 测试
|
||
|
||
测试文件位于: `modules/iCON.Abp.AML/test/iCON.Abp.AML.Application.Tests/`
|
||
|
||
### 测试文件列表
|
||
|
||
- `TestKYCService_Base.cs` - KYC测试基类
|
||
- `TestKYCService_ScanCertificate.cs` - 证件扫描测试(v1)
|
||
- `TestKYCService_ScanCertificateV2.cs` - 证件扫描测试(v2)
|
||
- `TestKYCService_ScanCertificateV2_OCR.cs` - OCR识别测试
|
||
- `TestKYCService_ScanCertificateV2_OCR_Passport.cs` - 护照OCR测试
|
||
- `TestKYCService_GetAttachmentFileSettingAsync.cs` - 附件设置测试
|
||
- `TestKYCService_GetScanAndValidateSettingAsync.cs` - 扫描验证设置测试
|
||
|
||
### 测试覆盖范围
|
||
|
||
- 证件扫描和识别
|
||
- OCR服务集成
|
||
- 设置管理
|
||
- 验证流程
|
||
- Mock服务测试
|