AI + 表格：表头 / 多级表头结构抽取与合并单元格逻辑补全的工程化落地

这是一篇为一线工程实践而写的文章：把“看起来都不像一张标准表”的现实报表，稳稳落地成可计算、可校验、可汇总的数据结构。我们会把“表头/多级表头结构抽取”“合并单元格逻辑补全”拆到骨头里，再给出可运行的参考实现与工程约束。

• 适读人群：数据工程、财务自动化、RPA/数字员工、报表解析（Excel/PDF/图片）相关的工程师与技术管理者

• 所用技术栈：Python（pandas、openpyxl）、启发式规则 + 轻量 AI（LLM/embedding）、数据结构（树与区间）

• 外部参考：

  • pandas 官方文档

  • openpyxl 官方文档

  • Camelot PDF table extraction

  • pdfplumber（GitHub）

---

目录

1. 背景与问题定义

2. 表头的本质：从“文本块”到“层级树”

3. 多级表头的结构建模：跨度、合并与路径

4. 合并单元格的逻辑补全：规则库与边界条件

5. AI 辅助抽取：启发式 + 小模型的协同

6. 工程实践路径：从 Excel/PDF 到统一 DataFrame

7. 代码实战一：openpyxl 填充合并单元格（行/列传播）

8. 代码实战二：表头树构建与“路径化”列名

9. 代码实战三：AI+规则的列名语义归一与冲突消解

10. 代码实战四：构造 pandas.MultiIndex 与完整校验链路

11. 性能与稳定性：大表处理、异常可观测与回滚

12. 对比与扩展：纯规则 vs 纯 OCR/LLM vs 混合方案

13. 总结与展望：从“可解析”到“可治理”的一小步

---

1. 背景与问题定义

现实世界中的业务报表（尤其是财务与运营类），在表头层级复杂、合并单元格频繁、跨页/跨区域漂移的情况下，很难用单一规则稳定解析。即便是 Excel 文件，也会因为“多人维护”“模板漂移”“临时合并/拆分”而导致结构多变。工程上，我们需要一个稳态输出：
1）抽取稳定结构的表头树，2）补全合并单元格信息，3）统一输出到标准列名/路径，以便下游做校验、对账、汇总、对比。

这个问题的难点在于三层不确定性：视觉布局不确定（合并/缩进/换行）、语义不确定（列名口径不同）、边界不确定（缺值、跨页、错位）。因此，纯 OCR/LLM 或 纯规则都容易在某些形态“翻车”。本文采用启发式规则 + 轻量 AI的混合范式，在可控工程成本内追求稳态产出。

目标：不仅“看懂表头”，还要“还原结构、补全逻辑、统一口径”，最终落在 pandas.MultiIndex 或扁平化“路径列名”上，且可被52项核对规则等下游逻辑直接消费。

---

2. 表头的本质：从“文本块”到“层级树”

第一件事不是“怎么写代码”，而是建立正确的数据抽象。对于任何带层级的表头，我们可以把它当作一棵树：

• 节点：表头单元格（含文本 + 覆盖区域）

• 边：父子层级（父节点覆盖范围包含子节点覆盖范围）

• 叶子：最底层列（对齐到数据区域的实际列）

这样的抽象有三个工程收益。其一，算法稳定：即使模板在拓扑上有改动（多一级或减少一级），树结构仍可推导。其二，语义保留：父节点通常代表类别、口径、单位等语义信息，拼接到路径里能增强可读性。其三，对齐计算：父节点的列跨度可作为叶子定位的“硬约束”。

要做的就是从二维网格（含合并/未合并）恢复**“树”：识别每个节点的行区间、列区间、文字**，然后构建父子关系，得到叶子路径作为最终列名。

小结：表头 = 树；列名 = 叶子路径；跨度 = 对齐约束。从这个视角出发，后续的合并补全与 AI 语义归一都有了“锚点”。

---

3. 多级表头的结构建模：跨度、合并与路径

我们需要一个统一的单元格表示：

• r1, c1, r2, c2：单元格覆盖的闭区间（行列坐标）

• text：去除样式与换行的文本内容

• kind：可选，先空置，后续由规则/AI 标注（如“单位”“期间”“指标”）

