# 轻量级实时协作应用-2班1组 **Repository Path**: grade-23-full-stack-class-2/lightweight-realtime-collab-app-class2-group1 ## Basic Information - **Project Name**: 轻量级实时协作应用-2班1组 - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-08-13 - **Last Updated**: 2025-09-01 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 🎨 涂色抢地盘 - Territory Paint Battle 一个基于Vue.js和.NET的实时多人协作绘画游戏，玩家通过涂色来占领区域，争夺地盘。 ## 🚀 功能特性 ### 核心功能 - 🔐 **用户认证系统**：JWT token认证，支持注册和登录 - 🎨 **实时多人绘画**：基于Canvas API的实时涂色功能 - 🏆 **实时排行榜**：显示玩家涂色面积占比和排名 - ⏰ **倒计时游戏模式**：30秒限时游戏，时间到自动结算 - 📊 **实时统计**：实时显示各玩家涂色面积百分比 - 🎯 **游戏状态管理**：等待、准备、游戏中、结算四个状态 - 👥 **玩家角色管理**：支持玩家和观战者两种角色 - 🔄 **自动重连**：断线重连后保持游戏状态 ### 高级功能 - 📱 **响应式设计**：支持桌面端和移动端 - 🗄️ **数据持久化**：PostgreSQL存储用户数据和游戏统计 - ⚡ **高性能缓存**：Redis缓存会话和实时数据 - 🔒 **安全机制**：防刷屏、防覆盖他人区域 - ⏱️ **无操作检测**：可配置的无操作自动登出（默认2分钟） - 🎮 **游戏结算**：显示获胜者和详细统计信息 ## 🛠️ 技术栈 ### 前端技术栈 - **框架**: Vue 3.5.18 + Composition API - **路由**: Vue Router 4.5.1 - **实时通信**: @microsoft/signalr 9.0.6 - **构建工具**: Vite 7.0.6 - **代码规范**: ESLint 9.31.0 + Prettier 3.6.2 - **开发工具**: Vue DevTools 8.0.0 ### 后端技术栈 - **框架**: .NET 8.0 - **Web框架**: ASP.NET Core Web API - **实时通信**: SignalR - **认证**: JWT Bearer Token - **架构模式**: 清洁架构 (Clean Architecture) - **ORM**: Entity Framework Core 8.0.2 - **API文档**: Swagger/OpenAPI ### 数据库技术栈 - **主数据库**: PostgreSQL 8.0.2 (远程: 8.152.214.221:5432) - **缓存数据库**: Redis 2.7.17 (远程: 8.152.214.221:6379) - **命名约定**: snake_case格式 (如: `user_roles`, `created_at`) - **迁移工具**: EF Core Migrations ## 🗄️ 数据库结构 ### 核心表结构 (snake_case格式) #### `players` - 玩家信息表 ```sql - id (UUID, PK) - username (VARCHAR, UNIQUE) - password_hash (VARCHAR) - created_at (TIMESTAMP) - last_login_at (TIMESTAMP) - color (VARCHAR) -- 玩家专属颜色 - total_games_played (INTEGER) -- 总游戏数 - total_games_won (INTEGER) -- 获胜局数 - total_area_painted (DOUBLE) -- 总涂色面积 ``` #### `game_sessions` - 游戏会话表 ```sql - id (UUID, PK) - name (VARCHAR) - status (VARCHAR) -- Waiting, Playing, Finished - created_at (TIMESTAMP) - started_at (TIMESTAMP) - ended_at (TIMESTAMP) - max_players (INTEGER) - time_limit (INTEGER) -- 游戏时长(秒) ``` #### `rooms` - 游戏房间表 ```sql - id (UUID, PK) - name (VARCHAR) - status (VARCHAR) - created_at (TIMESTAMP) - max_players (INTEGER) - current_players (INTEGER) ``` ## 🚀 快速开始 ### 环境要求 - **Node.js**: ^20.19.0 或 >=22.12.0 - **.NET**: 8.0 SDK - **数据库**: PostgreSQL 和 Redis (远程配置) ### 使用启动脚本 (推荐) #### Windows ```bash start.bat ``` #### Linux/Mac ```bash chmod +x start.sh ./start.sh ``` ### 手动启动 #### 1. 前端启动 ```bash cd frontend npm install npm run dev ``` 前端将在 `http://localhost:5173` 运行 #### 2. 后端启动 ```bash cd backend/src/TerritoryGame.API dotnet restore dotnet run ``` 后端API将在 `http://localhost:5008` 运行 Swagger文档: `http://localhost:5008/swagger` ## 🎮 游戏玩法 ### 游戏流程 1. **注册/登录**: 使用测试账号或注册新账号 2. **加入游戏**: 登录后自动进入游戏大厅 3. **准备阶段**: 点击"准备"按钮，等待其他玩家 4. **游戏开始**: 所有玩家准备后，房主可点击"开始游戏" 5. **涂色竞争**: 在30秒内尽可能多地涂色占领区域 6. **游戏结算**: 时间到后显示获胜者和统计信息 ## 📸 成果展示 ### 登录界面 ![登录界面](https://gitee.com/an-xiaoning/liuhuan/raw/master/20250821095242513.png) *用户登录界面，支持注册新账号和登录现有账号* ### 游戏大厅 ![游戏大厅](https://gitee.com/an-xiaoning/liuhuan/raw/master/20250821095302545.png) *游戏大厅界面，显示在线玩家列表和准备状态* ### 游戏进行中 ![游戏进行中](https://gitee.com/an-xiaoning/liuhuan/raw/master/20250821095445986.png) *实时多人涂色游戏界面，显示各玩家涂色区域和实时统计* ### 游戏结算 ![游戏结算](https://gitee.com/an-xiaoning/liuhuan/raw/master/20250821095510443.png) *游戏结束后的结算界面，显示获胜者和详细统计信息* ### 排行榜 ![排行榜](https://gitee.com/an-xiaoning/liuhuan/raw/master/20250821095322489.png) *玩家排行榜，显示总游戏数、获胜数和涂色面积统计* ### 游戏规则 - **玩家数量**: 2-6人 - **游戏时长**: 30秒 - **获胜条件**: 涂色面积最大的玩家获胜 - **涂色限制**: 不能覆盖其他玩家已涂色区域 - **观战模式**: 游戏开始后加入的玩家自动成为观战者 ### 特殊机制 - **实时同步**: 所有玩家的涂色操作实时同步 - **面积计算**: 基于网格的精确面积计算 - **防刷屏**: 连续涂色有冷却机制 - **断线重连**: 支持断线后重新连接 ## 📡 API接口 ### 认证接口 - `POST /api/auth/register` - 用户注册 - `POST /api/auth/login` - 用户登录 ### 统计接口 - `GET /api/statistics/my-stats` - 获取我的统计数据 - `GET /api/statistics/top-players` - 获取排行榜 ### 实时通信 (SignalR) - **Hub**: `/gamehub` - **事件**: - `JoinGame` - 加入游戏 - `SendPaintData` - 发送涂色数据 - `SetReady` - 设置准备状态 - `StartGame` - 开始游戏 - `UpdatePlayerStats` - 更新玩家统计 - `UpdateTimer` - 更新倒计时 - `GameFinished` - 游戏结束 ## 👥 测试账号 系统预置了以下测试账号： - **用户名**: `testuser123`, **密码**: `123456` - **用户名**: `player1`, **密码**: `player123` - **用户名**: `player2`, **密码**: `player123` ## 📁 项目结构 ``` lightweight-realtime-collab-app-class2-group1/ ├── frontend/ # Vue.js前端 │ ├── src/ │ │ ├── views/ # 页面组件 │ │ │ ├── Login.vue # 登录页面 (8.3KB) │ │ │ └── Game.vue # 游戏页面 (34KB) │ │ ├── router/ # 路由配置 │ │ │ └── index.js # 路由定义 │ │ ├── components/ # 通用组件 │ │ │ └── icons/ # 图标组件 │ │ ├── assets/ # 静态资源 │ │ │ ├── base.css # 基础样式 │ │ │ ├── logo.svg # Logo │ │ │ └── main.css # 主样式 │ │ ├── App.vue # 根组件 │ │ └── main.js # 应用入口 │ ├── public/ # 公共资源 │ │ └── favicon.ico # 网站图标 │ ├── package.json # 依赖配置 │ ├── vite.config.js # Vite配置 │ ├── eslint.config.js # ESLint配置 │ └── README.md # 前端说明 ├── backend/ # .NET后端 │ └── src/ │ ├── TerritoryGame.API/ # Web API层 │ │ ├── Controllers/ # API控制器 │ │ ├── Hubs/ # SignalR Hubs │ │ │ └── GameHub.cs # 游戏Hub (754行) │ │ ├── Filters/ # 过滤器 │ │ ├── Middleware/ # 中间件 │ │ ├── Program.cs # 应用配置 │ │ └── appsettings.json # 配置文件 │ ├── TerritoryGame.Application/ # 应用服务层 │ │ ├── Commands/ # 命令 │ │ │ ├── Game/ # 游戏命令 │ │ │ ├── Player/ # 玩家命令 │ │ │ └── Room/ # 房间命令 │ │ ├── Queries/ # 查询 │ │ │ ├── Game/ # 游戏查询 │ │ │ ├── Player/ # 玩家查询 │ │ │ ├── Room/ # 房间查询 │ │ │ └── Statistics/ # 统计查询 │ │ ├── Handlers/ # 命令/查询处理器 │ │ ├── Services/ # 应用服务 │ │ │ └── GameStatisticsService.cs # 统计服务 │ │ ├── DTOs/ # 数据传输对象 │ │ └── Interfaces/ # 接口定义 │ ├── TerritoryGame.Domain/ # 领域层 │ │ ├── Aggregates/ # 聚合根 │ │ ├── Entities/ # 实体 │ │ │ ├── Canvas/ # 画布实体 │ │ │ ├── Game/ # 游戏实体 │ │ │ ├── Player/ # 玩家实体 │ │ │ └── Room/ # 房间实体 │ │ ├── ValueObjects/ # 值对象 │ │ ├── Events/ # 领域事件 │ │ ├── Exceptions/ # 领域异常 │ │ ├── Interfaces/ # 领域接口 │ │ ├── Repositories/ # 仓储接口 │ │ └── Services/ # 领域服务 │ └── TerritoryGame.Infrastructure/ # 基础设施层 │ ├── Configuration/ # 配置 │ ├── External/ # 外部服务 │ ├── Persistence/ # 持久化 │ │ └── TerritoryGameDbContext.cs # EF上下文 │ ├── Redis/ # Redis配置 │ └── SignalR/ # SignalR配置 ├── docs/ # 项目文档 │ ├── REQUIREMENTS.md # 需求文档 (22KB) │ └── BACKEND_DEVELOPMENT_PROCESS.md # 后端开发过程 (11KB) ├── start.bat # Windows启动脚本 ├── start.sh # Linux/Mac启动脚本 └── README.md # 项目说明 ``` ## 🏗️ 架构设计 ### 前端架构 - **组件化设计**: 基于Vue 3 Composition API - **状态管理**: 响应式数据管理 - **实时通信**: SignalR客户端集成 - **Canvas渲染**: 原生Canvas API实现涂色功能 - **路由管理**: Vue Router实现页面导航 ### 后端架构 (清洁架构) ``` ┌─────────────────────────────────────┐ │ TerritoryGame.API │ ← 表现层 │ (Controllers, Hubs, Middleware) │ ├─────────────────────────────────────┤ │ TerritoryGame.Application │ ← 应用层 │ (Commands, Queries, Services) │ ├─────────────────────────────────────┤ │ TerritoryGame.Domain │ ← 领域层 │ (Entities, ValueObjects, Services) │ ├─────────────────────────────────────┤ │ TerritoryGame.Infrastructure │ ← 基础设施层 │ (Persistence, External Services) │ └─────────────────────────────────────┘ ``` ### 数据流 1. **前端** → SignalR → **GameHub** → **应用服务** → **领域服务** → **仓储** → **数据库** 2. **数据库** → **仓储** → **领域服务** → **应用服务** → **GameHub** → SignalR → **前端** ## 🔧 开发指南 ### 前端开发 ```bash cd frontend npm install # 安装依赖 npm run dev # 启动开发服务器 npm run build # 构建生产版本 npm run lint # 代码检查 npm run format # 代码格式化 ``` ### 后端开发 ```bash cd backend/src/TerritoryGame.API dotnet restore # 恢复包 dotnet run # 运行项目 dotnet build # 构建项目 dotnet test # 运行测试 ``` ### 数据库迁移 ```bash cd backend/src/TerritoryGame.Infrastructure dotnet ef migrations add InitialCreate dotnet ef database update ``` ### 代码规范 - **前端**: ESLint + Prettier - **后端**: .NET 8 代码规范 - **数据库**: snake_case命名约定 ## 🚀 部署 ### 前端部署 ```bash cd frontend npm run build # 将dist目录部署到Web服务器 ``` ### 后端部署 ```bash cd backend/src/TerritoryGame.API dotnet publish -c Release --self-contained # 部署到Linux服务器 ``` ### 生产环境配置 - **数据库**: 远程PostgreSQL和Redis - **反向代理**: Nginx配置 - **HTTPS**: SSL证书配置 - **进程管理**: systemd服务 ## 📊 性能优化 ### 前端优化 - **代码分割**: Vite自动代码分割 - **懒加载**: 路由懒加载 - **缓存策略**: 静态资源缓存 - **Canvas优化**: 防抖和节流 ### 后端优化 - **连接池**: 数据库连接池配置 - **缓存**: Redis缓存热点数据 - **异步处理**: 全异步操作 - **内存管理**: 及时释放资源 ## 🐛 故障排除 ### 常见问题 1. **连接失败**: 检查数据库连接字符串 2. **实时通信中断**: 检查SignalR配置 3. **涂色不同步**: 检查网格计算逻辑 4. **统计不更新**: 检查持久化流程 ### 日志查看 - **前端**: 浏览器开发者工具 - **后端**: 控制台输出和日志文件 - **数据库**: PostgreSQL和Redis日志 ## 🤝 贡献指南 1. Fork 项目 2. 创建功能分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 打开 Pull Request ## 📄 许可证 本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情 ## 👨‍💻 团队成员 - **刘欢** - http://game.7sunflower.cn - **叶功照** - http://game_01.ylovegforever.cn - **王璇** - http://game.thewangxuan.cn 如有问题或建议，请通过以下方式联系： - 提交 Issue - 发送邮件 - 团队内部沟通 --- **注意**: 本项目为课程作业，仅供学习和演示使用。