# 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服务测试