有了这个模型，合并单元格就是 r2 > r1 或 c2 > c1 的普通节点。构建树时遵循两个原则：
1）在同一行上，父节点的列区间应完全覆盖子节点；
2）在同一列上，父节点的行区间应完全覆盖子节点。

当模板存在“空白填充”（例如只合并了左上块，右下块空白），我们需要逻辑补全：将空白区域视作继承父节点文本。这正是合并补全的意义——不改变原文件，只在解析层做“看见即补齐”的标准化。

路径化策略：自上而下拼接非空文本，中间用 "/" 或 "::" 连接，得到诸如 "收入/话费/本期金额" 的列名。遇到空文本节点则跳过或继承父节点“口径”。

---

4. 合并单元格的逻辑补全：规则库与边界条件

逻辑补全并不是简单的“向下/向右填充”，还要处理以下边界：

• T 形/十字形合并：父节点横跨多列，同时与下方某些子节点还有纵向合并。

• 部分空白：合并范围内并非所有格子都可“视作父文本”，需要依据边界线/框线或相邻单元格判断。

• 对齐漂移：视觉上看齐，但网格中并未合并（人工用空格/缩进模拟），需要文本相似度 + 坐标距离修正。

工程上，我们优先使用确定性强的规则（openpyxl 的合并信息、边界区间），对不可判定的情况（例如“空白继承到底继承谁”），再引入小模型辅助打分（下一节详述）。

经验法则：逻辑补全只在解析层生效，不改源文件；用一个“补全标记位”（例如 virtual_fill=True）区分真实文本与继承文本，方便下游溯源与审计。

---

5. AI 辅助抽取：启发式 + 小模型的协同

LLM 能否一把梭？ 在报表解析里，上下文微小差异会带来巨大结构变化，纯 LLM 容易“想当然”。因此，我们采用规则先行、AI 兜底/加速的协同策略：

• 启发式负责硬约束：坐标、跨度、合并区间、对齐关系。

• AI 负责软判断：列名归一（“本期金额 = 当期金额 = 本期数”）、单位/期间识别、口径冲突消解，及模糊边界的继承判断。

• 小模型为主：embedding+KNN 词表、few-shot 判别、轻提示（不强依赖超长上下文）。

这种搭配在企业场景更可控：结构来自规则，语义来自 AI；出问题能定点回溯是哪层出错，也便于灰度上线与A/B 验证。

---

6. 工程实践路径：从 Excel/PDF 到统一 DataFrame

建议的流水线如下：

1）载入与预处理：Excel 用 openpyxl 读取样式与合并信息，PDF 用 camelot/pdfplumber 提取网格与文本框；
2）合并补全：按合并区间与相邻关系“向下/向右”虚拟填充，生成表头候选区（通常 1~N 行）；
3）表头树构建：对候选区进行树化，得到叶子路径；
4）AI 归一：对路径节点做语义归一（单位/期间/口径），消解同义冲突；
5）MultiIndex/路径列名：将叶子路径转为 pandas.MultiIndex 或扁平路径列，并与数据区对齐；
6）校验与导出：空列/重复列检测、单位一致性/期间闭包校验，输出标准化表。

连接下游：你可以把这份结构交给52项自动核对规则、差异分析、HTML 报告生成器（图表/高亮），形成端到端的“数字员工”流水线。

---

7. 代码实战一：openpyxl 填充合并单元格（行/列传播）

下面代码聚焦 Excel：识别合并区域并在解析层做虚拟填充，同时支持向下/向右传播，并保留 virtual_fill 标记位。示例足够通用，可直接嵌入你的解析器。

# coding: utf-8
from dataclasses import dataclass
from typing import List, Tuple, Dict, Any
from openpyxl import load_workbook

@dataclass
class Cell:
    r1: int
    c1: int
    r2: int
    c2: int
    text: str
    virtual_fill: bool = False

