内容
# 智能费用申报系统
多智能体多模态系统，用于自动化新加坡科技设计大学（SUTD）的费用申报处理。取代手动的SAP Concur工作流程（每个申报15-25分钟），目标是实现小于3分钟的提交时间和大于95%的字段提取准确率。
## 工作原理
四个LangGraph智能体通过以下流程处理申报：
```
收据上传 -> 接收智能体 -> 合规性 + 反欺诈（并行）-> 顾问 -> 决策
```
- **接收智能体** - 通过视觉语言模型（VLM）解析收据，验证政策，处理货币转换，并与用户确认
- **合规性智能体** - 提交后进行政策合规性检查
- **反欺诈智能体** - 异常检测和欺诈评分
- **顾问智能体** - 最终决策路由（自动批准 / 返回 / 升级）
## 技术栈
| 组件 | 技术 |
|-----------|-----------|
| 智能体 | LangGraph（Python） |
| 大型语言模型/视觉语言模型 | OpenRouter（Qwen 2.5 72B） |
| 网页界面 | FastAPI + Jinja2 + HTMX + Tailwind |
| 数据库 | PostgreSQL 16 |
| 向量存储 | Qdrant（政策嵌入） |
| MCP服务器 | FastMCP（RAG，数据库，货币，电子邮件） |
| 包管理器 | Poetry |
## 快速入门
### 前提条件
- Docker 和 Docker Compose
- Python 3.11+
- `.env.local` 文件（从 `.env.example` 复制并填写您的值）
```bash
cp .env.example .env.local
# 编辑 .env.local 文件，填写您的 OPENROUTER_API_KEY 和其他设置
```
### 启动
启动脚本通过单个命令将整个系统从零启动：
```bash
# 正常启动（保留现有数据）
./scripts/startup.sh
# 清洁重启（清除卷，重新导入政策，截断表）
./scripts/startup.sh --reset
```
脚本自动执行8个步骤：
1. 停止任何现有容器
2. 处理卷重置（如果使用 `--reset` 标志）
3. 构建并启动所有 Docker Compose 服务
4. 等待所有8个服务通过健康检查
5. 运行 Alembic 数据库迁移
6. 截断表以达到清洁状态（如果使用 `--reset` 标志）
7. 将政策文档导入 Qdrant
8. 验证所有路由和 MCP 服务器端点
启动完成后，系统将显示应用程序日志。按 `Ctrl+C` 停止日志跟踪（服务将继续运行）。
### 服务网址
| 服务 | 网址 |
|---------|-----|
| 应用程序界面 | http://localhost:8000 |
| Seq 日志 | http://localhost:5341 |
| PostgreSQL | localhost:5432 |
| Qdrant | http://localhost:6333 |
### 停止
```bash
# 停止服务（保留数据）
docker compose down
# 停止并清除所有数据
docker compose down -v
```
## 开发
### 运行测试
```bash
poetry run pytest tests/ -v
# 启用覆盖率
poetry run pytest --cov=agentic_claims --cov-report=term-missing
```
### 代码检查和格式化
```bash
poetry run ruff check src/ tests/
poetry run ruff format src/ tests/
```
### 在不使用 Docker 的情况下运行
需要本地运行 PostgreSQL 和 Qdrant：
```bash
poetry install
poetry run alembic upgrade head
python scripts/ingest_policies.py
poetry run chainlit run src/agentic_claims/app.py --host 0.0.0.0 --port 8000
```
## 基础设施
通过 `docker-compose.yml` 编排的8个服务：
| 服务 | 端口 | 目的 |
|---------|------|---------|
| `app` | 8000 | FastAPI 网页界面 + LangGraph 智能体 |
| `postgres` | 5432 | 申报数据库 + LangGraph 检查点 |
| `qdrant` | 6333 | 政策嵌入的向量存储 |
| `mcp-rag` | 8001 | 政策搜索 MCP 服务器 |
| `mcp-db` | 8002 | 数据库操作 MCP 服务器 |
| `mcp-currency` | 8003 | 货币转换 MCP 服务器 |
| `mcp-email` | 8004 | 电子邮件通知 MCP 服务器 |
| `seq` | 5341 | 结构化日志聚合 |
## 用户角色
| 角色 | 登录页面 | 能力 |
|------|-------------|-------------|
| 员工（用户） | `/` | 提交申报，上传收据，跟踪状态 |
| 审查者 | `/manage` | 审查申报，批准/拒绝/升级，查看分析数据 |
