feat: 修复 H5 底部导航覆盖 + 更新项目进度文档

## H5 底部导航修复 (Bug #10) - 精简 App.vue，移除重复 tabbar，仅保留全局样式 - uni-page 设置 height: calc(100% - 50px) + overflow-y: auto - 内容区域精确停在底部导航上方，独立滚动不再叠加 - 恢复 custom-tab-bar 组件 ## 项目进度文档 - PROGRESS.md 更新至 10 个 Bug 修复 - 新增 H5 底部导航修复记录 - 新增历史变更条目
2026-05-12 20:24:42 +08:00
parent 69e164dcae
commit 7b62c2f8b4
125 changed files with 19725 additions and 728 deletions
@@ -0,0 +1,293 @@
+# 外贸小助手 (TradeMate) — 开发计划
+
+> 版本: v1.0
+> 创建日期: 2026-05-09
+> 基于: 产品设计文档 & 技术架构文档 & 代码审查
+
+---
+
+## 一、阶段说明
+
+按优先级分为 4 个阶段，每个阶段完成后可独立上线验证：
+
+| 阶段 | 名称 | 目标 | 预估工时 |
+|------|------|------|---------|
+| P0 | 上线必须 | 小程序审核通过 + 核心链路跑通 | 2-3 天 |
+| P1 | MVP 补齐 | 产品设计承诺的功能闭环 | 1-2 周 |
+| P2 | 体验增强 | 用户留存 + 付费转化 | 2-3 周 |
+| P3 | 护城河建设 | AI 数据壁垒 + 网络效应 | 4-6 周 |
+
+---
+
+## 二、P0 — 上线必须（2-3 天）
+
+### 2.1 微信登录配置
+- **问题**: `wechat.py` 代码完整，但 `WECHAT_APP_ID` / `WECHAT_APP_SECRET` 未配置，前端微信登录按钮无实际功能
+- **改动量**: 纯配置（需微信开放平台账号）
+- **涉及文件**: `.env`、`backend/app/api/v1/auth.py`、`uni-app/src/pages/login/login.vue`
+- **验收**: 用户可点击微信授权登录
+
+### 2.2 隐私政策 & 用户协议页面
+- **问题**: 小程序审核必需要求，当前无任何法律文档页面
+- **改动量**: 新增 2 个静态页面
+- **涉及文件**: `uni-app/src/pages/agreement/privacy.vue`、`uni-app/src/pages/agreement/terms.vue`、`pages.json`
+- **验收**: 登录页底部展示协议链接，可点击打开
+
+### 2.3 首页数据 Mock 替换
+- **问题**: `index.vue:121` 使用了 `Math.floor(Math.random() * 20)` 模拟今日翻译数和报价单数
+- **改动量**: 接入真实统计 API
+- **涉及文件**: `uni-app/src/pages/index/index.vue`
+- **验收**: 首页所有数据来自后端真实接口
+
+### 2.4 admin API 鉴权修复
+- **问题**: `admin.py:11` 的 `require_admin` 无实际校验，任何持有 token 的用户都能改其他用户的 Tier
+- **改动量**: 增加用户角色字段 + 权限校验
+- **涉及文件**: `backend/app/models/user.py`、`backend/app/api/v1/admin.py`
+- **验收**: 普通用户访问 admin 接口返回 403
+
+### 2.5 前端 API 重复定义清理
+- **问题**: `api.js` 中 `translateApi` 和 `customerApi` 各定义了两遍（第 43 行和第 116 行、第 50 行和第 124 行），后者会覆盖前者但内容不一致（后者多了 `tts` 和 `importCustomers`）
+- **改动量**: 合并重复定义，保留完整版本
+- **涉及文件**: `uni-app/src/utils/api.js`
+- **验收**: 文件中每个 API 对象只出现一次
+
+---
+
+## 三、P1 — MVP 补齐（1-2 周）
+
+### 3.1 新用户引导流程
+
+**对应产品设计**: 用户旅程 §3.1 — 30 秒上手
+
+| 步骤 | 说明 |
+|------|------|
+| 首次注册登录后 | 弹出引导弹窗:"你主要卖什么产品？" |
+| 输入产品信息 | 名称 + 描述 + 目标市场 |
+| 自动生成 | 3 条营销文案 + 关键词建议 |
+| 保存产品 | 写入产品库 |
+| 跳转客户页 | 提示"添加或导入客户" |
+
+**涉及文件**:
+- `uni-app/src/pages/index/index.vue` — 首次登录检测 + 引导弹窗
+- `backend/app/services/onboarding.py` — 首次生成逻辑
+- `backend/app/api/v1/onboarding.py` — 引导 API
+
+**状态**: ✅ 已完成
+
+**验收**: 新注册用户登录后 30 秒内看到生成的营销文案
+
+### 3.2 真实数据分析
+
+**对应**: 首页仪表盘、数据分析页面
+
+- **后端**: 统计 API 已存在（`analytics.py`），数据来自数据库查询
+- **前端**: `analytics.vue` 已接入 `analyticsApi.getOverview()` 真实数据
+- **涉及文件**: `uni-app/src/pages/analytics/analytics.vue`、`backend/app/services/analytics.py`
+- **状态**: ✅ 已完成（首页和数据分析页面数据均来自真实接口）
+
+### 3.3 报价单 PDF 生成
+
+**对应**: 功能设计 §2.5
+
+- **后端**: `pdf_generator.py` 引用了 `weasyprint` 但该库未在 `requirements.txt` 中，且当前生成逻辑是纯文本
+- **改动**:
+  1. 将 `weasyprint` 加入 `requirements.txt`
+  2. 安装系统依赖（`libpango`、`libcairo` 等）
+  3. 实现正式的 HTML→PDF 模板渲染
+- **涉及文件**: `backend/app/services/pdf_generator.py`、`backend/requirements.txt`
+- **状态**: ✅ 已完成（weasyprint 模板 + HTML→PDF 渲染）
+- **验收**: `/quotations/{id}/pdf` 返回真实 PDF 文件
+
+### 3.4 TTS 前端集成
+
+**对应**: 功能设计 §2.3
+
+- **后端**: `tts.py` 已实现
+- **前端**: 翻译页面需添加"播放"按钮调用 TTS API
+- **涉及文件**: `uni-app/src/pages/translate/translate.vue`、`backend/app/api/v1/translate.py`
+- **状态**: ✅ 已完成（后端增加 GET 端点适配前端 downloadFile）
+- **验收**: 翻译结果可点击播放语音
+
+### 3.5 错误监控接入
+
+**对应**: 架构安全
+
+- 接入 Sentry 或其他错误监控服务
+- 后端: `sentry-sdk` 集成到 FastAPI
+- 前端: `uni-app` 错误捕获上报
+- **涉及文件**: `backend/app/main.py`、`backend/app/config.py`、`backend/requirements.txt`
+- **状态**: ✅ 已完成（Sentry FastAPI + SQLAlchemy 集成，配置 SENTRY_DSN 即可启用）
+- **验收**: 配置 SENTRY_DSN 后，故意制造错误可在监控平台看到
+
+---
+
+## 四、P2 — 体验增强（2-3 周）
+
+### 4.1 付费/计费系统
+
+**对应**: 盈利模式 §6
+
+| 模块 | 说明 |
+|------|------|
+| 支付 API | 接入微信支付（JSAPI）— 代码已完成，需微信支付商户号 |
+| 订阅管理 | `subscriptions` 表 + 到期自动降级 |
+| 前端升级页 | 展示 Free/Pro/Enterprise 对比 + 支付按钮 |
+| 配额联动 | 支付成功后自动更新 `user.tier` |
+
+**涉及文件**:
+- `backend/app/models/subscription.py`（新）
+- `backend/app/api/v1/payment.py`（新）
+- `backend/app/services/payment.py`（新）
+- `uni-app/src/pages/upgrade/upgrade.vue`（新）
+
+**状态**: ✅ 代码已完成（需配置微信支付商户号后真正可用）
+
+**验收**: 用户可完成从 free 到 pro 的完整支付升级流程
+
+### 4.2 应用内通知中心
+
+- **改动**:
+  - 新增 `notifications` 表
+  - 通知 API（列表/已读/删除/未读数）
+  - 前端通知中心页面 + 首页未读红点
+- **涉及文件**: `backend/app/models/notification.py`、`backend/app/api/v1/notification.py`、`backend/app/services/notification.py`、`uni-app/src/pages/notification/notification.vue`
+- **额外**: Celery 沉默客户检测任务同时写入应用内通知
+- **状态**: ✅ 已完成
+- **验收**: 沉默客户提醒、系统通知等在应用内可见
+
+### 4.3 数据导出
+
+- 客户列表导出 CSV
+- 报价单批量导出 CSV
+- **涉及文件**: `backend/app/services/export.py`、`backend/app/api/v1/customer.py`、`backend/app/api/v1/quotation.py`
+- **状态**: ✅ 已完成
+- **验收**: 访问 `/api/v1/customers/export/csv` 和 `/api/v1/quotations/export/csv` 下载文件
+
+### 4.4 速率限制
+
+**对应**: API设计 §5
+
+- 新增 `RateLimitMiddleware`，使用 Redis + 1 分钟窗口计数器
+- free: 100 req/min, pro: 500, enterprise: 2000
+- 超限返回 429，响应头携带 `X-RateLimit-Remaining`
+- **涉及文件**: `backend/app/core/middleware.py`、`backend/app/main.py`
+- **状态**: ✅ 已完成
+- **验收**: 超过限制返回 429
+
+### 4.5 用户反馈 & 帮助系统
+
+- 反馈提交（Bug/功能建议/其他）
+- 常见问题 FAQ（内置 4 条常见问题）
+- **涉及文件**: `backend/app/models/feedback.py`、`backend/app/api/v1/feedback.py`、`uni-app/src/pages/feedback/feedback.vue`
+- **状态**: ✅ 已完成
+- **验收**: 用户可提交反馈并查看常见问题
+
+---
+
+## 五、P3 — 护城河建设（4-6 周）
+
+### 5.1 AI 编辑学习回路
+
+**对应**: 护城河 §5.1
+
+当前 `messages` 表已有 `ai_suggestions`、`selected_suggestion`、`user_edited` 字段：
+
+1. 用户选择某个 AI 建议 → 记录正反馈（signal） ✅
+2. 用户修改 AI 建议再发送 → 记录差异（diff） ✅
+3. 系统定期分析用户偏好风格 ✅
+4. 下次生成时使用用户偏好做 few-shot ✅
+
+**涉及文件**:
+- `backend/app/services/preference.py`（新）— UserPreferenceService
+- `backend/app/api/v1/interaction.py`（新）— 选择/编辑/分析 API
+- `backend/app/models/preference.py`（新）— PreferenceAnalysis 模型
+- `backend/app/ai/router.py` — 注入 preference_context
+- `backend/app/ai/providers/openai.py` — 接受 preference_context 参数
+- `backend/app/ai/providers/claude.py` — 同上
+- `backend/app/ai/providers/spark.py` — 同上
+- `backend/app/ai/providers/local.py` — 同上
+- `backend/app/api/v1/translate.py` — getUserPreferenceContext + 传递到 AI layer
+- `backend/app/api/v1/marketing.py` — 同上
+- `backend/app/services/translation.py` — 透传 preference_context
+- `backend/app/services/marketing.py` — 透传 preference_context
+- `uni-app/src/utils/api.js` — 新增 interactionApi
+
+**验收**: 用户多次编辑后，AI 回复风格逐渐接近用户习惯
+
+### 5.2 营销效果追踪
+
+**对应**: 功能设计 §2.2
+
+- 记录用户复制了哪些营销文案 ✅
+- 记录用户发送了哪些文案 ✅
+- 展示文案使用统计（复制次数、发送次数、效果评分） ✅
+- **涉及文件**: `backend/app/models/preference.py`（MarketingEffect 模型）、`backend/app/services/marketing_effect.py`（新）、`backend/app/api/v1/interaction.py`（效果追踪端点）、`backend/app/services/analytics.py`（增加 marketing stats）、`backend/app/api/v1/analytics.py`（增加 marketing 统计接口）
+- **验收**: 营销素材页展示"已复制 15 次"等统计数据
+
+### 5.3 沉默客户模式算法
+
+**对应**: 护城河 §5.3
+
+1. 风险评分算法（沉默天数 + 活跃度 + 谈判阶段 + 关键词检测） ✅
+2. 评分等级输出（high/medium/low/minimal） ✅
+3. 跟进建议生成 ✅
+
+**涉及文件**:
+- `backend/app/services/silent_pattern.py`（新）— SilentPatternService
+- `backend/app/api/v1/silent_pattern.py`（新）— 风险分析 + 建议 API
+- `uni-app/src/utils/api.js` — 新增 silentPatternApi
+
+**验收**: 沉默客户列表显示风险评分等级及跟进建议
+
+### 5.4 语料库离线训练
+
+**对应**: AI架构 §4.3
+
+- `corpus_entries` 表已有数据但无训练逻辑：
+  1. embedding 向量计算（OpenAI text-embedding-3-small） ✅
+  2. 质量评分自动计算 ✅
+  3. 重复数据去重 ✅
+  4. 低质量数据清理 ✅
+  5. Celery beat 每日定时训练 ✅
+
+**涉及文件**:
+- `backend/app/services/corpus_trainer.py`（新）— 完整训练 pipeline
+- `backend/app/api/v1/training.py`（新）— 训练触发端点
+- `backend/app/workers/tasks.py` — 新增 run_daily_corpus_training 定时任务
+- `backend/app/celery_app.py` — 注册 daily-corpus-training 定时器
+
+**验收**: 语料库达到阈值后自动触发训练，翻译质量可量化提升
+
+### 5.5 报价单智能生成
+
+**对应**: 功能设计 §2.5
+
+从"手动填报价单"升级为"自动识别客户消息→生成报价单草稿":
+1. `extract_info` 识别客户询盘意图（产品、数量、贸易术语） ✅
+2. 自动匹配产品库价格 ✅
+3. 生成报价单草稿（含 matched/unmatched 标识） ✅
+
+**涉及文件**:
+- `backend/app/services/quotation.py` — 新增 generate_from_inquiry 方法
+- `backend/app/api/v1/quotation.py` — 新增 POST /quotations/generate-from-inquiry 端点
+- `uni-app/src/utils/api.js` — 新增 quotationApi.generateFromInquiry
+
+**验收**: 客户说 "How much for 500pcs FOB Shanghai?" → 系统自动生成含金额的报价单草稿
+
+---
+
+## 六、工作量汇总
+
+| 阶段 | 功能点 | 预估 |
+|------|--------|------|
+| **P0** | 微信登录配置、隐私协议、Mock 替换、admin 鉴权、API 去重 | ✅ 2-3 天 |
+| **P1** | 引导流程、数据分析、PDF、TTS、错误监控 | ✅ 1-2 周 |
+| **P2** | 支付系统、通知中心、数据导出、速率限制、帮助反馈 | ✅ 2-3 周 |
+| **P3** | AI 编辑学习、效果追踪、沉默算法、语料库训练、智能报价 | ✅ 4-6 周 |
+
+### 关键依赖
+
+- **P0** 无外部依赖，可立即开始
+- **P1 PDF** 需要服务器安装系统库（libpango, libcairo）
+- **P2 支付** 需要微信支付商户号
+- **P3 训练** 需要语料库自然积累到一定规模后才有意义（已实现 pipeline 和定时任务）
@@ -0,0 +1,327 @@
+# 外贸小助手 (TradeMate) — 功能差距修复计划
+
+> 基于 2026-05-10 全量代码审计
+> 将未完成/存根/未对接功能按优先级分为 FixP0-FixP3 四阶段
+
+---
+
+## 总体概况
+
+| 类别 | 数量 | 说明 |
+|------|------|------|
+| 🔴 外部阻塞（代码就绪） | 4 项 | 微信登录/支付/WhatsApp/AI回退 — 需要配置密钥 |
+| ⚠️ 部分实现/存根 | 4 项 | Push/汇率/PDF任务/weasyprint系统依赖 |
+| ❌ 前端未对接 | 12 项 | 后端有API但前端无入口 |
+| ✅ 完整实现 | ~25 项 | 核心链路前后端均对接 |
+
+---
+
+## FixP0 — 上线阻塞（必须先修复）
+
+### F0.1 Push 推送重写
+
+**问题**: `PushService.send_notification()` 只打印日志，无真实推送。设备注册用内存 dict。Celery 静默客户检测产出提醒但用户收不到。
+
+**方案**:
+1. 新建 `Device` 模型：user_id, platform, push_token, is_active, created_at
+2. 重写 `PushService`：使用 uni-push 或第三方推送通道
+3. `POST /push/register` 改为写数据库
+4. `send_notification()` 调用真实推送 SDK
+5. Celery `check_silent_customers` 任务同时写 Notification + PushService
+
+**涉及文件**:
+- `backend/app/models/device.py`（新）
+- `backend/app/models/__init__.py`
+- `backend/app/services/push.py`（重写）
+- `backend/app/api/v1/push.py`（重写）
+- `uni-app/src/utils/api.js`（新增 pushApi）
+- `uni-app/src/pages/index/index.vue`（注册设备 token）
+- `backend/alembic/versions/004_devices.py`（新）
+
+**预估**: 3-4 天（含前端 token 注册）
+
+### F0.2 汇率服务接入真实 API
+
+**问题**: `GET /api/v1/exchange/convert` 和 `GET /api/v1/exchange/rates` 返回硬编码数据，`EXCHANGE_RATE_API_KEY` 未使用。
+
+**方案**:
+1. 创建 `ExchangeRateService`：调用 exchangerate-api.com 或 国家外汇管理局 API
+2. Redis 缓存 6 小时减少 API 调用
+3. 更新硬编码字典为动态查询
+4. 报价单界面增加汇率显示和币种切换
+
+**涉及文件**:
+- `backend/app/services/exchange.py`（新 — 当前无 service）
+- `backend/app/api/v1/exchange.py`（重写 — 移除硬编码）
+- `uni-app/src/utils/api.js`（新增 exchangeApi）
+- `uni-app/src/pages/translate/translate.vue`（报价单汇率开关）
+
+**预估**: 1-2 天
+
+### F0.3 Celery PDF 任务修复
+
+**问题**: `workers/tasks.py:94` 调用旧纯文本 `generate_pdf_text()` 而非 `pdf_generator.generate_quotation()`。
+
+**方案**:
+- 将 Celery 任务 `generate_quotation_pdf` 改为调用 `pdf_generator.generate_quotation(data)` 并存储 blob
+
+**涉及文件**:
+- `backend/app/workers/tasks.py`（重写 generate_quotation_pdf）
+- `backend/app/services/pdf_generator.py`（增加保存 PDF 到磁盘方法）
+
+**预估**: 0.5 天
+
+### F0.4 weasyprint 系统依赖文档化
+
+**问题**: `requirements.txt` 有 weasyprint 但部署时需系统库，无文档说明。
+
+**方案**:
+- 在 README 和 docker-compose 中增加系统依赖安装说明
+- 若使用 Docker，在 Dockerfile 中提前安装
+
+```dockerfile
+RUN apt-get update && apt-get install -y libpango-1.0-0 libpangocairo-1.0-0 \
+    libgdk-pixbuf2.0-0 libffi-dev libcairo2 libcairo2-dev
+```
+
+**涉及文件**:
+- `Dockerfile`（新增或修改）
+- `README.md`（增加安装说明）
+
+**预估**: 0.5 天
+
+---
+
+## FixP1 — 前端对接（补齐体验）
+
+### F1.1 TTS 播放按钮
+
+**问题**: `GET/POST /api/v1/translate/tts` 后端已实现，翻译页无播放按钮，`api.js` 无 tts API。
+
+**方案**:
+- `api.js` 新增 `translateApi.textToSpeech(text, lang)`
+- `translate.vue` 翻译结果后增加 🔊 播放按钮，调用 `uni.downloadFile` → `uni.playVoice`
+
+**涉及文件**:
+- `uni-app/src/utils/api.js`
+- `uni-app/src/pages/translate/translate.vue`
+
+**预估**: 1 天
+
+### F1.2 信息抽取 + 翻译反馈 UI
+
+**问题**: `POST /translate/extract` 和 `POST /translate/feedback` 有后端无前端。
+
+**方案**:
+- 翻译页增加"抽取信息"按钮（提取客户消息中的产品/数量/价格）
+- 翻译结果增加 1-5 星评分，调用 feedback 端点写入 corpus quality_score
+
+**涉及文件**:
+- `uni-app/src/pages/translate/translate.vue`
+- `uni-app/src/utils/api.js`
+
+**预估**: 1 天
+
+### F1.3 营销关键词 + 竞品分析按钮
+
+**问题**: `POST /marketing/keywords`、`POST /marketing/competitor-analysis` 后端完整，前端营销页无入口。
+
+**方案**:
+- `marketingApi` 增加 `generateKeywords()` 和 `competitorAnalysis()`
+- `marketing.vue` 生成结果下方增加"生成关键词"和"竞品分析"按钮
+
+**涉及文件**:
+- `uni-app/src/utils/api.js`
+- `uni-app/src/pages/marketing/marketing.vue`
+
+**预估**: 1 天
+
+### F1.4 营销效果统计展示
+
+**问题**: `interactionApi.trackMarketingEffect/stats` 前端 API 已定义，`marketing.vue` 未展示统计数据。
+
+**方案**:
+- `marketing.vue` 增加统计卡片："今日复制 X 次 / 今日发送 Y 次 / 本周共 Z 次"
+- 每次复制文案时调用 `trackMarketingEffect({content, event_type:'copy'})`
+- 加载时调用 `getMarketingEffectStats()`
+
+**涉及文件**:
+- `uni-app/src/pages/marketing/marketing.vue`
+
+**预估**: 1 天
+
+### F1.5 AI 偏好展示 + 建议选择/编辑上报
+
+**问题**: `interactionApi.selectSuggestion/recordEdit/analyzePreferences` 已定义，翻译页未对接交互学习回路。
+
+**方案**:
+- 翻译页回复建议列表：用户点击某条 → 调用 `selectSuggestion(msgId, index)`
+- 用户编辑后发送 → 调用 `recordEdit(msgId, editedText)`
+- 设置页增加"AI 学习偏好"展示区（调用 `getPreferences()`）
+
+**涉及文件**:
+- `uni-app/src/pages/translate/translate.vue`
+- `uni-app/src/pages/settings/settings.vue`（如有）
+
+**预估**: 2 天
+
+### F1.6 沉默客户风险展示
+
+**问题**: `silentPatternApi.getRiskAnalysis/getSuggestions` 已定义，客户页未对接。
+
+**方案**:
+- 客户列表每项增加风险等级标识（🔴/🟡/🟢）
+- 客户详情页增加"跟进建议"区域
+- 调用 `getRiskAnalysis()` 在客户页顶部展示风险概况
+
+**涉及文件**:
+- `uni-app/src/pages/customer/customer.vue`（列表）
+- `uni-app/src/pages/customer/detail.vue`（详情）
+
+**预估**: 1.5 天
+
+### F1.7 智能报价按钮
+
+**问题**: `quotationApi.generateFromInquiry` 已定义，报价单页未对接。
+
+**方案**:
+- 报价单列表页增加"从询盘生成"按钮
+- 弹出输入框让用户粘贴客户询盘内容
+- 调用 API 后预览自动填充的报价单草稿
+
+**涉及文件**:
+- `uni-app/src/pages/quotation/quotation.vue`
+- `uni-app/src/pages/quotation/create.vue`（如有）
+
+**预估**: 1.5 天
+
+### F1.8 CSV 导出按钮
+
+**问题**: `GET /customers/export/csv` 和 `GET /quotations/export/csv` 后端完成，前端无导出入口。
+
+**方案**:
+- 客户页和报价单页的导航栏增加"导出"按钮
+- 使用 `uni.downloadFile` 下载 CSV
+
+**涉及文件**:
+- `uni-app/src/pages/customer/customer.vue`
+- `uni-app/src/pages/quotation/quotation.vue`
+
+**预估**: 0.5 天
+
+### F1.9 客户对话历史展示
+
+**问题**: `customerApi.getConversation` 已定义，客户详情页未展示对话记录。
+
+**方案**:
+- 客户详情页增加"对话记录" tab
+- 分页加载消息，显示发送/接收方向
+
+**涉及文件**:
+- `uni-app/src/pages/customer/detail.vue`
+
+**预估**: 1 天
+
+---
+
+## FixP2 — 管理后台补齐
+
+### F2.1 训练后台面板
+
+**问题**: `POST /training/corpus/*` 4 个端点后端完整，无前端入口。
+
+**方案**:
+- admin 页增加"语料库管理"标签
+- 展示语料库统计（总数/高质/低质/嵌入数）
+- 提供"运行训练"、"去重"、"清理"按钮
+
+**涉及文件**:
+- `uni-app/src/pages/admin/admin.vue`
+- `uni-app/src/utils/api.js`（新增 trainingApi）
+
+**预估**: 1 天
+
+### F2.2 反馈管理 + 用户管理增强
+
+**问题**: admin 面板只能看用户列表和改 tier，无反馈管理、系统监控。
+
+**方案**:
+- `GET /admin/feedbacks` 端点
+- admin 页增加"用户反馈"标签：列表/标记处理
+- 增加系统状态监控（Celery 队列长度、Redis 状态）
+
+**涉及文件**:
+- `backend/app/api/v1/admin.py`（新增反馈列表端点）
+- `uni-app/src/pages/admin/admin.vue`
+
+**预估**: 2 天
+
+---
+
+## FixP3 — 深层清理
+
+### F3.1 汇率集成报价单
+
+**问题**: 报价单创建/编辑时不可切换币种，无实时汇率。
+
+**方案**:
+- 报价单创建页增加币种选择（USD/CNY/EUR/GBP/JPY）
+- 调用 ExchangeRateService 自动换算
+- 报价单 PDF 显示原始币种金额和换算后金额
+
+**涉及文件**:
+- `backend/app/services/quotation.py`（create_quotation 加入汇率换算）
+- `backend/app/services/pdf_generator.py`（PDF 模板增加双币种行）
+- `uni-app/src/pages/quotation/create.vue`
+
+**预估**: 2 天
+
+### F3.2 Admin 统计指标扩展
+
+**问题**: admin dashboard 只返回 total_users/paid_users，缺少业务指标。
+
+**方案**:
+- `GET /admin/dashboard` 增加：今日活跃用户数、API 调用量、新增客户数、新建报价单数
+- 基于 `UsageLog` 聚合统计
+
+**涉及文件**:
+- `backend/app/services/admin.py`（如有）
+- `backend/app/api/v1/admin.py`
+
+**预估**: 1 天
+
+---
+
+## 工作量汇总
+
+| 阶段 | 项目 | 预估 |
+|------|------|------|
+| **FixP0** | Push 重写 + 汇率 API + PDF 任务修复 + weasyprint 依赖 | 5-6 天 |
+| **FixP1** | 9 项前端对接（TTS/抽取/关键词/效果/偏好/风险/报价/导出/对话） | 10-12 天 |
+| **FixP2** | 训练面板 + 反馈管理 | 3 天 |
+| **FixP3** | 汇率集成报价 + admin 统计扩展 | 3 天 |
+| **合计** | | **21-24 天** |
+
+### 外部依赖（开发期间可 mock）
+
+| 依赖 | 说明 |
+|------|------|
+| `EXCHANGE_RATE_API_KEY` | 免费版 exchangerate-api.com 即可 |
+| 推送通道 | uni-push（免费）或第三方通道 |
+| 微信商户号 | 支付上线必需 |
+
+### 建议执行顺序
+
+```
+FixP0.1 Push 重写 ────────────────────────── 最紧急，否则静默客户提醒等于没有
+  ↓
+FixP0.2 汇率 + FixP0.3 PDF 任务 ────────── 并行，无依赖
+  ↓
+FixP1.5 AI 偏好 + FixP1.6 沉默风险 ─────── P3 功能的最后闭环
+  ↓
+FixP1.1~1.4 TTS/抽取/关键词/效果 ──────── 批量前端对接
+  ↓
+FixP1.7~1.9 智能报价/导出/对话 ─────────── 报价 + 客户页增强
+  ↓
+FixP2 + FixP3 ─────────────────────────── 管理后台 + 深度清理
+```
@@ -1,8 +1,8 @@
 # 外贸小助手 (TradeMate) — 产品设计文档

