# 外贸小助手 (TradeMate) — V2 改造升级计划

> 版本: v1.0
> 创建日期: 2026-05-10
> 基于: 竞品调研 + 用户需求分析 + 现有代码审计

---

## 一、升级思路

### 核心原则

不堆功能，只做三件事：

1. **帮用户做决策** — 不只看数据，给建议（健康度看板）
2. **帮用户省时间** — 不让用户设规则，AI自动判断（跟进引擎）
3. **帮用户找机会** — 不买海关数据，AI用公开信息分析（市场分析）

### 和竞品的本质区别

| 维度 | 竞品思路 | 我们的思路 |
|------|---------|-----------|
| 数据 | 买海关数据（贵，滞后） | 用免费公开数据 + AI分析 |
| 流程 | 预设规则（固定时间/模板） | AI动态判断（时机/内容/渠道都个性化） |
| 体验 | 给个分数让用户自己猜 | 给分数 + 原因 + 建议动作 |
| 成本 | 年费几万起 + 邮件服务费 | 零外部采购成本，纯软件投入 |

---

## 二、功能一：客户健康度看板

### 优先级

**P0 — 先做这个**。数据已有，投入最小，用户感知最强。

### 实现步骤

| 步骤 | 内容 | 涉及文件 | 预估工时 |
|------|------|---------|---------|
| 1.1 | 实现 `CustomerHealthService` 评分引擎 | `backend/app/services/customer_health.py` | 4h |
| 1.2 | 实现健康度 API 端点 | `backend/app/api/v1/customer_health.py` | 2h |
| 1.3 | 注册路由到 main.py | `backend/app/main.py` | 0.5h |
| 1.4 | 客户列表页顶部增加健康度概览卡片 | `uni-app/src/pages/customers/customers.vue` | 3h |
| 1.5 | 客户详情页增加健康度看板 | `uni-app/src/pages/customers/customers.vue` detail modal | 3h |
| 1.6 | Celery 定时任务每小时更新评分缓存 | `backend/app/workers/tasks.py` | 2h |
| 1.7 | 前端 `api.js` 新增 healthApi | `uni-app/src/utils/api.js` | 0.5h |

**总工时**: ~15h | **外部依赖**: 无

### 评分模型（上线版）

```
health_score = 
  response_trend * 25% +     # 响应趋势（messages数据）
  sentiment_score * 20% +     # 情感轨迹（AI分析最近3条消息）
  inquiry_depth * 20% +       # 询盘深度（关键词匹配MOQ/认证等）
  silence_score * 20% +       # 沉默天数（归一化）
  business_value * 15%        # 商业价值（报价单数据）
```

无需 ML 模型，规则引擎即可，同步计算 < 50ms。

---

## 三、功能二：AI 智能跟进助手

### 优先级

**P1 — 在看板之后做**。依赖健康度数据，但有跟进引擎才有闭环。

### 实现步骤

| 步骤 | 内容 | 涉及文件 | 预估工时 |
|------|------|---------|---------|
| 2.1 | 创建 `followup_strategies` 和 `followup_logs` 数据模型 | `backend/app/models/followup.py` | 2h |
| 2.2 | 实现 `FollowupEngine` 策略选择器 + 内容生成 | `backend/app/services/followup_engine.py` | 6h |
| 2.3 | 实现跟进 API 端点 | `backend/app/api/v1/followup.py` | 3h |
| 2.4 | 注册路由到 main.py | `backend/app/main.py` | 0.5h |
| 2.5 | Celery beat 定时轮检（每6h） | `backend/app/workers/tasks.py` | 2h |
| 2.6 | 跟进提醒通知对接 PushService | `backend/app/services/followup_engine.py` | 2h |
| 2.7 | Alembic 迁移脚本 | `backend/alembic/versions/` | 1h |
| 2.8 | 前端跟进列表页 + 通知入口 | `uni-app/src/pages/followup/followup.vue` | 4h |
| 2.9 | 首页待跟进卡片组件 | `uni-app/src/pages/index/index.vue` | 2h |
| 2.10 | 前端 `api.js` 新增 followupApi | `uni-app/src/utils/api.js` | 0.5h |

**总工时**: ~23h | **外部依赖**: 无（复用 AI 营销素材能力）

### 跟进策略示例（初始版本）

