# Monitor HLS Playback Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 监控详情页可在 Chrome/Edge 真实播放 HLS，并补齐启动轮询、playUrl 续期、播放错误重建、停止直播与退出观看分离。

**Architecture:** `LivePlayer` 只负责媒体（Safari 原生 HLS / 其他动态 `import('hls.js')`）；`useMonitorLive` 管 join、phase 轮询、heartbeat、playUrl 续期、错误重试、leave/stop；`MonitorDetailPanel` 标题行加「停止直播」按钮。

**Tech Stack:** Vue 3、`hls.js`、现有 axios `src/utils/http.js`、Pinia `useUiStore`、`useMonitorLive` / `LivePlayer` / `MonitorDetailPanel`

**Spec:** `docs/superpowers/specs/2026-09-02-monitor-hls-playback-design.md`

---

## File map

| 文件 | 职责 |
|---|---|
| `package.json` / `package-lock.json` | 增加 `hls.js` |
| `src/config/urls.js` | `LIVE_SESSION` / `LIVE_STOP` |
| `src/api/live.js` | `getLiveSession` / `stopLive` |
| `src/components/LivePlayer.vue` | HLS 挂载/销毁/错误上报 |
| `src/composables/useMonitorLive.js` | 轮询、续期、重试、stop |
| `src/components/MonitorDetailPanel.vue` | 「停止直播」按钮 + emit |
| `src/views/MonitorView/MonitorView.vue` | 接线 `onPlayError` / `stopLiveStream` |

辅助约定：

- 请求：`import request from '@/utils/http'`（成功已解包 `res.data`）
- Toast / Confirm：`ui.toast(...)` / `await ui.confirm(title, desc, checks?)`
- `GET .../sessions/:id` 解包后是 **`LiveSession` 本体**（含 `phase`/`id`），不是 `{ session }`
- 本仓库无前端单测惯例：用 `npm run build` + 静态核对；不新增测试文件
- 精确 `git add`；commit 信息简短祈使句

---

### Task 1: 安装 hls.js + URL/API

**Files:**
- Modify: `package.json` / `package-lock.json`
- Modify: `src/config/urls.js`
- Modify: `src/api/live.js`

- [ ] **Step 1: 安装依赖**

```bash
npm install hls.js
```

确认 `package.json` `dependencies` 出现 `hls.js`。

- [ ] **Step 2: URL 常量**

在 `src/config/urls.js` 现有 live 段落后追加：

```js
export const LIVE_SESSION = (dockId, sessionId) => `/v1/live/${dockId}/sessions/${sessionId}`
export const LIVE_STOP = (dockId) => `/v1/live/${dockId}/stop`
```

保留现有：

```js
export const LIVE_SESSIONS = (dockId) => `/v1/live/${dockId}/sessions`
export const LIVE_PLAY_URL = (dockId) => `/v1/live/${dockId}/play-url`
export const LIVE_HEARTBEAT = (dockId, sessionId) => `/v1/live/${dockId}/sessions/${sessionId}/heartbeat`
export const LIVE_LEAVE = (dockId, sessionId) => `/v1/live/${dockId}/sessions/${sessionId}/viewers/me`
```

- [ ] **Step 3: API 封装**

`src/api/live.js` 最终应为：

```js
import request from '@/utils/http'

export function joinLive(dockId, payload = {}) {
  return request.post(`/v1/live/${dockId}/sessions`, payload)
}

export function getLiveSession(dockId, sessionId) {
  return request.get(`/v1/live/${dockId}/sessions/${sessionId}`)
}

export function getLivePlayURL(dockId, sessionId) {
  return request.get(`/v1/live/${dockId}/play-url`, {
    params: { streamSessionId: sessionId }
  })
}

export function heartbeatLive(dockId, sessionId) {
  return request.post(`/v1/live/${dockId}/sessions/${sessionId}/heartbeat`)
}

export function leaveLive(dockId, sessionId) {
  return request.delete(`/v1/live/${dockId}/sessions/${sessionId}/viewers/me`)
}

export function stopLive(dockId) {
  return request.post(`/v1/live/${dockId}/stop`)
}
```

- [ ] **Step 4: Commit**

```bash
git add package.json package-lock.json src/config/urls.js src/api/live.js
git commit -m "feat: add hls.js and live session/stop APIs"
```

---

### Task 2: LivePlayer HLS 适配

**Files:**
- Modify: `src/components/LivePlayer.vue`