-> 版本: v1.0
-> 创建日期: 2026-05-08
-> 状态: 初始设计
+> 版本: v1.1
+> 创建日期: 2026-05-10
+> 状态: V2 规划中

 ---

@@ -39,23 +39,35 @@
 ### 2.1 功能全景图

 ```
-┌─────────────────────────────────────────────────────┐
-│                    外贸小助手                         │
-│                                                      │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │
-│  │ 营销素材  │  │ 智能沟通  │  │ 客户跟进  │          │
-│  │ 工厂     │  │ 助手     │  │ 引擎     │           │
-│  ├──────────┤  ├──────────┤  ├──────────┤           │
-│  │ 开发信   │  │ 消息翻译  │  │ 沉默检测  │          │
-│  │ 产品文案  │  │ 回复建议  │  │ 跟进提醒  │          │
-│  │ 关键词   │  │ 一键发送  │  │ 话术推荐  │          │
-│  │ 竞品分析  │  │ 语气调整  │  │ 周期提醒  │          │
-│  └──────────┘  └──────────┘  └──────────┘           │
-│                                                      │
-│  ┌─────────────────────────────────────────┐         │
-│  │  跨功能支撑: 报价单生成 / 汇率换算      │         │
-│  └─────────────────────────────────────────┘         │
-└─────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────────┐
+│                        外贸小助手 V2                              │
+│                                                                  │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────────┐  │
+│  │ 营销素材  │  │ 智能沟通  │  │ 客户跟进  │  │ 智能决策中心   │  │
+│  │ 工厂     │  │ 助手     │  │ 引擎     │  │ (新增)         │  │
+│  ├──────────┤  ├──────────┤  ├──────────┤  ├────────────────┤  │
+│  │ 开发信   │  │ 消息翻译  │  │ 沉默检测  │  │ 健康度看板    │  │
+│  │ 产品文案  │  │ 回复建议  │  │ 跟进提醒  │  │ 客户评分      │  │
+│  │ 关键词   │  │ 语气调整  │  │ 话术推荐  │  │ 行动建议      │  │
+│  │ 竞品分析  │  │ TTS播放  │  │ 周期提醒  │  │ 趋势预警      │  │
+│  └──────────┘  └──────────┘  └─────┬────┘  └────────────────┘  │
+│                                     │                            │
+│  ┌──────────────────────────────────┼──────────────────────────┐ │
+│  │  AI智能跟进助手 (新增)           │                          │ │
+│  │  ┌─ 时机判断 ─ 内容生成 ─ 渠道选择 ─ 效果追踪 ─┐          │ │
+│  │  └──────────────────────────────────────────────┘          │ │
+│  └──────────────────────────────────┬──────────────────────────┘ │
+│                                     │                            │
+│  ┌──────────────────────────────────┼──────────────────────────┐ │
+│  │  智能市场机会分析 (新增)         │                          │ │
+│  │  ┌─ 趋势分析 ─ 客户发现 ─ 竞争情报 ─ 策略报告 ─┐          │ │
+│  │  └──────────────────────────────────────────────┘          │ │
+│  └─────────────────────────────────────────────────────────────┘ │
+│                                                                  │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │  跨功能支撑: 报价单生成 / 汇率换算 / 合规筛查 / 文档模板 │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
 ```

 ### 2.2 功能一：营销素材工厂（帮用户"有内容可发"）
