WongYikShern/AML-Transaction-Monitoring-System

# FinSight AI ### 混合 AI 驱动的反洗钱交易监控系统       ## 概述 金融犯罪每年给全球经济造成估计占全球 GDP **2% 到 5%** 的损失。传统的基于规则的反洗钱（AML）系统误报率很高，使得合规团队疲于应对；而纯机器学习方法则缺乏监管报告所需的可解释性。 **FinSight AI** 通过将确定性规则引擎与无监督 Isolation Forest 机器学习模型相结合，构成了一个单一的 **60/40 混合评分系统**来解决这个问题。其结果是 F1 分数高于任何单一方法，同时将误报率保持在足够低的水平，从而满足合规官的实际工作负载需求。 FinSight AI 是一个**全栈 AML 监控原型**，端到端地展示了这种混合方法，提供了从自动化交易评分和告警生成，到案件分配、审查和解决的完整调查工作流。所有这些都呈现在一个专为金融合规环境设计的 React 暗色主题界面中。 ## 存在的问题 | 挑战 | 影响 | | -------------------------------------------------------- | -------------------------------------------------------------- | | 单一的规则引擎会漏掉新颖、新兴的模式 | 低召回率 — 可疑交易逃避检测 | | 单一的 ML 模型会产生过多的误报 | 高 FPR — 官员浪费时间处理合法交易 | | 黑盒 ML 决策无法向监管机构解释 | 合规失败 — 没有正当理由的告警会被拒绝 | | 跨电子表格进行手动案件跟踪 | 调查周期缓慢，错过最后期限 | ## 解决方案 FinSight AI 将三个检测层融合为一个统一的工作流： ``` Transaction │ ├──► Rule Engine (four deterministic AML rules) ──► rule_score (0–100) │ │ ├──► Isolation Forest ML (12 behavioural features) ──► ml_score (0–100) │ │ └──────────────────────────────────────────────────► hybrid_score = rule×0.60 + ml×0.40 │ ┌────────────────────┘ │ hybrid_score ≥ 31 ▼ AML Alert ──► Investigation Case ──► Resolution ``` 每个告警都附有完整的**可解释性报告**：哪些规则被触发以及原因、哪些 ML 异常因素起了作用，以及一份简单明了的决策摘要——为官员采取行动提供所需的证据。 ## 核心功能 ### 1. 身份验证与安全 - 基于 JWT 的身份验证，包含 `full_access` (8 小时) 和 `2fa_pending` (10 分钟) token 类型 - 三级 RBAC：**Officer → Supervisor → Admin** - 5 次尝试失败后锁定账户（锁定 15 分钟） - Bcrypt 密码哈希与复杂度策略强制执行 - 2FA 桩流程（生成 → 验证 OTP） - 用于所有身份验证和案件事件的不可变审计日志 - Token 仅存储在 `sessionStorage` 中 — 绝不使用 `localStorage` ### 2. AML 检测引擎 #### 基于规则的检测 | 规则 | 触发条件 | 权重 | | ------------------- | ------------------------------------------------------------------------ | ------ | | 大额交易 | 单笔金额 ≥ RM 50,000 | 30% | | 结构化交易 | 24小时内低于阈值的交易累计 ≥ RM 50,000 | 25% | | 行为偏差 | 金额 ≥ 客户历史平均值的 3 倍（至少需要 5 笔先前的交易） | 30% | | 跨境风险 | 汇款渠道和/或高风险客户分类 | 15% | 每个触发的规则都会生成单独的分数，并附上易于理解的解释与该告警关联。 #### 机器学习 — Isolation Forest - 无监督异常检测：无需标注训练数据 - 200 个估计器，污染率 0.10 - 每笔交易的 **12 个行为特征**： | # | 特征 | 描述 | | --- | ----------------------- | ---------------------------------------------------- | | 1 | `amount` | 原始交易金额 (MYR) | | 2 | `log_amount` | log₁p(amount) — 压缩大值范围 | | 3 | `hour_of_day` | 0–23 — 异常小时检测 | | 4 | `day_of_week` | 0–6 (星期一 = 0) | | 5 | `customer_avg_amount` | 历史平均值（不包含当前交易） | | 6 | `amount_to_avg_ratio` | amount ÷ 客户平均值 | | 7 | `txn_count_last_24h` | 24小时窗口内的交易速度 | | 8 | `transaction_type_enc` | 标签编码的交易类型 | | 9 | `merchant_category_enc` | 标签编码的商户类别 | | 10 | `channel_enc` | 标签编码的渠道 (在线/移动/ATM/分行/POS) | | 11 | `customer_risk_enc` | 标签编码的客户风险等级 | | 12 | `is_remittance` | 用于汇款商户类别的二进制标志 | #### 混合评分 ``` hybrid_score = rule_score × 0.60 + ml_score × 0.40 Risk classification: Low 0 – 30 → No alert Medium 31 – 70 → Alert created High 71 – 100 → Alert created (priority) ``` ### 3. 告警管理 - 支持分页的告警队列，筛选条件包括：状态、风险等级、类别 - 告警详情页显示所有三个评分仪表（规则 / ML / 混合） - 完整的可解释性面板：触发规则及其各自得分、ML 异常因素、决策摘要以及最强烈的促成因素 - 告警状态生命周期：`open → under_review → closed / false_positive` ### 4. 调查工作流 - 从任何开放告警一键创建案件（manager+） - 案件队列，筛选条件包括：状态、优先级、分配的专员 - 状态工作流：`open → in_review → resolved` - 专员分配和重新分配（manager+） - 带有备注的解决方案：`confirmed_suspicious` 或 `false_positive` - 每次解决方案更新都会更改源告警状态并写入审计事件 ### 5. 仪表盘与分析 - 实时 KPI 卡片：未处理告警、高风险交易、活跃案件、总交易量 - 风险分布甜甜圈图（低 / 中 / 高） - 混合检测细分（规则标记 vs ML标记 vs 两者均有 vs 两者均无） - 最近告警表格 - ML 模型状态卡（模型版本、训练日期、已评分交易数） - 按状态和优先级划分的案例摘要 ### 6. 客户与交易监控 - 客户列表，支持搜索、风险类别和账户类型筛选 - 客户详情：完整资料、行为分析（平均金额、高峰时段、渠道细分）、近期交易历史 - 交易列表，具有 8 个筛选维度：类型、渠道、金额范围、日期范围、排序方向 - 交易详情：所有检测分数、规则细分、ML 分析、客户交叉引用 - 针对未评分交易提供“无可用分析”的优雅状态 ### 7. 模型评估仪表盘 - 并排比较规则引擎、Isolation Forest ML 和混合 AI - Recharts 条形图：所有三个系统的准确率 / 精确率 / 召回率 / F1 分数 - 误报率比较图表（越低越好） - 所有三个系统的混淆矩阵 - 带有实时 API 数据的研究见解卡片 - 仅限 supervisor 和 admin 角色访问 ## AI 模型评估 ### 数据集 由于金融数据隐私限制以及真实世界银行 AML 数据集的匮乏，我们生成了一个合成交易数据集，以模拟真实的数字银行行为和常见的可疑交易类型（大额转账、结构化模式、行为异常和跨境汇款）。 | 属性 | 值 | | ---------------------- | ----------------------- | | 交易总数 | 10,000 | | 客户数 | 150 | | 货币 | MYR (Malaysian Ringgit) | | 异常交易 | 1,300 (13%) | | 正常交易 | 8,700 (87%) | 该数据集包含一个 `seed_label` 字段（`normal`、`structuring`、`high_amount`、`abnormal`），为每笔交易编码了真实标签。关于其使用的关键点： - `seed_label` **被排除在 ML 训练之外** — Isolation Forest 模型是完全无监督的，从不查看这些标签 - `seed_label` **仅在三个评估函数中**（`get_rule_evaluation`、`get_ml_evaluation`、`get_hybrid_evaluation`）用于衡量与已知真实情况的检测准确率 - `seed_label` **绝不在前端暴露** — 它不会出现在任何告警、案件、交易详情或仪表盘视图中 ### 结果 | 系统 | 准确率 | 精确率 | 召回率 | F1 分数 | 误报率 | 标记数 | | --------------------- | --------- | --------- | --------- | --------- | ------------------- | ------- | | 规则引擎 | 91.0% | **99.5%** | 31.2% | 0.475 | **0.02%** | 407 | | Isolation Forest ML | 78.3% | 34.9% | **76.9%** | 0.480 | 21.45% | 2,865 | | **混合 AI (60/40)** | **92.3%** | 94.0% | 43.5% | **0.595** | 0.41% | 602 | **研究目标已验证：** 60/40 的混合比例在 F1 分数上优于这两个单一系统 — 比单一规则提高了 12.0 个百分点，比单一 ML 提高了 11.5 个百分点。它实现了接近规则引擎的精确率（94%），同时与单独使用规则相比大幅提高了召回率，且这一切都在低于 0.5% 的误报率下实现 — 这对于合规团队在运营上是完全可行的。 ## 技术栈 ### 后端 | 技术 | 版本 | 用途 | | ---------------- | ------- | ------------------------- | | Python | 3.14 | 运行时 | | Flask | 3.0.3 | Web 框架 + REST API | | Flask-SQLAlchemy | 3.1.1 | ORM | | MySQL / PyMySQL | 8.0 | 主数据库 | | PyJWT | 2.8.0 | JWT 身份验证 | | Flask-Bcrypt | 1.0.1 | 密码哈希 | | scikit-learn | 最新版 | Isolation Forest ML 模型 | | numpy / pandas | 最新版 | 特征工程 | | joblib | 最新版 | 模型序列化 | ### 前端 | 技术 | 版本 | 用途 | | -------------- | ------- | --------------------------------- | | React | 18 | UI 框架 | | Vite | 6 | 构建工具 + 开发服务器 | | Tailwind CSS | v3 | 实用优先的样式 | | React Router | v6 | 客户端路由 | | TanStack Query | v5 | 数据获取、缓存、mutations | | Zustand | 最新版 | 身份验证状态 | | Axios | 最新版 | HTTP 客户端 | | Recharts | 2.14.1 | 图表和数据可视化 | ## 架构 ### 系统层级 ``` ┌─────────────────────────────────────────────────────────────┐ │ React Frontend │ │ Vite 6 · React 18 · TanStack Query · Zustand · Recharts │ │ localhost:5500 — proxies /api → localhost:5000 │ └───────────────────────────┬─────────────────────────────────┘ │ HTTP / REST (JSON envelope) ┌───────────────────────────▼─────────────────────────────────┐ │ Flask API │ │ Blueprints: auth · customers · transactions · │ │ analysis · alerts · ml · hybrid · cases │ └──────────┬─────────────────────────────────────┬────────────┘ │ │ ┌──────────▼──────────┐ ┌────────────▼────────────┐ │ AML Services │ │ ML Pipeline │ │ rule_engine │ │ feature_engineering │ │ hybrid_service │ │ isolation_forest_model │ │ case_service │ │ ml_service │ │ auth_service │ └────────────┬────────────┘ └──────────┬──────────┘ │ └──────────────────┬──────────────────┘ │ ┌─────────────────────────────▼───────────────────────────────┐ │ MySQL 8.0 │ │ users · customers · transactions · transaction_analysis │ │ aml_alerts · investigation_cases · audit_logs │ │ ml_model_runs │ └─────────────────────────────────────────────────────────────┘ ``` ### AML 检测流水线 ``` Incoming Transaction │ ├──► Phase 4: Rule Engine ──────────────────────────────────────┐ │ large_amount · structuring · │ │ behaviour_deviation · cross_border_risk │ │ │ rule_score (0–100) ├──► Phase 5: Isolation Forest ML ─────────────────────────────┤ │ 12 behavioural features │ ml_score (0–100) │ unsupervised anomaly detection │ │ │ └──► Phase 6: Hybrid Scoring Engine ◄──────────────────────────┘ rule×0.60 + ml×0.40 = hybrid_score │ ┌──────────▼──────────┐ │ hybrid_score ≥ 31 │ │ AMLAlert created │ └──────────┬──────────┘ │ ┌──────────▼──────────┐ │ Phase 7/8D-2: │ │ InvestigationCase │ │ Officer assignment │ │ open → in_review │ │ → resolved │ └─────────────────────┘ ``` ### 响应信封 每个 API 响应都使用以下结构： ``` { "success": true, "data": { ... }, "error": null } ``` ## 安装说明 ### 前置条件 - Python 3.11+ 及 pip - Node.js 18+ 及 npm - MySQL 8.0 服务器（在本地运行） ### 后端设置 ``` cd backend # 创建并激活虚拟环境 python -m venv venv # Windows venv\Scripts\Activate.ps1 # macOS / Linux source venv/bin/activate # 安装依赖 pip install -r requirements.txt # 配置环境 cp .env.example .env # 使用你的 MySQL 凭据和 SECRET_KEY 编辑 .env # 初始化并填充数据库 python database/init_db.py python database/seed_data.py python database/set_passwords.py # 启动 Flask API python run.py # 运行于 http://127.0.0.1:5000 ``` ### 运行检测线（仅限首次） 数据填充后，通过完整的流水线对所有 10,000 笔交易进行评分。首先通过调用 `POST /api/auth/login` 获取 admin token。 ``` # 1. Rule engine curl -X POST http://localhost:5000/api/analysis/run-batch \ -H "Authorization: Bearer " # 2. 使用 Isolation Forest 训练和评分 curl -X POST http://localhost:5000/api/ml/train \ -H "Authorization: Bearer " curl -X POST http://localhost:5000/api/ml/analyse-batch \ -H "Authorization: Bearer " # 3. 混合评分 (创建所有 AML 警报) curl -X POST http://localhost:5000/api/hybrid/run-batch \ -H "Authorization: Bearer " ``` ### 前端设置 ``` cd frontend npm install npm run dev # 运行于 http://localhost:5500 # /api/* 会自动代理到 http://127.0.0.1:5000 ``` 在浏览器中打开 `http://localhost:5500`。必须先运行后端。 ### 环境变量 从 `backend/.env.example` 创建 `backend/.env`： ``` FLASK_ENV=development SECRET_KEY= DB_USER=root DB_PASSWORD= DB_HOST=localhost DB_PORT=3306 DB_NAME=aml_system ``` ## 开发账户 填充的数据库包含以下用于开发和演示的账户。**请勿在任何生产环境中使用这些凭据。** | 用户名 | 显示角色 | 权限 | | ------------------------------- | ---------------------- | ---------------------------------------------------------------------------- | | `AML.admin` | AML 管理员 | 完全系统访问权限、模型评估、审计审查、用户管理 | | `AML.supervisor` | AML 主管 | 案件管理、专员分配、主管审查、评估仪表盘 | | `AML.officer01`–`AML.officer06` | AML 合规官 | 告警审查、案件调查、添加备注、提交给主管审查 | 密码：`AML.admin` → `Admin@2026`，`AML.supervisor` → `Super@2026`，`AML.officer01–06` → `Officer@2026`。运行 `python database/rename_users.py`（从 `backend/` 目录下）以迁移现有的种子账户并设置密码。 ## 项目结构 ``` AML-Transaction-Monitoring-System/ ├── backend/ │ ├── run.py # Flask entry point │ ├── config.py # Development / Testing / Production configs │ ├── requirements.txt │ ├── .env.example │ ├── app/ │ │ ├── aml_config.py # Approved AML constants — do not modify │ │ ├── models/ # SQLAlchemy ORM models │ │ ├── routes/ # Flask blueprints (8 modules) │ │ ├── services/ # Business logic (auth, rule engine, ML, hybrid, cases) │ │ ├── ml/ │ │ │ ├── feature_engineering.py # 12-feature extraction │ │ │ ├── isolation_forest_model.py │ │ │ └── artifacts/ # Trained model files (gitignored) │ │ └── utils/ # Response envelope, JWT helpers, decorators │ └── database/ │ ├── init_db.py # Schema creation │ ├── seed_data.py # 10,000-transaction dataset │ ├── set_passwords.py # Bcrypt password initialisation │ └── run_phase*_tests.py # Phase-specific test suites │ ├── frontend/ │ ├── vite.config.js # Port 5500, /api proxy │ ├── tailwind.config.js # Design tokens │ └── src/ │ ├── api/ # Axios modules (auth, alerts, cases, customers, ...) │ ├── components/ # Layout, UI primitives, AppInitializer │ ├── hooks/ # useAuth │ ├── pages/ # 10 route pages │ ├── store/ # Zustand auth store │ └── utils/ # formatMYR, formatScore, humanise │ └── docs/ └── DEVELOPMENT_STATUS.md # Full technical reference ``` ## API 参考 | 组别 | 基础路径 | 端点 | | ------------ | --------------------- | --------------------------------------------------------------------------- | | 健康检查 | `/api/health` | GET | | 身份验证 | `/api/auth/*` | login, logout, me, change-password, login-history, 2fa/generate, 2fa/verify | | 客户 | `/api/customers/*` | list, detail, transactions, behaviour | | 交易 | `/api/transactions/*` | list, detail, stats | | 规则引擎 | `/api/analysis/*` | run, run-batch, result | | 告警 | `/api/alerts/*` | list, detail | | ML | `/api/ml/*` | train, analyse, analyse-batch, model-status, evaluation | | 混合 | `/api/hybrid/*` | run, run-batch, result, statistics, evaluation | | 案件 | `/api/cases/*` | create, list, statistics, detail, assign, status, resolve | 完整的端点文档位于 [`docs/DEVELOPMENT_STATUS.md`](docs/DEVELOPMENT_STATUS.md) 中。 ## 项目状态 | 组件 | 状态 | | ------------------------------- | ------------------------------------------------------------------- | | 后端 API (阶段 0–7) | ✅ 完成 | | AML 检测流水线 | ✅ 完成 — 已评分 10,000 笔交易 | | React 前端 (阶段 8A–8D-4) | ✅ 完成 | | 模型评估 | ✅ 完成 — 混合 F1: 0.595 | | 后端测试 | ✅ 完成 — 289/289 项后端服务、单元和冒烟测试通过 | | 前端集成 | ✅ 完成 — 所有页面已连接到实时 API | | 最终 UI 验证与优化 | ✅ 完成 | ### 后端服务、单元和冒烟测试结果 这些结果仅涵盖后端业务逻辑验证。不包含前端自动化测试。 | 阶段 | 测试套件 | 结果 | | ------------------------- | --------------------------- | ------------- | | 阶段 4 — 规则引擎 | 59 个隔离 + 15 个实时冒烟 | ✅ 74/74 | | 阶段 5 — ML 模型 | 39 个隔离 + 28 个实时冒烟 | ✅ 67/67 | | 阶段 6 — 混合评分 | 45 个隔离 + 25 个实时冒烟 | ✅ 70/70 | | 阶段 7 — 案件管理 | 53 个隔离 + 25 个实时冒烟 | ✅ 78/78 | | **总计** | | **✅ 289/289** | ## AML 配置参考 所有检测常量均在 `backend/app/aml_config.py` 中定义，未经审查不得修改。 | 参数 | 值 | | --------------------------------- | ------------------------------- | | 货币 | MYR (RM) | | 大额交易阈值 | RM 50,000 | | 结构化交易窗口 | 24 小时 | | 行为偏差阈值 | 客户历史平均值的 3 倍 | | 最小交易历史记录 | 5 笔先前的交易 | | 规则权重 — large_amount | 30% | | 规则权重 — structuring | 25% | | 规则权重 — behaviour_deviation | 30% | | 规则权重 — cross_border_risk | 15% | | 混合比例 — 规则 | 60% | | 混合比例 — ML | 40% | | 告警阈值 | hybrid_score ≥ 31 (中等风险) | ## 安全说明 - Token 存储在 `sessionStorage` 中，并在注销或会话过期时清除 - `seed_label` 字段（用于评估）绝不会在任何前端视图中暴露 - 所有风险评分均在服务器端计算；前端不执行任何评分逻辑 - 所有密码存储均使用 Bcrypt；明文密码从不被记录或返回 - 本项目中的 2FA 实现是一个**原型桩** — 为了演示目的，它会在 API 响应中返回 OTP 代码，并未集成到短信或电子邮件服务提供商中 ## 致谢 # <<<<<<< HEAD 作为毕业设计 (FYP) 构建，探索混合 AI 系统在金融犯罪检测中的应用。FinSight AI 是一个**研究原型和模拟的金融合规平台**，它不是经过认证的银行产品，也未经真实交易数据或监管 AML 标准验证。合成数据集、检测阈值和评分权重仅供学术演示使用。 作为毕业设计 (FYP) 构建，探索混合 AI 系统在金融犯罪检测中的应用。FinSight AI 是一个**研究原型和模拟的金融合规平台**，它不是经过认证的银行产品，也未经真实交易数据或监管 AML 标准验证。合成数据集、检测阈值和评分权重仅供学术演示使用。

标签：Apex, Flask, React, Syscalls, 反洗钱, 异常检测, 机器学习, 逆向工具, 金融风控