diff --git a/docs/2026-06-03-FRONTEND-DESIGN-SYSTEM-RUNBOOK.md b/docs/2026-06-03-FRONTEND-DESIGN-SYSTEM-RUNBOOK.md new file mode 100644 index 00000000..4708028f --- /dev/null +++ b/docs/2026-06-03-FRONTEND-DESIGN-SYSTEM-RUNBOOK.md @@ -0,0 +1,269 @@ +# 前端设计系统 Runbook + +> 适用：`deploy/tksea-portal/` 下所有 HTML 静态页（含 public portal + 7 个 admin 页） +> 建立时间：2026-06-03 +> 来源：把原本「像 demo」的多页 HTML 升级为对齐宿主 sub2api Vue+Tailwind teal/slate 体系的 Linear/Vercel 信息建筑派设计系统。 + +## 1. 文件结构 + +``` +deploy/tksea-portal/ +├── portal.css # 真设计系统 (777 行) — 唯一新视觉真源 +├── portal.js # window.Sub2ApiPortal — toast / icon / nav / theme / drawer +├── admin-common.css # 4KB legacy shim — 老类名映射到新 token +├── admin-common.js # 313 行原 nav 渲染契约（未动） +├── index.html # public portal (light) +├── admin/ +│ ├── index.html # admin 入口 +│ ├── logical-groups.html +│ ├── route-health.html +│ ├── accounts.html +│ ├── providers.html +│ └── batch-import.html # → /portal/admin-batch-import.html 1.5KB redirect +└── admin-batch-import.html # 旧地址实页（历史兼容） +``` + +**新页面 = `portal.css` + `portal.js` + 自己的 ` + + +
+ + +
+
+ Section Name +

页面主标题

+

副标题描述，用 token 控制字号行高。

+
+
+
+
+
+

API Root

+

-

+
+
+ +
+
+ +
+ + ... +
+
+ + + + + +``` + +## 4. 组件 API + +### 4.1 `
` + +```html +
+
+
+

label

+

0

+
+
+``` + +### 4.2 `
` + +`.statusbar` 是统一的提示条；颜色用 `data-tone="success|warning|danger|note|neutral"` 或直接 class `tone-healthy|tone-cooldown|tone-failing|tone-disabled|tone-ready|tone-note|tone-warn`。 + +### 4.3 Portal 图标 + +```js +Portal.icons.shield.mount("#icon-slot"); // 渲染 22px lucide stroke 1.75 +Portal.icons.group.mount("#icon-slot", { size: 18 }); +``` + +可用：`home / group / route / health / account / provider / import / check / x / alert / info / copy / edit / trash / plus / refresh / download / upload / eye / eyeoff / play / pause / search / filter / shield / activity / package / key / send / log-out / external-link / arrow-right / chevron-right` + +### 4.4 Toast + +```js +Portal.toast("保存成功", { tone: "success", duration: 3000 }); +Portal.toast("拉取失败", { tone: "danger" }); +``` + +### 4.5 Copy + +```js +Portal.copyText(value, { success: "已复制", failure: "复制失败" }); +``` + +### 4.6 Theme + +```js +Portal.theme.set("dark" | "light" | "auto"); // 写入 localStorage + html[data-theme] +Portal.theme.get(); // 当前生效 theme +``` + +### 4.7 Modern Nav + +```js +Portal.renderModernAdminNav(container, currentKey); +// 渲染带 SVG icon + 渐变 hover 的现代 nav；并存于 AdminCommon.renderAdminNav 之上 +``` + +## 5. 关键约束 + +1. **不要破坏测试契约字符串**：`logical_group` / `shadow_host_id` / `matched_account_state` / `account_resolution` / `package_tier` / `visibility_scope` / `gpt-5.4` / `MiniMax-M2.7-highspeed` / `deepseek-chat` / `Batch Import Admin` / `route_status` / `cooldown_seconds` / `failover_threshold` / `Smoke Logical Group` / `Smoke Provider Account` / `smoke-admin` / `smoke-route-primary` 等 70+ 字符串必须在 HTML 中出现（前端门禁 grep 断言）。 + +2. **不要修改 `admin-common.js`**：保留 `window.Sub2ApiAdminCommon` 的全局 API 契约。`portal.js` 是叠加层，不是替代层。 + +3. **不要使用 emoji / 渐变紫 / generic stock photo**：用 SVG icon + token 调色板。 + +4. **不要写裸 `style="color:#xxx"`**：用 `var(--text-muted)` 等 token。 + +5. **JS 引用 DOM ID 时**：新增的 page-hero / stat-card ID 必须和 `getElementById()` 调用对应。修改 stat-card label 时同步检查 JS 里的引用。 + +## 6. 测试门禁 + +```bash +cd /home/long/project/sub2api-cn-relay-manager +bash scripts/test/test_tksea_portal_assets.sh # 70+ 字符串契约断言 +bash scripts/test/verify_frontend_smoke.sh # chromium headless 渲染 7 页 + public +bash scripts/acceptance/verify_frontend_acceptance_matrix.sh # 总入口 +``` + +修改任何 `deploy/tksea-portal/*.html` / `portal.css` / `portal.js` / `admin-common.css` 后必须三门都过。 + +## 7. 截图 evidence + +```bash +# 启动本地 server（端口 8765，映射 /portal/* → deploy/tksea-portal/*） +python3 /tmp/portal_server.py & + +# 截图 8 个页面 +mkdir -p /tmp/portal-screenshots +for url in \ + "/portal/admin/index.html" \ + "/portal/admin/logical-groups.html" \ + "/portal/admin/route-health.html" \ + "/portal/admin/accounts.html" \ + "/portal/admin/providers.html" \ + "/portal/admin-batch-import.html" \ + "/portal/admin/batch-import.html" \ + "/portal/index.html"; do + name=$(basename "$url" .html) + google-chrome --headless --disable-gpu --no-sandbox --hide-scrollbars \ + --window-size=1440,2400 --virtual-time-budget=4000 \ + --screenshot=/tmp/portal-screenshots/${name}.png \ + "http://127.0.0.1:8765${url}" +done +``` + +## 8. 常见错误 + +- **重复 ``**：原页有 inline `` 紧跟 `