movecheck/README-萤石云对接.md

# 萤石云对接快速参考

> **快速参考文档** - 5分钟了解核心要点

---

## 🚀 快速开始

### 1. 文件清单
```
✅ src/pages/visual/index.vue              # 监控页面
✅ src/components/EzvizVideoPlayerSimple.vue  # 播放器组件
✅ src/static/html/ezviz-iframe.html       # iframe HTML
✅ src/utils/ezvizTokenManager.js          # Token管理
```

### 2. 配置清单
```json
// pages.json - 横屏配置
{
  "path": "pages/visual/index",
  "style": {
    "pageOrientation": "landscape"  // 横屏
  }
}

// manifest.json - 内存配置
{
  "app-plus": {
    "compatible": {
      "largeHeap": true  // 512MB
    }
  }
}
```

### 3. 核心代码（3步完成）

```javascript
// 步骤1: 获取 AccessToken
const accessToken = await tokenManager.getValidAccessToken()

// 步骤2: 准备配置
const config = {
  accessToken: accessToken,
  play_url: "ezopen://open.ys7.com/K74237657/1.hd.live"
}

// 步骤3: 初始化播放器
this.ezstate = true
await this.$nextTick()
this.$refs.playerVideoRef.initEzuikit(config)
```

---

## 📐 技术架构

```
Vue页面 → web-view → 本地HTML → 萤石云iframe
  ↓           ↓          ↓            ↓
管理状态   URL传参    解析参数    官方播放器
```

---

## 🔑 关键参数

### ezopen地址格式
```
ezopen://open.ys7.com/{设备序列号}/{通道号}.{清晰度}.live

示例：
ezopen://open.ys7.com/K74237657/1.hd.live
                      ↑          ↑ ↑
                   设备序列号   通道 清晰度(hd/sd)
```

### AccessToken获取
```javascript
// API: https://open.ys7.com/api/lapp/token/get
// 自动管理（推荐）
const token = await tokenManager.getValidAccessToken()

// 有效期：2小时
// 自动缓存：提前1小时刷新
```

---

## 🐛 常见问题速查

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 黑屏 | AccessToken过期 | `tokenManager.getValidAccessToken()` |
| 崩溃 | 内存不足 | 使用iframe方案 + largeHeap:true |
| 变形 | 容器比例错误 | padding-top: 56.25% (16:9) |
| ref undefined | 组件未渲染 | 先设置ezstate=true，再await $nextTick() |
| 加载慢 | 高清占用大 | 切换标清: .sd.live |

---

## 💡 核心解决方案

### 问题1：OutOfMemoryError
```javascript
// ❌ 不要加载本地SDK（~20MB）
<script src="/static/js/ezuikit.js"></script>

// ✅ 使用官方iframe（内存占用↓90%）
<iframe src="https://open.ys7.com/ezopen/h5/iframe?..."></iframe>
```

### 问题2：画面变形
```scss
// ✅ 使用padding-top锁定16:9
.video-content {
  &::before {
    content: '';
    display: block;
    padding-top: 56.25%; /* 16:9 */
  }
}
```

### 问题3：组件引用错误
```javascript
// ✅ 正确顺序
this.ezstate = true          // 1. 先渲染
await this.$nextTick()       // 2. 等待DOM
this.$refs.player.init()     // 3. 再调用
```

---

## 📊 性能对比

| 方案 | 内存占用 | 稳定性 | 加载速度 |
|------|---------|--------|----------|
| 本地SDK | 256MB+ | ❌ 崩溃 | 慢 |
| **iframe（最终）** | **~80MB** | **✅ 稳定** | **快** |

---

## 🎯 一键复制代码

### 播放器初始化（完整版）
```javascript
async getVideoData() {
  try {
    // 1. 获取token
    let accessToken
    try {
      accessToken = await tokenManager.getValidAccessToken()
    } catch (error) {
      accessToken = "backup-token"  // 备用
    }
    
    // 2. 配置参数
    const config = {
      accessToken: accessToken,
      play_url: "ezopen://open.ys7.com/K74237657/1.hd.live"
    }
    
    // 3. 渲染组件
    this.ezstate = true
    await this.$nextTick()
    
    // 4. 初始化播放器
    if (this.$refs.playerVideoRef) {
      this.$refs.playerVideoRef.initEzuikit(config)
    }
    
  } catch (error) {
    console.error('播放器初始化失败:', error)
  }
}
```

### 刷新播放器
```javascript
refresh() {
  this.$refs.playerVideoRef.refresh()
}
```

### 切换清晰度
```javascript
// 高清
play_url: "ezopen://open.ys7.com/K74237657/1.hd.live"

// 标清（省流量）
play_url: "ezopen://open.ys7.com/K74237657/1.sd.live"
```

---

## 📱 调试技巧

### 查看日志
```bash
# BlueStacks + ADB
adb logcat | grep -i "console\|chromium"
```

### Chrome远程调试
```
chrome://inspect/#devices
```

### 关键日志点
```javascript
console.log('AccessToken:', token.substring(0, 20))
console.log('PlayUrl:', play_url)
console.log('组件ref:', this.$refs.playerVideoRef)
```

---

## 🔗 相关链接

- 📖 [完整指南](./萤石云APP对接完整指南.md)
- 🌐 [萤石云开放平台](https://open.ys7.com/)
- 📚 [Uni-app文档](https://uniapp.dcloud.net.cn/)

---

## ✅ 检查清单

部署前确认：

```
□ 已配置 AppKey 和 AppSecret
□ 已获取设备序列号和验证码
□ pages.json 配置横屏 (pageOrientation: landscape)
□ manifest.json 启用大内存 (largeHeap: true)
□ 所有必需文件已添加
□ tokenManager 正常工作
□ 测试播放功能正常
```

---

**最后更新：** 2025-10-06  
**快速参考版本：** v1.0  

---

需要详细说明？查看 → [萤石云APP对接完整指南.md](./萤石云APP对接完整指南.md)