docs: update task #54 path recovery evidence

docs/task/54-修复实时监看按需拉流循环等待.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Task-54-修复实时监看按需拉流循环等待
 wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Task-54-%E4%BF%AE%E5%A4%8D%E5%AE%9E%E6%97%B6%E7%9B%91%E7%9C%8B%E6%8C%89%E9%9C%80%E6%8B%89%E6%B5%81%E5%BE%AA%E7%8E%AF%E7%AD%89%E5%BE%85.-
-wiki_revision: bdeca60040f62df75a8138491cb30939172b6b73
-synchronized_at: 2026-08-13T13:32:00Z
+wiki_revision: ff79f9dbc718ae570b01dace25304379124a99b4
+synchronized_at: 2026-08-13T14:05:00Z
 <!-- gitea-wiki-mirror:end -->
 
 # 54 修复实时监看按需拉流循环等待
@@ -27,12 +27,16 @@ MediaMTX 使用按需拉流时，必须先有播放器读取路径才会连接
 - 会话查询通过只读媒体端口刷新控制器状态，把等待状态安全收敛为可播放或需要处理，不重新应用路径配置。
 - 播放器包装接口覆盖全局嵌入策略为 `SAMEORIGIN`，并用 CSP `frame-ancestors 'self'` 限制为 Sense 同源页面；其他接口继续保持 `X-Frame-Options: DENY`。
 - iframe 导航无法附加 API 客户端的 `X-Product` 头，因此播放器路由改用窄导航认证：有效 Sense 会话 Cookie、媒体读取权限、`Sec-Fetch-Site: same-origin`、`Sec-Fetch-Mode: navigate` 和 `Sec-Fetch-Dest: iframe` 必须同时满足。普通 API 的产品头要求保持不变。
+- MediaMTX 路径首次配置使用 add，已存在时使用 replace；控制 API 刚启动尚未监听时限时等待。
+- Sense 完成数据库迁移后自动恢复所有 `desired=running` 路径；路径不存在显式标记为配置失败，不再误报 waiting。
 - 继续保持 `sourceOnDemand`，无人观看时不占用摄像机连接与转码资源。
 - 真实环境验证过程中发现已保存的 RTSP 凭据被摄像机拒绝（401）；已通过现有 Sense 接口使用本地已获授权配置修正运行数据，未把凭据写入仓库、工单、Wiki 或日志证据。
 
 ## 修改文件
 
-- `Sense/server/app/sense/media/service.go`、`route_port.go`：增加只读状态刷新能力。
+- `Sense/server/app/sense/media/service.go`、`route_port.go`：增加只读状态刷新、缺失状态和启动恢复能力。
+- `Sense/server/app/sense/adapters/mediamtx/client.go`、`client_test.go`：实现 add/replace 幂等语义并等待控制 API 就绪。
+- `Sense/server/cmd/sense/{modules_media.go,root.go}`、`internal/platform/app.go`：在迁移完成后执行媒体路径恢复。
 - `Sense/server/app/sense/media/service_test.go`：验证刷新状态且不重复配置路径。
 - `Sense/server/app/sense/liveview/service.go`：查询会话时刷新媒体状态。
 - `Sense/server/app/sense/liveview/http.go`、`http_test.go`：允许并验证播放器包装页仅同源嵌入。
@@ -52,6 +56,8 @@ MediaMTX 使用按需拉流时，必须先有播放器读取路径才会连接
 | 不泄露摄像机凭据和源地址 | 通过 |
 | 播放器可被 Sense 同源嵌入且其他页面仍禁止嵌入 | 通过，运行包接口响应头验证通过 |
 | iframe 不带 `X-Product` 时仍能安全认证 | 通过，同源 iframe + 有效 Cookie 返回 200；跨站返回 401；普通 API 缺少产品头返回 401 |
+| MediaMTX 冷启动后恢复 Sense 路径 | 通过，配置列表自动出现 2 条 `sourceOnDemand` 路径，无需手工对账 |
+| 两条摄像机路径可实际解码 | 通过，主码流 H.264 1920×1080 + AAC，子码流 H.264，均收到媒体字节 |
 
 ## 测试
 
@@ -61,7 +67,9 @@ MediaMTX 使用按需拉流时，必须先有播放器读取路径才会连接
 - Go 1.26.5 Windows 打包：通过。
 - 运行包响应头：播放器接口为 `SAMEORIGIN` 且包含 `frame-ancestors 'self'`；首页仍为 `DENY`。
 - 运行包浏览器式认证：不带 `X-Product`、带有效 Cookie 和同源 iframe Fetch Metadata 的播放器请求返回 200；跨站播放器与缺少产品头的普通 API 均返回 401。
-- 真实媒体链路：MediaMTX `sourceReady=true`、`readers=1`、收到媒体字节且包含 2 个轨道；Sense 会话由 `waiting` 收敛为 `ready`。
+- 冷启动恢复：MediaMTX 配置列表自动包含两条 Sense `sourceOnDemand` 路径；运行态列表也存在两条路径。
+- 真实媒体链路：主码流 H.264 1920×1080 + AAC，子码流 H.264；两条路径分别通过本机 RTSP 读取并收到媒体字节。
+- 单元测试覆盖路径首次 add、已有 replace、控制 API 启动等待、启动恢复及缺失路径不误报 waiting。
 - **未验证部分**：最终浏览器中的可视画面需要用户在当前浏览器验收；自动化已验证媒体源、读取者与会话状态收敛。
 
 ## 遗留问题
@@ -74,4 +82,5 @@ MediaMTX 使用按需拉流时，必须先有播放器读取路径才会连接
 - `b3dfd23` 更新按需拉流长期 Wiki 镜像。
 - `3696442` 允许播放器包装页仅被 Sense 同源嵌入。
 - `8bf9a6d` 支持同源播放器导航认证并保持普通 API 产品边界。
+- `d7cd3a5` 恢复 MediaMTX 按需路径并处理启动竞态。