This commit is contained in:
jeremygan2021
237
README 2.md
Normal file
237
README 2.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# 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. 克隆仓库
|
||||
```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/` | 获取论坛话题列表 |
|
||||
|
||||
**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](LICENSE) 许可证。
|
||||
|
||||
## 📧 联系方式
|
||||
|
||||
- **作者**: (Your Name/Organization)
|
||||
- **邮箱**: contact@example.com
|
||||
- **项目主页**: https://github.com/yourusername/market-page
|
||||
@@ -41,12 +41,16 @@ def patched_request(self, *args, **kwargs):
|
||||
return original_request(self, *args, **kwargs)
|
||||
Core.request = patched_request
|
||||
|
||||
def get_wechat_pay_client(pay_type=WeChatPayType.NATIVE):
|
||||
def get_wechat_pay_client(pay_type=WeChatPayType.NATIVE, appid=None, config=None):
|
||||
"""
|
||||
获取微信支付 V3 客户端实例的辅助函数
|
||||
"""
|
||||
print(f"正在获取微信支付配置...")
|
||||
wechat_config = WeChatPayConfig.objects.filter(is_active=True).first()
|
||||
|
||||
wechat_config = config
|
||||
if not wechat_config:
|
||||
wechat_config = WeChatPayConfig.objects.filter(is_active=True).first()
|
||||
|
||||
if not wechat_config:
|
||||
print("错误: 数据库中没有激活的 WeChatPayConfig")
|
||||
return None, "支付配置未找到"
|
||||
@@ -55,7 +59,13 @@ def get_wechat_pay_client(pay_type=WeChatPayType.NATIVE):
|
||||
|
||||
# 1. 严格清理所有配置项的空格和换行符
|
||||
mch_id = str(wechat_config.mch_id).strip()
|
||||
appid = str(wechat_config.app_id).strip()
|
||||
|
||||
# 如果传入了 appid，优先使用传入的
|
||||
if not appid:
|
||||
appid = str(wechat_config.app_id).strip()
|
||||
else:
|
||||
appid = str(appid).strip()
|
||||
|
||||
apiv3_key = str(wechat_config.apiv3_key).strip()
|
||||
serial_no = str(wechat_config.mch_cert_serial_no).strip()
|
||||
notify_url = str(wechat_config.notify_url).strip()
|
||||
@@ -694,12 +704,23 @@ class OrderViewSet(viewsets.ModelViewSet):
|
||||
order.wechat_user = user
|
||||
order.save()
|
||||
|
||||
wechat_config = WeChatPayConfig.objects.filter(is_active=True).first()
|
||||
# 小程序 AppID
|
||||
miniprogram_appid = 'wxdf2ca73e6c0929f0'
|
||||
|
||||
# 尝试查找特定配置
|
||||
wechat_config = WeChatPayConfig.objects.filter(app_id=miniprogram_appid).first()
|
||||
if not wechat_config:
|
||||
wechat_config = WeChatPayConfig.objects.filter(is_active=True).first()
|
||||
|
||||
if not wechat_config:
|
||||
return Response({'error': '支付系统维护中'}, status=status.HTTP_503_SERVICE_UNAVAILABLE)
|
||||
|
||||
# 初始化支付客户端
|
||||
wxpay, error_msg = get_wechat_pay_client(pay_type=WeChatPayType.JSAPI)
|
||||
# 初始化支付客户端，强制使用小程序 AppID
|
||||
wxpay, error_msg = get_wechat_pay_client(
|
||||
pay_type=WeChatPayType.JSAPI,
|
||||
appid=miniprogram_appid,
|
||||
config=wechat_config
|
||||
)
|
||||
if not wxpay:
|
||||
return Response({'error': error_msg}, status=500)
|
||||
|
||||
@@ -746,7 +767,7 @@ class OrderViewSet(viewsets.ModelViewSet):
|
||||
# 再次签名 (小程序端需要的签名)
|
||||
# 注意：WeChatPayV3 SDK 可能没有直接提供生成小程序签名的 helper，需手动计算
|
||||
# 签名串格式：appId\ntimeStamp\nnonceStr\npackage\n
|
||||
message_build = f"{wechat_config.app_id}\n{timestamp}\n{nonce_str}\n{package}\n"
|
||||
message_build = f"{miniprogram_appid}\n{timestamp}\n{nonce_str}\n{package}\n"
|
||||
|
||||
# 使用商户私钥签名
|
||||
# 注意：WeChatPayV3 对象的私钥属性名可能随版本变化，或者被封装
|
||||
|
||||
Reference in New Issue
Block a user