Scoring-System/README.md

# 创赢未来报名评分系统

> 一个专注于创新创业竞赛报名、作品提交与智能评分的全栈应用平台。

![Project Logo](frontend/public/logo.png)

## 📖 项目简介

创赢未来报名评分系统是一个基于现代技术栈构建的创新创业竞赛管理平台，为赛事主办方、参赛选手和评委提供从报名、作品提交到智能评分的全流程解决方案。项目采用前后端分离架构，包含 Django 后端 API、React Web 管理端以及 Taro 微信小程序客户端。

## ✨ 功能特性

### 📝 赛事报名系统
- **比赛管理**：多状态流程（草稿→发布→报名→提交→评审→结束）、时间管理、可见性控制
- **在线报名**：自定义报名表单、报名信息收集、报名审核机制
- **作品提交**：文件附件支持（PPT/PDF/图片/视频）、项目封面展示、状态管理
- **轮播展示**：首页轮播图管理、活动推广、视觉展示

### 🏆 竞赛评审系统
- **评委管理**：评委身份认证、身份标签管理、权限分配
- **评分系统**：多维度评分、权重配置、评委评语、防重复评分机制
- **AI 智能评估**：多模型支持（通义千问系列）、模板化评估、0-100分制评分、详细评语生成
- **成绩统计**：自动排名、分数汇总、结果导出

### 👤 用户身份管理
- **身份标签**：自定义身份标签（如：选手、评委、嘉宾、管理员）
- **用户身份**：灵活的身份分配机制、多身份支持
- **权限控制**：基于身份的访问控制、操作权限验证

### 💬 社区互动
- **赛事中心**：赛事列表展示、赛事详情、报名入口
- **活动管理**：线上线下活动、报名表单自定义、支付状态同步
- **论坛帖子**：技术讨论、求助问答、经验分享、官方公告四大分类
- **互动功能**：点赞、置顶、嵌套回复（楼中楼）

### 🤖 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)
- **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
- **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

## 🚀 本地开发环境搭建

### 1. 系统要求
- **Node.js**: >= 18.0.0
- **Python**: >= 3.10
- **PostgreSQL**: >= 13
- **WeChat DevTools**: 最新版 (用于小程序开发)

### 2. 克隆仓库
```bash
git clone https://gitea.tangledup-ai.com/quant-speed-AI/Scoring-System.git
cd Scoring-System
```

### 3. 后端环境配置 (Backend)
```bash
cd backend

# 创建虚拟环境 (推荐)
python -m venv venv
# macOS/Linux 激活
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 数据库迁移
python manage.py migrate

# 创建超级用户
python manage.py createsuperuser

# 启动开发服务器 (默认端口 8000)
python manage.py runserver
```

后台管理地址：`http://localhost:8000/admin/`

### 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
```

## 🔌 API 接口示例

后端提供 RESTful API，以下为核心接口示例：

| 方法 | 路径 | 描述 |
| --- | --- | --- |
| POST | `/api/shop/wechat/login/` | 微信用户登录 (换取 JWT) |
| GET | `/api/competition/competitions/` | 获取赛事列表 |
| POST | `/api/competition/competitions/{id}/register/` | 报名参赛 |
| GET | `/api/competition/projects/` | 获取参赛项目列表 |
| POST | `/api/competition/projects/` | 提交参赛项目 |
| 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 文档。

## 📂 目录结构说明

```
Scoring-System/
├── backend/                # Django 后端源码
│   ├── ai_services/        # AI服务模块 (语音转写、AI评估)
│   │   ├── models.py       # 转写任务、AI评估模板模型
│   │   ├── views.py        # API接口 (转写、评估、总结)
│   │   └── services.py     # 阿里云听悟、通义千问服务集成
│   ├── community/          # 论坛社区模块
│   │   ├── models.py       # 活动、帖子、回复、公告模型
│   │   └── views.py        # 社区API接口
│   ├── competition/        # 竞赛评审模块
│   │   ├── models.py       # 比赛、项目、评分、维度模型
│   │   ├── views.py        # 竞赛API接口
│   │   ├── judge_views.py  # 评委系统接口
│   │   └── admin.py        # 后台管理配置
│   ├── shop/               # 用户与身份模块
│   │   ├── models.py       # 用户、身份标签模型
│   │   ├── admin.py        # 后台管理 (身份标签、用户身份)
│   │   └── services.py     # 微信服务
│   ├── config/             # 项目核心配置
│   │   ├── settings.py     # Django配置 (含Unfold后台配置)
│   │   └── urls.py         # 主路由配置
│   ├── uploads/            # 用户上传文件 (媒体资源)
│   ├── manage.py           # Django 管理脚本
│   ├── requirements.txt    # Python 依赖
│   └── Dockerfile          # 后端容器配置
├── frontend/               # React Web 端源码
│   ├── src/
│   │   ├── components/     # 公共组件
│   │   ├── pages/          # 页面路由
│   │   │   ├── Home.jsx           # 首页 (轮播图、赛事展示)
│   │   │   └── competitions/      # 赛事中心
│   │   └── assets/         # 静态资源
│   ├── public/             # 公共资源 (logo、首页图片)
│   └── vite.config.js      # Vite 配置
├── miniprogram/            # Taro 小程序源码
│   ├── src/
│   │   ├── pages/          # 小程序页面
│   │   ├── 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！请遵循以下规范：

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: AI语音转写任务状态一直显示"处理中"？**
  - A: 检查阿里云听悟服务配置是否正确，包括AccessKey、AppKey等参数。可通过`python manage.py check_aliyun_config`命令验证配置。

- **Q: AI评估功能无法正常使用？**
  - A: 确保通义千问API密钥已正确配置，检查模型调用配额是否充足。

- **Q: 竞赛项目无法提交？**
  - A: 确认比赛状态为"作品提交中"，检查是否已报名该比赛，确保每人每比赛只能提交一个项目。

- **Q: 评委无法看到评分入口？**
  - A: 检查用户是否被正确分配了"评委"身份标签，确认比赛状态为"评审中"。

## 📜 许可证

本项目采用 [MIT License](LICENSE) 许可证。

## 📧 联系方式

- **项目仓库**: https://gitea.tangledup-ai.com/quant-speed-AI/Scoring-System
- **系统名称**: 创赢未来报名评分系统