- [ ] **Step 1: 重写组件（template 去掉 :src 绑定）**

完整文件：

```vue
<template>
  <div
    ref="frameEl"
    class="video-frame"
    :class="{ streaming: isLiveShell, playing: playable }"
  >
    <video
      v-if="playable"
      ref="videoEl"
      controls
      autoplay
      playsinline
    />
    <div v-else class="camera-scene">
      <div class="horizon" />
      <div class="dock-model"><span /><span /><i /></div>
    </div>

    <div class="video-overlay">
      <span>{{ cameraLabel }}</span>
      <small>{{ qualityText }}</small>
    </div>

    <div v-if="statusMessage" class="video-status">{{ statusMessage }}</div>

    <button
      class="play-control"
      type="button"
      :aria-label="active ? '关闭实时画面' : '打开实时画面'"
      @click="$emit('toggle')"
    >
      <svg><use :href="active ? '#i-stop' : '#i-play'" /></svg>
    </button>
  </div>
</template>

<script setup>
import { computed, onBeforeUnmount, ref, watch } from 'vue'

const props = defineProps({
  playUrl: { type: String, default: '' },
  phase: { type: String, default: '' },
  active: { type: Boolean, default: false },
  cameraLabel: { type: String, default: '机巢摄像头' },
})

const emit = defineEmits(['toggle', 'error'])

const frameEl = ref(null)
const videoEl = ref(null)
let hls = null
let attachSeq = 0

const playable = computed(() => props.playUrl && !props.playUrl.startsWith('fake://'))
const isLiveShell = computed(() => props.active && !playable.value)

const qualityText = computed(() => {
  if (playable.value) return 'LIVE · 播放中'
  if (props.playUrl?.startsWith('fake://')) return '控制面已验证'
  if (props.phase === 'starting' || props.phase === 'reconnecting') return '启动中'
  if (props.phase === 'failed') return '启动失败'
  return 'H.264 · 720P'
})

const statusMessage = computed(() => {
  if (playable.value) return ''
  if (props.phase === 'starting' || props.phase === 'reconnecting') return '正在等待直播流就绪'
  if (props.phase === 'failed') return '直播启动失败'
  if (props.playUrl?.startsWith('fake://')) return '控制面已验证，未配置本地媒体流'
  if (props.active) return '暂无实时视频数据'
  return ''
})

function destroyPlayer() {
  if (hls) {
    hls.destroy()
    hls = null
  }
  const video = videoEl.value
  if (video) {
    video.removeAttribute('src')
    video.load()
  }
}

async function attachPlayer(url) {
  const seq = ++attachSeq
  destroyPlayer()
  if (!url || url.startsWith('fake://')) return

  await Promise.resolve()
  const video = videoEl.value
  if (!video || seq !== attachSeq) return

  video.addEventListener('error', () => {
    if (seq !== attachSeq) return
    emit('error')
  }, { once: true })

  if (video.canPlayType('application/vnd.apple.mpegurl')) {
    video.src = url
    try { await video.play() } catch (_) {}
    return
  }

  const { default: Hls } = await import('hls.js')
  if (seq !== attachSeq) return
  if (!Hls.isSupported()) {
    emit('error')
    return
  }

  hls = new Hls({ enableWorker: true, lowLatencyMode: true })
  hls.on(Hls.Events.ERROR, (_event, data) => {
    if (seq !== attachSeq) return
    if (data?.fatal) emit('error')
  })
  hls.loadSource(url)
  hls.attachMedia(video)
  hls.on(Hls.Events.MANIFEST_PARSED, () => {
    if (seq !== attachSeq) return
    video.play().catch(() => {})
  })
}

watch(
  () => props.playUrl,
  (url) => {
    if (playable.value) attachPlayer(url)
    else destroyPlayer()
  },
  { immediate: true }
)

onBeforeUnmount(() => {
  attachSeq += 1
  destroyPlayer()
})

function requestFullscreen() {
  const el = playable.value ? videoEl.value : frameEl.value
  if (!el?.requestFullscreen) return false
  el.requestFullscreen()
  return true
}

defineExpose({ requestFullscreen, frameEl, videoEl })
</script>
```

若原文件另有 `<style>`，保留原样式块；上例仅替换 template + script。

- [ ] **Step 2: 静态核对**

1. 无 `:src="playUrl"`
2. 有 `import('hls.js')`
3. `onBeforeUnmount` destroy
4. fatal / video error → `emit('error')`