def read_ws_with_merged_fills(xlsx_path: str, sheet: str = None, header_rows: int = 10) -> Dict[str, Any]:
    """
    读取工作表前若干行，解析合并单元格并进行逻辑补全（向下/向右传播）。
    返回 cell 列表与一个二维文本网格，网格仅用于调试与可视化。
    """
    wb = load_workbook(xlsx_path, data_only=True)
    ws = wb[sheet] if sheet else wb.active

    # 1) 先构造一个纯文本网格（不考虑合并）
    max_row = min(ws.max_row, header_rows)
    max_col = ws.max_column
    grid = [[(ws.cell(r, c).value or "").strip() if isinstance(ws.cell(r, c).value, str) else (ws.cell(r, c).value or "")
             for c in range(1, max_col + 1)] for r in range(1, max_row + 1)]

    # 2) 基于 openpyxl 的 merged_ranges 做“上左”取值，填充合并区域
    for merged in ws.merged_cells.ranges:
        (r1, c1, r2, c2) = (merged.min_row, merged.min_col, merged.max_row, merged.max_col)
        if r1 <= max_row:  # 只处理表头候选区
            top_left = grid[r1 - 1][c1 - 1]
            for r in range(r1, min(r2, max_row) + 1):
                for c in range(c1, c2 + 1):
                    if r == r1 and c == c1:
                        continue
                    grid[r - 1][c - 1] = top_left

    # 3) 逻辑补全：为空的格子尝试“向上继承”与“向左继承”（可按需调换优先级）
    for r in range(max_row):
        for c in range(max_col):
            if grid[r][c] in (None, ""):
                inherit = None
                # 向上找最近非空
                for ru in range(r - 1, -1, -1):
                    if grid[ru][c] not in (None, ""):
                        inherit = grid[ru][c]
                        break
                # 向左找最近非空
                if inherit in (None, ""):
                    for cl in range(c - 1, -1, -1):
                        if grid[r][cl] not in (None, ""):
                            inherit = grid[r][cl]
                            break
                if inherit not in (None, ""):
                    grid[r][c] = inherit  # 虚拟补全，仅在解析层生效

    # 4) 导出 cell 列表（此处简化：将每个网格视作单元格；合并信息已在 grid 中体现）
    cells: List[Cell] = []
    for r in range(max_row):
        for c in range(max_col):
            txt = grid[r][c]
            # 标记虚拟填充：原始 ws 的该点若为空但 grid 有值，则认为 virtual_fill
            original = ws.cell(r + 1, c + 1).value
            virtual = (original in (None, "")) and (txt not in (None, ""))
            cells.append(Cell(r1=r + 1, c1=c + 1, r2=r + 1, c2=c + 1, text=str(txt or ""), virtual_fill=virtual))

    return {"cells": cells, "grid": grid, "max_row": max_row, "max_col": max_col}

说明与对比

• 这段代码把“真实合并”与“逻辑补全”统一映射到 grid，这样后续树构建可以不关心 Excel 的合并细节。

• 如果你的模板存在“强制左优先”的业务规则，可以调整第 3 步的继承优先级。

• 对比直接修改 Excel 文件的做法，这里仅在解析层“虚拟化”补全，便于审计与回滚。

---

8. 代码实战二：表头树构建与“路径化”列名

有了补全后的 grid，我们把前 N 行视作表头候选区，用“跨度覆盖”构建父子关系，最终得到叶子路径。下面用一个简化版实现演示思路：

# coding: utf-8
from dataclasses import dataclass, field
from typing import List, Tuple, Dict, Optional

@dataclass
class Node:
    r1: int; c1: int; r2: int; c2: int
    text: str
    children: List["Node"] = field(default_factory=list)

def build_header_nodes(grid: List[List[str]], header_rows: int) -> List[Node]:
    """
    将前 header_rows 行的网格转为节点（默认每个格子都是一个 1x1 的节点）。
    如果你有更精细的“视觉块”划分，可在这里替换。
    """
    nodes = []
    for r in range(header_rows):
        for c in range(len(grid[0])):
            text = (grid[r][c] or "").strip()
            nodes.append(Node(r1=r, c1=c, r2=r, c2=c, text=text))
    return nodes

def is_parent(p: Node, ch: Node) -> bool:
    """父覆盖子：行/列坐标都要覆盖，且父在上层（r 较小）"""
    return (p.r1 <= ch.r1 <= p.r2 <= ch.r2) and (p.c1 <= ch.c1 <= p.c2 <= ch.c2) and (p.r1 < ch.r1)

