TradeMate Dev
c6206787da
项目结构: - backend/ Python FastAPI 后端 - uni-app/ uni-app跨端前端 - docs/ 设计文档 - docker-compose.yml Docker编排 - nginx/scripts/systemd 运维配置 已完成功能: - 用户认证 (JWT) - 智能翻译 + 回复建议 - 营销素材生成 - 客户管理 + 沉默检测 - 报价单管理 - 产品库管理 - 汇率换算 - 推送通知 (uni-push) - WhatsApp Webhook框架 - Celery定时任务
362 lines
18 KiB
Markdown
362 lines
18 KiB
Markdown
# 外贸小助手 (TradeMate) — 技术架构文档
|
||
|
||
> 版本: v1.0
|
||
> 创建日期: 2026-05-08
|
||
|
||
---
|
||
|
||
## 一、系统架构总览
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────┐
|
||
│ 客户端层 │
|
||
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
||
│ │ 微信小程序 │ │ Web后台 │ │ WhatsApp │ │
|
||
│ │ (主入口) │ │ (管理用) │ │ 原生客户端 │ │
|
||
│ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ │
|
||
└─────────┼───────────────┼────────────────┼───────────┘
|
||
│ HTTP/JSON │ HTTP/JSON │ WhatsApp
|
||
│ │ │ Cloud API
|
||
┌─────────┼───────────────┼────────────────┼───────────┐
|
||
│ ┌┴──────────────┴────────────────┴┐ │
|
||
│ │ API Gateway (FastAPI) │ │
|
||
│ │ - 认证 (JWT + WeChat OAuth) │ │
|
||
│ │ - 用户 tier 中间件 │ │
|
||
│ │ - 配额控制中间件 │ │
|
||
│ └────────────────┬─────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────────────┼─────────────────┐ │
|
||
│ │ │ │ │
|
||
│ ┌─────┴─────┐ ┌──────┴──────┐ ┌───────┴──────┐ │
|
||
│ │ 业务服务 │ │ AI 服务 │ │ WhatsApp │ │
|
||
│ │ │ │ 抽象层 │ │ 集成服务 │ │
|
||
│ │ - 营销素材 │ │ - Provider │ │ - 消息收发 │ │
|
||
│ │ - 翻译回复 │ │ - Router │ │ - Webhook │ │
|
||
│ │ - 客户跟进 │ │ - 语料库 │ │ - 会话管理 │ │
|
||
│ │ - 报价单 │ │ - 成本控制 │ │ │ │
|
||
│ └─────┬─────┘ └──────┬──────┘ └──────┬───────┘ │
|
||
│ │ │ │ │
|
||
│ ┌─────┴─────────────────┴─────────────────┴──────┐ │
|
||
│ │ 数据层 │ │
|
||
│ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │
|
||
│ │ │PostgreSQL│ │ Redis │ │ 文件存储 │ │ │
|
||
│ │ │+pgvector │ │ (缓存) │ │ (报价单PDF) │ │ │
|
||
│ │ └──────────┘ └──────────┘ └──────────────┘ │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
└────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 二、技术栈选型
|
||
|
||
| 层级 | 技术 | 选型理由 |
|
||
|------|------|---------|
|
||
| 客户端 | 微信小程序 | 触达成本最低，中国外贸商家几乎100%使用微信 |
|
||
| 后端 | FastAPI (Python 3.11+) | 异步性能好，类型安全，生态成熟 |
|
||
| 主数据库 | PostgreSQL 15 + pgvector | 结构化数据 + 向量检索（语料库语义搜索） |
|
||
| 缓存 | Redis 7 | 会话缓存、配额计数、任务队列 |
|
||
| 任务队列 | Celery + Redis broker | 异步翻译、批量语料处理 |
|
||
| AI Provider | DeepL + OpenAI + Claude + 本地模型 | 按场景路由，成本优化 |
|
||
| WhatsApp | WhatsApp Cloud API | 官方API，合规稳定 |
|
||
| 部署 | Docker + Docker Compose | 一键部署，环境一致 |
|
||
|
||
---
|
||
|
||
## 三、目录结构
|
||
|
||
```
|
||
trade-assistant/
|
||
├── docs/ # 设计文档
|
||
│ ├── PRODUCT_DESIGN.md
|
||
│ ├── TECH_ARCHITECTURE.md
|
||
│ ├── API_DESIGN.md # API 接口设计
|
||
│ └── DATABASE_SCHEMA.md # 数据库设计
|
||
│
|
||
├── backend/ # Python 后端
|
||
│ ├── app/
|
||
│ │ ├── main.py # FastAPI 入口
|
||
│ │ ├── config.py # 配置管理
|
||
│ │ ├── database.py # 数据库连接
|
||
│ │ │
|
||
│ │ ├── models/ # SQLAlchemy 数据模型
|
||
│ │ │ ├── user.py
|
||
│ │ │ ├── product.py
|
||
│ │ │ ├── customer.py
|
||
│ │ │ ├── conversation.py
|
||
│ │ │ ├── quotation.py
|
||
│ │ │ └── corpus.py
|
||
│ │ │
|
||
│ │ ├── api/v1/ # REST API 路由
|
||
│ │ │ ├── auth.py # 认证
|
||
│ │ │ ├── marketing.py # 营销素材
|
||
│ │ │ ├── translate.py # 翻译与回复
|
||
│ │ │ ├── customer.py # 客户管理
|
||
│ │ │ ├── quotation.py # 报价单
|
||
│ │ │ └── whatsapp.py # WhatsApp 集成
|
||
│ │ │
|
||
│ │ ├── services/ # 业务逻辑层
|
||
│ │ │ ├── marketing.py # 营销素材生成
|
||
│ │ │ ├── translation.py # 翻译+回复引擎
|
||
│ │ │ ├── customer.py # 客户跟进引擎
|
||
│ │ │ ├── quotation.py # 报价单服务
|
||
│ │ │ └── whatsapp.py # WhatsApp 服务
|
||
│ │ │
|
||
│ │ ├── ai/ # AI 抽象层
|
||
│ │ │ ├── base.py # Provider 接口
|
||
│ │ │ ├── router.py # 智能路由+fallback
|
||
│ │ │ ├── trade_corpus.py # 外贸语料库
|
||
│ │ │ └── providers/ # 各引擎实现
|
||
│ │ │ ├── openai.py
|
||
│ │ │ ├── claude.py
|
||
│ │ │ ├── deepl.py
|
||
│ │ │ └── local.py
|
||
│ │ │
|
||
│ │ ├── core/ # 核心基础设施
|
||
│ │ │ ├── security.py # JWT + 加密
|
||
│ │ │ ├── exceptions.py # 异常处理
|
||
│ │ │ └── middleware.py # 中间件
|
||
│ │ │
|
||
│ │ └── workers/ # Celery 任务
|
||
│ │ └── tasks.py
|
||
│ │
|
||
│ ├── alembic/ # 数据库迁移
|
||
│ ├── requirements.txt
|
||
│ ├── Dockerfile
|
||
│ └── .env.example
|
||
│
|
||
├── miniprogram/ # 微信小程序
|
||
│ ├── app.js / app.json / app.wxss
|
||
│ ├── pages/
|
||
│ │ ├── index/ # 首页仪表盘
|
||
│ │ ├── translate/ # 翻译+回复
|
||
│ │ ├── customers/ # 客户管理
|
||
│ │ ├── marketing/ # 营销素材
|
||
│ │ └── quotation/ # 报价单
|
||
│ ├── components/ # 通用组件
|
||
│ └── utils/ # 工具函数
|
||
│
|
||
├── data/ # 数据存储
|
||
│ ├── corpus/ # 外贸语料库文件
|
||
│ └── models/ # 微调模型占位
|
||
│
|
||
├── scripts/ # 运维脚本
|
||
├── docker-compose.yml
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 四、AI 服务架构（核心）
|
||
|
||
### 4.1 Provider 抽象层
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ AIRouter │
|
||
│ │
|
||
│ execute(task_type, method, *args, **kwargs) │
|
||
│ │
|
||
│ 1. 根据 task_type 获取优先级列表 │
|
||
│ 2. 按优先级依次尝试 provider │
|
||
│ 3. 失败自动 fallback 到下一个 │
|
||
│ 4. 记录每次调用的 provider、token、耗时、成本 │
|
||
│ 5. 将结果存入语料库（如果质量达标） │
|
||
└──────────┬──────────┬──────────┬──────────┬──────────┘
|
||
│ │ │ │
|
||
┌──────┴──┐ ┌───┴────┐ ┌───┴────┐ ┌───┴──────┐
|
||
│ OpenAI │ │ Claude │ │ DeepL │ │ Local │
|
||
│ Provider│ │Provider│ │Provider│ │Provider │
|
||
└─────────┘ └────────┘ └────────┘ └──────────┘
|
||
```
|
||
|
||
### 4.2 路由规则
|
||
|
||
| 任务类型 | 主引擎 | Fallback | 成本策略 |
|
||
|---------|--------|---------|---------|
|
||
| 翻译（看懂） | DeepL | OpenAI → 本地 | 优先低成本 |
|
||
| 回复建议 | OpenAI GPT-4o | Claude → 本地 | 质量优先 |
|
||
| 营销文案 | Claude | OpenAI → 本地 | 质量优先 |
|
||
| 结构化提取 | OpenAI GPT-4o | Claude | 结构化能力优先 |
|
||
| 语料训练 | 本地（离线） | - | 零成本 |
|
||
|
||
### 4.3 语料库架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ TradeCorpus │
|
||
│ │
|
||
│ 收集: │
|
||
│ ├─ 用户翻译记录（原文→译文，用户是否编辑过） │
|
||
│ ├─ 用户选择的回复（用户从N个AI建议中选了哪个） │
|
||
│ ├─ 用户点赞/点踩的反馈 │
|
||
│ └─ 用户最终发出的版本（可能是AI建议+用户修改） │
|
||
│ │
|
||
│ 存储: │
|
||
│ ├─ PostgreSQL (结构化: 源文, 译文, 领域, 评分) │
|
||
│ └─ pgvector (语义向量, 用于相似翻译检索) │
|
||
│ │
|
||
│ 使用: │
|
||
│ ├─ 运行时: 相似翻译召回 → 做 few-shot prompt │
|
||
│ ├─ 离线: 训练专用翻译模型（用户量 >1万后启动） │
|
||
│ └─ 质量评估: 持续评估各 provider 的质量分数 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 五、护城河实现策略
|
||
|
||
### 5.1 外贸垂直语料库（数据壁垒）
|
||
|
||
**数据采集点**（在用户流程中无感埋点）：
|
||
|
||
```
|
||
用户操作 → 系统记录
|
||
────────────────────────────────────────
|
||
用户输入中文要翻译 → 原文
|
||
用户选择了某个回复建议 → 被选中的建议 + 未被选中的建议
|
||
用户修改了AI建议再发送 → AI原文 + 用户修改版本
|
||
用户点了赞/点踩 → 质量标签
|
||
用户复制了某条营销文案 → 文案被使用的统计
|
||
```
|
||
|
||
**语料库达到 10 万条后的效果**：
|
||
- 翻译时从语料库检索相似度 >90% 的历史翻译，直接复用或做 few-shot
|
||
- 回复建议不再是通用 prompt，而是"过去100个类似询盘的回复模式"
|
||
- 新用户冷启动时直接受益于存量语料
|
||
|
||
### 5.2 用户产品知识库（迁移成本壁垒）
|
||
|
||
用户存入的数据是不可替代的资产：
|
||
|
||
```
|
||
用户产品库:
|
||
├─ 产品名称/描述（双语）
|
||
├─ 价格表（不同客户不同价）
|
||
├─ 规格参数
|
||
├─ 产品图片
|
||
└─ 关键词（多语言）
|
||
|
||
客户画像:
|
||
├─ 基本信息（国家/公司/职位）
|
||
├─ 沟通偏好（正式/亲切）
|
||
├─ 历史价格
|
||
├─ 付款习惯
|
||
└─ 砍价风格
|
||
|
||
→ 换平台 = 所有数据重录
|
||
→ 用户用得越久，走得越难
|
||
```
|
||
|
||
### 5.3 沉默客户模式算法（网络效应）
|
||
|
||
```
|
||
输入:
|
||
- 本用户的客户沉默时长
|
||
- 跨用户匿名统计的"不同国家客户回复率时间分布"
|
||
- 历史成功跟进的话术模式
|
||
|
||
输出:
|
||
- 最佳跟进时间
|
||
- 最高回复率的话术类型
|
||
- 客户"可能还有意向"的概率评分
|
||
|
||
网络效应:
|
||
- 用户A的墨西哥客户跟进数据 → 改善用户B的墨西哥客户跟进建议
|
||
- 用户越多，预测越准
|
||
- 新用户直接获得"过去100个相似案例的最佳实践"
|
||
```
|
||
|
||
---
|
||
|
||
## 六、配额与计费系统
|
||
|
||
### 6.1 计费计量点
|
||
|
||
```
|
||
┌──────────────┬────────────┬───────────────┐
|
||
│ 功能 │ 计量单位 │ 免费版限制 │
|
||
├──────────────┼────────────┼───────────────┤
|
||
│ 翻译 │ 字符数 │ 5000/天 │
|
||
│ 回复建议 │ 请求次数 │ 20次/天 │
|
||
│ 营销文案生成 │ 请求次数 │ 5次/天 │
|
||
│ 报价单生成 │ 份数 │ 3份/天 │
|
||
│ 客户管理 │ 客户数 │ 5个 │
|
||
│ 跟进提醒 │ - │ 仅沉默检测 │
|
||
└──────────────┴────────────┴───────────────┘
|
||
```
|
||
|
||
### 6.2 实现架构
|
||
|
||
```
|
||
用户请求 → tier middleware → quota middleware → 业务逻辑
|
||
│ │
|
||
↓ ↓
|
||
User.tier Redis INCR user:daily_count
|
||
控制功能可用性 检查是否超限
|
||
```
|
||
|
||
---
|
||
|
||
## 七、WhatsApp 集成架构
|
||
|
||
```
|
||
WhatsApp User WhatsApp Cloud API TradeMate Backend
|
||
│ │ │
|
||
│ 发送消息 │ │
|
||
│ ────────────────────────────────► │ │
|
||
│ │ Webhook POST /webhook/whatsapp │
|
||
│ │ ────────────────────────────────► │
|
||
│ │ │
|
||
│ │ 1. 验证 Webhook signature │
|
||
│ │ 2. 解析消息内容 + 发送者信息 │
|
||
│ │ 3. 调用翻译服务（用户可配置） │
|
||
│ │ 4. 存储到 conversations 表 │
|
||
│ │ 5. 检查是否触发沉默检测更新 │
|
||
│ │ 6. 返回 200 OK │
|
||
│ │ │
|
||
│ 回复消息 │ POST /messages (通过 Cloud API) │
|
||
│ ◄──────────────────────────────── │ ──── 用户在小程序确认回复后 ────► │
|
||
│ │ │
|
||
```
|
||
|
||
**注意**：WhatsApp Cloud API 要求企业通过 Meta Business 认证，初始阶段可以使用用户手动复制消息到 WhatsApp 的方式替代，降低启动门槛。
|
||
|
||
---
|
||
|
||
## 八、安全设计
|
||
|
||
| 维度 | 措施 |
|
||
|------|------|
|
||
| 认证 | JWT + 微信 OAuth + refresh token 轮换 |
|
||
| API 安全 | 全站 HTTPS、请求签名校验、rate limiting |
|
||
| 数据安全 | 密码 bcrypt 哈希、敏感配置环境变量注入 |
|
||
| AI API Key | 仅服务端持有，不暴露给前端 |
|
||
| 用户隔离 | 所有查询强制 user_id 过滤 |
|
||
| WhatsApp | Webhook signature 验证、消息内容不落日志 |
|
||
|
||
---
|
||
|
||
## 九、部署架构
|
||
|
||
```
|
||
开发环境: docker-compose up（单机）
|
||
├─ backend:8000
|
||
├─ postgres:5432
|
||
├─ redis:6379
|
||
└─ celery-worker
|
||
|
||
生产环境: 阿里云/腾讯云轻量服务器
|
||
├─ Nginx 反代 + SSL
|
||
├─ systemd 管理 backend + celery
|
||
├─ PostgreSQL 走内网
|
||
└─ Redis 走内网
|
||
|
||
关键指标:
|
||
├─ API 响应: < 200ms (p95)
|
||
├─ 翻译延迟: < 2s (p95)
|
||
├─ 并发用户: 500+（单实例）
|
||
└─ 可用性: 99.5%
|
||
```
|