docs: 记录按需拉流状态刷新 (#54)

2026-08-13 14:59:34 +08:00
parent 8d4e4c2e84
commit b3dfd239ed
3 changed files with 7 additions and 6 deletions
@@ -2,7 +2,7 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Architecture-and-Code-Map
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Architecture-and-Code-Map.-
-wiki_revision: 9aa7be78bf7e988594d38e9e6b264db4edf71fc9
+wiki_revision: f0459c19263f3701e38c3f5501587c6b9d8c37cf
 synchronized_at: 2026-08-13T04:16:00Z
 <!-- gitea-wiki-mirror:end -->

@@ -103,7 +103,7 @@ Sense 后端功能以 `Sense/server/app/sense/` 为根，并通过 `Sense/server
 - `device/`：Device 台账、状态、分页和 AES-256-GCM 凭据保险箱；ONVIF 与 RTSP 凭据可分离或显式复用，读取模型只返回两组凭据是否已配置。
 - `adapters/onvif/`、`adapters/rtsp/`、`admission/`：获准网卡上的受控发现、手工 ONVIF 接入、Media 服务发现、Basic/Digest 认证、Profile/StreamUri 读取和 RTSP 验证。跨主机 Media 地址固定回用户已授权的 Device Service origin；跨主机 RTSP URI 只替换为授权主机并保留报告端口与路径。接入结果和脱敏 Profile 持久化到 PostgreSQL，重启后可恢复。
 - `adapters/mediamtx/`、`media/`：外部 MediaMTX 进程所有权、localhost Control API、媒体期望态与实际态对账；接入验证出可用 Profile 后自动按 Device/Profile 幂等建立并对账媒体路径。
- `liveview/`：绑定当前用户、最长两分钟的单路播放会话；列表投影设备名称、位置、码流名称与用途，只在内部保留 ID，不暴露源 URI 或摄像机秘密。
+- `liveview/`：绑定当前用户、最长两分钟的单路播放会话；列表投影设备名称、位置、码流名称与用途，只在内部保留 ID，不暴露源 URI 或摄像机秘密。`waiting` 会话立即加载播放器以触发 MediaMTX 按需拉流，会话轮询只读刷新媒体实际状态。
 - `area/`：归一化多边形/方向警戒线、不可变版本、并发版本校验和分辨率变化后的重新校准。

 前端在 `Sense/ui/src/{api,views,router/modules,components}/sense/` 使用对应模块；通用页面复用 Element Plus 表单、表格、分页、Dialog、Tag 和应用容器，只为播放器与区域画布新增局部业务组件。项目内 `identity.RecordAudit`、`device.ReadRTSPCredential`、`device.Describe`、`admission.VerifiedProfile`、`media.PlaybackRoute` 和 `area.ExportCurrent` 是窄适配端口，不是跨项目契约。
@@ -2,7 +2,7 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Business-Rules-and-Glossary
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Business-Rules-and-Glossary.-
-wiki_revision: 00c48e986cb9d75daae0b6a7eafe0529e3aba36a
+wiki_revision: 0790c5444ac4541f32e69a7d2b69fc52e97c0e49
 synchronized_at: 2026-08-13T04:16:00Z
 <!-- gitea-wiki-mirror:end -->

@@ -78,7 +78,7 @@ synchronized_at: 2026-08-13T04:16:00Z
 - **Profile**：主辅码流按分辨率分类并使用 RTSP 凭据分别验证；脱敏 Stream URI、验证状态和时间持久化，重启后保留。至少一个 Profile 验证成功后 Device 进入 `active`；认证失败、不可达、超时与校时问题使用可定位状态。
 - **自动媒体路径**：接入检查中每个验证成功的 Profile 都按 Device/Profile 幂等建立并立即对账媒体路径；MediaMTX 不可用不回滚摄像机接入，接入结果记录“需要处理”并引导到视频服务排错。
 - **MediaMTX**：保持外部进程。Sense 只停止自己启动并持有句柄的进程，最多自动重启三次；摄像机凭据只在 localhost 控制请求中瞬时组装，不持久化、不返回。
- **播放会话**：由当前 Sense 用户创建，最长两分钟；实时监看以设备名称、位置和主/子码流等业务标签供用户选择，内部 ID 只用于系统关联；设备分页和媒体路径不以 16 路作为硬上限，页面一次只打开一路流。
+- **播放会话**：由当前 Sense 用户创建，最长两分钟；实时监看以设备名称、位置和主/子码流等业务标签供用户选择，内部 ID 只用于系统关联；`waiting` 表示等待第一个播放器触发按需拉流，不是播放失败，播放器连接后会话轮询刷新为实际状态；设备分页和媒体路径不以 16 路作为硬上限，页面一次只打开一路流。
 - **区域版本**：坐标为 0..1 归一化值，并绑定 Device、Profile、宽高。每次发布或停用形成新版本；范围、点数、自交、退化、方向和期望版本由后端校验。Profile 分辨率变化后旧版本必须标记为需要重新校准。
 <!-- sense-mvp:end -->

@@ -2,7 +2,7 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Troubleshooting
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting
-wiki_revision: caa6704ed8aecb77e829504c2a739e30f5404aa9
+wiki_revision: 7e22db66d04b9af794bcd82fab7147c793570011
 synchronized_at: 2026-08-13T04:16:00Z
 <!-- gitea-wiki-mirror:end -->

@@ -55,7 +55,8 @@ synchronized_at: 2026-08-13T04:16:00Z
 | 接入成功但提示“媒体服务未就绪” / `process_failed` | 接入资料和 Profile 已保存，实时监看路径也已建立；检查仓库外 `SENSE_MEDIAMTX_BINARY`、基础配置和进程退出原因，修复后到视频服务重新对账。达到三次重启上限后需人工处理。 |
 | `apply_failed` / `unconverged` | 检查 localhost Control API 是否启用并为 v3；确认媒体路径和外部进程状态。 |
 | 实时监看没有设备 | 先在视频接入完成一次检查；系统会自动建立媒体路径。若已接入仍为空，检查接入结果的媒体状态和视频服务对账。 |
-| 画面等待、断开或会话过期 | 查看实时监看中的业务设备名和码流状态，必要时到视频服务执行对账后重新连接；播放会话最长两分钟。 |
+| 实时监看持续“等待拉流” | `waiting` 会话应立即加载播放器以触发按需拉流。若连接后仍等待，检查 MediaMTX 路径 readers 和源状态；`401 Unauthorized` 表示摄像机拒绝当前 RTSP 凭据，应在设备管理修正凭据后重新执行视频接入，不能把凭据写入日志或地址。 |
+| 画面等待、断开或会话过期 | 查看实时监看中的业务设备名和码流状态；会话轮询会只读刷新 MediaMTX 实际状态，无需手工对账。播放会话最长两分钟。 |
 | 区域提示需要重新校准 | Profile 分辨率已变化，按新画面重新绘制并发布新版本，不能静默复用旧坐标。 |

 自动测试不访问真实摄像头或未授权网络。PostgreSQL、MediaMTX、目标浏览器与实验室摄像机的联合验证必须在获准部署环境完成。