# 2026-06-02 — 终端页重构 T1–T5

## 摘要

将 `TerminalPage.vue`（约 1244 行单文件）拆分为 Composable + 6 个子组件，修复 markRaw、per-session overlay、计时器泄漏风险，并去除命令栏 DOM 查询与重复服务器选择器。

## 动机

- xterm/WebSocket/ResizeObserver 被 Vue 深度代理导致潜在渲染异常与内存问题（C1）
- 断开 overlay 为全局状态，切换 Tab 时非活动会话断开无提示（C2）
- Uptime 计时器存于外部 Map，清理路径不一致（C3）
- 单文件不可维护，命令栏依赖 CSS 类名查询 DOM（M1/M2）
- 空状态与对话框重复实现服务器列表（M3）

## 涉及文件

### 新建

- `frontend/src/composables/terminal/types.ts`
- `frontend/src/composables/terminal/termNativeStore.ts`
- `frontend/src/composables/terminal/useTerminalSettings.ts`
- `frontend/src/composables/terminal/useTerminalCmdBar.ts`
- `frontend/src/composables/terminal/useTerminalSessions.ts`
- `frontend/src/components/terminal/TerminalTabBar.vue`
- `frontend/src/components/terminal/TerminalToolbar.vue`
- `frontend/src/components/terminal/TerminalArea.vue`
- `frontend/src/components/terminal/TerminalCmdBar.vue`
- `frontend/src/components/terminal/TerminalQuickBar.vue`
- `frontend/src/components/terminal/TerminalServerPicker.vue`

### 修改

- `frontend/src/pages/TerminalPage.vue` — 组合层（约 280 行，含样式）
- `frontend/src/components/ShellHighlightField.vue` — `defineExpose` 供命令栏复制/粘贴

### 设计文档

- `docs/design/specs/2026-06-02-terminal-refactor-design.md`
- `docs/design/plans/2026-06-02-terminal-refactor.md`

## 关键实现

| 阶段 | 内容 |
|------|------|
| T1 | `termNativeStore` + `markRaw` 存放 xterm/FitAddon/ResizeObserver；uptime/ping/reconnect 计时器归入 native |
| T2 | 每会话 `showOverlay` / `overlayMsg` / `reconnectCountdown`；关闭末 Tab 显示空状态而非 overlay |
| T3 | `useTerminalSettings`、`useTerminalCmdBar`、`useTerminalSessions` |
| T4 | 6 个 `components/terminal/*` 子组件 |
| T5 | `TerminalCmdBar` 经 `ShellHighlightField` expose 操作输入；`TerminalServerPicker` 统一 inline/dialog |

## 迁移 / 重启

- 仅前端：需 `npm run build` 并部署 `web/app/` 静态资源
- 后端无变更，无需重启 `nexus`

## T6 补充（2026-06-02）

- 快捷命令 API 失败时 `snackbar` 提示后降级内置命令
- 全局快捷键 `Ctrl++`/`Ctrl+=` 合并为单分支并 `return`，避免重复触发

## 验证方式

```bash
cd frontend && npm run build-only
# 浏览器：/app/terminal — 新建会话、多 Tab、断网重连 overlay、命令栏复制粘贴、空状态选服务器
```

## 回滚

```bash
git checkout HEAD~1 -- frontend/src/pages/TerminalPage.vue frontend/src/components/ShellHighlightField.vue
# 删除 frontend/src/composables/terminal/ 与 frontend/src/components/terminal/
```
