# 外贸小助手 (TradeMate) — 项目进度文档

> 版本: v1.0
> 更新日期: 2026-05-08
> 状态: MVP开发中

---

## 一、项目概述

**项目名称**: 外贸小助手 (TradeMate)
**项目类型**: 微信小程序 + 后端API
**目标用户**: 外贸SOHO、小型外贸公司、工厂转型外贸

---

## 二、功能实现总览

### 2.1 已完成功能 ✅

| 功能模块 | 后端API | 前端页面 | 状态 |
|---------|---------|---------|------|
| **用户认证** | /auth/register, login, refresh, me, settings | 登录页 | ✅ |
| **智能翻译** | /translate, /reply, /extract, /feedback | 翻译页 | ✅ |
| **回复建议** | /translate/reply (3种语气) | 翻译页 | ✅ |
| **营销素材** | /marketing/generate, /keywords, /competitor-analysis | 营销页 | ✅ |
| **客户管理** | /customers CRUD, /silent, /conversation | 客户页 | ✅ |
| **沉默检测** | /customers/silent (3/7/14天) | 客户页 | ✅ |
| **报价单** | /quotations CRUD, /status | 报价页 | ✅ |
| **产品库** | /products CRUD | 产品页 | ✅ |
| **汇率换算** | /exchange/convert, /rates | (待集成) | ✅ |
| **推送通知** | /push/register, /send, /devices | (uni-push) | ✅ |
| **WhatsApp** | /whatsapp/webhook, /send, /qr | (框架) | ✅ |
| **定时任务** | Celery tasks | - | ✅ |

**前端页面**:
- 登录页 (pages/login)
- 首页仪表盘 (pages/index)
- 翻译+回复 (pages/translate)
- 客户管理 (pages/customers)
- 营销素材 (pages/marketing)
- 报价单 (pages/quotation)
- 产品库 (pages/product)
- 自定义TabBar

### 2.2 未完成功能 ❌

| 功能 | 优先级 | 说明 |
|------|--------|------|
| **微信登录** | 高 | 需配置微信开放平台OAuth |
| **WhatsApp真实集成** | 高 | 需注册Meta Business，配置真实API |
| **报价单PDF生成** | 中 | 需集成 weasyprint 库 |
| **文字转语音(TTS)** | 中 | uni-app 有对应API |
| **批量导入客户** | 中 | 需集成文件上传+xlsx解析 |
| **Web管理后台** | 低 | 设计中有，未实现 |
| **数据分析报表** | 低 | 首页数据目前为模拟 |
| **多人协作/团队** | 低 | 企业版功能 |
| **语料库训练** | 低 | V3功能，仅框架 |

### 2.3 缺失文档

- [x] 产品设计文档 (PRODUCT_DESIGN.md)
- [x] 技术架构文档 (TECH_ARCHITECTURE.md)
- [x] API设计文档 (API_DESIGN.md)
- [x] 数据库设计文档 (DATABASE_SCHEMA.md)
- [ ] 项目进度文档 (本文档) ✅

---

## 三、技术栈

### 3.1 后端

| 技术 | 版本 | 用途 |
|------|------|------|
| Python | 3.11+ | 运行环境 |
| FastAPI | latest | Web框架 |
| SQLAlchemy | 2.0+ | ORM |
| PostgreSQL | 15 | 主数据库 |
| pgvector | latest | 向量数据库 |
| Redis | 7 | 缓存/队列 |
| Celery | 5.0+ | 定时任务 |
| AI Providers | - | DeepL/OpenAI/Claude |

### 3.2 前端

| 技术 | 版本 | 用途 |
|------|------|------|
| uni-app | 3.0+ | 跨端框架 |
| Vue | 3.4+ | UI框架 |
| Sass/SCSS | - | 样式预处理 |
| uni-push | 2.0 | 推送服务 |

### 3.3 部署

| 技术 | 用途 |
|------|------|
| Docker | 容器化 |
| Docker Compose | 编排 |
| Nginx | 反向代理 |
| Systemd | 进程管理 |

---

## 四、目录结构

