AML/docs/KYC/KYCConfig.md

# KYC 配置分析文档

## 概述
本文档基于系统代码实际使用情况，分析 `appsettings.json` 文件中 `KYCConfig` 节点下各个配置项的作用和功能。

## 配置结构与代码使用分析

### 1. XiangyunAPI 配置
**使用位置**: `XiangyunService.cs`
**作用**: 配置祥云 OCR 识别服务的 API 接口参数

```csharp
// 在 XiangyunService 构造函数中使用
_xiangyunConfig = appConfig.Value.KYCConfig.XiangyunAPI;
```

**配置项说明**:
- **BaseUrl**: 祥云 OCR 服务的基础 URL (`https://netocr.com`)
- **Key**: API 访问密钥，用于身份验证
- **Secret**: API 访问密码，用于身份验证
- **Timeout**: HTTP 请求超时时间（秒），默认 30 秒

**实际用途**: 
- 身份证 OCR 识别 (`OCRIDCard`)
- 营业执照 OCR 识别 (`OCRBusinessLicense`)
- 文档 OCR 识别 (`OCRDocument`)
- 表格 OCR 识别 (`OCRTable`)
- 身份证实名验证 (`ValidateIDCard`)
- 护照验证 (`ValidatePassport`)
- 征信查询 (`ValidateCredit`)

### 2. CertificateCodeMappings 配置
**使用位置**: `XiangyunCartTypeCodeConverter.cs`
**作用**: 定义 AML 系统内部证件代码与祥云 OCR 服务证件代码的映射关系

```csharp
// 获取映射配置
return _configuration.GetSection("AppConfig:KYCConfig:XiangyunAPI:CertificateCodeMappings")
    .Get<List<CertificateCodeMapping>>();

// 转换方法
public string ToOCRCode(string amlCode) // AML代码转OCR代码
public string ToCreditCode(string amlCode) // AML代码转征信代码
public string ToValidateCode(string amlCode) // AML代码转验证代码
```

**映射字段**:
- **AMLCode**: AML 系统内部证件代码（支持多个代码用 "|" 分隔）
- **OCRCode**: 祥云 OCR 服务对应的证件类型代码
- **CreditCode**: 征信查询使用的代码
- **ValidateCode**: 验证服务使用的代码
- **Remark**: 证件类型说明

### 3. CertificateEntityColumParseRules 配置
**使用位置**: `CertificateEntityValueFinder.cs`
**作用**: 定义从 OCR 识别结果中解析实体字段的规则，用于前端UI可以自动填入

```csharp
// 获取解析规则
var rules = _appConfig.Value.KYCConfig.CertificateEntityColumParseRules;

// 查找匹配规则并提取值
public string FindValue(string name, CardInfo cardInfo)
public string FindValue(string name, string jsonContent)
```

**规则结构**:
- **AMLCode**: 适用的证件代码（"*" 表示所有证件）
- **EntityColumn**: 目标实体字段名（如 Name、Number、Birthday 等）
- **EntityColumnNames**: OCR 识别结果中可能的字段名称列表

**支持的实体字段**:
- CardName, Name, Number, CountryCode, Birthday, Address, Sex, ExpireDate, FirstOrGivenName, Surname

### 4. SupportCertificate 配置
**使用位置**: `KYCService.cs`, `ConsumerPortalService.cs`
**作用**: 定义系统支持的证件类型列表，用于前端显示

```csharp
// 获取个人证件类型
var supportCertificates = _configuration
    .GetSection("AppConfig:KYCConfig:SupportCertificate:Individual")
    .Get<List<CategoryDto>>();

// 获取企业证件类型
var supportCertificateCodes = _configuration
    .GetSection("AppConfig:KYCConfig:SupportCertificate:Organization")
    .Get<List<CategoryDto>>();
```

**用途**: 
- 为前端提供可选的证件类型列表
- 支持多语言显示（英文、简体中文、繁体中文、日文）
- 控制证件类型的启用状态和显示顺序

### 5. TranslateMappings 配置
**使用位置**: `TranslateMapper.cs`
**作用**: 定义验证结果的多语言翻译映射

```csharp
// 获取翻译映射
var translateMappings = _appConfig.Value.KYCConfig.TranslateMappings;

// 翻译方法
public string FindValue(string content, string objectType = "")
public MultipleLang FindMultipleLang(string content, string objectType = "")
```

**翻译对象类型**:
- **ValidateCredit**: 征信验证结果翻译
- **ValidateIDCard**: 身份证验证结果翻译

**翻译字段**:
- **Value**: 英文翻译
- **ValueSC**: 简体中文翻译
- **ValueTC**: 繁体中文翻译
- **MatchRules**: 匹配规则列表

