---
name: excel-report-converter
description: 当用户需要创建Python脚本将报表形式的Excel数据转换为结构化数据表时使用此技能。当用户提到：将Excel报表转换为数据表、解析Excel报表结构、创建Excel数据转换脚本、从打印模板格式提取数据、或者有类似"请购单维护"、"订单打印模板"等报表格式需要转换为标准表格时，即使没有明确说"创建脚本"，也应该触发此技能。这个技能专门处理那些面向打印/展示的报表布局（数据分散在多行多列、有表头/明细/页脚区块）到标准关系型数据表的转换。
---

# Excel报表数据转换技能

这个技能帮助你创建Python脚本，将各种报表形式的Excel数据转换为标准的数据表格式。

## 适用场景

当你遇到以下情况时，使用此技能：

- **报表式布局**：数据不是标准的行列表格，而是分散在多个区域
- **有表头/明细/页脚结构**：一个文档包含主信息、明细列表、汇总信息
- **打印模板格式**：为打印设计的Excel文件，需要提取其中的数据
- **多区块重复**：同一个Excel文件包含多个相同格式的报表区块
- **字段映射复杂**：目标字段与源单元格位置有复杂的对应关系
- **大数据量提取（性能敏感）**：需要快速提取数千行以上、包含大量单元格的复杂Excel报表

---

## 🚀 性能优化核心技术 (提速法则)
在处理中大型Excel报表时，传统的 `openpyxl` 逐个单元格读取方法会导致极严重的性能瓶颈。本技能强制采用以下高阶优化方案：

1. **空间换时间（内存二维数组）**：禁止在循环中频繁调用 `sheet.cell(row, col).value`。必须使用 `sheet.iter_rows(values_only=True)` 将整表数据一次性读入 Python 的 `List[List]` 中。后续所有的查找全部基于内存列表索引进行，速度可提升数十倍。
2. **预先构建映射字典**：将 `column_index_from_string` (字母转数字索引) 等固定操作移出循环，在脚本初始化时预先计算好映射字典。
3. **Pandas 向量化降维打击**：在保存 Excel 自动调整列宽时，放弃 `openpyxl` 的逐单元格遍历，直接利用 Pandas 的底层 C 语言级别操作 `df[col].astype(str).map(len).max()` 秒算列宽。
4. **避开 `read_only` 的“公式陷阱”**：绝不能为了加载速度盲目开启 `read_only=True`，这会导致由 Excel 隐式公式（如自动递增序号 `=A1+1`）生成的值返回 `None`。必须坚持使用默认加载模式配合 `data_only=True`，然后依靠“内存二维数组”来解决速度问题。

---

## 工作流程

### 第一步：分析源Excel文件结构并构建内存视图

使用openpyxl读取Excel文件，并立即将其转换为内存二维数组以提升后续处理速度：

```python
import openpyxl
from typing import List, Any

# 1. 加载工作簿 (保留 data_only=True, 弃用 read_only=True 保证公式值完整)
wb = openpyxl.load_workbook(file_path, data_only=True)
sheet = wb.active

# 2. 【核心提速机制】将整表数据一次性抽取为 Python 二维数组
# 填充一行 [None]，并为每一行填充一列 [None]，使后续列表索引(1-based)与Excel坐标严格对齐
excel_data = [[None]] 
for row in sheet.iter_rows(values_only=True):
    excel_data.append([None] + list(row))
wb.close() # 释放文件句柄

# 3. 辅助读取函数 (替代慢速的 sheet.cell().value)
def get_val(data: List[List[Any]], row: int, col: int) -> Any:
    try:
        if row < len(data) and col < len(data[row]):
            return data[row][col]
    except IndexError:
        pass
    return None
````

### 第二步：识别报表区块

大多数报表式Excel有以下特征，按优先级在 `excel_data` 中进行检测：

|**特征**|**检测方法**|**示例**|
|---|---|---|
|区块标题|A列包含特定关键词|"请购单维护"、"订单"|
|表头标签|冒号结尾的标签|"请购单号："、"日期："|
|明细表头|包含列名的行|"行号"、"物料编码"、"数量"|
|数据行|标签行下方连续的数据|非空的具体数据值|
|页脚行|包含"制单"、"审批"等|"制单人："、"审批人："|

**识别规则**：

1. 区块开始：通常在A列，包含报表类型名称
    
2. 表头区域：区块开始后3-6行，包含带冒号的字段标签
    
3. 明细表头：表头区域后，A列包含"行号"或类似列名
    
4. 明细数据：明细表头后，连续的非空行
    
5. 页脚区域：明细数据后，包含签名/审批信息
    

### 第三步：设计数据结构

根据识别结果，设计输出表结构：

**扁平化单表**

- 每条明细记录携带完整的表头信息
    
- 适合数据分析和导出


### 第四步：生成转换脚本

基于分析结果，生成包含以下函数的Python脚本：

Python

```
# 必需的核心函数
def find_sections(excel_data)
    """识别所有报表区块的起始行"""

def extract_header_data(excel_data, start_row)
    """提取表头信息"""

def extract_line_items(excel_data, header_row, section_end)
    """提取明细行数据"""

def extract_footer_data(excel_data, line_items_end)
    """提取页脚信息"""

def parse_section(excel_data, start_row, next_section)
    """解析单个报表区块"""

