# 版本检测组件 (VersionChecker)

## 功能说明

`VersionChecker` 是一个自动版本检测组件，用于检测应用是否有新版本可用，并在检测到新版本时提示用户更新。

## 主要特性

- ✅ **自动检测**：应用启动时自动开始版本检测
- ✅ **定时检查**：可配置检查间隔（默认 1 分钟）
- ✅ **智能提示**：检测到新版本时显示友好的更新提示
- ✅ **防重复**：可配置通知冷却时间，避免频繁提示
- ✅ **页面感知**：页面隐藏时暂停检查，显示时恢复检查
- ✅ **资源清理**：页面卸载时自动清理定时器
- ✅ **错误处理**：网络错误时不会影响应用正常运行

## 使用方法

### 基本使用

```tsx
import VersionChecker from '@/components/VersionChecker';

const App = () => {
  const currentBuildTime = process.env.REACT_APP_BUILD_TIME;

  return (
    <div>
      {/* 你的应用内容 */}
      <VersionChecker currentBuildTime={currentBuildTime} />
    </div>
  );
};
```

### 高级配置

```tsx
<VersionChecker
  currentBuildTime={process.env.REACT_APP_BUILD_TIME}
  checkInterval={30 * 1000} // 30秒检查一次
  notificationCooldown={10 * 60 * 1000} // 10分钟内不重复提示
/>
```

## 参数说明

| 参数                   | 类型               | 必填 | 默认值   | 说明                 |
| ---------------------- | ------------------ | ---- | -------- | -------------------- |
| `currentBuildTime`     | `string \| number` | ✅   | -        | 当前应用的构建时间戳 |
| `checkInterval`        | `number`           | ❌   | `60000`  | 检查间隔（毫秒）     |
| `notificationCooldown` | `number`           | ❌   | `300000` | 通知冷却时间（毫秒） |

## 工作原理

1. **版本信息获取**：通过 `fetch('/version.json')` 获取远程版本信息
2. **版本比较**：比较远程 `buildTimestamp` 与本地 `REACT_APP_BUILD_TIME`
3. **更新提示**：当远程时间戳大于本地时间戳时，显示更新通知
4. **用户操作**：用户可选择立即更新或稍后提醒

## 版本信息格式

组件期望的 `version.json` 文件格式：

```json
{
  "productId": "go-pmp",
  "version": "1.0.0 build:ABC123（UTC+8 北京时间: 2024-01-15 14:30:25）",
  "buildTime": "2024-01-15 14:30:25",
  "buildTimestamp": 1705302625,
  "environment": "prod"
}
```

## 通知样式

更新通知使用 Ant Design 的 `notification` 组件，包含：

- **标题**：发现新版本
- **描述**：检测到新版本 v{version}，建议刷新页面获取最新功能
- **操作按钮**：
  - 立即更新：刷新页面
  - 稍后提醒：关闭通知

## 环境变量要求

确保在构建时设置了 `REACT_APP_BUILD_TIME` 环境变量：

```bash
# 构建时设置
REACT_APP_BUILD_TIME=1705302625 npm run build
```

## 注意事项

1. **网络环境**：需要能够访问 `/version.json` 文件
2. **缓存控制**：请求时添加时间戳参数避免缓存
3. **错误处理**：网络错误不会影响应用正常运行
4. **性能考虑**：检查频率不宜过高，建议 1 分钟以上
5. **用户体验**：通知冷却时间建议设置合理，避免频繁打扰

## 调试

在浏览器控制台中可以看到详细的日志信息：

```
版本检查已启动，检查间隔: 60秒
获取到版本信息: {productId: "go-pmp", version: "1.0.0", ...}
版本检查 - 远程构建时间: 1705302625
版本检查 - 本地构建时间: 1705300000
检测到新版本可用
```

## 故障排除

### 1. 版本检测不工作

- 检查 `REACT_APP_BUILD_TIME` 环境变量是否正确设置
- 检查 `/version.json` 文件是否可以正常访问
- 查看浏览器控制台是否有错误信息

### 2. 频繁提示更新

- 调整 `notificationCooldown` 参数
- 检查版本信息中的 `buildTimestamp` 是否正确

### 3. 检测不到新版本

- 确认远程 `version.json` 文件已更新
- 检查 `buildTimestamp` 字段是否存在且为数字类型