# 🌐 TradeMate 外贸小助手

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

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Python](https://img.shields.io/badge/python-3.11-green.svg)
![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-cyan.svg)
![Vue](https://img.shields.io/badge/Vue-3.x-orange.svg)

---

## 📖 项目简介

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 — 让外贸更简单* 🚀