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
|