trade-assistant/docs/UPGRADE_PLAN.md

外贸小助手 (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 + 潜在客户 + 策略建议
□ 报告可保存到产品库
□ 报告可一键跳转生成营销文案
□ 渐进式加载（先展示趋势，逐步补充完整报告）