trade-assistant/docs/DEV_PLAN.md

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