mirror of
https://github.com/GSManagerXZ/GameServerManager.git
synced 2025-10-04 22:02:03 +08:00
156 lines
4 KiB
Markdown
156 lines
4 KiB
Markdown
# 新手引导功能实现说明
|
||
|
||
## 功能概述
|
||
|
||
根据开发说明要求，实现了一个完整的新手引导系统，包含两个主要步骤：
|
||
|
||
1. **SteamCMD 设置** - 检测平台并配置 SteamCMD（可跳过）
|
||
2. **游戏默认安装路径** - 设置游戏服务器的默认安装路径（不可跳过）
|
||
|
||
## 触发条件
|
||
|
||
- 用户首次登录时自动触发
|
||
- 检测条件：用户没有 `lastLogin` 记录，或者是 5 分钟内新创建的用户
|
||
- 可以在设置页面手动重新启动引导
|
||
|
||
## 技术实现
|
||
|
||
### 前端组件
|
||
|
||
1. **OnboardingWizard.tsx** - 主引导界面组件
|
||
- 进度指示器
|
||
- 步骤导航
|
||
- 统一的操作界面
|
||
|
||
2. **引导步骤组件**
|
||
- `SteamCMDOnboardingStep.tsx` - SteamCMD 检测和设置
|
||
- `GamePathOnboardingStep.tsx` - 游戏路径设置
|
||
|
||
3. **状态管理**
|
||
- `onboardingStore.ts` - 使用 Zustand 管理引导状态
|
||
- 持久化存储引导进度和完成状态
|
||
|
||
### 后端 API
|
||
|
||
1. **设置路由** (`/api/settings`)
|
||
- `POST /game-path` - 保存游戏默认安装路径
|
||
- `GET /game-path` - 获取游戏默认安装路径
|
||
|
||
2. **配置管理器扩展**
|
||
- 在 `ConfigManager` 中添加游戏配置支持
|
||
- 支持游戏默认安装路径的存储和管理
|
||
|
||
### 集成点
|
||
|
||
1. **认证流程集成**
|
||
- 在用户登录成功后检测是否首次登录
|
||
- 自动启动新手引导流程
|
||
|
||
2. **应用界面集成**
|
||
- 在 `App.tsx` 中集成引导组件
|
||
- 只在已登录用户中显示引导
|
||
|
||
3. **设置页面集成**
|
||
- 添加游戏默认安装路径设置
|
||
- 提供重新启动引导的功能
|
||
|
||
## 功能特性
|
||
|
||
### SteamCMD 步骤
|
||
- 自动检测操作系统平台
|
||
- 支持在线安装和手动路径设置两种模式
|
||
- 实时显示安装进度
|
||
- 复用现有的 SteamCMD 管理功能
|
||
|
||
### 游戏路径设置
|
||
- 根据平台提供默认路径建议
|
||
- 路径格式验证
|
||
- 路径示例和注意事项
|
||
- 同时保存到服务器和本地存储
|
||
|
||
## 用户体验
|
||
|
||
1. **渐进式引导**
|
||
- 每个步骤都有详细说明和功能介绍
|
||
- 清晰的进度指示器
|
||
- 可以前进、后退和跳过（部分步骤）
|
||
|
||
2. **智能检测**
|
||
- 自动检测已安装的组件
|
||
- 显示当前状态和配置信息
|
||
- 避免重复配置
|
||
|
||
3. **灵活操作**
|
||
- 支持跳过可选步骤
|
||
- 可以随时关闭引导
|
||
- 在设置中可重新启动
|
||
|
||
## 数据持久化
|
||
|
||
1. **引导状态**
|
||
- 使用 Zustand persist 中间件
|
||
- 存储在 localStorage 中
|
||
- 包含步骤完成状态和当前进度
|
||
|
||
2. **配置数据**
|
||
- 游戏路径保存到服务器配置文件
|
||
- 同时备份到本地存储
|
||
- 与现有设置系统集成
|
||
|
||
## 扩展性
|
||
|
||
1. **步骤扩展**
|
||
- 可以轻松添加新的引导步骤
|
||
- 步骤组件独立，便于维护
|
||
- 支持自定义跳过逻辑
|
||
|
||
2. **配置扩展**
|
||
- 配置管理器支持新的配置项
|
||
- API 路由可以扩展更多设置功能
|
||
- 前端组件可复用于其他设置场景
|
||
|
||
## 测试和调试
|
||
|
||
1. **手动测试**
|
||
- 在设置页面点击"重新启动新手引导"
|
||
- 清除浏览器存储模拟首次登录
|
||
- 创建新用户账户测试
|
||
|
||
2. **状态检查**
|
||
- 浏览器开发者工具查看 localStorage
|
||
- 网络面板检查 API 调用
|
||
- 控制台查看日志信息
|
||
|
||
## 注意事项
|
||
|
||
1. **兼容性**
|
||
- 确保在不同浏览器中正常工作
|
||
- 响应式设计适配移动设备
|
||
- 深色/浅色主题支持
|
||
|
||
2. **错误处理**
|
||
- API 调用失败时的降级处理
|
||
- 网络错误时的用户提示
|
||
- 配置保存失败的备用方案
|
||
|
||
3. **性能优化**
|
||
- 延迟加载引导组件
|
||
- 避免阻塞主界面渲染
|
||
- 合理的状态更新频率
|
||
|
||
## 后续优化建议
|
||
|
||
1. **增强功能**
|
||
- 添加引导完成后的欢迎页面
|
||
- 支持引导步骤的自定义顺序
|
||
- 添加引导进度的统计分析
|
||
|
||
2. **用户体验**
|
||
- 添加动画效果和过渡
|
||
- 支持键盘导航
|
||
- 提供引导视频或图片说明
|
||
|
||
3. **管理功能**
|
||
- 管理员可以自定义引导内容
|
||
- 支持多语言引导界面
|
||
- 引导数据的导入导出功能
|