@@ -174,6 +186,154 @@
  - 用户确认 → 生成正式报价单图片 → 一键发送
 ```

+### 2.6 功能四：客户健康度看板（帮用户"一眼看清该追谁"）
+
+#### 用户场景
+> "我有50多个客户，除了最近联系的那几个，其他谁在流失、谁快成交了，我心里完全没数。"
+
+#### 交互流程
+
+```
+[用户打开小程序]
+  └─ 点击"客户" → 顶部展示健康度总览卡片:
+       ├─ 🟢 活跃客户: 12
+       ├─ 🟡 需关注: 5
+       ├─ 🔴 高危流失: 3
+       └─ 📊 整体健康趋势（本周 vs 上周）
+
+[点击具体客户]
+  └─ 进入客户详情 → 健康度看板:
+       ├─ 综合评分: 78/100（评分趋势 ↑↓）
+       ├─ 评分维度明细:
+       │   ├─ 📈 响应趋势: +15%（回复速度在变快）
+       │   ├─ 💬 情感轨迹: 正面（AI分析最近3条消息）
+       │   ├─ 📋 询盘深度: "问了MOQ和认证"（成交信号）
+       │   ├─ ⏰ 沉默天数: 3天
+       │   └─ 💰 预估价值: $12,500
+       └─ 🎯 系统建议动作:
+            "客户问过MOQ和认证，建议明天发认证证书和报价单跟进"
+```
+
+#### 核心机制
+
+- **评分透明可解释**: 不像竞品黑盒打分，每个维度都有来源和原因
+- **多维度融合**: 响应趋势 + 情感分析 + 行为信号 + 沉默天数 + 商业价值
+- **Actionable**: 不只是分数，而是"到底是什么问题 + 建议怎么做"
+
+#### 数据来源（全在现有数据库里，无需外部API）
+
+| 维度 | 数据源 | 现有字段 |
+|------|--------|---------|
+| 响应趋势 | messages | created_at, direction |
+| 情感轨迹 | messages | content（AI分析） |
+| 询盘深度 | messages | content（关键词匹配） |
+| 沉默天数 | customers | last_contact_at |
+| 商业价值 | quotations | total, status |
+
+### 2.7 功能五：AI智能跟进助手（帮用户"知道什么时候跟、怎么跟"）
+
+#### 用户场景
+> "报完价客户就没消息了，我不知道该不该发消息、什么时候发、发什么内容合适。"
+
+#### 交互流程
+
+```
+[系统自动运行]
+  └─ AI 持续评估每个客户的跟进状态:
+       ├─ 每个客户生成"最优跟进时机"（基于历史互动模式）
+       ├─ 不同客户不同策略:
+       │   ├─ 客户A（沉默3天，之前聊报价）: "建议今晚8点WhatsApp发认证资料"
+       │   ├─ 客户B（沉默7天，之前聊样品）: "建议邮件发新品目录 + 限时折扣"
+       │   └─ 客户C（回盘积极，在比价）: "客户可能在对比，建议3天后主动降价5%"
+       └─ 系统主动推送通知:
+            "📌 跟进提醒: 客户Carlos沉默4天，最优跟进窗口还剩2天"
+
+[用户点击提醒]
+  └─ 进入跟进界面:
+       ├─ 客户背景摘要（快速回顾）
+       ├─ AI推荐的跟进内容（基于上次对话定制）
+       ├─ 选择渠道: WhatsApp / Email / 电话
+       └─ 一键发送 / 编辑后发送
+
+[发送后]
+  └─ 自动打标: "已跟进" → 继续监控客户反应
+  └─ 若3天内客户回复 → 标记"跟进成功" → 更新评分
+  └─ 若客户未回复 → 自动调整下一次跟进策略
+```
+
+#### 核心机制
+
+- **不是固定时间间隔**: 竞品用3/7/14天固定规则，AI根据客户状态动态判断
+- **多渠道选择**: 根据客户历史偏好推荐最佳渠道
+- **内容个性化**: 每次跟进都基于上次对话 + 产品库 + 市场信息生成
+- **闭环追踪**: 跟进→回复（或不回复）→调整策略
+
+#### 对比竞品
+
+| 维度 | 竞品 EDM 序列 | TradeMate AI 跟进 |
+|------|-------------|------------------|
+| 触发方式 | 预设时间（3/7/14天） | AI动态评估最佳时机 |
+| 内容 | 模板化 | 每次个性化生成 |
+| 渠道 | 仅邮件 | WhatsApp/邮件/电话 |
+| 适应性 | 固定流程 | 根据客户反应自动调整 |
+| 成本 | 邮件服务费 | 现有AI能力，零新增成本 |
+
+### 2.8 功能六：智能市场机会分析（帮用户"找到该开发哪个市场"）
+
+#### 用户场景
+> "我想开发新市场，但不知道哪个国家对我的产品需求大、竞争情况怎么样、应该怎么切入。"
+
+#### 交互流程
+
+```
+[用户输入产品信息]
+  └─ 点击"市场分析"
+  └─ AI 自动执行:
+       1. 调取免费国际贸易统计数据分析目标市场趋势
+       2. 搜索公开B2B平台/行业黄页发现潜在客户
+       3. 分析目标市场竞争格局和定价
+       4. 生成市场进入策略报告
+
+[用户收到报告]
+  ┌─────────────────────────────────────┐
+  │   📊 户外折叠椅 · 市场机会报告       │
+  │                                      │
+  │   🎯 推荐市场 Top 3:                  │
+  │   1. 美国 (+23% 进口增长) — 建议主攻  │
+  │   2. 德国 (+15%) — 中高端定位         │
+  │   3. 东南亚 (+40% 增长快速) — 建议布局 │
+  │                                      │
+  │   👥 潜在客户示例:                     │
+  │   · OutdoorLiving Inc. (美国)         │
+  │   · GartenPro GmbH (德国)             │
+  │   · CampingZone (东南亚)              │
+  │                                      │
+  │   💡 进入策略建议:                     │
+  │   · 美国: 侧重防水+承重卖点            │
+  │   · 德国: 强调环保认证                │
+  │   · 东南亚: 主打性价比                │
+  └─────────────────────────────────────┘
+
+[用户下一步]
+  └─ 点击"生成开发信" → AI 自动适配目标市场的文化习惯生成文案
+  └─ 保存报告到产品库 → 随时查阅
+```
+
+#### 核心机制
+
+- **零数据采购成本**: 使用免费国际贸易统计 API + AI 搜索，不买海关数据
+- **海关数据竞品的问题**: 数据滞后3-6个月，只有提单记录无具体联系人
+- **我们的方案**: 不只告诉你"谁买了"，而是"怎么找到他们、怎么卖进去"
+
+#### 数据源
+
+| 数据源 | 用途 | 成本 |
+|--------|------|------|
+| UN COMTRADE / ITC TradeMap | 国际贸易统计数据 | 免费 |
+| Google Custom Search / SerpAPI | B2B平台/黄页公开数据 | 免费~$50/月 |
+| Wikipedia/OpenStreetMap | 国家基础信息 | 免费 |
+| AI 已有知识 | 市场策略、文化习惯 | 已有 |
+
 ---

 ## 三、用户旅程
@@ -222,11 +382,13 @@

 ## 五、护城河策略

-详见 `TECH_ARCHITECTURE.md` 第 5 章，核心三层：
+详见 `TECH_ARCHITECTURE.md` 第 5 章，核心五层：

 1. **外贸垂直语料库**：用户每次使用产生的翻译/回复数据，积累成行业专属语料
 2. **用户产品知识库**：产品信息+客户偏好+历史报价，迁移成本极高
 3. **沉默客户模式算法**：跨用户行为数据产生的预测能力，网络效应
+4. **客户健康度评分模型**：基于多维度行为数据的客户价值评估，用户用得越久模型越准
+5. **AI跟进策略引擎**：基于历史跟进成功率的学习模型，持续优化时机/内容/渠道

 ---

@@ -244,7 +406,8 @@

 | 阶段 | 时间 | 功能 |
 |------|------|------|
-| MVP | 第1-4周 | 智能翻译+回复建议+基础营销素材+产品库 |
-| V2 | 第5-8周 | 沉默客户跟进+WhatsApp集成+报价单生成 |
-| V3 | 第9-12周 | 语料库训练+回复质量优化+多人协作 |
-| V4 | 第13-16周 | 跨用户A/B测试+预测算法+API开放 |
+| MVP | 第1-4周 | 智能翻译+回复建议+基础营销素材+产品库 ✅ |
+| V2 | 第5-8周 | 沉默客户跟进+WhatsApp集成+报价单生成 ✅ |
+| V3 | 第9-12周 | 语料库训练+回复质量优化+多人协作 ✅ |
+| V4 | 第13-16周 | 跨用户A/B测试+预测算法+API开放 ✅ |
+| **V5** | **第17-20周** | **客户健康度看板+智能跟进助手+市场机会分析** |
@@ -1,7 +1,8 @@
 # 外贸小助手 (TradeMate) — 技术架构文档

-> 版本: v1.0
-> 创建日期: 2026-05-08
+> 版本: v1.1
+> 创建日期: 2026-05-10
+> 更新: 新增客户健康度看板、AI跟进助手、市场机会分析三大模块

 ---

@@ -34,6 +35,8 @@
 │  │ - 翻译回复 │  │ - Router    │  │ - Webhook   │   │
 │  │ - 客户跟进 │  │ - 语料库   │  │ - 会话管理  │   │
 │  │ - 报价单   │  │ - 成本控制  │  │             │   │
+│  │ - 健康度   │  │ - 市场分析  │  │             │   │
+│  │ - 跟进引擎 │  │ - 跟进策略  │  │             │   │
 │  └─────┬─────┘  └──────┬──────┘  └──────┬───────┘   │
 │        │                │                  │          │
 │  ┌─────┴─────────────────┴─────────────────┴──────┐  │
@@ -99,6 +102,9 @@ trade-assistant/
 │   │   │   ├── marketing.py      # 营销素材生成
 │   │   │   ├── translation.py    # 翻译+回复引擎
 │   │   │   ├── customer.py       # 客户跟进引擎
+│   │   │   ├── customer_health.py # 客户健康度评分 (新增)
+│   │   │   ├── followup_engine.py # AI跟进策略引擎 (新增)
+│   │   │   ├── market_analysis.py # 市场机会分析 (新增)
 │   │   │   ├── quotation.py      # 报价单服务
 │   │   │   └── whatsapp.py       # WhatsApp 服务
 │   │   │
@@ -325,7 +331,212 @@ WhatsApp User                    WhatsApp Cloud API                    TradeMate

 ---

-## 八、安全设计
+## 八、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 推送
+
+#### 数据模型
+
+```python
+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
+```
+
+```python
+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次跟进的最佳实践"
+```
+
+---
+
+## 十一、安全设计

 | 维度 | 措施 |
 |------|------|
@@ -338,7 +549,7 @@ WhatsApp User                    WhatsApp Cloud API                    TradeMate

 ---

-## 九、部署架构
+## 十二、部署架构

 ```
 开发环境: docker-compose up（单机）
@@ -0,0 +1,195 @@
+# 外贸小助手 (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 + 潜在客户 + 策略建议
+□ 报告可保存到产品库
+□ 报告可一键跳转生成营销文案
+□ 渐进式加载（先展示趋势，逐步补充完整报告）
+```