fund-tracer/README.md

# 智析反诈 — 受害人被骗金额归集智能体

面向电信诈骗案件受害人资金梳理的多APP账单智能归集与被骗金额核验系统。

## 功能概览

- **案件管理** — 创建、查看、管理诈骗案件
- **截图上传** — 批量上传微信/支付宝/银行/数字钱包等多APP账单截图
- **OCR识别** — 云端多模态自动识别页面类型、提取交易字段，支持人工修正
- **交易归并** — 自动去重（订单号/金额+时间窗口）、识别本人账户中转
- **资金分析** — 生成资金流转关系图、交易时间轴、收款方聚合
- **认定复核** — 高/中/低置信分层，人工复核确认，自动生成认定理由
- **笔录辅助** — 基于分析结果自动生成笔录问询建议
- **报告导出** — Excel汇总表 / PDF报告 / Word文书，含证据索引和审计快照

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | React 18 + TypeScript + Ant Design + ECharts + TanStack Query + Zustand |
| 后端 | Python + FastAPI + SQLAlchemy 2.x (async) + Pydantic v2 |
| 数据库 | PostgreSQL 16 |
| 队列 | Celery + Redis 7 |
| AI能力 | 云OCR / 多模态大模型API（可配置） |
| 报告 | openpyxl + python-docx |

## 项目结构

```
fund-tracer/
├── frontend/          # React 前端
│   ├── src/
│   │   ├── pages/     # 7 个核心页面
│   │   ├── services/  # API 服务层
│   │   ├── store/     # Zustand 状态管理
│   │   ├── mock/      # Mock 数据（后端不可用时自动降级）
│   │   └── types/     # TypeScript 类型定义
│   └── package.json
├── backend/           # FastAPI 后端
│   ├── app/
│   │   ├── api/v1/    # REST API 路由
│   │   ├── models/    # SQLAlchemy ORM 模型
│   │   ├── schemas/   # Pydantic 请求/响应模型
│   │   ├── services/  # 业务逻辑层
│   │   ├── rules/     # 规则引擎（去重/中转/认定）
│   │   ├── workers/   # Celery 异步任务
│   │   └── repositories/ # 数据访问层
│   ├── alembic/       # 数据库迁移
│   ├── scripts/       # 种子数据等脚本
│   └── tests/         # pytest 测试
├── infra/
│   ├── docker/        # docker-compose (PG + Redis)
│   ├── env/           # 环境变量模板
│   └── scripts/       # 一键启动脚本
└── docs/              # 文档
```

## 快速开始

### 前提条件

- Node.js >= 18
- Python >= 3.11
- Docker & Docker Compose

### 一键启动

```bash
bash infra/scripts/start-dev.sh
```

### 手动启动

```bash
# 1. 启动基础设施（PostgreSQL + Redis）
cd infra/docker
docker compose up -d
cd ../..

# 2. 安装后端依赖
cd backend
python -m venv .venv                     # 创建虚拟环境（推荐）
source .venv/bin/activate                # macOS/Linux
# .venv\Scripts\activate                 # Windows
pip install -r requirements.txt          # 安装依赖

# 3. 配置环境变量
cp ../infra/env/.env.example .env        # 复制模板，按需编辑

# 4. 初始化数据库
alembic revision --autogenerate -m "init"
alembic upgrade head

# 5. 插入演示数据
python -m scripts.seed

# 6. 启动后端服务
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 7. 安装并启动前端（新开终端）
cd frontend
npm install
npm run dev
```

### 访问

- 前端: http://localhost:5173
- 后端 API: http://localhost:8000
- API 文档: http://localhost:8000/docs

## 纯前端演示模式

即使没有后端服务，前端也能正常运行。系统会自动检测后端可用性，不可用时降级为内置 mock 数据驱动。

```bash
cd frontend && npm run dev
```

## 配置 AI 能力

系统使用两组独立的 OpenAI 兼容接口，在 `backend/.env` 中配置：

```bash
# OCR — 截图识别与字段抽取（需要多模态/视觉能力）
OCR_API_KEY=your_key
OCR_API_URL=https://api.example.com/v1/chat/completions
OCR_MODEL=gpt-4o

# LLM — 认定理由生成、问询建议等推理任务
LLM_API_KEY=your_key
LLM_API_URL=https://api.example.com/v1/chat/completions
LLM_MODEL=gpt-4o-mini
```

- OCR 和 LLM 可以指向不同的供应商/模型（如 OCR 用视觉模型，LLM 用轻量文本模型）
- 如果只配置 LLM 而未配置 OCR，OCR 会自动降级使用 LLM 的配置
- 两者均未配置时自动使用 mock 数据，不影响演示

## 测试

```bash
cd backend
pytest tests/ -v
```

## API 端点一览

| 端点 | 方法 | 功能 |
|------|------|------|
| `/api/v1/cases` | GET/POST | 案件列表/创建 |
| `/api/v1/cases/{id}` | GET/PATCH | 案件详情/更新 |
| `/api/v1/cases/{id}/images` | GET/POST | 截图列表/上传 |
| `/api/v1/images/{id}` | GET | 截图详情+OCR结果 |
| `/api/v1/cases/{id}/analyze` | POST | 触发分析 |
| `/api/v1/cases/{id}/transactions` | GET | 交易列表 |
| `/api/v1/cases/{id}/flows` | GET | 资金流图 |
| `/api/v1/cases/{id}/assessments` | GET | 认定列表 |
| `/api/v1/assessments/{id}/review` | POST | 提交复核 |
| `/api/v1/cases/{id}/inquiry-suggestions` | GET | 问询建议 |
| `/api/v1/cases/{id}/reports` | GET/POST | 报告列表/生成 |
| `/api/v1/reports/{id}/download` | GET | 下载报告 |