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
parent c04fa2c19f
commit 5d2bced39f
31 changed files with 1933 additions and 816 deletions
@@ -0,0 +1,299 @@
+# 🌐 TradeMate 外贸小助手
+
+> **AI 驱动的外贸业务助手** — 专为外贸 SOHO 和小型团队打造
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Python](https://img.shields.io/badge/python-3.11-green.svg)
+![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-cyan.svg)
+![Vue](https://img.shields.io/badge/Vue-3.x-orange.svg)
+
+---
+
+## 📖 项目简介
+
+TradeMate 是一个 AI 驱动的外贸业务助手，帮助外贸 SOHO 和小型团队提升工作效率。通过集成大语言模型（Sensenova 星火、OpenAI 等），提供智能翻译、客户管理、营销文案生成、报价单自动生成等核心功能。
+
+**核心定位**：
+- 🎯 面向外贸 SOHO 和小型团队
+- 🌏 中英双语智能翻译
+- 🤖 AI 驱动的营销与报价
+- 📱 移动端优先设计（uni-app）
+
+---
+
+## ✨ 功能特性
+
+### 🔐 认证系统
+- JWT 双 Token 认证（access_token + refresh_token）
+- 游客模式（无需注册即可体验核心功能）
+- 微信小程序登录集成
+- 微信 H5 浏览器静默授权
+
+### 🌐 智能翻译
+- 中英互译（支持多 AI 提供商）
+- 公开翻译接口（游客可用）
+- 翻译质量反馈机制
+
+### 💬 智能回复
+- 基于客户询盘生成回复建议
+- 多风格回复（专业/友好）
+- 结合产品上下文智能生成
+
+### 📊 客户管理
+- 客户 CRUD 操作
+- 沉默客户提醒（可配置天数）
+- 客户对话记录追踪
+- 客户健康度分析
+
+### 📝 营销素材
+- AI 生成营销文案（多风格）
+- 关键词建议
+- 竞品分析
+
+### 📋 报价单管理
+- 从询盘自动生成报价单
+- 报价单 CRUD 操作
+- 多币种支持
+- 报价单状态跟踪
+
+### 📈 数据分析
+- 客户/翻译/报价单统计概览
+- 7 日趋势分析
+- 使用日志记录
+
+### 📱 前端应用
+- **uni-app** — 移动端 H5 + 微信小程序
+- **admin-frontend** — PC 管理后台（Vue 3 + Element Plus）
+- **user-frontend** — 用户工作台（Vue 3 + Element Plus）
+
+### 🔧 管理后台
+- 用户管理（列表/搜索/改套餐/改角色/启用禁用）
+- 使用统计（各功能调用 + 7 日趋势）
+- 操作日志（带筛选器 + 分页）
+- 系统配置（卡片表单）
+
+---
+
+## 🚀 快速开始
+
+### 前置要求
+
+- Docker & Docker Compose
+- Node.js 18+（开发环境）
+- Python 3.11+（开发环境）
+
+### 方式一：Docker Compose 一键启动（推荐）
+
+```bash
+# 1. 克隆项目
+git clone <repository-url>
+cd trade-assistant
+
+# 2. 配置环境变量
+cp backend/.env.example backend/.env
+# 编辑 backend/.env，填入必要的 API Key
+
+# 3. 启动所有服务
+docker-compose up -d
+
+# 4. 访问服务
+# 后端 API: http://localhost:8000
+# API 文档: http://localhost:8000/docs
+# 前端 H5: http://localhost:5173
+```
+
+### 方式二：本地开发环境
+
+```bash
+# 1. 后端开发
+cd backend
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+uvicorn app.main:app --reload --port 8000
+
+# 2. 前端 H5 开发
+cd uni-app
+npm install
+npm run dev:h5
+
+# 3. 管理后台开发
+cd admin-frontend
+npm install
+npm run dev
+
+# 4. 用户工作台开发
+cd user-frontend
+npm install
+npm run dev
+```
+
+---
+
+## ⚙️ 配置说明
+
+### 环境变量 (.env)
+
+| 变量 | 说明 | 示例 |
+|------|------|------|
+| `SECRET_KEY` | JWT 密钥 | `change-me-to-a-secure-key` |
+| `DATABASE_URL` | PostgreSQL 连接串 | `postgresql+asyncpg://user:pass@host:5432/db` |
+| `REDIS_URL` | Redis 连接串 | `redis://localhost:6379/0` |
+| `OPENAI_API_KEY` | OpenAI API Key | `sk-...` |
+| `SENSNOVA_API_KEY` | 星火大模型 API Key | `...` |
+| `DEEPL_API_KEY` | DeepL API Key | `...` |
+| `WECHAT_APP_ID` | 微信小程序 AppID | `wx...` |
+| `WECHAT_APP_SECRET` | 微信小程序 AppSecret | `...` |
+| `FRONTEND_URL` | 前端地址 | `http://localhost:5173` |
+
+### 数据库初始化
+
+```bash
+# 首次启动后，运行数据库迁移
+cd backend
+alembic upgrade head
+```
+
+---
+
+## 📚 API 文档
+
+- **Swagger UI**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+- **详细 API 设计文档**: [docs/API_DESIGN.md](docs/API_DESIGN.md)
+
+### 主要 API 端点
+
+| 模块 | 路径前缀 | 功能 |
+|------|----------|------|
+| 认证 | `/api/v1/auth/*` | 注册、登录、Token 刷新 |
+| 客户 | `/api/v1/customers/*` | 客户 CRUD、沉默客户 |
+| 翻译 | `/api/v1/translate/*` | 翻译、回复建议、信息提取 |
+| 营销 | `/api/v1/marketing/*` | 营销文案、关键词、竞品分析 |
+| 报价单 | `/api/v1/quotations/*` | 报价单 CRUD、从询盘生成 |
+| 分析 | `/api/v1/analytics/*` | 数据统计概览 |
+| WhatsApp | `/api/v1/whatsapp/*` | 消息发送、Webhook |
+
+---
+
+## 🏗️ 技术架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        Nginx (反向代理)                      │
+├─────────────────┬─────────────────┬─────────────────────────┤
+│  admin-frontend │  user-frontend  │       uni-app (H5)      │
+│    (Vue 3)      │    (Vue 3)      │      (移动端)           │
+│    :5173        │      :5174      │       :5173             │
+├─────────────────┴─────────────────┴─────────────────────────┤
+│                    FastAPI Backend (:8000)                   │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │
+│  │  Auth    │ │  AI Router│ │ Business │ │  Celery Worker │ │
+│  │  JWT     │ │  Multi-LLM│ │  Services│ │  Async Tasks   │ │
+│  └──────────┘ └──────────┘ └──────────┘ └────────────────┘ │
+├─────────────────────────────────────────────────────────────┤
+│                    PostgreSQL + Redis                        │
+│                    (pgvector for AI embeddings)              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 技术栈
+
+| 层级 | 技术 |
+|------|------|
+| 后端 | FastAPI + SQLAlchemy 1.4 async + asyncpg |
+| 数据库 | PostgreSQL 15 + pgvector + Redis 7 |
+| AI 提供商 | Sensenova (星火), OpenAI, DeepL |
+| 前端 | Vue 3 + uni-app + Element Plus |
+| 任务队列 | Celery + Redis |
+| 容器化 | Docker + Docker Compose |
+
+---
+
+## 📦 项目结构
+
+```
+trade-assistant/
+├── backend/                  # FastAPI 后端
+│   ├── app/                  # 应用代码
+│   │   ├── api/              # API 路由
+│   │   ├── core/             # 核心配置、安全、中间件
+│   │   ├── models/           # 数据库模型
+│   │   ├── services/         # 业务服务
+│   │   ├── ai/               # AI 路由和提供商
+│   │   └── main.py           # 应用入口
+│   ├── alembic/              # 数据库迁移
+│   ├── tests/                # 测试
+│   ├── Dockerfile
+│   └── requirements.txt
+├── uni-app/                  # 移动端 H5 + 小程序
+├── admin-frontend/           # PC 管理后台
+├── user-frontend/            # 用户工作台
+├── nginx/                    # Nginx 配置
+├── docs/                     # 项目文档
+│   ├── API_DESIGN.md
+│   ├── DATABASE_SCHEMA.md
+│   └── TECH_ARCHITECTURE.md
+├── docker-compose.yml        # Docker 编排
+├── Makefile                  # 快捷命令
+└── README.md                 # 本文件
+```
+
+---
+
+## 🧪 测试
+
+```bash
+# 运行所有后端测试
+cd backend && venv/bin/pytest
+
+# 运行特定测试文件
+venv/bin/pytest tests/test_auth_api.py
+
+# 运行关键词过滤测试
+venv/bin/pytest tests/ -k "test_login"
+```
+
+---
+
+## 📄 相关文档
+
+- [项目进度](PROGRESS.md) — 任务完成情况和待办事项
+- [Agent 指南](AGENTS.md) — 开发规范和关键注意事项
+- [API 设计](docs/API_DESIGN.md) — 详细 API 接口文档
+- [数据库 schema](docs/DATABASE_SCHEMA.md) — 数据模型定义
+- [技术架构](docs/TECH_ARCHITECTURE.md) — 系统架构详解
+
+---
+
+## 📝 开发规范
+
+- **提交信息**：聚焦 "why" 而非 "what"，使用英文
+- **测试**：新功能必须编写测试，提交前运行 `pytest`
+- **代码注释**：除非特别要求，否则不添加注释
+- **UI**：中文界面，移动端优先
+- **AI 服务**：使用 `MarketingService()`（无需 DB），客户健康用 `CustomerHealthService(db)`
+
+---
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+---
+
+## 📜 许可证
+
+MIT License
+
+---
+
+## 🔗 相关链接
+
+- [API 文档](http://localhost:8000/docs)
+- [项目文档](docs/)
+- [产品设计方案](docs/PRODUCT_DESIGN.md)
+
+---
+
+*TradeMate — 让外贸更简单* 🚀