npm package: @kenny_zx/websocket-version-checker
Description: 基于WebSocket的实时版本更新检查和通知系统，支持Vue 2/3和原生JavaScript
Author: Zhang Xuan
Latest version: 1.1.2

# WebSocket Version Checker

基于WebSocket的实时版本更新检查和通知系统，支持Vue 2/3和原生JavaScript。

## ✨ 特性

- 🚀 **实时推送** - 基于WebSocket，版本更新延迟<1秒
- 📦 **低资源消耗** - 降低98%的请求量和带宽
- 🔄 **自动重连** - 网络断开自动恢复
- 💓 **心跳检测** - 保持连接活性
- 🎯 **多环境支持** - 区分开发/UAT/生产环境
- 🛠️ **框架无关** - 支持Vue 2/3、React、原生JS
- 📱 **跨平台** - 浏览器、桌面应用、移动端

## 📦 安装

```bash
npm install @kenny_zx/websocket-version-checker socket.io-client
```

## 🚀 快速开始

### Vue 2 + Element UI

```javascript
// main.js
import Vue from 'vue'
import ElementUI from 'element-ui'
import { createVue2Plugin } from '@kenny_zx/websocket-version-checker'
import io from 'socket.io-client'

Vue.use(ElementUI)

// 安装版本检查插件
Vue.use(createVue2Plugin({
  websocketUrl: 'http://127.0.0.1:13481',
  systemName: '您的系统名称'
}))

// App.vue
export default {
  mounted() {
    // 连接并开始监听
    this.$versionChecker.connect(io)
  },
  beforeDestroy() {
    // 断开连接
    this.$versionChecker.disconnect()
  }
}
```

### 原生JavaScript

```javascript
import { WebSocketVersionChecker } from '@kenny_zx/websocket-version-checker'
import io from 'socket.io-client'

// 创建检查器
const checker = new WebSocketVersionChecker({
  websocketUrl: 'http://127.0.0.1:13481',
  systemName: '您的系统名称'
}, (versionData, isFirstRun, checkerInstance) => {
  // 自定义通知处理
  console.log('收到版本更新:', versionData)
  
  if (versionData.status === 'package_uploaded') {
    alert(`包上传成功！\n下载地址：${versionData.download_url}`)
  } else {
    if (confirm(`发现新版本 ${versionData.version_number}，是否立即更新？`)) {
      checkerInstance.setLocalVersion(versionData.version_number)
      window.location.reload()
    }
  }
})

// 连接
checker.connect(io)
```

## 📖 API文档

### WebSocketVersionChecker

#### 构造函数

```javascript
new WebSocketVersionChecker(config, notificationHandler)
```

**参数：**

- `config` (Object) - 配置对象
  - `websocketUrl` (String) - WebSocket服务器地址，默认 `http://127.0.0.1:13481`
  - `systemName` (String) - 系统名称，默认 `系统名称`
  - `heartbeatInterval` (Number) - 心跳间隔（毫秒），默认 `30000`
  - `maxFailCount` (Number) - 最大失败次数，默认 `3`
  - `localVersionKey` (String) - 本地版本存储键，默认 `system_version_number`
  - `ignoredVersionKey` (String) - 忽略版本存储键，默认 `system_ignored_version`

- `notificationHandler` (Function) - 自定义通知处理器
  - 参数1: `versionData` - 版本数据对象
  - 参数2: `isFirstRun` - 是否首次运行
  - 参数3: `checkerInstance` - 检查器实例

#### 方法

**connect(io)**
- 连接到WebSocket服务器
- 参数：`io` - Socket.IO客户端实例

**disconnect()**
- 断开WebSocket连接

**reconnect(io)**
- 重新连接WebSocket服务器
- 参数：`io` - Socket.IO客户端实例

**subscribe()**
- 订阅版本更新

**unsubscribe()**
- 取消订阅版本更新

**getLocalVersion()**
- 获取本地保存的版本号
- 返回：`String`

**setLocalVersion(version)**
- 保存版本号到本地
- 参数：`version` - 版本号字符串

**getIgnoredVersion()**
- 获取被忽略的版本号
- 返回：`String`

**setIgnoredVersion(version)**
- 保存忽略的版本号
- 参数：`version` - 版本号字符串

**clearIgnoredVersion()**
- 清除忽略的版本号

**compareVersion(newVersion, oldVersion)**
- 比较版本号大小
- 返回：`Boolean` - 新版本是否大于旧版本

