TradeMate Dev
5d2bced39f
- PROGRESS.md: update to 2026-05-29 with security hardening (T-005), 4-frontend architecture, AI provider refactoring, discovery features, landing page/referral/quota, desktop layout, admin AI management - AGENTS.md: add AI provider list (Alibaba/NVIDIA, removed Claude/DeepL/Local), DB-driven config, CSRF/rate-limit/CORS notes, admin_ai reload quirk - .env.example: sync with actual config, replace deprecated providers with current Sensenova/OpencodeGo/NVIDIA/Spark/Alibaba - docs/PROJECT_STATUS.md: archive (fully superseded by PROGRESS.md) - Remove generated JS files (_bing_search.js, _batch_search.js) - Remove empty directories (data/corpus, data/models) - Remove backend/.coverage (test artifact) - Fix services/.gitignore to cover _bing_search.js - Include pending AI provider DB admin feature (admin_ai, AIProvider model, AIProviders.vue, migration) and T-008 test report
299 lines
9.2 KiB
Markdown
299 lines
9.2 KiB
Markdown
# 🌐 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 一键启动（推荐）
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
### 方式二：本地开发环境
|
||
|
||
```bash
|
||
# 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` |
|
||
|
||
### 数据库初始化
|
||
|
||
```bash
|
||
# 首次启动后，运行数据库迁移
|
||
cd backend
|
||
alembic upgrade head
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 API 文档
|
||
|
||
- **Swagger UI**: http://localhost:8000/docs
|
||
- **ReDoc**: http://localhost:8000/redoc
|
||
- **详细 API 设计文档**: [docs/API_DESIGN.md](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 # 本文件
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 测试
|
||
|
||
```bash
|
||
# 运行所有后端测试
|
||
cd backend && venv/bin/pytest
|
||
|
||
# 运行特定测试文件
|
||
venv/bin/pytest tests/test_auth_api.py
|
||
|
||
# 运行关键词过滤测试
|
||
venv/bin/pytest tests/ -k "test_login"
|
||
```
|
||
|
||
---
|
||
|
||
## 📄 相关文档
|
||
|
||
- [项目进度](PROGRESS.md) — 任务完成情况和待办事项
|
||
- [Agent 指南](AGENTS.md) — 开发规范和关键注意事项
|
||
- [API 设计](docs/API_DESIGN.md) — 详细 API 接口文档
|
||
- [数据库 schema](docs/DATABASE_SCHEMA.md) — 数据模型定义
|
||
- [技术架构](docs/TECH_ARCHITECTURE.md) — 系统架构详解
|
||
|
||
---
|
||
|
||
## 📝 开发规范
|
||
|
||
- **提交信息**：聚焦 "why" 而非 "what"，使用英文
|
||
- **测试**：新功能必须编写测试，提交前运行 `pytest`
|
||
- **代码注释**：除非特别要求，否则不添加注释
|
||
- **UI**：中文界面，移动端优先
|
||
- **AI 服务**：使用 `MarketingService()`（无需 DB），客户健康用 `CustomerHealthService(db)`
|
||
|
||
---
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
---
|
||
|
||
## 📜 许可证
|
||
|
||
MIT License
|
||
|
||
---
|
||
|
||
## 🔗 相关链接
|
||
|
||
- [API 文档](http://localhost:8000/docs)
|
||
- [项目文档](docs/)
|
||
- [产品设计方案](docs/PRODUCT_DESIGN.md)
|
||
|
||
---
|
||
|
||
*TradeMate — 让外贸更简单* 🚀 |