GameServerManager/docs/新手引导功能说明.md

新手引导功能实现说明

功能概述

根据开发说明要求，实现了一个完整的新手引导系统，包含两个主要步骤：

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. 管理功能

   • 管理员可以自定义引导内容
   • 支持多语言引导界面
   • 引导数据的导入导出功能