313 lines
11 KiB
Markdown
313 lines
11 KiB
Markdown
# Quant Speed Market (量迹市场)
|
||
|
||
> 一个集成了电商、社区论坛、AI 服务与 AR/3D 模型展示的全栈应用平台。
|
||
|
||
|
||
|
||
## 📖 项目简介
|
||
npm run dev:weapp
|
||
Quant Speed Market 是一个基于现代技术栈构建的综合性平台，旨在为用户提供从商品购买、技术交流到 AI 工具使用的全方位体验。项目采用前后端分离架构，包含 Django 后端 API、React Web 管理端以及 Taro 微信小程序客户端。
|
||
|
||
## ✨ 功能特性
|
||
|
||
### 🛍️ 电商商城系统
|
||
- **商品管理**：ESP32硬件配置、库存管理、3D模型展示、产品特性标签
|
||
- **订单管理**：多类型订单（硬件/课程/活动）、完整状态流转、物流跟踪
|
||
- **支付系统**：微信支付V3集成、多种支付方式、安全签名验证、支付回调处理
|
||
- **分销系统**：二级分销体系、邀请机制、佣金计算（一级10%/二级2%）、提现管理
|
||
- **课程系统**：视频课程、固定时间课程、讲师管理、课程报名与咨询
|
||
|
||
### 💬 社区论坛系统
|
||
- **活动管理**：线上线下活动、报名表单自定义、支付状态同步、审核机制
|
||
- **论坛帖子**：技术讨论、求助问答、经验分享、官方公告四大分类
|
||
- **互动功能**：点赞、置顶、嵌套回复（楼中楼）、多媒体附件支持
|
||
- **公告系统**：时效控制、跳转链接、优先级排序、置顶功能
|
||
|
||
### 🤖 AI 服务系统
|
||
- **语音转写**：阿里云听悟集成、多格式音频支持、说话人分离、状态自动刷新
|
||
- **AI智能评估**：多模型支持（通义千问系列）、模板化评估、0-100分制评分、详细评语生成
|
||
- **智能总结**：多类型总结（段落/对话/问答/思维导图）、Markdown格式输出、异步生成机制
|
||
- **比赛集成**：AI评委身份、评分维度映射、自动评分同步、人工干预支持
|
||
|
||
### 🏆 竞赛评审系统
|
||
- **比赛管理**：多状态流程（草稿→发布→报名→提交→评审→结束）、时间管理、可见性控制
|
||
- **项目管理**：文件附件支持（PPT/PDF/图片/视频）、封面展示、状态管理
|
||
- **评分系统**：多维度评分、权重配置、评委评语、防重复评分机制
|
||
- **权限控制**：选手/评委/嘉宾三角色体系、报名审核、角色权限管理
|
||
|
||
### 🕶️ AR/3D 展示
|
||
- **3D模型预览**：基于Three.js的交互式3D模型展示
|
||
- **AR交互体验**：增强现实功能集成
|
||
- **多媒体支持**：图片、视频、文件等多格式媒体处理
|
||
|
||
### 📱 多端适配
|
||
- **微信小程序**：Taro框架开发、原生小程序体验、分包优化
|
||
- **Web管理端**：React + Ant Design、响应式设计、管理后台功能
|
||
- **跨平台支持**：可扩展至H5、支付宝小程序等平台
|
||
|
||
### 🔒 安全认证
|
||
- **微信登录**：小程序code换取session、OpenID/UnionID管理
|
||
- **手机验证**：验证码登录、手机号绑定、用户合并机制
|
||
- **JWT认证**：Token-based身份验证、API访问控制
|
||
- **权限验证**：基于角色的访问控制、操作权限验证
|
||
|
||
## 🛠️ 技术栈与依赖
|
||
|
||
### Backend (后端)
|
||
- **Framework**: Django 6.0 + Django REST Framework 3.16
|
||
- **Database**: PostgreSQL (psycopg2)
|
||
- **Payment**: WeChat Pay V3 (wechatpayv3)
|
||
- **AI Services**: 阿里云听悟 (语音转写)、通义千问 (AI评估)
|
||
- **Cloud Storage**: 阿里云OSS (文件存储)
|
||
- **Documentation**: drf-spectacular (OpenAPI 3.0)
|
||
- **Deployment**: Docker, Gunicorn
|
||
- **Authentication**: JWT + 微信OAuth2.0
|
||
|
||
### Frontend (Web 端)
|
||
- **Core**: React 19 + Vite 7
|
||
- **UI Library**: Ant Design 6
|
||
- **3D Engine**: Three.js + @react-three/fiber
|
||
- **Routing**: React Router v7
|
||
|
||
### Miniprogram (小程序)
|
||
- **Framework**: Taro 3.6 (React Flavor)
|
||
- **UI Library**: Taro UI
|
||
- **Styles**: SCSS
|
||
- **Platform**: WeChat Mini Program (可扩展至 H5/Alipay 等)
|
||
|
||
## 🚀 本地开发环境搭建
|
||
|
||
### 1. 系统要求
|
||
- **Node.js**: >= 18.0.0
|
||
- **Python**: >= 3.10
|
||
- **PostgreSQL**: >= 13
|
||
- **WeChat DevTools**: 最新版 (用于小程序开发)
|
||
|
||
### 2. 克隆仓库
|
||
```bash
|
||
git clone <repository-url>
|
||
cd market_page
|
||
```
|
||
|
||
### 3. 后端环境配置 (Backend)
|
||
```bash
|
||
cd backend
|
||
|
||
# 创建虚拟环境 (推荐)
|
||
python -m venv venv
|
||
# Windows 激活
|
||
venv\Scripts\activate
|
||
# macOS/Linux 激活
|
||
source venv/bin/activate
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 数据库迁移
|
||
python manage.py migrate
|
||
|
||
# 创建超级用户
|
||
python manage.py createsuperuser
|
||
|
||
# 启动开发服务器 (默认端口 8000)
|
||
python manage.py runserver
|
||
```
|
||
|
||
### 4. Web 前端配置 (Frontend)
|
||
```bash
|
||
cd ../frontend
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 启动开发服务器 (默认端口 5173)
|
||
npm run dev
|
||
```
|
||
|
||
### 5. 小程序配置 (Miniprogram)
|
||
```bash
|
||
cd ../miniprogram
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 编译并监听 (微信小程序)
|
||
npm run dev:weapp
|
||
```
|
||
*启动后，请打开微信开发者工具，导入 `miniprogram` 目录进行预览。*
|
||
|
||
## 📦 构建与运行
|
||
|
||
### Backend
|
||
```bash
|
||
# 收集静态文件
|
||
python manage.py collectstatic --noinput
|
||
|
||
# 使用 Gunicorn 运行 (生产环境)
|
||
gunicorn config.wsgi:application --bind 0.0.0.0:8000
|
||
```
|
||
|
||
### Frontend
|
||
```bash
|
||
# 构建生产版本
|
||
npm run build
|
||
|
||
# 预览构建产物
|
||
npm run preview
|
||
```
|
||
|
||
### Miniprogram
|
||
```bash
|
||
# 构建生产版本 (微信小程序)
|
||
npm run build:weapp
|
||
```
|
||
|
||
## 🧪 测试与覆盖率
|
||
|
||
### Backend
|
||
```bash
|
||
# 运行所有测试
|
||
python manage.py test
|
||
|
||
# 运行特定模块测试
|
||
python manage.py test shop.tests
|
||
```
|
||
|
||
### Frontend / Miniprogram
|
||
```bash
|
||
# 代码风格检查
|
||
npm run lint
|
||
```
|
||
|
||
## 🚢 部署指南
|
||
|
||
### Docker 部署 (推荐)
|
||
项目包含 `Dockerfile` 和 `docker-compose.yml` (根目录下)，可一键启动。
|
||
|
||
```bash
|
||
# 在项目根目录
|
||
docker-compose up -d --build
|
||
```
|
||
*注意：请确保已在 `backend/config/settings.py` 或环境变量中配置好生产环境的数据库连接和密钥。*
|
||
|
||
## 🔌 API 接口示例
|
||
|
||
后端提供 RESTful API，以下为核心接口示例：
|
||
|
||
| 方法 | 路径 | 描述 |
|
||
| --- | --- | --- |
|
||
| POST | `/api/shop/wechat/login/` | 微信用户登录 (换取 JWT) |
|
||
| GET | `/api/shop/configs/` | 获取 ESP32/商品配置列表 |
|
||
| POST | `/api/shop/orders/` | 创建新订单 |
|
||
| POST | `/api/shop/pay/` | 发起微信支付 |
|
||
| GET | `/api/community/topics/` | 获取论坛话题列表 |
|
||
| POST | `/api/ai/transcription/` | 创建语音转写任务 |
|
||
| GET | `/api/ai/transcription/{id}/` | 获取转写任务状态 |
|
||
| POST | `/api/competition/projects/` | 提交参赛项目 |
|
||
| GET | `/api/competition/projects/{id}/score/` | 获取项目评分 |
|
||
| POST | `/api/competition/scoring/` | 评委提交评分 |
|
||
|
||
**API 文档**: 启动后端后访问 `http://localhost:8000/api/schema/swagger-ui/` 查看完整 Swagger 文档。
|
||
|
||
## 📂 目录结构说明
|
||
|
||
```
|
||
market_page/
|
||
├── backend/ # Django 后端源码
|
||
│ ├── ai_services/ # AI服务模块 (语音转写、AI评估)
|
||
│ │ ├── models.py # 转写任务、AI评估模板模型
|
||
│ │ ├── views.py # API接口 (转写、评估、总结)
|
||
│ │ └── services.py # 阿里云听悟、通义千问服务集成
|
||
│ ├── community/ # 论坛社区模块
|
||
│ │ ├── models.py # 活动、帖子、回复、公告模型
|
||
│ │ ├── views.py # 社区API接口
|
||
│ │ └── admin_actions.py # 后台管理动作
|
||
│ ├── competition/ # 竞赛评审模块
|
||
│ │ ├── models.py # 比赛、项目、评分、维度模型
|
||
│ │ ├── judge_views.py # 评委系统接口
|
||
│ │ └── templates/ # 评委系统前端页面
|
||
│ ├── shop/ # 电商与支付模块
|
||
│ │ ├── models.py # 商品、订单、支付、用户模型
|
||
│ │ ├── services.py # 微信支付、短信服务
|
||
│ │ └── admin_actions.py # 订单管理动作
|
||
│ ├── config/ # 项目核心配置
|
||
│ │ ├── settings.py # Django配置
|
||
│ │ └── urls.py # 主路由配置
|
||
│ ├── uploads/ # 用户上传文件 (媒体资源)
|
||
│ ├── manage.py # Django 管理脚本
|
||
│ ├── requirements.txt # Python 依赖
|
||
│ └── Dockerfile # 后端容器配置
|
||
├── frontend/ # React Web 端源码
|
||
│ ├── src/
|
||
│ │ ├── components/ # 公共组件 (3D模型、弹窗等)
|
||
│ │ ├── pages/ # 页面路由 (Home, Forum, Payment)
|
||
│ │ ├── hooks/ # 自定义React Hooks
|
||
│ │ └── assets/ # 静态资源
|
||
│ ├── public/ # 公共资源
|
||
│ └── vite.config.js # Vite 配置
|
||
├── miniprogram/ # Taro 小程序源码
|
||
│ ├── src/
|
||
│ │ ├── pages/ # 小程序页面
|
||
│ │ ├── subpackages/ # 分包页面 (分销、论坛详情等)
|
||
│ │ ├── components/ # 小程序组件
|
||
│ │ └── utils/ # 工具函数
|
||
│ └── project.config.json # 微信小程序配置
|
||
├── docker-compose.yml # Docker 编排文件
|
||
└── README.md # 项目文档
|
||
```
|
||
|
||
## 🤝 贡献规范
|
||
|
||
欢迎提交 Pull Request！请遵循以下规范：
|
||
|
||
1. **分支管理**：
|
||
- `main`: 主分支，保持稳定。
|
||
- `dev`: 开发分支。
|
||
- `feat/xxx`: 新功能分支。
|
||
- `fix/xxx`: Bug 修复分支。
|
||
|
||
2. **Commit 格式**：
|
||
- `feat: 添加购物车功能`
|
||
- `fix: 修复支付回调失败问题`
|
||
- `docs: 更新 README`
|
||
- `style: 调整首页样式`
|
||
|
||
3. **PR 流程**：
|
||
- Fork 本仓库。
|
||
- 创建特性分支。
|
||
- 提交代码并推送到您的 Fork。
|
||
- 提交 PR 至 `dev` 分支。
|
||
|
||
## ❓ 常见问题排查
|
||
|
||
- **Q: 后端启动报错 `psycopg2` 相关错误？**
|
||
- A: 请确保本地已安装 PostgreSQL 并且开发库 (`libpq-dev` 或 equivalent) 已就绪。
|
||
|
||
- **Q: 小程序报错 "appID 不合法"？**
|
||
- A: 请在 `miniprogram/project.config.json` 中修改 `appid` 为您自己的测试 ID，或在开发者工具中开启 "不校验合法域名"。
|
||
|
||
- **Q: 微信支付接口调用失败？**
|
||
- A: 微信支付依赖真实商户号和证书，本地开发请使用模拟数据或沙箱环境。
|
||
|
||
- **Q: AI语音转写任务状态一直显示"处理中"？**
|
||
- A: 检查阿里云听悟服务配置是否正确，包括AccessKey、AppKey等参数。可通过`python manage.py check_aliyun_config`命令验证配置。
|
||
|
||
- **Q: AI评估功能无法正常使用？**
|
||
- A: 确保通义千问API密钥已正确配置，检查模型调用配额是否充足。评估模板中的提示词需要符合模型要求。
|
||
|
||
- **Q: 分销佣金没有正确计算？**
|
||
- A: 检查产品是否设置了独立分润比例，确认分销员状态为"正常"，查看佣金日志了解具体计算过程。
|
||
|
||
- **Q: 竞赛项目无法提交？**
|
||
- A: 确认比赛状态为"作品提交中"，检查是否已报名该比赛，确保每人每比赛只能提交一个项目。
|
||
|
||
## 📜 许可证
|
||
|
||
本项目采用 [MIT License](LICENSE) 许可证。
|
||
|
||
## 📧 联系方式
|
||
|
||
- **作者**: (Your Name/Organization)
|
||
- **邮箱**: contact@example.com
|
||
- **项目主页**: https://github.com/yourusername/market-page
|