🌐 TradeMate 外贸小助手

AI 驱动的外贸业务助手 — 专为外贸 SOHO 和小型团队打造

---

📖 项目简介

TradeMate 是一个 AI 驱动的外贸业务助手，帮助外贸 SOHO 和小型团队提升工作效率。通过集成大语言模型（Sensenova 星火、OpenAI 等），提供智能翻译、客户管理、营销文案生成、报价单自动生成等核心功能。

核心定位：

• 🎯 面向外贸 SOHO 和小型团队
• 🌏 中英双语智能翻译
• 🤖 AI 驱动的营销与报价
• 📱 移动端优先设计（uni-app）

---

✨ 功能特性

🔐 认证系统

• JWT 双 Token 认证（access_token + refresh_token）
• 游客模式（无需注册即可体验核心功能）
• 微信小程序登录集成
• 微信 H5 浏览器静默授权

🌐 智能翻译

• 中英互译（支持多 AI 提供商）
• 公开翻译接口（游客可用）
• 翻译质量反馈机制

💬 智能回复

• 基于客户询盘生成回复建议
• 多风格回复（专业/友好）
• 结合产品上下文智能生成

📊 客户管理

• 客户 CRUD 操作
• 沉默客户提醒（可配置天数）
• 客户对话记录追踪
• 客户健康度分析

📝 营销素材

• AI 生成营销文案（多风格）
• 关键词建议
• 竞品分析

📋 报价单管理

• 从询盘自动生成报价单
• 报价单 CRUD 操作
• 多币种支持
• 报价单状态跟踪

📈 数据分析

• 客户/翻译/报价单统计概览
• 7 日趋势分析
• 使用日志记录

📱 前端应用

• uni-app — 移动端 H5 + 微信小程序
• admin-frontend — PC 管理后台（Vue 3 + Element Plus）
• user-frontend — 用户工作台（Vue 3 + Element Plus）

🔧 管理后台

• 用户管理（列表/搜索/改套餐/改角色/启用禁用）
• 使用统计（各功能调用 + 7 日趋势）
• 操作日志（带筛选器 + 分页）
• 系统配置（卡片表单）

---

🚀 快速开始

前置要求

• Docker & Docker Compose
• Node.js 18+（开发环境）
• Python 3.11+（开发环境）

方式一：Docker Compose 一键启动（推荐）

# 1. 克隆项目
git clone <repository-url>
cd trade-assistant

# 2. 配置环境变量
cp backend/.env.example backend/.env
# 编辑 backend/.env，填入必要的 API Key

# 3. 启动所有服务
docker-compose up -d

# 4. 访问服务
# 后端 API: http://localhost:8000
# API 文档: http://localhost:8000/docs
# 前端 H5: http://localhost:5173

方式二：本地开发环境

# 1. 后端开发
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

# 2. 前端 H5 开发
cd uni-app
npm install
npm run dev:h5

# 3. 管理后台开发
cd admin-frontend
npm install
npm run dev

# 4. 用户工作台开发
cd user-frontend
npm install
npm run dev

---

⚙️ 配置说明

环境变量 (.env)

变量	说明	示例
SECRET_KEY	JWT 密钥	change-me-to-a-secure-key
DATABASE_URL	PostgreSQL 连接串	postgresql+asyncpg://user:pass@host:5432/db
REDIS_URL	Redis 连接串	redis://localhost:6379/0
OPENAI_API_KEY	OpenAI API Key	sk-...
SENSNOVA_API_KEY	星火大模型 API Key	...
DEEPL_API_KEY	DeepL API Key	...
WECHAT_APP_ID	微信小程序 AppID	wx...
WECHAT_APP_SECRET	微信小程序 AppSecret	...
FRONTEND_URL	前端地址	http://localhost:5173

数据库初始化

# 首次启动后，运行数据库迁移
cd backend
alembic upgrade head

---

📚 API 文档

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• 详细 API 设计文档: docs/API_DESIGN.md

