Skip to content

yuff100/FreightBot

BranchesTags

Repository files navigation

FreightBot

智能货代邮件自动化处理平台

FreightBot 是面向货代公司的邮件自动化 Agent，核心能力：

  1. 自动读取 客户邮件及附件中的物流信息
  2. 智能提取 业务字段，附带逐字段置信度评分
  3. 自动更新 公司内部物流系统
  4. 自动回复 客户确认邮件（基于模板生成，非自由文本）
  5. 安全降级 低置信度、字段冲突、系统异常时进入人工审核队列

核心原则

原则 说明
可靠性优先 宁可少自动，不可错自动
幂等优先 同一邮件、同一业务变更不得重复写入系统
稳定性优先 任一外部依赖异常时，系统必须可恢复、可重试、可追踪
可审计优先 每一步输入、判断、输出都必须有记录
人工兜底优先 无法确定时必须进入待审核队列，不允许"猜测后执行"

功能特性

邮件处理

  • 邮件接收: IMAP 轮询接入，自动去重
  • OCR 支持: PDF、图片附件文字提取（支持扫描件）
  • 混合提取: 正则 + NLP 模型双引擎字段提取
  • 置信度评分: 逐字段置信度，驱动自动/人工决策

自动化引擎

  • 自动化决策引擎: 多维评估（置信度 + 风险 + 业务规则 + 客户配置）
  • 灰度发布: MD5 一致性哈希分流，支持白名单/黑名单
  • 告警监控: 滑动窗口准确率追踪，可配置阈值自动告警
  • 客户级配置: 独立自动化阈值、风险容忍度、业务类型限制

基础设施

  • 异步处理: Celery + Redis 异步任务队列
  • 可观测性: Prometheus 指标 + OpenTelemetry + Jaeger 分布式追踪
  • 熔断器: 外部服务调用自动故障恢复
  • 健康检查: 存活/就绪探针，含依赖状态检查
  • 版本管理: 配置版本化，支持回滚和 diff 对比
  • 多客户支持: 客户专属模板、别名、提取规则
  • CI/CD: GitHub Actions（lint、test、type-check、docker build）

管理后台 Dashboard

  • 审核工作台: 任务列表、筛选、分页、详情对话框、审核操作
  • 监控面板: 准确率/告警/健康状态卡片、告警表格、一键解决
  • 灰度发布管理: 功能列表、配置编辑器、开关切换、一键回滚
  • 客户管理: CRUD 表格、搜索、模板/别名/规则分页管理
  • 版本管理: 实体选择器、版本历史、快照详情、JSON diff、一键回滚

Dashboard 截图

首页概览

Dashboard 首页

4 个统计卡片（待审核、今日处理、自动化率、系统准确率）+ 最近审核列表 + 活跃告警

审核工作台

审核工作台

任务筛选栏 + 6 列数据表格 + 详情对话框 + 批准/拒绝操作

监控面板

监控面板

准确率/告警数/健康状态统计卡片 + 告警列表 + 一键解决

灰度发布管理

灰度发布管理

功能列表 + 配置编辑器 + 开关切换 + 回滚操作

客户管理

客户管理

客户 CRUD 表格 + 搜索 + 创建/编辑/停用 + 模板/别名/规则分页

版本管理

版本管理

实体选择器 + 版本历史列表 + 快照详情 + JSON diff 对比 + 一键回滚

技术栈

后端

组件 技术
Web 框架 FastAPI
数据库 PostgreSQL + SQLAlchemy
任务队列 Celery + Redis
OCR pytesseract + OpenCV + PyMuPDF
NLP HuggingFace Transformers
日志 structlog（结构化 JSON）
监控 Prometheus + Grafana + OpenTelemetry + Jaeger
CI/CD GitHub Actions

前端

组件 技术
框架 Next.js 14（App Router）
UI 基础 React 18 + TypeScript
CSS Tailwind CSS
组件库 shadcn/ui
服务端状态 TanStack Query
图标 Lucide React

快速开始

后端服务

# 克隆仓库
git clone <repo-url>
cd FreightBot

# 配置环境变量
cp .env.example .env
# 编辑 .env 填入你的配置

# Docker 一键启动
docker-compose up --build -d

服务地址：

前端 Dashboard

cd frontend
npm install
npm run dev

Dashboard 地址: http://localhost:3001

项目结构