def assign_spans(nodes: List[Node]) -> None:
    """
    简化：在同一行内做“横向合并”，把相邻且文本相同的格子合并成更宽的节点；
    在同一列内做“纵向合并”，把相邻且文本相同的格子合成更高的节点。
    """
    # 横向
    row = max(n.r1 for n in nodes) + 1
    col = max(n.c1 for n in nodes) + 1
    merged = [[False]*col for _ in range(row)]
    by_pos: Dict[Tuple[int,int], Node] = {(n.r1, n.c1): n for n in nodes}
    # 横向合并
    for r in range(row):
        c = 0
        while c < col:
            if (r, c) in by_pos and not merged[r][c]:
                n = by_pos[(r, c)]
                span_c2 = c
                while span_c2 + 1 < col and (r, span_c2 + 1) in by_pos:
                    n2 = by_pos[(r, span_c2 + 1)]
                    if (n2.text == n.text) and not merged[r][span_c2 + 1]:
                        merged[r][span_c2 + 1] = True
                        span_c2 += 1
                    else:
                        break
                n.c2 = span_c2
                c = span_c2 + 1
            else:
                c += 1
    # 纵向合并
    for c in range(col):
        r = 0
        while r < row:
            if (r, c) in by_pos and not merged[r][c]:
                n = by_pos[(r, c)]
                span_r2 = r
                while span_r2 + 1 < row and (span_r2 + 1, c) in by_pos:
                    n2 = by_pos[(span_r2 + 1, c)]
                    if (n2.text == n.text) and not merged[span_r2 + 1][c]:
                        merged[span_r2 + 1][c] = True
                        span_r2 += 1
                    else:
                        break
                n.r2 = span_r2
                r = span_r2 + 1
            else:
                r += 1

def build_tree(nodes: List[Node]) -> List[Node]:
    """基于覆盖关系构建多层级树；顶层节点是最上行的节点集合。"""
    # 先按行排序，确保上层在前
    nodes = sorted(nodes, key=lambda n: (n.r1, n.c1))
    roots: List[Node] = [n for n in nodes if n.r1 == 0]
    # 逐层挂接
    for ch in nodes:
        if ch.r1 == 0:
            continue
        # 在上方可覆盖它的候选里，选择“覆盖范围最小”的那个作父
        candidates = [p for p in nodes if (p.r1 < ch.r1) and (p.c1 <= ch.c1 <= p.c2)]
        if candidates:
            parent = sorted(candidates, key=lambda p: (p.r2 - p.r1, p.c2 - p.c1))[0]
            parent.children.append(ch)
    return roots

def leaf_paths(node: Node, prefix: Optional[List[str]] = None) -> List[Tuple[str, Tuple[int,int]]]:
    """产出叶子路径（拼接非空文本）；同时返回叶子列的列坐标区间以便对齐数据区。"""
    prefix = prefix or []
    cur = prefix + ([node.text] if node.text else [])
    if not node.children:
        path = "/".join([p for p in cur if p])
        return [(path, (node.c1, node.c2))]
    out = []
    for ch in node.children:
        out.extend(leaf_paths(ch, cur))
    return out

说明与对比

• assign_spans 展示了一种“文本相等合并”的思路，适合经过“逻辑补全”的网格；在复杂模板下你可以把这里替换为“视觉块合并”。

• build_tree 用最小覆盖作为父子关系的选择规则，更贴近“最近父级”。

• leaf_paths 的“路径化”原则是跳过空文本，减少冗余。

---

9. 代码实战三：AI+规则的列名语义归一与冲突消解

当你拿到 "收入/话费/本期金额"、"收入/通话费/当期金额" 这类路径，需要进一步归一到标准字段，例如 "收入/话费/amount_current"。我们用“规则优先、AI 兜底”来做归一和冲突消解，并同时识别期间/单位这类“口径”信息。

# coding: utf-8
import re
from typing import List, Dict, Tuple

CANON_MAP = {
    # 关键词到标准语义键
    r"(本期|当期|本月|当月).*(金额|数|合计)": "amount_current",
    r"(上期|上月).*(金额|数|合计)": "amount_prev",
    r"(本年|年累计|至今).*(金额|数|合计)": "amount_ytd",
    r"(数量|笔数)$": "count",
    r"(单价|均价)": "unit_price",
}
UNIT_PATTERNS = [r"(元|人民币|CNY)", r"(万元|千元)"]
PERIOD_PATTERNS = [r"(202\d|20[1-2]\d)[-/\.年](\d{1,2})", r"(Q[1-4])", r"(本期|当期|上期|本月|上月)"]