| 触发条件 | 策略 | 渠道 | AI提示词方向 |
|---------|------|------|------------|
| 沉默 3-5 天, 健康分 50-79 | 温和提醒 | WhatsApp | "Just checking in if you need any further information" |
| 沉默 6-10 天, 健康分 30-49 | 价值提供 | Email | 推送新品目录/行业资讯/产品认证 |
| 沉默 11+ 天, 健康分 <30 | 重新激活 | Email | 限时折扣/客户调查/节日问候 |
| 客户有回复但未成交, 健康分 60+ | 促进决策 | WhatsApp | 成功案例/限时报价/差异优势 |

---

## 四、功能三：智能市场机会分析

### 优先级

**P2 — 最后做**。功能独立，用户价值高但实现复杂，涉及外部API集成。

### 实现步骤

| 步骤 | 内容 | 涉及文件 | 预估工时 |
|------|------|---------|---------|
| 3.1 | 创建 `market_reports` 数据模型 | `backend/app/models/market_report.py` | 1h |
| 3.2 | 实现 UN COMTRADE API 集成 | `backend/app/services/market_data.py` | 3h |
| 3.3 | 实现 Google Custom Search 集成 | `backend/app/services/market_data.py` | 2h |
| 3.4 | 实现 `MarketAnalysisService` AI报告生成 | `backend/app/services/market_analysis.py` | 6h |
| 3.5 | 实现市场分析 API 端点 | `backend/app/api/v1/market_analysis.py` | 3h |
| 3.6 | 注册路由到 main.py | `backend/app/main.py` | 0.5h |
| 3.7 | Celery 异步报告生成任务 | `backend/app/workers/tasks.py` | 2h |
| 3.8 | Alembic 迁移脚本 | `backend/alembic/versions/` | 1h |
| 3.9 | 前端市场分析页面 | `uni-app/src/pages/analysis/analysis.vue` | 4h |
| 3.10 | 添加 pages.json 路由 | `uni-app/src/pages.json` | 0.5h |
| 3.11 | 前端 `api.js` 新增 marketApi | `uni-app/src/utils/api.js` | 0.5h |

**总工时**: ~23.5h | **外部依赖**: UN COMTRADE 免费API注册 + Google Custom Search API key

### 数据源依赖

| 数据源 | 注册成本 | 调用限制 | 是否需要 |
|--------|---------|---------|---------|
| UN COMTRADE API | 免费注册 | 无硬限制 | 必须（趋势数据核心） |
| Google Custom Search | 免费（100次/天） | 100次/天 | 可选（客户发现增强） |
| AI 自有知识 | 已有 | 无限制 | 必须（报告生成） |

---

## 五、工作量汇总与排期

### 总览

| 功能 | 优先级 | 工时期 | 外部依赖 | 建议开始 |
|------|--------|-------|---------|---------|
| 客户健康度看板 | P0 | 2天 | 无 | 第1天 |
| AI 智能跟进助手 | P1 | 3天 | 无 | 第3天 |
| 智能市场机会分析 | P2 | 3天 | UN COMTRADE + Google API | 第6天 |

### 并行策略

```
第1-2天: 客户健康度看板 (后端1天 + 前端1天)
           │
第3-5天:  AI 跟进助手 (后端2天 + 前端1天)
           │
第6-8天:  市场机会分析 (后端2天 + 前端1天)
```

总工期约 **8 天**（一人全栈），若有前后端分工可压缩至 **5-6 天**。

### 外部依赖注册清单

```
□ UN COMTRADE API: https://comtrade.un.org/auth/register/
□ Google Custom Search API: https://programmablesearchengine.google.com/
   → 创建搜索引掣 → 获取 API Key + Search Engine ID
```

---

## 六、验收标准

### 健康度看板验收

```
□ 客户列表顶部展示健康度概览（活跃/需关注/高危数量）
□ 每个客户展示健康等级标签（🟢/🟡/🔴）
□ 点击客户进入详情 → 展示评分维度明细 + 建议动作
□ 评分各维度有来源说明（不是黑盒）
□ 首页展示总览数据
```

### AI跟进助手验收

```
□ 系统自动检测跟进时机 → 推送通知
□ 跟进通知含客户背景摘要 + AI建议内容
□ 用户可一键发送/编辑后发送
□ 跟进后自动追踪客户回复状态
□ 跟进记录可追溯
```

### 市场机会分析验收

```
□ 用户输入产品信息 → 30-60秒生成分析报告
□ 报告含推荐市场 Top 3 + 潜在客户 + 策略建议
□ 报告可保存到产品库
□ 报告可一键跳转生成营销文案
□ 渐进式加载（先展示趋势，逐步补充完整报告）
```