From f655aa0ede8b3f5486f2fdd555dce4e1d5763627 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=88=BD=E5=93=92=E5=93=92?= Date: Wed, 18 Mar 2026 22:44:32 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README.md=20?= =?UTF-8?q?=E4=B8=BA=E5=88=9B=E8=B5=A2=E6=9C=AA=E6=9D=A5=E6=8A=A5=E5=90=8D?= =?UTF-8?q?=E8=AF=84=E5=88=86=E7=B3=BB=E7=BB=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 189 ++++++++++++++++++++++++------------------------------ 1 file changed, 85 insertions(+), 104 deletions(-) diff --git a/README.md b/README.md index 6a61c38..00f53a3 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,58 @@ -# Quant Speed Market (量迹市场) +# 创赢未来报名评分系统 -> 一个集成了电商、社区论坛、AI 服务与 AR/3D 模型展示的全栈应用平台。 +> 一个专注于创新创业竞赛报名、作品提交与智能评分的全栈应用平台。 -![Project Logo](frontend/public/liangji_logo.svg) +![Project Logo](frontend/public/logo.png) ## 📖 项目简介 -npm run dev:weapp -Quant Speed Market 是一个基于现代技术栈构建的综合性平台，旨在为用户提供从商品购买、技术交流到 AI 工具使用的全方位体验。项目采用前后端分离架构，包含 Django 后端 API、React Web 管理端以及 Taro 微信小程序客户端。 + +创赢未来报名评分系统是一个基于现代技术栈构建的创新创业竞赛管理平台，为赛事主办方、参赛选手和评委提供从报名、作品提交到智能评分的全流程解决方案。项目采用前后端分离架构，包含 Django 后端 API、React Web 管理端以及 Taro 微信小程序客户端。 ## ✨ 功能特性 -### 🛍️ 电商商城系统 -- **商品管理**：ESP32硬件配置、库存管理、3D模型展示、产品特性标签 -- **订单管理**：多类型订单（硬件/课程/活动）、完整状态流转、物流跟踪 -- **支付系统**：微信支付V3集成、多种支付方式、安全签名验证、支付回调处理 -- **分销系统**：二级分销体系、邀请机制、佣金计算（一级10%/二级2%）、提现管理 -- **课程系统**：视频课程、固定时间课程、讲师管理、课程报名与咨询 - -### 💬 社区论坛系统 -- **活动管理**：线上线下活动、报名表单自定义、支付状态同步、审核机制 -- **论坛帖子**：技术讨论、求助问答、经验分享、官方公告四大分类 -- **互动功能**：点赞、置顶、嵌套回复（楼中楼）、多媒体附件支持 -- **公告系统**：时效控制、跳转链接、优先级排序、置顶功能 - -### 🤖 AI 服务系统 -- **语音转写**：阿里云听悟集成、多格式音频支持、说话人分离、状态自动刷新 -- **AI智能评估**：多模型支持（通义千问系列）、模板化评估、0-100分制评分、详细评语生成 -- **智能总结**：多类型总结（段落/对话/问答/思维导图）、Markdown格式输出、异步生成机制 -- **比赛集成**：AI评委身份、评分维度映射、自动评分同步、人工干预支持 +### 📝 赛事报名系统 +- **比赛管理**：多状态流程（草稿→发布→报名→提交→评审→结束）、时间管理、可见性控制 +- **在线报名**：自定义报名表单、报名信息收集、报名审核机制 +- **作品提交**：文件附件支持（PPT/PDF/图片/视频）、项目封面展示、状态管理 +- **轮播展示**：首页轮播图管理、活动推广、视觉展示 ### 🏆 竞赛评审系统 -- **比赛管理**：多状态流程（草稿→发布→报名→提交→评审→结束）、时间管理、可见性控制 -- **项目管理**：文件附件支持（PPT/PDF/图片/视频）、封面展示、状态管理 +- **评委管理**：评委身份认证、身份标签管理、权限分配 - **评分系统**：多维度评分、权重配置、评委评语、防重复评分机制 -- **权限控制**：选手/评委/嘉宾三角色体系、报名审核、角色权限管理 +- **AI 智能评估**：多模型支持（通义千问系列）、模板化评估、0-100分制评分、详细评语生成 +- **成绩统计**：自动排名、分数汇总、结果导出 -### 🕶️ AR/3D 展示 -- **3D模型预览**：基于Three.js的交互式3D模型展示 -- **AR交互体验**：增强现实功能集成 -- **多媒体支持**：图片、视频、文件等多格式媒体处理 +### 👤 用户身份管理 +- **身份标签**：自定义身份标签（如：选手、评委、嘉宾、管理员） +- **用户身份**：灵活的身份分配机制、多身份支持 +- **权限控制**：基于身份的访问控制、操作权限验证 -### 📱 多端适配 -- **微信小程序**：Taro框架开发、原生小程序体验、分包优化 -- **Web管理端**：React + Ant Design、响应式设计、管理后台功能 -- **跨平台支持**：可扩展至H5、支付宝小程序等平台 +### 💬 社区互动 +- **赛事中心**：赛事列表展示、赛事详情、报名入口 +- **活动管理**：线上线下活动、报名表单自定义、支付状态同步 +- **论坛帖子**：技术讨论、求助问答、经验分享、官方公告四大分类 +- **互动功能**：点赞、置顶、嵌套回复（楼中楼） + +### 🤖 AI 服务 +- **语音转写**：阿里云听悟集成、多格式音频支持、说话人分离、状态自动刷新 +- **智能总结**：多类型总结（段落/对话/问答/思维导图）、Markdown格式输出 ### 🔒 安全认证 - **微信登录**：小程序code换取session、OpenID/UnionID管理 - **手机验证**：验证码登录、手机号绑定、用户合并机制 - **JWT认证**：Token-based身份验证、API访问控制 -- **权限验证**：基于角色的访问控制、操作权限验证 + +### 📱 多端适配 +- **微信小程序**：Taro框架开发、原生小程序体验、分包优化 +- **Web管理端**：React + Ant Design、响应式设计、管理后台功能 +- **后台管理**：Django Unfold 美化后台、身份标签管理、赛事管理 ## 🛠️ 技术栈与依赖 ### Backend (后端) - **Framework**: Django 6.0 + Django REST Framework 3.16 +- **Admin UI**: Django Unfold (现代化后台管理界面) - **Database**: PostgreSQL (psycopg2) -- **Payment**: WeChat Pay V3 (wechatpayv3) - **AI Services**: 阿里云听悟 (语音转写)、通义千问 (AI评估) - **Cloud Storage**: 阿里云OSS (文件存储) - **Documentation**: drf-spectacular (OpenAPI 3.0) @@ -66,14 +62,14 @@ Quant Speed Market 是一个基于现代技术栈构建的综合性平台，旨 ### Frontend (Web 端) - **Core**: React 19 + Vite 7 - **UI Library**: Ant Design 6 -- **3D Engine**: Three.js + @react-three/fiber - **Routing**: React Router v7 +- **Styling**: CSS-in-JS + Tailwind CSS ### Miniprogram (小程序) - **Framework**: Taro 3.6 (React Flavor) - **UI Library**: Taro UI - **Styles**: SCSS -- **Platform**: WeChat Mini Program (可扩展至 H5/Alipay 等) +- **Platform**: WeChat Mini Program ## 🚀 本地开发环境搭建 @@ -85,8 +81,8 @@ Quant Speed Market 是一个基于现代技术栈构建的综合性平台，旨 ### 2. 克隆仓库 ```bash -git clone -cd market_page +git clone https://gitea.tangledup-ai.com/quant-speed-AI/Scoring-System.git +cd Scoring-System ``` ### 3. 后端环境配置 (Backend) @@ -95,8 +91,6 @@ cd backend # 创建虚拟环境 (推荐) python -m venv venv -# Windows 激活 -venv\Scripts\activate # macOS/Linux 激活 source venv/bin/activate @@ -113,6 +107,8 @@ python manage.py createsuperuser python manage.py runserver ``` +后台管理地址：`http://localhost:8000/admin/` + ### 4. Web 前端配置 (Frontend) ```bash cd ../frontend @@ -162,34 +158,6 @@ npm run preview 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，以下为核心接口示例： @@ -197,22 +165,21 @@ docker-compose up -d --build | 方法 | 路径 | 描述 | | --- | --- | --- | | 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}/` | 获取转写任务状态 | +| GET | `/api/competition/competitions/` | 获取赛事列表 | +| POST | `/api/competition/competitions/{id}/register/` | 报名参赛 | +| GET | `/api/competition/projects/` | 获取参赛项目列表 | | POST | `/api/competition/projects/` | 提交参赛项目 | -| GET | `/api/competition/projects/{id}/score/` | 获取项目评分 | | POST | `/api/competition/scoring/` | 评委提交评分 | +| GET | `/api/competition/projects/{id}/score/` | 获取项目评分 | +| POST | `/api/ai/transcription/` | 创建语音转写任务 | +| POST | `/api/ai/evaluations/` | 创建 AI 评估 | **API 文档**: 启动后端后访问 `http://localhost:8000/api/schema/swagger-ui/` 查看完整 Swagger 文档。 ## 📂 目录结构说明 ``` -market_page/ +Scoring-System/ ├── backend/ # Django 后端源码 │ ├── ai_services/ # AI服务模块 (语音转写、AI评估) │ │ ├── models.py # 转写任务、AI评估模板模型 @@ -220,18 +187,18 @@ market_page/ │ │ └── services.py # 阿里云听悟、通义千问服务集成 │ ├── community/ # 论坛社区模块 │ │ ├── models.py # 活动、帖子、回复、公告模型 -│ │ ├── views.py # 社区API接口 -│ │ └── admin_actions.py # 后台管理动作 +│ │ └── views.py # 社区API接口 │ ├── competition/ # 竞赛评审模块 │ │ ├── models.py # 比赛、项目、评分、维度模型 +│ │ ├── views.py # 竞赛API接口 │ │ ├── judge_views.py # 评委系统接口 -│ │ └── templates/ # 评委系统前端页面 -│ ├── shop/ # 电商与支付模块 -│ │ ├── models.py # 商品、订单、支付、用户模型 -│ │ ├── services.py # 微信支付、短信服务 -│ │ └── admin_actions.py # 订单管理动作 +│ │ └── admin.py # 后台管理配置 +│ ├── shop/ # 用户与身份模块 +│ │ ├── models.py # 用户、身份标签模型 +│ │ ├── admin.py # 后台管理 (身份标签、用户身份) +│ │ └── services.py # 微信服务 │ ├── config/ # 项目核心配置 -│ │ ├── settings.py # Django配置 +│ │ ├── settings.py # Django配置 (含Unfold后台配置) │ │ └── urls.py # 主路由配置 │ ├── uploads/ # 用户上传文件 (媒体资源) │ ├── manage.py # Django 管理脚本 @@ -239,23 +206,41 @@ market_page/ │ └── Dockerfile # 后端容器配置 ├── frontend/ # React Web 端源码 │ ├── src/ -│ │ ├── components/ # 公共组件 (3D模型、弹窗等) -│ │ ├── pages/ # 页面路由 (Home, Forum, Payment) -│ │ ├── hooks/ # 自定义React Hooks +│ │ ├── components/ # 公共组件 +│ │ ├── pages/ # 页面路由 +│ │ │ ├── Home.jsx # 首页 (轮播图、赛事展示) +│ │ │ └── competitions/ # 赛事中心 │ │ └── assets/ # 静态资源 -│ ├── public/ # 公共资源 +│ ├── public/ # 公共资源 (logo、首页图片) │ └── vite.config.js # Vite 配置 ├── miniprogram/ # Taro 小程序源码 │ ├── src/ │ │ ├── pages/ # 小程序页面 -│ │ ├── subpackages/ # 分包页面 (分销、论坛详情等) -│ │ ├── components/ # 小程序组件 +│ │ ├── subpackages/ # 分包页面 │ │ └── utils/ # 工具函数 │ └── project.config.json # 微信小程序配置 ├── docker-compose.yml # Docker 编排文件 └── README.md # 项目文档 ``` +## 🎯 核心模块说明 + +### 身份标签系统 +- **IdentityTag**: 可配置的身份标签，支持自定义名称和颜色 +- **UserIdentity**: 用户与标签的关联，支持多对多关系 +- **后台管理**: 在 Django Admin 中管理标签和用户身份分配 + +### 赛事管理系统 +- **Competition**: 赛事信息、时间安排、状态管理 +- **Project**: 参赛项目、作品提交、附件管理 +- **Score**: 评分记录、多维度评分、评语 +- **Carousel**: 首页轮播图管理 + +### AI 评估系统 +- **AIEvaluationTemplate**: 评估模板、评分维度配置 +- **AIEvaluation**: AI 评估结果、分数、评语 +- **TranscriptionTask**: 语音转写任务管理 + ## 🤝 贡献规范 欢迎提交 Pull Request！请遵循以下规范： @@ -267,8 +252,8 @@ market_page/ - `fix/xxx`: Bug 修复分支。 2. **Commit 格式**： - - `feat: 添加购物车功能` - - `fix: 修复支付回调失败问题` + - `feat: 添加赛事报名功能` + - `fix: 修复评分计算错误` - `docs: 更新 README` - `style: 调整首页样式` @@ -286,27 +271,23 @@ market_page/ - **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: 检查产品是否设置了独立分润比例，确认分销员状态为"正常"，查看佣金日志了解具体计算过程。 + - A: 确保通义千问API密钥已正确配置，检查模型调用配额是否充足。 - **Q: 竞赛项目无法提交？** - A: 确认比赛状态为"作品提交中"，检查是否已报名该比赛，确保每人每比赛只能提交一个项目。 +- **Q: 评委无法看到评分入口？** + - A: 检查用户是否被正确分配了"评委"身份标签，确认比赛状态为"评审中"。 + ## 📜 许可证 本项目采用 [MIT License](LICENSE) 许可证。 ## 📧 联系方式 -- **作者**: (Your Name/Organization) -- **邮箱**: contact@example.com -- **项目主页**: https://github.com/yourusername/market-page +- **项目仓库**: https://gitea.tangledup-ai.com/quant-speed-AI/Scoring-System +- **系统名称**: 创赢未来报名评分系统