### 6. CertificateContentMatchRules 配置
**使用位置**: `KYCService.cs`
**作用**: 根据证件内容自动识别证件类型

```csharp
// 获取证件内容匹配规则
var matchRules = _configuration.GetSection("AppConfig:KYCConfig:CertificateContentMatchRules")
    .Get<List<CertificateContentMatchRule>>();

// 自动识别证件类型
private string DetermineCertificateTypeCode(string content)
```

**用途**: 通过分析 OCR 识别的文本内容，自动判断证件类型

### 7. CountryCodeMatchRules 配置
**使用位置**: `KYCService.cs`
**作用**: 根据证件内容自动识别国家代码

```csharp
// 获取国家代码匹配规则
var matchRules = _configuration.GetSection("AppConfig:KYCConfig:CountryCodeMatchRules")
    .Get<List<CountryCodeMatchRule>>();

// 自动识别国家代码
private string findCountryCode(string content)
private string DetermineCountryCode(string content, string certificateCode)
```

**用途**: 通过分析证件内容，自动识别证件所属国家

### 8. AttachmentFileSetting 配置
**使用位置**: `KYCService.cs`
**作用**: 定义附件文件类型设置和证件处理器配置

```csharp
// 获取附件文件设置
var configValue = _configuration.GetSection("AppConfig:KYCConfig:AttachmentFileSetting")
    .Get<AttachmentFileSetting>();

// 相关方法
public async Task<AttachmentFileSetting> GetAttachmentFileSettingAsync()
public async Task<OperationDto> UpdateAttachmentFileSettingAsync(AttachmentFileSetting input)
```

**配置内容**:
- 个人和企业的文件类型定义
- 每种文件类型的处理器配置
- 文件验证和更新策略

### 9. ScanAndValidateSetting 配置
**使用位置**: `KYCService.cs`
**作用**: 定义扫描和验证模式设置

```csharp
// 获取扫描验证设置
var configSection = _configuration.GetSection("AppConfig:KYCConfig:ScanAndValidateSetting");

// 相关方法
public async Task<ScanAndValidateSetting> GetScanAndValidateSettingAsync()
public async Task<OperationDto> UpdateScanAndValidateSettingAsync(ScanAndValidateSetting input)
```

**配置模式**:
- **ScanMode**: 扫描模式（OCR、芯片扫描等）
- **InputMode**: 输入模式（手动输入等）

### 10. ScanAndValidateHandlers 配置
**使用位置**: `HandlerService.cs`
**作用**: 定义所有可用的扫描和验证处理器

```csharp
// 获取处理器配置
var handlersConfig = _configuration.GetSection("AppConfig:KYCConfig:ScanAndValidateHandlers")
    .Get<List<ScanAndValidateHandlerDefinition>>();

// 处理器执行
public async Task<HandleResultDto> Handle(HandleInputDto input)
```

**处理器类型**:
- **OCR 处理器**: OCRIDCard, OCRBusinessLicense, OCRDocument, OCRTable
- **验证处理器**: ValidateIDCard, ValidatePassport, ValidateCredit, ValidateBR
- **扫描处理器**: Scan_OCR, Scan_Chin

### 11. CertificateMappings 配置
**使用位置**: `KYCService.cs`
**作用**: 证件映射配置（用于扩展证件类型支持）

```csharp
// 获取证件映射
mappings = _configuration.GetSection("AppConfig:KYCConfig:CertificateMappings")
    .Get<List<CertificateMapping>>();
```

**用途**: 预留的扩展配置，用于支持更多证件类型的映射关系

## 数据库存储

KYC 配置还涉及数据库存储：
- **AttachmentFileSettingValue**: 存储租户级别的附件文件设置
- **ScanAndValidateSettingValue**: 存储租户级别的扫描验证设置

这些设置可以覆盖全局配置，实现租户级别的个性化配置。

## 总结

KYCConfig 配置是一个完整的 KYC 系统配置框架，通过以下方式实现功能：

1. **服务集成**: 与祥云 OCR 服务深度集成，支持多种证件识别和验证
2. **代码转换**: 通过映射表实现内部代码与外部服务代码的转换
3. **字段解析**: 智能解析 OCR 结果，提取结构化数据
4. **自动识别**: 基于内容规则自动识别证件类型和国家
5. **多语言支持**: 提供完整的多语言翻译机制
6. **灵活配置**: 支持租户级别的个性化配置
7. **处理器架构**: 模块化的处理器设计，支持扩展

该配置系统为 AML 系统提供了强大的 KYC 功能支持，能够处理复杂的证件识别、验证和管理需求。