trade-assistant/docs/FIX_PLAN.md

外贸小助手 (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 中提前安装

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 ─────────────────────────── 管理后台 + 深度清理