trade-assistant/docs/TECH_ARCHITECTURE.md

外贸小助手 (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%