trade-assistant/PROGRESS.md

TradeMate (外贸小助手) - 项目进度文档

更新时间: 2026-06-02 12:00
状态: ✅ 生产环境运行中 — AI 路由 DB 驱动 + 翻译配额全链路 + ECS RAM 角色认证

---

一、服务状态

服务	地址	状态
后端 API	http://localhost:8000	✅ 运行中
API 文档	http://localhost:8000/docs	✅ 可用
主站 — 营销落地页	https://trade.yuzhiran.com/	✅ 已部署
主站 — 移动端 H5	https://trade.yuzhiran.com/app/	✅ 已部署
主站 — 管理后台	https://trade.yuzhiran.com/admin/	✅ 已部署
主站 — 用户工作台	https://trade.yuzhiran.com/workspace/	✅ 已部署
镜像站	https://www.yuzhiran.com.cn/	✅ 同步部署
Redis	localhost:6379	✅ 运行中
PostgreSQL	localhost:5432	✅ 运行中

测试用户:

• 手机号: 13800138099 (或注册新用户)
• 密码: testpass123

---

二、已完成的工作

1. 项目架构演进 (4 前端项目并行)

项目	技术栈	端口	用途
backend/	FastAPI + SQLAlchemy async + asyncpg	8000	API 后端
uni-app/	Vue 3 + uni-app	5173	移动端 H5 / 微信小程序
admin-frontend/	Vue 3 + Element Plus + Vite	5173	PC 管理后台 (base: /admin/)
user-frontend/	Vue 3 + Element Plus + Vite	5174	用户工作台 (base: /workspace/)

2. 安全加固 (T-005) ✅

功能	实现	详情
CORS 白名单	app/core/middleware.py	限制特定前端域名、方法和请求头
速率限制	app/core/middleware.py	登录 5次/分、注册 3次/时、改密 3次/5分、支付 20次/分、Admin 30次/分
CSRF 防护	app/core/csrf.py	双提交 Cookie 模式中间件；payment/profile 等敏感端点必检；login/register/webhook 跳过
敏感日志清理	全代码审计	移除 Token/Key 等敏感信息打印 (T-002)

3. AI 提供商重构 ✅

变更	说明
移除	Claude (claude.py)、DeepL (deepl.py)、本地模型 (local.py)、OpencodeGo (opencode_go.py)、讯飞 Spark (spark.py)
当前提供商	Sensenova (商汤) + NVIDIA + 阿里机器翻译 (ECS RAM 角色)
DB 驱动配置	AIProvider 模型 + admin_ai.py API → 管理后台在线增删改 AI 模型
路由规则 DB 化	从 config.py 硬编码改为 system_configs 表读取 (key: ai_routing)，保存后自动重载
ECS RAM 角色	阿里翻译无需 AccessKey，优先使用 ECS 实例 RAM 角色获取 STS 临时凭证
Env 自动种子	启动时从 .env 读取 API Key 自动写入 DB

3.1 当前 AI 提供商

名称	类型	模型	用途
Sensenova (商汤)	sensenova	deepseek-v4-flash	翻译/回复/营销/提取/聊天
NVIDIA	nvidia	stepfun-ai/step-3.7-flash	翻译/回复/营销/提取/聊天
Sensenova (商汤) lite	sensenova	sensenova-6.7-flash-lite	轻量备用
NVIDIA qwen	nvidia	qwen/qwen3.5-397b-a17b	备用
阿里翻译	alibaba-mt	alibaba-mt	专用翻译 (ecommerce/general)

4. 客户挖掘 (Discovery) ✅

功能	文件	说明
搜索结果历史	discovery_record.py	自动保存每次搜索 + 带超时修复
联系人提取	discovery.py	点击从公司官网抓取 Email/Phone/WhatsApp/WeChat
真实搜索结果	mcp_search_server.py	对接 Google Custom Search 返回真实数据

5. 落地页 + 推荐系统 + 付费体系 ✅

功能	说明
落地页	静态 marketing 页面
推荐系统	referral.py — 推荐码 + 推荐关系追踪
用量配额	usage.py — 每日功能调用计数 + 上限判断
年费定价	payment.py — 新增 yearly 套餐选项
搜索 API 管理	admin_search.py — 管理后台配置搜索提供商