- [ ] **Step 3: Commit**

```bash
git add src/components/LivePlayer.vue
git commit -m "feat: play HLS in LivePlayer via hls.js"
```

---

### Task 3: useMonitorLive 轮询 / 续期 / 重试 / stop

**Files:**
- Modify: `src/composables/useMonitorLive.js`

- [ ] **Step 1: 整文件替换**

```js
import { computed, reactive } from 'vue'
import {
  getLivePlayURL,
  getLiveSession,
  heartbeatLive,
  joinLive,
  leaveLive,
  stopLive,
} from '@/api/live'

const PHASE_POLL_MS = 2500
const PHASE_TIMEOUT_MS = 60_000
const PLAY_RETRY_MAX = 3
const PLAY_EXPIRE_FALLBACK_SEC = 270
const PLAY_REFRESH_LEAD_MS = 30_000

export function useMonitorLive({ getDockId, ui, getLivePlayer }) {
  const live = reactive({
    session: null,
    dockId: '',
    playUrl: '',
    playUrlExpiresAt: 0,
    heartbeatTimer: null,
    phasePollTimer: null,
    playRefreshTimer: null,
    playRetryCount: 0,
    phasePollStartedAt: 0,
  })

  const livePhaseText = computed(() => {
    if (!live.session) return '待机'
    const phase = live.session.phase
    if (phase === 'streaming') return live.playUrl.startsWith('fake://') ? '模拟直播' : '直播中'
    if (phase === 'starting') return '启动中'
    if (phase === 'reconnecting') return '重连中'
    if (phase === 'stopping') return '停止中'
    if (phase === 'failed') return '启动失败'
    return '已停止'
  })

  const canFullscreenLive = computed(() => !!live.playUrl && !live.playUrl.startsWith('fake://'))

  function clearTimers() {
    window.clearTimeout(live.heartbeatTimer)
    window.clearTimeout(live.phasePollTimer)
    window.clearTimeout(live.playRefreshTimer)
    live.heartbeatTimer = null
    live.phasePollTimer = null
    live.playRefreshTimer = null
  }

  function resetLocal() {
    clearTimers()
    live.session = null
    live.dockId = ''
    live.playUrl = ''
    live.playUrlExpiresAt = 0
    live.playRetryCount = 0
    live.phasePollStartedAt = 0
  }

  function toggleLive() {
    if (live.session) closeLive()
    else openLive()
  }

  function fullscreenLive() {
    if (!canFullscreenLive.value) {
      ui.toast('当前无可全屏播放的视频流')
      return
    }
    const ok = getLivePlayer()?.requestFullscreen?.()
    if (!ok) ui.toast('当前浏览器不支持全屏')
  }

  async function openLive() {
    const dockId = getDockId?.()
    if (!dockId) return
    try {
      const result = await joinLive(dockId)
      live.session = result.session
      live.dockId = dockId
      live.playUrl = ''
      live.playUrlExpiresAt = 0
      live.playRetryCount = 0
      scheduleLiveHeartbeat(result.leaseExpiresAt)
      if (result.session.phase === 'streaming') {
        try {
          await refreshPlayURL()
        } catch (e) {
          await onPlayError(e)
        }
      } else {
        startPhasePolling()
      }
    } catch (e) {
      ui.toast(e.message || '打开直播失败')
    }
  }

  function startPhasePolling() {
    window.clearTimeout(live.phasePollTimer)
    live.phasePollStartedAt = Date.now()
    live.phasePollTimer = window.setTimeout(pollPhaseOnce, PHASE_POLL_MS)
  }

  async function pollPhaseOnce() {
    if (!live.dockId || !live.session?.id) return
    if (Date.now() - live.phasePollStartedAt > PHASE_TIMEOUT_MS) {
      ui.toast('直播启动超时')
      await closeLive(false)
      return
    }
    const sessionId = live.session.id
    try {
      // http 解包后是 LiveSession 本体，不是 { session }
      const session = await getLiveSession(live.dockId, sessionId)
      if (!live.session || live.session.id !== sessionId) return
      live.session = session
      if (session.phase === 'streaming') {
        window.clearTimeout(live.phasePollTimer)
        live.phasePollTimer = null
        try {
          await refreshPlayURL()
        } catch (e) {
          await onPlayError(e)
        }
        return
      }
      if (session.phase === 'failed' || session.phase === 'stopped') {
        ui.toast(session.phase === 'failed' ? '直播启动失败' : '直播已停止')
        await closeLive(false)
        return
      }
    } catch (e) {
      ui.toast(e.message || '查询直播状态失败')
      await closeLive(false)
      return
    }
    live.phasePollTimer = window.setTimeout(pollPhaseOnce, PHASE_POLL_MS)
  }

  // 成功返回 true；失败抛错，由调用方决定是否 onPlayError（避免互相递归）
  async function refreshPlayURL() {
    if (!live.dockId || !live.session?.id) return false
    const sessionId = live.session.id
    const play = await getLivePlayURL(live.dockId, sessionId)
    if (!live.session || live.session.id !== sessionId) return false
    live.playUrl = play.playUrl || ''
    const nowSec = Math.floor(Date.now() / 1000)
    live.playUrlExpiresAt = Number(play.expiresAt) || nowSec + PLAY_EXPIRE_FALLBACK_SEC
    live.playRetryCount = 0
    schedulePlayRefresh()
    return true
  }

  function schedulePlayRefresh() {
    window.clearTimeout(live.playRefreshTimer)
    if (!live.playUrl || live.playUrl.startsWith('fake://') || !live.playUrlExpiresAt) return
    const delay = Math.max(5000, live.playUrlExpiresAt * 1000 - Date.now() - PLAY_REFRESH_LEAD_MS)
    live.playRefreshTimer = window.setTimeout(async () => {
      try {
        await refreshPlayURL()
      } catch (e) {
        await onPlayError(e)
      }
    }, delay)
  }

  function scheduleLiveHeartbeat(expiresAt) {
    window.clearTimeout(live.heartbeatTimer)
    const delay = Math.max(5000, (Number(expiresAt) * 1000 - Date.now()) / 2)
    live.heartbeatTimer = window.setTimeout(async () => {
      if (!live.dockId || !live.session?.id) return
      try {
        const result = await heartbeatLive(live.dockId, live.session.id)
        if (!live.session) return
        live.session = result.session
        scheduleLiveHeartbeat(result.leaseExpiresAt)
        if (result.session.phase === 'streaming' && !live.playUrl) {
          try {
            await refreshPlayURL()
          } catch (e) {
            await onPlayError(e)
          }
        }
      } catch (e) {
        ui.toast(e.message || '直播观看已结束')
        await closeLive(false)
      }
    }, delay)
  }

  async function onPlayError(err) {
    if (!live.session) return
    if (live.playRetryCount >= PLAY_RETRY_MAX) {
      ui.toast(err?.message || '播放失败')
      live.playRetryCount = 0
      return
    }
    live.playRetryCount += 1
    try {
      await refreshPlayURL()
    } catch (e) {
      if (live.playRetryCount >= PLAY_RETRY_MAX) {
        ui.toast(e?.message || err?.message || '播放失败')
        live.playRetryCount = 0
      } else {
        await onPlayError(e)
      }
    }
  }

  async function closeLive(sendRequest = true) {
    const session = live.session
    const dockId = live.dockId
    resetLocal()
    if (sendRequest && session && dockId) {
      try {
        await leaveLive(dockId, session.id)
      } catch (_) {}
    }
  }

  async function stopLiveStream() {
    if (!live.session || !live.dockId) return
    const dockId = live.dockId
    const session = live.session
    const ok = await ui.confirm(
      '确认停止直播？',
      '停止后所有正在观看的用户都会失去画面。',
      ['确认停止推流', '影响当前所有观看者']
    )
    if (!ok) return
    try {
      await stopLive(dockId)
      resetLocal()
      try {
        await leaveLive(dockId, session.id)
      } catch (_) {}
      ui.toast('直播已停止')
    } catch (e) {
      ui.toast(e.message || '停止直播失败')
    }
  }

  return {
    live,
    livePhaseText,
    canFullscreenLive,
    toggleLive,
    fullscreenLive,
    openLive,
    closeLive,
    stopLiveStream,
    onPlayError,
  }
}
```

