TradeMate Dev
7b62c2f8b4
## H5 底部导航修复 (Bug #10) - 精简 App.vue，移除重复 tabbar，仅保留全局样式 - uni-page 设置 height: calc(100% - 50px) + overflow-y: auto - 内容区域精确停在底部导航上方，独立滚动不再叠加 - 恢复 custom-tab-bar 组件 ## 项目进度文档 - PROGRESS.md 更新至 10 个 Bug 修复 - 新增 H5 底部导航修复记录 - 新增历史变更条目
27 KiB
27 KiB
外贸小助手 (TradeMate) — 技术架构文档
版本: v1.1 创建日期: 2026-05-10 更新: 新增客户健康度看板、AI跟进助手、市场机会分析三大模块
一、系统架构总览
┌──────────────────────────────────────────────────────┐
│ 客户端层 │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ 微信小程序 │ │ 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 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 # 客户跟进引擎
│ │ │ ├── customer_health.py # 客户健康度评分 (新增)
│ │ │ ├── followup_engine.py # AI跟进策略引擎 (新增)
│ │ │ ├── market_analysis.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 的方式替代，降低启动门槛。
八、V2 新增模块架构
8.1 客户健康度看板
评分模型
输入 → 多维度特征提取 → 加权评分 → 等级输出 → 行动建议
评分维度与权重:
| 维度 | 权重 | 数据源 | 计算方式 |
|---|---|---|---|
| 响应趋势 | 25% | messages | 近7天平均回复时长 vs 前7天，趋势上升加分 |
| 情感轨迹 | 20% | messages | AI分析最近3条客户消息情感极性（正面/负面/中性） |
| 询盘深度 | 20% | messages | 是否包含MOQ/认证/FOB/证书等成交信号关键词 |
| 沉默天数 | 20% | customers | 归一化得分: 1天=100, 14天+=0 |
| 商业价值 | 15% | quotations | 历史成交金额 + 当前在谈金额 |
等级输出:
| 分数区间 | 等级 | 颜色 | 建议动作 |
|---|---|---|---|
| 80-100 | 活跃 | 🟢 绿 | 保持正常跟进 |
| 50-79 | 需关注 | 🟡 黄 | 3天内安排跟进 |
| 0-49 | 高危 | 🔴 红 | 立即跟进，提供优惠或新产品信息 |
技术实现
- 无需新模型: 使用现有
messages、customers、quotations表 - 轻量计算: 无需 ML 模型，规则引擎即可，同步计算 < 50ms
- 异步更新: Celery 定时任务每小时更新一次评分缓存到 Redis
- API:
GET /api/v1/customers/{id}/health— 单个客户健康度 - API:
GET /api/v1/customers/health-overview— 全量概览
8.2 AI 智能跟进引擎
架构
┌────────────────────────────────────────────────────────────┐
│ FollowupEngine │
│ │
│ 1. 状态评估 │
│ └─ 读客户健康度 → 判断是否到跟进时机 │
│ │
│ 2. 策略选择 │
│ ├─ 沉默 3-5 天 → 温和提醒（"Just checking in"） │
│ ├─ 沉默 6-10 天 → 价值提供（"新品/行业资讯"） │
│ ├─ 沉默 11+ 天 → 重新激活（"限时优惠/调查问卷"） │
│ └─ 客户有回复但未成交 → 促进决策（"成功案例/限时"） │
│ │
│ 3. 内容生成 │
│ └─ AI 基于客户画像+产品库+历史对话生成个性化内容 │
│ │
│ 4. 渠道推荐 │
│ ├─ 历史互动中 WhatsApp 回复率>60% → WhatsApp │
│ ├─ 客户来自展会/邮件 → Email │
│ └─ 紧急/高价商机 → 建议电话 │
│ │
│ 5. 效果追踪 │
│ └─ 跟进后监控客户反应 → 更新策略模型 │
└────────────────────────────────────────────────────────────┘
技术实现
- 跟进策略: 基于规则的策略选择器（可扩展为强化学习）
- 内容生成: 复用现有 AI 营销素材能力，注入客户上下文
- 渠道路由: 基于
customer.preference.channel和历史回复率 - 定时任务: Celery beat 每 6 小时轮检所有客户
- 通知推送: 检测到跟进时机 → 写入 notifications → PushService 推送
数据模型
class FollowupStrategy(Base):
"""跟进策略模板"""
__tablename__ = "followup_strategies"
id: UUID (PK)
user_id: UUID (nullable — null = 系统策略)
name: str # 策略名称
trigger_conditions: JSONB # 触发条件: {health_score_max, silence_days_min, ...}
channel: str # 推荐渠道
ai_prompt_template: str # AI提示词模板
min_interval_hours: int # 最短间隔
is_active: bool
success_count: int # 成功率统计
created_at: datetime
class FollowupLog(Base):
"""跟进记录"""
__tablename__ = "followup_logs"
id: UUID (PK)
user_id: UUID
customer_id: UUID (FK)
strategy_id: UUID (FK → followup_strategies)
health_score_before: float # 跟进前健康分
suggested_content: Text # AI建议内容
actual_content: Text # 用户实际发送内容
channel: str # 使用的渠道
was_sent: bool # 是否已发送
customer_replied: bool # 客户是否回复
replied_within_hours: int # 回复间隔
created_at: datetime
8.3 智能市场机会分析
架构
┌────────────────────────────────────────────────────────────┐
│ MarketAnalysisService │
│ │
│ 1. 市场趋势分析 │
│ └─ 调取 UN COMTRADE / ITC TradeMap API → 目标国进口趋势 │
│ │
│ 2. 客户发现 │
│ └─ Google Custom Search → B2B平台/行业黄页 → 潜在客户列表 │
│ │
│ 3. 竞争情报 │
│ └─ AI 分析竞品定价/卖点/市场定位 │
│ │
│ 4. 策略报告 │
│ └─ AI 综合生成: 市场选择→进入策略→风险提示→行动清单 │
└────────────────────────────────────────────────────────────┘
数据源集成
| 数据源 | 集成方式 | 费率 |
|---|---|---|
| UN COMTRADE API | REST API (https://comtrade.un.org/api/) | 免费, 需注册 |
| ITC TradeMap | SOAP/REST (https://www.trademap.org/) | 免费基础查询 |
| Google Custom Search | JSON API (100次/天免费) | 免费~$5/1000次 |
| SerpAPI | Google搜索结果结构化 | $50/月 起 |
| AI 自有知识 | 已有模型知识 | 免费 |
核心原则: 所有数据源有免费层，上线初期零数据采购成本。
API 设计
POST /api/v1/market-analysis/opportunity
输入: { product_name, description, category, target_markets? }
输出: {
recommended_markets: [{ country, growth_rate, entry_strategy }],
potential_clients: [{ name, source, description }],
competitive_landscape: "分析文本",
strategy_report: "完整策略报告"
}
GET /api/v1/market-analysis/reports
列表用户历史报告
GET /api/v1/market-analysis/reports/{id}
获取报告详情
关键设计决策
- 异步生成: 报告生成可能需要 30-60 秒，使用 Celery 异步任务
- 缓存策略: 相同产品+市场的报告缓存 7 天
- 渐进式展示: 前端先显示 loading，各个模块完成后逐步展示（趋势数据先出 → 客户发现 → 报告）
- 用户引导: 首次使用后提示"保存到产品库"或"一键生成开发信"
九、护城河策略（V2 更新）
V1 有三层护城河，V2 增加两层：
第 4 层: 客户健康度数据集
用户每日查看健康度 → 记录评分变化 → 验证建议有效性 → 优化评分模型
↓
跨用户匿名统计 → 行业基准对比
"你的客户健康度分布 vs 同行业用户的分布"
网络效应: 用户越多，行业基准越准，评分越有价值。
第 5 层: AI跟进策略知识库
每次跟进记录:
├─ 客户状态（评分/沉默天数/阶段）
├─ 跟进策略（时机/内容/渠道）
├─ 结果（回复/未回复/成交）
└─ 用户反馈
→ 积累到 1000+ 条后:
├─ 分析"什么策略在什么场景下最有效"
├─ 自动优化策略选择器
└─ 新用户直接受益于"过去1000次跟进的最佳实践"
十一、安全设计
| 维度 | 措施 |
|---|---|
| 认证 | JWT + 微信 OAuth + refresh token 轮换 |
| API 安全 | 全站 HTTPS、请求签名校验、rate limiting |
| 数据安全 | 密码 bcrypt 哈希、敏感配置环境变量注入 |
| AI API Key | 仅服务端持有，不暴露给前端 |
| 用户隔离 | 所有查询强制 user_id 过滤 |
| 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%