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

**更新时间**: 2026-05-29 12:00  
**状态**: ✅ 生产分支活跃开发 — 安全加固完成 + 4 前端项目并行 + 客户挖掘+AI 模型管理

---

## 一、服务状态

| 服务 | 地址 | 状态 |
|------|------|------|
| 后端 API | http://localhost:8000 | ✅ 运行中 |
| API 文档 | http://localhost:8000/docs | ✅ 可用 |
| 前端 H5 (uni-app) | http://localhost:5173 | ✅ 运行中 |
| 管理后台 (admin-frontend) | http://localhost:5173 | ✅ 运行中 |
| 用户工作台 (user-frontend) | http://localhost:5174 | ✅ 运行中 |
| 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 模式中间件；auth/payment/profile 等敏感端点必检；webhook 跳过 |
| **敏感日志清理** | 全代码审计 | 移除 Token/Key 等敏感信息打印 (T-002) |

### 3. AI 提供商重构 ✅

| 变更 | 说明 |
|------|------|
| **移除** | Claude (`claude.py`)、DeepL (`deepl.py`)、本地模型 (`local.py`) |
| **新增** | 阿里机器翻译 (`alibaba.py`)、NVIDIA (`nvidia.py`) |
| **主提供商** | Sensenova (商汤, `sensenova.py`) |
| **Fallback** | OpencodeGo → NVIDIA → 讯飞 Spark |
| **DB 驱动配置** | 新增 `AIProvider` 模型 + `admin_ai.py` API → 管理后台在线增删改 AI 模型 |
| **路由规则** | `router.py` 支持 `reload_from_db()` 从数据库实时加载配置 |
| **Env 自动种子** | 启动时从 `.env` 读取 API Key 自动写入 DB |

### 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` — 管理后台配置搜索提供商 |

### 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` | 前端直连后端端口 → 跨域 | ✅ 已修复 |

### 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. 其他增强

| 功能 | 说明 |
|------|------|
| 加载反馈 | 所有 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 (商汤) | 主提供商 | 翻译/回复/营销/提取 |
| OpencodeGo | Fallback | 翻译/回复/营销/提取 |
| NVIDIA | Fallback | 通用对话 |
| 讯飞 Spark | Fallback | 通用对话 |
| 阿里机器翻译 | 专用 | 翻译 (translate) |

### 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/                      # 数据目录
```

---

## 六、开发命令速查

```bash
# 后端
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`

---

## 八、部署架构

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

---

## 九、历史变更记录

| 日期 | 变更内容 |
|------|----------|
| 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 + 游客模式 |

---

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