WebUI设计
负责人：@Archeroy
定位
WebUI 是 Everpast 的家庭监控控制台，主要承担时间线浏览、自然语言查询、实时状态查看、视频回放、插件管理和系统配置等交互职责。
第一阶段按局域网单机部署设计，优先保证手机、平板和桌面浏览器可用。WebUI 不直接承担核心业务逻辑，不直接连接 MQTT Broker，也不直接访问底层文件系统；所有数据访问应通过后端 HTTP API、WebSocket 或 SSE 网关完成。
当前后端网关由 www-server 子模块提供，接口边界见 www-server 后端网关。
用户端
主页、事件查看、查询、实时监控、回放、AI对话、智能家居设备控制(对接HA的Web)
适配手机平板触摸
管理端
系统概览、设备添加修改、自动化配置、模型配置、系统设置等
技术栈
| 分类 | 选型 | 说明 |
|---|---|---|
| 前端框架 | Vue 3 | 当前 web-ui 已采用 Vue 单页应用 |
| 构建工具 | Vite | 开发启动快，部署产物简单，适合独立 SPA |
| UI 基础 | Element Plus | 当前控制台组件、表单、表格、菜单和图标均基于 Element Plus |
| 图标 | @element-plus/icons-vue | 与 Element Plus 组件体系保持一致 |
| 页面组织 | 单 Vue 应用内分区视图 | 当前通过侧边栏和分段控件切换用户端、管理端、开发控制台视图，尚未接入独立路由库 |
| 数据访问 | 原生 fetch + www-server HTTP API | 当前直接调用 /api/*，后续如查询缓存复杂度上升再评估封装 |
| 本地状态 | Vue 响应式状态 | 仅保存当前视图、筛选条件、表单草稿、WebSocket 状态等 UI 状态 |
| 表单校验 | Element Plus 表单组件 + 后端校验 | 当前配置字段由 /api/components 返回的元数据驱动，最终校验由 www-server / Genapsed 执行 |
| 实时通信 | WebSocket / SSE | 接收设备状态、日志、时间线增量和插件事件；由后端桥接 MQTT |
| 视频播放 | 原生 <video> 起步；需要 HLS 时再引入 hls.js | 优先降低复杂度，按回放格式再扩展 |
| 测试 | 当前未接入前端测试框架 | 后续可按 Vue 技术栈补充 Vitest、Vue Test Utils 和关键流程 Playwright |
架构边界
- WebUI 只调用后端公开接口，不直接订阅 MQTT topic。
- 视频、截图等大文件通过 HTTP 授权链接或后端返回的共享目录相对引用访问，MQTT 只传引用和元数据，不传文件内容。
- 权限校验、插件 topic 隔离、系统级命令执行统一留在 Genapsed / Supervisor / 后端网关处理。
- WebUI 的插件页面先作为宿主提供统一入口和配置界面，不在第一阶段实现微前端插件运行时。
- 首次配置向导可以复用同一套 Vue 应用，通过前端视图状态和后端状态决定是否进入向导模式；若后续页面层级复杂，再引入 Vue Router。
不采用方案
| 方案 | 暂不采用原因 |
|---|---|
| Next.js / SSR | 当前主要是局域网控制台，首屏 SEO 和服务端渲染收益低，部署复杂度更高 |
| 直接 MQTT over WebSocket | 容易把 topic 权限和认证细节泄漏到浏览器，破坏后端权限边界 |
| 微前端插件系统 | 插件生态尚未成熟，第一阶段会显著增加运行时复杂度 |
| 重型管理后台框架 | 当前 Element Plus 已满足控制台原型需求，暂不引入额外后台框架 |