# webchat-front

**Repository Path**: walii/webchat-front

## Basic Information

- **Project Name**: webchat-front
- **Description**: WebChat 是一款功能完整的即时通讯（IM）前端应用，基于 Vue 3 + Vite + Element Plus 构建，提供类微信的聊天体验。支持文本、图片、语音、文件、视频等多媒体消息，具备好友管理、群组聊天、实时推送、响应式布局等企业级特性。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-17
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Vue, JavaScript

## README

# WebChat 即时通讯客户端

[![Vue](https://img.shields.io/badge/Vue-3.5.13-brightgreen)](https://vuejs.org/)
[![Vite](https://img.shields.io/badge/Vite-6.1.0-646CFF)](https://vitejs.dev/)
[![Element Plus](https://img.shields.io/badge/Element%20Plus-2.11.8-409EFF)](https://element-plus.org/)
[![WebSocket](https://img.shields.io/badge/WebSocket-STOMP-important)](https://stomp.github.io/)
[![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)

**WebChat** 是一款功能完整的即时通讯（IM）前端应用，基于 Vue 3 + Vite + Element Plus 构建，提供类微信的聊天体验。支持文本、图片、语音、文件、视频等多媒体消息，具备好友管理、群组聊天、实时推送、响应式布局等企业级特性。

---

## 📖 目录

- [核心功能](#-核心功能)
- [技术栈](#-技术栈)
- [项目架构](#-项目架构)
- [快速开始](#-快速开始)
- [核心模块说明](#-核心模块说明)
- [状态管理](#-状态管理)
- [WebSocket 实时通信](#-websocket-实时通信)
- [环境配置](#-环境配置)
- [构建与部署](#-构建与部署)
- [项目特色](#-项目特色)
- [后续规划](#-后续规划)
- [贡献指南](#-贡献指南)
- [许可证](#-许可证)

---

## 🎯 核心功能

### 1. 用户认证
- 用户登录（用户名/密码 + JWT Token）
- 用户注册（昵称、密码、确认密码）
- 记住密码功能
- 自动登出与路由守卫
- Token 自动注入请求头

### 2. 即时通讯
- **WebSocket 实时消息**（基于 SockJS + STOMP）
- **消息类型**：文本、图片、文件、语音、系统消息、视频
- 气泡式聊天界面（微信风格）
- 消息自动滚动到底部
- 时间分隔线（≥5分钟间隔）
- 图片/视频点击预览
- 文件下载

### 3. 会话管理
- 会话列表（按最后消息时间排序）
- 最后一条消息摘要（文本化展示）
- 未读消息角标
- 会话搜索
- 点击切换会话
- 会话详情抽屉

### 4. 消息发送
- 多行文本输入（支持回车发送）
- 表情选择器（Emoji）
- 图片/视频上传（自动发送）
- 文件上传（显示文件名）
- **语音录制**：按住说话、上滑取消、实时计时（最长60秒）

### 5. 联系人管理
- 好友列表（分组显示，展开/折叠）
- 群组列表
- 联系人/群组详情查看
- 好友数量统计

### 6. 全局搜索
- 搜索用户
- 搜索会话
- 搜索结果独立窗口

### 7. 用户界面
- 左侧导航栏（消息、通讯录、发现）
- 未读消息角标
- 底部设置菜单（退出登录、设置窗口）
- **响应式布局**（桌面端/移动端自适应，@media 768px）
- 深色侧边栏 + 浅色内容区（微信配色）
- **移动端特色**：
  - 底部 TabBar（消息、通讯录、发现、我的）
  - "我的"页面（用户头像、昵称、微信号、功能菜单）
  - 滑动返回手势支持
  - 朋友圈页面（带返回按钮）
  - 联系人详情页面（带返回按钮）

### 8. WebSocket 高级特性
- **统一订阅管理**：`subscriptionManager.js` 集中管理所有订阅，避免重复订阅
- **自动重连机制**：指数退避策略（1s~30s），刷新页面自动恢复连接
- **订阅恢复**：重连成功后自动恢复所有订阅
- **消息去重**：群聊场景下自动过滤自己发送的消息（避免重复显示）

### 9. 数据持久化
- 登录状态持久化（localStorage）
- 会话列表缓存
- 刷新页面保持状态

---

## 🧰 技术栈

| 类别               | 技术选型                                                                 |
|-------------------|-------------------------------------------------------------------------|
| **核心框架**       | Vue 3.5.13 (Composition API + `<script setup>`)                         |
| **构建工具**       | Vite 6.1.0 + @vitejs/plugin-vue                                         |
| **UI 组件库**      | Element Plus 2.11.8 + Icons + @form-create/element-ui                   |
| **状态管理**       | Vuex 4.1.0 + vuex-persistedstate (localStorage)                         |
| **路由管理**       | Vue Router 4.6.3 (History 模式)                                         |
| **HTTP 客户端**    | Axios 1.15.0 (请求/响应拦截器，自动 Token)                               |
| **实时通信**       | SockJS 1.6.1 + Stomp.js 2.3.3                                           |
| **多媒体**         | MediaRecorder API (录音) + File API (上传) + Element Plus Image Viewer |
| **样式**           | CSS3 (自定义滚动条，响应式 @media 768px)                                |
| **开发环境**       | Node.js 18+ / npm 9+                                                    |

---

## 🏗️ 项目架构

```
src/
├── api/                    # API 接口层
│   ├── request.js          # Axios 实例（baseURL: http://192.168.10.6:8001）
│   ├── userApi.js          # 用户认证、用户信息、搜索
│   ├── sessionApi.js       # 会话列表
│   ├── messageApi.js       # 消息历史、发送
│   ├── friendApi.js        # 好友列表
│   ├── groupApi.js         # 群组列表
│   └── uploadApi.js        # 文件上传（语音/图片/文件）
├── client/                 # 客户端服务
│   ├── websocket.js        # WebSocket 连接管理（STOMP 协议）
│   └── subscriptionManager.js  # 统一订阅管理器（集中管理所有消息订阅）
├── components/             # 可复用组件（30+）
│   ├── MessageBubble.vue   # 消息气泡
│   ├── EmojiPanel.vue      # 表情面板
│   ├── VoiceRecorder.vue   # 语音录制
│   ├── SessionItem.vue     # 会话项
│   ├── SessionWindow.vue   # 会话窗口
│   ├── SessionList.vue     # 会话列表
│   ├── MobileTabBar.vue    # 移动端底部导航栏
│   ├── MomentWindow.vue    # 朋友圈窗口
│   ├── SettingWindow.vue   # 设置窗口
│   └── ...
├── layout/                 # 布局组件
│   ├── TabBar.vue          # 左侧导航栏（桌面端）
│   ├── MainFlex.vue        # 主内容区（左右分栏，支持移动端切换）
│   ├── LeftList.vue        # 左侧列表容器
│   └── RightWindow.vue     # 右侧窗口容器
├── router/                 # 路由配置
│   └── index.js            # 路由守卫（登录拦截）
├── store/                  # Vuex 状态管理
│   ├── store.js            # 入口（启用持久化）
│   ├── user.js             # 用户模块（token, user, showSetting, navIndex）
│   ├── session.js          # 会话模块（sessionList, currentSession, receivedMsgs）
│   └── detail.js           # 详情模块（currentDetail, currentDetailType）
├── views/                  # 页面视图
│   ├── Login.vue           # 登录页
│   ├── Register.vue        # 注册页
│   └── Index.vue           # 主应用页（含移动端初始化逻辑）
├── assets/                 # 静态资源
│   ├── global.css          # 全局样式
│   ├── responsive.js       # 响应式工具（设备检测）
│   ├── logo.ico
│   └── utils.js            # 工具函数
└── App.vue                 # 根组件
```

---

## 🚀 快速开始

### 前置条件
- Node.js 18+ 
- npm 9+ 或 pnpm 8+

### 1. 克隆项目
```bash
git clone https://github.com/your-company/webchat-frontend.git
cd webchat-frontend
```

### 2. 安装依赖
```bash
npm install
# 或使用 pnpm
pnpm install
```

### 3. 配置后端地址
编辑 `src/api/request.js`：
```javascript
const service = axios.create({
  baseURL: 'http://your-backend-ip:8001',  // 修改为实际后端地址
  timeout: 15000
})
```

### 4. 启动开发服务器
```bash
npm run dev
```
访问 `http://localhost:8002`（默认端口）

### 5. 生产构建
```bash
npm run build
# 构建产物位于 dist/ 目录
```

---

## 📦 核心模块说明

### API 接口层
所有后端请求统一通过 `request.js` 的 axios 实例发送：
- **请求拦截器**：自动添加 `Authorization: Bearer {token}`
- **响应拦截器**：统一处理错误码（如 401 跳转登录）
- **FormData 自动识别**：文件上传时自动设置 Content-Type

### 组件库
项目包含 30+ 可复用组件，核心组件如下：

| 组件                 | 用途                                 |
|----------------------|--------------------------------------|
| `MessageBubble`      | 消息气泡（左右区分，支持所有消息类型）|
| `EmojiPanel`         | 表情选择器（点击插入表情）           |
| `VoiceRecorder`      | 录音组件（按住说话，上滑取消）       |
| `SessionItem`        | 会话列表项（未读数、最后消息）       |
| `ChatInput`          | 消息输入栏（文本+工具栏）            |
| `ImagePreview`       | 图片/视频预览（基于 Element Plus）   |
| `ContactList`        | 联系人列表（分组、折叠）             |

### 工具函数 (`assets/utils.js`)
- `formatTime()` - 格式化消息时间（今天/昨天/日期）
- `getMessagePreview()` - 根据消息类型生成预览文本
- `uploadFile()` - 通用文件上传封装

---

## 🗃️ 状态管理

### User Module
```javascript
state: {
  token: '',           // JWT Token
  user: {},            // 用户信息 { id, username, nickname, avatar }
  showSetting: false   // 设置窗口显示
}
actions: {
  login(), logout(), setUser(), setToken()
}
```

### Session Module
```javascript
state: {
  sessionList: [],          // 会话列表（排序后）
  currentSession: null,     // 当前激活会话
  unreadCount: 0            // 总未读数
}
getters: {
  sortedSessionList  // 按置顶 + 最后消息时间排序
}
```

### Detail Module
```javascript
state: {
  currentDetail: null,      // 当前详情对象（好友或群组）
  currentDetailType: 0      // 0: 联系人, 1: 群组
}
```

**持久化策略**：使用 `vuex-persistedstate` 将 `user`、`session`、`detail` 模块持久化到 localStorage，刷新页面不丢失状态。

---

## 🔌 WebSocket 实时通信

### 连接管理 (`client/websocket.js`)
```javascript
// 连接 WebSocket
connect(token) {
  const socket = new SockJS(`${baseURL}/api/ws?token=${token}`);
  this.stompClient = Stomp.over(socket);
  this.stompClient.connect({}, onConnected, onError);
}

// 订阅个人消息队列
subscribe() {
  this.stompClient.subscribe('/user/queue/msg', (message) => {
    const msg = JSON.parse(message.body);
    // 添加到对应会话，更新未读数
  });
}
```

### 统一订阅管理 (`client/subscriptionManager.js`)
集中管理所有 WebSocket 订阅，避免组件重复订阅：

| 订阅频道 | 用途 |
|---------|------|
| `/user/queue/msg` | 用户私聊消息 |
| `/user/queue/request` | 好友请求消息 |
| `/topic/group/{groupId}` | 群聊消息 |

**核心功能：**
- 登录时统一初始化所有订阅
- 页面刷新时自动恢复订阅（通过 localStorage 恢复 token）
- 群聊消息去重（过滤自己发送的消息）
- 提供订阅/取消订阅群聊的方法

### 自动重连机制
```javascript
// 指数退避策略
calculateReconnectDelay() {
  const delay = this.minReconnectDelay * Math.pow(2, this.reconnectAttempts);
  return Math.min(delay, this.maxReconnectDelay); // 1s ~ 30s
}
```

**重连流程：**
1. WebSocket 连接断开 → 触发 `onDisconnect`
2. 计算重连间隔（指数退避：1s → 2s → 4s → ... → 30s）
3. 尝试重新连接
4. 连接成功 → 恢复所有订阅 → 更新会话列表

### 消息流程
1. 用户发送消息 → 调用 `/api/message/send` REST API
2. 后端通过 WebSocket 推送给接收方
3. `subscriptionManager` 接收实时消息 → 分发到对应处理器
4. 更新本地会话列表和消息历史
5. 更新未读消息角标

### 群聊消息去重
群聊场景下，自己发送的消息会被后端广播回来，通过判断 `fromUserId` 过滤：
```javascript
if (data.msg && data.msg.fromUserId === currentUser?.userId) {
  return; // 跳过自己发送的消息
}
```

---

## ⚙️ 环境配置

### 开发环境 (.env.development)
```env
VITE_API_BASE_URL=http://192.168.10.6:8001
VITE_WS_URL=ws://192.168.10.6:8001/api/ws
VITE_PORT=8002
```

### 生产环境 (.env.production)
```env
VITE_API_BASE_URL=https://api.yourdomain.com
VITE_WS_URL=wss://api.yourdomain.com/api/ws
```

### Vite 配置 (`vite.config.js`)
```javascript
export default defineConfig({
  plugins: [vue()],
  server: {
    host: '0.0.0.0',   // 允许局域网访问
    port: 8002,
    proxy: {
      '/api': {
        target: 'http://localhost:8001',
        changeOrigin: true
      }
    }
  },
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})
```

---

## 🚢 构建与部署

### 构建命令
```bash
npm run build    # 生产构建（默认输出到 dist/）
npm run preview  # 本地预览构建结果
```

### 部署方式

#### Nginx 配置示例
```nginx
server {
    listen 80;
    server_name chat.yourdomain.com;
    root /var/www/webchat/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://backend-server:8001/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /ws/ {
        proxy_pass http://backend-server:8001/ws/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

#### Docker 部署
```dockerfile
FROM node:18-alpine as build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
```

---

## ✨ 项目特色

- 🎙️ **原生语音录制**：利用浏览器 MediaRecorder API，无需第三方库
- 😊 **表情快捷输入**：Emoji 面板，提升聊天趣味性
- 📱 **响应式设计**：一套代码同时适配桌面和手机（@media 768px）
  - 桌面端：左右分栏布局
  - 移动端：底部 TabBar + 滑动返回手势
- 🔌 **WebSocket 实时推送**：毫秒级消息送达，支持断线重连
  - **统一订阅管理**：集中管理所有消息订阅，避免重复订阅
  - **自动重连机制**：指数退避策略（1s~30s），刷新自动恢复
  - **消息去重**：群聊场景自动过滤自己发送的消息
- 💾 **状态持久化**：刷新页面会话不丢失，用户体验连贯
- 🎨 **微信风格 UI**：气泡布局、绿色主题色、侧边栏深色
  - "我的"页面（用户头像、昵称、功能菜单）
  - 朋友圈页面（带返回按钮）
- 🛡️ **Token 自动管理**：请求拦截器自动注入，路由守卫防未登录
- ⚡ **Vite 极速开发**：冷启动 < 1s，HMR 毫秒级响应
- 🧩 **高组件化**：30+ 可复用组件，职责清晰，易于维护

---

## 📅 后续规划

- [ ] 消息撤回与编辑
- [ ] 群组管理功能（创建群、邀请成员、踢人）
- [ ] 好友申请与处理
- [ ] 消息搜索（聊天记录检索）
- [ ] 深色主题切换
- [ ] 桌面通知（Notification API）
- [ ] PWA 支持（离线可用）
- [ ] 视频通话（WebRTC）集成

---

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request。请确保：

1. 代码使用 ESLint + Prettier 格式化
2. 新功能包含必要的注释
3. 提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/)

```bash
# 安装依赖后运行 lint
npm run lint
npm run format
```

---

## 📄 许可证

[MIT License](LICENSE) © 2025 WebChat Contributors

---

> 💡 **提示**：生产环境请将 `baseURL` 改为实际域名，并启用 HTTPS/WSS 加密传输。