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 infra/scripts/start-dev.sh

手动启动

# 1. 启动基础设施
cd infra/docker && docker compose up -d

# 2. 安装并启动后端
cd backend
pip install -e ".[dev]"
cp ../infra/env/.env.example .env   # 按需编辑
alembic revision --autogenerate -m "init"
alembic upgrade head
python -m scripts.seed              # 插入演示数据
uvicorn app.main:app --reload --port 8000

# 3. 安装并启动前端
cd frontend
npm install
npm run dev

访问

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

纯前端演示模式

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

cd frontend && npm run dev

配置 AI 能力

在 backend/.env 中配置：

OCR_API_KEY=your_key
OCR_API_URL=https://api.example.com/v1/chat/completions
LLM_API_KEY=your_key
LLM_API_URL=https://api.example.com/v1/chat/completions
LLM_MODEL=model_name

支持 OpenAI 兼容格式的多模态 API。未配置时自动使用 mock 数据。

测试

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	下载报告