# Changelog: Vuetify 前端重建

**日期**: 2026-05-31
**变更摘要**: Nexus 前端从 Tailwind+Alpine.js 完全重建为 Vue 3 + Vuetify 4 + TypeScript SPA

## 动机
旧版前端使用 Tailwind CSS + Alpine.js 的 12 个独立 HTML 页面，无组件化、无路由、无类型安全。
随着功能增长，维护成本高，页面间状态共享困难。Vue 3 + Vuetify 4 提供：
- 组件化架构（Composition API + TypeScript）
- 统一设计系统（Vuetify Material Design）
- SPA 路由 + 路由守卫
- Pinia 状态管理（JWT auth store）
- 生产级构建工具链（Vite）

## 变更内容

### 新增：frontend/ 目录（Vue 3 + Vuetify 4 SPA）
- **技术栈**: Vue 3.5 + Vuetify 4 + TypeScript 5.9 + Vue Router 4 + Pinia 3 + Vite 8
- **14 个页面组件**: src/pages/ 下所有页面
  - LoginPage — JWT + TOTP 双因素登录，429 锁定处理
  - DashboardPage — 统计卡片 + 服务器分页表格 + 告警/资源面板
  - ServersPage — CRUD + 搜索 + 分页 + 编辑/删除对话框
  - TerminalPage — xterm.js WebSSH 终端（@xterm/xterm + FitAddon + WebLinksAddon）
  - FilesPage — 远程文件浏览器（浏览/上传/下载/新建目录/预览）
  - PushPage — 文件推送 + 进度条 + 推送历史
  - ScriptsPage — 脚本 CRUD + 执行
  - CredentialsPage — 密码预设/SSH 密钥/DB 凭据
  - SchedulesPage — Cron 调度 CRUD + 启用/禁用
  - RetriesPage — 重试队列 + 状态过滤
  - CommandsPage — 命令日志/SSH 会话双视图
  - AlertsPage — 告警统计 + 历史记录
  - AuditPage — 审计日志 + 操作过滤
  - SettingsPage — 系统设置/Telegram/TOTP/API Key/IP 白名单
- **App.vue**: 全局布局 — Vuetify App Bar + Navigation Drawer + Snackbar + 全局搜索
- **全局搜索**: App Bar 搜索框，对接 /api/search/，跨服务器/脚本/凭据/调度搜索
- **Auth Store**: Pinia composition store，JWT + admin profile，localStorage 持久化
- **API 工具**: src/api/index.ts — fetch 封装 + JWT 自动附加 + 401/429/202 处理
- **WebSocket**: src/composables/useWebSocket.ts — ws://alerts?token=JWT + 断线重连
- **主题持久化**: 主题选择保存到 localStorage（nexus_theme），刷新后恢复
- **Vite 代理**: /api → https://api.synaglobal.vip, /ws → wss://api.synaglobal.vip
- **生产构建**: base=/app/，输出到 web/app/dist/

### 设计规范
- 严格遵循 Vuetify 官方 Gallery 源码模式
- 统计卡片：v-list border two-line rounded-lg + v-icon :color size="30"
- 内容卡片：v-card elevation="0" border rounded="lg"
- 状态标签：v-chip label variant="tonal" size="x-small" border="current sm"
- 不自创配色，使用 Vuetify 默认 light/dark 主题

## 涉及文件
- `frontend/` — 全新目录，约 30 个文件
- `src/pages/TerminalPage.vue` — WebSSH 终端 Vue 化（xterm.js + Koko 协议）
- `src/App.vue` — 全局布局 + 搜索 + 主题切换 + WebSocket
- `src/plugins/vuetify.ts` — 主题持久化
- `src/router/index.ts` — 14 条 hash 路由 + /terminal 新增 + 路由守卫
- `src/api/index.ts` — HTTP 客户端 + JWT
- `src/stores/auth.ts` — Pinia auth store
- `src/composables/useWebSocket.ts` — WebSocket composable
- `vite.config.mts` — base + outDir + proxy 配置
- `package.json` — 依赖声明
- `web/app/dist/` — 构建产物输出目录

## 是否需迁移/重启
- 不影响后端，不需要重启 Python 服务
- 前端是独立的 SPA，部署时将 web/app/dist/ 内容放到 web/app/ 即可
- CORS 需包含 http://localhost:3000（开发环境）

## 验证方式
1. `cd frontend && npm run dev` → http://localhost:3000
2. 登录页 → 输入用户名/密码 → 跳转仪表盘
3. 逐页验证所有页面布局和交互
4. 主题切换 → 刷新页面 → 确认主题持久化
5. 全局搜索 → 输入关键词 → 显示搜索结果
6. 终端页 → 点击服务器的"终端"按钮 → xterm.js 连接 WebSSH
7. `npx vite build` → 确认构建成功
