Quant Speed Market (量迹市场)

一个集成了电商、社区论坛、AI 服务与 AR/3D 模型展示的全栈应用平台。

📖 项目简介

npm run dev:weapp Quant Speed Market 是一个基于现代技术栈构建的综合性平台，旨在为用户提供从商品购买、技术交流到 AI 工具使用的全方位体验。项目采用前后端分离架构，包含 Django 后端 API、React Web 管理端以及 Taro 微信小程序客户端。

✨ 功能特性

• 🛍️ 电商商城：支持商品浏览、购物车、微信支付 (WeChat Pay V3)、订单管理。
• 💬 社区论坛：支持发帖、回帖、话题分类、富文本编辑。
• 🤖 AI 服务：集成 AI 工具，提供智能辅助服务。
• 🕶️ AR/3D 展示：基于 Three.js 的 3D 模型预览与 AR 交互体验。
• 📱 多端适配：微信小程序原生体验，Web 端响应式管理后台。
• 🔒 安全认证：微信一键登录、手机号绑定、JWT 认证。

🛠️ 技术栈与依赖

Backend (后端)

• Framework: Django 6.0 + Django REST Framework 3.16
• Database: PostgreSQL (psycopg2)
• Payment: WeChat Pay V3 (wechatpayv3)
• Documentation: drf-spectacular (OpenAPI 3.0)
• Deployment: Docker, Gunicorn

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. 克隆仓库

git clone <repository-url>
cd market_page

3. 后端环境配置 (Backend)

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)

cd ../frontend

# 安装依赖
npm install

# 启动开发服务器 (默认端口 5173)
npm run dev

5. 小程序配置 (Miniprogram)

cd ../miniprogram

# 安装依赖
npm install

# 编译并监听 (微信小程序)
npm run dev:weapp

启动后，请打开微信开发者工具，导入 miniprogram 目录进行预览。

📦 构建与运行

Backend

# 收集静态文件
python manage.py collectstatic --noinput

# 使用 Gunicorn 运行 (生产环境)
gunicorn config.wsgi:application --bind 0.0.0.0:8000

Frontend

# 构建生产版本
npm run build

# 预览构建产物
npm run preview

Miniprogram

# 构建生产版本 (微信小程序)
npm run build:weapp

🧪 测试与覆盖率

Backend

# 运行所有测试
python manage.py test

# 运行特定模块测试
python manage.py test shop.tests

Frontend / Miniprogram

# 代码风格检查
npm run lint

🚢 部署指南

Docker 部署 (推荐)

项目包含 Dockerfile 和 docker-compose.yml (根目录下)，可一键启动。

# 在项目根目录
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/	获取论坛话题列表

API 文档: 启动后端后访问 http://localhost:8000/api/schema/swagger-ui/ 查看完整 Swagger 文档。

📂 目录结构说明

market_page/
├── backend/                # Django 后端源码
│   ├── community/          # 论坛社区模块
│   ├── shop/               # 电商与支付模块
│   ├── config/             # 项目核心配置
│   ├── uploads/            # 用户上传文件 (媒体资源)
│   ├── manage.py           # Django 管理脚本
│   └── requirements.txt    # Python 依赖
├── frontend/               # React Web 端源码
│   ├── src/
│   │   ├── components/     # 公共组件 (3D模型、弹窗等)
│   │   ├── pages/          # 页面路由 (Home, Forum, Payment)
│   │   └── assets/         # 静态资源
│   └── vite.config.js      # Vite 配置
├── miniprogram/            # Taro 小程序源码
│   ├── src/
│   │   ├── pages/          # 小程序页面
│   │   ├── subpackages/    # 分包页面 (分销、论坛详情等)
│   │   └── components/     # 小程序组件
│   └── project.config.json # 微信小程序配置
└── docker-compose.yml      # Docker 编排文件

🤝 贡献规范

欢迎提交 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: 微信支付依赖真实商户号和证书，本地开发请使用模拟数据或沙箱环境。

📜 许可证

本项目采用 MIT License 许可证。

📧 联系方式

• 作者: (Your Name/Organization)
• 邮箱: contact@example.com
• 项目主页: https://github.com/yourusername/market-page