5.1 支付系统 ✅

组件	文件	说明
统一网关	services/unified_pay.py	对接 宇之然 pay-api，HMAC-SHA256 签名
网关抽象	services/payment_gateway.py	PaymentGateway 抽象基类
支付服务	services/payment.py	多套餐创建/查询/退款/回调
交易记录	models/payment_transaction.py	订单号/金额/状态/退款流水
支付 API	api/v1/payment.py	下单/查询/退款/Webhook 统一入口
管理接口	api/v1/admin.py	交易列表/统计/后台退款
数据迁移	alembic/versions/add_payment_transactions_table.py	payment_transactions 表

支付流程:

1. 前端 POST /api/v1/payment/create-order (plan + pay_type: alipay / wechat)
2. 后端调用 unified pay-api 创建订单，返回 pay_url(支付宝) 或 code_url(微信扫码)
3. 用户完成支付后，pay-api 回调 POST /api/v1/payment/webhook
4. 后端更新订单状态 + 激活用户套餐

凭证: PAY_API_KEY / PAY_API_SECRET 从 .env 读取（外贸助手密钥），HMAC-SHA256 认证

6. PC 桌面端布局 ✅

功能	说明
响应式侧边栏	App.vue 全局侧边栏导航 (admin + user 共用)
修复侧边栏显示	导航 CSS 移至 App.vue 全局样式
消除重复 tabbar	桌面端侧边栏替代移动端底部导航
消除组件边界	侧边栏完全在 App.vue 内部

7. Bug 修复 (共 13 个)

序号	文件	问题描述	状态
1	app/main.py	中间件顺序错误 - TierMiddleware 需要最先执行	✅ 已修复
2	app/core/middleware.py	缺少 getattr 防御性检查	✅ 已修复
3	app/models/user.py	Product.user_id 缺少 ForeignKey	✅ 已修复
4	app/models/customer.py	Customer/Conversation.user_id 缺少 ForeignKey	✅ 已修复
5	app/models/quotation.py	Quotation.user_id 缺少 ForeignKey	✅ 已修复
6	app/api/v1/deps.py	get_current_user_id 读取参数而非 HTTP Header	✅ 已修复
7	app/core/security.py	passlib 与 bcrypt 版本不兼容	✅ 已替换为直接 bcrypt
8	app/ai/providers/openai.py	max_tokens=1000 不足	✅ 已增加到 3000
9	app/ai/providers/openai.py	Sensenova reasoning 字段未处理	✅ 已增强 fallback 逻辑
10	src/App.vue + 全局样式	H5 底部导航覆盖内容	✅ 已修复
11	app/api/v1/auth.py + deps.py	API 500 根因 — 游客 UUID 格式问题	✅ 已修复
12	backend/.env + app/main.py	CORS 配置不当	✅ 已修复
13	uni-app/src/utils/api.js	前端直连后端端口 → 跨域	✅ 已修复
14	app/api/v1/auth.py	登录/注册 CSRF 鸡生蛋 — 匿名用户无 cookie 导致 403	✅ 已修复
15	4 个前端登录/注册页面	后端错误英文直接展示给用户	✅ 已修复

8. 游客模式 (Guest Mode) ✅

功能	接口	说明
游客登录	POST /api/v1/auth/login/guest	生成 JWT，包含 is_guest: true
公开翻译	POST /api/v1/translate/public/translate	无需认证
公开信息提取	POST /api/v1/translate/public/extract	无需认证

9. 管理后台完整可用

功能	说明
用户管理	列表/搜索/改套餐/改角色/启用禁用
使用统计	今日各功能调用 + 7 日趋势
操作日志	带筛选器（动作/用户ID/日期范围）+ 分页
系统配置	卡片表单（input/switch/textarea），逐字段编辑
AI 模型配置	在线增删改 AI 提供商、重载配置、启停控制
搜索配置	搜索提供商管理

10. 翻译配额全链路 ✅

