From cf3c61eb24b8cbc3deb11ca2d05b419cb62239aa Mon Sep 17 00:00:00 2001 From: fengruixiang <474182370@qq.com> Date: Thu, 30 Apr 2026 10:07:35 +0800 Subject: [PATCH] init --- .gitignore | 0 CLAUDE.md | 108 ++++++++++++++++++++++ docs/KYC/README.md | 217 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 325 insertions(+) create mode 100644 .gitignore create mode 100644 CLAUDE.md create mode 100644 docs/KYC/README.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e69de29 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..37eb56f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,108 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Repository Overview + +This is a monorepo containing two main applications: +- **AML_Backend**: ASP.NET Core backend using ABP (ASP.NET Boilerplate) framework +- **AML_Frontend**: Angular 11 frontend using ABP Angular framework + +## Build Commands + +### Frontend (AML_Frontend) +```bash +cd AML_Frontend +npm install --legacy-peer-deps # Install dependencies +npm start # Start dev server with --open +npm run build:dev # Build for development +npm run build:prod # Build for production +npm run build:prod2 # Build for production2 (alternative env) +npm test # Run unit tests +npm run lint # Run linter +npm run e2e # Run e2e tests +``` + +### Backend (AML_Backend) +```bash +# Build with dotnet CLI +dotnet build iCON.Abp.AMLSolution.sln + +# Run migrations (Visual Studio Package Manager Console) +# 1. Set EntityFrameworkCore.DbMigrations as startup project +# 2. Set default project to: src\EntityFrameworkCore.DbMigrations +# 3. Run: Add-Migration +``` + +## Architecture + +### Backend Architecture (ABP Framework) + +**Solution Structure**: `AML_Backend/iCON.Abp.AMLSolution.sln` + +**Core Modules**: +- `modules/iCON.Abp.AML/` - Main AML (Anti-Money Laundering) module with: + - Application.Contracts - Service interfaces and DTOs + - Application - Service implementations + - Domain - Entities, domain logic + - Domain.Shared - Shared enums, constants + - EntityFrameworkCore - Repositories, DbContext + - HttpApi - API controllers + +**Key Services in iCON.Abp.AML**: +- `DetectionService` - AML detection logic +- `CRCheckerService` - Compliance checking +- `ConsumerPortalService` - Consumer-facing portal operations +- `CorporationService` / `IndividualService` - Entity management +- `DataCollectService` - Data collection pipeline +- `STRService` - Suspicious Transaction Reporting +- `ReportService` - Report generation + +**Host Projects**: +- `src/iCON.Abp.FX.HttpApi.Host` - Main API host (Program.cs entry point) +- `src/iCON.Abp.FX.Web.Public` - Public web portal +- `src/iCON.Abp.FX.DbMigrator` - Database migration runner + +**Infrastructure Projects**: +- `infrastructure/iCON.Core.Infrastructure.*` - Shared infrastructure utilities + +### Frontend Architecture (Angular 11 + ABP) + +**Main Application** (`AML_Frontend/src/app/`): +- `app.module.ts` - Root module with ABP configuration +- Feature modules under `modules/`: + - `aml-query/`, `agent/`, `configuration/`, `document/`, `form/`, `home/`, `investigate-setting/`, `llm/`, `log/`, `operator/`, `plan/`, `realtime-screening/`, `report/`, `risk-report/`, `screen-report/`, `stats/`, `str/`, `tenant-info/`, `transaction-report/`, `white-list/` + +**Shared Components** (`src/app/shared/`): +- `shared.module.ts` - Shared module exports + +**Viewer Components** (`src/app/components/components-viewer/`): +- `viewer-account-select/`, `viewer-account-form/`, `viewer-confirm-status/`, `viewer-customer-info/`, `viewer-print-list/`, `viewer-scan-modal/`, `viewer-upload-modal/` + +**External Module Dependencies**: +- `@volo/abp.ng.*` - ABP Angular modules (account, identity, saas, audit-logging, language-management, etc.) +- `@abp/ng.*` - ABP Angular core modules +- `ng-zorro-antd` - UI component library +- `primeng` - PrimeNG components +- `@ngxs/store` - State management +- `ngx-echarts` - Charting +- `@syncfusion/ej2-angular-*` - Syncfusion components + +**Build Configuration**: +- Angular 11 with `angular.json` defining build targets +- Multiple environment configurations (environment.ts, environment.dev.ts, environment.prod.ts, environment.prod2.ts) +- Uses SCSS for styling, HashLocationStrategy for routing + +## Database Migrations + +Migrations use Entity Framework Core. To create a migration: +1. Set `EntityFrameworkCore.DbMigrations` as the startup project in Visual Studio +2. Open Package Manager Console, set default project to `src\EntityFrameworkCore.DbMigrations` +3. Run `Add-Migration ` +4. Migrations apply automatically on next run + +## Notes + +- The backend uses ABP's modular architecture - each module (AML, AMLPortal, Basic, MediaStore) follows the same layer pattern +- Frontend proxies API calls through the Angular dev server configuration +- Both frontend and backend share the same solution but are in separate directories diff --git a/docs/KYC/README.md b/docs/KYC/README.md new file mode 100644 index 0000000..d388a29 --- /dev/null +++ b/docs/KYC/README.md @@ -0,0 +1,217 @@ +# 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`