def canonize_token(token: str) -> str:
    t = token.replace("（", "(").replace("）", ")")
    t = re.sub(r"\s+", "", t)
    for pat, key in CANON_MAP.items():
        if re.search(pat, t, re.I):
            return key
    return t  # 兜底：保留原词

def detect_unit(text: str) -> str:
    for pat in UNIT_PATTERNS:
        m = re.search(pat, text)
        if m:
            return m.group(1)
    return ""

def detect_period(text: str) -> str:
    for pat in PERIOD_PATTERNS:
        m = re.search(pat, text)
        if m:
            return m.group(1)
    return ""

def normalize_paths(paths: List[Tuple[str, Tuple[int,int]]]) -> List[Dict]:
    """
    输入: [("收入/话费/本期金额", (c1,c2)), ...]
    输出: [{"raw":..., "normalized":..., "unit":..., "period":..., "columns":(c1,c2)}]
    """
    out = []
    for p, colrng in paths:
        parts = [x for x in p.split("/") if x]
        unit = detect_unit(p) or detect_unit(parts[-1] if parts else "")
        period = detect_period(p) or detect_period(parts[-1] if parts else "")

        # 逐段标准化，末段更倾向数值语义
        norm_parts = [canonize_token(x) for x in parts[:-1]] + [canonize_token(parts[-1] if parts else "")]
        # 冲突消解（示例）：末段出现多个指标词时选择优先级高者
        priority = ["amount_current", "amount_prev", "amount_ytd", "count", "unit_price"]
        seen = [x for x in norm_parts if x in priority]
        last_key = seen[0] if seen else norm_parts[-1] if norm_parts else "value"
        # 去重并保留顺序
        uniq = []
        for x in norm_parts:
            if x not in uniq:
                uniq.append(x)
        normalized = "/".join(uniq[:-1] + [last_key])
        out.append({
            "raw": p,
            "normalized": normalized,
            "unit": unit,
            "period": period,
            "columns": colrng
        })
    return out

# 假设这里如果规则无法决定，我们再调用一个小模型做 few-shot 映射（伪代码）：
def small_llm_disambiguate(field: str, candidates: List[str]) -> str:
    """
    在工程里可用 embedding 相似度 + 规则打分的联合策略。
    这里给出占位函数：当规则不确定时返回最可能的候选。
    """
    # TODO: 替换为你的 embedding/KNN 或者轻提示 LLM
    return candidates[0] if candidates else field

说明与对比

• 规则部分用正则与关键词优先级即可覆盖 80% 的场景，复杂冲突再交给小模型。

• 将 unit 与 period 抽离到字段属性，避免把“单位/期间”硬编码在列名中，有利于治理与校验。

• 对比纯 LLM 映射，这里的“规则 + 轻模型”更透明、可审计。

---

10. 代码实战四：构造 pandas.MultiIndex 与完整校验链路

最终我们要把解析结果落地成一个可用的数据表。建议使用 pandas.MultiIndex 表达层级表头，同时保留一个扁平路径列名版本，方便 CSV/下游系统消费。

# coding: utf-8
import pandas as pd
from typing import List, Dict, Tuple

def to_multiindex_columns(items: List[Dict]) -> pd.MultiIndex:
    """
    items: [{"normalized": "收入/话费/amount_current", "unit": "元", "period": "本期", "columns": (c1, c2)}, ...]
    将 normalized 路径拆成层级，拼出 MultiIndex。
    """
    tuples = []
    for it in items:
        parts = it["normalized"].split("/")
        # 补充属性：在最末层添加一个"@meta"或使用 DataFrame.attrs 也可
        # 这里选择把 unit/period 拼在最后一层的后缀，便于可读
        last = parts[-1]
        suffix = []
        if it["unit"]:
            suffix.append(f"[{it['unit']}]")
        if it["period"]:
            suffix.append(f"({it['period']})")
        parts[-1] = last + (" " + " ".join(suffix) if suffix else "")
        tuples.append(tuple(parts))
    # 对齐层级：填充空层级
    max_depth = max(len(t) for t in tuples) if tuples else 1
    tuples = [t + tuple([""] * (max_depth - len(t))) for t in tuples]
    return pd.MultiIndex.from_tuples(tuples)

