# 自动表头检测功能 - 使用指南

## 功能概述

自动表头检测功能可以智能识别 Excel 文件中真正的列名（表头）行，特别适用于处理前几行有标题、说明、合并单元格等复杂结构的表格。

## 核心特性

### 1. 多策略智能检测

使用四种策略综合判断表头位置：

- **唯一字段数量**（权重40%）：字段越多的行越可能是表头
- **关键词匹配**（权重30%）：包含"姓名"、"学号"等常见列名加分
- **合并单元格惩罚**（权重-20%）：合并单元格多的行是标题
- **数据特征**（权重10%）：纯数字行降权（避免误选数据行）

### 2. 置信度评估

- **≥ 80%**：高置信度，直接使用
- **50-80%**：中等置信度，可以使用但建议验证
- **< 50%**：低置信度，给出警告，建议手动指定

### 3. 支持的列名关键词

系统内置了常见的中文章名列名：

```
姓名, 名字, 学号, 学籍号, 编号, ID,
身份证, 证件, 手机, 电话, 联系方式,
部门, 科室, 班级, 年级,
日期, 时间, 年份, 月份,
地址, 位置, 备注, 说明,
语文, 数学, 英语, 物理, 化学, 生物,
政治, 历史, 地理, 思品, 道德
```

## 使用方法

### 配置方式

在配置文件中设置 `header_row: "auto"`：

```yaml
source:
  file_path: "data/source.xlsx"
  sheet_name: "Sheet1"
  header_row: "auto"  # 启用自动检测
  key_field: "学号"

target:
  file_path: "templates/template.xlsx"
  sheet_name: "成绩表"
  header_row: "auto"  # 启用自动检测
  output_path: "output/result.xlsx"
```

### 执行导入

```bash
cd /home/aqbjqtd/.claude/skills/excel-data-import
python scripts/excel_import_enhanced.py your_config.yaml
```

### 输出示例

```
🔍 自动检测目标模板表头位置...
✅ 自动检测到目标模板表头在第 4 行
   数据起始行: 5
   置信度: 95.0%
   原因: 包含5个常见列名关键词 | 拥有6个唯一字段 | 无合并单元格

🔍 自动检测源文件表头位置...
  ✅ 检测到源文件表头在第 3 行 (置信度: 90.0%)
```

## 典型应用场景

### 场景1：简单表头

```
行1: 姓名 | 学号 | 身份证号  ← 直接是表头
行2: 张三 | 001 | ...         ← 数据
```

**检测结果**：第1行，置信度100%

### 场景2：有标题行

```
行1: 学生信息表              ← 大标题
行2: (空行)
行3: 姓名 | 学号 | 身份证号  ← 真正的表头
行4: 张三 | 001 | ...         ← 数据
```

**检测结果**：第3行，置信度100%

### 场景3：多层说明

```
行1: 2024年度学生成绩表
行2: 制表部门: 教务处
行3: 说明: 本表包含所有班级的学生信息
行4: 姓名 | 学号 | 语文 | 数学  ← 真正的表头
行5: 张三 | 001 | 90 | 95       ← 数据
```

**检测结果**：第4行，置信度100%

### 场景4：合并单元格标题

```
行1: [A1:E1 合并] 学生信息管理系统
行2: [A2:E2 合并] 2024-2025学年第一学期
行3: 姓名 | 学号 | 身份证号  ← 真正的表头
行4: 张三 | 001 | ...         ← 数据
```

**检测结果**：第3行，置信度100%

## 测试验证

运行内置测试套件：

```bash
python scripts/tests/test_auto_header_detection.py
```

**测试覆盖**：
- ✅ 简单表头（第1行就是列名）
- ✅ 有标题行（第1行标题，第3行列名）
- ✅ 多层说明（前3行说明，第4行列名）
- ✅ 合并单元格标题（第1-2行合并，第3行列名）
- ✅ 边缘情况（所有行都是数据）

## 技术细节

### 检测算法

1. **扫描前N行**（默认15行）
2. **排除空行**（完全空白的行跳过）
3. **计算每行得分**：
   ```
   得分 = 字段数×40 + 关键词×30 - 合并数×20 + 数据特征±10
   ```
4. **选择最高分行**作为表头
5. **计算置信度**：
   - 正常表头：`score / 100`（最高100%）
   - 疑似数据行：`score / 100`（最高40%）

### 配置参数

可以在配置文件中调整检测参数：

```yaml
options:
  auto_detect_params:
    max_check_rows: 15    # 最多检查前N行
    min_fields: 3         # 最少字段数量
    confidence_threshold: 0.5  # 置信度阈值
```

## 常见问题

### Q1: 检测不准确怎么办？

**A**: 如果置信度低于50%，系统会给出警告。此时建议：
1. 手动指定 `header_row` 数字
2. 检查表格结构是否过于特殊
3. 添加自定义关键词（需修改代码）

### Q2: 支持英文列名吗？

**A**: 当前版本主要优化中文列名。英文列名可能检测准确度较低，建议手动指定 `header_row`。

### Q3: 如何添加自定义关键词？

**A**: 编辑 `scripts/worksheet_analyzer.py` 中的 `HEADER_KEYWORDS` 列表：

```python
HEADER_KEYWORDS = [
    '姓名', '学号',
    '你的自定义关键词',
    # ...
]
```

### Q4: 可以跳过多行标题吗？

**A**: 可以！自动检测会自动跳过标题行。例如：
- 前3行都是标题
- 第4行是真正的列名
- 系统会自动检测到第4行

## 向后兼容性

- ✅ 手动指定 `header_row: 4` 仍然有效
- ✅ 旧配置文件无需修改即可使用
- ✅ 可以混合使用（源文件auto，目标模板手动）

## 更新日志

- **v2.1** (2026-01-28): 新增自动表头检测功能
- 支持多策略智能检测
- 置信度评估和警告
- 完整的测试覆盖

---

**技术支持**: 如有疑问，请查看完整文档或运行测试验证。