---
name: baoyu-workbench-frontend-pitfalls
description: 工作台前端铁律：搜索框/空状态/函数声明/字段映射/Tunnel运维/邮箱登录/备份恢复/CDN部署/离线登录/JSON优先加载/全面体检/Tailscale端口冲突/双路径部署/进程管理/跨文件合并/CDN缓存/init自调用/看板筛选器权限/KPI税合计全局修复/Manager默认筛选/app.html入口/KPI三层递进/Q3当季卡片bug/目标数据污染检测。新增#107。
---
# 宝锐工作台前端开发铁律
> 涉及「某角色看到全公司数据」或「删除某块内容，所有账户都不展示」：先读 `references/company-wide-scope-and-block-removal.md`（全公司口径数据源清单 + 删块四步：两入口同改 → node --check → 保留下游控件 → 部署后 grep 线上残留=0 + sha 比对）。
>
> 涉及「把某类要求分单独类别统计」「再单列一类」「清洗得不完全，把漏的拿出来」：先读 `references/derived-category-classification.md`（两级关键词规则：强词含备注/弱词只看标题正文；语境排除；互斥 vs 叠加；分桶求和 == 总数的硬校验）。
>
> 涉及「布局不合理 / 排布不合理的排布」「手机上输入框被压扁」「改版面」「新建含动态增删行的表单页」：先读 `references/responsive-form-layout.md`（排查顺序=先量 DOM 再改、视觉模型结论当假设；动态行栅格模板必须写在 CSS 类里否则媒体查询覆盖不了；只写单轴定位会打乱整行；底栏与主内容边线对齐；互斥分支的 toggle 语义与不变量检查；程序化填表必须派发 input）。
>
> 涉及「表格某列超出页面范围 / 列被裁掉 / 要适应窄屏 / 缩放调合适」：先读 `references/wide-table-fit-in-iframe.md`（工作台 iframe 外层 overflow:hidden 会静默剪掉溢出列；四招压缩 + 横滑兜底；验收必须量 1024 宽）。
>
> 涉及「服务被杀了没人拉起」「改了看门狗脚本要验」「定时任务到底有没有生效」：先读 `references/service-watchdog-verification.md`（看门狗 MAP 字段陷阱、必须“真杀一次”才算验证、测脚本时不要用管道接输出）。
>
> 涉及「地址栏改 hash 不切页」「分享带错点的链接打不开对应 Tab」「截图预览四张一模一样」：先读 `references/hash-tab-spa-navigation.md`（hash 标签页必须挂 `hashchange` 监听；截图/探活每页要换 URL 参数）。
## 112. 工作台内嵌页改动的发布闭环 + 免登录渲染验证
**发布闭环（改 `工具/X.html` 后逐条做完，漏一条用户就看到旧版）**：
1. 提取内联 JS 跑 `node --check`。
2. **升工作台 `工具/index.html` 里该页 iframe 的 `?v=`**：iframe 的 URL 不变时浏览器直接吃缓存，页面改对了用户仍是旧样（`src="/工具/X.html?v=20260910g"` → 换新串）。这是「改完没生效」最常见的原因，不是部署失败。
3. 部署页面本身 + 部署 `工具/index.html` → `/workbench/index.html`（双路径，来自同一个本地文件）。
4. 线上**比内容不比状态码**（`curl -H 'Cache-Control: no-cache'`）并断言本地 == 线上逐字节 + 本地改动特征串在线上命中。
**权限/API 页的免登录渲染验证（过不了登录 ≠ 不能验）**：这类页面靠 token 调 `/api/...` 拉数据，浏览器里直接开只会看到「请先登录」。验证办法：用本机 8765 起 http 源打开页面（`file://` 下 fetch 被 CORS 挡），同源 `fetch('/数据/x.json')` 取**真实数据** → 手动赋 `DATA`（补上 `visible_customers` 这类 render 依赖字段）、显示 `#app`、调 `render()`，再断言 KPI 文案、芯片计数、筛选后行数、行内标签数。用真实数据而不是手造样本，才能暴露口径错。
## 111. 看板趋势图：分段图合并为全年 + 分段合计先核对（2026-09-20）
**改动形态**：把「📅 月度目标/达成趋势（H1/H2 分段切换）」与「📊 H2月度目标 vs 实际」两张卡并成一张全年 12 个月图 → 去掉 `state.h1h2` 分段按钮、删掉 H2 卡、`drawMonthlyChart(kpi)` 固定 12 个月，数据由 `getKPI()` 统一提供 `yearTargets`/`yearActuals`（admin 与个人**两个分支**都要加；个人分支 1–6 月目标为 0 是历史行为，不要临时发明）。
**合并两条独立序列前，先算两边合计再跟汇总卡对一遍**。H1 月目标来自 `h1Monthly.total.targets`、H2 月目标来自 `Σ kpiDashboard.depts[].h2_months`，而 KPI 卡的年度目标来自 `kpiDashboard.total_target` —— 三处各自展示时谁也看不出，合成一条曲线立刻自相矛盾（实测 3,255 万 + 4,786 万 = 8,041 万 ≠ 6,950 万，差 1,091 万）。**先把差异算出来报给用户定口径，再决定怎么上线**；不要默默发一条自己都对不上的曲线。
**12 个月标签必须窄屏自适应**：`el.clientWidth < 560` 时把 `1月…12月` 降级成 `1…12`。6 个月的图改成 12 个月后手机端必叠加（这是「分段改整年」新增的坑，不是原有问题）。
**数据源/当月口径全套对照表见 `references/dashboard-kpi-trend-data-sources.md`**（月度目标、逐月实际、年度目标卡片分别取哪个字段；当月为什么必须用 `kpiProgress` 覆盖快照）。同文件另有两节必读：**「月度目标：权威源与口径统一」**（权威源 = 年度拆解表的「汇总」表，按人×12 月；用「部门月合计 == 部门年度目标」判定哪份可信，公司目标下调后月度拆解常没同步）与 **「派生键防回归」**（注入 `workbench_data.json` 的新键必须同步加进 `merge_workbench_data.py` 的 `FILES` 映射并重跑 merge，否则管道重跑静默丢键、页面悄悄退回旧口径；改数据驱动的视图要**连 JSON 一起部署**）。
**验数据驱动改动要走本地服务**：`http://127.0.0.1:8765/工具/index.html` 打开再验（同源能直接 fetch `/数据/workbench_data.json`）。用 `file://` 打开时数据 fetch 失败，图表会**静默渲染成全 0**，极易误判为代码 bug（自己先白查一轮）。判定顺序：「图表全 0」→ 先查 `state.data` 是否真的加载到（长度/键数）→ 再怀疑绘图代码。
**部署回读的假警报**：`curl -sL "$url" | shasum` 在 curl 失败时拿到的是**空串 sha**（`e3b0c442...`），会被误读成「CDN 不一致」。改成 `curl -sL --retry 2 -m 30 "$url" -o /tmp/x` → 先 `wc -c` 确认有字节 → 再比 sha；并 `grep` 线上的新标记（新标题/新函数名）确认「部署的确是本次改动」，只看 sha 定位不到部署了什么。
## 6. 访前准备重点客户快捷入口
### 筛选规则：必须与 MCP `field_17186c` 标签重合
**重点客户 = MCP `field_17186c === 'A类'`**（不是取数组前 N 个）。374 个 A 类客户 / 1700 全量。
```javascript
// ❌ 错误：取前 10 个，不区分是否重点
var top10 = all.slice(0, 10);
// ✅ 正确：按 MCP field_17186c 筛选 A 类
var keyCustomers = all.filter(function(c) { return c.field_17186c === 'A类'; });
var top = keyCustomers.slice(0, 30);
```
### MCP 客户关键字段速查
| 字段 | 含义 | 示例值 |
|------|------|--------|
| `field_17186c` | 客户级别 | A类(374)/B类(136)/C类(884)/D类(306) |
| `field_e62869` | 产品线标签 | `[{label:"分子诊断"}]` / `[{label:"生命科学"}]` |
| `field_c3224b` | 集团简称 | "美吉集团" |
| `field_5ed7ab` | 销售部门 | "诊断原料销售拓展部" |
| `work_item_id` | 飞书项目工作项ID | 7057317049 |
`customer_levels.json` 中的 `level: "重点客户"` 是后续人工标注，与 MCP 原始分类独立。访前准备取 MCP 口径。
### 链接规则：跳转客户详情页，不用 create URL
```javascript
// ✅ 正确：FEISHU_URL + work_item_id 直达客户详情
return '...';
// ❌ 错误：硬编码 project_key=6593cd71471290e3cc6be6e6 创建活动
// 生命科学客户不在该空间 → "空间不存在"
return '...';
```
## 69. 订单下单人必须从飞书「下单人」角色获取，不能用客户 owner（2026-07-28）
**症状**：离职人员（黄文清/李丽佳）名下 58 个客户的所有订单仍显示他们为下单人。
**根因**：`pull_orders.py` 通过 `mcp_customers.json` 的 `owner` 字段映射创建者。离职人员的客户 owner 未更新。
**修复**：调用 `get_workitem_brief` API 获取每个订单的 `role_members`，提取「下单人」角色用户。逐订单查询（186次），用缓存文件 `order_role_cache.json` 避免重复。
```python
# 关键代码
result = mcp("get_workitem_brief", {"project_key": PK, "work_item_id": wid})
role_members = result.get('work_item_attribute', {}).get('role_members', [])
for rm in role_members:
if rm.get('name') == '下单人':
members = rm.get('members', [])
if members: xdr = {'name_cn': members[0].get('name', ''), 'email': members[0].get('email', '')}
```
**缓存**：`order_role_cache.json`（按 orderId 索引），已缓存的订单不会重复查询。
**效果**：黄文清 26 客户→0，李丽佳 32 客户→0。186/186 下单人角色全部命中。
## 47. 飞书链接格式校正（各空间不同）
| 空间 | 正确格式 |
|------|---------|
| 客户(`xsguanli`) | `https://project.feishu.cn/xsguanli/kh/detail/{id}` |
| 客诉(`br-shgl`) | `https://project.feishu.cn/br-shgl/khts/detail/{work_item_id}` |
| 通用(`baoyu`) | `https://project.feishu.cn/baoyu/workitem/{id}` |
**NOT** `baoyu/workitem/{id}` for everything. 定义专用常量避免串用。
## 7. Tunnel 运维（2026-07-26 起：Tailscale Funnel 固定域名）
**当前架构**：`https://macbook-air-2.tail6864e8.ts.net` → 127.0.0.1:8765（Tailscale Funnel，URL 永久固定）。trycloudflare 临时隧道已全部弃用（曾出现 3 个死 URL：times-edinburgh / gazette-pretty / drug-round-concert）。
```bash
# 检测 API 是否可用
curl -s --max-time 10 "https://macbook-air-2.tail6864e8.ts.net/api/todos" | head -c 20
# 无输出/超时 → 检查 Tailscale 是否在线
tailscale status --json | python3 -c "import json,sys;d=json.load(sys.stdin);print(d['Self']['Online'])"
# Funnel 状态
tailscale funnel status
# 恢复：tailscale up → tailscale funnel --bg --https=443 http://127.0.0.1:8765
```
### Tailscale Serve 端口冲突（2026-07-28 已踩坑）
**症状**：`python3 销售工作台服务.py 8765` 启动即报 `OSError: [Errno 48] Address already in use`，但 `lsof -i :8765` 无输出。
**根因**：Tailscale Serve/Funnel 可能已绑定该端口，但 `lsof` 不显示（沙箱进程）。`netstat -anv | grep 8765` 可看到所有者是 `io.tailscale.ipn`。
**诊断**：
```bash
netstat -anv | grep 8765 # → io.tailscale.ipn 即 Tailscale
tailscale serve status # 查看当前绑定的端口和代理目标
```
**修复**：
```bash
tailscale serve reset # 清除所有 serve 配置，释放端口
# 然后重启工作台服务
```
> ⚠️ `tailscale serve reset` 会清除所有 Funnel/Serve 配置。如需保留其他服务，用 `tailscale serve --https=<新端口> / http://127.0.0.1:8000` 迁移而非 reset。
## 76. CloudBase 双路径部署——`/index.html` 与 `/workbench/index.html` 是独立文件
这两条路径在 CloudBase 上是**完全独立**的文件，修改一处不会自动同步到另一处：
**本地源文件 → CloudBase 路径映射（铁律）**：
| 本地文件 | CloudBase 路径 | 部署命令 |
|---------|---------------|---------|
| `工具/index.html` | `/workbench/index.html` | `tcb hosting deploy 工具/index.html /workbench/index.html -e ...` |
| `工具/销售工作台.html` | `/工具/销售工作台.html` 或本地使用 | 仅本地 localhost:8765 部署，一般不上 CloudBase |
| `数据/workbench_data.json` | `数据/workbench_data.json` | 由 `cb_sync.sh` 自动部署 |
**⚠️ 关键陷阱**：用户通过飞书工作台入口访问的是 `/workbench/index.html`（由 `工具/index.html` 部署），**不是** `工具/销售工作台.html`。本地改 `销售工作台.html` 后如果不改 `index.html` 并重新部署到 CloudBase，用户永远看不到更新。
```bash
# 主入口（/index.html）—— 一般不用
tcb hosting deploy /tmp/index_workbench.html /index.html -e bier-sales-d0gatbvlx288724e9
# 飞书工作台入口（/workbench/index.html）—— 主力入口，源文件是 工具/index.html
tcb hosting deploy 工具/index.html /workbench/index.html -e bier-sales-d0gatbvlx288724e9
```
**检测**：
```bash
# 比较两处代码是否一致
curl -s -H "Cache-Control: no-cache" "https://bier-sales-...tcloudbaseapp.com/index.html?v=$(date +%s)" | md5
curl -s -H "Cache-Control: no-cache" "https://bier-sales-...tcloudbaseapp.com/workbench/index.html?v=$(date +%s)" | md5
```
用户说"工作台打不开"或"飞书里的工作台有问题"时，先确认他访问的是哪个路径，再部署对应位置。飞书应用通常引用 `/workbench/index.html`。
## 8. replace_all 铁律 + patch 转义陷阱
### replace_all 禁令
HTML/JS 混合文件严禁 replace_all=true——语义相同的代码片段可能在不同函数中，patch 会注入到错误位置。
### patch 工具 Escape-drift 陷阱
patch 工具处理含引号的 HTML 文件时，频繁报 Escape-drift detected 错误。这是工具链序列化问题，不是代码错误。
铁律：HTML 文件改动用 Python execute_code 直接读写替换，不用 patch：
with open('file.html', 'r') as f: content = f.read()
content = content.replace(old, new)
with open('file.html', 'w') as f: f.write(content)
单处简单替换仍可尝试 patch，遇 escape-drift 立即切 Python。
**真实案例**：用 `replace_all=true` 替换 `adaptMcpFields` 中的 `if (key === 'complaints') { return items; }`，结果也匹配了 `renderThreeYearMonthly` 中的 `cumY` 函数体内的相似代码，30 行投诉映射代码被注入到中间，导致：
- JS 语法错误 `Unexpected end of input`
- `init()` 未定义，登录下拉框空白
- 整个页面不可用
**恢复**：从备份 `销售工作台_backup_20260725.html` 恢复 → 部署 → Python 脚本批量安全重加改动。
**铁律**：
1. replace_all 仅用于极其唯一的常量字符串（如 Tunnel URL）
2. 同一语义多处出现时，加前后 3-5 行上下文使 old_string 唯一
3. 改完立即 `python3 -c "...re..."` 确认旧模式已清理 + `node --check` 验 JS 语法
4. 如果已损坏：从备份恢复优先于手动修复
## 11. 从备份恢复后的三步检查清单
`replace_all` 破坏后最可靠恢复路径：备份 → Python 批量应用 → 补齐遗漏。
**恢复后必查**（三道关，缺一不可）：
1. **CloudBase SDK**：备份可能是 v1（无 SDK）。确认文件中有 `', html, re.DOTALL)
for i, s in enumerate(scripts):
if not s.strip() or 'cloudbase' in s[:30]: continue # 跳过外部 SDK
o, c = s.count('{'), s.count('}')
if o != c: print(f'⚠ Script block {i}: {o} {{ vs {c} }}')
"
# 无输出 = 通过
```
**完整验证清单**（建议每次改 HTML 后跑一遍）：
```bash
# 1. 括号平衡
python3 -c "..." # 如上
# 2. 无重复 var 声明
for v in API_BASE_URLS ROLE_KEY TODO_PREFIX AUTO_REFRESH_MS refreshTimer; do
c=$(grep -c "var $v\s*=" 销售工作台.html)
[ $c -gt 1 ] && echo "⚠ $v: $c duplicates"
done
# 3. loadData 是 JSON 优先版本
grep -c "fallbackPath" 销售工作台.html # ≥ 2
# 4. 函数无重复声明
grep -c "function loadData" 销售工作台.html # = 1
```
## 64. Python HTTP 服务代码缩进——改一行崩全局（2026-07-27 多次血案）
**症状**：`python3 脚本/销售工作台服务.py` 启动即报 `IndentationError: expected an indented block`，服务器无法启动。
**根因**：用 Python `str.replace()` 直接修改服务文件时，新代码段的缩进层级与旧代码不匹配。`销售工作台服务.py` 的 `do_POST` handler 有 **3-4 层嵌套**（类→方法→if→try），每层 4 空格。替换时哪怕多/少一个空格都会导致 `IndentationError`。
**历史记录**（今天连续崩溃 4 次）：
1. 添加 `datetime.now()` 但忘记 `from datetime import datetime`
2. 插入队列代码块时 `try:` 后的缩进不对
3. IMA 搜索代码的 `try/except` 缩进层级混入外层作用域
4. 多次 replace 后整体缩进损坏，只能整段重写
**铁律**：
- **不要连续 replace 多次**——两次以上 replace 在 Python 文件上，缩进必定出问题
- **用整段重写替代多步 replace**：找到 handler 的起止行 → 删除中间全部 → 写入新的完整 handler
- **`python3 -c \"compile(open('file.py').read(),'test','exec');print('OK')\"`** 在每次修改后立即执行
- **加 `from datetime import datetime`** 是高频遗漏——任何包含 `datetime.now()` 的代码必须检查
**恢复方法**：
```python
# 找到 handler 的起止行注释（如 '拜访卡生成 API' 和 '原有 todos API'）
with open('销售工作台服务.py') as f: lines = f.readlines()
# 找到注解行，替换整段为刚写好的干净代码
lines[handler_start:handler_end] = [clean_code_block]
with open('销售工作台服务.py','w') as f: f.writelines(lines)
```
**症状**：赵云浩在手机飞书中点拜访卡链接 → 404 Not Found。
**根因**：拜访卡存在 Mac 本地（`客户管理/拜访卡/`），CloudBase 无此文件。Funnel 不通时无法访问。
**修复**：每次生成拜访卡后部署到 CloudBase：
```bash
tcb hosting deploy "客户管理/拜访卡/{文件名}.html" "客户管理/拜访卡/{文件名}.html" -e bier-sales-d0gatbvlx288724e9
```
**存档区链接**：用相对路径（CloudBase CDN 自动解析），不要硬编码 Funnel URL。
**结论**：`sessionStorage` 是唯一可靠的方案。已在工作台中实现，点击飞书卡片链接 → 登录后自动切订单管理+展开物流。
```javascript
// ', html, re.DOTALL)
for i, s in enumerate(scripts):
if not s.strip() or 'cloudbase' in s[:30]: continue # 跳过外部 SDK
o, c = s.count('{'), s.count('}')
if o != c: print(f'⚠ Script block {i}: {o} {{ vs {c} }}')
"
# 无输出 = 通过
```
**完整验证清单**（建议每次改 HTML 后跑一遍）：
```bash
# 1. 括号平衡
python3 -c "..." # 如上
# 2. 无重复 var 声明
for v in API_BASE_URLS ROLE_KEY TODO_PREFIX AUTO_REFRESH_MS refreshTimer; do
c=$(grep -c "var $v\s*=" 销售工作台.html)
[ $c -gt 1 ] && echo "⚠ $v: $c duplicates"
done
# 3. loadData 是 JSON 优先版本
grep -c "fallbackPath" 销售工作台.html # ≥ 2
# 4. 函数无重复声明
grep -c "function loadData" 销售工作台.html # = 1
```
- `references/email-login-migration.md` — 邮箱登录迁移全记录（CloudBase SDK 失效→后端 API 过程）
- `references/complaints-data-reference.md` — 客诉数据字段与 MQL 查询
- `references/feishu-customer-link.md` — 飞书客户链接路由（诊断原料 vs 生命科学）
- `references/mcp-field-mappings.md` — MCP 字段映射表
- references/pipeline-scripts.md — 客诉+客户数据管道脚本（pull_complaints.py / pull_customers.py）
### 商机沙盘隔离 + 混合类型筛选 + 可编辑字段（2026-07-27）
**隔离**：`renderOppSandbox` 对非 admin/manager 按 `o.sales === user.name` 过滤。赵云浩 339→29 条。
**混合类型筛选**：约 60% 商机的 `type` 字段是"增量/存量"，既不能归入纯存量也不能归入纯增量。筛选按钮从 `===` 改为 `indexOf` 匹配：
```javascript
// 聚合时：混合类型同时计入存量和增量
if ((o.type||'').indexOf('存量')>=0) s['存量'] += toWanSmart(o.target, o.sales);
if ((o.type||'').indexOf('增量')>=0) s['增量'] += toWanSmart(o.target, o.sales);
// 筛选时
var filteredOpps = s.opps.filter(function(o) {
return oppSandboxFilter === 'all' || (o.type||'').indexOf(oppSandboxFilter) >= 0;
});
```
**可编辑字段**：type 标签改为 `contenteditable="true"`，blur 时 `updateOppField(el)` 存 localStorage 并重渲染。Q1-Q4 达成已有 number input。
`renderOppSandbox` 数据来自 `opportunity_sandbox.json`（`d.opportunities`），`o.sales` 字段即销售员名。非 admin/manager 按 `state.user.name` 精确过滤：
```javascript
// 数据隔离：非admin只看自己的商机
var user = state.user || {};
if (user.role !== 'admin' && user.role !== 'manager') {
opps = opps.filter(function(o) { return o.sales === user.name; });
}
```
商户数据中 `dept` 字段可能为 NaN（数据源问题），不影响按 sales 名称的过滤准确度。每个商机展开后有 Q1-Q4 达成输入框，blur 自动存 localStorage。验证结果：赵云浩 339→29 条。
## 40. MCP `double_value` 0 值被 Python falsy 吞掉（2026-07-27 血案）
**症状**：`shipment_status.json` 中所有订单 `taxTotal`/`amount` 均为 None/0，但 MQL 原始数据中 `field_51d592` 有非零值（如 `double_value: 162000`）。拉取 1442 条订单，价税合计全 0。
**根因链**：
1. `pull_orders.py` 中 `parse_items` → `fields['field_51d592'] = v['double_value']` ✅ 正确存为数字 0
2. 输出映射：`'金额': o.get('field_51d592', '')` → 若值为 0，`o.get('field_51d592', '')` 返回 **`0`（整数）**
3. `shipment_pipeline.py` 中 `o.get('金额', '') or ''` → **Python 中 `0 or ''` = `''`**（0 是 falsy！），金额被吞掉
**同时还有另一个 bug**：MCP 有时把 `double_value` 包在数组里：`[{"double_value": 371396.45}]`。`parse_items` 只处理了 `v['double_value']`，未处理 `v` 是列表的情况。
**修复**（两处）：
```python
# 修复 1：parse_items 加数组解包（pull_orders.py）
if isinstance(v, list) and len(v) > 0: v = v[0]
# 修复 2：输出时用 != '' 替代 or ''（pull_orders.py）
# ❌ '价税合计': o.get('field_51d592', ''), ← 0 被吞
# ✅ 使用 o['field_51d592'] if 'field_51d592' in o and o['field_51d592'] != '' else ''
'金额': o.get('field_51d592') if o.get('field_51d592') is not None else '',
# 修复 3：shipment_pipeline 中 0 值检查
# ❌ tax_total = o.get('金额', '') or ''
# ✅ tax_total = o.get('金额') if o.get('金额') is not None else ''
```
**铁律**：处理 `double_value` 时必须意识到 **`0` 是合法金额**（免费样品/0 元单），不能用 `or ''` 作默认值判断。同样适用于所有 numeric MCP 字段。
## 62. 存档区客户名模糊匹配——文件名简称 vs MCP 全称（2026-07-27）
**症状**：赵云浩的万孚拜访卡不显示，但清单中有。
**根因**：文件名客户名是简称 `广州万孚`，`getVisibleCustomers()` 返回全称 `广州万孚生物技术股份有限公司`。`indexOf` 严格匹配失败。
**修复**：双向包含 + 逐字重叠匹配：
```javascript
// 双向包含
if (fullName.indexOf(shortName) >= 0 || shortName.indexOf(fullName) >= 0) matched = true;
// 逐字重叠兜底（2字滑动窗口）
if (!matched && shortName.length >= 3) {
for (var ci = 0; ci < shortName.length - 1; ci++) {
if (fullName.indexOf(shortName.slice(ci, ci+2)) >= 0) overlap++;
}
if (overlap >= 2) matched = true;
}
```
## 43. `moql_field_list` 为 None 导致管道崩溃（2026-07-27）
**症状**：`pull_orders.py --days 365` 在 page 45（2250 条）崩溃：`TypeError: 'NoneType' object is not iterable`。全年数据拉取中断，只有前 2250 条入库。
**根因**：某些 MQL 返回的 items 中 `moql_field_list` 是 `null`。`item.get('moql_field_list', [])` 无法拦截 None（只有 key 不存在才走 default）。
**修复**：
```python
# ❌ 错误：None 不走 default
for f in item.get('moql_field_list', []):
# ✅ 正确：显式处理 None
for f in (item.get('moql_field_list') or []):
```
**铁律**：所有 MQL 解析循环都必须用 `or []` 而不是 `.get(key, [])` 防护 None。
## 35. 联系人数据通过联系人类型反向聚合（2026-07-27）
客户类型的 `field_8c870a`（联系人数量）在 MCP 中全部为空。需要通过联系人类型反向聚合：
1. 拉取全部联系人（`65b8a6cacde27fd415d769ca`，8804条）
2. 每个联系人有 `field_6b3789`（联系人关联客户）→ 取 label（客户名）
3. 按客户名聚合 `name`（联系人名称）→ 列表
4. 输出的 `customer_contacts.json` 被 `adaptMcpFields` 引用，计算 `contacts.length`
```python
# pull_contacts.py 核心: SELECT name, field_6b3789, work_item_id FROM 销售管理.联系人
by_customer[field_6b3789.label].append(name)
```
## 32. 销售订单 → 顺丰物流数据管道（2026-07-27）
订单管理 Tab 的数据源是 `shipment_status.json`，由 `shipment_pipeline.py` 从 `mcp_orders_input.json` 读取 → 调顺丰 API 查轨迹。但 `mcp_orders_input.json` 之前依赖手动 ERP 导出，已断流。
### 修复：MQL 直拉销售订单
`pull_orders.py`（在 `数据/` 目录）用 MQL 从飞书拉取销售订单，输出到 `mcp_orders_input.json`，再触发 `shipment_pipeline.py`。
**销售订单关键字段**（type_key=`662612aea6bb7089fea044ef`，48459 条）：
| MCP 字段 | 飞书显示名 | 取值方式 | 用途 |
|---------|----------|---------|------|
| `name` | 单据编号 | string_value | 订单号 |
| `start_time` | 创建时间 | string_value | 日期 |
| `field_96a245` | 物流单号 | string_value | 顺丰查询 key |
| `field_e1001d` | 销售订单关联客户 | key_label_value.label | 客户名 |
| `field_51d592` | 价税合计 | **double_value** | 金额 |
| `work_item_id` | 工作项ID | long_value | 飞书链接 |
**MQL 查询**：`SELECT name, start_time, field_96a245, field_e1001d, field_51d592, work_item_id FROM 销售管理.销售订单 WHERE start_time >= "YYYY-MM-DD"`
### 管道流程
```
pull_orders.py (--days 90)
→ mcp_orders_input.json
→ shipment_pipeline.py (顺丰 API 查轨迹)
→ shipment_status.json (→ 订单管理 Tab)
```
**已知现象**：
- 旧单号（几个月前）顺丰返回"暂无数据"（正常，顺丰不保留历史轨迹）
- 今天创建的订单物流单号为空（正常，未发货）
- 重复单号自动去重（同一订单多个工作项行）
### 集成到定时刷新
当前顺丰 cron（9:20/15:20）运行 `sf_delivery_watchdog.py`，但未前置拉取订单。长期应把 `pull_orders.py` 作为 `cb_sync.sh` 的前置步骤，或在 `sf_delivery_watchdog.py` 中集成。
Hermes cron 的 `script` 字段**必须是 `~/.hermes/scripts/` 下的相对文件名**，不接受绝对路径或家目录相对路径。
**错误配置**（导致 Silent failure，`Script not found`）：
```
script: /Users/liuxinyuan/Desktop/Hermes输出-工作类/脚本/cb_sync.sh ❌
script: 脚本/cb_sync.sh ❌
```
**修复**：在 `~/.hermes/scripts/` 创建**包装脚本**用 `exec` 转发到真实位置：
```bash
#!/bin/bash
# ~/.hermes/scripts/cb_sync.sh
exec bash "/Users/liuxinyuan/Desktop/Hermes输出-工作类/脚本/cb_sync.sh"
```
然后 cron 配置 `script: cb_sync.sh`。
**检测**：`hermes cron list` → 查看上次执行状态是否为 `Script not found`。即使脚本在别处存在且可执行，cron 也只会搜 `~/.hermes/scripts/`。
## 85. KPI 税合计数据源全局修复（2026-08-01）
**核心原则**：shipment_status.json 中 75% 订单 taxTotal=0（MCP pipeline pitfall #40），**所有税合计计算必须改用 KPI 数据源**。
### 三个修复点
| 函数 | 之前 | 之后 |
|------|------|------|
| `renderDashboard` fullYearTax | `orders.reduce()` | `dash.total_h1 + prog.total` |
| `getShipmentOrders` fullYearTax | `shipments.full_year_tax \|\| 0` (始终0) | `dash.total_h1 + prog.total` |
| `renderOrders` 本月/本季/本年 | `ps.taxTotal` (orders汇总) | KPI覆盖（本月=prog.total, 本年=fullTax, 本季=prog.total） |
### 验证命令
```bash
curl -s "/数据/kpi_dashboard.json" | python3 -c "import json,sys;d=json.load(sys.stdin);print(f'H1: {d[\"total_h1\"]/1e4:.1f}万')"
curl -s "/数据/kpi_progress.json" | python3 -c "import json,sys;d=json.load(sys.stdin);print(f'7月: {d[\"total\"]/1e4:.1f}万')"
```
详见 `references/kpi-tax-fix-all-modules.md`。
## 91. app.html 缺失 `var TODO_PREFIX` → 待办 Tab 数据不更新（2026-08-23）
**症状**：用户报"工作台待办 Tab 还没更新"（数据已写入但前端看不到）。切待办 Tab 控制台报 `ReferenceError: TODO_PREFIX is not defined`（getTodoKey 内）。
**根因**：app.html 是双线分拆重构版，从 index.html 拆分时**遗漏了顶层变量 `var TODO_PREFIX = 'bior_sw_todos_v2_'`**（index.html L542 有，app.html 无），但 `getTodoKey()`、`renderClosedFeed()` 等 3 处都在用它。这是 #89（debounce 缺失）同类的「分拆遗漏顶层声明」bug，只是这次是**变量**不是函数。
**主动排查方法（通用，比逐个猜高效）**：对比两个文件的顶层 `var X =` / `function X()` 定义差集，再对每个「app 缺失」的 X 检查是否被使用：
```python
def extract_defs(path):
js = '\n'.join(re.findall(r']*>(.*?)', open(path, encoding='utf-8').read(), re.DOTALL))
return (set(re.findall(r'\bvar\s+(\w+)\s*=', js)),
set(re.findall(r'function\s+(\w+)\s*\(', js)))
app_v, app_f = extract_defs('工具/app.html')
idx_v, idx_f = extract_defs('工具/index.html')
missing = (idx_v - app_v) | (idx_f - app_f)
# 对每个 missing 的 X，re.search(r'\bX\b', app_js) 判断是否被使用；被使用才可能是真 bug
```
**⚠️ 误报过滤（关键）**：差集会混入大量误报，必须逐个看「首处上下文」`js[max(0,u-40):u+40]` 才能区分：
- CSS 属性：`font-size` 里的 `size`、`node-time` 里的 `time`
- HTML 标签：``、`