]*class="page"[^>]*>.*?` 后面没有正确换行，导致被当作 HTML 标签解析
**解决方案**：
```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
...页面内容...
...
```
**教训**：弹窗 HTML 放在 `
` (页面关闭标签) **之后**导致弹窗不显示。必须在页面 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 属性。
---
### 经验4：按钮样式统一使用 CSS 类
**问题现象**：各页面按钮样式不统一，有内联样式如 `style="padding:10px 24px;"`
**解决方案**：统一使用 CSS 类
```html
```
**按钮样式规范**：
| 元素 | 类名 | 样式 |
|------|------|------|
| 主按钮 | `.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 = '''
'''
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` 定位困难
**解决方案**：使用复合条件或更精确的选择器
```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(\"\")}, 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 冲突）
- 模块之间完全独立