```
trade-assistant/
├── docs/                          # 设计文档
│   ├── PRODUCT_DESIGN.md          # 产品设计
│   ├── TECH_ARCHITECTURE.md       # 技术架构
│   ├── API_DESIGN.md              # API接口
│   ├── DATABASE_SCHEMA.md         # 数据库设计
│   └── PROJECT_STATUS.md          # 项目进度
│
├── backend/                       # Python后端
│   ├── app/
│   │   ├── main.py                # FastAPI入口
│   │   ├── config.py              # 配置
│   │   ├── database.py            # 数据库连接
│   │   ├── celery_app.py          # Celery配置
│   │   ├── models/                # 数据模型
│   │   │   ├── user.py            # 用户+产品
│   │   │   ├── customer.py        # 客户+对话+消息
│   │   │   ├── quotation.py       # 报价单+明细
│   │   │   └── corpus.py          # 语料库
│   │   ├── api/v1/               # REST API
│   │   │   ├── auth.py            # 认证
│   │   │   ├── translate.py       # 翻译
│   │   │   ├── marketing.py       # 营销
│   │   │   ├── customer.py        # 客户
│   │   │   ├── quotation.py       # 报价单
│   │   │   ├── product.py         # 产品
│   │   │   ├── exchange.py        # 汇率
│   │   │   ├── push.py            # 推送
│   │   │   └── whatsapp.py        # WhatsApp
│   │   ├── services/              # 业务逻辑
│   │   ├── ai/                   # AI抽象层
│   │   │   ├── router.py          # 智能路由
│   │   │   ├── trade_corpus.py    # 语料库
│   │   │   └── providers/         # 各引擎实现
│   │   ├── core/                  # 核心组件
│   │   │   ├── security.py        # JWT认证
│   │   │   ├── exceptions.py      # 异常处理
│   │   │   └── middleware.py      # 中间件
│   │   └── workers/              # Celery任务
│   │       └── tasks.py
│   ├── alembic/                  # 数据库迁移
│   ├── requirements.txt
│   ├── Dockerfile
│   └── .env.example
│
├── uni-app/                      # uni-app前端
│   ├── src/
│   │   ├── pages/                # 页面
│   │   │   ├── login/            # 登录
│   │   │   ├── index/            # 首页
│   │   │   ├── translate/        # 翻译
│   │   │   ├── customers/        # 客户
│   │   │   ├── marketing/        # 营销
│   │   │   ├── quotation/        # 报价单
│   │   │   └── product/          # 产品库
│   │   ├── components/          # 组件
│   │   │   └── tabbar/           # 自定义TabBar
│   │   ├── utils/                # 工具
│   │   │   ├── api.js            # API封装
│   │   │   └── push.js           # 推送服务
│   │   ├── static/               # 静态资源
│   │   ├── App.vue               # 应用入口
│   │   ├── main.js               # Vue初始化
│   │   └── pages.json            # 页面配置
│   ├── package.json
│   └── vite.config.js
│
├── miniprogram/                  # 微信小程序(原生-已弃用)
│
├── docker-compose.yml            # Docker编排
├── nginx/                        # Nginx配置
├── scripts/                      # 运维脚本
├── systemd/                      # Systemd服务
└── data/                         # 数据目录
```

---

## 五、待办事项

### 5.1 高优先级 (MVP)

- [ ] 配置微信登录OAuth
- [ ] 配置WhatsApp Cloud API真实环境
- [ ] 集成PDF生成库 (weasyprint)
- [ ] 添加批量客户导入功能

### 5.2 中优先级 (V2)

- [ ] 添加文字转语音(TTS)功能
- [ ] 实现Web管理后台基础功能
- [ ] 数据分析图表集成

### 5.3 低优先级 (V3+)

- [ ] 团队/多人协作功能
- [ ] 语料库训练模型
- [ ] API开放平台

---

## 六、部署说明

### 开发环境

```bash
# 启动后端
cd backend
docker-compose up -d

# 启动前端
cd uni-app
npm install
npm run dev:mp-weixin
```

### 生产环境

详见 `scripts/deploy.sh` 和 systemd 配置

---

## 七、相关文档链接

- [产品设计](./PRODUCT_DESIGN.md)
- [技术架构](./TECH_ARCHITECTURE.md)
- [API设计](./API_DESIGN.md)
- [数据库设计](./DATABASE_SCHEMA.md)