内容
# 金融风控系统 Finxiom
Finxiom 是一个面向生产的金融风控系统，用于检测金融欺诈和反洗钱合规。它可以处理单个交易或批量支付批次，运行一个受控的多代理调查流程，生成可追溯的风险决策和 SAR（可疑活动报告）草稿，并在采取不可逆转的行动（如提交 SAR 或账户冻结模拟）之前需要人工审批。
这不是一个聊天机器人。系统发起分析，在专家代理之间路由输入，构建关系证据，匹配欺诈类型，评估风险，准备审查包，并记录审计轨迹。
---
## 快速入门 — 一条命令
**前提条件：** [Docker Desktop](https://docs.docker.com/get-docker/) · [uv](https://docs.astral.sh/uv/getting-started/installation/) · [Node.js 18+](https://nodejs.org/)
```bash
git clone <repo-url> finxiom
cd finxiom
bash install.sh
```
`install.sh` 一步完成所有操作：
| 步骤 | 操作 |
|---|---|
| 前提条件检查 | 验证 Docker、uv、node、npm 是否可用 |
| `.env` 生成 | 复制 `.env.example`，生成随机安全密钥，可选提示输入 `OPENAI_API_KEY` |
| `frontend/.env.local` | 自动创建（无需手动编辑） |
| Docker 基础设施 | 拉取并启动 Postgres、Redis、Neo4j、Qdrant、MinIO、Langfuse、Jaeger、Prometheus、Grafana、Kong |
| Python 依赖 | `uv sync --locked --all-groups` |
| 数据库迁移 | `alembic upgrade head` |
| 示例数据 | 植入捆绑的 AML 示例交易 |
| Node 依赖 | `npm install` |
| 应用启动 | 启动后端（端口 8010），MCP 服务器（端口 8020），和 Next.js 开发服务器（端口 3001） |
一旦运行，打开 **http://localhost:3001** 并在 **http://localhost:3001/admin** 使用管理控制台。
> **没有 OpenAI 密钥？** 系统在 *确定性备用模式* 下完全可用 — 所有代理逻辑在没有实时 LLM 调用情况下运行。在 `install.sh` 提示输入 API 密钥时按 Enter 键跳过它。
### 之后的运行（第一次安装后）
```bash
bash start.sh # 启动应用 + Docker（跳过安装步骤）
bash start.sh --bg # 在后台启动
bash stop.sh # 停止应用进程（Docker 继续运行）
bash stop.sh --all # 停止所有内容，包括 Docker
```
或使用 Make：
```bash
make install # 完整安装 + 启动（与 bash install.sh 相同）
make start # 快速启动
make stop # 停止应用
```
### 完全容器化（仅 Docker，无本地 Node/uv）
```bash
cp .env.example .env # 编辑密钥后再继续
docker compose --env-file .env \
-f infra/docker-compose.yml \
-f infra/docker-compose.app.yml \
up --build
```
这将构建并运行 FastAPI 后端、Celery 工作线程和 MCP 服务器作为 Docker 容器，与基础设施一起。Next.js 前端仍然需要在本地运行（`npm run dev`），因为 `NEXT_PUBLIC_*` 环境变量在构建时嵌入。
---
## Finxiom 的功能
- 分析金融交易的结构、壳公司流动、跨境风险、高价值电汇和相关的反洗钱模式。
- 接受具有 ISO 20022、Fedwire、SWIFT MT103、ACH、参与方、银行、汇款和合规背景字段的现实 JSON 和 CSV 批量上传。
- 在保留有序专家代理证据链的情况下，以有界并行工作线程池运行批量行。
- 在现代分析师 UI 中显示实时案件进度，带有仪表盘、案件、案件详情选项卡、批量上传、管理策略控制、图形遍历、SAR 草稿和人工审查包。
- 显示具有网关/身份验证状态、Postgres 持久性、附加审计防护、Celery 工作线程状态、MCP 状态、OpenAI 模式、Langfuse 状态、示例文件和操作开始前注意事项的操作就绪控制室。
- 通过 MCP 为批准的外部代理和企业自动化客户端提供受控的调查工具。
- 使用基于风险的人工监督：分析师验证结论、假设、例外、声明到源映射和高影响动作，而不是手动重新阅读每个代理令牌。
- 存储每个案件，并带有 `created_at` 和 `processed_at` 时间戳、交易、最终交接、SAR 草稿、时间线、状态和审计事件。
- 允许分析师在批准前编辑和保存 SAR 草稿；编辑后的草稿在警报代理运行前持久化到案件和审计账本中。
- 支持 `LLM 模式：OpenAI 直播` 和 `LLM 模式：确定性备用`，因此应用程序在没有外部模型调用的情况下保持运行。
- 通过 Langfuse、OpenTelemetry、Jaeger、Prometheus 和 Grafana 发出跟踪、指标和操作信号。
## 架构
```mermaid
flowchart TD
A["单个交易<br/>或批量 JSON/CSV 上传"] --> AA["批量工作线程池<br/>有界行并发"]
X["Next.js 分析师 UI"] --> GW["Kong API 网关<br/>速率限制 + JWT 边缘检查"]
AA --> GW
GW --> B["FastAPI API<br/>Pydantic 验证 + 作用域 JWT"]
B --> CW["Celery 工作线程<br/>异步代理流水线队列"]
CW --> C
B --> C["协调器代理<br/>零工具，仅路由"]
C --> D["预算信封<br/>回合、工具、重试、运行时、令牌、重复操作防护"]
D --> E["摄取代理<br/>规范化、增强、重复数据删除、持久化有效载荷"]
E --> F["图代理<br/>实体图、3 跳遍历、环和壳检测"]
F --> G["模式代理<br/>类型嵌入、相似性、异常聚类"]
G --> H["风险代理<br/>评分策略、结构化输出 SAR 草稿、审查包"]
H --> I{"风险和置信度门控"}
I -->|"低风险"| J["自动解决<br/>仅审计"]
I -->|"高风险"| K["人工门控<br/>批准或拒绝"]
I -->|"预算或进度停止"| L["需要人工输入<br/>状态摘要 + 下一个问题"]
K -->|"批准"| M["警报代理<br/>SAR 提交模拟、冻结模拟、审计账本"]
K -->|"拒绝"| N["拒绝操作<br/>附加审计"]
B --> O["PostgreSQL<br/>案件、审计、关系状态"]
E --> P["Redis 堆栈<br/>缓存、重复数据删除、事件扇出"]
E --> Q["MinIO<br/>原始有效载荷快照"]
F --> R["Neo4j<br/>实体关系图"]
G --> S["Qdrant<br/>欺诈类型向量搜索"]
H --> T["OpenAI API<br/>代理 SDK、模型、嵌入、结构化输出"]
H --> U["Langfuse<br/>LLM 跟踪和声明上下文"]
B --> V["OpenTelemetry<br/>Jaeger 跟踪"]
B --> W["Prometheus + Grafana<br/>指标和仪表盘"]
Y["Finxiom MCP 服务器<br/>stdio 或可流式 HTTP"] --> B
```
## 代理工作流
1. **协调器代理** 接收验证的交易并创建类型交接。它按设计没有工具。
2. **摄取代理** 规范化支付字段，增强对手方，检查重复交易 ID，并存储原始有效载荷上下文。
3. **图代理** 构建源、目的地、参与方和对手方关系，然后执行遍历和壳环检查。
4. **模式代理** 嵌入交易上下文，搜索欺诈类型，评估异常信号，并聚类近期活动。
5. **风险代理** 将可配置的策略权重、置信度评分、图查找、类型匹配、源证据和自动检查结合成最终风险评分和 SAR 草稿。
6. **人工门控** 在分析师批准或拒绝案件之前阻止高影响动作。
7. **警报代理** 仅在批准后运行，并将 SAR/冻结模拟追加到审计账本。
每个自主运行都受到预算信封的约束：最大回合、工具调用、重试、运行时、输出令牌、总令牌预算和重复/无进展动作限制。如果运行停止进展，Finxiom 终止运行，总结当前状态，并请求人工输入。
## 技术栈和原理
| 层 | 技术 | 使用原因 |
|---|---|---|
| 后端 API | Python 3.12、FastAPI、Pydantic v2 | 异步 API 接口、强大的请求/响应验证、OpenAPI 文档、简单的类型代理交接。 |
| API 网关 | Kong Gateway | 面向网关的操作路径、速率限制和 JWT 边缘验证，在受保护的流量到达 FastAPI 之前。 |
| 异步执行 | Celery、Redis 代理 | 生产环境下的异步代理流水线执行的成形工作线程路径。 |
| Python 打包 | uv、`pyproject.toml`、`uv.lock` | 快速确定性的后端/MCP 安装、锁定文件可复制性和现代 Python 项目命令。 |
| 代理运行时 | OpenAI 代理 SDK 集成、OpenAI Python SDK | 多代理交接、模型调用、嵌入和结构化 SAR 样式输出（启用实时模式时）。 |
| 代理集成 | 模型上下文协议 SDK | 在不重复业务逻辑的情况下，将 Finxiom 调查、审计和人工门控工作流暴露给批准的外部代理。 |
| 本地备用 | 确定性评分和增强路径 | 在无模型凭证或网络访问的情况下，可靠的离线操作和可测试性。 |
| 前端 | Next.js 15、React 19、TypeScript | 现代应用路由器 UI，带有类型化组件和快速本地开发。 |
| UI/可视化 | Tailwind CSS、lucide-react、D3、Recharts | 密集的分析师 UI、图标驱动的控件、实时力图遍历和风险图表。 |
| 关系数据 | PostgreSQL 16 | 持久运行时案例/审计 JSON 存储 + Langfuse 后备存储。 |
| 图数据 | Neo4j 5 社区版 | 实体关系遍历和网络风险建模。 |
| 向量搜索 | Qdrant | 具有 HNSW 向量索引的欺诈类型相似性搜索。 |
| 缓存/事件 | Redis 堆栈 | 快速重复数据删除、缓存和事件扇出模式。 |
| 对象存储 | MinIO | S3 兼容的本地存储，用于原始有效载荷和证据快照。 |
| LLM 可观察性 | Langfuse | 跟踪模型调用、跨度、提示、输出和决策上下文。 |
| 分布式跟踪 | OpenTelemetry、Jaeger | 跨服务跟踪 API 和流水线执行。 |
| 指标 | Prometheus、Grafana | 监控请求数、延迟、风险评分、流水线运行和断路器状态。 |
| 质量 | pytest、ruff、mypy | 后端代码的回归测试、 linting 和静态检查。 |
| 本地基础设施 | Docker Compose | 数据库、图、向量、缓存、存储和可观察性服务的重现支持栈。 |
## 仓库地图
```text
finxiom/
├── backend/ # FastAPI API、代理、模式、服务、测试
│ ├── finxiom_agents/ # 协调器和专家代理
│ ├── api/routes/ # 交易、批量上传、案件、审批、事件、管理、健康检查
│ ├── failsafes/ # 预算信封、上下文防护、重试、断路器
│ ├── observability/ # Langfuse 和 OpenTelemetry 助手、Prometheus 指标
│ └── tests/ # API、代理、模式和安全测试
├── frontend/ # Next.js 分析师应用程序
│ ├── app/ # 仪表盘、上传、案件、案件详情、管理员页面
│ ├── components/ # 图、遥测、SAR 预览、人工审查、管理员控件
│ └── public/samples/ # 批量上传示例文件
├── mcp_server/ # 受控外部代理访问的 MCP 服务器
├── infra/ # Docker Compose、Kong、Celery 工作线程和可观察性配置
├── data/seed/ # 单个交易有效载荷和欺诈类型示例
├── data/runtime/ # 本地生成的管理员策略存储，git 忽略
├── docs/ # 架构和现实输入模型说明
└── scripts/ # 工作流运行器、重置助手、作用域 JWT 生成器
```
## 前提条件
- Docker Desktop 或兼容的 Docker 引擎。
- 推荐 Python 3.12。
- Node.js 20 或更新版本。
- 用于实时模型模式的 OpenAI API 密钥。没有它，系统在确定性备用模式下运行。
## 环境设置
创建本地环境文件：
```bash
cd finxiom
cp .env.example .env
```
在共享或部署之前编辑 `.env`：
- 为 `LLM 模式：OpenAI 直播` 设置 `OPENAI_API_KEY`。
- 替换 `POSTGRES_PASSWORD`、`NEO4J_PASSWORD`、`MINIO_ACCESS_KEY`、`MINIO_SECRET_KEY` 和 `JWT_SECRET_KEY` 的本地值。
- 将 `.env` 存放在 git 之外。它已由 `.gitignore` 忽略。
- 使用 `NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8080` 作为操作前端，以便请求通过 Kong 进行。
- 分析师页面通过 `/runtime/scoring-policy` 读取显示阈值，带有 `cases:read`。
- 管理策略/就绪调用不使用浏览器可见的令牌。它们通过管理员密码、签名的 HTTP-Only 管理会话 cookie 和服务器生成的 `admin:*` JWT 进行保护。
- 对于后端开发，直接调用 `http://127.0.0.1:8010` 仍然受支持。
- 保持 `JWT_SECRET_KEY` 与 `infra/kong/kong.yml` 中的 Kong JWT 密钥对齐，如果您替换本地值。
## 本地运行
Python 服务使用 `uv` 作为主要的包管理器。如果需要，请先安装它：
```bash
python3 -m pip install uv==0.9.17
```
启动 Docker 支持栈：
```bash
docker compose --env-file .env -f infra/docker-compose.yml up -d
```
这将启动 Postgres、Redis、Celery 工作线程、Neo4j、Qdrant、MinIO、Langfuse、Jaeger、Prometheus、Grafana 和 Kong。
安装后端依赖：
```bash
cd backend
uv sync --locked --all-groups
cd ..
```
运行数据库迁移：
```bash
cd backend
uv run --locked alembic upgrade head
cd ..
```
安装前端依赖：
```bash
cd frontend
npm install
cd ..
```
启动后端 API：
```bash
cd backend
uv run --locked uvicorn main:app --host 127.0.0.1 --port 8010 --reload
cd ..
```
在第二个终端，启动前端：
```bash
cd frontend
export NEXT_PUBLIC_APP_JWT="$(uv --project ../backend run --locked python ../scripts/generate_jwt.py --subject app-ui --scopes transactions:write,cases:read,cases:approve)"
env_value() { grep -m1 -E "^$1=" ../.env 2>/dev/null | sed 's/^[^=]*=//'; }
export ADMIN_PASSWORD="$(env_value ADMIN_PASSWORD)"
export JWT_SECRET_KEY="$(env_value JWT_SECRET_KEY)"
export GATEWAY_JWT_ISSUER="$(env_value GATEWAY_JWT_ISSUER)"
NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8080 \
FINXIOM_SERVER_API_BASE_URL=http://127.0.0.1:8080 \
NEXT_PUBLIC_APP_JWT="$NEXT_PUBLIC_APP_JWT" \
ADMIN_PASSWORD="$ADMIN_PASSWORD" \
JWT_SECRET_KEY="$JWT_SECRET_KEY" \
GATEWAY_JWT_ISSUER="${GATEWAY_JWT_ISSUER:-finxiom}" \
npm run dev
```
在第三个终端，可选地以流式 HTTP 模式启动 MCP 服务器：
```bash
export FINXIOM_MCP_BEARER_TOKEN="$(uv --project backend run --locked python scripts/generate_jwt.py --subject mcp --scopes transactions:write,cases:read,cases:approve,admin:read,admin:write)"
uv --project backend run --locked python -m mcp_server.server --transport streamable-http --host 127.0.0.1 --port 8020
cd ..
```
检查 Docker 栈：
```bash
docker compose --env-file .env -f infra/docker-compose.yml ps
cd ..
```
停止本地服务：
```bash
docker compose --env-file .env -f infra/docker-compose.yml down
cd ..
```
## 重启操作
使用重启实用程序，当端口卡住、Docker 服务需要干净的重新创建或工作站已空闲时。
```bash
bash scripts/restart_services.sh all
```
常见目标：
| 命令 | 它重启 |
|---|---|
| `bash scripts/restart_services.sh all` | Docker 支持栈、后端、前端、MCP。
| `bash scripts/restart_services.sh app` | 后端、前端和 MCP，确保基础设施正在运行。 |
| `bash scripts/restart_services.sh backend` | 端口 `8010` 上的 FastAPI 后端。
| `bash scripts/restart_services.sh frontend` | 端口 `3001` 上的 Next.js 前端。
| `bash scripts/restart_services.sh mcp` | 端口 `8020` 上的 Finxiom MCP 服务器。
| `bash scripts/restart_services.sh infra` | 所有 Docker 支持服务。
| `bash scripts/restart_services.sh observability` | Langfuse、Jaeger、Prometheus、Grafana。
| `bash scripts/restart_services.sh status` | Docker 状态、端口监听器、后端/前端检查。
| `bash scripts/restart_services.sh dependencies` | 每个目标的依赖项。
| `bash scripts/restart_services.sh mcp-smoke` | Finxiom MCP 服务器冒烟测试。
```
## 本地网址
| 服务 | 网址 |
|---|---|
| 主应用程序 | `http://localhost:3001/dashboard` |
| 批量上传 | `http://localhost:3001/upload` |
| 案件 | `http://localhost:3001/cases` |
| 管理控制台 | `http://localhost:3001/admin` |
| Kong 网关 | `http://127.0.0.1:8080` |
| FastAPI 文档 | `http://127.0.0.1:8010/docs` |
| 后端健康检查 | `http://127.0.0.1:8010/health` |
| 系统就绪性检查 | `http://127.0.0.1:8010/system/readiness` |
| 操作就绪性 API | `http://127.0.0.1:8010/operations/readiness` |
| MCP 可流式 HTTP 端点 | `http://127.0.0.1:8020/mcp` |
| Langfuse | `http://localhost:3000` |
| Grafana | `http://localhost:3002` |
| Prometheus | `http://localhost:9090` |
| Jaeger | `http://localhost:16686` |
| Neo4j 浏览器 | `http://localhost:7474` |
| MinIO 控制台 | `http://localhost:9001` |
Finxiom 管理控制台的密码从 `ADMIN_PASSWORD` 读取。在共享或部署环境之前，请更改本地开发值。
## 分步生产演练
使用此流程进行完整的端到端演练。
1. 确认应用程序正在运行：
```bash
APP_JWT="$(uv --project backend run --locked python scripts/generate_jwt.py --subject app-health --scopes cases:read)"
curl -H "Authorization: Bearer $APP_JWT" http://127.0.0.1:8080/health
```
响应包括当前的 LLM 模式、OpenAI 配置状态、模型名称和 Langfuse 状态，而不暴露密钥。
2. 打开管理控制台：
```text
http://localhost:3001/admin
```
使用本地管理员密码解锁管理控制台，然后单击就绪性选项卡，并确认 Kong、JWT 模式、OpenAI/Langfuse 模式、Postgres 案例存储、仅追加审计触发器、Celery 工作人员、MCP、示例文件和服务侦听器。
3. 打开主 UI：
```text
http://localhost:3001/dashboard
```
指出实时指标、运行时模式、Postgres 案例存储状态、MCP 状态、Langfuse 状态、最近的案例和类似分析师的布局。
4. 打开批量上传：
```text
http://localhost:3001/upload
```
上传其中一个示例文件：
```text
frontend/public/samples/sample_bulk_mixed.json
frontend/public/samples/high_risk_aml_bulk.json
frontend/public/samples/realistic_bulk_transactions.json
frontend/public/samples/realistic_bulk_transactions.csv
frontend/public/samples/clean_operations_bulk.csv
frontend/public/samples/validation_error_bulk.json
frontend/public/samples/sample_stress_realistic_50.json
frontend/public/samples/sample_stress_realistic_250.csv
```
5. 点击**批量运行代理**。
批量行通过有界并行工作线程池运行。默认工作线程限制为 `BULK_UPLOAD_MAX_CONCURRENCY=4`，因此审阅者可以看到几行验证和运行代理同时进行，而不会压倒 OpenAI 速率限制、存储或本地 CPU。使用 `sample_stress_realistic_50.json` 进行实时压力测试，使用 `sample_stress_realistic_250.csv` 进行更重的吞吐量测试，最好在确定性回退模式下或使用故意选择的管理员工作线程限制。 在每行中，代理交接保持有序，因为 Ingest 规范化支付，Graph 添加关系证据，Pattern 读取丰富证据，Risk 生成最终决策包。无效行在批量结果中隔离，而不是失败整个批次。
6. 从批量结果或案例页面打开高风险案例。
在案例详情页面上，显示：
- 包含交易和支付消息上下文的概述。
- 具有实体关系的调查选项卡，然后是代理证据。
- 实时图形遍历，其中关系跳跃自动显示。
- 置信度瀑布和每个代理的证据。
- 风险分析和可配置的评分因素。
- SAR 草稿、手动 SAR 编辑控件和人工审查包。
- 人工审批/拒绝门。
7. 批准高风险案例。
批准触发警报代理模拟，并将决策追加到审计账本。
8. 显示可观察性：
- 当 OpenAI 实时模式和 Langfuse 密钥配置好时，使用 Langfuse 进行 LLM 跟踪。
- 使用 Prometheus 和 Grafana 进行指标。
- 使用 Jaeger 进行 OpenTelemetry 跟踪。
## 样本评估
在生产审查之前运行可复制的样本评估器，以生成准确性、延迟、吞吐量、成本和人工门控率的可衡量证据：
```bash
uv --project backend run --locked python scripts/evaluate_samples.py \
--sample frontend/public/samples/sample_stress_realistic_50.json \
--concurrency 4
```
输出：
| 文件 | 目的 |
|---|---|
| `data/runtime/evaluation_report.json` | 机器可读的指标和每行结果。 |
| `docs/sample_evaluation_report.md` | 用于生产审查准备的人类可读 KPI 表。 |
仅当您故意让评估器调用实时 OpenAI 路径时，才使用 `--live-openai`。如果不使用该标志，评估器将强制确定性回退，因此报告是可重复的，并且可以安全运行多次。
## 管理配置
受保护的管理控制台允许运行时策略覆盖，而无需编辑代码。默认配置来自 `.env`，并本地持久化到 `data/runtime/scoring_policy.json`。
可配置区域包括：
- 风险评分阈值和权重。
- 制裁审查、有益所有者不透明度、高风险方和 PEP 暴露权重。
- 结构金额范围。
- Shell/ring 文本标记和图形遍历限制。
- 矢量匹配分数和异常增量。
- 每个代理的置信度默认值和重试提升。
- 人工门控阈值和超时。
- 预算信封限制：最大回合、工具调用、重试、运行时、令牌、成本、重复操作和输出截断。
- 断路器和 SSE 超时设置。
每个参数都有内联帮助，因此操作或合规用户可以在更改之前了解其含义。
## MCP 服务器
Finxiom 在 `mcp_server/` 中包含一个生产级 MCP 服务器。MCP 服务器包装现有的 FastAPI 后端，因此后端仍然是验证、代理执行、评分、审计和批准逻辑的记录系统。
MCP 工具：
| 工具 | 目的 |
|---|---|
| `get_runtime_status` | 读取安全运行时和 LLM 模式状态。 |
| `submit_transaction` | 将一个交易提交到代理管道。 |
| `submit_bulk_transactions` | 提交 JSON 交易批次。 |
| `list_cases` | 列出可见案例。 |
| `get_case` | 读取完整的案例详情。 |
| `get_case_audit` | 读取仅追加的案例审计事件。 |
| `get_human_review_packet` | 提取决策点、声明到源映射、检查和异常。 |
| `approve_case` | 在明确的人工确认后触发批准的警报代理模拟。 |
| `reject_case` | 拒绝案例并追加分析师注释。 |
| `get_scoring_policy` | 读取活动管理员评分策略。 |
| `update_scoring_policy` | 更新活动管理员评分策略。 |
| `reset_scoring_policy` | 将管理员策略重置为默认值。 |
通过 stdio 为桌面客户端运行 MCP：
```bash
cd /Users/ag/Documents/OpenAI_Hackathon/finxiom
FINXIOM_API_BASE_URL=http://127.0.0.1:8010 \
FINXIOM_MCP_BEARER_TOKEN="$(uv --project backend run --locked python scripts/generate_jwt.py --subject mcp --scopes transactions:write,cases:read,cases:approve,admin:read,admin:write)" \
uv --project backend run --locked python -m mcp_server.server --transport stdio
```
作为本地可流式 HTTP 服务运行 MCP：
```bash
bash scripts/restart_services.sh mcp
```
安全控制：
- 编写工具需要范围限定的 Finxiom 承载令牌。
- 为真实客户端使用最小权限令牌。
- `approve_case` 还需要 `confirm_irreversible_action=true`。
- MCP 不会绕过后端验证、评分策略、人工门控或审计跟踪。
## API 接口
核心端点：
| 方法 | 端点 | 目的 |
|---|---|---|
| `GET` | `/health` | 运行时健康和 LLM 模式。 |
| `GET` | `/runtime/status` | 安全的前端运行时状态。 |
| `GET` | `/runtime/scoring-policy` | 仅限分析师页面读取的评分/显示策略。 |
| `GET` | `/system/readiness` | 操作就绪性：存储模式、MCP 监听器、Langfuse 状态、OpenAI 模式和注意事项。 |
| `GET` | `/operations/readiness` | 操作就绪性：网关、身份验证、服务、Celery、样本、OpenAI 证据和注意事项。 |
| `POST` | `/transactions` | 提交一个交易。 |
| `POST` | `/transactions/bulk` | 提交 JSON 交易数组。 |
| `POST` | `/transactions/async` | 通过 Celery 排队交易；立即返回 `task_id`。 |
| `GET` | `/tasks/{task_id}` | 轮询 Celery 任务状态（PENDING/STARTED/SUCCESS/FAILURE）。 |
| `GET` | `/cases` | 列出案例。 |
| `GET` | `/cases/{case_id}` | 获取案例详情。 |
| `GET` | `/cases/{case_id}/audit` | 获取仅追加的审计事件。 |
| `POST` | `/cases/{case_id}/approve` | 人工审批门控。 |
| `POST` | `/cases/{case_id}/reject` | 人工拒绝门控。 |
| `GET` | `/events/{case_id}` | 服务器发送的事件，用于实时案例状态。 |
| `GET` | `/admin/scoring-policy` | 仅限管理员读取活动策略。 |
| `PUT` | `/admin/scoring-policy` | 仅限管理员更新活动策略。 |
| `POST` | `/admin/scoring-policy/reset` | 仅限管理员重置活动策略为默认值。 |
| `GET` | `/metrics` | Prometheus 指标。 |
大多数受保护的端点都需要范围限定的 JWT。使用以下命令生成应用程序令牌：
```bash
uv --project backend run --locked python scripts/generate_jwt.py --subject intake --scopes transactions:write,cases:read
uv --project backend run --locked python scripts/generate_jwt.py --subject analyst --scopes cases:read,cases:approve
uv --project backend run --locked python scripts/generate_jwt.py --subject admin --scopes admin:read,admin:write
```
浏览器客户端不应接收 `admin:*` 范围。分析师页面使用 `/runtime/scoring-policy` 进行只读显示阈值；管理员 UI 更改通过 Next.js 服务器操作层路由，并在管理员会话解锁后进行。
## LLM 运行时模式
Finxiom 在 UI 和健康端点中故意显示活动模型模式。
- `LLM mode: OpenAI live` 表示 `OPENAI_API_KEY` 已配置并且实时模型、嵌入和结构化输出路径可用。
- `LLM mode: deterministic fallback` 表示管道使用本地确定性丰富、图形逻辑、模式匹配、评分和 SAR 回退内容。
此设计使得生产运行可靠，同时保持生产集成路径可见且可测试。
## 可观察性
Langfuse、Grafana、Prometheus 和 Jaeger 是本地 Docker 堆栈的一部分。
在实时模型调用后，使用 Langfuse 检查模型和代理跟踪。在实例新鲜时创建 Langfuse 项目，将生成的公共和私钥复制到 `.env`，重启后端，并运行新的交易或批量上传。
使用 Prometheus 和 Grafana 检查 API 和管道指标。后端公开 `/metrics`，Docker Compose 在本地提供 Prometheus 和 Grafana。
使用 Jaeger 检查 FastAPI 和仪器请求的分布式跟踪。
## 测试和质量
运行后端测试：
```bash
cd backend
uv run --locked pytest tests/ -v --asyncio-mode=auto
```
运行 lint 和类型检查：
```bash
cd backend
uv run --locked ruff check .
uv run --locked mypy .
```
运行前端构建检查：
```bash
cd frontend
npm run build
```
## 故障排除
如果 `http://localhost:3001` 无法访问，请确认前端开发服务器正在运行：
```bash
bash scripts/restart_services.sh frontend
```
如果前端加载但 API 支持的页面显示 `401 Unauthorized`，请通过重启脚本重启前端，以便它接收新的限定范围的应用程序 JWT：
```bash
bash scripts/restart_services.sh frontend
```
如果通过 `http://127.0.0.1:8080` 的请求失败但直接后端请求有效，请验证 Kong 是否正在运行以及 `infra/kong/kong.yml` 中的 Kong JWT 密钥是否与 `scripts/generate_jwt.py` 使用的本地 `JWT_SECRET_KEY` 匹配。
如果 `http://127.0.0.1:8010/health` 无法访问，请确认后端正在端口 `8010` 上运行：
```bash
cd backend
uv run --locked uvicorn main:app --host 127.0.0.1 --port 8010 --reload
```
如果后端测试无法在 macOS 上找到 Docker，请在运行 pytest 之前设置 Docker Desktop 用户套接字：
```bash
export DOCKER_HOST=unix://$HOME/.docker/run/docker.sock
```
如果 Docker 服务显示空白凭证警告，请始终包含 env 文件：
```bash
docker compose --env-file .env -f infra/docker-compose.yml up -d
```
如果 Docker 曾有失败或部分镜像拉取，请重启 Docker Desktop，确保有足够的磁盘空间可用，然后再次拉取：
```bash
docker compose --env-file .env -f infra/docker-compose.yml pull
docker compose --env-file .env -f infra/docker-compose.yml up -d
```
如果 Langfuse 为空，请创建 Langfuse 项目，更新 `.env` 中的 `LANGFUSE_PUBLIC_KEY` 和 `LANGFUSE_SECRET_KEY`，重启后端，并运行新的交易。旧的确定性回退运行不会创建实时 LLM 跨度。
如果 Grafana 或 Prometheus 显示为空，请生成流量打开 UI、提交交易或运行：
```bash
bash scripts/run_end_to_end.sh
```
## 安全说明
- 请勿提交 `.env`、API 密钥、数据库密码、Langfuse 密钥或 JWT 机密。
- 本地管理员密码仅用于开发，必须在共享使用前进行轮换。
- 浏览器可见的应用程序令牌故意排除 `admin:*`；管理员读取/写入使用签名的 HTTP-Only 管理员会话和服务器端限定范围的 JWT。
- 生产部署应替换本地管理员密码为基于 OIDC/SAML 的 RBAC 和短期服务器颁发的令牌。
- 高影响操作由明确的分析师批准控制。
- 代理访问按路由级权限和类型交接范围限定。
- 在将输出传递到下一阶段之前会截断工具输出。
- 审计事件在应用程序层仅追加，具有数据库级更新/删除撤销支持。
## 其他文档
- `docs/architecture.md` 包含更深入的架构和防护说明。
- `docs/production_scorecard.md` 包含评分证明点和生产谈话要点。
- `docs/mcp_integration.md` 解释 MCP 工具、传输、范围和安全控制。
- `docs/realistic_input_model.md` 解释批量上传接受的现实世界支付字段。
- `docs/sample_evaluation_report.md` 包含最新的生成的样本 KPI 报告。
- `data/seed/` 包含单个交易样本负载和欺诈类型示例。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器