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