TradeMate Dev
512 lines
25 KiB
Markdown
512 lines
25 KiB
Markdown
# TradeMate (外贸小助手) - 项目进度文档
|
||
|
||
**更新时间**: 2026-07-11
|
||
**状态**: ✅ 生产环境运行中 — 收费方式调整（免费试用/私有化部署/买断源码）+ 功能审计补全 + SEO 营销落地页 + 部署优化
|
||
|
||
---
|
||
|
||
## 一、服务状态
|
||
|
||
| 服务 | 地址 | 状态 |
|
||
|------|------|------|
|
||
| 后端 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数字员工" 已接入路由 `/workspace/agent` 与侧边栏菜单（图标 MagicStick）；`/agent` 重定向到 `/workspace/agent` |
|
||
|
||
**工作流程**:
|
||
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. PC 工作台 UX 大幅重构 — 合并工作区 + CommandK 命令面板 ✅ [NEW]
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| **侧边栏精简** | 从 11 项合并为 5 项（首页/客户/业务/翻译/更多），减少 4 层级为 5 个清晰入口 |
|
||
| **CommandK 命令面板** | `user-frontend/src/components/CommandK.vue` — 全局 Ctrl+K 调出，快速搜索/导航/操作 |
|
||
| **工作区合并** | 客户/挖掘/跟进 → `WorkspaceCustomer.vue`；翻译/产品/报价/营销 → `WorkspaceBiz.vue` |
|
||
| **仪表盘简化** | `NewHome.vue` 精简为数据看板，去掉冗余入口 |
|
||
| **旧路由保留** | 旧页面可通过隐藏路由访问，保证兼容性 |
|
||
|
||
### 15. uni-app 移动端 4Tab 合并重构 ✅ [NEW]
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| **Tab Bar 精简** | 从 5 项（首页/客户/营销/报价/我的）改为 4 项（首页/客户/业务/我的） |
|
||
| **客户工作台** | `workspace-customer.vue` — 3 个内联标签（客户列表/挖掘新客/智能跟进） |
|
||
| **业务工作台** | `workspace-biz.vue` — 4 个内联标签（翻译/产品库/报价单/营销素材） |
|
||
| **个人中心更新** | `profile.vue` — 通知中心/数据分析/团队/升级会员/联系客服 |
|
||
| **pages.json** | 标签栏配置同步更新，新增 workspace 页面注册 |
|
||
|
||
### 16. 定价模型重构 + 升级弹窗 + 生态 UI ✅ [NEW]
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| **定价页重构** | `Upgrade.vue` 重新设计，新增 Yearly 套餐卡片 + 功能对比表 |
|
||
| **升级弹窗** | `UpgradeModal.vue` — 全局组件，任何页面可直接调起 |
|
||
| **生态入口** | `WorkspaceLanding.vue` — 工作台首页展示套餐状态 + 升级入口 |
|
||
| **路由整合** | 新增 `/workspace/upgrade` 路由，侧边栏可直接访问 |
|
||
|
||
### 17. 产品策略文档 + Agent 技能 + Chrome 浏览器扩展 ✅ [NEW]
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| **产品策略文档** | `docs/PRODUCT_STRATEGY.md` — 319 行完整产品路线图（市场分析/定位/功能规划/定价策略/增长路线） |
|
||
| **Agent 技能定义** | 3 个 `.opencode/skills/` 文件 — `customer-discovery.md` / `marketing-content.md` / `translate-reply.md` |
|
||
| **Chrome 扩展** | `browser-extension/` — 完整 Chrome 插件，支持 LinkedIn/Amazon/AliExpress 页面集成 |
|
||
| **浏览器扩展功能** | popup 面板调用 API 翻译/提取客户信息、网页右键菜单、自动填写报价单 |
|
||
|
||
### 18. 管理后台 AI 路由增强 ✅ [NEW]
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| **新增路由标签** | agent (数字员工)、followup (智能跟进)、outreach (开发信)、competitor (竞品分析) |
|
||
| **一行代码改动** | `admin-frontend/src/views/Config.vue` 更新 `ai_routing` 字段标签 |
|
||
|
||
### 19. 用户工作台 i18n 导航键更新 ✅ [NEW]
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| **中文 locale** | `zh-CN.json` — 新增 home/customers/biz/agent 导航键 |
|
||
| **英文 locale** | `en.json` — 同步新增对应导航键 |
|
||
| **双语言适配** | 确保重构后的侧边栏/面包屑/页面标题完整支持中英文切换 |
|
||
|
||
### 20. 后端持续优化 ✅ [NEW]
|
||
|
||
| 序号 | 文件 | 问题描述 | 状态 |
|
||
|------|------|----------|------|
|
||
| 16 | `customer_health.py` | 健康分计算逻辑优化，增加活跃度权重 | ✅ 已修复 |
|
||
| 17 | `corpus_trainer.py` | 语料库训练流程修复，避免空数据处理 | ✅ 已修复 |
|
||
| 18 | `middleware.py` | 中间件性能优化，减少请求路径匹配耗时 | ✅ 已修复 |
|
||
| 19 | `conftest.py` | 测试基础设施增强，新增 fixture 复用 | ✅ 已修复 |
|
||
|
||
### 21. 核心 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}` | ✅ 正常 |
|
||
|
||
---
|
||
|
||
### 22. 收费方式调整 + 功能审计补全 + SEO/营销落地页 + 部署优化 ✅ [NEW]
|
||
|
||
> **方向调整（2026-07-11）**：停止以「按月订阅」为主推的 SaaS 收费模型，改为合规的「免费试用 / 私有化部署 / 买断源码」三档方案。
|
||
> 合规依据：仅持 ICP 备案即可销售「免费试用 + 私有化部署（年付授权）+ 买断源码（一次性软件/服务合同）」；若上线「托管付费订阅」需另行办理 ICP 经营许可证。
|
||
|
||
| 模块 | 文件 | 说明 |
|
||
|------|------|------|
|
||
| **定价页重构** | `user-frontend/src/views/Upgrade.vue` + `UpgradeModal.vue`、`uni-app/src/pages/upgrade/upgrade.vue` | 三档方案：免费试用 ¥0 / 私有化部署 ¥39,800 年 / 买断源码 ¥98,000 一次性；价格为可配置展示值 |
|
||
| **企业线索后端** | `backend/app/api/v1/leads.py` + `models/enterprise_lead.py` + `alembic/versions/add_enterprise_leads.py` | 新增 `POST /api/v1/leads`（免登录），`EnterpriseLead` 模型 + `enterprise_leads` 表；CSRF 对 `/api/v1/leads` 放行 |
|
||
| **线索测试** | `backend/tests/test_leads_api.py` | 3 个用例全部通过 |
|
||
| **功能审计补全** | `user-frontend/src/router/index.js`、`UserLayout.vue`、`admin-frontend/src/api/index.js`、`admin-frontend/src/views/Users.vue` | 修复 Agent 路由未接入工作台；修复后台用户编辑调用错误端点（`PATCH /users/{id}/tier`、`POST .../toggle-active`、`PATCH .../role`、`/admin/usage-stats`） |
|
||
| **浏览器扩展补全** | `browser-extension/api/client.js`、`popup/popup.js`、`popup/index.html` | 新增「提取客户信息」（`extractInfo()`）+ 「客户」Tab + 升级链接指向 `/workspace/upgrade` |
|
||
| **后端测试** | `backend` pytest | 158 用例 + 3 leads 用例全部通过，无失败 |
|
||
| **SEO 营销落地页** | `landing/index.html`、`landing/robots.txt`、`landing/sitemap.xml` | 语义化可抓取 HTML + JSON-LD（`SoftwareApplication` + `FAQPage`）+ OG/Twitter + 规范化链接 + 内链到 `/app/`、`/workspace/`、定价；`robots.txt`/`sitemap.xml` 置于站点根 |
|
||
| **前端 SEO 增强** | `uni-app/index.html` | 修复损坏的 `og:image`/`twitter:image`（指向 `/app/static/images/yzr/yuzhiran.jpg`），更新描述为新三档定价 |
|
||
| **部署配置** | `deploy/frontend/nginx.conf` | 四路布局：`/` → 营销落地页（根）、`/app/` → uni-app H5、`/workspace/` → 用户工作台、`/admin/` → 管理后台、`/api/` → 后端 127.0.0.1:8000；各 SPA 带 `try_files ... /index.html` fallback |
|
||
|
||
**部署目录结构（目标）**：
|
||
```
|
||
/www/wwwroot/trade.yuzhiran.com/
|
||
├── index.html ← landing/ 营销落地页（SEO 主入口）
|
||
├── robots.txt ← landing/robots.txt
|
||
├── sitemap.xml ← landing/sitemap.xml
|
||
├── app/ ← uni-app 构建产物 (base: /app/)
|
||
├── workspace/ ← user-frontend 构建产物 (base: /workspace/)
|
||
├── admin/ ← admin-frontend 构建产物 (base: /admin/)
|
||
└── （后端由 systemd/uvicorn 运行，经 /api/ 代理）
|
||
```
|
||
|
||
**注意**：本环境无服务器 SSH 凭据，无法实际推送部署；上述产物与 `nginx.conf` 为部署就绪状态，需在目标服务器执行构建 + 拷贝 + `alembic upgrade head` + 重载 nginx。
|
||
|
||
---
|
||
|
||
## 三、待办事项
|
||
|
||
### 低优先级
|
||
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
|
||
# 1. 营销落地页（SEO 主入口）
|
||
cp landing/index.html /www/wwwroot/trade.yuzhiran.com/index.html
|
||
cp landing/robots.txt landing/sitemap.xml /www/wwwroot/trade.yuzhiran.com/
|
||
|
||
# 2. 三端 SPA 构建 & 部署
|
||
cd uni-app && npm run build:h5 && cp -r dist/build/h5/* /www/wwwroot/trade.yuzhiran.com/app/
|
||
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/
|
||
|
||
# 3. 后端：迁移 + 重启 (systemd)
|
||
cd backend && source venv/bin/activate && alembic upgrade head
|
||
sudo systemctl restart ftrade-backend.service
|
||
sudo journalctl -u ftrade-backend.service -n 20
|
||
|
||
# 4. Nginx：套用 deploy/frontend/nginx.conf 的 4 路布局后重载
|
||
sudo nginx -t && sudo nginx -s reload
|
||
|
||
# 本地开发启动
|
||
cd backend && source venv/bin/activate && uvicorn app.main:app --reload --port 8000
|
||
```
|
||
|
||
---
|
||
|
||
## 九、历史变更记录
|
||
|
||
| 日期 | 变更内容 |
|
||
|------|----------|
|
||
| 2026-07-11 | **收费方式调整**: 免费试用/私有化部署/买断源码三档；功能审计补全；SEO 营销落地页 + nginx 四路布局部署优化 |
|
||
| 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 + 游客模式 |
|
||
|
||
---
|
||
|
||
*本文档由任务进度跟踪系统维护*
|