Files
trade-assistant/PROGRESS.md
T
wlt 7317fbe012 feat: add AI Digital Employee agent orchestrator with pipeline tracking
- New AgentPipeline model with JSONB pipeline_data for stages/leads/summary
- AgentOrchestrator service chains DiscoveryService search→analyze→outreach→auto-save
- 3 new API endpoints: POST /agent/start, GET /agent/pipelines, GET /agent/{id}
- Full Agent dashboard Vue component with stats, pipeline grid, leads table, outreach preview
- Sidebar redesigned with AI Agent as primary entry point
- Updated PROGRESS.md, AGENTS.md, DATABASE_SCHEMA.md with latest state
2026-06-16 18:30:56 +08:00

409 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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-apiHMAC-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 + 游客模式 |
---
*本文档由任务进度跟踪系统维护*