主要 API 端点

模块	路径前缀	功能
认证	/api/v1/auth/*	注册、登录、Token 刷新
客户	/api/v1/customers/*	客户 CRUD、沉默客户
翻译	/api/v1/translate/*	翻译、回复建议、信息提取
营销	/api/v1/marketing/*	营销文案、关键词、竞品分析
报价单	/api/v1/quotations/*	报价单 CRUD、从询盘生成
分析	/api/v1/analytics/*	数据统计概览
WhatsApp	/api/v1/whatsapp/*	消息发送、Webhook

---

🏗️ 技术架构

┌─────────────────────────────────────────────────────────────┐
│                        Nginx (反向代理)                      │
├─────────────────┬─────────────────┬─────────────────────────┤
│  admin-frontend │  user-frontend  │       uni-app (H5)      │
│    (Vue 3)      │    (Vue 3)      │      (移动端)           │
│    :5173        │      :5174      │       :5173             │
├─────────────────┴─────────────────┴─────────────────────────┤
│                    FastAPI Backend (:8000)                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │
│  │  Auth    │ │  AI Router│ │ Business │ │  Celery Worker │ │
│  │  JWT     │ │  Multi-LLM│ │  Services│ │  Async Tasks   │ │
│  └──────────┘ └──────────┘ └──────────┘ └────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                    PostgreSQL + Redis                        │
│                    (pgvector for AI embeddings)              │
└─────────────────────────────────────────────────────────────┘

技术栈

层级	技术
后端	FastAPI + SQLAlchemy 1.4 async + asyncpg
数据库	PostgreSQL 15 + pgvector + Redis 7
AI 提供商	Sensenova (星火), OpenAI, DeepL
前端	Vue 3 + uni-app + Element Plus
任务队列	Celery + Redis
容器化	Docker + Docker Compose

---

📦 项目结构

trade-assistant/
├── backend/                  # FastAPI 后端
│   ├── app/                  # 应用代码
│   │   ├── api/              # API 路由
│   │   ├── core/             # 核心配置、安全、中间件
│   │   ├── models/           # 数据库模型
│   │   ├── services/         # 业务服务
│   │   ├── ai/               # AI 路由和提供商
│   │   └── main.py           # 应用入口
│   ├── alembic/              # 数据库迁移
│   ├── tests/                # 测试
│   ├── Dockerfile
│   └── requirements.txt
├── uni-app/                  # 移动端 H5 + 小程序
├── admin-frontend/           # PC 管理后台
├── user-frontend/            # 用户工作台
├── nginx/                    # Nginx 配置
├── docs/                     # 项目文档
│   ├── API_DESIGN.md
│   ├── DATABASE_SCHEMA.md
│   └── TECH_ARCHITECTURE.md
├── docker-compose.yml        # Docker 编排
├── Makefile                  # 快捷命令
└── README.md                 # 本文件

---

🧪 测试

# 运行所有后端测试
cd backend && venv/bin/pytest

# 运行特定测试文件
venv/bin/pytest tests/test_auth_api.py

# 运行关键词过滤测试
venv/bin/pytest tests/ -k "test_login"

---

📄 相关文档

• 项目进度 — 任务完成情况和待办事项
• Agent 指南 — 开发规范和关键注意事项
• API 设计 — 详细 API 接口文档
• 数据库 schema — 数据模型定义
• 技术架构 — 系统架构详解

---

📝 开发规范

• 提交信息：聚焦 "why" 而非 "what"，使用英文
• 测试：新功能必须编写测试，提交前运行 pytest
• 代码注释：除非特别要求，否则不添加注释
• UI：中文界面，移动端优先
• AI 服务：使用 MarketingService()（无需 DB），客户健康用 CustomerHealthService(db)

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

📜 许可证

MIT License

---

🔗 相关链接

• API 文档
• 项目文档
• 产品设计方案

---

TradeMate — 让外贸更简单 🚀