docs: define settings navigation performance fix

2026-07-30 22:01:31 +08:00
parent d60cff1dd8
commit 3bbd227c58
1 changed files with 54 additions and 0 deletions
@@ -0,0 +1,54 @@
+# 设置、导航与事件流性能修复设计
+
+日期：2026-07-30
+
+## 目标
+
+消除进入设置页和切换顶部菜单时的明显停顿，让实时连接状态及时进入已连接状态，并把顶层设置收敛为仅包含系统与安全配置。
+
+## 已确认根因
+
+- 顶部“设置”当前进入 `/settings/instances`。该页面先读取实例列表，再为每个实例请求资源数据，造成与安全设置无关的请求放大。
+- 顶部导航使用普通链接，`main.tsx` 只读取一次 `window.location.pathname`。每次菜单切换都会整页重载，重新初始化 React、数据源和事件流。
+- 控制平面已经刷新 SSE 上游响应头，但 Canary 网关代理写入下游响应头后没有立即刷新。没有事件正文时，浏览器的 `fetch` 一直不能进入 `open` 状态，因此右上角长期显示“正在连接”。
+
+## 路由与设置
+
+- 顶部“设置”链接直接指向 `/settings/system`。
+- 顶层设置页面只渲染密码保护与 HTTP/HTTPS 安全信息，不再显示设置子导航。
+- `/settings/instances` 作为旧地址重定向到 `/settings/system`，避免旧书签落入不存在页面。
+- `/settings/instances/:instanceId` 继续保留实例编辑器，只从节点详情的“编辑实例”入口访问。
+- 不删除实例编辑组件、实例创建流程或相关 API。
+
+## 同页导航
+
+- 新增一个小型浏览器路径 Hook，维护当前 `pathname`。
+- 拦截无修饰键、同源、当前窗口的站内链接：调用 `history.pushState` 并更新路径，不触发整页重载。
+- 外链、下载链接、`target` 链接、不同源链接和带修饰键点击继续使用浏览器默认行为。
+- 监听 `popstate`，保证浏览器前进和后退可用。
+- 页面切换后将主内容聚焦并恢复到页面顶部，保持键盘与阅读器导航可预期。
+- `AppShell` 在菜单切换期间保持挂载，因此默认数据源和事件流客户端不会重建。
+
+## 事件流
+
+- Canary 网关收到上游响应头后，在写入下游响应头时立即调用 `flushHeaders()`。
+- 继续以流方式转发正文，不缓存 SSE，不修改认证头、游标或重连策略。
+- 没有任何事件时，浏览器仍能立即收到 `200` 与 `text/event-stream`，右上角切换为“实时连接正常”。
+- 真正断线时仍显示“正在重新连接”，不通过隐藏状态标签掩盖故障。
+
+## 测试
+
+- 路由测试验证 `/settings/instances` 重定向到 `/settings/system`，实例编辑路由不变。
+- AppShell 测试验证顶栏设置链接指向安全设置，且设置子导航不再出现。
+- 浏览器路径 Hook 测试验证站内导航、前进后退和不应拦截的链接。
+- Canary 网关测试构造“只刷新响应头、不发送事件正文”的 SSE 上游，验证下游请求在正文到达前即可获得响应。
+- 集成或浏览器测试验证菜单切换不造成页面重载、事件订阅不重建，设置页不请求 Fleet 数据。
+- 最终在本地 `8789` 验证设置页响应、菜单切换和实时连接状态。
+
+## 非目标
+
+- 不引入第三方路由库。
+- 不删除实例编辑路由或实例创建功能。
+- 不改变事件内容、事件游标、重连退避或认证模型。
+- 不通过轮询替代 SSE。
+- 不重构节点、自动化或安全设置页面的视觉设计。