UniDesk Frontend Reference

UniDesk 前端是 React 组件化工业控制台，不追求展示型大屏效果。设计目标是高信息密度、低装饰、低字号、低间距，并让调度、节点、事件和配置入口在单屏内快速切换。

Source Contract

frontend 应用源码必须使用 TypeScript + React，禁止在 src/components/frontend 中维护手写 .js / .jsx 应用源码。浏览器请求的 /app.js 只能由 frontend Bun server 从 src/components/frontend/src/app.tsx 转译生成；public/ 目录只保存 HTML/CSS 等静态资产，不提交手写 app.js。

Layout

左侧边栏只切换主模块：运行总览、资源节点、任务调度、系统配置。顶部标签只切换当前主模块内的子功能；例如资源节点下的节点清单、资源标签、心跳状态只属于资源节点，和运行总览、任务调度、系统配置没有重复或共享语义。移动端左侧边栏会转为顶部横向主模块条，但高度必须在不同主模块之间保持一致，并保持窄条、单行、不换行；主内容区无论内容多少都必须从顶部向下排列，空状态也不得上下居中制造大块留白。

Overview Task Drilldown

态势总览 中的 待处理任务 指标必须可点击进入任务调度的 待处理任务 子标签，展示具体 queued、dispatched、running 任务的状态、Provider、已等待时间、payload 摘要和显式 查看原始JSON 操作。总览不得只给出无法追溯的数字；当后台把超时未终态任务转为 failed 后，待处理指标应回落，历史记录仍可在任务历史和执行结果中查看。

Resource Node Monitor View

资源节点模块必须提供 资源监控 子标签，用类似 Windows 任务管理器的性能页展示每个 provider 节点的 CPU、内存和硬盘用量历史曲线。该页面应包含节点切换、当前用量摘要、CPU/Memory/Disk 三条曲线、采样说明和 Provider Gateway 升级 控制区；曲线数据来自 backend-core 的 /api/nodes/system-status，不得在页面默认展示原始 JSON。内存曲线必须使用实际内存口径，不把 Linux page cache / buffer 计入占用。

Resource Node Docker View

资源节点模块必须提供 Docker 状态 子标签，用类似 Docker Desktop 的结构展示每个 provider 节点的 Docker daemon 状态。该页面应包含节点切换、daemon 摘要、Containers/Images/Volumes/Networks 指标、容器表格、镜像/卷/网络侧栏，并通过状态徽标区分 running、paused、exited 等状态。数据库命名卷 unidesk_pgdata_10gb 必须在 Volumes 区域和数据库命名卷卡片中显式可见，不得因为列表截断或匿名卷排序被隐藏。

Provider Gateway Upgrade Control

资源监控 子标签中的升级控制区通过 backend-core /api/dispatch 下发 provider.upgrade 任务。默认 预检升级 只生成升级计划并回传任务结果；执行升级 才允许调度节点本地 updater 容器执行 Compose 重建。前端只展示结构化任务状态、task id 和摘要，完整升级计划必须通过 查看原始JSON 显式查看。

Component Data Rendering

前端必须把 backend-core 返回的 JSON 渲染为合适的控件：状态徽标、指标卡、表格列、标签 chip、字段摘要、任务结果卡、日志行和表单控件。默认页面禁止暴露裸 JSON、pre JSON 或整段 JSON.stringify 文本；只有用户明确点击 查看原始JSON 按钮后，才允许在弹窗或高级编辑区展示原始 JSON。

frontend 提供账号密码登录，默认账号为 admin，默认密码为 Liang6516.。登录会话使用 frontend 容器签发的 HttpOnly Cookie；浏览器后续只访问同源 frontend API，frontend 再通过 Docker 内网代理 backend-core。

Visual Language

界面使用深钢蓝、炭黑、琥珀和冷青作为工业控制台色板；字体选择窄体和等宽组合，以减少横向浪费。字号、表格行高和面板间距保持克制，避免大标题和松散卡片造成信息密度下降。

Data Flow

浏览器不直接访问 backend-core。frontend 容器服务 React 静态资产、登录接口、会话接口和同源 API 代理；代理目标是 Docker 内网 http://backend-core:8080。provider-gateway 的外部接入地址只作为连接拓扑信息展示，不作为浏览器数据源。

4.3 KiB Raw Blame History Unescape Escape