# 外贸小助手 (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 和定时任务）