# 外贸小助手 (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 ─────────────────────────── 管理后台 + 深度清理
```