def align_data_region(raw_values: List[List], col_map: List[Tuple[Tuple[int,int], int]]) -> pd.DataFrame:
    """
    raw_values: 数据区的二维数组（不含表头）
    col_map: [((c1,c2), out_index), ...] 将列区间映射到输出列索引的关系
    真实工程中应该按 c1==c2 的叶子列来取值，这里演示合并列取其左边列。
    """
    if not raw_values:
        return pd.DataFrame()
    arr = []
    for row in raw_values:
        out = [None] * len(col_map)
        for i, (colrng, out_idx) in enumerate(col_map):
            c1, c2 = colrng
            # 简化：取 c1 列
            if c1 < len(row):
                out[out_idx] = row[c1]
        arr.append(out)
    df = pd.DataFrame(arr)
    return df

def construct_dataframe(header_items: List[Dict], raw_values: List[List]) -> pd.DataFrame:
    """
    综合：把 header_items 变成 MultiIndex，把 raw_values 对齐成数据表。
    """
    # 给每个 header item 分配输出列序号
    col_map = []
    for idx, it in enumerate(header_items):
        col_map.append((it["columns"], idx))
    # 数据
    df = align_data_region(raw_values, col_map)
    # MultiIndex
    mi = to_multiindex_columns(header_items)
    df.columns = mi
    # 可选：构造扁平路径列名，便于导出 CSV
    flat = ["::".join([lvl for lvl in tup if lvl]) for tup in df.columns.to_flat_index()]
    df_flat = df.copy()
    df_flat.columns = flat
    # 校验环节（示例）
    assert df.shape[1] == len(header_items), "列数不一致"
    # 这里可加入单位一致性、期间闭包等校验
    return df, df_flat

说明与对比

• MultiIndex 让层级信息成为“一等公民”，聚合/切片非常顺手；df_flat 则满足“落地导出”的需求。

• align_data_region 里简化了“合并列”处理，真实工程通常要求叶子列 c1==c2；如果不是，需要前置把“合并列”拆成叶子（用 leaf_paths 的列区间约束）。

---

11. 性能与稳定性：大表处理、异常可观测与回滚

真实环境里，表格往往宽而大：几千列、几万行，甚至跨多个 Sheet 与 PDF 页。要把体系跑稳，需要：

• 分段解析：先表头 N 行 + 数据区样本构建结构，再流式读全量数据；

• 缓存/指纹：对模板做“结构指纹”（节点拓扑 + 关键词哈希），命中指纹则走快速路径；

• 可观测性：每一步都打解析日志（模板指纹、规则/AI 决策、虚拟填充值统计），并产出可视化预览（HTML 高亮合并与路径列名）；

• 灰度与回滚：新规则/新模型先“影子运行”，对比旧版本输出差异，异常时可一键回滚；

• 时间/空间优化：openpyxl 读取时避免全表扫描；对 PDF 用坐标裁剪只抓表头区域；中间态结构尽量不可变（便于并发与缓存）。

---

12. 对比与扩展：纯规则 vs 纯 OCR/LLM vs 混合方案

• 纯规则：对固定模板很稳、性能好；一旦模板漂移或出现“人类创新合并法”，就容易挂。

• 纯 OCR/LLM：对“半结构化”的弹性强，但容易“想象力过剩”，在对齐与口径上不透明，难以审计与复现。

• 混合方案（本文）：结构硬约束交给规则（坐标、跨度、网格），语义软判断交给 AI（归一、口径、模糊继承），两者组合在企业场景里更可控、更可治理。

进一步的扩展方向包括：

• 版面理解（Layout）模型：用细粒度视觉块替代“文本相等合并”；

• 单位/期间的全局约束求解：把单位换算、期间闭包做成一个约束求解器（SAT/ILP）；

• 模板市场：将“结构指纹 + 归一映射”沉淀成可复用模板，降低上线成本。

---

13. 示意图

---

14. 实战整合示例（从文件到 DataFrame 的“一条龙”）

把上面的片段串起来，走一个完整 Demo（伪造 raw_values 作为数据区）：

# coding: utf-8
from typing import Any, Dict, List

