# app.html + index.html 合并踩坑记录 (2026-08-01)

## 背景
将 `index.html`（正式工作台，2900行）的完整 Tab 渲染体系合并到 `app.html`（测试页面，500行），同时保留 `app.html` 的业务线架构（line-aware TABS、邮箱登录、ls_groups 数据源）。

## 合并策略（Python 脚本）
```python
# 1. 保留 app.html 的 HTML head + login + CONFIG + auth + data loading
# 2. 从 index.html 提取 Navigation 之后的所有 render 函数
# 3. 拼接后写入
```

## 踩坑清单

### P1: 缺失变量（10+个）
Python 提取的是 index.html 中 `/* Navigation */` 之后的部分，但以下全局变量定义在 Navigation **之前**：
- `FEISHU_URL`, `FEISHU_CUSTOMER_URL`, `VISIT_CARD_API`, `FEISHU_NEW_ACTIVITY`
- `ACTIVITY_API`, `TODO_APIS`, `TODO_API_BASE`
- `CATS`, `CAT_COLORS`
- `USER_DEPTS`, `USER_DEPT_MAP`, `USER_AREA_MAP`
- `colorByRate`, `colorByDays`, `fmtW`, `esc`
- `TABS`（app.html 原本有，但被 merge 覆盖）
- `adaptMcpFields`, `extractLabel`

**教训**：合并前必须 grep 所有顶层 `var` 声明，完整复制。

### P2: DOM 结构不兼容
`app.html` 原 DOM：
```html
<div class="app-header">...</div>
<div class="app-main" id="appMain">...</div>
```

`index.html` render 函数期望：
```html
<header class="app-header">...</header>
<aside class="app-sidebar" id="sidebar"></aside>
<div id="custToolbar"></div>
<main class="app-main" id="main"></main>
<nav class="app-bottom-nav" id="bottomNav"></nav>
```

**必须对齐**，否则 `document.getElementById('sidebar')` 等全部返回 null。

### P3: `TABS is not defined`
`renderNav()` → `TABS.filter()` 崩溃。根因：`TABS` 在 app.html 的 CONFIG 区定义过，但 merge 时被 index.html 的代码覆盖了。

### P4: `adaptMcpFields is not defined`
`loadData()` 成功加载 10 个文件后调用 `adaptMcpFields()`，但该函数在 index.html 的 Navigation **之前**定义。需要从 index.html 第 755 行复制。

### P5: `fmtW is not defined` / `esc is not defined`
`renderDashboard` 大量使用 `fmtW()`、`esc()`、`colorByRate()`，这些是 index.html 第 508-513 行的全局 `var` 声明。必须复制。

### P6: `init()` 未执行 → `cbApp undefined`
2600 行的 `<script>` 底部调用 `init()`，但中间某个异常导致执行中断。
- `DOMContentLoaded` listener 在脚本底部注册时，事件早已触发 → 永远不执行
- **正确方案**：
```javascript
if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', init);
} else {
  init();
}
```

### P7: CDN 缓存遮蔽修复
CloudBase CDN TTL 5-10 min。每次部署后 `curl origin` 验证文件已更新，但浏览器看到的是边沿节点缓存的旧版。**验证手段**：`tcb hosting download` 确认 origin，浏览器等 5 min 后用无痕模式。

### P8: `doLogin` 按 email 查失败
`doLogin` 先 `tryQuery('email', email)` 再 `tryQuery('name', email)`。用户输入 `liuxinyuan`（拼音）时，email 字段无匹配，name 字段也无匹配（因为 name 是中文 `刘新元`）。用户需输入 `liuxinyuan@biori.com` 或 `刘新元`。

### P9: 函数重复定义导致旧版渲染
原始 app.html 有简版 `renderDashboard`，merge 后 index.html 的完整版在先，app.html 的简版在后 → 简版覆盖完整版。需删除旧的 `renderDiagDashboard`、`renderLifeScienceDashboard` 等函数。

### P10: `user_roles` 多文档导致下拉重复
同一用户在 CloudBase 中有多条文档（每个 dept 一条），`<select>` 下拉不除重 → 显示重复条目。改为邮箱/文本输入框解决。

## 检查清单（合并后必检）
```bash
# 1. 括号平衡
python3 -c "import re;html=open('app.html').read();..."
# 2. 关键函数存在
grep -c "function renderDashboard\|function renderOrders\|function renderCustomers\|var TABS\|function adaptMcpFields" app.html
# 3. 关键全局变量存在
grep -c "var FEISHU_URL\|var esc\|var fmtW\|var colorByRate" app.html
# 4. DOM 结构匹配
grep -c 'id="sidebar"\|id="main"\|id="dataTime"\|id="custToolbar"' app.html
```