ArayikGevorgyan/AML_System
GitHub: ArayikGevorgyan/AML_System
一个基于规则的 AML 交易监控系统，结合机器学习，用于检测可疑金融活动并支持案件管理与制裁筛查。
Stars: 0 | Forks: 0
# AML 交易监控系统
## 目录
- [概述](#overview)
- [功能特性](#features)
- [技术栈](#tech-stack)
- [系统架构](#system-architecture)
- [模块](#modules)
- [AML 检测规则](#aml-detection-rules)
- [制裁筛查算法](#sanctions-screening-algorithm)
- [机器学习模型](#ml-models)
- [快速开始](#quick-start)
- [演示凭据](#demo-credentials)
- [API 文档](#api-documentation)
- [项目结构](#project-structure)
## 概述
本系统模拟了一个真实的 AML（反洗钱）交易监控平台，供金融机构用于检测、调查和报告可疑金融活动。它实现了基于规则的检测、对 OFAC SDN 清单和 UN 合并清单的模糊制裁筛查、告警生成、案件管理、基于机器学习的异常检测以及完整的审计追踪。
## 功能特性
- **JWT 认证**：基于角色的访问控制（管理员 / 分析员 / 监督员）
- **用户注册**：带邮箱验证码的注册
- **客户与账户管理**：风险画像与 PEP 标记
- **交易监控**：自动风险评分
- **9 规则 AML 检测引擎**：基于 BSA、FATF 与 FinCEN 类型学
- **微交易检测**：高频小额重复交易
- **告警生成**：分级（低 / 中 / 高 / 严重）
- **案件管理**：调查流程与 SAR 提交支持
- **OFAC SDN + UN 合并清单筛查**：使用令牌回溯 Jaro-Winkler 模糊匹配
- **可搜索的下拉框**：类型（86 个项目）、项目（196 个国家）
- **机器学习异常检测**：每个客户基于 Isolation Forest 的行为模型
- **机器学习风险预测**：基于 Gradient Boosting 的 SAR 概率预测（未来 90 天）
- **批量筛查 CLI**：对 CSV 中的名单/ID 进行制裁库筛查
- **健康检查 CLI**：系统级状态检查与监控退出码
- **合规报告生成器**：指定日期范围的文本与 CSV 报告
- **交互式仪表板**：KPI、图表与实时统计
- **完整审计追踪**：所有操作的可追溯记录
- **深色 / 浅色模式**：可持久化偏好设置
## 技术栈
| 层级 | 技术 |
|------|------|
| 前端 | React 18、React Router v6、Recharts、React Icons、Axios |
| 后端 | Python 3.13、FastAPI、SQLAlchemy ORM、Pydantic v2 |
| 数据库 | SQLite（WAL 模式，启用外键） |
| 认证 | JWT（python-jose）、bcrypt 密码哈希 |
| 制裁数据 | OFAC SDN 高级 XML + UN 合并清单 XML |
| 模糊匹配 | jellyfish（Jaro-Winkler）、SQL ILIKE 子串预过滤 |
| XML 解析 | lxml iterparse（流式处理，内存高效） |
| 机器学习 / 统计 | scikit-learn、numpy（Isolation Forest、Gradient Boosting） |
| 邮件 | 通过 Brevo 的 SMTP（或开发环境终端回退） |
## 系统架构
```
┌─────────────────────────────────────────────────────────┐
│ React Frontend (Port 3000) │
│ Dashboard │ Customers │ Transactions │ Alerts │ Cases │
│ Sanctions │ Rules │ Audit │ Login │ Register │
└──────────────────────────┬──────────────────────────────┘
│ HTTP/REST (Axios + JWT)
┌──────────────────────────▼──────────────────────────────┐
│ FastAPI Backend (Port 8000) │
│ /api/v1/auth │ /customers │ /transactions │ /alerts │
│ /cases │ /rules │ /sanctions │ /dashboard │ /audit │
└──────────┬───────────────┬────────────────┬─────────────┘
│ │ │
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ SQLite DB │ │ Rules Engine│ │ Sanctions │
│ (aml.db) │ │ (9+ rules) │ │ Screener │
└─────────────┘ └─────────────┘ └──────┬──────┘
│
┌──────▼──────┐
│ OFAC SDN │
│ + UN List │
└─────────────┘
```
## 模块
| 模块 | 描述 |
|------|------|
| **认证** | JWT 登录/注销，注册邮箱验证，3 种角色 |
| **客户** | 客户档案、风险等级（低/中/高/严重）、PEP 状态、制裁标记 |
| **账户** | 与客户绑定的银行账户，自动生成账号 |
| **交易** | 创建与监控交易，提交时自动风险评分 |
| **规则引擎** | 9+ 条可配置 AML 检测规则，带阈值与时间窗口 |
| **告警** | 规则匹配自动生成，级别分类，状态流转 |
| **案件** | 调查管理、笔记线程、状态跟踪、SAR 提交 |
| **制裁筛查** | 对 OFAC SDN 与 UN 合并清单的模糊名称搜索 |
| **黑名单** | 自定义 IP、国家、实体、邮箱、账号黑白名单 |
| **风险评分** | 复合风险分（画像 + 交易行为 + 告警历史） |
| **机器学习模型** | Isolation Forest 异常检测 + Gradient Boosting SAR 预测 |
| **分析** | 交易趋势、风险分布、制裁统计 |
| **仪表板** | KPI 卡片、趋势图表、告警分布、案件统计 |
| **审计日志** | 完整不可变的审计追踪，含前后 JSON 快照 |
## AML 检测规则
所有规则均基于官方监管指引：**银行保密法（BSA）**、**FATF 建议** 与 **FinCEN 类型学**。
| # | 规则 | 监管依据 | 描述 |
|---|------|----------|------|
| 1 | **大额交易** | BSA / 31 USC §5313 | 单笔交易超过 $10,000 报告阈值 |
| 2 | **分拆（Smurfing）** | 31 USC §5324 | 多笔交易略低于阈值以规避 CTR 报告 |
| 3 | **高频交易** | FATF 建议 20 | 24 小时内异常高交易笔数 |
| 4 | **高速流动** | FinCEN 提醒 | 短时间内大额资金累计进出 |
| 5 | **高风险国家** | FATF / OFAC | 涉及 OFAC 清单或 FATF 高风险司法管辖区 |
| 6 | **快速转移** | FinCEN Pass-Through | 数小时内收进转出（分层指示） |
| 7 | **整数金额** | FATF 指引 | 可疑的整数金额（如 $5,000.00） |
| 8 | **PEP 交易** | FATF 建议 12 | 涉及政治公众人物 |
| 9 | **微交易** | FinCEN 指引 | 高频小额（账户测试指示） |
## 制裁筛查算法
制裁筛查器采用多阶段流水线，搜索 OFAC SDN 高级 XML 与 UN 合并清单。结果按别名逐行展示，匹配 OFAC 官方展示模型。
```
Input Name
│
▼
Normalize (lowercase, unicode→ASCII, remove honorifics, keep Arabic particles)
│
▼
SQL ILIKE Substring Pre-filter (candidate retrieval — fast DB-level filter)
│
▼
Composite Score per alias:
Token Recall (per-token best Jaro-Winkler) × 0.60
+ Full-string Jaro-Winkler × 0.25
+ Token Jaccard Overlap × 0.15
│
▼
Exact token subset → Score 100 (matches OFAC "Min Score = 100" rule)
│
▼
Filter by min_score → Sort by score desc → Return Results
```
**匹配强度**：精确（100）| 强（≥85）| 可能（≥70）| 弱（<70）
**支持的清单**：
| 清单 | 来源 | 条目数 |
|------|------|--------|
| OFAC SDN | sdn_advanced.xml（官方 OFAC） | 约 18,000+ |
| UN 安理会清单 | consolidatedLegacyByNAME.xml（联合国安理会） | 约 1,000+ |
## 机器学习模型
### 异常检测器（`ml/anomaly_detector.py`）
- **算法**：Isolation Forest（无监督）
- **目的**：基于客户自身历史行为检测统计异常交易，捕捉规则未覆盖的新型欺诈模式
- **特征**：log(金额)、小时、星期几、是否国际、是否整数金额、交易类型、渠道
- **输出**：异常分（0–100）、是否异常（bool）、原因
### 客户风险预测器（`ml/risk_model.py`）
- **算法**：梯度提升分类器（sklearn）
- **目的**：预测客户在未来 90 天内生成 SAR 的概率
- **特征**：14 项特征，包括交易速度、标记比例、告警严重分、PEP/制裁状态、国家风险、账户年龄
- **输出**：SAR 概率（0–1）、风险等级、关键因素
### 特征工程（`ml/feature_engineering.py`）
集中化流水线，为每个客户提取 30+ 项特征，涵盖 5 组：金额统计、速度窗口、时间模式、地理风险与告警历史。
### 模型评估器（`ml/model_evaluator.py`）
评估套件包含精确率、召回率、F1、ROC-AUC、混淆矩阵、阈值分析、K 折交叉验证与并排模型对比。召回率被设为最重要的 AML 指标。
## 快速开始
### 先条件
- Python 3.13+
- Node.js 18+
- OFAC SDN 高级 XML 文件（`sdn_advanced.xml`）
- UN 合并清单 XML 文件（`consolidatedLegacyByNAME.xml`）*（可选）*
### 1. 后端设置
```
cd backend
# 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate # macOS/Linux
# venv\Scripts\activate # Windows
# 安装依赖
pip install -r requirements.txt
# 导入数据库（用户、规则、客户、交易）
python scripts/seed_data.py
# 导入 OFAC SDN 制裁名单
python scripts/import_sanctions.py
# 导入联合国综合清单（可选）
python scripts/import_un_sanctions.py
# 配置电子邮件（可选 — 如果未配置，代码将打印到终端）
cp .env.example .env
# 编辑 .env 并填写 SMTP 凭据
# 启动 API 服务器
uvicorn main:app --reload --port 8000
```
### 2. 前端设置
```
cd frontend
npm install
npm start
```
在浏览器中打开 `http://localhost:3000`。
### 3. CLI 工具
```
# 批量筛查 CSV 中的名称与制裁名单
python scripts/bulk_screen.py --input customers.csv --output results.csv
# 系统健康检查
python scripts/health_check.py
# 生成合规报告（最近 30 天）
python scripts/generate_report.py --days 30 --format text
# 训练 ML 风险模型
python ml/train.py
```
### 4. 运行测试
```
cd backend
pytest tests/ -v
```
## 演示凭据
| 用户名 | 密码 | 角色 |
|--------|------|------|
| `admin` | `Admin@123` | 管理员 |
| `ArayikAnalyst` | `Analyst@123` | 分析员 |
| `ArayikSupervisor` | `Super@123` | 监督员 |
## API 文档
交互式 Swagger UI 地址：`http://localhost:8000/docs`
| 端点 | 描述 |
|------|------|
| `POST /api/v1/auth/login` | 认证并获取 JWT 令牌 |
| `POST /api/v1/auth/send-verification` | 发送邮箱验证码 |
| `POST /api/v1/auth/register` | 注册新用户账户 |
| `GET /api/v1/dashboard` | 获取所有仪表板 KPI 与图表 |
| `GET /api/v1/customers` | 列出所有客户 |
| `POST /api/v1/transactions` | 创建交易（触发规则引擎） |
| `GET /api/v1/alerts` | 列出告警（支持筛选） |
| `POST /api/v1/sanctions/search` | 模糊搜索 OFAC SDN + UN 列表 |
| `GET /api/v1/sanctions/stats` | 制裁库统计信息 |
| `GET /api/v1/audit` | 检索审计日志条目 |
## 项目结构
```
AML/
├── backend/
│ ├── main.py # FastAPI app entry point
│ ├── config.py # Settings and environment variables
│ ├── database.py # SQLAlchemy engine and session
│ ├── requirements.txt
│ ├── .env.example
│ ├── models/ # SQLAlchemy ORM models
│ │ ├── user.py
│ │ ├── customer.py
│ │ ├── account.py
│ │ ├── transaction.py
│ │ ├── rule.py
│ │ ├── alert.py
│ │ ├── case.py
│ │ ├── sanctions.py
│ │ ├── blacklist.py
│ │ └── audit_log.py
│ ├── routers/ # FastAPI route handlers
│ │ ├── auth.py
│ │ ├── customers.py
│ │ ├── transactions.py
│ │ ├── rules.py
│ │ ├── alerts.py
│ │ ├── cases.py
│ │ ├── sanctions.py
│ │ ├── blacklist.py
│ │ ├── dashboard.py
│ │ ├── reporting.py
│ │ ├── risk_scoring.py
│ │ └── audit.py
│ ├── services/ # Business logic
│ │ ├── rules_engine.py # AML detection engine (9 rules)
│ │ ├── sanctions_screener.py # Jaro-Winkler fuzzy screener
│ │ ├── alert_service.py
│ │ ├── case_service.py
│ │ ├── transaction_service.py
│ │ ├── customer_service.py
│ │ ├── risk_scoring_service.py
│ │ ├── blacklist_service.py
│ │ ├── dashboard_service.py
│ │ ├── auth_service.py
│ │ ├── audit_service.py
│ │ ├── escalation_service.py
│ │ ├── reporting_service.py
│ │ ├── predictive_risk_service.py
│ │ └── email_service.py
│ ├── ml/ # Machine learning models
│ │ ├── anomaly_detector.py # Isolation Forest per-customer
│ │ ├── risk_model.py # Gradient Boosting SAR predictor
│ │ ├── feature_engineering.py # Centralised feature pipeline
│ │ ├── model_evaluator.py # Metrics, threshold analysis
│ │ └── train.py # Training script
│ ├── analysis/ # Data analysis modules
│ │ ├── transaction_analysis.py
│ │ ├── risk_distribution.py
│ │ └── sanctions_stats.py
│ ├── tests/ # Unit tests (pytest)
│ │ ├── test_sanctions_screener.py
│ │ ├── test_risk_scoring.py
│ │ ├── test_rules_engine.py
│ │ ├── test_auth_service.py
│ │ ├── test_alert_service.py
│ │ ├── test_transaction_service.py
│ │ └── test_blacklist_service.py
│ ├── core/
│ │ ├── security.py # JWT and bcrypt
│ │ ├── dependencies.py # FastAPI dependencies / RBAC
│ │ └── enums.py
│ └── scripts/
│ ├── seed_data.py # Demo data seeder
│ ├── import_sanctions.py # OFAC XML importer
│ ├── import_un_sanctions.py # UN Consolidated List importer
│ ├── bulk_screen.py # CLI: bulk sanctions screening
│ ├── health_check.py # CLI: system health check
│ └── generate_report.py # CLI: compliance report generator
│
├── frontend/
│ ├── public/
│ └── src/
│ ├── App.js
│ ├── index.css # Global dark/light theme variables
│ ├── api/
│ │ └── client.js # Axios instance with JWT interceptor
│ ├── context/
│ │ ├── AuthContext.js
│ │ └── ThemeContext.js # Dark/light mode
│ ├── components/layout/
│ │ ├── Layout.js
│ │ ├── Sidebar.js
│ │ └── Topbar.js
│ └── pages/
│ ├── Login.js
│ ├── Register.js
│ ├── Dashboard.js
│ ├── Customers.js
│ ├── Transactions.js
│ ├── Alerts.js
│ ├── Cases.js
│ ├── Sanctions.js # Searchable Type/Program/Country dropdowns
│ ├── Rules.js
│ └── Audit.js
│
└── docs/
├── REQUIREMENTS.md
└── USER_STORIES.md
```
标签：196国家, 86项目, AML, BSA, CLI, Country, CRITICAL, FATF, FinCEN, HIGH, Jaro-Winkler, JWT认证, LOW, MEDIUM, ML风险预测, OFAC制裁筛查, PEP, Program, RBAC, RegTech, SAR, SAR预测, SDN, TCP/UDP协议, Type, WiFi技术, 九规则, 云计算, 交易监控, 交易监测, 健康检查, 区块链审计, 反洗钱, 可疑活动报告, 合规平台, 告警分级, 审计追踪, 客户管理, 尽职调查, 异常检测, 微交易检测, 批量筛查, 搜索筛选, 数据溯源, 时间序列, 梯度提升, 检测规则, 模块化设计, 模糊匹配, 用户注册, 监管科技, 系统架构, 网络资产发现, 联合国制裁名单, 自动化修复, 规则引擎, 角色权限, 账户管理, 逆向工具, 邮箱验证码, 金融安全, 金融监管, 隔离森林, 风险画像, 风险评分, 高频小额