back
loading skill details...
通用页面原型设计技能。基于 58种设计风格（默认Figma 风格） UI 的复杂业务系统 HTML 原型开发， 包括标准页面结构、统计卡片、筛选条件、数据表格、弹窗设计。 适用场景：(1) 创建新的管理页面原型 (2) 对照业务文档实现功能模块 (3) 设计弹窗和详情页 (4) 构建带看板和列表视图的页面。 **...
---
name: prototype-design
description: |
通用页面原型设计技能。基于 58种设计风格（默认Figma 风格） UI 的复杂业务系统 HTML 原型开发，
包括标准页面结构、统计卡片、筛选条件、数据表格、弹窗设计。
适用场景：(1) 创建新的管理页面原型 (2) 对照业务文档实现功能模块
(3) 设计弹窗和详情页 (4) 构建带看板和列表视图的页面。
**样式选择**：内置58+设计系统，直接引用 `references/design-systems/` 目录。
使用时指定 DESIGN_SYSTEM=<名称> 即可应用对应设计风格。
origin: openclaw
last_updated: 2026-04-14
changelog:
- 2026-04-14: 初始版本，从 WMS 项目经验中沉淀
- 2026-04-14: 新增长对话上下文管理章节
- 2026-04-14: 新增 WMS 项目实战经验（10条核心教训）
---
# 原型设计技能
## When to Use（何时使用）
- 用户要求创建新的管理页面原型
- 需要实现业务文档中的功能模块
- 需要设计弹窗、详情页
- 需要构建带看板或列表视图的页面
- 涉及 HTML/CSS/JS 前端代码的原型开发
## How to Use（如何使用）
### 1. 项目初始化
```bash
mkdir -p project/{pages,styles,scripts}
cd project
```
### 2. 设计系统选择
内置设计系统（`references/design-systems/`）：
- 默认：`figma-DESIGN.md`
- 管理后台：`linear-DESIGN.md`
- 简约专业：`vercel-DESIGN.md`
# 原型设计技能
通用页面原型开发指南，支持58+设计系统风格。
## 项目结构
```
project/
├── index.html # 单页应用入口
├── pages/ # 页面模块
│ ├── dashboard.html
│ ├── staff.html
│ └── ...
├── styles/
│ └── main.css # 全局样式
└── scripts/
└── main.js # 全局脚本
```
## 设计系统选择
**重要**：设计系统文件位于 `references/design-systems/` 目录。
### 使用步骤
1. **确定设计风格**：根据项目需求选择设计系统
- 管理后台常用：Figma、Linear、Notion、Vercel
- 电商/消费：Airbnb、Spotify、Stripe
- 企业级：IBM、Salesforce
2. **读取对应 DESIGN.md**
```bash
cat references/design-systems/figma-DESIGN.md
```
3. **应用设计规范**
- Color Palette → CSS变量
- Typography → 字体规范
- Component Stylings → 组件样式
### 常用设计系统快速参考
| 风格 | 设计系统 | 特点 |
|------|---------|------|
| 默认 | `figma-DESIGN.md` | 多彩色、现代 |
| 管理后台 | `linear-DESIGN.md` | 紫色主题、精致 |
| 简约专业 | `vercel-DESIGN.md` | 黑白精准、极简 |
| 温暖风格 | `notion-DESIGN.md` | 暖色极简 |
| 企业级 | `stripe-DESIGN.md` | 紫色渐变、高级感 |
## 标准页面结构
```html
<div id="page-xxx" class="page">
<!-- 1. Header -->
<header class="header">
<div class="header-left">
<h2>页面标题</h2>
<div class="breadcrumb"><span>首页</span><span>/</span><span>当前路径</span></div>
</div>
<div class="header-right">
<button class="btn btn-outline btn-sm">导出</button>
<button class="btn btn-primary btn-sm" onclick="openAddModal()">新增</button>
</div>
</header>
<!-- 2. 统计卡片 -->
<div class="stats-grid" style="grid-template-columns:repeat(4,1fr);">
<div class="stat-card">
<div class="stat-card-title">标题</div>
<div class="stat-card-value">数值</div>
<div class="stat-card-change">描述</div>
</div>
</div>
<!-- 3. 筛选条件 -->
<div class="table-filters">
<div class="filter-group">
<span class="filter-label">字段名</span>
<input type="text" class="filter-input" placeholder="提示...">
</div>
</div>
<!-- 4. 数据表格 -->
<table>
<thead><tr><th>字段1</th><th>字段2</th><th>操作</th></tr></thead>
<tbody>
<tr>
<td>数据</td>
<td><span class="tag tag-success">状态</span></td>
<td><button class="btn btn-sm btn-outline">详情</button></td>
</tr>
</tbody>
</table>
</div>
```
## 弹窗设计规范
### 标准弹窗模板
```html
<!-- 遮罩 + 居中弹窗 -->
<div id="modal-xxx" style="
display:none;
position:fixed;
top:0;left:0;right:0;bottom:0;
background:rgba(0,0,0,0.6);
z-index:1000;
align-items:center;
justify-content:center;
">
<!-- 内容框 -->
<div style="
background:white;
border-radius:16px;
width:560px;
max-width:90vw;
max-height:85vh;
overflow:hidden;
box-shadow:0 25px 80px rgba(0,0,0,0.35);
">
<!-- 标题栏 -->
<div style="
padding:20px 24px;
border-bottom:1px solid #E5E7EB;
display:flex;
align-items:center;
justify-content:space-between;
background:#F9FAFB;
">
<h3 style="margin:0;font-size:18px;font-weight:600;color:#111827;">弹窗标题</h3>
<button onclick="closeModal()" style="
border:none;
background:none;
font-size:24px;
color:#6B7280;
cursor:pointer;
padding:4px;
line-height:1;
">×</button>
</div>
<!-- 内容区 -->
<div style="
padding:24px;
overflow-y:auto;
max-height:calc(85vh - 140px);
">
<!-- 表单项示例 -->
<div style="display:grid;grid-template-columns:1fr 1fr;gap:20px;">
<div>
<label style="display:block;font-size:14px;font-weight:500;margin-bottom:8px;color:#374151;">
字段名 <span style="color:#EF4444;">*</span>
</label>
<select style="
width:100%;
padding:10px 12px;
border:1px solid #E5E7EB;
border-radius:8px;
font-size:14px;
background:white;
">
<option value="">请选择</option>
<option>选项1</option>
<option>选项2</option>
</select>
</div>
<div>
<label style="display:block;font-size:14px;font-weight:500;margin-bottom:8px;color:#374151;">字段名</label>
<input type="text" placeholder="请输入" style="
width:100%;
padding:10px 12px;
border:1px solid #E5E7EB;
border-radius:8px;
font-size:14px;
box-sizing:border-box;
">
</div>
</div>
<div style="margin-top:16px;">
<label style="display:block;font-size:14px;font-weight:500;margin-bottom:8px;color:#374151;">备注</label>
<textarea rows="3" placeholder="请输入备注" style="
width:100%;
padding:10px 12px;
border:1px solid #E5E7EB;
border-radius:8px;
font-size:14px;
resize:none;
box-sizing:border-box;
"></textarea>
</div>
</div>
<!-- 底部按钮 -->
<div style="
padding:16px 24px;
border-top:1px solid #E5E7EB;
display:flex;
justify-content:flex-end;
gap:12px;
background:#F9FAFB;
">
<button onclick="closeModal()" style="
padding:10px 20px;
border:1px solid #E5E7EB;
background:white;
border-radius:8px;
font-size:14px;
font-weight:500;
color:#374151;
cursor:pointer;
">取消</button>
<button onclick="saveData()" style="
padding:10px 20px;
border:none;
background:#4F46E5;
color:white;
border-radius:8px;
font-size:14px;
font-weight:500;
cursor:pointer;
">保存</button>
</div>
</div>
</div>
```
### 弹窗样式要点（必记）
| 元素 | 样式属性 | 正确值 | 常见错误 |
|------|---------|--------|---------|
| **外层遮罩** | `position` | `fixed` | 用 `absolute` 会滚动 |
| **遮罩背景** | `background` | `rgba(0,0,0,0.6)` | `0.5` 太淡，`0.7` 太浓 |
| **遮罩定位** | `top/left/right/bottom` | `0`（全屏覆盖） | 忘记设置任一边 |
| **弹窗容器** | `display` | `flex` | 父级用 flex 居中 |
| **居中方式** | `align-items + justify-content` | `center` + `center` | 缺少任一属性 |
| **内容框圆角** | `border-radius` | `16px` | `12px` 不够现代 |
| **内容框宽度** | `width` | `560px` 或 `90vw` | 固定 px 在小屏幕不友好 |
| **内容框高度** | `max-height` | `85vh` | `80vh` 可能显示不全 |
| **阴影** | `box-shadow` | `0 25px 80px rgba(0,0,0,0.35)` | 太淡看不出层次 |
### 表单项样式要点
| 元素 | 样式属性 | 正确值 |
|------|---------|--------|
| **输入框/下拉框** | `padding` | `10px 12px` |
| **输入框/下拉框** | `border-radius` | `8px` |
| **输入框/下拉框** | `border` | `1px solid #E5E7EB` |
| **输入框/下拉框** | `font-size` | `14px` |
| **textarea** | `resize` | `none` |
| **textarea** | `box-sizing` | `border-box` |
| **必填标记** | color | `#EF4444` (红色) |
### ⚠️ 常见错误
1. **不要使用 CSS 类名**：如 `class="modal"`、`class="btn btn-primary"` - 这些类通常没有定义样式或样式被覆盖
2. **必须使用内联样式**：弹窗组件应完全使用内联样式，避免外部 CSS 干扰
3. **遮罩层必须有 `z-index:1000`**：确保在最上层
4. **内容框不能用 `overflow:hidden`**：内容超出需要滚动，必须用 `overflow-y:auto`
## 看板视图
```html
<div style="display:grid;grid-template-columns:repeat(5,1fr);gap:16px;">
<!-- 列 -->
<div style="background:#F9FAFB;border-radius:12px;padding:16px;">
<div style="display:flex;justify-content:space-between;padding-bottom:12px;border-bottom:1px solid #E5E7EB;">
<span>待开始</span>
<span style="background:#FEE2E2;color:#DC2626;padding:2px 8px;border-radius:10px;font-size:12px;">5</span>
</div>
<div style="background:white;border-radius:8px;padding:12px;margin-top:12px;cursor:pointer;" onclick="showDetail()">
<div style="font-weight:500;">单号</div>
<div style="font-size:12px;color:#6B7280;">描述</div>
</div>
</div>
</div>
```
## Tab 切换
```html
<div class="tabs" style="margin-bottom:24px;">
<button class="tab active" onclick="switchTab('tab1')" style="background:#EEF2FF;color:#4F46E5;">Tab1</button>
<button class="tab" onclick="switchTab('tab2')" style="background:#F3F4F6;color:#6B7280;">Tab2</button>
</div>
```
## ⚠️ 重要：保持 index.html 同步
**问题现象**：更新 `pages/xxx.html` 后，直接打开 `index.html` 查看不会看到变化。
**原因**：`index.html` 是单页应用入口，包含所有页面的内嵌副本。`pages/` 目录的修改不会自动同步。
### 🔴 弹窗必须放在页面 div 内部
**常见错误**：弹窗 HTML 放在 `</div>` (页面关闭标签) **之后**
```html
<!-- ❌ 错误：弹窗在页面 div 外部 -->
<div id="page-xxx" class="page">
...页面内容...
</div>
<!-- 弹窗在这是错误的 -->
<div id="modal-xxx" style="display:none...">弹窗内容</div>
<!-- ✅ 正确：弹窗必须在页面 div 内部 -->
<div id="page-xxx" class="page">
...页面内容...
<!-- 弹窗放在这里 -->
<div id="modal-xxx" style="display:none...">弹窗内容</div>
</div>
```
### 🔴 Tab 切换函数必须使用页面级作用域
**常见错误**：使用全局选择器 `.tabs .tab` 会影响所有页面
```javascript
// ❌ 错误：会选择页面上所有的 tab
const tabs = document.querySelectorAll('.tabs .tab');
// ✅ 正确：使用页面级作用域
const tabs = document.querySelectorAll('#page-xxx .tabs > .tab');
```
**Tab 切换函数模板**：
```javascript
function switchXxxTab(tabName) {
// 1. 隐藏所有 tab 内容
document.querySelectorAll('.xxx-tab').forEach(t => t.style.display = 'none');
// 2. 显示选中的 tab 内容
document.getElementById('xxx-' + tabName).style.display = 'block';
// 3. 更新 tab 按钮状态（使用页面级作用域）
const tabs = document.querySelectorAll('#page-xxx .tabs > .tab');
tabs.forEach((t, i) => {
if (i === /* 当前tab索引 */) {
t.style.background = '#EEF2FF';
t.style.color = '#4F46E5';
} else {
t.style.background = '#F3F4F6';
t.style.color = '#6B7280';
}
});
}
```
### ✅ 同步脚本
**解决方案**：每次创建/更新 `pages/` 目录的页面后，必须运行以下同步脚本：
```bash
cd project
python3 << 'PYEOF'
import os
import re
# 1. 读取当前index.html
with open('index.html', 'r', encoding='utf-8') as f:
content = f.read()
# 2. 获取pages/目录下所有html文件（按文件名排序）
pages_dir = 'pages'
page_files = sorted([f for f in os.listdir(pages_dir) if f.endswith('.html')])
# 3. 对每个页面文件，提取 <div id="page-xxx" 内容
for page_file in page_files:
with open(os.path.join(pages_dir, page_file), 'r', encoding='utf-8') as f:
page_content = f.read()
# 提取 page-xxx 块的完整内容
match = re.search(r'(<div id="(page-\w+)"[^>]*class="page"[^>]*>.*?<script>\s*function \w+Open\w+Modal)', page_content, re.DOTALL)
if not match:
match = re.search(r'(<div id="(page-\w+)"[^>]*class="page"[^>]*>.*?)(<!--\s+<div id="page-)', page_content, re.DOTALL)
if match:
page_id = match.group(2)
page_block = match.group(1).strip()
# 在index.html中查找并替换对应的page块
# 匹配模式：<div id="page-xxx" class="page">...</div> 或 <div id="page-xxx" class="page">...<div id="page-yyy"
pattern = rf'(<div id="{re.escape(page_id)}"[^>]*class="page"[^>]*>)(.*?)((?=<div id="page-)|(?=<script>\s*$)|(?=</main>)|(?=</body>))'
existing = re.search(pattern, content, re.DOTALL)
if existing:
content = content[:existing.start()] + page_block + content[existing.end():]
print(f'✓ Updated: {page_id}')
else:
print(f'⚠ Not found in index: {page_id}')
else:
print(f'⚠ No page block found in: {page_file}')
# 4. 写回index.html
with open('index.html', 'w', encoding='utf-8') as f:
f.write(content)
print('\n✅ Sync complete!')
PYEOF
```
**重要提示**：
- ❌ 不要跳过同步步骤
- ❌ 不要只更新 `pages/` 目录就以为完成了
- ✅ 每次修改后都要运行同步脚本，再验证 `index.html`
---
## 组件命名规范
| 组件 | 类名 |
|------|------|
| 页面容器 | `.page` |
| 页头 | `.header` |
| 内容区 | `.content` |
| 统计卡片 | `.stat-card` |
| 表格卡片 | `.table-card` |
| 按钮-主要 | `.btn .btn-primary` |
| 按钮-次要 | `.btn .btn-outline` |
| 标签 | `.tag` |
| 状态 | `.status` |
| 分页 | `.pagination` |
## 重建 index.html
```bash
cd project
python3 << 'PYEOF'
page_order = ['dashboard', 'page1', 'page2', ...]
pages = [open(f'pages/{p}.html').read() for p in page_order]
html = f'''<!DOCTYPE html>
<html>
<head>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700" rel="stylesheet">
<link rel="stylesheet" href="styles/main.css">
</head>
<body>
<div class="layout">
<aside class="sidebar">...</aside>
<main class="main">
{chr(10).join(pages)}
</main>
</div>
<script src="scripts/main.js"></script>
</body>
</html>'''
open('index.html','w').write(html)
PYEOF
```
## 常见问题速查表
| 问题 | 症状 | 解决方案 |
|------|------|----------|
| 弹窗打不开 | `xxx is not defined` | 检查 main.js 引用位置和函数定义 |
| Tab 选中态错乱 | 所有 Tab 同时选中 | 用页面级作用域选择器 |
| Hash URL 不工作 | 页面 `display:none` | 添加 hashchange 监听 |
| 表格侵入侧边栏 | 横向滚动时布局乱 | 用 Ant Design 固定表头表格 |
| 复选框丢失 | 数据行没有 checkbox | 手动添加每个数据行的复选框 |
| 同步后功能失效 | 弹窗/按钮不工作 | 检查 script 标签格式和 div 平衡 |
---
## 长对话上下文管理（重要）
### 问题背景
当对话持续较长时，上下文窗口会逐渐积累历史消息，可能导致：
- 模型响应变慢
- token 超出限制
- 早期上下文被遗忘
### 解决方案：自动压缩 + 分阶段提交
#### 1. 自动 Compaction（对话压缩）
OpenClaw 会自动对长对话进行 compaction（压缩）：
- 将对话历史压缩成一个 `summary` 摘要
- 保留关键的项目进展、决策、待办事项
- 释放大量 token 空间
**触发时机**：通常在上下文累积到一定量时自动进行，无需手动干预
#### 2. Compaction 后的处理流程
当收到 compaction 后的新对话时，立即执行以下步骤：
```
1️⃣ 读取 summary 摘要，理解当前项目状态
↓
2️⃣ 检查 memory/YYYY-MM-DD.md 文件
↓
3️⃣ 将新进展追加到 memory 文件
↓
4️⃣ 继续工作，保持文件平衡
```
#### 3. 分阶段提交策略（小步提交）
**原则**：每个功能完成后立即提交，避免大量变更堆积
```bash
# ✅ 好的做法：功能完成即提交
git add -A && git commit -m "feat: 新增用户管理弹窗"
# ❌ 不好的做法：多个功能一起提交
git add -A && git commit -m "feat: 多项优化"
```
**好处**：
- 如果出问题，容易回溯
- 减少每次提交的文件变更量
- Compaction 后的 summary 更简洁
#### 4. 保持文件平衡
每次 HTML 修改后检查 div 平衡：
```bash
# 检查 div 平衡
python3 -c "
with open('index.html', 'r') as f:
c = f.read()
print(f'opens={c.count(\"<div\")}, closes={c.count(\"</div>\")}, diff={c.count(\"<div\")-c.count(\"</div>\")}')
"
# ✅ 正确输出：opens=xxx, closes=xxx, diff=0
# ❌ 错误输出：opens=xxx, closes=xxx, diff=≠0
```
**如果 diff 不为 0**，立即修复：
- 缺少 `</div>`：在合适位置添加
- 多余 `</div>`：删除多余的部分
#### 5. 定期同步到 memory 文件
每次 compaction 后或重要里程碑时，将进展写入 `memory/YYYY-MM-DD.md`：
```markdown
## 14:30 状态更新
### 功能名称 - 完善/修复
**新增内容**：
- 具体修改1
- 具体修改2
**提交记录**：`abc1234` feat: 描述
**文件**：`/path/to/file.html`
```
#### 6. 长对话工作流
```
用户提出需求
↓
理解现有代码结构（查看 summary + 文件）
↓
用 Python 脚本做精确文本替换
↓
修改完检查 div 平衡
↓
提交代码（每个功能单独提交）
↓
截图验证（如需要）
↓
回复用户
↓
（Compaction 自动触发时）
↓
读取 summary，追加进展到 memory 文件
```
### 为什么单页 HTML 不受上下文限制影响
WMS 原型是单页 HTML（`index.html`），3700+ divs：
- **不是日志文件**：不会无限增长
- **每次修改同一个文件**：不是追加模式
- **Compaction 只压缩对话历史**：不影响 HTML 文件本身
### 关键心态
> "我是 AI，每次醒来都是新的开始。但文件里的内容是我的记忆。"
- 上下文超限是 **对话历史** 被压缩，不是文件内容丢失
- HTML 文件本身不受影响
- 只要保持文件平衡和定期 commit，就能稳定工作
---
## 相关资源
- **内置设计系统**：`references/design-systems/` 目录包含58+设计系统完整规范
- 包含：Figma、Linear、Stripe、Vercel、Notion 等
- **字段规范**：[field-norms.md](references/field-norms.md) - 各模块标准字段定义
---
## 修改工作流（重要）
### 标准修改流程
每次对任何页面进行修改，必须遵循以下步骤：
```
1️⃣ 修改 pages/xxx.html
↓
2️⃣ 运行同步脚本 → 更新 index.html
↓
3️⃣ 本地测试 → 验证功能正常
↓
4️⃣ 提交代码 → git add + commit
```
### 🔴 第一步：修改 pages/xxx.html
在 `pages/` 目录的对应页面文件中进行修改：
- 弹窗 HTML 必须放在 `<div id="page-xxx" class="page">` 内部
- 脚本函数放在页面的 `<script>` 块中
### 🔴 第二步：同步到 index.html
**必须运行同步脚本**：
```bash
cd your-project-directory
python3 << 'PYEOF'
import os
import re
with open('index.html', 'r', encoding='utf-8') as f:
content = f.read()
pages_dir = 'pages'
page_files = sorted([f for f in os.listdir(pages_dir) if f.endswith('.html')])
for page_file in page_files:
with open(os.path.join(pages_dir, page_file), 'r', encoding='utf-8') as f:
page_content = f.read()
match = re.search(r'(<div id="(page-\w+)"[^>]*class="page"[^>]*>.*?)(?=<div id="page-|\s*<script>|\s*</main>)', page_content, re.DOTALL)
if not match:
print(f'⚠ Skip: {page_file}')
continue
page_id = match.group(2)
page_block = match.group(1).strip()
# 验证 div 平衡
opens = page_block.count('<div')
closes = page_block.count('</div>')
if opens != closes:
print(f'❌ Div imbalance in {page_id}: opens={opens}, closes={closes}')
continue
pattern = rf'(<div id="{re.escape(page_id)}"[^>]*class="page"[^>]*>)(.*?)(?=<div id="page-|\s*</main>)'
existing = re.search(pattern, content, re.DOTALL)
if existing:
content = content[:existing.start()] + page_block + content[existing.end():]
print(f'✓ Synced: {page_id}')
else:
print(f'⚠ Not found in index: {page_id}')
opens_all = content.count('<div')
closes_all = content.count('</div>')
print(f'\nDiv balance: opens={opens_all}, closes={closes_all}, diff={opens_all-closes_all}')
with open('index.html', 'w', encoding='utf-8') as f:
f.write(content)
print('✅ Sync complete!')
PYEOF
```
**重要检查**：
- 同步后必须验证 `index.html` 的 div 平衡（opens == closes）
- 如果不平衡，查找问题所在
### 🔴 第三步：本地测试
**启动本地服务器**（如果未运行）：
```bash
cd your-project-directory
npx http-server -p 8080 &
```
**测试步骤**：
```bash
# 1. 打开浏览器到首页
agent-browser goto http://localhost:8080
# 2. 导航到目标页面（使用 URL hash）
agent-browser goto http://localhost:8080/#page-name
# 3. 测试弹窗
agent-browser eval "openAddModal()" # 打开弹窗
agent-browser screenshot test-modal.png # 截图验证
agent-browser eval "closeModal()" # 关闭弹窗
# 4. 关闭浏览器
agent-browser close
```
**测试检查清单**：
- [ ] 页面正常加载
- [ ] 弹窗能打开
- [ ] 弹窗内容正确
- [ ] 弹窗能关闭
- [ ] Tab 切换正常（如有）
- [ ] 按钮点击有效
### 🔴 第四步：提交代码
```bash
cd your-project-directory
git add -A
git commit -m "fix: 描述修改内容"
```
---
## 📝 经验沉淀（2026-04-13）
### 问题1：弹窗函数无法调用（Uncaught ReferenceError）
**症状**：`openAddModal is not defined` 等错误
**根本原因**：
1. `main.js` 引用被同步脚本删除
2. 同步脚本移动了 `<script src="main.js"></script>` 位置
**解决方案**：
```javascript
// 确保 main.js 在 </main> 之后引入
</main>
<script src="scripts/main.js"></script>
</body>
```
### 问题2：所有 Tab 选中态不显示
**症状**：切换 Tab 时按钮背景色不变化，全部选中态显示错误
**根本原因**：Tab 切换函数使用全局选择器 `.tabs .tab` 会选中**所有页面**的 tab
**解决方案**：使用页面级作用域
```javascript
// ❌ 错误：会选择所有页面的 tab
document.querySelectorAll('.tabs .tab')
// ✅ 正确：只选当前页面的 tab
document.querySelectorAll('#page-xxx .tabs > .tab')
```
### 问题3：直接访问 hash URL 时页面不显示
**症状**：`http://localhost:8080/#delivery_return` 直接访问时页面 `display:none`
**根本原因**：没有 hashchange 监听，导航只用 click 事件
**解决方案**：在 main.js 添加 hash 路由监听
```javascript
// Hash 路由监听 - 支持直接访问 #page
window.addEventListener('hashchange', () => {
const hash = window.location.hash.replace('#', '');
if (hash) {
const navItem = document.querySelector(`[data-page="${hash}"]`);
if (navItem) {
navItem.click();
}
}
});
// 页面加载时检查 hash
if (window.location.hash) {
setTimeout(() => {
const hash = window.location.hash.replace('#', '');
const navItem = document.querySelector(`[data-page="${hash}"]`);
if (navItem) {
navItem.click();
}
}, 100);
}
```
### 问题4：表格横向滚动侵入左侧菜单
**症状**：表格内容多时，整个页面宽度被撑开，侵入左侧菜单栏
**根本原因**：
1. 表格使用 `width:100%` + `min-width:1400px` 矛盾
2. 容器没有正确设置 `overflow:hidden`
**解决方案**：使用 Ant Design 风格的固定表头表格
### 问题5：固定表头表格实现（Ant Design 风格）
**核心原理**：
1. **表头和表体分离** - 用两个独立的 `<table>`
2. **表头固定** - `overflow:hidden`，表头不滚动
3. **表体滚动** - `overflow:auto;max-height:440px`
4. **固定列用 `position:sticky`** - `left:0` / `right:0`
5. **固定表格布局** - `table-layout:fixed` + colgroup 定义列宽
**代码模板**：
```html
<!-- 外层容器 -->
<div class="ant-table-wrapper" style="display:flex;flex-direction:column;overflow:hidden;height:500px;">
<!-- 表头 - 固定不滚动 -->
<div class="ant-table-header" style="overflow:hidden;border-bottom:2px solid #E5E7EB;flex-shrink:0;">
<table style="table-layout:fixed;width:1800px;border-collapse:collapse;font-size:14px;">
<colgroup>
<col style="width:48px;"><!-- 复选框 -->
<col style="width:180px;"><!-- 单号 -->
<col style="width:100px;"><!-- 其他列... -->
<!-- ... -->
</colgroup>
<thead><tr>
<th style="position:sticky;left:0;background:#F9FAFB;z-index:4;"><input type="checkbox"></th>
<th style="position:sticky;left:48px;background:#F9FAFB;z-index:3;">单号</th>
<th>字段1</th>
<th>字段2</th>
<!-- ... -->
<th style="position:sticky;right:0;background:#F9FAFB;z-index:3;">操作</th>
</tr></thead>
</table>
</div>
<!-- 表体 - 独立滚动 -->
<div class="ant-table-body" style="overflow:auto;max-height:440px;">
<table style="table-layout:fixed;width:1800px;border-collapse:collapse;font-size:14px;">
<colgroup>
<!-- 与表头相同的列宽定义 -->
</colgroup>
<tbody>
<tr>
<td style="position:sticky;left:0;background:white;z-index:2;"><input type="checkbox"></td>
<td style="position:sticky;left:48px;background:white;z-index:2;">单号值</td>
<td>字段1值</td>
<!-- ... -->
<td style="position:sticky;right:0;background:white;z-index:2;"><button>操作</button></td>
</tr>
</tbody>
</table>
</div>
</div>
```
**关键样式**：
| 元素 | 样式 | 说明 |
|------|------|------|
| 表头 wrapper | `overflow:hidden;flex-shrink:0` | 不滚动 |
| 表体 wrapper | `overflow:auto;max-height:440px` | 垂直滚动 |
| 表头表格 | `table-layout:fixed;width:固定值` | 固定列宽 |
| 固定列 th/td | `position:sticky;left:0;z-index:2` | 左侧固定 |
| 右侧固定列 | `position:sticky;right:0` | 右侧固定 |
| 固定列背景 | `background:#F9FAFB` (表头) / `background:white` (表体) | 避免透明 |
### 问题6：筛选条件缺少查询/重置按钮
**解决方案**：
```html
<div class="table-filters">
<!-- 其他筛选字段... -->
<div class="filter-group" style="display:flex;gap:8px;">
<button class="btn btn-outline btn-sm" onclick="resetXxxFilters()">重置</button>
<button class="btn btn-primary btn-sm" onclick="searchXxx()">查询</button>
</div>
</div>
```
**对应 JS 函数**：
```javascript
function resetXxxFilters() {
document.querySelectorAll('#page-xxx .filter-select').forEach(s => s.selectedIndex = 0);
document.querySelectorAll('#page-xxx .filter-input').forEach(i => i.value = '');
}
function searchXxx() {
alert('查询功能 - 实际项目中会调用API过滤数据');
}
```
### 问题7：列表数据缺少复选框
**解决方案**：每行数据第一个 td 添加复选框
```html
<tr>
<td style="position:sticky;left:0;z-index:1;background:white;">
<input type="checkbox">
</td>
<td style="position:sticky;left:48px;z-index:1;background:white;">
<span style="font-family:monospace;font-weight:500;">FC-2026-0410-001</span>
</td>
<!-- 其他字段... -->
</tr>
```
### 问题8：script 标签格式导致同步失败
**症状**：同步后弹窗函数丢失
**原因**：`</script>` 后面没有正确换行，导致被当作 HTML 标签解析
**解决方案**：
```html
<!-- ❌ 错误 -->
<script>function foo(){}</script><div>
<!-- ✅ 正确 -->
<script>
function foo(){}
</script>
<div>
```
---
## 常见问题速查表
| 问题 | 症状 | 解决方案 |
|------|------|----------|
| 弹窗打不开 | `xxx is not defined` | 检查 main.js 引用位置和函数定义 |
| Tab 选中态错乱 | 所有 Tab 同时选中 | 用页面级作用域选择器 |
| Hash URL 不工作 | 页面 `display:none` | 添加 hashchange 监听 |
| 表格侵入侧边栏 | 横向滚动时布局乱 | 用 Ant Design 固定表头表格 |
| 复选框丢失 | 数据行没有 checkbox | 手动添加每个数据行的复选框 |
| 同步后功能失效 | 弹窗/按钮不工作 | 检查 script 标签格式和 div 平衡 |
---
## 📝 WMS 项目实战经验（2026-04-14）
### 经验1：弹窗 HTML 必须在页面 div 内部
**问题现象**："新增组织"按钮点击无反应，弹窗无法打开
**排查过程**：
1. 检查按钮 onclick 处理函数 → 存在
2. 检查 JavaScript 函数 → 存在
3. 检查弹窗 HTML 位置 → **发现弹窗放在了页面 div 外部**
**根本原因**：
```html
<!-- ❌ 错误：弹窗在页面 div 外部 -->
<div id="page-system_org" class="page">
...页面内容...
</div>
<!-- 弹窗在这里，页面关闭后的位置 -->
<div id="modal-add-org" style="display:none...">...</div>
<!-- ✅ 正确：弹窗必须在页面 div 内部 -->
<div id="page-system_org" class="page">
...页面内容...
<!-- 弹窗必须放在这里 -->
<div id="modal-add-org" style="display:none...">...</div>
</div>
```
**教训**：弹窗 HTML 放在 `</div>` (页面关闭标签) **之后**导致弹窗不显示。必须在页面 div 内部。
---
### 经验2：JavaScript 语法错误会导致整个脚本块失效
**问题现象**：修复弹窗位置后，按钮仍然无法点击
**排查过程**：
1. 使用 prototype-design 技能的调试方法
2. 检查 div 平衡 → 发现页面 div 缺少闭合标签
3. 修复 div 后检查脚本块 → 发现多余的 `}`
**根本原因**：`submitNewException()` 函数后有一个**多余的闭合括号 `}`**，导致 JavaScript 语法错误，整个脚本块无法执行
```javascript
// ❌ 错误：函数后有多余的 }
function submitNewException() {
// ...表单提交逻辑
}
//} <-- 多余的括号导致语法错误
// ✅ 正确：括号匹配
function submitNewException() {
// ...表单提交逻辑
}
```
**教训**：修改 HTML 时要确保 div 平衡；修改 JS 时要确保括号匹配。使用 Python 脚本做精确替换比手动编辑更安全。
---
### 经验3：按钮必须手动绑定 onclick
**问题现象**：新增弹窗后，弹窗中的按钮点击无反应
**根本原因**：新增的弹窗按钮**没有 onclick 属性**
**解决方案**：每个按钮都要显式绑定 onclick
```html
<!-- ❌ 错误：按钮没有 onclick -->
<button class="btn btn-primary">确定</button>
<!-- ✅ 正确：显式绑定 onclick -->
<button onclick="submitAddOrg()" class="btn btn-primary">确定</button>
```
**教训**：复制弹窗模板时，别忘了修改按钮的 onclick 属性。
---
### 经验4：按钮样式统一使用 CSS 类
**问题现象**：各页面按钮样式不统一，有内联样式如 `style="padding:10px 24px;"`
**解决方案**：统一使用 CSS 类
```html
<!-- ✅ 主按钮：黑色背景，胶囊形状 -->
<button class="btn btn-primary btn-sm">新增</button>
<!-- ✅ 次按钮：白色背景，灰色边框 -->
<button class="btn btn-outline btn-sm">取消</button>
```
**按钮样式规范**：
| 元素 | 类名 | 样式 |
|------|------|------|
| 主按钮 | `.btn .btn-primary` | 黑色背景 `#111827`，胶囊形 |
| 次按钮 | `.btn .btn-outline` | 白色背景，`#E5E7EB` 边框 |
| 按钮尺寸 | `.btn-sm` | `padding: 6px 12px; font-size: 12px` |
| 胶囊形状 | `border-radius: 50px` | 用于主、次按钮 |
---
### 经验5：Python 脚本精确替换避免手动错误
**问题现象**：手动编辑 HTML 时容易出现 div 不平衡、括号遗漏等问题
**解决方案**：使用 Python 脚本做精确文本替换
```python
with open('index.html', 'r') as f:
content = f.read()
# 替换前先备份
# ...
# 精确替换一段 HTML
old_text = '''<button class="btn btn-primary btn-sm">
新增模块
</button>'''
new_text = '''<button class="btn btn-primary btn-sm" onclick="openAddModuleModal()">
新增模块
</button>'''
content = content.replace(old_text, new_text)
with open('index.html', 'w') as f:
f.write(content)
# 验证 div 平衡
print(f'opens={content.count("<div")}, closes={content.count("</div>")}, diff={content.count("<div")-content.count("</div>")}')
```
**教训**：用 Python 脚本做精确替换，比手动编辑更可靠，尤其是涉及多行 HTML 时。
---
### 经验6：系统管理模块弹窗字段设计
**新增模块弹窗字段**：
| 字段 | 类型 | 说明 |
|------|------|------|
| 模块编码 | text | 必填，如 SYS_010 |
| 模块名称 | text | 必填 |
| 上级模块 | select | 无（顶级模块）/系统管理/基础档案... |
| 模块分类 | select | 系统管理/基础档案/作业配置... |
| 菜单层级 | select | 一级/二级/三级菜单 |
| 菜单图标 | text | emoji 格式 |
| 路由路径 | text | 如 /system/module |
| 排序 | number | 数字越小越靠前 |
| 状态 | select | 启用/禁用 |
| 备注 | textarea | 可选 |
**新增组织弹窗字段**：
| 字段 | 类型 | 说明 |
|------|------|------|
| 组织编码 | text | 必填，如 ORG_010 |
| 组织名称 | text | 必填 |
| 上级组织 | select | 母公司/北京仓/上海仓... |
| 组织类型 | select | 公司/仓库/部门/作业组 |
| 负责人 | text | 可选 |
| 联系电话 | tel | 可选 |
| 所在地区 | text | 如 北京市/朝阳区 |
| 状态 | select | 启用/禁用 |
| 组织地址 | textarea | 可选 |
**新增用户弹窗字段**：
| 字段 | 类型 | 说明 |
|------|------|------|
| 用户名 | text | 必填 |
| 登录密码 | password | 必填，6位以上 |
| 姓名 | text | 必填 |
| 手机号 | tel | 必填 |
| 邮箱 | email | 可选 |
| 所属组织 | select | 必填，北京仓-收货组/上海仓... |
| 用户角色 | select | 超级管理员/仓库管理员/作业员... |
| 岗位 | text | 可选 |
| 入职日期 | date | 可选 |
| 状态 | select | 正常/禁用/待审核 |
---
### 经验7：数据统计报表页面丰富度提升
**质量与异常报表增强**：
- 异常趋势图（近7天柱状图）
- 异常类型分布（货损42%/配送延误28%等）
- 闭环率分析（96.8%闭环率、2.5h平均处理时长）
**对账准确率监察增强**：
- KPI 从 4 个扩展到 6 个
- 新增已核销/核对中指标
**作业报表增强**：
- 新增时效达标率分析（拣货98.5%/上架97.8%等）
**库存报表增强**：
- 新增滞销库存预警（30天以上）
- 新增安全库存预警
---
### 经验8：复合条件定位按钮
**问题现象**：页面有多个相似按钮（如"新增"），用 `document.querySelector` 定位困难
**解决方案**：使用复合条件或更精确的选择器
```javascript
// ❌ 困难：页面有多个 btn-primary
document.querySelector('.btn.btn-primary')
// ✅ 更好：使用 onclick 属性定位
document.querySelector('button[onclick="openAddModuleModal()"]')
// ✅ 更好：在页面内部查找
document.querySelector('#page-system_module button[onclick="openAddModuleModal()"]')
```
---
### 经验9：修改后立即验证
**原则**：每次修改后立即验证，不要积累多个问题
**验证清单**：
```bash
# 1. 检查 div 平衡
python3 -c "with open('index.html') as f: c=f.read(); print(f'opens={c.count(\"<div\")}, closes={c.count(\"</div>\")}, diff={c.count(\"<div\")-c.count(\"</div>\")}')"
# 2. 截图验证
agent-browser goto http://localhost:8080/#page-name
agent-browser eval "openAddModal()"
agent-browser screenshot test-modal.png
agent-browser close
# 3. 提交代码
git add -A && git commit -m "feat: 描述"
```
---
### 经验10：单页 HTML 项目的好处
**为什么 WMS 原型用单页 HTML 没有问题**：
1. **Compaction 只压缩对话历史**：不影响 HTML 文件本身
2. **不是日志文件**：不会无限增长
3. **每次修改同一个文件**：不是追加模式
4. **3700+ divs 仍然高效**：文件体积适中，渲染快
**什么时候该拆分成多文件**：
- 单个文件超过 2MB
- 需要多人协作（git merge 冲突）
- 模块之间完全独立
don't have the plugin yet? install it then click "run inline in claude" again.