Goh-Sim-Yng-Nicole/fraudulent-transaction-detection-system-

# FTDS - 欺诈交易检测系统 FTDS 是一个基于 Docker 的微服务平台，用于银行交易、欺诈评分、分析师审查、申诉、审计日志、分析和可观测性。 它的构建旨在演示端到端的欺诈工作流程： - 客户注册、使用 OTP 登录并提交交易 - 可疑交易被标记以供分析师审查 - 分析师认领并对案件做出决定 - 客户可以对被拒绝的结果提出申诉 - 经理监控欺诈和申诉结果 - 运维用户通过受保护的 ingress 访问 Grafana、Jaeger、Prometheus、cAdvisor 和 Mailpit ## 项目功能 - 基于 OTP 登录的客户银行业务流程 - 具有 Kafka 支持状态更新的交易服务 - 欺诈评分和欺诈编排 - 具有认领/释放/决策所有权的 manually 审查队列 - 具有所有权和可审计性的申诉流程 - 面向欺诈经理的分析仪表板 - 具有完整性验证的审计追踪 API - 通过 Mailpit 进行本地 SMTP 的通知服务 - 使用 Grafana、Prometheus、Jaeger、cAdvisor 和 OpenTelemetry 的可观测性 - 通过 Nginx 为员工和运维人员提供基于角色的 ingress ## 核心架构 ``` Customer UI / Staff UI / Manager UI -> Nginx -> Kong -> Gateway Gateway routes to: -> Customer -> Transaction -> Fraud Review -> Appeal -> Analytics -> Audit Fraud pipeline: Transaction -> transaction.created -> detect_fraud -> fraud_score -> transaction.scored -> decision (local Kafka consumer) -> optional OutSystems decision handoff modes Decision events: -> transaction.flagged -> transaction.finalised -> transaction.reviewed -> appeal.created -> appeal.resolved Observability: -> OpenTelemetry Collector -> Jaeger -> Prometheus -> Grafana -> cAdvisor ``` ## 服务 | Service | Runtime | Port | Purpose | | -------------- | ---------------- | ---- | ----------------------------------------------------------------------------- | | `customer` | Python / FastAPI | 8005 | 注册、OTP 认证、个人资料、敏感账户操作 | | `transaction` | Python / FastAPI | 8000 | 交易创建、列表、状态、Kafka 驱动的更新 | | `fraud_score` | Node / Express | 8001 | ML 评分端点 | | `detect_fraud` | Python | 8008 | 规则 + ML 编排，发出 `transaction.scored` | | `decision` | Node / Express | 3005 | 消费已评分事件，持久化决策，发出 `transaction.flagged/finalised` | | `fraud-review` | Node / Express | 8002 | 标记审查队列和申诉审查队列 | | `appeal` | Node / Express | 8003 | 客户申诉 | | `analytics` | Node / Express | 8006 | 经理指标和实时仪表板数据 | | `audit` | Node / Express | 8007 | 审计事件存储和验证 | | `notification` | Node / Express | 8010 | 邮件 / 通知处理 | | `gateway` | Node / Express | 8004 | 公共 API 聚合和员工认证 | Docker Compose 现在包含一个本地独立 `decision` 服务。 `detect_fraud` 现在支持 3 种模式： - `local`: 在本地进行评分和决策，用于 Docker 开发和自动化测试 - `outsystems_http`: 在本地评分，然后调用外部 OutSystems 决策 API - `outsystems_kafka`: 在本地评分，发布 `transaction.scored`，并等待 Kafka 消费者（默认为仓库内的 `decision`，或外部 OutSystems 消费者）发布 `transaction.flagged` 或 `transaction.finalised` 对于 Kafka 决策架构（现在是默认的 Docker 设置），请使用： ``` DECISION_INTEGRATION_MODE=outsystems_kafka ENABLE_LOCAL_DECISION_FALLBACK=false OUTSYSTEMS_DECISION_URL= ``` 在该模式下，决策消费者应： 1. 消费 `transaction.scored` 2. 在内部持久化其自己的决策记录 3. 发布 `transaction.flagged` 或 `transaction.finalised` 本地 Docker 现在可以使用带有仓库内 `decision` 的 `outsystems_kafka` 完全独立运行。 ## UI 与访问 ### 主要 URL - 银行门户: [http://localhost:8088/banking.html](http://localhost:8088/banking.html) - 员工登录: [http://localhost:8088/staff-login.html](http://localhost:8088/staff-login.html) - 欺诈审查 UI: [http://localhost:8088/fraud-review.html](http://localhost:8088/fraud-review.html) - 经理仪表板: [http://localhost:8088/manager.html](http://localhost:8088/manager.html) - 公共边缘根目录: [http://localhost/](http://localhost/) - HTTPS 本地主机 ingress: [https://localhost/staff-login.html](https://localhost/staff-login.html) ### 员工角色 | Role | Default Login | Access | | --------------- | ---------------------------- | -------------------------------------------------------- | | `fraud_analyst` | `analyst` / `analyst123` | 欺诈审查 UI、标记案件、申诉审查 | | `fraud_manager` | `manager` / `manager123` | 欺诈审查 UI、经理仪表板 | | `ops_readonly` | `opsviewer` / `opsviewer123` | 经理仪表板、Grafana、Jaeger、Prometheus、cAdvisor | | `ops_admin` | `opsadmin` / `opsadmin123` | ops-readonly 可访问的所有内容，加上 Mailpit | 这些凭据仅用于本地/演示用途。 ### 受保护的可观测性 URL - Grafana: [http://localhost:3000](http://localhost:3000) - Jaeger: [http://localhost:16686](http://localhost:16686) - Prometheus: [http://localhost:9090](http://localhost:9090) - cAdvisor: [http://localhost:9091](http://localhost:9091) - Mailpit: [http://localhost:8025](http://localhost:8025) 这些路由通过 Nginx 反向代理提供服务，旨在供员工/运维人员访问，而非客户。 ## 案件所有权 标记的审查案件和申诉都会追踪经手人。 平台记录： - 谁认领了案件 - 他们当时拥有的角色 - 何时认领的 - 谁做出了最终决定 - 做出决定时他们拥有的角色 - 最终结果的说明/原因 这会在审查 API 中可见，并反映在 UI 中。 ## 快速开始 ### 1. 创建你的 env 文件 ``` Copy-Item .env.example .env ``` ### 2. 启动完整堆栈 ``` docker compose up -d --build --remove-orphans ``` ### 3. 打开主要入口点 - 客户: [http://localhost:8088/banking.html](http://localhost:8088/banking.html) - 员工: [http://localhost:8088/staff-login.html](http://localhost:8088/staff-login.html) - HTTPS 预演: [https://localhost/staff-login.html](https://localhost/staff-login.html) ## 演示指南 这是端到端演示项目的最简单方法。 ### 客户演示 1. 打开 [http://localhost:8088/banking.html](http://localhost:8088/banking.html)。 2. 注册一个新的客户账户。 3. 当登录要求输入 OTP 时，打开 [http://localhost:8025](http://localhost:8025) 的 Mailpit 并阅读最新的 OTP 邮件。 4. 验证 OTP 并进入银行门户。 ### 提交一笔正常交易 使用银行门户中的新交易表单。 示例值： - 收款人类型: `Pay Merchant (UEN)` - 商户 ID: `FTDS_NORMAL_DEMO` - 金额: `120.50` - 货币: `SGD` - 卡类型: `CREDIT` - 国家: `SG` ### 提交一笔标记交易 使用这些值可在当前本地堆栈中可靠地创建一个标记案件： - 收款人类型: `Pay Merchant (UEN)` - 商户 ID: `FTDS_FLAGGED_DEMO` - 金额: `3200` - 货币: `USD` - 卡类型: `PREPAID` - 国家: `NG` 经过短暂延迟后，交易状态应从 `PENDING` 变为 `FLAGGED`。 ### 分析师审查演示 1. 在 [http://localhost:8088/staff-login.html](http://localhost:8088/staff-login.html) 以如下身份登录： `analyst` / `analyst123` 2. 打开 [http://localhost:8088/fraud-review.html](http://localhost:8088/fraud-review.html)。 3. 认领标记的案件。 4. 批准或拒绝它。 如果您拒绝它，客户将看到交易变为 `REJECTED`。 ### 申诉演示 1. 在分析师 UI 中拒绝一笔标记的交易。 2. 返回客户银行门户。 3. 打开被拒绝的交易并提交申诉。 4. 返回分析师 UI。 5. 认领申诉并解决它。 ### 经理演示 1. 以 `manager` / `manager123` 身份登录。 2. 打开 [http://localhost:8088/manager.html](http://localhost:8088/manager.html)。 3. 展示： - 交易总数 - 批准/拒绝率 - 人工审查 - 申诉数量 - 实时决策质量指标 ### 运维演示 1. 以 `opsviewer` 或 `opsadmin` 身份登录。 2. 打开经理仪表板和可观测性链接。 3. 展示： - Grafana 仪表板 - Jaeger 服务追踪 - Prometheus 目标/指标 - cAdvisor 容器指标 - 包含 OTP 和警报邮件的 Mailpit 收件箱 ## 测试 ### 可用命令 从仓库根目录： ``` npm.cmd run test:unit npm.cmd run test:smoke npm.cmd run test:contracts npm.cmd run test:e2e npm.cmd run test:verify ``` `test:verify` 运行： ``` unit -> smoke -> contracts -> e2e ``` ### 测试覆盖范围 - 针对活动的 Python 欺诈和交易逻辑以及 Node 分析逻辑的单元测试 - 跨所有主要服务表面的冒烟检查 - 针对 API、受保护 UI、可观测性端点、Kafka topic 和消费者延迟的契约检查 - 完整的端到端流程，涵盖： - 注册 - OTP 验证 - 密码轮换 - 账户删除 - 标记交易审查 - 申诉创建和解决 - 分析更新 - 审计追踪存在性 ### 推荐验证流程 ``` docker compose up -d --build --remove-orphans npm.cmd run test:verify ``` ## CI 和代码质量 ### CI GitHub Actions 运行： - `npm run quality` - `npm run test:unit` - Docker Compose 验证 - 全堆栈构建 - `test:smoke` - `test:contracts` - `test:e2e` 工作流位于 [`.github/workflows/ci.yml`](C:/Users/Naren/Documents/SMU/y2s2/ESD/project2/fraudulent-transaction-detection-system-/.github/workflows/ci.yml)。 ### 本地质量命令 ``` npm.cmd run lint:js python -m ruff check services/customer services/transaction services/detect_fraud ftds testing/unit_py npm.cmd run format:check npm.cmd run quality ``` ## 安全和本地部署说明 - Nginx 充当员工页面和可观测性工具的感知角色反向代理。 - `https://localhost` 使用自签名证书进行本地预演，因此在您信任该证书之前，浏览器会发出警告。 - Kong 是端口 `80` 上的公共 API 边缘。 - 员工会话由 gateway 签名，并由 Nginx 再次检查以保护页面。 - 本地 Mailpit 用于 OTP 和通知邮件传递。 - 当 Redis 被禁用时，Analytics 当前使用内存中投影运行，因此如果重新创建 analytics 容器，指标将重置。 - 仅将默认本地凭据用于本地开发。 ## 仓库结构 ``` services/ customer/ transaction/ fraud_score/ detect_fraud/ decision/ process_flagged_appeals/ appeal/ analytics/ audit/ notification/ gateway/ ui/ banking.html staff-login.html fraud-review.html manager.html forbidden.html testing/ smoke-health.mjs service-contracts.mjs e2e-platform.mjs unit/ unit_py/ ``` ## 实用说明 - OTP 会投递到 [http://localhost:8025](http://localhost:8025) 的 Mailpit。 - 本地 `https://localhost` 上出现自签名证书警告是预期的。 - 如果重建后经理仪表板看起来停滞不前，请在生成新事件后刷新。 - 如果连接了 OutSystems，可以通过切换 `DECISION_INTEGRATION_MODE` 将决策移交到外部。

标签：Apex, API网关, API集成, cAdvisor, Docker, GET参数, Grafana, Jaeger, Kafka, Kong Gateway, Mailpit, MITM代理, Nginx, NIDS, OpenTelemetry, OTP验证, Python, React, SMTP, SOA, SonarQube插件, Spring Boot, Syscalls, 事件驱动架构, 云计算, 人工审核, 代码示例, 反欺诈, 可观测性, 学术项目, 安全防御评估, 审计日志, 容器化, 工作流引擎, 微前端, 微服务架构, 搜索引擎查询, 数据分析, 无后门, 服务编排, 机器学习, 用户代理, 申诉管理, 自定义脚本, 自定义请求头, 规则引擎, 请求拦截, 逆向工具, 金融欺诈检测, 银行交易系统, 风控系统