内容
实时欺诈检测平台
实时电商欺诈检测平台，提供全栈解决方案。
交易数据通过 REST API 接收，异步处理后通过 Kafka 进行流式处理，结合 Redis 支持的规则引擎进行评估，结果通过 Dashboard 和 MCP 工具对外提供。
## 目录
- [项目概述](#项目概述)
- [架构和技术栈](#架构和技术栈 [技术选择和原因选择和原因)
-结构](#项目目录- [快速](#快速启动-docker)
- [欺诈决策逻辑 3 规则](#逻辑-2/3-规则)
- [测试](#测试和模拟)
API 和 WebSocket api-和-websocket-概述)
- [MCP AI集成](#mcp-ai集成)
- [本地开发开发)
- [故障排除](#故障排除)
## 项目项目专注于早期发现可疑交易：
- 提供实时交易流和欺诈警报面板
- 报告基于状态和历史行为
- 为 AI 代理提供 MCP 直接查询
## 架构栈
### 后- Java 21
- Spring Boot（REST API，Socket，Actuator）
- JPA + Flyway Spring Kafka
- Spring
- Spring AI MCP Server
### 前端
- Vite + TypeScript
charts，React Query，Z
- Nginx（）
### 基础设施
Compose
- PostgreSQL
- Redis
- Kafka + Zookeeper
### 数据流
1. 客户端通过 `POST /api/v1/transactions`数据
2. 应用记录发布到 `transactions 主题
3. 消费者运行欺诈规则
写入数据库（`APPROVED` 或 `FRA5. 通过 WebSockettopic/transactions` 和/fraud-alerts`
6. MCP 工具向 AI 客户端提供欺诈和用户风险数据
## 技术选择和原因
- **Redis（规则引擎和缓存管理）**：在异常和欺诈检测中，特别是在速度和平均金额控制中，实时跟踪计数器至关重要。Redis 的内存性质和快速读写性能有助于最小化延迟。
- **Kafka（异步处理）**：选择 Kafka 来缓冲大量的交易流，解耦欺诈分析与主应用，以减少延迟。
- **Java 21 & Spring Boot**：由于其高并发支持、企业的可扩展性和模块化集成 AI 组件的能力。
- **React & WebSocket**：为了实时显示交易日志和欺诈警报。
## 项目目录结构
以下结构总结了存储库中的主要文件夹和关键文件：
```text
sentinel-fraud-detection/
|-- docker-compose.yml
|-- Dockerfile
|-- pom.xml
|-- README.md
|-- .env.example
|-- manual
|-- auto
|-- src/
| main/
| | |-- java/com/f/sentinel_fraud_detection/
| | |-- transaction/
| | | |-- fraud/
| | | |-- kafka/
| | |-- websocket/
| | | |-- mcp/
| | | `-- user/
| | `-- resources/
| | |-- application.yml
| | `-- db/migration/
| `-- test/
|-- frontend/
| |-- Dockerfile
| |-- package.json
| |-- src/
| | |-- api/
| | |-- components/
| | |-- hooks/
| | |-- pages/
| | |-- store/
| | |-- types/
| | `-- utils/
| `-- public/
`-- script/
|-- transaction_simulator.py
|-- mcp_server.py
`-- README.md
```
## 快速启动 Docker
### 环境变量
项目附带 `.env.example` 文件，其中包含默认值。您需要为后端和前端应用程序设置 `.env` 以使它们能够相互连接。
**Linux / macOS：**
```bash
cp .env.example .env
cp frontend/.env.example frontend/.env.local
```
**Windows (PowerShell)：**
```powershell
Copy-Item .env.example -Destination .env
Copy-Item frontend/.env.example -Destination frontend/.env.local
```
### 启动容器
确保系统上安装了 Docker 和 Docker Compose。在项目目录中运行bash
docker-compose up -d --build
```
- 前端：://localhost:5173`
- 后端 API：`http://localhost:8081`
- Swagger UI：`http://localhost:8081/swagger-ui.html`
- 健康检查：`http://localhost:8081/actuator/health`
停止服务：
```bash
docker compose down
```
## 欺诈决策逻辑 2/3 规则
如果交易违反以下 3 条规则中的至少 2 条，则视为欺诈：
- 速度：最近 60 秒内超过 5 笔交易
- 金额：超过最近 24 小时平均金额的 3 倍
- 地点：物理上不可能的位置跳转
分- 0-违规 -> 低风险
2 次违规 -> 中风险（欺诈）
- 3 次违规 -> 高风险（欺诈）
## 测试和模拟
### 手动测试
```bash
./manual-input.sh 11111111-1111-1111-1111-111111111111 450.75 Istanbul
```
### 自动流量和异常注入
```bash
./auto-test.sh --duration=60 --rate=8 --anomaly-chance=35
```
### 干运行 payload 检查
```bash
./auto-test.sh --duration=10 --rate=2 --anomaly-chance=25 --dry-run
```
### Python 模拟器场景
```bash
python script/transaction_simulator.py --scenario all
python script/transaction_simulator.py --scenario velocity --velocity-count 10 --velocity-window 1
python script/transaction_simulator.py --scenario amount --amount-baseline-count 8 --amount-spike 50000
```
## API 和 WebSocket 概述
### 交易 API
- `POST /api/v1/transactions`
- `GET /api/v1/transactions/users/{userId}`
- `api/v1/transactions/fraud?from=......`
-api/v1/{transactionId}`
### 用户 API
- `/v1/users/{userId}/status`
- Swagger：`http://localhost:8081.html`
- OpenAPI：`http://localhost:3/api-docs`
### WebSocket
- 端`ws://localhost:8081/ws`（SockJS/STOMP）
- 主题：
- `/topic/transactions`
- `/topic/fs`
## MCP AI 代理集成
MCP 工具在后端定义：
- `get_recent_frauds`
- `check_user_status`
资源：
- `src/main/java/com/furkanerd/sentinel_fraud_detection/mcp/McpToolsConfig.java`
- `src/main/resources/application.yml`
示例 MCP 客户端配置：
```json
{
"mcpServers": {
"sentinel-fraud": {
"url": "http://localhost1/mcp"
}
}
}
```
示例提示：
- `获取最近 30 分钟内的欺诈交易。`
- `检查用户 11111111-1111-1111-1111-111111111111 的风险状态。`
## 本地开发
如果您想在 Docker工作：
后端：
```bash
./mvnw spring-boot:run
：
```bash
cdnpm install
npm run dev
```
##
- 端口冲突：`8081`、`5173`、`5432`、`6379`、`9092`、`2181` 可能已占用
- 前端 API 连接失败：检查 `frontend/src/config.ts` 和 `V_BASE_URL` 的值
- Kafka 连接：在容器内kafka:909，在主机上使用:29092`
-检查应用程序是否CP URL 是否配置匹配
## 联
- LinkedInFurkan Erdoğan](https.linkedin.com/in/furkan/)
- Github：kanerd1](https://github.com/furkanerd- 邮箱：furdd1@gmail.com
---
本 README 文件基于存储现有文件结构和。