def parse_excel_file(file_path)
    """读取Excel文件，转换为二维数组并解析所有区块"""

def save_to_excel(data_df, output_path)
    """保存转换结果，利用Pandas向量化计算列宽"""
```

## 字段提取模式

### 模式1：固定偏移量（利用预计算）

当表头字段位置固定时使用：

Python

```
# 提取表头信息 (从内存数组快速读取)
def extract_header_data(excel_data, start_row):
    header = {}
    header['请购单号'] = get_val(excel_data, start_row + 3, 2) # Row+3, B列(2)
    return header
```

### 模式2：标签查找

当字段位置不固定但标签唯一时使用：

Python

```
def find_field_by_label(excel_data, label, start_row, search_range=10):
    """通过标签查找字段位置"""
    max_row = len(excel_data) - 1
    for row in range(start_row, min(start_row + search_range, max_row + 1)):
        # 假设标签在前10列中
        for col in range(1, min(11, len(excel_data[row]))):
            cell_value = get_val(excel_data, row, col)
            if cell_value and label in str(cell_value):
                # 返回值的位置（通常在标签的右侧）
                return get_val(excel_data, row, col + 1)
    return None
```

## 明细行提取策略

### 策略：预计算列映射字典 (极速匹配)

避免在双重循环中调用 `column_index_from_string`。

Python

```
from openpyxl.utils import column_index_from_string

LINE_ITEM_COLUMNS = {
    'A': '行号', 'B': '排产号', 'C': '物料编码'
}

# 全局预计算列索引
LINE_ITEM_COLUMNS_IDX = {
    column_index_from_string(col): field
    for col, field in LINE_ITEM_COLUMNS.items()
}

def extract_line_items(excel_data, header_row, section_end):
    line_items = []
    for row in range(header_row + 1, section_end):
        # ... 判断跳出逻辑 ...
        item = {}
        for col_num, field_name in LINE_ITEM_COLUMNS_IDX.items():
            item[field_name] = get_val(excel_data, row, col_num)
        if any(item.values()):
            line_items.append(item)
    return line_items
```

## 处理特殊情况

### 1. 空区块处理

当某个区块没有明细数据时，仍需创建一条记录：

Python

```
if not line_items:
    # 创建一条空记录，保留表头和页脚信息
    record = {**header_data, **footer_data}
    for field in LINE_ITEM_COLUMNS.values():
        record[field] = None
    flat_records.append(record)
```

## 输出格式

### Excel格式（结合 Pandas 向量化提速）

Python

```
from openpyxl.utils import get_column_letter

def save_to_excel(data_df, output_path):
    """保存为Excel文件并极速调整列宽"""
    with pd.ExcelWriter(output_path, engine='openpyxl') as writer:
        data_df.to_excel(writer, sheet_name='转换结果', index=False)
        worksheet = writer.sheets['转换结果']

        # 【提速】利用 Pandas 的向量化操作一次性算出最大列宽
        for idx, col in enumerate(data_df.columns):
            max_len = max(data_df[col].astype(str).map(len).max() if not data_df.empty else 0, len(str(col)))
            adjusted_width = min(max_len + 2, 50)
            col_letter = get_column_letter(idx + 1)
            worksheet.column_dimensions[col_letter].width = adjusted_width
```

## 依赖库

脚本需要以下依赖，确保在运行前安装：

Bash

```
pip install openpyxl pandas
```

## 验证清单

生成脚本后，验证以下内容：

- [ ] 成功识别所有报表区块
- [ ] 表头字段提取正确
- [ ] 明细行数据完整
- [ ] 页脚信息准确
- [ ] 空区块得到正确处理
- [ ] 输出文件格式正确
- [ ] 数据类型准确（日期、数字等）
- [ ] 没有重复或遗漏的记录

## 调试技巧

当脚本出现问题时：

1. **打印中间结果**：在每个函数中添加print语句，查看提取的数据
2. **检查单元格值**：确认openpyxl读取的值与预期一致
3. **验证索引**：确保行号和列号计算正确
4. **分步测试**：先测试单个区块，确认正确后再处理全部
5. **对比原文件**：在Excel中查看原始数据和提取结果的差异

## 常见问题

**Q: 为什么提取时有些序列号或公式计算的值变成了 `None`？**

A: 这是因为在 `openpyxl` 中错误开启了 `read_only=True` 模式，导致依靠 Excel 公式生成的值无法正确读取缓存。**解决方案**：去掉 `read_only=True`，只保留 `data_only=True`，并使用二维数组提取法来保障速度。

**Q: 输出的数据需要进一步处理怎么办？**

A: 脚本生成后，可以在将其转换为 Pandas DataFrame 之后，利用 Pandas 强大的生态添加数据清洗、验证、格式转换（如日期格式化）等功能。

## 最佳实践

1. **绝对优先使用内存二维数组**：直接摒弃 `sheet.cell().value` 的传统思维，这是报表转换脚本能商用的性能基石。
    
2. **预先计算，拒绝重复**：所有能够确定位置或索引关系的映射字典，全部放在全局作用域一次性计算完成。
    
3. **先分析，后编码**：花时间理解报表结构和分页/分块标识，比直接编码更高效。
    
4. **异常容错机制**：数据提取行要进行 `if any(item.values())` 判断，过滤纯空行；对于越界索引使用 `try-except` 包裹。