# 工作台 HTML JS 常见问题

## 1. 重复函数声明导致页面白屏

**症状**：页面永远显示"加载中"，数据不出现，控制台无报错或报 `function already declared`

**根因**：patch 替换代码段时，新增的 `function refreshData()` 与原有同名函数冲突。
原代码中可能已有该函数，新增代码段末尾又声明了一次。

**排查**：
```bash
grep -n "function refreshData" 工具/销售工作台.html
# 如果出现 2 行 → 有重复，删除多余的一个
```

**修复**：写新代码前必须先 `grep` 检查目标函数是否已存在。如已存在，只替换逻辑体，不新增声明。

## 2. 搜索框 oninput 触发全页重渲染导致失焦

**症状**：搜索框每输入一个字符就丢失焦点，光标跳到末尾，无法连续输入

**根因**：`oninput="orderState.filterText=this.value;render()"` 每次按键触发 `render()`，
重建整个 DOM。搜索框被销毁后重建，`value` 虽然从 state 恢复但焦点和光标位置丢失。

**修复**（三步）：
1. 给搜索框加 `id`（如 `id="orderSearchInput"`）
2. 用 debounce 防抖（300ms）避免逐字重建
3. `render()` 之后在新 DOM 上 restore focus：
```javascript
oninput="var t=this,v=t.value,p=t.selectionStart;orderState.filterText=v;debounce(function(){render();var el=document.getElementById('orderSearchInput');if(el){el.focus();el.selectionStart=el.selectionEnd=p;}},300)()"
```

**注意**：`render()` 必须先于 `getElementById` 执行，因为 `render()` 才创建新 DOM 元素。

## 3. MCP 数据字段名与旧 JSON 不兼容

**症状**：MCP 数据加载成功但看板显示 0/空/无数据

**根因**：MCP 返回 `field_5ed7ab` 等原始 field_key，前端期望 `dept` 等可读字段名。
直接在 fetch 结果上访问 `c.dept` 得到 `undefined`。

**修复**：在 `fetchWithFallback` 中加 `adaptMcpFields(key, items)` 映射层。
每个数据类型（customers/orders/activities）独立映射，补全缺失的计算字段（如 `total: 0`）。