bartoszbryg/tx-sieve

# 实时支付欺诈检测系统 我在网上看到的大多数后端项目，都只停留在有趣问题刚开始的地方。但这个项目不同。 支付欺诈检测：高吞吐量、异步决策、JWT 安全、基于规则和基于图的分析。逐阶段构建，设计决策在制定时同步记录。 ## 阶段 0 —— 编写任何代码前我回答的三个问题 ### 1. 这个系统究竟做什么？ 用户提交一笔支付。系统实时决定其是否为欺诈。决策在几毫秒内发生，而不是几分钟。 - 如果是欺诈：阻止交易并保存警报 - 如果是正常：处理交易，转移余额 就是这样。这个仓库中的一切都是为了让这一条流程正确、安全且大规模地运行而存在的。 ### 2. 核心约束条件是什么？ 这些不是偏好——它们是架构从第一天起就必须满足的要求： **高吞吐量** —— 支付是突发性的。系统不能在分析欺诈时阻塞 HTTP 线程。需要队列和异步 worker。 **实时** —— 欺诈的时间窗口只有几分钟宽。每日的电子邮件报告毫无用处。分析师需要一个在检测到欺诈瞬间立即更新的实时仪表盘。WebSocket 推送计划在下一阶段实现；当前阶段会持久化警报并暴露仪表盘统计数据。 **安全** —— 这是一个银行系统。除了登录外，每个 endpoint 都需要身份验证。JWT token，无状态，基于角色的访问控制。客户和系统操作员是独立的安全主体——将它们混为一谈是设计缺陷。 **可观测** —— 你无法调整你无法测量的东西。队列深度、规则触发次数、分析延迟、欺诈率——所有这些都从第一天起就作为 Prometheus 指标暴露出来。 **可解释** —— 在银行业，没有给出原因的拦截决策在法律上是不充分的。每个触发的欺诈规则都必须留下一条类型化的、可审计的记录，说明它发现了什么以及为什么。 ### 3. 核心组件有哪些？ ``` Java Spring Boot └── REST API (payments, users, alerts, dashboard) └── JWT security layer └── Fraud detection engine (rule-based + graph-based) └── Bounded queue + worker thread pool └── WebSocket broker (Phase 11, real-time analyst alerts) └── Prometheus metrics + Spring Actuator Python FastAPI (Phase 15) └── Statistical ML model (GradientBoosting) └── Feature engineering └── /score endpoint — returns fraud probability 0.0–1.0 H2 in-memory database (dev) / PostgreSQL (prod) Docker Compose (Phase 17) └── Wires both services together └── Health checks before Java starts ``` 目前，Java 负责处理交易、安全、欺诈规则、图分析以及异步 worker pipeline。Python 的统计异常检测属于后续阶段。当它接入时，如果 Python 不可用，Java 将继续运行基于规则的评分。设计上实现松耦合。 ## 架构 —— 目标全景图 ``` User submits payment (HTTP POST, JWT authenticated) │ ▼ PaymentService validates: sender exists, balance sufficient │ ▼ Transaction saved with status PENDING │ ▼ Enqueued to LinkedBlockingQueue (capacity: 10,000) API thread returns immediately — async from here │ ▼ Worker pool (4 threads) picks up transaction │ ▼ FraudDetectionEngine runs all rules in priority order │ ├── HighAmountRule > $10k warning / > $50k critical ├── RapidTransactionRule 3+ transactions in 5 minutes ├── VelocityBreachRule daily > $20k or hourly > $5k ├── BlacklistedMerchantRule merchant on known-bad list ├── UnusualLocationRule country differs from home ├── GraphFraudRule cycle detection via JGraphT └── MlFraudRule Python model probability ≥ 0.4 │ ▼ Scores accumulate (capped at 100) │ ├── score < 40 → APPROVED ├── score 40–69 → FLAGGED FOR REVIEW + alert saved └── score ≥ 70 → BLOCKED + alert saved + WebSocket broadcast (Phase 11) + no balance deduction ``` ## 为什么选择这些技术 | 技术 | 原因 | |---|---| | **Java 21 + Spring Boot 3.2** | 金融后端的生产标准。支持虚拟线程。Spring Boot 将配置保留在 YAML 中，而不是样板代码。 | | **JWT (无状态认证)** | 无需服务端 session 存储。每个请求都自我验证。这是水平扩展的必要条件。 | | **H2 (开发) / PostgreSQL (生产)** | H2 无需任何设置——应用程序无需外部依赖即可启动。生产环境通过环境变量进行切换，无需修改代码。 | | **LinkedBlockingQueue** | 在没有基础设施的情况下模拟 Kafka。有限的容量意味着背压是明确的：队列满 = 503，而不是崩溃。 | | **JGraphT** | 基于规则的评分单独查看每笔交易。而图能发现协同欺诈——洗钱团伙、骡子账户——这些是个别规则完全遗漏的。 | | **WebSocket / STOMP** | 计划在阶段 11 实现。HTTP 轮询会增加延迟并浪费连接；STOMP 推送将在交易被拦截的瞬间将警报传递到仪表盘。 | | **Python FastAPI + GradientBoosting** | 计划在阶段 15 实现。基于规则的系统能捕获已知模式。ML 能捕获不符合任何既定规则的异常。作为独立服务，这样 Python 崩溃时永远不会导致 Java API 宕机。 | | **Micrometer + Prometheus** | 每个欺诈规则触发、队列深度和分析持续时间都是一个指标。欺诈系统需要调优——你用数据调优，而不是靠猜测。 | | **Resilience4j 熔断器** | 计划在 ML 集成阶段实现。如果 Python ML 服务缓慢或宕机，熔断器就会打开，Java 就会停止尝试。 | | **Lombok + MapStruct** | 注解处理器在编译时生成样板代码，运行时零开销。Lombok 现在负责处理 getter/构造函数；如果映射需求超出了目前简单的 `TransactionMapper`，则可使用 MapStruct。 | | **金额使用 BigDecimal** | `double` 会丢失分位。在浮点数中 0.1 + 0.2 = 0.30000000000000004。银行对舍入误差负有法律责任。 | ## 构建顺序 我是按照依赖关系强制的顺序构建的——如果没有 entity，你就无法编写 service；如果没有配置好项目，你就无法编写 entity。 | 阶段 | 构建内容 | 文档 | |---|---|---| | **0** | 完成架构设计，暂无代码 | | | **1** ✅ | `pom.xml` + 入口程序 + YAML 配置（开发/生产分离） | [文档](docs/phase-01-project-foundation.md) | | **2** ✅ | 领域枚举：`TransactionStatus`、`RiskLevel`、`FraudRuleType` | [文档](docs/phase-02-project-enums-creation-for-states.md) | | **3** ✅ | JPA entity：`User`、`AppUser`、`Transaction`、`FraudAlert`、`MerchantBlacklist`、`UserSession` | [文档](docs/phase-03-project-jpa-entities.md) | | **4** ✅ | Repositories + 自定义欺诈查询 (`@Query`) | [文档](docs/phase-04-project-repository-for-jpa.md) | | **5** ✅ | DTO —— 请求/响应对象，永远不暴露原始 entity | [文档](docs/phase-05-project-dto-mapping.md) | | **6** ✅ | 类型化异常 + `GlobalExceptionHandler` | [文档](docs/phase-06-project-exception-handling.md) | | **7** ✅ | JWT 安全：token 提供者、过滤器、`UserDetailsService` | [文档](docs/phase-07-project-security-handling.md) | | **8** ✅ | 欺诈引擎：`FraudRule` 接口、5 条规则、图分析、编排器 | [文档](docs/phase-08-project-fraud-detection-engine.md) | | **9** ✅ | Services：`AuthService`、`UserService`、`PaymentService`、`FraudAlertService`、`DashboardService`、`MlFraudScoringService`、`TransactionMapper` | [文档](docs/phase-09-project-service-layer.md) | | **10** ✅ | 队列 + worker 池：`TransactionQueue`、`TransactionWorkerPool`、欺诈结果路由 | [文档](docs/phase-10-project-queue-worker-pool.md) | | **11** | WebSocket / STOMP 实时警报广播 | | | **12** | Spring 配置类：安全、WebSocket、缓存、异步、OpenAPI | | | **13** | `DataSeeder` —— 启动时加载演示数据 | | | **14** | REST controller —— 轻量级层，无业务逻辑 | | | **15** | Python FastAPI ML 服务 + GradientBoosting 模型 | | | **16** | `MlFraudRule` —— Java `<->` Python HTTP 集成 | | | **17** | Docker + Docker Compose —— 两个服务均接入健康检查 | | | **18** | 测试：单元测试（规则、引擎、服务）+ 集成测试（controller） | | 每个阶段标签都链接到该具体阶段的代码仓库。你可以浏览在任何 service 层出现之前、在添加安全机制之前、在队列存在之前的代码——完整的构建序列都是可见的。 ## 本项目的教学意义 这个项目中的每一个架构决策之所以存在，都是因为真实的银行系统需要它。这不是我凭空发明的设计——它是你从第一性原理进行推理时，由约束条件自然产生的设计。 理解一个设计决策*为什么*存在，比仅仅知道*如何*实现它更有价值。这个项目对两者都进行了记录。

标签：域名枚举, 测试用例, 自定义请求头, 请求拦截, 逆向工具