Codex
52 lines
5.8 KiB
Markdown
52 lines
5.8 KiB
Markdown
# 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 后，待处理指标应回落，历史记录仍可在任务历史和执行结果中查看。
|
||
|
||
## Task History Diagnostics
|
||
|
||
`任务调度 / 任务历史` 必须把任务生命周期渲染为可诊断表格，不得只显示更新时间和原始 payload 摘要。每行至少展示状态、任务命令和 id、Provider、任务耗时、载荷摘要、诊断信息、更新时间和显式 `查看原始JSON` 操作；终态任务的耗时按 `updatedAt - createdAt` 计算，待处理任务按当前时间减 `createdAt` 计算。失败任务必须在默认视图中提取 `result.error`、`result.message`、`result.stderr`、`result.reason` 或等价字段作为失败原因，并将 exit code、timeout、previous status 等关键诊断字段渲染为控件；完整 result 只能通过 `查看原始JSON` 展开。
|
||
|
||
## 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 Version View
|
||
|
||
资源节点模块必须提供 `网关版本` 子标签，按每个 Provider 展示 provider-gateway 版本号、升级策略、启动时间、能力摘要、最近自动更新状态和自动更新记录。自动更新记录的数据源是 `provider.upgrade` 任务历史，默认必须渲染为结构化表格字段：状态、模式、任务 id、来源、耗时、策略、结果摘要和更新时间；不得把升级 plan、task result 或服务日志作为裸 JSON 直接铺在页面上。`最近自动更新` 应优先选择最新 `mode: "schedule"` 的真实升级记录，避免后续预检 plan 覆盖真正的升级结果；完整升级任务 JSON 只能通过对应行的 `查看原始JSON` 按钮显式打开。
|
||
|
||
## 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。
|
||
|
||
## Login
|
||
|
||
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 的外部接入地址只作为连接拓扑信息展示，不作为浏览器数据源。
|