9.1 KiB

Raw Blame History

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 节点

配置结构示例

{
  "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

存储证件验证记录，包含验证状态和来源结果。

前端集成

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

9.1 KiB Raw Blame History Unescape Escape