# 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`