# 问题排查指南

本文档包含数数看板生成过程中的常见问题、诊断方法和解决方案。

## 快速诊断流程

```
遇到问题 → 运行诊断脚本 → 查看详细指南 → 应用解决方案
```

## 常见问题速查

| 问题 | 快速诊断 | 解决方案 |
|------|---------|---------|
| **🚨 生成配置内容错误** | 检查生成命令是否包含 `--from-feishu` | **重新生成并添加参数（参考 [Q0](#q0生成的配置不是飞书文档的内容而是默认的示例配置)）** |
| **🔴 固定值未作为筛选条件** | 检查报表的 `events[0].filts` 是否为空 | **已修复（2026-03-04），重新生成即可（参考 [Q14](#q14固定值字段未添加为筛选条件2026-03-04-修复)）** |
| **解析事件数量太少** | 运行 `python3 scripts/feishu_parser.py docs/xxx.md` | 手动创建 events_config（参考 [Q1](#q1解析到的事件数量太少怎么办)） |
| **配置无法导入** | 运行诊断脚本 [1](#1-字段完整性检查)、[2](#2-字段对比模板) | 检查 reportMappings 必需字段（参考[成功导入的关键要素](04-config-reference.md#成功导入的关键要素)） |
| **报表显示无数据** | 运行诊断脚本 [3](#3-全局筛选检查)、[4](#4-事件名称验证) | 检查 app_region 和事件名称拼写 |
| **报表数据混合了不同场景** | 检查是否缺少事件筛选条件 | 重新生成配置（参考 [Q14](#q14固定值字段未添加为筛选条件2026-03-04-修复)） |
| **报表数量超过30个** | 运行 `python3 scripts/split_dashboard.py xxx.json 30` | 自动拆分为多个批次 |

## 诊断工具

### 快速诊断命令

| 诊断项 | 命令 | 说明 |
|--------|------|------|
| **完整性校验** | `python3 scripts/validate_shushu_json.py docs/xxx.json` | 检查所有必需字段和格式 |
| **模板对比** | `python3 scripts/compare_with_template.py docs/xxx.json` | 对比生成文件与验证模板 |
| **看板拆分** | `python3 scripts/split_dashboard.py docs/xxx.json 30` | 拆分超过30个报表的看板 |

### 常用诊断技巧

**检查 reportMappings 字段：**
```bash
python3 -c "
import json
with open('docs/xxx.json') as f:
    data = json.load(f)
mapping = data['dashboardFolders'][0]['dashboards'][0]['reportMappings'][0]
print('字段列表:', list(mapping.keys()))
print('report_graph_shape:', mapping.get('report_graph_shape'))
"
```

**检查报表数量：**
```bash
python3 -c "
import json
with open('docs/xxx.json') as f:
    data = json.load(f)
print(f'报表数量: {len(data[\"reports\"])} (最多30个)')
"
```

## 快速修复方案

### 问题1：reportMappings 字段缺失

**症状**：导入成功但未创建报表

**快速修复**：
```bash
python3 scripts/validate_shushu_json.py docs/xxx.json
# 查看缺失字段，参考 examples/shushu_dashboard_template_verified.json 补全
```

### 问题2：app_region 值错误

**症状**：报表无数据

**快速修复**：
- 检查区服代码：C（华语服）、J（日服）、K（韩服）、M（美服）
- 使用 `scripts/validate_shushu_json.py` 检查全局筛选配置

### 问题3：事件名称拼写错误

**症状**：报表查询失败

**快速修复**：
- 检查生成的 JSON 文件中的 `eventName` 字段
- 在数数平台手动查询验证事件名称

## 预防措施

### 文档撰写
- ✅ 使用标准格式：`**事件名称：**ActivityTotal`
- ✅ 每个事件独立小节（###）
- ✅ 明确标注固定值：`= "value"`

### 生成配置
- ✅ 预览解析：`python3 scripts/feishu_parser.py docs/xxx.md`
- ✅ 立即验证：`python3 scripts/validate_shushu_json.py docs/xxx.json`
- ✅ 对比字段：参考 `examples/shushu_dashboard_template_verified.json`

### 导入前检查
- ✅ 文件大小：50K - 150K
- ✅ 报表数量：≤ 30
- ✅ 必需字段：运行综合检查脚本

## 常见问题详解

### Q0：生成的配置不是飞书文档的内容，而是默认的示例配置？⚠️

**问题现象**：

生成的JSON文件中，报表事件名称是 AppClick、EnterRoom、SendGift 等播棋相关事件，而不是飞书文档中定义的 ActivityTotal、ta_pageview、SendReward 等事件。

**原因分析**：

生成时**忘记添加 `--from-feishu` 参数**，导致脚本使用了硬编码的默认示例配置（播棋埋点），而不是从飞书文档读取。

**错误示例**：
```bash
# ❌ 缺少 --from-feishu 参数
python3 scripts/generate_shushu_json.py "C" "[五周年]导航页"

# 生成结果：使用默认配置（播棋），包含14个错误的报表
# - 报表1: 点击客户端首页入口 (AppClick)
# - 报表2: 游戏首页曝光 (AppViewScreen)
# - 报表3: 游戏首页场次点击 (AppClick)
# ...
```

**正确示例**：
```bash
# ✅ 必须添加 --from-feishu 参数
python3 scripts/generate_shushu_json.py "C" "[五周年]导航页" --from-feishu docs/feishu_doc.md

# 生成结果：正确解析飞书文档，包含15个正确的报表
# - 报表1: 1.1 每个阶段获得/消耗不同等級弹珠 (ActivityTotal)
# - 报表2: 1.2 获得额外充值优惠 (ActivityTotal)
# - 报表5: 2.1 活动页面曝光 (ta_pageview)
# ...
```

**验证方法**：

生成后立即检查前几个报表名称：
```bash
python3 -c "
import json
with open('docs/[五周年]导航页_数数看板_华语服.json', 'r', encoding='utf-8') as f:
    data = json.load(f)
for i, report in enumerate(data['reports'][:3], 1):
    name = report.get('reportName', '未命名')
    event = report['openQuery']['events'][0]['eventName']
    print(f'{i}. {name} ({event})')
"
```

**预期输出**（正确）：
```
1. 1.1 每个阶段获得/消耗不同等級弹珠用户数、获得/使用个数 (ActivityTotal)
2. 1.2 一、二阶段累计消耗达到 55 W 人数... (ActivityTotal)
3.  (ActivityTotal)
```

**错误输出**（忘记 --from-feishu）：
```
1. 点击客户端首页入口 (AppClick)
2. 游戏首页曝光 (AppViewScreen)
3. 游戏首页场次点击 (AppClick)
```

**解决方案**：

1. **重新生成**（推荐）：
   ```bash
   python3 scripts/generate_shushu_json.py "C" "[五周年]导航页" --from-feishu docs/feishu_doc.md
   ```

2. **标准工作流**：
   ```bash
   # 步骤1：获取飞书文档
   FEISHU_APP_ID=xxx FEISHU_APP_SECRET=xxx \
   python3 ../../../common/feishu2md/scripts/feishu2md.py \
   https://wepie.feishu.cn/wiki/xxxxx docs/feishu_doc.md

   # 步骤2：生成配置（必须加 --from-feishu）
   python3 scripts/generate_shushu_json.py "C" "活动名称" --from-feishu docs/feishu_doc.md

   # 步骤3：验证结果
   python3 scripts/validate_shushu_json.py docs/活动名称_数数看板_华语服.json
   ```

**预防措施**：

- ✅ 始终使用 `--from-feishu docs/feishu_doc.md` 参数
- ✅ 生成后立即检查前几个报表名称是否匹配
- ✅ 使用完整的标准工作流（获取文档 → 生成配置 → 验证结果）

**重要提醒**：

这是最容易犯的错误！`--from-feishu` 参数不是可选的，而是**从飞书文档生成看板的必需参数**。务必在每次生成时检查命令中是否包含此参数。

---

### Q1：解析到的事件数量太少怎么办？

**问题现象**：
```
📋 解析到的埋点事件:
   1. xxx (ActivityTotal)
   2. xxx (ActivityTotal)
   ...
✅ 数数看板配置生成成功！
   报表数量: 6
```
但实际文档中有 15+ 个埋点事件。

**原因分析**：
1. 文档使用了解析器不支持的格式（如【临时事件】、【组件事件】）
2. 同一小节包含多个事件，被合并识别
3. 特殊事件格式（CoinChange、SendReward）未被识别

**解决方案**：

**方法1：预览并确认（推荐第一步）**
```bash
# 先预览解析结果
python3 scripts/feishu_parser.py docs/feishu_doc.md

# 输出示例：
找到 6 个埋点事件：
1. xxx (ActivityTotal)
2. xxx (ActivityTotal)
...
```

对比文档章节数量，如果明显偏少，使用方法2。

**方法2：手动创建事件列表**

1. **创建 `docs/events_manual.json`**
   ```json
   [
     {
       "title": "1.1 获得弹珠",
       "event_name": "ActivityTotal",
       "event_filters": [],
       "group_by": ["activity_type", "action", "act_id"]
     },
     {
       "title": "1.2 消耗弹珠",
       "event_name": "ActivityTotal",
       "event_filters": [
         {"columnName": "action", "ftv": ["consume"]}
       ],
       "group_by": ["activity_type", "action", "act_id", "amount"]
     },
     {
       "title": "2.1 活动页面曝光",
       "event_name": "ta_pageview",
       "event_filters": [],
       "group_by": ["url", "url_path"]
     }
   ]
   ```

2. **使用手动配置生成**
   ```python
   import json
   import sys
   sys.path.insert(0, 'scripts')
   from generate_shushu_json import generate_shushu_dashboard

   # 读取手动配置
   with open('docs/events_manual.json', 'r') as f:
       events_config = json.load(f)

   # 生成看板
   dashboard_config, region_name = generate_shushu_dashboard(
       app_region="C",
       doc_title="活动埋点",
       events_config=events_config
   )

   # 保存
   output_file = f"docs/活动埋点_数数看板_{region_name}.json"
   with open(output_file, 'w', encoding='utf-8') as f:
       json.dump(dashboard_config, f, ensure_ascii=False, indent=2)
   ```

3. **验证结果**
   ```bash
   python3 scripts/validate_shushu_json.py docs/活动埋点_数数看板_华语服.json
   ```

**预防措施**：
- 撰写埋点文档时使用标准格式（见"飞书文档撰写最佳实践"）
- 每个事件单独写一个小节
- 使用"**事件名称：**"明确标记

---

### Q2：如何为同一事件创建多个报表（不同筛选条件）？

**场景**：
- ActivityTotal 事件包含多种玩法（lottery、charge_coupon、chip 等）
- 希望为每种玩法创建独立报表

**解决方案**：

在 `events_manual.json` 中为同一事件配置不同的 `event_filters`。

**完整示例**：`examples/events_config_example.json` 包含多个 ActivityTotal 事件的不同筛选配置（如抽奖、充值优惠、零食获得等），可直接参考。

这样会生成多个独立报表，每个报表只显示对应筛选条件的数据。

---

### Q3：如何修改全局筛选条件？

修改 `generate_shushu_json.py` 中的 filts 配置：
```python
"filts": [{
    "ftv": ["你的值"],
    "comparator": "equal",
    "columnName": "你的字段名"
}]
```

---

### Q4：如何添加新的分组字段？

在对应报表的 groupBy 数组中添加：
```python
{
    "tableType": "event",
    "columnName": "新字段名",
    "columnDesc": "新字段名"
}
```

---

### Q5：如何调整时间范围？

修改 eventView 中的时间配置：
```python
"recentDay": "0-7",  # 最近7天
"startTime": "2026-02-25 00:00:00",
"endTime": "2026-03-03 23:59:59"
```

---

### Q6：生成的JSON文件在哪里？

默认保存路径：
```
ai-platform/skills/testing/data_testing/testcase_generation/docs/<文档名>_数数看板_<区服名>.json
```

---

### Q7：如何验证JSON格式是否正确？

使用 Python 验证：
```bash
python3 -m json.tool <文件名>.json
```

---

### Q8：支持哪些区服？

系统支持以下所有区服：

| 代码 | 区服名称 | 代码 | 区服名称 |
|------|---------|------|---------|
| "" | 会玩 | "O" | JK服 |
| "A" | 阿语服 | "R" | 俄语服 |
| "Q" | 土语服 | "B" | 葡语服 |
| "P" | 菲律宾服 | "T" | 泰服 |
| "V" | 越南服 | "M" | 马尼服 |
| "C" | 华语服 | "U" | 美服 |
| "J" | 日服 | "I" | 印度服 |
| "K" | 韩服 | "S" | 西语服 |
| "N" | 巴基斯坦服 | "F" | 法语服 |
| "G" | 德语服 | | |

**使用方式**：
- 直接输入区服代码（如 "C"、"J"、"K"）
- 或者输入区服名称（如 "华语服"、"日服"、"韩服"）
- 系统会自动识别并配置对应的 app_region 筛选

---

### Q9：如何为同一份文档生成多个区服的看板？

多次运行，每次选择不同区服，自动生成对应的看板文件（如 `xxx_华语服.json`、`xxx_日服.json`）。

---

### Q10：如何确保生成的JSON能成功导入？

参考[成功导入的关键要素](04-config-reference.md#成功导入的关键要素)章节，特别注意 reportMappings 和 ui_config 的完整性。

---

### Q11：生成的报表名称为空怎么办？

**问题现象**：
生成的JSON文件中，报表名称显示为空或者显示为"报表1"、"报表2"等通用名称。

**原因分析**：
解析器可能无法从文档中提取到清晰的标题，导致 `reportName` 字段为空。

**解决方案**：

**方法1：手动更新JSON文件（推荐）**

```python
import json

# 定义报表名称
report_names = [
    "秘籍残页碎片的获得使用",
    "秘籍残页合成、强化",
    "群聊展开收起icon曝光",
    "群聊展开收起点击",
    # ... 根据实际情况添加
]

# 读取并更新
with open('docs/xxx_数数看板_华语服.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

# 更新报表名称
for idx, (report, name) in enumerate(zip(data['reports'], report_names), 1):
    report['reportName'] = name
    print(f"{idx}. 已更新: {name}")

# 保存
with open('docs/xxx_数数看板_华语服.json', 'w', encoding='utf-8') as f:
    json.dump(data, f, ensure_ascii=False, indent=2)

print("\n✅ 报表名称更新成功！")
```

**方法2：优化文档格式**

在飞书文档中为每个事件添加清晰的标题：
```markdown
### 【服务器】秘籍残页碎片的获得使用
**事件名称：**SeekingCultivator
...

### 【客户端】群聊展开收起曝光
**事件名称：**group_icon
...
```

**验证更新**：
```bash
# 验证名称已更新
python3 -c "
import json
with open('docs/xxx.json', 'r', encoding='utf-8') as f:
    data = json.load(f)
for idx, report in enumerate(data['reports'], 1):
    print(f\"{idx}. {report['reportName']}\")
"
```

---

### Q12: 生成的看板缺少事件级筛选条件

**问题现象**：

生成的看板配置中，所有报表的 `events[0].filts` 都为空数组，导致：
- 无法区分同一事件的不同业务场景（如 SeekingCultivator 的"合成"和"强化"）
- 数据统计范围过大，包含不相关数据
- 无法按固定值字段（如 screen_name、action）进行数据过滤

**原因分析**：

解析器目前只识别事件名称和分组字段，没有识别和提取**固定值字段**作为筛选条件。

**典型场景**：

1. **同一事件多个业务场景**
   - SeekingCultivator: action = "秘籍残页合成" vs "秘籍残页强化"
   - AppClick: screen_name = "IM消息页" vs "分享页"

2. **固定值字段区分**
   - scene = "游戏结算页" vs "H5活动页"
   - game_type = 1065

**解决方案**：

使用修复脚本手动添加筛选条件（已提供完整脚本）：

```python
#!/usr/bin/env python3
"""
修复看板配置中缺失的事件级筛选条件
"""
import json
import sys
import copy

def add_event_filter(report, column_name, value, is_number=False):
    """为报表添加事件级筛选条件"""
    filter_item = {
        "columnName": column_name,
        "comparator": "equal",
        "ftv": [value],
        "function": "eq",
        "relation": "and"
    }

    if is_number:
        filter_item["dataType"] = "NUMBER"

    report['openQuery']['events'][0]['filts'].append(filter_item)

# 使用示例
with open('docs/xxx_数数看板_华语服.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

reports = data['reports']

# 1. 添加单个筛选条件
add_event_filter(reports[0], "action", "秘籍残页碎片获得与使用")

# 2. 添加多个筛选条件
add_event_filter(reports[6], "screen_name", "分享页")
add_event_filter(reports[6], "scene", "游戏结算页")
add_event_filter(reports[6], "game_type", 1065, is_number=True)

# 3. 拆分报表（同一事件多个固定值）
original_report = copy.deepcopy(reports[1])

# 报表1：合成
reports[1]['reportName'] = "秘籍残页合成"
add_event_filter(reports[1], "action", "秘籍残页合成")

# 报表2：强化
enhance_report = original_report
enhance_report['reportId'] = 70008  # 新ID
enhance_report['reportName'] = "秘籍残页强化"
add_event_filter(enhance_report, "action", "秘籍残页强化")
reports.insert(2, enhance_report)

# 保存
with open('docs/xxx_fixed.json', 'w', encoding='utf-8') as f:
    json.dump(data, f, ensure_ascii=False, indent=2)
```

**验证筛选条件**：

```bash
python3 -c "
import json
with open('docs/xxx_fixed.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

for idx, report in enumerate(data['reports'], 1):
    name = report['reportName']
    filters = report['openQuery']['events'][0]['filts']
    print(f'{idx}. {name}')
    if filters:
        for f in filters:
            print(f'   ✅ {f[\"columnName\"]} = {f.get(\"ftv\", [])}')
    else:
        print('   ℹ️  无筛选条件')
"
```

**关键注意事项**：

1. **筛选条件位置**：`reports[i]['openQuery']['events'][0]['filts']`（事件级筛选）
2. **全局筛选位置**：`reports[i]['openQuery']['eventView']['filts']`（全局筛选，如 app_region）
3. **数值类型**：数值字段需要添加 `"dataType": "NUMBER"`
4. **报表拆分**：同一事件多个固定值时，需要拆分成多个报表，并更新 reportMappings 和 ui_config

---

### Q13: 导入失败报错 "java.lang.IllegalArgumentException: 未知的配置条目"（早期方案）

⚠️ **注意**：这是早期的一种解决方案。**推荐使用最新方案**（将 folder_type 改为 "folder_share"），这是更标准的做法。

**问题现象**：

导入看板时报错：
```
java.lang.IllegalArgumentException: 未知的配置条目
    at cn.thinkingdata.ta.event.common.dto.dashboard.FolderType.create(FolderType.java:29)
    at cn.thinkingdata.ta.event.service.business.interreact.DashboardImportService.importFolder
```

**原因分析**：

`folder_type` 字段值不正确：
- ❌ `"folder_normal"` - 不被识别
- ❌ `"default"` - 不被识别
- ✅ `"folder_share"` - 正确值（推荐）
- ⚠️ **删除该字段** - 在某些平台版本可行，但不是标准做法

**解决方案（早期版本）**：

**方案1：删除 `folder_type` 字段**（应急方案）：

```python
import json

# 读取文件
with open('docs/xxx_数数看板_华语服.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

# 删除 folder_type 字段
del data['dashboardFolders'][0]['folder_type']

print("✅ 已删除 folder_type 字段")

# 保存
with open('docs/xxx_数数看板_华语服.json', 'w', encoding='utf-8') as f:
    json.dump(data, f, ensure_ascii=False, indent=2)
```

**验证修复**：

```bash
python3 -c "
import json
with open('docs/xxx.json', 'r', encoding='utf-8') as f:
    data = json.load(f)
folder = data['dashboardFolders'][0]
if 'folder_type' in folder:
    print(f'❌ 仍包含 folder_type: {folder[\"folder_type\"]}')
else:
    print('✅ folder_type 已删除')
    print(f'保留字段: {list(folder.keys())}')
"
```

**方案2：使用正确的值**（推荐）：

```python
# 修改 folder_type 为正确的值
data['dashboardFolders'][0]['folder_type'] = "folder_share"
```

**标准解决方案**：

参考 **Q14**，这是最新的完整修复方案：
- ✅ 将 folder_type 改为 `"folder_share"`（标准做法）
- ✅ 修复解析器以支持中文弯引号
- ✅ 增强标题提取
- ✅ 完整的验证流程

**结论**：建议使用标准方案，而不是删除 folder_type 字段。

---

### Q14: 筛选条件未提取 + folder_type 最新修复（2026-03-04）

**问题现象**：

1. 导入报错 `未知的配置条目 (FolderType)`
2. 事件标题为空
3. 固定值筛选条件（如 `action = "秘籍残页碎片获得与使用"`）未被提取

**根本原因分析**：

1. **folder_type 值错误**：
   - ❌ `"default"` - 不被识别
   - ✅ `"folder_share"` - 正确值

2. **标题级别问题**：
   - 文档使用 `###` 级别标题
   - 解析器只识别 `####` 级别

3. **引号格式问题**（核心问题）：
   - 文档使用**中文弯引号** `"value"` (U+201C/U+201D)
   - 解析器只匹配英文直引号 `"value"` (U+0022)

**完整修复方案**：

#### 1. 修复 folder_type

```python
# scripts/generate_shushu_json.py:404
"folder_type": "folder_share",  # 改为正确的值
```

#### 2. 增强标题提取

```python
# scripts/feishu_parser.py:39-72
# 支持 ### 和 #### 两种级别
if line.startswith('###') and not line.startswith('####'):
    # 处理 ### 级别标题
    # 自动清理【】、ou_xxx 等标记
```

#### 3. 增强引号识别（关键）

```python
# scripts/feishu_parser.py:157
# 支持多种引号格式
pattern1 = r'([a-z_]+)\s*=\s*[""\'\u201C]([^""\'\u201D]+)[""\'\u201D]'

# 支持的引号类型：
# - 英文直引号 "value" (U+0022)
# - 单引号 'value' (U+0027)
# - 中文弯引号 "value" (U+201C/U+201D)
# - 全角引号 "value" (U+FF02)
```

#### 4. 多枚举值处理

```python
# 自动只取第一个值
# action = "秘籍残页合成"、"秘籍残页强化" → "秘籍残页合成"
if '、' in value or '，' in value:
    first_value = re.split('[、，]', value)[0].strip()
```

**验证修复**：

```bash
# 1. 测试解析器
python3 scripts/feishu_parser.py docs/feishu_doc.md

# 2. 重新生成配置
python3 scripts/generate_shushu_json.py "C" "文档标题" --from-feishu docs/feishu_doc.md

# 3. 检查结果
python3 -c "
import json
with open('docs/xxx.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

# 检查 folder_type
print(f'folder_type: {data[\"dashboardFolders\"][0][\"folder_type\"]}')

# 检查报表标题
for report in data['reports'][:3]:
    print(f'标题: {report[\"reportName\"]}')

# 检查筛选条件
event = data['reports'][0]['openQuery']['events'][0]
if 'filts' in event and event['filts']:
    print(f'✅ 包含筛选条件')
"
```

**结果**：
- ✅ folder_type = "folder_share"
- ✅ 所有事件标题正确
- ✅ 所有固定值筛选条件正确提取
- ✅ 可成功导入数数平台

**注意**：Q13 的方案（删除 folder_type）在某些数数平台版本可行，但使用 `"folder_share"` 是更标准的做法。

---

### Q15: 导入成功但提示"未成功创建报表"（2026-03-04 修复）

**问题现象**：

导入看板时提示导入成功，但实际未创建任何报表。

**根本原因**：

报表配置中缺少必需字段 `cols`（分组字段）和 `measures`（指标配置），导致数数平台无法正确创建报表。

**诊断方法**：

```python
import json

with open("docs/xxx.json", 'r', encoding='utf-8') as f:
    data = json.load(f)

# 检查每个报表的事件配置
for i, report in enumerate(data['reports'], 1):
    event = report['openQuery']['events'][0]

    has_cols = 'cols' in event and len(event['cols']) > 0
    has_measures = 'measures' in event and len(event['measures']) > 0

    if not has_cols or not has_measures:
        print(f"❌ 报表 {i}: {report['reportName']}")
        if not has_cols:
            print(f"   缺少 cols（分组字段）")
        if not has_measures:
            print(f"   缺少 measures（指标）")
```

**解决方案**：

此问题已在 **2026-03-04** 永久修复：

1. **已修复脚本**：`scripts/generate_shushu_json.py`
   - 在第 334-340 行添加了 `cols` 和 `measures` 字段
   - 所有后续生成的配置都会包含这些必需字段

2. **已增强解析器**：`scripts/feishu_parser.py`
   - 支持识别【临时事件】和【组件事件】
   - 从 6 个事件提升到 15 个事件的识别率

3. **默认字段配置**：
   - 即使文档中没有明确字段，也会添加默认的 `act_id` 分组
   - 确保所有报表都有基本的统计维度

**验证修复**：

```bash
# 使用最新脚本重新生成配置
python3 scripts/generate_shushu_json.py "C" "文档标题" --from-feishu docs/xxx.md

# 验证生成的配置
python3 scripts/validate_shushu_json.py docs/xxx_数数看板_华语服.json
```

**预期结果**：
- ✅ 所有报表都包含 `cols` 字段（至少1个分组字段）
- ✅ 所有报表都包含 `measures` 字段（至少包含"总次数"指标）
- ✅ 导入数数平台后能成功创建所有报表

**历史影响**：
- 该问题影响了 2026-03-04 之前生成的所有配置文件
- 如果使用旧配置，需要重新生成或手动添加缺失字段

---

## 工具箱

| 工具 | 命令 | 用途 |
|------|------|------|
| **解析预览** | `python3 scripts/feishu_parser.py docs/xxx.md` | 预览解析到的事件列表 |
| **格式校验** | `python3 scripts/validate_shushu_json.py docs/xxx.json` | 验证配置格式 |
| **字段对比** | `python3 scripts/compare_with_template.py docs/xxx.json` | 对比模板字段 |
| **看板拆分** | `python3 scripts/split_dashboard.py docs/xxx.json 30` | 拆分超过30个报表 |