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

**更新时间**: 2026-06-16 18:30  
**状态**: ✅ 生产环境运行中 — AI 路由 DB 驱动 + 翻译配额全链路 + ECS RAM 角色认证 + AI 数字员工

---

## 一、服务状态

| 服务 | 地址 | 状态 |
|------|------|------|
| 后端 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. AI 数字员工 (Agent Orchestrator) ✅ [NEW]

| 功能 | 文件 | 说明 |
|------|------|------|
| **Pipeline 模型** | `models/agent_pipeline.py` | `agent_pipelines` 表 — UUID PK + JSONB pipeline_data |
| **编排服务** | `services/agent_orchestrator.py` | 串接 DiscoveryService → 分析 → 评分 → 触达 → 自动入库 |
| **Agent API** | `api/v1/agent.py` | 3 端点: POST /start, GET /pipelines, GET /{id} |
| **Agent 仪表盘** | `user-frontend/src/views/Agent.vue` | 统计卡片 + 任务列表 + 流水线进度 + 线索表格 + 触达预览 |
| **侧边栏入口** | `layouts/UserLayout.vue` | "AI数字员工" 作为首位菜单项，图标 MagicStick |

**工作流程**:
1. 用户输入产品名称 + 描述 + 目标市场
2. Agent 自动搜索 → AI 分析匹配度 → 评分排序 → Top 5 生成触达文案
3. 高匹配客户 (≥70分) 自动保存到客户列表
4. 用户在线预览 WhatsApp/LinkedIn/Email 触达文案
5. 4 阶段流水线可视进度 (搜索→分析→触达→完成)

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

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

### 6.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 认证

### 7. PC 桌面端布局 ✅

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

### 8. 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 个前端登录/注册页面 | 后端错误英文直接展示给用户 | ✅ 已修复 |

### 9. 游客模式 (Guest Mode) ✅

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

### 10. 管理后台完整可用

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

### 11. 翻译配额全链路 ✅

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

### 12. 管理后台增强

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

### 13. 其他增强

| 功能 | 说明 |
|------|------|
| 加载反馈 | 所有 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 必检 |

### 14. 核心 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` | ✅ 正常 |
| AI Agent 启动 | `POST /api/v1/agent/start` | ✅ 正常 |
| AI Agent 列表 | `GET /api/v1/agent/pipelines` | ✅ 正常 |
| AI Agent 详情 | `GET /api/v1/agent/{id}` | ✅ 正常 |

---

## 三、待办事项

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

---

## 四、技术栈

### 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+ 路由模块, 含 agent)
│   │   ├── ai/               # AI 抽象层 (router + 5 providers)
│   │   ├── core/             # 安全/中间件/异常 (含 CSRF + 限流)
│   │   ├── models/           # 数据模型 (25+ 模型, 含 agent_pipeline)
│   │   ├── services/         # 业务逻辑 (30+ 服务, 含 agent_orchestrator)
│   │   ├── workers/          # Celery 任务
│   │   └── main.py           # FastAPI 入口
│   ├── alembic/              # 数据库迁移
│   ├── tests/                # 测试
│   └── Dockerfile
├── uni-app/                   # 移动端 H5 + 小程序
├── admin-frontend/            # PC 管理后台 (Vue 3 + Element Plus)
├── user-frontend/             # 用户工作台 (Vue 3 + Element Plus)
│   └── src/views/Agent.vue   # AI 数字员工仪表盘
├── 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`

---

## 八、部署架构

### 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 部署流程

```bash
# 前端构建 & 部署
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-16 | **AI 数字员工**: AgentOrchestrator 编排服务 + AgentPipeline 模型 + Agent API + 前端仪表盘 |
| 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 + 游客模式 |

---

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