414 lines
9.7 KiB
Markdown
414 lines
9.7 KiB
Markdown
|
# GameGroup 前端项目文档
|
||
|
|
|
||
|
|
**项目名称**: GameGroup 前端系统
|
||
|
|
**项目版本**: v1.0
|
||
|
|
**文档更新**: 2026-01-28
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 📚 文档目录
|
||
|
|
|
||
|
|
本目录包含 GameGroup 前端项目的所有设计文档和技术文档。
|
||
|
|
|
||
|
|
### 📁 目录结构
|
||
|
|
|
||
|
|
```
|
||
|
|
doc/
|
||
|
|
├── README.md # 本文档 - 文档导航
|
||
|
|
├── api/ # API相关文档
|
||
|
|
│ └── API文档.md # 后端API接口文档
|
||
|
|
├── design/ # 设计文档
|
||
|
|
│ ├── 01-前端架构设计.md # 前端技术架构
|
||
|
|
│ ├── 02-UI-UX设计规范.md # 视觉设计规范
|
||
|
|
│ ├── 03-组件设计文档.md # 组件库设计
|
||
|
|
│ └── 04-页面设计文档.md # 页面设计
|
||
|
|
└── 后端相关文档/
|
||
|
|
├── 后端README.md # 后端项目说明
|
||
|
|
└── 后端项目分析报告.md # 后端代码分析
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🎯 项目概述
|
||
|
|
|
||
|
|
GameGroup 是一个游戏社群管理平台,为玩家提供小组管理、游戏预约、积分系统、竞猜等功能。前端项目采用现代化的技术栈,注重用户体验和性能优化。
|
||
|
|
|
||
|
|
### 核心功能模块
|
||
|
|
|
||
|
|
- **认证模块**: 用户注册、登录、令牌刷新
|
||
|
|
- **用户中心**: 个人资料管理、设置
|
||
|
|
- **小组管理**: 创建/加入小组、成员管理、权限控制
|
||
|
|
- **游戏库**: 游戏浏览、搜索、筛选
|
||
|
|
- **预约系统**: 创建预约、加入/退出预约、时间管理
|
||
|
|
- **账目管理**: 账目记录、统计分析
|
||
|
|
- **排班助手**: 空闲时间提交、共同时间查找
|
||
|
|
- **荣誉墙**: 荣誉展示、时间轴
|
||
|
|
- **资产管理**: 资产借用/归还、流转记录
|
||
|
|
- **积分系统**: 积分查询、排行榜
|
||
|
|
- **竞猜系统**: 创建竞猜、参与竞猜、结算
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🛠 技术栈
|
||
|
|
|
||
|
|
### 核心技术
|
||
|
|
|
||
|
|
| 技术 | 版本 | 说明 |
|
||
|
|
|------|------|------|
|
||
|
|
| Vue | 3.x | 渐进式JavaScript框架 |
|
||
|
|
| TypeScript | 5.x | JavaScript超集,提供类型安全 |
|
||
|
|
| Vite | 5.x | 下一代前端构建工具 |
|
||
|
|
| Vue Router | 4.x | Vue官方路由管理器 |
|
||
|
|
| Pinia | 2.x | Vue官方状态管理库 |
|
||
|
|
| Element Plus | 最新 | Vue 3 UI组件库 |
|
||
|
|
| Tailwind CSS | 3.x | 原子化CSS框架 |
|
||
|
|
| Axios | 1.x | HTTP客户端 |
|
||
|
|
| Vitest | 最新 | 单元测试框架 |
|
||
|
|
|
||
|
|
### 开发工具
|
||
|
|
|
||
|
|
- **包管理器**: pnpm / npm / yarn
|
||
|
|
- **代码规范**: ESLint + Prettier
|
||
|
|
- **Git Hooks**: Husky + lint-staged
|
||
|
|
- **提交规范**: Commitlint
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 📖 文档说明
|
||
|
|
|
||
|
|
### 1. 前端架构设计 ([01-前端架构设计.md](design/01-前端架构设计.md))
|
||
|
|
|
||
|
|
**内容概览**:
|
||
|
|
- 技术栈选型和理由
|
||
|
|
- 项目架构设计(分层架构、模块化)
|
||
|
|
- 目录结构规范
|
||
|
|
- 状态管理方案
|
||
|
|
- 路由设计
|
||
|
|
- API请求层封装
|
||
|
|
- 性能优化策略
|
||
|
|
- 开发工具链配置
|
||
|
|
- 测试方案
|
||
|
|
- 部署方案
|
||
|
|
|
||
|
|
**适合人群**: 技术负责人、架构师、开发者
|
||
|
|
|
||
|
|
**阅读时间**: 30分钟
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### 2. UI/UX设计规范 ([02-UI-UX设计规范.md](design/02-UI-UX设计规范.md))
|
||
|
|
|
||
|
|
**内容概览**:
|
||
|
|
- 设计理念和核心价值
|
||
|
|
- 视觉风格定位
|
||
|
|
- 色彩系统(主色调、功能色、游戏主题色)
|
||
|
|
- 字体系统(字体家族、大小、字重、行高)
|
||
|
|
- 间距系统
|
||
|
|
- 组件规范(按钮、卡片、输入框、徽章、头像等)
|
||
|
|
- 动效规范(动画时长、缓动函数、常用动效)
|
||
|
|
- 响应式设计(断点系统、响应式策略)
|
||
|
|
- 无障碍设计(键盘导航、屏幕阅读器)
|
||
|
|
- 设计资源和工具
|
||
|
|
|
||
|
|
**适合人群**: UI设计师、前端开发者
|
||
|
|
|
||
|
|
**阅读时间**: 45分钟
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### 3. 组件设计文档 ([03-组件设计文档.md](design/03-组件设计文档.md))
|
||
|
|
|
||
|
|
**内容概览**:
|
||
|
|
- 组件概述和分类
|
||
|
|
- 基础组件(按钮、输入框、弹窗、卡片、表格等)
|
||
|
|
- 业务组件(用户卡片、小组卡片、游戏卡片、预约卡片等)
|
||
|
|
- 布局组件(主布局、导航栏、侧边栏)
|
||
|
|
- 组件通信方式(Props/Emits、Provide/Inject、Event Bus)
|
||
|
|
- 组件性能优化(懒加载、缓存、虚拟滚动)
|
||
|
|
- 组件测试示例
|
||
|
|
|
||
|
|
**适合人群**: 前端开发者
|
||
|
|
|
||
|
|
**阅读时间**: 60分钟
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### 4. 页面设计文档 ([04-页面设计文档.md](design/04-页面设计文档.md))
|
||
|
|
|
||
|
|
**内容概览**:
|
||
|
|
- 页面架构和层级
|
||
|
|
- 认证页面(登录、注册)
|
||
|
|
- 首页布局和内容
|
||
|
|
- 用户中心(个人资料、设置)
|
||
|
|
- 小组管理(列表、详情、创建)
|
||
|
|
- 游戏库(列表、详情)
|
||
|
|
- 预约管理(列表、创建)
|
||
|
|
- 积分排行榜
|
||
|
|
- 荣誉墙
|
||
|
|
- 响应式适配
|
||
|
|
- 页面动效
|
||
|
|
|
||
|
|
**适合人群**: UI设计师、前端开发者、产品经理
|
||
|
|
|
||
|
|
**阅读时间**: 50分钟
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### 5. API接口文档 ([api/API文档.md](api/API文档.md))
|
||
|
|
|
||
|
|
**内容概览**:
|
||
|
|
- 完整的后端API接口文档
|
||
|
|
- 请求方法、参数、响应格式
|
||
|
|
- 认证说明
|
||
|
|
- 错误码对照表
|
||
|
|
- 13个模块的70+接口:
|
||
|
|
- 认证相关
|
||
|
|
- 用户管理
|
||
|
|
- 小组管理
|
||
|
|
- 游戏库
|
||
|
|
- 预约管理
|
||
|
|
- 账目管理
|
||
|
|
- 排班助手
|
||
|
|
- 黑名单管理
|
||
|
|
- 荣誉墙
|
||
|
|
- 资产管理
|
||
|
|
- 积分系统
|
||
|
|
- 竞猜系统
|
||
|
|
- 系统接口
|
||
|
|
|
||
|
|
**适合人群**: 前端开发者、后端开发者
|
||
|
|
|
||
|
|
**阅读时间**: 按需查阅
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### 6. 后端项目文档
|
||
|
|
|
||
|
|
#### 后端README ([后端README.md](后端README.md))
|
||
|
|
|
||
|
|
后端项目的总体介绍,包含:
|
||
|
|
- 技术栈(NestJS + TypeScript + MySQL)
|
||
|
|
- 项目结构
|
||
|
|
- 开发指南
|
||
|
|
- 部署说明
|
||
|
|
|
||
|
|
#### 后端项目分析报告 ([后端项目分析报告.md](后端项目分析报告.md))
|
||
|
|
|
||
|
|
后端代码的详细分析,包含:
|
||
|
|
- 项目概览和架构
|
||
|
|
- 项目优点
|
||
|
|
- 需要修复的问题
|
||
|
|
- 性能优化建议
|
||
|
|
|
||
|
|
**适合人群**: 前端开发者(了解后端实现)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🚀 快速开始
|
||
|
|
|
||
|
|
### 环境要求
|
||
|
|
|
||
|
|
- Node.js >= 18.0.0
|
||
|
|
- pnpm >= 8.0.0 (推荐) 或 npm >= 9.0.0
|
||
|
|
|
||
|
|
### 安装依赖
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 使用pnpm(推荐)
|
||
|
|
pnpm install
|
||
|
|
|
||
|
|
# 或使用npm
|
||
|
|
npm install
|
||
|
|
```
|
||
|
|
|
||
|
|
### 启动开发服务器
|
||
|
|
|
||
|
|
```bash
|
||
|
|
pnpm dev
|
||
|
|
```
|
||
|
|
|
||
|
|
访问 http://localhost:5173
|
||
|
|
|
||
|
|
### 构建生产版本
|
||
|
|
|
||
|
|
```bash
|
||
|
|
pnpm build
|
||
|
|
```
|
||
|
|
|
||
|
|
### 运行测试
|
||
|
|
|
||
|
|
```bash
|
||
|
|
pnpm test
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 📋 开发规范
|
||
|
|
|
||
|
|
### Git提交规范
|
||
|
|
|
||
|
|
遵循 Conventional Commits 规范:
|
||
|
|
|
||
|
|
```
|
||
|
|
<type>(<scope>): <subject>
|
||
|
|
|
||
|
|
<body>
|
||
|
|
|
||
|
|
<footer>
|
||
|
|
```
|
||
|
|
|
||
|
|
**类型(type)**:
|
||
|
|
- `feat`: 新功能
|
||
|
|
- `fix`: 修复bug
|
||
|
|
- `docs`: 文档更新
|
||
|
|
- `style`: 代码格式调整(不影响功能)
|
||
|
|
- `refactor`: 重构
|
||
|
|
- `perf`: 性能优化
|
||
|
|
- `test`: 测试相关
|
||
|
|
- `chore`: 构建/工具链相关
|
||
|
|
|
||
|
|
**示例**:
|
||
|
|
```
|
||
|
|
feat(user): 添加用户头像上传功能
|
||
|
|
|
||
|
|
- 实现头像选择和裁剪
|
||
|
|
- 添加上传进度显示
|
||
|
|
- 支持预览功能
|
||
|
|
|
||
|
|
Closes #123
|
||
|
|
```
|
||
|
|
|
||
|
|
### 代码规范
|
||
|
|
|
||
|
|
- **TypeScript**: 所有代码使用TypeScript编写
|
||
|
|
- **组件命名**: PascalCase (UserCard.vue)
|
||
|
|
- **文件命名**: kebab-case (user-profile.ts)
|
||
|
|
- **变量命名**: camelCase (getUserInfo)
|
||
|
|
- **常量命名**: UPPER_SNAKE_CASE (API_BASE_URL)
|
||
|
|
|
||
|
|
### 样式规范
|
||
|
|
|
||
|
|
- **优先使用**: Tailwind CSS工具类
|
||
|
|
- **组件样式**: 使用scoped样式
|
||
|
|
- **全局样式**: 放在src/assets/styles
|
||
|
|
- **CSS变量**: 统一使用CSS变量定义主题
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🎨 设计原则
|
||
|
|
|
||
|
|
### 核心设计理念
|
||
|
|
|
||
|
|
**活力与专业并重**
|
||
|
|
- 融合游戏化元素与现代UI设计
|
||
|
|
- 保持管理工具的专业性和可靠性
|
||
|
|
|
||
|
|
**用户为中心**
|
||
|
|
- 简洁直观的操作流程
|
||
|
|
- 清晰的信息层级
|
||
|
|
- 即时的反馈机制
|
||
|
|
|
||
|
|
**性能优先**
|
||
|
|
- 快速加载
|
||
|
|
- 流畅动画
|
||
|
|
- 高效交互
|
||
|
|
|
||
|
|
### 设计关键词
|
||
|
|
|
||
|
|
- **活力**: 充满动感,富有生命力
|
||
|
|
- **简洁**: 去除冗余,聚焦核心
|
||
|
|
- **直观**: 一目了然,易于理解
|
||
|
|
- **有趣**: 愉悦体验,富有惊喜
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 📊 项目特色
|
||
|
|
|
||
|
|
### 1. 游戏化设计
|
||
|
|
|
||
|
|
- **游戏主题色**: 不同游戏类型使用不同颜色标识
|
||
|
|
- **徽章系统**: 会员、在线状态、荣誉展示
|
||
|
|
- **进度条**: 预约进度、积分进度可视化
|
||
|
|
- **动画效果**: 流畅的微交互增强体验
|
||
|
|
|
||
|
|
### 2. 响应式设计
|
||
|
|
|
||
|
|
- **移动优先**: 从最小屏幕开始设计
|
||
|
|
- **断点系统**: 6个响应式断点
|
||
|
|
- **自适应布局**: 灵活的网格系统
|
||
|
|
- **触摸优化**: 移动端友好的交互
|
||
|
|
|
||
|
|
### 3. 性能优化
|
||
|
|
|
||
|
|
- **代码分割**: 路由级和组件级代码分割
|
||
|
|
- **虚拟滚动**: 长列表性能优化
|
||
|
|
- **图片优化**: WebP格式、懒加载
|
||
|
|
- **缓存策略**: 接口缓存、组件缓存
|
||
|
|
|
||
|
|
### 4. 开发体验
|
||
|
|
|
||
|
|
- **TypeScript**: 完整的类型定义
|
||
|
|
- **热重载**: 即时的开发反馈
|
||
|
|
- **组件库**: 基于Element Plus扩展
|
||
|
|
- **测试**: Vitest单元测试
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🔗 相关链接
|
||
|
|
|
||
|
|
### 内部文档
|
||
|
|
|
||
|
|
- [后端项目文档](../gameGroupBE/doc/README.md)
|
||
|
|
- [后端API文档](../gameGroupBE/doc/api/API文档.md)
|
||
|
|
- [Swagger在线文档](http://localhost:3000/docs) (开发环境)
|
||
|
|
|
||
|
|
### 外部资源
|
||
|
|
|
||
|
|
- [Vue 3官方文档](https://cn.vuejs.org/)
|
||
|
|
- [Vite官方文档](https://cn.vitejs.dev/)
|
||
|
|
- [Pinia官方文档](https://pinia.vuejs.org/zh/)
|
||
|
|
- [Element Plus文档](https://element-plus.org/zh-CN/)
|
||
|
|
- [Tailwind CSS文档](https://tailwindcss.com/docs)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 📝 文档维护
|
||
|
|
|
||
|
|
### 更新规范
|
||
|
|
|
||
|
|
文档应随项目演进持续更新,更新时需:
|
||
|
|
|
||
|
|
1. **保持格式统一**: 遵循Markdown规范
|
||
|
|
2. **更新时间戳**: 在文档末尾更新时间
|
||
|
|
3. **记录变更**: 在相关文档中记录重大变更
|
||
|
|
4. **同步更新**: API文档与代码保持同步
|
||
|
|
|
||
|
|
### 文档负责人
|
||
|
|
|
||
|
|
- **架构文档**: 技术负责人
|
||
|
|
- **设计文档**: UI/UX设计师
|
||
|
|
- **组件文档**: 前端开发者
|
||
|
|
- **API文档**: 后端开发者
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 💬 反馈与建议
|
||
|
|
|
||
|
|
如有文档相关问题或建议,请:
|
||
|
|
|
||
|
|
1. 在项目中提Issue
|
||
|
|
2. 联系项目维护者
|
||
|
|
3. 参与文档改进
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
**文档版本**: v1.0
|
||
|
|
**最后更新**: 2026-01-28
|
||
|
|
**维护团队**: GameGroup Frontend Team
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 📄 许可证
|
||
|
|
|
||
|
|
本项目文档仅供内部使用,包含敏感信息,请勿泄露给外部人员。
|