193 lines
4.6 KiB
Markdown
193 lines
4.6 KiB
Markdown
|
# 宝箱竞猜系统 - 前端
|
|||
|
|
|
|||
|
|
基于 React + TypeScript + Vite 构建的现代化前端界面。
|
|||
|
|
|
|||
|
|
## 功能特性
|
|||
|
|
|
|||
|
|
- 🎨 现代化UI设计，支持深色主题
|
|||
|
|
- 📱 完全响应式布局，支持移动端
|
|||
|
|
- 🔐 完整的用户认证和权限管理
|
|||
|
|
- 🎮 主播控制台 - 创建和管理宝箱
|
|||
|
|
- 💰 用户中心 - 查看余额和交易记录
|
|||
|
|
- 🔴 实时WebSocket更新奖池信息
|
|||
|
|
- 🏆 富豪榜展示
|
|||
|
|
|
|||
|
|
## 技术栈
|
|||
|
|
|
|||
|
|
- **框架**: React 18 + TypeScript
|
|||
|
|
- **构建工具**: Vite
|
|||
|
|
- **路由**: React Router v6
|
|||
|
|
- **状态管理**: React Context
|
|||
|
|
- **HTTP客户端**: Axios
|
|||
|
|
- **WebSocket**: Socket.io Client
|
|||
|
|
- **样式**: CSS3 (使用CSS变量和现代特性)
|
|||
|
|
|
|||
|
|
## 项目结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
src/
|
|||
|
|
├── components/ # 公共组件
|
|||
|
|
│ ├── Header.tsx # 页面头部导航
|
|||
|
|
│ ├── Card.tsx # 卡片组件
|
|||
|
|
│ ├── ChestCard.tsx # 宝箱卡片
|
|||
|
|
│ ├── Loading.tsx # 加载组件
|
|||
|
|
│ └── ProtectedRoute.tsx # 路由权限控制
|
|||
|
|
├── pages/ # 页面组件
|
|||
|
|
│ ├── HomePage.tsx # 首页 - 宝箱列表
|
|||
|
|
│ ├── ChestPage.tsx # 宝箱详情页
|
|||
|
|
│ ├── LoginPage.tsx # 登录页
|
|||
|
|
│ ├── RegisterPage.tsx # 注册页
|
|||
|
|
│ ├── StreamerConsole.tsx # 主播控制台
|
|||
|
|
│ ├── UserProfile.tsx # 用户中心
|
|||
|
|
│ └── AdminPanel.tsx # 管理后台
|
|||
|
|
├── contexts/ # React Context
|
|||
|
|
│ └── AuthContext.tsx # 认证上下文
|
|||
|
|
├── services/ # 服务层
|
|||
|
|
│ ├── api.ts # API接口封装
|
|||
|
|
│ └── websocket.ts # WebSocket服务
|
|||
|
|
├── types/ # TypeScript类型定义
|
|||
|
|
│ └── index.ts
|
|||
|
|
├── App.tsx # 主应用组件
|
|||
|
|
├── main.tsx # 应用入口
|
|||
|
|
└── index.css # 全局样式
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 开发
|
|||
|
|
|
|||
|
|
### 安装依赖
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
npm install
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 启动开发服务器
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
npm run dev
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
服务将在 http://localhost:3000 启动
|
|||
|
|
|
|||
|
|
### 构建生产版本
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
npm run build
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 预览生产版本
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
npm run preview
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## API配置
|
|||
|
|
|
|||
|
|
前端通过环境变量配置API地址：
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
// src/services/api.ts
|
|||
|
|
const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || '';
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
如果需要修改API地址，请在 `.env` 文件中修改 `VITE_API_BASE_URL` 的值。
|
|||
|
|
|
|||
|
|
## 功能说明
|
|||
|
|
|
|||
|
|
### 用户角色
|
|||
|
|
|
|||
|
|
1. **普通用户 (user)**
|
|||
|
|
- 浏览活跃宝箱
|
|||
|
|
- 参与下注
|
|||
|
|
- 查看交易记录
|
|||
|
|
- 领取每日低保
|
|||
|
|
|
|||
|
|
2. **主播 (streamer)**
|
|||
|
|
- 拥有普通用户所有权限
|
|||
|
|
- 创建和管理宝箱
|
|||
|
|
- 封盘和结算操作
|
|||
|
|
- 获得5%分润
|
|||
|
|
|
|||
|
|
3. **管理员 (admin)**
|
|||
|
|
- 拥有所有权限
|
|||
|
|
- 管理用户
|
|||
|
|
- 调整用户余额
|
|||
|
|
|
|||
|
|
### 页面说明
|
|||
|
|
|
|||
|
|
- **首页** (`/`) - 展示所有活跃宝箱，支持实时更新
|
|||
|
|
- **宝箱详情** (`/chests/:id`) - 显示详细下注界面和赔率计算
|
|||
|
|
- **主播控制台** (`/streamer`) - 创建、封盘、结算宝箱
|
|||
|
|
- **用户中心** (`/profile`) - 查看个人信息、交易记录、富豪榜
|
|||
|
|
- **管理后台** (`/admin`) - 管理用户和调整余额
|
|||
|
|
|
|||
|
|
### WebSocket实时更新
|
|||
|
|
|
|||
|
|
系统通过WebSocket实现以下实时功能：
|
|||
|
|
- 奖池金额实时更新
|
|||
|
|
- 宝箱状态变更广播
|
|||
|
|
- 获胜通知推送
|
|||
|
|
|
|||
|
|
连接逻辑：
|
|||
|
|
```typescript
|
|||
|
|
// 根据用户角色连接不同频道
|
|||
|
|
const endpoint = userType === 'streamer' ? 'ws/streamer' : 'ws/user';
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 样式系统
|
|||
|
|
|
|||
|
|
使用CSS变量实现主题系统：
|
|||
|
|
|
|||
|
|
```css
|
|||
|
|
:root {
|
|||
|
|
--primary-color: #6366f1;
|
|||
|
|
--bg-color: #0f172a;
|
|||
|
|
--text-primary: #f1f5f9;
|
|||
|
|
/* ...更多变量 */
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
响应式断点：
|
|||
|
|
- 桌面端：> 768px
|
|||
|
|
- 移动端：≤ 768px
|
|||
|
|
|
|||
|
|
## 开发注意事项
|
|||
|
|
|
|||
|
|
1. **认证状态管理**
|
|||
|
|
- 使用AuthContext统一管理用户认证状态
|
|||
|
|
- 自动处理token刷新和失效
|
|||
|
|
|
|||
|
|
2. **路由权限**
|
|||
|
|
- 使用ProtectedRoute组件保护需要登录的页面
|
|||
|
|
- 根据用户角色控制页面访问
|
|||
|
|
|
|||
|
|
3. **错误处理**
|
|||
|
|
- 所有API请求都有错误处理机制
|
|||
|
|
- 401错误自动跳转到登录页
|
|||
|
|
|
|||
|
|
4. **性能优化**
|
|||
|
|
- 使用React.memo优化组件渲染
|
|||
|
|
- 合理使用useEffect依赖数组
|
|||
|
|
|
|||
|
|
## 常见问题
|
|||
|
|
|
|||
|
|
### Q: 前端无法连接后端API
|
|||
|
|
A: 检查后端服务是否在正确的地址启动，并确保CORS配置正确。默认情况下后端服务在 http://localhost:8000 启动。
|
|||
|
|
|
|||
|
|
### Q: WebSocket连接失败
|
|||
|
|
A: 检查后端WebSocket服务是否启动，以及token是否有效。
|
|||
|
|
|
|||
|
|
### Q: 样式显示异常
|
|||
|
|
A: 确保CSS文件正确加载，检查是否有CSS冲突。
|
|||
|
|
|
|||
|
|
## 贡献指南
|
|||
|
|
|
|||
|
|
1. 遵循现有的代码风格和项目结构
|
|||
|
|
2. 使用TypeScript进行类型检查
|
|||
|
|
3. 确保响应式设计兼容性
|
|||
|
|
4. 添加适当的错误处理
|
|||
|
|
5. 保持组件的单一职责原则
|
|||
|
|
|
|||
|
|
## 许可证
|
|||
|
|
|
|||
|
|
MIT License
|