feat: 实现 MediaMTX 分片分配与故障范围可观察 (#77)

Sense/ui/src/api/sense/media-shard.js

@@ -0,0 +1,13 @@
+import request from '@/utils/request'
+
+export function listMediaShards() {
+  return request({ url: '/api/v1/media-shards', method: 'get' })
+}
+
+export function getMediaShard(id) {
+  return request({ url: `/api/v1/media-shards/${encodeURIComponent(id)}`, method: 'get' })
+}
+
+export function preflightMediaShard(id) {
+  return request({ url: `/api/v1/media-shards/${encodeURIComponent(id)}/migration-preflight`, method: 'get' })
+}

Sense/ui/src/views/sense/media-shard/index.vue

@@ -0,0 +1,65 @@
+<template>
+  <BasicLayout>
+    <template #wrapper>
+      <el-card class="box-card">
+        <div class="page-header">
+          <div><h3>媒体分片</h3><p>查看 MediaMTX 分片容量、路径归属与故障影响。故障不会自动迁移路径。</p></div>
+          <el-button :icon="Refresh" :loading="loading" @click="load">刷新状态</el-button>
+        </div>
+
+        <el-alert v-if="summary.failed" type="error" :closable="false" show-icon class="status-alert">
+          <template #title>{{ summary.failed }} 个媒体分片异常，影响 {{ summary.impactedPaths }} 条路径</template>
+          路径仍保持原分片归属，便于定位故障范围；请先查看详情，不要直接变更生产配置。
+        </el-alert>
+
+        <el-row :gutter="12" class="summary-row" aria-label="媒体分片概览">
+          <el-col v-for="item in summaryCards" :key="item.label" :xs="12" :sm="6"><div class="summary-item"><span>{{ item.label }}</span><strong :class="item.className">{{ item.value }}</strong></div></el-col>
+        </el-row>
+
+        <el-table v-loading="loading" :data="shards" border stripe empty-text="暂无媒体分片运行记录">
+          <el-table-column label="分片" min-width="180"><template #default="scope"><strong>{{ scope.row.name }}</strong><div class="muted">{{ scope.row.id }} · {{ stateLabel(scope.row.mode) }}</div></template></el-table-column>
+          <el-table-column label="状态" width="112" align="center"><template #default="scope"><el-tag :type="stateType(scope.row.status)">{{ stateLabel(scope.row.status) }}</el-tag><div class="muted">{{ freshnessText(scope.row) }}</div></template></el-table-column>
+          <el-table-column label="已分配 / 容量" min-width="190"><template #default="scope"><div>{{ scope.row.assignedPaths }} / {{ scope.row.capacity }} 条路径</div><el-progress :percentage="usagePercent(scope.row)" :status="usagePercent(scope.row) >= 90 ? 'warning' : ''" /></template></el-table-column>
+          <el-table-column label="剩余容量" width="110" align="center"><template #default="scope">{{ scope.row.remaining }}</template></el-table-column>
+          <el-table-column prop="detail" label="运行说明" min-width="210" show-overflow-tooltip />
+          <el-table-column label="最近探测" min-width="170"><template #default="scope">{{ formatTime(scope.row.lastProbeAt) }}</template></el-table-column>
+          <el-table-column label="操作" width="156" fixed="right"><template #default="scope"><el-button v-permisaction="['sense:media-shard:detail']" type="primary" link @click="openDetail(scope.row.id)">影响详情</el-button><el-button v-permisaction="['sense:media-shard:preflight']" type="primary" link @click="openPreflight(scope.row.id)">迁移预检</el-button></template></el-table-column>
+        </el-table>
+      </el-card>
+
+      <el-dialog v-model="detailOpen" title="分片故障影响" width="min(880px, calc(100vw - 24px))" :close-on-click-modal="false">
+        <template v-if="selected"><el-descriptions :column="2" border><el-descriptions-item label="分片">{{ selected.name }}（{{ selected.id }}）</el-descriptions-item><el-descriptions-item label="状态"><el-tag :type="stateType(selected.status)">{{ stateLabel(selected.status) }}</el-tag></el-descriptions-item><el-descriptions-item label="路径占用">{{ selected.assignedPaths }} / {{ selected.capacity }}</el-descriptions-item><el-descriptions-item label="运行说明">{{ selected.detail }}</el-descriptions-item></el-descriptions>
+          <h4>受影响设备与 Profile</h4><el-table :data="selected.impact || []" border empty-text="此分片暂无路径归属"><el-table-column prop="deviceName" label="设备" min-width="150"><template #default="scope">{{ scope.row.deviceName || scope.row.deviceId }}<div class="muted">{{ scope.row.location || '未填写位置' }}</div></template></el-table-column><el-table-column prop="profileToken" label="Profile" min-width="130" /><el-table-column prop="path" label="媒体路径" min-width="180" /><el-table-column prop="actual" label="最近状态" width="120" /></el-table>
+        </template><template #footer><el-button @click="detailOpen = false">关闭</el-button></template>
+      </el-dialog>
+
+      <el-dialog v-model="preflightOpen" title="跨分片迁移预检（只读）" width="min(720px, calc(100vw - 24px))" :close-on-click-modal="false">
+        <template v-if="preflight"><el-alert :type="preflight.ready ? 'warning' : 'error'" :title="preflightConclusion(preflight)" :closable="false" show-icon /><el-descriptions :column="2" border class="preflight-summary"><el-descriptions-item label="源分片">{{ preflight.sourceShardId }}</el-descriptions-item><el-descriptions-item label="候选目标">{{ preflight.targetShardName || '无可用目标' }}</el-descriptions-item><el-descriptions-item label="影响路径">{{ preflight.impactedPaths }}</el-descriptions-item><el-descriptions-item label="执行授权">未授权</el-descriptions-item></el-descriptions><el-table :data="preflight.checks || []" border><el-table-column label="结果" width="90"><template #default="scope"><el-tag :type="scope.row.passed ? 'success' : 'danger'">{{ scope.row.passed ? '通过' : '未通过' }}</el-tag></template></el-table-column><el-table-column prop="name" label="检查项" width="130" /><el-table-column prop="detail" label="说明" min-width="260" /></el-table></template>
+        <template #footer><span class="read-only-note">本页面不会修改任何路径归属。</span><el-button @click="preflightOpen = false">关闭</el-button></template>
+      </el-dialog>
+    </template>
+  </BasicLayout>
+</template>
+
+<script setup>
+import { computed, onMounted, reactive, ref } from 'vue'
+import { Refresh } from '@element-plus/icons-vue'
+import { ElMessage } from 'element-plus'
+import { getMediaShard, listMediaShards, preflightMediaShard } from '@/api/sense/media-shard'
+import { freshnessText, preflightConclusion, stateLabel, stateType, usagePercent } from './mediaShardState'
+
+defineOptions({ name: 'SenseMediaShard' })
+const loading = ref(false); const shards = ref([]); const selected = ref(null); const preflight = ref(null); const detailOpen = ref(false); const preflightOpen = ref(false)
+const summary = reactive({ total: 0, available: 0, failed: 0, configuredCapacity: 0, assignedPaths: 0, impactedPaths: 0 })
+const summaryCards = computed(() => [{ label: '分片总数', value: summary.total }, { label: '可用 / 异常', value: `${summary.available} / ${summary.failed}`, className: summary.failed ? 'danger-number' : 'success-number' }, { label: '已分配 / 总容量', value: `${summary.assignedPaths} / ${summary.configuredCapacity}` }, { label: '故障影响', value: `${summary.impactedPaths} 条路径`, className: summary.impactedPaths ? 'danger-number' : '' }])
+function unwrap(response) { return response?.data?.data ?? response?.data ?? response }
+function formatTime(value) { return value ? new Date(value).toLocaleString('zh-CN', { hour12: false }) : '—' }
+async function load() { loading.value = true; try { const payload = unwrap(await listMediaShards()) || {}; shards.value = payload.list || []; Object.assign(summary, payload.summary || {}) } catch (error) { ElMessage.error(error.message || '媒体分片加载失败') } finally { loading.value = false } }
+async function openDetail(id) { try { selected.value = unwrap(await getMediaShard(id)); detailOpen.value = true } catch (error) { ElMessage.error(error.message || '分片详情加载失败') } }
+async function openPreflight(id) { try { preflight.value = unwrap(await preflightMediaShard(id)); preflightOpen.value = true } catch (error) { ElMessage.error(error.message || '迁移预检失败') } }
+onMounted(load)
+</script>
+
+<style scoped>
+.page-header{display:flex;align-items:flex-start;justify-content:space-between;gap:16px}.page-header h3{margin:0 0 6px}.page-header p{margin:0;color:#909399}.status-alert{margin:16px 0}.summary-row{margin:16px 0 20px}.summary-item{display:flex;align-items:center;justify-content:space-between;min-height:72px;padding:12px 16px;border:1px solid #ebeef5;border-radius:4px}.summary-item span{color:#606266}.summary-item strong{font-size:20px}.success-number{color:#67c23a}.danger-number{color:#f56c6c}.muted{color:#909399;font-size:12px;margin-top:4px}.preflight-summary{margin:16px 0}.read-only-note{margin-right:16px;color:#909399}@media(max-width:768px){.page-header{align-items:stretch;flex-direction:column}.summary-item{margin-bottom:8px;min-height:64px}.page-header .el-button{min-height:44px}}
+</style>

Sense/ui/src/views/sense/media-shard/mediaShardState.js

@@ -0,0 +1,6 @@
+const labels = { running: '运行正常', failed: '运行异常', unknown: '等待探测', disabled: '已停用', managed: 'Sense 托管', external: '外部运行' }
+export function stateLabel(value) { return labels[value] || value || '未知' }
+export function stateType(value) { return ({ running: 'success', failed: 'danger', unknown: 'warning', disabled: 'info' })[value] || 'info' }
+export function usagePercent(item) { const capacity = Number(item?.capacity) || 0; return capacity > 0 ? Math.min(100, Math.round((Number(item.assignedPaths) || 0) * 100 / capacity)) : 0 }
+export function freshnessText(item) { if (!item?.lastProbeAt) return '尚未探测'; return item.stale ? '状态已陈旧' : '刚刚更新' }
+export function preflightConclusion(result) { if (!result) return ''; if (!result.ready) return '当前不满足迁移前置条件'; return '预检通过，但仍需单独建立高风险工单并人工确认' }

Sense/ui/tests/unit/sense/mediaShardApi.spec.js

@@ -0,0 +1,8 @@
+jest.mock('@/utils/request', () => jest.fn(config => config))
+import request from '@/utils/request'
+import { getMediaShard, listMediaShards, preflightMediaShard } from '@/api/sense/media-shard'
+
+describe('Sense media shard API', () => {
+  beforeEach(() => request.mockClear())
+  test('exposes only read operations and safely encodes ids', () => { expect(listMediaShards()).toEqual({ url: '/api/v1/media-shards', method: 'get' }); expect(getMediaShard('a/b')).toEqual({ url: '/api/v1/media-shards/a%2Fb', method: 'get' }); expect(preflightMediaShard('a b')).toEqual({ url: '/api/v1/media-shards/a%20b/migration-preflight', method: 'get' }); expect(request).toHaveBeenCalledTimes(3) })
+})

Sense/ui/tests/unit/sense/mediaShardState.spec.js

@@ -0,0 +1,7 @@
+import { freshnessText, preflightConclusion, stateLabel, stateType, usagePercent } from '@/views/sense/media-shard/mediaShardState'
+
+describe('Sense media shard presentation state', () => {
+  test('uses clear operator-facing labels and non-color-only status', () => { expect(stateLabel('failed')).toBe('运行异常'); expect(stateType('failed')).toBe('danger'); expect(stateLabel('external')).toBe('外部运行') })
+  test('derives usage from configured capacity instead of a fixed tier', () => { expect(usagePercent({ assignedPaths: 7, capacity: 23 })).toBe(30); expect(usagePercent({ assignedPaths: 99, capacity: 0 })).toBe(0) })
+  test('makes stale data and read-only preflight explicit', () => { expect(freshnessText({ lastProbeAt: '2026-08-28T00:00:00Z', stale: true })).toBe('状态已陈旧'); expect(preflightConclusion({ ready: true })).toContain('高风险工单'); expect(preflightConclusion({ ready: false })).toContain('不满足') })
+})