joy-cli/docs/ops/joy-web-design.md

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