---
name: web-admin-prototype
description: Web 管理后台多页原型开发。当任务涉及桌面端后台管理原型、数据列表表格、筛选栏、详情弹窗等场景时使用。
---

# web-admin-prototype · Web 管理后台多页原型

## 何时触发

**主动触发**（用户说出以下任一短语，立即调用本 skill）：
- 「做一套后台原型」「管理后台原型」「桌面端原型」「后台原型」「Web 原型」「admin 原型」

**上下文触发**（同时满足 3 条，主动询问是否启用）：
1. 目标是桌面端 / Web 后台（1440px 基准）
2. 涉及 ≥ 2 个 HTML 页面
3. 用途是演示 / 评审 / 讲解

**已有原型延续**（用户未明说也触发）：
- 工作目录里有 plan.html + 多页 + pi-layout 结构，新增或修改页面时主动按本 skill 规范执行

**不触发**：
- 单文件原型 → 直接写 HTML 即可
- 移动端 / 手机端 → 走 `mobile-prototype`
- 单纯讨论设计规范不动手 → 走 `design-system`

---

## 目录结构（强制）

每个原型是一个目录，放在 `prototypes/YYYY-MM/<feature-name>-v1/` 下：

```
<feature-name>-v1/
├── plan.html              # 方案总览（多页复杂原型才需要，简单单页可省）
├── index.html             # 入口页（必须）
├── <page-2>.html          # 业务页 2
├── <page-3>.html          # 业务页 3 ...
├── styles/
│   ├── prototype-intro.css    # 介绍区样式（直接引用 skill 里的，不变）
│   ├── plan.css               # plan.html 专用样式
│   ├── base.css               # 桌面端基础样式（共享）
│   └── <page>.css             # 每页独立样式
├── scripts/
│   ├── store.js               # 跨页状态（共享）
│   ├── data.js                # 共享数据（共享）
│   └── <page>.js              # 每页独立脚本
└── .claude/launch.json        # 预览服务配置
```

**关键约定**：
- 单页简单原型（只有 index.html + 1~2 个业务页）→ 不需要 plan.html
- 多页复杂原型（≥ 3 页 + 有页面跳转关系）→ 需要 plan.html
- plan.html 有「是否生成」决策，在生成骨架时根据 --pages 数量判断

---

## 单页结构（单列桌面预览 + 详情按钮弹窗）

每个业务页必须包含：

```html
<div class="pi-layout">
  <header class="pi-header">
    <div class="pi-header-left">... 徽标 / 标题 / 副标 ...</div>
    <div class="pi-header-right">
      <button id="btnIntroDetail">详情</button>   <!-- 必带：触发介绍弹窗 -->
      <a class="pi-back" href="plan.html">← 返回方案总览</a>
    </div>
  </header>
  <main class="pi-main">
    <div class="pi-desktop-col">...</div>   <!-- 单列满宽：桌面预览 -->
  </main>
</div>

<!-- 详情弹窗：放页面介绍（详见下文） -->
<div class="detail-modal-overlay" id="introModal">...</div>
```

**⚠️ 与 mobile-prototype 的核心区别**：web 管理后台**不使用右侧固定 `.pi-intro-col` 介绍栏**。右侧介绍栏是 mobile-prototype 的规范，套到 web 后台会挤压业务表格、破坏 1440px 桌面布局。web 后台的介绍统一走「详情按钮 → 居中弹窗」。

**桌面预览（单列满宽）**

不使用手机框，直接渲染原型内容（1440px 基准），铺满整行。**顶栏必须紧凑**（高度 44px），不要让原型级 header 占用过多视觉：

```css
/* 顶栏紧凑化 */
.pi-header { padding: 8px 20px !important; gap: 12px !important; min-height: 44px; }
.pi-header-left { display: flex; align-items: center; gap: 10px; flex: 1; min-width: 0; }
.pi-badge { padding: 2px 8px; background: var(--wa-primary-light); color: var(--wa-primary); border: 1px solid var(--wa-primary-border); border-radius: 4px; font-size: 11px; font-weight: 500; }
.pi-title { margin: 0; font-size: 16px; font-weight: 600; line-height: 1.2; white-space: nowrap; }
.pi-subtitle { font-size: 12px; color: var(--wa-text-sub); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
.pi-header-right { display: flex; align-items: center; gap: 10px; flex-shrink: 0; }
.pi-user { font-size: 12px; color: var(--wa-text-sub); white-space: nowrap; }

/* 主区单列满宽 */
.pi-main {
  grid-template-columns: 1fr !important;
  max-width: 1920px !important;
  padding: 12px 20px !important;
  gap: 12px !important;
}
.pi-desktop-col {
  min-width: 0;
  overflow: auto;
  background: var(--pi-card-bg);
  border: 1px solid var(--pi-border);
  border-radius: var(--pi-radius);
}
.pi-desktop-col .desktop-preview {
  width: 100%;
  min-width: 1280px;
  min-height: 720px;
}
```

