TradeMate Dev
7b62c2f8b4
## H5 底部导航修复 (Bug #10) - 精简 App.vue，移除重复 tabbar，仅保留全局样式 - uni-page 设置 height: calc(100% - 50px) + overflow-y: auto - 内容区域精确停在底部导航上方，独立滚动不再叠加 - 恢复 custom-tab-bar 组件 ## 项目进度文档 - PROGRESS.md 更新至 10 个 Bug 修复 - 新增 H5 底部导航修复记录 - 新增历史变更条目
294 lines
12 KiB
Markdown
294 lines
12 KiB
Markdown
# 外贸小助手 (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 和定时任务）
|