3.8 KiB
SDD-008：管理端 UI 指南落地
| 字段 | 内容 |
|---|---|
| 级别 | S3（导航、会话错误处理与日志导出凭据传递方式） |
| 状态 | 本轮已实施，真实浏览器业务链路待联调 |
| 日期 | 2026-10-22 |
现状与目标
当前 Vue 3 / Element Plus 后台已有基本响应式布局与 CSS 变量，但菜单与路由双份维护、局部样式仍有散落数值，图表无数据时使用假的占位切片，部分请求失败只留下空白或抛出未处理错误。按 ~/Documents/WEB-UI-Development-Guide 的 02/04/05/06/07/08 章，以现有 Vue 栈完善全站视觉和交互，不更换框架、不修改后台授权模型与业务 API。
设计与兼容
- 路由 meta 提供菜单分组、顺序、图标与子页父路径；布局按 meta 渲染。保留已有 URL、管理员显隐规则和路由守卫；不能把客户端导航权限误认为服务器授权。
- 统一品牌、表面、文本、边框、间距、侧栏和动效 CSS 变量，沿用 Element Plus；页面卡片统一描边。移动端侧栏覆盖主内容，表格保持横向滚动，表单弹窗不越界。
- 概览、专线列表、拨号用户、设备列表、在线会话和流量图明确首屏加载、空数据、请求失败与重试；轮询失败保留已有可信数据，禁止绘制虚构切片。统计卡片使用可键盘聚焦的导航链接，图表按需注册。
- 登录不预填账号或展示默认口令；仅真实会话失效时统一清除本地登录态并跳转，不把登录表单的 401 当作过期会话，更不从 401 处理器递归注销。
- 日志 CSV 使用现有 Axios Authorization 请求并从 Blob 下载；筛选参数与原请求保持一致，不把 token 放入 URL。失败时保留原日志并明确显示错误，下载完成后释放 Blob URL。后端现有导出接口不变。
风险与验收
风险：菜单 meta 遗漏导致入口消失；颜色对比、窄屏表格或图表实例切换出错；登录错误处理误跳转；大文件 CSV 进入浏览器内存。验收：所有原有入口均可从对应角色看到，子页可返回专线；中文/英文页面可构建；桌面与小屏下菜单和操作按钮可点；登录 401 留在登录表单，业务 401 只触发一次跳转；接口错误时有重试且不伪造数据；日志导出请求 URL 不含 token，HTTP Authorization 携带凭据并成功下载 CSV。旧版后端接口保持兼容。提交前执行前端构建与 git diff --check，生产发布需另行确认可访问性与当前在线 VPN 连接；回退只需切回上一版前端嵌入二进制。
第二轮：页面拆分与发布
Settings.vue 的飞书身份与公网入口各自负责原有请求、加载状态及校验；Tunnels.vue 的专线详情（流量策略、WireGuard Peer、二维码）与实时日志各自管理原有弹层；VPNUsers.vue 的 MFA 管理弹层负责原有绑定、PIN、解锁与备用码操作，操作完成通知父页刷新列表。路由、接口 URL、鉴权头、表单字段和权限入口不变，页面私有组件放在各自的 views/<域>/components/。实时日志在关闭、切换和组件销毁时结束请求，以免后台持续读取。
风险：拆分状态后子组件遗漏初始化、刷新或清理；身份凭据与 MFA 的错误处理不能退化；二维码仍需在列表与详情两处可用。验收：前端构建、差异检查；管理端登录后验证设置页四个标签、专线详情/日志及拨号用户 MFA 操作；服务器确认 HTTPS 健康、OIDC 发现文档、Nginx 配置与原有 VPN 进程。生产发布只替换管理服务的内嵌前端二进制，不重启专线进程；先在 /tmp/opsx-vpn-backups 保留旧二进制，最多留两份。若健康检查或静态资源异常，恢复旧二进制并重启管理进程；保留现有数据库、证书和专线配置。