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 和定时任务）