组件	说明
TranslationQuota 模型	按月配额管理，支持 ecommerce/general/llm 三个版本
TranslationQuotaService	自动按月重置、配额检查/扣减/查询/管理
AlibabaMTProvider.translate()	调用前检查配额，调用后扣减字符
OpenAIProvider.translate()	LLM 翻译也走配额检查 (llm 版本)
后台 Quota.vue	配额管理页 (月限额/启用/重置)，修复了 API 路径 bug

11. 管理后台增强

功能	说明
AI 路由规则	配置页新增"AI路由规则"卡片，下拉选择已启用供应商
翻译配额页	修复路径 bug (quotas → translation-quotas)，新增 llm 配额
AI 模型配置	修复侧边栏链接路径
登录跳转	登录后自动跳转仪表盘

12. 其他增强

功能	说明
加载反馈	所有 AI/长操作增加用户友好 loading 状态
提取信息结构化展示	翻译页/首页显示卡片式字段列表（中文标签）
微信静默登录	.env 配置 + 前端 H5 公众号 OAuth
注册/登录记日志	user.register/login/login_guest 写入 usage_logs
Docker Compose 增强	添加 nginx/admin/user/uni-app 服务 + 独立网络 + Redis AOF
CSRF 保护	双提交 Cookie 模式，auth/payment/profile 必检

11. 核心 API 测试通过