def parse_excel_to_dataframe(xlsx_path: str, sheet: str = None, header_rows: int = 4) -> Dict[str, Any]:
    """
    端到端演示：Excel -> 合并补全 -> 表头树 -> 叶子路径 -> 语义归一 -> MultiIndex DataFrame
    """
    # 1) 读取与补全
    pack = read_ws_with_merged_fills(xlsx_path, sheet=sheet, header_rows=header_rows)
    grid = pack["grid"]  # 前 header_rows 行
    # 2) 表头节点与跨度合并
    nodes = build_header_nodes(grid, header_rows=header_rows)
    assign_spans(nodes)
    # 3) 树构建与叶子路径
    roots = build_tree(nodes)
    paths = []
    for r in roots:
        paths.extend(leaf_paths(r, []))
    # 4) 归一
    items = normalize_paths(paths)  # [{"normalized":..., "unit":..., "period":..., "columns":(c1,c2)}]
    # 5) 构造数据区（演示：假定 head 之后 10 行数据）
    data_rows = []
    max_col = pack["max_col"]
    for r in range(header_rows, header_rows + 10):
        row = []
        for c in range(max_col):
            row.append(f"V{r+1},{c+1}")  # 示例值
        data_rows.append(row)
    # 6) 产出 DataFrame（层级 & 扁平）
    df_multi, df_flat = construct_dataframe(items, data_rows)
    return {"df_multi": df_multi, "df_flat": df_flat, "items": items, "preview_grid": grid}

# 用法：
# result = parse_excel_to_dataframe("sample.xlsx", sheet="Sheet1", header_rows=4)
# print(result["df_multi"].head())
# print(result["df_flat"].head())

工程要点

• 在你的项目中，把第 5 步替换成真实的数据区抽取（定位首行数据与数据结束行的逻辑）。

• 若来自 PDF，请先用 camelot/pdfplumber 产出网格；注意“跨页表头复用”的对齐策略。

• 全流程需配合日志 + HTML 可视化，确保每一步能肉眼复查。

---

15. 实战细节清单（落地复盘）

1）边界处理：

• 空行/空列裁剪；全空白列不进入树；

• 只有单位/期间的行可“提升”为表头属性，不参与路径拼接；

• 发现重复列名（路径相同）时，追加“来源标记”或做列合并策略。

2）口径治理：

• 单位换算（元/千元/万元）统一到内部计量单位；

• 期间落点统一（2025-07，Q3-2025，本期=当前月份），并写入元数据；

• 指标口径冲突（amount_current vs amount_ytd）在同一路径下严禁并存。

3）可测性：

• 基于模板指纹构造回归样本集，每次规则/模型变更都跑回归；

• Diff 报告：列名变更、列数变化、单位/期间变化、空值率变化；

• 可回放：同一输入在任何时间、任何环境都产出同样的结构。

---

16. 背景–原理–实践–总结（主线回顾）

• 背景：企业报表层级复杂、合并多样，模板漂移导致解析不稳；

• 原理：把表头建模为树，用跨度覆盖确定父子关系，用路径确定列名；

• 实践：以 openpyxl/pandas 为基座，做逻辑补全、树构建、语义归一、MultiIndex 落地，并输出给核对/对账/可视化；

• 对比：纯规则稳但脆、纯 LLM 弹但飘，混合方案在可控成本内达到稳态输出；

• 代码：四段 30+ 行的参考实现，覆盖从 Excel 到 DataFrame 的关键环节。

---

17. 你可以直接复用的“落地策略模板”

• 结构先行：任何时候先拿到表头树与叶子路径，再谈语义。

• 属性外置：单位/期间等作为列属性或 DataFrame 元数据而非列名文本的一部分。

• 兜底可审计：每个“虚拟补全”“AI 判定”都打标记，能事后解释“为什么”。

• 模板指纹：上线前把主要模板固化为“指纹 + 归一映射”，降低上线摩擦。

• 灰度/回归：每次迭代都能影子运行与回归对比，出问题能回滚。

---

18. 总结与展望：从“可解析”到“可治理”的一小步

我们常以为“把表读进来”就万事大吉，但在企业自动化里，解析只是起点。真正的目标是：结构可解释、语义可治理、口径可复用、异常可追责。本文用树结构 + 逻辑补全 + 规则/AI 混合范式，把看似“艺术化”的合并表头，拉回到工程秩序里。