## 🎯 使用场景

### 场景1: 开发环境直接部署

```javascript
// 后端创建版本记录
{
  systemName: '您的系统',
  versionNumber: 'v2026.0128.1530',
  versionName: '开发环境部署',
  status: 'released',  // ← 实际部署
  // ...
}

// 前端收到推送，显示"发现新版本"通知
// 用户点击"立即更新"，页面自动刷新
```

### 场景2: UAT/生产环境包上传

```javascript
// 后端创建版本记录
{
  systemName: '您的系统',
  versionNumber: 'v2026.0128.1747',
  versionName: 'UAT环境包上传',
  status: 'package_uploaded',  // ← 包上传
  downloadUrl: 'http://example.com/dist.zip'
}

// 前端收到推送，显示"包上传成功"通知
// 显示下载地址，用户点击"我知道了"关闭
```

## 🔄 版本数据格式

```javascript
{
  version_number: 'v2026.0128.1530',     // 版本号
  version_name: '测试环境部署',          // 版本名称
  description: '部署到测试服务器',        // 描述
  release_notes: '1. feat: xxx\n2. fix: xxx',  // 发布说明
  release_by: '张三',                    // 发布人
  status: 'released',                    // 状态: released | package_uploaded
  download_url: 'http://...',            // 下载地址（可选）
  release_date: '2026-01-28T15:30:00'   // 发布时间
}
```

## 🎨 自定义通知UI

### Element UI样式

```javascript
import { Notification } from 'element-ui'

const notificationHandler = (versionData, isFirstRun, checker) => {
  if (isFirstRun) {
    Notification.info({
      title: '当前系统版本',
      message: `版本号：${versionData.version_number}`
    })
  } else {
    Notification.warning({
      title: '发现新版本',
      message: `版本号：${versionData.version_number}`
    })
  }
}

const checker = new WebSocketVersionChecker(config, notificationHandler)
```

### 原生浏览器通知

```javascript
const notificationHandler = (versionData, isFirstRun, checker) => {
  if (Notification.permission === 'granted') {
    new Notification('发现新版本', {
      body: `版本号：${versionData.version_number}`,
      icon: '/favicon.ico'
    })
  }
}
```

## 🧪 完整示例

查看 `examples/` 目录：

- `vue2-element-ui/` - Vue 2 + Element UI完整示例
- `vue3-element-plus/` - Vue 3 + Element Plus示例
- `vanilla-js/` - 原生JavaScript示例
- `react/` - React示例

## 🔧 后端集成

### Egg.js + Socket.IO

```javascript
// app/io/controller/versionController.js
async subscribe() {
  const { ctx } = this
  const { systemName } = ctx.args[0] || {}
  
  const room = systemName ? `version:${systemName}` : 'version:all'
  await ctx.socket.join(room)
  
  // 发送当前版本
  const latestVersion = await ctx.service.systemVersion.getLatestVersion(systemName)
  ctx.socket.emit('version:current', {
    code: 200,
    data: latestVersion
  })
}

// 创建版本后推送
async createVersion() {
  const result = await service.systemVersion.createVersion(versionData)
  
  // WebSocket推送
  app.io.of('/').to(`version:${systemName}`).emit('version:update', {
    code: 200,
    data: result
  })
}
```

## 📊 性能优势

| 指标 | 轮询方式 | WebSocket方式 | 提升 |
|-----|---------|--------------|------|
| 延迟 | 10-30秒 | <1秒 | **30倍** |
| 请求量 | 120次/小时 | 2次/小时 | **降低98%** |
| 带宽 | 360KB/小时 | 6KB/小时 | **降低98%** |

## 🐛 故障排查

### 问题1: 连接失败

**检查：**
```bash
curl http://127.0.0.1:13481
```

**解决：**
- 确保后端服务正在运行
- 检查防火墙设置
- 验证WebSocket端口可访问

### 问题2: 收不到推送

**检查：**
```javascript
console.log(checker.isConnected)  // 应该是 true
console.log(checker.isSubscribed)  // 应该是 true
```

**解决：**
- 确认系统名称匹配
- 检查WebSocket连接状态
- 手动重连：`checker.reconnect(io)`

## 📄 许可证

MIT

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 📮 联系方式

- 作者：Zhang Xuan
- Email: your-email@example.com
- GitHub: https://github.com/zhangxuan/websocket-version-checker