- [ ] **Step 2: 静态核对**

导出含 `stopLiveStream`、`onPlayError`；phase 轮询用 `getLiveSession`；`refreshPlayURL` 自身 catch 不回调 `onPlayError`；`closeLive` 清三类 timer。

- [ ] **Step 3: Commit**

```bash
git add src/composables/useMonitorLive.js
git commit -m "feat: poll live phase and renew HLS play URLs"
```

---

### Task 4: 详情面板停止按钮 + Monitor 接线

**Files:**
- Modify: `src/components/MonitorDetailPanel.vue`
- Modify: `src/views/MonitorView/MonitorView.vue`

- [ ] **Step 1: 详情面板标题行加按钮**

实时画面标题操作区改为：

```vue
<div class="section-title">
  <h3>实时画面</h3>
  <div>
    <span class="live-dot" :class="{ active: liveView.active }" />
    <b>{{ liveView.phaseText }}</b>
    <button
      v-if="liveView.active"
      class="text-button"
      type="button"
      title="停止直播推流"
      @click="$emit('stop-live')"
    >停止直播</button>
    <button class="icon-button" type="button" title="全屏播放" :disabled="!liveView.canFullscreen" @click="$emit('fullscreen-live')">
      <svg><use href="#i-maximize" /></svg>
    </button>
  </div>
</div>
```

