TradeMate Dev🌐 TradeMate 外贸小助手
AI 驱动的外贸业务助手 — 专为外贸 SOHO 和小型团队打造
📖 项目简介
TradeMate 是一个 AI 驱动的外贸业务助手，帮助外贸 SOHO 和小型团队提升工作效率。通过集成大语言模型（Sensenova 星火、OpenAI 等），提供智能翻译、客户管理、营销文案生成、报价单自动生成等核心功能。
核心定位：
- 🎯 面向外贸 SOHO 和小型团队
- 🌏 中英双语智能翻译
- 🤖 AI 驱动的营销与报价
- 📱 移动端优先设计（uni-app）
✨ 功能特性
🏗️ 产品生态
TradeMate 提供三种使用方式，共享同一后端和账号体系：
| 产品 | 描述 | 入口 |
|---|---|---|
| 🌐 网页工作台 | 全功能外贸 SaaS — 翻译、CRM、营销、报价、AI Agent | 浏览器访问 /workspace |
| 🧩 Chrome 浏览器插件 | 划词翻译、快捷客户搜索、营销生成 | 见 browser-extension/ 安装指南 |
| 🤖 AI 技能包 | SKILL.md 技能包，用于 Cursor/Claude Code/OpenCode | .opencode/skills/ |
三者独立运营、互相补充，共享同一后端和账号体系。
💰 收费方式
采用合规的「软件 + 服务」销售模式，不主推托管订阅：
| 方案 | 价格 | 说明 |
|---|---|---|
| 🆓 免费试用 | ¥0 | 注册即享核心功能体验 |
| 🏢 私有化部署 | ¥39,800 / 年 | 年付授权，独立部署到客户自有服务器 |
| 💎 买断源码 | ¥98,000 / 一次性 | 一次性买断完整前后端源码，可二次开发 |
企业线索（私有化/买断意向）通过
POST /api/v1/leads提交至enterprise_leads表，由后台跟进。旧版按月订阅后端逻辑保留但前端不再主推。
🔐 认证系统
- 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 |
SENSENOVA_API_KEY |
商汤/星火大模型 API Key | ... |
NVIDIA_API_KEY |
NVIDIA 大模型 API Key | ... |
OPENAI_API_KEY |
OpenAI 兼容 API Key（可选） | sk-... |
WECHAT_APP_ID |
微信小程序 AppID | wx... |
WECHAT_APP_SECRET |
微信小程序 AppSecret | ... |
FRONTEND_URL |
前端地址（逗号分隔多端） | http://localhost:5173,http://localhost:5174 |
数据库初始化
# 首次启动后，运行数据库迁移
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/* |
数据统计概览 |
/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 (商汤/星火), NVIDIA, 阿里机器翻译 (alibaba-mt) |
| 前端 | 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/ # 用户工作台
├── browser-extension/ # Chrome 浏览器插件
├── landing/ # SEO 营销落地页（根路径 /）+ robots.txt + sitemap.xml
├── deploy/ # 部署配置（含 frontend/nginx.conf 四路布局）
├── nginx/ # Nginx 配置
├── docs/ # 项目文档
│ ├── API_DESIGN.md
│ ├── DATABASE_SCHEMA.md
│ └── TECH_ARCHITECTURE.md
├── docker-compose.yml # Docker 编排
├── Makefile # 快捷命令
└── README.md # 本文件
🌐 生产部署
站点 trade.yuzhiran.com 采用四路 Nginx 布局，由 deploy/frontend/nginx.conf 定义：
| 路径 | 内容 | 来源 |
|---|---|---|
/ |
SEO 营销落地页（根） | landing/index.html + robots.txt + sitemap.xml |
/app/ |
移动端 H5（uni-app，base /app/） |
uni-app 构建产物 |
/workspace/ |
用户工作台（user-frontend，base /workspace/） |
user-frontend 构建产物 |
/admin/ |
管理后台（admin-frontend，base /admin/） |
admin-frontend 构建产物 |
/api/ |
后端 API 反向代理 | 127.0.0.1:8000（systemd/uvicorn 运行） |
# 落地页（SEO 主入口）
cp landing/index.html landing/robots.txt landing/sitemap.xml /www/wwwroot/trade.yuzhiran.com/
# 三端 SPA
cd uni-app && npm run build:h5 && cp -r dist/build/h5/* /www/wwwroot/trade.yuzhiran.com/app/
cd user-frontend && npm run build && cp -r dist/* /www/wwwroot/trade.yuzhiran.com/workspace/
cd admin-frontend && npm run build && cp -r dist/* /www/wwwroot/trade.yuzhiran.com/admin/
# 后端迁移 + 重启
cd backend && source venv/bin/activate && alembic upgrade head
sudo systemctl restart ftrade-backend.service
# 重载 Nginx（套用 deploy/frontend/nginx.conf 的四路布局）
sudo nginx -t && sudo nginx -s reload
🧪 测试
# 运行所有后端测试
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
🔗 相关链接
TradeMate — 让外贸更简单 🚀