894d8f57d0
Add joy online package injection helpers, expand vm/work/clone command surface for desktop and session ops, and polish remaining web tabs (drawer, ops, hardware, sessions) plus design/capacity docs.
181 lines
8.5 KiB
Markdown
181 lines
8.5 KiB
Markdown
# joy web 设计原则
|
||
|
||
> 2026-07-11 · 以 **神兽工坊** 为视觉与结构标准
|
||
> 触发：神州「资产」按硬件 tab 重做后定稿
|
||
> 范围：`Projects/joy-cli/src/joy/web/`
|
||
|
||
---
|
||
|
||
## 0. 一句话
|
||
|
||
**新世界 / 新 tab 的 UI 必须先对照神兽侧已有块再写；复用全局 CSS 与 core 组件，禁止另起一套「看起来差不多」的样式。**
|
||
|
||
标准参考（按优先级）：
|
||
|
||
1. **设备/资产卡** → 神兽 · **硬件** tab（`js/tabs/hardware.js` + `#pane-hardware`）
|
||
2. **列表/运维** → 神兽 · **运维** tab（`ops.js` + `card compact` / `infra-list`）
|
||
3. **神兽列表** → `beasts.js` + 抽屉
|
||
4. **全局** → `styles.css` + `core.js`（`ic` / `badgeXs` / `miniBar` / `esc` / `card-row`）
|
||
|
||
神州大地 / 混沌蛮荒 **不是** 另开视觉体系，只是 **数据与权限边界** 不同。
|
||
|
||
---
|
||
|
||
## 1. 结构标准：硬件 tab 模式
|
||
|
||
神兽 · 硬件已验证的结构（2026-07 定稿）：
|
||
|
||
| 层 | 做法 | 反例 |
|
||
|----|------|------|
|
||
| **总览** | 独立 section，`card compact ops-stat` 一排，可点跳到设备 | 把全部设备塞进一个 section 无限滚动 |
|
||
| **每台设备** | **独立 section**（`section-title` = 设备名），body 内完整指标 | 所有主机塞一个大 grid 堆坨 |
|
||
| **pane 布局** | CSS grid 列（硬件 4 列）；总览 `grid-column: 1 / -1`；设备 `span 1` | 仅靠 flex 横铺导致「全横排占满屏」 |
|
||
| **设备卡内容** | 顶栏 metric（在线/磁盘/内存/负载）+ `miniBar` + `infra-list` 明细 + 告警条 | 只留一个数字、或 26 张同质小卡无明细 |
|
||
|
||
**神州 · 资产 · 云主机** 已对齐（2026-07-11）：
|
||
|
||
- `sz-hosts` = 总览（对齐 `renderHwOverview`）
|
||
- `sz-host-<id>` = 每台独立 section（对齐 NAS / 路由器 / huawei-pc）
|
||
- `#pane-sz-assets` = 4 列网格（对齐 `#pane-hardware`）
|
||
- `renderShenzhouHost(d, hostId)` = 完整设备卡（对齐 `renderHwLive` / `renderHwNas`）
|
||
|
||
---
|
||
|
||
## 2. 复用全局样式（禁止私造）
|
||
|
||
### 2.1 必须用的全局类 / 组件
|
||
|
||
| 用途 | 用 | 不要 |
|
||
|------|-----|------|
|
||
| 指标卡 | `.card` `.card.compact` `.card-title` `.card-value` `.card-meta` `.card-row` | 自写 `div` + 内联 flex 仿卡片 |
|
||
| 可点总览格 | `.ops-stat`（pointer + hover） | 无交互的纯色块 |
|
||
| 明细行 | `.infra-list` `.infra-row` `.infra-name` `.infra-status` | 表格硬写或一长串 span |
|
||
| 状态色 | `.c-ok` `.c-err` `.c-warn` `.c-dim` + `.infra-status ok\|err\|warn` | 硬编码 `#22c55e` |
|
||
| 进度条 | `miniBar(pct, sev)`（core） | 自写 progress bar |
|
||
| 图标 | `ic(name)` / tab 内 `_szIcon` 委托 `ic` | emoji 当主图标（告警文案除外） |
|
||
| 徽章 | `badgeXs` / `_szBadge` | 自写 badge class |
|
||
| 转义 | `esc` / `_szEsc` | 直接插用户/API 字符串 |
|
||
| 告警条 | `.hw-alert`（可复用）+ 通知按钮模式 | 只 toast 不落盘 |
|
||
|
||
### 2.2 允许的局部 CSS
|
||
|
||
- **pane 网格**：`#pane-<tab-id>` + `#section-wrap-<section-id>`（与硬件同模式）
|
||
- **领域前缀**：如 `.sz-*` / `.mh-*` 仅用于 **布局钩子**，不复制一套 card 皮肤
|
||
- **禁止**：复制一份「神州专用 card 颜色/圆角/字号」与神兽不一致
|
||
|
||
### 2.3 内联 style
|
||
|
||
- 允许：间距微调（`margin-bottom:10px`）、单行 ellipsis、flex 子项 `min-width:0`
|
||
- 禁止：用内联定义整套视觉（颜色、字号阶梯、阴影）绕过 `styles.css`
|
||
|
||
---
|
||
|
||
## 3. 世界与导航
|
||
|
||
| 世界 | 正式名 | 标准 |
|
||
|------|--------|------|
|
||
| local | **神兽工坊** | 视觉与交互 **真源** |
|
||
| shenzhou | **神州大地** | 复用神兽组件；数据 = 生产资产 |
|
||
| manhuang | **混沌蛮荒** | 同上；业务/情报边界不同 |
|
||
|
||
- 世界切换在 **页眉右侧**（logo/时间在左，主题切换最右）
|
||
- 一级 tab 刷新时 **禁止** 因 badge 宽窄导致菜单跳动（`.tab-badge:empty { display:none }` + `white-space:nowrap`）
|
||
|
||
---
|
||
|
||
## 4. 实现检查清单（PR / 改 tab 前）
|
||
|
||
1. [ ] 是否已有神兽侧同类块可抄？（硬件 / 运维 / 神兽列表）
|
||
2. [ ] 是否用了 `card` / `infra-list` / `miniBar` / `ic` / `esc`？
|
||
3. [ ] 多实体（主机/站点/设备）是否 **总览 section + 每实体独立 section**？
|
||
4. [ ] pane 是否用 CSS grid 列布局，而不是「一个 section 里横排一百个」？
|
||
5. [ ] 新 CSS 是否只加 pane/section 钩子，未复制 card 皮肤？
|
||
6. [ ] 自动刷新是否只更新 section body（`_lastHtml`），不重建 skeleton？
|
||
7. [ ] 缓存戳是否 `update-cache-hash.sh`？
|
||
|
||
---
|
||
|
||
## 5. 反模式（踩过的坑）
|
||
|
||
| 反模式 | 为何不行 | 正确做法 |
|
||
|--------|----------|----------|
|
||
| 26 站各一张 ops-stat 堆成一坨 | 密度爆炸、不像硬件 | 汇总 metric + `infra-list` |
|
||
| 每台主机整行横铺（状态+磁盘+内存各占满宽） | 纵向爆炸 | 独立 section + pane 4 列 |
|
||
| 为「省空间」砍掉 miniBar/infra | 信息不足 | 保留完整卡，只改 **网格** |
|
||
| 神州另起 `_szCard` 皮肤 | 双轨维护 | section-title + 全局 card |
|
||
| 自动刷新重建 tab DOM | 菜单跳动 | skeleton 一次；badge 固定占位策略 |
|
||
|
||
---
|
||
|
||
## 6. 文件索引
|
||
|
||
| 角色 | 路径 |
|
||
|------|------|
|
||
| 本原则 | `docs/ops/joy-web-design.md` |
|
||
| 前端拆分 | `src/joy/web/js/README.md` |
|
||
| 硬件标准实现 | `src/joy/web/js/tabs/hardware.js` |
|
||
| 硬件 pane CSS | `styles.css` → `#pane-hardware` |
|
||
| 神州资产对齐实现 | `src/joy/web/js/tabs/shenzhou.js`（`renderShenzhouHost` / `SZ_CLOUD_HOSTS`） |
|
||
| 神州资产 pane CSS | `styles.css` → `#pane-sz-assets` / `#section-wrap-sz-host-*` |
|
||
| TABS 注册 | `src/joy/web/app.js`（`SHENZHOU_TABS` / `sz-assets` sections） |
|
||
| 神州产品边界 | `docs/ops/joy-shenzhou.md` |
|
||
|
||
---
|
||
|
||
## 7. 生产服务器设备卡信息层级
|
||
|
||
**硬件是基础，业务关联也有价值**（2026-07-11 定稿）。
|
||
|
||
| 层 | 字段 |
|
||
|----|------|
|
||
| 硬件基础 | reachable · disk%+bar · mem%+bar · load · uptime · inode% · 容器运行数 |
|
||
| 台账 | role · region · specs · ip · panel · container runtime · web · hostname · ssh |
|
||
| 业务关联 | 关键路径 n/红 · SSL ok/warn/crit · 业务系统 ids · 服务 n |
|
||
| 元数据 | sampled_at 年龄 · 告警条（含路径/SSL/收款） |
|
||
|
||
**展示节奏（对齐神兽硬件 NAS）**：
|
||
1. 告警条 — 仅有 issue 时
|
||
2. 主卡 4 列 — 始终（在线 / 盘 / 存 / 载）
|
||
3. 采样行 + 短档案 — 始终（角色 / SSH / 业务脉搏一句话）
|
||
4. `业务关联` fold — 默认折叠，路径/SSL/收款异常时 `open`
|
||
5. `机身详情` fold — 默认折叠，硬件阈值命中时 `open`
|
||
|
||
**通知（神州 = 瓦普专场）**：
|
||
- 硬件 tab → `notifyTuxDevice` → poke **tux**
|
||
- 神州 tab → 一律 poke **wapuu**（`notifyShenzhou` / `notifyWapuuPath` / `notifyWapuuHost` / `notifyWapuuShenzhouAlert`）
|
||
- 主机按钮文案固定「通知 wapuu」；payload 对齐硬件：角色/指标/路径/SSL/触发项全文，禁止只甩 host id
|
||
- wapuu 业务确认后，infra 转 konqi、制度转 tux
|
||
|
||
采集：`_PROBE_REMOTE` 含 INODE + docker/podman ps；`_enrich_hosts_with_biz` 挂 paths/ssl/business。
|
||
|
||
## 8. 关键路径（业务入口，非截图墙）
|
||
|
||
| 层 | 内容 |
|
||
|----|------|
|
||
| 主行 | 名 · 栈(WP/WP多站/CDN/静态/应用) · 状态 · 延迟/SLO · 钱标 |
|
||
| 短档案 | biz · 宿主跳转 · 多站摘要 · SSL 剩余天 · URL |
|
||
| 截图 fold | 默认折叠；异常时 open |
|
||
| 栈详情 fold | WP 版本/插件/DB/子站已列·未列；SSL；宿主 load |
|
||
| WP 网络卡 | 安装维度：多站点 9 子站 vs critical_paths 已列对照 |
|
||
| 通知 | `notifyWapuuPath` 全文 → poke **wapuu** |
|
||
|
||
未列子站 ≠ 故障：在 WP 网络中但未进脉搏台账；要监控再加 `critical_paths`。
|
||
|
||
### 栈扩展信息（只读，非面板内管理）
|
||
|
||
| stack | 接入字段 |
|
||
|-------|----------|
|
||
| **wp / wp-ms** | 主题(当前+已装) · 启用插件 slug@version · 目录插件数 · 网络级 sitewide · 未启用样例 · PHP/WP/DB |
|
||
| **static / cdn** | HTTP Server · CF/源缓存状态 · Content-Type · Last-Modified · 宿主运行时 |
|
||
| **app** | 同上指纹 + 宿主 containers_n/runtime/cores · 角色摘要 |
|
||
| 全栈 | SSL 剩余天 · 宿主 load/disk · 延迟/SLO |
|
||
|
||
启停插件/换主题 → 宝塔或 SSH；面板只展示 + 通知 wapuu。
|
||
|
||
## 9. 变更记录
|
||
|
||
| 日期 | 变更 |
|
||
|------|------|
|
||
| 2026-07-11 | 初版：以神兽硬件为标准；神州资产云主机按「总览 + 每台 section + 4 列」落地 |
|
||
| 2026-07-11 | 生产机设备卡：inode/容器/采样时间/地域台账/路径·SSL·业务关联 |
|
||
| 2026-07-11 | 关键路径：栈类型/WP多站/SSL·SLO/截图折叠/wp_networks |
|
