mxivideo/docs/LOGIN_SYSTEM_GUIDE.md

MixVideo 登录系统设计文档

🎨 设计概述

本文档描述了为MixVideo项目设计的美观大气、科技风格的登录页面，集成了Nakama用户系统。

🎯 设计目标

1. 美观大气: 现代化的UI设计，符合科技产品的视觉标准
2. 科技风格: 与MixVideo项目主题契合的设计语言
3. 用户体验: 流畅的交互体验和清晰的信息架构
4. 系统集成: 完整的Nakama用户系统集成

🏗️ 架构设计

技术栈

• 前端框架: React + TypeScript
• 状态管理: Zustand
• 样式系统: Tailwind CSS
• 用户系统: Nakama
• 路由管理: React Router
• 图标库: Lucide React

核心组件

1. 认证服务 (nakamaAuth.ts)

// 核心功能
- 用户登录/注册
- 会话管理
- 自动刷新token
- 用户资料管理
- 密码修改

2. 状态管理 (useAuthStore.ts)

// 状态管理
- 认证状态
- 用户信息
- 加载状态
- 错误处理

3. 登录页面 (LoginPage.tsx)

// 页面功能
- 登录表单
- 注册表单
- 密码可见性切换
- 表单验证
- 错误提示

4. 路由保护 (ProtectedRoute.tsx)

// 路由保护
- 认证检查
- 自动重定向
- 加载状态

5. 用户菜单 (UserMenu.tsx)

// 用户界面
- 用户头像
- 下拉菜单
- 快速操作
- 登出功能

🎨 视觉设计

设计理念

• 科技感: 使用渐变背景、毛玻璃效果、动画元素
• 专业性: 简洁的布局、清晰的层次结构
• 现代化: 圆角设计、阴影效果、微交互

色彩方案

/* 主色调 */
primary: #2563eb (蓝色)
secondary: #64748b (灰色)

/* 渐变色 */
background: from-secondary-900 via-secondary-800 to-primary-900
button: from-primary-500 to-blue-500

/* 透明度 */
glass: rgba(255, 255, 255, 0.1)
border: rgba(255, 255, 255, 0.2)

动画效果

• 背景动画: 脉冲光球效果
• 按钮动画: 悬停提升、光泽扫过
• 表单动画: 焦点状态过渡
• 加载动画: 旋转加载器

🔧 功能特性

登录功能

• 邮箱登录
• 用户名登录
• 密码可见性切换
• 记住我选项
• 错误提示
• 加载状态

注册功能

• 邮箱注册
• 用户名设置
• 显示名称
• 密码确认
• 表单验证
• 实时错误提示

用户管理

• 用户资料显示
• 头像管理
• 在线状态
• 快速操作菜单
• 安全登出

路由保护

• 认证检查
• 自动重定向
• 会话恢复
• 加载状态

📱 响应式设计

桌面端 (1024px+)

• 左右分栏布局
• 品牌展示区域
• 完整功能展示

平板端 (768px-1023px)

• 居中单栏布局
• 简化品牌信息
• 保持核心功能

移动端 (< 768px)

• 全屏登录表单
• 最小化装饰元素
• 优化触摸交互

🔐 安全特性

密码安全

• 密码可见性切换
• 客户端验证
• 安全传输

会话管理

• 自动token刷新
• 安全存储
• 过期处理

错误处理

• 友好错误提示
• 详细日志记录
• 优雅降级

🚀 部署配置

Nakama服务器配置

// 配置参数
SERVER_KEY: 'your-server-key'
HOST: 'your-nakama-host'
PORT: '7350'
USE_SSL: true // 生产环境建议启用

环境变量

VITE_NAKAMA_SERVER_KEY=your-server-key
VITE_NAKAMA_HOST=your-nakama-host
VITE_NAKAMA_PORT=7350
VITE_NAKAMA_USE_SSL=true

📋 使用指南

1. 安装依赖

pnpm install @heroiclabs/nakama-js

2. 配置Nakama

// 更新 nakamaAuth.ts 中的配置
private readonly SERVER_KEY = 'your-server-key';
private readonly HOST = 'your-nakama-host';
private readonly PORT = '7350';
private readonly USE_SSL = true;

3. 启动应用

pnpm run tauri:dev

4. 访问登录页面

• 未登录用户自动重定向到 /login
• 已登录用户重定向到首页

🎯 用户体验流程

首次访问

1. 用户打开应用
2. 检查认证状态
3. 重定向到登录页面
4. 显示品牌信息和登录表单

登录流程

1. 用户输入邮箱/用户名和密码
2. 客户端验证表单
3. 发送登录请求到Nakama
4. 保存会话信息
5. 重定向到首页

注册流程

1. 用户点击"立即注册"
2. 填写注册表单
3. 验证密码一致性
4. 发送注册请求
5. 自动登录并重定向

会话管理

1. 自动检查token有效性
2. 过期前自动刷新
3. 失败时清除本地状态
4. 重定向到登录页面

🔍 故障排除

常见问题

1. Nakama连接失败

解决方案:
- 检查服务器地址和端口
- 确认服务器密钥正确
- 检查网络连接

2. 登录失败

解决方案:
- 验证用户名/邮箱格式
- 检查密码长度和复杂度
- 查看控制台错误信息

3. 会话过期

解决方案:
- 检查token刷新逻辑
- 确认本地存储权限
- 重新登录

📈 性能优化

代码分割

• 登录页面独立打包
• 按需加载认证组件
• 优化bundle大小

缓存策略

• 用户信息本地缓存
• 头像图片缓存
• 会话状态持久化

网络优化

• 请求去重
• 错误重试
• 超时处理

🎨 自定义主题

颜色定制

/* 修改 tailwind.config.js */
colors: {
  primary: {
    500: '#your-primary-color',
    600: '#your-primary-dark',
  }
}

动画定制

/* 修改 src/index.css */
.login-button:hover {
  transform: translateY(-2px);
  box-shadow: 0 15px 30px rgba(59, 130, 246, 0.4);
}

📚 API文档

认证API

// 登录
nakamaAuth.login(credentials: LoginCredentials): Promise<UserProfile>

// 注册
nakamaAuth.register(credentials: RegisterCredentials): Promise<UserProfile>

// 登出
nakamaAuth.logout(): Promise<void>

// 获取当前用户
nakamaAuth.getCurrentUser(): Promise<UserProfile | null>

// 更新资料
nakamaAuth.updateProfile(updates: Partial<UserProfile>): Promise<void>

状态管理API

// 使用认证状态
const { isAuthenticated, user, loading, error } = useAuthStore();

// 执行登录
const { login } = useAuthStore();
await login({ email, password });

// 执行登出
const { logout } = useAuthStore();
await logout();

🎉 总结

MixVideo登录系统提供了：

1. 美观的视觉设计: 科技风格的现代化界面
2. 完整的功能体系: 登录、注册、会话管理
3. 优秀的用户体验: 流畅的交互和清晰的反馈
4. 强大的技术架构: 模块化设计和类型安全
5. 灵活的扩展性: 易于定制和维护

这套登录系统不仅满足了当前的功能需求，还为未来的扩展提供了坚实的基础。