# web-chat

**Repository Path**: zhang--shuang/web-chat

## Basic Information

- **Project Name**: web-chat
- **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-12-19
- **Last Updated**: 2025-12-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🐱 聊天应用 - 完整开发文档

> **日期**：2025-12-19
> **技术栈**：Spring Boot 3.2.0 + Vue 3.4.0 + WebSocket + MySQL

---

## 📋 目录

- [项目概述](#项目概述)
- [技术架构](#技术架构)
- [已完成功能](#已完成功能)
- [快速开始](#快速开始)
- [启动应用](#启动应用)
- [API 接口文档](#api-接口文档)
- [前端页面](#前端页面)
- [扩展功能计划](#扩展功能计划)
- [常见问题](#常见问题)

---

## 项目概述

这是一个功能完整的实时聊天应用，支持用户注册、登录、群聊等核心功能。系统采用前后端分离架构，使用 JWT 进行身份认证，WebSocket 实现实时通信。

### 核心特性

✅ **用户系统**

- 用户注册（用户名/手机号/密码，支持实时校验）
- 用户登录（支持用户名或手机号登录）
- JWT Token 认证
- 个人信息管理

✅ **聊天功能**

- WebSocket 实时通信
- 群聊消息
- 在线状态显示
- 消息历史记录

✅ **安全特性**

- BCrypt 密码加密
- JWT 无状态认证
- Spring Security 权限控制
- CORS 跨域支持

---

## 技术架构

### 后端技术栈

| 技术              | 版本   | 说明       |
| ----------------- | ------ | ---------- |
| Spring Boot       | 3.2.0  | 核心框架   |
| Spring Security   | 6.2.0  | 安全框架   |
| MyBatis-Plus      | 3..7   | ORM 框架   |
| MySQL             | 8.0    | 数据库     |
| WebSocket (STOMP) | -      | 实时通信   |
| JWT (jjwt)        | 0.12.3 | Token 认证 |
| Lombok            | -      | 代码简化   |
| Hutool            | 5.8.23 | 工具库     |

### 前端技术栈

| 技术       | 版本  | 说明             |
| ---------- | ----- | ---------------- |
| Vue        | 3.4.0 | 前端框架         |
| Vue Router | 4.x   | 路由管理         |
| Pinia      | 2.x   | 状态管理         |
| Axios      | 1.x   | HTTP 客户端      |
| STOMP.js   | 7.0.0 | WebSocket 客户端 |
| SockJS     | 1.6.1 | WebSocket 降级   |
| Vite       | 5.0.0 | 构建工具         |

---

## 已完成功能

### 🔐 用户认证模块

**后端实现：**

- `UserServiceImpl` - 用户业务逻辑
- `AuthController` - 认证接口（注册、登录、检查）
- `UserController` - 用户信息接口
- `JwtUtils` - JWT Token 生成与验证
- `JwtAuthenticationFilter` - JWT 认证过滤器
- `SecurityConfig` - Spring Security 配置

**前端实现：**

- `Login.vue` - 登录页面
- `Register.vue` - 注册页面（含实时校验）
- `Profile.vue` - 个人中心
- `useUserStore` - 用户状态管理（Pinia）
- `auth.js` - 认证 API 封装

**功能特性：**

- ✅ 用户名/手机号唯一性实时检查
- ✅ 密码强度验证（至少8位，含字母和数字）
- ✅ 手机号格式验证（中国大陆）
- ✅ JWT Token 自动刷新
- ✅ 登录状态持久化（LocalStorage）

### 💬 聊天功能模块

**后端实现：**

- `ChatMessageMapper` - 消息数据访问层
- WebSocket 配置（支持 STOMP）

**前端实现：**

- `Chat.vue` - 聊天室页面
- `WebSocketService.js` - WebSocket 封装（支持 JWT）

**功能特性：**

- ✅ 实时群聊消息
- ✅ 用户加入/离开提示
- ✅ 消息时间戳显示
- ✅ 自动滚动到最新消息
- ✅ 发送者区分显示（自己/他人）

### 🗄️ 数据库设计

**用户表 (user)**

- id, username, phone, password, nickname, email, avatar_url
- status, created_at, last_login_at, updated_at

**聊天消息表 (chat_message)**

- id, sender_id, receiver_id (NULL=群聊), content
- message_type, created_at

**角色权限表 (role, user_role)**

- 支持 RBAC 权限系统
- 预设 ADMIN 和 USER 角色

### 🎨 用户界面

**登录页面** (`/login`)

- 简洁优雅的渐变背景
- 用户名/手机号统一登录
- 实时错误提示
- 跳转到注册页面链接

**注册页面** (`/register`)

- 完整的表单验证
- 实时检查用户名/手机号是否已注册
- 密码强度提示
- 注册成功自动跳转登录

**聊天页面** (`/chat`)

- 现代化聊天界面
- 区分自己和他人的消息
- 个人头像显示
- 快捷跳转个人中心

**个人中心** (`/profile`)

- 显示用户信息
- 角色标识（管理员/普通用户）
- 退出登录功能
- 返回聊天室链接

---

## 快速开始

### 环境要求

- **JDK**: 17 或更高
- **Node.js**: 16 或更高
- **MySQL**: 8.0 或更高
- **Maven**: 3.6 或更高

---

## 启动应用

### 启动后端

1. **刷新 Maven 依赖**
   - 在 IDEA 中点击右上角 Maven 刷新按钮
   - 或右键 `pom.xml` → Maven → Reload Project

2. **启动 Spring Boot 应用**
   - 运行 `backend/src/main/java/com/example/chat/ChatApplication.java`
   - 默认端口：`8080`
   - 启动成功后访问：`http://localhost:8080`

### 启动前端

1. **安装依赖**

   ```bash
   cd frontend
   npm install
   ```

2. **启动开发服务器**

   ```bash
   npm run dev
   ```

   - 默认端口：`5173`
   - 访问地址：`http://localhost:5173`

---

## API 接口文档

### 认证接口（无需认证）

#### 1. 用户注册

```http
POST /api/auth/register
Content-Type: application/json

{
  "username": "testuser",
  "phone": "13800138000",
  "password": "Test1234",
  "nickname": "测试用户",
  "email": "test@example.com"
}
```

**响应示例：**

```json
{
  "code": 200,
  "message": "注册成功",
  "data": null
}
```

#### 2. 用户登录

```http
POST /api/auth/login
Content-Type: application/json

{
  "loginId": "testuser",
  "password": "Test1234"
}
```

**响应示例：**

```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "userInfo": {
      "id": 2,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@example.com",
      "avatarUrl": null,
      "roles": ["USER"]
    }
  }
}
```

#### 3. 检查用户名是否存在

```http
GET /api/auth/check-username?username=testuser
```

**响应：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": true  // true=已存在，false=不存在
}
```

#### 4. 检查手机号是否存在

```http
GET /api/auth/check-phone?phone=13800138000
```

### 用户接口（需要认证）

#### 1. 获取当前用户信息

```http
GET /api/user/info
Authorization: Bearer {token}
```

**响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 2,
    "username": "testuser",
    "nickname": "测试用户",
    "email": "test@example.com",
    "avatarUrl": null,
    "roles": ["USER"]
  }
}
```

#### 2. 更新当前用户信息

```http
PUT /api/user/info
Authorization: Bearer {token}
Content-Type: application/json

{
  "nickname": "新昵称",
  "email": "newemail@example.com",
  "avatarUrl": "https://example.com/avatar.jpg"
}
```

#### 3. 根据ID获取用户信息

```http
GET /api/user/{userId}
Authorization: Bearer {token}
```

---

## 前端页面

### 路由配置

| 路由        | 组件         | 说明             | 权限要求 |
| ----------- | ------------ | ---------------- | -------- |
| `/`         | -            | 重定向到 `/chat` | -        |
| `/login`    | Login.vue    | 登录页面         | 无需认证 |
| `/register` | Register.vue | 注册页面         | 无需认证 |
| `/chat`     | Chat.vue     | 聊天室           | 需要认证 |
| `/profile`  | Profile.vue  | 个人中心         | 需要认证 |

### 导航守卫

- **未登录用户** 访问需认证页面 → 跳转到登录页
- **已登录用户** 访问登录/注册页 → 跳转到聊天页
- **Token 失效** → 自动清除登录状态并跳转登录页

---

## 扩展功能计划

以下功能已完成数据库设计和部分代码结构，可在后续迭代中实现：

### 🖼️ 图形验证码

- 后端依赖已添加：`Easy Captcha 1.6.2`
- 需要实现：验证码生成接口、验证逻辑集成到登录流程

### 💌 私聊功能

- 数据库已支持：`chat_message.receiver_id` 字段
- 需要实现：私聊消息发送接口、前端私聊UI、消息路由逻辑

### 👑 管理员功能

- 数据库已支持：`role` 和 `user_role` 表
- 需要实现：用户管理界面、角色权限配置、管理员操作日志

### 📦 消息持久化

- 数据库已准备：`chat_message` 表
- 需要实现：WebSocket 消息保存到数据库、历史消息加载

### 🔔 消息通知

- 浏览器通知 API 集成
- 未读消息计数
- @提及功能

---

## 常见问题

### Q1: 启动后端报错 "Access denied for user 'mydata'@'localhost'"

**A:** 数据库未初始化或用户权限不足。

### Q2: 前端无法连接后端 WebSocket

**A:**

1. 检查后端是否启动（端口 8080）
2. 检查 CORS 配置是否正确
3. 确认浏览器控制台是否有错误信息

### Q3: 登录后 Token 失效

**A:**

1. 检查后端 `application.properties` 中的 `jwt.secret` 配置
2. 确认 Token 有效期（默认 24 小时）
3. 清除浏览器 LocalStorage 重新登录

### Q4: 注册时提示"用户名已存在"但实际不存在

**A:**

1. 检查数据库 `user` 表中是否有重复数据
2. 确认用户名不是"admin"（默认管理员）

### Q5: MyBatis-Plus 版本冲突

**A:** 确保使用 MyBatis-Plus 3.5.7 和 mybatis-spring 3.0.3，已在 `pom.xml` 中配置。

---

## 项目结构

```
web-chat/
├── backend/                  # 后端 Spring Boot 项目
│   ├── src/main/java/com/example/chat/
│   │   ├── config/          # 配置类（Security、CORS、WebSocket）
│   │   ├── controller/      # 控制器（Auth、User）
│   │   ├── dto/             # 数据传输对象
│   │   ├── entity/          # 实体类（User、ChatMessage、Role）
│   │   ├── exception/       # 异常处理
│   │   ├── mapper/          # MyBatis Mapper 接口
│   │   ├── security/        # 安全组件（JWT、Filter、UserPrincipal）
│   │   ├── service/         # 业务逻辑层
│   │   └── util/            # 工具类（JwtUtils）
│   ├── src/main/resources/
│   │   ├── schema/          # SQL 初始化脚本
│   │   └── application.properties  # 配置文件
│   ├── init-database.bat    # 数据库初始化脚本
│   └── pom.xml              # Maven 配置
│
└── frontend/                 # 前端 Vue 项目
    ├── src/
    │   ├── api/             # API 接口封装
    │   ├── components/      # 组件（已弃用，改用 views）
    │   ├── router/          # Vue Router 配置
    │   ├── services/        # 服务（WebSocket）
    │   ├── stores/          # Pinia 状态管理
    │   ├── views/           # 页面组件
    │   ├── App.vue          # 根组件
    │   └── main.js          # 入口文件
    ├── package.json         # NPM 配置
    └── vite.config.js       # Vite 配置
```

---

## 开发规范

### 后端代码规范

- 所有类和方法必须添加完整的 JavaDoc 注释
- 使用 Lombok 简化 Getter/Setter
- 统一异常处理（GlobalExceptionHandler）
- 统一响应格式（Result<T>）
- 遵循 RESTful API 设计原则

### 前端代码规范

- 使用 Vue 3 Composition API（script setup）
- 组件命名：PascalCase
- 函数命名：camelCase
- 常量命名：UPPER_SNAKE_CASE
- 所有 API 调用必须经过统一封装

---

## 性能优化建议

### 后端优化

1. **数据库连接池配置**

   ```properties
   spring.datasource.hikari.maximum-pool-size=20
   spring.datasource.hikari.minimum-idle=5
   ```

2. **MyBatis-Plus 缓存启用**

   ```properties
   mybatis-plus.configuration.cache-enabled=true
   ```

3. **JWT Token 缓存**

   - 使用 Redis 缓存 Token 验证结果

### 前端优化

1. **路由懒加载**（已实现）

   ```javascript
   component: () => import('../views/Login.vue')
   ```

2. **Axios 请求/响应缓存**

3. **WebSocket 心跳优化**

4. **消息列表虚拟滚动**（大量消息时）

---

## 安全注意事项

### 生产环境必须修改

1. **JWT 密钥**

   ```properties
   # 修改为复杂的随机字符串
   jwt.secret=YOUR_PRODUCTION_SECRET_KEY_HERE
   ```

2. **数据库密码**

   ```properties
   spring.datasource.username=your_db_user
   spring.datasource.password=your_strong_password
   ```

3. **CORS 配置**

   ```java
   // 限制允许的来源域名
   configuration.setAllowedOriginPatterns(Arrays.asList("https://your-domain.com"));
   ```

---

## 联系方式

如有问题或建议，请联系：

- **作者**：猫娘工程师 幽浮喵
- **日期**：2025-12-19

---

**祝您使用愉快！ฅ'ω'ฅ**