Nexus/docs/design/specs/2026-06-01-terminal-spa-iteration-design.md

终端页 SPA 迭代设计

日期: 2026-06-01
路由: /app/#/terminal（?server_id=&path=）

背景

Vue TerminalPage 已具备多标签 WebSSH、重连、快捷命令等能力，但存在：

1. v-main 未限定高度，终端区域在部分视口下高度为 0 或过小
2. 从服务器页带 server_id 跳转时，若已在终端路由则不会新建/切换会话（无 watch）
3. WebSocket URL 与 useWebSocket 构建方式不一致，VITE_API_BASE=/api 时 dev 可能异常
4. 无「连接中」态，失败时仅禁用发送按钮
5. path 查询参数仅全局生效，多标签会重复 cd
6. Ctrl+L 向 shell 发送 clear\r 非标准清屏

方案

项	做法
布局	App.vue 对 /terminal 路由给 v-main 增加 nexus-terminal-main（100dvh - app-bar + flex）
WS URL	新增 utils/wsUrl.ts，与告警 WS 同源规则
路由	watch(route.query)：server_id / path / new_tab
会话	TermSession.pendingPath、status（connecting/connected/error）
空状态	无会话时内嵌服务器列表 +「选择服务器」
清屏	Ctrl+L 仅 term.clear() + 可选 \x0c

验收

• #/terminal?server_id=8 首屏终端区域占满内容区且可输入
• 已在 #/terminal 时从服务器点「终端」能切换/新建会话
• #/terminal?server_id=8&path=/var/log 首包后自动 cd
• 断线显示重连 overlay；手动断开不自动重连
• 生产 wss://host/ws/terminal/{id}?token=… 可连