**介绍区（详情按钮 + 弹窗，强制）**

页面介绍信息（使用角色 / 本页定位 / 怎么用 / 示例 / 场景呼应）统一放在**详情弹窗**里，由顶栏右上角「详情」按钮触发。结构参考 `auto-parts-storage-management-v1.html`，样式复用 `base.css` 的 `.detail-modal-*` 类。

5 个内容块缺一不可：
1. **一句话概括** — 用 `.lead`，说明本页核心价值
2. **使用角色 + 上下游** — 用 `.card-grid` + `.info-card` 卡片组
3. **如何使用** — 3 步以内，用 `.steps` + `.step`
4. **示例** — 具体场景，用 `.example-box`
5. **场景呼应** — 与其他页关系，用 `.example-list`

弹窗开关逻辑（每页 `<script>` 末尾必带）：
- 点「详情」开：`.introModal.style.display='flex'` + `.classList.add('show')`
- 关闭：「×」按钮 / 点遮罩 / 按 Esc
- 关时移除 `.show` 类，并 `style.display='none'`

---

## plan.html 结构（按需生成）

**何时生成 plan.html：**
- 页面数 ≥ 3 → 生成
- 页面数 < 3 → 不生成，入口页右下角放一个「📋 方案名」角标即可

**plan.html 结构（精简版，参考 image-management-space-v1/plan.html）：**

```
顶部导航栏（方案名 + 入口页链接）

Hero（方案名 + 副标 + 标签 + 桌面缩略图）
① 架构概览（一行说明路由方式 / 状态共享 / CSS/JS 拆分）
② 页面流程（Mermaid 流程图，节点可点击弹出详情 Modal）
③ 页面清单（grid 卡片，每页一个链接）
④ 功能矩阵（表格：功能 × 页面，标记 ✓ / — / 待实现）
⑤ 架构约束（bullet 列表）
⑥ 已知限制（3 项）
⑦ 待确认问题（3 项）
```

**去掉 mobile-prototype plan.html 中的：**
- 三层级客户类型 Tab
- 方案核心 4 张卡
- P0/P2 优先级 Tab 闭环
- 节点 Modal（仅在复杂原型含 Mermaid 流程图时使用）

**节点详情 Modal（仅复杂原型）：**
与 mobile-prototype 一致，4 块结构：节点头 / 业务场景 / 业务动作 / 功能清单。

---

## plan.html 内容归属（防重复）

| 信息类型 | 唯一归属位置 | 禁止出现在 |
|---|---|---|
| 方案定位（一句话） | ① 架构概览的 plan-positioning | Hero 副标 |
| 页面跳转 | ③ 页面清单 | Hero、功能矩阵 |
| 功能点（带状态） | ④ 功能矩阵 | ① 架构概览、③ 页面清单 |

**扫读层（同 mobile-prototype / exec-briefing）**：Hero 副标 ≤ 1 句，定位 ≤ 1 句。有管线 / 公式用公式条 + 步骤标签，禁止收成功能卡。超过一句的规则用 `<details class="plan-scan-chips">` 或节点 Modal 下转。

---

## 详情弹窗（原型页内嵌）

参考 `auto-parts-storage-management-v1.html` 的弹窗设计：

```html
<div class="detail-modal-overlay" id="detailModal">
  <div class="detail-modal">
    <button class="close-detail-modal">×</button>
    <div class="detail-modal-header">
      <div class="detail-modal-icon">🏠</div>
      <div class="detail-modal-title-wrap">
        <h2>方案名称</h2>
        <p class="subtitle">副标题</p>
      </div>
    </div>
    <p class="lead"><strong>一句话概括：</strong>...</p>
    <div class="section">
      <div class="section-title">用途</div>
      <div class="card-grid">...</div>
    </div>
    <div class="section">
      <div class="section-title">如何使用</div>
      <div class="steps">...</div>
    </div>
    <div class="section">
      <div class="section-title">示例</div>
      <div class="example-list">...</div>
    </div>
  </div>
</div>
```

弹窗样式在 `<page>.css` 中定义，不放入共享样式。

---

## 设计 token（必须用 CSS 变量）

共享基础变量（在 `base.css` 中定义）：
```css
:root {
  --wa-primary: #2563EB;
  --wa-primary-light: #EFF6FF;
  --wa-primary-border: #BFDBFE;
  --wa-text-title: #111827;
  --wa-text-body: #1F2937;
  --wa-text-muted: #6B7280;
  --wa-border: #E5E7EB;
  --wa-bg: #F9FAFB;
  --wa-bg-white: #FFFFFF;
  --wa-radius: 8px;
  --wa-transition: 200ms ease-out;
}
```

禁写死 hex（业务页的特定颜色例外，如进度条 green/orange/red）。

---

