docs: 归档工单 #68 待验收证据

docs/task/68-Sense单路实时监看与播放状态反馈.md

@@ -0,0 +1,74 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Task-68-Sense单路实时监看与播放状态反馈
+wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Task-68-Sense%E5%8D%95%E8%B7%AF%E5%AE%9E%E6%97%B6%E7%9B%91%E7%9C%8B%E4%B8%8E%E6%92%AD%E6%94%BE%E7%8A%B6%E6%80%81%E5%8F%8D%E9%A6%88.-
+wiki_revision: 9e23cebb9bf4d9f7fd0de838cba860147b96468f
+synchronized_at: 2026-08-14T10:56:37Z
+<!-- gitea-wiki-mirror:end -->
+
+# 68 Sense单路实时监看与播放状态反馈
+
+- 类型：需求
+- 所属 Epic：#7
+- 所属 MVP / 版本：#8
+- 状态：待验收
+- 日期：2026-08-14
+- Gitea 工单：https://git.ilapage.cn/ila/yovision/issues/68
+- Pull Request：https://git.ilapage.cn/ila/yovision/pulls/86
+- 主项目：Sense
+
+## 背景与目标
+
+在 #67 已对账的 MediaMTX 路径上，为网管和非技术人员提供设备/Profile 搜索、分页和单路实时查看。Brain、Bell 不启动时可独立运行；页面不得暴露摄像头凭据、RTSP URI或内部媒体路径。
+
+## 最终方案
+
+- 后端在 `app/sense/liveview` 建立只含展示字段的分页投影，最多返回 50 条，不把 16/128 路变成硬上限。
+- 登录用户选择一路后创建 192 位随机播放能力；令牌绑定用户、同用户只保留一个会话，认证轮询时按 2 分钟无活动窗口续期，关闭页面后失效。
+- JSON 只返回同源 `/api/v1/liveview/player/<能力>`；包装页使用 no-store、no-referrer、SAMEORIGIN 与 CSP，再嵌入浏览器可达的 MediaMTX WebRTC 页面。
+- 默认由 Sense 请求主机推导 WebRTC 8889；反向代理、HTTPS 或端口映射通过安全的 `SENSE_MEDIAMTX_WEBRTC_PUBLIC_BASE` 显式配置。
+- 复用 GoAdmin Router/JWT/Casbin/迁移/动态菜单及 go-admin-ui BasicLayout、Axios、Element Plus 搜索/表格/分页/Dialog/Tag/权限按钮；只新增播放器业务组件。
+- waiting 时先保留 iframe 建立 reader；ready 后持续轮询，20 秒未就绪显示超时。关闭 Dialog 或组件卸载会清理 iframe、轮询和超时计时器。
+- 状态区分 loading、waiting、ready、authentication_failed、stream_not_found、service_unavailable、timeout、expired、offline 和 stopped，并给出可行动中文处理建议。
+
+## 修改文件
+
+- `Sense/server/app/sense/liveview/**`：分页投影、短期会话、播放器包装页及测试。
+- `Sense/server/app/admin/router/sense_liveview.go`：认证 API 与短期播放器路由。
+- `Sense/server/cmd/migrate/migration/version/*liveview*`：菜单、角色和 Casbin 权限。
+- `Sense/ui/src/views/sense/liveview/**`、`api/sense/liveview.js`：实时监看页面、状态映射和请求。
+- `Sense/ui/src/components/sense/video-player/**`：唯一业务专用播放器组件。
+- `Sense/ui/tests/unit/sense/liveview*.spec.js`：状态、iframe 和页面计时器生命周期测试。
+- Wiki Architecture、Business Rules、Local Development、Troubleshooting：架构、安全、配置、验证和排错。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 设备与 Profile 可搜索、分页并进入单路实时监看 | 通过 |
+| waiting 且播放 URL 有效时建立 reader，不循环等待 | 通过；真实合成 WebRTC smoke |
+| 加载、空、认证失败、stream not found、重连和超时可区分 | 通过 |
+| 页面不暴露凭据与内部文件路径 | 通过；DTO/JSON 测试与扫描 |
+| 128 路使用分页且不同时创建全部播放器 | 通过；服务端最大页 50，前端单 Dialog |
+| 通用组件无重复实现且播放器风格一致 | 通过 |
+
+## 测试
+
+- `go test ./...`、`go vet ./...`、`go build ./...`：通过。
+- `go test -race ./app/sense/liveview`：通过。
+- PostgreSQL 17 隔离迁移：1 个菜单、9 条 Casbin 策略、1 条迁移记录通过；临时实例/schema/目录已清理。
+- 前端 lint：0 error，32 条冻结上游 warning。
+- 前端单测：13 suites、40 tests 通过。
+- 前端生产构建：通过，6 条冻结上游 warning。
+- MediaMTX v1.19.3 + FFmpeg 合成 RTSP + Edge WebRTC：640×360、readyState=4、自动播放中；临时进程、配置和自动证书已清理。
+- Wiki 页面读取确认并成功导出镜像。
+- **未验证部分**：客户真实摄像机、现场防火墙/证书、实际部署反向代理和客户目标浏览器，需授权现场验收。
+
+## 风险与回退
+
+回退 PR #86 可移除实时监看入口、会话 API、菜单和播放器组件；#67 的设备/Profile、媒体路由与 MediaMTX 生命周期不受影响。内存会话随进程退出自然失效，无数据库业务数据需要回滚。
+
+## 相关提交
+
+- `c63c623` feat: 重建 Sense 单路实时监看 (#68)
+- `a279a1e` docs: 记录 Sense 实时监看架构 (#68)

wiki-docs.json

@@ -119,6 +119,10 @@
     {
       "page": "Task-67-Sense视频服务生命周期与状态对账",
       "path": "docs/task/67-Sense视频服务生命周期与状态对账.md"
+    },
+    {
+      "page": "Task-68-Sense单路实时监看与播放状态反馈",
+      "path": "docs/task/68-Sense单路实时监看与播放状态反馈.md"
     }
   ]
 }