功能	接口	状态
健康检查	GET /health	✅ 200
用户注册	POST /api/v1/auth/register	✅ 200
用户登录	POST /api/v1/auth/login	✅ 200
游客登录	POST /api/v1/auth/login/guest	✅ 200
翻译	POST /api/v1/translate/	✅ 正常
智能回复	POST /api/v1/translate/reply	✅ 正常
信息提取	POST /api/v1/translate/extract	✅ 正常
营销文案	POST /api/v1/marketing/generate	✅ 正常
报价单生成	POST /api/v1/quotations/generate-from-inquiry	✅ 正常
数据分析	GET /api/v1/analytics/overview	✅ 正常
产品 CRUD	/api/v1/products/*	✅ 正常
客户 CRUD	/api/v1/customers/*	✅ 正常
套餐计划	GET /api/v1/payment/plans	✅ 正常

---

三、待办事项

低优先级

1. 管理后台统计/日志页有数据验证（目前 usage_logs 为空，显示暂无数据）
2. 测试 WhatsApp 真实集成（需 Meta Business 认证）
3. 性能优化测试
4. 微信小程序端验证

---

四、技术栈

4.1 后端

技术	版本	用途
Python	3.11+	运行环境
FastAPI	latest	Web 框架
SQLAlchemy	1.4 async	ORM
PostgreSQL	15	主数据库
Redis	7	缓存 / 队列 / 速率限制
Celery	5.0+	定时任务 / 异步任务
pgvector	latest	向量存储 (语料库语义搜索)

4.2 AI 提供商

提供商	类型	模型	用途
Sensenova (商汤)	主提供商	deepseek-v4-flash	翻译/回复/营销/提取/聊天
NVIDIA	Fallback	stepfun-ai/step-3.7-flash	翻译/回复/营销/提取/聊天
Sensenova lite	轻量备用	sensenova-6.7-flash-lite	备用
NVIDIA qwen	备用	qwen/qwen3.5-397b-a17b	备用
阿里机器翻译	专用翻译	alibaba-mt	翻译 (ecommerce/general)
已删除	—	—	OpencodeGo / 讯飞 Spark / Claude / DeepL / 本地模型

4.3 前端

项目	技术	用途
uni-app	Vue 3 + uni-app	移动端 H5 / 微信小程序
admin-frontend	Vue 3 + Element Plus + Vite	PC 管理后台
user-frontend	Vue 3 + Element Plus + Vite	用户工作台

4.4 部署

技术	用途
Docker	容器化
Docker Compose	编排 (含 nginx/admin/user/uni-app)
Nginx	反向代理 / SPA fallback
Systemd	进程管理

---

五、目录结构

trade-assistant/
├── backend/                   # FastAPI 后端
│   ├── app/
│   │   ├── api/v1/           # REST API (30+ 路由模块)
│   │   ├── ai/               # AI 抽象层 (router + 5 providers)
│   │   ├── core/             # 安全/中间件/异常 (含 CSRF + 限流)
│   │   ├── models/           # 数据模型 (25+ 模型)
│   │   ├── services/         # 业务逻辑 (30+ 服务)
│   │   ├── workers/          # Celery 任务
│   │   └── main.py           # FastAPI 入口
│   ├── alembic/              # 数据库迁移
│   ├── tests/                # 测试
│   └── Dockerfile
├── uni-app/                   # 移动端 H5 + 小程序
├── admin-frontend/            # PC 管理后台 (Vue 3 + Element Plus)
├── user-frontend/             # 用户工作台 (Vue 3 + Element Plus)
├── nginx/                     # Nginx 配置
├── docker-compose.yml         # Docker 编排 (6 服务)
├── scripts/                   # 运维脚本
├── systemd/                   # Systemd 服务配置
├── docs/                      # 设计文档
└── data/                      # 数据目录

---

六、开发命令速查

# 后端
cd backend && source venv/bin/activate && uvicorn app.main:app --reload --port 8000

# 移动端 H5
cd uni-app && npm run dev:h5

# 管理后台
cd admin-frontend && npm run dev      # :5173, base: /admin/

# 用户工作台
cd user-frontend && npm run dev       # :5174, base: /workspace/

# 测试
cd backend && venv/bin/pytest

# 迁移
cd backend && alembic upgrade head

---

七、快速验证

• 前端 H5: http://localhost:5173
• API 文档: http://localhost:8000/docs

游客模式体验:

1. 点击 "快速体验" 按钮
2. 无需登录即可体验翻译和信息提取功能

注册用户登录:

• 手机号: 13800138099
• 密码: testpass123

---

八、部署架构

8.1 域名

域名	用途
trade.yuzhiran.com	主站 — 营销落地页 + Web 应用（当前生产域名）
www.yuzhiran.com.cn	之前用作镜像站 AI 教育，外贸项目不再使用

8.2 目录结构

trade.yuzhiran.com/
├── /              → 静态营销落地页
├── /app/          → uni-app 构建 (移动端 H5，当前未部署)
├── /admin/        → admin-frontend 构建 (管理后台)
├── /workspace/    → user-frontend 构建 (用户工作台)
└── /api/          → Nginx proxy → 127.0.0.1:8000 (systemd 管理)

8.3 部署流程

# 前端构建 & 部署
cd user-frontend && npm run build && cp -r dist/* /www/wwwroot/trade.yuzhiran.com/workspace/
cd admin-frontend && npm run build && cp -r dist/* /www/wwwroot/trade.yuzhiran.com/admin/

# 后端重启 (systemd)
sudo systemctl restart ftrade-backend.service

# 查看启动日志
sudo journalctl -u ftrade-backend.service -n 20

# 本地开发启动
cd backend && source venv/bin/activate && uvicorn app.main:app --reload --port 8000

---

九、历史变更记录

日期	变更内容
2026-06-02	生产环境部署 + AI 路由 DB 驱动 + 翻译配额扩展至 LLM + ECS RAM 角色认证 + 删除 OpencodeGo/Spark
2026-05-29	安全加固 (T-005): 限流/CSRF/CORS + AI 提供商 DB 管理 + 客户挖掘联系人提取
2026-05-28	加载反馈 + 搜索历史自动保存 + 超时修复
2026-05-26	落地页 + 推荐系统 + 用量配额 + 搜索 API 管理 + 年费定价
2026-05-24	admin-frontend/user-frontend 独立项目 + 认证/发票/客户挖掘
2026-05-22	桌面端响应式布局 + 侧边栏导航
2026-05-21	微信支付 + 翻译配额管理
2026-05-19	AI 助手二期 + 可配置 prompt + FAQ 匹配 + NVIDIA 提供商
2026-05-18	管理后台完整可用 + 注册登录记日志 + 提取信息结构化展示 + 微信静默登录
2026-05-15	OpencodeGo 主提供商 + 路由系统 + AI 模型配置管理
2026-05-13	自定义 tabbar + 首页快捷入口重新设计
2026-05-12	MVP: 核心 API + 前端 H5 + 游客模式

---

本文档由任务进度跟踪系统维护