FreightBot/
├── freightbot/
│   └── app/
│       ├── main.py                  # FastAPI 应用入口
│       ├── config.py                # 配置管理
│       ├── api/v1/                  # API v1 端点
│       │   ├── automation.py        # 自动化配置 & 灰度发布
│       │   ├── monitoring.py        # 告警 & 准确率监控
│       │   ├── versions.py          # 版本管理
│       │   ├── customers.py         # 多客户管理
│       │   ├── task.py              # 任务管理
│       │   ├── email.py             # 邮件接入
│       │   └── extraction.py        # 提取结果
│       ├── core/                    # 核心模块
│       │   ├── security.py          # JWT 认证
│       │   ├── business_rules.py    # 业务规则引擎 & 状态机
│       │   ├── tracing.py           # OpenTelemetry 分布式追踪
│       │   └── circuit_breaker.py   # 熔断器
│       ├── models/                  # SQLAlchemy ORM 模型
│       ├── schemas/                 # Pydantic 数据校验
│       ├── services/                # 业务服务
│       │   ├── automation_decision_engine.py  # 多维决策引擎
│       │   ├── gray_release_controller.py     # 灰度发布控制器
│       │   ├── alert_manager.py               # 告警管理器
│       │   ├── version_service.py             # 版本管理服务
│       │   ├── customer_service.py            # 多客户服务
│       │   └── health_service.py              # 增强健康检查
│       ├── extractors/              # 字段提取器
│       ├── db/                      # 数据库访问层
│       └── tasks/                   # Celery 异步任务
├── frontend/                        # Next.js 14 管理后台
│   └── src/
│       ├── app/                     # 页面路由
│       │   ├── page.tsx             # Dashboard 首页
│       │   ├── review/page.tsx      # 审核工作台
│       │   ├── monitoring/page.tsx  # 监控面板
│       │   ├── gray-release/page.tsx # 灰度发布管理
│       │   ├── customers/page.tsx   # 客户管理
│       │   └── versions/page.tsx    # 版本管理
│       ├── components/              # 共享组件
│       │   ├── ui/                  # shadcn/ui 基础组件
│       │   └── shared/              # 业务共享组件
│       └── lib/                     # 工具库
│           ├── api/                 # API 客户端 & 端点定义
│           └── types/               # TypeScript 类型定义
├── tests/                           # 148 个测试用例
├── docs/                            # 项目文档
│   ├── architecture.md              # 技术架构
│   ├── dashboard-design.md          # Dashboard UI 设计文档
│   ├── data-model.md                # 数据模型
│   ├── wireframes/                  # HTML 原型 & 线框图
│   └── screenshots/                 # Dashboard UI 截图
├── .github/workflows/ci.yml        # CI/CD 流水线
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
└── pyproject.toml

开发阶段

Phase 1 - 观察模式 ✅

  • IMAP 邮件接收与存储
  • 邮件内容及附件解析
  • PDF/图片附件 OCR
  • 正则 + NLP 模型字段提取
  • 置信度评估
  • 提取结果存储
  • Prometheus 指标采集

Phase 2 - 人工参与 ✅

  • 内部物流系统对接（Mock）
  • 人工审核工作台 API
  • 模板化自动回复邮件
  • 业务规则引擎 & 状态机
  • 基于置信度的路由（自动 vs 人工审核）

Phase 3 - 可控自动化 ✅

  • 多维自动化决策引擎（置信度 + 风险 + 业务规则 + 客户配置）
  • 灰度发布控制器（MD5 一致性哈希分流）
  • 告警管理器（滑动窗口准确率追踪）
  • 客户级自动化配置（阈值、风险容忍度、允许类型）
  • 流水线集成：决策引擎 → 灰度发布门控 → 自动处理 / 人工审核
  • 自动化管理 API (/api/v1/automation/*)
  • 监控 API (/api/v1/monitoring/*)
  • 40 个新增测试用例（决策引擎 10 + 灰度发布 16 + 告警管理 14）

Phase 4 - 规模化自动化 ✅

  • OpenTelemetry 分布式追踪（Jaeger 集成）
  • 增强健康检查（存活/就绪探针 + 依赖状态检查）
  • 熔断器模式（外部服务调用自动故障恢复）
  • CI/CD 流水线（GitHub Actions: lint、test、type-check、docker build）
  • 版本管理系统（配置版本化、回滚、diff 对比）
  • 多客户扩展（客户模板、别名、提取规则）
  • Dashboard UI（审核工作台、监控面板、灰度发布、客户管理、版本管理）

共计 148 个后端测试用例，全部通过。前端 npm run build 零错误。

文档

License

MIT

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages