Files

T

TradeMate Dev 5d2bced39f docs: update project docs and clean up redundant files

- PROGRESS.md: update to 2026-05-29 with security hardening (T-005),
  4-frontend architecture, AI provider refactoring, discovery features,
  landing page/referral/quota, desktop layout, admin AI management
- AGENTS.md: add AI provider list (Alibaba/NVIDIA, removed Claude/DeepL/Local),
  DB-driven config, CSRF/rate-limit/CORS notes, admin_ai reload quirk
- .env.example: sync with actual config, replace deprecated providers
  with current Sensenova/OpencodeGo/NVIDIA/Spark/Alibaba
- docs/PROJECT_STATUS.md: archive (fully superseded by PROGRESS.md)
- Remove generated JS files (_bing_search.js, _batch_search.js)
- Remove empty directories (data/corpus, data/models)
- Remove backend/.coverage (test artifact)
- Fix services/.gitignore to cover _bing_search.js
- Include pending AI provider DB admin feature (admin_ai, AIProvider model,
  AIProviders.vue, migration) and T-008 test report

2026-05-29 11:15:33 +08:00

12 KiB

Raw Blame History

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`	✅ 正常

三、待办事项

低优先级

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

四、技术栈

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

六、开发命令速查

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

游客模式体验:

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

注册用户登录:

手机号: 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 + 游客模式

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

12 KiB Raw Blame History

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

一、服务状态

二、已完成的工作

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

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

3. AI 提供商重构 ✅

4. 客户挖掘 (Discovery) ✅

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

6. PC 桌面端布局 ✅

7. Bug 修复 (共 13 个)

8. 游客模式 (Guest Mode) ✅

9. 管理后台完整可用

10. 其他增强

11. 核心 API 测试通过

三、待办事项

低优先级

四、技术栈

4.1 后端

4.2 AI 提供商

4.3 前端

4.4 部署

五、目录结构

六、开发命令速查

七、快速验证

八、部署架构

九、历史变更记录

12 KiB

Raw Blame History