原型设计技能

📖 About This Skill

mkdir -p project/{pages,styles,scripts}
cd project

project/
├── index.html          # 单页应用入口
├── pages/              # 页面模块
│   ├── dashboard.html
│   ├── staff.html
│   └── ...
├── styles/
│   └── main.css        # 全局样式
└── scripts/
    └── main.js        # 全局脚本

   cat references/design-systems/figma-DESIGN.md
   

  
  

    

      
页面标题
      
首页/当前路径
    
    

      导出
      新增
    
  
  
  

    

      
标题
      
数值
      
描述
    
  
  
  

    

      字段名
      
    
  
  
  

    
字段1
字段2
操作
    

      

        
数据
        
状态
        
详情
      
    
  

  
  

    
    

      
弹窗标题
      ×
    
    
    

      
      

        

          
            字段名 *
          
          
            请选择
            选项1
            选项2
          
        
        

          字段名
          
        
      
      

        备注
        
      
    
    
    

      取消
      保存
    
  

  
  

    

      待开始
      5
    
    

      
单号
      
描述
    
  

  Tab1
  Tab2

  ...页面内容...


弹窗内容


  ...页面内容...
  
  
弹窗内容

🔴 Tab 切换函数必须使用页面级作用域

常见错误：使用全局选择器 .tabs .tab 会影响所有页面

// ❌ 错误：会选择页面上所有的 tab
const tabs = document.querySelectorAll('.tabs .tab');
// ✅ 正确：使用页面级作用域
const tabs = document.querySelectorAll('#page-xxx .tabs > .tab');

Tab 切换函数模板：

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/ 目录的页面后，必须运行以下同步脚本：

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. 对每个页面文件，提取 

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'(
]*class="page"[^>]*>.*? 后面没有正确换行，导致被当作 HTML 标签解析
解决方案：




常见问题速查表
| 问题 | 症状 | 解决方案 |
|------|------|----------|
| 弹窗打不开 | 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 内部。
经验2：JavaScript 语法错误会导致整个脚本块失效
问题现象：修复弹窗位置后，按钮仍然无法点击
排查过程：
1. 使用 prototype-design 技能的调试方法
2. 检查 div 平衡 → 发现页面 div 缺少闭合标签
3. 修复 div 后检查脚本块 → 发现多余的 }
根本原因：submitNewException() 函数后有一个多余的闭合括号 }，导致 JavaScript 语法错误，整个脚本块无法执行
// ❌ 错误：函数后有多余的 }
function submitNewException() {
  // ...表单提交逻辑
}
//}  <-- 多余的括号导致语法错误
// ✅ 正确：括号匹配
function submitNewException() {
  // ...表单提交逻辑
}
教训：修改 HTML 时要确保 div 平衡；修改 JS 时要确保括号匹配。使用 Python 脚本做精确替换比手动编辑更安全。
经验3：按钮必须手动绑定 onclick
问题现象：新增弹窗后，弹窗中的按钮点击无反应
根本原因：新增的弹窗按钮没有 onclick 属性
解决方案：每个按钮都要显式绑定 onclick

确定

确定
教训：复制弹窗模板时，别忘了修改按钮的 onclick 属性。
经验4：按钮样式统一使用 CSS 类
问题现象：各页面按钮样式不统一，有内联样式如 style="padding:10px 24px;"
解决方案：统一使用 CSS 类

新增

取消
按钮样式规范：
| 元素 | 类名 | 样式 |
|------|------|------|
| 主按钮 | .btn .btn-primary | 黑色背景 #111827，胶囊形 |
| 次按钮 | .btn .btn-outline | 白色背景，#E5E7EB 边框 |
| 按钮尺寸 | .btn-sm | padding: 6px 12px; font-size: 12px |
| 胶囊形状 | border-radius: 50px | 用于主、次按钮 |
经验5：Python 脚本精确替换避免手动错误
问题现象：手动编辑 HTML 时容易出现 div 不平衡、括号遗漏等问题
解决方案：使用 Python 脚本做精确文本替换
with open('index.html', 'r') as f:
    content = f.read()
替换前先备份
...
精确替换一段 HTML
old_text = '''
              新增模块
            '''
new_text = '''
              新增模块
            '''
content = content.replace(old_text, new_text)
with open('index.html', 'w') as f:
    f.write(content)
验证 div 平衡
print(f'opens={content.count("")}, diff={content.count("")}')
教训：用 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 定位困难
解决方案：使用复合条件或更精确的选择器
// ❌ 困难：页面有多个 btn-primary
document.querySelector('.btn.btn-primary')
// ✅ 更好：使用 onclick 属性定位
document.querySelector('button[onclick="openAddModuleModal()"]')
// ✅ 更好：在页面内部查找
document.querySelector('#page-system_module button[onclick="openAddModuleModal()"]')
经验9：修改后立即验证
原则：每次修改后立即验证，不要积累多个问题
验证清单：
# 1. 检查 div 平衡
python3 -c "with open('index.html') as f: c=f.read(); print(f'opens={c.count(\"\")}, diff={c.count(\"\")}')"
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 冲突）
模块之间完全独立