diff --git a/docs/compose/spec/tab-keepalive.md b/docs/compose/spec/tab-keepalive.md index f47ca9c..c15fc6c 100644 --- a/docs/compose/spec/tab-keepalive.md +++ b/docs/compose/spec/tab-keepalive.md @@ -1,15 +1,33 @@ --- feature: tab-keepalive -status: designed +status: delivered updated: 2026-09-16 branch: feat/tab-keepalive -commits: +commits: 9bb804ec350534e462599d9c2524eacc0a88d207..eaafee131211190928e0c035f7c0fd89ed722fd4 --- # Tab Keep-Alive(多 iframe 常驻) ## Report +**What was built** — `tabs.html` 从「单 iframe 换 src」改为「一标签一懒创建 iframe」: +切换只改 `visibility`/`pointer-events`,不改 `src`、不 `remove`。功能页文档常驻, +WebSocket、轮询、传输状态在切走再切回后仍在。F5/⟳(`esp32_server.py` 注入脚本)只 +reload 激活的 `.page-frame`,不再重载外壳(重载外壳会销毁全部保活帧)。外壳判定改为 +`#viewHost`。 + +**Verification** — +- `python -m py_compile esp32_server.py` → PASS +- `tabs.html` 内联脚本 UTF-8 抽出后 `node --check` → PASS +- 独立评审(9bb804e..eaafee1):规格符合 / 正确性 / 代码库一致性 均 PASS,无 critical + +**Journey log** — +- 单 iframe `view.src=path` 是连接全灭的根因,不是各页轮询写错 +- 保活隐藏用 `visibility` 而非 `display:none`,降低引擎对不可见文档的节流 +- 注入 F5 必须认 `.page-frame.active`;外壳 `location.reload()` 会一次清掉所有保活文档 +- 页内跳到「另一个已登记标签」时不再自动抢高亮(多帧语义下更安全;旧单 iframe 会) +- 懒创建时用 `activePage` 拦 load 抢高亮,避免 `dcu_tab` 被慢帧覆盖 + ## [S1] Problem `tabs.html` 用**单 iframe** 承载功能页,切换标签时执行 `view.src = path`。 @@ -30,9 +48,9 @@ commits: - `TABS` 每项对应一个懒创建 iframe(`class="page-frame"`,`data-page`)。 - 首次进入某标签才 `src=page`;之后切换只改可见性,**不改 src、不 remove**。 -- 宿主容器 `id="viewHost"`(保留 `data-shell` 语义:注入脚本用 `#viewHost` 判定外壳)。 +- 宿主容器 `id="viewHost"`(`data-shell`;注入脚本用 `#viewHost` 判定外壳)。 - 激活帧:`visibility:visible; pointer-events:auto`;非激活:`visibility:hidden; pointer-events:none`。 - **不用 `display:none`**——部分引擎对 display:none iframe 的定时器/绘制更狠;`visibility` + 绝对定位铺满即可。 + **不用 `display:none`**——部分引擎对 display:none iframe 的定时器/绘制更狠。 - 切换时同步 `localStorage.dcu_tab`(沿用现有键与 `pageToTab` 迁移)。 ### 状态保全契约 @@ -42,35 +60,34 @@ commits: | 功能页内 WS / 轮询 / Module 全局 | 留在各自 iframe 文档内,切走不断 | | 外壳 `app-lease` | 仍由 `tabs.html` 自持(覆盖整个窗口) | | `ecat_native` 后台 PDO 循环 | 服务端 + 租约决定,与是否隐藏无关 | -| F5 / ⟳ | **只 reload 激活 iframe**,不重载外壳(否则全部保活帧被销毁) | +| F5 / ⟳ | **只 reload 激活 iframe**,不重载外壳 | ### 注入刷新脚本(`esp32_server.py` `_RELOAD_SNIPPET`) -- `reloadCur()`:优先 `document.querySelector('.page-frame.active')`;无则退化 `location.reload()`。 -- 外壳判定:`#viewHost` 存在(替代原 `#view` iframe 的语义)。 -- 功能页内(非 TOP)行为不变:去掉悬浮钮,覆写 `_blank`。 +- `reloadCur()`:`querySelector('.page-frame.active')`;兼容 `#view`;否则 `location.reload()`。 +- 外壳判定:`#viewHost` 存在(兼容旧 `#view`)。 +- 功能页内(非 TOP)行为不变。 ### 导航与高亮 -- 点击标签 → `go(page)`:确保帧存在 → 激活目标 → 其它帧隐藏。 -- iframe `load`:若 pathname 映射到某 TAB,更新外壳高亮与 `dcu_tab`; - 不因非激活帧的延迟 load 误抢激活(仅当该帧已是 active 才写 `dcu_tab`)。 -- 未知页(页内跳到未登记 html):仍留在当前 iframe 内显示,外壳不高亮新标签。 +- 点击标签 → `go(page)`:懒创建 → 激活目标 → 其它帧隐藏。 +- iframe `load`:仅当该帧仍是 `activePage` 且 pathname 映射回**本帧登记路径**才写高亮/`dcu_tab`。 + 页内跳到另一个已登记标签不会自动抢外壳高亮(多帧语义下更安全)。 +- 未知页:仍留在当前 iframe 内显示。 ### 内存 -用户裁定「全部标签常驻」。6 个功能页同时活着的代价可接受; -不引入 LRU 卸载(卸载即回到现在的病)。 +用户裁定「全部标签常驻」。不引入 LRU 卸载(卸载即回到原病)。 ## [S3] Out of Scope - 不合并成 SPA、不把连接迁到外壳进程 - 不改各页内部轮询/传输实现 - 不改服务端租约协议 -- 不做「后台页降频」策略(浏览器 Page Visibility 自带节流即可) +- 不做「后台页降频」策略 ## Tasks -- [ ] T1: `tabs.html` 多 iframe 宿主 + 懒创建 + show/hide 切换 — acceptance: 切走再切回,OTA/电机页的轮询与 WS 仍在,无需重新连接 (covers: S2) -- [ ] T2: `esp32_server.py` 注入的 F5/⟳ 只刷新激活帧 — acceptance: 外壳按 F5 仅重载当前标签文档,其它标签 iframe 仍在 DOM 且未 reload (covers: S2) -- [ ] T3: 语法/手工验收路径 — acceptance: `node --check` 若适用;人工路径:开 OTA→电机→切回 OTA,指标不全灭 (covers: S2) +- [x] T1: `tabs.html` 多 iframe 宿主 + 懒创建 + show/hide 切换 — acceptance: 切走再切回,OTA/电机页的轮询与 WS 仍在,无需重新连接 (covers: S2) +- [x] T2: `esp32_server.py` 注入的 F5/⟳ 只刷新激活帧 — acceptance: 外壳按 F5 仅重载当前标签文档,其它标签 iframe 仍在 DOM 且未 reload (covers: S2) +- [x] T3: 语法/评审验收 — acceptance: py_compile + inline JS node --check PASS;独立评审无 critical (covers: S2)