## UI 框架复用（强制）

**触发条件**：**项目仓库根目录**下存在 `prototypes/shared/` 本地化的 UI 框架（如 Tabler），或用户指定了框架。注意按仓库根定位，不是当前 cwd——本机 PUL-FMS 仓库是两层嵌套（`D:\Claude-code\PUL-FMS\PUL-FMS\`），框架实际在 `PUL-FMS/PUL-FMS/prototypes/shared/tabler/`；不确定时先 Glob `**/prototypes/shared/*` 确认真实位置，别凭约定猜路径。

1. **先查后写**：内容区组件（表格 / 卡片 / 按钮 / 徽标 / 表单 / 栅格 / 图标）必须先确认框架已有对应类，直接用框架类名；禁止在框架已有组件的情况下自写一套平行样式。
2. **框架空白才自写**：框架确实没有的组件（纯 CSS 库的空白，如树组件、mini 折叠侧栏）才允许自写，且必须：
   - 视觉语言对齐框架（主色 / 圆角 / 动效时长取框架值）；
   - 在该 css 文件的注释里注明「框架无此组件」。
3. **壳的取舍**：若框架布局组件与预览容器冲突（如 Tabler `.navbar-vertical` 是 `position:fixed`、无法嵌入 1440px 预览容器），壳（侧栏/顶栏）可自写，必须在样式文件头注释说明原因。
4. **交付可验证**：能说清「怎么证明用上了框架」——F12 查类名 / Network 看框架 css 已加载 / 删掉 link 后内容区变裸 HTML。
5. **实例留痕**：每个用了框架的原型目录放一份 `README.md`，记录本原型「用了什么 / 没用什么 / 为什么 / 怎么验证」（参考实例：`PUL-FMS/PUL-FMS/prototypes/2026-09/pul-fms-base-v1/README.md`，相对 `d:\Claude-code`）。

---

## 反模式（禁止）

- ❌ 右侧固定 `.pi-intro-col` 介绍栏 → 这是 mobile-prototype 规范，web 后台用「详情按钮 + 弹窗」
- ❌ placeholder.com 等占位图 → 用 CSS 几何图形或色块
- ❌ 生产级路由 → 用 `location.href` 跳转
- ❌ Redux / Vuex 等状态库 → 用 `store.js`（sessionStorage 包装）
- ❌ 写死 hex 颜色在共享样式中 → 用 CSS 变量
- ❌ 各页样式完全独立 → 必须共享 `base.css` / `prototype-intro.css`
- ❌ 写死预览端口号 → `launch.json` 用 `autoPort: true`
- ❌ 简单原型强制写 plan.html → 2 页以内的原型不需要
- ❌ 把管线 / 公式拆成功能卡，或在 plan 扫读层堆段落 → 公式条 + `<details>` 下转
- ❌ 已有本地化框架却自写平行组件 → 先查框架，框架无此组件才自写并注释原因
- ❌ 引用外网 CDN 框架 css/js → 必须本地化到本项目仓库的 `prototypes/shared/`

---

## 使用流程

### 场景 A：从零开始一套新原型

1. 用 scaffold.js 生成骨架：

```bash
node ~/.claude/skills/web-admin-prototype/scaffold.js \
  --name "tenant-storage-management-v1" \
  --title "租户空间存储管理" \
  --pages "index:入口页, list:数据列表, detail:详情弹窗" \
  --roles "运营管理员·张伟"
```

2. 用 `frontend-design` skill 生成每页真实原型内容（在 `.desktop-preview` 内）
3. 按详情弹窗规范填 `.detail-modal` 内的 5 块介绍内容
4. plan.html 按需生成（页面 ≥ 3 时）
5. 用 preview server 在浏览器验证

### 场景 B：已有原型加新页

1. 拷贝现有页（如 list.html）作为模板
2. 替换 `.desktop-preview` 内的原型内容
3. 按详情弹窗规范重写 `.detail-modal` 介绍内容
4. 在 plan.html 的「页面清单」grid 里加一张新卡

### 场景 C：修改已有页

1. 直接改对应的 `.html` / `.css` / `.js`
2. 不要动共享样式（prototype-intro.css / plan.css / base.css）
3. 改完用浏览器验证

---

## 模板文件清单

| 文件 | 用途 |
|---|---|
| `templates/page.html.tpl` | 单页骨架（单列桌面预览 + 详情按钮弹窗） |
| `templates/plan.html.tpl` | 方案总览骨架（精简版） |
| `templates/launch.json.tpl` | 预览服务配置 |
| `templates/styles/prototype-intro.css` | 介绍区样式（从 mobile-prototype 共享） |
| `templates/styles/base.css` | 桌面端基础样式 |
| `templates/styles/plan.css` | plan.html 专用样式 |
| `templates/scripts/store.js` | 跨页状态层 |
| `templates/scripts/data.js` | 共享数据骨架 |