`defineEmits` 增加 `'stop-live'`：

```js
const emit = defineEmits([
  'close',
  'open-device-detail',
  'select-parent',
  'toggle-live',
  'fullscreen-live',
  'live-error',
  'stop-live',
  'open-dock-status',
  'open-mission-detail',
  'update:controlExpanded',
  'command',
])
```

- [ ] **Step 2: MonitorView 解构与事件**

```js
const {
  live,
  livePhaseText,
  canFullscreenLive,
  toggleLive,
  fullscreenLive,
  closeLive,
  stopLiveStream,
  onPlayError,
} = useMonitorLive({
  getDockId: () => selectedDock.value?.dockId,
  ui,
  getLivePlayer: () => detailPanelRef.value?.livePlayerRef,
})
```

面板事件：

```vue
@toggle-live="toggleLive"
@fullscreen-live="fullscreenLive"
@live-error="onPlayError"
@stop-live="stopLiveStream"
```

替换原来的 `@live-error="ui.toast('视频播放失败')"`。

- [ ] **Step 3: Commit**

```bash
git add src/components/MonitorDetailPanel.vue src/views/MonitorView/MonitorView.vue
git commit -m "feat: wire stop-live and play error rebuild"
```

---

### Task 5: 构建验收

**Files:** 无新文件

- [ ] **Step 1: 构建**

```bash
npm run build
```

Expected: exit 0（chunk 变大警告可忽略）。

- [ ] **Step 2: 静态字符串核对**

```bash
rg -n "hls\\.js|getLiveSession|stopLive|stopLiveStream|onPlayError|playUrlExpiresAt|停止直播" \
  src/components/LivePlayer.vue \
  src/composables/useMonitorLive.js \
  src/components/MonitorDetailPanel.vue \
  src/views/MonitorView/MonitorView.vue \
  src/api/live.js \
  src/config/urls.js
```

Expected: 均有命中；`LivePlayer.vue` 无 `:src="playUrl"`。

- [ ] **Step 3: 手工联调清单（有后端时）**

1. Chrome：监控选机巢 → 播放 → 数秒内出画
2. 启动中：Network 可见 ~2.5s 一次 `GET .../sessions/:id`
3. 中心关闭：只 `DELETE .../viewers/me`，无 `/stop`
4. 「停止直播」：确认后 `POST .../stop`，画面清空
5. 可选：失效 playUrl → 自动重拉 ≤3 次

- [ ] **Step 4: 无额外改动则结束；有修复则补 commit**

---

## Spec coverage

| Spec 项 | Task |
|---|---|
| hls.js + Safari 原生 | Task 1 + 2 |
| 2.5s phase 轮询 / 60s 超时 | Task 3 |
| playUrl `expiresAt` 提前 30s 刷新 | Task 3 |
| 播放错误重建 ≤3 | Task 3 + 4 |
| 退出观看 vs 停止直播 | Task 3 + 4 |
| Media 页不动 | 无对应 task（刻意） |
| 动态 import hls.js | Task 2 |
| `GetLiveSession` 返回本体 | Task 3 |

## Self-review notes

- 无 TBD/占位
- API：`stopLive`；composable：`stopLiveStream` — 贯穿 Task 3/4
- `refreshPlayURL` 失败抛错，由调用方 `onPlayError`；二者不在 catch 里无界递归
- Monitor `@live-error` 改接 `onPlayError`，不再直接 toast
- 无前端单测文件（仓库惯例）